Transparent VFS-level whole-file compression (compress-on-write,decompress-on-read) over the ra8_io fabric. More...

#include <stdint.h>
#include "ra8_compress.h"
#include "ra8_err.h"

Include dependency graph for ra8_vfs_compress.h:

This graph shows which files directly or indirectly include this file:

Functions
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.
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.

Detailed Description

Transparent VFS-level whole-file compression (compress-on-write,

decompress-on-read) over the ra8_io fabric.

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

This layer makes DEFLATE compression a transparent property of a file: the caller hands a plain payload and a "name:/path" string, and the byte stream on the backing store is the compressed blob – the app never touches the codec, ra8_compress, or ra8_fs_write_file directly. Reading reverses the pipeline: the blob is pulled off the backing store and inflated into the caller's output buffer.

Both directions are whole-file (not an incremental stream filter), which matches the firmware's real .rabook RBKC use case and keeps the path simple and heap-free. Because the seam sits above the VFS, it composes over WHATEVER backend is mounted (RAM, SDRAM, SD/SDHI, OSPI, MRAM) – the same call writes a compressed file to any of them.

Every buffer is caller-provided, so the allocator (which this firmware traps) is never touched: the caller supplies the tdefl scratch, the staging blob buffer, and the decompressed-output buffer.

This header is opt-in: it pulls in ra8_compress (and through it miniz), so it is NOT part of the ra8_io.h umbrella – exactly like ra8_compress.h. Apps that want transparent compression include it directly and add miniz to their ra8_add_app(... LIBS ...).

static uint8_t scratch[(size_t)k_ra8_compress_scratch_bytes];
static uint8_t blob[(size_t)k_demo_blob_cap];
uint32_t       blob_len = 0;
(void)ra8_vfs_compress_write("ram:/STORY.RBK", payload, payload_len,
                                 scratch, sizeof(scratch),
                                 blob, sizeof(blob), &blob_len);
uint32_t out_len = 0;
(void)ra8_vfs_compress_read("ram:/STORY.RBK", blob, sizeof(blob),
                                restored, sizeof(restored), &out_len);

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

Since: 0.1.0

Definition in file ra8_vfs_compress.h.

Function Documentation

◆ 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.