TQMa93xxLA - YOCTO Linux BSP documentation

TQMa93xxLA - YOCTO Linux BSP documentation

This guide describes how to prepare, build and run a Cortex-M33 MCUXpresso hello world demo on STKa93xxLA with Windows and Linux.

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

Prerequisites

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

Prepare Host System

On Windows Host

This section describes the installation of the following tools:

Python3 (including pip) (version 3.8 or above)
ARM GNU Toolchain (e.g. version 15.2rel1)
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)

Set up a workspace directory in a local 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 describes the installation of the following tools:

Python3 (including pip) (version 3.8 or above)
ARM GNU Toolchain (version 15.2rel1)
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

Check the ~/.profile

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.

Set up the workspace directory

mkdir ~/workspace
cd ~/workspace

Set up Workspace

Go to the root workspace directory and then clone the Git 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 location needs to be added to PATH first.

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

Compile the Demo

Remove old builds if necessary

On Windows Host

rmdir build /s

On Linux Host

rm -rf ./build

Build the demo

west build -b tqmba93xxca mcuxsdk-examples-tq/_boards/tqmba93xxca/examples/demo_apps/hello_world/ -- -Dcore_id=cm33 -DCUSTOM_BOARD_ROOT="mcuxsdk-examples-tq/_boards"

The final build is located in ~/build/hello_world_cm33.elf.

Run and Debug the Demo

On Windows Host

Configure VS Code settings

Open the workspace and create a folder .vscode in the root directory. 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": "MIMX9332_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/tqmba93xxca/templates/launch.json

Boot the Board

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 boards Linux and the second port 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

On Linux Host

Boot the Board

Connect the Starterkit to the Host as described in the STKa93xxLA Quickstart Guide and open two new serial terminals with the first and second COM Port device. The first port will print serial output from the boards Linux and the second port will receive the serial output from Cortex M33.

Open the Debugserver

Open another terminal and open the debugserver there. Change the device specification (here: MIMX9332_M33) if necessary.

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

Run the Demo

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

Table of Contents

TQMa93xxLA - YOCTO Linux BSP documentation

Prerequisites

Prepare Host System

Set up Workspace

Compile the Demo

Run and Debug the Demo

Configure VS Code settings

Boot the Board

Run the Demo

Boot the Board

Open the Debugserver

Run the Demo