3.1.1.1. General Information

Install host dependencies

To install host dependencies for building TI U-boot source (standalone) on Ubuntu 22.04+, run the following command in the terminal prompt:

sudo apt install git xz-utils build-essential autoconf flex bison libssl-dev bc libncurses-dev \
python3 python3-setuptools python3-dev python3-yaml python3-jsonschema python3-pyelftools \
swig yamllint

3.1.1.1.1. Getting the U-Boot Source Code

The easiest way to get access to the U-boot source code is by downloading and installing the Processor SDK Linux. Once installed, the U-Boot source code is included in the SDK at the path <path to tisdk>/board-support. For your convenience the sources also includes the U-Boot’s git repository including commit history.

Alternatively, U-Boot sources can directly be fetched from GIT. The GIT repo URL, branch and commit id can be found in the U-Boot section of the release notes.

3.1.1.1.2. Build U-Boot

Note

The following commands are intended to be run from the root of the U-Boot tree unless otherwise specified. The root of the U-Boot tree is the top-level directory and can be identified by looking for the “MAINTAINERS” file.

Note

Note about HSM Rearchitecture

After HSM rearchitecture in bootloader, loading of remote cores with firmware will be supported at A72 SPL stage only and not at R5 SPL stage. Early loading of remote core firmware in R5 SPL requires core reset functionality. As part of HSM rearchitecture, this functionality has moved into the DM service which requires SPL to re-implement device and clock control. This support is not present in Uboot R5 SPL due to memory constraints on the existing 64-bit TI devices.

Note

As of Processor SDK 9.0, compilation of bootloader images will no longer require different defconfigs for GP and HS devices. The same build commands will generate images for GP, HS-SE and HS-FS devices.

Prebuilt Images

Several prebuilt images are required from the TI Processor SDK for building U-Boot on K3 based platforms.

  • TF-A (BL31): Refer to ARM Trusted Firmware-A for more information

  • OP-TEE (TEE): Refer to OP-TEE for more information

  • ti-linux-firmware (BINMAN_INDIRS): Prebuilt binaries for DM and SYSFW available here.

All of these are available in the SDK at <path to tisdk>/board-support/prebuilt-images>

Go here to download and install the SDK.

Setting up the toolchain paths

Refer to Yocto-built SDK Toolchains section to use the toolchain packaged in the Processor SDK (recommended).

Refer to ARM toolchains to download and setup ARM toolchains, if the Processor SDK is not used.

In either of the above setups, the u-boot build commands in the next section will assume the below variables are set appropriately.

  • CROSS_COMPILE_64

  • CC_64

  • CROSS_COMPILE_32

Compiling R5 and ARM64 images

Use the following table to determine what defconfig to use to configure with:

Board

SD / eMMC / UART / OSPI Boot

USB DFU

USB MSC

AM62X SK

am62x_evm_r5_defconfig am62x_evm_a53_defconfig

am62x_evm_r5_usbdfu_defconfig am62x_evm_a53_defconfig

am62x_evm_r5_usbmsc_defconfig am62x_evm_a53_defconfig

AM62X LP SK

am62x_lpsk_r5_defconfig am62x_lpsk_a53_defconfig

am62x_lpsk_r5_usbdfu_defconfig am62x_lpsk_a53_defconfig

AM62SIP SK

am62x_evm_r5_defconfig am62xsip_sk_r5.config am62x_evm_a53_defconfig

Note

Where to get the sources:

$ export UBOOT_DIR=<path-to-ti-u-boot>
$ export TI_LINUX_FW_DIR=<path-to-ti-linux-firmware>
$ export TFA_DIR=<path-to-arm-trusted-firmware>
$ export OPTEE_DIR=<path-to-ti-optee-os>

Note

The instructions below assume all binaries are built manually. For instructions to build bl31.bin go to: OP-TEE. For instructions to build tee-pager_v2.bin (bl32.bin) go to: ARM Trusted Firmware-A. BINMAN_INDIRS can point to <path-to-tisdk>/board-support/prebuilt-images/am62xx-evm to use the pre-built binaries that come in the pre-built SDK (bl31.bin for BL31, bl32.bin for TEE).

$ cd $UBOOT_DIR

R5
To build tiboot3.bin. Saved in $UBOOT_DIR/out/r5.

For AM62X
$ make ARCH=arm CROSS_COMPILE="$CROSS_COMPILE_32" am62x_evm_r5_defconfig O=$UBOOT_DIR/out/r5
$ make ARCH=arm CROSS_COMPILE="$CROSS_COMPILE_32" O=$UBOOT_DIR/out/r5 BINMAN_INDIRS=$TI_LINUX_FW_DIR

