storage.h File Reference

Two-bank durable blob storage over an explicit narrow port. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Go to the source code of this file.

Data Structures
struct	nx_storage_port_t
	Synchronous settled persistent Flash port. More...
struct	nx_storage_t
	Instance metadata with caller-sized workspace. More...

Macros
#define	NX_STORAGE_HEADER_SIZE   32u

Enumerations
enum	nx_storage_status_t {   NX_STORAGE_OK = 0 , NX_STORAGE_INVALID , NX_STORAGE_IO , NX_STORAGE_CORRUPT ,   NX_STORAGE_NO_SPACE , NX_STORAGE_NOT_FOUND , NX_STORAGE_UNSUPPORTED }
	Storage errors expose retry/reopen/recovery decisions. More...

Functions
nx_storage_status_t	nx_storage_open (nx_storage_t *storage, const nx_storage_port_t *port, size_t offset, size_t bank_size, void *workspace, size_t workspace_bytes)
	Open/recover two externally supplied uniform erase banks.
nx_storage_status_t	nx_storage_load (nx_storage_t *storage, void *output, size_t *size)
	Load and validate the latest committed whole blob.
nx_storage_status_t	nx_storage_save (nx_storage_t *storage, const void *data, size_t size)
	Commit a complete blob to the inactive bank.
size_t	nx_storage_capacity (const nx_storage_t *storage)
	Query usable blob capacity without touching hardware.

Detailed Description

Two-bank durable blob storage over an explicit narrow port.

Author

Nexus Team

Definition in file storage.h.

Macro Definition Documentation

NX_STORAGE_HEADER_SIZE

#define NX_STORAGE_HEADER_SIZE   32u

Definition at line 49 of file storage.h.

Enumeration Type Documentation

nx_storage_status_t

enum nx_storage_status_t

Storage errors expose retry/reopen/recovery decisions.

Enumerator
NX_STORAGE_OK
NX_STORAGE_INVALID
NX_STORAGE_IO
NX_STORAGE_CORRUPT
NX_STORAGE_NO_SPACE
NX_STORAGE_NOT_FOUND
NX_STORAGE_UNSUPPORTED

Definition at line 17 of file storage.h.

Function Documentation

nx_storage_capacity()

size_t nx_storage_capacity

(

const nx_storage_t *

storage

)

Query usable blob capacity without touching hardware.

Parameters

[in]

storage

Geometry-established instance, or NULL

Returns

Payload bytes per bank, or zero for invalid geometry

nx_storage_load()

nx_storage_status_t nx_storage_load	(	nx_storage_t *	storage,
		void *	output,
		size_t *	size )

Load and validate the latest committed whole blob.

Parameters

[in,out]	storage	Open instance, exclusively owned for this call
[out]	output	Destination; NULL requests only required size
[in,out]	size	Input capacity, output payload/required bytes

Returns

OK, NOT_FOUND, NO_SPACE, CORRUPT or IO/INVALID

Note

Output bytes valid only on OK; failure may partially write output. No destination pointer is retained after returning.

nx_storage_open()

nx_storage_status_t nx_storage_open	(	nx_storage_t *	storage,
		const nx_storage_port_t *	port,
		size_t	offset,
		size_t	bank_size,
		void *	workspace,
		size_t	workspace_bytes )

Open/recover two externally supplied uniform erase banks.

Parameters

[out]	storage	Unused or quiesced instance, no concurrent calls
[in]	port	Persistent settled port, may be storage's existing port
[in]	offset	Erase-aligned start within port region
[in]	bank_size	Each bank's erase-aligned byte size
[in]	workspace	Caller buffer, disjoint from instance/payload
[in]	workspace_bytes	At least max(32, port.program_size)

Returns

OK for recovered/empty store, CORRUPT for ambiguous or only invalid committed generations, IO/INVALID for port/geometry failures

Note

Task-only bounded scan over both bank payloads. Workspace remains borrowed by the instance through every subsequent load/save call.

nx_storage_save()

nx_storage_status_t nx_storage_save	(	nx_storage_t *	storage,
		const void *	data,
		size_t	size )

Commit a complete blob to the inactive bank.

Parameters

[in,out]	storage	Open exclusively owned instance
[in]	data	Payload disjoint from workspace, borrowed during call
[in]	size	Payload bytes; zero permits NULL

Returns

OK, NO_SPACE, INVALID or underlying port error

Note

Marker is programmed last after sync. Failed mutation keeps the previous bank and requires reopen; ambiguous marker failure can mean the new blob committed. Product owns migration/authentication/recovery policy.