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 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 /* Aligned */ 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 uiSlack; /**< */ 58 uint32_t uiNextHead; /**< */ 59 uint32_t uiTimerWraparounds; /**< Nr of timer wraparounds */ 60 uint32_t uiReserved; /**< Reserved */ 61 uint8_t* puiBuffer; /**< Trace Event Buffer: may be NULL */ 62 } TraceEventBuffer_t; 63 64 /** 65 * @internal Initialize trace event buffer. 66 * 67 * This routine initializes a trace event buffer and assigns it a 68 * memory area based on the supplied buffer. 69 * 70 * Trace event buffer options specifies the buffer behavior regarding 71 * old data, the alternatives are TRC_EVENT_BUFFER_OPTION_SKIP and 72 * TRC_EVENT_BUFFER_OPTION_OVERWRITE (mutual exclusive). 73 * 74 * @param[out] pxTraceEventBuffer Pointer to uninitialized trace event buffer. 75 * @param[in] uiOptions Trace event buffer options. 76 * @param[in] puiBuffer Pointer to buffer that will be used by the trace event buffer. 77 * @param[in] uiSize Size of buffer 78 * 79 * @retval TRC_FAIL Failure 80 * @retval TRC_SUCCESS Success 81 */ 82 traceResult xTraceEventBufferInitialize(TraceEventBuffer_t *pxTraceEventBuffer, uint32_t uiOptions, 83 uint8_t *puiBuffer, uint32_t uiSize); 84 85 /** 86 * @brief Allocates a data slot directly from the event buffer. 87 * 88 * @param[in] pxTraceEventBuffer Pointer to initialized trace event buffer. 89 * @param[in] uiSize Allocation size 90 * @param[out] ppvData Pointer that will hold the area from the buffer. 91 * 92 * @retval TRC_FAIL Failure 93 * @retval TRC_SUCCESS Success 94 */ 95 traceResult xTraceEventBufferAlloc(TraceEventBuffer_t *pxTraceEventBuffer, uint32_t uiSize, void **ppvData); 96 97 /** 98 * @brief Commits the last allocated block to the event buffer. 99 * 100 * @param[in] pxTraceEventBuffer Pointer to initialized trace event buffer. 101 * 102 * @retval TRC_FAIL Failure 103 * @retval TRC_SUCCESS Success 104 */ 105 traceResult xTraceEventBufferAllocCommit(TraceEventBuffer_t *pxTraceEventBuffer, const void *pvData, uint32_t uiSize, int32_t *piBytesWritten); 106 107 /** 108 * @brief Pushes data into trace event buffer. 109 * 110 * This routine attempts to push data into the trace event buffer. 111 * 112 * @param[in] pxTraceEventBuffer Pointer to initialized trace event buffer. 113 * @param[in] pvData Pointer to data that should be pushed into trace event buffer. 114 * @param[in] uiSize Size of data. 115 * @param[out] piBytesWritten Bytes written. 116 * 117 * @retval TRC_FAIL Failure 118 * @retval TRC_SUCCESS Success 119 */ 120 traceResult xTraceEventBufferPush(TraceEventBuffer_t *pxTraceEventBuffer, void *pvData, uint32_t uiSize, int32_t *piBytesWritten); 121 122 /** 123 * @brief Transfer trace event buffer data through streamport. 124 * 125 * This routine will attempt to transfer all existing data in the trace event 126 * buffer through the streamport. New data pushed to the trace event buffer 127 * during the execution of this routine will not be transferred 128 * 129 * @param[in] pxTraceEventBuffer Pointer to initialized trace event buffer. 130 * @param[out] piBytesWritten Bytes written. 131 * 132 * @retval TRC_FAIL Failure 133 * @retval TRC_SUCCESS Success 134 */ 135 traceResult xTraceEventBufferTransferAll(TraceEventBuffer_t* pxTraceEventBuffer, int32_t* piBytesWritten); 136 137 /** 138 * @brief Transfer trace event buffer data through streamport. 139 * 140 * This routine will attempt to transfer a chunk of existing data in the trace 141 * event buffer through the streamport. New data pushed to the trace event buffer 142 * during the execution of this routine will not be transfered. 143 * 144 * When transferring a chunk which wraps the buffer, a singular transfer 145 * is made to avoid issuing dual writes. This configuration means that 146 * during wrapping, the chunk might be reduced in size even if there is 147 * more data at the start of the buffer. To transfer more data check 148 * piBytesWritten and issue multiple transfers if required. 149 * 150 * @param[in] pxTraceEventBuffer Pointer to initialized trace event buffer. 151 * @param[out] piBytesWritten Bytes written. 152 * @param[in] uiChunkSize Maximum transfer chunk in bytes. 153 * 154 * @retval TRC_FAIL Failure 155 * @retval TRC_SUCCESS Success 156 */ 157 traceResult xTraceEventBufferTransferChunk(TraceEventBuffer_t* pxTraceEventBuffer, uint32_t uiChunkSize, int32_t* piBytesWritten); 158 159 160 /** 161 * @brief Clears all data from event buffer. 162 * 163 * @param[in] pxTraceEventBuffer Pointer to initialized trace event buffer. 164 * 165 * @retval TRC_FAIL Failure 166 * @retval TRC_SUCCESS Success 167 */ 168 traceResult xTraceEventBufferClear(TraceEventBuffer_t* pxTraceEventBuffer); 169 170 /** @} */ 171 172 #ifdef __cplusplus 173 } 174 #endif 175 176 #endif /* (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING) */ 177 178 #endif /* (TRC_USE_TRACEALYZER_RECORDER == 1) */ 179 180 #endif /* TRC_EVENT_BUFFER_H */ 181
