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