Skip navigation

J-Trace PRO - Setting up Trace

The following tutorial will explain how to setup streaming trace on a J-Trace PRO by using Ozone as a debugging tool. More information to streaming trace is available here: Streaming Trace




When using the J-Trace PRO as a debugging tool it is crucial for a successful session that the trace data output by the microcontroller is meeting specific timing requirements. The trace clock speed (TRACECLK) is on most microcontrollers directly dependent on the CPU clock speed and is usually half of the CPU clock speed.

The timing requirements are:

Signal nameDescriptionValue
twlTRACECLK LOW pulse widthMin. 2 ns
twhTRACECLK HIGH pulse widthMin. 2 ns
tr/tfClock and data rise/fall timeMax. 3 ns
tsData setup timeMin. 3 ns
thData hold timeMin. 2 ns

Note: J-Trace PRO has been designed to work with min. 1 ns ts and min. 1 ns th.

In some rare cases devices supporting Embedded Trace Macrocell (ETM) trace are not outputting signals that fulfill the aforementioned timing requirements. To still make trace debugging available to the customer the J-Trace PRO has a so called "Trace timing configuration" feature which compensates wrongly output trace data signals.

Minimum requirements

  • J-Link software version V6.14a or later
  • Ozone V2.22o or later
  • J-Trace PRO for Cortex-M HW version V1.0 or later
  • Setup Ozone project for target device

Trace timing diagram with CPU clock, TRACECLK and Trace data

Cortex-M Trace Reference Board

A Cortex-M Trace Reference Board will be used as an example device for the following setup as it is included in each J-Trace PRO delivery.

Setup - How To

To enable the trace pins the J-Trace PRO software will configure all needed pin settings for 4-bit tracing out-of-the-box for most supported devices and a simple launch of the debug session is sufficient to start streaming trace.

In all other cases or if you need to use less than 4-bits for tracing a J-Link script file needs to be loaded in your Ozone project. The  J-Link script file needs to be filled with code which initializes the trace pins and optionally sets trace data delays. To do this the template created by Ozone inside the .jdebug file needs to be filled with code as well.

In some trace example projects that are found on the SEGGER Wiki the projects will include .pex files instead of .JLinkScript files. They are however mutually interchangeable so only one of them needs to be present. A more technical guide on how to set up the J-Link script for tracing can be found here.

Create a .JLinkScript file in your project directory by creating an empty .txt file and renaming it to .JLinkScript at its end and add the function OnTraceStart() to it. The following code excerpt is taken from the example project for the Cortex-M Trace Reference Board which is available here.

The J-Link script file from the example project can be used as a reference on how to initialize trace pins, set additional settings on the J-Trace PRO etc.

