Core API#

oneAPI Unified Runtime Specification - Version 0.6

Common#

Common Enums#

ur_result_t#

enum ur_result_t#

Defines Return/Error codes.

Values:

enumerator UR_RESULT_SUCCESS#

Success.

enumerator UR_RESULT_ERROR_INVALID_OPERATION#

Invalid operation.

enumerator UR_RESULT_ERROR_INVALID_QUEUE_PROPERTIES#

Invalid queue properties.

enumerator UR_RESULT_ERROR_INVALID_QUEUE#

Invalid queue.

enumerator UR_RESULT_ERROR_INVALID_VALUE#

Invalid Value.

enumerator UR_RESULT_ERROR_INVALID_CONTEXT#

Invalid context.

enumerator UR_RESULT_ERROR_INVALID_PLATFORM#

Invalid platform.

enumerator UR_RESULT_ERROR_INVALID_BINARY#

Invalid binary.

enumerator UR_RESULT_ERROR_INVALID_PROGRAM#

Invalid program.

enumerator UR_RESULT_ERROR_INVALID_SAMPLER#

Invalid sampler.

enumerator UR_RESULT_ERROR_INVALID_BUFFER_SIZE#

Invalid buffer size.

enumerator UR_RESULT_ERROR_INVALID_MEM_OBJECT#

Invalid memory object.

enumerator UR_RESULT_ERROR_INVALID_EVENT#

Invalid event.

enumerator UR_RESULT_ERROR_INVALID_EVENT_WAIT_LIST#

Returned when the event wait list or the events in the wait list are invalid.

enumerator UR_RESULT_ERROR_MISALIGNED_SUB_BUFFER_OFFSET#

Misaligned sub buffer offset.

enumerator UR_RESULT_ERROR_INVALID_WORK_GROUP_SIZE#

Invalid work group size.

enumerator UR_RESULT_ERROR_COMPILER_NOT_AVAILABLE#

Compiler not available.

enumerator UR_RESULT_ERROR_PROFILING_INFO_NOT_AVAILABLE#

Profiling info not available.

enumerator UR_RESULT_ERROR_DEVICE_NOT_FOUND#

Device not found.

enumerator UR_RESULT_ERROR_INVALID_DEVICE#

Invalid device.

enumerator UR_RESULT_ERROR_DEVICE_LOST#

Device hung, reset, was removed, or adapter update occurred.

enumerator UR_RESULT_ERROR_DEVICE_REQUIRES_RESET#

Device requires a reset.

enumerator UR_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE#

Device currently in low power state.

enumerator UR_RESULT_ERROR_DEVICE_PARTITION_FAILED#

Device paritioning failed.

enumerator UR_RESULT_ERROR_INVALID_DEVICE_PARTITION_COUNT#

Invalid counts provided with UR_DEVICE_PARTITION_BY_COUNTS.

enumerator UR_RESULT_ERROR_INVALID_WORK_ITEM_SIZE#

Invalid work item size.

enumerator UR_RESULT_ERROR_INVALID_WORK_DIMENSION#

Invalid work dimension.

enumerator UR_RESULT_ERROR_INVALID_KERNEL_ARGS#

Invalid kernel args.

enumerator UR_RESULT_ERROR_INVALID_KERNEL#

Invalid kernel.

enumerator UR_RESULT_ERROR_INVALID_KERNEL_NAME#

[Validation] kernel name is not found in the program

enumerator UR_RESULT_ERROR_INVALID_KERNEL_ARGUMENT_INDEX#

[Validation] kernel argument index is not valid for kernel

enumerator UR_RESULT_ERROR_INVALID_KERNEL_ARGUMENT_SIZE#

[Validation] kernel argument size does not match kernel

enumerator UR_RESULT_ERROR_INVALID_KERNEL_ATTRIBUTE_VALUE#

[Validation] value of kernel attribute is not valid for the kernel or device

enumerator UR_RESULT_ERROR_INVALID_IMAGE_SIZE#

Invalid image size.

enumerator UR_RESULT_ERROR_INVALID_IMAGE_FORMAT_DESCRIPTOR#

Invalid image format descriptor.

enumerator UR_RESULT_ERROR_IMAGE_FORMAT_NOT_SUPPORTED#

Image format not supported.

enumerator UR_RESULT_ERROR_MEM_OBJECT_ALLOCATION_FAILURE#

Memory object allocation failure.

enumerator UR_RESULT_ERROR_INVALID_PROGRAM_EXECUTABLE#

Program object parameter is invalid.

enumerator UR_RESULT_ERROR_UNINITIALIZED#

[Validation] adapter is not initialized

enumerator UR_RESULT_ERROR_OUT_OF_HOST_MEMORY#

Insufficient host memory to satisfy call.

enumerator UR_RESULT_ERROR_OUT_OF_DEVICE_MEMORY#

Insufficient device memory to satisfy call.

enumerator UR_RESULT_ERROR_OUT_OF_RESOURCES#

Out of resources.

enumerator UR_RESULT_ERROR_PROGRAM_BUILD_FAILURE#

Error occurred when building program, see build log for details.

enumerator UR_RESULT_ERROR_PROGRAM_LINK_FAILURE#

Error occurred when linking programs, see build log for details.

enumerator UR_RESULT_ERROR_UNSUPPORTED_VERSION#

[Validation] generic error code for unsupported versions

enumerator UR_RESULT_ERROR_UNSUPPORTED_FEATURE#

[Validation] generic error code for unsupported features

enumerator UR_RESULT_ERROR_INVALID_ARGUMENT#

[Validation] generic error code for invalid arguments

enumerator UR_RESULT_ERROR_INVALID_NULL_HANDLE#

[Validation] handle argument is not valid

enumerator UR_RESULT_ERROR_HANDLE_OBJECT_IN_USE#

[Validation] object pointed to by handle still in-use by device

enumerator UR_RESULT_ERROR_INVALID_NULL_POINTER#

[Validation] pointer argument may not be nullptr

enumerator UR_RESULT_ERROR_INVALID_SIZE#

[Validation] invalid size or dimensions (e.g., must not be zero, or is out of bounds)

enumerator UR_RESULT_ERROR_UNSUPPORTED_SIZE#

[Validation] size argument is not supported by the device (e.g., too large)

enumerator UR_RESULT_ERROR_UNSUPPORTED_ALIGNMENT#

[Validation] alignment argument is not supported by the device (e.g., too small)

enumerator UR_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT#

[Validation] synchronization object in invalid state

enumerator UR_RESULT_ERROR_INVALID_ENUMERATION#

[Validation] enumerator argument is not valid

enumerator UR_RESULT_ERROR_UNSUPPORTED_ENUMERATION#

[Validation] enumerator argument is not supported by the device

enumerator UR_RESULT_ERROR_UNSUPPORTED_IMAGE_FORMAT#

[Validation] image format is not supported by the device

enumerator UR_RESULT_ERROR_INVALID_NATIVE_BINARY#

[Validation] native binary is not supported by the device

enumerator UR_RESULT_ERROR_INVALID_GLOBAL_NAME#

[Validation] global variable is not found in the program

enumerator UR_RESULT_ERROR_INVALID_FUNCTION_NAME#

[Validation] function name is not found in the program

enumerator UR_RESULT_ERROR_INVALID_GROUP_SIZE_DIMENSION#

[Validation] group size dimension is not valid for the kernel or device

enumerator UR_RESULT_ERROR_INVALID_GLOBAL_WIDTH_DIMENSION#

[Validation] global width dimension is not valid for the kernel or device

enumerator UR_RESULT_ERROR_PROGRAM_UNLINKED#

[Validation] compiled program or program with imports needs to be linked before kernels can be created from it.

enumerator UR_RESULT_ERROR_OVERLAPPING_REGIONS#

[Validation] copy operations do not support overlapping regions of memory

enumerator UR_RESULT_ERROR_INVALID_HOST_PTR#

Invalid host pointer.

enumerator UR_RESULT_ERROR_INVALID_USM_SIZE#

Invalid USM size.

enumerator UR_RESULT_ERROR_OBJECT_ALLOCATION_FAILURE#

Objection allocation failure.

enumerator UR_RESULT_ERROR_ADAPTER_SPECIFIC#

An adapter specific warning/error has been reported and can be retrieved via the urPlatformGetLastError entry point.

enumerator UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP#

Invalid Command-Buffer.

enumerator UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP#

Sync point is not valid for the command-buffer.

enumerator UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_WAIT_LIST_EXP#

Sync point wait list is invalid.

enumerator UR_RESULT_ERROR_UNKNOWN#

Unknown or internal error

ur_structure_type_t#

enum ur_structure_type_t#

Defines structure types.

Values:

enumerator UR_STRUCTURE_TYPE_CONTEXT_PROPERTIES#

ur_context_properties_t

enumerator UR_STRUCTURE_TYPE_IMAGE_DESC#

ur_image_desc_t

enumerator UR_STRUCTURE_TYPE_BUFFER_PROPERTIES#

ur_buffer_properties_t

enumerator UR_STRUCTURE_TYPE_BUFFER_REGION#

ur_buffer_region_t

enumerator UR_STRUCTURE_TYPE_BUFFER_CHANNEL_PROPERTIES#

ur_buffer_channel_properties_t

enumerator UR_STRUCTURE_TYPE_BUFFER_ALLOC_LOCATION_PROPERTIES#

ur_buffer_alloc_location_properties_t

enumerator UR_STRUCTURE_TYPE_PROGRAM_PROPERTIES#

ur_program_properties_t

enumerator UR_STRUCTURE_TYPE_USM_DESC#

ur_usm_desc_t

enumerator UR_STRUCTURE_TYPE_USM_HOST_DESC#

ur_usm_host_desc_t

enumerator UR_STRUCTURE_TYPE_USM_DEVICE_DESC#

ur_usm_device_desc_t

enumerator UR_STRUCTURE_TYPE_USM_POOL_DESC#

ur_usm_pool_desc_t

enumerator UR_STRUCTURE_TYPE_USM_POOL_LIMITS_DESC#

ur_usm_pool_limits_desc_t

enumerator UR_STRUCTURE_TYPE_DEVICE_BINARY#

ur_device_binary_t

enumerator UR_STRUCTURE_TYPE_SAMPLER_DESC#

ur_sampler_desc_t

enumerator UR_STRUCTURE_TYPE_QUEUE_PROPERTIES#

ur_queue_properties_t

enumerator UR_STRUCTURE_TYPE_QUEUE_INDEX_PROPERTIES#

ur_queue_properties_t

enumerator UR_STRUCTURE_TYPE_CONTEXT_NATIVE_PROPERTIES#

ur_context_native_properties_t

enumerator UR_STRUCTURE_TYPE_KERNEL_NATIVE_PROPERTIES#

ur_kernel_native_properties_t

enumerator UR_STRUCTURE_TYPE_QUEUE_NATIVE_PROPERTIES#

ur_queue_native_properties_t

enumerator UR_STRUCTURE_TYPE_MEM_NATIVE_PROPERTIES#

ur_mem_native_properties_t

enumerator UR_STRUCTURE_TYPE_EVENT_NATIVE_PROPERTIES#

ur_event_native_properties_t

enumerator UR_STRUCTURE_TYPE_PLATFORM_NATIVE_PROPERTIES#

ur_platform_native_properties_t

enumerator UR_STRUCTURE_TYPE_DEVICE_NATIVE_PROPERTIES#

ur_device_native_properties_t

enumerator UR_STRUCTURE_TYPE_PROGRAM_NATIVE_PROPERTIES#

ur_program_native_properties_t

enumerator UR_STRUCTURE_TYPE_SAMPLER_NATIVE_PROPERTIES#

ur_sampler_native_properties_t

enumerator UR_STRUCTURE_TYPE_QUEUE_NATIVE_DESC#

ur_queue_native_desc_t

enumerator UR_STRUCTURE_TYPE_DEVICE_PARTITION_PROPERTIES#

ur_device_partition_properties_t

enumerator UR_STRUCTURE_TYPE_KERNEL_ARG_MEM_OBJ_PROPERTIES#

ur_kernel_arg_mem_obj_properties_t

enumerator UR_STRUCTURE_TYPE_PHYSICAL_MEM_PROPERTIES#

ur_physical_mem_properties_t

enumerator UR_STRUCTURE_TYPE_KERNEL_ARG_POINTER_PROPERTIES#

ur_kernel_arg_pointer_properties_t

enumerator UR_STRUCTURE_TYPE_KERNEL_ARG_SAMPLER_PROPERTIES#

ur_kernel_arg_sampler_properties_t

enumerator UR_STRUCTURE_TYPE_KERNEL_EXEC_INFO_PROPERTIES#

ur_kernel_exec_info_properties_t

enumerator UR_STRUCTURE_TYPE_KERNEL_ARG_VALUE_PROPERTIES#

ur_kernel_arg_value_properties_t

enumerator UR_STRUCTURE_TYPE_KERNEL_ARG_LOCAL_PROPERTIES#

ur_kernel_arg_local_properties_t

enumerator UR_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_DESC#

ur_exp_command_buffer_desc_t

enumerator UR_STRUCTURE_TYPE_EXP_SAMPLER_MIP_PROPERTIES#

ur_exp_sampler_mip_properties_t

Common Structures#

ur_base_properties_t#

struct ur_base_properties_t#

Base for all properties types.

Public Members

ur_structure_type_t stype#

[in] type of this structure

void *pNext#

[in,out][optional] pointer to extension-specific structure

ur_base_desc_t#

struct ur_base_desc_t#

Base for all descriptor types.

Public Members

ur_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] pointer to extension-specific structure

ur_rect_offset_t#

struct ur_rect_offset_t#

3D offset argument passed to buffer rect operations

Public Members

uint64_t x#

[in] x offset (bytes)

uint64_t y#

[in] y offset (scalar)

uint64_t z#

[in] z offset (scalar)

ur_rect_region_t#

struct ur_rect_region_t#

3D region argument passed to buffer rect operations

Public Members

uint64_t width#

[in] width (bytes)

uint64_t height#

[in] height (scalar)

uint64_t depth#

[in] scalar (scalar)

Runtime#

Runtime Functions#

urInit#

UR_APIEXPORT ur_result_t UR_APICALL urInit(ur_device_init_flags_t device_flags)#

Initialize the ‘oneAPI’ adapter(s)

  • The application must call this function before calling any other function.

  • If this function is not called then all other functions will return UR_RESULT_ERROR_UNINITIALIZED.

  • Only one instance of each adapter will be initialized per process.

  • The application may call this function multiple times with different flags or environment variables enabled.

  • The application must call this function after forking new processes. Each forked process must call this function.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe for scenarios where multiple libraries may initialize the adapter(s) simultaneously.

Parameters

device_flags – [in] device initialization flags. must be 0 (default) or a combination of ur_device_init_flag_t.

Returns

urTearDown#

UR_APIEXPORT ur_result_t UR_APICALL urTearDown(void *pParams)#

Tear down the ‘oneAPI’ instance and release all its resources.

Parameters

pParams – [in] pointer to tear down parameters

Returns

Runtime Enums#

ur_device_init_flags_t#

enum ur_device_init_flag_t#

Values:

enumerator UR_DEVICE_INIT_FLAG_GPU#

initialize GPU device adapters.

enumerator UR_DEVICE_INIT_FLAG_CPU#

initialize CPU device adapters.

enumerator UR_DEVICE_INIT_FLAG_FPGA#

initialize FPGA device adapters.

enumerator UR_DEVICE_INIT_FLAG_MCA#

initialize MCA device adapters.

enumerator UR_DEVICE_INIT_FLAG_VPU#

initialize VPU device adapters.

Platform#

Platform Functions#

urPlatformGet#

UR_APIEXPORT ur_result_t UR_APICALL urPlatformGet(uint32_t NumEntries, ur_platform_handle_t *phPlatforms, uint32_t *pNumPlatforms)#

Retrieves all available platforms.

  • Multiple calls to this function will return identical platforms handles, in the same order.

  • The application may call this function from simultaneous threads, the implementation must be thread-safe

Remark

Analogues

  • clGetPlatformIDs

Parameters

  • NumEntries – [in] the number of platforms to be added to phPlatforms. If phPlatforms is not NULL, then NumEntries should be greater than zero, otherwise UR_RESULT_ERROR_INVALID_SIZE, will be returned.

  • phPlatforms – [out][optional][range(0, NumEntries)] array of handle of platforms. If NumEntries is less than the number of platforms available, then urPlatformGet shall only retrieve that number of platforms.

  • pNumPlatforms – [out][optional] returns the total number of platforms available.

Returns

urPlatformGetInfo#

UR_APIEXPORT ur_result_t UR_APICALL urPlatformGetInfo(ur_platform_handle_t hPlatform, ur_platform_info_t propName, size_t propSize, void *pPropValue, size_t *pPropSizeRet)#

Retrieves various information about platform.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Remark

Analogues

  • clGetPlatformInfo

Parameters

  • hPlatform – [in] handle of the platform

  • propName – [in] type of the info to retrieve

  • propSize – [in] the number of bytes pointed to by pPlatformInfo.

  • pPropValue – [out][optional][typename(propName, propSize)] array of bytes holding the info. If Size is not equal to or greater to the real number of bytes needed to return the info then the UR_RESULT_ERROR_INVALID_SIZE error is returned and pPlatformInfo is not used.

  • pPropSizeRet – [out][optional] pointer to the actual number of bytes being queried by pPlatformInfo.

Returns

urPlatformGetApiVersion#

UR_APIEXPORT ur_result_t UR_APICALL urPlatformGetApiVersion(ur_platform_handle_t hPlatform, ur_api_version_t *pVersion)#

Returns the API version supported by the specified platform.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters

  • hPlatform – [in] handle of the platform

  • pVersion – [out] api version

Returns

urPlatformGetNativeHandle#

UR_APIEXPORT ur_result_t UR_APICALL urPlatformGetNativeHandle(ur_platform_handle_t hPlatform, ur_native_handle_t *phNativePlatform)#

Return platform native platform handle.

  • Retrieved native handle can be used for direct interaction with the native platform driver.

  • Use interoperability platform extensions to convert native handle to native type.

  • The application may call this function from simultaneous threads for the same context.

  • The implementation of this function should be thread-safe.

Parameters

  • hPlatform – [in] handle of the platform.

  • phNativePlatform – [out] a pointer to the native handle of the platform.

Returns

urPlatformCreateWithNativeHandle#

UR_APIEXPORT ur_result_t UR_APICALL urPlatformCreateWithNativeHandle(ur_native_handle_t hNativePlatform, const ur_platform_native_properties_t *pProperties, ur_platform_handle_t *phPlatform)#

Create runtime platform object from native platform handle.

  • Creates runtime platform handle from native driver platform handle.

  • The application may call this function from simultaneous threads for the same context.

  • The implementation of this function should be thread-safe.

Parameters

  • hNativePlatform – [in] the native handle of the platform.

  • pProperties – [in][optional] pointer to native platform properties struct.

  • phPlatform – [out] pointer to the handle of the platform object created.

Returns

urPlatformGetBackendOption#

UR_APIEXPORT ur_result_t UR_APICALL urPlatformGetBackendOption(ur_platform_handle_t hPlatform, const char *pFrontendOption, const char **ppPlatformOption)#

Get the platform specific compiler backend option from a generic frontend option.

  • The string returned via the ppPlatformOption is a NULL terminated C style string.

  • The string returned via the ppPlatformOption is thread local.

  • The memory in the string returned via the ppPlatformOption is owned by the adapter.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters

  • hPlatform – [in] handle of the platform instance.

  • pFrontendOption – [in] string containing the frontend option.

  • ppPlatformOption – [out] returns the correct platform specific compiler option based on the frontend option.

Returns

urPlatformGetLastError#

UR_APIEXPORT ur_result_t UR_APICALL urPlatformGetLastError(ur_platform_handle_t hPlatform, const char **ppMessage, int32_t *pError)#

Get the last adapter specific error.

To be used after another entry-point has returned UR_RESULT_ERROR_ADAPTER_SPECIFIC in order to retrieve a message describing the circumstances of the underlying driver error and the error code returned by the failed driver entry-point.

  • Implementations must store the message and error code in thread-local storage prior to returning UR_RESULT_ERROR_ADAPTER_SPECIFIC.

  • The message and error code storage is will only be valid if a previously called entry-point returned UR_RESULT_ERROR_ADAPTER_SPECIFIC.

  • The memory pointed to by the C string returned in ppMessage is owned by the adapter and must be null terminated.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Example usage:

if (::urQueueCreate(hContext, hDevice, nullptr, &hQueue) ==
        ::UR_RESULT_ERROR_ADAPTER_SPECIFIC) {
    const char* pMessage;
    int32_t error;
    ::urPlatformGetLastError(hPlatform, &pMessage, &error);
}

Parameters

  • hPlatform – [in] handle of the platform instance

  • ppMessage – [out] pointer to a C string where the adapter specific error message will be stored.

  • pError – [out] pointer to an integer where the adapter specific error code will be stored.

Returns

Platform Enums#

ur_platform_info_t#

enum ur_platform_info_t#

Supported platform info.

Values:

enumerator UR_PLATFORM_INFO_NAME#

[char[]] The string denoting name of the platform. The size of the info needs to be dynamically queried.

enumerator UR_PLATFORM_INFO_VENDOR_NAME#

[char[]] The string denoting name of the vendor of the platform. The size of the info needs to be dynamically queried.

enumerator UR_PLATFORM_INFO_VERSION#

[char[]] The string denoting the version of the platform. The size of the info needs to be dynamically queried.

enumerator UR_PLATFORM_INFO_EXTENSIONS#

[char[]] The string denoting extensions supported by the platform. The size of the info needs to be dynamically queried.

enumerator UR_PLATFORM_INFO_PROFILE#

[char[]] The string denoting profile of the platform. The size of the info needs to be dynamically queried.

enumerator UR_PLATFORM_INFO_BACKEND#

[ur_platform_backend_t] The backend of the platform. Identifies the native backend adapter implementing this platform.

ur_api_version_t#

enum ur_api_version_t#

Supported API versions.

  • API versions contain major and minor attributes, use UR_MAJOR_VERSION and UR_MINOR_VERSION

Values:

enumerator UR_API_VERSION_0_6#

version 0.6

enumerator UR_API_VERSION_CURRENT#

latest known version

ur_platform_backend_t#

enum ur_platform_backend_t#

Identifies native backend adapters.

Values:

enumerator UR_PLATFORM_BACKEND_UNKNOWN#

The backend is not a recognized one.

enumerator UR_PLATFORM_BACKEND_LEVEL_ZERO#

The backend is Level Zero.

enumerator UR_PLATFORM_BACKEND_OPENCL#

The backend is OpenCL.

enumerator UR_PLATFORM_BACKEND_CUDA#

The backend is CUDA.

enumerator UR_PLATFORM_BACKEND_HIP#

The backend is HIP

Platform Structures#

ur_platform_native_properties_t#

struct ur_platform_native_properties_t#

Native platform creation properties.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_PLATFORM_NATIVE_PROPERTIES

void *pNext#

[in,out][optional] pointer to extension-specific structure

bool isNativeHandleOwned#

[in] Indicates UR owns the native handle or if it came from an interoperability operation in the application that asked to not transfer the ownership to the unified-runtime.

Device#

Device Functions#

urDeviceGet#

UR_APIEXPORT ur_result_t UR_APICALL urDeviceGet(ur_platform_handle_t hPlatform, ur_device_type_t DeviceType, uint32_t NumEntries, ur_device_handle_t *phDevices, uint32_t *pNumDevices)#

Retrieves devices within a platform.

  • Multiple calls to this function will return identical device handles, in the same order.

  • The number and order of handles returned from this function can be affected by environment variables that filter devices exposed through API.

  • The returned devices are taken a reference of and must be released with a subsequent call to urDeviceRelease.

  • The application may call this function from simultaneous threads, the implementation must be thread-safe

Remark

Analogues

  • clGetDeviceIDs

Parameters

  • hPlatform – [in] handle of the platform instance

  • DeviceType – [in] the type of the devices.

  • NumEntries – [in] the number of devices to be added to phDevices. If phDevices in not NULL then NumEntries should be greater than zero, otherwise UR_RESULT_ERROR_INVALID_VALUE, will be returned.

  • phDevices – [out][optional][range(0, NumEntries)] array of handle of devices. If NumEntries is less than the number of devices available, then platform shall only retrieve that number of devices.

  • pNumDevices – [out][optional] pointer to the number of devices. pNumDevices will be updated with the total number of devices available.

Returns

urDeviceGetInfo#

UR_APIEXPORT ur_result_t UR_APICALL urDeviceGetInfo(ur_device_handle_t hDevice, ur_device_info_t propName, size_t propSize, void *pPropValue, size_t *pPropSizeRet)#

Retrieves various information about device.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Remark

Analogues

  • clGetDeviceInfo

Parameters

  • hDevice – [in] handle of the device instance

  • propName – [in] type of the info to retrieve

  • propSize – [in] the number of bytes pointed to by pPropValue.

  • pPropValue – [out][optional][typename(propName, propSize)] array of bytes holding the info. If propSize is not equal to or greater than the real number of bytes needed to return the info then the UR_RESULT_ERROR_INVALID_SIZE error is returned and pPropValue is not used.

  • pPropSizeRet – [out][optional] pointer to the actual size in bytes of the queried propName.

Returns

urDeviceRetain#

UR_APIEXPORT ur_result_t UR_APICALL urDeviceRetain(ur_device_handle_t hDevice)#

Makes a reference of the device handle indicating it’s in use until paired urDeviceRelease is called.

  • Increments the device reference count if hDevice is a valid sub-device created by a call to urDevicePartition. If hDevice is a root level device (e.g. obtained with urDeviceGet), the reference count remains unchanged.

  • It is not valid to use the device handle, which has all of its references released.

  • The application may call this function from simultaneous threads for the same device.

  • The implementation of this function should be thread-safe.

Remark

Analogues

  • clRetainDevice

Parameters

hDevice – [in] handle of the device to get a reference of.

Returns

urDeviceRelease#

UR_APIEXPORT ur_result_t UR_APICALL urDeviceRelease(ur_device_handle_t hDevice)#

Releases the device handle reference indicating end of its usage.

  • Decrements the device reference count if hDevice is a valid sub-device created by a call to urDevicePartition. If hDevice is a root level device (e.g. obtained with urDeviceGet), the reference count remains unchanged.

  • The application may call this function from simultaneous threads for the same device.

  • The implementation of this function should be thread-safe.

Remark

Analogues

  • clReleaseDevice

Parameters

hDevice – [in] handle of the device to release.

Returns

urDevicePartition#

UR_APIEXPORT ur_result_t UR_APICALL urDevicePartition(ur_device_handle_t hDevice, const ur_device_partition_properties_t *pProperties, uint32_t NumDevices, ur_device_handle_t *phSubDevices, uint32_t *pNumDevicesRet)#

Partition the device into sub-devices.

  • Repeated calls to this function with the same inputs will produce the same output in the same order.

  • The function may be called to request a further partitioning of a sub-device into sub-sub-devices, and so on.

  • The application may call this function from simultaneous threads for the same device.

  • The implementation of this function should be thread-safe.

Remark

Analogues

  • clCreateSubDevices

Parameters

  • hDevice – [in] handle of the device to partition.

  • pProperties – [in] Device partition properties.

  • NumDevices – [in] the number of sub-devices.

  • phSubDevices – [out][optional][range(0, NumDevices)] array of handle of devices. If NumDevices is less than the number of sub-devices available, then the function shall only retrieve that number of sub-devices.

  • pNumDevicesRet – [out][optional] pointer to the number of sub-devices the device can be partitioned into according to the partitioning property.

Returns

urDeviceSelectBinary#

UR_APIEXPORT ur_result_t UR_APICALL urDeviceSelectBinary(ur_device_handle_t hDevice, const ur_device_binary_t *pBinaries, uint32_t NumBinaries, uint32_t *pSelectedBinary)#

Selects the most appropriate device binary based on runtime information and the IR characteristics.

  • The input binaries are various AOT images, and possibly an IL binary for JIT compilation.

  • The selected binary will be able to be run on the target device.

  • If no suitable binary can be found then function returns ${X}_INVALID_BINARY.

  • The application may call this function from simultaneous threads for the same device.

  • The implementation of this function should be thread-safe.

Parameters

  • hDevice – [in] handle of the device to select binary for.

  • pBinaries – [in] the array of binaries to select from.

  • NumBinaries – [in] the number of binaries passed in ppBinaries. Must greater than or equal to zero otherwise UR_RESULT_ERROR_INVALID_VALUE is returned.

  • pSelectedBinary – [out] the index of the selected binary in the input array of binaries. If a suitable binary was not found the function returns UR_RESULT_ERROR_INVALID_BINARY.

Returns

urDeviceGetNativeHandle#

UR_APIEXPORT ur_result_t UR_APICALL urDeviceGetNativeHandle(ur_device_handle_t hDevice, ur_native_handle_t *phNativeDevice)#

Return platform native device handle.

  • Retrieved native handle can be used for direct interaction with the native platform driver.

  • Use interoperability platform extensions to convert native handle to native type.

  • The application may call this function from simultaneous threads for the same context.

  • The implementation of this function should be thread-safe.

Parameters

  • hDevice – [in] handle of the device.

  • phNativeDevice – [out] a pointer to the native handle of the device.

Returns

urDeviceCreateWithNativeHandle#

UR_APIEXPORT ur_result_t UR_APICALL urDeviceCreateWithNativeHandle(ur_native_handle_t hNativeDevice, ur_platform_handle_t hPlatform, const ur_device_native_properties_t *pProperties, ur_device_handle_t *phDevice)#

