1\page mipi_syst_decoder_protocol SyS-T Data Protocol 2 3[TOC] 4 5Overview {#syst_decoder_prot_overview} 6============================================================================== 7The SyS-T Data Protocol is a byte sequence that represents a list of variable 8length SyS-T Messages without additional padding bytes between them. The 9SyS-T Data Protocol is intended for transmission over a lower level transport 10protocol. The lower level protocol is expected to provide indicators that 11identify the start and end of a SyS-T Message. One example of a lower level 12transport protocol is the 13[MIPI System Trace Protocol](http://mipi.org/specifications/debug#STP) (STP). 14SyS-T includes message frame definitions that provides time stamping 15and framing of a SyS-T Message based on STP packet types. The usage of 16other lower level transports protocols is possible by adapting the message 17writer or low level trace output functions from the platform level code. 18 19The SyS-T Data Protocol includes various optional fields for ensuring data 20integrity or time stamping. Depending on the capabilities of the lower level 21protocol, these SyS-T Message fields may be redundant and so be omitted to 22save trace bandwidth. 23 24 25Data Field Byte Ordering {#syst_decoder_prot_byteorder} 26------------------------------------------------------------------------------ 27All numeric data fields of the SyS-T Data Protocol follow little-endian byte 28ordering where less significant bytes precede more significant ones. Only the 29optional 128-bit Guid field is an exception to this rule. Its byte odering 30follows RFC 4122 which defines Guid fields following big-endian ordering. 31 32MIPI STPv2 Protocol Encoding {#syst_decoder_prot_format} 33------------------------------------------------------------------------------ 34In order to timestamp packets and to give an indication of a valid SyS-T 35Message beginning and end, each SyS-T Message starts with a 36TIMESTAMPED STP data packet and ends with either a FLAG packet or a 37MARKED data packet. 38For environments that can only afford light weight value style traces, a 39short message encoding is also available. This encoding uses a single IO to 40generate an STP packet that is both MARKED and TIMESTAMPED. The following 41table shows the supported STP packet sequences for a SyS-T Message. Dn means 42either a D8, D16, D32 or D64 data packet. 43The Dn* stands for a sequence of 0-x repeated Dn packets (of any sizes). Dn 44packets with a smaller payload size can be combined into a Dn with a larger 45size to reduce the number of IO's. For example, two D16 IO's can be combined 46into a single D32 as long as the resulting binary payload data produces the 47same result when being copied into memory. 48 49 MIPI STPv2 Sequences | Description 50---------------------------|-------------------------------------------- 51DnMTS |Single IO short message with Dn sized payload. This message is intended for numeric value only tracing. 52DnTS-Dn*-DnM |Arbitrary length sequence starting with a time stamped data value and followed by a sequence of zero or more payload data values. The last data value is MARKED to indicate the end of the sequence. 53DnTS-Dn*-FLAG |Arbitrary length sequence starting with time stamped data value and followed by a sequence of zero or more payload data values. The sequence is terminated with a FLAG packet. 54 55The reason for supporting sequences terminated with either a MARKED or a 56FLAG packet is to simplify the implementation for SW and HW trace generators. 57HW based generates may prefer the MARKED method to save additional logic for 58issuing a FLAG. SW trace generators may prefer the FLAG variant as it 59avoids special handling for the last Dn. 60 61 62 63Message Anatomy {#syst_decoder_prot_anatomy} 64------------------------------------------------------------------------------ 65A SyS-T Message is a byte sequence that starts with a 32-bit header, followed by 66mandatory and optional data attributes. The following picture shows the layout 67of a SyS-T Message with all fields present. 68 69 70 71 72The message fields are: 73 - A 32-bit [header] (#syst_decoder_prot_header) describing the message type and content 74 - An optional 128-bit wide [GUID] (#syst_decoder_prot_guid) identifying the message originating software module. 75 - An optional [location record] (#syst_decoder_prot_location) 76 - An optional [payload length] (#syst_decoder_prot_length) 77 - An optional [SyS-T timestamp] (#syst_prot_timestamp) 78 - API specific [payload data] (#syst_decoder_prot_payload) from zero up to 64 Kbytes. 79 - An optional CRC-32C [checksum] (#syst_decoder_prot_checksum) 80 81Attributes are stored one after the other without any additional alignment bytes. 82 83SyS-T Protocol Overhead {#syst_decoder_prot_overhead} 84------------------------------------------------------------------------------ 85The typical data overhead of the SyS-T Data Protocol is 4 bytes (32 bits) per 86message unless optional elements like CRC32 checksums are enabled. 87These 4 bytes come from the 32-bit message header at the beginning 88of each message. 89 90In addition to the typical usage as a message trace, SyS-T protocol offers also 91the following protocol types for small value or bulk data transfer support: 92 93 - Single value onle traces can utilize SHORT messages. These provide a 94 zero data overhead method on STP hardware using single DnMTS 95 packets to hold the data. 96 - SyS-T raw messages can be used to stream up to 64 Kbytes of payload data 97 in a single SyS-T Message to tunnel another Data Protocol through SyS-T. 98 99 100Data Protocol Details {#syst_decoder_prot_details} 101============================================================================== 102 103Header {#syst_decoder_prot_header} 104------------------------------------------------------------------------------ 105A SyS-T header is 32-bit value using the following layout: 106 107 108 109The meaning of the individual fields is explained in the table below. 110 111Field |Bits |Description 112--------|------|----------------------------------------------------- 113RES31 |31..31|Reserved, Must be set to zero. 114RES30 |30..30|Reserved, Must be set to zero. 115SUBTYPE |24..29|Additional message type information that depends on TYPE. 116GUID |23..23|Indicates whether the optional GUID is present 117ORIGIN |12..22|message origin and/or unit information 118TS |11..11|Indicates whether the optional message time stamp is present. 119CHK |10..10|Indicates whether the optional Checksum is present at the end. 120LEN |9..9 |Indicates whether the optional Payload length is present. 121LOC |8..8 |Indicates whether the optional Location Record field is present. 122RES7 |7..7 |Reserved, Must be set to zero. 123SEVERITY|4..6 |Severity level of the message. 124TYPE |0..3 |Message type 125 126C-Definition (struct mipi_syst_msg_tag): 127\code{.cpp} 128struct mipi_syst_msg_tag { 129 mipi_syst_u32 et_type:4; /**< SyS-T message type ID */ 130 mipi_syst_u32 et_severity:3; /**< severity level of message */ 131 mipi_syst_u32 et_res7:1; /**< reserved for future use */ 132 mipi_syst_u32 et_location:1; /**< indicate location information */ 133 mipi_syst_u32 et_length:1; /**< indicate variable length message */ 134 mipi_syst_u32 et_chksum:1; /**< indicate 32bit CRC */ 135 mipi_syst_u32 et_timestamp:1;/**< indicate 64 bit timestamp */ 136 mipi_syst_u32 et_modunit:11; /**< unit for GUID or module:unit */ 137 mipi_syst_u32 et_guid:1; /**< 128 bit GUID present */ 138 mipi_syst_u32 et_subtype:6; /**< type dependent sub category */ 139 mipi_syst_u32 et_res30:1; /**< reserved for future use */ 140 mipi_syst_u32 et_res31:1; /**< reserved for future use */ 141}; 142\endcode 143 144Severity {#syst_decoder_prot_header_severity} 145------------------------------------------------------------------------------ 146 147An optional severity level is assigned to a SyS-T Message to distinguish 148informational messages from warnings and errors. Severity levels are used 149for message classification and filtering. The severity levels are ordered 150by ascending numerical values. 151 152Severity |Value | Description 153---------------------------|:-----:|---------------------------------------------- 154MIPI_SYST_SEVERITY_MAX | 0 |No assigned severity. This is used for messages that should bypass filtering. This is typically used with RAW message that tunnel other protocols over SyS-T Messages. 155MIPI_SYST_SEVERITY_FATAL | 1 |Indicates a fatal level message. Such messages provide information about a failure condition from which the system cannot recover or cannot continue to function properly. 156MIPI_SYST_SEVERITY_ERROR | 2 |Indicates an error level message. Such messages provide information about an operation failure or inappropriate action that the system is not designed to handle. Errors may or may not cause a feature or system to subsequently fail. 157MIPI_SYST_SEVERITY_WARNING | 3 |Indicates a warning level message. Such messages provide information about an undesirable, but recoverable situation that may result in problems if no actions are taken. Warning message information can be utilized to adaptively adjust system operations to avoid failures or to improve performance based on the use case. 158MIPI_SYST_SEVERITY_INFO | 4 |Indicates an information level message. Such messages provide component specific information about operational actions and progress. They are intended for component specialists to analyze system behavior. 159MIPI_SYST_SEVERITY_USER1 | 5 |Indicates a first user-defined message level for information with a higher verbosity than MIPI_SYST_SEVERITY_INFO. They are intended for component specialists to analyze system behavior in greater detail. 160MIPI_SYST_SEVERITY_USER2 | 6 |Indicates a second user-defined level for informational messages with a higher verbosity than MIPI_SYST_SEVERITY_USER1. They are intended for component specialists to analyze system behavior in even greater detail. 161MIPI_SYST_SEVERITY_DEBUG | 7 |Indicate a debug level message. Such messages provide information that is intended for system developers for detailed analysis and debug of system behavior. It provides the finest granularity of trace information and is typically used during verification and debug phases. 162 163 164Message Origin or GUID {#syst_decoder_prot_guid} 165------------------------------------------------------------------------------ 166A SyS-T Message may contain a 128-bit wide GUID to identify the instrumented 167software module in a unique way. A GUID is used if the guid bit in the header 168is set. Otherwise the header origin field defines the message origin, 169saving the bandwidth and space that would be used for the additional GUID bits. 170 171Omitting the GUID is possible when the origin field or transport layer 172information sufficiently identifies the trace emitting source. An example 173for transport layer information are the Master and Channel pairs for transports 174using MIPI System Trace Protocol. If the message was sent from a dynamically 175assigned master and channel pool, then these values are not sufficient and a 176GUID must be used to describe the origin. If the handle got initialized using 177the #MIPI_SYST_SET_HANDLE_GUID_UNIT API then the GUID is emitted directly after 178the header in each message. 179Note: 180The GUID structure follows https://www.ietf.org/rfc/rfc4122.txt. 181 182Location {#syst_decoder_prot_location} 183------------------------------------------------------------------------------ 184 185A SyS-T Message can contain location information describing the position of 186its instrumentation call either as an instruction pointer address or as a 187"file:line" ID pair. This location information is generated if one of the 188API variants with the `_LOCADDR`, `_LOC16` or `_LOC32` suffix in the name is 189used. 190 191### C Definition of Location ### 192 193\code{.cpp} 194/** 195 * Specify format of used message location information that is added to the 196 * message data if tag.et_location == 1 197 */ 198struct mipi_syst_msglocation { 199 /** Message format 200 * 0 = 16-Bit file and 16-Bit line (total: 32-bit) 201 * 1 = 32-Bit file and 32-Bit line (total: 64-bit) 202 * 2 = 32-bit code address 203 * 3 = 64-bit code address 204 */ 205 mipi_syst_u8 el_format; 206 union { 207 union mipi_syst_msglocation32 loc32; /**< data for 32-bit variant */ 208 union mipi_syst_msglocation64 loc64; /**< data for 64-bit variant */ 209 } el_u; 210}; 211 212 213/** 214 * Location information inside a message (32-bit format) 215 * Location is either the source position of the instrumentation call, or 216 * the call instruction pointer value. 217 */ 218union mipi_syst_msglocation32 { 219 struct { 220 mipi_syst_u16 etls_fileID; /**< ID of instrumented file */ 221 mipi_syst_u16 etls_lineNo; /**< line number in file */ 222 } etls_source_location; 223 mipi_syst_u32 etls_code_location:32; 224 /**< instruction pointer value */ 225}; 226 227/** 228 * Location information inside a message (64-bit format) 229 * Location is either the source position of the instrumentation call, or 230 * the call instruction pointer value. 231 */ 232union mipi_syst_msglocation64 { 233 struct { 234 mipi_syst_u32 etls_fileID; /**< ID of instrumented file */ 235 mipi_syst_u32 etls_lineNo; /**< line number in file */ 236 } etls_source_location; 237 mipi_syst_u64 etls_code_location:64; 238 /**< instruction pointer value */ 239}; 240 241\endcode 242 243Length {#syst_decoder_prot_length} 244------------------------------------------------------------------------------ 245 246The location information is followed by a 16-bit length field if the header bit 247et_length is set. This length indicates the number of message payload bytes that 248follow. 249 250### C Definition of Length ### 251 252\code{.cpp} 253 syst_u16_t ed_len; 254\endcode 255 256 257Message Payload {#syst_decoder_prot_payload} 258------------------------------------------------------------------------------ 259A SyS-T Message can contain a type specific payload of up to 64 Kbytes. The payload 260appears after the optional message fields, but before the optional checksum. 261 262Checksum {#syst_decoder_prot_checksum} 263------------------------------------------------------------------------------ 264A SyS-T Message can end with a 32-bit CRC-32C checksum calculated over all of 265the message bytes, excluding the checksum value itself. The CRC generation is 266a per SyS-T handle choice. It is enabled or disabled by the 267#MIPI_SYST_ENABLE_HANDLE_CHECKSUM API. The default is disabled. 268 269Protocol Timestamp Handling {#syst_prot_timestamp} 270============================================================================== 271The default usage for the SyS-T protocol is to rely on a transport timestamp 272generated by, for example, trace arbiter hardware or a trace creating driver. 273In this case, a SyS-T Message does not carry its own timestamp information. In 274scenarios where no hardware time stamp exists, or this timestamp is not 275accurate, SyS-T Messages can include their own time stamp. An example scenario 276for this is when messages are buffered by a trace source before they are sent. 277In this case, the hardware time stamp will reflect a later message submission 278time, not the message creation time, which is typically what is desired. 279 280Clock Synchronization {#syst_prot_timestamp_sync} 281------------------------------------------------------------------------------ 282The SyS-T protocol facilitates correlating messages that use a time stamp of 283their own with the trace timestamp of the underlying transport protocol. This 284correlation is done using a synchronisation message, which contains both the 285transport protocol timestamp and the source clock value and frequency from 286the SyS-T message clock. 287 288These data values build a time correlation point between the transport 289clock and the SyS-T message clock. If MIPI STP is the transport protocol then 290the D32TS header time stamp will define the transport time stamp. The message 291is expected to be sent periodically from any source that requires time 292synchronisation with the transport protocol. Host side tooling needs at least 293one of these records in a trace stream to do the time correlation. Typically 294these synchronization messages are sent either periodically, such as once 295every second, or at the beginning of trace emitting phases. 296 297 298SyS-T Messages Types {#syst_decoder_prot_msg_types} 299============================================================================== 300This chapter shows the major SyS-T message types. 301The type can be one of the following (See [C Definition] (@ref mipi_syst_msgtype) ): 302 303 304 305Value |SyS-T Name |Description 306--------|-------------------------|------------------------------------- 3070 |MIPI_SYST_TYPE_BUILD |SyS-T client build version information 3081 |MIPI_SYST_TYPE_SHORT32 |32 Bit message with user defined payload value 3092 |MIPI_SYST_TYPE_STRING |Text message output for UTF-8 encoded strings 3103 |MIPI_SYST_TYPE_CATALOG |Catalog message output support formatting string with parameters 3114,5 |RESERVED-FOR-FUTURE-USE |Reserved 3126 |MIPI_SYST_TYPE_RAW |Raw binary payload 3137 |MIPI_SYST_TYPE_SHORT64 |64 Bit message with user defined payload value 3148 |MIPI_SYST_TYPE_CLOCK |Timing synchronization 3159..15 |RESERVED-FOR-FUTURE-USE |Reserved 316 317For further information on the different message type contents, read chapter 8 318in the MIPI Alliance Specification for System Software-Trace (SyS-T). 319
