ra8_usb_hmsc_enum.c

Go to the documentation of this file.

 
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_hal_internal.h"
#include "ra8_time.h"
#include "ra8_usb.h"
#include "ra8_usb_hmsc.h"
#include "ra8_usb_hmsc_internal.h"
 
static const char* s_tag = "USBHMSC";
 
/* =============================================================================
 * Polled enumeration ladder (hardware-proven; replaces the CTRT machine)
 * =============================================================================
 */

typedef enum : uint32_t {
  k_ra8_hmsc_vbus_settle_ms = 200U,  
  k_ra8_hmsc_attach_to_ms   = 2000U, 
  k_ra8_hmsc_debounce_ms    = 500U,  
  k_ra8_hmsc_reset_hold_ms  = 50U,   
  k_ra8_hmsc_recovery_ms    = 20U,   
  k_ra8_hmsc_addr_settle_ms = 5U,    
  k_ra8_hmsc_enum_tries     = 8U,    
  k_ra8_hmsc_no_reset_tries = 4U,    
  k_ra8_hmsc_addr_alt_mask  = 0x03U, 
  k_ra8_hmsc_cfg_buf_len    = 128U,  
  k_ra8_hmsc_attach_spin_limit = 50000000UL,
} ra8_usb_hmsc_enum_tune_t;

typedef enum : uint8_t {
  k_ra8_hmsc_off_dlen        = 0U,    
  k_ra8_hmsc_off_dtype       = 1U,    
  k_ra8_hmsc_off_iface_num   = 2U,    
  k_ra8_hmsc_off_iface_class = 5U,    
  k_ra8_hmsc_off_iface_sub   = 6U,    
  k_ra8_hmsc_off_iface_proto = 7U,    
  k_ra8_hmsc_off_ep_addr     = 2U,    
  k_ra8_hmsc_off_ep_attr     = 3U,    
  k_ra8_hmsc_off_ep_mps      = 4U,    
  k_ra8_hmsc_off_cfg_total   = 2U,    
  k_ra8_hmsc_off_cfg_value   = 5U,    
  k_ra8_hmsc_off_dev_vid     = 8U,    
  k_ra8_hmsc_off_dev_pid     = 10U,   
  k_ra8_hmsc_ep_dir_in_bit   = 0x80U, 
  k_ra8_hmsc_ep_num_mask     = 0x0FU, 
  k_ra8_hmsc_ep_attr_mask    = 0x03U, 
  k_ra8_hmsc_ep_attr_bulk    = 0x02U, 
  k_ra8_hmsc_byte_bits       = 8U,    
} ra8_usb_hmsc_walk_off_t;

