emu_host_io_internal.h File Reference

Bounded raw-descriptor I/O seam for the RA8 emulator. More...

#include <stdarg.h>
#include <stddef.h>
#include <stdint.h>
#include <sys/types.h>
#include "ra8_attributes.h"

Include dependency graph for emu_host_io_internal.h:

Go to the source code of this file.

Data Structures
struct	emu_io_result_t
	Complete, caller-visible result of a raw host-I/O operation. More...
struct	emu_io_ops_t
	Injectable raw operations used by the exact-transfer loops. More...
struct	emu_io_file_t
	Raw descriptor plus its stat-derived byte length. More...
struct	emu_io_txn_t
	Sibling temporary file used for failure-atomic publication. More...

Enumerations
enum	emu_io_status_t : uint8_t {   k_emu_io_ok = 0U ,   k_emu_io_invalid ,   k_emu_io_truncated ,   k_emu_io_eof ,   k_emu_io_error }
	Result status for an emulator host-I/O operation. More...

Functions
void	priv_emu_io_configure (int out_fd, int err_fd, const emu_io_ops_t *ops)
	Inject process output descriptors and optional raw transfer hooks.
emu_io_result_t	priv_emu_io_read_exact (int fd, void *buf, size_t count)
	Read exactly count sequential bytes or report EOF/fault progress.
emu_io_result_t	priv_emu_io_write_exact (int fd, const void *buf, size_t count)
	Write exactly count sequential bytes or report fault progress.
emu_io_result_t	priv_emu_io_pread_exact (int fd, void *buf, size_t count, off_t offset)
	Read exactly count bytes at offset without changing the cursor.
emu_io_result_t	priv_emu_io_pwrite_exact (int fd, const void *buf, size_t count, off_t offset)
	Write exactly count bytes at offset without changing the cursor.
emu_io_result_t	priv_emu_io_out_text (const char *text)
	Write a NUL-terminated literal to the injected output descriptor.
emu_io_result_t	priv_emu_io_err_text (const char *text)
	Write a NUL-terminated literal to the injected error descriptor.
emu_io_result_t	priv_emu_io_err_bytes (const void *bytes, size_t length)
	Write an exact non-NUL-terminated byte fragment to the error sink.
emu_io_result_t	priv_emu_io_outf (const char *format,...)
	Format bounded text and write it to the injected output descriptor.
emu_io_result_t	priv_emu_io_errf (const char *format,...)
	Format bounded text and write it to the injected error descriptor.
emu_io_result_t	priv_emu_io_file_text (int fd, const char *text)
	Write a NUL-terminated literal to an explicit raw descriptor.
emu_io_result_t	priv_emu_io_file_char (int fd, char value)
	Write one byte to an explicit raw descriptor.
emu_io_result_t	priv_emu_io_filef (int fd, const char *format,...)
	Format bounded text and write it to an explicit raw descriptor.
emu_io_result_t	priv_emu_io_open_read (const char *path, emu_io_file_t *file)
	Open and stat a regular file for bounded raw reading.
emu_io_result_t	priv_emu_io_close (emu_io_file_t *file)
	Close and invalidate an owned raw file descriptor.
emu_io_result_t	priv_emu_io_txn_begin (const char *path, emu_io_txn_t *txn)
	Create a sibling temporary output for failure-atomic publication.
emu_io_result_t	priv_emu_io_txn_commit (emu_io_txn_t *txn)
	Sync, close, and atomically rename an active sibling transaction.
void	priv_emu_io_txn_abort (emu_io_txn_t *txn)
	Close and unlink an active sibling transaction without publication.

Detailed Description

Bounded raw-descriptor I/O seam for the RA8 emulator.

Defines the private result, operation-injection, exact-transfer, formatting, file-open, and sibling-transaction contracts used by the host tool.

Copyright

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

Since

0.1.0

Definition in file emu_host_io_internal.h.

Enumeration Type Documentation

emu_io_status_t

enum emu_io_status_t : uint8_t

Result status for an emulator host-I/O operation.

