[UR] Implement extension mechanism

Author: Petr Vesely

include/ur.py

@@ -323,6 +323,21 @@ def __str__(self):
         return str(ur_platform_backend_v(self.value))
 
 
+###############################################################################
+## @brief Extension name maximum length.
+UR_MAX_EXTENSION_NAME_LENGTH = 256
+
+###############################################################################
+## @brief Extension properties.
+class ur_extension_properties_t(Structure):
+    _fields_ = [
+        ("stype", ur_structure_type_t),                                 ## [in] type of this structure, must be
+                                                                        ## ::UR_STRUCTURE_TYPE_EXTENSION_PROPERTIES
+        ("pNext", c_void_p),                                            ## [in,out][optional] pointer to extension-specific structure
+        ("name", c_char * UR_MAX_EXTENSION_NAME_LENGTH),                ## [in] null-terminated extension name.
+        ("version", c_ulong)                                            ## [in] version of the extension using ::UR_MAKE_VERSION.
+    ]
+
 ###############################################################################
 ## @brief Target identification strings for
 ##        ::ur_device_binary_t.pDeviceTargetSpec 
@@ -1752,6 +1767,13 @@ def __str__(self):
 else:
     _urPlatformGetBackendOption_t = CFUNCTYPE( ur_result_t, ur_platform_handle_t, c_char_p, POINTER(c_char_p) )
 
+###############################################################################
+## @brief Function-pointer for urPlatformGetExtensionProperties
+if __use_win_types:
+    _urPlatformGetExtensionProperties_t = WINFUNCTYPE( ur_result_t, ur_platform_handle_t, c_ulong, POINTER(ur_extension_properties_t), POINTER(c_ulong) )
+else:
+    _urPlatformGetExtensionProperties_t = CFUNCTYPE( ur_result_t, ur_platform_handle_t, c_ulong, POINTER(ur_extension_properties_t), POINTER(c_ulong) )
+
 
 ###############################################################################
 ## @brief Table of Platform functions pointers
@@ -1762,7 +1784,8 @@ class ur_platform_dditable_t(Structure):
         ("pfnGetNativeHandle", c_void_p),                               ## _urPlatformGetNativeHandle_t
         ("pfnCreateWithNativeHandle", c_void_p),                        ## _urPlatformCreateWithNativeHandle_t
         ("pfnGetApiVersion", c_void_p),                                 ## _urPlatformGetApiVersion_t
-        ("pfnGetBackendOption", c_void_p)                               ## _urPlatformGetBackendOption_t
+        ("pfnGetBackendOption", c_void_p),                              ## _urPlatformGetBackendOption_t
+        ("pfnGetExtensionProperties", c_void_p)                         ## _urPlatformGetExtensionProperties_t
     ]
 
 ###############################################################################
@@ -2761,6 +2784,7 @@ def __init__(self, version : ur_api_version_t):
         self.urPlatformCreateWithNativeHandle = _urPlatformCreateWithNativeHandle_t(self.__dditable.Platform.pfnCreateWithNativeHandle)
         self.urPlatformGetApiVersion = _urPlatformGetApiVersion_t(self.__dditable.Platform.pfnGetApiVersion)
         self.urPlatformGetBackendOption = _urPlatformGetBackendOption_t(self.__dditable.Platform.pfnGetBackendOption)
+        self.urPlatformGetExtensionProperties = _urPlatformGetExtensionProperties_t(self.__dditable.Platform.pfnGetExtensionProperties)
 
         # call driver to get function pointers
         Context = ur_context_dditable_t()

include/ur_api.h

@@ -606,6 +606,41 @@ typedef enum ur_platform_backend_t {
 
 } ur_platform_backend_t;
 
+///////////////////////////////////////////////////////////////////////////////
+#ifndef UR_MAX_EXTENSION_NAME_LENGTH
+/// @brief Extension name maximum length.
+#define UR_MAX_EXTENSION_NAME_LENGTH 256
+#endif // UR_MAX_EXTENSION_NAME_LENGTH
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Extension properties.
+typedef struct ur_extension_properties_t {
+    ur_structure_type_t stype;               ///< [in] type of this structure, must be
+                                             ///< ::UR_STRUCTURE_TYPE_EXTENSION_PROPERTIES
+    void *pNext;                             ///< [in,out][optional] pointer to extension-specific structure
+    char name[UR_MAX_EXTENSION_NAME_LENGTH]; ///< [in] null-terminated extension name.
+    uint32_t version;                        ///< [in] version of the extension using ::UR_MAKE_VERSION.
+
+} ur_extension_properties_t;
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Retrieve the set of supported extensions.
+///
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_UNINITIALIZED
+///     - ::UR_RESULT_ERROR_DEVICE_LOST
+///     - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
+///         + `NULL == hPlatform`
+UR_APIEXPORT ur_result_t UR_APICALL
+urPlatformGetExtensionProperties(
+    ur_platform_handle_t hPlatform,                  ///< [in] handle to the platform.
+    uint32_t count,                                  ///< [in] number of extension properties to fetch.
+    ur_extension_properties_t *pExtensionProperties, ///< [out][optional] array of supported extension.
+    uint32_t *pCountRet                              ///< [out][optional] will be updated with the total count of supported
+                                                     ///< extensions.
+);
+
 #if !defined(__GNUC__)
 #pragma endregion
 #endif