RA8_INTERNAL
static ra8_err_t internal_enum_read_dev_desc(uint8_t* desc)
{
  const ra8_usb_setup_t setup = {
    .bm_request_type = k_ra8_hmsc_bm_std_dev_in,
    .b_request       = k_ra8_hmsc_breq_get_descriptor,
    .w_value         = (uint16_t)((uint16_t)k_ra8_hmsc_desc_device << k_ra8_hmsc_byte_bits),
    .w_index         = 0U,
    .w_length        = k_ra8_hmsc_dev_desc_len,
  };
  uint16_t        rx  = 0U;
  const ra8_err_t err = ra8_usb_host_control_xfer(g_usb_hmsc_state.speed,
                                                  &setup,
                                                  desc,
                                                  (uint16_t)k_ra8_hmsc_dev_desc_len,
                                                  &rx);
  RA8_RETURN_ON_ERROR(err, s_tag, "enum: dev desc");
  if (rx != (uint16_t)k_ra8_hmsc_dev_desc_len) {
    return k_ra8_err_hw_error;
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_enum_hunt(uint8_t* desc, uint8_t* out_addr)
{
  ra8_delay_ms(k_ra8_hmsc_vbus_settle_ms);
  const uint32_t t0 = ra8_time_ms();
  for (uint32_t spin = 0U; spin < (uint32_t)k_ra8_hmsc_attach_spin_limit; spin++) {
    if (ra8_usb_host_line_state(g_usb_hmsc_state.speed) != 0U) {
      break;
    }
    if ((ra8_time_ms() - t0) > (uint32_t)k_ra8_hmsc_attach_to_ms) {
      break;
    }
  }
  ra8_delay_ms(k_ra8_hmsc_debounce_ms);
  ra8_err_t err = k_ra8_err_hw_timeout;
  for (uint8_t attempt = 0U; attempt < (uint8_t)k_ra8_hmsc_enum_tries; attempt++) {
    if (attempt >= (uint8_t)k_ra8_hmsc_no_reset_tries) {
      (void)ra8_usb_host_bus_reset(g_usb_hmsc_state.speed, true);
      ra8_delay_ms(k_ra8_hmsc_reset_hold_ms);
      (void)ra8_usb_host_bus_reset(g_usb_hmsc_state.speed, false);
    }
    (void)ra8_usb_host_set_uact(g_usb_hmsc_state.speed, true);
    ra8_delay_ms(k_ra8_hmsc_recovery_ms);
    const uint8_t addr = (uint8_t)(attempt & (uint8_t)k_ra8_hmsc_addr_alt_mask);
    (void)ra8_usb_host_set_target(g_usb_hmsc_state.speed, addr);
    err = internal_enum_read_dev_desc(desc);
    if (err == k_ra8_ok) {
      *out_addr = addr;
      return k_ra8_ok;
    }
  }
  return err;
}

RA8_INTERNAL
static ra8_err_t internal_enum_assign_addr(uint8_t* dev_addr)
{
  if (*dev_addr != 0U) {
    return k_ra8_ok;
  }
  const ra8_usb_setup_t setup = {
    .bm_request_type = k_ra8_hmsc_bm_std_dev_out,
    .b_request       = k_ra8_hmsc_breq_set_address,
    .w_value         = k_ra8_hmsc_assigned_address,
    .w_index         = 0U,
    .w_length        = 0U,
  };
  ra8_err_t err = ra8_usb_host_control_xfer(g_usb_hmsc_state.speed, &setup, nullptr, 0U, nullptr);
  RA8_RETURN_ON_ERROR(err, s_tag, "enum: set address");
  ra8_delay_ms(k_ra8_hmsc_addr_settle_ms);
  err = ra8_usb_host_set_target(g_usb_hmsc_state.speed, (uint8_t)k_ra8_hmsc_assigned_address);
  RA8_RETURN_ON_ERROR(err, s_tag, "enum: set target");
  *dev_addr = (uint8_t)k_ra8_hmsc_assigned_address;
  return k_ra8_ok;
}

RA8_INTERNAL
static void internal_enum_note_endpoint(const uint8_t* d)
{
  const uint8_t attr = (uint8_t)(d[k_ra8_hmsc_off_ep_attr] & (uint8_t)k_ra8_hmsc_ep_attr_mask);
  if (attr != (uint8_t)k_ra8_hmsc_ep_attr_bulk) {
    return;
  }
  const uint8_t  ea = d[k_ra8_hmsc_off_ep_addr];
  const uint16_t mps =
    (uint16_t)((uint16_t)d[k_ra8_hmsc_off_ep_mps] |
               (uint16_t)((uint16_t)d[k_ra8_hmsc_off_ep_mps + 1U] << k_ra8_hmsc_byte_bits));
  if ((ea & (uint8_t)k_ra8_hmsc_ep_dir_in_bit) != 0U) {
    if (g_usb_hmsc_state.device.bulk_in_ep == 0U) {
      g_usb_hmsc_state.device.bulk_in_ep         = (uint8_t)(ea & (uint8_t)k_ra8_hmsc_ep_num_mask);
      g_usb_hmsc_state.device.bulk_in_max_packet = mps;
    }
  } else {
    if (g_usb_hmsc_state.device.bulk_out_ep == 0U) {
      g_usb_hmsc_state.device.bulk_out_ep         = (uint8_t)(ea & (uint8_t)k_ra8_hmsc_ep_num_mask);
      g_usb_hmsc_state.device.bulk_out_max_packet = mps;
    }
  }
}

RA8_INTERNAL
static bool internal_enum_iface_is_msc(const uint8_t* d)
{
  if (d[k_ra8_hmsc_off_iface_class] != (uint8_t)k_ra8_hmsc_class_msc) {
    return false;
  }
  if (d[k_ra8_hmsc_off_iface_sub] != (uint8_t)k_ra8_hmsc_subclass_scsi) {
    return false;
  }
  if (d[k_ra8_hmsc_off_iface_proto] != (uint8_t)k_ra8_hmsc_protocol_bbb) {
    return false;
  }
  return true;
}

RA8_INTERNAL
static ra8_err_t internal_enum_walk_cfg(const uint8_t* cfg, uint16_t len)
{
  uint16_t off    = 0U;
  bool     in_msc = false;
  while (off < len) {
    const uint8_t dlen = cfg[off + (uint16_t)k_ra8_hmsc_off_dlen];
    if (dlen == 0U) {
      break;
    }
    const uint8_t dtype = cfg[off + (uint16_t)k_ra8_hmsc_off_dtype];
    if (dtype == (uint8_t)k_ra8_hmsc_desc_interface) {
      in_msc = internal_enum_iface_is_msc(&cfg[off]);
      if (in_msc) {
        g_usb_hmsc_state.device.interface_number = cfg[off + (uint16_t)k_ra8_hmsc_off_iface_num];
      }
    }
    if (dtype == (uint8_t)k_ra8_hmsc_desc_endpoint) {
      if (in_msc) {
        internal_enum_note_endpoint(&cfg[off]);
      }
    }
    off = (uint16_t)(off + dlen);
  }
  if (g_usb_hmsc_state.device.bulk_in_ep == 0U) {
    return k_ra8_err_hw_error;
  }
  if (g_usb_hmsc_state.device.bulk_out_ep == 0U) {
    return k_ra8_err_hw_error;
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_enum_read_config(uint8_t* out_cfg_value)
{
  uint8_t         cfg[k_ra8_hmsc_cfg_buf_len] = {};
  uint16_t        rx                          = 0U;
  ra8_usb_setup_t setup                       = {
    .bm_request_type = k_ra8_hmsc_bm_std_dev_in,
    .b_request       = k_ra8_hmsc_breq_get_descriptor,
    .w_value         = (uint16_t)((uint16_t)k_ra8_hmsc_desc_configuration << k_ra8_hmsc_byte_bits),
    .w_index         = 0U,
    .w_length        = k_ra8_hmsc_cfg_desc_len,
  };
  ra8_err_t err = ra8_usb_host_control_xfer(g_usb_hmsc_state.speed,
                                            &setup,
                                            cfg,
                                            (uint16_t)k_ra8_hmsc_cfg_desc_len,
                                            &rx);
  RA8_RETURN_ON_ERROR(err, s_tag, "enum: cfg header");
  uint16_t total =
    (uint16_t)((uint16_t)cfg[k_ra8_hmsc_off_cfg_total] |
               (uint16_t)((uint16_t)cfg[k_ra8_hmsc_off_cfg_total + 1U] << k_ra8_hmsc_byte_bits));
  if (total > (uint16_t)k_ra8_hmsc_cfg_buf_len) {
    total = (uint16_t)k_ra8_hmsc_cfg_buf_len;
  }
  *out_cfg_value = cfg[k_ra8_hmsc_off_cfg_value];
  setup.w_length = total;
  err            = ra8_usb_host_control_xfer(g_usb_hmsc_state.speed, &setup, cfg, total, &rx);
  RA8_RETURN_ON_ERROR(err, s_tag, "enum: cfg full");
  return internal_enum_walk_cfg(cfg, rx);
}

RA8_INTERNAL
static ra8_err_t internal_enum_configure(uint8_t dev_addr, uint8_t cfg_value)
{
  const ra8_usb_setup_t set_cfg = {
    .bm_request_type = k_ra8_hmsc_bm_std_dev_out,
    .b_request       = k_ra8_hmsc_breq_set_config,
    .w_value         = cfg_value,
    .w_index         = 0U,
    .w_length        = 0U,
  };
  ra8_err_t err = ra8_usb_host_control_xfer(g_usb_hmsc_state.speed, &set_cfg, nullptr, 0U, nullptr);
  RA8_RETURN_ON_ERROR(err, s_tag, "enum: set config");
  const ra8_usb_setup_t get_lun = {
    .bm_request_type = k_ra8_hmsc_bm_class_iface_in,
    .b_request       = k_ra8_hmsc_req_get_max_lun,
    .w_value         = 0U,
    .w_index         = g_usb_hmsc_state.device.interface_number,
    .w_length        = k_ra8_hmsc_get_max_lun_len,
  };
  uint8_t         lun             = 0U;
  uint16_t        lun_rx          = 0U;
  const ra8_err_t lun_err         = ra8_usb_host_control_xfer(g_usb_hmsc_state.speed,
                                                              &get_lun,
                                                              &lun,
                                                              (uint16_t)k_ra8_hmsc_get_max_lun_len,
                                                              &lun_rx);
  g_usb_hmsc_state.device.max_lun = 0U;
  if (lun_err == k_ra8_ok) {
    if (lun_rx == (uint16_t)k_ra8_hmsc_get_max_lun_len) {
      g_usb_hmsc_state.device.max_lun = lun;
    }
  }
  err = ra8_usb_host_pipe_setup(g_usb_hmsc_state.speed,
                                k_ra8_hmsc_pipe_bulk_in,
                                dev_addr,
                                g_usb_hmsc_state.device.bulk_in_ep,
                                true,
                                g_usb_hmsc_state.device.bulk_in_max_packet);
  RA8_RETURN_ON_ERROR(err, s_tag, "enum: pipe in");
  return ra8_usb_host_pipe_setup(g_usb_hmsc_state.speed,
                                 k_ra8_hmsc_pipe_bulk_out,
                                 dev_addr,
                                 g_usb_hmsc_state.device.bulk_out_ep,
                                 false,
                                 g_usb_hmsc_state.device.bulk_out_max_packet);
}

RA8_INTERNAL
static void internal_enum_fill_ids(const uint8_t* desc)
{
  g_usb_hmsc_state.device.vendor_id =
    (uint16_t)((uint16_t)desc[k_ra8_hmsc_off_dev_vid] |
               (uint16_t)((uint16_t)desc[k_ra8_hmsc_off_dev_vid + 1U] << k_ra8_hmsc_byte_bits));
  g_usb_hmsc_state.device.product_id =
    (uint16_t)((uint16_t)desc[k_ra8_hmsc_off_dev_pid] |
               (uint16_t)((uint16_t)desc[k_ra8_hmsc_off_dev_pid + 1U] << k_ra8_hmsc_byte_bits));
}

RA8_INTERNAL
static void internal_enum_publish(uint8_t dev_addr, ra8_usb_hmsc_device_t* out_device)
{
  g_usb_hmsc_state.device.device_address = dev_addr;
  g_usb_hmsc_state.attached              = true;
  if (g_usb_hmsc_state.attach_cb != nullptr) {
    g_usb_hmsc_state.attach_cb(g_usb_hmsc_state.attach_ctx, &g_usb_hmsc_state.device);
  }
  if (out_device != nullptr) {
    *out_device = g_usb_hmsc_state.device;
  }
}

RA8_INTERNAL
static ra8_err_t internal_enum_ladder(uint8_t* out_addr)
{
  uint8_t   desc[k_ra8_hmsc_dev_desc_len] = {};
  ra8_err_t err                           = internal_enum_hunt(desc, out_addr);
  RA8_RETURN_ON_ERROR(err, s_tag, "enumerate: hunt");
  internal_enum_fill_ids(desc);
 
  err = internal_enum_assign_addr(out_addr);
  RA8_RETURN_ON_ERROR(err, s_tag, "enumerate: address");
  uint8_t cfg_value = 0U;
  err               = internal_enum_read_config(&cfg_value);
  RA8_RETURN_ON_ERROR(err, s_tag, "enumerate: config");
  err = internal_enum_configure(*out_addr, cfg_value);
  RA8_RETURN_ON_ERROR(err, s_tag, "enumerate: configure");
  return k_ra8_ok;
}

ra8_err_t ra8_usb_hmsc_enumerate(ra8_usb_hmsc_device_t* out_device)
{
  if (!g_usb_hmsc_state.initialized) {
    return k_ra8_err_invalid_state;
  }
  g_usb_hmsc_state.attached = false;
  g_usb_hmsc_state.device   = (ra8_usb_hmsc_device_t){};
 
  uint8_t         dev_addr = 0U;
  const ra8_err_t err      = internal_enum_ladder(&dev_addr);
  if (err != k_ra8_ok) {
    return err;
  }
  internal_enum_publish(dev_addr, out_device);
  return k_ra8_ok;
}