emu_trace.c File Reference

Seam glue + –trace-sym implementation (see emu_trace.h). More...

#include "emu_trace.h"
#include <stdio.h>
#include "emu_elf.h"
#include "emu_host_io_internal.h"

Include dependency graph for emu_trace.c:

Go to the source code of this file.

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.
static RA8_INTERNAL void	internal_on_sym_trace (uc_engine *uc, uint64_t address, uint32_t size, void *user)
	Perform on sym trace for the emu trace model.
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

Seam glue + –trace-sym implementation (see emu_trace.h).

The return-to-LR helper, the named-symbol entry hook installer, and the --trace-sym logger – moved verbatim out of the ra8_emulator main translation unit.

Copyright

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

Since

0.1.0

Definition in file emu_trace.c.

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().

internal_on_sym_trace()

RA8_INTERNAL void internal_on_sym_trace ( uc_engine * uc, uint64_t address, uint32_t size, void * user )

static

Perform on sym trace for the emu trace model.

Perform on sym trace for the emu trace model; this step is contained within the emu trace model and uses bounded caller or module-owned storage.

Parameters

[in,out]	uc	Unicorn engine whose emulated state is read or updated.
[in]	address	Guest address involved in the operation.
[in]	size	Size of the requested region or access in bytes.
[in,out]	user	Hook context supplied when the callback was registered.

Precondition

Arguments satisfy the ranges documented for on sym trace.

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

Postcondition

State changes remain confined to the emu trace 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 73 of file emu_trace.c.

References priv_emu_io_errf().

Referenced by sym_trace_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	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().