Run and Debug C/C++ Tests on Target Using TRACE32 (T32XIL Toolbox Workflow)

R2026b

TRACE32 is software from Lauterbach that lets you load programs onto target hardware, run them, and inspect what they're doing. TRACE32 includes an Instruction Set Simulator (ISS) — a software-only mode that simulates the target without any physical hardware. This is useful for fast iteration and debugging in a reproducible environment.

This topic shows how to create a Polyspace® Test™ target registration package that uses the TRACE32 ISS with the T32XIL toolbox for host-target communication.

Before using this workflow, consider using the FDX (Fast Data Exchange) workflow instead — it works on both physical hardware and the ISS without requiring the T32XIL toolbox. See Run and Debug C/C++ Tests on Target Using TRACE32. Use the T32XIL workflow described here only if FDX is not supported for your target architecture.

Prerequisites

Before you begin, you need:

  • TRACE32 PowerView installed on your machine. Download from the Lauterbach Portal.

  • Java® Runtime Environment (JRE™) installed on your machine. You can obtain a JRE by installing OpenJDK®, an open-source implementation of the Java platform.

  • The T32XIL toolbox (t32xil.mltbx) installed using:

    polyspace-test -manage-addon -install -source t32xil.mltbx
    The .mltbx file is located in the TRACE32 installation under demo/env/matlabsimulink/. For more information, see polyspace-test -manage-addon.

    Once the installation completes, note the path to the T32XIL toolbox installation folder. You will need this path later when configuring your JSON preferences file.

TRACE32 Files Overview

Your target registration package uses three TRACE32-specific files in addition to the standard registration files. You can use template versions from the T32XIL toolbox installation folder as a starting point, or create them from scratch.

FilePurpose
trace32_settings.m

MATLAB function returning a struct with TRACE32 configuration (paths to executable, startup script, config file, timeouts).

Template available in demos/pil_referenced/<targetName>/<releaseNumber> in the T32XIL toolbox installation folder.

simulinktemplate.config.t32

TRACE32 configuration file specifying the debug interface mode, system paths, and TCP ports for communication.

Template available at the root level of the T32XIL toolbox installation folder.

trace32_<target>_startup.cmm

TRACE32 PRACTICE script that loads the ELF binary and configures the debug session.

Template available in demos/pil_referenced/<targetName>/<releaseNumber> in the T32XIL toolbox installation folder.

The complete package has this structure:

LauterbachISSPackage/
├── targetpreferences.json           #Preferences file
├── STM32F767ZI_Preferences.m       #MATLAB code to read preferences file
├── packageRegister.m                #MATLAB code for package registration
├── packageUnregister.m              #MATLAB code to unregister package
├── trace32_settings.m               #TRACE32 settings file
├── simulinktemplate.config.t32      #TRACE32 config file
├── trace32_<target>_startup.cmm    #TRACE32 startup script
├── STM32F767ZI_DebugIOTool.m       #MATLAB code to run applications through a debugger
└── README.md

The packageUnregister.m file undoes the registration. It calls target.remove on the connection and rmpath on the paths added by packageRegister.m.

The following sections describe how to create or configure the remaining files.

Configure TRACE32 Config File

Create a file named simulinktemplate.config.t32 in your package folder with these settings:

; (1) Debug interface mode
PBI=*SIM
USB
INSTANCE=AUTO

; (2) System paths
OS=
ID=TRACE32
SYS=C:\T32\bin\windows64

; (3) Communication ports
RCL=NETASSIST
PORT=20000
PACKLEN=1024

RCL=NETTCP
PORT=20001
PACKLEN=1024

Key settings:

  • PBI=*SIM with USB and INSTANCE=AUTO — The licensing configuration shown here obtains the simulator license from a USB-attached probe. Your setup may use a different license type (such as a node-locked or floating license).

  • SYS= — must point to the <installFolder>\bin\<arch> folder of your TRACE32 installation (for example, C:\T32\bin\windows64). This is where the TRACE32 executables (such as t32marm.exe) are located.

  • RCL=NETASSIST on port 20000 — used by the T32XIL toolbox for remote API control.

  • RCL=NETTCP on port 20001 — the rtiostream data channel used for test result transfer. This is the port you reference in packageRegister.m.

Configure Startup Script

Create a .cmm startup script for your target. The script must:

  • Accept the ELF path as a parameter.

  • Guard hardware-specific settings with IF (!SIMULATOR()) or IF SIMULATOR() ... ELSE.

  • Load the ELF.

  • Not issue a Go command. The DebugIOTool manages execution, so if the script issues Go, the target starts running before the toolbox is ready, and the test hangs or times out.

