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 buffer APIs. 13 */ 14 15 #ifndef TRC_EVENT_BUFFER_H 16 #define TRC_EVENT_BUFFER_H 17 18 #if (TRC_USE_TRACEALYZER_RECORDER == 1) && (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING) 19 20 #include <trcTypes.h> 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 /** 27 * @defgroup trace_event_buffer_apis Trace Event Buffer APIs 28 * @ingroup trace_recorder_apis 29 * @{ 30 */ 31 32 /** 33 * @def TRC_EVENT_BUFFER_OPTION_SKIP 34 * @brief Buffer should skip new events when full 35 */ 36 #define TRC_EVENT_BUFFER_OPTION_SKIP (0U) 37 38 /** 39 * @def TRC_EVENT_BUFFER_OPTION_OVERWRITE 40 * @brief Buffer should overwrite old events when full 41 */ 42 #define TRC_EVENT_BUFFER_OPTION_OVERWRITE (1U) 43 44 /** 45 * @brief Trace Event Buffer Structure 46 */ 47 typedef struct TraceEventBuffer /* Aligned */ 48 { 49 uint32_t uiHead; /**< Head index of buffer */ 50 uint32_t uiTail; /**< Tail index of buffer */ 51 uint32_t uiSize; /**< Buffer size */ 52 uint32_t uiOptions; /**< Options (skip/overwrite when full) */ 53 uint32_t uiDroppedEvents; /**< Nr of dropped events */ 54 uint32_t uiFree; /**< Nr of free bytes */ 55 uint32_t uiSlack; /**< */ 56 uint32_t uiNextHead; /**< */ 57 uint32_t uiTimerWraparounds; /**< Nr of timer wraparounds */ 58 uint32_t uiReserved; /**< Reserved */ 59 uint8_t* puiBuffer; /**< Trace Event Buffer: may be NULL */ 60 } TraceEventBuffer_t; 61 62 /** 63 * @internal Initialize trace event buffer. 64 * 65 * This routine initializes a trace event buffer and assigns it a 66 * memory area based on the supplied buffer. 67 * 68 * Trace event buffer options specifies the buffer behavior regarding 69 * old data, the alternatives are TRC_EVENT_BUFFER_OPTION_SKIP and 70 * TRC_EVENT_BUFFER_OPTION_OVERWRITE (mutual exclusive). 71 * 72 * @param[out] pxTraceEventBuffer Pointer to uninitialized trace event buffer. 73 * @param[in] uiOptions Trace event buffer options. 74 * @param[in] puiBuffer Pointer to buffer that will be used by the trace event buffer. 75 * @param[in] uiSize Size of buffer 76 * 77 * @retval TRC_FAIL Failure 78 * @retval TRC_SUCCESS Success 79 */ 80 traceResult xTraceEventBufferInitialize(TraceEventBuffer_t *pxTraceEventBuffer, uint32_t uiOptions, 81 uint8_t *puiBuffer, uint32_t uiSize); 82 83 /** 84 * @brief Allocates a data slot directly from the event buffer. 85 * 86 * @param[in] pxTraceEventBuffer Pointer to initialized trace event buffer. 87 * @param[in] uiSize Allocation size 88 * @param[out] ppvData Pointer that will hold the area from the buffer. 89 * 90 * @retval TRC_FAIL Failure 91 * @retval TRC_SUCCESS Success 92 */ 93 traceResult xTraceEventBufferAlloc(TraceEventBuffer_t *pxTraceEventBuffer, uint32_t uiSize, void **ppvData); 94 95 /** 96 * @brief Commits the last allocated block to the event buffer. 97 * 98 * @param[in] pxTraceEventBuffer Pointer to initialized trace event buffer. 99 * 100 * @retval TRC_FAIL Failure 101 * @retval TRC_SUCCESS Success 102 */ 103 traceResult xTraceEventBufferAllocCommit(TraceEventBuffer_t *pxTraceEventBuffer, const void *pvData, uint32_t uiSize, int32_t *piBytesWritten); 104 105 /** 106 * @brief Pushes data into trace event buffer. 107 * 108 * This routine attempts to push data into the trace event buffer. 109 * 110 * @param[in] pxTraceEventBuffer Pointer to initialized trace event buffer. 111 * @param[in] pvData Pointer to data that should be pushed into trace event buffer. 112 * @param[in] uiSize Size of data. 113 * @param[out] piBytesWritten Bytes written. 114 * 115 * @retval TRC_FAIL Failure 116 * @retval TRC_SUCCESS Success 117 */ 118 traceResult xTraceEventBufferPush(TraceEventBuffer_t *pxTraceEventBuffer, void *pvData, uint32_t uiSize, int32_t *piBytesWritten); 119 120 /** 121 * @brief Transfer trace event buffer data through streamport. 122 * 123 * This routine will attempt to transfer all existing data in the trace event 124 * buffer through the streamport. New data pushed to the trace event buffer 125 * during the execution of this routine will not be transferred 126 * 127 * @param[in] pxTraceEventBuffer Pointer to initialized trace event buffer. 128 * @param[out] piBytesWritten Bytes written. 129 * 130 * @retval TRC_FAIL Failure 131 * @retval TRC_SUCCESS Success 132 */ 133 traceResult xTraceEventBufferTransferAll(TraceEventBuffer_t* pxTraceEventBuffer, int32_t* piBytesWritten); 134 135 /** 136 * @brief Transfer trace event buffer data through streamport. 137 * 138 * This routine will attempt to transfer a chunk of existing data in the trace 139 * event buffer through the streamport. New data pushed to the trace event buffer 140 * during the execution of this routine will not be transfered. 141 * 142 * When transferring a chunk which wraps the buffer, a singular transfer 143 * is made to avoid issuing dual writes. This configuration means that 144 * during wrapping, the chunk might be reduced in size even if there is 145 * more data at the start of the buffer. To transfer more data check 146 * piBytesWritten and issue multiple transfers if required. 147 * 148 * @param[in] pxTraceEventBuffer Pointer to initialized trace event buffer. 149 * @param[out] piBytesWritten Bytes written. 150 * @param[in] uiChunkSize Maximum transfer chunk in bytes. 151 * 152 * @retval TRC_FAIL Failure 153 * @retval TRC_SUCCESS Success 154 */ 155 traceResult xTraceEventBufferTransferChunk(TraceEventBuffer_t* pxTraceEventBuffer, uint32_t uiChunkSize, int32_t* piBytesWritten); 156 157 158 /** 159 * @brief Clears all data from event buffer. 160 * 161 * @param[in] pxTraceEventBuffer Pointer to initialized trace event buffer. 162 * 163 * @retval TRC_FAIL Failure 164 * @retval TRC_SUCCESS Success 165 */ 166 traceResult xTraceEventBufferClear(TraceEventBuffer_t* pxTraceEventBuffer); 167 168 /** @} */ 169 170 #ifdef __cplusplus 171 } 172 #endif 173 174 #endif 175 176 #endif 177
