1 /* 2 * Percepio Trace Recorder for Tracealyzer v4.6.6 3 * Copyright 2021 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 buffer APIs. 13 */ 14 15 #ifndef TRC_EVENT_BUFFER_H 16 #define TRC_EVENT_BUFFER_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_buffer_apis Trace Event Buffer APIs 30 * @ingroup trace_recorder_apis 31 * @{ 32 */ 33 34 /** 35 * @def TRC_EVENT_BUFFER_OPTION_SKIP 36 * @brief Buffer should skip new events when full 37 */ 38 #define TRC_EVENT_BUFFER_OPTION_SKIP (0U) 39 40 /** 41 * @def TRC_EVENT_BUFFER_OPTION_OVERWRITE 42 * @brief Buffer should overwrite old events when full 43 */ 44 #define TRC_EVENT_BUFFER_OPTION_OVERWRITE (1U) 45 46 /** 47 * @brief Trace Event Buffer Structure 48 */ 49 typedef struct TraceEventBuffer 50 { 51 uint32_t uiHead; /**< Head index of buffer */ 52 uint32_t uiTail; /**< Tail index of buffer */ 53 uint32_t uiSize; /**< Buffer size */ 54 uint32_t uiOptions; /**< Options (skip/overwrite when full) */ 55 uint32_t uiDroppedEvents; /**< Nr of dropped events */ 56 uint32_t uiFree; /**< Nr of free bytes */ 57 uint32_t uiTimerWraparounds; /**< Nr of timer wraparounds */ 58 uint8_t* puiBuffer; /**< Trace Event Buffer: may be NULL */ 59 } TraceEventBuffer_t; 60 61 /** 62 * @internal Initialize trace event buffer. 63 * 64 * This routine initializes a trace event buffer and assigns it a 65 * memory area based on the supplied buffer. 66 * 67 * Trace event buffer options specifies the buffer behavior regarding 68 * old data, the alternatives are TRC_EVENT_BUFFER_OPTION_SKIP and 69 * TRC_EVENT_BUFFER_OPTION_OVERWRITE (mutal exclusive). 70 * 71 * @param[out] pxTraceEventBuffer Pointer to uninitialized trace event buffer. 72 * @param[in] uiOptions Trace event buffer options. 73 * @param[in] puiBuffer Pointer to buffer that will be used by the trace event buffer. 74 * @param[in] uiSize Size of buffer 75 * 76 * @retval TRC_FAIL Failure 77 * @retval TRC_SUCCESS Success 78 */ 79 traceResult xTraceEventBufferInitialize(TraceEventBuffer_t * pxTraceEventBuffer, uint32_t uiOptions, 80 uint8_t *puiBuffer, uint32_t uiSize); 81 82 /** 83 * @brief Pushes data into trace event buffer. 84 * 85 * This routine attempts to push data into the trace event buffer. 86 * 87 * @param[in] pxTraceEventBuffer Pointer to initialized trace event buffer. 88 * @param[in] pxData Pointer to data that should be pushed into trace event buffer. 89 * @param[in] uiSize Size of data. 90 * @param[out] piBytesWritten Bytes written. 91 * 92 * @retval TRC_FAIL Failure 93 * @retval TRC_SUCCESS Success 94 */ 95 traceResult xTraceEventBufferPush(TraceEventBuffer_t *pxTraceEventBuffer, void *pxData, uint32_t uiSize, int32_t *piBytesWritten); 96 97 /** 98 * @brief Transfer trace event buffer data through streamport. 99 * 100 * This routine will attempt to transfer all existing data in the trace event 101 * buffer through the streamport. New data pushed to the trace event buffer 102 * during the execution of this routine will not be transfered to 103 * 104 * @param[in] pxTraceEventBuffer Pointer to initialized trace event buffer. 105 * @param[out] piBytesWritten Bytes written. 106 * 107 * @retval TRC_FAIL Failure 108 * @retval TRC_SUCCESS Success 109 */ 110 traceResult xTraceEventBufferTransfer(TraceEventBuffer_t* pxTraceEventBuffer, int32_t* piBytesWritten); 111 112 /** 113 * @brief Clears all data from event buffer. 114 * 115 * @param[in] pxTraceEventBuffer Pointer to initialized trace event buffer. 116 * 117 * @retval TRC_FAIL Failure 118 * @retval TRC_SUCCESS Success 119 */ 120 traceResult xTraceEventBufferClear(TraceEventBuffer_t* pxTraceEventBuffer); 121 122 /** @} */ 123 124 #ifdef __cplusplus 125 } 126 #endif 127 128 #endif /* (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING) */ 129 130 #endif /* (TRC_USE_TRACEALYZER_RECORDER == 1) */ 131 132 #endif /* TRC_EVENT_BUFFER_H */ 133
