1 /*
2  * Copyright (C) 2017-2020 Alibaba Group Holding Limited
3  */
4 
5 /******************************************************************************
6  * @file     drv/mbox.h
7  * @brief    Header File for MBOX Driver
8  * @version  V1.0
9  * @date     5. Apr 2020
10  * @model    mbox
11  ******************************************************************************/
12 
13 #ifndef _DRV_MBOX_H_
14 #define _DRV_MBOX_H_
15 
16 #include <drv/common.h>
17 
18 #ifdef __cplusplus
19 extern "C" {
20 #endif
21 
22 typedef enum {
23     MBOX_EVENT_SEND_COMPLETE       = 0U,  ///< Send completed; however mbox may still transmit data
24     MBOX_EVENT_RECEIVED            = 1U,  ///< Data Received, only in mbox buf, call memcpy() get the data
25     MBOX_EVENT_ERROR               = 2U,  ///< Mbox transmit error occurred
26 } csi_mbox_event_t;
27 
28 typedef struct csi_mbox csi_mbox_t;
29 struct csi_mbox {
30     csi_dev_t        dev;
31     void (*callback)(csi_mbox_t *mbox, csi_mbox_event_t event, uint32_t channel_id, uint32_t received_len, void *arg);
32     void             *arg;
33     void             *priv;
34 };
35 
36 /**
37   \brief       Initialize mbox Interface.
38                Initializes the resources needed for the mbox interface.
39   \param[in]   mbox  Operate handle.
40   \param[in]   idx  The device idx.
41   \return      Error code \ref csi_error_t.
42 */
43 csi_error_t csi_mbox_init(csi_mbox_t *mbox, uint32_t idx);
44 
45 /**
46   \brief       Uninitialize mbox interface. stops operation and releases the software resources used by the interface.
47   \param[in]   mbox  Operate handle.
48 */
49 void csi_mbox_uninit(csi_mbox_t *mbox);
50 
51 /**
52   \brief       Start sending data to mbox transmitter.
53   \param[in]   mbox  Operate handle.
54   \param[in]   channel_id  Index of channel.
55   \param[in]   data  Pointer to buffer with data to send to mbox transmitter.
56   \param[in]   size  Number of data items to send.
57   \return      sent Number of data or error code.
58 */
59 int32_t csi_mbox_send(csi_mbox_t *mbox, uint32_t channel_id, const void *data, uint32_t size);
60 
61 /**
62   \brief       Start receiving data from mbox receiver.
63   \param[in]   mbox  Operate handle.
64   \param[in]   channel_id  Index of channel.
65   \param[out]  data  Pointer to buffer with data to receive from mailbox.
66   \param[in]   size  Number of data items to receive.
67   \return      received  Number or error code.
68 */
69 int32_t csi_mbox_receive(csi_mbox_t *mbox, uint32_t channel_id, void *data, uint32_t size);
70 
71 /**
72   \brief       Attach callback to the mbox.
73   \param[in]   mbox  Operate handle.
74   \param[in]   cb  Event callback function.
75   \param[in]   arg  User private param  for event callback.
76   \return      Error code \ref csi_error_t.
77 */
78 csi_error_t csi_mbox_attach_callback(csi_mbox_t *mbox, void *callback, void *arg);
79 
80 /**
81   \brief       Detach callback from the mbox
82   \param[in]   mbox  Operate handle.
83 */
84 void csi_mbox_detach_callback(csi_mbox_t *mbox);
85 
86 #ifdef __cplusplus
87 }
88 #endif
89 
90 #endif /* _DRV_MBOX_H_ */
91