From Variscite Wiki
VAR-SOM-MX8X - MCUXpresso 2.8.0

1 Overview

1.1 MCUXpresso SDK

MCUXpresso SDK board support provides example applications for NXP development and evaluation boards for Arm Cortex-M cores. Board support packages are found inside of the top level boards folder, and each supported board has its own folder (MCUXpresso SDK package can support multiple boards). Within each <board_name> folder there are various sub-folders to classify the type of examples they contain. These include (but are not limited to):

  • cmsis_driver_examples: Simple applications intended to concisely illustrate how to use CMSIS drivers.
  • demo_apps: Full-featured applications intended to highlight key functionality and use cases of the target MCU. These applications typically use multiple MCU peripherals and may leverage stacks and middleware.
  • driver_examples: Simple applications intended to concisely illustrate how to use the MCUXpresso SDK’s peripheral drivers for a single use case.
  • rtos_examples: Basic FreeRTOS OS examples showcasing the use of various RTOS objects (semaphores, queues, and so on) and interfacing with the MCUXpresso SDK’s RTOS drivers
  • multicore_examples: Simple applications intended to concisely illustrate how to use middleware/multicore stack


Here we describe how to use ARM GCC toolchain, officially supported following Getting Started with MCUXpresso SDK for MEK-MIMX8QX.pdf.

2 Prerequisites

Before starting, prepare a Yocto boot SD (with kernel 5.4.85 or newer).

To allow Cortex M4 accessing shared resources without experiencing Linux kernel conflicts, a dedicated device tree must be loaded, containing m4 label in the name, using the fdt_file environment variable in U-Boot.

This device tree disables some of the base device tree nodes in order to avoid conflicts between the main processor and Cortex M4.

File Name
imx8qxp-var-som-symphony-sd-m4.dtb VAR-SOM-MX8 device tree blob for kernel >= 5.4.85 (Yocto Dunfell)
imx8qxp-var-som-symphony-m4.dtb VAR-SOM-MX8 device tree blob for kernel >= 5.4.85 (Yocto Dunfell)

3 Installing required packages

Install cmake

sudo apt-get install cmake

Download and install GNU-ARM bare-metal toolchain:

mkdir ~/var-mcuxpresso
cd ~/var-mcuxpresso
tar xvf gcc-arm-none-eabi-9-2020-q2-update-x86_64-linux.tar.bz2

Download MCUXpresso SDK for the SOM:

cd ~/var-mcuxpresso
git clone -b mcuxpresso_sdk_2.8.x-var01
cd freertos-variscite

4 Documentation

Original NXP documentation is available online or in the following folder:


5 Available demos

All of the Variscite examples are located under the following folder


Default M4 pins used by the demos are:

function pin
debug UART (UART2) RX: J18.5 / TX: J18.3
I2C (I2C3) SCL: J16.10 / SDA: J16.12
M4 GPIO (M40_GPIO0_IO00) J16.3
M4 PWM (M40_TPM0_CH0) J16.7

