ucs2-lib/inc/ucs_trace.h

   1 /*------------------------------------------------------------------------------------------------*/
   2 /* UNICENS V2.1.0-3491                                                                            */
   3 /* Copyright (c) 2017 Microchip Technology Germany II GmbH & Co. KG.                              */
   4 /*                                                                                                */
   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.                                                            */
   9 /*                                                                                                */
  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.                                                   */
  14 /*                                                                                                */
  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/>.                          */
  17 /*                                                                                                */
  18 /* You may also obtain this software under a propriety license from Microchip.                    */
  19 /* Please contact Microchip for further information.                                              */
  20 /*------------------------------------------------------------------------------------------------*/
  21
  22 /*!
  23  * \file
  24  * \brief Internal header file of the trace interface
  25  */
  26
  27 #ifndef UCS_TRACE_H
  28 #define UCS_TRACE_H
  29
  30 /*------------------------------------------------------------------------------------------------*/
  31 /* Includes                                                                                       */
  32 /*------------------------------------------------------------------------------------------------*/
  33 #include "ucs_trace_pb.h"
  34
  35 #ifdef __cplusplus
  36 extern "C"
  37 {
  38 #endif
  39
  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"
  46
  47 /*------------------------------------------------------------------------------------------------*/
  48 /* Internal macros                                                                                */
  49 /*------------------------------------------------------------------------------------------------*/
  50
  51 /*! \def     UCS_TR_INFO
  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
  56  *           signature.
  57  *
  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
  63  *                                 argument list
  64  *           - <b>[...]</b><br>Variable argument list to pass trace arguments
  65  *
  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.
  70  *
  71  *           <b>Example:</b>
  72  *           \code
  73  *           extern void App_UcsTraceInfo(void * ucs_user_ptr,
  74  *                                        const char module_str[],
  75  *                                        const char entry_str[],
  76  *                                        uint16_t vargs_cnt,
  77  *                                        ...);
  78  *
  79  *           #define UCS_TR_INFO   App_UcsTraceInfo
  80  *           \endcode
  81  *
  82  *  \ingroup G_UCS_TRACE
  83  */
  84
  85 /*! \def     UCS_TR_ERROR
  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
  90  *           signature.
  91  *
  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
  97  *                                 argument list
  98  *           - <b>[...]</b><br>Variable argument list to pass trace arguments
  99  *
 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()".
 104  *
 105  *           <b>Example:</b>
 106  *           \code
 107  *           extern void App_UcsTraceError(void * ucs_user_ptr,
 108  *                                         const char module_str[],
 109  *                                         const char entry_str[],
 110  *                                         uint16_t vargs_cnt,
 111  *                                         ...);
 112  *
 113  *           #define UCS_TR_ERROR   App_UcsTraceError
 114  *           \endcode
 115  *
 116  *  \ingroup G_UCS_TRACE
 117  */
 118
 119
 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.
 133  */
 134
 135 /*!
 136  * \cond UCS_INTERNAL_DOC
 137  * \addtogroup G_TRACE
 138  * @{
 139  */
 140
 141 /*! \def     TR_INFO
 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
 152  *                                  argument list
 153  *                   - [...]        Variable argument list to pass trace arguments
 154  */
 155
 156 /*! \def     TR_ERROR
 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
 167  *                                  argument list
 168  *                   - [...]        Variable argument list to pass trace arguments
 169  */
 170
 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.
 175  */
 176
 177 /*! \def    TR_ASSERT
 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)
 183  */
 184
 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
 191  */
 192
 193 /*!
 194  * @}
 195  * \endcond
 196  */
 197
 198 /* parasoft suppress MISRA2004-19_7 MISRA2004-19_4 reason "function-like macros are allowed for tracing" */
 199 #ifdef UCS_TR_ERROR
 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)                             \
 204             {                                                                                       \
 205                 uint8_t i;                                                                          \
 206                 TR_ERROR(((ucs_user_ptr), (unit), TR_UCS_INIC_RESULT_ID_1, 0U));                     \
 207                 for(i=0U; i<info_size; i++)                                                         \
 208                 {                                                                                   \
 209                     TR_ERROR(((ucs_user_ptr), (unit), TR_UCS_INIC_RESULT_ID_2, 2U, i, info_ptr[i]))  \
 210                 }                                                                                   \
 211             }
 212 #else
 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)
 218 #endif
 219
 220 #ifdef UCS_TR_INFO
 221 #   define TR_INFO(args) UCS_TR_INFO args;
 222 #else
 223 #   define UCS_TR_INFO
 224 #   define TR_INFO(args)
 225 #endif
 226 /* parasoft unsuppress item MISRA2004-19_7 item MISRA2004-19_4 reason "function-like macros are allowed for tracing" */
 227
 228 #ifdef __cplusplus
 229 }       /* extern "C" */
 230 #endif
 231
 232 #endif  /* #ifndef UCS_TRACE_H */
 233
 234 /*------------------------------------------------------------------------------------------------*/
 235 /* End of file                                                                                    */
 236 /*------------------------------------------------------------------------------------------------*/
 237