src/gallium/drivers/llvmpipe/README

   1 LLVMPIPE -- a fork of softpipe that employs LLVM for code generation.
   2
   3
   4 Status
   5 ======
   6
   7 Done so far is:
   8
   9 - TGSI -> LLVM fragment shader translation
  10   - same level of support as the TGSI SSE2 exec machine
  11   - texture sampling via an intrinsic call
  12   - done in SoA
  13   - input interpolation also code generated
  14
  15 - blend -> LLVM (including logic ops)
  16   - SoA and AoS, but only the former used
  17
  18 - code is generic
  19   - intermediates can be vectors of floats, ubytes, fixed point, etc, and of
  20     any width and length
  21   - not all operations are implemented for these types yet though
  22
  23 Most mesa/progs/demos/* work. Speed is on par with Keith's softpipe-opt branch,
  24 which includes hand written fast implementations for common cases.
  25
  26 To do (probably by this order):
  27 - code generate the rest of the fragment pipeline, namely the
  28   depth/alpha/stencil state
  29 - concatenate the fragment pipeline (shader + depth/stencil/alpha + blend) in a
  30   single function
  31 - code generate texture sampling
  32 - translate TGSI control flow instructions
  33 - code generate the triangle setup and rasterization
  34
  35
  36 Requirements
  37 ============
  38
  39  - Linux
  40
  41  - udis86, http://udis86.sourceforge.net/ . Use my repository, which decodes
  42    opcodes not yet supported by upstream.
  43
  44      git clone git://people.freedesktop.org/~jrfonseca/udis86
  45      cd udis86
  46      ./configure --with-pic
  47      make
  48      sudo make install
  49
  50  - LLVM 2.5. On Debian based distributions do:
  51
  52      aptitude install llvm-dev
  53
  54    There is a typo in one of the llvm-dev 2.5 headers, that causes compilation
  55    errors in the debug build:
  56
  57      --- /usr/include/llvm-c/Core.h.orig        2009-08-10 15:38:54.000000000 +0100
  58      +++ /usr/include/llvm-c/Core.h     2009-08-10 15:38:25.000000000 +0100
  59      @@ -831,7 +831,7 @@
  60         template<typename T>
  61         inline T **unwrap(LLVMValueRef *Vals, unsigned Length) {
  62           #if DEBUG
  63      -    for (LLVMValueRef *I = Vals, E = Vals + Length; I != E; ++I)
  64      +    for (LLVMValueRef *I = Vals, *E = Vals + Length; I != E; ++I)
  65             cast<T>(*I);
  66           #endif
  67           return reinterpret_cast<T**>(Vals);
  68
  69  - A x86 or amd64 processor with support for sse2, sse3, and sse4.1 SIMD
  70    instructions. This is necessary because we emit several SSE intrinsics for
  71    convenience. See /proc/cpuinfo to know what your CPU supports.
  72
  73  - scons (although it should be straightforward to fix the Makefiles as well)
  74
  75
  76 Building
  77 ========
  78
  79 To build everything invoke scons as:
  80
  81   scons debug=yes statetrackers=mesa drivers=llvmpipe winsys=xlib dri=false -k
  82
  83
  84 Using
  85 =====
  86
  87 Building will create a drop-in alternative for libGL.so. To use it set the
  88 environment variables:
  89
  90   export LD_LIBRARY_PATH=$PWD/build/linux-x86-debug/lib:$LD_LIBRARY_PATH
  91   export LD_LIBRARY_PATH=$PWD/build/linux-x86_64-debug/lib:$LD_LIBRARY_PATH
  92
  93
  94 Unit testing
  95 ============
  96
  97 Building will also create several unit tests in
  98 build/linux-???-debug/gallium/drivers/llvmpipe:
  99
 100  - lp_test_blend: blending
 101  - lp_test_conv: SIMD vector conversion
 102  - lp_test_format: pixel unpacking/packing
 103
 104 Some of this tests can output results and benchmarks to a tab-seperated-file
 105 for posterior analysis, e.g.:
 106
 107   build/linux-x86_64/gallium/drivers/llvmpipe/lp_test_blend -o blend.tsv
 108
 109
 110 Development Notes
 111 =================
 112
 113 - We use LLVM-C bindings for now. They are not documented, but follow the C++
 114   interfaces very closely, and appear to be complete enough for code
 115   generation. See
 116   http://npcontemplation.blogspot.com/2008/06/secret-of-llvm-c-bindings.html
 117   for a standalone example.