This crate contains the control plane for "chaos mode". It can be used to inject pseudo-random perturbations into specific sections in the code while fuzzing. Its compilation is feature-gated to prevent any performance impact on release builds.

lib.rs:

Cranelift Control

This is the home of the control plane of chaos mode, a compilation feature intended to be turned on for certain fuzz targets. When the feature is turned off, as is normally the case, [ControlPlane] will be a zero-sized type and optimized away.

While the feature is turned on, the struct [ControlPlane] provides functionality to tap into pseudo-randomness at specific locations in the code. It may be used for targeted fuzzing of compiler internals, e.g. manipulate heuristic optimizations, clobber undefined register bits etc.

There are two ways to acquire a [ControlPlane]:

• arbitrary for the real deal (requires the fuzz feature, enabled by default)
• default for an "empty" control plane which always returns default values

Fuel Limit

Controls the number of mutations or optimizations that the compiler will perform before stopping.

When a perturbation introduced by chaos mode triggers a bug, it may not be immediately clear which of the introduced perturbations was the trigger. The fuel limit can then be used to binary-search for the trigger. It limits the number of perturbations introduced by the control plane. The fuel limit will typically be set with a command line argument passed to a fuzz target. For example:

cargo fuzz run --features chaos $TARGET -- --fuel=16

no_std support

This crate compiles in no_std environments, although both the fuzz or chaos features have a dependency on std. This means that on no_std you can't use arbitrary to initialize [ControlPlane] and can't enable chaos mode, although the rest of the usual [ControlPlane] API is available.