Livt packages

Livt.Utils

Version 1.1.1

Reusable Livt utility components, including configurable CRC helpers and CRC32.

Livt.Utils

Livt.Utils provides small reusable utility components for Livt hardware packages. It is intended for practical helpers that are broadly useful but do not belong in Livt.Base, Livt.IO, Livt.Math, Livt.Crypto, or a more specific domain package.

Version 1.1.1 provides:

  • Livt.Utils.Hashing.Crc: generic bit/byte CRC helpers with compile-time width, polynomial and bit-order configuration; see CRC contracts.
  • Livt.Utils.Hashing.Crc32: CRC32 checksum component using the IEEE 802.3 / zlib reflected polynomial 0xEDB88320.

📦 Package

[dependencies]
"Livt.Utils" = "1.1.1"

Version 1.1.1 publishes package discovery metadata, this README, the changelog, and the MIT license. Its component API is unchanged from 1.1.0.

Livt.Utils has no package dependencies. See CHANGELOG.md for release notes.

📚 Namespaces

Production components use a domain namespace below Livt.Utils. Tests mirror that shape below Livt.Utils.Tests.

Namespace Component Synthesizable Purpose
Livt.Utils.Hashing Crc Yes Combinational CRC updates; caller-owned state
Livt.Utils.Hashing Crc32 Yes CRC32 checksum over 16-byte blocks

🔌 API Overview

Generic CRC

New in 1.1.0, Crc<WIDTH = 32, POLYNOMIAL = 0x04C11DB7, REFLECTED = true> provides combinational UpdateBit(), UpdateByte() and UpdateBits() helpers, plus Reflect() and Finalize(). Widths from 1 through 32 bits are supported. Supply the polynomial in normal notation without its leading term, including when selecting reflected processing.

The caller owns and initializes the accumulator. The component owns no clock, running state, lookup table or RAM. Initialization, final XOR and checksum byte order are explicit caller choices. The default specialization can calculate CRC-32/ISO-HDLC when seeded with 0xFFFFFFFF and finalized with XOR 0xFFFFFFFF and reverse = false.

Use Crc when the caller controls updates bit by bit or byte by byte; use Crc32 for the existing stateful 16-byte block interface. See the generic CRC guide for configuration and finalization rules.

CRC32

Crc32 follows the IEEE 802.3 / zlib CRC32 convention:

  • reflected polynomial: 0xEDB88320
  • initial accumulator: 0xFFFFFFFF
  • final XOR: 0xFFFFFFFF
  • check value: CRC32("123456789") = 0xCBF43926
  • output byte order: little-endian

The component processes data as full 16-byte blocks plus one final partial block:

  • BLOCK_SIZE = 16
  • Reset()
  • ProcessBlock(blk)
  • ProcessFinalBlock(blk, len)
  • GetCrc()
  • GetByte(idx)

Call Reset() before starting a computation. Call ProcessBlock() for each complete 16-byte block. Call ProcessFinalBlock() exactly once for the final 0..16 bytes; this applies the final XOR. Read the result with GetCrc() or GetByte(idx).

GetByte(0) returns the least-significant CRC byte and GetByte(3) returns the most-significant CRC byte. Crc32 returns byte 3 for GetByte(idx) when idx is outside 0..3.

🧪 Build and Test

livt test

The configured test list is defined in livt.toml. Usage examples live in docs/usage.md. Hardware notes live in docs/hardware-notes.md.

🛠️ Development Notes

  • Keep source components in a domain namespace below Livt.Utils.
  • Keep tests in the mirrored Livt.Utils.Tests.<Domain> namespace.
  • Keep utility components general-purpose and domain-neutral.
  • Move cryptographic primitives to Livt.Crypto.
  • Move arithmetic primitives to Livt.Math.
  • Move I/O and peripheral components to Livt.IO.
  • Document reproducible compiler issues in COMPILER.md.

🚧 Outlook

Future additions may include named CRC profile presets, Adler-32, Fletcher checksums, byte-order helpers, and other small utilities that are reusable across Livt packages. The generic Crc already supports configurable CRC16 and CRC32 polynomials, including CRC32C.

📄 License

This project is licensed under the MIT License. See LICENSE.