Implement layer to allow adapter mocking.

include/ur_print.h

@@ -98,6 +98,22 @@ UR_APIEXPORT ur_result_t UR_APICALL urPrintLoaderConfigInfo(enum ur_loader_confi
 ///         - `buff_size < out_size`
 UR_APIEXPORT ur_result_t UR_APICALL urPrintCodeLocation(const struct ur_code_location_t params, char *buffer, const size_t buff_size, size_t *out_size);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_callback_override_mode_t enum
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL urPrintCallbackOverrideMode(enum ur_callback_override_mode_t value, char *buffer, const size_t buff_size, size_t *out_size);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_mock_callback_properties_t struct
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL urPrintMockCallbackProperties(const struct ur_mock_callback_properties_t params, char *buffer, const size_t buff_size, size_t *out_size);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print ur_adapter_info_t enum
 /// @returns
@@ -1074,6 +1090,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_mock_callbacks_params_t struct
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL urPrintLoaderConfigSetMockCallbacksParams(const struct ur_loader_config_set_mock_callbacks_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

@@ -227,6 +227,8 @@ inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct
 inline std::ostream &operator<<(std::ostream &os, enum ur_device_init_flag_t value);
 inline std::ostream &operator<<(std::ostream &os, enum ur_loader_config_info_t value);
 inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_code_location_t params);
+inline std::ostream &operator<<(std::ostream &os, enum ur_callback_override_mode_t value);
+inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_mock_callback_properties_t params);
 inline std::ostream &operator<<(std::ostream &os, enum ur_adapter_info_t value);
 inline std::ostream &operator<<(std::ostream &os, enum ur_adapter_backend_t value);
 inline std::ostream &operator<<(std::ostream &os, enum ur_platform_info_t value);
@@ -932,6 +934,9 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_function_t value) {
     case UR_FUNCTION_KERNEL_GET_SUGGESTED_LOCAL_WORK_SIZE:
         os << "UR_FUNCTION_KERNEL_GET_SUGGESTED_LOCAL_WORK_SIZE";
         break;
+    case UR_FUNCTION_LOADER_CONFIG_SET_MOCK_CALLBACKS:
+        os << "UR_FUNCTION_LOADER_CONFIG_SET_MOCK_CALLBACKS";
+        break;
     default:
         os << "unknown enumerator";
         break;
@@ -1049,6 +1054,9 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_structure_type_t value
     case UR_STRUCTURE_TYPE_USM_ALLOC_LOCATION_DESC:
         os << "UR_STRUCTURE_TYPE_USM_ALLOC_LOCATION_DESC";
         break;
+    case UR_STRUCTURE_TYPE_MOCK_CALLBACK_PROPERTIES:
+        os << "UR_STRUCTURE_TYPE_MOCK_CALLBACK_PROPERTIES";
+        break;
     case UR_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_DESC:
         os << "UR_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_DESC";
         break;
@@ -1277,6 +1285,11 @@ inline ur_result_t printStruct(std::ostream &os, const void *ptr) {
         printPtr(os, pstruct);
     } break;
 
+    case UR_STRUCTURE_TYPE_MOCK_CALLBACK_PROPERTIES: {
+        const ur_mock_callback_properties_t *pstruct = (const ur_mock_callback_properties_t *)ptr;
+        printPtr(os, pstruct);
+    } break;
+
     case UR_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_DESC: {
         const ur_exp_command_buffer_desc_t *pstruct = (const ur_exp_command_buffer_desc_t *)ptr;
         printPtr(os, pstruct);
@@ -1850,6 +1863,63 @@ inline std::ostream &operator<<(std::ostream &os, const struct ur_code_location_
     return os;
 }
 ///////////////////////////////////////////////////////////////////////////////
+/// @brief Print operator for the ur_callback_override_mode_t type
+/// @returns
+///     std::ostream &
+inline std::ostream &operator<<(std::ostream &os, enum ur_callback_override_mode_t value) {
+    switch (value) {
+    case UR_CALLBACK_OVERRIDE_MODE_BEFORE:
+        os << "UR_CALLBACK_OVERRIDE_MODE_BEFORE";
+        break;
+    case UR_CALLBACK_OVERRIDE_MODE_REPLACE:
+        os << "UR_CALLBACK_OVERRIDE_MODE_REPLACE";
+        break;
+    case UR_CALLBACK_OVERRIDE_MODE_AFTER:
+        os << "UR_CALLBACK_OVERRIDE_MODE_AFTER";
+        break;
+    default:
+        os << "unknown enumerator";
+        break;
+    }
+    return os;
+}
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print operator for the ur_mock_callback_properties_t type
+/// @returns
+///     std::ostream &
+inline std::ostream &operator<<(std::ostream &os, const struct ur_mock_callback_properties_t params) {
+    os << "(struct ur_mock_callback_properties_t){";
+
+    os << ".stype = ";
+
+    os << (params.stype);
+
+    os << ", ";
+    os << ".pNext = ";
+
+    ur::details::printStruct(os,
+                             (params.pNext));
+
+    os << ", ";
+    os << ".name = ";
+
+    ur::details::printPtr(os,
+                          (params.name));
+
+    os << ", ";
+    os << ".mode = ";
+
+    os << (params.mode);
+
+    os << ", ";
+    os << ".pCallback = ";
+
+    os << (params.pCallback);
+
+    os << "}";
+    return os;
+}
+///////////////////////////////////////////////////////////////////////////////
 /// @brief Print operator for the ur_adapter_info_t type
 /// @returns
 ///     std::ostream &
@@ -10101,6 +10171,26 @@ inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct
     return os;
 }
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print operator for the ur_loader_config_set_mock_callbacks_params_t type
+/// @returns
+///     std::ostream &
+inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_loader_config_set_mock_callbacks_params_t *params) {
+
+    os << ".hLoaderConfig = ";
+
+    ur::details::printPtr(os,
+                          *(params->phLoaderConfig));
+
+    os << ", ";
+    os << ".pCallbackProperties = ";
+
+    ur::details::printPtr(os,
+                          *(params->ppCallbackProperties));
+
+    return os;
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print operator for the ur_platform_get_params_t type
 /// @returns
@@ -17042,6 +17132,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_MOCK_CALLBACKS: {
+        os << (const struct ur_loader_config_set_mock_callbacks_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 destroy any backing memory associated with the handle(s)
       - `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,38 @@ 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 the ``MOCK``
+layer as described below. When the mock layer is enabled, calls to the API will
+still be intercepted by other layers (e.g. validation, tracing), but they will
+stop short of the loader - the call chain will end in either a generic fallback
+behavior defined by the mock layer itself, or a user defined replacement
+callback.
+
+The default fallback behavior for entry points in the mock layer 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 layer will return generic
+handles that track a reference count, and ``Retain``/``Release`` entry points will
+function as expected when used with these handles.
+
+During global setup the behavior of the mock layer can be customized by setting
+callbacks via ${x}LoaderConfigSetMockCallbacks. This entry point accepts a ``pNext``
+chain of structs, with each registering a callback with a given entry point in
+the API. Callbacks can be registered to be called ``BEFORE`` or ``AFTER`` the
+generic implementation, or they can be registered to entirely ``REPLACE`` it. A
+given entry point can only have one of each kind of callback associated with
+it, multiple structs with the same function/mode combination will override
+eachother.
+
+The callback signature defined by ``${x}_mock_callback_t`` takes a single
+``void *`` parameter. When calling a user callback the layer 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`_).
@@ -278,6 +310,8 @@ Layers currently included with the runtime are as follows:
      - Enables the XPTI tracing layer, see Tracing_ for more detail.
    * - UR_LAYER_ASAN \| UR_LAYER_MSAN \| UR_LAYER_TSAN
      - Enables the device-side sanitizer layer, see Sanitizers_ for more detail.
+   * - UR_LAYER_MOCK
+     - Enables adapter mocking for test purposes. Similar behavior to the null adapter except entry points can be overridden or instrumented with callbacks. See Mocking_ for more detail.
 
 Environment Variables
 ---------------------

scripts/core/adapter.yml

@@ -56,7 +56,7 @@ params:
   - type: "$x_adapter_handle_t"
     name: hAdapter
     desc: |
-          [in] Adapter handle to release
+          [in][release] Adapter handle to release
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Get a reference to the adapter handle."
@@ -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"
@@ -129,7 +129,7 @@ params:
     - type: "$x_context_handle_t"
       name: hContext
       desc: |
-            [in] handle of the context to release.
+            [in][release] handle of the context to release.
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Retrieves various information about context"

scripts/core/device.yml

@@ -503,7 +503,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"
@@ -522,7 +522,7 @@ params:
     - type: "$x_device_handle_t"
       name: hDevice
       desc: |
-            [in] handle of the device to release.
+            [in][release] handle of the device to release.
 --- #--------------------------------------------------------------------------
 type: enum
 desc: "Device affinity domain"

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
@@ -246,7 +246,7 @@ analogue:
 params:
     - type: $x_event_handle_t
       name: hEvent
-      desc: "[in] handle of the event object"
+      desc: "[in][release] handle of the event object"
 returns:
     - $X_RESULT_ERROR_INVALID_EVENT
     - $X_RESULT_ERROR_OUT_OF_RESOURCES

scripts/core/exp-bindless-images.yml

@@ -700,7 +700,7 @@ params:
       desc: "[in] handle of the device object"
     - type: $x_exp_interop_mem_handle_t
       name: hInteropMem
-      desc: "[in] handle of interop memory to be freed"
+      desc: "[in][release] handle of interop memory to be freed"
 returns:
     - $X_RESULT_ERROR_INVALID_CONTEXT
     - $X_RESULT_ERROR_INVALID_VALUE

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
@@ -265,7 +265,7 @@ name: ReleaseExp
 params:
     - type: $x_exp_command_buffer_handle_t
       name: hCommandBuffer
-      desc: "[in] Handle of the command-buffer object."
+      desc: "[in][release] Handle of the command-buffer object."
 returns:
     - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
     - $X_RESULT_ERROR_OUT_OF_RESOURCES
@@ -893,7 +893,7 @@ name: ReleaseCommandExp
 params:
     - type: $x_exp_command_buffer_command_handle_t
       name: hCommand
-      desc: "[in] Handle of the command-buffer command."
+      desc: "[in][release] 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."
@@ -309,7 +309,7 @@ details:
 params:
     - type: $x_kernel_handle_t
       name: hKernel
-      desc: "[in] handle for the Kernel to release"
+      desc: "[in][release] handle for the Kernel to release"
 --- #--------------------------------------------------------------------------
 type: struct
 desc: "Properties for for $xKernelSetArgPointer."