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