docs/llvmpipe.html

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