MCUXpresso
Overview
Release Notes
For full details about this release, refer to the Release Notes.
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 may 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 EVK-MIMX8MP.pdf.
Prerequisites
Before starting, prepare a Yocto boot SD card (with kernel 4.14.98 or newer).
To allow Cortex M7 accessing shared resources without experiencing Linux kernel conflicts, a dedicated device tree must be loaded, containing m7 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 M7.
| File Name |
Description |
|---|---|
| imx8mp-var-dart-dt8mcustomboard-m7.dtb | DART-MX8M-PLUS device tree blob for kernel >= 5.4.70 (Yocto Zeus) on DT8MCustomBoard 2.x |
| imx8mp-var-dart-dt8mcustomboard-legacy-m7.dtb | DART-MX8M-PLUS device tree blob for kernel >= 5.4.70 (Yocto Zeus) on on DT8MCustomBoard 1.x |
| imx8mp-var-som-symphony-m7.dtb | VAR-SOM-MX8M-PLUS device tree blob for kernels >= 5.4.70 (Yocto Zeus) on on Symphony-Board |
| imx8mp-var-som-symphony-2nd-ov5640m7.dtb | VAR-SOM-MX8M-PLUS device tree blob for kernels >= 5.4.70 (Yocto Zeus) on on Symphony-Board with 2nd OV5640 |
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 https://developer.arm.com/-/media/Files/downloads/gnu-rm/9-2020q2/gcc-arm-none-eabi-9-2020-q2-update-x86_64-linux.tar.bz2 $ 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 https://github.com/varigit/freertos-variscite -b mcuxpresso_sdk_2.9.x-var01 $ cd freertos-variscite
Documentation
Original NXP documentation is available online or in the following folder:
~/var-mcuxpresso/freertos-variscite/docs
Demos pins
Default M7 pins used by the demos are:
| Function | SoC balls | DART-MX8M-PLUS pins | DT8MCB pins | VAR-SOM-MX8M-PLUS pins | Symphony pins | Notes |
|---|---|---|---|---|---|---|
| UART3 RX/TX | AE6 / AJ4 | J2.87 / J2.89 | J12.11 / J12.13 | |||
| UART4 RX/TX | AH5 / AJ5 | J1.115 / J1.171 | J18.9 / J18.7 | |||
| GPIO3_IO14 | R26 | J1.79 | J17.10 | |||
| GPIO4_IO03 | AF10 | J2.59 | GPLED1 on DT8MCB rev 1.x J11.20 on DT8MCB rev 2.x |
|||
| I2C3 SCL/SDA | AJ7 / AJ6 | J3.46 / J3.42 | J12.18/ J12.20 | |||
| I2C4 SCL/SDA | AF8 / AD8 | J1.92 / J1.90 | J16.13 / J16.15 | Enabling it SPI devices will be no longer visible from Linux | ||
| PWM2 | D8 | J1.69 | J18.2 | |||
| PWM3 | AE18 | J3.36 | J14.7 | |||
| SPI1 CS0/SCK/SDI/SDO | AE20 / AF20 / AD20 / AC20 | J2.79 / J2.77 / J2.81 / J2.83 | J16.4/ J16.2 / J16.8 / J16.6 | Enabling it SPI devices will be no longer visible from Linux | ||
| SPI2 CS0/SCK/SDI/SDO | AJ22 / AH21 / AH20 / AJ21 | J1.39 / J1.43 / J1.41 / J1.45 | J16.4/ J16.2 / J16.6 / J16.8 | Enabling it SPI devices will be no longer visible from Linux |
Available demos
All of the Variscite examples are located under the following folder
~/var-mcuxpresso/freertos-variscite/boards/dart_mx8mp ~/var-mcuxpresso/freertos-variscite/boards/som_mx8mp
The available demos for DART-MX8M-PLUS are:
- driver_examples/i2c/interrupt_b2b_transfer/slave
- driver_examples/i2c/interrupt_b2b_transfer/master
- driver_examples/i2c/polling_b2b_transfer/slave
- driver_examples/i2c/polling_b2b_transfer/master
- driver_examples/wdog
- driver_examples/sdma/scatter_gather
- driver_examples/sdma/memory_to_memory
- driver_examples/gpio/led_output
- driver_examples/pwm
- driver_examples/uart/auto_baudrate_detect
- driver_examples/uart/interrupt
- driver_examples/uart/interrupt_rb_transfer
- driver_examples/uart/polling
- driver_examples/uart/interrupt_transfer
- driver_examples/gpt/timer
- driver_examples/gpt/capture
- driver_examples/ecspi/ecspi_loopback
- driver_examples/ecspi/interrupt_b2b_transfer/slave
- driver_examples/ecspi/interrupt_b2b_transfer/master
- driver_examples/ecspi/polling_b2b_transfer/slave
- driver_examples/ecspi/polling_b2b_transfer/master
- driver_examples/rdc
- driver_examples/tmu/monitor_threshold
- driver_examples/tmu/temperature_polling
- driver_examples/sema4/uboot
- rtos_examples/freertos_ecspi/ecspi_loopback
- rtos_examples/freertos_hello
- rtos_examples/freertos_queue
- rtos_examples/freertos_sem
- rtos_examples/freertos_generic
- rtos_examples/freertos_uart
- rtos_examples/freertos_tickless
- rtos_examples/freertos_mutex
- rtos_examples/freertos_event
- rtos_examples/freertos_swtimer
- rtos_examples/freertos_i2c
- cmsis_driver_examples/i2c/int_b2b_transfer/slave
- cmsis_driver_examples/i2c/int_b2b_transfer/master
- cmsis_driver_examples/uart/interrupt_transfer
- cmsis_driver_examples/ecspi/int_loopback_transfer
- cmsis_driver_examples/ecspi/sdma_loopback_transfer
- multicore_examples/rpmsg_lite_str_echo_rtos
- multicore_examples/rpmsg_lite_pingpong_rtos/linux_remote
- demo_apps/hello_world
- driver_examples/uart/idle_detect_sdma_transfer
- driver_examples/uart/sdma_transfer
- cmsis_driver_examples/uart/sdma_transfer
Almost all of the above demos are also available for EVK-MIMX8MP.
You can build and run the demos following official NXP documentation for EVK-MIMX8MP, available online or in the following document:
~/var-mcuxpresso/freertos-variscite/docs/Getting Started with MCUXpresso SDK for EVK-MIMX8MP.pdf
Building a demo
Building Manually
For any demo, follow these steps:
$ cd ~/var-mcuxpresso/freertos-variscite/boards/dart_mx8mp $ cd <demo_folder> $ cd armgcc $ export ARMGCC_DIR=~/var-mcuxpresso/gcc-arm-none-eabi-9-2020-q2-update $ ./build_all.sh > /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 card or eMMC) in the /boot folder already hosting the Linux device trees.
Building Using Yocto
In Yocto Zeus 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_dart | TCM | U-Boot |
| /boot/cm_<demo name>.bin.debug_som | TCM | U-Boot |
| /boot/cm_<demo name>.bin.ddr_debug_dart | DDR | U-Boot |
| /boot/cm_<demo name>.bin.ddr_debug_som | DDR | U-Boot |
| /lib/firmware/cm_<demo name>.elf.debug_dart | TCM | Linux Remoteproc Framework |
| /lib/firmware/cm_<demo name>.elf.debug_som | TCM | Linux Remoteproc Framework |
| /lib/firmware/cm_<demo name>.elf.ddr_debug_dart | DDR | Linux Remoteproc Framework |
| /lib/firmware/cm_<demo name>.elf.ddr_debug_som | 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
# Yocto Hardknott and older SRC_URI_remove = "git://github.com/varigit/freertos-variscite.git;protocol=git;branch=${MCUXPRESSO_BRANCH};" SRC_URI_append = " <your Git repository>" # Yocto Kirkstone and newer SRC_URI:remove = "git://github.com/varigit/freertos-variscite.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:
# Yocto Hardknott and older CM_DEMOS_append = "rtos_examples/freertos_hello" # Yocto Kirkstone and newer 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/
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-M7 as described in related linker file.
| memory type | M7 memory area | A53 memory area | memory lentgh | linker file |
|---|---|---|---|---|
| DDR | 0x80000000-0x801FFFFF (code) 0x80200000-0x803FFFFF (data) 0x80400000-0x80FFFFFF (data2) |
0x80000000-0x801FFFFF (code) 0x80200000-0x803FFFFF (data) 0x80400000-0x80FFFFFF (data2) |
16MB (DDR) | MIMX8MN6xxxxx_cm7_ddr_ram.ld |
| TCM | 0x00000000-0x0001FFFF (code) 0x20000000-0x2001FFFF (data) 0x80000000-0x80FFFFFF (data2) |
0x007E0000-0x007FFFFF (code) 0x00800000-0x0081FFFF (data) 0x80000000-0x80FFFFFF (data2) |
256kB (TCM) + 16MB (DDR) | MIMX8MN6xxxxx_cm7_ram.ld |
All linker files are locate in the armgcc folder of each demo.
The DDR reserved area must match the one declared in the kernel device tree: at least 1 GB of RAM is required on the SoM to allow Cortex-M7 accessing the range 0x80000000 - 0x80FFFFFF.
The RPMSG area is located at 0x40000000: all SoMs allow Cortex-M7 accessing the RPMSG area.
After launching the build_all.sh 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 the following i.MX 8M Plus Applications Processor Reference Manual paragraphs:
- 2.2 Cortex-A53 Memory Map
- 2.3 Cortex-M7 Memory Map
Running a demo
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_m7 yes; saveenv
To disable Cortex-M:
=> setenv use_m7 no; saveenv
Binary demos must be loaded to the memory type used for linking.
To use TCM:
=> setenv m7_addr 0x7E0000; saveenv
To use DDR:
=> setenv m7_addr 0x80000000; saveenv
To set the name of the Cortex-M binary
=> setenv m7_bin myapp.bin; saveenv
The .bin file is expected in the folder /boot of the booting media.
The U-Boot boot command will handle loading the Cortex-M firmware and start Linux for DART-MX8M-PLUS.
For testing, it is possible to run the firmware manually:
=> run loadm7bin && run runm7bin
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 EVK-MIMX8MP.pdf
Please refer to the Yocto Scripts section below for more information
Running a demo from Linux
The Linux remoteproc framework can be used to load the Cortex m7 firmware from Linux userspace.
On i.MX 8M platforms, "remoteproc" stops only the Cortex-M CPU, not the Cortex-M system. Therefore, any in-flight Cortex-M bus transactions would hang after the CPU is halted and this can only be resolved with a full SoC reset. It is not recommended to stop the Cortex-M7 CPU in a production system. If the system must stop the Cortex-M7 CPU, reload the image and restart it. Then, the Cortex-M7 CPU must be in the WFI state and have no external access to the Cortex-M7 TCM memory through eDMA or other similar transactions. A possible solution is to implement a handshake between the Cortex-M and Cortex-A CPUs to confirm that the Cortex-M CPU is safe to stop or reset.
Follow these steps to verify the Linux remoteproc framework is supported for your release:
- Select the software release from the DART-MX8M-PLUS software overview page.
- Click on Release Notes.
- Look for the Cortex m7 Linux remoteproc support row in the release notes to see which version is supported. If Cortex m7 Linux remoteproc support is not in the release notes table, the Linux remoteproc framework is not supported.
After confirming Linux remoteproc support, follow these steps to use the framework:
Boot Linux after following the steps in #Running a demo from U-Boot
Increase kernel loglevel while debugging:
# sysctl kernel.printk=7;
Check the state of the m7, it should be running already by U-Boot
# cat /sys/class/remoteproc/remoteproc0/state
If the state is 'running', stop the m7
# 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
Please refer to the Yocto Scripts section below for more information
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 |
Examples 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
Debugging a demo
JTAG Hardware
The Cortex-M firmware can be debugged using a JTAG debugger. Variscite recommends using a Segger J-Link Ultra+, J-Link Pro, or J-Link Wi-Fi debugger. You may also need a 9-pin Cortex-M adapter from Segger.
JTAG interface
The VAR-SOM-MX8M-PLUS exposes JTAG interface via an optional 10-pin header, on the SOM top left side.
The DART-MX8M-PLUS exports JTAG interface via an optional 10-pin header, on the DT8MCustomBoard top side.
Here is the pinout:
| pin | signal | description | pin | signal | description |
|---|---|---|---|---|---|
| 1 | JTAG_VREF | JTAG IO reference voltage, connected to SOM_3V3_PER via 150 Ohm. |
2 | JTAG_TMS | JTAG Mode Select signal |
| 3 | GND | Digital Ground | 4 | JTAG_TCK | JTAG Clock signal, include PD of 8.2K Ohm. |
| 5 | GND | Digital Ground | 6 | JTAG_TDO | JTAG Data Out signal |
| 7 | GND | Digital Ground | 8 | JTAG_TDI | JTAG Data In signal |
| 9 | JTAG_TRST_B | JTAG Reset signal, active low signal |
10 | POR_B | Programmer Reset, used to put the SOC in reset state. |
Please refer to SoM datasheet for further details.
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 EVK-MIMX8MP.pdf
Developing with Visual Studio Code
Visual Studio Code, which is freely available, can be used to develop and debug MCUXpresso firmware:
For a full guide demonstrating how to get started, please refer to MCUXpresso Development with VS Code.
Add support to SOMs with 1GB DDR
MCUXpresso:
$ cd freertos-variscite $ ./var_add_1GB_support.sh -b dart_mx8mp # for DART-MX8M-PLUS $ ./var_add_1GB_support.sh -b som_mx8mp # for VAR-SOM-MX8M-PLUS
U-Boot:
Following the guide at the Running a demo from U-Boot section above:
Change "setenv m7_addr 0x80000000" to "setenv m7_addr 0x7E000000" (when running for DDR):
$ setenv m7_addr 0x80000000" to "setenv m7_addr 0x7E000000" $ print ramsize_check
Check the cma_size related to the condition if test $sdram_size -le 1024; then setenv cma_size cma=xxxM;
if the xxxM value is greater than or equal to 640M then change to 512M:
$ setenv ramsize_check 'if test $sdram_size -le 512; then setenv cma_size cma=320M; else if test $sdram_size -le 1024; then setenv cma_size cma=512M; else setenv cma_size cma=960M; fi; fi;'
Save the environment changes:
$ saveenv
Kernel:
In the file arch/arm64/boot/dts/freescale/imx8mp-var-common-m7.dtsi
Change the following section:
m7_reserved: m7@0x80000000 {
no-map;
reg = <0 0x80000000 0 0x1000000>;
};
To:
m7_reserved: m7@0x7e000000 {
no-map;
reg = <0 0x7e000000 0 0x1000000>;
};
Build the updated dtb files:
$ make dtbs files
Then copy the generated *m7.dtb files to the /boot folder on the SD card/eMMC.
Filesystem:
In the file /etc/remoteproc/variscite-rproc.conf
Change the following section:
readonly CM_LOAD_ADDR_DDR="0x80000000"
To:
readonly CM_LOAD_ADDR_DDR="0x7e000000"