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