ra8_xspi.c

Go to the documentation of this file.

 
#include "ra8_xspi.h"
 
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_hw_err.h"
#include "ra8_log.h"
#include "ra8_mstp.h"
#include "ra8_ospi_regs.h"
#include "ra8_register_protection.h"
#include "ra8_system_regs.h"
#include "ra8_xspi_internal.h"

static const char* s_tag = "XSPI";

typedef enum : uint8_t {
  k_ra8_xspi_cmd_max_bytes = 16U, 
} ra8_xspi_cmd_limits_t;

typedef enum : uint8_t {
  k_ra8_xspi_onboard_cs = 1U, 
} ra8_xspi_chip_select_t;

typedef enum : uint32_t {
  k_ra8_xspi_reset_spin = 100000U, 
} ra8_xspi_reset_delay_t;

static const ra8_mstp_t s_xspi_mstp_table[] = {
  k_ra8_mstp_ospi0,
  k_ra8_mstp_ospi1,
};

RA8_INTERNAL
static ra8_err_t internal_wait_octacksrdy(uint8_t expected)
{
  /* SRDY (clock-source ready) is bit 7 of OCTACKCR. */
  /* HUM Ch 9.2.45 "OCTACKCR.OCTACKSRDY" p 360 */
  volatile const uint8_t* const ckcr = ra8_sys_octackcr();
  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(ckcr, mask, (uint32_t)k_ra8_xspi_ckcr_spin);
  }
  return ra8_hw_wait_flag_clear8(ckcr, mask, (uint32_t)k_ra8_xspi_ckcr_spin);
}

RA8_INTERNAL
static ra8_err_t internal_xspi_clock_block_init(void)
{
  static bool s_xspi_clock_inited = false;
  if (s_xspi_clock_inited) {
    return k_ra8_ok;
  }
  ra8_err_t err = k_ra8_ok;
  RA8_PROTECTED_WRITE(k_ra8_prcr_unlock_cgc)
  {
    /* HUM Ch 9.2.40 "OCTACKDIVCR" p 357 -- /1 keeps MOCO at its
     * native rate (~8 MHz nominal). The IS25LX512M JEDEC bring-up
     * runs comfortably below 50 MHz so /1 is conservative. */
    *ra8_sys_octackdivcr() = 0U;
 
    /* HUM Ch 9.2.45 "OCTACKCR.OCTACKSREQ" p 360 -- assert SREQ with
     * the reset-default source (MOCO, OCTACKSEL = 0001b). */
    const uint8_t sreq_mask = (uint8_t)(1U << k_ra8_usbckcr_bit_sreq);
    const uint8_t src_moco  = 0x01U;
    *ra8_sys_octackcr()     = (uint8_t)(src_moco | sreq_mask);
 
    /* Step 3: wait for SRDY = 1 (chip acknowledges the request). */
    err = internal_wait_octacksrdy(1U);
    if (err != k_ra8_ok) {
      ra8_log_error(s_tag, "xspi: OCTACKSRDY=1 timeout");
      break;
    }
    /* Step 4: drop SREQ -- commits the (same) source selection. */
    *ra8_sys_octackcr() = src_moco;
    /* Step 5: wait for SRDY = 0 -- handshake done. */
    err = internal_wait_octacksrdy(0U);
    if (err != k_ra8_ok) {
      ra8_log_error(s_tag, "xspi: OCTACKSRDY=0 timeout");
      break;
    }
  }
  if (err == k_ra8_ok) {
    s_xspi_clock_inited = true;
    ra8_log_info(s_tag, "octa block clock stable");
  }
  return err;
}

RA8_INTERNAL
static void internal_xspi_reset_spin(void)
{
  for (volatile uint32_t i = 0U; i < (uint32_t)k_ra8_xspi_reset_spin; i++) {
    /* spin */
  }
}

RA8_INTERNAL
static void internal_xspi_reset_device(volatile r_xspi_regs_t* reg)
{
  /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
  /* WPCS held high (write-protect deasserted) the whole time; only
   * RSTCS toggles. */
  reg->LIOCTL = k_ra8_xspi_lioctl_mask_wpcs; /* RSTCS = 0 (asserted, reset) */
  internal_xspi_reset_spin();
  reg->LIOCTL = k_ra8_xspi_lioctl_mask_wpcs | k_ra8_xspi_lioctl_mask_rstcs; /* RSTCS = 1 */
  internal_xspi_reset_spin();
}

RA8_INTERNAL
static void internal_xspi_apply_config(volatile r_xspi_regs_t* reg, ra8_xspi_lio_mode_t mode)
{
  /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
  reg->BMCTL0                          = (uint32_t)k_ra8_xspi_bmctl0_disabled;
  reg->CMCTLCH[0]                      = 0U;
  reg->CMCTLCH[1]                      = 0U;
  reg->WRAPCFG                         = 0U;
  reg->COMCFG                          = 0U;
  reg->LIOCFGCS[k_ra8_xspi_onboard_cs] = (uint32_t)mode;
  reg->CDCTL0 =
    ((uint32_t)k_ra8_xspi_onboard_cs << k_ra8_xspi_cdctl0_bit_cssel) & k_ra8_xspi_cdctl0_mask_cssel;
  reg->INTC = k_ra8_xspi_ints_mask_all;
}
 
ra8_err_t ra8_xspi_init(uint8_t instance, ra8_xspi_lio_mode_t mode)
{
  volatile r_xspi_regs_t* reg = ra8_xspi(instance);
  RA8_CHECK_NULL_PTR(reg, s_tag, "instance out of range");
  if (instance >= (uint8_t)(sizeof(s_xspi_mstp_table) / sizeof(s_xspi_mstp_table[0]))) {
    return k_ra8_err_invalid_arg;
  }
 
  /* HUM Ch 11.2.7 "MSTPCRB" Note 3 p 444 -- MSTPB16/17 must be written
   * AFTER OCTACLK is stable. Run the block-level OCTACKCR handshake
   * first; the helper is idempotent so a second ra8_xspi_init call
   * (e.g. for instance 1) skips it. */
  const ra8_err_t clk_err = internal_xspi_clock_block_init();
  if (clk_err != k_ra8_ok) {
    return clk_err;
  }
 
  /* HUM Ch 11.2.7 "MSTPCRB : Module Stop Control Register B", p 444 */
  const ra8_err_t mst_err = ra8_mstp_enable(s_xspi_mstp_table[instance]);
  /* GCOVR_EXCL_BR_START -- MSTP HW readback */
  RA8_RETURN_ON_ERROR(mst_err, s_tag, "xspi_init: mstp enable");
  /* GCOVR_EXCL_BR_STOP */
 
  internal_xspi_apply_config(reg, mode);
  internal_xspi_reset_device(reg);
 
  ra8_log_info_val(s_tag, "xspi_init inst", (uint32_t)instance);
  return k_ra8_ok;
}
 
ra8_err_t ra8_xspi_direct_command(uint8_t instance, const uint8_t* cmd_buf, uint8_t len)
{
  RA8_CHECK_NULL_PTR(cmd_buf, s_tag, "cmd_buf must not be nullptr");
  if (len > k_ra8_xspi_cmd_max_bytes) {
    return k_ra8_err_invalid_size;
  }
  volatile r_xspi_regs_t* reg = ra8_xspi(instance);
  if (reg == nullptr) {
    return k_ra8_err_out_of_range;
  }
 
  /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
  /* Pack the caller's bytes into CDBUF slot 0 as little-endian
   * words. Slot 0 is the full 16-byte CDBUF window (4 u32), so
   * raw callers can use any of the four indices. */
  uint32_t word = 0U;
  for (uint8_t i = 0U; i < len; i++) {
    word |= ((uint32_t)cmd_buf[i]) << ((i % 4U) * 8U);
    if ((i % 4U) == 3U) {
      reg->CDBUF[i / 4U] = word;
      word               = 0U;
    }
  }
  if ((len % 4U) != 0U) {
    reg->CDBUF[len / 4U] = word;
  }
 
  return k_ra8_ok;
}
 
/* =============================================================================
 * lifecycle + IRQ + power transition
 * =============================================================================
 */

typedef struct {
  ra8_xspi_event_fn_t fn;  
  void*               ctx; 
} ra8_xspi_state_t;

static ra8_xspi_state_t s_xspi_state[k_ra8_xspi_instance_count];
 
ra8_err_t ra8_xspi_deinit(uint8_t instance)
{
  volatile r_xspi_regs_t* reg = ra8_xspi(instance);
  RA8_CHECK_NULL_PTR(reg, s_tag, "instance out of range");
 
  /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
  reg->LIOCFGCS[0] = 0U;
  reg->INTE        = 0U;
  reg->INTC        = k_ra8_xspi_ints_mask_all;
 
  s_xspi_state[instance].fn  = nullptr;
  s_xspi_state[instance].ctx = nullptr;
  return ra8_mstp_disable(s_xspi_mstp_table[instance]);
}
 