Create runtime device object from native device handle.

  • Creates runtime device handle from native driver device handle.

  • The application may call this function from simultaneous threads for the same context.

  • The implementation of this function should be thread-safe.

Parameters

  • hNativeDevice – [in] the native handle of the device.

  • hPlatform – [in] handle of the platform instance

  • pProperties – [in][optional] pointer to native device properties struct.

  • phDevice – [out] pointer to the handle of the device object created.

Returns

urDeviceGetGlobalTimestamps#

UR_APIEXPORT ur_result_t UR_APICALL urDeviceGetGlobalTimestamps(ur_device_handle_t hDevice, uint64_t *pDeviceTimestamp, uint64_t *pHostTimestamp)#

Returns synchronized Host and Device global timestamps.

  • The application may call this function from simultaneous threads for the same context.

  • The implementation of this function should be thread-safe.

Remark

Analogues

  • clGetDeviceAndHostTimer

Parameters

  • hDevice – [in] handle of the device instance

  • pDeviceTimestamp – [out][optional] pointer to the Device’s global timestamp that correlates with the Host’s global timestamp value

  • pHostTimestamp – [out][optional] pointer to the Host’s global timestamp that correlates with the Device’s global timestamp value

Returns

Device Enums#

ur_device_type_t#

enum ur_device_type_t#

Supported device types.

Values:

enumerator UR_DEVICE_TYPE_DEFAULT#

The default device type as preferred by the runtime.

enumerator UR_DEVICE_TYPE_ALL#

Devices of all types.

enumerator UR_DEVICE_TYPE_GPU#

Graphics Processing Unit.

enumerator UR_DEVICE_TYPE_CPU#

Central Processing Unit.

enumerator UR_DEVICE_TYPE_FPGA#

Field Programmable Gate Array.

enumerator UR_DEVICE_TYPE_MCA#

Memory Copy Accelerator.

enumerator UR_DEVICE_TYPE_VPU#

Vision Processing Unit

ur_device_info_t#

enum ur_device_info_t#

Supported device info.

Values:

enumerator UR_DEVICE_INFO_TYPE#

[ur_device_type_t] type of the device

enumerator UR_DEVICE_INFO_VENDOR_ID#

[uint32_t] vendor Id of the device

enumerator UR_DEVICE_INFO_DEVICE_ID#

[uint32_t] Id of the device

enumerator UR_DEVICE_INFO_MAX_COMPUTE_UNITS#

[uint32_t] the number of compute units

enumerator UR_DEVICE_INFO_MAX_WORK_ITEM_DIMENSIONS#

[uint32_t] max work item dimensions

enumerator UR_DEVICE_INFO_MAX_WORK_ITEM_SIZES#

[size_t[]] return an array of max work item sizes

enumerator UR_DEVICE_INFO_MAX_WORK_GROUP_SIZE#

[size_t] max work group size

enumerator UR_DEVICE_INFO_SINGLE_FP_CONFIG#

[ur_device_fp_capability_flags_t] single precision floating point capability

enumerator UR_DEVICE_INFO_HALF_FP_CONFIG#

[ur_device_fp_capability_flags_t] half precision floating point capability

enumerator UR_DEVICE_INFO_DOUBLE_FP_CONFIG#

[ur_device_fp_capability_flags_t] double precision floating point capability

enumerator UR_DEVICE_INFO_QUEUE_PROPERTIES#

[ur_queue_flags_t] command queue properties supported by the device

enumerator UR_DEVICE_INFO_PREFERRED_VECTOR_WIDTH_CHAR#

[uint32_t] preferred vector width for char

enumerator UR_DEVICE_INFO_PREFERRED_VECTOR_WIDTH_SHORT#

[uint32_t] preferred vector width for short

enumerator UR_DEVICE_INFO_PREFERRED_VECTOR_WIDTH_INT#

[uint32_t] preferred vector width for int

enumerator UR_DEVICE_INFO_PREFERRED_VECTOR_WIDTH_LONG#

[uint32_t] preferred vector width for long

enumerator UR_DEVICE_INFO_PREFERRED_VECTOR_WIDTH_FLOAT#

[uint32_t] preferred vector width for float

enumerator UR_DEVICE_INFO_PREFERRED_VECTOR_WIDTH_DOUBLE#

[uint32_t] preferred vector width for double

enumerator UR_DEVICE_INFO_PREFERRED_VECTOR_WIDTH_HALF#

[uint32_t] preferred vector width for half float

enumerator UR_DEVICE_INFO_NATIVE_VECTOR_WIDTH_CHAR#

[uint32_t] native vector width for char

enumerator UR_DEVICE_INFO_NATIVE_VECTOR_WIDTH_SHORT#

[uint32_t] native vector width for short

enumerator UR_DEVICE_INFO_NATIVE_VECTOR_WIDTH_INT#

[uint32_t] native vector width for int

enumerator UR_DEVICE_INFO_NATIVE_VECTOR_WIDTH_LONG#

[uint32_t] native vector width for long

enumerator UR_DEVICE_INFO_NATIVE_VECTOR_WIDTH_FLOAT#

[uint32_t] native vector width for float

enumerator UR_DEVICE_INFO_NATIVE_VECTOR_WIDTH_DOUBLE#

[uint32_t] native vector width for double

enumerator UR_DEVICE_INFO_NATIVE_VECTOR_WIDTH_HALF#

[uint32_t] native vector width for half float

enumerator UR_DEVICE_INFO_MAX_CLOCK_FREQUENCY#

[uint32_t] max clock frequency in MHz

enumerator UR_DEVICE_INFO_MEMORY_CLOCK_RATE#

[uint32_t] memory clock frequency in MHz

enumerator UR_DEVICE_INFO_ADDRESS_BITS#

[uint32_t] address bits

enumerator UR_DEVICE_INFO_MAX_MEM_ALLOC_SIZE#

[uint64_t] max memory allocation size

enumerator UR_DEVICE_INFO_IMAGE_SUPPORTED#

[ur_bool_t] images are supported

enumerator UR_DEVICE_INFO_MAX_READ_IMAGE_ARGS#

[uint32_t] max number of image objects arguments of a kernel declared with the read_only qualifier

enumerator UR_DEVICE_INFO_MAX_WRITE_IMAGE_ARGS#

[uint32_t] max number of image objects arguments of a kernel declared with the write_only qualifier

enumerator UR_DEVICE_INFO_MAX_READ_WRITE_IMAGE_ARGS#

[uint32_t] max number of image objects arguments of a kernel declared with the read_write qualifier

enumerator UR_DEVICE_INFO_IMAGE2D_MAX_WIDTH#

[size_t] max width of Image2D object

enumerator UR_DEVICE_INFO_IMAGE2D_MAX_HEIGHT#

[size_t] max heigh of Image2D object

enumerator UR_DEVICE_INFO_IMAGE3D_MAX_WIDTH#

[size_t] max width of Image3D object

enumerator UR_DEVICE_INFO_IMAGE3D_MAX_HEIGHT#

[size_t] max height of Image3D object

enumerator UR_DEVICE_INFO_IMAGE3D_MAX_DEPTH#

[size_t] max depth of Image3D object

enumerator UR_DEVICE_INFO_IMAGE_MAX_BUFFER_SIZE#

[size_t] max image buffer size

enumerator UR_DEVICE_INFO_IMAGE_MAX_ARRAY_SIZE#

[size_t] max image array size

enumerator UR_DEVICE_INFO_MAX_SAMPLERS#

[uint32_t] max number of samplers that can be used in a kernel

enumerator UR_DEVICE_INFO_MAX_PARAMETER_SIZE#

[size_t] max size in bytes of all arguments passed to a kernel

enumerator UR_DEVICE_INFO_MEM_BASE_ADDR_ALIGN#

[uint32_t] memory base address alignment

enumerator UR_DEVICE_INFO_GLOBAL_MEM_CACHE_TYPE#

[ur_device_mem_cache_type_t] global memory cache type

enumerator UR_DEVICE_INFO_GLOBAL_MEM_CACHELINE_SIZE#

[uint32_t] global memory cache line size in bytes

enumerator UR_DEVICE_INFO_GLOBAL_MEM_CACHE_SIZE#

[uint64_t] size of global memory cache in bytes

enumerator UR_DEVICE_INFO_GLOBAL_MEM_SIZE#

[uint64_t] size of global memory in bytes

enumerator UR_DEVICE_INFO_GLOBAL_MEM_FREE#

[uint64_t] size of global memory which is free in bytes

enumerator UR_DEVICE_INFO_MAX_CONSTANT_BUFFER_SIZE#

[uint64_t] max constant buffer size in bytes

enumerator UR_DEVICE_INFO_MAX_CONSTANT_ARGS#

[uint32_t] max number of __const declared arguments in a kernel

enumerator UR_DEVICE_INFO_LOCAL_MEM_TYPE#

[ur_device_local_mem_type_t] local memory type

enumerator UR_DEVICE_INFO_LOCAL_MEM_SIZE#

[uint64_t] local memory size in bytes

enumerator UR_DEVICE_INFO_ERROR_CORRECTION_SUPPORT#

[ur_bool_t] support error correction to global and local memory

enumerator UR_DEVICE_INFO_HOST_UNIFIED_MEMORY#

[ur_bool_t] unified host device memory

enumerator UR_DEVICE_INFO_PROFILING_TIMER_RESOLUTION#

[size_t] profiling timer resolution in nanoseconds

enumerator UR_DEVICE_INFO_ENDIAN_LITTLE#

[ur_bool_t] little endian byte order

enumerator UR_DEVICE_INFO_AVAILABLE#

[ur_bool_t] device is available

enumerator UR_DEVICE_INFO_COMPILER_AVAILABLE#

[ur_bool_t] device compiler is available

enumerator UR_DEVICE_INFO_LINKER_AVAILABLE#

[ur_bool_t] device linker is available

enumerator UR_DEVICE_INFO_EXECUTION_CAPABILITIES#

[ur_device_exec_capability_flags_t] device kernel execution capability bit-field

enumerator UR_DEVICE_INFO_QUEUE_ON_DEVICE_PROPERTIES#

[ur_queue_flags_t] device command queue property bit-field

enumerator UR_DEVICE_INFO_QUEUE_ON_HOST_PROPERTIES#

[ur_queue_flags_t] host queue property bit-field

enumerator UR_DEVICE_INFO_BUILT_IN_KERNELS#

[char[]] a semi-colon separated list of built-in kernels

enumerator UR_DEVICE_INFO_PLATFORM#

[ur_platform_handle_t] the platform associated with the device

enumerator UR_DEVICE_INFO_REFERENCE_COUNT#

[uint32_t] Reference count of the device object. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.

enumerator UR_DEVICE_INFO_IL_VERSION#

[char[]] IL version

enumerator UR_DEVICE_INFO_NAME#

[char[]] Device name

enumerator UR_DEVICE_INFO_VENDOR#

[char[]] Device vendor

enumerator UR_DEVICE_INFO_DRIVER_VERSION#

[char[]] Driver version

enumerator UR_DEVICE_INFO_PROFILE#

[char[]] Device profile

enumerator UR_DEVICE_INFO_VERSION#

[char[]] Device version

enumerator UR_DEVICE_INFO_BACKEND_RUNTIME_VERSION#

[char[]] Version of backend runtime

enumerator UR_DEVICE_INFO_EXTENSIONS#

[char[]] Return a space separated list of extension names

enumerator UR_DEVICE_INFO_PRINTF_BUFFER_SIZE#

[size_t] Maximum size in bytes of internal printf buffer

enumerator UR_DEVICE_INFO_PREFERRED_INTEROP_USER_SYNC#

[ur_bool_t] prefer user synchronization when sharing object with other API

enumerator UR_DEVICE_INFO_PARENT_DEVICE#

[ur_device_handle_t] return parent device handle

enumerator UR_DEVICE_INFO_SUPPORTED_PARTITIONS#

[ur_device_partition_t[]] Returns an array of partition types supported by the device

enumerator UR_DEVICE_INFO_PARTITION_MAX_SUB_DEVICES#

[uint32_t] maximum number of sub-devices when the device is partitioned

enumerator UR_DEVICE_INFO_PARTITION_AFFINITY_DOMAIN#

[ur_device_affinity_domain_flags_t] Returns a bit-field of the supported affinity domains for partitioning. If the device does not support any affinity domains, then 0 will be returned.

enumerator UR_DEVICE_INFO_PARTITION_TYPE#

[ur_device_partition_property_t[]] return an array of ur_device_partition_property_t for properties specified in urDevicePartition

enumerator UR_DEVICE_INFO_MAX_NUM_SUB_GROUPS#

[uint32_t] max number of sub groups

enumerator UR_DEVICE_INFO_SUB_GROUP_INDEPENDENT_FORWARD_PROGRESS#

[ur_bool_t] support sub group independent forward progress

enumerator UR_DEVICE_INFO_SUB_GROUP_SIZES_INTEL#

[uint32_t[]] return an array of sub group sizes supported on Intel device

enumerator UR_DEVICE_INFO_USM_HOST_SUPPORT#

[ur_device_usm_access_capability_flags_t] support USM host memory access

enumerator UR_DEVICE_INFO_USM_DEVICE_SUPPORT#

[ur_device_usm_access_capability_flags_t] support USM device memory access

enumerator UR_DEVICE_INFO_USM_SINGLE_SHARED_SUPPORT#

[ur_device_usm_access_capability_flags_t] support USM single device shared memory access

enumerator UR_DEVICE_INFO_USM_CROSS_SHARED_SUPPORT#

[ur_device_usm_access_capability_flags_t] support USM cross device shared memory access

enumerator UR_DEVICE_INFO_USM_SYSTEM_SHARED_SUPPORT#

[ur_device_usm_access_capability_flags_t] support USM system wide shared memory access

enumerator UR_DEVICE_INFO_UUID#

[char[]] return device UUID

enumerator UR_DEVICE_INFO_PCI_ADDRESS#

[char[]] return device PCI address

enumerator UR_DEVICE_INFO_GPU_EU_COUNT#

[uint32_t] return Intel GPU EU count

enumerator UR_DEVICE_INFO_GPU_EU_SIMD_WIDTH#

[uint32_t] return Intel GPU EU SIMD width

enumerator UR_DEVICE_INFO_GPU_EU_SLICES#

[uint32_t] return Intel GPU number of slices

enumerator UR_DEVICE_INFO_GPU_EU_COUNT_PER_SUBSLICE#

[uint32_t] return Intel GPU EU count per subslice

enumerator UR_DEVICE_INFO_GPU_SUBSLICES_PER_SLICE#

[uint32_t] return Intel GPU number of subslices per slice

enumerator UR_DEVICE_INFO_GPU_HW_THREADS_PER_EU#

[uint32_t] return Intel GPU number of threads per EU

enumerator UR_DEVICE_INFO_MAX_MEMORY_BANDWIDTH#

[uint32_t] return max memory bandwidth in Mb/s

enumerator UR_DEVICE_INFO_IMAGE_SRGB#

[ur_bool_t] device supports sRGB images

enumerator UR_DEVICE_INFO_BUILD_ON_SUBDEVICE#

[ur_bool_t] Return true if sub-device should do its own program build

enumerator UR_DEVICE_INFO_ATOMIC_64#

[ur_bool_t] support 64 bit atomics

enumerator UR_DEVICE_INFO_ATOMIC_MEMORY_ORDER_CAPABILITIES#

[ur_memory_order_capability_flags_t] return a bit-field of atomic memory order capabilities

enumerator UR_DEVICE_INFO_ATOMIC_MEMORY_SCOPE_CAPABILITIES#

[ur_memory_scope_capability_flags_t] return a bit-field of atomic memory scope capabilities

enumerator UR_DEVICE_INFO_ATOMIC_FENCE_ORDER_CAPABILITIES#

[ur_memory_order_capability_flags_t] return a bit-field of atomic memory fence order capabilities

enumerator UR_DEVICE_INFO_ATOMIC_FENCE_SCOPE_CAPABILITIES#

[ur_memory_scope_capability_flags_t] return a bit-field of atomic memory fence scope capabilities

enumerator UR_DEVICE_INFO_BFLOAT16#

[ur_bool_t] support for bfloat16

enumerator UR_DEVICE_INFO_MAX_COMPUTE_QUEUE_INDICES#

[uint32_t] Returns 1 if the device doesn’t have a notion of a queue index. Otherwise, returns the number of queue indices that are available for this device.

enumerator UR_DEVICE_INFO_KERNEL_SET_SPECIALIZATION_CONSTANTS#

[ur_bool_t] support the urKernelSetSpecializationConstants entry point

enumerator UR_DEVICE_INFO_MEMORY_BUS_WIDTH#

[uint32_t] return the width in bits of the memory bus interface of the device.

enumerator UR_DEVICE_INFO_MAX_WORK_GROUPS_3D#

[size_t[3]] return max 3D work groups

enumerator UR_DEVICE_INFO_ASYNC_BARRIER#

[ur_bool_t] return true if Async Barrier is supported

enumerator UR_DEVICE_INFO_MEM_CHANNEL_SUPPORT#

[ur_bool_t] return true if specifying memory channels is supported

enumerator UR_DEVICE_INFO_HOST_PIPE_READ_WRITE_SUPPORTED#

[ur_bool_t] Return true if the device supports enqueueing commands to read and write pipes from the host.

enumerator UR_DEVICE_INFO_MAX_REGISTERS_PER_WORK_GROUP#

[uint32_t] The maximum number of registers available per block.

enumerator UR_DEVICE_INFO_IP_VERSION#

[uint32_t] The device IP version. The meaning of the device IP version is implementation-defined, but newer devices should have a higher version than older devices.

enumerator UR_DEVICE_INFO_BINDLESS_IMAGES_SUPPORT_EXP#

[ur_bool_t] returns true if the device supports the creation of bindless images

enumerator UR_DEVICE_INFO_BINDLESS_IMAGES_1D_USM_SUPPORT_EXP#

[ur_bool_t] returns true if the device supports the creation of 1D bindless images backed by USM

enumerator UR_DEVICE_INFO_BINDLESS_IMAGES_2D_USM_SUPPORT_EXP#

[ur_bool_t] returns true if the device supports the creation of 2D bindless images backed by USM

enumerator UR_DEVICE_INFO_BINDLESS_IMAGES_3D_USM_SUPPORT_EXP#

[ur_bool_t] returns true if the device supports the creation of 3D bindless images backed by USM

enumerator UR_DEVICE_INFO_IMAGE_PITCH_ALIGN_EXP#

[uint32_t] returns the required alignment of the pitch between two rows of an image in bytes

enumerator UR_DEVICE_INFO_MAX_IMAGE_LINEAR_WIDTH_EXP#

[size_t] returns the maximum linear width allowed for images allocated using USM

enumerator UR_DEVICE_INFO_MAX_IMAGE_LINEAR_HEIGHT_EXP#

[size_t] returns the maximum linear height allowed for images allocated using USM

enumerator UR_DEVICE_INFO_MAX_IMAGE_LINEAR_PITCH_EXP#

[size_t] returns the maximum linear pitch allowed for images allocated using USM

enumerator UR_DEVICE_INFO_MIPMAP_SUPPORT_EXP#

[ur_bool_t] returns true if the device supports allocating mipmap resources

enumerator UR_DEVICE_INFO_MIPMAP_ANISOTROPY_SUPPORT_EXP#

[ur_bool_t] returns true if the device supports sampling mipmap images with anisotropic filtering

enumerator UR_DEVICE_INFO_MIPMAP_MAX_ANISOTROPY_EXP#

[uint32_t] returns the maximum anisotropic ratio supported by the device

enumerator UR_DEVICE_INFO_MIPMAP_LEVEL_REFERENCE_SUPPORT_EXP#

[ur_bool_t] returns true if the device supports using images created from individual mipmap levels

enumerator UR_DEVICE_INFO_INTEROP_MEMORY_IMPORT_SUPPORT_EXP#

[ur_bool_t] returns true if the device supports importing external memory resources

enumerator UR_DEVICE_INFO_INTEROP_MEMORY_EXPORT_SUPPORT_EXP#

[ur_bool_t] returns true if the device supports exporting internal memory resources

enumerator UR_DEVICE_INFO_INTEROP_SEMAPHORE_IMPORT_SUPPORT_EXP#

[ur_bool_t] returns true if the device supports importing external semaphore resources

enumerator UR_DEVICE_INFO_INTEROP_SEMAPHORE_EXPORT_SUPPORT_EXP#

[ur_bool_t] returns true if the device supports exporting internal event resources

ur_device_affinity_domain_flags_t#

enum ur_device_affinity_domain_flag_t#

Values:

enumerator UR_DEVICE_AFFINITY_DOMAIN_FLAG_NUMA#

Split the device into sub devices comprised of compute units that share a NUMA node.

enumerator UR_DEVICE_AFFINITY_DOMAIN_FLAG_L4_CACHE#

Split the device into sub devices comprised of compute units that share a level 4 data cache.

enumerator UR_DEVICE_AFFINITY_DOMAIN_FLAG_L3_CACHE#

Split the device into sub devices comprised of compute units that share a level 3 data cache.

enumerator UR_DEVICE_AFFINITY_DOMAIN_FLAG_L2_CACHE#

Split the device into sub devices comprised of compute units that share a level 2 data cache.

enumerator UR_DEVICE_AFFINITY_DOMAIN_FLAG_L1_CACHE#

Split the device into sub devices comprised of compute units that share a level 1 data cache.

enumerator UR_DEVICE_AFFINITY_DOMAIN_FLAG_NEXT_PARTITIONABLE#

Split the device along the next partitionable affinity domain. The implementation shall find the first level along which the device or sub device may be further subdivided in the order: UR_DEVICE_AFFINITY_DOMAIN_FLAG_NUMA, UR_DEVICE_AFFINITY_DOMAIN_FLAG_L4_CACHE, UR_DEVICE_AFFINITY_DOMAIN_FLAG_L3_CACHE, UR_DEVICE_AFFINITY_DOMAIN_FLAG_L2_CACHE, UR_DEVICE_AFFINITY_DOMAIN_FLAG_L1_CACHE, and partition the device into sub devices comprised of compute units that share memory subsystems at this level.

ur_device_partition_t#

enum ur_device_partition_t#

Partition Properties.

Values:

enumerator UR_DEVICE_PARTITION_EQUALLY#

Partition Equally.

enumerator UR_DEVICE_PARTITION_BY_COUNTS#

Partition by counts.

enumerator UR_DEVICE_PARTITION_BY_AFFINITY_DOMAIN#

Partition by affinity domain.

enumerator UR_DEVICE_PARTITION_BY_CSLICE#

Partition by c-slice

ur_device_fp_capability_flags_t#

enum ur_device_fp_capability_flag_t#

Values:

enumerator UR_DEVICE_FP_CAPABILITY_FLAG_CORRECTLY_ROUNDED_DIVIDE_SQRT#

Support correctly rounded divide and sqrt.

enumerator UR_DEVICE_FP_CAPABILITY_FLAG_ROUND_TO_NEAREST#

Support round to nearest.

enumerator UR_DEVICE_FP_CAPABILITY_FLAG_ROUND_TO_ZERO#

Support round to zero.

enumerator UR_DEVICE_FP_CAPABILITY_FLAG_ROUND_TO_INF#

Support round to infinity.

enumerator UR_DEVICE_FP_CAPABILITY_FLAG_INF_NAN#

Support INF to NAN.

enumerator UR_DEVICE_FP_CAPABILITY_FLAG_DENORM#

Support denorm.

enumerator UR_DEVICE_FP_CAPABILITY_FLAG_FMA#

Support FMA.

enumerator UR_DEVICE_FP_CAPABILITY_FLAG_SOFT_FLOAT#

Basic floating point operations implemented in software.

ur_device_mem_cache_type_t#

enum ur_device_mem_cache_type_t#

Device memory cache type.

Values:

enumerator UR_DEVICE_MEM_CACHE_TYPE_NONE#

Has none cache.

enumerator UR_DEVICE_MEM_CACHE_TYPE_READ_ONLY_CACHE#

Has read only cache.

enumerator UR_DEVICE_MEM_CACHE_TYPE_READ_WRITE_CACHE#

Has read write cache

ur_device_local_mem_type_t#

enum ur_device_local_mem_type_t#

Device local memory type.

Values:

enumerator UR_DEVICE_LOCAL_MEM_TYPE_NONE#

No local memory support.

enumerator UR_DEVICE_LOCAL_MEM_TYPE_LOCAL#

Dedicated local memory.

enumerator UR_DEVICE_LOCAL_MEM_TYPE_GLOBAL#

Global memory

ur_device_exec_capability_flags_t#

enum ur_device_exec_capability_flag_t#

Values:

enumerator UR_DEVICE_EXEC_CAPABILITY_FLAG_KERNEL#

Support kernel execution.

enumerator UR_DEVICE_EXEC_CAPABILITY_FLAG_NATIVE_KERNEL#

Support native kernel execution

ur_memory_order_capability_flags_t#

enum ur_memory_order_capability_flag_t#

Values:

enumerator UR_MEMORY_ORDER_CAPABILITY_FLAG_RELAXED#

Relaxed memory ordering.

enumerator UR_MEMORY_ORDER_CAPABILITY_FLAG_ACQUIRE#

Acquire memory ordering.

enumerator UR_MEMORY_ORDER_CAPABILITY_FLAG_RELEASE#

Release memory ordering.

enumerator UR_MEMORY_ORDER_CAPABILITY_FLAG_ACQ_REL#

Acquire/release memory ordering.

enumerator UR_MEMORY_ORDER_CAPABILITY_FLAG_SEQ_CST#

Sequentially consistent memory ordering

ur_memory_scope_capability_flags_t#

enum ur_memory_scope_capability_flag_t#

Values:

enumerator UR_MEMORY_SCOPE_CAPABILITY_FLAG_WORK_ITEM#

Work item scope.

enumerator UR_MEMORY_SCOPE_CAPABILITY_FLAG_SUB_GROUP#

Sub group scope.

enumerator UR_MEMORY_SCOPE_CAPABILITY_FLAG_WORK_GROUP#

Work group scope.

enumerator UR_MEMORY_SCOPE_CAPABILITY_FLAG_DEVICE#

Device scope.

enumerator UR_MEMORY_SCOPE_CAPABILITY_FLAG_SYSTEM#

System scope

ur_device_usm_access_capability_flags_t#

enum ur_device_usm_access_capability_flag_t#

Values:

enumerator UR_DEVICE_USM_ACCESS_CAPABILITY_FLAG_ACCESS#

Memory can be accessed.

enumerator UR_DEVICE_USM_ACCESS_CAPABILITY_FLAG_ATOMIC_ACCESS#

Memory can be accessed atomically.

enumerator UR_DEVICE_USM_ACCESS_CAPABILITY_FLAG_CONCURRENT_ACCESS#

Memory can be accessed concurrently.

enumerator UR_DEVICE_USM_ACCESS_CAPABILITY_FLAG_ATOMIC_CONCURRENT_ACCESS#

Memory can be accessed atomically and concurrently

Device Structures#

ur_device_binary_t#

struct ur_device_binary_t#

Device Binary Type.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_DEVICE_BINARY

const void *pNext#

[in][optional] pointer to extension-specific structure

const char *pDeviceTargetSpec#

[in] null-terminated string representation of the device’s target architecture. For example:

  • UR_DEVICE_BINARY_TARGET_UNKNOWN

  • UR_DEVICE_BINARY_TARGET_SPIRV32

  • UR_DEVICE_BINARY_TARGET_SPIRV64

  • UR_DEVICE_BINARY_TARGET_SPIRV64_X86_64

  • UR_DEVICE_BINARY_TARGET_SPIRV64_GEN

  • UR_DEVICE_BINARY_TARGET_SPIRV64_FPGA

  • UR_DEVICE_BINARY_TARGET_NVPTX64

  • UR_DEVICE_BINARY_TARGET_AMDGCN

ur_device_partition_value_t#

union ur_device_partition_value_t#
#include <>

Device partition value.

Public Members

uint32_t equally#

[in] Number of compute units per sub-device when partitioning with UR_DEVICE_PARTITION_EQUALLY.

uint32_t count#

[in] Number of compute units in a sub-device when partitioning with UR_DEVICE_PARTITION_BY_COUNTS.

ur_device_affinity_domain_flags_t affinity_domain#

[in] The affinity domain to partition for when partitioning with $UR_DEVICE_PARTITION_BY_AFFINITY_DOMAIN.

ur_device_partition_property_t#

struct ur_device_partition_property_t#

Device partition property.

Public Members

ur_device_partition_t type#

[in] The partitioning type to be used.

ur_device_partition_value_t value#

[in] The paritioning value.

ur_device_partition_properties_t#

struct ur_device_partition_properties_t#

Device Partition Properties.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_DEVICE_PARTITION_PROPERTIES

void *pNext#

[in,out][optional] pointer to extension-specific structure

const ur_device_partition_property_t *pProperties#

[in] Pointer to the beginning of the properties array.

size_t PropCount#

[in] The length of properties pointed to by pProperties.

ur_device_native_properties_t#

struct ur_device_native_properties_t#

Native device creation properties.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_DEVICE_NATIVE_PROPERTIES

void *pNext#

[in,out][optional] pointer to extension-specific structure

bool isNativeHandleOwned#

[in] Indicates UR owns the native handle or if it came from an interoperability operation in the application that asked to not transfer the ownership to the unified-runtime.

Context#

Context Functions#

urContextCreate#

UR_APIEXPORT ur_result_t UR_APICALL urContextCreate(uint32_t DeviceCount, const ur_device_handle_t *phDevices, const ur_context_properties_t *pProperties, ur_context_handle_t *phContext)#

Creates a context with the given devices.

  • All devices should be from the same platform.

  • Context is used for resource sharing between all the devices associated with it.

  • Context also serves for resource isolation such that resources do not cross context boundaries.

  • The returned context is a reference and must be released with a subsequent call to urContextRelease.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Remark

Analogues

  • clCreateContext

Parameters

  • DeviceCount – [in] the number of devices given in phDevices

  • phDevices – [in][range(0, DeviceCount)] array of handle of devices.

  • pProperties – [in][optional] pointer to context creation properties.

  • phContext – [out] pointer to handle of context object created

Returns

urContextRetain#

UR_APIEXPORT ur_result_t UR_APICALL urContextRetain(ur_context_handle_t hContext)#

Makes a reference of the context handle indicating it’s in use until paired urContextRelease is called.

  • It is not valid to use a context handle, which has all of its references released.

  • The application may call this function from simultaneous threads for the same device.

  • The implementation of this function should be thread-safe.

Remark

Analogues

  • clRetainContext

Parameters

hContext – [in] handle of the context to get a reference of.

Returns

urContextRelease#

UR_APIEXPORT ur_result_t UR_APICALL urContextRelease(ur_context_handle_t hContext)#

Releases the context handle reference indicating end of its usage.

  • The application may call this function from simultaneous threads for the same context.

  • The implementation of this function should be thread-safe.

Remark

Analogues

  • clReleaseContext

Parameters

hContext – [in] handle of the context to release.

Returns

urContextGetInfo#

UR_APIEXPORT ur_result_t UR_APICALL urContextGetInfo(ur_context_handle_t hContext, ur_context_info_t propName, size_t propSize, void *pPropValue, size_t *pPropSizeRet)#

Retrieves various information about context.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Remark

Analogues

  • clGetContextInfo

Parameters

  • hContext – [in] handle of the context

  • propName – [in] type of the info to retrieve

  • propSize – [in] the number of bytes of memory pointed to by pPropValue.

  • pPropValue – [out][optional][typename(propName, propSize)] array of bytes holding the info. if propSize is not equal to or greater than the real number of bytes needed to return the info then the UR_RESULT_ERROR_INVALID_SIZE error is returned and pPropValue is not used.

  • pPropSizeRet – [out][optional] pointer to the actual size in bytes of the queried propName.

Returns

urContextGetNativeHandle#

UR_APIEXPORT ur_result_t UR_APICALL urContextGetNativeHandle(ur_context_handle_t hContext, ur_native_handle_t *phNativeContext)#

Return platform native context handle.

  • Retrieved native handle can be used for direct interaction with the native platform driver.

  • Use interoperability platform extensions to convert native handle to native type.

  • The application may call this function from simultaneous threads for the same context.

  • The implementation of this function should be thread-safe.

Parameters

  • hContext – [in] handle of the context.

  • phNativeContext – [out] a pointer to the native handle of the context.

Returns

urContextCreateWithNativeHandle#

UR_APIEXPORT ur_result_t UR_APICALL urContextCreateWithNativeHandle(ur_native_handle_t hNativeContext, uint32_t numDevices, const ur_device_handle_t *phDevices, const ur_context_native_properties_t *pProperties, ur_context_handle_t *phContext)#

Create runtime context object from native context handle.

  • Creates runtime context handle from native driver context handle.

  • The application may call this function from simultaneous threads for the same context.

  • The implementation of this function should be thread-safe.

Parameters

  • hNativeContext – [in] the native handle of the context.

  • numDevices – [in] number of devices associated with the context

  • phDevices – [in][range(0, numDevices)] list of devices associated with the context

  • pProperties – [in][optional] pointer to native context properties struct

  • phContext – [out] pointer to the handle of the context object created.

Returns

urContextSetExtendedDeleter#

UR_APIEXPORT ur_result_t UR_APICALL urContextSetExtendedDeleter(ur_context_handle_t hContext, ur_context_extended_deleter_t pfnDeleter, void *pUserData)#

Call extended deleter function as callback.

  • Calls extended deleter, a user-defined callback to delete context on some platforms.

  • This is done for performance reasons.

  • This API might be called directly by an application instead of a runtime backend.

  • The application may call this function from simultaneous threads for the same context.

  • The implementation of this function should be thread-safe.

Parameters

  • hContext – [in] handle of the context.

  • pfnDeleter – [in] Function pointer to extended deleter.

  • pUserData – [in][out][optional] pointer to data to be passed to callback.

Returns

Context Enums#

ur_context_flags_t#

enum ur_context_flag_t#

Values:

enumerator UR_CONTEXT_FLAG_TBD#

reserved for future use

ur_context_info_t#

enum ur_context_info_t#

Supported context info.

Values:

enumerator UR_CONTEXT_INFO_NUM_DEVICES#

[uint32_t] The number of the devices in the context

enumerator UR_CONTEXT_INFO_DEVICES#

[ur_device_handle_t[]] The array of the device handles in the context

enumerator UR_CONTEXT_INFO_REFERENCE_COUNT#

[uint32_t] Reference count of the context object. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.

enumerator UR_CONTEXT_INFO_USM_MEMCPY2D_SUPPORT#

[ur_bool_t] to indicate if the urEnqueueUSMMemcpy2D entrypoint is supported.

enumerator UR_CONTEXT_INFO_USM_FILL2D_SUPPORT#

[ur_bool_t] to indicate if the urEnqueueUSMFill2D entrypoint is supported.

enumerator UR_CONTEXT_INFO_ATOMIC_MEMORY_ORDER_CAPABILITIES#

[ur_memory_order_capability_flags_t] return a bit-field of atomic memory order capabilities.

enumerator UR_CONTEXT_INFO_ATOMIC_MEMORY_SCOPE_CAPABILITIES#

[ur_memory_scope_capability_flags_t] return a bit-field of atomic memory scope capabilities.

enumerator UR_CONTEXT_INFO_ATOMIC_FENCE_ORDER_CAPABILITIES#

[ur_memory_order_capability_flags_t] return a bit-field of atomic memory fence order capabilities. Zero is returned if the backend does not support context-level fences.

enumerator UR_CONTEXT_INFO_ATOMIC_FENCE_SCOPE_CAPABILITIES#

[ur_memory_scope_capability_flags_t] return a bit-field of atomic memory fence scope capabilities. Zero is returned if the backend does not support context-level fences.

Context Structures#

ur_context_properties_t#

struct ur_context_properties_t#

Context creation properties.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_CONTEXT_PROPERTIES

void *pNext#

[in,out][optional] pointer to extension-specific structure

ur_context_flags_t flags#

[in] context creation flags.

ur_context_native_properties_t#

struct ur_context_native_properties_t#

Properties for for urContextCreateWithNativeHandle.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_CONTEXT_NATIVE_PROPERTIES

void *pNext#

[in,out][optional] pointer to extension-specific structure

bool isNativeHandleOwned#

[in] Indicates UR owns the native handle or if it came from an interoperability operation in the application that asked to not transfer the ownership to the unified-runtime.

Memory#

Memory Functions#

urMemImageCreate#

UR_APIEXPORT ur_result_t UR_APICALL urMemImageCreate(ur_context_handle_t hContext, ur_mem_flags_t flags, const ur_image_format_t *pImageFormat, const ur_image_desc_t *pImageDesc, void *pHost, ur_mem_handle_t *phMem)#

Create an image object.

Remark

Analogues

  • clCreateImage

Parameters

  • hContext – [in] handle of the context object

  • flags – [in] allocation and usage information flags

  • pImageFormat – [in] pointer to image format specification

  • pImageDesc – [in] pointer to image description

  • pHost – [in][optional] pointer to the buffer data

  • phMem – [out] pointer to handle of image object created

Returns

urMemBufferCreate#

UR_APIEXPORT ur_result_t UR_APICALL urMemBufferCreate(ur_context_handle_t hContext, ur_mem_flags_t flags, size_t size, const ur_buffer_properties_t *pProperties, ur_mem_handle_t *phBuffer)#

Create a memory buffer.

Remark

Analogues

  • clCreateBuffer

Parameters

  • hContext – [in] handle of the context object

  • flags – [in] allocation and usage information flags

  • size – [in] size in bytes of the memory object to be allocated

  • pProperties – [in][optional] pointer to buffer creation properties

  • phBuffer – [out] pointer to handle of the memory buffer created

Returns

urMemRetain#

UR_APIEXPORT ur_result_t UR_APICALL urMemRetain(ur_mem_handle_t hMem)#

Get a reference the memory object. Increment the memory object’s reference count.

  • Useful in library function to retain access to the memory object after the caller released the object

Remark

Analogues

  • clRetainMemoryObject

Parameters

hMem – [in] handle of the memory object to get access

Returns

urMemRelease#

UR_APIEXPORT ur_result_t UR_APICALL urMemRelease(ur_mem_handle_t hMem)#

Decrement the memory object’s reference count and delete the object if the reference count becomes zero.

Remark

Analogues

  • clReleaseMemoryObject

Parameters

hMem – [in] handle of the memory object to release

Returns

urMemBufferPartition#

UR_APIEXPORT ur_result_t UR_APICALL urMemBufferPartition(ur_mem_handle_t hBuffer, ur_mem_flags_t flags, ur_buffer_create_type_t bufferCreateType, const ur_buffer_region_t *pRegion, ur_mem_handle_t *phMem)#

Create a sub buffer representing a region in an existing buffer.

Remark

Analogues

  • clCreateSubBuffer

Parameters

  • hBuffer – [in] handle of the buffer object to allocate from

  • flags – [in] allocation and usage information flags

  • bufferCreateType – [in] buffer creation type

  • pRegion – [in] pointer to buffer create region information

  • phMem – [out] pointer to the handle of sub buffer created

Returns

urMemGetNativeHandle#

UR_APIEXPORT ur_result_t UR_APICALL urMemGetNativeHandle(ur_mem_handle_t hMem, ur_native_handle_t *phNativeMem)#

Return platform native mem handle.

  • Retrieved native handle can be used for direct interaction with the native platform driver.

  • Use interoperability platform extensions to convert native handle to native type.

  • The application may call this function from simultaneous threads for the same context.

  • The implementation of this function should be thread-safe.

Parameters

  • hMem – [in] handle of the mem.

  • phNativeMem – [out] a pointer to the native handle of the mem.

Returns

urMemBufferCreateWithNativeHandle#

UR_APIEXPORT ur_result_t UR_APICALL urMemBufferCreateWithNativeHandle(ur_native_handle_t hNativeMem, ur_context_handle_t hContext, const ur_mem_native_properties_t *pProperties, ur_mem_handle_t *phMem)#

Create runtime buffer memory object from native memory handle.

  • The application may call this function from simultaneous threads for the same context.

  • The implementation of this function should be thread-safe.

Parameters

  • hNativeMem – [in] the native handle to the memory.

  • hContext – [in] handle of the context object.

  • pProperties – [in][optional] pointer to native memory creation properties.

  • phMem – [out] pointer to handle of buffer memory object created.

Returns

urMemImageCreateWithNativeHandle#

UR_APIEXPORT ur_result_t UR_APICALL urMemImageCreateWithNativeHandle(ur_native_handle_t hNativeMem, ur_context_handle_t hContext, const ur_image_format_t *pImageFormat, const ur_image_desc_t *pImageDesc, const ur_mem_native_properties_t *pProperties, ur_mem_handle_t *phMem)#

Create runtime image memory object from native memory handle.

  • The application may call this function from simultaneous threads for the same context.

  • The implementation of this function should be thread-safe.

Parameters

  • hNativeMem – [in] the native handle to the memory.

  • hContext – [in] handle of the context object.

  • pImageFormat – [in] pointer to image format specification.

  • pImageDesc – [in] pointer to image description.

  • pProperties – [in][optional] pointer to native memory creation properties.

  • phMem – [out] pointer to handle of image memory object created.

Returns

urMemGetInfo#

UR_APIEXPORT ur_result_t UR_APICALL urMemGetInfo(ur_mem_handle_t hMemory, ur_mem_info_t propName, size_t propSize, void *pPropValue, size_t *pPropSizeRet)#

Retrieve information about a memory object.

  • Query information that is common to all memory objects.

Remark

Analogues

  • clGetMemObjectInfo

Parameters

  • hMemory – [in] handle to the memory object being queried.

  • propName – [in] type of the info to retrieve.

  • propSize – [in] the number of bytes of memory pointed to by pPropValue.

  • pPropValue – [out][optional][typename(propName, propSize)] array of bytes holding the info. If propSize is less than the real number of bytes needed to return the info then the UR_RESULT_ERROR_INVALID_SIZE error is returned and pPropValue is not used.

  • pPropSizeRet – [out][optional] pointer to the actual size in bytes of the queried propName.

Returns

urMemImageGetInfo#

UR_APIEXPORT ur_result_t UR_APICALL urMemImageGetInfo(ur_mem_handle_t hMemory, ur_image_info_t propName, size_t propSize, void *pPropValue, size_t *pPropSizeRet)#

Retrieve information about an image object.

  • Query information specific to an image object.

Remark

Analogues

  • clGetImageInfo

Parameters

  • hMemory – [in] handle to the image object being queried.

  • propName – [in] type of image info to retrieve.

  • propSize – [in] the number of bytes of memory pointer to by pPropValue.

  • pPropValue – [out][optional][typename(propName, propSize)] array of bytes holding the info. If propSize is less than the real number of bytes needed to return the info then the UR_RESULT_ERROR_INVALID_SIZE error is returned and pPropValue is not used.

  • pPropSizeRet – [out][optional] pointer to the actual size in bytes of the queried propName.

Returns

Memory Enums#

ur_mem_flags_t#

enum ur_mem_flag_t#

Values:

enumerator UR_MEM_FLAG_READ_WRITE#

The memory object will be read and written by a kernel. This is the default

enumerator UR_MEM_FLAG_WRITE_ONLY#

The memory object will be written but not read by a kernel.

enumerator UR_MEM_FLAG_READ_ONLY#

The memory object is a read-only inside a kernel.

enumerator UR_MEM_FLAG_USE_HOST_POINTER#

Use memory pointed by a host pointer parameter as the storage bits for the memory object

enumerator UR_MEM_FLAG_ALLOC_HOST_POINTER#

Allocate memory object from host accessible memory.

enumerator UR_MEM_FLAG_ALLOC_COPY_HOST_POINTER#

Allocate memory and copy the data from host pointer pointed memory

ur_mem_type_t#

enum ur_mem_type_t#

Memory types.

Values:

enumerator UR_MEM_TYPE_BUFFER#

Buffer object.

enumerator UR_MEM_TYPE_IMAGE2D#

2D image object

enumerator UR_MEM_TYPE_IMAGE3D#

3D image object

enumerator UR_MEM_TYPE_IMAGE2D_ARRAY#

2D image array object

enumerator UR_MEM_TYPE_IMAGE1D#

1D image object

enumerator UR_MEM_TYPE_IMAGE1D_ARRAY#

1D image array object

enumerator UR_MEM_TYPE_IMAGE1D_BUFFER#

1D image buffer object

ur_mem_info_t#

enum ur_mem_info_t#

Memory Information type.

Values:

enumerator UR_MEM_INFO_SIZE#

[size_t] actual size of of memory object in bytes

enumerator UR_MEM_INFO_CONTEXT#

[ur_context_handle_t] context in which the memory object was created

ur_image_channel_order_t#

enum ur_image_channel_order_t#

Image channel order info: number of channels and the channel layout.

Values:

enumerator UR_IMAGE_CHANNEL_ORDER_A#

channel order A

enumerator UR_IMAGE_CHANNEL_ORDER_R#

channel order R

enumerator UR_IMAGE_CHANNEL_ORDER_RG#

channel order RG

enumerator UR_IMAGE_CHANNEL_ORDER_RA#

channel order RA

enumerator UR_IMAGE_CHANNEL_ORDER_RGB#

channel order RGB

enumerator UR_IMAGE_CHANNEL_ORDER_RGBA#

channel order RGBA

enumerator UR_IMAGE_CHANNEL_ORDER_BGRA#

channel order BGRA

enumerator UR_IMAGE_CHANNEL_ORDER_ARGB#

channel order ARGB

enumerator UR_IMAGE_CHANNEL_ORDER_ABGR#

channel order ABGR

enumerator UR_IMAGE_CHANNEL_ORDER_INTENSITY#

channel order intensity

enumerator UR_IMAGE_CHANNEL_ORDER_LUMINANCE#

channel order luminance

enumerator UR_IMAGE_CHANNEL_ORDER_RX#

channel order Rx

enumerator UR_IMAGE_CHANNEL_ORDER_RGX#

channel order RGx

enumerator UR_IMAGE_CHANNEL_ORDER_RGBX#

channel order RGBx

enumerator UR_IMAGE_CHANNEL_ORDER_SRGBA#

channel order sRGBA

ur_image_channel_type_t#

enum ur_image_channel_type_t#

Image channel type info: describe the size of the channel data type.

Values:

enumerator UR_IMAGE_CHANNEL_TYPE_SNORM_INT8#

channel type snorm int8

enumerator UR_IMAGE_CHANNEL_TYPE_SNORM_INT16#

channel type snorm int16

enumerator UR_IMAGE_CHANNEL_TYPE_UNORM_INT8#

channel type unorm int8

enumerator UR_IMAGE_CHANNEL_TYPE_UNORM_INT16#

channel type unorm int16

enumerator UR_IMAGE_CHANNEL_TYPE_UNORM_SHORT_565#

channel type unorm short 565

enumerator UR_IMAGE_CHANNEL_TYPE_UNORM_SHORT_555#

channel type unorm short 555

enumerator UR_IMAGE_CHANNEL_TYPE_INT_101010#

channel type int 101010

enumerator UR_IMAGE_CHANNEL_TYPE_SIGNED_INT8#

channel type signed int8

enumerator UR_IMAGE_CHANNEL_TYPE_SIGNED_INT16#

channel type signed int16

enumerator UR_IMAGE_CHANNEL_TYPE_SIGNED_INT32#

channel type signed int32

enumerator UR_IMAGE_CHANNEL_TYPE_UNSIGNED_INT8#

channel type unsigned int8

enumerator UR_IMAGE_CHANNEL_TYPE_UNSIGNED_INT16#

channel type unsigned int16

enumerator UR_IMAGE_CHANNEL_TYPE_UNSIGNED_INT32#

channel type unsigned int32

enumerator UR_IMAGE_CHANNEL_TYPE_HALF_FLOAT#

channel type half float

enumerator UR_IMAGE_CHANNEL_TYPE_FLOAT#

channel type float

ur_image_info_t#

enum ur_image_info_t#

Image information types.

Values:

enumerator UR_IMAGE_INFO_FORMAT#

[ur_image_format_t] image format

enumerator UR_IMAGE_INFO_ELEMENT_SIZE#

[size_t] element size

enumerator UR_IMAGE_INFO_ROW_PITCH#

[size_t] row pitch

enumerator UR_IMAGE_INFO_SLICE_PITCH#

[size_t] slice pitch

enumerator UR_IMAGE_INFO_WIDTH#

[size_t] image width

enumerator UR_IMAGE_INFO_HEIGHT#

[size_t] image height

enumerator UR_IMAGE_INFO_DEPTH#

[size_t] image depth

ur_buffer_create_type_t#

enum ur_buffer_create_type_t#

Buffer creation type.

Values:

enumerator UR_BUFFER_CREATE_TYPE_REGION#

buffer create type is region

Memory Structures#

ur_image_format_t#

struct ur_image_format_t#

Image format including channel layout and data type.

Public Members

ur_image_channel_order_t channelOrder#

[in] image channel order

ur_image_channel_type_t channelType#

[in] image channel type

ur_image_desc_t#

struct ur_image_desc_t#

Image descriptor type.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_IMAGE_DESC

const void *pNext#

[in][optional] pointer to extension-specific structure

ur_mem_type_t type#

[in][nocheck] memory object type

size_t width#

[in] image width

size_t height#

[in] image height

size_t depth#

[in] image depth

size_t arraySize#

[in] image array size

size_t rowPitch#

[in] image row pitch

size_t slicePitch#

[in] image slice pitch

uint32_t numMipLevel#

[in] number of MIP levels

uint32_t numSamples#

[in] number of samples

ur_buffer_properties_t#

struct ur_buffer_properties_t#

Buffer creation properties.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_BUFFER_PROPERTIES

void *pNext#

[in,out][optional] pointer to extension-specific structure

void *pHost#

[in][optional] pointer to the buffer data

ur_buffer_channel_properties_t#

struct ur_buffer_channel_properties_t#

Buffer memory channel creation properties.

Remark

Analogues

  • cl_intel_mem_channel_property

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_BUFFER_CHANNEL_PROPERTIES

void *pNext#

[in,out][optional] pointer to extension-specific structure

uint32_t channel#

[in] Identifies the channel/region to which the buffer should be mapped.

ur_buffer_alloc_location_properties_t#

struct ur_buffer_alloc_location_properties_t#

Buffer allocation location creation properties.

Remark

Analogues

  • cl_intel_mem_alloc_buffer_location

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_BUFFER_ALLOC_LOCATION_PROPERTIES

void *pNext#

[in,out][optional] pointer to extension-specific structure

uint32_t location#

[in] Identifies the ID of global memory partition to which the memory should be allocated.

ur_buffer_region_t#

struct ur_buffer_region_t#

Buffer region type, used to describe a sub buffer.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_BUFFER_REGION

const void *pNext#

[in][optional] pointer to extension-specific structure

size_t origin#

[in] buffer origin offset

size_t size#

[in] size of the buffer region

ur_mem_native_properties_t#

struct ur_mem_native_properties_t#

Native memory object creation properties.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_MEM_NATIVE_PROPERTIES

void *pNext#

[in,out][optional] pointer to extension-specific structure

bool isNativeHandleOwned#

[in] Indicates UR owns the native handle or if it came from an interoperability operation in the application that asked to not transfer the ownership to the unified-runtime.

Sampler#

Sampler Functions#

urSamplerCreate#

UR_APIEXPORT ur_result_t UR_APICALL urSamplerCreate(ur_context_handle_t hContext, const ur_sampler_desc_t *pDesc, ur_sampler_handle_t *phSampler)#

Create a sampler object in a context.

  • The props parameter specifies a list of sampler property names and their corresponding values.

  • The list is terminated with 0. If the list is NULL, default values will be used.

Remark

Analogues

  • clCreateSamplerWithProperties

Parameters

  • hContext – [in] handle of the context object

  • pDesc – [in] pointer to the sampler description

  • phSampler – [out] pointer to handle of sampler object created

Returns

urSamplerRetain#

UR_APIEXPORT ur_result_t UR_APICALL urSamplerRetain(ur_sampler_handle_t hSampler)#

Get a reference to the sampler object handle. Increment its reference count.

Remark

Analogues

  • clRetainSampler

Parameters

hSampler – [in] handle of the sampler object to get access

Returns

urSamplerRelease#

UR_APIEXPORT ur_result_t UR_APICALL urSamplerRelease(ur_sampler_handle_t hSampler)#

Decrement the sampler’s reference count and delete the sampler if the reference count becomes zero.

Remark

Analogues

  • clReleaseSampler

Parameters

hSampler – [in] handle of the sampler object to release

Returns

urSamplerGetInfo#

UR_APIEXPORT ur_result_t UR_APICALL urSamplerGetInfo(ur_sampler_handle_t hSampler, ur_sampler_info_t propName, size_t propSize, void *pPropValue, size_t *pPropSizeRet)#

Query information about a sampler object.

Remark

Analogues

  • clGetSamplerInfo

Parameters

  • hSampler – [in] handle of the sampler object

  • propName – [in] name of the sampler property to query

  • propSize – [in] size in bytes of the sampler property value provided

  • pPropValue – [out][typename(propName, propSize)][optional] value of the sampler property

  • pPropSizeRet – [out][optional] size in bytes returned in sampler property value

Returns

urSamplerGetNativeHandle#

UR_APIEXPORT ur_result_t UR_APICALL urSamplerGetNativeHandle(ur_sampler_handle_t hSampler, ur_native_handle_t *phNativeSampler)#

Return sampler native sampler handle.

  • Retrieved native handle can be used for direct interaction with the native platform driver.

  • Use interoperability sampler extensions to convert native handle to native type.

  • The application may call this function from simultaneous threads for the same context.

  • The implementation of this function should be thread-safe.

Parameters

  • hSampler – [in] handle of the sampler.

  • phNativeSampler – [out] a pointer to the native handle of the sampler.

Returns

urSamplerCreateWithNativeHandle#

UR_APIEXPORT ur_result_t UR_APICALL urSamplerCreateWithNativeHandle(ur_native_handle_t hNativeSampler, ur_context_handle_t hContext, const ur_sampler_native_properties_t *pProperties, ur_sampler_handle_t *phSampler)#

Create runtime sampler object from native sampler handle.

  • Creates runtime sampler handle from native driver sampler handle.

  • The application may call this function from simultaneous threads for the same context.

  • The implementation of this function should be thread-safe.

Parameters

  • hNativeSampler – [in] the native handle of the sampler.

  • hContext – [in] handle of the context object

  • pProperties – [in][optional] pointer to native sampler properties struct.

  • phSampler – [out] pointer to the handle of the sampler object created.

Returns

Sampler Enums#

ur_sampler_filter_mode_t#

enum ur_sampler_filter_mode_t#

Sampler Filter Mode.

Values:

enumerator UR_SAMPLER_FILTER_MODE_NEAREST#

Filter mode nearest.

enumerator UR_SAMPLER_FILTER_MODE_LINEAR#

Filter mode linear.

ur_sampler_addressing_mode_t#

enum ur_sampler_addressing_mode_t#

Sampler addressing mode.

Values:

enumerator UR_SAMPLER_ADDRESSING_MODE_NONE#

None.

enumerator UR_SAMPLER_ADDRESSING_MODE_CLAMP_TO_EDGE#

Clamp to edge.

enumerator UR_SAMPLER_ADDRESSING_MODE_CLAMP#

Clamp.

enumerator UR_SAMPLER_ADDRESSING_MODE_REPEAT#

Repeat.

enumerator UR_SAMPLER_ADDRESSING_MODE_MIRRORED_REPEAT#

Mirrored Repeat

ur_sampler_info_t#

enum ur_sampler_info_t#

Get sample object information.

Values:

enumerator UR_SAMPLER_INFO_REFERENCE_COUNT#

[uint32_t] Reference count of the sampler object. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.

enumerator UR_SAMPLER_INFO_CONTEXT#

[ur_context_handle_t] Sampler context info

enumerator UR_SAMPLER_INFO_NORMALIZED_COORDS#

[ur_bool_t] Sampler normalized coordinate setting

enumerator UR_SAMPLER_INFO_ADDRESSING_MODE#

[ur_sampler_addressing_mode_t] Sampler addressing mode setting

enumerator UR_SAMPLER_INFO_FILTER_MODE#

[ur_sampler_filter_mode_t] Sampler filter mode setting

Sampler Structures#

ur_sampler_desc_t#

struct ur_sampler_desc_t#

Sampler description.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_SAMPLER_DESC

const void *pNext#

[in][optional] pointer to extension-specific structure

bool normalizedCoords#

[in] Specify if image coordinates are normalized (true) or not (false)

ur_sampler_addressing_mode_t addressingMode#

[in] Specify the address mode of the sampler

ur_sampler_filter_mode_t filterMode#

[in] Specify the filter mode of the sampler

ur_sampler_native_properties_t#

struct ur_sampler_native_properties_t#

Native sampler creation properties.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_SAMPLER_NATIVE_PROPERTIES

void *pNext#

[in,out][optional] pointer to extension-specific structure

bool isNativeHandleOwned#

[in] Indicates UR owns the native handle or if it came from an interoperability operation in the application that asked to not transfer the ownership to the unified-runtime.

Usm#

Usm Functions#

urUSMHostAlloc#

UR_APIEXPORT ur_result_t UR_APICALL urUSMHostAlloc(ur_context_handle_t hContext, const ur_usm_desc_t *pUSMDesc, ur_usm_pool_handle_t pool, size_t size, void **ppMem)#

USM allocate host memory.

  • This function must support memory pooling.

  • If pUSMDesc is not NULL and pUSMDesc->pool is not NULL the allocation will be served from a specified memory pool.

  • Otherwise, the behavior is implementation-defined.

  • Allocations served from different memory pools must be isolated and must not reside on the same page.

  • Any flags/hints passed through pUSMDesc only affect the single allocation.

  • See also ur_usm_host_desc_t.

Parameters

  • hContext – [in] handle of the context object

  • pUSMDesc – [in][optional] USM memory allocation descriptor

  • pool – [in][optional] Pointer to a pool created using urUSMPoolCreate

  • size – [in] size in bytes of the USM memory object to be allocated

  • ppMem – [out] pointer to USM host memory object

Returns

urUSMDeviceAlloc#

UR_APIEXPORT ur_result_t UR_APICALL urUSMDeviceAlloc(ur_context_handle_t hContext, ur_device_handle_t hDevice, const ur_usm_desc_t *pUSMDesc, ur_usm_pool_handle_t pool, size_t size, void **ppMem)#

USM allocate device memory.

  • This function must support memory pooling.

  • If pUSMDesc is not NULL and pUSMDesc->pool is not NULL the allocation will be served from a specified memory pool.

  • Otherwise, the behavior is implementation-defined.

  • Allocations served from different memory pools must be isolated and must not reside on the same page.

  • Any flags/hints passed through pUSMDesc only affect the single allocation.

  • See also ur_usm_device_desc_t.

