Commit | Line | Data |
---|---|---|
7c14e955 | 1 | .\" nroff |
c4ccbbf9 MW |
2 | .\" |
3 | .\" Manual for CRC table generator | |
4 | .\" | |
5 | .\" (c) 2003, 2005, 2007, 2009, 2019, 2024 Straylight/Edgeware | |
6 | .\" | |
7 | . | |
8 | .\"----- Licensing notice --------------------------------------------------- | |
9 | .\" | |
10 | .\" This file is part of the mLib utilities library. | |
11 | .\" | |
12 | .\" mLib is free software: you can redistribute it and/or modify it under | |
13 | .\" the terms of the GNU Library General Public License as published by | |
14 | .\" the Free Software Foundation; either version 2 of the License, or (at | |
15 | .\" your option) any later version. | |
16 | .\" | |
17 | .\" mLib is distributed in the hope that it will be useful, but WITHOUT | |
18 | .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
19 | .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public | |
20 | .\" License for more details. | |
21 | .\" | |
22 | .\" You should have received a copy of the GNU Library General Public | |
23 | .\" License along with mLib. If not, write to the Free Software | |
24 | .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, | |
25 | .\" USA. | |
26 | . | |
27 | .\"-------------------------------------------------------------------------- | |
28 | .so ../defs.man \" @@@PRE@@@ | |
29 | . | |
30 | .\"-------------------------------------------------------------------------- | |
7c14e955 | 31 | .TH crc-mktab 1 "9 November 2003" "Straylight/Edgeware" "mLib utilities library" |
c4ccbbf9 MW |
32 | . |
33 | .\"-------------------------------------------------------------------------- | |
7c14e955 | 34 | .SH NAME |
35 | crc-mktab \- construct CRC tables for efficient computation | |
c4ccbbf9 MW |
36 | . |
37 | .\"-------------------------------------------------------------------------- | |
7c14e955 | 38 | .SH SYNOPSIS |
c4ccbbf9 | 39 | . |
7c14e955 | 40 | .B crc-mktab |
3e7267bf | 41 | .RB [ \-Ccr ] |
7c14e955 | 42 | .RB [ \-s |
43 | .IR symbol ] | |
44 | .RB [ \-t | |
45 | .IR type ] | |
46 | .RB [ \-i | |
47 | .IR header ] | |
48 | .br | |
49 | \c | |
50 | .RB [ \-g | |
51 | .IR macro ] | |
52 | .RB [ \-b | |
53 | .IR bits ] | |
54 | .RB [ \-B | |
55 | .IR chunk ] | |
56 | .RB [ \-p | |
57 | .IR poly ] | |
58 | .br | |
59 | \c | |
60 | .RB [ \-o | |
61 | .IR filename ] | |
c4ccbbf9 MW |
62 | . |
63 | .\"-------------------------------------------------------------------------- | |
7c14e955 | 64 | .SH DESCRIPTION |
c4ccbbf9 | 65 | . |
7c14e955 | 66 | The |
67 | .B crc-mktab | |
68 | program constructs tables for efficient computation of CRC (cyclic | |
69 | redundancy check) values. It will produce the table as either an array | |
70 | defined in a C source file or as an initializer macro defined in a C | |
71 | header file. | |
72 | .SS "Options" | |
73 | The program accepts no non-option arguments. At least one of | |
74 | .B \-b | |
75 | or | |
76 | .B \-p | |
77 | must be given. The options are as follows. | |
78 | .TP | |
79 | .B "\-h, \-\-help" | |
80 | Print a help message to standard output and exit successfully. | |
81 | .TP | |
82 | .B "\-v, \-\-version" | |
83 | Print the program's version number to standard output and exit | |
84 | successfully. | |
85 | .TP | |
86 | .B "\-u, \-\-usage" | |
87 | Print a one-line usage summary to standard output and exit successfully. | |
88 | .TP | |
3e7267bf MW |
89 | .B "\-C, \-\-const" |
90 | When producing C source (the | |
91 | .B \-c | |
92 | option), rather than a header, define the table to be | |
93 | .BR const . | |
7c14e955 | 94 | .B "\-c, \-\-c-source" |
95 | Produce a C source file which exports a symbol naming the array, instead | |
96 | of a C header file. | |
97 | .TP | |
6f444bda | 98 | .BI "\-s, \-\-symbol=" symbol |
7c14e955 | 99 | Name the table |
100 | .IR symbol . | |
101 | This is the name of the macro defined by a header file, or the array | |
102 | exported by a C source. The default macro name is | |
103 | .BR CRC_TAB ; | |
104 | the default array name is | |
105 | .BR crctab . | |
106 | .TP | |
107 | .BI "\-t, \-\-type=" type | |
108 | Specify the element type of the array defined by a C source output. The | |
d4efbcd9 | 109 | default is |
7c14e955 | 110 | .B "unsigned short" |
111 | if the polynomial has degree 16 or less, or | |
112 | .B "unsigned long" | |
113 | otherwise. This option does nothing without the | |
114 | .B \-c | |
115 | option. | |
116 | .TP | |
117 | .BI "\-i, \-\-include=" header | |
c4ccbbf9 | 118 | .RS |
d4efbcd9 | 119 | Request that generated C source include the named |
7c14e955 | 120 | .I header |
121 | file. Inserts a | |
122 | line of the form | |
7c14e955 | 123 | .IP |
c4ccbbf9 MW |
124 | .BI "#include """ header """" |
125 | .PP | |
7c14e955 | 126 | at the top of the generated C source. The default is not to include a |
127 | header file. This option does nothing without the | |
128 | .B \-c | |
129 | option. | |
c4ccbbf9 | 130 | .RE |
7c14e955 | 131 | .TP |
132 | .BI "\-g, \-\-guard=" macro | |
c4ccbbf9 | 133 | .RS |
7c14e955 | 134 | Use the named |
135 | .I macro | |
136 | as a guard against multiple inclusion of the generated header file. | |
137 | Inserts a pair of lines of the form | |
7c14e955 | 138 | .IP |
7c14e955 | 139 | .nf |
c4ccbbf9 MW |
140 | .BI "#ifndef " macro |
141 | .BI "#define " macro | |
7c14e955 | 142 | .fi |
c4ccbbf9 MW |
143 | .PP |
144 | at the top of the generated header, and a line | |
7c14e955 | 145 | .IP |
c4ccbbf9 MW |
146 | .BI "#endif" |
147 | .PP | |
7c14e955 | 148 | at the end. The default guard macro name is built from the output file |
149 | name specified with | |
150 | .B \-o | |
151 | by uppercasing all alphabetic characters in the name and replacing | |
d4efbcd9 | 152 | nonalphanumeric characters by underscores |
7c14e955 | 153 | .RB ` _ '. |
154 | This option does nothing with the | |
155 | .B \-c | |
156 | option. | |
c4ccbbf9 | 157 | .RE |
7c14e955 | 158 | .TP |
159 | .BI "\-b, \-\-bits=" bits | |
160 | Specifies the degree of the CRC polynomial or, equivalently, the length | |
161 | of the generated CRC. This must be an integer between 1 and 32 | |
162 | inclusive. If it is not specified, the polynomial given by | |
163 | .B \-p | |
164 | is examined and an educated guess made. (Currently we choose the | |
165 | smallest multiple of 8 which is large enough.) | |
166 | .TP | |
167 | .BI "\-B, \-\-bit-chunk=" chunk | |
168 | Chunk size in which bits are taken from the input. The number of | |
169 | entries in the table is precisely | |
170 | .RI 2\*(ss chunk \*(se. | |
171 | The default chunk size is 8. | |
172 | .TP | |
173 | .BI "\-p, \-\-polynomial=" poly | |
174 | Specifies the CRC polynomial as an integer. The polynomial has a | |
175 | nonzero coefficient in its | |
176 | .IR x \*(ss i \*(se | |
177 | term if and only if bit | |
178 | .I i | |
179 | of | |
180 | .I poly | |
181 | is nonzero. Note that if you want to specify the polynomial in | |
182 | hexadecimal, you must prefix it with | |
183 | .BR 0x . | |
184 | Default polynomials of degree 16 and 32 are known. | |
185 | .TP | |
186 | .B "\-r, \-\-reverse" | |
187 | Construct the table to compensate for unusual bit-ordering. Without | |
188 | this option, you'd have to reverse the order of all input chunks and the | |
189 | output CRC. | |
190 | .SS "The table and how to use it" | |
191 | Describing in detail the contents of the table would take too long. For | |
192 | an example of use, see the header file | |
193 | .BR crc32.h . | |
c4ccbbf9 MW |
194 | . |
195 | .\"-------------------------------------------------------------------------- | |
7c14e955 | 196 | .SH "SEE ALSO" |
c4ccbbf9 | 197 | . |
7c14e955 | 198 | .BR crc32 (3). |
199 | .PP | |
200 | .I A painless guide to CRC error detection algorithms | |
201 | by Ross N. Williams. | |
c4ccbbf9 MW |
202 | . |
203 | .\"-------------------------------------------------------------------------- | |
7c14e955 | 204 | .SH "AUTHOR" |
c4ccbbf9 | 205 | . |
9b5ac6ff | 206 | Mark Wooding, <mdw@distorted.org.uk> |
c4ccbbf9 MW |
207 | . |
208 | .\"----- That's all, folks -------------------------------------------------- |