Checked raw-fd presentation workspace implementation. More...

#include "emu_presentation.h"
#include <errno.h>
#include <fcntl.h>
#include <stdalign.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include "emu_host_io_internal.h"
#include "emu_view.h"

Include dependency graph for emu_presentation.c:

Data Structures
struct	emu_presentation_plan_t
	Complete internal geometry and storage plan. More...

Enumerations
enum	presentation_invariant_t : size_t { k_presentation_expected_scratch_bytes = 16384U }
	Compile-time invariant values for presentation storage. More...

Functions
static RA8_INTERNAL int	internal_anonymous_fd (size_t size, int *os_error)
	Create, unlink, and exactly size one anonymous temporary descriptor.
static RA8_INTERNAL emu_presentation_result_t	internal_result (emu_presentation_status_t status, size_t surface, size_t required_scratch, size_t supplied_scratch, int os_error)
	Construct a complete operation result.
static RA8_INTERNAL bool	internal_add (size_t left, size_t right, size_t *result)
	Checked size addition.
static RA8_INTERNAL bool	internal_multiply (size_t left, size_t right, size_t *result)
	Checked size multiplication.
static RA8_INTERNAL bool	internal_rotation_valid (uint32_t rotation)
	True for one supported clockwise rotation.
static RA8_INTERNAL emu_presentation_status_t	internal_plan (const emu_presentation_spec_t spec, emu_presentation_plan_t plan)
	Compute all checked geometry and storage values.
emu_presentation_result_t	emu_presentation_requirements (const emu_presentation_spec_t *spec)
	Compute exact raw-fd and scratch requirements without mutation.
emu_presentation_result_t	emu_presentation_open (const emu_presentation_spec_t spec, void scratch, size_t supplied_scratch_bytes, emu_presentation_workspace_t *workspace)
	Create and bind one unlinked raw-fd presentation workspace.
bool	emu_presentation_close (emu_presentation_workspace_t *workspace)
	Close one owned presentation descriptor and invalidate the workspace.
bool	emu_presentation_read (const emu_presentation_workspace_t workspace, size_t offset, void bytes, size_t count)
	Read exact RGB565 bytes at a checked surface offset.
bool	emu_presentation_write (emu_presentation_workspace_t workspace, size_t offset, const void bytes, size_t count)
	Write exact RGB565 bytes at a checked surface offset.
bool	emu_presentation_fill (void *context, uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint16_t color)
	Fill a checked RGB565 rectangle in a raw-fd surface.
bool	emu_presentation_snapshot (emu_presentation_workspace_t workspace, int snapshot_fd)
	Create an immutable unlinked descriptor snapshot of one surface.

Detailed Description

Checked raw-fd presentation workspace implementation.

Plans overflow-safe surface geometry and manages unlinked temporary descriptors for the raw composite and bounded scratch storage, with exact injected I/O and explicit ownership transfer on every lifecycle path.

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

Since: 0.1.0

Definition in file emu_presentation.c.

Enumeration Type Documentation

◆ presentation_invariant_t

enum presentation_invariant_t : size_t

Compile-time invariant values for presentation storage.

Enumerator
k_presentation_expected_scratch_bytes	Two maximum RGB565 tiles.

Definition at line 26 of file emu_presentation.c.

Function Documentation

◆ emu_presentation_close()

bool emu_presentation_close ( emu_presentation_workspace_t * workspace )

Close one owned presentation descriptor and invalidate the workspace.

Parameters

[in,out] workspace Workspace returned by emu_presentation_open.

Returns: Whether close completed or the workspace was already inactive.

Postcondition: workspace is reset with fd -1 even when close reports failure.

Note: Does not modify borrowed scratch bytes.

Since: 0.1.0

Close one owned presentation descriptor and invalidate the workspace; this step is contained within the emu presentation model and uses bounded caller or module-owned storage.

Return values

true	The emu presentation close condition holds or completed successfully; false otherwise.

Precondition: Arguments satisfy the ranges documented for emu presentation close.; The call executes on the emulator's single owning thread.

Postcondition: Ownership of caller-supplied storage is unchanged.

Definition at line 303 of file emu_presentation.c.

References emu_presentation_workspace_t::fd.

Referenced by internal_main_load_images(), main(), and priv_run_cleanup().

◆ emu_presentation_fill()

bool emu_presentation_fill	(	void *	context,
		uint16_t	x,
		uint16_t	y,
		uint16_t	width,
		uint16_t	height,
		uint16_t	color )

Fill a checked RGB565 rectangle in a raw-fd surface.

Matches board_overlay_fill_fn and uses only bound row scratch.

Parameters

[in,out]	context	An emu_presentation_workspace_t.
[in]	x	Rectangle column.
[in]	y	Rectangle row.
[in]	width	Rectangle width.
[in]	height	Rectangle height.
[in]	color	RGB565 fill color.

Returns: True when every row was written exactly.

Precondition: The rectangle is inside the composite geometry.

Postcondition: Failure is bounded to the owned raw surface; no external output changes.

Since: 0.1.0

Return values

true	The emu presentation fill condition holds or completed successfully; false otherwise.

Precondition: The call executes on the emulator's single owning thread.

Postcondition: Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Definition at line 339 of file emu_presentation.c.

References emu_presentation_workspace_t::composite_height, emu_presentation_workspace_t::composite_width, emu_presentation_write(), emu_presentation_workspace_t::scratch, and emu_presentation_workspace_t::scratch_bytes.

Referenced by priv_emu_view_surface_build().

◆ emu_presentation_open()

emu_presentation_result_t emu_presentation_open	(	const emu_presentation_spec_t *	spec,
		void *	scratch,
		size_t	supplied_scratch_bytes,
		emu_presentation_workspace_t *	workspace )

nodiscard

Create and bind one unlinked raw-fd presentation workspace.

Validates exact capacity before creating an anonymous temporary; failure preserves workspace and every scratch byte.

Parameters

[in]	spec	Presentation geometry and mode.
[in,out]	scratch	Caller-owned bounded scratch, or nullptr if inactive.
[in]	supplied_scratch_bytes	Writable scratch capacity.
[out]	workspace	Receives one independent owned descriptor on success.

Returns: Exact requirements, supplied capacity, and captured I/O error.

Precondition: spec and workspace are non-null.; Non-null scratch spans supplied_scratch_bytes writable bytes.; Active scratch is aligned to alignof(uint16_t).

Postcondition: Success leaves no named temporary path and owns exactly one descriptor.; Failure leaves workspace and scratch unchanged with no descriptor leak.

Note: Distinct workspaces are independently usable and closeable.

Since: 0.1.0

Definition at line 246 of file emu_presentation.c.

Referenced by internal_main_open_presentation().

◆ emu_presentation_read()

bool emu_presentation_read	(	const emu_presentation_workspace_t *	workspace,
		size_t	offset,
		void *	bytes,
		size_t	count )

Read exact RGB565 bytes at a checked surface offset.

Read exact rgb565 bytes at a checked surface offset; this step is contained within the emu presentation model and uses bounded caller or module-owned storage.

Parameters

[in]	workspace	Caller-owned workspace used by the operation.
[in]	offset	Byte or register offset at which processing begins.
[in,out]	bytes	Byte storage transferred by the operation.
[in]	count	Number of elements or bytes to process.

Returns: The emu presentation read result produced by the emu presentation model.

Return values

true	The emu presentation read condition holds or completed successfully; false otherwise.

Precondition: Arguments satisfy the ranges documented for emu presentation read.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu presentation model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 313 of file emu_presentation.c.

References emu_presentation_workspace_t::fd, k_emu_io_ok, priv_emu_io_pread_exact(), emu_io_result_t::status, and emu_presentation_workspace_t::surface_bytes.

Referenced by emu_presentation_snapshot(), and internal_write_ppm_pixels().

◆ emu_presentation_requirements()

emu_presentation_result_t emu_presentation_requirements ( const emu_presentation_spec_t * spec )

nodiscard

Compute exact raw-fd and scratch requirements without mutation.

Parameters

[in] spec Presentation geometry and mode.

Returns: Exact requirements or validation/overflow status.

Precondition: spec is non-null.

Postcondition: No caller memory, descriptor, filesystem name, or global changes.

Note: Pure and thread-safe.

Since: 0.1.0

