POSIX sapi_nvm backend: one plain file per region, with a whole-region FNV-1a-64 hash trailer recomputed on every write and verified on every read (ADR-018 section 2.3), satisfying REQ-OAL-NVM-001's "every read shall be integrity-checked" via a single trailing hash rather than a redundant-copy vote. More...

#include "safeapi/posix_backend/sapi_posix_backend.h"
#include <errno.h>
#include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/stat.h>
#include <unistd.h>

Include dependency graph for sapi_posix_backend_nvm.c:

Data Structures
struct	posix_nvm_state_t

Macros
#define	_POSIX_C_SOURCE 200809L
#define	SAPI_POSIX_NVM_TRAILER_SIZE 8U
#define	SAPI_POSIX_NVM_PATH_MAX 256U
#define	SAPI_POSIX_NVM_CHUNK_SIZE 256U

Typedefs
typedef char	posix_nvm_storage_fits_[(sizeof(posix_nvm_state_t)<=sizeof(sapi_nvm_storage_t)) ? 1 :-1]

Functions
static uint64_t	fnv1a64_update (uint64_t hash, const uint8_t *data, size_t len)
static void	hash_to_bytes (uint64_t hash, uint8_t out[SAPI_POSIX_NVM_TRAILER_SIZE])
static uint64_t	bytes_to_hash (const uint8_t in[SAPI_POSIX_NVM_TRAILER_SIZE])
static bool	read_at (int fd, size_t offset, void *buffer, size_t len)
static bool	write_at (int fd, size_t offset, const void *buffer, size_t len)
static bool	compute_region_hash (int fd, size_t region_size, uint64_t *out_hash)
static bool	rewrite_trailer (int fd, size_t region_size)
static sapi_status_t	backend_open (sapi_nvm_storage_t storage, const sapi_nvm_config_t config, sapi_nvm_handle_t *out_handle)
static sapi_status_t	backend_read (sapi_nvm_handle_t handle, size_t offset, void *out_buffer, size_t buffer_size)
static sapi_status_t	backend_write (sapi_nvm_handle_t handle, size_t offset, const void *buffer, size_t buffer_size)
static sapi_status_t	backend_sync (sapi_nvm_handle_t handle)
static sapi_status_t	backend_close (sapi_nvm_handle_t handle)
const sapi_nvm_backend_t *	sapi_posix_backend_nvm (void)
	The POSIX sapi_nvm backend (file-backed, FNV-1a-64 integrity).

Variables
static const uint64_t	FNV_OFFSET_BASIS = 0xcbf29ce484222325ULL
static const uint64_t	FNV_PRIME = 0x100000001b3ULL
static const sapi_nvm_backend_t	s_posix_nvm_backend

Detailed Description

POSIX sapi_nvm backend: one plain file per region, with a whole-region FNV-1a-64 hash trailer recomputed on every write and verified on every read (ADR-018 section 2.3), satisfying REQ-OAL-NVM-001's "every read shall be integrity-checked" via a single trailing hash rather than a redundant-copy vote.

Deliberately does NOT reuse sapi_checksum's CRC-64: that module's lookup tables are known-incomplete placeholders (flagged in ADR-017 and docs/MISRA_COMPLIANCE_REPORT.md). Building this backend's integrity check on top of a hash already known to be broken would just move the problem, not solve it. FNV-1a-64 is simple enough to implement correctly inline, with no lookup table to get wrong.

Region files live in the directory named by the SAPI_POSIX_NVM_DIR environment variable, or the current working directory if unset - there is no config field for this in sapi_nvm_config_t, and inventing one would be an API change outside this ADR's scope.

Known simplification: verifying a read means hashing the whole region on every sapi_nvm_read() call, not just the bytes requested - correct, but O(region_size) per read rather than O(bytes read). Fine for the region sizes a first backend is expected to see; a production backend for large regions would want per-block hashes instead.

Definition in file sapi_posix_backend_nvm.c.

Macro Definition Documentation

◆ _POSIX_C_SOURCE

#define _POSIX_C_SOURCE 200809L

Definition at line 1 of file sapi_posix_backend_nvm.c.

◆ SAPI_POSIX_NVM_CHUNK_SIZE

#define SAPI_POSIX_NVM_CHUNK_SIZE 256U

Definition at line 50 of file sapi_posix_backend_nvm.c.

◆ SAPI_POSIX_NVM_PATH_MAX

#define SAPI_POSIX_NVM_PATH_MAX 256U

Definition at line 49 of file sapi_posix_backend_nvm.c.

◆ SAPI_POSIX_NVM_TRAILER_SIZE

#define SAPI_POSIX_NVM_TRAILER_SIZE 8U

