Skip to main content

Crate reverie_liteinst

Crate reverie_liteinst 

Source

Modules§

rpc
Coordinator RPC handle for in-guest Reverie tools, now in reverie_inguest::guest::rpc.

Macros§

declare_fixed_tool_allocator
Declare the compiler allocator and immutable backing contract of a true leaf.
declare_legacy_private_tool_allocator
Declare the historical always-private BSS allocator for an embedded image.
declare_legacy_scoped_tool_allocator
Declare the historical scoped allocator for an embedded image. Outside its installation/dispatch scopes this allocator retains System use.
declare_legacy_tool_backing
Declare historical backing beside an existing custom or default allocator.

Structs§

FixedToolAllocator
Compiler allocator for a genuine preload with fixed Tool-owned backing.
InheritedEntries
Entries a fork-like syscall’s child counted again as its own first event.
LiteinstBackend
Shared preload launcher with a coordinator-owned GlobalTool.
LiteinstBackendStatsSnapshot
Stable LiteInst statistics captured after one backend run.
LiteinstBackendStatsSource
Backend-owned source for a typed LiteInst end-of-run snapshot.
PreloadBootstrap
Coordinator path and tool-specific bytes consumed by a preload constructor.
PrivateToolAllocator
Allocator for a real preload: every Rust allocation uses one of the two Tool-owned arenas, independent of dispatch depth. Installation storage has process lifetime; other allocations can be reused after deallocation.
RefusedChild
A child created for a refused creation (see PhysicalCreation::Refused).
RefusedProcessCreations
The runtime’s records of guest calls it refused before any Tool ran (a signal handler or alternate stack; a fork-like call while process forks are not allowed). A take returns what was refused in this process since the last take and clears it. The SET of fork-like call kinds protect_runtime_control refused with ENOTSUP because process forks are not allowed; the Tool never sees these calls. It records which of five kinds were refused, not how many times or in what order: repeats of a kind between two takes merge into one.
RefusedSignalControls
The guest signal controls protect_runtime_control refused with EPERM, which the Tool never sees as calls.
ScopedToolAllocator
Legacy allocator for embedded Tools: private during installation/dispatch, System outside those scopes. It is not the isolated preload allocator.

Enums§

BuiltinTool
Shared reverie-inguest built-in tool enum and getpid spoof constant.
CreationHookError
Why set_physical_creation_hook failed.
CreationRefusal
Why the runtime refused a creation; see PhysicalCreation::Refused.
LiteinstDispatchPath
A dispatch or installation path taken by a LiteInst runtime.
LiteinstPatchDecision
A distinct outcome for one candidate LiteInst patch site.
PhysicalCreation
One process creation the guest asked for, as the runtime performed or refused it; reported to the PhysicalCreationHook.
PreloadTool
Built-in synchronous tool executed by the preload runtime.

Constants§

ALT_STACK_ENV
REVERIE_LITEINST_ALT_STACK selector and parser for the shared reverie-inguest RuntimeConfig alt-stack knob. Environment variable selecting the shared RuntimeConfig::use_alt_stack knob for the in-guest runtime’s SIGSYS handler.
COMPAT_EVENT_COOKIE_ENV
Environment variable selecting a per-launch compatibility-event cookie.
COMPAT_EVENT_FD_ENV
Environment variable selecting an inherited descriptor for compatibility events.
COORDINATOR_ENV
Environment variable passed to legacy tool preloads with the coordinator path.
IN_GUEST_STAGE_STREAM_ENV
Enables fail-closed, allocation-free in-guest lifecycle stage markers on stderr.
PROCESS_FORK_ENV
Allows a caller to keep fork-family syscalls fail-closed while integrating a Tool whose process lifecycle is not ready for the direct backend.
SIGALRM_HANDLERS_ENV
Opts the Tool mode into guest SIGALRM handlers (signal phase 1), 1 or 0. Off by default: until the runtime delivers a SIGALRM to an admitted handler (step I4), a run that installs one ends at its first SIGALRM.
SITE_PATCHING_ENV
Selects whether an in-guest Reverie Tool patches trapping syscall sites.
SPOOF_PID
The value BuiltinTool::SpoofGetpid returns for getpid.
STATS_COORDINATOR_ENV
Environment variable naming the optional, stats-only coordinator socket.
STRADDLER_STALENESS_TICKS_ENV
Opt-in calibrated WordPatch++ delay, in timestamp-counter ticks.
TOOL_PASSTHROUGH
REVERIE_LITEINST_TOOL values and parser for shared built-in selection. REVERIE_LITEINST_TOOL value selecting the shared passthrough built-in.
TOOL_PRELOAD_ENV
Environment variable naming the tool-specific preload DSO for a backend run.
TOOL_SPOOF_GETPID
REVERIE_LITEINST_TOOL value selecting the shared getpid-spoofing built-in.

Functions§

