oneapi-src / oneapi-src/level-zero-spec

Clarification on command list semantics

Open
#323 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
19
Forks
29
PR merge metrics
No merged PRs in 30d

Description

The current spec provides the following flags when creating a command list:

  • ZE_COMMAND_LIST_FLAG_RELAXED_ORDERING: commands in the list may be reordered within certain limits by the driver before executing.
  • ZE_COMMAND_LIST_FLAG_IN_ORDER: commands in the list must be executed in the given order.

Interestingly, while the spec points out that it is not allowed to set both flags on the same list, it does allow to set neither of the flags. I don't think a command list with none of the two flags set is explicitly named anywhere in the spec, so I'll just call it a "default command list" here.

Let's say I'm working with a device that has one compute engine and one copy engine, exposed via one command queue group of type COMPUTE | COPY. So internally, this device is able to execute a copy command in parallel to a compute command.

Let's assume I have the following code (where E is an event):

cmdList.appendMemoryCopy(..., signal=None, wait=[])    // Command A
cmdList.appendLaunchKernel(..., signal=E, wait=[])     // Command B
cmdList.appendLaunchKernel(..., signal=None, wait=[E]) // Command C
cmdList.appendMemoryCopy(..., signal=None, wait=[])    // Command D
cmdQueue.executeCommandLists([cmdList])

Are the following statements true?

  • If cmdList was created with ZE_COMMAND_LIST_FLAG_IN_ORDER:
    • The only allowed execution order is A, B, C, D.
    • Each command must finish execution before the next one starts execution.
  • If cmdList was created with ZE_COMMAND_LIST_FLAG_RELAXED_ORDERING:
    • The only restriction is that B must finish before C starts execution, all other orderings are legal.
    • Legal execution: D, A, B, C.
    • Legal execution: D, B, C, A.
    • Some commands may also execute in parallel but there is no guarantee that they do, e.g., A may execute in parallel to B. And if B takes some time but A is quick is quick to finish, both A and D may execute in parallel to B.
  • If cmdList was created with neither of the flags (a "default command list"):
    • The order in which commands start execution is always A, B, C, D, but some commands may execute in parallel.
    • Legal execution: A executes in parallel to B, then C executes once B finishes, then D executes in parallel to C.
    • Illegal execution: D, A, B, C
    • Illegal execution: B, C, D, A

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the command-list flag definitions and execution-order semantics in the specification, focusing on the cases described for in-order, relaxed-ordering, and neither flag. Done means the specification clearly defines the default command-list behavior and confirms or corrects each ordering and parallel-execution example.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.