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")]
49 extern crate alloc;
50 
51 #[cfg(not(feature = "chaos"))]
52 mod zero_sized;
53 #[cfg(not(feature = "chaos"))]
54 pub use zero_sized::*;
55 
56 #[cfg(feature = "chaos")]
57 mod chaos;
58 #[cfg(feature = "chaos")]
59 pub use chaos::*;
60