231 lines
7.8 KiB
C
231 lines
7.8 KiB
C
/*
|
|
* <Copyright>
|
|
*
|
|
* Redistribution and use in source and binary forms, with or without
|
|
* modification, are permitted provided that the following conditions are met:
|
|
*
|
|
* Redistributions of source code must retain the above copyright notice, this
|
|
* list of conditions and the following disclaimer.
|
|
*
|
|
* Redistributions in binary form must reproduce the above copyright notice, this
|
|
* list of conditions and the following disclaimer in the documentation and/or
|
|
* other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY
|
|
* THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
|
|
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
|
* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
|
|
* EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
|
|
* INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
|
|
* BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
|
|
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
|
|
* OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
|
|
* ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
*
|
|
* liberasurecode frontend API header
|
|
*
|
|
* vi: set noai tw=79 ts=4 sw=4:
|
|
*/
|
|
|
|
#ifndef _ERASURECODE_H_
|
|
#define _ERASURECODE_H_
|
|
|
|
#include "list.h"
|
|
#include "erasurecode_stdinc.h"
|
|
#include "erasurecode_version.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/* =~=*=~==~=*=~==~=*=~= 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;
|
|
|
|
#ifndef EC_BACKENDS_SUPPORTED
|
|
#define EC_BACKENDS_SUPPORTED
|
|
/* Supported EC backends */
|
|
static const char *ec_backend_names[EC_BACKENDS_MAX] = {
|
|
"null",
|
|
"jerasure_rs_vand",
|
|
"jerasure_rs_cauchy",
|
|
"flat_xor_hd",
|
|
};
|
|
#endif // EC_BACKENDS_SUPPORTED
|
|
|
|
/* =~=*=~==~=*=~== EC Arguments - Common and backend-specific =~=*=~==~=*=~== */
|
|
|
|
/**
|
|
* Common and backend-specific args
|
|
* to be passed to liberasurecode_instance_create()
|
|
*/
|
|
struct ec_args {
|
|
int k; /* number of data fragments */
|
|
int m; /* number of parity fragments */
|
|
int w; /* word size, in bits (optional) */
|
|
|
|
union {
|
|
struct {
|
|
int hd; /* hamming distance (3 or 4) */
|
|
} flat_xor_hd_args; /* args specific to XOR codes */
|
|
struct {
|
|
uint64_t x, y; /* reserved for future expansion */
|
|
uint64_t z, a; /* reserved for future expansion */
|
|
} reserved;
|
|
} priv_args1;
|
|
|
|
void *priv_args2; /** flexible placeholder for
|
|
* future backend args */
|
|
|
|
int inline_chksum; /* embedded fragment checksums (yes/no), type */
|
|
int algsig_chksum; /* use algorithmic signature checksums */
|
|
};
|
|
|
|
/* =~=*=~==~=*=~== liberasurecode frontend API functions =~=*=~==~=~=*=~==~= */
|
|
|
|
/* liberasurecode frontend API functions */
|
|
|
|
/**
|
|
* Returns a list of supported EC backend names
|
|
*/
|
|
void liberasurecode_supported_backends(char **backend_names);
|
|
|
|
/**
|
|
* Create a liberasurecode instance and return a descriptor
|
|
* for use with EC operations (encode, decode, reconstruct)
|
|
*
|
|
* @param backend_name - one of the supported backends as
|
|
* defined by ec_backend_names
|
|
* @param ec_args - arguments to the EC backend
|
|
* arguments common to all backends
|
|
* k - number of data fragments
|
|
* m - number of parity fragments
|
|
* inline_checksum -
|
|
* algsig_checksum -
|
|
* backend-specific arguments
|
|
* flat_xor_hd_args - arguments for the xor_hd backend
|
|
*
|
|
* @returns liberasurecode instance descriptor (int > 0)
|
|
*/
|
|
int liberasurecode_instance_create(const char *backend_name,
|
|
struct ec_args *args);
|
|
|
|
/**
|
|
* Close a liberasurecode instance
|
|
*
|
|
* @param liberasurecode descriptor to close
|
|
*/
|
|
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,
|
|
const char *orig_data, uint64_t orig_data_size, /* input */
|
|
char **encoded_data, char **encoded_parity); /* output */
|
|
|
|
/**
|
|
* Reconstruct original data from a set of k encoded fragments
|
|
*
|
|
* @param desc - liberasurecode descriptor/handle
|
|
* from liberasurecode_instance_create()
|
|
* @param fragments - erasure encoded fragments (> = k)
|
|
* @param num_fragments - number of fragments being passed in
|
|
* @param fragment_len - length of each fragment (assume they are the same)
|
|
* @param out_data - output of decode
|
|
* @param out_data_len - length of decoded output
|
|
* @return 0 on success, -error code otherwise
|
|
*/
|
|
int liberasurecode_decode(int desc,
|
|
char **available_fragments, /* input */
|
|
int num_fragments, uint64_t fragment_len, /* input */
|
|
char *out_data, uint64_t *out_data_len); /* output */
|
|
|
|
/**
|
|
* Reconstruct a missing fragment from a subset of available fragments
|
|
*
|
|
* @param desc - liberasurecode descriptor/handle
|
|
* from liberasurecode_instance_create()
|
|
* @param fragment_len - size in bytes of the fragments
|
|
* @param available_fragments - erasure encoded fragments
|
|
* @param num_fragments - number of fragments being passed in
|
|
* @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,
|
|
char **available_fragments, /* input */
|
|
int num_fragments, uint64_t fragment_len, /* input */
|
|
int destination_idx, /* input */
|
|
char* out_fragment); /* output */
|
|
|
|
/**
|
|
* Determine which fragments are needed to reconstruct some subset
|
|
* of missing fragments. Returns a list of lists (as bitmaps)
|
|
* of fragments required to reconstruct missing indexes.
|
|
*/
|
|
int liberasurecode_fragments_needed(int desc,
|
|
int *missing_idxs, int *fragments_needed);
|
|
|
|
/**
|
|
* 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(char *fragment);
|
|
|
|
|
|
/**
|
|
* Verify a subset of fragments generated by encode()
|
|
*/
|
|
int liberasurecode_verify_stripe_metadata(char **fragments);
|
|
|
|
/**
|
|
* This computes the aligned size of a buffer passed into
|
|
* the encode function. The encode function must pad fragments
|
|
* to be algined with the word size (w) and the last fragment also
|
|
* needs to be aligned. This computes the sum of the algined fragment
|
|
* sizes for a given buffer to encode.
|
|
*/
|
|
int liberasurecode_get_aligned_data_size(int desc, int data_len);
|
|
|
|
/**
|
|
* This will return the minumum encode size, which is the minimum
|
|
* buffer size that can be encoded.
|
|
*/
|
|
int liberasurecode_get_minimum_encode_size(int desc);
|
|
|
|
|
|
/* ==~=*=~===~=*=~==~=*=~== liberasurecode Error codes =~=*=~==~=~=*=~==~== */
|
|
|
|
/* Error codes */
|
|
typedef enum {
|
|
EBACKENDNOTSUPP = 200,
|
|
EECMETHODNOTIMPL = 201,
|
|
EBACKENDINITERR = 202,
|
|
EBACKENDINUSE = 203,
|
|
EBACKENDNOTAVAIL = 204,
|
|
} LIBERASURECODE_ERROR_CODES;
|
|
|
|
/* =~=*=~==~=*=~==~=*=~==~=*=~===~=*=~==~=*=~===~=*=~==~=*=~===~=*=~==~=*=~= */
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif // _ERASURECODE_H_
|