Intel® Quark™ Microcontroller Software Interface  1.4.0
Intel® Quark™ Microcontroller BSP
qm_uart.h
1 /*
2  * {% copyright %}
3  */
4 
5 #ifndef __QM_UART_H__
6 #define __QM_UART_H__
7 
8 #include "qm_common.h"
9 #include "qm_soc_regs.h"
10 #include "qm_dma.h"
11 
12 /**
13  * UART peripheral driver.
14  *
15  * @defgroup groupUART UART
16  * @{
17  */
18 
19 /**
20  * UART Line control.
21  */
22 typedef enum {
23  QM_UART_LC_5N1 = 0x00, /**< 5 data bits, no parity, 1 stop bit. */
24  QM_UART_LC_5N1_5 = 0x04, /**< 5 data bits, no parity, 1.5 stop bits. */
25  QM_UART_LC_5E1 = 0x18, /**< 5 data bits, even parity, 1 stop bit. */
26  QM_UART_LC_5E1_5 = 0x1c, /**< 5 data bits, even par., 1.5 stop bits. */
27  QM_UART_LC_5O1 = 0x08, /**< 5 data bits, odd parity, 1 stop bit. */
28  QM_UART_LC_5O1_5 = 0x0c, /**< 5 data bits, odd parity, 1.5 stop bits. */
29  QM_UART_LC_6N1 = 0x01, /**< 6 data bits, no parity, 1 stop bit. */
30  QM_UART_LC_6N2 = 0x05, /**< 6 data bits, no parity, 2 stop bits. */
31  QM_UART_LC_6E1 = 0x19, /**< 6 data bits, even parity, 1 stop bit. */
32  QM_UART_LC_6E2 = 0x1d, /**< 6 data bits, even parity, 2 stop bits. */
33  QM_UART_LC_6O1 = 0x09, /**< 6 data bits, odd parity, 1 stop bit. */
34  QM_UART_LC_6O2 = 0x0d, /**< 6 data bits, odd parity, 2 stop bits. */
35  QM_UART_LC_7N1 = 0x02, /**< 7 data bits, no parity, 1 stop bit. */
36  QM_UART_LC_7N2 = 0x06, /**< 7 data bits, no parity, 2 stop bits. */
37  QM_UART_LC_7E1 = 0x1a, /**< 7 data bits, even parity, 1 stop bit. */
38  QM_UART_LC_7E2 = 0x1e, /**< 7 data bits, even parity, 2 stop bits. */
39  QM_UART_LC_7O1 = 0x0a, /**< 7 data bits, odd parity, 1 stop bit. */
40  QM_UART_LC_7O2 = 0x0e, /**< 7 data bits, odd parity, 2 stop bits. */
41  QM_UART_LC_8N1 = 0x03, /**< 8 data bits, no parity, 1 stop bit. */
42  QM_UART_LC_8N2 = 0x07, /**< 8 data bits, no parity, 2 stop bits. */
43  QM_UART_LC_8E1 = 0x1b, /**< 8 data bits, even parity, 1 stop bit. */
44  QM_UART_LC_8E2 = 0x1f, /**< 8 data bits, even parity, 2 stop bits. */
45  QM_UART_LC_8O1 = 0x0b, /**< 8 data bits, odd parity, 1 stop bit. */
46  QM_UART_LC_8O2 = 0x0f /**< 8 data bits, odd parity, 2 stop bits. */
47 } qm_uart_lc_t;
48 
49 /**
50  * UART Status type.
51  */
52 typedef enum {
53  QM_UART_IDLE = 0, /**< IDLE. */
54  QM_UART_RX_OE = BIT(1), /**< Receiver overrun. */
55  QM_UART_RX_PE = BIT(2), /**< Parity error. */
56  QM_UART_RX_FE = BIT(3), /**< Framing error. */
57  QM_UART_RX_BI = BIT(4), /**< Break interrupt. */
58  QM_UART_TX_BUSY = BIT(5), /**< TX Busy flag. */
59  QM_UART_RX_BUSY = BIT(6), /**< RX Busy flag. */
60  QM_UART_TX_NFULL = BIT(7), /**< TX FIFO not full. */
61  QM_UART_RX_NEMPTY = BIT(8), /**< RX FIFO not empty. */
63 
64 /**
65  * UART configuration structure type
66  */
67 typedef struct {
68  qm_uart_lc_t line_control; /**< Line control (enum). */
69  uint32_t baud_divisor; /**< Baud Divisor. */
70  bool hw_fc; /**< Hardware Automatic Flow Control. */
72 
73 /**
74  * UART asynchronous transfer structure.
75  */
76 typedef struct {
77  uint8_t *data; /**< Pre-allocated write or read buffer. */
78  uint32_t data_len; /**< Number of bytes to transfer. */
79 
80  /** Transfer callback
81  *
82  * @param[in] data Callback user data.
83  * @param[in] error 0 on success.
84  * Negative @ref errno for possible error codes.
85  * @param[in] status UART module status
86  * @param[in] len Length of the UART transfer if successful, 0
87  * otherwise.
88  */
89  void (*callback)(void *data, int error, qm_uart_status_t status,
90  uint32_t len);
91  void *callback_data; /**< Callback identifier. */
93 
94 /**
95  * Set UART configuration.
96  *
97  * Change the configuration of a UART module. This includes line control,
98  * baud rate and hardware flow control.
99  *
100  * @param[in] uart Which UART module to configure.
101  * @param[in] cfg New configuration for UART. This must not be NULL.
102  *
103  * @return Standard errno return type for QMSI.
104  * @retval 0 on success.
105  * @retval Negative @ref errno for possible error codes.
106  */
107 int qm_uart_set_config(const qm_uart_t uart, const qm_uart_config_t *const cfg);
108 
109 /**
110  * Get UART bus status.
111  *
112  * Retrieve UART interface status. Return QM_UART_BUSY if transmitting
113  * data; QM_UART_IDLE if available for transfer; QM_UART_TX_ERROR if an
114  * error has occurred in transmission.
115  *
116  * The user may call this function before performing an UART transfer in order
117  * to guarantee that the UART interface is available.
118 
119  * @param[in] uart Which UART to read the status of.
120  * @param[out] status Current UART status. This must not be NULL.
121  *
122  * @return Standard errno return type for QMSI.
123  * @retval 0 on success.
124  * @retval Negative @ref errno for possible error codes.
125  */
126 int qm_uart_get_status(const qm_uart_t uart, qm_uart_status_t *const status);
127 
128 /**
129  * UART character data write.
130  *
131  * Perform a single character write on the UART interface.
132  * This is a blocking synchronous call.
133  *
134  * @param[in] uart UART identifer.
135  * @param[in] data Data to write to UART.
136  *
137  * @return Standard errno return type for QMSI.
138  * @retval 0 on success.
139  * @retval Negative @ref errno for possible error codes.
140  */
141 int qm_uart_write(const qm_uart_t uart, const uint8_t data);
142 
143 /**
144  * UART character data read.
145  *
146  * Perform a single character read from the UART interface.
147  * This is a blocking synchronous call.
148  *
149  * @param[in] uart UART identifer.
150  * @param[out] data Data to read from UART. This must not be NULL.
151  * @param[out] status UART specific status.
152  *
153  * @return Standard errno return type for QMSI.
154  * @retval 0 on success.
155  * @retval Negative @ref errno for possible error codes.
156  */
157 int qm_uart_read(const qm_uart_t uart, uint8_t *const data,
158  qm_uart_status_t *const status);
159 
160 /**
161  * UART character data write.
162  *
163  * Perform a single character write on the UART interface.
164  * This is a non-blocking synchronous call.
165  *
166  * @param[in] uart UART identifier.
167  * @param[in] data Data to write to UART.
168  *
169  * @return Standard errno return type for QMSI.
170  * @retval 0 on success.
171  * @retval Negative @ref errno for possible error codes.
172  */
173 int qm_uart_write_non_block(const qm_uart_t uart, const uint8_t data);
174 
175 /**
176  * UART character data read.
177  *
178  * Perform a single character read from the UART interface.
179  * This is a non-blocking synchronous call.
180  *
181  * @param[in] uart UART identifer.
182  * @param[out] data Character read. This must not be NULL.
183  *
184  * @return Standard errno return type for QMSI.
185  * @retval 0 on success.
186  * @retval Negative @ref errno for possible error codes.
187  */
188 int qm_uart_read_non_block(const qm_uart_t uart, uint8_t *const data);
189 
190 /**
191  * UART multi-byte data write.
192  *
193  * Perform a write on the UART interface. This is a blocking
194  * synchronous call. The function will block until all data has
195  * been transferred.
196  *
197  * @param[in] uart UART controller identifier
198  * @param[in] data Data to write to UART. This must not be NULL.
199  * @param[in] len Length of data to write to UART.
200  *
201  * @return Standard errno return type for QMSI.
202  * @retval 0 on success.
203  * @retval Negative @ref errno for possible error codes.
204  */
205 int qm_uart_write_buffer(const qm_uart_t uart, const uint8_t *const data,
206  const uint32_t len);
207 
208 /**
209  * Interrupt based TX on UART.
210  *
211  * Perform an interrupt based TX transfer on the UART bus. The function
212  * will replenish the TX FIFOs on UART empty interrupts.
213  *
214  * @param[in] uart UART identifier.
215  * @param[in] xfer Structure containing pre-allocated
216  * write buffer and callback functions.
217  * The structure must not be NULL and must be kept valid until
218  * the transfer is complete.
219  *
220  * @return Standard errno return type for QMSI.
221  * @retval 0 on success.
222  * @retval Negative @ref errno for possible error codes.
223  */
224 int qm_uart_irq_write(const qm_uart_t uart,
225  const qm_uart_transfer_t *const xfer);
226 
227 /**
228  * Interrupt based RX on UART.
229  *
230  * Perform an interrupt based RX transfer on the UART bus. The function
231  * will read back the RX FIFOs on UART empty interrupts.
232  *
233  * @param[in] uart UART identifier.
234  * @param[in] xfer Structure containing pre-allocated read
235  * buffer and callback functions.
236  * The structure must not be NULL and must be kept valid until
237  * the transfer is complete.
238  *
239  * @return Standard errno return type for QMSI.
240  * @retval 0 on success.
241  * @retval Negative @ref errno for possible error codes.
242  */
243 int qm_uart_irq_read(const qm_uart_t uart,
244  const qm_uart_transfer_t *const xfer);
245 
246 /**
247  * Terminate UART IRQ TX transfer.
248  *
249  * Terminate the current IRQ TX transfer on the UART bus.
250  * This will cause the relevant callbacks to be called.
251  *
252  * @param[in] uart UART identifier.
253  *
254  * @return Standard errno return type for QMSI.
255  * @retval 0 on success.
256  * @retval Negative @ref errno for possible error codes.
257  */
258 int qm_uart_irq_write_terminate(const qm_uart_t uart);
259 
260 /**
261  * Terminate UART IRQ RX transfer.
262  *
263  * Terminate the current IRQ RX transfer on the UART bus.
264  * This will cause the relevant callbacks to be called.
265  *
266  * @param[in] uart UART identifier.
267  *
268  * @return Standard errno return type for QMSI.
269  * @retval 0 on success.
270  * @retval Negative @ref errno for possible error codes.
271  */
272 int qm_uart_irq_read_terminate(const qm_uart_t uart);
273 
274 /**
275  * Configure a DMA channel with a specific transfer direction.
276  *
277  * The user is responsible for managing the allocation of the pool
278  * of DMA channels provided by each DMA core to the different
279  * peripheral drivers that require them.
280  *
281  * This function configures DMA channel parameters that are unlikely to change
282  * between transfers, like transaction width, burst size, and handshake
283  * interface parameters. The user will likely only call this function once for
284  * the lifetime of an application unless the channel needs to be repurposed.
285  *
286  * Note that qm_dma_init() must first be called before configuring a channel.
287  *
288  * @param[in] uart UART identifier.
289  * @param[in] dma_ctrl_id DMA controller identifier.
290  * @param[in] dma_channel_id DMA channel identifier.
291  * @param[in] dma_channel_direction DMA channel direction, either
292  * QM_DMA_MEMORY_TO_PERIPHERAL (write transfer) or QM_DMA_PERIPHERAL_TO_MEMORY
293  * (read transfer).
294  *
295  * @return Standard errno return type for QMSI.
296  * @retval 0 on success.
297  * @retval Negative @ref errno for possible error codes.
298  */
300  const qm_uart_t uart, const qm_dma_t dma_ctrl_id,
301  const qm_dma_channel_id_t dma_channel_id,
302  const qm_dma_channel_direction_t dma_channel_direction);
303 
304 /**
305  * Perform a DMA-based TX transfer on the UART bus.
306  *
307  * In order for this call to succeed, previously the user
308  * must have configured a DMA channel with direction
309  * QM_DMA_MEMORY_TO_PERIPHERAL to be used on this UART, calling
310  * qm_uart_dma_channel_config(). The transfer length is limited to 4KB.
311  *
312  * Note that this function uses the UART TX FIFO empty interrupt and therefore,
313  * in addition to the DMA interrupts, the ISR of the corresponding UART must be
314  * registered before using this function.
315  *
316  * @param[in] uart UART identifer.
317  * @param[in] xfer Structure containing a pre-allocated write buffer
318  * and callback functions.
319  * This must not be NULL.
320  *
321  * @return Standard errno return type for QMSI.
322  * @retval 0 on success.
323  * @retval Negative @ref errno for possible error codes.
324  */
325 int qm_uart_dma_write(const qm_uart_t uart,
326  const qm_uart_transfer_t *const xfer);
327 
328 /**
329  * Perform a DMA-based RX transfer on the UART bus.
330  *
331  * In order for this call to succeed, previously the user
332  * must have configured a DMA channel with direction
333  * QM_DMA_PERIPHERAL_TO_MEMORY to be used on this UART, calling
334  * qm_uart_dma_channel_config(). The transfer length is limited to 4KB.
335  *
336  * @param[in] uart UART identifer.
337  * @param[in] xfer Structure containing a pre-allocated read buffer
338  * and callback functions.
339  * This must not be NULL.
340  *
341  * @return Standard errno return type for QMSI.
342  * @retval 0 on success.
343  * @retval Negative @ref errno for possible error codes.
344  */
345 int qm_uart_dma_read(const qm_uart_t uart,
346  const qm_uart_transfer_t *const xfer);
347 
348 /**
349  * Terminate the current DMA TX transfer on the UART bus.
350  *
351  * This will cause the relevant callbacks to be called.
352  *
353  * @param[in] uart UART identifer.
354  *
355  * @return Standard errno return type for QMSI.
356  * @retval 0 on success.
357  * @retval Negative @ref errno for possible error codes.
358  */
359 int qm_uart_dma_write_terminate(const qm_uart_t uart);
360 
361 /**
362  * Terminate the current DMA RX transfer on the UART bus.
363  *
364  * This will cause the relevant callbacks to be called.
365  *
366  * @param[in] uart UART identifer.
367  *
368  * @return Standard errno return type for QMSI.
369  * @retval 0 on success.
370  * @retval Negative @ref errno for possible error codes.
371  */
372 int qm_uart_dma_read_terminate(const qm_uart_t uart);
373 
374 /**
375  * Save UART context.
376  *
377  * Saves the configuration of the specified UART peripheral
378  * before entering sleep.
379  *
380  * @param[in] uart UART port index.
381  * @param[out] ctx UART context structure. This must not be NULL.
382  *
383  * @return Standard errno return type for QMSI.
384  * @retval 0 on success.
385  * @retval Negative @ref errno for possible error codes.
386  */
387 int qm_uart_save_context(const qm_uart_t uart, qm_uart_context_t *const ctx);
388 
389 /**
390  * Restore UART context.
391  *
392  * Restore the configuration of the specified UART peripheral
393  * after exiting sleep.
394  *
395  * FIFO control register cannot be read back,
396  * the default configuration is applied for this register.
397  * Application will need to restore its own parameters.
398  *
399  * @param[in] uart UART port index.
400  * @param[in] ctx UART context structure. This must not be NULL.
401  *
402  * @return Standard errno return type for QMSI.
403  * @retval 0 on success.
404  * @retval Negative @ref errno for possible error codes.
405  */
406 int qm_uart_restore_context(const qm_uart_t uart,
407  const qm_uart_context_t *const ctx);
408 
409 /**
410  * @}
411  */
412 
413 #endif /* __QM_UART_H__ */
qm_uart_lc_t
UART Line control.
Definition: qm_uart.h:22
int qm_uart_dma_channel_config(const qm_uart_t uart, const qm_dma_t dma_ctrl_id, const qm_dma_channel_id_t dma_channel_id, const qm_dma_channel_direction_t dma_channel_direction)
Configure a DMA channel with a specific transfer direction.
Definition: qm_uart.c:530
int qm_uart_irq_read(const qm_uart_t uart, const qm_uart_transfer_t *const xfer)
Interrupt based RX on UART.
Definition: qm_uart.c:389
int qm_uart_dma_read(const qm_uart_t uart, const qm_uart_transfer_t *const xfer)
Perform a DMA-based RX transfer on the UART bus.
Definition: qm_uart.c:625
qm_dma_t
DMA instances.
Definition: qm_soc_regs.h:1480
UART context to be saved between sleep/resume.
Definition: qm_soc_regs.h:993
int qm_uart_save_context(const qm_uart_t uart, qm_uart_context_t *const ctx)
Save UART context.
Definition: qm_uart.c:734
5 data bits, odd parity, 1.5 stop bits.
Definition: qm_uart.h:28
IDLE.
Definition: qm_uart.h:53
UART asynchronous transfer structure.
Definition: qm_uart.h:76
int qm_uart_get_status(const qm_uart_t uart, qm_uart_status_t *const status)
Get UART bus status.
Definition: qm_uart.c:253
qm_uart_lc_t line_control
Line control (enum).
Definition: qm_uart.h:68
int qm_uart_dma_write_terminate(const qm_uart_t uart)
Terminate the current DMA TX transfer on the UART bus.
Definition: qm_uart.c:658
6 data bits, even parity, 2 stop bits.
Definition: qm_uart.h:32
uint8_t * data
Pre-allocated write or read buffer.
Definition: qm_uart.h:77
qm_uart_t
Number of UART controllers.
Definition: qm_soc_regs.h:655
int qm_uart_dma_read_terminate(const qm_uart_t uart)
Terminate the current DMA RX transfer on the UART bus.
Definition: qm_uart.c:668
int qm_uart_irq_write(const qm_uart_t uart, const qm_uart_transfer_t *const xfer)
Interrupt based TX on UART.
Definition: qm_uart.c:368
7 data bits, no parity, 1 stop bit.
Definition: qm_uart.h:35
int qm_uart_write_non_block(const qm_uart_t uart, const uint8_t data)
UART character data write.
Definition: qm_uart.c:320
6 data bits, no parity, 2 stop bits.
Definition: qm_uart.h:30
8 data bits, even parity, 2 stop bits.
Definition: qm_uart.h:44
int qm_uart_read_non_block(const qm_uart_t uart, uint8_t *const data)
UART character data read.
Definition: qm_uart.c:331
5 data bits, odd parity, 1 stop bit.
Definition: qm_uart.h:27
5 data bits, even parity, 1 stop bit.
Definition: qm_uart.h:25
Receiver overrun.
Definition: qm_uart.h:54
Break interrupt.
Definition: qm_uart.h:57
6 data bits, even parity, 1 stop bit.
Definition: qm_uart.h:31
bool hw_fc
Hardware Automatic Flow Control.
Definition: qm_uart.h:70
5 data bits, no parity, 1.5 stop bits.
Definition: qm_uart.h:24
6 data bits, odd parity, 1 stop bit.
Definition: qm_uart.h:33
Parity error.
Definition: qm_uart.h:55
qm_uart_status_t
UART Status type.
Definition: qm_uart.h:52
5 data bits, even par., 1.5 stop bits.
Definition: qm_uart.h:26
7 data bits, odd parity, 1 stop bit.
Definition: qm_uart.h:39
int qm_uart_set_config(const qm_uart_t uart, const qm_uart_config_t *const cfg)
Set UART configuration.
Definition: qm_uart.c:215
TX FIFO not full.
Definition: qm_uart.h:60
int qm_uart_restore_context(const qm_uart_t uart, const qm_uart_context_t *const ctx)
Restore UART context.
Definition: qm_uart.c:742
7 data bits, even parity, 1 stop bit.
Definition: qm_uart.h:37
int qm_uart_irq_write_terminate(const qm_uart_t uart)
Terminate UART IRQ TX transfer.
Definition: qm_uart.c:412
RX Busy flag.
Definition: qm_uart.h:59
void * callback_data
Callback identifier.
Definition: qm_uart.h:91
qm_dma_channel_direction_t
DMA channel direction.
Definition: qm_dma.h:56
uint32_t baud_divisor
Baud Divisor.
Definition: qm_uart.h:69
7 data bits, odd parity, 2 stop bits.
Definition: qm_uart.h:40
6 data bits, odd parity, 2 stop bits.
Definition: qm_uart.h:34
7 data bits, even parity, 2 stop bits.
Definition: qm_uart.h:38
RX FIFO not empty.
Definition: qm_uart.h:61
8 data bits, even parity, 1 stop bit.
Definition: qm_uart.h:43
5 data bits, no parity, 1 stop bit.
Definition: qm_uart.h:23
8 data bits, no parity, 2 stop bits.
Definition: qm_uart.h:42
qm_dma_channel_id_t
DMA channel IDs.
Definition: qm_soc_regs.h:1486
int qm_uart_write(const qm_uart_t uart, const uint8_t data)
UART character data write.
Definition: qm_uart.c:280
int qm_uart_irq_read_terminate(const qm_uart_t uart)
Terminate UART IRQ RX transfer.
Definition: qm_uart.c:429
UART configuration structure type.
Definition: qm_uart.h:67
8 data bits, odd parity, 2 stop bits.
Definition: qm_uart.h:46
Framing error.
Definition: qm_uart.h:56
uint32_t data_len
Number of bytes to transfer.
Definition: qm_uart.h:78
6 data bits, no parity, 1 stop bit.
Definition: qm_uart.h:29
int qm_uart_read(const qm_uart_t uart, uint8_t *const data, qm_uart_status_t *const status)
UART character data read.
Definition: qm_uart.c:296
TX Busy flag.
Definition: qm_uart.h:58
int qm_uart_dma_write(const qm_uart_t uart, const qm_uart_transfer_t *const xfer)
Perform a DMA-based TX transfer on the UART bus.
Definition: qm_uart.c:591
8 data bits, odd parity, 1 stop bit.
Definition: qm_uart.h:45
7 data bits, no parity, 2 stop bits.
Definition: qm_uart.h:36
int qm_uart_write_buffer(const qm_uart_t uart, const uint8_t *const data, const uint32_t len)
UART multi-byte data write.
Definition: qm_uart.c:342
8 data bits, no parity, 1 stop bit.
Definition: qm_uart.h:41