ra8_err_t ra8_xspi_get_status(uint8_t instance, uint32_t* out_mask)
{
  RA8_CHECK_NULL_PTR(out_mask, s_tag, "out_mask must not be nullptr");
  volatile const r_xspi_regs_t* reg = ra8_xspi(instance);
  RA8_CHECK_NULL_PTR(reg, s_tag, "instance out of range");
  /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
  *out_mask = reg->COMSTT;
  return k_ra8_ok;
}
 
ra8_err_t ra8_xspi_clear_status(uint8_t instance, uint32_t mask)
{
  volatile r_xspi_regs_t* reg = ra8_xspi(instance);
  RA8_CHECK_NULL_PTR(reg, s_tag, "instance out of range");
  /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
  reg->INTC = mask;
  return k_ra8_ok;
}
 
ra8_err_t ra8_xspi_attach_handler(uint8_t instance, ra8_xspi_event_fn_t fn, void* ctx)
{
  if (instance >= k_ra8_xspi_instance_count) {
    return k_ra8_err_invalid_arg;
  }
  s_xspi_state[instance].fn  = fn;
  s_xspi_state[instance].ctx = ctx;
  return k_ra8_ok;
}
 
RA8_ISR_SAFE
void ra8_xspi_dispatch(uint8_t instance)
{
  if (instance >= k_ra8_xspi_instance_count) {
    return;
  }
  volatile r_xspi_regs_t* reg = ra8_xspi(instance);
  if (reg == nullptr) { /* GCOVR_EXCL_BR_LINE -- instance bounded above */
    return;             /* GCOVR_EXCL_LINE -- MSTP fail is HW-only      */
  }
  /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
  /* Snapshot INTS + COMSTT, clear every pending interrupt flag,
   * then hand the INTS mask off to the user callback so it can
   * decide whether the transfer was successful or errored. */
  const uint32_t mask = reg->INTS;
  reg->INTC           = k_ra8_xspi_ints_mask_all;
 
  const ra8_xspi_event_fn_t fn  = s_xspi_state[instance].fn;
  void* const               ctx = s_xspi_state[instance].ctx;
  if (fn != nullptr) {
    fn(ctx, mask);
  }
}
 
ra8_err_t ra8_xspi_enter_stop(uint8_t instance)
{
  if (instance >= k_ra8_xspi_instance_count) {
    return k_ra8_err_invalid_arg;
  }
  return ra8_mstp_disable(s_xspi_mstp_table[instance]);
}
 
ra8_err_t ra8_xspi_exit_stop(uint8_t instance)
{
  if (instance >= k_ra8_xspi_instance_count) {
    return k_ra8_err_invalid_arg;
  }
  return ra8_mstp_enable(s_xspi_mstp_table[instance]);
}
 
ra8_err_t ra8_xspi_xip_enter(uint8_t instance, uint8_t enter_code, uint8_t exit_code)
{
  volatile r_xspi_regs_t* reg = ra8_xspi(instance);
  RA8_CHECK_NULL_PTR(reg, s_tag, "instance out of range");
 
  /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
  /* FSP r_ospi_b_xip(true) flow:
   *   1. Stage XIP enter/exit codes in CMCTLCH for both channels.
   *   2. Map the target window read-only via BMCTL0 = 0x55.
   *   3. Set CMCTLCH.XIPEN to arm execute-in-place.
   * The first read on the memory-mapped window then transmits the
   * enter code. We omit the bus-bridge prefetch dance because the
   * driver does not enable prefetch by default. */
  const uint32_t code_word = ((uint32_t)enter_code << k_ra8_xspi_cmctlch_xipencode_pos) |
                             ((uint32_t)exit_code << k_ra8_xspi_cmctlch_xipexcode_pos);
 
  reg->BMCTL0     = k_ra8_xspi_bmctl0_read_only;
  reg->CMCTLCH[0] = code_word | k_ra8_xspi_cmctlch_xipen_mask;
  reg->CMCTLCH[1] = code_word | k_ra8_xspi_cmctlch_xipen_mask;
  return k_ra8_ok;
}
 
ra8_err_t ra8_xspi_xip_exit(uint8_t instance)
{
  volatile r_xspi_regs_t* reg = ra8_xspi(instance);
  RA8_CHECK_NULL_PTR(reg, s_tag, "instance out of range");
 
  /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
  /* FSP r_ospi_b_xip(false) flow: clear XIPEN, drop the codes,
   * and put BMCTL0 back to read/write so direct-command transfers
   * are no longer blocked by the memory-mapped path. */
  reg->CMCTLCH[0] = 0U;
  reg->CMCTLCH[1] = 0U;
  reg->BMCTL0     = k_ra8_xspi_bmctl0_read_write;
  return k_ra8_ok;
}
 
