ra8_fmt_stream_verify_plan.c File Reference

Exact caller-workspace planning for JOF verification. More...

#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "jof_produce.h"
#include "ra8_attributes.h"
#include "ra8_fmt_stream.h"

Include dependency graph for ra8_fmt_stream_verify_plan.c:

Go to the source code of this file.

Enumerations
enum	verify_plan_const_t : uint32_t {   k_verify_png_head = 26U ,   k_verify_png_chunks = 33U ,   k_verify_png_trns = 0x74524E53U ,   k_verify_png_idat = 0x49444154U ,   k_verify_jpeg_sof0 = 0xC0U ,   k_verify_jpeg_dht = 0xC4U ,   k_verify_jpeg_jpg = 0xC8U ,   k_verify_jpeg_dac = 0xCCU ,   k_verify_jpeg_marker = 0xFFU ,   k_verify_jpeg_soi = 0xD8U ,   k_verify_jpeg_sof_last = 0xCFU ,   k_verify_u32_high_shift = 24U ,   k_verify_jpeg_components = 7U ,   k_verify_png_chunk_record = 12U ,   k_verify_png_color_type = 25U ,   k_verify_fourcc_bytes = 4U ,   k_verify_webp_form_offset = 8U }
	Bounded encoded-header probe constants. More...
enum	verify_png_signature_t : uint8_t {   k_verify_png_sig_high = 0x89U ,   k_verify_png_sig_cr = 0x0DU ,   k_verify_png_sig_lf = 0x0AU ,   k_verify_png_sig_sub = 0x1AU }
	Fixed non-ASCII bytes in the PNG signature. More...

Functions
static ra8_err_t	internal_exact (const ra8_fmt_source_t *source, uint64_t offset, uint8_t *bytes, size_t len)
	Read one exact positioned span.
static uint16_t	internal_be16 (const uint8_t bytes[2])
	Decode one big-endian uint16 field.
static uint32_t	internal_be32 (const uint8_t bytes[4])
	Decode one big-endian uint32 field.
static bool	internal_is_sof (uint8_t marker)
	Classify a JPEG SOF-range marker without table-marker false positives.
static ra8_err_t	internal_jpeg_bpp (const ra8_fmt_source_t *source, uint8_t *bpp)
	Determine baseline JPEG output channels from the first SOF.
static ra8_err_t	internal_png_bpp (const ra8_fmt_source_t *source, uint8_t color_type, uint8_t *bpp)
	Scan pre-IDAT PNG chunks for palette transparency.
static ra8_err_t	internal_bpp (const ra8_fmt_source_t *source, uint8_t *bpp)
	Derive exact producer output channels from source headers.
static ra8_err_t	internal_stable (const ra8_fmt_source_t *source)
	Validate a source through its optional stability callback.
ra8_err_t	ra8_fmt_jof_verify_requirements (const ra8_fmt_source_t *source, ra8_fmt_jof_verify_requirements_t *out)
	Derive exact producer and comparison storage for bounded JOF verification.

Detailed Description

Exact caller-workspace planning for JOF verification.

Probes encoded JPEG, PNG, and WebP headers through positioned reads, derives decoder channel geometry, and reports exact caller-workspace bounds.

Copyright

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

Since

0.1.0

Definition in file ra8_fmt_stream_verify_plan.c.

Enumeration Type Documentation

verify_plan_const_t

enum verify_plan_const_t : uint32_t

Bounded encoded-header probe constants.

Enumerator
k_verify_png_head	Signature, IHDR, and colour type.
k_verify_png_chunks	First post-IHDR chunk offset.
k_verify_png_trns	PNG tRNS chunk code.
k_verify_png_idat	PNG IDAT chunk code.
k_verify_jpeg_sof0	First JPEG SOF code.
k_verify_jpeg_dht	JPEG table code in SOF range.
k_verify_jpeg_jpg	JPEG reserved SOF-range code.
k_verify_jpeg_dac	JPEG arithmetic table code.
k_verify_jpeg_marker	JPEG marker introducer.
k_verify_jpeg_soi	JPEG start-of-image marker.
k_verify_jpeg_sof_last	Last JPEG SOF-range marker.
k_verify_u32_high_shift	Big-endian uint32 high shift.
k_verify_jpeg_components	Component-count offset after len.
k_verify_png_chunk_record	PNG chunk framing bytes.
k_verify_png_color_type	PNG IHDR colour-type offset.
k_verify_fourcc_bytes	RIFF/WebP fourCC width.
k_verify_webp_form_offset	RIFF form-type field offset.

Definition at line 20 of file ra8_fmt_stream_verify_plan.c.

verify_png_signature_t

enum verify_png_signature_t : uint8_t

Fixed non-ASCII bytes in the PNG signature.

Enumerator
k_verify_png_sig_high	High-bit signature byte.
k_verify_png_sig_cr	Carriage return byte.
k_verify_png_sig_lf	Line feed byte.
k_verify_png_sig_sub	DOS EOF byte.

Definition at line 41 of file ra8_fmt_stream_verify_plan.c.

