RAM-backed standalone-LevelX NOR driver – implementation. More...

#include "lx_nor_ram.h"
#include "lx_api.h"
#include "ra8_attributes.h"

Include dependency graph for lx_nor_ram.c:

Enumerations
enum	lx_nor_ram_const_t : uint32_t { k_lx_nor_ram_total_blocks = 64U , k_lx_nor_ram_words_per_block = 512U , k_lx_nor_ram_total_words = 64U * 512U , k_lx_nor_ram_erased = 0xFFFFFFFFU }
	Geometry + sentinel constants for the RAM NOR driver. More...

Functions
static UINT	internal_ram_read (ULONG flash_address, ULONG destination, ULONG words)
	Read `words` ULONGs from the backing pointer into `destination`.
static UINT	internal_ram_write (ULONG flash_address, ULONG source, ULONG words)
	Write `words` ULONGs from `source` to the backing pointer.
static UINT	internal_ram_block_erase (ULONG block, ULONG erase_count)
	Erase one block to the LevelX erased pattern.
static UINT	internal_ram_block_erased_verify (ULONG block)
	Verify one block is fully erased.
unsigned int	lx_nor_ram_init (struct LX_NOR_FLASH_STRUCT *nor_flash)
	LevelX NOR driver-initialise callback over the static SRAM backing.
void	lx_nor_ram_wipe (void)
	Erase the entire SRAM backing to the LevelX "erased" pattern.

Variables
static ULONG	s_ram_backing [k_lx_nor_ram_total_words]
	The fake NOR media (persists across open/close within one boot).
static ULONG	s_ram_sector_buf [LX_NOR_SECTOR_SIZE]
	LevelX per-open sector scratch (one logical sector wide).

Detailed Description

RAM-backed standalone-LevelX NOR driver – implementation.

Tag: [Ring 6 / APP] {World: S}

Implements a minimal LevelX NOR driver whose media is a static ULONG array. The read/write callbacks dereference the ULONG* LevelX hands them directly (LevelX derives it from lx_nor_flash_base_address, which points at the backing), mirroring the vendored lx_nor_flash_simulator.c but first-party and heap-free. No peripheral register is touched, so the emulator and silicon run identical code.

