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