Definition at line 235 of file emu_presentation.c.

References internal_plan(), internal_result(), k_emu_presentation_ok, emu_presentation_plan_t::scratch_bytes, and emu_presentation_plan_t::surface_bytes.

◆ emu_presentation_snapshot()

bool emu_presentation_snapshot	(	emu_presentation_workspace_t *	workspace,
		int *	snapshot_fd )

Create an immutable unlinked descriptor snapshot of one surface.

Parameters

[in,out]	workspace	Complete surface and bounded transfer scratch.
[out]	snapshot_fd	Receives an owned descriptor positioned arbitrarily.

Returns: True only when every source byte was copied exactly.

Postcondition: Success transfers close ownership of snapshot_fd to the caller.; Failure preserves snapshot_fd and leaks no descriptor or path.

Note: The immutable copy prevents asynchronous display-provider data races.

Since: 0.1.0

Create an immutable unlinked descriptor snapshot of one surface; this step is contained within the emu presentation model and uses bounded caller or module-owned storage.

Return values

true	The emu presentation snapshot condition holds or completed successfully; false otherwise.

Precondition: Arguments satisfy the ranges documented for emu presentation snapshot.; The call executes on the emulator's single owning thread.

Definition at line 377 of file emu_presentation.c.

References emu_presentation_read(), emu_presentation_workspace_t::fd, internal_anonymous_fd(), k_emu_io_ok, priv_emu_io_pwrite_exact(), emu_presentation_workspace_t::scratch, emu_presentation_workspace_t::scratch_bytes, emu_io_result_t::status, and emu_presentation_workspace_t::surface_bytes.

◆ emu_presentation_write()

bool emu_presentation_write	(	emu_presentation_workspace_t *	workspace,
		size_t	offset,
		const void *	bytes,
		size_t	count )

Write exact RGB565 bytes at a checked surface offset.

Write exact rgb565 bytes at a checked surface offset; this step is contained within the emu presentation model and uses bounded caller or module-owned storage.

Parameters

[in,out]	workspace	Caller-owned workspace used by the operation.
[in]	offset	Byte or register offset at which processing begins.
[in]	bytes	Byte storage transferred by the operation.
[in]	count	Number of elements or bytes to process.

Returns: The emu presentation write result produced by the emu presentation model.

Return values

true	The emu presentation write condition holds or completed successfully; false otherwise.

Precondition: Arguments satisfy the ranges documented for emu presentation write.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu presentation model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 326 of file emu_presentation.c.

References emu_presentation_workspace_t::fd, k_emu_io_ok, priv_emu_io_pwrite_exact(), emu_io_result_t::status, and emu_presentation_workspace_t::surface_bytes.

Referenced by emu_presentation_fill(), and internal_write_rows().

◆ internal_add()

RA8_INTERNAL bool internal_add	(	size_t	left,
		size_t	right,
		size_t *	result )

static

Checked size addition.

Checked size addition; this step is contained within the emu presentation model and uses bounded caller or module-owned storage.

Parameters

[in]	left	Left input used by the operation.
[in]	right	Right input used by the operation.
[out]	result	Storage receiving the computed operation result.

Returns: The add result produced by the emu presentation model.

Return values

true	The add condition holds or completed successfully; false otherwise.

Precondition: Arguments satisfy the ranges documented for add.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu presentation model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 116 of file emu_presentation.c.

References RA8_INTERNAL.

Referenced by internal_plan().

◆ internal_anonymous_fd()

RA8_INTERNAL int internal_anonymous_fd	(	size_t	size,
		int *	os_error )

static

Create, unlink, and exactly size one anonymous temporary descriptor.

Create, unlink, and exactly size one anonymous temporary descriptor; this step is contained within the emu presentation model and uses bounded caller or module-owned storage.

Parameters

[in]	size	Size of the requested region or access in bytes.
[out]	os_error	Storage receiving the host error code on failure.

Returns: The anonymous descriptor result produced by the emu presentation model.

Return values

value The operation-specific anonymous descriptor value.

Precondition: Arguments satisfy the ranges documented for anonymous descriptor.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu presentation model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 42 of file emu_presentation.c.

References RA8_INTERNAL.

Referenced by emu_presentation_open(), and emu_presentation_snapshot().

