Transparent whole-file compress-on-write / decompress-on-read over the ra8_io VFS. More...

#include "ra8_vfs_compress.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_compress.h"
#include "ra8_err.h"
#include "ra8_fs.h"
#include "ra8_io_vfs.h"

Include dependency graph for ra8_vfs_compress.c:

Functions
static ra8_err_t	internal_ra8_vfs_compress_write_validate (const char path, const uint8_t src, const void scratch, const uint8_t blob_buf, const uint32_t *out_blob_len)
	Validate the five caller pointers handed to ra8_vfs_compress_write.
static ra8_err_t	internal_ra8_vfs_compress_store_blob (const char path, const uint8_t blob, uint32_t blob_len)
	Open path for write, stream the compressed blob, and close.
ra8_err_t	ra8_vfs_compress_write (const char path, const uint8_t src, uint32_t src_len, void scratch, uint32_t scratch_len, uint8_t blob_buf, uint32_t blob_cap, uint32_t *out_blob_len)
	Compress a payload and store it as a whole file through the VFS.
static ra8_err_t	internal_ra8_vfs_compress_read_validate (const char path, const uint8_t blob_buf, const uint8_t out, const uint32_t out_len)
	Validate the four caller pointers handed to ra8_vfs_compress_read.
static ra8_err_t	internal_ra8_vfs_compress_load_blob (const char path, uint8_t blob_buf, uint32_t blob_cap, uint32_t *out_blob_len)
	Open path for read, pull the whole blob into blob_buf, and close.
ra8_err_t	ra8_vfs_compress_read (const char path, uint8_t blob_buf, uint32_t blob_cap, uint8_t out, uint32_t out_cap, uint32_t out_len)
	Read a whole compressed file through the VFS and decompress it.

Variables
static const char *const	s_tag = "ra8_vfs_compress"
	Module log tag.

Detailed Description

Transparent whole-file compress-on-write / decompress-on-read over the ra8_io VFS.

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

Composes the buffer-to-buffer codec (ra8_compress / ra8_decompress) with the VFS file ops (ra8_io_vfs_open + ra8_fs_write / ra8_fs_read + ra8_fs_close). Write compresses the caller payload into the caller blob buffer and streams the blob to the resolved file; read pulls the blob off the file into the caller blob buffer and inflates it into the caller output. No allocator is touched – every buffer is caller-owned. All guards are single-condition (no compound decisions, so no MC/DC vectors are due).

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

Definition in file ra8_vfs_compress.c.

Function Documentation

◆ internal_ra8_vfs_compress_load_blob()

ra8_err_t internal_ra8_vfs_compress_load_blob	(	const char *	path,
		uint8_t *	blob_buf,
		uint32_t	blob_cap,
		uint32_t *	out_blob_len )

static

Open path for read, pull the whole blob into blob_buf, and close.

Resolves path through the VFS in read mode, copies up to blob_cap bytes into blob_buf, and closes the file. The read and close error codes are captured separately so the file is always closed even when the read fails; the read error takes precedence over the close error. Because ra8_fs_read caps the copy at blob_cap, a blob that fills blob_buf exactly cannot be distinguished from a truncated larger file, so a full-buffer read is rejected as k_ra8_err_invalid_size. Each guard is a single condition, so no compound decision is split across this helper and its caller.

Parameters

[in]	path	"name:/sub" source string (already validated).
[out]	blob_buf	Caller staging buffer for the on-disk blob.
[in]	blob_cap	Capacity of blob_buf in bytes.
[out]	out_blob_len	Byte count read into blob_buf on success.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Blob read and *out_blob_len set.
k_ra8_err_invalid_size	The blob filled blob_buf (possible truncation).
k_ra8_err_*	Propagated from the VFS open, read, or close.

Precondition: path, blob_buf, and out_blob_len are non-NULL (caller validated).; The named volume in path is mounted and the file exists.

Postcondition: On k_ra8_ok blob_buf[0 .. *out_blob_len) holds the on-disk blob.; On any non-ok return the file handle is closed (no leak).

Note: Not thread-safe with respect to blob_buf.

Since: 0.1.0

Definition at line 223 of file ra8_vfs_compress.c.

References k_ra8_err_invalid_size, k_ra8_fs_mode_read, k_ra8_ok, ra8_fs_close(), ra8_fs_read(), RA8_INTERNAL, ra8_io_vfs_open(), RA8_RETURN_ON_ERROR, and s_tag.

Referenced by ra8_vfs_compress_read().

◆ internal_ra8_vfs_compress_read_validate()

ra8_err_t internal_ra8_vfs_compress_read_validate	(	const char *	path,
		const uint8_t *	blob_buf,
		const uint8_t *	out,
		const uint32_t *	out_len )

