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