emu_args.c File Reference

CLI parsing implementation (see emu_args.h). More...

#include "emu_args.h"
#include <ctype.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "board_periph_eink.h"
#include "board_periph_modem.h"
#include "board_periph_sd.h"
#include "emu_host_io_internal.h"
#include "emu_seams.h"
#include "emu_view.h"

Include dependency graph for emu_args.c:

Go to the source code of this file.

Functions
static void	internal_args_print_usage (void)
	Print the ra8_emulator CLI usage text to injected error sink.
static void	internal_args_defaults (const char *elf_path, emu_args_t *out)
	Seed the parsed-args struct with every option's default.
static bool	internal_args_try_mode (int argc, char **argv, int *i, emu_args_t *out)
	Parse the mode / core / device / attach-flag options.
static bool	internal_args_try_display (int argc, char **argv, int *i, emu_args_t *out)
	Parse the display / output options.
static bool	internal_args_try_input (int argc, char **argv, int *i, emu_args_t *out)
	Parse the input-injection options.
static void	internal_args_attach_blank_sd (const char *spec)
	Parse a --sd-new size spec and attach a blank formatted card.
static bool	internal_args_try_sd (int argc, char **argv, int *i, emu_args_t *out)
	Parse the microSD options.
static bool	internal_args_try_sym (int argc, char **argv, int *i, emu_args_t *out)
	Parse the symbol-probe options.
static bool	internal_args_try_control (int argc, char **argv, int *i, emu_args_t *out)
	Parse the button / battery / reboot run-control options.
bool	emu_args_parse (int argc, char **argv, emu_args_t *out)
	Parse the ra8_emulator command line into out (or print usage).

Detailed Description

CLI parsing implementation (see emu_args.h).

The usage text and the option-decoding loop – moved verbatim out of the ra8_emulator main translation unit. The contract lives on the declaration of emu_args_parse() in emu_args.h.

Copyright

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

Since

0.1.0

Definition in file emu_args.c.

Function Documentation

emu_args_parse()

bool emu_args_parse	(	int	argc,
		char **	argv,
		emu_args_t *	out )

Parse the ra8_emulator command line into out (or print usage).

With no firmware argument the full usage text is printed to injected error sink and false is returned (the caller exits 2). Otherwise the option loop decodes argv[2..] into out with the original loop's exact semantics, including the parse-time side effects: –sd / –sd-new attach the SD model, –eink / –modem attach their device models, –fast-sd enables the block seam, and –low-power / –primary-core set the core-model knobs.

Parameters

[in]	argc	Argument count from main().
[in]	argv	Argument vector from main(); strings are aliased by out.
[out]	out	Receives every decoded option (fully overwritten).

Returns

Whether a firmware path was supplied and the parse ran.

Return values

true	out is populated; parse-time attachments are in effect.
false	No firmware argument; usage was printed, nothing decoded.

Precondition

