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