crcglot 0.4.0

Verified CRC source-code for C, C#, Go, Python, Rust, VHDL, and Zig — catalogue-driven, typed introspection API, self-test embedded.

crcglot

Verified CRC source code for C, Rust, VHDL, Python, Go, C#, and Zig. Catalogue-driven, self-test embedded, multi-language by design. Pure-stdlib package — zero runtime dependencies.

LLMs will gladly write you CRC code. It might even be right. crcglot guarantees the generated code matches the canonical reveng catalogue test vector (crc("123456789") == <check value>) and ships a self-test you can run on your toolchain to prove it.

Quick start

pip install crcglot
crcglot c crc32 file=mycrc

That's it. You now have mycrc.h and mycrc.c — drop-in CRC-32 with a built-in _self_test() you can call to verify it matches the canonical reveng check value.

Different language? Swap c for python / rust / vhdl / go / csharp / zig. Different algorithm? Run crcglot list to browse all 71.

Or use it from Python code:

from crcglot import LANGUAGES
header, source = LANGUAGES["c"].generator("crc32")

Both surfaces are documented in detail below.

What you get per language

Function	Purpose
<fname>_init / _update / _finalize	Streaming triple — feed data chunk by chunk
<fname>	One-shot wrapper that calls the streaming triple
<fname>_self_test	Verify against the reveng check value on your toolchain

Every target ships _self_test(): C returns 0/1, Rust emits a #[cfg(test)] block discovered by cargo test, VHDL / Python / Go / C# / Zig return boolean / bool.

CLI reference

crcglot <command> [options...]

crcglot list [GLOB]

Browse the catalogue. Optional GLOB filters by shell-style pattern (e.g. crc16-*). Exit code 1 if nothing matches.

crcglot list                # all 71 algorithms
crcglot list 'crc32-*'      # just the CRC-32 family

crcglot info <name>

Print parameters (width, poly, init, refin, refout, xorout, check, desc) for one algorithm. Exit 1 on unknown name.

crcglot info crc64-xz

crcglot {c | csharp | go | python | rust | vhdl | zig} <algorithm> [options...] [tokens...]

Generate source code for the chosen target language.

Option / token	Effect
(default) bit-by-bit	Smallest code, zero RAM table, slowest. All widths.
--table	256-entry lookup table, 4-8× faster. All widths.
--slice8	8 lookup tables, 5-10× faster than --table. CRC-32 / CRC-64 only. C / Rust / Go / C# / Zig.
--custom	Use raw Rocksoft/Williams params instead of a catalogue lookup (see below).
file=STEM	Write to disk (extension picked per language; see below). Omit for stdout.
symbol=NAME	Override the emitted function name. Default: derived from algorithm, or from file=STEM if given.

File extensions per language: C emits STEM.h + STEM.c; Python .py; Rust .rs; VHDL .vhd; Go .go; C# .cs; Zig .zig.

Rules:

• --table and --slice8 are mutually exclusive (exit 2 if both given).
• --slice8 python silently falls back to --table (CPython's per-int overhead eats the slice-by-8 speedup; stderr warns).
• Without file=, output goes to stdout. For C, header is emitted first, then source.
• C / Rust / VHDL files embed <symbol>_self_test() returning 0 on success. In constrained embedded targets, standard toolchain flags (-Wl,--gc-sections for C, LTO for Rust) strip whatever you don't call.

--custom (raw Rocksoft/Williams parameters)

For algorithms not in the catalogue:

crcglot c --custom width=16 poly=0x1234 init=0xFFFF \
         refin=true refout=true xorout=0x0000 file=mycustom

Param	Required	Notes
width=N	yes	8, 16, 32, or 64 only
poly=X	yes	Hex (0x...) or decimal
init=X	no	Default 0. Hex or decimal.
refin=B	no	Default false. Accepts true/false/1/0/yes/no/on/off.
refout=B	no	Default false. Same boolean syntax.
xorout=X	no	Default 0.
name=NAME	no	Default crc_custom. Used in generated comments.
desc=TEXT	no	Free-form description in comments.

The check value for the custom parameters is computed automatically (_generic_crc(b"123456789", ...)) and embedded into the generated _self_test().

Catalogue

64+ algorithms covering everything from CRC-8 (ATM, AUTOSAR, Bluetooth, Maxim 1-Wire) through CRC-16 (Modbus, XMODEM, CCITT, IBM SDLC) through CRC-32 (Ethernet, bzip2, iSCSI, AUTOSAR) to CRC-64 (XZ, ECMA-182, NVMe, Redis). Browse with crcglot list.

Programmatic API

Two registries, both keyed by short code:

LANGUAGES — supported target languages

from crcglot import LANGUAGES

for code, info in LANGUAGES.items():
    print(code, info.extensions, sorted(info.variants))
    # → c       ('.h', '.c')  ['bitwise', 'slice8', 'table']
    # → csharp  ('.cs',)      ['bitwise', 'slice8', 'table']
    # → go      ('.go',)      ['bitwise', 'slice8', 'table']
    # → python  ('.py',)      ['bitwise', 'table']
    # → rust    ('.rs',)      ['bitwise', 'slice8', 'table']
    # → vhdl    ('.vhd',)     ['bitwise']
    # → zig     ('.zig',)     ['bitwise', 'slice8', 'table']

Each entry is a frozen LanguageInfo dataclass with:

• code — dispatch key ("c", "csharp", ...)
• extensions — file extension tuple ((".h", ".c") for C; single-element for the rest)
• variants — subset of {"bitwise", "table", "slice8"} that the generator accepts
• generator(name, ...) — name-lookup callable (returns source string, or (header, source) tuple for C)
• generator_from_entry(name, algo, ...) — bypass the catalogue with a custom AlgorithmInfo

ALGORITHMS — the reveng CRC catalogue

from crcglot import ALGORITHMS

modbus = ALGORITHMS["crc16-modbus"]
print(modbus.width, hex(modbus.check), modbus.desc)
# → 16 0x4b37 Modbus RTU serial protocol

# Filter to CRC-32 only.
crc32_family = [a for a in ALGORITHMS.values() if a.width == 32]

Each entry is a frozen AlgorithmInfo dataclass with the full Rocksoft / Williams parameter set: name, width, poly, init, refin, refout, xorout, check, desc.

Custom polynomials

from crcglot import AlgorithmInfo, LANGUAGES
from crcglot.catalogue import _generic_crc

# Compute the canonical check value for a custom poly.
check = _generic_crc(b"123456789", 16, 0x1234, 0xFFFF, True, True, 0x0000)

# Build an AlgorithmInfo and feed it to any generator.
algo = AlgorithmInfo(
    name="my_crc16", width=16, poly=0x1234, init=0xFFFF,
    refin=True, refout=True, xorout=0x0000, check=check,
    desc="My custom CRC-16",
)
code = LANGUAGES["rust"].generator_from_entry("my_crc16", algo, table=True)

Example output

See EXAMPLES.md for the actual generated source for crc32 across every language × implementation combination (C / Rust / Python / VHDL / Go / C# / Zig crossed with bit-by-bit, table-driven, and slice-by-8 where supported). Every block is reproducible with one CLI command.

Acknowledgments

CRC catalogue data is derived from Greg Cook's reveng project — the canonical source for CRC algorithm parameters since 1999.

License

MIT