An example startup script is shown below. Adjust the CPU type and hardware-specific commands for your target.

ENTRY %LINE &ELF_FILE

IF (!OS.FILE(&ELF_FILE))
(
    PRINT %ERROR "The target binary location must be passed to the script."
    ENDDO
)

SYStem.CPU STM32F756ZG
IF SIMULATOR()
(
  TRACE.OFF
)
ELSE
(
  SYStem.CONFIG.DEBUGPORTTYPE SWD
  IF COMBIPROBE()||UTRACE()
  (
    SYStem.CONFIG.CONNECTOR MIPI20T
  )
  SYStem.Option DUALPORT ON
  SYStem.MemAccess DAP
  SYStem.JtagClock 10MHz
  Trace.DISable
)
SYStem.Up

Data.LOAD "&ELF_FILE"
sYmbol.ECA.LOADALL /SkipErrors

Mode.Mix
List.Mix

ENDDO

The example wraps all hardware debug port configuration (SYStem.CONFIG.DEBUGPORTTYPE, SYStem.MemAccess, and similar) inside the ELSE block. The simulator does not support these commands and they can cause the session to fail silently.

sYmbol.ECA.LOADALL /SkipErrors loads debug symbol information from all ELF sections, suppressing errors for sections that cannot be resolved. This is useful when the ELF references external libraries whose symbols are not available on the simulator.

Configure trace32_settings.m

Create a file named trace32_settings.m that returns a struct with paths to your TRACE32 files.

function cfg = trace32_settings()
    cfg = struct;
    cfg.T32_Executable       = 't32marm.exe';
    cfg.T32_Startupscript    = 'C:\path\to\your\trace32_startup.cmm';
    cfg.T32_Config           = 'C:\path\to\your\simulinktemplate.config.t32';
    cfg.Target_Binary_Extension = '.elf';
    cfg.rlm_license          = '';
    cfg.Timeout_Init         = 1000;
    cfg.Timeout_Transfer     = 1000;
    cfg.Timeout_T32RemoteApi = 1000;
    cfg.Hardware_Timer       = '';
    cfg.Stack_Profiler       = '';
end

Use full absolute paths to the files trace32_startup.cmm and simulinktemplate.config.t32. The T32XIL toolbox calls this function by name, so the file must be named trace32_settings.m and be on the MATLAB path (the addpath call in packageRegister.m ensures this). The trace32_settings.m file is the central configuration that the T32XIL toolbox reads to locate all TRACE32 components:

T32XIL toolbox calls trace32_settings()
    ├── cfg.T32_Config        → .t32 config file (debug interface, ports)
    ├── cfg.T32_Startupscript → .cmm script (loads ELF, configures CPU)
    └── cfg.T32_Executable    → TRACE32 PowerView executable (such as t32marm.exe)

Create JSON Target Preferences

Create a targetpreferences.json file with paths to your toolchain, board drivers, and the T32XIL toolbox installation folder.

{
    "GnuARMPath": "C:/path/to/your/gcc-arm-toolchain/tools",
    "DriverPath": "C:/path/to/your/board/drivers",
    "ToolchainName": "GCC ARM Cortex M | STM32F767ZI",
    "BoardName": "STM32F767ZI Nucleo",
    "TargetConnectionName": "STM32 F767ZI - Host Connection",
    "T32XilToolbox": "C:/Users/<user>/AppData/Roaming/MathWorks/MATLAB/Polyspace Add-Ons/T32XIL"
}

Create Preferences Class

Create a file STM32F767ZI_Preferences.m that defines a class inheriting from pstest.target.Trace32.TargetPreferences. This class reads the JSON preferences file and provides TRACE32-specific configuration to other package files.

classdef STM32F767ZI_Preferences < pstest.target.Trace32.TargetPreferences
    methods(Access=public)
        function this = STM32F767ZI_Preferences(jsonName)
            arguments
                jsonName (1,1) string = "targetpreferences.json"
            end
            jsonFullPath = fullfile(fileparts(which(mfilename)), jsonName);
            this@pstest.target.Trace32.TargetPreferences(jsonFullPath);
        end
    end
end

Create DebugIOTool Class

The DebugIOTool starts and tracks an application on the target through a debugger, allowing breakpoint-based debugging of tests.

Create a file STM32F767ZI_DebugIOTool.m with a class that inherits from pstest.target.Trace32.DebugIOTool and passes your preferences to the base class.