/* =============================================================================
 * Sweep 6 extensions: XIP mode select, DTR, DQS calibration, suspend/resume
 * =============================================================================
 */

typedef enum : uint8_t {
  k_ra8_spi_flash_op_suspend   = 0x75U, 
  k_ra8_spi_flash_op_resume    = 0x7AU, 
  k_ra8_spi_flash_op_reset_en  = 0x66U, 
  k_ra8_spi_flash_op_reset_dev = 0x99U, 
} ra8_xspi_jedec_extra_t;

typedef enum : uint8_t {
  k_ra8_xspi_reset_cmd_bytes_1s = 1U, 
  k_ra8_xspi_reset_cmd_bytes_8d = 2U, 
} ra8_xspi_reset_cmd_bytes_t;

typedef enum : uint8_t {
  k_ra8_xspi_addr_bytes_3 = 3U, 
  k_ra8_xspi_addr_bytes_4 = 4U, 
} ra8_xspi_addr_bytes_t;

typedef enum : uint32_t {
  k_ra8_xspi_calib_spin = 1024U, 
} ra8_xspi_calib_spin_t;
 
ra8_err_t ra8_xspi_set_xip_mode(uint8_t instance, bool enable, uint8_t read_cmd, uint8_t addr_bytes)
{
  volatile r_xspi_regs_t* reg = ra8_xspi(instance);
  RA8_CHECK_NULL_PTR(reg, s_tag, "instance out of range");
  if ((addr_bytes != k_ra8_xspi_addr_bytes_3) && (addr_bytes != k_ra8_xspi_addr_bytes_4)) {
    return k_ra8_err_invalid_arg;
  }
 
  /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
  /* CMCFGCS slot 0 = (mode, read-cmd-word, write-cmd-word, addr-word).
   * For XIP we only need read + addr; write opcode stays zero. */
  const uint8_t base                                    = 0U; /* slot 0 base index */
  reg->CMCFGCS[base + k_ra8_xspi_cmcfgcs_word_read_cmd] = (uint32_t)read_cmd
                                                          << k_ra8_xspi_cmcfgcs_pos_cmd;
  reg->CMCFGCS[base + k_ra8_xspi_cmcfgcs_word_addr]     = (uint32_t)addr_bytes
                                                          << k_ra8_xspi_cmcfgcs_pos_addr_size;
 
  if (enable) {
    /* Mirror FSP r_ospi_b_xip(true): map read-only and arm XIPEN. */
    reg->BMCTL0     = k_ra8_xspi_bmctl0_read_only;
    reg->CMCTLCH[0] = k_ra8_xspi_cmctlch_xipen_mask;
    reg->CMCTLCH[1] = k_ra8_xspi_cmctlch_xipen_mask;
  } else {
    /* FSP r_ospi_b_xip(false): clear XIPEN and re-open the bus. */
    reg->CMCTLCH[0] = 0U;
    reg->CMCTLCH[1] = 0U;
    reg->BMCTL0     = k_ra8_xspi_bmctl0_read_write;
  }
  return k_ra8_ok;
}
 
ra8_err_t ra8_xspi_set_dtr_mode(uint8_t instance, bool enable)
{
  volatile r_xspi_regs_t* reg = ra8_xspi(instance);
  RA8_CHECK_NULL_PTR(reg, s_tag, "instance out of range");
 
  /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
  uint32_t v = reg->LIOCFGCS[0];
  if (enable) {
    v |= k_ra8_xspi_liocfgcs_mask_ddren;
  } else {
    v &= ~k_ra8_xspi_liocfgcs_mask_ddren;
  }
  reg->LIOCFGCS[0] = v;
  return k_ra8_ok;
}
 
