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