usb_cdc_acm.h

Go to the documentation of this file.

#pragma once
#if defined(USE_ESP32_VARIANT_ESP32P4) || defined(USE_ESP32_VARIANT_ESP32S2) || defined(USE_ESP32_VARIANT_ESP32S3) || \
    defined(USE_ESP32_VARIANT_ESP32S31) || defined(USE_ESP32_VARIANT_ESP32H4)
 
#include "esphome/core/component.h"
#include "esphome/core/event_pool.h"
#include "esphome/core/lock_free_queue.h"
#include "esphome/components/uart/uart_component.h"
 
#include <array>
#include <atomic>
#include <cstring>
#include <functional>
#include "freertos/ringbuf.h"
#include "esp_err.h"
#include "tinyusb_cdc_acm.h"
 
namespace esphome::usb_cdc_acm {
 
static const uint8_t EVENT_QUEUE_SIZE = 12;
 
// Drain up to out_buf_sz bytes from a byte ring buffer, handling FreeRTOS's wrapped
// case with a second read. Shared with the cdc_acm_uart bridge platform, whose worker
// tasks drain the same ring buffers.
inline esp_err_t ringbuf_read_bytes(RingbufHandle_t ring_buf, uint8_t *out_buf, size_t out_buf_sz, size_t *rx_data_size,
                                    TickType_t x_ticks_to_wait) {
  size_t read_sz;
  uint8_t *buf = static_cast<uint8_t *>(xRingbufferReceiveUpTo(ring_buf, &read_sz, x_ticks_to_wait, out_buf_sz));
 
  if (buf == nullptr) {
    return ESP_FAIL;
  }
 
  memcpy(out_buf, buf, read_sz);
  vRingbufferReturnItem(ring_buf, (void *) buf);
  *rx_data_size = read_sz;
 
  // Buffer's data can be wrapped, in which case we should perform another read
  if (*rx_data_size < out_buf_sz) {
    buf = static_cast<uint8_t *>(xRingbufferReceiveUpTo(ring_buf, &read_sz, 0, out_buf_sz - *rx_data_size));
    if (buf != nullptr) {
      memcpy(out_buf + *rx_data_size, buf, read_sz);
      vRingbufferReturnItem(ring_buf, (void *) buf);
      *rx_data_size += read_sz;
    }
  }
 
  return ESP_OK;
}
 
// Callback types for line coding and line state changes
using LineCodingCallback = std::function<void(uint32_t bit_rate, uint8_t stop_bits, uint8_t parity, uint8_t data_bits)>;
using LineStateCallback = std::function<void(bool dtr, bool rts)>;
 
// Event types
enum CDCEventType : uint8_t {
  CDC_EVENT_LINE_STATE_CHANGED,
  CDC_EVENT_LINE_CODING_CHANGED,
};
 
// Event structure for the queue
struct CDCEvent {
  CDCEventType type;
  union {
    struct {
      bool dtr;
      bool rts;
    } line_state;
    struct {
      uint32_t bit_rate;
      uint8_t stop_bits;
      uint8_t parity;
      uint8_t data_bits;
    } line_coding;
  } data;
 
  // Required by EventPool - called before returning to pool
  void release() {
    // No dynamic memory to clean up, data is stored inline
  }
};
 
// Forward declaration
class USBCDCACMComponent;
 
class USBCDCACMInstance final : public uart::UARTComponent, public Parented<USBCDCACMComponent> {
 public:
  void setup();
  void loop();
  void dump_config();
 
  void set_interface_number(uint8_t itf) { this->itf_ = itf; }
  // Get the CDC port number for this instance
  uint8_t get_itf() const { return this->itf_; }
  // Ring buffer accessors for bridge components
  RingbufHandle_t get_tx_ringbuf() const { return this->usb_tx_ringbuf_; }
  RingbufHandle_t get_rx_ringbuf() const { return this->usb_rx_ringbuf_; }
 
  // Task handle accessor for notifying TX task
  TaskHandle_t get_tx_task_handle() const { return this->usb_tx_task_handle_; }
 
