From Variscite Wiki
VAR-SOM-MX8X - MCUXpresso 2.5.2

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 i.MX 8QuadXPlus.pdf.

1.2 iMX8 QM/QX boot flow

The boot process for iMX8QM/QX SoCs begins at Power On Reset (POR) where the hardware reset logic forces the System Controller (SCU) to begin execution starting from its on-chip boot ROM.

The platform boot is performed by the SCU and the Security Controller (SECO), working in concert to ensure that the intended and authorized set of images are loaded and started on various processing domains contained by the SoC.

The SCU plays the role of platform manager: it's the core that will interpret the boot settings, configure the interfaces/boot sources, look for the containers with boot images, and load these to the target on-chip or external memories.

Both the SCU and the SECO start execution, upon SoC POR, in their respective ROM memories.

A firmware (FW) image will be loaded for each as part of the boot process.

The images that will be loaded as part of the boot process are stored in containers.

A container can contain one or multiple images, as blocks of data specifying the load address, target address, etc.

At least two containers are needed for the boot process:

  • The first container will only contain the SECO FW Image.
  • The second container will typically contain:
    • The SCU FW image (SCFW)
    • The DDR Initialization image (embedded in SCFW)
    • The Cortex-M4 FW image(s)
    • The FW image(s) for the Cortex-A processing domain


In this scenario, the SCU plays the critical role to assign the resources before loading the Cortex-M4 and Cortex-A images.

Once the SCFW assigns specific resource to the Cortex-M4, this resource is not even visible from the Cortex-A, avoiding the need of dedicated device trees to prevent resource contentions.

2 Prerequisites

As explained above, the SCU is in charge to assign resources before loading the images.

This means that the SCFW must be customized and rebuilt in order to assign required resources and pins to the M4.

You can build it by following the Build SCFW from source code page, but remember the default build will not enable M4 resources.

Before starting the building stage describe in paragraph 3 of the above link, we propose the following additional patch

$ cd imx-scfw-porting-kit/src
$ wget
$ cd scfw_export_mx8qx_b0
$ patch -p1 < ../0002-mx8qxp-var-som_scfw-1.2.2_sample-M4-customization.diff

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
$ wget
$ tar xvf gcc-arm-none-eabi-7-2018-q2-update-linux.tar.bz2

Download MCUXpresso SDK for the SOM:

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

4 Documentation

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


5 Demos pins

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

6 Available demos

All of the Variscite examples are located under the following folder


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 i.MX 8QuadXPlus.pdf

7 Building a demo

7.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-7-2018-q2-update
$ ./ > /dev/null

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

The M4 image need now to be integrated in U-Boot.

You can build U-Boot by following the Build U-Boot from source code page, but remember that you need to use a different build target and link the M4 image.

To build a boot image, replace the commands available in the above page (at the end of secion 3), with

$ ln -sf <full_path_to_M4_image.bin> m4_image.bin
$ make -f soc.mak clean
$ make -f soc.mak SOC=iMX8QX MKIMG=./mkimage_imx8 PAD_IMAGE=./ <flash_target>
$ mv flash.bin imx-boot-sd.bin

There are two possible flash_targets: the flash_target must match the linker options used to generate the binary (refer to the next section for further detains):

For BSP 4.14.98_2.0.0

  • flash_regression_linux_m4: for images generated in the release folder (M4 code located in TCM)
  • flash_regression_linux_m4_ddr: for images generated in the ddr_release folder (M4 code located in DDR)

For new version of BSPs

  • flash_linux_m4: for images generated in the release folder

7.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/

8 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

9 Running a demo

9.1 Running a demo from U-Boot

Since the SCU will automatically read and load the Cortex-M application, no actions are required by the users.

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

10 Debugging a demo

10.1 JTAG Hardware

The Cortex-M firmware can be debugged using a JTAG debugger. Variscite recommends using a J-Link Pro or J-Link Wi-Fi debugger. You may also need a 9-pin adapter from Segger.

10.2 JTAG interface

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

Here is 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.

10.3 Developing with IAR Embedded Workbench

NXP provides a detailed step by step procedure to develop and debug MCUXpresso firmware using IAR Embedded Workbench and SEGGER SEGGER J-Link. Please refer to online or in the following document:

~/var-mcuxpresso/freertos-variscite/docs/Getting Started with MCUXpresso SDK for i.MX 8QuadXPlus.pdf

10.4 Developing with Visual Studio Code

Visual Studio Code, which is freely available, can be used to develop and debug MCUXpresso firmware:

Vscode MCUXpresso StoppedAtBreakPoint.png

For a full guide demonstrating how to get started, please refer to MCUXpresso Development with VS Code.