◆ internal_multiply()

RA8_INTERNAL bool internal_multiply	(	size_t	left,
		size_t	right,
		size_t *	result )

static

Checked size multiplication.

Checked size multiplication; this step is contained within the emu presentation model and uses bounded caller or module-owned storage.

Parameters

[in]	left	Left input used by the operation.
[in]	right	Right input used by the operation.
[out]	result	Storage receiving the computed operation result.

Returns: The multiply result produced by the emu presentation model.

Return values

true	The multiply condition holds or completed successfully; false otherwise.

Precondition: Arguments satisfy the ranges documented for multiply.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu presentation model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 138 of file emu_presentation.c.

References RA8_INTERNAL.

Referenced by internal_plan().

◆ internal_plan()

RA8_INTERNAL emu_presentation_status_t internal_plan	(	const emu_presentation_spec_t *	spec,
		emu_presentation_plan_t *	plan )

static

Compute all checked geometry and storage values.

Compute all checked geometry and storage values; this step is contained within the emu presentation model and uses bounded caller or module-owned storage.

Parameters

[in]	spec	Spec input used by the operation.
[in,out]	plan	Plan state or storage updated in place by the operation.

Returns: The plan result produced by the emu presentation model.

Return values

value The operation-specific plan value.

Precondition: Arguments satisfy the ranges documented for plan.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu presentation model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 176 of file emu_presentation.c.

References emu_presentation_spec_t::active, internal_add(), internal_multiply(), internal_rotation_valid(), k_board_overlay_min_height_px, k_board_overlay_sidebar_width_px, k_emu_presentation_invalid, k_emu_presentation_max_panel_px, k_emu_presentation_ok, k_emu_presentation_overflow, k_emu_presentation_tile_px, k_rotate_270, k_rotate_90, emu_presentation_spec_t::panel_height, emu_presentation_spec_t::panel_width, RA8_INTERNAL, and emu_presentation_spec_t::rotate_deg.

Referenced by emu_presentation_open(), and emu_presentation_requirements().

◆ internal_result()

RA8_INTERNAL emu_presentation_result_t internal_result	(	emu_presentation_status_t	status,
		size_t	surface,
		size_t	required_scratch,
		size_t	supplied_scratch,
		int	os_error )

static

Construct a complete operation result.

Construct a complete operation result; this step is contained within the emu presentation model and uses bounded caller or module-owned storage.

Parameters

[in]	status	Status value consumed or published by the operation.
[in]	surface	Descriptor-backed presentation surface to access.
[in]	required_scratch	Required scratch input used by the operation.
[in]	supplied_scratch	Supplied scratch input used by the operation.
[in]	os_error	Storage receiving the host error code on failure.

Returns: The result result produced by the emu presentation model.

Return values

value The operation-specific result value.

Precondition: Arguments satisfy the ranges documented for result.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu presentation model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 90 of file emu_presentation.c.

References RA8_INTERNAL.

Referenced by emu_presentation_open(), and emu_presentation_requirements().

◆ internal_rotation_valid()

RA8_INTERNAL bool internal_rotation_valid ( uint32_t rotation )

static

True for one supported clockwise rotation.

True for one supported clockwise rotation; this step is contained within the emu presentation model and uses bounded caller or module-owned storage.

Parameters

[in] rotation Rotation input used by the operation.

Returns: The rotation valid result produced by the emu presentation model.

Return values

true	The rotation valid condition holds or completed successfully; false otherwise.

Precondition: Arguments satisfy the ranges documented for rotation valid.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu presentation model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 158 of file emu_presentation.c.

References k_rotate_0, k_rotate_180, k_rotate_270, k_rotate_90, and RA8_INTERNAL.

Referenced by internal_plan().

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ presentation_invariant_t

Function Documentation

◆ emu_presentation_close()

◆ emu_presentation_fill()

◆ emu_presentation_open()

◆ emu_presentation_read()

◆ emu_presentation_requirements()

◆ emu_presentation_snapshot()

◆ emu_presentation_write()

◆ internal_add()

◆ internal_anonymous_fd()

◆ internal_multiply()

◆ internal_plan()

◆ internal_result()

◆ internal_rotation_valid()