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