raw_block io_uring_cmd 구현 (PR #3274)

[!tldr] 업무 관점 takeaway LMCache raw_block 백엔드에 NVMe io_uring_cmd passthrough 경로가 추가됐다. Block Layer를 완전히 우회해 NVMe 드라이버에 직접 명령을 보낸다. 핵심은 NvmeUringCmd.cdw13의 dspec 필드 — 여기에 FDP placement_id를 넣으면 NVMe 레벨에서 데이터 배치 스트림이 지정된다. 즉 이 PR이 FDP Backend의 배관을 완성한다. 그리고 builder() 패턴 도입으로 M3(io_uring setup flag 튜닝)의 착수점도 된다.

---

PR 개요

항목	내용
PR	#3274
작성자	Ankit Kumar (@ankit-sam)
상태	Open (리뷰 중)
요약	MP 모드 통합 rebase 중 누락된 io_uring 코드 복구 + NVMe io_uring_cmd passthrough 신규 추가

---

I/O 경로 비교

기존 io_uring:
  App → io_uring (SQE 64B) → Block Layer → NVMe Driver → SSD

io_uring_cmd (이 PR):
  App → io_uring_cmd (big SQE 128B) → NVMe Driver → SSD
                                            ↑
                                     Block Layer 완전 생략

---

Rust 변경사항 (lib.rs)

IoUringWrapper — 커널 버전 호환성 추상화

#[derive(Clone)]
enum IoUringWrapper {
    Standard(Arc<Mutex<IoUring<SqueueEntry, Entry>>>),  // 커널 5.4~5.18
    Big(Arc<Mutex<IoUring<Entry128, Entry32>>>),         // 커널 5.19+
}

타입	SQE 크기	CQE 크기	필요 커널	용도
Standard	64 bytes	16 bytes	5.4+	일반 pread/pwrite
Big	128 bytes	32 bytes	5.19+	io_uring_cmd (NVMe passthrough)

NVMe 명령 구조체(80 bytes)를 SQE에 inline으로 담으려면 128-byte SQE가 필수.

초기화 — Big 먼저 시도, 실패 시 Standard fallback:

let ring = match IoUring::<Entry128, Entry32>::builder()
    .build(iouring_queue_depth as u32)
{
    Ok(big_ring) => IoUringWrapper::Big(Arc::new(Mutex::new(big_ring))),
    Err(_) => {
        if use_uring_cmd {
            return Err(PyRuntimeError::new_err(
                "io_uring_cmd requires kernel 5.19 or later",
            ));
        }
        // fallback: Standard
        IoUringWrapper::Standard(Arc::new(Mutex::new(std_ring)))
    }
};

M3 착수점: .build() 앞에 .setup_single_issuer().setup_defer_taskrun() 등을 추가하는 게 M3의 핵심. Big/Standard 두 경로 모두에 적용해야 한다.

---

NvmeUringCmd — NVMe 명령 구조체

#[repr(C)]
#[derive(Debug, Clone, Copy)]
struct NvmeUringCmd {
    opcode: u8,      // NVME_IO_READ(0x02) / NVME_IO_WRITE(0x01)
    flags: u8,
    rsvd1: u16,
    nsid: u32,       // NVMe Namespace ID
    cdw2: u32,
    cdw3: u32,
    metadata: u64,
    addr: u64,       // 데이터 버퍼 주소
    metadata_len: u32,
    data_len: u32,   // 전송 크기 (bytes)
    cdw10: u32,      // SLBA[31:0] — 시작 LBA 하위 32비트
    cdw11: u32,      // SLBA[63:32] — 시작 LBA 상위 32비트
    cdw12: u32,      // NLB (Number of Logical Blocks - 1) | dtype
    cdw13: u32,      // dspec — FDP placement handle ID ← 핵심
    cdw14: u32,
    cdw15: u32,
    rsvd2: [u32; 4],
}

cdw13의 dspec 필드가 FDP 연결 지점이다. FDP placement_id를 여기 넣으면 NVMe 레벨에서 데이터 배치 스트림을 지정할 수 있다.

---

nvme_uring_cmd_prep — NVMe 명령 빌드

fn nvme_uring_cmd_prep(
    cmd: &mut NvmeUringCmd,
    is_write: bool,
    nsid: u32,
    offset: u64,      // 바이트 오프셋
    len: usize,
    lba_shift: u32,   // LBA 크기 = 1 << lba_shift (9=512B, 12=4KB)
    ptr: *const u8,
    dtype: u8,        // Directive Type (FDP = 2)
    dspec: u16,       // FDP placement handle ID
) {
    let slba = offset >> lba_shift;      // 바이트 오프셋 → LBA 번호
    let nlb  = (len >> lba_shift) - 1;  // 전송 크기 → 블록 수 - 1

    cmd.cdw10 = (slba & 0xFFFFFFFF) as u32;
    cmd.cdw11 = (slba >> 32) as u32;
    cmd.cdw12 = nlb as u32 | ((dtype as u32) << 20);
    cmd.cdw13 = (dspec as u32) << 16;   // FDP placement_id 여기
    cmd.addr  = ptr as u64;
    cmd.data_len = len as u32;
}

LBA 변환:

바이트 오프셋 → SLBA = offset >> lba_shift
전송 크기     → NLB  = (len >> lba_shift) - 1

---

register_fixed_buffers — zero-copy I/O 등록

fn register_fixed_buffers(&self, buffer_ptrs: Vec<usize>, buffer_sizes: Vec<usize>) -> PyResult<()> {
    let mut map = self.fixed_buffer_map.lock().unwrap();
    for (idx, (ptr, size)) in buffer_ptrs.iter().zip(buffer_sizes.iter()).enumerate() {
        map.insert(*ptr, (idx as u16, *size));
    }
    let iovecs: Vec<libc::iovec> = ...;
    ring.submitter().register_buffers(&iovecs)  // syscall 1번으로 N개 버퍼 등록
}

버퍼를 커널에 미리 등록하면 I/O 시 buf_index로 참조 가능 → 매번 주소 번역 불필요. CPU/GPU 메모리를 한 번 핀하고 재사용하는 구조.

---

Worker thread 배치 submit 패턴

let batch: Vec<IoSubmission> = std::mem::take(&mut *q);
for sub in batch.iter().take(to_submit_count) {
    build_and_submit_sqe(&ring_clone, sub, user_data);  // SQ에 추가 (syscall 아님)
}
ring.submitter().submit()  // syscall 1번으로 N개 한꺼번에 커널로

요청을 SQ에 쌓은 뒤 한 번의 syscall로 배치 제출 → N개 I/O에 syscall 1번.

---

Python 변경사항 (core.py)

_write_buffers / _read_buffers — I/O 경로 라우팅

io_engine = "posix"     → pwrite_from_buffer          (기존 동기 I/O)
io_engine = "io_uring"
  └── use_uring_cmd=True  → _write_uring_cmd_buffers  (NVMe passthrough)
  └── use_uring_cmd=False
        └── payload==total (정렬됨) → batched_write + wait_iouring (배치 비동기)
        └── 그 외               → write_uring           (개별 비동기)

기존 _write_one이 header/payload를 2번 pwrite했던 것과 달리, io_uring 경로는 batched_write로 여러 I/O를 한 번에 submit.

register_fixed_buffers_from_allocator

def register_fixed_buffers_from_allocator(self, memory_allocator) -> None:
    buffers = memory_allocator.get_paged_buffers()
    buffer_ptrs  = [buf.data_ptr() for buf in buffers]
    buffer_sizes = [buf.numel() * buf.element_size() for buf in buffers]
    self._rawdev().register_fixed_buffers(buffer_ptrs, buffer_sizes)

CPU allocator의 페이지 버퍼를 io_uring에 등록 → 이후 해당 버퍼 I/O는 zero-copy.

max_hw_sectors_kb — 자동 전송 크기 분할

max_hw_sectors_kb = _read_sysfs_int(f"{queue_dir}/max_hw_sectors_kb")
resolved_bytes    = max_hw_sectors_kb * 1024
aligned_bytes     = (resolved_bytes // self.block_align) * self.block_align

NVMe 디바이스가 한 번에 처리할 수 있는 최대 크기를 sysfs에서 읽어서, KV 청크가 초과하면 여러 NVMe 명령으로 분할 발행.

---

전체 I/O 흐름 (io_uring_cmd 경로)

Python: put_many(keys, objs)
  └─ _write_buffers(offsets, bufs, ...)
       └─ use_uring_cmd=True
            └─ _write_uring_cmd_buffers()
                 └─ nvme_uring_cmd_prep(cmd, offset, len, dspec=placement_id)
                      └─ IoUringWrapper::Big → UringCmd80 → SQ push
                           └─ submitter().submit()  [syscall 1번]
                                └─ NVMe HW: SLBA, NLB, FDP dspec 처리
                                     └─ wait_iouring(batch_id) → CQ 수거

---

M3와의 관계

이 PR이 완성되면 builder() 패턴이 도입되지만 setup flag는 없다:

// #3274 이후 상태 (M3 착수점)
IoUring::<Entry128, Entry32>::builder()
    .build(iouring_queue_depth as u32)   // ← 여기에 플래그 추가가 M3

IoUring::<SqueueEntry, Entry>::builder()
    .build(iouring_queue_depth as u32)   // ← fallback 경로에도 동일 적용

Worker thread가 single issuer 구조임에도 커널이 그 사실을 모르는 상태.
M3에서 setup_single_issuer(), setup_defer_taskrun() 추가 → SQ submission 오버헤드 감소.

---

FDP 연동 가능성

nvme_uring_cmd_prep의 dspec 파라미터가 FDP placement handle을 전달하는 필드:

cdw13 = (dspec as u32) << 16   ← FDP placement_id 여기

FDP placement_id 결정 로직이 완성되면, 이 dspec에 넘기는 것으로 FDP 활성화.
#3274가 그 배관을 완성하는 PR이다.

현재 PR:
  nvme_uring_cmd_prep(... dspec=0)       ← placement 미지정

FDP 다음 단계:
  nvme_uring_cmd_prep(... dspec=placement_id)
                              ↑
                    RUH 번호 직접 지정 → WAF ↓

---

현재 제약 및 리뷰 피드백

항목	내용
fixed buffer + uring_cmd 조합	아직 미구현 (PR 본문 명시)
정렬 검증 로직	오정렬 바이트 범위 검증 개선 요청 (DongDongJu 코멘트)
비정렬 I/O	지원 안 함 (블록 정렬 전송만)
--use-uring-cmd UX	--use-uring 없이 단독 사용 시 오해 소지 있는 에러 메시지

---

관련 페이지

• [[io_uring]] — io_uring_cmd 개념, big SQE/CQE 구조 상세
• [[raw_block-종단-분석]] — raw_block 전계층 분석, FDP 삽입 포인트 H1-H8
• [[NVMe-FDP]] — Placement Handle, RUH — dspec에 넣을 대상
• [[기여-포인트-맵]] — [2][8] 기여 포인트
• [[PR-3274-IoUring-NVMe]] — 이 PR 추적 페이지 (현재 상태, M1/M2 착수 조건)