1 /*
2  * Copyright (C) 2019 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 /* This .h file is intended for C clients (usually bootloader).  */
18 
19 #pragma once
20 
21 #include <stdint.h>
22 
23 /* Magic signature for super vbmeta. */
24 #define SUPER_VBMETA_MAGIC 0x5356424d
25 
26 /* Current super vbmeta version. */
27 #define SUPER_VBMETA_MAJOR_VERSION 1
28 #define SUPER_VBMETA_MINOR_VERSION 0
29 
30 /* super vbmeta size. */
31 #define SUPER_VBMETA_HEADER_SIZE sizeof(SuperVBMetaHeader)
32 #define SUPER_VBMETA_DESCRIPTOR_SIZE sizeof(VBMetaDescriptor)
33 #define SUPER_VBMETA_TABLE_MAX_SIZE 2048
34 
35 /* super vbmeta offset. */
36 #define PRIMARY_SUPER_VBMETA_TABLE_OFFSET 0
37 #define BACKUP_SUPER_VBMETA_TABLE_OFFSET SUPER_VBMETA_TABLE_MAX_SIZE
38 
39 /* restriction of vbmeta image */
40 #define VBMETA_IMAGE_MAX_NUM 32
41 #define VBMETA_IMAGE_MAX_SIZE 64 * 1024
42 
43 /* Binary format of the super vbmeta image.
44  *
45  * The super vbmeta image consists of two blocks:
46  *
47  *  +------------------------------------------+
48  *  | Super VBMeta Table - fixed size          |
49  *  +------------------------------------------+
50  *  | Backup Super VBMeta Table - fixed size   |
51  *  +------------------------------------------+
52  *  | VBMeta Images - fixed size               |
53  *  +------------------------------------------+
54  *
55  *  The "Super VBMeta Table" records the offset
56  *  and the size of each vbmeta_partition within
57  *  /super_vbmeta.
58  *
59  *  The "VBMeta Image" is copied from each vbmeta_partition
60  *  and filled with 0 until 64K bytes.
61  *
62  * The super vbmeta table consists of two blocks:
63  *
64  *  +-----------------------------------------+
65  *  | Header data - fixed size                |
66  *  +-----------------------------------------+
67  *  | VBMeta descriptors - variable size      |
68  *  +-----------------------------------------+
69  *
70  * The "Header data" block is described by the following struct and
71  * is always 128 bytes long.
72  *
73  * The "VBMeta descriptor" is |descriptors_size| + |vbmeta_name_length|
74  * bytes long. It contains the offset and size for each vbmeta image
75  * and is followed by |vbmeta_name_length| bytes of the partition name
76  * (UTF-8 encoded).
77  */
78 
79 typedef struct SuperVBMetaHeader {
80     /*  0: Magic signature (SUPER_VBMETA_MAGIC). */
81     uint32_t magic;
82 
83     /*  4: Major version. Version number required to read this super vbmeta. If the version is not
84      * equal to the library version, the super vbmeta should be considered incompatible.
85      */
86     uint16_t major_version;
87 
88     /*  6: Minor version. A library supporting newer features should be able to
89      * read super vbmeta with an older minor version. However, an older library
90      * should not support reading super vbmeta if its minor version is higher.
91      */
92     uint16_t minor_version;
93 
94     /*  8: The size of this header struct. */
95     uint32_t header_size;
96 
97     /*  12: The size of this super vbmeta table. */
98     uint32_t total_size;
99 
100     /*  16: SHA256 checksum of this super vbmeta table, with this field set to 0. */
101     uint8_t checksum[32];
102 
103     /*  48: The size of the vbmeta table descriptors. */
104     uint32_t descriptors_size;
105 
106     /*  52: mark which slot is in use. */
107     uint32_t in_use = 0;
108 
109     /*  56: reserved for other usage, filled with 0. */
110     uint8_t reserved[72];
111 } __attribute__((packed)) SuperVBMetaHeader;
112 
113 typedef struct VBMetaDescriptor {
114     /*  0: The slot number of the vbmeta image. */
115     uint8_t vbmeta_index;
116 
117     /*  12: The length of the vbmeta image name. */
118     uint32_t vbmeta_name_length;
119 
120     /*  16: Space reserved for other usage, filled with 0. */
121     uint8_t reserved[48];
122 } __attribute__((packed)) VBMetaDescriptor;