Merge branch 'docs/update_description_uart_interrupt' into 'master'

docs: update the description of UART interrupt

See merge request espressif/esp-idf!30118

Author: Lindazhxy

docs/en/api-reference/peripherals/uart.rst

@@ -1,6 +1,8 @@
 Universal Asynchronous Receiver/Transmitter (UART)
 ==================================================
 
+:link_to_translation:`zh_CN:[中文]`
+
 {IDF_TARGET_UART_EXAMPLE_PORT:default = "UART_NUM_1", esp32 = "UART_NUM_2", esp32s3 = "UART_NUM_2"}
 
 Introduction
@@ -114,11 +116,15 @@ Install Drivers
 
 Once the communication pins are set, install the driver by calling :cpp:func:`uart_driver_install` and specify the following parameters:
 
+- UART port number
 - Size of TX ring buffer
 - Size of RX ring buffer
-- Event queue handle and size
+- Pointer to store the event queue handle
+- Event queue size
 - Flags to allocate an interrupt
 
+.. _driver-code-snippet:
+
 The function allocates the required internal resources for the UART driver.
 
 .. code-block:: c
@@ -225,23 +231,45 @@ Use Interrupts
 
 There are many interrupts that can be generated depending on specific UART states or detected errors. The full list of available interrupts is provided in *{IDF_TARGET_NAME} Technical Reference Manual* > *UART Controller (UART)* > *UART Interrupts* and *UHCI Interrupts* [`PDF <{IDF_TARGET_TRM_EN_URL}#uart>`__]. You can enable or disable specific interrupts by calling :cpp:func:`uart_enable_intr_mask` or :cpp:func:`uart_disable_intr_mask` respectively.
 
-The :cpp:func:`uart_driver_install` function installs the driver's internal interrupt handler to manage the TX and RX ring buffers and provides high-level API functions like events (see below).
+The UART driver provides a convenient way to handle specific interrupts by wrapping them into corresponding events. Events defined in :cpp:type:`uart_event_type_t` can be reported to a user application using the FreeRTOS queue functionality.
+
+To receive the events that have happened, call :cpp:func:`uart_driver_install` and get the event queue handle returned from the function. Please see the above :ref:`code snippet <driver-code-snippet>` as an example.
+
+The processed events include the following:
 
-The API provides a convenient way to handle specific interrupts discussed in this document by wrapping them into dedicated functions:
+- **FIFO overflow** (:cpp:enumerator:`UART_FIFO_OVF`): The RX FIFO can trigger an interrupt when it receives more data than the FIFO can store.
 
-- **Event detection**: There are several events defined in :cpp:type:`uart_event_type_t` that may be reported to a user application using the FreeRTOS queue functionality. You can enable this functionality when calling :cpp:func:`uart_driver_install` described in :ref:`uart-api-driver-installation`. An example of using Event detection can be found in :example:`peripherals/uart/uart_events`.
+    - (Optional) Configure the full threshold of the FIFO space by entering it in the structure :cpp:type:`uart_intr_config_t` and call :cpp:func:`uart_intr_config` to set the configuration. This can help the data stored in the RX FIFO can be processed timely in the driver to avoid FIFO overflow.
+    - Enable the interrupts using the functions :cpp:func:`uart_enable_rx_intr`.
+    - Disable these interrupts using the corresponding functions :cpp:func:`uart_disable_rx_intr`.
 
-- **FIFO space threshold or transmission timeout reached**: The TX and RX FIFO buffers can trigger an interrupt when they are filled with a specific number of characters, or on a timeout of sending or receiving data. To use these interrupts, do the following:
+  .. code-block:: c
 
-    - Configure respective threshold values of the buffer length and timeout by entering them in the structure :cpp:type:`uart_intr_config_t` and calling :cpp:func:`uart_intr_config`
-    - Enable the interrupts using the functions :cpp:func:`uart_enable_tx_intr` and :cpp:func:`uart_enable_rx_intr`
-    - Disable these interrupts using the corresponding functions :cpp:func:`uart_disable_tx_intr` or :cpp:func:`uart_disable_rx_intr`
+      const uart_port_t uart_num = {IDF_TARGET_UART_EXAMPLE_PORT};
+      // Configure a UART interrupt threshold and timeout
+      uart_intr_config_t uart_intr = {
+          .intr_enable_mask = UART_INTR_RXFIFO_FULL | UART_INTR_RXFIFO_TOUT,
+          .rxfifo_full_thresh = 100,
+          .rx_timeout_thresh = 10,
+      };
+      ESP_ERROR_CHECK(uart_intr_config(uart_num, &uart_intr));
 
-- **Pattern detection**: An interrupt triggered on detecting a 'pattern' of the same character being received/sent repeatedly. This functionality is demonstrated in the example :example:`peripherals/uart/uart_events`. It can be used, e.g., to detect a command string with a specific number of identical characters (the 'pattern') at the end. The following functions are available:
+      // Enable UART RX FIFO full threshold and timeout interrupts
+      ESP_ERROR_CHECK(uart_enable_rx_intr(uart_num));
+
+- **Pattern detection** (:cpp:enumerator:`UART_PATTERN_DET`): An interrupt triggered on detecting a 'pattern' of the same character being received/sent repeatedly. It can be used, e.g., to detect a command string with a specific number of identical characters (the 'pattern') at the end. The following functions are available:
 
     - Configure and enable this interrupt using :cpp:func:`uart_enable_pattern_det_baud_intr`
     - Disable the interrupt using :cpp:func:`uart_disable_pattern_det_intr`
 
+  .. code-block:: c
+
+      //Set UART pattern detect function
+      uart_enable_pattern_det_baud_intr(EX_UART_NUM, '+', PATTERN_CHR_NUM, 9, 0, 0);
+
+- **Other events**: The UART driver can report other events such as data receiving (:cpp:enumerator:`UART_DATA`), ring buffer full (:cpp:enumerator:`UART_BUFFER_FULL`), detecting NULL after the stop bit (:cpp:enumerator:`UART_BREAK`), parity check error (:cpp:enumerator:`UART_PARITY_ERR`), and frame error (:cpp:enumerator:`UART_FRAME_ERR`).
+
+The strings inside of brackets indicate corresponding event names. An example of how to handle various UART events can be found in :example:`peripherals/uart/uart_events`.
 
 .. _uart-api-deleting-driver:
 

docs/zh_CN/api-reference/peripherals/uart.rst

@@ -1,6 +1,8 @@
 通用异步接收器/发送器 (UART)
 ==================================================
 
+:link_to_translation:`en:[English]`
+
 {IDF_TARGET_UART_EXAMPLE_PORT:default = "UART_NUM_1", esp32 = "UART_NUM_2", esp32s3 = "UART_NUM_2"}
 
 简介
@@ -114,11 +116,15 @@ UART 通信参数可以在一个步骤中完成全部配置，也可以在多个
 
 通信管脚设置完成后，请调用 :cpp:func:`uart_driver_install` 安装驱动程序并指定以下参数：
 
+- UART 控制器编号
 - Tx 环形缓冲区的大小
 - Rx 环形缓冲区的大小
-- 事件队列句柄和大小
+- 指向事件队列句柄的指针
+- 事件队列大小
 - 分配中断的标志
 
+.. _driver-code-snippet:
+
 该函数将为 UART 驱动程序分配所需的内部资源。
 
 .. code-block:: c
@@ -225,23 +231,45 @@ UART 控制器支持多种通信模式，使用函数 :cpp:func:`uart_set_mode`
 
 根据特定的 UART 状态或检测到的错误，可以生成许多不同的中断。**{IDF_TARGET_NAME} 技术参考手册** > UART 控制器 (UART) > UART 中断 和 UHCI 中断 [`PDF <{IDF_TARGET_TRM_EN_URL}#uart>`__] 中提供了可用中断的完整列表。调用 :cpp:func:`uart_enable_intr_mask` 或 :cpp:func:`uart_disable_intr_mask` 能够分别启用或禁用特定中断。
 
-调用 :cpp:func:`uart_driver_install` 函数可以安装驱动程序的内部中断处理程序，用以管理 Tx 和 Rx 环形缓冲区，并提供事件等高级 API 函数（见下文）。
+UART 驱动提供了一种便利的方法来处理特定的中断，即将中断包装成相应的事件。这些事件定义在 :cpp:type:`uart_event_type_t` 中，FreeRTOS 队列功能可将这些事件报告给用户应用程序。
+
+要接收已发生的事件，请调用 :cpp:func:`uart_driver_install` 函数并获取返回的事件队列句柄，可参考上述 :ref:`示例代码 <driver-code-snippet>`。
+
+UART 驱动可处理的事件包括：
 
