1 /*------------------------------------------------------------------------------------------------*/
2 /* UNICENS V2.1.0-3491 */
3 /* Copyright (c) 2017 Microchip Technology Germany II GmbH & Co. KG. */
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. */
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. */
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/>. */
18 /* You may also obtain this software under a propriety license from Microchip. */
19 /* Please contact Microchip for further information. */
20 /*------------------------------------------------------------------------------------------------*/
24 * \brief Internal header file of Application Message Classes
26 * \cond UCS_INTERNAL_DOC
27 * \addtogroup G_AMSMSG
31 #ifndef UCS_AMSMESSAGE_H
32 #define UCS_AMSMESSAGE_H
34 /*------------------------------------------------------------------------------------------------*/
36 /*------------------------------------------------------------------------------------------------*/
37 #include "ucs_ams_pb.h"
38 #include "ucs_message.h"
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))
52 /*------------------------------------------------------------------------------------------------*/
54 /*------------------------------------------------------------------------------------------------*/
55 /*! \brief Internal transmission result of an application message */
56 typedef enum Amsg_TxIntStatus_
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. */
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
69 typedef void (*Amsg_RxCompleteCb_t)(void* self, Ucs_AmsRx_Msg_t* msg_ptr);
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)
77 typedef void (*Amsg_TxCompleteCb_t)(Ucs_AmsTx_Msg_t* msg_ptr, Ucs_AmsTx_Result_t result, Ucs_AmsTx_Info_t info, void* self);
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
84 typedef void (*Amsg_TxCompleteSiaCb_t)(Ucs_AmsTx_Msg_t* msg_ptr, Ucs_AmsTx_Result_t result, Ucs_AmsTx_Info_t info);
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
90 typedef void (*Amsg_TxFreedCb_t)(void *owner_ptr, Ucs_AmsTx_Msg_t* msg_ptr);
92 /*------------------------------------------------------------------------------------------------*/
94 /*------------------------------------------------------------------------------------------------*/
95 /*! \brief Internal Tx message structure */
96 typedef struct Amsg_IntMsgTx_
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 */
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 */
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 */
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
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"
118 CDlNode node; /*!< \brief Node required for message pool */
120 Amsg_TxCompleteSiaCb_t complete_sia_fptr; /*!< \brief Single instance API Callback function which is invoked
121 * after transmission completed
123 Amsg_TxCompleteCb_t complete_fptr; /*!< \brief Callback function which is invoked after transmission
126 void *complete_inst_ptr; /*!< \brief Instance pointer which is required to invoke complete_fptr */
130 /*! \brief Internal Rx message structure */
131 typedef struct Amsg_IntMsgRx_
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 */
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 */
140 CDlNode node; /*!< \brief Node required for message pool */
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.
148 /*------------------------------------------------------------------------------------------------*/
150 /*------------------------------------------------------------------------------------------------*/
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);
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);
189 extern Ucs_AmsRx_Msg_t* Amsg_RxPeek(CDlList* list_ptr);
190 extern Ucs_AmsRx_Msg_t* Amsg_RxDequeue(CDlList* list_ptr);
196 #endif /* UCS_AMSMESSAGE_H */
203 /*------------------------------------------------------------------------------------------------*/
205 /*------------------------------------------------------------------------------------------------*/