Jerasure
1.2
A Library in C/C++ Facilitating Erasure Coding for Storage Applications
|
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