docs: replace llvmpipe/README with docs/llvmpipe.html

author: Brian Paul <brianp@vmware.com> 2011-04-07 13:56:45 -0600
committer: Brian Paul <brianp@vmware.com> 2011-04-07 13:56:45 -0600
commit: 0da2a22ba6cbe6a2175ac47ab4541b1cfa939d1f (patch)
tree: 1f73797e791f5b0de80f0dea5fc62f0ccae00757 /docs
parent: 06613b7b3a641b66400f09993a884daf7ab34509 (diff)
2 files changed, 205 insertions, 0 deletions
diff --git a/docs/contents.html b/docs/contents.html
index cf1661e4ea..8fc2ac0da9 100644
--- a/docs/contents.html
+++ b/docs/contents.html
@@ -62,6 +62,7 @@ a:visited {
 <LI><A HREF="perf.html" target="MainFrame">Performance Tips</A>
 <LI><A HREF="extensions.html" target="MainFrame">Mesa Extensions</A>
 <LI><A HREF="mangling.html" target="MainFrame">Function Name Mangling</A>
+<LI><A href="llvmpipe.html" target="MainFrame">Gallium llvmpipe driver</A>
 </ul>
 
 <b>Developer Topics</b>
diff --git a/docs/llvmpipe.html b/docs/llvmpipe.html
new file mode 100644
index 0000000000..28d7411d43
--- /dev/null
+++ b/docs/llvmpipe.html
@@ -0,0 +1,204 @@
+<HTML>
+
+<TITLE>llvmpipe</TITLE>
+
+<link rel="stylesheet" type="text/css" href="mesa.css"></head>
+
+<BODY>
+
+<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>
+
+<dl>
+<dt>An x86 or amd64 processor.  64-bit mode is preferred.</dt>
+<dd>
+   <p>
+   Support for sse2 is strongly encouraged.  Support for ssse3, and sse4.1 will
+   yield the most efficient code.  The less features the CPU has the more
+   likely is that you ran into underperforming, buggy, or incomplete code.  
+   </p>
+   <p>
+   See /proc/cpuinfo to know what your CPU supports.
+   </p>
+</dd>
+<dt>LLVM. Version 2.8 recommended. 2.6 or later required.</dt>
+<dd>
+   <p>
+   <b>NOTE</b>: LLVM 2.8 and earlier will not work on systems that support the
+   Intel AVX extensions (e.g. Sandybridge).  LLVM's code generator will
+   fail when trying to emit AVX instructions.  This was fixed in LLVM 2.9.
+   </p>
+   <p>
+   For Linux, on a recent Debian based distribution do:
+   </p>
+<pre>
+     aptitude install llvm-dev
+</pre>
+   For a RPM-based distribution do:
+   </p>
+<pre>
+     yum install llvm-devel
+</pre>
+
+   <p>
+   For Windows download pre-built MSVC 9.0 or MinGW binaries from
+   http://people.freedesktop.org/~jrfonseca/llvm/ and set the LLVM environment
+   variable to the extracted path.
+   </p>
+
+   <p>
+   For MSVC there are two set of binaries: llvm-x.x-msvc32mt.7z and
+   llvm-x.x-msvc32mtd.7z .
+   </p>
+
+   <p>
+   You have to set the LLVM=/path/to/llvm-x.x-msvc32mtd env var when passing
+   debug=yes to scons, and LLVM=/path/to/llvm-x.x-msvc32mt when building with
+   debug=no. This is necessary as LLVM builds as static library so the chosen
+   MS CRT must match.
+   </p>
+</dd>
+
+<dt>scons (optional)</dt>
+</dl>
+
+
+
+<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 is everything the except except the winsys:
+
+<pre>
+  scons build=debug libgl-gdi
+</pre>
+
+
+<h1>Using</h1>
+
+On Linux, building will create a drop-in alternative for libGL.so into
+
+<pre>
+  build/foo/gallium/targets/libgl-xlib/libGL.so
+</pre>
+or
+<pre>
+  lib/gallium/libGL.so
+</pre>
+
+To use it set the LD_LIBRARY_PATH environment variable accordingly.
+
+For performance evaluation pass debug=no to scons, and use the corresponding
+lib directory without the "-debug" suffix.
+
+On Windows, building will create a drop-in alternative for opengl32.dll. To use
+it put it in the same directory as the 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.
+
+
+<h1>Profiling</h1>
+
+To profile llvmpipe you should pass the options
+
+<pre>
+  scons build=profile <same-as-before>
+</pre>
+
+This will ensure that frame pointers are used both in C and JIT functions, and
+that no tail call optimizations are done by gcc.
+
+To better profile JIT code you'll need to build LLVM with oprofile integration.
+
+<pre>
+  ./configure \
+      --prefix=$install_dir \
+      --enable-optimized \
+      --disable-profiling \
+      --enable-targets=host-only \
+      --with-oprofile
+
+  make -C "$build_dir"
+  make -C "$build_dir" install
+
+  find "$install_dir/lib" -iname '*.a' -print0 | xargs -0 strip --strip-debug
+</pre>
+
+The you should define
+
+<pre>
+  export LLVM=/path/to/llvm-2.6-profile
+</pre>
+
+and rebuild.
+
+
+<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 
+  http://npcontemplation.blogspot.com/2008/06/secret-of-llvm-c-bindings.html
+  for a stand-alone example.  See the llvm-c/Core.h file for reference.
+</li>
+</ul>
author	Brian Paul <brianp@vmware.com>	2011-04-07 13:56:45 -0600
committer	Brian Paul <brianp@vmware.com>	2011-04-07 13:56:45 -0600
commit	0da2a22ba6cbe6a2175ac47ab4541b1cfa939d1f (patch)
tree	1f73797e791f5b0de80f0dea5fc62f0ccae00757 /docs
parent	06613b7b3a641b66400f09993a884daf7ab34509 (diff)