For AM62X LP
$ make ARCH=arm CROSS_COMPILE="$CROSS_COMPILE_32" am62x_lpsk_r5_defconfig O=$UBOOT_DIR/out/r5
$ make ARCH=arm CROSS_COMPILE="$CROSS_COMPILE_32" O=$UBOOT_DIR/out/r5 BINMAN_INDIRS=$TI_LINUX_FW_DIR

For AM62SIP
NOTE: AM62SIP Uses config fragment model.
$ make ARCH=arm CROSS_COMPILE="$CROSS_COMPILE_32" am62x_evm_r5_defconfig am62xsip_sk_r5.config O=$UBOOT_DIR/out/r5
$ make ARCH=arm CROSS_COMPILE="$CROSS_COMPILE_32" O=$UBOOT_DIR/out/r5 BINMAN_INDIRS=$TI_LINUX_FW_DIR

A53
To build tispl.bin and u-boot.img. Saved in $UBOOT_DIR/out/a53. Requires bl31.bin, tee-pager_v2.bin

For AM62X or AM62SIP
$ make ARCH=arm CROSS_COMPILE="$CROSS_COMPILE_64" am62x_evm_a53_defconfig O=$UBOOT_DIR/out/a53
$ make ARCH=arm CROSS_COMPILE="$CROSS_COMPILE_64" CC="$CC_64" BL31=$TFA_DIR/build/k3/lite/release/bl31.bin TEE=$OPTEE_DIR/out/arm-plat-k3/core/tee-pager_v2.bin O=$UBOOT_DIR/out/a53 BINMAN_INDIRS=$TI_LINUX_FW_DIR

For AM62X LP
$ make ARCH=arm CROSS_COMPILE="$CROSS_COMPILE_64" am62x_lpsk_a53_defconfig O=$UBOOT_DIR/out/a53
$ make ARCH=arm CROSS_COMPILE="$CROSS_COMPILE_64" CC="$CC_64" BL31=$TFA_DIR/build/k3/lite/release/bl31.bin TEE=$OPTEE_DIR/out/arm-plat-k3/core/tee-pager_v2.bin O=$UBOOT_DIR/out/a53 BINMAN_INDIRS=$TI_LINUX_FW_DIR

Note

BINMAN_INDIRS is used to fetch the DM binary from <path to ti-linux-firmware>/ti-dm/ and SYSFW binaries from <path to ti-linux-firmware>/ti-sysfw/. If using the SDK, BINMAN_INDIRS can point to <path to SDK>/board-support/prebuilt-images. Else any folder where DM is located in <path to folder>/ti-dm/ and SYSFW binaries are present in <path to folder>/ti-sysfw/ can be used. Please make sure to use the absolute path.

Note

It is also possible to pick up a custom DM binary by adding TI_DM argument pointing to the file. If not provided, it defaults to picking up the DM binary from BINMAN_INDIRS. This is only applicable to devices that utilize split firmware.

Target Images

Copy the below images to the boot partition of an SD card and boot. Instructions to format the SD card can be found here.

  • GP

    • tiboot3-am62x-gp-evm.bin from <output directory>/r5

    • tispl.bin_unsigned, u-boot.img_unsigned from <output directory>/a53

  • HS-FS

    • tiboot3-am62x-hs-fs-evm.bin from <output directory>/r5

    • tispl.bin, u-boot.img from <output directory>/a53

  • HS-SE

    • tiboot3-am62x-hs-evm.bin from <output directory>/r5

    • tispl.bin, u-boot.img from <output directory>/a53

3.1.1.1.3. Image Formats

  • tiboot3.bin:

+-----------------------+
|        X.509          |
|      Certificate      |
| +-------------------+ |
| |                   | |
| |        R5         | |
| |   u-boot-spl.bin  | |
| |                   | |
| +-------------------+ |
| |                   | |
| |TIFS with board cfg| |
| |                   | |
| +-------------------+ |
| |                   | |
| |                   | |
| |     FIT header    | |
| | +---------------+ | |
| | |               | | |
| | |   DTB 1...N   | | |
| | +---------------+ | |
| +-------------------+ |
+-----------------------+
  • tispl.bin

+-----------------------+
|                       |
|       FIT HEADER      |
| +-------------------+ |
| |                   | |
| |      A53 ATF      | |
| +-------------------+ |
| |                   | |
| |     A53 OPTEE     | |
| +-------------------+ |
| |                   | |
| |      R5 DM FW     | |
| +-------------------+ |
| |                   | |
| |      A53 SPL      | |
| +-------------------+ |
| |                   | |
| |   SPL DTB 1...N   | |
| +-------------------+ |
+-----------------------+

