/*

*

* Copyright (C) 2022 Intel Corporation

*

* Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.

* See LICENSE.TXT

* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception

*

* @file ur_libapi.cpp

*

* @brief C++ library for ur

*

*/

#include "ur_lib.hpp"

extern "C" {

///////////////////////////////////////////////////////////////////////////////

/// @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_result_t UR_APICALL urLoaderConfigCreate(

ur_loader_config_handle_t *

phLoaderConfig ///< [out] Pointer to handle of loader config object created.

) try {

return ur_lib::urLoaderConfigCreate(phLoaderConfig);

} catch (...) {

return exceptionToResult(std::current_exception());

}

///////////////////////////////////////////////////////////////////////////////

/// @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_result_t UR_APICALL urLoaderConfigRetain(

ur_loader_config_handle_t

hLoaderConfig ///< [in] loader config handle to retain

) try {

return ur_lib::urLoaderConfigRetain(hLoaderConfig);

} catch (...) {

return exceptionToResult(std::current_exception());

}

///////////////////////////////////////////////////////////////////////////////

/// @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_result_t UR_APICALL urLoaderConfigRelease(

ur_loader_config_handle_t hLoaderConfig ///< [in] config handle to release

) try {

return ur_lib::urLoaderConfigRelease(hLoaderConfig);

} catch (...) {

return exceptionToResult(std::current_exception());

}

///////////////////////////////////////////////////////////////////////////////

/// @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_REFERENCE_COUNT < 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_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.

) try {

return ur_lib::urLoaderConfigGetInfo(hLoaderConfig, propName, propSize,

pPropValue, pPropSizeRet);

} catch (...) {

return exceptionToResult(std::current_exception());

}

///////////////////////////////////////////////////////////////////////////////

/// @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_LAYER_NOT_PRESENT

/// + If layer specified with `pLayerName` can't be found by the loader.

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.

) try {

return ur_lib::urLoaderConfigEnableLayer(hLoaderConfig, pLayerName);

} catch (...) {

return exceptionToResult(std::current_exception());

}

///////////////////////////////////////////////////////////////////////////////

/// @brief Set a function callback for use by the loader to retrieve code

/// location information.

///

/// @details

/// - The code location callback is optional and provides additional

/// information to the tracing layer about the entry point of the current

/// execution flow.

/// - This functionality can be used to match traced unified runtime

/// function calls with higher-level user calls.

///

/// @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 == pfnCodeloc`

ur_result_t UR_APICALL urLoaderConfigSetCodeLocationCallback(

ur_loader_config_handle_t

hLoaderConfig, ///< [in] Handle to config object the layer will be enabled for.

ur_code_location_callback_t

pfnCodeloc, ///< [in] Function pointer to code location callback.

void *

pUserData ///< [in][out][optional] pointer to data to be passed to callback.

) try {

return ur_lib::urLoaderConfigSetCodeLocationCallback(hLoaderConfig,

pfnCodeloc, pUserData);

} catch (...) {

return exceptionToResult(std::current_exception());

}

///////////////////////////////////////////////////////////////////////////////

/// @brief Initialize the 'oneAPI' loader

///

/// @details

/// - The application must call this function before calling any other

/// function.

/// - If this function is not called then all other functions will return

/// ::UR_RESULT_ERROR_UNINITIALIZED.

/// - Only one instance of the loader will be initialized per process.

/// - The application may call this function multiple times with different

/// flags or environment variables enabled.

/// - The application must call this function after forking new processes.

/// Each forked process must call this function.

/// - The application may call this function from simultaneous threads.

/// - The implementation of this function must be thread-safe for scenarios

/// where multiple libraries may initialize the loader simultaneously.

///

/// @returns

/// - ::UR_RESULT_SUCCESS

/// - ::UR_RESULT_ERROR_UNINITIALIZED

/// - ::UR_RESULT_ERROR_DEVICE_LOST

/// - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC

/// - ::UR_RESULT_ERROR_INVALID_ENUMERATION

/// + `::UR_DEVICE_INIT_FLAGS_MASK & device_flags`

/// - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY

ur_result_t UR_APICALL urLoaderInit(

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.

) try {

if (UR_DEVICE_INIT_FLAGS_MASK & device_flags) {

return UR_RESULT_ERROR_INVALID_ENUMERATION;

}

static ur_result_t result = UR_RESULT_SUCCESS;

std::call_once(ur_lib::context->initOnce, [device_flags, hLoaderConfig]() {

result = ur_lib::context->Init(device_flags, hLoaderConfig);

});

return result;

} catch (...) {

return exceptionToResult(std::current_exception());

}

///////////////////////////////////////////////////////////////////////////////

/// @brief Tear down the 'oneAPI' loader and release all its resources

///

/// @returns

/// - ::UR_RESULT_SUCCESS

/// - ::UR_RESULT_ERROR_UNINITIALIZED

/// - ::UR_RESULT_ERROR_DEVICE_LOST

/// - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC

/// - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY

ur_result_t UR_APICALL urLoaderTearDown(void) try {

return ur_lib::urLoaderTearDown();

} catch (...) {

return exceptionToResult(std::current_exception());

}

///////////////////////////////////////////////////////////////////////////////

/// @brief Retrieves all available adapters

///

/// @details

/// - Adapter implementations must return exactly one adapter handle from

/// this entry point.

/// - The loader may return more than one adapter handle when there are

/// multiple available.

/// - Each returned adapter has its reference count incremented and should

/// be released with a subsequent call to ::urAdapterRelease.

/// - Adapters may perform adapter-specific state initialization when the

/// first reference to them is taken.

/// - An application may call this entry point multiple times to acquire

/// multiple references to the adapter handle(s).

///

/// @returns

/// - ::UR_RESULT_SUCCESS

/// - ::UR_RESULT_ERROR_UNINITIALIZED

/// - ::UR_RESULT_ERROR_DEVICE_LOST

/// - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC

/// - ::UR_RESULT_ERROR_INVALID_SIZE

ur_result_t UR_APICALL urAdapterGet(

uint32_t

NumEntries, ///< [in] the number of adapters to be added to phAdapters.

///< If phAdapters is not NULL, then NumEntries should be greater than

///< zero, otherwise ::UR_RESULT_ERROR_INVALID_SIZE,

///< will be returned.

ur_adapter_handle_t *

phAdapters, ///< [out][optional][range(0, NumEntries)] array of handle of adapters.

///< If NumEntries is less than the number of adapters available, then

///< ::urAdapterGet shall only retrieve that number of platforms.

uint32_t *

pNumAdapters ///< [out][optional] returns the total number of adapters available.

) try {

auto pfnAdapterGet = ur_lib::context->urDdiTable.Global.pfnAdapterGet;

if (nullptr == pfnAdapterGet) {

return UR_RESULT_ERROR_UNINITIALIZED;

}

return pfnAdapterGet(NumEntries, phAdapters, pNumAdapters);

} catch (...) {

return exceptionToResult(std::current_exception());

}

///////////////////////////////////////////////////////////////////////////////

/// @brief Releases the adapter handle reference indicating end of its usage

///

/// @details

/// - When the reference count of the adapter reaches zero, the adapter may

/// perform adapter-specififc resource teardown. Resources must be left in

/// a state where it safe for the adapter to be subsequently reinitialized

/// with ::urAdapterGet

///

/// @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 == hAdapter`

ur_result_t UR_APICALL urAdapterRelease(

ur_adapter_handle_t hAdapter ///< [in] Adapter handle to release

) try {

auto pfnAdapterRelease =

ur_lib::context->urDdiTable.Global.pfnAdapterRelease;

if (nullptr == pfnAdapterRelease) {

return UR_RESULT_ERROR_UNINITIALIZED;

}

return pfnAdapterRelease(hAdapter);

} catch (...) {

return exceptionToResult(std::current_exception());

}

///////////////////////////////////////////////////////////////////////////////

/// @brief Get a reference to the adapter handle.

///

/// @details

/// - Get a reference to the adapter handle. Increment its reference count

///

/// @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 == hAdapter`