Parameters

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device object

  • pUSMDesc – [in][optional] USM memory allocation descriptor

  • pool – [in][optional] Pointer to a pool created using urUSMPoolCreate

  • size – [in] size in bytes of the USM memory object to be allocated

  • ppMem – [out] pointer to USM device memory object

Returns

urUSMSharedAlloc#

UR_APIEXPORT ur_result_t UR_APICALL urUSMSharedAlloc(ur_context_handle_t hContext, ur_device_handle_t hDevice, const ur_usm_desc_t *pUSMDesc, ur_usm_pool_handle_t pool, size_t size, void **ppMem)#

USM allocate shared memory.

  • This function must support memory pooling.

  • If pUSMDesc is not NULL and pUSMDesc->pool is not NULL the allocation will be served from a specified memory pool.

  • Otherwise, the behavior is implementation-defined.

  • Allocations served from different memory pools must be isolated and must not reside on the same page.

  • Any flags/hints passed through pUSMDesc only affect the single allocation.

  • See also ur_usm_host_desc_t.

  • See also ur_usm_device_desc_t.

Parameters

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device object

  • pUSMDesc – [in][optional] Pointer to USM memory allocation descriptor.

  • pool – [in][optional] Pointer to a pool created using urUSMPoolCreate

  • size – [in] size in bytes of the USM memory object to be allocated

  • ppMem – [out] pointer to USM shared memory object

Returns

urUSMFree#

UR_APIEXPORT ur_result_t UR_APICALL urUSMFree(ur_context_handle_t hContext, void *pMem)#

Free the USM memory object.

Parameters

  • hContext – [in] handle of the context object

  • pMem – [in] pointer to USM memory object

Returns

urUSMGetMemAllocInfo#

UR_APIEXPORT ur_result_t UR_APICALL urUSMGetMemAllocInfo(ur_context_handle_t hContext, const void *pMem, ur_usm_alloc_info_t propName, size_t propSize, void *pPropValue, size_t *pPropSizeRet)#

Get USM memory object allocation information.

Parameters

  • hContext – [in] handle of the context object

  • pMem – [in] pointer to USM memory object

  • propName – [in] the name of the USM allocation property to query

  • propSize – [in] size in bytes of the USM allocation property value

  • pPropValue – [out][optional][typename(propName, propSize)] value of the USM allocation property

  • pPropSizeRet – [out][optional] bytes returned in USM allocation property

Returns

urUSMPoolCreate#

UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolCreate(ur_context_handle_t hContext, ur_usm_pool_desc_t *pPoolDesc, ur_usm_pool_handle_t *ppPool)#

Create USM memory pool with desired properties.

Parameters

  • hContext – [in] handle of the context object

  • pPoolDesc – [in] pointer to USM pool descriptor. Can be chained with ur_usm_pool_limits_desc_t

  • ppPool – [out] pointer to USM memory pool

Returns

urUSMPoolRetain#

UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolRetain(ur_usm_pool_handle_t pPool)#

Get a reference to the pool handle. Increment its reference count.

Parameters

pPool – [in] pointer to USM memory pool

Returns

urUSMPoolRelease#

UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolRelease(ur_usm_pool_handle_t pPool)#

Decrement the pool’s reference count and delete the pool if the reference count becomes zero.

  • All allocation belonging to the pool must be freed prior to the the reference count becoming zero.

  • If the pool is deleted, this function returns all its reserved memory to the driver.

Parameters

pPool – [in] pointer to USM memory pool

Returns

urUSMPoolGetInfo#

UR_APIEXPORT ur_result_t UR_APICALL urUSMPoolGetInfo(ur_usm_pool_handle_t hPool, ur_usm_pool_info_t propName, size_t propSize, void *pPropValue, size_t *pPropSizeRet)#

Query information about a USM memory pool.

Parameters

  • hPool – [in] handle of the USM memory pool

  • propName – [in] name of the pool property to query

  • propSize – [in] size in bytes of the pool property value provided

  • pPropValue – [out][optional][typename(propName, propSize)] value of the pool property

  • pPropSizeRet – [out][optional] size in bytes returned in pool property value

Returns

Usm Enums#

ur_usm_host_mem_flags_t#

enum ur_usm_host_mem_flag_t#

Values:

enumerator UR_USM_HOST_MEM_FLAG_INITIAL_PLACEMENT#

Optimize shared allocation for first access on the host

ur_usm_device_mem_flags_t#

enum ur_usm_device_mem_flag_t#

Values:

enumerator UR_USM_DEVICE_MEM_FLAG_WRITE_COMBINED#

Memory should be allocated write-combined (WC)

enumerator UR_USM_DEVICE_MEM_FLAG_INITIAL_PLACEMENT#

Optimize shared allocation for first access on the device.

enumerator UR_USM_DEVICE_MEM_FLAG_DEVICE_READ_ONLY#

Memory is only possibly modified from the host, but read-only in all device code

ur_usm_pool_flags_t#

enum ur_usm_pool_flag_t#

Values:

enumerator UR_USM_POOL_FLAG_ZERO_INITIALIZE_BLOCK#

All coarse-grain allocations (allocations from the driver) will be zero-initialized.

ur_usm_type_t#

enum ur_usm_type_t#

USM allocation type.

Values:

enumerator UR_USM_TYPE_UNKNOWN#

Unknown USM type.

enumerator UR_USM_TYPE_HOST#

Host USM type.

enumerator UR_USM_TYPE_DEVICE#

Device USM type.

enumerator UR_USM_TYPE_SHARED#

Shared USM type

ur_usm_alloc_info_t#

enum ur_usm_alloc_info_t#

USM memory allocation information type.

Values:

enumerator UR_USM_ALLOC_INFO_TYPE#

[ur_usm_type_t] Memory allocation type info

enumerator UR_USM_ALLOC_INFO_BASE_PTR#

[void *] Memory allocation base pointer info

enumerator UR_USM_ALLOC_INFO_SIZE#

[size_t] Memory allocation size info

enumerator UR_USM_ALLOC_INFO_DEVICE#

[ur_device_handle_t] Memory allocation device info

enumerator UR_USM_ALLOC_INFO_POOL#

[ur_usm_pool_handle_t] Memory allocation pool info

ur_usm_advice_flags_t#

enum ur_usm_advice_flag_t#

Values:

enumerator UR_USM_ADVICE_FLAG_DEFAULT#

The USM memory advice is default.

enumerator UR_USM_ADVICE_FLAG_SET_READ_MOSTLY#

Hint that memory will be read from frequently and written to rarely.

enumerator UR_USM_ADVICE_FLAG_CLEAR_READ_MOSTLY#

Removes the affect of UR_USM_ADVICE_FLAG_SET_READ_MOSTLY.

enumerator UR_USM_ADVICE_FLAG_SET_PREFERRED_LOCATION#

Hint that the preferred memory location is the specified device.

enumerator UR_USM_ADVICE_FLAG_CLEAR_PREFERRED_LOCATION#

Removes the affect of UR_USM_ADVICE_FLAG_SET_PREFERRED_LOCATION.

enumerator UR_USM_ADVICE_FLAG_SET_NON_ATOMIC_MOSTLY#

Hint that memory will mostly be accessed non-atomically.

enumerator UR_USM_ADVICE_FLAG_CLEAR_NON_ATOMIC_MOSTLY#

Removes the affect of UR_USM_ADVICE_FLAG_SET_NON_ATOMIC_MOSTLY.

enumerator UR_USM_ADVICE_FLAG_BIAS_CACHED#

Hint that memory should be cached.

enumerator UR_USM_ADVICE_FLAG_BIAS_UNCACHED#

Hint that memory should be not be cached.

enumerator UR_USM_ADVICE_FLAG_SET_ACCESSED_BY_DEVICE#

Hint that memory will be mostly accessed by the specified device.

enumerator UR_USM_ADVICE_FLAG_CLEAR_ACCESSED_BY_DEVICE#

Removes the affect of UR_USM_ADVICE_FLAG_SET_ACCESSED_BY_DEVICE.

enumerator UR_USM_ADVICE_FLAG_SET_ACCESSED_BY_HOST#

Hint that memory will be mostly accessed by the host.

enumerator UR_USM_ADVICE_FLAG_CLEAR_ACCESSED_BY_HOST#

Removes the affect of UR_USM_ADVICE_FLAG_SET_ACCESSED_BY_HOST.

enumerator UR_USM_ADVICE_FLAG_SET_PREFERRED_LOCATION_HOST#

Hint that the preferred memory location is the host.

enumerator UR_USM_ADVICE_FLAG_CLEAR_PREFERRED_LOCATION_HOST#

Removes the affect of UR_USM_ADVICE_FLAG_SET_PREFERRED_LOCATION_HOST

ur_usm_pool_info_t#

enum ur_usm_pool_info_t#

Get USM memory pool information.

Values:

enumerator UR_USM_POOL_INFO_REFERENCE_COUNT#

[uint32_t] Reference count of the pool object. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.

enumerator UR_USM_POOL_INFO_CONTEXT#

[ur_context_handle_t] USM memory pool context info

Usm Structures#

ur_usm_desc_t#

struct ur_usm_desc_t#

USM allocation descriptor type.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_USM_DESC

const void *pNext#

[in][optional] pointer to extension-specific structure

ur_usm_advice_flags_t hints#

[in] Memory advice hints

uint32_t align#

[in] alignment of the USM memory object Must be zero or a power of 2. Must be equal to or smaller than the size of the largest data type supported by hDevice.

ur_usm_host_desc_t#

struct ur_usm_host_desc_t#

USM host allocation descriptor type.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_USM_HOST_DESC

const void *pNext#

[in][optional] pointer to extension-specific structure

ur_usm_host_mem_flags_t flags#

[in] host memory allocation flags

ur_usm_device_desc_t#

struct ur_usm_device_desc_t#

USM device allocation descriptor type.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_USM_DEVICE_DESC

const void *pNext#

[in][optional] pointer to extension-specific structure

ur_usm_device_mem_flags_t flags#

[in] device memory allocation flags.

ur_usm_pool_desc_t#

struct ur_usm_pool_desc_t#

USM pool descriptor type.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_USM_POOL_DESC

const void *pNext#

[in][optional] pointer to extension-specific structure

ur_usm_pool_flags_t flags#

[in] memory allocation flags

ur_usm_pool_limits_desc_t#

struct ur_usm_pool_limits_desc_t#

USM pool limits descriptor type.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_USM_POOL_LIMITS_DESC

const void *pNext#

[in][optional] pointer to extension-specific structure

size_t maxPoolableSize#

[in] Allocations up to this limit will be subject to pooling

size_t minDriverAllocSize#

[in] Minimum allocation size that will be requested from the driver

Virtual memory#

Virtual memory Functions#

urVirtualMemGranularityGetInfo#

UR_APIEXPORT ur_result_t UR_APICALL urVirtualMemGranularityGetInfo(ur_context_handle_t hContext, ur_device_handle_t hDevice, ur_virtual_mem_granularity_info_t propName, size_t propSize, void *pPropValue, size_t *pPropSizeRet)#

Get information about the minimum and recommended granularity of physical and virtual memory.

Parameters

  • hContext – [in] handle of the context object.

  • hDevice – [in][optional] is the device to get the granularity from, if the device is null then the granularity is suitable for all devices in context.

  • propName – [in] type of the info to query.

  • propSize – [in] size in bytes of the memory pointed to by pPropValue.

  • pPropValue – [out][optional][typename(propName, propSize)] array of bytes holding the info. If propSize is less than the real number of bytes needed to return the info then the UR_RESULT_ERROR_INVALID_SIZE error is returned and pPropValue is not used.

  • pPropSizeRet – [out][optional] pointer to the actual size in bytes of the queried propName.”

Returns

urVirtualMemReserve#

UR_APIEXPORT ur_result_t UR_APICALL urVirtualMemReserve(ur_context_handle_t hContext, const void *pStart, size_t size, void **ppStart)#

Reserve a virtual memory range.

Parameters

  • hContext – [in] handle of the context object.

  • pStart – [in][optional] pointer to the start of the virtual memory region to reserve, specifying a null value causes the implementation to select a start address.

  • size – [in] size in bytes of the virtual address range to reserve.

  • ppStart – [out] pointer to the returned address at the start of reserved virtual memory range.

Returns

urVirtualMemFree#

UR_APIEXPORT ur_result_t UR_APICALL urVirtualMemFree(ur_context_handle_t hContext, const void *pStart, size_t size)#

Free a virtual memory range.

Parameters

  • hContext – [in] handle of the context object.

  • pStart – [in] pointer to the start of the virtual memory range to free.

  • size – [in] size in bytes of the virtual memory range to free.

Returns

urVirtualMemMap#

UR_APIEXPORT ur_result_t UR_APICALL urVirtualMemMap(ur_context_handle_t hContext, const void *pStart, size_t size, ur_physical_mem_handle_t hPhysicalMem, size_t offset, ur_virtual_mem_access_flags_t flags)#

Map a virtual memory range to a physical memory handle.

Parameters

  • hContext – [in] handle to the context object.

  • pStart – [in] pointer to the start of the virtual memory range.

  • size – [in] size in bytes of the virtual memory range to map.

  • hPhysicalMem – [in] handle of the physical memory to map pStart to.

  • offset – [in] offset in bytes into the physical memory to map pStart to.

  • flags – [in] access flags for the physical memory mapping.

Returns

urVirtualMemUnmap#

UR_APIEXPORT ur_result_t UR_APICALL urVirtualMemUnmap(ur_context_handle_t hContext, const void *pStart, size_t size)#

Unmap a virtual memory range previously mapped in a context.

  • After a call to this function, the virtual memory range is left in a state ready to be remapped.

Parameters

  • hContext – [in] handle to the context object.

  • pStart – [in] pointer to the start of the mapped virtual memory range

  • size – [in] size in bytes of the virtual memory range.

Returns

urVirtualMemSetAccess#

UR_APIEXPORT ur_result_t UR_APICALL urVirtualMemSetAccess(ur_context_handle_t hContext, const void *pStart, size_t size, ur_virtual_mem_access_flags_t flags)#

Set the access mode of a mapped virtual memory range.

Parameters

  • hContext – [in] handle to the context object.

  • pStart – [in] pointer to the start of the virtual memory range.

  • size – [in] size in bytes of the virutal memory range.

  • flags – [in] access flags to set for the mapped virtual memory range.

Returns

urVirtualMemGetInfo#

UR_APIEXPORT ur_result_t UR_APICALL urVirtualMemGetInfo(ur_context_handle_t hContext, const void *pStart, size_t size, ur_virtual_mem_info_t propName, size_t propSize, void *pPropValue, size_t *pPropSizeRet)#

Get information about a mapped virtual memory range.

Parameters

  • hContext – [in] handle to the context object.

  • pStart – [in] pointer to the start of the virtual memory range.

  • size – [in] size in bytes of the virtual memory range.

  • propName – [in] type of the info to query.

  • propSize – [in] size in bytes of the memory pointed to by pPropValue.

  • pPropValue – [out][optional][typename(propName, propSize)] array of bytes holding the info. If propSize is less than the real number of bytes needed to return the info then the UR_RESULT_ERROR_INVALID_SIZE error is returned and pPropValue is not used.

  • pPropSizeRet – [out][optional] pointer to the actual size in bytes of the queried propName.”

Returns

urPhysicalMemCreate#

UR_APIEXPORT ur_result_t UR_APICALL urPhysicalMemCreate(ur_context_handle_t hContext, ur_device_handle_t hDevice, size_t size, const ur_physical_mem_properties_t *pProperties, ur_physical_mem_handle_t *phPhysicalMem)#

Create a physical memory handle that virtual memory can be mapped to.

Parameters

  • hContext – [in] handle of the context object.

  • hDevice – [in] handle of the device object.

  • size – [in] size in bytes of phyisical memory to allocate, must be a multiple of UR_VIRTUAL_MEM_GRANULARITY_INFO_MINIMUM.

  • pProperties – [in][optional] pointer to physical memory creation properties.

  • phPhysicalMem – [out] pointer to handle of physical memory object created.

Returns

urPhysicalMemRetain#

UR_APIEXPORT ur_result_t UR_APICALL urPhysicalMemRetain(ur_physical_mem_handle_t hPhysicalMem)#

Retain a physical memory handle, increment its reference count.

Parameters

hPhysicalMem – [in] handle of the physical memory object to retain.

Returns

urPhysicalMemRelease#

UR_APIEXPORT ur_result_t UR_APICALL urPhysicalMemRelease(ur_physical_mem_handle_t hPhysicalMem)#

Release a physical memory handle, decrement its reference count.

Parameters

hPhysicalMem – [in] handle of the physical memory object to release.

Returns

Virtual memory Enums#

ur_virtual_mem_granularity_info_t#

enum ur_virtual_mem_granularity_info_t#

Virtual memory granularity info.

Values:

enumerator UR_VIRTUAL_MEM_GRANULARITY_INFO_MINIMUM#

[size_t] size in bytes of the minimum virtual memory granularity.

enumerator UR_VIRTUAL_MEM_GRANULARITY_INFO_RECOMMENDED#

[size_t] size in bytes of the recommended virtual memory granularity.

ur_virtual_mem_access_flags_t#

enum ur_virtual_mem_access_flag_t#

Values:

enumerator UR_VIRTUAL_MEM_ACCESS_FLAG_NONE#

Virtual memory has no access.

enumerator UR_VIRTUAL_MEM_ACCESS_FLAG_READ_WRITE#

Virtual memory has both read and write access.

enumerator UR_VIRTUAL_MEM_ACCESS_FLAG_READ_ONLY#

Virtual memory has read only access.

ur_virtual_mem_info_t#

enum ur_virtual_mem_info_t#

Virtual memory range info queries.

Values:

enumerator UR_VIRTUAL_MEM_INFO_ACCESS_MODE#

[ur_virtual_mem_access_flags_t] access flags of a mapped virtual memory range.

ur_physical_mem_flags_t#

enum ur_physical_mem_flag_t#

Values:

enumerator UR_PHYSICAL_MEM_FLAG_TBD#

reserved for future use.

Virtual memory Structures#

ur_physical_mem_properties_t#

struct ur_physical_mem_properties_t#

Physical memory creation properties.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_PHYSICAL_MEM_PROPERTIES

void *pNext#

[in,out][optional] pointer to extension-specific structure

ur_physical_mem_flags_t flags#

[in] physical memory creation flags

Program#

Program Functions#

urProgramCreateWithIL#

UR_APIEXPORT ur_result_t UR_APICALL urProgramCreateWithIL(ur_context_handle_t hContext, const void *pIL, size_t length, const ur_program_properties_t *pProperties, ur_program_handle_t *phProgram)#

Create a program object from input intermediate language.

  • The application may call this function from simultaneous threads.

Remark

Analogues

  • clCreateProgramWithIL

Parameters

  • hContext – [in] handle of the context instance

  • pIL – [in] pointer to IL binary.

  • length – [in] length of `pIL` in bytes.

  • pProperties – [in][optional] pointer to program creation properties.

  • phProgram – [out] pointer to handle of program object created.

Returns

urProgramCreateWithBinary#

UR_APIEXPORT ur_result_t UR_APICALL urProgramCreateWithBinary(ur_context_handle_t hContext, ur_device_handle_t hDevice, size_t size, const uint8_t *pBinary, const ur_program_properties_t *pProperties, ur_program_handle_t *phProgram)#

Create a program object from device native binary.

  • The application may call this function from simultaneous threads.

Remark

Analogues

  • clCreateProgramWithBinary

Parameters

  • hContext – [in] handle of the context instance

  • hDevice – [in] handle to device associated with binary.

  • size – [in] size in bytes.

  • pBinary – [in] pointer to binary.

  • pProperties – [in][optional] pointer to program creation properties.

  • phProgram – [out] pointer to handle of Program object created.

Returns

urProgramBuild#

UR_APIEXPORT ur_result_t UR_APICALL urProgramBuild(ur_context_handle_t hContext, ur_program_handle_t hProgram, const char *pOptions)#

Produces an executable program from one program, negates need for the linking step.

  • The application may call this function from simultaneous threads.

  • Following a succesful call to this entry point, the program passed will contain a binary of the UR_PROGRAM_BINARY_TYPE_EXECUTABLE type for each device in hContext.

Remark

Analogues

  • clBuildProgram

Parameters

  • hContext – [in] handle of the context instance.

  • hProgram – [in] Handle of the program to build.

  • pOptions – [in][optional] pointer to build options null-terminated string.

Returns

urProgramCompile#

UR_APIEXPORT ur_result_t UR_APICALL urProgramCompile(ur_context_handle_t hContext, ur_program_handle_t hProgram, const char *pOptions)#

Produces an executable program from one or more programs.

  • The application may call this function from simultaneous threads.

  • Following a succesful call to this entry point hProgram will contain a binary of the UR_PROGRAM_BINARY_TYPE_COMPILED_OBJECT type for each device in hContext.

Remark

Analogues

  • clCompileProgram

Parameters

  • hContext – [in] handle of the context instance.

  • hProgram – [in][out] handle of the program to compile.

  • pOptions – [in][optional] pointer to build options null-terminated string.

Returns

urProgramRetain#

UR_APIEXPORT ur_result_t UR_APICALL urProgramRetain(ur_program_handle_t hProgram)#

Get a reference to the Program object.

  • Get a reference to the Program object handle. Increment its reference count

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Remark

Analogues

  • clRetainProgram

Parameters

hProgram – [in] handle for the Program to retain

Returns

urProgramRelease#

UR_APIEXPORT ur_result_t UR_APICALL urProgramRelease(ur_program_handle_t hProgram)#

Release Program.

  • Decrement reference count and destroy the Program if reference count becomes zero.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Remark

Analogues

  • clReleaseProgram

Parameters

hProgram – [in] handle for the Program to release

Returns

urProgramGetFunctionPointer#

UR_APIEXPORT ur_result_t UR_APICALL urProgramGetFunctionPointer(ur_device_handle_t hDevice, ur_program_handle_t hProgram, const char *pFunctionName, void **ppFunctionPointer)#

Retrieves a device function pointer to a user-defined function.

  • Retrieves a pointer to the functions with the given name and defined in the given program.

  • UR_RESULT_ERROR_INVALID_FUNCTION_NAME is returned if the function can not be obtained.

  • The application may call this function from simultaneous threads for the same device.

  • The implementation of this function should be thread-safe.

Remark

Analogues

  • clGetDeviceFunctionPointerINTEL

Parameters

  • hDevice – [in] handle of the device to retrieve pointer for.

  • hProgram – [in] handle of the program to search for function in. The program must already be built to the specified device, or otherwise UR_RESULT_ERROR_INVALID_PROGRAM_EXECUTABLE is returned.

  • pFunctionName – [in] A null-terminates string denoting the mangled function name.

  • ppFunctionPointer – [out] Returns the pointer to the function if it is found in the program.

Returns

urProgramGetInfo#

UR_APIEXPORT ur_result_t UR_APICALL urProgramGetInfo(ur_program_handle_t hProgram, ur_program_info_t propName, size_t propSize, void *pPropValue, size_t *pPropSizeRet)#

Query information about a Program object.

Remark

Analogues

  • clGetProgramInfo

Parameters

  • hProgram – [in] handle of the Program object

  • propName – [in] name of the Program property to query

  • propSize – [in] the size of the Program property.

  • pPropValue – [in,out][optional][typename(propName, propSize)] array of bytes of holding the program info property. If propSize is not equal to or greater than the real number of bytes needed to return the info then the UR_RESULT_ERROR_INVALID_SIZE error is returned and pPropValue is not used.

  • pPropSizeRet – [out][optional] pointer to the actual size in bytes of the queried propName.

Returns

urProgramGetBuildInfo#

UR_APIEXPORT ur_result_t UR_APICALL urProgramGetBuildInfo(ur_program_handle_t hProgram, ur_device_handle_t hDevice, ur_program_build_info_t propName, size_t propSize, void *pPropValue, size_t *pPropSizeRet)#

Query build information about a Program object for a Device.

Remark

Analogues

  • clGetProgramBuildInfo

Parameters

  • hProgram – [in] handle of the Program object

  • hDevice – [in] handle of the Device object

  • propName – [in] name of the Program build info to query

  • propSize – [in] size of the Program build info property.

  • pPropValue – [in,out][optional][typename(propName, propSize)] value of the Program build property. If propSize is not equal to or greater than the real number of bytes needed to return the info then the UR_RESULT_ERROR_INVALID_SIZE error is returned and pPropValue is not used.

  • pPropSizeRet – [out][optional] pointer to the actual size in bytes of data being queried by propName.

Returns

urProgramSetSpecializationConstants#

UR_APIEXPORT ur_result_t UR_APICALL urProgramSetSpecializationConstants(ur_program_handle_t hProgram, uint32_t count, const ur_specialization_constant_info_t *pSpecConstants)#

Set an array of specialization constants on a Program.

  • The application may call this function from simultaneous threads for the same device.

  • The implementation of this function should be thread-safe.

  • hProgram must have been created with the urProgramCreateWithIL entry point.

  • Any spec constants set with this entry point will apply only to subsequent calls to urProgramBuild or urProgramCompile.

Parameters

  • hProgram – [in] handle of the Program object

  • count – [in] the number of elements in the pSpecConstants array

  • pSpecConstants – [in][range(0, count)] array of specialization constant value descriptions

Returns

urProgramGetNativeHandle#

UR_APIEXPORT ur_result_t UR_APICALL urProgramGetNativeHandle(ur_program_handle_t hProgram, ur_native_handle_t *phNativeProgram)#

Return program native program handle.

  • Retrieved native handle can be used for direct interaction with the native platform driver.

  • Use interoperability program extensions to convert native handle to native type.

  • The application may call this function from simultaneous threads for the same context.

  • The implementation of this function should be thread-safe.

Parameters

  • hProgram – [in] handle of the program.

  • phNativeProgram – [out] a pointer to the native handle of the program.

Returns

urProgramCreateWithNativeHandle#

UR_APIEXPORT ur_result_t UR_APICALL urProgramCreateWithNativeHandle(ur_native_handle_t hNativeProgram, ur_context_handle_t hContext, const ur_program_native_properties_t *pProperties, ur_program_handle_t *phProgram)#

Create runtime program object from native program handle.

  • Creates runtime program handle from native driver program handle.

  • The application may call this function from simultaneous threads for the same context.

  • The implementation of this function should be thread-safe.

Parameters

  • hNativeProgram – [in] the native handle of the program.

  • hContext – [in] handle of the context instance

  • pProperties – [in][optional] pointer to native program properties struct.

  • phProgram – [out] pointer to the handle of the program object created.

Returns

Program Enums#

ur_program_metadata_type_t#

enum ur_program_metadata_type_t#

Program metadata property type.

Values:

enumerator UR_PROGRAM_METADATA_TYPE_UINT32#

type is a 32-bit integer.

enumerator UR_PROGRAM_METADATA_TYPE_UINT64#

type is a 64-bit integer.

enumerator UR_PROGRAM_METADATA_TYPE_BYTE_ARRAY#

type is a byte array.

enumerator UR_PROGRAM_METADATA_TYPE_STRING#

type is a null-terminated string.

ur_program_info_t#

enum ur_program_info_t#

Get Program object information.

Values:

enumerator UR_PROGRAM_INFO_REFERENCE_COUNT#

[uint32_t] Reference count of the program object. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.

enumerator UR_PROGRAM_INFO_CONTEXT#

[ur_context_handle_t] Program context info.

enumerator UR_PROGRAM_INFO_NUM_DEVICES#

[uint32_t] Return number of devices associated with Program.

enumerator UR_PROGRAM_INFO_DEVICES#

[ur_device_handle_t[]] Return list of devices associated with Program.

enumerator UR_PROGRAM_INFO_SOURCE#

[char[]] Return program source associated with Program.

enumerator UR_PROGRAM_INFO_BINARY_SIZES#

[size_t[]] Return program binary sizes for each device.

enumerator UR_PROGRAM_INFO_BINARIES#

[unsigned char[]] Return program binaries for all devices for this Program.

enumerator UR_PROGRAM_INFO_NUM_KERNELS#

[size_t] Number of kernels in Program, return type size_t.

enumerator UR_PROGRAM_INFO_KERNEL_NAMES#

[char[]] Return a null-terminated, semi-colon separated list of kernel names in Program.

ur_program_build_status_t#

enum ur_program_build_status_t#

Program object build status.

Values:

enumerator UR_PROGRAM_BUILD_STATUS_NONE#

Program build status none.

enumerator UR_PROGRAM_BUILD_STATUS_ERROR#

Program build error.

enumerator UR_PROGRAM_BUILD_STATUS_SUCCESS#

Program build success.

enumerator UR_PROGRAM_BUILD_STATUS_IN_PROGRESS#

Program build in progress

ur_program_binary_type_t#

enum ur_program_binary_type_t#

Program object binary type.

Values:

enumerator UR_PROGRAM_BINARY_TYPE_NONE#

No program binary is associated with device.

enumerator UR_PROGRAM_BINARY_TYPE_COMPILED_OBJECT#

Program binary is compiled object.

enumerator UR_PROGRAM_BINARY_TYPE_LIBRARY#

Program binary is library object.

enumerator UR_PROGRAM_BINARY_TYPE_EXECUTABLE#

Program binary is executable

ur_program_build_info_t#

enum ur_program_build_info_t#

Get Program object build information.

Values:

enumerator UR_PROGRAM_BUILD_INFO_STATUS#

[ur_program_build_status_t] Program build status.

enumerator UR_PROGRAM_BUILD_INFO_OPTIONS#

[char[]] Null-terminated options string specified by last build, compile or link operation performed on the program.

enumerator UR_PROGRAM_BUILD_INFO_LOG#

[char[]] Null-terminated program build log.

