ra8_usb_hmsc.c

Go to the documentation of this file.

 
#include "ra8_usb_hmsc.h"
 
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_hal_internal.h"
#include "ra8_log.h"
#include "ra8_time.h"
#include "ra8_usb.h"
#include "ra8_usb_hmsc_internal.h"
 
static const char* s_tag = "USBHMSC";
 
/* =============================================================================
 * Internal constants
 * =============================================================================
 */

typedef enum : uint8_t {
  k_ra8_hmsc_cbw_off_signature   = 0U,  
  k_ra8_hmsc_cbw_off_tag         = 4U,  
  k_ra8_hmsc_cbw_off_data_length = 8U,  
  k_ra8_hmsc_cbw_off_flags       = 12U, 
  k_ra8_hmsc_cbw_off_lun         = 13U, 
  k_ra8_hmsc_cbw_off_cdb_length  = 14U, 
  k_ra8_hmsc_cbw_off_cdb         = 15U, 
} ra8_usb_hmsc_cbw_offset_t;

typedef enum : uint8_t {
  k_ra8_hmsc_csw_off_signature = 0U,  
  k_ra8_hmsc_csw_off_tag       = 4U,  
  k_ra8_hmsc_csw_off_residue   = 8U,  
  k_ra8_hmsc_csw_off_status    = 12U, 
} ra8_usb_hmsc_csw_offset_t;

typedef enum : uint8_t {
  k_ra8_hmsc_cbw_flag_data_out = 0x00U, 
  k_ra8_hmsc_cbw_flag_data_in  = 0x80U, 
} ra8_usb_hmsc_cbw_flag_t;

typedef enum : uint32_t {
  k_ra8_hmsc_cbw_signature = 0x43425355U, 
  k_ra8_hmsc_csw_signature = 0x53425355U, 
} ra8_usb_hmsc_signature_t;

typedef enum : uint8_t {
  k_ra8_hmsc_shift_byte0 = 0U,  
  k_ra8_hmsc_shift_byte1 = 8U,  
  k_ra8_hmsc_shift_byte2 = 16U, 
  k_ra8_hmsc_shift_byte3 = 24U, 
} ra8_usb_hmsc_byte_shift_t;

typedef enum : uint32_t {
  k_ra8_hmsc_byte_mask = 0xFFU, 
} ra8_usb_hmsc_byte_mask_t;

typedef enum : uint8_t {
  k_ra8_hmsc_cdb_off_opcode    = 0U, 
  k_ra8_hmsc_cdb_off_lba_msb   = 2U, 
  k_ra8_hmsc_cdb_off_lba_b1    = 3U, 
  k_ra8_hmsc_cdb_off_lba_b2    = 4U, 
  k_ra8_hmsc_cdb_off_lba_lsb   = 5U, 
  k_ra8_hmsc_cdb_off_cnt_msb   = 7U, 
  k_ra8_hmsc_cdb_off_cnt_lsb   = 8U, 
  k_ra8_hmsc_cdb_off_inq_alloc = 4U, 
} ra8_usb_hmsc_cdb_offset_t;

typedef enum : uint8_t {
  k_ra8_hmsc_lun_field_mask = 0x0FU, 
  k_ra8_hmsc_cdb_field_mask = 0x1FU, 
} ra8_usb_hmsc_lun_mask_t;

typedef enum : uint32_t {
  k_ra8_hmsc_initial_tag = 1U, 
} ra8_usb_hmsc_initial_tag_t;

typedef enum : uint8_t {
  k_ra8_hmsc_inq_qual_shift      = 5U,    
  k_ra8_hmsc_inq_dev_type_mask   = 0x1FU, 
  k_ra8_hmsc_inq_removable_shift = 7U,    
  k_ra8_hmsc_inq_removable_mask  = 1U,    
} ra8_usb_hmsc_inquiry_field_t;

typedef enum : uint8_t {
  k_ra8_hmsc_inq_off_dev_type    = 0U,  
  k_ra8_hmsc_inq_off_removable   = 1U,  
  k_ra8_hmsc_inq_off_version     = 2U,  
  k_ra8_hmsc_inq_off_vendor_id   = 8U,  
  k_ra8_hmsc_inq_off_product_id  = 16U, 
  k_ra8_hmsc_inq_off_product_rev = 32U, 
} ra8_usb_hmsc_inquiry_offset_t;