ur_result_t UR_APICALL urAdapterRetain(

ur_adapter_handle_t hAdapter ///< [in] Adapter handle to retain

) try {

auto pfnAdapterRetain = ur_lib::context->urDdiTable.Global.pfnAdapterRetain;

if (nullptr == pfnAdapterRetain) {

return UR_RESULT_ERROR_UNINITIALIZED;

}

return pfnAdapterRetain(hAdapter);

} catch (...) {

return exceptionToResult(std::current_exception());

}

///////////////////////////////////////////////////////////////////////////////

/// @brief Get the last adapter specific error.

///

/// @details

/// To be used after another entry-point has returned

/// ::UR_RESULT_ERROR_ADAPTER_SPECIFIC in order to retrieve a message describing

/// the circumstances of the underlying driver error and the error code

/// returned by the failed driver entry-point.

///

/// * Implementations *must* store the message and error code in thread-local

/// storage prior to returning ::UR_RESULT_ERROR_ADAPTER_SPECIFIC.

///

/// * The message and error code storage is will only be valid if a previously

/// called entry-point returned ::UR_RESULT_ERROR_ADAPTER_SPECIFIC.

///

/// * The memory pointed to by the C string returned in `ppMessage` is owned by

/// the adapter and *must* be null terminated.

///

/// * The application *may* call this function from simultaneous threads.

///

/// * The implementation of this function *should* be lock-free.

///

/// Example usage:

///

/// ```cpp

/// if (::urQueueCreate(hContext, hDevice, nullptr, &hQueue) ==

/// ::UR_RESULT_ERROR_ADAPTER_SPECIFIC) {

/// const char* pMessage;

/// int32_t error;

/// ::urAdapterGetLastError(hAdapter, &pMessage, &error);

/// }

/// ```

///

/// @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 == hAdapter`

/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER

/// + `NULL == ppMessage`

/// + `NULL == pError`

ur_result_t UR_APICALL urAdapterGetLastError(

ur_adapter_handle_t hAdapter, ///< [in] handle of the adapter instance

const char **

ppMessage, ///< [out] pointer to a C string where the adapter specific error message

///< will be stored.

int32_t *

pError ///< [out] pointer to an integer where the adapter specific error code will

///< be stored.

) try {

auto pfnAdapterGetLastError =

ur_lib::context->urDdiTable.Global.pfnAdapterGetLastError;

if (nullptr == pfnAdapterGetLastError) {

return UR_RESULT_ERROR_UNINITIALIZED;

}

return pfnAdapterGetLastError(hAdapter, ppMessage, pError);

} catch (...) {

return exceptionToResult(std::current_exception());

}

///////////////////////////////////////////////////////////////////////////////

/// @brief Retrieves information about the adapter

///

/// @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 == hAdapter`

/// - ::UR_RESULT_ERROR_INVALID_ENUMERATION

/// + `::UR_ADAPTER_INFO_REFERENCE_COUNT < propName`

/// - ::UR_RESULT_ERROR_UNSUPPORTED_ENUMERATION

/// + If `propName` is not supported by the adapter.

/// - ::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_OUT_OF_RESOURCES

/// - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY

ur_result_t UR_APICALL urAdapterGetInfo(

ur_adapter_handle_t hAdapter, ///< [in] handle of the adapter

ur_adapter_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 Size is not equal to or greater to 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 number of bytes being queried by pPropValue.

) try {

auto pfnAdapterGetInfo =

ur_lib::context->urDdiTable.Global.pfnAdapterGetInfo;

if (nullptr == pfnAdapterGetInfo) {

return UR_RESULT_ERROR_UNINITIALIZED;

}

return pfnAdapterGetInfo(hAdapter, propName, propSize, pPropValue,

pPropSizeRet);

} catch (...) {

return exceptionToResult(std::current_exception());

}

///////////////////////////////////////////////////////////////////////////////

/// @brief Retrieves all available platforms for the given adapters

///

/// @details

/// - Multiple calls to this function will return identical platforms

/// handles, in the same order.

/// - The application may call this function from simultaneous threads, the

/// implementation must be thread-safe

///

/// @remarks

/// _Analogues_

/// - **clGetPlatformIDs**

///