Enumerator
k_emu_io_ok	The complete operation succeeded.
k_emu_io_invalid	A pointer, descriptor, size, or path was invalid.
k_emu_io_truncated	Formatted text exceeded the bounded scratch buffer.
k_emu_io_eof	Input ended before the requested byte count.
k_emu_io_error	A host syscall failed; os_error carries errno.

Definition at line 22 of file emu_host_io_internal.h.

Function Documentation

priv_emu_io_close()

emu_io_result_t priv_emu_io_close ( emu_io_file_t * file )

nodiscard

Close and invalidate an owned raw file descriptor.

Definition at line 415 of file emu_host_io.c.

References internal_result(), k_emu_io_error, k_emu_io_invalid, and k_emu_io_ok.

Referenced by board_sd_attach(), load_panel(), and priv_emu_elf_source_close().

priv_emu_io_configure()

void priv_emu_io_configure	(	int	out_fd,
		int	err_fd,
		const emu_io_ops_t *	ops )

Inject process output descriptors and optional raw transfer hooks.

Selects composition-owned destinations and production or test raw operations.

Parameters

[in]	out_fd	Descriptor used by output-sink calls.
[in]	err_fd	Descriptor used by error-sink calls.
[in]	ops	Complete operation table, or nullptr for production syscalls.

Precondition

out_fd and err_fd are valid for their intended calls.

Non-null ops supplies all four callbacks.

Postcondition

Subsequent sink calls use the supplied descriptors.

Subsequent transfer calls use ops or the production table.

Note

Process-wide composition step; not thread-safe with active transfers.

Since

0.1.0

Definition at line 140 of file emu_host_io.c.

References s_err_fd, s_k_default_ops, s_ops, and s_out_fd.

Referenced by main().

priv_emu_io_err_bytes()

emu_io_result_t priv_emu_io_err_bytes ( const void * bytes, size_t length )

nodiscard

Write an exact non-NUL-terminated byte fragment to the error sink.

Definition at line 350 of file emu_host_io.c.

References priv_emu_io_write_exact(), and s_err_fd.

Referenced by internal_prof_name_chunk().

priv_emu_io_err_text()

emu_io_result_t priv_emu_io_err_text ( const char * text )

nodiscard

Write a NUL-terminated literal to the injected error descriptor.

Definition at line 344 of file emu_host_io.c.

References internal_result(), k_emu_io_invalid, priv_emu_io_write_exact(), s_err_fd, and strlen().

Referenced by internal_args_print_usage(), internal_prof_print_incl_self_table(), internal_prof_print_phase(), and prof_report().

priv_emu_io_errf()

emu_io_result_t priv_emu_io_errf ( const char * format, ... )

nodiscard

Format bounded text and write it to the injected error descriptor.

Definition at line 364 of file emu_host_io.c.

References internal_vformat(), and s_err_fd.

