Skip to content

docs: audit SIMD/scalar parity coverage across checksums crate#3393

Merged
oferchen merged 2 commits intomasterfrom
test/simd-scalar-parity-audit
Apr 26, 2026
Merged

docs: audit SIMD/scalar parity coverage across checksums crate#3393
oferchen merged 2 commits intomasterfrom
test/simd-scalar-parity-audit

Conversation

@oferchen
Copy link
Copy Markdown
Owner

Summary

  • Document the runtime CPU-feature dispatch ladder for every SIMD-accelerated checksum (rolling, MD4, MD5, SHA-256, CRC32C) directly in the relevant module rustdoc, so the supported AVX-512 -> AVX2 -> SSE4.1 -> SSSE3 -> SSE2 -> NEON -> scalar fallback chain is discoverable without grepping for is_x86_feature_detected!.
  • Add streaming-vs-one-shot parity tests for SHA-256 and CRC32C (16 KiB deterministic pseudo-random buffer + chunk-size sweep, plus RFC 3720 canonical vectors fed through the streaming wrapper for CRC32C) to guard against regressions in the streaming state machine that the existing one-shot vectors do not catch.
  • No runtime behaviour changes - purely additive rustdoc and tests.

Per-algorithm gap analysis

Algorithm Dispatch tiers documented Existing parity tests Gaps closed by this PR
Rolling AVX2 -> SSE2 -> NEON -> scalar rolling::tests::checksum::simd (lane sweeps, proptest, large inputs) Module rustdoc with dispatch table only - no test gap
MD4 AVX-512 -> AVX2 -> SSE2 -> NEON -> WASM -> scalar simd_parity_tests::md4_simd_parity (RFC 1320 + lane boundaries + proptest + 100 KiB inputs) Dispatch ladder + SSSE3/SSE4.1 reuse note only - no test gap
MD5 AVX-512 -> AVX2 -> SSE4.1 -> SSSE3 -> SSE2 -> NEON -> WASM -> scalar simd_parity_tests::md5_simd_parity (RFC 1321 + lane boundaries + proptest + 100 KiB inputs) Dispatch ladder only - no test gap
SHA-256 SHA-NI -> ARMv8 sha2 -> sha2-asm -> pure-Rust One-shot vectors + 1 KiB / 8 KiB streaming checks Added 16 KiB streaming/one-shot parity + chunk-size sweep
CRC32C x86_64 SSE4.2 -> aarch64 CRC -> software fallback Canonical one-shot vectors + 4 MiB streaming throughput Added 16 KiB streaming/one-shot parity + chunk-size sweep + canonical vectors via streaming API

Test plan

  • CI fmt + clippy
  • CI nextest (stable / Linux musl / macOS / Windows) - new tests run on every architecture and exercise whichever SIMD backend the host selects
  • CI interop validation

@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Apr 26, 2026
@oferchen oferchen force-pushed the test/simd-scalar-parity-audit branch from a5c172c to c2d9456 Compare April 26, 2026 03:48
@oferchen oferchen force-pushed the test/simd-scalar-parity-audit branch from c2d9456 to b1a2066 Compare April 26, 2026 09:58
Document the runtime CPU-feature dispatch ladder for every SIMD-accelerated
checksum (rolling, MD4, MD5, SHA-256, CRC32C) directly in the relevant
modules so the supported AVX-512 -> AVX2 -> SSE4.1 -> SSSE3 -> SSE2 -> NEON
-> scalar fallback chain is discoverable from rustdoc.

Add streaming/one-shot parity tests for SHA-256 and CRC32C: a 16 KiB
deterministic pseudo-random buffer and a chunk-size sweep, plus the
RFC 3720 canonical vectors fed through the streaming wrapper for CRC32C.
These guard against regressions in the streaming state machine that the
existing one-shot vectors do not catch. Rolling, MD4, and MD5 already have
exhaustive RFC + lane-boundary + proptest parity coverage and need no
additional tests.

No runtime behaviour changes - rustdoc and tests only.
The constants 2654435761 and 2246822519 exceed i32::MAX, so the implicit i32 inference from `0..N` fails type-check on `i.wrapping_mul(...)`. Annotate the range as `0u32..N` so the multiplier and result are unambiguous u32.
@oferchen oferchen force-pushed the test/simd-scalar-parity-audit branch from b1a2066 to 813f2c5 Compare April 26, 2026 10:46
@oferchen oferchen merged commit 34ebb14 into master Apr 26, 2026
40 of 41 checks passed
@oferchen oferchen deleted the test/simd-scalar-parity-audit branch April 26, 2026 12:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant