# CUDA API Problem - 심층 분석

**작성일**: 2025년 10월 7일
**상태**: 문제 분석 완료, 새로운 해결책 필요

## 1. 시도한 해결책: Hybrid API (실패)

**구현**: Runtime API `cudaLaunchKernel()` 사용
**결과**: ❌ 여전히 `CUDA_ERROR_INVALID_HANDLE` 발생

**실패 원인 분석**:
```
Runtime API Surface (cudaSurfaceObject_t)
      ↓
Driver API Kernel (cuModuleLoadData로 로드)
      ↓
Kernel 내부에서 surf2Dwrite() 호출 시 handle 불일치
```

## 2. 근본 문제 파악

### 문제의 핵심
- `cudaLaunchKernel()`이 Driver API 커널 함수를 받을 수 있음 ✅
- **BUT** 커널 내부에서 `surf2Dwrite()`가 사용하는 surface handle이 문제 ❌
- Driver API로 로드된 커널은 **Driver API surface object**를 기대함
- Runtime API surface object를 전달하면 handle space 불일치로 에러 발생

### 오해했던 부분
**잘못된 가정**: "`cudaLaunchKernel()`만 사용하면 Runtime API surface를 전달할 수 있다"
**진실**: 커널이 어떤 API로 로드되었는지가 중요 - Driver API 커널은 Driver API handles 필요

## 3. 올바른 해결책 2가지

### 옵션 A: Driver API Surface 사용 (권장)
**변경 파일**: `ExternalMemoryCache.cpp`
**변경 내용**:
```cpp
// Runtime API surface 생성 제거
cudaCreateSurfaceObject(&surface, &res_desc);  // 제거

// Driver API surface 생성으로 교체
cuSurfObjectCreate(&surface, &res_desc);  // 추가
```

**장점**:
- 코드 변경 최소화 (한 파일만 수정)
- PTX 커널 시스템 그대로 유지
- 즉시 구현 가능

**단점**:
- Runtime/Driver API 혼용 유지
- 장기적 유지보수성 약간 저하

### 옵션 B: 완전 Runtime API 전환
**변경 파일**: `D3D12SurfaceHandler.cpp`
**변경 내용**:
- PTX 로딩 제거
- NVRTC로 커널 재컴파일
- Runtime API 커널 함수 포인터 사용

**장점**:
- API 완전 통일
- 장기적 유지보수성 향상

**단점**:
- 구현 복잡도 높음
- NVRTC 통합 필요
- 빌드 시스템 재구성

## 4. 권장 조치: 옵션 A 구현

**이유**:
1. 사용자 요청 ("CUDA Runtime API 로 통일") 정신에 부합하지 않지만 **실용적**
2. 빠른 문제 해결 가능
3. 옵션 B는 향후 리팩토링으로 진행 가능

**구현 계획**:
1. `ExternalMemoryCache.cpp` 수정
   - `cudaCreateSurfaceObject()` → `cuSurfObjectCreate()`
   - Runtime API 타입 → Driver API 타입 변환
2. `ExternalMemoryCache.h` 수정
   - `cudaSurfaceObject_t` → `CUsurfObject` 타입 변경
3. `D3D12SurfaceHandler.h/.cpp` 수정
   - Surface object 타입 변경
4. 빌드 및 테스트

## 5. 다음 단계

사용자에게 상황 보고 및 옵션 선택 요청:
- **옵션 A**: Driver API surface (빠른 해결)
- **옵션 B**: 완전 Runtime API (시간 소요)

현재 상황:
- Hybrid API는 **작동하지 않음**
- 완전한 API 통일 필요