lx_nor_driver_ra8_xspi.c

Go to the documentation of this file.

 
#include "lx_nor_driver_ra8_xspi.h"
 
#include <stdint.h>
 
#include "lx_api.h"
#include "ra8_attributes.h"
#include "ra8_board_ek_ra8d2.h"
#include "ra8_err.h"
#include "ra8_log.h"
#include "ra8_pfs_regs.h"
#include "ra8_port_constants.h"
#include "ra8_time.h"
#include "ra8_xspi.h"

static const char* s_lx_xspi_tag = "LX_XSPI";

typedef enum : uint32_t {
  k_ra8_lx_jedec_mfr      = 0x9DU,      
  k_ra8_lx_jedec_type     = 0x5AU,      
  k_ra8_lx_jedec_capacity = 0x1AU,      
  k_ra8_lx_jedec_expected = 0x9D5A1AUL, 
} ra8_lx_jedec_id_t;

typedef enum : uint32_t {
  k_ra8_lx_xspi_instance = 0U,

  k_ra8_lx_nor_total_blocks = 64U,

  k_ra8_lx_nor_block_bytes = 4096U,

  k_ra8_lx_nor_words_per_block = 1024U,

  k_ra8_lx_nor_word_bytes = 4U,
} ra8_lx_nor_constants_t;

typedef enum : uintptr_t {
  k_ra8_lx_nor_base_addr = 0x10000000U,
} ra8_lx_nor_base_t;

static ULONG s_ra8_lx_nor_sector_buffer[LX_NOR_SECTOR_SIZE];
 
/* Convert a LevelX ``ULONG*`` flash pointer to a byte offset -- see implementation for details. */
RA8_INTERNAL static uint32_t internal_flash_offset_bytes(ULONG* flash_address)
{
  /* LevelX adds a number-of-ULONGs offset onto base_address and hands
   * the result back to us. Recover the byte offset by subtracting the
   * base in pointer-difference units (each unit is sizeof(ULONG) = 4
   * bytes on this target). */
  uintptr_t addr = (uintptr_t)flash_address;
  uintptr_t base = k_ra8_lx_nor_base_addr;
  return (uint32_t)(addr - base);
}

RA8_INTERNAL static UINT internal_nor_read(ULONG* flash_address, ULONG* destination, ULONG words)
{
  if ((flash_address == LX_NULL) || (destination == LX_NULL) || (words == 0U)) {
    return (UINT)LX_ERROR;
  }
  uint32_t  offset = internal_flash_offset_bytes(flash_address);
  uint32_t  bytes  = (uint32_t)words * k_ra8_lx_nor_word_bytes;
  ra8_err_t err =
    ra8_xspi_flash_read((uint8_t)k_ra8_lx_xspi_instance, offset, (uint8_t*)destination, bytes);
  if (err != k_ra8_ok) {
    return (UINT)LX_ERROR;
  }
  return (UINT)LX_SUCCESS;
}

RA8_INTERNAL static UINT internal_nor_write(ULONG* flash_address, ULONG* source, ULONG words)
{
  if ((flash_address == LX_NULL) || (source == LX_NULL) || (words == 0U)) {
    return (UINT)LX_ERROR;
  }
  uint32_t  offset = internal_flash_offset_bytes(flash_address);
  uint32_t  bytes  = (uint32_t)words * k_ra8_lx_nor_word_bytes;
  ra8_err_t err =
    ra8_xspi_flash_program((uint8_t)k_ra8_lx_xspi_instance, offset, (const uint8_t*)source, bytes);
  if (err != k_ra8_ok) {
    return (UINT)LX_ERROR;
  }
  return (UINT)LX_SUCCESS;
}

RA8_INTERNAL static UINT internal_nor_block_erase(ULONG block, ULONG erase_count)
{
  LX_PARAMETER_NOT_USED(erase_count);
  if (block >= (ULONG)k_ra8_lx_nor_total_blocks) {
    return (UINT)LX_ERROR;
  }
  uint32_t  offset = (uint32_t)block * k_ra8_lx_nor_block_bytes;
  ra8_err_t err    = ra8_xspi_flash_erase_sector((uint8_t)k_ra8_lx_xspi_instance, offset);
  if (err != k_ra8_ok) {
    return (UINT)LX_ERROR;
  }
  return (UINT)LX_SUCCESS;
}

