ra8_cgc_usb.c

Go to the documentation of this file.

 
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_cgc.h"
#include "ra8_cgc_internal.h"
#include "ra8_cgc_regs.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_hw_err.h"
#include "ra8_log.h"
#include "ra8_mstp.h"
#include "ra8_mstp_regs.h"
#include "ra8_register_protection.h"
#include "ra8_system_regs.h"
#include "ra8_time_constants.h"
 
static const char* s_tag = "CGC";

static volatile uint8_t s_usb60ckcr_probe = 0U;

static volatile uint8_t s_pll2_status_probe = 0U;

typedef enum : uint32_t {
  /* The USBCKSREQ -> USBCKSRDY synchronizer chain crosses from ICLK
   * into the UCK clock domain (currently HOCO @ ~20 MHz before this
   * routine runs). Worst case is a few HOCO cycles plus the M85 spin
   * latency at 1 GHz. FSP polls this unbounded; we cap at ~600 us to
   * stay NASA-Rule-2-compliant while leaving four orders of magnitude
   * of slack over the worst-case real handshake. */
  k_ra8_usbfs_srdy_poll_limit = 200000U, 
  k_ra8_usbfs_div5_code       = 6U,      
  k_ra8_usbfs_div8_code       = 4U,      
} ra8_usbfs_clock_local_t;

typedef enum : uint32_t {
  k_ra8_mstpb11_usbfs_mask = (uint32_t)(1UL << 11), 
} ra8_usbfs_mstp_local_t;

typedef enum : uint16_t {
  k_ra8_pll2_max_quarters   = 3U,  
  k_ra8_pll2_usbfs_mul      = 80U, 
  k_ra8_pll2_usbfs_quarters = 0U,  
} ra8_pll2_local_t;

RA8_INTERNAL static ra8_err_t internal_wait_usbcksrdy(uint8_t expected)
{
  volatile const uint8_t* const usbckcr = ra8_sys_usbckcr();
  const uint8_t                 mask    = (uint8_t)(1U << k_ra8_usbckcr_bit_srdy);
  /* Bounded wait through ra8_hw_err.h: on host tests the ra8_fake_mmio
   * seam decides the poll (first-poll success unless a test arms a
   * fault), so the real timeout leg is reachable everywhere. */
  if (expected != 0U) {
    return ra8_hw_wait_flag_set8(usbckcr, mask, (uint32_t)k_ra8_usbfs_srdy_poll_limit);
  }
  return ra8_hw_wait_flag_clear8(usbckcr, mask, (uint32_t)k_ra8_usbfs_srdy_poll_limit);
}

RA8_INTERNAL static ra8_err_t internal_pll2_program_protected(uint32_t pll2ccr, uint16_t pll2ccr2)
{
  ra8_err_t err = k_ra8_ok;
  RA8_PROTECTED_WRITE(k_ra8_prcr_unlock_cgc)
  {
    /* HUM Ch 9.2.11 "PLL2CR : PLL2 Control Register" p 336 -- stop
     * PLL2 before writing PLL2CCR / PLL2CCR2. */
    *ra8_sys_pll2cr() = (uint8_t)k_ra8_pll2cr_stop;
    err               = priv_ra8_cgc_wait_oscsf_clear(k_ra8_oscsf_bit_pll2sf);
    if (err != k_ra8_ok) {
      ra8_log_error(s_tag, "pll2: stop wait timeout");
      break;
    }
    /* HUM Ch 9.2.10 "PLL2CCR : PLL2 Clock Control Register" p 335 */
    *ra8_sys_pll2ccr() = pll2ccr;
    /* HUM Ch 9.2.12 "PLL2CCR2 : PLL2 Clock Control Register 2" p 335 */
    *ra8_sys_pll2ccr2() = pll2ccr2;
    *ra8_sys_pll2cr()   = (uint8_t)k_ra8_pll2cr_run;
    err                 = priv_ra8_cgc_wait_oscsf_set(k_ra8_oscsf_bit_pll2sf);
    if (err != k_ra8_ok) {
      ra8_log_error(s_tag, "pll2: lock wait timeout");
      break;
    }
  }
  return err;
}

