Merge pull request #1128 from aarongreig/aaron/clarifyQueueInfoSize

Clarify spec for QUEUE_INFO_SIZE and change testing for it accordingly.

Author: kbenzie

include/ur_api.h

@@ -5302,7 +5302,9 @@ typedef enum ur_queue_info_t {
                                        ///< The reference count returned should be considered immediately stale.
                                        ///< It is unsuitable for general use in applications. This feature is
                                        ///< provided for identifying memory leaks.
-    UR_QUEUE_INFO_SIZE = 5,            ///< [uint32_t] The size of the queue
+    UR_QUEUE_INFO_SIZE = 5,            ///< [uint32_t] The size of the queue on the device. Only a valid query
+                                       ///< if the queue was created with the `ON_DEVICE` queue flag, otherwise
+                                       ///< `::urQueueGetInfo` will return `::UR_RESULT_ERROR_INVALID_QUEUE`.
     UR_QUEUE_INFO_EMPTY = 6,           ///< [::ur_bool_t] return true if the queue was empty at the time of the
                                        ///< query
     /// @cond
@@ -5317,7 +5319,8 @@ typedef uint32_t ur_queue_flags_t;
 typedef enum ur_queue_flag_t {
     UR_QUEUE_FLAG_OUT_OF_ORDER_EXEC_MODE_ENABLE = UR_BIT(0), ///< Enable/disable out of order execution
     UR_QUEUE_FLAG_PROFILING_ENABLE = UR_BIT(1),              ///< Enable/disable profiling
-    UR_QUEUE_FLAG_ON_DEVICE = UR_BIT(2),                     ///< Is a device queue
+    UR_QUEUE_FLAG_ON_DEVICE = UR_BIT(2),                     ///< Is a device queue. If this is enabled `OUT_OF_ORDER_EXEC_MODE_ENABLE`
+                                                             ///< must also be enabled.
     UR_QUEUE_FLAG_ON_DEVICE_DEFAULT = UR_BIT(3),             ///< Is the default queue for a device
     UR_QUEUE_FLAG_DISCARD_EVENTS = UR_BIT(4),                ///< Events will be discarded
     UR_QUEUE_FLAG_PRIORITY_LOW = UR_BIT(5),                  ///< Low priority queue
@@ -5362,7 +5365,7 @@ typedef enum ur_queue_flag_t {
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `propSize != 0 && pPropValue == NULL`
 ///         + `pPropValue == NULL && pPropSizeRet == NULL`
-///     - ::UR_RESULT_ERROR_INVALID_QUEUE
+///     - ::UR_RESULT_ERROR_INVALID_QUEUE - "If `hQueue` isn't a valid queue handle or if `propName` isn't supported by `hQueue`."
 ///     - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
 ///     - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
 UR_APIEXPORT ur_result_t UR_APICALL

scripts/core/queue.yml

@@ -32,7 +32,10 @@ etors:
             The reference count returned should be considered immediately stale. 
             It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.
     - name: SIZE
-      desc: "[uint32_t] The size of the queue"
+      desc: |
+            [uint32_t] The size of the queue on the device. Only a valid query
+            if the queue was created with the `ON_DEVICE` queue flag, otherwise
+            `$xQueueGetInfo` will return `$X_RESULT_ERROR_INVALID_QUEUE`.
     - name: EMPTY
       desc: "[$x_bool_t] return true if the queue was empty at the time of the query"
 --- #--------------------------------------------------------------------------
@@ -49,7 +52,7 @@ etors:
       desc: "Enable/disable profiling"
     - name: ON_DEVICE
       value: "$X_BIT(2)"
-      desc: "Is a device queue"
+      desc: "Is a device queue. If this is enabled `OUT_OF_ORDER_EXEC_MODE_ENABLE` must also be enabled."
     - name: ON_DEVICE_DEFAULT
       value: "$X_BIT(3)"
       desc: "Is the default queue for a device"
@@ -108,6 +111,7 @@ returns:
         - "`propSize != 0 && pPropValue == NULL`"
         - "`pPropValue == NULL && pPropSizeRet == NULL`"
     - $X_RESULT_ERROR_INVALID_QUEUE
+        - "If `hQueue` isn't a valid queue handle or if `propName` isn't supported by `hQueue`."
     - $X_RESULT_ERROR_OUT_OF_HOST_MEMORY
     - $X_RESULT_ERROR_OUT_OF_RESOURCES
 --- #--------------------------------------------------------------------------

source/adapters/cuda/device.cpp

@@ -569,10 +569,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urDeviceGetInfo(ur_device_handle_t hDevice,
         ur_queue_flag_t(UR_QUEUE_FLAG_OUT_OF_ORDER_EXEC_MODE_ENABLE |
                         UR_QUEUE_FLAG_PROFILING_ENABLE));
   case UR_DEVICE_INFO_QUEUE_ON_DEVICE_PROPERTIES: {
-    // The mandated minimum capability:
-    ur_queue_flags_t Capability = UR_QUEUE_FLAG_PROFILING_ENABLE |
-                                  UR_QUEUE_FLAG_OUT_OF_ORDER_EXEC_MODE_ENABLE;
-    return ReturnValue(Capability);
+    return ReturnValue(0);
   }
   case UR_DEVICE_INFO_QUEUE_ON_HOST_PROPERTIES: {
     // The mandated minimum capability:

source/adapters/hip/device.cpp

@@ -478,10 +478,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urDeviceGetInfo(ur_device_handle_t hDevice,
     return ReturnValue(Capability);
   }
   case UR_DEVICE_INFO_QUEUE_ON_DEVICE_PROPERTIES: {
-    // The mandated minimum capability:
-    ur_queue_flags_t Capability = UR_QUEUE_FLAG_PROFILING_ENABLE |
-                                  UR_QUEUE_FLAG_OUT_OF_ORDER_EXEC_MODE_ENABLE;
-    return ReturnValue(Capability);
+    return ReturnValue(0);
   }
   case UR_DEVICE_INFO_QUEUE_ON_HOST_PROPERTIES:
   case UR_DEVICE_INFO_QUEUE_PROPERTIES: {

source/adapters/opencl/common.cpp

@@ -87,6 +87,8 @@ ur_result_t mapCLErrorToUR(cl_int Result) {
     return UR_RESULT_ERROR_DEVICE_NOT_AVAILABLE;
   case CL_INVALID_KERNEL_ARGS:
     return UR_RESULT_ERROR_INVALID_KERNEL_ARGS;
+  case CL_INVALID_COMMAND_QUEUE:
+    return UR_RESULT_ERROR_INVALID_QUEUE;
   default:
     return UR_RESULT_ERROR_UNKNOWN;
   }

source/loader/ur_libapi.cpp

@@ -4189,7 +4189,7 @@ ur_result_t UR_APICALL urKernelGetSuggestedLocalWorkSize(
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `propSize != 0 && pPropValue == NULL`
 ///         + `pPropValue == NULL && pPropSizeRet == NULL`
-///     - ::UR_RESULT_ERROR_INVALID_QUEUE
+///     - ::UR_RESULT_ERROR_INVALID_QUEUE - "If `hQueue` isn't a valid queue handle or if `propName` isn't supported by `hQueue`."
 ///     - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
 ///     - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
 ur_result_t UR_APICALL urQueueGetInfo(

source/ur_api.cpp

@@ -3556,7 +3556,7 @@ ur_result_t UR_APICALL urKernelGetSuggestedLocalWorkSize(
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `propSize != 0 && pPropValue == NULL`
 ///         + `pPropValue == NULL && pPropSizeRet == NULL`
-///     - ::UR_RESULT_ERROR_INVALID_QUEUE
+///     - ::UR_RESULT_ERROR_INVALID_QUEUE - "If `hQueue` isn't a valid queue handle or if `propName` isn't supported by `hQueue`."
 ///     - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
 ///     - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
 ur_result_t UR_APICALL urQueueGetInfo(

test/conformance/queue/queue_adapter_hip.match

@@ -1,2 +0,0 @@
-urQueueGetInfoTestWithInfoParam.Success/AMD_HIP_BACKEND___{{.*}}___UR_QUEUE_INFO_DEVICE_DEFAULT
-urQueueGetInfoTestWithInfoParam.Success/AMD_HIP_BACKEND___{{.*}}___UR_QUEUE_INFO_SIZE

test/conformance/queue/queue_adapter_native_cpu.match

@@ -26,11 +26,16 @@ urQueueFinishTest.Success/SYCL_NATIVE_CPU___SYCL_Native_CPU_
 urQueueFlushTest.Success/SYCL_NATIVE_CPU___SYCL_Native_CPU_
 urQueueGetInfoTestWithInfoParam.Success/SYCL_NATIVE_CPU___SYCL_Native_CPU___UR_QUEUE_INFO_CONTEXT
 urQueueGetInfoTestWithInfoParam.Success/SYCL_NATIVE_CPU___SYCL_Native_CPU___UR_QUEUE_INFO_DEVICE
-urQueueGetInfoTestWithInfoParam.Success/SYCL_NATIVE_CPU___SYCL_Native_CPU___UR_QUEUE_INFO_DEVICE_DEFAULT
 urQueueGetInfoTestWithInfoParam.Success/SYCL_NATIVE_CPU___SYCL_Native_CPU___UR_QUEUE_INFO_FLAGS
 urQueueGetInfoTestWithInfoParam.Success/SYCL_NATIVE_CPU___SYCL_Native_CPU___UR_QUEUE_INFO_REFERENCE_COUNT
-urQueueGetInfoTestWithInfoParam.Success/SYCL_NATIVE_CPU___SYCL_Native_CPU___UR_QUEUE_INFO_SIZE
 urQueueGetInfoTestWithInfoParam.Success/SYCL_NATIVE_CPU___SYCL_Native_CPU___UR_QUEUE_INFO_EMPTY
+urQueueGetInfoDeviceQueueTestWithInfoParam.Success/SYCL_NATIVE_CPU___SYCL_Native_CPU___UR_QUEUE_INFO_CONTEXT
+urQueueGetInfoDeviceQueueTestWithInfoParam.Success/SYCL_NATIVE_CPU___SYCL_Native_CPU___UR_QUEUE_INFO_DEVICE
+urQueueGetInfoDeviceQueueTestWithInfoParam.Success/SYCL_NATIVE_CPU___SYCL_Native_CPU___UR_QUEUE_INFO_DEVICE_DEFAULT
+urQueueGetInfoDeviceQueueTestWithInfoParam.Success/SYCL_NATIVE_CPU___SYCL_Native_CPU___UR_QUEUE_INFO_FLAGS
+urQueueGetInfoDeviceQueueTestWithInfoParam.Success/SYCL_NATIVE_CPU___SYCL_Native_CPU___UR_QUEUE_INFO_REFERENCE_COUNT
+urQueueGetInfoDeviceQueueTestWithInfoParam.Success/SYCL_NATIVE_CPU___SYCL_Native_CPU___UR_QUEUE_INFO_SIZE
+urQueueGetInfoDeviceQueueTestWithInfoParam.Success/SYCL_NATIVE_CPU___SYCL_Native_CPU___UR_QUEUE_INFO_EMPTY
 urQueueGetInfoTest.InvalidSizeSmall/SYCL_NATIVE_CPU___SYCL_Native_CPU_
 urQueueRetainTest.Success/SYCL_NATIVE_CPU___SYCL_Native_CPU_
 urQueueReleaseTest.Success/SYCL_NATIVE_CPU___SYCL_Native_CPU_

test/conformance/queue/queue_adapter_opencl.match

@@ -1,2 +0,0 @@
-urQueueGetInfoTestWithInfoParam.Success/Intel_R__OpenCL___{{.*}}___UR_QUEUE_INFO_DEVICE_DEFAULT
-urQueueGetInfoTestWithInfoParam.Success/Intel_R__OpenCL___{{.*}}___UR_QUEUE_INFO_SIZE

test/conformance/queue/urQueueGetInfo.cpp

@@ -20,10 +20,9 @@ using urQueueGetInfoTestWithInfoParam =
 
 UUR_TEST_SUITE_P(urQueueGetInfoTestWithInfoParam,
                  ::testing::Values(UR_QUEUE_INFO_CONTEXT, UR_QUEUE_INFO_DEVICE,
-                                   UR_QUEUE_INFO_DEVICE_DEFAULT,
                                    UR_QUEUE_INFO_FLAGS,
                                    UR_QUEUE_INFO_REFERENCE_COUNT,
-                                   UR_QUEUE_INFO_SIZE, UR_QUEUE_INFO_EMPTY),
+                                   UR_QUEUE_INFO_EMPTY),
                  uur::deviceTestWithParamPrinter<ur_queue_info_t>);
 
 TEST_P(urQueueGetInfoTestWithInfoParam, Success) {
@@ -70,6 +69,65 @@ TEST_P(urQueueGetInfoTestWithInfoParam, Success) {
     }
 }
 
+struct urQueueGetInfoDeviceQueueTestWithInfoParam
+    : public uur::urContextTestWithParam<ur_queue_info_t> {
+    void SetUp() {
+        urContextTestWithParam<ur_queue_info_t>::SetUp();
+        ur_queue_flags_t deviceQueueCapabilities;
+        ASSERT_SUCCESS(
+            urDeviceGetInfo(device, UR_DEVICE_INFO_QUEUE_ON_DEVICE_PROPERTIES,
+                            sizeof(deviceQueueCapabilities),
+                            &deviceQueueCapabilities, nullptr));
+        if (!deviceQueueCapabilities) {
+            GTEST_SKIP() << "Queue on device is not supported.";
+        }
+        ASSERT_SUCCESS(
+            urQueueCreate(context, device, &queueProperties, &queue));
+    }
+
+    void TearDown() {
+        if (queue) {
+            ASSERT_SUCCESS(urQueueRelease(queue));
+        }
+        urContextTestWithParam<ur_queue_info_t>::TearDown();
+    }
+
+    ur_queue_handle_t queue = nullptr;
+    ur_queue_properties_t queueProperties = {
+        UR_STRUCTURE_TYPE_QUEUE_PROPERTIES, nullptr,
+        UR_QUEUE_FLAG_ON_DEVICE | UR_QUEUE_FLAG_ON_DEVICE_DEFAULT |
+            UR_QUEUE_FLAG_OUT_OF_ORDER_EXEC_MODE_ENABLE};
+};
+
+UUR_TEST_SUITE_P(urQueueGetInfoDeviceQueueTestWithInfoParam,
+                 ::testing::Values(UR_QUEUE_INFO_CONTEXT, UR_QUEUE_INFO_DEVICE,
+                                   UR_QUEUE_INFO_DEVICE_DEFAULT,
+                                   UR_QUEUE_INFO_FLAGS,
+                                   UR_QUEUE_INFO_REFERENCE_COUNT,
+                                   UR_QUEUE_INFO_SIZE, UR_QUEUE_INFO_EMPTY),
+                 uur::deviceTestWithParamPrinter<ur_queue_info_t>);
+
+TEST_P(urQueueGetInfoDeviceQueueTestWithInfoParam, Success) {
+    ur_queue_info_t info_type = getParam();
+    size_t size = 0;
+    auto result = urQueueGetInfo(queue, info_type, 0, nullptr, &size);
+
+    if (result == UR_RESULT_SUCCESS) {
+        ASSERT_NE(size, 0);
+
+        if (const auto expected_size = queue_info_size_map.find(info_type);
+            expected_size != queue_info_size_map.end()) {
+            ASSERT_EQ(expected_size->second, size);
+        }
+
+        std::vector<uint8_t> data(size);
+        ASSERT_SUCCESS(
+            urQueueGetInfo(queue, info_type, size, data.data(), nullptr));
+    } else {
+        ASSERT_EQ_RESULT(result, UR_RESULT_ERROR_UNSUPPORTED_ENUMERATION);
+    }
+}
+
 using urQueueGetInfoTest = uur::urQueueTest;
 UUR_INSTANTIATE_DEVICE_TEST_SUITE_P(urQueueGetInfoTest);