static

Validate the four caller pointers handed to ra8_vfs_compress_read.

Rejects any NULL pointer argument before the VFS or the codec is touched, keeping the public entry point's body short and its statement count under the NASA Rule 4 / clang-tidy threshold. Each guard is a single condition (ptr == nullptr), so no compound decision is split across this helper and its caller and no MC/DC vector is due.

Parameters

[in]	path	"name:/sub" source string.
[in]	blob_buf	Caller staging buffer for the on-disk compressed blob.
[in]	out	Destination for the decompressed payload.
[in]	out_len	Out-param for the decompressed byte count.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Every pointer argument is non-NULL.
k_ra8_err_null_ptr	Some pointer argument was NULL.

Precondition: The caller passes the same pointers it received from its own caller.; s_tag is initialised (it is a file-scope constant).

Postcondition: On k_ra8_ok all four pointers are safe to dereference.; On k_ra8_err_null_ptr no pointer was dereferenced.

Note: Pure validation; not thread-safe-sensitive (reads no shared state).

Since: 0.1.0

Definition at line 179 of file ra8_vfs_compress.c.

References k_ra8_ok, RA8_CHECK_NULL_PTR, RA8_INTERNAL, and s_tag.

Referenced by ra8_vfs_compress_read().

◆ internal_ra8_vfs_compress_store_blob()

ra8_err_t internal_ra8_vfs_compress_store_blob	(	const char *	path,
		const uint8_t *	blob,
		uint32_t	blob_len )

static

Open path for write, stream the compressed blob, and close.

Resolves path through the VFS in write mode, writes the whole blob, and closes the file. The write and close error codes are captured separately so the file is always closed even when the write fails; the write error takes precedence over the close error. Each guard is a single condition, so no compound decision is split across this helper and its caller.

Parameters

[in]	path	"name:/sub" destination string (already validated).
[in]	blob	Compressed bytes to store.
[in]	blob_len	Number of bytes in blob to write.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Blob written and file closed cleanly.
k_ra8_err_*	Propagated from the VFS open, write, or close.

Precondition: path and blob are non-NULL (the caller validated them).; The named volume in path is mounted.

Postcondition: On k_ra8_ok the file holds exactly blob_len bytes.; On any non-ok return the file handle is closed (no leak).

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

Since: 0.1.0

Definition at line 108 of file ra8_vfs_compress.c.

References k_ra8_fs_mode_write, k_ra8_ok, ra8_fs_close(), ra8_fs_write(), ra8_io_vfs_open(), RA8_RETURN_ON_ERROR, and s_tag.

Referenced by ra8_vfs_compress_write().

◆ internal_ra8_vfs_compress_write_validate()

ra8_err_t internal_ra8_vfs_compress_write_validate	(	const char *	path,
		const uint8_t *	src,
		const void *	scratch,
		const uint8_t *	blob_buf,
		const uint32_t *	out_blob_len )

static

Validate the five caller pointers handed to ra8_vfs_compress_write.

Rejects any NULL pointer argument before the compressor or the VFS is touched, keeping the public entry point's body short and its statement count under the NASA Rule 4 / clang-tidy threshold. Each guard is a single condition (ptr == nullptr), so no compound decision is split across this helper and its caller and no MC/DC vector is due.

Parameters

[in]	path	"name:/sub" destination string.
[in]	src	Plain payload bytes to compress.
[in]	scratch	Caller compressor scratch buffer.
[in]	blob_buf	Caller staging buffer for the compressed blob.
[in]	out_blob_len	Out-param for the compressed byte count.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Every pointer argument is non-NULL.
k_ra8_err_null_ptr	Some pointer argument was NULL.

Precondition: The caller passes the same pointers it received from its own caller.; s_tag is initialised (it is a file-scope constant).

Postcondition: On k_ra8_ok all five pointers are safe to dereference.; On k_ra8_err_null_ptr no pointer was dereferenced.

Note: Pure validation; not thread-safe-sensitive (reads no shared state).

Since: 0.1.0

Definition at line 66 of file ra8_vfs_compress.c.

References k_ra8_ok, RA8_CHECK_NULL_PTR, RA8_INTERNAL, and s_tag.

Referenced by ra8_vfs_compress_write().

◆ ra8_vfs_compress_read()

ra8_err_t ra8_vfs_compress_read	(	const char *	path,
		uint8_t *	blob_buf,
		uint32_t	blob_cap,
		uint8_t *	out,
		uint32_t	out_cap,
		uint32_t *	out_len )

nodiscard

Read a whole compressed file through the VFS and decompress it.

