TQMa93xxCA - YOCTO Linux BSP documentation

This guide describes how to prepare, build, run and debug Cortex-M33 MCUXpresso example applications on STKa93xxCA with Windows and Linux.

Unless otherwise specified, the commands apply to both operating systems.

Segger J-Link Debug Probe (optional)
BSP built according to Quickstart BSP Instructions
Windows 10/11 or Ubuntu 22.04 and above

On Windows Host

This section lists the required tools:

Python3 (including pip) (version 3.8 or above)
ARM GNU Toolchain (e.g. version 15.2rel1, use AArch32 bare-metal target (arm-gnu-toolchain-15.2.rel1-mingw-w64-i686-arm-none-eabi.msi))
optional: Segger J-Link Software (version 9.34b)
Visual Studio Code (VS Code)
VS Code Extension Cortex-Debug (ID: marus25.cortex-debug)
CMake (version 3.30 or above)
West (version 1.5.0 or above)
Ninja (version 1.13.0)

Download the installers and complete the installation wizards for Python, the ARM GNU Toolchain, Segger J-Link, and Visual Studio Code. If these tools are already installed, make sure their versions meet the version requirements mentioned above. CMake and West will be installed after the workspace is set up.

Remember the installation directories for the ARM GNU Toolchain and Segger J-Link as they are important later on.

In VS Code, install the Cortex-Debug extension. (ID: marus25.cortex-debug)

Create a local workspace directory:

mkdir workspace
cd workspace

The ARMGCC_DIR system variable must be set to the installation directory of the ARM GNU toolchain. (e.g. C:\Program Files (x86)\Arm\GNU Toolchain mingw-w64-i686-arm-none-eabi) This can be achieved in the Windows Settings → System → Advanced System Settings → Advanced → Environment Variables

On Linux Host

This section lists the required tools:

Python3 (including pip) (version 3.8 or above)
ARM GNU Toolchain (e.g. version 15.2rel1, use AArch32 bare-metal target (arm-gnu-toolchain-15.2.rel1-x86_64-arm-none-eabi.tar.xz))
optional: Segger J-Link Software (version 9.34b)
CMake (version 3.30 or above)
West (version 1.5.0 or above)
Ninja (version 1.13.0)

Install Python

sudo apt update  
sudo apt install git python3-full python-is-python3 python3-pip

Download and install the SEGGER J-Link software package: https://www.segger.com/downloads/jlink/JLink_Linux_x86_64.deb

cd ~/Downloads 
sudo dpkg -i JLink_Linux_V934b_x86_64.deb

Install the ARM GNU Linux Toolchain

wget https://developer.arm.com/-/media/Files/downloads/gnu/15.2.rel1/binrel/arm-gnu-toolchain-15.2.rel1-x86_64-arm-none-eabi.tar.xz
sudo tar --xz -xf arm-gnu-toolchain-15.2.rel1-x86_64-arm-none-eabi.tar.xz --directory /opt
rm arm-gnu-toolchain-15.2.rel1-x86_64-arm-none-eabi.tar.xz

Verify that ~/.profile contains the following entries:

cat ~/.profile

It should contain the following lines:

# set PATH so it includes user's private bin if it exists
PATH="$HOME/bin:$PATH"
# set PATH so it includes user's private bin for python if it exists
PATH="$HOME/.local/bin:$PATH"

Create an ARMGCC_DIR environment variable

export ARMGCC_DIR=/opt/arm-gnu-toolchain-15.2.rel1-x86_64-arm-none-eabi/

Note: The exported variable will be gone if the terminal is closed.

Create a local workspace directory:

mkdir ~/workspace
cd ~/workspace

Go to the root workspace directory and then clone the repository:

git clone https://github.com/tq-systems/mcuxsdk-examples-tq.git

Install necessary dependencies for the SDK:

pip install ninja jsonschema cmake west
pip install -r mcuxsdk-examples-tq/scripts/requirements.txt

Initialize the workspace

west init --local mcuxsdk-examples-tq 
west update

