diff options
Diffstat (limited to 'doc/usage')
| -rw-r--r-- | doc/usage/cmd/bdinfo.rst | 7 | ||||
| -rw-r--r-- | doc/usage/cmd/config.rst | 40 | ||||
| -rw-r--r-- | doc/usage/cmd/dm.rst | 3 | ||||
| -rw-r--r-- | doc/usage/cmd/part.rst | 6 | ||||
| -rw-r--r-- | doc/usage/cmd/reset.rst | 2 | ||||
| -rw-r--r-- | doc/usage/cmd/sntp.rst | 2 | ||||
| -rw-r--r-- | doc/usage/cmd/wdt.rst | 2 | ||||
| -rw-r--r-- | doc/usage/cmd/wget.rst | 2 | ||||
| -rw-r--r-- | doc/usage/fit/dm-verity.rst | 304 | ||||
| -rw-r--r-- | doc/usage/fit/index.rst | 1 | ||||
| -rw-r--r-- | doc/usage/spl_boot.rst | 2 |
11 files changed, 358 insertions, 13 deletions
diff --git a/doc/usage/cmd/bdinfo.rst b/doc/usage/cmd/bdinfo.rst index 46046e55e06..6226d14bd66 100644 --- a/doc/usage/cmd/bdinfo.rst +++ b/doc/usage/cmd/bdinfo.rst @@ -124,12 +124,12 @@ Build current eth name of the active network device - Only shown if CONFIG_NET=y or CONFIG_NET_LWIP=y. + Only shown if CONFIG_NET=y. IP addr network address, value of the environment variable *ipaddr* - Only shown if CONFIG_NET=y or CONFIG_NET_LWIP=y. + Only shown if CONFIG_NET=y. fdt_blob address of U-Boot's own device tree, NULL if none @@ -173,5 +173,4 @@ The bdinfo command is available if CONFIG_CMD_BDI=y. The options to bdinfo are only available if CONFIG_GETOPT=y. -The ``-e`` option is additionally only available if CONFIG_NET=y or -CONFIG_NET_LWIP=y. +The ``-e`` option is additionally only available if CONFIG_NET=y. diff --git a/doc/usage/cmd/config.rst b/doc/usage/cmd/config.rst new file mode 100644 index 00000000000..bd8aa65ddbc --- /dev/null +++ b/doc/usage/cmd/config.rst @@ -0,0 +1,40 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. index:: + single: config (command) + +config command +============== + +Synopsis +-------- + +:: + + config [<str>] + +Description +----------- + +The config command prints the `.config` file used when building U-Boot +to the console. Note that the `.config` file is usually several 1000 +lines long. + +If the optional argument is given, only lines containing that string +(case insensitively) are printed. That can be useful if one wants to +check whether a specific option is enabled, or just to limit the +output to the subsystem of interest. + +The `.config` file is stored inside the U-Boot binary in +gzip-compressed format. + +Examples +-------- + +.. code-block:: bash + + # Print the entire .config + config + + # Print all lines related to pinctrl + config pinctrl diff --git a/doc/usage/cmd/dm.rst b/doc/usage/cmd/dm.rst index 196b22d1376..ac1c437bd9c 100644 --- a/doc/usage/cmd/dm.rst +++ b/doc/usage/cmd/dm.rst @@ -409,7 +409,8 @@ This example shows the abridged sandbox output:: regulator 1 [ ] sandbox_buck | | |-- buck2 regulator 2 [ ] sandbox_ldo | | |-- ldo1 regulator 3 [ ] sandbox_ldo | | |-- ldo2 - regulator 4 [ ] sandbox_buck | | `-- no_match_by_nodename + regulator 4 [ ] sandbox_buck | | |-- no_match_by_nodename + regulator 5 [ ] sandbox_ldo | | `-- ldo3 pmic 1 [ ] mc34708_pmic | `-- pmic@41 bootcount 0 [ + ] bootcount-rtc |-- bootcount@0 bootcount 1 [ ] bootcount-i2c-eeprom |-- bootcount diff --git a/doc/usage/cmd/part.rst b/doc/usage/cmd/part.rst index b91f6541f7f..a0e7be08a9a 100644 --- a/doc/usage/cmd/part.rst +++ b/doc/usage/cmd/part.rst @@ -52,7 +52,7 @@ The 'part list' command prints or sets an environment variable to the list of pa an optional environment variable to store the list of partitions value into. The 'part start' command sets an environment variable to the start of the partition (in blocks), -part can be either partition number or partition name. +part can be either partition number, partition UUID or partition name. interface interface for accessing the block device (mmc, sata, scsi, usb, ....) @@ -64,7 +64,7 @@ part can be either partition number or partition name. a variable to store the current start of the partition value into. The 'part size' command sets an environment variable to the size of the partition (in blocks), -part can be either partition number or partition name. +part can be either partition number, partition UUID or partition name. interface interface for accessing the block device (mmc, sata, scsi, usb, ....) @@ -76,7 +76,7 @@ part can be either partition number or partition name. a variable to store the current size of the partition value into. The 'part number' command sets an environment variable to the partition number using the partition name, -part must be specified as partition name. +part must be specified as partition UUID or partition name. interface interface for accessing the block device (mmc, sata, scsi, usb, ....) diff --git a/doc/usage/cmd/reset.rst b/doc/usage/cmd/reset.rst index 126db21cdb8..78c9c8873bc 100644 --- a/doc/usage/cmd/reset.rst +++ b/doc/usage/cmd/reset.rst @@ -20,7 +20,7 @@ Perform reset of the CPU. By default does COLD reset, which resets CPU, DDR and peripherals, on some boards also resets external PMIC. -w - Do warm WARM, reset CPU but keep peripheral/DDR/PMIC active. + Do WARM reset: reset CPU but keep peripheral/DDR/PMIC active. Return value diff --git a/doc/usage/cmd/sntp.rst b/doc/usage/cmd/sntp.rst index 2046828130d..433884f18b2 100644 --- a/doc/usage/cmd/sntp.rst +++ b/doc/usage/cmd/sntp.rst @@ -24,7 +24,7 @@ the server's IP address to be given on the command line or via the `ntpserverip` environment variable. The address of the NTP server does not need to be given if the DHCP server -provides one. The legacy network stack (`CONFIG_NET=y`) can only use the +provides one. The legacy network stack (`CONFIG_NET_LEGACY=y`) can only use the first NTP server provided in the `ntp-servers` DHCP option. When the network stack is lwIP (`CONFIG_NET_LWIP=y`) and DNS resolution diff --git a/doc/usage/cmd/wdt.rst b/doc/usage/cmd/wdt.rst index 711b74d20da..28abf98def9 100644 --- a/doc/usage/cmd/wdt.rst +++ b/doc/usage/cmd/wdt.rst @@ -16,7 +16,7 @@ Synopsis wdt start <timeout_ms> [flags] wdt stop wdt reset - wdt expirer [flags] + wdt expire [flags] Description ----------- diff --git a/doc/usage/cmd/wget.rst b/doc/usage/cmd/wget.rst index e6c42f967b9..f661d739a19 100644 --- a/doc/usage/cmd/wget.rst +++ b/doc/usage/cmd/wget.rst @@ -26,7 +26,7 @@ In order to use HTTPS you will need to compile wget with lwIP support. Legacy syntax ~~~~~~~~~~~~~ -The legacy syntax is supported by the legacy network stack (CONFIG_NET=y) +The legacy syntax is supported by the legacy network stack (CONFIG_NET_LEGACY=y) as well as by the lwIP base network stack (CONFIG_NET_LWIP=y). It supports HTTP only. diff --git a/doc/usage/fit/dm-verity.rst b/doc/usage/fit/dm-verity.rst new file mode 100644 index 00000000000..800a18fceae --- /dev/null +++ b/doc/usage/fit/dm-verity.rst @@ -0,0 +1,304 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +FIT dm-verity Boot Parameters +============================= + +Introduction +------------ + +Linux's dm-verity device-mapper target provides transparent integrity +checking of block devices using a Merkle tree. It is commonly used to +protect read-only root filesystems such as SquashFS images. + +When a FIT image packages the root filesystem as a loadable sub-image of +type ``filesystem`` (``IH_TYPE_FILESYSTEM``), the verity metadata can be +stored alongside the image data in a ``dm-verity`` subnode. U-Boot reads +this metadata at boot time and generates the kernel command-line parameters +that Linux needs to activate the verity target, eliminating the need for +an initramfs or userspace helper to set up dm-verity. + +This feature is enabled by ``CONFIG_FIT_VERITY`` (see ``boot/Kconfig``). + +Prerequisites +------------- + +* **Linux uImage.FIT block driver** – the kernel must include the FIT block + driver that exposes loadable sub-images as ``/dev/fit0``, ``/dev/fit1``, + etc. The driver assigns device numbers in the order loadables appear in + the FIT configuration. + +* **dm-verity support in the kernel** – ``CONFIG_DM_VERITY`` must be + enabled so the kernel can process the ``dm-mod.create=`` parameter. + +* **CONFIG_FIT_VERITY** enabled in U-Boot. + +How it works +------------ + +The implementation is split into a **build** phase and an **apply** phase, +both of which run automatically within the ``bootm`` state machine. No boot +method needs to call verity functions explicitly. + +**Build phase** (``BOOTM_STATE_FINDOTHER`` → ``boot_get_loadable()``) + +1. After all loadable sub-images have been loaded, + ``fit_verity_build_cmdline()`` iterates the configuration's + ``loadables`` list. + +2. For each loadable that is an ``IH_TYPE_FILESYSTEM`` image **and** + contains a ``dm-verity`` child node, a dm-verity target specification is + built by the helper ``fit_verity_build_target()``. + +3. The dm-verity target references ``/dev/fitN``, where *N* is the + zero-based index of the loadable in the configuration. This matches the + numbering used by the Linux FIT block driver. + +4. The resulting fragments are stored in ``struct bootm_headers``: + + ``images->dm_mod_create`` + The full dm-verity target table. Multiple targets are separated by ``;``. + + ``images->dm_mod_waitfor`` + Comma-separated list of ``/dev/fitN`` devices so the kernel waits for + the underlying FIT block devices to appear before activating + device-mapper. + +**Apply phase** (``BOOTM_STATE_OS_PREP``) + +5. Just before ``bootm_process_cmdline_env()`` processes the ``bootargs`` + environment variable, ``fit_verity_apply_bootargs()`` appends the + ``dm-mod.create=`` and ``dm-mod.waitfor=`` parameters. + +**Bootmeth integration** + + Because the fragments are stored in ``struct bootm_headers``, a boot + method can check ``fit_verity_active(images)`` between bootm state + invocations. A typical pattern splits ``bootm_run_states()`` into two + calls -- one for ``START|FINDOS|FINDOTHER|LOADOS`` and one for + ``OS_PREP|OS_GO`` -- and inspects ``fit_verity_active()`` in + between to decide whether to add a ``root=`` parameter pointing at the + dm-verity device. + +FIT image source (.its) example +------------------------------- + +Below is a minimal ``.its`` file showing a kernel and a dm-verity-protected +root filesystem packaged as a FIT. Only the three user-provided properties +(``algo``, ``data-block-size``, ``hash-block-size``) are included; ``mkimage`` +computes and fills in ``digest``, ``salt``, ``num-data-blocks``, and +``hash-start-block`` automatically (see `Generating verity metadata`_ below):: + + /dts-v1/; + + / { + description = "Kernel + dm-verity rootfs"; + #address-cells = <1>; + + images { + kernel { + description = "Linux kernel"; + data = /incbin/("./Image.gz"); + type = "kernel"; + arch = "arm64"; + os = "linux"; + compression = "gzip"; + load = <0x44000000>; + entry = <0x44000000>; + hash-1 { + algo = "sha256"; + }; + }; + + fdt { + description = "Device tree blob"; + data = /incbin/("./board.dtb"); + type = "flat_dt"; + arch = "arm64"; + compression = "none"; + hash-1 { + algo = "sha256"; + }; + }; + + rootfs { + description = "SquashFS root filesystem"; + data = /incbin/("./rootfs.squashfs"); + type = "filesystem"; + arch = "arm64"; + compression = "none"; + hash-1 { + algo = "sha256"; + }; + + dm-verity { + algo = "sha256"; + data-block-size = <4096>; + hash-block-size = <4096>; + }; + }; + }; + + configurations { + default = "config-1"; + config-1 { + description = "Boot with dm-verity rootfs"; + kernel = "kernel"; + fdt = "fdt"; + loadables = "rootfs"; + }; + }; + }; + +With this configuration U-Boot produces a kernel command line similar to:: + + dm-mod.create="rootfs,,, ro,0 <data_sectors> verity 1 \ + /dev/fit0 /dev/fit0 4096 4096 3762 3762 sha256 \ + 8e6791637f93cbb81fc45299e203cbe85ca2e47a38f5051bddeece92d7b1c9f9 \ + aa7b11f8db8fe2e5bfd4eca1d18a22b5de7ea39d2e1b93bb7272ce0c6ca3cc8e" \ + dm-mod.waitfor=/dev/fit0 + +dm-verity subnode properties +---------------------------- + +User-provided properties (required in the ``.its``): + +.. list-table:: + :header-rows: 1 + :widths: 20 15 65 + + * - Property + - Type + - Description + * - ``algo`` + - string + - Hash algorithm name, e.g. ``"sha256"``. + * - ``data-block-size`` + - u32 + - Data block size in bytes (>= 512, typically 4096). + * - ``hash-block-size`` + - u32 + - Hash block size in bytes (>= 512, typically 4096). + +Computed properties (filled in by ``mkimage``): + +.. list-table:: + :header-rows: 1 + :widths: 20 15 65 + + * - Property + - Type + - Description + * - ``num-data-blocks`` + - u32 + - Number of data blocks in the filesystem image (computed from the + image size and ``data-block-size``). + * - ``hash-start-block`` + - u32 + - Offset in ``hash-block-size``-sized blocks from the start of the + sub-image to the root block of the hash tree. + * - ``digest`` + - byte array + - Root hash of the Merkle tree, stored as raw bytes. Length must match + the output size of ``algo``. + * - ``salt`` + - byte array + - Salt used when computing the Merkle tree, stored as raw bytes. + +These values are the same ones produced by ``veritysetup format`` and can +typically be obtained from its output. +The ``digest`` and ``salt`` byte arrays correspond to the hex-encoded +``Root hash`` and ``Salt`` printed by ``veritysetup format``. + +Optional boolean properties (when present, they are collected and appended +as dm-verity optional parameters with hyphens converted to underscores): + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Property + - Description + * - ``restart-on-corruption`` + - Restart the system on data corruption. + * - ``panic-on-corruption`` + - Panic the system on data corruption. + * - ``restart-on-error`` + - Restart the system on I/O error. + * - ``panic-on-error`` + - Panic the system on I/O error. + * - ``check-at-most-once`` + - Verify data blocks only on first read. + + +Generating verity metadata +-------------------------- + +``mkimage`` automates the entire process. When it encounters a +``dm-verity`` subnode, it: + +1. Writes the embedded image data to a temporary file. +2. Runs ``veritysetup format`` with the user-supplied algorithm and + block sizes. +3. Parses ``Root hash`` and ``Salt`` from ``veritysetup`` stdout. +4. Reads the expanded content (original data + Merkle hash tree) back + into an in-memory buffer and removes the temporary file. The + external-data section written to the .itb file uses this buffer in + place of the original ``data`` property. +5. Writes the computed ``digest``, ``salt``, ``num-data-blocks``, and + ``hash-start-block`` properties into the ``dm-verity`` subnode. + +Images with ``dm-verity`` subnodes **must** use external data layout +(``mkimage -E``). ``mkimage`` will abort with an error if ``-E`` is +not specified. + +Usage:: + + # Create the filesystem image + mksquashfs rootfs/ rootfs.squashfs -comp xz + + # Build the FIT (dm-verity is computed automatically); align each + # external-data section to the block size of the underlying storage + # (see the alignment note below). + mkimage -E -B 0x1000 -f image.its image.itb + +``veritysetup`` (from the cryptsetup_ package) must be installed on +the build host. + +.. _cryptsetup: https://gitlab.com/cryptsetup/cryptsetup + +.. note:: + + ``veritysetup format`` is invoked with ``--no-superblock``, so no + on-disk superblock is written between the data and hash regions. + The Merkle hash tree is appended directly to the image data within + the FIT external data section. ``hash-start-block`` is therefore + computed as ``data_size / hash-block-size`` (the offset of the hash + region in units of ``hash-block-size``). When ``data-block-size`` + equals ``hash-block-size`` this happens to equal ``num-data-blocks``. + +.. note:: + + The Linux ``fitblk`` driver currently requires each ``filesystem`` + sub-image to start and end on block boundaries of the underlying + block device (typically 512 bytes, sometimes 4 KiB for eMMC or NVMe + with 4 KiB native sectors). Use ``mkimage -B <align>`` to pad + external-data sections to that boundary; ``-B 0x1000`` is a safe + default for the storage in common use. + + This alignment requirement comes from the kernel-side ``fitblk`` + driver to avoid unaligned-access fix-up overhead in block I/O, and + is **independent** of the dm-verity ``data-block-size`` and + ``hash-block-size`` properties -- those describe the block sizes + used by the device-mapper verity target itself, not storage + alignment. + +Kconfig +------- + +``CONFIG_FIT_VERITY`` + Depends on ``CONFIG_FIT`` and ``CONFIG_OF_LIBFDT``. + When enabled, ``fit_verity_build_cmdline()`` and + ``fit_verity_apply_bootargs()`` are compiled into the boot path. + When disabled, the functions are static inlines returning 0, so there + is no code-size impact. Works with both the ``bootm`` command and + BOOTSTD boot methods. diff --git a/doc/usage/fit/index.rst b/doc/usage/fit/index.rst index 6c78d8584ed..d17582b1d64 100644 --- a/doc/usage/fit/index.rst +++ b/doc/usage/fit/index.rst @@ -11,6 +11,7 @@ images that it reads and boots. Documentation about FIT is available in :maxdepth: 1 beaglebone_vboot + dm-verity howto kernel_fdt kernel_fdts_compressed diff --git a/doc/usage/spl_boot.rst b/doc/usage/spl_boot.rst index 93419f158af..64b8083e007 100644 --- a/doc/usage/spl_boot.rst +++ b/doc/usage/spl_boot.rst @@ -253,7 +253,7 @@ Ethernet a TFTP server and binary name. The binary is downloaded via the TFTP protocol. Required configuration settings include: - * CONFIG_SPL_NET=y or CONFIG_TPL_NET=y + * CONFIG_SPL_NET=y * CONFIG_SPL_ETH_DEVICE=y or CONFIG_DM_USB_GADGET=y |