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