crcglot 0.1.0__tar.gz

crcglot-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: crcglot
+Version: 0.1.0
+Summary: Verified CRC source-code for C, Rust, VHDL, Python — catalogue-driven, self-test embedded.
+Keywords: crc,checksum,code-generation,embedded,reveng,rocksoft,williams
+Author: Chuck Bass
+Author-email: Chuck Bass <chuck@acrocad.net>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/hucker/crcglot
+Project-URL: Repository, https://github.com/hucker/crcglot
+Project-URL: Issues, https://github.com/hucker/crcglot/issues
+Description-Content-Type: text/markdown
+
+# crcglot
+
+**Verified CRC source code for C, Rust, VHDL, and Python.**  Catalogue-driven, self-test embedded, multi-language by design.
+
+LLMs will gladly write you CRC code.  It might even be right.  `crcglot` guarantees the generated code matches the canonical [reveng catalogue](https://reveng.sourceforge.io/crc-catalogue/all.htm) test vector (`crc("123456789") == <check value>`) and ships a self-test you can run on your toolchain to prove it.
+
+## Quick start
+
+```bash
+pip install crcglot
+
+crcglot c crc32 --slice8 file=mycrc       # → mycrc.h + mycrc.c
+crcglot rust crc64-xz --slice8 > mycrc.rs
+crcglot vhdl crc32 > mycrc.vhd
+crcglot python crc16-modbus > mycrc.py
+
+crcglot list                              # browse the catalogue
+crcglot info crc32                        # show parameters
+```
+
+## 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 |
+
+C / Rust / VHDL ship `_self_test()` returning 0/1 (or boolean for VHDL).  Python verifies via the docstring's `check:` line — the same interpreter generated it.
+
+## Implementations
+
+| Flag | Description | Width support |
+| --- | --- | --- |
+| (default) bit-by-bit | Smallest code, zero RAM table, slowest | All |
+| `--table` | 256-entry lookup table, 4-8× faster | All |
+| `--slice8` | 8 lookup tables, 5-10× faster than `--table` | CRC-32 / CRC-64 only |
+
+Each generated file embeds the chosen implementation and the self-test.  In constrained embedded targets, standard toolchain flags (`-Wl,--gc-sections` for C, LTO for Rust) strip whatever you don't call.
+
+## Custom polynomials
+
+For algorithms not in the catalogue, pass Rocksoft/Williams parameters directly:
+
+```bash
+crcglot c --custom width=16 poly=0x1234 init=0xFFFF refin=true refout=true xorout=0x0000 file=mycustom
+```
+
+## 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`.
+
+## Acknowledgments
+
+CRC catalogue data is derived from Greg Cook's [reveng project](https://reveng.sourceforge.io/) — the canonical source for CRC algorithm parameters since 1999.
+
+## License
+
+MIT

crcglot-0.1.0/README.md

@@ -0,0 +1,59 @@
+# crcglot
+
+**Verified CRC source code for C, Rust, VHDL, and Python.**  Catalogue-driven, self-test embedded, multi-language by design.
+
+LLMs will gladly write you CRC code.  It might even be right.  `crcglot` guarantees the generated code matches the canonical [reveng catalogue](https://reveng.sourceforge.io/crc-catalogue/all.htm) test vector (`crc("123456789") == <check value>`) and ships a self-test you can run on your toolchain to prove it.
+
+## Quick start
+
+```bash
+pip install crcglot
+
+crcglot c crc32 --slice8 file=mycrc       # → mycrc.h + mycrc.c
+crcglot rust crc64-xz --slice8 > mycrc.rs
+crcglot vhdl crc32 > mycrc.vhd
+crcglot python crc16-modbus > mycrc.py
+
+crcglot list                              # browse the catalogue
+crcglot info crc32                        # show parameters
+```
+
+## 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 |
+
+C / Rust / VHDL ship `_self_test()` returning 0/1 (or boolean for VHDL).  Python verifies via the docstring's `check:` line — the same interpreter generated it.
+
+## Implementations
+
+| Flag | Description | Width support |
+| --- | --- | --- |
+| (default) bit-by-bit | Smallest code, zero RAM table, slowest | All |
+| `--table` | 256-entry lookup table, 4-8× faster | All |
+| `--slice8` | 8 lookup tables, 5-10× faster than `--table` | CRC-32 / CRC-64 only |
+
+Each generated file embeds the chosen implementation and the self-test.  In constrained embedded targets, standard toolchain flags (`-Wl,--gc-sections` for C, LTO for Rust) strip whatever you don't call.
+
+## Custom polynomials
+
+For algorithms not in the catalogue, pass Rocksoft/Williams parameters directly:
+
+```bash
+crcglot c --custom width=16 poly=0x1234 init=0xFFFF refin=true refout=true xorout=0x0000 file=mycustom
+```
+
+## 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`.
+
+## Acknowledgments
+
+CRC catalogue data is derived from Greg Cook's [reveng project](https://reveng.sourceforge.io/) — the canonical source for CRC algorithm parameters since 1999.
+
+## License
+
+MIT

crcglot-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "crcglot"
+version = "0.1.0"
+description = "Verified CRC source-code for C, Rust, VHDL, Python — catalogue-driven, self-test embedded."
+license = "MIT"
+requires-python = ">=3.11"
+readme = "README.md"
+authors = [{name = "Chuck Bass", email = "chuck@acrocad.net"}]
+keywords = ["crc", "checksum", "code-generation", "embedded", "reveng", "rocksoft", "williams"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Code Generators",
+    "Topic :: Software Development :: Embedded Systems",
+]
+dependencies = []  # pure stdlib
+
+[project.scripts]
+crcglot = "crcglot.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/hucker/crcglot"
+Repository = "https://github.com/hucker/crcglot"
+Issues = "https://github.com/hucker/crcglot/issues"
+
+[build-system]
+requires = ["uv_build"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --cov=crcglot --cov-report=term-missing -n auto"
+markers = [
+    "slow: subprocess-spawning test (compiles + runs generated code via gcc / rustc / ghdl).  Skip with -m 'not slow' for fast iteration.",
+]
+
+[tool.coverage.run]
+source = ["src/crcglot"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "if __name__",
+    "pragma: no cover",
+]
+show_missing = true
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=7.0",
+    "pytest-xdist>=3.8",
+]

crcglot-0.1.0/src/crcglot/__init__.py

@@ -0,0 +1,62 @@
+"""crcglot -- multi-language CRC code generator.
+
+Generate ready-to-compile CRC source code in C, Rust, VHDL, or Python
+for any of 64+ named algorithms (reveng catalogue) or any custom
+Rocksoft/Williams polynomial.  Three implementation shapes per target:
+bit-by-bit (smallest), table-driven (4-8x faster), and slice-by-8
+(another 5-10x faster, CRC-32/64 only).
+
+Public API:
+    - CRC_CATALOGUE: dict of named algorithm parameters.
+    - generate_c, generate_python, generate_rust, generate_vhdl:
+      name-lookup generators.
+    - generate_c_from_entry, etc.: generate from a custom entry dict
+      (Rocksoft/Williams params without catalogue lookup).
+    - GENERATORS, GENERATORS_FROM_ENTRY: dicts of the two forms
+      keyed by language code, for parameterized callers.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from crcglot.c import generate_c, generate_c_from_entry
+from crcglot.catalogue import CRC_CATALOGUE, _generic_crc, _reflect
+from crcglot.python import generate_python, generate_python_from_entry
+from crcglot.rust import generate_rust, generate_rust_from_entry
+from crcglot.vhdl import generate_vhdl, generate_vhdl_from_entry
+
+
+# Language code -> name-lookup generator callable.
+GENERATORS: dict[str, Callable] = {
+    "c": generate_c,
+    "python": generate_python,
+    "rust": generate_rust,
+    "vhdl": generate_vhdl,
+}
+
+
+# Language code -> entry-dict generator callable (custom-params path).
+GENERATORS_FROM_ENTRY: dict[str, Callable] = {
+    "c": generate_c_from_entry,
+    "python": generate_python_from_entry,
+    "rust": generate_rust_from_entry,
+    "vhdl": generate_vhdl_from_entry,
+}
+
+
+__all__ = [
+    "CRC_CATALOGUE",
+    "GENERATORS",
+    "GENERATORS_FROM_ENTRY",
+    "_generic_crc",
+    "_reflect",
+    "generate_c",
+    "generate_c_from_entry",
+    "generate_python",
+    "generate_python_from_entry",
+    "generate_rust",
+    "generate_rust_from_entry",
+    "generate_vhdl",
+    "generate_vhdl_from_entry",
+]

crcglot-0.1.0/src/crcglot/_helpers.py

@@ -0,0 +1,124 @@
+"""Language-agnostic helpers shared by every target generator.
+
+Function-name sanitization, hex formatting, bit masks, and CRC table
+pre-computation are identical across Python / C / Rust / VHDL output
+because they're math, not syntax.  Each language module imports what
+it needs from here; per-language helpers (table formatters,
+self-test scaffolds, header builders) stay local to their target.
+
+Underscore-prefixed; the package's public API is ``__init__.py``.
+"""
+
+from __future__ import annotations
+
+from crcglot.catalogue import _reflect
+
+
+def _func_name(algo_name: str) -> str:
+    """Convert a CRC algorithm name into a valid identifier.
+
+    Algorithm names from the reveng catalogue use ``-`` and ``.``
+    which aren't valid in C / Python / Rust / VHDL identifiers;
+    swap them for underscores.  Same mangling is applied
+    consistently across all four target languages.
+    """
+    return algo_name.replace("-", "_").replace(".", "_")
+
+
+def _hex(value: int, width: int) -> str:
+    """Format an integer as a ``0xHEX`` literal sized for ``width`` bits.
+
+    The ``0x``-prefixed form is identical in C / Python / Rust source
+    (and acceptable in VHDL comments), so callers across all target
+    languages share this helper.  VHDL *code* uses :func:`_vhdl_lit`
+    from the vhdl module because hex literals there have a different
+    syntax for arithmetic contexts.
+    """
+    hex_w = (width + 3) // 4
+    return f"0x{value:0{hex_w}X}"
+
+
+def _mask(width: int) -> str:
+    """Format ``(1 << width) - 1`` as a hex literal of matching width."""
+    return _hex((1 << width) - 1, width)
+
+
+def _build_table(width: int, poly: int, refin: bool) -> list[int]:
+    """Pre-compute the 256-entry CRC lookup table for an algorithm.
+
+    Returns the table as a list of ``width``-bit integers, one per
+    possible byte value.  Caller renders this list to its target
+    language's array syntax via per-language formatters.
+
+    The reflected-input case uses the reflected polynomial and
+    right-shifts; the normal case left-shifts.  Both are textbook
+    Sarwate's algorithm.
+    """
+    table = []
+    if refin:
+        ref_poly = _reflect(poly, width)
+        for i in range(256):
+            crc = i
+            for _ in range(8):
+                if crc & 1:
+                    crc = (crc >> 1) ^ ref_poly
+                else:
+                    crc >>= 1
+            table.append(crc & ((1 << width) - 1))
+    else:
+        for i in range(256):
+            crc = i << (width - 8)
+            for _ in range(8):
+                if crc & (1 << (width - 1)):
+                    crc = (crc << 1) ^ poly
+                else:
+                    crc <<= 1
+                crc &= (1 << width) - 1
+            table.append(crc)
+    return table
+
+
+def _build_slice8_tables(
+    width: int, poly: int, refin: bool,
+) -> list[list[int]]:
+    """Pre-compute the 8 tables used by slice-by-8 CRC.
+
+    Returns ``[T0, T1, ..., T7]``: each Tk is a 256-entry list of
+    width-bit ints.  Tk[i] is the CRC of ``[i] + [0] * k`` -- i.e.
+    the contribution to the running CRC of a byte at position k.
+
+    The recurrence: ``T(k+1)[i] = T0[low_byte(Tk[i])] ^ shifted_rest(Tk[i])``
+    where the shift direction matches the polynomial direction.  This
+    is what powers Intel's slice-by-8 (5-10x throughput over standard
+    table-driven for CRC-32 / CRC-64 on big buffers).
+    """
+    mask = (1 << width) - 1
+    t0 = _build_table(width, poly, refin)
+    tables = [t0]
+    for _ in range(7):
+        prev = tables[-1]
+        nxt: list[int] = []
+        if refin:
+            # Reflected: low byte feeds next lookup, rest shifts right.
+            for i in range(256):
+                v = prev[i]
+                nxt.append((t0[v & 0xFF] ^ (v >> 8)) & mask)
+        else:
+            # Normal: high byte feeds next lookup, rest shifts left.
+            for i in range(256):
+                v = prev[i]
+                top = (v >> (width - 8)) & 0xFF
+                nxt.append((t0[top] ^ ((v << 8) & mask)) & mask)
+        tables.append(nxt)
+    return tables
+
+
+# Note: a Python reference for slice-by-8 was considered but dropped.
+# It would have served as a test oracle for the generated C / Rust
+# code, but Python doesn't benefit from slice-by-N at runtime (per-int
+# overhead eats the win), and using it as an oracle adds a third
+# implementation that itself needs verification.  Better verification:
+# generate both bit-by-bit and slice-by-8 in the target language,
+# compile both, run both on the same inputs, assert they agree.
+# Bit-by-bit is reveng-verified, so equivalence means slice-by-8 is
+# correct.  Tests live in tests/test_crc_codegen_exec.py.