Command List - Experimental

Contents

Command List - Experimental#

oneAPI Level Zero Specification - Version 1.18.31

Command List - Experimental Functions#

zeCommandListCreateCloneExp#

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListCreateCloneExp(ze_command_list_handle_t hCommandList, ze_command_list_handle_t *phClonedCommandList)#

Creates a command list as the clone of another command list.

  • Deprecated:

    since 1.17

Parameters:

  • hCommandList – [in] handle to source command list (the command list to clone)

  • phClonedCommandList – [out] pointer to handle of the cloned command list

Returns:

zeCommandListImmediateAppendCommandListsExp#

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListImmediateAppendCommandListsExp(ze_command_list_handle_t hCommandListImmediate, uint32_t numCommandLists, ze_command_list_handle_t *phCommandLists, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)#

Appends command lists to dispatch from an immediate command list.

Parameters:

  • hCommandListImmediate – [in] handle of the immediate command list

  • numCommandLists – [in] number of command lists

  • phCommandLists – [in][range(0, numCommandLists)] handles of command lists

  • hSignalEvent – [in][optional] handle of the event to signal on completion

    • if not null, this event is signaled after the completion of all appended command lists

  • numWaitEvents – [in][optional] number of events to wait on before executing appended command lists; must be 0 if nullptr == phWaitEvents

  • phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before executing appended command lists.

    • if not null, all wait events must be satisfied prior to the start of any appended command list(s)

Returns:

zeCommandListGetNextCommandIdExp#

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListGetNextCommandIdExp(ze_command_list_handle_t hCommandList, const ze_mutable_command_id_exp_desc_t *desc, uint64_t *pCommandId)#

Returns a unique command identifier for the next command to be appended to a command list.

  • This function may only be called for a mutable command list.

  • This function may not be called on a closed command list.

  • This function may be called from simultaneous threads with the same command list handle.

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

Parameters:

  • hCommandList – [in] handle of the command list

  • desc – [in] pointer to mutable command identifier descriptor

  • pCommandId – [out] pointer to mutable command identifier to be written

Returns:

zeCommandListUpdateMutableCommandsExp#

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListUpdateMutableCommandsExp(ze_command_list_handle_t hCommandList, const ze_mutable_commands_exp_desc_t *desc)#

Updates mutable commands.

  • This function may only be called for a mutable command list.

  • The application must synchronize mutable command list execution before calling this function.

  • The application must close a mutable command list after completing all updates.

  • This function must not be called from simultaneous threads with the same command list handle.

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

Parameters:

  • hCommandList – [in] handle of the command list

  • desc – [in] pointer to mutable commands descriptor; multiple descriptors may be chained via pNext member

Returns:

zeCommandListUpdateMutableCommandSignalEventExp#

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListUpdateMutableCommandSignalEventExp(ze_command_list_handle_t hCommandList, uint64_t commandId, ze_event_handle_t hSignalEvent)#

Updates the signal event for a mutable command in a mutable command list.

  • This function may only be called for a mutable command list.

  • The type, scope and flags of the signal event must match those of the source command.

  • The application must synchronize mutable command list execution before calling this function.

  • The application must close a mutable command list after completing all updates.

  • This function must not be called from simultaneous threads with the same command list handle.

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

Parameters:

  • hCommandList – [in] handle of the command list

  • commandId – [in] command identifier

  • hSignalEvent – [in][optional] handle of the event to signal on completion

Returns:

zeCommandListUpdateMutableCommandWaitEventsExp#

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListUpdateMutableCommandWaitEventsExp(ze_command_list_handle_t hCommandList, uint64_t commandId, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)#

Updates the wait events for a mutable command in a mutable command list.

  • This function may only be called for a mutable command list.

  • The number of wait events must match that of the source command.

  • The type, scope and flags of the wait events must match those of the source command.

  • Passing nullptr as the wait events will update the command to not wait on any events prior to dispatch.

  • Passing nullptr as an event on event wait list will remove event dependency from this wait list slot.

  • The application must synchronize mutable command list execution before calling this function.

  • The application must close a mutable command list after completing all updates.

  • This function must not be called from simultaneous threads with the same command list handle.

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

Parameters:

  • hCommandList – [in] handle of the command list

  • commandId – [in] command identifier

  • numWaitEvents – [in][optional] the number of wait events

  • phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

Returns:

zeCommandListGetNextCommandIdWithKernelsExp#

Added in version 1.10

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListGetNextCommandIdWithKernelsExp(ze_command_list_handle_t hCommandList, const ze_mutable_command_id_exp_desc_t *desc, uint32_t numKernels, ze_kernel_handle_t *phKernels, uint64_t *pCommandId)#

Returns a unique command identifier for the next command to be appended to a command list. Provides possible kernel handles for kernel mutation when ZE_MUTABLE_COMMAND_EXP_FLAG_KERNEL_INSTRUCTION flag is present.

  • This function may only be called for a mutable command list.

  • This function may not be called on a closed command list.

  • This function may be called from simultaneous threads with the same command list handle.

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

Parameters:

  • hCommandList – [in] handle of the command list

  • desc – [in][out] pointer to mutable command identifier descriptor

  • numKernels – [in][optional] number of entries on phKernels list

  • phKernels – [in][optional][range(0, numKernels)] list of kernels that user can switch between using zeCommandListUpdateMutableCommandKernelsExp call

  • pCommandId – [out] pointer to mutable command identifier to be written

Returns:

zeCommandListUpdateMutableCommandKernelsExp#

Added in version 1.10

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListUpdateMutableCommandKernelsExp(ze_command_list_handle_t hCommandList, uint32_t numKernels, uint64_t *pCommandId, ze_kernel_handle_t *phKernels)#

Updates the kernel for a mutable command in a mutable command list.

  • This function may only be called for a mutable command list.

  • The kernel handle must be from the provided list for given command id.

  • The application must synchronize mutable command list execution before calling this function.

  • The application must close a mutable command list after completing all updates.

  • This function must not be called from simultaneous threads with the same command list handle.

  • This function must be called before updating kernel arguments and dispatch parameters, when kernel is mutated.

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

Parameters:

  • hCommandList – [in] handle of the command list

  • numKernels – [in] the number of kernels to update

  • pCommandId – [in][range(0, numKernels)] command identifier

  • phKernels – [in][range(0, numKernels)] handle of the kernel for a command identifier to switch to

Returns:

zeCommandListIsMutableExp#

Added in version 1.17

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListIsMutableExp(ze_command_list_handle_t hCommandList, ze_bool_t *pIsMutable)#

Query whether a command list was created with the mutable command list extension.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hCommandList – [in] handle of the command list

  • pIsMutable – [out] pointer bool determining whether command list was created with mutable extension

Returns:

Command List - Experimental Enums#

ze_mutable_command_exp_flags_t#

Added in version 1.9

enum ze_mutable_command_exp_flag_t#

Values:

enumerator ZE_MUTABLE_COMMAND_EXP_FLAG_KERNEL_ARGUMENTS#

kernel arguments

enumerator ZE_MUTABLE_COMMAND_EXP_FLAG_GROUP_COUNT#

kernel group count

enumerator ZE_MUTABLE_COMMAND_EXP_FLAG_GROUP_SIZE#

kernel group size

enumerator ZE_MUTABLE_COMMAND_EXP_FLAG_GLOBAL_OFFSET#

kernel global offset

enumerator ZE_MUTABLE_COMMAND_EXP_FLAG_SIGNAL_EVENT#

command signal event

enumerator ZE_MUTABLE_COMMAND_EXP_FLAG_WAIT_EVENTS#

command wait events

enumerator ZE_MUTABLE_COMMAND_EXP_FLAG_KERNEL_INSTRUCTION#

command kernel (since v1.10)

enumerator ZE_MUTABLE_COMMAND_EXP_FLAG_GRAPH_ARGUMENTS#

graph arguments (since v1.10)

enumerator ZE_MUTABLE_COMMAND_EXP_FLAG_FORCE_UINT32#

Value marking end of ZE_MUTABLE_COMMAND_EXP_FLAG_* ENUMs.

ze_mutable_command_list_exp_flags_t#

Added in version 1.9

enum ze_mutable_command_list_exp_flag_t#

Values:

enumerator ZE_MUTABLE_COMMAND_LIST_EXP_FLAG_RESERVED#

reserved

enumerator ZE_MUTABLE_COMMAND_LIST_EXP_FLAG_FORCE_UINT32#

Value marking end of ZE_MUTABLE_COMMAND_LIST_EXP_FLAG_* ENUMs.

Command List - Experimental Structures#

ze_mutable_command_id_exp_desc_t#

Added in version 1.9

struct ze_mutable_command_id_exp_desc_t#

Mutable command identifier descriptor.

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_mutable_command_exp_flags_t flags#

[in] mutable command flags.

ze_mutable_command_list_exp_properties_t#

Added in version 1.9

struct ze_mutable_command_list_exp_properties_t#

Mutable command list 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).

ze_mutable_command_list_exp_flags_t mutableCommandListFlags#

[out] mutable command list flags

ze_mutable_command_exp_flags_t mutableCommandFlags#

[out] mutable command flags

ze_mutable_command_list_exp_desc_t#

Added in version 1.9

struct ze_mutable_command_list_exp_desc_t#

Mutable command list descriptor.

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_mutable_command_list_exp_flags_t flags#

[in] mutable command list flags.

ze_mutable_commands_exp_desc_t#

Added in version 1.9

struct ze_mutable_commands_exp_desc_t#

Mutable commands descriptor.

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).

uint32_t flags#

[in] must be 0, this field is reserved for future use

ze_mutable_kernel_argument_exp_desc_t#

Added in version 1.9

struct ze_mutable_kernel_argument_exp_desc_t#

Mutable kernel argument descriptor.

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).

uint64_t commandId#

[in] command identifier

uint32_t argIndex#

[in] kernel argument index

size_t argSize#

[in] kernel argument size

const void *pArgValue#

[in] pointer to kernel argument value

ze_mutable_group_count_exp_desc_t#

Added in version 1.9

struct ze_mutable_group_count_exp_desc_t#

Mutable kernel group count descriptor.

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).

uint64_t commandId#

[in] command identifier

const ze_group_count_t *pGroupCount#

[in] pointer to group count

ze_mutable_group_size_exp_desc_t#

Added in version 1.9

struct ze_mutable_group_size_exp_desc_t#

Mutable kernel group size descriptor.

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).

uint64_t commandId#

[in] command identifier

uint32_t groupSizeX#

[in] group size for X dimension to use for the kernel

uint32_t groupSizeY#

[in] group size for Y dimension to use for the kernel

uint32_t groupSizeZ#

[in] group size for Z dimension to use for the kernel

ze_mutable_global_offset_exp_desc_t#

Added in version 1.9

struct ze_mutable_global_offset_exp_desc_t#

Mutable kernel global offset descriptor.

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).

uint64_t commandId#

[in] command identifier

uint32_t offsetX#

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

uint32_t offsetY#

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

uint32_t offsetZ#

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

ze_mutable_graph_argument_exp_desc_t#

Added in version 1.10

struct ze_mutable_graph_argument_exp_desc_t#

Mutable graph argument descriptor.

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).

uint64_t commandId#

[in] command identifier

uint32_t argIndex#

[in] graph argument index

const void *pArgValue#

[in] pointer to graph argument value