Adapt Polyspace Test Target Package for TRACE32 Instruction Set Simulator

The TRACE32 Instruction Set Simulator (ISS) is a software-only tool that simulates CPU instruction execution without requiring physical target hardware. Even if you have the physical target hardware, the ISS is powerful for debugging — it provides a reproducible, hardware-independent environment that simplifies test iteration. You can adapt an existing Polyspace® Test™ target registration package to use the ISS for debugging workflows.

Start by copying the folder structure from your existing target registration package (see Create Target Registration Packages for C/C++ Test Execution on Targets). Then apply the modifications described below.

Prerequisites

Before you begin, you need:

  • A working Polyspace Test target registration package for your board. See Create Target Registration Packages for C/C++ Test Execution on Targets for a tutorial on authoring target registration packages. The tutorial outlines the steps needed to create a target registration package using the STM32 Nucleo-144 board (with STM32F767ZI MCU) as an example.

    The example below can be adapted to any hardware board, but it uses the folder structure outlined in the previous tutorial for the STM32 Nucleo-144 board as a reference:

    STM32Package/
├── 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
├── targetUtilities/
│   ├── STM32F767ZI_ExecutionTool.m   #Optional - MATLAB code for executing applications on target
│   ├── src/
│   │   ├── customRtiostream.h
│   │   ├── customRtiostream.c # Implementation of rtiostream API for communicating with target
│   │   ├── STM32F767ZI_board.h
│   │   ├── STM32F767ZI_board.c # Implementation of target initialization function
└── README.md

    To begin adapting your target registration package, make a copy of the package folder (for instance, STM32Package above) and rename the folder to LauterbachISSPackage

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

  • 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, you see the path to the T32XIL toolbox installation folder. You will need to copy files from this installation folder into your target registration package (see next section).

TRACE32 Files Overview

When adapting your package for TRACE32, you work with three TRACE32-specific files in addition to your existing registration files. Template versions of these files are available (either directly in the subfolder or a further release-specific subfolder).

FilePurpose
trace32_settings.m

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

A template version of this file is available in a subfolder 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.

A template version of this file is 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.

A template version of this file is available in a subfolder demos/pil_referenced/<targetName>/<releaseNumber> in the T32XIL toolbox installation folder.

Copy the template versions of these files into the root folder where you will create the new target registration package. Your updated package looks like this:

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 file
├── simulinktemplate.config.t32 #Trace32 file
├── trace32_<target>_startup.cmm #Trace32 file
├── targetUtilities/
│   ├── STM32F767ZI_ExecutionTool.m   #Optional - MATLAB code for executing applications on target
│   ├── src/
│   │   ├── customRtiostream.h
│   │   ├── customRtiostream.c # Implementation of rtiostream API for communicating with target
│   │   ├── STM32F767ZI_board.h
│   │   ├── STM32F767ZI_board.c # Implementation of target initialization function
└── README.md

The following sections describe the adaptations you might need to make to the template versions of the Trace32 files.

Configure TRACE32 Config File

Compare the template version of the file simulinktemplate.config.t32 with the example below and check if you need to adapt some of the 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 (borrowing from a USB probe) is one example. Your setup may differ depending on your Lauterbach license type.

  • 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

You typically do not need to modify the .cmm file. 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).

An example startup script is shown below. The specifics of the script will change depending on the template version you started from.

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.

Configure trace32_settings.m

Update the settings file trace32_settings.m to provide the paths to the TRACE32 files, trace32_startup.cmm and simulinktemplate.config.t32.

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 in this file. 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)

Update JSON Target Preferences

Add the T32XIL toolbox installation path to your targetpreferences.json using the JSON key T32XilToolbox.

For instance, the JSON file from the previous tutorial with the addition of the new JSON key looks like this:

{
    "ProgrammerPath": "C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeProgrammer/bin/STM32_Programmer_CLI.exe",
    "GnuARMPath": "C:/ST/STM32CubeIDE_1.16.1/STM32CubeIDE/plugins/com.st.stm32cube.ide.mcu.externaltools.gnu-tools-for-stm32.12.3.rel1.win32_1.0.200.202406191623/tools",
    "DriverPath": "C:/ProgramData/supportpackages/stm32/stm32f7xx_based/stm32f7xx_dpfp/boards/nucleo_f767zi",
    "ToolchainName": "GCC ARM Cortex M | STM32F767ZI",
    "BoardName": "STM32F767ZI Nucleo",
    "TargetConnectionName": "STM32 F767ZI - Host Connection",
    "COMPORT" : "COM3"
    "T32XilToolbox": "C:/Users/<user>/AppData/Roaming/MathWorks/MATLAB/Polyspace Add-Ons/T32XIL"
}

Update File That Reads JSON Preferences

Update the definition of the class STM32F767ZI_Preferences to inherit from pstest.target.Trace32.TargetPreferences (instead of the standard pstest.target.TargetPreferences):

classdef STM32F767ZI_Preferences < pstest.target.Trace32.TargetPreferences
    methods(Access=public)
        function this = MyBoard_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

Instead of a regular execution tool, you will use a tool that starts and tracks an application on the target hardware through a debugger.

If you defined the execution tool as a class in a file STM32F767ZI_ExecutionTool.m, remove the file. Instead, in a file STM32F767ZI_DebugIOTool.m, create 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.

Your final target registration package looks like this:

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 file
├── simulinktemplate.config.t32 #Trace32 file
├── trace32_<target>_startup.cmm #Trace32 file
├── STM32F767ZI_DebugIOTool.m #MATLAB code to run applications through a debugger
├── targetUtilities/
│   ├── src/
│   │   ├── customRtiostream.h
│   │   ├── customRtiostream.c # Implementation of rtiostream API for communicating with target
│   │   ├── STM32F767ZI_board.h
│   │   ├── STM32F767ZI_board.c # Implementation of target initialization function
└── README.md

You will next make modifications to the package registration file packageRegister.m.

Adapt Target Registration File

Adapt the target registration file (packageRegister.m) for ISS mode. The ISS mode differs significantly from a standard TRACE32 registration in several key ways.

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

In ISS mode, register the execution service under the DebugIOTool API (to allow breakpoint-based debugging). The implementation of the API comes from the class STM32F767ZI_DebugIOTool class you defined 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;

Comment Out InitializationCode

When using the TRACE32 ISS, comment out or remove the InitializationCode property on the target.MainFunction object. The DebugIOTool API manages execution using breakpoints, so initialization is not needed.

mainFunction = target.create("MainFunction", "Name", "Test Main");

% mainFunction.InitializationCode = 'HAL_Init(); SystemClock_Config();';

Remove rtiostream Implementations from Build Dependencies

When using the DebugIOTool API, the framework automatically provides its own rtiostream implementation (rtiostreamdebuggerio.c). You do not need to supply any custom rtiostream implementation. Remove the paths to manual rtiostream source file from your build dependencies.

For instance, if you are using the package from the previous tutorial, you would comment out or remove these lines:

% comms.APIImplementations.BuildDependencies.SourceFiles = [ ...
%     baseSoftDir, '/customRtiostream.c' ...
%];

% comms.APIImplementations.BuildDependencies.IncludeFiles = [ ...
%     baseSoftDir, '/customRtiostream.h' ...
%];

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.

    • If you have previously registered the non-debug version of the package, unregister the package first using packageUnregister.m.

    • Register the debug version of the package using the adapted 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 upto 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 of the target.mainFunction object was not removed (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