Skip to main content

Yocto Linux BSP Ver.D User Guide for i.MX9 Series — Yocto 4.2

Introduction​

This document describes how to set up the build environment, fetch the BSP, build images, and customize software for Advantech boards based on NXP i.MX9 series (e.g., i.MX93). It targets BSP Version D aligned with NXP release L6.1.36-2.1.0 (Yocto 4.2 mickledore).

Getting Started

System Requirements​

  • CPU Cores: Intel® Core™ i7 (≥ 8 cores)
  • Memory: ≥ 16 GB
  • Disk Space: ≥ 500 GB (SSD strongly recommended)

Conventions​

  • ${PREBUILT_IMAGE} — compressed prebuilt image (*.img.gz)
  • ${CONTAINER_NAME} — container name (e.g., imx9LBVD0027)
  • ${BSP_TARBALL} — BSP tarball (*.tgz)
  • ${BSP_HOME} — BSP root directory
  • ${BDIR} — build directory (e.g., build_xwayland)
  • ${IMX9PROC} — i.MX9 processor code (e.g., imx93 for i.MX93)
  • ${BOARD} — target board (e.g., rom2820)
  • ${BOARD_REV} — board revision (e.g., a1)
  • ${MC} — machine code = ${IMX9PROC}${BOARD}${BOARD_REV}
    Example: imx93rom2820a1 for ROM‑2820 A1
  • ${MEM_SIZE} — memory size (one of: 1G / 2G / 4G / 6G)
  • ${UC} — U‑Boot config (e.g., 1G / 2G / 4G / 6G / FSPI_1G / FSPI_2G / FSPI_4G / FSPI_6G ...)
  • ${SD_DEVICE} — SD device path on host Linux (e.g., /dev/sdf)
  • ${SDCARD_IMAGE} — SDCard image built by bitbake (*.wic.zst)
  • ${WORKSPACE} — host workspace folder mapped into the container
  • ${UBOOT} — U‑Boot version (e.g., v2023.04_6.1.36-2.1.0)
  • ${KERNEL} — Linux kernel version (e.g., 6.1.36-2.1.0)
  • ${TOOLCHAIN} — toolchain install base (e.g., /opt/fsl-imx-wayland/6.1-mickledore)

Debug console / serial console — Use a terminal tool (minicom/putty/teraterm) configured to 115200 8N1.
Terminal console — Any terminal emulator (gnome-terminal, xfce4-terminal, etc.).

You can list supported machines after sourcing the environment:

$ source setup-environment

Docker Install and Settings​

If Docker is not available on your system, please install it first.

1) Install Docker Engine​

Refer to the official Docker installation guide for your platform.

2) Pull base image (example)​

$ docker pull advrisc/u20.04-imx8lbv1

Note: The example image name may reference i.MX8; it remains suitable as a general Ubuntu 20.04 base for i.MX9 BSP builds.

3) Create a container​

$ docker run --privileged -it \
  --name ${CONTAINER_NAME} \
  -v ${WORKSPACE}:/home/adv/adv-release-bsp \
  -v /dev:/dev \
  advrisc/u20.04-imx8lbv1 /bin/bash

Get BSP​

You can obtain the BSP in two ways.

Method A — Download BSP from GitHub​

The following example downloads Advantech Yocto BSP into a project directory adv-release-bsp:

$ git config --global user.name "Your Name"
$ git config --global user.email you@example.com
$ sudo chown adv:adv adv-release-bsp
$ cd adv-release-bsp
$ repo init -u https://github.com/ADVANTECH-Corp/adv-arm-yocto-bsp.git \
            -b imx-linux-mickledore \
            -m adv-6.1.36-2.1.0.xml
$ repo sync

Troubleshooting tips:

  • If you see “server certificate verification failed”, you can temporarily disable SSL verification (for self‑signed certs) — only as a last resort:

    export GIT_SSL_NO_VERIFY=1
    # or
    git config --global http.sslverify false

  • If you see “The unauthenticated git protocol on port 9418 is no longer supported.”, use:

    git config --global url."https://".insteadOf git://

Method B — Copy BSP tarball into the Container​

If you already have a BSP tarball (e.g., imx9LBVD0042_2024-05-26.tgz), copy it into the container workspace.

  1. Exit container to host:
exit
  1. Copy tarball into ${WORKSPACE} and fix ownership:
cp imx9LBVD0042_2024-05-26.tgz ${WORKSPACE}
sudo chown adv:adv ${WORKSPACE}/imx9LBVD0042_2024-05-26.tgz
  1. Re‑attach to the container:
docker start ${CONTAINER_NAME}
docker attach ${CONTAINER_NAME}
  1. Unpack inside the container:
tar zxvf imx9LBVD0042_2024-05-26.tgz

