- Removed warning about even polynomials. As Lars Pötter rightly pointed out, polynomials may be even.
- Updated the generated code to cope with big Widths (>32 bits) on 32 bit processors.
- The table-driven code for polynomials of width < 8 using a table index width < 8 was producing a wrong checksum. Thanks to Radosław Gancarz.
- Fixed a typo in the documentation. Thanks to Andreas Nebenfuehr.
pycrc provides CRC reference implementations in Python and a C source code generator. The used CRC variant can be chosen from a fast but space-consuming implementation to slower but smaller versions especially suitable for embedded applications. The models can be freely chosen, and the collection of CRC models lists some of the most popular models by name. The following functions are implemented:
- calculate the checksum of a string or a file.
- generate the source files for a "C" implementation.
The following variants of the CRC algorithm are supported:
- bit-by-bit: 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: 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.
- bitwise-expression: calculates the CRC byte-wise using bit-wise expressions (such as binary and, not, xor, bit-shifts etc). This algorithm uses the same approach as the table-driven variant, but uses a logic operations instead of a look-up table. It is slightly slower than the table-driven algorithm, but without the overhead of a look-up table. This is an experimental feature and will in most cases result in a slower and bigger binary than any other algorithm. This option is only valid for code generation, not for checking strings or files. It can take a long time to generate the output for models with a big --width parameter. Use with care.
- table-driven: 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.
pycrc is released under the terms of the MIT licence.
If you like pycrc and you would like to give something back, then please see some ways how to say thanks.
The latest released version is:
- Remove obsolete and unused 'direct' parameter. Thanks to Matthias Urlichs.
- Don't recurse into main() when an unknown algorithm is selected. Thanks to Matthias Urlichs.
- Fixed a bug in the handling of hex strings in Python3. Thanks to Matthias Kuehlewein.
- The input to the CRC routines can now be bytes or strings.
- Re-organised the symbol table.
- Updated qm.py from https://github.com/tpircher/quine-mccluskey.
- Added the experimental bitwise-expression generator target.
- Allow to specify the --include option multiple times.
- Completely revisited and reworked the documentation.
- Allow to abbreviate the names of the algorithms.
- Minor documentation changes.
The bitwise-expression generator is an experimental feature, which might one day be almost as fast as the table-driven code but much smaller. At the moment the generated code is bigger and slower than any other algorithm, so use at your own risk.
Older news can be read in the pycrc news archive.
To Do ¶
pycrc is considered stable code. No new features are planned, but bugs are still fixed and new models added on request.
Who uses pycrc ¶
Companies, organisations or projects using pycrc:
- Google in their App Engine crc32 implementation
- GNU Radio in the GR_DECT module
- University of British Columbia, Canada
- Technische Universität Wien, Austria
- Microchip Technologies Inc.
- CSR plc.
- Cambridge Consultants
- digest-crc, a Cyclic Redundancy Check (CRC) library for Ruby.
CRC links ¶
- Ross N. Williams' Painless Guide to CRC Error Detection Algorithms is a very good starting point to understand CRC algorithms.
- The online CRC calculator has been heavily used in the early stage of pycrc. It is a very good place to test your CRC implementation and the C implementation on this site is worth studying.
- The Wikipedia-page on Cyclic redundancy check contains a rather scientific (i.e. dry) explanation of the matter, but the links on the bottom of the page are very useful.
- The Catalogue of parametrised CRC Algorithms by Greg Cook contains a lot of useful information about CRC variants.
- Terry Ritter's The Great CRC Mystery is another good place to study CRC algorithms.
- Sometimes the result of a CRC calculation is known but not the parameters. In that case Gregory Ewing's article Reverse-Engineering a CRC Algorithm comes handy. It outlines an algorithm how to get the CRC parameters from raw data. Greg Cook's Perl script CRC RevEng does a good job in finding the parameters from a few data points.
Other Free CRC tools ¶
- crc-generator is a Python module which calculates the CRC and generates C source code. (MIT licence)
- CrcMoose is another CRC Python module, able to generate a CRC of arbitrary models and it contains a long list of CRC models. (MIT licence)
- Universal Crc is a C program that generates fast C source code. It is noteworthy that it can generate a table-driven algorithm for polynomials which do not have to be 8-bit aligned. (GPL licence)
This project is hosted on and GitHub.