1 /* 2 * Percepio Trace Recorder for Tracealyzer v4.10.3 3 * Copyright 2023 Percepio AB 4 * www.percepio.com 5 * 6 * SPDX-License-Identifier: Apache-2.0 7 */ 8 9 /** 10 * @file 11 * 12 * @brief Public trace event APIs. 13 */ 14 15 #ifndef TRC_EVENT_H 16 #define TRC_EVENT_H 17 18 #if (TRC_USE_TRACEALYZER_RECORDER == 1) 19 20 #if (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING) 21 22 #include <trcTypes.h> 23 24 #ifdef __cplusplus 25 extern "C" { 26 #endif 27 28 /** 29 * @defgroup trace_event_apis Trace Event APIs 30 * @ingroup trace_recorder_apis 31 * @{ 32 */ 33 34 /** 35 * @internal Trace Event Structure without uTraceUnsignedBaseType_t parameters 36 */ 37 typedef struct { /* Aligned */ 38 uint16_t EventID; /**< */ 39 uint16_t EventCount; /**< */ 40 uint32_t TS; /**< */ 41 } TraceEvent0_t; 42 43 /** 44 * @internal Trace Event Structure with one uTraceUnsignedBaseType_t parameter 45 */ 46 typedef struct { /* Aligned */ 47 uint16_t EventID; /**< */ 48 uint16_t EventCount; /**< */ 49 uint32_t TS; /**< */ 50 TraceUnsignedBaseType_t uxParams[1]; /**< */ 51 } TraceEvent1_t; 52 53 /** 54 * @internal Trace Event Structure with two uTraceUnsignedBaseType_t parameters 55 */ 56 typedef struct { /* Aligned */ 57 uint16_t EventID; /**< */ 58 uint16_t EventCount; /**< */ 59 uint32_t TS; /**< */ 60 TraceUnsignedBaseType_t uxParams[2]; /**< */ 61 } TraceEvent2_t; 62 63 /** 64 * @internal Trace Event Structure with three uTraceUnsignedBaseType_t parameters 65 */ 66 typedef struct { /* Aligned */ 67 uint16_t EventID; /**< */ 68 uint16_t EventCount; /**< */ 69 uint32_t TS; /**< */ 70 TraceUnsignedBaseType_t uxParams[3]; /**< */ 71 } TraceEvent3_t; 72 73 /** 74 * @internal Trace Event Structure with four uTraceUnsignedBaseType_t parameters 75 */ 76 typedef struct { /* Aligned */ 77 uint16_t EventID; /**< */ 78 uint16_t EventCount; /**< */ 79 uint32_t TS; /**< */ 80 TraceUnsignedBaseType_t uxParams[4]; /**< */ 81 } TraceEvent4_t; 82 83 /** 84 * @internal Trace Event Structure with five uTraceUnsignedBaseType_t parameters 85 */ 86 typedef struct { /* Aligned */ 87 uint16_t EventID; /**< */ 88 uint16_t EventCount; /**< */ 89 uint32_t TS; /**< */ 90 TraceUnsignedBaseType_t uxParams[5]; /**< */ 91 } TraceEvent5_t; 92 93 /** 94 * @internal Trace Event Structure with six uTraceUnsignedBaseType_t parameters 95 */ 96 typedef struct { /* Aligned */ 97 uint16_t EventID; /**< */ 98 uint16_t EventCount; /**< */ 99 uint32_t TS; /**< */ 100 TraceUnsignedBaseType_t uxParams[6]; /**< */ 101 } TraceEvent6_t; 102 103 /** 104 * @internal Trace Core Event Data Structure 105 */ 106 typedef struct TraceCoreEventData /* Aligned */ 107 { 108 uint32_t eventCounter; /**< */ 109 uint32_t reserved; /* alignment */ 110 } TraceCoreEventData_t; 111 112 /** 113 * @internal Trace Event Data Table Structure. 114 */ 115 typedef struct TraceEventDataTable /* Aligned */ 116 { 117 TraceCoreEventData_t coreEventData[TRC_CFG_CORE_COUNT]; /**< Holds data about current event for each core/isr depth */ 118 } TraceEventDataTable_t; 119 120 /** 121 * @internal Initialize event trace system. 122 * 123 * @param[in] pxBuffer Pointer to memory that will be used by the event 124 * trace system. 125 * 126 * @retval TRC_FAIL Failure 127 * @retval TRC_SUCCESS Success 128 */ 129 traceResult xTraceEventInitialize(TraceEventDataTable_t* pxBuffer); 130 131 /** 132 * Create a raw data event (i.e. not event code provided) 133 * @param pxSource The source buffer which should be copied 134 * @param ulSize The size of the data to be copied 135 * 136 * @retval TRC_FAIL 137 * @retval TRC_SUCCESS 138 */ 139 traceResult xTraceEventCreateRawBlocking(const void* pxSource, uint32_t ulSize); 140 141 /** 142 * @brief Creates an event with 0 parameters. 143 * 144 * @param[in] uiEventCode Event code. 145 * 146 * @retval TRC_FAIL Failure 147 * @retval TRC_SUCCESS Success 148 */ 149 traceResult xTraceEventCreate0(uint32_t uiEventCode); 150 151 /** 152 * @brief Creates an event with 1 parameters. 153 * 154 * @param[in] uiEventCode Event code. 155 * @param[in] uxParam1 First parameter. 156 * 157 * @retval TRC_FAIL Failure 158 * @retval TRC_SUCCESS Success 159 */ 160 traceResult xTraceEventCreate1(uint32_t uiEventCode, TraceUnsignedBaseType_t uxParam1); 161 162 /** 163 * @brief Creates an event with 2 parameters. 164 * 165 * @param[in] uiEventCode Event code. 166 * @param[in] uxParam1 First parameter. 167 * @param[in] uxParam2 Second parameter. 168 * 169 * @retval TRC_FAIL Failure 170 * @retval TRC_SUCCESS Success 171 */ 172 traceResult xTraceEventCreate2(uint32_t uiEventCode, TraceUnsignedBaseType_t uxParam1, TraceUnsignedBaseType_t uxParam2); 173 174 /** 175 * @brief Creates an event with 3 parameters. 176 * 177 * @param[in] uiEventCode Event code. 178 * @param[in] uxParam1 First parameter. 179 * @param[in] uxParam2 Second parameter. 180 * @param[in] uxParam3 Third parameter. 181 * 182 * @retval TRC_FAIL Failure 183 * @retval TRC_SUCCESS Success 184 */ 185 traceResult xTraceEventCreate3(uint32_t uiEventCode, TraceUnsignedBaseType_t uxParam1, TraceUnsignedBaseType_t uxParam2, TraceUnsignedBaseType_t uxParam3); 186 187 /** 188 * @brief Creates an event with 4 parameters. 189 * 190 * @param[in] uiEventCode Event code. 191 * @param[in] uxParam1 First parameter. 192 * @param[in] uxParam2 Second parameter. 193 * @param[in] uxParam3 Third parameter. 194 * @param[in] uxParam4 Fourth parameter. 195 * 196 * @retval TRC_FAIL Failure 197 * @retval TRC_SUCCESS Success 198 */ 199 traceResult xTraceEventCreate4(uint32_t uiEventCode, TraceUnsignedBaseType_t uxParam1, TraceUnsignedBaseType_t uxParam2, TraceUnsignedBaseType_t uxParam3, TraceUnsignedBaseType_t uxParam4); 200 201 /** 202 * @brief Creates an event with 5 parameters. 203 * 204 * @param[in] uiEventCode Event code. 205 * @param[in] uxParam1 First parameter. 206 * @param[in] uxParam2 Second parameter. 207 * @param[in] uxParam3 Third parameter. 208 * @param[in] uxParam4 Fourth parameter. 209 * @param[in] uxParam5 Fifth parameter. 210 * 211 * @retval TRC_FAIL Failure 212 * @retval TRC_SUCCESS Success 213 */ 214 traceResult xTraceEventCreate5(uint32_t uiEventCode, TraceUnsignedBaseType_t uxParam1, TraceUnsignedBaseType_t uxParam2, TraceUnsignedBaseType_t uxParam3, TraceUnsignedBaseType_t uxParam4, TraceUnsignedBaseType_t uxParam5); 215 216 /** 217 * @brief Creates an event with 6 parameters. 218 * 219 * @param[in] uiEventCode Event code. 220 * @param[in] uxParam1 First parameter. 221 * @param[in] uxParam2 Second parameter. 222 * @param[in] uxParam3 Third parameter. 223 * @param[in] uxParam4 Fourth parameter. 224 * @param[in] uxParam5 Fifth parameter. 225 * @param[in] uxParam6 Sixth parameter. 226 * 227 * @retval TRC_FAIL Failure 228 * @retval TRC_SUCCESS Success 229 */ 230 traceResult xTraceEventCreate6(uint32_t uiEventCode, TraceUnsignedBaseType_t uxParam1, TraceUnsignedBaseType_t uxParam2, TraceUnsignedBaseType_t uxParam3, TraceUnsignedBaseType_t uxParam4, TraceUnsignedBaseType_t uxParam5, TraceUnsignedBaseType_t uxParam6); 231 232 /** 233 * @brief Creates an offline event with no parameters and a payload 234 * 235 * @param[in] uiEventCode Event code. 236 * @param[in] puxData Pointer to payload buffer 237 * @param[in] uxSize Size of the payload buffer 238 * 239 * @retval TRC_FAIL Failure 240 * @retval TRC_SUCCESS Success 241 */ 242 traceResult xTraceEventCreateDataOffline0(uint32_t uiEventCode, const TraceUnsignedBaseType_t* const puxData, TraceUnsignedBaseType_t uxSize); 243 244 245 /** 246 * @brief Creates an event with no parameters and a payload 247 * 248 * @param[in] uiEventCode Event code. 249 * @param[in] puxData Pointer to payload buffer 250 * @param[in] uxSize Size of the payload buffer 251 * 252 * @retval TRC_FAIL Failure 253 * @retval TRC_SUCCESS Success 254 */ 255 traceResult xTraceEventCreateData0(uint32_t uiEventCode, const TraceUnsignedBaseType_t* const puxData, TraceUnsignedBaseType_t uxSize); 256 257 /** 258 * @brief Creates an event with 1 parameter and a payload 259 * 260 * @param[in] uiEventCode Event code. 261 * @param[in] uxParam1 First parameter. 262 * @param[in] puxData Pointer to payload buffer. 263 * @param[in] uxSize Size of the payload buffer. 264 * 265 * @retval TRC_FAIL Failure 266 * @retval TRC_SUCCESS Success 267 */ 268 traceResult xTraceEventCreateData1(uint32_t uiEventCode, TraceUnsignedBaseType_t uxParam1, const TraceUnsignedBaseType_t* const puxData, TraceUnsignedBaseType_t uxSize); 269 270 /** 271 * @brief Creates an event with 2 parameters and a payload 272 * 273 * @param[in] uiEventCode Event code. 274 * @param[in] uxParam1 First parameter. 275 * @param[in] uxParam2 Second parameter. 276 * @param[in] puxData Pointer to payload buffer. 277 * @param[in] uxSize Size of the payload buffer. 278 * 279 * @retval TRC_FAIL Failure 280 * @retval TRC_SUCCESS Success 281 */ 282 traceResult xTraceEventCreateData2(uint32_t uiEventCode, TraceUnsignedBaseType_t uxParam1, TraceUnsignedBaseType_t uxParam2, const TraceUnsignedBaseType_t* const puxData, TraceUnsignedBaseType_t uxSize); 283 284 /** 285 * @brief Creates an event with 3 parameters and a payload 286 * 287 * @param[in] uiEventCode Event code. 288 * @param[in] uxParam1 First parameter. 289 * @param[in] uxParam2 Second parameter. 290 * @param[in] uxParam3 Third parameter. 291 * @param[in] puxData Pointer to payload buffer. 292 * @param[in] uxSize Size of the payload buffer. 293 * 294 * @retval TRC_FAIL Failure 295 * @retval TRC_SUCCESS Success 296 */ 297 traceResult xTraceEventCreateData3(uint32_t uiEventCode, TraceUnsignedBaseType_t uxParam1, TraceUnsignedBaseType_t uxParam2, TraceUnsignedBaseType_t uxParam3, const TraceUnsignedBaseType_t* const puxData, TraceUnsignedBaseType_t uxSize); 298 299 /** 300 * @brief Creates an event with 4 parameters and a payload 301 * 302 * @param[in] uiEventCode Event code. 303 * @param[in] uxParam1 First parameter. 304 * @param[in] uxParam2 Second parameter. 305 * @param[in] uxParam3 Third parameter. 306 * @param[in] uxParam4 Fourth parameter. 307 * @param[in] puxData Pointer to payload buffer. 308 * @param[in] uxSize Size of the payload buffer. 309 * 310 * @retval TRC_FAIL Failure 311 * @retval TRC_SUCCESS Success 312 */ 313 traceResult xTraceEventCreateData4(uint32_t uiEventCode, TraceUnsignedBaseType_t uxParam1, TraceUnsignedBaseType_t uxParam2, TraceUnsignedBaseType_t uxParam3, TraceUnsignedBaseType_t uxParam4, const TraceUnsignedBaseType_t* const puxData, TraceUnsignedBaseType_t uxSize); 314 315 /** 316 * @brief Creates an event with 5 parameters and a payload 317 * 318 * @param[in] uiEventCode Event code. 319 * @param[in] uxParam1 First parameter. 320 * @param[in] uxParam2 Second parameter. 321 * @param[in] uxParam3 Third parameter. 322 * @param[in] uxParam4 Fourth parameter. 323 * @param[in] uxParam5 Fifth parameter. 324 * @param[in] puxData Pointer to payload buffer. 325 * @param[in] uxSize Size of the payload buffer. 326 * 327 * @retval TRC_FAIL Failure 328 * @retval TRC_SUCCESS Success 329 */ 330 traceResult xTraceEventCreateData5(uint32_t uiEventCode, TraceUnsignedBaseType_t uxParam1, TraceUnsignedBaseType_t uxParam2, TraceUnsignedBaseType_t uxParam3, TraceUnsignedBaseType_t uxParam4, TraceUnsignedBaseType_t uxParam5, const TraceUnsignedBaseType_t* const puxData, TraceUnsignedBaseType_t uxSize); 331 332 /** 333 * @brief Creates an event with 6 parameters and a payload 334 * 335 * @param[in] uiEventCode Event code. 336 * @param[in] uxParam1 First parameter. 337 * @param[in] uxParam2 Second parameter. 338 * @param[in] uxParam3 Third parameter. 339 * @param[in] uxParam4 Fourth parameter. 340 * @param[in] uxParam5 Fifth parameter. 341 * @param[in] uxParam6 Sixth parameter. 342 * @param[in] puxData Pointer to payload buffer. 343 * @param[in] uxSize Size of the payload buffer. 344 * 345 * @retval TRC_FAIL Failure 346 * @retval TRC_SUCCESS Success 347 */ 348 traceResult xTraceEventCreateData6(uint32_t uiEventCode, TraceUnsignedBaseType_t uxParam1, TraceUnsignedBaseType_t uxParam2, TraceUnsignedBaseType_t uxParam3, TraceUnsignedBaseType_t uxParam4, TraceUnsignedBaseType_t uxParam5, TraceUnsignedBaseType_t uxParam6, const TraceUnsignedBaseType_t* const puxData, TraceUnsignedBaseType_t uxSize); 349 350 /** 351 * @brief Gets trace event size. 352 * 353 * @param[in] pvAddress Pointer to initialized trace event. 354 * @param[out] puiSize Size. 355 * 356 * @retval TRC_FAIL Failure 357 * @retval TRC_SUCCESS Success 358 */ 359 traceResult xTraceEventGetSize(const void* const pvAddress, uint32_t* puiSize); 360 361 /** @} */ 362 363 #ifdef __cplusplus 364 } 365 #endif 366 367 #endif /* (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING) */ 368 369 #endif /* (TRC_USE_TRACEALYZER_RECORDER == 1) */ 370 371 #endif /* TRC_EVENT_H */ 372
