1 /* 2 * Copyright (C) 2007 The Android Open Source Project 3 * 4 * Redistribution and use in source and binary forms, with or without modification, 5 * are permitted provided that the following conditions are met: 6 * 7 * 1. Redistributions of source code must retain the above copyright notice, this 8 * list of conditions and the following disclaimer. 9 * 10 * 2. Redistributions in binary form must reproduce the above copyright notice, 11 * this list of conditions and the following disclaimer in the documentation 12 * and/or other materials provided with the distribution. 13 * 14 * 3. Neither the name of the copyright holder nor the names of its contributors 15 * may be used to endorse or promote products derived from this software without 16 * specific prior written permission. 17 * 18 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 19 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 20 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 21 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR 22 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 23 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 24 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 25 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 27 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28 */ 29 30 #pragma once 31 32 #include <stdint.h> 33 34 #define BOOT_MAGIC "ANDROID!" 35 #define BOOT_MAGIC_SIZE 8 36 #define BOOT_NAME_SIZE 16 37 #define BOOT_ARGS_SIZE 512 38 #define BOOT_EXTRA_ARGS_SIZE 1024 39 40 #define VENDOR_BOOT_MAGIC "VNDRBOOT" 41 #define VENDOR_BOOT_MAGIC_SIZE 8 42 #define VENDOR_BOOT_ARGS_SIZE 2048 43 #define VENDOR_BOOT_NAME_SIZE 16 44 45 #define VENDOR_RAMDISK_TYPE_NONE 0 46 #define VENDOR_RAMDISK_TYPE_PLATFORM 1 47 #define VENDOR_RAMDISK_TYPE_RECOVERY 2 48 #define VENDOR_RAMDISK_TYPE_DLKM 3 49 #define VENDOR_RAMDISK_NAME_SIZE 32 50 #define VENDOR_RAMDISK_TABLE_ENTRY_BOARD_ID_SIZE 16 51 52 /* When a boot header is of version 0, the structure of boot image is as 53 * follows: 54 * 55 * +-----------------+ 56 * | boot header | 1 page 57 * +-----------------+ 58 * | kernel | n pages 59 * +-----------------+ 60 * | ramdisk | m pages 61 * +-----------------+ 62 * | second stage | o pages 63 * +-----------------+ 64 * 65 * n = (kernel_size + page_size - 1) / page_size 66 * m = (ramdisk_size + page_size - 1) / page_size 67 * o = (second_size + page_size - 1) / page_size 68 * 69 * 0. all entities are page_size aligned in flash 70 * 1. kernel and ramdisk are required (size != 0) 71 * 2. second is optional (second_size == 0 -> no second) 72 * 3. load each element (kernel, ramdisk, second) at 73 * the specified physical address (kernel_addr, etc) 74 * 4. prepare tags at tag_addr. kernel_args[] is 75 * appended to the kernel commandline in the tags. 76 * 5. r0 = 0, r1 = MACHINE_TYPE, r2 = tags_addr 77 * 6. if second_size != 0: jump to second_addr 78 * else: jump to kernel_addr 79 */ 80 struct boot_img_hdr_v0 { 81 // Must be BOOT_MAGIC. 82 uint8_t magic[BOOT_MAGIC_SIZE]; 83 84 uint32_t kernel_size; /* size in bytes */ 85 uint32_t kernel_addr; /* physical load addr */ 86 87 uint32_t ramdisk_size; /* size in bytes */ 88 uint32_t ramdisk_addr; /* physical load addr */ 89 90 uint32_t second_size; /* size in bytes */ 91 uint32_t second_addr; /* physical load addr */ 92 93 uint32_t tags_addr; /* physical addr for kernel tags (if required) */ 94 uint32_t page_size; /* flash page size we assume */ 95 96 // Version of the boot image header. 97 uint32_t header_version; 98 99 // Operating system version and security patch level. 100 // For version "A.B.C" and patch level "Y-M-D": 101 // (7 bits for each of A, B, C; 7 bits for (Y-2000), 4 bits for M) 102 // os_version = A[31:25] B[24:18] C[17:11] (Y-2000)[10:4] M[3:0] 103 uint32_t os_version; 104 105 #if __cplusplus SetOsVersionboot_img_hdr_v0106 void SetOsVersion(unsigned major, unsigned minor, unsigned patch) { 107 os_version &= ((1 << 11) - 1); 108 os_version |= (((major & 0x7f) << 25) | ((minor & 0x7f) << 18) | ((patch & 0x7f) << 11)); 109 } 110 SetOsPatchLevelboot_img_hdr_v0111 void SetOsPatchLevel(unsigned year, unsigned month) { 112 os_version &= ~((1 << 11) - 1); 113 os_version |= (((year - 2000) & 0x7f) << 4) | ((month & 0xf) << 0); 114 } 115 #endif 116 117 uint8_t name[BOOT_NAME_SIZE]; /* asciiz product name */ 118 119 uint8_t cmdline[BOOT_ARGS_SIZE]; /* asciiz kernel commandline */ 120 121 uint32_t id[8]; /* timestamp / checksum / sha1 / etc */ 122 123 // Supplemental command line data; kept here to maintain 124 // binary compatibility with older versions of mkbootimg. 125 // Asciiz. 126 uint8_t extra_cmdline[BOOT_EXTRA_ARGS_SIZE]; 127 } __attribute__((packed)); 128 129 /* 130 * It is expected that callers would explicitly specify which version of the 131 * boot image header they need to use. 132 */ 133 typedef struct boot_img_hdr_v0 boot_img_hdr; 134 135 /* When a boot header is of version 1, the structure of boot image is as 136 * follows: 137 * 138 * +---------------------+ 139 * | boot header | 1 page 140 * +---------------------+ 141 * | kernel | n pages 142 * +---------------------+ 143 * | ramdisk | m pages 144 * +---------------------+ 145 * | second stage | o pages 146 * +---------------------+ 147 * | recovery dtbo/acpio | p pages 148 * +---------------------+ 149 * 150 * n = (kernel_size + page_size - 1) / page_size 151 * m = (ramdisk_size + page_size - 1) / page_size 152 * o = (second_size + page_size - 1) / page_size 153 * p = (recovery_dtbo_size + page_size - 1) / page_size 154 * 155 * 0. all entities are page_size aligned in flash 156 * 1. kernel and ramdisk are required (size != 0) 157 * 2. recovery_dtbo/recovery_acpio is required for recovery.img in non-A/B 158 * devices(recovery_dtbo_size != 0) 159 * 3. second is optional (second_size == 0 -> no second) 160 * 4. load each element (kernel, ramdisk, second) at 161 * the specified physical address (kernel_addr, etc) 162 * 5. If booting to recovery mode in a non-A/B device, extract recovery 163 * dtbo/acpio and apply the correct set of overlays on the base device tree 164 * depending on the hardware/product revision. 165 * 6. set up registers for kernel entry as required by your architecture 166 * 7. if second_size != 0: jump to second_addr 167 * else: jump to kernel_addr 168 */ 169 struct boot_img_hdr_v1 : public boot_img_hdr_v0 { 170 uint32_t recovery_dtbo_size; /* size in bytes for recovery DTBO/ACPIO image */ 171 uint64_t recovery_dtbo_offset; /* offset to recovery dtbo/acpio in boot image */ 172 uint32_t header_size; 173 } __attribute__((packed)); 174 175 /* When the boot image header has a version of 2, the structure of the boot 176 * image is as follows: 177 * 178 * +---------------------+ 179 * | boot header | 1 page 180 * +---------------------+ 181 * | kernel | n pages 182 * +---------------------+ 183 * | ramdisk | m pages 184 * +---------------------+ 185 * | second stage | o pages 186 * +---------------------+ 187 * | recovery dtbo/acpio | p pages 188 * +---------------------+ 189 * | dtb | q pages 190 * +---------------------+ 191 192 * n = (kernel_size + page_size - 1) / page_size 193 * m = (ramdisk_size + page_size - 1) / page_size 194 * o = (second_size + page_size - 1) / page_size 195 * p = (recovery_dtbo_size + page_size - 1) / page_size 196 * q = (dtb_size + page_size - 1) / page_size 197 * 198 * 0. all entities are page_size aligned in flash 199 * 1. kernel, ramdisk and DTB are required (size != 0) 200 * 2. recovery_dtbo/recovery_acpio is required for recovery.img in non-A/B 201 * devices(recovery_dtbo_size != 0) 202 * 3. second is optional (second_size == 0 -> no second) 203 * 4. load each element (kernel, ramdisk, second, dtb) at 204 * the specified physical address (kernel_addr, etc) 205 * 5. If booting to recovery mode in a non-A/B device, extract recovery 206 * dtbo/acpio and apply the correct set of overlays on the base device tree 207 * depending on the hardware/product revision. 208 * 6. set up registers for kernel entry as required by your architecture 209 * 7. if second_size != 0: jump to second_addr 210 * else: jump to kernel_addr 211 */ 212 struct boot_img_hdr_v2 : public boot_img_hdr_v1 { 213 uint32_t dtb_size; /* size in bytes for DTB image */ 214 uint64_t dtb_addr; /* physical load address for DTB image */ 215 } __attribute__((packed)); 216 217 218 /* When the boot image header has a version of 3, the structure of the boot 219 * image is as follows: 220 * 221 * +---------------------+ 222 * | boot header | 4096 bytes 223 * +---------------------+ 224 * | kernel | m pages 225 * +---------------------+ 226 * | ramdisk | n pages 227 * +---------------------+ 228 * 229 * m = (kernel_size + 4096 - 1) / 4096 230 * n = (ramdisk_size + 4096 - 1) / 4096 231 * 232 * Note that in version 3 of the boot image header, page size is fixed at 4096 bytes. 233 * 234 * The structure of the vendor boot image (introduced with version 3 and 235 * required to be present when a v3 boot image is used) is as follows: 236 * 237 * +---------------------+ 238 * | vendor boot header | o pages 239 * +---------------------+ 240 * | vendor ramdisk | p pages 241 * +---------------------+ 242 * | dtb | q pages 243 * +---------------------+ 244 245 * o = (2112 + page_size - 1) / page_size 246 * p = (vendor_ramdisk_size + page_size - 1) / page_size 247 * q = (dtb_size + page_size - 1) / page_size 248 * 249 * 0. all entities in the boot image are 4096-byte aligned in flash, all 250 * entities in the vendor boot image are page_size (determined by the vendor 251 * and specified in the vendor boot image header) aligned in flash 252 * 1. kernel, ramdisk, vendor ramdisk, and DTB are required (size != 0) 253 * 2. load the kernel and DTB at the specified physical address (kernel_addr, 254 * dtb_addr) 255 * 3. load the vendor ramdisk at ramdisk_addr 256 * 4. load the generic ramdisk immediately following the vendor ramdisk in 257 * memory 258 * 5. set up registers for kernel entry as required by your architecture 259 * 6. if the platform has a second stage bootloader jump to it (must be 260 * contained outside boot and vendor boot partitions), otherwise 261 * jump to kernel_addr 262 */ 263 struct boot_img_hdr_v3 { 264 // Must be BOOT_MAGIC. 265 uint8_t magic[BOOT_MAGIC_SIZE]; 266 267 uint32_t kernel_size; /* size in bytes */ 268 uint32_t ramdisk_size; /* size in bytes */ 269 270 // Operating system version and security patch level. 271 // For version "A.B.C" and patch level "Y-M-D": 272 // (7 bits for each of A, B, C; 7 bits for (Y-2000), 4 bits for M) 273 // os_version = A[31:25] B[24:18] C[17:11] (Y-2000)[10:4] M[3:0] 274 uint32_t os_version; 275 276 #if __cplusplus SetOsVersionboot_img_hdr_v3277 void SetOsVersion(unsigned major, unsigned minor, unsigned patch) { 278 os_version &= ((1 << 11) - 1); 279 os_version |= (((major & 0x7f) << 25) | ((minor & 0x7f) << 18) | ((patch & 0x7f) << 11)); 280 } 281 SetOsPatchLevelboot_img_hdr_v3282 void SetOsPatchLevel(unsigned year, unsigned month) { 283 os_version &= ~((1 << 11) - 1); 284 os_version |= (((year - 2000) & 0x7f) << 4) | ((month & 0xf) << 0); 285 } 286 #endif 287 288 uint32_t header_size; 289 290 uint32_t reserved[4]; 291 292 // Version of the boot image header. 293 uint32_t header_version; 294 295 // Asciiz kernel commandline. 296 uint8_t cmdline[BOOT_ARGS_SIZE + BOOT_EXTRA_ARGS_SIZE]; 297 } __attribute__((packed)); 298 299 struct vendor_boot_img_hdr_v3 { 300 // Must be VENDOR_BOOT_MAGIC. 301 uint8_t magic[VENDOR_BOOT_MAGIC_SIZE]; 302 303 // Version of the vendor boot image header. 304 uint32_t header_version; 305 306 uint32_t page_size; /* flash page size we assume */ 307 308 uint32_t kernel_addr; /* physical load addr */ 309 uint32_t ramdisk_addr; /* physical load addr */ 310 311 uint32_t vendor_ramdisk_size; /* size in bytes */ 312 313 uint8_t cmdline[VENDOR_BOOT_ARGS_SIZE]; /* asciiz kernel commandline */ 314 315 uint32_t tags_addr; /* physical addr for kernel tags (if required) */ 316 uint8_t name[VENDOR_BOOT_NAME_SIZE]; /* asciiz product name */ 317 318 uint32_t header_size; 319 320 uint32_t dtb_size; /* size in bytes for DTB image */ 321 uint64_t dtb_addr; /* physical load address for DTB image */ 322 } __attribute__((packed)); 323 324 /* When the boot image header has a version of 4, the structure of the boot 325 * image is as follows: 326 * 327 * +---------------------+ 328 * | boot header | 4096 bytes 329 * +---------------------+ 330 * | kernel | m pages 331 * +---------------------+ 332 * | ramdisk | n pages 333 * +---------------------+ 334 * | boot signature | g pages 335 * +---------------------+ 336 * 337 * m = (kernel_size + 4096 - 1) / 4096 338 * n = (ramdisk_size + 4096 - 1) / 4096 339 * g = (signature_size + 4096 - 1) / 4096 340 * 341 * Note that in version 4 of the boot image header, page size is fixed at 4096 342 * bytes. 343 * 344 * The structure of the vendor boot image version 4, which is required to be 345 * present when a version 4 boot image is used, is as follows: 346 * 347 * +------------------------+ 348 * | vendor boot header | o pages 349 * +------------------------+ 350 * | vendor ramdisk section | p pages 351 * +------------------------+ 352 * | dtb | q pages 353 * +------------------------+ 354 * | vendor ramdisk table | r pages 355 * +------------------------+ 356 * | bootconfig | s pages 357 * +------------------------+ 358 * 359 * o = (2128 + page_size - 1) / page_size 360 * p = (vendor_ramdisk_size + page_size - 1) / page_size 361 * q = (dtb_size + page_size - 1) / page_size 362 * r = (vendor_ramdisk_table_size + page_size - 1) / page_size 363 * s = (vendor_bootconfig_size + page_size - 1) / page_size 364 * 365 * Note that in version 4 of the vendor boot image, multiple vendor ramdisks can 366 * be included in the vendor boot image. The bootloader can select a subset of 367 * ramdisks to load at runtime. To help the bootloader select the ramdisks, each 368 * ramdisk is tagged with a type tag and a set of hardware identifiers 369 * describing the board, soc or platform that this ramdisk is intended for. 370 * 371 * The vendor ramdisk section is consist of multiple ramdisk images concatenated 372 * one after another, and vendor_ramdisk_size is the size of the section, which 373 * is the total size of all the ramdisks included in the vendor boot image. 374 * 375 * The vendor ramdisk table holds the size, offset, type, name and hardware 376 * identifiers of each ramdisk. The type field denotes the type of its content. 377 * The vendor ramdisk names are unique. The hardware identifiers are specified 378 * in the board_id field in each table entry. The board_id field is consist of a 379 * vector of unsigned integer words, and the encoding scheme is defined by the 380 * hardware vendor. 381 * 382 * For the different type of ramdisks, there are: 383 * - VENDOR_RAMDISK_TYPE_NONE indicates the value is unspecified. 384 * - VENDOR_RAMDISK_TYPE_PLATFORM ramdisks contain platform specific bits, so 385 * the bootloader should always load these into memory. 386 * - VENDOR_RAMDISK_TYPE_RECOVERY ramdisks contain recovery resources, so 387 * the bootloader should load these when booting into recovery. 388 * - VENDOR_RAMDISK_TYPE_DLKM ramdisks contain dynamic loadable kernel 389 * modules. 390 * 391 * Version 4 of the vendor boot image also adds a bootconfig section to the end 392 * of the image. This section contains Boot Configuration parameters known at 393 * build time. The bootloader is responsible for placing this section directly 394 * after the generic ramdisk, followed by the bootconfig trailer, before 395 * entering the kernel. 396 * 397 * 0. all entities in the boot image are 4096-byte aligned in flash, all 398 * entities in the vendor boot image are page_size (determined by the vendor 399 * and specified in the vendor boot image header) aligned in flash 400 * 1. kernel, ramdisk, and DTB are required (size != 0) 401 * 2. load the kernel and DTB at the specified physical address (kernel_addr, 402 * dtb_addr) 403 * 3. load the vendor ramdisks at ramdisk_addr 404 * 4. load the generic ramdisk immediately following the vendor ramdisk in 405 * memory 406 * 5. load the bootconfig immediately following the generic ramdisk. Add 407 * additional bootconfig parameters followed by the bootconfig trailer. 408 * 6. set up registers for kernel entry as required by your architecture 409 * 7. if the platform has a second stage bootloader jump to it (must be 410 * contained outside boot and vendor boot partitions), otherwise 411 * jump to kernel_addr 412 */ 413 struct boot_img_hdr_v4 : public boot_img_hdr_v3 { 414 uint32_t signature_size; /* size in bytes */ 415 } __attribute__((packed)); 416 417 struct vendor_boot_img_hdr_v4 : public vendor_boot_img_hdr_v3 { 418 uint32_t vendor_ramdisk_table_size; /* size in bytes for the vendor ramdisk table */ 419 uint32_t vendor_ramdisk_table_entry_num; /* number of entries in the vendor ramdisk table */ 420 uint32_t vendor_ramdisk_table_entry_size; /* size in bytes for a vendor ramdisk table entry */ 421 uint32_t bootconfig_size; /* size in bytes for the bootconfig section */ 422 } __attribute__((packed)); 423 424 struct vendor_ramdisk_table_entry_v4 { 425 uint32_t ramdisk_size; /* size in bytes for the ramdisk image */ 426 uint32_t ramdisk_offset; /* offset to the ramdisk image in vendor ramdisk section */ 427 uint32_t ramdisk_type; /* type of the ramdisk */ 428 uint8_t ramdisk_name[VENDOR_RAMDISK_NAME_SIZE]; /* asciiz ramdisk name */ 429 430 // Hardware identifiers describing the board, soc or platform which this 431 // ramdisk is intended to be loaded on. 432 uint32_t board_id[VENDOR_RAMDISK_TABLE_ENTRY_BOARD_ID_SIZE]; 433 } __attribute__((packed)); 434