Subzero: Add a detailed design document.

README.rst

 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
@@ skipping 22 matching lines @@
     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`` and ``none``.
+    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 the ``runtests.sh`` script.
+are currently invoked by running::
 
-A convenient way to run both the lit tests and the cross tests is::
+    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 -arch=x86 -filetype=obj -o=MyObj.o
+    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 translates only for the x86-32 architecture.  Native Client
-sandboxing is not yet implemented.  Two optimization levels, ``-Om1`` and
-``-O2``, are implemented.
+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, for the x32 flavor due to PNaCl bitcode restrictions.  ARM and

[JF, 2015/08/31 21:08:02]

"in native mode only" but sandboxing is in progress?

"for the x32 flavor due to PNaCl bitcode restrictions" that's not very clear.

[Jim Stichnoth, 2015/09/02 23:35:05]

Done.

+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 and infinite-weight
+* 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.