Command List - Deprecated

Contents

Command List - Deprecated#

oneAPI Level Zero Specification - Version 1.20.41

Command List - Deprecated Functions#

zeCommandListCreateCloneExp#

Added in version 1.9

Deprecated since 1.17. Mutable command lists replace command list cloning. Use ZE_extension_mutable_command_list instead.

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.

  • The source command list must be created with the ZE_COMMAND_LIST_FLAG_EXP_CLONEABLE flag.

  • The source command list must be closed prior to cloning.

  • The source command list may be cloned while it is running on the device.

  • The cloned command list inherits all properties of the source command list.

  • The cloned command list must be destroyed prior to the source command list.

  • The application must only use the command list for the device, or its sub-devices, which was provided during creation.

  • The application may call this function from simultaneous threads.

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

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

Deprecated since 1.16. Use zeCommandListImmediateAppendCommandListsWithParameters instead.

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.

  • The application must call this function only with command lists created with zeCommandListCreateImmediate.

  • The command lists passed to this function in the phCommandLists argument must be regular command lists (i.e. not immediate command lists).

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

  • The command lists are submitted to the device in the order they are received by the driver, whether from multiple calls (on the same or different threads) or a single call with multiple command lists.

  • The application must ensure the command lists are accessible by the device on which the immediate command list was created.

  • The application must ensure the device is not currently referencing the appended command list since the implementation is allowed to modify the contents of the command list for submission.

  • The application must only append command lists created with an identical command queue group ordinal to the immediate command list.

  • The application must ensure the immediate command list, command lists and events were created on the same context.

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

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)] handles of 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

Deprecated since 1.20. Use zeCommandListGetNextCommandIdExt instead.

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

Deprecated since 1.20. Use zeCommandListUpdateMutableCommandsExt instead.

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

Deprecated since 1.20. Use zeCommandListUpdateMutableCommandSignalEventExt instead.

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

Deprecated since 1.20. Use zeCommandListUpdateMutableCommandWaitEventsExt instead.

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

Deprecated since 1.20. Use zeCommandListGetNextCommandIdWithKernelsExt instead.

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

Deprecated since 1.20. Use zeCommandListUpdateMutableCommandKernelsExt instead.

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

Deprecated since 1.20. Use zeCommandListIsMutableExt instead.

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 - Deprecated Enums#

ze_mutable_command_exp_flags_t#

Added in version 1.9

Deprecated since 1.20. Use ze_mutable_command_ext_flags_t instead.

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

Deprecated since 1.20. Use ze_mutable_command_list_ext_flags_t instead.

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 - Deprecated Structures#

ze_mutable_command_id_exp_desc_t#

Added in version 1.9

Deprecated since 1.20. Use ze_mutable_command_id_ext_desc_t instead.

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

Deprecated since 1.20. Use ze_mutable_command_list_ext_properties_t instead.

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

Deprecated since 1.20. Use ze_mutable_command_list_ext_desc_t instead.

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

Deprecated since 1.20. Use ze_mutable_commands_ext_desc_t instead.

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

Deprecated since 1.20. Use ze_mutable_kernel_argument_ext_desc_t instead.

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

Deprecated since 1.20. Use ze_mutable_group_count_ext_desc_t instead.

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

Deprecated since 1.20. Use ze_mutable_group_size_ext_desc_t instead.

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

Deprecated since 1.20. Use ze_mutable_global_offset_ext_desc_t instead.

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

Deprecated since 1.20. Use ze_mutable_graph_argument_ext_desc_t instead.

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