[SYCL][DOC] Add specification for discard queue events extension (#4922)

See extension document for SYCL describing discard queue events behavior.

sycl/doc/extensions/DiscardQueueEvents/SYCL_EXT_ONEAPI_DISCARD_QUEUE_EVENTS.asciidoc

@@ -0,0 +1,212 @@
+= SYCL_EXT_ONEAPI_DISCARD_QUEUE_EVENTS
+: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
+
+:blank: pass:[ +]
+
+// 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}
+
+// This is necessary for asciidoc, but not for asciidoctor
+:cpp: C++
+
+== Introduction
+
+IMPORTANT: This specification is a draft.
+
+NOTE: 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.
+
+This document describes an extension that introduces a `discard_events` property for
+SYCL queues. This property enables developers to inform a SYCL implementation that
+the events returned from queue operations will not be used.
+
+== Notice
+
+Copyright (c) 2021 Intel Corporation. All rights reserved.
+
+== Status
+
+Working Draft
+
+This is a preview extension specification, intended to provide early access to
+a feature for review and community feedback. When the feature matures, this
+specification may be released as a formal extension.
+
+Because the interfaces defined by this specification are not final and are
+subject to change they are not intended to be used by shipping software
+products.
+
+== Version
+
+Revision: 1
+
+== Contributors
+
+Alexander Flegontov, Intel  +
+Greg Lueck, Intel  +
+John Pennycook, Intel +
+Vlad Romanov, Intel
+
+== Dependencies
+
+This extension is written against the SYCL 2020 specification, Revision 4.
+
+== Feature Test Macro
+
+This extension provides a feature-test macro as described in the core SYCL
+specification section 6.3.3 "Feature test macros".  Therefore, an
+implementation supporting this extension must predefine the macro
+`SYCL_EXT_ONEAPI_DISCARD_QUEUE_EVENTS` 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 APIs the implementation supports.
+
+[%header,cols="1,5"]
+|===
+|Value |Description
+|1     |Initial extension version.  Base features are supported.
+|===
+
+== Overview
+
+This extension adds `ext::oneapi::property::queue::discard_events` property for `sycl::queue`,
+by using this property the application informs a SYCL implementation that it will not use the event
+returned by any of the `queue` member functions. (i.e submit, parallel_for, copy, memset and others.)
+When the application creates a queue with this property,
+the implementation may be able to optimize some operations on the `queue`.
+The `discard_events` property is incompatible with `enable_profiling`.
+Attempts to construct a `queue` with both properties raises `errc::invalid`.
+
+Below is a usage example:
+[source,c++]
+----
+  sycl::property_list props{ext::oneapi::property::queue::discard_events{},
+                            property::queue::in_order{}};
+  sycl::queue Queue( props );
+
+  // some USM preparations ..
+
+  sycl::event e1, e2, e3;
+
+  // returning "invalid" events from each submission function:
+  e1 = Queue.parallel_for(NDRange, [=](nd_item<1> item){ do_smth1(); });
+
+  e2 = Queue.single_task([=](){ do_smth2(); });
+
+  e3 = Queue.submit([&](handler &CGH) { CGH.parallel_for(NDRange, [=](nd_item<1> item){ do_smth3(); }); });
+
+  Queue.wait();
+----
+
+In the example above, the application doesn't use sycl events: `e1`, `e2`, `e3`
+and is waiting for the end of work by `queue::wait()`.
+When the queue is created with the `discard_events` property,
+the returned events will be _invalid_ events, which are `sycl::event` objects that have limited capability.
+See the description of behavior for this event below for details.
+
+Here, only those member functions for the _invalid_ event are described that have behavior different from the default event behavior:
+[source,c++]
+----
+// must throw an exception with the errc::invalid error code.
+std::vector<event> get_wait_list();
+
+// must throw an exception with the errc::invalid error code.
+void wait();
+
+// if invalid event is passed into the function, must throw an exception with the errc::invalid error code.
+static void wait(const std::vector<event> &eventList);
+
+// must throw an exception with the errc::invalid error code.
+void wait_and_throw();
+
+// if invalid event is passed into the function, must throw an exception with the errc::invalid error code.
+static void wait_and_throw(const std::vector<event> &eventList);
+
+// must return info::event_command_status::ext_oneapi_unknown
+get_info<info::event::command_execution_status>() const;
+----
+
+The behavior when _invalid_ event is passed into handler API:
+[source,c++]
+----
+// must throw an exception with the errc::invalid error code.
+handler::depends_on(event Event)
+
+// must throw an exception with the errc::invalid error code.
+handler::depends_on(const std::vector<event> &Events)
+----
+
+A new enumerator value is also added to the `info::event_command_status` enumeration,
+which is returned by `get_info<info::event::command_execution_status>()` as described above:
+[source,c++]
+----
+namespace sycl {
+namespace info {
+
+enum class event_command_status : int {
+  // ...
+  ext_oneapi_unknown
+};
+
+} // namespace info
+} // namespace sycl
+----
+
+== Optimization behavior for DPC++
+
+This non-normative section describes the conditions when the DPC++ implementation provides an optimization benefit* for the `discard_events` property.
+
+ - The queue must be constructed with the `in_order` property.
+ - A kernel submitted to the queue must not use the https://github.com/intel/llvm/blob/sycl/sycl/doc/extensions/Assert/SYCL_ONEAPI_ASSERT.asciidoc[fallback assert feature].
+ - A queue operation submitted to the queue must not use streams or buffer / image accessors. However, local accessors do not inhibit optimization.
+ - Any queue operations using Level Zero backend temporarily work without optimization.
+
+*The benefit is that a low-level event is not created from backend, thereby saving time.
+
+See the behavior details for each condition below:
+
+=== Using out-of-order queue
+
+No optimization if a queue is created with the `discard_events` property and
+the property list does not include `in_order` property.
+
+=== Using fallback assert feature
+
+No optimization if the application calls the `assert` macro from a command that is submitted to the queue unless
+the device has native support for assertions (as specified by `aspect::ext_oneapi_native_assert`).
+
+=== Using streams or buffer / image accessors (excluding local accessors)
+
+No optimization if a queue operation that uses stream objects or buffer / image accessors is submitted to a queue created with
+the `discard_events` property. But using local accessors does not affect optimization.
+
+=== Using Level Zero backend
+
+Since Level Zero Plugin support is required to be able to not create a low-level event,
+any queue operations using the Level Zero backend temporarily work without optimization.
+
+
+== Issues
+
+None.
+
+== Revision History
+
+[cols="5,15,15,70"]
+[grid="rows"]
+[options="header"]
+|========================================
+|Rev|Date|Author|Changes
+|1|2021-11-09|Alexander Flegontov |*Initial public working draft*
+|========================================

sycl/doc/extensions/README.md

@@ -48,6 +48,7 @@ DPC++ extensions status:
 | [SYCL_INTEL_bf16_conversion](Bf16Conversion/SYCL_INTEL_bf16_conversion.asciidoc)                                            | Partially supported (Level Zero: GPU)     | Currently available only on Xe HP GPU. ext_intel_bf16_conversion aspect is not supported. |
 | [Property List](PropertyList/SYCL_EXT_ONEAPI_property_list.asciidoc)                                                        | Proposal                                  | |
 | [KernelProperties](KernelProperties/KernelProperties.asciidoc)                                                              | Proposal                                  | |
+| [DiscardQueueEvents](DiscardQueueEvents/SYCL_EXT_ONEAPI_DISCARD_QUEUE_EVENTS.asciidoc) | Proposal | |
 
 Legend: