import Mesa 11.0.6

author: Jonathan Gray <jsg@cvs.openbsd.org> 2015-11-22 02:46:45 +0000
committer: Jonathan Gray <jsg@cvs.openbsd.org> 2015-11-22 02:46:45 +0000
commit: 0784c49c0f8fcc8b3abd4c9286d9fd8bc089dd7d (patch)
tree: a6394e3e264a0f80b57f4ce0f5d9526aa543d4b0 /lib/mesa/docs/llvmpipe.html
parent: d91d0007eecf589ea5699e34aa4d748fce2c57b2 (diff)
1 files changed, 318 insertions, 0 deletions
diff --git a/lib/mesa/docs/llvmpipe.html b/lib/mesa/docs/llvmpipe.html
new file mode 100644
index 000000000..f603bd646
--- /dev/null
+++ b/lib/mesa/docs/llvmpipe.html
@@ -0,0 +1,318 @@
+<!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>llvmpipe</title>
+  <link rel="stylesheet" type="text/css" href="mesa.css">
+</head>
+<body>
+
+<div class="header">
+  <h1>The Mesa 3D Graphics Library</h1>
+</div>
+
+<iframe src="contents.html"></iframe>
+<div class="content">
+
+<h1>Introduction</h1>
+
+<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 or x86-64 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>
+
+
+<h1>Requirements</h1>
+
+<ul>
+<li>
+   <p>An x86 or amd64 processor; 64-bit mode recommended.</p>
+   <p>
+   Support for SSE2 is strongly encouraged.  Support for SSSE3 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.
+   </p>
+   <p>
+   See /proc/cpuinfo to know what your CPU supports.
+   </p>
+</li>
+<li>
+   <p>LLVM: version 3.4 recommended; 3.3 or later required.</p>
+   <p>
+   For Linux, on a recent Debian based distribution do:
+   </p>
+<pre>
+     aptitude install llvm-dev
+</pre>
+   <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 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
+   <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 -DLLVM_TARGETS_TO_BUILD=X86
+   to cmake.
+   </p>
+</li>
+
+<li>
+   <p>scons (optional)</p>
+</li>
+</ul>
+
+
+<h1>Building</h1>
+
+To build everything on Linux invoke scons as:
+
+<pre>
+  scons build=debug libgl-xlib
+</pre>
+
+Alternatively, you can build it with GNU make, if you prefer, by invoking it as
+
+<pre>
+  make linux-llvm
+</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>
+
+
+<h1>Using</h1>
+
+<h2>Linux</h2>
+
+<p>On Linux, building will create a drop-in alternative for libGL.so 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 LD_LIBRARY_PATH environment variable accordingly.</p>
+
+<p>For performance evaluation pass build=release to scons, and use the corresponding
+lib directory without the "-debug" suffix.</p>
+
+
+<h2>Windows</h2>
+
+<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 build/windows-x86-debug/gallium/targets/libgl-gdi/opengl32.dll to C:\Windows\SysWOW64\mesadrv.dll</p></li>
+  <li><p>load this registry settings:</p>
+  <pre>REGEDIT4
+
+; http://technet.microsoft.com/en-us/library/cc749368.aspx
+; http://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>
+
+
+<h1>Profiling</h1>
+
+<p>
+To profile llvmpipe you should build as
+</p>
+<pre>
+  scons build=profile &lt;same-as-before&gt;
+</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>
+
+<h2>Linux perf integration</h2>
+
+<p>
+On Linux, it is possible to have symbol resolution of JIT code with <a href="http://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 /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 script to produce disassembly of
+the generated code annotated with the samples.
+</p>
+
+<p>You can obtain a call graph via
+<a href="http://code.google.com/p/jrfonseca/wiki/Gprof2Dot#linux_perf">Gprof2Dot</a>.</p>
+
+
+<h1>Unit testing</h1>
+
+<p>
+Building will also create several unit tests in
+build/linux-???-debug/gallium/drivers/llvmpipe:
+</p>
+
+<ul>
+<li> lp_test_blend: blending
+<li> lp_test_conv: SIMD vector conversion
+<li> lp_test_format: pixel unpacking/packing
+</ul>
+
+<p>
+Some of this tests can output results and benchmarks to a tab-separated-file
+for posterior analysis, e.g.:
+</p>
+<pre>
+  build/linux-x86_64-debug/gallium/drivers/llvmpipe/lp_test_blend -o blend.tsv
+</pre>
+
+
+<h1>Development Notes</h1>
+
+<ul>
+<li>
+  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.
+</li>
+<li>
+  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.
+</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="http://npcontemplation.blogspot.com/2008/06/secret-of-llvm-c-bindings.html">
+  this stand-alone example</a>.  See the llvm-c/Core.h file for reference.
+</li>
+</ul>
+
+<h1 id="recommended_reading">Recommended Reading</h1>
+
+<ul>
+  <li>
+    <p>Rasterization</p>
+    <ul>
+      <li><a href="http://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="http://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="http://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="http://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="http://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="http://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="http://msdn.microsoft.com/en-us/library/gg615082.aspx#architecture">WARP Architecture and Performance</a></li>
+    </ul>
+  </li>
+</ul>
+
+</div>
+</body>
+</html>
author	Jonathan Gray <jsg@cvs.openbsd.org>	2015-11-22 02:46:45 +0000
committer	Jonathan Gray <jsg@cvs.openbsd.org>	2015-11-22 02:46:45 +0000
commit	0784c49c0f8fcc8b3abd4c9286d9fd8bc089dd7d (patch)
tree	a6394e3e264a0f80b57f4ce0f5d9526aa543d4b0 /lib/mesa/docs/llvmpipe.html
parent	d91d0007eecf589ea5699e34aa4d748fce2c57b2 (diff)