diff --git a/README.rst b/README.rst index d62e5b2777..31e674350b 100644 --- a/README.rst +++ b/README.rst @@ -2,8 +2,9 @@ Cretonne Code Generator ======================= -Cretonne is a low-level retargetable code generator. It translates a -target-independent intermediate language into executable machine code. +Cretonne is a low-level retargetable code generator. It translates a `target-independent +intermediate language `_ into executable +machine code. *This is a work in progress that is not yet functional.* @@ -15,28 +16,20 @@ target-independent intermediate language into executable machine code. :target: https://travis-ci.org/stoklund/cretonne :alt: Build Status -Cretonne is designed to be a code generator for WebAssembly with these design -goals: +For more information, see `the documentation +`_. -Portable semantics - As far as possible, Cretonne's input language has well-defined semantics - that are the same on all target architectures. The semantics are usually - the same as WebAssembly's. -Fast sandbox verification - Cretonne's input language has a safe subset for sandboxed code. No advanced - analysis is required to verify memory safety as long as only the safe - subset is used. The safe subset is expressive enough to implement - WebAssembly. -Scalable performance - Cretonne can be configured to generate code as quickly as possible, or it - can generate very good code at the cost of slower compile times. -Predictable performance - When optimizing, Cretonne focuses on adapting the target-independent IL to - the quirks of the target architecture. There are no advanced optimizations - that sometimes work, sometimes fail. +Planned uses +------------ -For more information, see -`the documentation `_. +Cretonne is designed to be a code generator for WebAssembly, but it is general enough to be useful +elsewhere too. The initial planned uses that affected its design are: + +1. `WebAssembly compiler for the SpiderMonkey engine in Firefox + `_. +2. `Backend for the IonMonkey JavaScript JIT compiler in Firefox + `_. +3. `Debug build backend for the Rust compiler `_. Building Cretonne ----------------- diff --git a/cranelift/media/spidermonkey1.png b/cranelift/media/spidermonkey1.png new file mode 100644 index 0000000000..0304a0a4f3 Binary files /dev/null and b/cranelift/media/spidermonkey1.png differ diff --git a/cranelift/media/spidermonkey2.png b/cranelift/media/spidermonkey2.png new file mode 100644 index 0000000000..14c6e3b543 Binary files /dev/null and b/cranelift/media/spidermonkey2.png differ diff --git a/rustc.rst b/rustc.rst new file mode 100644 index 0000000000..90ab7df8b4 --- /dev/null +++ b/rustc.rst @@ -0,0 +1,16 @@ +================= +Cretonne in Rustc +================= + +The Rust compiler currently uses LLVM as its optimizer and code generator for both debug and +release builds. The Cretonne project does not intend to compete with LLVM when it comes to +optimizing release builds, but for debug builds where compilation speed is paramount, it makes +sense to use Cretonne instead of LLVM. + +- Cretonne is designed to take advantage of multi-core CPUs, making parallel code generation quite + easy. This is harder with LLVM which was designed before multi-core CPUs where mainstream. +- Cretonne is designed with compilation speed in mind. It makes engineering tradeoffs that favor + compilation speed over advanced optimizations. + +See `the discussion on the Rust internals forum +`_. diff --git a/spidermonkey.rst b/spidermonkey.rst new file mode 100644 index 0000000000..57cbccc03e --- /dev/null +++ b/spidermonkey.rst @@ -0,0 +1,44 @@ +======================== +Cretonne in SpiderMonkey +======================== + +`SpiderMonkey `_ is the +JavaScript and WebAssembly engine in Firefox. Cretonne is designed to be used in SpiderMonkey with +the goal of enabling better code generation for ARM's 32-bit and 64-bit architectures, and building +a framework for improved low-level code optimizations in the future. + +Phase 1: WebAssembly +-------------------- + +SpiderMonkey currently has two WebAssembly compilers: The tier 1 baseline compiler (not shown +below) and the tier 2 compiler using the IonMonkey JavaScript compiler's optimizations and register +allocation. + +.. image:: media/spidermonkey1.png + :align: center + :width: 80% + :alt: Cretonne in SpiderMonkey phase 1 + +In phase 1, Cretonne aims to replace the IonMonkey-based tier 2 compiler for WebAssembly only. It +will still be orchestrated by the BaldrMonkey engine and compile WebAssembly modules on multiple +threads. Cretonne translates binary wasm functions directly into its own intermediate +representation, and it generates binary machine code without depending on SpiderMonkey's macro +assembler. + +Phase 2: IonMonkey +------------------ + +The IonMonkey JIT compiler is designed to compile JavaScript code. It uses two separate +intermediate representations to do that: + +- MIR is used for optimizations that are specific to JavaScript JIT compilation. It has good + support for JS types and the special tricks needed to make JS fast. +- LIR is used for register allocation. + +.. image:: media/spidermonkey2.png + :align: center + :width: 80% + :alt: Cretonne in SpiderMonkey phase 2 + +Cretonne has its own register allocator, so the LIR representation can be skipped when using +Cretonne as a backend for IonMonkey.