Provided by: pycrc_0.10.0-2_all bug

NAME

       pycrc - a free, easy to use Cyclic Redundancy Check (CRC) calculator and C source code
       generator.

SYNOPSIS

       python pycrc.py [OPTIONS]

DESCRIPTION

       pycrc[1] 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:

       •   calculate the checksum of a string (ASCII or hex)

       •   calculate the checksum of a file

       •   generate the header and source files for a C implementation.

       pycrc supports the following variants of the CRC algorithm:

       •   bit-by-bit or bbb: the basic algorithm which operates individually on every bit of the
           augmented message (i.e. the input data with Width 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.

       •   bit-by-bit-fast or bbf: a variation of the simple bit-by-bit algorithm. This algorithm
           still iterates over every bit of the message, but does not augment it (does not add
           Width zero bits at the end). It gives the same result as the bit-by-bit 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.

       •   table-driven or tbl: 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 --table-idx-width 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.

           The --slice-by option enables a variant of the table-driven 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.  Note: this
           option is experimental and not well-tested. Check your results and please raise bugs
           if you find problems.

OPTIONS

       --version
           show the program version number and exit.

       -h, --help
           show this help message and exit.

       --verbose
           be more verbose; in particular, print the value of the parameters and the chosen model
           to stdout.

       --check-string=STRING
           calculate the checksum of a string (default: “123456789”). If the string contains
           non-ASCII characters then it will be UTF-8 decoded.

       --check-hexstring=STRING
           calculate the checksum of a hexadecimal number string.

       --check-file=FILE
           calculate the checksum of a file. If the file contains non-ASCII characters then it
           will be UTF-8 decoded.

       --generate=CODE
           generate C source code; choose the type from {h, c, c-main, table}.

       --std=STD
           specify the C dialect of the generated code from {C89, ANSI, C99}.

       --algorithm=ALGO
           choose an algorithm from {bit-by-bit, bbb, bit-by-bit-fast, bbf, table-driven, tbl,
           all}.

       --model=MODEL
           choose a parameter set from {crc-5, crc-8, dallas-1-wire, crc-12-3gpp, crc-15, crc-16,
           crc-16-usb, crc-16-modbus, crc-16-genibus, crc-16-ccitt, r-crc-16, kermit, x-25,
           xmodem, zmodem, crc-24, crc-32, crc-32c, crc-32-mpeg, crc-32-bzip2, posix, jam, xfer,
           crc-64, crc-64-jones, crc-64-xz}.

       --width=NUM
           use NUM bits in the Polynomial.

       --poly=HEX
           use HEX as Polynomial.

       --reflect-in=BOOL
           reflect the octets in the input message.

       --xor-in=HEX
           use HEX as initial value.

       --reflect-out=BOOL
           reflect the resulting checksum before applying the XorOut value.

       --xor-out=HEX
           xor the final CRC value with HEX.

       --slice-by=NUM
           speed-up the table-driven calculation by operating on NUM octets of data rather than a
           single octet at a time.  NUM must be one of the values {4, 8, 16}.

       --table-idx-width=NUM
           use NUM bits to index the CRC table; NUM must be one of the values {1, 2, 4, 8}.

       --force-poly
           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.

       --symbol-prefix=STRING
           when generating source code, use STRING as prefix to the exported C symbols.

       --crc-type=STRING
           when generating source code, use STRING as crc_t type.

       --include-file=FILE
           when generating source code, include also FILE as header file. This option can be
           specified multiple times.

       -oFILE, --output=FILE
           write the generated code to FILE instead of stdout.

THE CRC PARAMETRIC MODEL

       The parametric model follows Ross N. Williams' convention described in A Painless Guide to
       CRC Error Detection Algorithms[2], often called the Rocksoft Model. Since most people are
       familiar with this kind of parameters, pycrc follows this convention, described as
       follows:

       Width
           The number of significant bits in the CRC Polynomial, 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 Width for the table-driven algorithm. As
           of version 0.7.5 any value is accepted for Width for all algorithms.

       Polynomial
           The unreflected polynomial of the CRC algorithm.

           The Polynomial may be specified in its standard form, i.e. with bit Width+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 Polynomial.

           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 --force-poly 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
           MODEL above.

       ReflectIn
           Reflect the octets of the message before processing them.

           A word is reflected or reversed by “flipping” 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.

           Some CRC algorithms can be implemented more efficiently in a bit reversed version,
           that's why many of the standard CRC models use reflected input octets.

       XorIn
           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 bit-by-bit one. This
           value can be interpreted as a value which will be XOR-ed into the CRC register after
           Width iterations of the bit-by-bit algorithm. This implies that the simple bit-by-bit
           algorithm must calculate the initial value using some sort of reverse CRC algorithm on
           the XorIn value.

       ReflectOut
           Reflect the final CRC result. This operation takes place before XOR-ing the final CRC
           value with the XorOut parameter.

       XorOut
           A value (usually all bits 0 or all 1) which will be XOR-ed to the final CRC value.

       Check
           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 “123456789” and can be used as a sanity check for a particular CRC
           implementation.

CODE GENERATION

       In the default configuration, the generated code is strict ISO C99. A minimal set of three
       functions are defined for each algorithm: crc_init(), crc_update() and crc_finalize().
       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.

       The generated source code uses the type crc_t, 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 --crc-type option.

   Fully parametrised models
       The prototypes of the CRC functions are normally generated by pycrc using the --generate h
       option. The CRC functions for a fully parametrised model will look like:

       #include <stdlib.h>
       typedef uint16_t crc_t;         /* pycrc will use an appropriate size here */

       crc_t crc_init(void);

       crc_t crc_update(crc_t crc, const unsigned char *data, size_t data_len);

       crc_t crc_finalize(crc_t crc);

       The code snippet below shows how to use the generated functions.

           #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\n", (long)crc);
               return 0;
           }

   Models with runtime-configurable parameters
       When the model is not fully defined then the missing parameters are stored in a structure
       of type crc_cfg_t. If a CRC function requires a value from the crc_cfg_t 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.

       If the Width was not specified when the code was generated, then the crc_cfg_t structure
       will contain three more fields: msb_mask, crc_mask and crc_shift. They are defined for
       performance reasons and must be initialised to the value given next to the field
       definition.

       For example, a completely undefined CRC implementation will generate a crc_cfg_t structure
       as below:

           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;

       msb_mask is a bitmask with the most significant bit of a Width bits wide data type set to
       1.  crc_mask is a bitmask with all bits of a Width bits wide data type set to 1.
       crc_shift is a shift counter that is used when Width is less than 8. It is the number of
       bits to shift the CRC register to align its top bit to a byte boundary.

       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 --generate c-main 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.

