src/ceph/src/erasure-code/isa/README

   1 ============================================
   2 INTEL ISA library Erasure Coding plugin
   3 ============================================
   4
   5 Build Requirements
   6 ==================
   7 Plug-in build compiles the included sources of ISA-L v2.10 and links them into the plugin. ISA-L implementation is portable and probes CPU features during runtime. Note that the names of the assembler source files have been renamed from *.asm to *.asm.s to be compatible with Automake.
   8
   9 Run-time Requirements
  10 =====================
  11 None
  12
  13 Plug-in Configuration
  14 =====================
  15
  16 Used parameters are:
  17 k : number of data chunks
  18 m : number of coding chunks
  19 technique : cauchy, reed_sol_van
  20
  21 The plug-in exports only two encoding technique (cauchy, reed_sol_van) using either a Vandermonde matrix or a Cauchy matrix for coding.
  22 By default a Vandermonde matrix is used. Be aware that sometimes the generated Vandermonde matrix is not always invertible and not fully MDS.
  23 Therefore the accepted parameter space has limited to maximum (21,4) and (32,3) for Vandermonde matrices.
  24
  25 Run the Test suite
  26 ==================
  27 cd ceph/src
  28 make unittest_erasure_code_isa
  29 ./unittest_erasure_code_isa --gtest_filter=*.* --log-to-stderr=true --debug-ods=20
  30
  31 Run the CEPH erasure code benchmark
  32 ===================================
  33 cd ceph/src
  34 make ceph_erasure_code_benchmark
  35
  36 # consult ./ceph_erasure_code_benchmark -h for help
  37
  38 # encode performance
  39 ./ceph_erasure_code_benchmark -p isa -P k=8 -P m=3 -S 1048576 -i 1000
  40
  41 # decode performance one lost
  42 ./ceph_erasure_code_benchmark -e 1 -w decode -p isa -P k=8 -P m=3 -S 1048576 -i 1000
  43
  44 # decode performance two lost
  45 ./ceph_erasure_code_benchmark -e 2 -w decode -p isa -P k=8 -P m=3 -S 1048576 -i 1000
  46
  47 # decode performance three lost
  48 ./ceph_erasure_code_benchmark -e 3 -w decode -p isa -P k=8 -P m=3 -S 1048576 -i 1000
  49
  50
  51 Developer Notes
  52 ===============
  53 The plugin provides optimal performance for 32-byte aligned buffer start address and
  54 k*32 byte aligned buffer length. The encoding tables are computed only once when the EC
  55 object is created. Decoding Tables have to be computed for each decoding since the available
  56 data/coding sources may change between calls.
  57 Decoding tables are cached in an LRU cache which is sufficiently large up to (12,4).
  58
  59 For larger configurations the cache might expire the 'oldest' tables and decoding might
  60 slow down. The plug-in uses an optimization to use a pure region XOR to decode single disk
  61 failures if the erased chunk is within the first (k+1) chunks.
  62
  63 The unittest probes all possible failure scenarios for (12,4) Vandermonde and Cauchy matrices.