typedef enum : uint8_t {
  k_ra8_hmsc_cap_off_last_lba = 0U, 
  k_ra8_hmsc_cap_off_blk_size = 4U, 
} ra8_usb_hmsc_capacity_offset_t;
 
/* =============================================================================
 * Internal state
 * =============================================================================
 */
 
/* Singleton shadow state. Shared with ra8_usb_hmsc_enum.c (the polled
 * enumeration ladder) through ra8_hal_internal.h: the type and the extern
 * declaration live there, the single definition lives here. */
ra8_usb_hmsc_state_t g_usb_hmsc_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_hmsc_bulk_max_packet_hs
                                       : k_ra8_hmsc_bulk_max_packet_fs;
}

RA8_INTERNAL
static uint32_t internal_next_tag(void)
{
  const uint32_t tag = g_usb_hmsc_state.next_cbw_tag;
  ++g_usb_hmsc_state.next_cbw_tag;
  return tag;
}
 
/* Pack a uint32 into 4 little-endian bytes -- see surrounding code and HUM citations. */
RA8_INTERNAL
static void internal_pack_u32_le(uint32_t value, uint8_t* dst)
{
  dst[0] = (uint8_t)((value >> k_ra8_hmsc_shift_byte0) & k_ra8_hmsc_byte_mask);
  dst[1] = (uint8_t)((value >> k_ra8_hmsc_shift_byte1) & k_ra8_hmsc_byte_mask);
  dst[2] = (uint8_t)((value >> k_ra8_hmsc_shift_byte2) & k_ra8_hmsc_byte_mask);
  dst[3] = (uint8_t)((value >> k_ra8_hmsc_shift_byte3) & k_ra8_hmsc_byte_mask);
}
 
/* Unpack a uint32 from 4 little-endian bytes -- see surrounding code and HUM citations. */
RA8_INTERNAL
static uint32_t internal_unpack_u32_le(const uint8_t* src)
{
  return ((uint32_t)src[0] << k_ra8_hmsc_shift_byte0) |
         ((uint32_t)src[1] << k_ra8_hmsc_shift_byte1) |
         ((uint32_t)src[2] << k_ra8_hmsc_shift_byte2) |
         ((uint32_t)src[3] << k_ra8_hmsc_shift_byte3);
}

RA8_INTERNAL
static uint32_t internal_unpack_u32_be(const uint8_t* src)
{
  return ((uint32_t)src[0] << k_ra8_hmsc_shift_byte3) |
         ((uint32_t)src[1] << k_ra8_hmsc_shift_byte2) |
         ((uint32_t)src[2] << k_ra8_hmsc_shift_byte1) |
         ((uint32_t)src[3] << k_ra8_hmsc_shift_byte0);
}

RA8_INTERNAL
static void internal_zero_bytes(uint8_t* dst, uint16_t len)
{
  for (uint16_t i = 0U; i < len; ++i) {
    dst[i] = 0U;
  }
}
 
/* Copy `len` bytes from `src` to `dst` byte-by-byte -- see surrounding code and HUM citations. */
RA8_INTERNAL
static void internal_copy_bytes(uint8_t* dst, const uint8_t* src, uint16_t len)
{
  for (uint16_t i = 0U; i < len; ++i) {
    dst[i] = src[i];
  }
}
 
/* =============================================================================
 * Public CBW / CSW helpers (also used as test introspection)
 * =============================================================================
 */
 
