ra8_usb.c

Go to the documentation of this file.

 
#include "ra8_usb.h"
 
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_hw_err.h"
#include "ra8_mstp.h"
#include "ra8_usb_internal.h"
#include "ra8_usb_regs.h"
 
static const char* s_tag = "USB";
 
/* =============================================================================
 * Tunables / sizing
 * =============================================================================
 */

typedef enum : uint32_t {
  k_ra8_usb_frdy_poll_limit = 10000000UL, 
  /* Short-bound FRDY poll used by queue_out's post-BCLR DBLB-second-
   * bank check. Must be tight (we're typically on the IRQ-time
   * drain path) but big enough to absorb the few cycles between BCLR
   * and the FIFO pointer flipping to the other bank when DBLB is on.
   * 256 iters x ~3 cycles == sub-microsecond at 1 GHz. */
  k_ra8_usb_dblb_frdy_poll_limit = 256UL, 
  /* CFIFOSEL CURPIPE/ISEL readback settle bound (a handful of bus
   * clocks; generous to stay fake-safe). */
  k_ra8_usb_fifosel_settle_limit = 1000UL, 
} ra8_usb_internal_lim32_t;
/* =============================================================================
 * Internal helpers
 * =============================================================================
 */

volatile r_usb_regs_t* priv_pick(ra8_usb_speed_t speed)
{
  if (speed == k_ra8_usb_speed_fs) {
    return ra8_usb_fs();
  }
  if (speed == k_ra8_usb_speed_hs) {
    return ra8_usb_hs();
  }
  return nullptr;
}

ra8_mstp_t priv_mstp(ra8_usb_speed_t speed)
{
  return (speed == k_ra8_usb_speed_hs) ? k_ra8_mstp_usbhs : k_ra8_mstp_usbfs;
}

void priv_rmw16(volatile uint16_t* reg, uint16_t set_mask, uint16_t clr_mask)
{
  const uint16_t old     = *reg;
  uint16_t       new_val = (uint16_t)(old & (uint16_t)~clr_mask);
  new_val                = (uint16_t)(new_val | set_mask);
  *reg                   = new_val;
}

bool priv_is_hs(volatile const r_usb_regs_t* reg)
{
  return reg == ra8_usb_hs();
}

void priv_select_cfifo(volatile r_usb_regs_t* reg, uint16_t pipe_num, bool is_in_dir)
{
  /* HUM Ch 36.2.7 / 37.2.8 CFIFOSEL p 1976 / 2071. The USBHS module
   * (IP1) requires MBW=32 -- FSP wires `USB1_CFIFO_MBW = USB_MBW_32`
   * unconditionally for this controller. With MBW=16 the SIE refuses
   * to arm an IN response (BSTS reads 0 and PID stays effectively
   * NAK on the wire even though DCPCTR.PID=BUF), and the host sees
   * unending NAKs / "device descriptor read/N, error -110". The
   * USBFS module (IP0) keeps MBW=16. */
  uint16_t sel = (uint16_t)(pipe_num & k_ra8_fifosel_curpipe);
  if (priv_is_hs(reg)) {
    sel = (uint16_t)(sel | k_ra8_fifosel_mbw_32);
  } else {
    sel = (uint16_t)(sel | k_ra8_fifosel_mbw_16);
  }
  if (is_in_dir) {
    sel = (uint16_t)(sel | k_ra8_fifosel_isel);
  }
  reg->CFIFOSEL = sel;
  /* FSP (usb_cstd_chg_curpipe) polls the CURPIPE/ISEL readback until the
   * window switch takes effect; without this a FIFO access issued right
   * after the select can land on the previous pipe's buffer (observed on
   * hardware as a bulk-OUT payload stuck with INBUFM set, never sent). */
  const uint16_t key = (uint16_t)(sel & (uint16_t)(k_ra8_fifosel_curpipe | k_ra8_fifosel_isel));
  for (uint32_t i = 0U; i < (uint32_t)k_ra8_usb_fifosel_settle_limit; ++i) {
    const uint16_t now =
      (uint16_t)(reg->CFIFOSEL & (uint16_t)(k_ra8_fifosel_curpipe | k_ra8_fifosel_isel));
    if (now == key) {
      return;
    }
  }
}

ra8_err_t priv_wait_frdy(volatile r_usb_regs_t* reg)
{
  /* HUM Ch 36.2.8 "CFIFOCTR : CFIFO Port Control Register", p 1979.
   * Loop bound is large (~10 ms ceiling at 1 GHz) because the DCP
   * is single-buffered: between consecutive EP0 IN chunks FRDY stays
   * low until the host actually pulls the previous chunk off the
   * wire. See ra8_usb_internal_lim32_t for the rationale. */
  for (uint32_t i = 0U; i < (uint32_t)k_ra8_usb_frdy_poll_limit; ++i) {
    const bool frdy = ((reg->CFIFOCTR & k_ra8_fifoctr_frdy) != 0U);
#if defined(RA8_OFF_TARGET) && defined(UNIT_TEST)
    /* Host MMIO fault seam, keyed on CFIFOCTR (the polled register). */
    if (ra8_fake_mmio_wait_eval(&reg->CFIFOCTR, i, frdy)) {
      return k_ra8_ok;
    }
#else
    if (frdy) {
      return k_ra8_ok;
    }
#endif
  }
  return k_ra8_err_hw_timeout;
}

void priv_dcp_pid(volatile r_usb_regs_t* reg, ra8_usb_pid_t pid)
{
  /* HUM Ch 36.2.21 "DCPCTR : DCP Control Register", p 1999 */
  priv_rmw16(&reg->DCPCTR, pid, k_ra8_pid_mask);
}

void priv_pipe_pid(volatile r_usb_regs_t* reg, uint8_t pipe_num, ra8_usb_pid_t pid)
{
  /* HUM Ch 36.2.27 "PIPEnCTR : PIPE n Control Register", p 2005 */
  const uint8_t idx = (uint8_t)(pipe_num - 1U);
  priv_rmw16(&reg->PIPECTR[idx], pid, k_ra8_pid_mask);
}
 
/* =============================================================================
 * Pipe-config word packing + quiesce (shared device/host helpers)
 * =============================================================================
 */

uint16_t priv_pipebuf_word(uint8_t pipe_num, uint16_t max_packet)
{
  const uint16_t mps_blocks = (uint16_t)(((uint32_t)max_packet + (k_ra8_pipebuf_block_bytes - 1U)) /
                                         k_ra8_pipebuf_block_bytes);
  const uint16_t blocks_per_pipe = (uint16_t)(mps_blocks * 2U);
  const uint16_t bufsize_field   = (uint16_t)(blocks_per_pipe - 1U);
  const uint16_t bufnmb_field =
    (uint16_t)(8U + (uint16_t)((uint16_t)(pipe_num - 1U) * blocks_per_pipe));
  return (uint16_t)((bufsize_field << k_ra8_pipebuf_bufsize_shift) |
                    (bufnmb_field & k_ra8_pipebuf_bufnmb_mask));
}

uint16_t
priv_pipecfg_word(uint8_t ep_addr, ra8_usb_ep_dir_t dir, ra8_usb_ep_type_t type, bool dblb_in)
{
  uint16_t cfg = (uint16_t)((uint16_t)ep_addr & k_ra8_pipecfg_epnum_mask);
  if (dir == k_ra8_usb_ep_dir_in) {
    cfg = (uint16_t)(cfg | k_ra8_pipecfg_dir_in);
  }
  if (type == k_ra8_usb_ep_type_bulk) {
    cfg = (uint16_t)(cfg | k_ra8_pipecfg_type_bulk);
    cfg = (uint16_t)(cfg | k_ra8_pipecfg_shtnak);
    /* Device OUT (receive): double-buffer so the host's next packet lands
     * in bank B while the ISR drains bank A. Single-banked OUT NAKs (and
     * wedges) the host's next packet during the per-packet re-arm of a
     * sustained multi-packet WRITE data phase. PIPEBUF already reserves
     * 2*MPS, and internal_irq_complete_out drains every ready bank per
     * ISR. Device IN stays single-banked (the free-bank handshake after
     * an MPS-exact fill is unreliable -- see header). HUM Ch 36.2.24. */
    if (dir == k_ra8_usb_ep_dir_out) {
      cfg = (uint16_t)(cfg | k_ra8_pipecfg_dblb);
    }
    /* DBLB on bulk IN only when the caller asks (host-mode IN). */
    if (dblb_in) {
      if (dir == k_ra8_usb_ep_dir_in) {
        cfg = (uint16_t)(cfg | k_ra8_pipecfg_dblb);
      }
    }
  } else if (type == k_ra8_usb_ep_type_intr) {
    cfg = (uint16_t)(cfg | k_ra8_pipecfg_type_intr);
  } else {
    cfg = (uint16_t)(cfg | k_ra8_pipecfg_type_iso);
  }
  return cfg;
}

