[Spec Constants] Improved handling of invalid/unsupported spec. const…

…ants

Two main changes to how `Kernel/ProgramSetSpecializationConstants`
are handled:
* They may now output either `INVALID_VALUE` or the new
  `INVALID_SPEC_ID` when the provided list is invalid.
* The OpenCL and level 0 adapters now respond to
  `UR_DEVICE_INFO_KERNEL_SET_SPECIALIZATION_CONSTANTS` with `false`
  rather than erroring out. This fixes some tests that were
  incorrectly not being skipped.
* `urKernelSetSpecializationConstants` now "implemented" (as a
  function that returns `UNSUPPORTED_FEATURE` for opencl and cuda.

include/ur_api.h

@@ -493,6 +493,7 @@ typedef enum ur_result_t {
                                                                               ///< retrieved via the urPlatformGetLastError entry point.
     UR_RESULT_ERROR_LAYER_NOT_PRESENT = 68,                                   ///< A requested layer was not found by the loader.
     UR_RESULT_ERROR_IN_EVENT_LIST_EXEC_STATUS = 69,                           ///< An event in the provided wait list has ::UR_EVENT_STATUS_ERROR.
+    UR_RESULT_ERROR_INVALID_SPEC_ID = 70,                                     ///< A specialization constant identifier is not valid.
     UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP = 0x1000,                      ///< Invalid Command-Buffer
     UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP = 0x1001,           ///< Sync point is not valid for the command-buffer
     UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_WAIT_LIST_EXP = 0x1002, ///< Sync point wait list is invalid
@@ -4535,6 +4536,11 @@ typedef struct ur_specialization_constant_info_t {
 ///         + `NULL == pSpecConstants`
 ///     - ::UR_RESULT_ERROR_INVALID_SIZE
 ///         + `count == 0`
+///     - ::UR_RESULT_ERROR_INVALID_VALUE
+///         + Any size specified in a pSpecConstant entry does not match the specialization constant in the module.
+///         + Any pValue specified in a pSpecConstant entry is nullptr.
+///     - ::UR_RESULT_ERROR_INVALID_SPEC_ID
+///         + Any id specified in a pSpecConstant entry is not a valid specialization constant identifier.
 UR_APIEXPORT ur_result_t UR_APICALL
 urProgramSetSpecializationConstants(
     ur_program_handle_t hProgram,                           ///< [in] handle of the Program object
@@ -5119,6 +5125,11 @@ urKernelSetArgMemObj(
 ///         + `count == 0`
 ///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
 ///         + If ::UR_DEVICE_INFO_KERNEL_SET_SPECIALIZATION_CONSTANTS query is false
+///     - ::UR_RESULT_ERROR_INVALID_VALUE
+///         + Any size specified in a pSpecConstant entry does not match the specialization constant in the module.
+///         + Any pValue specified in a pSpecConstant entry is nullptr.
+///     - ::UR_RESULT_ERROR_INVALID_SPEC_ID
+///         + Any id specified in a pSpecConstant entry is not a valid specialization constant identifier.
 UR_APIEXPORT ur_result_t UR_APICALL
 urKernelSetSpecializationConstants(
     ur_kernel_handle_t hKernel,                             ///< [in] handle of the kernel object

include/ur_print.hpp

@@ -1542,6 +1542,9 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_result_t value) {
     case UR_RESULT_ERROR_IN_EVENT_LIST_EXEC_STATUS:
         os << "UR_RESULT_ERROR_IN_EVENT_LIST_EXEC_STATUS";
         break;
+    case UR_RESULT_ERROR_INVALID_SPEC_ID:
+        os << "UR_RESULT_ERROR_INVALID_SPEC_ID";
+        break;
     case UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP:
         os << "UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP";
         break;

scripts/core/common.yml

@@ -276,6 +276,8 @@ etors:
       desc: "A requested layer was not found by the loader."
     - name: ERROR_IN_EVENT_LIST_EXEC_STATUS
       desc: "An event in the provided wait list has $X_EVENT_STATUS_ERROR."
+    - name: ERROR_INVALID_SPEC_ID
+      desc: "A specialization constant identifier is not valid."
     - name: ERROR_UNKNOWN
       value: "0x7ffffffe"
       desc: "Unknown or internal error"

scripts/core/kernel.yml

@@ -465,6 +465,11 @@ returns:
         - "`count == 0`"
     - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
         - "If $X_DEVICE_INFO_KERNEL_SET_SPECIALIZATION_CONSTANTS query is false"
+    - $X_RESULT_ERROR_INVALID_VALUE:
+        - "Any size specified in a pSpecConstant entry does not match the specialization constant in the module."
+        - "Any pValue specified in a pSpecConstant entry is nullptr."
+    - $X_RESULT_ERROR_INVALID_SPEC_ID:
+        - "Any id specified in a pSpecConstant entry is not a valid specialization constant identifier."
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Return platform native kernel handle."

scripts/core/program.yml

@@ -533,6 +533,11 @@ params:
 returns:
     - $X_RESULT_ERROR_INVALID_SIZE:
         - "`count == 0`"
+    - $X_RESULT_ERROR_INVALID_VALUE:
+        - "Any size specified in a pSpecConstant entry does not match the specialization constant in the module."
+        - "Any pValue specified in a pSpecConstant entry is nullptr."
+    - $X_RESULT_ERROR_INVALID_SPEC_ID:
+        - "Any id specified in a pSpecConstant entry is not a valid specialization constant identifier."
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Return program native program handle."

source/adapters/cuda/kernel.cpp

@@ -377,3 +377,8 @@ urKernelSetArgSampler(ur_kernel_handle_t hKernel, uint32_t argIndex,
   }
   return Result;
 }
+
+UR_APIEXPORT ur_result_t UR_APICALL urKernelSetSpecializationConstants(
+    ur_kernel_handle_t, uint32_t, const ur_specialization_constant_info_t *) {
+  return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
+}

source/adapters/cuda/ur_interface_loader.cpp

@@ -124,7 +124,7 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetKernelProcAddrTable(
   pDdiTable->pfnSetArgSampler = urKernelSetArgSampler;
   pDdiTable->pfnSetArgValue = urKernelSetArgValue;
   pDdiTable->pfnSetExecInfo = urKernelSetExecInfo;
-  pDdiTable->pfnSetSpecializationConstants = nullptr;
+  pDdiTable->pfnSetSpecializationConstants = urKernelSetSpecializationConstants;
   return UR_RESULT_SUCCESS;
 }
 

source/adapters/level_zero/device.cpp

@@ -839,6 +839,8 @@ UR_APIEXPORT ur_result_t UR_APICALL urDeviceGetInfo(
     return ReturnValue(uint32_t{false});
   case UR_DEVICE_INFO_IMAGE_SRGB:
     return ReturnValue(uint32_t{false});
+  case UR_DEVICE_INFO_KERNEL_SET_SPECIALIZATION_CONSTANTS:
+    return ReturnValue(uint32_t{false});
 
   case UR_DEVICE_INFO_QUEUE_ON_DEVICE_PROPERTIES:
   case UR_DEVICE_INFO_QUEUE_ON_HOST_PROPERTIES: {

source/adapters/opencl/common.cpp

@@ -83,6 +83,8 @@ ur_result_t mapCLErrorToUR(cl_int Result) {
     return UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_WAIT_LIST_EXP;
   case CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST:
     return UR_RESULT_ERROR_IN_EVENT_LIST_EXEC_STATUS;
+  case CL_INVALID_SPEC_ID:
+    return UR_RESULT_ERROR_INVALID_SPEC_ID;
   default:
     return UR_RESULT_ERROR_UNKNOWN;
   }

source/adapters/opencl/device.cpp

@@ -820,7 +820,6 @@ UR_APIEXPORT ur_result_t UR_APICALL urDeviceGetInfo(ur_device_handle_t hDevice,
   case UR_DEVICE_INFO_COMPILER_AVAILABLE:
   case UR_DEVICE_INFO_LINKER_AVAILABLE:
   case UR_DEVICE_INFO_PREFERRED_INTEROP_USER_SYNC:
-  case UR_DEVICE_INFO_KERNEL_SET_SPECIALIZATION_CONSTANTS:
   case UR_DEVICE_INFO_SUB_GROUP_INDEPENDENT_FORWARD_PROGRESS: {
     /* CL type: cl_bool
      * UR type: ur_bool_t */
@@ -969,6 +968,9 @@ UR_APIEXPORT ur_result_t UR_APICALL urDeviceGetInfo(ur_device_handle_t hDevice,
   case UR_DEVICE_INFO_COMMAND_BUFFER_UPDATE_SUPPORT_EXP: {
     return ReturnValue(false);
   }
+  case UR_DEVICE_INFO_KERNEL_SET_SPECIALIZATION_CONSTANTS: {
+    return ReturnValue(false);
+  }
   default: {
     return UR_RESULT_ERROR_INVALID_ENUMERATION;
   }

source/adapters/opencl/kernel.cpp

@@ -419,3 +419,8 @@ UR_APIEXPORT ur_result_t UR_APICALL urKernelSetArgSampler(
   CL_RETURN_ON_FAILURE(RetErr);
   return UR_RESULT_SUCCESS;
 }
+
+UR_APIEXPORT ur_result_t UR_APICALL urKernelSetSpecializationConstants(
+    ur_kernel_handle_t, uint32_t, const ur_specialization_constant_info_t *) {
+  return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
+}

source/adapters/opencl/ur_interface_loader.cpp

@@ -124,7 +124,7 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetKernelProcAddrTable(
   pDdiTable->pfnSetArgSampler = urKernelSetArgSampler;
   pDdiTable->pfnSetArgValue = urKernelSetArgValue;
   pDdiTable->pfnSetExecInfo = urKernelSetExecInfo;
-  pDdiTable->pfnSetSpecializationConstants = nullptr;
+  pDdiTable->pfnSetSpecializationConstants = urKernelSetSpecializationConstants;
   return UR_RESULT_SUCCESS;
 }
 

source/loader/ur_libapi.cpp

@@ -3402,6 +3402,11 @@ ur_result_t UR_APICALL urProgramGetBuildInfo(
 ///         + `NULL == pSpecConstants`
 ///     - ::UR_RESULT_ERROR_INVALID_SIZE
 ///         + `count == 0`
+///     - ::UR_RESULT_ERROR_INVALID_VALUE
+///         + Any size specified in a pSpecConstant entry does not match the specialization constant in the module.
+///         + Any pValue specified in a pSpecConstant entry is nullptr.
+///     - ::UR_RESULT_ERROR_INVALID_SPEC_ID
+///         + Any id specified in a pSpecConstant entry is not a valid specialization constant identifier.
 ur_result_t UR_APICALL urProgramSetSpecializationConstants(
     ur_program_handle_t hProgram, ///< [in] handle of the Program object
     uint32_t count, ///< [in] the number of elements in the pSpecConstants array
@@ -3987,6 +3992,11 @@ ur_result_t UR_APICALL urKernelSetArgMemObj(
 ///         + `count == 0`
 ///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
 ///         + If ::UR_DEVICE_INFO_KERNEL_SET_SPECIALIZATION_CONSTANTS query is false
+///     - ::UR_RESULT_ERROR_INVALID_VALUE
+///         + Any size specified in a pSpecConstant entry does not match the specialization constant in the module.
+///         + Any pValue specified in a pSpecConstant entry is nullptr.
+///     - ::UR_RESULT_ERROR_INVALID_SPEC_ID
+///         + Any id specified in a pSpecConstant entry is not a valid specialization constant identifier.
 ur_result_t UR_APICALL urKernelSetSpecializationConstants(
     ur_kernel_handle_t hKernel, ///< [in] handle of the kernel object
     uint32_t count, ///< [in] the number of elements in the pSpecConstants array

source/ur_api.cpp

@@ -2897,6 +2897,11 @@ ur_result_t UR_APICALL urProgramGetBuildInfo(
 ///         + `NULL == pSpecConstants`
 ///     - ::UR_RESULT_ERROR_INVALID_SIZE
 ///         + `count == 0`
+///     - ::UR_RESULT_ERROR_INVALID_VALUE
+///         + Any size specified in a pSpecConstant entry does not match the specialization constant in the module.
+///         + Any pValue specified in a pSpecConstant entry is nullptr.
+///     - ::UR_RESULT_ERROR_INVALID_SPEC_ID
+///         + Any id specified in a pSpecConstant entry is not a valid specialization constant identifier.
 ur_result_t UR_APICALL urProgramSetSpecializationConstants(
     ur_program_handle_t hProgram, ///< [in] handle of the Program object
     uint32_t count, ///< [in] the number of elements in the pSpecConstants array
@@ -3385,6 +3390,11 @@ ur_result_t UR_APICALL urKernelSetArgMemObj(
 ///         + `count == 0`
 ///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
 ///         + If ::UR_DEVICE_INFO_KERNEL_SET_SPECIALIZATION_CONSTANTS query is false
+///     - ::UR_RESULT_ERROR_INVALID_VALUE
+///         + Any size specified in a pSpecConstant entry does not match the specialization constant in the module.
+///         + Any pValue specified in a pSpecConstant entry is nullptr.
+///     - ::UR_RESULT_ERROR_INVALID_SPEC_ID
+///         + Any id specified in a pSpecConstant entry is not a valid specialization constant identifier.
 ur_result_t UR_APICALL urKernelSetSpecializationConstants(
     ur_kernel_handle_t hKernel, ///< [in] handle of the kernel object
     uint32_t count, ///< [in] the number of elements in the pSpecConstants array

test/conformance/kernel/kernel_adapter_level_zero.match

@@ -19,7 +19,3 @@ urKernelSetExecInfoTest.SuccessIndirectAccess/Intel_R__oneAPI_Unified_Runtime_ov
 urKernelSetExecInfoUSMPointersTest.SuccessHost/Intel_R__oneAPI_Unified_Runtime_over_Level_Zero___{{.*}}_
 urKernelSetExecInfoUSMPointersTest.SuccessDevice/Intel_R__oneAPI_Unified_Runtime_over_Level_Zero___{{.*}}_
 urKernelSetExecInfoUSMPointersTest.SuccessShared/Intel_R__oneAPI_Unified_Runtime_over_Level_Zero___{{.*}}_
-urKernelSetSpecializationConstantsTest.Success/Intel_R__oneAPI_Unified_Runtime_over_Level_Zero___{{.*}}_
-urKernelSetSpecializationConstantsTest.InvalidNullHandleKernel/Intel_R__oneAPI_Unified_Runtime_over_Level_Zero___{{.*}}_
-urKernelSetSpecializationConstantsTest.InvalidNullPointerSpecConstants/Intel_R__oneAPI_Unified_Runtime_over_Level_Zero___{{.*}}_
-urKernelSetSpecializationConstantsTest.InvalidSizeCount/Intel_R__oneAPI_Unified_Runtime_over_Level_Zero___{{.*}}_

test/conformance/kernel/kernel_adapter_opencl.match

@@ -1,5 +1 @@
 urKernelSetArgValueTest.InvalidKernelArgumentSize/Intel_R__OpenCL___{{.*}}
-urKernelSetSpecializationConstantsTest.Success/Intel_R__OpenCL___{{.*}}
-urKernelSetSpecializationConstantsTest.InvalidNullHandleKernel/Intel_R__OpenCL___{{.*}}
-urKernelSetSpecializationConstantsTest.InvalidNullPointerSpecConstants/Intel_R__OpenCL___{{.*}}
-urKernelSetSpecializationConstantsTest.InvalidSizeCount/Intel_R__OpenCL___{{.*}}

test/conformance/kernel/urKernelSetSpecializationConstants.cpp

@@ -27,6 +27,28 @@ struct urKernelSetSpecializationConstantsTest : uur::urBaseKernelExecutionTest {
 };
 UUR_INSTANTIATE_KERNEL_TEST_SUITE_P(urKernelSetSpecializationConstantsTest);
 
+struct urKernelSetSpecializationConstantsNegativeTest
+    : uur::urBaseKernelExecutionTest {
+    void SetUp() override {
+        UUR_RETURN_ON_FATAL_FAILURE(urBaseKernelExecutionTest::SetUp());
+        bool supports_kernel_spec_constant = false;
+        ASSERT_SUCCESS(urDeviceGetInfo(
+            device, UR_DEVICE_INFO_KERNEL_SET_SPECIALIZATION_CONSTANTS,
+            sizeof(supports_kernel_spec_constant),
+            &supports_kernel_spec_constant, nullptr));
+        if (supports_kernel_spec_constant) {
+            GTEST_SKIP() << "Device supports setting kernel spec constants.";
+        }
+        Build();
+    }
+
+    uint32_t spec_value = 42;
+    ur_specialization_constant_info_t info = {0, sizeof(spec_value),
+                                              &spec_value};
+};
+UUR_INSTANTIATE_KERNEL_TEST_SUITE_P(
+    urKernelSetSpecializationConstantsNegativeTest);
+
 TEST_P(urKernelSetSpecializationConstantsTest, Success) {
     ASSERT_SUCCESS(urKernelSetSpecializationConstants(kernel, 1, &info));
 
@@ -36,6 +58,11 @@ TEST_P(urKernelSetSpecializationConstantsTest, Success) {
     ValidateBuffer<uint32_t>(buffer, sizeof(spec_value), spec_value);
 }
 
+TEST_P(urKernelSetSpecializationConstantsNegativeTest, Unsupported) {
+    ASSERT_EQ_RESULT(UR_RESULT_ERROR_UNSUPPORTED_FEATURE,
+                     urKernelSetSpecializationConstants(kernel, 1, &info));
+}
+
 TEST_P(urKernelSetSpecializationConstantsTest, InvalidNullHandleKernel) {
     ASSERT_EQ_RESULT(UR_RESULT_ERROR_INVALID_NULL_HANDLE,
                      urKernelSetSpecializationConstants(nullptr, 1, &info));
@@ -51,3 +78,23 @@ TEST_P(urKernelSetSpecializationConstantsTest, InvalidSizeCount) {
     ASSERT_EQ_RESULT(UR_RESULT_ERROR_INVALID_SIZE,
                      urKernelSetSpecializationConstants(kernel, 0, &info));
 }
+
+TEST_P(urKernelSetSpecializationConstantsTest, InvalidValueSize) {
+    ur_specialization_constant_info_t bad_info = {0, 0x1000, &spec_value};
+    ASSERT_EQ_RESULT(UR_RESULT_ERROR_INVALID_VALUE,
+                     urKernelSetSpecializationConstants(kernel, 1, &bad_info));
+}
+
+TEST_P(urKernelSetSpecializationConstantsTest, InvalidValueId) {
+    ur_specialization_constant_info_t bad_info = {999, sizeof(spec_value),
+                                                  &spec_value};
+    ASSERT_EQ_RESULT(UR_RESULT_ERROR_INVALID_SPEC_ID,
+                     urKernelSetSpecializationConstants(kernel, 1, &bad_info));
+}
+
+TEST_P(urKernelSetSpecializationConstantsTest, InvalidValuePtr) {
+    ur_specialization_constant_info_t bad_info = {0, sizeof(spec_value),
+                                                  nullptr};
+    ASSERT_EQ_RESULT(UR_RESULT_ERROR_INVALID_VALUE,
+                     urKernelSetSpecializationConstants(kernel, 1, &bad_info));
+}

test/conformance/program/program_adapter_cuda.match

@@ -22,3 +22,6 @@
 {{OPT}}urProgramGetInfoTest.InvalidNullHandleProgram/NVIDIA_CUDA_BACKEND___{{.*}}___UR_PROGRAM_INFO_KERNEL_NAMES
 {{OPT}}urProgramLinkTest.Success/NVIDIA_CUDA_BACKEND___{{.*}}_
 {{OPT}}urProgramSetSpecializationConstantsTest.Success/NVIDIA_CUDA_BACKEND___{{.*}}_
+{{OPT}}urProgramSetSpecializationConstantsTest.InvalidValueSize/NVIDIA_CUDA_BACKEND___{{.*}}_
+{{OPT}}urProgramSetSpecializationConstantsTest.InvalidValueId/NVIDIA_CUDA_BACKEND___{{.*}}_
+{{OPT}}urProgramSetSpecializationConstantsTest.InvalidValuePtr/NVIDIA_CUDA_BACKEND___{{.*}}_

test/conformance/program/program_adapter_hip.match

@@ -22,4 +22,7 @@
 {{OPT}}urProgramGetInfoTest.InvalidNullHandleProgram/AMD_HIP_BACKEND___{{.*}}___UR_PROGRAM_INFO_KERNEL_NAMES
 {{OPT}}urProgramLinkTest.Success/AMD_HIP_BACKEND___{{.*}}_
 {{OPT}}urProgramSetSpecializationConstantsTest.Success/AMD_HIP_BACKEND___{{.*}}_
+{{OPT}}urProgramSetSpecializationConstantsTest.InvalidValueSize/AMD_HIP_BACKEND___{{.*}}_
+{{OPT}}urProgramSetSpecializationConstantsTest.InvalidValueId/AMD_HIP_BACKEND___{{.*}}_
+{{OPT}}urProgramSetSpecializationConstantsTest.InvalidValuePtr/AMD_HIP_BACKEND___{{.*}}_
 {{OPT}}{{Segmentation fault|Aborted}}

test/conformance/program/urProgramSetSpecializationConstants.cpp

@@ -46,3 +46,26 @@ TEST_P(urProgramSetSpecializationConstantsTest, InvalidSizeCount) {
     ASSERT_EQ_RESULT(UR_RESULT_ERROR_INVALID_SIZE,
                      urProgramSetSpecializationConstants(program, 0, &info));
 }
+
+TEST_P(urProgramSetSpecializationConstantsTest, InvalidValueSize) {
+    ur_specialization_constant_info_t bad_info = {0, 0x1000, &spec_value};
+    ASSERT_EQ_RESULT(
+        UR_RESULT_ERROR_INVALID_VALUE,
+        urProgramSetSpecializationConstants(program, 1, &bad_info));
+}
+
+TEST_P(urProgramSetSpecializationConstantsTest, InvalidValueId) {
+    ur_specialization_constant_info_t bad_info = {999, sizeof(spec_value),
+                                                  &spec_value};
+    ASSERT_EQ_RESULT(
+        UR_RESULT_ERROR_INVALID_SPEC_ID,
+        urProgramSetSpecializationConstants(program, 1, &bad_info));
+}
+
+TEST_P(urProgramSetSpecializationConstantsTest, InvalidValuePtr) {
+    ur_specialization_constant_info_t bad_info = {0, sizeof(spec_value),
+                                                  nullptr};
+    ASSERT_EQ_RESULT(
+        UR_RESULT_ERROR_INVALID_VALUE,
+        urProgramSetSpecializationConstants(program, 1, &bad_info));
+}