PC-range descriptor for direct, layout-based fallback unwinding. More...

#include <unwind_hint.hpp>

Collaboration diagram for microfmt::unwind_hint:

Public Types
using	unwind_routine_t = bool(*)(address_space_ref space, register_context_ref reg_ctx, uintptr_t &next_fp, uintptr_t &next_pc) noexcept
	Signature of a custom unwind routine provided by the hint.

Public Member Functions
constexpr bool	contains (uintptr_t pc) const noexcept
	Reports whether a PC falls within the hint range.

Public Attributes
uintptr_t	pc_start {0}
	Inclusive start of the covered PC range.

uintptr_t	pc_end {0}
	Exclusive end of the covered PC range.

unwind_routine_t	routine {nullptr}
	Custom routine handler, or `nullptr` to use layout-based fallback.

Detailed Description

PC-range descriptor for direct, layout-based fallback unwinding.

Unwind hints enable custom recovery routines for code regions that cannot be unwound via standard EXIDX, DWARF, or frame-pointer strategies. Common use cases include kernel context-switch stubs, scheduler trampolines, interrupt return paths, and custom prologue sequences that temporarily repurpose registers or saved context layouts.

Member Typedef Documentation

◆ unwind_routine_t

using microfmt::unwind_hint::unwind_routine_t = bool (*)(address_space_ref space, register_context_ref reg_ctx, uintptr_t &next_fp, uintptr_t &next_pc) noexcept

Signature of a custom unwind routine provided by the hint.

The routine receives a full register context handle (not just FP/PC) to enable reading and writing arbitrary registers during context recovery. This is essential for non-standard unwinds that:

Store or recover return addresses in general-purpose registers (GPRs)
Modify saved context as part of frame recovery
Need platform-specific or scheduler-aware state interpretation

Parameters

space	Target address space for memory reads/writes.
reg_ctx	Register context handle supporting read/write access to architecture-specific registers by DWARF index. Use reg_ctx.read<T>(dwarf_reg_index, value) or reg_ctx.write<T>(dwarf_reg_index, value) to access general-purpose and special registers.
next_fp	Output: recovered caller frame pointer.
next_pc	Output: recovered caller program counter.

Returns: true when the routine successfully recovered the next frame. Return false if the context is invalid, saved registers are absent, or the recovered addresses cannot advance the walk.

Note: Routines are not required to also write next_fp/next_pc back into reg_ctx's fp/return-address registers themselves – chained_unwinder_tag does this on every routine's behalf after a successful call, since it (unlike this type-erased routine) knows the concrete AbiTraits needed to pick the right registers. This keeps reg_ctx self-consistent for subsequent steps through any tier, since reg_ctx is always a mutable scratch snapshot (a dead-process register view or a local copy), never a live process to resume.

Member Function Documentation

◆ contains()

constexpr bool microfmt::unwind_hint::contains ( uintptr_t pc ) const

inlineconstexprnoexcept

Reports whether a PC falls within the hint range.

Parameters

pc	PC to test.

Returns: true when pc_start <= pc < pc_end.

Member Data Documentation

◆ pc_end

uintptr_t microfmt::unwind_hint::pc_end {0}

Exclusive end of the covered PC range.

◆ pc_start

uintptr_t microfmt::unwind_hint::pc_start {0}

Inclusive start of the covered PC range.

◆ routine

unwind_routine_t microfmt::unwind_hint::routine {nullptr}

Custom routine handler, or nullptr to use layout-based fallback.

The documentation for this struct was generated from the following file:

include/microfmt/inspector/unwind_hint.hpp

Public Types

Public Member Functions

Public Attributes