summaryrefslogtreecommitdiffstats
path: root/mnsl/mns_lld_pb.h
blob: d1a087baac45491e913c4f5873f1c95d5392414e (plain)
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 3 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                                                                                    */
/*------------------------------------------------------------------------------------------------*/