diff --git a/sycl/doc/extensions/README-process.md b/sycl/doc/extensions/README-process.md new file mode 100644 index 0000000000000..476b09cd6300a --- /dev/null +++ b/sycl/doc/extensions/README-process.md @@ -0,0 +1,181 @@ +# Lifetime of an Extension + +This document describes the process for creating and maintaining SYCL extension +documents over their lifetime. + + +## Creating a new extension + +Start by making a copy of the [template][1] extension specification document, +and follow the instructions in that document. Your extension should also +follow the rules in [chapter 6][2] of the SYCL specification, including the +"Guidelines for portable extensions". These rules require you to choose a +``. For DPC++, we use the string "oneapi" unless the extension +is very specific to Intel hardware in which case we use the string "intel". +The template uses the string "oneapi", so you must change occurrences of that +string if your extension is specific to Intel hardware. + +[1]: +[2]: + +Some sections in the template are optional. Remove these sections if they are +not needed. You should also remove any of the explanatory text (generally in +italics). + +Each extension must have a name. The template uses +"sycl\_ext\_oneapi\_myextension", but you must change the "myextension" to +something appropriate. Use lower case, and separate words with underbars. +Each extension also has a feature-test macro, which is the same as the +extension's name, except it uses all upper case. Finally, the name of the +specification file should match the name of the extension, for example +"sycl\_ext\_oneapi\_myextension.asciidoc". + +Usually new extensions are first created in the "proposed" state, so the +document should be added to that directory. However, it is also possible to +add a new extension at the same time as its implementation, in which case the +specification should be added to either the "supported" or "experimental" +directories. + +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. + + +## Implementing an extension + +Often, an extension is implemented sometime after it is proposed. When this +happens, the PR that implements the extension should also move the +specification to either the "supported" or "experimental" directory, as +appropriate. It is common to make small change to the specification when it is +implemented, so the PR that implements the extension may also make +modifications to the specification document. + +Be sure to change the text in the "Status" section when the extension is +implemented. See the [template][1] for the proper text. + +Sometimes an extension is implemented with multiple PRs. When this happens, +the last PR that implements the extension should also move the specification +document. We want the specification document to reflect the features that are +implemented in DPC++, so a specification should not be moved to "supported" or +"experimental" before the final PR that implements it. + +Ideally, all APIs in an extension should be implemented by the time we announce +support. If this is not possible, something must be done to ensure that the +specification is an accurate description of what is implemented. Following are +some techniques to accomplish this. + +### Split the specification into versions + +This is the preferred technique if the first release of an extension implements +some APIs but not others. In this case, the extension document should be +copied to the "supported" (or "experimental") directory, but the description of +the unimplemented APIs should be removed from this copy. Thus, the document in +that directory is an accurate description of the implementation. + +The original version of the specification in the "proposed" folder should +remain. In addition, a new "version" row should be added to the table that +describes the feature-test macro, and all the unimplemented APIs become part of +"version 2" of the specification. These APIs can be implemented later, +following the normal process of [adding a new version to an existing +extension][3]. + +[3]: <#adding-a-new-version-to-an-existing-extension> + +### Add NOTEs describing what is not implemented + +Sometimes all of the APIs in an extension are implemented, but they are not yet +implemented for all devices or backends. When this happens, we prefer to add +non-normative "notes" to the extension specification indicating what is not +yet implemented. The placement of these notes depends on the nature of the +unimplemented thing. For example, if the entire extension is unimplemented on +a certain backend, a note should be added in the "Status" section of the +document, as demonstrated in the [template][1]. If there are restrictions with +certain APIs, a note should be added near the description of each such API. + + +## Adding a new version to an existing extension + +It is common to add new APIs to an extension after it is first released. When +this happens, the new APIs should be protected by a new version of the +extension's feature-test macro. This allows an application to test the value +of the macro to know whether the implementation supports the API. + +Assuming the extension document is currently in the "supported" directory, make +a copy of that document in the "proposed" directory. Update the "Status" +section as shown in the [template][1], and add a new "version" row to the table +that describes the feature-test macro with a short summary of the new APIs +enabled in that version. The description of each new API should contain a +statement saying which version adds the API. For example, + +> This API is available starting in version 2 of this specification. + +Avoid unnecessary reformatting of the extension after it is copied. It should +be possible to see the new APIs that are proposed in the new version by using a +command like: + +``` +$ git diff {supported,proposed}/sycl_ext_oneapi_myextension.asciidoc +``` + +When the new version of the extension is implemented, the "proposed" version of +the specification should be moved back to the "supported" directory, +overwriting the previous version. + +Note that a new version of a supported extension should never remove any +functionality from the previous version. We expect existing code that uses the +old version to still work with the new version. + + +## Deprecating an extension + +Occasionally, we may decide to deprecate a supported extension. For example, +this might happen if an extension is adopted into a new version of the core +SYCL specification. When this happens, the specification is moved from the +"supported" directory to the "deprecated" directory, and the "Status" section +is changed as shown in the [template][1]. A signpost file is also added to +the "supported" directory with the same name as the original file and content +that looks like: + +``` +This extension has been deprecated, but the specification is still available +link:../deprecated/sycl_ext_oneapi_myextension.asciidoc[here]. +``` + +The purpose of the signpost file is to ensure that external links to the +extension are not broken, while still making it obvious that the extension is +now deprecated. + +Note that a deprecated extension is still supported, so the implementation is +not removed. + +We usually do not deprecate experimental extensions since there is no guarantee +that these extension remain supported from one DPC++ release to the next. +Instead, these extensions can be removed without a deprecation period. + + +## Removing support for an extension + +Eventually, we typically remove an extension some time after it is deprecated. +When this happens, we move the specification file to the "removed" directory +and update the "Status" section as shown in the [template][1]. We also remove +the signpost file. This typically happens in the same PR that removes the +implementation of the extension. + + +## Experimental extensions + +The process of creating and implementing an "experimental" extension has mostly +been described already, but there are some additional things to keep in mind. +Even though an extension may be experimental, we still want the specification +to accurately describe the API. Usually, the extension document is the main +user-facing description of the API, so it must be accurate in order for +customers to use the extension. Therefore, even an experimental extension +specification must contain [NOTEs][4] describing any APIs that are not yet +implemented. + +[4]: <#add-notes-describing-what-is-not-implemented> + +Since experimental extensions have no guaranteed compatibility from one DPC++ +release to another, we typically do not bother to add versions to the +feature-test macro. This is still allowed, of course, but it is also OK to +add, remove, or modify APIs without changing the version. diff --git a/sycl/doc/extensions/template.asciidoc b/sycl/doc/extensions/template.asciidoc new file mode 100644 index 0000000000000..96a067c412582 --- /dev/null +++ b/sycl/doc/extensions/template.asciidoc @@ -0,0 +1,226 @@ += sycl_ext_oneapi_myextension + +: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++] + +// 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) 2022-2022 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 4 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: + +* link:../supported/sycl_ext_oneapi_myotherextension.asciidoc[ + sycl_ext_oneapi_myotherextension] + + +== Status + +_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 {dpcpp}. + +_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 +link:../supported/sycl_ext_oneapi_myextension.asciidoc[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 {dpcpp}, but they are not finalized and may +change incompatibly in future versions of {dpcpp} 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 {dpcpp}, +we expect that the interfaces defined in this specification will be removed in +an upcoming {dpcpp} 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 {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] +==== +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. +==== + + +== Overview + +_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._ + +_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 +https://docs.asciidoctor.org/asciidoc/latest[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._ + + +== Specification + +=== Feature test macro + +_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._ + +[%header,cols="1,5"] +|=== +|Value +|Description + +|1 +|Initial version of this extension. +|=== + +_If your extension is "experimental", use this table instead:_ + +[%header,cols="1,5"] +|=== +|Value +|Description + +|1 +|The APIs of this experimental extension are not versioned, so the + feature-test macro always has this value. +|=== + +=== More sections at your discretion + +_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 `queue` +> class: +> +> ``` +> 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._ + + +== Implementation notes + +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 {dpcpp} design document +will be written instead._ + + +== Issues + +_Sometimes there will be unresolved issues in a "proposed" extension. If this +is the case, add an "Issues" section towards the end of the document, and list +each issue._