ra8_err_t ra8_usb_hmsc_build_cbw(uint8_t        target_lun,
                                 uint32_t       data_transfer_length,
                                 bool           data_in,
                                 const uint8_t* cdb,
                                 uint8_t        cdb_len,
                                 uint8_t*       out_cbw)
{
  RA8_CHECK_NULL_PTR(cdb, s_tag, "build_cbw: cdb");
  RA8_CHECK_NULL_PTR(out_cbw, s_tag, "build_cbw: out_cbw");
  if (target_lun > k_ra8_hmsc_lun_field_mask) {
    return k_ra8_err_invalid_arg;
  }
  if ((cdb_len == 0U) || (cdb_len > k_ra8_hmsc_cdb_max_len)) {
    return k_ra8_err_invalid_arg;
  }
 
  /* Zero the entire CBW so reserved nibbles stay 0 -- USB MSC BBB
   * rev 1.0 sec 5.1 requires zero in the high nibble of bCBWLUN /
   * the high 3 bits of bCBWCBLength. */
  internal_zero_bytes(out_cbw, k_ra8_hmsc_cbw_len);
 
  /* dCBWSignature = 'USBC' little-endian. */
  internal_pack_u32_le(k_ra8_hmsc_cbw_signature, &out_cbw[k_ra8_hmsc_cbw_off_signature]);
 
  /* dCBWTag = monotonic. */
  const uint32_t tag = internal_next_tag();
  internal_pack_u32_le(tag, &out_cbw[k_ra8_hmsc_cbw_off_tag]);
 
  /* dCBWDataTransferLength. */
  internal_pack_u32_le(data_transfer_length, &out_cbw[k_ra8_hmsc_cbw_off_data_length]);
 
  /* bmCBWFlags. */
  out_cbw[k_ra8_hmsc_cbw_off_flags] =
    data_in ? k_ra8_hmsc_cbw_flag_data_in : k_ra8_hmsc_cbw_flag_data_out;
 
  /* bCBWLUN (low 4 bits) / bCBWCBLength (low 5 bits). */
  out_cbw[k_ra8_hmsc_cbw_off_lun]        = (uint8_t)(target_lun & k_ra8_hmsc_lun_field_mask);
  out_cbw[k_ra8_hmsc_cbw_off_cdb_length] = (uint8_t)(cdb_len & k_ra8_hmsc_cdb_field_mask);
 
  /* CBWCB[16]. */
  internal_copy_bytes(&out_cbw[k_ra8_hmsc_cbw_off_cdb], cdb, (uint16_t)cdb_len);
 
  return k_ra8_ok;
}
 
ra8_err_t ra8_usb_hmsc_decode_csw(const uint8_t*             csw,
                                  uint32_t                   expected_tag,
                                  ra8_usb_hmsc_csw_status_t* out_status)
{
  RA8_CHECK_NULL_PTR(csw, s_tag, "decode_csw: csw");
  RA8_CHECK_NULL_PTR(out_status, s_tag, "decode_csw: out_status");
 
  const uint32_t signature = internal_unpack_u32_le(&csw[k_ra8_hmsc_csw_off_signature]);
  if (signature != k_ra8_hmsc_csw_signature) {
    return k_ra8_err_invalid_arg;
  }
  const uint32_t tag = internal_unpack_u32_le(&csw[k_ra8_hmsc_csw_off_tag]);
  if (tag != expected_tag) {
    return k_ra8_err_invalid_arg;
  }
 
  const uint8_t status_byte = csw[k_ra8_hmsc_csw_off_status];
  if ((status_byte != k_ra8_hmsc_csw_status_passed) &&
      (status_byte != k_ra8_hmsc_csw_status_failed) &&
      (status_byte != k_ra8_hmsc_csw_status_phase_error)) {
    return k_ra8_err_invalid_arg;
  }
 
  *out_status = (ra8_usb_hmsc_csw_status_t)status_byte;
  return k_ra8_ok;
}
 
/* =============================================================================
 * Lifecycle
 * =============================================================================
 */
 
ra8_err_t ra8_usb_hmsc_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;
  }
 
  g_usb_hmsc_state.speed        = speed;
  g_usb_hmsc_state.attached     = false;
  g_usb_hmsc_state.attach_cb    = nullptr;
  g_usb_hmsc_state.attach_ctx   = nullptr;
  g_usb_hmsc_state.device       = (ra8_usb_hmsc_device_t){};
  g_usb_hmsc_state.next_cbw_tag = k_ra8_hmsc_initial_tag;
  g_usb_hmsc_state.initialized  = true;
 
  ra8_log_info_val(s_tag, "host-MSC ready", (uint32_t)speed);
  return k_ra8_ok;
}
 
