emu_trace.h File Reference

Function-entry seam glue + the –trace-sym instrument. More...

#include <stdint.h>
#include <unicorn/unicorn.h>
#include "emu_elf.h"
#include "ra8_attributes.h"

Include dependency graph for emu_trace.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Enumerations
enum	emu_trace_cfg_t : uint32_t { k_trace_sym_max = 16U }
	Sizing for the –trace-sym instrument. More...

Functions
void	eth_hook_return (uc_engine *uc, uint32_t r0)
	Emulate "return r0;" from a hooked function: set R0, branch to LR.
void	eth_seam_hook (uc_engine *uc, const emu_elf_source_t *elf, const char *name, void *cb)
	Hook one symbol (if present) to cb; record it for the report.
void	sym_trace_install (uc_engine *uc, const emu_elf_source_t *elf, const char *const *names, uint32_t count)
	Install a --trace-sym entry hook for every requested symbol present.

Detailed Description

Function-entry seam glue + the –trace-sym instrument.

The shared "hook one ELF symbol's entry to a C callback" helpers every function-level seam builds on (emulate "return r0 to LR", install a UC_HOOK_CODE at a named symbol), plus the --trace-sym debugging instrument that logs each entry to a named function with its caller. The Ethernet frame seam that first introduced the helpers was retired once board_periph_eth modelled the R-Switch registers; the USB host-mode and fast-SD seams still ride them.

Split out of the ra8_emulator main translation unit; behaviour unchanged.

Copyright

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

Since

0.1.0

Definition in file emu_trace.h.

Enumeration Type Documentation

emu_trace_cfg_t

enum emu_trace_cfg_t : uint32_t

Sizing for the –trace-sym instrument.

Bounds both the CLI collection array and the installed hook handles, so a run can trace at most this many functions.

Invariant

The CLI parser and the installer share this bound.

See also

sym_trace_install() Consumes up to this many names.

Since

0.1.0

Enumerator
k_trace_sym_max	Max –trace-sym functions per run.

Definition at line 44 of file emu_trace.h.

Function Documentation

eth_hook_return()

void eth_hook_return	(	uc_engine *	uc,
		uint32_t	r0 )

Emulate "return r0;" from a hooked function: set R0, branch to LR.

Loads r0 into R0, moves PC to LR (Thumb bit dropped – the M-class core stays Thumb) and stops the engine so the chunked run loop relaunches from the returned PC (editing PC and continuing in-place corrupts Unicorn's block/Thumb state).

Parameters

[in,out]	uc	Unicorn engine stopped at a hooked function entry.
[in]	r0	The value the shadowed function "returns".

Returns

Nothing.

Precondition

uc sits at a function entry (LR holds the return address).

The caller is a UC_HOOK_CODE seam about to skip the real body.

Postcondition

R0/PC are set and the engine is stopped for relaunch.

Note

Not thread-safe; the emulator is single-threaded host-side.

See also

eth_seam_hook() Installs the seams that call this.

Since

0.1.0

Postcondition

Ownership of caller-supplied storage is unchanged.

Definition at line 32 of file emu_trace.c.

Referenced by internal_on_hmsc_enumerate(), internal_on_hmsc_ok(), internal_on_hmsc_read10(), internal_on_hmsc_read_capacity(), internal_on_hmsc_write10(), internal_on_sdmmc_read_block(), internal_on_usbh_bulk_in(), internal_on_usbh_control_xfer(), internal_on_usbh_line_state(), and internal_on_usbh_ok().

eth_seam_hook()

void eth_seam_hook	(	uc_engine *	uc,
		const emu_elf_source_t *	elf,
		const char *	name,
		void *	cb )

Hook one symbol (if present) to cb; record it for the report.

Resolves name from the ELF symbol table and installs a UC_HOOK_CODE at its entry; a missing symbol is silently skipped so a seam family can offer hooks for APIs the firmware may not link. Bounded by a fixed handle pool shared across all callers.

Parameters

[in,out]	uc	Unicorn engine.
[in]	elf	Open ELF source used for symbol resolution.
[in]	name	Symbol to hook.
[in]	cb	UC_HOOK_CODE callback to fire at the entry.

Returns

Nothing.

Precondition

elf remains open and valid for symbol resolution.

cb matches the UC_HOOK_CODE ABI.

Postcondition

On a resolved symbol one more entry hook is armed (pool permitting).

Note

Not thread-safe; call during single-threaded setup.

Since

0.1.0

Postcondition

Ownership of caller-supplied storage is unchanged.

< Max symbols the seam can hook across one run.

Definition at line 43 of file emu_trace.c.

References elf_sym_addr().

Referenced by usbh_seam_install().

sym_trace_install()

void sym_trace_install	(	uc_engine *	uc,
		const emu_elf_source_t *	elf,
		const char *const *	names,
		uint32_t	count )

Install a --trace-sym entry hook for every requested symbol present.

Parameters

[in,out]	uc	Active Unicorn engine.
[in]	elf	Open ELF source used for symbol resolution.
[in]	names	Symbol names from the CLI (stable for the run).
[in]	count	Number of names in names.

Returns

Nothing.

Precondition

uc is initialised and elf remains open.

names entries outlive the run (argv pointers).

Postcondition

A UC_HOOK_CODE logs each resolved symbol's entries (+LR).

Note

A name that does not resolve is reported once and skipped.

Since

0.1.0

Install a --trace-sym entry hook for every requested symbol present; this step is contained within the emu trace model and uses bounded caller or module-owned storage.

Postcondition

Ownership of caller-supplied storage is unchanged.

Parameters

[in,out]	uc	Active Unicorn engine.
[in]	elf	Loaded ELF image (for symbol resolution).
[in]	names	Symbol names from the CLI (stable for the run).
[in]	count	Number of names in names.

Precondition

uc is initialised and elf is a validated loaded image.

Postcondition

A UC_HOOK_CODE fires internal_on_sym_trace at each resolved symbol's entry.

Note

A name that does not resolve is reported once and skipped.

Since

0.1.0

Definition at line 98 of file emu_trace.c.

References elf_sym_addr(), internal_on_sym_trace(), k_trace_sym_max, and priv_emu_io_errf().

Referenced by internal_main_install_run_seams().