Initial skeleton of Subzero.

README.rst

Index: README.rst
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000000000000000000000000000000000000..2be7a29d396863c890e4199937ddc7808138e752
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,72 @@
+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.  The default is x8632,
+    and x8632fast (generate x8632 code as fast as possible at the cost of code
+    quality) is also available.  Future targets include x8664, arm32, and arm64.

[JF, 2014/03/23 00:03:15]

Bikeshedding names, it's weird to have upper/lower cases mixed, and the names
aren't what we usually go with AFAIK.

I'd expect x86-32, x86-64, arm, mips. ARM likes confusing things, so the new
names in ARMv8 are A32 and A64...

Fast seems orthogonal.

[Jim Stichnoth, 2014/03/24 13:18:53]

Well, my choices were all lowercase. :)  In any case, I agree that the names
should match PNaCl's (assuming we have those all consistent by now?), or part of
the LLVM target triple, but not something new.
I wouldn't say orthogonal, but I guess it really refers to the -O level. 
Different -O levels will differ in the list of passes, including code selection
strategy like FastISel versus SelectionDAG.  Maybe we can sort this out after a
couple of architectures are 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.