| Jim Stichnoth | f7c9a14 | 2014-04-29 10:52:43 -0700 | [diff] [blame] | 1 | Subzero - Fast code generator for PNaCl bitcode |
| 2 | =============================================== |
| 3 | |
| 4 | Building |
| 5 | -------- |
| 6 | |
| 7 | You must have LLVM trunk source code available and built. See |
| 8 | http://llvm.org/docs/GettingStarted.html#getting-started-quickly-a-summary for |
| 9 | guidance. |
| 10 | |
| 11 | Set variables ``LLVM_SRC_PATH`` and ``LLVM_BIN_PATH`` to point to the |
| 12 | appropriate directories in the LLVM source and build directories. These can be |
| 13 | set as environment variables, or you can modify the top-level Makefile. |
| 14 | |
| 15 | Run ``make`` at the top level to build the main target ``llvm2ice``. |
| 16 | |
| 17 | ``llvm2ice`` |
| 18 | ------------ |
| 19 | |
| 20 | The ``llvm2ice`` program uses the LLVM infrastructure to parse an LLVM bitcode |
| 21 | file and translate it into ICE. It then invokes ICE's translate method to lower |
| 22 | it to target-specific machine code, dumping the IR at various stages of the |
| 23 | translation. |
| 24 | |
| 25 | The program can be run as follows:: |
| 26 | |
| 27 | ../llvm2ice ./ir_samples/<file>.ll |
| 28 | ../llvm2ice ./tests_lit/llvm2ice_tests/<file>.ll |
| 29 | |
| 30 | At this time, ``llvm2ice`` accepts a few arguments: |
| 31 | |
| 32 | ``-help`` -- Show available arguments and possible values. |
| 33 | |
| 34 | ``-notranslate`` -- Suppress the ICE translation phase, which is useful if |
| 35 | ICE is missing some support. |
| 36 | |
| Jim Stichnoth | 5bc2b1d | 2014-05-22 13:38:48 -0700 | [diff] [blame] | 37 | ``-target=<TARGET>`` -- Set the target architecture. The default is x8632. |
| 38 | Future targets include x8664, arm32, and arm64. |
| 39 | |
| 40 | ``-O<LEVEL>`` -- Set the optimization level. Valid levels are ``2``, ``1``, |
| 41 | ``0``, ``-1``, and ``m1``. Levels ``-1`` and ``m1`` are synonyms, and |
| 42 | represent the minimum optimization and worst code quality, but fastest code |
| 43 | generation. |
| Jim Stichnoth | f7c9a14 | 2014-04-29 10:52:43 -0700 | [diff] [blame] | 44 | |
| 45 | ``-verbose=<list>`` -- Set verbosity flags. This argument allows a |
| 46 | comma-separated list of values. The default is ``none``, and the value |
| 47 | ``inst,pred`` will roughly match the .ll bitcode file. Of particular use |
| 48 | are ``all`` and ``none``. |
| 49 | |
| Jim Stichnoth | 5bc2b1d | 2014-05-22 13:38:48 -0700 | [diff] [blame] | 50 | ``-o <FILE>`` -- Set the assembly output file name. Default is stdout. |
| 51 | |
| 52 | ``-log <FILE>`` -- Set the file name for diagnostic output (whose level is |
| 53 | controlled by ``-verbose``). Default is stdout. |
| 54 | |
| Jim Stichnoth | f7c9a14 | 2014-04-29 10:52:43 -0700 | [diff] [blame] | 55 | See ir_samples/README.rst for more details. |
| 56 | |
| 57 | Running the test suite |
| 58 | ---------------------- |
| 59 | |
| 60 | Subzero uses the LLVM ``lit`` testing tool for its test suite, which lives in |
| 61 | ``tests_lit``. To execute the test suite, first build Subzero, and then run:: |
| 62 | |
| 63 | python <path_to_lit.py> -sv tests_lit |
| 64 | |
| 65 | ``path_to_lit`` is the direct path to the lit script in the LLVM source |
| 66 | (``$LLVM_SRC_PATH/utils/lit/lit.py``). |
| 67 | |
| 68 | The above ``lit`` execution also needs the LLVM binary path in the |
| 69 | ``LLVM_BIN_PATH`` env var. |
| 70 | |
| 71 | Assuming the LLVM paths are set up, ``make check`` is a convenient way to run |
| 72 | the test suite. |
| 73 | |
| 74 | Assembling ``llvm2ice`` output |
| 75 | ------------------------------ |
| 76 | |
| 77 | Currently ``llvm2ice`` produces textual assembly code in a structure suitable |
| 78 | for input to ``llvm-mc`` and currently using "intel" assembly syntax. The first |
| 79 | line of output is a convenient comment indicating how to pipe the output to |
| 80 | ``llvm-mc`` to produce object code. |