Readme

This guide contains instructions for configuring the build system, building targets, and executing the demonstration applications included in this repository, specifically designed for TQ-developed boards using the i.MX MCU family from NXP.

Table of content

[[TOC]]

Getting started

Requirements:

NOTE: The versions provided are the ones with which the build system and its artifacts were tested.

• Arm GNU Toolchain: arm-gnu-toolchain-12.2.rel1-[host system]-arm-none-eabi
• GCC: 12.2.1
• Visual Studio Code: v1.8.1^
• NXP's MCUXpresso SDK: MCUX_2.14.0_UPDATE_ENHC1
• CMake: v3.27.4
• West: v1.0.0
• Python: v3.10.4
• For Windows:
  • MinGW: v13.1.0
• For Debug only:
  • Segger J-link: v7.92l

VS-Code extensions

• CMake tools (from Microsoft): v1.16.3^
  • ID: ms-vscode.cmake-tools
  • Advice: Check if the 'Status-Bar-Visibillity' option is set to 'visible'.
• For Debug only:
  • Cortex-Debug (from marus25): v1.12.0^,
    • ID: marus25.cortex-debug

Preparation

• Python3 installation (needed for west repo tool and helper scripts).
• Install Arm GNU Toolchain. Use the .exe-file for installation or unpack the archive to the desired path.
• Install CMake and make sure that CMake is added to the system path.
• Windows only: Install MinGW and add its bin directory to the system PATH variable. For example: <Path to MinGW>/MinGW/bin.
• Set environmental variable ARMGCC_DIR pointing to the toolchain installation dir:
  • Use the "cmake.environment" option under settings.json.
  • create a system variable.
• Debugging only: Install Segger J-link (Version used: 7.92).
• Clone via 'west' NXP's mcu-sdk repository following the instructions under Clone repository from NXP.

Clone repository from NXP

This repository uses NXPs mcuxsdk repository. NXP's mcuxsdk uses the Zephyr West Tool to manage multiple Git repositories.

To clone the NXP's mcu-sdk repository using West, open a terminal and execute the following commands:

pip install west
cd  <project path>\dependencies
west init -m https://github.com/NXPmicro/mcux-sdk --mr MCUX_2.14.0_UPDATE_ENHC1 mcuxsdk
cd mcuxsdk
west update

NOTE: You can also install mcuxsdk in another path. If you did so, set MCUXSDK_ROOT enviroment varialbe to mcuxsdk path before building. Use the same procedure as for the variable ARMGCC_DIR.

Afterwards copy replace_include_guards.py into the same directory as of the mcuxsdk. ATTENTION: This step is absolute necessary!

After downloading the SDK from NXP using West, the Python script replace_include_guards.py must be run once. This is required because targets set to global cannot be built in the same build folder due to the existing include guards in the cmake files in NXP SDK.

cd <project path>
python3 <project path>/dependencies/replace_include_guards.py

This step will be executed automatically everytime CMake generates the build-system. CMake will check for the patched.txt file in your mcuxsdk dir after every execution. If this file exists, the patch script won't be executed again through a build command.

Building

Building from command line

When using from command line, cmake has to know where to find the toolchain:

• Set environment variable ARMGCC_DIR pointing to toolchain installation dir.
• If using multiple versions of cmake in parallel, you can define a variable CMAKE pointing to the executable to use.
• Use following flags to configure your build from the cmake commandline.

Flag	Meaning
CMAKE_TOOLCHAIN_FILE	must point to <project path>/dependencies/mcuxsdk/core/tools/cmake_toolchain_files/armgcc.cmake
CMAKE_BUILD_TYPE	following different types are tested in SDK: Debug, Release
bootDisk	Linker file selection Ram, Flash

• Settings for bootDisk
  • Ram: Linking for TCM.
  • Flash: Linking for QSPI NOR.

NOTE: Linking for SD-Ram isn't available yet and is planed to be included.

• Set the build directory to the path build using -B <project path>/build.
• Set the build generator using -G <your generator>.

Generate build system command

cd <project path>
cmake -DCMAKE_TOOLCHAIN_FILE="dependencies\mcuxsdk\core\tools\cmake_toolchain_files\armgcc.cmake" -DCMAKE_BUILD_TYPE="Debug" -DbootDisk="Ram" -B ".\build" -G "MinGW Makefiles" --fresh

• Build the target.

Build target command

cd <project path>
cmake --build ".\build" --config Debug --target < name of .elf-file or "all" > -j 14 -- 

Building with VS-Code

When using the VS-Code support, the following additional steps are needed:

• Install VS-Code.
• Follow instructions for setting up VS-Code.

Flags like CMAKE_TOOLCHAIN_FILE, CMAKE_BUILD_TYPE, bootDisk should be set in .vscode folder. Use the examples for guidance.

Setting up VS-Code

• Open Visual Studio in the applications folder.
• Please refer to the example templates when setting up VS-Code. You should have at least the same .json-files and .yaml-files in your .vscode folder by the end of this section.
• Install the CMake tools extension by Microsoft.
  • Ctrl+P: ext install ms-vscode.cmake-tools or search for the extension under the menu extensions on the left bar.
  • Adjust settings.json in the .vscode folder accordingly to your environment: Click here to open the example file for Windows.
  • Ensure you got the cmake-variants.yaml file.
