fix(driver_twai): added errata warning for c5 listen only mode

Author: wanckl

components/esp_driver_twai/esp_twai_onchip.c

@@ -6,7 +6,6 @@
 
 #include "esp_twai.h"
 #include "esp_twai_onchip.h"
-#include "soc/gpio_sig_map.h"
 #include "esp_private/twai_interface.h"
 #include "esp_private/twai_utils.h"
 #include "twai_private.h"
@@ -125,17 +124,14 @@ static esp_err_t _node_config_io(twai_onchip_ctx_t *node, const twai_onchip_node
 {
     ESP_RETURN_ON_FALSE(GPIO_IS_VALID_OUTPUT_GPIO(node_config->io_cfg.tx), ESP_ERR_INVALID_ARG, TAG, "Invalid tx gpio num");
     ESP_RETURN_ON_FALSE(GPIO_IS_VALID_GPIO(node_config->io_cfg.rx), ESP_ERR_INVALID_ARG, TAG, "Invalid rx gpio num");
-    uint64_t reserve_mask = BIT64(node_config->io_cfg.tx);
 
     // Set RX pin
     gpio_set_pull_mode(node_config->io_cfg.rx, GPIO_PULLUP_ONLY);    // pullup to avoid noise if no connection to transceiver
     gpio_matrix_input(node_config->io_cfg.rx, twai_periph_signals[node->ctrlr_id].rx_sig, false);
 
     // Set TX pin
-    // If enable_listen_only, disconnect twai signal, and output high to avoid any influence to bus
-    gpio_set_level(node_config->io_cfg.tx, 1);
-    int tx_sig = (node_config->flags.enable_listen_only) ? SIG_GPIO_OUT_IDX : twai_periph_signals[node->ctrlr_id].tx_sig;
-    gpio_matrix_output(node_config->io_cfg.tx, tx_sig, false, false);
+    uint64_t reserve_mask = BIT64(node_config->io_cfg.tx);
+    gpio_matrix_output(node_config->io_cfg.tx, twai_periph_signals[node->ctrlr_id].tx_sig, false, false);
 
     //Configure output clock pin (Optional)
     if (GPIO_IS_VALID_OUTPUT_GPIO(node_config->io_cfg.quanta_clk_out)) {
@@ -519,7 +515,7 @@ static esp_err_t _node_config_mask_filter(twai_node_handle_t node, uint8_t filte
     // FD targets don't support Dual filter
     ESP_RETURN_ON_FALSE(!mask_cfg->dual_filter, ESP_ERR_NOT_SUPPORTED, TAG, "The target don't support Dual Filter");
 #endif
-    ESP_RETURN_ON_FALSE(atomic_load(&twai_ctx->state) == TWAI_ERROR_BUS_OFF, ESP_ERR_INVALID_STATE, TAG, "config filter must when node stopped");
+    ESP_RETURN_ON_FALSE(atomic_load(&twai_ctx->state) == TWAI_ERROR_BUS_OFF, ESP_ERR_INVALID_STATE, TAG, "filter config must do when node stopped");
 
     twai_hal_configure_filter(twai_ctx->hal, filter_id, mask_cfg);
     return ESP_OK;
@@ -532,7 +528,7 @@ static esp_err_t _node_config_range_filter(twai_node_handle_t node, uint8_t filt
     ESP_RETURN_ON_FALSE(filter_id < SOC_TWAI_RANGE_FILTER_NUM, ESP_ERR_INVALID_ARG, TAG, "Invalid range filter id %d", filter_id);
     ESP_RETURN_ON_FALSE((range_cfg->range_low > range_cfg->range_high) || range_cfg->is_ext || !(range_cfg->range_high & ~TWAI_STD_ID_MASK), \
                         ESP_ERR_INVALID_ARG, TAG, "std_id only (is_ext=0) but valid low/high id larger than 11 bits");
-    ESP_RETURN_ON_FALSE(atomic_load(&twai_ctx->state) == TWAI_ERROR_BUS_OFF, ESP_ERR_INVALID_STATE, TAG, "config filter must when node stopped");
+    ESP_RETURN_ON_FALSE(atomic_load(&twai_ctx->state) == TWAI_ERROR_BUS_OFF, ESP_ERR_INVALID_STATE, TAG, "filter config must do when node stopped");
 
     twai_hal_configure_range_filter(twai_ctx->hal, filter_id, range_cfg);
     return ESP_OK;
@@ -651,6 +647,13 @@ esp_err_t twai_new_node_onchip(const twai_onchip_node_config_t *node_config, twa
         .enable_self_test = node_config->flags.enable_self_test,
         .enable_loopback = node_config->flags.enable_loopback,
     };
+#if CONFIG_IDF_TARGET_ESP32C5
+    // ESP32C5 has a bug that the listen only mode don't work when there are other nodes sending ACK each other
+    // See IDF-13059 for more details
+    if (node_config->flags.enable_listen_only) {
+        ESP_LOGW(TAG, "Listen only mode for ESP32C5 may not work properly when there are more than 2 nodes on the bus that are sending ACKs to each other");
+    }
+#endif
     ESP_GOTO_ON_FALSE(twai_hal_init(node->hal, &hal_config), ESP_ERR_INVALID_STATE, err, TAG, "hardware not in reset state");
     // Configure bus timing
     ESP_GOTO_ON_ERROR(_node_calc_set_bit_timing(&node->api_base, node_config->clk_src, &node_config->bit_timing, &node_config->data_timing), err, TAG, "bitrate error");

components/hal/esp32c5/include/hal/twaifd_ll.h

@@ -165,7 +165,7 @@ static inline void twaifd_ll_set_mode(twaifd_dev_t *hw, bool listen_only, bool s
 
     twaifd_mode_settings_reg_t opmode = {.val = hw->mode_settings.val};
     opmode.stm = self_test;
-    (void)listen_only; // listen only is not available in this chip, see "CTU FD 2v5 errata 0v2 issue 5"
+    opmode.bmm = listen_only;
     opmode.ilbp = loopback;
 
     hw->mode_settings.val = opmode.val;

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

@@ -90,6 +90,12 @@ Below are additional configuration fields of the :cpp:type:`twai_onchip_node_con
     - :cpp:member:`twai_onchip_node_config_t::flags::enable_listen_only`: Configures the node in listen-only mode. In this mode, the node only receives and does not transmit any dominant bits, including ACK and error frames.
     - :cpp:member:`twai_onchip_node_config_t::flags::no_receive_rtr`: When using filters, determines whether remote frames matching the ID pattern should be filtered out.
 
+.. only:: esp32c5
+
+    .. note::
+
+        Note: The listen-only mode on ESP32C5 can't work properly when there are multiple nodes on the bus that are sending ACKs to each other. An alternative is to use transceiver which supports listen-only mode itself (e.g. TJA1145), and combine it with self-test mode enabled.
+
 The :cpp:func:`twai_node_enable` function starts the TWAI controller. Once enabled, the controller is connected to the bus and can transmit messages. It also generates events upon receiving messages from other nodes on the bus or when bus errors are detected.
 
 The corresponding function, :cpp:func:`twai_node_disable`, immediately stops the node and disconnects it from the bus. Any ongoing transmissions will be aborted. When the node is re-enabled later, if there are pending transmissions in the queue, the driver will immediately initiate a new transmission attempt.
@@ -202,7 +208,7 @@ The following code demonstrates how to configure a baud rate of 500 Kbit/s with
 .. code:: c
 
     twai_timing_advanced_config_t timing_cfg = {
-        .brp = 8,       // Prescaler set to 8, time quantum = 80M / 8 = 10 MHz (1M Tq)
+        .brp = 8,       // Prescaler set to 8, time quantum = 80M / 8 = 10 MHz (10M Tq)
         .prop_seg = 10, // Propagation segment
         .tseg_1 = 4,    // Phase segment 1
         .tseg_2 = 5,    // Phase segment 2
@@ -254,7 +260,7 @@ The following code demonstrates how to calculate the MASK and configure a filter
     Dual Filter Mode
     """"""""""""""""
 
-    {IDF_TARGET_NAME} supports dual filter mode, which allows the hardware to be configured as two parallel independent 16-bit mask filters. By enabling this, more IDs can be received. Note that when filtering 29-bit extended IDs, each filter can only filter the upper 16 bits of the ID, while the remaining 13 bits are not filtered. The following code demonstrates how to configure dual filter mode using the function :cpp:func:`twai_make_dual_filter`:
+    {IDF_TARGET_NAME} supports dual filter mode, which allows the hardware to be configured as two parallel independent 16-bit mask filters. By enabling this, more IDs can be received. Note that using dual filter mode to filter 29-bit extended IDs, each filter can only filter the upper 16 bits of the ID, while the remaining 13 bits are not filtered. The following code demonstrates how to configure dual filter mode using the function :cpp:func:`twai_make_dual_filter`:
 
     .. code:: c
 

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

@@ -90,6 +90,12 @@ TWAI 是一种适用于汽车和工业应用的高可靠性的多主机实时串
     - :cpp:member:`twai_onchip_node_config_t::flags::enable_listen_only` 配置为监听模式，节点只接收，不发送任何显性位，包括 ACK 和错误帧。
     - :cpp:member:`twai_onchip_node_config_t::flags::no_receive_rtr` 使用过滤器时是否同时过滤掉符合 ID 规则的远程帧。
 
+.. only:: esp32c5
+
+    .. note::
+
+        注意： ESP32C5 的监听模式在总线上有多个节点相互发送 ACK 信号时无法正常工作。一种替代方案是使用本身支持监听模式的收发器（例如 TJA1145），并结合启用自测模式。
+
 函数 :cpp:func:`twai_node_enable` 将启动 TWAI 控制器，此时 TWAI 控制器就连接到了总线，可以向总线发送报文。如果收到了总线上其他节点发送的报文，或者检测到了总线错误，也将产生相应事件。
 
 与之对应的函数是 :cpp:func:`twai_node_disable`，该函数将立即停止节点工作并与总线断开，正在进行的传输将被中止。当下次重新启动时，如果发送队列中有未完成的任务，驱动将立即发起新的传输。
@@ -202,7 +208,7 @@ TWAI 报文有多种类型，由报头指定。一个典型的数据帧报文主
 .. code:: c
 
     twai_timing_advanced_config_t timing_cfg = {
-        .brp = 8,  // 预分频为 8，时间量子 80M/8=1M
+        .brp = 8,  // 预分频为 8，时间量子 80M/8=10M
         .prop_seg = 10,
         .tseg_1 = 4,
         .tseg_2 = 5,
@@ -227,7 +233,7 @@ TWAI 报文有多种类型，由报头指定。一个典型的数据帧报文主
 
 TWAI 控制器硬件可以根据 ID 对报文进行过滤，从而减少软硬件开销使节点更加高效。过滤掉报文的节点 **不会接收到该报文，但仍会应答**。
 
-{IDF_TARGET_NAME} 包含 {IDF_TARGET_CONFIG_SOC_TWAI_MASK_FILTER_NUM} 个掩码过滤器，报文通过任意一个过滤器即能收到改报文。典型的 TWAI 掩码过滤器通过 ID 和 MASK 配置，其中：
+{IDF_TARGET_NAME} 包含 {IDF_TARGET_CONFIG_SOC_TWAI_MASK_FILTER_NUM} 个掩码过滤器，报文通过任意一个过滤器即能收到该报文。典型的 TWAI 掩码过滤器通过 ID 和 MASK 配置，其中：
 
 - ID 表示期望接收的报文的标准11位或扩展29位ID。
 - MASK 表示对ID的过滤规则：
@@ -254,7 +260,7 @@ TWAI 控制器硬件可以根据 ID 对报文进行过滤，从而减少软硬
     双过滤器模式
     """"""""""""
 
-    {IDF_TARGET_NAME} 支持双过滤器模式，可将硬件配置为并列的两个独立的 16 位掩码过滤器，支持接收更多 ID，但当配置为过滤 29 位扩展ID时，每个过滤器只能过滤其ID的高 16 位，剩余13位不做过滤。以下代码展示了如何借助 :cpp:func:`twai_make_dual_filter` 配置双过滤器模式。
+    {IDF_TARGET_NAME} 支持双过滤器模式，可将硬件配置为并列的两个独立的 16 位掩码过滤器，支持接收更多 ID。但注意，使用双过滤器模式过滤 29 位扩展ID时，每个过滤器只能过滤其ID的高 16 位，剩余13位不做过滤。以下代码展示了如何借助 :cpp:func:`twai_make_dual_filter` 配置双过滤器模式。
 
     .. code:: c