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 <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 Types of events passed to callback in UART_ASYNC_API
43 *
44 * Receiving:
45 * 1. To start receiving, uart_rx_enable has to be called with first buffer
46 * 2. When receiving starts to current buffer,
47 * @ref uart_event_type::UART_RX_BUF_REQUEST will be generated, in response
48 * to that user can either:
49 *
50 * - Provide second buffer using uart_rx_buf_rsp, when first buffer is
51 * filled, receiving will automatically start to second buffer.
52 * - Ignore the event, this way when current buffer is filled
53 * @ref uart_event_type::UART_RX_RDY event will be generated and
54 * receiving will be stopped.
55 *
56 * 3. If some data was received and timeout occurred
57 * @ref uart_event_type::UART_RX_RDY event will be generated. It can happen
58 * multiples times for the same buffer. RX timeout is counted from last byte
59 * received i.e. if no data was received, there won't be any timeout event.
60 * 4. After buffer is filled @ref uart_event_type::UART_RX_RDY will be
61 * generated, immediately followed by
62 * @ref uart_event_type::UART_RX_BUF_RELEASED indicating that current buffer
63 * is no longer used.
64 * 5. If there was second buffer provided, it will become current buffer and
65 * we start again at point 2.
66 * If no second buffer was specified receiving is stopped and
67 * @ref uart_event_type::UART_RX_DISABLED event is generated. After that
68 * whole process can be repeated.
69 *
70 * Any time during reception @ref uart_event_type::UART_RX_STOPPED event can
71 * occur. if there is any data received, @ref uart_event_type::UART_RX_RDY
72 * event will be generated. It will be followed by
73 * @ref uart_event_type::UART_RX_BUF_RELEASED event for every buffer currently
74 * passed to driver and finally by @ref uart_event_type::UART_RX_DISABLED event.
75 *
76 * Receiving can be disabled using uart_rx_disable, after calling that
77 * function, if there is any data received,
78 * @ref uart_event_type::UART_RX_RDY event will be generated.
79 * @ref uart_event_type::UART_RX_BUF_RELEASED event will be generated for every
80 * buffer currently passed to driver and finally
81 * @ref uart_event_type::UART_RX_DISABLED event will occur.
82 *
83 * Transmitting:
84 * 1. Transmitting starts by uart_tx function.
85 * 2. If whole buffer was transmitted @ref uart_event_type::UART_TX_DONE is
86 * generated. If timeout occurred @ref uart_event_type::UART_TX_ABORTED will
87 * be generated.
88 *
89 * Transmitting can be aborted using @ref uart_tx_abort, after calling that
90 * function @ref uart_event_type::UART_TX_ABORTED event will be generated.
91 *
92 */
93 enum uart_event_type {
94 /** @brief Whole TX buffer was transmitted. */
95 UART_TX_DONE,
96 /**
97 * @brief Transmitting aborted due to timeout or uart_tx_abort call
98 *
99 * When flow control is enabled, there is a possibility that TX transfer
100 * won't finish in the allotted time. Some data may have been
101 * transferred, information about it can be found in event data.
102 */
103 UART_TX_ABORTED,
104 /**
105 * @brief Received data is ready for processing.
106 *
107 * This event is generated in the following cases:
108 * - When RX timeout occurred, and data was stored in provided buffer.
109 * This can happen multiple times in the same buffer.
110 * - When provided buffer is full.
111 * - After uart_rx_disable().
112 * - After stopping due to external event
113 * (@ref uart_event_type::UART_RX_STOPPED).
114 */
115 UART_RX_RDY,
116 /**
117 * @brief Driver requests next buffer for continuous reception.
118 *
119 * This event is triggered when receiving has started for a new buffer,
120 * i.e. it's time to provide a next buffer for a seamless switchover to
121 * it. For continuous reliable receiving, user should provide another RX
122 * buffer in response to this event, using uart_rx_buf_rsp function
123 *
124 * If uart_rx_buf_rsp is not called before current buffer
125 * is filled up, receiving will stop.
126 */
127 UART_RX_BUF_REQUEST,
128 /**
129 * @brief Buffer is no longer used by UART driver.
130 */
131 UART_RX_BUF_RELEASED,
132 /**
133 * @brief RX has been disabled and can be reenabled.
134 *
135 * This event is generated whenever receiver has been stopped, disabled
136 * or finished its operation and can be enabled again using
137 * uart_rx_enable
138 */
139 UART_RX_DISABLED,
140 /**
141 * @brief RX has stopped due to external event.
142 *
143 * Reason is one of uart_rx_stop_reason.
144 */
145 UART_RX_STOPPED,
146 };
147
148
149 /**
150 * @brief Reception stop reasons.
151 *
152 * Values that correspond to events or errors responsible for stopping
153 * receiving.
154 */
155 enum uart_rx_stop_reason {
156 /** @brief Overrun error */
157 UART_ERROR_OVERRUN = (1 << 0),
158 /** @brief Parity error */
159 UART_ERROR_PARITY = (1 << 1),
160 /** @brief Framing error */
161 UART_ERROR_FRAMING = (1 << 2),
162 /**
163 * @brief Break interrupt
164 *
165 * A break interrupt was received. This happens when the serial input
166 * is held at a logic '0' state for longer than the sum of
167 * start time + data bits + parity + stop bits.
168 */
169 UART_BREAK = (1 << 3),
170 /**
171 * @brief Collision error
172 *
173 * This error is raised when transmitted data does not match
174 * received data. Typically this is useful in scenarios where
175 * the TX and RX lines maybe connected together such as
176 * RS-485 half-duplex. This error is only valid on UARTs that
177 * support collision checking.
178 */
179 UART_ERROR_COLLISION = (1 << 4),
180 };
181
182 /** @brief UART TX event data. */
183 struct uart_event_tx {
184 /** @brief Pointer to current buffer. */
185 const uint8_t *buf;
186 /** @brief Number of bytes sent. */
187 size_t len;
188 };
189
190 /**
191 * @brief UART RX event data.
192 *
193 * The data represented by the event is stored in rx.buf[rx.offset] to
194 * rx.buf[rx.offset+rx.len]. That is, the length is relative to the offset.
195 */
196 struct uart_event_rx {
197 /** @brief Pointer to current buffer. */
198 uint8_t *buf;
199 /** @brief Currently received data offset in bytes. */
200 size_t offset;
201 /** @brief Number of new bytes received. */
202 size_t len;
203 };
204
205 /** @brief UART RX buffer released event data. */
206 struct uart_event_rx_buf {
207 /* @brief Pointer to buffer that is no longer in use. */
208 uint8_t *buf;
209 };
210
211 /** @brief UART RX stopped data. */
212 struct uart_event_rx_stop {
213 /** @brief Reason why receiving stopped */
214 enum uart_rx_stop_reason reason;
215 /** @brief Last received data. */
216 struct uart_event_rx data;
217 };
218
219 /** @brief Structure containing information about current event. */
220 struct uart_event {
221 /** @brief Type of event */
222 enum uart_event_type type;
223 /** @brief Event data */
224 union uart_event_data {
225 /** @brief @ref uart_event_type::UART_TX_DONE and
226 * @ref uart_event_type::UART_TX_ABORTED events data.
227 */
228 struct uart_event_tx tx;
229 /** @brief @ref uart_event_type::UART_RX_RDY event data. */
230 struct uart_event_rx rx;
231 /** @brief @ref uart_event_type::UART_RX_BUF_RELEASED event
232 * data.
233 */
234 struct uart_event_rx_buf rx_buf;
235 /** @brief @ref uart_event_type::UART_RX_STOPPED event data. */
236 struct uart_event_rx_stop rx_stop;
237 } data;
238 };
239
240 /**
241 * @typedef uart_callback_t
242 * @brief Define the application callback function signature for
243 * uart_callback_set() function.
244 *
245 * @param dev UART device structure.
246 * @param evt Pointer to uart_event structure.
247 * @param user_data Pointer to data specified by user.
248 */
249 typedef void (*uart_callback_t)(const struct device *dev,
250 struct uart_event *evt, void *user_data);
251
252 /**
253 * @brief UART controller configuration structure
254 *
255 * @param baudrate Baudrate setting in bps
256 * @param parity Parity bit, use @ref uart_config_parity
257 * @param stop_bits Stop bits, use @ref uart_config_stop_bits
258 * @param data_bits Data bits, use @ref uart_config_data_bits
259 * @param flow_ctrl Flow control setting, use @ref uart_config_flow_control
260 */
261 struct uart_config {
262 uint32_t baudrate;
263 uint8_t parity;
264 uint8_t stop_bits;
265 uint8_t data_bits;
266 uint8_t flow_ctrl;
267 };
268
269 /** @brief Parity modes */
270 enum uart_config_parity {
271 UART_CFG_PARITY_NONE,
272 UART_CFG_PARITY_ODD,
273 UART_CFG_PARITY_EVEN,
274 UART_CFG_PARITY_MARK,
275 UART_CFG_PARITY_SPACE,
276 };
277
278 /** @brief Number of stop bits. */
279 enum uart_config_stop_bits {
280 UART_CFG_STOP_BITS_0_5,
281 UART_CFG_STOP_BITS_1,
282 UART_CFG_STOP_BITS_1_5,
283 UART_CFG_STOP_BITS_2,
284 };
285
286 /** @brief Number of data bits. */
287 enum uart_config_data_bits {
288 UART_CFG_DATA_BITS_5,
289 UART_CFG_DATA_BITS_6,
290 UART_CFG_DATA_BITS_7,
291 UART_CFG_DATA_BITS_8,
292 UART_CFG_DATA_BITS_9,
293 };
294
295 /**
296 * @brief Hardware flow control options.
297 *
298 * With flow control set to none, any operations related to flow control
299 * signals can be managed by user with uart_line_ctrl functions.
300 * In other cases, flow control is managed by hardware/driver.
301 */
302 enum uart_config_flow_control {
303 UART_CFG_FLOW_CTRL_NONE,
304 UART_CFG_FLOW_CTRL_RTS_CTS,
305 UART_CFG_FLOW_CTRL_DTR_DSR,
306 };
307
308 /**
309 * @typedef uart_irq_callback_user_data_t
310 * @brief Define the application callback function signature for
311 * uart_irq_callback_user_data_set() function.
312 *
313 * @param dev UART device structure.
314 * @param user_data Arbitrary user data.
315 */
316 typedef void (*uart_irq_callback_user_data_t)(const struct device *dev,
317 void *user_data);
318
319 /**
320 * @typedef uart_irq_config_func_t
321 * @brief For configuring IRQ on each individual UART device.
322 *
323 * @param dev UART device structure.
324 *
325 * @internal
326 */
327 typedef void (*uart_irq_config_func_t)(const struct device *dev);
328
329 /**
330 * @brief UART device configuration.
331 *
332 * @param port Base port number
333 * @param base Memory mapped base address
334 * @param regs Register address
335 * @param sys_clk_freq System clock frequency in Hz
336 */
337 struct uart_device_config {
338 union {
339 uint32_t port;
340 uint8_t *base;
341 uint32_t regs;
342 };
343
344 uint32_t sys_clk_freq;
345
346 #if defined(CONFIG_UART_INTERRUPT_DRIVEN) || defined(CONFIG_UART_ASYNC_API)
347 uart_irq_config_func_t irq_config_func;
348 #endif
349 };
350
351 /** @brief Driver API structure. */
352 __subsystem struct uart_driver_api {
353
354 #ifdef CONFIG_UART_ASYNC_API
355
356 int (*callback_set)(const struct device *dev,
357 uart_callback_t callback,
358 void *user_data);
359
360 int (*tx)(const struct device *dev, const uint8_t *buf, size_t len,
361 int32_t timeout);
362 int (*tx_abort)(const struct device *dev);
363
364 int (*rx_enable)(const struct device *dev, uint8_t *buf, size_t len,
365 int32_t timeout);
366 int (*rx_buf_rsp)(const struct device *dev, uint8_t *buf, size_t len);
367 int (*rx_disable)(const struct device *dev);
368
369 #endif
370
371 /** Console I/O function */
372 int (*poll_in)(const struct device *dev, unsigned char *p_char);
373 void (*poll_out)(const struct device *dev, unsigned char out_char);
374
375 /** Console I/O function */
376 int (*err_check)(const struct device *dev);
377
378 /** UART configuration functions */
379 int (*configure)(const struct device *dev,
380 const struct uart_config *cfg);
381 int (*config_get)(const struct device *dev, struct uart_config *cfg);
382
383 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
384
385 /** Interrupt driven FIFO fill function */
386 int (*fifo_fill)(const struct device *dev, const uint8_t *tx_data,
387 int len);
388
389 /** Interrupt driven FIFO read function */
390 int (*fifo_read)(const struct device *dev, uint8_t *rx_data,
391 const int size);
392
393 /** Interrupt driven transfer enabling function */
394 void (*irq_tx_enable)(const struct device *dev);
395
396 /** Interrupt driven transfer disabling function */
397 void (*irq_tx_disable)(const struct device *dev);
398
399 /** Interrupt driven transfer ready function */
400 int (*irq_tx_ready)(const struct device *dev);
401
402 /** Interrupt driven receiver enabling function */
403 void (*irq_rx_enable)(const struct device *dev);
404
405 /** Interrupt driven receiver disabling function */
406 void (*irq_rx_disable)(const struct device *dev);
407
408 /** Interrupt driven transfer complete function */
409 int (*irq_tx_complete)(const struct device *dev);
410
411 /** Interrupt driven receiver ready function */
412 int (*irq_rx_ready)(const struct device *dev);
413
414 /** Interrupt driven error enabling function */
415 void (*irq_err_enable)(const struct device *dev);
416
417 /** Interrupt driven error disabling function */
418 void (*irq_err_disable)(const struct device *dev);
419
420 /** Interrupt driven pending status function */
421 int (*irq_is_pending)(const struct device *dev);
422
423 /** Interrupt driven interrupt update function */
424 int (*irq_update)(const struct device *dev);
425
426 /** Set the irq callback function */
427 void (*irq_callback_set)(const struct device *dev,
428 uart_irq_callback_user_data_t cb,
429 void *user_data);
430
431 #endif
432
433 #ifdef CONFIG_UART_LINE_CTRL
434 int (*line_ctrl_set)(const struct device *dev, uint32_t ctrl,
435 uint32_t val);
436 int (*line_ctrl_get)(const struct device *dev, uint32_t ctrl,
437 uint32_t *val);
438 #endif
439
440 #ifdef CONFIG_UART_DRV_CMD
441 int (*drv_cmd)(const struct device *dev, uint32_t cmd, uint32_t p);
442 #endif
443
444 };
445
446
447 /**
448 * @brief Set event handler function.
449 *
450 * Since it is mandatory to set callback to use other asynchronous functions,
451 * it can be used to detect if the device supports asynchronous API. Remaining
452 * API does not have that detection.
453 *
454 * @param dev UART device structure.
455 * @param callback Event handler.
456 * @param user_data Data to pass to event handler function.
457 *
458 * @retval -ENOSYS If not supported by the device.
459 * @retval -ENOTSUP If API not enabled.
460 * @retval 0 If successful, negative errno code otherwise.
461 */
uart_callback_set(const struct device * dev,uart_callback_t callback,void * user_data)462 static inline int uart_callback_set(const struct device *dev,
463 uart_callback_t callback,
464 void *user_data)
465 {
466 #ifdef CONFIG_UART_ASYNC_API
467 const struct uart_driver_api *api =
468 (const struct uart_driver_api *)dev->api;
469
470 if (api->callback_set == NULL) {
471 return -ENOSYS;
472 }
473
474 return api->callback_set(dev, callback, user_data);
475 #else
476 return -ENOTSUP;
477 #endif
478 }
479
480 /**
481 * @brief Send given number of bytes from buffer through UART.
482 *
483 * Function returns immediately and event handler,
484 * set using @ref uart_callback_set, is called after transfer is finished.
485 *
486 * @param dev UART device structure.
487 * @param buf Pointer to transmit buffer.
488 * @param len Length of transmit buffer.
489 * @param timeout Timeout in milliseconds. Valid only if flow control is
490 * enabled. @ref SYS_FOREVER_MS disables timeout.
491 *
492 * @retval -ENOTSUP If not supported.
493 * @retval -EBUSY There is already an ongoing transfer.
494 * @retval 0 If successful, negative errno code otherwise.
495 */
496 __syscall int uart_tx(const struct device *dev, const uint8_t *buf,
497 size_t len,
498 int32_t timeout);
499
z_impl_uart_tx(const struct device * dev,const uint8_t * buf,size_t len,int32_t timeout)500 static inline int z_impl_uart_tx(const struct device *dev, const uint8_t *buf,
501 size_t len, int32_t timeout)
502
503 {
504 #ifdef CONFIG_UART_ASYNC_API
505 const struct uart_driver_api *api =
506 (const struct uart_driver_api *)dev->api;
507
508 return api->tx(dev, buf, len, timeout);
509 #else
510 return -ENOTSUP;
511 #endif
512 }
513
514 /**
515 * @brief Abort current TX transmission.
516 *
517 * @ref uart_event_type::UART_TX_DONE event will be generated with amount of
518 * data sent.
519 *
520 * @param dev UART device structure.
521 *
522 * @retval -ENOTSUP If not supported.
523 * @retval -EFAULT There is no active transmission.
524 * @retval 0 If successful, negative errno code otherwise.
525 */
526 __syscall int uart_tx_abort(const struct device *dev);
527
z_impl_uart_tx_abort(const struct device * dev)528 static inline int z_impl_uart_tx_abort(const struct device *dev)
529 {
530 #ifdef CONFIG_UART_ASYNC_API
531 const struct uart_driver_api *api =
532 (const struct uart_driver_api *)dev->api;
533
534 return api->tx_abort(dev);
535 #else
536 return -ENOTSUP;
537 #endif
538 }
539
540 /**
541 * @brief Start receiving data through UART.
542 *
543 * Function sets given buffer as first buffer for receiving and returns
544 * immediately. After that event handler, set using @ref uart_callback_set,
545 * is called with @ref uart_event_type::UART_RX_RDY or
546 * @ref uart_event_type::UART_RX_BUF_REQUEST events.
547 *
548 * @param dev UART device structure.
549 * @param buf Pointer to receive buffer.
550 * @param len Buffer length.
551 * @param timeout Inactivity period after receiving at least a byte which
552 * triggers @ref uart_event_type::UART_RX_RDY event. Given in
553 * milliseconds. @ref SYS_FOREVER_MS disables timeout. See
554 * @ref uart_event_type for details.
555 *
556 * @retval -ENOTSUP If not supported.
557 * @retval -EBUSY RX already in progress.
558 * @retval 0 If successful, negative errno code otherwise.
559 *
560 */
561 __syscall int uart_rx_enable(const struct device *dev, uint8_t *buf,
562 size_t len,
563 int32_t timeout);
564
z_impl_uart_rx_enable(const struct device * dev,uint8_t * buf,size_t len,int32_t timeout)565 static inline int z_impl_uart_rx_enable(const struct device *dev,
566 uint8_t *buf,
567 size_t len, int32_t timeout)
568 {
569 #ifdef CONFIG_UART_ASYNC_API
570 const struct uart_driver_api *api =
571 (const struct uart_driver_api *)dev->api;
572
573 return api->rx_enable(dev, buf, len, timeout);
574 #else
575 return -ENOTSUP;
576 #endif
577 }
578
579 /**
580 * @brief Provide receive buffer in response to
581 * @ref uart_event_type::UART_RX_BUF_REQUEST event.
582 *
583 * Provide pointer to RX buffer, which will be used when current buffer is
584 * filled.
585 *
586 * @note Providing buffer that is already in usage by driver leads to
587 * undefined behavior. Buffer can be reused when it has been released
588 * by driver.
589 *
590 * @param dev UART device structure.
591 * @param buf Pointer to receive buffer.
592 * @param len Buffer length.
593 *
594 * @retval -ENOTSUP If not supported.
595 * @retval -EBUSY Next buffer already set.
596 * @retval -EACCES Receiver is already disabled (function called too late?).
597 * @retval 0 If successful, negative errno code otherwise.
598 *
599 */
uart_rx_buf_rsp(const struct device * dev,uint8_t * buf,size_t len)600 static inline int uart_rx_buf_rsp(const struct device *dev, uint8_t *buf,
601 size_t len)
602 {
603 #ifdef CONFIG_UART_ASYNC_API
604 const struct uart_driver_api *api =
605 (const struct uart_driver_api *)dev->api;
606
607 return api->rx_buf_rsp(dev, buf, len);
608 #else
609 return -ENOTSUP;
610 #endif
611 }
612
613 /**
614 * @brief Disable RX
615 *
616 * @ref uart_event_type::UART_RX_BUF_RELEASED event will be generated for every
617 * buffer scheduled, after that @ref uart_event_type::UART_RX_DISABLED event
618 * will be generated. Additionally, if there is any pending received data, the
619 * @ref uart_event_type::UART_RX_RDY event for that data will be generated
620 * before the @ref uart_event_type::UART_RX_BUF_RELEASED events.
621 *
622 * @param dev UART device structure.
623 *
624 * @retval -ENOTSUP If not supported.
625 * @retval -EFAULT There is no active reception.
626 * @retval 0 If successful, negative errno code otherwise.
627 */
628 __syscall int uart_rx_disable(const struct device *dev);
629
z_impl_uart_rx_disable(const struct device * dev)630 static inline int z_impl_uart_rx_disable(const struct device *dev)
631 {
632 #ifdef CONFIG_UART_ASYNC_API
633 const struct uart_driver_api *api =
634 (const struct uart_driver_api *)dev->api;
635
636 return api->rx_disable(dev);
637 #else
638 return -ENOTSUP;
639 #endif
640 }
641
642 /**
643 * @brief Check whether an error was detected.
644 *
645 * @param dev UART device structure.
646 *
647 * @retval uart_rx_stop_reason If error during receiving occurred.
648 * @retval 0 Otherwise.
649 * @retval -ENOSYS If this function is not supported.
650 */
651 __syscall int uart_err_check(const struct device *dev);
652
z_impl_uart_err_check(const struct device * dev)653 static inline int z_impl_uart_err_check(const struct device *dev)
654 {
655 const struct uart_driver_api *api =
656 (const struct uart_driver_api *)dev->api;
657
658 if (api->err_check == NULL) {
659 return -ENOSYS;
660 }
661
662 return api->err_check(dev);
663 }
664
665
666 /**
667 * @brief Poll the device for input.
668 *
669 * @param dev UART device structure.
670 * @param p_char Pointer to character.
671 *
672 * @retval 0 If a character arrived.
673 * @retval -1 If no character was available to read (i.e., the UART
674 * input buffer was empty).
675 * @retval -ENOSYS If the operation is not supported.
676 * @retval -EBUSY If reception was enabled using uart_rx_enabled
677 */
678 __syscall int uart_poll_in(const struct device *dev, unsigned char *p_char);
679
z_impl_uart_poll_in(const struct device * dev,unsigned char * p_char)680 static inline int z_impl_uart_poll_in(const struct device *dev,
681 unsigned char *p_char)
682 {
683 const struct uart_driver_api *api =
684 (const struct uart_driver_api *)dev->api;
685
686 if (api->poll_in == NULL) {
687 return -ENOSYS;
688 }
689
690 return api->poll_in(dev, p_char);
691 }
692
693 /**
694 * @brief Output a character in polled mode.
695 *
696 * This routine checks if the transmitter is empty.
697 * When the transmitter is empty, it writes a character to the data
698 * register.
699 *
700 * To send a character when hardware flow control is enabled, the handshake
701 * signal CTS must be asserted.
702 *
703 * @param dev UART device structure.
704 * @param out_char Character to send.
705 */
706 __syscall void uart_poll_out(const struct device *dev,
707 unsigned char out_char);
708
z_impl_uart_poll_out(const struct device * dev,unsigned char out_char)709 static inline void z_impl_uart_poll_out(const struct device *dev,
710 unsigned char out_char)
711 {
712 const struct uart_driver_api *api =
713 (const struct uart_driver_api *)dev->api;
714
715 api->poll_out(dev, out_char);
716 }
717
718 /**
719 * @brief Set UART configuration.
720 *
721 * Sets UART configuration using data from *cfg.
722 *
723 * @param dev UART device structure.
724 * @param cfg UART configuration structure.
725 *
726 *
727 * @retval -ENOSYS If configuration is not supported by device.
728 * or driver does not support setting configuration in runtime.
729 * @retval 0 If successful, negative errno code otherwise.
730 */
731 __syscall int uart_configure(const struct device *dev,
732 const struct uart_config *cfg);
733
z_impl_uart_configure(const struct device * dev,const struct uart_config * cfg)734 static inline int z_impl_uart_configure(const struct device *dev,
735 const struct uart_config *cfg)
736 {
737 const struct uart_driver_api *api =
738 (const struct uart_driver_api *)dev->api;
739
740 if (api->configure == NULL) {
741 return -ENOSYS;
742 }
743 return api->configure(dev, cfg);
744 }
745
746 /**
747 * @brief Get UART configuration.
748 *
749 * Stores current UART configuration to *cfg, can be used to retrieve initial
750 * configuration after device was initialized using data from DTS.
751 *
752 * @param dev UART device structure.
753 * @param cfg UART configuration structure.
754 *
755 * @retval -ENOSYS If driver does not support getting current configuration.
756 * @retval 0 If successful, negative errno code otherwise.
757 */
758 __syscall int uart_config_get(const struct device *dev,
759 struct uart_config *cfg);
760
z_impl_uart_config_get(const struct device * dev,struct uart_config * cfg)761 static inline int z_impl_uart_config_get(const struct device *dev,
762 struct uart_config *cfg)
763 {
764 const struct uart_driver_api *api =
765 (const struct uart_driver_api *)dev->api;
766
767 if (api->config_get == NULL) {
768 return -ENOSYS;
769 }
770
771 return api->config_get(dev, cfg);
772 }
773
774 /**
775 * @brief Fill FIFO with data.
776 *
777 * @details This function is expected to be called from UART
778 * interrupt handler (ISR), if uart_irq_tx_ready() returns true.
779 * Result of calling this function not from an ISR is undefined
780 * (hardware-dependent). Likewise, *not* calling this function
781 * from an ISR if uart_irq_tx_ready() returns true may lead to
782 * undefined behavior, e.g. infinite interrupt loops. It's
783 * mandatory to test return value of this function, as different
784 * hardware has different FIFO depth (oftentimes just 1).
785 *
786 * @param dev UART device structure.
787 * @param tx_data Data to transmit.
788 * @param size Number of bytes to send.
789 *
790 * @return Number of bytes sent.
791 * @retval -ENOSYS if this function is not supported
792 * @retval -ENOTSUP if API is not enabled.
793 */
uart_fifo_fill(const struct device * dev,const uint8_t * tx_data,int size)794 static inline int uart_fifo_fill(const struct device *dev,
795 const uint8_t *tx_data,
796 int size)
797 {
798 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
799 const struct uart_driver_api *api =
800 (const struct uart_driver_api *)dev->api;
801
802 if (api->fifo_fill == NULL) {
803 return -ENOSYS;
804 }
805
806 return api->fifo_fill(dev, tx_data, size);
807 #endif
808
809 return -ENOTSUP;
810 }
811
812 /**
813 * @brief Read data from FIFO.
814 *
815 * @details This function is expected to be called from UART
816 * interrupt handler (ISR), if uart_irq_rx_ready() returns true.
817 * Result of calling this function not from an ISR is undefined
818 * (hardware-dependent). It's unspecified whether "RX ready"
819 * condition as returned by uart_irq_rx_ready() is level- or
820 * edge- triggered. That means that once uart_irq_rx_ready() is
821 * detected, uart_fifo_read() must be called until it reads all
822 * available data in the FIFO (i.e. until it returns less data
823 * than was requested).
824 *
825 * Note that the calling context only applies to physical UARTs and
826 * no to the virtual ones found in USB CDC ACM code.
827 *
828 * @param dev UART device structure.
829 * @param rx_data Data container.
830 * @param size Container size.
831 *
832 * @return Number of bytes read.
833 * @retval -ENOSYS if this function is not supported.
834 * @retval -ENOTSUP if API is not enabled.
835 */
uart_fifo_read(const struct device * dev,uint8_t * rx_data,const int size)836 static inline int uart_fifo_read(const struct device *dev, uint8_t *rx_data,
837 const int size)
838 {
839 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
840 const struct uart_driver_api *api =
841 (const struct uart_driver_api *)dev->api;
842
843 if (api->fifo_read == NULL) {
844 return -ENOSYS;
845 }
846
847 return api->fifo_read(dev, rx_data, size);
848 #endif
849
850 return -ENOTSUP;
851 }
852
853 /**
854 * @brief Enable TX interrupt in IER.
855 *
856 * @param dev UART device structure.
857 *
858 * @return N/A
859 */
860 __syscall void uart_irq_tx_enable(const struct device *dev);
861
z_impl_uart_irq_tx_enable(const struct device * dev)862 static inline void z_impl_uart_irq_tx_enable(const struct device *dev)
863 {
864 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
865 const struct uart_driver_api *api =
866 (const struct uart_driver_api *)dev->api;
867
868 if (api->irq_tx_enable != NULL) {
869 api->irq_tx_enable(dev);
870 }
871 #endif
872 }
873 /**
874 * @brief Disable TX interrupt in IER.
875 *
876 * @param dev UART device structure.
877 *
878 * @return N/A
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 #endif
892 }
893
894 /**
895 * @brief Check if UART TX buffer can accept a new char
896 *
897 * @details Check if UART TX buffer can accept at least one character
898 * for transmission (i.e. uart_fifo_fill() will succeed and return
899 * non-zero). This function must be called in a UART interrupt
900 * handler, or its result is undefined. Before calling this function
901 * in the interrupt handler, uart_irq_update() must be called once per
902 * the handler invocation.
903 *
904 * @param dev UART device structure.
905 *
906 * @retval 1 If at least one char can be written to UART.
907 * @retval 0 If device is not ready to write a new byte.
908 * @retval -ENOSYS if this function is not supported.
909 * @retval -ENOTSUP if API is not enabled.
910 */
uart_irq_tx_ready(const struct device * dev)911 static inline int uart_irq_tx_ready(const struct device *dev)
912 {
913 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
914 const struct uart_driver_api *api =
915 (const struct uart_driver_api *)dev->api;
916
917 if (api->irq_tx_ready == NULL) {
918 return -ENOSYS;
919 }
920
921 return api->irq_tx_ready(dev);
922 #endif
923
924 return -ENOTSUP;
925 }
926
927 /**
928 * @brief Enable RX interrupt.
929 *
930 * @param dev UART device structure.
931 *
932 * @return N/A
933 */
934 __syscall void uart_irq_rx_enable(const struct device *dev);
935
z_impl_uart_irq_rx_enable(const struct device * dev)936 static inline void z_impl_uart_irq_rx_enable(const struct device *dev)
937 {
938 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
939 const struct uart_driver_api *api =
940 (const struct uart_driver_api *)dev->api;
941
942 if (api->irq_rx_enable != NULL) {
943 api->irq_rx_enable(dev);
944 }
945 #endif
946 }
947
948 /**
949 * @brief Disable RX interrupt.
950 *
951 * @param dev UART device structure.
952 *
953 * @return N/A
954 */
955 __syscall void uart_irq_rx_disable(const struct device *dev);
956
z_impl_uart_irq_rx_disable(const struct device * dev)957 static inline void z_impl_uart_irq_rx_disable(const struct device *dev)
958 {
959 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
960 const struct uart_driver_api *api =
961 (const struct uart_driver_api *)dev->api;
962
963 if (api->irq_rx_disable != NULL) {
964 api->irq_rx_disable(dev);
965 }
966 #endif
967 }
968
969 /**
970 * @brief Check if UART TX block finished transmission
971 *
972 * @details Check if any outgoing data buffered in UART TX block was
973 * fully transmitted and TX block is idle. When this condition is
974 * true, UART device (or whole system) can be power off. Note that
975 * this function is *not* useful to check if UART TX can accept more
976 * data, use uart_irq_tx_ready() for that. This function must be called
977 * in a UART interrupt handler, or its result is undefined. Before
978 * calling this function in the interrupt handler, uart_irq_update()
979 * must be called once per the handler invocation.
980 *
981 * @param dev UART device structure.
982 *
983 * @retval 1 If nothing remains to be transmitted.
984 * @retval 0 If transmission is not completed.
985 * @retval -ENOSYS if this function is not supported.
986 * @retval -ENOTSUP if API is not enabled.
987 */
uart_irq_tx_complete(const struct device * dev)988 static inline int uart_irq_tx_complete(const struct device *dev)
989 {
990 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
991 const struct uart_driver_api *api =
992 (const struct uart_driver_api *)dev->api;
993
994 if (api->irq_tx_complete == NULL) {
995 return -ENOSYS;
996 }
997 return api->irq_tx_complete(dev);
998 #endif
999 return -ENOTSUP;
1000
1001 }
1002
1003
1004 /**
1005 * @brief Check if UART RX buffer has a received char
1006 *
1007 * @details Check if UART RX buffer has at least one pending character
1008 * (i.e. uart_fifo_read() will succeed and return non-zero). This function
1009 * must be called in a UART interrupt handler, or its result is undefined.
1010 * Before calling this function in the interrupt handler, uart_irq_update()
1011 * must be called once per the handler invocation. It's unspecified whether
1012 * condition as returned by this function is level- or edge- triggered (i.e.
1013 * if this function returns true when RX FIFO is non-empty, or when a new
1014 * char was received since last call to it). See description of
1015 * uart_fifo_read() for implication of this.
1016 *
1017 * @param dev UART device structure.
1018 *
1019 * @retval 1 If a received char is ready.
1020 * @retval 0 If a received char is not ready.
1021 * @retval -ENOSYS if this function is not supported.
1022 * @retval -ENOTSUP if API is not enabled.
1023 */
uart_irq_rx_ready(const struct device * dev)1024 static inline int uart_irq_rx_ready(const struct device *dev)
1025 {
1026 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
1027 const struct uart_driver_api *api =
1028 (const struct uart_driver_api *)dev->api;
1029
1030 if (api->irq_rx_ready == NULL) {
1031 return -ENOSYS;
1032 }
1033 return api->irq_rx_ready(dev);
1034 #endif
1035
1036 return -ENOTSUP;
1037 }
1038 /**
1039 * @brief Enable error interrupt.
1040 *
1041 * @param dev UART device structure.
1042 *
1043 * @return N/A
1044 */
1045 __syscall void uart_irq_err_enable(const struct device *dev);
1046
z_impl_uart_irq_err_enable(const struct device * dev)1047 static inline void z_impl_uart_irq_err_enable(const struct device *dev)
1048 {
1049 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
1050 const struct uart_driver_api *api =
1051 (const struct uart_driver_api *)dev->api;
1052
1053 if (api->irq_err_enable) {
1054 api->irq_err_enable(dev);
1055 }
1056 #endif
1057 }
1058
1059 /**
1060 * @brief Disable error interrupt.
1061 *
1062 * @param dev UART device structure.
1063 *
1064 * @retval 1 If an IRQ is ready.
1065 * @retval 0 Otherwise.
1066 */
1067 __syscall void uart_irq_err_disable(const struct device *dev);
1068
z_impl_uart_irq_err_disable(const struct device * dev)1069 static inline void z_impl_uart_irq_err_disable(const struct device *dev)
1070 {
1071 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
1072 const struct uart_driver_api *api =
1073 (const struct uart_driver_api *)dev->api;
1074
1075 if (api->irq_err_disable) {
1076 api->irq_err_disable(dev);
1077 }
1078 #endif
1079 }
1080
1081 /**
1082 * @brief Check if any IRQs is pending.
1083 *
1084 * @param dev UART device structure.
1085 *
1086 * @retval 1 If an IRQ is pending.
1087 * @retval 0 If an IRQ is not pending.
1088 * @retval -ENOSYS if this function is not supported.
1089 * @retval -ENOTSUP if API is not enabled.
1090 */
1091 __syscall int uart_irq_is_pending(const struct device *dev);
1092
z_impl_uart_irq_is_pending(const struct device * dev)1093 static inline int z_impl_uart_irq_is_pending(const struct device *dev)
1094 {
1095 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
1096 const struct uart_driver_api *api =
1097 (const struct uart_driver_api *)dev->api;
1098
1099 if (api->irq_is_pending == NULL) {
1100 return -ENOSYS;
1101 }
1102 return api->irq_is_pending(dev);
1103 #endif
1104 return -ENOTSUP;
1105 }
1106
1107 /**
1108 * @brief Start processing interrupts in ISR.
1109 *
1110 * This function should be called the first thing in the ISR. Calling
1111 * uart_irq_rx_ready(), uart_irq_tx_ready(), uart_irq_tx_complete()
1112 * allowed only after this.
1113 *
1114 * The purpose of this function is:
1115 *
1116 * * For devices with auto-acknowledge of interrupt status on register
1117 * read to cache the value of this register (rx_ready, etc. then use
1118 * this case).
1119 * * For devices with explicit acknowledgement of interrupts, to ack
1120 * any pending interrupts and likewise to cache the original value.
1121 * * For devices with implicit acknowledgement, this function will be
1122 * empty. But the ISR must perform the actions needs to ack the
1123 * interrupts (usually, call uart_fifo_read() on rx_ready, and
1124 * uart_fifo_fill() on tx_ready).
1125 *
1126 * @param dev UART device structure.
1127 *
1128 * @retval -ENOSYS if this function is not supported.
1129 * @retval -ENOTSUP if API is not enabled.
1130 * @retval 1 On success.
1131 */
1132 __syscall int uart_irq_update(const struct device *dev);
1133
z_impl_uart_irq_update(const struct device * dev)1134 static inline int z_impl_uart_irq_update(const struct device *dev)
1135 {
1136 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
1137 const struct uart_driver_api *api =
1138 (const struct uart_driver_api *)dev->api;
1139
1140 if (api->irq_update == NULL) {
1141 return -ENOSYS;
1142 }
1143 return api->irq_update(dev);
1144 #endif
1145 return -ENOTSUP;
1146 }
1147
1148 /**
1149 * @brief Set the IRQ callback function pointer.
1150 *
1151 * This sets up the callback for IRQ. When an IRQ is triggered,
1152 * the specified function will be called with specified user data.
1153 * See description of uart_irq_update() for the requirements on ISR.
1154 *
1155 * @param dev UART device structure.
1156 * @param cb Pointer to the callback function.
1157 * @param user_data Data to pass to callback function.
1158 *
1159 * @return N/A
1160 */
uart_irq_callback_user_data_set(const struct device * dev,uart_irq_callback_user_data_t cb,void * user_data)1161 static inline void uart_irq_callback_user_data_set(const struct device *dev,
1162 uart_irq_callback_user_data_t cb,
1163 void *user_data)
1164 {
1165 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
1166 const struct uart_driver_api *api =
1167 (const struct uart_driver_api *)dev->api;
1168
1169 if ((api != NULL) && (api->irq_callback_set != NULL)) {
1170 api->irq_callback_set(dev, cb, user_data);
1171 }
1172 #endif
1173 }
1174
1175 /**
1176 * @brief Set the IRQ callback function pointer (legacy).
1177 *
1178 * This sets up the callback for IRQ. When an IRQ is triggered,
1179 * the specified function will be called with the device pointer.
1180 *
1181 * @param dev UART device structure.
1182 * @param cb Pointer to the callback function.
1183 *
1184 * @return N/A
1185 */
uart_irq_callback_set(const struct device * dev,uart_irq_callback_user_data_t cb)1186 static inline void uart_irq_callback_set(const struct device *dev,
1187 uart_irq_callback_user_data_t cb)
1188 {
1189 uart_irq_callback_user_data_set(dev, cb, NULL);
1190 }
1191
1192
1193 /**
1194 * @brief Manipulate line control for UART.
1195 *
1196 * @param dev UART device structure.
1197 * @param ctrl The line control to manipulate (see enum uart_line_ctrl).
1198 * @param val Value to set to the line control.
1199 *
1200 * @retval 0 If successful.
1201 * @retval -ENOSYS if this function is not supported.
1202 * @retval -ENOTSUP if API is not enabled.
1203 * @retval negative value if failed.
1204 */
1205 __syscall int uart_line_ctrl_set(const struct device *dev,
1206 uint32_t ctrl, uint32_t val);
1207
z_impl_uart_line_ctrl_set(const struct device * dev,uint32_t ctrl,uint32_t val)1208 static inline int z_impl_uart_line_ctrl_set(const struct device *dev,
1209 uint32_t ctrl, uint32_t val)
1210 {
1211 #ifdef CONFIG_UART_LINE_CTRL
1212 const struct uart_driver_api *api =
1213 (const struct uart_driver_api *)dev->api;
1214
1215 if (api->line_ctrl_set == NULL) {
1216 return -ENOSYS;
1217 }
1218 return api->line_ctrl_set(dev, ctrl, val);
1219 #endif
1220
1221 return -ENOTSUP;
1222 }
1223
1224 /**
1225 * @brief Retrieve line control for UART.
1226 *
1227 * @param dev UART device structure.
1228 * @param ctrl The line control to retrieve (see enum uart_line_ctrl).
1229 * @param val Pointer to variable where to store the line control value.
1230 *
1231 * @retval 0 If successful.
1232 * @retval -ENOSYS if this function is not supported.
1233 * @retval -ENOTSUP if API is not enabled.
1234 * @retval negative value if failed.
1235 */
1236 __syscall int uart_line_ctrl_get(const struct device *dev, uint32_t ctrl,
1237 uint32_t *val);
1238
z_impl_uart_line_ctrl_get(const struct device * dev,uint32_t ctrl,uint32_t * val)1239 static inline int z_impl_uart_line_ctrl_get(const struct device *dev,
1240 uint32_t ctrl, uint32_t *val)
1241 {
1242 #ifdef CONFIG_UART_LINE_CTRL
1243 const struct uart_driver_api *api =
1244 (const struct uart_driver_api *)dev->api;
1245
1246 if (api->line_ctrl_get == NULL) {
1247 return -ENOSYS;
1248 }
1249 return api->line_ctrl_get(dev, ctrl, val);
1250 #endif
1251
1252 return -ENOTSUP;
1253 }
1254
1255 /**
1256 * @brief Send extra command to driver.
1257 *
1258 * Implementation and accepted commands are driver specific.
1259 * Refer to the drivers for more information.
1260 *
1261 * @param dev UART device structure.
1262 * @param cmd Command to driver.
1263 * @param p Parameter to the command.
1264 *
1265 * @retval 0 If successful.
1266 * @retval -ENOSYS if this function is not supported.
1267 * @retval -ENOTSUP if API is not enabled.
1268 * @retval negative value if failed.
1269 */
1270 __syscall int uart_drv_cmd(const struct device *dev, uint32_t cmd, uint32_t p);
1271
z_impl_uart_drv_cmd(const struct device * dev,uint32_t cmd,uint32_t p)1272 static inline int z_impl_uart_drv_cmd(const struct device *dev, uint32_t cmd,
1273 uint32_t p)
1274 {
1275 #ifdef CONFIG_UART_DRV_CMD
1276 const struct uart_driver_api *api =
1277 (const struct uart_driver_api *)dev->api;
1278
1279 if (api->drv_cmd == NULL) {
1280 return -ENOSYS;
1281 }
1282 return api->drv_cmd(dev, cmd, p);
1283 #endif
1284
1285 return -ENOTSUP;
1286 }
1287
1288 #ifdef __cplusplus
1289 }
1290 #endif
1291
1292 /**
1293 * @}
1294 */
1295
1296 #include <syscalls/uart.h>
1297
1298 #endif /* ZEPHYR_INCLUDE_DRIVERS_UART_H_ */
1299