void priv_pipe_quiesce(volatile r_usb_regs_t* reg, uint8_t pipe_num)
{
  const uint16_t pipe_bit = (uint16_t)(1U << pipe_num);
  reg->BRDYENB            = (uint16_t)(reg->BRDYENB & (uint16_t)~pipe_bit);
  reg->NRDYENB            = (uint16_t)(reg->NRDYENB & (uint16_t)~pipe_bit);
  reg->BEMPENB            = (uint16_t)(reg->BEMPENB & (uint16_t)~pipe_bit);
  priv_pipe_pid(reg, pipe_num, k_ra8_pid_nak);
}
 
/* =============================================================================
 * CFIFO byte mover (shared device/host data path)
 * =============================================================================
 */

typedef enum : uint8_t {
  k_ra8_usb_shift_b1 = 8U,  
  k_ra8_usb_shift_b2 = 16U, 
  k_ra8_usb_shift_b3 = 24U, 
} ra8_usb_fifo_shift_t;

typedef uint32_t __attribute__((may_alias)) /* ATTR-OK: cppcheck 2.13 rejects the C23 spelling */
ra8_usb_cfifo32_t;

RA8_INTERNAL
static void
internal_fifo_write_hs_tail(volatile r_usb_regs_t* reg, const uint8_t* data, uint16_t len)
{
  const uint16_t tail = (uint16_t)(len & 0x3U);
  if (tail == 0U) {
    return;
  }
  const uint16_t sel_save = reg->CFIFOSEL;
  const uint16_t sel_base = (uint16_t)(sel_save & (uint16_t)~(uint16_t)k_ra8_fifosel_mbw_msk);
  uint16_t       offset   = (uint16_t)(len & (uint16_t)~(uint16_t)0x3U);
  /* For USBHS in little-endian mode, FSP writes the 16-bit residual
   * halfword to CFIFOH (CFIFO base + 0x02) and the 8-bit residual
   * byte to CFIFOHH (CFIFO base + 0x03), NOT to CFIFO itself. See
   * FSP r_usb_reg_access.h: USB1_CFIFO16=USB_M1->CFIFOH and
   * USB1_CFIFO8=USB_M1->CFIFOHH (in USB_CFG_LITTLE branch). The
   * chip uses these address aliases to commit the trailing 0..3
   * bytes when MBW is narrowed; a write to CFIFO at offset +0x00
   * in MBW=16/8 mode is silently dropped on USBHS, leaving DTLN
   * unchanged at 4N (verified empirically: 18-byte push showed
   * DTLN=16 instead of 18, and Linux saw -EOVERFLOW). */
  volatile uint16_t* const cfifoh  = (volatile uint16_t*)((uintptr_t)&reg->CFIFO + 2U);
  volatile uint8_t* const  cfifohh = (volatile uint8_t*)((uintptr_t)&reg->CFIFO + 3U);
  if ((tail & 0x2U) != 0U) {
    reg->CFIFOSEL     = (uint16_t)(sel_base | k_ra8_fifosel_mbw_16);
    const uint16_t lo = (uint16_t)data[offset + 0U];
    const uint16_t hi = (uint16_t)data[offset + 1U];
    *cfifoh           = (uint16_t)(lo | (uint16_t)(hi << k_ra8_usb_byte_bits));
    offset            = (uint16_t)(offset + 2U);
  }
  if ((tail & 0x1U) != 0U) {
    reg->CFIFOSEL = (uint16_t)(sel_base | k_ra8_fifosel_mbw_8);
    *cfifohh      = data[offset];
  }
  reg->CFIFOSEL = sel_save;
}

