# `cargo fuzz` Targets for Wasmtime
This crate defines various [libFuzzer ](https://www.llvm.org/docs/LibFuzzer.html )
fuzzing targets for Wasmtime, which can be run via [`cargo
fuzz`](https://rust-fuzz.github.io/book/cargo-fuzz.html).
These fuzz targets just glue together pre-defined test case generators with
oracles and pass libFuzzer-provided inputs to them. The test case generators and
oracles themselves are independent from the fuzzing engine that is driving the
fuzzing process and are defined in `wasmtime/crates/fuzzing` .
## Example
To start fuzzing run the following command, where `$MY_FUZZ_TARGET` is one of
the [available fuzz targets ](#available-fuzz-targets ):
```shell
cargo fuzz run $MY_FUZZ_TARGET
```
## Available Fuzz Targets
At the time of writing, we have the following fuzz targets:
* `api_calls` : stress the Wasmtime API by executing sequences of API calls; only
the subset of the API is currently supported.
* `compile` : Attempt to compile libFuzzer's raw input bytes with Wasmtime.
* `compile-maybe-invalid` : Attempt to compile a wasm-smith-generated Wasm module
with code sequences that may be invalid.
* `cranelift-fuzzgen` : Generate a Cranelift function and check that it returns
the same results when compiled to the host and when using the Cranelift
interpreter; only a subset of Cranelift IR is currently supported.
Implement an incremental compilation cache for Cranelift (#4551)
This is the implementation of https://github.com/bytecodealliance/wasmtime/issues/4155, using the "inverted API" approach suggested by @cfallin (thanks!) in Cranelift, and trait object to provide a backend for an all-included experience in Wasmtime.
After the suggestion of Chris, `Function` has been split into mostly two parts:
- on the one hand, `FunctionStencil` contains all the fields required during compilation, and that act as a compilation cache key: if two function stencils are the same, then the result of their compilation (`CompiledCodeBase<Stencil>`) will be the same. This makes caching trivial, as the only thing to cache is the `FunctionStencil`.
- on the other hand, `FunctionParameters` contain the... function parameters that are required to finalize the result of compilation into a `CompiledCode` (aka `CompiledCodeBase<Final>`) with proper final relocations etc., by applying fixups and so on.
Most changes are here to accomodate those requirements, in particular that `FunctionStencil` should be `Hash`able to be used as a key in the cache:
- most source locations are now relative to a base source location in the function, and as such they're encoded as `RelSourceLoc` in the `FunctionStencil`. This required changes so that there's no need to explicitly mark a `SourceLoc` as the base source location, it's automatically detected instead the first time a non-default `SourceLoc` is set.
- user-defined external names in the `FunctionStencil` (aka before this patch `ExternalName::User { namespace, index }`) are now references into an external table of `UserExternalNameRef -> UserExternalName`, present in the `FunctionParameters`, and must be explicitly declared using `Function::declare_imported_user_function`.
- some refactorings have been made for function names:
- `ExternalName` was used as the type for a `Function`'s name; while it thus allowed `ExternalName::Libcall` in this place, this would have been quite confusing to use it there. Instead, a new enum `UserFuncName` is introduced for this name, that's either a user-defined function name (the above `UserExternalName`) or a test case name.
- The future of `ExternalName` is likely to become a full reference into the `FunctionParameters`'s mapping, instead of being "either a handle for user-defined external names, or the thing itself for other variants". I'm running out of time to do this, and this is not trivial as it implies touching ISLE which I'm less familiar with.
The cache computes a sha256 hash of the `FunctionStencil`, and uses this as the cache key. No equality check (using `PartialEq`) is performed in addition to the hash being the same, as we hope that this is sufficient data to avoid collisions.
A basic fuzz target has been introduced that tries to do the bare minimum:
- check that a function successfully compiled and cached will be also successfully reloaded from the cache, and returns the exact same function.
- check that a trivial modification in the external mapping of `UserExternalNameRef -> UserExternalName` hits the cache, and that other modifications don't hit the cache.
- This last check is less efficient and less likely to happen, so probably should be rethought a bit.
Thanks to both @alexcrichton and @cfallin for your very useful feedback on Zulip.
Some numbers show that for a large wasm module we're using internally, this is a 20% compile-time speedup, because so many `FunctionStencil`s are the same, even within a single module. For a group of modules that have a lot of code in common, we get hit rates up to 70% when they're used together. When a single function changes in a wasm module, every other function is reloaded; that's still slower than I expect (between 10% and 50% of the overall compile time), so there's likely room for improvement.
Fixes #4155.
2 years ago
* `cranelift-icache` : Generate a Cranelift function A, applies a small mutation
to its source, yielding a function A', and checks that A compiled +
incremental compilation generates the same machine code as if A' was compiled
from scratch.
* `differential` : Generate a Wasm module, evaluate each exported function
with random inputs, and check that Wasmtime returns the same results as a
choice of another engine: the Wasm spec interpreter (see the
`wasm-spec-interpreter` crate), the `wasmi` interpreter, V8 (through the `v8`
crate), or Wasmtime itself run with a different configuration.
* `instantiate` : Generate a Wasm module and Wasmtime configuration and attempt
to compile and instantiate with them.
* `instantiate-many` : Generate many Wasm modules and attempt to compile and
instantiate them concurrently.
* `spectests` : Pick a random spec test and run it with a generated
configuration.
* `table_ops` : Generate a sequence of `externref` table operations and run them
in a GC environment.
The canonical list of fuzz targets is the `.rs` files in the `fuzz_targets`
directory:
```shell
ls wasmtime/fuzz/fuzz_targets/
```
## Corpora
While you *can* start from scratch, libFuzzer will work better if it is given a
[corpus ](https://www.llvm.org/docs/LibFuzzer.html#corpus ) of seed inputs to kick
start the fuzzing process. We maintain a corpus for each of these fuzz targets
in [a dedicated repo on
github](https://github.com/bytecodealliance/wasmtime-libfuzzer-corpus).
You can use our corpora by cloning it and placing it at `wasmtime/fuzz/corpus` :
```shell
git clone \
https://github.com/bytecodealliance/wasmtime-libfuzzer-corpus.git \
wasmtime/fuzz/corpus
```
## Reproducing a Fuzz Bug
When investigating a fuzz bug (especially one found by OSS-Fuzz), use the
following steps to reproduce it locally:
1. Download the test case (either the "Minimized Testcase" or "Unminimized
Testcase" from OSS-Fuzz will do).
2. Run the test case in the correct fuzz target:
```shell
cargo +nightly fuzz run < target > < test case >
```
If all goes well, the bug should reproduce and libFuzzer will dump the
failure stack trace to stdout
3. For more debugging information, run the command above with `RUST_LOG=debug`
to print the configuration and WebAssembly input used by the test case (see
uses of `log_wasm` in the `wasmtime-fuzzing` crate).
## Target specific options
### `cranelift-fuzzgen`
Fuzzgen supports passing the `FUZZGEN_ALLOWED_OPS` environment variable, which when available restricts the instructions that it will generate.
Running `FUZZGEN_ALLOWED_OPS=ineg,ishl cargo fuzz run cranelift-fuzzgen` will run fuzzgen but only generate `ineg` or `ishl` opcodes.
### `cranelift-icache`
The icache target also uses the fuzzgen library, thus also supports the `FUZZGEN_ALLOWED_OPS` enviornment variable as described in the `cranelift-fuzzgen` section above.
