Extensions

Objective

Features which are device- or vendor-specific can be exposed as extensions. The list of extensions supported by the driver implementation can be queried using zeDriverGetExtensionProperties.

There are two types of extensions defined by this specification:

  1. Standard - extensions ratified for inclusion into the current and all future versions of the specification.

  2. Experimental - extensions require additional experimentation and feedback from application vendors before ratification, therefore applications should not rely on experimental extensions in production.

In addition, an implementation may choose to provide additional non-standard extensions via zeDriverGetExtensionFunctionAddress. It is the responsibility of the implementation to ensure these extensions do not conflict or interfere with any features or extensions of the core APIs. These extensions are not documented as part of this specification.

Requirements

  • Extensions must use globally unique names for macros, enums, structures and functions

  • Extensions must have globally unique extension names reported from zeDriverGetExtensionProperties

  • All extensions must be defined in this specification

  • Extensions must not break backwards compatibility of the core APIs

  • Standard extension versions must be backwards compatible with prior versions

Naming Convention

The following naming conventions must be followed for standard extensions:

  • All extension functions must be postfixed with Ext

  • All macros must use all caps ZE_NAME_EXT convention

  • All structures, enumerations and other types must follow ze_name_ext_t snake case convention

  • All enumerator values must use all caps ZE_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

The following naming conventions must be followed for experimental extensions:

  • 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 ZE_NAME_EXP convention

  • All structures, enumerations and other types must follow ze_name_exp_t snake case convention

  • All enumerator values must use all caps ZE_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

Extending Enumerations

Any existing enumeration may be extended by adding new etors. Etors must still use extension naming convention and values should be assigned to avoid future compatibility issues.

Extending Structures

Any structure derived from :ref:`ze-base-desc-t` or :ref:`ze-base-properties-t` can be extended using structure chains. While it is possible to use other methods, this is the required method for extending existing structures.

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.

The extension must document the specific structures and functions that may be extended using the structure chain.

List of Standard Extensions

  • “ZE_extension_float_atomics”

  • “ZE_extension_raytracing”

List of Experimental Extensions

  • “ZE_experimental_global_offset”

  • “ZE_experimental_module_program”

  • “ZE_experimental_relaxed_allocation_limits”

  • “ZET_experimental_api_tracing”