RA8_INTERNAL
static void
internal_fifo_write_hs_head(volatile r_usb_regs_t* reg, const uint8_t* data, uint16_t len)
{
  volatile ra8_usb_cfifo32_t* const cfifo32 = (volatile ra8_usb_cfifo32_t*)(uintptr_t)&reg->CFIFO;
  const uint16_t                    quads   = (uint16_t)(len >> 2U);
  for (uint16_t i = 0U; i < quads; ++i) {
    const uint32_t b0 = (uint32_t)data[(4U * i) + 0U];
    const uint32_t b1 = (uint32_t)data[(4U * i) + 1U];
    const uint32_t b2 = (uint32_t)data[(4U * i) + 2U];
    const uint32_t b3 = (uint32_t)data[(4U * i) + 3U];
    *cfifo32 =
      b0 | (b1 << k_ra8_usb_shift_b1) | (b2 << k_ra8_usb_shift_b2) | (b3 << k_ra8_usb_shift_b3);
  }
}

void priv_fifo_write(volatile r_usb_regs_t* reg, const uint8_t* data, uint16_t len)
{
  /* HUM Ch 36.2.5 / 37.2.7 CFIFO p 1973 / 2070. CFIFO access width
   * must match CFIFOSEL.MBW. USBHS = 32-bit, USBFS = 16-bit. */
  if (priv_is_hs(reg)) {
    internal_fifo_write_hs_head(reg, data, len);
    internal_fifo_write_hs_tail(reg, data, len);
    return;
  }
  /* USBFS / MBW=16 path. */
  const uint16_t even = (uint16_t)(len >> 1U);
  for (uint16_t i = 0U; i < even; ++i) {
    const uint16_t lo = (uint16_t)data[(2U * i) + 0U];
    const uint16_t hi = (uint16_t)data[(2U * i) + 1U];
    reg->CFIFO        = (uint16_t)(lo | (uint16_t)(hi << k_ra8_usb_byte_bits));
  }
  if ((len & 1U) != 0U) {
    /* Trailing odd byte: switch to MBW=8 and write one byte. A 16-bit
     * write here adds a phantom zero byte to DTLN and the host sees
     * EOVERFLOW on every odd-length descriptor. Mirrors FSP
     * hw_usb_write_fifo8 for USBFS. HUM Ch 36.2.6 CFIFOSEL.MBW. */
    const uint16_t sel_save = reg->CFIFOSEL;
    const uint16_t sel_8 =
      (uint16_t)((sel_save & (uint16_t)~(uint16_t)k_ra8_fifosel_mbw_msk) | k_ra8_fifosel_mbw_8);
    volatile uint8_t* const cfifo8 = (volatile uint8_t*)(uintptr_t)&reg->CFIFO;
    reg->CFIFOSEL                  = sel_8;
    *cfifo8                        = data[len - 1U];
    reg->CFIFOSEL                  = sel_save;
  }
}

RA8_INTERNAL
static void internal_fifo_read_hs_head(volatile r_usb_regs_t* reg, uint8_t* data, uint16_t len)
{
  volatile const ra8_usb_cfifo32_t* const cfifo32 =
    (volatile ra8_usb_cfifo32_t*)(uintptr_t)&reg->CFIFO;
  const uint16_t quads = (uint16_t)(len >> 2U);
  for (uint16_t i = 0U; i < quads; ++i) {
    const uint32_t word = *cfifo32;
    data[(4U * i) + 0U] = (uint8_t)(word & k_ra8_usb_byte_mask);
    data[(4U * i) + 1U] = (uint8_t)((word >> k_ra8_usb_shift_b1) & k_ra8_usb_byte_mask);
    data[(4U * i) + 2U] = (uint8_t)((word >> k_ra8_usb_shift_b2) & k_ra8_usb_byte_mask);
    data[(4U * i) + 3U] = (uint8_t)((word >> k_ra8_usb_shift_b3) & k_ra8_usb_byte_mask);
  }
}