*       OnTraceStart()
*  Function description
*    If present, called right before trace is started.
*    Used to initialize MCU specific trace related things like configuring the trace pins for alternate function.
*  Return value
*    >= 0:  O.K.
*     < 0:  Error
*  Notes
*    (1) May use high-level API functions like JLINK_MEM_ etc.
*    (2) Should not call JLINK_TARGET_Halt(). Can rely on target being halted when entering this function
int OnTraceStart(void) {
// Insert pin init here
return 0;

If you want to use 1-bit trace edit the line in the code example excerpt as shown. The minimum requirement for trace to work is the initialization of the TRACECLK pin and TD0 pin.  So make sure your the TRACECLK and TD0 pins get initialized by the J-Link script file. Use the example project as reference: Link

// Set Trace Portwidth(Optional): Default 4 Pin Trace, other possibilities: 1, 2, 4
JLINK_TRACE_PortWidth = 1;

To include the J-Link script file into your Ozone project open your .jdebug file in a text editor and navigate  to the entry BeforeTargetConnect. Make sure you uncomment the code block of the function. To include the J-Link script file use the function Project.SetJLinkScript("FilePath") like shown in the following code example.

*       BeforeTargetConnect
* Function description
*   Event handler routine. Optional.
void BeforeTargetConnect (void) {
  // Trace pin init is done by J-Link script file as J-Link script files are IDE independent

When everything is set as described you should get the following output in your Ozone output console:


File.Open ("C:\Work\TestProjects\ST_STM32F407_84MHz_TraceExample\ST_STM32F407_TraceExample_Ozone.jdebug");

File.Open ("./Output/Debug/Exe/ST_STM32F407_TraceExample.elf");

File.Open: completed in 19 ms


Project.SetJLinkScript ("./ST_STM32F407_Modified_Traceconfig.JLinkScript");

Script executed: C:/Work/TestProjects/ST_STM32F407_84MHz_TraceExample/


To view trace information in Ozone go to View -> Instruction Trace and View -> Code Profile.

After a successful start of the debug session the tracing information will be updated in the corresponding windows and should look similar to this:


Trace timing configuration

In some cases the microcontroller outputs trace data with timings that are not fulfilling the required specifications. For this reason the J-Trace PRO has the possibility to adjust the trace sampling timing by either using a exec command, using the integrated J-Trace PRO webserver or set the sampling delay directly in Ozone in trace settings. Note: The following approach might not work on some Arm targets as it is implementation defined if half-syncs are available which are needed for this troubleshooting steps. In such cases simply skip to the troubleshooting steps explained with Ozone below the next code snippet.

To open the webserver first you need to connect the J-Trace to a local area network. Make sure the network assigned a IP-address to the J-Trace PRO. To find out which IP-address has been assigned the J-Link Commander can be used like in the picture to the right. Just launch the J-Link Commander and the IP-address will be printed out.

Type the assigned IP-address into your browsers address bar and press enter. Now the main menu of the webserver should pop up. Navigate to the menu entry "Trace timing configuration". In this interface it is possible to shift the sample timing to an earlier moment or a later one by either adjusting all used trace pins at once or one by one. When the target device is halted J-Trace PRO will receive so called "half-sync patterns" which are being monitored by the webserver.

If the signal timing of the trace pins is correct the webserver will show a green "O.K.". Should the timings be incorrect the webserver page will show a red "Not O.K.". In that case the movement of the sampling point can resolve that issue by adjusting it until the webserver shows a green "O.K.".

When the correct sampling point setting has been found it can be implemented into the J-Link script file by using the exec command TraceSampleAdjust which is further explained in the manual. The following J-Link script file code excerpt shows an example of how to set the delay for all pins to +1 ns (default is 2 ns).

// Adjust sampling point of trace pin (Optional: not needed for this CPU)
JLINK_ExecCommand("TraceSampleAdjust TD=1000");

Alternatively Ozone can be used directly to set the number of used trace pins and the trace sampling  delay. To access this option simply open the trace project in Ozone and go to Tools->Trace Settings.

Here you can switch between different trace sources and the number of trace pins used. Default for ETM trace is Trace Source = Trace Pins and Trace Port Width = 4-bit.

To modify the trace sampling delays open the options under Trace Timing and set the the "Override Timings" checkbox. Now either one delay for all data lines can be selected or for each individually.

If the half-sync via webserver approach is not available to verify your setup you can verify the functionality of trace with Ozone. If you see trace data in the instruction trace window when the target device is halted and no trace related error message is printed in Ozone console the trace setup is currently stable.

Just make sure to restart the debug session each time you adjust the timing delays.


Trace troubleshooting

No or incorrect trace data?

  • Open the J-Trace PRO webserver as described in section "Trace timing configuration"
  • Is a trace clock present in the webserver?
    • If not check the target devices PLL init and TRACECLK init
  • Halt the target and check if the pattern test is successful
  • If not successful try to move the sampling point of the signals in the webserver until the pattern test returns successfully
    • Still no successful pattern test? Check if the voltage levels of the pins reach the correct values by measuring with a oscilloscope
  • Pattern test successful but still incorrect trace data? Check the set pin drive strength in your pin initialization and set it to highest/fastest possible and check if a lower trace clock (slow down the CPU clock speed in your PLL init) solves the issue
    • Should this not be sufficient measure the trace signals including the trace clock with an oscilloscope and check if they meet the timing requirements shown in the section "Introduction" and suitable high/low voltage levels
  • Still no trace data but trace clock present?
    • Switch to 1-bit trace mode by setting "JLINK_TRACE_PortWidth = 1" in the J-Link script file and initializing only the TD0 pin as usually the higher bit trace pins are shared with other peripherals and functions on e.g. evaluation boards, thus altering their output signals and making them unusable for trace

Web server approach not working or not available?

  • Alternative approach is to use Ozone directly. Set trace timing under Tools->Trace Settings and restart the debug session to apply changes. Halt application.
    • Still no trace data in instruction trace window and Ozone console shows trace error? Adjust trace settings again.
      • Still no trace data in instruction trace window and Ozone console shows trace error?Repeat prior step until no more error messages are showing and the instruction trace window shows all expected trace data.

    Common timings

    The following list shows common timing types that get output by some devices. You can use this charts to determine to which Type the microcontroller you are using belongs to by measuring with an oscilloscope. In most cases there are no additional actions required by the user to fix trace timing errors output by the microcontroller. Should trace not work out-of-the-box with the J-Trace PRO after initializing all pins and clocks correctly please refer to section "Troubleshooting".

    Most microcontrollers follow the rule that their trace clock speed is the current CPU frequency divided by two. In some other rare cases the microcontroller divides the trace clock even further or has a fixed clock value.


    Type 1: 50% duty cycle

    All data signals have a fixed delay e.g. t1/2 that is directly dependent on the CPU clock speed. This is the preferred timing type as it assures that the trace signals will keep their timing requirements at all CPU clock speeds as they are directly dependent of the CPU clock.


    Type 2: Trace data delayed

    All data signals have a fixed delay tad which is independent of the CPU clock speed. This timing type can be problematic at higher CPU clock speeds as the fixed independent delay might not be sufficient which could lead to incorrect sampling of trace data.


    Type 3: Trace clock delayed

    The trace clock has a fixed delay tad which is independent of the CPU clock speed. This timing type can be problematic at higher CPU clock speeds as the fixed independent delay might not be sufficient which could lead to incorrect sampling of trace data.


    Type 4: No delay

    All data signals toggle at the same time as TRACECLK. Without compensation this timing type can lead to incorrectly sampled trace data. Luckily the J-Trace PRO offers a built in feature that compensates this incorrect timing types. See section "Trace timing configuration" for more information.