1.. _uart_api:
2
3Universal Asynchronous Receiver-Transmitter (UART)
4##################################################
5
6Overview
7********
8
9Zephyr provides three different ways to access the UART peripheral. Depending
10on the method, different API functions are used according to below sections:
11
121. :ref:`uart_polling_api`
132. :ref:`uart_interrupt_api`
143. :ref:`uart_async_api` using :ref:`dma_api`
15
16Polling is the most basic method to access the UART peripheral. The reading
17function, `uart_poll_in`, is a non-blocking function and returns a character
18or `-1` when no valid data is available. The writing function,
19`uart_poll_out`, is a blocking function and the thread waits until the given
20character is sent.
21
22With the Interrupt-driven API, possibly slow communication can happen in the
23background while the thread continues with other tasks. The Kernel's
24:ref:`kernel_data_passing_api` features can be used to communicate between
25the thread and the UART driver.
26
27The Asynchronous API allows to read and write data in the background using DMA
28without interrupting the MCU at all. However, the setup is more complex
29than the other methods.
30
31.. warning::
32
33   Interrupt-driven API and the Asynchronous API should NOT be used at
34   the same time, since both APIs require hardware interrupts to function
35   properly, using the callbacks for both APIs would result in interference
36   between each other. :kconfig:option:`CONFIG_UART_EXCLUSIVE_API_CALLBACKS`
37   is enabled by default so that only the callbacks associated with one API
38   is active at a time.
39
40
41Configuration Options
42*********************
43
44Most importantly, the Kconfig options define whether the polling API (default),
45the interrupt-driven API or the asynchronous API can be used. Only enable the
46features you need in order to minimize memory footprint.
47
48Related configuration options:
49
50* :kconfig:option:`CONFIG_SERIAL`
51* :kconfig:option:`CONFIG_UART_INTERRUPT_DRIVEN`
52* :kconfig:option:`CONFIG_UART_ASYNC_API`
53* :kconfig:option:`CONFIG_UART_WIDE_DATA`
54* :kconfig:option:`CONFIG_UART_USE_RUNTIME_CONFIGURE`
55* :kconfig:option:`CONFIG_UART_LINE_CTRL`
56* :kconfig:option:`CONFIG_UART_DRV_CMD`
57
58
59API Reference
60*************
61
62.. doxygengroup:: uart_interface
63
64
65.. _uart_polling_api:
66
67Polling API
68===========
69
70.. doxygengroup:: uart_polling
71
72
73.. _uart_interrupt_api:
74
75Interrupt-driven API
76====================
77
78.. doxygengroup:: uart_interrupt
79
80
81.. _uart_async_api:
82
83Asynchronous API
84================
85
86.. doxygengroup:: uart_async
87