Line data Source code
1 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 : * @ingroup uart_interface
11 : * @brief Main header file for UART driver API.
12 : */
13 :
14 : #ifndef ZEPHYR_INCLUDE_DRIVERS_UART_H_
15 : #define ZEPHYR_INCLUDE_DRIVERS_UART_H_
16 :
17 : /**
18 : * @brief Interfaces for Universal Asynchronous Receiver/Transmitter (UART)
19 : * controllers.
20 : * @defgroup uart_interface UART
21 : * @since 1.0
22 : * @version 1.0.0
23 : * @ingroup io_interfaces
24 : * @{
25 : */
26 :
27 : #include <stddef.h>
28 :
29 : #include <zephyr/device.h>
30 :
31 : #ifdef __cplusplus
32 : extern "C" {
33 : #endif
34 :
35 : /** @brief Line control signals. */
36 1 : enum uart_line_ctrl {
37 : UART_LINE_CTRL_BAUD_RATE = BIT(0), /**< Baud rate */
38 : UART_LINE_CTRL_RTS = BIT(1), /**< Request To Send (RTS) */
39 : UART_LINE_CTRL_DTR = BIT(2), /**< Data Terminal Ready (DTR) */
40 : UART_LINE_CTRL_DCD = BIT(3), /**< Data Carrier Detect (DCD) */
41 : UART_LINE_CTRL_DSR = BIT(4), /**< Data Set Ready (DSR) */
42 : };
43 :
44 : /**
45 : * @brief Reception stop reasons.
46 : *
47 : * Values that correspond to events or errors responsible for stopping
48 : * receiving.
49 : */
50 1 : enum uart_rx_stop_reason {
51 : /** @brief Overrun error */
52 : UART_ERROR_OVERRUN = (1 << 0),
53 : /** @brief Parity error */
54 : UART_ERROR_PARITY = (1 << 1),
55 : /** @brief Framing error */
56 : UART_ERROR_FRAMING = (1 << 2),
57 : /**
58 : * @brief Break interrupt
59 : *
60 : * A break interrupt was received. This happens when the serial input
61 : * is held at a logic '0' state for longer than the sum of
62 : * start time + data bits + parity + stop bits.
63 : */
64 : UART_BREAK = (1 << 3),
65 : /**
66 : * @brief Collision error
67 : *
68 : * This error is raised when transmitted data does not match
69 : * received data. Typically this is useful in scenarios where
70 : * the TX and RX lines maybe connected together such as
71 : * RS-485 half-duplex. This error is only valid on UARTs that
72 : * support collision checking.
73 : */
74 : UART_ERROR_COLLISION = (1 << 4),
75 : /** @brief Noise error */
76 : UART_ERROR_NOISE = (1 << 5),
77 : };
78 :
79 : /** @brief Parity modes */
80 1 : enum uart_config_parity {
81 : UART_CFG_PARITY_NONE, /**< No parity */
82 : UART_CFG_PARITY_ODD, /**< Odd parity */
83 : UART_CFG_PARITY_EVEN, /**< Even parity */
84 : UART_CFG_PARITY_MARK, /**< Mark parity */
85 : UART_CFG_PARITY_SPACE, /**< Space parity */
86 : };
87 :
88 : /** @brief Number of stop bits. */
89 1 : enum uart_config_stop_bits {
90 : UART_CFG_STOP_BITS_0_5, /**< 0.5 stop bit */
91 : UART_CFG_STOP_BITS_1, /**< 1 stop bit */
92 : UART_CFG_STOP_BITS_1_5, /**< 1.5 stop bits */
93 : UART_CFG_STOP_BITS_2, /**< 2 stop bits */
94 : };
95 :
96 : /** @brief Number of data bits. */
97 1 : enum uart_config_data_bits {
98 : UART_CFG_DATA_BITS_5, /**< 5 data bits */
99 : UART_CFG_DATA_BITS_6, /**< 6 data bits */
100 : UART_CFG_DATA_BITS_7, /**< 7 data bits */
101 : UART_CFG_DATA_BITS_8, /**< 8 data bits */
102 : UART_CFG_DATA_BITS_9, /**< 9 data bits */
103 : };
104 :
105 : /**
106 : * @brief Hardware flow control options.
107 : *
108 : * With flow control set to none, any operations related to flow control
109 : * signals can be managed by user with uart_line_ctrl functions.
110 : * In other cases, flow control is managed by hardware/driver.
111 : */
112 1 : enum uart_config_flow_control {
113 : UART_CFG_FLOW_CTRL_NONE, /**< No flow control */
114 : UART_CFG_FLOW_CTRL_RTS_CTS, /**< RTS/CTS flow control */
115 : UART_CFG_FLOW_CTRL_DTR_DSR, /**< DTR/DSR flow control */
116 : UART_CFG_FLOW_CTRL_RS485, /**< RS485 flow control */
117 : };
118 :
119 : /**
120 : * @brief UART controller configuration structure
121 : */
122 1 : struct uart_config {
123 1 : uint32_t baudrate; /**< Baudrate setting in bps */
124 1 : uint8_t parity; /**< Parity bit, use @ref uart_config_parity */
125 1 : uint8_t stop_bits; /**< Stop bits, use @ref uart_config_stop_bits */
126 1 : uint8_t data_bits; /**< Data bits, use @ref uart_config_data_bits */
127 1 : uint8_t flow_ctrl; /**< Flow control setting, use @ref uart_config_flow_control */
128 : };
129 :
130 : /**
131 : * @defgroup uart_interrupt Interrupt-driven UART API
132 : * @{
133 : */
134 :
135 : /**
136 : * @brief Define the application callback function signature for
137 : * uart_irq_callback_user_data_set() function.
138 : *
139 : * @param dev UART device instance.
140 : * @param user_data Arbitrary user data.
141 : */
142 1 : typedef void (*uart_irq_callback_user_data_t)(const struct device *dev,
143 : void *user_data);
144 :
145 : /**
146 : * @}
147 : *
148 : * @defgroup uart_async Async UART API
149 : * @since 1.14
150 : * @version 0.8.0
151 : * @{
152 : */
153 :
154 : /**
155 : * @brief Types of events passed to callback in UART_ASYNC_API
156 : *
157 : * Receiving:
158 : * 1. To start receiving, uart_rx_enable has to be called with first buffer
159 : * 2. When receiving starts to current buffer,
160 : * #UART_RX_BUF_REQUEST will be generated, in response to that user can
161 : * either:
162 : *
163 : * - Provide second buffer using uart_rx_buf_rsp, when first buffer is
164 : * filled, receiving will automatically start to second buffer.
165 : * - Ignore the event, this way when current buffer is filled
166 : * #UART_RX_RDY event will be generated and receiving will be stopped.
167 : *
168 : * 3. If some data was received and timeout occurred #UART_RX_RDY event will be
169 : * generated. It can happen multiples times for the same buffer. RX timeout
170 : * is counted from last byte received i.e. if no data was received, there
171 : * won't be any timeout event.
172 : * 4. #UART_RX_BUF_RELEASED event will be generated when the current buffer is
173 : * no longer used by the driver. It will immediately follow #UART_RX_RDY event.
174 : * Depending on the implementation buffer may be released when it is completely
175 : * or partially filled.
176 : * 5. If there was second buffer provided, it will become current buffer and
177 : * we start again at point 2.
178 : * If no second buffer was specified receiving is stopped and
179 : * #UART_RX_DISABLED event is generated. After that whole process can be
180 : * repeated.
181 : *
182 : * Any time during reception #UART_RX_STOPPED event can occur. if there is any
183 : * data received, #UART_RX_RDY event will be generated. It will be followed by
184 : * #UART_RX_BUF_RELEASED event for every buffer currently passed to driver and
185 : * finally by #UART_RX_DISABLED event.
186 : *
187 : * Receiving can be disabled using uart_rx_disable, after calling that
188 : * function, if there is any data received, #UART_RX_RDY event will be
189 : * generated. #UART_RX_BUF_RELEASED event will be generated for every buffer
190 : * currently passed to driver and finally #UART_RX_DISABLED event will occur.
191 : *
192 : * Transmitting:
193 : * 1. Transmitting starts by uart_tx function.
194 : * 2. If whole buffer was transmitted #UART_TX_DONE is generated. If timeout
195 : * occurred #UART_TX_ABORTED will be generated.
196 : *
197 : * Transmitting can be aborted using @ref uart_tx_abort, after calling that
198 : * function #UART_TX_ABORTED event will be generated.
199 : *
200 : */
201 1 : enum uart_event_type {
202 : /** @brief Whole TX buffer was transmitted. */
203 : UART_TX_DONE,
204 : /**
205 : * @brief Transmitting aborted due to timeout or uart_tx_abort call
206 : *
207 : * When flow control is enabled, there is a possibility that TX transfer
208 : * won't finish in the allotted time. Some data may have been
209 : * transferred, information about it can be found in event data.
210 : */
211 : UART_TX_ABORTED,
212 : /**
213 : * @brief Received data is ready for processing.
214 : *
215 : * This event is generated in the following cases:
216 : * - When RX timeout occurred, and data was stored in provided buffer.
217 : * This can happen multiple times in the same buffer.
218 : * - When provided buffer is full.
219 : * - After uart_rx_disable().
220 : * - After stopping due to external event (#UART_RX_STOPPED).
221 : */
222 : UART_RX_RDY,
223 : /**
224 : * @brief Driver requests next buffer for continuous reception.
225 : *
226 : * This event is triggered when receiving has started for a new buffer,
227 : * i.e. it's time to provide a next buffer for a seamless switchover to
228 : * it. For continuous reliable receiving, user should provide another RX
229 : * buffer in response to this event, using uart_rx_buf_rsp function
230 : *
231 : * If uart_rx_buf_rsp is not called before current buffer
232 : * is filled up, receiving will stop.
233 : */
234 : UART_RX_BUF_REQUEST,
235 : /**
236 : * @brief Buffer is no longer used by UART driver.
237 : */
238 : UART_RX_BUF_RELEASED,
239 : /**
240 : * @brief RX has been disabled and can be reenabled.
241 : *
242 : * This event is generated whenever receiver has been stopped, disabled
243 : * or finished its operation and can be enabled again using
244 : * uart_rx_enable
245 : */
246 : UART_RX_DISABLED,
247 : /**
248 : * @brief RX has stopped due to external event.
249 : *
250 : * Reason is one of uart_rx_stop_reason.
251 : */
252 : UART_RX_STOPPED,
253 : };
254 :
255 : /** @brief UART TX event data. */
256 1 : struct uart_event_tx {
257 : /** @brief Pointer to current buffer. */
258 1 : const uint8_t *buf;
259 : /** @brief Number of bytes sent. */
260 1 : size_t len;
261 : };
262 :
263 : /**
264 : * @brief UART RX event data.
265 : *
266 : * The data represented by the event is stored in rx.buf[rx.offset] to
267 : * rx.buf[rx.offset+rx.len]. That is, the length is relative to the offset.
268 : */
269 1 : struct uart_event_rx {
270 : /** @brief Pointer to current buffer. */
271 1 : uint8_t *buf;
272 : /** @brief Currently received data offset in bytes. */
273 1 : size_t offset;
274 : /** @brief Number of new bytes received. */
275 1 : size_t len;
276 : };
277 :
278 : /** @brief UART RX buffer released event data. */
279 1 : struct uart_event_rx_buf {
280 : /** @brief Pointer to buffer that is no longer in use. */
281 1 : uint8_t *buf;
282 : };
283 :
284 : /** @brief UART RX stopped data. */
285 1 : struct uart_event_rx_stop {
286 : /** @brief Reason why receiving stopped */
287 1 : enum uart_rx_stop_reason reason;
288 : /** @brief Last received data. */
289 1 : struct uart_event_rx data;
290 : };
291 :
292 : /** @brief Structure containing information about current event. */
293 1 : struct uart_event {
294 : /** @brief Type of event */
295 1 : enum uart_event_type type;
296 : /** @brief Event data */
297 1 : union uart_event_data {
298 : /** @brief #UART_TX_DONE and #UART_TX_ABORTED events data. */
299 1 : struct uart_event_tx tx;
300 : /** @brief #UART_RX_RDY event data. */
301 1 : struct uart_event_rx rx;
302 : /** @brief #UART_RX_BUF_RELEASED event data. */
303 1 : struct uart_event_rx_buf rx_buf;
304 : /** @brief #UART_RX_STOPPED event data. */
305 1 : struct uart_event_rx_stop rx_stop;
306 0 : } data;
307 : };
308 :
309 : /**
310 : * @typedef uart_callback_t
311 : * @brief Define the application callback function signature for
312 : * uart_callback_set() function.
313 : *
314 : * @param dev UART device instance.
315 : * @param evt Pointer to uart_event instance.
316 : * @param user_data Pointer to data specified by user.
317 : */
318 1 : typedef void (*uart_callback_t)(const struct device *dev,
319 : struct uart_event *evt, void *user_data);
320 :
321 : /**
322 : * @}
323 : */
324 :
325 : /**
326 : * @brief Check whether an error was detected.
327 : *
328 : * @param dev UART device instance.
329 : *
330 : * @retval 0 If no error was detected.
331 : * @retval err Error flags as defined in @ref uart_rx_stop_reason
332 : * @retval -ENOSYS If not implemented.
333 : */
334 1 : __syscall int uart_err_check(const struct device *dev);
335 :
336 : /**
337 : * @defgroup uart_polling Polling UART API
338 : * @{
339 : */
340 :
341 : /**
342 : * @brief Read a character from the device for input.
343 : *
344 : * This routine checks if the receiver has valid data. When the
345 : * receiver has valid data, it reads a character from the device,
346 : * stores to the location pointed to by p_char, and returns 0 to the
347 : * calling thread. It returns -1, otherwise. This function is a
348 : * non-blocking call.
349 : *
350 : * @param dev UART device instance.
351 : * @param p_char Pointer to character.
352 : *
353 : * @retval 0 If a character arrived.
354 : * @retval -1 If no character was available to read (i.e. the UART
355 : * input buffer was empty).
356 : * @retval -ENOSYS If the operation is not implemented.
357 : * @retval -EBUSY If async reception was enabled using @ref uart_rx_enable
358 : */
359 1 : __syscall int uart_poll_in(const struct device *dev, unsigned char *p_char);
360 :
361 : /**
362 : * @brief Read a 16-bit datum from the device for input.
363 : *
364 : * This routine checks if the receiver has valid data. When the
365 : * receiver has valid data, it reads a 16-bit datum from the device,
366 : * stores to the location pointed to by p_u16, and returns 0 to the
367 : * calling thread. It returns -1, otherwise. This function is a
368 : * non-blocking call.
369 : *
370 : * @param dev UART device instance.
371 : * @param p_u16 Pointer to 16-bit data.
372 : *
373 : * @retval 0 If data arrived.
374 : * @retval -1 If no data was available to read (i.e., the UART
375 : * input buffer was empty).
376 : * @retval -ENOTSUP If API is not enabled.
377 : * @retval -ENOSYS If the function is not implemented.
378 : * @retval -EBUSY If async reception was enabled using @ref uart_rx_enable
379 : */
380 1 : __syscall int uart_poll_in_u16(const struct device *dev, uint16_t *p_u16);
381 :
382 : /**
383 : * @brief Write a character to the device for output.
384 : *
385 : * This routine checks if the transmitter is full. When the
386 : * transmitter is not full, it writes a character to the data
387 : * register. It waits and blocks the calling thread otherwise. This
388 : * function is a blocking call. It blocks the calling thread until the
389 : * character is sent.
390 : *
391 : * To send a character when hardware flow control is enabled, the handshake
392 : * signal CTS must be asserted.
393 : *
394 : * @param dev UART device instance.
395 : * @param out_char Character to send.
396 : */
397 1 : __syscall void uart_poll_out(const struct device *dev,
398 : unsigned char out_char);
399 :
400 : /**
401 : * @brief Write a 16-bit datum to the device for output.
402 : *
403 : * This routine checks if the transmitter is full. When the
404 : * transmitter is not full, it writes a 16-bit datum to the data
405 : * register. It waits and blocks the calling thread, otherwise. This
406 : * function is a blocking call.
407 : *
408 : * To send a datum when hardware flow control is enabled, the handshake
409 : * signal CTS must be asserted.
410 : *
411 : * @param dev UART device instance.
412 : * @param out_u16 Wide data to send.
413 : */
414 1 : __syscall void uart_poll_out_u16(const struct device *dev, uint16_t out_u16);
415 :
416 : /**
417 : * @}
418 : */
419 :
420 : /**
421 : * @brief Set UART configuration.
422 : *
423 : * Sets UART configuration using data from *cfg.
424 : *
425 : * @param dev UART device instance.
426 : * @param cfg UART configuration structure.
427 : *
428 : * @retval 0 If successful.
429 : * @retval -errno Negative errno code in case of failure.
430 : * @retval -ENOSYS If configuration is not supported by device
431 : * or driver does not support setting configuration in runtime.
432 : * @retval -ENOTSUP If API is not enabled.
433 : */
434 1 : __syscall int uart_configure(const struct device *dev,
435 : const struct uart_config *cfg);
436 :
437 : /**
438 : * @brief Get UART configuration.
439 : *
440 : * Stores current UART configuration to *cfg, can be used to retrieve initial
441 : * configuration after device was initialized using data from DTS.
442 : *
443 : * @param dev UART device instance.
444 : * @param cfg UART configuration structure.
445 : *
446 : * @retval 0 If successful.
447 : * @retval -errno Negative errno code in case of failure.
448 : * @retval -ENOSYS If driver does not support getting current configuration.
449 : * @retval -ENOTSUP If API is not enabled.
450 : */
451 1 : __syscall int uart_config_get(const struct device *dev,
452 : struct uart_config *cfg);
453 :
454 : /**
455 : * @addtogroup uart_interrupt
456 : * @{
457 : */
458 :
459 : /**
460 : * @brief Fill FIFO with data.
461 : *
462 : * @details This function is expected to be called from UART
463 : * interrupt handler (ISR), if uart_irq_tx_ready() returns true.
464 : * Result of calling this function not from an ISR is undefined
465 : * (hardware-dependent). Likewise, *not* calling this function
466 : * from an ISR if uart_irq_tx_ready() returns true may lead to
467 : * undefined behavior, e.g. infinite interrupt loops. It's
468 : * mandatory to test return value of this function, as different
469 : * hardware has different FIFO depth (oftentimes just 1).
470 : *
471 : * @param dev UART device instance.
472 : * @param tx_data Data to transmit.
473 : * @param size Number of bytes to send.
474 : *
475 : * @return Number of bytes sent.
476 : * @retval -ENOSYS if this function is not supported
477 : * @retval -ENOTSUP If API is not enabled.
478 : */
479 1 : static inline int uart_fifo_fill(const struct device *dev, const uint8_t *tx_data, int size);
480 :
481 : /**
482 : * @brief Fill FIFO with wide data.
483 : *
484 : * @details This function is expected to be called from UART
485 : * interrupt handler (ISR), if uart_irq_tx_ready() returns true.
486 : * Result of calling this function not from an ISR is undefined
487 : * (hardware-dependent). Likewise, *not* calling this function
488 : * from an ISR if uart_irq_tx_ready() returns true may lead to
489 : * undefined behavior, e.g. infinite interrupt loops. It's
490 : * mandatory to test return value of this function, as different
491 : * hardware has different FIFO depth (oftentimes just 1).
492 : *
493 : * @param dev UART device instance.
494 : * @param tx_data Wide data to transmit.
495 : * @param size Number of datum to send.
496 : *
497 : * @return Number of datum sent.
498 : * @retval -ENOSYS If this function is not implemented
499 : * @retval -ENOTSUP If API is not enabled.
500 : */
501 1 : static inline int uart_fifo_fill_u16(const struct device *dev, const uint16_t *tx_data, int size);
502 :
503 : /**
504 : * @brief Read data from FIFO.
505 : *
506 : * @details This function is expected to be called from UART
507 : * interrupt handler (ISR), if uart_irq_rx_ready() returns true.
508 : * Result of calling this function not from an ISR is undefined
509 : * (hardware-dependent). It's unspecified whether "RX ready"
510 : * condition as returned by uart_irq_rx_ready() is level- or
511 : * edge- triggered. That means that once uart_irq_rx_ready() is
512 : * detected, uart_fifo_read() must be called until it reads all
513 : * available data in the FIFO (i.e. until it returns less data
514 : * than was requested).
515 : *
516 : * @param dev UART device instance.
517 : * @param rx_data Data container.
518 : * @param size Container size.
519 : *
520 : * @return Number of bytes read.
521 : * @retval -ENOSYS If this function is not implemented.
522 : * @retval -ENOTSUP If API is not enabled.
523 : */
524 1 : static inline int uart_fifo_read(const struct device *dev, uint8_t *rx_data, const int size);
525 :
526 : /**
527 : * @brief Read wide data from FIFO.
528 : *
529 : * @details This function is expected to be called from UART
530 : * interrupt handler (ISR), if uart_irq_rx_ready() returns true.
531 : * Result of calling this function not from an ISR is undefined
532 : * (hardware-dependent). It's unspecified whether "RX ready"
533 : * condition as returned by uart_irq_rx_ready() is level- or
534 : * edge- triggered. That means that once uart_irq_rx_ready() is
535 : * detected, uart_fifo_read() must be called until it reads all
536 : * available data in the FIFO (i.e. until it returns less data
537 : * than was requested).
538 : *
539 : * @param dev UART device instance.
540 : * @param rx_data Wide data container.
541 : * @param size Container size.
542 : *
543 : * @return Number of datum read.
544 : * @retval -ENOSYS If this function is not implemented.
545 : * @retval -ENOTSUP If API is not enabled.
546 : */
547 1 : static inline int uart_fifo_read_u16(const struct device *dev, uint16_t *rx_data, const int size);
548 :
549 : /**
550 : * @brief Enable TX interrupt in IER.
551 : *
552 : * @param dev UART device instance.
553 : */
554 1 : __syscall void uart_irq_tx_enable(const struct device *dev);
555 :
556 : /**
557 : * @brief Disable TX interrupt in IER.
558 : *
559 : * @param dev UART device instance.
560 : */
561 1 : __syscall void uart_irq_tx_disable(const struct device *dev);
562 :
563 : /**
564 : * @brief Check if UART TX buffer can accept bytes
565 : *
566 : * @details Check if UART TX buffer can accept more bytes
567 : * for transmission (i.e. uart_fifo_fill() will succeed and return
568 : * non-zero). This function must be called in a UART interrupt
569 : * handler, or its result is undefined. Before calling this function
570 : * in the interrupt handler, uart_irq_update() must be called once per
571 : * the handler invocation.
572 : *
573 : * @param dev UART device instance.
574 : *
575 : * @retval 0 If device is not ready to write a new byte.
576 : * @retval >0 Minimum number of bytes that can be written in a single call to
577 : * @ref uart_fifo_fill. It may be possible to write more bytes, but
578 : * the actual number written must be checked in the return code from
579 : * @ref uart_fifo_fill.
580 : * @retval -ENOSYS If this function is not implemented.
581 : * @retval -ENOTSUP If API is not enabled.
582 : */
583 1 : static inline int uart_irq_tx_ready(const struct device *dev);
584 :
585 : /**
586 : * @brief Enable RX interrupt.
587 : *
588 : * @param dev UART device instance.
589 : */
590 1 : __syscall void uart_irq_rx_enable(const struct device *dev);
591 :
592 : /**
593 : * @brief Disable RX interrupt.
594 : *
595 : * @param dev UART device instance.
596 : */
597 1 : __syscall void uart_irq_rx_disable(const struct device *dev);
598 :
599 : /**
600 : * @brief Check if UART TX block finished transmission
601 : *
602 : * @details Check if any outgoing data buffered in UART TX block was
603 : * fully transmitted and TX block is idle. When this condition is
604 : * true, UART device (or whole system) can be power off. Note that
605 : * this function is *not* useful to check if UART TX can accept more
606 : * data, use uart_irq_tx_ready() for that. This function must be called
607 : * in a UART interrupt handler, or its result is undefined. Before
608 : * calling this function in the interrupt handler, uart_irq_update()
609 : * must be called once per the handler invocation.
610 : *
611 : * @param dev UART device instance.
612 : *
613 : * @retval 1 If nothing remains to be transmitted.
614 : * @retval 0 If transmission is not completed.
615 : * @retval -ENOSYS If this function is not implemented.
616 : * @retval -ENOTSUP If API is not enabled.
617 : */
618 1 : static inline int uart_irq_tx_complete(const struct device *dev);
619 :
620 : /**
621 : * @brief Check if UART RX buffer has a received char
622 : *
623 : * @details Check if UART RX buffer has at least one pending character
624 : * (i.e. uart_fifo_read() will succeed and return non-zero). This function
625 : * must be called in a UART interrupt handler, or its result is undefined.
626 : * Before calling this function in the interrupt handler, uart_irq_update()
627 : * must be called once per the handler invocation. It's unspecified whether
628 : * condition as returned by this function is level- or edge- triggered (i.e.
629 : * if this function returns true when RX FIFO is non-empty, or when a new
630 : * char was received since last call to it). See description of
631 : * uart_fifo_read() for implication of this.
632 : *
633 : * @param dev UART device instance.
634 : *
635 : * @retval 1 If a received char is ready.
636 : * @retval 0 If a received char is not ready.
637 : * @retval -ENOSYS If this function is not implemented.
638 : * @retval -ENOTSUP If API is not enabled.
639 : */
640 1 : static inline int uart_irq_rx_ready(const struct device *dev);
641 :
642 : /**
643 : * @brief Enable error interrupt.
644 : *
645 : * @param dev UART device instance.
646 : */
647 1 : __syscall void uart_irq_err_enable(const struct device *dev);
648 :
649 : /**
650 : * @brief Disable error interrupt.
651 : *
652 : * @param dev UART device instance.
653 : */
654 1 : __syscall void uart_irq_err_disable(const struct device *dev);
655 :
656 : /**
657 : * @brief Check if any IRQs is pending.
658 : *
659 : * @param dev UART device instance.
660 : *
661 : * @retval 1 If an IRQ is pending.
662 : * @retval 0 If an IRQ is not pending.
663 : * @retval -ENOSYS If this function is not implemented.
664 : * @retval -ENOTSUP If API is not enabled.
665 : */
666 1 : __syscall int uart_irq_is_pending(const struct device *dev);
667 :
668 : /**
669 : * @brief Start processing interrupts in ISR.
670 : *
671 : * This function should be called the first thing in the ISR. Calling
672 : * uart_irq_rx_ready(), uart_irq_tx_ready(), uart_irq_tx_complete()
673 : * allowed only after this.
674 : *
675 : * The purpose of this function is:
676 : *
677 : * * For devices with auto-acknowledge of interrupt status on register
678 : * read to cache the value of this register (rx_ready, etc. then use
679 : * this case).
680 : * * For devices with explicit acknowledgment of interrupts, to ack
681 : * any pending interrupts and likewise to cache the original value.
682 : * * For devices with implicit acknowledgment, this function will be
683 : * empty. But the ISR must perform the actions needs to ack the
684 : * interrupts (usually, call uart_fifo_read() on rx_ready, and
685 : * uart_fifo_fill() on tx_ready).
686 : *
687 : * @param dev UART device instance.
688 : *
689 : * @retval 1 On success.
690 : * @retval -ENOSYS If this function is not implemented.
691 : * @retval -ENOTSUP If API is not enabled.
692 : */
693 1 : __syscall int uart_irq_update(const struct device *dev);
694 :
695 : /**
696 : * @brief Set the IRQ callback function pointer.
697 : *
698 : * This sets up the callback for IRQ. When an IRQ is triggered,
699 : * the specified function will be called with specified user data.
700 : * See description of uart_irq_update() for the requirements on ISR.
701 : *
702 : * @param dev UART device instance.
703 : * @param cb Pointer to the callback function.
704 : * @param user_data Data to pass to callback function.
705 : *
706 : * @retval 0 On success.
707 : * @retval -ENOSYS If this function is not implemented.
708 : * @retval -ENOTSUP If API is not enabled.
709 : */
710 1 : static inline int uart_irq_callback_user_data_set(const struct device *dev,
711 : uart_irq_callback_user_data_t cb,
712 : void *user_data);
713 :
714 : /**
715 : * @brief Set the IRQ callback function pointer (legacy).
716 : *
717 : * This sets up the callback for IRQ. When an IRQ is triggered,
718 : * the specified function will be called with the device pointer.
719 : *
720 : * @param dev UART device instance.
721 : * @param cb Pointer to the callback function.
722 : *
723 : * @retval 0 On success.
724 : * @retval -ENOSYS If this function is not implemented.
725 : * @retval -ENOTSUP If API is not enabled.
726 : */
727 1 : static inline int uart_irq_callback_set(const struct device *dev,
728 : uart_irq_callback_user_data_t cb);
729 :
730 : /**
731 : * @}
732 : */
733 :
734 : /**
735 : * @addtogroup uart_async
736 : * @{
737 : */
738 :
739 : /**
740 : * @brief Set event handler function.
741 : *
742 : * Since it is mandatory to set callback to use other asynchronous functions,
743 : * it can be used to detect if the device supports asynchronous API. Remaining
744 : * API does not have that detection.
745 : *
746 : * @param dev UART device instance.
747 : * @param callback Event handler.
748 : * @param user_data Data to pass to event handler function.
749 : *
750 : * @retval 0 If successful.
751 : * @retval -ENOSYS If not supported by the device.
752 : * @retval -ENOTSUP If API not enabled.
753 : */
754 1 : static inline int uart_callback_set(const struct device *dev,
755 : uart_callback_t callback,
756 : void *user_data);
757 :
758 : /**
759 : * @brief Send given number of bytes from buffer through UART.
760 : *
761 : * Function returns immediately and event handler,
762 : * set using @ref uart_callback_set, is called after transfer is finished.
763 : *
764 : * @param dev UART device instance.
765 : * @param buf Pointer to transmit buffer.
766 : * @param len Length of transmit buffer.
767 : * @param timeout Timeout in microseconds. Valid only if flow control is
768 : * enabled. @ref SYS_FOREVER_US disables timeout.
769 : *
770 : * @retval 0 If successful.
771 : * @retval -ENOTSUP If API is not enabled.
772 : * @retval -EBUSY If There is already an ongoing transfer.
773 : * @retval -errno Other negative errno value in case of failure.
774 : */
775 1 : __syscall int uart_tx(const struct device *dev, const uint8_t *buf,
776 : size_t len,
777 : int32_t timeout);
778 :
779 : /**
780 : * @brief Send given number of datum from buffer through UART.
781 : *
782 : * Function returns immediately and event handler,
783 : * set using @ref uart_callback_set, is called after transfer is finished.
784 : *
785 : * @param dev UART device instance.
786 : * @param buf Pointer to wide data transmit buffer.
787 : * @param len Length of wide data transmit buffer.
788 : * @param timeout Timeout in milliseconds. Valid only if flow control is
789 : * enabled. @ref SYS_FOREVER_MS disables timeout.
790 : *
791 : * @retval 0 If successful.
792 : * @retval -ENOTSUP If API is not enabled.
793 : * @retval -EBUSY If there is already an ongoing transfer.
794 : * @retval -errno Other negative errno value in case of failure.
795 : */
796 1 : __syscall int uart_tx_u16(const struct device *dev, const uint16_t *buf,
797 : size_t len, int32_t timeout);
798 :
799 : /**
800 : * @brief Abort current TX transmission.
801 : *
802 : * #UART_TX_DONE event will be generated with amount of data sent.
803 : *
804 : * @param dev UART device instance.
805 : *
806 : * @retval 0 If successful.
807 : * @retval -ENOTSUP If API is not enabled.
808 : * @retval -EFAULT There is no active transmission.
809 : * @retval -errno Other negative errno value in case of failure.
810 : */
811 1 : __syscall int uart_tx_abort(const struct device *dev);
812 :
813 : /**
814 : * @brief Start receiving data through UART.
815 : *
816 : * Function sets given buffer as first buffer for receiving and returns
817 : * immediately. After that event handler, set using @ref uart_callback_set,
818 : * is called with #UART_RX_RDY or #UART_RX_BUF_REQUEST events.
819 : *
820 : * @param dev UART device instance.
821 : * @param buf Pointer to receive buffer.
822 : * @param len Buffer length.
823 : * @param timeout Inactivity period after receiving at least a byte which
824 : * triggers #UART_RX_RDY event. Given in microseconds.
825 : * @ref SYS_FOREVER_US disables timeout. See @ref uart_event_type
826 : * for details.
827 : *
828 : * @retval 0 If successful.
829 : * @retval -ENOTSUP If API is not enabled.
830 : * @retval -EBUSY RX already in progress.
831 : * @retval -errno Other negative errno value in case of failure.
832 : *
833 : */
834 1 : __syscall int uart_rx_enable(const struct device *dev, uint8_t *buf,
835 : size_t len,
836 : int32_t timeout);
837 :
838 : /**
839 : * @brief Start receiving wide data through UART.
840 : *
841 : * Function sets given buffer as first buffer for receiving and returns
842 : * immediately. After that event handler, set using @ref uart_callback_set,
843 : * is called with #UART_RX_RDY or #UART_RX_BUF_REQUEST events.
844 : *
845 : * @param dev UART device instance.
846 : * @param buf Pointer to wide data receive buffer.
847 : * @param len Buffer length.
848 : * @param timeout Inactivity period after receiving at least a byte which
849 : * triggers #UART_RX_RDY event. Given in milliseconds.
850 : * @ref SYS_FOREVER_MS disables timeout. See
851 : * @ref uart_event_type for details.
852 : *
853 : * @retval 0 If successful.
854 : * @retval -ENOTSUP If API is not enabled.
855 : * @retval -EBUSY RX already in progress.
856 : * @retval -errno Other negative errno value in case of failure.
857 : *
858 : */
859 1 : __syscall int uart_rx_enable_u16(const struct device *dev, uint16_t *buf,
860 : size_t len, int32_t timeout);
861 :
862 : /**
863 : * @brief Provide receive buffer in response to #UART_RX_BUF_REQUEST event.
864 : *
865 : * Provide pointer to RX buffer, which will be used when current buffer is
866 : * filled.
867 : *
868 : * @note Providing buffer that is already in usage by driver leads to
869 : * undefined behavior. Buffer can be reused when it has been released
870 : * by driver.
871 : *
872 : * @param dev UART device instance.
873 : * @param buf Pointer to receive buffer.
874 : * @param len Buffer length.
875 : *
876 : * @retval 0 If successful.
877 : * @retval -ENOTSUP If API is not enabled.
878 : * @retval -EBUSY Next buffer already set.
879 : * @retval -EACCES Receiver is already disabled (function called too late?).
880 : * @retval -errno Other negative errno value in case of failure.
881 : */
882 1 : static inline int uart_rx_buf_rsp(const struct device *dev, uint8_t *buf,
883 : size_t len);
884 :
885 : /**
886 : * @brief Provide wide data receive buffer in response to #UART_RX_BUF_REQUEST
887 : * event.
888 : *
889 : * Provide pointer to RX buffer, which will be used when current buffer is
890 : * filled.
891 : *
892 : * @note Providing buffer that is already in usage by driver leads to
893 : * undefined behavior. Buffer can be reused when it has been released
894 : * by driver.
895 : *
896 : * @param dev UART device instance.
897 : * @param buf Pointer to wide data receive buffer.
898 : * @param len Buffer length.
899 : *
900 : * @retval 0 If successful.
901 : * @retval -ENOTSUP If API is not enabled
902 : * @retval -EBUSY Next buffer already set.
903 : * @retval -EACCES Receiver is already disabled (function called too late?).
904 : * @retval -errno Other negative errno value in case of failure.
905 : */
906 1 : static inline int uart_rx_buf_rsp_u16(const struct device *dev, uint16_t *buf,
907 : size_t len);
908 :
909 : /**
910 : * @brief Disable RX
911 : *
912 : * #UART_RX_BUF_RELEASED event will be generated for every buffer scheduled,
913 : * after that #UART_RX_DISABLED event will be generated. Additionally, if there
914 : * is any pending received data, the #UART_RX_RDY event for that data will be
915 : * generated before the #UART_RX_BUF_RELEASED events.
916 : *
917 : * @param dev UART device instance.
918 : *
919 : * @retval 0 If successful.
920 : * @retval -ENOTSUP If API is not enabled.
921 : * @retval -EFAULT There is no active reception.
922 : * @retval -errno Other negative errno value in case of failure.
923 : */
924 1 : __syscall int uart_rx_disable(const struct device *dev);
925 :
926 : /**
927 : * @}
928 : */
929 :
930 : /**
931 : * @brief Manipulate line control for UART.
932 : *
933 : * @param dev UART device instance.
934 : * @param ctrl The line control to manipulate (see enum uart_line_ctrl).
935 : * @param val Value to set to the line control.
936 : *
937 : * @retval 0 If successful.
938 : * @retval -ENOSYS If this function is not implemented.
939 : * @retval -ENOTSUP If API is not enabled.
940 : * @retval -errno Other negative errno value in case of failure.
941 : */
942 1 : __syscall int uart_line_ctrl_set(const struct device *dev,
943 : uint32_t ctrl, uint32_t val);
944 :
945 : /**
946 : * @brief Retrieve line control for UART.
947 : *
948 : * @param dev UART device instance.
949 : * @param ctrl The line control to retrieve (see enum uart_line_ctrl).
950 : * @param val Pointer to variable where to store the line control value.
951 : *
952 : * @retval 0 If successful.
953 : * @retval -ENOSYS If this function is not implemented.
954 : * @retval -ENOTSUP If API is not enabled.
955 : * @retval -errno Other negative errno value in case of failure.
956 : */
957 1 : __syscall int uart_line_ctrl_get(const struct device *dev, uint32_t ctrl,
958 : uint32_t *val);
959 :
960 : /**
961 : * @brief Send extra command to driver.
962 : *
963 : * Implementation and accepted commands are driver specific.
964 : * Refer to the drivers for more information.
965 : *
966 : * @param dev UART device instance.
967 : * @param cmd Command to driver.
968 : * @param p Parameter to the command.
969 : *
970 : * @retval 0 If successful.
971 : * @retval -ENOSYS If this function is not implemented.
972 : * @retval -ENOTSUP If API is not enabled.
973 : * @retval -errno Other negative errno value in case of failure.
974 : */
975 1 : __syscall int uart_drv_cmd(const struct device *dev, uint32_t cmd, uint32_t p);
976 :
977 : #ifdef __cplusplus
978 : }
979 : #endif
980 :
981 : /**
982 : * @}
983 : */
984 :
985 : #include <zephyr/drivers/uart/uart_internal.h>
986 : #include <zephyr/syscalls/uart.h>
987 :
988 : #endif /* ZEPHYR_INCLUDE_DRIVERS_UART_H_ */
|
