tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs-rst: convert librs book to ReST
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
+214
-290
+1
-1
Documentation/DocBook/Makefile
+1
-1
Documentation/DocBook/Makefile
-289
Documentation/DocBook/librs.tmpl
-289
Documentation/DocBook/librs.tmpl
···
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 */
98
-
static 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
-
*/
106
-
rs_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 */
136
-
uint16_t par[6];
137
-
/* Initialize the parity buffer */
138
-
memset(par, 0, sizeof(par));
139
-
/* Encode 512 byte in data8. Store parity in buffer par */
140
-
encode_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 */
176
-
uint16_t par[6];
177
-
uint8_t data[512];
178
-
int numerr;
179
-
/* Receive data */
180
-
.....
181
-
/* Receive parity */
182
-
.....
183
-
/* Decode 512 byte in data8.*/
184
-
numerr = 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 */
194
-
uint16_t par[6], syn[6];
195
-
uint8_t data[512];
196
-
int numerr;
197
-
/* Receive data */
198
-
.....
199
-
/* Receive parity */
200
-
.....
201
-
/* Get syndrome from hardware decoder */
202
-
.....
203
-
/* Decode 512 byte in data8.*/
204
-
numerr = 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 */
217
-
uint16_t par[6], syn[6], corr[8];
218
-
uint8_t data[512];
219
-
int numerr, errpos[8];
220
-
/* Receive data */
221
-
.....
222
-
/* Receive parity */
223
-
.....
224
-
/* Get syndrome from hardware decoder */
225
-
.....
226
-
/* Decode 512 byte in data8.*/
227
-
numerr = decode_rs8 (rs_decoder, NULL, NULL, 512, syn, 0, errpos, 0, corr);
228
-
for (i = 0; i < 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 */
242
-
free_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
-
!Iinclude/linux/rslib.h
255
-
</chapter>
256
-
257
-
<chapter id="pubfunctions">
258
-
<title>Public Functions Provided</title>
259
-
<para>
260
-
This chapter contains the autogenerated documentation of the Reed-Solomon functions
261
-
which are exported.
262
-
</para>
263
-
!Elib/reed_solomon/reed_solomon.c
264
-
</chapter>
265
-
266
-
<chapter id="credits">
267
-
<title>Credits</title>
268
-
<para>
269
-
The library code for encoding and decoding was written by Phil Karn.
270
-
</para>
271
-
<programlisting>
272
-
Copyright 2002, Phil Karn, KA9Q
273
-
May be used under the terms of the GNU General Public License (GPL)
274
-
</programlisting>
275
-
<para>
276
-
The wrapper functions and interfaces are written by Thomas Gleixner.
277
-
</para>
278
-
<para>
279
-
Many users have provided bugfixes, improvements and helping hands for testing.
280
-
Thanks a lot.
281
-
</para>
282
-
<para>
283
-
The following people have contributed to this document:
284
-
</para>
285
-
<para>
286
-
Thomas Gleixner<email>tglx@linutronix.de</email>
287
-
</para>
288
-
</chapter>
289
-
</book>
+1
Documentation/core-api/index.rst
+1
Documentation/core-api/index.rst
+212
Documentation/core-api/librs.rst
+212
Documentation/core-api/librs.rst
···
1
+
==========================================
2
+
Reed-Solomon Library Programming Interface
3
+
==========================================
4
+
5
+
:Author: Thomas Gleixner
6
+
7
+
Introduction
8
+
============
9
+
10
+
The generic Reed-Solomon Library provides encoding, decoding and error
11
+
correction functions.
12
+
13
+
Reed-Solomon codes are used in communication and storage applications to
14
+
ensure data integrity.
15
+
16
+
This documentation is provided for developers who want to utilize the
17
+
functions provided by the library.
18
+
19
+
Known Bugs And Assumptions
20
+
==========================
21
+
22
+
None.
23
+
24
+
Usage
25
+
=====
26
+
27
+
This chapter provides examples of how to use the library.
28
+
29
+
Initializing
30
+
------------
31
+
32
+
The init function init_rs returns a pointer to an rs decoder structure,
33
+
which holds the necessary information for encoding, decoding and error
34
+
correction with the given polynomial. It either uses an existing
35
+
matching decoder or creates a new one. On creation all the lookup tables
36
+
for fast en/decoding are created. The function may take a while, so make
37
+
sure not to call it in critical code paths.
38
+
39
+
::
40
+
41
+
/* the Reed Solomon control structure */
42
+
static struct rs_control *rs_decoder;
43
+
44
+
/* Symbolsize is 10 (bits)
45
+
* Primitive polynomial is x^10+x^3+1
46
+
* first consecutive root is 0
47
+
* primitive element to generate roots = 1
48
+
* generator polynomial degree (number of roots) = 6
49
+
*/
50
+
rs_decoder = init_rs (10, 0x409, 0, 1, 6);
51
+
52
+
53
+
Encoding
54
+
--------
55
+
56
+
The encoder calculates the Reed-Solomon code over the given data length
57
+
and stores the result in the parity buffer. Note that the parity buffer
58
+
must be initialized before calling the encoder.
59
+
60
+
The expanded data can be inverted on the fly by providing a non-zero
61
+
inversion mask. The expanded data is XOR'ed with the mask. This is used
62
+
e.g. for FLASH ECC, where the all 0xFF is inverted to an all 0x00. The
63
+
Reed-Solomon code for all 0x00 is all 0x00. The code is inverted before
64
+
storing to FLASH so it is 0xFF too. This prevents that reading from an
65
+
erased FLASH results in ECC errors.
66
+
67
+
The databytes are expanded to the given symbol size on the fly. There is
68
+
no support for encoding continuous bitstreams with a symbol size != 8 at
69
+
the moment. If it is necessary it should be not a big deal to implement
70
+
such functionality.
71
+
72
+
::
73
+
74
+
/* Parity buffer. Size = number of roots */
75
+
uint16_t par[6];
76
+
/* Initialize the parity buffer */
77
+
memset(par, 0, sizeof(par));
78
+
/* Encode 512 byte in data8. Store parity in buffer par */
79
+
encode_rs8 (rs_decoder, data8, 512, par, 0);
80
+
81
+
82
+
Decoding
83
+
--------
84
+
85
+
The decoder calculates the syndrome over the given data length and the
86
+
received parity symbols and corrects errors in the data.
87
+
88
+
If a syndrome is available from a hardware decoder then the syndrome
89
+
calculation is skipped.
90
+
91
+
The correction of the data buffer can be suppressed by providing a
92
+
correction pattern buffer and an error location buffer to the decoder.
93
+
The decoder stores the calculated error location and the correction
94
+
bitmask in the given buffers. This is useful for hardware decoders which
95
+
use a weird bit ordering scheme.
96
+
97
+
The databytes are expanded to the given symbol size on the fly. There is
98
+
no support for decoding continuous bitstreams with a symbolsize != 8 at
99
+
the moment. If it is necessary it should be not a big deal to implement
100
+
such functionality.
101
+
102
+
Decoding with syndrome calculation, direct data correction
103
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
104
+
105
+
::
106
+
107
+
/* Parity buffer. Size = number of roots */
108
+
uint16_t par[6];
109
+
uint8_t data[512];
110
+
int numerr;
111
+
/* Receive data */
112
+
.....
113
+
/* Receive parity */
114
+
.....
115
+
/* Decode 512 byte in data8.*/
116
+
numerr = decode_rs8 (rs_decoder, data8, par, 512, NULL, 0, NULL, 0, NULL);
117
+
118
+
119
+
Decoding with syndrome given by hardware decoder, direct data correction
120
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
121
+
122
+
::
123
+
124
+
/* Parity buffer. Size = number of roots */
125
+
uint16_t par[6], syn[6];
126
+
uint8_t data[512];
127
+
int numerr;
128
+
/* Receive data */
129
+
.....
130
+
/* Receive parity */
131
+
.....
132
+
/* Get syndrome from hardware decoder */
133
+
.....
134
+
/* Decode 512 byte in data8.*/
135
+
numerr = decode_rs8 (rs_decoder, data8, par, 512, syn, 0, NULL, 0, NULL);
136
+
137
+
138
+
Decoding with syndrome given by hardware decoder, no direct data correction.
139
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
140
+
141
+
Note: It's not necessary to give data and received parity to the
142
+
decoder.
143
+
144
+
::
145
+
146
+
/* Parity buffer. Size = number of roots */
147
+
uint16_t par[6], syn[6], corr[8];
148
+
uint8_t data[512];
149
+
int numerr, errpos[8];
150
+
/* Receive data */
151
+
.....
152
+
/* Receive parity */
153
+
.....
154
+
/* Get syndrome from hardware decoder */
155
+
.....
156
+
/* Decode 512 byte in data8.*/
157
+
numerr = decode_rs8 (rs_decoder, NULL, NULL, 512, syn, 0, errpos, 0, corr);
158
+
for (i = 0; i < numerr; i++) {
159
+
do_error_correction_in_your_buffer(errpos[i], corr[i]);
160
+
}
161
+
162
+
163
+
Cleanup
164
+
-------
165
+
166
+
The function free_rs frees the allocated resources, if the caller is
167
+
the last user of the decoder.
168
+
169
+
::
170
+
171
+
/* Release resources */
172
+
free_rs(rs_decoder);
173
+
174
+
175
+
Structures
176
+
==========
177
+
178
+
This chapter contains the autogenerated documentation of the structures
179
+
which are used in the Reed-Solomon Library and are relevant for a
180
+
developer.
181
+
182
+
.. kernel-doc:: include/linux/rslib.h
183
+
:internal:
184
+
185
+
Public Functions Provided
186
+
=========================
187
+
188
+
This chapter contains the autogenerated documentation of the
189
+
Reed-Solomon functions which are exported.
190
+
191
+
.. kernel-doc:: lib/reed_solomon/reed_solomon.c
192
+
:export:
193
+
194
+
Credits
195
+
=======
196
+
197
+
The library code for encoding and decoding was written by Phil Karn.
198
+
199
+
::
200
+
201
+
Copyright 2002, Phil Karn, KA9Q
202
+
May be used under the terms of the GNU General Public License (GPL)
203
+
204
+
205
+
The wrapper functions and interfaces are written by Thomas Gleixner.
206
+
207
+
Many users have provided bugfixes, improvements and helping hands for
208
+
testing. Thanks a lot.
209
+
210
+
The following people have contributed to this document:
211
+
212
+
Thomas Gleixner\ tglx@linutronix.de