1 /* 2 * Percepio Trace Recorder for Tracealyzer v4.8.1 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 Macro helper for setting trace event parameter count. 36 */ 37 #define TRC_EVENT_SET_PARAM_COUNT(id, n) ((uint16_t)(((uint16_t)(id)) | ((((uint16_t)(n)) & 0xF) << 12))) 38 39 /** 40 * @internal Macro helper for getting trace event parameter count. 41 */ 42 #define TRC_EVENT_GET_PARAM_COUNT(id) (((id) >> 12u) & 0xFU) 43 44 #if (TRC_CFG_CORE_COUNT > 1) 45 #define TRC_EVENT_SET_EVENT_COUNT(c) ((uint16_t)(((TRC_CFG_GET_CURRENT_CORE() & 0xF) << 12) | ((uint16_t)(c) & 0xFFF))) 46 #else 47 #define TRC_EVENT_SET_EVENT_COUNT(c) ((uint16_t)(c)) 48 #endif 49 50 /** 51 * @internal Macro helper for setting base event data. 52 */ 53 #define SET_BASE_EVENT_DATA(pxEvent, eventId, paramCount, eventCount) \ 54 ( \ 55 (pxEvent)->EventID = TRC_EVENT_SET_PARAM_COUNT(eventId, paramCount), \ 56 (pxEvent)->EventCount = TRC_EVENT_SET_EVENT_COUNT(eventCount), \ 57 xTraceTimestampGet(&(pxEvent)->TS) \ 58 ) 59 60 /** 61 * @internal Macro helper for resetting trace event data. 62 */ 63 #define RESET_EVENT_DATA(p) \ 64 ( \ 65 (p)->pvBlob = 0, \ 66 (p)->size = 0, \ 67 (p)->offset = 0 \ 68 ) 69 70 /** 71 * @internal Macro optimization for getting trace event size. 72 */ 73 #define TRC_EVENT_GET_SIZE(pvAddress, puiSize) (*(uint32_t*)(puiSize) = sizeof(TraceEvent0_t) + (TRC_EVENT_GET_PARAM_COUNT(((TraceEvent0_t*)(pvAddress))->EventID)) * sizeof(TraceBaseType_t), TRC_SUCCESS) 74 75 /** 76 * @internal Macro optimization for getting trace event data pointer with an offset. 77 */ 78 #define TRC_EVENT_GET_RAW_DATA(xEventHandle, uiOffset, uiSize, ppvData) ((void)(uiSize), *(void**)(ppvData) = (void*)&((uint8_t*)((TraceEventData_t*)(xEventHandle))->pvBlob)[uiOffset], TRC_SUCCESS) 79 80 /** 81 * @internal Macro optimization for getting trace event payload pointer with an offset. 82 */ 83 #define TRC_EVENT_GET_PAYLOAD(xEventHandle, uiOffset, uiSize, ppvData) ((void)(uiSize), *(void**)(ppvData) = (void*)&((uint8_t*)((TraceEventData_t*)(xEventHandle))->pvBlob)[sizeof(TraceEvent0_t) + (uiOffset)], TRC_SUCCESS) 84 85 /** 86 * @internal Macro optimization for getting trace event remaining payload size. 87 */ 88 #define TRC_EVENT_PAYLOAD_REMAINING(xEventHandle, puiValue) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(*(uint32_t*)(puiValue) = ((TraceEventData_t*)(xEventHandle))->size - ((TraceEventData_t*)(xEventHandle))->offset, TRC_SUCCESS) 89 90 /** 91 * @internal Macro optimization for getting trace event used payload size. 92 */ 93 #define TRC_EVENT_PAYLOAD_USED(xEventHandle, puiValue) (*(uint32_t*)(puiValue) = ((TraceEventData_t*)(xEventHandle))->offset - sizeof(TraceEvent0_t), TRC_SUCCESS) 94 95 /** 96 * @internal Macro optimization getting trace event payload size. 97 */ 98 #define TRC_EVENT_PAYLOAD_SIZE(xEventHandle, puiValue) (*(uint32_t*)(puiValue) = ((TraceEventData_t*)(xEventHandle))->size - sizeof(TraceEvent0_t), TRC_SUCCESS) 99 100 /** 101 * @internal Macro optimization for adding a pointer address to trace event. 102 */ 103 #define TRC_EVENT_ADD_POINTER(xEventHandle, value) \ 104 TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3( \ 105 ((void**)((TraceEventData_t*)(xEventHandle))->pvBlob)[((TraceEventData_t*)(xEventHandle))->offset / sizeof(void*)] = (value), \ 106 ((TraceEventData_t*)(xEventHandle))->offset += sizeof(void*), \ 107 TRC_SUCCESS \ 108 ) 109 110 /** 111 * @internal Macro optimization for adding a unsigned base type to trace event. 112 */ 113 #define TRC_EVENT_ADD_UNSIGNED_BASE_TYPE(xEventHandle, value) \ 114 TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3( \ 115 ((TraceUnsignedBaseType_t*)((TraceEventData_t*)(xEventHandle))->pvBlob)[((TraceEventData_t*)(xEventHandle))->offset / sizeof(TraceUnsignedBaseType_t)] = (value), \ 116 ((TraceEventData_t*)(xEventHandle))->offset += sizeof(TraceUnsignedBaseType_t), \ 117 TRC_SUCCESS \ 118 ) 119 120 /** 121 * @internal Macro optimization for adding a 32-bit value to trace event. 122 */ 123 #define TRC_EVENT_ADD_32(xEventHandle, value) \ 124 TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3( \ 125 ((uint32_t*)((TraceEventData_t*)(xEventHandle))->pvBlob)[((TraceEventData_t*)(xEventHandle))->offset / sizeof(uint32_t)] = (value), \ 126 ((TraceEventData_t*)(xEventHandle))->offset += sizeof(uint32_t), \ 127 TRC_SUCCESS \ 128 ) 129 130 /** 131 * @internal Macro optimization for adding a 16-bit value to trace event. 132 */ 133 #define TRC_EVENT_ADD_16(xEventHandle, value) \ 134 TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3( \ 135 ((uint16_t*)((TraceEventData_t*)(xEventHandle))->pvBlob)[((TraceEventData_t*)(xEventHandle))->offset / sizeof(uint16_t)] = (value), \ 136 ((TraceEventData_t*)(xEventHandle))->offset += sizeof(uint16_t), \ 137 TRC_SUCCESS \ 138 ) 139 140 /** 141 * @internal Macro optimization for adding a 8-bit value to trace event. 142 */ 143 #define TRC_EVENT_ADD_8(xEventHandle, value) \ 144 TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3( \ 145 ((uint8_t*)((TraceEventData_t*)(xEventHandle))->pvBlob)[((TraceEventData_t*)(xEventHandle))->offset / sizeof(uint8_t)] = (value), \ 146 ((TraceEventData_t*)(xEventHandle))->offset += sizeof(uint8_t), \ 147 TRC_SUCCESS \ 148 ) 149 150 /** 151 * @internal Macro optimization for beginning an offline trace event. 152 */ 153 #define TRC_EVENT_BEGIN_OFFLINE(uiEventCode, uiPayloadSize, pxEventHandle) \ 154 ( \ 155 (xTraceEventBeginRawOffline((uint32_t)(sizeof(TraceEvent0_t) + (uiPayloadSize)), pxEventHandle)) == TRC_SUCCESS ? \ 156 ( \ 157 SET_BASE_EVENT_DATA((TraceEvent0_t*)(((TraceEventData_t*)*(pxEventHandle))->pvBlob), \ 158 uiEventCode, \ 159 (((TraceEventData_t*)*(pxEventHandle))->size - sizeof(TraceEvent0_t)) / sizeof(TraceBaseType_t), \ 160 pxTraceEventDataTable->coreEventData[TRC_CFG_GET_CURRENT_CORE()].eventCounter), \ 161 ((TraceEventData_t*)*(pxEventHandle))->offset += sizeof(TraceEvent0_t), \ 162 TRC_SUCCESS \ 163 ) : TRC_FAIL \ 164 ) 165 166 /** 167 * @internal Trace Event Structure without uTraceUnsignedBaseType_t parameters 168 */ 169 typedef struct { /* Aligned */ 170 uint16_t EventID; /**< */ 171 uint16_t EventCount; /**< */ 172 uint32_t TS; /**< */ 173 } TraceEvent0_t; 174 175 /** 176 * @internal Trace Event Structure with one uTraceUnsignedBaseType_t parameter 177 */ 178 typedef struct { /* Aligned */ 179 uint16_t EventID; /**< */ 180 uint16_t EventCount; /**< */ 181 uint32_t TS; /**< */ 182 TraceUnsignedBaseType_t uxParams[1]; /**< */ 183 } TraceEvent1_t; 184 185 /** 186 * @internal Trace Event Structure with two uTraceUnsignedBaseType_t parameters 187 */ 188 typedef struct { /* Aligned */ 189 uint16_t EventID; /**< */ 190 uint16_t EventCount; /**< */ 191 uint32_t TS; /**< */ 192 TraceUnsignedBaseType_t uxParams[2]; /**< */ 193 } TraceEvent2_t; 194 195 /** 196 * @internal Trace Event Structure with three uTraceUnsignedBaseType_t parameters 197 */ 198 typedef struct { /* Aligned */ 199 uint16_t EventID; /**< */ 200 uint16_t EventCount; /**< */ 201 uint32_t TS; /**< */ 202 TraceUnsignedBaseType_t uxParams[3]; /**< */ 203 } TraceEvent3_t; 204 205 /** 206 * @internal Trace Event Structure with four uTraceUnsignedBaseType_t parameters 207 */ 208 typedef struct { /* Aligned */ 209 uint16_t EventID; /**< */ 210 uint16_t EventCount; /**< */ 211 uint32_t TS; /**< */ 212 TraceUnsignedBaseType_t uxParams[4]; /**< */ 213 } TraceEvent4_t; 214 215 /** 216 * @internal Trace Event Structure with five uTraceUnsignedBaseType_t parameters 217 */ 218 typedef struct { /* Aligned */ 219 uint16_t EventID; /**< */ 220 uint16_t EventCount; /**< */ 221 uint32_t TS; /**< */ 222 TraceUnsignedBaseType_t uxParams[5]; /**< */ 223 } TraceEvent5_t; 224 225 /** 226 * @internal Trace Event Structure with six uTraceUnsignedBaseType_t parameters 227 */ 228 typedef struct { /* Aligned */ 229 uint16_t EventID; /**< */ 230 uint16_t EventCount; /**< */ 231 uint32_t TS; /**< */ 232 TraceUnsignedBaseType_t uxParams[6]; /**< */ 233 } TraceEvent6_t; 234 235 /** 236 * @internal Trace Event Structure with seven uTraceUnsignedBaseType_t parameters 237 */ 238 typedef struct { /* Aligned */ 239 uint16_t EventID; /**< */ 240 uint16_t EventCount; /**< */ 241 uint32_t TS; /**< */ 242 TraceUnsignedBaseType_t uxParams[7]; /**< */ 243 } TraceEvent7_t; 244 245 /** 246 * @internal Trace Event Data Structure 247 */ 248 typedef struct TraceEventData /* Aligned */ 249 { 250 void* pvBlob; /**< */ 251 uint32_t size; /**< */ 252 uint32_t offset; /**< */ 253 } TraceEventData_t; 254 255 /** 256 * @internal Trace Core Event Data Structure 257 */ 258 typedef struct TraceCoreEventData /* Aligned */ 259 { 260 TraceEventData_t eventData[(TRC_CFG_MAX_ISR_NESTING)+1]; /* aligned */ 261 uint32_t eventCounter; /**< */ 262 uint32_t reserved; /* alignment */ 263 TRACE_ALLOC_CRITICAL_SECTION() 264 } TraceCoreEventData_t; 265 266 /** 267 * @internal Trace Event Data Table Structure. 268 */ 269 typedef struct TraceEventDataTable /* Aligned */ 270 { 271 TraceCoreEventData_t coreEventData[TRC_CFG_CORE_COUNT]; /**< Holds data about current event for each core/isr depth */ 272 } TraceEventDataTable_t; 273 274 extern TraceEventDataTable_t* pxTraceEventDataTable; 275 276 /** 277 * @internal Initialize event trace system. 278 * 279 * @param[in] pxBuffer Pointer to memory that will be used by the event 280 * trace system. 281 * 282 * @retval TRC_FAIL Failure 283 * @retval TRC_SUCCESS Success 284 */ 285 traceResult xTraceEventInitialize(TraceEventDataTable_t* pxBuffer); 286 287 /** 288 * @brief Gets trace event size. 289 * 290 * @param[in] pvAddress Pointer to initialized trace event. 291 * @param[out] puiSize Size. 292 * 293 * @retval TRC_FAIL Failure 294 * @retval TRC_SUCCESS Success 295 */ 296 traceResult xTraceEventGetSize(const void* const pvAddress, uint32_t* puiSize); 297 298 /** 299 * @brief Creates an event with 0 parameters. 300 * 301 * @param[in] uiEventCode Event code. 302 * 303 * @retval TRC_FAIL Failure 304 * @retval TRC_SUCCESS Success 305 */ 306 traceResult xTraceEventCreate0(uint32_t uiEventCode); 307 308 /** 309 * @brief Creates an event with 1 parameters. 310 * 311 * @param[in] uiEventCode Event code. 312 * @param[in] uxParam1 First parameter. 313 * 314 * @retval TRC_FAIL Failure 315 * @retval TRC_SUCCESS Success 316 */ 317 traceResult xTraceEventCreate1(uint32_t uiEventCode, TraceUnsignedBaseType_t uxParam1); 318 319 /** 320 * @brief Creates an event with 2 parameters. 321 * 322 * @param[in] uiEventCode Event code. 323 * @param[in] uxParam1 First parameter. 324 * @param[in] uxParam2 Second parameter. 325 * 326 * @retval TRC_FAIL Failure 327 * @retval TRC_SUCCESS Success 328 */ 329 traceResult xTraceEventCreate2(uint32_t uiEventCode, TraceUnsignedBaseType_t uxParam1, TraceUnsignedBaseType_t uxParam2); 330 331 /** 332 * @brief Creates an event with 3 parameters. 333 * 334 * @param[in] uiEventCode Event code. 335 * @param[in] uxParam1 First parameter. 336 * @param[in] uxParam2 Second parameter. 337 * @param[in] uxParam3 Third parameter. 338 * 339 * @retval TRC_FAIL Failure 340 * @retval TRC_SUCCESS Success 341 */ 342 traceResult xTraceEventCreate3(uint32_t uiEventCode, TraceUnsignedBaseType_t uxParam1, TraceUnsignedBaseType_t uxParam2, TraceUnsignedBaseType_t uxParam3); 343 344 /** 345 * @brief Creates an event with 4 parameters. 346 * 347 * @param[in] uiEventCode Event code. 348 * @param[in] uxParam1 First parameter. 349 * @param[in] uxParam2 Second parameter. 350 * @param[in] uxParam3 Third parameter. 351 * @param[in] uxParam4 Fourth parameter. 352 * 353 * @retval TRC_FAIL Failure 354 * @retval TRC_SUCCESS Success 355 */ 356 traceResult xTraceEventCreate4(uint32_t uiEventCode, TraceUnsignedBaseType_t uxParam1, TraceUnsignedBaseType_t uxParam2, TraceUnsignedBaseType_t uxParam3, TraceUnsignedBaseType_t uxParam4); 357 358 /** 359 * @brief Creates an event with 5 parameters. 360 * 361 * @param[in] uiEventCode Event code. 362 * @param[in] uxParam1 First parameter. 363 * @param[in] uxParam2 Second parameter. 364 * @param[in] uxParam3 Third parameter. 365 * @param[in] uxParam4 Fourth parameter. 366 * @param[in] uxParam5 Fifth parameter. 367 * 368 * @retval TRC_FAIL Failure 369 * @retval TRC_SUCCESS Success 370 */ 371 traceResult xTraceEventCreate5(uint32_t uiEventCode, TraceUnsignedBaseType_t uxParam1, TraceUnsignedBaseType_t uxParam2, TraceUnsignedBaseType_t uxParam3, TraceUnsignedBaseType_t uxParam4, TraceUnsignedBaseType_t uxParam5); 372 373 /** 374 * @brief Creates an event with 6 parameters. 375 * 376 * @param[in] uiEventCode Event code. 377 * @param[in] uxParam1 First parameter. 378 * @param[in] uxParam2 Second parameter. 379 * @param[in] uxParam3 Third parameter. 380 * @param[in] uxParam4 Fourth parameter. 381 * @param[in] uxParam5 Fifth parameter. 382 * @param[in] uxParam6 Sixth parameter. 383 * 384 * @retval TRC_FAIL Failure 385 * @retval TRC_SUCCESS Success 386 */ 387 traceResult xTraceEventCreate6(uint32_t uiEventCode, TraceUnsignedBaseType_t uxParam1, TraceUnsignedBaseType_t uxParam2, TraceUnsignedBaseType_t uxParam3, TraceUnsignedBaseType_t uxParam4, TraceUnsignedBaseType_t uxParam5, TraceUnsignedBaseType_t uxParam6); 388 389 /** 390 * @internal Begins a raw trace event offline. 391 * 392 * This routine begins a trace event with specified size. Must call xTraceEventEnd() 393 * to finalize event creation. Does not care about RecorderEnabled. 394 * 395 * @param[in] uiSize Size. 396 * @param[in] pxEventHandle Pointer to initialized trace event. 397 * 398 * @retval TRC_FAIL Failure 399 * @retval TRC_SUCCESS Success 400 */ 401 traceResult xTraceEventBeginRawOffline(uint32_t uiSize, TraceEventHandle_t* pxEventHandle); 402 403 /** 404 * @internal Begins a blocking trace event offline. 405 * 406 * This routine begins a trace event with specified size. Must call xTraceEventEnd() 407 * to finalize event creation. Does not care about RecorderEnabled. 408 * 409 * @param[in] uiSize Size. 410 * @param[in] pxEventHandle Pointer to initialized trace event. 411 * 412 * @retval TRC_FAIL Failure 413 * @retval TRC_SUCCESS Success 414 */ 415 traceResult xTraceEventBeginRawOfflineBlocking(uint32_t uiSize, TraceEventHandle_t* pxEventHandle); 416 417 /** 418 * @internal Begins a trace event offline. 419 * 420 * This routine begins a trace event with specified size. Must call xTraceEventEnd() 421 * to finalize event creation. Does not care about RecorderEnabled. 422 * 423 * @param[in] uiSize Size. 424 * @param[in] pxEventHandle Pointer to initialized trace event. 425 * 426 * @retval TRC_FAIL Failure 427 * @retval TRC_SUCCESS Success 428 */ 429 #define xTraceEventBeginOffline TRC_EVENT_BEGIN_OFFLINE 430 431 /** 432 * @brief Begins a trace event. 433 * 434 * This routine begins a trace event with specified size. Must call xTraceEventEnd() 435 * to finalize event creation. Does not care about RecorderEnabled. 436 * 437 * @param[in] uiSize Size. 438 * @param[in] pxEventHandle Pointer to initialized trace event. 439 * 440 * @retval TRC_FAIL Failure 441 * @retval TRC_SUCCESS Success 442 */ 443 #define xTraceEventBegin(uiEventCode, uiTotalPayloadSize, pxEventHandle) \ 444 (xTraceIsRecorderEnabled() ? xTraceEventBeginOffline(uiEventCode, uiTotalPayloadSize, pxEventHandle) : TRC_FAIL) 445 446 /** 447 * @internal Ends a trace event offline. 448 * 449 * This routine ends the event that was begun by calling on xTraceEventBegin(). 450 * Does not care about uiRecorderEnabled. 451 * 452 * @param[in] xEventHandle Pointer to initialized trace event. 453 * 454 * @retval TRC_FAIL Failure 455 * @retval TRC_SUCCESS Success 456 */ 457 traceResult xTraceEventEndOffline(TraceEventHandle_t xEventHandle); 458 459 /** 460 * @internal Ends a blocking event offline. 461 * 462 * Ends the event that was begun by calling on xTraceEventBegin() 463 * 464 * @param[in] xEventHandle Pointer to initialized trace event. 465 * 466 * @retval TRC_FAIL Failure 467 * @retval TRC_SUCCESS Success 468 */ 469 traceResult xTraceEventEndOfflineBlocking(TraceEventHandle_t xEventHandle); 470 471 /** 472 * @brief Ends a trace event. 473 * 474 * This routine ends the event that was begun by calling on xTraceEventBegin(). 475 * Does not care about uiRecorderEnabled. 476 * 477 * @param[in] xEventHandle Pointer to initialized trace event. 478 * 479 * @retval TRC_FAIL Failure 480 * @retval TRC_SUCCESS Success 481 */ 482 #define xTraceEventEnd(xEventHandle) \ 483 (!xTraceIsRecorderEnabled() ? TRC_FAIL : xTraceEventEndOffline(xEventHandle)) 484 485 /** 486 * @brief Adds data to event payload. 487 * 488 * @param[in] xEventHandle Pointer to initialized trace event. 489 * @param[in] puxData Pointer to data. 490 * @param[in] uxSize Size. 491 * 492 * @retval TRC_FAIL Failure 493 * @retval TRC_SUCCESS Success 494 */ 495 traceResult xTraceEventAddData(TraceEventHandle_t xEventHandle, const TraceUnsignedBaseType_t* const puxData, TraceUnsignedBaseType_t uxSize); 496 497 /** 498 * @brief Adds string to event payload. 499 * 500 * @param[in] xEventHandle Pointer to initialized trace event. 501 * @param[in] szString Pointer to string. 502 * @param[in] uiLength Size. 503 * 504 * @retval TRC_FAIL Failure 505 * @retval TRC_SUCCESS Success 506 */ 507 #define xTraceEventAddString(xEventHandle, szString, uiLength) xTraceEventAddData(xEventHandle, (TraceUnsignedBaseType_t*)(szString), (((uiLength) + (sizeof(TraceUnsignedBaseType_t) - 1)) / sizeof(TraceUnsignedBaseType_t))) 508 509 #if ((TRC_CFG_USE_TRACE_ASSERT) == 1) 510 511 /** 512 * @brief Gets trace event data pointer with an offset. 513 * 514 * This routine gets a trace event data pointer with an offset. It also verifies 515 * the size so it won't go outside its' buffer. 516 * 517 * @param[in] xEventHandle Pointer to initialized trace event. 518 * @param[in] uiOffset Offset. 519 * @param[in] uiSize Size. 520 * @param[out] ppvData Data. 521 * 522 * @retval TRC_FAIL Failure 523 * @retval TRC_SUCCESS Success 524 */ 525 traceResult xTraceEventGetRawData(TraceEventHandle_t xEventHandle, uint32_t uiOffset, uint32_t uiSize, void** ppvData); 526 527 /** 528 * @brief Gets trace event payload pointer with an offset. 529 * 530 * This routine gets a trace event payload pointer with an offset. It also verifies 531 * the size so it won't go outside its payload buffer. 532 * 533 * @param[in] xEventHandle Pointer to initialized trace event. 534 * @param[in] uiOffset Offset. 535 * @param[in] uiSize Size. 536 * @param[out] ppvData Data. 537 * 538 * @retval TRC_FAIL Failure 539 * @retval TRC_SUCCESS Success 540 */ 541 traceResult xTraceEventGetPayload(const TraceEventHandle_t xEventHandle, uint32_t uiOffset, uint32_t uiSize, void** ppvData); 542 543 /** 544 * @brief Gets the amount of remaining trace event payload. 545 * 546 * @param[in] xEventHandle Pointer to initialized trace event. 547 * @param[out] puiValue Value. 548 * 549 * @retval TRC_FAIL Failure 550 * @retval TRC_SUCCESS Success 551 */ 552 traceResult xTraceEventPayloadRemaining(const TraceEventHandle_t xEventHandle, uint32_t* puiValue); 553 554 /** 555 * @brief Gets the amount of used trace event payload. 556 * 557 * @param[in] xEventHandle Pointer to initialized trace event. 558 * @param[out] puiValue Value 559 * 560 * @retval TRC_FAIL Failure 561 * @retval TRC_SUCCESS Success 562 */ 563 traceResult xTraceEventPayloadUsed(TraceEventHandle_t xEventHandle, uint32_t* puiValue); 564 565 /** 566 * @brief Gets trace event payload size. 567 * 568 * @param[in] xEventHandle Pointer to initialized trace event. 569 * @param[out] puiValue Value 570 * 571 * @retval TRC_FAIL Failure 572 * @retval TRC_SUCCESS Success 573 */ 574 traceResult xTraceEventPayloadSize(TraceEventHandle_t xEventHandle, uint32_t* puiValue); 575 576 /** 577 * @brief Adds an unsigned base type value as trace event payload 578 * 579 * @param[in] xEventHandle Pointer to initialized trace event. 580 * @param[in] uxValue Value. 581 * 582 * @retval TRC_FAIL Failure 583 * @retval TRC_SUCCESS Success 584 */ 585 traceResult xTraceEventAddUnsignedBaseType(TraceEventHandle_t xEventHandle, TraceUnsignedBaseType_t uxValue); 586 587 /** 588 * @brief Adds a pointer address as trace event payload 589 * 590 * @param[in] xEventHandle Pointer to initialized trace event. 591 * @param[in] pvAddress Address. 592 * 593 * @retval TRC_FAIL Failure 594 * @retval TRC_SUCCESS Success 595 */ 596 traceResult xTraceEventAddPointer(TraceEventHandle_t xEventHandle, void *pvAddress); 597 598 /** 599 * @brief Adds an uint32_t as trace event payload 600 * 601 * @param[in] xEventHandle Pointer to initialized trace event. 602 * @param[in] value Value. 603 * 604 * @retval TRC_FAIL Failure 605 * @retval TRC_SUCCESS Success 606 */ 607 traceResult xTraceEventAdd32(TraceEventHandle_t xEventHandle, uint32_t value); 608 609 /** 610 * @brief Adds an uint16_t as trace event payload 611 * 612 * @param[in] xEventHandle Pointer to initialized trace event. 613 * @param[in] value Value. 614 * 615 * @retval TRC_FAIL Failure 616 * @retval TRC_SUCCESS Success 617 */ 618 traceResult xTraceEventAdd16(TraceEventHandle_t xEventHandle, uint16_t value); 619 620 /** 621 * @brief Adds an uint8_t as trace event payload. 622 * 623 * @param[in] xEventHandle Pointer to initialized trace event. 624 * @param[in] value Value. 625 * 626 * @retval TRC_FAIL Failure 627 * @retval TRC_SUCCESS Success 628 */ 629 traceResult xTraceEventAdd8(TraceEventHandle_t xEventHandle, uint8_t value); 630 631 #else /* ((TRC_CFG_USE_TRACE_ASSERT) == 1) */ 632 633 /** 634 * @brief Gets trace event size. 635 * 636 * @param[in] pvAddress Pointer to initialized trace event. 637 * @param[out] puiSize Size. 638 * 639 * @retval TRC_FAIL Failure 640 * @retval TRC_SUCCESS Success 641 */ 642 #define xTraceEventGetSize(pvAddress, puiSize) (*(uint32_t*)(puiSize) = sizeof(TraceEvent0_t) + (TRC_EVENT_GET_PARAM_COUNT(((TraceEvent0_t*)(pvAddress))->EventID)) * sizeof(uint32_t), TRC_SUCCESS) 643 644 /** 645 * @brief Gets trace event data pointer with an offset. 646 * 647 * This routine gets a trace event data pointer with an offset. It also verfies 648 * that the size so it won't go outside its buffer. 649 * 650 * @param[in] xEventHandle Pointer to initialized trace event. 651 * @param[in] uiOffset Offset. 652 * @param[in] uiSize Size. 653 * @param[out] ppvData Data. 654 * 655 * @retval TRC_FAIL Failure 656 * @retval TRC_SUCCESS Success 657 */ 658 #define xTraceEventGetRawData TRC_EVENT_GET_RAW_DATA 659 660 /** 661 * @brief Gets trace event payload pointer with an offset. 662 * 663 * This routine gets a trace event payload pointer with an offset. It also verifies 664 * that the size so it won't go outside its payload buffer. 665 * 666 * @param[in] xEventHandle Pointer to initialized trace event. 667 * @param[in] uiOffset Offset. 668 * @param[in] uiSize Size. 669 * @param[out] ppvData Data. 670 * 671 * @retval TRC_FAIL Failure 672 * @retval TRC_SUCCESS Success 673 */ 674 #define xTraceEventGetPayload TRC_EVENT_GET_PAYLOAD 675 676 /** 677 * @brief Gets the amount of remaining trace event payload. 678 * 679 * @param[in] xEventHandle Pointer to initialized trace event. 680 * @param[out] puiValue Value. 681 * 682 * @retval TRC_FAIL Failure 683 * @retval TRC_SUCCESS Success 684 */ 685 #define xTraceEventPayloadRemaining TRC_EVENT_PAYLOAD_REMAINING 686 687 /** 688 * @brief Gets the amount of used trace event payload. 689 * 690 * @param[in] xEventHandle Pointer to initialized trace event. 691 * @param[out] puiValue Value 692 * 693 * @retval TRC_FAIL Failure 694 * @retval TRC_SUCCESS Success 695 */ 696 #define xTraceEventPayloadUsed TRC_EVENT_PAYLOAD_USED 697 698 /** 699 * @brief Gets trace event payload size. 700 * 701 * @param[in] xEventHandle Pointer to initialized trace event. 702 * @param[out] puiValue Value 703 * 704 * @retval TRC_FAIL Failure 705 * @retval TRC_SUCCESS Success 706 */ 707 #define xTraceEventPayloadSize TRC_EVENT_PAYLOAD_SIZE 708 709 /* Adds a pointer as event payload with no errors checks */ 710 #define xTraceEventAddPointer TRC_EVENT_ADD_POINTER 711 712 /** 713 * @brief Adds an unsigned base type value as trace event payload 714 * 715 * @param[in] xEventHandle Pointer to initialized trace event. 716 * @param[in] uxValue Value. 717 * 718 * @retval TRC_FAIL Failure 719 * @retval TRC_SUCCESS Success 720 */ 721 #define xTraceEventAddUnsignedBaseType TRC_EVENT_ADD_UNSIGNED_BASE_TYPE 722 723 /** 724 * @brief Adds an uint32_t as trace event payload 725 * 726 * @param[in] xEventHandle Pointer to initialized trace event. 727 * @param[in] value Value. 728 * 729 * @retval TRC_FAIL Failure 730 * @retval TRC_SUCCESS Success 731 */ 732 #define xTraceEventAdd32 TRC_EVENT_ADD_32 733 734 /** 735 * @brief Adds an uint16_t as trace event payload 736 * 737 * @param[in] xEventHandle Pointer to initialized trace event. 738 * @param[in] value Value. 739 * 740 * @retval TRC_FAIL Failure 741 * @retval TRC_SUCCESS Success 742 */ 743 #define xTraceEventAdd16 TRC_EVENT_ADD_16 744 745 /** 746 * @brief Adds an uint8_t as trace event payload. 747 * 748 * @param[in] xEventHandle Pointer to initialized trace event. 749 * @param[in] value Value. 750 * 751 * @retval TRC_FAIL Failure 752 * @retval TRC_SUCCESS Success 753 */ 754 #define xTraceEventAdd8 TRC_EVENT_ADD_8 755 756 #endif /* ((TRC_CFG_USE_TRACE_ASSERT) == 1) */ 757 758 /** @} */ 759 760 #ifdef __cplusplus 761 } 762 #endif 763 764 #endif /* (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING) */ 765 766 #endif /* (TRC_USE_TRACEALYZER_RECORDER == 1) */ 767 768 #endif /* TRC_EVENT_H */ 769
