# ocaml-crc — CRC checksums for OCaml

Fast, portable CRC checksums with optional hardware acceleration.

## Algorithms

| Algorithm | Polynomial | Init | Reflect | XOR Out | Check (`"123456789"`) | Standard |
|-----------|-----------|------|---------|---------|----------------------|----------|
| CRC-16-CCITT | 0x1021 | 0xFFFF | No | None | 0x29B1 | ITU-T V.41, CCSDS FECF |
| CRC-16-X.25 | 0x1021 | 0xFFFF | Yes | 0xFFFF | 0x906E | ITU-T X.25, RFC 9171 |
| CRC-32 | 0xEDB88320 | 0xFFFFFFFF | Yes | 0xFFFFFFFF | 0xCBF43926 | ISO 3309, ITU-T V.42 |
| CRC-32C | 0x82F63B78 | 0xFFFFFFFF | Yes | 0xFFFFFFFF | 0xE3069283 | RFC 3720 (iSCSI) |

## Performance

Three implementation tiers, selected automatically:

| Tier | Strategy | CRC-32C throughput | When |
|------|----------|-------------------|------|
| Hardware | SSE4.2 / ARM CRC intrinsics | ~15-30 GB/s | x86_64 with SSE4.2, aarch64 |
| Slicing-by-8 | 8 x 256-entry tables | ~1-4 GB/s | Software fallback (native, jsoo, wasm) |
| Byte-at-a-time | 256-entry table | ~300 MB/s | CRC-16 variants |

Hardware detection follows the mirage-crypto pattern: compile-time flag
gating via dune-configurator + runtime CPUID check. On x86_64, SSE4.2
accelerates CRC-32C; on ARM, both CRC-32 and CRC-32C use hardware
instructions. The software slicing-by-8 path is always available as
fallback and is the default on js_of_ocaml and wasm_of_ocaml targets.

```ocaml
# Crc.has_hardware_crc;;
- : bool = true
```

## Usage

```ocaml
let () =
  let data = "Hello, world!" in
  Printf.printf "CRC-16-CCITT: 0x%04X\n" (Crc.crc16_ccitt data);
  Printf.printf "CRC-16-X.25:  0x%04X\n" (Crc.crc16_x25 data);
  Printf.printf "CRC-32:       0x%08X\n" (Crc.crc32 data);
  Printf.printf "CRC-32C:      0x%08X\n" (Crc.crc32c data)
```

Sub-range variants for bytes buffers:

```ocaml
let () =
  let buf = Bytes.of_string "Hello, world!" in
  Printf.printf "Hello:  0x%04X\n" (Crc.crc16_ccitt_bytes buf 0 5);
  Printf.printf "world!: 0x%08X\n" (Crc.crc32c_bytes buf 7 6)
```

## Installation

Install with opam:

<!-- $MDX skip -->
```sh
$ opam install nox-crc
```

If opam cannot find the package, it may not yet be released in the public
`opam-repository`. Add the overlay repository, then install it:

<!-- $MDX skip -->
```sh
$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install nox-crc
```

## Portability

All CRC-32 variants use `Int32` arithmetic internally, ensuring correct
results on both 64-bit native OCaml and 32-bit targets (js_of_ocaml,
wasm_of_ocaml). The C stubs for hardware acceleration are optional:
without them, the pure OCaml slicing-by-8 path is used automatically.

## Test vectors

All check values are verified against standard test vectors from ITU-T
V.41, ISO 3309, and RFC 3720 Section 12.1. Property-based fuzz tests
(Crowbar/AFL) verify string/bytes agreement, output ranges, self-check
residues, and determinism.

## License

ISC