Yocto Linux BSP Ver.B User Guide
Introduction
This document describes how to obtain, build, customize, and recover Advantech’s Yocto 3.3 (hardknott) BSP for i.MX8-based platforms.
Getting Started
Building Yocto Image — System Requirements
- CPU Cores: Quad‑core processor (or higher recommended)
- Memory: 8 GB RAM (more is recommended for better performance)
- Disk Space: 350 GB (SSD recommended for better performance)
Conventions
-
\${PREBUILT_IMAGE}— compressed prebuilt image (*.img.gz) -
\${CONTAINER_NAME}— container name (e.g.imx8LBVB0016) -
\${BSP_TARBALL}— BSP tarball (*.tgz) -
\${BSP_HOME}— home directory of the BSP -
\${BDIR}— build directory (e.g.build_x11) -
\${MX8PROC}— i.MX8 processormx8mqfor i.MX8M Quad/Dualmx8mmfor i.MX8MMmx8mpfor i.MX8MPmx8qmfor i.MX8QMmx8qxpfor i.MX8QXP
-
\${IMX8PROC}— shorthand processor string:imx8mq/imx8mm/imx8mp/imx8qm/imx8qxp -
\${BOARD}— available targets:rom5720rom5721rom7720rom5620rom3620rom5722rsb3720 -
\${BOARD_REV}— board revision, e.g.a1 -
\${MC}— machine code combined as\${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)imx8mprom5722a1(ROM‑5722 A1)imx8mprsb3720a1(RSB‑3720 A1)
You can also list supported machines:
$ source setup-environment -
\${MEM_SIZE}— memory size, e.g.2G/4G -
\${UC}— U‑Boot config, e.g.1G/2G/4G/FSPI_1G/FSPI_2G… -
\${SD_DEVICE}— device name of SD card in Linux (e.g./dev/sdf) -
\${SDCARD_IMAGE}— sdcard image built by bitbake (*.wic.bz2) -
\${WORKSPACE}— host workspace folder -
\${UBOOT}— U‑Boot version (e.g.2016.03) -
\${KERNEL}— Linux kernel version (e.g.4.14.98) -
\${TOOLCHAIN}— toolchain install dir (e.g./opt/fsl-imx-x11/4.1.15-2.0.0)
Debug/serial console: use a serial terminal (minicom/putty/teraterm …) at 115200 8N1.
Terminal console: any terminal program (gnome‑terminal, xfce4‑terminal …).
Docker install and settings
If you don’t have Docker, please install it first (refer to the Docker Engine installation guide).
Pull base image
$ docker pull advrisc/u18.04-imx8lbv1
Create container
$ docker run --privileged -it --name ${CONTAINER_NAME} \
-v ${WORKSPACE}:/home/adv/adv-release-bsp \
-v /dev:/dev advrisc/u18.04-imx8lbv1 /bin/bash
Get BSP
You can either download from GitHub via repo, or copy a BSP tarball into the container.
Download BSP from GitHub
For example, using official tag imx8LBVB0209:
$ 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 refs/tags/imx8LBVB0209 -m imx8LBVB0209.xml
$ repo sync
Other BSP manifests
5.10.35‑2.0.0:
$ repo init -u git://github.com/ADVANTECH-Corp/adv-arm-yocto-bsp.git \
-b imx-linux-hardknott -m imx-5.10.35-2.0.0.xml
$ repo sync
5.10.72‑2.2.0:
$ repo init -u git://github.com/ADVANTECH-Corp/adv-arm-yocto-bsp.git \
-b imx-linux-hardknott -m imx-5.10.72-2.2.0.xml
$ repo sync
If you see “server certificate verification failed” with self‑signed certs:
$ 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.”:
$ git config --global url."https://".insteadOf git://
Copy BSP tarball to container
If you already have a BSP tarball (e.g. imx8LBVB0029_2021-10-23.tgz):
- Exit the container
$ exit
- Copy tarball to
\${WORKSPACE}and fix ownership
$ cp imx8LBVB0029_2021-10-23.tgz ${WORKSPACE}
$ sudo chown adv:adv ${WORKSPACE}/imx8LBVB0029_2021-10-23.tgz
- Back to container
$ docker start ${CONTAINER_NAME}
$ docker attach ${CONTAINER_NAME}
- Unpack
$ tar zxvf imx8LBVB0029_2021-10-23.tgz
Downloads tarball (optional but recommended)
Yocto will create a downloads/ during build, but fetching may fail occasionally. Using a prepared downloads tarball can help.
- Example:
downloads_imx8_5.10.35.tar.gz(md5:912999faf861bf413cef4cf7a9f18dfa)
Steps:
- Exit container
$ exit
- Copy tarball to
\${WORKSPACE}and fix ownership
$ cp downloads_imx8_5.10.35.tar.gz ${WORKSPACE}
$ sudo chown adv:adv ${WORKSPACE}/downloads_imx8_5.10.35.tar.gz
- Back to container
$ docker start ${CONTAINER_NAME}
$ docker attach ${CONTAINER_NAME}
- Unpack and link
$ tar zxvf downloads_imx8_5.10.35.tar.gz
$ cd adv-release-bsp
$ ln -s ${WORKSPACE}/downloads_imx8_5.10.35 downloads
Introducing the BSP
The BSP is based on the Yocto Project with NXP/Freescale enhancements for i.MX8, and Advantech board support.
Key items:
sources/— Yocto layers (community + Advantech)meta-advantech/— Advantech meta layermeta-fsl-*— NXP/Freescale meta layersfsl-setup-release.sh— create a new build envsetup-environment— continue an existing env- One or more build directories
Naming rule
-
BSP tarball:
imx8LBVA0010_2019-08-27.tgzLB= Linux BSPVA0010= Version A0010
-
Prebuilt image:
5720A1AIM20LIVA0010_iMX8M_2G_2020-08-27.img.gz5720A1= ROM‑5720 A1LI= Linux Image2G= DDR size
BSP content
sources/**meta-advantech/— Advantech layermeta-fsl-*— NXP/Freescale layers
fsl-setup-release.sh— new build envsetup-environment— continue env
Build Instructions
Create a new build environment
$ cd ${BSP_HOME}
$ MACHINE=${MC} DISTRO=fsl-imx-xwayland \
source imx-setup-release.sh -b ${BDIR}
Specify default U‑Boot config:
$ MACHINE=${MC} UBOOT_CONFIG=${UC} DISTRO=fsl-imx-xwayland \
source imx-setup-release.sh -b ${BDIR}
Accept the EULA when prompted.
Continue an existing build environment
$ cd ${BSP_HOME}
$ source setup-environment ${BDIR}
Build SD card image
$ bitbake imx-image-full
The output imx-image-full-${MC}.wic.bz2 will be under ./tmp/deploy/images/${MC} when finished.
Build toolchain installer
$ bitbake meta-toolchain
The installer will be under ./tmp/deploy/sdk, e.g.
fsl-imx-xwayland-glibc-x86_64-meta-toolchain-aarch64-toolchain-${KERNEL}-zeus.sh
Build bootloader
$ bitbake imx-boot
Build Linux kernel
If you’re in Docker, install tmux first:
$ sudo apt-get update && sudo apt-get install -y tmux
$ tmux
Kernel menuconfig:
$ bitbake linux-imx -c menuconfig
Exit tmux window after editing:
$ exit
Build kernel image:
$ bitbake linux-imx
Artifacts Image and Image-${IMX8PROC}-${BOARD}-${BOARD_REV}.dtb will be under ./tmp/deploy/images/${MC}.
Creating boot-up on-board flash from prebuilt image
Create a bootable SD card
# gunzip -c ${PREBUILT_IMAGE} | sudo dd of=${SD_DEVICE} bs=1M
# sync
Creating boot-up on-board flash from built SD card image
Create a bootable SD card
$ pushd ${BSP_HOME}/${BDIR}/tmp/deploy/images/${MC}
$ sudo bzcat ${SDCARD_IMAGE} | sudo dd of=${SD_DEVICE} bs=1M
$ sync
$ popd
Debug console information
Hardware
Please refer to your board’s debug UART header and cable mapping (Debug Port Information).
Software
Use a serial terminal such as minicom or putty with 115200 baud.
One-step build image
Docker must be preinstalled.
Download helper script:
$ wget https://raw.githubusercontent.com/ADVANTECH-Corp/RISC_tools_scripts/hardknott/imx8/adv_imx8_build.sh
$ sudo chmod a+x adv_imx8_build.sh
Build image:
$ sudo ./adv_imx8_build.sh ${BOARD}
# Example
$ sudo ./adv_imx8_build.sh rom5720
Result images:
workspace/${BDIR}/tmp/deploy/images/${MC}
Then follow Creating boot-up on-board flash from built SD card image.
Customization
Package addition
Add tcf-agent & openssh-sftp-server
$ cd ${BSP_HOME}/sources/meta-advantech/meta-fsl-imx/recipes-fsl/images
# Edit fsl-image-adv.inc and append:
IMAGE_INSTALL += " tcf-agent openssh-sftp-server "
Add Chromium browser
Edit local.conf under ${BSP_HOME}/${BDIR}/conf.
Method 1 (recommended)
CORE_IMAGE_EXTRA_INSTALL += "chromium-ozone-wayland"
Method 2
IMAGE_INSTALL_append = "${@bb.utils.contains('DISTRO_FEATURES', 'wayland', ' chromium-ozone-wayland libexif', \
bb.utils.contains('DISTRO_FEATURES', 'x11', ' chromium-x11 libexif', '', d), d)}"
LICENSE_FLAGS_WHITELIST = "${@bb.utils.contains('DISTRO_FEATURES', 'wayland', 'commercial', \
bb.utils.contains('DISTRO_FEATURES', 'x11', 'commercial', '', d), d)}"
Add QtWebEngine
# ${BSP_HOME}/${BDIR}/conf/local.conf
IMAGE_INSTALL_append += " packagegroup-qt5-webengine "
Setting up SDK
Build the SDK installer (see above), then run it:
$ cd ${BSP_HOME}/${BDIR}/tmp/deploy/sdk
$ sudo ./fsl-imx-xwayland-glibc-x86_64-meta-toolchain-aarch64-toolchain-5.4-zeus.sh
Follow prompts and wait until the SDK finishes installing.
Setting up cross-compiling 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
# Example
$ make imx8mm_rom5721a1_2G_defconfig
Build U‑Boot
$ make -j$(nproc)
Build imx-boot image with imx-mkimage
Obtain the imx-boot tarball (example for ROM‑5721):
$ tar zxvf 5721A1AIM20LIVA0118_iMX8MM_imx-boot.tgz
$ cd 5721A1AIM20LIVA0118_iMX8MM_imx-boot/
# Copy necessary files to imx-mkimage folder
$ ./cp_uboot.sh <uboot_path> ${IMX8PROC}
# Make imx-boot image
$ ./mk_imx-boot.sh ${IMX8PROC}
# Example
$ ./cp_uboot.sh ../uboot-imx6 imx8m
$ ./mk_imx-boot.sh imx8mm
Replace imx-boot
Write to on‑board flash:
$ sudo dd if=flash.bin of=/dev/mmcblk0 bs=1K seek=<offset> conv=fsync
Offsets:
33— i.MX 8QuadMax A0, i.MX 8QuadXPlus A0, i.MX 8M Quad, i.MX 8M Mini32— i.MX 8M Plus, i.MX 8QuadXPlus B0/C0, i.MX 8QuadMax B0
Build & update kernel/modules/DTB manually
Assumes cross env is sourced (see Setting up cross‑compiling environment).
Unpack kernel tarball in container
$ sudo chown adv:adv imx8LBVA0029_2019-10-23_linux-imx.tgz
$ tar zxvf imx8LBVA0029_2019-10-23_linux-imx.tgz
Configure kernel
$ cd linux-imx
$ make distclean
$ make imx_v8_adv_defconfig
$ make menuconfig
Build kernel
$ make -j$(nproc) Image
If you hit link errors like the screenshot, try:
$ unset LDFLAGS
The kernel Image will be at ./arch/arm64/boot/.
Build modules
$ make -j$(nproc) modules
$ make modules_install INSTALL_MOD_PATH=~/temp/rootfs
Build DTB
$ make -j$(nproc) freescale/${IMX8PROC}-${BOARD}-${BOARD_REV}.dtb
# Example
$ make -j$(nproc) freescale/imx8mq-rom5720-a1.dtb
DTB will be at ./arch/arm64/boot/dts/freescale/.
Replace kernel & DTB
Copy Image and DTB to your SD/eMMC boot partition as needed.
Improve boot speed
Bootloader
- Boot delay
u-boot> setenv bootdelay 0
u-boot> saveenv
u-boot> reset
- Disable console messages (quieter kernel)
u-boot> setenv mmcargs setenv bootargs ${jh_clk} console=${console} \
modprobe.blacklist=${modprobe.blacklist} root=${mmcroot} \
video=HDMI-A-1:${videores} quiet
u-boot> saveenv
u-boot> reset
Or disable debug port entirely:
u-boot> setenv console
u-boot> saveenv
u-boot> reset
Services
Disable unneeded services:
$ sudo systemctl disable <service>
# e.g.
$ sudo systemctl disable boottimes
System Recovery
Restore eMMC image if the on‑board system is corrupted.
Recovery by SD card
- Copy
5720A1AIM20LIVA0022_iMX8M_flash_tool.tgzto your PC. - Insert SD card.
- Make a bootable SD:
# tar zxvf 5720A1AIM20LIVA0022_iMX8M_2G_flash_tool.tgz
# cd 5720A1AIM20LIVA0022_iMX8M_2G_flash_tool/mk_inand/
# sudo ./mksd-linux.sh /dev/sdg
- Copy
5720A1AIM20LIVA0022_iMX8M_flash_toolto a USB disk. - Insert USB disk + SD card and boot from SD.
- From the USB disk, flash eMMC:
# cd /run/media/sda1/
# cd 5720A1AIM20LIVA0022_iMX8M_2G_flash_tool/mk_inand/
# sudo ./mksd-linux.sh /dev/mmcblk0
Recovery by UUU tool
- Download UUU: https://github.com/ADVANTECH-Corp/uuu/releases/tag/v20200619
- Run:
# Linux
$ sudo ./uuu
# Windows
> uuu.exe
- Prepare a folder containing:
1. uuu
2. imx-boot-imx8mqrom5720a1-sd.bin-flash_evk
3. fsl-image-validation-imx-imx8mqrom5720a1-20190917152605.rootfs.sdcard
4. Image_dtb.uuu
5. rootfs.uuu
- Connect OTG cable PC ↔ device.
- Set boot mode (e.g. ROM‑5720/5721/5620:
1,2,3=off 4=on, ROM‑7720:1,2,3,4,5,6=offor1,2,4,5,6=off 3=on) and power on. - Example burn commands (U‑Boot ≥ 2019‑11‑01 for writing to
mmcblk0):
# 1) Burn U‑Boot to eMMC
## a) replace U‑Boot in mmcblk0boot0
$ sudo ./uuu -b emmc imx-boot-imx8mqrom5720a1-sd.bin-flash_evk
## b) replace U‑Boot in mmcblk0
$ sudo ./uuu -b emmc_adv imx-boot-imx8mqrom5720a1-sd.bin-flash_evk
# 2) Burn rootfs image to eMMC
## a) with U‑Boot in mmcblk0boot0
$ sudo ./uuu -b emmc_all imx-boot-imx8mqrom5720a1-sd.bin-flash_evk \
fsl-image-validation-imx-imx8mqrom5720a1-20190917152605.rootfs.sdcard
## b) with U‑Boot in mmcblk0
$ sudo ./uuu -b emmc_all_adv imx-boot-imx8mqrom5720a1-sd.bin-flash_evk \
fsl-image-validation-imx-imx8mqrom5720a1-20190917152605.rootfs.sdcard
- To update only kernel/DTB via UUU:
# Rename files
_Image
_board.dtb
# Then
$ sudo ./uuu Image_dtb.uuu
- To update only rootfs via UUU:
# Rename rootfs tarball
_rootfs.tar.bz2
# Then
$ sudo ./uuu rootfs.uuu
- Fastboot method (UUU >= 1.4.139)
# In U‑Boot
u-boot> fastboot 0
# From host
$ sudo uuu -b fat_write Image mmc 0:1
$ sudo uuu -b fat_write xxx.dtb mmc 0:1
More usage: https://github.com/NXPmicro/mfgtools/wiki
Package List
List all packages built into the image:
$ bitbake -g fsl-image-qt5-validation-imx \
&& cat recipe-depends.dot | grep -v -e '-native' | grep -v digraph \
| grep -v -e '-image' | awk '{print $1}' | sort | uniq
(2019‑10‑25 Package List)
Show all recipes (including non-installed):
$ bitbake -s
(2019‑10‑25 Package Version List)
You can also check:
${BDIR}/tmp/deploy/images/${MC}/fsl-image-qt5-validation-imx-${MC}.manifest
On target board, list packages by rpm:
$ rpm -qa --root / --dbpath /var/lib/rpm | sort
(2019‑10‑25 RPM on Board List)
Device Tree Source file select
Choose DTB in U‑Boot to enable different devices, e.g.:
u-boot> setenv fdt_file adv-imx8mm-rom5721-a1-dsi2dp.dtb
u-boot> saveenv
u-boot> boot
ROM‑5721
Display
- DSI to LVDS
imx8mm-rom5721-a1.dtb(g070vw01)imx8mm-rom5721-a1-dsi2lvds-g150xgel05.dtb(g150xgel05)imx8mm-rom5721-a1-dsi2lvds-g215hvn01.dtb(g215hvn01)
- DSI to DP
imx8mm-rom5721-a1-dsi2dp.dtb
- DSI to HDMI
imx8mm-rom5721-a1-adv7535.dtb
- DSI (panels)
imx8mm-rom5721-a1-auog101uan02.dtb(auog101uan02)
- M.2 SDIO
imx8mm-rom5721-a1-m2-sdio.dtb(adjust CN43~CN48)
ROM‑5720
Display
- DSI to HDMI
imx8mq-rom5720-a1-dcss-adv7535.dtbimx8mq-rom5720-a1-lcdif-adv7535.dtb- For Weston UI, set
drm-device=card2in/etc/xdg/weston/weston.ini
- DSI (panel)
imx8mq-rom5720-a1-dcss-auog101uan02.dtb(auog101uan02)
- Dual Display (DSI->HDMI + HDMI)
imx8mq-rom5720-a1-dual-display.dtb- For Weston UI, set
drm-device=card1
- M.2 SDIO
imx8mq-rom5720-a1-m2-sdio.dtb(adjust CN43~CN48)
ROM‑5620
Display
- LVDS
imx8mxp-rom5620-a1.dtb(g070vw01)imx8qxp-rom5620-a1-lvds-chimei.dtb(g150xgel05)imx8qxp-rom5620-a1-lvds-dual.dtb(g215hvn01)
- LVDS to HDMI
imx8qxp-rom5620-a1-hdmi-bridge.dtb
- DSI to HDMI
imx8qxp-rom5620-a1-hdmi-bridge.dtb
- DSI (panel)
imx8qxp-rom5620-a1-auog101uan02.dtb(auog101uan02)
- M.2 SDIO
imx8qxp-rom5620-a1-m2-sdio.dtb(adjust CN43~CN48)
ROM‑7720
Display
- HDMI
imx8qm-rom7720-a1.dtb
- LVDS
imx8qm-rom7720-a1-lvds0.dtb(g070vw01)imx8qm-rom7720-a1-lvds1.dtb(g070vw01)imx8qm-rom7720-a1-lvds-dual.dtb(g215hvn01)
- HDMI + LVDS
imx8qm-rom7720-a1-hdmi-lvds0.dtb(HDMI + g070vw01)imx8qm-rom7720-a1-hdmi-lvds1.dtb(HDMI + g070vw01)imx8qm-rom7720-a1-hdmi-lvds-dual.dtb(HDMI + g215hvn01)
- LVDS to HDMI
imx8qm-rom7720-a1-it6263.dtb
- Audio Codec
imx8qm-rom7720-a1-sgtl5000.dtb
RSB‑3720
Display
- HDMI (default)
imx8mp-rsb3720-a1.dtb
- LVDS + HDMI
imx8mp-rsb3720-a1-lvds0-auo.dtb(g070vw01 LVDS0 + HDMI)imx8mp-rsb3720-a1-lvds1-auo.dtb(g070vw01 LVDS1 + HDMI)imx8mp-rsb3720-a1-lvds-dual.dtb(g215hvn01 dual LVDS + HDMI)
- DSI
imx8mp-rsb3720-a1-adv7535.dtb(DSI->HDMI) + HDMIimx8mp-rsb3720-a1-auog101uan02.dtb(DSI) + HDMI
Camera
- OV5640 (default):
imx8mp-rsb3720-a1.dtb - Basler:
imx8mp-rsb3720-a1-basler.dtb
ROM‑5722
Display
- HDMI (default):
imx8mp-rom5722-a1.dtb - LVDS + HDMI
imx8mp-rom5722-a1-lvds0-auo.dtb(g070vw01 LVDS0 + HDMI)imx8mp-rom5722-a1-lvds1-auo.dtb(g070vw01 LVDS1 + HDMI)imx8mp-rom5722-a1-lvds-dual.dtb(g215hvn01 dual LVDS + HDMI)
- DSI
imx8mp-rom5722-a1-adv7535.dtb(DSI->HDMI) + HDMIimx8mp-rom5722-a1-auog101uan02.dtb(DSI) + HDMI
Camera
- OV5640 (default):
imx8mp-rom5722-a1.dtb - Basler:
imx8mp-rom5722-a1-basler.dtb
ROM‑3620
Display
- LVDS
imx8mxp-rom3620-a1.dtb(g070vw01)imx8qxp-rom3620-a1-lvds-chimei.dtb(g150xgel05)imx8qxp-rom3620-a1-lvds-dual.dtb(g215hvn01)
- DSI to HDMI
imx8qxp-rom3620-a1-hdmi-bridge.dtb
- DSI (panel)
imx8qxp-rom3620-a1-auog101uan02.dtb(auog101uan02)
Burn‑in Test
Read MAC, Serial Number, Manufacture Date from QSPI
Note: Adjust
/dev/mtdblock0and offsets for your platform.
MAC 0
READ_DATA=$(dd if=/dev/mtdblock0 bs=1 skip=$((0xd0000)) count=6 2>/dev/null | hexdump -e '6/1 "%02x:" "\n"' | sed 's/:$//')
echo "$READ_DATA"
MAC 1
READ_DATA=$(dd if=/dev/mtdblock0 bs=1 skip=$((0xd0400)) count=6 2>/dev/null | hexdump -e '6/1 "%02x:" "\n"' | sed 's/:$//')
echo "$READ_DATA"
Serial Number
READ_DATA=$(dd if=/dev/mtdblock0 bs=1 skip=$((0xd0006)) count=10 2>/dev/null)
echo "$READ_DATA"
Manufacture Date (formatted as YYYY-MM-DD_hh-mm-ss)
RAW=$(dd if=/dev/mtdblock0 bs=1 skip=$((0xd0010)) count=14 2>/dev/null)
READ_DATA="$(echo "$RAW" | cut -c1-4)-$(echo "$RAW" | cut -c5-6)-$(echo "$RAW" | cut -c7-8)_$(echo "$RAW" | cut -c9-10)-$(echo "$RAW" | cut -c11-12)-$(echo "$RAW" | cut -c13-14)"
echo "$READ_DATA"