Difference between revisions of "Setting Up Trace with Ozone"

From SEGGER Wiki
Jump to: navigation, search
(Setup Requirements)
(Setup Requirements)
Line 61: Line 61:
 
=== Setup Requirements ===
 
=== Setup Requirements ===
   
  +
Ozone's trace settings are configured via Ozone commands (or the trace settings dialog) as described below.
The following sections describe the debugger commands that can be executed from the project script in order to to configure trace with Ozone.
 
   
 
== Trace Settings Overview ==
 
== Trace Settings Overview ==

Revision as of 22:51, 8 January 2020


Introduction

This wiki article describes the configuration of trace within Ozone. For a general overview about trace with J-Link and J-Trace, please refer to SEGGER's website and the J-Link/J-Trace user guide.

Trace Features Overview

Ozone's trace features consist of the following elements:

Debug Window Description
Instruction Trace Window Displays the history of executed machine instructions.
Code Profile Window Displays program execution metrics (code coverage and CPU load) selectively at a file, function, source line or instruction level.
Timeline Window Visualizes the supported trace and data sampling channels in a combined signal plot.
Code Windows Display program execution metrics inlined with the code.

Trace Requirements

Ozone currently supports trace on the following MCU architectures:

  • Cortex-M
  • Cortex-A
  • Cortex-R

The Cortex architecture principally allows two ways how trace data may be moved from the target to the PC: in a buffered (ETB) and a streaming (ETM) fashion. ETM trace has many advantages over ETB trace but also an extended hardware requirement (see below).

Target Requirements for ETB Trace

Buffered trace requires the target to contain an embedded trace buffer (ETB). The trace buffer must be accessible to J-Link/J-Trace, i.e. accessible via the selected target interface. ETB-Trace otherwise poses no additional requirements on the hardware setup.

Target Requirements for ETM Trace

Streaming trace requires the target CPU to contain an embedded trace macrocell (ETM) or a program trace macrocell (PTM). The trace data generated by these units is emitted via dedicated CPU pins. It is target dependent if these trace pins are present and to what type of debug header they are connected, if any. Most commonly, the trace pins are routed to a 19-pin Samtec FTSH "trace" header.

Debug Probe Requirements

  • ETB trace is supported by all J-Link and J-Trace models
  • ETM trace requires a J-Trace PRO model to be employed

Setup Requirements

Ozone's trace settings are configured via Ozone commands (or the trace settings dialog) as described below.

Trace Settings Overview

The following table summarizes all Ozone commands (settings) provided to configure trace. These commands can be executed from the project script.

Command Description Default
Project.SetTraceSource(src) Selects the trace source to use. none
Project.SetTracePortWidth(width) Specifies the number of trace pins provided by the target. Permitted values are 1, 2 and 4. 4
Project.SetTraceTiming(d1, d2, d3, d4) Configures the sampling delay of trace pin n (n=1...4). 2.0ns
Debug.ReadIntoInstCache(Addr,Size) Initializes the instruction cache. none
Edit.SysVar(VAR_TRACE_MAX_INST_CNT, cnt) Specifies the maximum amount of instructions that Ozone can process and store during a streaming trace session. 10M
Edit.SysVar(VAR_TRACE_TIMESTAMPS_ENABLED, on) Specifies weather the target is to output (and J-Trace/Ozone is to process) instruction timestamps multiplexed into the trace data stream. 1
Edit.SysVar(VAR_TRACE_CORE_CLOCK, freq) CPU frequency in Hz. Ozone uses this variable to convert instruction timestamps from CPU cycle count to time format. 100 kHz

Trace Settings

This section gives a more detailed description of the trace settings listed above.

Trace Source

Ozone's debug windows can be fed with trace data from different sources. Currently, only one trace source can be active at any given time. The supported trace sources are the valid arguments of command Project.SetTraceSource, as described below.

Trace Source Description
TRACE_SOURCE_NONE All trace features of Ozone are disabled.
TRACE_SOURCE_ETM Instruction trace data is read from the target's trace pins (in real-time) and provided to Ozone's trace windows. This mode requires a J-Trace debug probe.
TRACE_SOURCE_ETB Instruction trace data is read from the target's embedded trace buffer (ETB).
TRACE_SOURCE_SWO Printf data is read via the Serial Wire Output interface and output to Ozone's Terminal Window.
  • ETB trace does not need to be configuration in Ozone. It simply needs to be selected as the trace source to be used.
  • ETM trace has multiple configuration settings which can be edited via the trace settings dialog or the commands described above.

Trace Pin Sampling Delays

Ozone provides command Project.SetTraceTiming(d1, d2, d3, d4). This command instructs J-Trace to delay the sampling of individual trace pins. The valid value range is -5 to +5 nanoseconds at steps of 50 ps for each pin. The delays may be necessary in case the target hardware does not provide sufficient setup and hold times for one or multiple trace pins. In such cases, delaying TCLK can compensate this and make tracing possibly anyhow. Per default, J-Trace samples all trace pins synchronously with a delay of 2.0 nanoseconds. The trace pin delay configuration is only relevant when the selected trace source is "Trace Pins" / ETM.

The trace pin sampling delays can be conveniently edited via the trace timing subdialog of the trace settings dialog.

OzoneTraceTimingsDialog.png

Instruction Timestamps

J-Trace PRO is able to read the execution time of traced instructions from the target. Among other uses, this enables power profiling via Ozone's timeline debug window.

The command Edit.SysVar(VAR_TRACE_TIMESTAMPS_ENABLED, on) is provided to enable or disable trace timestamps. When trace timestamps are not required, the option should be disabled to enhance the overall tracing performance.

Instruction Cache

All instruction-trace related features of Ozone require the prior initialization of the instruction cache with the program code to be debugged. In case a download is performed on debug session start, Ozone automatically initializes the instruction cache with the downloaded bytes. In situations where the instruction cache is not fully initialized from the downloaded bytes, e.g. when:

  • program code areas are initialized at runtime (e.g. RAM-Debug)
  • no program file is specified
  • attaching to a running program

the instruction cache has to be initialized manually via command Debug.ReadIntoInstCache(Addr,Size). For details on how to use this command within an Ozone project script, please refer to Debug and Trace with RAM Functions. When the instruction cache is not initialized, Ozone will display a warning message indicating that debugging information will be inaccurate.

Trace Settings Dialog

The trace settings dialog is accessible from the tools menu.

OzoneToolsMenu.png

This dialog allows users to conveniently edit all of the trace settings described above.

OzoneTraceSettingsDialog.png

Selective Tracing

Many Arm-Cortex targets allow trace data output to be limited to a set of user-defined program address ranges. When selective tracing is active, the target's trace buffer is only filled with trace data that matches the configured constraints. This makes selective tracing particularly valuable on hardware setups with limited trace buffer size and no streaming trace capability.

It is to a high degree target dependent if selective tracing is supported and to what extent. A generic requirements overview cannot be given. Instead, refer to your MCU model's user manual or contact the manufacturer when unsure about the capabilities of your target.

Upon target connection, J-Link/J-Trace automatically detects if the target supports selective tracing and enables the debugger to use Tracepoints when selective tracing is available.

References

  • Ozone User Guide
  • J-Link / J-Trace User Guide