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 internal event buffer APIs. 13 */ 14 15 #ifndef TRC_INTERNAL_BUFFER_H 16 #define TRC_INTERNAL_BUFFER_H 17 18 #if (TRC_USE_TRACEALYZER_RECORDER == 1) 19 20 #include <trcDefines.h> 21 22 #if (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING) 23 24 #ifndef TRC_USE_INTERNAL_BUFFER 25 #define TRC_USE_INTERNAL_BUFFER 1 26 #endif 27 28 #ifndef TRC_INTERNAL_EVENT_BUFFER_WRITE_MODE 29 #define TRC_INTERNAL_EVENT_BUFFER_WRITE_MODE TRC_INTERNAL_EVENT_BUFFER_OPTION_WRITE_MODE_DIRECT 30 #endif 31 32 #ifndef TRC_INTERNAL_EVENT_BUFFER_TRANSFER_MODE 33 #define TRC_INTERNAL_EVENT_BUFFER_TRANSFER_MODE TRC_INTERNAL_EVENT_BUFFER_OPTION_TRANSFER_MODE_ALL 34 #endif 35 36 #ifndef TRC_INTERNAL_BUFFER_CHUNK_SIZE 37 #define TRC_INTERNAL_BUFFER_CHUNK_SIZE 1024UL 38 #endif 39 40 #ifndef TRC_INTERNAL_BUFFER_PAGE_SIZE 41 #define TRC_INTERNAL_BUFFER_PAGE_SIZE 1024UL 42 #endif 43 44 #ifndef TRC_INTERNAL_BUFFER_CHUNK_TRANSFER_AGAIN_SIZE_LIMIT 45 #define TRC_INTERNAL_BUFFER_CHUNK_TRANSFER_AGAIN_SIZE_LIMIT (TRC_INTERNAL_BUFFER_PAGE_SIZE / 2UL) 46 #endif 47 48 #ifndef TRC_INTERNAL_BUFFER_CHUNK_TRANSFER_AGAIN_COUNT_LIMIT 49 #define TRC_INTERNAL_BUFFER_CHUNK_TRANSFER_AGAIN_COUNT_LIMIT (5UL) 50 #endif 51 52 #if (TRC_USE_INTERNAL_BUFFER == 1) 53 54 #include <trcTypes.h> 55 56 #ifdef __cplusplus 57 extern "C" { 58 #endif 59 60 /** 61 * @defgroup trace_internal_event_buffer_apis Trace Internal Event Buffer APIs 62 * @ingroup trace_recorder_apis 63 * @{ 64 */ 65 66 /** 67 * @internal Initializes the internal trace event buffer used by certain stream ports. 68 * 69 * @param[in] puiBuffer Pointer to previously allocated memory buffer 70 * @param[in] uiSize Size of buffer 71 * 72 * @retval TRC_FAIL Failure 73 * @retval TRC_SUCCESS Success 74 */ 75 traceResult xTraceInternalEventBufferInitialize(uint8_t* puiBuffer, uint32_t uiSize); 76 77 /** 78 * @brief Allocates a data slot directly from the internal event buffer. 79 * 80 * @param[in] uiSize Allocation size 81 * @param[out] ppvData Pointer that will hold the area from the buffer. 82 * 83 * @retval TRC_FAIL Failure 84 * @retval TRC_SUCCESS Success 85 */ 86 traceResult xTraceInternalEventBufferAlloc(uint32_t uiSize, void **ppvData); 87 88 /** 89 * @brief Commits the last allocated block to the internal event buffer. 90 * 91 * For the sake of conformity this function accepts the same arguments as 92 * xTraceInternalEventBufferPush. These arguments are not used in the 93 * traditional sense since the alloc already managed these parts. This 94 * function simply marks the allocate stage as complete and ready 95 * for transfer. 96 * 97 * @param[in] pvData Pointer to data 98 * @param[in] uiSize Size of data 99 * @param[out] piBytesWritten Bytes written. 100 * 101 * @retval TRC_FAIL Failure 102 * @retval TRC_SUCCESS Success 103 */ 104 traceResult xTraceInternalEventBufferAllocCommit(void *pvData, uint32_t uiSize, int32_t *piBytesWritten); 105 106 /** 107 * @brief Pushes data to the internal trace event buffer. 108 * 109 * @param[in] pvData Pointer to data 110 * @param[in] uiSize Size of data 111 * @param[out] piBytesWritten Bytes written. 112 * 113 * @retval TRC_FAIL Failure 114 * @retval TRC_SUCCESS Success 115 */ 116 traceResult xTraceInternalEventBufferPush(void *pvData, uint32_t uiSize, int32_t *piBytesWritten); 117 118 #if (TRC_INTERNAL_EVENT_BUFFER_TRANSFER_MODE == TRC_INTERNAL_EVENT_BUFFER_OPTION_TRANSFER_MODE_ALL) 119 #define xTraceInternalEventBufferTransfer xTraceInternalEventBufferTransferAll 120 #else 121 #define xTraceInternalEventBufferTransfer xTraceInternalEventBufferTransferChunk 122 #endif 123 124 /** 125 * @brief Transfers all internal trace event buffer data using the function 126 * xTraceStreamPortWriteData(...) as defined in trcStreamPort.h. 127 * 128 * This function is intended to be called by the periodic TzCtrl task with a 129 * suitable delay (e.g. 10-100 ms). 130 * 131 * In case of errors from the streaming interface, it registers a warning 132 * (TRC_WARNING_STREAM_PORT_WRITE) provided by xTraceErrorGetLast(). 133 * 134 * @retval TRC_FAIL Failure 135 * @retval TRC_SUCCESS Success 136 */ 137 traceResult xTraceInternalEventBufferTransferAll(void); 138 139 /** 140 * @brief Transfer internal trace event buffer data through streamport. 141 * 142 * This routine will attempt to transfer a chunk of existing data in the trace 143 * event buffer through the streamport. New data pushed to the trace event buffer 144 * during the execution of this routine will not be transfered. 145 * 146 * When transferring a chunk which wraps the buffer, a singular transfer 147 * is made to avoid issuing dual writes. This configuration means that 148 * during wrapping, the chunk might be reduced in size even if there is 149 * more data at the start of the buffer. To transfer more data check 150 * piBytesWritten and issue multiple transfers if required. 151 * 152 * @retval TRC_FAIL Failure 153 * @retval TRC_SUCCESS Success 154 */ 155 traceResult xTraceInternalEventBufferTransferChunk(void); 156 157 /** 158 * @brief Clears all trace events in the internal trace event buffer. 159 * 160 * @retval TRC_FAIL Failure 161 * @retval TRC_SUCCESS Success 162 */ 163 traceResult xTraceInternalEventBufferClear(void); 164 165 /** @} */ 166 167 #ifdef __cplusplus 168 } 169 #endif 170 171 #else /* (TRC_USE_INTERNAL_BUFFER == 1)*/ 172 173 #define xTraceInternalEventBufferInitialize(puiBuffer, uiSize) ((void)(uiSize), (puiBuffer) != 0 ? TRC_SUCCESS : TRC_FAIL) 174 #define xTraceInternalEventBufferAlloc(ppvData, uiSize) ((void)(uiSize), (ppvData) != 0 ? TRC_SUCCESS : TRC_FAIL) 175 #define xTraceInternalEventBufferAllocCommit(pvData, uiSize, piBytesWritten) ((void)(pvData), (void)(uiSize), (void)(piBytesWritten), TRC_SUCCESS) 176 #define xTraceInternalEventBufferPush(pvData, uiSize, piBytesWritten) ((void)(uiSize), (void)(piBytesWritten), (pvData) != 0 ? TRC_SUCCESS : TRC_FAIL) 177 #define xTraceInternalEventBufferTransfer() (void)(TRC_SUCCESS) 178 #define xTraceInternalEventBufferTransferChunk(piBytesWritten, uiChunkSize) ((void)(piBytesWritten), (void)(uiChunkSize), TRC_SUCCESS) 179 #define xTraceInternalEventBufferClear() (void)(TRC_SUCCESS) 180 181 #endif /* (TRC_USE_INTERNAL_BUFFER == 1)*/ 182 183 #endif /* (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING) */ 184 185 #endif /* (TRC_USE_TRACEALYZER_RECORDER == 1) */ 186 187 #endif /* TRC_INTERNAL_BUFFER_H */ 188