ra8_err_t ra8_cgc_pll2_enable(uint8_t mul_int, uint8_t mul_quarters, ra8_plodiv_t p_div_code)
{
  if (mul_int == 0U) {
    return k_ra8_err_invalid_arg;
  }
  if ((uint16_t)mul_quarters > (uint16_t)k_ra8_pll2_max_quarters) {
    return k_ra8_err_invalid_arg;
  }
 
  ra8_log_info_val(s_tag, "pll2 enable mul_int", (uint32_t)mul_int);
 
  /* Idempotency (HUM Ch 9): never re-program a running PLL2 -- if FS
   * path already locked it, the HS path's "same VCO" request is a no-op. */
  if ((*ra8_sys_oscsf() & (uint8_t)(1U << k_ra8_oscsf_bit_pll2sf)) != 0U) {
    ra8_log_info(s_tag, "pll2 already locked -- skip re-program");
    return k_ra8_ok;
  }
 
  /* PLL2CCR (32-bit, HUM Ch 9.2.9): PLL2MULNF[7:6] | PLL2MUL[16:8]. */
  const uint32_t mul_quarters_field =
    ((uint32_t)mul_int * (uint32_t)k_ra8_cgc_quarters_per_unit) + (uint32_t)mul_quarters;
  const uint32_t pll2ccr =
    ((mul_quarters_field & (uint32_t)k_ra8_pll2ccr_mask_quarters) << k_ra8_pllccr_shift_quarters) |
    ((uint32_t)k_ra8_plsrcsel_main << k_ra8_pllccr_shift_plsrcsel) |
    ((uint32_t)k_ra8_plidiv_div2 & (uint32_t)k_ra8_pll2ccr_mask_plidiv);
 
  /* PLL2CCR2: P from caller; Q/R fixed at /6. Code 0 is prohibited
   * per HUM Ch 9.2.10/9.2.12 (drops the whole 16-bit write). */
  const uint16_t pll2ccr2 =
    (uint16_t)(((uint16_t)k_ra8_plodiv_div6 << k_ra8_pllccr2_shift_plodivr) |
               ((uint16_t)k_ra8_plodiv_div6 << k_ra8_pllccr2_shift_plodivq) |
               ((uint16_t)p_div_code << k_ra8_pllccr2_shift_plodivp));
 
  const ra8_err_t err = internal_pll2_program_protected(pll2ccr, pll2ccr2);
  if (err != k_ra8_ok) {
    return err;
  }
  ra8_log_info(s_tag, "pll2 locked");
  return k_ra8_ok;
}

RA8_INTERNAL static ra8_err_t internal_usbckcr_switch_to_pll2p_div5(void)
{
  ra8_err_t err = k_ra8_ok;
  RA8_PROTECTED_WRITE(k_ra8_prcr_unlock_cgc)
  {
    const uint8_t sreq_mask = (uint8_t)(1U << k_ra8_usbckcr_bit_sreq);
    *ra8_sys_usbckcr()      = sreq_mask;
    err                     = internal_wait_usbcksrdy(1U);
    if (err != k_ra8_ok) {
      ra8_log_error(s_tag, "usbfs: SRDY=1 timeout");
      break;
    }
    *ra8_sys_usbckdivcr() = (uint8_t)k_ra8_usbfs_div5_code;
    const uint8_t src     = (uint8_t)((uint8_t)k_ra8_usbcksel_pll2p & k_ra8_usbckcr_mask_sel);
    *ra8_sys_usbckcr()    = (uint8_t)(src | sreq_mask);
    *ra8_sys_usbckcr()    = src;
    err                   = internal_wait_usbcksrdy(0U);
    if (err != k_ra8_ok) {
      ra8_log_error(s_tag, "usbfs: SRDY=0 timeout");
      break;
    }
  }
  return err;
}

