1 /* 2 * Trace Recorder for Tracealyzer v4.6.6 3 * Copyright 2021 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 ((((TRC_CFG_STREAM_PORT_BUFFER_SIZE) + sizeof(uint32_t) - 1) / sizeof(uint32_t)) * sizeof(uint32_t)) 50 51 /** 52 * @brief 53 */ 54 typedef struct TraceMultiCoreBuffer 55 { 56 uint32_t uiSize; 57 uint8_t uiBuffer[TRC_STREAM_PORT_BUFFER_SIZE]; 58 } TraceMultiCoreBuffer_t; 59 60 /** 61 * @brief 62 */ 63 typedef struct TraceRingBuffer 64 { 65 volatile uint8_t START_MARKERS[12]; 66 TraceHeaderBuffer_t xHeaderBuffer; 67 TraceTimestampBuffer_t xTimestampInfo; 68 TraceEntryTableBuffer_t xEntryTableBuffer; 69 TraceMultiCoreBuffer_t xEventBuffer; 70 volatile uint8_t END_MARKERS[12]; 71 } TraceRingBuffer_t; 72 73 /** 74 * @brief 75 */ 76 typedef struct TraceStreamPortData 77 { 78 TraceMultiCoreEventBuffer_t xMultiCoreEventBuffer; 79 TraceRingBuffer_t xRingBuffer; 80 } TraceStreamPortData_t; 81 82 extern TraceStreamPortData_t* pxStreamPortData; 83 84 /** 85 * @def TRC_STREAM_PORT_BUFFER_SIZE 86 * @brief The buffer size, aligned to base type. 87 */ 88 #define TRC_STREAM_PORT_DATA_BUFFER_SIZE (sizeof(TraceStreamPortData_t)) 89 90 /** 91 * @brief A structure representing the trace stream port buffer. 92 */ 93 typedef struct TraceStreamPortBuffer 94 { 95 uint8_t buffer[(TRC_STREAM_PORT_DATA_BUFFER_SIZE)]; 96 } TraceStreamPortBuffer_t; 97 98 /** 99 * @internal Stream port initialize callback. 100 * 101 * This function is called by the recorder as part of its initialization phase. 102 * 103 * @param[in] pxBuffer Buffer 104 * 105 * @retval TRC_FAIL Initialization failed 106 * @retval TRC_SUCCESS Success 107 */ 108 traceResult xTraceStreamPortInitialize(TraceStreamPortBuffer_t* pxBuffer); 109 110 /** 111 * @brief Allocates data from the stream port. 112 * 113 * @param[in] uiSize Allocation size 114 * @param[out] ppvData Allocation data pointer 115 * 116 * @retval TRC_FAIL Allocate failed 117 * @retval TRC_SUCCESS Success 118 */ 119 #define xTraceStreamPortAllocate(uiSize, ppvData) ((void)uiSize, xTraceStaticBufferGet(ppvData)) 120 121 /** 122 * @brief Commits data to the stream port, depending on the implementation/configuration of the 123 * stream port this data might be directly written to the stream port interface, buffered, or 124 * something else. 125 * 126 * @param[in] pvData Data to commit 127 * @param[in] uiSize Data to commit size 128 * @param[out] piBytesCommitted Bytes commited 129 * 130 * @retval TRC_FAIL Commit failed 131 * @retval TRC_SUCCESS Success 132 */ 133 traceResult xTraceStreamPortCommit(void* pvData, uint32_t uiSize, int32_t* piBytesCommitted); 134 135 /** 136 * @brief Writes data through the stream port interface. 137 * 138 * @param[in] pvData Data to write 139 * @param[in] uiSize Data to write size 140 * @param[out] piBytesWritten Bytes written 141 * 142 * @retval TRC_FAIL Write failed 143 * @retval TRC_SUCCESS Success 144 */ 145 #define xTraceStreamPortWriteData(pvData, uiSize, piBytesWritten) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_4((void)(pvData), (void)(uiSize), (void)(piBytesWritten), TRC_SUCCESS) 146 147 /** 148 * @brief Reads data through the stream port interface. 149 * 150 * @param[in] pvData Destination data buffer 151 * @param[in] uiSize Destination data buffer size 152 * @param[out] piBytesRead Bytes read 153 * 154 * @retval TRC_FAIL Read failed 155 * @retval TRC_SUCCESS Success 156 */ 157 #define xTraceStreamPortReadData(pvData, uiSize, piBytesRead) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_4((void)(pvData), (void)(uiSize), (void)(piBytesRead), TRC_SUCCESS) 158 159 /** 160 * @brief Callback for when recorder is enabled 161 * 162 * @param[in] uiStartOption Start option used when enabling trace recorder 163 * 164 * @retval TRC_FAIL Read failed 165 * @retval TRC_SUCCESS Success 166 */ 167 #define xTraceStreamPortOnEnable(uiStartOption) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2((void)(uiStartOption), TRC_SUCCESS) 168 169 /** 170 * @brief Callback for when recorder is disabled 171 * 172 * @retval TRC_FAIL Read failed 173 * @retval TRC_SUCCESS Success 174 */ 175 #define xTraceStreamPortOnDisable() TRC_COMMA_EXPR_TO_STATEMENT_EXPR_1(TRC_SUCCESS) 176 177 /** 178 * @brief Callback for when tracing begins 179 * 180 * @retval TRC_FAIL Read failed 181 * @retval TRC_SUCCESS Success 182 */ 183 traceResult xTraceStreamPortOnTraceBegin(void); 184 185 /** 186 * @brief Callback for when tracing ends 187 * 188 * @retval TRC_FAIL Read failed 189 * @retval TRC_SUCCESS Success 190 */ 191 #define xTraceStreamPortOnTraceEnd() TRC_COMMA_EXPR_TO_STATEMENT_EXPR_1(TRC_SUCCESS) 192 193 #ifdef __cplusplus 194 } 195 #endif 196 197 #endif /*(TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING)*/ 198 199 #endif /*(TRC_USE_TRACEALYZER_RECORDER == 1)*/ 200 201 #endif /* TRC_STREAM_PORT_H */ 202
