[JiangheZhai]

Description

Add block-unaligned I/O support for Mooncake Store NVMe-oF replicas.

Previously, NoF operations required the logical object size, transfer size, and range offsets to be aligned to the NVMe namespace block size. This change separates the logical object size from the block-aligned physical allocation and I/O size.

Key changes:

• Round NoF allocations and physical I/O ranges up to the NVMe block size while preserving the original logical object size in replica metadata.
• Add SPDK SGL-based I/O using spdk_nvme_ns_cmd_readv() and spdk_nvme_ns_cmd_writev().
• Split registered buffers into DMA-accessible, physically contiguous SGL entries.
• Support block-unaligned writes by appending a zero-initialized DMA padding buffer without reading beyond the user buffer.
• Support block-unaligned NoF range reads by:
  • aligning the physical read range to LBA boundaries;
  • directing leading and trailing unwanted bytes into temporary discard buffers;
  • transferring the requested bytes directly into the destination buffer.
• Validate controller SGL support, DWORD alignment requirements, SGL lengths, address arithmetic, and LBA count conversions.
• Keep temporary padding and discard DMA buffers alive until asynchronous I/O completion.
• Propagate the NVMe block size through NoF registration, segment metadata, and replica descriptors.
• Reject NoF segments with inconsistent block sizes in the same segment pool.
• Add NoF ranged-read support to the Store client path.
• Add the verify_nof_unaligned benchmark scenario for validating unaligned Put/Get behavior.

NoF controllers used by this path must report SGL support. Controllers requiring DWORD-aligned SGL entries only accept addresses and lengths aligned to four bytes.

Module

• Transfer Engine (mooncake-transfer-engine)
• Mooncake Store (mooncake-store)
• Mooncake EP (mooncake-ep)
• Mooncake PG (mooncake-pg)
• Integration (mooncake-integration)
• P2P Store (mooncake-p2p-store)
• Python Wheel (mooncake-wheel)
• Common (mooncake-common)
• Mooncake RL (mooncake-rl)
• CI/CD
• Docs
• Other

Type of Change

• Bug fix
• New feature
• Refactor
• Breaking change
• Documentation update
• Performance improvement
• Other

How Has This Been Tested?

The change introduces the verify_nof_unaligned benchmark scenario to verify:

• writing an object whose logical size is not block-aligned;
• reading the complete logical object without exposing padding bytes;
• reading a range with an unaligned source offset;
• reading a range with unaligned head and tail boundaries;
• copying the requested range into a destination buffer with a non-zero offset;
• validating returned data against the original pattern.

The manual test requires an NVMe-oF controller that supports SGL.

Test commands:

./scripts/code_format.sh
pre-commit run --all-files

python3 mooncake-store/benchmarks/store_kv_bench.py \
  --scenario verify_nof_unaligned \
  --memory-replica-num 0 \
  --nof-replica-num 1 \
  --nof-block-size 4096 \
  --value-size 12300 \
  --range-src-offset 4 \
  --range-size 8228 \
  --range-dst-offset 4 \
  <NoF environment-specific arguments>

[LujhCoconut]

The alignment of NoF stems from earlier contributors coupling it with SPDK. We are currently considering a refactor of the NoF-related code to improve code quality and maintainability. Please refer to the discussions in the linked issue #3131.