Zbi


Usage: zbi [OUTPUT...] INPUT... [-- PATTERN...]

Diagnostic switches:
    --help, -h                     print this message
    --list, -t                     list input ZBI item headers; no --output
    --verbose, -v                  show contents (e.g. BOOTFS file names)
    --extract, -x                  extract BOOTFS files
    --extract-items, -X            extract items as pseudo-files (see below)
    --extract-raw, -R              extract original payloads, not ZBI format

Output file switches:
    --output=FILE, -o FILE         output file name
    --depfile=FILE, -d FILE        makefile dependency output file name
    --output-dir=DIR, -D FILE      extracted files go under DIR (default: .)
    --json-output=FILE, -j FILE    record entries to a JSON file

The `--output` FILE is always removed and created fresh after all input
files have been opened.  So it is safe to use the same file name as an input
file and the `--output` FILE, to append more items.

Input control switches apply to subsequent input arguments:
    --directory=DIR, -C DIR        change directory to DIR
    --files, -F                    read BOOTFS manifest files (default)
    --files-type=TYPE              set the item type under which the BOOTFS
                                   will be created (default: "bootfs")
    --prefix=PREFIX, -p PREFIX     prepend PREFIX/ to target file names
    --replace, -r                  duplicate target file name OK (see below)
    --type=TYPE[:N], -T TYPE[:N]   input files are TYPE items (see below)
    --compressed[=HOW], -c [HOW]   compress storage images (see below)
    --uncompressed, -u             do not compress storage images
    --recompress                   recompress input items already compressed
    --ignore-missing-files, -i     a manifest entry whose source file doesn't
                                   exist is ignored without error

Input arguments:
    --entry=TEXT, -e TEXT          like an input file containing only TEXT
    FILE                           input or manifest file
    DIRECTORY                      directory tree copied to BOOTFS PREFIX/

