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 meson with:
 124 <pre>
 125   mkdir build
 126   cd build
 127   meson -D glx=gallium-xlib -D gallium-drivers=swrast
 128   ninja
 129 </pre>
 130
 131 but the rest of these instructions assume that scons is used.
 132
 133 For Windows the procedure is similar except the target:
 134
 135 <pre>
 136   scons platform=windows build=debug libgl-gdi
 137 </pre>
 138
 139
 140 <h1>Using</h1>
 141
 142 <h2>Linux</h2>
 143
 144 <p>On Linux, building will create a drop-in alternative for libGL.so into</p>
 145
 146 <pre>
 147   build/foo/gallium/targets/libgl-xlib/libGL.so
 148 </pre>
 149 or
 150 <pre>
 151   lib/gallium/libGL.so
 152 </pre>
 153
 154 <p>To use it set the LD_LIBRARY_PATH environment variable accordingly.</p>
 155
 156 <p>For performance evaluation pass build=release to scons, and use the corresponding
 157 lib directory without the "-debug" suffix.</p>
 158
 159
 160 <h2>Windows</h2>
 161
 162 <p>
 163 On Windows, building will create
 164 <code>build/windows-x86-debug/gallium/targets/libgl-gdi/opengl32.dll</code>
 165 which is a drop-in alternative for system's <code>opengl32.dll</code>.  To use
 166 it put it in the same directory as your application.  It can also be used by
 167 replacing the native ICD driver, but it's quite an advanced usage, so if you
 168 need to ask, don't even try it.
 169 </p>
 170
 171 <p>
 172 There is however an easy way to replace the OpenGL software renderer that comes
 173 with Microsoft Windows 7 (or later) with llvmpipe (that is, on systems without
 174 any OpenGL drivers):
 175 </p>
 176
 177 <ul>
 178   <li><p>copy build/windows-x86-debug/gallium/targets/libgl-gdi/opengl32.dll to C:\Windows\SysWOW64\mesadrv.dll</p></li>
 179   <li><p>load this registry settings:</p>
 180   <pre>REGEDIT4
 181
 182 ; https://technet.microsoft.com/en-us/library/cc749368.aspx
 183 ; https://www.msfn.org/board/topic/143241-portable-windows-7-build-from-winpe-30/page-5#entry942596
 184 [HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Windows NT\CurrentVersion\OpenGLDrivers\MSOGL]
 185 "DLL"="mesadrv.dll"
 186 "DriverVersion"=dword:00000001
 187 "Flags"=dword:00000001
 188 "Version"=dword:00000002
 189 </pre>
 190   </li>
 191   <li>Ditto for 64 bits drivers if you need them.</li>
 192 </ul>
 193
 194
 195 <h1>Profiling</h1>
 196
 197 <p>
 198 To profile llvmpipe you should build as
 199 </p>
 200 <pre>
 201   scons build=profile &lt;same-as-before&gt;
 202 </pre>
 203
 204 <p>
 205 This will ensure that frame pointers are used both in C and JIT functions, and
 206 that no tail call optimizations are done by gcc.
 207 </p>
 208
 209 <h2>Linux perf integration</h2>
 210
 211 <p>
 212 On Linux, it is possible to have symbol resolution of JIT code with <a href="https://perf.wiki.kernel.org/">Linux perf</a>:
 213 </p>
 214
 215 <pre>
 216         perf record -g /my/application
 217         perf report
 218 </pre>
 219
 220 <p>
 221 When run inside Linux perf, llvmpipe will create a /tmp/perf-XXXXX.map file with
 222 symbol address table.  It also dumps assembly code to /tmp/perf-XXXXX.map.asm,
 223 which can be used by the bin/perf-annotate-jit.py script to produce disassembly of
 224 the generated code annotated with the samples.
 225 </p>
 226
 227 <p>You can obtain a call graph via
 228 <a href="https://github.com/jrfonseca/gprof2dot#linux-perf">Gprof2Dot</a>.</p>
 229
 230
 231 <h1>Unit testing</h1>
 232
 233 <p>
 234 Building will also create several unit tests in
 235 build/linux-???-debug/gallium/drivers/llvmpipe:
 236 </p>
 237
 238 <ul>
 239 <li> lp_test_blend: blending
 240 <li> lp_test_conv: SIMD vector conversion
 241 <li> lp_test_format: pixel unpacking/packing
 242 </ul>
 243
 244 <p>
 245 Some of these tests can output results and benchmarks to a tab-separated file
 246 for later analysis, e.g.:
 247 </p>
 248 <pre>
 249   build/linux-x86_64-debug/gallium/drivers/llvmpipe/lp_test_blend -o blend.tsv
 250 </pre>
 251
 252
 253 <h1>Development Notes</h1>
 254
 255 <ul>
 256 <li>
 257   When looking at this code for the first time, start in lp_state_fs.c, and
 258   then skim through the lp_bld_* functions called there, and the comments
 259   at the top of the lp_bld_*.c functions.
 260 </li>
 261 <li>
 262   The driver-independent parts of the LLVM / Gallium code are found in
 263   src/gallium/auxiliary/gallivm/.  The filenames and function prefixes
 264   need to be renamed from "lp_bld_" to something else though.
 265 </li>
 266 <li>
 267   We use LLVM-C bindings for now. They are not documented, but follow the C++
 268   interfaces very closely, and appear to be complete enough for code
 269   generation. See
 270   <a href="https://npcontemplation.blogspot.com/2008/06/secret-of-llvm-c-bindings.html">
 271   this stand-alone example</a>.  See the llvm-c/Core.h file for reference.
 272 </li>
 273 </ul>
 274
 275 <h1 id="recommended_reading">Recommended Reading</h1>
 276
 277 <ul>
 278   <li>
 279     <p>Rasterization</p>
 280     <ul>
 281       <li><a href="https://www.cs.unc.edu/~olano/papers/2dh-tri/">Triangle Scan Conversion using 2D Homogeneous Coordinates</a></li>
 282       <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>
 283       <li><a href="http://devmaster.net/posts/6133/rasterization-using-half-space-functions">Rasterization using half-space functions</a></li>
 284       <li><a href="http://devmaster.net/posts/6145/advanced-rasterization">Advanced Rasterization</a></li>
 285       <li><a href="https://fgiesen.wordpress.com/2013/02/17/optimizing-sw-occlusion-culling-index/">Optimizing Software Occlusion Culling</a></li>
 286     </ul>
 287   </li>
 288   <li>
 289     <p>Texture sampling</p>
 290     <ul>
 291       <li><a href="http://chrishecker.com/Miscellaneous_Technical_Articles#Perspective_Texture_Mapping">Perspective Texture Mapping</a></li>
 292       <li><a href="https://www.flipcode.com/archives/Texturing_As_In_Unreal.shtml">Texturing As In Unreal</a></li>
 293       <li><a href="http://www.gamasutra.com/view/feature/3301/runtime_mipmap_filtering.php">Run-Time MIP-Map Filtering</a></li>
 294       <li><a href="http://alt.3dcenter.org/artikel/2003/10-26_a_english.php">Will "brilinear" filtering persist?</a></li>
 295       <li><a href="http://ixbtlabs.com/articles2/gffx/nv40-rx800-3.html">Trilinear filtering</a></li>
 296       <li><a href="http://devmaster.net/posts/12785/texture-swizzling">Texture Swizzling</a></li>
 297     </ul>
 298   </li>
 299   <li>
 300     <p>SIMD</p>
 301     <ul>
 302       <li><a href="http://www.cdl.uni-saarland.de/projects/wfv/#header4">Whole-Function Vectorization</a></li>
 303     </ul>
 304   </li>
 305   <li>
 306     <p>Optimization</p>
 307     <ul>
 308       <li><a href="http://www.drdobbs.com/optimizing-pixomatic-for-modern-x86-proc/184405807">Optimizing Pixomatic For Modern x86 Processors</a></li>
 309       <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>
 310       <li><a href="http://www.agner.org/optimize/">Software optimization resources</a></li>
 311       <li><a href="https://software.intel.com/en-us/articles/intel-intrinsics-guide">Intel Intrinsics Guide</a><li>
 312     </ul>
 313   </li>
 314   <li>
 315     <p>LLVM</p>
 316     <ul>
 317       <li><a href="http://llvm.org/docs/LangRef.html">LLVM Language Reference Manual</a></li>
 318       <li><a href="https://npcontemplation.blogspot.co.uk/2008/06/secret-of-llvm-c-bindings.html">The secret of LLVM C bindings</a></li>
 319     </ul>
 320   </li>
 321   <li>
 322     <p>General</p>
 323     <ul>
 324       <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>
 325       <li><a href="https://msdn.microsoft.com/en-us/library/gg615082.aspx#architecture">WARP Architecture and Performance</a></li>
 326     </ul>
 327   </li>
 328 </ul>
 329
 330 </div>
 331 </body>
 332 </html>