Copyright © 2025 Intel Corporation. All rights reserved.
Khronos® is a registered trademark and SYCL™ and SPIR™ are trademarks of The Khronos Group Inc. OpenCL™ is a trademark of Apple Inc. used by permission by Khronos.
To report problems with this extension, please open a new issue at:
This extension is written against the SYCL 2020 revision 9 specification. All references below to the "core SYCL specification" or to section numbers in the SYCL specification refer to that revision.
If your extension depends on other SYCL extensions, add a paragraph and bulleted list like this:
This extension also depends on the following other SYCL extensions:
Choose one of the following according to the status of your extension. For a "proposed" extension:
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.
Use this if the extension becomes "supported":
This extension is implemented and fully supported by DPC++.
Use this if the extension is a proposed new version of an existing extension:
This is a proposed update to an existing extension. 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. See here for the existing extension, which is implemented.
Use this if the extension becomes "experimental":
This is an experimental extension specification, intended to provide early access to features and gather community feedback. Interfaces defined in this specification are implemented in DPC++, but they are not finalized and may change incompatibly in future versions of DPC++ without prior notice. Shipping software products should not rely on APIs defined in this specification.
Use this if the extension becomes "deprecated":
This extension has been deprecated. Although it is still supported in DPC++, we expect that the interfaces defined in this specification will be removed in an upcoming DPC++ release. Shipping software products should stop using APIs defined in this specification and use an alternative instead.
Use this if the extension becomes "removed":
This extension is no longer implemented in DPC++. This specification is being archived only for historical purposes. The APIs defined in this specification no longer exist and cannot be used.
Sometimes an extension can be used only on certain backends. Your extension document should include this section when this is the case.
Our preference is to tie the extension to a device aspect when it is available only on certain backends because it results in a clear error if the application mistakenly tries to use it on an unsupported backend. When this is the case, include a paragraph like this:
The APIs in this extension may be used only on a device that has
aspect::ext_oneapi_foo. The application must check that the device has
this aspect before submitting a kernel using any of the APIs in this
extension. If the application fails to do this, the implementation throws
a synchronous exception with the errc::kernel_not_supported error code
when the kernel is submitted to the queue.
Occasionally, an extension is limited to certain backends and there is no related device aspect. When this is the case, include a paragraph like:
This extension is currently implemented in DPC++ only for GPU devices and only when using the Level Zero backend. Attempting to use this extension in kernels that run on other devices or backends may result in undefined behavior. Be aware that the compiler is not able to issue a diagnostic to warn you if this happens.
Provide a brief overview of the extension here and explain the motivation if appropriate. This is also a good place to show an example usage, but there is no need to exhaustively show all aspects of your extension. Those details should be explained in the sections that follow. This section is just an overview to introduce your readers to your extension.
It is also appropriate to give an indication of who the target audience is for the extension. For example, if the extension is intended only for ninja programmers, we might say something like:
The properties described in this extension are advanced features that most applications should not need to use. In most cases, applications get the best performance without using these properties.
Occasionally, we might add an extension as a stopgap measure for a limited audience. When this happens, it’s best to discourage general usage with a statement like:
This extension exists to solve a specific problem, and a general solution is still being evaluated. It is not recommended for general usage.
Note that text should be wrapped at 80 columns as shown in this template. Extensions use AsciiDoc markup language (like this template). If you need help with AsciiDoc syntax, see the manual.
GitHub understands most AsciiDoc syntax, so files with the .asciidoc
extension are rendered nicely into HTML. Occasionally, you will find an
AsciiDoc feature that GitHub does not understand, though, so you should check
that GitHub renders your extension document nicely before merging it. If you
find a feature that GitHub does not understand, do not use it. We expect
users to read these specifications directly in the GitHub UI, so make sure that
your specification is nicely formatted when viewed this way.
All extensions should provide a feature-test macro, so that applications
can use #ifdef to protect code that uses your extension. Use this text
for all extensions:
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_MYEXTENSION 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.
And follow the text with a table like this unless the extension is "experimental". Note that your table may have more than one row if it has multiple versions.
| Value | Description |
|---|---|
1 |
Initial version of this extension. |
If your extension is "experimental", use this table instead:
| Value | Description |
|---|---|
1 |
The APIs of this experimental extension are not versioned, so the feature-test macro always has this value. |
Your extension specification will certainly have more sections which describe the APIs of your extension. Define these sections as you see fit.
As a general rule, do not describe how you will change the core SYCL specification. For example, there is no need to say something like "Add the following paragraph to section 4.6.7 of the core SYCL specification …" Instead, just describe the semantics and APIs of the extension itself. We will figure out later how to change the core SYCL specification if the extension is adopted.
There may be times when an extension adds a new member function to an existing SYCL class or a new enumerator to an existing SYCL enumeration. In cases like these, say something like:
This extension adds the following new member function to the SYCL
queueclass:class queue { void ext_oneapi_myfunction(); };
Avoid unnecessary duplication of core SYCL APIs. For example, there is no
need to list the existing member functions in queue if your extension adds a
new member function. Duplication like this can be troublesome if something in
the core SYCL specification changes later.
This non-normative section provides information about one possible implementation of this extension. It is not part of the specification of the extension’s API.
This section is not normally needed, but occasionally a "proposed" extension will contains some notes about the intended implementation. If so, add this section, and include the text in the first paragraph above indicating that the section is non-normative. Follow that paragraph with whatever implementation notes you think are necessary. Usually, this section will be removed by the time the extension is implemented, and a more detailed DPC++ design document will be written instead.