llvmpipe.html 9.71 KB
Newer Older
1 2 3 4 5 6 7 8
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en">
<head>
  <meta http-equiv="content-type" content="text/html; charset=utf-8">
  <title>llvmpipe</title>
  <link rel="stylesheet" type="text/css" href="mesa.css">
</head>
<body>
9

Andreas Boll's avatar
Andreas Boll committed
10 11 12 13 14 15 16
<div class="header">
  <h1>The Mesa 3D Graphics Library</h1>
</div>

<iframe src="contents.html"></iframe>
<div class="content">

17
<h1>Introduction</h1>
18 19 20 21 22 23 24 25 26 27 28 29 30 31 32

<p>
The Gallium llvmpipe driver is a software rasterizer that uses LLVM to
do runtime code generation.
Shaders, point/line/triangle rasterization and vertex processing are
implemented with LLVM IR which is translated to x86 or x86-64 machine
code.
Also, the driver is multithreaded to take advantage of multiple CPU cores
(up to 8 at this time).
It's the fastest software rasterizer for Mesa.
</p>


<h1>Requirements</h1>

Jose Fonseca's avatar
Jose Fonseca committed
33 34
<ul>
<li>
Andreas Boll's avatar
Andreas Boll committed
35
   <p>An x86 or amd64 processor; 64-bit mode recommended.</p>
36
   <p>
37 38
   Support for SSE2 is strongly encouraged.  Support for SSSE3 and SSE4.1 will
   yield the most efficient code.  The fewer features the CPU has the more
Andreas Boll's avatar
Andreas Boll committed
39
   likely is that you run into underperforming, buggy, or incomplete code.
40 41
   </p>
   <p>
42
   See /proc/cpuinfo to know what your CPU supports.
43
   </p>
Jose Fonseca's avatar
Jose Fonseca committed
44 45
</li>
<li>
46
   <p>LLVM: version 3.4 recommended; 3.3 or later required.</p>
47
   <p>
Jose Fonseca's avatar
Jose Fonseca committed
48
   For Linux, on a recent Debian based distribution do:
49 50
   </p>
<pre>
51
     aptitude install llvm-dev
52
</pre>
Andreas Boll's avatar
Andreas Boll committed
53
   <p>
54 55 56 57 58 59 60
   For a RPM-based distribution do:
   </p>
<pre>
     yum install llvm-devel
</pre>

   <p>
61 62 63
   For Windows you will need to build LLVM from source with MSVC or MINGW
   (either natively or through cross compilers) and CMake, and set the LLVM
   environment variable to the directory you installed it to.
Jose Fonseca's avatar
Jose Fonseca committed
64

Jose Fonseca's avatar
Jose Fonseca committed
65 66
   LLVM will be statically linked, so when building on MSVC it needs to be
   built with a matching CRT as Mesa, and you'll need to pass
67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89
   <code>-DLLVM_USE_CRT_xxx=yyy</code> as described below.
   </p>

   <table border="1">
     <tr>
       <th rowspan="2">LLVM build-type</th>
       <th colspan="2" align="center">Mesa build-type</th>
     </tr>
     <tr>
       <th>debug,checked</th>
       <th>release,profile</th>
     </tr>
     <tr>
       <th>Debug</th>
       <td><code>-DLLVM_USE_CRT_DEBUG=MTd</code></td>
       <td><code>-DLLVM_USE_CRT_DEBUG=MT</code></td>
     </tr>
     <tr>
       <th>Release</th>
       <td><code>-DLLVM_USE_CRT_RELEASE=MTd</code></td>
       <td><code>-DLLVM_USE_CRT_RELEASE=MT</code></td>
     </tr>
   </table>
90

91
   <p>
Jose Fonseca's avatar
Jose Fonseca committed
92 93
   You can build only the x86 target by passing -DLLVM_TARGETS_TO_BUILD=X86
   to cmake.
94
   </p>
Jose Fonseca's avatar
Jose Fonseca committed
95 96 97 98 99 100
</li>

<li>
   <p>scons (optional)</p>
</li>
</ul>
101

102

103
<h1>Building</h1>
104

Jose Fonseca's avatar
Jose Fonseca committed
105
To build everything on Linux invoke scons as:
106

107
<pre>
108
  scons build=debug libgl-xlib
109
</pre>
110

111 112
Alternatively, you can build it with GNU make, if you prefer, by invoking it as

113
<pre>
114
  make linux-llvm
115
</pre>
116

117
but the rest of these instructions assume that scons is used.
118

Jose Fonseca's avatar
Jose Fonseca committed
119
For Windows the procedure is similar except the target:
Jose Fonseca's avatar
Jose Fonseca committed
120

