Skip to main content

Yocto Linux BSP Ver.F User Guide for i.MX8 Series — Yocto 5.0 (Scarthgap)

Introduction​

This document describes how to set up the build environment, fetch the BSP, build images, create bootable media, and customize software for Advantech boards based on NXP i.MX8 series. It targets BSP Version F aligned with NXP release L6.6.23-2.0.0 (Yocto 5.0 scarthgap).

Getting Started

System Requirements​

  • CPU Cores: Quad-core processor (or higher recommended)
  • Memory: 8 GB RAM (more is recommended for better performance)
  • Disk Space: 400 GB (more is recommended; SSD suggested for better performance)

Conventions​

  • ${PREBUILT_IMAGE} — compressed prebuilt image (*.img.gz)

  • ${CONTAINER_NAME} — container name (e.g., imx8LBVD0027)

  • ${BSP_TARBALL} — BSP tarball (*.tgz)

  • ${BSP_HOME} — BSP root directory inside the container

  • ${BDIR} — build directory (e.g., build_xwayland)

  • ${MX8PROC} — i.MX8 processor short code:

    • mx8mq for i.MX8M Dual Core
    • mx8mm for i.MX8MM
    • mx8mp for i.MX8MP
    • mx8qm for i.MX8QM
    • mx8qxp for i.MX8QXP
    • mx8ulp for i.MX8ULP

  • ${IMX8PROC} — i.MX8 processor code: imx8mq / imx8mm / imx8qm / imx8qxp / imx8mp / imx8ulp

  • ${BOARD} — target board: rom5720, rom5721, rom7720, rom5620, rom3620, rom5722, rsb3720, rom2620, rsb3730

  • ${BOARD_REV} — board revision (e.g., a1)

  • ${MC} — machine code = ${IMX8PROC}${BOARD}${BOARD_REV}

    Examples:

    imx8mqrom5720a1   → ROM-5720 A1
    imx8qmrom7720a1   → ROM-7720 A1
    imx8qxprom5620a1  → ROM-5620 A1
    imx8qxprom3620a1  → ROM-3620 A1
    imx8mmrom5721a1   → ROM-5721 A1
    imx8mprom5722a2   → ROM-5722 A1
    imx8mprsb3720a1   → RSB-3720 A1
    imx8mprsb3720a2   → RSB-3720 A2  ← (used this version)
    imx8ulprom2620a1  → ROM-2620 A1
    imx8mmrsb3730a2   → RSB-3730 A2

    You can also list supported machines after sourcing the environment:

    $ source setup-environment

  • ${MEM_SIZE} — memory size: 1G / 2G / 4G / 6G

  • ${UC} — U-Boot config: 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} — SD card image built by bitbake (*.wic.zst)

  • ${WORKSPACE} — host workspace folder mapped into the container

  • ${UBOOT} — U-Boot version (e.g., v2024.04_6.6.23_2.0.0)

  • ${KERNEL} — Linux kernel version (e.g., 6.6.23_2.0.0)

  • ${TOOLCHAIN} — toolchain base (e.g., /opt/fsl-imx-wayland/6.1-mickledore/environment)

Debug/Serial console: use a terminal tool (minicom/putty/teraterm) configured to 115200 8N1. Terminal console: any terminal emulator (gnome-terminal, xfce4-terminal, etc.).

Docker Install and Settings​

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

Install Docker Engine​

Refer to the official Docker installation guide for your platform.

Pull Base Image from Docker Hub​

$ docker pull advrisc/u20.04-imx8lbv1

Pulls the Ubuntu 20.04 image used as the build base.

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 the Advantech Yocto BSP into adv-release-bsp and checks out scarthgap / 6.6.23-2.0.0:

$ 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 git://github.com/ADVANTECH-Corp/adv-arm-yocto-bsp.git \
            -b imx-linux-scarthgap \
            -m adv-6.6.23-2.0.0.xml
$ repo sync

Troubleshooting:​

  • "server certificate verification failed" (self-signed certs):
export GIT_SSL_NO_VERIFY=1
# or
git config --global http.sslverify false
  • "The unauthenticated git protocol on port 9418 is no longer supported.":
git config --global url."https://".insteadOf git://

Method B — Copy BSP Tarball into the Container​

If you have a BSP tarball (e.g., imx8LBVD0027_2023-10-25.tgz), copy it into the container workspace.

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

During Yocto builds, a downloads/ folder caches sources. To reduce fetch failures, reuse a prepared archive (e.g., downloads_imx9_6.6.36_2.1.0.tar.gz).

You can get the Downloads tarball from the following URL: downloads_imx9_6.6.36_2.1.0.tar

  1. Exit to host:
exit
  1. Copy into ${WORKSPACE} and fix ownership:
cp downloads_imx9_6.6.36_2.1.0.tar ${WORKSPACE}
sudo chown adv:adv ${WORKSPACE}/downloads_imx9_6.6.36_2.1.0.tar
  1. Re-attach to the container:
docker start ${CONTAINER_NAME}
docker attach ${CONTAINER_NAME}
  1. Unpack:
tar zxvf downloads_imx9_6.6.36_2.1.0.tar
  1. Link into the BSP tree:
cd adv-release-bsp
ln -s ${WORKSPACE}/downloads_imx9_6.6.36_2.1.0 downloads

Introducing BSP​

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

  • sources/ — Yocto layers (community + NXP + Advantech)
  • one or more build directories
  • scripts to set up the environment

Naming Rule​

  • BSP file name: imx8LBVD0027_YYYY-MM-DD.tgz
    • LB = Linux BSP
    • VD0027 = Version D.0027
  • Prebuilt image name: 3720A2AIM36LIVD0027_iMX8MP_6G_YYYY-MM-DD.img.gz
    • 3720A2 = RSB-3720 A2
    • LI = prebuilt Linux Image
    • 6G = 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 environment
  • setup-environment — continue an existing build environment

Build Instructions

Create a New Build Environment​

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

To set a default U-Boot config during creation:

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

Examples for RSB-3720 A2:

# 6G version
MACHINE=imx8mprsb3720a2 UBOOT_CONFIG=6G DISTRO=fsl-imx-xwayland source imx-setup-release.sh -b build_x11

# 4G version
MACHINE=imx8mprsb3720a2 UBOOT_CONFIG=4G DISTRO=fsl-imx-xwayland source imx-setup-release.sh -b build_x11

# 2G version
MACHINE=imx8mprsb3720a2 UBOOT_CONFIG=2G DISTRO=fsl-imx-xwayland source imx-setup-release.sh -b build_x11

You need to read and accept the EULA when prompted.

Accept EULA

Continue an Existing Build Environment​

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

Build SD Card Image​

bitbake imx-image-full

Results (upon success) in ./tmp/deploy/images/${MC}:

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

Build Toolchain Installer (SDK)​

SDK includes Qt:

bitbake imx-image-full -c populate_sdk

Or build the base toolchain:

bitbake meta-toolchain

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

fsl-imx-wayland-glibc-x86_64-meta-toolchain-armv8a-imx8mp-lpddr4-evk-toolchain-${KERNEL}-scarthgap.sh

Build Bootloader​

bitbake imx-boot

Build Linux Kernel​

If you are in Docker, install tmux before running menuconfig:

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

Build the kernel:

bitbake linux-imx

Resulting files under ./tmp/deploy/images/${MC}:

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

Compile Error Exception Handling​

Case 1: Vulkan-Loader​

Change directory to the vulkan meta-layer folder:

$ cd ${BSP_HOME}/sources/meta-freescale/recipes-downgrade/vulkan/

Modify the vulkan-loader bb file to change the SRC_URL branch name from master to main:

$ vim vulkan-loader_1.2.182.0.bb

Case 2: nnshark​

(TBD)

Creating Boot Media

From a Prebuilt Image​

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

# gunzip -c ${PREBUILT_IMAGE} | dd of=${SD_DEVICE} bs=1M
# sync

From a Built SD Card Image​

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

One-Step Build Image​

Your machine must have Docker pre-installed. Download the build script:

$ wget https://raw.githubusercontent.com/ADVANTECH-Corp/RISC_tools_scripts/mickledore/imx8/adv_imx8_build.sh
$ sudo chmod a+x adv_imx8_build.sh

Build the image:

$ sudo ./adv_imx8_build.sh ${BOARD}
# e.g.
$ sudo ./adv_imx8_build.sh rom5720

The output image will be in:

workspace/${BDIR}/tmp/deploy/images/${MC}

Then follow the Creating Boot Media from Built SD Card Image section.

Debug Console Information

If you want to see bootloader/kernel messages, prepare the following.

Hardware​

  • Refer to your product's Debug Port Information for the connector location and pinout.

Software​

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

Customization

Setting up SDK​

Build the SDK as described above, then run the installer:

cd ${BSP_HOME}/${BDIR}/tmp/deploy/sdk
sudo ./fsl-imx-xwayland-glibc-x86_64-meta-toolchain-armv8a-imx8mprsb3720a2-toolchain-6.6-scarthgap.sh

Follow prompts: choose install path or press Enter for default, then confirm Proceed [y/n]?.

Reference SDK download: downloads_SDK

Setting up SDK

Setting up Cross-Compiling Environment​

After SDK installation, source the toolchain environment:

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

Build U-Boot in a Standalone Environment​

Configure U-Boot​

make ${IMX8PROC}_${BOARD}${BOARD_REV}_${MEM_SIZE}_defconfig
# e.g.
make imx8mp_rsb3720a2_6G_defconfig

