Allocation-free raw-descriptor ELF source ownership and bounded views. More...

#include <stdint.h>
#include "emu_elf.h"
#include "emu_elf_source_internal.h"
#include "emu_host_io_internal.h"

Include dependency graph for emu_elf_source.c:

Functions
static RA8_INTERNAL emu_elf_io_result_t	internal_elf_result (emu_elf_io_status_t status, uint64_t required, uint64_t supplied, int os_error)
	Construct one fully initialized ELF I/O result.
static RA8_INTERNAL emu_elf_io_result_t	internal_from_host (emu_io_result_t io, uint64_t required, uint64_t supplied)
	Translate a raw host-I/O result without losing progress metadata.
emu_elf_io_result_t	priv_emu_elf_source_open (const char path, emu_elf_source_t source)
	Open one regular ELF source without reading or allocating its bytes.
emu_elf_io_result_t	priv_emu_elf_source_close (emu_elf_source_t *source)
	Close and invalidate one independently owned ELF source.
emu_elf_io_result_t	priv_emu_elf_read (const emu_elf_source_t source, uint64_t offset, size_t required_bytes, void scratch, size_t supplied_bytes, emu_elf_view_t *view)
	Read one exact source range into caller-owned bounded scratch.

Detailed Description

Allocation-free raw-descriptor ELF source ownership and bounded views.

Each caller owns an independent descriptor context. Parsing code acquires only exact transient views in caller-provided scratch memory.

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

Since: 0.1.0

Definition in file emu_elf_source.c.

Function Documentation

◆ internal_elf_result()

RA8_INTERNAL emu_elf_io_result_t internal_elf_result	(	emu_elf_io_status_t	status,
		uint64_t	required,
		uint64_t	supplied,
		int	os_error )

static

Construct one fully initialized ELF I/O result.

Copies semantic status, exact byte counts, and captured errno by value.

Parameters

[in]	status	Semantic operation status.
[in]	required	Exact source or range byte requirement.
[in]	supplied	Caller-provided scratch bytes.
[in]	os_error	Captured host error, or zero.

Returns: Complete result value.

Return values

emu_elf_io_result_t A fully initialized result.

Precondition: status is a valid emu_elf_io_status_t.; Byte counts describe the current operation.

Postcondition: No caller or host state changes.; Every result field is initialized.

Note: Pure and thread-safe.

Since: 0.1.0

Definition at line 35 of file emu_elf_source.c.

Referenced by internal_from_host(), priv_emu_elf_read(), priv_emu_elf_source_close(), and priv_emu_elf_source_open().

◆ internal_from_host()

RA8_INTERNAL emu_elf_io_result_t internal_from_host	(	emu_io_result_t	io,
		uint64_t	required,
		uint64_t	supplied )

static

Translate a raw host-I/O result without losing progress metadata.

Maps raw invalid and EOF states while preserving host faults.

Parameters

[in]	io	Raw host operation result.
[in]	required	Exact ELF operation requirement.
[in]	supplied	Caller-provided scratch bytes.

Returns: Corresponding ELF invalid, EOF, or host-error result.

Return values

emu_elf_io_result_t The mapped result with exact byte metadata.

Precondition: io does not report success.; Byte counts describe the current operation.

Postcondition: No state changes.; Captured errno is retained for host errors.

Note: Pure and thread-safe.

Since: 0.1.0

Definition at line 59 of file emu_elf_source.c.

References internal_elf_result(), k_emu_elf_io_eof, k_emu_elf_io_error, k_emu_elf_io_invalid, k_emu_io_eof, and k_emu_io_invalid.

Referenced by priv_emu_elf_read(), priv_emu_elf_source_close(), and priv_emu_elf_source_open().

◆ priv_emu_elf_read()

emu_elf_io_result_t priv_emu_elf_read	(	const emu_elf_source_t *	source,
		uint64_t	offset,
		size_t	required_bytes,
		void *	scratch,
		size_t	supplied_bytes,
		emu_elf_view_t *	view )

