============ 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 :ref:`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 :ref:`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 :ref:`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. 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. List of Standard Extensions =========================== - :ref:`"ZE_extension_eu_count" ` - :ref:`"ZE_extension_pci_properties" ` - :ref:`"ZE_extension_srgb" ` - :ref:`"ZE_extension_bfloat16_conversions" ` - :ref:`"ZE_extension_cache_reservation" ` - :ref:`"ZE_extension_device_luid" ` - :ref:`"ZE_extension_device_ip_version" ` - :ref:`"ZE_extension_event_query_kernel_timestamps" ` - :ref:`"ZE_extension_float_atomics" ` - :ref:`"ZE_extension_image_copy" ` - :ref:`"ZE_extension_image_query_alloc_properties" ` - :ref:`"ZE_extension_image_view" ` - :ref:`"ZE_extension_image_view_planar" ` - :ref:`"ZE_extension_kernel_max_group_size_properties" ` - :ref:`"ZE_extension_linkage_inspection" ` - :ref:`"ZE_extension_linkonce_odr" ` - :ref:`"ZE_extension_memory_compression_hints" ` - :ref:`"ZE_extension_memory_free_policies" ` - :ref:`"ZE_extension_device_memory_properties" ` - :ref:`"ZE_extension_raytracing" ` - :ref:`"ZE_extension_subgroups" ` - :ref:`"ZES_extension_engine_activity" ` - :ref:`"ZES_extension_power_limits" ` List of Experimental Extensions =============================== - :ref:`"ZE_experimental_rtas_builder" ` - :ref:`"ZE_experimental_bandwidth_properties" ` - :ref:`"ZE_experimental_event_query_timestamps" ` - :ref:`"ZE_experimental_fabric" ` - :ref:`"ZE_experimental_global_offset" ` - :ref:`"ZE_experimental_image_memory_properties" ` - :ref:`"ZE_experimental_image_view" ` - :ref:`"ZE_experimental_image_view_planar" ` - :ref:`"ZE_experimental_scheduling_hints" ` - :ref:`"ZE_experimental_power_saving_hint" ` - :ref:`"ZE_experimental_module_program" ` - :ref:`"ZE_experimental_relaxed_allocation_limits" ` - :ref:`"ZE_experimental_sub_allocations" ` - :ref:`"ZET_experimental_global_metric_timestamps" ` - :ref:`"ZET_experimental_metric_export_data" ` - :ref:`"ZET_experimental_calculate_multiple_metrics" ` - :ref:`"ZET_experimental_api_tracing" ` - :ref:`"ZES_extension_ras_state" `