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