1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2 <html lang="en"> 3 <head> 4 <meta http-equiv="content-type" content="text/html; charset=utf-8"> 5 <title>llvmpipe</title> 6 <link rel="stylesheet" type="text/css" href="mesa.css"> 7 </head> 8 <body> 9 10 <h1>Introduction</h1> 11 12 <p> 13 The Gallium llvmpipe driver is a software rasterizer that uses LLVM to 14 do runtime code generation. 15 Shaders, point/line/triangle rasterization and vertex processing are 16 implemented with LLVM IR which is translated to x86 or x86-64 machine 17 code. 18 Also, the driver is multithreaded to take advantage of multiple CPU cores 19 (up to 8 at this time). 20 It's the fastest software rasterizer for Mesa. 21 </p> 22 23 24 <h1>Requirements</h1> 25 26 <ul> 27 <li> 28 <p>An x86 or amd64 processor; 64-bit mode recommended.</p> 29 <p> 30 Support for SSE2 is strongly encouraged. Support for SSSE3 and SSE4.1 will 31 yield the most efficient code. The fewer features the CPU has the more 32 likely is that you run into underperforming, buggy, or incomplete code. 33 </p> 34 <p> 35 See /proc/cpuinfo to know what your CPU supports. 36 </p> 37 </li> 38 <li> 39 <p>LLVM: version 2.9 recommended; 2.6 or later required.</p> 40 <p><b>NOTE</b>: LLVM 2.8 and earlier will not work on systems that support the 41 Intel AVX extensions (e.g. Sandybridge). LLVM's code generator will 42 fail when trying to emit AVX instructions. This was fixed in LLVM 2.9. 43 </p> 44 <p> 45 For Linux, on a recent Debian based distribution do: 46 </p> 47 <pre> 48 aptitude install llvm-dev 49 </pre> 50 <p> 51 For a RPM-based distribution do: 52 </p> 53 <pre> 54 yum install llvm-devel 55 </pre> 56 57 <p> 58 For Windows you will need to build LLVM from source with MSVC or MINGW 59 (either natively or through cross compilers) and CMake, and set the LLVM 60 environment variable to the directory you installed it to. 61 62 LLVM will be statically linked, so when building on MSVC it needs to be 63 built with a matching CRT as Mesa, and you'll need to pass 64 -DLLVM_USE_CRT_RELEASE=MTd for debug and checked builds, 65 -DLLVM_USE_CRT_RELEASE=MTd for profile and release builds. 66 67 You can build only the x86 target by passing -DLLVM_TARGETS_TO_BUILD=X86 68 to cmake. 69 </p> 70 </li> 71 72 <li> 73 <p>scons (optional)</p> 74 </li> 75 </ul> 76 77 78 <h1>Building</h1> 79 80 To build everything on Linux invoke scons as: 81 82 <pre> 83 scons build=debug libgl-xlib 84 </pre> 85 86 Alternatively, you can build it with GNU make, if you prefer, by invoking it as 87 88 <pre> 89 make linux-llvm 90 </pre> 91 92 but the rest of these instructions assume that scons is used. 93 94 For Windows the procedure is similar except the target: 95 96 <pre> 97 scons build=debug libgl-gdi 98 </pre> 99 100 101 <h1>Using</h1> 102 103 On Linux, building will create a drop-in alternative for libGL.so into 104 105 <pre> 106 build/foo/gallium/targets/libgl-xlib/libGL.so 107 </pre> 108 or 109 <pre> 110 lib/gallium/libGL.so 111 </pre> 112 113 To use it set the LD_LIBRARY_PATH environment variable accordingly. 114 115 For performance evaluation pass debug=no to scons, and use the corresponding 116 lib directory without the "-debug" suffix. 117 118 On Windows, building will create a drop-in alternative for opengl32.dll. To use 119 it put it in the same directory as the application. It can also be used by 120 replacing the native ICD driver, but it's quite an advanced usage, so if you 121 need to ask, don't even try it. 122 123 124 <h1>Profiling</h1> 125 126 To profile llvmpipe you should pass the options 127 128 <pre> 129 scons build=profile <same-as-before> 130 </pre> 131 132 This will ensure that frame pointers are used both in C and JIT functions, and 133 that no tail call optimizations are done by gcc. 134 135 To better profile JIT code you'll need to build LLVM with oprofile integration. 136 137 <pre> 138 ./configure \ 139 --prefix=$install_dir \ 140 --enable-optimized \ 141 --disable-profiling \ 142 --enable-targets=host-only \ 143 --with-oprofile 144 145 make -C "$build_dir" 146 make -C "$build_dir" install 147 148 find "$install_dir/lib" -iname '*.a' -print0 | xargs -0 strip --strip-debug 149 </pre> 150 151 The you should define 152 153 <pre> 154 export LLVM=/path/to/llvm-2.6-profile 155 </pre> 156 157 and rebuild. 158 159 160 <h1>Unit testing</h1> 161 162 <p> 163 Building will also create several unit tests in 164 build/linux-???-debug/gallium/drivers/llvmpipe: 165 </p> 166 167 <ul> 168 <li> lp_test_blend: blending 169 <li> lp_test_conv: SIMD vector conversion 170 <li> lp_test_format: pixel unpacking/packing 171 </ul> 172 173 <p> 174 Some of this tests can output results and benchmarks to a tab-separated-file 175 for posterior analysis, e.g.: 176 </p> 177 <pre> 178 build/linux-x86_64-debug/gallium/drivers/llvmpipe/lp_test_blend -o blend.tsv 179 </pre> 180 181 182 <h1>Development Notes</h1> 183 184 <ul> 185 <li> 186 When looking to this code by the first time start in lp_state_fs.c, and 187 then skim through the lp_bld_* functions called in there, and the comments 188 at the top of the lp_bld_*.c functions. 189 </li> 190 <li> 191 The driver-independent parts of the LLVM / Gallium code are found in 192 src/gallium/auxiliary/gallivm/. The filenames and function prefixes 193 need to be renamed from "lp_bld_" to something else though. 194 </li> 195 <li> 196 We use LLVM-C bindings for now. They are not documented, but follow the C++ 197 interfaces very closely, and appear to be complete enough for code 198 generation. See 199 http://npcontemplation.blogspot.com/2008/06/secret-of-llvm-c-bindings.html 200 for a stand-alone example. See the llvm-c/Core.h file for reference. 201 </li> 202 </ul> 203 204 </body> 205 </html> 206
