ra8_usb_host_ctrl.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_hw_err.h"
#include "ra8_usb.h"
#include "ra8_usb_internal.h"
#include "ra8_usb_regs.h"
 
static const char* s_tag = "USB";
 
/* =============================================================================
 * Host-mode control-transfer engine (polled, synchronous)
 *
 * The RA SIE signals host control-transfer progress through SUREQ-clear
 * (SETUP done), BRDY (a DATA packet landed in the DCP buffer) and BEMP
 * (the STATUS stage completed) -- NOT through CTRT, which is a device-mode
 * control-stage signal. This block composes the existing FIFO/PID helpers
 * into a blocking GET/SET control transfer over the DCP (pipe 0).
 * =============================================================================
 */

typedef enum : uint32_t {
  k_ra8_usb_ctrl_poll_limit = 2000000UL, 
} ra8_usb_host_ctrl_lim_t;

typedef enum : uint8_t {
  k_ra8_usb_cs_begin     = 0U, 
  k_ra8_usb_cs_setup     = 1U, 
  k_ra8_usb_cs_data_in   = 2U, 
  k_ra8_usb_cs_data_pkt  = 3U, 
  k_ra8_usb_cs_data_done = 4U, 
  k_ra8_usb_cs_status    = 5U, 
  k_ra8_usb_cs_done      = 6U, 
  k_ra8_usb_cs_data_out  = 7U, 
} ra8_usb_host_ctrl_stage_code_t;

static volatile uint8_t s_host_ctrl_stage = (uint8_t)k_ra8_usb_cs_begin;
 
uint8_t ra8_usb_host_ctrl_stage(void)
{
  return s_host_ctrl_stage;
}

void priv_host_program_devadd(volatile r_usb_regs_t* reg, uint8_t dev_addr)
{
  const uint16_t  rhst = (uint16_t)(reg->DVSTCTR0 & (uint16_t)k_ra8_usb_rhst_mask);
  const uintptr_t off =
    (uintptr_t)k_ra8_usb_devadd0_off + ((uintptr_t)dev_addr * (uintptr_t)k_ra8_usb_devadd_stride);
  volatile uint16_t* const devadd = (volatile uint16_t*)((uintptr_t)reg + off);
  *devadd                         = (uint16_t)(rhst << (uint16_t)k_ra8_usb_usbspd_shift);
}

RA8_INTERNAL
static ra8_err_t internal_host_wait_sts(volatile const uint16_t* sts, uint16_t mask)
{
  for (uint32_t i = 0U; i < (uint32_t)k_ra8_usb_ctrl_poll_limit; ++i) {
    if ((*sts & mask) != 0U) {
      return k_ra8_ok;
    }
  }
  return k_ra8_err_hw_timeout;
}

RA8_INTERNAL
static ra8_err_t internal_host_dcp_in_wait(volatile r_usb_regs_t* reg)
{
  for (uint32_t i = 0U; i < (uint32_t)k_ra8_usb_ctrl_poll_limit; ++i) {
    if ((reg->BRDYSTS & (uint16_t)k_ra8_usb_dcp_pipe0_bit) != 0U) {
      return k_ra8_ok;
    }
    if ((reg->DCPCTR & (uint16_t)k_ra8_usb_pid_stall_bit) != 0U) {
      return k_ra8_err_hw_error;
    }
    if ((reg->NRDYSTS & (uint16_t)k_ra8_usb_dcp_pipe0_bit) != 0U) {
      reg->NRDYSTS = (uint16_t)~(uint16_t)k_ra8_usb_dcp_pipe0_bit;
      priv_dcp_pid(reg, k_ra8_pid_buf);
    }
  }
  return k_ra8_err_hw_timeout;
}

