Skip to content

Commit 498686c

Browse files
authored
[SYCL][Doc] Simplify queue recorded node definition (#254)
Simplify the definition of a node in the Record & Replay API. Move the wording around sub-graphs to the sub-graph section, and use "command" terminology rather than "kernel" to be more generic. Actions Gordon's feedback from: * Lack of clarity over inclusion of queue shortcut functions intel#5626 (comment) * Say "command" rather than "kernel" intel#5626 (comment)
1 parent 68c5b42 commit 498686c

File tree

1 file changed

+17
-16
lines changed

1 file changed

+17
-16
lines changed

sycl/doc/extensions/proposed/sycl_ext_oneapi_graph.asciidoc

+17-16
Original file line numberDiff line numberDiff line change
@@ -200,8 +200,6 @@ Table {counter: tableNumber}. Values of the `SYCL_EXT_ONEAPI_GRAPH` macro.
200200

201201
=== SYCL Graph Terminology
202202

203-
:explicit-memory-ops: https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#subsec:explicitmemory
204-
205203
Table {counter: tableNumber}. Terminology.
206204
[%header,cols="1,3"]
207205
|===
@@ -231,8 +229,8 @@ Table {counter: tableNumber}. Explicit Graph Definition.
231229

232230
| Node
233231
| In the explicit graph building API nodes are created by the user invoking
234-
methods on a modifiable graph. Each node represents either a command-group
235-
function or an empty operation.
232+
methods on a modifiable graph passing a command-group function (CGF). Each node
233+
represents either a command-group or an empty operation.
236234

237235
| Edge
238236
| In the explicit graph building API edges are primarily defined by the user
@@ -258,17 +256,14 @@ Table {counter: tableNumber}. Recorded Graph Definition.
258256
| Concept | Description
259257

260258
| Node
261-
| A node in a queue recorded graph represents a command group submission to the
262-
device associated with the queue begin recorded. Each submission encompasses
263-
either one or both of a.) some data movement, b.) a single asynchronous kernel
264-
launch. Nodes cannot define forward edges, only backwards. That is, kernels can
265-
only create dependencies on command-groups that have already been submitted.
266-
This means that transparently a node can depend on a previously recorded graph
267-
(sub-graph), which works by creating edges to the individual nodes in the old
268-
graph. Explicit memory operations without kernels, such as a memory copy, are
269-
still classed as nodes under this definition, as the
270-
{explicit-memory-ops}[SYCL 2020 specification states] that these can be seen as
271-
specialized kernels executing on the device.
259+
| A node in a queue recorded graph represents a command-group submission to the
260+
device associated with the queue being recorded. Nodes are constructed from
261+
the command-group functions (CGF) passed to `queue::submit()`, or from the queue
262+
shortcut equivalents for the defined handler command types. Each submission
263+
encompasses either one or both of a.) some data movement, b.) a single
264+
asynchronous command launch. Nodes cannot define forward edges, only backwards.
265+
That is, nodes can only create dependencies on command-groups that have already
266+
been submitted.
272267

273268
| Edge
274269
| An edge in a queue recorded graph is expressed through command group
@@ -287,7 +282,13 @@ buffers.
287282

288283
A node in a graph can take the form of a nested sub-graph. This occurs when
289284
a command-group submission that invokes `handler::ext_oneapi_graph()` with an
290-
executable graph object is added to the graph as a node.
285+
executable graph object is added to the graph as a node. The child graph node is
286+
scheduled in the parent graph as-if edges are created to connect the root nodes
287+
of the child graph with the dependent nodes of the parent graph.
288+
289+
Adding an executable graph as a sub-graph does not affect its existing node
290+
dependencies, such that it could be submitted in future without any side
291+
effects of prior uses as a sub-graph.
291292

292293
=== API Modifications
293294

0 commit comments

Comments
 (0)