| 1 | .\" nroff |
| 2 | .ie t \{\ |
| 3 | . ds ss \s8\u |
| 4 | . ds se \d\s0 |
| 5 | .\} |
| 6 | .el \{\ |
| 7 | . ds ss ^ |
| 8 | . ds se |
| 9 | .\} |
| 10 | .TH crc-mktab 1 "9 November 2003" "Straylight/Edgeware" "mLib utilities library" |
| 11 | .SH NAME |
| 12 | crc-mktab \- construct CRC tables for efficient computation |
| 13 | .SH SYNOPSIS |
| 14 | .B crc-mktab |
| 15 | .RB [ \-cr ] |
| 16 | .RB [ \-s |
| 17 | .IR symbol ] |
| 18 | .RB [ \-t |
| 19 | .IR type ] |
| 20 | .RB [ \-i |
| 21 | .IR header ] |
| 22 | .br |
| 23 | \c |
| 24 | .RB [ \-g |
| 25 | .IR macro ] |
| 26 | .RB [ \-b |
| 27 | .IR bits ] |
| 28 | .RB [ \-B |
| 29 | .IR chunk ] |
| 30 | .RB [ \-p |
| 31 | .IR poly ] |
| 32 | .br |
| 33 | \c |
| 34 | .RB [ \-o |
| 35 | .IR filename ] |
| 36 | .SH DESCRIPTION |
| 37 | The |
| 38 | .B crc-mktab |
| 39 | program constructs tables for efficient computation of CRC (cyclic |
| 40 | redundancy check) values. It will produce the table as either an array |
| 41 | defined in a C source file or as an initializer macro defined in a C |
| 42 | header file. |
| 43 | .SS "Options" |
| 44 | The program accepts no non-option arguments. At least one of |
| 45 | .B \-b |
| 46 | or |
| 47 | .B \-p |
| 48 | must be given. The options are as follows. |
| 49 | .TP |
| 50 | .B "\-h, \-\-help" |
| 51 | Print a help message to standard output and exit successfully. |
| 52 | .TP |
| 53 | .B "\-v, \-\-version" |
| 54 | Print the program's version number to standard output and exit |
| 55 | successfully. |
| 56 | .TP |
| 57 | .B "\-u, \-\-usage" |
| 58 | Print a one-line usage summary to standard output and exit successfully. |
| 59 | .TP |
| 60 | .B "\-c, \-\-c-source" |
| 61 | Produce a C source file which exports a symbol naming the array, instead |
| 62 | of a C header file. |
| 63 | .TP |
| 64 | .BI "\-s, \-\-symbol=" symbol |
| 65 | Name the table |
| 66 | .IR symbol . |
| 67 | This is the name of the macro defined by a header file, or the array |
| 68 | exported by a C source. The default macro name is |
| 69 | .BR CRC_TAB ; |
| 70 | the default array name is |
| 71 | .BR crctab . |
| 72 | .TP |
| 73 | .BI "\-t, \-\-type=" type |
| 74 | Specify the element type of the array defined by a C source output. The |
| 75 | default is |
| 76 | .B "unsigned short" |
| 77 | if the polynomial has degree 16 or less, or |
| 78 | .B "unsigned long" |
| 79 | otherwise. This option does nothing without the |
| 80 | .B \-c |
| 81 | option. |
| 82 | .TP |
| 83 | .BI "\-i, \-\-include=" header |
| 84 | Request that generated C source include the named |
| 85 | .I header |
| 86 | file. Inserts a |
| 87 | line of the form |
| 88 | .PP |
| 89 | .nf |
| 90 | .BI " #include """ header """" |
| 91 | .fi |
| 92 | .IP |
| 93 | at the top of the generated C source. The default is not to include a |
| 94 | header file. This option does nothing without the |
| 95 | .B \-c |
| 96 | option. |
| 97 | .TP |
| 98 | .BI "\-g, \-\-guard=" macro |
| 99 | Use the named |
| 100 | .I macro |
| 101 | as a guard against multiple inclusion of the generated header file. |
| 102 | Inserts a pair of lines of the form |
| 103 | .PP |
| 104 | .nf |
| 105 | .BI " #ifndef " macro |
| 106 | .BI " #define " macro |
| 107 | .fi |
| 108 | .IP |
| 109 | at the top of the generated header, and a line |
| 110 | .PP |
| 111 | .nf |
| 112 | .BI " #endif" |
| 113 | .fi |
| 114 | .IP |
| 115 | at the end. The default guard macro name is built from the output file |
| 116 | name specified with |
| 117 | .B \-o |
| 118 | by uppercasing all alphabetic characters in the name and replacing |
| 119 | nonalphanumeric characters by underscores |
| 120 | .RB ` _ '. |
| 121 | This option does nothing with the |
| 122 | .B \-c |
| 123 | option. |
| 124 | .TP |
| 125 | .BI "\-b, \-\-bits=" bits |
| 126 | Specifies the degree of the CRC polynomial or, equivalently, the length |
| 127 | of the generated CRC. This must be an integer between 1 and 32 |
| 128 | inclusive. If it is not specified, the polynomial given by |
| 129 | .B \-p |
| 130 | is examined and an educated guess made. (Currently we choose the |
| 131 | smallest multiple of 8 which is large enough.) |
| 132 | .TP |
| 133 | .BI "\-B, \-\-bit-chunk=" chunk |
| 134 | Chunk size in which bits are taken from the input. The number of |
| 135 | entries in the table is precisely |
| 136 | .RI 2\*(ss chunk \*(se. |
| 137 | The default chunk size is 8. |
| 138 | .TP |
| 139 | .BI "\-p, \-\-polynomial=" poly |
| 140 | Specifies the CRC polynomial as an integer. The polynomial has a |
| 141 | nonzero coefficient in its |
| 142 | .IR x \*(ss i \*(se |
| 143 | term if and only if bit |
| 144 | .I i |
| 145 | of |
| 146 | .I poly |
| 147 | is nonzero. Note that if you want to specify the polynomial in |
| 148 | hexadecimal, you must prefix it with |
| 149 | .BR 0x . |
| 150 | Default polynomials of degree 16 and 32 are known. |
| 151 | .TP |
| 152 | .B "\-r, \-\-reverse" |
| 153 | Construct the table to compensate for unusual bit-ordering. Without |
| 154 | this option, you'd have to reverse the order of all input chunks and the |
| 155 | output CRC. |
| 156 | .SS "The table and how to use it" |
| 157 | Describing in detail the contents of the table would take too long. For |
| 158 | an example of use, see the header file |
| 159 | .BR crc32.h . |
| 160 | .SH "SEE ALSO" |
| 161 | .BR crc32 (3). |
| 162 | .PP |
| 163 | .I A painless guide to CRC error detection algorithms |
| 164 | by Ross N. Williams. |
| 165 | .SH "AUTHOR" |
| 166 | Mark Wooding, <mdw@distorted.org.uk> |
| 167 | |