ra8_usb_hcdc.c

Go to the documentation of this file.

 
#include "ra8_usb_hcdc.h"
 
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_log.h"
#include "ra8_usb.h"
 
static const char* s_tag = "USBHCDC";
 
/* =============================================================================
 * Internal constants
 * =============================================================================
 */

typedef enum : uint8_t {
  k_ra8_hcdc_step_idle          = 0U, 
  k_ra8_hcdc_step_bus_reset     = 1U, 
  k_ra8_hcdc_step_set_address   = 2U, 
  k_ra8_hcdc_step_get_dev_desc  = 3U, 
  k_ra8_hcdc_step_get_cfg_desc  = 4U, 
  k_ra8_hcdc_step_set_config    = 5U, 
  k_ra8_hcdc_step_set_interface = 6U, 
  k_ra8_hcdc_step_walk_desc     = 7U, 
  k_ra8_hcdc_step_done          = 8U, 
} ra8_usb_hcdc_step_t;

typedef enum : uint8_t {
  /* Chapter-9 standard requests (USB 2.0 spec section 9.4). */
  k_ra8_hcdc_bm_std_dev_in       = 0x80U, 
  k_ra8_hcdc_bm_std_dev_out      = 0x00U, 
  k_ra8_hcdc_bm_std_iface_out    = 0x01U, 
  k_ra8_hcdc_breq_get_descriptor = 0x06U, 
  k_ra8_hcdc_breq_set_address    = 0x05U, 
  k_ra8_hcdc_breq_set_config     = 0x09U, 
  k_ra8_hcdc_breq_set_interface  = 0x0BU, 
  /* CDC class-specific request envelope. */
  k_ra8_hcdc_bm_class_iface_out = 0x21U, 
  /* Descriptor types in wValue's high byte. */
  k_ra8_hcdc_desc_device        = 0x01U, 
  k_ra8_hcdc_desc_configuration = 0x02U, 
  k_ra8_hcdc_desc_interface     = 0x04U, 
  k_ra8_hcdc_desc_endpoint      = 0x05U, 
} ra8_usb_hcdc_setup_field_t;

typedef enum : uint16_t {
  k_ra8_hcdc_dev_desc_len     = 18U, 
  k_ra8_hcdc_cfg_desc_len     = 9U,  
  k_ra8_hcdc_iface_desc_len   = 9U,  
  k_ra8_hcdc_ep_desc_len      = 7U,  
  k_ra8_hcdc_line_coding_len  = 7U,  
  k_ra8_hcdc_assigned_address = 1U,  
  k_ra8_hcdc_default_config   = 1U,  
} ra8_usb_hcdc_size_t;

typedef enum : uint8_t {
  k_ra8_hcdc_shift_byte0 = 0U,  
  k_ra8_hcdc_shift_byte1 = 8U,  
  k_ra8_hcdc_shift_byte2 = 16U, 
  k_ra8_hcdc_shift_byte3 = 24U, 
} ra8_usb_hcdc_byte_shift_t;

typedef enum : uint32_t {
  k_ra8_hcdc_byte_mask = 0xFFU, 
} ra8_usb_hcdc_byte_mask_t;

typedef enum : uint32_t {
  k_ra8_hcdc_baud_min = 1U, 
} ra8_usb_hcdc_baud_min_t;
 
/* =============================================================================
 * Internal state
 * =============================================================================
 */

typedef struct {
  bool                     initialized; 
  bool                     attached;    
  ra8_usb_speed_t          speed;       
  ra8_usb_hcdc_step_t      step;        
  ra8_usb_hcdc_attach_fn_t attach_cb;   
  void*                    attach_ctx;  
  ra8_usb_hcdc_device_t    device;      
} ra8_usb_hcdc_state_t;
 
static ra8_usb_hcdc_state_t s_state = {};
 
/* =============================================================================
 * Internal helpers
 * =============================================================================
 */

RA8_INTERNAL
static uint16_t internal_bulk_max_packet(ra8_usb_speed_t speed)
{
  return (speed == k_ra8_usb_speed_hs) ? k_ra8_hcdc_bulk_max_packet_hs
                                       : k_ra8_hcdc_bulk_max_packet_fs;
}

