| <!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"> |
| <title>Gallium LLVMpipe Driver</title> |
| <link rel="stylesheet" type="text/css" href="mesa.css"> |
| </head> |
| <body> |
| |
| <div class="header"> |
| The Mesa 3D Graphics Library |
| </div> |
| |
| <iframe src="contents.html"></iframe> |
| <div class="content"> |
| |
| <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, x86-64, or ppc64le machine |
| 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> |
| |
| |
| <h2>Requirements</h2> |
| |
| <ul> |
| <li> |
| <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 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 <code>/proc/cpuinfo</code> to know what your CPU supports. |
| </p> |
| </li> |
| <li> |
| <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> |
| <pre> |
| yum install llvm-devel |
| </pre> |
| |
| <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 |
| <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 |
| <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> |
| |
| <p> |
| You can build only the x86 target by passing |
| <code>-DLLVM_TARGETS_TO_BUILD=X86</code> to cmake. |
| </p> |
| </li> |
| |
| <li> |
| <p>scons (optional)</p> |
| </li> |
| </ul> |
| |
| |
| <h2>Building</h2> |
| |
| To build everything on Linux invoke scons as: |
| |
| <pre> |
| scons build=debug libgl-xlib |
| </pre> |
| |
| Alternatively, you can build it with meson with: |
| <pre> |
| 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. |
| |
| For Windows the procedure is similar except the target: |
| |
| <pre> |
| scons platform=windows build=debug libgl-gdi |
| </pre> |
| |
| |
| <h2>Using</h2> |
| |
| <h3>Linux</h3> |
| |
| <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 |
| </pre> |
| or |
| <pre> |
| lib/gallium/libGL.so |
| </pre> |
| |
| <p>To use it set the <code>LD_LIBRARY_PATH</code> environment variable |
| accordingly.</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> |
| |
| |
| <h3>Windows</h3> |
| |
| <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 |
| replacing the native ICD driver, but it's quite an advanced usage, so if you |
| need to ask, don't even try it. |
| </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> |
| <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 |
| |
| ; 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 |
| [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> |
| |
| |
| <h2>Profiling</h2> |
| |
| <p> |
| To profile llvmpipe you should build as |
| </p> |
| <pre> |
| scons build=profile <same-as-before> |
| </pre> |
| |
| <p> |
| This will ensure that frame pointers are used both in C and JIT functions, and |
| that no tail call optimizations are done by gcc. |
| </p> |
| |
| <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>: |
| </p> |
| |
| <pre> |
| perf record -g /my/application |
| perf report |
| </pre> |
| |
| <p> |
| 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> |
| |
| |
| <h2>Unit testing</h2> |
| |
| <p> |
| Building will also create several unit tests in |
| <code>build/linux-???-debug/gallium/drivers/llvmpipe</code>: |
| </p> |
| |
| <ul> |
| <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 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> |
| |
| |
| <h2>Development Notes</h2> |
| |
| <ul> |
| <li> |
| 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 |
| <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 <code>llvm-c/Core.h</code> file for |
| reference. |
| </li> |
| </ul> |
| |
| <h2 id="recommended_reading">Recommended Reading</h2> |
| |
| <ul> |
| <li> |
| <p>Rasterization</p> |
| <ul> |
| <li><a href="https://www.cs.unc.edu/~olano/papers/2dh-tri/">Triangle Scan Conversion using 2D Homogeneous Coordinates</a></li> |
| <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> |
| <li><a href="https://fgiesen.wordpress.com/2013/02/17/optimizing-sw-occlusion-culling-index/">Optimizing Software Occlusion Culling</a></li> |
| </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> |
| <li><a href="https://www.flipcode.com/archives/Texturing_As_In_Unreal.shtml">Texturing As In Unreal</a></li> |
| <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> |
| <li><a href="https://software.intel.com/en-us/articles/intel-intrinsics-guide">Intel Intrinsics Guide</a></li> |
| </ul> |
| </li> |
| <li> |
| <p>LLVM</p> |
| <ul> |
| <li><a href="http://llvm.org/docs/LangRef.html">LLVM Language Reference Manual</a></li> |
| <li><a href="https://npcontemplation.blogspot.co.uk/2008/06/secret-of-llvm-c-bindings.html">The secret of LLVM C bindings</a></li> |
| </ul> |
| </li> |
| <li> |
| <p>General</p> |
| <ul> |
| <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> |
| </ul> |
| </li> |
| </ul> |
| |
| </div> |
| </body> |
| </html> |