Non-Volatile Memory

Persistent storage with mandatory integrity checking on read (ADR-001). More...

Files
file	src/oal/nvm/sapi_nvm.c
	NVM service: validates parameters, then dispatches to the backend registered via sapi_nvm_register_backend() (ADR-005).

Data Structures
struct	sapi_nvm_config_t
	Configuration for sapi_nvm_open(). More...

Typedefs
typedef struct sapi_nvm_impl_s *	sapi_nvm_handle_t
	Opaque handle to an open NVM region, returned by sapi_nvm_open().

Functions
	SAFEAPI_DECLARE_STORAGE (sapi_nvm_storage_t, 64U)
	Caller-owned, fixed-size storage backing one sapi_nvm_handle_t.
sapi_status_t	sapi_nvm_open (sapi_nvm_storage_t *storage, const sapi_nvm_config_t *config, sapi_nvm_handle_t *out_handle)
	Opens (creating if necessary) a named NVM region.
sapi_status_t	sapi_nvm_read (sapi_nvm_handle_t handle, size_t offset, void *out_buffer, size_t buffer_size)
	Reads and integrity-checks data from an NVM region.
sapi_status_t	sapi_nvm_write (sapi_nvm_handle_t handle, size_t offset, const void *buffer, size_t buffer_size)
	Writes data and its integrity metadata to an NVM region.
sapi_status_t	sapi_nvm_sync (sapi_nvm_handle_t handle)
	Forces any buffered writes to durable storage.
sapi_status_t	sapi_nvm_close (sapi_nvm_handle_t handle)
	Closes an NVM region handle.

Detailed Description

Persistent storage with mandatory integrity checking on read (ADR-001).

Typedef Documentation

sapi_nvm_handle_t

typedef struct sapi_nvm_impl_s* sapi_nvm_handle_t

Opaque handle to an open NVM region, returned by sapi_nvm_open().

Definition at line 30 of file sapi_nvm.h.

Function Documentation

sapi_nvm_open()

sapi_status_t sapi_nvm_open	(	sapi_nvm_storage_t *	storage,
		const sapi_nvm_config_t *	config,
		sapi_nvm_handle_t *	out_handle )

Opens (creating if necessary) a named NVM region.

Parameters

storage	Caller-owned storage for the handle's state. Must not be NULL.
config	Region configuration. Must not be NULL; config->region_name must not be NULL and config->region_size must be > 0.
out_handle	Receives the opened region's handle. Must not be NULL.

Returns

SAPI_STATUS_OK; SAPI_STATUS_INVALID_PARAM for a bad argument; SAPI_STATUS_NOT_INITIALIZED if no backend is registered (sapi_nvm_register_backend()); SAPI_STATUS_NOT_SUPPORTED if the registered backend does not implement open. REQ-OAL-NVM-010

Definition at line 44 of file sapi_nvm.c.

sapi_nvm_read()

sapi_status_t sapi_nvm_read	(	sapi_nvm_handle_t	handle,
		size_t	offset,
		void *	out_buffer,
		size_t	buffer_size )

Reads and integrity-checks data from an NVM region.

Parameters

handle	Open region handle. Must not be NULL.
offset	Byte offset within the region to read from.
out_buffer	Destination buffer. Must not be NULL.
buffer_size	Number of bytes to read into out_buffer; must be > 0.

Returns

SAPI_STATUS_OK; SAPI_STATUS_INVALID_PARAM for a bad argument; SAPI_STATUS_DATA_CORRUPTION if the integrity check fails (the output buffer content is then undefined and shall not be used); SAPI_STATUS_NOT_INITIALIZED/SAPI_STATUS_NOT_SUPPORTED as in sapi_nvm_open(). REQ-OAL-NVM-011

Definition at line 68 of file sapi_nvm.c.

sapi_nvm_write()

sapi_status_t sapi_nvm_write	(	sapi_nvm_handle_t	handle,
		size_t	offset,
		const void *	buffer,
		size_t	buffer_size )

Writes data and its integrity metadata to an NVM region.

Parameters

handle	Open region handle. Must not be NULL.
offset	Byte offset within the region to write to.
buffer	Source data. Must not be NULL.
buffer_size	Number of bytes to write from buffer; must be > 0.

Returns

SAPI_STATUS_OK; SAPI_STATUS_INVALID_PARAM for a bad argument; SAPI_STATUS_NOT_INITIALIZED/SAPI_STATUS_NOT_SUPPORTED as in sapi_nvm_open(). REQ-OAL-NVM-012

Definition at line 88 of file sapi_nvm.c.

sapi_nvm_sync()

sapi_status_t sapi_nvm_sync

(

sapi_nvm_handle_t

handle

)

Forces any buffered writes to durable storage.

Parameters

handle

Open region handle. Must not be NULL.

Returns

SAPI_STATUS_OK; SAPI_STATUS_INVALID_PARAM; SAPI_STATUS_NOT_INITIALIZED/ SAPI_STATUS_NOT_SUPPORTED as in sapi_nvm_open(). REQ-OAL-NVM-013

Definition at line 108 of file sapi_nvm.c.

sapi_nvm_close()

sapi_status_t sapi_nvm_close

(

sapi_nvm_handle_t

handle

)

Closes an NVM region handle.

Parameters

handle

Handle to close. Must not be NULL. Invalid to use after this call.

Returns

SAPI_STATUS_OK; SAPI_STATUS_INVALID_PARAM; SAPI_STATUS_NOT_INITIALIZED/ SAPI_STATUS_NOT_SUPPORTED as in sapi_nvm_open(). REQ-OAL-NVM-014

Definition at line 125 of file sapi_nvm.c.