Skip to main content

Yocto Linux BSP User Guide

Introduction​

本文件說明 Advantech i.MX8 系列在 Yocto 4.2 (mickledore) 的 BSP 使用方式與常見作業流程。對應 NXP release L6.1.22-2.0.0，kernel 版本為 6.1.22-2.0.0。

Getting Started

Building Yocto Image — System Requirements​

  • CPU：建議 4 核以上
  • 記憶體：8 GB RAM（更多更佳）
  • 磁碟：400 GB 以上（建議 SSD）

Conventions​

  • ${PREBUILT_IMAGE}：預先編好的壓縮映像（*.img.gz）
  • ${CONTAINER_NAME}：Docker container 名稱（例如：imx8LBVD0027）
  • ${BSP_TARBALL}：BSP 壓縮檔（*.tgz）
  • ${BSP_HOME}：BSP 的家目錄
  • ${BDIR}：build 目錄（例如：build_xwayland）
  • ${MX8PROC}：i.MX8 處理器
    • mx8mq（iMX8M Dual Core）、mx8mm（iMX8MM）、mx8mp（iMX8MP）、mx8qm（iMX8QM）、mx8qxp（iMX8QXP）、mx8ulp（iMX8ULP）
  • ${IMX8PROC}：i.MX8 處理器（imx8mq / imx8mm / imx8qm / imx8qxp / imx8mp / imx8ulp）
  • ${BOARD}：目標板，支援清單如下
    • rom5720、rom5721、rom7720、rom5620、rom3620、rom5722、rsb3720、rom2620、rsb3730
  • ${BOARD_REV}：板子版號（例如：a1）
  • ${MC}：machine code，由 ${IMX8PROC}${BOARD}${BOARD_REV} 組成
    • 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）
    • imx8mprsb3720a2（RSB-3720 A2，本文以此版為例）
    • imx8ulprom2620a1（ROM-2620 A1）
    • imx8mmrsb3730a2（RSB-3730 A2）
    • 也可用 source setup-environment 查詢 BSP 支援的 machine
  • ${MEM_SIZE}：記憶體大小（1G / 2G / 4G / 6G）
  • ${UC}：u-boot config（1G / 2G / 4G / 6G / FSPI_1G / FSPI_2G / FSPI_4G / FSPI_6G …）
  • ${SD_DEVICE}：SD 卡在 Linux 下的裝置名稱（例如：/dev/sdf）
  • ${SDCARD_IMAGE}：bitbake 產生的 sdcard image（*.wic.zst）
  • ${WORKSPACE}：host 端 workspace 目錄
  • ${UBOOT}：u-boot 版本（例如：v2023.04_6.1.22-2.0.0）
  • ${KERNEL}：linux kernel 版本（例如：6.1.22-2.0.0）
  • ${TOOLCHAIN}：toolchain 安裝目錄（例如：opt/fsl-imx-wayland/6.1-mickledore/environment）
  • debug console / serial console：serial terminal 程式（minicom、putty、teraterm …），serial port 設為 115200 8N1
  • terminal console：terminal 程式（gnome-terminal、xfce4-terminal …）

Docker install and setting​

若系統尚未安裝 docker，請先依下列步驟安裝並啟動。

To install Docker Engine on your platform​

請參考 Docker Installation Guide。

To pull ubuntu 20.04 image from Docker Hub​

$ docker pull advrisc/u20.04-imx8lbv1

（Docker Hub 上的 ubuntu 20.04 image）

To create 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​

有兩種方式可將 BSP 放入上面建立的 container。

Download BSP From GitHub​

以下範例說明如何從 GitHub 下載 Advantech Yocto BSP。範例中會建立一個名為 adv-release-bsp 的目錄，並以官方版本 imx8LBVD0XXX 為例：

$ 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-mickledore -m adv-6.1.22-2.0.0.xml
$ repo sync

若遇到 server certificate verification failed，可用下列指令關閉 SSL 驗證：

$ export GIT_SSL_NO_VERIFY=1

或

$ git config --global http.sslverify false

若遇到 The unauthenticated git protocol on port 9418 is no longer supported.，可試著執行：

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

Copy BSP tarball to Container​

若你已有 BSP tarball（例如 imx8LBVD0027_2023-10-25.tgz），需將它複製進 container。步驟如下：

  1. 離開 container 回到本機
$ exit
  1. 複製 BSP tarball 到 ${WORKSPACE} 並變更擁有者
$ cp imx8LBVD0027_2023-10-25.tgz ${WORKSPACE}
$ sudo chown adv:adv ${WORKSPACE}/imx8LBVD0027_2023-10-25.tgz
  1. 回到 container
$ docker start ${CONTAINER_NAME}
$ docker attach ${CONTAINER_NAME}
  1. 解開 BSP tarball
$ tar zxvf imx8LBVD0027_2023-10-25.tgz

Downloads tarball​

非必要步驟。

編譯 Yocto image 時會產生 downloads 目錄，內含所需的所有套件，但常常無法正常抓取，因此保留此 downloads 目錄可減少 fetch 失敗的問題。