Referenced by board_eink_report(), board_modem_report(), board_net_on_tx(), board_net_report(), board_periph_icu_raise_event(), board_periph_note_irq_taken(), board_periph_register_block(), board_periph_sci_feed_rx(), board_sd_attach(), board_sd_attach_blank(), board_sd_save(), board_usb_bridge_dcp_in_take(), board_usb_host_report(), board_usb_host_write(), board_usb_report(), div0_patch_sites(), div0_seam_install(), emu_mmio_print_bgc_and_table(), emu_mmio_print_counts(), emu_tz_install(), fast_sd_seam_install(), internal_adc_report(), internal_adc_write(), internal_args_attach_blank_sd(), internal_bkup_report(), internal_cac_report(), internal_canfd_loopback_deliver(), internal_canfd_report(), internal_ceu_do_capture(), internal_ceu_report(), internal_cpu1_engine_init(), internal_crc_report(), internal_dac_report(), internal_dac_write(), internal_div0_scan_segment(), internal_dmac_report(), internal_dmac_run_transfer(), internal_doc_report(), internal_drw_report(), internal_dtc_report(), internal_eth_report(), internal_glcdc_report(), internal_gptp_report(), internal_guard_setup_record(), internal_i3c_report(), internal_install_seg_hooks(), internal_ipc_report(), internal_ipc_write(), internal_lvd_report(), internal_main_apply_button_battery(), internal_main_arm_touch_seq(), internal_main_feed_inputs(), internal_main_load_ns(), internal_main_load_primary(), internal_main_open_engine(), internal_main_open_memory(), internal_main_open_presentation(), internal_main_reset_vector(), internal_main_resolve_symbols(), internal_map_periph_mmio(), internal_map_regions(), internal_mram_report(), internal_mstp_report(), internal_net_rx_icmp(), internal_net_rx_tcp(), internal_net_tcp_on_estab(), internal_npu_report(), internal_on_sym_trace(), internal_on_unmapped(), internal_pdctr_report(), internal_pdm_report(), internal_poeg_report(), internal_port_report(), internal_port_trace_leds(), internal_prcr_report(), internal_prof_print_boot_timeline(), internal_prof_print_incl_self_table(), internal_prof_print_phase(), internal_report_created(), internal_report_irqs(), internal_report_unhandled_insn(), internal_reset_report(), internal_riic_report(), internal_rtc_raise_events(), internal_rtc_report(), internal_rtt_report(), internal_run_classify_click(), internal_run_open_view(), internal_run_print_dump_syms(), internal_run_print_sd_summary(), internal_run_print_stop_summary(), internal_run_print_verdict(), internal_sci_report(), internal_sdhi_report(), internal_spi_report(), internal_sram_report(), internal_ssie_report(), internal_stream_segment(), internal_timer_report(), internal_ulpt_report(), internal_ulpt_tick_channel(), internal_usb_hid_decode_report(), internal_usbhs_do_setup(), internal_usbhs_report(), internal_wdt_report(), internal_xspi_report(), load_elf(), load_panel(), long_shift_seam_install(), priv_riic_devices_report(), priv_run_hold_view(), priv_run_write_outputs(), priv_usb_log_line(), prof_load(), prof_report(), sym_trace_install(), usbh_seam_install(), and warm_reboot().

priv_emu_io_file_char()

emu_io_result_t priv_emu_io_file_char ( int fd, char value )

nodiscard

Write one byte to an explicit raw descriptor.

Definition at line 379 of file emu_host_io.c.

References priv_emu_io_write_exact().

Referenced by internal_prof_js_frames(), internal_prof_json_samples(), and internal_prof_name_chunk().

priv_emu_io_file_text()

emu_io_result_t priv_emu_io_file_text ( int fd, const char * text )

nodiscard

Write a NUL-terminated literal to an explicit raw descriptor.

Definition at line 373 of file emu_host_io.c.

References internal_result(), k_emu_io_invalid, priv_emu_io_write_exact(), and strlen().

Referenced by internal_prof_js_frames(), internal_prof_json_frames(), internal_prof_write_html(), and internal_prof_write_speedscope().

priv_emu_io_filef()

emu_io_result_t priv_emu_io_filef ( int fd, const char * format, ... )

nodiscard

Format bounded text and write it to an explicit raw descriptor.

Definition at line 384 of file emu_host_io.c.

References internal_vformat().

Referenced by internal_prof_json_samples(), internal_prof_json_weights(), internal_prof_write_html(), internal_prof_write_speedscope(), and write_ppm().

priv_emu_io_open_read()

emu_io_result_t priv_emu_io_open_read ( const char * path, emu_io_file_t * file )

nodiscard

Open and stat a regular file for bounded raw reading.

Definition at line 393 of file emu_host_io.c.

References internal_result(), k_emu_io_error, k_emu_io_invalid, k_emu_io_ok, and O_CLOEXEC.

Referenced by board_sd_attach(), load_panel(), and priv_emu_elf_source_open().

priv_emu_io_out_text()

emu_io_result_t priv_emu_io_out_text ( const char * text )

nodiscard

Write a NUL-terminated literal to the injected output descriptor.

Definition at line 338 of file emu_host_io.c.

References internal_result(), k_emu_io_invalid, priv_emu_io_write_exact(), s_out_fd, and strlen().

priv_emu_io_outf()

emu_io_result_t priv_emu_io_outf ( const char * format, ... )

nodiscard

