Skip to main content

Yocto Linux BSP User Guide

Introduction​

This guide describes how to obtain, build, and flash the Advantech i.MX6 Yocto kirkstone (5.15.x / Yocto 4.0) BSP, and how to set up a development environment.

Getting Started​

System Requirements​

  • CPU Cores: Quad‑core (or higher recommended)
  • Memory: 8 GB RAM (more recommended)
  • Disk Space: 350 GB (SSD recommended)

Conventions​

  • ${PREBUILT_IMAGE} : compressed prebuilt image (e.g., *.img.gz)
  • ${CONTAINER_NAME} : container name (e.g., imx6LBVC0002)
  • ${BSP_TARBALL} : BSP tarball (*.tgz)
  • ${BSP_HOME} : BSP root directory
  • ${BDIR} : build directory (e.g., build_x11)
  • ${MX6PROC} : i.MX6 processor short name — e.g., mx6q (Dual Quad)
  • ${IMX6PROC} : i.MX6 processor family — e.g., imx6q
  • ${BOARD} : board name — e.g., rom7420, rsb4411
  • ${BOARD_REV} : board revision — e.g., a1
  • ${MC} : machine code, ${IMX6PROC}${BOARD}${BOARD_REV}
    Examples: imx6qrom7420a1 (ROM‑7420 A1), imx6qrsb4411a1 (RSB‑4411 A1)
  • ${MEM_SIZE} : memory size (e.g., 1G/2G)
  • ${UC} : U‑Boot config (e.g., 1G/2G/4G/FSPI_1G/FSPI_2G ...)
  • ${SD_DEVICE} : SD card device path in Linux (e.g., /dev/sdf)
  • ${SDCARD_IMAGE} : SD card image produced by bitbake (e.g., *.wic.zst)
  • ${WORKSPACE} : host workspace folder
  • ${UBOOT} : U‑Boot version (e.g., v2022.04_5.15.52_2.1.0)
  • ${KERNEL} : Linux kernel version (e.g., 5.15.52_2.1.0)
  • ${TOOLCHAIN} : toolchain install dir (e.g., opt/fsl-imx-wayland/5-15-kirkstone/environment)

Serial console: use minicom/putty/teraterm @ 115200 8N1.
Terminal: gnome-terminal / xfce4-terminal, etc.

Docker Install & Setup​

If Docker is not installed, refer to the official Docker documentation for your platform.

Pull the Ubuntu 20.04 image​

docker pull advrisc/u20.04-imx8lbv1

Create a container​

Ensure ${WORKSPACE} exists on the host and is shared with Docker.

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 from GitHub or by copying a BSP tarball into the container.

1) Download BSP from GitHub​

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-kirkstone -m adv-5.15.52-2.1.0.xml
repo sync

After repo sync, modify meta-freescale/recipes-bsp/u-boot/u-boot-imx-common_2022.04.inc according to:
https://github.com/Freescale/meta-freescale/commit/f851708484206263aecee032288d27c948745ce8

U-Boot common include

Git tips:

  • Self‑signed certs (SSL verify failure): 
    export GIT_SSL_NO_VERIFY=1
    # or
    git config --global http.sslverify false
  • 9418 unauthenticated git protocol disabled: 
    git config --global url."https://".insteadOf git://

2) (Optional) Pre-populate downloads​

During Yocto builds, a downloads/ folder is populated. To reduce fetch failures, preload it from a tarball (e.g., downloads_imx6_5.15.52_2.1.0.tar.gz).

# On host
cp downloads_imx6_5.15.52_2.1.0.tar.gz "${WORKSPACE}"
sudo chown adv:adv "${WORKSPACE}/downloads_imx6_5.15.52_2.1.0.tar.gz"

# Back to container
docker start "${CONTAINER_NAME}"
docker attach "${CONTAINER_NAME}"

# Inside container
tar zxvf downloads_imx6_5.15.52_2.1.0.tar.gz
cd adv-release-bsp
ln -s "${WORKSPACE}/downloads_imx6_5.15.52_2.1.0" downloads

