Octal Serial Peripheral Interface (OSPI / xSPI) driver. More...

#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"

Include dependency graph for ra8_xspi.c:

Data Structures
struct	ra8_xspi_state_t
	Per-instance callback state. More...

Enumerations
enum	ra8_xspi_cmd_limits_t : uint8_t { k_ra8_xspi_cmd_max_bytes = 16U }
	Byte-count limits on raw direct-command buffers. More...
enum	ra8_xspi_chip_select_t : uint8_t { k_ra8_xspi_onboard_cs = 1U }
	Which controller chip-select drives the on-board OSPI flash. More...
enum	ra8_xspi_reset_delay_t : uint32_t { k_ra8_xspi_reset_spin = 100000U }
	Bounded busy-spin counts for the LIOCTL.RSTCS reset pulse. More...
enum	ra8_xspi_jedec_extra_t : 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 }
	Extra JEDEC opcodes used by suspend/resume control. More...
enum	ra8_xspi_reset_cmd_bytes_t : uint8_t { k_ra8_xspi_reset_cmd_bytes_1s = 1U , k_ra8_xspi_reset_cmd_bytes_8d = 2U }
	Allowed cmd_bytes values for ra8_xspi_software_reset. More...
enum	ra8_xspi_addr_bytes_t : uint8_t { k_ra8_xspi_addr_bytes_3 = 3U , k_ra8_xspi_addr_bytes_4 = 4U }
	Allowed address-byte widths for ra8_xspi_set_xip_mode. More...
enum	ra8_xspi_calib_spin_t : uint32_t { k_ra8_xspi_calib_spin = 1024U }
	Bounded spin budget for the auto-calibration handshake. More...

Functions
static ra8_err_t	internal_wait_octacksrdy (uint8_t expected)
	Bounded wait on OCTACKCR.OCTACKSRDY reaching expected.
static ra8_err_t	internal_xspi_clock_block_init (void)
	Block-level OCTA clock init – run BEFORE the first MSTP release.
static void	internal_xspi_reset_spin (void)
	Bounded busy-spin used between the RSTCS reset edges.
static void	internal_xspi_reset_device (volatile r_xspi_regs_t *reg)
	Pulse the controller-driven flash RESET (LIOCTL.RSTCS) low->high.
static void	internal_xspi_apply_config (volatile r_xspi_regs_t *reg, ra8_xspi_lio_mode_t mode)
	Apply the manual-command controller config for the on-board flash.
ra8_err_t	ra8_xspi_init (uint8_t instance, ra8_xspi_lio_mode_t mode)
	Initialise an xSPI instance in the chosen link-layer IO mode.
ra8_err_t	ra8_xspi_direct_command (uint8_t instance, const uint8_t *cmd_buf, uint8_t len)
	Issue a raw command via the direct-command registers.
ra8_err_t	ra8_xspi_deinit (uint8_t instance)
	Tear down the xSPI instance (disable + MSTP release).
ra8_err_t	ra8_xspi_get_status (uint8_t instance, uint32_t *out_mask)
	Read the xSPI COMSTT busy/error mask.
ra8_err_t	ra8_xspi_clear_status (uint8_t instance, uint32_t mask)
	Clear transfer-complete / error bits in INTS via INTC.
ra8_err_t	ra8_xspi_attach_handler (uint8_t instance, ra8_xspi_event_fn_t fn, void *ctx)
	Attach a completion callback.
void	ra8_xspi_dispatch (uint8_t instance)
	Dispatch an xSPI event – snapshot INTS + fire callback.
ra8_err_t	ra8_xspi_enter_stop (uint8_t instance)
	Put an xSPI instance into MSTP-gated stop.
ra8_err_t	ra8_xspi_exit_stop (uint8_t instance)
	Exit MSTP-gated stop.
ra8_err_t	ra8_xspi_xip_enter (uint8_t instance, uint8_t enter_code, uint8_t exit_code)
	Enable XIP (execute-in-place) memory-mapped read mode.
ra8_err_t	ra8_xspi_xip_exit (uint8_t instance)
	Disable XIP mode and restore command-only access.
ra8_err_t	ra8_xspi_set_xip_mode (uint8_t instance, bool enable, uint8_t read_cmd, uint8_t addr_bytes)
	Enable or disable memory-mapped (XIP) read mode.
ra8_err_t	ra8_xspi_set_dtr_mode (uint8_t instance, bool enable)
	Enable or disable double-data-rate (DDR / DTR) link mode.
ra8_err_t	ra8_xspi_calibrate_dqs (uint8_t instance)
	Run the data-strobe (DQS) calibration sequence.
ra8_err_t	ra8_xspi_suspend (uint8_t instance)
	Suspend a long-running flash erase / program operation.
ra8_err_t	ra8_xspi_resume (uint8_t instance)
	Resume a previously suspended erase / program.
static ra8_err_t	internal_issue_reset_opcode (volatile r_xspi_regs_t *reg, uint8_t opcode, uint8_t cmd_bytes)
	Issue a single RSTEN-or-RST opcode in either 1S or 8D form.
ra8_err_t	ra8_xspi_software_reset (uint8_t instance, uint8_t cmd_bytes)
	Issue the JEDEC software-reset pair (RSTEN 0x66 + RST 0x99).

Variables
static const char *	s_tag = "XSPI"
	Logging tag for this driver.
static const ra8_mstp_t	s_xspi_mstp_table []
	Instance-index -> MSTP id lookup.
static ra8_xspi_state_t	s_xspi_state [k_ra8_xspi_instance_count]
	Per-instance callback state (s_ prefix for file-static).

Detailed Description

