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