콘텐츠로 이동

Python Execution API

함수 시그니처 비고
launch_kernel_with_binary_path (binary_path: str, args: HaLaunchArgs) -> None 디바이스 실행 완료 시점까지 블로킹
launch_kernel_async_with_binary_path (binary_path: str, args: HaLaunchArgs, stream: int = HA_STREAM_DEFAULT) -> None 스트림에 큐잉한 뒤 즉시 반환
library_load_data (data: int) -> int 미리 컴파일된 커널 라이브러리를 등록하고 라이브러리 핸들을 반환. 디바이스를 사용하지 않음
library_get_kernel (library: int, name: str) -> int 라이브러리에서 이름이 name인 커널의 핸들을 반환
launch_kernel_with_handle (kernel: int, args: HaLaunchArgs) -> None 라이브러리 커널을 실행하고 디바이스 실행 완료까지 블로킹
launch_kernel_async_with_handle (kernel: int, args: HaLaunchArgs, stream: int = HA_STREAM_DEFAULT) -> None 라이브러리 커널 실행을 스트림에 큐잉한 뒤 즉시 반환

args 파라미터는 단일 HaLaunchArgs 객체여야 합니다. Python list 같은 컬렉션을 직접 전달하면 TypeError가 발생합니다.

실행 함수는 제어를 반환하기 전에 인자 목록의 모든 데이터를 읽어들이므로, 호출이 끝난 직후 인자 객체를 해제하거나 값을 바꿔도 안전합니다. 비동기 실행에서도 마찬가지입니다.


커널 라이브러리

미리 컴파일된 커널을 담은 라이브러리를 등록하고, 이름으로 얻은 커널 핸들로 실행합니다. 라이브러리 핸들과 커널 핸들은 불투명한 int이며 프로세스가 끝날 때까지 유효합니다. 대응하는 C++ API는 Execution API를 참고하십시오.

  • library_load_data()의 data는 확장 모듈에 빌드되어 들어간 HaLibraryData의 주소이며, 그 모듈이 제공합니다. 데이터는 복사되지 않으므로 프로세스가 끝날 때까지 유효해야 합니다. 호출할 때마다 새 라이브러리가 등록됩니다.
  • library_get_kernel()은 같은 이름에 대해 항상 같은 핸들을 반환하며, 이후 어느 디바이스에서 실행하든 같습니다.
  • 라이브러리 커널은 Legato 커널입니다. 디바이스마다 첫 실행 때 그 디바이스에 커널이 로드됩니다.
  • launch_kernel_async_with_handle()은 인자를 호출 중에 모두 읽고 큐잉되면 반환합니다. 디바이스 실행 실패는 이후 호출에서 드러납니다.
발생 상황 결과
library_load_data()에 0을 넘김 RuntimeError(HaInvalidArgument)
라이브러리 데이터가 잘못됨 RuntimeError(HaKernelInvalidArgument)
이 hart가 읽지 못하는 형식의 라이브러리 RuntimeError(HaKernelUnsupported)
library_get_kernel()에 0을 넘김 RuntimeError(HaInvalidArgument)
library_load_data()가 반환하지 않은 라이브러리 핸들 RuntimeError(HaKernelInvalidHandle)
라이브러리에 그 이름의 커널이 없음 RuntimeError(HaKernelNotFound)
library_get_kernel()이 반환하지 않은 커널 핸들로 실행 RuntimeError(HaKernelInvalidHandle)
라이브러리에 현재 디바이스용 커널 바이너리가 없음 RuntimeError(HaKernelNoBinaryForDevice)
커널이 받지 않는 인자 RuntimeError(HaKernelInvalidArgument)

HaLaunchArgs

커널 실행 한 회차에 사용할 인자들을 추가된 순서대로 관리하는 객체입니다. 커널 ABI 규격에 맞춰 인자가 기록되는 내부 구조는 공개되지 않으며, 호출부는 아래 메서드로만 인자를 다룹니다.

1
from hart import HaDataType, HaLaunchArgRoute, HaLaunchArgs
메서드 시그니처 용도
HaLaunchArgs() () -> HaLaunchArgs 빈 인자 목록 객체 생성
add_tensor (route: HaLaunchArgRoute, target_core: int, da: int, dims: list[int], offset: int = 0) -> None Tensor 인자 추가
add_scalar (route: HaLaunchArgRoute, target_core: int, dtype: HaDataType, bits: int) -> None Scalar 인자 추가
add_array (route: HaLaunchArgRoute, target_core: int, dims: list[int], raw_data: bytes \| bytearray \| memoryview, strides: list[int] \| None = None) -> None Array 인자 추가 (데이터는 내부로 복사됨)
set_tensor (index: int, da: int, dims: list[int]) -> None index번째 Tensor의 주소와 차원 교체
set_scalar_bits (index: int, bits: int) -> None index번째 Scalar의 값 교체
set_array (index: int, dims: list[int], raw_data: bytes \| bytearray \| memoryview) -> None index번째 Array의 차원과 데이터 교체
  • 스레드 안전성: 한 HaLaunchArgs 객체는 여러 스레드에서 안전하게 공유할 수 있습니다. 객체 내부의 잠금이 인자 추가·교체와 커널 실행이 겹치지 않도록 하나씩 차례로 처리합니다. 다만 값 교체와 커널 실행이 동시에 겹칠 때 실행이 교체 전과 후 중 어느 값을 쓸지는 정해져 있지 않습니다.
  • 디바이스 검증: 인자를 추가할 때는 현재 디바이스(set_device())를 기준으로 유효성을 검사합니다 (예: CORE route에서 지정한 코어 번호). 현재 디바이스를 지정하지 않은 상태에서 add_*를 호출하면 RuntimeError(HaDeviceNotInitialized)가 발생합니다. 값 교체(set_*)는 이미 담긴 인자의 값만 바꾸므로 디바이스가 필요 없습니다.
  • 디바이스 주소: 디바이스 메모리 주소(da)는 int로 직접 넘깁니다. PyCapsule이나 ctypes 정수 같은 래퍼 타입으로 감싸지 마십시오.
  • 값 교체 제약: set_*의 index는 add_*로 인자를 추가한 순서이며 0부터 셉니다. 처음 추가할 때 정한 route, target_core, dtype은 유지되며, Tensor와 Array의 차원 수(rank)는 바꿀 수 없습니다.
  • C++ API 대응: Python의 각 메서드는 C++의 HaLaunchArgs 클래스와 HaLaunchArgsAdd*() / HaLaunchArgsSet*() 함수에 1:1로 대응합니다. 상세 파라미터 조건은 C++ Execution API를 참고하십시오.

route와 target_core

모든 인자에는 인자를 기록할 위치를 정하는 route와 target_core를 지정합니다.

  • route: 인자를 기록할 ABI 블록을 고릅니다. UNIVERSAL은 top 블록과 모든 코어 블록, TOP은 top 블록만, CORE는 target_core로 지정한 코어 하나의 블록입니다.
  • target_core: route가 CORE일 때만 의미가 있으며, 대상 코어 번호를 넘깁니다. 그 밖의 route에서는 무시되며 관례상 -1을 넘깁니다.

route는 커널이 컴파일될 때 정해진 것과 같아야 합니다.

add_scalar의 bits는 값의 비트 패턴입니다. dtype은 INT8, INT16, INT32, INT64, FLOAT16, BFLOAT16, FLOAT32, FLOAT64, FLOAT8 중 하나이며, 지정한 데이터 타입이 차지하는 하위 바이트만 읽습니다. 예를 들어 음수 INT32는 하위 4바이트의 2의 보수, FLOAT32는 하위 4바이트의 IEEE 754 비트 패턴으로 해석됩니다.

예외 및 오류 처리

발생 상황 결과
현재 디바이스를 지정하지 않음 add_* 시점에 RuntimeError(HaDeviceNotInitialized)
디바이스 리셋이 진행 중 add_* 시점에 RuntimeError(HaDeviceNotReady)
지원하지 않는 dtype, 잘못된 route, 현재 디바이스에 없는 코어 번호 등 인자 구성 규칙 위반 추가·교체 시점에 RuntimeError(HaKernelInvalidArgument), 목록은 바뀌지 않음
인자의 종류·개수·route가 커널 선언과 다르거나, 실행 디바이스에 없는 코어를 가리킴 커널 실행이 RuntimeError(HaKernelInvalidArgument)로 거부되며, 기대한 규격과 전달된 규격이 로그에 기록됨

예제

launch_kernel_with_binary_path

바이너리 파일 경로를 지정해 동기 방식으로 커널을 실행합니다. 디바이스별 첫 실행 때 커널 로드가 함께 수행됩니다.

커널 메타데이터는 디바이스별로 캐싱되므로, 벤치마크에서 첫 회차 실행에는 순수 연산이 아닌 로드 시간이 포함됩니다. 정확히 측정하려면 본 측정 전에 반드시 워밍업을 거치십시오.

예제
1
2
3
4
5
6
7
8
9
import hart
from hart import HaLaunchArgRoute, HaLaunchArgs

hart.set_device(0)  # 인자는 현재 디바이스를 기준으로 검사됨
args = HaLaunchArgs()
args.add_tensor(HaLaunchArgRoute.UNIVERSAL, -1, input_ptr, [m, k])
args.add_tensor(HaLaunchArgRoute.UNIVERSAL, -1, weight_ptr, [k, n])
args.add_tensor(HaLaunchArgRoute.UNIVERSAL, -1, output_ptr, [m, n])
hart.launch_kernel_with_binary_path("/path/to/kernel.bin", args)

launch_kernel_async_with_binary_path

같은 스트림에 메모리 전송과 커널 실행을 차례로 큐잉하고, 호스트는 완료를 기다리지 않고 바로 다음 작업을 진행합니다.

예제
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import hart
from hart import HaDataType, HaLaunchArgRoute, HaLaunchArgs

args = HaLaunchArgs()
args.add_tensor(HaLaunchArgRoute.UNIVERSAL, -1, dev_in, [10, 512])
args.add_scalar(HaLaunchArgRoute.TOP, -1, HaDataType.INT64, bits=7)

hart.mem_cpy_async(dev_in, host_in, n, hart.HaMemCpyDirection.HostToDevice, stream)
hart.launch_kernel_async_with_binary_path(kernel_path, args, stream)
hart.mem_cpy_async(host_out, dev_out, n, hart.HaMemCpyDirection.DeviceToHost, stream)

hart.stream_synchronize(stream)  # 이 시점에 전송과 커널 실행이 모두 완료됨

launch_kernel_with_handle

라이브러리를 한 번 등록하고 커널 핸들을 얻어 실행합니다. library_data_address는 라이브러리를 담은 확장 모듈이 제공하는 HaLibraryData 주소입니다.

예제
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import hart
from hart import HaLaunchArgRoute, HaLaunchArgs

library = hart.library_load_data(library_data_address)  # 프로세스당 한 번
matmul = hart.library_get_kernel(library, "matmul")

hart.set_device(0)
args = HaLaunchArgs()
args.add_tensor(HaLaunchArgRoute.UNIVERSAL, -1, input_ptr, [m, k])
args.add_tensor(HaLaunchArgRoute.UNIVERSAL, -1, output_ptr, [m, n])
hart.launch_kernel_with_handle(matmul, args)  # 디바이스 0에서 처음 실행할 때 커널이 로드됨

launch_kernel_async_with_handle

커널 핸들로 스트림에 실행을 큐잉합니다.

예제
1
2
hart.launch_kernel_async_with_handle(matmul, args, stream)
hart.stream_synchronize(stream)

인자 객체를 재사용한 반복 실행

같은 인자 구성으로 커널 실행을 반복할 때는 매번 객체를 새로 만들지 말고, 기존 인자 목록 객체를 재사용하면서 값만 교체하는 방식을 권장합니다.

예제
1
2
3
4
5
6
7
8
args = HaLaunchArgs()
args.add_tensor(HaLaunchArgRoute.UNIVERSAL, -1, buf_a, [10, 512])   # index 0 (Tensor)
args.add_scalar(HaLaunchArgRoute.TOP, -1, HaDataType.INT64, bits=7)  # index 1 (Scalar)

for step in range(steps):
    args.set_tensor(0, da=bufs[step], dims=[10, 512])
    args.set_scalar_bits(1, step)
    hart.launch_kernel_async_with_binary_path(kernel_path, args, stream)

함께 보기