/// @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 == phAdapters`

/// - ::UR_RESULT_ERROR_INVALID_SIZE

/// + `NumEntries == 0 && phPlatforms != NULL`

ur_result_t UR_APICALL urPlatformGet(

ur_adapter_handle_t *

phAdapters, ///< [in][range(0, NumAdapters)] array of adapters to query for platforms.

uint32_t NumAdapters, ///< [in] number of adapters pointed to by phAdapters

uint32_t

NumEntries, ///< [in] the number of platforms to be added to phPlatforms.

///< If phPlatforms is not NULL, then NumEntries should be greater than

///< zero, otherwise ::UR_RESULT_ERROR_INVALID_SIZE,

///< will be returned.

ur_platform_handle_t *

phPlatforms, ///< [out][optional][range(0, NumEntries)] array of handle of platforms.

///< If NumEntries is less than the number of platforms available, then

///< ::urPlatformGet shall only retrieve that number of platforms.

uint32_t *

pNumPlatforms ///< [out][optional] returns the total number of platforms available.

) try {

auto pfnGet = ur_lib::context->urDdiTable.Platform.pfnGet;

if (nullptr == pfnGet) {

return UR_RESULT_ERROR_UNINITIALIZED;

}

return pfnGet(phAdapters, NumAdapters, NumEntries, phPlatforms,

pNumPlatforms);

} catch (...) {

return exceptionToResult(std::current_exception());

}

///////////////////////////////////////////////////////////////////////////////

/// @brief Retrieves various information about platform

///

/// @details

/// - The application may call this function from simultaneous threads.

/// - The implementation of this function should be lock-free.

///

/// @remarks

/// _Analogues_

/// - **clGetPlatformInfo**

///

/// @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 == hPlatform`

/// - ::UR_RESULT_ERROR_INVALID_ENUMERATION

/// + `::UR_PLATFORM_INFO_BACKEND < propName`

/// - ::UR_RESULT_ERROR_UNSUPPORTED_ENUMERATION

/// + If `propName` is not supported by the adapter.

/// - ::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_PLATFORM

/// - ::UR_RESULT_ERROR_OUT_OF_RESOURCES

/// - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY

ur_result_t UR_APICALL urPlatformGetInfo(

ur_platform_handle_t hPlatform, ///< [in] handle of the platform

ur_platform_info_t propName, ///< [in] type of the info to retrieve

size_t propSize, ///< [in] the number of bytes pointed to by pPlatformInfo.

void *

pPropValue, ///< [out][optional][typename(propName, propSize)] array of bytes holding

///< the info.

///< If Size is not equal to or greater to the real number of bytes needed

///< to return the info then the ::UR_RESULT_ERROR_INVALID_SIZE error is

///< returned and pPlatformInfo is not used.

size_t *

pPropSizeRet ///< [out][optional] pointer to the actual number of bytes being queried by pPlatformInfo.

) try {

auto pfnGetInfo = ur_lib::context->urDdiTable.Platform.pfnGetInfo;

if (nullptr == pfnGetInfo) {

return UR_RESULT_ERROR_UNINITIALIZED;

}

return pfnGetInfo(hPlatform, propName, propSize, pPropValue, pPropSizeRet);

} catch (...) {

return exceptionToResult(std::current_exception());

}

///////////////////////////////////////////////////////////////////////////////

/// @brief Returns the API version supported by the specified platform

///

/// @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 == hPlatform`

/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER

/// + `NULL == pVersion`

ur_result_t UR_APICALL urPlatformGetApiVersion(

ur_platform_handle_t hPlatform, ///< [in] handle of the platform

ur_api_version_t *pVersion ///< [out] api version

) try {

auto pfnGetApiVersion =

ur_lib::context->urDdiTable.Platform.pfnGetApiVersion;

if (nullptr == pfnGetApiVersion) {

return UR_RESULT_ERROR_UNINITIALIZED;

}

return pfnGetApiVersion(hPlatform, pVersion);

} catch (...) {

return exceptionToResult(std::current_exception());

}

///////////////////////////////////////////////////////////////////////////////

/// @brief Return platform native platform handle.

