1\page mipi_syst_api_overview Instrumentation API Overview 2 3[TOC] 4 5Overview {#mipi_syst_api} 6============================================================================== 7The SyS-T instrumentation API is exposed as a set of CPP Macros with the 8prefix `MIPI_SYST_`. The definitions for the instrumentation API are provided by 9the C-Language header file `mipi_syst.h`. This is the only header needed for 10adding instrumentation calls to your software. 11 12See the @ref mipi_syst_example_page for a `hello world` style example that uses 13the instrumentation API. 14 15SyS-T Library States {#mipi_syst_api_state} 16============================================================================== 17 18The SyS-T library has 2 levels of data states to store information. These are: 19 201. global state (mipi_syst_header structure) 212. per handle state (mipi_syst_handle structure) 22 23The global state contains data for the operation of the library itself and 24is shared between SyS-T handles. The global state is initialized and 25destroyed using the #MIPI_SYST_INIT and #MIPI_SYST_SHUTDOWN functions. 26 27SyS-T can operate with multiple global state structures. In this case the 28initialization functions with the "_STATE" suffix in their names must be used 29to specify the intended state (See #MIPI_SYST_INIT_STATE, 30#MIPI_SYST_SHUTDOWN_STATE, #MIPI_SYST_INIT_HANDLE_STATE and #MIPI_SYST_ALLOC_HANDLE_STATE). 31 32The handle state is unique for each SyS-T 33handle and allows sending trace data without causing data races with other 34SyS-T handles. 35 36SyS-T Handles {#mipi_syst_api_handles} 37============================================================================== 38Each message generating instrumentation API expects a pointer to a `SyS-T handle` 39as the first parameter. This handle builds the connection between the 40Software API and trace emitting hardware or driver code. It can best be seen 41as something similar to a FILE * in traditional C/C++ file IO. 42 43A SyS-T handle is obtained by using one of the #MIPI_SYST_ALLOC_HANDLE, 44#MIPI_SYST_ALLOC_HANDLE_STATE, #MIPI_SYST_INIT_HANDLE, or 45#MIPI_SYST_INIT_HANDLE_STATE macros. A handle is destroyed by calling 46#MIPI_SYST_DELETE_HANDLE on it. 47 48SyS-T and Multi-threading {#mipi_syst_api_threading} 49============================================================================== 50The SyS-T library provides a thread safe usage model that, for performance 51reasons, does not use any data locking techniques. It is important to 52understand this model to avoid incorrect usage that would result in hard to 53analyze data races or corrupted message data output. The threading model is 54defined by the following rules: 55 56- SyS-T operates thread safe, as long as __SyS-T handles are not shared 57 between simultaneously executing threads__. 58- Sharing a SyS-T handle between threads requires locking around each 59 instrumentation API call in the code using SyS-T. 60- Platform adaption code that modifies the global library mipi_syst_header 61 state may need locking inside its hook functions to protect state data 62 members. See the mipi_stp_sim platform code in 63 platform/mipi_stp_sim/src/mipi_syst_platform.c for an example where locking 64 is required. 65 66The recommended SyS-T usage is to create a SyS-T handle exclusively for each 67thread and to store it in thread local storage. This usage provides low 68software overhead, as no locking is required while utilizing trace arbiter 69hardware or trace creating drivers that are capable of supporting multiple 70data channels in parallel. 71 72API Name Conventions {#mipi_syst_api_conventions} 73============================================================================== 74All API functions are provided as CPP macros with the prefix `MIPI_SYST_`. 75 76The data transmitting instrumentation calls exist in up to 4 variants for 77generating additional location information. Location information describes 78the instrumentation position of the API as either an instruction pointer 79address, or a source "file:line" ID pair. This information is used during 80trace decoding to map message data back to source locations. The name 81conventions for the variants are: 82 83- **MIPI_SYST_<API-NAME>(...)**<BR> 84 API without location information generation 85 86- **MIPI_SYST_<API-NAME>_LOC16(..,f, ...)**<BR> 87 API variant that includes the instrumentation source position as a 88 "file:line" id pair of 16-bit width each. The file id is user defined 89 and passed as an additional parameter. This API requires the SyS-T platform 90 feature define #MIPI_SYST_PCFG_ENABLE_LOCATION_RECORD. 91 92- **MIPI_SYST_<API-NAME>_LOC32(..,f, ...)**<BR> 93 API variant that includes the instrumentation source position as a 94 "file:line" id pair of 32-bit width each. The file id is user defined 95 and passed as an additional parameter. This API requires the SyS-T platform 96 feature define #MIPI_SYST_PCFG_ENABLE_LOCATION_RECORD. 97 98- **MIPI_SYST_<API-NAME>_LOCADDR(...)**<BR> 99 API variant that includes the instrumentation instruction address as 100 location. This API requires the SyS-T platform feature defines 101 #MIPI_SYST_PCFG_ENABLE_LOCATION_RECORD and #MIPI_SYST_PCFG_ENABLE_LOCATION_ADDRESS. 102 103See description of the #MIPI_SYST_DEBUG API call as an example showing all 104variants. 105 106SyS-T Message Attributes {#mipi_syst_api_attributes} 107============================================================================== 108The SyS-T message produced by an API call contains mandatory and optional 109data attributes. This chapter describes the attributes and how they are 110defined when adding instrumentation calls.The message attributes are: 111 112- A 32-bit header describing the message type and content 113- An optional 128-bit wide GUID identifying the message originating software 114 module. 115- An optional location record 116- An optional payload length 117- API specific payload data of up to 64 Kbytes 118- An optional CRC-32C checksum. 119 120 121 122SyS-T Message Header {#mipi_syst_api_header} 123------------------------------------------------------------------------------ 124Each SyS-T message starts with a 32-bit header, which is defined by the data 125structure mipi_syst_msg_tag. The header contains the following information: 126 127- __Type and Subtype__ fields identifying the Message Type.<BR> 128 These fields are set internally by the API call. 129 130- Software __Module__ and __Unit__ IDs<BR> 131 These fields identify the software module that originated the message. They 132 are taken from the SyS-T handle used in the call. See the API calls 133 #MIPI_SYST_SET_HANDLE_GUID_UNIT and #MIPI_SYST_SET_HANDLE_MODULE_UNIT for an 134 example how the origin fields are used. 135 136- __Message Severity__<BR> 137 Each message contains a 3-bit severity level defined by the mipi_syst_severity 138 enumeration. 139 140- __Content__ Bits<BR> 141 These bits define what other optional attributes are present in the message. 142 143Message Origin GUID {#mipi_syst_api_guid} 144------------------------------------------------------------------------------ 145A message can contain a 128-bit wide GUID to identify the instrumented SW 146module in a unique way. The GUID is emitted directly after the header if 147the handle was initialized using the #MIPI_SYST_SET_HANDLE_GUID_UNIT API. The 148GUID structure follows the RFC 4122 conventions and can be obtained 149using various tools. One example is the `uuidgen` command on Linux. 150 151Message Location Information {#mipi_syst_api_loc} 152------------------------------------------------------------------------------ 153A message can contain location information describing the position of its 154instrumentation call either as an instruction pointer address or as a 155"file:line" ID pair. This location information is generated if one of the 156API variants with the `_LOCADDR`, `_LOC16` or `_LOC32` suffix in the name is 157used. 158 159Message Payload {#mipi_syst_api_payload} 160------------------------------------------------------------------------------ 161A message contains type-specific payload of up to 64 Kbytes, which is 162generated internally by the API function from its parameters. These functions 163also insert a 16-bit payload length field when when enabled by 164the MIPI_SYST_ENABLE_HANDLE_LENGTH API. 165 166Message Checksum {#mipi_syst_api_chkssum} 167------------------------------------------------------------------------------ 168A message can end with a 32-bit CRC32C checksum calculated over all of the 169message bytes, excluding the checksum value itself. The CRC generation is a 170per SyS-T handle choice. It is enabled or disabled by the 171#MIPI_SYST_ENABLE_HANDLE_CHECKSUM API. The default is disabled. 172 173
