perf(umbp): hardware CRC-32C and direct I/O for the SSD tier

[TianDi101]

Extracts three self-contained pieces of SSD-tier work from a larger pure-SSD branch onto main. Nothing from that branch's pure-SSD mode, multi-drive sharding, hugepage staging, UMBP_SSD_TIMING instrumentation or UMBP_SSD_DURABILITY knob is included here.

1. Hardware CRC-32C (9573db2)

segment::CrcUpdate was a bitwise, table-less CRC-32/ISO-HDLC — 8 shift/XOR per byte, ~152 MB/s on one core — run over every byte of every record on both read and write. On the SSD tier the checksum, not the drive, set the ceiling.

Replaced with CRC-32C via the SSE4.2 crc32 instruction, __builtin_cpu_supports runtime dispatch, and a byte-identical portable table fallback. The fallback is a correctness requirement, not just portability: a segment written on a host with hardware support must verify on one without, so both paths are pinned to the same reflected polynomial (0x82F63B78). ~152 MB/s → ~13.4 GB/s. No -msse4.2 on the translation unit.

Also splits segment::Writer::Prepare into Build (checksum + record assembly) and Reserve (index reservation). SSDTier runs Build outside mu_ and only Reserve under it, so a write batch no longer blocks concurrent reads on the same drive for its whole CRC + copy time. Critical section 908 ms → 0.04 ms.

2. Startup truncate guard (d499c03)

A segment whose head the scanner cannot parse silently swallows every subsequent write: the scanner stops at the first unreadable header, but write_offset comes from the file size, so the writer appends past the junk. Next open, the scanner stops in the same place — everything written in between is gone, permanently.

Nothing upstream catches this. PeerSsdManager::DiscardLeftoverOnStartup only wipes when Capacity() reports used > 0, and a scan that broke at offset 0 reports used == 0 — so it logs "no SSD leftover" and skips the wipe. It surfaces as a 0% SSD hit rate with no error anywhere.

The record-format changes in this PR make a stale directory exactly this case, which is why the fix ships alongside them. It is kept as a separate commit so it can be reverted independently.

3. Direct I/O (f45be75)

The SSD tier is itself a cache, so buffered I/O gives it a second, unmanaged DRAM cache underneath: reads are served from the page cache at many times device bandwidth, the node reports DRAM it is actually consuming as free, and any measurement of drive behaviour is meaningless — a "1 drive vs 2 drives" comparison can show no difference simply because neither run touched a drive. ssd.direct_io=true (UMBP_SSD_DIRECT_IO=1) bypasses it.

O_DIRECT requires buffer address, file offset and length to all be alignment multiples, which the old layout satisfied for none of the three. Hence record layout v3, padded to a fixed kRecordAlign of 4096: [header|key|pad][value|pad]. A fixed constant rather than the device's reported requirement, so a directory keeps its meaning when it moves between devices. Padding is unconditional, so one directory is readable with either setting — only the reader's buffer alignment differs.

Supporting pieces: AlignedBuffer (posix_memalign-backed, zeroes padding so it cannot leak heap contents to the device); a startup probe that round-trips one aligned block rather than trusting a capability bit, catching tmpfs/overlayfs and coarser-alignment devices, falling back to buffered with a warning rather than failing to come up; and a bounce path for unaligned read destinations — the exception rather than the rule, but required, because without it the failure is an EINVAL the per-key fallback would just repeat, surfacing as a silent 100% miss.

Compatibility

kRecordVersion 1 → 3. Old records fail the scanner's pre-existing version check and are dropped; this tier is a cache, so its contents are always re-fetchable. No multi-version read support is included, by design.

Capacity is now charged in padded bytes — a 512 B value occupies 8192 B once prefix and value are each padded. Honest accounting of what the device gives up, but a 16× change for small values; worth knowing before this meets a small-KV workload.

ssd.segment_size_bytes must now be a multiple of 4096, or the append cursor lands unaligned at segment roll-over. Validate() rejects it up front rather than failing at the first direct write.

Two knobs come with direct I/O because they are needed to interpret its results: ssd.verify_crc isolates checksum cost from storage cost (records written with it off carry kFlagNoCrc and stay readable by a reader with it on), and ssd.tier_io_threads fans the tier's CPU-bound phases over 4 workers by default, matching the DRAM tier's read_threads_/write_threads_ so a DRAM-vs-SSD comparison does not silently measure 4 threads against 1. Both defaults are behaviour-neutral.

Testing

Full umbp ctest: 38/41. The 3 failures are the pre-existing no active RDMA device container limitation, thrown in SetUp() before any tier code runs.

• test_segment_crc (new) pins the standard CRC-32C check value 0xE3069283, which also catches an accidental revert to ISO-HDLC (check value 0xCBF43926); verifies the selected path against an independent bitwise reference at every tail length mod 8 and at unaligned starts; checks streaming composition and Build/Reserve generation stamping.
• test_ssd_direct_io (new) covers layout invariants, AlignedBuffer, a buffered/direct round trip against both aligned and unaligned destinations (so both the direct and the bounce path), the verify_crc=false round trip, thread-count invariance, and padded capacity accounting. Confirmed running with the probe genuinely active, not silently falling back to buffered.
• test_ssd_tier gains a case for the stale segment head. Verified it fails without the guard commit — the second key is unreadable after restart — so it pins the actual regression rather than passing vacuously.

🤖 Generated with Claude Code