[UR] Add backend option entrypoint

Author: veselypeta

include/ur.py

@@ -1577,6 +1577,7 @@ class ur_function_v(IntEnum):
     USM_GET_MEM_ALLOC_INFO = 111                    ## Enumerator for ::urUSMGetMemAllocInfo
     USM_POOL_CREATE = 112                           ## Enumerator for ::urUSMPoolCreate
     USM_POOL_DESTROY = 113                          ## Enumerator for ::urUSMPoolDestroy
+    PLATFORM_GET_BACKEND_OPTION = 114               ## Enumerator for ::urPlatformGetBackendOption
 
 class ur_function_t(c_int):
     def __str__(self):
@@ -1642,6 +1643,13 @@ def __str__(self):
 else:
     _urPlatformGetApiVersion_t = CFUNCTYPE( ur_result_t, ur_platform_handle_t, POINTER(ur_api_version_t) )
 
+###############################################################################
+## @brief Function-pointer for urPlatformGetBackendOption
+if __use_win_types:
+    _urPlatformGetBackendOption_t = WINFUNCTYPE( ur_result_t, ur_platform_handle_t, c_char_p, POINTER(c_char_p) )
+else:
+    _urPlatformGetBackendOption_t = CFUNCTYPE( ur_result_t, ur_platform_handle_t, c_char_p, POINTER(c_char_p) )
+
 
 ###############################################################################
 ## @brief Table of Platform functions pointers
@@ -1651,7 +1659,8 @@ class ur_platform_dditable_t(Structure):
         ("pfnGetInfo", c_void_p),                                       ## _urPlatformGetInfo_t
         ("pfnGetNativeHandle", c_void_p),                               ## _urPlatformGetNativeHandle_t
         ("pfnCreateWithNativeHandle", c_void_p),                        ## _urPlatformCreateWithNativeHandle_t
-        ("pfnGetApiVersion", c_void_p)                                  ## _urPlatformGetApiVersion_t
+        ("pfnGetApiVersion", c_void_p),                                 ## _urPlatformGetApiVersion_t
+        ("pfnGetBackendOption", c_void_p)                               ## _urPlatformGetBackendOption_t
     ]
 
 ###############################################################################
@@ -2641,6 +2650,7 @@ def __init__(self, version : ur_api_version_t):
         self.urPlatformGetNativeHandle = _urPlatformGetNativeHandle_t(self.__dditable.Platform.pfnGetNativeHandle)
         self.urPlatformCreateWithNativeHandle = _urPlatformCreateWithNativeHandle_t(self.__dditable.Platform.pfnCreateWithNativeHandle)
         self.urPlatformGetApiVersion = _urPlatformGetApiVersion_t(self.__dditable.Platform.pfnGetApiVersion)
+        self.urPlatformGetBackendOption = _urPlatformGetBackendOption_t(self.__dditable.Platform.pfnGetBackendOption)
 
         # call driver to get function pointers
         Context = ur_context_dditable_t()

include/ur_api.h

@@ -522,6 +522,36 @@ urPlatformCreateWithNativeHandle(
     ur_platform_handle_t *phPlatform    ///< [out] pointer to the handle of the platform object created.
 );
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Get the adapter specific compiler backend option from a generic
+///        frontend option.
+///
+/// @details
+///     - The string returned via the ppAdapterOption is a NULL terminated C
+///       style string.
+///     - The string returned via the ppAdapterOption is thread local.
+///     - The memory in the string returned via the ppAdapterOption is owned by
+///       the adapter.
+///     - The application may call this function from simultaneous threads.
+///     - The implementation of this function should be lock-free.
+///
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_UNINITIALIZED
+///     - ::UR_RESULT_ERROR_DEVICE_LOST
+///     - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
+///         + `NULL == hPlatform`
+///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+///         + `NULL == pFrontendOption`
+///         + `NULL == ppAdapterOption`
+UR_APIEXPORT ur_result_t UR_APICALL
+urPlatformGetBackendOption(
+    ur_platform_handle_t hPlatform, ///< [in] handle of the platform instance.
+    const char *pFrontendOption,    ///< [in] string containing the frontend option.
+    const char **ppAdapterOption    ///< [out] returns the correct adapter specific option based on the
+                                    ///< frontend option.
+);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Retrieve string representation of the underlying adapter specific
 ///        result reported by the the last API that returned
