Booting LAN969x
1. Introduction
This document will focus on the LAN969x SoC, but to fully explain the boot process and boot facilities it is also necessary to consider the flash memories available on the board. The upcoming sections will briefly describe the boot media supported by the LAN969x, and then describe which of these media is available on the various evaluation boards offered by Microchip.
This document uses many abbreviations, see the terms and abbreviations section for details. |
2. Overview
LAN969x offers secure boot, which is based on ARM Trusted Firmware (TF-A). The TF-A architecture heavily influences the boot-sequence, and to understand how LAN969x boots, a bit of TF-A understanding is also needed.
Following is an illustration of a typical lan969x boot sequence using UBoot and Linux:
It is possible to skip UBoot, if this case the boot sequence will look like this:
TF-A and LAN969x goes through the following boot steps:
-
TF-A/BL1 This is ROM code embedded inside the chip. LAN969x always start by booting TF-A/BL1 from ROM. TF-A/BL1 loads the next bootloader (BL2) from one of the support boot-medias. The strapping pins are used to configure which of the supported boot-media to use.
-
BL2 This is a second stage boot-loader also part of TF-A. This bootloader runs from an on-chip SRAM, it setup the trust-zones, configure DDR memory and other basic platform initialization. Once the platform is initialized, it will load BL31 and BL33 from the configured boot-media into SRAM memory.
-
BL31 This is a called "EL3 Runtime Software", also part of TF-A. This stage does not influence the boot-flow directly, and will not be covered here.
-
BL33 In TF-A terminology, this is the unsecure firmware. It is not part of the TF-A project, but is signed and distributed together with TF-A. TF-A imports this as a BLOB. Typically this is either UBoot, LMStaX or a special version of the kernel which can run without UBoot.
The above list of update-able images (BL2, BL31 and BL33), plus relevant
certificates and relevant support files are packed in a FIP
(Firmware Image
Packet), which is a storage format defined by TF-A. The FIP containing these
images must be stored raw in the designed boot-media. In some cases it must be
put at a specific address, while in other it is stored in a partition with a
predefined name.
This document will not go into the details of TF-A, but just assume that the FIP is available and describe where and how it can be programmed. Two different FIPs will be used, one with UBoot as BL33, and another one with Linux-kernel as BL33.
3. Boot media configuration
The strapping pins are configuring the initial boot mode. The table below lists the supported modes:
Strapping Pins | LAN969x A0 |
---|---|
0000 (0x0) |
eMMC + FC0 (for trace) |
0001 (0x1) |
QSPI0 + FC0 (for trace) |
0010 (0x2) |
SDCard + FC0 (for trace) |
0011 (0x3) |
eMMC |
0100 (0x4) |
QSPI0 |
0101 (0x5) |
SDCard |
0110 (0x6) |
Reserved |
0111 (0x7) |
Reserved |
1000 (0x8) |
QSPI0-HS + FC0 |
1001 (0x9) |
Reserved |
1010 (0xa) |
TF-A Monitor at FC0 |
1011 (0xb) |
TF-A Monitor at FC0-HS |
1100 (0xc) |
Reserved |
1101 (0xd) |
QSPI0-HS |
1110 (0xe) |
Reserved |
1111 (0xf) |
SPI Client |
The strapping configuration is read by TF-A/BL1, which uses it to select select the boot-media, and thereby determinate where the FIP is loaded from. UBoot will also use the strapping pins to determinate which flash to load the environment configuration from.
In the above table FC0 means FlexCOM0, running in UART mode configured as 115200/8/N/1 with the RX signal at GPIO52/Alt-1 and TX signal at GPIO53/Alt-1.
For modes 0000-0010
the FC0 terminal is used as to emit debug traces
Mode 0011
to 0101
perform the same boot procedure, but with trace disabled
to improve performance.
In mode 1010
and 1011
a bidirectional machine interface is implemented.
3.1. UART Traces
When booting from flash the TF-A loaders can be configured to emit trace messages on the UART provided by FlexCom0. The following table show the strapping configurations with and without traces enables.
Trace enable | Trace disable | Flash type |
---|---|---|
0000 |
0011 |
eMMC |
0001 |
0100 |
QSPI/NOR |
0002 |
0101 |
SDCard |
Boards which do not have a compatible HW configuration shall avoid this strap mode.
Be aware that traces to the UART impact boot time and should only be activated when debugging is needed or the startup time is not important. |
3.2. Booting from eMMC/SDCard (0000, 0010, 0011 or 0101)
When booting from eMMC/SDCard, a valid GUID Partition Table (GPT) must be used. The
TF-A/BL1 ROM will look for a partition called fip
and fip.bak
and use then
accordingly. The table below provide an example of a partition table. The page
size for the eMMC/SDCard device is 0x200/512 bytes.
Type | Partition id | Partition Name | Offset | Partition size |
---|---|---|---|---|
GPT (PartTable) |
n/a |
n/a |
0x00000000 |
0x00008000 (32kb) |
TF-A FIP |
1 |
fip |
0x00100000 |
0x08000000 (128mb) |
TF-A FIP |
2 |
fip.bak |
0x08100000 |
0x08000000 (128mb) |
UBoot (Env) |
3 |
Env |
0x10100000 |
0x00200000 (2mb) |
UBoot (Env) |
4 |
Env.bak |
0x10300000 |
0x00200000 (2mb) |
ext4 (rootfs) |
5 |
Boot0 |
0x10500000 |
0x40000000 (1gb) |
ext4 (rootfs) |
6 |
Boot1 |
0x50500000 |
0x40000000 (1gb) |
ext4 (data) |
7 |
Data |
0x90500000 |
0x6fa00000 (1.74gb) |
SDCard doesn’t support redundant environment.
The bold partitions are the items which is hard-coded in either TF-A/BL1 or in UBoot. If it relates to UBoot then it can be changed, but requires changes to UBoot as well. Everything else is just an example which can be changed according to customer needs. |
3.3. Booting from NOR (0001 or 0100)
The following table contains the offsets used by TF-A and LMStaX when booting from QSPI/NOR:
Type | Partition id | Partition Name | Offset | Partition size |
---|---|---|---|---|
GPT (PartTable) |
n/a |
n/a |
0x00000000 |
0x00001000 (4KB) |
TF-A FIP |
1 |
fip |
0x00001000 |
0x0001e000 (120KB) |
TF-A FIP |
2 |
img-sel |
0x0001f000 |
0x00002000 (8KB) |
LMSTAX |
3 |
img-a |
0x00021000 |
0x000cf800 (830KB) |
LMSTAX |
4 |
img-b |
0x000f0800 |
0x000cf800 (830KB) |
TinyFS |
5 |
data |
0x001c0000 |
0x00040000 (256KB) |
3.4. UART Monitor (1010)
This mode will boot into a UART monitor using FlexCom0. This can be used to program the OTP and to load firmware into flash. This mode can be used without any valid content in the flash, and is therefore useful for de-brick or even production scenarios.
The UART Monitor implement a machine interface and should not be used interactively with a terminal. Instead use the HTML5 client provided as part of the TF-A project.
For any other use-case, the UART console terminal needs to be configured to 115200/8/N/1 |
4. Beyond TF-A
So far we have concentrated on configuring the HW and boot media. Once put in place, TF-A/BL2, BL2 and BL31 will boot, and eventually reach TF-A/BL33. TF-A/BL33 is the boot-step after TF-A, and can be UBoot, Linux kernel or some other OS. The following chapters covers this in more details.
4.1. TF-A/UBoot/Linux
In this mode the UBoot binary is embedded in into the FIP as TF-A/BL33. TF-A will do the platform initialization, load images (and authenticate them), DDR initialization etc. Once done, it will boot UBoot, which then control the next steps in boot flow.
UBoot will take care of loading the ITB and the rootfs and boot up into the Linux.
This is the so called normal-boot mode. |
5. Images and artifacts
The referenced images and archives can all found on public servers. Therefore, the following description will provide all needed information.
5.1. TFA images
The TFA (FIPs) images can be found under following link:
https://github.com/microchip-ung/arm-trusted-firmware/releases
5.2. Buildroot artifacts
The build artifacts (UBoot, kernel, rootfs etc.) can be found on following public server:
http://mscc-ent-open-source.s3-website-eu-west-1.amazonaws.com/?prefix=public_root/bsp
Download the proper architecture and build version. For example:
mscc-brsdk-arm64-yyyy.version.tar.gz
After extracting the *.tar.gz file, all rootfs and ITB related files can be found
inside following folder:
mscc-brsdk-arm64-yyyy.version/arm64-armv8_a-linux-gnu/standalone/release
5.3. Artifacts
The following subchapter gives a rough overview of the common used terms in the context of the available images and build artifacts.
5.3.1. TFA images
The upcoming table is describing the most important files extracted from the TFA artifacts archive:
File name | File type | BL33 data | Flash | Description |
---|---|---|---|---|
|
HTML5 |
n/a |
n/a |
Firmware update tool for MS Edge or Chrome |
|
BIN image |
n/a |
n/a |
Firmware update binary |
|
FIP file |
UBoot |
NOR/MMC |
Compressed RAW Plain text FIP (not encrypted) |
|
FIP file |
Linux |
NOR/MMC |
Compressed RAW Plain text FIP (not encrypted) |
|
GPT image |
UBoot |
MMC |
Compressed GPT image with embedded Plain text FIP |
|
GPT image |
Linux |
MMC |
Compressed GPT image with embedded Plain text FIP |
|
GPT image |
UBoot |
NOR |
Compressed GPT image with embedded Plain text FIP |
|
FIP file |
UBoot |
NOR/MMC |
Compressed RAW encrypted FIP (not encrypted) |
|
FIP file |
Linux |
NOR/MMC |
Compressed RAW encrypted FIP (not encrypted) |
|
GPT image |
UBoot |
MMC |
Compressed GPT image with embedded encrypted FIP |
|
GPT image |
Linux |
MMC |
Compressed GPT image with embedded encrypted FIP |
|
GPT image |
UBoot |
NOR |
Compressed GPT image with embedded encrypted FIP |
5.3.2. Buildroot artifacts
Following table is describing the available ITB and filesystem related binaries inside the buildroot artifacts archive:
File name | Description |
---|---|
|
ext4 rootfs with ITB, located in the root directory. |
|
ITB only, used in the *.gz file. |
|
ITB with Kernel and squashfs filesystem. Suitable for network boot. |
|
Standalone ITB (also usable for Sparx5) |
|
Standalone FIT Source |
|
Firmware update tool for MS Edge or Chrome |
|
Device Tree Blob for EV23x71a for XStaX |
|
Device Tree Blob for EV23x71a for Standalone |
|
Device Tree Blob for PCB10001 Modular Test Board |
|
Device Tree Blob for Sunrise FPGA Test Platform |
|
Device Tree Blob for LS1046 used with PCB110 for Standalone |
|
Device Tree Blob for LS1046 used with PCB121 for Standalone |
|
Device Tree Blob for LS1046 used with PCB134 for Standalone |
|
Linux Kernel Binary |
|
Compressed Linux Kernel Binary |
|
Compressed Linux Kernel Binary |
|
ext2 rootfs standalone |
|
ext4 rootfs standalone |
|
squashfs filesystem standalone |
|
rootfs/tar standalone |
|
Device Tree Blob for PCB134 with eMMC for XStaX |
|
Device Tree Blob for PCB134 for XStaX |
|
Device Tree Blob for PCB135 with eMMC for XStaX |
|
Device Tree Blob for PCB135 for XStaX |
|
Device Tree Blob for PCB125 Modular Test Board |
|
Device Tree Blob for PCB134 with eMMC for Standalone |
|
Device Tree Blob for PCB134 for Standalone |
|
Device Tree Blob for PCB135 with eMMC for Standalone |
|
Device Tree Blob for PCB135 for Standalone |
|
ITB without a rootfs |
|
Source file for ITB without a rootfs |
|
ITB without a rootfs in UBIFS format |
5.3.3. Kernel
The ITB files from the build artifacts archive including always the latest available kernel files.
5.3.4. DTS
The device tree sources are a set of text files in the Linux kernel source tree. They describe the hardware properties for a specific platform.
5.3.5. DTB
For processing the DTS, a Device Tree Compiler is used. The compiler takes a device-tree source as input and outputs a device-tree in a machine readable format.
Since the DTS represents the device-tree data in a human readable format, it is
the preferred input format.
The output result of the DTC results is a .dtb
file.
5.3.6. rootfs
Various types of root filesystem builds are provided inside the build artifact archive.
5.3.7. rootfs/tar
The rootfs/tar is accumulating a large collection of files into a single archive file, while preserving filesystem information such as user/group permissions, dates, files, inodes and directory structures.
There is no tarball compression method used. |
A tarball build of the rootfs/tar can be found inside the build artifacts
archive. Please have a look for a binary which is named to rootfs.tar
.
5.4. FIT
The Flattened Image Tree is a format for combining different binary elements
such as the kernel, initramfs and DTB into a single .itb
file.
Bootloaders like e.g. UBoot can read and process the FIT metadata to boot an embedded Linux system. |
5.4.1. ITB full
This type of the FIT is containing the kernel files, device tree(s) and a root filesystem. Besides the FIP file, only one further single binary needs to be maintained and flashed to the target system. The drawback is the longer bootup time, caused by the larger image size.
The according binary, which includes a 'squashfs' root filesystem, can be found in the build artifacts archive named by 'fit.itb'.
5.5. ext4
Beside of the rootfs/tar and the squashfs, there is also the usage of an ext4 root filesystem possible. The following section should give a rough overview about some ext4 based use-cases.
5.5.1. ext4 with embedded ITB bare on FS
This variant of the ext4 build is containing the ext4 filesystem and additionally an ITB located inside root directory of the ext4 filesystem. For example, UBoot is capable to load filesystem and execute the ITB found in the root directory.
This build variant is available inside the build artifacts archive. It is named to 'brsdk_standalone_arm64.ext4.gz'.
5.6. FIP
The FIP binary, so called 'fip.bin', is containing all parts of the TF-A firmware build. Basically,
following components can be found there:
-
BL2
-
BL31 or BL33
-
certificates
-
support files
The different FIP builds can be found inside the build artifacts archive.
5.7. GPT image
The GPT image is used for configuring basically the flash device structure. This means writing the GPT, creating all needed partitions and do some further setup work.
The boot partition named to 'fip' will contain afterwards a 'fip.bin' file for the first system startup.
5.8. eMMC/SDCard default partition schema
The following table is showing the default partition scheme for the MMC flash devices. This means this table is valid for the eMMC and the SDCard device.
offset size Name/desc ============== =============== ===================== 0x00000000 0x00008000 GPT 0x00100000 0x08000000 fip 0x08100000 0x08000000 fip.bk 0x10100000 0x00200000 Env 0x10300000 0x00200000 Env.bak 0x10500000 0x40000000 Boot0 0x50500000 0x40000000 Boot1 0x90500000 0x6fa00000 Data
When eMMC or SDCard is selected as boot media, the TF-A expects a GPT in the first 32kb of the flash memory.
The ROM code will look for a partition called fip
. It will now try to boot
from this partition.
If the booting from the fip
partition fails, it will try to load the firmware
image from the fip.bak
recovery partition.
If the boot attempt from the recovery partition is failing, no fallback approach is offered here.
6. Boot configurations
Possible boot methods will be described in the upcoming sections.
6.1. Network-boot
Before using the network boot feature, it needs to be ensured that the UBoot bootlader is made available inside the BL33.
After startup and entering UBoot console, the network stack on the target needs to be configured. This can be done by using static network settings or using a dynamic IP address provisioning like DHCP.
On the host system a TFTP server needs to be established. Host and target needs to be located in the same subnet. Afterwards the files can be transmitted over network to the target system memory.
For the network boot scenario a 'fit.itb' file needs to be provisioned by the TFTP server. After configuration of the UBoot, the file can be uploaded to the platform and will be executed directly from the target memory.
6.2. NOR
When QSPI/NOR is selected as boot media, the TF-A expect that the NOR flash is used in raw mode. This means in comparison to the eMMC/SDCard approach, there is no filesystem applied here.
The NOR flash device can usually programmed with a standard SPI flash programmer. Before attaching the programmer, check the usage of the proper pin header and use the correct SPI pins on the eval board. But here, there is also another further way for updating the NOR flash device possible. This will be described in the upcoming chapters.
Take care to write the 'fip.bin' file to a NOR memory address of 0x0 (zero).+ Because of the NOR size limitation on the LAN969x eval boards, only the 'fip.bin' file can be stored.
6.3. eMMC
For the eMMC boot operation mode, the 'fip.bin' file must to be located in a partition named 'fip' or 'fip.bak'.
In this example, the UBoot needs to be part of the 'fip.bin'. This is required for uploading and writing the ITB and FS data via DHCP/TFTP to the correct eMMC partition sections.
Afterwards the environment variables of UBoot needs to be setup properly for a full boot.
7. Use-cases
7.1. Debrick or blank flash
In case of a blank eMMC or NOR device, following the instructions in Restore SecureBoot Images
7.2. UBoot
According the flashed FIP or GPT file, UBoot is available during system boot and can be used for customizing e.g. the ITB and rootfs related components. Furthermore, it can be used for updating existing GPT images or FIP files on the flash device.
The table above lists the FIP or GPT images that contains a UBoot binary.
Sometimes it makes also to use the command of 'help', which provides a huge collection of all available commands and features. For example, the command of 'env print' can be used for dumping all available and initialized variables on the system.
7.2.1. Working with MMC subsystem
For setting up the UBoot mode, following steps needs to be applied:
-
Set the strapping mode to 0x0 (eMMC + FC0). See LAN969x Strapping Pins.
-
Attach the board via usb cable to the host workstation
-
Configure a serial console application like e.g. putty (settings 115200/8/N/1)
-
Attach console application to /dev/ttyACM0
-
Reset the board and interrupt the UBoot autoboot before timeout.
-
On UBoot console, the command 'mmc info' will return the emmc device properties.
m => mmc info Device: sdhci-host@e0830000 Manufacturer ID: 9d OEM: 101 Name: IS008 Bus Speed: 30000000 Mode : MMC High Speed (52MHz) Rd Block Len: 512 MMC version 5.0 High Capacity: Yes Capacity: 7.3 GiB Bus Width: 4-bit Erase Group Size: 512 KiB HC WP Group Size: 8 MiB User Capacity: 7.3 GiB WRREL Boot Capacity: 4 MiB ENH RPMB Capacity: 4 MiB ENH
The UBoot command of 'mmc help' will provide an overview of all available mmc sub system related commands.
m => mmc help mmc - MMC sub system Usage: mmc info - display info of the current MMC device mmc read addr blk# cnt mmc write addr blk# cnt mmc erase blk# cnt mmc rescan mmc part - lists available partition on current mmc device mmc dev [dev] [part] - show or set current mmc device [partition] mmc list - lists available devices mmc hwpartition [args...] - does hardware partitioning arguments (sizes in 512-byte blocks): [user [enh start cnt] [wrrel {on|off}]] - sets user data area attributes [gp1|gp2|gp3|gp4 cnt [enh] [wrrel {on|off}]] - general purpose partition [check|set|complete] - mode, complete set partitioning completed WARNING: Partitioning is a write-once setting once it is set to complete. Power cycling is required to initialize partitions after set to complete. mmc bootbus dev boot_bus_width reset_boot_bus_width boot_mode - Set the BOOT_BUS_WIDTH field of the specified device mmc bootpart-resize <dev> <boot part size MB> <RPMB part size MB> - Change sizes of boot and RPMB partitions of specified device mmc partconf dev [boot_ack boot_partition partition_access] - Show or change the bits of the PARTITION_CONFIG field of the specified device mmc rst-function dev value - Change the RST_n_FUNCTION field of the specified device WARNING: This is a write-once field and 0 / 1 / 2 are the only valid values. mmc setdsr <value> - set DSR register value
For example, the MMC command of 'mmc write' will primarily used for storing the data content on the flash device.
7.2.2. Working with NOR subsystem
For setting up the UBoot mode, following steps needs to be applied:
-
Set the strapping mode to 0x1 (QSPI + FC0). See LAN969x Strapping Pins.
-
Attach the board via usb cable to the host workstation
-
Configure a serial console application like e.g. putty (settings 115200/8/N/1)
-
Attach putty to /dev/ttyACM0
-
Reset the board and interrupt the UBoot autoboot before timeout
-
On the UBoot console, the command 'sf probe' will return the spi flash device properties
m => sf probe SF: Detected sst26wf016 with page size 256 Bytes, erase size 4 KiB, total 2 MiB
The UBoot command of 'sf help' will provide an overview of all available spi flash related sub system commands.
m => sf help sf - SPI flash sub-system Usage: sf probe [[bus:]cs] [hz] [mode] - init flash device on given SPI bus and chip select sf read addr offset|partition len - read `len' bytes starting at `offset' or from start of mtd `partition'to memory at `addr' sf write addr offset|partition len - write `len' bytes from memory at `addr' to flash at `offset' or to start of mtd `partition' sf erase offset|partition [+]len - erase `len' bytes from `offset' or from start of mtd `partition' `+len' round up `len' to block size sf update addr offset|partition len - erase and write `len' bytes from memory at `addr' to flash at `offset' or to start of mtd `partition' sf protect lock/unlock sector len - protect/unprotect 'len' bytes starting at address 'sector'
The SPI flash command of 'sf write' or 'sf update' will primarily used for storing FIP data content on the SPI flash device.
7.2.3. Loading files from network
UBoot can also configured for using the network stack for file transmission. A common practice is to enable the DHCP server on the host and using the UBoot 'dhcp' command. After recognizing a valid IP address, a file transmission using TFTP wil be established.
In case of using a static IP setup on the target, the following example can be applied via UBoot console. Adjust the values to the individual network environment.
The command of 'tftpboot' can be used then afterwards on the UBoot console.
env set 'ipaddr 192.168.0.10' env set 'netmask 255.255.255.0' env set 'serverip 192.168.0.1' saveenv m => help tftp tftpboot - boot image via network using TFTP protocol Usage: tftpboot [loadAddress] [[hostIPaddr:]bootfilename]
In case of a available DHCP server in the network, the UBoot command of 'dhcp' can be used. It will setup the network configuration and establish afterwards the TFTP based file transmission.
m => help dhcp dhcp - boot image via network using DHCP/TFTP protocol Usage: dhcp [loadAddress] [[hostIPaddr:]bootfilename]
The DHCP server, TFTP server and the target needs to be reside in the same network. |
Hereby, a test binary called 'fip.bin' will be now transmitted from the TFTP server via network to the target device memory. The used address of 0x64000000 is chosen randomly and points to an unused DDR memory section.
m => dhcp 0x64000000 fip.bin port0 Waiting for PHY auto negotiation to complete........ done Using port0 device TFTP from server 192.168.0.1; our IP address is 192.168.0.20 Filename 'fip.bin'. Load address: 0x64000000 Loading: ###################################### 106.4 KiB/s done Bytes transferred = 553376 (871a0 hex)
Now, the 'fip.bin' data is copied the target memory and can be e.g. written into an eMMC partition or in NOR flash device.
7.2.4. Boot image
This chapter shows some update examples.
In the first step, we have to check the UBoot environment variables inside the UBoot console. Therefore enter UBooot console by following routine:
-
Reset the board and wait for the UBoot autoboot stage
-
Press any key to stop autoboot timer in order to get a U-Boot console prompt.
Make sure that following environment variables are available as shown.
m => env print baudrate=115200 bootargs=console=ttyAT0,115200 root=/dev/ram0 loglevel=4 uio_pdrv_genirq.of_id=generic-uio bootargs_extra=uio_pdrv_genirq.of_id=generic-uio loglevel=1 bootcmd=run mmc_boot bootdelay=3 console=ttyAT0,115200n8 div_512=setexpr _tmp_ ${filesize} + 0x1ff; setexpr filesize_512 ${_tmp_} / 0x200; env set _tmp_ fdt_high=0xffffffff fdt_update=fdt addr ${loadaddr}; fdt set /images/kernel/ entry <0x0 0x60000000>; fdt set /images/kernel/ load <0x0 0x60000000> fip_fw=lan969x_a0.fip fip_fw_dl=dhcp ${loadaddr} ${fip_fw} initrd_high=0xffffffff loadaddr=0x64000000 mmc_bak=6 mmc_boot=run mmc_tryboot;run mmc_swap; run mmc_tryboot mmc_boot01_dlup=run mmc_dl; run mmc_boot0_upd; run mmc_boot1_upd mmc_boot0_dlup=run mmc_dl; run mmc_boot0_upd mmc_boot0_upd=run div_512; gpt setenv mmc 0 Boot0; mmc write ${mmc_unzip_loadaddr} ${gpt_partition_addr} ${filesize_512} mmc_boot1_dlup=run mmc_dl; run mmc_boot1_upd mmc_boot1_upd=run div_512; gpt setenv mmc 0 Boot1; mmc write ${mmc_unzip_loadaddr} ${gpt_partition_addr} ${filesize_512} mmc_cur=5 mmc_dev=mmc 0 mmc_dl=dhcp ${loadaddr} ${mmc_fw}; unzip ${loadaddr} ${mmc_unzip_loadaddr} mmc_fip01_dlup=run fip_fw_dl; if test $? = 0; then run mmc_fip0_upd; run mmc_fip1_upd; fi mmc_fip0_dlup=run fip_fw_dl; if test $? = 0; then run mmc_fip0_upd; fi; mmc_fip0_upd=run div_512; gpt setenv mmc 0 fip; mmc write ${loadaddr} ${gpt_partition_addr} ${filesize_512} mmc_fip1_dlup=run fip_fw_dl; if test $? = 0; then run mmc_fip1_upd; fi; mmc_fip1_upd=run div_512; gpt setenv mmc 0 fip.bak; mmc write ${loadaddr} ${gpt_partition_addr} ${filesize_512} mmc_format=gpt guid ${mmc_dev} mmc_guid; gpt write ${mmc_dev} ${mmc_part}; env save mmc_fw=brsdk_standalone_arm64.ext4.gz mmc_load=ext4load ${mmc_dev}:${mmc_cur} ${loadaddr} Image.itb mmc_part=uuid_disk=${mmc_guid};name=fip,start=1MiB,size=128MiB,type=system;name=fip.bak,size=128MiB,type=system;name=Env,size=2MiB,type=data;name=Env.bak,size=2MiB,type=data;name=Boot0,size=1GiB,type=linux;name=Boot1,size=1GiB,type=linux;name=Data,size=-,type=linux mmc_swap=env set _mmc_tmp ${mmc_bak}; env set mmc_bak ${mmc_cur}; env set mmc_cur ${_mmc_tmp}; env set _mmc_tmp; env save mmc_tryboot=run mmc_load; if test $? = 0; then run fdt_update; setenv mtdroot root_next=/dev/mmcblk0p${mmc_cur}; run ramboot; fi; mmc_unzip_loadaddr=0x80000000 mtdparts=mtdparts=spi0:-(fip) nor_boot=sf probe; env set active linux; run nor_tryboot; env set active linux.bk; run nor_tryboot nor_dlup=dhcp ${nor_image}; run nor_update nor_fip_dlup=run fip_fw_dl; if test $? = 0; then run nor_fip_upd; fi; nor_fip_upd=sf probe; sf update ${loadaddr} 0 ${filesize} nor_image=brsdk_standalone_arm64.itb nor_only=env set mtdparts mtdparts=${nor_parts};env set bootcmd run nor_boot;env save nor_parts=spi0:1920k(fip),64k(Env),64k(Env.bk),25m(linux),25m(linux.bk),12m(rootfs_data) nor_tryboot=mtd read ${active} ${loadaddr}; run ramboot nor_update=sf probe; sf update ${fileaddr} linux ${filesize} ramboot=bootm start ${loadaddr}#${pcb}; bootm loados ${loadaddr}#${pcb}; bootm ramdisk ${loadaddr}#${pcb}; run set_rootargs; run setup; bootm fdt ${loadaddr}#${pcb}; bootm prep ${loadaddr}#${pcb}; bootm go ${loadaddr}#${pcb} rootargs_mmc=setenv rootargs root=/dev/mmcblk0p${mmc_cur} rw rootwait rootargs_ram=setenv rootargs root=/dev/ram0 ro rootwait set_rootargs=if test $initrd_start = 0; then run rootargs_mmc; else; run rootargs_ram; fi; setup=setenv bootargs console=${console} ${mtdparts} ${rootargs} ${mtdroot} fis_act=${active} boot_source=${boot_source} ${bootargs_extra} Environment size: 3056/65531 bytes
Use the env set
command if something is wrong or missing and remember to use
the env save
command when you are done.
There might be other environment variables defined, but you can safely ignore them.
Some explanation for the predefined environment variables and for what they are used for:
-
fdt_high
- The value 0xffffffff prevents an extra copy of the flattened device tree. -
initrd_high
- The value 0xffffffff prevents an extra copy of the ramdisk. -
baudrate
- U-Boot console baudrate. -
bootdelay
- Number of seconds to wait for user input before running bootcmd. -
bootcmd
- Command to run automatically at boot. Default is set torun mmc_boot
. -
loadaddr
- Temporary address to use when loading images via TFTP or from eMMC. -
mmc_unzip_loadaddr
- Temporarily used address for uncompressing images -
mmc_bak
- The backup partition index for boot1 -
mmc_boot
- Try first to load 'brsdk_standalone_arm64.ext4.gz' from active partition. If failing then backup partition will be tried -
mmc_cur
- The default partition index for boot0 -
mmc_dev
- eMMC device to use in read/write commands. -
mmc_format
- Format eMMC device according defined partition layout -
mmc_part
- Partition layout definitions to use in 'mmc_format'. -
mmc_swap
- Change active partition from 'Boot0' to 'Boot1' and vice versa -
mmc_tryboot
- Seeking for available boot images -
mmc_load
- Try to load an ITB image from the active partition -
ramboot
- Try to load an run an ITB image from memory -
setup
- Configuring bootargs environment variable -
rootargs_mmc
- Configuration for rootfs in eMMC -
rootargs_ram
- Configuration for rootfs in ram -
set_rootargs
- Set correct configuration for root file system -
div_512
- Calculates the number of required flash pages (512 bytes) -
fip_fw
- Defines the name of the FIP file used for eMMC and NOR update -
fip_fw_dl
- Configuring and starting the DHCP request for file download -
nor_fip_upd
- Writes the FIP data to the NOR flash device -
nor_fip_dlup
- Download and write the FIP data to NOR flash device -
mmc_fip0_upd
- Writes FIP data to the eMMC device in partition 'fip' -
mmc_fip_dlup
- Download and write the FIP data to eMMC device -
mmc_fip1_upd
- Writes FIP data to the eMMC device in partition 'fip.bak' -
mmc_fip1_dlup
- Download and write the FIP data to eMMC device -
mmc_fip01_dlup
- Download FIP and write data to partition 'fip0' and 'fip1' -
mmc_fw
- Defines the name of the ext4.gz file for eMMC update -
mmc_dl
- Download ext4.gz file and uncompress data into target memory -
mmc_boot0_upd
- Writes the uncompressed data to the eMMC device in partition 'boot0' -
mmc_boot0_dlup
- Download, uncompress and write the image data to eMMC device -
mmc_boot1_upd
- Writes the uncompressed data to the eMMC device in partition 'boot1' -
mmc_boot1_dlup
- Download, uncompress and write the image data to eMMC device -
mmc_boot01_dlup
- Download, uncompress and write data to partition 'boot0' and 'boot1' -
console
- Configuration settings for the console terminal -
mtdparts
- NOR flash partition configuration -
bootargs_extra
- Additional UBoot arguments
The following examples assumes that the build artifacts of
brsdk_standalone_arm64.ext4.gz
and/or lan969x_a0.fip
are available on the
TFTP server.
7.2.4.1. from eMMC
For a successful eMMC boot, a special partition layout needs to be make available on the flash device. This can be achieved by following two approaches:
Use the already defined UBoot console command of 'mmc_format':
m => run mmc_format success! Writing GPT: success! Saving Environment to MMC... Writing to redundant MMC(0)... OK
or
Write a GPT image directly to the blank eMMC device, like described in the eMMC GPT section.
For checking the partition layout, use the UBoot command of 'mmc part'.This is the expected partition layout here:
m => mmc part Partition Map for MMC device 0 -- Partition Type: EFI Part Start LBA End LBA Name Attributes Type GUID Partition GUID 1 0x00000040 0x0004003f "fip" attrs: 0x0000000000000000 type: ebd0a0a2-b9e5-4433-87c0-68b6b72699c7 guid: 00042021-0408-4601-9dcc-a8c51255994f 2 0x00040040 0x0008003f "fip.bak" attrs: 0x0000000000000000 type: ebd0a0a2-b9e5-4433-87c0-68b6b72699c7 guid: 8ef917d1-2c6f-4bd0-a5b2-331a19f91cb2 3 0x00080040 0x0008103f "Env" attrs: 0x0000000000000000 type: ebd0a0a2-b9e5-4433-87c0-68b6b72699c7 guid: 77877125-add0-4374-9e60-02cb591c9737 4 0x00081040 0x0008203f "Env.bak" attrs: 0x0000000000000000 type: ebd0a0a2-b9e5-4433-87c0-68b6b72699c7 guid: b4b84b8a-04e3-48ae-8536-aff5c9c495b1 5 0x00082040 0x0028203f "Boot0" attrs: 0x0000000000000000 type: ebd0a0a2-b9e5-4433-87c0-68b6b72699c7 guid: 35219908-c613-4b08-9322-3391ff571e19 6 0x00282040 0x0048203f "Boot1" attrs: 0x0000000000000000 type: ebd0a0a2-b9e5-4433-87c0-68b6b72699c7 guid: 8e123a33-e3d3-4db9-92f4-d3ebd9b3224f 7 0x00482040 0x00e8ffde "Data" attrs: 0x0000000000000000 type: ebd0a0a2-b9e5-4433-87c0-68b6b72699c7 guid: 02a90af2-5d1c-4a29-9177-97a513e3cae4
Verify that Start LBA
in each partition equals the partition addresses in the
corresponding environment variable mmc_p<n>
. Please also see the
Partition table section.
The following scenario will now upload an brsdk_standalone_arm64.ext4.gz
file,
which is containing an ext4 rootfs and including an ITB in the root directory.
Following steps needs to be applied therefore:
Run the mmc_boot0_dlup
command to load the brsdk_standalone_arm64.ext4.gz
file
via DHCP to the target memory. Afterwards, the file will be uncompressed and
written into the eMMC partition 'Boot0'.
m => run mmc_boot0_dlup port0 Waiting for PHY auto negotiation to complete........ done Using port0 device TFTP from server 192.168.0.1; our IP address is 192.168.0.10 Filename 'brsdk_standalone_arm64.ext4.gz'. Load address: 0x64000000 Loading: ################################################################# ###### ........... ################################################################# ######################### 6.2 MiB/s done Bytes transferred = 106115072 (6533000 hex) MMC write: dev # 0, block # 8192, count 208960 ... 208960 blocks written: OK
If UBoot run in its default configuration, it will do now all needed actions, and make the rootfs and ITB available in the expected eMMC partition.
7.2.4.2. from network
Running the fip_fw_dl
command will upload the lan969x_a0.fip
file
using the DHCP/TFTP connection.
m => fip_fw_dl port0 Waiting for PHY auto negotiation to complete........ done Using port0 device TFTP from server 192.168.0.1; our IP address is 192.168.0.10 Filename 'lan969x_a0.fip'. Load address: 0x64000000 Loading: ################################################################# ###### ........... ################################################################# ######################################### 2.9 MiB/s done Bytes transferred = 22538412 (157e8ac hex)
Afterwards the command of ramboot
will execute the image inside
the memory. For example:
## Loading kernel from FIT Image at 64000000 ... Using Device Tree in place at 67d00000, end 67d07977 Starting kernel ...
For configuring the device permanently to the network boot mode, set the
environment variable of bootcmd
as shown below:
m => setenv bootcmd 'run fip_fw_dl; run ramboot' m => saveenv m => reset
After reset, UBoot will run the sequence of bootcmd
on every target startup.
7.2.4.3. from NOR
No matter if you have a eMMC equipped evaluation board you can also select to store the boot image in SPI NOR flash only and use this image as the boot media.
This will not be as fast as booting from eMMC but can be used as a fallback solution in case the first option is not available for some other reason.
To set the u-boot env to boot from nor it is required to run this command:
m => run nor_only
This will partitioned the NOR like this:
m => mtd list List of MTD devices: * nor0 - device: spi-flash@0 - parent: qspi@e0834000 - driver: jedec_spi_nor - path: /ahb/apb/qspi@e0834000/spi-flash@0 - type: NOR flash - block size: 0x1000 bytes - min I/O: 0x1 bytes - 0x000000000000-0x000000200000 : "nor0" - 0x000000000000-0x0000001e0000 : "fip" - 0x0000001e0000-0x0000001f0000 : "Env" - 0x0000001f0000-0x000000200000 : "Env.bk" - 0x000000200000-0x000001a00000 : "linux" - 0x000001a00000-0x000003400000 : "linux.bk" - 0x000003400000-0x000004000000 : "rootfs_data"
As you can see there are two 25MB linux partitions (a main and a backup) that can be used to store a FIT image.
To add an image in the NOR flash it is required to download the image and write it in the NOR using the command:
m => run nor_dlup
You can boot the system with the run nor_boot
command.
7.2.5. Program image
The UBoot console can also be used for programming a new image. This can be the case for some update reasons. But therefore, a running system with UBoot needs to be available on the target.
7.2.5.1. to eMMC
In the first step, we have to boot into UBoot console like following description:
-
Reset the board and wait for the UBoot autoboot stage
-
Press any key to stop autoboot timer in order to get a U-Boot console prompt.
Now we will upload a GPT image like e.g. lan969x_a0-release-ssk-mmc.gpt
to the target memory.
m => dhcp 0x64000000 lan969x_a0-release-ssk-mmc.gpt port0 Waiting for PHY auto negotiation to complete........ done Using port0 device TFTP from server 192.168.0.1; our IP address is 192.168.0.10 Filename 'lan969x_a0-release-ssk-mmc.gpt'. Load address: 0x64000000 Loading: ################################################################# ################################################################# ###### ........... ################################################################# ####### 6.1 MiB/s done Bytes transferred = 104890368 (6408000 hex)
Now the image data is uploaded to the target memory and can be written to the flash device.
Lets focus on the next two upcoming commands. The first command converts the uploaded filesize to the required number of flash pages (512 byte). The second command is writing the image data to the eMMC flash device.
Important is here, to set the write offset address of 0x0 (zero) for the flash.
m => run div_512 m => mmc write ${loadaddr} 0x0 ${filesize_512} MMC write: dev # 0, block # 0, count 208960 ... 208960 blocks written: OK
7.3. Update image from Linux
A running Linux system on the target can also be used for image update purpose. Therefore a network connection from the target to the host system needs to be established first. Afterwards a working TFTP server needs to make available in the same network.
Using the fdisk
command will dump the available partitions on the eMMC. This
is useful for checking the proper partition index identifier.
The device /dev/mmcblk0p<n> corresponds to partition <n>.
# fdisk -l Found valid GPT with protective MBR; using GPT Disk /dev/mmcblk0: 15269888 sectors, 3360M Logical sector size: 512 Disk identifier (GUID): 671e9526-c34a-4bc9-9670-bfebb6dba410 Partition table holds up to 128 entries First usable sector is 34, last usable sector is 15269854 Number Start (sector) End (sector) Size Name 1 2048 264191 128M fip 2 264192 526335 128M fip.bak 3 526336 530431 2048K Env 4 530432 534527 2048K Env.bak 5 534528 2631679 1024M Boot0 6 2631680 4728831 1024M Boot1 7 4728832 7634910 1418M Data
7.3.1. Update FIP
One way to upload the e.g. lan969x_a0-release-ssk.fip
file, is to
use a TFTP client inside the running Linux.
Therefore attach the putty console to the target and upload the FIP file using
the 'dhcp' or 'tftp' command in an e.g. /temp
folder on the target.
Afterwards the file can be written by using the dd
command into the proper
device partition.
In this example, we will write the data into the partition named to fip
which
can be mapped to /dev/mmcblk0p1
.
dd if=/temp/lan969x_a0-release-ssk.fip of=/dev/mmcblk0p1
After rebooting of the target, the updated file will be executed now.
7.3.2. Update ext4-img
The same approach as described before, can be applied also for updating the
brsdk_standalone_arm64.ext4.gz
binary.
Upload the file using e.g. TFTP to a /temp
folder or to a destination folder
of your preference. In this folder, it needs to be unzipped first.
Afterwards write the file by using the dd
command to the proper device partition.
In this example, we will write the data into the partition named to Boot0
which
can be mapped to /dev/mmcblk0p5
.
dd if=/temp/ext4-itb-bare.ext4 of=/dev/mmcblk0p5
After rebooting of the target, the updated file will be executed now.
8. TERMS and ABBREVIATIONS
BL1 Boot Loader 1: In secure immutable ROM (Trusted ROM Firmware) BL2 Boot Loader 2: In secure on-chip RAM, temporary (Trusted Boot Firmware) BL31 Boot Loader 31: Resident secure services (ARM v8) BL32 Boot Loader 32: Resident secure services (ARM v7) BL33 Boot Loader 33: Typically U-Boot. BSSK Binding Secret Symmetric Key CLI Command line interface DDR Double Data Rate, memory type DHCP Dynamic Host Configuration Protocol DTB Device Tree Blob DTC Device Tree Compiler DTS Device Tree Source files eMMC Embedded MultiMediaCard FCx Flex Com Interface #x FIP Firmware Image Package FIT Flattened Image Tree FS Filesystem FW Firmware GPT GUID Partition Table JTAG Joint Test Action Group, interface for testing and debugging KERNEL The Linux kernel LBA Logical Block Address OTP One-Time-Programmable Memory PCIe Peripheral Component Interconnect Express PSCI Power State Coordination Interface ROOTFS ROOT File System, used in Linux context ROT Root of Trust ROT-PK Root of Trust Public Key ROT-PK-SHA Root of Trust Public Key SHA (SHA of the public key of the ROT) ROT-PRIVATE Root of Trust Private Key SDCard Secure Digital Card SJTAG Secure JTAG SoC System on Chip SPI Serial Peripheral Interface SRAM Secure Ram SSK Secret Symmetric Key TBBR Trusted Board Boot Requirements TF-A Trusted Firmware for ARMv7 and ARMv8 TFTP Trivial File Transfer Protocol UART Universal Asynchronous Receiver-Transmitter