ra8_err_t ra8_usb_hmsc_close(void)
{
  if (!g_usb_hmsc_state.initialized) {
    return k_ra8_err_invalid_state;
  }
  /* Bus power down: drop UACT before tearing the controller. */
  (void)ra8_usb_host_set_uact(g_usb_hmsc_state.speed, false);
  const ra8_err_t err          = ra8_usb_host_deinit(g_usb_hmsc_state.speed);
  g_usb_hmsc_state.initialized = false;
  g_usb_hmsc_state.attached    = false;
  g_usb_hmsc_state.attach_cb   = nullptr;
  g_usb_hmsc_state.attach_ctx  = nullptr;
  return err;
}
 
/* =============================================================================
 * Attach callback
 * =============================================================================
 */
 
ra8_err_t ra8_usb_hmsc_attach_callback(ra8_usb_hmsc_attach_fn_t on_attach, void* ctx)
{
  if (!g_usb_hmsc_state.initialized) {
    return k_ra8_err_invalid_state;
  }
  g_usb_hmsc_state.attach_cb  = on_attach;
  g_usb_hmsc_state.attach_ctx = ctx;
  return k_ra8_ok;
}
 
/* =============================================================================
 * Internal BOT helpers shared by SCSI command entry points
 * =============================================================================
 */
 
