123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213 |
- 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.
- Building within LLVM trunk
- --------------------------
- Subzero can also be built from within a standard LLVM trunk checkout. Here is
- an example of how it can be checked out and built::
- mkdir llvm-git
- cd llvm-git
- git clone http://llvm.org/git/llvm.git
- cd llvm/projects/
- git clone https://chromium.googlesource.com/native_client/pnacl-subzero
- cd ../..
- mkdir build
- cd build
- cmake -G Ninja ../llvm/
- ninja
- ./bin/pnacl-sz -version
- This creates a default build of ``pnacl-sz``; currently any options such as
- ``DEBUG=1`` or ``MINIMAL=1`` have to be added manually.
- ``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
- the intermediate representation at various stages of the translation.
- The program can be run as follows::
- ../pnacl-sz ./path/to/<file>.pexe
- ../pnacl-sz ./tests_lit/pnacl-sz_tests/<file>.ll
- At this time, ``pnacl-sz`` accepts a number of arguments, including the
- following:
- ``-help`` -- Show available arguments and possible values. (Note: this
- unfortunately also pulls in some LLVM-specific options that are reported but
- that Subzero doesn't use.)
- ``-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.
- Future targets include x8664, arm32, and arm64.
- ``-filetype=obj|asm|iasm`` -- Select the output file type. ``obj`` is a
- native ELF file, ``asm`` is a textual assembly file, and ``iasm`` is a
- 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``, ``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::
- 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 -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 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, and only for the x32 flavor due to the fact that pointers and
- 32-bit integers are indistinguishable in PNaCl bitcode. Sandboxing support for
- x86-64 is in progress. ARM and 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 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.
|