@@ -5671,6 +5706,17 @@ typedef struct ur_platform_get_backend_option_params_t {
     const char ***pppPlatformOption;
 } ur_platform_get_backend_option_params_t;
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urPlatformGetExtensionProperties
+/// @details Each entry is a pointer to the parameter passed to the function;
+///     allowing the callback the ability to modify the parameter's value
+typedef struct ur_platform_get_extension_properties_params_t {
+    ur_platform_handle_t *phPlatform;
+    uint32_t *pcount;
+    ur_extension_properties_t **ppExtensionProperties;
+    uint32_t **ppCountRet;
+} ur_platform_get_extension_properties_params_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function parameters for urContextCreate
 /// @details Each entry is a pointer to the parameter passed to the function;

include/ur_ddi.h

@@ -60,6 +60,14 @@ typedef ur_result_t(UR_APICALL *ur_pfnPlatformGetBackendOption_t)(
     const char *,
     const char **);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urPlatformGetExtensionProperties
+typedef ur_result_t(UR_APICALL *ur_pfnPlatformGetExtensionProperties_t)(
+    ur_platform_handle_t,
+    uint32_t,
+    ur_extension_properties_t *,
+    uint32_t *);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Table of Platform functions pointers
 typedef struct ur_platform_dditable_t {
@@ -69,6 +77,7 @@ typedef struct ur_platform_dditable_t {
     ur_pfnPlatformCreateWithNativeHandle_t pfnCreateWithNativeHandle;
     ur_pfnPlatformGetApiVersion_t pfnGetApiVersion;
     ur_pfnPlatformGetBackendOption_t pfnGetBackendOption;
+    ur_pfnPlatformGetExtensionProperties_t pfnGetExtensionProperties;
 } ur_platform_dditable_t;
 
 ///////////////////////////////////////////////////////////////////////////////

scripts/core/EXT.rst

@@ -0,0 +1,91 @@
+<%
+    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}PlatformGetExtensionProperties query.
+Each extensions 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}PlatformGetExtensionProperties
+- 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:
+## --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 structure chains. 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.
+
+
+// TODO - list all extensions

scripts/core/platform.yml

@@ -242,3 +242,40 @@ etors:
     - name: HIP
       value: "4"
       desc: "The backend is HIP"
+--- #--------------------------------------------------------------------------
+type: macro
+desc: "Extension name maximum length."
+name: $X_MAX_EXTENSION_NAME_LENGTH
+value: "256"
+--- #--------------------------------------------------------------------------
+type: struct
+desc: "Extension properties."
+name: $x_extension_properties_t
+base: $x_base_properties_t
+class: $xPlatform
+members:
+    - type: char
+      name: name[$X_MAX_EXTENSION_NAME_LENGTH]
+      desc: "[in] null-terminated extension name."
+    - type: uint32_t
+      name: version
+      desc: "[in] version of the extension using $X_MAKE_VERSION."
+--- #--------------------------------------------------------------------------
+type: function
+desc: "Retrieve the set of supported extensions."
+class: $xPlatform
+name: GetExtensionProperties
+decl: static
+params:
+    - type: $x_platform_handle_t
+      name: hPlatform
+      desc: "[in] handle to the platform."
+    - type: uint32_t
+      name: count
+      desc: "[in] number of extension properties to fetch."
+    - type: $x_extension_properties_t*
+      name: pExtensionProperties
+      desc: "[out][optional] array of supported extension."
+    - type: uint32_t*
+      name: pCountRet
+      desc: "[out][optional] will be updated with the total count of supported extensions."

scripts/templates/index.rst.mako

@@ -13,4 +13,5 @@
 
    core/INTRO.rst
    core/PROG.rst
+   core/EXT.rst
    api.rst

source/adapters/null/ur_nullddi.cpp

@@ -218,6 +218,32 @@ __urdlllocal ur_result_t UR_APICALL urGetLastResult(
     return result;
 }
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Intercept function for urPlatformGetExtensionProperties
+__urdlllocal ur_result_t UR_APICALL urPlatformGetExtensionProperties(
+    ur_platform_handle_t hPlatform, ///< [in] handle to the platform.
+    uint32_t count, ///< [in] number of extension properties to fetch.
+    ur_extension_properties_t *
+        pExtensionProperties, ///< [out][optional] array of supported extension.
+    uint32_t *
+        pCountRet ///< [out][optional] will be updated with the total count of supported
+                  ///< extensions.
+) {
+    ur_result_t result = UR_RESULT_SUCCESS;
+
+    // if the driver has created a custom function, then call it instead of using the generic path
+    auto pfnGetExtensionProperties =
+        d_context.urDdiTable.Platform.pfnGetExtensionProperties;
+    if (nullptr != pfnGetExtensionProperties) {
+        result = pfnGetExtensionProperties(hPlatform, count,
+                                           pExtensionProperties, pCountRet);
+    } else {
+        // generic implementation
+    }
+
+    return result;
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Intercept function for urDeviceGet
 __urdlllocal ur_result_t UR_APICALL urDeviceGet(
@@ -3440,6 +3466,9 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetPlatformProcAddrTable(
 
     pDdiTable->pfnGetBackendOption = driver::urPlatformGetBackendOption;
 
+    pDdiTable->pfnGetExtensionProperties =
+        driver::urPlatformGetExtensionProperties;
+
     return result;
 }