Octal Serial Peripheral Interface (OSPI / xSPI) driver.

Tag: [Ring 3 / HAL] {World: S}

driver for the RA8D2 OSPI block. Provides a minimal SPI NOR flash driver layered on top of the xSPI manual-command engine (CDCTL0 + CDBUF[] + INTS.CMDCMP).

This translation unit owns the block/clock/reset bring-up and the lifecycle + IRQ + power + XIP/DTR/DQS-calibration + software-reset surface:

ra8_xspi_init() – select a protocol mode + clear pending IRQs.
ra8_xspi_direct_command() – raw CDBUF poke.
ra8_xspi_deinit / get_status / clear_status / attach_handler / enter_stop / exit_stop lifecycle + IRQ + power surface.
ra8_xspi_set_xip_mode / set_dtr_mode / calibrate_dqs / suspend / resume / software_reset extended controller surface.

The manual-command engine and the JEDEC NOR-flash read / program / erase / status / id operations live in the sibling translation unit ra8_xspi_flash.c; the two manual-command primitives it exports (priv_ra8_xspi_kick_command / priv_ra8_xspi_issue_simple_opcode) are declared in ra8_xspi_internal.h and reused here by the suspend / resume / software-reset paths.

CDBUF convention used by this driver

Each CDBUF slot is 4 x 32-bit words wide. This driver writes exclusively to slot 0 and encodes a manual transfer as:

CDBUF[0] – opcode byte in the low 8 bits.
CDBUF[1] – flash address (3- or 4-byte).
CDBUF[2] – write-data low word (bytes 0..3).
CDBUF[3] – write-data high word (bytes 4..7).

Read responses (status, JEDEC ID, flash-read bytes) land in CDBUF[2] / CDBUF[3] after the controller clears TRREQ.

Every build emits the identical register sequence; host unit tests round-trip data through the register-level NOR-flash model in tests/mocks/src/ra8_fake_xspi_flash.c, which services each TRREQ kick from the CMDCMP poll's ra8_fake_mmio seam consult (#238). Every register write carries a HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986 citation comment for the cite checker.

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Definition in file ra8_xspi.c.

Enumeration Type Documentation

◆ ra8_xspi_addr_bytes_t

enum ra8_xspi_addr_bytes_t : uint8_t

Allowed address-byte widths for ra8_xspi_set_xip_mode.

Enumerator
k_ra8_xspi_addr_bytes_3	24-bit JEDEC address.
k_ra8_xspi_addr_bytes_4	32-bit JEDEC address.

Definition at line 604 of file ra8_xspi.c.

◆ ra8_xspi_calib_spin_t

enum ra8_xspi_calib_spin_t : uint32_t

Bounded spin budget for the auto-calibration handshake.

Enumerator
k_ra8_xspi_calib_spin	CCCTL0.CAEN poll budget.

Definition at line 613 of file ra8_xspi.c.

◆ ra8_xspi_chip_select_t

enum ra8_xspi_chip_select_t : uint8_t

Which controller chip-select drives the on-board OSPI flash.

The xSPI controller fans every manual command out to one of two chip-select devices (CS0 / CS1). Which physical CS strobe pin that maps to is a board fact, not a per-call knob: on the EK-RA8D2 the on-board IS25LX512M's chip-select net (OSPI_FLASH_S_L, P104) is wired to the controller's CS**1** line, and the Renesas FSP EK-RA8D2 OSPI configuration (configuration.xml module.driver.ospi_b.channel = channel.1) confirms the vendor drives the part on device 1. The controller therefore must (a) carry the protocol/timing config in LIOCFGCS[1] and (b) assert CDCTL0.CSSEL = 1 on every manual command, or the CS0 strobe (an unconnected pin) toggles instead, the flash never sees chip-select, and RDID floats to 0x00FFFFFF on the board pull-ups. HUM Ch 44 p 2986; EK-RA8D2 UM Table 29 p 35.

Enumerator
k_ra8_xspi_onboard_cs	IS25LX512M is on controller CS1.

Definition at line 100 of file ra8_xspi.c.

◆ ra8_xspi_cmd_limits_t

enum ra8_xspi_cmd_limits_t : uint8_t

Byte-count limits on raw direct-command buffers.

Enumerator
k_ra8_xspi_cmd_max_bytes	A CDBUF slot holds 16 bytes.

Definition at line 78 of file ra8_xspi.c.

◆ ra8_xspi_jedec_extra_t

enum ra8_xspi_jedec_extra_t : uint8_t

Extra JEDEC opcodes used by suspend/resume control.

Enumerator
k_ra8_spi_flash_op_suspend	0x75 erase/program suspend.
k_ra8_spi_flash_op_resume	0x7A erase/program resume.
k_ra8_spi_flash_op_reset_en	0x66 RSTEN – IS25LX512M Ch 8.20 p 39.
k_ra8_spi_flash_op_reset_dev	0x99 RST – IS25LX512M Ch 8.21 p 39.

Definition at line 579 of file ra8_xspi.c.

◆ ra8_xspi_reset_cmd_bytes_t

enum ra8_xspi_reset_cmd_bytes_t : uint8_t

Allowed cmd_bytes values for ra8_xspi_software_reset.

1-byte opcodes are used in 1S-1S-1S extended SPI mode, 2-byte opcodes (opcode | (~opcode << 8)) in 8D-8D-8D OPI/DDR mode. Cite: IS25LX512M datasheet Ch 7.3 "Operating Protocols" p 27.

Enumerator
k_ra8_xspi_reset_cmd_bytes_1s	1-byte opcode for 1S-1S-1S.
k_ra8_xspi_reset_cmd_bytes_8d	2-byte opcode pair for 8D-8D-8D.

Definition at line 595 of file ra8_xspi.c.

◆ ra8_xspi_reset_delay_t

enum ra8_xspi_reset_delay_t : uint32_t

Bounded busy-spin counts for the LIOCTL.RSTCS reset pulse.

The vendor EK-RA8D2 bring-up (ospi_flash_issi_is25lx512.c reset_ospi_device) holds LIOCTL.RSTCS low for ~50 us and high for ~50 us. With no SysTick dependency in this driver the wait is a bounded register-free busy loop; at ~1 cycle per iteration on the 1 GHz Cortex-M85 k_ra8_xspi_reset_spin iterations is comfortably over the IS25LX512M tRLRH/tRHSL minima (100 ns each) while staying in the tens-of-microseconds the vendor uses. IS25LX512M datasheet Ch 9.2 "Hardware Reset".

Enumerator
k_ra8_xspi_reset_spin	~tens of us busy-spin per reset edge.

Definition at line 118 of file ra8_xspi.c.

Function Documentation

◆ internal_issue_reset_opcode()

ra8_err_t internal_issue_reset_opcode	(	volatile r_xspi_regs_t *	reg,
		uint8_t	opcode,
		uint8_t	cmd_bytes )

static

Issue a single RSTEN-or-RST opcode in either 1S or 8D form.

In 1S-1S-1S mode the opcode is a single byte placed at CDT.CMD bits [31..16] with CMDSIZE=1. In 8D-8D-8D mode the chip expects the opcode followed by its bitwise complement so the controller has to ship two bytes; we encode that as opcode | (~opcode << 8) in the same CMD field with CMDSIZE=2. The CDT.CMD field is 16 bits wide ([31..16]) so both forms fit cleanly. No address phase, no data phase. IS25LX512M datasheet Ch 7.3 p 27 ("Operating Protocols")

Ch 8.20/8.21 p 39 (RSTEN/RST opcodes); HUM Ch 44 p 2986 for the CDT layout.

Parameters

[in]	reg	xSPI register block.
[in]	opcode	JEDEC reset opcode (0x66 RSTEN or 0x99 RST).
[in]	cmd_bytes	1 (1S) or 2 (8D); chosen by the caller based on the protocol mode the chip might be in.

Returns: k_ra8_ok on success, k_ra8_err_hw_timeout on CMDCMP timeout.

Return values

k_ra8_ok	Operation completed successfully.
other	Non-zero error code from the underlying operation.

Precondition: Module/state preconditions hold (see function body).; Module/state preconditions hold (see function body).

Postcondition: Documented side effects are visible on success.; Documented side effects are visible on success.

Note: Not thread-safe; the caller must serialise concurrent access.

Since: 0.1.0

Definition at line 729 of file ra8_xspi.c.

References r_xspi_regs_t::CDBUF, k_ra8_xspi_cdbuf_idx_addr, k_ra8_xspi_cdbuf_idx_cdt, k_ra8_xspi_cdbuf_idx_data0, k_ra8_xspi_cdbuf_idx_data1, k_ra8_xspi_cdt_addsize_0, k_ra8_xspi_cdt_mask_addsize, k_ra8_xspi_cdt_mask_cmdsize, k_ra8_xspi_cdt_mask_trtype, k_ra8_xspi_cdt_pos_addsize, k_ra8_xspi_cdt_pos_cmd, k_ra8_xspi_cdt_pos_cmdsize, k_ra8_xspi_cdt_pos_trtype, k_ra8_xspi_cdt_trtype_write, k_ra8_xspi_reset_cmd_bytes_8d, and priv_ra8_xspi_kick_command().

Referenced by ra8_xspi_software_reset().

◆ internal_wait_octacksrdy()

ra8_err_t internal_wait_octacksrdy ( uint8_t expected )

static

Bounded wait on OCTACKCR.OCTACKSRDY reaching expected.

Mirrors internal_wait_canfdcksrdy in ra8_canfd.c and internal_wait_usbcksrdy in ra8_cgc.c. Polls OCTACKCR bit 7 (OCTACKSRDY) until it equals expected or k_ra8_xspi_ckcr_spin iterations elapse. HUM Ch 9.2.45 "OCTACKCR" p 360 documents OCTACKSRDY at bit 7 (R) – "Possible to Switch" flag.

Parameters

[in] expected 1U after SREQ=1; 0U after SREQ=0.

Returns: ra8_err_t outcome.

Return values

k_ra8_ok	SRDY observed equal to expected.
k_ra8_err_hw_timeout	SRDY never matched within the budget.

Precondition: Caller holds the PRCR-CGC unlock window (PRCR=0xA501).; expected is 0 or 1.

Postcondition: No register state is modified – this is a read-only poll.; On timeout the caller relocks PRCR.

Note: Not thread-safe; init context only.

Since: 0.1.0

Definition at line 158 of file ra8_xspi.c.

References k_ra8_usbckcr_bit_srdy, k_ra8_xspi_ckcr_spin, ra8_hw_wait_flag_clear8(), ra8_hw_wait_flag_set8(), and ra8_sys_octackcr().

Referenced by internal_xspi_clock_block_init().

◆ internal_xspi_apply_config()

void internal_xspi_apply_config	(	volatile r_xspi_regs_t *	reg,
		ra8_xspi_lio_mode_t	mode )

static

Apply the manual-command controller config for the on-board flash.

Wakes the wrapper, idles the common/XiP config, writes the link-IO protocol mode into the on-board chip-select's LIOCFGCS slot, and points the manual-command engine at that CS via CDCTL0.CSSEL. BMCTL0 is forced disabled so the AHB system-bus path cannot race the manual-command engine (FSP gates this via r_ospi_b_xip(false)); leaving it enabled lets the controller NAK CDCTL0.TRREQ and time out CMDCMP. CMCTLCH[0/1] are zeroed so XIPEN is not left armed. The CS is k_ra8_xspi_onboard_cs (CS1): the EK-RA8D2 IS25LX512M is wired there (FSP OSPI example channel == 1); an earlier CS0 default strobed an unconnected pin and floated RDID to 0x00FFFFFF (issue #44). HUM Ch 44 p 2986.

Parameters

[in]	reg	xSPI register block (already gated open by the caller).
[in]	mode	Link-IO protocol/latency word for LIOCFGCS.

Returns: None.

Precondition: reg != nullptr and the xSPI MSTP gate is open.; OCTACLK is stable (clock-block handshake done).

Postcondition: LIOCFGCS[k_ra8_xspi_onboard_cs] == mode and CDCTL0.CSSEL selects that CS; latent interrupt flags are cleared.; BMCTL0 is disabled (manual-command path owns the bus).

Note: Not thread-safe; init context only.

Since: 0.1.0

Definition at line 358 of file ra8_xspi.c.

References r_xspi_regs_t::BMCTL0, r_xspi_regs_t::CDCTL0, r_xspi_regs_t::CMCTLCH, r_xspi_regs_t::COMCFG, r_xspi_regs_t::INTC, k_ra8_xspi_bmctl0_disabled, k_ra8_xspi_cdctl0_bit_cssel, k_ra8_xspi_cdctl0_mask_cssel, k_ra8_xspi_ints_mask_all, k_ra8_xspi_onboard_cs, r_xspi_regs_t::LIOCFGCS, and r_xspi_regs_t::WRAPCFG.

Referenced by ra8_xspi_init().

◆ internal_xspi_clock_block_init()

ra8_err_t internal_xspi_clock_block_init ( void )

static

Block-level OCTA clock init – run BEFORE the first MSTP release.

HUM Ch 11.2.7 "MSTPCRB" Note 3 (p 444) states that MSTPB16 / MSTPB17 (the per-instance OSPI module-stop bits) must be written AFTER the OCTACLK is stable. OCTACKCR resets to 0x01 (OCTACKSEL = MOCO, OCTACKSREQ = 0, OCTACKSRDY = 0). MOCO is on at reset, but the RA8D2 CGC requires an explicit SREQ -> SRDY -> SREQ-clear handshake before the chip raises OCTACKSRDY and declares the clock stable. Without that handshake the OSPI manual-command engine's internal state machine cannot retire CDCTL0.TRREQ after the first CDBUF[0].CDT write – symptom seen on HIL: every ra8_xspi_flash_* operation surfaces as k_ra8_err_hw_timeout on CMDCMP, and flash_journal's g_fj_match / g_fj_mismatch counters both read 0 across the 5 s memprobe window.

Steps (mirror of internal_canfd_clock_block_init in ra8_canfd.c + the USBCKCR pattern in ra8_cgc.c, with the OCTACKCR-specific procedure from HUM Ch 9.2.45 p 360):

Write OCTACKDIVCR = 0 (/1 – documented reset value).
Set OCTACKCR.OCTACKSREQ = 1 (request switch) while keeping the reset-default OCTACKSEL = MOCO.
Poll until OCTACKSRDY = 1.
Re-write OCTACKCR with SREQ=0, source = MOCO – commits the (same) source selection.
Poll until OCTACKSRDY = 0 (handshake done).

This helper is idempotent via a static guard: only the first caller performs the handshake; subsequent ra8_xspi_init calls (e.g. for instance 1 after instance 0) skip it. MOCO -> /1 keeps OCTACLK at its native MOCO rate (~8 MHz nominal) which is fine for the IS25LX JEDEC-mode bring-up; a later board-specific tune can switch the source to a PLL output by reissuing the same handshake.

Returns: ra8_err_t outcome.

Return values

k_ra8_ok	OCTACLK declared stable; safe to release MSTP.
k_ra8_err_hw_timeout	SRDY handshake stuck.

Precondition: Single-threaded init context (no other CGC writes in flight).; MOCO is running – chip reset default; ra8_cgc_init does not explicitly stop MOCO.

Postcondition: On k_ra8_ok the OCTA block clock is stable; MSTPB16/17 may now be released.; On error the OSPI MSTP gate is NOT touched.; PRCR is re-locked.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 225 of file ra8_xspi.c.

References internal_wait_octacksrdy(), k_ra8_ok, k_ra8_prcr_unlock_cgc, k_ra8_usbckcr_bit_sreq, ra8_log_error, ra8_log_info, RA8_PROTECTED_WRITE, ra8_sys_octackcr(), ra8_sys_octackdivcr(), and s_tag.

Referenced by ra8_xspi_init().

◆ internal_xspi_reset_device()

void internal_xspi_reset_device ( volatile r_xspi_regs_t * reg )

static

Pulse the controller-driven flash RESET (LIOCTL.RSTCS) low->high.

Mirror of the vendor EK-RA8D2 bring-up (ospi_b_ep.c ospi_b_init and ospi_flash_issi_is25lx512.c reset_ospi_device): after the controller protocol/timing config is in place, drive LIOCTL.RSTCS low, wait, then high, wait. This issues a hardware reset to the selected chip-select's flash through the controller's RESET output, returning a device that a prior loader may have left in OPI/DOPI back to its power-on 1S SPI protocol. WPCS is held high (write-protect deasserted) throughout. HUM Ch 44 p 2986.

Parameters

[in] reg xSPI register block (already gated open by the caller).

Returns: None.

Precondition: reg != nullptr and the xSPI MSTP gate is open.; The link-IO protocol/timing config has already been written.

Postcondition: The on-board flash has seen a RESET low->high pulse and RSTCS is left deasserted (1).; WPCS remains high (write-protect deasserted).

Note: Not thread-safe; init context only.

Since: 0.1.0

Definition at line 318 of file ra8_xspi.c.

References internal_xspi_reset_spin(), k_ra8_xspi_lioctl_mask_rstcs, k_ra8_xspi_lioctl_mask_wpcs, and r_xspi_regs_t::LIOCTL.

Referenced by ra8_xspi_init().

◆ internal_xspi_reset_spin()

void internal_xspi_reset_spin ( void )

static

Bounded busy-spin used between the RSTCS reset edges.

Register-free delay (no SysTick dependency from this HAL driver). volatile counter so the optimiser cannot elide the loop. Sized by k_ra8_xspi_reset_spin to span the IS25LX512M tRLRH/tRHSL minima. IS25LX512M datasheet Ch 9.2 "Hardware Reset".

Returns: None.

Precondition: Called only from the single-threaded xSPI init path.; No interrupt depends on this delay being preempted.

Postcondition: At least k_ra8_xspi_reset_spin iterations have elapsed.; No registers or shared state are modified.

Note: Runs on every build; the host burns the same bounded loop so no code path is compiled out of the coverage build.

Since: 0.1.0

Definition at line 286 of file ra8_xspi.c.

References k_ra8_xspi_reset_spin.

Referenced by internal_xspi_reset_device().

◆ ra8_xspi_attach_handler()

ra8_err_t ra8_xspi_attach_handler	(	uint8_t	instance,
		ra8_xspi_event_fn_t	fn,
		void *	ctx )

nodiscard

Attach a completion callback.

Since: 0.1.0

Definition at line 483 of file ra8_xspi.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_xspi_instance_count, and s_xspi_state.

◆ ra8_xspi_calibrate_dqs()

ra8_err_t ra8_xspi_calibrate_dqs ( uint8_t instance )

nodiscard

Run the data-strobe (DQS) calibration sequence.

Project-native equivalent of FSP R_OSPI_B_AutoCalibrate for target 0. Programmes the CCCTLCS[0..7] calibration descriptor with FSP-derived defaults, sets CAEN to start the controller's automatic phase-scan state machine, then polls until the controller clears CAEN itself or the bounded spin budget expires. On success the controller updates WRAPCFG.DSSFTCS0 with the winning sample-shift code. Cite: HUM Ch 44 p 2986.

Parameters

[in] instance xSPI instance (0 or 1).

Returns: k_ra8_ok on success.; k_ra8_err_null_ptr if instance is out of range.; k_ra8_err_hw_timeout if calibration never completes.

Precondition: Driver was initialized in an OPI / 8D mode.

Postcondition: CCCTL0.CAEN is 0.; On host builds the calibration step is a no-op that returns k_ra8_ok (no real DQS line to phase-scan).

Since: 0.1.0

Definition at line 664 of file ra8_xspi.c.

References r_xspi_regs_t::CCCTLCS, k_ra8_xspi_calib_spin, k_ra8_xspi_ccctl0_mask_caen, RA8_CHECK_NULL_PTR, ra8_hw_wait_flag_clear32(), ra8_xspi(), and s_tag.

◆ ra8_xspi_clear_status()

ra8_err_t ra8_xspi_clear_status	(	uint8_t	instance,
		uint32_t	mask )

nodiscard

Clear transfer-complete / error bits in INTS via INTC.

Since: 0.1.0

Definition at line 474 of file ra8_xspi.c.

References r_xspi_regs_t::INTC, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_xspi(), and s_tag.

◆ ra8_xspi_deinit()

ra8_err_t ra8_xspi_deinit ( uint8_t instance )

nodiscard

Tear down the xSPI instance (disable + MSTP release).

Since: 0.1.0

Definition at line 449 of file ra8_xspi.c.

References r_xspi_regs_t::INTC, r_xspi_regs_t::INTE, k_ra8_xspi_ints_mask_all, r_xspi_regs_t::LIOCFGCS, RA8_CHECK_NULL_PTR, ra8_mstp_disable(), ra8_xspi(), s_tag, s_xspi_mstp_table, and s_xspi_state.

◆ ra8_xspi_direct_command()

ra8_err_t ra8_xspi_direct_command	(	uint8_t	instance,
		const uint8_t *	cmd_buf,
		uint8_t	len )

nodiscard

Issue a raw command via the direct-command registers.

Parameters

[in]	instance	xSPI channel (0 or 1).
[in]	cmd_buf	Up to 16 bytes of command / address / data.
[in]	len	Number of bytes in cmd_buf.

Since: 0.1.0

Definition at line 402 of file ra8_xspi.c.

References r_xspi_regs_t::CDBUF, k_ra8_err_invalid_size, k_ra8_err_out_of_range, k_ra8_ok, k_ra8_xspi_cmd_max_bytes, RA8_CHECK_NULL_PTR, ra8_xspi(), and s_tag.

◆ ra8_xspi_dispatch()

void ra8_xspi_dispatch ( uint8_t instance )

Dispatch an xSPI event – snapshot INTS + fire callback.

Called from the xSPI transfer-complete / error ISR (HUM Ch 49 "xSPI", p 2581) to snapshot INTS and invoke the registered handler. Out-of-range instance and unattached slots are silently dropped so spurious IRQs are harmless.

Parameters

[in] instance xSPI controller instance index (0 or 1).

Precondition: Called from ISR context or a host-test driver.; instance < 2.

Postcondition: Stored callback (if any) has been invoked exactly once.; INTS latch is left for the caller to ack via ra8_xspi_clear_status.

Note: Not thread-safe; pair with NVIC masking.

Since: 0.1.0

Definition at line 494 of file ra8_xspi.c.

References r_xspi_regs_t::INTC, r_xspi_regs_t::INTS, k_ra8_xspi_instance_count, k_ra8_xspi_ints_mask_all, ra8_xspi(), and s_xspi_state.

◆ ra8_xspi_enter_stop()

ra8_err_t ra8_xspi_enter_stop ( uint8_t instance )

nodiscard

Put an xSPI instance into MSTP-gated stop.

Since: 0.1.0

Definition at line 517 of file ra8_xspi.c.

References k_ra8_err_invalid_arg, k_ra8_xspi_instance_count, ra8_mstp_disable(), and s_xspi_mstp_table.

◆ ra8_xspi_exit_stop()

ra8_err_t ra8_xspi_exit_stop ( uint8_t instance )

nodiscard

Exit MSTP-gated stop.

Since: 0.1.0

Definition at line 525 of file ra8_xspi.c.

References k_ra8_err_invalid_arg, k_ra8_xspi_instance_count, ra8_mstp_enable(), and s_xspi_mstp_table.

◆ ra8_xspi_get_status()

ra8_err_t ra8_xspi_get_status	(	uint8_t	instance,
		uint32_t *	out_mask )

nodiscard

Read the xSPI COMSTT busy/error mask.

Since: 0.1.0

Definition at line 464 of file ra8_xspi.c.

References r_xspi_regs_t::COMSTT, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_xspi(), and s_tag.

Referenced by ra8_nsc_xspi_status().

◆ ra8_xspi_init()

ra8_err_t ra8_xspi_init	(	uint8_t	instance,
		ra8_xspi_lio_mode_t	mode )

nodiscard

Initialise an xSPI instance in the chosen link-layer IO mode.

Parameters

[in]	instance	xSPI instance (0 or 1).
[in]	mode	Desired LIOCFG mode (1S/2S/4S/8S/8D).

Returns: k_ra8_ok on success.; k_ra8_err_null_ptr if instance is out of range.

Since: 0.1.0

Definition at line 372 of file ra8_xspi.c.

References internal_xspi_apply_config(), internal_xspi_clock_block_init(), internal_xspi_reset_device(), k_ra8_err_invalid_arg, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_log_info_val, ra8_mstp_enable(), RA8_RETURN_ON_ERROR, ra8_xspi(), s_tag, and s_xspi_mstp_table.

Referenced by demo_run(), flash_journal_setup_or_halt(), internal_reset_phase_1s(), internal_reset_phase_8d(), internal_swap_run_all(), ospirw_ospi_provision(), and selftest_ospi_provision().

◆ ra8_xspi_resume()

ra8_err_t ra8_xspi_resume ( uint8_t instance )

nodiscard

Resume a previously suspended erase / program.

Issues the JEDEC resume opcode (0x7A) via the manual-command engine and polls CMDCMP for completion. Pairs 1:1 with ra8_xspi_suspend().

Parameters

[in] instance xSPI instance (0 or 1).

Returns: k_ra8_ok on success.; k_ra8_err_null_ptr if instance is out of range.; k_ra8_err_hw_timeout if CMDCMP never asserts.

Since: 0.1.0

Definition at line 690 of file ra8_xspi.c.

References k_ra8_spi_flash_op_resume, priv_ra8_xspi_issue_simple_opcode(), RA8_CHECK_NULL_PTR, ra8_xspi(), and s_tag.

◆ ra8_xspi_set_dtr_mode()

ra8_err_t ra8_xspi_set_dtr_mode	(	uint8_t	instance,
		bool	enable )

nodiscard

Enable or disable double-data-rate (DDR / DTR) link mode.

Sets / clears LIOCFGCS[0].DDREN (HUM Ch 44 p 2986). Callers must already have selected an appropriate protocol mode (typically k_ra8_xspi_lio_8d8d8d) via ra8_xspi_init().

Parameters

[in]	instance	xSPI instance (0 or 1).
[in]	enable	true: DDR; false: SDR.

Returns: k_ra8_ok on success.; k_ra8_err_null_ptr if instance is out of range.

Precondition: Driver is open.

Postcondition: LIOCFGCS[0] reflects the requested DDREN state.

Since: 0.1.0

Definition at line 648 of file ra8_xspi.c.

References k_ra8_ok, k_ra8_xspi_liocfgcs_mask_ddren, r_xspi_regs_t::LIOCFGCS, RA8_CHECK_NULL_PTR, ra8_xspi(), and s_tag.

◆ ra8_xspi_set_xip_mode()

ra8_err_t ra8_xspi_set_xip_mode	(	uint8_t	instance,
		bool	enable,
		uint8_t	read_cmd,
		uint8_t	addr_bytes )

nodiscard

Enable or disable memory-mapped (XIP) read mode.

Programs the CMCFGCS[0] read-command slot with the supplied opcode + address-byte width, mirrors FSP r_ospi_b_xip(true/false) by toggling the per-channel CMCTLCH.XIPEN bits, and arms the read-only system-bus mapping via BMCTL0. The matching write command is left at zero because XiP windows are read-only by design. Cite: HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986.

Parameters

[in]	instance	xSPI instance (0 or 1).
[in]	enable	true to enable XIP, false to tear it down.
[in]	read_cmd	JEDEC read opcode (e.g. 0xEB / 0xEE / 0x0B).
[in]	addr_bytes	Address byte count (3 or 4).

Returns: k_ra8_ok on success.; k_ra8_err_null_ptr if instance is out of range.; k_ra8_err_invalid_arg if addr_bytes is neither 3 nor 4.

Precondition: Driver has been initialized via ra8_xspi_init().

Postcondition: On enable: CMCFGCS slot 0 carries (read_cmd, addr_bytes) and CMCTLCH[0/1].XIPEN is set.; On disable: CMCTLCH[0/1].XIPEN is cleared and BMCTL0 == k_ra8_xspi_bmctl0_read_write.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 617 of file ra8_xspi.c.

References r_xspi_regs_t::BMCTL0, r_xspi_regs_t::CMCFGCS, r_xspi_regs_t::CMCTLCH, k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_xspi_addr_bytes_3, k_ra8_xspi_addr_bytes_4, k_ra8_xspi_bmctl0_read_only, k_ra8_xspi_bmctl0_read_write, k_ra8_xspi_cmcfgcs_pos_addr_size, k_ra8_xspi_cmcfgcs_pos_cmd, k_ra8_xspi_cmcfgcs_word_addr, k_ra8_xspi_cmcfgcs_word_read_cmd, k_ra8_xspi_cmctlch_xipen_mask, RA8_CHECK_NULL_PTR, ra8_xspi(), and s_tag.

◆ ra8_xspi_software_reset()

ra8_err_t ra8_xspi_software_reset	(	uint8_t	instance,
		uint8_t	cmd_bytes )

nodiscard

Issue the JEDEC software-reset pair (RSTEN 0x66 + RST 0x99).

Drives the two-step JEDEC reset sequence used by every modern SPI NOR vendor (ISSI IS25LX, Macronix MX25, Winbond W25, Micron MT25Q): first RSTEN (Reset Enable, opcode 0x66) and then RST (Reset, opcode 0x99). After RST returns the device must be left undisturbed for tRPH (~50 us) before the next CS assertion; the caller is responsible for that wait (we use ra8_delay_ms(1)).

The two protocol modes the driver exercises are:

1S-1S-1S (cmd_bytes = 1): single 8-bit opcode on DQ0 only. This is the form the chip will recognise after a power-on reset.
8D-8D-8D (cmd_bytes = 2): two 8-bit opcodes shipped as opcode | (~opcode << 8) on all eight DQ lines on both clock edges. This is the form the chip will recognise if a previous boot left it in OPI mode and the SoC was warm-reset (POR is the only thing that clears the volatile-config-register choice of protocol on IS25LX512M).

To recover from an unknown protocol state at cold-or-warm boot the board bring-up should call this function once in each protocol mode: one of the two will be the no-op (the chip ignores the wrong-shape opcode) and the other will actually reset the chip back to 1S-1S-1S.

Cite: IS25LX512M datasheet Ch 8.20 "Reset Enable (RSTEN)" and Ch 8.21 "Reset (RST)" (p 39); HUM Ch 44 p 2986 for the manual- command engine fields used to send the opcodes.

Parameters

[in]	instance	xSPI instance (0 or 1).
[in]	cmd_bytes	Number of opcode bytes to ship per command: 1 for 1S-1S-1S SPI, 2 for 8D-8D-8D OPI.

Returns: k_ra8_ok on success.; k_ra8_err_null_ptr if instance is out of range.; k_ra8_err_invalid_arg if cmd_bytes is neither 1 nor 2.; k_ra8_err_hw_timeout if the controller never raises CMDCMP for either RSTEN or RST.

Precondition: Driver has been initialized via ra8_xspi_init() in a protocol mode that matches cmd_bytes.; Caller will leave the chip undisturbed for tRPH (>=50 us) after this returns before issuing the next command.

Postcondition: The flash device, if it recognised the opcode pair, has reverted its volatile-config registers to power-on defaults and is back in 1S-1S-1S extended SPI.

Note: Not thread-safe. Intended to be called only during bring-up.

Since: 0.1.0

Definition at line 756 of file ra8_xspi.c.

References internal_issue_reset_opcode(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_spi_flash_op_reset_dev, k_ra8_spi_flash_op_reset_en, k_ra8_xspi_reset_cmd_bytes_1s, k_ra8_xspi_reset_cmd_bytes_8d, RA8_CHECK_NULL_PTR, ra8_xspi(), and s_tag.

Referenced by internal_reset_phase_1s(), and internal_reset_phase_8d().

◆ ra8_xspi_suspend()

ra8_err_t ra8_xspi_suspend ( uint8_t instance )

nodiscard

Suspend a long-running flash erase / program operation.

Issues the JEDEC suspend opcode (0x75) via the manual-command engine, polls CMDCMP, and lets the SPI device pause its in-flight erase or program so that interactive reads can be served. Cite: HUM Ch 44 p 2986.

Parameters

[in] instance xSPI instance (0 or 1).

Returns: k_ra8_ok on success.; k_ra8_err_null_ptr if instance is out of range.; k_ra8_err_hw_timeout if CMDCMP never asserts.

Precondition: Driver is open.

Postcondition: Flash device is in suspended state; ra8_xspi_resume() is required before further write traffic.

Since: 0.1.0

Definition at line 683 of file ra8_xspi.c.

References k_ra8_spi_flash_op_suspend, priv_ra8_xspi_issue_simple_opcode(), RA8_CHECK_NULL_PTR, ra8_xspi(), and s_tag.

◆ ra8_xspi_xip_enter()

ra8_err_t ra8_xspi_xip_enter	(	uint8_t	instance,
		uint8_t	enter_code,
		uint8_t	exit_code )

nodiscard

Enable XIP (execute-in-place) memory-mapped read mode.

Programs CMCTLCH[0/1] with the supplied XiP enter/exit codes, sets BMCTL0 = 0x55 to map the target window read-only on the system bus, and arms CMCTLCH.XIPEN. Tracks FSP R_OSPI_B_XipEnter / r_ospi_b_xip(true). Cite: HUM Ch 44 "Octal Serial Peripheral Interface (OSPI)" p 2986.

Parameters

[in]	instance	xSPI instance (0 or 1).
[in]	enter_code	Vendor-specific XIP enter byte (e.g. 0xA5).
[in]	exit_code	Vendor-specific XIP exit byte (e.g. 0x5A).

Returns: k_ra8_ok on success.; k_ra8_err_null_ptr if instance is out of range.

Precondition: Driver has been initialized via ra8_xspi_init().; A read command set has been programmed in CMCFGCS[n].

Postcondition: BMCTL0 reads as k_ra8_xspi_bmctl0_read_only.; CMCTLCH[0/1].XIPEN is set.

Note: Not thread-safe; call from a single bring-up context.

Since: 0.1.0

Definition at line 533 of file ra8_xspi.c.

References r_xspi_regs_t::BMCTL0, r_xspi_regs_t::CMCTLCH, k_ra8_ok, k_ra8_xspi_bmctl0_read_only, k_ra8_xspi_cmctlch_xipen_mask, k_ra8_xspi_cmctlch_xipencode_pos, k_ra8_xspi_cmctlch_xipexcode_pos, RA8_CHECK_NULL_PTR, ra8_xspi(), and s_tag.

◆ ra8_xspi_xip_exit()

ra8_err_t ra8_xspi_xip_exit ( uint8_t instance )

nodiscard

Disable XIP mode and restore command-only access.

Clears CMCTLCH[0/1].XIPEN and zeroes out the XIP enter/exit codes, then resets BMCTL0 so further direct-command transfers are not blocked by an active memory-mapped path. Tracks FSP R_OSPI_B_XipExit / r_ospi_b_xip(false).

Parameters

[in] instance xSPI instance (0 or 1).

Returns: k_ra8_ok on success.; k_ra8_err_null_ptr if instance is out of range.

Precondition: Driver is open and previously entered XIP via ra8_xspi_xip_enter().

Postcondition: CMCTLCH[0/1] == 0 and XIPEN is cleared.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 555 of file ra8_xspi.c.

References r_xspi_regs_t::BMCTL0, r_xspi_regs_t::CMCTLCH, k_ra8_ok, k_ra8_xspi_bmctl0_read_write, RA8_CHECK_NULL_PTR, ra8_xspi(), and s_tag.

Variable Documentation

◆ s_tag

const char* s_tag = "XSPI"

static

Logging tag for this driver.

Definition at line 72 of file ra8_xspi.c.

◆ s_xspi_mstp_table

const ra8_mstp_t s_xspi_mstp_table[]

static

Initial value:

                                          = {
  k_ra8_mstp_ospi0,
  k_ra8_mstp_ospi1,
}

Instance-index -> MSTP id lookup.

OSPI0 and OSPI1 each have their own MSTPB bit (16/17) per HUM Ch 11.2.7 p 444. Each bit also covers the matching DOTF channel.

Definition at line 128 of file ra8_xspi.c.

Referenced by ra8_xspi_deinit(), ra8_xspi_enter_stop(), ra8_xspi_exit_stop(), and ra8_xspi_init().

◆ s_xspi_state

ra8_xspi_state_t s_xspi_state[k_ra8_xspi_instance_count]

static

Per-instance callback state (s_ prefix for file-static).

Definition at line 447 of file ra8_xspi.c.

Referenced by internal_swap_run_all(), ra8_xspi_attach_handler(), ra8_xspi_deinit(), and ra8_xspi_dispatch().

Data Structures

Enumerations

Functions

Variables

Detailed Description

CDBUF convention used by this driver

Enumeration Type Documentation

◆ ra8_xspi_addr_bytes_t

◆ ra8_xspi_calib_spin_t

◆ ra8_xspi_chip_select_t

◆ ra8_xspi_cmd_limits_t

◆ ra8_xspi_jedec_extra_t

◆ ra8_xspi_reset_cmd_bytes_t

◆ ra8_xspi_reset_delay_t

Function Documentation

◆ internal_issue_reset_opcode()

◆ internal_wait_octacksrdy()

◆ internal_xspi_apply_config()

◆ internal_xspi_clock_block_init()

◆ internal_xspi_reset_device()

◆ internal_xspi_reset_spin()

◆ ra8_xspi_attach_handler()

◆ ra8_xspi_calibrate_dqs()

◆ ra8_xspi_clear_status()

◆ ra8_xspi_deinit()

◆ ra8_xspi_direct_command()

◆ ra8_xspi_dispatch()

◆ ra8_xspi_enter_stop()

◆ ra8_xspi_exit_stop()

◆ ra8_xspi_get_status()

◆ ra8_xspi_init()

◆ ra8_xspi_resume()

◆ ra8_xspi_set_dtr_mode()

◆ ra8_xspi_set_xip_mode()

◆ ra8_xspi_software_reset()

◆ ra8_xspi_suspend()

◆ ra8_xspi_xip_enter()

◆ ra8_xspi_xip_exit()

Variable Documentation

◆ s_tag

◆ s_xspi_mstp_table

◆ s_xspi_state