3.1.1.1.4. Boot Flow

On K3 architecture based devices, ROM supports boot only via MCU(R5). This means that bootloader has to run on R5 core. In order to meet this constraint, keeping safety in picture and to have faster boot time, the software boot architecture is designed as below:

+------------------------------------------------------------------------+
|        TIFS            |      Main R5          |        A53            |
+------------------------------------------------------------------------+
|    +--------+          |                       |                       |
|    |  Reset |          |                       |                       |
|    +--------+          |                       |                       |
|         :              |                       |                       |
|    +--------+          |   +-----------+       |                       |
|    | *ROM*  |----------|-->| Reset rls |       |                       |
|    +--------+          |   +-----------+       |                       |
|    |        |          |         :             |                       |
|    |  ROM   |          |         :             |                       |
|    |services|          |         :             |                       |
|    |        |          |   +-------------+     |                       |
|    |        |          |   |  *R5 ROM*   |     |                       |
|    |        |          |   +-------------+     |                       |
|    |        |<---------|---|Load and auth|     |                       |
|    |        |          |   | tiboot3.bin |     |                       |
|    +--------+          |   +-------------+     |                       |
|    |        |<---------|---| Load sysfw  |     |                       |
|    |        |          |   | part to TIFS|     |                       |
|    |        |          |   | core        |     |                       |
|    |        |          |   +-------------+     |                       |
|    |        |          |         :             |                       |
|    |        |          |         :             |                       |
|    |        |          |         :             |                       |
|    |        |          |   +-------------+     |                       |
|    |        |          |   |  *R5 SPL*   |     |                       |
|    |        |          |   +-------------+     |                       |
|    |        |          |   |    DDR      |     |                       |
|    |        |          |   |   config    |     |                       |
|    |        |          |   +-------------+     |                       |
|    |        |          |   |    Load     |     |                       |
|    |        |          |   |  tispl.bin  |     |                       |
|    |        |          |   +-------------+     |                       |
|    |        |          |   |   Load R5   |     |                       |
|    |        |          |   |   firmware  |     |                       |
|    |        |          |   +-------------+     |                       |
|    |        |<---------|---| Start A53   |     |                       |
|    |        |          |   | and jump to |     |                       |
|    |        |          |   | DM fw image |     |                       |
|    |        |          |   +-------------+     |                       |
|    |        |          |                       |     +-----------+     |
|    |        |----------|-----------------------|---->| Reset rls |     |
|    |        |          |                       |     +-----------+     |
|    |  TIFS  |          |                       |          :            |
|    |Services|          |                       |     +-----------+     |
|    |        |<---------|-----------------------|---->|*ATF/OPTEE*|     |
|    |        |          |                       |     +-----------+     |
|    |        |          |                       |          :            |
|    |        |          |                       |     +-----------+     |
|    |        |<---------|-----------------------|---->| *A53 SPL* |     |
|    |        |          |                       |     +-----------+     |
|    |        |          |                       |     |   Load    |     |
|    |        |          |                       |     | u-boot.img|     |
|    |        |          |                       |     +-----------+     |
|    |        |          |                       |          :            |
|    |        |          |                       |     +-----------+     |
|    |        |<---------|-----------------------|---->| *U-Boot*  |     |
|    |        |          |                       |     +-----------+     |
|    |        |          |                       |     |  prompt   |     |
|    |        |----------|-----------------------|-----+-----------+-----|
|    +--------+          |                       |                       |
|                        |                       |                       |
+------------------------------------------------------------------------+

Here TIFS acts as master and provides all the critical services. R5/ARM64 requests TIFS to get these services done as shown in the above diagram.

3.1.1.1.5. U-Boot Environment

Note

SDK 9.0 will not default to the environments that are saved on the boards, It will default to the ones that are given with the particular uboot in the release.

By default the SDK builds will have the default environments whenever being run, to have some custom environments, one needs to rely on uEnv.txt file.

The added benefit of using uEnv.txt is that it is more granular than the saveenv counterpart as we can choose to store the variables that are actually being set during the development workflow.

Writing to MMC/EMMC

=> env export -t $loadaddr <list of variables>
=> fatwrite mmc ${mmcdev} ${loadaddr} ${bootenvfile} ${filesize}