classdef STM32F767ZI_DebugIOTool < pstest.target.Trace32.DebugIOTool
    methods
        function this = STM32F767ZI_DebugIOTool
            this@pstest.target.Trace32.DebugIOTool(STM32F767ZI_Preferences());
        end
    end
end

Save this file in the root folder of your package.

Create Target Registration File

Create the target registration file packageRegister.m. This file registers the board, toolchain paths, execution service, and communication channel with the Polyspace Test framework.

Create Board and Processor

Create the board and processor objects, and attach a MainFunction.

board = target.create("Board", "Name", prefs.BoardName);
processor = target.create("Processor", "Name", "STM32F767ZI", "Manufacturer", "ST");
board.Processors = processor;

mainFunction = target.create("MainFunction", "Name", "Test Main");
board.MainFunctions = mainFunction;
On the ISS, the DebugIOTool provides its own rtiostream implementation, so you do not need to add source files or include paths to the MainFunction.

Add Paths

Add the T32XIL toolbox paths to the MATLAB path. Save the current search path. The savepath call persists the addpath calls so the target remains registered across Polyspace sessions.

currentFilePath = fileparts(mfilename('fullpath'));
addpath(currentFilePath);
jsonFullPath = fullfile(currentFilePath, 'targetpreferences.json');
prefs = STM32F767ZI_Preferences(jsonFullPath);
addpath(prefs.T32XilToolbox);

if savepath
    warning('Error while saving path!');
end
rehash toolboxcache;

Register DebugIOTool API

Register the execution service under the DebugIOTool API to allow breakpoint-based debugging. The implementation comes from the STM32F767ZI_DebugIOTool class you created earlier.

customExecutionService = target.create("APIImplementation", ...
    "Name", "STM32F767ZI - Execution Service Implementation", ...
    "API", target.get("API", "DebugIOTool"), ...
    "BuildDependencies", target.create("MATLABDependencies", "Classes", "STM32F767ZI_DebugIOTool"));

executionService = target.create("ExecutionService", ...
    "Name", "STM32F767ZI - Target Process Execution", ...
    "APIImplementation", customExecutionService);

board.Tools.DebugTools = executionService;

Add PILDebugIOProtocol

Add the following protocol to your board to deactivate timeout so that execution can stop at breakpoints:

debugProtocol = target.internal.create("PILDebugIOProtocol", "Name", "STM32F767ZI DebugIOProtocol");
debugProtocol.BreakpointPollingWaitTime = 10000;
board.Inner.CommunicationProtocolStacks = debugProtocol;

Configure TCP Connection

Configure the TCP connection with the correct port matching your .config.t32 file:

connection = target.create("TargetConnection");
connection.Name = prefs.TargetConnectionName;
connection.CommunicationChannel = target.create("TCPChannel", "Name", "MyBoard TCPChannel");
connection.CommunicationChannel.IPAddress = "localhost";
connection.CommunicationChannel.Port = 20001;
connection.Target = board;

The port must match the RCL=NETTCP port in your .config.t32 file (default: 20001). A mismatch means MATLAB cannot receive test results from the target.

Register and Run

To register and use the target in the Polyspace Platform user interface:

  1. Open a project configuration. On the toolstrip, select Manage Boards. Register the package using the packageRegister.m file you created in this example.

  2. On the Build tab of the configuration, select your board name for the option Target board name (Testing).

  3. On the Project toolstrip, select Debug.

  4. Build your project and run tests as usual. The TRACE32 PowerView software opens, loads the ELF file created during build, stops at a breakpoint, and allows you to perform further debugging. For instance, you can search and find the function under test, place a breakpoint in the function, continue up to the breakpoint and poll variables.

Troubleshooting

SymptomLikely Cause
Build succeeds but "timeout receiving data"TCP port mismatch between packageRegister.m and .config.t32.
PowerView opens but no breakpoint hitThe InitializationCode property was set on the target.MainFunction object (target hangs in HAL init), or an ExecutionTool API was registered instead of DebugIOTool.
Linker error: multiple definition of rtIOStreamOpenYou have a build dependency on a file with a custom implementation of the rtiostream API. Remove the build dependency.
"TRACE32 class not found in path"T32XIL toolbox was not installed, or the path to the toolbox installation folder was not added to the JSON file.
PowerView opens with errors about SWD/debug portStartup .cmm script applies hardware debug commands without IF (!SIMULATOR()) or IF (SIMULATOR()) ... ELSE guard.

See Also

Topics