214 lines
5.5 KiB
HTML
214 lines
5.5 KiB
HTML
<!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>
|
|
|
|
<div class="header">
|
|
<h1>The Mesa 3D Graphics Library</h1>
|
|
</div>
|
|
|
|
<iframe src="contents.html"></iframe>
|
|
<div class="content">
|
|
|
|
<h1>Introduction</h1>
|
|
|
|
<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>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>An x86 or amd64 processor; 64-bit mode recommended.</p>
|
|
<p>
|
|
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
|
|
likely is that you run into underperforming, buggy, or incomplete code.
|
|
</p>
|
|
<p>
|
|
See /proc/cpuinfo to know what your CPU supports.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>LLVM: version 2.9 recommended; 2.6 or later required.</p>
|
|
<p><b>NOTE</b>: LLVM 2.8 and earlier will not work on systems that support the
|
|
Intel AVX extensions (e.g. Sandybridge). LLVM's code generator will
|
|
fail when trying to emit AVX instructions. This was fixed in LLVM 2.9.
|
|
</p>
|
|
<p>
|
|
For Linux, on a recent Debian based distribution do:
|
|
</p>
|
|
<pre>
|
|
aptitude install llvm-dev
|
|
</pre>
|
|
<p>
|
|
For a RPM-based distribution do:
|
|
</p>
|
|
<pre>
|
|
yum install llvm-devel
|
|
</pre>
|
|
|
|
<p>
|
|
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.
|
|
|
|
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
|
|
-DLLVM_USE_CRT_RELEASE=MTd for debug and checked builds,
|
|
-DLLVM_USE_CRT_RELEASE=MTd for profile and release builds.
|
|
|
|
You can build only the x86 target by passing -DLLVM_TARGETS_TO_BUILD=X86
|
|
to cmake.
|
|
</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>scons (optional)</p>
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
<h1>Building</h1>
|
|
|
|
To build everything on Linux invoke scons as:
|
|
|
|
<pre>
|
|
scons build=debug libgl-xlib
|
|
</pre>
|
|
|
|
Alternatively, you can build it with GNU make, if you prefer, by invoking it as
|
|
|
|
<pre>
|
|
make linux-llvm
|
|
</pre>
|
|
|
|
but the rest of these instructions assume that scons is used.
|
|
|
|
For Windows the procedure is similar except the target:
|
|
|
|
<pre>
|
|
scons build=debug libgl-gdi
|
|
</pre>
|
|
|
|
|
|
<h1>Using</h1>
|
|
|
|
On Linux, building will create a drop-in alternative for libGL.so into
|
|
|
|
<pre>
|
|
build/foo/gallium/targets/libgl-xlib/libGL.so
|
|
</pre>
|
|
or
|
|
<pre>
|
|
lib/gallium/libGL.so
|
|
</pre>
|
|
|
|
To use it set the LD_LIBRARY_PATH environment variable accordingly.
|
|
|
|
For performance evaluation pass debug=no to scons, and use the corresponding
|
|
lib directory without the "-debug" suffix.
|
|
|
|
On Windows, building will create a drop-in alternative for opengl32.dll. To use
|
|
it put it in the same directory as the application. It can also be used by
|
|
replacing the native ICD driver, but it's quite an advanced usage, so if you
|
|
need to ask, don't even try it.
|
|
|
|
|
|
<h1>Profiling</h1>
|
|
|
|
<p>
|
|
To profile llvmpipe you should build as
|
|
</p>
|
|
<pre>
|
|
scons build=profile <same-as-before>
|
|
</pre>
|
|
|
|
<p>
|
|
This will ensure that frame pointers are used both in C and JIT functions, and
|
|
that no tail call optimizations are done by gcc.
|
|
</p>
|
|
|
|
<h2>Linux perf integration</h2>
|
|
|
|
<p>
|
|
On Linux, it is possible to have symbol resolution of JIT code with <a href="http://perf.wiki.kernel.org/">Linux perf</a>:
|
|
</p>
|
|
|
|
<pre>
|
|
perf record -g /my/application
|
|
perf report
|
|
</pre>
|
|
|
|
<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
|
|
<a href="http://code.google.com/p/jrfonseca/wiki/Gprof2Dot#linux_perf">Gprof2Dot</a>.</p>
|
|
|
|
|
|
<h1>Unit testing</h1>
|
|
|
|
<p>
|
|
Building will also create several unit tests in
|
|
build/linux-???-debug/gallium/drivers/llvmpipe:
|
|
</p>
|
|
|
|
<ul>
|
|
<li> lp_test_blend: blending
|
|
<li> lp_test_conv: SIMD vector conversion
|
|
<li> lp_test_format: pixel unpacking/packing
|
|
</ul>
|
|
|
|
<p>
|
|
Some of this tests can output results and benchmarks to a tab-separated-file
|
|
for posterior analysis, e.g.:
|
|
</p>
|
|
<pre>
|
|
build/linux-x86_64-debug/gallium/drivers/llvmpipe/lp_test_blend -o blend.tsv
|
|
</pre>
|
|
|
|
|
|
<h1>Development Notes</h1>
|
|
|
|
<ul>
|
|
<li>
|
|
When looking to this code by the first time start in lp_state_fs.c, and
|
|
then skim through the lp_bld_* functions called in there, and the comments
|
|
at the top of the lp_bld_*.c functions.
|
|
</li>
|
|
<li>
|
|
The driver-independent parts of the LLVM / Gallium code are found in
|
|
src/gallium/auxiliary/gallivm/. The filenames and function prefixes
|
|
need to be renamed from "lp_bld_" to something else though.
|
|
</li>
|
|
<li>
|
|
We use LLVM-C bindings for now. They are not documented, but follow the C++
|
|
interfaces very closely, and appear to be complete enough for code
|
|
generation. See
|
|
http://npcontemplation.blogspot.com/2008/06/secret-of-llvm-c-bindings.html
|
|
for a stand-alone example. See the llvm-c/Core.h file for reference.
|
|
</li>
|
|
</ul>
|
|
|
|
</div>
|
|
</body>
|
|
</html>
|