可從下列連結取得 downloads tarball（downloads_imx8_6.1.22_2.0.0.tar.gz）：

取得後複製到你的 ${WORKSPACE}。步驟如下：

  1. 離開 container 回到本機
$ exit
  1. 複製 downloads tarball 到 ${WORKSPACE} 並變更擁有者
$ cp downloads_imx8_6.1.22_2.0.0.tar.gz ${WORKSPACE}
$ sudo chown adv:adv ${WORKSPACE}/downloads_imx8_6.1.22_2.0.0.tar.gz
  1. 回到 container
$ docker start ${CONTAINER_NAME}
$ docker attach ${CONTAINER_NAME}
  1. 解開 downloads tarball
$ tar zxvf downloads_imx8_6.1.22_2.0.0.tar.gz
  1. 建立指向 downloads 目錄的連結
$ cd adv-release-bsp
$ ln -s ${WORKSPACE}/downloads_imx8_6.1.22_2.0.0 downloads

Introducing BSP​

此 BSP 以 Yocto Project 為基礎，包含 Freescale 針對 i.MX8 的強化功能，以及 Advantech 針對特定目標板的功能。

Advantech Yocto Project BSP release 目錄內含一個 sources 目錄（存放編譯用的 recipes）、一個以上的 build 目錄，以及一組用來設定環境的 script。編譯用的 recipes 同時來自社群與 Advantech，Yocto Project 的 layer 會被下載到 sources 目錄。

Naming Rule​

tarball / prebuilt image 的命名由型號名稱加上 LB 或 LI，再接版本號與釋出日期組成。

例如 BSP 檔名 imx8LBVD0027_2023-10-25.tgz：

  • LB 為 Linux BSP 的縮寫
  • VD0027 代表 Version D.0027

例如 Yocto image 名稱 3720A2AIM36LIVD0027_iMX8MP_6G_2023-10-25.img.gz：

  • 3720A2 代表 RSB-3720 A2
  • LI 為 prebuilt Linux Image 的縮寫
  • 6G 為 DDR 大小

BSP Content​

重要目錄說明如下：

  • sources/
    • meta-advantech/：Advantech 的 meta layer
    • meta-fsl-*/：Freescale 的 meta layer
  • fsl-setup-release.sh：建立新的 build 環境
  • setup-environment：接續既有的 build 環境

Build Instructions​

To create one new build environment​

在 terminal console 執行下列指令：

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

可指定 u-boot 預設 config：

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

例如板子為 3720A2 6G 版本：

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

4G 版本：

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

2G 版本：

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

需閱讀並接受 EULA。

Accept EULA

To continue an exist build environment​

在 terminal console 執行下列指令：

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

To build sdcard image​

建立或接續 build 環境後，執行：

$ bitbake imx-image-full

編譯成功後，imx-image-full-${MC}.wic.zst 與 ...wic.bmap 兩個檔案會位於 ./tmp/deploy/images/${MC} 目錄。

To build toolchain installer​

SDK 包含 QT：

$ bitbake imx-image-full -c populate_sdk

建立或接續 build 環境後，執行：

$ bitbake meta-toolchain

installer 會位於 ./tmp/deploy/sdk 目錄：

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

To build bootloader​

建立或接續 build 環境後，執行：

$ bitbake imx-boot

To build linux kernel​

建立或接續 build 環境後，若在 docker image 中操作，請先安裝 tmux：

$ sudo apt-get install tmux

進入 tmux：

$ tmux

在 terminal console 執行下列指令叫出 menuconfig：

$ bitbake linux-imx -c menuconfig

編輯完 menuconfig 後，輸入下列指令離開 tmux：

$ exit

編譯 kernel image：

$ bitbake linux-imx

Image 與 Image-${IMX8PROC}-${BOARD}-${BOARD_REV}.dtb 兩個檔案會位於 ./tmp/deploy/images/${MC} 目錄。

Compile error exception handling​

Case 1. Vulkan-Loader​

切換到 vulkan meta-layer 目錄：

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

修改 vulkan-loader 的 bb 檔，把 SRC_URL 的 branch 名稱從 master 改為 main：

$ vim vulkan-loader_1.2.182.0.bb

Case 2. nnshark​

（TBD）

Creating boot-up on-board flash from prebuilt image​

To create one boot-up SD card​

在 terminal console 執行下列指令：

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

Creating boot-up on-board flash from built sdcard image​

To create one boot-up SD card​

在 terminal console 執行下列指令：

$ pushd ${BSP_HOME}/${BDIR}/tmp/deploy/images/${MC}
$ zstd -cd ${SDCARD_IMAGE} | sudo dd of=${SD_DEVICE} bs=1M
$ sync
$ popd

（或使用 bmaptool 以節省時間）

$ sudo bmaptool copy --bmap ${SDCARD_IMAGE/zst/bmap} ${SDCARD_IMAGE} ${SD_DEVICE}

Debug console information​

若要查看裝置的 debug 訊息，需準備硬體裝置與軟體工具。

Preparing for hardware device​

下列連結提供各裝置的 debug port slot 與 debug port line 資訊：

