콘텐츠로 이동

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를 사용하는 소프트웨어의 계층 구조

드라이버 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
HaDrvDev a = nullptr, b = nullptr;
ha_drv_open(0, &a);
ha_drv_open(0, &b);                     // 같은 디바이스 0에 대한 두 번째 핸들

HaDevicePtr buf = 0;
ha_drv_malloc(a, &buf, n, /*is_interleaved=*/false, HA_STREAM_DEFAULT);

// a로 할당한 메모리를 b로 큐잉한 복사에서 사용. 두 핸들 모두 이 스레드의 같은 기본 스트림을 가리킴
HaDrvStreamOp h2d{HA_STREAM_OP_MEMCPY, {}};
h2d.memcpy = {buf, reinterpret_cast<HaDevicePtr>(src), n, HaMemCpyDirection::HostToDevice};
uint64_t seq_a = 0, seq_b = 0;
ha_drv_stream_post(a, HA_STREAM_DEFAULT, &h2d, &seq_a);
ha_drv_stream_post(b, HA_STREAM_DEFAULT, &h2d, &seq_b);   // seq_b == seq_a + 1 (같은 스트림, 순번 하나)
ha_drv_wait(a, HA_STREAM_DEFAULT, nullptr, HA_WAIT_STREAM_SYNC, -1, nullptr);
ha_drv_free(a, buf, HA_STREAM_DEFAULT);

int index = ha_drv_get_device_id(a);    // 0

ha_drv_close(b);
ha_drv_close(a);                        // open마다 close 하나
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
#include "ha_driver_api.h"

int main() {
  if (ha_drv_init() != HaError::HaSuccess) return 1;   // 모든 디바이스 부트스트랩

  HaDrvDev dev = nullptr;
  ha_drv_open(0, &dev);                                // 디바이스 0 핸들 획득

  float in[1024] = {}, out[1024] = {};
  const size_t n = sizeof(in);
  HaDevicePtr da = 0;
  ha_drv_malloc(dev, &da, n, /*is_interleaved=*/false, HA_STREAM_DEFAULT);

  ha_drv_memcpy(dev, da, reinterpret_cast<HaDevicePtr>(in), n, HaMemCpyDirection::HostToDevice,
                HA_STREAM_DEFAULT);

  HaDrvKernel k = nullptr;
  ha_drv_kernel_load_from_file(dev, "kernels/scale.elf", &k);
  uint32_t dims[] = {1024};
  HaLaunchArgs args;                                   // 스코프를 벗어나면 해제됨
  ha_drv_launch_args_add_tensor(dev, args, HaLaunchArgRoute::Universal, -1, da, dims, 1, 0);
  ha_drv_kernel_launch(dev, HA_STREAM_DEFAULT, k, args);   // 리스트는 실행 호출 반환 시 이미 소비됨

  ha_drv_memcpy(dev, reinterpret_cast<HaDevicePtr>(out), da, n, HaMemCpyDirection::DeviceToHost,
                HA_STREAM_DEFAULT);

  // 이 대기가 끝나기 전에는 in/out 호스트 버퍼를 해제하면 안 됩니다.
  ha_drv_wait(dev, HA_STREAM_DEFAULT, nullptr, HA_WAIT_STREAM_SYNC, -1, nullptr);

  ha_drv_kernel_release(dev, k);
  ha_drv_free(dev, da, HA_STREAM_DEFAULT);
  ha_drv_close(dev);
  ha_drv_deinit();                                     // 모든 핸들을 닫은 뒤 전체 해제
  return 0;
}

다음 단계