|
| 1 | += sycl_ext_oneapi_queue_priority |
| 2 | + |
| 3 | +:source-highlighter: coderay |
| 4 | +:coderay-linenums-mode: table |
| 5 | + |
| 6 | +// This section needs to be after the document title. |
| 7 | +:doctype: book |
| 8 | +:toc2: |
| 9 | +:toc: left |
| 10 | +:encoding: utf-8 |
| 11 | +:lang: en |
| 12 | +:dpcpp: pass:[DPC++] |
| 13 | + |
| 14 | +// Set the default source code type in this document to C++, |
| 15 | +// for syntax highlighting purposes. This is needed because |
| 16 | +// docbook uses c++ and html5 uses cpp. |
| 17 | +:language: {basebackend@docbook:c++:cpp} |
| 18 | + |
| 19 | + |
| 20 | +== Notice |
| 21 | + |
| 22 | +[%hardbreaks] |
| 23 | +Copyright (C) 2022-2022 Intel Corporation. All rights reserved. |
| 24 | + |
| 25 | +Khronos(R) is a registered trademark and SYCL(TM) and SPIR(TM) are trademarks |
| 26 | +of The Khronos Group Inc. OpenCL(TM) is a trademark of Apple Inc. used by |
| 27 | +permission by Khronos. |
| 28 | + |
| 29 | +== Contact |
| 30 | + |
| 31 | +To report problems with this extension, please open a new issue at: |
| 32 | + |
| 33 | +https://github.com/intel/llvm/issues |
| 34 | + |
| 35 | + |
| 36 | +== Dependencies |
| 37 | + |
| 38 | +This extension is written against the SYCL 2020 revision 6 specification. All |
| 39 | +references below to the "core SYCL specification" or to section numbers in the |
| 40 | +SYCL specification refer to that revision. |
| 41 | + |
| 42 | +== Status |
| 43 | + |
| 44 | +This extension is implemented and fully supported by {dpcpp}. |
| 45 | +[NOTE] |
| 46 | +==== |
| 47 | +Although {dpcpp} supports this extension on all backends, it is currently used |
| 48 | +only on Level Zero. Other backends ignore the properties defined in this specification. |
| 49 | +==== |
| 50 | + |
| 51 | +== Overview |
| 52 | + |
| 53 | +Introduce SYCL queue properties specifying the desired priority of a queue. |
| 54 | +These priorities are a hint and may be ignored if not supported by |
| 55 | +underlying backends. |
| 56 | + |
| 57 | +== Specification |
| 58 | + |
| 59 | +=== Feature test macro |
| 60 | + |
| 61 | +This extension provides a feature-test macro as described in the core SYCL |
| 62 | +specification. An implementation supporting this extension must predefine |
| 63 | +the macro `SYCL_EXT_ONEAPI_QUEUE_PRIORITY` to one of the values defined |
| 64 | +in the table below. Applications can test for the existence of this macro |
| 65 | +to determine if the implementation supports this feature, or applications |
| 66 | +can test the macro's value to determine which of the extension's features |
| 67 | +the implementation supports. |
| 68 | + |
| 69 | +[%header,cols="1,5"] |
| 70 | +|=== |
| 71 | +|Value |
| 72 | +|Description |
| 73 | + |
| 74 | +|1 |
| 75 | +|Initial version of this extension. |
| 76 | +|=== |
| 77 | + |
| 78 | +=== API of the extension |
| 79 | + |
| 80 | +This extension adds support for new properties for SYCL queue constructors |
| 81 | +taking properties list: |
| 82 | + |
| 83 | +```c++ |
| 84 | +namespace sycl::ext::oneapi::property::queue { |
| 85 | + |
| 86 | + class priority_normal { |
| 87 | + public: |
| 88 | + priority_normal() = default; |
| 89 | + }; |
| 90 | + class priority_low { |
| 91 | + public: |
| 92 | + priority_low() = default; |
| 93 | + }; |
| 94 | + class priority_high { |
| 95 | + public: |
| 96 | + priority_high() = default; |
| 97 | + }; |
| 98 | + |
| 99 | +} // namespace |
| 100 | +``` |
| 101 | +The new properties hint the SYCL runtime that the queue gets the specified |
| 102 | +priority for execution if supported by underlying target runtimes. These |
| 103 | +properties are hints and may safely be ignored by an implementation. |
| 104 | + |
| 105 | +It is illegal to specify multiple differrent priority hints for the same queue. |
| 106 | +Doing so causes the `queue` constructor to throw a synchronous `exception` with |
| 107 | +the `errc::invalid` error code. |
0 commit comments