Build U-Boot​

make -j4

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

Obtain the imx-boot tarball for your product (example for RSB-3720 A2):

tar zxvf 3720A2AIM36LIVD0027_iMX8MP_6G_imx-boot.tgz
cd 3720A2AIM36LIVD0027_iMX8MP_6G_imx-boot/

The folder contains two scripts. Copy necessary files to the imx-mkimage folder:

./cp_uboot.sh ${uboot_path} ${IMX8PROC}

Make the imx-boot image:

./mk_imx-boot.sh ${IMX8PROC}

Example for i.MX8MP:

./cp_uboot.sh ../uboot-imx imx8mp
./mk_imx-boot.sh imx8mp

Replace imx-boot​

Write to on-board flash:

$ dd if=flash.bin of=/dev/mmcblk0 bs=1K seek=<offset> conv=fsync

Where <offset> is:

  • 33 — for i.MX8QuadMax A0, i.MX8QuadXPlus A0, i.MX8M Quad, i.MX8M Mini
  • 32 — for i.MX8M Plus, i.MX8QuadXPlus B0/C0, i.MX8QuadMax B0, i.MX8ULP

Building & Updating Kernel / Modules / DTB Manually​

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

Get Linux-imx Sources​

Copy the kernel tarball to ${WORKSPACE}, re-attach to container, fix ownership, and unpack:

$ sudo chown adv:adv imx8LBVD0027_2023-10-25_linux-imx.tgz
$ tar zxvf imx8LBVD0027_2023-10-25_linux-imx.tgz

Configure the Kernel​

cd linux-imx
make distclean
make imx_v8_adv_defconfig
make menuconfig

Build Kernel Image​

make -j4 Image

If you encounter link-flags issues:

unset LDFLAGS
make -j4 Image

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

Build Kernel Modules​

make -j4 modules
make modules_install INSTALL_MOD_PATH=~/temp/rootfs

Build Device Tree Blob​

make -j4 freescale/${IMX8PROC}-${BOARD}-${BOARD_REV}.dtb
# e.g.
make -j4 freescale/imx8mp-rsb3720-a2.dtb

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

Replace Kernel & DTB on Target Media​

  • Copy Image to the appropriate partition on SD card or eMMC.
  • Copy ${IMX8PROC}-${BOARD}-${BOARD_REV}.dtb to the device's DTB directory on SD card or eMMC.

Improve Boot Speed

Bootloader​

  1. Boot delay

Disable boot delay in U-Boot:

setenv bootdelay 0
env save
reset
  1. Disable console output

Reducing console messages accelerates boot.

  • Kernel quiet mode in bootargs:
setenv mmcargs setenv bootargs ${jh_clk} console=${console} modprobe.blacklist=${modprobe.blacklist} root=${mmcroot} video=HDMI-A-1:${videores} quiet
env save
reset
  • Or disable the debug port entirely:
setenv console
env save
reset

Rootfs​

(TBD)

Services​

Disable unneeded services:

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

System Recovery

This section provides detailed procedures for restoring the eMMC image.

For more information, refer to the NXP mfgtools (UUU) wiki.

Reflash eMMC from Boot SD Card​

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

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

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

  4. Run mksd-linux.sh and follow on-screen prompts to reflash from SD to eMMC.

How to Read MAC, Serial Number, and Manufacture Date from QSPI Flash

MAC Address 0​

READ_DATA=`dd if=/dev/mtdblock0 bs=1 skip=$((0xd0000)) count=6 2> /dev/null | hexdump -e '16/1 "%02x " "\n"' | sed 's/ /:/g' | cut -c 1-17`
echo $READ_DATA

MAC Address 1​

READ_DATA=`dd if=/dev/mtdblock0 bs=1 skip=$((0xd0400)) count=6 2> /dev/null | hexdump -e '16/1 "%02x " "\n"' | sed 's/ /:/g' | cut -c 1-17`
echo $READ_DATA

Serial Number​

READ_DATA=`dd if=/dev/mtdblock0 bs=1 skip=$((0xd0006)) count=10 2> /dev/null | cut -c 1-10`
echo $READ_DATA

Manufacture Date​

READ_DATA=`dd if=/dev/mtdblock0 bs=1 skip=$((0xd0010)) count=14 2> /dev/null | cut -c 1-14`
READ_DATA=`echo $READ_DATA | cut -c 1-4`-`echo $READ_DATA | cut -c 5-6`-`echo $READ_DATA | cut -c 7-8`_`echo $READ_DATA | cut -c 9-10`-`echo $READ_DATA | cut -c 11-12`-`echo $READ_DATA | cut -c 13-14`
echo $READ_DATA

Document version: Ver.F (Yocto 5.0 — scarthgap, kernel 6.6.23-2.0.0, i.MX8 series).