콘텐츠로 이동

Driver API (ha_drv_*)

드라이버 API(ha_drv_*)는 디바이스를 다루는 모든 함수가 디바이스 핸들을 받는 디바이스 핸들 기반 API입니다. CUDA Driver API에 대응합니다. 개념적 이해와 세부 사용 순서는 드라이버 API 가이드를 참고하십시오.

1
#include "ha_driver_api.h"

ha_driver_api.h includes ha_driver_types.h, which declares the driver types (HaDrv*). A header that needs a driver type but no driver function can include ha_driver_types.h alone.

빌드 및 링크 설정

CMake 패키지 hart의 hart::ha_umd_core 타깃을 링크하십시오. 상위 런타임 API와 함께 사용하는 경우 hart::ha_hart만 링크해도 됩니다.

1
2
find_package(hart REQUIRED COMPONENTS hw)
target_link_libraries(your_target PRIVATE hart::ha_umd_core)

섹션

페이지 내용
Device 디바이스 부트스트랩, 핸들 Open/Close, 디바이스 속성(Attributes) 조회, 디바이스 리셋
Memory 디바이스 메모리 할당 및 해제, 1-D/N-D 데이터 복사(Memcpy), 디바이스 메모리 통계, 호스트 메모리 할당
Execution 커널 라이브러리 등록과 커널 조회, 커널 로드(파일·라이브러리)·실행·해제
Streams & Events 스트림 및 이벤트 생성·파괴, 작업 큐잉(Queueing), 호스트 동기화 대기
TLB 정적 KV 캐시 TLB 및 페이지 테이블(Page-table) TLB 구성
Types 열거형(Enum), 핸들 타입, 구조체 정의

공통 규칙

본 규칙은 모든 드라이버 API 진입점에 공통 적용되며, 개별 페이지에서 반복 설명하지 않습니다.

  1. 디바이스 핸들 기반 호출: 디바이스를 다루는 모든 함수는 디바이스 핸들을 첫 번째 인자로 받습니다. 핸들은 ha_drv_open()으로 생성하고 ha_drv_close()로 해제합니다. 복수 디바이스를 한 번에 제어하는 함수는 제공되지 않습니다. 다음 함수는 디바이스 핸들을 받지 않습니다: 핸들을 얻기 전에 쓰는 ha_drv_scan_devices·ha_drv_init·ha_drv_deinit·ha_drv_get_device_count·ha_drv_open, 디바이스와 무관한 호스트 메모리 함수 ha_drv_host_mem_*와 커널 라이브러리 함수 ha_drv_library_*, 이미 만든 인자 목록만 고치는 ha_drv_launch_args_set_*.
  2. 기본 스트림(HA_STREAM_DEFAULT): 호출 스레드가 해당 디바이스에서 사용하는 기본 스트림입니다. 최초 사용 시 자동 생성되며, 동일 프로세스 내 런타임 API가 같은 스레드·디바이스에서 사용하는 기본 스트림과 같은 스트림입니다. 이 스트림의 핸들을 돌려주는 함수는 없습니다. 디바이스 메모리 할당과 해제 (ha_drv_malloc, ha_drv_malloc_3d, ha_drv_free)는 스트림 순서를 따르지 않으므로 stream 인자를 무시합니다.
  3. 비동기 실행 모델: 메모리 복사와 커널 실행은 항상 비동기로 동작합니다. 작업을 큐에 등록한 직후 반환되며, 완료 여부는 ha_drv_wait()로 확인합니다. 실행 중 발생한 오류는 스트림에 남아 다음 대기 시점에 반환됩니다. 단, 커널의 첫 실행이 다른 스트림에서 아직 진행 중인 그 커널의 바이너리 복사를 만나면, ha_drv_kernel_launch()는 복사가 끝날 때까지 호스트에서 기다립니다.
  4. 리셋 시 핸들 무효화: 디바이스 리셋(ha_drv_reset()) 이후에는 이전의 모든 하위 핸들(스트림, 이벤트, 메모리 할당, 커널)이 무효화됩니다. 디바이스 핸들을 제외한 모든 하위 객체를 다시 만들어야 합니다.
  5. 런타임 API와 혼용 금지: 같은 디바이스에 런타임 API(Ha*)와 드라이버 API를 함께 쓰지 마십시오. 런타임이 관리하는 주소·스트림·이벤트 정보가 드라이버 API 호출과 어긋납니다. 자세한 내용은 드라이버 API 가이드를 참고하십시오.