1 /*
2 * Copyright (c) 2018-2019 Nordic Semiconductor ASA
3 * Copyright (c) 2015 Wind River Systems, Inc.
4 *
5 * SPDX-License-Identifier: Apache-2.0
6 */
7
8 /**
9 * @file
10 * @brief Public APIs for UART drivers
11 */
12
13 #ifndef ZEPHYR_INCLUDE_DRIVERS_UART_H_
14 #define ZEPHYR_INCLUDE_DRIVERS_UART_H_
15
16 /**
17 * @brief UART Interface
18 * @defgroup uart_interface UART Interface
19 * @ingroup io_interfaces
20 * @{
21 */
22
23 #include <errno.h>
24 #include <stddef.h>
25
26 #include <zephyr/device.h>
27
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31
32 /** @brief Line control signals. */
33 enum uart_line_ctrl {
34 UART_LINE_CTRL_BAUD_RATE = BIT(0), /**< Baud rate */
35 UART_LINE_CTRL_RTS = BIT(1), /**< Request To Send (RTS) */
36 UART_LINE_CTRL_DTR = BIT(2), /**< Data Terminal Ready (DTR) */
37 UART_LINE_CTRL_DCD = BIT(3), /**< Data Carrier Detect (DCD) */
38 UART_LINE_CTRL_DSR = BIT(4), /**< Data Set Ready (DSR) */
39 };
40
41 /**
42 * @brief Reception stop reasons.
43 *
44 * Values that correspond to events or errors responsible for stopping
45 * receiving.
46 */
47 enum uart_rx_stop_reason {
48 /** @brief Overrun error */
49 UART_ERROR_OVERRUN = (1 << 0),
50 /** @brief Parity error */
51 UART_ERROR_PARITY = (1 << 1),
52 /** @brief Framing error */
53 UART_ERROR_FRAMING = (1 << 2),
54 /**
55 * @brief Break interrupt
56 *
57 * A break interrupt was received. This happens when the serial input
58 * is held at a logic '0' state for longer than the sum of
59 * start time + data bits + parity + stop bits.
60 */
61 UART_BREAK = (1 << 3),
62 /**
63 * @brief Collision error
64 *
65 * This error is raised when transmitted data does not match
66 * received data. Typically this is useful in scenarios where
67 * the TX and RX lines maybe connected together such as
68 * RS-485 half-duplex. This error is only valid on UARTs that
69 * support collision checking.
70 */
71 UART_ERROR_COLLISION = (1 << 4),
72 /** @brief Noise error */
73 UART_ERROR_NOISE = (1 << 5),
74 };
75
76 /** @brief Parity modes */
77 enum uart_config_parity {
78 UART_CFG_PARITY_NONE, /**< No parity */
79 UART_CFG_PARITY_ODD, /**< Odd parity */
80 UART_CFG_PARITY_EVEN, /**< Even parity */
81 UART_CFG_PARITY_MARK, /**< Mark parity */
82 UART_CFG_PARITY_SPACE, /**< Space parity */
83 };
84
85 /** @brief Number of stop bits. */
86 enum uart_config_stop_bits {
87 UART_CFG_STOP_BITS_0_5, /**< 0.5 stop bit */
88 UART_CFG_STOP_BITS_1, /**< 1 stop bit */
89 UART_CFG_STOP_BITS_1_5, /**< 1.5 stop bits */
90 UART_CFG_STOP_BITS_2, /**< 2 stop bits */
91 };
92
93 /** @brief Number of data bits. */
94 enum uart_config_data_bits {
95 UART_CFG_DATA_BITS_5, /**< 5 data bits */
96 UART_CFG_DATA_BITS_6, /**< 6 data bits */
97 UART_CFG_DATA_BITS_7, /**< 7 data bits */
98 UART_CFG_DATA_BITS_8, /**< 8 data bits */
99 UART_CFG_DATA_BITS_9, /**< 9 data bits */
100 };
101
102 /**
103 * @brief Hardware flow control options.
104 *
105 * With flow control set to none, any operations related to flow control
106 * signals can be managed by user with uart_line_ctrl functions.
107 * In other cases, flow control is managed by hardware/driver.
108 */
109 enum uart_config_flow_control {
110 UART_CFG_FLOW_CTRL_NONE, /**< No flow control */
111 UART_CFG_FLOW_CTRL_RTS_CTS, /**< RTS/CTS flow control */
112 UART_CFG_FLOW_CTRL_DTR_DSR, /**< DTR/DSR flow control */
113 UART_CFG_FLOW_CTRL_RS485, /**< RS485 flow control */
114 };
115
116 /**
117 * @brief UART controller configuration structure
118 */
119 struct uart_config {
120 uint32_t baudrate; /**< Baudrate setting in bps */
121 uint8_t parity; /**< Parity bit, use @ref uart_config_parity */
122 uint8_t stop_bits; /**< Stop bits, use @ref uart_config_stop_bits */
123 uint8_t data_bits; /**< Data bits, use @ref uart_config_data_bits */
124 uint8_t flow_ctrl; /**< Flow control setting, use @ref uart_config_flow_control */
125 };
126
127 /**
128 * @defgroup uart_interrupt Interrupt-driven UART API
129 * @{
130 */
131
132 /**
133 * @brief Define the application callback function signature for
134 * uart_irq_callback_user_data_set() function.
135 *
136 * @param dev UART device instance.
137 * @param user_data Arbitrary user data.
138 */
139 typedef void (*uart_irq_callback_user_data_t)(const struct device *dev,
140 void *user_data);
141
142 /**
143 * @brief For configuring IRQ on each individual UART device.
144 *
145 * @param dev UART device instance.
146 */
147 typedef void (*uart_irq_config_func_t)(const struct device *dev);
148
149 /**
150 * @}
151 *
152 * @defgroup uart_async Async UART API
153 * @{
154 */
155
156 /**
157 * @brief Types of events passed to callback in UART_ASYNC_API
158 *
159 * Receiving:
160 * 1. To start receiving, uart_rx_enable has to be called with first buffer
161 * 2. When receiving starts to current buffer,
162 * #UART_RX_BUF_REQUEST will be generated, in response to that user can
163 * either:
164 *
165 * - Provide second buffer using uart_rx_buf_rsp, when first buffer is
166 * filled, receiving will automatically start to second buffer.
167 * - Ignore the event, this way when current buffer is filled
168 * #UART_RX_RDY event will be generated and receiving will be stopped.
169 *
170 * 3. If some data was received and timeout occurred #UART_RX_RDY event will be
171 * generated. It can happen multiples times for the same buffer. RX timeout
172 * is counted from last byte received i.e. if no data was received, there
173 * won't be any timeout event.
174 * 4. #UART_RX_BUF_RELEASED event will be generated when the current buffer is
175 * no longer used by the driver. It will immediately follow #UART_RX_RDY event.
176 * Depending on the implementation buffer may be released when it is completely
177 * or partially filled.
178 * 5. If there was second buffer provided, it will become current buffer and
179 * we start again at point 2.
180 * If no second buffer was specified receiving is stopped and
181 * #UART_RX_DISABLED event is generated. After that whole process can be
182 * repeated.
183 *
184 * Any time during reception #UART_RX_STOPPED event can occur. if there is any
185 * data received, #UART_RX_RDY event will be generated. It will be followed by
186 * #UART_RX_BUF_RELEASED event for every buffer currently passed to driver and
187 * finally by #UART_RX_DISABLED event.
188 *
189 * Receiving can be disabled using uart_rx_disable, after calling that
190 * function, if there is any data received, #UART_RX_RDY event will be
191 * generated. #UART_RX_BUF_RELEASED event will be generated for every buffer
192 * currently passed to driver and finally #UART_RX_DISABLED event will occur.
193 *
194 * Transmitting:
195 * 1. Transmitting starts by uart_tx function.
196 * 2. If whole buffer was transmitted #UART_TX_DONE is generated. If timeout
197 * occurred #UART_TX_ABORTED will be generated.
198 *
199 * Transmitting can be aborted using @ref uart_tx_abort, after calling that
200 * function #UART_TX_ABORTED event will be generated.
201 *
202 */
203 enum uart_event_type {
204 /** @brief Whole TX buffer was transmitted. */
205 UART_TX_DONE,
206 /**
207 * @brief Transmitting aborted due to timeout or uart_tx_abort call
208 *
209 * When flow control is enabled, there is a possibility that TX transfer
210 * won't finish in the allotted time. Some data may have been
211 * transferred, information about it can be found in event data.
212 */
213 UART_TX_ABORTED,
214 /**
215 * @brief Received data is ready for processing.
216 *
217 * This event is generated in the following cases:
218 * - When RX timeout occurred, and data was stored in provided buffer.
219 * This can happen multiple times in the same buffer.
220 * - When provided buffer is full.
221 * - After uart_rx_disable().
222 * - After stopping due to external event (#UART_RX_STOPPED).
223 */
224 UART_RX_RDY,
225 /**
226 * @brief Driver requests next buffer for continuous reception.
227 *
228 * This event is triggered when receiving has started for a new buffer,
229 * i.e. it's time to provide a next buffer for a seamless switchover to
230 * it. For continuous reliable receiving, user should provide another RX
231 * buffer in response to this event, using uart_rx_buf_rsp function
232 *
233 * If uart_rx_buf_rsp is not called before current buffer
234 * is filled up, receiving will stop.
235 */
236 UART_RX_BUF_REQUEST,
237 /**
238 * @brief Buffer is no longer used by UART driver.
239 */
240 UART_RX_BUF_RELEASED,
241 /**
242 * @brief RX has been disabled and can be reenabled.
243 *
244 * This event is generated whenever receiver has been stopped, disabled
245 * or finished its operation and can be enabled again using
246 * uart_rx_enable
247 */
248 UART_RX_DISABLED,
249 /**
250 * @brief RX has stopped due to external event.
251 *
252 * Reason is one of uart_rx_stop_reason.
253 */
254 UART_RX_STOPPED,
255 };
256
257 /** @brief UART TX event data. */
258 struct uart_event_tx {
259 /** @brief Pointer to current buffer. */
260 const uint8_t *buf;
261 /** @brief Number of bytes sent. */
262 size_t len;
263 };
264
265 /**
266 * @brief UART RX event data.
267 *
268 * The data represented by the event is stored in rx.buf[rx.offset] to
269 * rx.buf[rx.offset+rx.len]. That is, the length is relative to the offset.
270 */
271 struct uart_event_rx {
272 /** @brief Pointer to current buffer. */
273 uint8_t *buf;
274 /** @brief Currently received data offset in bytes. */
275 size_t offset;
276 /** @brief Number of new bytes received. */
277 size_t len;
278 };
279
280 /** @brief UART RX buffer released event data. */
281 struct uart_event_rx_buf {
282 /** @brief Pointer to buffer that is no longer in use. */
283 uint8_t *buf;
284 };
285
286 /** @brief UART RX stopped data. */
287 struct uart_event_rx_stop {
288 /** @brief Reason why receiving stopped */
289 enum uart_rx_stop_reason reason;
290 /** @brief Last received data. */
291 struct uart_event_rx data;
292 };
293
294 /** @brief Structure containing information about current event. */
295 struct uart_event {
296 /** @brief Type of event */
297 enum uart_event_type type;
298 /** @brief Event data */
299 union uart_event_data {
300 /** @brief #UART_TX_DONE and #UART_TX_ABORTED events data. */
301 struct uart_event_tx tx;
302 /** @brief #UART_RX_RDY event data. */
303 struct uart_event_rx rx;
304 /** @brief #UART_RX_BUF_RELEASED event data. */
305 struct uart_event_rx_buf rx_buf;
306 /** @brief #UART_RX_STOPPED event data. */
307 struct uart_event_rx_stop rx_stop;
308 } data;
309 };
310
311 /**
312 * @typedef uart_callback_t
313 * @brief Define the application callback function signature for
314 * uart_callback_set() function.
315 *
316 * @param dev UART device instance.
317 * @param evt Pointer to uart_event instance.
318 * @param user_data Pointer to data specified by user.
319 */
320 typedef void (*uart_callback_t)(const struct device *dev,
321 struct uart_event *evt, void *user_data);
322
323 /**
324 * @}
325 */
326
327 /**
328 * @cond INTERNAL_HIDDEN
329 *
330 * For internal driver use only, skip these in public documentation.
331 */
332
333 /** @brief Driver API structure. */
334 __subsystem struct uart_driver_api {
335
336 #ifdef CONFIG_UART_ASYNC_API
337
338 int (*callback_set)(const struct device *dev,
339 uart_callback_t callback,
340 void *user_data);
341
342 int (*tx)(const struct device *dev, const uint8_t *buf, size_t len,
343 int32_t timeout);
344 int (*tx_abort)(const struct device *dev);
345
346 int (*rx_enable)(const struct device *dev, uint8_t *buf, size_t len,
347 int32_t timeout);
348 int (*rx_buf_rsp)(const struct device *dev, uint8_t *buf, size_t len);
349 int (*rx_disable)(const struct device *dev);
350
351 #ifdef CONFIG_UART_WIDE_DATA
352 int (*tx_u16)(const struct device *dev, const uint16_t *buf,
353 size_t len, int32_t timeout);
354 int (*rx_enable_u16)(const struct device *dev, uint16_t *buf,
355 size_t len, int32_t timeout);
356 int (*rx_buf_rsp_u16)(const struct device *dev, uint16_t *buf,
357 size_t len);
358 #endif
359
360 #endif
361
362 /** Console I/O function */
363 int (*poll_in)(const struct device *dev, unsigned char *p_char);
364 void (*poll_out)(const struct device *dev, unsigned char out_char);
365
366 #ifdef CONFIG_UART_WIDE_DATA
367 int (*poll_in_u16)(const struct device *dev, uint16_t *p_u16);
368 void (*poll_out_u16)(const struct device *dev, uint16_t out_u16);
369 #endif
370
371 /** Console I/O function */
372 int (*err_check)(const struct device *dev);
373
374 #ifdef CONFIG_UART_USE_RUNTIME_CONFIGURE
375 /** UART configuration functions */
376 int (*configure)(const struct device *dev,
377 const struct uart_config *cfg);
378 int (*config_get)(const struct device *dev, struct uart_config *cfg);
379 #endif
380
381 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
382
383 /** Interrupt driven FIFO fill function */
384 int (*fifo_fill)(const struct device *dev, const uint8_t *tx_data,
385 int len);
386
387 #ifdef CONFIG_UART_WIDE_DATA
388 int (*fifo_fill_u16)(const struct device *dev, const uint16_t *tx_data,
389 int len);
390 #endif
391
392 /** Interrupt driven FIFO read function */
393 int (*fifo_read)(const struct device *dev, uint8_t *rx_data,
394 const int size);
395
396 #ifdef CONFIG_UART_WIDE_DATA
397 int (*fifo_read_u16)(const struct device *dev, uint16_t *rx_data,
398 const int size);
399 #endif
400
401 /** Interrupt driven transfer enabling function */
402 void (*irq_tx_enable)(const struct device *dev);
403
404 /** Interrupt driven transfer disabling function */
405 void (*irq_tx_disable)(const struct device *dev);
406
407 /** Interrupt driven transfer ready function */
408 int (*irq_tx_ready)(const struct device *dev);
409
410 /** Interrupt driven receiver enabling function */
411 void (*irq_rx_enable)(const struct device *dev);
412
413 /** Interrupt driven receiver disabling function */
414 void (*irq_rx_disable)(const struct device *dev);
415
416 /** Interrupt driven transfer complete function */
417 int (*irq_tx_complete)(const struct device *dev);
418
419 /** Interrupt driven receiver ready function */
420 int (*irq_rx_ready)(const struct device *dev);
421
422 /** Interrupt driven error enabling function */
423 void (*irq_err_enable)(const struct device *dev);
424
425 /** Interrupt driven error disabling function */
426 void (*irq_err_disable)(const struct device *dev);
427
428 /** Interrupt driven pending status function */
429 int (*irq_is_pending)(const struct device *dev);
430
431 /** Interrupt driven interrupt update function */
432 int (*irq_update)(const struct device *dev);
433
434 /** Set the irq callback function */
435 void (*irq_callback_set)(const struct device *dev,
436 uart_irq_callback_user_data_t cb,
437 void *user_data);
438
439 #endif
440
441 #ifdef CONFIG_UART_LINE_CTRL
442 int (*line_ctrl_set)(const struct device *dev, uint32_t ctrl,
443 uint32_t val);
444 int (*line_ctrl_get)(const struct device *dev, uint32_t ctrl,
445 uint32_t *val);
446 #endif
447
448 #ifdef CONFIG_UART_DRV_CMD
449 int (*drv_cmd)(const struct device *dev, uint32_t cmd, uint32_t p);
450 #endif
451
452 };
453
454 /** @endcond */
455
456 /**
457 * @brief Check whether an error was detected.
458 *
459 * @param dev UART device instance.
460 *
461 * @retval 0 If no error was detected.
462 * @retval err Error flags as defined in @ref uart_rx_stop_reason
463 * @retval -ENOSYS If not implemented.
464 */
465 __syscall int uart_err_check(const struct device *dev);
466
z_impl_uart_err_check(const struct device * dev)467 static inline int z_impl_uart_err_check(const struct device *dev)
468 {
469 const struct uart_driver_api *api =
470 (const struct uart_driver_api *)dev->api;
471
472 if (api->err_check == NULL) {
473 return -ENOSYS;
474 }
475
476 return api->err_check(dev);
477 }
478
479 /**
480 * @defgroup uart_polling Polling UART API
481 * @{
482 */
483
484 /**
485 * @brief Read a character from the device for input.
486 *
487 * This routine checks if the receiver has valid data. When the
488 * receiver has valid data, it reads a character from the device,
489 * stores to the location pointed to by p_char, and returns 0 to the
490 * calling thread. It returns -1, otherwise. This function is a
491 * non-blocking call.
492 *
493 * @param dev UART device instance.
494 * @param p_char Pointer to character.
495 *
496 * @retval 0 If a character arrived.
497 * @retval -1 If no character was available to read (i.e. the UART
498 * input buffer was empty).
499 * @retval -ENOSYS If the operation is not implemented.
500 * @retval -EBUSY If async reception was enabled using @ref uart_rx_enable
501 */
502 __syscall int uart_poll_in(const struct device *dev, unsigned char *p_char);
503
z_impl_uart_poll_in(const struct device * dev,unsigned char * p_char)504 static inline int z_impl_uart_poll_in(const struct device *dev,
505 unsigned char *p_char)
506 {
507 const struct uart_driver_api *api =
508 (const struct uart_driver_api *)dev->api;
509
510 if (api->poll_in == NULL) {
511 return -ENOSYS;
512 }
513
514 return api->poll_in(dev, p_char);
515 }
516
517 /**
518 * @brief Read a 16-bit datum from the device for input.
519 *
520 * This routine checks if the receiver has valid data. When the
521 * receiver has valid data, it reads a 16-bit datum from the device,
522 * stores to the location pointed to by p_u16, and returns 0 to the
523 * calling thread. It returns -1, otherwise. This function is a
524 * non-blocking call.
525 *
526 * @param dev UART device instance.
527 * @param p_u16 Pointer to 16-bit data.
528 *
529 * @retval 0 If data arrived.
530 * @retval -1 If no data was available to read (i.e., the UART
531 * input buffer was empty).
532 * @retval -ENOTSUP If API is not enabled.
533 * @retval -ENOSYS If the function is not implemented.
534 * @retval -EBUSY If async reception was enabled using @ref uart_rx_enable
535 */
536 __syscall int uart_poll_in_u16(const struct device *dev, uint16_t *p_u16);
537
z_impl_uart_poll_in_u16(const struct device * dev,uint16_t * p_u16)538 static inline int z_impl_uart_poll_in_u16(const struct device *dev,
539 uint16_t *p_u16)
540 {
541 #ifdef CONFIG_UART_WIDE_DATA
542 const struct uart_driver_api *api =
543 (const struct uart_driver_api *)dev->api;
544
545 if (api->poll_in_u16 == NULL) {
546 return -ENOSYS;
547 }
548
549 return api->poll_in_u16(dev, p_u16);
550 #else
551 ARG_UNUSED(dev);
552 ARG_UNUSED(p_u16);
553 return -ENOTSUP;
554 #endif
555 }
556
557 /**
558 * @brief Write a character to the device for output.
559 *
560 * This routine checks if the transmitter is full. When the
561 * transmitter is not full, it writes a character to the data
562 * register. It waits and blocks the calling thread, otherwise. This
563 * function is a blocking call.
564 *
565 * To send a character when hardware flow control is enabled, the handshake
566 * signal CTS must be asserted.
567 *
568 * @param dev UART device instance.
569 * @param out_char Character to send.
570 */
571 __syscall void uart_poll_out(const struct device *dev,
572 unsigned char out_char);
573
z_impl_uart_poll_out(const struct device * dev,unsigned char out_char)574 static inline void z_impl_uart_poll_out(const struct device *dev,
575 unsigned char out_char)
576 {
577 const struct uart_driver_api *api =
578 (const struct uart_driver_api *)dev->api;
579
580 api->poll_out(dev, out_char);
581 }
582
583 /**
584 * @brief Write a 16-bit datum to the device for output.
585 *
586 * This routine checks if the transmitter is full. When the
587 * transmitter is not full, it writes a 16-bit datum to the data
588 * register. It waits and blocks the calling thread, otherwise. This
589 * function is a blocking call.
590 *
591 * To send a datum when hardware flow control is enabled, the handshake
592 * signal CTS must be asserted.
593 *
594 * @param dev UART device instance.
595 * @param out_u16 Wide data to send.
596 */
597 __syscall void uart_poll_out_u16(const struct device *dev, uint16_t out_u16);
598
z_impl_uart_poll_out_u16(const struct device * dev,uint16_t out_u16)599 static inline void z_impl_uart_poll_out_u16(const struct device *dev,
600 uint16_t out_u16)
601 {
602 #ifdef CONFIG_UART_WIDE_DATA
603 const struct uart_driver_api *api =
604 (const struct uart_driver_api *)dev->api;
605
606 api->poll_out_u16(dev, out_u16);
607 #else
608 ARG_UNUSED(dev);
609 ARG_UNUSED(out_u16);
610 #endif
611 }
612
613 /**
614 * @}
615 */
616
617 /**
618 * @brief Set UART configuration.
619 *
620 * Sets UART configuration using data from *cfg.
621 *
622 * @param dev UART device instance.
623 * @param cfg UART configuration structure.
624 *
625 * @retval 0 If successful.
626 * @retval -errno Negative errno code in case of failure.
627 * @retval -ENOSYS If configuration is not supported by device
628 * or driver does not support setting configuration in runtime.
629 * @retval -ENOTSUP If API is not enabled.
630 */
631 __syscall int uart_configure(const struct device *dev,
632 const struct uart_config *cfg);
633
z_impl_uart_configure(const struct device * dev,const struct uart_config * cfg)634 static inline int z_impl_uart_configure(const struct device *dev,
635 const struct uart_config *cfg)
636 {
637 #ifdef CONFIG_UART_USE_RUNTIME_CONFIGURE
638 const struct uart_driver_api *api =
639 (const struct uart_driver_api *)dev->api;
640
641 if (api->configure == NULL) {
642 return -ENOSYS;
643 }
644 return api->configure(dev, cfg);
645 #else
646 ARG_UNUSED(dev);
647 ARG_UNUSED(cfg);
648 return -ENOTSUP;
649 #endif
650 }
651
652 /**
653 * @brief Get UART configuration.
654 *
655 * Stores current UART configuration to *cfg, can be used to retrieve initial
656 * configuration after device was initialized using data from DTS.
657 *
658 * @param dev UART device instance.
659 * @param cfg UART configuration structure.
660 *
661 * @retval 0 If successful.
662 * @retval -errno Negative errno code in case of failure.
663 * @retval -ENOSYS If driver does not support getting current configuration.
664 * @retval -ENOTSUP If API is not enabled.
665 */
666 __syscall int uart_config_get(const struct device *dev,
667 struct uart_config *cfg);
668
z_impl_uart_config_get(const struct device * dev,struct uart_config * cfg)669 static inline int z_impl_uart_config_get(const struct device *dev,
670 struct uart_config *cfg)
671 {
672 #ifdef CONFIG_UART_USE_RUNTIME_CONFIGURE
673 const struct uart_driver_api *api =
674 (const struct uart_driver_api *)dev->api;
675
676 if (api->config_get == NULL) {
677 return -ENOSYS;
678 }
679
680 return api->config_get(dev, cfg);
681 #else
682 ARG_UNUSED(dev);
683 ARG_UNUSED(cfg);
684 return -ENOTSUP;
685 #endif
686 }
687
688 /**
689 * @addtogroup uart_interrupt
690 * @{
691 */
692
693 /**
694 * @brief Fill FIFO with data.
695 *
696 * @details This function is expected to be called from UART
697 * interrupt handler (ISR), if uart_irq_tx_ready() returns true.
698 * Result of calling this function not from an ISR is undefined
699 * (hardware-dependent). Likewise, *not* calling this function
700 * from an ISR if uart_irq_tx_ready() returns true may lead to
701 * undefined behavior, e.g. infinite interrupt loops. It's
702 * mandatory to test return value of this function, as different
703 * hardware has different FIFO depth (oftentimes just 1).
704 *
705 * @param dev UART device instance.
706 * @param tx_data Data to transmit.
707 * @param size Number of bytes to send.
708 *
709 * @return Number of bytes sent.
710 * @retval -ENOSYS if this function is not supported
711 * @retval -ENOTSUP If API is not enabled.
712 */
uart_fifo_fill(const struct device * dev,const uint8_t * tx_data,int size)713 static inline int uart_fifo_fill(const struct device *dev,
714 const uint8_t *tx_data,
715 int size)
716 {
717 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
718 const struct uart_driver_api *api =
719 (const struct uart_driver_api *)dev->api;
720
721 if (api->fifo_fill == NULL) {
722 return -ENOSYS;
723 }
724
725 return api->fifo_fill(dev, tx_data, size);
726 #else
727 ARG_UNUSED(dev);
728 ARG_UNUSED(tx_data);
729 ARG_UNUSED(size);
730 return -ENOTSUP;
731 #endif
732 }
733
734 /**
735 * @brief Fill FIFO with wide data.
736 *
737 * @details This function is expected to be called from UART
738 * interrupt handler (ISR), if uart_irq_tx_ready() returns true.
739 * Result of calling this function not from an ISR is undefined
740 * (hardware-dependent). Likewise, *not* calling this function
741 * from an ISR if uart_irq_tx_ready() returns true may lead to
742 * undefined behavior, e.g. infinite interrupt loops. It's
743 * mandatory to test return value of this function, as different
744 * hardware has different FIFO depth (oftentimes just 1).
745 *
746 * @param dev UART device instance.
747 * @param tx_data Wide data to transmit.
748 * @param size Number of datum to send.
749 *
750 * @return Number of datum sent.
751 * @retval -ENOSYS If this function is not implemented
752 * @retval -ENOTSUP If API is not enabled.
753 */
uart_fifo_fill_u16(const struct device * dev,const uint16_t * tx_data,int size)754 static inline int uart_fifo_fill_u16(const struct device *dev,
755 const uint16_t *tx_data,
756 int size)
757 {
758 #if defined(CONFIG_UART_INTERRUPT_DRIVEN) && defined(CONFIG_UART_WIDE_DATA)
759 const struct uart_driver_api *api =
760 (const struct uart_driver_api *)dev->api;
761
762 if (api->fifo_fill_u16 == NULL) {
763 return -ENOSYS;
764 }
765
766 return api->fifo_fill_u16(dev, tx_data, size);
767 #else
768 ARG_UNUSED(dev);
769 ARG_UNUSED(tx_data);
770 ARG_UNUSED(size);
771 return -ENOTSUP;
772 #endif
773 }
774
775 /**
776 * @brief Read data from FIFO.
777 *
778 * @details This function is expected to be called from UART
779 * interrupt handler (ISR), if uart_irq_rx_ready() returns true.
780 * Result of calling this function not from an ISR is undefined
781 * (hardware-dependent). It's unspecified whether "RX ready"
782 * condition as returned by uart_irq_rx_ready() is level- or
783 * edge- triggered. That means that once uart_irq_rx_ready() is
784 * detected, uart_fifo_read() must be called until it reads all
785 * available data in the FIFO (i.e. until it returns less data
786 * than was requested).
787 *
788 * @param dev UART device instance.
789 * @param rx_data Data container.
790 * @param size Container size.
791 *
792 * @return Number of bytes read.
793 * @retval -ENOSYS If this function is not implemented.
794 * @retval -ENOTSUP If API is not enabled.
795 */
uart_fifo_read(const struct device * dev,uint8_t * rx_data,const int size)796 static inline int uart_fifo_read(const struct device *dev, uint8_t *rx_data,
797 const int size)
798 {
799 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
800 const struct uart_driver_api *api =
801 (const struct uart_driver_api *)dev->api;
802
803 if (api->fifo_read == NULL) {
804 return -ENOSYS;
805 }
806
807 return api->fifo_read(dev, rx_data, size);
808 #else
809 ARG_UNUSED(dev);
810 ARG_UNUSED(rx_data);
811 ARG_UNUSED(size);
812 return -ENOTSUP;
813 #endif
814 }
815
816 /**
817 * @brief Read wide data from FIFO.
818 *
819 * @details This function is expected to be called from UART
820 * interrupt handler (ISR), if uart_irq_rx_ready() returns true.
821 * Result of calling this function not from an ISR is undefined
822 * (hardware-dependent). It's unspecified whether "RX ready"
823 * condition as returned by uart_irq_rx_ready() is level- or
824 * edge- triggered. That means that once uart_irq_rx_ready() is
825 * detected, uart_fifo_read() must be called until it reads all
826 * available data in the FIFO (i.e. until it returns less data
827 * than was requested).
828 *
829 * @param dev UART device instance.
830 * @param rx_data Wide data container.
831 * @param size Container size.
832 *
833 * @return Number of datum read.
834 * @retval -ENOSYS If this function is not implemented.
835 * @retval -ENOTSUP If API is not enabled.
836 */
uart_fifo_read_u16(const struct device * dev,uint16_t * rx_data,const int size)837 static inline int uart_fifo_read_u16(const struct device *dev,
838 uint16_t *rx_data,
839 const int size)
840 {
841 #if defined(CONFIG_UART_INTERRUPT_DRIVEN) && defined(CONFIG_UART_WIDE_DATA)
842 const struct uart_driver_api *api =
843 (const struct uart_driver_api *)dev->api;
844
845 if (api->fifo_read_u16 == NULL) {
846 return -ENOSYS;
847 }
848
849 return api->fifo_read_u16(dev, rx_data, size);
850 #else
851 ARG_UNUSED(dev);
852 ARG_UNUSED(rx_data);
853 ARG_UNUSED(size);
854 return -ENOTSUP;
855 #endif
856 }
857
858 /**
859 * @brief Enable TX interrupt in IER.
860 *
861 * @param dev UART device instance.
862 */
863 __syscall void uart_irq_tx_enable(const struct device *dev);
864
z_impl_uart_irq_tx_enable(const struct device * dev)865 static inline void z_impl_uart_irq_tx_enable(const struct device *dev)
866 {
867 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
868 const struct uart_driver_api *api =
869 (const struct uart_driver_api *)dev->api;
870
871 if (api->irq_tx_enable != NULL) {
872 api->irq_tx_enable(dev);
873 }
874 #else
875 ARG_UNUSED(dev);
876 #endif
877 }
878
879 /**
880 * @brief Disable TX interrupt in IER.
881 *
882 * @param dev UART device instance.
883 */
884 __syscall void uart_irq_tx_disable(const struct device *dev);
885
z_impl_uart_irq_tx_disable(const struct device * dev)886 static inline void z_impl_uart_irq_tx_disable(const struct device *dev)
887 {
888 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
889 const struct uart_driver_api *api =
890 (const struct uart_driver_api *)dev->api;
891
892 if (api->irq_tx_disable != NULL) {
893 api->irq_tx_disable(dev);
894 }
895 #else
896 ARG_UNUSED(dev);
897 #endif
898 }
899
900 /**
901 * @brief Check if UART TX buffer can accept a new char
902 *
903 * @details Check if UART TX buffer can accept at least one character
904 * for transmission (i.e. uart_fifo_fill() will succeed and return
905 * non-zero). This function must be called in a UART interrupt
906 * handler, or its result is undefined. Before calling this function
907 * in the interrupt handler, uart_irq_update() must be called once per
908 * the handler invocation.
909 *
910 * @param dev UART device instance.
911 *
912 * @retval 1 If TX interrupt is enabled and at least one char can be
913 * written to UART.
914 * @retval 0 If device is not ready to write a new byte.
915 * @retval -ENOSYS If this function is not implemented.
916 * @retval -ENOTSUP If API is not enabled.
917 */
uart_irq_tx_ready(const struct device * dev)918 static inline int uart_irq_tx_ready(const struct device *dev)
919 {
920 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
921 const struct uart_driver_api *api =
922 (const struct uart_driver_api *)dev->api;
923
924 if (api->irq_tx_ready == NULL) {
925 return -ENOSYS;
926 }
927
928 return api->irq_tx_ready(dev);
929 #else
930 ARG_UNUSED(dev);
931 return -ENOTSUP;
932 #endif
933 }
934
935 /**
936 * @brief Enable RX interrupt.
937 *
938 * @param dev UART device instance.
939 */
940 __syscall void uart_irq_rx_enable(const struct device *dev);
941
z_impl_uart_irq_rx_enable(const struct device * dev)942 static inline void z_impl_uart_irq_rx_enable(const struct device *dev)
943 {
944 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
945 const struct uart_driver_api *api =
946 (const struct uart_driver_api *)dev->api;
947
948 if (api->irq_rx_enable != NULL) {
949 api->irq_rx_enable(dev);
950 }
951 #else
952 ARG_UNUSED(dev);
953 #endif
954 }
955
956 /**
957 * @brief Disable RX interrupt.
958 *
959 * @param dev UART device instance.
960 */
961 __syscall void uart_irq_rx_disable(const struct device *dev);
962
z_impl_uart_irq_rx_disable(const struct device * dev)963 static inline void z_impl_uart_irq_rx_disable(const struct device *dev)
964 {
965 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
966 const struct uart_driver_api *api =
967 (const struct uart_driver_api *)dev->api;
968
969 if (api->irq_rx_disable != NULL) {
970 api->irq_rx_disable(dev);
971 }
972 #else
973 ARG_UNUSED(dev);
974 #endif
975 }
976
977 /**
978 * @brief Check if UART TX block finished transmission
979 *
980 * @details Check if any outgoing data buffered in UART TX block was
981 * fully transmitted and TX block is idle. When this condition is
982 * true, UART device (or whole system) can be power off. Note that
983 * this function is *not* useful to check if UART TX can accept more
984 * data, use uart_irq_tx_ready() for that. This function must be called
985 * in a UART interrupt handler, or its result is undefined. Before
986 * calling this function in the interrupt handler, uart_irq_update()
987 * must be called once per the handler invocation.
988 *
989 * @param dev UART device instance.
990 *
991 * @retval 1 If nothing remains to be transmitted.
992 * @retval 0 If transmission is not completed.
993 * @retval -ENOSYS If this function is not implemented.
994 * @retval -ENOTSUP If API is not enabled.
995 */
uart_irq_tx_complete(const struct device * dev)996 static inline int uart_irq_tx_complete(const struct device *dev)
997 {
998 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
999 const struct uart_driver_api *api =
1000 (const struct uart_driver_api *)dev->api;
1001
1002 if (api->irq_tx_complete == NULL) {
1003 return -ENOSYS;
1004 }
1005 return api->irq_tx_complete(dev);
1006 #else
1007 ARG_UNUSED(dev);
1008 return -ENOTSUP;
1009 #endif
1010 }
1011
1012 /**
1013 * @brief Check if UART RX buffer has a received char
1014 *
1015 * @details Check if UART RX buffer has at least one pending character
1016 * (i.e. uart_fifo_read() will succeed and return non-zero). This function
1017 * must be called in a UART interrupt handler, or its result is undefined.
1018 * Before calling this function in the interrupt handler, uart_irq_update()
1019 * must be called once per the handler invocation. It's unspecified whether
1020 * condition as returned by this function is level- or edge- triggered (i.e.
1021 * if this function returns true when RX FIFO is non-empty, or when a new
1022 * char was received since last call to it). See description of
1023 * uart_fifo_read() for implication of this.
1024 *
1025 * @param dev UART device instance.
1026 *
1027 * @retval 1 If a received char is ready.
1028 * @retval 0 If a received char is not ready.
1029 * @retval -ENOSYS If this function is not implemented.
1030 * @retval -ENOTSUP If API is not enabled.
1031 */
uart_irq_rx_ready(const struct device * dev)1032 static inline int uart_irq_rx_ready(const struct device *dev)
1033 {
1034 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
1035 const struct uart_driver_api *api =
1036 (const struct uart_driver_api *)dev->api;
1037
1038 if (api->irq_rx_ready == NULL) {
1039 return -ENOSYS;
1040 }
1041 return api->irq_rx_ready(dev);
1042 #else
1043 ARG_UNUSED(dev);
1044 return -ENOTSUP;
1045 #endif
1046 }
1047 /**
1048 * @brief Enable error interrupt.
1049 *
1050 * @param dev UART device instance.
1051 */
1052 __syscall void uart_irq_err_enable(const struct device *dev);
1053
z_impl_uart_irq_err_enable(const struct device * dev)1054 static inline void z_impl_uart_irq_err_enable(const struct device *dev)
1055 {
1056 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
1057 const struct uart_driver_api *api =
1058 (const struct uart_driver_api *)dev->api;
1059
1060 if (api->irq_err_enable) {
1061 api->irq_err_enable(dev);
1062 }
1063 #else
1064 ARG_UNUSED(dev);
1065 #endif
1066 }
1067
1068 /**
1069 * @brief Disable error interrupt.
1070 *
1071 * @param dev UART device instance.
1072 */
1073 __syscall void uart_irq_err_disable(const struct device *dev);
1074
z_impl_uart_irq_err_disable(const struct device * dev)1075 static inline void z_impl_uart_irq_err_disable(const struct device *dev)
1076 {
1077 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
1078 const struct uart_driver_api *api =
1079 (const struct uart_driver_api *)dev->api;
1080
1081 if (api->irq_err_disable) {
1082 api->irq_err_disable(dev);
1083 }
1084 #else
1085 ARG_UNUSED(dev);
1086 #endif
1087 }
1088
1089 /**
1090 * @brief Check if any IRQs is pending.
1091 *
1092 * @param dev UART device instance.
1093 *
1094 * @retval 1 If an IRQ is pending.
1095 * @retval 0 If an IRQ is not pending.
1096 * @retval -ENOSYS If this function is not implemented.
1097 * @retval -ENOTSUP If API is not enabled.
1098 */
1099 __syscall int uart_irq_is_pending(const struct device *dev);
1100
z_impl_uart_irq_is_pending(const struct device * dev)1101 static inline int z_impl_uart_irq_is_pending(const struct device *dev)
1102 {
1103 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
1104 const struct uart_driver_api *api =
1105 (const struct uart_driver_api *)dev->api;
1106
1107 if (api->irq_is_pending == NULL) {
1108 return -ENOSYS;
1109 }
1110 return api->irq_is_pending(dev);
1111 #else
1112 ARG_UNUSED(dev);
1113 return -ENOTSUP;
1114 #endif
1115 }
1116
1117 /**
1118 * @brief Start processing interrupts in ISR.
1119 *
1120 * This function should be called the first thing in the ISR. Calling
1121 * uart_irq_rx_ready(), uart_irq_tx_ready(), uart_irq_tx_complete()
1122 * allowed only after this.
1123 *
1124 * The purpose of this function is:
1125 *
1126 * * For devices with auto-acknowledge of interrupt status on register
1127 * read to cache the value of this register (rx_ready, etc. then use
1128 * this case).
1129 * * For devices with explicit acknowledgment of interrupts, to ack
1130 * any pending interrupts and likewise to cache the original value.
1131 * * For devices with implicit acknowledgment, this function will be
1132 * empty. But the ISR must perform the actions needs to ack the
1133 * interrupts (usually, call uart_fifo_read() on rx_ready, and
1134 * uart_fifo_fill() on tx_ready).
1135 *
1136 * @param dev UART device instance.
1137 *
1138 * @retval 1 On success.
1139 * @retval -ENOSYS If this function is not implemented.
1140 * @retval -ENOTSUP If API is not enabled.
1141 */
1142 __syscall int uart_irq_update(const struct device *dev);
1143
z_impl_uart_irq_update(const struct device * dev)1144 static inline int z_impl_uart_irq_update(const struct device *dev)
1145 {
1146 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
1147 const struct uart_driver_api *api =
1148 (const struct uart_driver_api *)dev->api;
1149
1150 if (api->irq_update == NULL) {
1151 return -ENOSYS;
1152 }
1153 return api->irq_update(dev);
1154 #else
1155 ARG_UNUSED(dev);
1156 return -ENOTSUP;
1157 #endif
1158 }
1159
1160 /**
1161 * @brief Set the IRQ callback function pointer.
1162 *
1163 * This sets up the callback for IRQ. When an IRQ is triggered,
1164 * the specified function will be called with specified user data.
1165 * See description of uart_irq_update() for the requirements on ISR.
1166 *
1167 * @param dev UART device instance.
1168 * @param cb Pointer to the callback function.
1169 * @param user_data Data to pass to callback function.
1170 *
1171 * @retval 0 On success.
1172 * @retval -ENOSYS If this function is not implemented.
1173 * @retval -ENOTSUP If API is not enabled.
1174 */
uart_irq_callback_user_data_set(const struct device * dev,uart_irq_callback_user_data_t cb,void * user_data)1175 static inline int uart_irq_callback_user_data_set(const struct device *dev,
1176 uart_irq_callback_user_data_t cb,
1177 void *user_data)
1178 {
1179 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
1180 const struct uart_driver_api *api =
1181 (const struct uart_driver_api *)dev->api;
1182
1183 if ((api != NULL) && (api->irq_callback_set != NULL)) {
1184 api->irq_callback_set(dev, cb, user_data);
1185 return 0;
1186 } else {
1187 return -ENOSYS;
1188 }
1189 #else
1190 ARG_UNUSED(dev);
1191 ARG_UNUSED(cb);
1192 ARG_UNUSED(user_data);
1193 return -ENOTSUP;
1194 #endif
1195 }
1196
1197 /**
1198 * @brief Set the IRQ callback function pointer (legacy).
1199 *
1200 * This sets up the callback for IRQ. When an IRQ is triggered,
1201 * the specified function will be called with the device pointer.
1202 *
1203 * @param dev UART device instance.
1204 * @param cb Pointer to the callback function.
1205 *
1206 * @retval 0 On success.
1207 * @retval -ENOSYS If this function is not implemented.
1208 * @retval -ENOTSUP If API is not enabled.
1209 */
uart_irq_callback_set(const struct device * dev,uart_irq_callback_user_data_t cb)1210 static inline int uart_irq_callback_set(const struct device *dev,
1211 uart_irq_callback_user_data_t cb)
1212 {
1213 return uart_irq_callback_user_data_set(dev, cb, NULL);
1214 }
1215
1216 /**
1217 * @}
1218 */
1219
1220 /**
1221 * @addtogroup uart_async
1222 * @{
1223 */
1224
1225 /**
1226 * @brief Set event handler function.
1227 *
1228 * Since it is mandatory to set callback to use other asynchronous functions,
1229 * it can be used to detect if the device supports asynchronous API. Remaining
1230 * API does not have that detection.
1231 *
1232 * @param dev UART device instance.
1233 * @param callback Event handler.
1234 * @param user_data Data to pass to event handler function.
1235 *
1236 * @retval 0 If successful.
1237 * @retval -ENOSYS If not supported by the device.
1238 * @retval -ENOTSUP If API not enabled.
1239 */
uart_callback_set(const struct device * dev,uart_callback_t callback,void * user_data)1240 static inline int uart_callback_set(const struct device *dev,
1241 uart_callback_t callback,
1242 void *user_data)
1243 {
1244 #ifdef CONFIG_UART_ASYNC_API
1245 const struct uart_driver_api *api =
1246 (const struct uart_driver_api *)dev->api;
1247
1248 if (api->callback_set == NULL) {
1249 return -ENOSYS;
1250 }
1251
1252 return api->callback_set(dev, callback, user_data);
1253 #else
1254 ARG_UNUSED(dev);
1255 ARG_UNUSED(callback);
1256 ARG_UNUSED(user_data);
1257 return -ENOTSUP;
1258 #endif
1259 }
1260
1261 /**
1262 * @brief Send given number of bytes from buffer through UART.
1263 *
1264 * Function returns immediately and event handler,
1265 * set using @ref uart_callback_set, is called after transfer is finished.
1266 *
1267 * @param dev UART device instance.
1268 * @param buf Pointer to transmit buffer.
1269 * @param len Length of transmit buffer.
1270 * @param timeout Timeout in microseconds. Valid only if flow control is
1271 * enabled. @ref SYS_FOREVER_US disables timeout.
1272 *
1273 * @retval 0 If successful.
1274 * @retval -ENOTSUP If API is not enabled.
1275 * @retval -EBUSY If There is already an ongoing transfer.
1276 * @retval -errno Other negative errno value in case of failure.
1277 */
1278 __syscall int uart_tx(const struct device *dev, const uint8_t *buf,
1279 size_t len,
1280 int32_t timeout);
1281
z_impl_uart_tx(const struct device * dev,const uint8_t * buf,size_t len,int32_t timeout)1282 static inline int z_impl_uart_tx(const struct device *dev, const uint8_t *buf,
1283 size_t len, int32_t timeout)
1284
1285 {
1286 #ifdef CONFIG_UART_ASYNC_API
1287 const struct uart_driver_api *api =
1288 (const struct uart_driver_api *)dev->api;
1289
1290 return api->tx(dev, buf, len, timeout);
1291 #else
1292 ARG_UNUSED(dev);
1293 ARG_UNUSED(buf);
1294 ARG_UNUSED(len);
1295 ARG_UNUSED(timeout);
1296 return -ENOTSUP;
1297 #endif
1298 }
1299
1300 /**
1301 * @brief Send given number of datum from buffer through UART.
1302 *
1303 * Function returns immediately and event handler,
1304 * set using @ref uart_callback_set, is called after transfer is finished.
1305 *
1306 * @param dev UART device instance.
1307 * @param buf Pointer to wide data transmit buffer.
1308 * @param len Length of wide data transmit buffer.
1309 * @param timeout Timeout in milliseconds. Valid only if flow control is
1310 * enabled. @ref SYS_FOREVER_MS disables timeout.
1311 *
1312 * @retval 0 If successful.
1313 * @retval -ENOTSUP If API is not enabled.
1314 * @retval -EBUSY If there is already an ongoing transfer.
1315 * @retval -errno Other negative errno value in case of failure.
1316 */
1317 __syscall int uart_tx_u16(const struct device *dev, const uint16_t *buf,
1318 size_t len, int32_t timeout);
1319
z_impl_uart_tx_u16(const struct device * dev,const uint16_t * buf,size_t len,int32_t timeout)1320 static inline int z_impl_uart_tx_u16(const struct device *dev,
1321 const uint16_t *buf,
1322 size_t len, int32_t timeout)
1323
1324 {
1325 #if defined(CONFIG_UART_ASYNC_API) && defined(CONFIG_UART_WIDE_DATA)
1326 const struct uart_driver_api *api =
1327 (const struct uart_driver_api *)dev->api;
1328
1329 return api->tx_u16(dev, buf, len, timeout);
1330 #else
1331 ARG_UNUSED(dev);
1332 ARG_UNUSED(buf);
1333 ARG_UNUSED(len);
1334 ARG_UNUSED(timeout);
1335 return -ENOTSUP;
1336 #endif
1337 }
1338
1339 /**
1340 * @brief Abort current TX transmission.
1341 *
1342 * #UART_TX_DONE event will be generated with amount of data sent.
1343 *
1344 * @param dev UART device instance.
1345 *
1346 * @retval 0 If successful.
1347 * @retval -ENOTSUP If API is not enabled.
1348 * @retval -EFAULT There is no active transmission.
1349 * @retval -errno Other negative errno value in case of failure.
1350 */
1351 __syscall int uart_tx_abort(const struct device *dev);
1352
z_impl_uart_tx_abort(const struct device * dev)1353 static inline int z_impl_uart_tx_abort(const struct device *dev)
1354 {
1355 #ifdef CONFIG_UART_ASYNC_API
1356 const struct uart_driver_api *api =
1357 (const struct uart_driver_api *)dev->api;
1358
1359 return api->tx_abort(dev);
1360 #else
1361 ARG_UNUSED(dev);
1362 return -ENOTSUP;
1363 #endif
1364 }
1365
1366 /**
1367 * @brief Start receiving data through UART.
1368 *
1369 * Function sets given buffer as first buffer for receiving and returns
1370 * immediately. After that event handler, set using @ref uart_callback_set,
1371 * is called with #UART_RX_RDY or #UART_RX_BUF_REQUEST events.
1372 *
1373 * @param dev UART device instance.
1374 * @param buf Pointer to receive buffer.
1375 * @param len Buffer length.
1376 * @param timeout Inactivity period after receiving at least a byte which
1377 * triggers #UART_RX_RDY event. Given in microseconds.
1378 * @ref SYS_FOREVER_US disables timeout. See @ref uart_event_type
1379 * for details.
1380 *
1381 * @retval 0 If successful.
1382 * @retval -ENOTSUP If API is not enabled.
1383 * @retval -EBUSY RX already in progress.
1384 * @retval -errno Other negative errno value in case of failure.
1385 *
1386 */
1387 __syscall int uart_rx_enable(const struct device *dev, uint8_t *buf,
1388 size_t len,
1389 int32_t timeout);
1390
z_impl_uart_rx_enable(const struct device * dev,uint8_t * buf,size_t len,int32_t timeout)1391 static inline int z_impl_uart_rx_enable(const struct device *dev,
1392 uint8_t *buf,
1393 size_t len, int32_t timeout)
1394 {
1395 #ifdef CONFIG_UART_ASYNC_API
1396 const struct uart_driver_api *api =
1397 (const struct uart_driver_api *)dev->api;
1398
1399 return api->rx_enable(dev, buf, len, timeout);
1400 #else
1401 ARG_UNUSED(dev);
1402 ARG_UNUSED(buf);
1403 ARG_UNUSED(len);
1404 ARG_UNUSED(timeout);
1405 return -ENOTSUP;
1406 #endif
1407 }
1408
1409 /**
1410 * @brief Start receiving wide data through UART.
1411 *
1412 * Function sets given buffer as first buffer for receiving and returns
1413 * immediately. After that event handler, set using @ref uart_callback_set,
1414 * is called with #UART_RX_RDY or #UART_RX_BUF_REQUEST events.
1415 *
1416 * @param dev UART device instance.
1417 * @param buf Pointer to wide data receive buffer.
1418 * @param len Buffer length.
1419 * @param timeout Inactivity period after receiving at least a byte which
1420 * triggers #UART_RX_RDY event. Given in milliseconds.
1421 * @ref SYS_FOREVER_MS disables timeout. See
1422 * @ref uart_event_type for details.
1423 *
1424 * @retval 0 If successful.
1425 * @retval -ENOTSUP If API is not enabled.
1426 * @retval -EBUSY RX already in progress.
1427 * @retval -errno Other negative errno value in case of failure.
1428 *
1429 */
1430 __syscall int uart_rx_enable_u16(const struct device *dev, uint16_t *buf,
1431 size_t len, int32_t timeout);
1432
z_impl_uart_rx_enable_u16(const struct device * dev,uint16_t * buf,size_t len,int32_t timeout)1433 static inline int z_impl_uart_rx_enable_u16(const struct device *dev,
1434 uint16_t *buf, size_t len,
1435 int32_t timeout)
1436 {
1437 #if defined(CONFIG_UART_ASYNC_API) && defined(CONFIG_UART_WIDE_DATA)
1438 const struct uart_driver_api *api =
1439 (const struct uart_driver_api *)dev->api;
1440
1441 return api->rx_enable_u16(dev, buf, len, timeout);
1442 #else
1443 ARG_UNUSED(dev);
1444 ARG_UNUSED(buf);
1445 ARG_UNUSED(len);
1446 ARG_UNUSED(timeout);
1447 return -ENOTSUP;
1448 #endif
1449 }
1450
1451 /**
1452 * @brief Provide receive buffer in response to #UART_RX_BUF_REQUEST event.
1453 *
1454 * Provide pointer to RX buffer, which will be used when current buffer is
1455 * filled.
1456 *
1457 * @note Providing buffer that is already in usage by driver leads to
1458 * undefined behavior. Buffer can be reused when it has been released
1459 * by driver.
1460 *
1461 * @param dev UART device instance.
1462 * @param buf Pointer to receive buffer.
1463 * @param len Buffer length.
1464 *
1465 * @retval 0 If successful.
1466 * @retval -ENOTSUP If API is not enabled.
1467 * @retval -EBUSY Next buffer already set.
1468 * @retval -EACCES Receiver is already disabled (function called too late?).
1469 * @retval -errno Other negative errno value in case of failure.
1470 */
uart_rx_buf_rsp(const struct device * dev,uint8_t * buf,size_t len)1471 static inline int uart_rx_buf_rsp(const struct device *dev, uint8_t *buf,
1472 size_t len)
1473 {
1474 #ifdef CONFIG_UART_ASYNC_API
1475 const struct uart_driver_api *api =
1476 (const struct uart_driver_api *)dev->api;
1477
1478 return api->rx_buf_rsp(dev, buf, len);
1479 #else
1480 ARG_UNUSED(dev);
1481 ARG_UNUSED(buf);
1482 ARG_UNUSED(len);
1483 return -ENOTSUP;
1484 #endif
1485 }
1486
1487 /**
1488 * @brief Provide wide data receive buffer in response to #UART_RX_BUF_REQUEST
1489 * event.
1490 *
1491 * Provide pointer to RX buffer, which will be used when current buffer is
1492 * filled.
1493 *
1494 * @note Providing buffer that is already in usage by driver leads to
1495 * undefined behavior. Buffer can be reused when it has been released
1496 * by driver.
1497 *
1498 * @param dev UART device instance.
1499 * @param buf Pointer to wide data receive buffer.
1500 * @param len Buffer length.
1501 *
1502 * @retval 0 If successful.
1503 * @retval -ENOTSUP If API is not enabled
1504 * @retval -EBUSY Next buffer already set.
1505 * @retval -EACCES Receiver is already disabled (function called too late?).
1506 * @retval -errno Other negative errno value in case of failure.
1507 */
uart_rx_buf_rsp_u16(const struct device * dev,uint16_t * buf,size_t len)1508 static inline int uart_rx_buf_rsp_u16(const struct device *dev, uint16_t *buf,
1509 size_t len)
1510 {
1511 #if defined(CONFIG_UART_ASYNC_API) && defined(CONFIG_UART_WIDE_DATA)
1512 const struct uart_driver_api *api =
1513 (const struct uart_driver_api *)dev->api;
1514
1515 return api->rx_buf_rsp_u16(dev, buf, len);
1516 #else
1517 ARG_UNUSED(dev);
1518 ARG_UNUSED(buf);
1519 ARG_UNUSED(len);
1520 return -ENOTSUP;
1521 #endif
1522 }
1523
1524 /**
1525 * @brief Disable RX
1526 *
1527 * #UART_RX_BUF_RELEASED event will be generated for every buffer scheduled,
1528 * after that #UART_RX_DISABLED event will be generated. Additionally, if there
1529 * is any pending received data, the #UART_RX_RDY event for that data will be
1530 * generated before the #UART_RX_BUF_RELEASED events.
1531 *
1532 * @param dev UART device instance.
1533 *
1534 * @retval 0 If successful.
1535 * @retval -ENOTSUP If API is not enabled.
1536 * @retval -EFAULT There is no active reception.
1537 * @retval -errno Other negative errno value in case of failure.
1538 */
1539 __syscall int uart_rx_disable(const struct device *dev);
1540
z_impl_uart_rx_disable(const struct device * dev)1541 static inline int z_impl_uart_rx_disable(const struct device *dev)
1542 {
1543 #ifdef CONFIG_UART_ASYNC_API
1544 const struct uart_driver_api *api =
1545 (const struct uart_driver_api *)dev->api;
1546
1547 return api->rx_disable(dev);
1548 #else
1549 ARG_UNUSED(dev);
1550 return -ENOTSUP;
1551 #endif
1552 }
1553
1554 /**
1555 * @}
1556 */
1557
1558 /**
1559 * @brief Manipulate line control for UART.
1560 *
1561 * @param dev UART device instance.
1562 * @param ctrl The line control to manipulate (see enum uart_line_ctrl).
1563 * @param val Value to set to the line control.
1564 *
1565 * @retval 0 If successful.
1566 * @retval -ENOSYS If this function is not implemented.
1567 * @retval -ENOTSUP If API is not enabled.
1568 * @retval -errno Other negative errno value in case of failure.
1569 */
1570 __syscall int uart_line_ctrl_set(const struct device *dev,
1571 uint32_t ctrl, uint32_t val);
1572
z_impl_uart_line_ctrl_set(const struct device * dev,uint32_t ctrl,uint32_t val)1573 static inline int z_impl_uart_line_ctrl_set(const struct device *dev,
1574 uint32_t ctrl, uint32_t val)
1575 {
1576 #ifdef CONFIG_UART_LINE_CTRL
1577 const struct uart_driver_api *api =
1578 (const struct uart_driver_api *)dev->api;
1579
1580 if (api->line_ctrl_set == NULL) {
1581 return -ENOSYS;
1582 }
1583 return api->line_ctrl_set(dev, ctrl, val);
1584 #else
1585 ARG_UNUSED(dev);
1586 ARG_UNUSED(ctrl);
1587 ARG_UNUSED(val);
1588 return -ENOTSUP;
1589 #endif
1590 }
1591
1592 /**
1593 * @brief Retrieve line control for UART.
1594 *
1595 * @param dev UART device instance.
1596 * @param ctrl The line control to retrieve (see enum uart_line_ctrl).
1597 * @param val Pointer to variable where to store the line control value.
1598 *
1599 * @retval 0 If successful.
1600 * @retval -ENOSYS If this function is not implemented.
1601 * @retval -ENOTSUP If API is not enabled.
1602 * @retval -errno Other negative errno value in case of failure.
1603 */
1604 __syscall int uart_line_ctrl_get(const struct device *dev, uint32_t ctrl,
1605 uint32_t *val);
1606
z_impl_uart_line_ctrl_get(const struct device * dev,uint32_t ctrl,uint32_t * val)1607 static inline int z_impl_uart_line_ctrl_get(const struct device *dev,
1608 uint32_t ctrl, uint32_t *val)
1609 {
1610 #ifdef CONFIG_UART_LINE_CTRL
1611 const struct uart_driver_api *api =
1612 (const struct uart_driver_api *)dev->api;
1613
1614 if (api->line_ctrl_get == NULL) {
1615 return -ENOSYS;
1616 }
1617 return api->line_ctrl_get(dev, ctrl, val);
1618 #else
1619 ARG_UNUSED(dev);
1620 ARG_UNUSED(ctrl);
1621 ARG_UNUSED(val);
1622 return -ENOTSUP;
1623 #endif
1624 }
1625
1626 /**
1627 * @brief Send extra command to driver.
1628 *
1629 * Implementation and accepted commands are driver specific.
1630 * Refer to the drivers for more information.
1631 *
1632 * @param dev UART device instance.
1633 * @param cmd Command to driver.
1634 * @param p Parameter to the command.
1635 *
1636 * @retval 0 If successful.
1637 * @retval -ENOSYS If this function is not implemented.
1638 * @retval -ENOTSUP If API is not enabled.
1639 * @retval -errno Other negative errno value in case of failure.
1640 */
1641 __syscall int uart_drv_cmd(const struct device *dev, uint32_t cmd, uint32_t p);
1642
z_impl_uart_drv_cmd(const struct device * dev,uint32_t cmd,uint32_t p)1643 static inline int z_impl_uart_drv_cmd(const struct device *dev, uint32_t cmd,
1644 uint32_t p)
1645 {
1646 #ifdef CONFIG_UART_DRV_CMD
1647 const struct uart_driver_api *api =
1648 (const struct uart_driver_api *)dev->api;
1649
1650 if (api->drv_cmd == NULL) {
1651 return -ENOSYS;
1652 }
1653 return api->drv_cmd(dev, cmd, p);
1654 #else
1655 ARG_UNUSED(dev);
1656 ARG_UNUSED(cmd);
1657 ARG_UNUSED(p);
1658 return -ENOTSUP;
1659 #endif
1660 }
1661
1662 #ifdef __cplusplus
1663 }
1664 #endif
1665
1666 /**
1667 * @}
1668 */
1669
1670 #include <syscalls/uart.h>
1671
1672 #endif /* ZEPHYR_INCLUDE_DRIVERS_UART_H_ */
1673
