aboutsummaryrefslogtreecommitdiff
path: root/mesalib/docs/llvmpipe.html
diff options
context:
space:
mode:
Diffstat (limited to 'mesalib/docs/llvmpipe.html')
-rw-r--r--mesalib/docs/llvmpipe.html406
1 files changed, 202 insertions, 204 deletions
diff --git a/mesalib/docs/llvmpipe.html b/mesalib/docs/llvmpipe.html
index 5f4e9de3b..bd9cc26f2 100644
--- a/mesalib/docs/llvmpipe.html
+++ b/mesalib/docs/llvmpipe.html
@@ -1,204 +1,202 @@
-<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>
+<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>
+
+<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 2.9 recommended; 2.6 or later required.</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 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
+ -DLLVM_USE_CRT_RELEASE=MTd for debug and checked builds,
+ -DLLVM_USE_CRT_RELEASE=MTd for profile and release builds.
+
+ 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 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>