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