argv has argc entries that outlive the run (main's argv).

out is non-null.

Postcondition

On true, out->elf_path is argv[1] and all fields hold their defaults or decoded values.

On false, injected error sink carries the usage text and out is untouched.

Note

Not thread-safe; call once from main() before setup.

See also

emu_run_and_report() Consumes the values via emu_run_cfg_t.

Since

0.1.0

Definition at line 485 of file emu_args.c.

References internal_args_defaults(), internal_args_print_usage(), internal_args_try_control(), internal_args_try_display(), internal_args_try_input(), internal_args_try_mode(), internal_args_try_sd(), and internal_args_try_sym().

Referenced by main().

internal_args_attach_blank_sd()

void internal_args_attach_blank_sd ( const char * spec )

static

Parse a --sd-new size spec and attach a blank formatted card.

The spec is <N>[k|m|g|t][:fat16|fat32]. A bare number is MiB; a k/m/g/t suffix sets the unit (so "30g" is 30 GiB). The FAT flavour defaults by size the way a real SD card is shipped (FAT32 at or above k_fat32_min_mib), because FAT16 cannot address a multi-GB card; an explicit :fat16 / :fat32 overrides that.

Parameters

[in]

spec

Size specification text from the command line.

Precondition

spec is a NUL-terminated argument.

The SD model has no card attached yet.

Postcondition

A card is attached only when the size is non-zero and within the 32-bit sector count FAT can address.

An over-large request is diagnosed on injected error sink and attaches nothing.

Note

Not thread-safe; argument parsing runs once at startup.

Since

0.1.0

Definition at line 315 of file emu_args.c.

References board_sd_attach_blank(), k_bytes_per_sector, k_fat32_min_mib, k_sd_u32_max, k_sectors_per_mib, k_size_kib, k_strtol_base10, priv_emu_io_errf(), RA8_INTERNAL, strchr(), and strstr().

Referenced by internal_args_try_sd().

internal_args_defaults()

void internal_args_defaults ( const char * elf_path, emu_args_t * out )

static

Seed the parsed-args struct with every option's default.

Zero-initializes out (so all flags / counts / string pointers are false / 0 / NULL) then sets the non-zero defaults: the ELF path, the unset sentinels (-1 for click / battery), the default panel size, and the RA8D2 device. The option parsers overwrite only the fields their flags set.

Parameters

[in]	elf_path	The firmware path from argv[1].
[out]	out	The struct to seed.

Returns

void

Precondition

elf_path and out are non-NULL.

The caller has verified argc >= 2.

Postcondition

out holds every field's documented default.

out->elf_path == elf_path.

Note

Not thread-safe; single-threaded CLI setup.

Since

0.1.0

Definition at line 110 of file emu_args.c.

References emu_args_t::battery_soc, emu_args_t::click_x, emu_args_t::click_y, emu_args_t::elf_path, emu_args_t::emu_device, k_board_device_ra8d2, k_rotate_0, k_view_default_h, k_view_default_w, RA8_INTERNAL, emu_args_t::rotate_deg, emu_args_t::view_h, and emu_args_t::view_w.

Referenced by emu_args_parse().

internal_args_print_usage()

void internal_args_print_usage ( void )

static

Print the ra8_emulator CLI usage text to injected error sink.

The full option reference, printed when ra8_emulator is invoked without a firmware path. Text is verbatim from the pre-split parser.

Returns

void

Precondition

injected error sink is writable.

The caller is about to return a parse failure.

Postcondition

The usage text has been written to injected error sink.

No parse state is produced.

Note

Not thread-safe; single-threaded CLI setup.

Since

0.1.0

Definition at line 43 of file emu_args.c.

References priv_emu_io_err_text(), and RA8_INTERNAL.

Referenced by emu_args_parse().

internal_args_try_control()

bool internal_args_try_control ( int argc, char ** argv, int * i, emu_args_t * out )

static

Parse the button / battery / reboot run-control options.

Handles –button, –battery, –charge and –reboot. –battery and –charge both latch battery_opt. Exact-match strncmp keeps the group order-independent.

Parameters

[in]	argc	The argument count.
[in]	argv	The argument vector.
[in,out]	i	Index of the current option; advanced past consumed values.
[in,out]	out	The struct to update.

Returns

true when the option at *i belonged to this group.

Return values

true	The option was recognized and applied.
false	Not one of this group's options; try the next parser.

Precondition

argv, i and out are non-NULL and *i is in [2, argc).

out has been seeded by internal_args_defaults.

Postcondition

On true, out and *i reflect the consumed option.

Note

Not thread-safe; single-threaded CLI setup.

Since

0.1.0

Postcondition

Ownership of caller-supplied storage is unchanged.

Definition at line 463 of file emu_args.c.

References emu_args_t::battery_charging, emu_args_t::battery_opt, emu_args_t::battery_soc, emu_args_t::button_press, k_strtol_base10, RA8_INTERNAL, emu_args_t::reboot_count, and strncmp().

Referenced by emu_args_parse().

internal_args_try_display()

bool internal_args_try_display ( int argc, char ** argv, int * i, emu_args_t * out )

static

Parse the display / output options.

Handles –ppm / –record-secs / –record / –rotate / –panel / –size. Exact-match strncmp keeps the group order-independent.

Parameters

[in]	argc	The argument count.
[in]	argv	The argument vector.
[in,out]	i	Index of the current option; advanced past consumed values.
[in,out]	out	The struct to update.

Returns

true when the option at *i belonged to this group.

Return values

true	The option was recognized and applied.
false	Not one of this group's options; try the next parser.

Precondition

argv, i and out are non-NULL and *i is in [2, argc).

out has been seeded by internal_args_defaults.

Postcondition

On true, out and *i reflect the consumed option.

Note

Not thread-safe; single-threaded CLI setup.

Since

0.1.0

Postcondition

Ownership of caller-supplied storage is unchanged.

Definition at line 202 of file emu_args.c.

References k_max_panel_px, k_rotate_180, k_rotate_270, k_rotate_90, k_strtol_base10, emu_args_t::panel_path, emu_args_t::ppm_path, RA8_INTERNAL, emu_args_t::record_dir, emu_args_t::record_secs, emu_args_t::rotate_deg, emu_args_t::size_set, strncmp(), emu_args_t::view_h, and emu_args_t::view_w.

Referenced by emu_args_parse().

internal_args_try_input()

bool internal_args_try_input ( int argc, char ** argv, int * i, emu_args_t * out )

static

Parse the input-injection options.

Handles –ns / –input / –keys / –touch-seq / –usb-in / –click. Exact-match strncmp keeps the group order-independent.

Parameters

[in]	argc	The argument count.
[in]	argv	The argument vector.
[in,out]	i	Index of the current option; advanced past consumed values.
[in,out]	out	The struct to update.

Returns

true when the option at *i belonged to this group.

Return values

true	The option was recognized and applied.
false	Not one of this group's options; try the next parser.

Precondition

argv, i and out are non-NULL and *i is in [2, argc).

out has been seeded by internal_args_defaults.

Postcondition

On true, out and *i reflect the consumed option.

Note

Not thread-safe; single-threaded CLI setup.

Since

0.1.0

Postcondition

Ownership of caller-supplied storage is unchanged.

Definition at line 262 of file emu_args.c.

References emu_args_t::click_x, emu_args_t::click_y, emu_args_t::input_str, k_strtol_base10, emu_args_t::keys_str, emu_args_t::ns_elf_path, RA8_INTERNAL, strncmp(), emu_args_t::touch_seq_str, emu_args_t::usb_in_str, and emu_args_t::want_click.

Referenced by emu_args_parse().

internal_args_try_mode()

bool internal_args_try_mode ( int argc, char ** argv, int * i, emu_args_t * out )

static

Parse the mode / core / device / attach-flag options.

Handles –view / –usbhs-loop / –trace / –low-power / –fast-sd / –eink / –modem (no-value flags and side-effect attaches) plus the –primary-core and –device value options. Exact-match strncmp, so the group is order-independent relative to the other parsers.

Parameters

[in]	argc	The argument count.
[in]	argv	The argument vector.
[in,out]	i	Index of the current option; advanced past consumed values.
[in,out]	out	The struct to update.

Returns

true when the option at *i belonged to this group.

Return values

true	The option was recognized and applied.
false	Not one of this group's options; try the next parser.

Precondition

argv, i and out are non-NULL and *i is in [2, argc).

out has been seeded by internal_args_defaults.

Postcondition

On true, out and *i reflect the consumed option.

Note

Not thread-safe; single-threaded CLI setup.

Since

0.1.0

Postcondition

Ownership of caller-supplied storage is unchanged.

Definition at line 145 of file emu_args.c.

References board_eink_attach(), board_modem_attach(), emu_args_t::emu_device, emu_fast_sd_enable(), emu_set_low_power(), emu_set_primary_core(), k_board_device_ra8d2, k_board_device_ra8p1, k_core_m33, k_core_m85, RA8_INTERNAL, strncmp(), emu_args_t::usbhs_loop, emu_args_t::want_trace, and emu_args_t::want_view.

Referenced by emu_args_parse().

internal_args_try_sd()

bool internal_args_try_sd ( int argc, char ** argv, int * i, emu_args_t * out )

static

Parse the microSD options.

Handles –sd (attach an image), –sd-new (create + attach a blank formatted card, decoding the N[k|m|g|t][:fat16|fat32] spec) and –save-sd. Exact-match strncmp keeps the group order-independent.

Parameters

[in]	argc	The argument count.
[in]	argv	The argument vector.
[in,out]	i	Index of the current option; advanced past consumed values.
[in,out]	out	The struct to update.

Returns

true when the option at *i belonged to this group.

Return values

true	The option was recognized and applied.
false	Not one of this group's options; try the next parser.

Precondition

argv, i and out are non-NULL and *i is in [2, argc).

out has been seeded by internal_args_defaults.

Postcondition

On true, out / *i and any SD attach reflect the consumed option.

Note

Not thread-safe; single-threaded CLI setup.

Since

0.1.0

Postcondition

Ownership of caller-supplied storage is unchanged.

Definition at line 368 of file emu_args.c.

References board_sd_attach(), internal_args_attach_blank_sd(), RA8_INTERNAL, emu_args_t::save_sd_path, and strncmp().

Referenced by emu_args_parse().

internal_args_try_sym()

bool internal_args_try_sym ( int argc, char ** argv, int * i, emu_args_t * out )

static

Parse the symbol-probe options.

Handles –dump-sym (append a global to read after the run), –stop-sym (watch a global + threshold) and –trace-sym (log a function's entries). The dump / trace lists cap at their array bounds. Exact-match strncmp keeps the group order-independent.

Parameters

[in]	argc	The argument count.
[in]	argv	The argument vector.
[in,out]	i	Index of the current option; advanced past consumed values.
[in,out]	out	The struct to update.

Returns

true when the option at *i belonged to this group.

Return values

true	The option was recognized and applied.
false	Not one of this group's options; try the next parser.

Precondition

argv, i and out are non-NULL and *i is in [2, argc).

out has been seeded by internal_args_defaults.

Postcondition

On true, out and *i reflect the consumed option.

Note

Not thread-safe; single-threaded CLI setup.

Since

0.1.0

Postcondition

Ownership of caller-supplied storage is unchanged.

Definition at line 412 of file emu_args.c.

References emu_args_t::dump_sym_n, emu_args_t::dump_sym_names, k_dump_sym_max, k_strtol_base10, k_trace_sym_max, RA8_INTERNAL, emu_args_t::stop_sym_name, emu_args_t::stop_sym_thresh, strncmp(), emu_args_t::trace_sym_n, and emu_args_t::trace_sym_names.

Referenced by emu_args_parse().