From 2f2df82bc5d622f4e9ad1d3c93db8284bfc06657 Mon Sep 17 00:00:00 2001 From: Darian Leung Date: Sat, 19 Feb 2022 01:27:59 +0800 Subject: [PATCH] twai: Enable ESP32 errata workarounds by default --- components/driver/Kconfig | 8 ++--- docs/en/api-reference/peripherals/twai.rst | 38 ++++++++++------------ 2 files changed, 21 insertions(+), 25 deletions(-) diff --git a/components/driver/Kconfig b/components/driver/Kconfig index f25bc53978..ba7fc12f65 100644 --- a/components/driver/Kconfig +++ b/components/driver/Kconfig @@ -105,7 +105,7 @@ menu "Driver configurations" config TWAI_ERRATA_FIX_BUS_OFF_REC bool "Add SW workaround for REC change during bus-off" depends on IDF_TARGET_ESP32 - default n + default y help When the bus-off condition is reached, the REC should be reset to 0 and frozen (via LOM) by the driver's ISR. However on the ESP32, there is an edge case where the REC will increase before the @@ -117,7 +117,7 @@ menu "Driver configurations" config TWAI_ERRATA_FIX_TX_INTR_LOST bool "Add SW workaround for TX interrupt lost errata" depends on IDF_TARGET_ESP32 - default n + default y help On the ESP32, when a transmit interrupt occurs, and interrupt register is read on the same APB clock cycle, the transmit interrupt could be lost. Enabling this option will add a workaround that checks the @@ -126,7 +126,7 @@ menu "Driver configurations" config TWAI_ERRATA_FIX_RX_FRAME_INVALID bool "Add SW workaround for invalid RX frame errata" depends on IDF_TARGET_ESP32 - default n + default y help On the ESP32, when receiving a data or remote frame, if a bus error occurs in the data or CRC field, the data of the next received frame could be invalid. Enabling this option will add a workaround that @@ -137,7 +137,7 @@ menu "Driver configurations" config TWAI_ERRATA_FIX_RX_FIFO_CORRUPT bool "Add SW workaround for RX FIFO corruption errata" depends on IDF_TARGET_ESP32 - default n + default y help On the ESP32, when the RX FIFO overruns and the RX message counter maxes out at 64 messages, the entire RX FIFO is no longer recoverable. Enabling this option will add a workaround that resets the peripheral diff --git a/docs/en/api-reference/peripherals/twai.rst b/docs/en/api-reference/peripherals/twai.rst index fb221b5c90..2667b27058 100644 --- a/docs/en/api-reference/peripherals/twai.rst +++ b/docs/en/api-reference/peripherals/twai.rst @@ -13,21 +13,11 @@ The Two-Wire Automotive Interface (TWAI) is a real-time serial communication pro This programming guide is split into the following sections: - 1. :ref:`twai-protocol-summary` - - 2. :ref:`signals-lines-and-transceiver` - - 3. :ref:`configuration` - - 4. :ref:`driver-operation` - - 5. :ref:`examples` - +.. contents:: Sections + :depth: 2 .. --------------------------- Basic TWAI Concepts ----------------------------- -.. _twai-protocol-summary: - TWAI Protocol Summary --------------------- @@ -63,11 +53,8 @@ The TWAI protocol implements a feature known as "fault confinement" where a pers **Bus-Off:** A node becomes Bus-Off when the **TEC becomes greater than or equal to 256**. A Bus-Off node is unable influence the bus in any manner (essentially disconnected from the bus) thus eliminating itself from the bus. A node will remain in the Bus-Off state until it undergoes bus-off recovery. - .. ---------------------- Signal Lines and Transceiver ------------------------- -.. _signals-lines-and-transceiver: - Signals Lines and Transceiver ----------------------------- @@ -91,8 +78,6 @@ The TWAI controller's interface consists of 4 signal lines known as **TX, RX, BU .. ------------------------------ Configuration -------------------------------- -.. _configuration: - Driver Configuration -------------------- @@ -267,9 +252,22 @@ To place the TWAI driver's ISR, users must do the following: .. note:: When the :ref:`CONFIG_TWAI_ISR_IN_IRAM` option is enabled, the TWAI driver will no longer log any alerts (i.e., the ``TWAI_ALERT_AND_LOG`` flag will not have any effect). -.. ------------------------------- TWAI Driver --------------------------------- +.. only:: esp32 -.. _driver-operation: + ESP32 Errata Workarounds + ^^^^^^^^^^^^^^^^^^^^^^^^ + + The ESP32's TWAI controller contains multiple hardware errata (more details about the errata can be found in the `ESP32's ECO document `_). Some of these errata are critical, and under specific circumstances, can place the TWAI controller into an unrecoverable state (i.e., the controller gets stuck until it is reset by the CPU). + + The TWAI driver contains software workarounds for these critical errata. With these workarounds, the ESP32 TWAI driver can operate normally, albeit with degraded performance. The degraded performance will affect users in the following ways depending on what particular errata conditions are encountered: + + - The TWAI driver can occasionally drop some received messages. + - The TWAI driver can be unresponsive for a short period of time (i.e., will not transmit or ACK for 11 bit times or longer). + - If :ref:`CONFIG_TWAI_ISR_IN_IRAM` is enabled, the workarounds will increase IRAM usage by approximately 1KB. + + The software workarounds are enabled by default and it is recommended that users keep this workarounds enabled. + +.. ------------------------------- TWAI Driver --------------------------------- Driver Operation ---------------- @@ -354,8 +352,6 @@ These bit field members can also be toggled using the the `flags` member of :cpp .. -------------------------------- Examples ----------------------------------- -.. _examples: - Examples --------