The `--directory` or `-C` switch affects subsequent input arguments but
it never affects output arguments, which are always relative to the original
current working directory (`zbi` doesn't actually do `chdir()` at all).

With `--files` or `-F` (the default state), files with ZBI_TYPE_CONTAINER
headers are incomplete boot files and other files are BOOTFS manifest files.
Each DIRECTORY is listed recursively and handled just like a manifest file
using the path relative to DIRECTORY as the target name (before any PREFIX).
Each `--prefix` or `-p` switch affects each file from a manifest or
directory in subsequent FILE, DIRECTORY, or TEXT arguments.
All files are packed into a single item in BOOTFS format, regardless of
position.  The `--files-type` switch controls the type field for this item,
by default `BOOTFS`.  Any input items of that same type will be combined
along with any other files into the single output item. When extracting,
--files-type controls which item type to extract files from.

With `--type` or `-T`, input files are treated as TYPE instead of manifest
files, and directories are not permitted.  See below for the TYPE strings.
If `:N` appears after TYPE then larger input files are truncated to N bytes.
In this case, input files other than regular files are allowed: N or fewer
bytes will be read from the input device, pipe, or socket.

ZBI items from input ZBI files are normally emitted unchanged.  (However,
see below about BOOTFS items.)  With `--recompress`, input items of storage
types well be decompressed (if needed) on input and then freshly compressed
(or not) according to the preceding `--compressed=...` or `--uncompressed`.

Format control switches (last switch affects all output):
    --bootable=ARCH, -B ARCH       verify result is a bootable image
    --compressed[=HOW], -c [HOW]   compress BOOTFS images (see below)
    --uncompressed, -u             do not compress BOOTFS images

HOW defaults to `zstd` and can be one of (case-insensitive):
 * `none` (same as `--uncompressed`)
 * `LEVEL` (an integer) or `max` (default algorithm, currently `zstd`)
 * `lz4f` or `lz4f.LEVEL` (an integer) or `lz4f.max`
 * `zstd` or `zstd.LEVEL` (an integer) or `zstd.max` or `zstd.overclock`
The meaning of LEVEL depends on the algorithm.  The default is chosen for
good compression ratios with fast compression time.  `max` is for the best
compression ratios but much slower compression time (e.g. release builds).

If there are no PATTERN arguments and no files named to add to the BOOTFS
(via manifest file entries, nonempty directories, or `--entry` switches)
then any ZBI input items of BOOTFS type are passed through as they are,
except for possibly compressing raw `--type=bootfs` input items.
In all other cases there is only a single BOOTFS item (if any) written out.
So `-- \*` will force merging when no individual files are being added.

The BOOTFS image contains all files from BOOTFS items in ZBI input files,
manifest files, directories, and `--entry` switches.  The BOOTFS directory
table is always sorted.  By default it's an error to have duplicate target
file names in the input (even with the same source).  `--replace` or `-r`
allows it: the last entry in input order wins.
**TODO(mcgrathr):** not quite true yet

Each argument after -- is a shell filename PATTERN (`*` matches even `/`)
to filter the files that will be packed into BOOTFS, extracted, or listed.
For a PATTERN that starts with `!` or `^` matching names are excluded after
including matches for all positive PATTERN arguments.  Note that PATTERN
is compared to the final BOOTFS target file name with any PREFIX applied.

When extracting a single file, `--output` or `-o` can be used.
Otherwise multiple files are created with their BOOTFS file names
relative to PREFIX (default empty, so in the current directory).
Note that the last PREFIX on the command line affects extraction,
though each PREFIX also (first) affects BOOTFS files added due to arguments
that follow it.  So if any PREFIX appears before such input arguments when
extracting, the extracted file names will have a doubled PREFIX unless a
`--prefix=.` or other PREFIX value follows the input arguments.

With `--extract-items` or `-X`, instead of BOOTFS files the names are
synthesized as shown below, numbered in the order items appear in the input
starting with 001.  Output files are ZBI files that can be input later.

With `--extract-raw` or `-R`, each file is written with just the
uncompressed payload of the item and no ZBI headers.
TYPE can be hexadecimal or a name string (case-insensitive).
Extracted items use the file names shown below:
    --type               --extract-item             --extract-raw
    CONTAINER            001.container.zbi          001.container.bin
    KERNEL_X64           001.kernel_x64.zbi         001.kernel_x64.bin
    KERNEL_ARM64         001.kernel_arm64.zbi       001.kernel_arm64.bin
    KERNEL_RISCV64       001.kernel_riscv64.zbi     001.kernel_riscv64.bin
    DISCARD              001.discard.zbi            001.discard.bin
    RAMDISK              001.ramdisk.zbi            001.ramdisk.bin
    BOOTFS               001.bootfs.zbi             001.bootfs.bin
    BOOTFS_FACTORY       001.bootfs_factory.zbi     001.bootfs_factory.bin
    KERNEL               001.kernel.zbi             001.kernel.bin
    CMDLINE              001.cmdline.zbi            001.cmdline.txt
    CRASHLOG             001.crashlog.zbi           001.crashlog.bin
    NVRAM                001.nvram.zbi              001.nvram.bin
    PLATFORM_ID          001.platform_id.zbi        001.platform_id.bin
    CPU_TOPOLOGY         001.cpu_topology.zbi       001.cpu_topology.bin
    DEPRECATED_CPU_TOPOLOGY_V1 001.deprecated_cpu_topology_v1.zbi 001.deprecated_cpu_topology_v1.bin
    DEPRECATED_CPU_TOPOLOGY_V2 001.deprecated_cpu_topology_v2.zbi 001.deprecated_cpu_topology_v2.bin
    MEM_CONFIG           001.mem_config.zbi         001.mem_config.bin
    KERNEL_DRIVER        001.kernel_driver.zbi      001.kernel_driver.bin
    ACPI_RSDP            001.acpi_rsdp.zbi          001.acpi_rsdp.bin
    SMBIOS               001.smbios.zbi             001.smbios.bin
    EFI_SYSTEM_TABLE     001.efi_system_table.zbi   001.efi_system_table.bin
    FRAMEBUFFER          001.framebuffer.zbi        001.framebuffer.bin
    DRV_MAC_ADDRESS      001.drv_mac_address.zbi    001.drv_mac_address.bin
    DRV_PARTITION_MAP    001.drv_partition_map.zbi  001.drv_partition_map.bin
    DRV_BOARD_PRIVATE    001.drv_board_private.zbi  001.drv_board_private.bin
    DRV_BOARD_INFO       001.drv_board_info.zbi     001.drv_board_info.bin
    IMAGE_ARGS           001.image_args.zbi         001.image_args.txt
    BOOT_VERSION         001.boot_version.zbi       001.boot_version.bin
    HW_REBOOT_REASON     001.hw_reboot_reason.zbi   001.hw_reboot_reason.bin
    SERIAL_NUMBER        001.serial_number.zbi      001.serial_number.txt
    BOOTLOADER_FILE      001.bootloader_file.zbi    001.bootloader_file.bin
    DEVICETREE           001.devicetree.zbi         001.devicetree.dtb
    ENTROPY              001.entropy.zbi            001.entropy.bin
    EFI_MEMORY_ATTRIBUTES_TABLE 001.efi_memory_attributes_table.zbi 001.efi_memory_attributes_table.bin