[UR] Implement extension mechanism #458
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,117 @@ | ||
| <% | ||
| import re | ||
| from templates import helper as th | ||
| %><% | ||
| OneApi=tags['$OneApi'] | ||
| x=tags['$x'] | ||
| X=x.upper() | ||
| %> | ||
| ============== | ||
| Extensions | ||
| ============== | ||
|
|
||
| Objective | ||
| ========= | ||
|
|
||
| Extensions allow for additional functionality to be added to the Unified Runtime specification | ||
| without affecting the core specification. Extensions may in future be promoted to the core specification | ||
| in a later version of Unified Runtime, when agreed upon by the Working Group. All extensions are | ||
| optional and are not required to be implemented by any particular adapter, but are expected to | ||
| be widely available and possibly be required in a future version of the specification. Adapters | ||
| must report which extensions are supported through the ${X}_PLATFORM_INFO_EXTENSIONS platform info query. | ||
| Each extension may also impose additional restrictions on when it can be used - i.e. a platform | ||
| or device query. | ||
|
|
||
| There are two types of extensions defined by this specification: | ||
|
|
||
| 1. **Standard** - extension will be included into the current and all future version of the specification. | ||
| 2. **Experimental** - extensions require additional experimentation and development, before becoming a standard extension. | ||
| Applications should not rely on experimental extensions in production. | ||
|
|
||
| Requirements | ||
| ============ | ||
|
|
||
| - Extensions must use globally unique names for macros, enums, structures and functions | ||
| - Extensions must have globally unique extension names reported from ${X}_PLATFORM_INFO_EXTENSIONS platform info query | ||
| - All extensions must be defined in this specification | ||
veselypeta marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - Extensions must not break backwards compatibility of the core APIs | ||
|
There was a problem hiding this comment. Does this also include semantic breaks as well as interface breaks in the core APIs, i.e. does this forbid an extension from altering the behavior of an existing API?
Contributor
Author
There was a problem hiding this comment. I think an extension can alter the behavour of an existing API. For example you might want to chain an additional structure to the input or use extension specific enums, but default usage should remain the same.
Contributor
There was a problem hiding this comment. Hmm, I'm not sure I'm so confortable with extensions that change semantics because we have no way to opt-out with this architecture. If we were able to enable extensions, like Vulkan, maybe I'd be more conformtable with that. |
||
| - Standard extension versions must be backwards compatible with prior versions | ||
|
Contributor
Author
There was a problem hiding this comment. I copied this from L0 extension scheme, but perhaps we could use semantic versioning with extensions with major/minor versions? There was a problem hiding this comment. Does this mean that experimental extensions are permitted to break backwards compatibility?
Contributor
Author
There was a problem hiding this comment. Yes I think that makes sense. Experimental extensions should have no ABI or backwards compatibility requirements. |
||
|
|
||
|
|
||
| Naming Convention | ||
| ----------------- | ||
|
|
||
| The following naming conventions must be followed for **standard** extensions: | ||
| ## --validate=off | ||
| - The extension name must begin with `${x}_ext` | ||
| - All extension functions must be postfixed with `Ext` | ||
| - All macros must use all caps `${X}_<NAME>_EXT` convention | ||
| - All structures, enumerations and other types must follow `${x}_<name>_ext_t` snake case convention | ||
| - All enumerator values must use all caps `${X}_ENUM_EXT_ETOR_NAME` convention | ||
| - All handle types must end with `ext_handle_t` | ||
| - All descriptor structures must end with `ext_desc_t` | ||
| - All property structures must end with `ext_properties_t` | ||
| - All flag enumerations must end with `ext_flags_t` | ||
| ## --validate=on | ||
|
|
||
| The following naming conventions must be followed for **experimental** extensions: | ||
|
|
||
| ## --validate=off | ||
| - The extension name must begin with `${x}_exp` | ||
| - Experimental extensions may be added and removed from the driver at any time. | ||
| - Experimental extensions are not guaranteed to be forward- or backward-compatible between versions. | ||
| - Experimental extensions are not guaranteed to be supported in production driver releases; and may appear and disappear from release to release. | ||
| - All extension functions must be postfixed with `Exp` | ||
| - All macros must use all caps `${X}_<NAME>_EXP` convention | ||
| - All structures, enumerations and other types must follow `${x}_<name>_exp_t` snake case convention | ||
| - All enumerator values must use all caps `${X}_ENUM_EXP_ETOR_NAME` convention | ||
| - All handle types must end with `exp_handle_t` | ||
| - All descriptor structures must end with `exp_desc_t` | ||
| - All property structures must end with `exp_properties_t` | ||
| - All flag enumerations must end with `exp_flags_t` | ||
| ## --validate=on | ||
|
|
||
| Extending Enumerations | ||
| ---------------------- | ||
|
|
||
| Any existing enumeration may be extended by adding new enumerators. Enumerators must use the extensions naming | ||
| convention and values should be assigned to avoid future compatibility issues. | ||
|
|
||
|
|
||
| Extending Structures | ||
| -------------------- | ||
|
|
||
| Any structure derived from ``${x}_base_desc_t`` or ``${x}_base_properties_t`` can be extended using a structure chain | ||
| by adding a pointer to the extended structure in `pNext` member variable. No other method of extending structures is allowed. | ||
|
|
||
| A structure chain can contain more than one extension structure, in any order. Therefore, extensions should not | ||
| be dependent on their order relative to other extensions and the implementation must be order agnostic. In addition, | ||
| the implementation will ignore extended structures that it does not support. | ||
|
|
||
| The extension must document the specific structures and functions that may be extended using the structure chain. | ||
|
|
||
veselypeta marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| Adding an extension | ||
| =================== | ||
|
|
||
| * Extend the specification with the functions, enumerations, macros, and structures required by the extension, ensuring that | ||
| all additions fully comply with the naming and ABI requirements detailed above. | ||
|
|
||
| * Document the extension in `EXT_<ext-name>.rst` file based on the `EXT_Template.rst`, ensuring it is added to the list of | ||
| extensions below. | ||
|
|
||
| * The extension will only be accepted if all conditions are met and its addition is agreed upon by the Working Group. | ||
|
There was a problem hiding this comment. Does this refer to an extension becoming a standard extension? |
||
|
|
||
|
|
||
| List of Standard Extensions | ||
|
There was a problem hiding this comment. Just a thought, maybe these lists should also track the implementation status of the extensions, so whether they are implemented, and then which version of UR supports which version of the extension, particularly for the experimental extensions which may change, so high-level languages know what they can use when updating the UR interface. |
||
| =========================== | ||
| %for name in meta['macro']: | ||
| %if name.endswith('EXT_NAME'): | ||
|
|
||
| - :ref:`${th.subt(namesapce, tags, meta['macro'][name]['values'][0])} <${th.subt(namesapce, tags, name)}>` | ||
|
|
||
| %endif | ||
| %endfor | ||
|
|
||
| List of Experimental Extensions | ||
| =============================== | ||
| // TODO - list all experimental extensions | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| <% | ||
| import re | ||
| from templates import helper as th | ||
| %><% | ||
| OneApi=tags['$OneApi'] | ||
| x=tags['$x'] | ||
| X=x.upper() | ||
| %> | ||
| :orphan: | ||
|
|
||
| .. _${X}_OPAQUE_DATA_EXT_NAME: | ||
|
|
||
| ===================== | ||
| Opaque Data Extension | ||
| ===================== | ||
|
|
||
| API | ||
| --- | ||
|
|
||
| * Macros | ||
|
|
||
| * ${X}_OPAQUE_DATA_EXT_NAME | ||
|
|
||
|
|
||
| * Functions | ||
|
|
||
| * ${x}PlatformGetOpaqueDataExt | ||
|
|
||
|
|
||
| Opaque Data Extension | ||
| ~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| Some devices whose device code is compiled by the host compiler (e.g. CPU emulators) may use | ||
| this extension to access some device code functionality implemented in/behind the adapter. | ||
|
|
||
| Dependencies | ||
| ~~~~~~~~~~~~ | ||
|
|
||
| This extension has no dependencies and relies of v0.6 of the Unified Runtime specification. | ||
|
|
||
| Extension Changelog | ||
| ~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| v0.1 | ||
| ==== | ||
| Document changes ... | ||
|
|
||
| v0.2 | ||
| ==== | ||
| Document changes ... | ||
|
|
||
|
|
||
| Contributors | ||
| ~~~~~~~~~~~~ | ||
|
|
||
| * Contributor A, Company A, [email protected] | ||
| * Contributor B, Company B, [email protected] | ||
| * ... |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Will there be implementation or coverage requirements for when an extension should move from experimental to standard?