summaryrefslogtreecommitdiffstats
path: root/ucs2-lib/inc/ucs_transceiver.h
blob: ca5cf68bc440df3efd0015306ecd6f7d420cbec2 (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
/*------------------------------------------------------------------------------------------------*/
/* UNICENS V2.1.0-3491                                                                            */
/* Copyright (c) 2017 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 2 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 class CTransceiver
 *
 * \cond UCS_INTERNAL_DOC
 * \addtogroup  G_TRCV
 * @{
 */

#ifndef UCS_TRANSCEIVER_H
#define UCS_TRANSCEIVER_H

/*------------------------------------------------------------------------------------------------*/
/* Includes                                                                                       */
/*------------------------------------------------------------------------------------------------*/
#include "ucs_message.h"
#include "ucs_pool.h"
#include "ucs_pmfifo.h"

#ifdef __cplusplus
extern "C"
{
#endif

/*------------------------------------------------------------------------------------------------*/
/* Types                                                                                          */
/*------------------------------------------------------------------------------------------------*/ 
/*! \brief   Assignable callback function which is invoked for message reception 
 *  \param   self    The instance
 *  \param   tel_ptr Reference to the message object
 */
typedef void (*Trcv_RxCompleteCb_t)(void *self, Msg_MostTel_t *tel_ptr);

/*! \brief   Assignable callback function which is invoked to filter Rx messages
 *  \details Filtering is a synchronous operation. Hence, it is not possible to keep a message
 *           object for delayed processing. The invoked function has to decide whether a 
 *           message shall be discarded and freed to the Rx pool. Therefore, it has to return 
 *           \c true. By returning \ false, the message will be received in the usual way.
 *  \param   self    The instance
 *  \param   tel_ptr Reference to the message object
 *  \return  Returns \c true to discard the message and free it to the pool (no-pass). Otherwise, returns 
 *           \c false (pass).
 */
typedef bool (*Trcv_RxFilterCb_t)(void *self, Msg_MostTel_t *tel_ptr);

/*------------------------------------------------------------------------------------------------*/
/* Macros                                                                                         */
/*------------------------------------------------------------------------------------------------*/
#define TRCV_SIZE_TX_POOL    10U                    /*!< \brief Number of messages in the message pool */

/*------------------------------------------------------------------------------------------------*/
/* Class CTransceiver                                                                             */
/*------------------------------------------------------------------------------------------------*/
/*! \brief   Class CTransceiver 
 *  \details Provides MOST message objects and communication methods to further classes
 */
typedef struct CTransceiver_
{
    CMessage             tx_msgs[TRCV_SIZE_TX_POOL];/*!< \brief Messages in message pool */
    CPool                tx_msg_pool;               /*!< \brief The message pool */
    uint16_t             tx_def_src;                /*!< \brief Default source address for Tx message object */
    void                *ucs_user_ptr;              /*!< \brief User reference that needs to be passed in every callback function */
    uint8_t              own_id;                    /*!< \brief ID of the transceiver required for tracing */
    CPmFifo             *fifo_ptr;                  /*!< \brief Reference to dedicated port message FIFO */

    Trcv_RxCompleteCb_t  rx_complete_fptr;          /*!< \brief Callback function which is invoked on 
                                                     *          message reception 
                                                     */
    void                *rx_complete_inst;          /*!< \brief Instance which is notified on 
                                                     *          message reception 
                                                     */
    Trcv_RxFilterCb_t    rx_filter_fptr;            /*!< \brief Callback function which is invoked 
                                                     *          to filter Rx messages
                                                     */
    void                *rx_filter_inst;            /*!< \brief Instance which is notified to
                                                     *          filter Rx messages
                                                     */
} CTransceiver;

/*------------------------------------------------------------------------------------------------*/
/* Methods                                                                                        */
/*------------------------------------------------------------------------------------------------*/
/* Constructor */
extern void Trcv_Ctor(CTransceiver *self, CPmFifo *fifo_ptr, uint16_t def_src_addr, void *ucs_user_ptr, uint8_t trace_id);
/* Tx */
extern Msg_MostTel_t* Trcv_TxAllocateMsg(CTransceiver *self, uint8_t size);
extern void Trcv_TxSendMsg(CTransceiver *self, Msg_MostTel_t *tel_ptr);
extern void Trcv_TxSendMsgExt(CTransceiver *self, Msg_MostTel_t *tel_ptr, Msg_TxStatusCb_t callback_fptr, void *inst_ptr);
extern void Trcv_TxSendMsgBypass(CTransceiver *self, Msg_MostTel_t *tel_ptr, Msg_TxStatusCb_t callback_fptr, void *inst_ptr);
extern void Trcv_TxReleaseMsg(Msg_MostTel_t *tel_ptr);
extern void Trcv_TxReuseMsg(Msg_MostTel_t *tel_ptr);
/* Rx */
extern void Trcv_RxAssignReceiver(CTransceiver *self, Trcv_RxCompleteCb_t callback_fptr, void *inst_ptr);
extern void Trcv_RxAssignFilter(CTransceiver *self, Trcv_RxFilterCb_t callback_fptr, void *inst_ptr);
extern void Trcv_RxReleaseMsg(CTransceiver *self, Msg_MostTel_t *tel_ptr);
extern void Trcv_RxOnMsgComplete(void *self, CMessage *tel_ptr);

#ifdef __cplusplus
}                                                   /* extern "C" */
#endif

#endif /* #ifndef UCS_TRANSCEIVER_H */

/*!
 * @}
 * \endcond
 */

/*------------------------------------------------------------------------------------------------*/
/* End of file                                                                                    */
/*------------------------------------------------------------------------------------------------*/