Command Visit Extension

Command Visit Extension#

Introduced in Level Zero version 1.20

API#

Command Visit#

This extension introduces APIs for visiting commands recorded in a command list or graph and applying custom behavior to each visited command.

Semantics and Behavior#

  1. zeCommandListVisitExt traverses command list commands in recording order. The command list must be created with ZE_COMMAND_LIST_FLAG_ENABLE_COMMAND_VISIT.

  2. zeGraphVisitExt traverses graph commands in recording order. Graphs do not require an explicit opt-in flag.

  3. Concrete visitors are provided by chaining one or more ze_concrete_visitor_ext_desc_t structures to the pNext chain of ze_command_visit_ext_desc_t, one per API function. Each fname must be unique within the chain. The implementation executes the concrete callback whose fname matches the current command API.

  4. If no concrete callback is provided for a command, the implementation applies defaultOp from ze_command_visit_ext_desc_t.

  5. For each command without a concrete callback, the implementation invokes, in order: beforeDefaultOpClb (if not null), defaultOp, afterDefaultOpClb (if not null). For commands with a concrete callback, only the concrete callback is invoked.

  6. beforeDefaultOpClb and afterDefaultOpClb may inspect or modify synchronization parameters (wait events and signal event) used by the default operation, e.g. to remap event lists without modifying the command itself.

Concrete visitor callbacks have the same signature as the visited API, with userData appended as the last parameter and the ZE_VISITOR_CCONV calling convention. For example, a concrete visitor for zeCommandListAppendLaunchKernel has the following prototype:

ze_result_t ZE_VISITOR_CCONV myLaunchKernelVisitor(
    ze_command_list_handle_t hCommandList,
    ze_kernel_handle_t hKernel,
    const ze_group_count_t* pLaunchFuncArgs,
    ze_event_handle_t hSignalEvent,
    uint32_t numWaitEvents,
    ze_event_handle_t* phWaitEvents,
    void* userData);
// Create a source command list with command visit enabled
ze_command_list_desc_t srcDesc = {
    ZE_STRUCTURE_TYPE_COMMAND_LIST_DESC,                // stype
    nullptr,                                              // pNext
    0,                                                    // commandQueueGroupOrdinal
    ZE_COMMAND_LIST_FLAG_ENABLE_COMMAND_VISIT           // flags
};
ze_command_list_handle_t hCommandList;
zeCommandListCreate(hContext, hDevice, &srcDesc, &hCommandList);

// ... record commands into hCommandList ...

// Create a target command list that will receive re-appended commands
ze_command_list_desc_t dstDesc = {
    ZE_STRUCTURE_TYPE_COMMAND_LIST_DESC,                // stype
    nullptr,                                              // pNext
    0,                                                    // commandQueueGroupOrdinal
    0                                                     // flags
};
ze_command_list_handle_t hTargetCommandList;
zeCommandListCreate(hContext, hDevice, &dstDesc, &hTargetCommandList);

// Register a concrete visitor for kernel launches
ze_concrete_visitor_ext_desc_t launchVisitor = {
    ZE_STRUCTURE_TYPE_CONCRETE_VISITOR_EXT_DESC,       // stype
    nullptr,                                              // pNext
    "zeCommandListAppendLaunchKernel",                 // fname
    (void*)myLaunchKernelVisitor                          // callback
};

// Configure default command visit behavior
ze_command_visit_ext_desc_t visitDesc = {
    ZE_STRUCTURE_TYPE_COMMAND_VISIT_EXT_DESC,            // stype
    &launchVisitor,                                       // pNext
    userData,                                             // userData
    hTargetCommandList,                                   // hReappendTargetCommandList
    beforeDefaultCallback,                                // beforeDefaultOpClb
    ZE_COMMAND_VISIT_EXT_DEFAULT_OP_REAPPEND,           // defaultOp
    afterDefaultCallback                                  // afterDefaultOpClb
};

// Visit a command list
zeCommandListVisitExt(hCommandList, &visitDesc);

// Visit a graph
zeGraphVisitExt(hGraph, &visitDesc);