liberasurecode 1.6.3
Erasure Code API library
Loading...
Searching...
No Matches
Functions | Variables
erasurecode.c File Reference
#include <assert.h>
#include <zlib.h>
#include "list.h"
#include "erasurecode.h"
#include "erasurecode_backend.h"
#include "erasurecode_helpers.h"
#include "erasurecode_helpers_ext.h"
#include "erasurecode_preprocessing.h"
#include "erasurecode_postprocessing.h"
#include "erasurecode_stdinc.h"
#include "alg_sig.h"
#include "erasurecode_log.h"

Go to the source code of this file.

Functions

 SLIST_HEAD (backend_list, ec_backend)
 Look up a backend instance by descriptor.
 
int liberasurecode_backend_alloc_desc (void)
 Allocated backend instance descriptor.
 
int liberasurecode_backend_instance_register (ec_backend_t instance)
 Register a backend instance with liberasurecode.
 
int liberasurecode_backend_instance_unregister (ec_backend_t instance)
 Unregister a backend instance.
 
static void print_dlerror (const char *caller)
 
void * liberasurecode_backend_open (ec_backend_t instance)
 
int liberasurecode_backend_close (ec_backend_t instance)
 
void __attribute__ ((constructor))
 
void __attribute__ ((destructor))
 
int liberasurecode_backend_available (const ec_backend_id_t backend_id)
 Checks if a given backend is available.
 
int liberasurecode_instance_create (const ec_backend_id_t id, struct ec_args *args)
 Create a liberasurecode instance and return a descriptor for use with EC operations (encode, decode, reconstruct)
 
int liberasurecode_instance_destroy (int desc)
 Close a liberasurecode instance.
 
int liberasurecode_encode_cleanup (int desc, char **encoded_data, char **encoded_parity)
 Cleanup structures allocated by librasurecode_encode.
 
int liberasurecode_encode (int desc, const char *orig_data, uint64_t orig_data_size, char ***encoded_data, char ***encoded_parity, uint64_t *fragment_len)
 Erasure encode a data buffer.
 
int liberasurecode_decode_cleanup (int desc, char *data)
 Cleanup structures allocated by librasurecode_decode.
 
int liberasurecode_decode (int desc, char **available_fragments, int num_fragments, uint64_t fragment_len, int force_metadata_checks, char **out_data, uint64_t *out_data_len)
 Reconstruct original data from a set of k encoded fragments.
 
int liberasurecode_reconstruct_fragment (int desc, char **available_fragments, int num_fragments, uint64_t fragment_len, int destination_idx, char *out_fragment)
 Reconstruct a missing fragment from a subset of available fragments.
 
int liberasurecode_fragments_needed (int desc, int *fragments_to_reconstruct, int *fragments_to_exclude, int *fragments_needed)
 Return a list of lists with valid rebuild indexes given a list of missing indexes.
 
int liberasurecode_get_fragment_metadata (char *fragment, fragment_metadata_t *fragment_metadata)
 Get opaque metadata for a fragment.
 
int is_invalid_fragment_header (fragment_header_t *header)
 
int liberasurecode_verify_fragment_metadata (ec_backend_t be, fragment_metadata_t *md)
 
int is_invalid_fragment_metadata (int desc, fragment_metadata_t *fragment_metadata)
 
int is_invalid_fragment (int desc, char *fragment)
 
int liberasurecode_verify_stripe_metadata (int desc, char **fragments, int num_fragments)
 
int liberasurecode_get_aligned_data_size (int desc, uint64_t data_len)
 This computes the aligned size of a buffer passed into the encode function.
 
int liberasurecode_get_minimum_encode_size (int desc)
 This will return the minumum encode size, which is the minimum buffer size that can be encoded.
 
int liberasurecode_get_fragment_size (int desc, int data_len)
 
uint32_t liberasurecode_get_version ()
 This will return the liberasurecode version for the descriptor.
 

Variables

struct ec_backend_common backend_null
 
struct ec_backend_common backend_flat_xor_hd
 
struct ec_backend_common backend_jerasure_rs_vand
 
struct ec_backend_common backend_jerasure_rs_cauchy
 
struct ec_backend_common backend_isa_l_rs_vand
 
struct ec_backend_common backend_shss
 
struct ec_backend_common backend_liberasurecode_rs_vand
 
struct ec_backend_common backend_isa_l_rs_cauchy
 
struct ec_backend_common backend_libphazr
 
ec_backend_t ec_backends_supported []
 
int num_supported_backends = 0
 
char * ec_backends_supported_str [EC_BACKENDS_MAX]
 

Function Documentation

◆ __attribute__() [1/2]

void __attribute__ ( (constructor)  )

◆ __attribute__() [2/2]

void __attribute__ ( (destructor)  )

Definition at line 215 of file erasurecode.c.

