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>Gallium LLVMpipe Driver</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>Gallium LLVMpipe Driver</h1>
  18
  19 <h2>Introduction</h2>
  20
  21 <p>
  22 The Gallium llvmpipe driver is a software rasterizer that uses LLVM to
  23 do runtime code generation.
  24 Shaders, point/line/triangle rasterization and vertex processing are
  25 implemented with LLVM IR which is translated to x86, x86-64, or ppc64le machine
  26 code.
  27 Also, the driver is multithreaded to take advantage of multiple CPU cores
  28 (up to 8 at this time).
  29 It's the fastest software rasterizer for Mesa.
  30 </p>
  31
  32
  33 <h2>Requirements</h2>
  34
  35 <ul>
  36 <li>
  37    <p>
  38    For x86 or amd64 processors, 64-bit mode is recommended.
  39    Support for SSE2 is strongly encouraged.  Support for SSE3 and SSE4.1 will
  40    yield the most efficient code.  The fewer features the CPU has the more
  41    likely it is that you will run into underperforming, buggy, or incomplete code.
  42    </p>
  43    <p>
  44    For ppc64le processors, use of the Altivec feature (the Vector
  45    Facility) is recommended if supported; use of the VSX feature (the
  46    Vector-Scalar Facility) is recommended if supported AND Mesa is
  47    built with LLVM version 4.0 or later.
  48    </p>
  49    <p>
  50    See /proc/cpuinfo to know what your CPU supports.
  51    </p>
  52 </li>
  53 <li>
  54    <p>Unless otherwise stated, LLVM version 3.4 is recommended; 3.3 or later is required.</p>
  55    <p>
  56    For Linux, on a recent Debian based distribution do:
  57    </p>
  58 <pre>
  59      aptitude install llvm-dev
  60 </pre>
  61    <p>
  62    If you want development snapshot builds of LLVM for Debian and derived
  63    distributions like Ubuntu, you can use the APT repository at <a
  64    href="https://apt.llvm.org/" title="Debian Development packages for LLVM"
  65    >apt.llvm.org</a>, which are maintained by Debian's LLVM maintainer.
  66    </p>
  67    <p>
  68    For a RPM-based distribution do:
  69    </p>
  70 <pre>
  71      yum install llvm-devel
  72 </pre>
  73
  74    <p>
  75    For Windows you will need to build LLVM from source with MSVC or MINGW
  76    (either natively or through cross compilers) and CMake, and set the LLVM
  77    environment variable to the directory you installed it to.
  78
  79    LLVM will be statically linked, so when building on MSVC it needs to be
  80    built with a matching CRT as Mesa, and you'll need to pass
  81    <code>-DLLVM_USE_CRT_xxx=yyy</code> as described below.
  82    </p>
  83
  84    <table border="1">
  85      <tr>
  86        <th rowspan="2">LLVM build-type</th>
  87        <th colspan="2" align="center">Mesa build-type</th>
  88      </tr>
  89      <tr>
  90        <th>debug,checked</th>
  91        <th>release,profile</th>
  92      </tr>
  93      <tr>
  94        <th>Debug</th>
  95        <td><code>-DLLVM_USE_CRT_DEBUG=MTd</code></td>
  96        <td><code>-DLLVM_USE_CRT_DEBUG=MT</code></td>
  97      </tr>
  98      <tr>
  99        <th>Release</th>
 100        <td><code>-DLLVM_USE_CRT_RELEASE=MTd</code></td>
 101        <td><code>-DLLVM_USE_CRT_RELEASE=MT</code></td>
 102      </tr>
 103    </table>
 104
 105    <p>
 106    You can build only the x86 target by passing -DLLVM_TARGETS_TO_BUILD=X86
 107    to cmake.
 108    </p>
 109 </li>
 110
 111 <li>
 112    <p>scons (optional)</p>
 113 </li>
 114 </ul>
 115
 116
 117 <h2>Building</h2>
 118
 119 To build everything on Linux invoke scons as:
 120
 121 <pre>
 122   scons build=debug libgl-xlib
 123 </pre>
 124
 125 Alternatively, you can build it with meson with:
 126 <pre>
 127   mkdir build
 128   cd build
 129   meson -D glx=gallium-xlib -D gallium-drivers=swrast
 130   ninja
 131 </pre>
 132
 133 but the rest of these instructions assume that scons is used.
 134
 135 For Windows the procedure is similar except the target:
 136
 137 <pre>
 138   scons platform=windows build=debug libgl-gdi
 139 </pre>
 140
 141
 142 <h2>Using</h2>
 143
 144 <h3>Linux</h3>
 145
 146 <p>On Linux, building will create a drop-in alternative for libGL.so into</p>
 147
 148 <pre>
 149   build/foo/gallium/targets/libgl-xlib/libGL.so
 150 </pre>
 151 or
 152 <pre>
 153   lib/gallium/libGL.so
 154 </pre>
 155
 156 <p>To use it set the LD_LIBRARY_PATH environment variable accordingly.</p>
 157
 158 <p>For performance evaluation pass build=release to scons, and use the corresponding
 159 lib directory without the "-debug" suffix.</p>
 160
 161
 162 <h3>Windows</h3>
 163
 164 <p>
 165 On Windows, building will create
 166 <code>build/windows-x86-debug/gallium/targets/libgl-gdi/opengl32.dll</code>
 167 which is a drop-in alternative for system's <code>opengl32.dll</code>.  To use
 168 it put it in the same directory as your application.  It can also be used by
 169 replacing the native ICD driver, but it's quite an advanced usage, so if you
 170 need to ask, don't even try it.
 171 </p>
 172
 173 <p>
 174 There is however an easy way to replace the OpenGL software renderer that comes
 175 with Microsoft Windows 7 (or later) with llvmpipe (that is, on systems without
 176 any OpenGL drivers):
 177 </p>
 178
 179 <ul>
 180   <li><p>copy build/windows-x86-debug/gallium/targets/libgl-gdi/opengl32.dll to C:\Windows\SysWOW64\mesadrv.dll</p></li>
 181   <li><p>load this registry settings:</p>
 182   <pre>REGEDIT4
 183
 184 ; https://technet.microsoft.com/en-us/library/cc749368.aspx
 185 ; https://www.msfn.org/board/topic/143241-portable-windows-7-build-from-winpe-30/page-5#entry942596
 186 [HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Windows NT\CurrentVersion\OpenGLDrivers\MSOGL]
 187 "DLL"="mesadrv.dll"
 188 "DriverVersion"=dword:00000001
 189 "Flags"=dword:00000001
 190 "Version"=dword:00000002
 191 </pre>
 192   </li>
 193   <li>Ditto for 64 bits drivers if you need them.</li>
 194 </ul>
 195
 196
 197 <h2>Profiling</h2>
 198
 199 <p>
 200 To profile llvmpipe you should build as
 201 </p>
 202 <pre>
 203   scons build=profile &lt;same-as-before&gt;
 204 </pre>
 205
 206 <p>
 207 This will ensure that frame pointers are used both in C and JIT functions, and
 208 that no tail call optimizations are done by gcc.
 209 </p>
 210
 211 <h3>Linux perf integration</h3>
 212
 213 <p>
 214 On Linux, it is possible to have symbol resolution of JIT code with <a href="https://perf.wiki.kernel.org/">Linux perf</a>:
 215 </p>
 216
 217 <pre>
 218         perf record -g /my/application
 219         perf report
 220 </pre>
 221
 222 <p>
 223 When run inside Linux perf, llvmpipe will create a /tmp/perf-XXXXX.map file with
 224 symbol address table.  It also dumps assembly code to /tmp/perf-XXXXX.map.asm,
 225 which can be used by the bin/perf-annotate-jit.py script to produce disassembly of
 226 the generated code annotated with the samples.
 227 </p>
 228
 229 <p>You can obtain a call graph via
 230 <a href="https://github.com/jrfonseca/gprof2dot#linux-perf">Gprof2Dot</a>.</p>
 231
 232
 233 <h2>Unit testing</h2>
 234
 235 <p>
 236 Building will also create several unit tests in
 237 build/linux-???-debug/gallium/drivers/llvmpipe:
 238 </p>
 239
 240 <ul>
 241 <li> lp_test_blend: blending
 242 <li> lp_test_conv: SIMD vector conversion
 243 <li> lp_test_format: pixel unpacking/packing
 244 </ul>
 245
 246 <p>
 247 Some of these tests can output results and benchmarks to a tab-separated file
 248 for later analysis, e.g.:
 249 </p>
 250 <pre>
 251   build/linux-x86_64-debug/gallium/drivers/llvmpipe/lp_test_blend -o blend.tsv
 252 </pre>
 253
 254
 255 <h2>Development Notes</h2>
 256
 257 <ul>
 258 <li>
 259   When looking at this code for the first time, start in lp_state_fs.c, and
 260   then skim through the lp_bld_* functions called there, and the comments
 261   at the top of the lp_bld_*.c functions.
 262 </li>
 263 <li>
 264   The driver-independent parts of the LLVM / Gallium code are found in
 265   src/gallium/auxiliary/gallivm/.  The filenames and function prefixes
 266   need to be renamed from "lp_bld_" to something else though.
 267 </li>
 268 <li>
 269   We use LLVM-C bindings for now. They are not documented, but follow the C++
 270   interfaces very closely, and appear to be complete enough for code
 271   generation. See
 272   <a href="https://npcontemplation.blogspot.com/2008/06/secret-of-llvm-c-bindings.html">
 273   this stand-alone example</a>.  See the llvm-c/Core.h file for reference.
 274 </li>
 275 </ul>
 276
 277 <h2 id="recommended_reading">Recommended Reading</h2>
 278
 279 <ul>
 280   <li>
 281     <p>Rasterization</p>
 282     <ul>
 283       <li><a href="https://www.cs.unc.edu/~olano/papers/2dh-tri/">Triangle Scan Conversion using 2D Homogeneous Coordinates</a></li>
 284       <li><a href="http://www.drdobbs.com/parallel/rasterization-on-larrabee/217200602">Rasterization on Larrabee</a> (<a href="http://devmaster.net/posts/2887/rasterization-on-larrabee">DevMaster copy</a>)</li>
 285       <li><a href="http://devmaster.net/posts/6133/rasterization-using-half-space-functions">Rasterization using half-space functions</a></li>
 286       <li><a href="http://devmaster.net/posts/6145/advanced-rasterization">Advanced Rasterization</a></li>
 287       <li><a href="https://fgiesen.wordpress.com/2013/02/17/optimizing-sw-occlusion-culling-index/">Optimizing Software Occlusion Culling</a></li>
 288     </ul>
 289   </li>
 290   <li>
 291     <p>Texture sampling</p>
 292     <ul>
 293       <li><a href="http://chrishecker.com/Miscellaneous_Technical_Articles#Perspective_Texture_Mapping">Perspective Texture Mapping</a></li>
 294       <li><a href="https://www.flipcode.com/archives/Texturing_As_In_Unreal.shtml">Texturing As In Unreal</a></li>
 295       <li><a href="http://www.gamasutra.com/view/feature/3301/runtime_mipmap_filtering.php">Run-Time MIP-Map Filtering</a></li>
 296       <li><a href="http://alt.3dcenter.org/artikel/2003/10-26_a_english.php">Will "brilinear" filtering persist?</a></li>
 297       <li><a href="http://ixbtlabs.com/articles2/gffx/nv40-rx800-3.html">Trilinear filtering</a></li>
 298       <li><a href="http://devmaster.net/posts/12785/texture-swizzling">Texture Swizzling</a></li>
 299     </ul>
 300   </li>
 301   <li>
 302     <p>SIMD</p>
 303     <ul>
 304       <li><a href="http://www.cdl.uni-saarland.de/projects/wfv/#header4">Whole-Function Vectorization</a></li>
 305     </ul>
 306   </li>
 307   <li>
 308     <p>Optimization</p>
 309     <ul>
 310       <li><a href="http://www.drdobbs.com/optimizing-pixomatic-for-modern-x86-proc/184405807">Optimizing Pixomatic For Modern x86 Processors</a></li>
 311       <li><a href="http://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-optimization-manual.html">Intel 64 and IA-32 Architectures Optimization Reference Manual</a></li>
 312       <li><a href="http://www.agner.org/optimize/">Software optimization resources</a></li>
 313       <li><a href="https://software.intel.com/en-us/articles/intel-intrinsics-guide">Intel Intrinsics Guide</a></li>
 314     </ul>
 315   </li>
 316   <li>
 317     <p>LLVM</p>
 318     <ul>
 319       <li><a href="http://llvm.org/docs/LangRef.html">LLVM Language Reference Manual</a></li>
 320       <li><a href="https://npcontemplation.blogspot.co.uk/2008/06/secret-of-llvm-c-bindings.html">The secret of LLVM C bindings</a></li>
 321     </ul>
 322   </li>
 323   <li>
 324     <p>General</p>
 325     <ul>
 326       <li><a href="https://fgiesen.wordpress.com/2011/07/09/a-trip-through-the-graphics-pipeline-2011-index/">A trip through the Graphics Pipeline</a></li>
 327       <li><a href="https://msdn.microsoft.com/en-us/library/gg615082.aspx#architecture">WARP Architecture and Performance</a></li>
 328     </ul>
 329   </li>
 330 </ul>
 331
 332 </div>
 333 </body>
 334 </html>