i.MX 8M Mini - MCU M4 firmware guide

1. Preface

This guide describes how to build and run the firmware on ARM Cortex M4 core included in imx8m-mini SoC. It is good to start with tool MCUXpresso from NXP to design M4 firmware. This toolchain contains demos, libraries and build scripts for NXP EVK boards. As this toolset doesn't contain compiler it is necessary to use an external compiler toolchain.
To run an application with M4 core it is also necessary to update ARM Trusted Firmware ATF and Linux Device Tree table Linux DTB.
ATF is responsible for resource allocation (configuration which peripheral is accessible by each CPU core domain M4 and A53). To use a peripheral unit with M4 core it is necessary to attach this peripheral to M4 core domain. Then it is necessary to disable all peripherals attached to M4 domain in the Linux to prevent kernel crash (peripherals attached to M4 domain are not accessible in A53 domain).

This document is related to Congatec Yocto version: cgtimx8mm__imx-linux-zeus
With kernel 5.4.47

2. M4 - Firmware Build

2.1 SDK - MCUXpresso 2.10.0

MCUXpresso SDK is development tool-set to build firmware for micro-controllers based on Arm® Cortex®-M cores. SDK provides setups for compiler, hardware libraries, FreeRTOS operating system and examples of application for NXP development and evaluation boards. Each board support package can be found inside of the top level <MCUXpresso_dir>/boards folder. Each supported board has its own folder with name referred as <board_name> in this document.
MCIXpresso tool-set with documentation can be downloaded from NXP site.

NXP board	Derived Congatec Board	sub-folder name

NXP board	Derived Congatec Board	sub-folder name
EVK-MIMX8MM	conga-SMX8-Mini	`<MCUXpresso_dir>/boards/evkmimx8mm/`

2.2 Prerequisities

Install cmake

$ sudo apt-get install cmake

Download and install GNU-ARM bare-metal toolchain:

$ mkdir ~/<MCUXpresso_dir>
$ cd ~/<MCUXpresso_dir>
$ wget <https://developer.arm.com/-/media/Files/downloads/gnu-rm/10-2020q4/gcc-arm-none-eabi-10-2020-q4-major-x86_64-linux.tar.bz2>
$ tar xvf gcc-arm-none-eabi-10-2020-q4-major-x86_64-linux.tar.bz2

Instal downloaded MCUXpresso tar

The SDK tools is generated by NXP download page. Select the right type of the processor and follow download instructions. Copy downloaded SDK to final folder and unpack.

$ cp <download_dir>/SDK_2_10_0_EVK-MIMX8MM.tar.gz ~/<MCUXpresso_dir>
$ tar xzf SDK_2_10_0_EVK-MIMX8MM.tar.gz

2.3 Build application

Build "Hello World" demo

All of the NXP examples are located under the following folder

~/<MCUXpresso_dir>/boards/evkmimx8mm

To show how to quickly build first demo - build of simple Hello World application is selected. This demo is linked to run from MC4 TCM memory at address 0x1ffe0000. For detailed description of memory map see imx8mm reference manual. The demo uses UART4 to say "Hello World". How to download and run the application is described later.

To build "Hellow World" demo, follow these steps:

Several folders in ~/<MCUXpresso_dir>/boards/evkmimx8mm/demo_apps/hello_world/armgccare created:

Demo name	Image foder	Description	Link Address

Demo name	Image foder	Description	Link Address
TCM demo	release	release variant, no debug info, run from M4 TCM memory	`0x1ffe0000`
	debug	debug variant, debug info included, run from M4 TCM memory	`0x1ffe0000`
DDR demo	ddr_release	release variant, no debug info, run from DDR memory	`0x80000000`
	ddr_debug	debug variant, debug info included, run from DDR memory	`0x80000000`
FLASH demo	flash_release	release variant, no debug info, run directly from NOR flash	`0x08000000`
	flash_debug	debug variant, debug info included, run directly from NOR flash	`0x08000000`
	CMakeFiles	build tool files (not described in this guide)	N/A

