Initial Commit

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                                                                                    */
+/*------------------------------------------------------------------------------------------------*/
+