Note: If the installed commands (e.g. west) are not recognized, their installation directory needs to be added to the PATH environment variable.

For Windows, add the following to the system environment:
C:/Users/<Username>/AppData/Roaming/Python/Python3x/Scripts

For Linux, execute:
export PATH=$PATH:$HOME/.local/bin

Remove old builds if necessary

On Windows Host

rmdir build /s

On Linux Host

rm -rf ./build

Available example applications for TQMa93xxCA:

List of Applications

Demo	Path used in the build command	Description
CANFD Ping Pong	`driver_examples/flexcan/canfd_ping_pong_buffer_transfer`	Demonstrates CANFD message ping pong between two boards over CAN bus.
FlexCAN Ping Pong	`driver_examples/flexcan/ping_pong_buffer_transfer`	Demonstrates CAN message ping pong between two boards over CAN bus.
Hello World	`demo_apps/hello_world/`	Hello World demo, to make sure everything has been set up correctly.
NPU Firmware	`eiq_examples/ethosu/ethosu_apps_rpmsg`	NPU firmware, needed for NXP ETHOSU driver and software stack.
RGPIO Input Interrupt Demo	`driver_examples/rgpio/input_interrupt`	Uses the Cortex-M33 to detect edges at a GPIO pin.
RGPIO LED Output Demo	`driver_examples/rgpio/led_output`	Uses the Cortex-M33 to toggle a GPIO pin periodically.
RPMSG Ping Pong	`multicore_examples/rpmsg_lite_pingpong_rtos_linux/remote`	Demonstrates inter-core communication between Cortex-A55 and Cortex-M33.

Additional information about the example applications on TQMa93xxCA can be found on our GitHub. For information about a specific application, refer to the corresponding example directory.

Build the Example:

west build -b tqma93xxca-mba93xxca mcuxsdk-examples-tq/_boards/tqma93xxca-mba93xxca/examples/<application_path>/ -Dcore_id=cm33 -DCUSTOM_BOARD_ROOT="mcuxsdk-examples-tq/_boards" --config=debug
#e.g.
west build -b tqma93xxca-mba93xxca mcuxsdk-examples-tq/_boards/tqma93xxca-mba93xxca/examples/demo_apps/hello_world/ -Dcore_id=cm33 -DCUSTOM_BOARD_ROOT="mcuxsdk-examples-tq/_boards" --config=debug

Build configuration and parameters:

Parameters:

-DCUSTOM_BOARD_ROOT: Necessary for board definitions outside of the mcuxsdk directory.
-Dcore_id: Target core for the build (e.g. cm7, cm33).
--config: Optional, used to set the build configuration. Uses configuration debug by default.
--pristine: With this parameter, the build directory is cleaned before the build process.

Build Configurations:

Build Configuration	Description
debug	Build for SRAM with full debug symbols and no optimization
release	Speed- and size-optimized build for internal memory

The final build is located in build/<application_name>.elf.

It is possible to execute the example applications directly on the target from either U-Boot or Linux. The applications can also be debugged via VS Code or GDB-Server.

It is advised to refer to our GitHub documentation, as some examples require additional configuration or setup steps before they can be executed successfully..

Boot the Board
Connect the Starterkit to the host as described in the STKa93xxCA Quickstart Guide and open two new serial terminals with the first and second virtual serial interfaces. The first interface will print serial output from the board's Linux and the second interface will receive the serial output from Cortex M33.

To run the demos on the target directly, load the .bin and .elf onto a USB flash drive or an SD card.

Run the Demo from U-Boot
Boot the Starterkit and stop at the U-Boot prompt. Execute the following commands:

# when loading from usb
usb start
load usb 0:1 ${loadaddr} <application_name>_cm33.bin
# or when loading from SD
load mmc 1:1 ${loadaddr} <application_name>_cm33.bin

cp.b ${loadaddr} 0x201e0000 ${filesize}
bootaux 0x1ffe0000 0

The demo's output should be printed in the Cortex-M33 terminal.

