U-Boot features¶

Introduction¶

This page documents the key features and functionalities supported by U-Boot.

Info

The default environment may change between releases/commits. If you manually upgrade U-Boot, and you have an old environment saved, it is a good idea to reset your environment to the new default (see Environment handling commands).

(There is no need to do that manually if you install U-Boot using our recovery SD card image).

Notable features¶

USB Mass Storage gadget¶

You can use the board as a USB Mass Storage device: You will be able to access all the partitions of any block device that is on the board or connected to it, from your host PC - You will see them as /dev/sdXX, just like connecting a regular USB storage to your PC, and you'll be able to mount them, and have full read/write access to them. You can even use it to flash a new U-Boot, re-partition the storage, re-format it, etc. This is especially useful for updating the internal eMMC.

To do this you need to connect a USB cable between the USB Client port of the board and a regular USB Host port on your PC, and use U-Boot's ums command.

General ums usage is:

ums <USB_controller> [<devtype>] <devnum>  e.g. ums 0 mmc 0
    devtype defaults to mmc

devtype can be any block device (e.g. mmc, usb)

To mount the eMMC:

ums 0 mmc 2

To mount an SD card:

ums 0 mmc 1

Depending on your host PC, it may automatically mount it or not. If not, you can use dmesg to see the names of the device and its partitions (it should be in the form of /dev/sdXX) and mount them yourself. To exit the ums command and disconnect the USB device press ctrl+c.

Note: You should use a Linux PC host as Windows can't naturally read ext file systems.

USB Ethernet Gadget¶

The USB Ethernet gadget allows you to make the board act as a USB Ethernet device when connecting its USB Client port to a host PC using a USB cable. Basically, it allows for "Ethernet over USB". This is especially useful if you build a custom board without an Ethernet interface and you want to boot via network using TFTP.

This feature is disabled by default. To enable it, you need to un-comment the defines of the following configs in include/configs/imx8mn_var_som.h in the U-Boot source code:

CONFIG_USB_ETHER
CONFIG_USB_ETH_CDC

Now you should have a new Ethernet interface called usb_ether.

Before actually using it you should get to know the following environment variables: Variables specific to this gadget:

usbnet_devaddr  - The virtual MAC address of the device (the board side).
usbnet_hostaddr - The virtual MAC address of the host (the PC side).

General network variables:

ethprime - Sets the primary Ethernet interface. This is the interface that will be tried first.
ethact   - Sets the currently active Ethernet interface. Normally, it is modified by the Ethernet driver, but you can change it if you want to override.
ipaddr   - IP address of the device - needed for tftp command.
netmask  - Subnet Mask.
serverip - TFTP server IP address - needed for tftp command.

So, for example:

setenv usbnet_devaddr f8:dc:7a:00:00:02
setenv usbnet_hostaddr f8:dc:7a:00:00:01
setenv ethact usb_ether
setenv ipaddr 192.168.0.100
setenv netmask 255.255.255.0
setenv serverip 192.168.0.101

And now you are ready to use tftpboot over the usb_ether interface.

Notes:

Once you run a network command, e.g. tftpboot, the gadget will be connected to your host PC and a new network adapter will be added to it, for the duration of the network interaction.
Note that you may need to configure your host PC to use the new network adapter properly - this configuration is OS dependent.

General U-Boot commands¶

List all supported commands and their description/usage (help command)¶

List all supported commands with a brief description for each one:

help

Print the description and usage of 'command':

help command

Environment handling commands¶

Print the values of all environment variables:

printenv

Print value of environment variable 'name':

printenv name

Set environment variable 'name' to 'value ...':

setenv name value ...

Delete environment variable 'name':

setenv name

Reset default environment:

env default -a

Save environment variables to persistent storage:

saveenv

File System access¶

List files in a directory (default /):

ls <interface> [<dev[:part]>] [directory]

For example:

List files in the BOOT partition of our NAND/eMMC Recovery SD card (after booting from it):

ls mmc 0:1

List files in directory /opt/images/Yocto in the rootfs partition of our NAND/eMMC Recovery SD card (after booting from it):

ls mmc 0:2 /opt/images/Yocto

Load binary file 'filename' from a partition to RAM address 'addr':

load <interface> [<dev[:part]> [<addr> [<filename> [bytes [pos]]]]]

USB sub-system¶

To use the USB as host (connect a USB Storage or Ethernet Device to the board), you need to use the usb command. Usage:

