liberasurecode API changes after discussion w/ Kevin

Signed-off-by: Tushar Gohad <tushar.gohad@intel.com>

1 files changed, 119 insertions, 17 deletions

diff --git a/include/erasurecode/erasurecode.h b/include/erasurecode/erasurecode.h
index ccced1b..250bae9 100644
--- a/include/erasurecode/erasurecode.h
+++ b/include/erasurecode/erasurecode.h
@@ -22,6 +22,8 @@
  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  *
  * liberasurecode frontend API header
+ *
+ * vi: set noai tw=79 ts=4 sw=4:
  */
 
 #ifndef _ERASURECODE_H_
@@ -41,33 +43,131 @@ extern "C" {
 #define dl_restrict
 #endif
 
+/* =~=*=~==~=*=~==~=*=~= Supported EC backends =~=*=~==~=*=~==~=*=~==~=*=~== */
+
+/* Supported EC backends */
+typedef enum {
+    EC_BACKEND_NULL                     = 0,
+    EC_BACKEND_JERASURE_RS_VAND         = 1,
+    EC_BACKEND_JERASURE_RS_CAUCHY       = 2,
+    EC_BACKEND_FLAT_XOR_HD              = 3,
+    EC_BACKENDS_MAX,
+} ec_backend_id_t;
+
+const char *ec_backend_names[EC_BACKENDS_MAX] =
+    "null",
+    "jerasure_rs_vand",
+    "jerasure_rs_cauchy",
+    "flat_xor_hd";
+
+/* =~=*=~==~=*=~== EC Arguments - Common and backend-specific =~=*=~==~=*=~== */
+
+/**
+ * Common and backend-specific args
+ * to be passed to liberasurecode_instance_create()
+ */
+struct ec_args {
+    int k;
+    int m;
+    union {
+        struct {
+            int hd;
+        } flat_xor_hd_args;
+        struct {
+            int w;
+        } jerasure_args;
+    }
+    int inline_chksum;
+    int algsig_chksum;
+}
+
+/* =~=*=~==~=*=~== liberasurecode frontend API functions =~=*=~==~=~=*=~==~= */
+
 /* liberasurecode frontend API functions */
+
+/**
+ */
 void liberasurecode_supported_backends(char **backend_names);
 
+/**
+ */
 int liberasurecode_instance_create(const char *backend_name,
-        int k, int m, int w, void *args);
+                                   sturct ec_args *args);
+
+/**
+ */
 int liberasurecode_instance_destroy(int desc);
 
+
+/**
+ * Erasure encode a data buffer
+ *
+ * @param desc - liberasurecode descriptor/handle
+ *        from liberasurecode_instance_create()
+ * @param orig_data - data to encode
+ * @param orig_data_size - length of data to encode
+ * @param encoded_data - to return k data fragments
+ * @param encoded_parity - to return m parity fragments
+ * @return 0 on success, -error code otherwise
+ */
 int liberasurecode_encode(int desc,
-        char **data, char **parity, int blocksize);
-int liberasurecode_decode(int desc,
-        char **data, char **parity, int *missing_idxs,
-        int blocksize);
-int liberasurecode_reconstruct(int desc,
-        char **data, char **parity, int *missing_idxs,
-        int destination_idx, int blocksize);
+        const char *orig_data, uint64_t orig_data_size,
+        char **encoded_data, char **encoded_parity);
+
+/**
+ * Reconstruct original data from a set of k encoded fragments
+ *
+ * @param desc - liberasurecode descriptor/handle
+ *        from liberasurecode_instance_create()
+ * @param fragment_size - size in bytes of the fragments
+ * @param encoded_data - erasure encoded data fragments (k)
+ * @param encoded_parity - erasure encoded parity fragments (m)
+ * @param out_data - output of decode
+ * @return 0 on success, -error code otherwise
+ */
+int liberasurecode_decode(int desc, uint64_t fragment_size, 
+        char **encoded_data, char **encoded_parity,
+        char *out_data);
+
+/**
+ * Reconstruct a missing fragment from a subset of available fragments
+ *
+ * @param desc - liberasurecode descriptor/handle
+ *        from liberasurecode_instance_create()
+ * @param fragment_size - size in bytes of the fragments
+ * @param encoded_data - erasure encoded data fragments (k)
+ * @param encoded_parity - erasure encoded parity fragments (m)
+ * @param destination_idx - missing idx to reconstruct
+ * @param out_fragment - output of reconstruct
+ * @return 0 on success, -error code otherwise
+ */
+int liberasurecode_reconstruct_fragment(int desc,
+        uint64_t fragment_size,
+        char **encoded_data, char **encoded_parity,
+        int destination_idx, char* out_fragment);
+
+/**
+ * Determine which fragments are needed to reconstruct some subset
+ * of missing fragments.
+ */
 int liberasurecode_fragments_needed(int desc,
         int *missing_idxs, int *fragments_needed);
 
-/* Supported EC backends */
-typedef enum {
-    EC_BACKEND_NULL             = 0,
-    EC_BACKEND_RS_VAND          = 1,
-    EC_BACKEND_RS_CAUCHY_ORIG   = 2,
-    EC_BACKEND_FLAT_XOR_3       = 3,
-    EC_BACKEND_FLAT_XOR_4       = 4,
-    EC_BACKENDS_MAX,
-} ec_backend_id_t;
+/**
+ * Get opaque metadata for a fragment.  The metadata is opaque to the
+ * client, but meaningful to the underlying library.  It is used to verify
+ * stripes in verify_stripe_metadata().
+ */
+// int liberasurecode_get_fragment_metadata()
+
+
+/**
+ * Verify a subset of fragments generated by encode()
+ */
+// int liberasurecode_verify_stripe_metadata()
+
+
+/* ==~=*=~===~=*=~==~=*=~== liberasurecode Error codes =~=*=~==~=~=*=~==~== */
 
 /* Error codes */
 typedef enum {
@@ -77,6 +177,8 @@ typedef enum {
     EBACKENDNOTAVAIL = 204,
 } LIBERASURECODE_ERROR_CODES;
 
+/* =~=*=~==~=*=~==~=*=~==~=*=~===~=*=~==~=*=~===~=*=~==~=*=~===~=*=~==~=*=~= */
+
 #ifdef __cplusplus
 }
 #endif