RA8_INTERNAL
static ra8_err_t internal_host_setup_wait(volatile r_usb_regs_t* reg)
{
  const uint16_t sack  = (uint16_t)(1U << k_ra8_int1_bit_sack);
  const uint16_t sign  = (uint16_t)(1U << k_ra8_int1_bit_sign);
  const uint16_t sureq = (uint16_t)(1U << k_ra8_dcpctr_bit_sureq);
#if !(defined(RA8_OFF_TARGET) && defined(UNIT_TEST))
  /* Clear the stale SACK/SIGN latches before asserting SUREQ. Skipped on the
   * host unit-test build: its plain-RAM INTSTS1 cannot be re-latched by a SIE
   * after a W0C clear, so wiping it here would erase the SACK/SIGN outcome a
   * test pre-loaded and the poll below would never observe it. */
  reg->INTSTS1 = (uint16_t)~(uint16_t)(sack | sign);
#endif
  priv_rmw16(&reg->DCPCTR, sureq, 0U);
  for (uint32_t i = 0U; i < (uint32_t)k_ra8_usb_ctrl_poll_limit; ++i) {
    const uint16_t sts1 = reg->INTSTS1;
#if defined(RA8_OFF_TARGET) && defined(UNIT_TEST)
    const bool got_sack = ra8_fake_mmio_wait_eval(&reg->INTSTS1, i, ((sts1 & sack) != 0U));
#else
    const bool got_sack = ((sts1 & sack) != 0U);
#endif
    if (got_sack) {
      reg->INTSTS1 = (uint16_t)~sack;
      return k_ra8_ok;
    }
    if ((sts1 & sign) != 0U) {
      reg->INTSTS1 = (uint16_t)~sign;
      return k_ra8_err_hw_error;
    }
  }
  return k_ra8_err_hw_timeout;
}

RA8_INTERNAL
static ra8_err_t internal_host_ctrl_setup(volatile r_usb_regs_t* reg, const ra8_usb_setup_t* setup)
{
  const uint16_t sureq = (uint16_t)(1U << k_ra8_dcpctr_bit_sureq);
  if ((reg->DCPCTR & sureq) != 0U) {
    /* A SETUP issued with the port inactive (e.g. before any device was
     * attached) leaves SUREQ wedged. The USBHS instance provides
     * SUREQCLR to abort it; try that before reporting busy. */
    if (priv_is_hs(reg)) {
      priv_rmw16(&reg->DCPCTR, (uint16_t)(1U << k_ra8_dcpctr_bit_sureqclr), 0U);
    }
    if ((reg->DCPCTR & sureq) != 0U) {
      return k_ra8_err_busy;
    }
  }
  priv_dcp_pid(reg, k_ra8_pid_nak);
  /* Clear any stale CCPL left by a prior transfer's status stage. With
   * CCPL still set, arming PID=BUF for the new DATA stage makes the SIE
   * run a status stage instead, so the data stage never moves (observed
   * as stage=2 with DCPCTR=0x0004 on hardware). */
  priv_rmw16(&reg->DCPCTR, 0U, (uint16_t)(1U << k_ra8_dcpctr_bit_ccpl));
  /* Refresh the DEVADD slot of the address the DCP currently targets
   * (DCPMAXP.DEVSEL); 0 before SET_ADDRESS, the assigned address after
   * ra8_usb_host_set_target. */
  const uint8_t devsel = (uint8_t)((uint16_t)(reg->DCPMAXP >> (uint16_t)k_ra8_usb_devsel_shift) &
                                   (uint16_t)k_ra8_usb_devsel_field_mask);
  priv_host_program_devadd(reg, devsel);
#ifdef RA8_OFF_TARGET
  /* BEMPSTS/BRDYSTS are W1C: on hardware, writing ~DCP clears every set status
   * bit EXCEPT the DCP pipe. A plain-RAM fake would blind-assign 0xFFFE and zero
   * the DCP bit a test pre-loaded for the DATA stage, so model the W1C (preserve
   * DCP, clear the rest) explicitly off-target. */
  reg->BEMPSTS = (uint16_t)(reg->BEMPSTS & (uint16_t)k_ra8_usb_dcp_pipe0_bit);
  reg->BRDYSTS = (uint16_t)(reg->BRDYSTS & (uint16_t)k_ra8_usb_dcp_pipe0_bit);
#else
  reg->BEMPSTS = (uint16_t)~(uint16_t)k_ra8_usb_dcp_pipe0_bit;
  reg->BRDYSTS = (uint16_t)~(uint16_t)k_ra8_usb_dcp_pipe0_bit;
#endif
  const uint16_t req = (uint16_t)((uint16_t)setup->bm_request_type |
                                  (uint16_t)((uint16_t)setup->b_request << k_ra8_usb_byte_bits));
  reg->USBREQ        = req;
  reg->USBVAL        = setup->w_value;
  reg->USBINDX       = setup->w_index;
  reg->USBLENG       = setup->w_length;
  /* Arm + clear the SETUP outcome flags: SACK latches when the device
   * ACKs the SETUP, SIGN when three transmission attempts fail. SUREQ
   * self-clearing alone is NOT an ACK indication, so gate on these. */
  const uint16_t sack = (uint16_t)(1U << k_ra8_int1_bit_sack);
  const uint16_t sign = (uint16_t)(1U << k_ra8_int1_bit_sign);
  reg->INTENB1        = (uint16_t)(reg->INTENB1 | (uint16_t)(sack | sign));
  return internal_host_setup_wait(reg);
}

