cranelift_control/lib.rs
1//! # Cranelift Control
2//!
3//! This is the home of the control plane of chaos mode, a compilation feature
4//! intended to be turned on for certain fuzz targets. When the feature is
5//! turned off, as is normally the case, [ControlPlane] will be a zero-sized
6//! type and optimized away.
7//!
8//! While the feature is turned on, the struct [ControlPlane]
9//! provides functionality to tap into pseudo-randomness at specific locations
10//! in the code. It may be used for targeted fuzzing of compiler internals,
11//! e.g. manipulate heuristic optimizations, clobber undefined register bits
12//! etc.
13//!
14//! There are two ways to acquire a [ControlPlane]:
15//! - [arbitrary] for the real deal (requires the `fuzz` feature, enabled by default)
16//! - [default] for an "empty" control plane which always returns default
17//! values
18//!
19//! ## Fuel Limit
20//!
21//! Controls the number of mutations or optimizations that the compiler will
22//! perform before stopping.
23//!
24//! When a perturbation introduced by chaos mode triggers a bug, it may not be
25//! immediately clear which of the introduced perturbations was the trigger. The
26//! fuel limit can then be used to binary-search for the trigger. It limits the
27//! number of perturbations introduced by the control plane. The fuel limit will
28//! typically be set with a command line argument passed to a fuzz target. For
29//! example:
30//! ```sh
31//! cargo fuzz run --features chaos $TARGET -- --fuel=16
32//! ```
33//!
34//! ## `no_std` support
35//!
36//! This crate compiles in `no_std` environments, although both the `fuzz`
37//! or `chaos` features have a dependency on `std`. This means that on `no_std`
38//! you can't use [arbitrary] to initialize [ControlPlane] and can't enable
39//! chaos mode, although the rest of the usual [ControlPlane] API is available.
40//!
41//! [arbitrary]: ControlPlane#method.arbitrary
42//! [default]: ControlPlane#method.default
43
44#![no_std]
45
46// The `alloc` crate is only needed by chaos mode, which guarantees that
47// `alloc` is present because of its dependency on `std`.
48#[cfg(feature = "chaos")]
49extern crate alloc;
50
51#[cfg(not(feature = "chaos"))]
52mod zero_sized;
53#[cfg(not(feature = "chaos"))]
54pub use zero_sized::*;
55
56#[cfg(feature = "chaos")]
57mod chaos;
58#[cfg(feature = "chaos")]
59pub use chaos::*;