[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 a number of
  adapters.

include/ur_api.h

@@ -502,6 +502,7 @@ typedef enum ur_result_t {
  UR_RESULT_ERROR_LAYER_NOT_PRESENT = 67, ///< A requested layer was not found by the loader.
  UR_RESULT_ERROR_IN_EVENT_LIST_EXEC_STATUS = 68, ///< An event in the provided wait list has ::UR_EVENT_STATUS_ERROR.
  UR_RESULT_ERROR_DEVICE_NOT_AVAILABLE = 69, ///< Device in question has `::UR_DEVICE_INFO_AVAILABLE == false`
+ 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
@@ -4640,6 +4641,11 @@ typedef struct ur_specialization_constant_info_t {
 /// + `NULL == pSpecConstants`
 /// - ::UR_RESULT_ERROR_INVALID_SIZE
 /// + `count == 0`
+/// - ::UR_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.
+/// - ::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
@@ -5226,6 +5232,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
+/// + 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.
+/// - ::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

@@ -1588,6 +1588,9 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_result_t value) {
  case UR_RESULT_ERROR_DEVICE_NOT_AVAILABLE:
  os << "UR_RESULT_ERROR_DEVICE_NOT_AVAILABLE";
  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: "An event in the provided wait list has $X_EVENT_STATUS_ERROR."
  - name: ERROR_DEVICE_NOT_AVAILABLE
  desc: "Device in question has `$X_DEVICE_INFO_AVAILABLE == false`"
+ - 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:
+ - "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."
+ - $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

@@ -542,6 +542,11 @@ params:
 returns:
  - $X_RESULT_ERROR_INVALID_SIZE:
  - "`count == 0`"
+ - $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."
+ - $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

@@ -410,3 +410,8 @@ UR_APIEXPORT ur_result_t UR_APICALL urKernelGetSuggestedLocalWorkSize(
  pSuggestedLocalWorkSize);
  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;
  pDdiTable->pfnGetSuggestedLocalWorkSize = urKernelGetSuggestedLocalWorkSize;
  return UR_RESULT_SUCCESS;
 }

source/adapters/level_zero/device.cpp

@@ -859,6 +859,8 @@ UR_APIEXPORT ur_result_t UR_APICALL urDeviceGetInfo(
  return ReturnValue(ur_bool_t{false});
  case UR_DEVICE_INFO_IMAGE_SRGB:
  return ReturnValue(ur_bool_t{false});
+ case UR_DEVICE_INFO_KERNEL_SET_SPECIALIZATION_CONSTANTS:
+ return ReturnValue(ur_bool_t{false});
 
  case UR_DEVICE_INFO_QUEUE_ON_DEVICE_PROPERTIES:
  case UR_DEVICE_INFO_QUEUE_ON_HOST_PROPERTIES: {
@@ -1054,8 +1056,6 @@ UR_APIEXPORT ur_result_t UR_APICALL urDeviceGetInfo(
  // L0 does not support sampling 1D USM sampled image data.
  return ReturnValue(false);
  }
- case UR_DEVICE_INFO_KERNEL_SET_SPECIALIZATION_CONSTANTS:
- return ReturnValue(false);
  case UR_DEVICE_INFO_GLOBAL_VARIABLE_SUPPORT:
  return ReturnValue(true);
  default:

source/adapters/native_cpu/kernel.cpp

@@ -271,7 +271,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urKernelSetSpecializationConstants(
  std::ignore = count;
  std::ignore = pSpecConstants;
 
- DIE_NO_IMPLEMENTATION
+ return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
 }
 
 UR_APIEXPORT ur_result_t UR_APICALL urKernelGetNativeHandle(

source/adapters/opencl/common.cpp

@@ -95,6 +95,8 @@ ur_result_t mapCLErrorToUR(cl_int Result) {
  return UR_RESULT_ERROR_INVALID_QUEUE;
  case CL_INVALID_ARG_SIZE:
  return UR_RESULT_ERROR_INVALID_KERNEL_ARGUMENT_SIZE;
+ case CL_INVALID_SPEC_ID:
+ return UR_RESULT_ERROR_INVALID_SPEC_ID;
  default:
  return UR_RESULT_ERROR_UNKNOWN;
  }

source/adapters/opencl/device.cpp

@@ -1031,6 +1031,9 @@ UR_APIEXPORT ur_result_t UR_APICALL urDeviceGetInfo(ur_device_handle_t hDevice,
  deviceSupportsURCommandBufferKernelUpdate(Dev, Supported));
  return ReturnValue(Supported);
  }
+ case UR_DEVICE_INFO_KERNEL_SET_SPECIALIZATION_CONSTANTS: {
+ return ReturnValue(false);
+ }
  default: {
  return UR_RESULT_ERROR_INVALID_ENUMERATION;
  }

source/adapters/opencl/kernel.cpp

@@ -430,3 +430,8 @@ UR_APIEXPORT ur_result_t UR_APICALL urKernelGetSuggestedLocalWorkSize(
  pGlobalWorkSize, pSuggestedLocalWorkSize));
  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;
  pDdiTable->pfnGetSuggestedLocalWorkSize = urKernelGetSuggestedLocalWorkSize;
  return UR_RESULT_SUCCESS;
 }

source/loader/ur_libapi.cpp

@@ -3486,6 +3486,11 @@ ur_result_t UR_APICALL urProgramGetBuildInfo(
 /// + `NULL == pSpecConstants`
 /// - ::UR_RESULT_ERROR_INVALID_SIZE
 /// + `count == 0`
+/// - ::UR_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.
+/// - ::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
@@ -4079,6 +4084,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
+/// + 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.
+/// - ::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

@@ -2981,6 +2981,11 @@ ur_result_t UR_APICALL urProgramGetBuildInfo(
 /// + `NULL == pSpecConstants`
 /// - ::UR_RESULT_ERROR_INVALID_SIZE
 /// + `count == 0`
+/// - ::UR_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.
+/// - ::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
@@ -3470,6 +3475,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
+/// + 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.
+/// - ::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_opencl.match

@@ -1 +1,2 @@
 urKernelGetInfoTest.Success/Intel_R__OpenCL_{{.*}}_UR_KERNEL_INFO_NUM_REGS
+urKernelSetArgValueTest.InvalidKernelArgumentSize/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

@@ -9,5 +9,8 @@ urProgramGetInfoTest.Success/NVIDIA_CUDA_BACKEND___{{.*}}___UR_PROGRAM_INFO_NUM_
 urProgramGetInfoTest.Success/NVIDIA_CUDA_BACKEND___{{.*}}___UR_PROGRAM_INFO_KERNEL_NAMES
 {{OPT}}urProgramSetSpecializationConstantsTest.Success/NVIDIA_CUDA_BACKEND___{{.*}}
 {{OPT}}urProgramSetSpecializationConstantsTest.UseDefaultValue/NVIDIA_CUDA_BACKEND___{{.*}}
-urProgramSetMultipleSpecializationConstantsTest.MultipleCalls/NVIDIA_CUDA_BACKEND___{{.*}}
-urProgramSetMultipleSpecializationConstantsTest.SingleCall/NVIDIA_CUDA_BACKEND___{{.*}}
+urProgramSetSpecializationConstantsTest.InvalidValueSize/NVIDIA_CUDA_BACKEND___{{.*}}_
+urProgramSetSpecializationConstantsTest.InvalidValueId/NVIDIA_CUDA_BACKEND___{{.*}}_
+urProgramSetSpecializationConstantsTest.InvalidValuePtr/NVIDIA_CUDA_BACKEND___{{.*}}_
+urProgramSetMultipleSpecializationConstantsTest.MultipleCalls/NVIDIA_CUDA_BACKEND___{{.*}}_
+urProgramSetMultipleSpecializationConstantsTest.SingleCall/NVIDIA_CUDA_BACKEND___{{.*}}_

test/conformance/program/program_adapter_hip.match

@@ -8,7 +8,11 @@ urProgramGetInfoTest.Success/AMD_HIP_BACKEND___{{.*}}___UR_PROGRAM_INFO_KERNEL_N
 # HIP hasn't implemented urProgramLink
 {{OPT}}urProgramLinkTest.Success/AMD_HIP_BACKEND___{{.*}}_
 
+# Hip doesn't support specialization constants
 urProgramSetSpecializationConstantsTest.Success/AMD_HIP_BACKEND___{{.*}}_
 urProgramSetSpecializationConstantsTest.UseDefaultValue/AMD_HIP_BACKEND___{{.*}}_
+urProgramSetSpecializationConstantsTest.InvalidValueSize/AMD_HIP_BACKEND___{{.*}}_
+urProgramSetSpecializationConstantsTest.InvalidValueId/AMD_HIP_BACKEND___{{.*}}_
+urProgramSetSpecializationConstantsTest.InvalidValuePtr/AMD_HIP_BACKEND___{{.*}}_
 urProgramSetMultipleSpecializationConstantsTest.MultipleCalls/AMD_HIP_BACKEND___{{.*}}_
 urProgramSetMultipleSpecializationConstantsTest.SingleCall/AMD_HIP_BACKEND___{{.*}}_

test/conformance/program/urProgramSetSpecializationConstants.cpp

@@ -141,3 +141,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));
+}