Intel® Quark™ Microcontroller Software Interface 1.4.0 Intel® Quark™ Microcontroller BSP

- Main Page
- Modules
- Data Structures
- Files

- File List

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. */
25 QM_MBOX_CH_IDLE = 0,
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 */
36 QM_MBOX_CH_INT_AND_DATA_PEND =
37 (QM_MBOX_CH_STS | QM_MBOX_CH_STS_CTRL_INT),
38 } qm_mbox_ch_status_t;
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. */
49 } qm_mbox_payload_t;
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. */
56 QM_MBOX_INTERRUPT_MODE = 0,
57 /** Mailbox channel operates in polling mode. */
58 QM_MBOX_POLLING_MODE
59 } qm_mbox_mode_t;
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];
71 } qm_mbox_msg_t;
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 */
85 qm_mbox_destination_t dest;
86 /**< Mode of operation */
87 qm_mbox_mode_t mode;
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 */
99 qm_mbox_callback_t callback;
100 /**< Callback function data to return via the callback function. */
101 void *callback_data;
102 } qm_mbox_config_t;
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__ */
qm_mbox_callback_t
void(* qm_mbox_callback_t)(void *data)
Definition of the mailbox callback function prototype.
Definition: qm_mailbox.h:78
qm_mbox_payload_t
qm_mbox_payload_t
Mailbox message payload index values.
Definition: qm_mailbox.h:43
QM_MBOX_PAYLOAD_1
Payload index value 1.
Definition: qm_mailbox.h:45
qm_mbox_ch_read
int qm_mbox_ch_read(const qm_mbox_ch_t mbox_ch, qm_mbox_msg_t *const msg)
Read specified mailbox channel.
Definition: qm_mailbox_se.c:198
qm_mbox_ch_t
qm_mbox_ch_t
Mailbox channel identifiers.
Definition: qm_mailbox_defs.h:18
qm_mbox_config_t::dest
qm_mbox_destination_t dest
< Mailbox Destination
Definition: qm_mailbox.h:85
QM_MBOX_POLLING_MODE
Mailbox channel operates in polling mode.
Definition: qm_mailbox.h:58
QM_MBOX_PAYLOAD_2
Payload index value 2.
Definition: qm_mailbox.h:46
qm_mbox_ch_write
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.
Definition: qm_mailbox_se.c:171
qm_mbox_ch_get_status
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.
Definition: qm_mailbox_se.c:248
qm_mbox_msg_t::ctrl
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
qm_mbox_msg_t
Definition of the mailbox message.
Definition: qm_mailbox.h:64
QM_MBOX_CH_IDLE
No interrupt pending nor any data to consume.
Definition: qm_mailbox.h:25
QM_MBOX_CH_INT_AND_DATA_PEND
Receiver hasn't serviced the interrupt and data has not been consumed.
Definition: qm_mailbox.h:36
QM_MBOX_CH_DATA_PEND
Receiver has serviced the interrupt and data has not been consumed.
Definition: qm_mailbox.h:30
qm_mbox_ch_set_config
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
qm_mbox_destination_t
Definition of the mailbox direction of operation The direction of communication for each channel is c...
Definition: qm_mailbox_defs.h:35
QM_MBOX_INTERRUPT_MODE
Mailbox channel operates in interrupt mode.
Definition: qm_mailbox.h:56
qm_mbox_config_t::mode
qm_mbox_mode_t mode
Message callback.
Definition: qm_mailbox.h:87
qm_mbox_mode_t
qm_mbox_mode_t
Definition of the mailbox mode of operation, interrupt mode or polling mode.
Definition: qm_mailbox.h:54
QM_MBOX_PAYLOAD_3
Payload index value 3.
Definition: qm_mailbox.h:47
QM_MBOX_PAYLOAD_0
Payload index value 0.
Definition: qm_mailbox.h:44
QM_MBOX_PAYLOAD_NUM
Number of payloads.
Definition: qm_mailbox.h:48
qm_mbox_config_t
Mailbox Configuration Structure.
Definition: qm_mailbox.h:83
qm_mbox_config_t::callback
qm_mbox_callback_t callback
Callback function data to return via the callback function.
Definition: qm_mailbox.h:99
qm_mbox_ch_status_t
qm_mbox_ch_status_t
Mailbox channel status return codes.
Definition: qm_mailbox.h:23