ucs2-lib/inc/ucs_class.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 UNICENS API class
  25  * \cond UCS_INTERNAL_DOC
  26  * \addtogroup G_UCS_CLASS
  27  * @{
  28  */
  29 #ifndef UCS_CLASS_H
  30 #define UCS_CLASS_H
  31
  32 /*------------------------------------------------------------------------------------------------*/
  33 /* Includes                                                                                       */
  34 /*------------------------------------------------------------------------------------------------*/
  35 #include "ucs_class_pb.h"
  36 #include "ucs_base.h"
  37 #include "ucs_pmfifo.h"
  38 #include "ucs_pmchannel.h"
  39 #include "ucs_pmevent.h"
  40 #include "ucs_transceiver.h"
  41 #include "ucs_factory.h"
  42 #include "ucs_rtm.h"
  43 #include "ucs_epm.h"
  44 #include "ucs_net.h"
  45 #include "ucs_attach.h"
  46 #include "ucs_nodedis.h"
  47 #include "ucs_bc_diag.h"
  48 #include "ucs_sys_diag.h"
  49 #include "ucs_prog.h"
  50 #include "ucs_exc.h"
  51 #include "ucs_smm.h"
  52 #include "ucs_amd.h"
  53 #include "ucs_cmd.h"
  54 #include "ucs_mgr.h"
  55 #include "ucs_nodeobserver.h"
  56
  57 #ifdef __cplusplus
  58 extern "C"
  59 {
  60 #endif
  61
  62 /*------------------------------------------------------------------------------------------------*/
  63 /* Types                                                                                          */
  64 /*------------------------------------------------------------------------------------------------*/
  65 /*! \brief   Assignable callback function which is invoked to filter Rx messages
  66  *  \details Filtering is a synchronous operation. Hence, it is not possible to keep a message
  67  *           object for delayed processing. The invoked function has to decide whether a
  68  *           message shall be discarded and freed to the Rx pool. Therefore, it has to return
  69  *           \c true. By returning \ false, the message will be received in the usual way.
  70  *  \param   tel_ptr  Reference to the message object
  71  *  \param   user_ptr User reference provided in \ref Ucs_InitData_t "Ucs_InitData_t::user_ptr"
  72  *  \return  Returns \c true to discard the message and free it to the pool (no-pass). Otherwise, returns
  73  *           \c false (pass).
  74  */
  75 typedef bool (*Ucs_RxFilterCb_t)(Msg_MostTel_t *tel_ptr, void *user_ptr);
  76
  77 /*! \brief This structure holds instance and related parameters of the base component */
  78 typedef struct Ucs_GeneralData_
  79 {
  80     /*! \brief Instance of the Base component */
  81     CBase base;
  82     /*! \brief Application callback to request UNICENS service calls */
  83     Ucs_RequestServiceCb_t request_service_fptr;
  84     /*! \brief Observer to proxy callback request_service_fptr() */
  85     CSingleObserver service_request_obs;
  86     /*! \brief Application callback to report general errors */
  87     Ucs_ErrorCb_t general_error_fptr;
  88     /*! \brief Observer to proxy callback general_error_fptr() */
  89     CSingleObserver general_error_obs;
  90     /*! \brief Application callback to request the current tick count value */
  91     Ucs_GetTickCountCb_t get_tick_count_fptr;
  92     /*! \brief Observer to proxy callback get_tick_count_fptr() */
  93     CSingleObserver get_tick_count_obs;
  94     /*! \brief Application callback to start the application timer needed for UNICENS event triggered service call. */
  95     Ucs_SetAppTimerCb_t set_application_timer_fptr;
  96     /*! \brief Observer to proxy callback set_application_timer_fptr() */
  97     CSingleObserver set_application_timer_obs;
  98
  99 } Ucs_GeneralData_t;
 100
 101 /*! \brief This structure holds the reference to the local FBlock INIC instance and related parameters */
 102 typedef struct Ucs_InicData_
 103 {
 104     /*! \brief Reference to the local Instance of the FBlock INIC component */
 105     CInic* local_inic;
 106     /*! \brief Instance of the Attach service */
 107     CAttachService attach;
 108     /*! \brief Observer to proxy callback power_state_fptr() */
 109     CObserver device_status_obs;
 110     /*! \brief The last known power state, required since no masked observer is available */
 111     Ucs_Inic_PowerState_t power_state;
 112
 113 } Ucs_InicData_t;
 114
 115 /*! \brief This structure holds the Resources Management callback functions */
 116 typedef struct Ucs_UcsXrm_
 117 {
 118     /*! \brief Callback function that reports streaming-related information for the MOST Network
 119      *         Port, including the state of the port and available streaming bandwidth.
 120      */
 121     Ucs_Xrm_Most_PortStatusCb_t most_port_status_fptr;
 122     /*! \brief Observer to proxy callback most_port_status_fptr() */
 123     CObserver most_port_status_obs;
 124
 125 } Ucs_UcsXrm_t;
 126
 127 /*! \brief This structure holds the Network Management instance and related parameters */
 128 typedef struct Ucs_NetData_
 129 {
 130     /*! \brief Instance of the Network Management */
 131     CNetworkManagement inst;
 132     /*! \brief Application callback for NetworkStartup() */
 133     Ucs_StdResultCb_t startup_fptr;
 134     /*! \brief Observer to proxy callback startup_fptr() */
 135     CSingleObserver startup_obs;
 136     /*! \brief Application callback for NetworkShutdown() */
 137     Ucs_StdResultCb_t shutdown_fptr;
 138     /*! \brief Observer to proxy callback shutdown_fptr() */
 139     CSingleObserver shutdown_obs;
 140     /*! \brief Application callback for NetworkForceNotAvailable() */
 141     Ucs_StdResultCb_t force_na_fptr;
 142     /*! \brief Observer to proxy callback force_na_fptr() */
 143     CSingleObserver force_na_obs;
 144     /*! \brief Application callback for NetworkFrameCounterGet() */
 145     Ucs_Network_FrameCounterCb_t frame_counter_fptr;
 146     /*! \brief Observer to proxy callback frame_counter_fptr() */
 147     CSingleObserver frame_counter_obs;
 148     /*! \brief Application callback to report network status */
 149     Ucs_Network_StatusCb_t status_fptr;
 150     /*! \brief Observer to proxy callback status_fptr() */
 151     CMaskedObserver status_obs;
 152 #if 0
 153     /*! \brief Application callback for NetworkForceNotAvailable() */
 154     Ucs_StdResultCb_t force_na_fptr;
 155     /*! \brief Observer to proxy callback force_na_fptr() */
 156     CSingleObserver force_na_obs;
 157 #endif
 158
 159 } Ucs_NetData_t;
 160
 161 #if 0
 162 /*! \brief This structure holds attach process related parameters */
 163 typedef struct Ucs_AtsData_
 164 {
 165     /*! \brief Instance of the Attach service */
 166     CAttachService inst;
 167     /*! \brief Function pointer to start the attach process */
 168     /* Ucs_StartAttachCb_t start_attach_fptr; */
 169     /*! \brief Reference to instance used during the attach process */
 170     /*void *attach_inst_ptr;*/
 171
 172 } Ucs_AtsData_t;
 173 #endif
 174
 175 typedef struct Ucs_MsgData_
 176 {
 177     /*! \brief The MCM FIFO */
 178     CPmFifo mcm_fifo;
 179     /*! \brief The MCM communication module */
 180     CTransceiver mcm_transceiver;
 181     /*! \brief Application message distributor */
 182     CAmd amd;
 183     /*! \brief Memory allocator required for the application message service */
 184     Ams_MemAllocator_t ams_allocator;
 185     /*! \brief Application message pool */
 186     CAmsMsgPool ams_pool;
 187     /*! \brief Application message service */
 188     CAms ams;
 189     /*! \brief Static memory management */
 190     CStaticMemoryManager smm;
 191     /*! \brief Observer to proxy callback tx_message_freed_fptr() */
 192     CObserver ams_tx_freed_obs;
 193     /*! \brief Signals that tx_message_freed_fptr() must be called as soon as
 194      *         a Tx message object is freed the next time.
 195      */
 196     bool ams_tx_alloc_failed;
 197     /*! \brief Command Interpreter */
 198     CCmd cmd;
 199
 200 } Ucs_MsgData_t;
 201
 202
 203 /*------------------------------------------------------------------------------------------------*/
 204 /* Internal Class                                                                                 */
 205 /*------------------------------------------------------------------------------------------------*/
 206 /*! \brief The class CUcs representing the UNICENS API */
 207 typedef struct CUcs_
 208 {
 209     /*! \brief Stores the instance id, which is generated by Ucs_CreateInstance() */
 210     uint8_t ucs_inst_id;
 211     /*! \brief User reference that needs to be passed in every callback function */
 212     void *ucs_user_ptr;
 213     /*! \brief Backup of initialization data */
 214     Ucs_InitData_t init_data;
 215     /*! \brief Stores the init result callback function */
 216     Ucs_InitResultCb_t init_result_fptr;
 217     /*! \brief Observer to proxy callback init_result_fptr() */
 218     CSingleObserver init_result_obs;
 219     /*! \brief Stores the result callback function for Ucs_Stop() */
 220     Ucs_StdResultCb_t uninit_result_fptr;
 221     /*! \brief Observer to proxy callback uninit_result_fptr() */
 222     CMaskedObserver uninit_result_obs;
 223     /*! \brief General data required for base component */
 224     Ucs_GeneralData_t general;
 225
 226     /*! \brief Instance of port message channel (service) */
 227     CPmChannel pmch;
 228     /*! \brief Instance of port message event handler */
 229     CPmEventHandler pme;
 230     /*! \brief Instance of port message FIFOs */
 231     CPmFifos fifos;
 232     /*! \brief The ICM FIFO */
 233     CPmFifo icm_fifo;
 234     /*! \brief The RCM FIFO */
 235     CPmFifo rcm_fifo;
 236     /*! \brief The ICM communication module */
 237     CTransceiver icm_transceiver;
 238     /*! \brief The RCM communication module */
 239     CTransceiver rcm_transceiver;
 240     /*! \brief Factory component instance */
 241     CFactory factory;
 242     /*! \brief INIC Resources Management callbacks functions */
 243     Ucs_UcsXrm_t xrm;
 244     /*!< \brief The XRM Pool instance */
 245     CXrmPool xrmp;
 246     /*!< \brief The Routes Management instance */
 247     CRouteManagement rtm;
 248     /*!< \brief The EndPoints Management instance */
 249     CEndpointManagement epm;
 250     /*! \brief FBlock INIC instance and related parameters */
 251     Ucs_InicData_t inic;
 252     /*! \brief Network Management instance and related parameters */
 253     Ucs_NetData_t net;
 254     /*! \brief FBlock EXC component instance and related parameters */
 255     CExc exc;
 256     /*! \brief System diagnosis component instance and related parameters */
 257     CSysDiag sys_diag;
 258     /*! \brief Node Discovery instance and related parameters */
 259     CNodeDiscovery nd;
 260     /*! \brief BackChannel Diagnosis instance and related parameters */
 261     CBackChannelDiag bcd;
 262     /*! \brief Programming Interface instance and parameters */
 263     CProgramming prg;
 264     /*! \brief Application Message related Data */
 265     Ucs_MsgData_t msg;
 266     /*! \brief The manager instance */
 267     CManager mgr;
 268     /*! \brief The node observer instance */
 269     CNodeObserver nobs;
 270     /*! \brief Filter callback required for unit testing*/
 271     Ucs_RxFilterCb_t rx_filter_fptr;
 272
 273     /*! \brief Is \c true if initialization completed successfully */
 274     bool init_complete;
 275
 276 } CUcs;
 277
 278 /*------------------------------------------------------------------------------------------------*/
 279 /* Unit tests only                                                                                */
 280 /*------------------------------------------------------------------------------------------------*/
 281 extern void Ucs_AssignRxFilter(Ucs_Inst_t *self, Ucs_RxFilterCb_t callback_fptr);
 282
 283 #ifdef __cplusplus
 284 }   /* extern "C" */
 285 #endif
 286
 287 #endif /* UCS_CLASS_H */
 288
 289 /*!
 290  * @}
 291  * \endcond
 292  */
 293
 294 /*------------------------------------------------------------------------------------------------*/
 295 /* End of file                                                                                    */
 296 /*------------------------------------------------------------------------------------------------*/
 297