Debug Port Information

Preparing for software tool​

  • 需準備 debug console 工具，例如 minicom 或 putty
  • Baud rate：115200

One step build image​

機器需預先安裝 docker。

下載下列 script 可快速建置 image：

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

建置 image：

$ sudo ./adv_imx8_build.sh ${BOARD}
$ sudo ./adv_imx8_build.sh rom5720

image 會位於 workspace 目錄：

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

Customization

Setting up SDK​

請依 To build toolchain installer 一節建立 toolchain installer，然後在 terminal console 執行：

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

輸入新的安裝目錄，或直接按 Enter 使用預設目錄。出現 Proceed[y/n]? 時輸入正確選項，等待 SDK 安裝完成。

Setting up sdk

Setting up cross compiling environment​

SDK 已設定完成後（參考 Setting up SDK），在 terminal console 執行：

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

Build U-Boot in standalone environment​

Config u-boot​

make ${IMX8PROC}_${BOARD}${BOARD_REV}_${MEM_SIZE}_defconfig

例如：

make imx8mp_rsb3720a2_6G_defconfig

Build u-boot​

make -j4

Build imx-boot image by using imx-mkimage for imx8​

從我方 server 取得 imx-boot tarball，以下以 rom5721 為例：

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

此目錄中有兩個 script。複製必要檔案到 imx-mkimage 目錄：

./cp_uboot.sh ${uboot path} ${IMX8PROC}

製作 imx-boot image：

./mk_imx-boot.sh ${IMX8PROC}

例如：

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

Build imx-boot image by using imx-mkimage for imx93​

從我方 server 取得 imx-boot tarball，以下以 rom2820 為例：

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

此目錄中有兩個 script。複製必要檔案到 imx-mkimage 目錄：

./cp_uboot.sh ${uboot path} ${IMX8PROC}

製作 imx-boot image：

./mk_imx-boot.sh ${IMX8PROC}

例如：

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

Replace imx-boot​

執行下列指令寫入 on-board flash：

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

其中 offset 為：

  • 33：i.MX 8QuadMax A0、i.MX 8QuadXPlus A0、i.MX 8M Quad、i.MX 8M Mini
  • 32：i.MX 8M Plus、i.MX 8QuadXPlus B0/C0、i.MX 8QuadMax B0、i.MX 8ulp

Building & updating kernel/modules/dtb manually​

cross compiling 環境已設定完成（參考 Setting up cross compiling environment）。

Copy BSP tarball to Container​

參考 Copy BSP tarball to Container，將 kernel tarball 複製到 ${WORKSPACE} 並回到 container。

變更擁有者並解開 tarball：

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

Config kernel​

設定 linux kernel：

$ cd linux-imx
$ make distclean
$ make imx_v8_adv_defconfig
$ make menuconfig

開始編譯 linux kernel：

$ make -j4 Image

若遇到錯誤如下圖：

imx8 error

執行下列指令後重新編譯：

$ unset LDFLAGS

kernel image 檔 Image 位於 ./arch/arm64/boot/ 目錄。

編譯 kernel modules：

$ make -j4 modules

將所有 modules 複製到暫時的 rootfs 目錄 ~/temp/rootfs：

$ make modules_install INSTALL_MOD_PATH=~/temp/rootfs

編譯 device tree blob：

$ make -j4 freescale/${IMX8PROC}-${BOARD}-${BOARD_REV}.dtb

例如：

$ make -j4 freescale/imx8mp-rsb3720-a2.dtb

device tree blob ${IMX8PROC}-${BOARD}-${BOARD_REV}.dtb 位於 ./arch/arm64/boot/dts/freescale/ 目錄。

Replace kernel & dts​

  • Replace kernel：複製 Image 到 SDcard 或 emmc
  • Replace dtb file：複製 dtb 檔到 SDcard 或 emmc

Improve boot speed​

Bootloader​

  1. bootdelay time — 透過設定 bootloader 環境變數取消 bootdelay：
setenv bootdelay 0
env save
reset
  1. Disable console — 關閉 debug 訊息輸出也能加快開機。

關閉 kernel 訊息：

setenv mmcargs setenv bootargs ${jh_clk} console=${console} modprobe.blacklist=${modprobe.blacklist} root=${mmcroot} video=HDMI-A-1:${videores} quiet
env save
reset

或關閉 debug port：

setenv console
env save
reset

Rootfs​

（TBD）

Services​

使用 systemctl disable 可移除不必要的服務：

systemctl disable <services>

例如：

systemctl disable boottimes

System Recovery

本節說明還原 eMMC image 的詳細流程。

更多用法請參考 NXP mfgtools wiki。

Reflash EMMC from Boot SD CARD

下載 mksd-linux.sh。

  • 下載 "Product_AIM_Release_version"_flash_tool.tgz
  • 解壓 "Product_AIM_Release_version"_flash_tool.tgz
  • 將 mksd-linux.sh 複製到 mk_inand 目錄
  • 執行 mksd-linux.sh

Package List

（TBD）

How to get the MAC, Serial Number, and Manufacture Date in the QSPI flash

MAC 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 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