2012-06-12 08:05:03 +01:00
<!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" >
2019-05-06 11:57:15 +01:00
< title > Gallium LLVMpipe Driver< / title >
2012-06-12 08:05:03 +01:00
< link rel = "stylesheet" type = "text/css" href = "mesa.css" >
< / head >
< body >
2009-08-10 12:35:16 +01:00
2012-09-18 17:57:02 +01:00
< div class = "header" >
2019-05-06 12:26:47 +01:00
The Mesa 3D Graphics Library
2012-09-18 17:57:02 +01:00
< / div >
< iframe src = "contents.html" > < / iframe >
< div class = "content" >
2019-05-06 11:57:15 +01:00
< h1 > Gallium LLVMpipe Driver< / h1 >
< h2 > Introduction< / h2 >
2011-04-07 20:56:45 +01:00
< 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
2017-11-27 19:44:58 +00:00
implemented with LLVM IR which is translated to x86, x86-64, or ppc64le machine
2011-04-07 20:56:45 +01:00
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 >
2019-05-06 11:57:15 +01:00
< h2 > Requirements< / h2 >
2011-04-07 20:56:45 +01:00
2011-11-05 10:38:16 +00:00
< ul >
< li >
2011-04-07 20:56:45 +01:00
< p >
2017-11-27 19:44:58 +00:00
For x86 or amd64 processors, 64-bit mode is recommended.
2017-02-26 23:58:03 +00:00
Support for SSE2 is strongly encouraged. Support for SSE3 and SSE4.1 will
2011-11-05 21:11:59 +00:00
yield the most efficient code. The fewer features the CPU has the more
2017-11-27 19:44:59 +00:00
likely it is that you will run into underperforming, buggy, or incomplete code.
2011-04-07 20:56:45 +01:00
< / p >
< p >
2017-11-27 19:44:58 +00:00
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 >
2019-06-04 12:11:59 +01:00
See < code > /proc/cpuinfo< / code > to know what your CPU supports.
2011-04-07 20:56:45 +01:00
< / p >
2011-11-05 10:38:16 +00:00
< / li >
< li >
2017-11-27 19:44:58 +00:00
< p > Unless otherwise stated, LLVM version 3.4 is recommended; 3.3 or later is required.< / p >
2011-04-07 20:56:45 +01:00
< p >
2010-01-10 18:37:07 +00:00
For Linux, on a recent Debian based distribution do:
2011-04-07 20:56:45 +01:00
< / p >
< pre >
2020-01-16 19:18:07 +00:00
aptitude install llvm-dev
2011-04-07 20:56:45 +01:00
< / pre >
2017-11-16 11:58:50 +00:00
< p >
2017-11-27 19:44:59 +00:00
If you want development snapshot builds of LLVM for Debian and derived
2017-11-16 11:58:50 +00:00
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 >
2012-06-12 08:05:22 +01:00
< p >
2011-04-07 20:56:45 +01:00
For a RPM-based distribution do:
< / p >
< pre >
2020-01-16 19:18:07 +00:00
yum install llvm-devel
2011-04-07 20:56:45 +01:00
< / pre >
< p >
2015-04-13 13:08:13 +01:00
For Windows you will need to build LLVM from source with MSVC or MINGW
2019-06-04 12:11:59 +01:00
(either natively or through cross compilers) and CMake, and set the
< code > LLVM< / code > environment variable to the directory you installed
it to.
2010-01-10 18:37:07 +00:00
2011-11-05 10:38:16 +00:00
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
2015-04-13 13:08:13 +01:00
< code > -DLLVM_USE_CRT_xxx=yyy< / code > as described below.
< / p >
< table border = "1" >
< tr >
< th rowspan = "2" > LLVM build-type< / th >
< th colspan = "2" align = "center" > Mesa build-type< / th >
< / tr >
< tr >
< th > debug,checked< / th >
< th > release,profile< / th >
< / tr >
< tr >
< th > Debug< / th >
< td > < code > -DLLVM_USE_CRT_DEBUG=MTd< / code > < / td >
< td > < code > -DLLVM_USE_CRT_DEBUG=MT< / code > < / td >
< / tr >
< tr >
< th > Release< / th >
< td > < code > -DLLVM_USE_CRT_RELEASE=MTd< / code > < / td >
< td > < code > -DLLVM_USE_CRT_RELEASE=MT< / code > < / td >
< / tr >
< / table >
2010-05-13 16:18:05 +01:00
2015-04-13 13:08:13 +01:00
< p >
2019-06-04 12:11:59 +01:00
You can build only the x86 target by passing
< code > -DLLVM_TARGETS_TO_BUILD=X86< / code > to cmake.
2011-04-07 20:56:45 +01:00
< / p >
2011-11-05 10:38:16 +00:00
< / li >
< li >
< p > scons (optional)< / p >
< / li >
< / ul >
2010-05-13 16:18:05 +01:00
2009-08-10 12:35:16 +01:00
2019-05-06 11:57:15 +01:00
< h2 > Building< / h2 >
2009-08-10 12:35:16 +01:00
2010-01-10 18:37:07 +00:00
To build everything on Linux invoke scons as:
2009-08-10 12:35:16 +01:00
2011-04-07 20:56:45 +01:00
< pre >
2020-01-16 19:18:07 +00:00
scons build=debug libgl-xlib
2011-04-07 20:56:45 +01:00
< / pre >
2009-08-10 12:35:16 +01:00
2019-04-24 13:16:57 +01:00
Alternatively, you can build it with meson with:
2011-04-07 20:56:45 +01:00
< pre >
2020-01-16 19:18:07 +00:00
mkdir build
cd build
meson -D glx=gallium-xlib -D gallium-drivers=swrast
ninja
2011-04-07 20:56:45 +01:00
< / pre >
2009-08-22 22:26:55 +01:00
2009-09-11 11:24:00 +01:00
but the rest of these instructions assume that scons is used.
2009-08-22 22:26:55 +01:00
2011-11-05 10:38:16 +00:00
For Windows the procedure is similar except the target:
2010-01-10 18:37:07 +00:00
2011-04-07 20:56:45 +01:00
< pre >
2020-01-16 19:18:07 +00:00
scons platform=windows build=debug libgl-gdi
2011-04-07 20:56:45 +01:00
< / pre >
2009-08-10 12:35:16 +01:00
2019-05-06 11:57:15 +01:00
< h2 > Using< / h2 >
2009-08-10 12:35:16 +01:00
2019-05-06 11:57:15 +01:00
< h3 > Linux< / h3 >
2014-05-29 20:02:31 +01:00
2019-06-04 12:11:59 +01:00
< p > On Linux, building will create a drop-in alternative for
< code > libGL.so< / code > into< / p >
2009-08-10 12:35:16 +01:00
2011-04-07 20:56:45 +01:00
< pre >
2020-01-16 19:18:07 +00:00
build/foo/gallium/targets/libgl-xlib/libGL.so
2011-04-07 20:56:45 +01:00
< / pre >
or
< pre >
2020-01-16 19:18:07 +00:00
lib/gallium/libGL.so
2011-04-07 20:56:45 +01:00
< / pre >
2009-08-22 22:26:55 +01:00
2019-06-04 12:11:59 +01:00
< p > To use it set the < code > LD_LIBRARY_PATH< / code > environment variable
accordingly.< / p >
2014-05-29 20:02:31 +01:00
2019-06-04 12:11:59 +01:00
< p > For performance evaluation pass < code > build=release< / code > to scons,
and use the corresponding lib directory without the < code > -debug< / code >
suffix.< / p >
2014-05-29 20:02:31 +01:00
2009-08-22 22:26:55 +01:00
2019-05-06 11:57:15 +01:00
< h3 > Windows< / h3 >
2009-09-11 11:24:00 +01:00
2014-05-29 20:02:31 +01:00
< p >
On Windows, building will create
< code > build/windows-x86-debug/gallium/targets/libgl-gdi/opengl32.dll< / code >
which is a drop-in alternative for system's < code > opengl32.dll< / code > . To use
it put it in the same directory as your application. It can also be used by
2010-01-10 18:37:07 +00:00
replacing the native ICD driver, but it's quite an advanced usage, so if you
need to ask, don't even try it.
2014-05-29 20:02:31 +01:00
< / p >
< p >
There is however an easy way to replace the OpenGL software renderer that comes
with Microsoft Windows 7 (or later) with llvmpipe (that is, on systems without
any OpenGL drivers):
< / p >
< ul >
2019-06-04 12:11:59 +01:00
< 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 >
2014-05-29 20:02:31 +01:00
< li > < p > load this registry settings:< / p >
< pre > REGEDIT4
2017-02-09 02:10:17 +00:00
; https://technet.microsoft.com/en-us/library/cc749368.aspx
; https://www.msfn.org/board/topic/143241-portable-windows-7-build-from-winpe-30/page-5#entry942596
2014-05-29 20:02:31 +01:00
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Windows NT\CurrentVersion\OpenGLDrivers\MSOGL]
"DLL"="mesadrv.dll"
"DriverVersion"=dword:00000001
"Flags"=dword:00000001
"Version"=dword:00000002
< / pre >
< / li >
< li > Ditto for 64 bits drivers if you need them.< / li >
< / ul >
2010-01-10 18:37:07 +00:00
2009-08-10 12:35:16 +01:00
2019-05-06 11:57:15 +01:00
< h2 > Profiling< / h2 >
2010-09-21 17:50:30 +01:00
2013-04-17 13:32:15 +01:00
< p >
To profile llvmpipe you should build as
< / p >
2011-04-07 20:56:45 +01:00
< pre >
2020-01-16 19:18:07 +00:00
scons build=profile < same-as-before>
2011-04-07 20:56:45 +01:00
< / pre >
2010-09-21 17:50:30 +01:00
2013-04-17 13:32:15 +01:00
< p >
2010-09-21 17:50:30 +01:00
This will ensure that frame pointers are used both in C and JIT functions, and
that no tail call optimizations are done by gcc.
2013-04-17 13:32:15 +01:00
< / p >
2010-09-21 17:50:30 +01:00
2019-05-06 11:57:15 +01:00
< h3 > Linux perf integration< / h3 >
2010-09-21 17:50:30 +01:00
2013-04-17 13:32:15 +01:00
< p >
2017-02-09 02:10:17 +00:00
On Linux, it is possible to have symbol resolution of JIT code with < a href = "https://perf.wiki.kernel.org/" > Linux perf< / a > :
2013-04-17 13:32:15 +01:00
< / p >
2010-09-21 17:50:30 +01:00
2011-04-07 20:56:45 +01:00
< pre >
2020-01-16 19:18:07 +00:00
perf record -g /my/application
perf report
2011-04-07 20:56:45 +01:00
< / pre >
2010-09-21 17:50:30 +01:00
2013-04-17 13:32:15 +01:00
< p >
2019-06-04 12:11:59 +01:00
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.
2013-04-17 13:32:15 +01:00
< / p >
< p > You can obtain a call graph via
2017-02-09 02:10:17 +00:00
< a href = "https://github.com/jrfonseca/gprof2dot#linux-perf" > Gprof2Dot< / a > .< / p >
2010-09-21 17:50:30 +01:00
2019-05-06 11:57:15 +01:00
< h2 > Unit testing< / h2 >
2009-08-10 12:35:16 +01:00
2011-04-07 20:56:45 +01:00
< p >
2009-08-10 12:35:16 +01:00
Building will also create several unit tests in
2019-06-04 12:11:59 +01:00
< code > build/linux-???-debug/gallium/drivers/llvmpipe< / code > :
2011-04-07 20:56:45 +01:00
< / p >
2009-08-10 12:35:16 +01:00
2012-06-12 08:05:22 +01:00
< ul >
2019-06-04 12:11:59 +01:00
< 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
2011-04-07 20:56:45 +01:00
< / ul >
2009-08-10 12:35:16 +01:00
2011-04-07 20:56:45 +01:00
< p >
2017-11-27 19:44:59 +00:00
Some of these tests can output results and benchmarks to a tab-separated file
for later analysis, e.g.:
2011-04-07 20:56:45 +01:00
< / p >
< pre >
2020-01-16 19:18:07 +00:00
build/linux-x86_64-debug/gallium/drivers/llvmpipe/lp_test_blend -o blend.tsv
2011-04-07 20:56:45 +01:00
< / pre >
2009-08-10 12:35:16 +01:00
2009-08-21 10:57:48 +01:00
2019-05-06 11:57:15 +01:00
< h2 > Development Notes< / h2 >
2009-08-21 10:57:48 +01:00
2011-04-07 20:56:45 +01:00
< ul >
< li >
2017-11-27 19:44:59 +00:00
When looking at this code for the first time, start in lp_state_fs.c, and
2019-06-04 12:11:59 +01:00
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.
2011-04-07 20:56:45 +01:00
< / li >
< li >
The driver-independent parts of the LLVM / Gallium code are found in
2019-06-04 12:11:59 +01:00
< code > src/gallium/auxiliary/gallivm/< / code > . The filenames and function
prefixes need to be renamed from < code > lp_bld_< / code > to something else
though.
2011-04-07 20:56:45 +01:00
< / li >
< li >
We use LLVM-C bindings for now. They are not documented, but follow the C++
2009-08-21 10:57:48 +01:00
interfaces very closely, and appear to be complete enough for code
generation. See
2017-02-09 02:10:17 +00:00
< a href = "https://npcontemplation.blogspot.com/2008/06/secret-of-llvm-c-bindings.html" >
2019-06-04 12:11:59 +01:00
this stand-alone example< / a > . See the < code > llvm-c/Core.h< / code > file for
reference.
2011-04-07 20:56:45 +01:00
< / li >
< / ul >
2012-06-12 08:05:03 +01:00
2019-05-06 11:57:15 +01:00
< h2 id = "recommended_reading" > Recommended Reading< / h2 >
2013-11-21 17:52:50 +00:00
< ul >
< li >
< p > Rasterization< / p >
< ul >
2017-02-09 02:10:17 +00:00
< li > < a href = "https://www.cs.unc.edu/~olano/papers/2dh-tri/" > Triangle Scan Conversion using 2D Homogeneous Coordinates< / a > < / li >
2013-11-21 17:52:50 +00:00
< li > < a href = "http://www.drdobbs.com/parallel/rasterization-on-larrabee/217200602" > Rasterization on Larrabee< / a > (< a href = "http://devmaster.net/posts/2887/rasterization-on-larrabee" > DevMaster copy< / a > )< / li >
< li > < a href = "http://devmaster.net/posts/6133/rasterization-using-half-space-functions" > Rasterization using half-space functions< / a > < / li >
< li > < a href = "http://devmaster.net/posts/6145/advanced-rasterization" > Advanced Rasterization< / a > < / li >
2017-02-09 02:10:17 +00:00
< li > < a href = "https://fgiesen.wordpress.com/2013/02/17/optimizing-sw-occlusion-culling-index/" > Optimizing Software Occlusion Culling< / a > < / li >
2013-11-21 17:52:50 +00:00
< / ul >
< / li >
< li >
< p > Texture sampling< / p >
< ul >
< li > < a href = "http://chrishecker.com/Miscellaneous_Technical_Articles#Perspective_Texture_Mapping" > Perspective Texture Mapping< / a > < / li >
2017-02-09 02:10:17 +00:00
< li > < a href = "https://www.flipcode.com/archives/Texturing_As_In_Unreal.shtml" > Texturing As In Unreal< / a > < / li >
2013-11-21 17:52:50 +00:00
< li > < a href = "http://www.gamasutra.com/view/feature/3301/runtime_mipmap_filtering.php" > Run-Time MIP-Map Filtering< / a > < / li >
< li > < a href = "http://alt.3dcenter.org/artikel/2003/10-26_a_english.php" > Will "brilinear" filtering persist?< / a > < / li >
< li > < a href = "http://ixbtlabs.com/articles2/gffx/nv40-rx800-3.html" > Trilinear filtering< / a > < / li >
< li > < a href = "http://devmaster.net/posts/12785/texture-swizzling" > Texture Swizzling< / a > < / li >
< / ul >
< / li >
< li >
< p > SIMD< / p >
< ul >
< li > < a href = "http://www.cdl.uni-saarland.de/projects/wfv/#header4" > Whole-Function Vectorization< / a > < / li >
< / ul >
< / li >
< li >
< p > Optimization< / p >
< ul >
< 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 >
2019-04-18 15:39:25 +01:00
< li > < a href = "https://software.intel.com/en-us/articles/intel-intrinsics-guide" > Intel Intrinsics Guide< / a > < / li >
2013-11-21 17:52:50 +00:00
< / ul >
< / li >
< li >
< p > LLVM< / p >
< ul >
< li > < a href = "http://llvm.org/docs/LangRef.html" > LLVM Language Reference Manual< / a > < / li >
2017-02-09 02:10:17 +00:00
< li > < a href = "https://npcontemplation.blogspot.co.uk/2008/06/secret-of-llvm-c-bindings.html" > The secret of LLVM C bindings< / a > < / li >
2013-11-21 17:52:50 +00:00
< / ul >
< / li >
< li >
2013-11-25 08:28:23 +00:00
< p > General< / p >
2013-11-21 17:52:50 +00:00
< ul >
2017-02-09 02:10:17 +00:00
< li > < a href = "https://fgiesen.wordpress.com/2011/07/09/a-trip-through-the-graphics-pipeline-2011-index/" > A trip through the Graphics Pipeline< / a > < / li >
< li > < a href = "https://msdn.microsoft.com/en-us/library/gg615082.aspx#architecture" > WARP Architecture and Performance< / a > < / li >
2013-11-21 17:52:50 +00:00
< / ul >
< / li >
< / ul >
2012-09-18 17:57:02 +01:00
< / div >
2012-06-12 08:05:03 +01:00
< / body >
< / html >