Function Documentation

internal_be16()

uint16_t internal_be16 ( const uint8_t bytes[2] )

static

Decode one big-endian uint16 field.

Combines exactly two network-order bytes without unaligned access.

Parameters

[in]

bytes

Two encoded bytes.

Returns

Decoded host-order value.

Return values

UINT16_MAX

The encoded field contains all one bits.

Precondition

bytes spans exactly two readable bytes.

The caller has already bounded the enclosing encoded object.

Postcondition

No source byte changes.

The return value depends only on the two input bytes.

Note

Pure and thread-safe.

Since

0.1.0

Definition at line 103 of file ra8_fmt_stream_verify_plan.c.

Referenced by internal_jpeg_bpp().

internal_be32()

uint32_t internal_be32 ( const uint8_t bytes[4] )

static

Decode one big-endian uint32 field.

Combines exactly four network-order bytes without unaligned access.

Parameters

[in]

bytes

Four encoded bytes.

Returns

Decoded host-order value.

Return values

UINT32_MAX

The encoded field contains all one bits.

Precondition

bytes spans exactly four readable bytes.

The caller has already bounded the enclosing encoded object.

Postcondition

No source byte changes.

The return value depends only on the four input bytes.

Note

Pure and thread-safe.

Since

0.1.0

Definition at line 122 of file ra8_fmt_stream_verify_plan.c.

References k_verify_u32_high_shift.

Referenced by internal_png_bpp().

internal_bpp()

ra8_err_t internal_bpp ( const ra8_fmt_source_t * source, uint8_t * bpp )

static

Derive exact producer output channels from source headers.

Dispatches bounded JPEG, PNG, and WebP header probes.

Parameters

[in]	source	Supported encoded image.
[out]	bpp	Receives one, three, or four.

Returns

Probe status.

Return values

k_ra8_ok	A supported source supplied its decoder channel count.
k_ra8_err_not_supported	The source kind is unsupported.
other	Source or malformed-header status.

Precondition

source is non-null with at least the bounded probe prefix.

bpp is writable.

Postcondition

Success initializes bpp.

No source byte or callback state is modified.

Note

Does not decode pixel bodies.

Since

0.1.0

Definition at line 287 of file ra8_fmt_stream_verify_plan.c.

References internal_exact(), internal_jpeg_bpp(), internal_png_bpp(), k_ra8_err_not_supported, k_ra8_ok, k_verify_fourcc_bytes, k_verify_jpeg_marker, k_verify_jpeg_soi, k_verify_png_color_type, k_verify_png_head, k_verify_png_sig_cr, k_verify_png_sig_high, k_verify_png_sig_lf, k_verify_png_sig_sub, k_verify_webp_form_offset, and memcmp().

Referenced by ra8_fmt_jof_verify_requirements().

internal_exact()

ra8_err_t internal_exact ( const ra8_fmt_source_t * source, uint64_t offset, uint8_t * bytes, size_t len )

static

Read one exact positioned span.

Loops over legal short reads and rejects premature or oversized progress.

Parameters

[in]	source	Bound immutable source.
[in]	offset	Absolute offset.
[out]	bytes	Exact destination span.
[in]	len	Required byte count.

Returns

Callback status or protocol failure.

Return values

k_ra8_ok	Every requested byte was initialized.
k_ra8_err_protocol_error	The range or callback progress was invalid.
other	Positioned-source callback status.

Precondition

The requested range is within source size.

Non-empty bytes spans len writable bytes.

Postcondition

Success initializes every requested byte.

Source position and captured extent remain unchanged.

Note

Thread safety inherits the source callback.

Since

0.1.0

Definition at line 68 of file ra8_fmt_stream_verify_plan.c.

References ra8_fmt_source_t::ctx, k_ra8_err_protocol_error, k_ra8_ok, ra8_fmt_source_t::read_at, and ra8_fmt_source_t::size.

Referenced by internal_bpp(), internal_jpeg_bpp(), and internal_png_bpp().

internal_is_sof()

bool internal_is_sof ( uint8_t marker )

static

Classify a JPEG SOF-range marker without table-marker false positives.

Accepts frame markers while excluding DHT, JPG, and DAC codes.

Parameters

[in]

marker

Candidate marker byte.

Returns

Whether marker is a supported start-of-frame marker.

Return values

true	The marker denotes a frame header.
false	The marker is outside the range or names a table.

Precondition

marker is the byte following a JPEG marker introducer.

Marker stuffing has already been removed.

Postcondition

No parser or source state changes.

Classification is deterministic.

Note

Pure and thread-safe.

Since

0.1.0

Definition at line 143 of file ra8_fmt_stream_verify_plan.c.

References k_verify_jpeg_dac, k_verify_jpeg_dht, k_verify_jpeg_jpg, k_verify_jpeg_sof0, and k_verify_jpeg_sof_last.

Referenced by internal_jpeg_bpp().

internal_jpeg_bpp()

ra8_err_t internal_jpeg_bpp ( const ra8_fmt_source_t * source, uint8_t * bpp )

static

