Implement loader config object, allow programatic layer management.

examples/hello_world/hello_world.cpp

@@ -19,7 +19,7 @@ int main(int argc, char *argv[]) {
  ur_result_t status;
 
  // Initialize the platform
- status = urInit(0);
+ status = urInit(0, nullptr);
  if (status != UR_RESULT_SUCCESS) {
  std::cout << "urInit failed with return code: " << status << std::endl;
  return 1;

include/ur.py

@@ -55,6 +55,11 @@ def UR_MINOR_VERSION( _ver ):
 class ur_bool_t(c_ubyte):
  pass
 
+###############################################################################
+## @brief Handle of a loader config object
+class ur_loader_config_handle_t(c_void_p):
+ pass
+
 ###############################################################################
 ## @brief Handle of a platform instance
 class ur_platform_handle_t(c_void_p):
@@ -300,6 +305,17 @@ def __str__(self):
  return hex(self.value)
 
 
+###############################################################################
+## @brief Supported loader info
+class ur_loader_config_info_v(IntEnum):
+ AVAILABLE_LAYERS = 0 ## [char[]] Null-terminated, semi-colon separated list of available
+ ## layers.
+
+class ur_loader_config_info_t(c_int):
+ def __str__(self):
+ return str(ur_loader_config_info_v(self.value))
+
+
 ###############################################################################
 ## @brief Supported platform info
 class ur_platform_info_v(IntEnum):
@@ -2034,6 +2050,11 @@ class ur_function_v(IntEnum):
  COMMAND_BUFFER_APPEND_MEMBUFFER_READ_EXP = 169 ## Enumerator for ::urCommandBufferAppendMembufferReadExp
  COMMAND_BUFFER_APPEND_MEMBUFFER_WRITE_RECT_EXP = 170## Enumerator for ::urCommandBufferAppendMembufferWriteRectExp
  COMMAND_BUFFER_APPEND_MEMBUFFER_READ_RECT_EXP = 171 ## Enumerator for ::urCommandBufferAppendMembufferReadRectExp
+ LOADER_CONFIG_CREATE = 172 ## Enumerator for ::urLoaderConfigCreate
+ LOADER_CONFIG_RELEASE = 173 ## Enumerator for ::urLoaderConfigRelease
+ LOADER_CONFIG_RETAIN = 174 ## Enumerator for ::urLoaderConfigRetain
+ LOADER_CONFIG_GET_INFO = 175 ## Enumerator for ::urLoaderConfigGetInfo
+ LOADER_CONFIG_ENABLE_LAYER = 176 ## Enumerator for ::urLoaderConfigEnableLayer
 
 class ur_function_t(c_int):
  def __str__(self):
@@ -2155,6 +2176,53 @@ def __str__(self):
 ###############################################################################
 __use_win_types = "Windows" == platform.uname()[0]
 
+###############################################################################
+## @brief Function-pointer for urLoaderConfigCreate
+if __use_win_types:
+ _urLoaderConfigCreate_t = WINFUNCTYPE( ur_result_t, POINTER(ur_loader_config_handle_t) )
+else:
+ _urLoaderConfigCreate_t = CFUNCTYPE( ur_result_t, POINTER(ur_loader_config_handle_t) )
+
+###############################################################################
+## @brief Function-pointer for urLoaderConfigRetain
+if __use_win_types:
+ _urLoaderConfigRetain_t = WINFUNCTYPE( ur_result_t, ur_loader_config_handle_t )
+else:
+ _urLoaderConfigRetain_t = CFUNCTYPE( ur_result_t, ur_loader_config_handle_t )
+
+###############################################################################
+## @brief Function-pointer for urLoaderConfigRelease
+if __use_win_types:
+ _urLoaderConfigRelease_t = WINFUNCTYPE( ur_result_t, ur_loader_config_handle_t )
+else:
+ _urLoaderConfigRelease_t = CFUNCTYPE( ur_result_t, ur_loader_config_handle_t )
+
+###############################################################################
+## @brief Function-pointer for urLoaderConfigGetInfo
+if __use_win_types:
+ _urLoaderConfigGetInfo_t = WINFUNCTYPE( ur_result_t, ur_loader_config_handle_t, ur_loader_config_info_t, c_size_t, c_void_p, POINTER(c_size_t) )
+else:
+ _urLoaderConfigGetInfo_t = CFUNCTYPE( ur_result_t, ur_loader_config_handle_t, ur_loader_config_info_t, c_size_t, c_void_p, POINTER(c_size_t) )
+
+###############################################################################
+## @brief Function-pointer for urLoaderConfigEnableLayer
+if __use_win_types:
+ _urLoaderConfigEnableLayer_t = WINFUNCTYPE( ur_result_t, ur_loader_config_handle_t, c_char_p )
+else:
+ _urLoaderConfigEnableLayer_t = CFUNCTYPE( ur_result_t, ur_loader_config_handle_t, c_char_p )
+
+
+###############################################################################
+## @brief Table of LoaderConfig functions pointers
+class ur_loader_config_dditable_t(Structure):
+ _fields_ = [
+ ("pfnCreate", c_void_p), ## _urLoaderConfigCreate_t
+ ("pfnRetain", c_void_p), ## _urLoaderConfigRetain_t
+ ("pfnRelease", c_void_p), ## _urLoaderConfigRelease_t
+ ("pfnGetInfo", c_void_p), ## _urLoaderConfigGetInfo_t
+ ("pfnEnableLayer", c_void_p) ## _urLoaderConfigEnableLayer_t
+ ]
+
 ###############################################################################
 ## @brief Function-pointer for urPlatformGet
 if __use_win_types:
@@ -3439,9 +3507,9 @@ class ur_usm_p2p_exp_dditable_t(Structure):
 ###############################################################################
 ## @brief Function-pointer for urInit
 if __use_win_types:
- _urInit_t = WINFUNCTYPE( ur_result_t, ur_device_init_flags_t )
+ _urInit_t = WINFUNCTYPE( ur_result_t, ur_device_init_flags_t, ur_loader_config_handle_t )
 else:
- _urInit_t = CFUNCTYPE( ur_result_t, ur_device_init_flags_t )
+ _urInit_t = CFUNCTYPE( ur_result_t, ur_device_init_flags_t, ur_loader_config_handle_t )
 
 ###############################################################################
 ## @brief Function-pointer for urTearDown
@@ -3604,6 +3672,7 @@ class ur_device_dditable_t(Structure):
 ###############################################################################
 class ur_dditable_t(Structure):
  _fields_ = [
+ ("LoaderConfig", ur_loader_config_dditable_t),
  ("Platform", ur_platform_dditable_t),
  ("Context", ur_context_dditable_t),
  ("Event", ur_event_dditable_t),

include/ur_api.h

@@ -88,6 +88,10 @@ extern "C" {
 /// @brief compiler-independent type
 typedef uint8_t ur_bool_t;
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Handle of a loader config object
+typedef struct ur_loader_config_handle_t_ *ur_loader_config_handle_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Handle of a platform instance
 typedef struct ur_platform_handle_t_ *ur_platform_handle_t;
@@ -333,6 +337,136 @@ typedef enum ur_device_init_flag_t {
 /// @brief Bit Mask for validating ur_device_init_flags_t
 #define UR_DEVICE_INIT_FLAGS_MASK 0xffffffe0
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Create a loader config object.
+///
+/// @returns
+/// - ::UR_RESULT_SUCCESS
+/// - ::UR_RESULT_ERROR_UNINITIALIZED
+/// - ::UR_RESULT_ERROR_DEVICE_LOST
+/// - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
+/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+/// + `NULL == phLoaderConfig`
+UR_APIEXPORT ur_result_t UR_APICALL
+urLoaderConfigCreate(
+ ur_loader_config_handle_t *phLoaderConfig ///< [out] Pointer to handle of loader config object created.
+);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Get a reference to the loader config object.
+///
+/// @details
+/// - Get a reference to the loader config handle. Increment its reference
+/// count
+/// - 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_ADAPTER_SPECIFIC
+/// - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
+/// + `NULL == hLoaderConfig`
+UR_APIEXPORT ur_result_t UR_APICALL
+urLoaderConfigRetain(
+ ur_loader_config_handle_t hLoaderConfig ///< [in] loader config handle to retain
+);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Release config handle.
+///
+/// @details
+/// - Decrement reference count and destroy the config handle if reference
+/// count becomes zero.
+/// - 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_ADAPTER_SPECIFIC
+/// - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
+/// + `NULL == hLoaderConfig`
+UR_APIEXPORT ur_result_t UR_APICALL
+urLoaderConfigRelease(
+ ur_loader_config_handle_t hLoaderConfig ///< [in] config handle to release
+);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Supported loader info
+typedef enum ur_loader_config_info_t {
+ UR_LOADER_CONFIG_INFO_AVAILABLE_LAYERS = 0, ///< [char[]] Null-terminated, semi-colon separated list of available
+ ///< layers.
+ /// @cond
+ UR_LOADER_CONFIG_INFO_FORCE_UINT32 = 0x7fffffff
+ /// @endcond
+
+} ur_loader_config_info_t;
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Retrieves various information about the loader.
+///
+/// @details
+/// - 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_ADAPTER_SPECIFIC
+/// - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
+/// + `NULL == hLoaderConfig`
+/// - ::UR_RESULT_ERROR_INVALID_ENUMERATION
+/// + `::UR_LOADER_CONFIG_INFO_AVAILABLE_LAYERS < propName`
+/// - ::UR_RESULT_ERROR_UNSUPPORTED_ENUMERATION
+/// + If `propName` is not supported by the loader.
+/// - ::UR_RESULT_ERROR_INVALID_SIZE
+/// + `propSize == 0 && pPropValue != NULL`
+/// + If `propSize` is less than the real number of bytes needed to return the info.
+/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+/// + `propSize != 0 && pPropValue == NULL`
+/// + `pPropValue == NULL && pPropSizeRet == NULL`
+/// - ::UR_RESULT_ERROR_INVALID_DEVICE
+/// - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
+/// - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
+UR_APIEXPORT ur_result_t UR_APICALL
+urLoaderConfigGetInfo(
+ ur_loader_config_handle_t hLoaderConfig, ///< [in] handle of the loader config object
+ ur_loader_config_info_t propName, ///< [in] type of the info to retrieve
+ size_t propSize, ///< [in] the number of bytes pointed to by pPropValue.
+ void *pPropValue, ///< [out][optional][typename(propName, propSize)] array of bytes holding
+ ///< the info.
+ ///< If propSize is not equal to or greater than the real number of bytes
+ ///< needed to return the info
+ ///< then the ::UR_RESULT_ERROR_INVALID_SIZE error is returned and
+ ///< pPropValue is not used.
+ size_t *pPropSizeRet ///< [out][optional] pointer to the actual size in bytes of the queried propName.
+);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Enable a layer for the specified loader config.
+///
+/// @returns
+/// - ::UR_RESULT_SUCCESS
+/// - ::UR_RESULT_ERROR_UNINITIALIZED
+/// - ::UR_RESULT_ERROR_DEVICE_LOST
+/// - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
+/// - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
+/// + `NULL == hLoaderConfig`
+/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+/// + `NULL == pLayerName`
+/// - ::UR_RESULT_ERROR_INVALID_VALUE
+/// + If layer specified with `pLayerName` can't be found by the loader.
+UR_APIEXPORT ur_result_t UR_APICALL
+urLoaderConfigEnableLayer(
+ ur_loader_config_handle_t hLoaderConfig, ///< [in] Handle to config object the layer will be enabled for.
+ const char *pLayerName ///< [in] Null terminated string containing the name of the layer to
+ ///< enable.
+);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Initialize the 'oneAPI' adapter(s)
 ///
@@ -360,8 +494,9 @@ typedef enum ur_device_init_flag_t {
 /// - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
 UR_APIEXPORT ur_result_t UR_APICALL
 urInit(
- ur_device_init_flags_t device_flags ///< [in] device initialization flags.
- ///< must be 0 (default) or a combination of ::ur_device_init_flag_t.
+ ur_device_init_flags_t device_flags, ///< [in] device initialization flags.
+ ///< must be 0 (default) or a combination of ::ur_device_init_flag_t.
+ ur_loader_config_handle_t hLoaderConfig ///< [in][optional] Handle of loader config handle.
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -5358,6 +5493,11 @@ typedef enum ur_function_t {
  UR_FUNCTION_COMMAND_BUFFER_APPEND_MEMBUFFER_READ_EXP = 169, ///< Enumerator for ::urCommandBufferAppendMembufferReadExp
  UR_FUNCTION_COMMAND_BUFFER_APPEND_MEMBUFFER_WRITE_RECT_EXP = 170, ///< Enumerator for ::urCommandBufferAppendMembufferWriteRectExp
  UR_FUNCTION_COMMAND_BUFFER_APPEND_MEMBUFFER_READ_RECT_EXP = 171, ///< Enumerator for ::urCommandBufferAppendMembufferReadRectExp
+ UR_FUNCTION_LOADER_CONFIG_CREATE = 172, ///< Enumerator for ::urLoaderConfigCreate
+ UR_FUNCTION_LOADER_CONFIG_RELEASE = 173, ///< Enumerator for ::urLoaderConfigRelease
+ UR_FUNCTION_LOADER_CONFIG_RETAIN = 174, ///< Enumerator for ::urLoaderConfigRetain
+ UR_FUNCTION_LOADER_CONFIG_GET_INFO = 175, ///< Enumerator for ::urLoaderConfigGetInfo
+ UR_FUNCTION_LOADER_CONFIG_ENABLE_LAYER = 176, ///< Enumerator for ::urLoaderConfigEnableLayer
  /// @cond
  UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
  /// @endcond
@@ -7864,6 +8004,51 @@ urUsmP2PPeerAccessGetInfoExp(
 #if !defined(__GNUC__)
 #pragma region callbacks
 #endif
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urLoaderConfigCreate
+/// @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_loader_config_create_params_t {
+ ur_loader_config_handle_t **pphLoaderConfig;
+} ur_loader_config_create_params_t;
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urLoaderConfigRetain
+/// @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_loader_config_retain_params_t {
+ ur_loader_config_handle_t *phLoaderConfig;
+} ur_loader_config_retain_params_t;
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urLoaderConfigRelease
+/// @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_loader_config_release_params_t {
+ ur_loader_config_handle_t *phLoaderConfig;
+} ur_loader_config_release_params_t;
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urLoaderConfigGetInfo
+/// @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_loader_config_get_info_params_t {
+ ur_loader_config_handle_t *phLoaderConfig;
+ ur_loader_config_info_t *ppropName;
+ size_t *ppropSize;
+ void **ppPropValue;
+ size_t **ppPropSizeRet;
+} ur_loader_config_get_info_params_t;
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urLoaderConfigEnableLayer
+/// @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_loader_config_enable_layer_params_t {
+ ur_loader_config_handle_t *phLoaderConfig;
+ const char **ppLayerName;
+} ur_loader_config_enable_layer_params_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function parameters for urPlatformGet
 /// @details Each entry is a pointer to the parameter passed to the function;
@@ -9619,6 +9804,7 @@ typedef struct ur_usm_p2p_peer_access_get_info_exp_params_t {
 /// allowing the callback the ability to modify the parameter's value
 typedef struct ur_init_params_t {
  ur_device_init_flags_t *pdevice_flags;
+ ur_loader_config_handle_t *phLoaderConfig;
 } ur_init_params_t;
 
 ///////////////////////////////////////////////////////////////////////////////

include/ur_ddi.h

@@ -1869,7 +1869,8 @@ typedef ur_result_t(UR_APICALL *ur_pfnGetUsmP2PExpProcAddrTable_t)(
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function-pointer for urInit
 typedef ur_result_t(UR_APICALL *ur_pfnInit_t)(
- ur_device_init_flags_t);
+ ur_device_init_flags_t,
+ ur_loader_config_handle_t);
 
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function-pointer for urTearDown

scripts/core/common.yml

@@ -60,6 +60,11 @@ name: $x_bool_t
 value: uint8_t
 --- #--------------------------------------------------------------------------
 type: handle
+desc: "Handle of a loader config object"
+class: $xLoaderConfig
+name: "$x_loader_config_handle_t"
+--- #--------------------------------------------------------------------------
+type: handle
 desc: "Handle of a platform instance"
 class: $xPlatform
 name: "$x_platform_handle_t"

scripts/core/registry.yml

@@ -502,3 +502,18 @@ etors:
 - name: COMMAND_BUFFER_APPEND_MEMBUFFER_READ_RECT_EXP
  desc: Enumerator for $xCommandBufferAppendMembufferReadRectExp
  value: '171'
+- name: LOADER_CONFIG_CREATE
+ desc: Enumerator for $xLoaderConfigCreate
+ value: '172'
+- name: LOADER_CONFIG_RELEASE
+ desc: Enumerator for $xLoaderConfigRelease
+ value: '173'
+- name: LOADER_CONFIG_RETAIN
+ desc: Enumerator for $xLoaderConfigRetain
+ value: '174'
+- name: LOADER_CONFIG_GET_INFO
+ desc: Enumerator for $xLoaderConfigGetInfo
+ value: '175'
+- name: LOADER_CONFIG_ENABLE_LAYER
+ desc: Enumerator for $xLoaderConfigEnableLayer
+ value: '176'