Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / mesa3d / 4871128e58402385dc6f920884273c003a1124e1 / . / docs / llvmpipe.html
blob: 80f8a017665d1a8e230096ed3801565f00c24479 [file] [log] [blame]
Andreas Bollecd5c7c2012-06-12 09:05:03 +0200[diff] [blame]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>
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]9
Andreas Bollb5da52a2012-09-18 18:57:02 +0200[diff] [blame]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
Andreas Bollecd5c7c2012-06-12 09:05:03 +0200[diff] [blame]17<h1>Introduction</h1>
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]18
19<p>
20The Gallium llvmpipe driver is a software rasterizer that uses LLVM to
21do runtime code generation.
22Shaders, point/line/triangle rasterization and vertex processing are
23implemented with LLVM IR which is translated to x86 or x86-64 machine
24code.
25Also, the driver is multithreaded to take advantage of multiple CPU cores
26(up to 8 at this time).
27It's the fastest software rasterizer for Mesa.
28</p>
José Fonseca9285f152009-08-10 12:35:16 +0100[diff] [blame]29
30
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]31<h1>Requirements</h1>
José Fonseca9285f152009-08-10 12:35:16 +0100[diff] [blame]32
José Fonseca65d0c842011-11-05 10:38:16 +0000[diff] [blame]33<ul>
34<li>
Andreas Bollfd64b392012-06-12 09:05:49 +0200[diff] [blame]35 <p>An x86 or amd64 processor; 64-bit mode recommended.</p>
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]36 <p>
Matt Turner9f52b872011-11-05 17:11:59 -0400[diff] [blame]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
Andreas Bollfd64b392012-06-12 09:05:49 +0200[diff] [blame]39 likely is that you run into underperforming, buggy, or incomplete code.
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]40 </p>
41 <p>
José Fonsecada1c4022009-11-26 11:15:08 +0000[diff] [blame]42 See /proc/cpuinfo to know what your CPU supports.
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]43 </p>
José Fonseca65d0c842011-11-05 10:38:16 +0000[diff] [blame]44</li>
45<li>
Andreas Bolldf2be222012-06-12 09:05:22 +0200[diff] [blame]46 <p>LLVM: version 2.9 recommended; 2.6 or later required.</p>
47 <p><b>NOTE</b>: LLVM 2.8 and earlier will not work on systems that support the
Brian Paul06613b72011-04-07 13:43:00 -0600[diff] [blame]48 Intel AVX extensions (e.g. Sandybridge). LLVM's code generator will
49 fail when trying to emit AVX instructions. This was fixed in LLVM 2.9.
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]50 </p>
51 <p>
José Fonseca12576552010-01-10 18:37:07 +0000[diff] [blame]52 For Linux, on a recent Debian based distribution do:
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]53 </p>
54<pre>
José Fonseca9285f152009-08-10 12:35:16 +0100[diff] [blame]55 aptitude install llvm-dev
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]56</pre>
Andreas Bolldf2be222012-06-12 09:05:22 +0200[diff] [blame]57 <p>
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]58 For a RPM-based distribution do:
59 </p>
60<pre>
61 yum install llvm-devel
62</pre>
José Fonseca19b31d02009-08-10 15:43:04 +0100[diff] [blame]63
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]64 <p>
José Fonseca65d0c842011-11-05 10:38:16 +0000[diff] [blame]65 For Windows you will need to build LLVM from source with MSVC or MINGW
66 (either natively or through cross compilers) and CMake, and set the LLVM
67 environment variable to the directory you installed it to.
José Fonseca19b31d02009-08-10 15:43:04 +0100[diff] [blame]68
José Fonseca65d0c842011-11-05 10:38:16 +0000[diff] [blame]69 LLVM will be statically linked, so when building on MSVC it needs to be
70 built with a matching CRT as Mesa, and you'll need to pass
71 -DLLVM_USE_CRT_RELEASE=MTd for debug and checked builds,
72 -DLLVM_USE_CRT_RELEASE=MTd for profile and release builds.
José Fonsecaf379e7d2010-05-13 16:18:05 +0100[diff] [blame]73
José Fonseca65d0c842011-11-05 10:38:16 +0000[diff] [blame]74 You can build only the x86 target by passing -DLLVM_TARGETS_TO_BUILD=X86
75 to cmake.
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]76 </p>
José Fonseca65d0c842011-11-05 10:38:16 +0000[diff] [blame]77</li>
José Fonsecaf379e7d2010-05-13 16:18:05 +0100[diff] [blame]78
José Fonseca65d0c842011-11-05 10:38:16 +0000[diff] [blame]79<li>
80 <p>scons (optional)</p>
81</li>
82</ul>
83
José Fonseca9285f152009-08-10 12:35:16 +0100[diff] [blame]84
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]85<h1>Building</h1>
José Fonseca9285f152009-08-10 12:35:16 +0100[diff] [blame]86
José Fonseca12576552010-01-10 18:37:07 +0000[diff] [blame]87To build everything on Linux invoke scons as:
José Fonseca9285f152009-08-10 12:35:16 +0100[diff] [blame]88
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]89<pre>
José Fonseca601498a2010-11-01 13:30:22 +0000[diff] [blame]90 scons build=debug libgl-xlib
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]91</pre>
José Fonseca9285f152009-08-10 12:35:16 +0100[diff] [blame]92
José Fonseca5811ed82009-08-22 22:26:55 +0100[diff] [blame]93Alternatively, you can build it with GNU make, if you prefer, by invoking it as
94
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]95<pre>
José Fonseca5811ed82009-08-22 22:26:55 +0100[diff] [blame]96 make linux-llvm
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]97</pre>
José Fonseca5811ed82009-08-22 22:26:55 +0100[diff] [blame]98
José Fonseca1fc41002009-09-11 11:24:00 +0100[diff] [blame]99but the rest of these instructions assume that scons is used.
José Fonseca5811ed82009-08-22 22:26:55 +0100[diff] [blame]100
José Fonseca65d0c842011-11-05 10:38:16 +0000[diff] [blame]101For Windows the procedure is similar except the target:
José Fonseca12576552010-01-10 18:37:07 +0000[diff] [blame]102
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]103<pre>
José Fonseca601498a2010-11-01 13:30:22 +0000[diff] [blame]104 scons build=debug libgl-gdi
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]105</pre>
José Fonseca9285f152009-08-10 12:35:16 +0100[diff] [blame]106
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]107
108<h1>Using</h1>
José Fonseca9285f152009-08-10 12:35:16 +0100[diff] [blame]109
José Fonseca601498a2010-11-01 13:30:22 +0000[diff] [blame]110On Linux, building will create a drop-in alternative for libGL.so into
José Fonseca9285f152009-08-10 12:35:16 +0100[diff] [blame]111
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]112<pre>
José Fonseca601498a2010-11-01 13:30:22 +0000[diff] [blame]113 build/foo/gallium/targets/libgl-xlib/libGL.so
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]114</pre>
115or
116<pre>
117 lib/gallium/libGL.so
118</pre>
José Fonseca9285f152009-08-10 12:35:16 +0100[diff] [blame]119
José Fonseca601498a2010-11-01 13:30:22 +0000[diff] [blame]120To use it set the LD_LIBRARY_PATH environment variable accordingly.
José Fonseca5811ed82009-08-22 22:26:55 +0100[diff] [blame]121
José Fonseca1fc41002009-09-11 11:24:00 +0100[diff] [blame]122For performance evaluation pass debug=no to scons, and use the corresponding
123lib directory without the "-debug" suffix.
124
José Fonseca12576552010-01-10 18:37:07 +0000[diff] [blame]125On Windows, building will create a drop-in alternative for opengl32.dll. To use
126it put it in the same directory as the application. It can also be used by
127replacing the native ICD driver, but it's quite an advanced usage, so if you
128need to ask, don't even try it.
129
José Fonseca9285f152009-08-10 12:35:16 +0100[diff] [blame]130
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]131<h1>Profiling</h1>
José Fonseca388c9412010-09-21 17:50:30 +0100[diff] [blame]132
José Fonsecab8f68582013-04-17 13:32:15 +0100[diff] [blame]133<p>
134To profile llvmpipe you should build as
135</p>
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]136<pre>
Andreas Boll703a6622012-06-12 09:05:15 +0200[diff] [blame]137 scons build=profile &lt;same-as-before&gt;
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]138</pre>
José Fonseca388c9412010-09-21 17:50:30 +0100[diff] [blame]139
José Fonsecab8f68582013-04-17 13:32:15 +0100[diff] [blame]140<p>
José Fonseca388c9412010-09-21 17:50:30 +0100[diff] [blame]141This will ensure that frame pointers are used both in C and JIT functions, and
142that no tail call optimizations are done by gcc.
José Fonsecab8f68582013-04-17 13:32:15 +0100[diff] [blame]143</p>
José Fonseca388c9412010-09-21 17:50:30 +0100[diff] [blame]144
José Fonsecab8f68582013-04-17 13:32:15 +0100[diff] [blame]145<h2>Linux perf integration</h2>
146
147<p>
148On Linux, it is possible to have symbol resolution of JIT code with <a href="http://perf.wiki.kernel.org/">Linux perf</a>:
149</p>
José Fonseca388c9412010-09-21 17:50:30 +0100[diff] [blame]150
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]151<pre>
José Fonsecab8f68582013-04-17 13:32:15 +0100[diff] [blame]152 perf record -g /my/application
153 perf report
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]154</pre>
José Fonseca388c9412010-09-21 17:50:30 +0100[diff] [blame]155
José Fonsecab8f68582013-04-17 13:32:15 +0100[diff] [blame]156<p>
157When run inside Linux perf, llvmpipe will create a /tmp/perf-XXXXX.map file with
158symbol address table. It also dumps assembly code to /tmp/perf-XXXXX.map.asm,
159which can be used by the bin/perf-annotate-jit script to produce disassembly of
160the generated code annotated with the samples.
161</p>
José Fonseca388c9412010-09-21 17:50:30 +0100[diff] [blame]162
José Fonsecab8f68582013-04-17 13:32:15 +0100[diff] [blame]163<p>You can obtain a call graph via
164<a href="http://code.google.com/p/jrfonseca/wiki/Gprof2Dot#linux_perf">Gprof2Dot</a>.</p>
José Fonseca388c9412010-09-21 17:50:30 +0100[diff] [blame]165
166
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]167<h1>Unit testing</h1>
José Fonseca9285f152009-08-10 12:35:16 +0100[diff] [blame]168
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]169<p>
José Fonseca9285f152009-08-10 12:35:16 +0100[diff] [blame]170Building will also create several unit tests in
171build/linux-???-debug/gallium/drivers/llvmpipe:
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]172</p>
José Fonseca9285f152009-08-10 12:35:16 +0100[diff] [blame]173
Andreas Bolldf2be222012-06-12 09:05:22 +0200[diff] [blame]174<ul>
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]175<li> lp_test_blend: blending
176<li> lp_test_conv: SIMD vector conversion
177<li> lp_test_format: pixel unpacking/packing
178</ul>
José Fonseca9285f152009-08-10 12:35:16 +0100[diff] [blame]179
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]180<p>
José Fonseca1fc41002009-09-11 11:24:00 +0100[diff] [blame]181Some of this tests can output results and benchmarks to a tab-separated-file
José Fonseca89146cd2009-08-20 10:21:49 +0100[diff] [blame]182for posterior analysis, e.g.:
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]183</p>
184<pre>
José Fonseca5811ed82009-08-22 22:26:55 +0100[diff] [blame]185 build/linux-x86_64-debug/gallium/drivers/llvmpipe/lp_test_blend -o blend.tsv
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]186</pre>
José Fonseca9285f152009-08-10 12:35:16 +0100[diff] [blame]187
José Fonsecac5531f52009-08-21 10:57:48 +0100[diff] [blame]188
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]189<h1>Development Notes</h1>
José Fonsecac5531f52009-08-21 10:57:48 +0100[diff] [blame]190
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]191<ul>
192<li>
193 When looking to this code by the first time start in lp_state_fs.c, and
José Fonseca5811ed82009-08-22 22:26:55 +0100[diff] [blame]194 then skim through the lp_bld_* functions called in there, and the comments
Andreas Bollfd64b392012-06-12 09:05:49 +0200[diff] [blame]195 at the top of the lp_bld_*.c functions.
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]196</li>
197<li>
198 The driver-independent parts of the LLVM / Gallium code are found in
Brian Pauld0b35352010-03-15 11:46:41 -0600[diff] [blame]199 src/gallium/auxiliary/gallivm/. The filenames and function prefixes
200 need to be renamed from "lp_bld_" to something else though.
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]201</li>
202<li>
203 We use LLVM-C bindings for now. They are not documented, but follow the C++
José Fonsecac5531f52009-08-21 10:57:48 +0100[diff] [blame]204 interfaces very closely, and appear to be complete enough for code
205 generation. See
206 http://npcontemplation.blogspot.com/2008/06/secret-of-llvm-c-bindings.html
José Fonseca601498a2010-11-01 13:30:22 +0000[diff] [blame]207 for a stand-alone example. See the llvm-c/Core.h file for reference.
Brian Paul0da2a222011-04-07 13:56:45 -0600[diff] [blame]208</li>
209</ul>
Andreas Bollecd5c7c2012-06-12 09:05:03 +0200[diff] [blame]210
Andreas Bollb5da52a2012-09-18 18:57:02 +0200[diff] [blame]211</div>
Andreas Bollecd5c7c2012-06-12 09:05:03 +0200[diff] [blame]212</body>
213</html>