From 66c8acea1bc460d132786e2d8504321df818765a Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Tue, 7 Oct 2025 17:29:54 -0400 Subject: [PATCH] [SYCL][Doc] Add spec to record an event Add a proposed extension specification which allows an application to reuse the same event object in multiple command submissions, rather than creating a new event for each submission. --- .../sycl_ext_oneapi_record_event.asciidoc | 213 ++++++++++++++++++ 1 file changed, 213 insertions(+) create mode 100644 sycl/doc/extensions/proposed/sycl_ext_oneapi_record_event.asciidoc diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_record_event.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_record_event.asciidoc new file mode 100644 index 0000000000000..5b79d3ad4c880 --- /dev/null +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_record_event.asciidoc @@ -0,0 +1,213 @@ += sycl_ext_oneapi_record_event + +:source-highlighter: coderay +:coderay-linenums-mode: table + +// This section needs to be after the document title. +:doctype: book +:toc2: +:toc: left +:encoding: utf-8 +:lang: en +:dpcpp: pass:[DPC++] +:endnote: —{nbsp}end{nbsp}note + +// Set the default source code type in this document to C++, +// for syntax highlighting purposes. This is needed because +// docbook uses c++ and html5 uses cpp. +:language: {basebackend@docbook:c++:cpp} + + +== Notice + +[%hardbreaks] +Copyright (C) 2025 Intel Corporation. All rights reserved. + +Khronos(R) is a registered trademark and SYCL(TM) and SPIR(TM) are trademarks +of The Khronos Group Inc. OpenCL(TM) is a trademark of Apple Inc. used by +permission by Khronos. + + +== Contact + +To report problems with this extension, please open a new issue at: + +https://github.com/intel/llvm/issues + + +== Dependencies + +This extension is written against the SYCL 2020 revision 10 specification. +All references below to the "core SYCL specification" or to section numbers in +the SYCL specification refer to that revision. + +This extension also depends on the following other SYCL extensions: + +* link:../experimental/sycl_ext_oneapi_enqueue_functions.asciidoc[ + sycl_ext_oneapi_enqueue_functions] + + +== Status + +This is a proposed extension specification, intended to gather community +feedback. +Interfaces defined in this specification may not be implemented yet or may be in +a preliminary state. +The specification itself may also change in incompatible ways before it is +finalized. +*Shipping software products should not rely on APIs defined in this +specification.* + + +== Overview + +This extension adds the ability to reuse the same `event` object in multiple +command submissions, rather than creating a new event for each submission. +This pattern may perform better on some implementations because fewer event +objects need to be created and destroyed. +The pattern may also be more familiar to users porting CUDA code to SYCL. + + +== Specification + +=== Feature test macro + +This extension provides a feature-test macro as described in the core SYCL +specification. An implementation supporting this extension must predefine the +macro `SYCL_EXT_ONEAPI_RECORD_EVENT` to one of the values defined in the table +below. Applications can test for the existence of this macro to determine if +the implementation supports this feature, or applications can test the macro's +value to determine which of the extension's features the implementation +supports. + +[%header,cols="1,5"] +|=== +|Value +|Description + +|1 +|The APIs of this experimental extension are not versioned, so the + feature-test macro always has this value. +|=== + +=== New kernel launch property + +This extension adds a new kernel launch property: + +[source,c++] +---- +namespace sycl::ext::oneapi::experimental { + +struct record_event { + record_event(event* evt); (1) +}; +using record_event_key = record_event; + +} // namespace sycl::ext::oneapi::experimental +---- + +This property may be passed as a launch property to the following command +submission functions from +link:../experimental/sycl_ext_oneapi_enqueue_functions.asciidoc[ +sycl_ext_oneapi_enqueue_functions]: + +* The `submit` overload that takes parameters of type `queue` and `Properties`. +* The `single_task` overloads that take parameters of type `queue` and + `Properties`. +* The `parallel_for` overloads that take parameters of type `queue` and + `launch_config`. +* The `nd_launch` overloads that take parameters of type `queue` and + `launch_config`. +* The `memcpy` overload that takes parameters of type `queue` and `Properties`. +* The `copy` overload that takes parameters of type `queue` and `Properties`. +* The `memset` overload that takes parameters of type `queue` and `Properties`. +* The `fill` overload that takes parameters of type `queue` and `Properties`. +* The `prefetch` overload that takes parameters of type `queue` and + `Properties`. +* The `mem_advise` overload that takes parameters of type `queue` and + `Properties`. +* The `barrier` overload that takes parameters of type `queue` and `Properties`. +* The `partial_barrier` overload that takes parameters of type `queue` and + `Properties`. +* The `execute_graph` overload that takes parameters of type `queue` and + `Properties`. + +_Effects (1)_: Constructs a `record_event` property with a pointer to an `event` +object. +When `evt` is not null, the following happens. +The status of the event is disassociated with any previously submitted command, +and its status is reset to `info::event_command_status::submitted`. +For the `submit` function, this happens when the command group function returns +back to `submit`. +The event is then associated with the newly submitted command. +Assuming the event remains associated with this command, the event's status +changes according to the execution status of that command. +When `evt` is null, the property has no effect on the command submission. + +_Remarks:_ + +* If a recorded event is used as a command dependency for some other command + _C2_ (e.g. via `handler::depends_on`), the dependency is captured at the point + when _C2_ is submitted. + The dependency does _not_ change if the event is subsequently overwritten via + `record_event`. + +* If another host thread is blocked in a call to `event::wait` when that same + event is associated with a new command via `record_event`, it is unspecified + whether the call to `event:wait` unblocks. + + +== Example + +[source,c++] +---- +#include +namespace syclex = sycl::ext::oneapi::experimental; + +int main() { + sycl::queue q1; + sycl::queue q2; + sycl::event e; + sycl::range r{GLOBAL}; + + // Launch a command and record an event which tracks its completion. + syclex::launch_config cfg{r, syclex::record_event{&e}}; + syclex::parallel_for(q1, cfg, [=](sycl::item<> it) { /* ... */ }); + + // Launch another command which depends on that event and also + // record completion of this new command using the same event. + syclex::submit(q2, syclex::record_event{&e}, [&](sycl::handler cgh) { + cgh.depends_on(e); + syclex::parallel_for(cgh, r, [=](sycl::item<> it) { /* ... */ }); + }); + + // Wait for both commands to complete. + e.wait(); +} +---- + + +== Implementation notes + +It is expected that the implementation will often be able to reuse the +underlying backend event object when a SYCL event is passed to `record_event`. +However, there will still be cases when the implementation needs to release the +underlying backend event and create a new one. +For example, this will happen when the existing backend event is from a +different backend or from a different context than the command being submitted. +In these cases, we expect that the implementation will release the backend event +and associate the SYCL event with a new backend event. + + +== Issues + +* Is it possible to implement the behavior specified above regarding + `event::wait` and `record_event`? + What if the implementation needs to release the backend event when another + host thread is blocked in a call to `event:wait`? + Can we guarantee that the call to `event::wait` either remains blocked or + becomes unblocked? + (Either is fine.) + Or, is it possible that this will lead to a crash? + If a crash is possible, we need to weaken the specification to say this + condition is UB.