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