Add information about SpiderMonkey and rustc plans.

README.rst

@@ -2,8 +2,9 @@
 Cretonne Code Generator
 =======================
 
-Cretonne is a low-level retargetable code generator. It translates a
+Cretonne is a low-level retargetable code generator. It translates a `target-independent
-target-independent intermediate language into executable machine code.
+intermediate language <http://cretonne.readthedocs.io/en/latest/langref.html>`_ 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
+For more information, see `the documentation
-goals:
+<https://cretonne.readthedocs.io/en/latest/?badge=latest>`_.
 
-Portable semantics
+Planned uses
-    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.
 
-For more information, see
+Cretonne is designed to be a code generator for WebAssembly, but it is general enough to be useful
-`the documentation <https://cretonne.readthedocs.io/en/latest/?badge=latest>`_.
+elsewhere too. The initial planned uses that affected its design are:
+
+1. `WebAssembly compiler for the SpiderMonkey engine in Firefox
+   <spidermonkey.rst#phase-1-webassembly>`_.
+2. `Backend for the IonMonkey JavaScript JIT compiler in Firefox
+   <spidermonkey.rst#phase-2-ionmonkey>`_.
+3. `Debug build backend for the Rust compiler <rustc.rst>`_.
 
 Building Cretonne
 -----------------

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
+<https://internals.rust-lang.org/t/possible-alternative-compiler-backend-cretonne>`_.

spidermonkey.rst

@@ -0,0 +1,44 @@
+========================
+Cretonne in SpiderMonkey
+========================
+
+`SpiderMonkey <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/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.