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