Introduction
+Gallium LLVMpipe Driver
+ +Introduction
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). @@ -28,30 +30,36 @@ It's the fastest software rasterizer for Mesa.
-Requirements
+Requirements
-
-
An x86 or amd64 processor; 64-bit mode recommended.
+ 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. +
++ 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.
- See /proc/cpuinfo to know what your CPU supports. + See
/proc/cpuinfo
to know what your CPU supports. -
-
LLVM: version 3.4 recommended; 3.3 or later required.
+Unless otherwise stated, LLVM version 3.4 is recommended; 3.3 or later is required.
For Linux, on a recent Debian based distribution do:
- aptitude install llvm-dev +aptitude install llvm-dev
- If you want development snaptshot builds of LLVM for Debian and derived + If you want development snapshot builds of LLVM for Debian and derived distributions like Ubuntu, you can use the APT repository at apt.llvm.org, which are maintained by Debian's LLVM maintainer. @@ -60,13 +68,14 @@ It's the fastest software rasterizer for Mesa. For a RPM-based distribution do:
- yum install llvm-devel +yum install llvm-devel
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 +
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 @@ -95,8 +104,8 @@ It's the fastest software rasterizer for Mesa.- 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 +
-DLLVM_TARGETS_TO_BUILD=X86
to cmake.
@@ -106,18 +115,20 @@ It's the fastest software rasterizer for Mesa.
Building
+Building
To build everything on Linux invoke scons as:- scons build=debug libgl-xlib +scons build=debug libgl-xlib-Alternatively, you can build it with autoconf/make with: +Alternatively, you can build it with meson with:
- ./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 +ninjabut the rest of these instructions assume that scons is used. @@ -125,31 +136,34 @@ but the rest of these instructions assume that scons is used. For Windows the procedure is similar except the target:
- scons platform=windows build=debug libgl-gdi +scons platform=windows build=debug libgl-gdi-
Using
+Using
-Linux
+Linux
-On Linux, building will create a drop-in alternative for libGL.so into
+On Linux, building will create a drop-in alternative for
+libGL.so
into
- build/foo/gallium/targets/libgl-xlib/libGL.so +build/foo/gallium/targets/libgl-xlib/libGL.soor
- lib/gallium/libGL.so +lib/gallium/libGL.so-
To use it set the LD_LIBRARY_PATH environment variable accordingly.
+To use it set the LD_LIBRARY_PATH
environment variable
+accordingly.
For performance evaluation pass build=release to scons, and use the corresponding -lib directory without the "-debug" suffix.
+For performance evaluation pass build=release
to scons,
+and use the corresponding lib directory without the -debug
+suffix.
Windows
+Windows
On Windows, building will create @@ -167,7 +181,9 @@ any OpenGL drivers):
-
-
copy build/windows-x86-debug/gallium/targets/libgl-gdi/opengl32.dll to C:\Windows\SysWOW64\mesadrv.dll
+ copy
build/windows-x86-debug/gallium/targets/libgl-gdi/opengl32.dll
+ toC:\Windows\SysWOW64\mesadrv.dll
+load this registry settings:
REGEDIT4 @@ -184,13 +200,13 @@ any OpenGL drivers):
Profiling
+Profiling
To profile llvmpipe you should build as
- scons build=profile <same-as-before> +scons build=profile <same-as-before>
@@ -198,73 +214,76 @@ This will ensure that frame pointers are used both in C and JIT functions, and that no tail call optimizations are done by gcc.
-Linux perf integration
+Linux perf integration
On Linux, it is possible to have symbol resolution of JIT code with Linux perf:
- perf record -g /my/application - perf report +perf record -g /my/application +perf report
-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
+/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.
You can obtain a call graph via Gprof2Dot.
-Unit testing
+Unit testing
Building will also create several unit tests in
-build/linux-???-debug/gallium/drivers/llvmpipe:
+build/linux-???-debug/gallium/drivers/llvmpipe
:
-
-
- lp_test_blend: blending -
- lp_test_conv: SIMD vector conversion -
- lp_test_format: pixel unpacking/packing +
-
lp_test_blend
: blending + -
lp_test_conv
: SIMD vector conversion + -
lp_test_format
: pixel unpacking/packing
-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.:
- build/linux-x86_64-debug/gallium/drivers/llvmpipe/lp_test_blend -o blend.tsv +build/linux-x86_64-debug/gallium/drivers/llvmpipe/lp_test_blend -o blend.tsv-
Development Notes
+Development Notes
-
- 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
lp_bld_*
functions called there, and + the comments at the top of thelp_bld_*.c
functions. -
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.
+
src/gallium/auxiliary/gallivm/
. The filenames and function + prefixes need to be renamed fromlp_bld_
to something else + though. -
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
- this stand-alone example. See the llvm-c/Core.h file for reference.
+ this stand-alone example. See the
llvm-c/Core.h
file for + reference.
Recommended Reading
+Recommended Reading
- @@ -300,7 +319,7 @@ for posterior analysis, e.g.:
- Optimizing Pixomatic For Modern x86 Processors
- Intel 64 and IA-32 Architectures Optimization Reference Manual
- Software optimization resources -
- Intel Intrinsics Guide
- +
- Intel Intrinsics Guide