The available demos for VAR-SOM-MX8X are:

  • cmsis_driver_examples/lpi2c/int_b2b_transfer/slave
  • cmsis_driver_examples/lpi2c/int_b2b_transfer/master
  • cmsis_driver_examples/lpi2c/edma_b2b_transfer/slave
  • cmsis_driver_examples/lpi2c/edma_b2b_transfer/master
  • cmsis_driver_examples/lpuart/edma_transfer
  • cmsis_driver_examples/lpuart/interrupt_transfer
  • demo_apps/hello_world
  • driver_examples/edma/scatter_gather
  • driver_examples/edma/memory_to_memory
  • driver_examples/intmux
  • driver_examples/lpi2c/edma_b2b_transfer/slave
  • driver_examples/lpi2c/edma_b2b_transfer/master
  • driver_examples/lpi2c/interrupt_b2b_transfer/slave
  • driver_examples/lpi2c/interrupt_b2b_transfer/master
  • driver_examples/lpi2c/polling_b2b_transfer/slave
  • driver_examples/lpi2c/polling_b2b_transfer/master
  • driver_examples/lpi2c/read_accel_value_transfer
  • driver_examples/lpit
  • driver_examples/lpuart/edma_transfer
  • driver_examples/lpuart/interrupt_rb_transfer
  • driver_examples/lpuart/polling
  • driver_examples/lpuart/interrupt_transfer
  • driver_examples/rgpio/led_output
  • driver_examples/sema42/uboot
  • driver_examples/tpm/input_capture
  • driver_examples/tpm/dual_edge_capture
  • driver_examples/tpm/timer
  • driver_examples/tpm/simple_pwm
  • driver_examples/tpm/output_compare
  • driver_examples/tstmr
  • driver_examples/wdog32
  • mmcau_examples/mmcau_api
  • multicore_examples/rpmsg_lite_pingpong_rtos/linux_remote
  • multicore_examples/rpmsg_lite_str_echo_rtos
  • rtos_examples/freertos_hello
  • rtos_examples/freertos_queue
  • rtos_examples/freertos_sem
  • rtos_examples/freertos_generic
  • rtos_examples/freertos_tickless
  • rtos_examples/freertos_mutex
  • rtos_examples/freertos_event
  • rtos_examples/freertos_swtimer

Additional demos are available as reference code, but require HW/SW customization.

Almost all of the above demos are also available for IMX8QXP-MEK.

You can build and run the demos following official NXP documentation for IMX8QXP-MEK, available online or in the following document:

~/var-mcuxpresso/freertos-variscite/docs/Getting Started with MCUXpresso SDK for MEK-MIMX8QX.pdf

6 Building a demo

6.1 Building Manually

For any demo, follow these steps:

cd ~/var-mcuxpresso/freertos-variscite/boards/som_mx8qx
cd <demo_folder>
cd armgcc
export ARMGCC_DIR=~/var-mcuxpresso/gcc-arm-none-eabi-9-2020-q2-update
./ > /dev/null

You can choose any <demo_folder> from the list available in the previous section.

Then copy the ".bin" to the boot media (either the SD or eMMC) in the /boot folder already hosting the Linux device trees.

6.2 Building Using Yocto

In Yocto Dunfell and newer, Variscite provides a Yocto recipe for building and installing firmware into the Yocto image:

This recipe installs the following firmware files:

File Memory Loaded Using...
/boot/cm_<demo name>.bin.debug TCM U-Boot
/boot/cm_<demo name>.bin.ddr_debug DDR U-Boot
/lib/firmware/cm_<demo name>.elf.debug TCM Linux Remoteproc Framework
/lib/firmware/cm_<demo name>.elf.ddr_debug DDR Linux Remoteproc Framework

If you have modified freertos-variscite in your own Git repository and kept the same directory structure, you can easily build your custom firmware by creating a bbappend file:

$ mkdir -p <your-layer>/recipes-bsp/freertos-variscite
$ nano <your-layer>/recipes-bsp/freertos-variscite/freertos-variscite_2.9.x.bbappend

Append SRC_URI and SRCREV to use your freertos-variscite Git repository

SRC_URI_remove = "git://;protocol=git;branch=${MCUXPRESSO_BRANCH};"
SRC_URI_append = " <your Git repository>"
SRCREV = "<your Git commit id>"

Append CM_DEMOS to build your firmware. For example, to build rtos_examples/freertos_hello:

CM_DEMOS_append = "rtos_examples/freertos_hello"

Rebuild fsl-image-gui:

$ bitbake -c cleansstate freertos-variscite && bitbake fsl-image-gui

The firmware binary files should now be installed to /boot/ and elf files to /lib/firmware/

7 Memory types

The SDK allow linking using 2 different memory types: DDR, TCM.

Here is available a short summary of memory areas used by Cortex-M4 as described in related linker file.