The following will update the uEnv.txt file on the bootmedia and then whenever “run envboot” is run on the board, uEnv.txt will be read based on mmcdev value to be read either from emmc/sd card.

You can specifically choose the variables that you are changing in your development process so that the other variables are not affected due to the whole environment being saved. Optionally, one can save the full environment too in uEnv.txt by not specifying <list of variables> this will have some issues with the ethernet mac addresses not being overridden but other things will be set.

Reading from MMC/EMMC

By default run envboot will read it from the MMC/EMMC partition ( based on mmcdev) and set the environments.

If manually needs to be done then the environment can be read from the filesystem and then imported

=> fatload mmc ${mmcdev} ${loadaddr} ${bootenvfile}
=> env import -t ${loadaddr} ${filesize}

For production environments if one needs to rely on saveenv counterpart then they can always refer to the commit

Networking Environment

When using a USB-Ethernet dongle a valid MAC address must be set in the environment. To create a valid address please read **this page**. Then issue the following command:

=> setenv usbethaddr value:from:link:above

You can use the printenv command to see if usbethaddr is already set.

Then start the USB subsystem:

=> usb start

The default behavior of U-Boot is to utilize all information that a DHCP server passes to us when the user issues the dhcp command. This will include the dhcp parameter next-server which indicates where to fetch files from via TFTP. There may be times however where the dhcp server on your network provides incorrect information and you are unable to modify the server. In this case the following steps can be helpful:

=> setenv autoload no
=> dhcp
=> setenv serverip correct.server.ip
=> tftp

Another alternative is to utilize the full syntax of the tftp command:

=> setenv autoload no
=> dhcp
=> tftp ${loadaddr} server.ip:fileName

3.1.1.1.6. Available RAM for image download

To know the amount of RAM available for downloading images or for other usage, use bdinfo command.

=> bdinfo
arch_number = 0x00000000
boot_params = 0x80000100
DRAM bank   = 0x00000000
-> start    = 0x80000000
-> size     = 0x7F000000
baudrate    = 115200 bps
TLB addr    = 0xFEFF0000
relocaddr   = 0xFEF30000
reloc off   = 0x7E730000
irq_sp      = 0xFCEF8880
sp start    = 0xFCEF8870
Early malloc usage: 890 / 2000

After booting, U-Boot relocates itself (along with its various reserved RAM areas) and places itself at end of available RAM (starting at relocaddr in bdinfo output above). Only the stack is located just before that area. The address of top of the stack is in sp start in bdinfo output and it grows downwards. Users should reserve at least about 1MB for stack, so in the example output above, RAM in the range of [0x80000000, 0xFCE00000] is safely available for use.

3.1.1.1.7. Device Trees

A note about device trees. Now all supported boards are required to use a device tree to boot. To facilitate this in supported platforms, a command in U-Boot environment findfdt is available that will set the fdtfile variable to the name of the device tree to use, as found with the kernel sources. In the Keystone-2 family devices (K2H/K/E/L/G), it is specified by name_fdt variable for each platform. The device tree is expected to be loaded from the same media as the kernel, and from the same relative path.

3.1.1.1.8. SRAM memory Layout during R5 SPL bootloader stage

The SRAM memory layout explains the memory used for Bootloader’s operation.

┌──────────────────────────────────────┐0x43c00000
│                                      │
│                                      │
│               SPL IMAGE              │
│           (Max size 192 KB)          │
│            (excluding BSS)           │
│             (196608B  Max)           │
│                                      │
├──────────────────────────────────────┤0x43c30000
│                                      │
│                                      │
│            STACK (13568B Max)        │
│                                      │
│                                      │
├──────────────────────────────────────┤
│         Global Data (428B Max)       │
├──────────────────────────────────────┤
│                                      │
│            HEAP (28KB Max)           │
│                                      │
├──────────────────────────────────────┤0x43c3a7f0
│                                      │
│             EMPTY (16B)              │
│                                      │
├──────────────────────────────────────┤0x43c3a800
│                                      │
│                                      │
│         DM config data (2KB)         │
│                                      │
│                                      │
├──────────────────────────────────────┤0x43c3b000
│                                      │
│             BSS (12KB)               │
│                                      │
├──────────────────────────────────────┤0x43c3e000
│                                      │
│                                      │
│           EMPTY (4.5KB)              │
│        (Reserved for ROM)            │
│                                      │
├──────────────────────────────────────┤0x43c3f1e0
│                                      │
│       ROM Boot parameter table       │
│    + Extended boot info (3.5 KB)     │
│                                      │
└──────────────────────────────────────┘0x43c3ffff