PoC 코드베이스 지도 — `DongDongJu/LMCache:fdp-waf-agentic-replay-poc`

HEAD: 35784a3c benchmarks: add FDP WAF replay stress harness dev base: f8ffd8f06d7c252cef52e82387ab730f71a2f050 ([MP] Introduce EventNotifier #3144) 커밋 수: 39 diffstat 총합: 95 files changed, 15,678 insertions(+), 1,623 deletions(-) Clone 위치: ~/workspace/LMCache-fdp-poc-src

1. 한 줄 요약

PoC는 dev f8ffd8f0 (2025-12 ~ 2026-01 추정) 위에 세 묶음의 코드를 쌓은 통합 브랜치:

raw_block MP L2 adapter 인프라 (PoC 30 커밋) — 이미 origin/dev에 머지된 작업의 사실상 동등 버전
FDP / io_uring_cmd 코어 (PoC 3 커밋) — dspec/dtype NVMe directive 통로
agentic replay + FDP WAF stress harness (PoC 6 커밋) — 측정/벤치마크 도구 1,500줄+

핵심 메시지: PoC는 그 자체로 self-contained한 측정 환경. dev에 머지하기 위한 PR이 아니라, NVIDIA PoC를 위한 1회성 통합 환경이다. 향후 upstream 작업은 이 안에서 (a) FDP 코어와 (b) WAF stress harness를 잘라내 별개 PR로 분할해야 한다.

2. 커밋 분류

2.1 — raw_block MP L2 adapter 인프라 (30 커밋, 위치적으로 dev에 이미 들어간 작업과 겹침)

f4c74a6f ~ d6102820 (오래된 → 최신순):

커밋	메시지
f4c74a6f	Add raw block MP L2 adapter support
b536dcce	Document raw block MP adapter design
29915507	Fix operator README wrapping
804a4cd3	Harden raw block core review issues
7f7db1da	Fix raw block L2 adapter task handling
b9a5beb5	Remove raw block backend private core proxy
d584ec05	Fix raw block pre-commit review issues
dfbc3270	Address raw block review regressions
193b177f	Fix raw block pin and key codec review issues
bbabdbe5	Fix raw block key recovery regressions
88b4a699	Synchronize raw block pin tracking
86abefa9	Make raw block core close thread-safe
d1d15917	Lock raw block prefix metadata during load
4cb17747	Fix raw block adapter error bitmap sizing
eff635e0	Harden raw block eviction handling
bc704082	Harden raw block completion callbacks
55017910	Align raw block store notifications
d85efe24	Guard raw block adapter eventfd close
8babb91d	Pass raw block object sizes to L2 listeners
dbd9618f	Disable global L2 eviction for raw block
d877efeb	Document raw block store task result shape
3884639d	Align L2 listener test signatures
69ec7993	Keep raw block eventfds valid through callbacks
02e860f4	Fix raw block merge with L2 adapter usage
ab0d3e6d	Support vLLM 0.19 MP adapter constructor
14a18a25	Expose io_uring paths for raw block storage
cd57db9e	Add blkio native connector and MP L2 adapter
d6102820	Document raw block io_uring and blkio L2 storage
0ec9f1e0	Fix raw block inflight and pin locks
a25ff41c	Narrow raw block pin lock scope

해석: 이 30개 커밋은 dev에 이미 머지된 raw_block MP L2 adapter 작업과 기능적으로 동등한 자체 구현. 즉, PoC는 dev의 최신 raw_block 작업을 따라가지 않고 별도 인프라를 자체 작성해서 그 위에 FDP를 쌓았다. 후속 PR로 upstream에 가져가려면 dev의 현재 raw_block과 정합 작업이 필요하다 (단계 5 daegyu94_integration.md / poc_patterns_to_adopt.md 참조).

2.2 — FDP / io_uring_cmd 코어 (3 커밋, 이번 task의 핵심)

커밋	메시지	변경
17ad9b4f	raw-block: add FDP PoC for uring cmd	Rust write API에 NVMe directive 필드(`dtype`/`dspec`) 추가, RUH 선택 + per-RUH metadata 분할 plumbing, 설정 검증 + 테스트
f3a4297a	raw-block: split FDP data and metadata RUHs	data RUH pool과 metadata RUH pool 분리, io_uring_cmd raw-command 기본값을 비-O_DIRECT로 (NVMe ns char device가 O_DIRECT 미지원)
1497b060	raw-block: place FDP writes by MP worker	고유 MP worker 단위로 placement rank 부여 → 다중 TP worker가 별도 data RUH로 매핑되며 cache key identity는 변경 없음

2.3 — agentic replay + FDP WAF stress harness (6 커밋)

커밋	메시지
6336a845	trace: support cache salt suffix on replay
010219c2	raw-block: add base-offset layout support
cea489a8	raw-block: expose byte-offset window config
e230c2e3	tests: cover raw-block byte-offset windows
9986f7ae	docs: document raw-block byte windows
35784a3c	benchmarks: add FDP WAF replay stress harness

효과: 같은 raw-block 디바이스를 여러 trace replay worker가 byte 영역으로 분할 점유 가능. salt suffix는 동일 trace를 여러 instance가 같이 돌릴 때 키 충돌 방지용.

3. 변경 파일 카테고리별 정리

3.1 — Raw block backend (Python core / Rust binding / L2 adapter)

파일	LoC	역할
`lmcache/v1/storage_backend/raw_block/core.py`	+2,239 (신규)	새 RawBlockCore — config에 `use_fdp`/`fdp_data_ruh_ids`/`fdp_metadata_ruh_ids`/`fdp_directive_type`/`fdp_metadata_mode` 5개 필드. `_select_fdp_ruh()`/`_select_fdp_metadata_ruh()`/`_write_directive_for_ruh()` 3개 메서드가 placement 결정의 진입점
`lmcache/v1/storage_backend/raw_block/__init__.py`	+34	모듈 export
`lmcache/v1/storage_backend/raw_block/key_codec.py`	+168	object/legacy 키 인코딩 (FDP에서 worker_id 추출용)
`lmcache/v1/storage_backend/plugins/rust_raw_block_backend.py`	+308 / -1623	대대적 축소 — RawBlockCore로 위임
`lmcache/v1/distributed/l2_adapters/raw_block_l2_adapter.py`	+867 (신규)	L2 adapter — config JSON `use_fdp`/`fdp_*` 필드 파싱, `use_fdp=true` 시 `use_uring_cmd=true` 강제
`rust/raw_block/src/lib.rs`	+835 / -?	신규: `dspec`/`dtype` 필드. `pwrite` API 시그니처에 `dtype: u8 = 0`/`dspec: u16 = 0` 추가. `cmd.cdw13 = (dspec as u32) << 16`로 NVMe write command에 directive 부착

3.2 — File backend / fs_l2_adapter

변경 없음. PoC는 file backend를 건드리지 않음. 즉 fcntl(F_SET_FILE_RW_HINT, RWH_WRITE_LIFE_*) 같은 file-level write hint 경로는 미구현. (단계 5 file_backend_fdp.md의 새 영역으로 남음).

3.3 — 새 storage backend: blkio (native NVMe-passthru)

파일	LoC	역할
`csrc/storage_backends/blkio/connector.cpp`	+235	C++ libblkio 기반 connector
`csrc/storage_backends/blkio/connector.h`	+92
`csrc/storage_backends/blkio/pybind.cpp`	+14
`csrc/storage_backends/blkio/README.md`	+231
`lmcache/v1/distributed/l2_adapters/blkio_l2_adapter.py`	+478
`lmcache/v1/storage_backend/native_clients/blkio_client.py`	+48
`tests/v1/distributed/test_blkio_l2_adapter.py`	+250
`tests/v1/storage_backend/test_blkio_connector.py`	+437

해석: blkio = libblkio 기반 native (C++) 백엔드. raw_block과 별개 경로로 io_uring_cmd 지원. PoC는 raw_block만 FDP에 사용하지만, blkio adapter는 추후 FDP 통합 후보.

3.4 — Agentic replay harness (벤치/측정)

파일	LoC	역할
`benchmarks/agentic_mp_trace/`	+2,800	dataset adapter 11개(agentbench/appworld/browsergym/gaia/.../webarena), launcher (vllm/openai/lmcache_server), record/replay scripts
`benchmarks/agentic_mp_trace/replay/fdp_policy.py`	+72	storage class별 RUH 정책: `default_data_ruhs`/`default_metadata_ruhs`/`classes.<class>.data_ruhs`/`metadata_ruhs`
`benchmarks/agentic_mp_trace/replay/window_allocator.py`	+72	byte-offset window 분배 (worker별 디바이스 영역 할당)

3.5 — FDP WAF stress harness (이번 task의 측정 핵심)

파일	LoC	역할
`benchmarks/fdp_waf_stress/run_fdp_waf_stress.py`	+1,456	WAF 측정 통합 harness — trace footprint 분석, worker별 byte window 할당, RUH 정책 적용, mode = `mixed`/`separated`/`no_fdp` 3개
`benchmarks/fdp_waf_stress/generate_synthetic_traces.py`	+574	합성 trace 생성 (실 워크로드 없을 때 대체)
`benchmarks/fdp_waf_stress/README.md`	+181	사용법
`benchmarks/fdp_waf_stress/config.example.yaml`	+102	정책/handle 매핑 예시
`tests/benchmarks/fdp_waf_stress/`	+400	단위 테스트

run_fdp_waf_stress.py 핵심 인터페이스:

expand_ruh_ids(spec) → [0, 1, 2, 3] 같은 ID 리스트로 정규화
_resolve_worker_ruhs(...) → worker별 RUH 할당
build_l2_adapter(worker, config) → l2-adapter JSON dict 생성 (use_fdp/fdp_data_ruh_ids 등)
build_replay_command(...) → lmcache trace replay ... 명령 빌드
make_meta_magic(worker_global_index) / make_salt_suffix(...) → 동일 디바이스 공유 시 충돌 방지

3.6 — Tests

파일	LoC
`tests/v1/storage_backend/test_rust_raw_block_backend.py`	+507 (FDP directive 테스트 포함)
`tests/v1/storage_backend/test_raw_block_key_codec.py`	+37
`tests/v1/distributed/test_raw_block_l2_adapter.py`	+940 (신규)
`tests/v1/distributed/test_blkio_l2_adapter.py`	+250 (신규)
`tests/v1/distributed/test_l2_adapter_factory.py`	+59/-? (FDP factory 분기)
`tests/v1/storage_backend/test_blkio_connector.py`	+437 (신규)

3.7 — Docs

파일	변경
`docs/design/v1/distributed/l2_adapters/raw_block.md`	+172 (FDP 옵션 5개 표 + per_ruh metadata mode 문서)
`docs/source/mp/l2_storage.rst`	+99
`docs/source/kv_cache/storage_backends/blkio.rst`	+328 (신규)
`docs/source/mp/tracing_and_debugging.rst`	+36
`rust/raw_block/README.md`	+121

4. FDP 호출 그래프 (write 경로)

[L2 adapter config JSON]
   │ use_fdp=true
   │ fdp_data_ruh_ids=[0,1,2,3]
   │ fdp_metadata_ruh_ids=[4]
   │ fdp_directive_type=2  (FDP directive)
   │ fdp_metadata_mode="per_ruh"
   ▼
RawBlockL2Adapter._validate_config()  [raw_block_l2_adapter.py:243]
   │ — use_fdp=true → use_uring_cmd=true 강제
   │ — fdp_*_ruh_ids 비어있지 않음, 중복 없음, uint16 범위
   ▼
RawBlockCore.__init__()  [raw_block/core.py:162-225]
   │ — 동일 검증 + self._fdp_metadata_ruh_index = {ruh: idx}
   ▼
RawBlockCore.put / put_many                   [data 경로]
   │
   │ for each key:
   │     ruh = self._select_fdp_ruh(key, obj)              [core.py:342]
   │           ├ obj.metadata.fdp_placement_rank 우선         (server.py:34 — MP worker가 stamp)
   │           ├ key.namespace == "object" → kv_rank>>16     (decode_object_key)
   │           └ legacy → parsed_key.worker_id
   │           idx = worker_index % len(fdp_data_ruh_ids)
   │           return fdp_data_ruh_ids[idx]
   │     dtype, dspec = self._write_directive_for_ruh(ruh)  [core.py:399]
   │           return (self.fdp_directive_type, ruh)        # (2, ruh_id)
   │     rust_pwrite(offset, buf, len, dtype=dtype, dspec=dspec)
   ▼
[Rust] RawBlockBackend.pwrite_from_buffer  [rust/raw_block/src/lib.rs:804-820]
   │ #[pyo3(signature = (offsets, buffers, total_lens, dtype = 0, dspec = 0))]
   │ validate_nvme_directive(use_uring_cmd, dtype, dspec)
   │   — dspec != 0 && dtype == 0 → reject
   │   — (dtype != 0 || dspec != 0) && !use_uring_cmd → reject
   ▼
io_uring_cmd NVMe passthrough
   │ struct nvme_uring_cmd cmd
   │ cmd.opcode = NVMe Write
   │ cmd.cdw12 |= dtype (4 bits)
   │ cmd.cdw13 = (dspec as u32) << 16     ← placement ID 들어가는 자리
   ▼
[NVMe device] Write to RUH=dspec

Metadata 경로 (체크포인트):

RawBlockCore._write_metadata_checkpoint()
   ruh = self._select_fdp_metadata_ruh(encoded_key)  [core.py:380]
         digest = blake2b(encoded_key)[:8]
         idx = digest % len(fdp_metadata_ruh_ids)
         return fdp_metadata_ruh_ids[idx]
   → 동일하게 (dtype, dspec) 통로로 진입

핵심 포인트:

placement rank의 결정 로직은 3단 fallback: (1) obj.metadata.fdp_placement_rank (MP worker가 명시 stamp) > (2) object key의 kv_rank>>16 (worker index 비트) > (3) legacy key의 worker_id. 모두 모듈로 N으로 RUH index로 매핑.
즉 PoC는 per-vLLM-Worker 정책이 기본이며, prompt-aware/phase-aware 정책은 코어 레이어에 없고 agentic replay harness의 storage_class 단위 RUH 매핑으로 우회한다.

5. 의존성

use_fdp=true ↔ use_uring_cmd=true (강제). io_uring_cmd 없이는 FDP 사용 불가.
io_uring_cmd 인프라 (Rust pwrite API의 dtype/dspec 인자, cmd.cdw13)는 PoC가 자체적으로 추가 — dev에 머지된 ankit-sam 작업(#3274)의 인프라와는 별개. 자세한 비교는 02_ankit_sam_pr1_diff.md 참조.
빌드: pip install -e . + Rust ext (maturin develop 또는 cargo build). PoC가 setup.py를 +110줄 추가했음 — 빌드 절차 변경 가능성. 단계 3 빌드 시 확인.

6. 향후 단계와의 연결

단계 1.3 02_ankit_sam_pr1_diff.md → ankit-sam#1과의 인프라 동등성 검증
단계 1.4 03_fdp_implementation_audit.md → 7카테고리 Y/N + 빈자리
단계 5 poc_patterns_to_adopt.md → 위 호출 그래프 중 (a) _select_fdp_ruh/_select_fdp_metadata_ruh/_write_directive_for_ruh 3-함수 추상화, (b) RUH config 5필드 (use_fdp/fdp_data_ruh_ids/fdp_metadata_ruh_ids/fdp_directive_type/fdp_metadata_mode)를 upstream 후보로 검토

1. 한 줄 요약​

2. 커밋 분류​

2.1 — raw_block MP L2 adapter 인프라 (30 커밋, 위치적으로 dev에 이미 들어간 작업과 겹침)​

2.2 — FDP / io_uring_cmd 코어 (3 커밋, 이번 task의 핵심)​

2.3 — agentic replay + FDP WAF stress harness (6 커밋)​

3. 변경 파일 카테고리별 정리​

3.1 — Raw block backend (Python core / Rust binding / L2 adapter)​

3.2 — File backend / fs_l2_adapter​

3.3 — 새 storage backend: blkio (native NVMe-passthru)​

3.4 — Agentic replay harness (벤치/측정)​

3.5 — FDP WAF stress harness (이번 task의 측정 핵심)​

3.6 — Tests​

3.7 — Docs​

4. FDP 호출 그래프 (write 경로)​

5. 의존성​

6. 향후 단계와의 연결​