diff options
Diffstat (limited to 'mnsl/mns_lld_pb.h')
| -rw-r--r-- | mnsl/mns_lld_pb.h | 221 |
1 files changed, 221 insertions, 0 deletions
diff --git a/mnsl/mns_lld_pb.h b/mnsl/mns_lld_pb.h new file mode 100644 index 0000000..d1a087b --- /dev/null +++ b/mnsl/mns_lld_pb.h @@ -0,0 +1,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 */ +/*------------------------------------------------------------------------------------------------*/ + |