Setting Up Trace with Ozone
- 1 Introduction
- 2 Trace Features Overview
- 3 Trace Requirements
- 4 Trace Settings Overview
- 5 Trace Settings
- 6 Trace Settings Dialog
- 7 Selective Tracing
- 8 References
Trace Features Overview
Ozone's trace features consist of the following elements:
|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.|
Ozone currently supports trace on the following MCU architectures:
The Cortex architecture principally allows two ways how trace data may be moved from the target to the PC: in a buffered (ETB/MTB) and a streaming (ETM/PTM) fashion. ETM trace has many advantages over ETB trace but also an extended hardware requirement (see below).
Target Requirements for ETB/MTB Trace
Buffered trace requires the target to contain an embedded trace buffer (ETB) or a micro trace buffer (MTB). 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/PTM 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/MTB trace is supported by all J-Link and J-Trace models
- ETM/PTM trace requires a J-Trace PRO model to be employed
Depending on the hardware setup, trace with Ozone may need to be configured via the project script or trace settings dialog as described in the following sections.
Trace Settings Overview
The following table summarizes all Ozone commands (settings) provided
to configure trace. These commands should be executed from project file function
OnProjectLoad, with the exception of command
||Selects the trace source to use.||none|
||Specifies the number of trace pins provided by the target. Permitted values are 1, 2 and 4.||4|
||Configures the sampling delay of trace pin n (n=1...4).||2.0ns|
||Initializes the instruction cache.||none|
||Specifies the maximum amount of instructions that Ozone can process and store during a streaming trace session.||10M|
||Specifies weather the target is to output (and J-Trace/Ozone is to process) instruction timestamps multiplexed into the trace data stream.||1|
||CPU frequency in Hz. Ozone uses this variable to convert instruction timestamps from CPU cycle count to time format.||100 kHz|
This section gives a more detailed description of the trace settings listed above.
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_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 PRO debug probe. Same for PTM.|
|TRACE_SOURCE_ETB||Instruction trace data is read from the target's embedded trace buffer (ETB). Same for MTB|
|TRACE_SOURCE_SWO||Printf data is read via the Serial Wire Output interface and output to Ozone's Terminal Window.|
- ETB/MTB trace does not need to be configuration in Ozone. It simply needs to be selected as the trace source to be used.
- ETM/PTM 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.
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.
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.
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.
This dialog allows users to conveniently edit all of the trace settings described above.
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.
- Ozone User Guide
- J-Link / J-Trace User Guide