nodiscard

Read one exact source range into caller-owned bounded scratch.

Parameters

[in]	source	Open immutable ELF source.
[in]	offset	First source byte to read.
[in]	required_bytes	Exact requested byte count.
[out]	scratch	Caller-owned destination.
[in]	supplied_bytes	Available destination bytes.
[out]	view	Receives the complete transient view on success.

Returns: Exact range, capacity, or transfer status.

Return values

k_emu_elf_io_ok	The view was published completely.
k_emu_elf_io_capacity	Required bytes exceed supplied bytes.

Precondition: scratch spans supplied_bytes writable bytes when nonzero.; source remains open through the operation.

Postcondition: Failure leaves view untouched.; Success publishes exactly required_bytes at offset.

Note: Failure may alter scratch bytes but never publishes a partial view.

Since: 0.1.0

Definition at line 99 of file emu_elf_source.c.

References emu_elf_source_t::fd, internal_elf_result(), internal_from_host(), k_emu_elf_io_capacity, k_emu_elf_io_eof, k_emu_elf_io_invalid, k_emu_elf_io_ok, k_emu_io_ok, emu_elf_source_t::length, priv_emu_io_pread_exact(), and emu_io_result_t::status.

Referenced by internal_div0_scan_segment(), internal_load_segment(), internal_long_shift_segment(), internal_program_table(), internal_stream_segment(), and internal_symbol_read().

◆ priv_emu_elf_source_close()

emu_elf_io_result_t priv_emu_elf_source_close ( emu_elf_source_t * source )

nodiscard

Close and invalidate one independently owned ELF source.

Parameters

[in,out] source Open source to close.

Returns: Exact close status.

Return values

k_emu_elf_io_ok	The descriptor was closed and invalidated.
k_emu_elf_io_invalid	`source` was null or already closed.

Precondition: source is null, closed, or owned by the caller.; No concurrent read is active through source.

Postcondition: A valid descriptor is invalidated even when close reports error.; Other source instances remain usable.

Note: Not safe during a concurrent read through the same source.

Since: 0.1.0

Definition at line 85 of file emu_elf_source.c.

References emu_elf_source_t::fd, internal_elf_result(), internal_from_host(), k_emu_elf_io_invalid, k_emu_elf_io_ok, k_emu_io_ok, emu_elf_source_t::length, priv_emu_io_close(), and emu_io_result_t::status.

Referenced by internal_main_load_images(), internal_main_load_ns(), internal_main_load_primary(), internal_main_run_loaded(), and priv_run_cleanup().

◆ priv_emu_elf_source_open()

emu_elf_io_result_t priv_emu_elf_source_open	(	const char *	path,
		emu_elf_source_t *	source )

nodiscard

Open one regular ELF source without reading or allocating its bytes.

Parameters

[in]	path	NUL-terminated source path.
[out]	source	Receives an independently owned descriptor on success.

Returns: Exact open result including the full source length.

Return values

k_emu_elf_io_ok	A regular source was published with its exact length.
k_emu_elf_io_error	The source could not be opened or stated.

Precondition: path and source are non-null.; source is not currently open.

Postcondition: Failure leaves source untouched and owns no descriptor.; Success leaves source open until priv_emu_elf_source_close.

Note: Distinct source objects have independent lifetimes.

Since: 0.1.0

Definition at line 70 of file emu_elf_source.c.

References internal_elf_result(), internal_from_host(), k_emu_elf_io_invalid, k_emu_elf_io_ok, k_emu_io_ok, emu_elf_source_t::length, priv_emu_io_open_read(), and emu_io_result_t::status.

Referenced by internal_main_load_ns(), and internal_main_load_primary().

Functions

Detailed Description

Function Documentation

◆ internal_elf_result()

◆ internal_from_host()

◆ priv_emu_elf_read()

◆ priv_emu_elf_source_close()

◆ priv_emu_elf_source_open()