References ec_backends_supported_str, and num_supported_backends.

◆ is_invalid_fragment()

int is_invalid_fragment ( int  desc,
char *  fragment 
)

◆ is_invalid_fragment_header()

int is_invalid_fragment_header ( fragment_header_t *  header)

◆ is_invalid_fragment_metadata()

int is_invalid_fragment_metadata ( int  desc,
fragment_metadata_t *  fragment_metadata 
)

◆ liberasurecode_backend_alloc_desc()

int liberasurecode_backend_alloc_desc ( void  )

Allocated backend instance descriptor.

Returns a unique descriptor for a new backend. The caller must hold active_instances_rwlock

Definition at line 105 of file erasurecode.c.

Referenced by liberasurecode_backend_instance_register().

◆ liberasurecode_backend_available()

int liberasurecode_backend_available ( const ec_backend_id_t  backend_id)

Checks if a given backend is available.

Parameters
backend_id- one of the supported backends.
Returns
1 if a backend is available; 0 otherwise

Definition at line 232 of file erasurecode.c.

References ec_backends_supported, liberasurecode_backend_close(), and liberasurecode_backend_open().

◆ liberasurecode_backend_close()

int liberasurecode_backend_close ( ec_backend_t  instance)

◆ liberasurecode_backend_instance_register()

int liberasurecode_backend_instance_register ( ec_backend_t  instance)

Register a backend instance with liberasurecode.

Parameters
instance- backend enum
Returns
new backend descriptor

Definition at line 122 of file erasurecode.c.

References liberasurecode_backend_alloc_desc().

Referenced by liberasurecode_instance_create().

◆ liberasurecode_backend_instance_unregister()

int liberasurecode_backend_instance_unregister ( ec_backend_t  instance)

Unregister a backend instance.

Returns
0 on success, non-0 on error

Definition at line 149 of file erasurecode.c.

Referenced by liberasurecode_instance_destroy().

◆ liberasurecode_backend_open()

void * liberasurecode_backend_open ( ec_backend_t  instance)

◆ liberasurecode_decode()

int liberasurecode_decode ( int  desc,
char **  available_fragments,
int  num_fragments,
uint64_t  fragment_len,
int  force_metadata_checks,
char **  out_data,
uint64_t *  out_data_len 
)

Reconstruct original data from a set of k encoded fragments.

Parameters
desc- liberasurecode descriptor/handle from liberasurecode_instance_create()
available_fragments- erasure encoded fragments (> = k)
num_fragments- number of fragments being passed in
fragment_len- length of each fragment (assume they are the same)
force_metadata_checks- force fragment metadata checks (default: 0)
out_data- output pointer to decoded data
out_data_len- output length of decoded output
Returns
0 on success, -error code otherwise

Definition at line 540 of file erasurecode.c.

References add_fragment_metadata(), alloc_and_set_buffer(), alloc_zeroed_buffer(), fragments_to_string(), get_data_ptr_array_from_fragments(), get_fragment_partition(), is_invalid_fragment(), is_invalid_fragment_header(), and prepare_fragments_for_decode().

◆ liberasurecode_decode_cleanup()

int liberasurecode_decode_cleanup ( int  desc,
char *  data 
)

Cleanup structures allocated by librasurecode_decode.

The caller has no context, so cannot safely free memory allocated by liberasurecode, so it must pass the deallocation responsibility back to liberasurecode.

Parameters
desc- liberasurecode descriptor/handle from liberasurecode_instance_create()
data- (char *) buffer of data decoded by librasurecode_decode
Returns
0 in success; -error otherwise

Definition at line 515 of file erasurecode.c.

◆ liberasurecode_encode()

int liberasurecode_encode ( int  desc,
const char *  orig_data,
uint64_t  orig_data_size,
char ***  encoded_data,
char ***  encoded_parity,
uint64_t *  fragment_len 
)

Erasure encode a data buffer.

Parameters
desc- liberasurecode descriptor/handle from liberasurecode_instance_create()
orig_data- data to encode
orig_data_size- length of data to encode
encoded_data- pointer to output array (char **) of k data fragments (char *), allocated by the callee
encoded_parity- pointer to output array (char **) of m parity fragments (char *), allocated by the callee
fragment_len- pointer to output length of each fragment, assuming all fragments are the same length
Returns
0 on success, -error code otherwise

Definition at line 413 of file erasurecode.c.

References alloc_zeroed_buffer(), finalize_fragments_after_encode(), get_fragment_ptr_array_from_data(), get_fragment_size(), liberasurecode_encode_cleanup(), and prepare_fragments_for_encode().

◆ liberasurecode_encode_cleanup()

int liberasurecode_encode_cleanup ( int  desc,
char **  encoded_data,
char **  encoded_parity 
)

