move .rst to docs

README.rst

Index: README.rst
diff --git a/README.rst b/README.rst
deleted file mode 100644
index 0257558a17fd0de0c4b8b3361ee92c51c5c33f58..0000000000000000000000000000000000000000
--- a/README.rst
+++ /dev/null
@@ -1,192 +0,0 @@
-Subzero - Fast code generator for PNaCl bitcode
-===============================================
-
-Design
-------
-
-See the accompanying DESIGN.rst file for a more detailed technical overview of
-Subzero.
-
-Building
---------
-
-Subzero is set up to be built within the Native Client tree.  Follow the
-`Developing PNaCl
-<https://sites.google.com/a/chromium.org/dev/nativeclient/pnacl/developing-pnacl>`_
-instructions, in particular the section on building PNaCl sources.  This will
-prepare the necessary external headers and libraries that Subzero needs.
-Checking out the Native Client project also gets the pre-built clang and LLVM
-tools in ``native_client/../third_party/llvm-build/Release+Asserts/bin`` which
-are used for building Subzero.
-
-The Subzero source is in ``native_client/toolchain_build/src/subzero``.  From
-within that directory, ``git checkout master && git pull`` to get the latest
-version of Subzero source code.
-
-The Makefile is designed to be used as part of the higher level LLVM build
-system.  To build manually, use the ``Makefile.standalone``.  There are several
-build configurations from the command line::
-
-    make -f Makefile.standalone
-    make -f Makefile.standalone DEBUG=1
-    make -f Makefile.standalone NOASSERT=1
-    make -f Makefile.standalone DEBUG=1 NOASSERT=1
-    make -f Makefile.standalone MINIMAL=1
-    make -f Makefile.standalone ASAN=1
-    make -f Makefile.standalone TSAN=1
-
-``DEBUG=1`` builds without optimizations and is good when running the translator
-inside a debugger.  ``NOASSERT=1`` disables assertions and is the preferred
-configuration for performance testing the translator.  ``MINIMAL=1`` attempts to
-minimize the size of the translator by compiling out everything unnecessary.
-``ASAN=1`` enables AddressSanitizer, and ``TSAN=1`` enables ThreadSanitizer.
-
-The result of the ``make`` command is the target ``pnacl-sz`` in the current
-directory.
-
-``pnacl-sz``
-------------
-
-The ``pnacl-sz`` program parses a pexe or an LLVM bitcode file and translates it
-into ICE (Subzero's intermediate representation).  It then invokes the ICE
-translate method to lower it to target-specific machine code, optionally dumping
-the intermediate representation at various stages of the translation.
-
-The program can be run as follows::
-
-    ../pnacl-sz ./path/to/<file>.pexe
-    ../pnacl-sz ./tests_lit/pnacl-sz_tests/<file>.ll
-
-At this time, ``pnacl-sz`` accepts a number of arguments, including the
-following:
-
-    ``-help`` -- Show available arguments and possible values.  (Note: this
-    unfortunately also pulls in some LLVM-specific options that are reported but
-    that Subzero doesn't use.)
-
-    ``-notranslate`` -- Suppress the ICE translation phase, which is useful if
-    ICE is missing some support.
-
-    ``-target=<TARGET>`` -- Set the target architecture.  The default is x8632.
-    Future targets include x8664, arm32, and arm64.
-
-    ``-filetype=obj|asm|iasm`` -- Select the output file type.  ``obj`` is a
-    native ELF file, ``asm`` is a textual assembly file, and ``iasm`` is a
-    low-level textual assembly file demonstrating the integrated assembler.
-
-    ``-O<LEVEL>`` -- Set the optimization level.  Valid levels are ``2``, ``1``,
-    ``0``, ``-1``, and ``m1``.  Levels ``-1`` and ``m1`` are synonyms, and
-    represent the minimum optimization and worst code quality, but fastest code
-    generation.
-
-    ``-verbose=<list>`` -- Set verbosity flags.  This argument allows a
-    comma-separated list of values.  The default is ``none``, and the value
-    ``inst,pred`` will roughly match the .ll bitcode file.  Of particular use
-    are ``all``, ``most``, and ``none``.
-
-    ``-o <FILE>`` -- Set the assembly output file name.  Default is stdout.
-
-    ``-log <FILE>`` -- Set the file name for diagnostic output (whose level is
-    controlled by ``-verbose``).  Default is stdout.
-
-    ``-timing`` -- Dump some pass timing information after translating the input
-    file.
-
-Running the test suite
-----------------------
-
-Subzero uses the LLVM ``lit`` testing tool for part of its test suite, which
-lives in ``tests_lit``. To execute the test suite, first build Subzero, and then
-run::
-
-    make -f Makefile.standalone check-lit
-
-There is also a suite of cross tests in the ``crosstest`` directory.  A cross
-test takes a test bitcode file implementing some unit tests, and translates it
-twice, once with Subzero and once with LLVM's known-good ``llc`` translator.
-The Subzero-translated symbols are specially mangled to avoid multiple
-definition errors from the linker.  Both translated versions are linked together
-with a driver program that calls each version of each unit test with a variety
-of interesting inputs and compares the results for equality.  The cross tests
-are currently invoked by running::
-
-    make -f Makefile.standalone check-xtest
-
-Similar, there is a suite of unit tests::
-
-    make -f Makefile.standalone check-unit
-
-A convenient way to run the lit, cross, and unit tests is::
-
-    make -f Makefile.standalone check
-
-Assembling ``pnacl-sz`` output as needed
-----------------------------------------
-
-``pnacl-sz`` can now produce a native ELF binary using ``-filetype=obj``.
-
-``pnacl-sz`` can also produce textual assembly code in a structure suitable for
-input to ``llvm-mc``, using ``-filetype=asm`` or ``-filetype=iasm``.  An object
-file can then be produced using the command::
-
-    llvm-mc -triple=i686 -filetype=obj -o=MyObj.o
-
-Building a translated binary
-----------------------------
-
-There is a helper script, ``pydir/szbuild.py``, that translates a finalized pexe
-into a fully linked executable.  Run it with ``-help`` for extensive
-documentation.
-
-By default, ``szbuild.py`` builds an executable using only Subzero translation,
-but it can also be used to produce hybrid Subzero/``llc`` binaries (``llc`` is
-the name of the LLVM translator) for bisection-based debugging.  In bisection
-debugging mode, the pexe is translated using both Subzero and ``llc``, and the
-resulting object files are combined into a single executable using symbol
-weakening and other linker tricks to control which Subzero symbols and which
-``llc`` symbols take precedence.  This is controlled by the ``-include`` and
-``-exclude`` arguments.  These can be used to rapidly find a single function
-that Subzero translates incorrectly leading to incorrect output.
-
-There is another helper script, ``pydir/szbuild_spec2k.py``, that runs
-``szbuild.py`` on one or more components of the Spec2K suite.  This assumes that
-Spec2K is set up in the usual place in the Native Client tree, and the finalized
-pexe files have been built.  (Note: for working with Spec2K and other pexes,
-it's helpful to finalize the pexe using ``--no-strip-syms``, to preserve the
-original function and global variable names.)
-
-Status
-------
-
-Subzero currently fully supports the x86-32 architecture, for both native and
-Native Client sandboxing modes.  The x86-64 architecture is also supported in
-native mode only, and only for the x32 flavor due to the fact that pointers and
-32-bit integers are indistinguishable in PNaCl bitcode.  Sandboxing support for
-x86-64 is in progress.  ARM and MIPS support is in progress.  Two optimization
-levels, ``-Om1`` and ``-O2``, are implemented.
-
-The ``-Om1`` configuration is designed to be the simplest and fastest possible,
-with a minimal set of passes and transformations.
-
-* Simple Phi lowering before target lowering, by generating temporaries and
-  adding assignments to the end of predecessor blocks.
-
-* Simple register allocation limited to pre-colored or infinite-weight
-  Variables.
-
-The ``-O2`` configuration is designed to use all optimizations available and
-produce the best code.
-
-* Address mode inference to leverage the complex x86 addressing modes.
-
-* Compare/branch fusing based on liveness/last-use analysis.
-
-* Global, linear-scan register allocation.
-
-* Advanced phi lowering after target lowering and global register allocation,
-  via edge splitting, topological sorting of the parallel moves, and final local
-  register allocation.
-
-* Stack slot coalescing to reduce frame size.
-
-* Branch optimization to reduce the number of branches to the following block.