ra8_io block-device backend over OSPI NOR flash via ra8_xspi. More...

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

Include dependency graph for ra8_io_blockdev_xspi.h:

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

Data Structures
struct	ra8_io_blockdev_xspi_state_t
	Caller-owned private state for an OSPI NOR block device. More...

Functions
ra8_err_t	ra8_io_blockdev_xspi_init (ra8_io_blockdev_t bd, ra8_io_blockdev_xspi_state_t state, uint8_t instance, uint32_t base_off, uint32_t block_count, bool read_only)
	Bind an OSPI NOR block-device backend into a caller-owned handle.

Detailed Description

ra8_io block-device backend over OSPI NOR flash via ra8_xspi.

Tag: [Ring 4 / PAL] {World: NS}

The xSPI backend exposes the 64 MiB external Octo-SPI NOR flash as an array of 512-byte logical blocks on top of the ra8_xspi HAL driver. NOR semantics are surfaced through the capability query: a program only clears bits (1 -> 0), and a 4 KiB sector must be erased back to all-ones before it can be re-programmed. So an arbitrary block write performs a whole-sector read-modify-write internally – read the 4 KiB sector, overlay the touched 512-byte blocks, erase the sector, and program the 4 KiB back. Reads and erases are bounds-checked; erases must be sector-aligned (multiples of eight logical blocks). The backend touches no MMIO directly; every flash access goes through ra8_xspi_flash_read/_program/_erase_sector, which carry the Hardware User's Manual citations.

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

Since: 0.1.0

Definition in file ra8_io_blockdev_xspi.h.

Function Documentation

◆ ra8_io_blockdev_xspi_init()

ra8_err_t ra8_io_blockdev_xspi_init	(	ra8_io_blockdev_t *	bd,
		ra8_io_blockdev_xspi_state_t *	state,
		uint8_t	instance,
		uint32_t	base_off,
		uint32_t	block_count,
		bool	read_only )

nodiscard

Bind an OSPI NOR block-device backend into a caller-owned handle.

Records instance/base_off/block_count in state, marks it read-only per read_only, and points bd at the xSPI vtable with state as its context. No allocation occurs; the caller owns both bd and state. The window must be whole-sector aligned: base_off a multiple of 4096 and block_count a non-zero multiple of 8 (4096 / 512). The application must have brought up the controller with ra8_xspi_init(instance, mode) before any call is dispatched through the bound device.

Parameters

[out]	bd	Handle to bind (zero-initialised by the caller).
[out]	state	Caller-owned backend state to populate.
[in]	instance	xSPI HAL instance index (0 or 1).
[in]	base_off	Flash byte offset of logical block 0 (% 4096 == 0).
[in]	block_count	Number of 512-byte logical blocks (non-zero, % 8 == 0).
[in]	read_only	true to reject writes and erases on this device.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Backend bound; bd is usable.
k_ra8_err_null_ptr	bd or state was NULL.
k_ra8_err_invalid_arg	instance >= 2, base_off not sector-aligned, or block_count not a non-zero multiple of 8.

Precondition: ra8_xspi_init(instance, mode) has already succeeded.; bd and state out-live every call made through the device.

Postcondition: On success bd dispatches to the xSPI backend over the flash window.; On any non-ok return bd and state are left unbound/untouched.

Note: Not thread-safe with respect to the same device.

Since: 0.1.0

Definition at line 501 of file ra8_io_blockdev_xspi.c.

References ra8_io_blockdev_xspi_state_t::base_off, ra8_io_blockdev_xspi_state_t::block_count, ra8_io_blockdev_t::ctx, ra8_io_blockdev_t::iface, ra8_io_blockdev_xspi_state_t::instance, internal_xspi_check_geom(), k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_io_blockdev_xspi_state_t::read_only, s_tag, and s_xspi_iface.

Referenced by demo_run(), and internal_swap_run_all().

Data Structures

Functions

Detailed Description

Function Documentation

◆ ra8_io_blockdev_xspi_init()