MIPI STP Decoder
The MIPI System Trace Protocol (MIPI STP) was developed as a generic base protocol that can be shared by multiple application-specific trace protocols. It serves as a wrapper protocol that merges disparate streams that typically contain different trace protocols from different trace sources. Stream consists of opcode (shortest is 4 bit long) followed by optional data and optional timestamp. There are opcodes for data (8, 16, 32, 64 bit data marked/not marked, with or without timestamp), stream recognition (master and channel), synchronization (ASYNC opcode) and others.
One example where protocol is used is ARM Coresight STM (System Trace Macrocell) where data written to Stimulus Port registers maps directly to STP stream.
This module can be used to perform on-chip decoding of the data stream. STP v2 is used.
Usage
Decoder is initialized with a callback. A callback is called on each decoded opcode.
Decoder has internal state since there are dependency between opcodes (e.g. timestamp can be
relative). Decoder can be in synchronization or not. Initial state is configurable.
If decoder is not synchronized to the stream then it decodes each nibble in search for ASYNC opcode.
Loss of synchronization can be indicated to the decoder by calling
mipi_stp_decoder_sync_loss(). mipi_stp_decoder_decode() is used to decode the data.
Limitations
There are following limitations:
Decoder supports only little endian architectures.
When decoding nibbles, it is more efficient when core supports unaligned memory access. Implementation supports optimized version with unaligned memory access and generic one. Optimized version is used for ARM Cortex-M (expect for M0).
Limited set of the most common opcodes is implemented.
API documentation
- group mipi_stp_decoder_apis
Defines
-
STP_DECODER_TYPE2STR(_type)
Convert type to a string literal.
- Parameters:
_type – type
- Returns:
String literal.
Typedefs
-
typedef void (*mipi_stp_decoder_cb)(enum mipi_stp_decoder_ctrl_type type, union mipi_stp_decoder_data data, uint64_t *ts, bool marked)
Callback signature.
Callback is called whenever an element from STPv2 stream is decoded.
Note
Callback is called with interrupts locked.
- Param type:
Type. See mipi_stp_decoder_ctrl_type.
- Param data:
Data. Data associated with a given
type.- Param ts:
Timestamp. Present if not NULL.
- Param marked:
Set to true if opcode was marked.
Enums
-
enum mipi_stp_decoder_ctrl_type
STPv2 opcodes.
Values:
-
enumerator STP_DATA4 = 1
-
enumerator STP_DATA8 = 2
-
enumerator STP_DATA16 = 4
-
enumerator STP_DATA32 = 8
-
enumerator STP_DATA64 = 16
-
enumerator STP_DECODER_NULL = 128
-
enumerator STP_DECODER_MASTER
-
enumerator STP_DECODER_MERROR
-
enumerator STP_DECODER_CHANNEL
-
enumerator STP_DECODER_VERSION
-
enumerator STP_DECODER_FREQ
-
enumerator STP_DECODER_GERROR
-
enumerator STP_DECODER_FLAG
-
enumerator STP_DECODER_ASYNC
-
enumerator STP_DECODER_NOT_SUPPORTED
-
enumerator STP_DATA4 = 1
Functions
-
int mipi_stp_decoder_init(const struct mipi_stp_decoder_config *config)
Initialize the decoder.
- Parameters:
config – Configuration.
- Return values:
0 – On successful initialization.
negative – On failure.
-
int mipi_stp_decoder_decode(const uint8_t *data, size_t len)
Decode STPv2 stream.
Function decodes the stream and calls the callback for every decoded element.
- Parameters:
data – Data.
len – Data length.
- Return values:
0 – On successful decoding.
negative – On failure.
-
void mipi_stp_decoder_sync_loss(void)
Indicate synchronization loss.
If detected, then decoder starts to look for ASYNC marker and drops all data until ASYNC is found. Synchronization can be lost when there is data loss (e.g. due to overflow).
-
union mipi_stp_decoder_data
- #include <mipi_stp_decoder.h>
Union with data associated with a given STP opcode.
-
struct mipi_stp_decoder_config
- #include <mipi_stp_decoder.h>
Decoder configuration.
Public Members
-
bool start_out_of_sync
Indicates that decoder start in out of sync state.
-
mipi_stp_decoder_cb cb
Callback.
-
bool start_out_of_sync
-
STP_DECODER_TYPE2STR(_type)