Skip navigation
j-trace--product-icon.svg

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

Introduction

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 name Description Value
tlw TRACECLK LOW pulse width Min. 2 ns
thw TRACECLK HIGH pulse width Min. 2 ns
tr/tf Clock and data rise/fall time Max. 3 ns
tds Data setup time Min. 3 ns
tdh Data hold time Min. 2 ns

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

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 outputted 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

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
  //
  Project.SetJLinkScript("./ST_STM32F407_Modified_Traceconfig.JLinkScript");
}

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

Debug.Start();

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

Script executed: C:/Work/TestProjects/ST_STM32F407_84MHz_TraceExample/
ST_STM32F407_Modified_Traceconfig.JLinkScript

...

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:

Instruction_Trace_Window.PNG
Code_Profile_Window2.PNG

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 or using the integrated J-Trace PRO webserver.

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 the "Override Timings" checkbox needs to be enabled. Now either one delay for all data lines can be selected or for each individually.

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

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

Type 1: All data signals get output at the same time as TRACECLK

Type 2: All data signals have a fixed delay e.g. t1/2 that is directly dependent on the CPU clock speed

Type 3: All data signals have a fixed delay tad which is independent of the CPU clock speed