• For Debug only: Install cortex-debug extension from marus25.
  • either use Ctrl+P and ext install marus25.cortex-debug
  • or search for the extension under the menu extensions on the left bar
  • Set up the desired configurations for debug on VS-Code. You will need two files, one to configure the debug settings for VS-Code (settings.json) and a second to setup the debugger configuration (launch.json). Here is an entire guide for setting up VS-Code in order to use J-Link segger as debugger with VS-Code.
• ATTENTION: Please refer, if existing, to the README of your board for further details on setting up the debugger. Some boards may require special settings.
  • The Readme should be placed under: examples/README.md.

Building target

After fulfillment of the preparations VS-Code should be displaying the CMake-Tools option on the lower bar. In order to build a target, select the build variant by clicking on the corresponding option. You can also select your target by clicking on "set default build target".

Click after selection of the desired options on "Build" to build your target(s).

Optionally you can choose the target within the CMake-menu-bar.

Loading targets

Before running a target, make sure you've minded the boot instructions of your board.

Loading a target via GDB Server

If you prefer to boot without VS-Code follow the instructions for debugging within the boards README.

Loading a target VS-Code

You can follow the instructions for debugging with VS-Code.

Debugging

Debugging with VS-Code

The repository utilizes JLinkGDBServerCL alongside the appropriate hardware for debugging in VS-Code. To initiate debugging, you need to configure the debug tool. Once configured, select the debug tool from the left menu bar and choose the desired debug configuration specified within the launch.json. To begin debugging, either click on start debugging or press F5.

• ATTENTION: Please refer, if existing, to the README of your board for further details on setting up the debugger. Some boards may require special settings.
  • The Readme should be placed under: examples/README.md.

Applications

The list of all applications can found in board README file.

Build system

Structure of repository

The general structure is constituted in such a way that it was tried to create as little maintenance effort for the demo repo as possible. Thus, everything that can be summarized in higher-level folders is also deposited there.

Folder/File	Description
templates	Examples for the VS-Code setting files.
templates/cmake-variants.yaml	The Build-Type configurations.
templates/settings.json	Configurations for CMake and the cortex-debug-tool.
templates/launch.json	All debug configurations.
examples	Path for the demo-applications.
examples/board	Generic files used for every app and board specific information/configuration.
examples/board/cmake	CMake related files used for integrating the board in the build system.
examples/board/<file>.mex	Configuration file used in MCUX-Config Tools.
build	All build-related files.
build/boards/<boardtype>/dist	Location for images.
cmake	Location for CMake scripts.
dependencies	Dependencies and dependencies related files.
dependencies/TQDevices	Custom programmed APIs used for the applications.
dependencies/mcuxsdk	The downloaded repository from NXP.
dependencies/replace_include_guards.py	A patch script for the mcusdk.
doxy	Doxy-file generator configurations.
scripts	Scripts for automated build tests and version generation.

The build system was created based on the specifications of NXP. Accordingly, for each app in NXP's repo, all sources from the Driver-APIs and other libs are added to the target named MCUX_SDK_PROJECT_NAME using the target_sources() command. This target is created in the CMakeLists.txt from the application. This scheme is basically also used in this repo. However, all Include-Guards were changed from Global to Directory using the patch script replace_include_guards.py. This has the consequence that one build directory can now be used for all apps here. Using the add_subdirectory() command, a directory is added per level, so that there are no conflicts per target. However, this has the disadvantage that the order of all includes must be correct.

Programming apps

This guide provides instructions and hints on how to structure the build system within the context of the MCUXpresso-SDKs and the build system structure within this repository when creating new apps or boards.

When creating a new application, a new folder for the application has to be created and the CMakeLists.txt file located in .../examples must be updated. A new CMakeLists.txt file should be placed within the new application directory. You can use any of the CMakeLists.txt files from the demo applications as a template. When a new directory with an application is created, it must be added to examples/CMakeLists.txt. The variables specified in the examples/CMakeList.txt folder must be adjusted accordingly.

The CMakeLists.txt file in the examples/<app_name> directory ensures the correct inclusion of files. To use flags_macros for linking/compiling and to configure NXP's modules, create a config.cmake file. Templates for this can also be found in the demo applications.

You can add special files globally to all targets by adding them to the var BOARD_SRCS or specific to one target by adding them to the list under add_executable. Mind that you also should point to the directory where they are located by adding it to target_include_directories, if the directory you are using is newly created.

If you need own board files instead of the default one in this repository, reset the BOARD_SRCS variable with your own file list and the BoardDirPath variable with the directory you're aiming for.

Compiler and linker flags are set in the flags.cmake file in the examples/board/cmake directory. However, to configure specific flags, use the config.cmake file in the application folder. There is also a flags_macros.cmake file under cmake in top level dir.

When programming, use the linker scripts provided by TQ. You can include your own linker files using the set commands with the vars:

set(LINKER_FILE_RAM "<your_path>")
set(LINKER_FILE_FLASH "<your_path>")
...

The command should be placed in the CMakeLists.txt of the application directory before including flags.cmake.

The examples under mcuxsdk/examples can be helpful for learning about NXP's API.

License

Except where otherwise noted, all files within this repository are licensed under the following terms, excluding build system files (such as .cmake), configuration files for development environments (such as Visual Studio Code setup files):

SPDX-License-Identifier: BSD-3-Clause

Copyright (c) 2021 - 2023 TQ-Systems GmbH license@tq-group.com, D-82229 Seefeld, Germany. Author: Isaac L. L. Yuki

Support Wiki

Please refer to our support wiki for more information.