feat(isotp): enhance ISO-TP transport with callback support and thread safety features

Author: eternal-echo

esp_isotp/inc/esp_isotp.h

@@ -28,6 +28,38 @@
 extern "C" {
 #endif
 
+/**
+ * @brief ISO-TP receive callback function type
+ *
+ * Called when a complete message has been received successfully.
+ *
+ * @warning This callback executes in the same context as isotp_on_can_message(),
+ *          which is typically ISR context. Keep callback execution time minimal
+ *          and avoid blocking operations.
+ * @note The data pointer is only valid during the callback execution.
+ *       Copy data immediately if needed beyond the callback scope.
+ *
+ * @param[in] data Pointer to received data (valid only during callback)
+ * @param[in] size Size of received data in bytes
+ * @param[in] user_arg User argument provided during configuration
+ */
+typedef void (*esp_isotp_rx_callback_t)(const uint8_t *data, uint32_t size, void *user_arg);
+
+/**
+ * @brief ISO-TP transmit callback function type
+ *
+ * Called when a complete message has been transmitted successfully.
+ *
+ * @note Execution context depends on message type:
+ *       - Single-frame: Called immediately from isotp_send() in caller's context
+ *       - Multi-frame: Called from isotp_poll() in task context
+ * @note Keep callback execution time minimal to avoid affecting system performance.
+ *
+ * @param[in] tx_size Size of transmitted data in bytes
+ * @param[in] user_arg User argument provided during configuration
+ */
+typedef void (*esp_isotp_tx_callback_t)(uint32_t tx_size, void *user_arg);
+
 /**
  * @brief ISO-TP link handle
  */
@@ -41,7 +73,12 @@ typedef struct {
     uint32_t rx_id;                  /*!< TWAI ID for receiving ISO-TP frames (11-bit or 29-bit) */
     uint32_t tx_buffer_size;         /*!< Size of the transmit buffer (max message size to send) */
     uint32_t rx_buffer_size;         /*!< Size of the receive buffer (max message size to receive) */
+    uint32_t tx_frame_pool_size;     /*!< Size of TX frame pool (0 for default: 8) */
     bool use_extended_id;            /*!< true: use 29-bit extended ID, false: use 11-bit standard ID */
+
+    esp_isotp_rx_callback_t rx_callback; /*!< Receive completion callback (NULL for polling mode) */
+    esp_isotp_tx_callback_t tx_callback; /*!< Transmit completion callback (NULL to disable) */
+    void *callback_arg;               /*!< User argument passed to callbacks */
 } esp_isotp_config_t;
 
 /**
@@ -63,11 +100,16 @@ typedef struct {
 esp_err_t esp_isotp_new_transport(twai_node_handle_t twai_node, const esp_isotp_config_t *config, esp_isotp_handle_t *out_handle);
 
 /**
- * @brief Send data over an ISO-TP link (non-blocking)
+ * @brief Send data over an ISO-TP link (non-blocking, ISR-safe)
  *
  * Immediately sends first/single frame and returns. For multi-frame messages,
  * remaining frames are sent during subsequent esp_isotp_poll() calls.
  *
+ * @note This function is ISR-safe and can be called from interrupt context.
+ * @note TX completion callback timing:
+ *       - Single-frame: Called immediately from isotp_send()
+ *       - Multi-frame: Called from isotp_poll() when last frame is sent
+ *
  * @param handle ISO-TP handle
  * @param data Data to send
  * @param size Data length in bytes
@@ -83,12 +125,17 @@ esp_err_t esp_isotp_new_transport(twai_node_handle_t twai_node, const esp_isotp_
 esp_err_t esp_isotp_send(esp_isotp_handle_t handle, const uint8_t *data, uint32_t size);
 
 /**
- * @brief Send data over an ISO-TP link with specified TWAI ID (non-blocking)
+ * @brief Send data over an ISO-TP link with specified TWAI ID (non-blocking, ISR-safe)
  *
  * Similar to esp_isotp_send(), but allows specifying a different TWAI ID for transmission.
  * This function is primarily used for functional addressing where multiple nodes
  * may respond to the same request.
  *
+ * @note This function is ISR-safe and can be called from interrupt context.
+ * @note TX completion callback timing:
+ *       - Single-frame: Called immediately from isotp_send_with_id()
+ *       - Multi-frame: Called from isotp_poll() when last frame is sent
+ *
  * @param handle ISO-TP handle
  * @param id TWAI identifier to use for transmission (overrides configured tx_id)
  * @param data Data to send
@@ -99,19 +146,24 @@ esp_err_t esp_isotp_send(esp_isotp_handle_t handle, const uint8_t *data, uint32_
  *     - ESP_ERR_NO_MEM: Data too large for buffer or no space available
  *     - ESP_ERR_INVALID_SIZE: Invalid data size
  *     - ESP_ERR_TIMEOUT: Send operation timed out
- *     - ESP_ERR_INVALID_ARG: Invalid parameters
+ *     - ESP_ERR_INVALID_ARG: Invalid parameters or ID exceeds format mask
  *     - ESP_FAIL: Other send errors
  */
 esp_err_t esp_isotp_send_with_id(esp_isotp_handle_t handle, uint32_t id, const uint8_t *data, uint32_t size);
 
 /**
- * @brief Extract a complete received message (non-blocking)
+ * @brief Extract a complete received message (non-blocking, task context only)
  *
  * This function only extracts data that has already been assembled by esp_isotp_poll().
  * It does NOT process incoming TWAI frames - that happens in esp_isotp_poll().
  *
  * Process: TWAI frames → esp_isotp_poll() assembles → esp_isotp_receive() extracts
  *
+ * @warning This function is NOT ISR-safe and must only be called from task context.
+ * @note When using callback mode (rx_callback != NULL), received messages are
+ *       automatically delivered via callback. This function should only be used
+ *       in polling mode (rx_callback == NULL).
+ *
  * @param handle ISO-TP handle
  * @param data Buffer to store received data
  * @param size Buffer size in bytes
@@ -125,10 +177,10 @@ esp_err_t esp_isotp_send_with_id(esp_isotp_handle_t handle, uint32_t id, const u
  *     - ESP_ERR_INVALID_ARG: Invalid parameters
  *     - ESP_FAIL: Other receive errors
  */
-esp_err_t esp_isotp_receive(esp_isotp_handle_t handle, uint8_t *data, uint32_t size, uint32_t *received_size);
+esp_err_t esp_isotp_receive(esp_isotp_handle_t handle, uint8_t *data, const uint32_t size, uint32_t *received_size);
 
 /**
- * @brief Poll the ISO-TP link to process messages (CRITICAL - call regularly!)
+ * @brief Poll the ISO-TP link to process messages (CRITICAL - call regularly, task context only)
  *
  * This function drives the ISO-TP state machine. Call every 1-10ms for proper operation.
  *
@@ -137,9 +189,13 @@ esp_err_t esp_isotp_receive(esp_isotp_handle_t handle, uint8_t *data, uint32_t s
  * - Processes incoming TWAI frames and assembles complete messages
  * - Handles flow control and timeouts
  * - Updates internal state machine
+ * - Triggers TX completion callbacks for multi-frame messages
  *
  * Without regular polling: multi-frame sends will stall and receives won't complete.
  *
+ * @warning This function is NOT ISR-safe and must only be called from task context.
+ * @note TX completion callbacks for multi-frame messages are triggered from this function.
+ *
  * @param handle ISO-TP handle
  * @return
  *     - ESP_OK: Processing successful