Opens path ("name:/sub") through the VFS, reads the entire blob into the caller-provided blob_buf, then inflates it with ra8_decompress into out. Heap-free: the staging blob buffer and the output buffer are both caller-provided. Reverses ra8_vfs_compress_write exactly.

Parameters

[in]	path	"name:/sub" source string.
[out]	blob_buf	Caller staging buffer for the on-disk compressed blob.
[in]	blob_cap	Capacity of blob_buf (must hold the whole blob).
[out]	out	Destination for the decompressed payload.
[in]	out_cap	Capacity of out (must hold the whole result).
[out]	out_len	Decompressed byte count on success.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Read and decompressed; *out_len set.
k_ra8_err_null_ptr	Any pointer argument was NULL.
k_ra8_err_invalid_arg	path has no name: prefix.
k_ra8_err_not_found	The mount name or the file is absent.
k_ra8_err_invalid_size	The blob exceeded blob_cap.
k_ra8_err_no_mem	out was too small, or the blob is corrupt.
k_ra8_err_*	Propagated from the VFS read.

Precondition: The named volume in path is mounted and the file exists.; out is large enough to hold the whole decompressed payload.

Postcondition: On success out[0 .. *out_len) holds the original payload.; On any non-ok return the buffers are unspecified.

Note: Heap-free; not thread-safe with respect to blob_buf / out.

Since: 0.1.0

Definition at line 246 of file ra8_vfs_compress.c.

References internal_ra8_vfs_compress_load_blob(), internal_ra8_vfs_compress_read_validate(), k_ra8_ok, ra8_decompress(), RA8_RETURN_ON_ERROR, and s_tag.

Referenced by internal_demo_roundtrip().

◆ ra8_vfs_compress_write()

ra8_err_t ra8_vfs_compress_write	(	const char *	path,
		const uint8_t *	src,
		uint32_t	src_len,
		void *	scratch,
		uint32_t	scratch_len,
		uint8_t *	blob_buf,
		uint32_t	blob_cap,
		uint32_t *	out_blob_len )

nodiscard

Compress a payload and store it as a whole file through the VFS.

Resolves path ("name:/sub") through the VFS, DEFLATE-compresses src into the caller-provided blob_buf via ra8_compress (using the caller-provided scratch for the miniz compressor), then writes the resulting blob to the file over whatever backend backs the named mount. No allocator is touched: both the compressor scratch and the staging blob buffer come from the caller.

Parameters

[in]	src	Plain payload bytes to compress.
[in]	src_len	Number of input bytes (> 0).
[in]	path	"name:/sub" destination string.
[in]	scratch	Caller buffer >= k_ra8_compress_scratch_bytes, 8-byte aligned (holds the miniz compressor).
[in]	scratch_len	Size of scratch in bytes.
[out]	blob_buf	Caller staging buffer for the compressed blob.
[in]	blob_cap	Capacity of blob_buf in bytes.
[out]	out_blob_len	Compressed byte count written to the file on success.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Compressed and stored; *out_blob_len set.
k_ra8_err_null_ptr	Any pointer argument was NULL.
k_ra8_err_invalid_size	scratch_len is below the minimum.
k_ra8_err_no_mem	blob_buf was too small for the result.
k_ra8_err_invalid_arg	path has no name: prefix.
k_ra8_err_not_found	The mount name is absent.
k_ra8_err_*	Propagated from the compressor or the VFS write.

Precondition: scratch is at least k_ra8_compress_scratch_bytes and 8-aligned.; The named volume in path is mounted.

Postcondition: On success the file holds a raw-DEFLATE blob of *out_blob_len bytes.; On any non-ok return no file is created and the buffers are unspecified.

Note: Not thread-safe with respect to the same scratch / blob buffer.

Since: 0.1.0

Definition at line 123 of file ra8_vfs_compress.c.

References internal_ra8_vfs_compress_store_blob(), internal_ra8_vfs_compress_write_validate(), k_ra8_ok, ra8_compress(), RA8_RETURN_ON_ERROR, and s_tag.

Referenced by internal_demo_roundtrip().

Variable Documentation

◆ s_tag

const char* const s_tag = "ra8_vfs_compress"

static

Module log tag.

Definition at line 34 of file ra8_vfs_compress.c.

Functions

Variables

Detailed Description

Function Documentation

◆ internal_ra8_vfs_compress_load_blob()

◆ internal_ra8_vfs_compress_read_validate()

◆ internal_ra8_vfs_compress_store_blob()

◆ internal_ra8_vfs_compress_write_validate()

◆ ra8_vfs_compress_read()

◆ ra8_vfs_compress_write()

Variable Documentation

◆ s_tag