José Fonseca | 9285f15 | 2009-08-10 12:35:16 +0100 | [diff] [blame] | 1 | LLVMPIPE -- a fork of softpipe that employs LLVM for code generation. |
| 2 | |
| 3 | |
| 4 | Requirements |
| 5 | ============ |
| 6 | |
José Fonseca | da1c402 | 2009-11-26 11:15:08 +0000 | [diff] [blame] | 7 | - A x86 or amd64 processor. 64bit mode is preferred. |
| 8 | |
| 9 | Support for sse2 is strongly encouraged. Support for ssse3, and sse4.1 will |
| 10 | yield the most efficient code. The less features the CPU has the more |
| 11 | likely is that you ran into underperforming, buggy, or incomplete code. |
| 12 | |
| 13 | See /proc/cpuinfo to know what your CPU supports. |
José Fonseca | 818d444 | 2009-08-16 11:50:17 +0100 | [diff] [blame] | 14 | |
José Fonseca | e6314db | 2011-03-13 19:24:26 +0000 | [diff] [blame^] | 15 | - LLVM. Version 2.8 recommended. 2.6 or later required. |
José Fonseca | 818d444 | 2009-08-16 11:50:17 +0100 | [diff] [blame] | 16 | |
José Fonseca | 1257655 | 2010-01-10 18:37:07 +0000 | [diff] [blame] | 17 | For Linux, on a recent Debian based distribution do: |
José Fonseca | 9285f15 | 2009-08-10 12:35:16 +0100 | [diff] [blame] | 18 | |
| 19 | aptitude install llvm-dev |
José Fonseca | 19b31d0 | 2009-08-10 15:43:04 +0100 | [diff] [blame] | 20 | |
José Fonseca | 1257655 | 2010-01-10 18:37:07 +0000 | [diff] [blame] | 21 | For Windows download pre-built MSVC 9.0 or MinGW binaries from |
| 22 | http://people.freedesktop.org/~jrfonseca/llvm/ and set the LLVM environment |
| 23 | variable to the extracted path. |
José Fonseca | 19b31d0 | 2009-08-10 15:43:04 +0100 | [diff] [blame] | 24 | |
José Fonseca | f379e7d | 2010-05-13 16:18:05 +0100 | [diff] [blame] | 25 | For MSVC there are two set of binaries: llvm-x.x-msvc32mt.7z and |
| 26 | llvm-x.x-msvc32mtd.7z . |
| 27 | |
| 28 | You have to set the LLVM=/path/to/llvm-x.x-msvc32mtd env var when passing |
| 29 | debug=yes to scons, and LLVM=/path/to/llvm-x.x-msvc32mt when building with |
| 30 | debug=no. This is necessary as LLVM builds as static library so the chosen |
| 31 | MS CRT must match. |
| 32 | |
José Fonseca | 8bf4e5d | 2009-11-24 16:01:01 +0000 | [diff] [blame] | 33 | - scons (optional) |
José Fonseca | 9285f15 | 2009-08-10 12:35:16 +0100 | [diff] [blame] | 34 | |
| 35 | |
| 36 | Building |
| 37 | ======== |
| 38 | |
José Fonseca | 1257655 | 2010-01-10 18:37:07 +0000 | [diff] [blame] | 39 | To build everything on Linux invoke scons as: |
José Fonseca | 9285f15 | 2009-08-10 12:35:16 +0100 | [diff] [blame] | 40 | |
José Fonseca | 601498a | 2010-11-01 13:30:22 +0000 | [diff] [blame] | 41 | scons build=debug libgl-xlib |
José Fonseca | 9285f15 | 2009-08-10 12:35:16 +0100 | [diff] [blame] | 42 | |
José Fonseca | 5811ed8 | 2009-08-22 22:26:55 +0100 | [diff] [blame] | 43 | Alternatively, you can build it with GNU make, if you prefer, by invoking it as |
| 44 | |
| 45 | make linux-llvm |
| 46 | |
José Fonseca | 1fc4100 | 2009-09-11 11:24:00 +0100 | [diff] [blame] | 47 | but the rest of these instructions assume that scons is used. |
José Fonseca | 5811ed8 | 2009-08-22 22:26:55 +0100 | [diff] [blame] | 48 | |
José Fonseca | 1257655 | 2010-01-10 18:37:07 +0000 | [diff] [blame] | 49 | For windows is everything the except except the winsys: |
| 50 | |
José Fonseca | 601498a | 2010-11-01 13:30:22 +0000 | [diff] [blame] | 51 | scons build=debug libgl-gdi |
José Fonseca | 9285f15 | 2009-08-10 12:35:16 +0100 | [diff] [blame] | 52 | |
| 53 | Using |
| 54 | ===== |
| 55 | |
José Fonseca | 601498a | 2010-11-01 13:30:22 +0000 | [diff] [blame] | 56 | On Linux, building will create a drop-in alternative for libGL.so into |
José Fonseca | 9285f15 | 2009-08-10 12:35:16 +0100 | [diff] [blame] | 57 | |
José Fonseca | 601498a | 2010-11-01 13:30:22 +0000 | [diff] [blame] | 58 | build/foo/gallium/targets/libgl-xlib/libGL.so |
José Fonseca | 9285f15 | 2009-08-10 12:35:16 +0100 | [diff] [blame] | 59 | |
José Fonseca | 601498a | 2010-11-01 13:30:22 +0000 | [diff] [blame] | 60 | To use it set the LD_LIBRARY_PATH environment variable accordingly. |
José Fonseca | 5811ed8 | 2009-08-22 22:26:55 +0100 | [diff] [blame] | 61 | |
José Fonseca | 1fc4100 | 2009-09-11 11:24:00 +0100 | [diff] [blame] | 62 | For performance evaluation pass debug=no to scons, and use the corresponding |
| 63 | lib directory without the "-debug" suffix. |
| 64 | |
José Fonseca | 1257655 | 2010-01-10 18:37:07 +0000 | [diff] [blame] | 65 | On Windows, building will create a drop-in alternative for opengl32.dll. To use |
| 66 | it put it in the same directory as the application. It can also be used by |
| 67 | replacing the native ICD driver, but it's quite an advanced usage, so if you |
| 68 | need to ask, don't even try it. |
| 69 | |
José Fonseca | 9285f15 | 2009-08-10 12:35:16 +0100 | [diff] [blame] | 70 | |
José Fonseca | 388c941 | 2010-09-21 17:50:30 +0100 | [diff] [blame] | 71 | Profiling |
| 72 | ========= |
| 73 | |
| 74 | To profile llvmpipe you should pass the options |
| 75 | |
José Fonseca | 601498a | 2010-11-01 13:30:22 +0000 | [diff] [blame] | 76 | scons build=profile <same-as-before> |
José Fonseca | 388c941 | 2010-09-21 17:50:30 +0100 | [diff] [blame] | 77 | |
| 78 | This will ensure that frame pointers are used both in C and JIT functions, and |
| 79 | that no tail call optimizations are done by gcc. |
| 80 | |
| 81 | |
| 82 | To better profile JIT code you'll need to build LLVM with oprofile integration. |
| 83 | |
José Fonseca | e6314db | 2011-03-13 19:24:26 +0000 | [diff] [blame^] | 84 | ./configure \ |
José Fonseca | 388c941 | 2010-09-21 17:50:30 +0100 | [diff] [blame] | 85 | --prefix=$install_dir \ |
| 86 | --enable-optimized \ |
| 87 | --disable-profiling \ |
| 88 | --enable-targets=host-only \ |
| 89 | --with-oprofile |
| 90 | |
| 91 | make -C "$build_dir" |
| 92 | make -C "$build_dir" install |
| 93 | |
| 94 | find "$install_dir/lib" -iname '*.a' -print0 | xargs -0 strip --strip-debug |
| 95 | |
| 96 | The you should define |
| 97 | |
| 98 | export LLVM=/path/to/llvm-2.6-profile |
| 99 | |
| 100 | and rebuild. |
| 101 | |
| 102 | |
José Fonseca | 9285f15 | 2009-08-10 12:35:16 +0100 | [diff] [blame] | 103 | Unit testing |
| 104 | ============ |
| 105 | |
| 106 | Building will also create several unit tests in |
| 107 | build/linux-???-debug/gallium/drivers/llvmpipe: |
| 108 | |
| 109 | - lp_test_blend: blending |
| 110 | - lp_test_conv: SIMD vector conversion |
| 111 | - lp_test_format: pixel unpacking/packing |
| 112 | |
José Fonseca | 1fc4100 | 2009-09-11 11:24:00 +0100 | [diff] [blame] | 113 | Some of this tests can output results and benchmarks to a tab-separated-file |
José Fonseca | 89146cd | 2009-08-20 10:21:49 +0100 | [diff] [blame] | 114 | for posterior analysis, e.g.: |
| 115 | |
José Fonseca | 5811ed8 | 2009-08-22 22:26:55 +0100 | [diff] [blame] | 116 | build/linux-x86_64-debug/gallium/drivers/llvmpipe/lp_test_blend -o blend.tsv |
José Fonseca | 9285f15 | 2009-08-10 12:35:16 +0100 | [diff] [blame] | 117 | |
José Fonseca | c5531f5 | 2009-08-21 10:57:48 +0100 | [diff] [blame] | 118 | |
| 119 | Development Notes |
| 120 | ================= |
| 121 | |
José Fonseca | 5811ed8 | 2009-08-22 22:26:55 +0100 | [diff] [blame] | 122 | - When looking to this code by the first time start in lp_state_fs.c, and |
| 123 | then skim through the lp_bld_* functions called in there, and the comments |
| 124 | at the top of the lp_bld_*.c functions. |
| 125 | |
Brian Paul | d0b3535 | 2010-03-15 11:46:41 -0600 | [diff] [blame] | 126 | - The driver-independent parts of the LLVM / Gallium code are found in |
| 127 | src/gallium/auxiliary/gallivm/. The filenames and function prefixes |
| 128 | need to be renamed from "lp_bld_" to something else though. |
José Fonseca | 5811ed8 | 2009-08-22 22:26:55 +0100 | [diff] [blame] | 129 | |
José Fonseca | c5531f5 | 2009-08-21 10:57:48 +0100 | [diff] [blame] | 130 | - We use LLVM-C bindings for now. They are not documented, but follow the C++ |
| 131 | interfaces very closely, and appear to be complete enough for code |
| 132 | generation. See |
| 133 | http://npcontemplation.blogspot.com/2008/06/secret-of-llvm-c-bindings.html |
José Fonseca | 601498a | 2010-11-01 13:30:22 +0000 | [diff] [blame] | 134 | for a stand-alone example. See the llvm-c/Core.h file for reference. |