121
<pre>
122
  scons platform=windows build=debug libgl-gdi
123 124
</pre>

125

126
<h1>Using</h1>
127

128 129 130
<h2>Linux</h2>

<p>On Linux, building will create a drop-in alternative for libGL.so into</p>
131

132
<pre>
133
  build/foo/gallium/targets/libgl-xlib/libGL.so
134 135 136 137 138
</pre>
or
<pre>
  lib/gallium/libGL.so
</pre>
139

140 141 142 143 144
<p>To use it set the LD_LIBRARY_PATH environment variable accordingly.</p>

<p>For performance evaluation pass build=release to scons, and use the corresponding
lib directory without the "-debug" suffix.</p>

145

146
<h2>Windows</h2>
147

148 149 150 151 152
<p>
On Windows, building will create
<code>build/windows-x86-debug/gallium/targets/libgl-gdi/opengl32.dll</code>
which is a drop-in alternative for system's <code>opengl32.dll</code>.  To use
it put it in the same directory as your application.  It can also be used by
Jose Fonseca's avatar
Jose Fonseca committed
153 154
replacing the native ICD driver, but it's quite an advanced usage, so if you
need to ask, don't even try it.
155 156 157 158 159 160 161 162 163 164 165 166 167
</p>

<p>
There is however an easy way to replace the OpenGL software renderer that comes
with Microsoft Windows 7 (or later) with llvmpipe (that is, on systems without
any OpenGL drivers):
</p>

<ul>
  <li><p>copy build/windows-x86-debug/gallium/targets/libgl-gdi/opengl32.dll to C:\Windows\SysWOW64\mesadrv.dll</p></li>
  <li><p>load this registry settings:</p>
  <pre>REGEDIT4

Eric Engestrom's avatar
Eric Engestrom committed
168 169
; https://technet.microsoft.com/en-us/library/cc749368.aspx
; https://www.msfn.org/board/topic/143241-portable-windows-7-build-from-winpe-30/page-5#entry942596
170 171 172 173 174 175 176 177 178
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Windows NT\CurrentVersion\OpenGLDrivers\MSOGL]
"DLL"="mesadrv.dll"
"DriverVersion"=dword:00000001
"Flags"=dword:00000001
"Version"=dword:00000002
</pre>
  </li>
  <li>Ditto for 64 bits drivers if you need them.</li>
</ul>
Jose Fonseca's avatar
Jose Fonseca committed
179

180

181
<h1>Profiling</h1>
182

183 184 185
<p>
To profile llvmpipe you should build as
</p>
186
<pre>
Andreas Boll's avatar
Andreas Boll committed
187
  scons build=profile &lt;same-as-before&gt;
188
</pre>
189

190
<p>
191 192
This will ensure that frame pointers are used both in C and JIT functions, and
that no tail call optimizations are done by gcc.
193
</p>
194

195
<h2>Linux perf integration</h2>
196

197
<p>
Eric Engestrom's avatar
Eric Engestrom committed
198
On Linux, it is possible to have symbol resolution of JIT code with <a href="https://perf.wiki.kernel.org/">Linux perf</a>:
199
</p>
200

201
<pre>
202 203
	perf record -g /my/application
	perf report
204
</pre>
205

206 207 208 209 210 211 212 213
<p>
When run inside Linux perf, llvmpipe will create a /tmp/perf-XXXXX.map file with
symbol address table.  It also dumps assembly code to /tmp/perf-XXXXX.map.asm,
which can be used by the bin/perf-annotate-jit script to produce disassembly of
the generated code annotated with the samples.
</p>

<p>You can obtain a call graph via
Eric Engestrom's avatar
Eric Engestrom committed
214
<a href="https://github.com/jrfonseca/gprof2dot#linux-perf">Gprof2Dot</a>.</p>
215 216


217
<h1>Unit testing</h1>
218

219
<p>
220 221
Building will also create several unit tests in
build/linux-???-debug/gallium/drivers/llvmpipe:
222
</p>
223

Andreas Boll's avatar
Andreas Boll committed
224
<ul>
225 226 227 228
<li> lp_test_blend: blending
<li> lp_test_conv: SIMD vector conversion
<li> lp_test_format: pixel unpacking/packing
</ul>
229

230
<p>
231
Some of this tests can output results and benchmarks to a tab-separated-file
232
for posterior analysis, e.g.:
233 234
</p>
<pre>
235
  build/linux-x86_64-debug/gallium/drivers/llvmpipe/lp_test_blend -o blend.tsv
236
</pre>
237

238

239
<h1>Development Notes</h1>
240