BSP Structure (Overview)​

  • sources/ — Yocto layers (NXP/Freescale + community + Advantech)
  • meta-advantech/ — Advantech layer
  • fsl-setup-release.sh — create a new build environment
  • setup-environment — continue an existing build environment
  • build_* — one or more build directories

Build Instructions​

Create a new build environment​

cd "${BSP_HOME}"
MACHINE="${MC}" DISTRO=fsl-imx-xwayland source imx-setup-release.sh -b "${BDIR}"
# Optional: 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
# Output: tmp/deploy/images/${MC}/imx-image-full-${MC}.wic.zst

Build toolchain installer​

bitbake meta-toolchain
# Output: tmp/deploy/sdk/
# Example:
# fsl-imx-xwayland-glibc-x86_64-imx-image-full-cortexa9t2hf-neon-imx6qsabresd-toolchain-5.15-kirkstone

Build bootloader​

bitbake imx-boot

Build Linux kernel​

If operating inside Docker, install tmux:

sudo apt-get update && sudo apt-get install -y tmux
tmux

Menuconfig:

bitbake linux-imx -c menuconfig

Exit the tmux window after editing:

exit

Build kernel:

bitbake linux-imx
# Outputs:
#   tmp/deploy/images/${MC}/Image
#   tmp/deploy/images/${MC}/Image-${IMX6PROC}-${BOARD}-${BOARD_REV}.dtb

Flashing / Boot Media​

From prebuilt image (*.img.gz)​

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

From built SD card image​

If your image is .wic.zst (kirkstone default):

pushd "${BSP_HOME}/${BDIR}/tmp/deploy/images/${MC}"
sudo sh -c 'zstdcat "${SDCARD_IMAGE}" | dd of="${SD_DEVICE}" bs=1M status=progress conv=fsync'
sync
popd

If it is .wic.bz2:

pushd "${BSP_HOME}/${BDIR}/tmp/deploy/images/${MC}"
sudo sh -c 'bzcat "${SDCARD_IMAGE}" | dd of="${SD_DEVICE}" bs=1M status=progress conv=fsync'
sync
popd

Caution: dd will overwrite the target device. Verify ${SD_DEVICE} before proceeding.

Debug Console​

  • Use minicom/putty/teraterm with 115200 8N1.
  • Board‑specific debug port details: see your board hardware manual (ROM‑7420 / RSB‑4411).

Customization

Setting up SDK​

See Build toolchain installer to build the SDK, then:

cd "${BSP_HOME}/${BDIR}/tmp/deploy/sdk"
sudo ./fsl-imx-xwayland-glibc-x86_64-imx-image-full-cortexa9t2hf-neon-imx6qsabresd-toolchain-5.15-kirkstone

Follow prompts for install path. When asked Proceed [y/n]?, answer accordingly.

SDK Setup

Setting up cross‑compile environment​

source "${TOOLCHAIN}/environment-setup-cortexa9t2hf-neon-poky-linux-gnueabi"

Build U‑Boot (standalone)​

Configure​

make ${IMX6PROC}_${BOARD}${BOARD_REV}_${MEM_SIZE}_defconfig
# Example:
# make mx6qrom7420a1_1G_defconfig

Build​

make -j$(nproc)

Building & Updating kernel/modules/DTB manually​

Ensure the cross‑compile environment is sourced (see above).

Get kernel source​

git clone https://github.com/ADVANTECH-Corp/linux-imx.git -b adv_5.15.52_2.1.0
cd linux-imx

Configure kernel​

make distclean
make imx_v7_adv_defconfig
make menuconfig

Build kernel image​

make -j$(nproc) Image
# Output: arch/arm/boot/Image

If you hit link errors like the screenshot, run and rebuild:

unset LDFLAGS

Build modules​

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

Build device tree blob(s)​

make -j$(nproc) ${IMX6PROC}-${BOARD}-${BOARD_REV}.dtb
# Example:
# make -j$(nproc) imx6q-rom7420-a1.dtb
# Output: arch/arm/boot/dts/

Replace kernel & DTS on target media​

  • Copy Image to the boot partition on SD/eMMC.
  • Copy the .dtb to the device tree location on SD/eMMC (path depends on your BSP/bootloader).

Reflash eMMC from Boot SD Card