  // Callback registration for line coding and line state changes
  void set_line_coding_callback(LineCodingCallback callback) { this->line_coding_callback_ = std::move(callback); }
  void set_line_state_callback(LineStateCallback callback) { this->line_state_callback_ = std::move(callback); }
 
  // Called from USB core task context queues event for processing in main loop
  void queue_line_coding_event(uint32_t bit_rate, uint8_t stop_bits, uint8_t parity, uint8_t data_bits);
  void queue_line_state_event(bool dtr, bool rts);
 
  static void usb_tx_task_fn(void *arg);
  void usb_tx_task();
 
  // UARTComponent interface implementation
  void write_array(const uint8_t *data, size_t len) override;
  bool peek_byte(uint8_t *data) override;
  bool read_array(uint8_t *data, size_t len) override;
  size_t available() override;
  uart::UARTFlushResult flush() override;
#if defined(USE_ESP8266) || defined(USE_ESP32)
  // No-op: in CDC ACM device mode the host dictates the line coding, so there are no
  // local UART settings to (re)apply.
  void load_settings(bool dump_config) override {}
  using UARTComponent::load_settings;  // also bring in the no-arg overload for convenience
#endif
 
 protected:
  void check_logger_conflict() override;
 
  // Process queued events and invoke callbacks (called from main loop)
  void process_events_();
  // True while TX bytes are still in the ring buffer or held by the TX task
  bool tx_pending_();
  TaskHandle_t usb_tx_task_handle_{nullptr};
 
  RingbufHandle_t usb_tx_ringbuf_{nullptr};
  RingbufHandle_t usb_rx_ringbuf_{nullptr};
  // TX task staging; a member rather than a stack array so it does not size the task stack.
  std::array<uint8_t, CONFIG_TINYUSB_CDC_TX_BUFSIZE> usb_tx_staging_{};
  // Non-zero while the TX task holds bytes it has pulled from the ring buffer but not
  // yet handed to TinyUSB; lets flush() account for data that is in neither the ring
  // buffer nor TinyUSB's FIFO.
  // Threading: written only by usb_tx_task(); read by flush()'s bounded wait on the
  // caller's task (typically the main loop).
  // std::atomic<uint8_t> rather than std::atomic<bool> because GCC on Xtensa
  // generates an indirect function call for atomic<bool> ops instead of inlining
  // them; atomic<uint8_t> inlines correctly on all platforms.
  std::atomic<uint8_t> usb_tx_busy_{0};
  // Running total of bytes dropped by write_array() (never reset), and the timestamp
  // of the last "buffer full" log line (throttled so a sustained host stall doesn't
  // flood the log).
  uint32_t tx_dropped_bytes_{0};
  uint32_t tx_dropped_log_ms_{0};
  // RX buffer for peek functionality
  uint8_t peek_buffer_{0};
  bool has_peek_{false};
  uint8_t itf_{0};
  // User-registered callbacks (called from main loop)
  LineCodingCallback line_coding_callback_{nullptr};
  LineStateCallback line_state_callback_{nullptr};
 
  // Lock-free queue and event pool for cross-task event passing
  // Pool sized to queue capacity (SIZE-1) because LockFreeQueue<T,N> is a ring
  // buffer that holds N-1 elements. This guarantees allocate() returns nullptr
  // before push() can fail, preventing both a pool slot leak and an SPSC
  // violation on the pool's internal free list.
  EventPool<CDCEvent, EVENT_QUEUE_SIZE - 1> event_pool_;
  LockFreeQueue<CDCEvent, EVENT_QUEUE_SIZE> event_queue_;
};
 
class USBCDCACMComponent final : public Component {
 public:
  USBCDCACMComponent();
 
  void setup() override;
  void loop() override;
  void dump_config() override;
  float get_setup_priority() const override { return setup_priority::IO; }
 
  // Interface management
  void add_interface(USBCDCACMInstance *interface);
  USBCDCACMInstance *get_interface_by_number(uint8_t itf);
 
 protected:
  std::array<USBCDCACMInstance *, ESPHOME_MAX_USB_CDC_INSTANCES> interfaces_{};
};
 
extern USBCDCACMComponent *global_usb_cdc_component;  // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
 
}  // namespace esphome::usb_cdc_acm
#endif