241 242 243
<ul>
<li>
  When looking to this code by the first time start in lp_state_fs.c, and 
244
  then skim through the lp_bld_* functions called in there, and the comments
Andreas Boll's avatar
Andreas Boll committed
245
  at the top of the lp_bld_*.c functions.
246 247 248
</li>
<li>
  The driver-independent parts of the LLVM / Gallium code are found in
249 250
  src/gallium/auxiliary/gallivm/.  The filenames and function prefixes
  need to be renamed from "lp_bld_" to something else though.
251 252 253
</li>
<li>
  We use LLVM-C bindings for now. They are not documented, but follow the C++
254 255
  interfaces very closely, and appear to be complete enough for code
  generation. See 
Eric Engestrom's avatar
Eric Engestrom committed
256
  <a href="https://npcontemplation.blogspot.com/2008/06/secret-of-llvm-c-bindings.html">
257
  this stand-alone example</a>.  See the llvm-c/Core.h file for reference.
258 259
</li>
</ul>
260

261 262 263 264 265 266
<h1 id="recommended_reading">Recommended Reading</h1>

<ul>
  <li>
    <p>Rasterization</p>
    <ul>
Eric Engestrom's avatar
Eric Engestrom committed
267
      <li><a href="https://www.cs.unc.edu/~olano/papers/2dh-tri/">Triangle Scan Conversion using 2D Homogeneous Coordinates</a></li>
268 269 270
      <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>
      <li><a href="http://devmaster.net/posts/6133/rasterization-using-half-space-functions">Rasterization using half-space functions</a></li>
      <li><a href="http://devmaster.net/posts/6145/advanced-rasterization">Advanced Rasterization</a></li>
Eric Engestrom's avatar
Eric Engestrom committed
271
      <li><a href="https://fgiesen.wordpress.com/2013/02/17/optimizing-sw-occlusion-culling-index/">Optimizing Software Occlusion Culling</a></li>
272 273 274 275 276 277
    </ul>
  </li>
  <li>
    <p>Texture sampling</p>
    <ul>
      <li><a href="http://chrishecker.com/Miscellaneous_Technical_Articles#Perspective_Texture_Mapping">Perspective Texture Mapping</a></li>
Eric Engestrom's avatar
Eric Engestrom committed
278
      <li><a href="https://www.flipcode.com/archives/Texturing_As_In_Unreal.shtml">Texturing As In Unreal</a></li>
279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296
      <li><a href="http://www.gamasutra.com/view/feature/3301/runtime_mipmap_filtering.php">Run-Time MIP-Map Filtering</a></li>
      <li><a href="http://alt.3dcenter.org/artikel/2003/10-26_a_english.php">Will "brilinear" filtering persist?</a></li>
      <li><a href="http://ixbtlabs.com/articles2/gffx/nv40-rx800-3.html">Trilinear filtering</a></li>
      <li><a href="http://devmaster.net/posts/12785/texture-swizzling">Texture Swizzling</a></li>
    </ul>
  </li>
  <li>
    <p>SIMD</p>
    <ul>
      <li><a href="http://www.cdl.uni-saarland.de/projects/wfv/#header4">Whole-Function Vectorization</a></li>
    </ul>
  </li>
  <li>
    <p>Optimization</p>
    <ul>
      <li><a href="http://www.drdobbs.com/optimizing-pixomatic-for-modern-x86-proc/184405807">Optimizing Pixomatic For Modern x86 Processors</a></li>
      <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>
      <li><a href="http://www.agner.org/optimize/">Software optimization resources</a></li>
Eric Engestrom's avatar
Eric Engestrom committed
297
      <li><a href="https://software.intel.com/en-us/articles/intel-intrinsics-guide">Intel Intrinsics Guide</a><li>
298 299 300 301 302 303
    </ul>
  </li>
  <li>
    <p>LLVM</p>
    <ul>
      <li><a href="http://llvm.org/docs/LangRef.html">LLVM Language Reference Manual</a></li>
Eric Engestrom's avatar
Eric Engestrom committed
304
      <li><a href="https://npcontemplation.blogspot.co.uk/2008/06/secret-of-llvm-c-bindings.html">The secret of LLVM C bindings</a></li>
305 306 307
    </ul>
  </li>
  <li>
308
    <p>General</p>
309
    <ul>
Eric Engestrom's avatar
Eric Engestrom committed
310 311
      <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>
      <li><a href="https://msdn.microsoft.com/en-us/library/gg615082.aspx#architecture">WARP Architecture and Performance</a></li>
312 313 314 315
    </ul>
  </li>
</ul>

Andreas Boll's avatar
Andreas Boll committed
316
</div>
317 318
</body>
</html>