alt_stack_from_env_value
Parses an ALT_STACK_ENV value into the use_alt_stack boolean.
blocking_global_rpc
Sends request to the coordinator’s global state and waits for its response, from the installed Tool’s own synchronous code running inside a Tool callback but outside the callback’s own send_rpc: for example from a synchronous method a callback calls, where no reverie::Guest is at hand. Inside a callback the runtime’s own syscalls are not intercepted. Guest code outside a callback cannot use this: its syscalls on the coordinator connection are guest syscalls, which the runtime refuses. It uses the process’s one existing coordinator connection, so it reconnects after a fork exactly as callbacks do, and it adds no descriptor.
builtin_tool_from_env_value
Parses a shared reverie-inguest BuiltinTool from a REVERIE_LITEINST_TOOL value, returning None for the LiteInst-native strace/compat modes and any other value.
configure_command
Configures a guest command to load the runtime and select a built-in tool.
configure_command_builtin
Configures a guest command to load the runtime and select a shared built-in.
guest_stats_enabled
Whether this process image’s runtime collects the statistics it reports at exit: true once the in-guest Tool host initializes the actual collector. Ordinary installations select its endpoint from the compatible REVERIE_LITEINST_STATS_COORDINATOR environment variable; guest code that ran before installation could have changed that variable. Authenticated private InitialImage setup uses the fixed companion of its genuine coordinator endpoint, without an environment fallback. A Tool can check this after installation returns; the host must still require the actual terminal report and clean RPC drain. An image that collects nothing reports nothing at exit.
install_tool⚠
Install a concrete Reverie tool in this guest and connect it to its coordinator.
install_tool_from_bootstrap⚠
Installs a concrete tool using a consumed bootstrap coordinator path.
install_tool_from_bootstrap_with_runtime⚠
Install an ordinary bootstrap Tool using a caller-owned concrete runtime.
install_tool_quiescent⚠
Install a concrete Reverie tool with quiescent patch publication.
preflight_tool_allocator
Checks that this linked root’s allocator uses the runtime’s selected Tool backing. Call during installation, while a dispatch allocation scope is live, before connecting or publishing a Tool. This grants no installation or private-image authority.
preload_library_path
Locates the preload runtime produced beside the current executable.
reserve_tool_output_fd⚠
Moves fd, a socket the in-guest Tool owns for its own output (for example one end of a socket pair its log records go to), to a reserved number in the runtime’s range (runtime_fd_minimums), closes fd, and returns the reserved number. From then on the runtime keeps the guest away from it exactly as it does from the coordinator connection: a close_range over it spares it, and a guest close, read, write, shutdown, send, setsockopt or other descriptor operation on it fails with EBADF, as on a number the guest does not have open. A guest dup2/dup3 onto its number succeeds as it would if the number were free: the runtime first moves the socket to another free number (runtime_fd_minimums), so the Tool must read the current number from tool_output_fd for each use. Tool code writes to it through its own syscalls, which the runtime does not dispatch to the guest’s protections. A forked child inherits the descriptor and its protection.
reverie_liteinst_fallback_dispatch_count
Total syscalls that reached LiteInst’s fallback dispatch path.
reverie_liteinst_fallback_refusal_count
Fallback attempts refused by the runtime before ordinary Tool dispatch.
reverie_liteinst_fallback_syscall_count
Number of times syscall number reached LiteInst’s fallback dispatch path.
reverie_liteinst_fallback_syscall_refusal_count
Per-syscall breakdown of reverie_liteinst_fallback_refusal_count. Numbers outside the tracked table contribute only to the total.
reverie_liteinst_initialize⚠
Initializes the preload runtime when selected by the launcher environment.
reverie_liteinst_site_hook_count
Returns the number of installed-hook callbacks observed at one syscall instruction.
reverie_liteinst_site_trap_count
Returns the number of SIGSYS deliveries observed at one syscall instruction.
set_guest_alt_stack
Selects the shared reverie-inguest RuntimeConfig alt-stack knob for a guest.
set_guest_process_forks
Select whether the direct runtime may forward process-creation syscalls.
set_guest_site_patching
Select whether an in-guest Reverie Tool patches trapping syscall sites.
set_physical_creation_hook
Registers the process’s PhysicalCreationHook.
site_patching_enabled
site_patching_from_env_value
straddler_staleness_from_env_value
Parses the calibrated straddler delay selected for this machine.
take_preload_bootstrap⚠
Consumes the inherited generic-tool bootstrap, if one is present.
take_refused_process_creations
Takes the set of fork-like call kinds refused in this process since the last take, so that a Tool can report them; taking clears the set, so each kind is reported once per take. A forked child starts with its parent’s set. Nothing calls this yet; a Tool that reports refusals is its first caller.
take_refused_signal_controls
Takes the guest signal controls refused in this process since the last call, so that the Tool can report them (each refusal is reported once: taking clears them). A forked child starts with its parent’s record.
tool_output_fd
The Tool output socket’s current number, if one is reserved (reserve_tool_output_fd). It can change when the guest dup2s onto it, so the Tool reads it for each use.

Type Aliases§

PhysicalCreationHook
Called by the runtime in the creating process only, exactly once for each process creation the guest asks for (fork, the copying vfork, and the plain-fork forms of clone and clone3), whether it succeeded, failed or was refused. The call happens synchronously after the physical call returns, and before the copying vfork’s wait or the return to the Tool. For Created the transient pidfd is closed, and its closure confirmed, before the call. For Refused it may still be open (a child that could not be killed, or a failed close); the process then ends right after the call, which releases it. The hook must not wait for guest progress or take the dispatch locks. An error, like a refusal, ends the creating process with status 125; the Tool reports its own failure before returning one.