mirror of
https://github.com/zephyrproject-rtos/zephyr
synced 2025-09-09 11:22:39 +00:00
df294e34e1
Fixes bad usage of single backticks in lieu of double backticks for rendering inline literals, or simple '*' for italics. When appropriate, a better construct than double backticks has been selected (ex. :file:, :kconfig:option:, :c:func:, ...), or proper :ref: have been used if the original intention was to have a link. Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
87 lines
2.5 KiB
ReStructuredText
87 lines
2.5 KiB
ReStructuredText
.. _uart_api:
|
|
|
|
Universal Asynchronous Receiver-Transmitter (UART)
|
|
##################################################
|
|
|
|
Overview
|
|
********
|
|
|
|
Zephyr provides three different ways to access the UART peripheral. Depending
|
|
on the method, different API functions are used according to below sections:
|
|
|
|
1. :ref:`uart_polling_api`
|
|
2. :ref:`uart_interrupt_api`
|
|
3. :ref:`uart_async_api` using :ref:`dma_api`
|
|
|
|
Polling is the most basic method to access the UART peripheral. The reading
|
|
function, :c:func:`uart_poll_in`, is a non-blocking function and returns a character
|
|
or ``-1`` when no valid data is available. The writing function,
|
|
:c:func:`uart_poll_out`, is a blocking function and the thread waits until the given
|
|
character is sent.
|
|
|
|
With the Interrupt-driven API, possibly slow communication can happen in the
|
|
background while the thread continues with other tasks. The Kernel's
|
|
:ref:`kernel_data_passing_api` features can be used to communicate between
|
|
the thread and the UART driver.
|
|
|
|
The Asynchronous API allows to read and write data in the background using DMA
|
|
without interrupting the MCU at all. However, the setup is more complex
|
|
than the other methods.
|
|
|
|
.. warning::
|
|
|
|
Interrupt-driven API and the Asynchronous API should NOT be used at
|
|
the same time for the same hardware peripheral, since both APIs require
|
|
hardware interrupts to function properly. Using the callbacks for both
|
|
APIs would result in interference between each other.
|
|
:kconfig:option:`CONFIG_UART_EXCLUSIVE_API_CALLBACKS` is enabled by default
|
|
so that only the callbacks associated with one API is active at a time.
|
|
|
|
|
|
Configuration Options
|
|
*********************
|
|
|
|
Most importantly, the Kconfig options define whether the polling API (default),
|
|
the interrupt-driven API or the asynchronous API can be used. Only enable the
|
|
features you need in order to minimize memory footprint.
|
|
|
|
Related configuration options:
|
|
|
|
* :kconfig:option:`CONFIG_SERIAL`
|
|
* :kconfig:option:`CONFIG_UART_INTERRUPT_DRIVEN`
|
|
* :kconfig:option:`CONFIG_UART_ASYNC_API`
|
|
* :kconfig:option:`CONFIG_UART_WIDE_DATA`
|
|
* :kconfig:option:`CONFIG_UART_USE_RUNTIME_CONFIGURE`
|
|
* :kconfig:option:`CONFIG_UART_LINE_CTRL`
|
|
* :kconfig:option:`CONFIG_UART_DRV_CMD`
|
|
|
|
|
|
API Reference
|
|
*************
|
|
|
|
.. doxygengroup:: uart_interface
|
|
|
|
|
|
.. _uart_polling_api:
|
|
|
|
Polling API
|
|
===========
|
|
|
|
.. doxygengroup:: uart_polling
|
|
|
|
|
|
.. _uart_interrupt_api:
|
|
|
|
Interrupt-driven API
|
|
====================
|
|
|
|
.. doxygengroup:: uart_interrupt
|
|
|
|
|
|
.. _uart_async_api:
|
|
|
|
Asynchronous API
|
|
================
|
|
|
|
.. doxygengroup:: uart_async
|