wehub-resource-sync
77 lines
4.1 KiB
ReStructuredText
77 lines
4.1 KiB
ReStructuredText
Raw Block (Rust)
|
|
================
|
|
|
|
A built-in L2 adapter that stores KV objects in fixed-size slots on a raw block
|
|
device or pre-sized file using the Rust raw-device I/O bindings. It reuses the
|
|
existing raw-block metadata checkpoint model and writes directly into the
|
|
caller-provided load buffers during prefetch.
|
|
|
|
**Required fields:**
|
|
|
|
- ``device_path``: Raw device path or pre-sized file path.
|
|
- ``slot_bytes``: Fixed slot size in bytes. Must be aligned to ``block_align``.
|
|
|
|
**Optional fields:**
|
|
|
|
- ``capacity_bytes``: Optional cap on the usable device bytes. Default ``0``
|
|
means use the full device/file size.
|
|
- ``use_odirect``: ``true`` or ``false`` (default ``true``).
|
|
- ``block_align``: Device alignment in bytes (default ``4096``).
|
|
- ``header_bytes``: Per-slot header reservation (default ``4096``).
|
|
- ``meta_total_bytes``: Reserved metadata checkpoint region (default ``256MiB``).
|
|
- ``meta_magic`` / ``meta_version``: Metadata checkpoint identity/version knobs.
|
|
- ``meta_checkpoint_interval_sec`` / ``meta_idle_quiet_ms`` /
|
|
``meta_enable_periodic`` / ``meta_verify_on_load``: Checkpoint and recovery
|
|
controls carried over from the legacy raw-block backend.
|
|
- ``load_checkpoint_on_init``: Load an existing on-device metadata checkpoint
|
|
during startup (default ``true``). Set to ``false`` to start with an empty
|
|
in-memory index instead.
|
|
- ``enable_zero_copy``: Try aligned direct-buffer I/O when possible.
|
|
- ``io_engine``: Rust raw-block I/O engine. Valid values are ``"posix"``
|
|
(default synchronous ``pread``/``pwrite`` path), ``"io_uring"`` (direct Rust
|
|
io_uring syscall path).
|
|
- ``use_uring_cmd``: Enable NVMe passthrough via io_uring command interface
|
|
for direct device access. Requires ``io_engine="io_uring"`` and NVMe
|
|
character device node (e.g., ``/dev/ng0n1``).
|
|
- ``iouring_queue_depth``: Queue depth for ``io_engine="io_uring"``.
|
|
- ``max_data_transfer_size``: Maximum data transfer size for
|
|
``use_uring_cmd=true``. Large transfers are split into smaller chunks
|
|
that fit within device limits.
|
|
- ``num_store_workers`` / ``num_lookup_workers`` / ``num_load_workers``:
|
|
Worker-thread counts for each operation type.
|
|
|
|
**Notes:**
|
|
|
|
- ``raw_block`` is a server-owned MP adapter. It does **not** support
|
|
per-TP device-path mappings in MP mode.
|
|
- ``raw_block`` remains ``"type": "raw_block"`` for all supported engines.
|
|
- ``raw_block`` owns on-device slot allocation, checkpointing, and recovery
|
|
through ``RawBlockCore``. Slot reclamation is driven by the shared/global
|
|
L2 eviction controller or explicit ``delete()`` calls.
|
|
- If ``use_odirect`` is enabled, the server's ``--l1-align-bytes`` should be
|
|
at least ``block_align``.
|
|
- ``persist_enabled`` must remain ``true`` for this adapter.
|
|
- For ``use_uring_cmd=true``, ``device_path`` must use the NVMe character
|
|
device node (e.g., ``/dev/ng0n1``) instead of the block device node
|
|
(``/dev/nvme0n1``). The character device provides direct NVMe
|
|
command passthrough.
|
|
- ``use_uring_cmd`` requires ``io_engine="io_uring"`` to be set.
|
|
- When ``use_uring_cmd=true``, ``use_odirect`` is ignored for NVMe namespace
|
|
character devices.
|
|
|
|
**Configuration examples:**
|
|
|
|
.. code-block:: bash
|
|
|
|
# Basic raw_block with posix I/O
|
|
--l2-adapter '{"type": "raw_block", "device_path": "/dev/nvme0n1", "slot_bytes": 1048576, "block_align": 4096, "header_bytes": 4096, "meta_total_bytes": 268435456, "use_odirect": true, "num_store_workers": 2, "num_lookup_workers": 1, "num_load_workers": 4}'
|
|
|
|
# With io_uring
|
|
--l2-adapter '{"type": "raw_block", "device_path": "/dev/nvme0n1", "slot_bytes": 1048576, "io_engine": "io_uring", "iouring_queue_depth": 256, "use_odirect": true}'
|
|
|
|
# With io_uring_cmd (NVMe passthrough)
|
|
--l2-adapter '{"type": "raw_block", "device_path": "/dev/ng0n1", "slot_bytes": 1048576, "io_engine": "io_uring", "use_uring_cmd": true, "iouring_queue_depth": 256, "max_data_transfer_size": 131072, "use_odirect": false}'
|
|
|
|
# With eviction
|
|
--l2-adapter '{"type": "raw_block", "device_path": "/dev/nvme0n1", "slot_bytes": 1048576, "load_checkpoint_on_init": false, "eviction": {"eviction_policy": "LRU", "trigger_watermark": 0.9, "eviction_ratio": 0.1}}'
|