src/gallium/drivers/llvmpipe/README

   1 LLVMPIPE -- a fork of softpipe that employs LLVM for code generation.
   2
   3
   4 Requirements
   5 ============
   6
   7  - A x86 or amd64 processor.  64bit mode is preferred.
   8
   9    Support for sse2 is strongly encouraged.  Support for ssse3, and sse4.1 will
  10    yield the most efficient code.  The less features the CPU has the more
  11    likely is that you ran into underperforming, buggy, or incomplete code.
  12
  13    See /proc/cpuinfo to know what your CPU supports.
  14
  15  - LLVM 2.6 (or later)
  16
  17    For Linux, on a recent Debian based distribution do:
  18
  19      aptitude install llvm-dev
  20
  21    For Windows download pre-built MSVC 9.0 or MinGW binaries from
  22    http://people.freedesktop.org/~jrfonseca/llvm/ and set the LLVM environment
  23    variable to the extracted path.
  24
  25    For MSVC there are two set of binaries: llvm-x.x-msvc32mt.7z and
  26    llvm-x.x-msvc32mtd.7z .
  27
  28    You have to set the LLVM=/path/to/llvm-x.x-msvc32mtd env var when passing
  29    debug=yes to scons, and LLVM=/path/to/llvm-x.x-msvc32mt when building with
  30    debug=no. This is necessary as LLVM builds as static library so the chosen
  31    MS CRT must match.
  32
  33    The version of LLVM from SVN ("2.7svn") from mid-March 2010 is pretty
  34    stable and has some features not in version 2.6.
  35
  36  - scons (optional)
  37
  38  - udis86, http://udis86.sourceforge.net/ (optional). My personal repository
  39    supports more opcodes which haven't been merged upstream yet:
  40
  41      git clone git://anongit.freedesktop.org/~jrfonseca/udis86
  42      cd udis86
  43      ./autogen.sh
  44      ./configure --with-pic
  45      make
  46      sudo make install
  47
  48
  49 Building
  50 ========
  51
  52 To build everything on Linux invoke scons as:
  53
  54   scons build=debug libgl-xlib
  55
  56 Alternatively, you can build it with GNU make, if you prefer, by invoking it as
  57
  58   make linux-llvm
  59
  60 but the rest of these instructions assume that scons is used.
  61
  62 For windows is everything the except except the winsys:
  63
  64   scons build=debug libgl-gdi
  65
  66 Using
  67 =====
  68
  69 On Linux, building will create a drop-in alternative for libGL.so into
  70
  71   build/foo/gallium/targets/libgl-xlib/libGL.so
  72
  73 To use it set the LD_LIBRARY_PATH environment variable accordingly.
  74
  75 For performance evaluation pass debug=no to scons, and use the corresponding
  76 lib directory without the "-debug" suffix.
  77
  78 On Windows, building will create a drop-in alternative for opengl32.dll. To use
  79 it put it in the same directory as the application. It can also be used by
  80 replacing the native ICD driver, but it's quite an advanced usage, so if you
  81 need to ask, don't even try it.
  82
  83
  84 Profiling
  85 =========
  86
  87 To profile llvmpipe you should pass the options
  88
  89   scons build=profile <same-as-before>
  90
  91 This will ensure that frame pointers are used both in C and JIT functions, and
  92 that no tail call optimizations are done by gcc.
  93
  94
  95 To better profile JIT code you'll need to build LLVM with oprofile integration.
  96
  97   source_dir=$PWD/llvm-2.6
  98   build_dir=$source_dir/build/profile
  99   install_dir=$source_dir-profile
 100
 101   mkdir -p "$build_dir"
 102   cd "$build_dir" && \
 103   $source_dir/configure \
 104       --prefix=$install_dir \
 105       --enable-optimized \
 106       --disable-profiling \
 107       --enable-targets=host-only \
 108       --with-oprofile
 109
 110   make -C "$build_dir"
 111   make -C "$build_dir" install
 112
 113   find "$install_dir/lib" -iname '*.a' -print0 | xargs -0 strip --strip-debug
 114
 115 The you should define
 116
 117   export LLVM=/path/to/llvm-2.6-profile
 118
 119 and rebuild.
 120
 121
 122 Unit testing
 123 ============
 124
 125 Building will also create several unit tests in
 126 build/linux-???-debug/gallium/drivers/llvmpipe:
 127
 128  - lp_test_blend: blending
 129  - lp_test_conv: SIMD vector conversion
 130  - lp_test_format: pixel unpacking/packing
 131
 132 Some of this tests can output results and benchmarks to a tab-separated-file
 133 for posterior analysis, e.g.:
 134
 135   build/linux-x86_64-debug/gallium/drivers/llvmpipe/lp_test_blend -o blend.tsv
 136
 137
 138 Development Notes
 139 =================
 140
 141 - When looking to this code by the first time start in lp_state_fs.c, and
 142   then skim through the lp_bld_* functions called in there, and the comments
 143   at the top of the lp_bld_*.c functions.
 144
 145 - The driver-independent parts of the LLVM / Gallium code are found in
 146   src/gallium/auxiliary/gallivm/.  The filenames and function prefixes
 147   need to be renamed from "lp_bld_" to something else though.
 148
 149 - We use LLVM-C bindings for now. They are not documented, but follow the C++
 150   interfaces very closely, and appear to be complete enough for code
 151   generation. See
 152   http://npcontemplation.blogspot.com/2008/06/secret-of-llvm-c-bindings.html
 153   for a stand-alone example.  See the llvm-c/Core.h file for reference.