1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
|
/*------------------------------------------------------------------------------------------------*/
/* UNICENS V2.1.0-3491 */
/* Copyright (c) 2017 Microchip Technology Germany II GmbH & Co. KG. */
/* */
/* This program is free software: you can redistribute it and/or modify */
/* it under the terms of the GNU General Public License as published by */
/* the Free Software Foundation, either version 2 of the License, or */
/* (at your option) any later version. */
/* */
/* This program is distributed in the hope that it will be useful, */
/* but WITHOUT ANY WARRANTY; without even the implied warranty of */
/* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the */
/* GNU General Public License for more details. */
/* */
/* You should have received a copy of the GNU General Public License */
/* along with this program. If not, see <http://www.gnu.org/licenses/>. */
/* */
/* You may also obtain this software under a propriety license from Microchip. */
/* Please contact Microchip for further information. */
/*------------------------------------------------------------------------------------------------*/
/*!
* \file
* \brief Internal header file of the trace interface
*/
#ifndef UCS_TRACE_H
#define UCS_TRACE_H
/*------------------------------------------------------------------------------------------------*/
/* Includes */
/*------------------------------------------------------------------------------------------------*/
#include "ucs_trace_pb.h"
#ifdef __cplusplus
extern "C"
{
#endif
/*------------------------------------------------------------------------------------------------*/
/* Unit and entry ids */
/*------------------------------------------------------------------------------------------------*/
#define TR_UCS_ASSERT "ASSERT failed in line %d"
#define TR_UCS_INIC_RESULT_ID_1 "INIC error data:"
#define TR_UCS_INIC_RESULT_ID_2 "--> Data[%u]: 0x%02X"
/*------------------------------------------------------------------------------------------------*/
/* Internal macros */
/*------------------------------------------------------------------------------------------------*/
/*! \def UCS_TR_INFO
* \brief Trace macro to capture trace info events
* \details This macro is used to enable the capturing of trace info events. The macro must be
* mapped onto a user-defined function. To disable the trace info events, the macro must
* not be defined. The mapped user-defined function must adhere to the following function
* signature.
*
* void (*Ucs_TraceCb_t)(void * ucs_user_ptr, const char module_str[], const char entry_str[], uint16_t vargs_cnt, ...);
* - <b>ucs_user_ptr</b><br>Reference to the User argument
* - <b>module_str</b><br>The name of the software module that has posted the trace
* - <b>entry_str</b><br>The trace entry as formatted string
* - <b>vargs_cnt</b><br>Number of trace arguments which will be passed within the variable
* argument list
* - <b>[...]</b><br>Variable argument list to pass trace arguments
*
* \warning Do not assign UCS_TR_INFO in a production system. This has major effects on the CPU load and runtime.
* UCS_TR_INFO is intended for debugging software during development phase. Microchip Support might
* request you to assign of this macro to spy on internal events. Disable this macro definition after
* your support case is closed.
*
* <b>Example:</b>
* \code
* extern void App_UcsTraceInfo(void * ucs_user_ptr,
* const char module_str[],
* const char entry_str[],
* uint16_t vargs_cnt,
* ...);
*
* #define UCS_TR_INFO App_UcsTraceInfo
* \endcode
*
* \ingroup G_UCS_TRACE
*/
/*! \def UCS_TR_ERROR
* \brief Trace macro to capture trace error events
* \details This macro is used to enable the capturing of trace error events. The macro must be
* mapped onto a user-defined function. To disable the trace error events, the macro must
* not be defined. The mapped user-defined function must adhere to the following function
* signature.
*
* void (*Ucs_TraceCb_t)(void * ucs_user_ptr, const char module_str[], const char entry_str[], uint16_t vargs_cnt, ...);
* - <b>ucs_user_ptr</b><br>Reference to the User argument
* - <b>module_str</b><br>The name of the software module that has posted the trace
* - <b>entry_str</b><br>The trace entry as formatted string
* - <b>vargs_cnt</b><br>Number of trace arguments which will be passed within the variable
* argument list
* - <b>[...]</b><br>Variable argument list to pass trace arguments
*
* \note The captured error events can be used for logging and as a first step for debugging
* unexpected behavior. However, the application must not derive any action when an error
* is indicated by the trace interface. An application must handle rely on result callback
* functions and handle "general.error_fptr()".
*
* <b>Example:</b>
* \code
* extern void App_UcsTraceError(void * ucs_user_ptr,
* const char module_str[],
* const char entry_str[],
* uint16_t vargs_cnt,
* ...);
*
* #define UCS_TR_ERROR App_UcsTraceError
* \endcode
*
* \ingroup G_UCS_TRACE
*/
/*! \addtogroup G_UCS_TRACE
* \details The UCS Trace Interface is intended for debugging and logging purpose.
* There are 2 different trace options:
* - The definition of trace macros to print out internal states, messages
* and errors. This option provides two trace classes: \c info and \c error. Each trace
* class can be activated by defining the respective macro UCS_TR_INFO
* UCS_TR_ERROR in the configuration header file \c ucs_cfg.h.
* While the \c info class is intended only for debugging purpose during
* development, the \c error class can also be active for logging purpose
* in a production system.
* - Implementation of the callback function Ucs_DebugErrorMsgCb_t which is assigned
* during initialization. The callback function is fired on every received Error
* message from a local or remote INIC.
*/
/*!
* \cond UCS_INTERNAL_DOC
* \addtogroup G_TRACE
* @{
*/
/*! \def TR_INFO
* \brief Trace macro to capture trace info events
* \details The macro is referenced to a public trace macro which must be defined in ucs_cfg.h. The
* public macros refers to a trace function which must be implemented by the application.
* The given arguments can be stored or immediately converted into a trace output by
* invoking the function Ucs_Tr_DecodeTrace().
* \param args Container of arguments. The following arguments are of the container.
* - ucs_user_ptr Reference to the User argument
* - unit Id of the UNICENS unit that has posted the trace
* - entry Id of the trace entry
* - vargs_cnt Number of trace arguments which will be passed within the variable
* argument list
* - [...] Variable argument list to pass trace arguments
*/
/*! \def TR_ERROR
* \brief Trace macro to capture trace error events
* \details The macro is referenced to a public trace macro which must be defined in ucs_cfg.h. The
* public macros refers to a trace function which must be implemented by the application.
* The given arguments can be stored or immediately converted into a trace output by
* invoking the function Ucs_Tr_DecodeTrace().
* \param args Container of arguments. The following arguments are of the container.
* - ucs_user_ptr Reference to the User argument
* - unit Id of the UNICENS unit that has posted the trace
* - entry Id of the trace entry
* - vargs_cnt Number of trace arguments which will be passed within the variable
* argument list
* - [...] Variable argument list to pass trace arguments
*/
/*! \def TR_FAILED_ASSERT
* \brief Failed Assert statement which will add error entry into the trace output.
* \param ucs_user_ptr Reference to the User argument
* \param unit Identifier for the respective software unit.
*/
/*! \def TR_ASSERT
* \brief Assert statement which evaluates an expression to true. If the expression
* evaluates to false a failed assert will be printed into the trace output.
* \param ucs_user_ptr Reference to the User argument
* \param unit Identifier for the respective software unit.
* \param expr Expression which shall evaluate to \c true (expectation applies)
*/
/*! \def TR_ERROR_INIC_RESULT
* \brief Trace macro to capture INIC error data
* \param ucs_user_ptr Reference to the User argument
* \param unit Identifier for the respective software unit.
* \param info_ptr Byte stream which contains the raw INIC error data
* \param info_size Size of the INIC error data in bytes
*/
/*!
* @}
* \endcond
*/
/* parasoft suppress MISRA2004-19_7 MISRA2004-19_4 reason "function-like macros are allowed for tracing" */
#ifdef UCS_TR_ERROR
# define TR_ERROR(args) UCS_TR_ERROR args;
# define TR_FAILED_ASSERT(ucs_user_ptr, unit) TR_ERROR(((ucs_user_ptr), (unit), TR_UCS_ASSERT, 1U, __LINE__))
# define TR_ASSERT(ucs_user_ptr, unit, expr) if (!(expr)) {TR_FAILED_ASSERT((ucs_user_ptr), (unit));}
# define TR_ERROR_INIC_RESULT(ucs_user_ptr, unit, info_ptr, info_size) \
{ \
uint8_t i; \
TR_ERROR(((ucs_user_ptr), (unit), TR_UCS_INIC_RESULT_ID_1, 0U)); \
for(i=0U; i<info_size; i++) \
{ \
TR_ERROR(((ucs_user_ptr), (unit), TR_UCS_INIC_RESULT_ID_2, 2U, i, info_ptr[i])) \
} \
}
#else
# define UCS_TR_ERROR
# define TR_ERROR(args)
# define TR_FAILED_ASSERT(ucs_user_ptr, unit)
# define TR_ASSERT(ucs_user_ptr, unit, expr)
# define TR_ERROR_INIC_RESULT(ucs_user_ptr, unit, info_ptr, info_size)
#endif
#ifdef UCS_TR_INFO
# define TR_INFO(args) UCS_TR_INFO args;
#else
# define UCS_TR_INFO
# define TR_INFO(args)
#endif
/* parasoft unsuppress item MISRA2004-19_7 item MISRA2004-19_4 reason "function-like macros are allowed for tracing" */
#ifdef __cplusplus
} /* extern "C" */
#endif
#endif /* #ifndef UCS_TRACE_H */
/*------------------------------------------------------------------------------------------------*/
/* End of file */
/*------------------------------------------------------------------------------------------------*/
|
