From 488916bcffccc66a1430566a762d94e460f8442a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?F=C3=A1bio=20Mestre?= Date: Thu, 4 Jul 2024 13:42:17 +0100 Subject: [PATCH 1/3] [SYCL][Graph] Add implicit queue recording mechanism --- .../experimental/sycl_ext_oneapi_graph.asciidoc | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/sycl/doc/extensions/experimental/sycl_ext_oneapi_graph.asciidoc b/sycl/doc/extensions/experimental/sycl_ext_oneapi_graph.asciidoc index a8cab9bdb1be6..264b753491f8c 100644 --- a/sycl/doc/extensions/experimental/sycl_ext_oneapi_graph.asciidoc +++ b/sycl/doc/extensions/experimental/sycl_ext_oneapi_graph.asciidoc @@ -1442,7 +1442,7 @@ The alternative `queue_state::recording` state is used for graph construction. Instead of being scheduled for execution, command-groups submitted to the queue are recorded to a graph object as new nodes for each submission. After recording has finished and the queue returns to the executing state, the recorded commands are -not then executed, they are transparent to any following queue operations. The state +not executed, they are transparent to any following queue operations. The state of a queue can be queried with `queue::ext_oneapi_get_state()`. .Queue State Diagram @@ -1453,7 +1453,18 @@ graph LR Recording -->|End Recording| Executing .... -==== Queue Properties +==== Implicit Queue Recording + +Submitting a command-group to a queue can implicitly change its state +to `queue_state::recording`. This will occur when the command-group depends on +an event that has been returned by a queue in the recording state. + +A queue whose state has been set to `queue_state::recording` using this +mechanism, will behave as if it had been passed as an argument to +`command_graph::begin_recording()`. In particular, its state will not +change again until `command_graph::end_recording()` is called. + +==== Queue Properties; :queue-properties: https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html#sec:queue-properties From 528b14c5c1f5f91aa5138e7247bbccd6e93efb7b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?F=C3=A1bio=20Mestre?= Date: Thu, 4 Jul 2024 16:22:53 +0100 Subject: [PATCH 2/3] Add example and address review comments --- .../sycl_ext_oneapi_graph.asciidoc | 29 ++++++++++++++++--- 1 file changed, 25 insertions(+), 4 deletions(-) diff --git a/sycl/doc/extensions/experimental/sycl_ext_oneapi_graph.asciidoc b/sycl/doc/extensions/experimental/sycl_ext_oneapi_graph.asciidoc index 264b753491f8c..29ad1234b05d3 100644 --- a/sycl/doc/extensions/experimental/sycl_ext_oneapi_graph.asciidoc +++ b/sycl/doc/extensions/experimental/sycl_ext_oneapi_graph.asciidoc @@ -1453,17 +1453,38 @@ graph LR Recording -->|End Recording| Executing .... -==== Implicit Queue Recording +==== Transitive Queue Recording -Submitting a command-group to a queue can implicitly change its state -to `queue_state::recording`. This will occur when the command-group depends on -an event that has been returned by a queue in the recording state. +Submitting a command-group to a queue in the executable state can implicitly +change its state to `queue_state::recording`. This will occur when the +command-group depends on an event that has been returned by a queue in the +recording state. The change of state happens before the command-group is +submitted (i.e. a new graph node will be created for that command-group). A queue whose state has been set to `queue_state::recording` using this mechanism, will behave as if it had been passed as an argument to `command_graph::begin_recording()`. In particular, its state will not change again until `command_graph::end_recording()` is called. +===== Example + +[source,c++] +---- +// q1 state is set to recording. +graph.begin_recording(q1); + +// Node is added to the graph by submitting to a recording queue. +auto e1 = q1.single_task(...); + +// Since there is a dependency on e1 which was created by a queue being +// recorded, q2 immediately enters record mode, and a new node is created +// with an edge between e1 and e2. +auto e2 = q2.single_task(e1, ...); + +// Ends recording on q1 and q2. +graph.end_recording(); +---- + ==== Queue Properties; :queue-properties: https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html#sec:queue-properties From 4f126ed529c86f12f96dbad3da61d3675b48c79f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?F=C3=A1bio=20Mestre?= Date: Thu, 4 Jul 2024 16:39:22 +0100 Subject: [PATCH 3/3] Fix typo --- sycl/doc/extensions/experimental/sycl_ext_oneapi_graph.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sycl/doc/extensions/experimental/sycl_ext_oneapi_graph.asciidoc b/sycl/doc/extensions/experimental/sycl_ext_oneapi_graph.asciidoc index 29ad1234b05d3..c71eb00b3834c 100644 --- a/sycl/doc/extensions/experimental/sycl_ext_oneapi_graph.asciidoc +++ b/sycl/doc/extensions/experimental/sycl_ext_oneapi_graph.asciidoc @@ -1485,7 +1485,7 @@ auto e2 = q2.single_task(e1, ...); graph.end_recording(); ---- -==== Queue Properties; +==== Queue Properties :queue-properties: https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html#sec:queue-properties