1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
4
5<book id="Reed-Solomon-Library-Guide">
6 <bookinfo>
7  <title>Reed-Solomon Library Programming Interface</title>
8  
9  <authorgroup>
10   <author>
11    <firstname>Thomas</firstname>
12    <surname>Gleixner</surname>
13    <affiliation>
14     <address>
15      <email>tglx@linutronix.de</email>
16     </address>
17    </affiliation>
18   </author>
19  </authorgroup>
20
21  <copyright>
22   <year>2004</year>
23   <holder>Thomas Gleixner</holder>
24  </copyright>
25
26  <legalnotice>
27   <para>
28     This documentation is free software; you can redistribute
29     it and/or modify it under the terms of the GNU General Public
30     License version 2 as published by the Free Software Foundation.
31   </para>
32      
33   <para>
34     This program is distributed in the hope that it will be
35     useful, but WITHOUT ANY WARRANTY; without even the implied
36     warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
37     See the GNU General Public License for more details.
38   </para>
39      
40   <para>
41     You should have received a copy of the GNU General Public
42     License along with this program; if not, write to the Free
43     Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
44     MA 02111-1307 USA
45   </para>
46      
47   <para>
48     For more details see the file COPYING in the source
49     distribution of Linux.
50   </para>
51  </legalnotice>
52 </bookinfo>
53
54<toc></toc>
55
56  <chapter id="intro">
57      <title>Introduction</title>
58  <para>
59  	The generic Reed-Solomon Library provides encoding, decoding
60	and error correction functions.
61  </para>
62  <para>
63  	Reed-Solomon codes are used in communication and storage
64	applications to ensure data integrity. 
65  </para>
66  <para>
67  	This documentation is provided for developers who want to utilize
68	the functions provided by the library.
69  </para>
70  </chapter>
71  
72  <chapter id="bugs">
73     <title>Known Bugs And Assumptions</title>
74  <para>
75	None.	
76  </para>
77  </chapter>
78
79  <chapter id="usage">
80     	<title>Usage</title>
81	<para>
82		This chapter provides examples of how to use the library.
83	</para>
84	<sect1>
85		<title>Initializing</title>
86		<para>
87			The init function init_rs returns a pointer to an
88			rs decoder structure, which holds the necessary
89			information for encoding, decoding and error correction
90			with the given polynomial. It either uses an existing
91			matching decoder or creates a new one. On creation all
92			the lookup tables for fast en/decoding are created.
93			The function may take a while, so make sure not to 
94			call it in critical code paths.
95		</para>
96		<programlisting>
97/* the Reed Solomon control structure */
98static struct rs_control *rs_decoder;
99
100/* Symbolsize is 10 (bits)
101 * Primitive polynomial is x^10+x^3+1
102 * first consecutive root is 0
103 * primitive element to generate roots = 1
104 * generator polynomial degree (number of roots) = 6
105 */
106rs_decoder = init_rs (10, 0x409, 0, 1, 6);
107		</programlisting>
108	</sect1>
109	<sect1>
110		<title>Encoding</title>
111		<para>
112			The encoder calculates the Reed-Solomon code over
113			the given data length and stores the result in 
114			the parity buffer. Note that the parity buffer must
115			be initialized before calling the encoder.
116		</para>
117		<para>
118			The expanded data can be inverted on the fly by
119			providing a non-zero inversion mask. The expanded data is
120			XOR'ed with the mask. This is used e.g. for FLASH
121			ECC, where the all 0xFF is inverted to an all 0x00.
122			The Reed-Solomon code for all 0x00 is all 0x00. The
123			code is inverted before storing to FLASH so it is 0xFF
124			too. This prevents that reading from an erased FLASH
125			results in ECC errors.
126		</para>
127		<para>
128			The databytes are expanded to the given symbol size
129			on the fly. There is no support for encoding continuous
130			bitstreams with a symbol size != 8 at the moment. If
131			it is necessary it should be not a big deal to implement
132			such functionality.
133		</para>
134		<programlisting>
135/* Parity buffer. Size = number of roots */
136uint16_t par[6];
137/* Initialize the parity buffer */
138memset(par, 0, sizeof(par));
139/* Encode 512 byte in data8. Store parity in buffer par */
140encode_rs8 (rs_decoder, data8, 512, par, 0);
141		</programlisting>
142	</sect1>
143	<sect1>
144		<title>Decoding</title>
145		<para>
146			The decoder calculates the syndrome over
147			the given data length and the received parity symbols
148			and corrects errors in the data.
149		</para>
150		<para>
151			If a syndrome is available from a hardware decoder
152			then the syndrome calculation is skipped.
153		</para>
154		<para>
155			The correction of the data buffer can be suppressed
156			by providing a correction pattern buffer and an error
157			location buffer to the decoder. The decoder stores the
158			calculated error location and the correction bitmask
159			in the given buffers. This is useful for hardware
160			decoders which use a weird bit ordering scheme.
161		</para>
162		<para>
163			The databytes are expanded to the given symbol size
164			on the fly. There is no support for decoding continuous
165			bitstreams with a symbolsize != 8 at the moment. If
166			it is necessary it should be not a big deal to implement
167			such functionality.
168		</para>
169		
170		<sect2>
171		<title>
172			Decoding with syndrome calculation, direct data correction
173		</title>
174		<programlisting>
175/* Parity buffer. Size = number of roots */
176uint16_t par[6];
177uint8_t  data[512];
178int numerr;
179/* Receive data */
180.....
181/* Receive parity */
182.....
183/* Decode 512 byte in data8.*/
184numerr = decode_rs8 (rs_decoder, data8, par, 512, NULL, 0, NULL, 0, NULL);
185		</programlisting>
186		</sect2>
187
188		<sect2>
189		<title>
190			Decoding with syndrome given by hardware decoder, direct data correction
191		</title>
192		<programlisting>
193/* Parity buffer. Size = number of roots */
194uint16_t par[6], syn[6];
195uint8_t  data[512];
196int numerr;
197/* Receive data */
198.....
199/* Receive parity */
200.....
201/* Get syndrome from hardware decoder */
202.....
203/* Decode 512 byte in data8.*/
204numerr = decode_rs8 (rs_decoder, data8, par, 512, syn, 0, NULL, 0, NULL);
205		</programlisting>
206		</sect2>
207
208		<sect2>
209		<title>
210			Decoding with syndrome given by hardware decoder, no direct data correction.
211		</title>
212		<para>
213			Note: It's not necessary to give data and received parity to the decoder.
214		</para>
215		<programlisting>
216/* Parity buffer. Size = number of roots */
217uint16_t par[6], syn[6], corr[8];
218uint8_t  data[512];
219int numerr, errpos[8];
220/* Receive data */
221.....
222/* Receive parity */
223.....
224/* Get syndrome from hardware decoder */
225.....
226/* Decode 512 byte in data8.*/
227numerr = decode_rs8 (rs_decoder, NULL, NULL, 512, syn, 0, errpos, 0, corr);
228for (i = 0; i &lt; numerr; i++) {
229	do_error_correction_in_your_buffer(errpos[i], corr[i]);
230}
231		</programlisting>
232		</sect2>
233	</sect1>
234	<sect1>
235		<title>Cleanup</title>
236		<para>
237			The function free_rs frees the allocated resources,
238			if the caller is the last user of the decoder.
239		</para>
240		<programlisting>
241/* Release resources */
242free_rs(rs_decoder);
243		</programlisting>
244	</sect1>
245
246  </chapter>
247	
248  <chapter id="structs">
249     <title>Structures</title>
250     <para>
251     This chapter contains the autogenerated documentation of the structures which are
252     used in the Reed-Solomon Library and are relevant for a developer.
253     </para>
254<!-- include/linux/rslib.h -->
255<refentry id="API-struct-rs-control">
256<refentryinfo>
257 <title>LINUX</title>
258 <productname>Kernel Hackers Manual</productname>
259 <date>July 2017</date>
260</refentryinfo>
261<refmeta>
262 <refentrytitle><phrase>struct rs_control</phrase></refentrytitle>
263 <manvolnum>9</manvolnum>
264 <refmiscinfo class="version">4.1.27</refmiscinfo>
265</refmeta>
266<refnamediv>
267 <refname>struct rs_control</refname>
268 <refpurpose>
269  rs control structure
270 </refpurpose>
271</refnamediv>
272<refsynopsisdiv>
273 <title>Synopsis</title>
274  <programlisting>
275struct rs_control {
276  int mm;
277  int nn;
278  uint16_t * alpha_to;
279  uint16_t * index_of;
280  uint16_t * genpoly;
281  int nroots;
282  int fcr;
283  int prim;
284  int iprim;
285  int gfpoly;
286  int (* gffunc) (int);
287  int users;
288  struct list_head list;
289};  </programlisting>
290</refsynopsisdiv>
291 <refsect1>
292  <title>Members</title>
293  <variablelist>
294    <varlistentry>      <term>mm</term>
295      <listitem><para>
296Bits per symbol
297      </para></listitem>
298    </varlistentry>
299    <varlistentry>      <term>nn</term>
300      <listitem><para>
301Symbols per block (= (1&lt;&lt;mm)-1)
302      </para></listitem>
303    </varlistentry>
304    <varlistentry>      <term>alpha_to</term>
305      <listitem><para>
306log lookup table
307      </para></listitem>
308    </varlistentry>
309    <varlistentry>      <term>index_of</term>
310      <listitem><para>
311Antilog lookup table
312      </para></listitem>
313    </varlistentry>
314    <varlistentry>      <term>genpoly</term>
315      <listitem><para>
316Generator polynomial
317      </para></listitem>
318    </varlistentry>
319    <varlistentry>      <term>nroots</term>
320      <listitem><para>
321Number of generator roots = number of parity symbols
322      </para></listitem>
323    </varlistentry>
324    <varlistentry>      <term>fcr</term>
325      <listitem><para>
326First consecutive root, index form
327      </para></listitem>
328    </varlistentry>
329    <varlistentry>      <term>prim</term>
330      <listitem><para>
331Primitive element, index form
332      </para></listitem>
333    </varlistentry>
334    <varlistentry>      <term>iprim</term>
335      <listitem><para>
336prim-th root of 1, index form
337      </para></listitem>
338    </varlistentry>
339    <varlistentry>      <term>gfpoly</term>
340      <listitem><para>
341The primitive generator polynominal
342      </para></listitem>
343    </varlistentry>
344    <varlistentry>      <term>gffunc</term>
345      <listitem><para>
346Function to generate the field, if non-canonical representation
347      </para></listitem>
348    </varlistentry>
349    <varlistentry>      <term>users</term>
350      <listitem><para>
351Users of this structure
352      </para></listitem>
353    </varlistentry>
354    <varlistentry>      <term>list</term>
355      <listitem><para>
356List entry for the rs control list
357      </para></listitem>
358    </varlistentry>
359  </variablelist>
360 </refsect1>
361</refentry>
362
363  </chapter>
364
365  <chapter id="pubfunctions">
366     <title>Public Functions Provided</title>
367     <para>
368     This chapter contains the autogenerated documentation of the Reed-Solomon functions
369     which are exported.
370     </para>
371<!-- lib/reed_solomon/reed_solomon.c -->
372<refentry id="API-free-rs">
373<refentryinfo>
374 <title>LINUX</title>
375 <productname>Kernel Hackers Manual</productname>
376 <date>July 2017</date>
377</refentryinfo>
378<refmeta>
379 <refentrytitle><phrase>free_rs</phrase></refentrytitle>
380 <manvolnum>9</manvolnum>
381 <refmiscinfo class="version">4.1.27</refmiscinfo>
382</refmeta>
383<refnamediv>
384 <refname>free_rs</refname>
385 <refpurpose>
386  Free the rs control structure, if it is no longer used
387 </refpurpose>
388</refnamediv>
389<refsynopsisdiv>
390 <title>Synopsis</title>
391  <funcsynopsis><funcprototype>
392   <funcdef>void <function>free_rs </function></funcdef>
393   <paramdef>struct rs_control * <parameter>rs</parameter></paramdef>
394  </funcprototype></funcsynopsis>
395</refsynopsisdiv>
396<refsect1>
397 <title>Arguments</title>
398 <variablelist>
399  <varlistentry>
400   <term><parameter>rs</parameter></term>
401   <listitem>
402    <para>
403     the control structure which is not longer used by the
404     caller
405    </para>
406   </listitem>
407  </varlistentry>
408 </variablelist>
409</refsect1>
410</refentry>
411
412<refentry id="API-init-rs">
413<refentryinfo>
414 <title>LINUX</title>
415 <productname>Kernel Hackers Manual</productname>
416 <date>July 2017</date>
417</refentryinfo>
418<refmeta>
419 <refentrytitle><phrase>init_rs</phrase></refentrytitle>
420 <manvolnum>9</manvolnum>
421 <refmiscinfo class="version">4.1.27</refmiscinfo>
422</refmeta>
423<refnamediv>
424 <refname>init_rs</refname>
425 <refpurpose>
426     Find a matching or allocate a new rs control structure
427 </refpurpose>
428</refnamediv>
429<refsynopsisdiv>
430 <title>Synopsis</title>
431  <funcsynopsis><funcprototype>
432   <funcdef>struct rs_control * <function>init_rs </function></funcdef>
433   <paramdef>int <parameter>symsize</parameter></paramdef>
434   <paramdef>int <parameter>gfpoly</parameter></paramdef>
435   <paramdef>int <parameter>fcr</parameter></paramdef>
436   <paramdef>int <parameter>prim</parameter></paramdef>
437   <paramdef>int <parameter>nroots</parameter></paramdef>
438  </funcprototype></funcsynopsis>
439</refsynopsisdiv>
440<refsect1>
441 <title>Arguments</title>
442 <variablelist>
443  <varlistentry>
444   <term><parameter>symsize</parameter></term>
445   <listitem>
446    <para>
447     the symbol size (number of bits)
448    </para>
449   </listitem>
450  </varlistentry>
451  <varlistentry>
452   <term><parameter>gfpoly</parameter></term>
453   <listitem>
454    <para>
455     the extended Galois field generator polynomial coefficients,
456     with the 0th coefficient in the low order bit. The polynomial
457     must be primitive;
458    </para>
459   </listitem>
460  </varlistentry>
461  <varlistentry>
462   <term><parameter>fcr</parameter></term>
463   <listitem>
464    <para>
465     the first consecutive root of the rs code generator polynomial
466     in index form
467    </para>
468   </listitem>
469  </varlistentry>
470  <varlistentry>
471   <term><parameter>prim</parameter></term>
472   <listitem>
473    <para>
474     primitive element to generate polynomial roots
475    </para>
476   </listitem>
477  </varlistentry>
478  <varlistentry>
479   <term><parameter>nroots</parameter></term>
480   <listitem>
481    <para>
482     RS code generator polynomial degree (number of roots)
483    </para>
484   </listitem>
485  </varlistentry>
486 </variablelist>
487</refsect1>
488</refentry>
489
490<refentry id="API-init-rs-non-canonical">
491<refentryinfo>
492 <title>LINUX</title>
493 <productname>Kernel Hackers Manual</productname>
494 <date>July 2017</date>
495</refentryinfo>
496<refmeta>
497 <refentrytitle><phrase>init_rs_non_canonical</phrase></refentrytitle>
498 <manvolnum>9</manvolnum>
499 <refmiscinfo class="version">4.1.27</refmiscinfo>
500</refmeta>
501<refnamediv>
502 <refname>init_rs_non_canonical</refname>
503 <refpurpose>
504     Find a matching or allocate a new rs control structure, for fields with non-canonical representation
505 </refpurpose>
506</refnamediv>
507<refsynopsisdiv>
508 <title>Synopsis</title>
509  <funcsynopsis><funcprototype>
510   <funcdef>struct rs_control * <function>init_rs_non_canonical </function></funcdef>
511   <paramdef>int <parameter>symsize</parameter></paramdef>
512   <paramdef>int (*<parameter>gffunc</parameter>)
513     <funcparams>int</funcparams></paramdef>
514   <paramdef>int <parameter>fcr</parameter></paramdef>
515   <paramdef>int <parameter>prim</parameter></paramdef>
516   <paramdef>int <parameter>nroots</parameter></paramdef>
517  </funcprototype></funcsynopsis>
518</refsynopsisdiv>
519<refsect1>
520 <title>Arguments</title>
521 <variablelist>
522  <varlistentry>
523   <term><parameter>symsize</parameter></term>
524   <listitem>
525    <para>
526     the symbol size (number of bits)
527    </para>
528   </listitem>
529  </varlistentry>
530  <varlistentry>
531   <term><parameter>gffunc</parameter></term>
532   <listitem>
533    <para>
534     pointer to function to generate the next field element,
535     or the multiplicative identity element if given 0.  Used
536     instead of gfpoly if gfpoly is 0
537    </para>
538   </listitem>
539  </varlistentry>
540  <varlistentry>
541   <term><parameter>fcr</parameter></term>
542   <listitem>
543    <para>
544     the first consecutive root of the rs code generator polynomial
545     in index form
546    </para>
547   </listitem>
548  </varlistentry>
549  <varlistentry>
550   <term><parameter>prim</parameter></term>
551   <listitem>
552    <para>
553     primitive element to generate polynomial roots
554    </para>
555   </listitem>
556  </varlistentry>
557  <varlistentry>
558   <term><parameter>nroots</parameter></term>
559   <listitem>
560    <para>
561     RS code generator polynomial degree (number of roots)
562    </para>
563   </listitem>
564  </varlistentry>
565 </variablelist>
566</refsect1>
567</refentry>
568
569<refentry id="API-encode-rs8">
570<refentryinfo>
571 <title>LINUX</title>
572 <productname>Kernel Hackers Manual</productname>
573 <date>July 2017</date>
574</refentryinfo>
575<refmeta>
576 <refentrytitle><phrase>encode_rs8</phrase></refentrytitle>
577 <manvolnum>9</manvolnum>
578 <refmiscinfo class="version">4.1.27</refmiscinfo>
579</refmeta>
580<refnamediv>
581 <refname>encode_rs8</refname>
582 <refpurpose>
583     Calculate the parity for data values (8bit data width)
584 </refpurpose>
585</refnamediv>
586<refsynopsisdiv>
587 <title>Synopsis</title>
588  <funcsynopsis><funcprototype>
589   <funcdef>int <function>encode_rs8 </function></funcdef>
590   <paramdef>struct rs_control * <parameter>rs</parameter></paramdef>
591   <paramdef>uint8_t * <parameter>data</parameter></paramdef>
592   <paramdef>int <parameter>len</parameter></paramdef>
593   <paramdef>uint16_t * <parameter>par</parameter></paramdef>
594   <paramdef>uint16_t <parameter>invmsk</parameter></paramdef>
595  </funcprototype></funcsynopsis>
596</refsynopsisdiv>
597<refsect1>
598 <title>Arguments</title>
599 <variablelist>
600  <varlistentry>
601   <term><parameter>rs</parameter></term>
602   <listitem>
603    <para>
604     the rs control structure
605    </para>
606   </listitem>
607  </varlistentry>
608  <varlistentry>
609   <term><parameter>data</parameter></term>
610   <listitem>
611    <para>
612     data field of a given type
613    </para>
614   </listitem>
615  </varlistentry>
616  <varlistentry>
617   <term><parameter>len</parameter></term>
618   <listitem>
619    <para>
620     data length
621    </para>
622   </listitem>
623  </varlistentry>
624  <varlistentry>
625   <term><parameter>par</parameter></term>
626   <listitem>
627    <para>
628     parity data, must be initialized by caller (usually all 0)
629    </para>
630   </listitem>
631  </varlistentry>
632  <varlistentry>
633   <term><parameter>invmsk</parameter></term>
634   <listitem>
635    <para>
636     invert data mask (will be xored on data)
637    </para>
638   </listitem>
639  </varlistentry>
640 </variablelist>
641</refsect1>
642<refsect1>
643<title>Description</title>
644<para>
645   The parity uses a uint16_t data type to enable
646   symbol size &gt; 8. The calling code must take care of encoding of the
647   syndrome result for storage itself.
648</para>
649</refsect1>
650</refentry>
651
652<refentry id="API-decode-rs8">
653<refentryinfo>
654 <title>LINUX</title>
655 <productname>Kernel Hackers Manual</productname>
656 <date>July 2017</date>
657</refentryinfo>
658<refmeta>
659 <refentrytitle><phrase>decode_rs8</phrase></refentrytitle>
660 <manvolnum>9</manvolnum>
661 <refmiscinfo class="version">4.1.27</refmiscinfo>
662</refmeta>
663<refnamediv>
664 <refname>decode_rs8</refname>
665 <refpurpose>
666     Decode codeword (8bit data width)
667 </refpurpose>
668</refnamediv>
669<refsynopsisdiv>
670 <title>Synopsis</title>
671  <funcsynopsis><funcprototype>
672   <funcdef>int <function>decode_rs8 </function></funcdef>
673   <paramdef>struct rs_control * <parameter>rs</parameter></paramdef>
674   <paramdef>uint8_t * <parameter>data</parameter></paramdef>
675   <paramdef>uint16_t * <parameter>par</parameter></paramdef>
676   <paramdef>int <parameter>len</parameter></paramdef>
677   <paramdef>uint16_t * <parameter>s</parameter></paramdef>
678   <paramdef>int <parameter>no_eras</parameter></paramdef>
679   <paramdef>int * <parameter>eras_pos</parameter></paramdef>
680   <paramdef>uint16_t <parameter>invmsk</parameter></paramdef>
681   <paramdef>uint16_t * <parameter>corr</parameter></paramdef>
682  </funcprototype></funcsynopsis>
683</refsynopsisdiv>
684<refsect1>
685 <title>Arguments</title>
686 <variablelist>
687  <varlistentry>
688   <term><parameter>rs</parameter></term>
689   <listitem>
690    <para>
691     the rs control structure
692    </para>
693   </listitem>
694  </varlistentry>
695  <varlistentry>
696   <term><parameter>data</parameter></term>
697   <listitem>
698    <para>
699     data field of a given type
700    </para>
701   </listitem>
702  </varlistentry>
703  <varlistentry>
704   <term><parameter>par</parameter></term>
705   <listitem>
706    <para>
707     received parity data field
708    </para>
709   </listitem>
710  </varlistentry>
711  <varlistentry>
712   <term><parameter>len</parameter></term>
713   <listitem>
714    <para>
715     data length
716    </para>
717   </listitem>
718  </varlistentry>
719  <varlistentry>
720   <term><parameter>s</parameter></term>
721   <listitem>
722    <para>
723     syndrome data field (if NULL, syndrome is calculated)
724    </para>
725   </listitem>
726  </varlistentry>
727  <varlistentry>
728   <term><parameter>no_eras</parameter></term>
729   <listitem>
730    <para>
731     number of erasures
732    </para>
733   </listitem>
734  </varlistentry>
735  <varlistentry>
736   <term><parameter>eras_pos</parameter></term>
737   <listitem>
738    <para>
739     position of erasures, can be NULL
740    </para>
741   </listitem>
742  </varlistentry>
743  <varlistentry>
744   <term><parameter>invmsk</parameter></term>
745   <listitem>
746    <para>
747     invert data mask (will be xored on data, not on parity!)
748    </para>
749   </listitem>
750  </varlistentry>
751  <varlistentry>
752   <term><parameter>corr</parameter></term>
753   <listitem>
754    <para>
755     buffer to store correction bitmask on eras_pos
756    </para>
757   </listitem>
758  </varlistentry>
759 </variablelist>
760</refsect1>
761<refsect1>
762<title>Description</title>
763<para>
764   The syndrome and parity uses a uint16_t data type to enable
765   symbol size &gt; 8. The calling code must take care of decoding of the
766   syndrome result and the received parity before calling this code.
767   Returns the number of corrected bits or -EBADMSG for uncorrectable errors.
768</para>
769</refsect1>
770</refentry>
771
772<refentry id="API-encode-rs16">
773<refentryinfo>
774 <title>LINUX</title>
775 <productname>Kernel Hackers Manual</productname>
776 <date>July 2017</date>
777</refentryinfo>
778<refmeta>
779 <refentrytitle><phrase>encode_rs16</phrase></refentrytitle>
780 <manvolnum>9</manvolnum>
781 <refmiscinfo class="version">4.1.27</refmiscinfo>
782</refmeta>
783<refnamediv>
784 <refname>encode_rs16</refname>
785 <refpurpose>
786     Calculate the parity for data values (16bit data width)
787 </refpurpose>
788</refnamediv>
789<refsynopsisdiv>
790 <title>Synopsis</title>
791  <funcsynopsis><funcprototype>
792   <funcdef>int <function>encode_rs16 </function></funcdef>
793   <paramdef>struct rs_control * <parameter>rs</parameter></paramdef>
794   <paramdef>uint16_t * <parameter>data</parameter></paramdef>
795   <paramdef>int <parameter>len</parameter></paramdef>
796   <paramdef>uint16_t * <parameter>par</parameter></paramdef>
797   <paramdef>uint16_t <parameter>invmsk</parameter></paramdef>
798  </funcprototype></funcsynopsis>
799</refsynopsisdiv>
800<refsect1>
801 <title>Arguments</title>
802 <variablelist>
803  <varlistentry>
804   <term><parameter>rs</parameter></term>
805   <listitem>
806    <para>
807     the rs control structure
808    </para>
809   </listitem>
810  </varlistentry>
811  <varlistentry>
812   <term><parameter>data</parameter></term>
813   <listitem>
814    <para>
815     data field of a given type
816    </para>
817   </listitem>
818  </varlistentry>
819  <varlistentry>
820   <term><parameter>len</parameter></term>
821   <listitem>
822    <para>
823     data length
824    </para>
825   </listitem>
826  </varlistentry>
827  <varlistentry>
828   <term><parameter>par</parameter></term>
829   <listitem>
830    <para>
831     parity data, must be initialized by caller (usually all 0)
832    </para>
833   </listitem>
834  </varlistentry>
835  <varlistentry>
836   <term><parameter>invmsk</parameter></term>
837   <listitem>
838    <para>
839     invert data mask (will be xored on data, not on parity!)
840    </para>
841   </listitem>
842  </varlistentry>
843 </variablelist>
844</refsect1>
845<refsect1>
846<title>Description</title>
847<para>
848   Each field in the data array contains up to symbol size bits of valid data.
849</para>
850</refsect1>
851</refentry>
852
853<refentry id="API-decode-rs16">
854<refentryinfo>
855 <title>LINUX</title>
856 <productname>Kernel Hackers Manual</productname>
857 <date>July 2017</date>
858</refentryinfo>
859<refmeta>
860 <refentrytitle><phrase>decode_rs16</phrase></refentrytitle>
861 <manvolnum>9</manvolnum>
862 <refmiscinfo class="version">4.1.27</refmiscinfo>
863</refmeta>
864<refnamediv>
865 <refname>decode_rs16</refname>
866 <refpurpose>
867     Decode codeword (16bit data width)
868 </refpurpose>
869</refnamediv>
870<refsynopsisdiv>
871 <title>Synopsis</title>
872  <funcsynopsis><funcprototype>
873   <funcdef>int <function>decode_rs16 </function></funcdef>
874   <paramdef>struct rs_control * <parameter>rs</parameter></paramdef>
875   <paramdef>uint16_t * <parameter>data</parameter></paramdef>
876   <paramdef>uint16_t * <parameter>par</parameter></paramdef>
877   <paramdef>int <parameter>len</parameter></paramdef>
878   <paramdef>uint16_t * <parameter>s</parameter></paramdef>
879   <paramdef>int <parameter>no_eras</parameter></paramdef>
880   <paramdef>int * <parameter>eras_pos</parameter></paramdef>
881   <paramdef>uint16_t <parameter>invmsk</parameter></paramdef>
882   <paramdef>uint16_t * <parameter>corr</parameter></paramdef>
883  </funcprototype></funcsynopsis>
884</refsynopsisdiv>
885<refsect1>
886 <title>Arguments</title>
887 <variablelist>
888  <varlistentry>
889   <term><parameter>rs</parameter></term>
890   <listitem>
891    <para>
892     the rs control structure
893    </para>
894   </listitem>
895  </varlistentry>
896  <varlistentry>
897   <term><parameter>data</parameter></term>
898   <listitem>
899    <para>
900     data field of a given type
901    </para>
902   </listitem>
903  </varlistentry>
904  <varlistentry>
905   <term><parameter>par</parameter></term>
906   <listitem>
907    <para>
908     received parity data field
909    </para>
910   </listitem>
911  </varlistentry>
912  <varlistentry>
913   <term><parameter>len</parameter></term>
914   <listitem>
915    <para>
916     data length
917    </para>
918   </listitem>
919  </varlistentry>
920  <varlistentry>
921   <term><parameter>s</parameter></term>
922   <listitem>
923    <para>
924     syndrome data field (if NULL, syndrome is calculated)
925    </para>
926   </listitem>
927  </varlistentry>
928  <varlistentry>
929   <term><parameter>no_eras</parameter></term>
930   <listitem>
931    <para>
932     number of erasures
933    </para>
934   </listitem>
935  </varlistentry>
936  <varlistentry>
937   <term><parameter>eras_pos</parameter></term>
938   <listitem>
939    <para>
940     position of erasures, can be NULL
941    </para>
942   </listitem>
943  </varlistentry>
944  <varlistentry>
945   <term><parameter>invmsk</parameter></term>
946   <listitem>
947    <para>
948     invert data mask (will be xored on data, not on parity!)
949    </para>
950   </listitem>
951  </varlistentry>
952  <varlistentry>
953   <term><parameter>corr</parameter></term>
954   <listitem>
955    <para>
956     buffer to store correction bitmask on eras_pos
957    </para>
958   </listitem>
959  </varlistentry>
960 </variablelist>
961</refsect1>
962<refsect1>
963<title>Description</title>
964<para>
965   Each field in the data array contains up to symbol size bits of valid data.
966   Returns the number of corrected bits or -EBADMSG for uncorrectable errors.
967</para>
968</refsect1>
969</refentry>
970
971  </chapter>
972  
973  <chapter id="credits">
974     <title>Credits</title>
975	<para>
976		The library code for encoding and decoding was written by Phil Karn.
977	</para>
978	<programlisting>
979		Copyright 2002, Phil Karn, KA9Q
980 		May be used under the terms of the GNU General Public License (GPL)
981	</programlisting>
982	<para>
983		The wrapper functions and interfaces are written by Thomas Gleixner.
984	</para>
985	<para>
986		Many users have provided bugfixes, improvements and helping hands for testing.
987		Thanks a lot.
988	</para>
989	<para>
990		The following people have contributed to this document:
991	</para>
992	<para>
993		Thomas Gleixner<email>tglx@linutronix.de</email>
994	</para>
995  </chapter>
996</book>
997