ra8_cgc.c

Go to the documentation of this file.

 
#include "ra8_cgc.h"
 
#include <stdint.h>
 
#include "ra8_attributes.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_mrms_regs.h"
#include "ra8_mstp.h"
#include "ra8_mstp_regs.h"
#include "ra8_register_protection.h"
#include "ra8_sram.h"
#include "ra8_system_regs.h"
#include "ra8_time_constants.h"
 
static const char* s_tag = "CGC";

typedef enum : uint8_t {
  k_ra8_cgc_clock_count = 10U, 
} ra8_cgc_clock_count_t;

static uint32_t s_clock_hz[k_ra8_cgc_clock_count] = {
  [k_ra8_clock_id_cpuclk0] = k_ra8_moco_hz,
  [k_ra8_clock_id_cpuclk1] = k_ra8_moco_hz,
  [k_ra8_clock_id_iclk]    = k_ra8_moco_hz,
  [k_ra8_clock_id_pclka]   = k_ra8_moco_hz,
  [k_ra8_clock_id_pclkb]   = k_ra8_moco_hz,
  [k_ra8_clock_id_pclkc]   = k_ra8_moco_hz,
  [k_ra8_clock_id_pclkd]   = k_ra8_moco_hz,
  [k_ra8_clock_id_pclke]   = k_ra8_moco_hz,
  [k_ra8_clock_id_fclk]    = k_ra8_moco_hz,
  [k_ra8_clock_id_mriclk]  = k_ra8_moco_hz,
};

RA8_INTERNAL static void internal_publish_clocks(void)
{
  s_clock_hz[k_ra8_clock_id_cpuclk0] = k_ra8_cpuclk0_hz;
  s_clock_hz[k_ra8_clock_id_cpuclk1] = k_ra8_cpuclk1_hz;
  s_clock_hz[k_ra8_clock_id_iclk]    = k_ra8_iclk_hz;
  s_clock_hz[k_ra8_clock_id_pclka]   = k_ra8_pclka_hz;
  s_clock_hz[k_ra8_clock_id_pclkb]   = k_ra8_pclkb_hz;
  s_clock_hz[k_ra8_clock_id_pclkc]   = k_ra8_pclkc_hz;
  s_clock_hz[k_ra8_clock_id_pclkd]   = k_ra8_pclkd_hz;
  s_clock_hz[k_ra8_clock_id_pclke]   = k_ra8_pclke_hz;
  s_clock_hz[k_ra8_clock_id_fclk]    = k_ra8_fclk_hz;
  s_clock_hz[k_ra8_clock_id_mriclk]  = k_ra8_mriclk_hz;
}
 
ra8_err_t ra8_cgc_get_clock_hz(ra8_clock_id_t id, uint32_t* out_hz)
{
  if (out_hz == nullptr) {
    return k_ra8_err_null_ptr;
  }
  const uint8_t idx = (uint8_t)id;
  if (idx >= (uint8_t)(sizeof(s_clock_hz) / sizeof(s_clock_hz[0]))) {
    return k_ra8_err_invalid_arg;
  }
  *out_hz = s_clock_hz[idx];
  return k_ra8_ok;
}
 
/* =============================================================================
 * Local-only typed-enum vocabulary
 * =============================================================================
 */

typedef enum : uint32_t {
  k_ra8_cgc_osc_spin_limit  = 0x40000UL, 
  k_ra8_cgc_pll_spin_limit  = 0x40000UL, 
  k_ra8_cgc_mrm_spin_limit  = 0x40000UL, 
  k_ra8_cgc_vscr_spin_limit = 0x40000UL, 
  k_ra8_cgc_scik_spin_limit = 0x40000UL, 
} ra8_cgc_spin_t;

typedef enum : uint8_t {
  k_ra8_pfb_flush_dummy_reads = 3U, 
} ra8_cgc_dummy_count_t;

typedef enum : uint8_t {
  k_ra8_pllcr_bit_pllstp = 0U, 
} ra8_pllcr_bit_t;

typedef enum : uint8_t {
  k_ra8_pllcr_run  = 0x00U, 
  k_ra8_pllcr_stop = 0x01U, 
} ra8_pllcr_val_t;

