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
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 //! [arbitrary]: ControlPlane#method.arbitrary
35 //! [default]: ControlPlane#method.default
36 
37 #[cfg(not(feature = "chaos"))]
38 mod zero_sized;
39 #[cfg(not(feature = "chaos"))]
40 pub use zero_sized::*;
41 
42 #[cfg(feature = "chaos")]
43 mod chaos;
44 #[cfg(feature = "chaos")]
45 pub use chaos::*;
46