• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1LLVMpipe
2========
3
4Introduction
5------------
6
7The Gallium llvmpipe driver is a software rasterizer that uses LLVM to
8do runtime code generation. Shaders, point/line/triangle rasterization
9and vertex processing are implemented with LLVM IR which is translated
10to x86, x86-64, or ppc64le machine code. Also, the driver is
11multithreaded to take advantage of multiple CPU cores (up to 8 at this
12time). It's the fastest software rasterizer for Mesa.
13
14Requirements
15------------
16
17-  For x86 or amd64 processors, 64-bit mode is recommended. Support for
18   SSE2 is strongly encouraged. Support for SSE3 and SSE4.1 will yield
19   the most efficient code. The fewer features the CPU has the more
20   likely it is that you will run into underperforming, buggy, or
21   incomplete code.
22
23   For ppc64le processors, use of the Altivec feature (the Vector
24   Facility) is recommended if supported; use of the VSX feature (the
25   Vector-Scalar Facility) is recommended if supported AND Mesa is built
26   with LLVM version 4.0 or later.
27
28   See ``/proc/cpuinfo`` to know what your CPU supports.
29
30-  Unless otherwise stated, LLVM version 3.9 or later is required.
31
32   For Linux, on a recent Debian based distribution do:
33
34   .. code-block:: console
35
36      aptitude install llvm-dev
37
38   If you want development snapshot builds of LLVM for Debian and
39   derived distributions like Ubuntu, you can use the APT repository at
40   `apt.llvm.org <https://apt.llvm.org/>`__, which are maintained by
41   Debian's LLVM maintainer.
42
43   For a RPM-based distribution do:
44
45   .. code-block:: console
46
47      yum install llvm-devel
48
49   For Windows you will need to build LLVM from source with MSVC or
50   MINGW (either natively or through cross compilers) and CMake, and set
51   the ``LLVM`` environment variable to the directory you installed it
52   to. LLVM will be statically linked, so when building on MSVC it needs
53   to be built with a matching CRT as Mesa, and you'll need to pass
54   ``-DLLVM_USE_CRT_xxx=yyy`` as described below.
55
56
57   +-----------------+----------------------------------------------------------------+
58   | LLVM build-type | Mesa build-type                                                |
59   |                 +--------------------------------+-------------------------------+
60   |                 | debug,checked                  | release,profile               |
61   +=================+================================+===============================+
62   | Debug           | ``-DLLVM_USE_CRT_DEBUG=MTd``   | ``-DLLVM_USE_CRT_DEBUG=MT``   |
63   +-----------------+--------------------------------+-------------------------------+
64   | Release         | ``-DLLVM_USE_CRT_RELEASE=MTd`` | ``-DLLVM_USE_CRT_RELEASE=MT`` |
65   +-----------------+--------------------------------+-------------------------------+
66
67   You can build only the x86 target by passing
68   ``-DLLVM_TARGETS_TO_BUILD=X86`` to cmake.
69
70Building
71--------
72
73To build everything on Linux invoke meson as:
74
75.. code-block:: console
76
77   mkdir build
78   cd build
79   meson -D glx=gallium-xlib -D gallium-drivers=swrast
80   ninja
81
82
83Using
84-----
85
86Linux
87~~~~~
88
89On Linux, building will create a drop-in alternative for ``libGL.so``
90into
91
92::
93
94   build/foo/gallium/targets/libgl-xlib/libGL.so
95
96or
97
98::
99
100   lib/gallium/libGL.so
101
102To use it set the ``LD_LIBRARY_PATH`` environment variable accordingly.
103
104Windows
105~~~~~~~
106
107On Windows, building will create
108``build/windows-x86-debug/gallium/targets/libgl-gdi/opengl32.dll`` which
109is a drop-in alternative for system's ``opengl32.dll``, which will use
110the Mesa ICD, ``build/windows-x86-debug/gallium/targets/wgl/libgallium_wgl.dll``.
111To use it put both dlls in the same directory as your application. It can also
112be used by replacing the native ICD driver, but it's quite an advanced usage, so if
113you need to ask, don't even try it.
114
115There is however an easy way to replace the OpenGL software renderer
116that comes with Microsoft Windows 7 (or later) with llvmpipe (that is,
117on systems without any OpenGL drivers):
118
119-  copy
120   ``build/windows-x86-debug/gallium/targets/wgl/libgallium_wgl.dll`` to
121   ``C:\Windows\SysWOW64\mesadrv.dll``
122
123-  load this registry settings:
124
125   ::
126
127      REGEDIT4
128
129      ; https://technet.microsoft.com/en-us/library/cc749368.aspx
130      ; https://www.msfn.org/board/topic/143241-portable-windows-7-build-from-winpe-30/page-5#entry942596
131      [HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Windows NT\CurrentVersion\OpenGLDrivers\MSOGL]
132      "DLL"="mesadrv.dll"
133      "DriverVersion"=dword:00000001
134      "Flags"=dword:00000001
135      "Version"=dword:00000002
136
137-  Ditto for 64 bits drivers if you need them.
138
139Profiling
140---------
141
142Linux perf integration
143~~~~~~~~~~~~~~~~~~~~~~
144
145On Linux, it is possible to have symbol resolution of JIT code with
146`Linux perf <https://perf.wiki.kernel.org/>`__:
147
148::
149
150   perf record -g /my/application
151   perf report
152
153When run inside Linux perf, llvmpipe will create a
154``/tmp/perf-XXXXX.map`` file with symbol address table. It also dumps
155assembly code to ``/tmp/perf-XXXXX.map.asm``, which can be used by the
156``bin/perf-annotate-jit.py`` script to produce disassembly of the
157generated code annotated with the samples.
158
159You can obtain a call graph via
160`Gprof2Dot <https://github.com/jrfonseca/gprof2dot#linux-perf>`__.
161
162Unit testing
163------------
164
165Building will also create several unit tests in
166``build/linux-???-debug/gallium/drivers/llvmpipe``:
167
168-  ``lp_test_blend``: blending
169-  ``lp_test_conv``: SIMD vector conversion
170-  ``lp_test_format``: pixel unpacking/packing
171
172Some of these tests can output results and benchmarks to a tab-separated
173file for later analysis, e.g.:
174
175::
176
177   build/linux-x86_64-debug/gallium/drivers/llvmpipe/lp_test_blend -o blend.tsv
178
179Development Notes
180-----------------
181
182-  When looking at this code for the first time, start in lp_state_fs.c,
183   and then skim through the ``lp_bld_*`` functions called there, and
184   the comments at the top of the ``lp_bld_*.c`` functions.
185-  The driver-independent parts of the LLVM / Gallium code are found in
186   ``src/gallium/auxiliary/gallivm/``. The filenames and function
187   prefixes need to be renamed from ``lp_bld_`` to something else
188   though.
189-  We use LLVM-C bindings for now. They are not documented, but follow
190   the C++ interfaces very closely, and appear to be complete enough for
191   code generation. See `this stand-alone
192   example <https://npcontemplation.blogspot.com/2008/06/secret-of-llvm-c-bindings.html>`__.
193   See the ``llvm-c/Core.h`` file for reference.
194
195.. _recommended_reading:
196
197Recommended Reading
198-------------------
199
200-  Rasterization
201
202   -  `Triangle Scan Conversion using 2D Homogeneous
203      Coordinates <https://www.cs.unc.edu/~olano/papers/2dh-tri/>`__
204   -  `Rasterization on
205      Larrabee <http://www.drdobbs.com/parallel/rasterization-on-larrabee/217200602>`__
206      (`DevMaster
207      copy <http://devmaster.net/posts/2887/rasterization-on-larrabee>`__)
208   -  `Rasterization using half-space
209      functions <http://devmaster.net/posts/6133/rasterization-using-half-space-functions>`__
210   -  `Advanced
211      Rasterization <http://devmaster.net/posts/6145/advanced-rasterization>`__
212   -  `Optimizing Software Occlusion
213      Culling <https://fgiesen.wordpress.com/2013/02/17/optimizing-sw-occlusion-culling-index/>`__
214
215-  Texture sampling
216
217   -  `Perspective Texture
218      Mapping <http://chrishecker.com/Miscellaneous_Technical_Articles#Perspective_Texture_Mapping>`__
219   -  `Texturing As In
220      Unreal <https://www.flipcode.com/archives/Texturing_As_In_Unreal.shtml>`__
221   -  `Run-Time MIP-Map
222      Filtering <http://www.gamasutra.com/view/feature/3301/runtime_mipmap_filtering.php>`__
223   -  `Will "brilinear" filtering
224      persist? <http://alt.3dcenter.org/artikel/2003/10-26_a_english.php>`__
225   -  `Trilinear
226      filtering <http://ixbtlabs.com/articles2/gffx/nv40-rx800-3.html>`__
227   -  `Texture
228      Swizzling <http://devmaster.net/posts/12785/texture-swizzling>`__
229
230-  SIMD
231
232   -  `Whole-Function
233      Vectorization <http://www.cdl.uni-saarland.de/projects/wfv/#header4>`__
234
235-  Optimization
236
237   -  `Optimizing Pixomatic For Modern x86
238      Processors <http://www.drdobbs.com/optimizing-pixomatic-for-modern-x86-proc/184405807>`__
239   -  `Intel 64 and IA-32 Architectures Optimization Reference
240      Manual <http://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-optimization-manual.html>`__
241   -  `Software optimization
242      resources <http://www.agner.org/optimize/>`__
243   -  `Intel Intrinsics
244      Guide <https://software.intel.com/en-us/articles/intel-intrinsics-guide>`__
245
246-  LLVM
247
248   -  `LLVM Language Reference
249      Manual <http://llvm.org/docs/LangRef.html>`__
250   -  `The secret of LLVM C
251      bindings <https://npcontemplation.blogspot.co.uk/2008/06/secret-of-llvm-c-bindings.html>`__
252
253-  General
254
255   -  `A trip through the Graphics
256      Pipeline <https://fgiesen.wordpress.com/2011/07/09/a-trip-through-the-graphics-pipeline-2011-index/>`__
257   -  `WARP Architecture and
258      Performance <https://msdn.microsoft.com/en-us/library/gg615082.aspx#architecture>`__
259