typedef enum : uint16_t {
  k_ra8_cgc_pllmul_int_default = 250U, 
  k_ra8_cgc_pllmul_quarters    = 0U,   
} ra8_cgc_pll_mul_t;

typedef enum : uint8_t {
  k_ra8_scickcr_sel_pll1r = 0x08U,      
  k_ra8_scickcr_cksreq    = (1U << 6U), 
  k_ra8_scickcr_cksrdy    = (1U << 7U), 
} ra8_cgc_scickcr_bit_t;

typedef enum : uint8_t {
  k_ra8_scickdivcr_div4 = 0x03U, 
} ra8_cgc_scickdivcr_t;
 
ra8_err_t priv_ra8_cgc_wait_oscsf_set(uint8_t bit)
{
  /* HUM Ch 9.2.21 "OSCSF : Oscillation Stabilization Flag Register" p 344 */
  volatile const uint8_t* const oscsf = ra8_sys_oscsf();
  /* On host tests the bounded wait consults the ra8_fake_mmio seam: it
   * succeeds on the first poll unless a test arms a fault, so the real
   * poll/timeout legs run everywhere (T1-01, no off-target short-circuit). */
  return ra8_hw_wait_flag_set8(oscsf, (uint8_t)(1U << bit), (uint32_t)k_ra8_cgc_osc_spin_limit);
}
 
ra8_err_t priv_ra8_cgc_wait_oscsf_clear(uint8_t bit)
{
  /* HUM Ch 9.2.21 "OSCSF : Oscillation Stabilization Flag Register" p 344 */
  volatile const uint8_t* const oscsf = ra8_sys_oscsf();
  return ra8_hw_wait_flag_clear8(oscsf, (uint8_t)(1U << bit), (uint32_t)k_ra8_cgc_pll_spin_limit);
}

RA8_INTERNAL static void internal_clear_pfb(void)
{
  /* HUM Ch 59.4.3 "Frequency Change Procedure" p 3548 */
  /* Cross-reference: FSP bsp_clocks.c. */
  volatile uint32_t* const mrcpfb = ra8_mrms_mrcpfb();
  *mrcpfb                         = k_ra8_mrcpfb_disable;
  for (uint8_t i = 0U; i < k_ra8_pfb_flush_dummy_reads; i++) {
    (void)*mrcpfb;
  }
}

RA8_INTERNAL static ra8_err_t internal_set_vscr_not_high_v(void)
{
  /* HUM Ch 11.2.43 "VSCR : Voltage Scaling Control Register" p 477 */
  /* Cross-reference: FSP bsp_clocks.c. */
  volatile uint32_t* const vscr = ra8_sys_vscr();
  *vscr                         = k_ra8_vscr_bit_vscm;
 
  return ra8_hw_wait_flag_clear32(vscr,
                                  (uint32_t)k_ra8_vscr_bit_vscmtsf,
                                  (uint32_t)k_ra8_cgc_vscr_spin_limit);
}

RA8_INTERNAL static ra8_err_t internal_stop_pll1(void)
{
  /* HUM Ch 9.2.8 "PLLCR : PLL Control Register" p 333 */
  /* Cross-reference: FSP bsp_clocks.c. */
  *ra8_sys_pllcr() = k_ra8_pllcr_stop;
  /* HUM Ch 9.2.21 "OSCSF : Oscillation Stabilization Flag Register" p 344 */
  /* Cross-reference: FSP bsp_clocks.c. */
  return priv_ra8_cgc_wait_oscsf_clear(k_ra8_oscsf_bit_pll1sf);
}

RA8_INTERNAL static ra8_err_t internal_program_and_start_pll1(void)
{
  /* PLLMUL is encoded as (integer*4 + quarters) shifted by 6, which
   * simultaneously fills PLLMULNF[7:6] and PLLMUL[16:8]. */
  const uint32_t mul_quarters =
    ((uint32_t)k_ra8_cgc_pllmul_int_default * k_ra8_cgc_quarters_per_unit) +
    k_ra8_cgc_pllmul_quarters;
 
  const uint32_t pllccr =
    (((mul_quarters & k_ra8_pllccr_mask_quarters) << k_ra8_pllccr_shift_quarters) |
     ((uint32_t)k_ra8_plsrcsel_main << k_ra8_pllccr_shift_plsrcsel) |
     ((uint32_t)k_ra8_plidiv_div3 & k_ra8_pllccr_mask_plidiv));
 
  const uint16_t pllccr2 = (uint16_t)(((uint16_t)k_ra8_plodiv_div5 << k_ra8_pllccr2_shift_plodivr) |
                                      ((uint16_t)k_ra8_plodiv_div6 << k_ra8_pllccr2_shift_plodivq) |
                                      ((uint16_t)k_ra8_plodiv_div2 << k_ra8_pllccr2_shift_plodivp));
 
  /* HUM Ch 9.2.6 "PLLCCR : PLL Clock Control Register" p 331 */
  /* Cross-reference: FSP bsp_clocks.c. */
  *ra8_sys_pllccr() = pllccr;
  /* HUM Ch 9.2.7 "PLLCCR2 : PLL Clock Control Register 2" p 332 */
  /* Cross-reference: FSP bsp_clocks.c. */
  *ra8_sys_pllccr2() = pllccr2;
 
  /* HUM Ch 9.2.8 "PLLCR : PLL Control Register" p 333 */
  /* Cross-reference: FSP bsp_clocks.c. */
  *ra8_sys_pllcr() = k_ra8_pllcr_run;
  /* HUM Ch 9.2.21 "OSCSF : Oscillation Stabilization Flag Register" p 344 */
  /* Cross-reference: FSP bsp_clocks.c. */
  return priv_ra8_cgc_wait_oscsf_set(k_ra8_oscsf_bit_pll1sf);
}

RA8_INTERNAL static ra8_err_t
internal_wait_mrm_freq(volatile uint32_t* reg, uint32_t key, uint32_t freq_mhz)
{
  for (uint32_t i = 0U; i < k_ra8_cgc_mrm_spin_limit; i++) {
#if defined(RA8_OFF_TARGET) && defined(UNIT_TEST)
    /* Host MMIO fault seam: the loop-exit decision comes from
     * ra8_fake_mmio_wait_eval (satisfied on the first poll unless a test
     * arms a fault) because plain host RAM cannot strip the key byte
     * on readback the way the silicon latch does. */
    if (ra8_fake_mmio_wait_eval(reg, i, (*reg == freq_mhz))) {
      return k_ra8_ok;
    }
#else
    if (*reg == freq_mhz) {
      return k_ra8_ok;
    }
#endif
    *reg = key | freq_mhz;
  }
  return k_ra8_err_hw_timeout;
}

RA8_INTERNAL static ra8_err_t internal_set_mrm_wait_states(uint32_t mriclk_hz, uint32_t mrpclk_hz)
{
  const uint32_t mri_mhz = (mriclk_hz <= k_ra8_cgc_mr_min_hz)
                             ? 0U
                             : ((mriclk_hz + k_ra8_cgc_hz_per_mhz - 1U) / k_ra8_cgc_hz_per_mhz);
  const uint32_t mre_mhz = (mrpclk_hz <= k_ra8_cgc_mr_min_hz)
                             ? 0U
                             : ((mrpclk_hz + k_ra8_cgc_hz_per_mhz - 1U) / k_ra8_cgc_hz_per_mhz);
 
  /* HUM Ch 59.5.2 "MRCFREQ : Code MRAM Frequency Notifications Register" p 3551 */
  /* Cross-reference: FSP bsp_clocks.c. */
  ra8_err_t err = internal_wait_mrm_freq(ra8_mrms_mrcfreq(), k_ra8_mrcfreq_key, mri_mhz);
  if (err != k_ra8_ok) {
    return err;
  }
  /* HUM Ch 59.5.3 "MREFREQ : Extra MRAM Frequency Notifications Register" p 3552 */
  /* Cross-reference: FSP bsp_clocks.c. */
  err = internal_wait_mrm_freq(ra8_mrms_mrefreq(), k_ra8_mrefreq_key, mre_mhz);
  return err;
}

