How to configure JLinkScript files to enable tracing

From SEGGER Wiki
Jump to: navigation, search

This article will describe how to enable trace with a J-Link script file for supported target devices.

Introduction

To enable tracing on a target device, two configurations must be met:

  1. The trace related Arm Coresight module needs to be set up (done automatically by J-Link software)
  2. Target device specific pins and SFRs need to be initialized (done by the user in the J-Link Script file)

For the best trace experience, we recommend using Ozone: https://www.segger.com/products/development-tools/ozone-j-link-debugger/

Generic Guide

  1. Create a J-Link script file by creating a plain text file and renaming it to Filename.JLinkScript and open it in a text editor.
  2. Add the function OnTraceStart() to the J-Link script file. (more information about script file functions in the J-Link User Manual UM08001)
  3. Locate the trace pins used on your board schematics.
  4. Initialize the trace pins and enable the trace clock with the corresponding clock registers if needed.
  5. If available, configure additional trace config registers that are not part of Arm Coresight modules.
  6. Set the script file in your IDE/debugger of choice: Using J-Link Script Files
  7. Connect the J-Trace via the trace connector to your target.
  8. Start tracing.

Example Setup

Prerequisites

The following prerequisites must be met to be able to work with the example setup:

The example project is already configured to run out-of-the-box with Ozone. However, this tutorial is meant to teach how to create a new configuration for any target device that is supported.

Setup

In the example project, you will find a .JLinkScript file that already configures the target device correctly. This script file will now be used as reference to explain how a script file would be created for the Cortex-M Trace Reference Board from scratch.

The Cortex-M Trace Reference Board is based on an ST STM32F407VE.

  1. Get a copy of the STM32F407VE Reference Manual from ST, this documentation will be needed to have all necessary register information.
  2. Create a J-Link script file by simply creating a plain text file and renaming it to Filename.JLinkScript.
  3. Add function OnTraceStart() to the J-Link script file. It follows C like syntax, which is explained further in the J-Link user manual.
  4. Locate the trace pins used on your board schematics, in case of the example device pins PE2-PE6 are used for tracing.
  5. For most Arm Cortex devices peripheral clocks for GPIOs are disabled after reset, in case of the example device register RCC_AHB1ENR needs to be edited to enable the GPIOE clock.
  6. Access 32-bit registers through the script file by using JLINK_MEM_ReadU32() and JLINK_MEM_WriteU32().
  7. Set the corresponding GPIO registers to enable alternate function mode for pins PE2-PE6, we recommend using the highest speed setting for trace pins to stay within timing requirements for trace.
  8. For the example device there is an additional device specific trace register that must be set, it is called DBGMCU_CR. In this register, the used pin (1-4) must be configured and trace enabled.
  9. Save the script file and set it in your IDE/debugger of choice: Using J-Link Script Files
  10. Start tracing.

Troubleshooting

Do you get no or incorrect trace data? Consider the following troubleshooting steps:

  • Check if registers need to be unlocked first.
  • Check if the correct peripheral clocks have been enabled, the clock tree in the target device manual should give more insight.
  • Check if the correct pins are configured, on some devices the GPIO settings must be set in the right order.
  • Check if there is an additional device specific trace related register which needs to be configured.
  • Make sure there are no capacitive or inductive elements connected to the trace lanes (e.g. Diodes, capacitors, inductors etc.).
  • Some target devices allow multiple sets of trace pins that can be activated, if you are mixing them make sure that this is supported by the MCU.
  • Does the issue persist when using Ozone instead? Some IDE/debugger vendors do not support all trace features that the J-Trace PRO offers.
  • Make sure your application does not repurpose the trace pins during run time for other peripherals or functionality.
  • In some cases the target device's ROM table is not complete or broken so J-Trace PRO can't autodetect the Arm trace components. In such a case, the trace component addresses need to be added manually so the generic trace init can be executed. Keep in mind that there are sometimes multiple memory spaces on one target device, so make sure the addresses you are setting are accessible by an external debug probe. An example script implementation for this can be found here: Adding missing ROM table entries