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