Merge branch 'docs/add_p4_uart_programming_guide' into 'master'

docs(uart): update lp uart and p4 uart programming guide

Closes IDF-7737

See merge request espressif/esp-idf!29179
This commit is contained in:
Gao Xu 2024-03-04 11:00:05 +08:00
commit 3e54584e61
10 changed files with 71 additions and 56 deletions

View File

@ -395,6 +395,10 @@ config SOC_UART_SUPPORT_WAKEUP_INT
bool
default y
config SOC_UART_HAS_LP_UART
bool
default y
config SOC_UART_SUPPORT_FSM_TX_WAIT_SEND
bool
default y

View File

@ -480,6 +480,7 @@
// #define SOC_UART_SUPPORT_RTC_CLK (1) // TODO: [ESP32C5] IDF-8642
#define SOC_UART_SUPPORT_XTAL_CLK (1) /*!< Support XTAL clock as the clock source */
#define SOC_UART_SUPPORT_WAKEUP_INT (1) /*!< Support UART wakeup interrupt */
#define SOC_UART_HAS_LP_UART (1) /*!< Support LP UART */
// UART has an extra TX_WAIT_SEND state when the FIFO is not empty and XOFF is enabled
#define SOC_UART_SUPPORT_FSM_TX_WAIT_SEND (1)

View File

@ -1187,6 +1187,10 @@ config SOC_UART_SUPPORT_WAKEUP_INT
bool
default y
config SOC_UART_HAS_LP_UART
bool
default y
config SOC_UART_SUPPORT_FSM_TX_WAIT_SEND
bool
default y

View File

@ -471,6 +471,7 @@
#define SOC_UART_SUPPORT_RTC_CLK (1) /*!< Support RTC clock as the clock source */
#define SOC_UART_SUPPORT_XTAL_CLK (1) /*!< Support XTAL clock as the clock source */
#define SOC_UART_SUPPORT_WAKEUP_INT (1) /*!< Support UART wakeup interrupt */
#define SOC_UART_HAS_LP_UART (1) /*!< Support LP UART */
// UART has an extra TX_WAIT_SEND state when the FIFO is not empty and XOFF is enabled
#define SOC_UART_SUPPORT_FSM_TX_WAIT_SEND (1)

View File

@ -1299,6 +1299,10 @@ config SOC_UART_SUPPORT_WAKEUP_INT
bool
default y
config SOC_UART_HAS_LP_UART
bool
default y
config SOC_UART_SUPPORT_FSM_TX_WAIT_SEND
bool
default y

View File

@ -539,6 +539,7 @@
#define SOC_UART_SUPPORT_RTC_CLK (1) /*!< Support RTC clock as the clock source */
#define SOC_UART_SUPPORT_XTAL_CLK (1) /*!< Support XTAL clock as the clock source */
#define SOC_UART_SUPPORT_WAKEUP_INT (1) /*!< Support UART wakeup interrupt */
#define SOC_UART_HAS_LP_UART (1) /*!< Support LP UART */
// UART has an extra TX_WAIT_SEND state when the FIFO is not empty and XOFF is enabled
#define SOC_UART_SUPPORT_FSM_TX_WAIT_SEND (1)

View File

@ -147,7 +147,6 @@ api-reference/peripherals/sd_pullup_requirements.rst
api-reference/peripherals/spi_master.rst
api-reference/peripherals/index.rst
api-reference/peripherals/sdmmc_host.rst
api-reference/peripherals/uart.rst
api-reference/peripherals/ecdsa.rst
api-reference/peripherals/rmt.rst
api-reference/kconfig.rst

View File

@ -83,7 +83,6 @@ api-reference/peripherals/i2c.rst
api-reference/peripherals/dedic_gpio.rst
api-reference/peripherals/sd_pullup_requirements.rst
api-reference/peripherals/index.rst
api-reference/peripherals/uart.rst
api-reference/network/esp_openthread.rst
api-reference/network/esp_dpp.rst
api-reference/network/esp_now.rst

View File