/* Validate driver state + LUN before issuing a SCSI command -- see surrounding code and HUM citations. */
RA8_INTERNAL
static ra8_err_t internal_check_ready(uint8_t target_lun)
{
  if (!g_usb_hmsc_state.initialized) {
    return k_ra8_err_invalid_state;
  }
  if (!g_usb_hmsc_state.attached) {
    return k_ra8_err_invalid_state;
  }
  if (target_lun > k_ra8_hmsc_max_lun) {
    return k_ra8_err_invalid_arg;
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_send_cbw(const uint8_t* cbw)
{
  return ra8_usb_host_bulk_out(g_usb_hmsc_state.speed,
                               k_ra8_hmsc_pipe_bulk_out,
                               cbw,
                               k_ra8_hmsc_cbw_len);
}

RA8_INTERNAL
static ra8_err_t internal_recv_bytes(uint8_t* dst, uint16_t* inout_len)
{
  const uint16_t cap = *inout_len;
  return ra8_usb_host_bulk_in(g_usb_hmsc_state.speed, k_ra8_hmsc_pipe_bulk_in, dst, cap, inout_len);
}
 
/* Build a 6-byte CDB for SCSI INQUIRY -- see surrounding code and HUM citations. */
RA8_INTERNAL
static void internal_build_inquiry_cdb(uint8_t* cdb)
{
  internal_zero_bytes(cdb, k_ra8_hmsc_cdb6_len);
  cdb[k_ra8_hmsc_cdb_off_opcode]    = k_ra8_hmsc_scsi_inquiry;
  cdb[k_ra8_hmsc_cdb_off_inq_alloc] = (uint8_t)k_ra8_hmsc_inquiry_resp_len;
}
 
/* Build a 10-byte CDB for SCSI READ_CAPACITY(10) -- see surrounding code and HUM citations. */
RA8_INTERNAL
static void internal_build_read_capacity_cdb(uint8_t* cdb)
{
  internal_zero_bytes(cdb, k_ra8_hmsc_cdb10_len);
  cdb[k_ra8_hmsc_cdb_off_opcode] = k_ra8_hmsc_scsi_read_capacity_10;
}

RA8_INTERNAL
static void
internal_build_rw10_cdb(uint8_t opcode, uint32_t lba, uint16_t block_count, uint8_t* cdb)
{
  internal_zero_bytes(cdb, k_ra8_hmsc_cdb10_len);
  cdb[k_ra8_hmsc_cdb_off_opcode] = opcode;
  cdb[k_ra8_hmsc_cdb_off_lba_msb] =
    (uint8_t)((lba >> k_ra8_hmsc_shift_byte3) & k_ra8_hmsc_byte_mask);
  cdb[k_ra8_hmsc_cdb_off_lba_b1] =
    (uint8_t)((lba >> k_ra8_hmsc_shift_byte2) & k_ra8_hmsc_byte_mask);
  cdb[k_ra8_hmsc_cdb_off_lba_b2] =
    (uint8_t)((lba >> k_ra8_hmsc_shift_byte1) & k_ra8_hmsc_byte_mask);
  cdb[k_ra8_hmsc_cdb_off_lba_lsb] =
    (uint8_t)((lba >> k_ra8_hmsc_shift_byte0) & k_ra8_hmsc_byte_mask);
  cdb[k_ra8_hmsc_cdb_off_cnt_msb] =
    (uint8_t)((block_count >> k_ra8_hmsc_shift_byte1) & k_ra8_hmsc_byte_mask);
  cdb[k_ra8_hmsc_cdb_off_cnt_lsb] = (uint8_t)(block_count & k_ra8_hmsc_byte_mask);
}
 
/* Build CBW + push it on bulk-OUT -- see surrounding code and HUM citations. */
RA8_INTERNAL
static ra8_err_t internal_issue_cbw(uint8_t        target_lun,
                                    uint32_t       xfer_len,
                                    bool           data_in,
                                    const uint8_t* cdb,
                                    uint8_t        cdb_len,
                                    uint32_t*      out_tag)
{
  uint8_t         cbw[k_ra8_hmsc_cbw_len] = {};
  const ra8_err_t cbw_err =
    ra8_usb_hmsc_build_cbw(target_lun, xfer_len, data_in, cdb, cdb_len, cbw);
  RA8_RETURN_ON_ERROR(cbw_err, s_tag, "issue_cbw: build cbw");
  *out_tag = internal_unpack_u32_le(&cbw[k_ra8_hmsc_cbw_off_tag]);
  return internal_send_cbw(cbw);
}

RA8_INTERNAL
static ra8_err_t internal_read_csw(uint32_t expected_tag)
{
  uint8_t   csw[k_ra8_hmsc_csw_len] = {};
  uint16_t  len                     = k_ra8_hmsc_csw_len;
  ra8_err_t err                     = internal_recv_bytes(csw, &len);
  RA8_RETURN_ON_ERROR(err, s_tag, "read_csw: bulk in");
  if (len != (uint16_t)k_ra8_hmsc_csw_len) {
    return k_ra8_err_hw_error;
  }
  ra8_usb_hmsc_csw_status_t status = k_ra8_hmsc_csw_status_phase_error;
  err                              = ra8_usb_hmsc_decode_csw(csw, expected_tag, &status);
  RA8_RETURN_ON_ERROR(err, s_tag, "read_csw: decode");
  if (status != k_ra8_hmsc_csw_status_passed) {
    return k_ra8_err_hw_error;
  }
  return k_ra8_ok;
}
 
/* function -- see surrounding code and HUM citations. */
RA8_INTERNAL
static ra8_err_t internal_run_data_in(uint8_t        target_lun,
                                      const uint8_t* cdb,
                                      uint8_t        cdb_len,
                                      uint8_t*       out_buf,
                                      uint16_t*      inout_len)
{
  uint32_t        tag     = 0U;
  const ra8_err_t cbw_err = internal_issue_cbw(target_lun, *inout_len, true, cdb, cdb_len, &tag);
  RA8_RETURN_ON_ERROR(cbw_err, s_tag, "run_data_in: issue cbw");
  const ra8_err_t derr = internal_recv_bytes(out_buf, inout_len);
  RA8_RETURN_ON_ERROR(derr, s_tag, "run_data_in: data");
  return internal_read_csw(tag);
}
 
/* function -- see surrounding code and HUM citations. */
RA8_INTERNAL
static ra8_err_t internal_run_data_out(uint8_t        target_lun,
                                       const uint8_t* cdb,
                                       uint8_t        cdb_len,
                                       const uint8_t* in_buf,
                                       uint16_t       push_len)
{
  uint32_t        tag = 0U;
  const ra8_err_t cbw_err =
    internal_issue_cbw(target_lun, (uint32_t)push_len, false, cdb, cdb_len, &tag);
  RA8_RETURN_ON_ERROR(cbw_err, s_tag, "run_data_out: issue cbw");
  /* The bulk-OUT primitive ships one packet per call, so chunk at the
   * DEVICE's enumerated bulk-OUT wMaxPacketSize -- NOT the host
   * controller's native ceiling. On a HS host driving an FS device (the
   * self-loop) the controller speed is HS (512) but the endpoint is FS
   * (64); chunking at 512 advances the offset 8x faster than the 64-byte
   * packet actually sent, so the device receives only 1/8 of the data
   * and the WRITE wedges. The pipe's PIPEMAXP is already this value
   * (see the enum pipe setup). Fall back to the speed ceiling only if
   * enumeration left it unset. */
  uint16_t mps = g_usb_hmsc_state.device.bulk_out_max_packet;
  if (mps == 0U) {
    mps = internal_bulk_max_packet(g_usb_hmsc_state.speed);
  }
  uint16_t offset = 0U;
  while (offset < push_len) {
    uint16_t chunk = (uint16_t)(push_len - offset);
    if (chunk > mps) {
      chunk = mps;
    }
    const ra8_err_t werr = ra8_usb_host_bulk_out(g_usb_hmsc_state.speed,
                                                 k_ra8_hmsc_pipe_bulk_out,
                                                 &in_buf[offset],
                                                 chunk);
    RA8_RETURN_ON_ERROR(werr, s_tag, "run_data_out: data chunk");
    offset = (uint16_t)(offset + chunk);
  }
  return internal_read_csw(tag);
}

RA8_INTERNAL
static void internal_decode_inquiry(const uint8_t* raw, ra8_usb_hmsc_inquiry_response_t* response)
{
  internal_zero_bytes((uint8_t*)response, (uint16_t)sizeof(*response));
  const uint8_t b0                 = raw[k_ra8_hmsc_inq_off_dev_type];
  const uint8_t b1                 = raw[k_ra8_hmsc_inq_off_removable];
  response->peripheral_qualifier   = (uint8_t)(b0 >> k_ra8_hmsc_inq_qual_shift);
  response->peripheral_device_type = (uint8_t)(b0 & k_ra8_hmsc_inq_dev_type_mask);
  response->removable =
    (uint8_t)((b1 >> k_ra8_hmsc_inq_removable_shift) & k_ra8_hmsc_inq_removable_mask);
  response->version = raw[k_ra8_hmsc_inq_off_version];
  internal_copy_bytes(response->vendor_id,
                      &raw[k_ra8_hmsc_inq_off_vendor_id],
                      (uint16_t)sizeof(response->vendor_id));
  internal_copy_bytes(response->product_id,
                      &raw[k_ra8_hmsc_inq_off_product_id],
                      (uint16_t)sizeof(response->product_id));
  internal_copy_bytes(response->product_revision,
                      &raw[k_ra8_hmsc_inq_off_product_rev],
                      (uint16_t)sizeof(response->product_revision));
}
 
/* =============================================================================
 * SCSI commands -- public entry points
 * =============================================================================
 */
 
ra8_err_t ra8_usb_hmsc_inquiry(uint8_t target_lun, ra8_usb_hmsc_inquiry_response_t* response)
{
  RA8_CHECK_NULL_PTR(response, s_tag, "inquiry: response");
  const ra8_err_t ready_err = internal_check_ready(target_lun);
  RA8_RETURN_ON_ERROR(ready_err, s_tag, "inquiry: not ready");
 
  uint8_t cdb[k_ra8_hmsc_cdb_max_len] = {};
  internal_build_inquiry_cdb(cdb);
 
  uint8_t         raw_response[k_ra8_hmsc_inquiry_resp_len] = {};
  uint16_t        got_len                                   = k_ra8_hmsc_inquiry_resp_len;
  const ra8_err_t err =
    internal_run_data_in(target_lun, cdb, (uint8_t)k_ra8_hmsc_cdb6_len, raw_response, &got_len);
  RA8_RETURN_ON_ERROR(err, s_tag, "inquiry: bot");
  internal_decode_inquiry(raw_response, response);
  return k_ra8_ok;
}
 
ra8_err_t
ra8_usb_hmsc_read_capacity(uint8_t target_lun, uint32_t* block_count, uint32_t* block_size)
{
  RA8_CHECK_NULL_PTR(block_count, s_tag, "read_capacity: block_count");
  RA8_CHECK_NULL_PTR(block_size, s_tag, "read_capacity: block_size");
  const ra8_err_t ready_err = internal_check_ready(target_lun);
  RA8_RETURN_ON_ERROR(ready_err, s_tag, "read_capacity: not ready");
 
  uint8_t cdb[k_ra8_hmsc_cdb_max_len] = {};
  internal_build_read_capacity_cdb(cdb);
 
  uint8_t         raw_response[k_ra8_hmsc_read_capacity_resp_len] = {};
  uint16_t        got_len = k_ra8_hmsc_read_capacity_resp_len;
  const ra8_err_t err =
    internal_run_data_in(target_lun, cdb, (uint8_t)k_ra8_hmsc_cdb10_len, raw_response, &got_len);
  RA8_RETURN_ON_ERROR(err, s_tag, "read_capacity: bot");
 
  /* Decode SBC-4 sec 5.10: byte[0..3] = LAST valid LBA (big-endian),
   * byte[4..7] = block size (big-endian). When the fake returns
   * zeros default to a sane block size so calling code can still
   * compute capacities. */
  const uint32_t last_lba = internal_unpack_u32_be(&raw_response[k_ra8_hmsc_cap_off_last_lba]);
  const uint32_t blk      = internal_unpack_u32_be(&raw_response[k_ra8_hmsc_cap_off_blk_size]);
  *block_count            = last_lba + 1U;
  *block_size             = (blk == 0U) ? (uint32_t)k_ra8_hmsc_block_size_default : blk;
  return k_ra8_ok;
}
 
ra8_err_t
ra8_usb_hmsc_read10(uint8_t target_lun, uint32_t lba, uint16_t block_count, uint8_t* out_buf)
{
  RA8_CHECK_NULL_PTR(out_buf, s_tag, "read10: out_buf");
  if (block_count == 0U) {
    return k_ra8_err_invalid_arg;
  }
  const ra8_err_t ready_err = internal_check_ready(target_lun);
  RA8_RETURN_ON_ERROR(ready_err, s_tag, "read10: not ready");
 
  uint8_t cdb[k_ra8_hmsc_cdb_max_len] = {};
  internal_build_rw10_cdb(k_ra8_hmsc_scsi_read_10, lba, block_count, cdb);
 
  /* dCBWDataTransferLength = block_count * block_size. We default to
   * the standard 512-byte block; production should use the cached
   * read_capacity result. */
  const uint32_t  xfer_len = (uint32_t)block_count * (uint32_t)k_ra8_hmsc_block_size_default;
  uint16_t        got_len  = (xfer_len > UINT16_MAX) ? UINT16_MAX : (uint16_t)xfer_len;
  const ra8_err_t err =
    internal_run_data_in(target_lun, cdb, (uint8_t)k_ra8_hmsc_cdb10_len, out_buf, &got_len);
  RA8_RETURN_ON_ERROR(err, s_tag, "read10: bot");
  return k_ra8_ok;
}
 
ra8_err_t
ra8_usb_hmsc_write10(uint8_t target_lun, uint32_t lba, uint16_t block_count, const uint8_t* in_buf)
{
  RA8_CHECK_NULL_PTR(in_buf, s_tag, "write10: in_buf");
  if (block_count == 0U) {
    return k_ra8_err_invalid_arg;
  }
  const ra8_err_t ready_err = internal_check_ready(target_lun);
  RA8_RETURN_ON_ERROR(ready_err, s_tag, "write10: not ready");
 
  uint8_t cdb[k_ra8_hmsc_cdb_max_len] = {};
  internal_build_rw10_cdb(k_ra8_hmsc_scsi_write_10, lba, block_count, cdb);
 
  const uint32_t  xfer_len = (uint32_t)block_count * (uint32_t)k_ra8_hmsc_block_size_default;
  const uint16_t  push_len = (xfer_len > UINT16_MAX) ? UINT16_MAX : (uint16_t)xfer_len;
  const ra8_err_t err =
    internal_run_data_out(target_lun, cdb, (uint8_t)k_ra8_hmsc_cdb10_len, in_buf, push_len);
  RA8_RETURN_ON_ERROR(err, s_tag, "write10: bot");
  return k_ra8_ok;
}