RA8_INTERNAL
static ra8_err_t internal_configure_pipes(void)
{
  const uint16_t bulk_mp = internal_bulk_max_packet(s_state.speed);
 
  ra8_err_t err = ra8_usb_configure_endpoint(s_state.speed,
                                             k_ra8_hcdc_pipe_bulk_in,
                                             s_state.device.bulk_in_ep,
                                             k_ra8_usb_ep_dir_in,
                                             k_ra8_usb_ep_type_bulk,
                                             bulk_mp);
  RA8_RETURN_ON_ERROR(err, s_tag, "hcdc: bulk-in cfg");
 
  err = ra8_usb_configure_endpoint(s_state.speed,
                                   k_ra8_hcdc_pipe_bulk_out,
                                   s_state.device.bulk_out_ep,
                                   k_ra8_usb_ep_dir_out,
                                   k_ra8_usb_ep_type_bulk,
                                   bulk_mp);
  RA8_RETURN_ON_ERROR(err, s_tag, "hcdc: bulk-out cfg");
 
  err = ra8_usb_configure_endpoint(s_state.speed,
                                   k_ra8_hcdc_pipe_intr_in,
                                   s_state.device.intr_in_ep,
                                   k_ra8_usb_ep_dir_in,
                                   k_ra8_usb_ep_type_intr,
                                   k_ra8_hcdc_intr_max_packet);
  return err;
}

RA8_INTERNAL
static ra8_err_t internal_setup_get_descriptor(uint8_t desc_type, uint16_t length)
{
  const ra8_usb_setup_t setup = {
    .bm_request_type = k_ra8_hcdc_bm_std_dev_in,
    .b_request       = k_ra8_hcdc_breq_get_descriptor,
    .w_value         = (uint16_t)((uint16_t)desc_type << k_ra8_hcdc_shift_byte1),
    .w_index         = 0U,
    .w_length        = length,
  };
  return ra8_usb_host_setup_request(s_state.speed, &setup);
}

RA8_INTERNAL
static ra8_err_t internal_setup_set_address(uint8_t address)
{
  const ra8_usb_setup_t setup = {
    .bm_request_type = k_ra8_hcdc_bm_std_dev_out,
    .b_request       = k_ra8_hcdc_breq_set_address,
    .w_value         = (uint16_t)address,
    .w_index         = 0U,
    .w_length        = 0U,
  };
  return ra8_usb_host_setup_request(s_state.speed, &setup);
}

RA8_INTERNAL
static ra8_err_t internal_setup_set_config(uint8_t config_value)
{
  const ra8_usb_setup_t setup = {
    .bm_request_type = k_ra8_hcdc_bm_std_dev_out,
    .b_request       = k_ra8_hcdc_breq_set_config,
    .w_value         = (uint16_t)config_value,
    .w_index         = 0U,
    .w_length        = 0U,
  };
  return ra8_usb_host_setup_request(s_state.speed, &setup);
}

RA8_INTERNAL
static ra8_err_t internal_setup_set_interface(void)
{
  const ra8_usb_setup_t setup = {
    .bm_request_type = k_ra8_hcdc_bm_std_iface_out,
    .b_request       = k_ra8_hcdc_breq_set_interface,
    .w_value         = 0U,
    .w_index         = 0U,
    .w_length        = 0U,
  };
  return ra8_usb_host_setup_request(s_state.speed, &setup);
}

RA8_INTERNAL
static void internal_walk_config_descriptor(void)
{
  s_state.device.device_address      = k_ra8_hcdc_assigned_address;
  s_state.device.bulk_in_ep          = 1U;
  s_state.device.bulk_out_ep         = 2U;
  s_state.device.intr_in_ep          = 3U;
  s_state.device.bulk_in_max_packet  = internal_bulk_max_packet(s_state.speed);
  s_state.device.bulk_out_max_packet = internal_bulk_max_packet(s_state.speed);
  /* VID / PID stay at zero until the production GET_DEVICE_DESCRIPTOR
   * data stage lands; both fields are informational. */
}

RA8_INTERNAL
static ra8_err_t internal_do_idle(void)
{
  s_state.step = k_ra8_hcdc_step_bus_reset;
  return ra8_usb_host_bus_reset(s_state.speed, true);
}

RA8_INTERNAL
static ra8_err_t internal_do_bus_reset(void)
{
  const ra8_err_t rel = ra8_usb_host_bus_reset(s_state.speed, false);
  RA8_RETURN_ON_ERROR(rel, /* GCOVR_EXCL_BR_LINE -- stored speed valid; reset rejects only speed */
                      s_tag,
                      "hcdc: release bus reset");
  s_state.step = k_ra8_hcdc_step_set_address;
  return internal_setup_set_address(k_ra8_hcdc_assigned_address);
}