memory type M4 memory area A35 memory area memory lentgh linker file
DDR 0x88000000-0x881FFFFF (code)
0x88200000-0x883FFFFF (data)
0x88400000-0x8FFFFFFF (data2)
0x88000000-0x881FFFFF (code)
0x88200000-0x883FFFFF (data)
0x88400000-0x8FFFFFFF (data2)
128MB (DDR) MIMX8QX6xxxFZ_cm4_ddr_ram.ld
TCM 0x1FFE0000-0x1FFFFFFF (code)
0x20000000-0x2001FFFF (data)
0x88000000-0x8FFFFFFF (data2)
0x34FE0000-0x34FFFFFF (code)
0x35000000-0x3501FFFF (data)
0x88000000-0x8FFFFFFF (data2)
256kB (TCM) + 128MB (DDR) MIMX8QX6xxxFZ_cm4_ram.ld

All linker files are locate in the armgcc folder of each demo.

After launching the command the following folder will be created in the armgcc folder

  • ddr_debug: containing DDR binaries compiled in debug mode (not stripped: symbols available)
  • ddr_release: containing DDR binaries compiled in release mode (stripped: no symbols available)
  • debug: containing TCM binaries compiled in debug mode (not stripped: symbols available)
  • release: containing TCM binaries compiled in release mode (stripped: no symbols available)

Further details about memory mapping are available in i.MX 8DualXPlus/8QuadXPlus Applications Processor Reference Manual paragraphs:

  • 2.2 System Memory Map
  • 2.2.9 Cortex-M4 Memory Map

8 Running a demo

8.1 Running a demo from U-Boot

To allow Cortex-M accessing shared resources without experiencing Linux kernel conflicts, a dedicated device tree must be loaded.

To enable Cortex-M:

setenv use_m4 yes; saveenv

To disable Cortex-M:

setenv use_m4 no; saveenv

Binary demos must be loaded to the memory type used for linking.

To use TCM:

setenv m4_addr 0x88000000; saveenv  (TCM is at 0x34FE0000, but U-Boot load to 0x88000000)

To use DDR:

setenv m4_addr 0x88000000; saveenv

To set the name of the Cortex-M binary

setenv m4_bin myapp.bin; saveenv

The .bin file is expected in the folder /boot of the booting media.

The uboot boot command will take care to correctly load the Cortex-M firmware and start Linux for VAR-SOM-MX8X

For testing, it is possible to run the firmware manually

run loadm4bin && run runm4bin

Additional details and step by step procedure to run each of the demos is available online or in the following document:

~/var-mcuxpresso/freertos-variscite/docs/Getting Started with MCUXpresso SDK for MEK-MIMX8QX.pdf

For Yocto Dunfell and newer, this process can be simplified using /etc/remoteproc/variscite-rproc-u-boot
Please refer to the Yocto Scripts section below for more information

8.2 Running a demo from Linux

Note: The Linux remoteproc framework is currently supported by the following configurations:

Variscite SOM Kernel Version
imx8mm-var-som 5.4-2.1.x-imx_var01 or newer
imx8mm-var-dart 5.4-2.1.x-imx_var01 or newer
imx8mn-var-som 5.4-2.1.x-imx_var01 or newer
imx8mq-var-dart 5.4-2.1.x-imx_var01 or newer
imx8qm-var-som 5.4-2.1.x-imx_var01 or newer
imx8qm-var-spear 5.4-2.1.x-imx_var01 or newer
imx8qxp-var-som 5.4-2.1.x-imx_var01 or newer

Increase kernel loglevel while debugging:

 sysctl kernel.printk=7;

Check the state of the m4, it should be running already by U-Boot

 cat /sys/class/remoteproc/remoteproc0/state

If the state is 'running', stop the m4

 echo stop > /sys/class/remoteproc/remoteproc0/state

Load new firmware (.elf file must already exist in /lib/firmware directory)

 echo hello_world.elf > /sys/class/remoteproc/remoteproc0/firmware

Run the new firmware

 echo start > /sys/class/remoteproc/remoteproc0/state
