[MN-dev] [mndiff]: r97 - trunk/noe/rs.h

[michael]

Author: michael
Date: Wed Oct 22 00:51:23 2008
New Revision: 97

Log:
doxy


Modified:
   trunk/noe/rs.h

Modified: trunk/noe/rs.h
==============================================================================
--- trunk/noe/rs.h	(original)
+++ trunk/noe/rs.h	Wed Oct 22 00:51:23 2008
@@ -17,6 +17,11 @@
  */
 
 /**
+ *
+ * @Note, EXT(init)() has to be called before using any functions from this file.
+ */
+
+/**
  * gets the syndroms.
  * @param src a 2^16 entry long polynom
  * @param syn the syndrom polynom will be stored here
@@ -25,22 +30,58 @@
 void EXT(getSyndrom)(GFF4Element *syn, GFF4Element *src, int order, int codeBits);
 
 /**
- *
- * @param codeBits log2(codeSize)
+ * Appends parity symbols to data to make the whole a Reed Solomon codeword.
+ * @param data The input data to encode and the output codeword
+ *        The length of the input data is (1<<codeBits) - parityCount for GF(fermat prime)
+ *        and (1<<codeBits) - parityCount - 1 for GF(2^n) based codes.
+ * @param parityCount The number of parity symbols
+ * @param parityLocator Some temporary space used by this function,
+ *        it should be at least parityCount+2 symbols long and its first symbol
+ *        should be set to 0 whenever parityCount changes.
+ * @param codeBits log2(codeSize), must be equal to n for GF(2^n) based codes currently,
+ *        this may change though.
  */
 void EXT(rsEncode)(GFF4Element *data, GFF4Element *parityLocator, int parityCount, int codeBits);
 
 /**
- *
- * @param codeBits log2(codeSize)
+ * Corrects some data using a Reed Solomon code.
+ * @param data The input codeword to correct and the corrected output codeword.
+ * @param parityCount The number of parity symbols
+ * @param erasedCount The number of erased symbols, that is symbols for which we know they
+ *        are damaged / damaged symbols with known locations.
+ * @param erased the indexes in the input codeword of erased symbols.
+ * @param erassureLocator Some temporary space used by this function,
+ *        it should be at least parityCount+2 symbols long and its first symbol
+ *        should be set to 0 whenever erased or erasedCount changes.
+ * @param codeBits log2(codeSize), must be equal to n for GF(2^n) based codes currently,
+ *        this may change though.
+ * @returns the number of corrected symbols or a negative value in case of a uncorrectable error.
  */
 int EXT(rsDecode)(GFF4Element *data, int *erased, GFF4Element *erassureLocator, int erasedCount, int parityCount, int codeBits);
 
 #if M==0
 
 /**
- *
- * @param codeBits log2(codeSize)
+ * Transforms (or inverse transforms) a Reed Solomon code based on GF(fermat prime) so that
+ * none of its parity symbols equals the largest symbol. Both the original and the transformed
+ * codes are normal RS codes.
+ * (Possibly) damaged codes should always be corrected through rsDecode() before using this
+ * function here!
+ * This function/transform needs a data symbol (at tLocation) that is not too large, that
+ * is for 50% or less parity than code the most significant bit at tLocation must be 0.
+ * @param data The input and output codeword.
+ * @param parityCount The number of parity symbols
+ * @param parityLocator Some temporary space used by this function,
+ *        it should be at least parityCount+2 symbols long and its first symbol
+ *        should be set to 0 whenever parityCount changes.
+ * @param tPoly Some temporary space used by this function,
+ *        it should be at least parityCount symbols long and its first symbol
+ *        should be set to 0 whenever parityCount or tLocation changes.
+ * @param tLocation
+ * @param codeBits log2(codeSize), must be equal to n for GF(2^n) based codes currently,
+ *        this may change though.
+ * @param encode 1 for the transform to avoid the largest symbols, 0 to reverse it.
+ * @returns 0 if success or a negative value in case of an error.
  */
 int EXT(rsTransform)(GFF4Element *data, GFF4Element *parityLocator, int parityCount, GFF4Element *tPoly, int tLocation, int encode, int codeBits);
 #endif