git.gag.com Git - debian/gnuradio/blob - gnuradio-core/src/lib/reed-solomon/rs.3

   1 .TH REED-SOLOMON 3
   2 .SH NAME
   3 init_rs_int, encode_rs_int, decode_rs_int, free_rs_int,
   4 init_rs_char, encode_rs_char, decode_rs_char, free_rs_char,
   5 encode_rs_8, decode_rs_8, encode_rs_ccsds, decode_rs_ccsds
   6 .SH SYNOPSIS
   7 .nf
   8 .ft B
   9 #include "rs.h"
  10
  11 void *init_rs_int(unsigned int symsize,unsigned int gfpoly,unsigned fcr,
  12 unsigned prim,unsigned int nroots);
  13 void encode_rs_int(void *rs,int *data,int *parity);
  14 int decode_rs_int(void *rs,int *data,int *eras_pos,int no_eras);
  15 void free_rs_int(void *rs);
  16
  17 void *init_rs_char(unsigned int symsize,unsigned int gfpoly,unsigned fcr,
  18 unsigned prim,unsigned int nroots);
  19 void encode_rs_char(void *rs,unsigned char *data,unsigned char *parity);
  20 int decode_rs_char(void *rs,unsigned char *data,int *eras_pos,int no_eras);
  21 void free_rs_char(void *rs);
  22
  23 void encode_rs_8(unsigned char *data,unsigned char  *parity);
  24 int decode_rs_8(unsigned char *data,int *eras_pos,int no_eras);
  25
  26 void encode_rs_ccsds(unsigned char *data,unsigned char  *parity);
  27 int decode_rs_ccsds(unsigned char *data,int *eras_pos,int no_eras);
  28
  29 unsigned char Taltab[256];
  30 unsigned char Tal1tab[256];
  31
  32 .fi
  33
  34 .SH DESCRIPTION
  35 These functions implement Reed-Solomon error control encoding and
  36 decoding. For optimal performance in a variety of applications, three
  37 sets of functions are supplied. To access these functions, add "-lrs"
  38 to your linker command line.
  39
  40 The functions with names ending in "_int" handle data in integer arrays,
  41 permitting arbitrarily large codewords limited only by machine
  42 resources.
  43
  44 The functions with names ending in "_char" take unsigned char arrays and can
  45 handle codes with symbols of 8 bits or less (i.e., with codewords of
  46 255 symbols or less).
  47
  48 \fBencode_rs_8\fR and \fBdecode_rs_8\fR implement a specific
  49 (255,223) code with 8-bit symbols specified by the CCSDS:
  50 a field generator of 1 + X + X^2 + X^7 + X^8 and a code
  51 generator with first consecutive root = 112 and a primitive element of
  52 11. These functions use the conventional
  53 polynomial form, \fBnot\fR the dual-basis specified in
  54 the CCSDS standard, to represent symbols.
  55
  56 For full CCSDS compatibility, \fBencode_rs_ccsds\fR and
  57 \fBdecode_rs_ccsds\fR are provided. These functions use two lookup
  58 tables, \fBTaltab\fR to convert from conventional to dual-basis, and
  59 \fBTal1tab\fR to perform the inverse mapping from dual-basis to
  60 conventional form, before and after calls to \fBencode_rs_8\fR
  61 and \fBdecode_rs_8\fR.
  62
  63 The _8 and _ccsds functions do not require initialization.
  64 To use the general purpose RS encoder or decoder (i.e.,
  65 the _char or _int versions), the user must first
  66 call \fBinit_rs_int\fR or \fBinit_rs_char\fR as appropriate. The
  67 arguments are as follows:
  68
  69 \fBsymsize\fR gives the symbol size in bits, up to 8 for \fBinit_rs_char\fR
  70 or 32 for \fBinit_rs_int\fR on a machine with 32-bit ints (though such a
  71 huge code would exhaust memory limits on a 32-bit machine). The resulting
  72 Reed-Solomon code word will have 2^\fBsymsize\fR - 1 symbols,
  73 each containing \fBsymsize\fR bits.
  74
  75 \fBgfpoly\fR gives the extended Galois field generator polynomial coefficients,
  76 with the 0th coefficient in the low order bit. The polynomial
  77 \fImust\fR be primitive; if not, the call will fail and NULL will be
  78 returned.
  79
  80 \fBfcr\fR gives, in index form, the first consecutive root of the
  81 Reed Solomon code generator polynomial.
  82
  83 \fBprim\fR gives, in index form, the primitive element in the Galois field
  84 used to generate the Reed Solomon code generator polynomial.
  85
  86 \fBnroots\fR gives the number of roots in the Reed Solomon code
  87 generator polynomial. This equals the number of parity symbols
  88 per code block.
  89
  90 The resulting Reed-Solomon code has parameters (N,K), where
  91 N = 2^\fBsymsize\fR-1 and K = N-\fBnroots\fR.
  92
  93 The \fBencode_rs_char\fR and \fBencode_rs_int\fR functions accept
  94 the pointer returned by \fBinit_rs_char\fR or
  95 \fBinit_rs_int\fR, respectively, to
  96 encode a block of data using the specified code.
  97 The input data array is expected to
  98 contain K symbols (of \fBsymsize\fR bits each, right justified
  99 in each char or int) and \fBnroots\fR parity symbols will be placed
 100 into the \fBparity\fR array, right justified.
 101
 102 The \fBdecode_rs_char\fR and \fBdecode_rs_int\fR functions correct
 103 the errors in a Reed-Solomon codeword up to the capability of the code.
 104 An optional list of "erased" symbol indices may be given in the \fBeras_pos\fR
 105 array to assist the decoder; this parameter may be NULL if no erasures
 106 are given. The number of erased symbols must be given in the \fBno_eras\fR
 107 parameter.
 108
 109 To maximize performance, the encode and decode functions perform no
 110 "sanity checking" of their inputs. Decoder failure may result if
 111 \fBeras_pos\fR contains duplicate entries, and both encoder and
 112 decoder will fail if an input symbol exceeds its allowable range.
 113 (Symbol range overflow cannot occur with the _8 or _ccsds functions,
 114 or with the _char functions when 8-bit symbols are specified.)
 115
 116 The decoder corrects the symbols "in place", returning the number
 117 of symbols in error. If the codeword is uncorrectable, -1 is returned
 118 and the data block is unchanged. If \fBeras_pos\fR is non-null, it is
 119 used to return a list of corrected symbol positions, in no particular
 120 order.  This means that the
 121 array passed through this parameter \fImust\fR have at least \fBnroots\fR
 122 elements to prevent a possible buffer overflow.
 123
 124 The \fBfree_rs_int\fR and \fBfree_rs_char\fR functions free the internal
 125 space allocated by the \fBinit_rs_int\fR and \fBinit_rs_char\fR functions,
 126 respecitively.
 127
 128 The functions \fBencode_rs_8\fR and \fBdecode_rs_8\fR do not have
 129 corresponding \fBinit\fR and \fBfree\fR, nor do they take the
 130 \fBrs\fR argument accepted by the other functions as their parameters
 131 are statically compiled. These functions implement a code
 132 equivalent to calling
 133
 134 \fBinit_rs_char\fR(8,0x187,112,11,32);
 135
 136 and using the resulting pointer with \fBencode_rs_char\fR and
 137 \fBdecode_rs_char\fR.
 138
 139 .SH RETURN VALUES
 140 \fBinit_rs_int\fR and \fBinit_rs_char\fR return a pointer to an internal
 141 control structure that must be passed to the corresponding encode, decode
 142 and free functions. These functions return NULL on error.
 143
 144 The decode functions return a count of corrected
 145 symbols, or -1 if the block was uncorrectible.
 146
 147 .SH AUTHOR
 148 Phil Karn, KA9Q (karn@ka9q.net), based heavily on earlier work by Robert
 149 Morelos-Zaragoza (rober@spectra.eng.hawaii.edu) and Hari Thirumoorthy
 150 (harit@spectra.eng.hawaii.edu).
 151
 152 .SH COPYRIGHT
 153 Copyright 2002, Phil Karn, KA9Q. May be used under the terms of the
 154 GNU General Public License (GPL).
 155
 156 .SH SEE ALSO
 157 CCSDS 101.0-B-5: Telemetry Channel Coding.
 158 http://www.ccsds.org/documents/pdf/CCSDS-101.0-B-5.pdf
 159
 160 .SH NOTE
 161 CCSDS chose the "dual basis" symbol representation because it
 162 simplified the implementation of a Reed-Solomon encoder in dedicated
 163 hardware. However, this approach holds no advantages for a software
 164 implementation on a general purpose computer, so use of the dual basis
 165 is recommended only if compatibility with the CCSDS standard is needed,
 166 e.g., to decode data from an existing spacecraft using the CCSDS
 167 standard. If you just want a fast (255,223) RS codec without needing
 168 to interoperate with a CCSDS standard code, use \fBencode_rs_8\fR
 169 and \fBdecode_rs_8\fR.
 170