TQMa93xxLA - YOCTO Linux BSP documentation

This guide describes how to prepare, build, run and debug Cortex-M33 MCUXpresso example applications on STKa93xxLA 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 TQMa93xxLA:

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 TQMa93xxLA 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 run the example applications from U-Boot or Linux. Specific instructions for each demo can be found on our GitHub.

The applications can also be debugged via VS Code on Windows or via GDB-Server on Linux.

On Windows Host

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

Connect the Starterkit to the host as described in the STKa93xxLA Quickstart Guide and open two new terminals with the first and second COM port devices. The first port will print serial output from the board's Linux and the second port will receive the serial output from Cortex M33.

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

On Linux Host

Connect the Starterkit to the host as described in the STKa93xxLA 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 another terminal and open the debugserver there. Change the device specification (here: MIMX9352_M33) if necessary.

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

Connect to the GDB server in the first terminal

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

Execute the following to start debugging the demo

target remote localhost:50000
monitor reset
monitor halt
load ~/workspace/build/hello_world_cm33.elf 
monitor go

The second serial terminal should print a “hello world.” message.

TQMa93xxLA - YOCTO Linux BSP documentation

Prerequisites

Prepare Host System

Set up Workspace

Compile the Application

Run and Debug the Demo

Configure VS Code settings

Boot the Board

Run the Demo

Boot the Board

Open the Debugserver

Run the Demo