raw_block_line.md 의 구조 — L1~L4 와 Contract 의미
변경 검증 가이드 (다음 fetch 후):
본 메모는
raw_block_line.md의 섹션 구조 자체를 설명하는 메타 문서이므로, 원문 헤더가## L1 ~ ## L4에서 다른 형태(예:## §1,## Layer 1) 로 바뀌거나 항목이 추가/삭제되면 본문 표 전체를 다시 써야 함. 자매 메모(perf-findings / l2_adapters_contract) 의 분업 경계가 바뀌어도 "다른 메모와 분업" 섹션 갱신 필요.
L1~L4 는 LMCache 캐시 계층이 아니다
raw_block_line.md 의 ## L1, ## L2 같은 섹션 헤더는 분석 깊이(추상화 레벨) 를 구분한 거지 LMCache 의 L1/L2 캐시 계층이 아니다.
| 섹션 | 의미 | 다루는 것 |
|---|---|---|
| L1 — Contract | 가장 위 (외부 인터페이스) | 누가 누구를 부르는지, eventfd/lock/close 같은 계약 invariant, 책임 분리 표 |
| L2 — I/O 경로 | 중간 (런타임 동작) | put/get/lookup/evict/checkpoint sequence diagram, 디바이스 레이아웃 |
| L3 — 삽입 후보 지점 | 적용 (개입 지점) | FDP/HC-SSD 를 어디에 끼워 넣을지 H1~H8 후크 표 |
| L4 — io_uring 분석 | 가장 아래 (Rust/kernel) | ring 구조, op 종류, fixed buffer, NVMe passthru 여부 |
위 → 아래 갈수록 구체적/저수준. 네트워크 OSI 처럼 "층" 을 쌓아 분석.
왜 이렇게 나눴나
- 분석 단계와 코드 수정 단계를 분리: L1/L2 는 "현 상태 어떻게 생겼나" read-only 분석, L3 는 "어떻게 손댈까" actionable, L4 는 "그 자리의 더 아래"
- TODO 4 (라인 종단 분석) 결과물: 한 모듈을 위~아래 끝까지 종단으로 훑는 작업이라 자연스럽게 층별 정리
- 다른 메모와 분업:
- raw-block-perf-findings.md — 성능 관점만
- l2_adapters_contract.md — 인터페이스 관점만
- 이 메모는 종단 분석이라 layer 로 묶음
⚠️ 헷갈리는 포인트
LMCache 도메인에는 L1 cache = in-memory(CPU 메모리), L2 cache = persistent storage(디스크/원격) 라는 의미가 따로 있고 본문에서도 자주 등장 (예: "L2 lock", "L1 alignment").
섹션 헤더 ## L1 — ... 의 L1 과 본문 안의 "L1 alignment" 의 L1 은 같은 글자지만 의미 완전히 다름.
→ 다음에 비슷한 메모 쓸 때 헤더를 ## Layer 1 — Contract 또는 ## §1 Contract 로 바꾸면 혼동 줄어듦.
"Contract" 섹션의 의미
소프트웨어 엔지니어링의 "계약(contract)" 의미. Design by Contract 에서 온 용어.
어떤 컴포넌트가 호출자에게 보장하는 약속과, 호출자가 지켜야 하는 전제의 집합
쉽게: "이 모듈을 쓰려면 이걸 지켜야 하고, 그러면 이걸 보장해줄게".
raw_block_line.md 의 L1 Contract 섹션이 담은 것
| 항목 | 무엇을 명시하는가 | Contract 측면 |
|---|---|---|
| 계층 구조 (mermaid) | 누가 누구를 부르는지 | "이 모듈이 어디에 끼는가" |
| 책임 분리 표 | 각 레이어의 하는 일 / 안 하는 일 | "이건 내 책임이고 저건 아니다" |
| MP adapter 진입/탈출 invariant | 항상 참이어야 할 조건들 | 불변 조건(invariant) = contract 핵심 |
| 미충족 / 제약 | per_tp_device_paths MP 거부, alignment 등 | 사전 조건(precondition) = 호출자가 지킬 것 |
= "이 모듈을 사용/수정할 때 깨면 안 되는 약속들".
왜 가장 위(L1) 에 뒀나
코드 수정 전에 "절대 깨면 안 되는 항목" 을 먼저 못박는 게 안전. FDP/HC-SSD 후크 (L3) 넣다가 invariant 깨면 — 예: submit non-blocking 이 무너지거나, close 순서 바뀌거나 — 회복 어려운 버그.
L3 에서 손댈 자리 정할 때 "L1 contract 와 충돌하지 않는가?" 체크포인트로 사용하려고 의도적으로 위에 둠.
비슷한 의미 별도 파일
l2_adapters_contract.md — L2AdapterInterface 자체 contract 만 다루는 메모. raw_block_line.md 의 L1 섹션은 그 하위 (특정 구현체인 raw_block 의) contract.