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 task APIs. 13 */ 14 15 #ifndef TRC_TASK_H 16 #define TRC_TASK_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_task_apis Trace Task APIs 28 * @ingroup trace_recorder_apis 29 * @{ 30 */ 31 32 #ifndef TRC_CFG_ENABLE_STACK_MONITOR 33 #define TRC_CFG_ENABLE_STACK_MONITOR 0 34 #endif 35 36 /** 37 * @internal Trace Task Data Structure 38 */ 39 typedef struct TraceTaskData /* Aligned */ 40 { 41 void* coreTasks[TRC_CFG_CORE_COUNT]; 42 } TraceTaskData_t; 43 44 extern TraceTaskData_t* pxTraceTaskData; 45 46 /** 47 * @internal Initialize trace task system. 48 * 49 * @param[in] pxBuffer Pointer to memory that will be used by the 50 * trace task system. 51 * 52 * @retval TRC_FAIL Failure 53 * @retval TRC_SUCCESS Success 54 */ 55 traceResult xTraceTaskInitialize(TraceTaskData_t* pxBuffer); 56 57 /** 58 * @brief Register trace task in the trace. 59 * 60 * @param[in] pvTask Task. 61 * @param[in] szName Name. 62 * @param[in] uxPriority Priority. 63 * @param[out] pxTaskHandle Pointer to uninitialized trace task. 64 * 65 * @retval TRC_FAIL Failure 66 * @retval TRC_SUCCESS Success 67 */ 68 #define xTraceTaskRegister(pvTask, szName, uxPriority, pxTaskHandle) ((((pvTask) != 0) && (xTraceObjectRegister(PSF_EVENT_TASK_CREATE, pvTask, szName, uxPriority, (TraceObjectHandle_t*)(pxTaskHandle)) == TRC_SUCCESS)) ? ((void)xTraceStackMonitorAdd(pvTask), TRC_SUCCESS) : TRC_FAIL) 69 70 /** 71 * @brief Unregister trace task from trace. 72 * 73 * @param[in] xTaskHandle Pointer to initialized trace task. 74 * @param[in] uxPriority Priority. 75 * 76 * @retval TRC_FAIL Failure 77 * @retval TRC_SUCCESS Success 78 */ 79 #define xTraceTaskUnregister(xTaskHandle, uxPriority) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2((void)xTraceStackMonitorRemove(xTraceEntryGetAddressReturn((TraceEntryHandle_t)(xTaskHandle))), xTraceObjectUnregister((TraceObjectHandle_t)(xTaskHandle), PSF_EVENT_TASK_DELETE, uxPriority)) 80 81 /** 82 * @brief Sets trace task name. 83 * 84 * @param[in] pvTask Task. 85 * @param[in] szName Name. 86 * 87 * @retval TRC_FAIL Failure 88 * @retval TRC_SUCCESS Success 89 */ 90 #define xTraceTaskSetName xTraceObjectSetName 91 92 /** 93 * @brief Sets trace task priority. 94 * 95 * @param[in] xTaskHandle Pointer to initialized trace task. 96 * @param[in] uxPriority Priority. 97 * 98 * @retval TRC_FAIL Failure 99 * @retval TRC_SUCCESS Success 100 */ 101 traceResult xTraceTaskSetPriority(TraceTaskHandle_t xTaskHandle, TraceUnsignedBaseType_t uxPriority); 102 103 /** 104 * @brief Registers trace task without trace task handle. 105 * 106 * @param[in] pvTask Task. 107 * @param[in] szName Name. 108 * @param[in] uxPriority Priority. 109 * 110 * @retval TRC_FAIL Failure 111 * @retval TRC_SUCCESS Success 112 */ 113 #define xTraceTaskRegisterWithoutHandle(pvTask, szName, uxPriority) ((((pvTask) != 0) && (xTraceObjectRegisterWithoutHandle(PSF_EVENT_TASK_CREATE, pvTask, szName, uxPriority) == TRC_SUCCESS)) ? ((void)xTraceStackMonitorAdd(pvTask), TRC_SUCCESS) : TRC_FAIL) 114 115 /** 116 * @brief Unregisters trace task without trace task handle. 117 * 118 * @param[in] pvTask Task. 119 * @param[in] uxPriority Priority. 120 * 121 * @retval TRC_FAIL Failure 122 * @retval TRC_SUCCESS Success 123 */ 124 #define xTraceTaskUnregisterWithoutHandle(pvTask, uxPriority) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2((void)xTraceStackMonitorRemove(pvTask), xTraceObjectUnregisterWithoutHandle(PSF_EVENT_TASK_DELETE, pvTask, uxPriority)) 125 126 /** 127 * @brief Sets trace task name without trace task handle. 128 * 129 * @param[in] pvTask Task. 130 * @param[in] szName Name. 131 * 132 * @retval TRC_FAIL Failure 133 * @retval TRC_SUCCESS Success 134 */ 135 #define xTraceTaskSetNameWithoutHandle xTraceObjectSetNameWithoutHandle 136 137 /** 138 * @brief Sets trace task priority without trace task handle. 139 * 140 * @param[in] pvTask Task. 141 * @param[in] uxPriority Priority. 142 * 143 * @retval TRC_FAIL Failure 144 * @retval TRC_SUCCESS Success 145 */ 146 traceResult xTraceTaskSetPriorityWithoutHandle(void* pvTask, TraceUnsignedBaseType_t uxPriority); 147 148 /** 149 * @brief Registers trace task switch event. 150 * 151 * @param[in] pvTask Task. 152 * @param[in] uxPriority Priority. 153 * 154 * @retval TRC_FAIL Failure 155 * @retval TRC_SUCCESS Success 156 */ 157 traceResult xTraceTaskSwitch(void* pvTask, TraceUnsignedBaseType_t uxPriority); 158 159 #if (TRC_CFG_INCLUDE_READY_EVENTS == 1) 160 /** 161 * @brief Registers trace task ready event. 162 * 163 * @param[in] pvTask Task. 164 * 165 * @retval TRC_FAIL Failure 166 * @retval TRC_SUCCESS Success 167 */ 168 #define xTraceTaskReady(pvTask) xTraceEventCreate1(PSF_EVENT_TASK_READY, (TraceUnsignedBaseType_t)(pvTask)) 169 #else 170 #define xTraceTaskReady(p) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2((void)p, TRC_SUCCESS) 171 #endif 172 173 /** 174 * @brief Sets current trace task on current core. 175 * 176 * @param[in] pvTask Task. 177 * 178 * @retval TRC_FAIL Failure 179 * @retval TRC_SUCCESS Success 180 */ 181 #define xTraceTaskSetCurrent(pvTask) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(pxTraceTaskData->coreTasks[TRC_CFG_GET_CURRENT_CORE()] = (pvTask), TRC_SUCCESS) 182 183 /** 184 * @brief Sets current trace task on specific core. 185 * 186 * @param[in] coreId Core id. 187 * @param[in] pvTask Task. 188 * 189 * @retval TRC_FAIL Failure 190 * @retval TRC_SUCCESS Success 191 */ 192 #define xTraceTaskSetCurrentOnCore(coreId, pvTask) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(pxTraceTaskData->coreTasks[coreId] = (pvTask), TRC_SUCCESS) 193 194 /** 195 * @brief Gets current trace task on current core. 196 * 197 * @param[out] ppvTask Task. 198 * 199 * @retval TRC_FAIL Failure 200 * @retval TRC_SUCCESS Success 201 */ 202 #define xTraceTaskGetCurrent(ppvTask) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(*(ppvTask) = pxTraceTaskData->coreTasks[TRC_CFG_GET_CURRENT_CORE()], TRC_SUCCESS) 203 204 /** 205 * @brief Gets current trace task on specific core. 206 * 207 * @param[in] coreId Core id. 208 * @param[out] ppvTask Task. 209 * 210 * @retval TRC_FAIL Failure 211 * @retval TRC_SUCCESS Success 212 */ 213 #define xTraceTaskGetCurrentOnCore(coreId, ppvTask) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2(*(ppvTask) = pxTraceTaskData->coreTasks[coreId], TRC_SUCCESS) 214 215 /** 216 * @brief Returns current trace task. 217 * 218 * @returns Current trace task. 219 */ 220 #define xTraceTaskGetCurrentReturn() (pxTraceTaskData->coreTasks[TRC_CFG_GET_CURRENT_CORE()]) 221 222 /** 223 * @brief Registers trace task instance finished event. 224 * 225 * This routine creates a trace event that ends the current task instance at 226 * this very instant. This makes the viewer split the current fragment at 227 * this point and begin a new actor instance, even if no task-switch has 228 * occurred 229 * 230 * @retval TRC_FAIL Failure 231 * @retval TRC_SUCCESS Success 232 */ 233 #define xTraceTaskInstanceFinishedNow() xTraceEventCreate0(PSF_EVENT_IFE_DIRECT) 234 235 /** 236 * @brief Marks the current trace task instance as finished on the next 237 * kernel call. 238 * 239 * If that kernel call is blocking, the instance ends after the blocking event 240 * and the corresponding return event is then the start of the next instance. 241 * If the kernel call is not blocking, the viewer instead splits the current 242 * fragment right before the kernel call, which makes this call the first event 243 * of the next instance. 244 * 245 * @retval TRC_FAIL Failure 246 * @retval TRC_SUCCESS Success 247 */ 248 #define xTraceTaskInstanceFinishedNext() xTraceEventCreate0(PSF_EVENT_IFE_NEXT) 249 250 /** @} */ 251 252 #ifdef __cplusplus 253 } 254 #endif 255 256 #else 257 258 #define xTraceTaskRegister(__pvTask, ___szName, __uxPriority, __pxTaskHandle) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_5((void)(__pvTask), (void)(__szName), (void)(__uxPriority), (void)(__pxTaskHandle), TRC_SUCCESS) 259 260 #define xTraceTaskUnregister(__xTaskHandle, __uxPriority) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(__xTaskHandle), (void)(__uxPriority), TRC_SUCCESS) 261 262 #define xTraceTaskSetName(__xTaskHandle, __szName) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(__xTaskHandle), (void)(__szName), TRC_SUCCESS) 263 264 #define xTraceTaskSetPriority(__xTaskHandle, __uxPriority) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(__xTaskHandle), (void)(__uxPriority), TRC_SUCCESS) 265 266 #define xTraceTaskRegisterWithoutHandle(__pvTask, __szName, __uxPriority) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_4((void)(__pvTask), (void)(__szName), (void)(__uxPriority), TRC_SUCCESS) 267 268 #define xTraceTaskUnregisterWithoutHandle(__pvTask, __uxPriority) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(__pvTask), (void)(__uxPriority), TRC_SUCCESS) 269 270 #define xTraceTaskSetNameWithoutHandle(__pvTask, __szName) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(__pvTask), (void)(__szName), TRC_SUCCESS) 271 272 #define xTraceTaskSetPriorityWithoutHandle(__pvTask, __uxPriority) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(__pvTask), (void)(__uxPriority), TRC_SUCCESS) 273 274 #define xTraceTaskSwitch(__pvTask, __uxPriority) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(__pvTask), (void)(__uxPriority), TRC_SUCCESS) 275 276 #define xTraceTaskReady(__pvTask) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2((void)(__pvTask), TRC_SUCCESS) 277 278 #define xTraceTaskSetCurrent(__pvTask) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2((void)(__pvTask), TRC_SUCCESS) 279 280 #define xTraceTaskSetCurrentOnCore(__coreId, __pvTask) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(__coreId), (void)(__pvTask), TRC_SUCCESS) 281 282 #define xTraceTaskGetCurrent(__ppvTask) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2((void)(__ppvTask), TRC_SUCCESS) 283 284 #define xTraceTaskGetCurrentOnCore(__coreId, __ppvTask) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(__coreId), (void)(__ppvTask), TRC_SUCCESS) 285 286 #define xTraceTaskGetCurrentReturn() (0) 287 288 #define xTraceTaskInstanceFinishedNow() (TRC_SUCCESS) 289 290 #define xTraceTaskInstanceFinishedNext() (TRC_SUCCESS) 291 292 #endif 293 294 #endif 295
