Added DEVICE_INFO_PROGRAM_SET_SPECIALIZATION_CONSTANTS

RossBrunton · RossBrunton · commit 128ea0237ced · 2025-01-20T12:16:10.000Z
This is similar to the existing
`DEVICE_INFO_KERNEL_SET_SPECIALIZATION_CONSTANTS` device info, only
it applies to programs rather than kernels. All of the adapters should
be updated to report it correctly, and tests have been added.
diff --git a/include/ur_api.h b/include/ur_api.h
@@ -2198,6 +2198,9 @@ typedef enum ur_device_info_t {
   /// to the `USMPool` entry points and usage of the `pool` parameter of the
   /// USM alloc entry points.
   UR_DEVICE_INFO_USM_POOL_SUPPORT = 119,
+  /// [::ur_bool_t] support the ::urProgramSetSpecializationConstants entry
+  /// point
+  UR_DEVICE_INFO_PROGRAM_SET_SPECIALIZATION_CONSTANTS = 120,
   /// [::ur_bool_t] Returns true if the device supports the use of
   /// command-buffers.
   UR_DEVICE_INFO_COMMAND_BUFFER_SUPPORT_EXP = 0x1000,
@@ -5739,6 +5742,10 @@ typedef struct ur_specialization_constant_info_t {
 /// @brief Set an array of specialization constants on a Program.
 ///
 /// @details
+///     - This entry point is optional, the application should query for support
+///       with device query
+///       ::UR_DEVICE_INFO_PROGRAM_SET_SPECIALIZATION_CONSTANTS passed to
+///       ::urDeviceGetInfo.
 ///     - The application may call this function from simultaneous threads for
 ///       the same device.
 ///     - The implementation of this function should be thread-safe.
@@ -5758,6 +5765,9 @@ typedef struct ur_specialization_constant_info_t {
 ///         + `NULL == pSpecConstants`
 ///     - ::UR_RESULT_ERROR_INVALID_SIZE
 ///         + `count == 0`
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + If ::UR_DEVICE_INFO_PROGRAM_SET_SPECIALIZATION_CONSTANTS query is
+///         false
 ///     - ::UR_RESULT_ERROR_INVALID_VALUE
 ///         + A pSpecConstant entry contains a size that does not match that of
 ///         the specialization constant in the module.
diff --git a/include/ur_print.hpp b/include/ur_print.hpp
@@ -2917,6 +2917,9 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_device_info_t value) {
   case UR_DEVICE_INFO_USM_POOL_SUPPORT:
     os << "UR_DEVICE_INFO_USM_POOL_SUPPORT";
     break;
+  case UR_DEVICE_INFO_PROGRAM_SET_SPECIALIZATION_CONSTANTS:
+    os << "UR_DEVICE_INFO_PROGRAM_SET_SPECIALIZATION_CONSTANTS";
+    break;
   case UR_DEVICE_INFO_COMMAND_BUFFER_SUPPORT_EXP:
     os << "UR_DEVICE_INFO_COMMAND_BUFFER_SUPPORT_EXP";
     break;
@@ -4548,6 +4551,19 @@ inline ur_result_t printTagged(std::ostream &os, const void *ptr,
 
     os << ")";
   } break;
+  case UR_DEVICE_INFO_PROGRAM_SET_SPECIALIZATION_CONSTANTS: {
+    const ur_bool_t *tptr = (const ur_bool_t *)ptr;
+    if (sizeof(ur_bool_t) > size) {
+      os << "invalid size (is: " << size
+         << ", expected: >=" << sizeof(ur_bool_t) << ")";
+      return UR_RESULT_ERROR_INVALID_SIZE;
+    }
+    os << (const void *)(tptr) << " (";
+
+    os << *tptr;
+
+    os << ")";
+  } break;
   case UR_DEVICE_INFO_COMMAND_BUFFER_SUPPORT_EXP: {
     const ur_bool_t *tptr = (const ur_bool_t *)ptr;
     if (sizeof(ur_bool_t) > size) {
diff --git a/scripts/core/device.yml b/scripts/core/device.yml
@@ -443,6 +443,8 @@ etors:
       desc: "[$x_bool_t] return true if the device supports the `EnqueueDeviceGlobalVariableWrite` and `EnqueueDeviceGlobalVariableRead` entry points."
     - name: USM_POOL_SUPPORT
       desc: "[$x_bool_t] return true if the device supports USM pooling. Pertains to the `USMPool` entry points and usage of the `pool` parameter of the USM alloc entry points."
+    - name: PROGRAM_SET_SPECIALIZATION_CONSTANTS
+      desc: "[$x_bool_t] support the $xProgramSetSpecializationConstants entry point"
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Retrieves various information about device"
diff --git a/scripts/core/program.yml b/scripts/core/program.yml
@@ -528,6 +528,7 @@ desc: "Set an array of specialization constants on a Program."
 class: $xProgram
 name: SetSpecializationConstants
 details:
+    - "This entry point is optional, the application should query for support with device query $X_DEVICE_INFO_PROGRAM_SET_SPECIALIZATION_CONSTANTS passed to $xDeviceGetInfo."
     - "The application may call this function from simultaneous threads for the same device."
     - "The implementation of this function should be thread-safe."
     - "`hProgram` must have been created with the $xProgramCreateWithIL entry point."
@@ -546,6 +547,8 @@ params:
 returns:
     - $X_RESULT_ERROR_INVALID_SIZE:
         - "`count == 0`"
+    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
+        - "If $X_DEVICE_INFO_PROGRAM_SET_SPECIALIZATION_CONSTANTS query is false"
     - $X_RESULT_ERROR_INVALID_VALUE:
         - "A pSpecConstant entry contains a size that does not match that of the specialization constant in the module."
         - "A pSpecConstant entry contains a nullptr pValue."
diff --git a/source/adapters/cuda/device.cpp b/source/adapters/cuda/device.cpp
@@ -1065,6 +1065,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urDeviceGetInfo(ur_device_handle_t hDevice,
     return ReturnValue(AddressBuffer,
                        strnlen(AddressBuffer, AddressBufferSize - 1) + 1);
   }
+  case UR_DEVICE_INFO_PROGRAM_SET_SPECIALIZATION_CONSTANTS:
   case UR_DEVICE_INFO_KERNEL_SET_SPECIALIZATION_CONSTANTS:
     return ReturnValue(static_cast<ur_bool_t>(false));
     // TODO: Investigate if this information is available on CUDA.
diff --git a/source/adapters/hip/device.cpp b/source/adapters/hip/device.cpp
@@ -789,6 +789,10 @@ UR_APIEXPORT ur_result_t UR_APICALL urDeviceGetInfo(ur_device_handle_t hDevice,
     return ReturnValue(ur_bool_t{false});
   }
 
+  case UR_DEVICE_INFO_PROGRAM_SET_SPECIALIZATION_CONSTANTS: {
+    return ReturnValue(ur_bool_t{false});
+  }
+
   case UR_DEVICE_INFO_ATOMIC_MEMORY_ORDER_CAPABILITIES: {
     ur_memory_order_capability_flags_t Capabilities =
         UR_MEMORY_ORDER_CAPABILITY_FLAG_RELAXED |
diff --git a/source/adapters/level_zero/device.cpp b/source/adapters/level_zero/device.cpp
@@ -1156,6 +1156,8 @@ ur_result_t urDeviceGetInfo(
     // L0 does not support sampling 1D USM sampled image data.
     return ReturnValue(false);
   }
+  case UR_DEVICE_INFO_PROGRAM_SET_SPECIALIZATION_CONSTANTS:
+    return ReturnValue(true);
   case UR_DEVICE_INFO_KERNEL_SET_SPECIALIZATION_CONSTANTS:
     return ReturnValue(false);
   case UR_DEVICE_INFO_GLOBAL_VARIABLE_SUPPORT:
diff --git a/source/adapters/native_cpu/device.cpp b/source/adapters/native_cpu/device.cpp
@@ -428,6 +428,11 @@ UR_APIEXPORT ur_result_t UR_APICALL urDeviceGetInfo(ur_device_handle_t hDevice,
 
   case UR_DEVICE_INFO_LOW_POWER_EVENTS_EXP:
     return ReturnValue(false);
+
+  case UR_DEVICE_INFO_KERNEL_SET_SPECIALIZATION_CONSTANTS:
+  case UR_DEVICE_INFO_PROGRAM_SET_SPECIALIZATION_CONSTANTS:
+    return ReturnValue(false);
+
   default:
     DIE_NO_IMPLEMENTATION;
   }
diff --git a/source/adapters/opencl/device.cpp b/source/adapters/opencl/device.cpp
@@ -7,6 +7,7 @@
 //===-----------------------------------------------------------------===//
 
 #include "device.hpp"
+#include "adapter.hpp"
 #include "common.hpp"
 #include "platform.hpp"
 
@@ -1125,6 +1126,11 @@ UR_APIEXPORT ur_result_t UR_APICALL urDeviceGetInfo(ur_device_handle_t hDevice,
     return ReturnValue(UUID);
   }
 
+  case UR_DEVICE_INFO_PROGRAM_SET_SPECIALIZATION_CONSTANTS: {
+    return ReturnValue(
+        ur::cl::getAdapter()->clSetProgramSpecializationConstant != nullptr);
+  }
+
   // We can't query to check if these are supported, they will need to be
   // manually updated if support is ever implemented.
   case UR_DEVICE_INFO_KERNEL_SET_SPECIALIZATION_CONSTANTS:
diff --git a/source/loader/ur_libapi.cpp b/source/loader/ur_libapi.cpp
@@ -3543,6 +3543,10 @@ ur_result_t UR_APICALL urProgramGetBuildInfo(
 /// @brief Set an array of specialization constants on a Program.
 ///
 /// @details
+///     - This entry point is optional, the application should query for support
+///       with device query
+///       ::UR_DEVICE_INFO_PROGRAM_SET_SPECIALIZATION_CONSTANTS passed to
+///       ::urDeviceGetInfo.
 ///     - The application may call this function from simultaneous threads for
 ///       the same device.
 ///     - The implementation of this function should be thread-safe.
@@ -3562,6 +3566,9 @@ ur_result_t UR_APICALL urProgramGetBuildInfo(
 ///         + `NULL == pSpecConstants`
 ///     - ::UR_RESULT_ERROR_INVALID_SIZE
 ///         + `count == 0`
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + If ::UR_DEVICE_INFO_PROGRAM_SET_SPECIALIZATION_CONSTANTS query is
+///         false
 ///     - ::UR_RESULT_ERROR_INVALID_VALUE
 ///         + A pSpecConstant entry contains a size that does not match that of
 ///         the specialization constant in the module.
diff --git a/source/ur_api.cpp b/source/ur_api.cpp
@@ -3109,6 +3109,10 @@ ur_result_t UR_APICALL urProgramGetBuildInfo(
 /// @brief Set an array of specialization constants on a Program.
 ///
 /// @details
+///     - This entry point is optional, the application should query for support
+///       with device query
+///       ::UR_DEVICE_INFO_PROGRAM_SET_SPECIALIZATION_CONSTANTS passed to
+///       ::urDeviceGetInfo.
 ///     - The application may call this function from simultaneous threads for
 ///       the same device.
 ///     - The implementation of this function should be thread-safe.
@@ -3128,6 +3132,9 @@ ur_result_t UR_APICALL urProgramGetBuildInfo(
 ///         + `NULL == pSpecConstants`
 ///     - ::UR_RESULT_ERROR_INVALID_SIZE
 ///         + `count == 0`
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + If ::UR_DEVICE_INFO_PROGRAM_SET_SPECIALIZATION_CONSTANTS query is
+///         false
 ///     - ::UR_RESULT_ERROR_INVALID_VALUE
 ///         + A pSpecConstant entry contains a size that does not match that of
 ///         the specialization constant in the module.
diff --git a/test/conformance/device/urDeviceGetInfo.cpp b/test/conformance/device/urDeviceGetInfo.cpp
@@ -110,6 +110,7 @@ static std::unordered_map<ur_device_info_t, size_t> device_info_size_map = {
     {UR_DEVICE_INFO_BFLOAT16, sizeof(ur_bool_t)},
     {UR_DEVICE_INFO_MAX_COMPUTE_QUEUE_INDICES, sizeof(uint32_t)},
     {UR_DEVICE_INFO_KERNEL_SET_SPECIALIZATION_CONSTANTS, sizeof(ur_bool_t)},
+    {UR_DEVICE_INFO_PROGRAM_SET_SPECIALIZATION_CONSTANTS, sizeof(ur_bool_t)},
     {UR_DEVICE_INFO_MEMORY_BUS_WIDTH, sizeof(uint32_t)},
     {UR_DEVICE_INFO_MAX_WORK_GROUPS_3D, sizeof(size_t[3])},
     {UR_DEVICE_INFO_ASYNC_BARRIER, sizeof(ur_bool_t)},
@@ -251,7 +252,8 @@ UUR_DEVICE_TEST_SUITE_P(
         UR_DEVICE_INFO_2D_BLOCK_ARRAY_CAPABILITIES_EXP,        //
         UR_DEVICE_INFO_PREFERRED_VECTOR_WIDTH_DOUBLE,          //
         UR_DEVICE_INFO_PREFERRED_VECTOR_WIDTH_HALF,            //
-        UR_DEVICE_INFO_PREFERRED_VECTOR_WIDTH_INT              //
+        UR_DEVICE_INFO_PREFERRED_VECTOR_WIDTH_INT,             //
+        UR_DEVICE_INFO_PROGRAM_SET_SPECIALIZATION_CONSTANTS    //
         ),
     uur::deviceTestWithParamPrinter<ur_device_info_t>);
 
diff --git a/test/conformance/program/urProgramSetSpecializationConstants.cpp b/test/conformance/program/urProgramSetSpecializationConstants.cpp
@@ -11,6 +11,15 @@ struct urProgramSetSpecializationConstantsTest : uur::urKernelExecutionTest {
   void SetUp() override {
     program_name = "spec_constant";
     UUR_RETURN_ON_FATAL_FAILURE(urProgramTest::SetUp());
+
+    bool supports_kernel_spec_constant = false;
+    ASSERT_SUCCESS(urDeviceGetInfo(
+        device, UR_DEVICE_INFO_PROGRAM_SET_SPECIALIZATION_CONSTANTS,
+        sizeof(supports_kernel_spec_constant), &supports_kernel_spec_constant,
+        nullptr));
+    if (!supports_kernel_spec_constant) {
+      GTEST_SKIP() << "Device does not support setting program spec constants.";
+    }
   }
 
   uint32_t spec_value = 42;
@@ -19,20 +28,50 @@ struct urProgramSetSpecializationConstantsTest : uur::urKernelExecutionTest {
 };
 UUR_INSTANTIATE_DEVICE_TEST_SUITE_P(urProgramSetSpecializationConstantsTest);
 
+struct urProgramSetSpecializationConstantsNegativeTest
+    : uur::urKernelExecutionTest {
+  void SetUp() override {
+    program_name = "spec_constant";
+    UUR_RETURN_ON_FATAL_FAILURE(urProgramTest::SetUp());
+
+    bool supports_kernel_spec_constant = false;
+    ASSERT_SUCCESS(urDeviceGetInfo(
+        device, UR_DEVICE_INFO_PROGRAM_SET_SPECIALIZATION_CONSTANTS,
+        sizeof(supports_kernel_spec_constant), &supports_kernel_spec_constant,
+        nullptr));
+    if (supports_kernel_spec_constant) {
+      GTEST_SKIP() << "Device does supports setting program spec constants.";
+    }
+  }
+
+  uint32_t spec_value = 42;
+  uint32_t default_spec_value = 1000; // Must match the one in the SYCL source
+  ur_specialization_constant_info_t info = {0, sizeof(spec_value), &spec_value};
+};
+UUR_INSTANTIATE_DEVICE_TEST_SUITE_P(
+    urProgramSetSpecializationConstantsNegativeTest);
+
 struct urProgramSetMultipleSpecializationConstantsTest
     : uur::urKernelExecutionTest {
   // The types of spec constants in this program are {uint32_t, uint64_t, bool}
   void SetUp() override {
     program_name = "spec_constant_multiple";
     UUR_RETURN_ON_FATAL_FAILURE(urProgramTest::SetUp());
+
+    bool supports_kernel_spec_constant = false;
+    ASSERT_SUCCESS(urDeviceGetInfo(
+        device, UR_DEVICE_INFO_PROGRAM_SET_SPECIALIZATION_CONSTANTS,
+        sizeof(supports_kernel_spec_constant), &supports_kernel_spec_constant,
+        nullptr));
+    if (!supports_kernel_spec_constant) {
+      GTEST_SKIP() << "Device does not support setting program spec constants.";
+    }
   }
 };
 UUR_INSTANTIATE_DEVICE_TEST_SUITE_P(
     urProgramSetMultipleSpecializationConstantsTest);
 
 TEST_P(urProgramSetSpecializationConstantsTest, Success) {
-  UUR_KNOWN_FAILURE_ON(uur::CUDA{}, uur::HIP{});
-
   ASSERT_SUCCESS(urProgramSetSpecializationConstants(program, 1, &info));
   ASSERT_SUCCESS(urProgramBuild(context, program, nullptr));
   auto entry_points =
@@ -46,9 +85,12 @@ TEST_P(urProgramSetSpecializationConstantsTest, Success) {
   ValidateBuffer<uint32_t>(buffer, sizeof(spec_value), spec_value);
 }
 
-TEST_P(urProgramSetSpecializationConstantsTest, UseDefaultValue) {
-  UUR_KNOWN_FAILURE_ON(uur::CUDA{}, uur::HIP{});
+TEST_P(urProgramSetSpecializationConstantsNegativeTest, Unsupported) {
+  ASSERT_EQ_RESULT(UR_RESULT_ERROR_UNSUPPORTED_FEATURE,
+                   urProgramSetSpecializationConstants(program, 1, &info));
+}
 
+TEST_P(urProgramSetSpecializationConstantsTest, UseDefaultValue) {
   ur_platform_backend_t backend;
   ASSERT_SUCCESS(urPlatformGetInfo(platform, UR_PLATFORM_INFO_BACKEND,
                                    sizeof(ur_platform_backend_t), &backend,
@@ -72,8 +114,6 @@ TEST_P(urProgramSetSpecializationConstantsTest, UseDefaultValue) {
 }
 
 TEST_P(urProgramSetMultipleSpecializationConstantsTest, MultipleCalls) {
-  UUR_KNOWN_FAILURE_ON(uur::CUDA{}, uur::HIP{});
-
   uint32_t a = 100;
   uint64_t b = 200;
   bool c = false;
@@ -104,8 +144,6 @@ TEST_P(urProgramSetMultipleSpecializationConstantsTest, MultipleCalls) {
 }
 
 TEST_P(urProgramSetMultipleSpecializationConstantsTest, SingleCall) {
-  UUR_KNOWN_FAILURE_ON(uur::CUDA{}, uur::HIP{});
-
   uint32_t a = 200;
   uint64_t b = 300;
   bool c = true;
@@ -159,8 +197,7 @@ TEST_P(urProgramSetSpecializationConstantsTest, InvalidValueSize) {
 }
 
 TEST_P(urProgramSetSpecializationConstantsTest, InvalidValueId) {
-  UUR_KNOWN_FAILURE_ON(uur::CUDA{}, uur::HIP{}, uur::LevelZero{},
-                       uur::LevelZeroV2{});
+  UUR_KNOWN_FAILURE_ON(uur::LevelZero{}, uur::LevelZeroV2{});
 
   ur_specialization_constant_info_t bad_info = {999, sizeof(spec_value),
                                                 &spec_value};
@@ -169,8 +206,7 @@ TEST_P(urProgramSetSpecializationConstantsTest, InvalidValueId) {
 }
 
 TEST_P(urProgramSetSpecializationConstantsTest, InvalidValuePtr) {
-  UUR_KNOWN_FAILURE_ON(uur::CUDA{}, uur::HIP{}, uur::LevelZero{},
-                       uur::LevelZeroV2{});
+  UUR_KNOWN_FAILURE_ON(uur::LevelZero{}, uur::LevelZeroV2{});
 
   ur_specialization_constant_info_t bad_info = {0, sizeof(spec_value), nullptr};
   ASSERT_EQ_RESULT(UR_RESULT_ERROR_INVALID_VALUE,
diff --git a/tools/urinfo/urinfo.hpp b/tools/urinfo/urinfo.hpp
@@ -327,6 +327,9 @@ inline void printDeviceInfos(ur_device_handle_t hDevice,
   std::cout << prefix;
   printDeviceInfo<ur_bool_t>(hDevice, UR_DEVICE_INFO_USM_POOL_SUPPORT);
   std::cout << prefix;
+  printDeviceInfo<ur_bool_t>(
+      hDevice, UR_DEVICE_INFO_PROGRAM_SET_SPECIALIZATION_CONSTANTS);
+  std::cout << prefix;
   printDeviceInfo<ur_bool_t>(hDevice,
                              UR_DEVICE_INFO_COMMAND_BUFFER_SUPPORT_EXP);
   std::cout << prefix;

Original file line number	Diff line number	Diff line change
`@@ -1065,6 +1065,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urDeviceGetInfo(ur_device_handle_t hDevice,`
`1065`	`1065`	`return ReturnValue(AddressBuffer,`
`1066`	`1066`	`strnlen(AddressBuffer, AddressBufferSize - 1) + 1);`
`1067`	`1067`	`}`
	`1068`	`+ case UR_DEVICE_INFO_PROGRAM_SET_SPECIALIZATION_CONSTANTS:`
`1068`	`1069`	`case UR_DEVICE_INFO_KERNEL_SET_SPECIALIZATION_CONSTANTS:`
`1069`	`1070`	`return ReturnValue(static_cast<ur_bool_t>(false));`
`1070`	`1071`	`// TODO: Investigate if this information is available on CUDA.`
Original file line number	Diff line number	Diff line change
`@@ -1156,6 +1156,8 @@ ur_result_t urDeviceGetInfo(`
`1156`	`1156`	`// L0 does not support sampling 1D USM sampled image data.`
`1157`	`1157`	`return ReturnValue(false);`
`1158`	`1158`	`}`
	`1159`	`+ case UR_DEVICE_INFO_PROGRAM_SET_SPECIALIZATION_CONSTANTS:`
	`1160`	`+ return ReturnValue(true);`
`1159`	`1161`	`case UR_DEVICE_INFO_KERNEL_SET_SPECIALIZATION_CONSTANTS:`
`1160`	`1162`	`return ReturnValue(false);`
`1161`	`1163`	`case UR_DEVICE_INFO_GLOBAL_VARIABLE_SUPPORT:`