@ -12,7 +12,7 @@ The {IDF_TARGET_NAME} chip has {IDF_TARGET_SOC_UART_HP_NUM} UART controllers (al
Each UART controller is independently configurable with parameters such as baud rate, data bit length, bit ordering, number of stop bits, parity bit, etc. All the regular UART controllers are compatible with UART-enabled devices from various manufacturers and can also support Infrared Data Association (IrDA) protocols.
.. only:: SOC_UART_LP_NUM
.. only:: SOC_UART_HAS_LP_UART
Additionally, the {IDF_TARGET_NAME} chip has one low-power (LP) UART controller. It is the cut-down version of regular UART. Usually, the LP UART controller only support basic UART functionality with a much smaller RAM size, and does not support IrDA or RS485 protocols. For a full list of difference between UART and LP UART, please refer to the **{IDF_TARGET_NAME} Technical Reference Manual** > **UART Controller (UART)** > **Features** [`PDF <{IDF_TARGET_TRM_EN_URL}#uart>`__]).
@ -30,6 +30,10 @@ The overview describes how to establish communication between an {IDF_TARGET_NAM
Steps 1 to 3 comprise the configuration stage. Step 4 is where the UART starts operating. Steps 5 and 6 are optional.
.. only:: SOC_UART_HAS_LP_UART
Additionally, when using the LP UART Controller you need to pay attention to :ref:`uart-api-lp-uart-driver`.
The UART driver's functions identify each of the UART controllers using :cpp:type:`uart_port_t`. This identification is needed for all the following function calls.
@ -239,32 +243,6 @@ The API provides a convenient way to handle specific interrupts discussed in thi
- Disable the interrupt using :cpp:func:`uart_disable_pattern_det_intr`
Macros
^^^^^^
The API also defines several macros. For example, :c:macro:`UART_HW_FIFO_LEN` defines the length of hardware FIFO buffers; :c:macro:`UART_BITRATE_MAX` gives the maximum baud rate supported by the UART controllers, etc.
.. only:: SOC_UART_LP_NUM
Use LP UART Controller with HP Core
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The UART driver also supports to control the LP UART controller when the chip is in active mode. The configuration steps for the LP UART are no difference with the steps for a normal UART controller, except:
1. The port number for the LP UART controller is defined by :c:macro:`LP_UART_NUM_0`.
2. The available clock sources for the LP UART controller can be found in :cpp:type:`lp_uart_sclk_t`.
3. The size of the hardware FIFO for the LP UART controller is much smaller, which is defined in :c:macro:`SOC_LP_UART_FIFO_LEN`.
.. only:: SOC_LP_GPIO_MATRIX_SUPPORTED
4. The GPIO pins for the LP UART controller can only be selected from the LP GPIO pins.
.. only:: not SOC_LP_GPIO_MATRIX_SUPPORTED
4. The GPIO pins for the LP UART controller are unalterable, because there is no LP GPIO matrix on the target. Please see **{IDF_TARGET_NAME} Technical Reference Manual** > **IO MUX and GPIO Matrix (GPIO, IO MUX)** > **LP IO MUX Functions List** [`PDF <{IDF_TARGET_TRM_EN_URL}#lp-io-mux-func-list>`__] for the specific pin numbers.
.. _uart-api-deleting-driver:
Deleting a Driver
@ -273,6 +251,29 @@ Deleting a Driver
If the communication established with :cpp:func:`uart_driver_install` is no longer required, the driver can be removed to free allocated resources by calling :cpp:func:`uart_driver_delete`.
Macros
^^^^^^
The API also defines several macros. For example, :c:macro:`UART_HW_FIFO_LEN` defines the length of hardware FIFO buffers; :c:macro:`UART_BITRATE_MAX` gives the maximum baud rate supported by the UART controllers, etc.
.. only:: SOC_UART_HAS_LP_UART
.. _uart-api-lp-uart-driver:
Use LP UART Controller with HP Core
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The UART driver also supports to control the LP UART controller when the chip is in active mode. The configuration steps for the LP UART are the same as the steps for a normal UART controller, except:
.. list::
- The port number for the LP UART controller is defined by :c:macro:`LP_UART_NUM_0`.
- The available clock sources for the LP UART controller can be found in :cpp:type:`lp_uart_sclk_t`.
- The size of the hardware FIFO for the LP UART controller is much smaller, which is defined in :c:macro:`SOC_LP_UART_FIFO_LEN`.
:SOC_LP_GPIO_MATRIX_SUPPORTED: - The GPIO pins for the LP UART controller can only be selected from the LP GPIO pins.
:not SOC_LP_GPIO_MATRIX_SUPPORTED: - The GPIO pins for the LP UART controller are unalterable, because there is no LP GPIO matrix on the target. Please see **{IDF_TARGET_NAME} Technical Reference Manual** > **IO MUX and GPIO Matrix (GPIO, IO MUX)** > **LP IO MUX Functions List** [`PDF <{IDF_TARGET_TRM_EN_URL}#lp-io-mux-func-list>`__] for the specific pin numbers.
Overview of RS485 Specific Communication 0ptions
------------------------------------------------

View File

@ -12,7 +12,7 @@
每个 UART 控制器可以独立配置波特率、数据位长度、位顺序、停止位位数、奇偶校验位等参数。所有具备完整功能的 UART 控制器都能与不同制造商的 UART 设备兼容,并且支持红外数据协会 (IrDA) 定义的标准协议。
.. only:: SOC_UART_LP_NUM
.. only:: SOC_UART_HAS_LP_UART
此外,{IDF_TARGET_NAME} 芯片还有一个满足低功耗需求的 LP UART 控制器。LP UART 是原 UART 的功能剪裁版本。它只支持基础 UART 功能,不支持 IrDA 或 RS485 协议,并且只有一块较小的 RAM 存储空间。想要全面了解的 UART 及 LP UART 功能区别,请参考 **{IDF_TARGET_NAME} 技术参考手册** > UART 控制器 (UART) > 主要特性 [`PDF <{IDF_TARGET_TRM_EN_URL}#uart>`__]。
@ -30,6 +30,10 @@
步骤 1 到 3 为配置阶段,步骤 4 为 UART 运行阶段,步骤 5 和 6 为可选步骤。
.. only:: SOC_UART_HAS_LP_UART
此外LP UART 控制器的编程需要注意 :ref:`uart-api-lp-uart-driver`
UART 驱动程序函数通过 :cpp:type:`uart_port_t` 识别不同的 UART 控制器。调用以下所有函数均需此标识。
@ -239,32 +243,6 @@ API 提供了一种便利的方法来处理本文所讨论的特定中断,即
- 禁用中断:调用 :cpp:func:`uart_disable_pattern_det_intr`
宏指令
^^^^^^^^^^^^
API 还定义了一些宏指令。例如,:c:macro:`UART_HW_FIFO_LEN` 定义了硬件 FIFO 缓冲区的长度,:c:macro:`UART_BITRATE_MAX` 定义了 UART 控制器支持的最大波特率。
.. only:: SOC_UART_LP_NUM
使用主核驱动 LP UART 控制器
^^^^^^^^^^^^^^^^^^^^^^^^
UART 驱动程序还适配了在 Active 模式下对 LP UART 控制器的驱动。LP UART 的配置流程和普通 UART 没有本质上的差别,除了有以下几点需要注意:
1. LP UART 控制器的端口号为 :c:macro:`LP_UART_NUM_0`
2. LP UART 控制器的可选时钟源可以在 :cpp:type:`lp_uart_sclk_t` 中找到。
3. LP UART 控制器的硬件 FIFO 大小要远小于普通 UART 控制器的硬件 FIFO 大小,其值为 :c:macro:`SOC_LP_UART_FIFO_LEN`
.. only:: SOC_LP_GPIO_MATRIX_SUPPORTED
4. LP UART 控制器的 GPIO 引脚只能从 LP GPIO 引脚中选择。
.. only:: not SOC_LP_GPIO_MATRIX_SUPPORTED
4. 由于该芯片没有 LP GPIO 交换矩阵LP UART 控制器的 GPIO 引脚不可改变。具体的引脚号请查看 **{IDF_TARGET_NAME} 技术参考手册** > **IO MUX 和 GPIO 交换矩阵 (GPIO, IO MUX)** > **LP IO MUX 管脚功能列表** [`PDF <{IDF_TARGET_TRM_CN_URL}#lp-io-mux-func-list>`__]。
.. _uart-api-deleting-driver:
删除驱动程序
@ -273,6 +251,29 @@ API 还定义了一些宏指令。例如,:c:macro:`UART_HW_FIFO_LEN` 定义了
如不再需要与 :cpp:func:`uart_driver_install` 建立通信,则可调用 :cpp:func:`uart_driver_delete` 删除驱动程序,释放已分配的资源。
宏指令
^^^^^^^^^^^^
API 还定义了一些宏指令。例如,:c:macro:`UART_HW_FIFO_LEN` 定义了硬件 FIFO 缓冲区的长度,:c:macro:`UART_BITRATE_MAX` 定义了 UART 控制器支持的最大波特率。
.. only:: SOC_UART_HAS_LP_UART
.. _uart-api-lp-uart-driver:
使用主核驱动 LP UART 控制器
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
UART 驱动程序还适配了在 Active 模式下对 LP UART 控制器的驱动。LP UART 的配置流程和普通 UART 没有本质上的差别,除了有以下几点需要注意:
.. list::
- LP UART 控制器的端口号为 :c:macro:`LP_UART_NUM_0`
- LP UART 控制器的可选时钟源可以在 :cpp:type:`lp_uart_sclk_t` 中找到。
- LP UART 控制器的硬件 FIFO 大小要远小于普通 UART 控制器的硬件 FIFO 大小,其值为 :c:macro:`SOC_LP_UART_FIFO_LEN`
:SOC_LP_GPIO_MATRIX_SUPPORTED: - LP UART 控制器的 GPIO 引脚只能从 LP GPIO 引脚中选择。
:not SOC_LP_GPIO_MATRIX_SUPPORTED: - 由于该芯片没有 LP GPIO 交换矩阵LP UART 控制器的 GPIO 引脚不可改变。具体的引脚号请查看 **{IDF_TARGET_NAME} 技术参考手册** > **IO MUX 和 GPIO 交换矩阵 (GPIO, IO MUX)** > **LP IO MUX 管脚功能列表** [`PDF <{IDF_TARGET_TRM_CN_URL}#lp-io-mux-func-list>`__]。
RS485 特定通信模式简介
----------------------------------------------