Format bounded text and write it to the injected output descriptor.

Definition at line 355 of file emu_host_io.c.

References internal_vformat(), and s_out_fd.

Referenced by console_flush_line(), internal_on_itm_stim_write(), and internal_rtt_line_feed().

priv_emu_io_pread_exact()

emu_io_result_t priv_emu_io_pread_exact ( int fd, void * buf, size_t count, off_t offset )

nodiscard

Read exactly count bytes at offset without changing the cursor.

Definition at line 294 of file emu_host_io.c.

References internal_pread_adapter(), and internal_transfer().

Referenced by board_view_read_rgb888_fd(), emu_presentation_read(), internal_copy_bytes(), priv_board_sd_storage_read(), and priv_emu_elf_read().

priv_emu_io_pwrite_exact()

emu_io_result_t priv_emu_io_pwrite_exact ( int fd, const void * buf, size_t count, off_t offset )

nodiscard

Write exactly count bytes at offset without changing the cursor.

Definition at line 299 of file emu_host_io.c.

References internal_pwrite_adapter(), and internal_transfer().

Referenced by emu_presentation_snapshot(), emu_presentation_write(), internal_copy_bytes(), internal_write_sector(), and priv_board_sd_storage_write().

priv_emu_io_read_exact()

emu_io_result_t priv_emu_io_read_exact ( int fd, void * buf, size_t count )

nodiscard

Read exactly count sequential bytes or report EOF/fault progress.

Definition at line 284 of file emu_host_io.c.

References internal_read_adapter(), and internal_transfer().

Referenced by load_panel().

priv_emu_io_txn_abort()

void priv_emu_io_txn_abort

(

emu_io_txn_t *

txn

)

Close and unlink an active sibling transaction without publication.

Releases any temporary descriptor/path while preserving the final target.

Parameters

[in,out]

txn

Transaction to abandon; nullptr is accepted.

Precondition

Non-null txn was zero-initialised or passed to priv_emu_io_txn_begin().

The caller no longer intends to commit txn.

Postcondition

Any owned descriptor is closed and set to -1.

Any named sibling temporary is unlinked and cleared.

Note

Does not modify the final target path.

Since

0.1.0

Definition at line 467 of file emu_host_io.c.

References emu_io_txn_t::fd, and emu_io_txn_t::temp.

Referenced by board_sd_save(), internal_prof_write_html(), internal_prof_write_speedscope(), and write_ppm().

priv_emu_io_txn_begin()

emu_io_result_t priv_emu_io_txn_begin ( const char * path, emu_io_txn_t * txn )

nodiscard

Create a sibling temporary output for failure-atomic publication.

Definition at line 427 of file emu_host_io.c.

References emu_io_txn_t::fd, emu_io_txn_t::final, internal_result(), k_emu_io_error, k_emu_io_invalid, k_emu_io_ok, k_emu_io_truncated, and emu_io_txn_t::temp.

Referenced by board_sd_save(), internal_prof_write_html(), internal_prof_write_speedscope(), and write_ppm().

priv_emu_io_txn_commit()

emu_io_result_t priv_emu_io_txn_commit ( emu_io_txn_t * txn )

nodiscard

Sync, close, and atomically rename an active sibling transaction.

Definition at line 447 of file emu_host_io.c.

References emu_io_txn_t::fd, emu_io_txn_t::final, internal_result(), k_emu_io_error, k_emu_io_invalid, k_emu_io_ok, and emu_io_txn_t::temp.

Referenced by board_sd_save(), internal_prof_write_html(), internal_prof_write_speedscope(), and write_ppm().

priv_emu_io_write_exact()

emu_io_result_t priv_emu_io_write_exact ( int fd, const void * buf, size_t count )

nodiscard

Write exactly count sequential bytes or report fault progress.

Definition at line 289 of file emu_host_io.c.

References internal_transfer(), and internal_write_adapter().

Referenced by internal_vformat(), internal_write_ppm_pixels(), priv_emu_io_err_bytes(), priv_emu_io_err_text(), priv_emu_io_file_char(), priv_emu_io_file_text(), and priv_emu_io_out_text().