콘텐츠로 이동

2. 실행 모델

드라이버 API에서 디바이스를 사용하려면 먼저 디바이스를 부트스트랩하고 핸들을 연 뒤, 커널을 로드해 핸들 기반으로 실행합니다. 런타임 API와 달리 별도의 동기 실행 함수가 제공되지 않습니다. 커널 실행과 메모리 복사는 모두 스트림에 큐잉되는 즉시 반환되며, 작업 완료 여부는 4장 스트림과 이벤트의 ha_drv_wait를 통해 확인합니다.

본 장에서는 디바이스 핸들의 수명 주기, 커널 핸들의 수명 주기, 그리고 비동기 디스패치(Asynchronous Dispatch)의 제어권 반환 시점을 다룹니다.


Contents

Section Objective
2.1 디바이스 관리 (Device Management) 부트스트랩, 핸들 Open/Close, 속성 조회 및 종료 순서
2.2 커널 로딩과 실행 커널 핸들(HaDrvKernel)의 로드, 비동기 실행 및 해제
2.3 비동기 디스패치 (Asynchronous Dispatch) 제어권 반환 시점과 완료 확인 및 호스트 버퍼 유효성

2.1 디바이스 관리 (Device Management)

드라이버 API의 디바이스 관리는 프로세스 단위의 함수 쌍(ha_drv_init / ha_drv_deinit)과 디바이스 핸들 단위의 함수 쌍(ha_drv_open / ha_drv_close)으로 구분됩니다.

디바이스 수명 주기 (Device Lifecycle)

  1. 초기화(ha_drv_init): 시스템에 장착된 모든 디바이스를 스캔하고 부트스트랩합니다. 사용 가능한 디바이스가 없으면 HaDeviceNotAvailable을 반환하며, 디바이스가 준비된 뒤 다시 호출할 수 있습니다.
  2. 핸들 열기(ha_drv_open): ha_drv_open(index, &dev)를 호출해 대상 디바이스에 대한 참조를 잡고 HaDrvDev 핸들을 받습니다. 새로운 디바이스 객체를 생성하는 것이 아니라 이미 부트스트랩된 디바이스를 가리킵니다.
  3. 자원 활용: 메모리, 스트림, 커널 제어 함수 등 모든 후속 API는 이 핸들을 첫 번째 인자로 받습니다.
  4. 핸들 닫기(ha_drv_close): ha_drv_close(dev)를 호출해 참조를 반납합니다. 디바이스 자체는 부트스트랩 상태로 유지됩니다.
  5. 종료(ha_drv_deinit): 모든 디바이스와 그 스트림, 이벤트, 커널, 메모리를 최종 해제합니다. 단, 열린 핸들이 하나라도 남아 있으면 자원을 해제하지 않고 HaDeviceBusy를 반환합니다.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
ha_drv_init();                                   // 프로세스: 모든 디바이스 부트스트랩

int count = 0;
ha_drv_get_device_count(&count);

HaDrvDev dev = nullptr;
ha_drv_open(0, &dev);                            // 핸들: 디바이스 0에 대한 참조 획득

int64_t channels = 0;
ha_drv_get_attr(dev, HA_DEV_ATTR_DRAM_CHANNELS, &channels);

// ... 메모리, 스트림, 커널 작업 수행 ...

ha_drv_close(dev);                               // 핸들 반납 (디바이스 0은 부트스트랩 상태 유지)
ha_drv_deinit();                                 // 프로세스: 모든 디바이스 자원 해제
API 동기 여부 동작
ha_drv_init() Sync 모든 디바이스를 스캔하고 부트스트랩. 이미 부트스트랩되어 있으면 추가 동작 없음
ha_drv_get_device_count() Sync 부트스트랩된 디바이스 수 조회
ha_drv_open() Sync 대상 디바이스에 대한 HaDrvDev 핸들 획득
ha_drv_get_attr() Sync 디바이스 단일 속성(Attribute) 값 읽기
ha_drv_close() Sync 디바이스 핸들 참조 반납
ha_drv_deinit() Sync 모든 디바이스 자원 최종 해제(열린 핸들이 남아 있으면 HaDeviceBusy)

참고: 재부트스트랩

ha_drv_init()은 디바이스가 이미 부트스트랩되어 있으면 별도 처리 없이 성공을 반환합니다. 디바이스를 다시 부트스트랩하려면 열린 핸들을 모두 닫은 뒤 ha_drv_deinit()을 먼저 호출해야 합니다.

리셋 (Device Reset)

ha_drv_reset(dev)는 디바이스를 강제 재초기화하고 그 디바이스의 스트림, 이벤트, 메모리 할당, 커널 핸들을 일괄 무효화합니다. 최상위 디바이스 핸들(HaDrvDev)은 그대로 유효합니다. 세부 사양은 5.3 디바이스 리셋을 참고하십시오.

2.2 커널 로딩과 실행

드라이버 API는 바이너리 파일 경로만으로 커널을 직접 실행하지 않으며, 커널을 디바이스에 로드해 발급받은 커널 핸들(HaDrvKernel)을 인자로 전달해 실행합니다. 커널은 파일에서 로드하거나, 미리 컴파일된 커널 라이브러리에서 로드합니다.

커널 로드 (Kernel Load)

ha_drv_kernel_load_from_file(dev, path, &k)는 커널 파일의 유효성을 검증하고 디바이스 메모리를 예약합니다. 이 연산은 디바이스 동작 완료를 기다리지 않습니다. 같은 파일을 다시 로드하면 새로운 핸들이 발급되지만, 디바이스 메모리는 서로 공유됩니다.

커널 라이브러리에서 로드 (Kernel Library)

커널 라이브러리는 디바이스 버전별로 빌드한 커널을 하나로 묶은 데이터(HaLibraryData)입니다. 라이브러리는 디바이스와 무관하게 다루고, 디바이스에 올릴 때 그 디바이스의 칩에 맞는 빌드를 고릅니다.

  1. ha_drv_library_load_data(&lib, data)로 라이브러리를 등록합니다. 디바이스가 필요 없어 ha_drv_init() 전에도 호출할 수 있으며, 데이터는 복사되지 않으므로 프로세스가 끝날 때까지 유효해야 합니다.
  2. ha_drv_library_get_kernel(&kernel, lib, name)으로 이름에 해당하는 커널 핸들(HaKernel_t)을 얻습니다. 이 핸들은 어느 디바이스에도 로드되지 않은 커널을 가리킵니다. 이름은 ha_drv_library_kernel_name()으로 다시 읽을 수 있습니다.
  3. ha_drv_kernel_load_from_library(dev, kernel, &k)로 디바이스 칩에 맞는 빌드를 로드해 HaDrvKernel을 받습니다. 라이브러리에 그 칩용 빌드가 없으면 HaKernelNoBinaryForDevice를 반환합니다. 이후 실행과 해제는 파일에서 로드한 커널과 같습니다.

라이브러리 핸들(HaLibrary_t)과 라이브러리 커널 핸들(HaKernel_t)은 프로세스가 끝날 때까지 유효하며 디바이스 리셋의 영향을 받지 않습니다. 리셋으로 무효화되는 것은 디바이스에 로드한 HaDrvKernel뿐이므로, 리셋 뒤에는 ha_drv_kernel_load_from_library()만 다시 호출하면 됩니다.

커널 실행 (Kernel Execution)

ha_drv_kernel_launch(dev, stream, k, args)은 커널 실행을 스트림에 큐잉한 직후 반환합니다. 커널 인자는 인자 리스트(HaLaunchArgs 객체)로 전달합니다. 리스트는 객체를 생성해 만들고, 스코프를 벗어나 소멸할 때 해제됩니다. 인자는 ha_drv_launch_args_add_*()로 추가하며, 이 함수들은 각 인자를 지정한 디바이스(dev)의 코어 구성에 맞는지 검사합니다. 반복 실행 시 값만 바꿀 때는 ha_drv_launch_args_set_*()를 씁니다 (Execution 참고). 리스트가 커널의 인자 형식과 맞지 않으면 실행이 HaKernelInvalidArgument로 거부됩니다.

인자 리스트는 함수 반환 이전에 소비되므로 호출 직후 리스트를 해제하거나 다음 실행을 위해 갱신해도 안전합니다. 단, 커널의 최초 실행 시점에는 바이너리 업로드 작업이 해당 스트림에 먼저 큐잉될 수 있습니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
HaDrvKernel k = nullptr;
if (ha_drv_kernel_load_from_file(dev, "kernels/add.elf", &k) == HaError::HaKernelNotFound) {
  return;   // 커널 파일 경로 확인 필요
}

uint32_t dims[] = {1024};
HaLaunchArgs args;                                       // 스코프를 벗어나면 해제됨
ha_drv_launch_args_add_tensor(dev, args, HaLaunchArgRoute::Universal, -1, a, dims, 1, 0);
ha_drv_launch_args_add_tensor(dev, args, HaLaunchArgRoute::Universal, -1, b, dims, 1, 0);
ha_drv_launch_args_add_tensor(dev, args, HaLaunchArgRoute::Universal, -1, out, dims, 1, 0);

ha_drv_kernel_launch(dev, HA_STREAM_DEFAULT, k, args);   // 스트림 큐잉 후 즉시 반환
ha_drv_kernel_launch(dev, HA_STREAM_DEFAULT, k, args);   // 같은 핸들·리스트로 재실행 가능

ha_drv_wait(dev, HA_STREAM_DEFAULT, nullptr, HA_WAIT_STREAM_SYNC, -1, nullptr);
ha_drv_kernel_release(dev, k);
API 동기 여부 동작
ha_drv_library_load_data() Sync 커널 라이브러리 등록 후 라이브러리 핸들(HaLibrary_t) 발급. 디바이스 불필요
ha_drv_library_get_kernel() Sync 이름으로 라이브러리 커널 핸들(HaKernel_t) 조회
ha_drv_kernel_load_from_file() Sync 커널 파일 검증과 디바이스 메모리 예약 후 커널 핸들(HaDrvKernel) 발급
ha_drv_kernel_load_from_library() Sync 디바이스 칩에 맞는 라이브러리 커널 빌드 검증과 디바이스 메모리 예약 후 커널 핸들(HaDrvKernel) 발급
ha_drv_kernel_launch() Async 커널 실행을 스트림에 큐잉(첫 실행 시 바이너리 업로드가 먼저 큐잉될 수 있음)
ha_drv_kernel_release() Sync 커널 핸들 무효화(이미 큐잉된 실행은 그대로 진행)

참고: 커널 핸들 안전성

이미 해제된 핸들이나 디바이스 리셋 이전에 발급된 핸들로 커널 실행을 시도하면 HaKernelInvalidHandle을 반환하며, 다른 커널이 잘못 실행되는 일은 없습니다. 또한 디바이스 메모리는 ha_drv_kernel_release 호출 시 즉시 반환되지 않고, 디바이스 리셋이나 종료 시점에 일괄 해제됩니다.

2.3 비동기 디스패치 (Asynchronous Dispatch)

드라이버 API의 커널 실행(ha_drv_kernel_launch)과 메모리 복사(ha_drv_memcpy, ha_drv_memcpy_nd) 함수는 모두 비동기(Asynchronous) 방식으로 동작합니다. HA_STREAM_DEFAULT를 포함한 모든 스트림에서 작업을 큐에 등록하면 바로 반환하며, 반환은 작업이 큐에 들어갔다는 뜻일 뿐 디바이스 작업이 완료되었음을 나타내지 않습니다.

반환 전에 호스트에서 일부 처리가 일어나는 경우는 세 가지입니다. 어느 경우든 이번 호출로 큐잉한 작업이 완료되었다는 뜻은 아닙니다.

  • 커널의 첫 실행: 다른 스트림에서 같은 커널의 바이너리 업로드가 진행 중이면, ha_drv_kernel_launch는 그 업로드가 끝날 때까지 호스트에서 기다린 뒤 반환할 수 있습니다.
  • 스테이징을 거치는 N-D 복사: ha_drv_memcpy_nd가 호스트 스테이징 버퍼를 쓰는 호스트→디바이스 복사는 반환 전에 원본을 스테이징 버퍼로 복사해 둡니다. 그래서 이 경우에는 반환 직후 원본 버퍼를 해제해도 됩니다.
  • 스테이징 버퍼 한도 초과: 아직 동기화되지 않은 스테이징 버퍼의 프로세스 전체 합계가 HA_MEMCPYND_ASYNC_STAGING_MAX_UNSYNCED_BYTES를 넘은 상태에서 ha_drv_memcpy_nd가 스테이징을 쓰면, 큐잉 전에 그 복사를 받을 스트림을 먼저 동기화합니다. 이때는 그 스트림에 앞서 큐잉한 작업이 끝날 때까지 반환하지 않습니다.

런타임 API의 동기 함수(HaLaunchKernel, HaMemCpy)에 해당하는 블로킹 동작이 필요하면, 작업 큐잉 직후 같은 스트림을 대상으로 ha_drv_wait(HA_WAIT_STREAM_SYNC)를 호출하십시오.

주의: 호스트 버퍼 수명

비동기 복사에 전달한 호스트 버퍼는 해당 스트림의 완료를 동기화(ha_drv_wait)하기 전까지 해제, 재할당, 값 수정을 해서는 안 됩니다. 반환 시점에는 호스트↔디바이스 전송이 아직 진행 중일 수 있습니다.


다음 단계