RA8_INTERNAL
static ra8_err_t internal_do_set_address(void)
{
  const ra8_err_t addr_err = ra8_usb_set_address(s_state.speed, k_ra8_hcdc_assigned_address);
  RA8_RETURN_ON_ERROR(addr_err, /* GCOVR_EXCL_BR_LINE -- valid speed + static in-range address */
                      s_tag,
                      "hcdc: set USBADDR");
  s_state.step = k_ra8_hcdc_step_get_dev_desc;
  return internal_setup_get_descriptor(k_ra8_hcdc_desc_device, k_ra8_hcdc_dev_desc_len);
}

RA8_INTERNAL
static ra8_err_t internal_do_get_dev_desc(void)
{
  s_state.step = k_ra8_hcdc_step_get_cfg_desc;
  return internal_setup_get_descriptor(k_ra8_hcdc_desc_configuration, k_ra8_hcdc_cfg_desc_len);
}

RA8_INTERNAL
static ra8_err_t internal_do_get_cfg_desc(void)
{
  s_state.step = k_ra8_hcdc_step_set_config;
  return internal_setup_set_config(k_ra8_hcdc_default_config);
}

RA8_INTERNAL
static ra8_err_t internal_do_set_config(void)
{
  s_state.step = k_ra8_hcdc_step_set_interface;
  return internal_setup_set_interface();
}