ra8_err_t ra8_cgc_usbfs_clock_enable(void)
{
  ra8_log_info(s_tag, "usbfs clock enable");
 
  /* Step 1: bring up PLL2 to land 240 MHz on PLL2P. */
  const ra8_err_t pll2_err = ra8_cgc_pll2_enable((uint8_t)k_ra8_pll2_usbfs_mul,
                                                 (uint8_t)k_ra8_pll2_usbfs_quarters,
                                                 k_ra8_plodiv_div4);
  if (pll2_err != k_ra8_ok) {
    ra8_log_error_val(s_tag, "usbfs: pll2 enable failed", (uint32_t)pll2_err);
    return pll2_err;
  }
 
  /* Step 2a: Force USBFS into module-stop (MSTPB11 = 1) BEFORE the SREQ
   * handshake. HUM Ch 9 "Clock selection switching procedure" step 1
   * (p367 / p370 / p373 / p378 / p381) is mandatory whenever USBCKDIVCR
   * is moved off 1/1; we are programming /5 below. MSTPCR is NOT
   * PRCR-protected. ra8_usb_device_init() releases MSTPB11 again later
   * via the ref-counted ra8_mstp_enable() path. */
  ra8_mstp()->MSTPCRB |= (uint32_t)k_ra8_mstpb11_usbfs_mask;
  (void)ra8_mstp()->MSTPCRB; /* HUM 11.2.7 Note 2: read-back. */
 
  /* Step 2a': Ensure HOCO is running. USBCKCR's reset-default source is
   * HOCO; the SREQ -> SRDY synchronizer crosses from ICLK into the
   * CURRENT UCK source's clock domain (HOCO). If HOCO is stopped
   * (HCSTP=1, the chip reset state) the handshake never completes -- we
   * observed USBCKCR=0x40 (SREQ=1, SRDY=0) with HOCOCR=0x01 and
   * OSCSF.HOCOSF=0 on real silicon. ra8_cgc_init() leaves HOCO stopped
   * because it switches SCKSCR to PLL1; we have to start HOCO here so
   * the source clock for USBCKCR is alive when SREQ is asserted.
   * HOCOCR IS PRCR-protected (HUM Ch 9; FSP wraps writes inside its
   * BSP_PRV_PRCR_UNLOCK / BSP_PRV_PRCR_LOCK window -- writes outside
   * the window are silently dropped, which is what we observed when
   * an earlier attempt left HOCOCR at 0x01 after the store). */
  ra8_err_t hoco_err = k_ra8_ok;
  RA8_PROTECTED_WRITE(k_ra8_prcr_unlock_cgc)
  {
    volatile uint8_t* const hococr = ra8_sys_hococr();
    if ((*hococr & (uint8_t)(1U << k_ra8_hococr_hcstp)) != 0U) {
      *hococr = (uint8_t)((uint8_t)*hococr & (uint8_t)~(1U << k_ra8_hococr_hcstp));
    }
  }
  /* OSCSF.HOCOSF poll outside PRCR window (read-only register). */
  hoco_err = priv_ra8_cgc_wait_oscsf_set(k_ra8_oscsf_bit_hocosf);
  if (hoco_err != k_ra8_ok) {
    ra8_log_error(s_tag, "usbfs: HOCO stabilization timeout");
    return hoco_err;
  }
  ra8_log_info(s_tag, "usbfs: HOCO running for USBCKCR source");
 
  /* Step 2b: USBCKCR / USBCKDIVCR handshake. */
  const ra8_err_t err = internal_usbckcr_switch_to_pll2p_div5();
  if (err != k_ra8_ok) {
    return err;
  }
  ra8_log_info(s_tag, "usbfs clock ready (PLL2P/5 = 48 MHz)");
  return k_ra8_ok;
}

typedef enum : uint32_t {
  k_ra8_usbhs_srdy_poll_limit = 200000U, 
  k_ra8_usbhs_div4_code       = 2U,      
} ra8_usbhs_clock_local_t;

typedef enum : uint32_t {
  k_ra8_mstpb12_usbhs_mask = (uint32_t)(1UL << 12), 
} ra8_usbhs_mstp_local_t;

