Initial skeleton of Subzero.
This includes just enough code to build the high-level ICE IR and dump it back out again. There is a script szdiff.py that does a fuzzy diff of the input and output for verification. See the comment in szdiff.py for a description of the fuzziness.
Building llvm2ice requires LLVM headers, libs, and tools (e.g. FileCheck) to be present. These default to something like llvm_i686_linux_work/Release+Asserts/ based on the checked-out and built pnacl-llvm code; I'll try to figure out how to more automatically detect the build configuration.
"make check" runs the lit tests.
This CL has under 2000 lines of "interesting" Ice*.{h,cpp} code, plus 600 lines of llvm2ice.cpp driver code, and the rest is tests.
Here is the high-level mapping of source files to functionality:
IceDefs.h, IceTypes.h, IceTypes.cpp:
Commonly used types and utilities.
IceCfg.h, IceCfg.cpp:
Operations at the function level.
IceCfgNode.h, IceCfgNode.cpp:
Operations on basic blocks (nodes).
IceInst.h, IceInst.cpp:
Operations on instructions.
IceOperand.h, IceOperand.cpp:
Operations on operands, such as stack locations, physical registers, and constants.
BUG= none
R=jfb@chromium.org
Review URL: https://codereview.chromium.org/205613002
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..9de4602
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,71 @@
+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`` 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.
+
+ ``-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.
