mkdepthcharge - Build boot images for the ChromeOS bootloader
mkdepthcharge -o FILE [options]
[VMLINUZ] [INITRAMFS ...] [DTB ...]
mkdepthcharge wraps the mkimage(1) and
vbutil_kernel(1) programs with reasonable defaults to package its
inputs into the format the ChromeOS bootloader expects. It also automates
preprocessing steps and initramfs support hacks that a user would have to do
manually or write a script for.
The VMLINUZ should be a kernel executable, INITRAMFS
should be a ramdisk image that the kernel should be able to use on its own,
and DTB files should be device-tree binary files appropriate for the
kernel.
mkdepthcharge tries to determine the type of each input
file by some heuristics on their contents, but failing that it assumes a
file is whatever is missing in the VMLINUZ, INITRAMFS,
DTB order. Alternatively, these files can be specified as options
instead of positional arguments.
- -A ARCH, --arch ARCH
- Architecture to build the images for. The following architectures are
understood: arm, arm64, aarch64 for ARM boards;
x86, x86_64, amd64 for x86 boards. If not given, the
build architecture of the VMLINUZ file is used.
- --format FORMAT
- Kernel image format to use, either fit or zimage. If not
given, architecture-specific defaults are used.
- fit
- This is the default on ARM boards. The VMLINUZ and the optional
INITRAMFS, DTB files are packaged into the Flattened Image
Tree (FIT) format using mkimage(1) and that is passed to
vbutil_kernel(1).
- zimage
- This is the default for x86 boards. The VMLINUZ is passed mostly
unmodified to vbutil_kernel(1), except for decompression and
padding for self-decompression. The INITRAMFS file is passed as the
--bootloader argument and the kernel header is modified to point to
where it will be in memory. It does not support packaging DTB
files.
- -h,
--help
- Show a help message and exit.
- --kernel-start ADDR
- Start of the Depthcharge kernel buffer in memory. Depthcharge loads the
packed data to a fixed physical address in memory, and some initramfs
support hacks require this value to be known. This is exactly the
board-specific CONFIG_KERNEL_START value in the Depthcharge source
code and defaults to 0x100000 for the x86 architecture.
- -o FILE, --output FILE
- Write the image to FILE. The image isn't generated at the output,
but copied to it from a temporary working directory. This option is
mandatory.
- --pad-vmlinuz,
--no-pad-vmlinuz
- Pad the VMLINUZ file so that the kernel's self-decompression has
enough space to avoid overwriting the INITRAMFS file during boot.
This has different defaults and behaviour depending on the image format,
see explanations in their respective sections.
- --tmpdir DIR
- Create and keep temporary files in DIR. If not given, a temporary
mkdepthcharge-* directory is created in /tmp and removed at
exit.
- -v,
--verbose
- Print info messages, mkimage(1) output and vbutil_kernel(1)
output to stderr.
- -V,
--version
- Print program version and exit.
- -C TYPE, --compress TYPE
- Compress the VMLINUZ before packaging it into a FIT image, either
with lz4 or lzma. none is also accepted, but does
nothing.
- -n DESC, --name DESC
- Description of the VMLINUZ to put in the FIT image.
- --pad-vmlinuz,
--no-pad-vmlinuz
- Pad the VMLINUZ file so that the kernel's self-decompression has
enough space to avoid overwriting the INITRAMFS file during boot.
The necessary padding is calculated based on compressed and decompressed
kernel sizes and the --kernel-start argument.
On earliest boards U-Boot moves the INITRAMFS away to a
safe place before running the VMLINUZ, and on ARM64 boards
Depthcharge itself decompresses the VMLINUZ to a safe place. But
32-bit ARM boards with Depthcharge lack FIT ramdisk support and run the
VMLINUZ in-place, so this initramfs support hack is necessary on
those.
This option is enabled by default when --patch-dtbs is
given, use the --no-pad-vmlinuz argument to disable it.
- --patch-dtbs,
--no-patch-dtbs
- Add linux,initrd-start and linux,initrd-end properties to
the DTB files' /chosen nodes. Their values are based on the
--kernel-start or the --ramdisk-load-address argument, one
of which is required if this argument is given.
These properties are normally added by Depthcharge, but 32-bit
ARM Chromebooks were released with versions before FIT ramdisk support
was introduced, so this initramfs support hack is necessary on
those.
- --ramdisk-load-address ADDR
- Add a load property to the FIT ramdisk subimage section. The oldest
ARM Chromebooks use an old custom U-Boot that implements the same verified
boot flow as Depthcharge. Its FIT ramdisk support requires an explicit
load address for the ramdisk, which can be provided with this
argument.
- --pad-vmlinuz,
--no-pad-vmlinuz
- Pad the VMLINUZ file so that the kernel's self-decompression has
enough space to avoid overwriting the INITRAMFS file during boot.
The necessary padding is calculated based on values in the zImage header
and the --kernel-start argument.
If the VMLINUZ and INITRAMFS are small enough
(about 16 MiB in total) they may fit between --kernel-start and
the start of the decompression buffer. In this case the padding is
unnecessary and not added.
The padding is usually larger than the decompressed version of
the kernel, so it results in unbootable images for older boards with
small image size limits. For these, it is usually necessary to use
--set-init-size, or custom kernels to make the parts fit as
described above.
This is disabled by default in favour of
--set-init-size, use the --pad-vmlinuz argument to enable
it.
- --set-init-size,
--no-set-init-size
- Increase the init_size kernel boot parameter so that the kernel's
self-decompression does not overwrite the INITRAMFS file during
boot. The modified value is calculated based on values in the zImage
header and the --kernel-start argument.
This only works if the kernel has KASLR enabled (as is
the default), because then the kernel itself tries to avoid overwriting
the INITRAMFS during decompression. However it does not do this
when first copying the VMLINUZ to the end of the decompression
buffer. Increasing init_size shifts copy this upwards to avoid it
overlapping INITRAMFS.
If the VMLINUZ and INITRAMFS are small enough,
they may fit before the first compressed copy's start. In this case
changing the value is unnecessary and skipped.
This is enabled by default, use the --no-set-init-size
argument to disable it.
- --bootloader FILE
- Bootloader stub for the very first Chromebooks that use H2C as their
firmware. Beyond those, this field is ignored on the firmware side except
as a ramdisk for the multiboot and zbi formats.
If an INITRAMFS is given for the zimage format,
it is placed here as part of an initramfs support hack for x86 boards.
Otherwise, an empty file is used.
- -c CMD [CMD ...],
--cmdline CMD [CMD ...]
- Command-line parameters for the kernel. Can be used multiple times to
append new values. If not given, -- is used.
The ChromeOS bootloader expands any instance of %U in
the kernel command line with the PARTUUID of the ChromeOS kernel
partition it has chosen to boot, e.g.
root=PARTUUID=%U/PARTNROFF=1 will set the root partition to the
one after the booted partition.
As knowing the currently booted partition is generally useful,
mkdepthcharge prepends kern_guid=%U to the given kernel
command line parameters to capture it. Use --no-kern-guid to
disable this.
- --kern-guid,
--no-kern-guid
- Prepend kern_guid=%U to kernel command-line parameters. This is
enabled by default, use the --no-kern-guid argument to disable
it.
- --keydir KEYDIR
- Directory containing verified boot keys to use. Equivalent to using
--keyblock KEYDIR/kernel.keyblock,
--signprivate KEYDIR/kernel_data_key.vbprivk, and
--signpubkey KEYDIR/kernel_subkey.vbpubk.
- --keyblock FILE, --signprivate FILE, --signpubkey FILE
- ChromiumOS verified boot keys. More specifically: kernel key block,
private keys in .vbprivk format, and public keys in .vbpubk format.
If not given, defaults to files set in
depthcharge-tools configuration. If those are not set,
mkdepthcharge searches for these keys in
/etc/depthcharge-tools and /usr/share/vboot/devkeys
directories, the latter being test keys that may be distributed with
vbutil_kernel(1).
You can set these in depthcharge-tools configuration by
the vboot-keyblock, vboot-private-key and
vboot-public-key options under a depthcharge-tools config
section.
In general, exits with zero on success and non-zero on
failure.
- /etc/depthcharge-tools/config,
/etc/depthcharge-tools/config.d/*
- The depthcharge-tools configuration files. These might be used to
specify locations of the ChromiumOS verified boot keys as system
configuration.
- /etc/depthcharge-tools
- The depthcharge-tools configuration directory. mkdepthcharge
searches this directory for verified boot keys.
- /usr/share/vboot/devkeys
- A directory containing test keys which should have been installed by
vbutil_kernel(1).
- KEYDIR/kernel.keyblock
- Default kernel key block file used for signing the image.
- KEYDIR/kernel_subkey.vbpubk
- Default public key used to verify signed images.
- KEYDIR/kernel_data_key.vbprivk
- Default private key used for signing the image.
depthchargectl(1), mkimage(1),
vbutil_kernel(1), futility(1)