enumerator UR_PROGRAM_BUILD_INFO_BINARY_TYPE#

[ur_program_binary_type_t] Program binary type.

Program Structures#

ur_program_metadata_value_t#

union ur_program_metadata_value_t#
#include <>

Program metadata value union.

Public Members

uint32_t data32#

[in] inline storage for the 32-bit data, type UR_PROGRAM_METADATA_TYPE_UINT32.

uint64_t data64#

[in] inline storage for the 64-bit data, type UR_PROGRAM_METADATA_TYPE_UINT64.

char *pString#

[in] pointer to null-terminated string data, type UR_PROGRAM_METADATA_TYPE_STRING.

void *pData#

[in] pointer to binary data, type UR_PROGRAM_METADATA_TYPE_BYTE_ARRAY.

ur_program_metadata_t#

struct ur_program_metadata_t#

Program metadata property.

Public Members

char *pName#

[in] null-terminated metadata name.

ur_program_metadata_type_t type#

[in] the type of metadata value.

size_t size#

[in] size in bytes of the data pointed to by value.pData, or 0 when value size is less than 64-bits and is stored directly in value.data.

ur_program_metadata_value_t value#

[in] the metadata value storage.

ur_program_properties_t#

struct ur_program_properties_t#

Program creation properties.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_PROGRAM_PROPERTIES

void *pNext#

[in,out][optional] pointer to extension-specific structure

uint32_t count#

[in] the number of entries in pMetadatas, if count is greater than zero then pMetadatas must not be null.

const ur_program_metadata_t *pMetadatas#

[in][optional][range(0,count)] pointer to array of metadata entries.

ur_specialization_constant_info_t#

struct ur_specialization_constant_info_t#

Specialization constant information.

Public Members

uint32_t id#

[in] specialization constant Id

size_t size#

[in] size of the specialization constant value

const void *pValue#

[in] pointer to the specialization constant value bytes

ur_program_native_properties_t#

struct ur_program_native_properties_t#

Native program creation properties.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_PROGRAM_NATIVE_PROPERTIES

void *pNext#

[in,out][optional] pointer to extension-specific structure

bool isNativeHandleOwned#

[in] Indicates UR owns the native handle or if it came from an interoperability operation in the application that asked to not transfer the ownership to the unified-runtime.

Kernel#

Kernel Functions#

urKernelCreate#

UR_APIEXPORT ur_result_t UR_APICALL urKernelCreate(ur_program_handle_t hProgram, const char *pKernelName, ur_kernel_handle_t *phKernel)#

Create kernel object from a program.

  • Multiple calls to this function will return identical device handles, in the same order.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters

  • hProgram – [in] handle of the program instance

  • pKernelName – [in] pointer to null-terminated string.

  • phKernel – [out] pointer to handle of kernel object created.

Returns

urKernelSetArgValue#

UR_APIEXPORT ur_result_t UR_APICALL urKernelSetArgValue(ur_kernel_handle_t hKernel, uint32_t argIndex, size_t argSize, const ur_kernel_arg_value_properties_t *pProperties, const void *pArgValue)#

Set kernel argument to a value.

  • The application may call this function from simultaneous threads with the same kernel handle.

  • The implementation of this function should be lock-free.

Parameters

  • hKernel – [in] handle of the kernel object

  • argIndex – [in] argument index in range [0, num args - 1]

  • argSize – [in] size of argument type

  • pProperties – [in][optional] pointer to value properties.

  • pArgValue – [in] argument value represented as matching arg type.

Returns

urKernelSetArgLocal#

UR_APIEXPORT ur_result_t UR_APICALL urKernelSetArgLocal(ur_kernel_handle_t hKernel, uint32_t argIndex, size_t argSize, const ur_kernel_arg_local_properties_t *pProperties)#

Set kernel argument to a local buffer.

  • The application may call this function from simultaneous threads with the same kernel handle.

  • The implementation of this function should be lock-free.

Parameters

  • hKernel – [in] handle of the kernel object

  • argIndex – [in] argument index in range [0, num args - 1]

  • argSize – [in] size of the local buffer to be allocated by the runtime

  • pProperties – [in][optional] pointer to local buffer properties.

Returns

urKernelGetInfo#

UR_APIEXPORT ur_result_t UR_APICALL urKernelGetInfo(ur_kernel_handle_t hKernel, ur_kernel_info_t propName, size_t propSize, void *pPropValue, size_t *pPropSizeRet)#

Query information about a Kernel object.

Remark

Analogues

  • clGetKernelInfo

Parameters

  • hKernel – [in] handle of the Kernel object

  • propName – [in] name of the Kernel property to query

  • propSize – [in] the size of the Kernel property value.

  • pPropValue – [in,out][optional][typename(propName, propSize)] array of bytes holding the kernel info property. If propSize is not equal to or greater than the real number of bytes needed to return the info then the UR_RESULT_ERROR_INVALID_SIZE error is returned and pPropValue is not used.

  • pPropSizeRet – [out][optional] pointer to the actual size in bytes of data being queried by propName.

Returns

urKernelGetGroupInfo#

UR_APIEXPORT ur_result_t UR_APICALL urKernelGetGroupInfo(ur_kernel_handle_t hKernel, ur_device_handle_t hDevice, ur_kernel_group_info_t propName, size_t propSize, void *pPropValue, size_t *pPropSizeRet)#

Query work Group information about a Kernel object.

Remark

Analogues

  • clGetKernelWorkGroupInfo

Parameters

  • hKernel – [in] handle of the Kernel object

  • hDevice – [in] handle of the Device object

  • propName – [in] name of the work Group property to query

  • propSize – [in] size of the Kernel Work Group property value

  • pPropValue – [in,out][optional][typename(propName, propSize)] value of the Kernel Work Group property.

  • pPropSizeRet – [out][optional] pointer to the actual size in bytes of data being queried by propName.

Returns

urKernelGetSubGroupInfo#

UR_APIEXPORT ur_result_t UR_APICALL urKernelGetSubGroupInfo(ur_kernel_handle_t hKernel, ur_device_handle_t hDevice, ur_kernel_sub_group_info_t propName, size_t propSize, void *pPropValue, size_t *pPropSizeRet)#

Query SubGroup information about a Kernel object.

Parameters

  • hKernel – [in] handle of the Kernel object

  • hDevice – [in] handle of the Device object

  • propName – [in] name of the SubGroup property to query

  • propSize – [in] size of the Kernel SubGroup property value

  • pPropValue – [in,out][optional][typename(propName, propSize)] value of the Kernel SubGroup property.

  • pPropSizeRet – [out][optional] pointer to the actual size in bytes of data being queried by propName.

Returns

urKernelRetain#

UR_APIEXPORT ur_result_t UR_APICALL urKernelRetain(ur_kernel_handle_t hKernel)#

Get a reference to the Kernel object.

  • Get a reference to the Kernel object handle. Increment its reference count

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Remark

Analogues

  • clRetainKernel

Parameters

hKernel – [in] handle for the Kernel to retain

Returns

urKernelRelease#

UR_APIEXPORT ur_result_t UR_APICALL urKernelRelease(ur_kernel_handle_t hKernel)#

Release Kernel.

  • Decrement reference count and destroy the Kernel if reference count becomes zero.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Remark

Analogues

  • clReleaseKernel

Parameters

hKernel – [in] handle for the Kernel to release

Returns

urKernelSetArgPointer#

UR_APIEXPORT ur_result_t UR_APICALL urKernelSetArgPointer(ur_kernel_handle_t hKernel, uint32_t argIndex, const ur_kernel_arg_pointer_properties_t *pProperties, const void *pArgValue)#

Set a USM pointer as the argument value of a Kernel.

  • The application may call this function from simultaneous threads with the same kernel handle.

  • The implementation of this function should be lock-free.

Remark

Analogues

  • clSetKernelArgSVMPointer

Parameters

  • hKernel – [in] handle of the kernel object

  • argIndex – [in] argument index in range [0, num args - 1]

  • pProperties – [in][optional] pointer to USM pointer properties.

  • pArgValue – [in][optional] USM pointer to memory location holding the argument value. If null then argument value is considered null.

Returns

urKernelSetExecInfo#

UR_APIEXPORT ur_result_t UR_APICALL urKernelSetExecInfo(ur_kernel_handle_t hKernel, ur_kernel_exec_info_t propName, size_t propSize, const ur_kernel_exec_info_properties_t *pProperties, const void *pPropValue)#

Set additional Kernel execution attributes.

  • The application must not call this function from simultaneous threads with the same kernel handle.

  • The implementation of this function should be lock-free.

Remark

Analogues

  • clSetKernelExecInfo

Parameters

  • hKernel – [in] handle of the kernel object

  • propName – [in] name of the execution attribute

  • propSize – [in] size in byte the attribute value

  • pProperties – [in][optional] pointer to execution info properties.

  • pPropValue – [in][typename(propName, propSize)] pointer to memory location holding the property value.

Returns

urKernelSetArgSampler#

UR_APIEXPORT ur_result_t UR_APICALL urKernelSetArgSampler(ur_kernel_handle_t hKernel, uint32_t argIndex, const ur_kernel_arg_sampler_properties_t *pProperties, ur_sampler_handle_t hArgValue)#

Set a Sampler object as the argument value of a Kernel.

  • The application may call this function from simultaneous threads with the same kernel handle.

  • The implementation of this function should be lock-free.

Parameters

  • hKernel – [in] handle of the kernel object

  • argIndex – [in] argument index in range [0, num args - 1]

  • pProperties – [in][optional] pointer to sampler properties.

  • hArgValue – [in] handle of Sampler object.

Returns

urKernelSetArgMemObj#

UR_APIEXPORT ur_result_t UR_APICALL urKernelSetArgMemObj(ur_kernel_handle_t hKernel, uint32_t argIndex, const ur_kernel_arg_mem_obj_properties_t *pProperties, ur_mem_handle_t hArgValue)#

Set a Memory object as the argument value of a Kernel.

  • The application may call this function from simultaneous threads with the same kernel handle.

  • The implementation of this function should be lock-free.

Parameters

  • hKernel – [in] handle of the kernel object

  • argIndex – [in] argument index in range [0, num args - 1]

  • pProperties – [in][optional] pointer to Memory object properties.

  • hArgValue – [in][optional] handle of Memory object.

Returns

urKernelSetSpecializationConstants#

UR_APIEXPORT ur_result_t UR_APICALL urKernelSetSpecializationConstants(ur_kernel_handle_t hKernel, uint32_t count, const ur_specialization_constant_info_t *pSpecConstants)#

Set an array of specialization constants on a Kernel.

  • This entry point is optional, the application should query for support with device query UR_DEVICE_INFO_KERNEL_SET_SPECIALIZATION_CONSTANTS passed to urDeviceGetInfo.

  • Adapters which are capable of setting specialization constants immediately prior to urEnqueueKernelLaunch with low overhead should implement this entry point.

  • Otherwise, if setting specialization constants late requires recompiling or linking a program, adapters should not implement this entry point.

  • The application may call this function from simultaneous threads for the same device.

  • The implementation of this function should be thread-safe.

Parameters

  • hKernel – [in] handle of the kernel object

  • count – [in] the number of elements in the pSpecConstants array

  • pSpecConstants – [in] array of specialization constant value descriptions

Returns

urKernelGetNativeHandle#

UR_APIEXPORT ur_result_t UR_APICALL urKernelGetNativeHandle(ur_kernel_handle_t hKernel, ur_native_handle_t *phNativeKernel)#

Return platform native kernel handle.

  • Retrieved native handle can be used for direct interaction with the native platform driver.

  • Use interoperability platform extensions to convert native handle to native type.

  • The application may call this function from simultaneous threads for the same context.

  • The implementation of this function should be thread-safe.

Parameters

  • hKernel – [in] handle of the kernel.

  • phNativeKernel – [out] a pointer to the native handle of the kernel.

Returns

urKernelCreateWithNativeHandle#

UR_APIEXPORT ur_result_t UR_APICALL urKernelCreateWithNativeHandle(ur_native_handle_t hNativeKernel, ur_context_handle_t hContext, ur_program_handle_t hProgram, const ur_kernel_native_properties_t *pProperties, ur_kernel_handle_t *phKernel)#

Create runtime kernel object from native kernel handle.

  • Creates runtime kernel handle from native driver kernel handle.

  • The application may call this function from simultaneous threads for the same context.

  • The implementation of this function should be thread-safe.

Parameters

  • hNativeKernel – [in] the native handle of the kernel.

  • hContext – [in] handle of the context object

  • hProgram – [in] handle of the program associated with the kernel

  • pProperties – [in][optional] pointer to native kernel properties struct

  • phKernel – [out] pointer to the handle of the kernel object created.

Returns

Kernel Enums#

ur_kernel_info_t#

enum ur_kernel_info_t#

Get Kernel object information.

Values:

enumerator UR_KERNEL_INFO_FUNCTION_NAME#

[char[]] Return null-terminated kernel function name.

enumerator UR_KERNEL_INFO_NUM_ARGS#

[size_t] Return Kernel number of arguments.

enumerator UR_KERNEL_INFO_REFERENCE_COUNT#

[uint32_t] Reference count of the kernel object. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.

enumerator UR_KERNEL_INFO_CONTEXT#

[ur_context_handle_t] Return Context object associated with Kernel.

enumerator UR_KERNEL_INFO_PROGRAM#

[ur_program_handle_t] Return Program object associated with Kernel.

enumerator UR_KERNEL_INFO_ATTRIBUTES#

[char[]] Return null-terminated kernel attributes string.

enumerator UR_KERNEL_INFO_NUM_REGS#

[uint32_t] Return the number of registers used by the compiled kernel (device specific).

ur_kernel_group_info_t#

enum ur_kernel_group_info_t#

Get Kernel Work Group information.

Values:

enumerator UR_KERNEL_GROUP_INFO_GLOBAL_WORK_SIZE#

[size_t[3]] Return Work Group maximum global size

enumerator UR_KERNEL_GROUP_INFO_WORK_GROUP_SIZE#

[size_t] Return maximum Work Group size

enumerator UR_KERNEL_GROUP_INFO_COMPILE_WORK_GROUP_SIZE#

