ra8_xspi_flash.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_ospi_regs.h"
#include "ra8_xspi.h"
#include "ra8_xspi_internal.h"

static const char* s_tag = "XSPI";

typedef enum : uint32_t {
  k_xspi_byte_mask = 0xFFUL, 
} xspi_mask_t;

typedef enum : uint8_t {
  k_ra8_spi_flash_op_write_enable = 0x06U, 
  k_ra8_spi_flash_op_page_program = 0x02U, 
  k_ra8_spi_flash_op_read_status  = 0x05U, 
  k_ra8_spi_flash_op_read_id      = 0x9FU, 
  k_ra8_spi_flash_op_read         = 0x03U, 
  k_ra8_spi_flash_op_erase_sector = 0x20U, 
} ra8_spi_flash_op_t;

typedef enum : uint8_t {
  k_ra8_flash_status_bit_wip = 0U, 
  k_ra8_flash_status_bit_wel = 1U, 
} ra8_flash_status_bit_t;

typedef enum : uint32_t {
  k_ra8_xspi_addr_space_3byte = 0x1000000UL, 
} ra8_xspi_addr_space_t;

typedef enum : uint8_t {
  k_ra8_xspi_cdt_max_data_bytes = 8U, 
} ra8_xspi_cdt_limits_t;

RA8_INTERNAL
static uint32_t internal_make_cdt(uint8_t opcode,
                                  uint8_t cmd_bytes,
                                  uint8_t addr_bytes,
                                  uint8_t data_bytes,
                                  uint8_t is_write)
{
  /* CMD is a 16-bit field at CDT[31:16]. The command-manual engine
   * transmits CMDSIZE bytes MSB-first starting at bit 31, so an
   * N-byte command must be LEFT-justified inside the 16-bit field:
   * a 1-byte opcode belongs at bits [31:24], a 2-byte opcode pair at
   * [31:16]. Placing a 1-byte opcode at [23:16] (a bare ``opcode <<
   * 16``) makes the controller clock out the zero byte at [31:24]
   * instead -- the flash then sees command 0x00 for every 0x9F /
   * 0x05 / 0x06 / 0x02 / 0x20 op, never answers, and RDID floats to
   * 0x00FFFFFF even though CMDCMP fires. Mirrors FSP
   * ``r_ospi_b_direct_transfer`` which stores ``command`` already
   * left-aligned in the 16-bit CMD field. HUM Ch 44 p 2986. */
  const uint8_t  cmd_shift = (uint8_t)(8U * (2U - (cmd_bytes & k_ra8_xspi_cdt_mask_cmdsize)));
  const uint32_t cmd_word  = ((uint32_t)opcode << cmd_shift) & (uint32_t)k_ra8_xspi_cdt_mask_cmd;
  return (((uint32_t)cmd_bytes & k_ra8_xspi_cdt_mask_cmdsize) << k_ra8_xspi_cdt_pos_cmdsize) |
         (((uint32_t)addr_bytes & k_ra8_xspi_cdt_mask_addsize) << k_ra8_xspi_cdt_pos_addsize) |
         (((uint32_t)data_bytes & k_ra8_xspi_cdt_mask_datasize) << k_ra8_xspi_cdt_pos_datasize) |
         (((uint32_t)is_write & k_ra8_xspi_cdt_mask_trtype) << k_ra8_xspi_cdt_pos_trtype) |
         (cmd_word << k_ra8_xspi_cdt_pos_cmd);
}

typedef enum : uint8_t {
  k_ra8_xspi_resp_bytes_status = 1U, 
  k_ra8_xspi_resp_bytes_jedec  = 3U, 
} ra8_spi_flash_resp_bytes_t;

RA8_INTERNAL
static ra8_err_t internal_flash_range_check(uint32_t flash_addr, uint32_t len)
{
  if (flash_addr >= (uint32_t)k_ra8_xspi_addr_space_3byte) {
    return k_ra8_err_invalid_arg;
  }
  if (len > ((uint32_t)k_ra8_xspi_addr_space_3byte - flash_addr)) {
    return k_ra8_err_invalid_arg;
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_wait_command_done(volatile r_xspi_regs_t* reg)
{
  ra8_err_t wait = k_ra8_err_hw_timeout;
  for (uint32_t i = 0U; i < (uint32_t)k_ra8_xspi_cmd_spin; i++) {
    /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
    const bool cmdcmp = ((reg->INTS & (uint32_t)k_ra8_xspi_ints_mask_cmdcmp) != 0U);
#if defined(RA8_OFF_TARGET) && defined(UNIT_TEST)
    /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
    if (ra8_fake_mmio_poll(&reg->INTS, i, cmdcmp)) {
#else
    if (cmdcmp) {
#endif
      wait = k_ra8_ok;
      break;
    }
  }
  if (wait != k_ra8_ok) {
    return wait;
  }
  /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
  /* FSP r_ospi_b_direct_transfer clears every pending status bit at the
   * end of a manual command via ``INTC = INTS``. */
  reg->INTC = reg->INTS;
  return k_ra8_ok;
}
 
ra8_err_t priv_ra8_xspi_kick_command(volatile r_xspi_regs_t* reg)
{
  /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
  reg->CDCTL0 |= k_ra8_xspi_cdctl0_mask_trreq;
  return internal_wait_command_done(reg);
}
 
ra8_err_t priv_ra8_xspi_issue_simple_opcode(volatile r_xspi_regs_t* reg, uint8_t opcode)
{
  /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
  /* Populate CDBUF slot 0 per FSP ``r_ospi_b_direct_transfer``:
   * CDT carries opcode + size encoding, CDA/CDD0/CDD1 are zeroed
   * because there is no address phase and no payload. CDCTL1/CDCTL2
   * are periodic-mode fields (PEREXP / PERMSK in FSP) -- leave
   * them at zero for one-shot manual commands. */
  reg->CDBUF[k_ra8_xspi_cdbuf_idx_cdt] = internal_make_cdt(opcode,
                                                           k_ra8_xspi_cdt_cmdsize_1,
                                                           k_ra8_xspi_cdt_addsize_0,
                                                           0U,
                                                           k_ra8_xspi_cdt_trtype_read);
  /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
  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_INTERNAL
static ra8_err_t
internal_issue_read_opcode(volatile r_xspi_regs_t* reg, uint8_t opcode, uint8_t resp_bytes)
{
  /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
  reg->CDBUF[k_ra8_xspi_cdbuf_idx_cdt] = internal_make_cdt(opcode,
                                                           k_ra8_xspi_cdt_cmdsize_1,
                                                           k_ra8_xspi_cdt_addsize_0,
                                                           resp_bytes,
                                                           k_ra8_xspi_cdt_trtype_read);
  /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
  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_INTERNAL
static void internal_build_chunk_header(volatile r_xspi_regs_t* reg,
                                        uint8_t                 opcode,
                                        uint32_t                addr,
                                        uint8_t                 data_bytes,
                                        uint8_t                 is_write)
{
  /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
  reg->CDBUF[k_ra8_xspi_cdbuf_idx_cdt] = internal_make_cdt(opcode,
                                                           k_ra8_xspi_cdt_cmdsize_1,
                                                           k_ra8_xspi_cdt_addsize_3,
                                                           data_bytes,
                                                           is_write);
  /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
  reg->CDBUF[k_ra8_xspi_cdbuf_idx_addr] = addr;
}

RA8_INTERNAL
static ra8_err_t internal_flash_read_chunk(volatile r_xspi_regs_t* reg,
                                           uint32_t                flash_addr,
                                           uint8_t*                buf,
                                           uint32_t                chunk)
{
  internal_build_chunk_header(reg,
                              k_ra8_spi_flash_op_read,
                              flash_addr,
                              (uint8_t)chunk,
                              k_ra8_xspi_cdt_trtype_read);
  const ra8_err_t wait = priv_ra8_xspi_kick_command(reg);
  if (wait != k_ra8_ok) {
    return wait;
  }
  for (uint32_t i = 0U; i < chunk; i++) {
    const uint8_t cdbuf_word_idx =
      (i < 4U) ? (uint8_t)k_ra8_xspi_cdbuf_idx_data0 : (uint8_t)k_ra8_xspi_cdbuf_idx_data1;
    /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
    /* CDBUF data words: bytes 0..3 in CDD0, bytes 4..7 in CDD1. */
    const uint32_t word = reg->CDBUF[cdbuf_word_idx];
    buf[i]              = (uint8_t)(word >> ((i % 4U) * 8U));
  }
  return k_ra8_ok;
}
 
ra8_err_t ra8_xspi_flash_read(uint8_t instance, uint32_t flash_addr, uint8_t* buf, uint32_t len)
{
  RA8_CHECK_NULL_PTR(buf, s_tag, "buf must not be nullptr");
  if ((len == 0U) || (len > k_ra8_xspi_max_xfer)) {
    return k_ra8_err_invalid_arg;
  }
  volatile r_xspi_regs_t* reg = ra8_xspi(instance);
  RA8_CHECK_NULL_PTR(reg, s_tag, "instance out of range");
  const ra8_err_t rng = internal_flash_range_check(flash_addr, len);
  if (rng != k_ra8_ok) {
    return rng;
  }
 
  /* The manual-command engine carries only k_ra8_xspi_cdt_max_data_bytes
   * (8) data bytes per transfer, so walk the request in 8-byte chunks.
   * (HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986.) */
  uint32_t off = 0U;
  while (off < len) {
    uint32_t chunk = len - off;
    if (chunk > (uint32_t)k_ra8_xspi_cdt_max_data_bytes) {
      chunk = (uint32_t)k_ra8_xspi_cdt_max_data_bytes;
    }
    const ra8_err_t e = internal_flash_read_chunk(reg, flash_addr + off, &buf[off], chunk);
    if (e != k_ra8_ok) {
      return e;
    }
    off += chunk;
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t
internal_flash_stage_program(volatile r_xspi_regs_t* reg, uint32_t flash_addr, uint32_t len)
{
  const ra8_err_t wren = priv_ra8_xspi_issue_simple_opcode(reg, k_ra8_spi_flash_op_write_enable);
  if (wren != k_ra8_ok) {
    return wren;
  }
  /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
  /* Programme a JEDEC 0x02 page-program with 3-byte address. The
   * outgoing byte count is encoded in CDT.DATASIZE (FSP semantics);
   * leaving the periodic-mode CDCTL1/CDCTL2 PEREXP/PERMSK fields
   * untouched. The kick (TRREQ) is deferred to the caller so that
   * CDBUF[CDD0]/CDBUF[CDD1] can be loaded with the payload first --
   * see this helper's @details for the rationale. */
  const uint8_t chunk =
    (len > (uint32_t)k_ra8_xspi_cdt_max_data_bytes) ? k_ra8_xspi_cdt_max_data_bytes : (uint8_t)len;
  internal_build_chunk_header(reg,
                              k_ra8_spi_flash_op_page_program,
                              flash_addr,
                              chunk,
                              k_ra8_xspi_cdt_trtype_write);
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_poll_wip_clear(uint8_t instance)
{
  for (uint32_t i = 0U; i < (uint32_t)k_ra8_flash_program_timeout_us; i++) {
    uint8_t         status = 0U;
    const ra8_err_t e      = ra8_xspi_flash_read_status(instance, &status);
    if (e != k_ra8_ok) {
      return e;
    }
    const bool wip_clear = ((status & (uint8_t)(1U << (uint8_t)k_ra8_flash_status_bit_wip)) == 0U);
    if (wip_clear) {
      return k_ra8_ok;
    }
  }
  return k_ra8_err_timeout;
}

RA8_INTERNAL
static void
internal_xspi_stage_payload(volatile r_xspi_regs_t* reg, const uint8_t* data, uint32_t len)
{
  uint32_t data_lo = 0U;
  uint32_t data_hi = 0U;
  for (uint32_t i = 0U; i < len; i++) {
    const uint32_t shift = (uint32_t)((i % 4U) * 8U);
    if (i < 4U) {
      data_lo |= ((uint32_t)data[i]) << shift;
    } else {
      data_hi |= ((uint32_t)data[i]) << shift;
    }
  }
  /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
  reg->CDBUF[(uint8_t)k_ra8_xspi_cdbuf_idx_data0] = data_lo;
  reg->CDBUF[(uint8_t)k_ra8_xspi_cdbuf_idx_data1] = data_hi;
}

RA8_INTERNAL
static ra8_err_t internal_flash_program_chunk(volatile r_xspi_regs_t* reg,
                                              uint8_t                 instance,
                                              uint32_t                flash_addr,
                                              const uint8_t*          data,
                                              uint32_t                chunk)
{
  const ra8_err_t p = internal_flash_stage_program(reg, flash_addr, chunk);
  if (p != k_ra8_ok) {
    return p;
  }
  /* Stage CDD0/CDD1 BEFORE TRREQ (cf. internal_xspi_stage_payload). */
  internal_xspi_stage_payload(reg, data, chunk);
  const ra8_err_t kick = priv_ra8_xspi_kick_command(reg);
  if (kick != k_ra8_ok) {
    return kick;
  }
  return internal_poll_wip_clear(instance);
}
 
ra8_err_t
ra8_xspi_flash_program(uint8_t instance, uint32_t flash_addr, const uint8_t* data, uint32_t len)
{
  RA8_CHECK_NULL_PTR(data, s_tag, "data must not be nullptr");
  if ((len == 0U) || (len > k_ra8_xspi_max_xfer)) {
    return k_ra8_err_invalid_arg;
  }
  volatile r_xspi_regs_t* reg = ra8_xspi(instance);
  RA8_CHECK_NULL_PTR(reg, s_tag, "instance out of range");
  const ra8_err_t rng = internal_flash_range_check(flash_addr, len);
  if (rng != k_ra8_ok) {
    return rng;
  }
 
  /* Each manual-command page-program carries <= 8 data bytes and a
   * single PP must not cross a 256-byte NOR page boundary, so walk the
   * payload in chunks clamped to both limits (HUM Ch 44 p 2986).  This
   * is what makes a 512-byte LevelX sector write round-trip instead of
   * persisting only the first 8 bytes. */
  uint32_t off = 0U;
  while (off < len) {
    const uint32_t addr = flash_addr + off;
    const uint32_t page_left =
      (uint32_t)k_ra8_xspi_page_len - (addr & ((uint32_t)k_ra8_xspi_page_len - 1U));
    uint32_t chunk = len - off;
    if (chunk > (uint32_t)k_ra8_xspi_cdt_max_data_bytes) {
      chunk = (uint32_t)k_ra8_xspi_cdt_max_data_bytes;
    }
    if (chunk > page_left) {
      chunk = page_left;
    }
    const ra8_err_t e = internal_flash_program_chunk(reg, instance, addr, &data[off], chunk);
    if (e != k_ra8_ok) {
      return e;
    }
    off += chunk;
  }
  return k_ra8_ok;
}
 
ra8_err_t ra8_xspi_flash_erase_sector(uint8_t instance, uint32_t flash_addr)
{
  volatile r_xspi_regs_t* reg = ra8_xspi(instance);
  RA8_CHECK_NULL_PTR(reg, s_tag, "instance out of range");
  const ra8_err_t rng = internal_flash_range_check(flash_addr, 0U);
  if (rng != k_ra8_ok) {
    return rng;
  }
 
  const ra8_err_t wren = priv_ra8_xspi_issue_simple_opcode(reg, k_ra8_spi_flash_op_write_enable);
  if (wren != k_ra8_ok) {
    return wren;
  }
 
  /* Programme a JEDEC 0x20 sector-erase with 3-byte address.
   * Erase has no payload, so DATASIZE=0 and TRTYPE=write. */
  internal_build_chunk_header(reg,
                              k_ra8_spi_flash_op_erase_sector,
                              flash_addr,
                              0U,
                              k_ra8_xspi_cdt_trtype_write);
 
  const ra8_err_t wait = priv_ra8_xspi_kick_command(reg);
  if (wait != k_ra8_ok) {
    return wait;
  }
  return internal_poll_wip_clear(instance);
}
 
ra8_err_t ra8_xspi_flash_read_status(uint8_t instance, uint8_t* out_status)
{
  RA8_CHECK_NULL_PTR(out_status, s_tag, "out_status must not be nullptr");
  volatile r_xspi_regs_t* reg = ra8_xspi(instance);
  RA8_CHECK_NULL_PTR(reg, s_tag, "instance out of range");
 
  /* RDSR returns 1 status byte; DATASIZE must be 1, not 0, or the
   * controller never clocks the response and CDD0 stays stale. See
   * IS25LX512M datasheet Ch 8.6. */
  const ra8_err_t e = internal_issue_read_opcode(reg,
                                                 k_ra8_spi_flash_op_read_status,
                                                 (uint8_t)k_ra8_xspi_resp_bytes_status);
  if (e != k_ra8_ok) {
    return e;
  }
  /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
  *out_status = (uint8_t)(reg->CDBUF[(uint8_t)k_ra8_xspi_cdbuf_idx_data0] & k_xspi_byte_mask);
  return k_ra8_ok;
}
 
ra8_err_t ra8_xspi_flash_read_id(uint8_t instance, uint32_t* out_id)
{
  RA8_CHECK_NULL_PTR(out_id, s_tag, "out_id must not be nullptr");
  volatile r_xspi_regs_t* reg = ra8_xspi(instance);
  RA8_CHECK_NULL_PTR(reg, s_tag, "instance out of range");
 
  /* RDID returns 3 JEDEC bytes (MFR/TYPE/CAP); DATASIZE must be 3.
   * IS25LX512M datasheet Ch 8.13 "Read Identification (RDID)". */
  const ra8_err_t e = internal_issue_read_opcode(reg,
                                                 k_ra8_spi_flash_op_read_id,
                                                 (uint8_t)k_ra8_xspi_resp_bytes_jedec);
  if (e != k_ra8_ok) {
    return e;
  }
  /* HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 */
  /* JEDEC 0x9F returns MFR, MEMTYPE, CAPACITY in that byte order.
   * Repack into ``(mfr << 16) | (type << 8) | cap`` as documented
   * in the public API header. */
  const uint32_t word = reg->CDBUF[(uint8_t)k_ra8_xspi_cdbuf_idx_data0];
  *out_id = ((word & k_xspi_byte_mask) << 16U) | (((word >> 8U) & k_xspi_byte_mask) << 8U) |
            ((word >> 16U) & k_xspi_byte_mask);
  return k_ra8_ok;
}