Determine baseline JPEG output channels from the first SOF.

Walks bounded marker segments until a supported frame header is found.

Parameters

[in]	source	JPEG source.
[out]	bpp	Receives one or three output channels.

Returns

Probe or unsupported-channel status.

Return values

k_ra8_ok	A supported SOF supplied the channel count.
k_ra8_err_not_supported	The SOF channel count is unsupported.
other	Source or malformed-marker status.

Precondition

source is non-null with a positioned-read callback.

The source begins with a JPEG start-of-image marker.

Postcondition

Success initializes bpp.

Failure does not publish a channel count.

Note

Work is bounded by immutable source length.

Since

0.1.0

Definition at line 168 of file ra8_fmt_stream_verify_plan.c.

References internal_be16(), internal_exact(), internal_is_sof(), k_ra8_err_not_supported, k_ra8_err_protocol_error, k_ra8_ok, k_verify_jpeg_components, and k_verify_jpeg_marker.

Referenced by internal_bpp().

internal_png_bpp()

ra8_err_t internal_png_bpp ( const ra8_fmt_source_t * source, uint8_t color_type, uint8_t * bpp )

static

Scan pre-IDAT PNG chunks for palette transparency.

Maps IHDR colour type and optional tRNS presence to producer channels.

Parameters

[in]	source	PNG source.
[in]	color_type	IHDR colour-type byte.
[out]	bpp	Receives the producer output channel count.

Returns

Probe or malformed-window status.

Return values

k_ra8_ok	A supported mapping reached the first IDAT.
k_ra8_err_not_supported	The colour type is unsupported.
other	Source or malformed-chunk status.

Precondition

source is a bounded PNG positioned source.

bpp is writable.

Postcondition

Success initializes bpp exactly as the producer does.

Source bytes and position remain unchanged.

Note

Work is bounded by the pre-IDAT source bytes.

Since

0.1.0

Definition at line 229 of file ra8_fmt_stream_verify_plan.c.

References internal_be32(), internal_exact(), k_ra8_err_not_supported, k_ra8_err_protocol_error, k_ra8_ok, k_verify_png_chunk_record, k_verify_png_chunks, k_verify_png_idat, k_verify_png_trns, and ra8_fmt_source_t::size.

Referenced by internal_bpp().

internal_stable()

ra8_err_t internal_stable ( const ra8_fmt_source_t * source )

static

Validate a source through its optional stability callback.

Delegates immutable-view revalidation while preserving optional bindings.

Parameters

[in]

source

Source to validate.

Returns

Stability callback status or success when validation is absent.

Return values

k_ra8_ok	The source is unchanged or has no validator.
other	The backend observed mutation or validation failure.

Precondition

source is non-null.

The captured size still describes the intended object.

Postcondition

No source position changes.

Success permits continued trust in the captured view.

Note

Thread safety inherits the backend validator.

Since

0.1.0

Definition at line 336 of file ra8_fmt_stream_verify_plan.c.

References ra8_fmt_source_t::ctx, k_ra8_ok, ra8_fmt_source_t::size, and ra8_fmt_source_t::validate.

Referenced by ra8_fmt_jof_verify_requirements().

ra8_fmt_jof_verify_requirements()

ra8_err_t ra8_fmt_jof_verify_requirements ( const ra8_fmt_source_t * source, ra8_fmt_jof_verify_requirements_t * out )

nodiscard

Derive exact producer and comparison storage for bounded JOF verification.

Parameters

[in]	source	Stable JPEG, PNG, or WebP source.
[out]	out	Receives exact phase requirements.

Returns

Probe or sizing status.

Precondition

source provides immutable positioned reads for its declared size.

Postcondition

Success initializes every requirement field without creating a spool.

Note

Source-kind parsing is bounded by source size and caller storage.

Since

0.1.0

Definition at line 341 of file ra8_fmt_stream_verify_plan.c.

References ra8_fmt_jof_verify_requirements_t::band_height, ra8_fmt_jof_verify_requirements_t::band_tile_bytes, ra8_fmt_jof_verify_requirements_t::banded_work_bytes, ra8_fmt_jof_verify_requirements_t::bpp, ra8_fmt_jof_convert_requirements_t::height, ra8_fmt_jof_verify_requirements_t::height, internal_bpp(), internal_stable(), jof_stored_bound(), jof_work_bytes(), k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, ra8_fmt_jof_convert_requirements(), ra8_fmt_source_t::read_at, ra8_fmt_jof_verify_requirements_t::reference_work_bytes, ra8_fmt_jof_verify_requirements_t::row_bytes, ra8_fmt_jof_verify_requirements_t::scratch_bytes, ra8_fmt_jof_convert_requirements_t::tile_height, ra8_fmt_jof_convert_requirements_t::webp_work_bytes, ra8_fmt_jof_verify_requirements_t::webp_work_bytes, ra8_fmt_jof_convert_requirements_t::width, ra8_fmt_jof_verify_requirements_t::width, and ra8_fmt_jof_convert_requirements_t::work_bytes.

Referenced by internal_open_and_size().