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