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