1. 개요¶
드라이버 API(ha_drv_*)는 디바이스를 다루는 모든 함수가 디바이스 핸들을 받는 디바이스 핸들 기반 API입니다. 런타임
API(Ha*)가 CUDA 런타임 API에 대응한다면, 드라이버 API는 CUDA 드라이버 API에 해당합니다.
대부분의 애플리케이션은 런타임 API만으로 충분합니다. 드라이버 API는 디바이스를 핸들로 직접 지정해야 하는 경량 환경(Edge 등)이나, 자체 런타임·프레임워크 백엔드를 구현하면서 디바이스·스트림·커널의 수명을 직접 관리해야 할 때 사용합니다.
참고
함수별 상세 시그니처는 Driver API 레퍼런스를 참고하십시오. 본 가이드는 런타임 API 가이드와 같은 장 구조를 따릅니다 — 실행(2장), 메모리(3장), 순서와 동기화(4장), 실패 처리(5장).
Contents¶
| Section | Objective |
|---|---|
| 1.1 드라이버 API의 역할 | 드라이버 API가 맡는 일과 이를 사용하는 소프트웨어의 구성 |
| 1.2 런타임 API와의 차이 | 디바이스 지정 방식, 번호 체계, 혼용 금지 주의사항 |
| 1.3 핵심 개념 | 이후 장들에서 공통으로 사용하는 주요 어휘 |
| 1.4 디바이스 핸들 (Device Handle) | HaDrvDev의 의미, 수명, 공유, 소유 관계 |
| 1.5 기본 사용 예제 | 메모리 할당, 복사, 커널 실행, 동기화까지의 기본 흐름 |
1.1 드라이버 API의 역할¶
드라이버 API는 디바이스 핸들 하나 단위로 디바이스 관리, 메모리, 실행, 동기화를 다룹니다.
아래 그림은 드라이버 API를 사용하는 소프트웨어의 예상 구조입니다. 애플리케이션 스레드와 드라이버 API 사이에 사용자가 직접 만든 계층(자체 런타임, 프레임워크 백엔드 등)이 들어가 디바이스 핸들, 객체 수명, 디바이스 간 조율을 맡고, 모든 호출에 디바이스 핸들을 넘깁니다.
드라이버 API를 사용하는 소프트웨어의 계층 구조
드라이버 API가 다루는 영역은 다음 다섯 가지입니다.
| 영역 | 하는 일 | 주요 함수 | 가이드 |
|---|---|---|---|
| 디바이스 관리 | 부트스트랩, 핸들 열기·닫기, 속성 조회, 리셋 | ha_drv_init, ha_drv_open, ha_drv_close, ha_drv_get_attr, ha_drv_reset |
실행 모델 |
| 메모리 관리 | 디바이스 메모리 할당·해제, 호스트와 디바이스 사이 복사 | ha_drv_malloc, ha_drv_free, ha_drv_memcpy, ha_drv_memcpy_nd |
메모리 모델 |
| 실행 제어 | 파일이나 커널 라이브러리에서 커널 로드, 스트림에 실행 큐잉 | ha_drv_kernel_load_from_file, ha_drv_kernel_load_from_library, ha_drv_kernel_launch |
실행 모델 |
| 순서와 동기화 | 스트림·이벤트 생성, 스트림에 작업 큐잉, 완료 대기 | ha_drv_obj_create, ha_drv_stream_post, ha_drv_wait |
스트림과 이벤트 |
| 실패 처리 | 스트림에 남은 오류 확인, 디바이스 리셋 | ha_drv_wait, ha_drv_reset |
에러 처리와 리셋 |
디바이스를 다루는 모든 함수는 디바이스 핸들(HaDrvDev)을 첫 번째 인자로 받으며, 여러 디바이스를 한 번에 다루는
함수는 제공되지 않습니다. 디바이스와 무관한 함수(부트스트랩, 호스트 메모리, 커널 라이브러리, 인자 리스트 값 변경)는 핸들을
받지 않습니다. C++ 환경에서만 사용할 수 있으며(C 링키지), CMake 타깃 hart::ha_umd_core를 링크해야 합니다.
1.2 런타임 API와의 차이¶
두 API의 차이는 다음과 같습니다.
| 비교 구분 | 런타임 API (Ha*) |
드라이버 API (ha_drv_*) |
|---|---|---|
| 디바이스 지정 방식 | 스레드별 현재 디바이스(HaSetDevice) |
사용할 디바이스를 HaDrvDev 핸들 인자로 지정 |
| 디바이스 번호 체계 | 초기화에 성공한 디바이스 대상의 가상 ID(0부터 재배치) | 물리 하드웨어 디바이스 인덱스 |
| 멀티 디바이스 처리 | 포인터 주소로 소유 디바이스를 찾아 자동 라우팅하고 P2P 직접 전송 지원 | 단일 디바이스 제어(다중 디바이스는 호출 조합으로 구성) |
| 커널 실행 방식 | 바이너리 경로 또는 커널 라이브러리의 커널 핸들로 실행(디바이스별 로드는 자동) | 명시적 로드(ha_drv_kernel_load_from_file, ha_drv_kernel_load_from_library) 후 핸들로 실행하며 스트림에 비동기로 큐잉 |
| 메모리 복사 인터페이스 | 동기(HaMemCpy)와 비동기(HaMemCpyAsync) 함수 분리 |
항상 스트림에 비동기로 큐잉 |
| CMake 링크 타깃 | hart::ha_hart |
hart::ha_umd_core |
| 명시적 스트림·이벤트 | HaStreamCreate, HaEventCreate(HaStream_t, HaEvent_t) |
ha_drv_obj_create(HaStream_t, HaDrvEvent). 드라이버 이벤트는 런타임 이벤트와 별개 객체 |
| 메모리 해제 | HaMemFree, 스트림 순서 기반 HaMemFreeAsync |
즉시 해제(ha_drv_free), 스트림 순서 기반 HA_STREAM_OP_FREE |
| 동기화 | HaStreamSynchronize, HaEventSynchronize, HaDeviceSynchronize |
ha_drv_wait 단일 진입점으로 스트림·이벤트·디바이스 대기 |
| 디바이스 리셋 | HaResetDevice, HaResetAllDevices |
ha_drv_reset(디바이스 핸들 유지, 하위 객체 무효화) |
| 지원 언어 | C++, Python | C++(C 링키지) |
기본 스트림은 스레드와 디바이스마다 하나씩 있으며, 두 API는 같은 스레드와 디바이스에서 기본 스트림을 공유합니다.
참고: 디바이스 번호 불일치
ha_drv_open에 전달하는 index는 하드웨어 디바이스 인덱스인 반면, 런타임 API의 디바이스 ID는
가상 ID입니다. 초기화에 실패한 디바이스가 있으면
두 번호 체계가 서로 어긋나므로 같은 번호가 같은 디바이스를 가리킨다는 보장이 없습니다.
런타임 API와 드라이버 API를 같은 디바이스에 섞어 쓰지 마십시오
두 API는 같은 디바이스 상태를 공유하지만, 런타임 API가 따로 관리하는 정보(전역 주소 테이블, 스트림·이벤트 관리 정보)는 드라이버 API 호출을 알지 못합니다. 같은 디바이스에서 두 API를 섞어 쓰면 다음 문제가 생깁니다.
- 메모리 관리 충돌: 한쪽 API로 할당한 메모리를 다른 쪽 API로 해제하거나 복사하면 런타임이 주소 소유권을 인식하지 못하거나, 해제된 주소가 런타임 관리 정보에 남습니다.
- 이벤트 비호환: 드라이버 이벤트(
HaDrvEvent)와 런타임 이벤트(HaEvent_t)는 별개 객체라 서로 대기할 수 없습니다. - 예기치 않은 핸들 무효화:
ha_drv_reset은 런타임 API가 만든 스트림, 이벤트, 메모리 할당까지 무효화하지만, 런타임은 이를 알지 못합니다.
권장 지침: 한 프로세스에서 두 API가 모두 필요하다면, 디바이스마다 한쪽 API만 전담하여 사용하십시오.
1.3 핵심 개념¶
| 핵심 개념 | 설명 |
|---|---|
디바이스 핸들 (HaDrvDev) |
부트스트랩된 디바이스 하나에 대한 참조. ha_drv_open으로 얻고 ha_drv_close로 해제합니다(디바이스 핸들 참고). |
기본 스트림 (HA_STREAM_DEFAULT) |
(호출 스레드, 디바이스)마다 하나씩 있는 스트림. 최초 사용 시 자동 생성됩니다(스트림 참고). |
스트림 작업 (HaDrvStreamOp) |
ha_drv_stream_post로 스트림에 큐잉하는 작업. 복사, 지연 해제, 파일 로드, 이벤트 기록 등을 포함합니다(스트림 참고). |
순번 (seq) |
스트림에 큐잉된 작업마다 붙는 순번. 동기화 범위가 어디까지 유효한지 판단하는 기준이 됩니다(동기화 지점 참고). |
커널 핸들 (HaDrvKernel) |
ha_drv_kernel_load_from_file 또는 ha_drv_kernel_load_from_library로 디바이스에 로드한 커널. 커널 실행 시 이 핸들을 인자로 전달합니다(커널 로딩과 실행 참고). |
| 스트림 오류 (Sticky error) | 실행 중 실패한 작업의 오류가 스트림에 남아, 이후의 대기와 큐잉에서 계속 반환되는 상태입니다(스트림 오류 참고). |
| 디바이스 리셋 | 디바이스를 재초기화하고 그 디바이스의 하위 핸들을 일괄 무효화하는 동작입니다(디바이스 리셋 참고). |
1.4 디바이스 핸들 (Device Handle)¶
HaDrvDev는 드라이버 API의 모든 호출이 대상 디바이스를 지정하는 수단입니다. 런타임 API가 스레드마다 고른 "현재
디바이스"를 암묵적으로 쓰는 것과 달리, 드라이버 API는 호출마다 이 핸들을 명시합니다.
핸들의 정체 (What a Handle Is)¶
HaDrvDev는 이미 부트스트랩된 디바이스 하나에 대한 참조입니다. 디바이스 자체가 아니므로 핸들을 열거나 닫아도
디바이스가 만들어지거나 사라지지 않습니다. 디바이스를 만들고 없애는 것은 프로세스 단위의 ha_drv_init /
ha_drv_deinit이고, 핸들은 그 사이에서 참조를 잡고 놓을 뿐입니다(디바이스 관리).
- 열기와 닫기:
ha_drv_open(index, &dev)이 참조를 하나 잡고,ha_drv_close(dev)가 놓습니다. 성공한 open마다 close가 하나씩 필요하며, 닫은 핸들은 다시 쓰지 않습니다. - 종료 조건:
ha_drv_deinit은 열린 핸들이 하나도 없을 때만 디바이스를 해제합니다. 남아 있으면HaDeviceBusy를 반환하고 아무것도 해제하지 않습니다. - 인덱스:
ha_drv_open의index는 하드웨어 디바이스 인덱스입니다. 핸들에서 인덱스를 다시 얻으려면ha_drv_get_device_id(dev)를 씁니다. 런타임 API의 가상 디바이스 ID와는 다른 번호입니다(런타임 API와의 차이).
같은 디바이스의 여러 핸들 (Multiple Handles)¶
같은 index로 여러 번 열면 같은 디바이스를 가리키는 핸들이 하나씩 더 생깁니다. 이 핸들들은 디바이스의 상태를
공유합니다. 한 핸들로 할당한 메모리를 다른 핸들로 큐잉한 작업에서 쓸 수 있고, HA_STREAM_DEFAULT는 두 핸들에서
같은 기본 스트림을 가리키므로 두 핸들로 큐잉한 작업은 하나의 순번(seq)으로 이어집니다. 각 핸들은 따로 닫아야
합니다.
디바이스 핸들의 수명과, 같은 디바이스 상태를 공유하는 두 핸들
스레드와 핸들 (Threads)¶
핸들은 특정 스레드에 묶이지 않습니다. 여러 스레드가 같은 핸들로 동시에 호출할 수 있습니다. 다만 스트림 인자에
HA_STREAM_DEFAULT를 넘기면 호출 스레드의 기본 스트림을 뜻하므로, 같은 핸들이라도 스레드마다 다른 기본
스트림을 씁니다(스트림).
하위 객체의 소유 (Owned Objects)¶
스트림, 이벤트, 커널, 메모리 할당은 그것을 만든 디바이스에 속합니다. 함수에 넘기는 하위 객체는 같은 디바이스의 핸들과 함께 써야 하며, 다른 디바이스의 객체를 넘기면 거부됩니다.
| 잘못 넘긴 객체 | 반환 |
|---|---|
| 다른 디바이스의 스트림 | HaStreamInvalidHandle |
| 다른 디바이스의 이벤트 | HaEventInvalidHandle |
| 다른 디바이스에 로드한 커널 | HaInvalidArgument |
리셋과 핸들 (Reset)¶
ha_drv_reset(dev) 이후에도 디바이스 핸들은 그대로 유효합니다. 무효가 되는 것은 그 디바이스의 하위 객체(스트림,
이벤트, 할당, 커널)뿐이므로, 같은 핸들로 하위 객체를 다시 만들면 됩니다(디바이스 리셋).
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 | |
| API | 동기 여부 | 동작 |
|---|---|---|
ha_drv_open() |
Sync | 부트스트랩된 디바이스에 대한 핸들 획득 |
ha_drv_close() |
Sync | 핸들 반납. 디바이스는 유지 |
ha_drv_get_device_id() |
Sync | 핸들이 가리키는 하드웨어 디바이스 인덱스 조회 |
ha_drv_is_ready() |
Sync | 디바이스가 해제되지 않았고 핸들이 유효한지 확인. 리셋 진행 여부는 반영하지 않음 |
ha_drv_get_attr() |
Sync | 디바이스 속성 하나 읽기 |
1.5 기본 사용 예제¶
디바이스 0을 열어 메모리를 할당하고, 데이터를 복사해 커널을 실행한 뒤 결과를 받아오는 전체 흐름입니다. 복사와
실행은 모두 호출 스레드의 기본 스트림에 순서대로 큐잉되며, 마지막 ha_drv_wait 시점에 한꺼번에 완료를
확인합니다.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 | |
다음 단계¶
- 실행 모델 — 디바이스 관리와 커널 실행
- Driver API 레퍼런스 — 함수별 시그니처와 반환 코드