Skip to content

A Python CRC library for calculation and C-code generation

License

Notifications You must be signed in to change notification settings

GardenTools/CrcEngine

Repository files navigation

https://img.shields.io/github/actions/workflow/status/GardenTools/CrcEngine/python-package.yml Documentation Status

CrcEngine

A python library for CRC calculation providing table-based as well as bit-bashing implementations (for reference).

Installing

CrcEngine can be installing using pip with

pip install crcengine

Usage

Pre-defined algorithms such as CRC32 are available. Tailored algorithms can be created by calling CrcEngine.create() and other related methods.

A calculation engine for a specific named algorithm can be obtained using CrcEngine.new(). Algorithms which are not pre-defined can be created using CrcEngine.create()

A list of pre-defined algorithms can be obtained using crcengine.algorithms_available()

>>> list(crcengine.algorithms_available())
['crc8', 'crc8-autosar', 'crc8-bluetooth', 'crc8-ccitt', 'crc8-gsm-b', 'crc8-sae-j1850', 'crc15-can', 'crc16-kermit', 'crc16-ccitt-true', 'crc16-xmodem', 'crc16-autosar', 'crc16-ccitt-false', 'crc16-cdma2000', 'crc16-ibm', 'crc16-modbus', 'crc16-profibus', 'crc24-flexray16-a', 'crc24-flexray16-b', 'crc32', 'crc32-bzip2', 'crc32-c', 'crc64-ecma']

Built-in algorithms

crc8, crc8-autosar, crc8-bluetooth, crc8-ccitt, crc8-gsm-b, crc8-sae-j1850, crc15-can, crc16-kermit, crc16-ccitt-true, crc16-xmodem, crc16-autosar, crc16-ccitt-false, crc16-cdma2000, crc16-ibm, crc16-modbus, crc16-profibus, crc24-flexray16-a, crc24-flexray16-b, crc32, crc32-bzip2, crc32-c, crc64-ecma

Examples

Using a pre-defined algorithm

import crcengine
crc_algorithm = crcengine.new('crc32-bzip2')
result = crc_algorithm(b'123456789')
print('CRC=0x{:08x}'.format(result))

Output: > CRC=0xfc891918

Defining an algorithm

import crcengine
params = crcengine.CrcParams(0x864cfb, 24, 0xb704ce, reflect_in=False, reflect_out=False, xor_out=0)
crc_openpgp = crcengine.create_from_params(params)
# this is equivalent to
crc_openpgp = crcengine.create(params=params)
# invocation
result = crc_openpgp(b'123456789')
print(f'CRC=0x{result:08x}')

When using create() params must be passed as a keyword parameter, since the function also accepts polynomial and seed parameters for backwards compatibility.

Code Generation

The library can generate C code for a given table-algorithm. The code produced is intended to be a reasonable compromise between size, complexity and speed without requiring allocation of memory for table generation at runtime.

Faster implementations of specific algorithms can be achieved in software which unroll loops and pipeline the operations different bytes to introduce parallelism in the calculation see intel_soft_src for example. Some processors also include instructions specifically for crc calculation.

Code Generation Example usage:

Generating code into a directory named "out" by passing CRC parameters

params = crcengine.get_algorithm_params('crc32')
crcengine.generate_code(params, 'out/')

or referencing the algorithm by name

crcengine.generate_code('crc16-xmodem', 'out/')

Downloading

Running the tests

Tests can be performed directly by executing pytest in the "tests" directory

Running the Codegen tests

The codegen tests make use of ceedling which is expected to be installed as a ruby gem. The unit tests are configured to compile with gcc.


With thanks to Greg Cook for providing such a thoroughly collated list of CRC definitions