Merge branch 'fix/improve_spi_and_twai_docs' into 'master'

fix(driver_twai): improve new driver API description

Closes IDFGH-16806

See merge request espressif/esp-idf!43922

components/esp_driver_twai/include/esp_twai_types.h

@@ -42,7 +42,7 @@ typedef struct {
     twai_error_state_t state;       /**< Node's error state */
     uint16_t tx_error_count;        /**< Node's TX error count */
     uint16_t rx_error_count;        /**< Node's RX error count */
-    uint32_t tx_queue_remaining;    /**< Node's TX free queue space */
+    uint32_t tx_queue_remaining;    /**< Node's TX queue remaining frame space (number of frames) */
 } twai_node_status_t;
 
 /**

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

@@ -498,7 +498,7 @@ GPIO Matrix and IO_MUX
 
     Most of the chip's peripheral signals have a direct connection to their dedicated IO_MUX pins. However, the signals can also be routed to any other available pins using the less direct GPIO matrix. If at least one signal is routed through the GPIO matrix, then all signals will be routed through it.
 
-    When an SPI Host is set to 80 MHz or lower frequencies, routing SPI pins via the GPIO matrix will behave the same compared to routing them via IOMUX.
+    When an SPI Host is set to 40 MHz or lower frequencies, routing SPI pins via the GPIO matrix will behave the same compared to routing them via IOMUX.
 
     The IO_MUX pins for SPI buses are given below.
 

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

@@ -103,7 +103,12 @@ TWAI messages come in various types, which are specified by their headers. A typ
 .. image:: ../../../_static/diagrams/twai/frame_struct.svg
     :align: center
 
-To reduce performance overhead caused by memory copying, the TWAI driver uses pointers to pass messages. The following code demonstrates how to transmit a typical data frame:
+To reduce performance overhead caused by memory copying, the TWAI driver uses pointers to pass messages. The driver is designed to operate in asynchronous mode, so the :cpp:type:`twai_frame_t` structure and the memory pointed to by :cpp:member:`twai_frame_t::buffer` must remain valid until the transmission is actually complete. You can determine when transmission is complete in the following ways:
+
+- Call the :cpp:func:`twai_node_transmit_wait_all_done` function to wait for all transmissions to complete.
+- Register the :cpp:member:`twai_event_callbacks_t::on_tx_done` event callback function to receive a notification when transmission is complete.
+
+The following code demonstrates how to transmit a typical data frame:
 
 .. code:: c
 
@@ -200,7 +205,7 @@ The TWAI driver supports transmitting messages from an Interrupt Service Routine
     }
 
 .. note::
-    When calling :cpp:func:`twai_node_transmit` from an ISR, the ``timeout`` parameter is ignored, and the function will not block. If the transmit queue is full, the function will return immediately with an error. It is the application's responsibility to handle cases where the queue is full.
+    When calling :cpp:func:`twai_node_transmit` from an ISR, the ``timeout`` parameter is ignored, and the function will not block. If the transmit queue is full, the function will return immediately with an error. It is the application's responsibility to handle cases where the queue is full. Similarly, the ``twai_frame_t`` structure and the memory pointed to by ``buffer`` must remain valid until the transmission is complete. You can get the completed frame by the :cpp:member:`twai_tx_done_event_data_t::done_tx_frame` pointer.
 
 Bit Timing Customization
 ------------------------

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

@@ -498,7 +498,7 @@ GPIO 矩阵与 IO_MUX 管脚
 
     芯片的大多数外围信号都与之专用的 IO_MUX 管脚连接，但这些信号也可以通过较不直接的 GPIO 矩阵路由到任何其他可用的管脚。只要有一个信号是通过 GPIO 矩阵路由的，那么所有的信号都将通过它路由。
 
-    当 SPI 主机被设置为 80 MHz 或更低的频率时，通过 GPIO 矩阵路由 SPI 管脚的行为将与通过 IOMUX 路由相同。
+    当 SPI 主机被设置为 40 MHz 或更低的频率时，通过 GPIO 矩阵路由 SPI 管脚的行为将与通过 IOMUX 路由相同。
 
     SPI 总线的 IO_MUX 管脚如下表所示。
 

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

@@ -103,7 +103,12 @@ TWAI 报文有多种类型，由报头指定。一个典型的数据帧报文主
 .. image:: ../../../_static/diagrams/twai/frame_struct.svg
     :align: center
 
-为减少拷贝带来的性能损失，TWAI 驱动使用指针进行传递。以下代码展示了如何发送一条典型的数据帧报文：
+为减少拷贝带来的性能损失，TWAI 驱动使用指针进行传递。且驱动设计为异步模式，因此，在传输真正完成之前， :cpp:type:`twai_frame_t` 实体及其 :cpp:member:`twai_frame_t::buffer` 指向的内存必须保持有效。可通过以下方式得知传输完成：
+
+- 调用 :cpp:func:`twai_node_transmit_wait_all_done` 函数等待所有传输完成。
+- 注册 :cpp:member:`twai_event_callbacks_t::on_tx_done` 事件回调函数，在传输完成时接收通知。
+
+以下代码展示了如何发送一条典型的数据帧报文：
 
 .. code:: c
 
@@ -200,7 +205,7 @@ TWAI 驱动支持在中断服务程序 (ISR) 中发送报文。这对于需要
     }
 
 .. note::
-    在 ISR 中调用 :cpp:func:`twai_node_transmit` 时，``timeout`` 参数将被忽略，函数不会阻塞。如果发送队列已满，函数将立即返回错误。应用程序需要自行处理队列已满的情况。
+    在 ISR 中调用 :cpp:func:`twai_node_transmit` 时，``timeout`` 参数将被忽略，函数不会阻塞。如果发送队列已满，函数将立即返回错误。应用程序需要自行处理队列已满的情况。同样，``twai_frame_t`` 及其 ``buffer`` 指向的内存必须在 **该传输** 完成之前保持有效。通过 :cpp:member:`twai_tx_done_event_data_t::done_tx_frame` 指针可得知该次完成的报文。
 
 位时序自定义
 -------------