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 * @internal Public trace multicore event buffer APIs. 13 */ 14 15 #ifndef TRC_MULTI_CORE_EVENT_BUFFER_H 16 #define TRC_MULTI_CORE_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_multi_core_event_buffer_apis Trace Multi-Core Event Buffer APIs 30 * @ingroup trace_recorder_apis 31 * @{ 32 */ 33 34 /** 35 * @brief Trace Multi-Core Event Buffer Structure 36 */ 37 typedef struct TraceMultiCoreEventBuffer /* Aligned */ 38 { 39 TraceEventBuffer_t *xEventBuffer[TRC_CFG_CORE_COUNT]; /**< */ 40 } TraceMultiCoreEventBuffer_t; 41 42 /** 43 * @internal Initialize multi-core event buffer. 44 * 45 * This routine initializes a multi-core trace event buffer and assignts it 46 * a memory area based on the supplied buffer. 47 * 48 * Trace event buffer options specifies the buffer behavior regarding 49 * old data, the alternatives are TRC_EVENT_BUFFER_OPTION_SKIP and 50 * TRC_EVENT_BUFFER_OPTION_OVERWRITE (mutal exclusive). 51 * 52 * @param[out] pxTraceMultiCoreEventBuffer Pointer to unitialized multi-core trace event buffer. 53 * @param[in] uiOptions Trace event buffer options. 54 * @param[in] puiBuffer Pointer to buffer that will be used by the multi-core trace event buffer. 55 * @param[in] uiSize Size of buffer. 56 * 57 * @retval TRC_FAIL Failure 58 * @retval TRC_SUCCESS Success 59 */ 60 traceResult xTraceMultiCoreEventBufferInitialize(TraceMultiCoreEventBuffer_t* const pxTraceMultiCoreEventBuffer, uint32_t uiOptions, 61 uint8_t* puiBuffer, uint32_t uiSize); 62 63 64 65 #if ((TRC_CFG_USE_TRACE_ASSERT) == 1) 66 /** 67 * @brief Allocates a data slot directly from the event buffer. 68 * 69 * @param[in] pxTraceMultiCoreEventBuffer Pointer to initialized multi-core trace event buffer. 70 * @param[in] uiSize Allocation size 71 * @param[out] ppvData Pointer that will hold the area from the buffer. 72 * 73 * @retval TRC_FAIL Failure 74 * @retval TRC_SUCCESS Success 75 */ 76 traceResult xTraceMultiCoreEventBufferAlloc(const TraceMultiCoreEventBuffer_t * const pxTraceMultiCoreEventBuffer, uint32_t uiSize, void** ppvData); 77 78 /** 79 * @brief Commits the last allocated block to the event buffer. 80 * 81 * @param[in] pxTraceMultiCoreEventBuffer Pointer to initialized multi-core trace event buffer. 82 * @param[in] pvData Data pointer. 83 * @param[in] uiSize Data size. 84 * @param piBytesWritten The number of bytes that was written. 85 * 86 * @retval TRC_FAIL Failure 87 * @retval TRC_SUCCESS Success 88 */ 89 traceResult xTraceMultiCoreEventBufferAllocCommit(const TraceMultiCoreEventBuffer_t * const pxTraceMultiCoreEventBuffer, void *pvData, uint32_t uiSize, int32_t *piBytesWritten); 90 91 /** 92 * @brief Pushes data into multi-core trace event buffer. 93 * 94 * This routine attempts to push data into the multi-core trace event buffer. Selection 95 * of which core the data is pushed for is managed automatically through the 96 * TRC_CFG_GET_CURRENT_CORE macro which is defined on an RTOS basis. 97 * 98 * @param[in] pxTraceMultiCoreEventBuffer Pointer to initialized multi-core event buffer. 99 * @param[in] pvData Pointer to data should be pushed into multi-core event buffer. 100 * @param[in] uiSize Size of data that should be pushed into multi-core trace event buffer. 101 * @param[out] piBytesWritten Pointer to variable which the routine will write the number 102 * of bytes that was pushed into the multi-core trace event buffer. 103 * 104 * @retval TRC_FAIL Failure 105 * @retval TRC_SUCCESS Success 106 */ 107 traceResult xTraceMultiCoreEventBufferPush(const TraceMultiCoreEventBuffer_t* const pxTraceMultiCoreEventBuffer, void* pvData, uint32_t uiSize, int32_t* piBytesWritten); 108 109 #else 110 111 /** 112 * @brief Allocates a data slot directly from the event buffer. 113 * 114 * @param[in] pxTraceEventBuffer Pointer to initialized multi-core trace event buffer. 115 * @param[in] uiSize Allocation size 116 * @param[out] ppvData Pointer that will hold the area from the buffer. 117 * 118 * @retval TRC_FAIL Failure 119 * @retval TRC_SUCCESS Success 120 */ 121 #define xTraceMultiCoreEventBufferAlloc(pxTraceMultiCoreEventBuffer, uiSize, ppvData) xTraceEventBufferAlloc((pxTraceMultiCoreEventBuffer)->xEventBuffer[TRC_CFG_GET_CURRENT_CORE()], uiSize, ppvData) 122 123 /** 124 * @brief Commits the last allocated block to the event buffer. 125 * 126 * @param[in] pxTraceEventBuffer Pointer to initialized multi-core trace event buffer. 127 * 128 * @retval TRC_FAIL Failure 129 * @retval TRC_SUCCESS Success 130 */ 131 #define xTraceMultiCoreEventBufferAllocCommit(pxTraceMultiCoreEventBuffer, pvData, uiSize, piBytesWritten) xTraceEventBufferAllocCommit((pxTraceMultiCoreEventBuffer)->xEventBuffer[TRC_CFG_GET_CURRENT_CORE()], pvData, uiSize, piBytesWritten) 132 133 /** 134 * @brief Pushes data into multi-core trace event buffer. 135 * 136 * This routine attempts to push data into the multi-core trace event buffer. Selection 137 * of which core the data is pushed for is managed automatically through the 138 * TRC_CFG_GET_CURRENT_CORE macro which is defined on an RTOS basis. 139 * 140 * @param[in] pxTraceMultiCoreEventBuffer Pointer to initialized multi-core event buffer. 141 * @param[in] pvData Pointer to data should be pushed into multi-core event buffer. 142 * @param[in] uiSize Size of data that should be pushed into multi-core trace event buffer. 143 * @param[out] piBytesWritten Pointer to variable which the routine will write the number 144 * of bytes that was pushed into the multi-core trace event buffer. 145 * 146 * @retval TRC_FAIL Failure 147 * @retval TRC_SUCCESS Success 148 */ 149 #define xTraceMultiCoreEventBufferPush(pxTraceMultiCoreEventBuffer, pvData, uiSize, piBytesWritten) xTraceEventBufferPush((pxTraceMultiCoreEventBuffer)->xEventBuffer[TRC_CFG_GET_CURRENT_CORE()], pvData, uiSize, piBytesWritten) 150 151 #endif 152 153 /** 154 * @brief Transfer multi-core trace event buffer data through streamport. 155 * 156 * This routine will attempt to transfer all existing data in the multi-core trace event 157 * buffer through the streamport. New data pushed to the trace event buffer 158 * during the execution of this routine will not be transfered to 159 * 160 * @param[in] pxTraceMultiCoreEventBuffer Pointer to initialized multi-core event buffer. 161 * @param[out] piBytesWritten Pointer to variable which the routine will write the number 162 * of bytes that was pushed into the multi-core trace event buffer. 163 * 164 * @retval TRC_FAIL Failure 165 * @retval TRC_SUCCESS Success 166 */ 167 traceResult xTraceMultiCoreEventBufferTransferAll(const TraceMultiCoreEventBuffer_t* const pxTraceMultiCoreEventBuffer, int32_t* piBytesWritten); 168 169 /** 170 * @brief Transfer multi-core trace event buffer data through streamport. 171 * 172 * This routine will attempt to transfer a chunk of stored event data in the multi-core 173 * trace event buffer. Note that the chunk size is on a per-core basis with each core 174 * event buffer attempting to push up to uiChunkSize of bytes. 175 * 176 * @param[in] pxTraceMultiCoreEventBuffer Pointer to initialized multi-core event buffer. 177 * @param[in] uiChunkSize Number of bytes to attempt to transfer per core. 178 * @param[out] piBytesWritten Pointer to variable which the routine will write the number 179 * of bytes that was pushed into the multi-core trace event buffer. 180 */ 181 traceResult xTraceMultiCoreEventBufferTransferChunk(const TraceMultiCoreEventBuffer_t* const pxTraceMultiCoreEventBuffer, uint32_t uiChunkSize, int32_t* piBytesWritten); 182 183 /** 184 * @brief Clears all data from event buffer. 185 * 186 * @param[in] pxTraceMultiCoreEventBuffer Pointer to initialized multi-core trace event buffer. 187 * 188 * @retval TRC_FAIL Failure 189 * @retval TRC_SUCCESS Success 190 */ 191 traceResult xTraceMultiCoreEventBufferClear(const TraceMultiCoreEventBuffer_t* const pxTraceMultiCoreEventBuffer); 192 193 /** @} */ 194 195 #ifdef __cplusplus 196 } 197 #endif 198 199 #endif /* (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING) */ 200 201 #endif /* (TRC_USE_TRACEALYZER_RECORDER == 1) */ 202 203 #endif /* TRC_MULTI_CORE_EVENT_BUFFER_H */ 204
