ra8_usb_pmsc.c

Go to the documentation of this file.

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

typedef enum : uint8_t {
  k_ra8_pmsc_cbw_off_signature   = 0U,  
  k_ra8_pmsc_cbw_off_tag         = 4U,  
  k_ra8_pmsc_cbw_off_data_length = 8U,  
  k_ra8_pmsc_cbw_off_flags       = 12U, 
  k_ra8_pmsc_cbw_off_lun         = 13U, 
  k_ra8_pmsc_cbw_off_cdb_length  = 14U, 
  k_ra8_pmsc_cbw_off_cdb         = 15U, 
} ra8_usb_pmsc_cbw_offset_t;

typedef enum : uint8_t {
  k_ra8_pmsc_csw_off_signature = 0U,  
  k_ra8_pmsc_csw_off_tag       = 4U,  
  k_ra8_pmsc_csw_off_residue   = 8U,  
  k_ra8_pmsc_csw_off_status    = 12U, 
} ra8_usb_pmsc_csw_offset_t;

typedef enum : uint8_t {
  k_ra8_pmsc_cbw_flag_data_out = 0x00U, 
  k_ra8_pmsc_cbw_flag_data_in  = 0x80U, 
} ra8_usb_pmsc_cbw_flag_t;

typedef enum : uint32_t {
  k_ra8_pmsc_cbw_signature = 0x43425355U, 
  k_ra8_pmsc_csw_signature = 0x53425355U, 
} ra8_usb_pmsc_signature_t;

typedef enum : uint32_t {
  k_ra8_pmsc_initial_tag = 0U, 
} ra8_usb_pmsc_initial_tag_t;

typedef enum : uint8_t {
  k_ra8_pmsc_lun_field_mask = 0x0FU, 
  k_ra8_pmsc_cdb_field_mask = 0x1FU, 
} ra8_usb_pmsc_lun_mask_t;
 
/* =============================================================================
 * Internal state
 * =============================================================================
 */
 
ra8_usb_pmsc_state_data_t g_usb_pmsc_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_pmsc_bulk_max_packet_hs
                                       : k_ra8_pmsc_bulk_max_packet_fs;
}

RA8_INTERNAL
static void internal_configure_pipes(void)
{
  const uint16_t bulk_mp = internal_bulk_max_packet(g_usb_pmsc_state.speed);
 
  /* Both calls receive the init-validated speed and compile-time pipe tuples
   * that satisfy every `ra8_usb_configure_endpoint` argument guard. */
  (void)ra8_usb_configure_endpoint(g_usb_pmsc_state.speed,
                                   k_ra8_pmsc_pipe_bulk_in,
                                   k_ra8_pmsc_ep_bulk_in,
                                   k_ra8_usb_ep_dir_in,
                                   k_ra8_usb_ep_type_bulk,
                                   bulk_mp);
  (void)ra8_usb_configure_endpoint(g_usb_pmsc_state.speed,
                                   k_ra8_pmsc_pipe_bulk_out,
                                   k_ra8_pmsc_ep_bulk_out,
                                   k_ra8_usb_ep_dir_out,
                                   k_ra8_usb_ep_type_bulk,
                                   bulk_mp);
}

RA8_INTERNAL
static void internal_pack_u32_le(uint32_t value, uint8_t* dst)
{
  dst[0] = (uint8_t)((value >> k_ra8_pmsc_shift_byte0) & k_ra8_pmsc_byte_mask);
  dst[1] = (uint8_t)((value >> k_ra8_pmsc_shift_byte1) & k_ra8_pmsc_byte_mask);
  dst[2] = (uint8_t)((value >> k_ra8_pmsc_shift_byte2) & k_ra8_pmsc_byte_mask);
  dst[3] = (uint8_t)((value >> k_ra8_pmsc_shift_byte3) & k_ra8_pmsc_byte_mask);
}

RA8_INTERNAL
static uint32_t internal_unpack_u32_le(const uint8_t* src)
{
  return ((uint32_t)src[0] << k_ra8_pmsc_shift_byte0) |
         ((uint32_t)src[1] << k_ra8_pmsc_shift_byte1) |
         ((uint32_t)src[2] << k_ra8_pmsc_shift_byte2) |
         ((uint32_t)src[3] << k_ra8_pmsc_shift_byte3);
}
 
