Jerasure  1.2
A Library in C/C++ Facilitating Erasure Coding for Storage Applications
jerasure.h
Go to the documentation of this file.
00001 /* jerasure.h - header of kernel procedures
00002  * James S. Plank
00003 
00004 Jerasure - A C/C++ Library for a Variety of Reed-Solomon and RAID-6 Erasure Coding Techniques
00005 
00006 Revision 1.2A
00007 May 24, 2011
00008 
00009 James S. Plank
00010 Department of Electrical Engineering and Computer Science
00011 University of Tennessee
00012 Knoxville, TN 37996
00013 plank@cs.utk.edu
00014 
00015 Copyright (c) 2011, James S. Plank
00016 All rights reserved.
00017 
00018 Redistribution and use in source and binary forms, with or without
00019 modification, are permitted provided that the following conditions
00020 are met:
00021 
00022  - Redistributions of source code must retain the above copyright
00023    notice, this list of conditions and the following disclaimer.
00024 
00025  - Redistributions in binary form must reproduce the above copyright
00026    notice, this list of conditions and the following disclaimer in
00027    the documentation and/or other materials provided with the
00028    distribution.
00029 
00030  - Neither the name of the University of Tennessee nor the names of its
00031    contributors may be used to endorse or promote products derived
00032    from this software without specific prior written permission.
00033 
00034 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
00035 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
00036 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
00037 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
00038 HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
00039 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
00040 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
00041 OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
00042 AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00043 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
00044 WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00045 POSSIBILITY OF SUCH DAMAGE.
00046 
00047  */
00048 
00049 #ifndef _JERASURE_H
00050 #define _JERASURE_H
00051 
00052 /* This uses procedures from the Galois Field arithmetic library */
00053 
00054 #include "galois.h"
00055 
00056 /* ------------------------------------------------------------ */
00057 /* In all of the routines below:
00058 
00059    operation = an array of 5 integers:
00060 
00061           0 = operation: 0 for copy, 1 for xor (-1 for end)
00062           1 = source device (0 - k+m-1)
00063           2 = source packet (0 - w-1)
00064           3 = destination device (0 - k+m-1)
00065           4 = destination packet (0 - w-1)
00066  */
00067 
00068 /* ---------------------------------------------------------------  */
00069 /* Bitmatrices / schedules ---------------------------------------- */
00070 
00083 int *jerasure_matrix_to_bitmatrix(int k, int m, int w, int *matrix);
00084 
00096 int **jerasure_dumb_bitmatrix_to_schedule(int k, int m, int w, int *bitmatrix);
00097 
00109 int **jerasure_smart_bitmatrix_to_schedule(int k, int m, int w, int *bitmatrix);
00110 
00121 int ***jerasure_generate_schedule_cache(int k, int m, int w, int *bitmatrix, int smart);
00122 
00129 void jerasure_free_schedule(int **schedule);
00130 
00139 void jerasure_free_schedule_cache(int k, int m, int ***cache);
00140 
00141 
00142 /* ------------------------------------------------------------ */
00143 /* Encoding - these are all straightforward.  jerasure_matrix_encode only 
00144    works with w = 8|16|32.  */
00145 
00153 void jerasure_do_parity(int k, char **data_ptrs, char *parity_ptr, int size);
00154 
00166 void jerasure_matrix_encode(int k, int m, int w, int *matrix,
00167                           char **data_ptrs, char **coding_ptrs, int size);
00168 
00181 void jerasure_bitmatrix_encode(int k, int m, int w, int *bitmatrix,
00182                             char **data_ptrs, char **coding_ptrs, int size, int packetsize);
00183 
00197 void jerasure_schedule_encode(int k, int m, int w, int **schedule,
00198                                   char **data_ptrs, char **coding_ptrs, int size, int packetsize);
00199 
00200 /* ------------------------------------------------------------ */
00201 /* Decoding. -------------------------------------------------- */
00202 
00203 /* These return integers, because the matrix may not be invertible. 
00204    
00205    The parameter row_k_ones should be set to 1 if row k of the matrix
00206    (or rows kw to (k+1)w+1) of th distribution matrix are all ones
00207    (or all identity matrices).  Then you can improve the performance
00208    of decoding when there is more than one failure, and the parity
00209    device didn't fail.  You do it by decoding all but one of the data
00210    devices, and then decoding the last data device from the data devices
00211    and the parity device.
00212 
00213  */
00214 
00230 int jerasure_matrix_decode(int k, int m, int w, 
00231                           int *matrix, int row_k_ones, int *erasures,
00232                           char **data_ptrs, char **coding_ptrs, int size);
00233 
00252 int jerasure_bitmatrix_decode(int k, int m, int w, 
00253                             int *bitmatrix, int row_k_ones, int *erasures,
00254                             char **data_ptrs, char **coding_ptrs, int size, int packetsize);
00255 
00271 int jerasure_schedule_decode_lazy(int k, int m, int w, int *bitmatrix, int *erasures,
00272                             char **data_ptrs, char **coding_ptrs, int size, int packetsize,
00273                             int smart);
00287 int jerasure_schedule_decode_cache(int k, int m, int w, int ***scache, int *erasures,
00288                             char **data_ptrs, char **coding_ptrs, int size, int packetsize);
00289 
00298 int jerasure_make_decoding_matrix(int k, int m, int w, int *matrix, int *erased, 
00299                                   int *decoding_matrix, int *dm_ids);
00300 
00309 int jerasure_make_decoding_bitmatrix(int k, int m, int w, int *matrix, int *erased, 
00310                                   int *decoding_matrix, int *dm_ids);
00311 
00319 int *jerasure_erasures_to_erased(int k, int m, int *erasures);
00320 
00321 /* ------------------------------------------------------------ */
00322 /* These perform dot products and schedules. -------------------*/
00323 /*
00324    src_ids is a matrix of k id's (0 - k-1 for data devices, k - k+m-1
00325    for coding devices) that identify the source devices.  Dest_id is
00326    the id of the destination device.
00327 
00328    jerasure_do_scheduled_operations executes the schedule on w*packetsize worth of
00329    bytes from each device.  ptrs is an array of pointers which should have as many
00330    elements as the highest referenced device in the schedule.
00331 
00332  */
00333  
00343 void jerasure_matrix_dotprod(int k, int w, int *matrix_row,
00344                           int *src_ids, int dest_id,
00345                           char **data_ptrs, char **coding_ptrs, int size);
00346 
00358 void jerasure_bitmatrix_dotprod(int k, int w, int *bitmatrix_row,
00359                              int *src_ids, int dest_id,
00360                              char **data_ptrs, char **coding_ptrs, int size, int packetsize);
00361 
00368 void jerasure_do_scheduled_operations(char **ptrs, int **schedule, int packetsize);
00369 
00370 /* ------------------------------------------------------------ */
00371 /* Matrix Inversion ------------------------------------------- */
00372 /*
00373    The two matrix inversion functions work on rows*rows matrices of
00374    ints.  If a bitmatrix, then each int will just be zero or one.
00375    Otherwise, they will be elements of gf(2^w).  Obviously, you can
00376    do bit matrices with crs_invert_matrix() and set w = 1, but
00377    crs_invert_bitmatrix will be more efficient.
00378 
00379    The two invertible functions return whether a matrix is invertible.
00380    They are more efficient than the inverstion functions.
00381 
00382    Mat will be destroyed when the matrix inversion or invertible
00383    testing is done.  Sorry.
00384 
00385    Inv must be allocated by the caller.
00386 
00387    The two invert_matrix functions return 0 on success, and -1 if the
00388    matrix is uninvertible.
00389 
00390    The two invertible function simply return whether the matrix is
00391    invertible.  (0 or 1). Mat will be destroyed.
00392  */
00393 
00401 int jerasure_invert_matrix(int *mat, int *inv, int rows, int w);
00402 
00408 int jerasure_invert_bitmatrix(int *mat, int *inv, int rows);
00409 
00416 int jerasure_invertible_matrix(int *mat, int rows, int w);
00417 
00423 int jerasure_invertible_bitmatrix(int *mat, int rows);
00424 
00425 /* ------------------------------------------------------------ */
00426 /* Basic matrix operations -------------------------------------*/
00427 /*
00428    Each of the print_matrix routines require a w.  In jerasure_print_matrix,
00429    this is to calculate the field width.  In jerasure_print_bitmatrix, it is
00430    to put spaces between the bits.
00431 
00432    jerasure_matrix_multiply is a simple matrix multiplier in GF(2^w).  It returns a r1*c2
00433    matrix, which is the product of the two input matrices.  It allocates
00434    the product.  Obviously, c1 should equal r2.  However, this is not
00435    validated by the procedure.  
00436 */
00437 
00444 void jerasure_print_matrix(int *matrix, int rows, int cols, int w);
00445 
00452 void jerasure_print_bitmatrix(int *matrix, int rows, int cols, int w);
00453 
00460 int *jerasure_matrix_multiply(int *m1, int *m2, int r1, int c1, int r2, int c2, int w);
00461 
00462 /* ------------------------------------------------------------ */
00463 /* Stats ------------------------------------------------------ */
00464 
00471 void jerasure_get_stats(double *fill_in);
00472 
00473 #endif
 All Files Functions Variables Defines