1 /* 2 * Trace Recorder for Tracealyzer v4.9.2 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 use XMOS xScope as a streaming channel. 10 */ 11 12 #ifndef TRC_STREAMING_PORT_H 13 #define TRC_STREAMING_PORT_H 14 15 #if (TRC_USE_TRACEALYZER_RECORDER == 1) 16 17 #if (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING) 18 19 #ifdef __cplusplus 20 extern "C" { 21 #endif 22 23 #include <trcTypes.h> 24 #include <trcStreamPortConfig.h> 25 26 #define TRC_USE_INTERNAL_BUFFER (TRC_CFG_STREAM_PORT_USE_INTERNAL_BUFFER) 27 28 #define TRC_INTERNAL_EVENT_BUFFER_WRITE_MODE (TRC_CFG_STREAM_PORT_INTERNAL_BUFFER_WRITE_MODE) 29 30 #define TRC_INTERNAL_EVENT_BUFFER_TRANSFER_MODE (TRC_CFG_STREAM_PORT_INTERNAL_BUFFER_TRANSFER_MODE) 31 32 #define TRC_INTERNAL_BUFFER_CHUNK_SIZE (TRC_CFG_STREAM_PORT_INTERNAL_BUFFER_CHUNK_SIZE) 33 34 #define TRC_INTERNAL_BUFFER_CHUNK_TRANSFER_AGAIN_SIZE_LIMIT (TRC_CFG_STREAM_PORT_INTERNAL_BUFFER_CHUNK_TRANSFER_AGAIN_SIZE_LIMIT) 35 36 #define TRC_INTERNAL_BUFFER_CHUNK_TRANSFER_AGAIN_COUNT_LIMIT (TRC_CFG_STREAM_PORT_INTERNAL_BUFFER_CHUNK_TRANSFER_AGAIN_COUNT_LIMIT) 37 38 /* Aligned */ 39 #define TRC_STREAM_PORT_INTERNAL_BUFFER_SIZE ((((TRC_CFG_STREAM_PORT_INTERNAL_BUFFER_SIZE) + sizeof(TraceUnsignedBaseType_t) - 1) / sizeof(TraceUnsignedBaseType_t)) * sizeof(TraceUnsignedBaseType_t)) 40 41 /** 42 * @brief A structure representing the trace stream port buffer. 43 */ 44 typedef struct TraceStreamPortBuffer /* Aligned */ 45 { 46 #if (TRC_USE_INTERNAL_BUFFER == 1) 47 uint8_t uiBufferInternal[TRC_STREAM_PORT_INTERNAL_BUFFER_SIZE]; 48 #endif 49 uint8_t uiBuffer[sizeof(TraceUnsignedBaseType_t)]; 50 } TraceStreamPortBuffer_t; 51 52 /** 53 * @internal Stream port initialize callback. 54 * 55 * This function is called by the recorder as part of its initialization phase. 56 * 57 * @param[in] pxBuffer Buffer 58 * @retval TRC_FAIL Initialization failed 59 * @retval TRC_SUCCESS Success 60 */ 61 traceResult xTraceStreamPortInitialize(TraceStreamPortBuffer_t* pxBuffer); 62 63 /** 64 * @brief Stream port begin callback. 65 * 66 * This function is called by the recorder as part of its begin phase. 67 * 68 * @retval TRC_FAIL Failure 69 * @retval TRC_SUCCESS Success 70 */ 71 traceResult xTraceStreamPortOnBegin(void); 72 73 /** 74 * @brief Stream port end callback. 75 * 76 * This function is called by the recorder as part of its end phase. 77 * 78 * @retval TRC_FAIL Failure 79 * @retval TRC_SUCCESS Success 80 */ 81 traceResult xTraceStreamPortOnEnd(void); 82 83 /** 84 * @brief Allocates data from the stream port. 85 * 86 * @param[in] uiSize Allocation size 87 * @param[out] ppvData Allocation data pointer 88 * 89 * @retval TRC_FAIL Allocate failed 90 * @retval TRC_SUCCESS Success 91 */ 92 traceResult xTraceStreamPortAllocate(uint32_t uiSize, void** ppvData); 93 94 /** 95 * @brief Commits data to the stream port, depending on the implementation/configuration of the 96 * stream port this data might be directly written to the stream port interface, buffered, or 97 * something else. 98 * 99 * @param[in] pvData Data to commit 100 * @param[in] uiSize Data to commit size 101 * @param[out] piBytesCommitted Bytes commited 102 * 103 * @retval TRC_FAIL Commit failed 104 * @retval TRC_SUCCESS Success 105 */ 106 traceResult xTraceStreamPortCommit(void* pvData, uint32_t uiSize, int32_t* piBytesCommitted); 107 108 /** 109 * @brief Writes data through the stream port interface. 110 * 111 * @param[in] pvData Data to write 112 * @param[in] uiSize Data to write size 113 * @param[out] piBytesWritten Bytes written 114 * 115 * @retval TRC_FAIL Write failed 116 * @retval TRC_SUCCESS Success 117 */ 118 traceResult xTraceStreamPortWriteData(void* pvData, uint32_t uiSize, int32_t* piBytesWritten); 119 120 /** 121 * @brief Reads data through the stream port interface. 122 * 123 * @param[in] pvData Destination data buffer 124 * @param[in] uiSize Destination data buffer size 125 * @param[out] piBytesRead Bytes read 126 * 127 * @retval TRC_FAIL Read failed 128 * @retval TRC_SUCCESS Success 129 */ 130 traceResult xTraceStreamPortReadData(void* pvData, uint32_t uiSize, int32_t* piBytesRead); 131 132 #define xTraceStreamPortOnEnable(uiStartOption) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2((void)(uiStartOption), TRC_SUCCESS) 133 134 #define xTraceStreamPortOnDisable() TRC_COMMA_EXPR_TO_STATEMENT_EXPR_1(TRC_SUCCESS) 135 136 #define xTraceStreamPortOnTraceBegin() TRC_COMMA_EXPR_TO_STATEMENT_EXPR_1(TRC_SUCCESS) 137 138 #define xTraceStreamPortOnTraceEnd() TRC_COMMA_EXPR_TO_STATEMENT_EXPR_1(TRC_SUCCESS) 139 140 #ifdef __cplusplus 141 } 142 #endif 143 144 #endif /*(TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING)*/ 145 146 #endif /*(TRC_USE_TRACEALYZER_RECORDER == 1)*/ 147 148 #endif /* TRC_STREAMING_PORT_H */ 149
