docs/llvmpipe.rst

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