Merge branch 'feat/twai_driver_add_programming_guide' into 'master'

feat(driver_twai): new driver add programming guide

Closes IDF-9466

See merge request espressif/esp-idf!39013

Author: wanckl

components/driver/twai/twai.c

@@ -247,10 +247,13 @@ static void twai_intr_handler_main(void *arg)
 
     //Handle events that only require alerting (i.e. no handler)
     if (events & TWAI_HAL_EVENT_BUS_OFF) {
+        twai_ll_set_mode(p_twai_obj->hal->dev, true, false, false);  //Freeze TEC/REC by entering LOM
         p_twai_obj->state = TWAI_STATE_BUS_OFF;
         twai_alert_handler(p_twai_obj, TWAI_ALERT_BUS_OFF, &alert_req);
     }
     if (events & TWAI_HAL_EVENT_BUS_RECOV_CPLT) {
+        //Back to STOPPED state after recovered, for cautious engineering strategy
+        twai_ll_enter_reset_mode(p_twai_obj->hal->dev);
         p_twai_obj->state = TWAI_STATE_STOPPED;
         twai_alert_handler(p_twai_obj, TWAI_ALERT_BUS_RECOVERED, &alert_req);
     }

components/esp_driver_twai/esp_twai_onchip.c

@@ -234,6 +234,15 @@ static void _node_isr_main(void *arg)
         if (twai_ctx->cbs.on_state_change) {
             do_yield |= twai_ctx->cbs.on_state_change(&twai_ctx->api_base, &e_data, twai_ctx->user_data);
         }
+        // node recover from busoff, restart remain tx transaction
+        if ((e_data.old_sta == TWAI_ERROR_BUS_OFF) && (e_data.new_sta == TWAI_ERROR_ACTIVE)) {
+            if (xQueueReceiveFromISR(twai_ctx->tx_mount_queue, &twai_ctx->p_curr_tx, &do_yield)) {
+                atomic_store(&twai_ctx->hw_busy, true);
+                _node_start_trans(twai_ctx);
+            } else {
+                atomic_store(&twai_ctx->hw_busy, false);
+            }
+        }
     }
 
     // deal RX event, then TX later, TODO: DIG-620