///

/// @details

/// - Retrieved native handle can be used for direct interaction with the

/// native platform driver.

/// - Use interoperability platform extensions to convert native handle to

/// native type.

/// - The application may call this function from simultaneous threads for

/// the same context.

/// - The implementation of this function should be thread-safe.

///

/// @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 == hPlatform`

/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER

/// + `NULL == phNativePlatform`

/// - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE

/// + If the adapter has no underlying equivalent handle.

ur_result_t UR_APICALL urPlatformGetNativeHandle(

ur_platform_handle_t hPlatform, ///< [in] handle of the platform.

ur_native_handle_t *

phNativePlatform ///< [out] a pointer to the native handle of the platform.

) try {

auto pfnGetNativeHandle =

ur_lib::context->urDdiTable.Platform.pfnGetNativeHandle;

if (nullptr == pfnGetNativeHandle) {

return UR_RESULT_ERROR_UNINITIALIZED;

}

return pfnGetNativeHandle(hPlatform, phNativePlatform);

} catch (...) {

return exceptionToResult(std::current_exception());

}

///////////////////////////////////////////////////////////////////////////////

/// @brief Create runtime platform object from native platform handle.

///

/// @details

/// - Creates runtime platform handle from native driver platform handle.

/// - The application may call this function from simultaneous threads for

/// the same context.

/// - The implementation of this function should be thread-safe.

///

/// @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 == phPlatform`

/// - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE

/// + If the adapter has no underlying equivalent handle.

ur_result_t UR_APICALL urPlatformCreateWithNativeHandle(

ur_native_handle_t

hNativePlatform, ///< [in][nocheck] the native handle of the platform.

const ur_platform_native_properties_t *

pProperties, ///< [in][optional] pointer to native platform properties struct.

ur_platform_handle_t *

phPlatform ///< [out] pointer to the handle of the platform object created.

) try {

auto pfnCreateWithNativeHandle =

ur_lib::context->urDdiTable.Platform.pfnCreateWithNativeHandle;

if (nullptr == pfnCreateWithNativeHandle) {

return UR_RESULT_ERROR_UNINITIALIZED;

}

return pfnCreateWithNativeHandle(hNativePlatform, pProperties, phPlatform);

} catch (...) {

return exceptionToResult(std::current_exception());

}

///////////////////////////////////////////////////////////////////////////////

/// @brief Get the platform specific compiler backend option from a generic

/// frontend option.

///

/// @details

/// - The string returned via the ppPlatformOption is a NULL terminated C

/// style string.

/// - The string returned via the ppPlatformOption is thread local.

/// - The memory in the string returned via the ppPlatformOption 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_ADAPTER_SPECIFIC

/// - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE

/// + `NULL == hPlatform`

/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER

/// + `NULL == pFrontendOption`

/// + `NULL == ppPlatformOption`

/// - ::UR_RESULT_ERROR_INVALID_VALUE

/// + If `pFrontendOption` is not a valid frontend option.

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 **

ppPlatformOption ///< [out] returns the correct platform specific compiler option based on

///< the frontend option.

) try {

auto pfnGetBackendOption =

ur_lib::context->urDdiTable.Platform.pfnGetBackendOption;

if (nullptr == pfnGetBackendOption) {

return UR_RESULT_ERROR_UNINITIALIZED;

}

return pfnGetBackendOption(hPlatform, pFrontendOption, ppPlatformOption);

} catch (...) {

return exceptionToResult(std::current_exception());

}

///////////////////////////////////////////////////////////////////////////////

/// @brief Retrieves devices within a platform

///

/// @details

/// - Multiple calls to this function will return identical device handles,

/// in the same order.

/// - The number and order of handles returned from this function can be

/// affected by environment variables that filter devices exposed through

/// API.

/// - The returned devices are taken a reference of and must be released

/// with a subsequent call to ::urDeviceRelease.

/// - The application may call this function from simultaneous threads, the

/// implementation must be thread-safe

///

/// @remarks

/// _Analogues_

/// - **clGetDeviceIDs**

///

/// @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 == hPlatform`

/// - ::UR_RESULT_ERROR_INVALID_ENUMERATION

