1 /* 2 * Copyright (C) 2018 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 #ifndef LOGICAL_PARTITION_METADATA_FORMAT_H_ 18 #define LOGICAL_PARTITION_METADATA_FORMAT_H_ 19 20 #ifdef __cplusplus 21 #include <string> 22 #include <vector> 23 #endif 24 25 #include <stdint.h> 26 27 #ifdef __cplusplus 28 extern "C" { 29 #endif 30 31 /* Magic signature for LpMetadataGeometry. */ 32 #define LP_METADATA_GEOMETRY_MAGIC 0x616c4467 33 34 /* Space reserved for geometry information. */ 35 #define LP_METADATA_GEOMETRY_SIZE 4096 36 37 /* Magic signature for LpMetadataHeader. */ 38 #define LP_METADATA_HEADER_MAGIC 0x414C5030 39 40 /* Current metadata version. */ 41 #define LP_METADATA_MAJOR_VERSION 10 42 #define LP_METADATA_MINOR_VERSION 0 43 44 /* Attributes for the LpMetadataPartition::attributes field. 45 * 46 * READONLY - The partition should not be considered writable. When used with 47 * device mapper, the block device will be created as read-only. 48 */ 49 #define LP_PARTITION_ATTR_NONE 0x0 50 #define LP_PARTITION_ATTR_READONLY (1 << 0) 51 52 /* This flag is only intended to be used with super_empty.img and super.img on 53 * retrofit devices. On these devices there are A and B super partitions, and 54 * we don't know ahead of time which slot the image will be applied to. 55 * 56 * If set, the partition name needs a slot suffix applied. The slot suffix is 57 * determined by the metadata slot number (0 = _a, 1 = _b). 58 */ 59 #define LP_PARTITION_ATTR_SLOT_SUFFIXED (1 << 1) 60 61 /* Mask that defines all valid attributes. */ 62 #define LP_PARTITION_ATTRIBUTE_MASK (LP_PARTITION_ATTR_READONLY | LP_PARTITION_ATTR_SLOT_SUFFIXED) 63 64 /* Default name of the physical partition that holds logical partition entries. 65 * The layout of this partition will look like: 66 * 67 * +--------------------+ 68 * | Disk Geometry | 69 * +--------------------+ 70 * | Geometry Backup | 71 * +--------------------+ 72 * | Metadata | 73 * +--------------------+ 74 * | Backup Metadata | 75 * +--------------------+ 76 * | Logical Partitions | 77 * +--------------------+ 78 */ 79 #define LP_METADATA_DEFAULT_PARTITION_NAME "super" 80 81 /* Size of a sector is always 512 bytes for compatibility with the Linux kernel. */ 82 #define LP_SECTOR_SIZE 512 83 84 /* Amount of space reserved at the start of every super partition to avoid 85 * creating an accidental boot sector. 86 */ 87 #define LP_PARTITION_RESERVED_BYTES 4096 88 89 /* This structure is stored at block 0 in the first 4096 bytes of the 90 * partition, and again in the following block. It is never modified and 91 * describes how logical partition information can be located. 92 */ 93 typedef struct LpMetadataGeometry { 94 /* 0: Magic signature (LP_METADATA_GEOMETRY_MAGIC). */ 95 uint32_t magic; 96 97 /* 4: Size of the LpMetadataGeometry struct. */ 98 uint32_t struct_size; 99 100 /* 8: SHA256 checksum of this struct, with this field set to 0. */ 101 uint8_t checksum[32]; 102 103 /* 40: Maximum amount of space a single copy of the metadata can use. This 104 * must be a multiple of LP_SECTOR_SIZE. 105 */ 106 uint32_t metadata_max_size; 107 108 /* 44: Number of copies of the metadata to keep. For A/B devices, this 109 * will be 2. For an A/B/C device, it would be 3, et cetera. For Non-A/B 110 * it will be 1. A backup copy of each slot is kept, so if this is "2", 111 * there will be four copies total. 112 */ 113 uint32_t metadata_slot_count; 114 115 /* 48: Logical block size. This is the minimal alignment for partition and 116 * extent sizes, and it must be a multiple of LP_SECTOR_SIZE. Note that 117 * this must be equal across all LUNs that comprise the super partition, 118 * and thus this field is stored in the geometry, not per-device. 119 */ 120 uint32_t logical_block_size; 121 } __attribute__((packed)) LpMetadataGeometry; 122 123 /* The logical partition metadata has a number of tables; they are described 124 * in the header via the following structure. 125 * 126 * The size of the table can be computed by multiplying entry_size by 127 * num_entries, and the result must not overflow a 32-bit signed integer. 128 */ 129 typedef struct LpMetadataTableDescriptor { 130 /* 0: Location of the table, relative to end of the metadata header. */ 131 uint32_t offset; 132 /* 4: Number of entries in the table. */ 133 uint32_t num_entries; 134 /* 8: Size of each entry in the table, in bytes. */ 135 uint32_t entry_size; 136 } __attribute__((packed)) LpMetadataTableDescriptor; 137 138 /* Binary format for the header of the logical partition metadata format. 139 * 140 * The format has three sections. The header must occur first, and the 141 * proceeding tables may be placed in any order after. 142 * 143 * +-----------------------------------------+ 144 * | Header data - fixed size | 145 * +-----------------------------------------+ 146 * | Partition table - variable size | 147 * +-----------------------------------------+ 148 * | Partition table extents - variable size | 149 * +-----------------------------------------+ 150 * 151 * The "Header" portion is described by LpMetadataHeader. It will always 152 * precede the other three blocks. 153 * 154 * All fields are stored in little-endian byte order when serialized. 155 * 156 * This struct is versioned; see the |major_version| and |minor_version| 157 * fields. 158 */ 159 typedef struct LpMetadataHeader { 160 /* 0: Four bytes equal to LP_METADATA_HEADER_MAGIC. */ 161 uint32_t magic; 162 163 /* 4: Version number required to read this metadata. If the version is not 164 * equal to the library version, the metadata should be considered 165 * incompatible. 166 */ 167 uint16_t major_version; 168 169 /* 6: Minor version. A library supporting newer features should be able to 170 * read metadata with an older minor version. However, an older library 171 * should not support reading metadata if its minor version is higher. 172 */ 173 uint16_t minor_version; 174 175 /* 8: The size of this header struct. */ 176 uint32_t header_size; 177 178 /* 12: SHA256 checksum of the header, up to |header_size| bytes, computed as 179 * if this field were set to 0. 180 */ 181 uint8_t header_checksum[32]; 182 183 /* 44: The total size of all tables. This size is contiguous; tables may not 184 * have gaps in between, and they immediately follow the header. 185 */ 186 uint32_t tables_size; 187 188 /* 48: SHA256 checksum of all table contents. */ 189 uint8_t tables_checksum[32]; 190 191 /* 80: Partition table descriptor. */ 192 LpMetadataTableDescriptor partitions; 193 /* 92: Extent table descriptor. */ 194 LpMetadataTableDescriptor extents; 195 /* 104: Updateable group descriptor. */ 196 LpMetadataTableDescriptor groups; 197 /* 116: Block device table. */ 198 LpMetadataTableDescriptor block_devices; 199 } __attribute__((packed)) LpMetadataHeader; 200 201 /* This struct defines a logical partition entry, similar to what would be 202 * present in a GUID Partition Table. 203 */ 204 typedef struct LpMetadataPartition { 205 /* 0: Name of this partition in ASCII characters. Any unused characters in 206 * the buffer must be set to 0. Characters may only be alphanumeric or _. 207 * The name must include at least one ASCII character, and it must be unique 208 * across all partition names. The length (36) is the same as the maximum 209 * length of a GPT partition name. 210 */ 211 char name[36]; 212 213 /* 36: Attributes for the partition (see LP_PARTITION_ATTR_* flags above). */ 214 uint32_t attributes; 215 216 /* 40: Index of the first extent owned by this partition. The extent will 217 * start at logical sector 0. Gaps between extents are not allowed. 218 */ 219 uint32_t first_extent_index; 220 221 /* 44: Number of extents in the partition. Every partition must have at 222 * least one extent. 223 */ 224 uint32_t num_extents; 225 226 /* 48: Group this partition belongs to. */ 227 uint32_t group_index; 228 } __attribute__((packed)) LpMetadataPartition; 229 230 /* This extent is a dm-linear target, and the index is an index into the 231 * LinearExtent table. 232 */ 233 #define LP_TARGET_TYPE_LINEAR 0 234 235 /* This extent is a dm-zero target. The index is ignored and must be 0. */ 236 #define LP_TARGET_TYPE_ZERO 1 237 238 /* This struct defines an extent entry in the extent table block. */ 239 typedef struct LpMetadataExtent { 240 /* 0: Length of this extent, in 512-byte sectors. */ 241 uint64_t num_sectors; 242 243 /* 8: Target type for device-mapper (see LP_TARGET_TYPE_* values). */ 244 uint32_t target_type; 245 246 /* 12: Contents depends on target_type. 247 * 248 * LINEAR: The sector on the physical partition that this extent maps onto. 249 * ZERO: This field must be 0. 250 */ 251 uint64_t target_data; 252 253 /* 20: Contents depends on target_type. 254 * 255 * LINEAR: Must be an index into the block devices table. 256 * ZERO: This field must be 0. 257 */ 258 uint32_t target_source; 259 } __attribute__((packed)) LpMetadataExtent; 260 261 /* This struct defines an entry in the groups table. Each group has a maximum 262 * size, and partitions in a group must not exceed that size. There is always 263 * a "default" group of unlimited size, which is used when not using update 264 * groups or when using overlayfs or fastbootd. 265 */ 266 typedef struct LpMetadataPartitionGroup { 267 /* 0: Name of this group. Any unused characters must be 0. */ 268 char name[36]; 269 270 /* 36: Flags (see LP_GROUP_*). */ 271 uint32_t flags; 272 273 /* 40: Maximum size in bytes. If 0, the group has no maximum size. */ 274 uint64_t maximum_size; 275 } __attribute__((packed)) LpMetadataPartitionGroup; 276 277 /* This flag is only intended to be used with super_empty.img and super.img on 278 * retrofit devices. If set, the group needs a slot suffix to be interpreted 279 * correctly. The suffix is automatically applied by ReadMetadata(). 280 */ 281 #define LP_GROUP_SLOT_SUFFIXED (1 << 0) 282 283 /* This struct defines an entry in the block_devices table. There must be at 284 * least one device, and the first device must represent the partition holding 285 * the super metadata. 286 */ 287 typedef struct LpMetadataBlockDevice { 288 /* 0: First usable sector for allocating logical partitions. this will be 289 * the first sector after the initial geometry blocks, followed by the 290 * space consumed by metadata_max_size*metadata_slot_count*2. 291 */ 292 uint64_t first_logical_sector; 293 294 /* 8: Alignment for defining partitions or partition extents. For example, 295 * an alignment of 1MiB will require that all partitions have a size evenly 296 * divisible by 1MiB, and that the smallest unit the partition can grow by 297 * is 1MiB. 298 * 299 * Alignment is normally determined at runtime when growing or adding 300 * partitions. If for some reason the alignment cannot be determined, then 301 * this predefined alignment in the geometry is used instead. By default 302 * it is set to 1MiB. 303 */ 304 uint32_t alignment; 305 306 /* 12: Alignment offset for "stacked" devices. For example, if the "super" 307 * partition itself is not aligned within the parent block device's 308 * partition table, then we adjust for this in deciding where to place 309 * |first_logical_sector|. 310 * 311 * Similar to |alignment|, this will be derived from the operating system. 312 * If it cannot be determined, it is assumed to be 0. 313 */ 314 uint32_t alignment_offset; 315 316 /* 16: Block device size, as specified when the metadata was created. This 317 * can be used to verify the geometry against a target device. 318 */ 319 uint64_t size; 320 321 /* 24: Partition name in the GPT. Any unused characters must be 0. */ 322 char partition_name[36]; 323 324 /* 60: Flags (see LP_BLOCK_DEVICE_* flags below). */ 325 uint32_t flags; 326 } __attribute__((packed)) LpMetadataBlockDevice; 327 328 /* This flag is only intended to be used with super_empty.img and super.img on 329 * retrofit devices. On these devices there are A and B super partitions, and 330 * we don't know ahead of time which slot the image will be applied to. 331 * 332 * If set, the block device needs a slot suffix applied before being used with 333 * IPartitionOpener. The slot suffix is determined by the metadata slot number 334 * (0 = _a, 1 = _b). 335 */ 336 #define LP_BLOCK_DEVICE_SLOT_SUFFIXED (1 << 0) 337 338 #ifdef __cplusplus 339 } /* extern "C" */ 340 #endif 341 342 #endif /* LOGICAL_PARTITION_METADATA_FORMAT_H_ */ 343