Skip to content

[SYCL][DOC] Add section on backend support and portability to ext template/README #7656

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Dec 13, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions sycl/doc/extensions/README-process.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,30 @@ While an extension is in the "proposed" state, it is perfectly OK to make
further modifications to its specification. There is no need to change the
version of the extension's feature-test macro when this occurs.

When proposing a new extension targeting a particular backend, consider
which other backends may be likely to use similar architecture features
and may be able to support the extension. Some types of devices, such as
GPU accelerators (e.g. devices using `level_zero`, `ext_oneapi_cuda`, and
`ext_oneapi_hip` backends) are often designed to target similar sets of
programming patterns. For example, a common set of applications and
patterns that are targeted by gpu accelerators includes AI algorithms and
data analytics, quantum or classical particle based simulations, and quantum
or classical field based simulations. This is important to consider
early on in order to make sure that the extension design takes account of
the requirements of all supportable backends. If unsure about the
applicability of an extension to a backend, it is recommended to seek advice
from one of the developers responsible for that backend. When an extension
API is not supported on some backends or devices, one option is to treat the
API as an "optional kernel feature" and tie it to a device
aspect (or to one of the architecture enums).
In this case, the application must do one of two things:

- The host code can test the device and only submit the kernel to the
device if it has the required aspect, or
- The device code can use the experimental `if_architecture_is` function to
call the API conditionally based on the device architecture. (This only
works for AOT compilation currently.)


## Implementing an extension

Expand Down
33 changes: 23 additions & 10 deletions sycl/doc/extensions/template.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -96,19 +96,32 @@ This extension is no longer implemented in {dpcpp}. This specification is
being archived only for historical purposes. *The APIs defined in this
specification no longer exist and cannot be used.*

_This is an example of a note which can be added if your extension is
implemented only for certain backends. A note like this is appropriate if the
extension is implemented only on certain devices or backends._

[NOTE]
====
== Backend support status

_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 {dpcpp} 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.
====

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.

== Overview

Expand Down