erasure code: add shec's documentation / change default layout

Signed-off-by: Takeshi Miyamae <miyamae.takeshi@jp.fujitsu.com>

diff --git a/doc/rados/operations/erasure-code-isa.rst b/doc/rados/operations/erasure-code-isa.rst
index 241c7faeef9c30c197ebfa012723762ec11453ba..9d4ff7f52f0aa024a1e42207f9e286e345a00e2e 100644 (file)
--- a/doc/rados/operations/erasure-code-isa.rst
+++ b/doc/rados/operations/erasure-code-isa.rst
@@ -2,14 +2,14 @@
 ISA erasure code plugin
 =======================
 
-The *isa* plugin is encapsulates the `ISA
+The *isa* plugin encapsulates the `ISA
 <https://01.org/intel%C2%AE-storage-acceleration-library-open-source-version/>`_
 library. It only runs on Intel processors.
 
 Create an isa profile
 =====================
 
-To create a new *jerasure* erasure code profile::
+To create a new *isa* erasure code profile::
 
         ceph osd erasure-code-profile set {name} \
              plugin=isa \

diff --git a/doc/rados/operations/erasure-code-shec.rst b/doc/rados/operations/erasure-code-shec.rst
new file mode 100644 (file)
index 0000000..2d71ad7
--- /dev/null
+++ b/doc/rados/operations/erasure-code-shec.rst
@@ -0,0 +1,133 @@
+========================
+SHEC erasure code plugin
+========================
+
+The *shec* plugin encapsulates the `multiple SHEC
+<https://wiki.ceph.com/Planning/Blueprints/Hammer/Shingled_Erasure_Code_(SHEC)>`_
+library. It allows ceph to recover data more efficiently than Reed Solomon codes.
+
+Create an SHEC profile
+======================
+
+To create a new *shec* erasure code profile::
+
+        ceph osd erasure-code-profile set {name} \
+             plugin=shec \
+             [k={data-chunks}] \
+             [m={coding-chunks}] \
+             [c={durability-estimator}] \
+             [ruleset-root={root}] \
+             [ruleset-failure-domain={bucket-type}] \
+             [directory={directory}] \
+             [--force]
+
+Where:
+
+``k={data-chunks}``
+
+:Description: Each object is split in **data-chunks** parts,
+              each stored on a different OSD.
+
+:Type: Integer
+:Required: No.
+:Default: 4
+
+``m={coding-chunks}``
+
+:Description: Compute **coding-chunks** for each object and store them on
+              different OSDs. The number of **coding-chunks** does not necessarily
+              equal the number of OSDs that can be down without losing data.
+
+:Type: Integer
+:Required: No.
+:Default: 3
+
+``c={durability-estimator}``
+
+:Description: The number of parity chunks each of which includes each data chunk in its
+              calculation range. The number is used as a **durability estimator**.
+              For instance, if c=2, 2 OSDs can be down without losing data.
+
+:Type: Integer
+:Required: No.
+:Default: 2
+
+``ruleset-root={root}``
+
+:Description: The name of the crush bucket used for the first step of
+              the ruleset. For intance **step take default**.
+
+:Type: String
+:Required: No.
+:Default: default
+
+``ruleset-failure-domain={bucket-type}``
+
+:Description: Ensure that no two chunks are in a bucket with the same
+              failure domain. For instance, if the failure domain is
+              **host** no two chunks will be stored on the same
+              host. It is used to create a ruleset step such as **step
+              chooseleaf host**.
+
+:Type: String
+:Required: No.
+:Default: host
+
+``directory={directory}``
+
+:Description: Set the **directory** name from which the erasure code
+              plugin is loaded.
+
+:Type: String
+:Required: No.
+:Default: /usr/lib/ceph/erasure-code
+
+``--force``
+
+:Description: Override an existing profile by the same name.
+
+:Type: String
+:Required: No.
+
+Brief description of SHEC's layouts
+===================================
+
+Space Efficiency
+----------------
+
+Space efficiency is a ratio of data chunks to all ones in a object and
+represented as k/(k+m).
+In order to improve space efficiency, you should increase k or decrease m.
+
+::
+
+        space efficiency of SHEC(4,3,2) = 4/(4+3) = 0.57
+        SHEC(5,3,2) or SHEC(4,2,2) improves SHEC(4,3,2)'s space efficiency
+
+Durability
+----------
+
+The third parameter of SHEC (=c) is a durability estimator, which approximates
+the number of OSDs that can be down without losing data.
+
+``durability estimator of SHEC(4,3,2) = 2``
+
+Recovery Efficiency
+-------------------
+
+Describing calculation of recovery efficiency is beyond the scope of this document,
+but at least increasing m without increasing c achieves improvement of recovery efficiency.
+(However, we must pay attention to the sacrifice of space efficiency in this case.)
+
+``SHEC(4,2,2) -> SHEC(4,3,2) : achieves improvement of recovery efficiency``
+
+Erasure code profile examples
+=============================
+
+::
+
+        $ ceph osd erasure-code-profile set SHECprofile \
+             plugin=shec \
+             k=8 m=4 c=3 \
+             ruleset-failure-domain=host
+        $ ceph osd pool create shecpool 256 256 erasure SHECprofile

diff --git a/src/erasure-code/shec/ErasureCodeShec.h b/src/erasure-code/shec/ErasureCodeShec.h
index 937d72f34f20f55f4be166bafd88a09284707a1c..7eaccf5e7fd9e9f61f5dcc979fef8b37d2563910 100644 (file)
--- a/src/erasure-code/shec/ErasureCodeShec.h
+++ b/src/erasure-code/shec/ErasureCodeShec.h
@@ -52,11 +52,11 @@ public:
                  ErasureCodeShecTableCache &_tcache) :
     tcache(_tcache),
     k(0),
-    DEFAULT_K(2),
+    DEFAULT_K(4),
     m(0),
-    DEFAULT_M(1),
+    DEFAULT_M(3),
     c(0),
-    DEFAULT_C(1),
+    DEFAULT_C(2),
     w(0),
     DEFAULT_W(8),
     technique(_technique),

diff --git a/src/test/erasure-code/TestErasureCodeShec.cc b/src/test/erasure-code/TestErasureCodeShec.cc
index 8d3a5f6a206794e17ef78cb31eaf70867474b073..25325f64d2d01642350aefb140babd132ed5d980 100644 (file)
--- a/src/test/erasure-code/TestErasureCodeShec.cc
+++ b/src/test/erasure-code/TestErasureCodeShec.cc
@@ -785,9 +785,9 @@ TEST(ErasureCodeShec, init_29)
   EXPECT_TRUE(shec->matrix != NULL);
   EXPECT_EQ(0, r);
   //k,m,c are default values
-  EXPECT_EQ(2u, shec->k);
-  EXPECT_EQ(1u, shec->m);
-  EXPECT_EQ(1u, shec->c);
+  EXPECT_EQ(4u, shec->k);
+  EXPECT_EQ(3u, shec->m);
+  EXPECT_EQ(2u, shec->c);
 
   delete shec;
   delete parameters;