Build and Install FreeRTOS for SMARC-iMX8M (Cortex-M4 core)

This document provides instructions for advanced users how Embedian offers patches and builds a customized version of FreeRTOS for Embedian's SMARC-iMX8M product platform and how to install the images to bring the evaluation board up and running. 

Our aim is to fully support our hardware through device drivers. We also provide unit tests so that testing a board is easy and custom development can start precisely. The recommended host environment is Ubuntu 16.04.

Before using this guide, we assume you understand how to setup a Yocto, Debian or Ubuntu working SD card. This guild apply to U-boot 2019.04 and Linux kernel 4.19.35 or higher. Here we are not mention Yocto/Debian/Ubuntu setup and compilation. There are well document available from Embedian.

There are several options in both processors, code can be located in one of the following:

• TCM (Tightly Coupled Memory): 128kB available
• DDR: up to 1MB available (can be increased, set in the device tree)

Note that the TCM is the preferred option when possible since it offers the best performances since it is an internal memory dedicated to the Cortex-M4.

External memories, such as the DDR, offer more space but are also much slower to access. 

In this article, it is assumed that every application runs from the TCM.

Availability

SMARC-iMX8M from Embedian

Carrier Board

EVK-STD-CARRIER-S20 (universal carrier board for all SMARC 2.0 modules) from Embedian

Basic Resources

• AArch64 Cross Compiler
  • Linaro: https://launchpad.net/linaro-toolchain-binaries
• Bootloader
  • Das U-Boot – the Universal Boot Loader http://www.denx.de/wiki/U-Boot
  • Source – http://git.denx.de/?p=u-boot.git;a=summary
• Linux Kernel
  • Linus's Mainline tree: http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=summary
  • Freescale Linux source tree: git://git.freescale.com/imx/linux-imx.git
  • Freescale BSP meta layer: git://git.freescale.com/imx/meta-fsl-bsp-release
  • OpenEmbedded/Yocto BSP layer for Freescale's ARM platform git://git.yoctoproject.org/meta-fsl-arm
  • Embedian SMARC-iMX8M kernel source tree for linux smarc-8m_imx_4.19.35_1.0.0: git@git.embedian.com:developer/smarc-fsl-linux-kernel.git
• ARM based rootfs
  • Debian Squeeze: http://www.debian.org/

ARM Cross Compiler: GCC

To build Embedian’s SMARC-iMX8M FreeRTOS, you will need to install the following ARM GNU gcc compiler first: 

For MCUXpresso 2.8.0 FreeRTOS, you need to use the following ARM GNU GCC coss compilier. 

Test:

If this test fails, verify that you have the 32bit libraries installed on your development system.

To download the source codes, you need to register at Embedian's git server first and put your ssh public key there.

Generating SSH Keys

We recommend you use SSH keys to establish a secure connection between your computer and Embedian Gitlab server. The steps below will walk you through generating an SSH key and then adding the public key to our Gitlab account.

Step 1. Check for SSH keys

First, we need to check for existing ssh keys on your computer. Open up Git Bash and run:

Check the directory listing to see if you have a file named either id_rsa.pub or id_dsa.pub. If you don't have either of those files go to step 2. Otherwise, you already have an existing keypair, and you can skip to step 3.

Step 2. Generate a new SSH key

To generate a new SSH key, enter the code below. We want the default settings so when asked to enter a file in which to save the key, just press enter.

Now you need to enter a passphrase.

Which should give you something like this:

Step 3. Add your SSH key to Embedian Gitlab Server

Copy the key to your clipboard.

Go to Embedian Git Server. At Profile Setting --> SSH Keys --> Add SSH Key 

Paste your public key and press "Add Key" and your are done.

Download Source Codes

For downloading the latest source code of FreeRTOS for SMARC-iMX8M, we have to use MCUExpresso SDK generator online tool. Below is the link: 

https://mcuxpresso.nxp.com/en/select

Embedian has customized it for SMARC-iMX8M.

The file structures are as below.

Install Required Packages 

Install cmake. 

Build ROMSG Sample Application

Change the directory to the application project directory, which has a path similar to the following:

This will compile and create binaries. The binaries will be available as <install_dir>freertos/boards/smarcimx8mq/multicore_examples/rpmsg_lite_str_echo_rtos/armgcc/release/rpmsg_lite_str_echo_rtos_imxcm4.bin

Same steps will be applied for other sample applications.

Test Application at U-Boot

Once you finished compilation of rtos application, you can test it at U-Boot first. Prepare a working SD card.

Bootup the device and stop at U-Boot Command Prompt.

You will see messages from Cortex-M4 debug port at SER2.

"RPMSG String Echo FreeRTOS RTOS API Demo..."

Setup SD Card

Assuming that you have a working Yocto/Debian/Ubuntu SD card.

Replace kernel device tree file:

The FreeRTOS examples uses SER2, I2C3 (I2C_GP, S48 and S49), GPIO0 (P108) and PWM3 (GPIO5). It is therefore, we need to disable those pin for Cortex-A53 and reserve a dedicate memory area for Cortex-M4. 
All available DTB files for Cortex-M4 are listed in the table below.

Replacing Kernel device tree file to adopt Cortex-M4

Pass Kernel Parameters to Kernel (uEnv.txt)

At uEnv.txt file, you need to add the following parameters.

$ sudo mount ${DISK}1 /media/boot/

$ sudo vim /media/boot/uEnv.txt

$ sudo umount /media/boot

Add the following parameter below the line "image=Image"

Add the following parameters in the "uenvcmd" and before "run mmcboot".

Boot up the device and you will see "M4 is started" at dmesg.

Demo Programs

In this section, we will show how to use the demo programs.

RPMsg TTY demo

This demo application demonstrates the RPMsg remote peer stack. It works with Linux RPMsg master peer to transfer string content back and forth. The Linux driver creates a tty node to which you can write to. The MCU displays what is received, and echoes back the same message as an acknowledgement. The tty reader on ARM Cortex-A53 core can get the message, and start another transaction. The demo demonstrates RPMsg’s ability to send arbitrary content back and forth.

Copy rpmsg_lite_str_echo_rtos.bin to the first partition of your SD card and add m4_bin=rpmsg_lite_str_echo_rtos.bin at uEnv.txt file. Boot up the device. You will see SER2 print out the following Cortex-M4 messages.

RPMSG String Echo FreeRTOS RTOS API Demo...

Nameservice sent, ready for incoming messages...

At device side,

You will see SER2 print out the following messages.

Get Message From Master Side : "hello world!" [len : 12]
Get Message From Master Side : "this is a test" [len : 14]
Get New Line From Master Side

RPMsg Ping Pong demo

Same as previous demo, this one demonstrates the RPMsg communication. After the communication channels are created, Linux OS transfers the first integer to FreeRTOS OS. The receiving peer adds 1 to the integer and transfers it back, a hundred times and then stops.

Copy rpmsg_lite_pingpong_rtos_linux_remote.bin to the first partition of your SD card and add m4_bin=rpmsg_lite_pingpong_rtos_linux_remote.bin at uEnv.txt file. Boot up the device. You will see SER2 print out the following Cortex-M4 messages.

RPMSG Ping-Pong FreeRTOS RTOS API Demo...
RPMSG Share Base Addr is 0xb8000000
Link is up!
Nameservice announce sent.

At device side,

You will see SER2 print out the following messages.

Waiting for ping...
Sending pong...
Waiting for ping...
Sending pong...
Waiting for ping...
Sending pong...
Waiting for ping...
Sending pong...
Waiting for ping...
Sending pong...
Waiting for ping...
Sending pong...
Waiting for ping...
Sending pong...
Waiting for ping...
Sending pong...
Waiting for ping... 

Hello World demo

The Hello World project is a simple demonstration program that uses the BSP software. It prints the “Hello World” message to the ARM Cortex-M4 debug terminal SER2.

Copy hello_world.bin to the first partition of your SD card and add m4_bin=hello_world.bin at uEnv.txt file. Boot up the device. You will see SER2 print out the following Cortex-M4 messages.

hello world. 

GPIO demo

The GPIO demo code uses GPIO0 as an example to toggle this pin.

Copy igpio_led_output.bin to the first partition of your SD card and add m4_bin=igpio_led_output.bin at uEnv.txt file. Boot up the device. You will see SER2 print out the following Cortex-M4 messages.

GPIO Driver example

The LED is blinking.

Use scope to measure GPIO0, you will see a square wave that means this pin is toggled.

PWM demo

The PWM demo code uses GPIO5 (PWM3) as an example.

Copy ipwm.bin to the first partition of your SD card and add m4_bin=ipwm.bin at uEnv.txt file. Boot up the device. You will see SER2 print out the following Cortex-M4 messages.

PWM driver example.

Use scope to measure GPIO5, you will see PWM signals

Setup eMMC

For SMARC-iMX8M, the SD card is always emulated as /dev/mmcblk1 and on-module eMMC is always emulated as /dev/mmcblk0. Setting up eMMC now is nothing but changing the device descriptor. 

Follow exactly the same steps as that set up SD card. This time, the first partition of eMMC will be /dev/mmcblk0p1.