1 /*
2 * Percepio Trace Recorder SDK 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 stack monitor APIs.
13  */
14 
15 #ifndef TRC_STACK_MONITOR_H
16 #define TRC_STACK_MONITOR_H
17 
18 #if (TRC_USE_TRACEALYZER_RECORDER == 1) && (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING) && ((TRC_CFG_ENABLE_STACK_MONITOR) == 1) && ((TRC_CFG_SCHEDULING_ONLY) == 0)
19 
20 #include <stdint.h>
21 #include <trcRecorder.h>
22 
23 #ifdef __cplusplus
24 extern "C" {
25 #endif
26 
27 /**
28  * @defgroup trace_stack_monitor_apis Trace Stack Monitor APIs
29  * @ingroup trace_recorder_apis
30  * @{
31  */
32 
33 typedef struct TraceStackMonitorEntry	/* Aligned */
34 {
35 	void *pvTask;
36 	TraceUnsignedBaseType_t uxPreviousLowWaterMark;
37 } TraceStackMonitorEntry_t;
38 
39 typedef struct TraceStackMonitorData	/* Aligned */
40 {
41 	TraceStackMonitorEntry_t xEntries[TRC_CFG_STACK_MONITOR_MAX_TASKS];
42 
43 	TraceUnsignedBaseType_t uxEntryCount;
44 } TraceStackMonitorData_t;
45 
46 /**
47  * @internal Initialize trace stack monitor system.
48  *
49  * @param[in] pxBuffer Pointer to memory that will be used by the trace
50  * stack monitor system.
51  *
52  * @retval TRC_FAIL Failure
53  * @retval TRC_SUCCESS Success
54  */
55 traceResult xTraceStackMonitorInitialize(TraceStackMonitorData_t* pxBuffer);
56 
57 /**
58  * @brief Adds task/thread to trace stack monitor.
59  *
60  * @param[in] pvTask Task/Thread.
61  *
62  * @retval TRC_FAIL Failure
63  * @retval TRC_SUCCESS Success
64  */
65 traceResult xTraceStackMonitorAdd(void* pvTask);
66 
67 /**
68  * @brief Removes task/thread from trace stack monitor.
69  *
70  * @param[in] pvTask Task/Thread.
71  *
72  * @retval TRC_FAIL Failure
73  * @retval TRC_SUCCESS Success
74  */
75 traceResult xTraceStackMonitorRemove(void* pvTask);
76 
77 /**
78  * @brief Gets trace stack monitor tread/task at index.
79  *
80  * @param[in] uiIndex Index.
81  * @param[in] ppvTask Task/Thread.
82  * @param[out] puxLowWaterMark Low water mark.
83  *
84  * @retval TRC_FAIL Failure
85  * @retval TRC_SUCCESS Success
86  */
87 traceResult xTraceStackMonitorGetAtIndex(uint32_t uiIndex, void** ppvTask, TraceUnsignedBaseType_t* puxLowWaterMark);
88 
89 /**
90  * @brief Performs trace stack monitor reporting.
91  *
92  * This routine performs a trace stack monitor check and report
93  * for TRC_CFG_STACK_MONITOR_MAX_REPORTS number of registered
94  * tasks/threads.
95  *
96  * @retval TRC_FAIL Failure
97  * @retval TRC_SUCCESS Success
98  */
99 traceResult xTraceStackMonitorReport(void);
100 
101 /** @} */
102 
103 #ifdef __cplusplus
104 }
105 #endif
106 
107 #else
108 
109 typedef struct TraceStackMonitorData
110 {
111 	uint32_t buffer[1];
112 } TraceStackMonitorData_t;
113 
114 #define xTraceStackMonitorInitialize(__pxBuffer) ((void)(__pxBuffer), TRC_SUCCESS)
115 
116 #define xTraceStackMonitorDiagnosticsGet(__xType, __puiValue) ((void)(__xType), (__puiValue) != 0 ? *(__puiValue) = 0 : 0, (__puiValue) != 0 ? TRC_SUCCESS : TRC_FAIL)
117 
118 #define xTraceStackMonitorDiagnosticsSet(__xType, __uiValue) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_3((void)(__xType), (void)(__uiValue), TRC_SUCCESS)
119 
120 #define xTraceStackMonitorAdd(__pvTask) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2((void)(__pvTask), TRC_SUCCESS)
121 
122 #define xTraceStackMonitorRemove(__pvTask) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2((void)(__pvTask), TRC_SUCCESS)
123 
124 #define xTraceStackMonitorGetAtIndex(__uiIndex, __ppvTask, __puxLowWaterMark) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_4((void)(__uiIndex), (void)_(ppvTask), (void)(__puxLowWaterMark), TRC_SUCCESS)
125 
126 #define xTraceStackMonitorReport() TRC_COMMA_EXPR_TO_STATEMENT_EXPR_1(TRC_SUCCESS)
127 
128 #endif
129 
130 #endif
131