RA8_INTERNAL
static void internal_fifo_read_hs_tail(volatile r_usb_regs_t* reg, uint8_t* data, uint16_t len)
{
  const uint16_t tail = (uint16_t)(len & 0x3U);
  if (tail == 0U) {
    return;
  }
  /* HUM Ch 37.2.7 CFIFO: at MBW=32 the FIFO read pointer only advances
   * on 32-bit reads at CFIFO+0. Narrow CFIFOH/CFIFOHH reads at MBW=16/8
   * do not advance the pointer reliably (a 3-byte bulk-OUT packet drains
   * as bytes [0],[1],[0] when mixed). For the trailing 1..3 bytes of a
   * non-quadword packet we keep MBW=32 and consume one final 32-bit
   * word, extracting only the `tail` low-order bytes (the FIFO presents
   * unused-byte slots as don't-care). One read, one pointer advance,
   * no MBW transition. */
  const uint32_t word     = *(volatile ra8_usb_cfifo32_t*)(uintptr_t)&reg->CFIFO;
  const uint16_t off_base = (uint16_t)(len & (uint16_t)~(uint16_t)0x3U);
  const uint8_t  bytes[4] = {
    (uint8_t)(word & k_ra8_usb_byte_mask),
    (uint8_t)((word >> k_ra8_usb_shift_b1) & k_ra8_usb_byte_mask),
    (uint8_t)((word >> k_ra8_usb_shift_b2) & k_ra8_usb_byte_mask),
    (uint8_t)((word >> k_ra8_usb_shift_b3) & k_ra8_usb_byte_mask),
  };
  for (uint16_t i = 0U; i < tail; ++i) {
    data[off_base + i] = bytes[i];
  }
}

void priv_fifo_read(volatile r_usb_regs_t* reg, uint8_t* data, uint16_t len)
{
  /* HUM Ch 37.2.7 "CFIFO : CFIFO Port Register" p 2070 */
  if (priv_is_hs(reg)) {
    internal_fifo_read_hs_head(reg, data, len);
    internal_fifo_read_hs_tail(reg, data, len);
    return;
  }
  /* USBFS / MBW=16 path. */
  const uint16_t even = (uint16_t)(len >> 1U);
  for (uint16_t i = 0U; i < even; ++i) {
    const uint16_t word = reg->CFIFO;
    data[(2U * i) + 0U] = (uint8_t)(word & k_ra8_usb_byte_mask);
    data[(2U * i) + 1U] = (uint8_t)((word >> k_ra8_usb_byte_bits) & k_ra8_usb_byte_mask);
  }
  if ((len & 1U) != 0U) {
    /* Trailing odd byte: switch to MBW=8 and read one byte so DTLN
     * advances by exactly 1. Mirrors FSP hw_usb_read_fifo8 for USBFS. */
    const uint16_t sel_save = reg->CFIFOSEL;
    const uint16_t sel_8 =
      (uint16_t)((sel_save & (uint16_t)~(uint16_t)k_ra8_fifosel_mbw_msk) | k_ra8_fifosel_mbw_8);
    volatile const uint8_t* const cfifo8 = (volatile uint8_t*)(uintptr_t)&reg->CFIFO;
    reg->CFIFOSEL                        = sel_8;
    data[len - 1U]                       = *cfifo8;
    reg->CFIFOSEL                        = sel_save;
  }
}
 
/* =============================================================================
 * Shared DCP chunk push (device DCP-IN + host control-write data path)
 * =============================================================================
 */

ra8_err_t priv_dcp_push_chunk(volatile r_usb_regs_t* reg, const uint8_t* p, uint16_t n)
{
  const ra8_err_t ready = priv_wait_frdy(reg);
  RA8_RETURN_ON_ERROR(ready, s_tag, "dcp_in_data: FRDY timeout (chunk)");
  priv_fifo_write(reg, p, n);
  /* HUM Ch 36.2.8 "CFIFOCTR : CFIFO Port Control Register", p 1979.
   *
   * 2026-05-20 attempt: FSP r_usb_plibusbip.c only sets BVAL on the
   * short last chunk (n < MPS), letting hardware auto-flag full-MPS
   * chunks. Tried that here; usb_cdc_echo dropped off the bus and
   * the chip didn't enumerate. Our synchronous multi-chunk push (vs
   * FSP's BRDY-IRQ-per-chunk) apparently requires the explicit BVAL
   * pulse on every chunk to commit each one before the next FRDY
   * poll. Keep the unconditional write. */
  reg->CFIFOCTR = k_ra8_fifoctr_bval;
  return k_ra8_ok;
}