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 trace ISR APIs. 13 */ 14 15 #ifndef TRC_ISR_H 16 #define TRC_ISR_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_isr_apis Trace ISR APIs 30 * @ingroup trace_recorder_apis 31 * @{ 32 */ 33 34 /** 35 * @internal Trace ISR Core Data Structure 36 */ 37 typedef struct TraceISRCoreData /* Aligned */ 38 { 39 TraceISRHandle_t handleStack[TRC_CFG_MAX_ISR_NESTING]; /**< */ 40 int32_t stackIndex; /**< */ 41 uint32_t isPendingContextSwitch; /**< */ 42 } TraceISRCoreData_t; 43 44 /** 45 * @internal Trace ISR Data Structure 46 */ 47 typedef struct TraceISRData /* Aligned */ 48 { 49 TraceISRCoreData_t cores[TRC_CFG_CORE_COUNT]; /* ISR handles */ 50 } TraceISRData_t; 51 52 /* We expose this to enable faster access */ 53 extern TraceISRData_t* pxTraceISRData; 54 55 /** 56 * @internal Initialize ISR trace system. 57 * 58 * @param[in] pxBuffer Pointer to memory that will be used by the ISR 59 * trace system. 60 * 61 * @retval TRC_FAIL Failure 62 * @retval TRC_SUCCESS Success 63 */ 64 traceResult xTraceISRInitialize(TraceISRData_t *pxBuffer); 65 66 /** 67 * @brief Registers trace ISR. 68 * 69 * This routine stores a name and priority level for an Interrupt Service Routine, 70 * to allow for better visualization. Returns a TraceISRHandle_t used by 71 * xTraceISRBegin/xTraceISREnd. 72 * 73 * Example: 74 * #define PRIO_OF_ISR_TIMER1 3 // the hardware priority of the interrupt 75 * TraceISRHandle_t xISRTimer1Handle = 0; // The ID set by the recorder 76 * ... 77 * xTraceISRRegister("ISRTimer1", PRIO_OF_ISR_TIMER1, &xISRTimer1Handle); 78 * ... 79 * void ISR_handler() 80 * { 81 * xTraceISRBegin(xISRTimer1Handle); 82 * ... 83 * xTraceISREnd(0); 84 * } 85 * 86 * @param[in] szName Name. 87 * @param[in] uiPriority Priority. 88 * @param[out] pxISRHandle Pointer to uninitialized ISR trace handle. 89 * 90 * @retval TRC_FAIL Failure 91 * @retval TRC_SUCCESS Success 92 */ 93 traceResult xTraceISRRegister(const char* szName, uint32_t uiPriority, TraceISRHandle_t* pxISRHandle); 94 95 /** 96 * @brief Registers the beginning of an Interrupt Service Routine. 97 * 98 * This routine register the beginning of an ISR using a TraceISRHandle_t. 99 * See xTraceISRRegister for and example of using ISR tracing. 100 * 101 * @param[in] xISRHandle Pointer to initialized ISR trace handle. 102 * 103 * @retval TRC_FAIL Failure 104 * @retval TRC_SUCCESS Success 105 */ 106 traceResult xTraceISRBegin(TraceISRHandle_t xISRHandle); 107 108 /** 109 * @brief Registers the end of an Interrupt Service Routine. 110 * 111 * This routine register the end of an ISR using a TraceISRHandle_t. 112 * See xTraceISRRegister for and example of using ISR tracing. 113 * 114 * The parameter uxIsTaskSwitchRequired indicates if the interrupt has requested 115 * a task-switch (= 1), e.g., by signaling a semaphore. Otherwise (= 0) the 116 * interrupt is assumed to return to the previous context. 117 * 118 * @param[in] xIsTaskSwitchRequired Task switch required. 119 * 120 * @retval TRC_FAIL Failure 121 * @retval TRC_SUCCESS Success 122 */ 123 traceResult xTraceISREnd(TraceBaseType_t xIsTaskSwitchRequired); 124 125 #if ((TRC_CFG_USE_TRACE_ASSERT) == 1) 126 127 /** 128 * @brief Gets current trace ISR nesting level. 129 * 130 * This routine gets the current trace ISR nesting level for the 131 * CPU on which it is called. 132 * 133 * @param[out] puiValue Value. 134 * 135 * @retval TRC_FAIL Failure 136 * @retval TRC_SUCCESS Success 137 */ 138 traceResult xTraceISRGetCurrentNesting(int32_t* puiValue); 139 140 /** 141 * @brief 142 * 143 * @return int32_t 144 */ 145 int32_t xTraceISRGetCurrentNestingReturned(void); 146 147 /** 148 * @brief Gets current ISR trace handle. 149 * 150 * @param[out] pxISRHandle ISR Handle. 151 * 152 * @retval TRC_FAIL Failure 153 * @retval TRC_SUCCESS Success 154 */ 155 traceResult xTraceISRGetCurrent(TraceISRHandle_t* pxISRHandle); 156 157 #else /* ((TRC_CFG_USE_TRACE_ASSERT) == 1) */ 158 159 /** 160 * @brief Gets current trace ISR nesting level. 161 * 162 * This routine gets the current trace ISR nesting level for the 163 * CPU on which it is called. 164 * 165 * @param[out] puiValue Value. 166 * 167 * @retval TRC_FAIL Failure 168 * @retval TRC_SUCCESS Success 169 */ 170 #define xTraceISRGetCurrentNesting(puiValue) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(*(puiValue) = pxTraceISRData->cores[TRC_CFG_GET_CURRENT_CORE()].stackIndex, TRC_SUCCESS) 171 172 /** 173 * @brief 174 * 175 * @return int32_t 176 */ 177 #define xTraceISRGetCurrentNestingReturned() (pxTraceISRData->cores[TRC_CFG_GET_CURRENT_CORE()].stackIndex) 178 179 /** 180 * @brief Gets current trace ISR nesting level. 181 * 182 * This routine gets the current trace ISR nesting level for the 183 * CPU on which it is called. 184 * 185 * @param[out] puiValue Value. 186 * 187 * @retval TRC_FAIL Failure 188 * @retval TRC_SUCCESS Success 189 */ 190 #define xTraceISRGetCurrent(pxISRHandle) (xTraceISRGetCurrentNestingReturned() >= 0 ? (*(pxISRHandle) = pxTraceISRData->cores[TRC_CFG_GET_CURRENT_CORE()].handleStack[xTraceISRGetCurrentNestingReturned()], TRC_SUCCESS) : TRC_FAIL) 191 192 #endif /* ((TRC_CFG_USE_TRACE_ASSERT) == 1) */ 193 194 /** @internal Deprecated - Provides backwards-compability with older recorders for now, will be removed in the future */ 195 TraceISRHandle_t xTraceSetISRProperties(const char* szName, uint32_t uiPriority); 196 197 /** @internal Deprecated - Provides backwards-compability with older recorders for now, will be removed in the future */ 198 #define xTraceGetCurrentISRNesting(puiValue) xTraceISRGetCurrentNesting(puiValue) 199 200 /** @internal Deprecated - Provides backwards-compability with older recorders for now, will be removed in the future */ 201 #define vTraceStoreISRBegin(xISRHandle) xTraceISRBegin(xISRHandle) 202 203 /** @internal Deprecated - Provides backwards-compability with older recorders for now, will be removed in the future */ 204 #define vTraceStoreISREnd(xIsTaskSwitchRequired) xTraceISREnd(xIsTaskSwitchRequired) 205 206 /** @} */ 207 208 #ifdef __cplusplus 209 } 210 #endif 211 212 #endif 213 214 #endif 215 216 #endif 217
