graph_executor_v2 변경 가이드 (무엇을 바꿀 때 어디를 고치는가)

0) 빠른 요약 표

작업 유형                          주요 수정 파일                                                        필요한 수정/검토 포인트

새 커널 추가 (예: conv2d 또는 gemm 변형)	src/my_kernels.cu, src/launch_table.cpp, compiler/kernels/registry.py	(1) C 진입점 함수 구현 (2) 런치 테이블에 이름-포인터 등록 (3) 파이썬 레지스트리에 메타 추가 (4) 필요 시 capability 점수 추가
기존 커널 성능 개선 (그리드/블록/타일)	src/my_kernels.cu	런처 내부의 블록/그리드/타일링/메모리 접근 최적화, 에러코드/스트림 유지
f16/TC (WMMA, cuBLASLt) 추가	src/my_kernels.cu, src/launch_table.cpp, compiler/kernels/registry.py	f16용 C 진입점 구현 + 등록, 레지스트리에 flags.tensor_core=True/dtype 업데이트, capability 점수 조정
새 연산(Op) 추가 (예: LAYER_NORM)	compiler/kernels/registry.py, compiler/kernels/selector.py, (네이티브가 있다면) src/launch_table.cpp, src/my_kernels.cu	레지스트리에 op_type 후보 등록 → selector 룰/네이티브 점수 반영 → 네이티브 커널/점수 테이블 추가
커널 선택 로직 개선	compiler/kernels/selector.py	_score_by_rules() 확장(dtypes, layouts, shape/stride, 아키텍처) + query_capability() 결과 가중치 조정
런타임 인자/ 파라미터 전달 변경	compiler/runtime/executor.py, (필요 시) include/ge_v2_api.h	_prepare_buffers()에서 desc/params 구성 변경, ABI 바뀌면 헤더/문서 동시 수정
ABI(계약) 변경 (함수 시그니처, 버퍼 순서, 파라미터 블록 등)	include/ge_v2_api.h, src/bindings_min_api.cpp, src/launch_table.cpp, src/my_kernels.cu, compiler/runtime/executor.py, 문서	버전 증가(GE2_API_VERSION++), 바인딩/런처/실행기 모두 동일 규약으로 갱신, README/문서 업데이트
capability 점수 정책 변경/추가	src/launch_table.cpp	<OPTYPE>__<KERNEL_NAME> → int 점수 테이블 갱신
빌드 스크립트 변경 (새 소스/라이브러리)	CMakeLists.txt	새 .cu/.cpp 추가, target_link_libraries()(예: CUDA::cublasLt) 업데이트, include 경로 추가
스모크/테스트 추가	smoke_test_v2.py (+ 필요 시 새 테스트 파일)	새로운 op/커널에 맞춘 입력 생성, params 블록 생성, 참값 검증

 

1) 새 커널(변형) 추가

 

C 진입점 구현

• 파일: src/my_kernels.cu
• 주의: 반환값 규약(0/음수) 유지, 스트림은 reinterpret_cast<cudaStream_t>(stream).

extern "C" int ge2_launch_<name>(const ge2_uintptr* bufs, int n, void* stream) {
  // 1) bufs에서 A/B/(bias)/C/params 해석
  // 2) params(Host)에서 shape/옵션 읽기
  // 3) grid/block 계산, 커널 <<<>>> 호출
  // 4) cudaGetLastError() → 0 성공 / 음수 에러코드
}

 

런치 테이블 등록

• 파일: src/launch_table.cpp

extern "C" int ge2_launch_<name>(const ge2_uintptr*, int, void*);
static std::unordered_map<std::string, ge2_kernel_fn> tab = {
  {"<kernel_name>", &ge2_launch_<name>},
  // ...
};

 

 

파이썬 레지스트리 등록

• 파일: compiler/kernels/registry.py

register({
  "name": "<kernel_name>",
  "op_type": "<OPTYPE>",
  "dtypes": {"in": [...], "out": "..."},
  "flags": {"tensor_core": True/False, "min_mnk": (..)},
  "layouts": {...},
})

 

2) 기존 커널 성능 개선

• 파일: src/my_kernels.cu
• 내용: 블록/그리드/타일링, shared memory, vectorized LD/ST, 매크로타일, double-buffering, warp-level 연산 등.
• 변경 금지/유지:
  • 진입점 시그니처/에러코드/버퍼 순서/스트림 해석은 ge_v2_api.h 규약과 동일해야 함.
  • 성능 튜닝으로 ABI가 흔들리면 아래 6번(ABI 변경)을 따름.

 

3) f16(Tensor Core)/cuBLASLt 추가

• 파일: src/my_kernels.cu
  • ge2_launch_gemm_bias_act_tc_f16 구현: WMMA(텐서코어) 또는 cuBLASLt 호출
  • dtype 변환/accumulate 정책(f16 load → f32 accum → f16 cast) 명시