If remoteproc is used to reload ddr firmware, special disable_cache firmware must be reloaded between stop and start
For Example:
 echo cm_rpmsg_lite_pingpong_rtos_linux_remote.elf.ddr_debug > /sys/class/remoteproc/remoteproc0/firmware
 echo start > /sys/class/remoteproc/remoteproc0/state
 echo stop > /sys/class/remoteproc/remoteproc0/state
 echo cm_disable_cache.elf.debug > /sys/class/remoteproc/remoteproc0/firmware
 echo start > /sys/class/remoteproc/remoteproc0/state
 echo stop > /sys/class/remoteproc/remoteproc0/state
 echo cm_rpmsg_lite_str_echo_rtos_imxcm4.elf.ddr_debug > /sys/class/remoteproc/remoteproc0/firmware
 echo start > /sys/class/remoteproc/remoteproc0/state
 echo stop > /sys/class/remoteproc/remoteproc0/state

For Yocto Dunfell and newer, this process can be simplified using /etc/remoteproc/variscite-rproc-linux
Please refer to the Yocto Scripts section below for more information

8.3 Running a Demo using Yocto Scripts

In Yocto Dunfell and newer, Variscite provides scripts to simplify loading firmware via U-Boot or Linux:

Script Description
/etc/remoteproc/variscite-rproc-u-boot Configure U-Boot to load firmware on boot
/etc/remoteproc/variscite-rproc-linux Load and run firmware using Linux remoteproc framework


variscite-rproc-u-boot example on imx8mm-var-dart:

root@imx8mm-var-dart:~# /etc/remoteproc/variscite-rproc-u-boot -f /boot/cm_hello_world.bin.ddr_debug
Configuring for DDR memory
+ fw_setenv m4_addr 0x7E000000
+ fw_setenv fdt_file imx8mm-var-som-symphony-m4.dtb
+ fw_setenv use_m4 yes
+ fw_setenv m4_bin cm_hello_world.bin.ddr_debug

Finished: Please reboot, the m4 firmware will run during U-Boot

variscite-rproc-linux example on imx8mm-var-dart:

root@imx8mm-var-dart:~# /etc/remoteproc/variscite-rproc-linux -f /lib/firmware/cm_hello_world.elf.ddr_debug
Cortex-M: Stopping
[  359.212638] remoteproc remoteproc0: stopped remote processor imx-rproc
[  359.219709] remoteproc remoteproc0: powering up imx-rproc
Cortex-M: Loading cm_hello_world.elf.ddr_debug
[  359.227101] remoteproc remoteproc0: Booting fw image cm_hello_world.elf.ddr_debug, size 269100
[  359.238493] imx-rproc imx8mm-cm4: m4 ddr @ 0x7e000000
[  359.243584] remoteproc remoteproc0: no dtb rsrc-table
[  359.248797] imx-rproc imx8mm-cm4: Setting up stack pointer and reset vector from firmware in DDR
[  359.257626] imx-rproc imx8mm-cm4: Stack: 0x7e400000
[  359.262542] imx-rproc imx8mm-cm4: Reset Vector: 0x7e00030d
Cortex-M: Starting
[  359.318074] remoteproc remoteproc0: remote processor imx-rproc is now up

9 Debugging a demo

9.1 JTAG interface

Cortex-M debugging may require JTAG.

The VAR-SOM-MX8X exposes JTAG interface via an optional 10-pin header

Here the pinout

pin signal description pin signal (ball) description
1 JTAG_VREF JTAG reference voltage (3.3V) 2 JTAG_TMS (AG35) JTAG Mode Select
3 GND Digital Ground 4 JTAG_TCK (AE31) JTAG Clock
5 GND Digital Ground 6 JTAG_TDO (AF32) JTAG Data Out
7 RTCK JTAG Return clock 8 JTAG_TDI (AH34) JTAG Data In

Please refer to SOM datasheet for further details.

9.2 Debugging GUI

A detailed step by step procedure to debug using SEGGER J-Link is available online or in the following document:

~/var-mcuxpresso/freertos-variscite/docs/Getting Started with MCUXpresso SDK for MEK-MIMX8QX.pdf