To run appropriate demo it is necessary to copy dedicated .bin file to the SD card that is used for system boot.
For TCM demo copy the hello_world.bin file located in ~/<MCUXpresso_dir>/boards/evkmimx8mm/demo_apps/hello_world/armgcc/release to the boot media SD card to the boot partition.
For DDR demo copy the hello_world.bin file located in ~/<MCUXpresso_dir>/boards/evkmimx8mm/demo_apps/hello_world/armgcc/ddr_release to the boot media SD card to the boot partition with different name e.g hello_world_ddr.bin.

3. Running "Hello World" demo

To run the application on ARM-Cortex M4 core it is necessary to perform additional steps, that allow M4 core access to needed resources.

3.1 Prerequisities

Resource planning is performed by ARM Trusted Firmware referenced as ATF and Linux Device Tree setiing referenced as Linux DTB. ATF package is a part of "Boot Container" that is used by SoC to load operating system. Linux DTB is necessary for configuration of Linux kernel device drivers. All resources needed for M4 core must be disabled in Linux.
All required packages are listed in the table bellow.

Package	Build Guide	Description

Package	Build Guide	Description
U-Boot	i.MX 8M Mini Bootloader standalone build	Das U-Boot boot loader, responsible to load ATF and Linux Kernel together with Device Tree configuration file
ATF	in this document	ARM Trusted Firmware - resource and security management
MkImage	i.MX 8M Mini Bootcontainer	Bootcontainer creation tool
Linux Kernel	i.MX 8M Mini Kernel standalone build	Linux Kernel Sources

To build the boot container it is necessary to download (compile) and install - GNU-ARM aarch64 toolchain.
There are exists two possible sources:

ARM precompiled toolchain (by ARM company)
Yocto generated SDK

3.1.1 ARM precompiled toolchain

To download, unpack and prepare ARM precompiled toolchain use these commands:

3.1.2 YOCTO SDK

Yocto build tool provides own compiler toolchain that can be used out of Yocto tree. Yocto also provides necessary files to build boot container.
If you didn't build the Yocto build system before follows these steps:
First install some required packages:

Next install Google repo tool needed to download all necessary projects:

And finally build the SDK:

Be aware that the build proces takes several hours.
If you have compiled Yocto image before the steps to gerenate SDK are simpler:

Install SDK to you computer:

Enter install folder for the SDK at your will, for this document it will be named as <~/yocto-SDK-dir>.
Note: If you are to use a system folder (i.e. /opt) call this script with sudo.

3.2 ATF Update

ARM Trusted Firmware is a part of standard boot-container supproted by NXP and Congatec.
First download and deploy source code for ATF.

Prepare toolchain to be used for this build:
Precompiled toolchain:

Or Yocto generated toolchain:

Next it is necessary to update source code file responsible for resource and security setting:

file	description

file	description
`~/atf-imx8-family/plat/imx/imx8m/imx8mm/imx8mm_bl31_setup.c`	source file with board setup code

ATF documentation can be found on ATF-A projetc documentation pages.

3.2.1 Example how to enable UART4 for M4 core domain:

Find this piece of code in the file imx8mm_bl31_setup.c

and change it to:

next build the ATF:

Generated file necessary for boot container creation is:

file	description

file	description
`~/atf-imx8-family/build/imx8mm/release/bl31.bin`	ATF binary image linked to OCRAM memory

3.3 U-Boot

Build appropriate U-Boot for your bootcontainer. Follows instructions how to build U-Boot for SD card or onboard NOR FLASH in guide "i.MX 8M Mini Bootloader standalone build".
NOTE: supposed that cross-compiler toochain is set as it is described in section 3.2 ATF Update

Configurations for U-Boot build:

Configuration	Description

Configuration	Description
flash_sx8m	Uboot linked for SD card
flash_sx8m_flexspi	U-Boot linked for onboard NOR Flash

Generated files necessary for boot container creation are:

file	description

file	description
`~/<uboot-build-dir>/spl/u-boot-spl.bin`	SPL - Secondary loader, linked to TCM memory, need to activate DDR and load ATF and TPL
`~/<uboot-build-dir>/u-boot-nodtb.bin`	TPL - U-Boot bootloader, needed to load kernel and kernel device tree
`~/<uboot-build-dir>/arch/arm/dts/imx8mm-cgtsx8m.dtb`	U-Boot device tree

NOTE: naming scheme is the same for both U-Boot versions (SD or NOR Flash).

3.4 Bootcontainer

