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