RA8_INTERNAL
static void internal_host_ctrl_data_arm(volatile r_usb_regs_t* reg)
{
  priv_select_cfifo(reg, 0U, false);
  reg->CFIFOCTR = (uint16_t)k_ra8_fifoctr_bclr;
  reg->BRDYENB  = (uint16_t)(reg->BRDYENB | (uint16_t)k_ra8_usb_dcp_pipe0_bit);
  reg->NRDYENB  = (uint16_t)(reg->NRDYENB | (uint16_t)k_ra8_usb_dcp_pipe0_bit);
  priv_rmw16(&reg->DCPCTR, (uint16_t)(1U << k_ra8_dcpctr_bit_sqset), 0U);
  priv_dcp_pid(reg, k_ra8_pid_buf);
}

RA8_INTERNAL
static ra8_err_t internal_host_ctrl_data_in(volatile r_usb_regs_t* reg,
                                            uint8_t*               data,
                                            uint16_t               want,
                                            uint16_t               mxps,
                                            uint16_t*              out_rx)
{
  uint16_t rx   = 0U;
  bool     done = false;
  internal_host_ctrl_data_arm(reg);
  while (!done) {
    const ra8_err_t br = internal_host_dcp_in_wait(reg);
    if (br != k_ra8_ok) {
      priv_dcp_pid(reg, k_ra8_pid_nak);
      return br;
    }
    s_host_ctrl_stage = (uint8_t)k_ra8_usb_cs_data_pkt;
    priv_select_cfifo(reg, 0U, false);
    if (priv_wait_frdy(reg) != k_ra8_ok) {
      priv_dcp_pid(reg, k_ra8_pid_nak);
      return k_ra8_err_hw_timeout;
    }
    const uint16_t dtln  = (uint16_t)(reg->CFIFOCTR & k_ra8_fifoctr_dtln);
    uint16_t       chunk = dtln;
    if ((uint16_t)(rx + chunk) > want) {
      chunk = (uint16_t)(want - rx);
    }
    if (chunk > 0U) {
      priv_fifo_read(reg, &data[rx], chunk);
    }
    reg->CFIFOCTR = (uint16_t)k_ra8_fifoctr_bclr;
    rx            = (uint16_t)(rx + dtln);
    reg->BRDYSTS  = (uint16_t)~(uint16_t)k_ra8_usb_dcp_pipe0_bit;
    if (dtln < mxps) {
      done = true;
    }
    if (rx >= want) {
      done = true;
    }
  }
  priv_dcp_pid(reg, k_ra8_pid_nak);
  *out_rx = rx;
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_host_ctrl_status(volatile r_usb_regs_t* reg, bool write_zlp)
{
  const uint16_t ccpl = (uint16_t)(1U << k_ra8_dcpctr_bit_ccpl);
  reg->BEMPSTS        = (uint16_t)~(uint16_t)k_ra8_usb_dcp_pipe0_bit;
  reg->BRDYSTS        = (uint16_t)~(uint16_t)k_ra8_usb_dcp_pipe0_bit;
  reg->BEMPENB        = (uint16_t)(reg->BEMPENB | (uint16_t)k_ra8_usb_dcp_pipe0_bit);
  reg->BRDYENB        = (uint16_t)(reg->BRDYENB | (uint16_t)k_ra8_usb_dcp_pipe0_bit);
  /* A control-WRITE data stage left DCPCFG.DIR = 1 (OUT tokens); its IN-ZLP
   * status stage needs DIR = 0 so the host issues an IN token to collect the
   * device's status ZLP. Restore it for the write / no-data status (the
   * control-READ OUT-ZLP status keeps the default DIR and is best-effort).
   * HUM Ch 36.2.18 "DCPCFG : DCP Configuration" p 1989. */
  if (!write_zlp) {
    priv_rmw16(&reg->DCPCFG, 0U, (uint16_t)(1U << (uint8_t)k_ra8_dcpcfg_bit_dir));
  }
  /* The status stage is always DATA1; force the DCP sequence bit so the
   * device does not NAK a toggle mismatch (seen as NRDYSTS bit 0). */
  priv_rmw16(&reg->DCPCTR, (uint16_t)(1U << k_ra8_dcpctr_bit_sqset), 0U);
  priv_select_cfifo(reg, 0U, write_zlp);
  if (write_zlp) {
    /* Control-read status is an OUT the host must drive: enqueue a
     * zero-length packet (BVAL, no CFIFO write) and assert CCPL. This is
     * best-effort -- the DATA-IN payload the caller wanted is already in
     * hand, and a fresh SETUP re-syncs the control endpoint regardless, so
     * a slow/NAKed OUT status does not invalidate the transfer. */
    reg->CFIFOCTR = (uint16_t)k_ra8_fifoctr_bval;
    priv_dcp_pid(reg, k_ra8_pid_buf);
    priv_rmw16(&reg->DCPCTR, ccpl, 0U);
    (void)internal_host_wait_sts(&reg->BEMPSTS, k_ra8_usb_dcp_pipe0_bit);
    priv_dcp_pid(reg, k_ra8_pid_nak);
    priv_rmw16(&reg->DCPCTR, 0U, ccpl);
    return k_ra8_ok;
  }
  /* Control-write / no-data status is an IN: free the DCP receive buffer
   * FIRST -- a stale BSTS blocks the incoming ZLP, the SIE NAKs it
   * forever, and the request never takes effect on the device (observed
   * on hardware as SET_CONFIGURATION "passing" while the bulk endpoints
   * stayed dead). Then arm PID=BUF + CCPL and require the BRDY that
   * marks the device's status ZLP received. */
  reg->CFIFOCTR = (uint16_t)k_ra8_fifoctr_bclr;
  reg->NRDYSTS  = (uint16_t)~(uint16_t)k_ra8_usb_dcp_pipe0_bit;
  priv_dcp_pid(reg, k_ra8_pid_buf);
  priv_rmw16(&reg->DCPCTR, ccpl, 0U);
  const ra8_err_t ierr = internal_host_dcp_in_wait(reg);
  priv_dcp_pid(reg, k_ra8_pid_nak);
  priv_rmw16(&reg->DCPCTR, 0U, ccpl);
  /* Drain the status ZLP so it cannot alias the next data stage. */
  reg->CFIFOCTR = (uint16_t)k_ra8_fifoctr_bclr;
  reg->BRDYSTS  = (uint16_t)~(uint16_t)k_ra8_usb_dcp_pipe0_bit;
  return ierr;
}

RA8_INTERNAL
static ra8_err_t internal_host_ctrl_data_out(volatile r_usb_regs_t* reg,
                                             const uint8_t*         data,
                                             uint16_t               want,
                                             uint16_t               mxps)
{
  /* Host DCP issues IN tokens by default (DCPCFG.DIR = 0, which serves the
   * common control-READ data stage). A control-WRITE data stage must flip
   * DIR = 1 so the controller issues OUT tokens; otherwise the device sees an
   * IN token in its write-data stage and flags CTSQ = SQER, dropping the
   * payload (CFIFOSEL.ISEL only sets the CPU FIFO-access direction, not the
   * wire token direction). HUM Ch 36.2.18 "DCPCFG : DCP Configuration" p 1989. */
  priv_rmw16(&reg->DCPCFG, (uint16_t)(1U << (uint8_t)k_ra8_dcpcfg_bit_dir), 0U);
  priv_select_cfifo(reg, 0U, true);
  /* HUM Ch 36.2.8 "CFIFOCTR : CFIFO Port Control Register", p 1979 -- discard
   * any stale bank so FRDY re-asserts for the fresh write. */
  reg->CFIFOCTR = (uint16_t)k_ra8_fifoctr_bclr;
  /* First data packet after SETUP is DATA1; force the DCP sequence bit so the
   * device does not drop it on a toggle mismatch. */
  priv_rmw16(&reg->DCPCTR, (uint16_t)(1U << k_ra8_dcpctr_bit_sqset), 0U);
  reg->BEMPSTS = (uint16_t)~(uint16_t)k_ra8_usb_dcp_pipe0_bit;
  reg->BEMPENB = (uint16_t)(reg->BEMPENB | (uint16_t)k_ra8_usb_dcp_pipe0_bit);
 
  const uint16_t step = (mxps == 0U) ? (uint16_t)1U : mxps;
  uint16_t       off  = 0U;
  while (off < want) {
    uint16_t chunk = (uint16_t)(want - off);
    if (chunk > step) {
      chunk = step;
    }
    const ra8_err_t perr = priv_dcp_push_chunk(reg, &data[off], chunk);
    if (perr != k_ra8_ok) {
      priv_dcp_pid(reg, k_ra8_pid_nak);
      return perr;
    }
    priv_dcp_pid(reg, k_ra8_pid_buf);
    /* Best-effort drain wait. The DCP BEMP completion indication is unreliable
     * on this silicon (see ::internal_host_ctrl_status) -- gating hard on it
     * deadlocks an OUT that actually landed. Give the bank a bounded window to
     * drain (back-pressure for multi-packet) but proceed regardless; the IN
     * status stage + the class protocol (DFU_GETSTATUS) confirm delivery. */
    (void)internal_host_wait_sts(&reg->BEMPSTS, (uint16_t)k_ra8_usb_dcp_pipe0_bit);
    reg->BEMPSTS = (uint16_t)~(uint16_t)k_ra8_usb_dcp_pipe0_bit;
    off          = (uint16_t)(off + chunk);
  }
  priv_dcp_pid(reg, k_ra8_pid_nak);
  return k_ra8_ok;
}

ra8_err_t ra8_usb_dcp_out_arm(ra8_usb_speed_t speed)
{
  volatile r_usb_regs_t* reg = priv_pick(speed);
  if (reg == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  /* Receiving the data stage of a control-WRITE on the DCP. The first data
   * packet after a SETUP is ALWAYS DATA1 (USB 2.0 sec 8.6); a stale DCP
   * sequence toggle makes the SIE silently ACK-and-discard the host's packet
   * with NO BRDY -- the exact failure the host read-arm guards against in
   * ::internal_host_ctrl_data_arm. So clear the stale BRDY latch, select the
   * DCP read window, clear the receive bank (BCLR), enable the DCP BRDY
   * interrupt, force the receive toggle to DATA1 via DCPCTR.SQSET, and set
   * PID=BUF so the SIE ACKs the OUT token.
   * HUM Ch 36.2.21 "DCPCTR" p 1991 (SQSET) / Ch 36.2.11 "BRDYENB" p 1982 /
   * Ch 36.2.8 "CFIFOCTR" p 1979 (BCLR). */
  priv_dcp_pid(reg, k_ra8_pid_nak);
  /* Clear any stale CCPL left by the previous transfer's status stage. With
   * CCPL still set, arming PID=BUF makes the SIE run a status stage instead of
   * accepting the data stage -- CTSQ goes to SQER and the OUT data never lands.
   * Device-side mirror of the host guard in ::internal_host_ctrl_setup.
   * HUM Ch 36.2.21 "DCPCTR : DCP Control Register" p 1991 (CCPL). */
  priv_rmw16(&reg->DCPCTR, 0U, (uint16_t)(1U << (uint8_t)k_ra8_dcpctr_bit_ccpl));
  reg->BRDYSTS = (uint16_t)~(uint16_t)k_ra8_usb_dcp_pipe0_bit;
  priv_select_cfifo(reg, 0U, false);
  reg->CFIFOCTR = (uint16_t)k_ra8_fifoctr_bclr;
  reg->BRDYENB  = (uint16_t)(reg->BRDYENB | (uint16_t)k_ra8_usb_dcp_pipe0_bit);
  priv_rmw16(&reg->DCPCTR, (uint16_t)(1U << (uint8_t)k_ra8_dcpctr_bit_sqset), 0U);
  priv_dcp_pid(reg, k_ra8_pid_buf);
  if ((reg->BRDYENB & (uint16_t)k_ra8_usb_dcp_pipe0_bit) == 0U) {
    /* The line above OR-set the DCP bit into BRDYENB and no helper touches
     * BRDYENB before this re-read of the same word, so under RA8_OFF_TARGET
     * (plain-RAM registers) the bit is always present; this timeout is only
     * reachable on silicon where the SIE refuses the enable. */
    return k_ra8_err_hw_timeout; /* GCOVR_EXCL_LINE -- SIE enable refusal seen only on silicon */
  }
  return k_ra8_ok;
}

ra8_err_t ra8_usb_dcp_out_read(ra8_usb_speed_t speed, uint8_t* buf, uint16_t cap, uint16_t* out_rx)
{
  volatile r_usb_regs_t* reg = priv_pick(speed);
  if (reg == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  if ((buf == nullptr) || (out_rx == nullptr)) {
    return k_ra8_err_invalid_arg;
  }
  *out_rx = 0U;
 
  /* The BRDY ISR only calls this once the DCP BRDY latch is set; if it is
   * not, the OUT packet has not landed -- report no-data so the caller can
   * retry on the next IRQ rather than draining a stale or empty bank. */
  if ((reg->BRDYSTS & (uint16_t)k_ra8_usb_dcp_pipe0_bit) == 0U) {
    return k_ra8_err_no_data;
  }
  /* Disable the one-shot DCP BRDY and W0C-clear the latch before draining
   * (FSP order; protects DBLB bank edges and prevents an ISR re-storm).
   * HUM Ch 36.2.11 "BRDYENB" p 1982 / Ch 36.2.13 "BRDYSTS" p 1984. */
  reg->BRDYENB = (uint16_t)(reg->BRDYENB & (uint16_t)~(uint16_t)k_ra8_usb_dcp_pipe0_bit);
  reg->BRDYSTS = (uint16_t)~(uint16_t)k_ra8_usb_dcp_pipe0_bit;
 
  priv_select_cfifo(reg, 0U, false);
  if (priv_wait_frdy(reg) != k_ra8_ok) {
    priv_dcp_pid(reg, k_ra8_pid_nak);
    return k_ra8_err_hw_timeout;
  }
  /* HUM Ch 36.2.8 "CFIFOCTR : CFIFO Port Control Register", p 1979 */
  const uint16_t dtln = (uint16_t)(reg->CFIFOCTR & k_ra8_fifoctr_dtln);
  if (dtln == 0U) {
    reg->CFIFOCTR = (uint16_t)k_ra8_fifoctr_bclr;
  } else {
    const uint16_t take = (dtln < cap) ? dtln : cap;
    priv_fifo_read(reg, buf, take);
  }
  *out_rx = dtln;
  priv_dcp_pid(reg, k_ra8_pid_nak);
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_host_data_phase(volatile r_usb_regs_t* reg,
                                          const ra8_usb_setup_t* setup,
                                          uint8_t*               data,
                                          uint16_t               data_len,
                                          uint16_t*              out_rx,
                                          bool*                  out_is_read)
{
  *out_rx      = 0U;
  bool is_read = false;
  if (setup->w_length > 0U) {
    if ((setup->bm_request_type & (uint16_t)k_ra8_usb_setup_dir_in) != 0U) {
      if (data != nullptr) {
        is_read = true;
      }
    }
  }
  *out_is_read        = is_read;
  const uint16_t mxps = (uint16_t)(reg->DCPMAXP & (uint16_t)k_ra8_usb_dcpmaxp_mxps);
  uint16_t       want = setup->w_length;
  if (data_len < want) {
    want = data_len;
  }
  /* Control-OUT with a data stage (e.g. DFU_DNLOAD): drive the payload to the
   * device; the opposite-direction (IN) zero-length status stage follows. */
  if ((setup->w_length > 0U) && !is_read && (data != nullptr)) {
    s_host_ctrl_stage    = (uint8_t)k_ra8_usb_cs_data_out;
    const ra8_err_t oerr = internal_host_ctrl_data_out(reg, data, want, mxps);
    if (oerr == k_ra8_ok) {
      s_host_ctrl_stage = (uint8_t)k_ra8_usb_cs_data_done;
    }
    return oerr;
  }
  if (!is_read) {
    return k_ra8_ok;
  }
  s_host_ctrl_stage    = (uint8_t)k_ra8_usb_cs_data_in;
  const ra8_err_t derr = internal_host_ctrl_data_in(reg, data, want, mxps, out_rx);
  if (derr == k_ra8_ok) {
    s_host_ctrl_stage = (uint8_t)k_ra8_usb_cs_data_done;
  }
  return derr;
}
 
ra8_err_t ra8_usb_host_control_xfer(ra8_usb_speed_t        speed,
                                    const ra8_usb_setup_t* setup,
                                    uint8_t*               data,
                                    uint16_t               data_len,
                                    uint16_t*              out_received)
{
  RA8_CHECK_NULL_PTR(setup, s_tag, "host_control_xfer: setup");
  volatile r_usb_regs_t* reg = priv_pick(speed);
  if (reg == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  s_host_ctrl_stage    = (uint8_t)k_ra8_usb_cs_begin;
  const ra8_err_t serr = internal_host_ctrl_setup(reg, setup);
  if (serr != k_ra8_ok) {
    return serr;
  }
  s_host_ctrl_stage       = (uint8_t)k_ra8_usb_cs_setup;
  uint16_t        rx      = 0U;
  bool            is_read = false;
  const ra8_err_t derr    = internal_host_data_phase(reg, setup, data, data_len, &rx, &is_read);
  if (derr != k_ra8_ok) {
    return derr;
  }
  if (out_received != nullptr) {
    *out_received = rx;
  }
  s_host_ctrl_stage     = (uint8_t)k_ra8_usb_cs_status;
  const ra8_err_t sterr = internal_host_ctrl_status(reg, is_read);
  if (sterr == k_ra8_ok) {
    s_host_ctrl_stage = (uint8_t)k_ra8_usb_cs_done;
  }
  return sterr;
}