reverie-core 0.4.0

Deterministic user-space syscall and signal interception runtime — the core Reverie process-instrumentation framework.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

/*
 * Copyright (c) Meta Platforms, Inc. and affiliates.
 * All rights reserved.
 *
 * This source code is licensed under the BSD-style license found in the
 * LICENSE file in the root directory of this source tree.
 */

//! Reverie is a user space system-call interception framework for Linux. It can
//! be used to intercept, modify, or elide a syscall before the kernel executes
//! it.
//!
//! Reverie consists of a family of crates:
//!  - `reverie` (this one): Primarily provides the [`Tool`] trait interface
//!    that Reverie tools must implement to intercept syscalls. It also defines
//!    the [`Backend`] trait, which is the contract a *backend* implementation
//!    must satisfy in order to run an arbitrary tool.
//!  - `reverie-ptrace`: The backend that uses ptrace to intercept syscalls.
//!    This is currently the only non-experimental backend and is the reference
//!    implementation of the [`Backend`] contract. In the future, we may have a
//!    backend that uses binary rewriting to intercept syscalls within the guest
//!    process.
//!  - `reverie-syscalls`: Provides typed syscalls, which provide safer and more
//!    ergonomic access to the arguments of a syscall. Also provides pretty
//!    printing of syscalls and their arguments.
//!
//! The rest of the `reverie-*` crates are used in service to the above crates.
//!
//! # Tools and backends
//!
//! There are two sides to every Reverie program:
//!  - A [`Tool`] decides *what* to do when the guest hits a trappable event.
//!    This is what most users write; see the [`Tool`] trait for the full
//!    handler API.
//!  - A [`Backend`] decides *how* those events are trapped and how the tool is
//!    run against a live guest process tree (spawning, syscall interception,
//!    hosting global state, teardown). `reverie-ptrace` is the reference
//!    backend; the [`Backend`] trait spells out exactly what any alternative
//!    backend must provide.
//!
//! For examples of usage, please see the [`reverie-examples`][] folder.
//!
//! See also [`README.md`][] for a high-level overview of Reverie.
//!
//! [`reverie-examples`]: https://github.com/facebookexperimental/reverie/tree/main/reverie-examples
//! [`README.md`]: https://github.com/facebookexperimental/reverie

#![deny(missing_docs)]
#![deny(rustdoc::broken_intra_doc_links)]
#![cfg(target_os = "linux")]

mod auxv;
mod backend;
pub mod backend_stats;
mod backtrace;
mod dispatch_stats;
mod error;
mod guest;
#[cfg(target_arch = "x86_64")]
pub mod pmu;
mod process_signal_control;
#[cfg(target_arch = "x86_64")]
mod rdtsc;
mod regs;
mod signal;
mod signal_observation;
mod stack;
mod subscription;
mod timer;
mod tool;
pub mod vdso;

pub use auxv::*;
pub use backend::*;
pub use backend_stats::*;
pub use backtrace::*;
pub use dispatch_stats::*;
pub use error::*;
pub use guest::*;
pub use process::ExitStatus;
pub use process::Pid;
#[cfg(target_arch = "x86_64")]
pub use rdtsc::*;
pub use regs::RegDisplay;
pub use regs::RegDisplayOptions;
pub use reverie_process as process;
pub use signal::*;
pub use signal_observation::*;
pub use stack::*;
pub use subscription::*;
pub use timer::*;
pub use tool::*;

/// The identifier for a specific thread, corresponding to the output of gettid.
/// In many cases, Linux blurs the Pid/Tid distinction, but Reverie should
/// consistently use TIDs when referring to threads, and Pids when referring to
/// shared address spaces that (typically) correspond to processes.
///
/// This type is currently equivalent to [`Pid`], but relying on that equivalence
/// is deprecated. `Tid` may be a distinct newtype in the future.
pub type Tid = Pid;

/// Required for `impl Tool for MyTool` blocks.
///
/// NOTE: This is just an alias for `async_trait` for now, but may be extended in
/// the future to do more things (like derive syscall subscriptions).
pub use async_trait::async_trait as tool;
/// Required for `impl GlobalTool for MyGlobalTool` blocks.
///
/// NOTE: This is just an alias for `async_trait` for now, but may be extended in
/// the future to do more things (like deriving Request/Response types from
/// method names).
pub use async_trait::async_trait as global_tool;
/// Required for `impl Backend for MyBackend` blocks.
///
/// NOTE: This is just an alias for `async_trait` for now, but may be extended in
/// the future.
pub use async_trait::async_trait as backend;
// Reexport nix Signal type.
pub use nix::sys::signal::Signal;
/// CPUID result.
pub use raw_cpuid::CpuIdResult;
/// typed syscalls.
pub use reverie_syscalls as syscalls;

/// `Never` type is a stopgap for the unstable `!` type (i.e., the never type).
pub type Never = never_say_never::Never;

// Run-owned process signal control; no borrowed Guest is retained.
pub use process_signal_control::*;