RA8_INTERNAL static UINT internal_nor_block_erased_verify(ULONG block)
{
  if (block >= (ULONG)k_ra8_lx_nor_total_blocks) {
    return (UINT)LX_ERROR;
  }
  uint32_t offset       = (uint32_t)block * k_ra8_lx_nor_block_bytes;
  uint32_t remain_words = k_ra8_lx_nor_words_per_block;
  while (remain_words > 0U) {
    uint32_t chunk_words = remain_words;
    if (chunk_words > (uint32_t)LX_NOR_SECTOR_SIZE) {
      chunk_words = (uint32_t)LX_NOR_SECTOR_SIZE;
    }
    uint32_t  chunk_bytes = chunk_words * k_ra8_lx_nor_word_bytes;
    ra8_err_t err         = ra8_xspi_flash_read((uint8_t)k_ra8_lx_xspi_instance,
                                                offset,
                                                (uint8_t*)s_ra8_lx_nor_sector_buffer,
                                                chunk_bytes);
    if (err != k_ra8_ok) {
      return (UINT)LX_ERROR;
    }
    for (uint32_t i = 0U; i < chunk_words; i++) {
      if (s_ra8_lx_nor_sector_buffer[i] != (ULONG)LX_ALL_ONES) {
        return (UINT)LX_ERROR;
      }
    }
    offset += chunk_bytes;
    remain_words -= chunk_words;
  }
  return (UINT)LX_SUCCESS;
}

typedef struct {
  uint32_t magic;        
  uint32_t call_count;   
  uint32_t rid_err;      
  uint32_t jedec_id;     
  uint32_t reset_8d_err; 
  uint32_t reset_1s_err; 
  uint32_t stage;        
  uint32_t reserved;     
} ra8_xspi_rdid_observation_t;

typedef enum : uint32_t {
  k_ra8_xspi_stage_pins     = 1U, 
  k_ra8_xspi_stage_init_8d  = 2U, 
  k_ra8_xspi_stage_reset_8d = 3U, 
  k_ra8_xspi_stage_init_1s  = 4U, 
  k_ra8_xspi_stage_reset_1s = 5U, 
  k_ra8_xspi_stage_rdid     = 6U, 
  k_ra8_xspi_stage_done     = 7U, 
} ra8_xspi_stage_t;

typedef enum : uint32_t {
  k_ra8_xspi_rdid_magic = 0x44494452UL, 
} ra8_xspi_rdid_magic_t;

ra8_xspi_rdid_observation_t g_ra8_xspi_rdid_observed;

typedef enum : uint8_t {
  k_ra8_xspi_pin_count = 12U, 
} ra8_xspi_pin_count_t;

typedef struct {
  uint8_t  port;          
  uint8_t  pin;           
  uint8_t  psel_observed; 
  uint8_t  pmr_observed;  
  uint32_t pfs_raw;       
} ra8_xspi_pin_observation_t;

ra8_xspi_pin_observation_t g_ra8_xspi_pin_observed[k_ra8_xspi_pin_count];

typedef struct {
  uint8_t port; 
  uint8_t pin;  
} ra8_xspi_pin_ref_t;

static const ra8_xspi_pin_ref_t s_ra8_xspi_pin_refs[k_ra8_xspi_pin_count] = {
  {(uint8_t)k_ra8_port_1, (uint8_t)k_ra8_pin_4}, 
  {(uint8_t)k_ra8_port_8, (uint8_t)k_ra8_pin_8}, 
  {(uint8_t)k_ra8_port_8, (uint8_t)k_ra8_pin_1}, 
  {(uint8_t)k_ra8_port_1, (uint8_t)k_ra8_pin_0}, 
  {(uint8_t)k_ra8_port_8, (uint8_t)k_ra8_pin_3}, 
  {(uint8_t)k_ra8_port_1, (uint8_t)k_ra8_pin_3}, 
  {(uint8_t)k_ra8_port_1, (uint8_t)k_ra8_pin_1}, 
  {(uint8_t)k_ra8_port_1, (uint8_t)k_ra8_pin_2}, 
  {(uint8_t)k_ra8_port_8, (uint8_t)k_ra8_pin_0}, 
  {(uint8_t)k_ra8_port_8, (uint8_t)k_ra8_pin_2}, 
  {(uint8_t)k_ra8_port_8, (uint8_t)k_ra8_pin_4}, 
  {0xFFU, 0xFFU},                                
};

typedef enum : uint8_t {
  k_ra8_lx_pin_unobserved = 0xFFU, 
  k_ra8_lx_pfs_psel_mask  = 0x1FU, 
} ra8_lx_pin_diag_t;

RA8_INTERNAL static void internal_capture_xspi_pin_state(void)
{
  for (uint8_t i = 0U; i < (uint8_t)k_ra8_xspi_pin_count; i++) {
    const uint8_t port                       = s_ra8_xspi_pin_refs[i].port;
    const uint8_t pin                        = s_ra8_xspi_pin_refs[i].pin;
    g_ra8_xspi_pin_observed[i].port          = port;
    g_ra8_xspi_pin_observed[i].pin           = pin;
    g_ra8_xspi_pin_observed[i].psel_observed = (uint8_t)k_ra8_lx_pin_unobserved;
    g_ra8_xspi_pin_observed[i].pmr_observed  = (uint8_t)k_ra8_lx_pin_unobserved;
    g_ra8_xspi_pin_observed[i].pfs_raw       = 0U;
    if ((port > (uint8_t)k_ra8_port_max) || (pin > (uint8_t)k_ra8_pin_max)) {
      continue;
    }
    volatile uint32_t* pfs = ra8_pfs_pmn((ra8_port_t)port, (ra8_pin_t)pin);
    if (pfs == nullptr) {
      continue;
    }
    const uint32_t raw                 = *pfs;
    g_ra8_xspi_pin_observed[i].pfs_raw = raw;
    g_ra8_xspi_pin_observed[i].psel_observed =
      (uint8_t)((raw >> (uint32_t)k_ra8_pfs_bit_psel0) & (uint32_t)k_ra8_lx_pfs_psel_mask);
    g_ra8_xspi_pin_observed[i].pmr_observed =
      (uint8_t)(((raw & (uint32_t)k_ra8_pfs_mask_pmr) != 0U) ? 1U : 0U);
  }
}

static bool s_xspi_bus_ready = false;

typedef enum : uint32_t {
  k_ra8_xspi_reset_settle_ms = 1U, 
} ra8_xspi_reset_timing_t;

typedef enum : uint8_t {
  k_ra8_xspi_reset_form_1s = 1U, 
  k_ra8_xspi_reset_form_8d = 2U, 
} ra8_xspi_reset_form_t;

RA8_INTERNAL static void internal_stamp_observed_start(void)
{
  g_ra8_xspi_rdid_observed.magic = (uint32_t)k_ra8_xspi_rdid_magic;
  g_ra8_xspi_rdid_observed.call_count += 1U;
  g_ra8_xspi_rdid_observed.rid_err      = (uint32_t)k_ra8_ok;
  g_ra8_xspi_rdid_observed.jedec_id     = 0U;
  g_ra8_xspi_rdid_observed.reset_8d_err = (uint32_t)k_ra8_ok;
  g_ra8_xspi_rdid_observed.reset_1s_err = (uint32_t)k_ra8_ok;
  g_ra8_xspi_rdid_observed.stage        = (uint32_t)k_ra8_xspi_stage_pins;
}

RA8_INTERNAL static UINT internal_reset_phase_8d(void)
{
  g_ra8_xspi_rdid_observed.stage = (uint32_t)k_ra8_xspi_stage_init_8d;
  if (ra8_xspi_init((uint8_t)k_ra8_lx_xspi_instance, k_ra8_xspi_lio_8d8d8d) != k_ra8_ok) {
    ra8_log_error(s_lx_xspi_tag, "ra8_xspi_init 8d failed");
    return (UINT)LX_ERROR;
  }
  g_ra8_xspi_rdid_observed.stage = (uint32_t)k_ra8_xspi_stage_reset_8d;
  const ra8_err_t reset_8d =
    ra8_xspi_software_reset((uint8_t)k_ra8_lx_xspi_instance, (uint8_t)k_ra8_xspi_reset_form_8d);
  g_ra8_xspi_rdid_observed.reset_8d_err = (uint32_t)reset_8d;
  /* Tolerate timeouts here: if the chip is in 1S mode, the 8D bytes
   * never form a recognised opcode and CMDCMP may legitimately stall.
   * The Phase-B 1S reset will recover regardless. */
  ra8_delay_ms((uint32_t)k_ra8_xspi_reset_settle_ms);
  return (UINT)LX_SUCCESS;
}

RA8_INTERNAL static UINT internal_reset_phase_1s(void)
{
  g_ra8_xspi_rdid_observed.stage = (uint32_t)k_ra8_xspi_stage_init_1s;
  if (ra8_xspi_init((uint8_t)k_ra8_lx_xspi_instance, k_ra8_xspi_lio_1s1s1s) != k_ra8_ok) {
    ra8_log_error(s_lx_xspi_tag, "ra8_xspi_init 1s failed");
    return (UINT)LX_ERROR;
  }
  g_ra8_xspi_rdid_observed.stage = (uint32_t)k_ra8_xspi_stage_reset_1s;
  const ra8_err_t reset_1s =
    ra8_xspi_software_reset((uint8_t)k_ra8_lx_xspi_instance, (uint8_t)k_ra8_xspi_reset_form_1s);
  g_ra8_xspi_rdid_observed.reset_1s_err = (uint32_t)reset_1s;
  ra8_delay_ms((uint32_t)k_ra8_xspi_reset_settle_ms);
  return (UINT)LX_SUCCESS;
}

RA8_INTERNAL static UINT internal_probe_rdid(void)
{
  g_ra8_xspi_rdid_observed.stage = (uint32_t)k_ra8_xspi_stage_rdid;
  uint32_t        jedec_id       = 0U;
  const ra8_err_t rid_err = ra8_xspi_flash_read_id((uint8_t)k_ra8_lx_xspi_instance, &jedec_id);
  g_ra8_xspi_rdid_observed.rid_err  = (uint32_t)rid_err;
  g_ra8_xspi_rdid_observed.jedec_id = jedec_id;
  if (rid_err != k_ra8_ok) {
    ra8_log_error_val(s_lx_xspi_tag, "RDID transfer failed err", (uint32_t)rid_err);
    return (UINT)LX_ERROR;
  }
  ra8_log_info_val(s_lx_xspi_tag, "RDID returned", jedec_id);
  if (jedec_id != (uint32_t)k_ra8_lx_jedec_expected) {
    ra8_log_error_val(s_lx_xspi_tag, "RDID mismatch (expected 0x9D5A1A); got", jedec_id);
    return (UINT)LX_ERROR;
  }
  return (UINT)LX_SUCCESS;
}

RA8_INTERNAL static UINT internal_bus_init_once(void)
{
  if (s_xspi_bus_ready) {
    return (UINT)LX_SUCCESS;
  }
 
  /* Stamp the magic + bump the counter BEFORE any HAL call so even a
   * hang inside the controller leaves a visible breadcrumb at the
   * known SRAM address. */
  internal_stamp_observed_start();
 
  if (ra8_board_xspi_pins_init() != k_ra8_ok) {
    /* Capture whatever pin state we have BEFORE bailing so JLink can
     * see how far the BSP got even on partial-failure paths. */
    internal_capture_xspi_pin_state();
    ra8_log_error(s_lx_xspi_tag, "xspi pin init failed");
    return (UINT)LX_ERROR;
  }
  /* Snapshot post-init PSEL on every OCTA pad. Any row where
   * psel_observed != 0x1C or pmr_observed != 1 means the BSP enum is
   * wrong for that pin -- the chip will not see that signal. */
  internal_capture_xspi_pin_state();
 
  const UINT phase_a = internal_reset_phase_8d();
  if (phase_a != (UINT)LX_SUCCESS) {
    return phase_a;
  }
  const UINT phase_b = internal_reset_phase_1s();
  if (phase_b != (UINT)LX_SUCCESS) {
    return phase_b;
  }
  const UINT probe = internal_probe_rdid();
  if (probe != (UINT)LX_SUCCESS) {
    return probe;
  }
 
  g_ra8_xspi_rdid_observed.stage = (uint32_t)k_ra8_xspi_stage_done;
  s_xspi_bus_ready               = true;
  return (UINT)LX_SUCCESS;
}
 
/* Lx nor driver ra xspi initialize -- see implementation for details. */
UINT lx_nor_driver_ra8_xspi_initialize(LX_NOR_FLASH* nor_flash)
{
  if (nor_flash == LX_NULL) {
    return (UINT)LX_ERROR;
  }
 
  /* Idempotent bus bring-up: pins + xSPI controller. Done here (not
   * in main) so the LevelX driver is self-contained and apps don't
   * have to remember the order of init calls. */
  const UINT bus = internal_bus_init_once();
  if (bus != (UINT)LX_SUCCESS) {
    return bus;
  }
 
  /* Programme the synthetic base + geometry. LevelX uses the base
   * pointer as a cookie when calling back into our read / write
   * callbacks; we recover the byte offset from it inside
   * internal_flash_offset_bytes(). */
  nor_flash->lx_nor_flash_base_address    = (ULONG*)(uintptr_t)k_ra8_lx_nor_base_addr;
  nor_flash->lx_nor_flash_total_blocks    = (ULONG)k_ra8_lx_nor_total_blocks;
  nor_flash->lx_nor_flash_words_per_block = (ULONG)k_ra8_lx_nor_words_per_block;
 
  /* Wire up the four LevelX driver callbacks. */
  nor_flash->lx_nor_flash_driver_read                = internal_nor_read;
  nor_flash->lx_nor_flash_driver_write               = internal_nor_write;
  nor_flash->lx_nor_flash_driver_block_erase         = internal_nor_block_erase;
  nor_flash->lx_nor_flash_driver_block_erased_verify = internal_nor_block_erased_verify;
 
  /* Hand LevelX a 512-byte ULONG-aligned RAM scratch buffer for its
   * sector-mapping reads. */
  nor_flash->lx_nor_flash_sector_buffer = &s_ra8_lx_nor_sector_buffer[0];
 
  return (UINT)LX_SUCCESS;
}