Cleanup structures allocated by librasurecode_encode.

The caller has no context, so cannot safely free memory allocated by liberasurecode, so it must pass the deallocation responsibility back to liberasurecode.

Parameters
desc- liberasurecode descriptor/handle from liberasurecode_instance_create()
encoded_data- (char **) array of k data fragments (char *), allocated by liberasurecode_encode
encoded_parity- (char **) array of m parity fragments (char *), allocated by liberasurecode_encode
Returns
0 in success; -error otherwise

Definition at line 365 of file erasurecode.c.

Referenced by liberasurecode_encode().

◆ liberasurecode_fragments_needed()

int liberasurecode_fragments_needed ( int  desc,
int *  fragments_to_reconstruct,
int *  fragments_to_exclude,
int *  fragments_needed 
)

Return a list of lists with valid rebuild indexes given a list of missing indexes.

@desc: liberasurecode instance descriptor (obtained with liberasurecode_instance_create) @fragments_to_reconstruct list of indexes to reconstruct @fragments_to_exclude list of indexes to exclude from reconstruction equation @fragments_needed list of fragments needed to reconstruct fragments in fragments_to_reconstruct

Returns
a list of lists (bitmaps) of indexes to rebuild data from (in 'fragments_needed')

Definition at line 976 of file erasurecode.c.

◆ liberasurecode_get_aligned_data_size()

int liberasurecode_get_aligned_data_size ( int  desc,
uint64_t  data_len 
)

This computes the aligned size of a buffer passed into the encode function.

The encode function must pad fragments to be aligned with the word size (w) and the last fragment also needs to be aligned. This computes the sum of the aligned fragment sizes for a given buffer to encode.

Definition at line 1250 of file erasurecode.c.

Referenced by liberasurecode_get_minimum_encode_size().

◆ liberasurecode_get_fragment_metadata()

int liberasurecode_get_fragment_metadata ( char *  fragment,
fragment_metadata_t *  fragment_metadata 
)

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().

Parameters
fragment- fragment pointer
fragment_metadata- pointer to output fragment metadata struct (reference passed by the user)

Definition at line 1029 of file erasurecode.c.

References get_data_ptr_from_fragment(), is_invalid_fragment_header(), and liberasurecode_crc32_alt().

Referenced by is_invalid_fragment().

◆ liberasurecode_get_fragment_size()

int liberasurecode_get_fragment_size ( int  desc,
int  data_len 
)

Definition at line 1286 of file erasurecode.c.

References get_aligned_data_size().

◆ liberasurecode_get_minimum_encode_size()

int liberasurecode_get_minimum_encode_size ( int  desc)

This will return the minumum encode size, which is the minimum buffer size that can be encoded.

Definition at line 1281 of file erasurecode.c.

References liberasurecode_get_aligned_data_size().

◆ liberasurecode_get_version()

uint32_t liberasurecode_get_version ( )

This will return the liberasurecode version for the descriptor.

Definition at line 1307 of file erasurecode.c.

◆ liberasurecode_instance_create()

int liberasurecode_instance_create ( const ec_backend_id_t  id,
struct ec_args *  args 
)

Create a liberasurecode instance and return a descriptor for use with EC operations (encode, decode, reconstruct)

Parameters
id- one of the supported backends as defined by ec_backend_id_t
args- arguments to the EC backend arguments common to all backends k - number of data fragments m - number of parity fragments w - word size, in bits hd - hamming distance (=m for Reed-Solomon) ct - fragment checksum type (stored with the fragment metadata) backend-specific arguments null_args - arguments for the null backend flat_xor_hd, jerasure do not require any special args
Returns
liberasurecode instance descriptor (int > 0)

Definition at line 266 of file erasurecode.c.

References ec_backends_supported, liberasurecode_backend_instance_register(), liberasurecode_backend_open(), and print_dlerror().

◆ liberasurecode_instance_destroy()

int liberasurecode_instance_destroy ( int  desc)

Close a liberasurecode instance.

Parameters
desc- liberasurecode descriptor to close

Definition at line 326 of file erasurecode.c.

References liberasurecode_backend_close(), and liberasurecode_backend_instance_unregister().

◆ liberasurecode_reconstruct_fragment()

int liberasurecode_reconstruct_fragment ( int  desc,
char **  available_fragments,
int  num_fragments,
uint64_t  fragment_len,
int  destination_idx,
char *  out_fragment 
)

Reconstruct a missing fragment from a subset of available fragments.

Parameters
desc- liberasurecode descriptor/handle from liberasurecode_instance_create()
fragment_len- size in bytes of the fragments
available_fragments- erasure encoded fragments
num_fragments- number of fragments being passed in
destination_idx- missing idx to reconstruct
out_fragment- output of reconstruct
Returns
0 on success, -error code otherwise

