Initial skeleton of Subzero.

README.rst

Index: README.rst
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000000000000000000000000000000000000..ace196a18d010a3cc958d8c71e364286fcf46f36
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,70 @@
+Subzero - Fast code generator for PNaCl bitcode
+===============================================
+
+Building
+--------
+
+You must have LLVM trunk source code available and built.  See
+http://llvm.org/docs/GettingStarted.html#getting-started-quickly-a-summary for
+guidance.
+
+Set variables ``LLVM_SRC_PATH``, ``LLVM_BUILD_PATH``, and ``LLVM_BIN_PATH`` to
+point to the appropriate directories in the LLVM source and build directories.
+These can be set as environment variables, or you can modify the top-level
+Makefile.
+
+Run ``make`` at the top level to build the main target ``llvm2ice``.
+
+``llvm2ice``
+------------
+
+The ``llvm2ice`` program uses the LLVM infrastructure to parse an LLVM bitcode
+file and translate it into ICE.  It then invokes ICE's translate method to lower
+it to target-specific machine code, dumping the IR at various stages of the
+translation.
+
+The program can be run as follows::
+
+    ../llvm2ice ./ir_samples/<file>.ll
+    ../llvm2ice ./tests_lit/llvm2ice_tests/<file>.ll
+
+At this time, ``llvm2ice`` accepts a few arguments:
+
+    ``-help`` -- Show available arguments and possible values.
+
+    ``-notranslate`` -- Suppress the ICE translation phase, which is useful if
+    ICE is missing some support.
+
+    ``-target=<TARGET>`` -- Set the target architecture (default x8632).

[JF, 2014/03/21 02:11:30]

What are the target architecture that are supported? Everyone writes them
differently...

[Jim Stichnoth, 2014/03/21 21:33:08]

Added to the doc.  For the curious:
- x8632 (default, all optimizations enabled)
- x8632fast (minimal passes, lousy code quality)
- x8664, arm32, arm64 (to be implemented)

+
+    ``-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``.
+
+See ir_samples/README.rst for more details.
+
+Running the test suite
+----------------------
+
+Subzero uses the LLVM ``lit`` testing tool for its test suite, which lives in
+``tests_lit``. To execute the test suite, first build Subzero, and then run::
+
+    python <path_to_lit.py> -sv tests_lit
+
+``path_to_lit`` is the direct path to the lit script in the LLVM source
+(``$LLVM_SRC_PATH/utils/lit/lit.py``).
+
+The above ``lit`` execution also needs the LLVM binary path in the
+``LLVM_BIN_PATH`` env var.
+
+Assuming the LLVM paths are set up, ``make check`` is a convenient way to run
+the test suite.
+
+Assembling ``llvm2ice`` output
+------------------------------
+
+Currently ``llvm2ice`` produces textual assembly code in a structure
+suitable for input to ``llvm-mc`` and currently using "intel" assembly
+syntax.  The first line of output is a convenient comment indicating
+how to pipe the output to ``llvm-mc`` to produce object code.