ADR: introduce docs/history/, merge 0011+0018, prune migration cruft

- CLAUDE.md: add ADR Lifecycle subsection (superseded → docs/history/,
  immutable numbering, no renumber)
- ADR-0011: merge ADR-0018 content as "Address Model: LA" section
  alongside PA / VA; status notes VA model is currently implemented
- ADR-0018 / 0029 / 0031: moved to docs/history/ with status updates
  (0018 merged into 0011, 0029 superseded by 0032, 0031 absorbed
  into 0001 rev 2)
- ADR-0019: rewrite Context as PE-HBM connectivity decision
  (self-contained, no LA model framing)
- ADR-0019/0020/0021/0023/0025/0027: Status Proposed → Accepted
  (code verified) and prune Implementation Notes / Affected files /
  Test strategy / "현재 상태" sub-sections describing pre-impl state
- ADR-0024/0026: same migration-flavor cleanup; 0026 also drops D6
  Migration and D8 docs-update sub-decisions
- ADR-0030: status simplified (blocker ADR-0031 now superseded)
- SPEC.md: R10 + §0.2 reflect PA / VA / LA model names
- ADR-0008/0012/0013: refresh ADR-0011 subtitle in Links

21 files changed, 553 insertions(+), 1290 deletions(-).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-05-19 11:42:45 -07:00
parent ecc57d050d
commit 22fd0d2b9d
23 changed files with 553 additions and 1290 deletions
+1 -103
View File
@@ -2,30 +2,10 @@
## Status
Proposed
Accepted
## Context
### 현재 구조의 문제
pe_accel (SchedulerV2Component)은 5개 하드웨어 블록(DmaIn, DmaWb, Gemm, Math, Tcm)을
**단일 컴포넌트 내부**에 숨기고 있다.
```
SchedulerV2Component (단일 topology 노드)
├── DmaInBlock ← 내부 SimPy Store로 직접 연결
├── DmaWbBlock ← topology에 안 보임
├── GemmBlock ← 교체 불가
├── MathBlock ← 교체 불가
└── TcmBlock ← 교체 불가
```
문제점:
- 블록이 다음 블록을 `desc.next_block`으로 직접 참조 — 하드코딩된 라우팅
- 개별 블록 교체 불가 (ADR-0015 컴포넌트 교체 원칙 위배)
- topology에서 PE 내부 구조가 보이지 않음
- GemmBlock과 MathBlock이 TCM load/store 로직을 각각 중복 구현
### 실제 하드웨어 구조
```
@@ -370,64 +350,6 @@ Topology edge는 **control/dispatch visibility + runtime chaining** 양쪽을
Scheduler → 하위 컴포넌트 edge는 초기 dispatch 경로이며,
컴포넌트 간 edge는 token self-routing에 의한 runtime chaining 경로이다.
### D8. 기존 코드 마이그레이션 — builtin 통합
기존 builtin v1 컴포넌트와 pe_accel을 **새 builtin으로 교체**한다.
#### 마이그레이션 전략
1. 기존 `components/builtin/``components/builtin_legacy/`로 백업 (수정 없이 보관)
2. 기존 `components/custom/pe_accel/` → 동일하게 백업
3.`components/builtin/`에 ADR-0021 아키텍처로 재구현
4. topology.yaml은 **하나만 유지** (pe_fetch_store 포함)
5. components.yaml은 새 builtin을 가리킴
```yaml
# components.yaml — 새 builtin
pe_scheduler_v1: kernbench.components.builtin.pe_scheduler:PeSchedulerComponent
pe_gemm_v1: kernbench.components.builtin.pe_gemm:PeGemmComponent
pe_math_v1: kernbench.components.builtin.pe_math:PeMathComponent
pe_dma_v1: kernbench.components.builtin.pe_dma:PeDmaComponent
pe_fetch_store_v1: kernbench.components.builtin.pe_fetch_store:PeFetchStoreComponent
pe_tcm_v1: kernbench.components.builtin.pe_tcm:PeTcmComponent
```
impl 이름(pe_gemm_v1 등)은 유지하되, **구현이 ADR-0021 아키텍처로 교체**된다.
기존 벤치마크와 테스트의 topology.yaml 참조는 변경 없이 동작한다.
#### 레이턴시 모델 계승
새 builtin 컴포넌트의 레이턴시 모델링(MAC cycle 계산, SIMD latency,
TCM BW serialization, DMA fabric latency 등)은 **pe_accel 현재 버전의 구현을 바탕으로** 한다.
tiling.py의 tile schedule 생성 로직도 그대로 가져온다.
아키텍처(컴포넌트 분리, self-routing)만 변경하고, 타이밍 정확도는 유지한다.
#### 테스트 전략
#### 테스트 계획
**1. 기존 테스트 통과** (regression):
마이그레이션 완료 후 기존 테스트(366개)가 전부 통과해야 한다.
**2. 레이턴시 regression**:
pe_accel과 동일한 입력에 대해 새 builtin이 동일 레이턴시를 산출하는지 검증.
**3. Phase 1 → Phase 2 end-to-end**:
SimPy 시뮬레이션(Phase 1)에서 op_log 생성 → DataExecutor(Phase 2)로
실제 numpy 연산 → 결과 정합성 검증까지 통합 테스트.
- GEMM: tl.composite(gemm) → op_log → Phase 2 matmul → allclose 검증
- MATH: tl.exp / tl.add 등 → op_log → Phase 2 numpy op → allclose 검증
- 체이닝: GEMM 출력 → MATH 입력 → 최종 결과 end-to-end 검증
**4. TileToken self-routing**:
- tile이 plan의 stage sequence를 따라 체이닝되는지 검증
- 마지막 stage에서 PipelineContext.complete_tile() exactly-once 검증
- queue backpressure: DMA queue capacity 초과 시 feeder만 block 검증
**5. 비동기 pipeline overlap**:
- 동일 command 내 tile 간 stage overlap 발생 검증 (tile0 GEMM 중 tile1 DMA)
- 다중 command: cmd1 feed 완료 후 cmd2 feed 시작 (FIFO 순서) 검증
### D9. TileToken 메시지 정의
컴포넌트 간 tile 작업 전달에 사용하는 메시지.
@@ -465,7 +387,6 @@ Token lifecycle:
(PeInternalTxn 기반, ADR-0014 유지)
- **다중 pipeline 간 자원 경합 모델**: 현재 범위에서는 단일 pipeline의
정확한 모델링에 집중. 다중 pipeline 간 TCM bank conflict 등은 future work.
- **builtin_legacy 유지보수**: 백업 목적이며, 버그 수정이나 기능 추가 대상이 아님.
## Open Questions
@@ -502,27 +423,4 @@ Token lifecycle:
- PE 내부 컴포넌트 수 증가 (5 → 6) — topology 노드/edge 증가
- 컴포넌트 분리로 인해 intra-PE token forwarding이 이전 대비 더 명시적으로 드러남
- 기존 builtin/pe_accel과의 breaking change — 마이그레이션 필요
---
## 영향받는 파일
| 파일 | 변경 |
|------|------|
| `topology.yaml` | pe_fetch_store 컴포넌트 추가, 체이닝 edge 추가 |
| `components.yaml` | 새 builtin 컴포넌트 등록 |
| `src/kernbench/topology/builder.py` | PE 내부 edge에 fetch_store + 체이닝 edge 추가 |
| `src/kernbench/common/pe_commands.py` | TileToken 정의 추가 |
| `src/kernbench/components/builtin/pe_scheduler.py` | 재구현 (feeder + plan 기반 dispatch) |
| `src/kernbench/components/builtin/pe_gemm.py` | 재구현 (TileToken, _process 패턴) |
| `src/kernbench/components/builtin/pe_math.py` | 재구현 (TileToken, _process 패턴) |
| `src/kernbench/components/builtin/pe_dma.py` | 재구현 (TileToken, _process 패턴) |
| `src/kernbench/components/builtin/pe_fetch_store.py` | 신규 |
| `src/kernbench/components/builtin/pe_tcm.py` | 재구현 (TcmRequest 서비스) |
| `src/kernbench/components/builtin/types.py` | 신규: TilePlan, Stage, StageType, PipelineContext, TileToken |
| `src/kernbench/components/builtin/tiling.py` | pe_accel에서 이식: plan 생성 로직 |
백업:
| `src/kernbench/components/builtin_legacy/` | 기존 builtin 전체 백업 (수정 없이 보관) |
| `src/kernbench/components/custom/pe_accel/` | 기존 pe_accel 백업 (수정 없이 보관) |