Embedded module TQMLX2160A - YOCTO Linux BSP documentation


Memory Layout

Partitions

The following table shows the current memory layout:

SPI-NOR

start end content
0x0 0x100000 RCW-PBL
0x100000 0x300000 U-Boot
0x500000 0x600000 U-Boot-Env
0x800000 0xa00000 DDR-PHY
0xa00000 0xd00000 DPAA2-MC
0xd00000 0xe00000 DPAA2-DPL
0xe00000 0xf00000 DPAA2-DPC
0x1000000 0x8000000 RootFS UBI

eMMC / SD-Card

start content
0x1000 RCW-PBL
0x100000 U-Boot
0x800000 DDR-PHY
0x1000000 Boot Partition
0x3000000 RootFS ext4

Create SD-Card image

Create SD Card with BSP Image

The Yocto Scarthgap build generates a compressed .wic.zst image along with a corresponding .wic.bmap block map file. The image can be written to the SD Card efficiently using the bmaptool utility in Linux. This tool automatically handles the decompression and significantly speeds up the flashing process by skipping empty data blocks: 

$ cd <path to the deploy directory>
$ sudo bmaptool copy tq-image-generic-debug-tqmlx2160a-mblx2160a.rootfs.wic.zst /dev/sdc #Assuming the SD card is assigned to /dev/sdc

To identify the SD card in Linux the shell command dmesg can be used:

  1. Open a new terminal
  2. Execute the following command without plugged SD Card 
     $ dmesg | tail -n 15
  3. Insert SD Card and wait a few seconds
  4. Run the command from step two again 
    $ dmesg | tail -n 15 
 #plug in SD Card into the reader
$ dmesg | tail -n 15

Flash SPI-NOR

Write Bootloader to SPI-NOR Flash via Network

The onboard SPI-NOR flash can be updated directly from the U-Boot command line using the built-in update macros. This process downloads the required images from a TFTP server and flashes them automatically to the correct partitions.

Prerequisites

  • A TFTP server running on the host PC containing the bootloader files.
  • An active Ethernet connection between the STKLX2160A and the host PC.
  • The required bootloader files from the atf deploy directory (fip_uboot.bin and bl2_flexspi_nor.pbl).
Important: NOR_SWAP# Signal and SPI Target Selection
The module provides multiple SPI flash devices. Switch S1-4 controls the NOR_SWAP# signal, which determines the target SPI flash device for the update process.
  • Before flashing the SPI device, ensure the DIP switches are configured for SD-Card or eMMC boot mode.
  • Toggle S1-4 (ON or OFF) to select the desired SPI flash. The current state (enabled/disabled) can be verified on the MBLX2160 display under the S1 information page.
  • A power cycle is strictly required after changing the S1-4 switch position to apply the new routing.

Update via U-Boot (TFTP)

1. Copy the bootloader files from the atf directory inside the Yocto deploy space into the root directory of the TFTP server.

2. Power on the STKLX2160A and stop the autoboot process by pressing any key when prompted to enter the U-Boot shell (⇒).
3. Configure the network settings in U-Boot (adjust the IP addresses to match the local network): 

=> setenv ipaddr <Board-IP>
=> setenv serverip <Host-PC-IP>

4. Set the file names of the binaries to be updated: 

=> setenv uboot fip_uboot.bin
=> setenv pbl_spi bl2_flexspi_nor.pbl

5. Execute the pre-configured update macros to automatically download and flash the TF-A/U-Boot (FIP) and the Primary Boot Loader (PBL): 

# 1. Update TF-A / U-Boot
=> run update_uboot_spi
 
# 2. Update the Primary Boot Loader (RCW-PBL)
=> run update_pbl_spi
These commands will automatically probe the SPI flash, fetch the files via TFTP, and safely update the specific partitions defined for the TQMLX2160A.

6. Power off the STKLX2160A.
7. Set the STKLX2160A DIP switches to boot from SPI-NOR Flash (See DIP Switches S1).
8. Power on the STKLX2160A. The board should now boot directly from the SPI-NOR flash.

Copy Firmware from SD Card to eMMC

Write Image to eMMC using U-Boot

If no network connection is available, the eMMC can be flashed by loading the system image from a prepared SD card into the RAM, and writing it directly to the eMMC using U-Boot commands.

Prerequisites

  • An SD card flashed with the current BSP image (see section “Create SD-Card image”).
  • A serial console connection to the STKLX2160A.

Update via U-Boot (SD Card)

1. Set the STKLX2160A DIP switches to boot from the SD Card (See DIP Switches S1).
2. Power on the STKLX2160A and stop the autoboot process by pressing any key when prompted to enter the U-Boot shell (⇒).
3. Load the uncompressed image file (e.g., .wic) from the SD card into the RAM. Keep track of the number of bytes read (filesize), as this is required for the write command: 

=> load mmc 0:1 ${loadaddr} <image-name.wic>
 
# Example:
=> load mmc 0:1 ${loadaddr} tq-image-generic-debug-tqmlx2160a-mblx2160a.rootfs.wic

4. Switch the active MMC device to the eMMC (mmc 1): 

=> mmc dev 1
The command mmc info can be used to verify that the correct storage device (eMMC) is currently selected.

5. Calculate the block count required for the write command. The total size in bytes (from step 3) must be divided by the block length (usually 512 bytes). Convert the result to hexadecimal. *(Example: 663464960 Bytes / 512 = 1295830 blocks → Hex: 13C5D6)*

6. Write the image from the RAM directly to the eMMC: 

=> mmc write ${loadaddr} 0 <block-count-hex>
 
# Example using the calculated block count:
=> mmc write ${loadaddr} 0 13C5D6

7. Power off the STKLX2160A.
8. Set the STKLX2160A DIP switches to boot from eMMC (See DIP Switches S1).
9. Power on the STKLX2160A. The board should now boot directly from the eMMC.

Write Complete Image to eMMC

Flash Full .wic Image via Network (TFTP)

Because the system provides only a single active SDHC controller routing, it is not possible to directly copy data from an SD card to the eMMC. To write a complete .wic image to the eMMC, the image must be downloaded from a TFTP server (or USB drive) into the RAM first, and written to the eMMC afterwards.

Prerequisites

  • A TFTP server running on the host PC hosting the uncompressed .wic image.
  • The STKLX2160A must be booted from QSPI (SPI-NOR).
  • DIP switch S5-1 must be set to ON to select the eMMC as the active SDHC device.

Update Procedure via U-Boot

1. Calculate the block count required for the write command. Divide the total image size in bytes by the block length (512 bytes) and convert the result to hexadecimal. *(Example: Image size 466894848 Bytes / 512 = 911904 blocks → Hex: DEA20 → 0xDEA20)*

2. Power on the STKLX2160A and stop the autoboot process to enter the U-Boot shell (⇒).
3. Configure the network interface (e.g., via DHCP) and disable the U-Boot autoload feature: 

=> dhcp
=> setenv autoload no

4. Define the image name and the calculated hexadecimal block count: 

=> setenv wic_name <name-of-yocto-image.wic>
=> setenv wic_blk <calculated-hex-value>
 
# Example:
=> setenv wic_name tq-image-generic-debug-tqmlx2160a-mblx2160a.rootfs.wic
=> setenv wic_blk 0xDEA20

5. Define the custom U-Boot macro to automate the download and flash process. *(Note: Ensure the variable ${mmcdev} matches the eMMC device ID defined in the environment)*: 

=> setenv write_wic_emmc 'run set_getcmd; ${getcmd} ${wic_name}; mmc dev ${mmcdev}; mmc rescan; mmc write ${loadaddr} 0 ${wic_blk}'

6. Execute the newly created macro to load the data from TFTP into the RAM and write it to the eMMC: 

=> run write_wic_emmc

7. Power off the board, configure the DIP switches to boot from eMMC, and power cycle the system.

Using NFS Boot

Booting the System via Network (NFS)

To boot the TQMLX2160A over the network, a working bootloader must be present on the eMMC, SD-Card, or SPI-NOR flash. The bootloader will fetch the kernel image and device tree via TFTP and mount the Root File System (RootFS) via NFS.

Prerequisites

Configuration of U-Boot Environment

1. Power on the STKLX2160A and stop the autoboot process to enter the U-Boot shell (⇒).
2. Disable the U-Boot autoload feature to prevent unwanted automatic network boots during configuration: 

=> setenv autoload no

3. Configure the network interface. This can be done either manually or via DHCP:

Option A: Manual IP Configuration 

=> setenv serverip <TFTP/NFS-Server-IP>
=> setenv ipaddr <Board-IP>
=> setenv netmask <Network-Mask>

Option B: DHCP Configuration 

=> setenv serverip <TFTP/NFS-Server-IP>
=> dhcp

4. Set the necessary U-Boot variables to define the NFS root path, the device tree file, and the kernel image name: 

# Define the NFS export path on the host PC
=> setenv rootpath <path-to-nfs-root>
 
# Define the device tree and kernel file names matching the TFTP directory
=> setenv fdtfile <fdt-file-name.dtb>
=> setenv kernel <kernel-image-name>
Ensure that the specified NFS directory is properly exported in the /etc/exports file on the host PC running the NFS server.

5. Save the environment variables permanently (optional): 

=> saveenv

6. Execute the built-in U-Boot macro to start the network boot process: 

=> run netboot
The information provided on this wiki page is subject to change due to circumstances beyond our control. While we strive to keep all details as accurate and up-to-date as possible, it is possible that certain updates or changes may go unnoticed for some time. As a result, some sections of this page may contain outdated information. If you notice any mistakes in the documentation, we kindly ask you to inform the TQ Support through our ticket system.