/// + `::UR_DEVICE_TYPE_VPU < DeviceType`

/// - ::UR_RESULT_ERROR_INVALID_SIZE

/// + `NumEntries == 0 && phDevices != NULL`

/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER

/// + `NumEntries > 0 && phDevices == NULL`

/// - ::UR_RESULT_ERROR_INVALID_VALUE

ur_result_t UR_APICALL urDeviceGet(

ur_platform_handle_t hPlatform, ///< [in] handle of the platform instance

ur_device_type_t DeviceType, ///< [in] the type of the devices.

uint32_t

NumEntries, ///< [in] the number of devices to be added to phDevices.

///< If phDevices is not NULL, then NumEntries should be greater than zero.

///< Otherwise ::UR_RESULT_ERROR_INVALID_SIZE

///< will be returned.

ur_device_handle_t *

phDevices, ///< [out][optional][range(0, NumEntries)] array of handle of devices.

///< If NumEntries is less than the number of devices available, then

///< platform shall only retrieve that number of devices.

uint32_t *pNumDevices ///< [out][optional] pointer to the number of devices.

///< pNumDevices will be updated with the total number of devices available.

) try {

auto pfnGet = ur_lib::context->urDdiTable.Device.pfnGet;

if (nullptr == pfnGet) {

return UR_RESULT_ERROR_UNINITIALIZED;

}

return pfnGet(hPlatform, DeviceType, NumEntries, phDevices, pNumDevices);

} catch (...) {

return exceptionToResult(std::current_exception());

}

///////////////////////////////////////////////////////////////////////////////

/// @brief Retrieves various information about device

///

/// @details

/// - The application may call this function from simultaneous threads.

/// - The implementation of this function should be lock-free.

///

/// @remarks

/// _Analogues_

/// - **clGetDeviceInfo**

///

/// @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 == hDevice`

/// - ::UR_RESULT_ERROR_INVALID_ENUMERATION

/// + `::UR_DEVICE_INFO_INTEROP_SEMAPHORE_EXPORT_SUPPORT_EXP < propName`

/// - ::UR_RESULT_ERROR_UNSUPPORTED_ENUMERATION

/// + If `propName` is not supported by the adapter.

/// - ::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_result_t UR_APICALL urDeviceGetInfo(

ur_device_handle_t hDevice, ///< [in] handle of the device instance

ur_device_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.

) try {

auto pfnGetInfo = ur_lib::context->urDdiTable.Device.pfnGetInfo;

if (nullptr == pfnGetInfo) {

return UR_RESULT_ERROR_UNINITIALIZED;

}

return pfnGetInfo(hDevice, propName, propSize, pPropValue, pPropSizeRet);

} catch (...) {

return exceptionToResult(std::current_exception());

}

///////////////////////////////////////////////////////////////////////////////

/// @brief Makes a reference of the device handle indicating it's in use until

/// paired ::urDeviceRelease is called

///

/// @details

/// - Increments the device reference count if `hDevice` is a valid

/// sub-device created by a call to `urDevicePartition`. If `hDevice` is a

/// root level device (e.g. obtained with `urDeviceGet`), the reference

/// count remains unchanged.

/// - It is not valid to use the device handle, which has all of its

/// references released.

/// - The application may call this function from simultaneous threads for

/// the same device.

/// - The implementation of this function should be thread-safe.

///

/// @remarks

/// _Analogues_

/// - **clRetainDevice**

///

/// @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 == hDevice`

ur_result_t UR_APICALL urDeviceRetain(

ur_device_handle_t

hDevice ///< [in] handle of the device to get a reference of.

) try {

auto pfnRetain = ur_lib::context->urDdiTable.Device.pfnRetain;

if (nullptr == pfnRetain) {

return UR_RESULT_ERROR_UNINITIALIZED;

}

return pfnRetain(hDevice);

} catch (...) {

return exceptionToResult(std::current_exception());

}

///////////////////////////////////////////////////////////////////////////////

/// @brief Releases the device handle reference indicating end of its usage

///

/// @details

/// - Decrements the device reference count if `hDevice` is a valid

