WGSL · 27 커널 계약 문서화
단계: 수치 검증과 커널 설계 · 편집 가능한 예제 · 저장 ID: wgsl-step-27
목표와 학습 후 역량
- 커널 자원 계약을 문서화한다.
- 재현과 실패 상태를 관리한다.
선수 지식
26단위 결과물과 기록을 이어 사용합니다. 커널 계약 문서화 실험에 앞서 이전 입력과 기준 출력을 보관합니다.
핵심 개념과 설명
입력 계약
커널의 타입·길이·정렬·접근 권한이 명시되어야 호스트 구현을 바꿔도 결과를 유지할 수 있습니다. 단순 함수 설명만으로는 GPU 자원 계약을 전달하기 어렵습니다.
실패 계약
지원 실패·컴파일 실패·장치 손실은 계산 오차와 다른 실패입니다. 결과 파일에 원인과 미실행 상태를 구분해 기록합니다.
실습 준비
예제 화면의 실행 범위 안내를 먼저 확인하세요. 다음은 과제를 별도 프로젝트로 확장할 때의 준비 환경입니다. 별도 localhost 또는 HTTPS 프로젝트에서 직접 구현하는 문서 안내 실습입니다. secure context, navigator.gpu, adapter 요청 결과를 확인하고 미지원 안내를 제공합니다. device.lost 처리와 자원 해제를 유지합니다.
연결된 예제는 출발점입니다. 아래 과제 전체가 완성된 코드는 아니며, 예제의 지원 범위를 넘는 작업은 별도 프로젝트에서 수행하세요.
실습 과제
- README.md에 map·reduction·stencil 세 커널의 입력·출력·layout·동기화 범위를 표로 적으세요.
- 의도한 shader 오류와 device loss 뒤 재생성 절차를 검토하세요.
- 새 세션에서 저장한 seed·설정·fixture로 테스트를 실행하고 결과를 내보내세요.
관찰할 변수
| 변수 | 기준 조건 | 바꿀 조건 | 예상할 변화·검증 가설 |
|---|---|---|---|
| 실행 시작 | 기존 장치 상태 | 재초기화한 새 세션 | CPU 입력과 계약이 충분하면 같은 결과를 재현할 것으로 예상합니다. |
표의 예상은 측정 결과가 아닙니다. 한 번에 한 조건만 바꾸고 실제 결과가 다르면 원인을 기록하세요.
완료 조건
- 세 커널의 동기화 범위와 접근 권한이 문서에 있다.
- 실행 결과와 지원 불가·미실행 상태를 별도 표시한다.
자가 점검
- 컴파일 통과가 수치 정확성을 보장하나요?
- 호스트 layout이 바뀌면 어떤 테스트가 먼저 실패해야 하나요?
공식 참고
연결된 예제와 실행 범위
실제 WebGPU/WGSL 실행. HTTPS/localhost와 지원 adapter 필요; 미지원 환경에는 사유를 표시하며 CPU 결과를 GPU로 대체하지 않습니다.
원본 코드·기록은 자동으로 덮어쓰지 않습니다. 기존 예제를 초기화할 때도 필기는 유지됩니다.
다음 학습
이전: Workgroup 구성과 측정 · 다음: Compute와 경계