Kernel - Experimental

oneAPI Level Zero Specification - Version 1.18.31

Kernel - Experimental Functions

zeKernelSetGlobalOffsetExp

Added in version 1.1

ZE_APIEXPORT ze_result_t ZE_APICALL zeKernelSetGlobalOffsetExp(ze_kernel_handle_t hKernel, uint32_t offsetX, uint32_t offsetY, uint32_t offsetZ)

Set global work offset for a kernel.

• The global work offset will be used when a zeCommandListAppendLaunchKernel() variant is called.

• The application must not 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

• offsetX – [in] global offset for X dimension to use for this kernel

• offsetY – [in] global offset for Y dimension to use for this kernel

• offsetZ – [in] global offset for Z dimension to use for this kernel

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hKernel

zeKernelSchedulingHintExp

Added in version 1.2

ZE_APIEXPORT ze_result_t ZE_APICALL zeKernelSchedulingHintExp(ze_kernel_handle_t hKernel, ze_scheduling_hint_exp_desc_t *pHint)

Provide kernel scheduling hints that may improve performance.

• The scheduling hints may improve performance only and are not required for correctness.

• If a specified scheduling hint is unsupported it will be silently ignored.

• If two conflicting scheduling hints are specified there is no defined behavior; the hints may be ignored or one hint may be chosen arbitrarily.

• The application must not 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

• pHint – [in] pointer to kernel scheduling hint descriptor

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hKernel

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pHint

• ZE_RESULT_ERROR_INVALID_ENUMERATION

  • 0x7 < pHint->flags

• ZE_RESULT_ERROR_UNSUPPORTED_ENUMERATION

zeKernelGetBinaryExp

Added in version 1.11

ZE_APIEXPORT ze_result_t ZE_APICALL zeKernelGetBinaryExp(ze_kernel_handle_t hKernel, size_t *pSize, uint8_t *pKernelBinary)

Retrieves kernel binary program data (ISA GEN format).

• A valid kernel handle must be created with zeKernelCreate.

• Returns Intel Graphics Assembly (GEN ISA) format binary program data for kernel handle.

• The application may call this function from simultaneous threads.

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

Parameters:

• hKernel – [in] Kernel handle.

• pSize – [in,out] pointer to variable with size of GEN ISA binary.

• pKernelBinary – [in,out] pointer to storage area for GEN ISA binary function.

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hKernel

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pSize

  • nullptr == pKernelBinary

zeKernelGetAllocationPropertiesExp

Added in version 1.14

ZE_APIEXPORT ze_result_t ZE_APICALL zeKernelGetAllocationPropertiesExp(ze_kernel_handle_t hKernel, uint32_t *pCount, ze_kernel_allocation_exp_properties_t *pAllocationProperties)

Retrieves kernel allocation properties.

• A valid kernel handle must be created with zeKernelCreate.

• Returns array of kernel allocation properties for kernel handle.

• The application may call this function from simultaneous threads.

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

Parameters:

• hKernel – [in] Kernel handle.

• pCount – [in,out] pointer to the number of kernel allocation properties. if count is zero, then the driver shall update the value with the total number of kernel allocation properties available. if count is greater than the number of kernel allocation properties available, then the driver shall update the value with the correct number of kernel allocation properties.

• pAllocationProperties – [in,out][optional][range(0, *pCount)] array of kernel allocation properties. if count is less than the number of kernel allocation properties available, then driver shall only retrieve that number of kernel allocation properties.

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hKernel

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pCount

Kernel - Experimental Enums

ze_scheduling_hint_exp_flags_t

Added in version 1.2

enum ze_scheduling_hint_exp_flag_t

Values:

enumerator ZE_SCHEDULING_HINT_EXP_FLAG_OLDEST_FIRST

Hint that the kernel prefers oldest-first scheduling.

enumerator ZE_SCHEDULING_HINT_EXP_FLAG_ROUND_ROBIN

Hint that the kernel prefers round-robin scheduling.

enumerator ZE_SCHEDULING_HINT_EXP_FLAG_STALL_BASED_ROUND_ROBIN

Hint that the kernel prefers stall-based round-robin scheduling.

enumerator ZE_SCHEDULING_HINT_EXP_FLAG_FORCE_UINT32

Value marking end of ZE_SCHEDULING_HINT_EXP_FLAG_* ENUMs.

Kernel - Experimental Structures

ze_scheduling_hint_exp_desc_t

Added in version 1.2

struct ze_scheduling_hint_exp_desc_t

Kernel scheduling hint descriptor.

• This structure may be passed to zeKernelSchedulingHintExp.

Public Members

ze_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_scheduling_hint_exp_flags_t flags

[in] flags specifying kernel scheduling hints. must be 0 (default) or a valid combination of ze_scheduling_hint_exp_flag_t.

ze_kernel_allocation_exp_properties_t

Added in version 1.14

struct ze_kernel_allocation_exp_properties_t

Kernel allocation properties.

Public Members

ze_structure_type_t stype

[in] type of this structure

void *pNext

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint64_t base

[out] base address of the allocation

size_t size

[out] size of allocation

ze_memory_type_t type

[out] type of allocation

uint32_t argIndex

[out] kernel argument index for current allocation, -1 for driver internal (not kernel argument) allocations