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
|
/*
* MOST NetServices "Light" V3.2.7.0.1796 MultiInstance Patch
*
* Copyright (C) 2015 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 Declaration of the low-level driver interface
* \defgroup G_LLD Low-Level Driver
* \brief API functions to be used by the low-level driver.
* \details The MOST NetServices provides a certain set of functions which are only dedicated to the low-level driver.
* The low-level driver \em API is a set of functions which shall be used by the low-level driver.
* The low-level driver \em callbacks is a set of function that shall be implemented by the low-level driver.
* The low-level driver \em callbacks shall be assigned to the MOST NetServices initialization structure.
* During initialization MOST NetServices invokes the callback \ref Mns_Lld_Callbacks_t "start_fptr" and
* passes the low-level driver \em API as pointer to \ref Mns_Lld_Api_t.
* \mns_ic_started{ See also Getting Started with \ref P_UM_STARTED_LLD. }
* \mns_ic_examples{ See also <i>Examples</i>, section \ref P_UM_EXAMPLE_LLD_01, \ref P_UM_EXAMPLE_LLD_02 and \ref P_UM_EXAMPLE_LLD_03. }
* \ingroup G_MNS_API
* \defgroup G_LLD_TYPES Referred Types
* \brief Referred types used by the low-level driver interface
* \ingroup G_LLD
* \defgroup G_LLD_API Low-Level Driver API
* \brief Function pointers to be used by the low-level driver
* \ingroup G_LLD
*/
#ifndef MNS_LLD_PB_H
#define MNS_LLD_PB_H
/*------------------------------------------------------------------------------------------------*/
/* Includes */
/*------------------------------------------------------------------------------------------------*/
#include "mns_types_cfg.h"
#include "mns_memory_pb.h"
#ifdef __cplusplus
extern "C"
{
#endif
/*!
* \addtogroup G_LLD_TYPES
* @{
*/
/*------------------------------------------------------------------------------------------------*/
/* Structures */
/*------------------------------------------------------------------------------------------------*/
/*! \brief Tx message object providing the raw port message byte stream */
typedef struct Mns_Lld_TxMsg_
{
struct Mns_Lld_TxMsg_ *custom_next_msg_ptr;/*!< \brief Shall be used by the LLD implementation to queue messages for
* asynchronous transmission
* \details MOST NetServices will set this value to \c NULL since only
* single messages are forwarded to the LLD. Within the transmit function
* it is recommended that the LLD queues the message for asynchronous
* transmission. Despite a driver's transmit function might signal busy for
* a short term MOST NetServices might forward multiple messages for
* transmission. If a driver works asynchronously (interrupt driven) it
* can easily use this pointer build a queue of waiting messages.
* Nonetheless, it is important that \ref Mns_Lld_Api_t::tx_release_fptr
* "tx_release_fptr" is invoked for every message separately. The Interface
* between MOST NetServices and the LLD does only support single messages.
*/
Mns_Mem_Buffer_t *memory_ptr; /*!< \brief Points to the data buffer */
} Mns_Lld_TxMsg_t;
/*! \brief Rx message object pointing to the raw port message byte stream. */
typedef struct Mns_Lld_RxMsg_
{
uint8_t* data_ptr; /*!< \brief Points to a MOST NetServices allocated memory chunk. */
uint16_t data_size; /*!< \brief Size of the memory chunk in bytes. Valid values: 6..72. */
} Mns_Lld_RxMsg_t;
/*!
* @}
* \addtogroup G_LLD_API
* @{
*/
/*------------------------------------------------------------------------------------------------*/
/* Low-level driver API */
/*------------------------------------------------------------------------------------------------*/
/*! \brief Allocates an Rx message object
* \param inst_ptr Reference to internal MOST NetServices handler
* \param buffer_size The size in bytes of the received Rx message.
* Valid values: 6..72.
* \return The Rx message object or \c NULL if no message object is available. In the latter
* case the low-level driver can wait until Mns_Lld_RxMsgAvailableCb_t() is invoked.
* The low-level driver is allowed to pre-allocate Rx messages with the maximum size
* of 72 bytes. After writing received data into Mns_Lld_RxMsg_t::data_ptr the
* low-level driver must set Mns_Lld_RxMsg_t::data_size to the actual message size.
* \warning
* The function will also return \c NULL if the requested \c buffer_size exceeds the valid range.
* In such a case the MOST NetServices cannot guarantee that Mns_Lld_RxMsgAvailableCb_t() is
* called as expected. Received messages exceeding the valid range must be discarded by the LLD.
*/
typedef Mns_Lld_RxMsg_t* (*Mns_Lld_RxAllocateCb_t)(void *inst_ptr, uint16_t buffer_size);
/*! \brief Frees an unused Rx message object
* \param inst_ptr Reference to internal MOST NetServices handler
* \param msg_ptr Reference to the unused Rx message object
*/
typedef void (*Mns_Lld_RxFreeUnusedCb_t)(void *inst_ptr, Mns_Lld_RxMsg_t *msg_ptr);
/*! \brief Pass an Rx message to MOST NetServices
* \param inst_ptr Reference to internal MOST NetServices handler
* \param msg_ptr Reference to the Rx message object containing the received
* message.
*/
typedef void (*Mns_Lld_RxReceiveCb_t)(void *inst_ptr, Mns_Lld_RxMsg_t *msg_ptr);
/*! \brief Notifies that the LLD no longer needs to access the Tx message object
* \param inst_ptr Reference to internal MOST NetServices handler
* \param msg_ptr Reference to the Tx message object which is no longer accessed
* by the low-level driver
*/
typedef void (*Mns_Lld_TxReleaseCb_t)(void *inst_ptr, Mns_Lld_TxMsg_t *msg_ptr);
/*! \brief Initialization required for one communication channel (control or packet)
*/
typedef struct Mns_Lld_Api_
{
Mns_Lld_RxAllocateCb_t rx_allocate_fptr; /*!< \brief Allocates an Rx message object */
Mns_Lld_RxFreeUnusedCb_t rx_free_unused_fptr; /*!< \brief Frees an unused Rx message object */
Mns_Lld_RxReceiveCb_t rx_receive_fptr; /*!< \brief Pass an Rx message to MOST NetServices */
Mns_Lld_TxReleaseCb_t tx_release_fptr; /*!< \brief Notifies that the LLD no longer needs to access the Tx message object */
} Mns_Lld_Api_t;
/*!
* @}
* \addtogroup G_LLD
* @{
*/
/*------------------------------------------------------------------------------------------------*/
/* LLD interface functions */
/*------------------------------------------------------------------------------------------------*/
/*! \brief Notifies the LLD to start transmitting and receiving messages
* \param api_ptr Reference to MOST NetServices LLD interface
* \param ns_ptr Reference to internal MOST NetServices handler
*/
typedef void (*Mns_Lld_StartCb_t)(Mns_Lld_Api_t* api_ptr, void *ns_ptr, void *inst_ptr);
/*! \brief Notifies the LLD to stop/abort transmitting and receiving messages
* \details As soon as this function is called the low-level driver is not allowed
* to call any MOST NetServices function.
*/
typedef void (*Mns_Lld_StopCb_t)(void *inst_ptr);
/*! \brief Notifies the LLD to reset the INIC
* \details If this function is called the low-level driver is responsible to
* perform an INIC hardware reset.
*/
typedef void (*Mns_Lld_ResetInicCb_t)(void *inst_ptr);
/*! \brief Callback function which is invoked as soon as port message objects are available again.
* \details By implementing this callback function the low-level driver can avoid polling for
* Rx message objects. The low-level driver should wait for the function call as soon
* as Mns_Lld_RxAllocateCb_t() returns NULL. Only then it shall call those functions again.
*/
typedef void (*Mns_Lld_RxMsgAvailableCb_t)(void *inst_ptr);
/*! \brief Callback function which is invoked to transmit a single message to the INIC
* \param msg_ptr Reference to a single Tx message.
*/
typedef void (*Mns_Lld_TxTransmitCb_t)(Mns_Lld_TxMsg_t *msg_ptr, void *inst_ptr);
/*!
* @}
* \addtogroup G_LLD_TYPES
* @{
*/
/*! \brief Set of functions implemented by the low-level driver
*/
typedef struct Mns_Lld_Callbacks_
{
Mns_Lld_StartCb_t start_fptr; /*!< \brief Callback function to initialize the low-level driver and
* start the transmission and reception of messages */
Mns_Lld_StopCb_t stop_fptr; /*!< \brief Callback function to stop/abort the transmission and reception of messages */
Mns_Lld_RxMsgAvailableCb_t rx_available_fptr; /*!< \brief Callback function which is invoked as soon as Rx message objects are available again */
Mns_Lld_TxTransmitCb_t tx_transmit_fptr; /*!< \brief Callback function to transmit one or multiple messages to the INIC */
} Mns_Lld_Callbacks_t;
/*! @} */
#ifdef __cplusplus
} /* extern "C" */
#endif
#endif /* #ifndef MNS_LLD_PB_H */
/*------------------------------------------------------------------------------------------------*/
/* End of file */
/*------------------------------------------------------------------------------------------------*/
|
