Update Cranelift README. (#4220)
Our README was starting to show its age; it did not reflect the current status of Cranelift well with respect to production maturity, current supported backends, or performance. This PR makes a pass over the "Status" section to fix that. It also removes some old/out-of-date details, like `no_std` support (which has bitrotted).
This commit is contained in:
Chris Fallin
@@ -30,30 +30,56 @@ Status
|
|||||||
|
|
||||||
Cranelift currently supports enough functionality to run a wide variety
|
Cranelift currently supports enough functionality to run a wide variety
|
||||||
of programs, including all the functionality needed to execute
|
of programs, including all the functionality needed to execute
|
||||||
WebAssembly MVP functions, although it needs to be used within an
|
WebAssembly (MVP and various extensions like SIMD), although it needs to be
|
||||||
external WebAssembly embedding to be part of a complete WebAssembly
|
used within an external WebAssembly embedding such as Wasmtime to be part of a
|
||||||
implementation.
|
complete WebAssembly implementation. It is also usable as a backend for
|
||||||
|
non-WebAssembly use cases: for example, there is an effort to build a [Rust
|
||||||
|
compiler backend] using Cranelift.
|
||||||
|
|
||||||
The x86-64 backend is currently the most complete and stable; other
|
Cranelift is production-ready, and is used in production in several places, all
|
||||||
architectures are in various stages of development. Cranelift currently
|
within the context of Wasmtime. It is carefully fuzzed as part of Wasmtime with
|
||||||
supports both the System V AMD64 ABI calling convention used on many
|
differential comparison against V8 and the executable Wasm spec, and the
|
||||||
platforms and the Windows x64 calling convention. The performance
|
register allocator is separately fuzzed with symbolic verification. There is an
|
||||||
of code produced by Cranelift is not yet impressive, though we have plans
|
active effort to formally verify Cranelift's instruction-selection backends. We
|
||||||
to fix that.
|
take security seriously and have a [security policy] as a part of Bytecode
|
||||||
|
Alliance.
|
||||||
|
|
||||||
The core codegen crates have minimal dependencies, support no\_std mode
|
Cranelift has three backends: x86-64, aarch64 (aka ARM64), and s390x (aka IBM
|
||||||
(see below), and do not require any host floating-point support, and
|
Z). All three backends fully support enough functionality for Wasm MVP, and
|
||||||
do not use callstack recursion.
|
x86-64 and aarch64 fully support SIMD as well. On x86-64, Cranelift supports
|
||||||
|
both the System V AMD64 ABI calling convention used on many platforms and the
|
||||||
|
Windows x64 calling convention. On aarch64, Cranelift supports the standard
|
||||||
|
Linux calling convention and also has specific support for macOS (i.e., M1 /
|
||||||
|
Apple Silicon).
|
||||||
|
|
||||||
Cranelift does not yet perform mitigations for Spectre or related
|
Cranelift's code quality is within range of competitiveness to browser JIT
|
||||||
security issues, though it may do so in the future. It does not
|
engines' optimizing tiers. A [recent paper] includes third-party benchmarks of
|
||||||
currently make any security-relevant instruction timing guarantees. It
|
Cranelift, driven by Wasmtime, against V8 and an LLVM-based Wasm engine, WAVM
|
||||||
has seen a fair amount of testing and fuzzing, although more work is
|
(Fig 22). The speed of Cranelift's generated code is ~2% slower than that of
|
||||||
needed before it would be ready for a production use case.
|
V8 (TurboFan), and ~14% slower than WAVM (LLVM). Its compilation speed, in the
|
||||||
|
same paper, is measured as approximately an order of magnitude faster than WAVM
|
||||||
|
(LLVM). We continue to work to improve both measures.
|
||||||
|
|
||||||
Cranelift's APIs are not yet stable.
|
[Rust compiler backend]: https://github.com/bjorn3/rustc_codegen_cranelift
|
||||||
|
[security policy]: https://bytecodealliance.org/security
|
||||||
|
[recent paper]: https://arxiv.org/abs/2011.13127
|
||||||
|
|
||||||
Cranelift currently requires Rust 1.37 or later to build.
|
The core codegen crates have minimal dependencies and are carefully written to
|
||||||
|
handle malicious or arbitrary compiler input: in particular, they do not use
|
||||||
|
callstack recursion.
|
||||||
|
|
||||||
|
Cranelift performs some basic mitigations for Spectre attacks on heap bounds
|
||||||
|
checks, table bounds checks, and indirect branch bounds checks; see
|
||||||
|
[#1032] for more.
|
||||||
|
|
||||||
|
[#1032]: https://github.com/bytecodealliance/wasmtime/issues/1032
|
||||||
|
|
||||||
|
Cranelift's APIs are not yet considered stable, though we do follow
|
||||||
|
semantic-versioning (semver) with minor-version patch releases.
|
||||||
|
|
||||||
|
Cranelift generally requires the latest stable Rust to build as a policy, and
|
||||||
|
is tested as such, but we can incorporate fixes for compilation with older Rust
|
||||||
|
versions on a best-effort basis.
|
||||||
|
|
||||||
Contributing
|
Contributing
|
||||||
------------
|
------------
|
||||||
@@ -92,57 +118,6 @@ to tell cargo to visit all of the crates.
|
|||||||
`test-all.sh` at the top level is a script which runs all the cargo
|
`test-all.sh` at the top level is a script which runs all the cargo
|
||||||
tests and also performs code format, lint, and documentation checks.
|
tests and also performs code format, lint, and documentation checks.
|
||||||
|
|
||||||
<details>
|
|
||||||
<summary>Building with no_std</summary>
|
|
||||||
|
|
||||||
The following crates support \`no\_std\`, although they do depend on liballoc:
|
|
||||||
- cranelift-entity
|
|
||||||
- cranelift-bforest
|
|
||||||
- cranelift-codegen
|
|
||||||
- cranelift-frontend
|
|
||||||
- cranelift-native
|
|
||||||
- cranelift-wasm
|
|
||||||
- cranelift-module
|
|
||||||
- cranelift-preopt
|
|
||||||
- cranelift
|
|
||||||
|
|
||||||
To use no\_std mode, disable the std feature and enable the core
|
|
||||||
feature. This currently requires nightly rust.
|
|
||||||
|
|
||||||
For example, to build \`cranelift-codegen\`:
|
|
||||||
|
|
||||||
``` {.sourceCode .sh}
|
|
||||||
cd cranelift-codegen
|
|
||||||
cargo build --no-default-features --features core
|
|
||||||
```
|
|
||||||
|
|
||||||
Or, when using cranelift-codegen as a dependency (in Cargo.toml):
|
|
||||||
|
|
||||||
``` {.sourceCode .}
|
|
||||||
[dependency.cranelift-codegen]
|
|
||||||
...
|
|
||||||
default-features = false
|
|
||||||
features = ["core"]
|
|
||||||
```
|
|
||||||
|
|
||||||
no\_std support is currently "best effort". We won't try to break it,
|
|
||||||
and we'll accept patches fixing problems, however we don't expect all
|
|
||||||
developers to build and test no\_std when submitting patches.
|
|
||||||
Accordingly, the ./test-all.sh script does not test no\_std.
|
|
||||||
|
|
||||||
There is a separate ./test-no\_std.sh script that tests the no\_std
|
|
||||||
support in packages which support it.
|
|
||||||
|
|
||||||
It's important to note that cranelift still needs liballoc to compile.
|
|
||||||
Thus, whatever environment is used must implement an allocator.
|
|
||||||
|
|
||||||
Also, to allow the use of HashMaps with no\_std, an external crate
|
|
||||||
called hashmap\_core is pulled in (via the core feature). This is mostly
|
|
||||||
the same as std::collections::HashMap, except that it doesn't have DOS
|
|
||||||
protection. Just something to think about.
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details>
|
<details>
|
||||||
<summary>Log configuration</summary>
|
<summary>Log configuration</summary>
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user