/// sub-device created by a call to `urDevicePartition`. If `hDevice` is a

/// root level device (e.g. obtained with `urDeviceGet`), the reference

/// count remains unchanged.

/// - The application may call this function from simultaneous threads for

/// the same device.

/// - The implementation of this function should be thread-safe.

///

/// @remarks

/// _Analogues_

/// - **clReleaseDevice**

///

/// @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 == hDevice`

ur_result_t UR_APICALL urDeviceRelease(

ur_device_handle_t hDevice ///< [in] handle of the device to release.

) try {

auto pfnRelease = ur_lib::context->urDdiTable.Device.pfnRelease;

if (nullptr == pfnRelease) {

return UR_RESULT_ERROR_UNINITIALIZED;

}

return pfnRelease(hDevice);

} catch (...) {

return exceptionToResult(std::current_exception());

}

///////////////////////////////////////////////////////////////////////////////

/// @brief Partition the device into sub-devices

///

/// @details

/// - Repeated calls to this function with the same inputs will produce the

/// same output in the same order.

/// - The function may be called to request a further partitioning of a

/// sub-device into sub-sub-devices, and so on.

/// - The application may call this function from simultaneous threads for

/// the same device.

/// - The implementation of this function should be thread-safe.

///

/// @remarks

/// _Analogues_

/// - **clCreateSubDevices**

///

/// @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 == hDevice`

/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER

/// + `NULL == pProperties`

/// + `NULL == pProperties->pProperties`

/// - ::UR_RESULT_ERROR_DEVICE_PARTITION_FAILED

/// - ::UR_RESULT_ERROR_INVALID_DEVICE_PARTITION_COUNT

ur_result_t UR_APICALL urDevicePartition(

ur_device_handle_t hDevice, ///< [in] handle of the device to partition.

const ur_device_partition_properties_t

*pProperties, ///< [in] Device partition properties.

uint32_t NumDevices, ///< [in] the number of sub-devices.

ur_device_handle_t *

phSubDevices, ///< [out][optional][range(0, NumDevices)] array of handle of devices.

///< If NumDevices is less than the number of sub-devices available, then

///< the function shall only retrieve that number of sub-devices.

uint32_t *

pNumDevicesRet ///< [out][optional] pointer to the number of sub-devices the device can be

///< partitioned into according to the partitioning property.

) try {

auto pfnPartition = ur_lib::context->urDdiTable.Device.pfnPartition;

if (nullptr == pfnPartition) {

return UR_RESULT_ERROR_UNINITIALIZED;

}

return pfnPartition(hDevice, pProperties, NumDevices, phSubDevices,

pNumDevicesRet);

} catch (...) {

return exceptionToResult(std::current_exception());

}

///////////////////////////////////////////////////////////////////////////////

/// @brief Selects the most appropriate device binary based on runtime

/// information and the IR characteristics.

///

/// @details

/// - The input binaries are various AOT images, and possibly an IL binary

/// for JIT compilation.

/// - The selected binary will be able to be run on the target device.

/// - If no suitable binary can be found then function returns

/// ${X}_INVALID_BINARY.

/// - The application may call this function from simultaneous threads for

/// the same device.

/// - The implementation of this function should be thread-safe.

///

/// @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 == hDevice`

/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER

/// + `NULL == pBinaries`

/// + `NULL == pSelectedBinary`

/// - ::UR_RESULT_ERROR_INVALID_SIZE

/// + `NumBinaries == 0`

ur_result_t UR_APICALL urDeviceSelectBinary(

ur_device_handle_t

hDevice, ///< [in] handle of the device to select binary for.

const ur_device_binary_t

*pBinaries, ///< [in] the array of binaries to select from.

uint32_t NumBinaries, ///< [in] the number of binaries passed in ppBinaries.

///< Must greater than or equal to zero otherwise

///< ::UR_RESULT_ERROR_INVALID_VALUE is returned.

uint32_t *

pSelectedBinary ///< [out] the index of the selected binary in the input array of binaries.

///< If a suitable binary was not found the function returns ::UR_RESULT_ERROR_INVALID_BINARY.

) try {