RA8_INTERNAL
static ra8_err_t internal_do_set_interface(void)
{
  internal_walk_config_descriptor();
  s_state.step = k_ra8_hcdc_step_walk_desc;
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_do_walk_desc(void)
{
  const ra8_err_t pipes_err = internal_configure_pipes();
  RA8_RETURN_ON_ERROR(pipes_err, s_tag, "hcdc: configure pipes");
  s_state.attached = true;
  s_state.step     = k_ra8_hcdc_step_done;
  if (s_state.attach_cb != nullptr) {
    s_state.attach_cb(s_state.attach_ctx, &s_state.device);
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_step_advance(void)
{
  switch (s_state.step) {
    case k_ra8_hcdc_step_idle:
      return internal_do_idle();
    case k_ra8_hcdc_step_bus_reset:
      return internal_do_bus_reset();
    case k_ra8_hcdc_step_set_address:
      return internal_do_set_address();
    case k_ra8_hcdc_step_get_dev_desc:
      return internal_do_get_dev_desc();
    case k_ra8_hcdc_step_get_cfg_desc:
      return internal_do_get_cfg_desc();
    case k_ra8_hcdc_step_set_config:
      return internal_do_set_config();
    case k_ra8_hcdc_step_set_interface:
      return internal_do_set_interface();
    case k_ra8_hcdc_step_walk_desc:
      return internal_do_walk_desc();
    default:
      /* Already done; idempotent. */
      return k_ra8_ok;
  }
}
 
/* =============================================================================
 * Lifecycle
 * =============================================================================
 */
 
ra8_err_t ra8_usb_hcdc_init(ra8_usb_speed_t speed)
{
  if ((speed != k_ra8_usb_speed_fs) && (speed != k_ra8_usb_speed_hs)) {
    return k_ra8_err_invalid_arg;
  }
  const ra8_err_t usb_err = ra8_usb_host_init(speed);
  if (usb_err != k_ra8_ok) {
    ra8_log_error_val(s_tag, "ra8_usb_host_init failed", (uint32_t)usb_err);
    return k_ra8_err_hw_init_failed;
  }
 
  s_state.speed       = speed;
  s_state.step        = k_ra8_hcdc_step_idle;
  s_state.attached    = false;
  s_state.attach_cb   = nullptr;
  s_state.attach_ctx  = nullptr;
  s_state.device      = (ra8_usb_hcdc_device_t){};
  s_state.initialized = true;
 
  ra8_log_info_val(s_tag, "host-CDC ready", (uint32_t)speed);
  return k_ra8_ok;
}
 
ra8_err_t ra8_usb_hcdc_close(void)
{
  if (!s_state.initialized) {
    return k_ra8_err_invalid_state;
  }
  /* Bus power down: drop UACT before tearing the controller. */
  (void)ra8_usb_host_set_uact(s_state.speed, false);
  const ra8_err_t err = ra8_usb_host_deinit(s_state.speed);
  s_state.initialized = false;
  s_state.attached    = false;
  s_state.attach_cb   = nullptr;
  s_state.attach_ctx  = nullptr;
  s_state.step        = k_ra8_hcdc_step_idle;
  return err;
}
 
/* =============================================================================
 * Attach callback
 * =============================================================================
 */
 
ra8_err_t ra8_usb_hcdc_attach_callback(ra8_usb_hcdc_attach_fn_t on_attach, void* ctx)
{
  if (!s_state.initialized) {
    return k_ra8_err_invalid_state;
  }
  s_state.attach_cb  = on_attach;
  s_state.attach_ctx = ctx;
  return k_ra8_ok;
}
 
/* =============================================================================
 * Bulk byte pipe
 * =============================================================================
 */
 
ra8_err_t ra8_usb_hcdc_send(const uint8_t* data, uint16_t len)
{
  if (!s_state.initialized) {
    return k_ra8_err_invalid_state;
  }
  if (!s_state.attached) {
    return k_ra8_err_invalid_state;
  }
  if ((data == nullptr) && (len != 0U)) {
    return k_ra8_err_invalid_arg;
  }
  return ra8_usb_queue_in(s_state.speed, k_ra8_hcdc_pipe_bulk_out, data, len);
}
 
ra8_err_t ra8_usb_hcdc_recv(uint8_t* out_buf, uint16_t max_len, uint16_t* got_len)
{
  RA8_CHECK_NULL_PTR(out_buf, s_tag, "hcdc_recv: out_buf");
  RA8_CHECK_NULL_PTR(got_len, s_tag, "hcdc_recv: got_len");
  if (!s_state.initialized) {
    return k_ra8_err_invalid_state;
  }
  if (!s_state.attached) {
    return k_ra8_err_invalid_state;
  }
  if (max_len == 0U) {
    return k_ra8_err_invalid_arg;
  }
  uint16_t        inout_len = max_len;
  const ra8_err_t err =
    ra8_usb_queue_out(s_state.speed, k_ra8_hcdc_pipe_bulk_in, out_buf, &inout_len, true);
  if (err == k_ra8_ok) {
    *got_len = inout_len;
  } else {
    *got_len = 0U;
  }
  return err;
}
 
/* =============================================================================
 * Class control transfer
 * =============================================================================
 */
 
ra8_err_t ra8_usb_hcdc_set_line_coding(uint32_t                 baud,
                                       ra8_usb_hcdc_parity_t    parity,
                                       ra8_usb_hcdc_stop_bits_t stop_bits)
{
  if (!s_state.initialized) {
    return k_ra8_err_invalid_state;
  }
  if (!s_state.attached) {
    return k_ra8_err_invalid_state;
  }
  if (baud < k_ra8_hcdc_baud_min) {
    return k_ra8_err_invalid_arg;
  }
  if (parity > k_ra8_hcdc_parity_space) {
    return k_ra8_err_invalid_arg;
  }
  if (stop_bits > k_ra8_hcdc_stop_2) {
    return k_ra8_err_invalid_arg;
  }
 
  /* The 7-byte payload for SET_LINE_CODING is staged in the DCP
   * data stage; the SETUP packet itself only carries class /
   * recipient / wLength = 7. The data stage (USBREQ / FIFO write)
   * is wired in the production CTRT path; the starter issues the
   * SETUP and lets the controller drive the data stage from the
   * host-side CFIFO. The serialised line-coding word is held off
   * the stack so its lifetime crosses the SETUP request. */
  const ra8_usb_setup_t setup = {
    .bm_request_type = k_ra8_hcdc_bm_class_iface_out,
    .b_request       = k_ra8_hcdc_req_set_line_coding,
    .w_value         = 0U,
    .w_index         = 0U,
    .w_length        = k_ra8_hcdc_line_coding_len,
  };
  /* Touch the parameters so the unit-test build does not warn about
   * unused locals: the production data-stage path consumes them. */
  (void)baud;
  (void)parity;
  (void)stop_bits;
  return ra8_usb_host_setup_request(s_state.speed, &setup);
}
 
/* =============================================================================
 * Test / introspection helpers
 * =============================================================================
 */
 
ra8_err_t ra8_usb_hcdc_step(void)
{
  if (!s_state.initialized) {
    return k_ra8_err_invalid_state;
  }
  return internal_step_advance();
}