1 /* 2 * 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 * The interface definitions for trace streaming ("stream ports"). 9 * This "stream port" sets up the recorder to stream to a Ring Buffer. 10 */ 11 12 #ifndef TRC_STREAM_PORT_H 13 #define TRC_STREAM_PORT_H 14 15 #if (TRC_USE_TRACEALYZER_RECORDER == 1) 16 17 #if (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING) 18 19 #include <trcTypes.h> 20 #include <trcStreamPortConfig.h> 21 #include <trcRecorder.h> 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 /** 28 * @def TRC_EXTERNAL_BUFFERS 29 * 30 * @brief This Stream Port houses the EntryTable and Timestamp buffers 31 */ 32 #define TRC_EXTERNAL_BUFFERS 1 33 34 /** 35 * @def TRC_SEND_NAME_ONLY_ON_DELETE 36 * 37 * @brief This Stream Port requires additional information to be sent when objects are deleted 38 */ 39 #define TRC_SEND_NAME_ONLY_ON_DELETE 1 40 41 /** 42 * @def TRC_USE_INTERNAL_BUFFER 43 * 44 * @brief This Stream Port uses the Multi Core Buffer directly. 45 */ 46 47 #define TRC_USE_INTERNAL_BUFFER 0 48 49 #define TRC_STREAM_PORT_BUFFER_SIZE (((uint32_t)(TRC_CFG_STREAM_PORT_BUFFER_SIZE) / sizeof(TraceUnsignedBaseType_t)) * sizeof(TraceUnsignedBaseType_t)) /* aligned */ 50 51 /** 52 * @brief 53 */ 54 typedef struct TraceMultiCoreBuffer /* Aligned */ 55 { 56 TraceUnsignedBaseType_t uxSize; /* aligned */ 57 uint8_t uiBuffer[TRC_STREAM_PORT_BUFFER_SIZE]; /* size is aligned */ 58 } TraceMultiCoreBuffer_t; 59 60 /** 61 * @brief 62 */ 63 typedef struct TraceRingBuffer 64 { 65 uint32_t reserved0; /* alignment with START_MARKERS */ 66 volatile uint8_t START_MARKERS[12]; 67 TraceHeaderBuffer_t xHeaderBuffer; /* aligned */ 68 TraceTimestampData_t xTimestampInfo; /* aligned */ 69 TraceEntryTable_t xEntryTable; /* aligned */ 70 TraceMultiCoreBuffer_t xEventBuffer; /* aligned */ 71 volatile uint8_t END_MARKERS[12]; 72 uint32_t reserved1; /* alignment */ 73 } TraceRingBuffer_t; 74 75 /** 76 * @brief 77 */ 78 typedef struct TraceStreamPortData 79 { 80 TraceMultiCoreEventBuffer_t xMultiCoreEventBuffer; 81 TraceRingBuffer_t xRingBuffer; 82 } TraceStreamPortData_t; 83 84 extern TraceStreamPortData_t* pxStreamPortData; 85 86 /** 87 * @def TRC_STREAM_PORT_BUFFER_SIZE 88 * @brief The buffer size, aligned to base type. 89 */ 90 #define TRC_STREAM_PORT_DATA_BUFFER_SIZE (sizeof(TraceStreamPortData_t)) 91 92 /** 93 * @brief A structure representing the trace stream port buffer. 94 */ 95 typedef struct TraceStreamPortBuffer 96 { 97 uint8_t buffer[(TRC_STREAM_PORT_DATA_BUFFER_SIZE)]; 98 } TraceStreamPortBuffer_t; 99 100 /** 101 * @internal Stream port initialize callback. 102 * 103 * This function is called by the recorder as part of its initialization phase. 104 * 105 * @param[in] pxBuffer Buffer 106 * 107 * @retval TRC_FAIL Initialization failed 108 * @retval TRC_SUCCESS Success 109 */ 110 traceResult xTraceStreamPortInitialize(TraceStreamPortBuffer_t* pxBuffer); 111 112 /** 113 * @brief Allocates data from the stream port. 114 * 115 * @param[in] uiSize Allocation size 116 * @param[out] ppvData Allocation data pointer 117 * 118 * @retval TRC_FAIL Allocate failed 119 * @retval TRC_SUCCESS Success 120 */ 121 #define xTraceStreamPortAllocate(_uiSize, _ppvData) xTraceMultiCoreEventBufferAlloc(&pxStreamPortData->xMultiCoreEventBuffer, _uiSize, _ppvData) 122 123 /** 124 * @brief Commits data to the stream port, depending on the implementation/configuration of the 125 * stream port this data might be directly written to the stream port interface, buffered, or 126 * something else. 127 * 128 * @param[in] pvData Data to commit 129 * @param[in] uiSize Data to commit size 130 * @param[out] piBytesCommitted Bytes commited 131 * 132 * @retval TRC_FAIL Commit failed 133 * @retval TRC_SUCCESS Success 134 */ 135 #define xTraceStreamPortCommit(_pvData, _uiSize, _piBytesCommitted) xTraceMultiCoreEventBufferAllocCommit(&pxStreamPortData->xMultiCoreEventBuffer, _pvData, _uiSize, _piBytesCommitted) 136 137 /** 138 * @brief Writes data through the stream port interface. 139 * 140 * @param[in] pvData Data to write 141 * @param[in] uiSize Data to write size 142 * @param[out] piBytesWritten Bytes written 143 * 144 * @retval TRC_FAIL Write failed 145 * @retval TRC_SUCCESS Success 146 */ 147 #define xTraceStreamPortWriteData(_pvData, _uiSize, _piBytesWritten) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_4((void)(_pvData), (void)(_uiSize), (void)(_piBytesWritten), TRC_SUCCESS) 148 149 /** 150 * @brief Reads data through the stream port interface. 151 * 152 * @param[in] pvData Destination data buffer 153 * @param[in] uiSize Destination data buffer size 154 * @param[out] piBytesRead Bytes read 155 * 156 * @retval TRC_FAIL Read failed 157 * @retval TRC_SUCCESS Success 158 */ 159 #define xTraceStreamPortReadData(pvData, uiSize, piBytesRead) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_4((void)(pvData), (void)(uiSize), (void)(piBytesRead), TRC_SUCCESS) 160 161 /** 162 * @brief Callback for when recorder is enabled 163 * 164 * @param[in] uiStartOption Start option used when enabling trace recorder 165 * 166 * @retval TRC_FAIL Fail 167 * @retval TRC_SUCCESS Success 168 */ 169 #define xTraceStreamPortOnEnable(uiStartOption) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2((void)(uiStartOption), TRC_SUCCESS) 170 171 /** 172 * @brief Callback for when recorder is disabled 173 * 174 * @retval TRC_FAIL Fail 175 * @retval TRC_SUCCESS Success 176 */ 177 #define xTraceStreamPortOnDisable() TRC_COMMA_EXPR_TO_STATEMENT_EXPR_1(TRC_SUCCESS) 178 179 /** 180 * @brief Callback for when tracing begins 181 * 182 * @retval TRC_FAIL Fail 183 * @retval TRC_SUCCESS Success 184 */ 185 traceResult xTraceStreamPortOnTraceBegin(void); 186 187 /** 188 * @brief Callback for when tracing ends 189 * 190 * @retval TRC_FAIL Fail 191 * @retval TRC_SUCCESS Success 192 */ 193 #define xTraceStreamPortOnTraceEnd() TRC_COMMA_EXPR_TO_STATEMENT_EXPR_1(TRC_SUCCESS) 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_STREAM_PORT_H */ 204
