ucs2-lib/inc/ucs_lld_pb.h

   1 /*------------------------------------------------------------------------------------------------*/
   2 /* UNICENS V2.1.0-3491                                                                            */
   3 /* Copyright (c) 2017 Microchip Technology Germany II GmbH & Co. KG.                              */
   4 /*                                                                                                */
   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.                                                            */
   9 /*                                                                                                */
  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.                                                   */
  14 /*                                                                                                */
  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/>.                          */
  17 /*                                                                                                */
  18 /* You may also obtain this software under a propriety license from Microchip.                    */
  19 /* Please contact Microchip for further information.                                              */
  20 /*------------------------------------------------------------------------------------------------*/
  21
  22 /*!
  23  * \file
  24  * \brief       Declaration of the low-level driver interface
  25  *
  26  * \addtogroup  G_UCS_LLD
  27  * @{
  28  * \details     UNICENS provides a certain set of functions which are only dedicated to the low-level driver.
  29  *              The low-level driver \em API is a set of functions which shall be used by the low-level driver.
  30  *              The low-level driver \em callbacks is a set of function that shall be implemented by the low-level driver.
  31  *              The low-level driver \em callbacks shall be assigned to the UNICENS initialization structure.
  32  *              During initialization UNICENS invokes the callback \ref Ucs_Lld_Callbacks_t "start_fptr" and
  33  *              passes the low-level driver \em API as pointer to \ref Ucs_Lld_Api_t.
  34  * <!--
  35  *              \mns_ic_started{ See also Getting Started with \ref P_UM_STARTED_LLD. }
  36  *              \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. }
  37  * -->
  38  * @}
  39  */
  40
  41 #ifndef UCS_LLD_PB_H
  42 #define UCS_LLD_PB_H
  43
  44 /*------------------------------------------------------------------------------------------------*/
  45 /* Includes                                                                                       */
  46 /*------------------------------------------------------------------------------------------------*/
  47 #include "ucs_types_cfg.h"
  48 #include "ucs_memory_pb.h"
  49
  50 #ifdef __cplusplus
  51 extern "C"
  52 {
  53 #endif
  54
  55 /*!
  56  * \addtogroup  G_UCS_LLD_TYPES
  57  * @{
  58  */
  59
  60 /*------------------------------------------------------------------------------------------------*/
  61 /* Structures                                                                                     */
  62 /*------------------------------------------------------------------------------------------------*/
  63 /*! \brief  Tx message object providing the raw port message byte stream */
  64 typedef struct Ucs_Lld_TxMsg_
  65 {
  66     struct Ucs_Lld_TxMsg_ *custom_next_msg_ptr;/*!< \brief     Shall be used by the LLD implementation to queue messages for
  67                                                 *              asynchronous transmission
  68                                                 *   \details   UNICENS will set this value to \c NULL since only
  69                                                 *              single messages are forwarded to the LLD. Within the transmit function
  70                                                 *              it is recommended that the LLD queues the message for asynchronous
  71                                                 *              transmission. Despite a driver's transmit function might signal busy for
  72                                                 *              a short term the UNICENS library might forward multiple messages for
  73                                                 *              transmission. If a driver works asynchronously (interrupt driven) it
  74                                                 *              can easily use this pointer build a queue of waiting messages.
  75                                                 *              Nonetheless, it is important that \ref Ucs_Lld_Api_t::tx_release_fptr
  76                                                 *              "tx_release_fptr" is invoked for every message separately. The Interface
  77                                                 *              between the UNICENS library and the LLD does only support single messages.
  78                                                 */
  79     Ucs_Mem_Buffer_t *memory_ptr;              /*!< \brief     Points to the data buffer */
  80
  81 } Ucs_Lld_TxMsg_t;
  82
  83 /*! \brief  Rx message object pointing to the raw port message byte stream. */
  84 typedef struct Ucs_Lld_RxMsg_
  85 {
  86     uint8_t*        data_ptr;       /*!< \brief Points to a UNICENS allocated memory chunk. */
  87     uint16_t        data_size;      /*!< \brief Size of the memory chunk in bytes. Valid values: 6..72. */
  88
  89 } Ucs_Lld_RxMsg_t;
  90
  91 /*!
  92  * @}
  93  * \addtogroup  G_UCS_LLD_API
  94  * @{
  95  */
  96
  97 /*------------------------------------------------------------------------------------------------*/
  98 /* Low-level driver API                                                                           */
  99 /*------------------------------------------------------------------------------------------------*/
 100 /*! \brief  Allocates an Rx message object
 101  *  \param  inst_ptr    Reference to an internal UNICENS handler
 102  *  \param  buffer_size The size in bytes of the received Rx message.
 103  *                      Valid values: 6..72.
 104  *  \return The Rx message object or \c NULL if no message object is available. In the latter
 105  *          case the low-level driver can wait until Ucs_Lld_RxMsgAvailableCb_t() is invoked.
 106  *          The low-level driver is allowed to pre-allocate Rx messages with the maximum size
 107  *          of 72 bytes. After writing received data into Ucs_Lld_RxMsg_t::data_ptr the
 108  *          low-level driver must set Ucs_Lld_RxMsg_t::data_size to the actual message size.
 109  *          \warning
 110  *          The function will also return \c NULL if the requested \c buffer_size exceeds the valid range.
 111  *          In such a case the UNICENS cannot guarantee that Ucs_Lld_RxMsgAvailableCb_t() is
 112  *          called as expected. Received messages exceeding the valid range must be discarded by the LLD.
 113  */
 114 typedef Ucs_Lld_RxMsg_t* (*Ucs_Lld_RxAllocateCb_t)(void *inst_ptr, uint16_t buffer_size);
 115
 116 /*! \brief  Frees an unused Rx message object
 117  *  \param  inst_ptr    Reference to internal UNICENS handler
 118  *  \param  msg_ptr     Reference to the unused Rx message object
 119  */
 120 typedef void (*Ucs_Lld_RxFreeUnusedCb_t)(void *inst_ptr, Ucs_Lld_RxMsg_t *msg_ptr);
 121
 122 /*! \brief  Pass an Rx message to UNICENS
 123  *  \param  inst_ptr    Reference to internal UNICENS handler
 124  *  \param  msg_ptr     Reference to the Rx message object containing the received
 125  *                      message.
 126  */
 127 typedef void (*Ucs_Lld_RxReceiveCb_t)(void *inst_ptr, Ucs_Lld_RxMsg_t *msg_ptr);
 128
 129 /*! \brief  Notifies that the LLD no longer needs to access the Tx message object
 130  *  \param  inst_ptr    Reference to internal UNICENS handler
 131  *  \param  msg_ptr     Reference to the Tx message object which is no longer accessed
 132  *                      by the low-level driver
 133  */
 134 typedef void (*Ucs_Lld_TxReleaseCb_t)(void *inst_ptr, Ucs_Lld_TxMsg_t *msg_ptr);
 135
 136 /*! \brief   Initialization required for one communication channel (control or packet)
 137  */
 138 typedef struct Ucs_Lld_Api_
 139 {
 140     Ucs_Lld_RxAllocateCb_t   rx_allocate_fptr;     /*!< \brief  Allocates an Rx message object */
 141     Ucs_Lld_RxFreeUnusedCb_t rx_free_unused_fptr;  /*!< \brief  Frees an unused Rx message object */
 142     Ucs_Lld_RxReceiveCb_t    rx_receive_fptr;      /*!< \brief  Pass an Rx message to the UNICENS library */
 143     Ucs_Lld_TxReleaseCb_t    tx_release_fptr;      /*!< \brief  Notifies that the LLD no longer needs to access the Tx message object */
 144
 145 } Ucs_Lld_Api_t;
 146
 147 /*!
 148  * @}
 149  * \addtogroup  G_UCS_LLD
 150  * @{
 151  */
 152
 153 /*------------------------------------------------------------------------------------------------*/
 154 /* LLD interface functions                                                                        */
 155 /*------------------------------------------------------------------------------------------------*/
 156
 157 /*! \brief      Notifies the LLD to start transmitting and receiving messages
 158  *  \param      api_ptr         Reference to UNICENS LLD interface
 159  *  \param      inst_ptr        Reference to internal UNICENS handler
 160  *  \param      lld_user_ptr    User defined pointer which is provided in \ref Ucs_Lld_Callbacks_t structure.
 161  */
 162 typedef void (*Ucs_Lld_StartCb_t)(Ucs_Lld_Api_t* api_ptr, void *inst_ptr, void *lld_user_ptr);
 163
 164 /*! \brief      Notifies the LLD to stop/abort transmitting and receiving messages
 165  *  \details    As soon as this function is called the low-level driver is not allowed
 166  *              to call any UNICENS API function.
 167  *  \param      lld_user_ptr    User defined pointer which is provided in \ref Ucs_Lld_Callbacks_t structure.
 168  */
 169 typedef void (*Ucs_Lld_StopCb_t)(void *lld_user_ptr);
 170
 171 /*! \brief      Notifies the LLD to reset the INIC
 172  *  \details    If this function is called the low-level driver is responsible to
 173  *              perform an INIC hardware reset.
 174  *  \param      lld_user_ptr    User defined pointer which is provided in \ref Ucs_Lld_Callbacks_t structure.
 175  */
 176 typedef void (*Ucs_Lld_ResetInicCb_t)(void *lld_user_ptr);
 177
 178 /*! \brief      Callback function which is invoked as soon as port message objects are available again.
 179  *  \details    By implementing this callback function the low-level driver can avoid polling for
 180  *              Rx message objects. The low-level driver should wait for the function call as soon
 181  *              as Ucs_Lld_RxAllocateCb_t() returns NULL. Only then it shall call those functions again.
 182  *  \param      lld_user_ptr    User defined pointer which is provided in \ref Ucs_Lld_Callbacks_t structure.
 183  */
 184 typedef void (*Ucs_Lld_RxMsgAvailableCb_t)(void *lld_user_ptr);
 185
 186 /*! \brief      Callback function which is invoked to transmit a single message to the INIC
 187  *  \param      msg_ptr         Reference to a single Tx message.
 188  *  \param      lld_user_ptr    User defined pointer which is provided in \ref Ucs_Lld_Callbacks_t structure.
 189  */
 190 typedef void (*Ucs_Lld_TxTransmitCb_t)(Ucs_Lld_TxMsg_t *msg_ptr, void *lld_user_ptr);
 191
 192 /*!
 193  * @}
 194  * \addtogroup  G_UCS_LLD_TYPES
 195  * @{
 196  */
 197
 198 /*! \brief  Set of functions implemented by the low-level driver
 199  */
 200 typedef struct Ucs_Lld_Callbacks_
 201 {
 202     void                      *lld_user_ptr;       /*!< \brief    Optional pointer that is passed when invoking a callback function which is assigned in Ucs_Lld_Callbacks_t. */
 203     Ucs_Lld_StartCb_t          start_fptr;         /*!< \brief    Callback function to initialize the low-level driver and
 204                                                     *             start the transmission and reception of messages */
 205     Ucs_Lld_StopCb_t           stop_fptr;          /*!< \brief    Callback function to stop/abort the transmission and reception of messages */
 206     Ucs_Lld_RxMsgAvailableCb_t rx_available_fptr;  /*!< \brief    Callback function which is invoked as soon as Rx message objects are available again */
 207     Ucs_Lld_TxTransmitCb_t     tx_transmit_fptr;   /*!< \brief    Callback function to transmit one or multiple messages to the INIC */
 208
 209 } Ucs_Lld_Callbacks_t;
 210
 211 /*! @} */
 212
 213 #ifdef __cplusplus
 214 }                                                   /* extern "C" */
 215 #endif
 216
 217 #endif /* #ifndef UCS_LLD_PB_H */
 218
 219 /*------------------------------------------------------------------------------------------------*/
 220 /* End of file                                                                                    */
 221 /*------------------------------------------------------------------------------------------------*/
 222