diff options
Diffstat (limited to 'ucs2-lib/inc/ucs_trace.h')
| -rw-r--r-- | ucs2-lib/inc/ucs_trace.h | 237 |
1 files changed, 237 insertions, 0 deletions
diff --git a/ucs2-lib/inc/ucs_trace.h b/ucs2-lib/inc/ucs_trace.h new file mode 100644 index 0000000..3137932 --- /dev/null +++ b/ucs2-lib/inc/ucs_trace.h @@ -0,0 +1,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 */ +/*------------------------------------------------------------------------------------------------*/ + |