smokephil/CANLibrary
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Added pycrc library (MIT License) for CRC calculations to the repository.

Browse source
This commit is contained in:
Christian Sltrop 2012-07-30 15:08:37 +02:00
parent c35e26f025
commit 3233dc96b1
24 changed files with 6136 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

26
pycrc/doc/Makefile Normal file
View file

@ -0,0 +1,26 @@
XSLTPROC = xsltproc
XSLTPARAM = --nonet --novalid
HTML_STYLESHEET = /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl
MAN_STYLESHEET = /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl
source = pycrc.xml
targets = $(source:.xml=.html) $(source:.xml=.1)
all: $(targets)
.PHONY: clean
clean:
$(RM) $(targets)
.PHONY: check
check:
xmllint --valid --noout $(source)
%.html: %.xml
$(XSLTPROC) $(XSLTPARAM) -o $@ $(HTML_STYLESHEET) $<
%.1: %.xml
$(XSLTPROC) $(XSLTPARAM) -o $@ $(MAN_STYLESHEET) $<
%.txt: %.html
links -dump -no-numbering -no-references $< > $@

531
pycrc/doc/pycrc.1 Normal file
View file

@ -0,0 +1,531 @@
'\" t
.\" Title: pycrc
.\" Author: Thomas Pircher <tehpeh@gmx.net>
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\" Date: 2011-11-19
.\" Manual: pycrc
.\" Source: pycrc 0.7.9
.\" Language: English
.\"
.TH "PYCRC" "1" "2011\-11\-19" "pycrc 0.7.9" "pycrc"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
pycrc \- a free, easy to use Cyclic Redundancy Check (CRC) calculator and source code generator\&.
.SH "SYNOPSIS"
.HP \w'\fBpycrc\fR\ 'u
\fBpycrc\fR [OPTIONS]
.SH "DESCRIPTION"
.PP
\m[blue]\fBpycrc\fR\m[]\&\s-2\u[1]\d\s+2
provides a parametrised CRC reference implementation written in Python and a source code generator for C\&. The generated C source code can be optimised for simplicity, speed or tight memory constraints for embedded platforms\&. The following operations are implemented:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
generate the checksum of a string (ASCII or hex)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
generate the checksum of a file
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
generate the C header and source files for a client implementation\&.
.RE
.PP
The following variants of the CRC algorithm are supported:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIbit\-by\-bit\fR: the basic algorithm which operates individually on every bit of the augmented message (i\&.e\&. the input data with
\fIWidth\fR
0\-bits attached to the end)\&. This algorithm is the easiest to understand because it is a straightforward implementation of the basic polynomial division, but it is also the slowest among all possible variants\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIbit\-by\-bit\-fast\fR: a variation of the simple
\fIbit\-by\-bit\fR
algorithm, with the difference that it does not need to augment the data, i\&.e\&. it does not add
\fIWidth\fR
zero bits at the end of the message\&. This algorithm might be a good choice for embedded platforms, where code space is a major concern\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fItable\-driven\fR: the standard table driven algorithm\&. This is the fastest variant because it operates on one byte at a time, as opposed to bits, and uses a look\-up table of 256 elements, which might not be feasible for small embedded systems, though\&. Anyway, the number of elements in the look\-up table can be reduced by means of the
\fB\-\-table\-idx\-width\fR
command line switch\&. By using 4 bits (16 elements in the look\-up table) a significant speed\-up can be measured with respect to the bit\-by\-bit algorithms\&.
.RE
.sp
.SH "OPTIONS"
.PP
\fB\-\-version\fR
.RS 4
show program\*(Aqs version number and exit
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
show this help message and exit
.RE
.PP
\fB\-\-verbose\fR
.RS 4
be more verbose; in particular, print the value of the parameters and the chosen model
.RE
.PP
\fB\-\-check\-string=\fR\fISTRING\fR
.RS 4
calculate the checksum of the given string (\*(Aq\fI123456789\fR\*(Aq default)
.RE
.PP
\fB\-\-check\-hexstring=\fR\fISTRING\fR
.RS 4
calculate the checksum of the given hexadecimal string
.RE
.PP
\fB\-\-check\-file=\fR\fIFILE\fR
.RS 4
calculate the checksum of the given file
.RE
.PP
\fB\-\-generate=\fR\fICODE\fR
.RS 4
generate the source code type as a choice from {c, h, c\-main, table}
.RE
.PP
\fB\-\-std=\fR\fISTD\fR
.RS 4
C standard style of the generated code from {C89, ANSI, C99}
.RE
.PP
\fB\-\-algorithm=\fR\fIALGO\fR
.RS 4
choose an algorithm from {\fIbit\-by\-bit\fR,
\fIbit\-by\-bit\-fast\fR,
\fItable\-driven\fR,
\fIall\fR}
.RE
.PP
\fB\-\-model=\fR\fIMODEL\fR
.RS 4
choose a parameter set from {\fIcrc\-5\fR,
\fIcrc\-8\fR,
\fIdallas\-1\-wire\fR,
\fIcrc\-12\-3gpp\fR,
\fIcrc\-15\fR,
\fIcrc\-16\fR,
\fIcrc\-16\-usb\fR,
\fIcrc\-16\-modbus\fR,
\fIcrc\-16\-genibus\fR,
\fIccitt\fR,
\fIr\-crc\-16\fR,
\fIkermit\fR,
\fIx\-25\fR,
\fIxmodem\fR,
\fIzmodem\fR,
\fIcrc\-24\fR,
\fIcrc\-32\fR,
\fIcrc\-32c\fR,
\fIcrc\-32\-mpeg\fR,
\fIcrc\-32\-bzip2\fR,
\fIposix\fR,
\fIjam\fR,
\fIxfer\fR,
\fIcrc\-64\fR,
\fIcrc\-64\-jones\fR,
\fIcrc\-64\-xz\fR}
.RE
.PP
\fB\-\-width=\fR\fINUM\fR
.RS 4
use
\fINUM\fR
bits in the
\fIPolynomial\fR
.RE
.PP
\fB\-\-poly=\fR\fIHEX\fR
.RS 4
use
\fIHEX\fR
as
\fIPolynomial\fR
.RE
.PP
\fB\-\-reflect\-in=\fR\fIBOOL\fR
.RS 4
reflect input bytes
.RE
.PP
\fB\-\-xor\-in=\fR\fIHEX\fR
.RS 4
use
\fIHEX\fR
as initial value
.RE
.PP
\fB\-\-reflect\-out=\fR\fIBOOL\fR
.RS 4
reflect output bytes
.RE
.PP
\fB\-\-xor\-out=\fR\fIHEX\fR
.RS 4
xor the final CRC value with
\fIHEX\fR
.RE
.PP
\fB\-\-table\-idx\-width=\fR\fINUM\fR
.RS 4
use
\fINUM\fR
bits to index the CRC table;
\fINUM\fR
must be one of the values {\fI1\fR,
\fI2\fR,
\fI4\fR,
\fI8\fR}
.RE
.PP
\fB\-\-symbol\-prefix=\fR\fISTRING\fR
.RS 4
when generating source code, use
\fISTRING\fR
as prefix to the generated symbols
.RE
.PP
\fB\-\-crc\-type=\fR\fISTRING\fR
.RS 4
when generating source code, use
\fISTRING\fR
as crc_t type
.RE
.PP
\fB\-\-include\-file=\fR\fIFILE\fR
.RS 4
when generating source code, include also
\fIFILE\fR
as header file
.RE
.PP
\fB\-o\fR\fIFILE\fR, \fB\-\-output=\fR\fIFILE\fR
.RS 4
write the generated code to
\fIFILE\fR
instead to stdout
.RE
.SH "THE CRC PARAMETRIC MODEL"
.PP
The parametric model follows Ross N\&. Williams\*(Aq convention described in
\m[blue]\fBA Painless Guide to CRC Error Detection Algorithms\fR\m[]\&\s-2\u[2]\d\s+2, commonly called the Rocksoft Model\&. Since most people are familiar with this kind of parameters, pycrc follows this convention, described as follows:
.PP
\fIWidth\fR
.RS 4
The width of the CRC
\fIPolynomial\fR, in number of bits\&. This is also the width of the final CRC result\&. Previous versions of pycrc only multiples of 8 could be be used as
\fIWidth\fR
for the
\fItable\-driven\fR
algorithm\&. As of version 0\&.7\&.5, any
\fIWidth\fR
is accepted on all algorithms\&.
.RE
.PP
\fIPolynomial\fR
.RS 4
The unreflected polynomial of the CRC algorithm\&.
.sp
The
\fIPolynomial\fR
may be specified in its standard form, i\&.e\&. with bit
\fIWidth\fR+1 set to 1, but the most significant bit may also be omitted\&. For example, for a
\fIWidth\fR
of 16, both forms 0x18005 and 0x8005 are accepted\&.
.RE
.PP
\fIReflectIn\fR
.RS 4
Reflect the bytes of the message before processing them\&. A word is reflected by inverting the position of its bits with respect to the middle axis of the word\&. The reversed value of 0xa3 (10100010b) is 0x45 (01000101b), for example\&. Some CRC algorithms can be implemented more efficiently in a bit reversed version\&.
.sp
Reflected algorithms are more efficient than straight\-forward implementations, thus many of the standard algorithmic variants use reflected input bytes\&.
.RE
.PP
\fIXorIn\fR
.RS 4
The initial value (usually all 0 or all 1) in the algorithms which operate on the non\-augmented message\&. This value can be seen as a value which will be XOR\-ed into the CRC register after
\fIWidth\fR
iterations of the
\fIbit\-by\-bit\fR
algorithm\&. This means the simple
\fIbit\-by\-bit\fR
algorithm must calculate the initial value using some sort of reverse CRC algorithm on the
\fIXorIn\fR
value\&.
.RE
.PP
\fIReflectOut\fR
.RS 4
Reflect the final CRC result\&. This operation takes place before XOR\-ing the final CRC value with the
\fIXorOut\fR
parameter\&.
.RE
.PP
\fIXorOut\fR
.RS 4
A value (usually all bits 0 or all 1) which will be XOR\-ed to the final CRC value\&.
.RE
.PP
\fICheck\fR
.RS 4
This value is not exactly a parameter of a model but it is sometimes given together with the Rocksoft Model parameters\&. It is the CRC value of the parametrised model over the string "\fI123456789\fR" and may be used to validate an implementation\&.
.RE
.SH "CODE GENERATION"
.PP
In the default configuration, the generated code is strict ISO C99 code\&. A minimal set of three functions are defined for each algorithm:
\fBcrc_init()\fR,
\fBcrc_update()\fR
and
\fBcrc_finalize()\fR\&. According to the number of parameters given to pycrc, a different interface definition is generated\&. Fully parametrised models have a simpler API, while the generated code for runtime\-specified implementations adds a pointer to a configuration structure as first parameter to all functions\&.
.PP
The generated source code uses the type
\fBcrc_t\fR, which is used throughout the code\&. It may be redefined in the generated header file\&.
.SS "Fully parametrised models"
.PP
The prototypes of these functions are normally generated by pycrc using the
\fI\-\-generate h\fR
option\&. The prototypes of the
.sp
.ft B
.nf
#include <stdlib\&.h>
/* pycrc will define the appropriate type
* when generating the header file\&. */
typedef XXXX crc_t;
.fi
.ft
.HP \w'crc_t\ crc_init('u
.BI "crc_t crc_init(void);"
.HP \w'crc_t\ crc_update('u
.BI "crc_t crc_update(crc_t\ " "crc" ", const\ unsigned\ char\ *" "data" ", size_t\ " "data_len" ");"
.HP \w'crc_t\ crc_finalize('u
.BI "crc_t crc_finalize(crc_t\ " "crc" ");"
.PP
The following code snippet shows how to use the generated functions\&.
.sp
.if n \{\
.RS 4
.\}
.nf
#include "pycrc_generated_crc\&.h"
#include <stdio\&.h>
int main(void)
{
static const unsigned char str1[] = "1234";
static const unsigned char str2[] = "56789";
crc_t crc;
crc = crc_init();
crc = crc_update(crc, str1, sizeof(str1) \- 1);
crc = crc_update(crc, str2, sizeof(str2) \- 1);
// more calls to crc_update\&.\&.\&.
crc = crc_finalize(crc);
printf("0x%lx\en", (long)crc);
return 0;
}
.fi
.if n \{\
.RE
.\}
.sp
.SS "Models with runtime\-configurable parameters"
.PP
When the model is not fully defined then the missing parameters are contained in a structure of type
\fBcrc_cfg_t\fR\&. The first argument of the CRC functions is a pointer to that structure, and its fields must be initialised properly by the user before the first call to the CRC functions\&. This structure contains three additional parameters,
\fImsb_mask\fR,
\fIcrc_mask\fR
and
\fIcrc_shift\fR, if the
\fIWidth\fR
was undefined when the code was generated\&.
.sp
.if n \{\
.RS 4
.\}
.nf
typedef struct {
unsigned int width;
crc_t poly;
bool reflect_in;
crc_t xor_in;
bool reflect_out;
crc_t xor_out;
// internal parameters
crc_t msb_mask; // initialise as 1UL << (cfg\->width \- 1)
crc_t crc_mask; // initialise as (cfg\->msb_mask \- 1) | cfg\->msb_mask
unsigned int crc_shift; // initialise as cfg\->width < 8 ? 8 \- cfg\->width : 0
} crc_cfg_t;
.fi
.if n \{\
.RE
.\}
.PP
\fImsb_mask\fR
is a bitmask with the most significant bit of a
\fIWidth\fR
bits wide data type set to 1\&.
\fIcrc_mask\fR
is a bitmask with all bits of a
\fIWidth\fR
bits wide data type set to 1\&.
\fIcrc_shift\fR
is a shift counter that is used when
\fIWidth\fR
is less than 8\&. It is the number of bits to shift the CRC register to align its top bit at a byte boundary\&.
.PP
The file
test/main\&.c
in the source package of pycrc contains a fully featured example of how to use the generated source code\&. A shorter, more compact
main()
function can be generated with the
\fI\-\-generate c\-main\fR
option\&. This second variant is the better option when some of the CRC parameters are known and some are unknown during code generation\&.
.SH "EXAMPLES"
.PP
.PP
Calculate the CRC\-32 checksum of the string 123456789:
.RS 4
\fBpython pycrc\&.py \-\-model crc\-32 \-\-check\-string 123456789\fR
.RE
.PP
Generate the source code of the table\-driven algorithm for an embedded application\&.
.RS 4
\fBpython pycrc\&.py \-\-model crc\-16 \-\-algorithm table\-driven \-\-table\-idx\-width 4 \-\-generate h \-o crc\&.h\fR
.sp
\fBpython pycrc\&.py \-\-model crc\-16 \-\-algorithm table\-driven \-\-table\-idx\-width 4 \-\-generate c \-o crc\&.c\fR
.sp
The table index width of 4 bits ensures a moderate memory consumption\&. In fact, the size of the resulting table is
16 * sizeof(crc_t)
bytes\&. A variant of the last generated output is the
\fIc\-main\fR
target: a simple
\fImain()\fR
function is generated in addition to the CRC routines:
.sp
\fBpython pycrc\&.py \-\-model crc\-16 \-\-algorithm table\-driven \-\-table\-idx\-width 4 \-\-generate c\-main \-o crc\&.c\fR
.RE
.PP
Generate the CRC table only:
.RS 4
\fBpython pycrc\&.py \-\-model kermit \-\-generate table \-o crc\-table\&.txt\fR
.RE
.SH "SEE ALSO"
.PP
The homepage of pycrc is
\m[blue]\fBhttp://www\&.tty1\&.net/pycrc/\fR\m[]\&.
.PP
For a long list of known CRC models, see Greg Cook\*(Aqs
\m[blue]\fBCatalogue of Parameterised CRC Algorithms\fR\m[]\&\s-2\u[3]\d\s+2\&.
.SH "COPYRIGHT"
.PP
This work is licensed under a
\m[blue]\fBCreative Commons Attribution\-Share Alike 3\&.0 Unported License\fR\m[]\&\s-2\u[4]\d\s+2\&.
.SH "AUTHOR"
.PP
\fBThomas Pircher\fR <\&tehpeh@gmx\&.net\&>
.RS 4
Author of pycrc and this manual page\&.
.RE
.SH "NOTES"
.IP " 1." 4
pycrc
.RS 4
\%http://www.tty1.net/pycrc/
.RE
.IP " 2." 4
A Painless Guide to CRC Error Detection Algorithms
.RS 4
\%http://www.ross.net/crc/crcpaper.html
.RE
.IP " 3." 4
Catalogue of Parameterised CRC Algorithms
.RS 4
\%http://regregex.bbcmicro.net/crc-catalogue.htm
.RE
.IP " 4." 4
Creative Commons Attribution-Share Alike 3.0 Unported License
.RS 4
\%http://creativecommons.org/licenses/by-sa/3.0/
.RE

247
pycrc/doc/pycrc.html Normal file
View file

@ -0,0 +1,247 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pycrc</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /></head><body><div class="refentry" title="pycrc"><a id="pycrc"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>pycrc — a free, easy to use Cyclic Redundancy Check (CRC) calculator and source code generator.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">pycrc</code> [OPTIONS]</p></div></div><div class="refsect1" title="Description"><a id="idp66576"></a><h2>Description</h2><p>
<a class="ulink" href="http://www.tty1.net/pycrc/" target="_top">pycrc</a>
provides a parametrised CRC reference implementation written in Python and a source code generator for C.
The generated C source code can be optimised for simplicity, speed or tight memory constraints for embedded platforms.
The following operations are implemented:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
generate the checksum of a string (ASCII or hex)
</p></li><li class="listitem"><p>
generate the checksum of a file
</p></li><li class="listitem"><p>
generate the C header and source files for a client implementation.
</p></li></ul></div><p>
</p><p>
The following variants of the CRC algorithm are supported:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
<em class="replaceable"><code>bit-by-bit</code></em>: the basic algorithm which operates individually on every bit of the augmented message
(i.e. the input data with <em class="replaceable"><code>Width</code></em> 0-bits attached to the end).
This algorithm is the easiest to understand because it is a straightforward implementation of the basic polynomial division,
but it is also the slowest among all possible variants.
</p></li><li class="listitem"><p>
<em class="replaceable"><code>bit-by-bit-fast</code></em>: a variation of the simple <em class="replaceable"><code>bit-by-bit</code></em> algorithm,
with the difference that it does not need to augment the data, i.e. it does not add <em class="replaceable"><code>Width</code></em> zero
bits at the end of the message.
This algorithm might be a good choice for embedded platforms, where code space is a major concern.
</p></li><li class="listitem"><p>
<em class="replaceable"><code>table-driven</code></em>: the standard table driven algorithm.
This is the fastest variant because it operates on one byte at a time, as opposed to bits, and uses a look-up table of 256 elements,
which might not be feasible for small embedded systems, though. Anyway, the number of elements in the look-up table can be reduced by
means of the <code class="option">--table-idx-width</code> command line switch. By using 4 bits (16 elements in the look-up table) a significant
speed-up can be measured with respect to the bit-by-bit algorithms.
</p></li></ul></div><p>
</p></div><div class="refsect1" title="Options"><a id="idp80400"></a><h2>Options</h2><div class="variablelist"><dl><dt><span class="term">
<code class="option">--version</code>
</span></dt><dd><p>show program's version number and exit</p></dd><dt><span class="term">
<code class="option">-h</code>
, </span><span class="term">
<code class="option">--help</code>
</span></dt><dd><p>show this help message and exit</p></dd><dt><span class="term">
<code class="option">--verbose</code>
</span></dt><dd><p>be more verbose; in particular, print the value of the parameters and the chosen model</p></dd><dt><span class="term">
<code class="option">--check-string=</code><em class="replaceable"><code>STRING</code></em>
</span></dt><dd><p>calculate the checksum of the given string ('<em class="replaceable"><code>123456789</code></em>' default)</p></dd><dt><span class="term">
<code class="option">--check-hexstring=</code><em class="replaceable"><code>STRING</code></em>
</span></dt><dd><p>calculate the checksum of the given hexadecimal string</p></dd><dt><span class="term">
<code class="option">--check-file=</code><em class="replaceable"><code>FILE</code></em>
</span></dt><dd><p>calculate the checksum of the given file</p></dd><dt><span class="term">
<code class="option">--generate=</code><em class="replaceable"><code>CODE</code></em>
</span></dt><dd><p>generate the source code type as a choice from {c, h, c-main, table}</p></dd><dt><span class="term">
<code class="option">--std=</code><em class="replaceable"><code>STD</code></em>
</span></dt><dd><p>C standard style of the generated code from {C89, ANSI, C99}</p></dd><dt><span class="term">
<code class="option">--algorithm=</code><em class="replaceable"><code>ALGO</code></em>
</span></dt><dd><p>choose an algorithm from {<em class="replaceable"><code>bit-by-bit</code></em>, <em class="replaceable"><code>bit-by-bit-fast</code></em>,
<em class="replaceable"><code>table-driven</code></em>, <em class="replaceable"><code>all</code></em>}</p></dd><dt><span class="term">
<code class="option">--model=</code><em class="replaceable"><code>MODEL</code></em>
</span></dt><dd><p>choose a parameter set from
{<em class="replaceable"><code>crc-5</code></em>,
<em class="replaceable"><code>crc-8</code></em>,
<em class="replaceable"><code>dallas-1-wire</code></em>,
<em class="replaceable"><code>crc-12-3gpp</code></em>,
<em class="replaceable"><code>crc-15</code></em>,
<em class="replaceable"><code>crc-16</code></em>,
<em class="replaceable"><code>crc-16-usb</code></em>,
<em class="replaceable"><code>crc-16-modbus</code></em>,
<em class="replaceable"><code>crc-16-genibus</code></em>,
<em class="replaceable"><code>ccitt</code></em>,
<em class="replaceable"><code>r-crc-16</code></em>,
<em class="replaceable"><code>kermit</code></em>,
<em class="replaceable"><code>x-25</code></em>,
<em class="replaceable"><code>xmodem</code></em>,
<em class="replaceable"><code>zmodem</code></em>,
<em class="replaceable"><code>crc-24</code></em>,
<em class="replaceable"><code>crc-32</code></em>,
<em class="replaceable"><code>crc-32c</code></em>,
<em class="replaceable"><code>crc-32-mpeg</code></em>,
<em class="replaceable"><code>crc-32-bzip2</code></em>,
<em class="replaceable"><code>posix</code></em>,
<em class="replaceable"><code>jam</code></em>,
<em class="replaceable"><code>xfer</code></em>,
<em class="replaceable"><code>crc-64</code></em>,
<em class="replaceable"><code>crc-64-jones</code></em>,
<em class="replaceable"><code>crc-64-xz</code></em>}</p></dd><dt><span class="term">
<code class="option">--width=</code><em class="replaceable"><code>NUM</code></em>
</span></dt><dd><p>use <em class="replaceable"><code>NUM</code></em> bits in the <em class="replaceable"><code>Polynomial</code></em></p></dd><dt><span class="term">
<code class="option">--poly=</code><em class="replaceable"><code>HEX</code></em>
</span></dt><dd><p>use <em class="replaceable"><code>HEX</code></em> as <em class="replaceable"><code>Polynomial</code></em></p></dd><dt><span class="term">
<code class="option">--reflect-in=</code><em class="replaceable"><code>BOOL</code></em>
</span></dt><dd><p>reflect input bytes</p></dd><dt><span class="term">
<code class="option">--xor-in=</code><em class="replaceable"><code>HEX</code></em>
</span></dt><dd><p>use <em class="replaceable"><code>HEX</code></em> as initial value</p></dd><dt><span class="term">
<code class="option">--reflect-out=</code><em class="replaceable"><code>BOOL</code></em>
</span></dt><dd><p>reflect output bytes</p></dd><dt><span class="term">
<code class="option">--xor-out=</code><em class="replaceable"><code>HEX</code></em>
</span></dt><dd><p>xor the final CRC value with <em class="replaceable"><code>HEX</code></em></p></dd><dt><span class="term">
<code class="option">--table-idx-width=</code><em class="replaceable"><code>NUM</code></em>
</span></dt><dd><p>use <em class="replaceable"><code>NUM</code></em> bits to index the CRC table; <em class="replaceable"><code>NUM</code></em> must be one of the values
{<em class="replaceable"><code>1</code></em>, <em class="replaceable"><code>2</code></em>, <em class="replaceable"><code>4</code></em>, <em class="replaceable"><code>8</code></em>}</p></dd><dt><span class="term">
<code class="option">--symbol-prefix=</code><em class="replaceable"><code>STRING</code></em>
</span></dt><dd><p>when generating source code, use <em class="replaceable"><code>STRING</code></em> as prefix to the generated symbols</p></dd><dt><span class="term">
<code class="option">--crc-type=</code><em class="replaceable"><code>STRING</code></em>
</span></dt><dd><p>when generating source code, use <em class="replaceable"><code>STRING</code></em> as crc_t type</p></dd><dt><span class="term">
<code class="option">--include-file=</code><em class="replaceable"><code>FILE</code></em>
</span></dt><dd><p>when generating source code, include also <em class="replaceable"><code>FILE</code></em> as header file</p></dd><dt><span class="term">
<code class="option">-o</code><em class="replaceable"><code>FILE</code></em>
, </span><span class="term">
<code class="option">--output=</code><em class="replaceable"><code>FILE</code></em>
</span></dt><dd><p>write the generated code to <em class="replaceable"><code>FILE</code></em> instead to stdout</p></dd></dl></div></div><div class="refsect1" title="The CRC Parametric Model"><a id="idp170688"></a><h2>The CRC Parametric Model</h2><p>
The parametric model follows Ross N. Williams' convention described in
<a class="ulink" href="http://www.ross.net/crc/crcpaper.html" target="_top">A Painless Guide to CRC Error Detection Algorithms</a>,
commonly called the Rocksoft Model.
Since most people are familiar with this kind of parameters, pycrc follows this convention, described as follows:
</p><div class="glosslist"><dl><dt><em class="replaceable"><code>Width</code></em></dt><dd><p>
The width of the CRC <em class="replaceable"><code>Polynomial</code></em>, in number of bits. This is also the width of the final CRC result.
Previous versions of pycrc only multiples of 8 could be be used as <em class="replaceable"><code>Width</code></em> for the
<em class="replaceable"><code>table-driven</code></em> algorithm. As of version 0.7.5, any <em class="replaceable"><code>Width</code></em> is accepted
on all algorithms.
</p></dd><dt><em class="replaceable"><code>Polynomial</code></em></dt><dd><p>
The unreflected polynomial of the CRC algorithm.
</p><p>
The <em class="replaceable"><code>Polynomial</code></em> may be specified in its standard form, i.e. with bit <em class="replaceable"><code>Width</code></em>+1
set to 1, but the most significant bit may also be omitted. For example, for a <em class="replaceable"><code>Width</code></em> of 16,
both forms 0x18005 and 0x8005 are accepted.
</p></dd><dt><em class="replaceable"><code>ReflectIn</code></em></dt><dd><p>
Reflect the bytes of the message before processing them. A word is reflected by inverting the position of its bits with
respect to the middle axis of the word.
The reversed value of 0xa3 (10100010b) is 0x45 (01000101b), for example.
Some CRC algorithms can be implemented more efficiently in a bit reversed version.
</p><p>
Reflected algorithms are more efficient than straight-forward implementations, thus many of the standard algorithmic
variants use reflected input bytes.
</p></dd><dt><em class="replaceable"><code>XorIn</code></em></dt><dd><p>
The initial value (usually all 0 or all 1) in the algorithms which operate on the non-augmented message.
This value can be seen as a value which will be XOR-ed into the CRC register after <em class="replaceable"><code>Width</code></em>
iterations of the <em class="replaceable"><code>bit-by-bit</code></em> algorithm.
This means the simple <em class="replaceable"><code>bit-by-bit</code></em> algorithm must calculate the initial value using some sort of
reverse CRC algorithm on the <em class="replaceable"><code>XorIn</code></em> value.
</p></dd><dt><em class="replaceable"><code>ReflectOut</code></em></dt><dd><p>
Reflect the final CRC result. This operation takes place before XOR-ing the final CRC
value with the <em class="replaceable"><code>XorOut</code></em> parameter.
</p></dd><dt><em class="replaceable"><code>XorOut</code></em></dt><dd><p>
A value (usually all bits 0 or all 1) which will be XOR-ed to the final CRC value.
</p></dd><dt><em class="replaceable"><code>Check</code></em></dt><dd><p>
This value is not exactly a parameter of a model but it is sometimes given together with the Rocksoft Model parameters.
It is the CRC value of the parametrised model over the string "<em class="replaceable"><code>123456789</code></em>" and
may be used to validate an implementation.
</p></dd></dl></div><p>
</p></div><div class="refsect1" title="Code generation"><a id="idp203248"></a><h2>Code generation</h2><p>
In the default configuration, the generated code is strict ISO C99 code.
A minimal set of three functions are defined for each algorithm:
<code class="function">crc_init()</code>, <code class="function">crc_update()</code> and <code class="function">crc_finalize()</code>.
According to the number of parameters given to pycrc, a different interface definition is generated.
Fully parametrised models have a simpler API, while the generated code for runtime-specified implementations adds a
pointer to a configuration structure as first parameter to all functions.
</p><p>
The generated source code uses the type <span class="type">crc_t</span>, which is used throughout the code. It may be redefined in the generated header file.
</p><div class="refsect2" title="Fully parametrised models"><a id="idp206896"></a><h3>Fully parametrised models</h3><p>
The prototypes of these functions are normally generated by pycrc using the <em class="replaceable"><code>--generate h</code></em> option.
The prototypes of the
</p><div class="funcsynopsis"><pre class="funcsynopsisinfo">
#include &lt;stdlib.h&gt;
/* pycrc will define the appropriate type
* when generating the header file. */
typedef XXXX crc_t;
</pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">crc_t <strong>fsfunccrc_init</strong>(</code></td><td><code>void)</code>;</td><td> </td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">crc_t <strong>fsfunccrc_update</strong>(</code></td><td>crc_t <var class="pdparam">crc</var>, </td></tr><tr><td> </td><td>const unsigned char *<var class="pdparam">data</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">data_len</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">crc_t <strong>fsfunccrc_finalize</strong>(</code></td><td>crc_t <var class="pdparam">crc</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
The following code snippet shows how to use the generated functions.
</p><pre class="programlisting">
#include "pycrc_generated_crc.h"
#include &lt;stdio.h&gt;
int main(void)
{
static const unsigned char str1[] = "1234";
static const unsigned char str2[] = "56789";
crc_t crc;
crc = crc_init();
crc = crc_update(crc, str1, sizeof(str1) - 1);
crc = crc_update(crc, str2, sizeof(str2) - 1);
// more calls to crc_update...
crc = crc_finalize(crc);
printf("0x%lx\n", (long)crc);
return 0;
}
</pre><p>
</p></div><div class="refsect2" title="Models with runtime-configurable parameters"><a id="idp218176"></a><h3>Models with runtime-configurable parameters</h3><p>
When the model is not fully defined then the missing parameters are contained in a structure of
type <span class="type">crc_cfg_t</span>.
The first argument of the CRC functions is a pointer to that structure, and its fields must be initialised
properly by the user before the first call to the CRC functions.
This structure contains three additional parameters, <em class="parameter"><code>msb_mask</code></em>, <em class="parameter"><code>crc_mask</code></em>
and <em class="parameter"><code>crc_shift</code></em>, if the <em class="replaceable"><code>Width</code></em> was undefined when the code was generated.
</p><pre class="programlisting">
typedef struct {
unsigned int width;
crc_t poly;
bool reflect_in;
crc_t xor_in;
bool reflect_out;
crc_t xor_out;
// internal parameters
crc_t msb_mask; // initialise as 1UL &lt;&lt; (cfg-&gt;width - 1)
crc_t crc_mask; // initialise as (cfg-&gt;msb_mask - 1) | cfg-&gt;msb_mask
unsigned int crc_shift; // initialise as cfg-&gt;width &lt; 8 ? 8 - cfg-&gt;width : 0
} crc_cfg_t;
</pre><p>
</p><p>
<em class="parameter"><code>msb_mask</code></em> is a bitmask with the most significant bit of a <em class="replaceable"><code>Width</code></em> bits
wide data type set to 1.
<em class="parameter"><code>crc_mask</code></em> is a bitmask with all bits of a <em class="replaceable"><code>Width</code></em> bits
wide data type set to 1.
<em class="parameter"><code>crc_shift</code></em> is a shift counter that is used when <em class="replaceable"><code>Width</code></em> is less than 8.
It is the number of bits to shift the CRC register to align its top bit at a byte boundary.
</p><p>
The file <code class="filename">test/main.c</code> in the source package of pycrc contains a fully featured example
of how to use the generated source code.
A shorter, more compact <code class="code">main()</code> function can be generated with the <em class="replaceable"><code>--generate c-main</code></em>
option.
This second variant is the better option when some of the CRC parameters are known and some are unknown during code generation.
</p></div></div><div class="refsect1" title="Examples"><a id="idp228256"></a><h2>Examples</h2><p>
</p><div class="glosslist"><dl><dt>Calculate the CRC-32 checksum of the string 123456789:</dt><dd><p>
<strong class="userinput"><code>python pycrc.py --model crc-32 --check-string 123456789</code></strong>
</p></dd><dt>Generate the source code of the table-driven algorithm for an embedded application.</dt><dd><p>
<strong class="userinput"><code>python pycrc.py --model crc-16 --algorithm table-driven --table-idx-width 4 --generate h -o crc.h</code></strong>
</p><p>
<strong class="userinput"><code>python pycrc.py --model crc-16 --algorithm table-driven --table-idx-width 4 --generate c -o crc.c</code></strong>
</p><p>
The table index width of 4 bits ensures a moderate memory consumption.
In fact, the size of the resulting table is <code class="code">16 * sizeof(crc_t)</code> bytes.
A variant of the last generated output is the <em class="replaceable"><code>c-main</code></em> target:
a simple <em class="replaceable"><code>main()</code></em> function is generated in addition to the CRC routines:
</p><p>
<strong class="userinput"><code>python pycrc.py --model crc-16 --algorithm table-driven --table-idx-width 4 --generate c-main -o crc.c</code></strong>
</p></dd><dt>Generate the CRC table only:</dt><dd><p>
<strong class="userinput"><code>python pycrc.py --model kermit --generate table -o crc-table.txt</code></strong>
</p></dd></dl></div><p>
</p></div><div class="refsect1" title="See Also"><a id="idp239696"></a><h2>See Also</h2><p>
The homepage of pycrc is <a class="ulink" href="http://www.tty1.net/pycrc/" target="_top">http://www.tty1.net/pycrc/</a>.
</p><p>
For a long list of known CRC models, see Greg Cook's <a class="ulink" href="http://regregex.bbcmicro.net/crc-catalogue.htm" target="_top">Catalogue of Parameterised CRC Algorithms</a>.
</p></div><div class="refsect1" title="Copyright"><a id="idp242800"></a><h2>Copyright</h2><p>
This work is licensed under a
<a class="ulink" href="http://creativecommons.org/licenses/by-sa/3.0/" target="_top">Creative Commons Attribution-Share Alike 3.0 Unported License</a>.
</p></div></div></body></html>

582
pycrc/doc/pycrc.xml Normal file
View file

@ -0,0 +1,582 @@
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY program_name "pycrc">
<!ENTITY program_version "0.7.9">
<!ENTITY date "2011-11-19">
<!ENTITY author_firstname "Thomas">
<!ENTITY author_surname "Pircher">
<!ENTITY author_email "tehpeh@gmx.net">
<!ENTITY author "&author_firstname; &author_surname;">
<!ENTITY bit-by-bit "bit-by-bit">
<!ENTITY bit-by-bit-fast "bit-by-bit-fast">
<!ENTITY table-driven "table-driven">
<!ENTITY width "Width">
<!ENTITY poly "Polynomial">
<!ENTITY reflect_in "ReflectIn">
<!ENTITY xor_in "XorIn">
<!ENTITY reflect_out "ReflectOut">
<!ENTITY xor_out "XorOut">
<!ENTITY check "Check">
]>
<refentry id="&program_name;">
<refentryinfo>
<title>&program_name;</title>
<productname>&program_name;</productname>
<productnumber>&program_version;</productnumber>
<author>
<firstname>&author_firstname;</firstname>
<surname>&author_surname;</surname>
<contrib>Author of &program_name; and this manual page.</contrib>
<email>&author_email;</email>
</author>
<date>&date;</date>
</refentryinfo>
<refmeta>
<refentrytitle>&program_name;</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>
<refnamediv>
<refname>&program_name;</refname>
<refpurpose>a free, easy to use Cyclic Redundancy Check (CRC) calculator and source code generator.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>&program_name;</command>
<arg>OPTIONS</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<ulink url="http://www.tty1.net/pycrc/">&program_name;</ulink>
provides a parametrised CRC reference implementation written in Python and a source code generator for C.
The generated C source code can be optimised for simplicity, speed or tight memory constraints for embedded platforms.
The following operations are implemented:
<itemizedlist>
<listitem>
<para>
generate the checksum of a string (ASCII or hex)
</para>
</listitem>
<listitem>
<para>
generate the checksum of a file
</para>
</listitem>
<listitem>
<para>
generate the C header and source files for a client implementation.
</para>
</listitem>
</itemizedlist>
</para>
<para>
The following variants of the CRC algorithm are supported:
<itemizedlist>
<listitem>
<para>
<replaceable>&bit-by-bit;</replaceable>: the basic algorithm which operates individually on every bit of the augmented message
(i.e. the input data with <replaceable>&width;</replaceable> 0-bits attached to the end).
This algorithm is the easiest to understand because it is a straightforward implementation of the basic polynomial division,
but it is also the slowest among all possible variants.
</para>
</listitem>
<listitem>
<para>
<replaceable>&bit-by-bit-fast;</replaceable>: a variation of the simple <replaceable>&bit-by-bit;</replaceable> algorithm,
with the difference that it does not need to augment the data, i.e. it does not add <replaceable>&width;</replaceable> zero
bits at the end of the message.
This algorithm might be a good choice for embedded platforms, where code space is a major concern.
</para>
</listitem>
<listitem>
<para>
<replaceable>&table-driven;</replaceable>: the standard table driven algorithm.
This is the fastest variant because it operates on one byte at a time, as opposed to bits, and uses a look-up table of 256 elements,
which might not be feasible for small embedded systems, though. Anyway, the number of elements in the look-up table can be reduced by
means of the <option>--table-idx-width</option> command line switch. By using 4 bits (16 elements in the look-up table) a significant
speed-up can be measured with respect to the bit-by-bit algorithms.
</para>
</listitem>
</itemizedlist>
</para>
</refsect1>
<refsect1><title>Options</title>
<variablelist>
<varlistentry>
<term>
<option>--version</option>
</term>
<listitem>
<para>show program's version number and exit</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-h</option>
</term>
<term>
<option>--help</option>
</term>
<listitem>
<para>show this help message and exit</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--verbose</option>
</term>
<listitem>
<para>be more verbose; in particular, print the value of the parameters and the chosen model</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--check-string=</option><replaceable>STRING</replaceable>
</term>
<listitem>
<para>calculate the checksum of the given string ('<replaceable>123456789</replaceable>' default)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--check-hexstring=</option><replaceable>STRING</replaceable>
</term>
<listitem>
<para>calculate the checksum of the given hexadecimal string</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--check-file=</option><replaceable>FILE</replaceable>
</term>
<listitem>
<para>calculate the checksum of the given file</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--generate=</option><replaceable>CODE</replaceable>
</term>
<listitem>
<para>generate the source code type as a choice from {c, h, c-main, table}</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--std=</option><replaceable>STD</replaceable>
</term>
<listitem>
<para>C standard style of the generated code from {C89, ANSI, C99}</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--algorithm=</option><replaceable>ALGO</replaceable>
</term>
<listitem>
<para>choose an algorithm from {<replaceable>bit-by-bit</replaceable>, <replaceable>bit-by-bit-fast</replaceable>,
<replaceable>table-driven</replaceable>, <replaceable>all</replaceable>}</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--model=</option><replaceable>MODEL</replaceable>
</term>
<listitem>
<para>choose a parameter set from
{<replaceable>crc-5</replaceable>,
<replaceable>crc-8</replaceable>,
<replaceable>dallas-1-wire</replaceable>,
<replaceable>crc-12-3gpp</replaceable>,
<replaceable>crc-15</replaceable>,
<replaceable>crc-16</replaceable>,
<replaceable>crc-16-usb</replaceable>,
<replaceable>crc-16-modbus</replaceable>,
<replaceable>crc-16-genibus</replaceable>,
<replaceable>ccitt</replaceable>,
<replaceable>r-crc-16</replaceable>,
<replaceable>kermit</replaceable>,
<replaceable>x-25</replaceable>,
<replaceable>xmodem</replaceable>,
<replaceable>zmodem</replaceable>,
<replaceable>crc-24</replaceable>,
<replaceable>crc-32</replaceable>,
<replaceable>crc-32c</replaceable>,
<replaceable>crc-32-mpeg</replaceable>,
<replaceable>crc-32-bzip2</replaceable>,
<replaceable>posix</replaceable>,
<replaceable>jam</replaceable>,
<replaceable>xfer</replaceable>,
<replaceable>crc-64</replaceable>,
<replaceable>crc-64-jones</replaceable>,
<replaceable>crc-64-xz</replaceable>}</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--width=</option><replaceable>NUM</replaceable>
</term>
<listitem>
<para>use <replaceable>NUM</replaceable> bits in the <replaceable>&poly;</replaceable></para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--poly=</option><replaceable>HEX</replaceable>
</term>
<listitem>
<para>use <replaceable>HEX</replaceable> as <replaceable>&poly;</replaceable></para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--reflect-in=</option><replaceable>BOOL</replaceable>
</term>
<listitem>
<para>reflect input bytes</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--xor-in=</option><replaceable>HEX</replaceable>
</term>
<listitem>
<para>use <replaceable>HEX</replaceable> as initial value</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--reflect-out=</option><replaceable>BOOL</replaceable>
</term>
<listitem>
<para>reflect output bytes</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--xor-out=</option><replaceable>HEX</replaceable>
</term>
<listitem>
<para>xor the final CRC value with <replaceable>HEX</replaceable></para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--table-idx-width=</option><replaceable>NUM</replaceable>
</term>
<listitem>
<para>use <replaceable>NUM</replaceable> bits to index the CRC table; <replaceable>NUM</replaceable> must be one of the values
{<replaceable>1</replaceable>, <replaceable>2</replaceable>, <replaceable>4</replaceable>, <replaceable>8</replaceable>}</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--symbol-prefix=</option><replaceable>STRING</replaceable>
</term>
<listitem>
<para>when generating source code, use <replaceable>STRING</replaceable> as prefix to the generated symbols</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--crc-type=</option><replaceable>STRING</replaceable>
</term>
<listitem>
<para>when generating source code, use <replaceable>STRING</replaceable> as crc_t type</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--include-file=</option><replaceable>FILE</replaceable>
</term>
<listitem>
<para>when generating source code, include also <replaceable>FILE</replaceable> as header file</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-o</option><replaceable>FILE</replaceable>
</term>
<term>
<option>--output=</option><replaceable>FILE</replaceable>
</term>
<listitem>
<para>write the generated code to <replaceable>FILE</replaceable> instead to stdout</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1><title>The CRC Parametric Model</title>
<para>
The parametric model follows Ross N. Williams' convention described in
<ulink url="http://www.ross.net/crc/crcpaper.html">A Painless Guide to CRC Error Detection Algorithms</ulink>,
commonly called the Rocksoft Model.
Since most people are familiar with this kind of parameters, &program_name; follows this convention, described as follows:
<glosslist>
<glossentry>
<glossterm><replaceable>&width;</replaceable></glossterm>
<glossdef>
<para>
The width of the CRC <replaceable>&poly;</replaceable>, in number of bits. This is also the width of the final CRC result.
Previous versions of &program_name; only multiples of 8 could be be used as <replaceable>&width;</replaceable> for the
<replaceable>&table-driven;</replaceable> algorithm. As of version 0.7.5, any <replaceable>&width;</replaceable> is accepted
on all algorithms.
</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm><replaceable>&poly;</replaceable></glossterm>
<glossdef>
<para>
The unreflected polynomial of the CRC algorithm.
</para>
<para>
The <replaceable>&poly;</replaceable> may be specified in its standard form, i.e. with bit <replaceable>&width;</replaceable>+1
set to 1, but the most significant bit may also be omitted. For example, for a <replaceable>&width;</replaceable> of 16,
both forms 0x18005 and 0x8005 are accepted.
</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm><replaceable>&reflect_in;</replaceable></glossterm>
<glossdef>
<para>
Reflect the bytes of the message before processing them. A word is reflected by inverting the position of its bits with
respect to the middle axis of the word.
The reversed value of 0xa3 (10100010b) is 0x45 (01000101b), for example.
Some CRC algorithms can be implemented more efficiently in a bit reversed version.
</para>
<para>
Reflected algorithms are more efficient than straight-forward implementations, thus many of the standard algorithmic
variants use reflected input bytes.
</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm><replaceable>&xor_in;</replaceable></glossterm>
<glossdef>
<para>
The initial value (usually all 0 or all 1) in the algorithms which operate on the non-augmented message.
This value can be seen as a value which will be XOR-ed into the CRC register after <replaceable>&width;</replaceable>
iterations of the <replaceable>&bit-by-bit;</replaceable> algorithm.
This means the simple <replaceable>&bit-by-bit;</replaceable> algorithm must calculate the initial value using some sort of
reverse CRC algorithm on the <replaceable>&xor_in;</replaceable> value.
</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm><replaceable>&reflect_out;</replaceable></glossterm>
<glossdef>
<para>
Reflect the final CRC result. This operation takes place before XOR-ing the final CRC
value with the <replaceable>&xor_out;</replaceable> parameter.
</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm><replaceable>&xor_out;</replaceable></glossterm>
<glossdef>
<para>
A value (usually all bits 0 or all 1) which will be XOR-ed to the final CRC value.
</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm><replaceable>&check;</replaceable></glossterm>
<glossdef>
<para>
This value is not exactly a parameter of a model but it is sometimes given together with the Rocksoft Model parameters.
It is the CRC value of the parametrised model over the string "<replaceable>123456789</replaceable>" and
may be used to validate an implementation.
</para>
</glossdef>
</glossentry>
</glosslist>
</para>
</refsect1>
<refsect1><title>Code generation</title>
<para>
In the default configuration, the generated code is strict ISO C99 code.
A minimal set of three functions are defined for each algorithm:
<function>crc_init()</function>, <function>crc_update()</function> and <function>crc_finalize()</function>.
According to the number of parameters given to &program_name;, a different interface definition is generated.
Fully parametrised models have a simpler API, while the generated code for runtime-specified implementations adds a
pointer to a configuration structure as first parameter to all functions.
</para>
<para>
The generated source code uses the type <type>crc_t</type>, which is used throughout the code. It may be redefined in the generated header file.
</para>
<refsect2><title>Fully parametrised models</title>
<para>
The prototypes of these functions are normally generated by &program_name; using the <replaceable>--generate h</replaceable> option.
The prototypes of the
</para>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;stdlib.h&gt;
/* &program_name; will define the appropriate type
* when generating the header file. */
typedef XXXX crc_t;
</funcsynopsisinfo>
<funcprototype>
<?dbhtml funcsynopsis-style='ansi'?>
<funcdef>crc_t <function>crc_init</function></funcdef>
<void/>
</funcprototype>
<funcprototype>
<?dbhtml funcsynopsis-style='ansi'?>
<funcdef>crc_t <function>crc_update</function></funcdef>
<paramdef>crc_t <parameter>crc</parameter></paramdef>
<paramdef>const unsigned char *<parameter>data</parameter></paramdef>
<paramdef>size_t <parameter>data_len</parameter></paramdef>
</funcprototype>
<funcprototype>
<?dbhtml funcsynopsis-style='ansi'?>
<funcdef>crc_t <function>crc_finalize</function></funcdef>
<paramdef>crc_t <parameter>crc</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The following code snippet shows how to use the generated functions.
<programlisting>
#include "&program_name;_generated_crc.h"
#include &lt;stdio.h&gt;
int main(void)
{
static const unsigned char str1[] = "1234";
static const unsigned char str2[] = "56789";
crc_t crc;
crc = crc_init();
crc = crc_update(crc, str1, sizeof(str1) - 1);
crc = crc_update(crc, str2, sizeof(str2) - 1);
// more calls to crc_update...
crc = crc_finalize(crc);
printf("0x%lx\n", (long)crc);
return 0;
}
</programlisting>
</para>
</refsect2>
<refsect2><title>Models with runtime-configurable parameters</title>
<para>
When the model is not fully defined then the missing parameters are contained in a structure of
type <type>crc_cfg_t</type>.
The first argument of the CRC functions is a pointer to that structure, and its fields must be initialised
properly by the user before the first call to the CRC functions.
This structure contains three additional parameters, <parameter>msb_mask</parameter>, <parameter>crc_mask</parameter>
and <parameter>crc_shift</parameter>, if the <replaceable>&width;</replaceable> was undefined when the code was generated.
<programlisting>
typedef struct {
unsigned int width;
crc_t poly;
bool reflect_in;
crc_t xor_in;
bool reflect_out;
crc_t xor_out;
// internal parameters
crc_t msb_mask; // initialise as 1UL &lt;&lt; (cfg-&gt;width - 1)
crc_t crc_mask; // initialise as (cfg-&gt;msb_mask - 1) | cfg-&gt;msb_mask
unsigned int crc_shift; // initialise as cfg-&gt;width &lt; 8 ? 8 - cfg-&gt;width : 0
} crc_cfg_t;
</programlisting>
</para>
<para>
<parameter>msb_mask</parameter> is a bitmask with the most significant bit of a <replaceable>&width;</replaceable> bits
wide data type set to 1.
<parameter>crc_mask</parameter> is a bitmask with all bits of a <replaceable>&width;</replaceable> bits
wide data type set to 1.
<parameter>crc_shift</parameter> is a shift counter that is used when <replaceable>&width;</replaceable> is less than 8.
It is the number of bits to shift the CRC register to align its top bit at a byte boundary.
</para>
<para>
The file <filename>test/main.c</filename> in the source package of &program_name; contains a fully featured example
of how to use the generated source code.
A shorter, more compact <code>main()</code> function can be generated with the <replaceable>--generate c-main</replaceable>
option.
This second variant is the better option when some of the CRC parameters are known and some are unknown during code generation.
</para>
</refsect2>
</refsect1>
<refsect1><title>Examples</title>
<para>
<glosslist>
<glossentry>
<glossterm>Calculate the CRC-32 checksum of the string 123456789:</glossterm>
<glossdef>
<para>
<userinput>python pycrc.py --model crc-32 --check-string 123456789</userinput>
</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Generate the source code of the table-driven algorithm for an embedded application.</glossterm>
<glossdef>
<para>
<userinput>python pycrc.py --model crc-16 --algorithm table-driven --table-idx-width 4 --generate h -o crc.h</userinput>
</para>
<para>
<userinput>python pycrc.py --model crc-16 --algorithm table-driven --table-idx-width 4 --generate c -o crc.c</userinput>
</para>
<para>
The table index width of 4 bits ensures a moderate memory consumption.
In fact, the size of the resulting table is <code>16 * sizeof(crc_t)</code> bytes.
A variant of the last generated output is the <replaceable>c-main</replaceable> target:
a simple <replaceable>main()</replaceable> function is generated in addition to the CRC routines:
</para>
<para>
<userinput>python pycrc.py --model crc-16 --algorithm table-driven --table-idx-width 4 --generate c-main -o crc.c</userinput>
</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Generate the CRC table only:</glossterm>
<glossdef>
<para>
<userinput>python pycrc.py --model kermit --generate table -o crc-table.txt</userinput>
</para>
</glossdef>
</glossentry>
</glosslist>
</para>
</refsect1>
<refsect1><title>See Also</title>
<para>
The homepage of &program_name; is <ulink url="http://www.tty1.net/pycrc/">http://www.tty1.net/pycrc/</ulink>.
</para>
<para>
For a long list of known CRC models, see Greg Cook's <ulink url="http://regregex.bbcmicro.net/crc-catalogue.htm">Catalogue of Parameterised CRC Algorithms</ulink>.
</para>
</refsect1>
<refsect1><title>Copyright</title>
<para>
This work is licensed under a
<ulink url="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution-Share Alike 3.0 Unported License</ulink>.
</para>
</refsect1>
</refentry>