xSPI / Octo-SPI driver (flash read/program/erase + ID/status) More...

#include <stdint.h>
#include "ra8_err.h"
#include "ra8_ospi_regs.h"

Include dependency graph for ra8_xspi.h:

This graph shows which files directly or indirectly include this file:

Typedefs
typedef void(*	ra8_xspi_event_fn_t) (void *ctx, uint32_t status_mask)
	xSPI event callback.

Functions
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_flash_read (uint8_t instance, uint32_t flash_addr, uint8_t *buf, uint32_t len)
	Read len bytes from external flash into buf.
ra8_err_t	ra8_xspi_flash_program (uint8_t instance, uint32_t flash_addr, const uint8_t *data, uint32_t len)
	Program (write) len bytes at flash_addr.
ra8_err_t	ra8_xspi_flash_erase_sector (uint8_t instance, uint32_t flash_addr)
	Erase the 4 KiB sector containing flash_addr.
ra8_err_t	ra8_xspi_flash_read_status (uint8_t instance, uint8_t *out_status)
	Read the flash Status Register (opcode 0x05).
ra8_err_t	ra8_xspi_flash_read_id (uint8_t instance, uint32_t *out_id)
	Read the JEDEC ID (opcode 0x9F), returning 24 bits in a uint32_t.
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.
ra8_err_t	ra8_xspi_software_reset (uint8_t instance, uint8_t cmd_bytes)
	Issue the JEDEC software-reset pair (RSTEN 0x66 + RST 0x99).

Detailed Description

xSPI / Octo-SPI driver (flash read/program/erase + ID/status)

Driver surface for the RA8D2 xSPI controller in direct-command mode. Supports initialisation at a given link-layer IO width, raw command-buffer writes, and a minimal set of SPI NOR flash operations (read, page program, sector erase, status/ID read).

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

Definition in file ra8_xspi.h.

Typedef Documentation

◆ ra8_xspi_event_fn_t

typedef void(* ra8_xspi_event_fn_t) (void *ctx, uint32_t status_mask)

xSPI event callback.

Definition at line 154 of file ra8_xspi.h.

Function Documentation

◆ 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_flash_erase_sector()

ra8_err_t ra8_xspi_flash_erase_sector	(	uint8_t	instance,
		uint32_t	flash_addr )

nodiscard

Erase the 4 KiB sector containing flash_addr.

Parameters

[in]	instance	xSPI instance.
[in]	flash_addr	Address within the target sector (3-byte addressable).

Returns: k_ra8_ok on success.; k_ra8_err_null_ptr if instance is out of range.; k_ra8_err_invalid_arg if flash_addr exceeds the 2^24-byte window a 3-byte JEDEC address can reach.; k_ra8_err_hw_timeout if the WREN / SE command never retires.; k_ra8_err_timeout if WIP does not clear.

Since: 0.1.0

Definition at line 724 of file ra8_xspi_flash.c.

References internal_build_chunk_header(), internal_flash_range_check(), internal_poll_wip_clear(), k_ra8_ok, k_ra8_spi_flash_op_erase_sector, k_ra8_spi_flash_op_write_enable, k_ra8_xspi_cdt_trtype_write, priv_ra8_xspi_issue_simple_opcode(), priv_ra8_xspi_kick_command(), RA8_CHECK_NULL_PTR, ra8_xspi(), and s_tag.

Referenced by flash_journal_round_trip(), internal_nor_block_erase(), internal_write_one_sector(), internal_xspi_erase(), ospirw_ospi_provision(), and selftest_ospi_write_pattern().

◆ ra8_xspi_flash_program()

ra8_err_t ra8_xspi_flash_program	(	uint8_t	instance,
		uint32_t	flash_addr,
		const uint8_t *	data,
		uint32_t	len )

nodiscard

Program (write) len bytes at flash_addr.

Sequence per chunk is: Write Enable -> Page Program -> Poll WIP, with chunks clamped to the 8-byte manual-command slot and to 256-byte NOR page boundaries. Every build drives the identical xSPI register sequence; host unit tests run it against the register-level NOR model in tests/mocks/src/ra8_fake_xspi_flash.c.

Parameters

[in]	instance	xSPI instance.
[in]	flash_addr	Flash offset (3-byte addressable).
[in]	data	Source buffer.
[in]	len	Number of bytes to program.

Returns: k_ra8_ok on success.; k_ra8_err_null_ptr if data or instance is invalid.; k_ra8_err_invalid_arg if len == 0, len > k_ra8_xspi_max_xfer, or [flash_addr, flash_addr + len) exceeds the 2^24-byte window a 3-byte JEDEC address can reach.; k_ra8_err_hw_timeout if a WREN / PP command never retires.; k_ra8_err_timeout if the WIP bit never clears.