During Yocto builds, a downloads/ folder is created to cache sources. To reduce fetch failures, you can reuse a prepared archive, e.g., downloads_y40_6.1.36.tar.gz.

  1. Exit to host:
exit
  1. Copy the downloads tarball into ${WORKSPACE}:
cp downloads_y40_6.1.36.tar.gz ${WORKSPACE}
sudo chown adv:adv ${WORKSPACE}/downloads_y40_6.1.36.tar.gz
  1. Re‑attach to the container:
docker start ${CONTAINER_NAME}
docker attach ${CONTAINER_NAME}
  1. Unpack:
tar zxvf downloads_y40_6.1.36.tar.gz
  1. Link it into the BSP tree:
cd adv-release-bsp
ln -s ${WORKSPACE}/downloads_y40_6.1.36 downloads

Introducing the BSP​

The BSP is based on the Yocto Project with NXP (Freescale) enhancements for i.MX93, plus Advantech board support. The top‑level directory contains:

  • sources/ — all Yocto layers (community + NXP + Advantech)
  • build directories — one or more per configuration
  • helper scripts for environment setup

Naming Rule​

  • BSP file name: imx9LBVD0042_YYYY-MM-DD.tgz
    • LB = Linux BSP
    • VD0042 = Version D, build 0042
  • Prebuilt image name: 2820A1AIM36LIVD0042_iMX93_2G_YYYY-MM-DD.img.gz
    • 2820A1 = ROM‑2820 A1
    • LI = Linux Image (prebuilt)
    • 2G = DDR size

BSP Content (key items)​

  • sources/meta-advantech/ — Advantech meta‑layer
  • sources/meta-fsl-* — NXP (Freescale) meta‑layers
  • fsl-setup-release.sh — create a new build env
  • setup-environment — resume an existing build env

Build Instructions​

Create a New Build Environment​

cd ${BSP_HOME}
MACHINE=${MC} DISTRO=fsl-imx-xwayland source imx-setup-release.sh -b ${BDIR}

To specify a default U‑Boot config at creation time:

MACHINE=${MC} UBOOT_CONFIG=${UC} DISTRO=fsl-imx-xwayland source imx-setup-release.sh -b ${BDIR}

You will be prompted to accept the EULA.

Accept EULA

Continue an Existing Build Environment​

cd ${BSP_HOME}
source setup-environment ${BDIR}

Build SDCard Image​

bitbake imx-image-full

When complete, you will find:

  • imx-image-full-${MC}.wic.zst
  • imx-image-full-${MC}.wic.bmap

in: ./tmp/deploy/images/${MC}

Build Toolchain Installer (SDK)​

bitbake meta-toolchain

The installer will be in ./tmp/deploy/sdk/, e.g.:

fsl-imx-wayland-glibc-x86_64-meta-toolchain-armv8a-imx93rom2820a1-toolchain-${KERNEL}-mickledore.sh

Build Bootloader​

bitbake imx-boot

Build Linux Kernel​

If building inside Docker, install tmux so you can run menuconfig safely:

sudo apt-get update
sudo apt-get install -y tmux
tmux
bitbake linux-imx -c menuconfig
# After configuration, exit the tmux window:
exit

Build the kernel:

bitbake linux-imx

Resulting files:

  • Image
  • Image-${IMX9PROC}-${BOARD}-${BOARD_REV}.dtb

Both under: ./tmp/deploy/images/${MC}

Creating Bootable Media from a Prebuilt Image​

Create a Boot SD Card (from prebuilt image)​

Warning: Double‑check ${SD_DEVICE} before running dd.

sudo sh -c 'gunzip -c ${PREBUILT_IMAGE} | dd of=${SD_DEVICE} bs=1M status=progress'
sync

Creating Bootable Media from a Built SDCard Image​

Create a Boot SD Card (from ${SDCARD_IMAGE})​

pushd ${BSP_HOME}/${BDIR}/tmp/deploy/images/${MC}
zstd -cd ${SDCARD_IMAGE} | sudo dd of=${SD_DEVICE} bs=1M status=progress
# Or, faster with bmaptool:
sudo bmaptool copy --bmap ${SDCARD_IMAGE/.zst/.bmap} ${SDCARD_IMAGE} ${SD_DEVICE}
sync
popd

Debug Console Information​

If you need boot logs and kernel messages, prepare:

Hardware​

  • Please refer to your product’s Debug Port Information (connector location and pinout).

Software​

  • Use a serial terminal such as minicom or putty.
  • Baud rate: 115200

Customization

Setting up SDK​

Follow Build Toolchain Installer (SDK) to generate the installer, then run:

cd ${BSP_HOME}/${BDIR}/tmp/deploy/sdk
sudo ./fsl-imx-wayland-glibc-x86_64-meta-toolchain-armv8a-imx93rom2820a1-toolchain-6.1-mickledore.sh

When prompted, choose or confirm the installation directory and proceed.

Download SDK Link (for reference only): [downloads_SDK]

Setting up SDK

Setting up Cross‑Compiling Environment​

After SDK installation, source the environment:

source ${TOOLCHAIN}/environment-setup-aarch64-poky-linux

Build U‑Boot in a Standalone Environment​

Configure U‑Boot​

make ${IMX9PROC}_${BOARD}${BOARD_REV}_${MEM_SIZE}_defconfig
# e.g.
make imx93_rom2820a1_2G_defconfig

Build U‑Boot​

make -j$(nproc)

Build imx-boot Image using imx-mkimage (i.MX93)​

  1. Obtain the imx-boot tarball for your product (example for ROM‑2820):
tar zxvf 2820A1AIM36LIVD0042_iMX93_2G_imx-boot.tgz
cd 2820A1AIM36LIVD0042_iMX93_2G_imx-boot/
  1. Copy necessary artifacts into the imx-mkimage folder:
cp u-boot.bin spl/u-boot-spl.bin arch/arm/dts/imx93-rom2820-a1.dtb tools/mkimage \
   /path/to/imx-mkimage/iMX9/
  1. Build flash.bin:
cd /path/to/imx-mkimage
make SOC=iMX9 REV=A1 flash_singleboot

Flash imx-boot​

  • Using uuu to eMMC:
cp flash.bin ~/mfgtools/uuu/
cd ~/mfgtools/uuu
sudo ./uuu -b emmc flash.bin
  • Or writing raw to device (example uses /dev/sdd, adjust as needed):
sudo dd if=flash.bin of=/dev/sdd bs=1K seek=32 conv=fsync
sync

Building & Updating Kernel / Modules / DTB Manually​

Ensure your cross‑compile environment is sourced (see Setting up Cross‑Compiling Environment).

Get Linux‑imx Sources​

If not already available, download per your workflow (e.g., from Advantech/NXP). (Reference: [adv_6.1.36_2.1.0])

Configure the Kernel​

cd linux-imx
make distclean
make imx_v8_adv_defconfig
make menuconfig

Build Kernel Image​

make -j$(nproc) Image

If you hit link flags issues, try:

unset LDFLAGS
make -j$(nproc) Image

The kernel Image is at: ./arch/arm64/boot/

Build Kernel Modules​

make -j$(nproc) modules
make modules_install INSTALL_MOD_PATH=~/temp/rootfs

Build Device Tree Blob​

make -j$(nproc) freescale/${IMX9PROC}-${BOARD}-${BOARD_REV}.dtb
# e.g.
make -j$(nproc) freescale/imx93-rom2820-a1.dtb

DTBs are at: ./arch/arm64/boot/dts/freescale/

Replace Kernel & DTB on Target Media​

  • Copy Image to the appropriate /boot (or partition) on SD/eMMC.
  • Copy ${IMX9PROC}-${BOARD}-${BOARD_REV}.dtb to the device’s DTB directory on SD/eMMC.
    (Exact paths depend on your image layout and bootloader configuration.)

Improve Boot Speed​

Bootloader​

  1. Boot delay
    Disable boot delay in U‑Boot:
setenv bootdelay 0
saveenv
reset
  1. Disable console output
    Reducing console messages speeds boot.
  • Kernel quiet mode in bootargs (example):
setenv mmcargs 'setenv bootargs ${jh_clk} console=${console} modprobe.blacklist=${modprobe_blacklist} root=${mmcroot} video=HDMI-A-1:${videores} quiet'
saveenv
reset
  • Or disable console entirely:
setenv console
saveenv
reset

Rootfs​

TBD — optimize services and startup scripts per application.

Services​

Disable unneeded services:

sudo systemctl disable <service-name>
# e.g.
sudo systemctl disable boottimes

System Recovery

This section provides procedures to restore the eMMC image.

For more details, see the NXP mfgtools wiki (UUU).

Reflash eMMC from Boot SD Card​

  1. Download the mksd-linux.sh script:
    https://github.com/ADVANTECH-Corp/RISC_tools_scripts/blob/mickledore/imx8/mksd-linux.sh

  2. Download the "Product_AIM_Release_version"_flash_tool.tgz bundle and unzip it.

  3. Copy mksd-linux.sh into the mk_inand folder.

  4. Run mksd-linux.sh to prepare and flash from SD to eMMC (follow on‑screen prompts).

FreeRTOS (i.MX8ULP / i.MX9)

TBD — FreeRTOS bring-up notes and examples for i.MX93 (and references to i.MX8ULP when applicable).