ucs2-lib/inc/ucs_pmchannel.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 Internal header file of Port Message Channel
  25  *
  26  * \cond UCS_INTERNAL_DOC
  27  * \addtogroup G_PMC
  28  * @{
  29  */
  30
  31 #ifndef UCS_PMCHANNEL_H
  32 #define UCS_PMCHANNEL_H
  33
  34 /*------------------------------------------------------------------------------------------------*/
  35 /* Includes                                                                                       */
  36 /*------------------------------------------------------------------------------------------------*/
  37 #include "ucs_rules.h"
  38 #include "ucs_lld_pb.h"
  39 #include "ucs_lldpool.h"
  40 #include "ucs_pool.h"
  41 #include "ucs_base.h"
  42 #include "ucs_message.h"
  43 #include "ucs_pmp.h"
  44
  45 #ifdef __cplusplus
  46 extern "C"
  47 {
  48 #endif
  49
  50 /*------------------------------------------------------------------------------------------------*/
  51 /* Macros                                                                                         */
  52 /*------------------------------------------------------------------------------------------------*/
  53 #define PMCH_POOL_SIZE_RX_MIN       10U  /*!< \brief Minimal size of Rx pool which is shared by all FIFOs */
  54 #define PMCH_POOL_SIZE_RX_OPT       35U  /*!< \brief Optimal size of Rx pool which is shared by all FIFOs */
  55
  56 #define PMCH_MCM_CREDITS_OPT        21U  /*!< \brief Optimal number of credits configured for MCM FIFO */
  57 #define PMCH_MCM_THRESHOLD_OPT      8U   /*!< \brief Optimal threshold configured for MCM FIFO */
  58
  59 #define PMCH_FIFO_CREDITS_OPT       5U   /*!< \brief Optimal number of credits configured for conventional FIFOs */
  60 #define PMCH_FIFO_THRESHOLD_OPT     4U   /*!< \brief Optimal threshold configured for conventional FIFO */
  61
  62 #define PMCH_FIFO_CREDITS_MIN       3U   /*!< \brief Minimal number of credits configured for conventional FIFOs */
  63 #define PMCH_FIFO_THRESHOLD_MIN     2U   /*!< \brief Minimal threshold configured for conventional FIFO */
  64
  65 /* required rules */
  66 #if defined(MNSL_FOOTPRINT_TINY) && defined(MNSL_CHANNEL_POOL_SIZE_RX)
  67 # error Forbidden combination of macros MNSL_FOOTPRINT_TINY and MNSL_CHANNEL_POOL_SIZE_RX
  68 #endif
  69
  70 #ifdef MNSL_CHANNEL_POOL_SIZE_RX
  71 # if (MNSL_CHANNEL_POOL_SIZE_RX < PMCH_POOL_SIZE_RX_MIN)
  72 #   error MNSL_CHANNEL_POOL_SIZE_RX must be at least 10
  73 # endif
  74 #endif
  75
  76 /*! \def     MNSL_CHANNEL_POOL_SIZE_RX
  77  *  \brief   MNSL configuration that defines the number of pre-allocated Rx messages which are shared by all FIFOs.
  78  *           Valid values: 35...65535. Default value: 35.
  79  *
  80  *  \def     PMCH_POOL_SIZE_RX
  81  *  \brief   Defines the number of pre-allocated Rx messages which are shared by all FIFOs.
  82  */
  83 #ifdef MNSL_FOOTPRINT_TINY
  84 # define PMCH_POOL_SIZE_RX          (PMCH_POOL_SIZE_RX_MIN)
  85 # define PMCH_MCM_CREDITS           (PMCH_FIFO_CREDITS_MIN)
  86 # define PMCH_FIFO_CREDITS          (PMCH_FIFO_CREDITS_MIN)
  87 # define PMCH_MCM_THRESHOLD         (PMCH_FIFO_THRESHOLD_MIN)
  88 # define PMCH_FIFO_THRESHOLD        (PMCH_FIFO_THRESHOLD_MIN)
  89 # define MNSL_CHANNEL_POOL_SIZE_RX  (PMCH_POOL_SIZE_RX_MIN)
  90 #elif defined MNSL_CHANNEL_POOL_SIZE_RX
  91 # define PMCH_POOL_SIZE_RX          ((uint16_t)MNSL_CHANNEL_POOL_SIZE_RX)
  92 # define PMCH_MCM_CREDITS           (PMCH_FIFO_CREDITS_MIN)
  93 # define PMCH_FIFO_CREDITS          (PMCH_FIFO_CREDITS_MIN)
  94 # define PMCH_MCM_THRESHOLD         (PMCH_FIFO_THRESHOLD_MIN)
  95 # define PMCH_FIFO_THRESHOLD        (PMCH_FIFO_THRESHOLD_MIN)
  96 #else
  97 # define PMCH_POOL_SIZE_RX          (PMCH_POOL_SIZE_RX_OPT)
  98 # define PMCH_MCM_CREDITS           (PMCH_MCM_CREDITS_OPT)
  99 # define PMCH_FIFO_CREDITS          (PMCH_FIFO_CREDITS_OPT)
 100 # define PMCH_MCM_THRESHOLD         (PMCH_MCM_THRESHOLD_OPT)
 101 # define PMCH_FIFO_THRESHOLD        (PMCH_FIFO_THRESHOLD_OPT)
 102 # define MNSL_CHANNEL_POOL_SIZE_RX  (PMCH_POOL_SIZE_RX_OPT)
 103 #endif
 104
 105 /*------------------------------------------------------------------------------------------------*/
 106 /* Types                                                                                          */
 107 /*------------------------------------------------------------------------------------------------*/
 108 typedef void (*Pmch_OnRxMsg_t)(void *fifo_ptr, CMessage *msg_ptr);
 109 typedef void (*Pmch_OnTxRelease_t)(void *fifo_ptr, Ucs_Lld_TxMsg_t *handle_ptr);
 110
 111 /*! \brief  Initialization structure of the Base Module. */
 112 typedef struct Pmch_InitData_
 113 {
 114     void *ucs_user_ptr;         /*!< \brief User reference that needs to be passed in every callback function */
 115     Ucs_Lld_Callbacks_t lld_iface;              /*!< \brief LLD callback functions */
 116     Pmch_OnTxRelease_t tx_release_fptr;         /*!< \brief Callback which releases a FIFO dedicated LLD buffer */
 117
 118 } Pmch_InitData_t;
 119
 120 /*! \brief  Combination of callback and instance for a receiving FIFO */
 121 typedef struct Pmch_Receiver_
 122 {
 123     Pmch_OnRxMsg_t rx_fptr;                     /*!< \brief Reference to an Rx callback function */
 124     void *inst_ptr;                             /*!< \brief Reference to the instance which shall be
 125                                                  *          passed to the callback function */
 126 } Pmch_Receiver_t;
 127
 128 /*------------------------------------------------------------------------------------------------*/
 129 /* Class attributes                                                                               */
 130 /*------------------------------------------------------------------------------------------------*/
 131 /*! \brief   Structure of a PMS object */
 132 typedef struct CPmChannel_
 133 {
 134     Pmch_InitData_t init_data;                      /*!< \brief Copy of initialization data */
 135
 136     Lld_IntRxMsg_t  lld_rx_msgs[PMCH_POOL_SIZE_RX]; /*!< \brief Pre-allocated LLD Rx message objects */
 137     CMessage        rx_msgs[PMCH_POOL_SIZE_RX];     /*!< \brief Pre-allocated Rx message objects */
 138     CPool           rx_msgs_pool;                   /*!< \brief Pre-allocated Rx message pool */
 139     bool            rx_trigger_available;           /*!< \brief Triggers LLD callback function if a buffer
 140                                                      *          is available again.
 141                                                      */
 142     bool            lld_active;                     /*!< \brief Determines whether the LLD is running */
 143     Ucs_Lld_Api_t   ucs_iface;                      /*!< \brief PMS function pointers */
 144
 145     Pmch_Receiver_t receivers[PMP_MAX_NUM_FIFOS];   /*!< \brief Registered FIFOs for Rx */
 146
 147 } CPmChannel;
 148
 149
 150 /*------------------------------------------------------------------------------------------------*/
 151 /* Class methods                                                                                  */
 152 /*------------------------------------------------------------------------------------------------*/
 153 /* component creation */
 154 extern void Pmch_Ctor(CPmChannel *self, const Pmch_InitData_t *init_ptr);
 155 extern void Pmch_Initialize(CPmChannel *self);
 156 extern void Pmch_Uninitialize(CPmChannel *self);
 157 extern void Pmch_RegisterReceiver(CPmChannel *self, Pmp_FifoId_t fifo_id, Pmch_OnRxMsg_t rx_fptr, void *inst_ptr);
 158 extern void Pmch_Transmit(CPmChannel *self, Ucs_Lld_TxMsg_t *msg_ptr);
 159 extern void Pmch_ReturnRxToPool(void *self, CMessage *msg_ptr);
 160
 161 #ifdef __cplusplus
 162 }                                               /* extern "C" */
 163 #endif
 164
 165 #endif                                          /* UCS_PMCHANNEL_H */
 166
 167 /*!
 168  * @}
 169  * \endcond
 170  */
 171
 172 /*------------------------------------------------------------------------------------------------*/
 173 /* End of file                                                                                    */
 174 /*------------------------------------------------------------------------------------------------*/
 175