.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "MKDEPTHCHARGE" 1 "2022-11-24" "v0.6.1" "depthcharge-tools"
.SH NAME
mkdepthcharge \- Build boot images for the ChromeOS bootloader
.SH SYNOPSIS
.sp
\fBmkdepthcharge\fP \fB\-o\fP \fIFILE\fP [options] [\fIVMLINUZ\fP] [\fIINITRAMFS\fP] [\fIDTB\fP ...]
.SH DESCRIPTION
.sp
\fBmkdepthcharge\fP wraps the \fImkimage\fP(1) and \fIvbutil_kernel\fP(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.
.sp
The \fIVMLINUZ\fP should be a kernel executable, \fIINITRAMFS\fP should be a
ramdisk image that the kernel should be able to use on its own, and
\fIDTB\fP files should be device\-tree binary files appropriate for the
kernel.
.sp
\fBmkdepthcharge\fP 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 \fIVMLINUZ\fP, \fIINITRAMFS\fP, \fIDTB\fP order.
Alternatively, these files can be specified as options instead of
positional arguments.
.SH OPTIONS
.SS Input files
.INDENT 0.0
.TP
.BI \-d \ VMLINUZ\fR,\fB \ \-\-vmlinuz \ VMLINUZ
Kernel executable. If a compressed file is given here, it is
decompressed and its contents are used in its place.
.TP
.BI \-i \ INITRAMFS\fR,\fB \ \-\-initramfs \ INITRAMFS
Ramdisk image.
.UNINDENT
.INDENT 0.0
.TP
.B \-b \fIDTB\fP [\fIDTB\fP ...], \-\-dtbs \fIDTB\fP [\fIDTB\fP ...]
Device\-tree binary files.
.UNINDENT
.SS Global options
.INDENT 0.0
.TP
.BI \-A \ ARCH\fR,\fB \ \-\-arch \ ARCH
Architecture to build the images for.  The following architectures
are understood: \fBarm\fP, \fBarm64\fP, \fBaarch64\fP for ARM boards;
\fBx86\fP, \fBx86_64\fP, \fBamd64\fP for x86 boards. If not given, the
build architecture of the \fIVMLINUZ\fP file is used.
.TP
.BI \-\-format \ FORMAT
Kernel image format to use, either \fBfit\fP or \fBzimage\fP\&. If not
given, architecture\-specific defaults are used.
.INDENT 7.0
.TP
.B fit
This is the default on ARM boards. The \fIVMLINUZ\fP and the
optional \fIINITRAMFS\fP, \fIDTB\fP files are packaged into the
Flattened Image Tree (FIT) format using \fImkimage\fP(1) and that is
passed to \fIvbutil_kernel\fP(1)\&.
.TP
.B zimage
This is the default for x86 boards. The \fIVMLINUZ\fP is passed
mostly unmodified to \fIvbutil_kernel\fP(1), except for decompression
and padding for self\-decompression. The \fIINITRAMFS\fP file is
passed as the \fB\-\-bootloader\fP argument and the kernel header is
modified to point to where it will be in memory. It does not
support packaging \fIDTB\fP files.
.UNINDENT
.TP
.B  \-h\fP,\fB  \-\-help
Show a help message and exit.
.TP
.BI \-\-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 \fBCONFIG_KERNEL_START\fP value in the
Depthcharge source code and defaults to \fB0x100000\fP for the x86
architecture.
.TP
.BI \-o \ FILE\fR,\fB \ \-\-output \ FILE
Write the image to \fIFILE\fP\&. The image isn\(aqt generated at the output,
but copied to it from a temporary working directory. This option is
mandatory.
.TP
.BI \-\-tmpdir \ DIR
Create and keep temporary files in \fIDIR\fP\&. If not given, a temporary
\fBmkdepthcharge\-*\fP directory is created in \fB/tmp\fP and removed at
exit.
.TP
.B  \-v\fP,\fB  \-\-verbose
Print info messages, \fImkimage\fP(1) output and \fIvbutil_kernel\fP(1) output to
stderr.
.TP
.B  \-V\fP,\fB  \-\-version
Print program version and exit.
.UNINDENT
.SS FIT image options
.INDENT 0.0
.TP
.BI \-C \ TYPE\fR,\fB \ \-\-compress \ TYPE
Compress the \fIVMLINUZ\fP before packaging it into a FIT image, either
with \fBlz4\fP or \fBlzma\fP\&. \fBnone\fP is also accepted, but does
nothing.
.TP
.BI \-n \ DESC\fR,\fB \ \-\-name \ DESC
Description of the \fIVMLINUZ\fP to put in the FIT image.
.TP
.B  \-\-patch\-dtbs\fP,\fB  \-\-no\-patch\-dtbs
Add \fBlinux,initrd\-start\fP and \fBlinux,initrd\-end\fP properties to
the \fIDTB\fP files\(aq \fB/chosen\fP nodes. Their values are based on the
\fB\-\-kernel\-start\fP or the \fB\-\-ramdisk\-load\-address\fP argument, one
of which is required if this argument is given.
.sp
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.
.TP
.BI \-\-ramdisk\-load\-address \ ADDR
Add a \fBload\fP 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.
.UNINDENT
.SS zImage image options
.INDENT 0.0
.TP
.B  \-\-pad\-vmlinuz\fP,\fB  \-\-no\-pad\-vmlinuz
Pad the \fIVMLINUZ\fP file so that the kernel\(aqs self\-decompression has
enough space to avoid overwriting the \fIINITRAMFS\fP file during boot.
The necessary padding is calculated based on values in the zImage
header and the \fB\-\-kernel\-start\fP argument.
.sp
If the \fIVMLINUZ\fP and \fIINITRAMFS\fP are small enough (about 16 MiB in
total) they may fit between \fB\-\-kernel\-start\fP and the start of the
decompression buffer. In this case the padding is unnecessary and
not added.
.sp
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
custom kernels to make the parts fit as described above.
.sp
This is enabled by default, use the \fB\-\-no\-pad\-vmlinuz\fP argument to
disable it.
.UNINDENT
.SS Depthcharge image options
.INDENT 0.0
.TP
.BI \-\-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 \fBmultiboot\fP and \fBzbi\fP formats.
.sp
If an \fIINITRAMFS\fP is given for the \fBzimage\fP format, it is placed
here as part of an initramfs support hack for x86 boards. Otherwise,
an empty file is used.
.UNINDENT
.INDENT 0.0
.TP
.B \-c \fICMD\fP [\fICMD\fP ...], \-\-cmdline \fICMD\fP [\fICMD\fP ...]
Command\-line parameters for the kernel. Can be used multiple times
to append new values. If not given, \fB\-\-\fP is used.
.sp
The ChromeOS bootloader expands any instance of \fB%U\fP in the kernel
command line with the PARTUUID of the ChromeOS kernel partition it
has chosen to boot, e.g. \fBroot=PARTUUID=%U/PARTNROFF=1\fP will set
the root partition to the one after the booted partition.
.sp
As knowing the currently booted partition is generally useful,
\fBmkdepthcharge\fP prepends \fBkern_guid=%U\fP to the given kernel
command line parameters to capture it. Use \fB\-\-no\-kern\-guid\fP to
disable this.
.UNINDENT
.INDENT 0.0
.TP
.BI \-\-keydir \ DIR
Directory containing developer keys to use. Equivalent to using
\fB\-\-keyblock\fP "\fIDIR\fP\fB/kernel.keyblock\fP", \fB\-\-signprivate\fP
"\fIDIR\fP\fB/kernel_data_key.vbprivk\fP", and \fB\-\-signpubkey\fP
"\fIDIR\fP\fB/kernel_subkey.vbpubk\fP".
.TP
.BI \-\-keyblock \ FILE
Kernel key block file. If not given, the test key files distributed
with \fIvbutil_kernel\fP(1) are used.
.TP
.B  \-\-kern\-guid\fP,\fB  \-\-no\-kern\-guid
Prepend \fBkern_guid=%U\fP to kernel command\-line parameters. This is
enabled by default, use the \fB\-\-no\-kern\-guid\fP argument to disable
it.
.TP
.BI \-\-signprivate \ FILE
Private keys in .vbprivk format. If not given, the test key files
distributed with \fIvbutil_kernel\fP(1) are used.
.TP
.BI \-\-signpubkey \ FILE
Public keys in .vbpubk format. If not given, the test key files
distributed with \fIvbutil_kernel\fP(1) are used.
.UNINDENT
.SH EXIT STATUS
.sp
In general, exits with zero on success and non\-zero on failure.
.SH FILES
.INDENT 0.0
.TP
.B /usr/share/vboot/devkeys
Default devkeys directory containing test keys which might have
been installed by \fIvbutil_kernel\fP(1)\&.
.TP
.B /usr/share/vboot/devkeys/kernel.keyblock
Default kernel key block file used for signing the image.
.TP
.B /usr/share/vboot/devkeys/kernel_subkey.vbpubk
Default public key used to verify signed images.
.TP
.B /usr/share/vboot/devkeys/kernel_data_key.vbprivk
Default private key used for signing the image.
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
.TP
.B \fBmkdepthcharge\fP \fB\-o\fP \fIdepthcharge.img\fP \fI/boot/vmlinuz\fP
The simplest invocation possible. If tried on an ARM board, the
firmware might refuse to boot the output image since it doesn\(aqt have
a dtb for the board. Otherwise, even if the firmware runs the
\fI/boot/vmlinuz\fP binary, it might not correctly boot due to
non\-firmware causes (e.g. kernel panic due to not having a root).
.TP
.B \fBmkdepthcharge\fP \fB\-o\fP \fIsystem.img\fP \fB\-\-cmdline\fP \fI"root=/dev/mmcblk0p2"\fP \fB\-\-compress\fP \fIlz4\fP \fB\-\-\fP \fI/boot/vmlinuz.gz\fP \fI/boot/initrd.img\fP \fIrk3399\-gru\-kevin.dtb\fP
A command someone using a Samsung Chromebook Plus (v1) might run on
their board to create a bootable image for their running system.
.TP
.B \fBmkdepthcharge\fP \fB\-o\fP \fIveyron.img\fP \fB\-c\fP \fI"root=LABEL=ROOT gpt"\fP \fB\-\-kernel\-start\fP \fI0x2000000\fP \fB\-\-patch\-dtbs\fP \fB\-\-\fP \fI/boot/vmlinuz\fP \fI/boot/initramfs\-linux.img\fP \fI/boot/dtbs/rk3288\-veyron\-*.dtb\fP
Build an image intended to work on veyron boards like ASUS
Chromebook C201PA and Chromebook Flip C100PA. The stock Depthcharge
on these boards doesn\(aqt process the FIT ramdisk, so the dtbs needs
to be patched to boot with initramfs.
.TP
.B \fBmkdepthcharge\fP \fB\-o\fP \fIpeach\-pit.img\fP \fB\-c\fP \fI"console=null"\fP \fB\-\-ramdisk\-load\-address\fP \fI0x44000000\fP \fB\-\-\fP \fIvmlinuz\fP \fIinitramfs\fP \fIexynos5420\-peach\-pit.dtb\fP
Build an image intended to work on a Samsung Chromebook 2 (11").
This board uses a custom U\-Boot, so needs an explicit ramdisk load
address.
.UNINDENT
.SH SEE ALSO
.sp
\fIdepthchargectl\fP(1), \fImkimage\fP(1), \fIvbutil_kernel\fP(1), \fIfutility\fP(1)
.\" Generated by docutils manpage writer.
.