Boot container is a small binary file that is recognized and loaded by the SoC internal ROM code. ROM code check several supported boot devices.
To prepare boot container the U-Boot from Yocto can be used with limitation that Congatec Yocto build environment provides U-Boot dedicated for SD card deployment only. To obtain U-Boot dedicated for internal NOR flash it is necessary to build it from source codes.

The guide how to prepare boot container binary file is on i.MX 8M Mini Bootcontainer.

First prepare boot container build tool:

next copy files in the bellow to the folder ~/mkimage-imx8-family/iMX8M/:

UBoot:
- ~/<uboot-build-dir>/spl/u-boot-spl.bin
- ~/<uboot-build-dir>/u-boot-nodtb.bin
- ~/<uboot-build-dir>/arch/arm/dts/imx8mm-cgtsx8m.dtb
ATF:
- ~/atf-imx8-family/build/imx8mm/release/bl31.bin
DDR training binaries
- ~/<yocto_dir>/<build_dir>/tmp/deploy/images/imx8mm-cgt-sx8m/imx-boot-tools/lpddr4_pmu_train_1d_dmem.bin
- ~/<yocto_dir>/<build_dir>/tmp/deploy/images/imx8mm-cgt-sx8m/imx-boot-tools/lpddr4_pmu_train_1d_imem.bin
- ~/<yocto_dir>/<build_dir>/tmp/deploy/images/imx8mm-cgt-sx8m/imx-boot-tools/lpddr4_pmu_train_2d_dmem.bin
- ~/<yocto_dir>/<build_dir>/tmp/deploy/images/imx8mm-cgt-sx8m/imx-boot-tools/lpddr4_pmu_train_2d_imem.bin

Finaly create boot conteiner image:

Where <Make Image Target> is:

Boot Device	Target

Boot Device	Target
SD Card	flash_sx8m
NOR Flash	flash_sx8m_flexspi

Resulting file flash.bin is located in the folder ~/mkimage-imx8-family/iMX8M/

3.4.1 Install boot container - SD card build

SD card boot container image can be coppied to SD card by dd commnad.

3.4.2 Install boot container - NOR Flash build

Copy NOR flash version of the boot container to SD card to "boot" partition

Insert SD card to the board and break boot sequence in the U-Boot (just by hitting some key). Then load the boot container binary to the RAM and flash it to the NOR flash:

NOTE: fatload shows the size in bytes in decimal format, to use this in sf write command it is necessary to convert this number to hexadecimal format

3.5 Linux Device Tree

To prevent Linux kernel to access resources attached to the M4 core it is necessary to disable these devices in the Kernel Device Tree configuration file. Kernel sources can be downloaded from Yocto tree or directly from Congatec GIT.

To use Linux Kernel from Congatec Yocto use these commands:

Or you can get kernel source from Congatec GIT repository:

Now edit DTB located at: ~<kernel_dir>/arch/arm64/boot/dts/congatec/imx8mm-cgtsx8m.dts

Finaly compile DTB NOTE: supposed that cross-compiler toochain is set as it is described in section 3.2 ATF Update

Copy created DTB file to the SD card, partition /boot (as a replacement of old DTB file)

3.5.1 Example how to remove UART4 from kernel DTS:

Open file ~<kernel_dir>/arch/arm64/boot/dts/congatec/imx8mm-cgtsx8m.dts in some text editor and find the section:

and change field status - to disabled

3.6 Download and Run demo application with U-Boot

Connect serial cable to debug console on the board and open your preferred serial terminal for the serial devices, setting the speed to 115200 bps, 8 data bits, 1 stop bit (115200, 8N1), no parity, then power on the board.
Connect another serial cable to SER1 serial port on the SEVAL carrier board and open another terminal application on the PC. Configure the terminal with this setting:

115200
No parity
8 data bits
1 stop bit

Power on the board and hit any key to stop autoboot in the terminal, then enter to U-Boot command line mode. You can then write the image and run it from TCM or DRAM with the following commands:

a. If the hello_world.bin is made from the debug/release target, which means the binary file will run at TCM, use the following commands to boot:

b. If the hello_world.bin is made from the ddr_debug/ddr_release target, which means the binary file runs at DRAM, use the following commands:

<!---
c. If the hello_world.bin is made from the flash_debug/flash_releasetarget, which means the binary file runs at nor_flash, use the following commands:

--->