i.MX 93/91 debug console relocation with Yocto Project

Yes

Introduction.

i.MX93 and i.MX91 use LPUART1 as the debug console in their board portfolios, relocating the LPUART is the very first step when porting custom boards. Therefore, this article will contribute to understanding Yocto Project customization tools and procedures.

This UART relocation change can be made in standalone build, nevertheless, Yocto Project pros are that NXP has already a Linux Factory distribution for their machines, has porting tools for new layers and machines, it also creates the image including your changes.

In this document, you will use an existing machine while creating a new layer, as both are good practices for changes, a new layer is much simpler since you will patch existing files and the configuration is shorter. You will also use an useful tool for development of different recipes, e.g. Kernel, U-boot, etc.

1. Hardware Setup.

FRDM-i.MX91, i.MX91-EVK, i.MX93EVK featuring REV A1 or as this document uses, FRDM-i.MX93.
Connect 5V power source to P1.
Connect USB type-A to type-C to USB1 P2.
Connect a digital analyzer or UART bridge to expansion connector P11.
- P11[32] TX, P11[33] RX and P11[34] GND.
[Optional] SD card for booting, eMMC is an option too.

2. Yocto Project and devtool setup for recipes development.

Start creating a fresh build for the board that you are using [1].

$ mkdir Yocto-FRDM
$ cd Yocto-FRDM
$ repo init -u https://github.com/nxp-imx/imx-manifest -b imx-linux-scarthgap -m imx-6.6.36-2.1.0.xml
$ repo sync

$ cd ./sources
$ git clone https://github.com/nxp-imx-support/meta-imx-frdm.git
$ cd meta-imx-frdm
$ git checkout imx-frdm-2.0

You can build any image, custom projects may need multiple builds for development, then imx-image-core is a great option since it's light and compiling it requires less time.

$ cd ~/Yocto-FRDM/
$ MACHINE=imx93frdm DISTRO=fsl-imx-xwayland source sources/meta-imx-frdm/tools/imx-frdm-setup.sh -b FRDM-i.MX93
$ bitbake imx-image-core

Porting development is accelerated using devtool, when modifying a recipe, a new directory is created workspace/sources/<recipes> and has the recipe unpacked with the patches from all layers applied. You can modify as many recipes as you like.

$ devtool modify u-boot-imx

3. Rebuild an image with a custom name.

At this point you don't have a custom layer but the workspace, which acts as one with 99 level priority and you can confirm this by issuing a simple change in DTS line 12.

$ cd workspace/sources/u-boot-imx/
$ git status
$ git log
$ nano arch/arm/dts/imx93-11x11-frdm.dts

model = "NXP i.MX93 11X11 FRDM board LPUART8 variant";

$ bitbake u-boot-imx
$ bitbake imx-image-core

Bitbaking the recipe is useful for code debug, bitbaking the image makes changes present in u-boot*, imx-boot* and imx-image* files in the same tmp/deploy/images/imx93frdm directory.

Flash the rebuilt image and note that this image still uses P16 console.

4. Transition from devtool to a new custom layer.

Devtool method was used for the development of this article, when the image passed all tests, a new layer could be created using the appropriate patches. These are the steps to generate and apply them.

$ git add .
$ git commit -m "i.MX93 FRDM board renaming"

Then a new patch can be generated or you can update the recipe with $ devtool update-recipe u-boot-imx. The latter creates a patch, includes it in the image configuration but copies it to the main u-boot recipe, a more organized approach is to create a new layer, you can set a different name for it.

meta-imx-console in this case will be used for board renaming, later it will be adjusted to relocate the console. [2]

$ git format-patch HEAD~
$ cd ~/Yocto-FRDM/sources
$ bitbake-layers create-layer meta-imx-console
$ bitbake-layers add-layer meta-imx-console
$ nano ~/Yocto-FRDM/FRDM-i.MX93/conf/bblayers.conf

- BBLAYERS += "/home/joseph/Yocto-FRDM/FRDM-i.MX93/workspace"

You just used a script to generate the necessary files, a little rework is needed though.

$ cd meta-imx-console
$ nano conf/layer.conf

BBFILE_PRIORITY_meta-imx-console = "9"

# LAYERDEPENDS_meta-testing = "core"
$ mkdir -p recipes-bsp/u-boot/files
$ cd recipes-bsp/u-boot/
$ nano u-boot-imx_%.bbappend

FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
SRC_URI:append = " file://0001-i.MX93-FRDM-board-renaming.patch"

$ cp ~/Yocto-FRDM/FRDM-i.MX93/workspace/sources/u-boot-imx/0001-i.MX93-FRDM-board-renaming.patch files/
$ bitbake imx-image-core

NOTE the differences between the build configuration from parsing recipes in the devtool and new layer output.

5. Changes for LPUART8 console usage.

There is a reference document for i.MX 8 series [3] that supported the file collection listed below.

imx-atf
	plat/imx/imx93/include/platform_def.h

u-boot-imx
	arch/arm/dts/imx93-11x11-frdm-u-boot.dtsi
	arch/arm/dts/imx93-11x11-frdm.dts
	arch/arm/dts/imx93.dtsi
	arch/arm/mach-imx/imx9/native/clock.c
	board/freescale/imx93_evk/imx93_evk.c
	include/configs/imx93_evk.h

linux-imx
	arch/arm64/boot/dts/freescale/imx93-11x11-frdm.dts
	arch/arm64/boot/dts/freescale/imx93.dtsi

File modifications are in the patches along with the necessary recipes append files, these files just are appended to the recipe configuration and the only instruction is to add a patch, this is understood by Yocto as configure, patch, compile and deploy make sure to unzip the attachments and that your final structure is the following.

meta-imx-console/
├── conf
│ └── layer.conf
├── COPYING.MIT
├── README
├── recipes-bsp
│ ├── imx-atf
│ │ ├── files
│ │ │ └── 0001-imx-atf-imx93frdm-lpuart-console-relocation.patch
│ │ └── imx-atf_%.bbappend
│ └── u-boot
│ ├── files
│ │ └── 0001-imx-uboot-imx93frdm-lpuart-console-relocation.patch
│ └── u-boot-imx_%.bbappend
└── recipes-kernel
└── linux
├── files
│ └── 0001-imx-linux-imx93frdm-lpuart-console-relocation.patch
└── linux-imx_%.bbappend

The % sign means to match any string, you can either set those to the specific branch that your build is working at but it's preferred to leave it that way.

Then build the image that will use LPUART8 as the new console from boot to Linux.

Conclusion.

You have the necessary file list for setting up and using different UARTs as the system console for i.MX 8 and 9 series and you have confirmed it working in any board you have for i.MX 93/91.

Yocto Project knowledge in NXP BSP has been extended from a previous article about patching kernel and drivers to customizing other recipes and what tools are available as their advantages upon different situations [4].

Finally, console access is granted to a new custom board, this is where all debug messages from other codes will be printed.

References.

[1] https://github.com/nxp-imx-support/meta-imx-frdm/
[2] Yocto Project customization guide
[3] Change the console from UART 2 to UART 4 on the i.MX8MN
[4] Working With Yocto Devtool

Remember that the patches below are provided as is, they were developed under LF6.6.36 and meta-imx-frdm recipe 2.0. When using them you are subject to the record of acceptance and legal compliance from EULA agreement in your Yocto build.