| // Copyright 2023 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| /// This library contains the definitions for the Zircon Boot Image (ZBI) format. |
| /// |
| /// A Zircon Boot Image consists of a container header followed by boot items. |
| /// Each boot item has a header (zbi_header_t) and then a payload of |
| /// `zbi_header_t.length bytes`, which can be any size. `The zbi_header_t.type` |
| /// field indicates how to interpret the payload. Many types specify an additional |
| /// type-specific header that begins a variable-sized payload. |
| /// `zbi_header_t.length` does not include the `zbi_header_t` itself, but does |
| /// include any type-specific headers as part of the payload. All fields in all |
| /// header formats are little-endian. |
| /// |
| /// Padding bytes appear after each item as needed to align the payload size up to |
| /// a `ZBI_ALIGNMENT` (8-byte) boundary. This padding is not reflected in the |
| /// `zbi_header_t.length` value. |
| /// |
| /// A bootable ZBI can be booted by a Zircon-compatible boot loader. It contains one |
| /// `ZBI_TYPE_KERNEL_{ARCH}` boot item that must come first, followed by any number |
| /// of additional boot items whose number, types, and details much comport with that |
| /// kernel's expectations. |
| /// |
| /// A partial ZBI cannot be booted, and is only used during the build process. It |
| /// contains one or more boot items and can be combined with a kernel and other |
| /// ZBIs to make a bootable ZBI. |
| /// |
| /// ZBI_TYPE_STORAGE_* types represent an image that might otherwise appear on some |
| /// block storage device, i.e. a RAM disk of some sort. All zbi_header_t fields |
| /// have the same meanings for all these types. The interpretation of the payload |
| /// (after possible decompression) is indicated by the specific `zbi_header_t.type` |
| /// value. |
| /// |
| /// **Note:** The ZBI_TYPE_STORAGE_* types are not a long-term stable ABI. |
| /// - Items of these types are always packed for a specific version of the |
| /// kernel and userland boot services, often in the same build that compiles |
| /// the kernel. |
| /// - These item types are **not** expected to be synthesized or |
| /// examined by boot loaders. |
| /// - New versions of the `zbi` tool will usually retain the ability to |
| /// read old formats and non-default switches to write old formats, for |
| /// diagnostic use. |
| /// |
| /// ## Maintenance & Evolution |
| /// |
| /// ### ABI Stability |
| /// |
| /// The ZBI definitions form the contract between a bootloader and the kernel so |
| /// must remain ABI backwards-compatible. Failure to do so would result in undefined |
| /// behavior when devices update their kernel to the new ABI but their bootloader |
| /// still uses the old ABI (or vice-versa). |
| /// |
| /// It is generally infeasible to update all bootloaders and kernels to a new ABI in |
| /// lockstep, not only due to the proliferation of boards running Fuchsia, but also |
| /// because many boards do not support firmware A/B/R without which it is impossible |
| /// to guarantee atomic updates to both the bootloader and kernel. |
| /// |
| /// ### API Stability |
| /// |
| /// API stability is not required. These definitions are not exported to Fuchsia |
| /// application developers so will not break any out-of-tree builds if e.g. a |
| /// constant name is updated. |
| /// |
| /// They are exported in the Firmware SDK for firmware developers, but firmware |
| /// does not expect to automatically roll new SDK builds; any uprev to a new SDK |
| /// is an intentional action that expects some porting work. |
| library zbi; |