RA8_INTERNAL static ra8_err_t internal_wait_usb60cksrdy(uint8_t expected)
{
  volatile const uint8_t* const usb60ckcr = ra8_sys_usb60ckcr();
  const uint8_t                 mask      = (uint8_t)(1U << k_ra8_usbckcr_bit_srdy);
  /* Bounded wait through ra8_hw_err.h: on host tests the ra8_fake_mmio
   * seam decides the poll (first-poll success unless a test arms a
   * fault), so the real timeout leg is reachable everywhere. */
  if (expected != 0U) {
    return ra8_hw_wait_flag_set8(usb60ckcr, mask, (uint32_t)k_ra8_usbhs_srdy_poll_limit);
  }
  return ra8_hw_wait_flag_clear8(usb60ckcr, mask, (uint32_t)k_ra8_usbhs_srdy_poll_limit);
}

RA8_INTERNAL static ra8_err_t internal_usb60ckcr_switch_to_pll2p_div4(void)
{
  ra8_err_t err = k_ra8_ok;
  RA8_PROTECTED_WRITE(k_ra8_prcr_unlock_cgc)
  {
    const uint8_t sreq_mask = (uint8_t)(1U << k_ra8_usbckcr_bit_sreq);
    const uint8_t srdy_mask = (uint8_t)(1U << k_ra8_usbckcr_bit_srdy);
    /* FSP `bsp_clocks.c` ::bsp_peripheral_clock_set sequence (HUM Ch 9
     * "Clock selection switching procedure"):
     *
     *   1. Set SREQ=1 with read-modify-write so the current SEL field
     *      is preserved (the reset-default source is HOCO; clobbering
     *      SEL to 0 also writes "HOCO" but loses the invariant that
     *      SREQ is asserted on top of the EXISTING source -- this
     *      matters when the previous source is no longer running).
     *   2. Spin-wait SRDY=1 (handshake acknowledge).
     *   3. Programme USB60CKDIVCR (peripheral clock now stopped).
     *   4. Write `source | SREQ | SRDY` -- the SRDY bit being set in
     *      the same write is mandatory per FSP (line 2896 of
     *      `bsp_clocks.c`); on RA8 Gen2 silicon, omitting SRDY here
     *      makes the subsequent SREQ-clear hang at step 6.
     *   5. Clear SREQ via read-modify-write (peripheral clock starts).
     *   6. Spin-wait SRDY=0 (start acknowledged).                       */
    volatile uint8_t* const ckcr = ra8_sys_usb60ckcr();
    *ckcr                        = (uint8_t)(*ckcr | sreq_mask);
    err                          = internal_wait_usb60cksrdy(1U);
    if (err != k_ra8_ok) {
      ra8_log_error(s_tag, "usbhs: SRDY=1 timeout");
      break;
    }
    *ra8_sys_usb60ckdivcr() = (uint8_t)k_ra8_usbhs_div4_code;
    const uint8_t src       = (uint8_t)((uint8_t)k_ra8_usbcksel_pll2p & k_ra8_usbckcr_mask_sel);
    *ckcr                   = (uint8_t)(src | sreq_mask | srdy_mask);
    *ckcr                   = (uint8_t)(*ckcr & (uint8_t)~sreq_mask);
    err                     = internal_wait_usb60cksrdy(0U);
    if (err != k_ra8_ok) {
      ra8_log_error(s_tag, "usbhs: SRDY=0 timeout");
      break;
    }
  }
  /* Diagnostic witnesses -- read OUTSIDE the PRCR window since
   * USB60CKCR / OSCSF reads are not protected. */
  s_usb60ckcr_probe   = *ra8_sys_usb60ckcr();
  s_pll2_status_probe = *ra8_sys_oscsf();
  return err;
}
 
