mkdepthcharge(1)

📦
version 0.6.2 · 4 versions
, in ubuntu resolute, ubuntu stonking

🌈 mkdepthcharge(1) · depthcharge-tools 🌈

✨ NAME ✨

mkdepthcharge — build boot images for the ChromeOS bootloader 💅

🌸 SYNOPSIS 🌸

mkdepthcharge -o FILE [options] [VMLINUZ] [INITRAMFS ...] [DTB ...]

💫 DESCRIPTION 💫

okay bestie, here's the vibe: mkdepthcharge is basically the ultimate glow-up wrapper around mkimage(1) and vbutil_kernel(1). it takes those two and hands them reasonable defaults so your inputs get packaged into the exact format the ChromeOS bootloader is expecting. no cap. 🎀

and it doesn't stop there — it also automates all the preprocessing steps and initramfs support hacks that you'd otherwise be doing manually or writing a whole script for. it's giving "I got you, girl". ✨

so who are the players?

  • VMLINUZ — should be a kernel executable 🧚
  • INITRAMFS — should be a ramdisk image that the kernel should be able to use on its own 💖
  • DTB files — should be device-tree binary files appropriate for the kernel 🌸

mkdepthcharge tries to figure out the type of each input file by some heuristics on their contents (detective energy 🔍), but if that fails? it just assumes a file is whatever's missing in the VMLINUZ, INITRAMFS, DTB order. Alternatively, these files can be specified as options instead of positional arguments. your call, main character. 👑

💅 OPTIONS 💅

🍓 Input files 🍓

  • -d VMLINUZ, --vmlinuz VMLINUZ — the kernel executable. If a compressed file is given here, it is decompressed and its contents are used in its place. 🔥
  • -i INITRAMFS [INITRAMFS ...], --initramfs INITRAMFS [INITRAMFS ...] — ramdisk image. If multiple files are given (e.g. for CPU microcode updates 👀), they are concatenated and used as a single file. teamwork!
  • -b DTB [DTB ...], --dtbs DTB [DTB ...] — device-tree binary files. 🌈

🦋 Global options 🦋

  • -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. bye bestie 👋
  • --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. 💫

🧚 FIT image options 🧚

  • -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. 🗺️

🎀 zImage image options 🎀

  • --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. 🫶

👑 Depthcharge image options 👑

  • --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. 📝

🌟 EXIT STATUS 🌟

In general, exits with zero on success and non-zero on failure. simple as that bestie 💖

📁 FILES 🗂️

  • /etc/depthcharge-tools/config, /etc/depthcharge-tools/config.d/* — the depthcharge-tools config files bestie 💅. These can be used to say where your ChromiumOS verified boot keys live, like, as system configuration. Very "set it and forget it" of them.
  • /etc/depthcharge-tools — this is the depthcharge-tools config directory, the home base 🏠. mkdepthcharge goes digging around in here looking for verified boot keys.
  • /usr/share/vboot/devkeys — a directory stuffed with test keys that should have been installed by vbutil_kernel(1). Should have. 👀
  • KEYDIR/kernel.keyblock — the default kernel key block file, aka the one used for signing the image ✍️.
  • KEYDIR/kernel_subkey.vbpubk — the default public key, the one that verifies signed images ✅.
  • KEYDIR/kernel_data_key.vbprivk — the default private key used for signing the image 🔐. Guard it with your life, bestie.

🌸 EXAMPLES 🌸

Okay this is the part where it gets real fun, because these are actual things you can type and the vibes are immaculate. Let's go 🦋

✨ The bare minimum, no thoughts just vibes

mkdepthcharge -o depthcharge.img /boot/vmlinuz

This is the simplest invocation that exists, periodt. But heads up: if you try this on an ARM board, the firmware might straight up refuse to boot the output image because it's got no dtb for the board 😭. And even if the firmware does run the /boot/vmlinuz binary, it might not actually boot correctly for non-firmware reasons — like a kernel panic because there's no root. Not the move. 💀

✨ The Samsung Chromebook Plus (v1) moment

mkdepthcharge -o system.img --cmdline "root=/dev/mmcblk0p2" --compress lz4 -- /boot/vmlinuz.gz /boot/initrd.img rk3399-gru-kevin.dtb

This is what someone on a Samsung Chromebook Plus (v1) might run on their board to make a bootable image for the system they're actually running. Main character energy, lowkey iconic 👑

✨ The veyron board situation

mkdepthcharge -o veyron.img -c "root=LABEL=ROOT gpt" --kernel-start 0x2000000 --patch-dtbs -- /boot/vmlinuz /boot/initramfs-linux.img /boot/dtbs/rk3288-veyron-*.dtb

Build an image meant to work on veyron boards — think ASUS Chromebook C201PA and Chromebook Flip C100PA 🎀. Here's the tea: the stock Depthcharge on these boards does not process the FIT ramdisk, so the dtbs needs to be patched for it to boot with initramfs. No patch, no boot, no cap. 🧚

✨ The peach-pit plot twist

mkdepthcharge -o peach-pit.img -c "console=null" --ramdisk-load-address 0x44000000 -- vmlinuz initramfs exynos5420-peach-pit.dtb exynos5420-peach-pit.dtb

Build an image meant to work on a Samsung Chromebook 2 (11" ). This board runs a custom U-Boot, so it needs an explicit ramdisk load address, okay?? And its firmware has a bug when loading the device-tree file — so you gotta list that file twice for the result to actually be bootable. Yes, twice. Same file. That's not a typo, that's a workaround, and it's giving "firmware said I'm quirky" 💅🫶

🌈 SEE ALSO 🌈

That's the whole page bestie, you made it to the end and I'm so proud of you 🥹💖. This was v0.6.2, dated 2023-06-30, and yeah, mkdepthcharge(1) really said "here's everything you need, now go make a bootable image." Slay. ✨👑💅

📦 where this page comes from