EXAMPLES

       Calculate the CRC-32 checksum of the string “123456789”:
           python pycrc.py --model crc-32 --check-string 123456789

       Generate the source code of the table-driven algorithm for an embedded application.
           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).

           python pycrc.py --model crc-16 --algorithm table-driven --table-idx-width 4 --generate
           h -o crc.h

           python pycrc.py --model crc-16 --algorithm table-driven --table-idx-width 4 --generate
           c -o crc.c

           A variant of the c target is c-main: this target will generate a simple main()
           function in addition to the CRC functions:

           python pycrc.py --model crc-16 --algorithm table-driven --table-idx-width 4 --generate
           c-main -o crc.c

       Generate the CRC table only:
           python pycrc.py --model kermit --generate table -o crc-table.txt

SEE ALSO

       The homepage of pycrc is https://pycrc.org.

       A list of common CRC models is at https://pycrc.org/models.html. For a long list of known
       CRC models, see Greg Cook's Catalogue of Parameterised CRC Algorithms[3].

COPYRIGHT

       This work is licensed under a Creative Commons Attribution-ShareAlike 4.0
       International[4].

AUTHOR

       Thomas Pircher <tehpeh-web@tty1.net>
           Author of pycrc and this manual page.

NOTES

        1. pycrc
           https://pycrc.org

        2. A Painless Guide to CRC Error Detection Algorithms
           http://www.ross.net/crc/crcpaper.html

        3. Catalogue of Parameterised CRC Algorithms
           http://reveng.sourceforge.net/crc-catalogue/

        4. Creative Commons Attribution-ShareAlike 4.0 International
           https://creativecommons.org/licenses/by-sa/4.0/