ADR: translate adr-ko/ to Korean, fix ADR-0013 slug, refine Status check
Follow-up to the bilingual-structure commit: docs/adr-ko/ now holds only Korean versions (24 files translated from English placeholders), ADR-0013 slug uses kebab-case in both folders, and the verify tool allows translated parenthetical commentary in the Status block. - Translate 24 English files in docs/adr-ko/ to Korean. The previous bilingual-structure commit had left these as English copies because their source content was already English; this commit fulfills the policy that docs/adr-ko/ contains only Korean. - Rename ADR-0013 in both adr/ and adr-ko/ from ver-verification_strategy.md to ver-verification-strategy.md (kebab-case consistency with other ADRs). - CLAUDE.md (ADR Translation Discipline): clarify that only the Status lifecycle keyword (Accepted / Proposed / Stub / Draft / Superseded by ADR-NNNN / Merged into ADR-NNNN) must match across EN and KO; parenthetical commentary and trailing list items may be translated. - tools/verify_adr_lang_pairs.py: replace byte-equal Status check with normalize_status_keyword() which strips parenthetical commentary and takes only the first non-empty line. - tests/test_verify_adr_lang_pairs.py: update existing test names, add coverage for translated parenthetical, translated trailing list, and Superseded-by-NNNN keyword equality. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -1,4 +1,4 @@
|
||||
# ADR-0022: 2D Grid program_id Semantics
|
||||
# ADR-0022: 2D 그리드 program_id 시맨틱
|
||||
|
||||
## Status
|
||||
|
||||
@@ -6,38 +6,43 @@ Accepted
|
||||
|
||||
## Context
|
||||
|
||||
Triton kernels use `tl.program_id(axis)` to identify their position in a launch grid.
|
||||
Our hardware has a 2-level hierarchy: **cubes** contain **PEs**.
|
||||
The previous implementation ignored the `axis` parameter and always returned a flat PE index,
|
||||
making it impossible for kernels to distinguish their cube-local position from their cube identity.
|
||||
Triton 커널은 `tl.program_id(axis)`를 사용해 launch 그리드 내 자신의
|
||||
위치를 식별한다. 본 하드웨어는 2단계 계층을 갖는다: **큐브**가 **PE**를
|
||||
포함한다. 이전 구현은 `axis` 파라미터를 무시하고 항상 평탄화된 PE
|
||||
인덱스를 반환했기 때문에, 커널이 큐브 내부 위치와 큐브 식별자를 구분할
|
||||
수 없었다.
|
||||
|
||||
## Decision
|
||||
|
||||
Map `tl.program_id` and `tl.num_programs` to the 2D hardware grid:
|
||||
`tl.program_id`와 `tl.num_programs`를 2D 하드웨어 그리드에 매핑한다:
|
||||
|
||||
| Call | Returns | Description |
|
||||
|------|---------|-------------|
|
||||
| `tl.program_id(axis=0)` | `local_pe_id` | PE index within cube |
|
||||
| `tl.program_id(axis=1)` | `cube_id` | Cube index |
|
||||
| `tl.num_programs(axis=0)` | `num_pes_per_cube` | PEs per cube |
|
||||
| `tl.num_programs(axis=1)` | `num_cubes` | Total cubes |
|
||||
| `tl.program_id(axis=0)` | `local_pe_id` | 큐브 내 PE 인덱스 |
|
||||
| `tl.program_id(axis=1)` | `cube_id` | 큐브 인덱스 |
|
||||
| `tl.num_programs(axis=0)` | `num_pes_per_cube` | 큐브당 PE 개수 |
|
||||
| `tl.num_programs(axis=1)` | `num_cubes` | 전체 큐브 개수 |
|
||||
|
||||
Global PID is derived as:
|
||||
전역 PID는 다음과 같이 도출된다:
|
||||
|
||||
```python
|
||||
global_pid = tl.program_id(axis=1) * tl.num_programs(axis=0) + tl.program_id(axis=0)
|
||||
```
|
||||
|
||||
### Axis mapping rationale
|
||||
### 축 매핑 근거
|
||||
|
||||
- **axis=0 = PE (innermost)**: PEs within a cube share HBM and communicate via local NOC mesh. This is the fast, tightly-coupled dimension — analogous to threads within a block.
|
||||
- **axis=1 = Cube (outer)**: Cross-cube communication goes through UCIe with higher latency. This is the coarser scheduling dimension — analogous to blocks in a grid.
|
||||
- **axis=0 = PE (최내부)**: 큐브 내부 PE들은 HBM을 공유하고 로컬 NoC
|
||||
메시를 통해 통신한다. 빠르고 강하게 결합된 차원이다 — 블록 내부의
|
||||
스레드와 유사하다.
|
||||
- **axis=1 = 큐브 (외부)**: 큐브 간 통신은 더 높은 레이턴시의 UCIe를
|
||||
통한다. 더 거친 스케줄링 차원이다 — 그리드 내의 블록과 유사하다.
|
||||
|
||||
## Implementation
|
||||
|
||||
### TLContext (`triton_emu/tl_context.py`)
|
||||
|
||||
Added `cube_id` and `num_cubes` constructor parameters. `program_id()` and `num_programs()` dispatch on `axis`:
|
||||
`cube_id`와 `num_cubes` 생성자 파라미터를 추가했다. `program_id()`와
|
||||
`num_programs()`가 `axis`로 디스패치한다:
|
||||
|
||||
```python
|
||||
def program_id(self, axis: int = 0) -> int:
|
||||
@@ -53,18 +58,22 @@ def num_programs(self, axis: int = 0) -> int:
|
||||
|
||||
### PE_CPU (`components/builtin/pe_cpu.py`)
|
||||
|
||||
- Extracts `num_cubes` from `ctx.spec["system"]["sips"]["cubes_per_sip"]`
|
||||
- Passes `cube_id` (already available as `self._cube_idx`) and `num_cubes` to TLContext
|
||||
- `ctx.spec["system"]["sips"]["cubes_per_sip"]`에서 `num_cubes`를
|
||||
추출한다.
|
||||
- `cube_id`(이미 `self._cube_idx`로 사용 가능)와 `num_cubes`를
|
||||
TLContext에 전달한다.
|
||||
|
||||
### KernelRunner (`triton_emu/kernel_runner.py`)
|
||||
|
||||
- Receives `num_cubes` from PE_CPU
|
||||
- Passes `cube_id` and `num_cubes` to TLContext in greenlet mode
|
||||
- PE_CPU로부터 `num_cubes`를 수신한다.
|
||||
- greenlet 모드에서 `cube_id`와 `num_cubes`를 TLContext에 전달한다.
|
||||
|
||||
## Backward Compatibility
|
||||
|
||||
- Existing code using `tl.program_id(0)` or `tl.program_id()` is unchanged — returns the same PE index as before.
|
||||
- `cube_id` and `num_cubes` default to `0` and `1`, so callers that don't provide them (e.g. unit tests) continue to work.
|
||||
- `tl.program_id(0)` 또는 `tl.program_id()`를 사용하는 기존 코드는
|
||||
변경되지 않는다 — 이전과 동일한 PE 인덱스를 반환한다.
|
||||
- `cube_id`와 `num_cubes`는 기본값이 `0`과 `1`이므로, 이를 제공하지
|
||||
않는 호출자(예: 유닛 테스트)도 계속 동작한다.
|
||||
|
||||
## Usage Example
|
||||
|
||||
@@ -74,7 +83,7 @@ def sharded_gemm_kernel(a_ptr, b_ptr, out_ptr, M, K, N, tl):
|
||||
cube_id = tl.program_id(axis=1) # which cube
|
||||
global_pid = cube_id * tl.num_programs(axis=0) + local_pid
|
||||
|
||||
# Column-wise sharding across global PID
|
||||
# 전역 PID에 걸친 column-wise 샤딩
|
||||
n_per_pid = N // (tl.num_programs(axis=1) * tl.num_programs(axis=0))
|
||||
col_start = global_pid * n_per_pid
|
||||
|
||||
@@ -86,5 +95,6 @@ def sharded_gemm_kernel(a_ptr, b_ptr, out_ptr, M, K, N, tl):
|
||||
|
||||
## Consequences
|
||||
|
||||
- Benchmarks can now express cube-aware sharding and addressing without hardcoding topology dimensions.
|
||||
- Future axis=2 (SIP-level) can be added following the same pattern if needed.
|
||||
- 벤치마크가 토폴로지 차원을 하드코딩하지 않고 큐브 인식 샤딩과 주소
|
||||
지정을 표현할 수 있다.
|
||||
- 필요 시 axis=2(SIP 레벨)를 동일한 패턴을 따라 향후 추가할 수 있다.
|
||||
|
||||
Reference in New Issue
Block a user