Since: 0.1.0

Definition at line 685 of file ra8_xspi_flash.c.

References internal_flash_program_chunk(), internal_flash_range_check(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_xspi_cdt_max_data_bytes, k_ra8_xspi_max_xfer, k_ra8_xspi_page_len, RA8_CHECK_NULL_PTR, ra8_xspi(), and s_tag.

Referenced by flash_journal_round_trip(), internal_nor_write(), internal_xspi_program_chunked(), ospirw_msc_write(), and selftest_ospi_write_pattern().

◆ ra8_xspi_flash_read()

ra8_err_t ra8_xspi_flash_read	(	uint8_t	instance,
		uint32_t	flash_addr,
		uint8_t *	buf,
		uint32_t	len )

nodiscard

Read len bytes from external flash into buf.

Builds a standard 0x03 (1S-1S-1S) read command sequence in 8-byte manual-command chunks, kicks each via CDCTL0.TRREQ, polls INTS.CMDCMP for completion, and copies the CDD0/CDD1 response words into buf. Host unit tests exercise the identical sequence against the register-level NOR model in tests/mocks/src/ra8_fake_xspi_flash.c.

Parameters

[in]	instance	xSPI instance (0 or 1).
[in]	flash_addr	Flash offset to read from (3-byte addressable).
[out]	buf	Destination buffer. Must not be NULL.
[in]	len	Number of bytes to read.

Returns: k_ra8_ok on success.; k_ra8_err_null_ptr if buf is NULL or instance out of range.; k_ra8_err_invalid_arg if len == 0, len > k_ra8_xspi_max_xfer, or [flash_addr, flash_addr + len) exceeds the 2^24-byte window a 3-byte JEDEC address can reach.; k_ra8_err_hw_timeout if a read command never retires (CMDCMP).

Since: 0.1.0

Definition at line 431 of file ra8_xspi_flash.c.

References internal_flash_range_check(), internal_flash_read_chunk(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_xspi_cdt_max_data_bytes, k_ra8_xspi_max_xfer, RA8_CHECK_NULL_PTR, ra8_xspi(), and s_tag.

Referenced by flash_journal_round_trip(), internal_nor_block_erased_verify(), internal_nor_read(), internal_xspi_read_chunked(), ospirw_msc_read(), ra8_nsc_xspi_read(), and selftest_fat_fill_sector().

◆ ra8_xspi_flash_read_id()

ra8_err_t ra8_xspi_flash_read_id	(	uint8_t	instance,
		uint32_t *	out_id )

nodiscard

Read the JEDEC ID (opcode 0x9F), returning 24 bits in a uint32_t.

The returned word packs the three JEDEC bytes as: (manufacturer << 16) | (mem_type << 8) | capacity. Compatible with Macronix MX25, Winbond W25, Renesas AT25, and ISSI IS25 parts.

Parameters

[in]	instance	xSPI instance.
[out]	out_id	24-bit JEDEC ID in a 32-bit word.

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

Since: 0.1.0

Definition at line 773 of file ra8_xspi_flash.c.

References r_xspi_regs_t::CDBUF, internal_issue_read_opcode(), k_ra8_ok, k_ra8_spi_flash_op_read_id, k_ra8_xspi_cdbuf_idx_data0, k_ra8_xspi_resp_bytes_jedec, k_xspi_byte_mask, RA8_CHECK_NULL_PTR, ra8_xspi(), and s_tag.

Referenced by flash_journal_setup_or_halt(), internal_probe_rdid(), ospirw_ospi_provision(), and selftest_ospi_provision().

◆ ra8_xspi_flash_read_status()

ra8_err_t ra8_xspi_flash_read_status	(	uint8_t	instance,
		uint8_t *	out_status )

nodiscard

Read the flash Status Register (opcode 0x05).

Parameters

[in]	instance	xSPI instance.
[out]	out_status	Status-register value (WIP is bit 0).

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

Since: 0.1.0

Definition at line 753 of file ra8_xspi_flash.c.

References r_xspi_regs_t::CDBUF, internal_issue_read_opcode(), k_ra8_ok, k_ra8_spi_flash_op_read_status, k_ra8_xspi_cdbuf_idx_data0, k_ra8_xspi_resp_bytes_status, k_xspi_byte_mask, RA8_CHECK_NULL_PTR, ra8_xspi(), and s_tag.

Referenced by internal_poll_wip_clear().

◆ 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.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ ra8_xspi_event_fn_t

Function Documentation

◆ 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_flash_erase_sector()

◆ ra8_xspi_flash_program()

◆ ra8_xspi_flash_read()

◆ ra8_xspi_flash_read_id()

◆ ra8_xspi_flash_read_status()

◆ 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()