Cyclic redundancy checks

Utilities for computing cyclic redundancy checks (CRCs) in software and in hardware.

CRCs are specified using the Algorithm class, which contains settings for CRC width, polynomial, initial value, input/output reflection, and output XOR. Many commonly used CRC algorithms are available in the catalog module, while most other CRC designs can be accommodated by manually constructing Algorithm.

Call the Algorithm with a data_width to obtain a Parameters class, which fully defines a CRC computation. The Parameters class provides the compute() method to perform software computations, and the create() method to create a hardware CRC module, Processor.

# Create a predefined CRC16-CCITT hardware module, using the default
# 8-bit data width (in other words, bytes).
from amaranth.lib.crc.catalog import CRC16_CCITT
crc = m.submodules.crc = CRC16_CCITT().create()

# Create a custom CRC algorithm, specify the data width explicitly,
# and use it to compute a CRC value in software.
from amaranth.lib.crc import Algorithm
algo = Algorithm(crc_width=16, polynomial=0x1021, initial_crc=0xffff,
                 reflect_input=False, reflect_output=False,
                 xor_output=0x0000)
assert algo(data_width=8).compute(b"123456789") == 0x29b1
class amaranth.lib.crc.Algorithm(*, crc_width, polynomial, initial_crc, reflect_input, reflect_output, xor_output)

Settings for a CRC algorithm, excluding data width.

The parameter set is based on the Williams model from “A Painless Guide to CRC Error Detection Algorithms”: http://www.ross.net/crc/download/crc_v3.txt

For a reference of standard CRC parameter sets, refer to:

  • reveng’s catalogue, which uses an identical parameterisation,

  • crcmod’s list of predefined functions, but remove the leading ‘1’ from the polynominal, XOR the “Init-value” with “XOR-out” to obtain initial_crc, and where “Reversed” is True, set both reflect_input and reflect_output to True,

  • CRC Zoo, which contains only polynomials; use the “explicit +1” form of polynomial but remove the leading ‘1’.

Many commonly used CRC algorithms are available in the catalog module, which includes all entries in the reveng catalogue.

To create a Parameters instance, call the Algorithm object with the required data width, which defaults to 8 bits.

Parameters:

  • crc_width (int) – Bit width of CRC word. Also known as “width” in the Williams model.

  • polynomial (int) – CRC polynomial to use, crc_width bits long, without the implicit x**crc_width term. Polynomial is always specified with the highest order terms in the most significant bit positions; use reflect_input and reflect_output to perform a least significant bit first computation.

  • initial_crc (int) – Initial value of CRC register at reset. Most significant bit always corresponds to the highest order term in the CRC register.

  • reflect_input (bool) – If True, the input data words are bit-reflected, so that they are processed least significant bit first.

  • reflect_output (bool) – If True, the output CRC is bit-reflected, so the least-significant bit of the output is the highest-order bit of the CRC register. Note that this reflection is performed over the entire CRC register; for transmission you may want to treat the output as a little-endian multi-word value, so for example the reflected 16-bit output 0x4E4C would be transmitted as the two octets 0x4C 0x4E, each transmitted least significant bit first.

  • xor_output (int) – The output CRC will be the CRC register XOR’d with this value, applied after any output bit-reflection.

__call__(data_width=8)

Constructs a Parameters instance from this Algorithm with the specified data_width.

Parameters:

data_width (int) – Bit width of data words, default 8.

class amaranth.lib.crc.Parameters(algorithm, data_width=8)

Full set of parameters for a CRC computation.

Contains the settings from Algorithm and additionally data_width. Refer to Algorithm for details of what each parameter means and how to construct them.

From this class, you can directly compute CRCs with the compute() method, or construct a hardware module with the create() method.

Parameters:

  • algorithm (Algorithm) – CRC algorithm to use. Specifies the CRC width, polynomial, initial value, whether to reflect the input or output words, and any output XOR.

  • data_width (int) – Bit width of data words.

property algorithm

Returns an Algorithm with the CRC settings from this instance.

residue()

Compute the residue value for this CRC, which is the value left in the CRC register after processing any valid codeword.

create()

Returns a Processor configured with these parameters.

compute(data)

Computes and returns the CRC of all data words in data.

Parameters:

data (iterable of integers) – The CRC is computed over this complete set of data. Each item is an integer of bitwidth equal to data_width.

class amaranth.lib.crc.Processor(*args, src_loc_at=0, **kwargs)

Cyclic redundancy check (CRC) processor module.

This module generates CRCs from an input data stream, which can be used to validate an existing CRC or generate a new CRC. It is configured by the Parameters class, which can handle most forms of CRCs. Refer to that class’s documentation for a description of the parameters.

The CRC value is updated on any clock cycle where valid is asserted, with the updated value available on the crc output on the subsequent clock cycle. The latency is therefore one clock cycle, and the throughput is one data word per clock cycle.

The CRC is reset to its initial value whenever start is asserted. start and valid may be asserted on the same clock cycle, in which case a new CRC computation is started with the current value of data.

With data_width=1, a classic bit-serial CRC is implemented for the given polynomial in a Galois-type shift register. For larger values of data_width, a similar architecture computes every new bit of the CRC in parallel.

The match_detected output may be used to validate data with a trailing CRC (also known as a codeword). If the most recently processed word(s) form the valid CRC of all the previous data since start was asserted, the CRC register will always take on a fixed value known as the residue. The match_detected output indicates whether the CRC register currently contains this residue.

Parameters:

parameters (Parameters) – CRC parameters.

Variables:

  • start (Signal(), in) – Assert to indicate the start of a CRC computation, re-initialising the CRC register to the initial value. May be asserted simultaneously with valid or by itself.

  • data (Signal(data_width), in) – Data word to add to CRC when valid is asserted.

  • valid (Signal(), in) – Assert when data is valid to add the data word to the CRC.

  • crc (Signal(crc_width), out) – Registered CRC output value, updated one clock cycle after valid becomes asserted.

  • match_detected (Signal(), out) – Asserted if the current CRC value indicates a valid codeword has been received.

The following pre-defined CRC algorithms are available: