| // 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. |
| |
| library zbi; |
| |
| // TODO(https://fxbug.dev/42062786): Figure out documentation convention. |
| |
| const ALIGNMENT uint32 = 8; |
| |
| /// Numeric prefix for kernel types. |
| /// |
| /// 'KRN\0' |
| const TYPE_KERNEL_PREFIX uint32 = 0x004e524b; |
| |
| /// Mask to compare against TYPE_KERNEL_PREFIX. |
| const TYPE_KERNEL_MASK uint32 = 0x00ffffff; |
| |
| /// Numeric prefix for driver metadata types. |
| /// |
| /// 'm\0\0\0' |
| const TYPE_DRIVER_METADATA_PREFIX uint32 = 0x0000006d; |
| |
| /// Mask to compare against TYPE_DRIVER_METADATA_PREFIX. |
| const TYPE_DRIVER_METADATA_MASK uint32 = 0x000000ff; |
| |
| type Type = flexible enum : uint32 { |
| |
| /// 'BOOT' |
| /// |
| /// Each ZBI starts with a container header. |
| /// length: Total size of the image after this header. |
| /// This includes all item headers, payloads, and padding. |
| /// It does not include the container header itself. |
| /// Must be a multiple of ZBI_ALIGNMENT. |
| /// extra: Must be ZBI_CONTAINER_MAGIC. |
| /// flags: Must be ZBI_FLAGS_VERSION and no other flags. |
| CONTAINER = 0x544f4f42; |
| |
| /// x86-64 kernel. See zbi_kernel_t for a payload description. |
| /// |
| /// 'KRNL' |
| KERNEL_X64 = 0x4c000000 | TYPE_KERNEL_PREFIX; |
| |
| /// ARM64 kernel. See zbi_kernel_t for a payload description. |
| /// |
| /// KRN8 |
| KERNEL_ARM64 = 0x38000000 | TYPE_KERNEL_PREFIX; |
| |
| /// RISC-V kernel. See zbi_kernel_t for a payload description. |
| /// |
| /// 'KRNV' |
| KERNEL_RISCV64 = 0x56000000 | TYPE_KERNEL_PREFIX; |
| |
| /// A discarded item that should just be ignored. This is used for an |
| /// item that was already processed and should be ignored by whatever |
| /// stage is now looking at the ZBI. An earlier stage already "consumed" |
| /// this information, but avoided copying data around to remove it from |
| /// the ZBI item stream. |
| /// |
| /// 'SKIP' |
| DISCARD = 0x50494b53; |
| |
| /// A virtual disk image. This is meant to be treated as if it were a |
| /// storage device. The payload (after decompression) is the contents of |
| /// the storage device, in whatever format that might be. |
| /// |
| /// 'RDSK' |
| STORAGE_RAMDISK = 0x4b534452; |
| |
| /// The /boot filesystem in BOOTFS format, specified in |
| /// <lib/zbi-format/internal/bootfs.h>. This represents an internal |
| /// contract between Zircon userboot (//docs/userboot.md), which handles |
| /// the contents of this filesystem, and platform tooling, which prepares |
| /// them. |
| /// |
| /// 'BFSB' |
| STORAGE_BOOTFS = 0x42534642; |
| |
| /// Storage used by the kernel (such as a compressed image containing the |
| /// actual kernel). The meaning and format of the data is specific to the |
| /// kernel, though it always uses the standard (private) storage |
| /// compression protocol. Each particular KERNEL_{ARCH} item image and its |
| /// STORAGE_KERNEL item image are intimately tied and one cannot work |
| /// without the exact correct corresponding other. |
| /// |
| /// 'KSTR' |
| STORAGE_KERNEL = 0x5254534b; |
| |
| // The remaining types are used to communicate information from the boot |
| // loader to the kernel. Usually these are synthesized in memory by the |
| // boot loader, but they can also be included in a ZBI along with the |
| // kernel and BOOTFS. Some boot loaders may set the zbi_header_t flags |
| // and crc32 fields to zero, though setting them to ZBI_FLAGS_VERSION and |
| // ZBI_ITEM_NO_CRC32 is specified. The kernel doesn't check. |
| |
| /// Device-specific factory data, stored in BOOTFS format. |
| /// |
| /// TODO(https://fxbug.dev/42109921): This should not use the "STORAGE" infix. |
| /// |
| /// 'BFSF' |
| STORAGE_BOOTFS_FACTORY = 0x46534642; |
| |
| /// A kernel command line fragment, a UTF-8 string that need not be |
| /// NUL-terminated. The kernel's own option parsing accepts only printable |
| /// 'ASCI'I and treats all other characters as equivalent to whitespace. Multiple |
| /// ZBI_TYPE_CMDLINE items can appear. They are treated as if concatenated with |
| /// ' ' between each item, in the order they appear: first items in the bootable |
| /// ZBI containing the kernel; then items in the ZBI synthesized by the boot |
| /// loader. The kernel interprets the [whole command line](../../../../docs/kernel_cmdline.md). |
| /// |
| /// 'CMDL' |
| CMDLINE = 0x4c444d43; |
| |
| /// The crash log from the previous boot, a UTF-8 string. |
| /// |
| /// 'BOOM' |
| CRASHLOG = 0x4d4f4f42; |
| |
| /// Physical memory region that will persist across warm boots. See zbi_nvram_t |
| /// for payload description. |
| /// |
| /// 'NVLL' |
| NVRAM = 0x4c4c564e; |
| |
| /// Platform ID Information. |
| /// |
| /// 'PLID' |
| PLATFORM_ID = 0x44494c50; |
| |
| /// Board-specific information. |
| /// |
| /// mBSI |
| DRV_BOARD_INFO = 0x49534200 | TYPE_DRIVER_METADATA_PREFIX; |
| |
| /// CPU configuration. See zbi_topology_node_t for a description of the payload. |
| // |
| // 'CPU3' |
| CPU_TOPOLOGY = 0x43505533; |
| |
| /// Device memory configuration. See zbi_mem_range_t for a description of the |
| /// payload. |
| /// |
| /// 'MEMC' |
| MEM_CONFIG = 0x434d454d; |
| |
| /// Kernel driver configuration. The zbi_header_t.extra field gives a |
| /// ZBI_KERNEL_DRIVER_* type that determines the payload format. |
| /// See <lib/zbi-format/driver-config.h> for details. |
| /// |
| /// 'KDRV' |
| KERNEL_DRIVER = 0x5652444b; |
| |
| /// 'ACPI' Root Table Pointer, a uint64_t physical address. |
| /// |
| /// 'RSDP' |
| ACPI_RSDP = 0x50445352; |
| |
| /// 'SMBI' |
| /// |
| /// 'SMBI'OS entry point, a uint64_t physical address. |
| SMBIOS = 0x49424d53; |
| |
| /// EFI system table, a uint64_t physical address. |
| /// |
| /// 'EFIS' |
| EFI_SYSTEM_TABLE = 0x53494645; |
| |
| /// EFI memory attributes table. An example of this format can be found in UEFI 2.10 section 4.6.4, |
| /// but the consumer of this item is responsible for interpreting whatever the bootloader supplies |
| /// (in particular the "version" field may differ as the format evolves). |
| /// |
| /// 'EMAT' |
| EFI_MEMORY_ATTRIBUTES_TABLE = 0x54414d45; |
| |
| /// Framebuffer parameters, a zbi_swfb_t entry. |
| /// |
| /// 'SWFB' |
| FRAMEBUFFER = 0x42465753; |
| |
| /// The image arguments, data is a trivial text format of one "key=value" per line |
| /// with leading whitespace stripped and "#" comment lines and blank lines ignored. |
| /// It is processed by bootsvc and parsed args are shared to others via Arguments service. |
| /// TODO: the format can be streamlined after the /config/additional_boot_args compat support is |
| /// removed. |
| /// |
| /// 'IARG' |
| IMAGE_ARGS = 0x47524149; |
| |
| /// A copy of the boot version stored within the sysconfig |
| /// partition |
| /// |
| /// 'BVRS' |
| BOOT_VERSION = 0x53525642; |
| |
| /// MAC address for Ethernet, Wifi, Bluetooth, etc. zbi_header_t.extra |
| /// is a board-specific index to specify which device the MAC address |
| /// applies to. zbi_header_t.length gives the size in bytes, which |
| /// varies depending on the type of address appropriate for the device. |
| /// |
| /// mMAC |
| DRV_MAC_ADDRESS = 0x43414d00 | TYPE_DRIVER_METADATA_PREFIX; |
| |
| /// A partition map for a storage device, a zbi_partition_map_t header |
| /// followed by one or more zbi_partition_t entries. zbi_header_t.extra |
| /// is a board-specific index to specify which device this applies to. |
| /// |
| /// mPRT |
| DRV_PARTITION_MAP = 0x54525000 | TYPE_DRIVER_METADATA_PREFIX; |
| |
| /// Private information for the board driver. |
| /// |
| /// mBOR |
| DRV_BOARD_PRIVATE = 0x524f4200 | TYPE_DRIVER_METADATA_PREFIX; |
| |
| /// 'HWRB' |
| HW_REBOOT_REASON = 0x42525748; |
| |
| /// The serial number, an unterminated ASCII string of printable non-whitespace |
| /// characters with length zbi_header_t.length. |
| /// |
| /// 'SRLN' |
| SERIAL_NUMBER = 0x4e4c5253; |
| |
| /// This type specifies a binary file passed in by the bootloader. |
| /// The first byte specifies the length of the filename without a NUL terminator. |
| /// The filename starts on the second byte. |
| /// The file contents are located immediately after the filename. |
| /// |
| /// Layout: | name_len | name | payload |
| /// ^(1 byte) ^(name_len bytes) ^(length of file) |
| /// |
| /// 'BTFL' |
| BOOTLOADER_FILE = 0x4c465442; |
| |
| /// The devicetree blob from the legacy boot loader, if any. This is used only |
| /// for diagnostic and development purposes. Zircon kernel and driver |
| /// configuration is entirely driven by specific ZBI items from the boot |
| /// loader. The boot shims for legacy boot loaders pass the raw devicetree |
| /// along for development purposes, but extract information from it to populate |
| /// specific ZBI items such as ZBI_TYPE_KERNEL_DRIVER et al. |
| DEVICETREE = 0xd00dfeed; |
| |
| /// An arbitrary number of random bytes attested to have high entropy. Any |
| /// number of items of any size can be provided, but no data should be provided |
| /// that is not true entropy of cryptographic quality. This is used to seed |
| /// secure cryptographic pseudo-random number generators. |
| /// |
| /// 'RAND' |
| SECURE_ENTROPY = 0x444e4152; |
| |
| /// This provides a data dump and associated logging from a boot loader, |
| /// shim, or earlier incarnation that wants its data percolated up by the |
| /// booting Zircon kernel. See zbi_debugdata_t for a description of the |
| /// payload. |
| /// |
| /// 'DBGD' |
| DEBUGDATA = 0x44474244; |
| |
| /// Each RISC-V hart has an associated "ISA string" encoding its supported |
| /// extensions: see Chapter 27 (ISA Extension Naming Conventions) in |
| /// https://riscv.org/wp-content/uploads/2019/12/riscv-spec-20191213.pdf. |
| /// This item gives the NUL-separated (and -terminated) concatenation of |
| /// all such strings in the system. |
| /// |
| /// The first character of the table must be NUL; that is, the first entry |
| /// in the table must be the empty and invalid, which is pointed to by a |
| /// default-constructructed index. Beyond that, there are no guarantees to |
| /// order the strings in the table or the extent of their (de)duplication. |
| /// |
| /// A given hart's index into the table is encoded within its associated |
| /// node structure in the ZBI_TYPE_CPU_TOPOLOGY item. |
| /// |
| /// 'VISA' |
| RISCV64_ISA_STRTAB = 0x41534956; |
| }; |
| |
| /// LSW of sha256("bootdata") |
| const CONTAINER_MAGIC uint32 = 0x868cf7e6; |
| |
| /// LSW of sha256("bootitem") |
| const ITEM_MAGIC uint32 = 0xb5781729; |
| |
| /// Flags associated with an item. A valid flags value must always include |
| /// ZBI_FLAGS_VERSION. Values should also contain ZBI_FLAGS_CRC32 for any item |
| /// where it's feasible to compute the CRC32 at build time. Other flags are |
| /// specific to each type. |
| type Flags = flexible bits : uint32 { |
| // 0x00000001 is reserved for internal usage. |
| |
| /// This flag is always required. |
| VERSION = 0x00010000; |
| |
| /// ZBI items with the CRC32 flag must have a valid crc32. |
| /// Otherwise their crc32 field must contain ZBI_ITEM_NO_CRC32 |
| CRC32 = 0x00020000; |
| }; |
| |
| /// Value for zbi_header_t.crc32 when ZBI_FLAGS_CRC32 is not set. |
| const ITEM_NO_CRC32 uint32 = 0x4a87e8d6; |
| |
| /// Each header must be 8-byte aligned. The length field specifies the |
| /// actual payload length and does not include the size of padding. |
| type Header = struct { |
| /// ZBI_TYPE_* constant. |
| type Type; |
| |
| /// Size of the payload immediately following this header. This |
| /// does not include the header itself nor any alignment padding |
| /// after the payload. |
| length uint32; |
| |
| /// Type-specific extra data. Each type specifies the use of this |
| /// field. When not explicitly specified, it should be zero. |
| extra uint32; |
| |
| /// Flags for this item. |
| flags Flags; |
| |
| /// For future expansion. Set to 0. |
| reserved0 uint32; |
| reserved1 uint32; |
| |
| /// Must be ZBI_ITEM_MAGIC. |
| magic uint32; |
| |
| /// Must be the CRC32 of payload if ZBI_FLAGS_CRC32 is set, |
| /// otherwise must be ZBI_ITEM_NO_CRC32. |
| crc32 uint32; |
| }; |