Re-do docs and testing

Author: aarongreig

scripts/core/INTRO.rst

@@ -258,30 +258,26 @@ For more information about the usage of mentioned environment variables see `Env
 
 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
+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 layer will return generic
+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.
 
-During global setup the behavior of the mock layer can be customized by setting
-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 behavior of the mock adapter can be customized by linking the
+``unified-runtime::mock`` library and making use of the ``mock::callbacks``
+object. 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 layer will pack the
+``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
@@ -309,8 +305,6 @@ 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/templates/mockddi.cpp.mako

@@ -9,7 +9,7 @@ from templates import helper as th
     X=x.upper()
 %>/*
  *
- * Copyright (C) 2019-2024 Intel Corporation
+ * Copyright (C) 2024 Intel Corporation
  *
  * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
  * See LICENSE.TXT

source/CMakeLists.txt

@@ -8,6 +8,5 @@ add_definitions(-DUR_VALIDATION_LAYER_SUPPORTED_VERSION="${PROJECT_VERSION_MAJOR
 
 add_subdirectory(common)
 add_subdirectory(loader)
-#add_subdirectory(layers)
 add_subdirectory(mock)
 add_subdirectory(adapters)

source/loader/CMakeLists.txt

@@ -159,6 +159,7 @@ if(UR_ENABLE_SANITIZER)
     )
 endif()
 
+
 # link validation backtrace dependencies
 if(UNIX)
     find_package(Libbacktrace)

source/loader/ur_lib.cpp

@@ -225,6 +225,9 @@ urLoaderConfigSetCodeLocationCallback(ur_loader_config_handle_t hLoaderConfig,
 ur_result_t
 urLoaderConfigSetMockingEnabled(ur_loader_config_handle_t hLoaderConfig,
                                 ur_bool_t enable) {
+    if (!hLoaderConfig) {
+        return UR_RESULT_ERROR_INVALID_NULL_HANDLE;
+    }
     hLoaderConfig->enableMock = enable;
     return UR_RESULT_SUCCESS;
 }

test/CMakeLists.txt

@@ -26,6 +26,7 @@ add_subdirectory(adapters)
 add_subdirectory(usm)
 add_subdirectory(layers)
 add_subdirectory(unit)
+add_subdirectory(mock)
 if(UR_BUILD_TOOLS)
   add_subdirectory(tools)
 endif()

test/layers/mock/CMakeLists.txt renamed to test/mock/CMakeLists.txt

@@ -11,13 +11,11 @@ target_link_libraries(${MOCK_TEST_NAME}
   ${PROJECT_NAME}::loader
   ${PROJECT_NAME}::headers
   ${PROJECT_NAME}::testing
+  ${PROJECT_NAME}::mock
   GTest::gtest_main)
 
 add_test(NAME ${MOCK_TEST_NAME}
     COMMAND ${MOCK_TEST_NAME}
     WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
 
 set_tests_properties(${MOCK_TEST_NAME} PROPERTIES LABELS "mock")
-
-set_property(TEST ${MOCK_TEST_NAME} PROPERTY ENVIRONMENT
-    "UR_ADAPTERS_FORCE_LOAD=\"$<TARGET_FILE:ur_adapter_mock>\"")

test/layers/mock/mock.cpp renamed to test/mock/mock.cpp

@@ -14,41 +14,17 @@
 #include <gtest/gtest.h>
 #include <ur_api.h>
 
-TEST(Mock, NullProperties) {
-    uur::raii::LoaderConfig loader_config;
-    ASSERT_EQ(urLoaderConfigCreate(loader_config.ptr()), UR_RESULT_SUCCESS);
-    ASSERT_EQ(urLoaderConfigSetMockCallbacks(loader_config, nullptr),
-              UR_RESULT_ERROR_INVALID_NULL_POINTER);
-}
-
-TEST(Mock, NullCallback) {
-    uur::raii::LoaderConfig loader_config;
-    ASSERT_EQ(urLoaderConfigCreate(loader_config.ptr()), UR_RESULT_SUCCESS);
-
-    ur_mock_callback_properties_t callback_properties = {
-        UR_STRUCTURE_TYPE_MOCK_CALLBACK_PROPERTIES, nullptr, "urAdapterGet",
-        UR_CALLBACK_OVERRIDE_MODE_REPLACE, nullptr};
-
-    ASSERT_EQ(
-        urLoaderConfigSetMockCallbacks(loader_config, &callback_properties),
-        UR_RESULT_ERROR_INVALID_NULL_POINTER);
-}
-
-ur_result_t generic_callback(void *) { return UR_RESULT_SUCCESS; }
+#include <ur_mock_helpers.hpp>
 
 TEST(Mock, NullHandle) {
-    ur_mock_callback_properties_t callback_properties = {
-        UR_STRUCTURE_TYPE_MOCK_CALLBACK_PROPERTIES, nullptr, "urAdapterGet",
-        UR_CALLBACK_OVERRIDE_MODE_REPLACE, &generic_callback};
-
-    ASSERT_EQ(urLoaderConfigSetMockCallbacks(nullptr, &callback_properties),
+    ASSERT_EQ(urLoaderConfigSetMockingEnabled(nullptr, true),
               UR_RESULT_ERROR_INVALID_NULL_HANDLE);
 }
 
 TEST(Mock, DefaultBehavior) {
     uur::raii::LoaderConfig loader_config;
     ASSERT_EQ(urLoaderConfigCreate(loader_config.ptr()), UR_RESULT_SUCCESS);
-    ASSERT_EQ(urLoaderConfigEnableLayer(loader_config, "UR_LAYER_MOCK"),
+    ASSERT_EQ(urLoaderConfigSetMockingEnabled(loader_config, true),
               UR_RESULT_SUCCESS);
     ASSERT_EQ(urLoaderInit(0, loader_config), UR_RESULT_SUCCESS);
 
@@ -108,32 +84,20 @@ ur_result_t afterUrAdapterGet(void *pParams) {
 TEST(Mock, Callbacks) {
     uur::raii::LoaderConfig loader_config;
     ASSERT_EQ(urLoaderConfigCreate(loader_config.ptr()), UR_RESULT_SUCCESS);
+    ASSERT_EQ(urLoaderConfigSetMockingEnabled(loader_config, true),
+              UR_RESULT_SUCCESS);
+    ASSERT_EQ(urLoaderInit(0, loader_config), UR_RESULT_SUCCESS);
 
     // This callback is set up to check *phAdapters is still the pre-call
     // init value we set below
-    ur_mock_callback_properties_t adapterGetBeforeProperties = {
-        UR_STRUCTURE_TYPE_MOCK_CALLBACK_PROPERTIES, nullptr, "urAdapterGet",
-        UR_CALLBACK_OVERRIDE_MODE_BEFORE, &beforeUrAdapterGet};
+    mock::callbacks.set_before_callback("urAdapterGet", &beforeUrAdapterGet);
 
     // This callback is set up to return a distinct test value in phAdapters
     // rather than the default generic handle
-    ur_mock_callback_properties_t adapterGetReplaceProperties = {
-        UR_STRUCTURE_TYPE_MOCK_CALLBACK_PROPERTIES, &adapterGetBeforeProperties,
-        "urAdapterGet", UR_CALLBACK_OVERRIDE_MODE_REPLACE,
-        &replaceUrAdapterGet};
+    mock::callbacks.set_replace_callback("urAdapterGet", &replaceUrAdapterGet);
 
     // This callback is set up to check our replace callback did its job
-    ur_mock_callback_properties_t adapterGetAfterProperties = {
-        UR_STRUCTURE_TYPE_MOCK_CALLBACK_PROPERTIES,
-        &adapterGetReplaceProperties, "urAdapterGet",
-        UR_CALLBACK_OVERRIDE_MODE_AFTER, &afterUrAdapterGet};
-
-    ASSERT_EQ(urLoaderConfigSetMockCallbacks(loader_config,
-                                             &adapterGetAfterProperties),
-              UR_RESULT_SUCCESS);
-    ASSERT_EQ(urLoaderConfigEnableLayer(loader_config, "UR_LAYER_MOCK"),
-              UR_RESULT_SUCCESS);
-    ASSERT_EQ(urLoaderInit(0, loader_config), UR_RESULT_SUCCESS);
+    mock::callbacks.set_after_callback("urAdapterGet", &afterUrAdapterGet);
 
     ur_adapter_handle_t adapter =
         reinterpret_cast<ur_adapter_handle_t>(0xF00DCAFE);