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

Added a new section in the extension template and simple recommendations
for considering cross backend support when adding new oneapi extensions.

Signed-off-by: JackAKirk <[email protected]>
Co-authored-by: JackAKirk <[email protected]>
Co-authored-by: Greg Lueck <[email protected]>

Author: 3 people

sycl/doc/extensions/README-process.md

@@ -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
 

sycl/doc/extensions/template.asciidoc

@@ -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