1.\"
2.\" Copyright 1998 by Luigi Rizzo, Dip. Ingegneria dell'Informazione,
3.\" Universitaet Berlin.  See the source code for copyright details.
4.\" THERE IS ABSOLUTELY NO WARRANTY FOR THIS SOFTWARE.
5.\"
6.Dd July 15, 1998
7.Dt FEC 3
8.Os
9.Sh NAME
10.Nm fec_new, fec_encode, fec_encode, fec_free
11.Nd An erasure code in GF(2^m)
12.Sh SYNOPSIS
13.Fd #include <fec.h>
14.Ft void *
15.Fn fec_new "int k" "int n"
16.Ft void
17.Fn fec_encode "void *code" "void *data[]" "void *dst" "int i" "int sz"
18.Ft int
19.Fn fec_decode "void *code" "void *data[]" "int i[]" "int sz"
20.Ft void *
21.Fn fec_free "void *code"
22.Sh "DESCRIPTION"
23This library implements a simple (n,k)
24erasure code based on Vandermonde matrices.
25The encoder takes
26.Fa k
27packets of size
28.Fa sz
29each, and is able to produce up to
30.Fa n
31different encoded packets, numbered from 0 to n-1,
32such that any subset of
33.Fa k
34of them permits reconstruction of the original data.
35.Pp
36The data structures necessary for the encoding/decoding must
37first be created using calling
38.Fn fec_new
39with the desired parameters. The code descriptor returned by the function
40must be passed to other functions, and destroyed calling
41.Fn fec_free
42.Pp
43Allowed values for k and n depend on a compile-time value
44of
45.Fa GF_BITS
46and must be k <= n <= 2^GF_BITS.
47Best performance is achieved with GF_BITS=8, although the code supports
48also GF_BITS=16.
49.Pp
50Encoding is done by calling
51.Fn fec_encode
52and passing it pointers to the code descriptor, the source and
53destination data packets, the index of the packet to be produced,
54and the size of the packet.
55
56.Pp Decoding is done calling
57.Fn fec_decode
58with pointers to the code, received packets, indexes of received
59packets, and packet size. Decoding is done in place, possibly
60shuffling the arrays passed as parameters.  Decoding is deterministic
61as long as the received packets are different. The decoding procedure
62does some limited testing on this and returns if parameters are
63invalid.
64
65.Sh EXAMPLE
66.nf
67#include <fec.h>
68
69/*
70 * example of sender code
71 */
72void *code ;
73int n, k ;
74
75void *src[] ;
76void *pkt ;
77
78code = new_code (k, n );
79
80for (i = 0 ; i < k ; i++ )
81    src[i] = .. pointer to i-th source packet ..
82for (each packet to transmit) {
83   i = ... index of the packet ;
84   fec_encode(code, src, pkt, i, size) ;
85   .. use packet in pkt
86}
87fec_free(code) ;
88
89/*
90 * example of receiver code
91 */
92void *code ;
93int n, k ;
94
95void *data[] ;
96int *ix[] ;
97
98code = new_code (k, n );
99
100for (i = 0 ; i < k ; i++ ) {
101    ... receive a new packet ...
102    data[i] = .. pointer to i-th source packet ..
103    ix[i] = .. index of i-th source packet ..
104}
105fec_decode(code, data, ix, size) ;
106/*
107 * now data[] has pointers to the source packets
108 */
109
110.SH BUGS
111Please direct bug reports to luigi@iet.unipi.it .
112.Sh "SEE ALSO"
113