ra8_err_t priv_ra8_cgc_ensure_hoco_running_for_usb_ck(void)
{
  RA8_PROTECTED_WRITE(k_ra8_prcr_unlock_cgc)
  {
    volatile uint8_t* const hococr = ra8_sys_hococr();
    if ((*hococr & (uint8_t)(1U << k_ra8_hococr_hcstp)) != 0U) {
      *hococr = (uint8_t)((uint8_t)*hococr & (uint8_t)~(1U << k_ra8_hococr_hcstp));
    }
  }
  /* On host tests the OSCSF wait consults the ra8_fake_mmio seam and
   * succeeds on its first poll unless a test arms a fault -- no HOCOSF
   * RAM seeding is needed for callers (USB60CKCR / ESWCKCR SREQ->SRDY
   * handshakes) to make progress. */
  return priv_ra8_cgc_wait_oscsf_set(k_ra8_oscsf_bit_hocosf);
}

ra8_err_t ra8_cgc_usbhs_pll_enable(void)
{
  ra8_log_info(s_tag, "usbhs phy clock enable");
 
  /* Step 1: HUM Ch 9.2.21 "OSCSF : Oscillation Stabilization Flag
   * Register", p 344. The USBHS PHY's 12 MHz reference is derived
   * from the main XTAL; without MOSCSF=1 the PHY cannot lock. */
  const ra8_err_t osc_err = priv_ra8_cgc_wait_oscsf_set(k_ra8_oscsf_bit_moscsf);
  if (osc_err != k_ra8_ok) {
    ra8_log_error_val(s_tag, "usbhs: main xtal not stable", (uint32_t)osc_err);
    return osc_err;
  }
 
  /* Step 2: bring up PLL2 to land 240 MHz on PLL2P. Reuse the FS path's
   * configuration -- 24 MHz XTAL / PL2IDIV(/2) * MUL(80) = 960 MHz VCO,
   * PL2ODIVP=/4 -> PLL2P = 240 MHz. PLL2P / 4 = 60.000 MHz on USB60CLK
   * exactly (0 ppm vs the USBHS 60 MHz spec target). ra8_cgc_pll2_enable
   * is idempotent w.r.t. the PRCR window and tolerates being called
   * once per USB controller bring-up (FS path also calls it). */
  const ra8_err_t pll2_err = ra8_cgc_pll2_enable((uint8_t)k_ra8_pll2_usbfs_mul,
                                                 (uint8_t)k_ra8_pll2_usbfs_quarters,
                                                 k_ra8_plodiv_div4);
  if (pll2_err != k_ra8_ok) {
    ra8_log_error_val(s_tag, "usbhs: pll2 enable failed", (uint32_t)pll2_err);
    return pll2_err;
  }
 
  /* Step 3: Force USBHS into module-stop (MSTPB12 = 1) BEFORE the SREQ
   * handshake. HUM Ch 9 "Clock selection switching procedure" step 1 is
   * mandatory whenever USB60CKDIVCR is moved off 1/1 (we are programming
   * /4 below). MSTPCR is NOT PRCR-protected. ra8_usb_device_init() will
   * release MSTPB12 again later via the ref-counted ra8_mstp_enable
   * path for k_ra8_mstp_usbhs. */
  ra8_mstp()->MSTPCRB |= (uint32_t)k_ra8_mstpb12_usbhs_mask;
  (void)ra8_mstp()->MSTPCRB; /* HUM 11.2.7 Note 2: read-back. */
 
  /* Step 4: Ensure HOCO is running so the SREQ->SRDY synchronizer can
   * drain (USB60CKCR's reset-default source is HOCO). */
  const ra8_err_t hoco_err = priv_ra8_cgc_ensure_hoco_running_for_usb_ck();
  if (hoco_err != k_ra8_ok) {
    ra8_log_error(s_tag, "usbhs: HOCO stabilization timeout");
    return hoco_err;
  }
 
  /* Step 5: USB60CKCR / USB60CKDIVCR SREQ/SRDY handshake. */
  const ra8_err_t err = internal_usb60ckcr_switch_to_pll2p_div4();
  if (err != k_ra8_ok) {
    return err;
  }
 
  ra8_log_info(s_tag, "usbhs phy clock ready (PLL2P/4 = 60 MHz)");
  return k_ra8_ok;
}