diff --git a/sycl/doc/extensions/proposed/sycl_ext_oneapi_queue_priority.asciidoc b/sycl/doc/extensions/proposed/sycl_ext_oneapi_queue_priority.asciidoc new file mode 100644 index 0000000000000..25e7974e9482b --- /dev/null +++ b/sycl/doc/extensions/proposed/sycl_ext_oneapi_queue_priority.asciidoc @@ -0,0 +1,119 @@ += sycl_ext_oneapi_queue_priority + +: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-2023 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 6 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.* + +== Specification + +This extension defines an additional queue property that permit a backend, +when supported, to create command queues with different levels of priority. +Priorities are hints from the programmer that certain command submissions +to a device may execute before others of lesser priority. + +=== 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_QUEUE_PRIORITY` 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. +|=== + +=== API Additions + + +This extension defines the following new property that may be passed to the +constructor of the `queue` class: + +[%header,cols="1,5"] +|=== +|Property +|Description + +| `sycl::ext::oneapi::property::queue::priority` +| +|=== + +[%header,cols="1,5"] +|=== +|Property Constructor +|Description + +| `sycl::ext::oneapi::property::queue::priority(int priority=0)` +| Specifies that the queue should be constructed with the specified `priority`. +Commands executed by this queue may take priority over commands with lower priority +on this queue's device. The default priority has value `0`. If the user specifies +`priority` outside the range returned by `sycl::ext::oneapi::queue::priority_range`, +`priority` will be clamped down or up to the least or greatest priority in the range. + +|=== + +This extension also defines the following new query for the `queue` class: + +[%header,cols="1,5"] +|=== +|Property +|Description + +| `sycl::ext::oneapi::info::queue::priority_range` +| Returns a `std::array` that represents the `{leastPriority,greatestPriority}` +for this queue. Lower numbers imply greater priorities. The default priority has value `0`. +Specifying priorities outside of this range when creating a queue will result in the specified +priority being clamped down or up to the least priority or greatest priority, respectively. + +|=== \ No newline at end of file