ucs2-lib/inc/ucs_amsmessage.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 Application Message Classes
  25  *
  26  * \cond UCS_INTERNAL_DOC
  27  * \addtogroup G_AMSMSG
  28  * @{
  29  */
  30
  31 #ifndef UCS_AMSMESSAGE_H
  32 #define UCS_AMSMESSAGE_H
  33
  34 /*------------------------------------------------------------------------------------------------*/
  35 /* Includes                                                                                       */
  36 /*------------------------------------------------------------------------------------------------*/
  37 #include "ucs_ams_pb.h"
  38 #include "ucs_message.h"
  39 #include "ucs_dl.h"
  40
  41 #ifdef __cplusplus
  42 extern "C"
  43 {
  44 #endif
  45
  46 /*------------------------------------------------------------------------------------------------*/
  47 /* Internal constants                                                                             */
  48 /*------------------------------------------------------------------------------------------------*/
  49 #define AMSG_TX_OBJECT_SZ   (sizeof(Amsg_IntMsgTx_t))
  50 #define AMSG_RX_OBJECT_SZ   (sizeof(Amsg_IntMsgRx_t))
  51
  52 /*------------------------------------------------------------------------------------------------*/
  53 /* Internal types                                                                                 */
  54 /*------------------------------------------------------------------------------------------------*/
  55 /*! \brief Internal transmission result of an application message */
  56 typedef enum Amsg_TxIntStatus_
  57 {
  58     AMSG_TX_INTRES_NONE     = 0x00U,  /*!< \brief   The internal transmission is not applicable. */
  59     AMSG_TX_INTRES_SUCCESS  = 0x01U,  /*!< \brief   The internal transmission succeeded. */
  60     AMSG_TX_INTRES_ERRBUF   = 0x02U   /*!< \brief   The internal transmission failed. */
  61
  62 } Amsg_TxIntStatus_t;
  63
  64 /*! \brief  Assignable function which is invoked as soon as an application message is received
  65  *          completely and available in the Rx message queue
  66  *  \param  self            The instance (optional)
  67  *  \param  msg_ptr         Reference to the received message
  68  */
  69 typedef void (*Amsg_RxCompleteCb_t)(void* self, Ucs_AmsRx_Msg_t* msg_ptr);
  70
  71 /*! \brief  Callback function type which is fired as soon as an AMS transmission was finished
  72  *  \param  msg_ptr         Reference to the related message object
  73  *  \param  result          Transmission result
  74  *  \param  info            Detailed INIC transmission result
  75  *  \param  self            The instance (optional)
  76  */
  77 typedef void (*Amsg_TxCompleteCb_t)(Ucs_AmsTx_Msg_t* msg_ptr, Ucs_AmsTx_Result_t result, Ucs_AmsTx_Info_t info, void* self);
  78
  79 /*! \brief  Single instance API callback function type which is fired as soon as an AMS transmission was finished
  80  *  \param  msg_ptr         Reference to the related message object
  81  *  \param  result          Transmission result
  82  *  \param  info            Detailed INIC transmission result
  83  */
  84 typedef void (*Amsg_TxCompleteSiaCb_t)(Ucs_AmsTx_Msg_t* msg_ptr, Ucs_AmsTx_Result_t result, Ucs_AmsTx_Info_t info);
  85
  86 /*! \brief  Callback function which is invoked to free a Tx message object to the owning pool
  87  *  \param  owner_ptr       The owning pool of the message object
  88  *  \param  msg_ptr         Reference to the related message object
  89  */
  90 typedef void (*Amsg_TxFreedCb_t)(void *owner_ptr, Ucs_AmsTx_Msg_t* msg_ptr);
  91
  92 /*------------------------------------------------------------------------------------------------*/
  93 /* Class                                                                                          */
  94 /*------------------------------------------------------------------------------------------------*/
  95 /*! \brief Internal Tx message structure */
  96 typedef struct Amsg_IntMsgTx_
  97 {
  98     Ucs_AmsTx_Msg_t     pb_msg;                 /*!< \brief Public message struct must be the first member */
  99     void               *info_ptr;               /*!< \brief Custom object information required by memory management */
 100
 101     void               *free_inst_ptr;          /*!< \brief Reference which is passed to free_ptr */
 102     Amsg_TxFreedCb_t    free_fptr;              /*!< \brief Callback function which is called to free the object */
 103
 104     uint8_t            *memory_ptr;             /*!< \brief Reference to payload provided by memory management */
 105     void               *memory_info_ptr;        /*!< \brief Custom payload information required by memory management */
 106     uint16_t            memory_sz;              /*!< \brief Size of the payload that is provided by memory management */
 107
 108     uint16_t            next_segment_cnt;       /*!< \brief Specifies the next segment count. '0xFF' means size prefixed */
 109     uint8_t             follower_id;            /*!< \brief Identifier of segmented messages and corresponding telegrams  */
 110     Ucs_MsgTxStatus_t   temp_result;            /*!< \brief Stores the temporary result that is notified when then transmission
 111                                                  *          has completed
 112                                                  */
 113     uint16_t            backup_dest_address;    /*!< \brief Backup of replaced target address. */
 114     Amsg_TxIntStatus_t  internal_status;        /*!< \brief Stores the internal transmission status */
 115     bool                ignore_wrong_target;    /*!< \brief Forces the message to report transmission result "success", although
 116                                                  *          the INIC has reported transmission error "wrong target"
 117                                                  */
 118     CDlNode             node;                   /*!< \brief Node required for message pool */
 119
 120     Amsg_TxCompleteSiaCb_t complete_sia_fptr;   /*!< \brief Single instance API Callback function which is invoked
 121                                                  *          after transmission completed
 122                                                  */
 123     Amsg_TxCompleteCb_t    complete_fptr;       /*!< \brief Callback function which is invoked after transmission
 124                                                  *          completed
 125                                                  */
 126     void                  *complete_inst_ptr;   /*!< \brief Instance pointer which is required to invoke complete_fptr */
 127
 128 } Amsg_IntMsgTx_t;
 129
 130 /*! \brief Internal Rx message structure */
 131 typedef struct Amsg_IntMsgRx_
 132 {
 133     Ucs_AmsRx_Msg_t     pb_msg;                 /*!< \brief Public message structure must be the first member */
 134     void               *info_ptr;               /*!< \brief Custom object information required by memory management */
 135
 136     uint8_t            *memory_ptr;             /*!< \brief Reference to payload provided by memory management */
 137     void               *memory_info_ptr;        /*!< \brief Custom payload information required by memory management */
 138     uint16_t            memory_sz;              /*!< \brief The size of the allocated user payload in bytes */
 139
 140     CDlNode             node;                   /*!< \brief Node required for message pool */
 141
 142     uint8_t             exp_tel_cnt;            /*!< \brief The expected TelCnt used for segmented transfer */
 143     bool                gc_marker;              /*!< \brief Identifies message objects that were already
 144                                                  *          marked by the garbage collector.
 145                                                  */
 146 } Amsg_IntMsgRx_t;
 147
 148 /*------------------------------------------------------------------------------------------------*/
 149 /* Class methods                                                                                  */
 150 /*------------------------------------------------------------------------------------------------*/
 151 /* Tx */
 152 extern void Amsg_TxCtor(Ucs_AmsTx_Msg_t *self, void *info_ptr, Amsg_TxFreedCb_t free_fptr, void *free_inst_ptr);
 153 extern void Amsg_TxSetInternalPayload(Ucs_AmsTx_Msg_t *self, uint8_t *mem_ptr, uint16_t mem_size, void *mem_info_ptr);
 154 extern void Amsg_TxReuse(Ucs_AmsTx_Msg_t *self);
 155 extern void Amsg_TxSetCompleteCallback(Ucs_AmsTx_Msg_t *self, Amsg_TxCompleteSiaCb_t compl_sia_fptr,
 156                                 Amsg_TxCompleteCb_t compl_fptr, void* compl_inst_ptr);
 157 extern void Amsg_TxNotifyComplete(Ucs_AmsTx_Msg_t *self, Ucs_AmsTx_Result_t result, Ucs_AmsTx_Info_t info);
 158 extern void Amsg_TxFreeUnused(Ucs_AmsTx_Msg_t *self);
 159 extern void Amsg_TxUpdateInternalResult(Ucs_AmsTx_Msg_t *self, Amsg_TxIntStatus_t result);
 160 extern void Amsg_TxUpdateResult(Ucs_AmsTx_Msg_t *self, Ucs_MsgTxStatus_t result);
 161 extern Ucs_AmsTx_Result_t Amsg_TxGetResultCode(Ucs_AmsTx_Msg_t *self);
 162 extern Ucs_AmsTx_Info_t Amsg_TxGetResultInfo(Ucs_AmsTx_Msg_t *self);
 163 extern uint16_t Amsg_TxGetNextSegmCnt(Ucs_AmsTx_Msg_t *self);
 164 extern void Amsg_TxIncrementNextSegmCnt(Ucs_AmsTx_Msg_t *self);
 165 extern uint8_t Amsg_TxGetFollowerId(Ucs_AmsTx_Msg_t *self);
 166 extern void Amsg_TxSetFollowerId(Ucs_AmsTx_Msg_t *self, uint8_t id);
 167 extern void Amsg_TxReplaceDestinationAddr(Ucs_AmsTx_Msg_t *self, uint16_t new_destination);
 168 extern void Amsg_TxRemoveFromQueue(Ucs_AmsTx_Msg_t *self, CDlList *list_ptr);
 169 extern void Amsg_TxEnqueue(Ucs_AmsTx_Msg_t* self, CDlList* list_ptr);
 170 extern Ucs_AmsTx_Msg_t* Amsg_TxPeek(CDlList* list_ptr);
 171 extern Ucs_AmsTx_Msg_t* Amsg_TxDequeue(CDlList* list_ptr);
 172
 173 /* Rx */
 174 extern void Amsg_RxCtor(Ucs_AmsRx_Msg_t *self, void *info_ptr);
 175 extern void Amsg_RxBuildFromTx(Ucs_AmsRx_Msg_t *self, Ucs_AmsTx_Msg_t *tx_ptr, uint16_t source_address);
 176 extern void Amsg_RxHandleSetup(Ucs_AmsRx_Msg_t *self);
 177 extern void Amsg_RxHandleSetMemory(Ucs_AmsRx_Msg_t *self, uint8_t *mem_ptr, uint16_t mem_size, void *info_ptr);
 178 extern bool Amsg_RxHandleIsIdentical(Ucs_AmsRx_Msg_t *self, Msg_MostTel_t *tel_ptr);
 179 extern void Amsg_RxCopySignatureFromTel(Ucs_AmsRx_Msg_t *self, Msg_MostTel_t* src_ptr);
 180 extern void Amsg_RxCopySignatureToTel(Ucs_AmsRx_Msg_t *self, Msg_MostTel_t* target_ptr);
 181 extern void Amsg_RxCopyToPayload(Ucs_AmsRx_Msg_t *self, uint8_t data[], uint8_t data_sz);
 182 extern bool Amsg_RxAppendPayload(Ucs_AmsRx_Msg_t *self, Msg_MostTel_t* src_ptr);
 183 extern bool Amsg_RxHasExternalPayload(Ucs_AmsRx_Msg_t *self);
 184 extern void Amsg_RxEnqueue(Ucs_AmsRx_Msg_t* self, CDlList* list_ptr);
 185 extern void Amsg_RxSetGcMarker(Ucs_AmsRx_Msg_t* self, bool value);
 186 extern bool Amsg_RxGetGcMarker(Ucs_AmsRx_Msg_t* self);
 187 extern uint8_t Amsg_RxGetExpTelCnt(Ucs_AmsRx_Msg_t* self);
 188 /* Rx helpers */
 189 extern Ucs_AmsRx_Msg_t* Amsg_RxPeek(CDlList* list_ptr);
 190 extern Ucs_AmsRx_Msg_t* Amsg_RxDequeue(CDlList* list_ptr);
 191
 192 #ifdef __cplusplus
 193 }               /* extern "C" */
 194 #endif
 195
 196 #endif          /* UCS_AMSMESSAGE_H */
 197
 198 /*!
 199  * @}
 200  * \endcond
 201  */
 202
 203 /*------------------------------------------------------------------------------------------------*/
 204 /* End of file                                                                                    */
 205 /*------------------------------------------------------------------------------------------------*/
 206