Improvements to align CTS and Spec for Adapter.

- Add missing error condition to urAdapterGet which is mentioned in its description.
	- Return UR_RESULT_ERROR_INVALID_SIZE when NumEntries == 0 and phAdapters != NULL.
- Check adapter reference count is updated accordingly after calls to urAdapterRetain/Release.
- Update urAdapterGetInfo tests
	- ReferenceCountNotZero to check adapter reference count is not 0.
	- ValidAdapterBackend to check UR_ADAPTER_INFO_BACKEND returns a value enumerated in ur_adapter_backend_t.

Author: martygrant

include/ur_api.h

@@ -841,6 +841,7 @@ urLoaderTearDown(
 ///     - ::UR_RESULT_ERROR_DEVICE_LOST
 ///     - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
 ///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         + `NumEntries == 0 && phAdapters != NULL`
 UR_APIEXPORT ur_result_t UR_APICALL
 urAdapterGet(
     uint32_t NumEntries,             ///< [in] the number of adapters to be added to phAdapters.

scripts/core/adapter.yml

@@ -35,13 +35,14 @@ params:
       name: phAdapters
       desc: |
             [out][optional][range(0, NumEntries)] array of handle of adapters.
-            If NumEntries is less than the number of adapters available, then $xAdapterGet shall only retrieve that number of platforms.
+            If NumEntries is less than the number of adapters available, then $xAdapterGet shall only retrieve that number of adapters.
     - type: "uint32_t*"
       name: "pNumAdapters"
       desc: |
             [out][optional] returns the total number of adapters available. 
 returns:
-    - $X_RESULT_ERROR_INVALID_SIZE
+    - $X_RESULT_ERROR_INVALID_SIZE:
+        - "`NumEntries == 0 && phAdapters != NULL`"
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Releases the adapter handle reference indicating end of its usage"

source/loader/layers/validation/ur_valddi.cpp

@@ -36,6 +36,9 @@ __urdlllocal ur_result_t UR_APICALL urAdapterGet(
     }
 
     if (getContext()->enableParameterValidation) {
+        if (NumEntries == 0 && phAdapters != NULL) {
+            return UR_RESULT_ERROR_INVALID_SIZE;
+        }
     }
 
     ur_result_t result = pfnAdapterGet(NumEntries, phAdapters, pNumAdapters);

source/loader/ur_libapi.cpp

@@ -292,6 +292,7 @@ ur_result_t UR_APICALL urLoaderTearDown(void) try {
 ///     - ::UR_RESULT_ERROR_DEVICE_LOST
 ///     - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
 ///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         + `NumEntries == 0 && phAdapters != NULL`
 ur_result_t UR_APICALL urAdapterGet(
     uint32_t
         NumEntries, ///< [in] the number of adapters to be added to phAdapters.

source/ur_api.cpp

@@ -278,6 +278,7 @@ ur_result_t UR_APICALL urLoaderTearDown(void) {
 ///     - ::UR_RESULT_ERROR_DEVICE_LOST
 ///     - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
 ///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         + `NumEntries == 0 && phAdapters != NULL`
 ur_result_t UR_APICALL urAdapterGet(
     uint32_t
         NumEntries, ///< [in] the number of adapters to be added to phAdapters.

test/conformance/adapter/urAdapterGet.cpp

@@ -18,5 +18,6 @@ TEST_F(urAdapterGetTest, InvalidNumEntries) {
     uint32_t adapter_count;
     ASSERT_SUCCESS(urAdapterGet(0, nullptr, &adapter_count));
     std::vector<ur_adapter_handle_t> adapters(adapter_count);
-    ASSERT_SUCCESS(urAdapterGet(0, adapters.data(), nullptr));
+    ASSERT_EQ(urAdapterGet(0, adapters.data(), nullptr),
+              UR_RESULT_ERROR_INVALID_SIZE);
 }

test/conformance/adapter/urAdapterGetInfo.cpp

@@ -87,3 +87,21 @@ TEST_F(urAdapterGetInfoTest, InvalidNullPointerPropSizeRet) {
         urAdapterGetInfo(adapter, UR_ADAPTER_INFO_BACKEND, 0, nullptr, nullptr),
         UR_RESULT_ERROR_INVALID_NULL_POINTER);
 }
+
+TEST_F(urAdapterGetInfoTest, ReferenceCountNotZero) {
+    uint32_t referenceCount = 0;
+
+    ASSERT_SUCCESS(urAdapterGetInfo(adapter, UR_ADAPTER_INFO_REFERENCE_COUNT,
+                                    sizeof(referenceCount), &referenceCount,
+                                    nullptr));
+    ASSERT_GT(referenceCount, 0);
+}
+
+TEST_F(urAdapterGetInfoTest, ValidAdapterBackend) {
+    ur_adapter_backend_t backend;
+    ASSERT_SUCCESS(urAdapterGetInfo(adapter, UR_ADAPTER_INFO_BACKEND,
+                                    sizeof(backend), &backend, nullptr));
+
+    ASSERT_TRUE(backend >= UR_ADAPTER_BACKEND_LEVEL_ZERO &&
+                backend <= UR_ADAPTER_BACKEND_NATIVE_CPU);
+}

test/conformance/adapter/urAdapterRelease.cpp

@@ -15,8 +15,22 @@ struct urAdapterReleaseTest : uur::runtime::urAdapterTest {
 };
 
 TEST_F(urAdapterReleaseTest, Success) {
+    uint32_t referenceCount = 0;
+
+    ASSERT_SUCCESS(urAdapterGetInfo(adapter, UR_ADAPTER_INFO_REFERENCE_COUNT,
+                                    sizeof(referenceCount), &referenceCount,
+                                    nullptr));
+    ASSERT_EQ(referenceCount, 1);
+
     ASSERT_SUCCESS(urAdapterRetain(adapter));
+    urAdapterGetInfo(adapter, UR_ADAPTER_INFO_REFERENCE_COUNT,
+                     sizeof(referenceCount), &referenceCount, nullptr);
+    ASSERT_EQ(referenceCount, 2);
+
     EXPECT_SUCCESS(urAdapterRelease(adapter));
+    urAdapterGetInfo(adapter, UR_ADAPTER_INFO_REFERENCE_COUNT,
+                     sizeof(referenceCount), &referenceCount, nullptr);
+    ASSERT_EQ(referenceCount, 1);
 }
 
 TEST_F(urAdapterReleaseTest, InvalidNullHandleAdapter) {

test/conformance/adapter/urAdapterRetain.cpp

@@ -15,8 +15,22 @@ struct urAdapterRetainTest : uur::runtime::urAdapterTest {
 };
 
 TEST_F(urAdapterRetainTest, Success) {
+    uint32_t referenceCount = 0;
+
+    ASSERT_SUCCESS(urAdapterGetInfo(adapter, UR_ADAPTER_INFO_REFERENCE_COUNT,
+                                    sizeof(referenceCount), &referenceCount,
+                                    nullptr));
+    ASSERT_EQ(referenceCount, 1);
+
     ASSERT_SUCCESS(urAdapterRetain(adapter));
+    urAdapterGetInfo(adapter, UR_ADAPTER_INFO_REFERENCE_COUNT,
+                     sizeof(referenceCount), &referenceCount, nullptr);
+    ASSERT_EQ(referenceCount, 2);
+
     EXPECT_SUCCESS(urAdapterRelease(adapter));
+    urAdapterGetInfo(adapter, UR_ADAPTER_INFO_REFERENCE_COUNT,
+                     sizeof(referenceCount), &referenceCount, nullptr);
+    ASSERT_EQ(referenceCount, 1);
 }
 
 TEST_F(urAdapterRetainTest, InvalidNullHandleAdapter) {