Improvements to align CTS and Spec for Adapter

include/ur_api.h

@@ -849,6 +849,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.
@@ -857,7 +858,7 @@ urAdapterGet(
                                      ///< 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.
+                                     ///< ::urAdapterGet shall only retrieve that number of adapters.
     uint32_t *pNumAdapters           ///< [out][optional] returns the total number of adapters available.
 );
 

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/adapters/mock/ur_mockddi.cpp

@@ -24,7 +24,7 @@ __urdlllocal ur_result_t UR_APICALL urAdapterGet(
     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.
+    ///< ::urAdapterGet shall only retrieve that number of adapters.
     uint32_t *
         pNumAdapters ///< [out][optional] returns the total number of adapters available.
     ) try {

source/loader/layers/tracing/ur_trcddi.cpp

@@ -26,7 +26,7 @@ __urdlllocal ur_result_t UR_APICALL urAdapterGet(
     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.
+    ///< ::urAdapterGet shall only retrieve that number of adapters.
     uint32_t *
         pNumAdapters ///< [out][optional] returns the total number of adapters available.
 ) {

source/loader/layers/validation/ur_valddi.cpp

@@ -25,7 +25,7 @@ __urdlllocal ur_result_t UR_APICALL urAdapterGet(
     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.
+    ///< ::urAdapterGet shall only retrieve that number of adapters.
     uint32_t *
         pNumAdapters ///< [out][optional] returns the total number of adapters available.
 ) {
@@ -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_ldrddi.cpp

@@ -24,7 +24,7 @@ __urdlllocal ur_result_t UR_APICALL urAdapterGet(
     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.
+    ///< ::urAdapterGet shall only retrieve that number of adapters.
     uint32_t *
         pNumAdapters ///< [out][optional] returns the total number of adapters available.
 ) {

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.
@@ -301,7 +302,7 @@ ur_result_t UR_APICALL urAdapterGet(
     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.
+    ///< ::urAdapterGet shall only retrieve that number of adapters.
     uint32_t *
         pNumAdapters ///< [out][optional] returns the total number of adapters available.
     ) try {

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.
@@ -287,7 +288,7 @@ ur_result_t UR_APICALL urAdapterGet(
     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.
+    ///< ::urAdapterGet shall only retrieve that number of adapters.
     uint32_t *
         pNumAdapters ///< [out][optional] returns the total number of adapters available.
 ) {

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,19 @@ struct urAdapterReleaseTest : uur::runtime::urAdapterTest {
 };
 
 TEST_F(urAdapterReleaseTest, Success) {
-    ASSERT_SUCCESS(urAdapterRetain(adapter));
+    uint32_t referenceCountBefore = 0;
+
+    ASSERT_SUCCESS(urAdapterGetInfo(adapter, UR_ADAPTER_INFO_REFERENCE_COUNT,
+                                    sizeof(referenceCountBefore),
+                                    &referenceCountBefore, nullptr));
+
+    uint32_t referenceCountAfter = 0;
     EXPECT_SUCCESS(urAdapterRelease(adapter));
+    ASSERT_SUCCESS(urAdapterGetInfo(adapter, UR_ADAPTER_INFO_REFERENCE_COUNT,
+                                    sizeof(referenceCountAfter),
+                                    &referenceCountAfter, nullptr));
+
+    ASSERT_LE(referenceCountAfter, referenceCountBefore);
 }
 
 TEST_F(urAdapterReleaseTest, InvalidNullHandleAdapter) {

test/conformance/adapter/urAdapterRetain.cpp

@@ -15,8 +15,19 @@ struct urAdapterRetainTest : uur::runtime::urAdapterTest {
 };
 
 TEST_F(urAdapterRetainTest, Success) {
-    ASSERT_SUCCESS(urAdapterRetain(adapter));
-    EXPECT_SUCCESS(urAdapterRelease(adapter));
+    uint32_t referenceCountBefore = 0;
+
+    ASSERT_SUCCESS(urAdapterGetInfo(adapter, UR_ADAPTER_INFO_REFERENCE_COUNT,
+                                    sizeof(referenceCountBefore),
+                                    &referenceCountBefore, nullptr));
+
+    uint32_t referenceCountAfter = 0;
+    EXPECT_SUCCESS(urAdapterRetain(adapter));
+    ASSERT_SUCCESS(urAdapterGetInfo(adapter, UR_ADAPTER_INFO_REFERENCE_COUNT,
+                                    sizeof(referenceCountAfter),
+                                    &referenceCountAfter, nullptr));
+
+    ASSERT_GT(referenceCountAfter, referenceCountBefore);
 }
 
 TEST_F(urAdapterRetainTest, InvalidNullHandleAdapter) {