[SYCL][DOC] Queue priority extension document

sycl/doc/extensions/proposed/sycl_ext_oneapi_queue_priority.asciidoc

@@ -0,0 +1,131 @@
+= 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++]
+: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) 2026 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 11 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 defines an additional queue property that permits 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.
+
+== 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_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.
+|===
+
+=== New queue property
+
+This extension defines the following new property that may be passed to
+the constructor of the `queue` class:
+
+'''
+
+[source,c++]
+----
+namespace sycl::ext::oneapi::property::queue {
+
+class priority {
+public:
+  priority(int priority_value);
+};
+
+} // namespace sycl::ext::oneapi::property::queue
+----
+
+_Effects:_ Specifies that the queue should be constructed with the specified
+`priority_value`. Commands executed by this queue may take priority over
+commands in queues with lower priority on this device. If the user specifies
+`priority_value` outside the range returned by
+`sycl::ext::oneapi::info::device::priority_range` for the device associated
+with the queue, `priority_value` will be clamped down or up to the lowest or
+highest priority in the range. Lower numbers imply greater priorities.
+If the property is not set for a queue, the default priority for that queue is
+assumed to be 0.
+
+=== New device information descriptor
+
+'''
+
+[source, c++]
+----
+namespace sycl::ext::oneapi::info::device {
+
+struct priority_range {
+  using return_type = std::array<int, 2>;
+};
+
+} // namespace sycl::ext::oneapi::info::device
+----
+
+_Remarks:_ Template parameter to `device::get_info`.
+
+_Returns:_ `std::array<int,2>` that represents the `{lowestPriority,
+highestPriority}` for this device. The first element is the numerical value
+corresponding to the lowest (least urgent) queue priority supported by the
+device, and the second element is the numerical value corresponding to the
+highest (most urgent) queue priority supported by the device. Lower numerical
+values imply greater priorities.