-API 提供了一种便利的方法来处理本文所讨论的特定中断，即用专用函数包装中断：
+- **FIFO 空间溢出** (:cpp:enumerator:`UART_FIFO_OVF`)：当接收到的数据超过 FIFO 的存储能力时，Rx FIFO 会触发中断。
 
-- **事件检测**：:cpp:type:`uart_event_type_t` 定义了多个事件，使用 FreeRTOS 队列功能能够将其报告给用户应用程序。调用 :ref:`uart-api-driver-installation` 中的 :cpp:func:`uart_driver_install` 函数，可以启用此功能，请参考 :example:`peripherals/uart/uart_events` 中使用事件检测的示例。
+    - （可选）配置 FIFO 阈值：在结构体 :cpp:type:`uart_intr_config_t` 中输入阈值，然后调用 :cpp:func:`uart_intr_config` 使能配置。这有助于驱动及时处理 RX FIFO 中的数据，避免 FIFO 溢出。
+    - 启用中断：调用函数 :cpp:func:`uart_enable_rx_intr`
+    - 禁用中断：调用函数 :cpp:func:`uart_disable_rx_intr`
 
-- **达到 FIFO 空间阈值或传输超时**：Tx 和 Rx FIFO 缓冲区在填充特定数量的字符和在发送或接收数据超时的情况下将会触发中断。如要使用此类中断，请执行以下操作：
+  .. code-block:: c
 
-    - 配置缓冲区长度和超时阈值：在结构体 :cpp:type:`uart_intr_config_t` 中输入相应阈值并调用 :cpp:func:`uart_intr_config`
-    - 启用中断：调用函数 :cpp:func:`uart_enable_tx_intr` 和 :cpp:func:`uart_enable_rx_intr`
-    - 禁用中断：调用函数 :cpp:func:`uart_disable_tx_intr` 或 :cpp:func:`uart_disable_rx_intr`
+      const uart_port_t uart_num = {IDF_TARGET_UART_EXAMPLE_PORT};
+      // Configure a UART interrupt threshold and timeout
+      uart_intr_config_t uart_intr = {
+          .intr_enable_mask = UART_INTR_RXFIFO_FULL | UART_INTR_RXFIFO_TOUT,
+          .rxfifo_full_thresh = 100,
+          .rx_timeout_thresh = 10,
+      };
+      ESP_ERROR_CHECK(uart_intr_config(uart_num, &uart_intr));
 
-- **模式检测**：在检测到重复接收/发送同一字符的“模式”时触发中断，请参考示例 :example:`peripherals/uart/uart_events`。例如，模式检测可用于检测命令字符串末尾是否存在特定数量的相同字符（“模式”）。可以调用以下函数：
+      // Enable UART RX FIFO full threshold and timeout interrupts
+      ESP_ERROR_CHECK(uart_enable_rx_intr(uart_num));
+
+- **模式检测** (:cpp:enumerator:`UART_PATTERN_DET`)：在检测到重复接收/发送同一字符的“模式”时触发中断，例如，模式检测可用于检测命令字符串末尾是否存在特定数量的相同字符（“模式”）。可以调用以下函数：
 
     - 配置并启用此中断：调用 :cpp:func:`uart_enable_pattern_det_baud_intr`
     - 禁用中断：调用 :cpp:func:`uart_disable_pattern_det_intr`
 
+  .. code-block:: c
+
+      //Set UART pattern detect function
+      uart_enable_pattern_det_baud_intr(EX_UART_NUM, '+', PATTERN_CHR_NUM, 9, 0, 0);
+
+- **其他事件**：UART 驱动可处理的其他事件包括数据接收 (:cpp:enumerator:`UART_DATA`)、环形缓冲区已满 (:cpp:enumerator:`UART_BUFFER_FULL`)、在停止位后检测到 NULL (:cpp:enumerator:`UART_BREAK`)、奇偶校验错误 (:cpp:enumerator:`UART_PARITY_ERR`)、以及帧错误 (:cpp:enumerator:`UART_FRAME_ERR`)。
+
+括号中的字符串为相应的事件名称。请参考 :example:`peripherals/uart/uart_events` 中处理 UART 事件的示例。
 
 .. _uart-api-deleting-driver: