Skip to content

Callback Params

ha_callback_params.h is a collection of structs that carry the arguments of a specific Ha* call to a callback when that call is instrumented. Each struct below corresponds to one Ha* call, and its fields hold the arguments passed to that call as is.

The enter/exit hooks that actually fill these structs and pass them to registered subscribers, and the subscription API (HaApiEnter/HaApiExit/HaSubscribe/HaUnsubscribe), are owned by a separate component (interceptor), not by hart (runtime), so this page does not cover them.

Contents

Parameter struct (Params) Corresponding runtime API function
HaSetDeviceParams HaSetDevice
HaResetDeviceParams HaResetDevice
HaResetAllDevicesParams HaResetAllDevices
HaMemAllocParams HaMemAlloc, HaMemAlloc3D
HaMemAllocAsyncParams HaMemAllocAsync
HaMemFreeParams HaMemFree
HaMemFreeAsyncParams HaMemFreeAsync
HaMemCpyParams HaMemCpy
HaMemCpyAsyncParams HaMemCpyAsync
HaMemCpyNdParams HaMemCpyNd
HaMemCpyNdAsyncParams HaMemCpyNdAsync
HaMemLoadFileAsyncParams HaMemLoadFileAsync
HaLibraryLoadDataParams HaLibraryLoadData
HaLaunchKernelParams HaLaunchKernel
HaLaunchKernelAsyncParams HaLaunchKernelAsync
HaStreamParams HaStreamSynchronize, HaStreamQuery
HaStreamWaitEventParams HaStreamWaitEvent
HaEventRecordParams HaEventRecord
HaEventParams HaEventSynchronize, HaEventQuery

HaSetDeviceParams

Args for HaSetDevice.

Field Type Description
device_id int Target device index.

HaResetDeviceParams

Args for HaResetDevice.

Field Type Description
device_id int Target device index.

HaResetAllDevicesParams

Args for HaResetAllDevices. HaResetAllDevices takes no arguments; the field exists only because an empty struct is not valid C.

Field Type Description
reserved uint8_t Unused; always 0.

HaMemAllocParams

Args for HaMemAlloc and HaMemAlloc3D.

Field Type Description
ptr uint64_t * Out device pointer (HaDevicePtr*).
size size_t Allocation size in bytes (1-D variant; 0 when is_3d).
is_interleaved int Non-zero if interleaved across channels.
is_3d int Non-zero for the HaMemAlloc3D variant (w / h / c valid).
w size_t 3D width (valid when is_3d).
h size_t 3D height (valid when is_3d).
c size_t 3D channel (valid when is_3d).

Note

is_3d determines which fields are valid: 0 means a flat buffer of size bytes (HaMemAlloc), and 1 means a 3D shape (HaMemAlloc3D), in which case w/h/c are valid and size is 0.


HaMemAllocAsyncParams

Args for HaMemAllocAsync.

Field Type Description
ptr uint64_t * Out device pointer (HaDevicePtr*).
size size_t Allocation size in bytes.
is_interleaved int Non-zero if interleaved across channels.
stream void * Stream the allocation is enqueued on (HaStream_t).

HaMemFreeParams

Args for HaMemFree.

Field Type Description
ptr uint64_t Device pointer to free (HaDevicePtr).

HaMemFreeAsyncParams

Args for HaMemFreeAsync.

Field Type Description
ptr uint64_t Device pointer to free (HaDevicePtr).
stream void * Stream the free is enqueued on (HaStream_t).

HaMemCpyParams

Args for HaMemCpy.

Field Type Description
dst uint64_t Destination pointer (HaDevicePtr).
src uint64_t Source pointer (HaDevicePtr).
size size_t Number of bytes to copy.
direction int Copy direction (numeric HaMemCpyDirection).

HaMemCpyAsyncParams

Args for HaMemCpyAsync.

Field Type Description
dst uint64_t Destination pointer (HaDevicePtr).
src uint64_t Source pointer (HaDevicePtr).
size size_t Number of bytes to copy.
direction int Copy direction (numeric HaMemCpyDirection).
stream void * Stream the copy is enqueued on (HaStream_t).

HaMemCpyNdParams

Args for HaMemCpyNd. The extent is carried as the two HaLayout descriptors rather than a byte count. They are void pointers because HaLayout is C++-only (ha_types.h).

Field Type Description
dst uint64_t Destination pointer (HaDevicePtr).
dst_layout const void * Destination layout (const HaLayout *).
src uint64_t Source pointer (HaDevicePtr).
src_layout const void * Source layout (const HaLayout *).

HaMemCpyNdAsyncParams

Args for HaMemCpyNdAsync. Mirrors HaMemCpyNdParams.

Field Type Description
dst uint64_t Destination pointer (HaDevicePtr).
dst_layout const void * Destination layout (const HaLayout *).
src uint64_t Source pointer (HaDevicePtr).
src_layout const void * Source layout (const HaLayout *).
stream void * Stream the copy is enqueued on (HaStream_t).

HaMemLoadFileAsyncParams

Args for HaMemLoadFileAsync.

Field Type Description
file_fd int Source file descriptor.
file_off size_t Byte offset within the file.
dst uint64_t Destination pointer (HaDevicePtr).
len size_t Number of bytes to load.
stream void * Stream the load is enqueued on (HaStream_t).

HaLibraryLoadDataParams

Args for HaLibraryLoadData.

Field Type Description
library void * Where the new library handle (HaLibrary_t) is written.
data const void * The library data (a HaLibraryData).

HaLaunchKernelParams

Args for HaLaunchKernel.

Field Type Description
kernel void * Kernel handle (HaKernel_t) as passed; NULL for the binary-path overload.
kernel_name const char * Name of kernel; NULL if kernel is not a valid handle or for a path.
binary_path const char * Kernel binary path; NULL for the kernel-handle overload.

Note

Which fields are filled depends on the overload called. The runtime fills the values below and passes them to the callback.

  • Kernel-handle overload: fills kernel (and kernel_name if the handle is valid); binary_path is NULL.
  • Binary-path overload: fills binary_path; kernel and kernel_name are NULL.

HaLaunchKernelAsyncParams

Args for HaLaunchKernelAsync.

Field Type Description
kernel void * As in HaLaunchKernelParams.
kernel_name const char * As in HaLaunchKernelParams.
binary_path const char * As in HaLaunchKernelParams.
stream void * Stream the launch is enqueued on (HaStream_t).

HaStreamParams

Args for HaStreamSynchronize and HaStreamQuery.

Field Type Description
stream void * Stream being fenced or polled (HaStream_t; NULL is the caller's default stream).

HaStreamWaitEventParams

Args for HaStreamWaitEvent.

Field Type Description
stream void * Stream that will wait (HaStream_t).
event void * Event waited on (HaEvent_t).

HaEventRecordParams

Args for HaEventRecord.

Field Type Description
event void * Event being recorded (HaEvent_t).
stream void * Stream the record is enqueued on (HaStream_t).

HaEventParams

Args for HaEventSynchronize and HaEventQuery.

Field Type Description
event void * Event being waited on or polled (HaEvent_t).