ra8_err_t ra8_xspi_calibrate_dqs(uint8_t instance)
{
  volatile r_xspi_regs_t* reg = ra8_xspi(instance);
  RA8_CHECK_NULL_PTR(reg, s_tag, "instance out of range");
 
  /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
  /* Mirror FSP R_OSPI_B_AutoCalibrate: arm CAEN and wait for the
   * controller to clear it once the phase-scan completes. The full
   * preamble-pattern + CARDCMD descriptor is owned by board-level
   * code in higher-level callers. On host tests the bounded wait
   * consults the ra8_fake_mmio seam (first-poll success unless a test
   * arms a fault); the CAEN bit itself stays set in host RAM because
   * only the real controller clears it. */
  reg->CCCTLCS[0] |= k_ra8_xspi_ccctl0_mask_caen;
  return ra8_hw_wait_flag_clear32(&reg->CCCTLCS[0],
                                  (uint32_t)k_ra8_xspi_ccctl0_mask_caen,
                                  (uint32_t)k_ra8_xspi_calib_spin);
}
 
ra8_err_t ra8_xspi_suspend(uint8_t instance)
{
  volatile r_xspi_regs_t* reg = ra8_xspi(instance);
  RA8_CHECK_NULL_PTR(reg, s_tag, "instance out of range");
  return priv_ra8_xspi_issue_simple_opcode(reg, k_ra8_spi_flash_op_suspend);
}
 
ra8_err_t ra8_xspi_resume(uint8_t instance)
{
  volatile r_xspi_regs_t* reg = ra8_xspi(instance);
  RA8_CHECK_NULL_PTR(reg, s_tag, "instance out of range");
  return priv_ra8_xspi_issue_simple_opcode(reg, k_ra8_spi_flash_op_resume);
}

RA8_INTERNAL
static ra8_err_t
internal_issue_reset_opcode(volatile r_xspi_regs_t* reg, uint8_t opcode, uint8_t cmd_bytes)
{
  /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
  /* Build the CMD half-word for either 1S (just the opcode) or 8D
   * (opcode + complement). The complement form is what 8D-mode SPI
   * NOR devices require so they can distinguish "real opcode" from
   * "garbage on the bus". */
  /* CMD is transmitted MSB-first from CDT[31:16]; a 1-byte opcode must
   * be left-justified to CDT[31:24] (cmd_word << 8), a 2-byte 8D pair
   * fills the full [31:16] field. Same rule as internal_make_cdt. */
  uint16_t cmd_word = (uint16_t)(opcode << 8U);
  if (cmd_bytes == (uint8_t)k_ra8_xspi_reset_cmd_bytes_8d) {
    cmd_word = (uint16_t)(opcode | (((uint16_t)(uint8_t)~opcode) << 8U));
  }
  reg->CDBUF[k_ra8_xspi_cdbuf_idx_cdt] =
    (((uint32_t)cmd_bytes & k_ra8_xspi_cdt_mask_cmdsize) << k_ra8_xspi_cdt_pos_cmdsize) |
    (((uint32_t)k_ra8_xspi_cdt_addsize_0 & k_ra8_xspi_cdt_mask_addsize)
     << k_ra8_xspi_cdt_pos_addsize) |
    (((uint32_t)k_ra8_xspi_cdt_trtype_write & k_ra8_xspi_cdt_mask_trtype)
     << k_ra8_xspi_cdt_pos_trtype) |
    (((uint32_t)cmd_word) << k_ra8_xspi_cdt_pos_cmd);
  reg->CDBUF[k_ra8_xspi_cdbuf_idx_addr]  = 0U;
  reg->CDBUF[k_ra8_xspi_cdbuf_idx_data0] = 0U;
  reg->CDBUF[k_ra8_xspi_cdbuf_idx_data1] = 0U;
  return priv_ra8_xspi_kick_command(reg);
}
 
ra8_err_t ra8_xspi_software_reset(uint8_t instance, uint8_t cmd_bytes)
{
  volatile r_xspi_regs_t* reg = ra8_xspi(instance);
  RA8_CHECK_NULL_PTR(reg, s_tag, "instance out of range");
  if ((cmd_bytes != (uint8_t)k_ra8_xspi_reset_cmd_bytes_1s) &&
      (cmd_bytes != (uint8_t)k_ra8_xspi_reset_cmd_bytes_8d)) {
    return k_ra8_err_invalid_arg;
  }
 
  /* IS25LX512M Ch 8.20-8.21 p 39: RSTEN must be the immediately
   * preceding command before RST or the device ignores RST. */
  const ra8_err_t en = internal_issue_reset_opcode(reg, k_ra8_spi_flash_op_reset_en, cmd_bytes);
  if (en != k_ra8_ok) {
    return en;
  }
  const ra8_err_t rst = internal_issue_reset_opcode(reg, k_ra8_spi_flash_op_reset_dev, cmd_bytes);
  if (rst != k_ra8_ok) {
    return rst;
  }
  return k_ra8_ok;
}