reverie/lib.rs
1/*
2 * Copyright (c) Meta Platforms, Inc. and affiliates.
3 * All rights reserved.
4 *
5 * This source code is licensed under the BSD-style license found in the
6 * LICENSE file in the root directory of this source tree.
7 */
8
9//! Reverie is a user space system-call interception framework for Linux. It can
10//! be used to intercept, modify, or elide a syscall before the kernel executes
11//! it.
12//!
13//! Reverie is the instrumentation layer for [Hermit](https://hermetic-infra.org).
14//! For the command-line interface, see [`hermit-run`](https://crates.io/crates/hermit-run).
15//! For background, see [Hermit: Deterministic Linux for Controlled Testing and Software Bug-finding](https://developers.facebook.com/blog/post/2022/11/22/hermit-deterministic-linux-testing/).
16//!
17//! Reverie consists of a family of crates:
18//! - `reverie` (this one): Primarily provides the [`Tool`] trait interface
19//! that Reverie tools must implement to intercept syscalls. It also defines
20//! the [`Backend`] trait, which is the contract a *backend* implementation
21//! must satisfy in order to run an arbitrary tool.
22//! - `reverie-ptrace`: The backend that uses ptrace to intercept syscalls.
23//! This is currently the only non-experimental backend and is the reference
24//! implementation of the [`Backend`] contract. In the future, we may have a
25//! backend that uses binary rewriting to intercept syscalls within the guest
26//! process.
27//! - `reverie-syscalls`: Provides typed syscalls, which provide safer and more
28//! ergonomic access to the arguments of a syscall. Also provides pretty
29//! printing of syscalls and their arguments.
30//!
31//! The rest of the `reverie-*` crates are used in service to the above crates.
32//!
33//! # Tools and backends
34//!
35//! There are two sides to every Reverie program:
36//! - A [`Tool`] decides *what* to do when the guest hits a trappable event.
37//! This is what most users write; see the [`Tool`] trait for the full
38//! handler API.
39//! - A [`Backend`] decides *how* those events are trapped and how the tool is
40//! run against a live guest process tree (spawning, syscall interception,
41//! hosting global state, teardown). `reverie-ptrace` is the reference
42//! backend; the [`Backend`] trait spells out exactly what any alternative
43//! backend must provide.
44//!
45//! For examples of usage, please see the [`reverie-examples`][] folder.
46//!
47//! See also [`README.md`][] for a high-level overview of Reverie.
48//!
49//! [`reverie-examples`]: https://github.com/facebookexperimental/reverie/tree/main/reverie-examples
50//! [`README.md`]: https://github.com/facebookexperimental/reverie
51
52#![deny(missing_docs)]
53#![deny(rustdoc::broken_intra_doc_links)]
54#![cfg(target_os = "linux")]
55
56mod auxv;
57mod backend;
58pub mod backend_stats;
59mod backtrace;
60mod dispatch_stats;
61mod error;
62mod guest;
63#[cfg(target_arch = "x86_64")]
64pub mod pmu;
65mod process_signal_control;
66#[cfg(target_arch = "x86_64")]
67mod rdtsc;
68mod regs;
69mod signal;
70mod signal_observation;
71mod stack;
72mod subscription;
73mod timer;
74mod tool;
75pub mod vdso;
76
77pub use auxv::*;
78pub use backend::*;
79pub use backend_stats::*;
80pub use backtrace::*;
81pub use dispatch_stats::*;
82pub use error::*;
83pub use guest::*;
84pub use process::ExitStatus;
85pub use process::Pid;
86#[cfg(target_arch = "x86_64")]
87pub use rdtsc::*;
88pub use regs::RegDisplay;
89pub use regs::RegDisplayOptions;
90pub use reverie_process as process;
91pub use signal::*;
92pub use signal_observation::*;
93pub use stack::*;
94pub use subscription::*;
95pub use timer::*;
96pub use tool::*;
97
98/// The identifier for a specific thread, corresponding to the output of gettid.
99/// In many cases, Linux blurs the Pid/Tid distinction, but Reverie should
100/// consistently use TIDs when referring to threads, and Pids when referring to
101/// shared address spaces that (typically) correspond to processes.
102///
103/// This type is currently equivalent to [`Pid`], but relying on that equivalence
104/// is deprecated. `Tid` may be a distinct newtype in the future.
105pub type Tid = Pid;
106
107/// Required for `impl Tool for MyTool` blocks.
108///
109/// NOTE: This is just an alias for `async_trait` for now, but may be extended in
110/// the future to do more things (like derive syscall subscriptions).
111pub use async_trait::async_trait as tool;
112/// Required for `impl GlobalTool for MyGlobalTool` blocks.
113///
114/// NOTE: This is just an alias for `async_trait` for now, but may be extended in
115/// the future to do more things (like deriving Request/Response types from
116/// method names).
117pub use async_trait::async_trait as global_tool;
118/// Required for `impl Backend for MyBackend` blocks.
119///
120/// NOTE: This is just an alias for `async_trait` for now, but may be extended in
121/// the future.
122pub use async_trait::async_trait as backend;
123// Reexport nix Signal type.
124pub use nix::sys::signal::Signal;
125/// CPUID result.
126pub use raw_cpuid::CpuIdResult;
127/// typed syscalls.
128pub use reverie_syscalls as syscalls;
129
130/// `Never` type is a stopgap for the unstable `!` type (i.e., the never type).
131pub type Never = never_say_never::Never;
132
133// Run-owned process signal control; no borrowed Guest is retained.
134pub use process_signal_control::*;