RA8_INTERNAL static void internal_program_dividers(void)
{
  /* HUM Ch 9.2.6 "SCKDIVCR : System Clock Division Control Register"
   * / FSP bsp_clocks.c */
  const uint32_t sckdivcr = ((uint32_t)k_ra8_clock_div_8 << k_ra8_sckdivcr_fck_shift) |
                            ((uint32_t)k_ra8_clock_div_4 << k_ra8_sckdivcr_ick_shift) |
                            ((uint32_t)k_ra8_clock_div_4 << k_ra8_sckdivcr_pcke_shift) |
                            ((uint32_t)k_ra8_clock_div_8 << k_ra8_sckdivcr_bck_shift) |
                            ((uint32_t)k_ra8_clock_div_8 << k_ra8_sckdivcr_pcka_shift) |
                            ((uint32_t)k_ra8_clock_div_16 << k_ra8_sckdivcr_pckb_shift) |
                            ((uint32_t)k_ra8_clock_div_8 << k_ra8_sckdivcr_pckc_shift) |
                            ((uint32_t)k_ra8_clock_div_4 << k_ra8_sckdivcr_pckd_shift);
  *ra8_sys_sckdivcr()     = sckdivcr;
 
  /* HUM Ch 9.2.7 "SCKDIVCR2 : System Clock Division Control Register 2"
   * / FSP bsp_clocks.c */
  const uint16_t sckdivcr2 =
    (uint16_t)(((uint16_t)k_ra8_clock_div_4 << k_ra8_sckdivcr2_mriclk_shift) |
               ((uint16_t)k_ra8_clock_div_1 << k_ra8_sckdivcr2_npuclk_shift) |
               ((uint16_t)k_ra8_clock_div_4 << k_ra8_sckdivcr2_cpuclk1_shift) |
               ((uint16_t)k_ra8_clock_div_1 << k_ra8_sckdivcr2_cpuclk0_shift));
  *ra8_sys_sckdivcr2() = sckdivcr2;
}

RA8_INTERNAL static void internal_set_pfb(void)
{
  const uint32_t mri_mhz = *ra8_mrms_mrcfreq();
  if (mri_mhz >= k_ra8_mrcpfb_threshold_mhz) {
    /* HUM Ch 59.5.1 "MRCPFB : Code MRAM Prefetch Buffer Enable Register" p 3551 */
    /* Cross-reference: FSP bsp_clocks.c. */
    *ra8_mrms_mrcpfb() = k_ra8_mrcpfb_enable;
  }
}

RA8_INTERNAL static ra8_err_t internal_route_sciclk(void)
{
  volatile uint8_t* const ckcr  = ra8_sys_scickcr();
  volatile uint8_t* const divcr = ra8_sys_scickdivcr();
 
  /* HUM Ch 9.2.54 "SCICKCR : SCI Clock Control Register" p 368 */
  /* step 1 */
  *ckcr = (uint8_t)(*ckcr | k_ra8_scickcr_cksreq);
  const ra8_err_t req_err =
    ra8_hw_wait_flag_set8(ckcr, (uint8_t)k_ra8_scickcr_cksrdy, (uint32_t)k_ra8_cgc_scik_spin_limit);
  if (req_err != k_ra8_ok) {
    return req_err;
  }
  /* HUM Ch 9.2.49 "SCICKDIVCR : SCI Clock Division Control Register" p 365 */
  /* step 2 */
  *divcr = k_ra8_scickdivcr_div4;
  *ckcr  = (uint8_t)(k_ra8_scickcr_sel_pll1r | k_ra8_scickcr_cksreq);
  /* Step 3: clear CKSREQ to start the new clock. */
  *ckcr = k_ra8_scickcr_sel_pll1r;
  return ra8_hw_wait_flag_clear8(ckcr,
                                 (uint8_t)k_ra8_scickcr_cksrdy,
                                 (uint32_t)k_ra8_cgc_scik_spin_limit);
}

