Commit 7a502868f1fb77faa6667f13b7cc1fb42acb1186

Authored by Jim Plank
1 parent b5ff7900
Exists in master and in 1 other branch v2

Needed .txt

Showing 1 changed file with 21 additions and 19 deletions   Show diff stats
README.txt
1 1 This is revision 2.0 of Jerasure. This is pretty much Jerasure 1.2 without the
2   -original Galois Field backend. Version 2.0 links directly to GF-Complete.
  2 +original Galois Field backend. Version 2.0 links directly to GF-Complete, which
  3 +is more flexible than the original, and *much* faster, because it leverages SIMD
  4 +instructions.
3 5  
4 6 External Documentation:
5 7  
... ... @@ -12,10 +14,9 @@ Custom usgae of GF-Complete is explained in this file (see below).
12 14  
13 15 NOTE: You must have GF-Complete installed in order to use Jerasure 2.0.
14 16  
15   -There are two directories:
  17 +There are two directories of source code:
16 18  
17 19 The src directory contains the jerasure code.
18   -
19 20 The Examples directory contains the example programs.
20 21  
21 22 The makefile assumes that Examples is a subdirectory of the home directory.
... ... @@ -33,7 +34,7 @@ Installing:
33 34 This will install the examples under PREFIX/bin, the library under PREFIX/lib
34 35 and the header files under PREFIX/include
35 36  
36   -See individual source file to determine what the examples do.
  37 +See individual source files to determine what the examples do.
37 38  
38 39 Inclusion of GF-Complete:
39 40  
... ... @@ -44,8 +45,8 @@ determine the default field to use, if one is not specified.
44 45 If you would like to explore a using a different Galois Field implementation,
45 46 you can dynamically set the backend GF for a given word-size (w).
46 47  
47   -The new galois.[ch] exports the following functions to be used by applications
48   -for dynamically setting the backend GF:
  48 +The new galois.c and galois.h export the following functions to be used by applications
  49 +for dynamically setting the back-end GF:
49 50  
50 51 1.) galois_change_technique
51 52  
... ... @@ -53,21 +54,25 @@ for dynamically setting the backend GF:
53 54  
54 55 void galois_change_technique(gf_t *gf, int w);
55 56  
  57 + This is the recommended way for you to change techniques.
  58 +
56 59 This function will take a pointer to a Galois field structure and set it as the
57 60 current backend for all operations in GF(2^w). Note that you must specify 'w'
58 61 here, since the internal GF structure is mostly opaque to Jerasure. Be sure to
59 62 change the technique with the correct structure and word-size.
60 63  
61   - There are a few ways to get a pointer to a gf_t structure: via GF-Complete or
62   - using the helper functions provided by Jerasure: galois_init_field and
63   - galois_init_composite_field.
  64 + There are a few ways to get a pointer to a gf_t structure: GF-Complete gives three
  65 + primitives for this -- create_gf_from_argv(), gf_init_easy() and gf_init_hard().
  66 + Please read the documentation on GF-Complete for how these work. By far, the
  67 + most powerful and easy is create_gf_from_argv(), which parses an argv-style
  68 + string. Otherwise, the most flexible is gf_init_hard().
  69 +
  70 + In galois.c/galois.h, we have defined galois_init_field(), which is pretty much
  71 + identical to gf_init_hard(), except it performs memory allocation with malloc(),
  72 + and galois_init_composite_field(), which facilitates creating composite fields.
64 73  
65   - GF-Complete exposes create_gf_from_argv, gf_init_easy and gf_init_hard. See
66   - the GF-Complete documentation for more detail on how to use those functions.
67   - You can definitely create more complicated fields with the GF-Complete
68   - initialization functions, but the two helper functions provided by Jerasure
69   - (galois_init_field and galois_init_composite_field) can be used to create most
70   - of the supported Galois Fields.
  74 + These are described below, but once again, we recommend using create_gf_from_argv()
  75 + or gf_init_hard() if you want to change your Galois field.
71 76  
72 77 2.) galois_init_field
73 78  
... ... @@ -149,10 +154,6 @@ For more information on how to change the backing fields for Jerasure, please re
149 154 2.) Examples/reed_sol_time_gf.c: Runs more thorough timing and validation tests
150 155 for a backing GF (uses create_gf_from_argv to get gf_t pointer)
151 156  
152   - 3.) Examples/reed_sol_hard_time_gf.c: Runs more thorough timing and validation tests
153   - for a backing GF (uses galois_init_field and galois_init_composite_field to get gf_t
154   - pointer)
155   -
156 157 Performance:
157 158  
158 159 There are two performance-based test scripts: time_all_gfs_argv_init.sh and
... ... @@ -174,3 +175,4 @@ the test run of
174 175 is recorded as this in PERF.txt:
175 176  
176 177 _12_3_8_128_65536_-m_SPLIT_8_4_-r_SSE_- 2813.34
  178 +
... ...