[size_t[3]] Return Work Group size required by the source code, such as attribute((required_work_group_size(X,Y,Z))

enumerator UR_KERNEL_GROUP_INFO_LOCAL_MEM_SIZE#

[size_t] Return local memory required by the Kernel

enumerator UR_KERNEL_GROUP_INFO_PREFERRED_WORK_GROUP_SIZE_MULTIPLE#

[size_t] Return preferred multiple of Work Group size for launch

enumerator UR_KERNEL_GROUP_INFO_PRIVATE_MEM_SIZE#

[size_t] Return minimum amount of private memory in bytes used by each work item in the Kernel

ur_kernel_sub_group_info_t#

enum ur_kernel_sub_group_info_t#

Get Kernel SubGroup information.

Values:

enumerator UR_KERNEL_SUB_GROUP_INFO_MAX_SUB_GROUP_SIZE#

[uint32_t] Return maximum SubGroup size

enumerator UR_KERNEL_SUB_GROUP_INFO_MAX_NUM_SUB_GROUPS#

[uint32_t] Return maximum number of SubGroup

enumerator UR_KERNEL_SUB_GROUP_INFO_COMPILE_NUM_SUB_GROUPS#

[uint32_t] Return number of SubGroup required by the source code

enumerator UR_KERNEL_SUB_GROUP_INFO_SUB_GROUP_SIZE_INTEL#

[uint32_t] Return SubGroup size required by Intel

ur_kernel_cache_config_t#

enum ur_kernel_cache_config_t#

Kernel Cache Configuartion.

Values:

enumerator UR_KERNEL_CACHE_CONFIG_DEFAULT#

No preference for SLM or data cache.

enumerator UR_KERNEL_CACHE_CONFIG_LARGE_SLM#

Large Shared Local Memory (SLM) size.

enumerator UR_KERNEL_CACHE_CONFIG_LARGE_DATA#

Large General Data size.

ur_kernel_exec_info_t#

enum ur_kernel_exec_info_t#

Set additional Kernel execution information.

Values:

enumerator UR_KERNEL_EXEC_INFO_USM_INDIRECT_ACCESS#

[ur_bool_t] Kernel might access data through USM pointer.

enumerator UR_KERNEL_EXEC_INFO_USM_PTRS#

[void *[]] Provide an explicit array of USM pointers that the kernel will access.

enumerator UR_KERNEL_EXEC_INFO_CACHE_CONFIG#

[ur_kernel_cache_config_t] Provide the preferred cache configuration

Kernel Structures#

ur_kernel_arg_value_properties_t#

struct ur_kernel_arg_value_properties_t#

Properties for for urKernelSetArgValue.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_KERNEL_ARG_VALUE_PROPERTIES

void *pNext#

[in,out][optional] pointer to extension-specific structure

ur_kernel_arg_local_properties_t#

struct ur_kernel_arg_local_properties_t#

Properties for for urKernelSetArgLocal.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_KERNEL_ARG_LOCAL_PROPERTIES

void *pNext#

[in,out][optional] pointer to extension-specific structure

ur_kernel_arg_pointer_properties_t#

struct ur_kernel_arg_pointer_properties_t#

Properties for for urKernelSetArgPointer.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_KERNEL_ARG_POINTER_PROPERTIES

void *pNext#

[in,out][optional] pointer to extension-specific structure

ur_kernel_exec_info_properties_t#

struct ur_kernel_exec_info_properties_t#

Properties for for urKernelSetExecInfo.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_KERNEL_EXEC_INFO_PROPERTIES

void *pNext#

[in,out][optional] pointer to extension-specific structure

ur_kernel_arg_sampler_properties_t#

struct ur_kernel_arg_sampler_properties_t#

Properties for for urKernelSetArgSampler.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_KERNEL_ARG_SAMPLER_PROPERTIES

void *pNext#

[in,out][optional] pointer to extension-specific structure

ur_kernel_arg_mem_obj_properties_t#

struct ur_kernel_arg_mem_obj_properties_t#

Properties for for urKernelSetArgMemObj.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_KERNEL_ARG_MEM_OBJ_PROPERTIES

void *pNext#

[in,out][optional] pointer to extension-specific structure

ur_mem_flags_t memoryAccess#

[in] Memory access flag. Allowed values are: UR_MEM_FLAG_READ_WRITE, UR_MEM_FLAG_WRITE_ONLY, UR_MEM_FLAG_READ_ONLY.

ur_kernel_native_properties_t#

struct ur_kernel_native_properties_t#

Properties for for urKernelCreateWithNativeHandle.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_KERNEL_NATIVE_PROPERTIES

void *pNext#

[in,out][optional] pointer to extension-specific structure

bool isNativeHandleOwned#

[in] Indicates UR owns the native handle or if it came from an interoperability operation in the application that asked to not transfer the ownership to the unified-runtime.

Queue#

Queue Functions#

urQueueGetInfo#

UR_APIEXPORT ur_result_t UR_APICALL urQueueGetInfo(ur_queue_handle_t hQueue, ur_queue_info_t propName, size_t propSize, void *pPropValue, size_t *pPropSizeRet)#

Query information about a command queue.

Remark

Analogues

  • clGetCommandQueueInfo

Parameters

  • hQueue – [in] handle of the queue object

  • propName – [in] name of the queue property to query

  • propSize – [in] size in bytes of the queue property value provided

  • pPropValue – [out][optional][typename(propName, propSize)] value of the queue property

  • pPropSizeRet – [out][optional] size in bytes returned in queue property value

Returns

urQueueCreate#

UR_APIEXPORT ur_result_t UR_APICALL urQueueCreate(ur_context_handle_t hContext, ur_device_handle_t hDevice, const ur_queue_properties_t *pProperties, ur_queue_handle_t *phQueue)#

Create a command queue for a device in a context.

Remark

Analogues

  • clCreateCommandQueueWithProperties

Parameters

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device object

  • pProperties – [in][optional] pointer to queue creation properties.

  • phQueue – [out] pointer to handle of queue object created

Returns

urQueueRetain#

UR_APIEXPORT ur_result_t UR_APICALL urQueueRetain(ur_queue_handle_t hQueue)#

Get a reference to the command queue handle. Increment the command queue’s reference count.

  • Useful in library function to retain access to the command queue after the caller released the queue.

Remark

Analogues

  • clRetainCommandQueue

Parameters

hQueue – [in] handle of the queue object to get access

Returns

urQueueRelease#

UR_APIEXPORT ur_result_t UR_APICALL urQueueRelease(ur_queue_handle_t hQueue)#

Decrement the command queue’s reference count and delete the command queue if the reference count becomes zero.

  • After the command queue reference count becomes zero and all queued commands in the queue have finished, the queue is deleted.

  • It also performs an implicit flush to issue all previously queued commands in the queue.

Remark

Analogues

  • clReleaseCommandQueue

Parameters

hQueue – [in] handle of the queue object to release

Returns

urQueueGetNativeHandle#

UR_APIEXPORT ur_result_t UR_APICALL urQueueGetNativeHandle(ur_queue_handle_t hQueue, ur_queue_native_desc_t *pDesc, ur_native_handle_t *phNativeQueue)#

Return queue native queue handle.

  • Retrieved native handle can be used for direct interaction with the native platform driver.

  • Use interoperability queue extensions to convert native handle to native type.

  • The application may call this function from simultaneous threads for the same context.

  • The implementation of this function should be thread-safe.

Parameters

  • hQueue – [in] handle of the queue.

  • pDesc – [in][optional] pointer to native descriptor

  • phNativeQueue – [out] a pointer to the native handle of the queue.

Returns

urQueueCreateWithNativeHandle#

UR_APIEXPORT ur_result_t UR_APICALL urQueueCreateWithNativeHandle(ur_native_handle_t hNativeQueue, ur_context_handle_t hContext, ur_device_handle_t hDevice, const ur_queue_native_properties_t *pProperties, ur_queue_handle_t *phQueue)#

Create runtime queue object from native queue handle.

  • Creates runtime queue handle from native driver queue handle.

  • The application may call this function from simultaneous threads for the same context.

  • The implementation of this function should be thread-safe.

Parameters

  • hNativeQueue – [in] the native handle of the queue.

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device object

  • pProperties – [in][optional] pointer to native queue properties struct

  • phQueue – [out] pointer to the handle of the queue object created.

Returns

urQueueFinish#

UR_APIEXPORT ur_result_t UR_APICALL urQueueFinish(ur_queue_handle_t hQueue)#

Blocks until all previously issued commands to the command queue are finished.

  • Blocks until all previously issued commands to the command queue are issued and completed.

  • urQueueFinish does not return until all enqueued commands have been processed and finished.

  • urQueueFinish acts as a synchronization point.

Remark

Analogues

  • clFinish

Parameters

hQueue – [in] handle of the queue to be finished.

Returns

urQueueFlush#

UR_APIEXPORT ur_result_t UR_APICALL urQueueFlush(ur_queue_handle_t hQueue)#

Issues all previously enqueued commands in a command queue to the device.

  • Guarantees that all enqueued commands will be issued to the appropriate device.

  • There is no guarantee that they will be completed after urQueueFlush returns.

Remark

Analogues

  • clFlush

Parameters

hQueue – [in] handle of the queue to be flushed.

Returns

Queue Enums#

ur_queue_info_t#

enum ur_queue_info_t#

Query queue info.

Values:

enumerator UR_QUEUE_INFO_CONTEXT#

[ur_queue_handle_t] context associated with this queue.

enumerator UR_QUEUE_INFO_DEVICE#

[ur_device_handle_t] device associated with this queue.

enumerator UR_QUEUE_INFO_DEVICE_DEFAULT#

[ur_queue_handle_t] the current default queue of the underlying device.

enumerator UR_QUEUE_INFO_FLAGS#

[ur_queue_flags_t] the properties associated with ur_queue_properties_t::flags.

enumerator UR_QUEUE_INFO_REFERENCE_COUNT#

[uint32_t] Reference count of the queue object. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.

enumerator UR_QUEUE_INFO_SIZE#

[uint32_t] The size of the queue

enumerator UR_QUEUE_INFO_EMPTY#

[ur_bool_t] return true if the queue was empty at the time of the query

ur_queue_flags_t#

enum ur_queue_flag_t#

Values:

enumerator UR_QUEUE_FLAG_OUT_OF_ORDER_EXEC_MODE_ENABLE#

Enable/disable out of order execution.

enumerator UR_QUEUE_FLAG_PROFILING_ENABLE#

Enable/disable profiling.

enumerator UR_QUEUE_FLAG_ON_DEVICE#

Is a device queue.

enumerator UR_QUEUE_FLAG_ON_DEVICE_DEFAULT#

Is the default queue for a device.

enumerator UR_QUEUE_FLAG_DISCARD_EVENTS#

Events will be discarded.

enumerator UR_QUEUE_FLAG_PRIORITY_LOW#

Low priority queue.

enumerator UR_QUEUE_FLAG_PRIORITY_HIGH#

High priority queue.

enumerator UR_QUEUE_FLAG_SUBMISSION_BATCHED#

Hint: enqueue and submit in a batch later. No change in queue semantics. Implementation chooses submission mode.

enumerator UR_QUEUE_FLAG_SUBMISSION_IMMEDIATE#

Hint: enqueue and submit immediately. No change in queue semantics. Implementation chooses submission mode.

enumerator UR_QUEUE_FLAG_USE_DEFAULT_STREAM#

Use the default stream. Only meaningful for CUDA. Other platforms may ignore this flag.

enumerator UR_QUEUE_FLAG_SYNC_WITH_DEFAULT_STREAM#

Synchronize with the default stream. Only meaningful for CUDA. Other platforms may ignore this flag.

Queue Structures#

ur_queue_properties_t#

struct ur_queue_properties_t#

Queue creation properties.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_QUEUE_PROPERTIES

void *pNext#

[in,out][optional] pointer to extension-specific structure

ur_queue_flags_t flags#

[in] Bitfield of queue creation flags

ur_queue_index_properties_t#

struct ur_queue_index_properties_t#

Queue index creation properties.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_QUEUE_INDEX_PROPERTIES

void *pNext#

[in,out][optional] pointer to extension-specific structure

uint32_t computeIndex#

[in] Specifies the compute index as described in the sycl_ext_intel_queue_index extension.

ur_queue_native_desc_t#

struct ur_queue_native_desc_t#

Descriptor for urQueueGetNativeHandle and urQueueCreateWithNativeHandle.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_QUEUE_NATIVE_DESC

const void *pNext#

[in][optional] pointer to extension-specific structure

void *pNativeData#

[in][optional] Adapter-specific metadata needed to create the handle.

ur_queue_native_properties_t#

struct ur_queue_native_properties_t#

Properties for for urQueueCreateWithNativeHandle.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_QUEUE_NATIVE_PROPERTIES

void *pNext#

[in,out][optional] pointer to extension-specific structure

bool isNativeHandleOwned#

[in] Indicates UR owns the native handle or if it came from an interoperability operation in the application that asked to not transfer the ownership to the unified-runtime.

Event#

Event Functions#

urEventGetInfo#

UR_APIEXPORT ur_result_t UR_APICALL urEventGetInfo(ur_event_handle_t hEvent, ur_event_info_t propName, size_t propSize, void *pPropValue, size_t *pPropSizeRet)#

Get event object information.

Remark

Analogues

  • clGetEventInfo

Parameters

  • hEvent – [in] handle of the event object

  • propName – [in] the name of the event property to query

  • propSize – [in] size in bytes of the event property value

  • pPropValue – [out][optional][typename(propName, propSize)] value of the event property

  • pPropSizeRet – [out][optional] bytes returned in event property

Returns

urEventGetProfilingInfo#

UR_APIEXPORT ur_result_t UR_APICALL urEventGetProfilingInfo(ur_event_handle_t hEvent, ur_profiling_info_t propName, size_t propSize, void *pPropValue, size_t *pPropSizeRet)#

Get profiling information for the command associated with an event object.

Remark

Analogues

  • clGetEventProfilingInfo

Parameters

  • hEvent – [in] handle of the event object

  • propName – [in] the name of the profiling property to query

  • propSize – [in] size in bytes of the profiling property value

  • pPropValue – [out][optional][typename(propName, propSize)] value of the profiling property

  • pPropSizeRet – [out][optional] pointer to the actual size in bytes returned in propValue

Returns

urEventWait#

UR_APIEXPORT ur_result_t UR_APICALL urEventWait(uint32_t numEvents, const ur_event_handle_t *phEventWaitList)#

Wait for a list of events to finish.

Remark

Analogues

  • clWaitForEvent

Parameters

  • numEvents – [in] number of events in the event list

  • phEventWaitList – [in][range(0, numEvents)] pointer to a list of events to wait for completion

Returns

urEventRetain#

UR_APIEXPORT ur_result_t UR_APICALL urEventRetain(ur_event_handle_t hEvent)#

Get a reference to an event handle. Increment the event object’s reference count.

Remark

Analogues

  • clRetainEvent

Parameters

hEvent – [in] handle of the event object

Returns

urEventRelease#

UR_APIEXPORT ur_result_t UR_APICALL urEventRelease(ur_event_handle_t hEvent)#

Decrement the event object’s reference count and delete the event object if the reference count becomes zero.

Remark

Analogues

  • clReleaseEvent

Parameters

hEvent – [in] handle of the event object

Returns

urEventGetNativeHandle#

UR_APIEXPORT ur_result_t UR_APICALL urEventGetNativeHandle(ur_event_handle_t hEvent, ur_native_handle_t *phNativeEvent)#

Return platform native event handle.

  • Retrieved native handle can be used for direct interaction with the native platform driver.

  • Use interoperability platform extensions to convert native handle to native type.

  • The application may call this function from simultaneous threads for the same context.

  • The implementation of this function should be thread-safe.

Parameters

  • hEvent – [in] handle of the event.

  • phNativeEvent – [out] a pointer to the native handle of the event.

Returns

urEventCreateWithNativeHandle#

UR_APIEXPORT ur_result_t UR_APICALL urEventCreateWithNativeHandle(ur_native_handle_t hNativeEvent, ur_context_handle_t hContext, const ur_event_native_properties_t *pProperties, ur_event_handle_t *phEvent)#

Create runtime event object from native event handle.

  • Creates runtime event handle from native driver event handle.

  • The application may call this function from simultaneous threads for the same context.

  • The implementation of this function should be thread-safe.

Parameters

  • hNativeEvent – [in] the native handle of the event.

  • hContext – [in] handle of the context object

  • pProperties – [in][optional] pointer to native event properties struct

  • phEvent – [out] pointer to the handle of the event object created.

Returns

urEventSetCallback#

UR_APIEXPORT ur_result_t UR_APICALL urEventSetCallback(ur_event_handle_t hEvent, ur_execution_info_t execStatus, ur_event_callback_t pfnNotify, void *pUserData)#

Register a user callback function for a specific command execution status.

  • The registered callback function will be called when the execution status of command associated with event changes to an execution status equal to or past the status specified by command_exec_status.

  • The application may call this function from simultaneous threads for the same context.

  • The implementation of this function should be thread-safe.

Parameters

  • hEvent – [in] handle of the event object

  • execStatus – [in] execution status of the event

  • pfnNotify – [in] execution status of the event

  • pUserData – [in][out][optional] pointer to data to be passed to callback.

Returns

Event Enums#

ur_command_t#

enum ur_command_t#

Command type.

Values:

enumerator UR_COMMAND_KERNEL_LAUNCH#

Event created by urEnqueueKernelLaunch.

enumerator UR_COMMAND_EVENTS_WAIT#

Event created by urEnqueueEventsWait.

enumerator UR_COMMAND_EVENTS_WAIT_WITH_BARRIER#

Event created by urEnqueueEventsWaitWithBarrier.

enumerator UR_COMMAND_MEM_BUFFER_READ#

Event created by urEnqueueMemBufferRead.

enumerator UR_COMMAND_MEM_BUFFER_WRITE#

Event created by urEnqueueMemBufferWrite.

enumerator UR_COMMAND_MEM_BUFFER_READ_RECT#

Event created by urEnqueueMemBufferReadRect.

enumerator UR_COMMAND_MEM_BUFFER_WRITE_RECT#

Event created by urEnqueueMemBufferWriteRect.

enumerator UR_COMMAND_MEM_BUFFER_COPY#

Event created by urEnqueueMemBufferCopy.

enumerator UR_COMMAND_MEM_BUFFER_COPY_RECT#

Event created by urEnqueueMemBufferCopyRect.

enumerator UR_COMMAND_MEM_BUFFER_FILL#

Event created by urEnqueueMemBufferFill.

enumerator UR_COMMAND_MEM_IMAGE_READ#

Event created by urEnqueueMemImageRead.

enumerator UR_COMMAND_MEM_IMAGE_WRITE#

Event created by urEnqueueMemImageWrite.

enumerator UR_COMMAND_MEM_IMAGE_COPY#

Event created by urEnqueueMemImageCopy.

enumerator UR_COMMAND_MEM_BUFFER_MAP#

Event created by urEnqueueMemBufferMap.

enumerator UR_COMMAND_MEM_UNMAP#

Event created by urEnqueueMemUnmap.

enumerator UR_COMMAND_USM_FILL#

Event created by urEnqueueUSMFill.

enumerator UR_COMMAND_USM_MEMCPY#

Event created by urEnqueueUSMMemcpy.

enumerator UR_COMMAND_USM_PREFETCH#

Event created by urEnqueueUSMPrefetch.

enumerator UR_COMMAND_USM_ADVISE#

Event created by urEnqueueUSMAdvise.

enumerator UR_COMMAND_USM_FILL_2D#

Event created by urEnqueueUSMFill2D.

enumerator UR_COMMAND_USM_MEMCPY_2D#

Event created by urEnqueueUSMMemcpy2D.

enumerator UR_COMMAND_DEVICE_GLOBAL_VARIABLE_WRITE#

Event created by urEnqueueDeviceGlobalVariableWrite.

enumerator UR_COMMAND_DEVICE_GLOBAL_VARIABLE_READ#

Event created by urEnqueueDeviceGlobalVariableRead.

enumerator UR_COMMAND_READ_HOST_PIPE#

Event created by urEnqueueReadHostPipe.

enumerator UR_COMMAND_WRITE_HOST_PIPE#

Event created by urEnqueueWriteHostPipe.

enumerator UR_COMMAND_COMMAND_BUFFER_ENQUEUE_EXP#

Event created by urCommandBufferEnqueueExp.

enumerator UR_COMMAND_INTEROP_SEMAPHORE_WAIT_EXP#

Event created by urBindlessImagesWaitExternalSemaphoreExp.

enumerator UR_COMMAND_INTEROP_SEMAPHORE_SIGNAL_EXP#

Event created by urBindlessImagesSignalExternalSemaphoreExp

ur_event_status_t#

enum ur_event_status_t#

Event Status.

Values:

enumerator UR_EVENT_STATUS_COMPLETE#

Command is complete.

enumerator UR_EVENT_STATUS_RUNNING#

Command is running.

enumerator UR_EVENT_STATUS_SUBMITTED#

Command is submitted.

enumerator UR_EVENT_STATUS_QUEUED#

Command is queued

ur_event_info_t#

enum ur_event_info_t#

Event query information type.

Values:

enumerator UR_EVENT_INFO_COMMAND_QUEUE#

[ur_queue_handle_t] Command queue information of an event object

enumerator UR_EVENT_INFO_CONTEXT#

[ur_context_handle_t] Context information of an event object

enumerator UR_EVENT_INFO_COMMAND_TYPE#

[ur_command_t] Command type information of an event object

enumerator UR_EVENT_INFO_COMMAND_EXECUTION_STATUS#

[ur_event_status_t] Command execution status of an event object

enumerator UR_EVENT_INFO_REFERENCE_COUNT#

[uint32_t] Reference count of the event object. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.

ur_profiling_info_t#

enum ur_profiling_info_t#

Profiling query information type.

Values:

enumerator UR_PROFILING_INFO_COMMAND_QUEUED#

[uint64_t] A 64-bit value of current device counter in nanoseconds when the event is enqueued

enumerator UR_PROFILING_INFO_COMMAND_SUBMIT#

[uint64_t] A 64-bit value of current device counter in nanoseconds when the event is submitted

enumerator UR_PROFILING_INFO_COMMAND_START#

[uint64_t] A 64-bit value of current device counter in nanoseconds when the event starts execution

enumerator UR_PROFILING_INFO_COMMAND_END#

[uint64_t] A 64-bit value of current device counter in nanoseconds when the event has finished execution

enumerator UR_PROFILING_INFO_COMMAND_COMPLETE#

[uint64_t] A 64-bit value of current device counter in nanoseconds when the event and any child events enqueued by this event on the device have finished execution

ur_execution_info_t#

enum ur_execution_info_t#

Event states for all events.

Values:

enumerator UR_EXECUTION_INFO_EXECUTION_INFO_COMPLETE#

Indicates that the event has completed.

enumerator UR_EXECUTION_INFO_EXECUTION_INFO_RUNNING#

Indicates that the device has started processing this event.

enumerator UR_EXECUTION_INFO_EXECUTION_INFO_SUBMITTED#

Indicates that the event has been submitted by the host to the device.

enumerator UR_EXECUTION_INFO_EXECUTION_INFO_QUEUED#

Indicates that the event has been queued, this is the initial state of events.

Event Structures#

ur_event_native_properties_t#

struct ur_event_native_properties_t#

Properties for for urEventCreateWithNativeHandle.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_EVENT_NATIVE_PROPERTIES

void *pNext#

[in,out][optional] pointer to extension-specific structure

bool isNativeHandleOwned#

[in] Indicates UR owns the native handle or if it came from an interoperability operation in the application that asked to not transfer the ownership to the unified-runtime.

Registry#

Registry Enums#

ur_function_t#

enum ur_function_t#

Defines unique stable identifiers for all functions.

Values:

enumerator UR_FUNCTION_CONTEXT_CREATE#

Enumerator for urContextCreate.

enumerator UR_FUNCTION_CONTEXT_RETAIN#

Enumerator for urContextRetain.

enumerator UR_FUNCTION_CONTEXT_RELEASE#

Enumerator for urContextRelease.

enumerator UR_FUNCTION_CONTEXT_GET_INFO#

Enumerator for urContextGetInfo.

enumerator UR_FUNCTION_CONTEXT_GET_NATIVE_HANDLE#

Enumerator for urContextGetNativeHandle.

enumerator UR_FUNCTION_CONTEXT_CREATE_WITH_NATIVE_HANDLE#

Enumerator for urContextCreateWithNativeHandle.

enumerator UR_FUNCTION_CONTEXT_SET_EXTENDED_DELETER#

Enumerator for urContextSetExtendedDeleter.

enumerator UR_FUNCTION_DEVICE_GET#

Enumerator for urDeviceGet.

enumerator UR_FUNCTION_DEVICE_GET_INFO#

Enumerator for urDeviceGetInfo.

enumerator UR_FUNCTION_DEVICE_RETAIN#

Enumerator for urDeviceRetain.

enumerator UR_FUNCTION_DEVICE_RELEASE#

Enumerator for urDeviceRelease.

enumerator UR_FUNCTION_DEVICE_PARTITION#

Enumerator for urDevicePartition.

enumerator UR_FUNCTION_DEVICE_SELECT_BINARY#

Enumerator for urDeviceSelectBinary.

enumerator UR_FUNCTION_DEVICE_GET_NATIVE_HANDLE#

Enumerator for urDeviceGetNativeHandle.

enumerator UR_FUNCTION_DEVICE_CREATE_WITH_NATIVE_HANDLE#

Enumerator for urDeviceCreateWithNativeHandle.

enumerator UR_FUNCTION_DEVICE_GET_GLOBAL_TIMESTAMPS#

Enumerator for urDeviceGetGlobalTimestamps.

enumerator UR_FUNCTION_ENQUEUE_KERNEL_LAUNCH#

Enumerator for urEnqueueKernelLaunch.

enumerator UR_FUNCTION_ENQUEUE_EVENTS_WAIT#

Enumerator for urEnqueueEventsWait.

enumerator UR_FUNCTION_ENQUEUE_EVENTS_WAIT_WITH_BARRIER#

Enumerator for urEnqueueEventsWaitWithBarrier.

enumerator UR_FUNCTION_ENQUEUE_MEM_BUFFER_READ#

Enumerator for urEnqueueMemBufferRead.

enumerator UR_FUNCTION_ENQUEUE_MEM_BUFFER_WRITE#

Enumerator for urEnqueueMemBufferWrite.

enumerator UR_FUNCTION_ENQUEUE_MEM_BUFFER_READ_RECT#

Enumerator for urEnqueueMemBufferReadRect.

enumerator UR_FUNCTION_ENQUEUE_MEM_BUFFER_WRITE_RECT#

Enumerator for urEnqueueMemBufferWriteRect.

enumerator UR_FUNCTION_ENQUEUE_MEM_BUFFER_COPY#

Enumerator for urEnqueueMemBufferCopy.

enumerator UR_FUNCTION_ENQUEUE_MEM_BUFFER_COPY_RECT#

Enumerator for urEnqueueMemBufferCopyRect.

enumerator UR_FUNCTION_ENQUEUE_MEM_BUFFER_FILL#

Enumerator for urEnqueueMemBufferFill.

enumerator UR_FUNCTION_ENQUEUE_MEM_IMAGE_READ#

Enumerator for urEnqueueMemImageRead.

enumerator UR_FUNCTION_ENQUEUE_MEM_IMAGE_WRITE#

Enumerator for urEnqueueMemImageWrite.

enumerator UR_FUNCTION_ENQUEUE_MEM_IMAGE_COPY#

Enumerator for urEnqueueMemImageCopy.

enumerator UR_FUNCTION_ENQUEUE_MEM_BUFFER_MAP#

Enumerator for urEnqueueMemBufferMap.

enumerator UR_FUNCTION_ENQUEUE_MEM_UNMAP#

Enumerator for urEnqueueMemUnmap.

enumerator UR_FUNCTION_ENQUEUE_USM_FILL#

Enumerator for urEnqueueUSMFill.

enumerator UR_FUNCTION_ENQUEUE_USM_MEMCPY#

Enumerator for urEnqueueUSMMemcpy.

enumerator UR_FUNCTION_ENQUEUE_USM_PREFETCH#

Enumerator for urEnqueueUSMPrefetch.

enumerator UR_FUNCTION_ENQUEUE_USM_ADVISE#

Enumerator for urEnqueueUSMAdvise.

enumerator UR_FUNCTION_ENQUEUE_DEVICE_GLOBAL_VARIABLE_WRITE#

Enumerator for urEnqueueDeviceGlobalVariableWrite.

enumerator UR_FUNCTION_ENQUEUE_DEVICE_GLOBAL_VARIABLE_READ#

Enumerator for urEnqueueDeviceGlobalVariableRead.

enumerator UR_FUNCTION_EVENT_GET_INFO#

Enumerator for urEventGetInfo.

enumerator UR_FUNCTION_EVENT_GET_PROFILING_INFO#

Enumerator for urEventGetProfilingInfo.

enumerator UR_FUNCTION_EVENT_WAIT#

Enumerator for urEventWait.

enumerator UR_FUNCTION_EVENT_RETAIN#

Enumerator for urEventRetain.

enumerator UR_FUNCTION_EVENT_RELEASE#

Enumerator for urEventRelease.

enumerator UR_FUNCTION_EVENT_GET_NATIVE_HANDLE#

Enumerator for urEventGetNativeHandle.

enumerator UR_FUNCTION_EVENT_CREATE_WITH_NATIVE_HANDLE#

Enumerator for urEventCreateWithNativeHandle.

enumerator UR_FUNCTION_EVENT_SET_CALLBACK#

Enumerator for urEventSetCallback.

enumerator UR_FUNCTION_KERNEL_CREATE#

Enumerator for urKernelCreate.

enumerator UR_FUNCTION_KERNEL_SET_ARG_VALUE#

Enumerator for urKernelSetArgValue.

enumerator UR_FUNCTION_KERNEL_SET_ARG_LOCAL#

Enumerator for urKernelSetArgLocal.

enumerator UR_FUNCTION_KERNEL_GET_INFO#

Enumerator for urKernelGetInfo.

enumerator UR_FUNCTION_KERNEL_GET_GROUP_INFO#

Enumerator for urKernelGetGroupInfo.

enumerator UR_FUNCTION_KERNEL_GET_SUB_GROUP_INFO#

Enumerator for urKernelGetSubGroupInfo.

enumerator UR_FUNCTION_KERNEL_RETAIN#

Enumerator for urKernelRetain.

enumerator UR_FUNCTION_KERNEL_RELEASE#

Enumerator for urKernelRelease.

enumerator UR_FUNCTION_KERNEL_SET_ARG_POINTER#

Enumerator for urKernelSetArgPointer.

enumerator UR_FUNCTION_KERNEL_SET_EXEC_INFO#

Enumerator for urKernelSetExecInfo.

enumerator UR_FUNCTION_KERNEL_SET_ARG_SAMPLER#

Enumerator for urKernelSetArgSampler.

enumerator UR_FUNCTION_KERNEL_SET_ARG_MEM_OBJ#

Enumerator for urKernelSetArgMemObj.

enumerator UR_FUNCTION_KERNEL_SET_SPECIALIZATION_CONSTANTS#

Enumerator for urKernelSetSpecializationConstants.

enumerator UR_FUNCTION_KERNEL_GET_NATIVE_HANDLE#

Enumerator for urKernelGetNativeHandle.

enumerator UR_FUNCTION_KERNEL_CREATE_WITH_NATIVE_HANDLE#

Enumerator for urKernelCreateWithNativeHandle.

enumerator UR_FUNCTION_MEM_IMAGE_CREATE#

Enumerator for urMemImageCreate.

enumerator UR_FUNCTION_MEM_BUFFER_CREATE#

Enumerator for urMemBufferCreate.

enumerator UR_FUNCTION_MEM_RETAIN#

Enumerator for urMemRetain.

enumerator UR_FUNCTION_MEM_RELEASE#

Enumerator for urMemRelease.

enumerator UR_FUNCTION_MEM_BUFFER_PARTITION#

Enumerator for urMemBufferPartition.

enumerator UR_FUNCTION_MEM_GET_NATIVE_HANDLE#

Enumerator for urMemGetNativeHandle.

enumerator UR_FUNCTION_ENQUEUE_READ_HOST_PIPE#

Enumerator for urEnqueueReadHostPipe.

enumerator UR_FUNCTION_MEM_GET_INFO#

Enumerator for urMemGetInfo.

enumerator UR_FUNCTION_MEM_IMAGE_GET_INFO#

Enumerator for urMemImageGetInfo.

enumerator UR_FUNCTION_PLATFORM_GET#

Enumerator for urPlatformGet.

enumerator UR_FUNCTION_PLATFORM_GET_INFO#

Enumerator for urPlatformGetInfo.

enumerator UR_FUNCTION_PLATFORM_GET_API_VERSION#

Enumerator for urPlatformGetApiVersion.

enumerator UR_FUNCTION_PLATFORM_GET_NATIVE_HANDLE#

Enumerator for urPlatformGetNativeHandle.

enumerator UR_FUNCTION_PLATFORM_CREATE_WITH_NATIVE_HANDLE#

Enumerator for urPlatformCreateWithNativeHandle.

enumerator UR_FUNCTION_PROGRAM_CREATE_WITH_IL#

Enumerator for urProgramCreateWithIL.

enumerator UR_FUNCTION_PROGRAM_CREATE_WITH_BINARY#

Enumerator for urProgramCreateWithBinary.

enumerator UR_FUNCTION_PROGRAM_BUILD#

Enumerator for urProgramBuild.

enumerator UR_FUNCTION_PROGRAM_COMPILE#

Enumerator for urProgramCompile.

enumerator UR_FUNCTION_PROGRAM_LINK#

Enumerator for urProgramLink.

enumerator UR_FUNCTION_PROGRAM_RETAIN#

Enumerator for urProgramRetain.

enumerator UR_FUNCTION_PROGRAM_RELEASE#

Enumerator for urProgramRelease.

enumerator UR_FUNCTION_PROGRAM_GET_FUNCTION_POINTER#

Enumerator for urProgramGetFunctionPointer.

enumerator UR_FUNCTION_PROGRAM_GET_INFO#

Enumerator for urProgramGetInfo.

enumerator UR_FUNCTION_PROGRAM_GET_BUILD_INFO#

Enumerator for urProgramGetBuildInfo.

enumerator UR_FUNCTION_PROGRAM_SET_SPECIALIZATION_CONSTANTS#

Enumerator for urProgramSetSpecializationConstants.

enumerator UR_FUNCTION_PROGRAM_GET_NATIVE_HANDLE#

Enumerator for urProgramGetNativeHandle.

enumerator UR_FUNCTION_PROGRAM_CREATE_WITH_NATIVE_HANDLE#

Enumerator for urProgramCreateWithNativeHandle.

enumerator UR_FUNCTION_QUEUE_GET_INFO#

Enumerator for urQueueGetInfo.

enumerator UR_FUNCTION_QUEUE_CREATE#

Enumerator for urQueueCreate.

enumerator UR_FUNCTION_QUEUE_RETAIN#

Enumerator for urQueueRetain.

enumerator UR_FUNCTION_QUEUE_RELEASE#

Enumerator for urQueueRelease.

enumerator UR_FUNCTION_QUEUE_GET_NATIVE_HANDLE#

Enumerator for urQueueGetNativeHandle.

enumerator UR_FUNCTION_QUEUE_CREATE_WITH_NATIVE_HANDLE#

Enumerator for urQueueCreateWithNativeHandle.

enumerator UR_FUNCTION_QUEUE_FINISH#

Enumerator for urQueueFinish.

enumerator UR_FUNCTION_QUEUE_FLUSH#

Enumerator for urQueueFlush.

enumerator UR_FUNCTION_INIT#

Enumerator for urInit.

enumerator UR_FUNCTION_TEAR_DOWN#

Enumerator for urTearDown.

enumerator UR_FUNCTION_SAMPLER_CREATE#

Enumerator for urSamplerCreate.

enumerator UR_FUNCTION_SAMPLER_RETAIN#

Enumerator for urSamplerRetain.

enumerator UR_FUNCTION_SAMPLER_RELEASE#

Enumerator for urSamplerRelease.

enumerator UR_FUNCTION_SAMPLER_GET_INFO#

Enumerator for urSamplerGetInfo.

enumerator UR_FUNCTION_SAMPLER_GET_NATIVE_HANDLE#

Enumerator for urSamplerGetNativeHandle.

enumerator UR_FUNCTION_SAMPLER_CREATE_WITH_NATIVE_HANDLE#

Enumerator for urSamplerCreateWithNativeHandle.

enumerator UR_FUNCTION_USM_HOST_ALLOC#

Enumerator for urUSMHostAlloc.

enumerator UR_FUNCTION_USM_DEVICE_ALLOC#

Enumerator for urUSMDeviceAlloc.

enumerator UR_FUNCTION_USM_SHARED_ALLOC#

Enumerator for urUSMSharedAlloc.

enumerator UR_FUNCTION_USM_FREE#

Enumerator for urUSMFree.

enumerator UR_FUNCTION_USM_GET_MEM_ALLOC_INFO#

Enumerator for urUSMGetMemAllocInfo.

enumerator UR_FUNCTION_USM_POOL_CREATE#

Enumerator for urUSMPoolCreate.

enumerator UR_FUNCTION_COMMAND_BUFFER_CREATE_EXP#

Enumerator for urCommandBufferCreateExp.

enumerator UR_FUNCTION_PLATFORM_GET_BACKEND_OPTION#

Enumerator for urPlatformGetBackendOption.

enumerator UR_FUNCTION_MEM_BUFFER_CREATE_WITH_NATIVE_HANDLE#

Enumerator for urMemBufferCreateWithNativeHandle.

enumerator UR_FUNCTION_MEM_IMAGE_CREATE_WITH_NATIVE_HANDLE#

Enumerator for urMemImageCreateWithNativeHandle.

enumerator UR_FUNCTION_ENQUEUE_WRITE_HOST_PIPE#

Enumerator for urEnqueueWriteHostPipe.

enumerator UR_FUNCTION_USM_POOL_RETAIN#

Enumerator for urUSMPoolRetain.

enumerator UR_FUNCTION_USM_POOL_RELEASE#

Enumerator for urUSMPoolRelease.

enumerator UR_FUNCTION_USM_POOL_GET_INFO#

Enumerator for urUSMPoolGetInfo.

enumerator UR_FUNCTION_COMMAND_BUFFER_RETAIN_EXP#

Enumerator for urCommandBufferRetainExp.

enumerator UR_FUNCTION_COMMAND_BUFFER_RELEASE_EXP#

Enumerator for urCommandBufferReleaseExp.

enumerator UR_FUNCTION_COMMAND_BUFFER_FINALIZE_EXP#

Enumerator for urCommandBufferFinalizeExp.

enumerator UR_FUNCTION_COMMAND_BUFFER_APPEND_KERNEL_LAUNCH_EXP#

Enumerator for urCommandBufferAppendKernelLaunchExp.

enumerator UR_FUNCTION_COMMAND_BUFFER_ENQUEUE_EXP#

Enumerator for urCommandBufferEnqueueExp.

enumerator UR_FUNCTION_COMMAND_BUFFER_APPEND_MEMCPY_USM_EXP#

Enumerator for urCommandBufferAppendMemcpyUSMExp.

enumerator UR_FUNCTION_COMMAND_BUFFER_APPEND_MEMBUFFER_COPY_EXP#

Enumerator for urCommandBufferAppendMembufferCopyExp.

enumerator UR_FUNCTION_COMMAND_BUFFER_APPEND_MEMBUFFER_COPY_RECT_EXP#

Enumerator for urCommandBufferAppendMembufferCopyRectExp.

enumerator UR_FUNCTION_USM_PITCHED_ALLOC_EXP#

Enumerator for urUSMPitchedAllocExp.

enumerator UR_FUNCTION_BINDLESS_IMAGES_UNSAMPLED_IMAGE_HANDLE_DESTROY_EXP#

Enumerator for urBindlessImagesUnsampledImageHandleDestroyExp.

enumerator UR_FUNCTION_BINDLESS_IMAGES_SAMPLED_IMAGE_HANDLE_DESTROY_EXP#

Enumerator for urBindlessImagesSampledImageHandleDestroyExp.

enumerator UR_FUNCTION_BINDLESS_IMAGES_IMAGE_ALLOCATE_EXP#

Enumerator for urBindlessImagesImageAllocateExp.

enumerator UR_FUNCTION_BINDLESS_IMAGES_IMAGE_FREE_EXP#

Enumerator for urBindlessImagesImageFreeExp.

enumerator UR_FUNCTION_BINDLESS_IMAGES_UNSAMPLED_IMAGE_CREATE_EXP#

Enumerator for urBindlessImagesUnsampledImageCreateExp.

enumerator UR_FUNCTION_BINDLESS_IMAGES_SAMPLED_IMAGE_CREATE_EXP#

Enumerator for urBindlessImagesSampledImageCreateExp.

enumerator UR_FUNCTION_BINDLESS_IMAGES_IMAGE_COPY_EXP#

Enumerator for urBindlessImagesImageCopyExp.

enumerator UR_FUNCTION_BINDLESS_IMAGES_IMAGE_GET_INFO_EXP#

Enumerator for urBindlessImagesImageGetInfoExp.

enumerator UR_FUNCTION_BINDLESS_IMAGES_MIPMAP_GET_LEVEL_EXP#

Enumerator for urBindlessImagesMipmapGetLevelExp.

enumerator UR_FUNCTION_BINDLESS_IMAGES_MIPMAP_FREE_EXP#

Enumerator for urBindlessImagesMipmapFreeExp.

enumerator UR_FUNCTION_BINDLESS_IMAGES_IMPORT_OPAQUE_FD_EXP#

Enumerator for urBindlessImagesImportOpaqueFDExp.

enumerator UR_FUNCTION_BINDLESS_IMAGES_MAP_EXTERNAL_ARRAY_EXP#

Enumerator for urBindlessImagesMapExternalArrayExp.

enumerator UR_FUNCTION_BINDLESS_IMAGES_RELEASE_INTEROP_EXP#

Enumerator for urBindlessImagesReleaseInteropExp.

enumerator UR_FUNCTION_BINDLESS_IMAGES_IMPORT_EXTERNAL_SEMAPHORE_OPAQUE_FD_EXP#

Enumerator for urBindlessImagesImportExternalSemaphoreOpaqueFDExp.

enumerator UR_FUNCTION_BINDLESS_IMAGES_DESTROY_EXTERNAL_SEMAPHORE_EXP#

Enumerator for urBindlessImagesDestroyExternalSemaphoreExp.

enumerator UR_FUNCTION_BINDLESS_IMAGES_WAIT_EXTERNAL_SEMAPHORE_EXP#

Enumerator for urBindlessImagesWaitExternalSemaphoreExp.

enumerator UR_FUNCTION_BINDLESS_IMAGES_SIGNAL_EXTERNAL_SEMAPHORE_EXP#

Enumerator for urBindlessImagesSignalExternalSemaphoreExp.

enumerator UR_FUNCTION_PLATFORM_GET_LAST_ERROR#

Enumerator for urPlatformGetLastError.

enumerator UR_FUNCTION_ENQUEUE_USM_FILL_2D#

Enumerator for urEnqueueUSMFill2D.

enumerator UR_FUNCTION_ENQUEUE_USM_MEMCPY_2D#

Enumerator for urEnqueueUSMMemcpy2D.

enumerator UR_FUNCTION_VIRTUAL_MEM_GRANULARITY_GET_INFO#

Enumerator for urVirtualMemGranularityGetInfo.

enumerator UR_FUNCTION_VIRTUAL_MEM_RESERVE#

Enumerator for urVirtualMemReserve.

enumerator UR_FUNCTION_VIRTUAL_MEM_FREE#

Enumerator for urVirtualMemFree.

enumerator UR_FUNCTION_VIRTUAL_MEM_MAP#

Enumerator for urVirtualMemMap.

enumerator UR_FUNCTION_VIRTUAL_MEM_UNMAP#

Enumerator for urVirtualMemUnmap.

enumerator UR_FUNCTION_VIRTUAL_MEM_SET_ACCESS#

Enumerator for urVirtualMemSetAccess.

enumerator UR_FUNCTION_VIRTUAL_MEM_GET_INFO#

Enumerator for urVirtualMemGetInfo.

enumerator UR_FUNCTION_PHYSICAL_MEM_CREATE#

Enumerator for urPhysicalMemCreate.

enumerator UR_FUNCTION_PHYSICAL_MEM_RETAIN#

Enumerator for urPhysicalMemRetain.

enumerator UR_FUNCTION_PHYSICAL_MEM_RELEASE#

Enumerator for urPhysicalMemRelease.

enumerator UR_FUNCTION_USM_IMPORT_EXP#

Enumerator for urUSMImportExp.

enumerator UR_FUNCTION_USM_RELEASE_EXP#

Enumerator for urUSMReleaseExp.

enumerator UR_FUNCTION_USM_P2P_ENABLE_PEER_ACCESS_EXP#

Enumerator for urUsmP2PEnablePeerAccessExp.

enumerator UR_FUNCTION_USM_P2P_DISABLE_PEER_ACCESS_EXP#

Enumerator for urUsmP2PDisablePeerAccessExp.

enumerator UR_FUNCTION_USM_P2P_PEER_ACCESS_GET_INFO_EXP#

Enumerator for urUsmP2PPeerAccessGetInfoExp.

enumerator UR_FUNCTION_COMMAND_BUFFER_APPEND_MEMBUFFER_WRITE_EXP#

Enumerator for urCommandBufferAppendMembufferWriteExp.

enumerator UR_FUNCTION_COMMAND_BUFFER_APPEND_MEMBUFFER_READ_EXP#

Enumerator for urCommandBufferAppendMembufferReadExp.

enumerator UR_FUNCTION_COMMAND_BUFFER_APPEND_MEMBUFFER_WRITE_RECT_EXP#

Enumerator for urCommandBufferAppendMembufferWriteRectExp.

enumerator UR_FUNCTION_COMMAND_BUFFER_APPEND_MEMBUFFER_READ_RECT_EXP#

Enumerator for urCommandBufferAppendMembufferReadRectExp

Enqueue#

Enqueue Functions#

urEnqueueKernelLaunch#

UR_APIEXPORT ur_result_t UR_APICALL urEnqueueKernelLaunch(ur_queue_handle_t hQueue, ur_kernel_handle_t hKernel, uint32_t workDim, const size_t *pGlobalWorkOffset, const size_t *pGlobalWorkSize, const size_t *pLocalWorkSize, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Enqueue a command to execute a kernel.

Remark

Analogues

  • clEnqueueNDRangeKernel

Parameters

  • hQueue – [in] handle of the queue object

  • hKernel – [in] handle of the kernel object

  • workDim – [in] number of dimensions, from 1 to 3, to specify the global and work-group work-items

  • pGlobalWorkOffset – [in] pointer to an array of workDim unsigned values that specify the offset used to calculate the global ID of a work-item

  • pGlobalWorkSize – [in] pointer to an array of workDim unsigned values that specify the number of global work-items in workDim that will execute the kernel function

  • pLocalWorkSize – [in][optional] pointer to an array of workDim unsigned values that specify the number of local work-items forming a work-group that will execute the kernel function. If nullptr, the runtime implementation will choose the work-group size.

  • numEventsInWaitList – [in] size of the event wait list

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before the kernel execution. If nullptr, the numEventsInWaitList must be 0, indicating that no wait event.

  • phEvent – [out][optional] return an event object that identifies this particular kernel execution instance.

Returns

urEnqueueEventsWait#

UR_APIEXPORT ur_result_t UR_APICALL urEnqueueEventsWait(ur_queue_handle_t hQueue, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Enqueue a command which waits a list of events to complete before it completes.

  • If the event list is empty, it waits for all previously enqueued commands to complete.

  • It returns an event which can be waited on.

Remark

Analogues

  • clEnqueueMarkerWithWaitList

Parameters

  • hQueue – [in] handle of the queue object

  • numEventsInWaitList – [in] size of the event wait list

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before this command can be executed. If nullptr, the numEventsInWaitList must be 0, indicating that all previously enqueued commands must be complete.

  • phEvent – [out][optional] return an event object that identifies this particular command instance.

Returns

urEnqueueEventsWaitWithBarrier#

UR_APIEXPORT ur_result_t UR_APICALL urEnqueueEventsWaitWithBarrier(ur_queue_handle_t hQueue, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Enqueue a barrier command which waits a list of events to complete before it completes.

  • If the event list is empty, it waits for all previously enqueued commands to complete.

  • It blocks command execution - any following commands enqueued after it do not execute until it completes.

  • It returns an event which can be waited on.

Remark

Analogues

  • clEnqueueBarrierWithWaitList

Parameters

  • hQueue – [in] handle of the queue object

  • numEventsInWaitList – [in] size of the event wait list

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before this command can be executed. If nullptr, the numEventsInWaitList must be 0, indicating that all previously enqueued commands must be complete.

  • phEvent – [out][optional] return an event object that identifies this particular command instance.

Returns

urEnqueueMemBufferRead#

UR_APIEXPORT ur_result_t UR_APICALL urEnqueueMemBufferRead(ur_queue_handle_t hQueue, ur_mem_handle_t hBuffer, bool blockingRead, size_t offset, size_t size, void *pDst, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Enqueue a command to read from a buffer object to host memory.

  • Input parameter blockingRead indicates if the read is blocking or non-blocking.

Remark

Analogues

  • clEnqueueReadBuffer

Parameters

  • hQueue – [in] handle of the queue object

  • hBuffer – [in] handle of the buffer object

  • blockingRead – [in] indicates blocking (true), non-blocking (false)

  • offset – [in] offset in bytes in the buffer object

  • size – [in] size in bytes of data being read

  • pDst – [in] pointer to host memory where data is to be read into

  • numEventsInWaitList – [in] size of the event wait list

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before this command can be executed. If nullptr, the numEventsInWaitList must be 0, indicating that this command does not wait on any event to complete.

  • phEvent – [out][optional] return an event object that identifies this particular command instance.

Returns

urEnqueueMemBufferWrite#

UR_APIEXPORT ur_result_t UR_APICALL urEnqueueMemBufferWrite(ur_queue_handle_t hQueue, ur_mem_handle_t hBuffer, bool blockingWrite, size_t offset, size_t size, const void *pSrc, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Enqueue a command to write into a buffer object from host memory.

  • Input parameter blockingWrite indicates if the write is blocking or non-blocking.

Remark

Analogues

  • clEnqueueWriteBuffer

Parameters

  • hQueue – [in] handle of the queue object

  • hBuffer – [in] handle of the buffer object

  • blockingWrite – [in] indicates blocking (true), non-blocking (false)

  • offset – [in] offset in bytes in the buffer object

  • size – [in] size in bytes of data being written

  • pSrc – [in] pointer to host memory where data is to be written from

  • numEventsInWaitList – [in] size of the event wait list

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before this command can be executed. If nullptr, the numEventsInWaitList must be 0, indicating that this command does not wait on any event to complete.

  • phEvent – [out][optional] return an event object that identifies this particular command instance.

Returns

urEnqueueMemBufferReadRect#

UR_APIEXPORT ur_result_t UR_APICALL urEnqueueMemBufferReadRect(ur_queue_handle_t hQueue, ur_mem_handle_t hBuffer, bool blockingRead, ur_rect_offset_t bufferOrigin, ur_rect_offset_t hostOrigin, ur_rect_region_t region, size_t bufferRowPitch, size_t bufferSlicePitch, size_t hostRowPitch, size_t hostSlicePitch, void *pDst, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Enqueue a command to read a 2D or 3D rectangular region from a buffer object to host memory.

  • Input parameter blockingRead indicates if the read is blocking or non-blocking.

  • The buffer and host 2D or 3D rectangular regions can have different shapes.

Remark

Analogues

  • clEnqueueReadBufferRect

Parameters

  • hQueue – [in] handle of the queue object

  • hBuffer – [in] handle of the buffer object

  • blockingRead – [in] indicates blocking (true), non-blocking (false)

  • bufferOrigin – [in] 3D offset in the buffer

  • hostOrigin – [in] 3D offset in the host region

  • region – [in] 3D rectangular region descriptor: width, height, depth

  • bufferRowPitch – [in] length of each row in bytes in the buffer object

  • bufferSlicePitch – [in] length of each 2D slice in bytes in the buffer object being read

  • hostRowPitch – [in] length of each row in bytes in the host memory region pointed by dst

  • hostSlicePitch – [in] length of each 2D slice in bytes in the host memory region pointed by dst

  • pDst – [in] pointer to host memory where data is to be read into

  • numEventsInWaitList – [in] size of the event wait list

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before this command can be executed. If nullptr, the numEventsInWaitList must be 0, indicating that this command does not wait on any event to complete.

  • phEvent – [out][optional] return an event object that identifies this particular command instance.

Returns

urEnqueueMemBufferWriteRect#

UR_APIEXPORT ur_result_t UR_APICALL urEnqueueMemBufferWriteRect(ur_queue_handle_t hQueue, ur_mem_handle_t hBuffer, bool blockingWrite, ur_rect_offset_t bufferOrigin, ur_rect_offset_t hostOrigin, ur_rect_region_t region, size_t bufferRowPitch, size_t bufferSlicePitch, size_t hostRowPitch, size_t hostSlicePitch, void *pSrc, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Enqueue a command to write a 2D or 3D rectangular region in a buffer object from host memory.

  • Input parameter blockingWrite indicates if the write is blocking or non-blocking.

  • The buffer and host 2D or 3D rectangular regions can have different shapes.

Remark

Analogues

  • clEnqueueWriteBufferRect

Parameters

  • hQueue – [in] handle of the queue object

  • hBuffer – [in] handle of the buffer object

  • blockingWrite – [in] indicates blocking (true), non-blocking (false)

  • bufferOrigin – [in] 3D offset in the buffer

  • hostOrigin – [in] 3D offset in the host region

  • region – [in] 3D rectangular region descriptor: width, height, depth

  • bufferRowPitch – [in] length of each row in bytes in the buffer object

  • bufferSlicePitch – [in] length of each 2D slice in bytes in the buffer object being written

  • hostRowPitch – [in] length of each row in bytes in the host memory region pointed by src

  • hostSlicePitch – [in] length of each 2D slice in bytes in the host memory region pointed by src

  • pSrc – [in] pointer to host memory where data is to be written from

  • numEventsInWaitList – [in] size of the event wait list

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] points to a list of events that must be complete before this command can be executed. If nullptr, the numEventsInWaitList must be 0, indicating that this command does not wait on any event to complete.

  • phEvent – [out][optional] return an event object that identifies this particular command instance.

Returns

urEnqueueMemBufferCopy#

UR_APIEXPORT ur_result_t UR_APICALL urEnqueueMemBufferCopy(ur_queue_handle_t hQueue, ur_mem_handle_t hBufferSrc, ur_mem_handle_t hBufferDst, size_t srcOffset, size_t dstOffset, size_t size, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Enqueue a command to copy from a buffer object to another.

Remark

Analogues

  • clEnqueueCopyBuffer

Parameters

  • hQueue – [in] handle of the queue object

  • hBufferSrc – [in] handle of the src buffer object

  • hBufferDst – [in] handle of the dest buffer object

  • srcOffset – [in] offset into hBufferSrc to begin copying from

  • dstOffset – [in] offset info hBufferDst to begin copying into

  • size – [in] size in bytes of data being copied

  • numEventsInWaitList – [in] size of the event wait list

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before this command can be executed. If nullptr, the numEventsInWaitList must be 0, indicating that this command does not wait on any event to complete.

  • phEvent – [out][optional] return an event object that identifies this particular command instance.

Returns

urEnqueueMemBufferCopyRect#

UR_APIEXPORT ur_result_t UR_APICALL urEnqueueMemBufferCopyRect(ur_queue_handle_t hQueue, ur_mem_handle_t hBufferSrc, ur_mem_handle_t hBufferDst, ur_rect_offset_t srcOrigin, ur_rect_offset_t dstOrigin, ur_rect_region_t region, size_t srcRowPitch, size_t srcSlicePitch, size_t dstRowPitch, size_t dstSlicePitch, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Enqueue a command to copy a 2D or 3D rectangular region from one buffer object to another.

Remark

Analogues

  • clEnqueueCopyBufferRect

Parameters

  • hQueue – [in] handle of the queue object

  • hBufferSrc – [in] handle of the source buffer object

  • hBufferDst – [in] handle of the dest buffer object

  • srcOrigin – [in] 3D offset in the source buffer

  • dstOrigin – [in] 3D offset in the destination buffer

  • region – [in] source 3D rectangular region descriptor: width, height, depth

  • srcRowPitch – [in] length of each row in bytes in the source buffer object

  • srcSlicePitch – [in] length of each 2D slice in bytes in the source buffer object

  • dstRowPitch – [in] length of each row in bytes in the destination buffer object

  • dstSlicePitch – [in] length of each 2D slice in bytes in the destination buffer object

  • numEventsInWaitList – [in] size of the event wait list

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before this command can be executed. If nullptr, the numEventsInWaitList must be 0, indicating that this command does not wait on any event to complete.

  • phEvent – [out][optional] return an event object that identifies this particular command instance.

Returns

urEnqueueMemBufferFill#

UR_APIEXPORT ur_result_t UR_APICALL urEnqueueMemBufferFill(ur_queue_handle_t hQueue, ur_mem_handle_t hBuffer, const void *pPattern, size_t patternSize, size_t offset, size_t size, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Enqueue a command to fill a buffer object with a pattern of a given size.

Remark

Analogues

  • clEnqueueFillBuffer

Parameters

  • hQueue – [in] handle of the queue object

  • hBuffer – [in] handle of the buffer object

  • pPattern – [in] pointer to the fill pattern

  • patternSize – [in] size in bytes of the pattern

  • offset – [in] offset into the buffer

  • size – [in] fill size in bytes, must be a multiple of patternSize

  • numEventsInWaitList – [in] size of the event wait list

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before this command can be executed. If nullptr, the numEventsInWaitList must be 0, indicating that this command does not wait on any event to complete.

  • phEvent – [out][optional] return an event object that identifies this particular command instance.

Returns

urEnqueueMemImageRead#

UR_APIEXPORT ur_result_t UR_APICALL urEnqueueMemImageRead(ur_queue_handle_t hQueue, ur_mem_handle_t hImage, bool blockingRead, ur_rect_offset_t origin, ur_rect_region_t region, size_t rowPitch, size_t slicePitch, void *pDst, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Enqueue a command to read from an image or image array object to host memory.

  • Input parameter blockingRead indicates if the read is blocking or non-blocking.

Remark

Analogues

  • clEnqueueReadImage

Parameters

  • hQueue – [in] handle of the queue object

  • hImage – [in] handle of the image object

  • blockingRead – [in] indicates blocking (true), non-blocking (false)

  • origin – [in] defines the (x,y,z) offset in pixels in the 1D, 2D, or 3D image

  • region – [in] defines the (width, height, depth) in pixels of the 1D, 2D, or 3D image

  • rowPitch – [in] length of each row in bytes

  • slicePitch – [in] length of each 2D slice of the 3D image

  • pDst – [in] pointer to host memory where image is to be read into

  • numEventsInWaitList – [in] size of the event wait list

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before this command can be executed. If nullptr, the numEventsInWaitList must be 0, indicating that this command does not wait on any event to complete.

  • phEvent – [out][optional] return an event object that identifies this particular command instance.

Returns

urEnqueueMemImageWrite#

UR_APIEXPORT ur_result_t UR_APICALL urEnqueueMemImageWrite(ur_queue_handle_t hQueue, ur_mem_handle_t hImage, bool blockingWrite, ur_rect_offset_t origin, ur_rect_region_t region, size_t rowPitch, size_t slicePitch, void *pSrc, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Enqueue a command to write an image or image array object from host memory.

  • Input parameter blockingWrite indicates if the write is blocking or non-blocking.

Remark

Analogues

  • clEnqueueWriteImage

Parameters

  • hQueue – [in] handle of the queue object

  • hImage – [in] handle of the image object

  • blockingWrite – [in] indicates blocking (true), non-blocking (false)

  • origin – [in] defines the (x,y,z) offset in pixels in the 1D, 2D, or 3D image

  • region – [in] defines the (width, height, depth) in pixels of the 1D, 2D, or 3D image

  • rowPitch – [in] length of each row in bytes

  • slicePitch – [in] length of each 2D slice of the 3D image

  • pSrc – [in] pointer to host memory where image is to be read into

  • numEventsInWaitList – [in] size of the event wait list

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before this command can be executed. If nullptr, the numEventsInWaitList must be 0, indicating that this command does not wait on any event to complete.

  • phEvent – [out][optional] return an event object that identifies this particular command instance.

Returns

urEnqueueMemImageCopy#

UR_APIEXPORT ur_result_t UR_APICALL urEnqueueMemImageCopy(ur_queue_handle_t hQueue, ur_mem_handle_t hImageSrc, ur_mem_handle_t hImageDst, ur_rect_offset_t srcOrigin, ur_rect_offset_t dstOrigin, ur_rect_region_t region, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Enqueue a command to copy from an image object to another.

Remark

Analogues

  • clEnqueueCopyImage

Parameters

  • hQueue – [in] handle of the queue object

  • hImageSrc – [in] handle of the src image object

  • hImageDst – [in] handle of the dest image object

  • srcOrigin – [in] defines the (x,y,z) offset in pixels in the source 1D, 2D, or 3D image

  • dstOrigin – [in] defines the (x,y,z) offset in pixels in the destination 1D, 2D, or 3D image

  • region – [in] defines the (width, height, depth) in pixels of the 1D, 2D, or 3D image

  • numEventsInWaitList – [in] size of the event wait list

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before this command can be executed. If nullptr, the numEventsInWaitList must be 0, indicating that this command does not wait on any event to complete.

  • phEvent – [out][optional] return an event object that identifies this particular command instance.

Returns

urEnqueueMemBufferMap#

UR_APIEXPORT ur_result_t UR_APICALL urEnqueueMemBufferMap(ur_queue_handle_t hQueue, ur_mem_handle_t hBuffer, bool blockingMap, ur_map_flags_t mapFlags, size_t offset, size_t size, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent, void **ppRetMap)#

Enqueue a command to map a region of the buffer object into the host address space and return a pointer to the mapped region.

  • Input parameter blockingMap indicates if the map is blocking or non-blocking.

  • Currently, no direct support in Level Zero. Implemented as a shared allocation followed by copying on discrete GPU

  • TODO: add a driver function in Level Zero?

Remark

Analogues

  • clEnqueueMapBuffer

Parameters

  • hQueue – [in] handle of the queue object

  • hBuffer – [in] handle of the buffer object

  • blockingMap – [in] indicates blocking (true), non-blocking (false)

  • mapFlags – [in] flags for read, write, readwrite mapping

  • offset – [in] offset in bytes of the buffer region being mapped

  • size – [in] size in bytes of the buffer region being mapped

  • numEventsInWaitList – [in] size of the event wait list

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before this command can be executed. If nullptr, the numEventsInWaitList must be 0, indicating that this command does not wait on any event to complete.

  • phEvent – [out][optional] return an event object that identifies this particular command instance.

  • ppRetMap – [out] return mapped pointer. TODO: move it before numEventsInWaitList?

Returns

urEnqueueMemUnmap#

UR_APIEXPORT ur_result_t UR_APICALL urEnqueueMemUnmap(ur_queue_handle_t hQueue, ur_mem_handle_t hMem, void *pMappedPtr, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Enqueue a command to unmap a previously mapped region of a memory object.

Remark

Analogues

  • clEnqueueUnmapMemObject

Parameters

  • hQueue – [in] handle of the queue object

  • hMem – [in] handle of the memory (buffer or image) object

  • pMappedPtr – [in] mapped host address

  • numEventsInWaitList – [in] size of the event wait list

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before this command can be executed. If nullptr, the numEventsInWaitList must be 0, indicating that this command does not wait on any event to complete.

  • phEvent – [out][optional] return an event object that identifies this particular command instance.

Returns

urEnqueueUSMFill#

UR_APIEXPORT ur_result_t UR_APICALL urEnqueueUSMFill(ur_queue_handle_t hQueue, void *ptr, size_t patternSize, const void *pPattern, size_t size, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Enqueue a command to fill USM memory.

Parameters

  • hQueue – [in] handle of the queue object

  • ptr – [in] pointer to USM memory object

  • patternSize – [in] the size in bytes of the pattern. Must be a power of 2 and less than or equal to width.

  • pPattern – [in] pointer with the bytes of the pattern to set.

  • size – [in] size in bytes to be set. Must be a multiple of patternSize.

  • numEventsInWaitList – [in] size of the event wait list

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before this command can be executed. If nullptr, the numEventsInWaitList must be 0, indicating that this command does not wait on any event to complete.

  • phEvent – [out][optional] return an event object that identifies this particular command instance.

Returns

urEnqueueUSMMemcpy#

UR_APIEXPORT ur_result_t UR_APICALL urEnqueueUSMMemcpy(ur_queue_handle_t hQueue, bool blocking, void *pDst, const void *pSrc, size_t size, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Enqueue a command to copy USM memory.

Parameters

  • hQueue – [in] handle of the queue object

  • blocking – [in] blocking or non-blocking copy

  • pDst – [in] pointer to the destination USM memory object

  • pSrc – [in] pointer to the source USM memory object

  • size – [in] size in bytes to be copied

  • numEventsInWaitList – [in] size of the event wait list

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before this command can be executed. If nullptr, the numEventsInWaitList must be 0, indicating that this command does not wait on any event to complete.

  • phEvent – [out][optional] return an event object that identifies this particular command instance.

Returns

urEnqueueUSMPrefetch#

UR_APIEXPORT ur_result_t UR_APICALL urEnqueueUSMPrefetch(ur_queue_handle_t hQueue, const void *pMem, size_t size, ur_usm_migration_flags_t flags, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Enqueue a command to prefetch USM memory.

Parameters

  • hQueue – [in] handle of the queue object

  • pMem – [in] pointer to the USM memory object

  • size – [in] size in bytes to be fetched

  • flags – [in] USM prefetch flags

  • numEventsInWaitList – [in] size of the event wait list

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before this command can be executed. If nullptr, the numEventsInWaitList must be 0, indicating that this command does not wait on any event to complete.

  • phEvent – [out][optional] return an event object that identifies this particular command instance.

Returns

urEnqueueUSMAdvise#

UR_APIEXPORT ur_result_t UR_APICALL urEnqueueUSMAdvise(ur_queue_handle_t hQueue, const void *pMem, size_t size, ur_usm_advice_flags_t advice, ur_event_handle_t *phEvent)#

Enqueue a command to set USM memory advice.

Parameters

  • hQueue – [in] handle of the queue object

  • pMem – [in] pointer to the USM memory object

  • size – [in] size in bytes to be advised

  • advice – [in] USM memory advice

  • phEvent – [out][optional] return an event object that identifies this particular command instance.

Returns

urEnqueueUSMFill2D#

UR_APIEXPORT ur_result_t UR_APICALL urEnqueueUSMFill2D(ur_queue_handle_t hQueue, void *pMem, size_t pitch, size_t patternSize, const void *pPattern, size_t width, size_t height, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Enqueue a command to fill 2D USM memory.

Parameters

  • hQueue – [in] handle of the queue to submit to.

  • pMem – [in] pointer to memory to be filled.

  • pitch – [in] the total width of the destination memory including padding.

  • patternSize – [in] the size in bytes of the pattern. Must be a power of 2 and less than or equal to width.

  • pPattern – [in] pointer with the bytes of the pattern to set.

  • width – [in] the width in bytes of each row to fill. Must be a multiple of patternSize.

  • height – [in] the height of the columns to fill.

  • numEventsInWaitList – [in] size of the event wait list

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before the kernel execution. If nullptr, the numEventsInWaitList must be 0, indicating that no wait event.

  • phEvent – [out][optional] return an event object that identifies this particular kernel execution instance.

Returns

urEnqueueUSMMemcpy2D#

UR_APIEXPORT ur_result_t UR_APICALL urEnqueueUSMMemcpy2D(ur_queue_handle_t hQueue, bool blocking, void *pDst, size_t dstPitch, const void *pSrc, size_t srcPitch, size_t width, size_t height, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Enqueue a command to copy 2D USM memory.

Parameters

  • hQueue – [in] handle of the queue to submit to.

  • blocking – [in] indicates if this operation should block the host.

  • pDst – [in] pointer to memory where data will be copied.

  • dstPitch – [in] the total width of the source memory including padding.

  • pSrc – [in] pointer to memory to be copied.

  • srcPitch – [in] the total width of the source memory including padding.

  • width – [in] the width in bytes of each row to be copied.

  • height – [in] the height of columns to be copied.

  • numEventsInWaitList – [in] size of the event wait list

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before the kernel execution. If nullptr, the numEventsInWaitList must be 0, indicating that no wait event.

  • phEvent – [out][optional] return an event object that identifies this particular kernel execution instance.

Returns

urEnqueueDeviceGlobalVariableWrite#

UR_APIEXPORT ur_result_t UR_APICALL urEnqueueDeviceGlobalVariableWrite(ur_queue_handle_t hQueue, ur_program_handle_t hProgram, const char *name, bool blockingWrite, size_t count, size_t offset, const void *pSrc, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Enqueue a command to write data from the host to device global variable.

Parameters

  • hQueue – [in] handle of the queue to submit to.

  • hProgram – [in] handle of the program containing the device global variable.

  • name – [in] the unique identifier for the device global variable.

  • blockingWrite – [in] indicates if this operation should block.

  • count – [in] the number of bytes to copy.

  • offset – [in] the byte offset into the device global variable to start copying.

  • pSrc – [in] pointer to where the data must be copied from.

  • numEventsInWaitList – [in] size of the event wait list.

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before the kernel execution. If nullptr, the numEventsInWaitList must be 0, indicating that no wait event.

  • phEvent – [out][optional] return an event object that identifies this particular kernel execution instance.

Returns

urEnqueueDeviceGlobalVariableRead#

UR_APIEXPORT ur_result_t UR_APICALL urEnqueueDeviceGlobalVariableRead(ur_queue_handle_t hQueue, ur_program_handle_t hProgram, const char *name, bool blockingRead, size_t count, size_t offset, void *pDst, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Enqueue a command to read data from a device global variable to the host.

Parameters

  • hQueue – [in] handle of the queue to submit to.

  • hProgram – [in] handle of the program containing the device global variable.

  • name – [in] the unique identifier for the device global variable.

  • blockingRead – [in] indicates if this operation should block.

  • count – [in] the number of bytes to copy.

  • offset – [in] the byte offset into the device global variable to start copying.

  • pDst – [in] pointer to where the data must be copied to.

  • numEventsInWaitList – [in] size of the event wait list.

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before the kernel execution. If nullptr, the numEventsInWaitList must be 0, indicating that no wait event.

  • phEvent – [out][optional] return an event object that identifies this particular kernel execution instance.

Returns

urEnqueueReadHostPipe#

UR_APIEXPORT ur_result_t UR_APICALL urEnqueueReadHostPipe(ur_queue_handle_t hQueue, ur_program_handle_t hProgram, const char *pipe_symbol, bool blocking, void *pDst, size_t size, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Enqueue a command to read from a pipe to the host.

Parameters

  • hQueue – [in] a valid host command-queue in which the read command will be queued. hQueue and hProgram must be created with the same UR context.

  • hProgram – [in] a program object with a successfully built executable.

  • pipe_symbol – [in] the name of the program scope pipe global variable.

  • blocking – [in] indicate if the read operation is blocking or non-blocking.

  • pDst – [in] a pointer to buffer in host memory that will hold resulting data from pipe.

  • size – [in] size of the memory region to read, in bytes.

  • numEventsInWaitList – [in] number of events in the wait list.

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before the host pipe read. If nullptr, the numEventsInWaitList must be 0, indicating that no wait event.

  • phEvent – [out][optional] returns an event object that identifies this read command and can be used to query or queue a wait for this command to complete.

Returns

urEnqueueWriteHostPipe#

UR_APIEXPORT ur_result_t UR_APICALL urEnqueueWriteHostPipe(ur_queue_handle_t hQueue, ur_program_handle_t hProgram, const char *pipe_symbol, bool blocking, void *pSrc, size_t size, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Enqueue a command to write data from the host to a pipe.

Parameters

  • hQueue – [in] a valid host command-queue in which the write command will be queued. hQueue and hProgram must be created with the same UR context.

  • hProgram – [in] a program object with a successfully built executable.

  • pipe_symbol – [in] the name of the program scope pipe global variable.

  • blocking – [in] indicate if the read and write operations are blocking or non-blocking.

  • pSrc – [in] a pointer to buffer in host memory that holds data to be written to the host pipe.

  • size – [in] size of the memory region to read or write, in bytes.

  • numEventsInWaitList – [in] number of events in the wait list.

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before the host pipe write. If nullptr, the numEventsInWaitList must be 0, indicating that no wait event.

  • phEvent – [out] returns an event object that identifies this write command and can be used to query or queue a wait for this command to complete.

Returns

Enqueue Enums#

ur_map_flags_t#

enum ur_map_flag_t#

Values:

enumerator UR_MAP_FLAG_READ#

Map for read access.

enumerator UR_MAP_FLAG_WRITE#

Map for write access.

enumerator UR_MAP_FLAG_WRITE_INVALIDATE_REGION#

Map for discard_write access

ur_usm_migration_flags_t#

enum ur_usm_migration_flag_t#

Values:

enumerator UR_USM_MIGRATION_FLAG_DEFAULT#

Default migration TODO: Add more enums!

Bindless images (experimental)#

Bindless images (experimental) Functions#

urUSMPitchedAllocExp#

UR_APIEXPORT ur_result_t UR_APICALL urUSMPitchedAllocExp(ur_context_handle_t hContext, ur_device_handle_t hDevice, const ur_usm_desc_t *pUSMDesc, ur_usm_pool_handle_t pool, size_t widthInBytes, size_t height, size_t elementSizeBytes, void **ppMem, size_t *pResultPitch)#

USM allocate pitched memory.

  • This function must support memory pooling.

  • If pUSMDesc is not NULL and pUSMDesc->pool is not NULL the allocation will be served from a specified memory pool.

  • Otherwise, the behavior is implementation-defined.

  • Allocations served from different memory pools must be isolated and must not reside on the same page.

  • Any flags/hints passed through pUSMDesc only affect the single allocation.

  • See also ur_usm_host_desc_t.

  • See also ur_usm_device_desc_t.

Remark

Analogues

  • cuMemAllocPitch

Parameters

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device object

  • pUSMDesc – [in][optional] Pointer to USM memory allocation descriptor.

  • pool – [in][optional] Pointer to a pool created using urUSMPoolCreate

  • widthInBytes – [in] width in bytes of the USM memory object to be allocated

  • height – [in] height of the USM memory object to be allocated

  • elementSizeBytes – [in] size in bytes of an element in the allocation

  • ppMem – [out] pointer to USM shared memory object

  • pResultPitch – [out] pitch of the allocation

Returns

urBindlessImagesUnsampledImageHandleDestroyExp#

UR_APIEXPORT ur_result_t UR_APICALL urBindlessImagesUnsampledImageHandleDestroyExp(ur_context_handle_t hContext, ur_exp_image_handle_t hImage)#

Destroy bindless unsampled image handles.

Remark

Analogues

  • cuSurfObjectDestroy

Parameters

  • hContext – [in] handle of the context object

  • hImage – [in] pointer to handle of image object to destroy

Returns

urBindlessImagesSampledImageHandleDestroyExp#

UR_APIEXPORT ur_result_t UR_APICALL urBindlessImagesSampledImageHandleDestroyExp(ur_context_handle_t hContext, ur_exp_image_handle_t hImage)#

Destroy bindless sampled image handles.

Remark

Analogues

  • cuTexObjectDestroy

Parameters

  • hContext – [in] handle of the context object

  • hImage – [in] pointer to handle of image object to destroy

Returns

urBindlessImagesImageAllocateExp#

UR_APIEXPORT ur_result_t UR_APICALL urBindlessImagesImageAllocateExp(ur_context_handle_t hContext, const ur_image_format_t *pImageFormat, const ur_image_desc_t *pImageDesc, ur_exp_image_mem_handle_t *phImageMem)#

Allocate memory for bindless images.

Remark

Analogues

  • cuArray3DCreate

  • cuMipmappedArrayCreate

Parameters

  • hContext – [in] handle of the context object

  • pImageFormat – [in] pointer to image format specification

  • pImageDesc – [in] pointer to image description

  • phImageMem – [out] pointer to handle of image memory allocated

Returns

urBindlessImagesImageFreeExp#

UR_APIEXPORT ur_result_t UR_APICALL urBindlessImagesImageFreeExp(ur_context_handle_t hContext, ur_exp_image_mem_handle_t hImageMem)#

Free memory for bindless images.

Remark

Analogues

  • cuArrayDestroy

Parameters

  • hContext – [in] handle of the context object

  • hImageMem – [in] handle of image memory to be freed

Returns

urBindlessImagesUnsampledImageCreateExp#

UR_APIEXPORT ur_result_t UR_APICALL urBindlessImagesUnsampledImageCreateExp(ur_context_handle_t hContext, ur_exp_image_mem_handle_t hImageMem, const ur_image_format_t *pImageFormat, const ur_image_desc_t *pImageDesc, ur_mem_handle_t *phMem, ur_exp_image_handle_t *phImage)#

Create a bindless unsampled image handle.

Remark

Analogues

  • cuSurfObjectCreate

Parameters

  • hContext – [in] handle of the context object

  • hImageMem – [in] handle to memory from which to create the image

  • pImageFormat – [in] pointer to image format specification

  • pImageDesc – [in] pointer to image description

  • phMem – [out] pointer to handle of image object created

  • phImage – [out] pointer to handle of image object created

Returns

urBindlessImagesSampledImageCreateExp#

UR_APIEXPORT ur_result_t UR_APICALL urBindlessImagesSampledImageCreateExp(ur_context_handle_t hContext, ur_exp_image_mem_handle_t hImageMem, const ur_image_format_t *pImageFormat, const ur_image_desc_t *pImageDesc, ur_sampler_handle_t hSampler, ur_mem_handle_t *phMem, ur_exp_image_handle_t *phImage)#

Create a bindless sampled image handle.

Remark

Analogues

  • cuTexObjectCreate

Parameters

  • hContext – [in] handle of the context object

  • hImageMem – [in] handle to memory from which to create the image

  • pImageFormat – [in] pointer to image format specification

  • pImageDesc – [in] pointer to image description

  • hSampler – [in] sampler to be used

  • phMem – [out] pointer to handle of image object created

  • phImage – [out] pointer to handle of image object created

Returns

urBindlessImagesImageCopyExp#

UR_APIEXPORT ur_result_t UR_APICALL urBindlessImagesImageCopyExp(ur_context_handle_t hContext, void *pDst, void *pSrc, const ur_image_format_t *pImageFormat, const ur_image_desc_t *pImageDesc, ur_exp_image_copy_flags_t imageCopyFlags, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Copy image data Host to Device or Device to Host.

Remark

Analogues

  • cuMemcpyHtoAAsync

  • cuMemcpyAtoHAsync

  • cuMemcpy2DAsync

  • cuMemcpy3DAsync

Parameters

  • hContext – [in] handle of the context object

  • pDst – [in] location the data will be copied to

  • pSrc – [in] location the data will be copied from

  • pImageFormat – [in] pointer to image format specification

  • pImageDesc – [in] pointer to image description

  • imageCopyFlags – [in] flags describing copy direction e.g. H2D or D2H

  • numEventsInWaitList – [in] size of the event wait list

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before this command can be executed. If nullptr, the numEventsInWaitList must be 0, indicating that all previously enqueued commands must be complete.

  • phEvent – [out][optional] return an event object that identifies this particular command instance.

Returns

urBindlessImagesImageGetInfoExp#

UR_APIEXPORT ur_result_t UR_APICALL urBindlessImagesImageGetInfoExp(ur_exp_image_mem_handle_t hImageMem, ur_image_info_t propName, void *pPropValue, size_t *pPropSizeRet)#

Query an image memory handle for specific properties.

Parameters

  • hImageMem – [in] handle to the image memory

  • propName – [in] queried info name

  • pPropValue – [out][optional] returned query value

  • pPropSizeRet – [out][optional] returned query value size

Returns

urBindlessImagesMipmapGetLevelExp#

UR_APIEXPORT ur_result_t UR_APICALL urBindlessImagesMipmapGetLevelExp(ur_context_handle_t hContext, ur_exp_image_mem_handle_t hImageMem, uint32_t mipmapLevel, ur_exp_image_mem_handle_t *phImageMem)#

Retrieve individual image from mipmap.

Remark

Analogues

  • cuMipmappedArrayGetLevel

Parameters

  • hContext – [in] handle of the context object

  • hImageMem – [in] memory handle to the mipmap image

  • mipmapLevel – [in] requested level of the mipmap

  • phImageMem – [out] returning memory handle to the individual image

Returns

urBindlessImagesMipmapFreeExp#

UR_APIEXPORT ur_result_t UR_APICALL urBindlessImagesMipmapFreeExp(ur_context_handle_t hContext, ur_exp_image_mem_handle_t hMem)#

Free mipmap memory for bindless images.

Remark

Analogues

  • cuMipmappedArrayDestroy

Parameters

  • hContext – [in] handle of the context object

  • hMem – [in] handle of image memory to be freed

Returns

urBindlessImagesImportOpaqueFDExp#

UR_APIEXPORT ur_result_t UR_APICALL urBindlessImagesImportOpaqueFDExp(ur_context_handle_t hContext, size_t size, uint32_t fileDescriptor, ur_exp_interop_mem_handle_t *phInteropMem)#

Import external memory in the form of a file descriptor.

Remark

Analogues

  • cuImportExternalMemory

Parameters

  • hContext – [in] handle of the context object

  • size – [in] size of the external memory

  • fileDescriptor – [in] the file descriptor

  • phInteropMem – [out] interop memory handle to the external memory

Returns

urBindlessImagesMapExternalArrayExp#

UR_APIEXPORT ur_result_t UR_APICALL urBindlessImagesMapExternalArrayExp(ur_context_handle_t hContext, const ur_image_format_t *pImageFormat, const ur_image_desc_t *pImageDesc, ur_exp_interop_mem_handle_t hInteropMem, ur_exp_image_handle_t *phImageMem)#

Map an interop memory handle to an image memory handle.

Parameters

  • hContext – [in] handle of the context object

  • pImageFormat – [in] pointer to image format specification

  • pImageDesc – [in] pointer to image description

  • hInteropMem – [in] interop memory handle to the external memory

  • phImageMem – [out] image memory handle to the externally allocated memory

Returns

urBindlessImagesReleaseInteropExp#

UR_APIEXPORT ur_result_t UR_APICALL urBindlessImagesReleaseInteropExp(ur_context_handle_t hContext, ur_exp_interop_mem_handle_t hInteropMem)#

Destroy interop memory.

Remark

Analogues

  • cuDestroyExternalMemory

Parameters

  • hContext – [in] handle of the context object

  • hInteropMem – [in] handle of interop memory to be freed

Returns

urBindlessImagesImportExternalSemaphoreOpaqueFDExp#

UR_APIEXPORT ur_result_t UR_APICALL urBindlessImagesImportExternalSemaphoreOpaqueFDExp(ur_context_handle_t hContext, uint32_t fileDescriptor, ur_exp_interop_semaphore_handle_t *phInteropSemaphoreHandle)#

Import an external semaphore in the form of a file descriptor.

Remark

Analogues

  • cuImportExternalSemaphore

Parameters

  • hContext – [in] handle of the context object

  • fileDescriptor – [in] the file descriptor

  • phInteropSemaphoreHandle – [out] interop semaphore handle to the external semaphore

Returns

urBindlessImagesDestroyExternalSemaphoreExp#

UR_APIEXPORT ur_result_t UR_APICALL urBindlessImagesDestroyExternalSemaphoreExp(ur_context_handle_t hContext, ur_exp_interop_semaphore_handle_t hInteropSemaphore)#

Destroy the external semaphore handle.

Remark

Analogues

  • cuDestroyExternalSemaphore

Parameters

  • hContext – [in] handle of the context object

  • hInteropSemaphore – [in] handle of interop semaphore to be destroyed

Returns

urBindlessImagesWaitExternalSemaphoreExp#

UR_APIEXPORT ur_result_t UR_APICALL urBindlessImagesWaitExternalSemaphoreExp(ur_queue_handle_t hQueue, ur_exp_interop_semaphore_handle_t hSemaphore, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Instruct the queue with a non-blocking wait on an external semaphore.

Remark

Analogues

  • cuWaitExternalSemaphoresAsync

Parameters

  • hQueue – [in] handle of the queue object

  • hSemaphore – [in] interop semaphore handle

  • numEventsInWaitList – [in] size of the event wait list

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before this command can be executed. If nullptr, the numEventsInWaitList must be 0, indicating that all previously enqueued commands must be complete.

  • phEvent – [out][optional] return an event object that identifies this particular command instance.

Returns

urBindlessImagesSignalExternalSemaphoreExp#

UR_APIEXPORT ur_result_t UR_APICALL urBindlessImagesSignalExternalSemaphoreExp(ur_queue_handle_t hQueue, ur_exp_interop_semaphore_handle_t hSemaphore, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Instruct the queue to signal the external semaphore handle once all previous commands have completed execution.

Remark

Analogues

  • cuSignalExternalSemaphoresAsync

Parameters

  • hQueue – [in] handle of the queue object

  • hSemaphore – [in] interop semaphore handle

  • numEventsInWaitList – [in] size of the event wait list

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before this command can be executed. If nullptr, the numEventsInWaitList must be 0, indicating that all previously enqueued commands must be complete.

  • phEvent – [out][optional] return an event object that identifies this particular command instance.

Returns

Bindless images (experimental) Enums#

ur_exp_image_copy_flags_t#

enum ur_exp_image_copy_flag_t#

Values:

enumerator UR_EXP_IMAGE_COPY_FLAG_HOST_TO_DEVICE#

Host to device.

enumerator UR_EXP_IMAGE_COPY_FLAG_DEVICE_TO_HOST#

Device to host.

enumerator UR_EXP_IMAGE_COPY_FLAG_DEVICE_TO_DEVICE#

Device to device

Bindless images (experimental) Structures#

ur_exp_sampler_mip_properties_t#

struct ur_exp_sampler_mip_properties_t#

Describes mipmap sampler properties.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_EXP_SAMPLER_MIP_PROPERTIES

void *pNext#

[in,out][optional] pointer to extension-specific structure

float minMipmapLevelClamp#

[in] minimum mipmap level from which we can sample, minimum value being 0

float maxMipmapLevelClamp#

[in] maximum mipmap level from which we can sample, maximum value being the number of levels

float maxAnistropy#

[in] anisotropic ratio used when samplling the mipmap with anisotropic filtering

Command buffer (experimental)#

Command buffer (experimental) Functions#

urCommandBufferCreateExp#

UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferCreateExp(ur_context_handle_t hContext, ur_device_handle_t hDevice, const ur_exp_command_buffer_desc_t *pCommandBufferDesc, ur_exp_command_buffer_handle_t *phCommandBuffer)#

Create a Command-Buffer object.

  • Create a command-buffer object

Parameters

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device object

  • pCommandBufferDesc – [in][optional] CommandBuffer descriptor

  • phCommandBuffer – [out] pointer to Command-Buffer handle

Returns

urCommandBufferRetainExp#

UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferRetainExp(ur_exp_command_buffer_handle_t hCommandBuffer)#

Increment the command-buffer object’s reference count.

Parameters

hCommandBuffer – [in] handle of the command-buffer object

Returns

urCommandBufferReleaseExp#

UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferReleaseExp(ur_exp_command_buffer_handle_t hCommandBuffer)#

Decrement the command-buffer object’s reference count and delete the command-buffer object if the reference count becomes zero.

Parameters

hCommandBuffer – [in] handle of the command-buffer object

Returns

urCommandBufferFinalizeExp#

UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferFinalizeExp(ur_exp_command_buffer_handle_t hCommandBuffer)#

Stop recording on a command-buffer object such that no more commands can be appended and make it ready to enqueue.

Parameters

hCommandBuffer – [in] handle of the command-buffer object

Returns

urCommandBufferAppendKernelLaunchExp#

UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferAppendKernelLaunchExp(ur_exp_command_buffer_handle_t hCommandBuffer, ur_kernel_handle_t hKernel, uint32_t workDim, const size_t *pGlobalWorkOffset, const size_t *pGlobalWorkSize, const size_t *pLocalWorkSize, uint32_t numSyncPointsInWaitList, const ur_exp_command_buffer_sync_point_t *pSyncPointWaitList, ur_exp_command_buffer_sync_point_t *pSyncPoint)#

Append a kernel execution command to a command-buffer object.

Parameters

  • hCommandBuffer – [in] handle of the command-buffer object

  • hKernel – [in] kernel to append

  • workDim – [in] dimension of the kernel execution

  • pGlobalWorkOffset – [in] Offset to use when executing kernel.

  • pGlobalWorkSize – [in] Global work size to use when executing kernel.

  • pLocalWorkSize – [in] Local work size to use when executing kernel.

  • numSyncPointsInWaitList – [in] The number of sync points in the provided dependency list.

  • pSyncPointWaitList – [in][optional] A list of sync points that this command depends on.

  • pSyncPoint – [out][optional] sync point associated with this command

Returns

urCommandBufferAppendMemcpyUSMExp#

UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferAppendMemcpyUSMExp(ur_exp_command_buffer_handle_t hCommandBuffer, void *pDst, const void *pSrc, size_t size, uint32_t numSyncPointsInWaitList, const ur_exp_command_buffer_sync_point_t *pSyncPointWaitList, ur_exp_command_buffer_sync_point_t *pSyncPoint)#

Append a USM memcpy command to a command-buffer object.

Parameters

  • hCommandBuffer – [in] handle of the command-buffer object.

  • pDst – [in] Location the data will be copied to.

  • pSrc – [in] The data to be copied.

  • size – [in] The number of bytes to copy

  • numSyncPointsInWaitList – [in] The number of sync points in the provided dependency list.

  • pSyncPointWaitList – [in][optional] A list of sync points that this command depends on.

  • pSyncPoint – [out][optional] sync point associated with this command

Returns

urCommandBufferAppendMembufferCopyExp#

UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferAppendMembufferCopyExp(ur_exp_command_buffer_handle_t hCommandBuffer, ur_mem_handle_t hSrcMem, ur_mem_handle_t hDstMem, size_t srcOffset, size_t dstOffset, size_t size, uint32_t numSyncPointsInWaitList, const ur_exp_command_buffer_sync_point_t *pSyncPointWaitList, ur_exp_command_buffer_sync_point_t *pSyncPoint)#

Append a memory copy command to a command-buffer object.

Parameters

  • hCommandBuffer – [in] handle of the command-buffer object.

  • hSrcMem – [in] The data to be copied.

  • hDstMem – [in] The location the data will be copied to.

  • srcOffset – [in] Offset into the source memory.

  • dstOffset – [in] Offset into the destination memory

  • size – [in] The number of bytes to be copied.

  • numSyncPointsInWaitList – [in] The number of sync points in the provided dependency list.

  • pSyncPointWaitList – [in][optional] A list of sync points that this command depends on.

  • pSyncPoint – [out][optional] sync point associated with this command

Returns

urCommandBufferAppendMembufferWriteExp#

UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferAppendMembufferWriteExp(ur_exp_command_buffer_handle_t hCommandBuffer, ur_mem_handle_t hBuffer, size_t offset, size_t size, const void *pSrc, uint32_t numSyncPointsInWaitList, const ur_exp_command_buffer_sync_point_t *pSyncPointWaitList, ur_exp_command_buffer_sync_point_t *pSyncPoint)#

Append a memory write command to a command-buffer object.

Parameters

  • hCommandBuffer – [in] handle of the command-buffer object.

  • hBuffer – [in] handle of the buffer object.

  • offset – [in] offset in bytes in the buffer object.

  • size – [in] size in bytes of data being written.

  • pSrc – [in] pointer to host memory where data is to be written from.

  • numSyncPointsInWaitList – [in] The number of sync points in the provided dependency list.

  • pSyncPointWaitList – [in][optional] A list of sync points that this command depends on.

  • pSyncPoint – [out][optional] sync point associated with this command

Returns

urCommandBufferAppendMembufferReadExp#

UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferAppendMembufferReadExp(ur_exp_command_buffer_handle_t hCommandBuffer, ur_mem_handle_t hBuffer, size_t offset, size_t size, void *pDst, uint32_t numSyncPointsInWaitList, const ur_exp_command_buffer_sync_point_t *pSyncPointWaitList, ur_exp_command_buffer_sync_point_t *pSyncPoint)#

Append a memory read command to a command-buffer object.

Parameters

  • hCommandBuffer – [in] handle of the command-buffer object.

  • hBuffer – [in] handle of the buffer object.

  • offset – [in] offset in bytes in the buffer object.

  • size – [in] size in bytes of data being written.

  • pDst – [in] pointer to host memory where data is to be written to.

  • numSyncPointsInWaitList – [in] The number of sync points in the provided dependency list.

  • pSyncPointWaitList – [in][optional] A list of sync points that this command depends on.

  • pSyncPoint – [out][optional] sync point associated with this command

Returns

urCommandBufferAppendMembufferCopyRectExp#

UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferAppendMembufferCopyRectExp(ur_exp_command_buffer_handle_t hCommandBuffer, ur_mem_handle_t hSrcMem, ur_mem_handle_t hDstMem, ur_rect_offset_t srcOrigin, ur_rect_offset_t dstOrigin, ur_rect_region_t region, size_t srcRowPitch, size_t srcSlicePitch, size_t dstRowPitch, size_t dstSlicePitch, uint32_t numSyncPointsInWaitList, const ur_exp_command_buffer_sync_point_t *pSyncPointWaitList, ur_exp_command_buffer_sync_point_t *pSyncPoint)#

Append a rectangular memory copy command to a command-buffer object.

Parameters

  • hCommandBuffer – [in] handle of the command-buffer object.

  • hSrcMem – [in] The data to be copied.

  • hDstMem – [in] The location the data will be copied to.

  • srcOrigin – [in] Origin for the region of data to be copied from the source.

  • dstOrigin – [in] Origin for the region of data to be copied to in the destination.

  • region – [in] The extents describing the region to be copied.

  • srcRowPitch – [in] Row pitch of the source memory.

  • srcSlicePitch – [in] Slice pitch of the source memory.

  • dstRowPitch – [in] Row pitch of the destination memory.

  • dstSlicePitch – [in] Slice pitch of the destination memory.

  • numSyncPointsInWaitList – [in] The number of sync points in the provided dependency list.

  • pSyncPointWaitList – [in][optional] A list of sync points that this command depends on.

  • pSyncPoint – [out][optional] sync point associated with this command

Returns

urCommandBufferAppendMembufferWriteRectExp#

UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferAppendMembufferWriteRectExp(ur_exp_command_buffer_handle_t hCommandBuffer, ur_mem_handle_t hBuffer, ur_rect_offset_t bufferOffset, ur_rect_offset_t hostOffset, ur_rect_region_t region, size_t bufferRowPitch, size_t bufferSlicePitch, size_t hostRowPitch, size_t hostSlicePitch, void *pSrc, uint32_t numSyncPointsInWaitList, const ur_exp_command_buffer_sync_point_t *pSyncPointWaitList, ur_exp_command_buffer_sync_point_t *pSyncPoint)#

Append a rectangular memory write command to a command-buffer object.

Parameters

  • hCommandBuffer – [in] handle of the command-buffer object.

  • hBuffer – [in] handle of the buffer object.

  • bufferOffset – [in] 3D offset in the buffer.

  • hostOffset – [in] 3D offset in the host region.

  • region – [in] 3D rectangular region descriptor: width, height, depth.

  • bufferRowPitch – [in] length of each row in bytes in the buffer object.

  • bufferSlicePitch – [in] length of each 2D slice in bytes in the buffer object being written.

  • hostRowPitch – [in] length of each row in bytes in the host memory region pointed to by pSrc.

  • hostSlicePitch – [in] length of each 2D slice in bytes in the host memory region pointed to by pSrc.

  • pSrc – [in] pointer to host memory where data is to be written from.

  • numSyncPointsInWaitList – [in] The number of sync points in the provided dependency list.

  • pSyncPointWaitList – [in][optional] A list of sync points that this command depends on.

  • pSyncPoint – [out][optional] sync point associated with this command

Returns

urCommandBufferAppendMembufferReadRectExp#

UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferAppendMembufferReadRectExp(ur_exp_command_buffer_handle_t hCommandBuffer, ur_mem_handle_t hBuffer, ur_rect_offset_t bufferOffset, ur_rect_offset_t hostOffset, ur_rect_region_t region, size_t bufferRowPitch, size_t bufferSlicePitch, size_t hostRowPitch, size_t hostSlicePitch, void *pDst, uint32_t numSyncPointsInWaitList, const ur_exp_command_buffer_sync_point_t *pSyncPointWaitList, ur_exp_command_buffer_sync_point_t *pSyncPoint)#

Append a rectangular memory read command to a command-buffer object.

Parameters

  • hCommandBuffer – [in] handle of the command-buffer object.

  • hBuffer – [in] handle of the buffer object.

  • bufferOffset – [in] 3D offset in the buffer.

  • hostOffset – [in] 3D offset in the host region.

  • region – [in] 3D rectangular region descriptor: width, height, depth.

  • bufferRowPitch – [in] length of each row in bytes in the buffer object.

  • bufferSlicePitch – [in] length of each 2D slice in bytes in the buffer object being read.

  • hostRowPitch – [in] length of each row in bytes in the host memory region pointed to by pDst.

  • hostSlicePitch – [in] length of each 2D slice in bytes in the host memory region pointed to by pDst.

  • pDst – [in] pointer to host memory where data is to be read into.

  • numSyncPointsInWaitList – [in] The number of sync points in the provided dependency list.

  • pSyncPointWaitList – [in][optional] A list of sync points that this command depends on.

  • pSyncPoint – [out][optional] sync point associated with this command

Returns

urCommandBufferEnqueueExp#

UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferEnqueueExp(ur_exp_command_buffer_handle_t hCommandBuffer, ur_queue_handle_t hQueue, uint32_t numEventsInWaitList, const ur_event_handle_t *phEventWaitList, ur_event_handle_t *phEvent)#

Submit a command-buffer for execution on a queue.

Parameters

  • hCommandBuffer – [in] handle of the command-buffer object.

  • hQueue – [in] the queue to submit this command-buffer for execution.

  • numEventsInWaitList – [in] size of the event wait list

  • phEventWaitList – [in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before the command-buffer execution. If nullptr, the numEventsInWaitList must be 0, indicating no wait events.

  • phEvent – [out][optional] return an event object that identifies this particular command-buffer execution instance.

Returns

Command buffer (experimental) Structures#

ur_exp_command_buffer_desc_t#

struct ur_exp_command_buffer_desc_t#

Command-Buffer Descriptor Type.

Public Members

ur_structure_type_t stype#

[in] type of this structure, must be UR_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_DESC

const void *pNext#

[in][optional] pointer to extension-specific structure

Usm import release (experimental)#

Usm import release (experimental) Functions#

urUSMImportExp#

UR_APIEXPORT ur_result_t UR_APICALL urUSMImportExp(ur_context_handle_t hContext, void *pMem, size_t size)#

Import memory into USM.

  • Import memory into USM

Parameters

  • hContext – [in] handle of the context object

  • pMem – [in] pointer to host memory object

  • size – [in] size in bytes of the host memory object to be imported

Returns

urUSMReleaseExp#

UR_APIEXPORT ur_result_t UR_APICALL urUSMReleaseExp(ur_context_handle_t hContext, void *pMem)#

Release memory from USM.

  • Release memory from USM

Parameters

  • hContext – [in] handle of the context object

  • pMem – [in] pointer to host memory object

Returns

Usm p2p (experimental)#

Usm p2p (experimental) Functions#

urUsmP2PEnablePeerAccessExp#

UR_APIEXPORT ur_result_t UR_APICALL urUsmP2PEnablePeerAccessExp(ur_device_handle_t commandDevice, ur_device_handle_t peerDevice)#

Enable access to peer device memory.

  • Enables the command device to access and write device memory allocations located on the peer device, provided that a P2P link between the two devices is available.

  • When Peer Access is successfully enabled, P2P memory accesses are guaranteed to be allowed on the peer device until urUsmP2PDisablePeerAccessExp is called.

  • Note that the function operands may, but aren’t guaranteed to, commute for a given adapter: the peer device is not guaranteed to have access to device memory allocations located on the command device.

  • It is not guaranteed that the commutation relations of the function arguments are identical for peer access and peer copies: For example, for a given adapter the peer device may be able to copy data from the command device, but not access and write the same data on the command device.

  • Consult the appropriate adapter driver documentation for details of adapter specific behavior and native error codes that may be returned.

Remark

Analogues

  • cuCtxEnablePeerAccess

Parameters

  • commandDevice – [in] handle of the command device object

  • peerDevice – [in] handle of the peer device object

Returns

urUsmP2PDisablePeerAccessExp#

UR_APIEXPORT ur_result_t UR_APICALL urUsmP2PDisablePeerAccessExp(ur_device_handle_t commandDevice, ur_device_handle_t peerDevice)#

Disable access to peer device memory.

  • Disables the ability of the command device to access and write device memory allocations located on the peer device, provided that a P2P link between the two devices was enabled prior to the call.

  • Note that the function operands may, but aren’t guaranteed to, commute for a given adapter. If, prior to the function call, the peer device had access to device memory allocations on the command device, it is not guaranteed to still have such access following the function return.

  • It is not guaranteed that the commutation relations of the function arguments are identical for peer access and peer copies: For example for a given adapter, if, prior to the call, the peer device had access to device memory allocations on the command device, the peer device may still, following the function call, be able to copy data from the command device, but not access and write the same data on the command device.

  • Consult the appropriate adapter driver documentation for details of adapter specific behavior and native error codes that may be returned.

Remark

Analogues

  • cuCtxDisablePeerAccess

Parameters

  • commandDevice – [in] handle of the command device object

  • peerDevice – [in] handle of the peer device object

Returns

urUsmP2PPeerAccessGetInfoExp#

UR_APIEXPORT ur_result_t UR_APICALL urUsmP2PPeerAccessGetInfoExp(ur_device_handle_t commandDevice, ur_device_handle_t peerDevice, ur_exp_peer_info_t propName, size_t propSize, void *pPropValue, size_t *pPropSizeRet)#

Disable access to peer device memory.

  • Queries the peer access capabilities from the command device to the peer device according to the query propName.

Remark

Analogues

  • cuDeviceGetP2PAttribute

Parameters

  • commandDevice – [in] handle of the command device object

  • peerDevice – [in] handle of the peer device object

  • propName – [in] type of the info to retrieve

  • propSize – [in] the number of bytes pointed to by pPropValue.

  • pPropValue – [out][optional][typename(propName, propSize)] array of bytes holding the info. If propSize is not equal to or greater than the real number of bytes needed to return the info then the UR_RESULT_ERROR_INVALID_SIZE error is returned and pPropValue is not used.

  • pPropSizeRet – [out][optional] pointer to the actual size in bytes of the queried propName.

Returns

Usm p2p (experimental) Enums#

ur_exp_peer_info_t#

enum ur_exp_peer_info_t#

Supported peer info.

Values:

enumerator UR_EXP_PEER_INFO_UR_PEER_ACCESS_SUPPORTED#

[uint32_t] 1 if P2P access is supported otherwise P2P access is not supported.

enumerator UR_EXP_PEER_INFO_UR_PEER_ATOMICS_SUPPORTED#

[uint32_t] 1 if atomic operations are supported over the P2P link, otherwise such operations are not supported.