RA8_INTERNAL static ra8_err_t internal_start_main_osc(void)
{
  /* HUM Ch 9.2.27 "MOSCWTCR : Main Clock Oscillator Wait Control Register" p 349 */
  *ra8_sys_moscwtcr() = k_ra8_moscwtcr_2_to_16_cycles;
 
  /* HUM Ch 9.2.13 "MOSCCR : Main Clock Oscillator Control Register" p 338 */
  volatile uint8_t* const moscr =
    (volatile uint8_t*)((uintptr_t)k_ra8_system_base_addr + (uintptr_t)k_ra8_sys_off_moscr);
  *moscr = (uint8_t)(*moscr & (uint8_t)~k_ra8_moscr_mostp_mask);
 
  return priv_ra8_cgc_wait_oscsf_set(k_ra8_oscsf_bit_moscsf);
}

RA8_INTERNAL static ra8_err_t internal_cgc_init_protected(void)
{
  ra8_err_t err = internal_start_main_osc();
  if (err == k_ra8_ok) {
    err = internal_set_vscr_not_high_v();
  }
  if (err == k_ra8_ok) {
    err = internal_stop_pll1();
  }
  if (err == k_ra8_ok) {
    err = internal_program_and_start_pll1();
  }
  if (err == k_ra8_ok) {
    /* Step 6: MRMS wait-state latches must come BEFORE the SCKSCR
     * switch -- the new MRICLK and MRPCLK rates kick in the moment
     * SCKDIVCR2 is committed. */
    err = internal_set_mrm_wait_states(k_ra8_mriclk_hz, k_ra8_fclk_hz);
  }
  if (err == k_ra8_ok) {
    /* Step 7: the SRAM wait state, for exactly the same reason and in
     * exactly the same window as step 6. HUM Ch 58.3.7 "Wait State"
     * p 3540 is unambiguous -- above half the maximum ICLK, "when the
     * wait is not inserted, the operation is not guaranteed" -- and
     * SRAMWTSC.WTEN resets to 0 while this sequence takes ICLK to
     * k_ra8_iclk_hz, its maximum. Programming it after the SCKSCR
     * switch would leave a window in which .data, .bss and the stack
     * are read at full speed with no wait; the ONE fault it is known
     * to produce is a single dropped bit in a value read back out of
     * SRAM, so that window has to be empty, not short (tracker #524). */
    err = ra8_sram_set_wait_state_for_clock(k_ra8_iclk_hz, (uint32_t)k_ra8_iclk_max_hz);
  }
  if (err == k_ra8_ok) {
    internal_program_dividers();
    /* HUM Ch 9.2.5 "SCKSCR : System Clock Source Control Register" p 330 */
    *ra8_sys_sckscr() = k_ra8_cksel_pll1;
  }
  return err;
}
 
ra8_err_t ra8_cgc_init(void)
{
  ra8_log_info(s_tag, "cgc_init -> XTAL -> PLL1 (1 GHz)");
 
  /* Step 1 happens outside the PRCR window: MRMS isn't a protected block. */
  internal_clear_pfb();
 
  ra8_err_t err = k_ra8_ok;
  RA8_PROTECTED_WRITE(k_ra8_prcr_unlock_cgc)
  {
    err = internal_cgc_init_protected();
  }
 
  if (err != k_ra8_ok) {
    ra8_log_error_val(s_tag, "cgc_init failed", (uint32_t)err);
    return err;
  }
 
  /* Step 10 happens after SCKSCR is on PLL1 -- MRMS isn't protected. */
  internal_set_pfb();
 
  /* Step 11 needs PRCR unlocked again. */
  RA8_PROTECTED_WRITE(k_ra8_prcr_unlock_cgc)
  {
    err = internal_route_sciclk();
  }
  if (err != k_ra8_ok) {
    ra8_log_error_val(s_tag, "sciclk route failed", (uint32_t)err);
    return err;
  }
 
  internal_publish_clocks();
  ra8_log_info(s_tag, "system clock = PLL1, CPUCLK0 = 1 GHz");
  return k_ra8_ok;
}
 
