분석 계획 (TODO)

작성일: 2026-05-19 목적: LMCache 의 SSD I/O 스택을 FDP / HC-SSD / 기존 io_uring 활용 관점에서 분석. 관련: lmcache_overview.md

---

0. 분석 렌즈 (모든 모듈에 동일 적용)

각 모듈을 읽을 때 항상 아래 4가지 관점으로 노트를 남긴다.

#	렌즈	묻는 질문
L1	Contract	어떤 인터페이스/추상 클래스를 따르는가? 입력/출력/invariant 는? 어떤 호출 순서가 보장되는가?
L2	I/O 경로	read/write 가 어디서 발생하는가? 데이터 흐름 (host buffer ↔ device ↔ disk)? 동기/비동기? 배치 단위?
L3	FDP / HC-SSD 삽입 지점	stream hint, RUH(Reclaim Unit Handle), placement ID 를 끼울 수 있는 지점은? HC-SSD offload(예: compression/CRC) 를 위탁할 수 있는 hook 은?
L4	io_uring 활용 방식	(해당되는 경우) io_uring_* 호출 위치, queue depth, SQ/CQ 배치 정책, op 종류, registered buffer/file 사용 여부

주의: io_uring 은 이미 구현되어 있음. "어떻게 추가할지" 가 아니라 "어떻게 쓰고 있는지" 를 분석한다.

---

1. 산출물 규칙

• 모듈별 분석 노트: private/refs/notes/<topic>.md
  • 파일 상단에 L1~L4 섹션을 그대로 두고 채움.
  • 인용은 path/to/file.py:line 포맷.
• 최종 종합: lmcache_overview.md 끝에 "§6. SSD I/O 스택 종합" 섹션으로 append.
• 코드 수정은 이 단계에서 하지 않음. 분석/노트만.

---

2. TODO 리스트

진입 순서는 lmcache_overview.md §5.3 의 권장 순서를 따른다.

TODO 1 — L2 어댑터 전체 그림 ✅

• 읽기: docs/design/v1/distributed/l2_adapters/overall.md
• 노트: private/refs/notes/l2_adapters_overall.md
• 목표 산출:
  • L2 어댑터가 무엇이고 storage_backend 와 어떤 관계인지 한 문단
  • 어댑터 종류 분류 (fs / native / plugin / nixl / mooncake / s3 / resp / mock / raw_block / dax)
  • L1, L2 채워두기 (L3, L4 는 모듈별 분석 후 채움)

TODO 2 — 어댑터 계약과 등록 흐름 ✅

• 읽기: lmcache/v1/distributed/l2_adapters/base.py, factory.py, config.py
• 노트: private/refs/notes/l2_adapters_contract.md
• 목표 산출 (L1 중심):
  • L2Adapter 추상 메서드 시그니처와 의미
  • factory 가 config 로부터 어댑터를 고르는 분기 로직
  • serde wrapper 가 어디서 끼어드는지 (serde_wrapper.py)

TODO 3 — adapter ↔ plugin 연결 메커니즘 ✅

• 읽기: docs/design/v1/distributed/l2_adapters/plugin.md + plugin_l2_adapter.py + native_plugin_l2_adapter.py
• 노트: private/refs/notes/plugin_pipeline.md
• 목표 산출 (L1 + L2):
  • L2Adapter 가 plugin 백엔드를 호출하는 경로 (call graph)
  • plugin (native vs python) 의 차이
  • 설정 키 매핑: config 등록부터 adapter 인스턴스 생성까지

TODO 4 — raw_block 라인 종단 분석 (★ 최우선) ✅

• 읽기:
  • docs/design/v1/distributed/l2_adapters/raw_block.md
  • lmcache/v1/distributed/l2_adapters/raw_block_l2_adapter.py
  • lmcache/v1/storage_backend/plugins/rust_raw_block_backend.py
  • lmcache/v1/storage_backend/raw_block/core.py, key_codec.py
• 노트: private/refs/notes/raw_block_line.md
• 목표 산출 (L1~L4 모두 채움):
  • L1: adapter → plugin → core 인터페이스 종단 다이어그램
  • L2: put / get / lookup / evict 시의 데이터 흐름 (CPU buffer, slab, slot, device)
  • L3: FDP/HC-SSD 삽입 후보 지점 표 (어디에 placement_id, stream, offload hook 을 넣을 수 있는가)
  • L4: io_uring 사용 분석
    • 어디서 ring 을 만들고 submit/complete 하는가
    • queue depth (DEFAULT_IOURING_QUEUE_DEPTH) 와 배치 정책
    • registered buffer / fixed file 사용 여부
    • 어떤 op (READ/WRITE/READV/WRITEV/FSYNC …) 를 쓰는가
    • per-TP device sharding (PerTPDevicePaths) 가 ring 분배에 미치는 영향

TODO 5 — eviction / quota 사이드 트랙

• 읽기:
  • docs/design/v1/distributed/l2_adapters/l2_eviction.md
  • docs/design/v1/distributed/l2_adapters/l2_per_user_quota.md
• 노트: private/refs/notes/l2_eviction_quota.md
• 목표 산출:
  • eviction 트리거 조건과 raw_block slot 회수 흐름
  • FDP 관점에서 RUH 회수 정책과 일치/불일치 지점

TODO 6 — dax 라인 (참고 비교)

• 읽기:
  • docs/design/v1/distributed/l2_adapters/dax.md
  • lmcache/v1/distributed/l2_adapters/dax_l2_adapter.py
  • lmcache/v1/storage_backend/plugins/dax_backend.py
  • lmcache/v1/storage_backend/dax/core.py
• 노트: private/refs/notes/dax_line.md
• 목표 산출:
  • raw_block 라인과 동일 패턴인지 확인 (인터페이스/호출 흐름)
  • 다른 점만 짧게 (mmap 기반 vs io_uring 기반)

TODO 7 — serde wrapper 와 정합성

• 읽기: docs/design/v1/distributed/l2_adapters/serde_wrapper.md + serde_wrapper.py
• 노트: 위 노트들 안의 해당 섹션에 짧게 흡수 (단독 파일 X)
• 목표 산출:
  • serde 가 어느 시점에 끼어드는가 (adapter 진입/탈출)
  • HC-SSD offload 후보(예: compression) 가 들어갈 자리와 충돌 여부

TODO 8 — 종합

• lmcache_overview.md 에 §6 "SSD I/O 스택 종합" 섹션 추가
• 포함 내용:
  • adapter → plugin → core 계층 그림 (raw_block 기준)
  • io_uring 사용 요약 (queue depth, op 종류, 배치 정책)
  • FDP / HC-SSD 삽입 후보 지점 정리표
  • 다음 단계 (코드 수정 단계로 넘어갈 때의 우선순위)

---

3. 진행 규칙

• 각 TODO 는 읽기 → 노트 작성 → 체크박스 마킹 순서.
• 노트는 길게 쓰지 않는다. L1L4 각 15 bullet 이면 충분.
• 디자인 문서와 코드가 다르면 코드를 우선 하고 차이를 노트에 기록.
• 의문점은 노트 하단 "Open Questions" 에 모았다가 일괄 질문.