[UR] Add extension documentation template

Author: Petr Vesely

include/ur.py

@@ -273,6 +273,18 @@ def __str__(self):
         return hex(self.value)
 
 
+###############################################################################
+## @brief Extension name maximum length.
+UR_MAX_EXTENSION_NAME_LENGTH = 256
+
+###############################################################################
+## @brief Extension type.
+class ur_platform_extension_t(Structure):
+    _fields_ = [
+        ("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 Supported platform info
 class ur_platform_info_v(IntEnum):
@@ -282,8 +294,9 @@ class ur_platform_info_v(IntEnum):
                                                     ## size of the info needs to be dynamically queried.
     VERSION = 3                                     ## [char[]] The string denoting the version of the platform. The size of
                                                     ## the info needs to be dynamically queried.
-    EXTENSIONS = 4                                  ## [char[]] The string denoting extensions supported by the platform. The
-                                                    ## size of the info needs to be dynamically queried.
+    EXTENSIONS = 4                                  ## [::ur_platform_extension_t[]] an array of ::ur_platform_extension_t
+                                                    ## which express which extensions supported by the platform. 
+                                                    ## The size of the info needs to be dynamically queried.
     PROFILE = 5                                     ## [char[]] The string denoting profile of the platform. The size of the
                                                     ## info needs to be dynamically queried.
     BACKEND = 6                                     ## [::ur_platform_backend_t] The backend of the platform. Identifies the
@@ -323,21 +336,6 @@ 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 
@@ -1767,13 +1765,6 @@ 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
@@ -1784,8 +1775,7 @@ 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
-        ("pfnGetExtensionProperties", c_void_p)                         ## _urPlatformGetExtensionProperties_t
+        ("pfnGetBackendOption", c_void_p)                               ## _urPlatformGetBackendOption_t
     ]
 
 ###############################################################################
@@ -2784,7 +2774,6 @@ 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

@@ -359,6 +359,20 @@ urTearDown(
 #if !defined(__GNUC__)
 #pragma region platform
 #endif
+///////////////////////////////////////////////////////////////////////////////
+#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 type.
+typedef struct ur_platform_extension_t {
+    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_platform_extension_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Retrieves all available platforms
 ///
@@ -398,8 +412,9 @@ typedef enum ur_platform_info_t {
                                       ///< size of the info needs to be dynamically queried.
     UR_PLATFORM_INFO_VERSION = 3,     ///< [char[]] The string denoting the version of the platform. The size of
                                       ///< the info needs to be dynamically queried.
-    UR_PLATFORM_INFO_EXTENSIONS = 4,  ///< [char[]] The string denoting extensions supported by the platform. The
-                                      ///< size of the info needs to be dynamically queried.
+    UR_PLATFORM_INFO_EXTENSIONS = 4,  ///< [::ur_platform_extension_t[]] an array of ::ur_platform_extension_t
+                                      ///< which express which extensions supported by the platform.
+                                      ///< The size of the info needs to be dynamically queried.
     UR_PLATFORM_INFO_PROFILE = 5,     ///< [char[]] The string denoting profile of the platform. The size of the
                                       ///< info needs to be dynamically queried.
     UR_PLATFORM_INFO_BACKEND = 6,     ///< [::ur_platform_backend_t] The backend of the platform. Identifies the
@@ -606,41 +621,6 @@ 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
@@ -5706,17 +5686,6 @@ 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,14 +60,6 @@ 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 {
@@ -77,7 +69,6 @@ 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

@@ -4,7 +4,7 @@
     X=x.upper()
 %>
 ==============
- Extensions
+Extensions
 ==============
 
 Objective
@@ -87,5 +87,22 @@ 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.
 
+Adding an extension
+===================
 
-// TODO - list all extensions
+* 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.
+
+
+List of Standard Extensions
+===========================
+// TODO - list all standard extensions
+
+List of Experimental Extensions
+===============================
+// TODO - list all experimental extensions

scripts/core/EXT_Template.rst

@@ -0,0 +1,42 @@
+<%
+import re
+from templates import helper as th
+%><%
+    OneApi=tags['$OneApi']
+    x=tags['$x']
+    X=x.upper()
+%>
+:orphan:
+
+==================================
+Unified Runtime Extension Template
+==================================
+
+API
+---
+
+* Enumerations
+
+
+    * List all enumerations defined by the extension.
+
+
+* Structures
+
+
+    * List all structures defined by the extension.
+    * ...
+
+
+* Functions
+
+
+    * List all functions defined by the extension.
+    * ...
+
+
+Unified Runtime Extension Template
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In this section describe in detail the purpose of the extension, along with its
+valid usage.

scripts/core/platform.yml

@@ -10,6 +10,23 @@ type: header
 desc: "Intel $OneApi Unified Runtime APIs for Platform"
 ordinal: "1"
 --- #--------------------------------------------------------------------------
+type: macro
+desc: "Extension name maximum length."
+name: $X_MAX_EXTENSION_NAME_LENGTH
+value: "256"
+--- #--------------------------------------------------------------------------
+type: struct
+desc: "Extension type."
+name: $x_platform_extension_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: "Retrieves all available platforms"
 class: $xPlatform
@@ -57,7 +74,9 @@ etors:
       desc: "[char[]] The string denoting the version of the platform. The size of the info needs to be dynamically queried."
     - name: EXTENSIONS
       value: "4"
-      desc: "[char[]] The string denoting extensions supported by the platform. The size of the info needs to be dynamically queried."
+      desc: |
+            [$x_platform_extension_t[]] an array of $x_platform_extension_t which express which extensions supported by the platform. 
+            The size of the info needs to be dynamically queried.
       todo: "document extensions names and their meaning"
     - name: PROFILE
       value: "5"
@@ -242,40 +261,3 @@ 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."

source/adapters/null/ur_nullddi.cpp

@@ -218,32 +218,6 @@ __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(
@@ -3466,9 +3440,6 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetPlatformProcAddrTable(
 
     pDdiTable->pfnGetBackendOption = driver::urPlatformGetBackendOption;
 
-    pDdiTable->pfnGetExtensionProperties =
-        driver::urPlatformGetExtensionProperties;
-
     return result;
 }