• 파일: src/launch_table.cpp
  • f16용 커널 이름 등록
  • capability 점수에서 f16에 높은 기본점수(또는 device_caps 기반 동적 점수)
• 파일: compiler/kernels/registry.py
  • 해당 커널 메타에 flags.tensor_core=True, dtype "f16" 반영
• 파일: compiler/kernels/selector.py
  • device_caps["tensor_core"]면 가산점, dtype/layout 호환 체크

 

4) 새 연산(Op) 추가

• 파일: compiler/kernels/registry.py
  • 새로운 op_type의 후보 커널 메타 등록
• 파일: compiler/kernels/selector.py
  • _score_by_rules()에 op 특화 규칙(예: 채널/배치/패딩 등) 추가
  • 필요 시 native.query_capability()와 키 규약: "<OPTYPE>__<KERNEL_NAME>"
• 네이티브 동반 구현 시: src/my_kernels.cu, src/launch_table.cpp
• (선택) 실행기에서 파라미터 블록: compiler/runtime/executor.py
  • _prepare_buffers()에서 Host params 블록 구성/append

 

5) 런타임 인자/파라미터 전달 변경

• 파일: compiler/runtime/executor.py
  • _prepare_buffers()에서 버퍼 순서(입력→출력→(옵션)Host params) 유지
  • descs/params 생성 규약을 커널이 필요로 하는 형태로 확장(예: strides, padding, activation type 등)
• 네이티브에서 params 해석: src/my_kernels.cu
  • 동일 레이아웃의 struct로 캐스팅해 사용
• 문서화 필수: README/설명 파일에 파라미터 레이아웃 기록

 

6) ABI(계약) 변경

가급적 피하고, 불가피할 때는 원자적으로 처리.

• 파일: include/ge_v2_api.h
  • 타입/시그니처/순서 변경 → GE2_API_VERSION 증가
• 파일: src/bindings_min_api.cpp
  • pybind 시그니처 동기화
• 파일: src/launch_table.cpp, src/my_kernels.cu
  • 모든 진입점/해석 코드 동기화
• 파일: compiler/runtime/executor.py
  • _prepare_buffers()/params 생성 동기화
• 파일: 문서(README/가이드)
  • 변경점/마이그레이션 절차 기록
• 호환 체크: 파이썬에서 gev2.GE2_API_VERSION을 읽어 미스매치를 감지 → 명확한 에러 출력

 

 

7) capability 점수 정책 변경

• 파일: src/launch_table.cpp
  • 정적 점수 조정 또는 키 추가/제거
  • 키 형식 고정: "<OPTYPE>__<KERNEL_NAME>"
• (선택) 셀렉터 가중치: compiler/kernels/selector.py
  • 네이티브 점수 + 룰 기반의 합산 로직 조정

 

 

8) 빌드 스크립트 변경

• 파일: CMakeLists.txt
  • 새 소스 추가 시 set(SRC ...)에 파일 추가
  • 새 라이브러리 링크(예: CUDA::cublasLt)
  • target_include_directories() 확장 (외부 헤더)
  • 설치 산출물(헤더/모듈) 추가

 

9) 스모크/테스트

• 파일: smoke_test_v2.py (또는 tests/*)
  • 새 커널/연산에 맞춘 입력/params 생성
  • 참값(NumPy/Torch CPU) 대비 오차 확인
  • 런타임 에러코드/예외 메시지 단언

 

10) 불변 규약(깨면 전파 수정 필요)

• 버퍼 순서: 입력들 → 출력들 → (옵션) Host params(마지막)
• 스트림: cudaStream_t를 void*로 전달/복구
• 반환값: 0=성공, 음수=오류 (공통 에러코드 테이블 유지)
• capability 키: "<OPTYPE>__<KERNEL_NAME>"
• 레지스트리 이름 일치: registry.py의 "name" == launch_table.cpp key
• 버전: ABI 변경 시 GE2_API_VERSION++ 및 문서 갱신

 

11) 변경 예시(패턴)

A. 새 커널 gemm_bias_act_f32_tiled 추가

• my_kernels.cu: extern "C" int ge2_launch_gemm_bias_act_f32_tiled(...) 구현

//launch_table.cpp

{"gemm_bias_act_f32_tiled", &ge2_launch_gemm_bias_act_f32_tiled}
{"GEMM_BIAS_ACT__gemm_bias_act_f32_tiled", 90}

#registry.py

register({"name": "gemm_bias_act_f32_tiled", "op_type":"GEMM_BIAS_ACT",
          "dtypes":{"in":["f32","f32","f32"],"out":"f32"},
          "flags":{"tensor_core":False,"min_mnk":(256,256,128)}})

 

B. GELU 활성화 추가(파라미터 확장)

• executor.py: params에 act=2 세팅
• my_kernels.cu: act==2 분기에서 GELU 적용
• ABI 변경 아님(필드 재사용) → 버전 증가 불필요