Update spec to make kernel validation optional

RossBrunton · RossBrunton · commit 38d12a5be477 · 2025-02-12T11:54:16.000Z
Several adapters don't support validating kernel signatures when
enqueued. To handle this, we now allow urEnqueueKernelLaunch to return
`SUCCESS` even when parameters are invalid.

Some tests have also been updated. The CUDA adapter has also been
updated to handle invalid arguments.
diff --git a/include/ur_api.h b/include/ur_api.h
@@ -7428,6 +7428,11 @@ UR_APIEXPORT ur_result_t UR_APICALL urEventSetCallback(
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Enqueue a command to execute a kernel
 ///
+/// @details
+///     - Adapters may perform validation on the number of arguments set to the
+///       kernel, but are not required to do so and may return
+///       `::UR_RESULT_SUCCESS` even for invalid invocations.
+///
 /// @remarks
 ///   _Analogues_
 ///     - **clEnqueueNDRangeKernel**
@@ -7455,8 +7460,9 @@ UR_APIEXPORT ur_result_t UR_APICALL urEventSetCallback(
 ///     - ::UR_RESULT_ERROR_INVALID_WORK_DIMENSION
 ///     - ::UR_RESULT_ERROR_INVALID_WORK_GROUP_SIZE
 ///     - ::UR_RESULT_ERROR_INVALID_VALUE
-///     - ::UR_RESULT_ERROR_INVALID_KERNEL_ARGS - "The kernel argument values
-///     have not been specified."
+///     - ::UR_RESULT_ERROR_INVALID_KERNEL_ARGS
+///         + The kernel argument values have not been specified and the adapter
+///         is able to detect this.
 ///     - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
 ///     - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
 UR_APIEXPORT ur_result_t UR_APICALL urEnqueueKernelLaunch(
diff --git a/scripts/core/enqueue.yml b/scripts/core/enqueue.yml
@@ -16,6 +16,9 @@ type: function
 desc: "Enqueue a command to execute a kernel"
 class: $xEnqueue
 name: KernelLaunch
+details:
+  - "Adapters may perform validation on the number of arguments set to the kernel, but are not required to do so and may
+    return `$X_RESULT_SUCCESS` even for invalid invocations."
 ordinal: "0"
 analogue:
     - "**clEnqueueNDRangeKernel**"
@@ -65,8 +68,8 @@ returns:
     - $X_RESULT_ERROR_INVALID_WORK_DIMENSION
     - $X_RESULT_ERROR_INVALID_WORK_GROUP_SIZE
     - $X_RESULT_ERROR_INVALID_VALUE
-    - $X_RESULT_ERROR_INVALID_KERNEL_ARGS
-        - "The kernel argument values have not been specified."
+    - $X_RESULT_ERROR_INVALID_KERNEL_ARGS:
+        - "The kernel argument values have not been specified and the adapter is able to detect this."
     - $X_RESULT_ERROR_OUT_OF_HOST_MEMORY
     - $X_RESULT_ERROR_OUT_OF_RESOURCES
 --- #--------------------------------------------------------------------------
diff --git a/source/adapters/cuda/enqueue.cpp b/source/adapters/cuda/enqueue.cpp
@@ -465,10 +465,19 @@ enqueueKernelLaunch(ur_queue_handle_t hQueue, ur_kernel_handle_t hKernel,
     }
 
     auto &ArgPointers = hKernel->getArgPointers();
-    UR_CHECK_ERROR(cuLaunchKernel(
-        CuFunc, BlocksPerGrid[0], BlocksPerGrid[1], BlocksPerGrid[2],
-        ThreadsPerBlock[0], ThreadsPerBlock[1], ThreadsPerBlock[2], LocalSize,
-        CuStream, const_cast<void **>(ArgPointers.data()), nullptr));
+    try {
+      UR_CHECK_ERROR(cuLaunchKernel(
+          CuFunc, BlocksPerGrid[0], BlocksPerGrid[1], BlocksPerGrid[2],
+          ThreadsPerBlock[0], ThreadsPerBlock[1], ThreadsPerBlock[2], LocalSize,
+          CuStream, const_cast<void **>(ArgPointers.data()), nullptr));
+    } catch (ur_result_t Err) {
+      // cuLaunchKernel returns CUDA_ERROR_INVALID_VALUE if the args are
+      // incorrect
+      if (Err == UR_RESULT_ERROR_INVALID_VALUE) {
+        return UR_RESULT_ERROR_INVALID_KERNEL_ARGS;
+      }
+      return Err;
+    }
 
     if (phEvent) {
       UR_CHECK_ERROR(RetImplEvent->record());
diff --git a/source/loader/ur_libapi.cpp b/source/loader/ur_libapi.cpp
@@ -4979,6 +4979,11 @@ ur_result_t UR_APICALL urEventSetCallback(
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Enqueue a command to execute a kernel
 ///
+/// @details
+///     - Adapters may perform validation on the number of arguments set to the
+///       kernel, but are not required to do so and may return
+///       `::UR_RESULT_SUCCESS` even for invalid invocations.
+///
 /// @remarks
 ///   _Analogues_
 ///     - **clEnqueueNDRangeKernel**
@@ -5006,8 +5011,9 @@ ur_result_t UR_APICALL urEventSetCallback(
 ///     - ::UR_RESULT_ERROR_INVALID_WORK_DIMENSION
 ///     - ::UR_RESULT_ERROR_INVALID_WORK_GROUP_SIZE
 ///     - ::UR_RESULT_ERROR_INVALID_VALUE
-///     - ::UR_RESULT_ERROR_INVALID_KERNEL_ARGS - "The kernel argument values
-///     have not been specified."
+///     - ::UR_RESULT_ERROR_INVALID_KERNEL_ARGS
+///         + The kernel argument values have not been specified and the adapter
+///         is able to detect this.
 ///     - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
 ///     - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
 ur_result_t UR_APICALL urEnqueueKernelLaunch(
diff --git a/source/ur_api.cpp b/source/ur_api.cpp
@@ -4344,6 +4344,11 @@ ur_result_t UR_APICALL urEventSetCallback(
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Enqueue a command to execute a kernel
 ///
+/// @details
+///     - Adapters may perform validation on the number of arguments set to the
+///       kernel, but are not required to do so and may return
+///       `::UR_RESULT_SUCCESS` even for invalid invocations.
+///
 /// @remarks
 ///   _Analogues_
 ///     - **clEnqueueNDRangeKernel**
@@ -4371,8 +4376,9 @@ ur_result_t UR_APICALL urEventSetCallback(
 ///     - ::UR_RESULT_ERROR_INVALID_WORK_DIMENSION
 ///     - ::UR_RESULT_ERROR_INVALID_WORK_GROUP_SIZE
 ///     - ::UR_RESULT_ERROR_INVALID_VALUE
-///     - ::UR_RESULT_ERROR_INVALID_KERNEL_ARGS - "The kernel argument values
-///     have not been specified."
+///     - ::UR_RESULT_ERROR_INVALID_KERNEL_ARGS
+///         + The kernel argument values have not been specified and the adapter
+///         is able to detect this.
 ///     - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
 ///     - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
 ur_result_t UR_APICALL urEnqueueKernelLaunch(
diff --git a/test/conformance/enqueue/urEnqueueKernelLaunch.cpp b/test/conformance/enqueue/urEnqueueKernelLaunch.cpp
@@ -142,26 +142,15 @@ TEST_P(urEnqueueKernelLaunchTest, InvalidWorkGroupSize) {
 }
 
 TEST_P(urEnqueueKernelLaunchTest, InvalidKernelArgs) {
-  // Cuda and hip both lack any way to validate kernel args
-  UUR_KNOWN_FAILURE_ON(uur::CUDA{}, uur::HIP{});
-  UUR_KNOWN_FAILURE_ON(uur::LevelZero{}, uur::LevelZeroV2{});
-
-  ur_platform_backend_t backend;
-  ASSERT_SUCCESS(urPlatformGetInfo(platform, UR_PLATFORM_INFO_BACKEND,
-                                   sizeof(ur_platform_backend_t), &backend,
-                                   nullptr));
-
-  if (backend == UR_PLATFORM_BACKEND_CUDA ||
-      backend == UR_PLATFORM_BACKEND_HIP ||
-      backend == UR_PLATFORM_BACKEND_LEVEL_ZERO) {
-    GTEST_FAIL() << "AMD, L0 and Nvidia can't check kernel arguments.";
-  }
+  // Seems to segfault
+  UUR_KNOWN_FAILURE_ON(uur::HIP{});
 
   // Enqueue kernel without setting any args
-  ASSERT_EQ_RESULT(urEnqueueKernelLaunch(queue, kernel, n_dimensions,
-                                         &global_offset, &global_size, nullptr,
-                                         0, nullptr, nullptr),
-                   UR_RESULT_ERROR_INVALID_KERNEL_ARGS);
+  auto error =
+      urEnqueueKernelLaunch(queue, kernel, n_dimensions, &global_offset,
+                            &global_size, nullptr, 0, nullptr, nullptr);
+  ASSERT_TRUE(error == UR_RESULT_ERROR_INVALID_KERNEL_ARGS ||
+              error == UR_RESULT_SUCCESS);
 }
 
 TEST_P(urEnqueueKernelLaunchKernelWgSizeTest, Success) {
