Skip to main content

Yocto Linux BSP User Guide for i.MX9 Series - Yocto 6.0 (Wrynose)

Overview​

This guide describes how to set up the Yocto 6.0 (Wrynose) environment, add the Advantech BSP layer, build a bootable image, and flash it to an SD card for supported i.MX9-based boards.

Supported platforms:

  • i.MX 93
  • i.MX 95

Target release: Yocto 6.0 (Wrynose), NXP release 6.18.20-2.0.0.

Note: meta-advantech-nxp is hosted in Azure DevOps and may require valid access permission.

Prerequisites​

  • Ubuntu 22.04 or 24.04 host system
  • 8 CPU cores or more recommended
  • 16 GB RAM minimum, 32 GB recommended
  • 500 GB free disk space recommended
  • Git, Docker, Python, and Yocto build tools

The first build requires accepting the NXP Software License Agreement when the setup script prompts for it. The examples below set EULA=1 to allow the build to continue after the license has been accepted.

Build Environment​

1. Fix the Ubuntu 24.04 user namespace restriction​

sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

2. Start the Docker container​

docker run --privileged -it --name wrynose-6.18.20-2.0.0 \
    -v <your_workspace_path>:/home/adv:rw \
    -v /dev:/dev \
    advrisc/u22.04-imx9lbv1:latest /bin/bash

Replace <your_workspace_path> with your local workspace path.

Quick Start​

1. Configure Git​

git config --global user.name "Your Name"
git config --global user.email "your.email@advantech.com"
export GIT_SSL_NO_VERIFY=1
git config --global http.sslverify false
git config --global url."https://".insteadOf git://

2. Initialize the NXP Yocto manifest​

mkdir imx-yocto-bsp
cd imx-yocto-bsp
repo init -u https://github.com/nxp-imx/imx-manifest -b imx-linux-wrynose -m imx-6.18.20-2.0.0.xml
repo sync -j$(nproc)

3. Clone the Advantech meta layer​

cd sources
git clone https://AIM-Linux@dev.azure.com/AIM-Linux/meta-advantech-nxp/_git/meta-advantech-nxp -b wrynose-6.18.20-2.0.0
cd ..

The meta-advantech-nxp repository is hosted in Azure DevOps. Confirm that your account has access before running git clone.

Supported Boards​

BoardSoCMachine nameBuild directory
ROM-2820i.MX 93imx93rom2820a1build_rom2820
AFE-E420i.MX 93imx93afee420a1build_afee420
AOM-5521i.MX 95 A2imx95aom5521a2build_aom5521
AOM-2521i.MX 95 B0imx95aom2521b0build_aom2521

Build Image​

To continue an existing build environment, run the following from the BSP root directory instead of running imx-setup-release.sh again:

source setup-environment build_<board>
bitbake imx-image-full

ROM-2820​

MACHINE=imx93rom2820a1 DISTRO=fsl-imx-xwayland EULA=1 source ./imx-setup-release.sh -b build_rom2820
bitbake-layers add-layer ../sources/meta-advantech-nxp
bitbake imx-image-full

AFE-E420​

MACHINE=imx93afee420a1 DISTRO=fsl-imx-xwayland EULA=1 source ./imx-setup-release.sh -b build_afee420
bitbake-layers add-layer ../sources/meta-advantech-nxp
bitbake imx-image-full

AOM-5521​

MACHINE=imx95aom5521a2 DISTRO=fsl-imx-xwayland EULA=1 source ./imx-setup-release.sh -b build_aom5521
bitbake-layers add-layer ../sources/meta-advantech-nxp
bitbake imx-image-full

AOM-2521​

MACHINE=imx95aom2521b0 DISTRO=fsl-imx-xwayland EULA=1 source ./imx-setup-release.sh -b build_aom2521
bitbake-layers add-layer ../sources/meta-advantech-nxp
bitbake imx-image-full

Verify Output​

ls build_<board>/tmp/deploy/images/<machine>/

Expected output:

imx-image-full-<machine>*.wic.zst

The exact filename can include a timestamp or release suffix. Use the filename shown by ls in the following flashing step.

Flash to SD Card​

zstd -d imx-image-full-<machine>.wic.zst
sudo dd if=imx-image-full-<machine>.wic of=/dev/sdX bs=4M status=progress conv=fsync

Warning: Confirm the target device is correct before running dd; writing to the wrong disk may destroy data.

After writing the image, boot the board from the SD card. Use a serial console configured for 115200 8N1 to monitor the boot process. After login, verify the running image with:

uname -a
cat /etc/os-release

Troubleshooting​

  • repo sync fails: check network access, the correct manifest branch, and available disk space
  • git clone fails: verify Azure DevOps access and the repository branch name
  • bitbake-layers add-layer fails: confirm ../sources/meta-advantech-nxp exists and has not already been added
  • Docker permission errors: confirm the workspace volume is writable by the container user
  • A machine is not found: confirm the machine configuration exists in conf/machine/ and that the correct manifest branch was initialized
  • Build fails: verify the Yocto environment was sourced correctly and the container includes the required packages
  • NXP Yocto release notes
  • Advantech BSP documentation
  • Board-specific deployment guides