From ed7cb4b0700e908fc1fd905a830f3f750023e4cd Mon Sep 17 00:00:00 2001
From: jbrodman <brodman@gmail.com>
Date: Tue, 20 Sep 2022 09:19:58 -0400
Subject: [PATCH] [SYCL][DOC] Extension to add hints to stop batching and start
 executing (#6465)

Signed-off-by: James Brodman <james.brodman@intel.com>
Co-authored-by: Greg Lueck <gregory.m.lueck@intel.com>
Co-authored-by: John Pennycook <john.pennycook@intel.com>
---
 .../proposed/sycl_ext_oneapi_prod.asciidoc    | 114 ++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 sycl/doc/extensions/proposed/sycl_ext_oneapi_prod.asciidoc

diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_prod.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_prod.asciidoc
new file mode 100644
index 0000000000000..f5670a6fab698
--- /dev/null
+++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_prod.asciidoc
@@ -0,0 +1,114 @@
+= sycl_ext_oneapi_prod
+
+: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++]
+
+// 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) 2022-2022 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 5 specification.  All
+references below to the "core SYCL specification" or to section numbers in the
+SYCL specification refer to that revision.
+
+== 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 a mechanism to signal that it is desirable for a SYCL queue
+to begin executing any previously submitted commands once their dependencies
+have been satisfied.
+
+This can be a useful performance hint if a SYCL runtime or backend runtime
+batches several commands before passing them to a device for execution.
+
+== 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_PROD` 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
+|Initial version of this extension.
+|===
+
+=== New member function
+
+This extension adds the following new member function to the SYCL `queue`
+class:
+
+```
+class queue {
+  void ext_oneapi_prod();
+};
+```
+
+A call to `ext_oneapi_prod` provides a hint to the SYCL runtime that it
+should start executing any previously submitted commands once their
+prerequisites have been satisfied. Calls to `ext_oneapi_prod` are
+non-blocking. Calling `ext_oneapi_prod` does not guarantee that
+previously submitted commands will eventually begin executing, nor that any
+previously submitted commands will execute concurrently with the host thread.
+
+[NOTE]
+====
+Since commands submitted to a SYCL queue are not required to execute
+immediately, SYCL devices and backends may buffer commands until a
+blocking call is encountered (e.g. `queue::wait`) or until some
+implementation-specific threshold is met. `ext_oneapi_prod` can be used
+in such cases to override default behavior and encourage earlier execution.
+====
+
+[NOTE]
+====
+Although `ext_oneapi_prod` is a performance hint, its impact upon application
+performance will be highly dependent upon the combination of device, backend
+and application characteristics. In some cases, it may even degrade performance
+(e.g. by interfering with batching or fusion optimizations).
+====