ucs2-lib/inc/ucs_ams_pb.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 Public header file of Application Message Service
  25  */
  26 /*!
  27  * \addtogroup G_UCS_AMS_TYPES
  28  * @{
  29  */
  30
  31 #ifndef UCS_AMS_PB_H
  32 #define UCS_AMS_PB_H
  33
  34 /*------------------------------------------------------------------------------------------------*/
  35 /* Includes                                                                                       */
  36 /*------------------------------------------------------------------------------------------------*/
  37 #include "ucs_rules.h"
  38 #include "ucs_message_pb.h"
  39
  40 #ifdef __cplusplus
  41 extern "C"
  42 {
  43 #endif
  44
  45 /*! \brief   Defines which address type was used by the transmitter of a message. */
  46 typedef enum Ucs_AmsRx_ReceiveType_
  47 {
  48     UCS_AMSRX_RCT_SINGLECAST    = 0U,           /*!< \brief Message was transmitted as singlecast */
  49     UCS_AMSRX_RCT_GROUPCAST     = 1U,           /*!< \brief Message was transmitted as groupcast */
  50     UCS_AMSRX_RCT_BROADCAST     = 2U            /*!< \brief Message was transmitted as broadcast */
  51
  52 } Ucs_AmsRx_ReceiveType_t;
  53
  54 /*------------------------------------------------------------------------------------------------*/
  55 /* Types                                                                                          */
  56 /*------------------------------------------------------------------------------------------------*/
  57 /*! \brief Application message Tx type */
  58 typedef struct Ucs_AmsTx_Msg_
  59 {
  60     uint16_t        destination_address;        /*!< \brief   Destination address. Find some predefined addresses \ref G_UCS_AMS "here". */
  61     uint16_t        msg_id;                     /*!< \brief   16bit message descriptor */
  62     uint8_t         llrbc;                      /*!< \brief   Specifies the "Low-Level Retry Block Count" (LLRBC)
  63                                                  *   \details Valid values: 0..100. Default value: configurable via \ref Ucs_AmsTx_InitData_t "default_llrbc"
  64                                                  *            of the initialization structure \ref Ucs_AmsTx_InitData_t.
  65                                                  */
  66     uint8_t        *data_ptr;                   /*!< \brief   Payload data */
  67     uint16_t        data_size;                  /*!< \brief   The size of payload data in bytes */
  68     void           *custom_info_ptr;            /*!< \brief   Customer specific reference
  69                                                  *   \details The application is allowed to use this attribute to assign an
  70                                                  *            own reference to the message object. The reference is initialized
  71                                                  *            by the UNICENS library with \c NULL and will not alter until the
  72                                                  *            transmission has finished.
  73                                                  */
  74 } Ucs_AmsTx_Msg_t;
  75
  76 /*! \brief Application message Rx type */
  77 typedef struct Ucs_AmsRx_Msg_
  78 {
  79     uint16_t        source_address;             /*!< \brief Source address */
  80     uint16_t        msg_id;                     /*!< \brief 16bit message descriptor */
  81     uint8_t        *data_ptr;                   /*!< \brief Reference to payload */
  82     uint16_t        data_size;                  /*!< \brief Payload size in bytes */
  83     void           *custom_info_ptr;            /*!< \brief Customer specific reference */
  84     Ucs_AmsRx_ReceiveType_t receive_type;       /*!< \brief Defines which address type was used by the transmitter of this message */
  85
  86 } Ucs_AmsRx_Msg_t;
  87
  88 /*! \brief Transmission result of an application message */
  89 typedef enum Ucs_AmsTx_Result_
  90 {
  91     UCS_AMSTX_RES_SUCCESS             = 0x00U,/*!< \brief   The transmission succeeded. */
  92
  93     UCS_AMSTX_RES_ERR_RETRIES_EXP     = 0x01U,/*!< \brief   The transmission including all retries have failed.
  94                                                *   \details The following issues may have caused the failure:
  95                                                *            - message corruption
  96                                                *            - transmission timeouts
  97                                                *            - full receive buffers of the destination device
  98                                                *            - full receive buffers of the local device if the
  99                                                *              destination was the own address, own group or broadcast
 100                                                *              address
 101                                                *            .
 102                                                */
 103     UCS_AMSTX_RES_ERR_INVALID_TGT     = 0x02U,/*!< \brief   The transmission failed because the specified destination
 104                                                *            address is not found or not valid.
 105                                                *   \details The following issues may have caused the failure:
 106                                                *            - device with the given destination address is not found
 107                                                *            - destination address is reserved (for future use)
 108                                                *            - destination address is 0xFFFF (un-initialized logical
 109                                                *              node address is not supported)
 110                                                *            .
 111                                                */
 112     UCS_AMSTX_RES_ERR_NOT_AVAILABLE   = 0x03U,/*!< \brief   The transmission failed since the network or the INIC
 113                                                *            is not available.
 114                                                */
 115     UCS_AMSTX_RES_ERR_BUF_INTERNAL    = 0xFEU,/*!< \brief   The transmission failed because the allocation of an Rx message object failed.
 116                                                *            The Rx message object is required to receive the message via the own Rx message queue.
 117                                                *   \details This is possible in the following cases:
 118                                                *            - A message is transmitted to the own node address and the allocation
 119                                                *              of an Rx message object failed.
 120                                                *            - The network transmission to the own group address or broadcast address
 121                                                *              succeeded but the allocation of an Rx message object failed. The application
 122                                                *              has to decide whether to retransmit the message to the own address again.
 123                                                */
 124     UCS_AMSTX_RES_ERR_UNEXPECTED      = 0xFFU /*!< \brief   The transmission failed due to an unexpected error.
 125                                                *            The cause of this failure may be an invalid INIC configuration,
 126                                                *            or an INIC to UNICENS incompatibility issue.
 127                                                */
 128 } Ucs_AmsTx_Result_t;
 129
 130
 131 /*! \brief  Detailed INIC transmission information which might be useful for debugging purposes. */
 132 typedef enum Ucs_AmsTx_Info_
 133 {
 134     UCS_AMSTX_I_SUCCESS             = 0x00U, /*!< \brief   The transmission succeeded.
 135                                               *   \details The corresponding transmission result is \ref UCS_AMSTX_RES_SUCCESS.
 136                                               */
 137     UCS_AMSTX_I_ERR_CFG_NORECEIVER  = 0x01U, /*!< \brief   The transmission failed because the MOST network is not accessible for
 138                                               *            MCM in the current attach state or for ICM in general.
 139                                               *   \details The corresponding transmission result is \ref UCS_AMSTX_RES_ERR_UNEXPECTED.
 140                                               */
 141     UCS_AMSTX_I_ERR_BF              = 0x08U, /*!< \brief   The transmission failed because the receivers buffer is full.
 142                                               *   \details The corresponding transmission result is \ref UCS_AMSTX_RES_ERR_RETRIES_EXP.
 143                                               */
 144     UCS_AMSTX_I_ERR_CRC             = 0x09U, /*!< \brief   The transmission failed because of a failed CRC.
 145                                               *   \details The corresponding transmission result is \ref UCS_AMSTX_RES_ERR_RETRIES_EXP.
 146                                               */
 147     UCS_AMSTX_I_ERR_ID              = 0x0AU, /*!< \brief   The transmission failed because of corrupted identifiers.
 148                                               *   \details The corresponding transmission result is \ref UCS_AMSTX_RES_ERR_RETRIES_EXP.
 149                                               */
 150     UCS_AMSTX_I_ERR_ACK             = 0x0BU, /*!< \brief   The transmission failed because of corrupted PACK or CACK.
 151                                               *   \details The corresponding transmission result is \ref UCS_AMSTX_RES_ERR_RETRIES_EXP.
 152                                               */
 153     UCS_AMSTX_I_ERR_TIMEOUT         = 0x0CU, /*!< \brief   The transmission failed because of a transmission timeout.
 154                                               *   \details The corresponding transmission result is \ref UCS_AMSTX_RES_ERR_RETRIES_EXP.
 155                                               */
 156     UCS_AMSTX_I_ERR_FATAL_WT        = 0x10U, /*!< \brief   The transmission failed because of destination is not available.
 157                                               *   \details The corresponding transmission result is \ref UCS_AMSTX_RES_ERR_INVALID_TGT.
 158                                               */
 159     UCS_AMSTX_I_ERR_FATAL_OA        = 0x11U, /*!< \brief   The transmission failed because of the destination is the own node address.
 160                                               *   \details The corresponding transmission result is \ref UCS_AMSTX_RES_ERR_INVALID_TGT.
 161                                               */
 162     UCS_AMSTX_I_ERR_UNAVAIL_TRANS   = 0x18U, /*!< \brief   The transmission canceled during the transition from network interface state
 163                                               *            "available" to "not available".
 164                                               *   \details The corresponding transmission result is \ref UCS_AMSTX_RES_ERR_NOT_AVAILABLE.
 165                                               */
 166     UCS_AMSTX_I_ERR_UNAVAIL_OFF     = 0x19U, /*!< \brief   The transmission failed because the network interface state is "not available".
 167                                               *   \details The corresponding transmission result is \ref UCS_AMSTX_RES_ERR_NOT_AVAILABLE.
 168                                               */
 169     UCS_AMSTX_I_ERR_UNKNOWN         = 0xFEU, /*!< \brief   The transmission failed because of an unknown INIC error code.
 170                                               *   \details The corresponding transmission result is \ref UCS_AMSTX_RES_ERR_UNEXPECTED.
 171                                               *            Please check if the MNS version is compatible with the applied INIC firmware version.
 172                                               */
 173     UCS_AMSTX_I_ERR_UNSYNCED        = 0xFFU  /*!< \brief   The transmission failed because the communication between the EHC
 174                                               *            and the INIC is lost.
 175                                               *   \details The reason can be a communication error between the EHC and the INIC or that
 176                                               *            the application has called Ucs_Stop().\n
 177                                               *            The corresponding transmission result is \ref UCS_AMSTX_RES_ERR_NOT_AVAILABLE.
 178                                               */
 179 } Ucs_AmsTx_Info_t;
 180
 181 /*! \brief   Type of a callback function that is invoked as soon as a
 182  *           message transmission was finished
 183  *  \details The callback function notifies the result of a completed transmission. If
 184  *           the message has external payload, the application must decide whether
 185  *           to re-use or to free the external payload.
 186  *  \param   msg_ptr  Reference to the related Tx message object. When the callback function returns
 187  *                    the reference is no longer valid.
 188  *  \param   result   The transmission result.
 189  *  \param   info     Detailed INIC transmission result, which might be helpful for debug purposes.
 190  *  \param   user_ptr User reference provided in \ref Ucs_InitData_t "Ucs_InitData_t::user_ptr"
 191  */
 192 typedef void (*Ucs_AmsTx_CompleteCb_t)(Ucs_AmsTx_Msg_t* msg_ptr, Ucs_AmsTx_Result_t result, Ucs_AmsTx_Info_t info, void *user_ptr);
 193
 194 /*!
 195  * @}
 196  * \addtogroup G_UCS_AMS
 197  * @{
 198  */
 199
 200 /*! \brief  Type of a callback function that is invoked to notify that
 201  *          a Tx application message object is available again while a previous
 202  *          allocation using Ucs_AmsTx_AllocMsg() has failed.
 203  *  \param  user_ptr    User reference provided in \ref Ucs_InitData_t "Ucs_InitData_t::user_ptr"
 204  */
 205 typedef void (*Ucs_AmsTx_MsgFreedCb_t)(void *user_ptr);
 206
 207 /*! \brief  Callback function type that is invoked if UNICENS has received a message
 208  *          completely and appended to the Rx message queue.
 209  *  \param  user_ptr    User reference provided in \ref Ucs_InitData_t "Ucs_InitData_t::user_ptr"
 210  */
 211 typedef void (*Ucs_AmsRx_MsgReceivedCb_t)(void *user_ptr);
 212
 213 #ifdef __cplusplus
 214 }               /* extern "C" */
 215 #endif
 216
 217 #endif  /* ifndef UCS_AMS_PB_H */
 218
 219 /*! @} */
 220
 221 /*------------------------------------------------------------------------------------------------*/
 222 /* End of file                                                                                    */
 223 /*------------------------------------------------------------------------------------------------*/
 224