Intel® Quark™ Microcontroller Software Interface  1.4.0
Intel® Quark™ Microcontroller BSP
qm_mailbox.h
1 /*
2  * {% copyright %}
3  */
4 
5 #ifndef __QM_MAILBOX_H__
6 #define __QM_MAILBOX_H__
7 
8 #include "qm_common.h"
9 #include "qm_soc_regs.h"
10 #include "qm_mailbox_defs.h"
11 
12 #if (HAS_MAILBOX)
13 /**
14  * Mailbox driver.
15  *
16  * @defgroup groupMailbox Mailbox
17  * @{
18  */
19 
20 /**
21  * Mailbox channel status return codes
22  */
23 typedef enum {
24  /** No interrupt pending nor any data to consume. */
26 
27  /**
28  * Receiver has serviced the interrupt and data
29  * has not been consumed. */
30  QM_MBOX_CH_DATA_PEND = QM_MBOX_CH_STS,
31 
32  /**
33  * Receiver hasn't serviced the interrupt and data
34  * has not been consumed.
35  */
37  (QM_MBOX_CH_STS | QM_MBOX_CH_STS_CTRL_INT),
39 
40 /**
41  * Mailbox message payload index values.
42  */
43 typedef enum {
44  QM_MBOX_PAYLOAD_0 = 0, /**< Payload index value 0. */
45  QM_MBOX_PAYLOAD_1, /**< Payload index value 1. */
46  QM_MBOX_PAYLOAD_2, /**< Payload index value 2. */
47  QM_MBOX_PAYLOAD_3, /**< Payload index value 3. */
48  QM_MBOX_PAYLOAD_NUM, /**< Number of payloads. */
50 
51 /**
52  * Definition of the mailbox mode of operation, interrupt mode or polling mode.
53  */
54 typedef enum {
55  /** Mailbox channel operates in interrupt mode. */
57  /** Mailbox channel operates in polling mode. */
60 
61 /**
62  * Definition of the mailbox message.
63  */
64 typedef struct {
65  /** Control word - bits 30 to 0 used as data/message id,
66  * bit 31 triggers channel interrupt when set by the driver.
67  */
68  uint32_t ctrl;
69  /** Mailbox data buffer. */
70  uint32_t data[QM_MBOX_PAYLOAD_NUM];
72 
73 /**
74  * Definition of the mailbox callback function prototype.
75  *
76  * @param[in] data The callback user data.
77  */
78 typedef void (*qm_mbox_callback_t)(void *data);
79 
80 /**
81  * Mailbox Configuration Structure
82  */
83 typedef struct {
84  /**< Mailbox Destination */
86  /**< Mode of operation */
88 
89  /**<
90  * Message callback.
91  *
92  * Called after a message is received on the channel and the channel
93  * is configured in interrupt mode.
94  *
95  * @note NULL for a write Mailbox.
96  *
97  * @param[in] data User defined data.
98  */
100  /**< Callback function data to return via the callback function. */
101  void *callback_data;
103 
104 /**
105  * Set the mailbox channel configuration.
106  *
107  * The function registers the interrupt vector to the mailbox ISR handler
108  * when at least one mailbox channel is enabled, configured in interrupt mode
109  * and the ISR is not handled by the application.
110  *
111  * @param[in] mbox_ch Mailbox channel identifier.
112  * @param[in] config Mailbox configuration.
113  *
114  * @return Standard errno return type for QMSI.
115  * @retval 0 on success.
116  * @retval Negative @ref errno for possible error codes.
117  */
118 int qm_mbox_ch_set_config(const qm_mbox_ch_t mbox_ch,
119  const qm_mbox_config_t *const config);
120 
121 /**
122  * Write to a specified mailbox channel.
123  *
124  * @param[in] mbox_ch Mailbox channel identifier.
125  * @param[in] msg Pointer to the data to write to the mailbox channel. This
126  * must not be NULL.
127  *
128  * @return Standard errno return type for QMSI.
129  * @retval 0 on success.
130  * @retval Negative @ref errno for possible error codes.
131  */
132 int qm_mbox_ch_write(const qm_mbox_ch_t mbox_ch,
133  const qm_mbox_msg_t *const msg);
134 
135 /**
136  * Read specified mailbox channel.
137  *
138  * @param[in] mbox_ch Mailbox channel identifier.
139  * @param[out] msg Pointer to the data to read from the mailbox channel. This
140  * must not be NULL.
141  *
142  * @return Standard errno return type for QMSI.
143  * @retval 0 on success.
144  * @retval Negative @ref errno for possible error codes.
145  */
146 int qm_mbox_ch_read(const qm_mbox_ch_t mbox_ch, qm_mbox_msg_t *const msg);
147 
148 /**
149  * Retrieve the specified mailbox channel status.
150  *
151  * @param[in] mbox_ch Mailbox identifier to retrieve the status from.
152  * @param[out] status Mailbox status. This must not be NULL.
153  *
154  * @return Standard errno return type for QMSI.
155  * @retval 0 on success.
156  * @retval Negative @ref errno for possible error codes.
157  */
158 int qm_mbox_ch_get_status(const qm_mbox_ch_t mbox_ch,
159  qm_mbox_ch_status_t *const status);
160 
161 /**
162  * @}
163  */
164 
165 #endif /* HAS_MAILBOX */
166 #endif /* __QM_MAILBOX_H__ */
void(* qm_mbox_callback_t)(void *data)
Definition of the mailbox callback function prototype.
Definition: qm_mailbox.h:78
qm_mbox_payload_t
Mailbox message payload index values.
Definition: qm_mailbox.h:43
Payload index value 1.
Definition: qm_mailbox.h:45
int qm_mbox_ch_read(const qm_mbox_ch_t mbox_ch, qm_mbox_msg_t *const msg)
Read specified mailbox channel.
qm_mbox_ch_t
Mailbox channel identifiers.
qm_mbox_destination_t dest
< Mailbox Destination
Definition: qm_mailbox.h:85
Mailbox channel operates in polling mode.
Definition: qm_mailbox.h:58
Payload index value 2.
Definition: qm_mailbox.h:46
int qm_mbox_ch_write(const qm_mbox_ch_t mbox_ch, const qm_mbox_msg_t *const msg)
Write to a specified mailbox channel.
int qm_mbox_ch_get_status(const qm_mbox_ch_t mbox_ch, qm_mbox_ch_status_t *const status)
Retrieve the specified mailbox channel status.
uint32_t ctrl
Control word - bits 30 to 0 used as data/message id, bit 31 triggers channel interrupt when set by th...
Definition: qm_mailbox.h:68
Definition of the mailbox message.
Definition: qm_mailbox.h:64
No interrupt pending nor any data to consume.
Definition: qm_mailbox.h:25
Receiver hasn't serviced the interrupt and data has not been consumed.
Definition: qm_mailbox.h:36
Receiver has serviced the interrupt and data has not been consumed.
Definition: qm_mailbox.h:30
int qm_mbox_ch_set_config(const qm_mbox_ch_t mbox_ch, const qm_mbox_config_t *const config)
Set the mailbox channel configuration.
Definition: qm_mailbox_se.c:99
qm_mbox_destination_t
Definition of the mailbox direction of operation The direction of communication for each channel is c...
Mailbox channel operates in interrupt mode.
Definition: qm_mailbox.h:56
qm_mbox_mode_t mode
Message callback.
Definition: qm_mailbox.h:87
qm_mbox_mode_t
Definition of the mailbox mode of operation, interrupt mode or polling mode.
Definition: qm_mailbox.h:54
Payload index value 3.
Definition: qm_mailbox.h:47
Payload index value 0.
Definition: qm_mailbox.h:44
Number of payloads.
Definition: qm_mailbox.h:48
Mailbox Configuration Structure.
Definition: qm_mailbox.h:83
qm_mbox_callback_t callback
Callback function data to return via the callback function.
Definition: qm_mailbox.h:99
qm_mbox_ch_status_t
Mailbox channel status return codes.
Definition: qm_mailbox.h:23