ra8_err_t ra8_cgc_use_hoco(void)
{
  volatile uint8_t* const hococr = ra8_sys_hococr();
  *hococr = (uint8_t)((uint8_t)*hococr & (uint8_t)~(1U << k_ra8_hococr_hcstp));
 
  const ra8_err_t err = priv_ra8_cgc_wait_oscsf_set(k_ra8_oscsf_bit_hocosf);
  if (err != k_ra8_ok) {
    return err;
  }
 
  RA8_PROTECTED_WRITE(k_ra8_prcr_unlock_cgc)
  {
    *ra8_sys_sckscr() = k_ra8_cksel_hoco;
  }
 
  ra8_log_info(s_tag, "switched to HOCO");
  return k_ra8_ok;
}
 
/* =============================================================================
 * Runtime reconfigure + stop detection
 * =============================================================================
 */

static ra8_cgc_ostd_fn_t s_ostd_handler = nullptr;

static void* s_ostd_ctx = nullptr;

static bool s_ostd_enabled = false;
 
ra8_err_t ra8_cgc_switch_pll1_target(uint32_t new_cpuclk_hz)
{
  if (new_cpuclk_hz == 0U) {
    return k_ra8_err_invalid_arg;
  }
  ra8_log_info_val(s_tag, "switch pll1 target", new_cpuclk_hz);
 
  /* Step 1: temporarily fall back to MOCO so the CPU is not clocked
   * from PLL1 while we reprogramme it. */
  RA8_PROTECTED_WRITE(k_ra8_prcr_unlock_cgc)
  {
    *ra8_sys_sckscr() = k_ra8_cksel_moco;
  }
 
  /* Step 2: stop + restart PLL1 with the existing field encodings.
   * For now we only support the FSP-quickstart values; a future
   * change can compute PLLCCR / PLLCCR2 from `new_cpuclk_hz`. */
  ra8_err_t pll_err = k_ra8_ok;
  RA8_PROTECTED_WRITE(k_ra8_prcr_unlock_cgc)
  {
    pll_err = internal_stop_pll1();
    if (pll_err == k_ra8_ok) {
      pll_err = internal_program_and_start_pll1();
    }
    if (pll_err != k_ra8_ok) {
      ra8_log_error_val(s_tag, "pll1 retune failed", (uint32_t)pll_err);
      /* fall through: leave SCKSCR on MOCO so the CPU keeps running. */
    }
  }
 
  /* Step 3: switch SCKSCR back to PLL1 if the lock succeeded, then
   * republish the clock tree. */
  RA8_PROTECTED_WRITE(k_ra8_prcr_unlock_cgc)
  {
    if (pll_err == k_ra8_ok) {
      *ra8_sys_sckscr() = k_ra8_cksel_pll1;
    }
  }
  internal_publish_clocks();
  s_clock_hz[k_ra8_clock_id_cpuclk0] = new_cpuclk_hz;
  return k_ra8_ok;
}
 
ra8_err_t ra8_cgc_enable_stop_detection(ra8_cgc_ostd_fn_t handler, void* ctx)
{
  if (handler == nullptr) {
    return k_ra8_err_null_ptr;
  }
  s_ostd_handler = handler;
  s_ostd_ctx     = ctx;
  s_ostd_enabled = true;
  /* HUM Ch 9.2.23 "OSTDCR : Oscillation Stop Detection Control Register", p 346
   * -- target programming deferred until the first real NMI wiring
   * lands. On host (fake) the enable-flag is tracked
   * purely in software and the test helper fires the stored
   * callback directly. */
  ra8_log_info(s_tag, "stop detection armed");
  return k_ra8_ok;
}
 
ra8_err_t ra8_cgc_disable_stop_detection(void)
{
  s_ostd_handler = nullptr;
  s_ostd_ctx     = nullptr;
  s_ostd_enabled = false;
  ra8_log_info(s_tag, "stop detection disarmed");
  return k_ra8_ok;
}
 
void ra8_cgc_fake_trigger_stop_detection(void)
{
  if (!s_ostd_enabled) {
    return;
  }
  const ra8_cgc_ostd_fn_t cb  = s_ostd_handler;
  void* const             ctx = s_ostd_ctx;
  if (cb != nullptr) {
    cb(ctx);
  }
}