CAN: Add functions to clear queues and fix multiple bugs

This commits adds the functions can_clear_transmit_queue() and
can_clear_receive_queue(). Closes #2906

The following bug are fixed:

- CAN_IO_UNUSED is now explicitly cast to enum type. Closes #2825
- Fix multiple documentation errors. Closes #2898, Closes #2794
- can_reconfigure_alerts() returns incorrect current_alerts. Closes #3028
- Add missing header file. Closes #3065

components/driver/can.c

@@ -438,6 +438,8 @@ static void can_intr_handler_rx(BaseType_t *task_woken, int *alert_req)
             can_alert_handler(CAN_ALERT_RX_QUEUE_FULL, alert_req);
         }
     }
+    //Todo: Add Software Filters
+    //Todo: Check for data overrun of RX FIFO, then trigger alert
 }
 
 static void can_intr_handler_tx(can_status_reg_t *status, int *alert_req)
@@ -496,7 +498,6 @@ static void can_intr_handler_main(void *arg)
         //Triggers when arbitration is lost
         can_intr_handler_arb_lost(&alert_req);
     }
-    //Todo: Check data overrun bug where interrupt does not trigger even when enabled
 
     //Handle TX/RX interrupts
     if (intr_reason.rx) {
@@ -913,7 +914,7 @@ esp_err_t can_reconfigure_alerts(uint32_t alerts_enabled, uint32_t *current_aler
     CAN_CHECK(p_can_obj != NULL, ESP_ERR_INVALID_STATE);
     CAN_ENTER_CRITICAL();
     uint32_t cur_alerts;
-    cur_alerts = can_read_alerts(&cur_alerts, 0);       //Clear any unhandled alerts
+    can_read_alerts(&cur_alerts, 0);                    //Clear any unhandled alerts
     p_can_obj->alerts_enabled = alerts_enabled;         //Update enabled alerts
     CAN_EXIT_CRITICAL();
 
@@ -977,3 +978,30 @@ esp_err_t can_get_status_info(can_status_info_t *status_info)
     return ESP_OK;
 }
 
+esp_err_t can_clear_transmit_queue()
+{
+    //Check State
+    CAN_CHECK(p_can_obj != NULL, ESP_ERR_INVALID_STATE);
+    CAN_CHECK(p_can_obj->tx_queue != NULL, ESP_ERR_NOT_SUPPORTED);
+
+    CAN_ENTER_CRITICAL();
+    //If a message is currently undergoing transmission, the tx interrupt handler will decrement tx_msg_count
+    p_can_obj->tx_msg_count = (p_can_obj->control_flags & CTRL_FLAG_TX_BUFF_OCCUPIED) ? 1 : 0;
+    xQueueReset(p_can_obj->tx_queue);
+    CAN_EXIT_CRITICAL();
+
+    return ESP_OK;
+}
+
+esp_err_t can_clear_receive_queue()
+{
+    //Check State
+    CAN_CHECK(p_can_obj != NULL, ESP_ERR_INVALID_STATE);
+
+    CAN_ENTER_CRITICAL();
+    p_can_obj->rx_msg_count = 0;
+    xQueueReset(p_can_obj->rx_queue);
+    CAN_EXIT_CRITICAL();
+
+    return ESP_OK;
+}

components/driver/include/driver/can.h

@@ -19,6 +19,7 @@
 extern "C" {
 #endif
 
+#include "freertos/FreeRTOS.h"
 #include "esp_types.h"
 #include "esp_intr.h"
 #include "esp_err.h"
@@ -105,7 +106,7 @@ extern "C" {
 #define CAN_EXTD_ID_MASK                0x1FFFFFFF  /**< Bit mask for 29 bit Extended Frame Format ID */
 #define CAN_STD_ID_MASK                 0x7FF       /**< Bit mask for 11 bit Standard Frame Format ID */
 #define CAN_MAX_DATA_LEN                8           /**< Maximum number of data bytes in a CAN2.0B frame */
-#define CAN_IO_UNUSED                   (-1)        /**< Marks GPIO as unused in CAN configuration */
+#define CAN_IO_UNUSED                   ((gpio_num_t) -1)   /**< Marks GPIO as unused in CAN configuration */
 /** @endcond */
 
 /* ----------------------- Enum and Struct Definitions ---------------------- */
@@ -392,6 +393,34 @@ esp_err_t can_initiate_recovery();
  */
 esp_err_t can_get_status_info(can_status_info_t *status_info);
 
+/**
+ * @brief   Clear the transmit queue
+ *
+ * This function will clear the transmit queue of all messages.
+ *
+ * @note    The transmit queue is automatically cleared when can_stop() or
+ *          can_initiate_recovery() is called.
+ *
+ * @return
+ *      - ESP_OK: Transmit queue cleared
+ *      - ESP_ERR_INVALID_STATE: CAN driver is not installed or TX queue is disabled
+ */
+esp_err_t can_clear_transmit_queue();
+
+/**
+ * @brief   Clear the receive queue
+ *
+ * This function will clear the receive queue of all messages.
+ *
+ * @note    The receive queue is automatically cleared when can_start() is
+ *          called.
+ *
+ * @return
+ *      - ESP_OK: Transmit queue cleared
+ *      - ESP_ERR_INVALID_STATE: CAN driver is not installed
+ */
+esp_err_t can_clear_receive_queue();
+
 #ifdef __cplusplus
 }
 #endif