@@ -263,9 +272,9 @@ static void _node_isr_main(void *arg)
 
     // deal TX event
     if (events & TWAI_HAL_EVENT_TX_BUFF_FREE) {
-        // only call tx_done_cb when tx without error, otherwise on_error_cb should triggered if it is registered
-        if (twai_ctx->cbs.on_tx_done && (events & TWAI_HAL_EVENT_TX_SUCCESS)) {
+        if (twai_ctx->cbs.on_tx_done) {
             twai_tx_done_event_data_t tx_ev = {
+                .is_tx_success = (events & TWAI_HAL_EVENT_TX_SUCCESS),  // find 'on_error_cb' if not success
                 .done_tx_frame = twai_ctx->p_curr_tx,
             };
             do_yield |= twai_ctx->cbs.on_tx_done(&twai_ctx->api_base, &tx_ev, twai_ctx->user_data);
@@ -484,6 +493,9 @@ static esp_err_t _node_config_mask_filter(twai_node_handle_t node, uint8_t filte
     twai_onchip_ctx_t *twai_ctx = __containerof(node, twai_onchip_ctx_t, api_base);
     ESP_RETURN_ON_FALSE(filter_id < SOC_TWAI_MASK_FILTER_NUM, ESP_ERR_INVALID_ARG, TAG, "Invalid mask filter id %d", filter_id);
     ESP_RETURN_ON_FALSE(mask_cfg->num_of_ids <= 1, ESP_ERR_INVALID_ARG, TAG, "Invalid num_of_ids");
+    uint32_t id = mask_cfg->num_of_ids ? mask_cfg->id_list[0] : mask_cfg->id;
+    bool full_close = (mask_cfg->mask == UINT32_MAX) && (id == UINT32_MAX);
+    ESP_RETURN_ON_FALSE(full_close || mask_cfg->dual_filter || mask_cfg->is_ext || !((mask_cfg->mask | id) & ~TWAI_STD_ID_MASK), ESP_ERR_INVALID_ARG, TAG, "std_id only (is_ext=0) but valid id/mask larger than 11 bits");
 #if SOC_TWAI_SUPPORT_FD
     // 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");
@@ -499,6 +511,8 @@ static esp_err_t _node_config_range_filter(twai_node_handle_t node, uint8_t filt
 {
     twai_onchip_ctx_t *twai_ctx = __containerof(node, twai_onchip_ctx_t, api_base);
     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");
 
     twai_hal_configure_range_filter(twai_ctx->hal, filter_id, range_cfg);

components/esp_driver_twai/include/esp_twai_onchip.h

@@ -13,44 +13,6 @@
 extern "C" {
 #endif
 
-/**
- * @brief Helper function to configure a dual 16-bit acceptance filter.
- * @note  For 29bits Extended IDs, ONLY high 16bits id/mask is used for eache filter.
- *
- * @param id1     First ID to filter.
- * @param mask1   Mask for first ID.
- * @param id2     Second ID to filter.
- * @param mask2   Mask for second ID.
- * @param is_ext  True if using Extended (29-bit) IDs, false for Standard (11-bit) IDs.
- * @return twai_mask_filter_config_t   A filled filter configuration structure for dual filtering.
- */
-static inline twai_mask_filter_config_t twai_make_dual_filter(uint16_t id1, uint16_t mask1, uint16_t id2, uint16_t mask2, bool is_ext)
-{
-    /**
-     * Dual filter is a special mode in hardware,
-     * which allow split general 32bits filter register to 2 unit of 16 bits id/mask pairs then using as 2 filter
-     * below code do bit shifting to reach hardware requirement in this mode, for detail please refer to `Dual Filter Mode` of TRM
-     *
-     *  31            16 15             0
-     *  ▼              ▼ ▼              ▼
-     *  xxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxx
-     *  ◄─11 bits─►      ◄─11 bits─►
-     *  std filter 2     std filter 1
-     *  ─────────────────────────────────
-     *  ◄───16─bits────► ◄───16─bits────►
-     *    ext filter 2     etx filter 1
-     */
-    twai_mask_filter_config_t dual_cfg = {
-        .id = is_ext ? (((id1 & TWAI_EXT_ID_MASK) >> 13) << 16) | ((id2 & TWAI_EXT_ID_MASK) >> 13) : \
-        ((id1 & TWAI_STD_ID_MASK) << 21) | ((id2 & TWAI_STD_ID_MASK) << 5),
-        .mask = is_ext ? (((mask1 & TWAI_EXT_ID_MASK) >> 13) << 16) | ((mask2 & TWAI_EXT_ID_MASK) >> 13) : \
-        ((mask1 & TWAI_STD_ID_MASK) << 21) | ((mask2 & TWAI_STD_ID_MASK) << 5),
-        .is_ext = is_ext,
-        .dual_filter = true,
-    };
-    return dual_cfg;
-}
-
 /**
  * @brief TWAI on-chip node initialization configuration structure
  */
@@ -72,7 +34,7 @@ typedef struct {
         uint32_t enable_loopback: 1;        /**< The TWAI controller receive back frames what it send out */
         uint32_t enable_listen_only: 1;     /**< The TWAI controller will not influence the bus (No transmissions or acknowledgments) but can receive messages */
         uint32_t no_receive_rtr: 1;         /**< Don't receive remote frames */
-    } flags;
+    } flags;                                /**< Misc configuration flags */
 } twai_onchip_node_config_t;
 
 /**
@@ -91,6 +53,44 @@ typedef struct {
  */
 esp_err_t twai_new_node_onchip(const twai_onchip_node_config_t *node_config, twai_node_handle_t *node_ret);
 
+/**
+ * @brief Helper function to configure a dual 16-bit acceptance filter.
+ * @note  For 29bits Extended IDs, ONLY high 16bits id/mask is used for eache filter.
+ *
+ * @param id1     First ID to filter.
+ * @param mask1   Mask for first ID.
+ * @param id2     Second ID to filter.
+ * @param mask2   Mask for second ID.
+ * @param is_ext  True if using Extended (29-bit) IDs, false for Standard (11-bit) IDs.
+ * @return twai_mask_filter_config_t   A filled filter configuration structure for dual filtering.
+ */
+static inline twai_mask_filter_config_t twai_make_dual_filter(uint16_t id1, uint16_t mask1, uint16_t id2, uint16_t mask2, bool is_ext)
+{
+    /**
+     * Dual filter is a special mode in hardware,
+     * which allow split general 32bits filter register to 2 unit of 16 bits id/mask pairs then using as 2 filter
+     * below code do bit shifting to reach hardware requirement in this mode, for detail please refer to `Dual Filter Mode` of TRM
+     *
+     *  31            16 15             0
+     *  ▼              ▼ ▼              ▼
+     *  xxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxx
+     *  ◄─11 bits─►      ◄─11 bits─►
+     *  std filter 2     std filter 1
+     *  ─────────────────────────────────
+     *  ◄───16─bits────► ◄───16─bits────►
+     *    ext filter 2     etx filter 1
+     */
+    twai_mask_filter_config_t dual_cfg = {
+        .id = is_ext ? (((id1 & TWAI_EXT_ID_MASK) >> 13) << 16) | ((id2 & TWAI_EXT_ID_MASK) >> 13) : \
+        ((id1 & TWAI_STD_ID_MASK) << 21) | ((id2 & TWAI_STD_ID_MASK) << 5),
+        .mask = is_ext ? (((mask1 & TWAI_EXT_ID_MASK) >> 13) << 16) | ((mask2 & TWAI_EXT_ID_MASK) >> 13) : \
+        ((mask1 & TWAI_STD_ID_MASK) << 21) | ((mask2 & TWAI_STD_ID_MASK) << 5),
+        .is_ext = is_ext,
+        .dual_filter = true,
+    };
+    return dual_cfg;
+}
+
 #ifdef __cplusplus
 }
 #endif

components/esp_driver_twai/include/esp_twai_types.h

@@ -29,7 +29,7 @@ typedef struct {
 /**
  * @brief TWAI transaction frame param type
  */
-typedef struct twai_frame_t {
+typedef struct {
     twai_frame_header_t header;     /**< message attribute/metadata, exclude data buffer*/
     uint8_t *buffer;                /**< buffer address for tx and rx message data*/
     size_t buffer_len;              /**< buffer length of provided data buffer pointer, in bytes.*/
@@ -57,6 +57,7 @@ typedef struct {
  * @brief TWAI "TX done" event data
  */
 typedef struct {
+    bool is_tx_success;                 /**< Indicate if frame send successful, refer `on_error` callback for fail reason if send failed */
     const twai_frame_t *done_tx_frame;  /**< Pointer to the frame that has been transmitted */
 } twai_tx_done_event_data_t;
 

components/hal/include/hal/twai_types.h

@@ -17,8 +17,8 @@ extern "C" {
 #endif
 
 /* valid bits in TWAI ID for frame formats */
-#define TWAI_STD_ID_MASK    0x000007FFU /* Mask of the ID fields in a standard frame */
-#define TWAI_EXT_ID_MASK    0x1FFFFFFFU /* Mask of the ID fields in an extended frame */
+#define TWAI_STD_ID_MASK        0x000007FFU /**< Mask of the ID fields in a standard frame */
+#define TWAI_EXT_ID_MASK        0x1FFFFFFFU /**< Mask of the ID fields in an extended frame */
 
 /* TWAI payload length and DLC definitions */
 #define TWAI_FRAME_MAX_DLC      8
@@ -32,10 +32,10 @@ extern "C" {
  * @brief TWAI node error fsm states
  */
 typedef enum {
-    TWAI_ERROR_ACTIVE,          /**< Error active state: TEC/REC < 96 */
-    TWAI_ERROR_WARNING,         /**< Error warning state: TEC/REC >= 96 and < 128 */
-    TWAI_ERROR_PASSIVE,         /**< Error passive state: TEC/REC >= 128 and < 256 */
-    TWAI_ERROR_BUS_OFF,         /**< Bus-off state: TEC >= 256 (node offline) */
+    TWAI_ERROR_ACTIVE,              /**< Error active state: TEC/REC < 96 */
+    TWAI_ERROR_WARNING,             /**< Error warning state: TEC/REC >= 96 and < 128 */
+    TWAI_ERROR_PASSIVE,             /**< Error passive state: TEC/REC >= 128 and < 256 */
+    TWAI_ERROR_BUS_OFF,             /**< Bus-off state: TEC >= 256 (node offline) */
 } twai_error_state_t;
 
 /**

components/hal/twai_hal_sja1000.c

@@ -216,8 +216,8 @@ static inline uint32_t twai_hal_decode_interrupt(twai_hal_context_t *hal_ctx)
                 TWAI_HAL_SET_BITS(events, TWAI_HAL_EVENT_ERROR_WARNING);
                 TWAI_HAL_SET_BITS(state_flags, TWAI_HAL_STATE_FLAG_ERR_WARN);
             } else if (hal_ctx->state_flags & TWAI_HAL_STATE_FLAG_RECOVERING) {
-                //Previously undergoing bus recovery. Thus means bus recovery complete
-                TWAI_HAL_SET_BITS(events, TWAI_HAL_EVENT_BUS_RECOV_CPLT);
+                //Previously undergoing bus recovery. Thus means bus recovery complete, hardware back to error_active
+                TWAI_HAL_SET_BITS(events, TWAI_HAL_EVENT_BUS_RECOV_CPLT | TWAI_HAL_EVENT_ERROR_ACTIVE);
                 TWAI_HAL_CLEAR_BITS(state_flags, TWAI_HAL_STATE_FLAG_RECOVERING | TWAI_HAL_STATE_FLAG_BUS_OFF);
             } else {        //Just went below EWL
                 TWAI_HAL_SET_BITS(events, TWAI_HAL_EVENT_BELOW_EWL);
@@ -269,17 +269,13 @@ uint32_t twai_hal_get_events(twai_hal_context_t *hal_ctx)
 
     //Handle low latency events
     if (events & TWAI_HAL_EVENT_BUS_OFF) {
-        twai_ll_set_mode(hal_ctx->dev, true, false, false);  //Freeze TEC/REC by entering LOM
 #ifdef CONFIG_TWAI_ERRATA_FIX_BUS_OFF_REC
         //Errata workaround: Force REC to 0 by re-triggering bus-off (by setting TEC to 0 then 255)
         twai_ll_set_tec(hal_ctx->dev, 0);
         twai_ll_set_tec(hal_ctx->dev, 255);
         (void) twai_ll_get_and_clear_intrs(hal_ctx->dev);    //Clear the re-triggered bus-off interrupt
 #endif
     }
-    if (events & TWAI_HAL_EVENT_BUS_RECOV_CPLT) {
-        twai_ll_enter_reset_mode(hal_ctx->dev);     //Enter reset mode to stop the controller
-    }
     if (events & TWAI_HAL_EVENT_BUS_ERR) {
         twai_ll_err_type_t type;
         twai_ll_err_dir_t dir;