ULONG width note: under LX_STANDALONE_ENABLE, ULONG is unsigned long (4 bytes on the arm-none-eabi ILP32 target, 8 bytes on the LP64 test host). The erased pattern is written as (ULONG)0xFFFFFFFF (== LevelX's LX_ALL_ONES), matching how LevelX compares words against 0xFFFFFFFF.

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

Definition in file lx_nor_ram.c.

Enumeration Type Documentation

◆ lx_nor_ram_const_t

enum lx_nor_ram_const_t : uint32_t

Geometry + sentinel constants for the RAM NOR driver.

64 blocks * 512 words/block is an ample logical-sector space for the demo (well over a hundred usable 512-byte sectors on both the 4-byte target and 8-byte host) while keeping the SRAM backing modest (128 KiB on the target).

Since: 0.1.0

Enumerator
k_lx_nor_ram_total_blocks	NOR blocks.
k_lx_nor_ram_words_per_block	ULONG words/block.
k_lx_nor_ram_total_words	Backing word count.
k_lx_nor_ram_erased	LevelX erased word.

Definition at line 39 of file lx_nor_ram.c.

Function Documentation

◆ internal_ram_block_erase()

UINT internal_ram_block_erase	(	ULONG	block,
		ULONG	erase_count )

static

Erase one block to the LevelX erased pattern.

Computes the selected block's base word and overwrites exactly one geometry-defined block with the erased value.

Parameters

[in]	block	Block index.
[in]	erase_count	LevelX erase counter (unused).

Returns: LX_SUCCESS, or LX_ERROR when block is out of range.

Return values

0	Block erased.
1	`block` is out of range.

Precondition: block indexes a real block.; The backing is static storage.

Postcondition: Every word of the block reads as the erased pattern.; No other block is touched.

Note: Not thread-safe; the store serialises access.

Since: 0.1.0

Definition at line 146 of file lx_nor_ram.c.

References k_lx_nor_ram_erased, k_lx_nor_ram_total_blocks, k_lx_nor_ram_words_per_block, RA8_INTERNAL, and s_ram_backing.

Referenced by lx_nor_ram_init().

◆ internal_ram_block_erased_verify()

UINT internal_ram_block_erased_verify ( ULONG block )

static

Verify one block is fully erased.

Bounds-checks the block index, then scans every word in the block for the LevelX erased pattern without modifying the backing.

Parameters

[in] block Block index.

Returns: LX_SUCCESS when erased, else LX_ERROR.

Return values

0	Every word matches the erased pattern.
1	`block` is out of range, or a word is not erased.

Precondition: block indexes a real block.; The backing is static storage.

Postcondition: The backing is unmodified.; A success result means the block may be programmed.

Note: Not thread-safe; the store serialises access.

Since: 0.1.0

Definition at line 174 of file lx_nor_ram.c.

References k_lx_nor_ram_erased, k_lx_nor_ram_total_blocks, k_lx_nor_ram_words_per_block, RA8_INTERNAL, and s_ram_backing.

Referenced by lx_nor_ram_init().

◆ internal_ram_read()

UINT internal_ram_read	(	ULONG *	flash_address,
		ULONG *	destination,
		ULONG	words )

static

Read words ULONGs from the backing pointer into destination.

Copies the requested contiguous range without allocating storage or changing the emulated NOR contents.

Parameters

[in]	flash_address	Source pointer into the backing (LevelX cookie).
[out]	destination	Destination buffer of `words` ULONGs.
[in]	words	Word count.

Returns: LX_SUCCESS, or LX_ERROR on a NULL argument.

Return values

0	Words copied.
1	A pointer argument was NULL.

Precondition: flash_address lies within the backing.; destination covers words ULONGs.

Postcondition: destination holds the copied words on success.; The backing is unmodified.

Note: Not thread-safe; the store serialises access.

Since: 0.1.0

Definition at line 82 of file lx_nor_ram.c.

References RA8_INTERNAL.

◆ internal_ram_write()

UINT internal_ram_write	(	ULONG *	flash_address,
		ULONG *	source,
		ULONG	words )

static

Write words ULONGs from source to the backing pointer.

Programs the requested contiguous range directly in the RAM-backed NOR model without allocating storage or touching other words.

Parameters

[in]	flash_address	Destination pointer into the backing (LevelX cookie).
[in]	source	Source buffer of `words` ULONGs.
[in]	words	Word count.

Returns: LX_SUCCESS, or LX_ERROR on a NULL argument.

Return values

0	Words written.
1	A pointer argument was NULL.

Precondition: flash_address lies within the backing.; source covers words ULONGs.

Postcondition: The targeted backing words hold source on success.; No word outside the range is changed.

Note: Not thread-safe; the store serialises access.

Since: 0.1.0

Definition at line 116 of file lx_nor_ram.c.

References RA8_INTERNAL.

◆ lx_nor_ram_init()

unsigned int lx_nor_ram_init ( struct LX_NOR_FLASH_STRUCT * nor_flash )

LevelX NOR driver-initialise callback over the static SRAM backing.

Signature-compatible with ra8_cache_store_nor_init_fn: programs the control block's geometry, the read/write/erase/verify callbacks, and the LevelX per-open sector buffer against the static backing array. Passed straight to lx_nor_flash_open() / lx_nor_flash_format().

Parameters

[in,out] nor_flash LevelX control block to populate.

Returns: 0 (LX_SUCCESS) on success; non-zero on a NULL argument.

Return values

0	Control block programmed.
1	`nor_flash` was NULL.

Precondition: nor_flash points at caller-owned LevelX control-block storage.; The static backing array is available (always; static storage).

Postcondition: On success all four driver callbacks and the geometry are set.; The backing SRAM is left as-is (open uses it; format erases it).

Note: Not thread-safe; the store serialises access.

Since: 0.1.0

Definition at line 188 of file lx_nor_ram.c.

References internal_ram_block_erase(), internal_ram_block_erased_verify(), internal_ram_read(), internal_ram_write(), k_lx_nor_ram_total_blocks, k_lx_nor_ram_words_per_block, s_ram_backing, and s_ram_sector_buf.

Referenced by internal_rcs_build_cfg().

◆ lx_nor_ram_wipe()

void lx_nor_ram_wipe ( void )

Erase the entire SRAM backing to the LevelX "erased" pattern.

Resets the fake NOR media to a blank (unformatted) device. Firmware never needs this – reset zeroes the BSS backing and the first mount formats it – but the host test calls it between independent scenarios that share the one static backing.

Returns: Nothing.

Precondition: The backing array is static storage (always available).; No LevelX operation is mid-flight against the backing.

Postcondition: Every backing word reads as the erased pattern.; A subsequent open sees a blank (unformatted) device.

Note: Not thread-safe; the store serialises access.

Since: 0.1.0

Definition at line 204 of file lx_nor_ram.c.

References k_lx_nor_ram_erased, k_lx_nor_ram_total_words, and s_ram_backing.

Variable Documentation

◆ s_ram_backing

ULONG s_ram_backing[k_lx_nor_ram_total_words]

static

The fake NOR media (persists across open/close within one boot).

Warning: Written only through the driver callbacks and lx_nor_ram_wipe.

Since: 0.1.0

Definition at line 52 of file lx_nor_ram.c.

Referenced by internal_ram_block_erase(), internal_ram_block_erased_verify(), lx_nor_ram_init(), and lx_nor_ram_wipe().

◆ s_ram_sector_buf

ULONG s_ram_sector_buf[LX_NOR_SECTOR_SIZE]

static

LevelX per-open sector scratch (one logical sector wide).

Warning: Owned by LevelX between open and close; not for other use.

Since: 0.1.0

Definition at line 60 of file lx_nor_ram.c.

Referenced by lx_nor_ram_init().

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ lx_nor_ram_const_t

Function Documentation

◆ internal_ram_block_erase()

◆ internal_ram_block_erased_verify()

◆ internal_ram_read()

◆ internal_ram_write()

◆ lx_nor_ram_init()

◆ lx_nor_ram_wipe()

Variable Documentation

◆ s_ram_backing

◆ s_ram_sector_buf