Improvements to align CTS and Spec for Device (#16746)

Migrated from oneapi-src#2597

- Rework urDeviceGetInfoTest to move all enums to their own tests
instead of a switch case -
oneapi-src#2290
- Remove the UR/OpenCL Device enum map function - no point maintaining
both a switch case and a separate mapping function
- Update some spec wording for consistency
- Add missing Device info enums to OpenCL adapater
- Add new urDevicePartition test for checking
UR_DEVICE_INFO_PARENT_DEVICE
- Move UUR_RETURN_ON_FATAL_FAILURE and UUR_ASSERT_SUCCESS_OR_UNSUPPORTED
to join similar macros in checks.h
- Update spec to say info queries that return char[] are null-terminated
- Add missing unsupported device enums to HIP adapter
- Reverted bindless image types back to size_t
- Moved ComponentDevices test to a separate PlatformTest derived fixture
- Added new ASSERT_QUERY_RETURNS_VALUE macro as a helper to validate
simple numerical GetInfo queries
- Added new stringPropertyIsValid helper function to validate string
queries
- Add missing unsupported device enums to HIP adapter

Author: martygrant

include/ur_api.h

@@ -1442,20 +1442,20 @@ UR_APIEXPORT ur_result_t UR_APICALL urPlatformGet(
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Supported platform info
 typedef enum ur_platform_info_t {
-  /// [char[]] The string denoting name of the platform. The size of the
-  /// info needs to be dynamically queried.
-  UR_PLATFORM_INFO_NAME = 1,
-  /// [char[]] The string denoting name of the vendor of the platform. The
+  /// [char[]] The null-terminated string denoting name of the platform. The
   /// size of the info needs to be dynamically queried.
+  UR_PLATFORM_INFO_NAME = 1,
+  /// [char[]] The null-terminated string denoting name of the vendor of the
+  /// platform. The size of the info needs to be dynamically queried.
   UR_PLATFORM_INFO_VENDOR_NAME = 2,
-  /// [char[]] The string denoting the version of the platform. The size of
-  /// the info needs to be dynamically queried.
+  /// [char[]] The null-terminated string denoting the version of the
+  /// platform. The size of the info needs to be dynamically queried.
   UR_PLATFORM_INFO_VERSION = 3,
-  /// [char[]] The string denoting extensions supported by the platform. The
-  /// size of the info needs to be dynamically queried.
+  /// [char[]] The null-terminated string denoting extensions supported by
+  /// the platform. The size of the info needs to be dynamically queried.
   UR_PLATFORM_INFO_EXTENSIONS = 4,
-  /// [char[]] The string denoting profile of the platform. The size of the
-  /// info needs to be dynamically queried.
+  /// [char[]] The null-terminated string denoting profile of the platform.
+  /// The size of the info needs to be dynamically queried.
   UR_PLATFORM_INFO_PROFILE = 5,
   /// [::ur_platform_backend_t] The backend of the platform. Identifies the
   /// native backend adapter implementing this platform.
@@ -2037,7 +2037,8 @@ typedef enum ur_device_info_t {
   UR_DEVICE_INFO_QUEUE_ON_DEVICE_PROPERTIES = 60,
   /// [::ur_queue_flags_t] host queue property bit-field
   UR_DEVICE_INFO_QUEUE_ON_HOST_PROPERTIES = 61,
-  /// [char[]] a semi-colon separated list of built-in kernels
+  /// [char[]] a null-terminated semi-colon separated list of built-in
+  /// kernels
   UR_DEVICE_INFO_BUILT_IN_KERNELS = 62,
   /// [::ur_platform_handle_t] the platform associated with the device
   UR_DEVICE_INFO_PLATFORM = 63,
@@ -2046,21 +2047,22 @@ typedef enum ur_device_info_t {
   /// It is unsuitable for general use in applications. This feature is
   /// provided for identifying memory leaks.
   UR_DEVICE_INFO_REFERENCE_COUNT = 64,
-  /// [char[]] IL version
+  /// [char[]] null-terminated IL version
   UR_DEVICE_INFO_IL_VERSION = 65,
-  /// [char[]] Device name
+  /// [char[]] null-terminated device name
   UR_DEVICE_INFO_NAME = 66,
-  /// [char[]] Device vendor
+  /// [char[]] null-terminated device vendor
   UR_DEVICE_INFO_VENDOR = 67,
-  /// [char[]] Driver version
+  /// [char[]] null-terminated driver version
   UR_DEVICE_INFO_DRIVER_VERSION = 68,
-  /// [char[]] Device profile
+  /// [char[]] null-terminated device profile
   UR_DEVICE_INFO_PROFILE = 69,
-  /// [char[]] Device version
+  /// [char[]] null-terminated device version
   UR_DEVICE_INFO_VERSION = 70,
-  /// [char[]] Version of backend runtime
+  /// [char[]] null-terminated version of backend runtime
   UR_DEVICE_INFO_BACKEND_RUNTIME_VERSION = 71,
-  /// [char[]] Return a space separated list of extension names
+  /// [char[]] Return a null-terminated space separated list of extension
+  /// names
   UR_DEVICE_INFO_EXTENSIONS = 72,
   /// [size_t] Maximum size in bytes of internal printf buffer
   UR_DEVICE_INFO_PRINTF_BUFFER_SIZE = 73,
@@ -2080,9 +2082,8 @@ typedef enum ur_device_info_t {
   /// If the device does not support any affinity domains, then 0 will be
   /// returned.
   UR_DEVICE_INFO_PARTITION_AFFINITY_DOMAIN = 78,
-  /// [::ur_device_partition_property_t[]] return an array of
-  /// ::ur_device_partition_property_t for properties specified in
-  /// ::urDevicePartition
+  /// [::ur_device_partition_property_t[]] returns an array of properties
+  /// specified in ::urDevicePartition
   UR_DEVICE_INFO_PARTITION_TYPE = 79,
   /// [uint32_t] max number of sub groups
   UR_DEVICE_INFO_MAX_NUM_SUB_GROUPS = 80,
@@ -2107,7 +2108,7 @@ typedef enum ur_device_info_t {
   UR_DEVICE_INFO_USM_SYSTEM_SHARED_SUPPORT = 87,
   /// [uint8_t[]][optional-query] return device UUID
   UR_DEVICE_INFO_UUID = 88,
-  /// [char[]][optional-query] return device PCI address
+  /// [char[]][optional-query] return null-terminated device PCI address
   UR_DEVICE_INFO_PCI_ADDRESS = 89,
   /// [uint32_t][optional-query] return Intel GPU EU count
   UR_DEVICE_INFO_GPU_EU_COUNT = 90,
@@ -2253,20 +2254,20 @@ typedef enum ur_device_info_t {
   /// [::ur_bool_t] returns true if the device supports sampling cubemapped
   /// images across face boundaries
   UR_DEVICE_INFO_CUBEMAP_SEAMLESS_FILTERING_SUPPORT_EXP = 0x2011,
-  /// [::ur_bool_t] returns true if the device is capable of fetching USM
-  /// backed 1D sampled image data.
+  /// [::ur_bool_t] returns true if the device supports fetching USM backed
+  /// 1D sampled image data.
   UR_DEVICE_INFO_BINDLESS_SAMPLED_IMAGE_FETCH_1D_USM_EXP = 0x2012,
-  /// [::ur_bool_t] returns true if the device is capable of fetching
-  /// non-USM backed 1D sampled image data.
+  /// [::ur_bool_t] returns true if the device supports fetching non-USM
+  /// backed 1D sampled image data.
   UR_DEVICE_INFO_BINDLESS_SAMPLED_IMAGE_FETCH_1D_EXP = 0x2013,
-  /// [::ur_bool_t] returns true if the device is capable of fetching USM
-  /// backed 2D sampled image data.
+  /// [::ur_bool_t] returns true if the device supports fetching USM backed
+  /// 2D sampled image data.
   UR_DEVICE_INFO_BINDLESS_SAMPLED_IMAGE_FETCH_2D_USM_EXP = 0x2014,
-  /// [::ur_bool_t] returns true if the device is capable of fetching
-  /// non-USM backed 2D sampled image data.
+  /// [::ur_bool_t] returns true if the device supports fetching non-USM
+  /// backed 2D sampled image data.
   UR_DEVICE_INFO_BINDLESS_SAMPLED_IMAGE_FETCH_2D_EXP = 0x2015,
-  /// [::ur_bool_t] returns true if the device is capable of fetching
-  /// non-USM backed 3D sampled image data.
+  /// [::ur_bool_t] returns true if the device supports fetching non-USM
+  /// backed 3D sampled image data.
   UR_DEVICE_INFO_BINDLESS_SAMPLED_IMAGE_FETCH_3D_EXP = 0x2017,
   /// [::ur_bool_t] returns true if the device supports timestamp recording
   UR_DEVICE_INFO_TIMESTAMP_RECORDING_SUPPORT_EXP = 0x2018,
@@ -2276,11 +2277,11 @@ typedef enum ur_device_info_t {
   /// [::ur_bool_t] returns true if the device supports unique addressing
   /// per dimension.
   UR_DEVICE_INFO_BINDLESS_UNIQUE_ADDRESSING_PER_DIM_EXP = 0x201A,
-  /// [::ur_bool_t] returns true if the device is capable of sampling USM
-  /// backed 1D sampled image data.
+  /// [::ur_bool_t] returns true if the device supports sampling USM backed
+  /// 1D sampled image data.
   UR_DEVICE_INFO_BINDLESS_SAMPLE_1D_USM_EXP = 0x201B,
-  /// [::ur_bool_t] returns true if the device is capable of sampling USM
-  /// backed 2D sampled image data.
+  /// [::ur_bool_t] returns true if the device supports sampling USM backed
+  /// 2D sampled image data.
   UR_DEVICE_INFO_BINDLESS_SAMPLE_2D_USM_EXP = 0x201C,
   /// [::ur_bool_t] returns true if the device supports enqueueing of native
   /// work
@@ -5572,12 +5573,12 @@ typedef enum ur_program_info_t {
   UR_PROGRAM_INFO_DEVICES = 3,
   /// [char[]] Return program IL if the program was created with
   /// ::urProgramCreateWithIL, otherwise return size will be set to 0 and
-  /// nothing will be returned.
+  /// nothing will be returned. This is not null-terminated.
   UR_PROGRAM_INFO_IL = 4,
   /// [size_t[]] Return program binary sizes for each device.
   UR_PROGRAM_INFO_BINARY_SIZES = 5,
   /// [unsigned char[]] Return program binaries for all devices for this
-  /// Program.
+  /// Program. These are not null-terminated.
   UR_PROGRAM_INFO_BINARIES = 6,
   /// [size_t][optional-query] Number of kernels in Program, return type
   /// size_t.

scripts/core/device.yml

@@ -320,7 +320,7 @@ etors:
     - name: QUEUE_ON_HOST_PROPERTIES
       desc: "[$x_queue_flags_t] host queue property bit-field"
     - name: BUILT_IN_KERNELS
-      desc: "[char[]] a semi-colon separated list of built-in kernels"
+      desc: "[char[]] a null-terminated semi-colon separated list of built-in kernels"
     - name: PLATFORM
       desc: "[$x_platform_handle_t] the platform associated with the device"
     - name: REFERENCE_COUNT
@@ -329,21 +329,21 @@ 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: IL_VERSION
-      desc: "[char[]] IL version"
+      desc: "[char[]] null-terminated IL version"
     - name: NAME
-      desc: "[char[]] Device name"
+      desc: "[char[]] null-terminated device name"
     - name: VENDOR
-      desc: "[char[]] Device vendor"
+      desc: "[char[]] null-terminated device vendor"
     - name: DRIVER_VERSION
-      desc: "[char[]] Driver version"
+      desc: "[char[]] null-terminated driver version"
     - name: PROFILE
-      desc: "[char[]] Device profile"
+      desc: "[char[]] null-terminated device profile"
     - name: VERSION
-      desc: "[char[]] Device version"
+      desc: "[char[]] null-terminated device version"
     - name: BACKEND_RUNTIME_VERSION
-      desc: "[char[]] Version of backend runtime"
+      desc: "[char[]] null-terminated version of backend runtime"
     - name: EXTENSIONS
-      desc: "[char[]] Return a space separated list of extension names"
+      desc: "[char[]] Return a null-terminated space separated list of extension names"
     - name: PRINTF_BUFFER_SIZE
       desc: "[size_t] Maximum size in bytes of internal printf buffer"
     - name: PREFERRED_INTEROP_USER_SYNC
@@ -359,7 +359,7 @@ etors:
             [$x_device_affinity_domain_flags_t] Returns a bit-field of the supported affinity domains for partitioning.
             If the device does not support any affinity domains, then 0 will be returned.
     - name: PARTITION_TYPE
-      desc: "[$x_device_partition_property_t[]] return an array of $x_device_partition_property_t for properties specified in $xDevicePartition"
+      desc: "[$x_device_partition_property_t[]] returns an array of properties specified in $xDevicePartition"
     - name: MAX_NUM_SUB_GROUPS
       desc: "[uint32_t] max number of sub groups"
     - name: SUB_GROUP_INDEPENDENT_FORWARD_PROGRESS
@@ -379,7 +379,7 @@ etors:
     - name: UUID
       desc: "[uint8_t[]][optional-query] return device UUID"
     - name: PCI_ADDRESS
-      desc: "[char[]][optional-query] return device PCI address"
+      desc: "[char[]][optional-query] return null-terminated device PCI address"
     - name: GPU_EU_COUNT
       desc: "[uint32_t][optional-query] return Intel GPU EU count"
     - name: GPU_EU_SIMD_WIDTH

scripts/core/exp-bindless-images.yml

@@ -88,19 +88,19 @@ etors:
       desc: "[$x_bool_t] returns true if the device supports sampling cubemapped images across face boundaries"
     - name: BINDLESS_SAMPLED_IMAGE_FETCH_1D_USM_EXP
       value: "0x2012"
-      desc: "[$x_bool_t] returns true if the device is capable of fetching USM backed 1D sampled image data."
+      desc: "[$x_bool_t] returns true if the device supports fetching USM backed 1D sampled image data."
     - name: BINDLESS_SAMPLED_IMAGE_FETCH_1D_EXP
       value: "0x2013"
-      desc: "[$x_bool_t] returns true if the device is capable of fetching non-USM backed 1D sampled image data."
+      desc: "[$x_bool_t] returns true if the device supports fetching non-USM backed 1D sampled image data."
     - name: BINDLESS_SAMPLED_IMAGE_FETCH_2D_USM_EXP
       value: "0x2014"
-      desc: "[$x_bool_t] returns true if the device is capable of fetching USM backed 2D sampled image data."
+      desc: "[$x_bool_t] returns true if the device supports fetching USM backed 2D sampled image data."
     - name: BINDLESS_SAMPLED_IMAGE_FETCH_2D_EXP
       value: "0x2015"
-      desc: "[$x_bool_t] returns true if the device is capable of fetching non-USM backed 2D sampled image data."
+      desc: "[$x_bool_t] returns true if the device supports fetching non-USM backed 2D sampled image data."
     - name: BINDLESS_SAMPLED_IMAGE_FETCH_3D_EXP
       value: "0x2017"
-      desc: "[$x_bool_t] returns true if the device is capable of fetching non-USM backed 3D sampled image data."
+      desc: "[$x_bool_t] returns true if the device supports fetching non-USM backed 3D sampled image data."
     - name: IMAGE_ARRAY_SUPPORT_EXP
       value: "0x2019"
       desc: "[$x_bool_t] returns true if the device supports allocating and accessing image array resources."
@@ -109,10 +109,10 @@ etors:
       desc: "[$x_bool_t] returns true if the device supports unique addressing per dimension."
     - name: BINDLESS_SAMPLE_1D_USM_EXP
       value: "0x201B"
-      desc: "[$x_bool_t] returns true if the device is capable of sampling USM backed 1D sampled image data."
+      desc: "[$x_bool_t] returns true if the device supports sampling USM backed 1D sampled image data."
     - name: BINDLESS_SAMPLE_2D_USM_EXP
       value: "0x201C"
-      desc: "[$x_bool_t] returns true if the device is capable of sampling USM backed 2D sampled image data."
+      desc: "[$x_bool_t] returns true if the device supports sampling USM backed 2D sampled image data."
 --- #--------------------------------------------------------------------------
 type: enum
 extend: true

scripts/core/platform.yml

@@ -59,20 +59,20 @@ typed_etors: True
 etors:
     - name: NAME
       value: "1"
-      desc: "[char[]] The string denoting name of the platform. The size of the info needs to be dynamically queried."
+      desc: "[char[]] The null-terminated string denoting name of the platform. The size of the info needs to be dynamically queried."
     - name: VENDOR_NAME
       value: "2"
-      desc: "[char[]] The string denoting name of the vendor of the platform. The size of the info needs to be dynamically queried."
+      desc: "[char[]] The null-terminated string denoting name of the vendor of the platform. The size of the info needs to be dynamically queried."
     - name: VERSION
       value: "3"
-      desc: "[char[]] The string denoting the version of the platform. The size of the info needs to be dynamically queried."
+      desc: "[char[]] The null-terminated string denoting the version of the platform. The size of the info needs to be dynamically queried."
     - name: EXTENSIONS
       value: "4"
-      desc: "[char[]] The string denoting extensions supported by the platform. The size of the info needs to be dynamically queried."
+      desc: "[char[]] The null-terminated string denoting extensions supported by the platform. The size of the info needs to be dynamically queried."
       todo: "document extensions names and their meaning"
     - name: PROFILE
       value: "5"
-      desc: "[char[]] The string denoting profile of the platform. The size of the info needs to be dynamically queried."
+      desc: "[char[]] The null-terminated string denoting profile of the platform. The size of the info needs to be dynamically queried."
       todo: "currently always return FULL_PROFILE, deprecate?"
     - name: BACKEND
       value: "6"

scripts/core/program.yml

@@ -381,11 +381,11 @@ etors:
           [$x_device_handle_t[]] Return list of devices associated with a program.
           This is either the list of devices associated with the context or a subset of those devices when the program is created using $xProgramCreateWithBinary.
     - name: IL
-      desc: "[char[]] Return program IL if the program was created with $xProgramCreateWithIL, otherwise return size will be set to 0 and nothing will be returned."
+      desc: "[char[]] Return program IL if the program was created with $xProgramCreateWithIL, otherwise return size will be set to 0 and nothing will be returned. This is not null-terminated."
     - name: BINARY_SIZES
       desc: "[size_t[]] Return program binary sizes for each device."
     - name: BINARIES
-      desc: "[unsigned char[]] Return program binaries for all devices for this Program."
+      desc: "[unsigned char[]] Return program binaries for all devices for this Program. These are not null-terminated."
     - name: NUM_KERNELS
       desc: "[size_t][optional-query] Number of kernels in Program, return type size_t."
     - name: KERNEL_NAMES

source/adapters/cuda/device.cpp

@@ -862,21 +862,21 @@ UR_APIEXPORT ur_result_t UR_APICALL urDeviceGetInfo(ur_device_handle_t hDevice,
     UR_CHECK_ERROR(cuDeviceGetAttribute(
         &tex_max_linear_width,
         CU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE2D_LINEAR_WIDTH, hDevice->get()));
-    return ReturnValue(tex_max_linear_width);
+    return ReturnValue(static_cast<size_t>(tex_max_linear_width));
   }
   case UR_DEVICE_INFO_MAX_IMAGE_LINEAR_HEIGHT_EXP: {
     int32_t tex_max_linear_height = 0;
     UR_CHECK_ERROR(cuDeviceGetAttribute(
         &tex_max_linear_height,
         CU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE2D_LINEAR_HEIGHT, hDevice->get()));
-    return ReturnValue(tex_max_linear_height);
+    return ReturnValue(static_cast<size_t>(tex_max_linear_height));
   }
   case UR_DEVICE_INFO_MAX_IMAGE_LINEAR_PITCH_EXP: {
     int32_t tex_max_linear_pitch = 0;
     UR_CHECK_ERROR(cuDeviceGetAttribute(
         &tex_max_linear_pitch,
         CU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE2D_LINEAR_PITCH, hDevice->get()));
-    return ReturnValue(tex_max_linear_pitch);
+    return ReturnValue(static_cast<size_t>(tex_max_linear_pitch));
   }
   case UR_DEVICE_INFO_MIPMAP_SUPPORT_EXP: {
     // CUDA supports mipmaps.

source/adapters/hip/device.cpp

@@ -227,7 +227,6 @@ UR_APIEXPORT ur_result_t UR_APICALL urDeviceGetInfo(ur_device_handle_t hDevice,
   }
   case UR_DEVICE_INFO_IMAGE_SUPPORTED: {
     bool Enabled = false;
-
     if (std::getenv("UR_HIP_ENABLE_IMAGE_SUPPORT") != nullptr) {
       Enabled = true;
     } else {
@@ -823,17 +822,17 @@ UR_APIEXPORT ur_result_t UR_APICALL urDeviceGetInfo(ur_device_handle_t hDevice,
   }
   case UR_DEVICE_INFO_MAX_IMAGE_LINEAR_WIDTH_EXP: {
     // Default values due to non-existent hipamd queries for linear sizes.
-    constexpr uint32_t MaxLinearWidth{1};
+    constexpr size_t MaxLinearWidth{1};
     return ReturnValue(MaxLinearWidth);
   }
   case UR_DEVICE_INFO_MAX_IMAGE_LINEAR_HEIGHT_EXP: {
     // Default values due to non-existent hipamd queries for linear sizes.
-    constexpr uint32_t MaxLinearHeight{1};
+    constexpr size_t MaxLinearHeight{1};
     return ReturnValue(MaxLinearHeight);
   }
   case UR_DEVICE_INFO_MAX_IMAGE_LINEAR_PITCH_EXP: {
     // Default values due to non-existent hipamd queries for linear sizes.
-    constexpr uint32_t MaxLinearPitch{1};
+    constexpr size_t MaxLinearPitch{1};
     return ReturnValue(MaxLinearPitch);
   }
   case UR_DEVICE_INFO_MIPMAP_SUPPORT_EXP: {
@@ -1070,6 +1069,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urDeviceGetInfo(ur_device_handle_t hDevice,
   case UR_DEVICE_INFO_GPU_HW_THREADS_PER_EU:
   case UR_DEVICE_INFO_MAX_MEMORY_BANDWIDTH:
   case UR_DEVICE_INFO_IP_VERSION:
+  case UR_DEVICE_INFO_CLUSTER_LAUNCH_EXP:
     return UR_RESULT_ERROR_UNSUPPORTED_ENUMERATION;
   case UR_DEVICE_INFO_2D_BLOCK_ARRAY_CAPABILITIES_EXP:
     return ReturnValue(

source/adapters/level_zero/device.cpp

@@ -1105,7 +1105,7 @@ ur_result_t urDeviceGetInfo(
   case UR_DEVICE_INFO_MAX_IMAGE_LINEAR_PITCH_EXP:
     logger::error("Unsupported ParamName in urGetDeviceInfo");
     logger::error("ParamName=%{}(0x{})", ParamName, logger::toHex(ParamName));
-    return UR_RESULT_ERROR_INVALID_VALUE;
+    return UR_RESULT_ERROR_UNSUPPORTED_ENUMERATION;
   case UR_DEVICE_INFO_MIPMAP_SUPPORT_EXP: {
     // L0 does not support mipmaps.
     return ReturnValue(false);
@@ -1117,7 +1117,7 @@ ur_result_t urDeviceGetInfo(
   case UR_DEVICE_INFO_MIPMAP_MAX_ANISOTROPY_EXP:
     logger::error("Unsupported ParamName in urGetDeviceInfo");
     logger::error("ParamName=%{}(0x{})", ParamName, logger::toHex(ParamName));
-    return UR_RESULT_ERROR_INVALID_VALUE;
+    return UR_RESULT_ERROR_UNSUPPORTED_ENUMERATION;
   case UR_DEVICE_INFO_MIPMAP_LEVEL_REFERENCE_SUPPORT_EXP: {
     // L0 does not support creation of images from individual mipmap levels.
     return ReturnValue(false);