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