Ring accelerators provide a hardware means of simplifying DMA transactions by converting constant address accesses to equivalent accesses via a circular data structure in memory.
DMA controllers don't need to know the state of the ring which allows multiple DMA controllers or channels to coherently share the same ring structure.
In most cases, ring accelerator programming is handled by the [Processor SDK](https://software-dl.ti.com/processor-sdk-rtos/esd/docs/latest/rtos/index.html) UDMA library.
Ring accelerator trace is a system trace source that can be captured to an on-chip embedded trace buffer (ETB) or exported to the pins to a supported debug probe.
The data contained in the ring accelerator trace is the ring operation and optionally the data that was associated with the operation as shown in Figure 0.
Ring accelerator trace is useful in debugging DMA transactions via the ring accelerator operations logged in the trace data.
There are three types of operations that a ring accelerator makes:
1. Push (head or tail flag indicates location of push)
2. Pop (empty flag indicates if ring is empty)
3. Peek (empty flag indicates if ring is empty)
Figure 0: Example trace data set captured via the UDMA Direct TR DRU example application on an AM65x EVM.
## Supported Devices
## Getting Started in CCS
To use the DMA Ring Accelerator Trace application, you must have an active debug session opened with a Keystone 3 device.
The DMA Ring Accelerator Trace window can then be opened by right-clicking any of the cores and selecting SoC Analysis→DMA Ring Accelerator Trace.
Figure 1: Open DMA Ring Accelerator Trace by right-clicking a connected core and selecting SoC Analysis→DMA Ring Accelerator Trace.
## Trace Data
The trace data contains the following fields:
- **Master ID**
A unique identifier which indicates the source of the ring operation.
- **Master Name**
The name associated with a Master ID.
The type of operation that was traced.
- **Data Message**
The data that was associated with the traced operation.
The ring number in which the trace operation occurred.
- **Global Timestamp**
The time of the traced operation clocked by the Global Timestamp Counter (GTC).
# Ring Accelerator Configuration
Figure 2: Selecting OK on the configuration screen will automatically start trace capture.
- **DMA Subsystem**
The DMA Subsystem options are device dependent and specify which DMA subsystem to trace.
- **Debugger enabled trace**
If checked, the debugger will program (and override) the ring accelerator trace control registers.
If unchecked, only the trace aggregator and receiver will be enabled.
Application code such as the CSL will be responsible for enabling trace on the ring accelerators when unchecked.
- **Message Data**
If checked, message data of ring operations will captured.
Length of message data is dependent on message size.
If unchecked, no message data will be traced or displayed in trace output.
- **Trace all rings**
If checked, all ring operations will be traced.
If unchecked, only ring operations that match the specified ring number will be traced.
- **Event ID**
Specify the event number to send when detecting a bus error (0 - 65536).
- **Overflow Ring Number**
Ring number to send overflow messages to.
# Receiver Settings
There are two options for exporting ring accelerator trace data: ETB or TPIU (pin trace).
Currently for TPIU trace only the Pro Trace receiver is supported.
Figure 3: Receiver settings configured to halt trace when CortexA53_0_0 core halts.
## Buffer Type
All receivers support circular and stop-on-full buffer types.
In circular buffer mode, the ETB or Pro Trace will overwrite data once the buffer is full continually until trace is stopped.
In stop-on-full mode, the trace capture will automatically halt when the buffer is full.
## Halt trace capture when specified core halts
All receivers support the halt trace capture when specified core halts field. When this field is set to an existing core name, the trace data recording will halt automatically when the specified core halts.
This feature is useful, along with breakpoint, in tracing the exact code that you want to profile.
The Pro Trace has two additional options that the ETB receiver does not have: Pins and Buffer Size.
Select the number of pins you will use to export data off-chip.
More pins will allow more bandwidth.
- **Buffer Size**
Select the size of buffer for binary trace data.
Note that the trace data is highly compressed in binary form and will result in files much larger than the specified buffer size.