@@ -4295,6 +4325,7 @@ typedef enum ur_function_t {
     UR_FUNCTION_USM_GET_MEM_ALLOC_INFO = 111,              ///< Enumerator for ::urUSMGetMemAllocInfo
     UR_FUNCTION_USM_POOL_CREATE = 112,                     ///< Enumerator for ::urUSMPoolCreate
     UR_FUNCTION_USM_POOL_DESTROY = 113,                    ///< Enumerator for ::urUSMPoolDestroy
+    UR_FUNCTION_PLATFORM_GET_BACKEND_OPTION = 114,         ///< Enumerator for ::urPlatformGetBackendOption
     /// @cond
     UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
     /// @endcond
@@ -5526,6 +5557,28 @@ typedef void(UR_APICALL *ur_pfnPlatformGetApiVersionCb_t)(
     void *pTracerUserData,
     void **ppTracerInstanceUserData);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Callback function parameters for urPlatformGetBackendOption
+/// @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_backend_option_params_t {
+    ur_platform_handle_t *phPlatform;
+    const char **ppFrontendOption;
+    const char ***pppAdapterOption;
+} ur_platform_get_backend_option_params_t;
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Callback function-pointer for urPlatformGetBackendOption
+/// @param[in] params Parameters passed to this instance
+/// @param[in] result Return value
+/// @param[in] pTracerUserData Per-Tracer user data
+/// @param[in,out] ppTracerInstanceUserData Per-Tracer, Per-Instance user data
+typedef void(UR_APICALL *ur_pfnPlatformGetBackendOptionCb_t)(
+    ur_platform_get_backend_option_params_t *params,
+    ur_result_t result,
+    void *pTracerUserData,
+    void **ppTracerInstanceUserData);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Table of Platform callback functions pointers
 typedef struct ur_platform_callbacks_t {
@@ -5534,6 +5587,7 @@ typedef struct ur_platform_callbacks_t {
     ur_pfnPlatformGetNativeHandleCb_t pfnGetNativeHandleCb;
     ur_pfnPlatformCreateWithNativeHandleCb_t pfnCreateWithNativeHandleCb;
     ur_pfnPlatformGetApiVersionCb_t pfnGetApiVersionCb;
+    ur_pfnPlatformGetBackendOptionCb_t pfnGetBackendOptionCb;
 } ur_platform_callbacks_t;
 
 ///////////////////////////////////////////////////////////////////////////////

include/ur_ddi.h

@@ -53,6 +53,13 @@ typedef ur_result_t(UR_APICALL *ur_pfnPlatformGetApiVersion_t)(
     ur_platform_handle_t,
     ur_api_version_t *);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urPlatformGetBackendOption
+typedef ur_result_t(UR_APICALL *ur_pfnPlatformGetBackendOption_t)(
+    ur_platform_handle_t,
+    const char *,
+    const char **);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Table of Platform functions pointers
 typedef struct ur_platform_dditable_t {
@@ -61,6 +68,7 @@ typedef struct ur_platform_dditable_t {
     ur_pfnPlatformGetNativeHandle_t pfnGetNativeHandle;
     ur_pfnPlatformCreateWithNativeHandle_t pfnCreateWithNativeHandle;
     ur_pfnPlatformGetApiVersion_t pfnGetApiVersion;
+    ur_pfnPlatformGetBackendOption_t pfnGetBackendOption;
 } ur_platform_dditable_t;
 
 ///////////////////////////////////////////////////////////////////////////////

scripts/core/platform.yml

@@ -168,6 +168,28 @@ params:
             [out] pointer to the handle of the platform object created.
 --- #--------------------------------------------------------------------------
 type: function
+desc: "Get the adapter specific compiler backend option from a generic frontend option."
+class: $xPlatform
+name: GetBackendOption
+decl: static
+details:
+    - "The string returned via the ppAdapterOption is a NULL terminated C style string."
+    - "The string returned via the ppAdapterOption is thread local."
+    - "The memory in the string returned via the ppAdapterOption is owned by the adapter."
+    - "The application may call this function from simultaneous threads."
+    - "The implementation of this function should be lock-free."
+params:
+    - type: $x_platform_handle_t
+      name: hPlatform
+      desc: "[in] handle of the platform instance."
+    - type: const char*
+      name: pFrontendOption
+      desc: "[in] string containing the frontend option."
+    - type: const char**
+      name: ppAdapterOption
+      desc: "[out] returns the correct adapter specific option based on the frontend option."
+--- #--------------------------------------------------------------------------
+type: function
 desc: "Retrieve string representation of the underlying adapter specific result
        reported by the the last API that returned UR_RESULT_ADAPTER_SPECIFIC.
        Allows for an adapter independent way to return an adapter

scripts/core/registry.yml

@@ -346,3 +346,6 @@ etors:
 - name: USM_POOL_DESTROY
   desc: Enumerator for $xUSMPoolDestroy
   value: '113'
+- name: PLATFORM_GET_BACKEND_OPTION
+  desc: Enumerator for $xPlatformGetBackendOption
+  value: '114'

scripts/generate_ids.py

@@ -52,6 +52,7 @@ def generate_registry(path, specs):
     print("Updating registry %s"%path)
 
     ids = new_registry
+    ids = sorted(ids, key=lambda x: int(x['value']))
     wrapper = { 'name': ENUM_NAME, 'type': 'enum', 'desc': 'Defines unique stable identifiers for all functions' , 'etors': ids}
     header = {'type': 'header', 'desc': quoted('Intel$OneApi Unified Rutime function registry'), 'ordinal': quoted(9)}
 

source/common/ur_params.hpp

@@ -4270,6 +4270,10 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_function_t value) {
     case UR_FUNCTION_USM_POOL_DESTROY:
         os << "UR_FUNCTION_USM_POOL_DESTROY";
         break;
+
+    case UR_FUNCTION_PLATFORM_GET_BACKEND_OPTION:
+        os << "UR_FUNCTION_PLATFORM_GET_BACKEND_OPTION";
+        break;
     default:
         os << "unknown enumerator";
         break;
@@ -6730,6 +6734,27 @@ operator<<(std::ostream &os,
     return os;
 }
 
+inline std::ostream &
+operator<<(std::ostream &os,
+           const struct ur_platform_get_backend_option_params_t *params) {
+
+    os << ".hPlatform = ";
+
+    ur_params::serializePtr(os, *(params->phPlatform));
+
+    os << ", ";
+    os << ".pFrontendOption = ";
+
+    ur_params::serializePtr(os, *(params->ppFrontendOption));
+
+    os << ", ";
+    os << ".ppAdapterOption = ";
+
+    ur_params::serializePtr(os, *(params->pppAdapterOption));
+
+    return os;
+}
+
 inline std::ostream &
 operator<<(std::ostream &os,
            const struct ur_program_create_with_il_params_t *params) {
@@ -7933,6 +7958,9 @@ inline int serializeFunctionParams(std::ostream &os, uint32_t function,
     case UR_FUNCTION_PLATFORM_GET_API_VERSION: {
         os << (const struct ur_platform_get_api_version_params_t *)params;
     } break;
+    case UR_FUNCTION_PLATFORM_GET_BACKEND_OPTION: {
+        os << (const struct ur_platform_get_backend_option_params_t *)params;
+    } break;
     case UR_FUNCTION_PROGRAM_CREATE_WITH_IL: {
         os << (const struct ur_program_create_with_il_params_t *)params;
     } break;

source/drivers/null/ur_nullddi.cpp

@@ -170,6 +170,31 @@ __urdlllocal ur_result_t UR_APICALL urPlatformCreateWithNativeHandle(
     return result;
 }
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Intercept function for urPlatformGetBackendOption
+__urdlllocal ur_result_t UR_APICALL urPlatformGetBackendOption(
+    ur_platform_handle_t hPlatform, ///< [in] handle of the platform instance.
+    const char
+        *pFrontendOption, ///< [in] string containing the frontend option.
+    const char **
+        ppAdapterOption ///< [out] returns the correct adapter specific option based on the
+                        ///< frontend option.
+) {
+    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 pfnGetBackendOption =
+        d_context.urDdiTable.Platform.pfnGetBackendOption;
+    if (nullptr != pfnGetBackendOption) {
+        result =
+            pfnGetBackendOption(hPlatform, pFrontendOption, ppAdapterOption);
+    } else {
+        // generic implementation
+    }
+
+    return result;
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Intercept function for urGetLastResult
 __urdlllocal ur_result_t UR_APICALL urGetLastResult(
@@ -3342,6 +3367,8 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetPlatformProcAddrTable(
 
     pDdiTable->pfnGetApiVersion = driver::urPlatformGetApiVersion;
 
+    pDdiTable->pfnGetBackendOption = driver::urPlatformGetBackendOption;
+
     return result;
 }
 

source/loader/layers/tracing/ur_trcddi.cpp

@@ -208,6 +208,38 @@ __urdlllocal ur_result_t UR_APICALL urPlatformCreateWithNativeHandle(
     return result;
 }
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Intercept function for urPlatformGetBackendOption
+__urdlllocal ur_result_t UR_APICALL urPlatformGetBackendOption(
+    ur_platform_handle_t hPlatform, ///< [in] handle of the platform instance.
+    const char
+        *pFrontendOption, ///< [in] string containing the frontend option.
+    const char **
+        ppAdapterOption ///< [out] returns the correct adapter specific option based on the
+                        ///< frontend option.
+) {
+    auto pfnGetBackendOption = context.urDdiTable.Platform.pfnGetBackendOption;
+
+    if (nullptr == pfnGetBackendOption) {
+        return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
+    }
+
+    ur_platform_get_backend_option_params_t params = {
+        &hPlatform, &pFrontendOption, &ppAdapterOption};
+    uint64_t instance =
+        context.notify_begin(UR_FUNCTION_PLATFORM_GET_BACKEND_OPTION,
+                             "urPlatformGetBackendOption", &params);
+
+    ur_result_t result =
+        pfnGetBackendOption(hPlatform, pFrontendOption, ppAdapterOption);
+
+    context.notify_end(UR_FUNCTION_PLATFORM_GET_BACKEND_OPTION,
+                       "urPlatformGetBackendOption", &params, &result,
+                       instance);
+
+    return result;
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Intercept function for urGetLastResult
 __urdlllocal ur_result_t UR_APICALL urGetLastResult(
@@ -4112,6 +4144,10 @@ __urdlllocal ur_result_t UR_APICALL urGetPlatformProcAddrTable(
     dditable.pfnGetApiVersion = pDdiTable->pfnGetApiVersion;
     pDdiTable->pfnGetApiVersion = ur_tracing_layer::urPlatformGetApiVersion;
 
+    dditable.pfnGetBackendOption = pDdiTable->pfnGetBackendOption;
+    pDdiTable->pfnGetBackendOption =
+        ur_tracing_layer::urPlatformGetBackendOption;
+
     return result;
 }
 ///////////////////////////////////////////////////////////////////////////////

source/loader/layers/validation/ur_valddi.cpp

@@ -211,6 +211,42 @@ __urdlllocal ur_result_t UR_APICALL urPlatformCreateWithNativeHandle(
     return result;
 }
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Intercept function for urPlatformGetBackendOption
+__urdlllocal ur_result_t UR_APICALL urPlatformGetBackendOption(
+    ur_platform_handle_t hPlatform, ///< [in] handle of the platform instance.
+    const char
+        *pFrontendOption, ///< [in] string containing the frontend option.
+    const char **
+        ppAdapterOption ///< [out] returns the correct adapter specific option based on the
+                        ///< frontend option.
+) {
+    auto pfnGetBackendOption = context.urDdiTable.Platform.pfnGetBackendOption;
+
+    if (nullptr == pfnGetBackendOption) {
+        return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
+    }
+
+    if (context.enableParameterValidation) {
+        if (NULL == hPlatform) {
+            return UR_RESULT_ERROR_INVALID_NULL_HANDLE;
+        }
+
+        if (NULL == pFrontendOption) {
+            return UR_RESULT_ERROR_INVALID_NULL_POINTER;
+        }
+
+        if (NULL == ppAdapterOption) {
+            return UR_RESULT_ERROR_INVALID_NULL_POINTER;
+        }
+    }
+
+    ur_result_t result =
+        pfnGetBackendOption(hPlatform, pFrontendOption, ppAdapterOption);
+
+    return result;
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Intercept function for urGetLastResult
 __urdlllocal ur_result_t UR_APICALL urGetLastResult(
@@ -4983,6 +5019,10 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetPlatformProcAddrTable(
     dditable.pfnGetApiVersion = pDdiTable->pfnGetApiVersion;
     pDdiTable->pfnGetApiVersion = ur_validation_layer::urPlatformGetApiVersion;
 
+    dditable.pfnGetBackendOption = pDdiTable->pfnGetBackendOption;
+    pDdiTable->pfnGetBackendOption =
+        ur_validation_layer::urPlatformGetBackendOption;
+
     return result;
 }