- Change Log
- Copyright and license information
- Contributors
- 1. Introduction
- 2. Trace Control and Trace Protocols
- 3. Trace System Overview
- 4. Trace Control Interface Overview
- 5. Versioning of Components
- 6. Trace Encoder Control Interface
- 7. Trace RAM Sink
- 8. Trace Funnel
- 9. Trace PIB Sink
- 10. Trace ATB Bridge
- 11. Minimal Implementation
- 12. Reset and Discovery
- 13. Enabling and Disabling
- 14. Legacy Interface Version
|
Warning
|
This document is in the Frozen state
Change is extremely unlikely. |
This RISC-V Trace Control Interface specification is © 2019-2023 RISC-V international
This document is released under a Creative Commons Attribution 4.0
International License.
creativecommons.org/licenses/by/4.0/.
Please cite as: “RISC-V Trace Control Interface Specification", RISC-V International
Key contributors to RISC-V Trace Control Interface specification in alphabetical order:
Bruce Ableidinger (SiFive) ⇒ Initial SiFive donation, reviews
Robert Chyla (IAR, SiFive) ⇒ Most topics, editing, publishing
Ernie Edgar (SiFive) ⇒ Initial SiFive donation, reviews
Jay Gamoneda (NXP) ⇒ Reviews
Markus Goehrle (Lauterbach) ⇒ Reviews, updates
Iain Robertson (UltraSoC, Siemens) ⇒ E-Trace compatibility, filtering chapter, reviews
Nino Vidovic (Segger) ⇒ Reviews
This document presents a standardized control interface for RISC-V trace infrastructure (such as trace encoders, trace funnels, trace sinks, …) for the Efficient Trace for RISC-V Specification Version 2.0 and for the RISC-V N-Trace specification version 1.0. Both Trace Working Groups agreed to standardize the control interface so that trace control software development tools can be used interchangeably with any RISC-V device implementing processor and/or data trace.
Instruction Trace is a system that collects a history of processor execution, along with other events. The trace system may be set up and controlled using a register-based interface. Hart execution activity appears on the Ingress Port and feeds into a Trace Encoder where it is compressed and formatted into trace messages. The Trace Encoder transmits trace messages to a Trace Sink. In multi-core systems, each hart has its own Trace Encoder, and typically all will connect to a Trace Funnel that aggregates the trace data from multiple sources and sends the data to a single destination.
This specification does not define the hardware interconnection between the hart and Trace Encoder, as this is defined in the Efficient Trace for RISC-V Specification Version 2.0. This document also does not define the hardware interconnection between the Trace Encoder and Trace Funnel, or between the Trace Encoder/Funnel and Trace Sink.
This specification allows a wide range of implementations including low-gate-count minimal instruction trace and systems with only instrumentation trace. Implementation choices include whether to support branch trace, data trace, instrumentation trace, timestamps, external triggers, various trace sink types, and various optimization tradeoffs between gate count, features, and bandwidth requirements.
This specification defines many registers, but not all trace protocols/encoders must support all bits/fields/options. However it is important to define some small subset which is REQUIRED.
This document includes chapter 'Minimal Implementation' which describes the smallest possible set of registers/fields, but each message protocol supported by this standard must clarify the exact meaning of supported registers/fields and bits as some of them define.
There are two standard trace protocols which will utilize this RISC-V Trace Control Interface:
-
Efficient Trace for RISC-V Specification - it describes RISC-V Trace Ingress Port signals.
-
At the moment of this writing this is version 2.0 (ratified May 5-th 2022).
-
-
RISC-V N-Trace (Nexus-based Trace) Specification.
This document (together with details provided in any of above documents) should be considered as a complete guideline for particular trace implementation.
|
Note
|
It is suggested to start from one of documents referenced above as these are master documents referencing other related documents (including this one). |
This section briefly describes features of the Trace Encoder and other trace components as background for understanding some of the control interface register fields.
Trace Encoder - Hardware module that accepts execution information from a hart and generates a stream of trace messages/packets.
Trace Message/Packet - Depending on protocol different names can be used, but it means the same. It is considered as a continuous sequence of (usually bytes) describing program and/or data flow.
Trace Funnel - Hardware module that combines trace streams from multiple Trace Encoders into a single output stream.
Trace Sink - Hardware module that accepts a stream of trace messages and records them in memory or forwards them onward in some format.
Trace Decoder - Software program that takes a recorded trace (from Trace Sink) and produces readable execution history.
WARL - Write any, read legal. If a non-legal value is written, the written value must be ignored and the register will keep previous, legal value. Used by debugger to determine system capabilities. See Discovery chapter.
ATB - Advanced Trace Bus, a protocol described in ARM document IHI0032B.
PIB - Pin Interface Block, a parallel or serial off-chip trace port feeding into a trace probe.
By monitoring the Ingress Port, the Trace Encoder determines when a program flow discontinuity has occurred and whether the discontinuity is inferable or non-inferable. An inferable discontinuity is one for which the Trace Decoder can statically determine the destination, such as a direct branch instruction in which the destination or offset is included in the opcode. Non-inferable discontinuities include all other types as interrupt, exception, and indirect jump instructions.
Branch Trace Messaging is the simplest form of instruction trace. Each program counter discontinuity results in one trace message, either a Direct or Indirect Branch Message. Linear instructions (or sequences of linear instructions) do not result in any trace messages/packets.
Indirect Branch Messages normally contain a compressed address to reduce bandwidth. The Trace Encoder emits a Branch With Sync Message containing the complete instruction address under certain conditions. This message type is a variant of the Direct or Indirect Branch Message and includes a full address and a field indicating the reason for the Sync.
Both the Efficient Trace for RISC-V (E-Trace) Specification and the Nexus standard define systems of messages intended to improve compression by reporting only whether conditional branches are taken by encoding each branch outcome in a single taken/not-taken bit. The destinations of non-inferable jumps and calls are reported as compressed addresses. Much better compression can be achieved, but an Encoder implementation will typically require more hardware.
Several other optimizations are possible to improve trace compression. These are optional for any Trace Encoder and there should be a way to disable optimizations in case the trace system is used with code that does not follow recommended API rules. Examples of optimizations are a Return-address stack, Branch repetition, Statically-inferable jump, and Branch prediction.
The Trace Encoder transmits completed messages to a Trace Sink. This specification defines a number of different sink types, all optional, and allows an implementation to define other sink types. A Trace Encoder must have at least one sink attached to it.
|
Note
|
Trace messages/packets are sequences of bytes. In case of wider sink width, some padding/idle bytes (or additional formatting) may be added by particular sink. Nexus format allows any number of idle bytes between messages. |
The Trace Encoder packs trace messages into fixed-width trace words (usually bytes). These are then stored in a dedicated RAM, typically located on-chip, in a circular-buffer fashion. When the RAM has filled, it may optionally be stopped, or it may wrap and overwrite earlier trace data.
The Trace Encoder packs trace messages into fixed-width trace words. These are then stored in a range of system memory reserved for trace using a DMA-type bus master in a circular-buffer fashion. When the memory range has been filled, it may optionally be stopped, or it may wrap and overwrite earlier trace data. This type of sink may also be used to transmit trace off-chip through, for example, a PCIe or USB port.
The ATB Bridge transmits bytes of RISC-V trace messages as an ATB bus master.
ATB width is byte aligned (8, 16, 32, 64, 128) which is well matching packet=sequence-of-bytes definition.
The Trace Encoder may send trace messages to a Trace Funnel. The Funnel aggregates the trace from each of its inputs (either RISC-V Trace Encoder or another Trace Funnel) and sends the combined trace stream to its designated Trace Sink or ATB Bridge, which is one or more of the sink types above.
|
Note
|
It is assumed that each input to the funnel (Trace Encoder or another Trace Funnel) has a unique message source ID defined (trTeSrcID field in the trTeControl register).
|
The Trace Control interface consists of a set of 32-bit registers. The control interface can be used to set up and control a trace session, retrieve collected trace, and control any trace system components.
This specification defines the following trace components:
| Component Name | Component Type (value=symbol) | Base Address (symbol) | Description |
|---|---|---|---|
Trace Encoder |
0x1=TRCOMP_ENCODER |
trBaseEncoder |
Accepts execution information from a hart (via Trace Ingress Port) and generates a stream of RISC-V trace messages/packets. |
Trace Funnel |
0x8=TRCOMP_FUNNEL |
trBaseFunnel |
Accepts several RISC-V trace message/packet streams (from multiple Trace Encoder[s] or Trace Funnel[s]) and merges them into a single stream of trace messages/packets. |
Trace RAM Sink |
0x9=TRCOMP_RAMSINK |
trBaseRamSink |
Accepts RISC-V trace messages/packets (from Trace Encoder or Trace Funnel) and stores them into RAM buffer (either dedicated SRAM or System Bus). |
Trace PIB Sink |
0xA=TRCOMP_PIBSINK |
trBasePibSink |
Accepts RISC-V trace messages/packets (from Trace Encoder or Trace Funnel) and sends them via a set of pins (parallel or serial). |
Trace ATB Bridge |
0xE=TRCOMP_ATBBRIDGE |
trBaseAtbBridge |
Accepts RISC-V trace messages/packets (from Trace Encoder or Trace Funnel) and forwards them to ATB bus in a system. |
|
Note
|
This specification is NOT addressing discovery of base addresses of trace components. These base addresses (symbols in above table) must be specified as part of trace tool configuration. Connections between different trace components must be also defined. Future versions of this specification may allow a single base address to be sufficient to access all components in the system. |
Each Trace Component is controlled by a set of 32-bit registers occupying up to a 4KB space. Base address of each trace component must be aligned on the 4KB boundary.
Each hart being traced must have its own separate Trace Encoder control component. This also applies to multiple harts that belong to the same core. A system with multiple harts must allow generating messages with a field indicating which hart is responsible for that message.
Different components must be connected via internal busses and/or FIFO buffers. This specification does not define this interconnect logic, but the following rules must be followed:
-
Each component sending a trace message/packet must assure the entire packet can be accepted by the destination component (or pushed into the FIFO buffer).
-
Sending a partial packet is NEVER allowed as it will not be possible to process and decode such a trace.
-
-
If a component cannot send an entire message/packet it must wait until it will be possible to do so.
-
Tracing is typically required to be non-intrusive, and if the Trace Encoder cannot keep up with the hart it must drop the packet and wait for the receiver to be ready.
-
Once trace is allowed to resume it must issue an instruction trace synchronization message/packet so the decoder will be aware that some (unknown) amount of trace has been lost.
-
It is advisable to drain the trace pipeline to some hysteresis level before resuming - otherwise a lot of short chunks of trace may be produced.
-
-
Optionally (and if acceptable to the user), the Trace Encoder may be configured to stall the hart in order to avoid packet loss.
-
Easiest way to prevent trace overflows is to assure FIFO capable of holding several trace messages/packets is placed AFTER Trace Encoder and/or use wider internal busses to provide more bandwidth.
-
Bandwidth at input to the sink must be in general larger than the data being produced.
-
Amount of data being generated can be limited by creating tracing windows with the help of triggers.
-
| Input | Output | Description |
|---|---|---|
Ingress Port |
Trace Encoder |
Ingress Port (from hart) providing raw trace trace to be encoded |
Trace Encoder |
Trace RAM Sink |
Single hart tracing to RAM buffer |
Trace Encoder |
Trace PIB Sink |
Single hart tracing via pins |
Trace Encoder |
Trace ATB Bridge |
Single hart tracing to Arm ATB infrastructure |
Trace Encoder |
Trace Funnel |
Sending trace from single hart to Trace Funnel (to be combined from other RISC-V trace) |
Trace Funnel |
Trace Funnel |
Sending combined trace from multiple harts to higher level Trace Funnel (to be combined from other RISC-V trace) |
Trace Funnel |
Trace RAM Sink |
Sending combined trace from multiple harts to RAM buffer |
Trace Funnel |
Trace PIB Sink |
Sending combined trace from multiple harts via pins |
Trace Funnel |
Trace ATB Bridge |
Sending combined trace from multiple harts to Arm ATB infrastructure |
Trace ATB Bridge |
Arm ATB bus |
Sending trace to ATB (to combine RISC-V trace with other Arm components on the system) |
|
Note
|
Sending to Arm ATB infrastructure is allowed (via ATB Bridge), but this specification does not specify how to transport trace data from (possible) Arm components in the system using RISC-V Trace sub-system. One of possible ways of doing so would be to create a custom trace component, configure it to encapsulate it as custom Nexus trace messages and connect it as input to one of trace funnels. |
+----------------+ | Single Hart | | +----------+ +---------+ +------------+ | | Trace | | Trace | | Trace Sink | | | Ingress =====>| Encoder |---->| or | | | Port | | | | ATB Bridge | | +----------+ +---------+ +------------+ | | +----------------+
+-----------+ +---------+
| Hart with | | Trace |
| Ingress |==>| Encoder |---+
| Port | | | |
+-----------+ +---------+ |
|
+-----------+ +---------+ | +--------+ +-------------+
| Hart with | | Trace | +-->| Trace | | Trace Sink |
| Ingress |==>| Encoder |------>| Funnel |---->| or |
| Port | | | +-->| | | ATB Bridge |
+-----------+ +---------+ | +--------+ +-------------+
|
+-----------+ +---------+ |
| Hart with | | Trace | |
| Ingress |==>| Encoder |---+
| Port | | |
+-----------+ +---------+
+-------------------------+
| 3 Harts with 3 Encoders |
| and local Funnel |---+
| (see above) | |
+-------------------------+ |
| +--------+ +-------------+
+-->| Trace | | Trace Sink |
| Funnel |---->| or |
+-->| (top) | | ATB Bridge |
| +--------+ +-------------+
+-------------------------+ |
| 3 Harts with 3 Encoders | |
| and local Funnel |---+
| (see above) |
+-------------------------+
+-------------------------+
| 3 Harts with 3 Encoders |
| and local Funnel |---+
| (see above) | |
+-------------------------+ |
|
+-----------+ +---------+ | +--------+ +-------------+
| Hart with | | Trace | +-->| Trace | | Trace Sink |
| Ingress |==>| Encoder |------>| Funnel |---->| or |
| Port | | |---+ | (top) | | ATB Bridge |
+-----------+ +---------+ | +--------+ +-------------+
|
v
+----------------+
| Trace RAM Sink |
| (in SRAM mode) |
+----------------+
|
Note
|
In above configuration top Trace Funnel should allow disabling an input from an extra Trace Encoder so trace from 3-hart cluster may go to Trace Sink only and trace from an extra hart may go to Trace RAM Sink only. |
For the access method to the trace control registers, it makes a difference whether these registers shall be accessed by an external debug/trace tool, or by an internal debugger running on the chip.
Trace control register access by an external debugger (this is the most common use case):
-
External debuggers must be able to access all trace control registers independent of whether the traced harts are running or halted. That is why for external debuggers, the recommended access method for memory-mapped control registers is memory accesses through the RISC-V debug module using SBA (System Bus Access) as defined in the RISC-V Debug Specification.
Trace control register access by an internal debugger:
-
Through loads and stores performed by one or more harts in the system. Mapping the control interface into physical memory accessible from a hart allows that hart to manage a trace session independently from an external debugger. A hart may act as an internal debugger or may act in cooperation with an external debugger. Two possible use models are collecting crash information in the field and modifying trace collection parameters during execution. If a system has physical memory protection (PMP), a range can be configured to restrict access to the trace system from hart(s).
|
Note
|
Additional control path(s) may also be implemented, such as extra JTAG registers or devices, a dedicated DMI debug bus or message-passing network. Such an access (which is NOT based on System Bus) may require custom implementation by trace probe vendors as this specification only mandates probe vendors to provide access via SBA commands. |
Each block of 32-bit registers (for each component) has the following layout:
| Address Offset | Register Name | Compliance | Description |
|---|---|---|---|
0x000 |
tr??Control |
Required |
Main control register for this trace component |
0x004 |
tr??Impl |
Required |
Trace Implementation information for this trace component |
0x008 |
tr??Control2 |
Optional |
Additional controls for this trace component (can be named differently) |
0x00C |
tr??Control3 |
Optional |
Additional controls for this trace component (can be named differently) |
0x010 - 0xDFF |
— |
Optional |
Additional registers (specific for particular type of component). All not used registers are reserved and should read as 0 and ignore writes. |
0xE00 - 0xFFF |
— |
Optional |
Registers reserved for implementation/vendor specific details. May allow identification of components on a system bus. |
|
Warning
|
Each component has a tr??Active bit in the tr??Control register. Accesses to other registers are unpredictable when the tr??Active bit is 0.
|
Each trace component has a tr??Impl register (at address offset 0x4) where trace component version and trace component type can be identified. This register allows debug tools to verify provided base addresses of components and potentially adjust tool behavior by looking at component versions.
|
Note
|
Each component may have a different version. Initial version of this specification defines all components to specify component version as 1.0 (major=1, minor=0). |
Registers in the 4KB range that are not implemented are reserved and read as 0 and ignore writes.
Most trace control registers are optional. Some WARL fields may be hard-coded to any value (including 0). It allows different implementations to provide different functionality.
Both N-Trace and E-Trace encoders are controlled by the same set of bits/fields in the same 'trTe???' registers - as almost every register/field/bit is optional this provides good flexibility in implementation.
All other trace components are shared between different trace encoders (N-Trace and E-Trace).
| Address Offset | Register Name | Compliance | Description |
|---|---|---|---|
0x000 |
trTeControl |
Required |
Trace Encoder control register |
0x004 |
trTeImpl |
Required |
Trace Encoder implementation information |
0x008 |
trTeInstFeatures |
Optional |
Extra instruction trace encoder features and trace source IDs |
0x00C |
trTeInstFilters |
Optional |
Determine which filters qualify an instruction trace |
Data trace control (trTeData??) |
|||
0x010 |
trTeDataControl |
Optional |
Data trace control and features |
0x014 - 0x018 |
— |
Reserved |
Reserved for more data trace related registers |
0x01C |
trTeDataFilters |
Optional |
Determine which filters qualify data trace |
Reserved |
|||
0x020 - 0x03F |
— |
Reserved |
Reserved for more registers/sub-components |
Timestamp control (trTs??) |
|||
0x040 |
trTsControl |
Optional |
Timestamp control register |
0x044 |
— |
Optional |
Reserved |
0x048 |
trTsCounterLow |
Optional |
Lower 32 bits of timestamp counter |
0x04C |
trTsCounterHigh |
Optional |
Upper bits of timestamp counter |
Trigger control (trTeTrig??) |
|||
0x050 |
trTeTrigDbgControl |
Optional |
Debug Triggers control register |
0x054 |
trTeTrigExtInControl |
Optional |
External Triggers Input control register |
0x058 |
trTeTrigExtOutControl |
Optional |
External Triggers Output control register |
Reserved |
|||
0x060 - 0x0DF |
— |
Reserved |
Reserved for more registers/sub-components |
Discovery related |
|||
0x0E0 - 0x0FF |
trTeDiscovery0.. trTeDiscovery7 |
Optional |
Protocol dependent configuration/discovery-related registers |
Reserved |
|||
0x100 - 0x3FF |
— |
Reserved |
Reserved for more registers/sub-components |
Filters & comparators (trTeFilter??, trTeComp??) |
|||
0x400 - 0x5FF |
trTeFilter?? |
Optional |
Trace Encoder Filter Registers |
0x600 - 0x7FF |
trTeComp?? |
Optional |
Trace Encoder Comparator Registers |
Examples of possible additional sub-components in Trace Encoder are:
-
PC Sampling
-
Instrumentation Trace
| Address Offset | Register Name | Compliance | Description |
|---|---|---|---|
0x000 |
trRamControl |
Required |
RAM Sink control register |
0x004 |
trRamImpl |
Required |
RAM Sink Implementation information |
0x008 - 0x00F |
— |
Reserved |
Reserved for more control registers |
0x010 |
trRamStartLow |
Required |
Lower 32 bits of start address of circular trace buffer |
0x014 |
trRamStartHigh |
Optional |
Upper bits of start address of circular trace buffer |
0x018 |
trRamLimitLow |
Required |
Lower 32 bits of end address of circular trace buffer |
0x01C |
trRamLimitHigh |
Optional |
Upper bits of end address of circular trace buffer |
0x020 |
trRamWPLow |
Required |
Lower 32 bits of current write location for trace data in circular buffer |
0x024 |
trRamWPHigh |
Optional |
Upper bits of current write location for trace data in circular buffer |
0x028 |
trRamRPLow |
Optional |
Lower 32 bits of access pointer for trace readback |
0x02C |
trRamRPHigh |
Optional |
Upper bits of access pointer for trace readback |
0x040 |
trRamData |
Optional |
Read/write access to SRAM trace memory (32-bit data) |
0x044 - 0x07F |
— |
Optional |
Reserved for bigger read buffer |
| Address Offset | Register Name | Compliance | Description |
|---|---|---|---|
0x000 |
trPibControl |
Required |
Trace PIB Sink control register |
0x004 |
trPibImpl |
Required |
Trace PIB Sink Implementation information |
| Address Offset | Register Name | Compliance | Description |
|---|---|---|---|
0x000 |
trFunnelControl |
Required |
Trace Funnel control register |
0x004 |
trFunnelImpl |
Required |
Trace Funnel Implementation information |
0x008 |
trFunnelDisInput |
Optional |
Disable individual funnel inputs |
Timestamp control (trTs??) |
|||
0x040 |
trTsControl |
Optional |
Timestamp control register |
0x044 |
— |
Reserved |
Reserved for extra timestamp control |
0x048 |
trTsCounterLow |
Optional |
Lower 32 bits of timestamp counter |
0x04C |
trTsCounterHigh |
Optional |
Upper bits of timestamp counter |
|
Note
|
Funnels may optionally be a source of timestamp and/or forward timestamp to Trace Encoders in the system. This way several Trace Encoders may share timestamp and trace from several harts may be time-correlated. |
Each component has a tr??Impl register, which includes two 4-bit tr??VerMinor and tr??VerMajor fields. These fields are guaranteed to be present in all future revisions of a standard, so trace tools will be able to discover a component version and act accordingly.
-
Value 0 as
tr??VerMajoris NOT allowed (due to compatibility reasons). -
Different components may report different versions (as some components may be updated more often than others).
-
The major version
tr??VerMajorfield should change, when some incompatible (which will break older trace software) change is introduced. -
The minor version
tr??VerMinorfield should change, when change is considered a compatible extension (for example adding a new field) - for that reason software should always write 0 to undefined bits in registers. -
Version 15.x is reserved for non-compatible version encoding.
-
Version n.15 should be used as experimental (in development) implementation.
Versions must be always reported as two decimal numbers major.minor - initial version of this specification is defined as 1.0.
Trace software should handle versions as follows (let’s assume hypothetical version 2.3 was defined as current version in moment of release of trace software)
-
0.x ⇒ Reject as not supported or generate a warning and handle as legacy version 0.
-
2.3 ⇒ Accept silently.
-
2.2 ⇒ Accept silently (and trim features or not allow users to set newer features).
-
2.4 ⇒ Generate a warning but continue using 2.3 features.
-
2.15 ⇒ Generate an "experimental version" warning but continue using 2.3 features.
-
1.x ⇒ Generate a warning and continue or reject as an obsolete (referring to last debugger supporting this version).
-
3.x ⇒ Abort with an error that this future version is not compatible with existing software and possibly redirect to the tool update page.
|
Note
|
Displayed messages should report component name, component base address and current and supported version numbers. It is suggested to display the full hexadecimal value of tr??Impl register as it may aid in debugging of possibly incorrect/incompatible component configuration.
|
Many features of the Trace Encoder (TE for short) are optional. In most cases, optional features are enabled using a WARL (write any, read legal) register field. A debugger can determine if an optional feature is present by writing to the register field and reading back the result.
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
0 |
trTeActive |
Primary enable/reset for the TE. When 0, the TE may have clocks gated off or be powered down, and other register locations may be inaccessible. Hardware may take an arbitrarily long time to process power-up and power-down and will indicate completion when the read value of this bit matches what was written. |
RW |
0 |
1 |
trTeEnable |
1: Trace Encode is enabled. Allows |
RW |
0 |
2 |
trTeInstTracing |
1: Instruction trace is being generated. Written from a trace tool (after a write to |
RW |
0 |
3 |
trTeEmpty |
Reads as 1 when all generated trace have been emitted. |
R |
1 |
6-4 |
trTeInstMode |
Main instruction trace generation mode |
WARL |
SD(1) |
8-7 |
— |
Reserved for future modes |
— |
0 |
9 |
trTeContext |
Send Ownership messages to indicate processor context when scontext, mcontext, v, or prv changes and full context information immediately after all Sync messages. |
WARL |
SD |
10 |
— |
Reserved |
WARL |
SD |
11 |
trTeInstTrigEnable |
1: Allows |
WARL |
0 |
12 |
trTeInstStallOrOverflow |
Written to 1 by hardware when an overflow message is generated or when the TE requests a hart stall. Clears to 0 at TE reset or when the trace is enabled ( |
RC1 |
0 |
13 |
trTeInstStallEna |
0: If TE cannot send a message, the message is dropped. The protocol dependent overflow instruction trace synchronization message/packet is generated when the trace is restarted, so the decoder will know that trace is lost and must reset any internal decoder state. |
WARL |
SD |
14 |
— |
Reserved |
— |
0 |
15 |
trTeInhibitSrc |
0: Trace source field (of |
WARL |
SD |
17-16 |
trTeInstSyncMode |
Select periodic instruction trace synchronization message/packet generation mechanism. At least one non-zero mechanism must be implemented. |
WARL |
SD |
19-18 |
— |
Reserved |
— |
0 |
23-20 |
trTeInstSyncMax |
The maximum interval (in units determined by |
WARL |
SD |
26-24 |
trTeFormat |
Trace recording format: |
WARL |
SD |
31-27 |
— |
Reserved |
— |
0 |
SD(1) = System-Dependent, but these fields should always have same values at reset (
trTeActive= 0)
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
3-0 |
trTeVerMajor |
Trace Encoder Major Version. Value 1 means the component is compliant with this document. Value 0 means legacy version - see 'Legacy Interface Version' chapter at the end. |
R |
1 |
7-4 |
trTeVerMinor |
Trace Encoder Minor Version. Value 0 means the component is compliant with this document. |
R |
0 |
11-8 |
trTeCompType |
Trace Encoder Component Type (Trace Encoder) |
R |
0x1 |
15-12 |
— |
Reserved for future versions of this standard |
— |
0 |
19-16 |
trTeProtocolMajor |
Trace Protocol Major Version. Value of this field is defined by a document which defines a trace encoding protocol. |
R |
SD |
23-20 |
trTeProtocolMinor |
Trace Protocol Minor Version. Value of this field is defined by a document which defines a trace encoding protocol. |
R |
SD |
31-24 |
— |
Reserved for vendor specific implementation details |
— |
SD |
|
Note
|
trTeProtocol?? fields are separated from trTeVer?? as we may have the same control interface, but protocol itself may be extended with new packets/ messages/ fields.
|
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
0 |
trTeInstNoAddrDiff |
Do not send differential addresses when set (always full address is sent) |
WARL |
0 |
1 |
trTeInstNoTrapAddr |
When set, do not sent trap handler address in trap packets |
WARL |
0 |
2 |
trTeInstEnSequentialJump |
Treat sequentially inferrable jumps as inferable PC discontinuities when set. |
WARL |
0 |
3 |
trTeInstEnImplicitReturn |
Treat returns as inferable PC discontinuities when returning from a recent call on a stack. Field |
WARL |
0 |
4 |
trTeInstEnBranchPrediction |
Branch predictor enabled when set. |
WARL |
0 |
5 |
trTeInstEnJumpTargetCache |
Jump target cache enabled when set. |
WARL |
0 |
7-6 |
trTeInstImplicitReturnMode |
Defines how the decoder is handling stack of return addresses (if enabled by trTeInstEnImplicitReturn bit): |
R |
SD |
8 |
trTeInstEnRepeatedHistory |
Enable repeated branch history detection when set. |
WARL |
0 |
9 |
trTeInstEnAllJumps |
Emit trace message or add history bit for direct unconditional/inferable control flow changes (jumps or calls). Normally these instructions do not generate any trace as the decoder is able to determine the next instruction. Trace will not compress well but timestamp accuracy will be better - may be used when profiling loops. |
WARL |
0 |
10 |
trTeInstExtendAddrMSB |
When set, allow extension of virtual address MSB bits (RISC-V Sv39/48/57 virtual address modes assume MSB bits to be all identical). Encoding details are trace protocol dependent. |
WARL |
0 |
15-11 |
— |
Reserved for additional instruction trace control/status bits |
— |
0 |
27-16 |
trTeSrcID |
This TE source ID. If |
WARL |
SD |
31-28 |
trTeSrcBits |
The number of bits in the trace source field (0..12), unless disabled by |
WARL |
SD |
|
Note
|
Applicability of different trTeInst?? fields for each trace encoding protocol is described in a document which defines the protocol (and not all fields are applicable to all protocols).
|
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
15-0 |
trTeInstFilters |
Determine which filters qualify an instruction trace. If bit n is a 1 then instructions will be traced when filter n matches. If all bits are 0, all instructions are traced. |
WARL |
0 |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
0 |
trTeDataImplemented |
Read as 1 if data trace is implemented. |
R |
SD |
1 |
trTeDataTracing |
1: Data trace is being generated. Written from a trace tools or controlled by triggers. When trDataTracing=1, data trace may be subject to additional filtering in some implementations. |
WARL |
SD |
2 |
trTeDataTrigEnable |
Global enable/disable for data trace triggers |
WARL |
0 |
3 |
trTeDataStallOrOverflow |
Written to 1 by hardware when an overflow message is generated or when the TE requests a hart stall due to data trace. Clears to 0 at TE reset or when the trace is enabled ( |
RC1 |
0 |
4 |
trTeDataStallEna |
0: If TE cannot send data trace messages, an overflow message is generated when the trace is restarted. |
WARL |
0 |
5 |
trTeDataDrop |
Written to 1 by hardware when the data trace packet was dropped (if enabled). Clears to 0 at TE reset or when the trace is enabled ( |
RC1 |
0 |
6 |
trTeDataDropEna |
1: Allow dropping data trace to avoid instruction trace overflows. Setting this bit will not guarantee that instruction trace overflows will not happen. |
WARL |
0 |
15-7 |
— |
Reserved for additional data trace control/status bits. |
— |
0 |
16 |
trTeDataNoValue |
Omit data values from data trace packets when set. |
WARL |
SD |
17 |
trTeDataNoAddr |
Omit data address from data trace packets when set. |
WARL |
SD |
19-18 |
trTeDataAddrCompress |
Data trace address compression selection: |
WARL |
SD |
|
Note
|
Applicability of different trTeData?? fields for each trace encoding protocol is described in a document which defines the protocol (and not all fields are applicable to all protocols).
|
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
15-0 |
trTeDataFilters |
Determine which filters qualify data trace. If bit n is a 1 then data accessed will be traced when filter n matches. If all bits are 0, all data accesses are traced. |
WARL |
0 |
Timestamp Unit is an optional sub-component present in either Trace Encode or Trace Funnel. An implementation may choose from several types of timestamp units:
-
Internal System - fixed clock in a system (such as bus clock) is used to increment the timestamp counter
-
Internal Core - core clock is used to increment the timestamp counter (only applicable to Trace Encoders)
-
Shared - shares timestamp with another Trace Encoder or Trace Funnel
-
External - accepts a binary timestamp value from an outside source such as ARM CoreSight™ trace
Implementations may have no timestamp, one timestamp type, or more than one type. The WARL field trTsType is used to determine the system capability and to set the desired type.
The width of the timestamp is implementation-dependent, typically 40 or 48 bits (40 bit timestamp will overflow every 4.7 minutes assuming 1GHz timestamp clock).
In a system with Funnels, typically all the Funnels are built with a Timestamp Unit. The top-level Funnel is the source of the timestamp (Internal System or External) and all the Encoders and other Funnels have a Shared timestamp. This assures that all timestamps in the system are the same and trace from different harts may be time-correlated. To perform the forwarding function, the mid-level Funnels must be programmed with trFunnelActive = 1 (which is natural as all trace messages must pass through that funnel).
An Internal Timestamp Unit may include a prescaler divider, which can extend the range of a narrower timestamp and uses less power but has less resolution.
In a system with an Internal Core timestamp counter (implemented in Trace Encoder associated with a hart), it may be desirable to stop the counter when the hart is halted by a debugger. An optional control bit is provided for this purpose, but it may or may not be implemented.
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
0 |
trTsActive |
Primary reset/enable for timestamp unit |
RW |
0 |
1 |
trTsCount |
Internal timestamp only. 1: counter runs, 0: counter stopped |
RW |
0 |
2 |
trTsReset |
Internal timestamp only. Write 1 to reset the timestamp counter |
W1 |
0 |
3 |
trTsRunInDebug |
Internal Core timestamp only. 1: counter runs when hart is halted (in debug mode), 0: stopped |
WARL |
0 |
6-4 |
trTsType |
Type of Timestamp unit |
WARL |
SD |
7 |
— |
Reserved |
— |
0 |
9-8 |
trTsPrescale |
Internal timestamp only. Prescale timestamp clock by 2^2n (1, 4, 16, 64). |
WARL |
0 |
14-10 |
— |
Reserved |
— |
0 |
15 |
trTsEnable |
Global enable for timestamp field in trace messages/packets (for Trace Encoder only). |
WARL |
0 |
23-16 |
System-dependent fields to control what message/packet types include timestamp fields. |
WARL |
0 |
|
29-24 |
trTsWidth |
Width of timestamp in bits (0..63) |
R |
SD |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
31-0 |
trTsCounterLow |
Lower 32 bits of timestamp counter. |
R |
0 |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
31-0 |
trTsCounterHigh |
Upper bits of timestamp counter, zero-extended. |
R |
0 |
Debug triggers are signals from the hart that a trigger (breakpoint or watchpoint) was hit, but the action associated with that trigger is a trace-related action. Action identifiers 2-5 are reserved for trace actions in the RISC-V Debug Spec, where triggers are defined. Actions 2-4 are defined by the Efficient Trace for RISC-V (E-Trace) Specification. The desired action is written to the action field of the Match Control mcontrol CSR (0x7a1). Not all harts support trace actions; the debugger should read back mcontrol CSR after setting one of these actions to verify that the option exists.
| Action (from debug spec) | Effect |
|---|---|
0 |
Breakpoint exception |
1 |
Debug exception |
2 |
Trace-on action When When |
3 |
Trace-off action When When |
4 |
Trace-notify action It will cause the encoder to generate a packet with the current PC (and possibly timestamp). If trace is not active ( |
5 |
Vendor-specific action (optional) |
If there are vendor-specific features that require control, the trTeTrigDbgControl register is used.
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
31-0 |
trTeTrigDbgControl |
Vendor-specific trigger setup |
WARL |
0 |
The TE may be configured with up to 8 external trigger inputs for controlling trace. These are in addition to the external triggers present in the Debug Module when Halt Groups are implemented. The specific hardware signals comprising an external trigger are implementation-dependent.
External Trigger Outputs may also be present. A trigger out may be generated by trace starting, trace stopping, a watchpoint, or by other system-specific events.
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
3-0 |
trTeTrigExtInAction0 |
Select action to perform when external trigger input 0 fires. If external trigger input 0 does not exist, then its action is fixed at 0. |
WARL |
0 |
31-4 |
trTeTrigExtInAction n |
Select actions (as defined for bits 3-0) for external trigger input n (1..7). If an external trigger input does not exist, then its action is fixed at 0. |
WARL |
0 |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
3-0 |
trTeTrigExtOutEvent0 |
Bitmap to select which event(s) cause external trigger 0 output to fire. If external trigger output 0 does not exist, then all bits are fixed at 0. Bits 2 and 3 may be fixed at 0 if the corresponding feature is not implemented. |
WARL |
0 |
31-4 |
trTeTrigExtOutEvent n |
Select events for external trigger output n (1..7). If an external trigger output does not exist, then its event bits are fixed at 0 |
WARL |
0 |
All registers with offsets 0x400 .. 0x7FC are reserved for additional trace encoder filter options (context, addresses, modes, etc.).
Trace encoder filters are an optional feature that can be used to control the generated trace in various ways.
The registers below divide the filter logic into filters and comparators to provide maximum flexibility at low cost. The number of filters and comparators depends on the system. Each filter unit can specify filtering against instruction and optionally against data trace inputs from the hart. When filter i is implemented, the registers trTeFilteriControl and trTeInstFilters must be implemented to enable it. And to apply filter i to the data trace, the trTeDataFilters register must also be present. And if a match bit in the trTeFilteriControl register can be set to 1 (= enabling a filter option), the corresponding register from the bit’s description must have a valid value. Each of the mentioned comparator units is actually a pair of comparators (primary and secondary, or P and S), so a limited range can be matched with a single comparator unit if needed.
|
Note
|
Filter and comparator registers refer to values of some signals (as priv, itype, ecause, dtype, 'dsize, …) available on Trace Ingress Port. See E-Trace specification for details of encoding of these values. |
| Address Offset | Register Name | Compliance | Description |
|---|---|---|---|
0x400 + 0x20*i |
trTeFilteriControl |
Optional |
Filter i control |
0x404 + 0x20*i |
trTeFilteriMatchInst |
Optional |
Filter i instruction match control |
0x408 + 0x20*i |
trTeFilteriMatchEcause |
Optional |
Filter i Ecause match control |
0x40C + 0x20*i |
— |
Optional |
Reserved |
0x410 + 0x20*i |
trTeFilteriMatchValueImpdef |
Optional |
Filter i impdef value |
0x414 + 0x20*i |
trTeFilteriMatchMaskImpdef |
Optional |
Filter i impdef mask |
0x418 + 0x20*i |
trTeFilteriMatchData |
Optional |
Filter i Data trace match control |
0x41C + 0x20*i |
— |
Optional |
Reserved |
| 0x600 + 0x20*j | trTeCompjControl | Optional | Comparator j control |
|---|---|---|---|
0x604 + 0x20*j |
— |
Optional |
Reserved |
0x608 + 0x20*j |
— |
Optional |
Reserved |
0x60c + 0x20*j |
— |
Optional |
Reserved |
0x610 + 0x20*j |
trTeCompjPmatchLow |
Optional |
Comparator j primary match (bits 31:0) |
0x614 + 0x20*j |
trTeCompjPmatchHigh |
Optional |
Comparator j primary match (bits 63:32) |
0x618 + 0x20*j |
trTeCompjSmatchLow |
Optional |
Comparator j secondary match (bits 31:0) |
0x61C + 0x20*j |
trTeCompjSmatchHigh |
Optional |
Comparator j secondary match (bits 63:32) |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
0 |
trTeFilterEnable |
Overall filter enable for filter #i |
WARL |
0 |
1 |
trTeFilterMatchPrivilege |
When set, match privilege levels specified by |
WARL |
0 |
2 |
trTeFilterMatchEcause |
When set, start matching from exception cause codes specified by |
WARL |
0 |
3 |
trTeFilterMatchInterrupt |
When set, start matching from a trap with the interrupt level codes specified by
|
WARL |
0 |
4 |
trTeFilterMatchComp1 |
When set, the output of the comparator selected by |
WARL |
0 |
7-5 |
trTeFilterComp1 |
Specifies the comparator unit to use for the 1st comparison. |
WARL |
SD |
8 |
trTeFilterMatchComp2 |
When set, the output of the comparator selected by |
WARL |
0 |
11-9 |
trTeFilterComp2 |
Specifies the comparator unit to use for the 2nd comparison. |
WARL |
SD |
12 |
trTeFilterMatchComp3 |
When set, the output of the comparator selected by |
WARL |
0 |
15-13 |
trTeFilterComp3 |
Specifies the comparator unit to use for the 3rd comparison. |
WARL |
SD |
16 |
trTeFilterMatchImpdef |
When set, match impdef values as specified by |
WARL |
0 |
23-17 |
— |
Reserved |
— |
0 |
24 |
trTeFilterMatchDtype |
When set, match dtype values as specified by |
WARL |
0 |
25 |
trTeFilterMatchDsize |
When set, match dsize values as specified by |
WARL |
0 |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
7-0 |
trTeFilterMatchChoicePrivilege |
When |
WARL |
SD |
8 |
trTeFilterMatchValueInterrupt |
When |
WARL |
SD |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
31-0 |
trTeFilterMatchChoiceEcause |
When |
WARL |
SD |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
31-0 |
trTeFilterMatchValueImpdef |
When |
WARL |
SD |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
31-0 |
trTeFilterMatchMaskImpdef |
When |
WARL |
SD |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
15-0 |
trTeFilterMatchChoiceDtype |
When |
WARL |
SD |
23-16 |
trTeFilterMatchChoiceDsize |
When |
WARL |
SD |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
1-0 |
trTeCompPInput |
Determines which input to compare against the primary comparator. |
WARL |
SD |
3-2 |
trTeCompSInput |
Determines which input to compare against the secondary comparator. Same encoding as |
WARL |
SD |
6-4 |
trTeCompPFunction |
Selects the primary comparator function. Primary result is true if input selected via |
WARL |
SD |
7 |
— |
Reserved |
— |
0 |
10-8 |
trTeCompSFunction |
Selects the secondary comparator function. Secondary result is true if input selected via |
WARL |
SD |
11 |
— |
Reserved |
— |
0 |
13-12 |
trTeCompMatchMode |
Selects the match condition used to assert the overall comparator output |
WARL |
SD |
14 |
trTeCompPNotify |
Generate a trace packet explicitly reporting the address
of the final instruction in a block that causes a
primary match (requires |
WARL |
SD |
15 |
trTeCompSNotify |
Generate a trace packet explicitly reporting the address
of the final instruction in a block that causes a
secondary match (requires |
WARL |
SD |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
31-0 |
trTeCompPMatchLow |
The match value for the primary comparator (bits 31:0). |
WARL |
SD |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
31-0 |
trTeCompPMatchHigh |
The match value for the primary comparator (bits 63:32). |
WARL |
SD |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
31-0 |
trTeCompSMatchLow |
The match value for the secondary comparator (bits 31:0). |
WARL |
SD |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
31-0 |
trTeCompSMatchHigh |
The match value for the secondary comparator (bits 63:32). |
WARL |
SD |
Trace RAM Sink may be instantiated or configured to support storing trace into dedicated SRAM or system memory. SRAM mode is using dedicated local memory inside of RAM sink, while system memory mode (SMEM mode) is accessing memory via system bus (care should be taken to not overwrite application code or data - it is usually done by reserving part of system memory for trace). Dedicated SRAM memory must be read via dedicated trRamData register, while memory in SMEM mode should be read as any other memory on system bus - for example using SBA (System Bus Access) access mode as defined in the RISC-V Debug Specification.
Trace data is placed in memory in LSB order (first byte of trace packet/data is placed on LSB).
Be aware that in case trace memory wraps around some protocols may require additional synchronization data - it is usually done by periodically generating a sequence of alignment synchronization bytes which cannot be part of any valid packet. Specification of each trace protocol must define it.
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
0 |
trRamActive |
Primary enable/reset for Trace RAM Sink. When 0, the Trace RAM Sink may have clocks gated off or be powered down, and other register locations may be inaccessible. Hardware may take an arbitrarily long time to process power-up and power-down and will indicate completion when the read value of this bit matches what was written. |
RW |
0 |
1 |
trRamEnable |
1: Trace RAM Sink enabled. Setting |
RW |
0 |
2 |
— |
Reserved |
— |
0 |
3 |
trRamEmpty |
Reads 1 when Trace RAM Sink internal buffers are empty, which means that all trace data is flushed. |
R |
1 |
4 |
trRamMode |
0: This RAM Sink will operate in SRAM mode |
WARL |
SD |
7-5 |
— |
Reserved |
— |
0 |
8 |
trRamStopOnWrap |
1: Disable storing trace to RAM ( |
WARL |
0 |
10-9 |
trRamMemFormat |
0: Memory is formatted as plain bytes |
WARL |
SD |
11 |
— |
Reserved |
— |
0 |
14-12 |
trRamSinkAsyncFreq |
0: Alignment synchronization packets disabled (may be the only choice for some protocols) |
WARL |
SD |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
3-0 |
trRamVerMajor |
Trace RAM Sink Component Major Version. Value 1 means the component is compliant with this document. |
R |
1 |
7-4 |
trRamVerMinor |
Trace RAM Sink Component Minor Version. Value 0 means the component is compliant with this document. |
R |
0 |
11-8 |
trRamCompType |
Trace RAM Sink Component Type (RAM Sink) |
R |
0x9 |
12 |
trRamHasSRAM |
This RAM Sink supports SRAM mode |
R |
SD |
13 |
trRamHasSMEM |
This RAM Sink supports SMEM (System Memory) mode |
R |
SD |
23-14 |
— |
Reserved for future versions of this standard |
— |
0 |
31-24 |
— |
Reserved for vendor specific implementation details |
— |
SD |
|
Note
|
Single RAM Sink may support both SRAM and SMEM modes, but not both of them may be enabled at the same time. It is also possible to have more than one RAM Sink in a system. |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
1-0 |
— |
Always 0 (two LSB of 32-bit address) |
R |
0 |
31-2 |
trRamStartLow |
Byte address of start of trace sink circular buffer. It is always aligned on at least a 32-bit/4-byte boundary. An SRAM sink will usually have |
WARL |
Undef or fixed to 0 |
For a bus with an address larger than 32-bit, corresponding High registers define the MSB part of such a larger address.
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
31-0 |
trRamStartHigh |
High order bits (63:32) of |
WARL |
Undef |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
1-0 |
— |
Always 0 (two LSB of 32-bit address) |
R |
0 |
31-2 |
trRamLimitLow |
Highest absolute 32-bit part of address of trace circular buffer. The |
WARL |
Undef |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
31-0 |
trRamLimitHigh |
High order bits (63:32) of |
WARL |
Undef |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
0 |
trRamWrap |
Set to 1 by hardware when |
WARL |
0 |
1 |
— |
Always 0 (bit B1 of 32-bit address) |
R |
0 |
32-2 |
trRamWPLow |
Absolute 32-bit part of address in trace sink memory where next trace message will be written. Fixed to a natural boundary. After a trace word write occurs while |
WARL |
Undef |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
31-0 |
trRamWPHigh |
High order bits (63:32) of |
WARL |
Undef |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
1-0 |
— |
Always 0 (two LSB of 32-bit address) |
R |
0 |
31-2 |
trRamRPLow |
Absolute 32-bit part of address in trace circular memory buffer visible through |
WARL |
Undef |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
31-0 |
trRamRPHigh |
High order bits (63:32) of |
WARL |
Undef |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
31-0 |
trRamData |
Read (and optional write) value for trace sink memory access. SRAM is always accessed by 32-bit words through this path regardless of the actual width of the sink memory. Required for SRAM mode and optional for SMEM mode. |
R or RW |
Undef |
|
Note
|
When trace capture was wrapped around (trRamWrap = 1) beginning of trace is not available and oldest packets/messages in the trace buffer (starting at address in trRamWP) will be most likely not complete. Trace decoders must look for the start of a message. Also when trace is stopped on wrap around, the very last message recorded in trace memory may not be complete.
|
Implementations when a trace buffer in system memory will be bigger than 4GB is desired will be unlikely, so in most cases trace tools would not need to use trRamWPHigh and trRamRPHigh registers.
Table below shows typical Trace RAM Sink configurations. Implementing other configurations is not suggested as trace tools may not support it without adjustments.
| Mode | trRamStart | trRamLimit | trRamWP | trRamRP | trRamData |
|---|---|---|---|---|---|
SRAM |
0 |
Hard coded to max size (2^M) at reset, but can be possibly trimmed |
Required |
Required |
Required |
SMEM Generic |
Any (2^N aligned) |
Any ( |
Required |
Not implemented |
Not implemented |
SMEM Fixed |
Fixed (2^N aligned) |
Fixed to max size at reset ( |
Required |
Not implemented |
Not implemented |
|
Note
|
Value A means alignment which depends on memory access width. If we have memory access width of 32-bits, A=4 and value of trRamLimit register should be 0x…FC. Some implementations may impose bigger alignment of trace data (to allow more efficient transfer rates) for SMEM mode. For SRAM mode A must be 4 as access to trace via trRamData is always 32-bits wide.
|
Trace tool should start interacting with Trace RAM Sink by releasing RAM Sink from reset by setting trRamActive = 1 and waiting for this bit to be set. After that it should verify trRamEmpty = 1, read trRamImpl and verify trRamCompType and trRamVer?? fields. Values of trRamHasSRAM/SMEM fields will provide main types of RAM Sink being implemented.
Later trRamMode should be set (depending on desired RAM Sink mode). It is important to set this field first as other registers may behave differently for SRAM and SMEM modes.
In SRAM mode, the trace memory is dedicated for trace storage and trRamStart?? registers should be settable (usually both not implemented and return 0). trRamLimitLow registers may be either hardcoded (to reflect physical SRAM size) or writable (allowing trimming RAM size allowing faster wrap-around or sharing same memory with some other components in the system).
Detection of valid ranges of each trRamStart?? and trRamLimit?? registers should be performed by writing 0 and 0xFFFFFFFF.
After setting 0, the lowest possible value must be set. After setting 0xFFFFFFFF the highest possible value must be set. If the highest value for trRamStartHigh or trRamLimitHigh is 0, it means the register is NOT implemented.
Some implementations may provide different limits for different start addresses, so the trace tool should always set trRamStart?? registers first - this option can be used when a particular implementation has two different RAM regions (each with different physical memory size).
Not every value may be settable in trRamStart/Limit registers. Value written may be trimmed (for example aligned on a particular 2^N boundary) and a trace tool should verify values being written. In case accepted values are different from what was provided by the user, a message should be printed which may allow the user to adjust (possbly suboptimal) settings.
Registers trRamStart?? and trRamLimit?? are usually set at the beginning of a debug/trace session and never changed.
|
Important
|
In SMEM mode (trRamMode = 1) trace tool should never set trRamStart?? and trRamLimit?? registers outside of range provided by the user as otherwise raw trace being written to memory may corrupt running code and/or data or stack. This type of errors may be very difficult to diagnose as in complex system code (or data) being overwritten by trace may be used way, way later after actual corruption was made.
|
Having both trRamStart/Limit?? registers set, the tool should try to set trRamRP?? to the same value as trRamLimit??. If it is settable it means that the trRamData register should be used to read the trace. Otherwise collected trace must be read using normal, physical memory accesses (in range defined by trRamStart/Limit?? registers).
Before enabling RAM Trace Sink (by setting trRamEnable = 1) the trace tool should set trRamWP?? registers (usually to the same values as in trRamStart?? register). Enabling trace must NOT change any of trRamStart/Size/WP/RP?? registers. Just after the trace is enabled trRamWP?? may change as a result of trace being added to trace memory.
After trace is enabled and active (trRamEnable = 1 or trRamEmpty = 0), the trace tool should NOT write any of trRamStart/Limit/WP?? registers.
Setting trRamRP and reading trRamData may be attempted while trace is active, but support for reading SRAM trace while trace is active may not always be implemented. In such a case write to trRamRP must be ignored and trRamData read must not advance trRamRP. Reading the trace in the SMEM mode via normal memory reads is always allowed.
|
Note
|
Even if reading trace (while trace is active) is implemented, circular trace buffer may be overwritten even several times, so values being read by trRamData will be of no use. However when trace is started/stopped by infrequent triggers, reading SRAM trace may be useful. However the very last packet in memory may be incomplete as the last trace word may be buffered inside (and trRamEmpty = 0 will be observed).
|
|
Note
|
Trace RAM Sink may implement writing trace by writing to trRamData, but this mode is usable only for testing, so will most likely not be implemented. Trace tool is not required to support writing to the trRamData register.
|
The Trace Funnel combines messages/packets from multiple sources into a single trace stream. It is implementation-dependent how many incoming messages/packets are accepted before it is switching to another input cycle and in what order. But a continuous stream of messages/packets at one input cannot cause other inputs to not be handled. Most fair implementation would be to process just a single message/packet from each input in round-robin fashion.
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
0 |
trFunnelActive |
Primary enable/reset for trace funnel. When 0, the Trace Funnel may have clocks gated off or be powered down, and other register locations may be inaccessible. Hardware may take an arbitrarily long time to process power-up and power-down and will indicate completion when the read value of this bit matches what was written. |
RW |
0 |
1 |
trFunnelEnable |
1: Trace Funnel enabled. Setting |
RW |
0 |
2 |
— |
Reserved |
— |
0 |
3 |
trFunnelEmpty |
Reads 1 when Trace Funnel internal buffers are empty |
R |
1 |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
3-0 |
trFunnelVerMajor |
Trace Funnel Component Major Version. Value 1 means the component is compliant with this document. |
R |
1 |
7-4 |
trFunnelVerMinor |
Trace Funnel Component Minor Version. Value 0 means the component is compliant with this document. |
R |
0 |
11-8 |
trFunnelCompType |
Trace Funnel Component Type (Trace Funnel) |
R |
0x8 |
23-12 |
— |
Reserved for future versions of this standard |
— |
0 |
31-24 |
— |
Reserved for vendor specific implementation details |
— |
SD |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
15-0 |
trFunnelDisInput |
1: Funnel input #n is disabled (incoming messages are ignored). |
WARL |
0 |
|
Note
|
trFunnelDisInput register is optional. When not implemented (or never set) it will read as 0, which means that all inputs are always enabled. When implemented, it can be set to 0xFFFF to detect which inputs maybe disabled in that trace funnel. Disabling inputs is needed when a single trace encoder may provide output to more than one possible active destination/sink.
|
Trace data may be sent to chip pins through an interface called the Pin Interface Block (PIB). This interface typically operates at a few hundred MHz and can sometimes be higher with careful constraints and board layout or by using LVDS or other high-speed signal protocol. PIB may consist of just one signal and in this configuration may be called SWT (Serial-Wire Trace). Alternative configurations include a trace clock (TRC_CLK) and 1/2/4/8/16 parallel trace data signals (TRC_DATA) timed to that trace clock. WARL register fields are used to determine specific PIB capabilities.
The modes and behavior described here are intended to be compatible with trace probes available in the market.
PIB Register Interface
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
0 |
trPibActive |
Primary enable/reset for PIB Sink component. When 0, the PIB Sink may have clocks gated off or be powered down, and other register locations may be inaccessible. Hardware may take an arbitrarily long time to process power-up and power-down and will indicate completion when the read value of this bit matches what was written. |
RW |
0 |
1 |
trPibEnable |
0: PIB does not accept input but holds output(s) at idle state defined by pibMode. |
RW |
0 |
2 |
— |
Reserved |
— |
0 |
3 |
trPibEmpty |
Reads 1 when PIB internal buffers are empty |
R |
1 |
7-4 |
trPibMode |
Select mode for output pins. Allowed values are described in the |
WARL |
0 |
8 |
trPibClkCenter |
In parallel modes, adjust TRC_CLK timing to the center of the bit period. This can be set only if |
WARL |
SD |
9 |
trPibCalibrate |
Set this to 1 to generate a repeating calibration pattern to help tune a probe’s signal delays, bit rate, etc. The calibration pattern is described below. Optional. |
WARL |
0 |
11-10 |
— |
Reserved |
— |
0 |
14-12 |
trPibAsyncFreq |
0: Alignment synchronization packets disabled (may be the only choice for some protocols) |
WARL |
SD |
15 |
— |
Reserved |
— |
0 |
31-16 |
trPibDivider |
Timebase selection for the PIB module. The input clock is divided by |
WARL |
SD |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
3-0 |
trPibVerMajor |
Trace PIB Sink Component Major Version. Value 1 means the component is compliant with this document. |
R |
1 |
7-4 |
trPibVerMinor |
Trace PIB Sink Component Minor Version. Value 0 means the component is compliant with this document. |
R |
0 |
11-8 |
trPibCompType |
Trace PIB Sink Component Type (PIB Sink) |
R |
0xA |
23-12 |
— |
Reserved for future versions of this standard |
— |
0 |
31-24 |
— |
Reserved for vendor specific implementation details |
— |
SD |
Software can determine what modes are available by attempting to write each mode setting to the WARL field trPibMode and reading back to see if the value was accepted.
| Mode | trPibMode | trPibClkCenter | Bit rate |
|---|---|---|---|
Off |
0 |
X |
— |
SWT Manchester |
4 |
X |
1/2 |
SWT UART |
5 |
X |
1 |
TRC_CLK + 1 TRC_DATA |
8 |
0 |
1 |
TRC_CLK + 2 TRC_DATA |
9 |
0 |
1 |
TRC_CLK + 4 TRC_DATA |
10 |
0 |
1 |
TRC_CLK + 8 TRC_DATA |
11 |
0 |
1 |
TRC_CLK + 16 TRC_DATA |
12 |
0 |
1 |
TRC_CLK + 1 TRC_DATA |
8 |
1 |
1/2 |
TRC_CLK + 2 TRC_DATA |
9 |
1 |
1/2 |
TRC_CLK + 4 TRC_DATA |
10 |
1 |
1/2 |
TRC_CLK + 8 TRC_DATA |
11 |
1 |
1/2 |
TRC_CLK + 16 TRC_DATA |
12 |
1 |
1/2 |
Since the PIB supports many different modes, it is necessary to follow a particular programming sequence:
-
Activate the PIB by setting
trPibActive. -
Set the
trPibMode,trPibDivider,trPibClkCenter, andtrPibCalibratefields. This will set the TRC_DATA outputs to the quiescent state (whether that is high or low depends ontrPibMode) and start TRC_CLK running. -
Activate the receiving device, such as a trace probe. Allow time for PLL to sync up, if using a PLL with a parallel PIB mode.
-
Set
trPibEnable. This enables the PIB to generate output either immediately (calibration mode) or when the Trace Encoder or Trace Funnel begins sending trace messages/packets.
-
Trace messages/packets are considered as sequences of bytes and are always transmitted with LSB bits/bytes first.
-
In 16-bit mode the first byte of message/packet is transmitted on LSB bits #0-#7 and second/odd byte will be transmitted on MSB bits#8-#15.
-
Idle sequences (no message/packet to be sent) are transmitted between messages.
-
Idle sequence depends on trace protocol and must be defined in a way allowing detection of the start of first byte of message/packet following the idle sequence.
-
Idle sequences are defined in documents where trace protocols are defined.
-
Traditionally, off-chip trace has used this protocol. There are a number of parallel data signals (TRC_DATA0..15) and one continuously-running trace clock (TRC_CLK). The data rate of several parallel signals can be much higher than either of the serial-wire protocols.
This protocol is oriented to send full, variable length trace messages/packets rather than fixed-width trace words.
When a message start is detected, this sample and possibly the next few (depending on the width of TRC_DATA) are collected until a complete byte has been received. Bytes are transmitted LSB first, with TRC_DATA[0] representing the LSB in each beat of data. The receiver continues collecting bytes until a complete message has been received. The criteria for this depends on the trace format. After the last byte of a message, the data signals may then go to their idle state or a new message may begin in the next bit period.
The trace clock, TRC_CLK, normally has edges coincident with the TRC_DATA edges. Typically, a trace probe will delay trace data or use a PLL to recover a sampling clock that is twice the frequency of TRC_CLK and shifted 90 degrees so that its rising edges occur near the center of each bit period. If the PIB implementation supports it, the debugger can set trPibClkCenter to change the timing of TRC_CLK so that there is a TRC_CLK edge at the center of each bit period on TRC_DATA. Note that this option cuts the data rate in half relative to normal parallel mode and still requires the probe to sample TRC_DATA on both edges of TRC_CLK.
This example shows 8-bit parallel mode with trPibClkCenter = 0 transmitting a 5-byte message/packet followed by a 2-byte message/packet.
And an example showing 8-bit parallel mode transmitting a 4-byte packet with trPibClkCenter = 1
In optional calibration mode, the PIB transmits a repeating pattern. Probes can use this to automatically tune input delays due to skew on different PIB signal lines and to adjust to the transmitter’s data rate (trPibDivider and trPibClkCenter). Calibration patterns for each mode are listed below.
| Mode | Calibration Bytes | Wire Sequence |
|---|---|---|
UART, Manchester |
AA 55 00 FF |
alternating 1/0, then all 0, then all 1 |
1-bit parallel |
AA 55 00 FF |
alternating 1/0, then all 0, then all 1 |
2-bit parallel |
66 66 CC 33 |
2, 1, 2, 1, 2, 1, 2, 1, 0, 3, 0, 3, 3, 0, 3, 0 |
4-bit parallel |
5A 5A F0 0F |
A, 5, A, 5, 0, F, F, 0 |
8-bit parallel |
AA 55 00 FF |
AA, 55, 00, FF |
16-bit parallel |
AA AA 55 55 00 00 FF FF |
AAAA, 5555, 0000, FFFF |
|
Note
|
Calibration mode may be used even by probes which do not support calibration of trace just to assure trace routing on PCB is correct and PIB is correctly enabled. It may be also possible to use calibration mode to check trace signal routing from SoC using scope or logic analyzer. |
In this mode, the PIB outputs complete trace messages encapsulated between a start bit and a stop bit. Each bit period is divided into 2 phases and the sequential values of the TRC_DATA[0] pin during those 2 phases denote the bit value. Bits of the message are transmitted LSB first. The idle state of TRC_DATA[0] is low in this mode.
| Bit | Phase 1 | Phase 2 |
|---|---|---|
start |
1 |
0 |
logic 0 |
0 |
1 |
logic 1 |
1 |
0 |
stop/idle |
0 |
0 |
In UART protocol, the PIB outputs bytes of a trace message encapsulated in a 10-bit packet consisting of a low start bit, 8 data bits, LSB first, and a high stop bit. Another packet may begin immediately following the stop bit or there may be an idle period between packets. When no data is being sent, TRC_DATA[0] is high in this mode.
Some SoCs may have an Advanced Trace Bus (ATB) infrastructure to manage trace produced by other components. In such systems, it is feasible to route RISC-V trace output to the ATB through an ATB Bridge. This module manages the interface to ATB, generating ATB trace records that encapsulate RISC-V trace produced by the Trace Encoder or Trace Funnel. There is a control register that includes trace on/off control and a field allowing software to set the Trace Source ID to be used on the ATB. This Trace Source ID allows software to extract RISC-V trace from the combined trace. This interface is compatible with AMBA 4 ATB v1.1.
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
0 |
trAtbBridgeActive |
Primary enable for the ATB Bridge. When 0, the ATB Bridge may have clocks gated off or be powered down, and other register locations may be inaccessible. Hardware may take an arbitrarily long time to process power-up and power-down and will indicate completion when the read value of this bit matches what was written. |
RW |
0 |
1 |
trAtbBridgeEnable |
1: ATB Bridge enabled. Setting |
RW |
0 |
2 |
— |
Reserved |
— |
0 |
3 |
trAtbBridgeEmpty |
Reads 1 when ATB Bridge internal buffers are empty |
R |
1 |
7-4 |
— |
Reserved |
— |
0 |
14-8 |
trAtbBridgeID |
ID of this node on ATB. Values of 0x00 and 0x70-0x7F are reserved by the ATB specification and should not be used. |
RW |
0 |
| Bit | Field | Description | RW | Reset |
|---|---|---|---|---|
3-0 |
trAtbBridgeVerMajor |
ATB Bridge Component Major Version. Value 1 means the component is compliant with this document. |
R |
1 |
7-4 |
trAtbBridgeVerMinor |
ATB Bridge Component Minor Version. Value 0 means the component is compliant with this document. |
R |
0 |
11-8 |
trAtbBridgeCompType |
ATB Bridge Component Type (ATB Bridge) |
R |
0xE |
14-12 |
trAtbBridgeAsyncFreq |
0: Alignment synchronization packets disabled (may be the only choice for some protocols) |
WARL |
SD |
23-15 |
— |
Reserved for future versions of this standard |
— |
0 |
31-24 |
— |
Reserved for vendor specific implementation details |
— |
SD |
An implementation determines the data widths of the connection from the Trace Encoder or Trace Funnel and of the ATB port.
This (non-normative) chapter gives an of what needs to be done to put together complete RISC-V trace implementation without getting familiar with every detail of every register.
Minimal General Registers/Fields
These requirements are applicable to the entire trace sub-system.
-
One
Trace Encoderper hart being traced is required. -
At least one of Trace RAM or Trace PIB sinks or Trace ATB Bridge is required as the final destination of an encoded RISC-V trace.
-
Implementations providing custom transport only are NOT considered fully compliant with this specification as custom trace tools will be needed.
-
-
Each trace component in a system is required to implement
tr??Controlandtr??Implregisters.-
tr??Activebit must be settable to 0 or 1, although reset itself is NOT required. -
tr??Enablebit must be settable to 0 or 1 and must support flushing (if applicable) when changed from 1 to 0. -
tr??Emptybit must read as 0 when the trace component has some trace data internally buffered (may be hard-coded to 1). -
tr??VerMajor,tr??VerMinorandtr??CompTypemust be implemented.
-
Minimal Trace Encoder Register/Fields
-
Bit
trTeInstTracingmust be implemented (to start/stop instruction trace output from Trace Encoder). -
One of
trTeInstMode= 3 (Branch Trace) or 6 (History Trace) must be implemented (can be a hard-coded value). -
At least one of the non-0 values of
trTeInstSyncModemust be settable (or hard-coded). -
Field
trTeFormatmust correspond to implemented trace protocol (0 for E-Trace or 1 for N-Trace). -
Fields
trTeProtocolMajorandtrTeProtocolMinormust return versions of implemented protocol. -
All other registers/fields/bits may be tied to 0.
Minimal Trace RAM Sink Register/Fields
SRAM mode only:
-
Bit
trRamHasSRAMmust be tied to 1 andtrRamModemust be tied to 0. -
Bit
trRamWrapmust be implemented. -
Register
trRamLimitLowmust be implemented, but can be hard coded to value '2^M-4' (address 0x..FC). -
Register
trRamWPLowmust at least accept a write of 0. -
Register
trRamRPLowmust accept any 32-bit aligned value in inclusive range < 0 ..trRamLimitLow>.-
If width of access to SRAM is wider than 32-bits any 32-bit aligned value of
trRamRPmust be allowed and reads must be buffered.
-
-
Register
trRamDatamust be implemented for reading only. -
All other registers/fields/bits may be tied to 0.
SMEM mode only:
-
Bit
trRamHasSMEMmust be tied to 1 andtrRamModemust be tied to 1. -
Bit
trRamWrapmust be implemented. -
Register
trRamStartmust be implemented, but can be hard coded to value '2^N' (address 0x..00). -
Register
trRamLimitmust be implemented, but can be hard coded to value '2^N + 2^M-4' (address 0x..FC). -
Registers
trRamWPmust accept any 32-bit aligned value in inclusive range <trRamStart..trRamLimit>. -
All other registers/fields/bits may be tied to 0.
Minimal Trace PIB Sink Register/Fields
It is hard to define required mode as it depends on SoC bandwidth requirements and capabilities, but some general guidance may be provided.
-
4-bit mode is supported by most (if not all) trace probes and less expensive MIPI20 connectors can be used.
-
1-bit and 2-bit modes should be only used when there are critical constraints on the number of MCU pins. Not all trace probes may support these modes.
-
-
Serial mode should be only considered when either limited trace is required or cores run slowly. Not all trace probes may support this mode and max allowed speeds may vary.
-
Manchester encoding is self-synchronizing and may provide a more reliable trace. However UART mode may provide better bandwidth. It is suggested to support both.
-
-
8-bit and 16-bit modes will provide better bandwidth, but require a more expensive Mictor connector and only more advanced trace probe models may support it.
-
It is suggested to provide as fast as possible trace logic clock, and allow a trace tool to set the divider in the
trPibDividerfield. -
For TRC_CLK frequencies higher than 50MHz, it is suggested to provide a calibration mode.
-
If possible implement
trPibClkCenterfor better flexibility.
-
Minimal ATB Bridge Register/Fields
-
Field
trAtbBridgeIDmust be settable by trace tool (hard-coded ID may not be handled by all trace tools).
This chapter describes what trace tools should do to reset and discover trace features.
|
Important
|
Trace tools must be provided with base addresses of all trace components. |
There are several (independent) reset bits defined by this specification
-
trTeActive- reset for Trace Encoder component (this will disable encoder from single hart) -
trFunnelActive- reset for Trace Funnel component -
trPibActive- reset for PIB component (resets Probe Interface Block only) -
trRamActive- reset for RAM component (resets RAM Sink only) -
trAtbBridgeActive- resets ATB Bridge component (resets ATB Bridge interface)
These reset bits should (when kept low) reset most of other registers/fields/bits to defined reset values.
Releasing components from reset may take time - debug tools should monitor (with reasonable timeout) if the appropriate bit actually changed from 0 to 1. Other fields/bits should remain unchanged (as were set during reset).
|
Note
|
Some of the reset values are defined as SD (system dependent) and these values should reset as well and each time to the same value as would be after power-up.
|
|
Note
|
Some bigger registers (holding RAM addresseses) may not reset - debugger is expected to write to them before enabling trace. These registers have Undef in reset the field. It should not prevent some implementations from resetting these.
|
Reset and Discovery should be performed as follows:
-
Reset the component by setting
tr??Active= 0. -
Read-back and wait until
tr??Active= 0 is read. -
Save
tr??Controlregister as it holds all reset values (it may prevent a trace tool to do read-modify operation later). -
Release from reset by setting
tr??Active= 1 and wait fortr??Active= 1 to be read (to confirm component is not in reset).
|
Important
|
When performing a write which is setting tr??Active = 1, no other bits should be changed.
|
-
Handle
tr??VerMinor/Majoras described in 'Versioning of Components' chapter.-
If
tr??VerMajoris 0 (for Trace Encoder component) either handle it as legacy version 0 or abort with an error.
-
-
Read
tr??Impland comparetr??ComTypefield with expected value. -
Set some WARL fields and read back to discover supported component configuration - make sure the component is NOT enabled (by setting
tr??Enable= 1) by mistake. -
Configure some initial values in all needed registers/fields. Read-back each one to assure these are set properly.
As we are dealing with several independent components, it is important to assure that the component which is in reset (or powered down) is keeping its outputs on safe values, so garbage trace data is not emitted.
In general it is safer to power-up and enable components starting from sinks/bridges, followed by Funnel and Encoder as last. Each implementation should test this sequence.
Enabling should work as follows:
-
Release all needed components from reset by setting
tr??Active= 1 as described above. -
Set desired mode and verify if that mode is set (regardless of discovery results).
-
For RAM Sink:
-
Setup needed addresses (if possible and desired) as these may not reset.
-
-
For PIB Sink:
-
Calibrate PIB (if possible and desired).
-
Start physical trace capture (trace probe dependent).
-
-
Configure RAM Sink/PIB Sink/ATB Bridge in appropriate mode.
-
Verify if a particular mode is set.
-
-
Set main enable for RAM Sink/PIB Sink/ATB Bridge component by setting
tr??Enable= 1.-
Read back and wait for confirmation (
tr??Enable= 1).
-
-
Enable Trace Funnel[s] in the same way.
-
Configure and Enable Trace Encoder[s] in the same way (last should be write of
trTeEnable= 1 followed by read to verify that it is set). -
Either manually set
trTeInstTracing=1and/ortrTeDataTracing=1bits or set triggers to start the trace. -
Start hart[s] to be traced (hart could be already running as well - in this case trace will be generated in the moment when
trTeInstTracingortrTeDataTracingbit is set). -
Periodically read
trTeControlfor status of trace (as it may stop by itself due to triggers).-
If RAM Sink was configured with
trRamStopOnWrap= 1, readtrRamEnableto see if RAM capture was stopped.
-
|
Note
|
Discovery may not be necessary to enable and test the trace during development of SoC. However discovery must be possible and should be tested by SoC designer - this is necessary for trace tools to work with that SoC without any customization. |
|
Note
|
Trace tools may verify a particular setting once per session, so subsequent starts of trace may be faster. |
|
Note
|
Trace tools should provide configuration settings allowing more verbose logging mode during discovery and initialization, so potential compatibility issues may be solved. |
Disabling the trace should work as follows:
-
It is essential to disable the trace from encoders associated with stopped harts as entering debug mode is NOT flushing any trace pipelines.
-
Disable and flush trace starting from Encoders, then Funnels and finally Sinks or Bridges.
-
Set
tr??Enable= 0 and wait fortr??Enable= 0 andtr??Empty= 1 for each trace component. -
It is important to do it in that order as otherwise data may be lost.
-
-
Stop physical capture if PIB sink was enabled (trace probe dependent).
-
Read the trace.
-
For RAM Trace Sink read
trRamWP- depending ontrRamWrapbit, you may read trace from two ranges. -
For RAM Trace Sink in SRAM mode, set
trRamRPand readtrRamDatamultiple times. -
For RAM Trace Sink in SMEM mode, read trace from system memory using memory read.
-
For PIB Trace Sink read trace from trace probe.
-
For ATB Bridge, read trace using Coresight components (ETB/TMC/TPIU).
-
Decoding trace
-
Decoder (in most cases) must have an access to code which is running on device either by reading it from device or from a file containing the code (binary/hex/srec/ELF).
-
The trace collected by trace probes can be read and decoded while a trace is being captured (this is called trace streaming mode).
-
There is no guarantee that the last trace packet is completed until the trace is properly flushed and disabled.
-
-
Decoding of the trace should never affect code being traced.
Value of trTeVerMajor as 0 means this is the original version of this interface.
Initially this specification was kept somewhat compatible, but after the split of components into 4K regions it was hard to list all changes.
In general the migration path from 'ver 0' (for both IP providers and tool vendors) should not be hard as the main concepts remain.
The best reference for this is the original donation from SiFive:
|
Important
|
Not all trace tools may support legacy version 0. But all such tools should reject the version 0 with a very clear message. |
This document was converted to ADOC from original proposal by SiFive hosted here:
Here is original disclaimer from this PDF document:
Document Version 20200612
Copyright © 2020 SiFive, Inc.
This document is released under a Creative Commons Attribution 4.0 International License
You are free to copy and redistribute the material in any medium or format.
You may remix, transform, and build on the material for any purpose, including commercial.
No warranties are implied.