Run the Demo from Linux
Boot the Starterkit into Linux. Make sure to select the imx93-tqma9352-mba93xxca-rpmsg.dtb device tree when prompted in U-Boot. Alternatively, use setenv fdtfile imx93-tqma9352-mba93xxca-rpmsg.dtb.

Copy the .elf file of the example application from USB or SD into /lib/firmware. Write the application name to /sys/class/remoteproc/remoteproc0/firmware:

echo <application_name>_cm33.elf > /sys/class/remoteproc/remoteproc0/firmware

Start the demo:

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

The demo's output should be printed in the Cortex-M33 terminal.

The demo can be stopped using:

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

Configure VS Code Settings
Open the workspace in VS Code and create a folder .vscode in the workspace root. Create a settings.json with the following content and modify the installation paths

{
    "cortex-debug.gdbPath": "<arm-none-eabi-gdb.exe path>",
    "cortex-debug.armToolchainPath": "<arm-none-eabi-gcc.exe path>",
    "cortex-debug.JLinkGDBServerPath": "<JLinkGDBServerCL.exe path>",
    "cortex-debug.variableUseNaturalFormat": true,
}

Note: The content can also be copied from /mcuxsdk-examples-tq/templates/settings.json

Create a launch.json with the following content and change the device specification if necessary:

{
    "configurations": [
        {
            "showDevDebugOutput": "both",
            "type": "cortex-debug",
            "request": "launch",
            "name": "Debug J-Link RAM i.MX93",
            "cwd": "${workspaceFolder}",
            "executable": "${workspaceFolder}/build/hello_world_cm33.elf",
            "servertype": "jlink",
            "device": "MIMX9352_M33",
            "interface": "jtag",
            "serverArgs": [
                "-endian", 
                "little",
                "-LocalhostOnly",
                "-speed", 
                "4000"
            ],
            "postLaunchCommands": [
                "target remote localhost:50000",
                "monitor reset",
                "monitor halt",
                "load"
            ]
        }
    ]
}

Note: The content can also be copied from /mcusdk-examples-tq/_boards/tqma93xxca-mba93xxca/templates/launch.json

Boot the Board
Connect the Starterkit to the host as described in the STKa93xxCA Quickstart Guide and open two new serial terminals with the first and second virtual serial interfaces. The first interface will print serial output from the board's Linux and the second interface will receive the serial output from Cortex M33.

Run the Demo
In VS Code, swap to the Run and Debug section on the left side and choose “Debug J-Link RAM i.MX93” from the dropdown menu. Then, click the green PLAY button (or press F5).

The program will be loaded onto the board and will start the main function. A “Hello World” text should be printed on the serial console

Boot the Board
Connect the Starterkit to the host as described in the STKa93xxCA Quickstart Guide and open two new serial terminals with the first and second virtual serial interfaces. The first interface will print serial output from the board's Linux and the second interface will receive the serial output from Cortex M33.

Open the Debugserver
Open a terminal and start the J-Link GDB Server. Change the device specification (here: MIMX9352_M33) if necessary.

JLinkGDBServerCLExe -device MIMX9352_M33 -if JTAG -speed 4000 -port 50000

Note: On Windows, make sure that JLinkGDBServerCL.exe is available via the PATH environment variable or use the full path to the executable.

Run the Demo
Open a second terminal and start GDB.

# Windows
& '.\Program Files (x86)\Arm\GNU Toolchain 15.2 mingw-w64-i686-arm-none-eabi\bin\arm-none-eabi-gdb.exe'

# Linux
/opt/arm-gnu-toolchain-15.2.rel1-x86_64-arm-none-eabi/bin/arm-none-eabi-gdb

With GDB, execute the following to start debugging the demo

file <PATH.elf>
target remote localhost:50000
monitor reset
monitor halt
load
monitor go

The demo's output should be printed in the Cortex-M33 terminal.

TQMa93xxCA - YOCTO Linux BSP documentation

Prerequisites

Prepare Host System

Set up Workspace

Compile the Application

Run and Debug the Demo

Run the Demo on the Target

Run the Demo using VS Code

Run and Debug the Demo using GDBServer