# FreeBSD Manual Pages

REED-SOLOMON(3) Library Functions Manual REED-SOLOMON(3)NAMEinit_rs_int, encode_rs_int, decode_rs_int, free_rs_int, init_rs_char, encode_rs_char, decode_rs_char, free_rs_char, encode_rs_8, decode_rs_8, encode_rs_ccsds, decode_rs_ccsds - Reed-Solomon encoding/decodingSYNOPSIS#include"rs.h"void*init_rs_int(intsymsize,intgfpoly,intfcr,intprim,intnroots,intpad);voidencode_rs_int(void*rs,int*data,int*parity);intdecode_rs_int(void*rs,int*data,int*eras_pos,intno_eras);voidfree_rs_int(void*rs);void*init_rs_char(intsymsize,intgfpoly,intfcr,intprim,intnroots,intpad);voidencode_rs_char(void*rs,unsignedchar*data,unsignedchar*parity);intdecode_rs_char(void*rs,unsignedchar*data,int*eras_pos,intno_eras);voidfree_rs_char(void*rs);voidencode_rs_8(unsignedchar*data,unsignedchar*parity,intpad);intdecode_rs_8(unsignedchar*data,int*eras_pos,intno_eras,intpad);voidencode_rs_ccsds(unsignedchar*data,unsignedchar*parity,intpad);intdecode_rs_ccsds(unsignedchar*data,int*eras_pos,intno_eras,intpad);unsignedcharTaltab[256];unsignedcharTal1tab[256];DESCRIPTIONThese functions implement Reed-Solomon error control encoding and de- coding. For optimal performance in a variety of applications, three sets of functions are supplied. To access these functions, add "-lrs" to your linker command line. The functions with names ending in _inthandle data in integer arrays, permitting arbitrarily large codewords limited only by machine re- sources. The functions with names ending in _chartake unsigned char arrays and can handle codes with symbols of 8 bits or less (i.e., with codewords of 255 symbols or less).encode_rs_8anddecode_rs_8implement a specific (255,223) code with 8-bit symbols specified by the CCSDS: a field generator of 1 + X + X^2 + X^7 + X^8 and a code generator with first consecutive root = 112 and a primitive element of 11. These functions use the conventional polyno- mial form,notthe dual-basis specified in the CCSDS standard, to rep- resent symbols. This code may be shortened by giving a non-zeropadvalue to produce a (255-pad,223-pad) code. The padding will consist of the specified number of zeroes at the front of the full codeword. For full CCSDS compatibility,encode_rs_ccsdsanddecode_rs_ccsdsare provided. These functions use two lookup tables,Taltabto convert from conventional to dual-basis, andTal1tabto perform the inverse mapping from dual-basis to conventional form, before and after calls toen-code_rs_8anddecode_rs_8. The _8and _ccsdsfunctions do not require initialization. To use the general purpose RS encoder or decoder (i.e., the _charor _intversions), the user must first callinit_rs_intorinit_rs_charas appropriate. The arguments are as follows:symsizegives the symbol size in bits, up to 8 forinit_rs_charor 32 forinit_rs_inton a machine with 32-bit ints (though such a huge code would exhaust memory limits on a 32-bit machine). The resulting Reed- Solomon code word will have 2^symsize- 1 symbols, each containingsym-sizebits. The codeword may be shortened with thepadparameter de- scribed below.gfpolygives the extended Galois field generator polynomial coeffi- cients, with the 0th coefficient in the low order bit. The polynomialmustbe primitive; if not, the call will fail and NULL will be re- turned.fcrgives, in index form, the first consecutive root of the Reed Solomon code generator polynomial.primgives, in index form, the primitive element in the Galois field used to generate the Reed Solomon code generator polynomial.nrootsgives the number of roots in the Reed Solomon code generator polynomial. This equals the number of parity symbols per code block.padgives the number of leading symbols in the codeword that are im- plicitly padded to zero in a shortened code block. The resulting Reed-Solomon code has parameters (N,K), where N = 2^sym-size-pad- 1 and K = N-nroots. Theencode_rs_charandencode_rs_intfunctions accept the pointer re- turned byinit_rs_charorinit_rs_int, respectively, to encode a block of data using the specified code. The input data array is expected to contain K symbols (ofsymsizebits each, right justified in each char or int) andnrootsparity symbols will be placed into theparityarray, right justified. Thedecode_ functions correct the errors in a Reed-Solomon codeword of N symbols up to the capability of the code. An optional list of "erased" symbol indices may be given in theeras_posarray to assist the decoder; this parameter may be NULL if no erasures are given. The number of erased symbols must be given in theno_erasparameter. To maximize performance, the encode and decode functions perform no "sanity checking" of their inputs. Decoder failure may result iferas_poscontains duplicate entries, and both encoder and decoder will fail if an input symbol exceeds its allowable range. (Symbol range overflow cannot occur with the _8or _ccsdsfunctions, or with the _charfunctions when 8-bit symbols are specified.) The decoder corrects the symbols "in place", returning the number of symbols in error. If the codeword is uncorrectable, -1 is returned and the data block is unchanged. Iferas_posis non-null, it is used to re- turn a list of corrected symbol positions, in no particular order. This means that the array passed through this parametermusthave at leastnrootselements to prevent a possible buffer overflow. Thefree_rs_intandfree_rs_charfunctions free the internal space al- located by theinit_rs_intandinit_rs_charfunctions, respecitively. The functionsencode_rs_8anddecode_rs_8do not have correspondinginitandfree, nor do they take thersargument accepted by the other functions as their parameters are statically compiled. These functions implement a code equivalent to callinginit_rs_char(8,0x187,112,11,32,pad); and using the resulting pointer withencode_rs_charanddecode_rs_char.RETURN VALUESinit_rs_intandinit_rs_charreturn a pointer to an internal control structure that must be passed to the corresponding encode, decode and free functions. These functions return NULL on error. Thedecode_ functions return a count of corrected symbols, or -1 if the block was uncorrectible.AUTHORPhil Karn, KA9Q (karn@ka9q.net), based heavily on earlier work by Robert Morelos-Zaragoza (robert@spectra.eng.hawaii.edu) and Hari Thiru- moorthy (harit@spectra.eng.hawaii.edu). Extra improvements suggested by Detmar Welz (dwelz@web.de).COPYRIGHTCopyright 2002, Phil Karn, KA9Q. May be used under the terms of the GNU General Public License (GPL).SEE ALSOCCSDS 101.0-B-5: Telemetry Channel Coding. http://www.ccsds.org/docu- ments/pdf/CCSDS-101.0-B-5.pdfNOTECCSDS chose the "dual basis" symbol representation because it simpli- fied the implementation of a Reed-Solomon encoder in dedicated hard- ware. However, this approach holds no advantages for a software imple- mentation on a general purpose computer, so use of the dual basis is recommended only if compatibility with the CCSDS standard is needed, e.g., to decode data from an existing spacecraft using the CCSDS stan- dard. If you just want a fast (255,223) RS codec without needing to in- teroperate with a CCSDS standard code, useencode_rs_8anddecode_rs_8. REED-SOLOMON(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | AUTHOR | COPYRIGHT | SEE ALSO | NOTE

Want to link to this manual page? Use this URL:

<https://www.freebsd.org/cgi/man.cgi?query=rs&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>