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