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