'\" t
.\"     Title: pycrc
.\"    Author: Thomas Pircher <tehpeh-web@tty1.net>
.\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
.\"      Date: 2017-08-11
.\"    Manual: pycrc
.\"    Source: pycrc 0.9.1
.\"  Language: English
.\"
.TH "PYCRC" "1" "2017\-08\-11" "pycrc 0.9.1" "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 C source code generator\&.
.SH "SYNOPSIS"
.HP \w'\fBpython\ pycrc\&.py\fR\ 'u
\fBpython pycrc\&.py\fR [OPTIONS]
.SH "DESCRIPTION"
.PP
\m[blue]\fBpycrc\fR\m[]\&\s-2\u[1]\d\s+2
is a CRC reference implementation in Python and a C source code generator for parametrised CRC models\&. The generated C source code can be optimised for simplicity, speed or small memory footprint, as required on small embedded systems\&. The following operations are implemented:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
calculate 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
.\}
calculate 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 header and source files for a C implementation\&.
.RE
.PP
pycrc supports the following variants of the CRC algorithm:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIbit\-by\-bit\fR
or
\fIbbb\fR: the basic algorithm which operates individually on every bit of the augmented message (i\&.e\&. the input data with
\fIWidth\fR
zero bits added at the end)\&. This algorithm is a straightforward implementation of the basic polynomial division and is the easiest one to understand, but it is also the slowest one 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
or
\fIbbf\fR: a variation of the simple
\fIbit\-by\-bit\fR
algorithm\&. This algorithm still iterates over every bit of the message, but does not augment it (does not add
\fIWidth\fR
zero bits at the end)\&. It gives the same result as the
\fIbit\-by\-bit\fR
method by carefully choosing the initial value of the algorithm\&. This method might be a good choice for embedded platforms, where code space is more important than execution speed\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fItable\-driven\fR
or
\fItbl\fR: the standard table driven algorithm\&. This is the fastest variant because it operates on one byte at a time, as opposed to one bit at the time\&. This method uses a look\-up table (usually of 256 elements), which might not be acceptable for small embedded systems\&. The number of elements in the look\-up table can be reduced with the
\fB\-\-table\-idx\-width\fR
command line switch\&. The value of 4 bits for the table index (16 elements in the look\-up table) can be a good compromise between execution speed and code size\&.
.sp
The
\fB\-\-slice\-by\fR
option enables a variant of the
\fItable\-driven\fR
algorithm that operates on 32 bits of data or more at a time rather than 8 bits\&. This can dramatically speed\-up the calculation of the CRC, at the cost of increased code and data size\&.
\fINote\fR: this option is experimental and not well\-tested\&. Check your results and please raise bugs if you find problems\&.
.RE
.sp
.SH "OPTIONS"
.PP
\fB\-\-version\fR
.RS 4
show the program 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 to
stdout\&.
.RE
.PP
\fB\-\-check\-string=\fR\fISTRING\fR
.RS 4
calculate the checksum of a string (default:
\(lq\fI123456789\fR\(rq)\&. If the string contains non\-ASCII characters then it will be UTF\-8 decoded\&.
.RE
.PP
\fB\-\-check\-hexstring=\fR\fISTRING\fR
.RS 4
calculate the checksum of a hexadecimal number string\&.
.RE
.PP
\fB\-\-check\-file=\fR\fIFILE\fR
.RS 4
calculate the checksum of a file\&. If the file contains non\-ASCII characters then it will be UTF\-8 decoded\&.
.RE
.PP
\fB\-\-generate=\fR\fICODE\fR
.RS 4
generate C source code; choose the type from {\fIh\fR,
\fIc\fR,
\fIc\-main\fR,
\fItable\fR}\&.
.RE
.PP
\fB\-\-std=\fR\fISTD\fR
.RS 4
specify the C dialect 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,
\fIbbb\fR,
\fIbit\-by\-bit\-fast\fR,
\fIbbf\fR,
\fItable\-driven\fR,
\fItbl\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,
\fIcrc\-16\-ccitt\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 the octets in the input message\&.
.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 the resulting checksum before applying the XorOut value\&.
.RE
.PP
\fB\-\-xor\-out=\fR\fIHEX\fR
.RS 4
xor the final CRC value with
\fIHEX\fR\&.
.RE
.PP
\fB\-\-slice\-by=\fR\fINUM\fR
.RS 4
speed\-up the table\-driven calculation by operating on
\fINUM\fR
octets of data rather than a single octet at a time\&.
\fINUM\fR
must be one of the values {\fI4\fR,
\fI8\fR,
\fI16\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\-\-force\-poly\fR
.RS 4
override any errors about possibly unsuitable polynoms\&. pycrc does not allow even polynoms or polynoms that are wider than Width\&. Use this option to override the error, if you know what you are doing\&.
.RE
.PP
\fB\-\-symbol\-prefix=\fR\fISTRING\fR
.RS 4
when generating source code, use
\fISTRING\fR
as prefix to the exported C 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\&. This option can be specified multiple times\&.
.RE
.PP
\fB\-o\fR\fIFILE\fR, \fB\-\-output=\fR\fIFILE\fR
.RS 4
write the generated code to
\fIFILE\fR
instead of
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, often 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 number of significant bits in the CRC
\fIPolynomial\fR, excluding the most significant 1\&. This will also be the number of bits in the final CRC result\&. In previous versions of pycrc only multiples of 8 could be used as
\fIWidth\fR
for the
\fItable\-driven\fR
algorithm\&. As of version 0\&.7\&.5 any value is accepted for
\fIWidth\fR
for 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, both numbers 0x18005 and 0x8005 are accepted for a 16\-bit
\fIPolynomial\fR\&.
.sp
Most polynomials used in real world applications are odd (the least significant bit is 1), but there are some good even ones\&. pycrc allows the use of even polynomials with the
\fB\-\-force\-poly\fR
option\&. Some even polynomials may yield incorrect checksums depending on the used algorithm\&. Use at your own risk and if at all possible use a well\-known
\fIMODEL\fR
above\&.
.RE
.PP
\fIReflectIn\fR
.RS 4
Reflect the octets of the message before processing them\&.
.sp
A word is reflected or reversed by
\(lqflipping\(rq
its bits around the mid\-point of the word\&. The most significant bit of the word is moved to the least significant position, the second\-most significant bit is moved to the second\-least significant position and so on\&. The reflected value of 0xa2 (10100010b) is 0x45 (01000101b), for example\&.
.sp
Some CRC algorithms can be implemented more efficiently in a bit reversed version, that\*(Aqs why many of the standard CRC models use reflected input octets\&.
.RE
.PP
\fIXorIn\fR
.RS 4
The initial value (usually all 0 or all 1) for algorithms which operate on the non\-augmented message, that is, any algorithm other than the
\fIbit\-by\-bit\fR
one\&. This value can be interpreted as a value which will be XOR\-ed into the CRC register after
\fIWidth\fR
iterations of the
\fIbit\-by\-bit\fR
algorithm\&. This implies that 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
\(lq\fI123456789\fR\(rq
and can be used as a sanity check for a particular CRC implementation\&.
.RE
.SH "CODE GENERATION"
.PP
In the default configuration, the generated code is strict ISO C99\&. A minimal set of three functions are defined for each algorithm:
\fBcrc_init()\fR,
\fBcrc_update()\fR
and
\fBcrc_finalize()\fR\&. Depending on the number of parameters given to pycrc, a different interface will be defined\&. A fully parametrised model has a simpler API, while the generated code for a runtime\-specified implementation requires 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 to hold intermediate results and also the final CRC value\&. It is defined in the generated header file and its type may be overridden with the
\fB\-\-crc\-type\fR
option\&.
.SS "Fully parametrised models"
.PP
The prototypes of the CRC functions are normally generated by pycrc using the
\fI\-\-generate h\fR
option\&. The CRC functions for a fully parametrised model will look like:
.sp
.ft B
.nf
#include <stdlib\&.h>
typedef uint16_t crc_t;         /* pycrc will use an appropriate size here */
                
.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 code snippet below 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 stored in a structure of type
\fBcrc_cfg_t\fR\&. If a CRC function requires a value from the
\fBcrc_cfg_t\fR
structure, then the first function argument is always a pointer to that structure\&. All fields of the configuration structure must be properly initialised before the first call to any CRC function\&.
.PP
If the
\fIWidth\fR
was not specified when the code was generated, then the
\fBcrc_cfg_t\fR
structure will contain three more fields:
\fImsb_mask\fR,
\fIcrc_mask\fR
and
\fIcrc_shift\fR\&. They are defined for performance reasons and must be initialised to the value given next to the field definition\&.
.PP
For example, a completely undefined CRC implementation will generate a
\fBcrc_cfg_t\fR
structure as below:
.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 (crc_t)1u << (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 to 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 as it will always output valid code 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 \(lq123456789\(rq:
.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
The table index width of 4 bits ensures a moderate memory usage\&. To be precise, the size of the resulting table will be
16 * sizeof(crc_t)\&.
.sp
\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
A variant of the
\fIc\fR
target is
\fIc\-main\fR: this target will generate a simple
\fImain()\fR
function in addition to the CRC functions:
.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]\fBhttps://pycrc\&.org\fR\m[]\&.
.PP
A list of common CRC models is at
\m[blue]\fBhttps://pycrc\&.org/models\&.html\fR\m[]\&. 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\-ShareAlike 4\&.0 International\fR\m[]\&\s-2\u[4]\d\s+2\&.
.SH "AUTHOR"
.PP
\fBThomas Pircher\fR <\&tehpeh\-web@tty1\&.net\&>
.RS 4
Author of pycrc and this manual page\&.
.RE
.SH "NOTES"
.IP " 1." 4
pycrc
.RS 4
\%https://pycrc.org
.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://reveng.sourceforge.net/crc-catalogue/
.RE
.IP " 4." 4
Creative Commons Attribution-ShareAlike 4.0 International
.RS 4
\%https://creativecommons.org/licenses/by-sa/4.0/
.RE