<html lang="en">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
- <title>llvmpipe</title>
+ <title>Gallium LLVMpipe Driver</title>
<link rel="stylesheet" type="text/css" href="mesa.css">
</head>
<body>
<div class="header">
- <h1>The Mesa 3D Graphics Library</h1>
+ The Mesa 3D Graphics Library
</div>
<iframe src="contents.html"></iframe>
<div class="content">
-<h1>Introduction</h1>
+<h1>Gallium LLVMpipe Driver</h1>
+
+<h2>Introduction</h2>
<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
+implemented with LLVM IR which is translated to x86, x86-64, or ppc64le machine
code.
Also, the driver is multithreaded to take advantage of multiple CPU cores
(up to 8 at this time).
</p>
-<h1>Requirements</h1>
+<h2>Requirements</h2>
<ul>
<li>
- <p>An x86 or amd64 processor; 64-bit mode recommended.</p>
<p>
+ For x86 or amd64 processors, 64-bit mode is recommended.
Support for SSE2 is strongly encouraged. Support for SSE3 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.
+ likely it is that you will run into underperforming, buggy, or incomplete code.
+ </p>
+ <p>
+ For ppc64le processors, use of the Altivec feature (the Vector
+ Facility) is recommended if supported; use of the VSX feature (the
+ Vector-Scalar Facility) is recommended if supported AND Mesa is
+ built with LLVM version 4.0 or later.
</p>
<p>
- See /proc/cpuinfo to know what your CPU supports.
+ See <code>/proc/cpuinfo</code> to know what your CPU supports.
</p>
</li>
<li>
- <p>LLVM: version 3.4 recommended; 3.3 or later required.</p>
+ <p>Unless otherwise stated, LLVM version 3.4 is recommended; 3.3 or later is required.</p>
<p>
For Linux, on a recent Debian based distribution do:
</p>
<pre>
aptitude install llvm-dev
</pre>
+ <p>
+ If you want development snapshot builds of LLVM for Debian and derived
+ distributions like Ubuntu, you can use the APT repository at <a
+ href="https://apt.llvm.org/" title="Debian Development packages for LLVM"
+ >apt.llvm.org</a>, which are maintained by Debian's LLVM maintainer.
+ </p>
<p>
For a RPM-based distribution do:
</p>
<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.
+ (either natively or through cross compilers) and CMake, and set the
+ <code>LLVM</code> 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
</table>
<p>
- You can build only the x86 target by passing -DLLVM_TARGETS_TO_BUILD=X86
- to cmake.
+ You can build only the x86 target by passing
+ <code>-DLLVM_TARGETS_TO_BUILD=X86</code> to cmake.
</p>
</li>
</ul>
-<h1>Building</h1>
+<h2>Building</h2>
To build everything on Linux invoke scons as:
scons build=debug libgl-xlib
</pre>
-Alternatively, you can build it with autoconf/make with:
+Alternatively, you can build it with meson with:
<pre>
- ./configure --enable-glx=gallium-xlib --with-gallium-drivers=swrast --disable-dri --disable-gbm --disable-egl
- make
+ mkdir build
+ cd build
+ meson -D glx=gallium-xlib -D gallium-drivers=swrast
+ ninja
</pre>
but the rest of these instructions assume that scons is used.
</pre>
-<h1>Using</h1>
+<h2>Using</h2>
-<h2>Linux</h2>
+<h3>Linux</h3>
-<p>On Linux, building will create a drop-in alternative for libGL.so into</p>
+<p>On Linux, building will create a drop-in alternative for
+<code>libGL.so</code> into</p>
<pre>
build/foo/gallium/targets/libgl-xlib/libGL.so
lib/gallium/libGL.so
</pre>
-<p>To use it set the LD_LIBRARY_PATH environment variable accordingly.</p>
+<p>To use it set the <code>LD_LIBRARY_PATH</code> environment variable
+accordingly.</p>
-<p>For performance evaluation pass build=release to scons, and use the corresponding
-lib directory without the "-debug" suffix.</p>
+<p>For performance evaluation pass <code>build=release</code> to scons,
+and use the corresponding lib directory without the <code>-debug</code>
+suffix.</p>
-<h2>Windows</h2>
+<h3>Windows</h3>
<p>
On Windows, building will create
</p>
<ul>
- <li><p>copy build/windows-x86-debug/gallium/targets/libgl-gdi/opengl32.dll to C:\Windows\SysWOW64\mesadrv.dll</p></li>
+ <li><p>copy <code>build/windows-x86-debug/gallium/targets/libgl-gdi/opengl32.dll</code>
+ to <code>C:\Windows\SysWOW64\mesadrv.dll</code>
+ </p></li>
<li><p>load this registry settings:</p>
<pre>REGEDIT4
</ul>
-<h1>Profiling</h1>
+<h2>Profiling</h2>
<p>
To profile llvmpipe you should build as
that no tail call optimizations are done by gcc.
</p>
-<h2>Linux perf integration</h2>
+<h3>Linux perf integration</h3>
<p>
On Linux, it is possible to have symbol resolution of JIT code with <a href="https://perf.wiki.kernel.org/">Linux perf</a>:
</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.py script to produce disassembly of
-the generated code annotated with the samples.
+When run inside Linux perf, llvmpipe will create a
+<code>/tmp/perf-XXXXX.map</code> file with symbol address table. It also
+dumps assembly code to <code>/tmp/perf-XXXXX.map.asm</code>, which can be
+used by the <code>bin/perf-annotate-jit.py</code> script to produce
+disassembly of the generated code annotated with the samples.
</p>
<p>You can obtain a call graph via
<a href="https://github.com/jrfonseca/gprof2dot#linux-perf">Gprof2Dot</a>.</p>
-<h1>Unit testing</h1>
+<h2>Unit testing</h2>
<p>
Building will also create several unit tests in
-build/linux-???-debug/gallium/drivers/llvmpipe:
+<code>build/linux-???-debug/gallium/drivers/llvmpipe</code>:
</p>
<ul>
-<li> lp_test_blend: blending
-<li> lp_test_conv: SIMD vector conversion
-<li> lp_test_format: pixel unpacking/packing
+<li> <code>lp_test_blend</code>: blending
+<li> <code>lp_test_conv</code>: SIMD vector conversion
+<li> <code>lp_test_format</code>: pixel unpacking/packing
</ul>
<p>
-Some of this tests can output results and benchmarks to a tab-separated-file
-for posterior analysis, e.g.:
+Some of these tests can output results and benchmarks to a tab-separated file
+for later analysis, e.g.:
</p>
<pre>
build/linux-x86_64-debug/gallium/drivers/llvmpipe/lp_test_blend -o blend.tsv
</pre>
-<h1>Development Notes</h1>
+<h2>Development Notes</h2>
<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.
+ When looking at this code for the first time, start in lp_state_fs.c, and
+ then skim through the <code>lp_bld_*</code> functions called there, and
+ the comments at the top of the <code>lp_bld_*.c</code> 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.
+ <code>src/gallium/auxiliary/gallivm/</code>. The filenames and function
+ prefixes need to be renamed from <code>lp_bld_</code> 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
<a href="https://npcontemplation.blogspot.com/2008/06/secret-of-llvm-c-bindings.html">
- this stand-alone example</a>. See the llvm-c/Core.h file for reference.
+ this stand-alone example</a>. See the <code>llvm-c/Core.h</code> file for
+ reference.
</li>
</ul>
-<h1 id="recommended_reading">Recommended Reading</h1>
+<h2 id="recommended_reading">Recommended Reading</h2>
<ul>
<li>
<li><a href="http://www.drdobbs.com/optimizing-pixomatic-for-modern-x86-proc/184405807">Optimizing Pixomatic For Modern x86 Processors</a></li>
<li><a href="http://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-optimization-manual.html">Intel 64 and IA-32 Architectures Optimization Reference Manual</a></li>
<li><a href="http://www.agner.org/optimize/">Software optimization resources</a></li>
- <li><a href="https://software.intel.com/en-us/articles/intel-intrinsics-guide">Intel Intrinsics Guide</a><li>
+ <li><a href="https://software.intel.com/en-us/articles/intel-intrinsics-guide">Intel Intrinsics Guide</a></li>
</ul>
</li>
<li>
projects / mesa.git / blobdiff