Rework null adapter into mock adapter

examples/collector/README.md

@@ -19,7 +19,7 @@ $ mkdir build
 $ cd build
 $ cmake .. -DUR_ENABLE_TRACING=ON
 $ make
-$ UR_ADAPTERS_FORCE_LOAD=./lib/libur_adapter_null.so UR_ENABLE_LAYERS=UR_LAYER_TRACING XPTI_TRACE_ENABLE=1 XPTI_FRAMEWORK_DISPATCHER=./lib/libxptifw.so XPTI_SUBSCRIBERS=./lib/libcollector.so ./bin/hello_world
+$ UR_ADAPTERS_FORCE_LOAD=./lib/libur_adapter_mock.so UR_ENABLE_LAYERS=UR_LAYER_TRACING XPTI_TRACE_ENABLE=1 XPTI_FRAMEWORK_DISPATCHER=./lib/libxptifw.so XPTI_SUBSCRIBERS=./lib/libcollector.so ./bin/hello_world
 ```
 
 See [XPTI framework documentation](https://github.com/intel/llvm/blob/sycl/xptifw/doc/XPTI_Framework.md) for more information.

include/ur_api.h

@@ -226,6 +226,7 @@ typedef enum ur_function_t {
     UR_FUNCTION_BINDLESS_IMAGES_IMPORT_EXTERNAL_MEMORY_EXP = 226,         ///< Enumerator for ::urBindlessImagesImportExternalMemoryExp
     UR_FUNCTION_BINDLESS_IMAGES_IMPORT_EXTERNAL_SEMAPHORE_EXP = 227,      ///< Enumerator for ::urBindlessImagesImportExternalSemaphoreExp
     UR_FUNCTION_ENQUEUE_NATIVE_COMMAND_EXP = 228,                         ///< Enumerator for ::urEnqueueNativeCommandExp
+    UR_FUNCTION_LOADER_CONFIG_SET_MOCKING_ENABLED = 229,                  ///< Enumerator for ::urLoaderConfigSetMockingEnabled
     /// @cond
     UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
     /// @endcond
@@ -601,7 +602,7 @@ urLoaderConfigCreate(
 ///         + `NULL == hLoaderConfig`
 UR_APIEXPORT ur_result_t UR_APICALL
 urLoaderConfigRetain(
-    ur_loader_config_handle_t hLoaderConfig ///< [in] loader config handle to retain
+    ur_loader_config_handle_t hLoaderConfig ///< [in][retain] loader config handle to retain
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -742,6 +743,29 @@ urLoaderConfigSetCodeLocationCallback(
     void *pUserData                          ///< [in][out][optional] pointer to data to be passed to callback.
 );
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief The only adapter reported with mock enabled will be the mock adapter.
+///
+/// @details
+///     - The mock adapter will default to returning ::UR_RESULT_SUCCESS for all
+///       entry points. It will also create and correctly reference count dummy
+///       handles where appropriate. Its behaviour can be modified by linking
+///       the mock library and using the object accessed via
+///       mock::getCallbacks().
+///
+/// @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
+urLoaderConfigSetMockingEnabled(
+    ur_loader_config_handle_t hLoaderConfig, ///< [in] Handle to config object mocking will be enabled for.
+    ur_bool_t enable                         ///< [in] Handle to config object the layer will be enabled for.
+);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Initialize the 'oneAPI' loader
 ///
@@ -863,7 +887,7 @@ urAdapterRelease(
 ///         + `NULL == hAdapter`
 UR_APIEXPORT ur_result_t UR_APICALL
 urAdapterRetain(
-    ur_adapter_handle_t hAdapter ///< [in] Adapter handle to retain
+    ur_adapter_handle_t hAdapter ///< [in][retain] Adapter handle to retain
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -1736,7 +1760,7 @@ urDeviceGetInfo(
 ///         + `NULL == hDevice`
 UR_APIEXPORT ur_result_t UR_APICALL
 urDeviceRetain(
-    ur_device_handle_t hDevice ///< [in] handle of the device to get a reference of.
+    ur_device_handle_t hDevice ///< [in][retain] handle of the device to get a reference of.
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -2217,7 +2241,7 @@ urContextCreate(
 ///         + `NULL == hContext`
 UR_APIEXPORT ur_result_t UR_APICALL
 urContextRetain(
-    ur_context_handle_t hContext ///< [in] handle of the context to get a reference of.
+    ur_context_handle_t hContext ///< [in][retain] handle of the context to get a reference of.
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -2739,7 +2763,7 @@ urMemBufferCreate(
 ///     - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
 UR_APIEXPORT ur_result_t UR_APICALL
 urMemRetain(
-    ur_mem_handle_t hMem ///< [in] handle of the memory object to get access
+    ur_mem_handle_t hMem ///< [in][retain] handle of the memory object to get access
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -3130,7 +3154,7 @@ urSamplerCreate(
 ///     - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
 UR_APIEXPORT ur_result_t UR_APICALL
 urSamplerRetain(
-    ur_sampler_handle_t hSampler ///< [in] handle of the sampler object to get access
+    ur_sampler_handle_t hSampler ///< [in][retain] handle of the sampler object to get access
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -3690,7 +3714,7 @@ urUSMPoolCreate(
 ///         + `NULL == pPool`
 UR_APIEXPORT ur_result_t UR_APICALL
 urUSMPoolRetain(
-    ur_usm_pool_handle_t pPool ///< [in] pointer to USM memory pool
+    ur_usm_pool_handle_t pPool ///< [in][retain] pointer to USM memory pool
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -4046,7 +4070,7 @@ urPhysicalMemCreate(
 ///         + `NULL == hPhysicalMem`
 UR_APIEXPORT ur_result_t UR_APICALL
 urPhysicalMemRetain(
-    ur_physical_mem_handle_t hPhysicalMem ///< [in] handle of the physical memory object to retain.
+    ur_physical_mem_handle_t hPhysicalMem ///< [in][retain] handle of the physical memory object to retain.
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -4334,7 +4358,7 @@ urProgramLink(
 ///         + `NULL == hProgram`
 UR_APIEXPORT ur_result_t UR_APICALL
 urProgramRetain(
-    ur_program_handle_t hProgram ///< [in] handle for the Program to retain
+    ur_program_handle_t hProgram ///< [in][retain] handle for the Program to retain
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -4985,7 +5009,7 @@ urKernelGetSubGroupInfo(
 ///         + `NULL == hKernel`
 UR_APIEXPORT ur_result_t UR_APICALL
 urKernelRetain(
-    ur_kernel_handle_t hKernel ///< [in] handle for the Kernel to retain
+    ur_kernel_handle_t hKernel ///< [in][retain] handle for the Kernel to retain
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -5492,7 +5516,7 @@ urQueueCreate(
 ///     - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
 UR_APIEXPORT ur_result_t UR_APICALL
 urQueueRetain(
-    ur_queue_handle_t hQueue ///< [in] handle of the queue object to get access
+    ur_queue_handle_t hQueue ///< [in][retain] handle of the queue object to get access
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -5887,7 +5911,7 @@ urEventWait(
 ///     - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
 UR_APIEXPORT ur_result_t UR_APICALL
 urEventRetain(
-    ur_event_handle_t hEvent ///< [in] handle of the event object
+    ur_event_handle_t hEvent ///< [in][retain] handle of the event object
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -8252,7 +8276,7 @@ urCommandBufferCreateExp(
 ///     - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
 UR_APIEXPORT ur_result_t UR_APICALL
 urCommandBufferRetainExp(
-    ur_exp_command_buffer_handle_t hCommandBuffer ///< [in] Handle of the command-buffer object.
+    ur_exp_command_buffer_handle_t hCommandBuffer ///< [in][retain] Handle of the command-buffer object.
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -8799,7 +8823,7 @@ urCommandBufferEnqueueExp(
 ///     - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
 UR_APIEXPORT ur_result_t UR_APICALL
 urCommandBufferRetainCommandExp(
-    ur_exp_command_buffer_command_handle_t hCommand ///< [in] Handle of the command-buffer command.
+    ur_exp_command_buffer_command_handle_t hCommand ///< [in][retain] Handle of the command-buffer command.
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -9657,6 +9681,15 @@ typedef struct ur_loader_config_set_code_location_callback_params_t {
     void **ppUserData;
 } ur_loader_config_set_code_location_callback_params_t;
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urLoaderConfigSetMockingEnabled
+/// @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_set_mocking_enabled_params_t {
+    ur_loader_config_handle_t *phLoaderConfig;
+    ur_bool_t *penable;
+} ur_loader_config_set_mocking_enabled_params_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function parameters for urPlatformGet
 /// @details Each entry is a pointer to the parameter passed to the function;

include/ur_print.h

@@ -1106,6 +1106,14 @@ UR_APIEXPORT ur_result_t UR_APICALL urPrintLoaderConfigEnableLayerParams(const s
 ///         - `buff_size < out_size`
 UR_APIEXPORT ur_result_t UR_APICALL urPrintLoaderConfigSetCodeLocationCallbackParams(const struct ur_loader_config_set_code_location_callback_params_t *params, char *buffer, const size_t buff_size, size_t *out_size);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_loader_config_set_mocking_enabled_params_t struct
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL urPrintLoaderConfigSetMockingEnabledParams(const struct ur_loader_config_set_mocking_enabled_params_t *params, char *buffer, const size_t buff_size, size_t *out_size);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print ur_platform_get_params_t struct
 /// @returns

include/ur_print.hpp

@@ -938,6 +938,9 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_function_t value) {
     case UR_FUNCTION_ENQUEUE_NATIVE_COMMAND_EXP:
         os << "UR_FUNCTION_ENQUEUE_NATIVE_COMMAND_EXP";
         break;
+    case UR_FUNCTION_LOADER_CONFIG_SET_MOCKING_ENABLED:
+        os << "UR_FUNCTION_LOADER_CONFIG_SET_MOCKING_ENABLED";
+        break;
     default:
         os << "unknown enumerator";
         break;
@@ -10277,6 +10280,25 @@ inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct
     return os;
 }
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print operator for the ur_loader_config_set_mocking_enabled_params_t type
+/// @returns
+///     std::ostream &
+inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_loader_config_set_mocking_enabled_params_t *params) {
+
+    os << ".hLoaderConfig = ";
+
+    ur::details::printPtr(os,
+                          *(params->phLoaderConfig));
+
+    os << ", ";
+    os << ".enable = ";
+
+    os << *(params->penable);
+
+    return os;
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print operator for the ur_platform_get_params_t type
 /// @returns
@@ -17332,6 +17354,9 @@ inline ur_result_t UR_APICALL printFunctionParams(std::ostream &os, ur_function_
     case UR_FUNCTION_LOADER_CONFIG_SET_CODE_LOCATION_CALLBACK: {
         os << (const struct ur_loader_config_set_code_location_callback_params_t *)params;
     } break;
+    case UR_FUNCTION_LOADER_CONFIG_SET_MOCKING_ENABLED: {
+        os << (const struct ur_loader_config_set_mocking_enabled_params_t *)params;
+    } break;
     case UR_FUNCTION_PLATFORM_GET: {
         os << (const struct ur_platform_get_params_t *)params;
     } break;

scripts/YaML.md

@@ -620,11 +620,12 @@ class ur_name_t(Structure):
       - `out` is used for params that are write-only; if the param is a pointer, then the memory being pointed to is also write-only
       - `in,out` is used for params that are both read and write; typically this is used for pointers to other data structures that contain both read and write params
       - `nocheck` is used to specify that no additional validation checks will be generated.
-    + `desc` may include one the following annotations: {`"[optional]"`, `"[range(start,end)]"`, `"[release]"`, `"[typename(typeVarName)]"`, `"[bounds(offset,size)]"`}
+    + `desc` may include one the following annotations: {`"[optional]"`, `"[range(start,end)]"`, `"[retain]"`, `"[release]"`, `"[typename(typeVarName)]"`, `"[bounds(offset,size)]"`}
       - `optional` is used for params that are handles or pointers where it is legal for the value to be `nullptr`
       - `range` is used for params that are array pointers to specify the valid range that the is valid to read
         + `start` and `end` must be an ISO-C standard identifier or literal
         + `start` is inclusive and `end` is exclusive
+      - `retain` is used for params that are handles or pointers to handles where the function will increment the reference counter associated with the handle(s).
       - `release` is used for params that are handles or pointers to handles where the function will decrement the handle's reference count, potentially leaving it in an invalid state if the reference count reaches zero.
       - `typename` is used to denote the type enum for params that are opaque pointers to values of tagged data types.
       - `bounds` is used for params that are memory objects or USM allocations. It specifies the range within the memory allocation represented by the param that will be accessed by the operation.

scripts/core/INTRO.rst

@@ -256,6 +256,33 @@ Currently, UR looks for these adapter libraries:
 
 For more information about the usage of mentioned environment variables see `Environment Variables`_ section.
 
+Mocking
+---------------------
+A mock UR adapter can be accessed for test purposes by enabling it via
+${x}LoaderConfigSetMockingEnabled.
+
+The default fallback behavior for entry points in the mock adapter is to simply
+return ``UR_RESULT_SUCCESS``. For entry points concerning handles, i.e. those
+that create a new handle or modify the reference count of an existing one, a
+dummy handle mechanism is used. This means the adapter will return generic
+handles that track a reference count, and ``Retain``/``Release`` entry points will
+function as expected when used with these handles.
+
+The behavior of the mock adapter can be customized by linking the
+``unified-runtime::mock`` library and making use of the object accessed via the
+``mock::getCallbacks()`` helper. Callbacks can be passed into this object to
+run either before or after a given entry point, or they can be set to entirely
+replace the default behavior.  Only one callback of each type (before, replace,
+after) can be set per entry point, with subsequent callbacks set in the same
+"slot" overwriting any set previously.
+
+The callback signature defined by ``ur_mock_callback_t`` takes a single
+``void *`` parameter. When calling a user callback the adapter will pack the
+entry point's parameters into the appropriate ``_params_t`` struct (e.g.
+``ur_adapter_get_params_t``) and pass a pointer to that struct into the
+callback. This allows parameters to be accessed and modified. The definitions
+for these parameter structs can be found in the main API header.
+
 Layers
 ---------------------
 UR comes with a mechanism that allows various API intercept layers to be enabled, either through the API or with an environment variable (see `Environment Variables`_).

scripts/core/adapter.yml

@@ -70,7 +70,7 @@ params:
   - type: "$x_adapter_handle_t"
     name: hAdapter
     desc: |
-          [in] Adapter handle to retain
+          [in][retain] Adapter handle to retain
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Get the last adapter specific error."

scripts/core/context.yml

@@ -80,7 +80,7 @@ params:
     - type: "$x_context_handle_t"
       name: hContext
       desc: |
-            [in] handle of the context to get a reference of.
+            [in][retain] handle of the context to get a reference of.
 --- #--------------------------------------------------------------------------
 type: enum
 desc: "Supported context info"

scripts/core/device.yml

@@ -505,7 +505,7 @@ params:
     - type: "$x_device_handle_t"
       name: hDevice
       desc: |
-            [in] handle of the device to get a reference of.
+            [in][retain] handle of the device to get a reference of.
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Releases the device handle reference indicating end of its usage"

scripts/core/event.yml

@@ -230,7 +230,7 @@ analogue:
 params:
     - type: $x_event_handle_t
       name: hEvent
-      desc: "[in] handle of the event object"
+      desc: "[in][retain] handle of the event object"
 returns:
     - $X_RESULT_ERROR_INVALID_EVENT
     - $X_RESULT_ERROR_OUT_OF_RESOURCES

scripts/core/exp-command-buffer.yml

@@ -252,7 +252,7 @@ name: RetainExp
 params:
     - type: $x_exp_command_buffer_handle_t
       name: hCommandBuffer
-      desc: "[in] Handle of the command-buffer object."
+      desc: "[in][retain] Handle of the command-buffer object."
 returns:
     - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
     - $X_RESULT_ERROR_OUT_OF_RESOURCES
@@ -879,7 +879,7 @@ name: RetainCommandExp
 params:
     - type: $x_exp_command_buffer_command_handle_t
       name: hCommand
-      desc: "[in] Handle of the command-buffer command."
+      desc: "[in][retain] Handle of the command-buffer command."
 returns:
     - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_COMMAND_HANDLE_EXP
     - $X_RESULT_ERROR_OUT_OF_RESOURCES

scripts/core/kernel.yml

@@ -292,7 +292,7 @@ details:
 params:
     - type: $x_kernel_handle_t
       name: hKernel
-      desc: "[in] handle for the Kernel to retain"
+      desc: "[in][retain] handle for the Kernel to retain"
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Release Kernel."

scripts/core/loader.yml

@@ -52,7 +52,7 @@ details:
 params:
     - type: $x_loader_config_handle_t
       name: hLoaderConfig
-      desc: "[in] loader config handle to retain"
+      desc: "[in][retain] loader config handle to retain"
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Release config handle."
@@ -188,6 +188,22 @@ params:
       desc: "[in][out][optional] pointer to data to be passed to callback."
 --- #--------------------------------------------------------------------------
 type: function
+desc: "The only adapter reported with mock enabled will be the mock adapter."
+details:
+    - "The mock adapter will default to returning $X_RESULT_SUCCESS for all entry points. It will also create and correctly reference count dummy handles where appropriate. Its behaviour can be modified by linking the mock library and using the object accessed via mock::getCallbacks()."
+class: $xLoaderConfig
+loader_only: True
+name: "SetMockingEnabled"
+decl: static
+params:
+    - type: $x_loader_config_handle_t
+      name: hLoaderConfig
+      desc: "[in] Handle to config object mocking will be enabled for."
+    - type: $x_bool_t
+      name: enable
+      desc: "[in] Handle to config object the layer will be enabled for."
+--- #--------------------------------------------------------------------------
+type: function
 desc: "Initialize the $OneApi loader"
 class: $xLoader
 loader_only: True