Definition at line 770 of file erasurecode.c.

References add_fragment_metadata(), alloc_and_set_buffer(), alloc_zeroed_buffer(), get_data_ptr_array_from_fragments(), get_fragment_partition(), is_invalid_fragment_header(), and prepare_fragments_for_decode().

◆ liberasurecode_verify_fragment_metadata()

int liberasurecode_verify_fragment_metadata ( ec_backend_t  be,
fragment_metadata_t *  md 
)

Definition at line 1151 of file erasurecode.c.

Referenced by is_invalid_fragment_metadata().

◆ liberasurecode_verify_stripe_metadata()

int liberasurecode_verify_stripe_metadata ( int  desc,
char **  fragments,
int  num_fragments 
)

Definition at line 1216 of file erasurecode.c.

References is_invalid_fragment_metadata().

◆ print_dlerror()

static void print_dlerror ( const char *  caller)
static

Definition at line 167 of file erasurecode.c.

Referenced by liberasurecode_instance_create().

◆ SLIST_HEAD()

SLIST_HEAD ( backend_list  ,
ec_backend   
)

Look up a backend instance by descriptor.

Returns
pointer to a registered liberasurecode instance The caller must hold active_instances_rwlock

Definition at line 76 of file erasurecode.c.

Variable Documentation

◆ backend_flat_xor_hd

struct ec_backend_common backend_flat_xor_hd
extern

Definition at line 51 of file flat_xor_hd.c.

Referenced by flat_xor_is_compatible_with().

◆ backend_isa_l_rs_cauchy

struct ec_backend_common backend_isa_l_rs_cauchy
extern

Definition at line 49 of file isa_l_rs_cauchy.c.

Referenced by isa_l_rs_cauchy_is_compatible_with().

◆ backend_isa_l_rs_vand

struct ec_backend_common backend_isa_l_rs_vand
extern

Definition at line 48 of file isa_l_rs_vand.c.

Referenced by isa_l_rs_vand_is_compatible_with().

◆ backend_jerasure_rs_cauchy

struct ec_backend_common backend_jerasure_rs_cauchy
extern

Definition at line 51 of file jerasure_rs_cauchy.c.

Referenced by jerasure_rs_cauchy_is_compatible_with().

◆ backend_jerasure_rs_vand

struct ec_backend_common backend_jerasure_rs_vand
extern

Definition at line 51 of file jerasure_rs_vand.c.

Referenced by jerasure_rs_vand_is_compatible_with().

◆ backend_liberasurecode_rs_vand

struct ec_backend_common backend_liberasurecode_rs_vand
extern

Definition at line 49 of file liberasurecode_rs_vand.c.

Referenced by liberasurecode_rs_vand_is_compatible_with().

◆ backend_libphazr

struct ec_backend_common backend_libphazr
extern

Definition at line 50 of file libphazr.c.

Referenced by pio_is_compatible_with().

◆ backend_null

struct ec_backend_common backend_null
extern

Definition at line 231 of file null.c.

◆ backend_shss

struct ec_backend_common backend_shss
extern

Definition at line 43 of file shss.c.

Referenced by shss_is_compatible_with().

◆ ec_backends_supported

ec_backend_t ec_backends_supported[]
Initial value:
= {
(ec_backend_t) &backend_null,
(ec_backend_t) &backend_jerasure_rs_vand,
(ec_backend_t) &backend_jerasure_rs_cauchy,
(ec_backend_t) &backend_flat_xor_hd,
(ec_backend_t) &backend_isa_l_rs_vand,
(ec_backend_t) &backend_shss,
(ec_backend_t) &backend_isa_l_rs_cauchy,
(ec_backend_t) &backend_libphazr,
NULL,
}
struct ec_backend_common backend_flat_xor_hd
Definition flat_xor_hd.c:51
struct ec_backend_common backend_null
Definition null.c:231
struct ec_backend_common backend_shss
Definition shss.c:43
struct ec_backend_common backend_isa_l_rs_vand
struct ec_backend_common backend_liberasurecode_rs_vand
struct ec_backend_common backend_isa_l_rs_cauchy
struct ec_backend_common backend_libphazr
Definition libphazr.c:50
struct ec_backend_common backend_jerasure_rs_cauchy
struct ec_backend_common backend_jerasure_rs_vand

Definition at line 56 of file erasurecode.c.

Referenced by __attribute__(), liberasurecode_backend_available(), and liberasurecode_instance_create().

◆ ec_backends_supported_str

char* ec_backends_supported_str[EC_BACKENDS_MAX]

Definition at line 71 of file erasurecode.c.

Referenced by __attribute__(), and __attribute__().

◆ num_supported_backends

int num_supported_backends = 0

Definition at line 70 of file erasurecode.c.

Referenced by __attribute__(), and __attribute__().