usb start - start (scan) USB controller
usb reset - reset (rescan) USB controller
usb stop [f] - stop USB [f]=force stop
usb tree - show USB device tree
usb info [dev] - show available USB devices
usb test [dev] [port] [mode] - set USB 2.0 test mode
    (specify port 0 to indicate the device's upstream port)
    Available modes: J, K, S[E0_NAK], P[acket], F[orce_Enable]
usb storage - show details of USB storage devices
usb dev [dev] - show or set current USB storage device
usb part [dev] - print partition table of one or all USB storage    devices
usb read addr blk# cnt - read `cnt' blocks starting at block `blk#'
    to memory address `addr'
usb write addr blk# cnt - write `cnt' blocks starting at block `blk#'
    from memory address `addr'

First, connect your device to a USB port on the board. After the device is connected, start the USB controller:

usb start

If you connect/disconnect devices after that, before you can access them you need to rescan the USB controller:

usb reset

Using a USB Storage Device¶

Once you connected the device and started the USB controller, you can now use the regular File System commands mentioned above with it. The <interface> in this case is 'usb'.

TPM 2.0 Support¶

For Symphony-Board v2.0 or higher and Sonata-Board, U-Boot supports TPM 2.0 devices connected over I2C. This allows early TPM access before the Linux kernel is loaded, including measured boot support, PCR operations, secure key storage flows, and hardware random number generation.

The tpm2 command family is available from the U-Boot command line when TPM support is enabled in the U-Boot configuration and the TPM device is described in the board device tree.

For the upstream U-Boot measured boot requirements, see the U-Boot measured boot documentation.
For the TPM command model and standard data structures, see the Trusted Computing Group TPM 2.0 Library specification.

General TPM 2.0 Usage¶

Before running other TPM commands, initialize the TPM device and start it:

tpm2 init
tpm2 startup TPM2_SU_CLEAR

TPM2_SU_CLEAR performs a clear startup and starts the TPM with fresh volatile state. TPM2_SU_STATE resumes the TPM from previously saved state and is used only when the platform implements that suspend/resume flow.

To run the TPM self test:

tpm2 self_test full

Device and Capability Information¶

List the available TPM devices and show the current device:

tpm2 device

Print information about the current TPM device:

tpm2 info

Read TPM capabilities with get_capability:

tpm2 get_capability <capability> <property> <addr> <count>

The command arguments are:

capability - TPM capability group
property   - property or PCR selection inside the capability group
addr       - memory address used to store the returned values
count      - number of values to return

For example, to read the vendor ID string:

tpm2 get_capability 0x6 0x106 0x200 2

For an STM ST33KTPM TPM, this typically returns 0x53543333 and 0x4b54504d, which decode to the ASCII string ST33KTPM.

For capability constants and returned structures, refer to the TCG TPM 2.0 Library specification, especially Part 2, Structures, and Part 3, Commands.

PCR Commands¶

Platform Configuration Registers (PCRs) hold measured boot values. Extending a PCR combines the current PCR value with a new digest, so the final value represents the complete sequence of measurements.

Extend a PCR with a digest stored in memory:

tpm2 pcr_extend <pcr_index> <digest_addr>

Read a PCR value into memory:

tpm2 pcr_read <pcr_index> <addr>

These commands are the low-level building blocks for a measured boot chain: each boot stage measures the next stage before handing off control. A mismatch in any measured component changes the final PCR value.

For the standard PCR and measured boot model, see the TCG TPM 2.0 Library specification and the U-Boot measured boot documentation.

Clearing and Authorization¶

Clear a TPM hierarchy:

tpm2 clear <hierarchy>

Clearing removes keys, non-volatile data, and authorization state associated with the selected hierarchy. Use this carefully on provisioned systems.

Change the authorization value of a hierarchy:

tpm2 change_auth <hierarchy> <new_password> [<old_password>]

Supported hierarchy names are PLATFORM, OWNER, ENDORSEMENT, and LOCKOUT.

Dictionary Attack Mitigation¶

The TPM can enter lockout after repeated failed authorization attempts. This is the TPM dictionary attack mitigation mechanism.

Reset the dictionary attack failure counter:

tpm2 dam_reset [<password>]

Change the dictionary attack parameters:

tpm2 dam_parameters <max_tries> <recovery_time> <lockout_recovery> [<password>]

The parameters are:

max_tries         - maximum failed authorization attempts before lockout
recovery_time     - time, in seconds, before the failure counter is reduced
lockout_recovery  - time, in seconds, before lockout is cleared

For example, to disable dictionary attack mitigation during development:

tpm2 dam_parameters 0xffffffff 0 1

Do not use this configuration on production systems.

Automatic Startup¶

To simplify boot scripts, autostart runs the TPM initialization, startup, and self-test sequence:

tpm2 autostart

This is commonly placed early in the bootcmd sequence on systems that use the TPM during boot.

Typical Usage Flow¶

A minimal sequence to initialize the TPM and confirm communication is:

tpm2 init
tpm2 startup TPM2_SU_CLEAR
tpm2 self_test full
tpm2 get_capability 0x6 0x106 0x200 2

If the capability command returns the expected vendor ID values instead of an error, the TPM is responding to U-Boot commands and can be used for PCR operations or measured boot integration.