docs/llvmpipe.html

   1 <HTML>
   2
   3 <TITLE>llvmpipe</TITLE>
   4
   5 <link rel="stylesheet" type="text/css" href="mesa.css"></head>
   6
   7 <BODY>
   8
   9 <H1>Introduction</H1>
  10
  11 <p>
  12 The Gallium llvmpipe driver is a software rasterizer that uses LLVM to
  13 do runtime code generation.
  14 Shaders, point/line/triangle rasterization and vertex processing are
  15 implemented with LLVM IR which is translated to x86 or x86-64 machine
  16 code.
  17 Also, the driver is multithreaded to take advantage of multiple CPU cores
  18 (up to 8 at this time).
  19 It's the fastest software rasterizer for Mesa.
  20 </p>
  21
  22
  23 <h1>Requirements</h1>
  24
  25 <dl>
  26 <dt>An x86 or amd64 processor.  64-bit mode is preferred.</dt>
  27 <dd>
  28    <p>
  29    Support for sse2 is strongly encouraged.  Support for ssse3, and sse4.1 will
  30    yield the most efficient code.  The less features the CPU has the more
  31    likely is that you ran into underperforming, buggy, or incomplete code.
  32    </p>
  33    <p>
  34    See /proc/cpuinfo to know what your CPU supports.
  35    </p>
  36 </dd>
  37 <dt>LLVM. Version 2.8 recommended. 2.6 or later required.</dt>
  38 <dd>
  39    <p>
  40    <b>NOTE</b>: LLVM 2.8 and earlier will not work on systems that support the
  41    Intel AVX extensions (e.g. Sandybridge).  LLVM's code generator will
  42    fail when trying to emit AVX instructions.  This was fixed in LLVM 2.9.
  43    </p>
  44    <p>
  45    For Linux, on a recent Debian based distribution do:
  46    </p>
  47 <pre>
  48      aptitude install llvm-dev
  49 </pre>
  50    For a RPM-based distribution do:
  51    </p>
  52 <pre>
  53      yum install llvm-devel
  54 </pre>
  55
  56    <p>
  57    For Windows download pre-built MSVC 9.0 or MinGW binaries from
  58    http://people.freedesktop.org/~jrfonseca/llvm/ and set the LLVM environment
  59    variable to the extracted path.
  60    </p>
  61
  62    <p>
  63    For MSVC there are two set of binaries: llvm-x.x-msvc32mt.7z and
  64    llvm-x.x-msvc32mtd.7z .
  65    </p>
  66
  67    <p>
  68    You have to set the LLVM=/path/to/llvm-x.x-msvc32mtd env var when passing
  69    debug=yes to scons, and LLVM=/path/to/llvm-x.x-msvc32mt when building with
  70    debug=no. This is necessary as LLVM builds as static library so the chosen
  71    MS CRT must match.
  72    </p>
  73 </dd>
  74
  75 <dt>scons (optional)</dt>
  76 </dl>
  77
  78
  79
  80 <h1>Building</h1>
  81
  82 To build everything on Linux invoke scons as:
  83
  84 <pre>
  85   scons build=debug libgl-xlib
  86 </pre>
  87
  88 Alternatively, you can build it with GNU make, if you prefer, by invoking it as
  89
  90 <pre>
  91   make linux-llvm
  92 </pre>
  93
  94 but the rest of these instructions assume that scons is used.
  95
  96 For windows is everything the except except the winsys:
  97
  98 <pre>
  99   scons build=debug libgl-gdi
 100 </pre>
 101
 102
 103 <h1>Using</h1>
 104
 105 On Linux, building will create a drop-in alternative for libGL.so into
 106
 107 <pre>
 108   build/foo/gallium/targets/libgl-xlib/libGL.so
 109 </pre>
 110 or
 111 <pre>
 112   lib/gallium/libGL.so
 113 </pre>
 114
 115 To use it set the LD_LIBRARY_PATH environment variable accordingly.
 116
 117 For performance evaluation pass debug=no to scons, and use the corresponding
 118 lib directory without the "-debug" suffix.
 119
 120 On Windows, building will create a drop-in alternative for opengl32.dll. To use
 121 it put it in the same directory as the application. It can also be used by
 122 replacing the native ICD driver, but it's quite an advanced usage, so if you
 123 need to ask, don't even try it.
 124
 125
 126 <h1>Profiling</h1>
 127
 128 To profile llvmpipe you should pass the options
 129
 130 <pre>
 131   scons build=profile <same-as-before>
 132 </pre>
 133
 134 This will ensure that frame pointers are used both in C and JIT functions, and
 135 that no tail call optimizations are done by gcc.
 136
 137 To better profile JIT code you'll need to build LLVM with oprofile integration.
 138
 139 <pre>
 140   ./configure \
 141       --prefix=$install_dir \
 142       --enable-optimized \
 143       --disable-profiling \
 144       --enable-targets=host-only \
 145       --with-oprofile
 146
 147   make -C "$build_dir"
 148   make -C "$build_dir" install
 149
 150   find "$install_dir/lib" -iname '*.a' -print0 | xargs -0 strip --strip-debug
 151 </pre>
 152
 153 The you should define
 154
 155 <pre>
 156   export LLVM=/path/to/llvm-2.6-profile
 157 </pre>
 158
 159 and rebuild.
 160
 161
 162 <h1>Unit testing</h1>
 163
 164 <p>
 165 Building will also create several unit tests in
 166 build/linux-???-debug/gallium/drivers/llvmpipe:
 167 </p>
 168
 169 </ul>
 170 <li> lp_test_blend: blending
 171 <li> lp_test_conv: SIMD vector conversion
 172 <li> lp_test_format: pixel unpacking/packing
 173 </ul>
 174
 175 <p>
 176 Some of this tests can output results and benchmarks to a tab-separated-file
 177 for posterior analysis, e.g.:
 178 </p>
 179 <pre>
 180   build/linux-x86_64-debug/gallium/drivers/llvmpipe/lp_test_blend -o blend.tsv
 181 </pre>
 182
 183
 184 <h1>Development Notes</h1>
 185
 186 <ul>
 187 <li>
 188   When looking to this code by the first time start in lp_state_fs.c, and
 189   then skim through the lp_bld_* functions called in there, and the comments
 190   at the top of the lp_bld_*.c functions.
 191 </li>
 192 <li>
 193   The driver-independent parts of the LLVM / Gallium code are found in
 194   src/gallium/auxiliary/gallivm/.  The filenames and function prefixes
 195   need to be renamed from "lp_bld_" to something else though.
 196 </li>
 197 <li>
 198   We use LLVM-C bindings for now. They are not documented, but follow the C++
 199   interfaces very closely, and appear to be complete enough for code
 200   generation. See
 201   http://npcontemplation.blogspot.com/2008/06/secret-of-llvm-c-bindings.html
 202   for a stand-alone example.  See the llvm-c/Core.h file for reference.
 203 </li>
 204 </ul>