void priv_zero_bytes(uint8_t* dst, uint32_t len)
{
  for (uint32_t i = 0U; i < len; ++i) {
    dst[i] = 0U;
  }
}

RA8_INTERNAL
static void internal_copy_bytes(uint8_t* dst, const uint8_t* src, uint32_t len)
{
  for (uint32_t i = 0U; i < len; ++i) {
    dst[i] = src[i];
  }
}
 
/* =============================================================================
 * BOT state machine -- public entry points
 * =============================================================================
 */
 
ra8_err_t ra8_usb_pmsc_feed_cbw(const uint8_t* cbw)
{
  RA8_CHECK_NULL_PTR(cbw, s_tag, "feed_cbw: cbw");
  if (!g_usb_pmsc_state.initialized) {
    return k_ra8_err_invalid_state;
  }
  if (!g_usb_pmsc_state.storage_attached) {
    return k_ra8_err_invalid_state;
  }
 
  /* USB MSC BBB rev 1.0 sec 6.2.1 "Valid CBW" -- signature must be
   * 'USBC' little-endian. */
  const uint32_t signature = internal_unpack_u32_le(&cbw[k_ra8_pmsc_cbw_off_signature]);
  if (signature != k_ra8_pmsc_cbw_signature) {
    /* Spec sec 6.6.1 "CBW Not Valid": stall both bulk pipes and
     * await reset recovery. The starter surfaces this as a CSW
     * with status `phase_error` so the caller's state machine can
     * proceed deterministically. */
    g_usb_pmsc_state.bot_state = k_ra8_pmsc_state_csw_tx;
    g_usb_pmsc_state.cbw_tag   = internal_unpack_u32_le(&cbw[k_ra8_pmsc_cbw_off_tag]);
    return k_ra8_err_invalid_arg;
  }
 
  g_usb_pmsc_state.cbw_tag         = internal_unpack_u32_le(&cbw[k_ra8_pmsc_cbw_off_tag]);
  g_usb_pmsc_state.cbw_data_length = internal_unpack_u32_le(&cbw[k_ra8_pmsc_cbw_off_data_length]);
  g_usb_pmsc_state.cbw_dir_in = (cbw[k_ra8_pmsc_cbw_off_flags] & k_ra8_pmsc_cbw_flag_data_in) != 0U;
  g_usb_pmsc_state.cbw_lun    = (uint8_t)(cbw[k_ra8_pmsc_cbw_off_lun] & k_ra8_pmsc_lun_field_mask);
  g_usb_pmsc_state.cbw_cdb_len =
    (uint8_t)(cbw[k_ra8_pmsc_cbw_off_cdb_length] & k_ra8_pmsc_cdb_field_mask);
  internal_copy_bytes(g_usb_pmsc_state.cbw_cdb,
                      &cbw[k_ra8_pmsc_cbw_off_cdb],
                      (uint32_t)k_ra8_pmsc_cdb_max_len);
  g_usb_pmsc_state.bot_state     = k_ra8_pmsc_state_cdb_decode;
  g_usb_pmsc_state.last_data_len = 0U;
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_dispatch_scsi(uint8_t*                   data_buf,
                                        uint32_t                   data_buf_capacity,
                                        uint32_t*                  data_len,
                                        ra8_usb_pmsc_csw_status_t* csw_status)
{
  const uint8_t opcode = g_usb_pmsc_state.cbw_cdb[k_ra8_pmsc_cdb_off_opcode];
  switch (opcode) {
    case k_ra8_pmsc_scsi_test_unit_ready:
      /* Passing -- no data phase. */
      return k_ra8_ok;
    case k_ra8_pmsc_scsi_inquiry:
      return priv_handle_inquiry(data_buf, data_buf_capacity, data_len);
    case k_ra8_pmsc_scsi_read_capacity_10:
      return priv_handle_read_capacity(data_buf, data_buf_capacity, data_len);
    case k_ra8_pmsc_scsi_request_sense:
      return priv_handle_request_sense(data_buf, data_buf_capacity, data_len);
    case k_ra8_pmsc_scsi_mode_sense_6:
      return priv_handle_mode_sense(data_buf, data_buf_capacity, data_len);
    case k_ra8_pmsc_scsi_read_10:
      return priv_handle_read10(data_buf, data_buf_capacity, data_len);
    case k_ra8_pmsc_scsi_write_10:
      return priv_handle_write10(data_buf, data_len);
    default:
      /* Unsupported opcode -> CSW status FAILED, no data. */
      *csw_status = k_ra8_pmsc_csw_status_failed;
      return k_ra8_ok;
  }
}

RA8_INTERNAL
static ra8_err_t internal_dispatch_preconditions(uint32_t data_buf_capacity)
{
  if (!g_usb_pmsc_state.initialized) {
    return k_ra8_err_invalid_state;
  }
  if (!g_usb_pmsc_state.storage_attached) {
    return k_ra8_err_invalid_state;
  }
  if (g_usb_pmsc_state.bot_state != k_ra8_pmsc_state_cdb_decode) {
    return k_ra8_err_invalid_state;
  }
  if (data_buf_capacity == 0U) {
    return k_ra8_err_invalid_size;
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static void internal_dispatch_advance_state(uint32_t data_len)
{
  g_usb_pmsc_state.last_data_len = data_len;
  if (data_len > 0U) {
    g_usb_pmsc_state.bot_state =
      g_usb_pmsc_state.cbw_dir_in ? k_ra8_pmsc_state_data_tx : k_ra8_pmsc_state_data_rx;
  } else {
    g_usb_pmsc_state.bot_state = k_ra8_pmsc_state_csw_tx;
  }
}
 
ra8_err_t ra8_usb_pmsc_dispatch_command(uint8_t*                   data_buf,
                                        uint32_t                   data_buf_capacity,
                                        uint32_t*                  data_len,
                                        ra8_usb_pmsc_csw_status_t* csw_status)
{
  RA8_CHECK_NULL_PTR(data_buf, s_tag, "dispatch: data_buf");
  RA8_CHECK_NULL_PTR(data_len, s_tag, "dispatch: data_len");
  RA8_CHECK_NULL_PTR(csw_status, s_tag, "dispatch: csw_status");
  const ra8_err_t pre_err = internal_dispatch_preconditions(data_buf_capacity);
  if (pre_err != k_ra8_ok) {
    return pre_err;
  }
 
  *data_len           = 0U;
  *csw_status         = k_ra8_pmsc_csw_status_passed;
  const ra8_err_t err = internal_dispatch_scsi(data_buf, data_buf_capacity, data_len, csw_status);
  if (err != k_ra8_ok) {
    *csw_status = k_ra8_pmsc_csw_status_failed;
    *data_len   = 0U;
  }
  internal_dispatch_advance_state(*data_len);
  return k_ra8_ok;
}
 
ra8_err_t
ra8_usb_pmsc_build_csw(ra8_usb_pmsc_csw_status_t csw_status, uint32_t residue, uint8_t* out_csw)
{
  RA8_CHECK_NULL_PTR(out_csw, s_tag, "build_csw: out_csw");
  if (!g_usb_pmsc_state.initialized) {
    return k_ra8_err_invalid_state;
  }
 
  priv_zero_bytes(out_csw, (uint32_t)k_ra8_pmsc_csw_len);
  internal_pack_u32_le(k_ra8_pmsc_csw_signature, &out_csw[k_ra8_pmsc_csw_off_signature]);
  internal_pack_u32_le(g_usb_pmsc_state.cbw_tag, &out_csw[k_ra8_pmsc_csw_off_tag]);
  internal_pack_u32_le(residue, &out_csw[k_ra8_pmsc_csw_off_residue]);
  out_csw[k_ra8_pmsc_csw_off_status] = (uint8_t)csw_status;
  g_usb_pmsc_state.bot_state         = k_ra8_pmsc_state_idle;
  return k_ra8_ok;
}
 
ra8_err_t ra8_usb_pmsc_step(void)
{
  if (!g_usb_pmsc_state.initialized) {
    return k_ra8_err_invalid_state;
  }
  if (!g_usb_pmsc_state.storage_attached) {
    return k_ra8_err_invalid_state;
  }
 
  /* Each invocation advances by exactly one phase. The IDLE phase
   * is observable through the public state; in production the
   * caller pumps `step` from the bulk-OUT-completion ISR until the
   * machine returns to IDLE waiting for the next CBW. The CBW_RX
   * and CDB_DECODE phases are caller-driven: the application drains
   * the bulk-OUT FIFO and invokes `ra8_usb_pmsc_feed_cbw` /
   * `ra8_usb_pmsc_dispatch_command` directly, so `step` leaves
   * those phases untouched. */
  switch (g_usb_pmsc_state.bot_state) {
    case k_ra8_pmsc_state_idle:
      /* Awaiting CBW. */
      g_usb_pmsc_state.bot_state = k_ra8_pmsc_state_cbw_rx;
      break;
    case k_ra8_pmsc_state_cbw_rx:
    case k_ra8_pmsc_state_cdb_decode:
      /* Caller drives the CBW capture / CDB dispatch directly. */
      break;
    case k_ra8_pmsc_state_data_tx:
    case k_ra8_pmsc_state_data_rx:
      /* Caller pushes / pulls the data phase; transition to CSW. */
      g_usb_pmsc_state.bot_state = k_ra8_pmsc_state_csw_tx;
      break;
    case k_ra8_pmsc_state_csw_tx:
    default:
      /* CSW sent (or unknown state); rewind to IDLE. */
      g_usb_pmsc_state.bot_state = k_ra8_pmsc_state_idle;
      break;
  }
  return k_ra8_ok;
}
 
/* =============================================================================
 * Storage backend
 * =============================================================================
 */
 
ra8_err_t ra8_usb_pmsc_attach_storage(const ra8_usb_pmsc_storage_t* storage)
{
  if (!g_usb_pmsc_state.initialized) {
    return k_ra8_err_invalid_state;
  }
  RA8_CHECK_NULL_PTR(storage, s_tag, "attach_storage: storage");
  RA8_CHECK_NULL_PTR(storage->read_block, s_tag, "attach_storage: read_block");
  RA8_CHECK_NULL_PTR(storage->write_block, s_tag, "attach_storage: write_block");
  RA8_CHECK_NULL_PTR(storage->get_capacity, s_tag, "attach_storage: get_capacity");
  RA8_CHECK_NULL_PTR(storage->get_inquiry, s_tag, "attach_storage: get_inquiry");
 
  g_usb_pmsc_state.storage          = *storage;
  g_usb_pmsc_state.storage_attached = true;
  g_usb_pmsc_state.bot_state        = k_ra8_pmsc_state_idle;
  ra8_log_info(s_tag, "storage attached");
  return k_ra8_ok;
}
 
/* =============================================================================
 * Lifecycle
 * =============================================================================
 */
 
ra8_err_t ra8_usb_pmsc_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_device_init(speed);
  if (usb_err != k_ra8_ok) {
    ra8_log_error_val(s_tag, "ra8_usb_device_init failed", (uint32_t)usb_err);
    return k_ra8_err_hw_init_failed;
  }
 
  g_usb_pmsc_state.speed            = speed;
  g_usb_pmsc_state.bot_state        = k_ra8_pmsc_state_idle;
  g_usb_pmsc_state.storage_attached = false;
  g_usb_pmsc_state.storage          = (ra8_usb_pmsc_storage_t){};
  g_usb_pmsc_state.cbw_tag          = k_ra8_pmsc_initial_tag;
  g_usb_pmsc_state.cbw_data_length  = 0U;
  g_usb_pmsc_state.cbw_dir_in       = false;
  g_usb_pmsc_state.cbw_lun          = 0U;
  g_usb_pmsc_state.cbw_cdb_len      = 0U;
  g_usb_pmsc_state.last_data_len    = 0U;
  priv_zero_bytes(g_usb_pmsc_state.cbw_cdb, (uint32_t)k_ra8_pmsc_cdb_max_len);
  g_usb_pmsc_state.initialized = true;
 
  internal_configure_pipes();
 
  ra8_log_info_val(s_tag, "device-MSC ready", (uint32_t)speed);
  return k_ra8_ok;
}
 
ra8_err_t ra8_usb_pmsc_close(void)
{
  if (!g_usb_pmsc_state.initialized) {
    return k_ra8_err_invalid_state;
  }
  /* Drop D+ pull-up so the host sees a clean detach. */
  (void)ra8_usb_device_attach(g_usb_pmsc_state.speed, false);
  const ra8_err_t err               = ra8_usb_device_deinit(g_usb_pmsc_state.speed);
  g_usb_pmsc_state.initialized      = false;
  g_usb_pmsc_state.storage_attached = false;
  g_usb_pmsc_state.bot_state        = k_ra8_pmsc_state_idle;
  return err;
}