Definition at line 48 of file sapi_posix_backend_nvm.c.

Typedef Documentation

◆ posix_nvm_storage_fits_

typedef char posix_nvm_storage_fits_[(sizeof(posix_nvm_state_t)<=sizeof(sapi_nvm_storage_t)) ? 1 :-1]

Definition at line 46 of file sapi_posix_backend_nvm.c.

Function Documentation

◆ backend_close()

sapi_status_t backend_close ( sapi_nvm_handle_t handle )

static

Definition at line 321 of file sapi_posix_backend_nvm.c.

◆ backend_open()

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

static

Definition at line 189 of file sapi_posix_backend_nvm.c.

◆ backend_read()

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

static

Definition at line 248 of file sapi_posix_backend_nvm.c.

◆ backend_sync()

sapi_status_t backend_sync ( sapi_nvm_handle_t handle )

static

Definition at line 306 of file sapi_posix_backend_nvm.c.

◆ backend_write()

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

static

Definition at line 282 of file sapi_posix_backend_nvm.c.

◆ bytes_to_hash()

uint64_t bytes_to_hash ( const uint8_t in[SAPI_POSIX_NVM_TRAILER_SIZE] )

static

Definition at line 77 of file sapi_posix_backend_nvm.c.

◆ compute_region_hash()

bool compute_region_hash	(	int	fd,
		size_t	region_size,
		uint64_t *	out_hash )

static

Hashes region_size bytes starting at file offset 0, streaming through a fixed-size stack buffer (no dynamic allocation, per REQ-OAL-NVM-002).

Definition at line 151 of file sapi_posix_backend_nvm.c.

◆ fnv1a64_update()

uint64_t fnv1a64_update	(	uint64_t	hash,
		const uint8_t *	data,
		size_t	len )

static

Definition at line 55 of file sapi_posix_backend_nvm.c.

◆ hash_to_bytes()

void hash_to_bytes	(	uint64_t	hash,
		uint8_t	out[SAPI_POSIX_NVM_TRAILER_SIZE] )

static

Definition at line 67 of file sapi_posix_backend_nvm.c.

◆ read_at()

bool read_at	(	int	fd,
		size_t	offset,
		void *	buffer,
		size_t	len )

static

EINTR-retrying full read at a given offset. Returns true on a complete read of len bytes, false otherwise (short read/error treated alike - both mean the caller cannot trust the data).

Definition at line 92 of file sapi_posix_backend_nvm.c.

◆ rewrite_trailer()

bool rewrite_trailer	(	int	fd,
		size_t	region_size )

static

Recomputes the whole-region hash and (re)writes the trailer.

Definition at line 176 of file sapi_posix_backend_nvm.c.

◆ sapi_posix_backend_nvm()

const sapi_nvm_backend_t * sapi_posix_backend_nvm ( void )

The POSIX sapi_nvm backend (file-backed, FNV-1a-64 integrity).

Definition at line 336 of file sapi_posix_backend_nvm.c.

◆ write_at()

bool write_at	(	int	fd,
		size_t	offset,
		const void *	buffer,
		size_t	len )

static

EINTR-retrying full write at a given offset.

Definition at line 123 of file sapi_posix_backend_nvm.c.

Variable Documentation

◆ FNV_OFFSET_BASIS

const uint64_t FNV_OFFSET_BASIS = 0xcbf29ce484222325ULL

static

Definition at line 52 of file sapi_posix_backend_nvm.c.

◆ FNV_PRIME

const uint64_t FNV_PRIME = 0x100000001b3ULL

static

Definition at line 53 of file sapi_posix_backend_nvm.c.

◆ s_posix_nvm_backend

const sapi_nvm_backend_t s_posix_nvm_backend

static

Initial value:

= { backend_open, backend_read, backend_write, backend_sync,

backend_close }

Definition at line 333 of file sapi_posix_backend_nvm.c.

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ _POSIX_C_SOURCE

◆ SAPI_POSIX_NVM_CHUNK_SIZE

◆ SAPI_POSIX_NVM_PATH_MAX

◆ SAPI_POSIX_NVM_TRAILER_SIZE

Typedef Documentation

◆ posix_nvm_storage_fits_

Function Documentation

◆ backend_close()

◆ backend_open()

◆ backend_read()

◆ backend_sync()

◆ backend_write()

◆ bytes_to_hash()

◆ compute_region_hash()

◆ fnv1a64_update()

◆ hash_to_bytes()

◆ read_at()

◆ rewrite_trailer()

◆ sapi_posix_backend_nvm()

◆ write_at()

Variable Documentation

◆ FNV_OFFSET_BASIS

◆ FNV_PRIME

◆ s_posix_nvm_backend