Rename INVALID_FUNCTION_NAME to FUNCTION_ADDRESS_NOT_AVAILABLE.

aarongreig · aarongreig · commit db38dc4f7bec · 2024-06-26T15:31:41.000+01:00
This lines up better with the original PI error code and what it was
meant to convey.

Also clarify the spec around return codes for
urProgramGetFunctionPointer and update the relevant CTS test.
diff --git a/include/ur_api.h b/include/ur_api.h
@@ -479,7 +479,8 @@ typedef enum ur_result_t {
     UR_RESULT_ERROR_UNSUPPORTED_IMAGE_FORMAT = 55,                            ///< [Validation] image format is not supported by the device
     UR_RESULT_ERROR_INVALID_NATIVE_BINARY = 56,                               ///< [Validation] native binary is not supported by the device
     UR_RESULT_ERROR_INVALID_GLOBAL_NAME = 57,                                 ///< [Validation] global variable is not found in the program
-    UR_RESULT_ERROR_INVALID_FUNCTION_NAME = 58,                               ///< [Validation] function name is not found in the program
+    UR_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE = 58,                      ///< [Validation] function name is in the program but its address could not
+                                                                              ///< be determined
     UR_RESULT_ERROR_INVALID_GROUP_SIZE_DIMENSION = 59,                        ///< [Validation] group size dimension is not valid for the kernel or
                                                                               ///< device
     UR_RESULT_ERROR_INVALID_GLOBAL_WIDTH_DIMENSION = 60,                      ///< [Validation] global width dimension is not valid for the kernel or
@@ -4354,8 +4355,8 @@ urProgramRelease(
 /// @details
 ///     - Retrieves a pointer to the functions with the given name and defined
 ///       in the given program.
-///     - ::UR_RESULT_ERROR_INVALID_FUNCTION_NAME is returned if the function
-///       can not be obtained.
+///     - ::UR_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE is returned if the
+///       function can not be obtained.
 ///     - The application may call this function from simultaneous threads for
 ///       the same device.
 ///     - The implementation of this function should be thread-safe.
@@ -4375,6 +4376,10 @@ urProgramRelease(
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == pFunctionName`
 ///         + `NULL == ppFunctionPointer`
+///     - ::UR_RESULT_ERROR_INVALID_KERNEL_NAME
+///         + If `pFunctionName` couldn't be found in `hProgram`.
+///     - ::UR_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE
+///         + If `pFunctionName` could be located, but its address couldn't be retrieved.
 UR_APIEXPORT ur_result_t UR_APICALL
 urProgramGetFunctionPointer(
     ur_device_handle_t hDevice,   ///< [in] handle of the device to retrieve pointer for.
diff --git a/include/ur_print.hpp b/include/ur_print.hpp
@@ -1525,8 +1525,8 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_result_t value) {
     case UR_RESULT_ERROR_INVALID_GLOBAL_NAME:
         os << "UR_RESULT_ERROR_INVALID_GLOBAL_NAME";
         break;
-    case UR_RESULT_ERROR_INVALID_FUNCTION_NAME:
-        os << "UR_RESULT_ERROR_INVALID_FUNCTION_NAME";
+    case UR_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE:
+        os << "UR_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE";
         break;
     case UR_RESULT_ERROR_INVALID_GROUP_SIZE_DIMENSION:
         os << "UR_RESULT_ERROR_INVALID_GROUP_SIZE_DIMENSION";
diff --git a/scripts/core/common.yml b/scripts/core/common.yml
@@ -251,8 +251,8 @@ etors:
       desc: "[Validation] native binary is not supported by the device"
     - name: ERROR_INVALID_GLOBAL_NAME
       desc: "[Validation] global variable is not found in the program"
-    - name: ERROR_INVALID_FUNCTION_NAME
-      desc: "[Validation] function name is not found in the program"
+    - name: ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE
+      desc: "[Validation] function name is in the program but its address could not be determined"
     - name: ERROR_INVALID_GROUP_SIZE_DIMENSION
       desc: "[Validation] group size dimension is not valid for the kernel or device"
     - name: ERROR_INVALID_GLOBAL_WIDTH_DIMENSION
diff --git a/scripts/core/program.yml b/scripts/core/program.yml
@@ -291,7 +291,7 @@ analogue:
     - "**clGetDeviceFunctionPointerINTEL**"
 details:
     - "Retrieves a pointer to the functions with the given name and defined in the given program."
-    - "$X_RESULT_ERROR_INVALID_FUNCTION_NAME is returned if the function can not be obtained."
+    - "$X_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE is returned if the function can not be obtained."
     - "The application may call this function from simultaneous threads for the same device."
     - "The implementation of this function should be thread-safe."
 params:
@@ -313,6 +313,11 @@ params:
       name: ppFunctionPointer
       desc: |
             [out] Returns the pointer to the function if it is found in the program.
+returns:
+    - $X_RESULT_ERROR_INVALID_KERNEL_NAME:
+        - "If `pFunctionName` couldn't be found in `hProgram`."
+    - $X_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE:
+        - "If `pFunctionName` could be located, but its address couldn't be retrieved."
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Retrieves a pointer to a device global variable."
diff --git a/source/adapters/cuda/program.cpp b/source/adapters/cuda/program.cpp
@@ -503,7 +503,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urProgramGetFunctionPointer(
     UR_CHECK_ERROR(Ret);
   if (Ret == CUDA_ERROR_NOT_FOUND) {
     *ppFunctionPointer = 0;
-    Result = UR_RESULT_ERROR_INVALID_FUNCTION_NAME;
+    Result = UR_RESULT_ERROR_INVALID_KERNEL_NAME;
   }
 
   return Result;
diff --git a/source/adapters/hip/program.cpp b/source/adapters/hip/program.cpp
@@ -539,7 +539,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urProgramGetFunctionPointer(
     UR_CHECK_ERROR(Ret);
   if (Ret == hipErrorNotFound) {
     *ppFunctionPointer = 0;
-    Result = UR_RESULT_ERROR_INVALID_FUNCTION_NAME;
+    Result = UR_RESULT_ERROR_INVALID_KERNEL_NAME;
   }
 
   return Result;
diff --git a/source/adapters/level_zero/common.cpp b/source/adapters/level_zero/common.cpp
@@ -46,9 +46,8 @@ ur_result_t ze2urResult(ze_result_t ZeResult) {
   case ZE_RESULT_ERROR_INVALID_NATIVE_BINARY:
     return UR_RESULT_ERROR_INVALID_BINARY;
   case ZE_RESULT_ERROR_INVALID_KERNEL_NAME:
-    return UR_RESULT_ERROR_INVALID_KERNEL_NAME;
   case ZE_RESULT_ERROR_INVALID_FUNCTION_NAME:
-    return UR_RESULT_ERROR_INVALID_FUNCTION_NAME;
+    return UR_RESULT_ERROR_INVALID_KERNEL_NAME;
   case ZE_RESULT_ERROR_OVERLAPPING_REGIONS:
     return UR_RESULT_ERROR_INVALID_OPERATION;
   case ZE_RESULT_ERROR_INVALID_GROUP_SIZE_DIMENSION:
diff --git a/source/adapters/level_zero/common.hpp b/source/adapters/level_zero/common.hpp
@@ -145,8 +145,8 @@ static auto getUrResultString = [](ur_result_t Result) {
     return "UR_RESULT_ERROR_INVALID_NATIVE_BINARY";
   case UR_RESULT_ERROR_INVALID_GLOBAL_NAME:
     return "UR_RESULT_ERROR_INVALID_GLOBAL_NAME";
-  case UR_RESULT_ERROR_INVALID_FUNCTION_NAME:
-    return "UR_RESULT_ERROR_INVALID_FUNCTION_NAME";
+  case UR_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE:
+    return "UR_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE";
   case UR_RESULT_ERROR_INVALID_GROUP_SIZE_DIMENSION:
     return "UR_RESULT_ERROR_INVALID_GROUP_SIZE_DIMENSION";
   case UR_RESULT_ERROR_INVALID_GLOBAL_WIDTH_DIMENSION:
diff --git a/source/adapters/level_zero/program.cpp b/source/adapters/level_zero/program.cpp
@@ -570,7 +570,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urProgramGetFunctionPointer(
     // exists
     ClResult.pop_back();
     if (is_in_separated_string(ClResult, ';', std::string(FunctionName)))
-      return UR_RESULT_ERROR_INVALID_FUNCTION_NAME;
+      return UR_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE;
 
     return UR_RESULT_ERROR_INVALID_KERNEL_NAME;
   }
diff --git a/source/adapters/opencl/program.cpp b/source/adapters/opencl/program.cpp
@@ -451,10 +451,6 @@ UR_APIEXPORT ur_result_t UR_APICALL urProgramGetFunctionPointer(
           CLContext, cl_ext::ExtFuncPtrCache->clGetDeviceFunctionPointerCache,
           cl_ext::GetDeviceFunctionPointerName, &FuncT));
 
-  if (!FuncT) {
-    return UR_RESULT_ERROR_INVALID_FUNCTION_NAME;
-  }
-
   // Check if the kernel name exists to prevent the OpenCL runtime from throwing
   // an exception with the cpu runtime.
   // TODO: Use fallback search method if the clGetDeviceFunctionPointerINTEL
@@ -488,7 +484,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urProgramGetFunctionPointer(
   // that the function name is invalid.
   if (CLResult == CL_INVALID_ARG_VALUE) {
     *ppFunctionPointer = 0;
-    return UR_RESULT_ERROR_INVALID_FUNCTION_NAME;
+    return UR_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE;
   }
 
   CL_RETURN_ON_FAILURE(CLResult);
diff --git a/source/loader/ur_libapi.cpp b/source/loader/ur_libapi.cpp
@@ -3222,8 +3222,8 @@ ur_result_t UR_APICALL urProgramRelease(
 /// @details
 ///     - Retrieves a pointer to the functions with the given name and defined
 ///       in the given program.
-///     - ::UR_RESULT_ERROR_INVALID_FUNCTION_NAME is returned if the function
-///       can not be obtained.
+///     - ::UR_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE is returned if the
+///       function can not be obtained.
 ///     - The application may call this function from simultaneous threads for
 ///       the same device.
 ///     - The implementation of this function should be thread-safe.
@@ -3243,6 +3243,10 @@ ur_result_t UR_APICALL urProgramRelease(
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == pFunctionName`
 ///         + `NULL == ppFunctionPointer`
+///     - ::UR_RESULT_ERROR_INVALID_KERNEL_NAME
+///         + If `pFunctionName` couldn't be found in `hProgram`.
+///     - ::UR_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE
+///         + If `pFunctionName` could be located, but its address couldn't be retrieved.
 ur_result_t UR_APICALL urProgramGetFunctionPointer(
     ur_device_handle_t
         hDevice, ///< [in] handle of the device to retrieve pointer for.
diff --git a/source/ur_api.cpp b/source/ur_api.cpp
@@ -2746,8 +2746,8 @@ ur_result_t UR_APICALL urProgramRelease(
 /// @details
 ///     - Retrieves a pointer to the functions with the given name and defined
 ///       in the given program.
-///     - ::UR_RESULT_ERROR_INVALID_FUNCTION_NAME is returned if the function
-///       can not be obtained.
+///     - ::UR_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE is returned if the
+///       function can not be obtained.
 ///     - The application may call this function from simultaneous threads for
 ///       the same device.
 ///     - The implementation of this function should be thread-safe.
@@ -2767,6 +2767,10 @@ ur_result_t UR_APICALL urProgramRelease(
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == pFunctionName`
 ///         + `NULL == ppFunctionPointer`
+///     - ::UR_RESULT_ERROR_INVALID_KERNEL_NAME
+///         + If `pFunctionName` couldn't be found in `hProgram`.
+///     - ::UR_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE
+///         + If `pFunctionName` could be located, but its address couldn't be retrieved.
 ur_result_t UR_APICALL urProgramGetFunctionPointer(
     ur_device_handle_t
         hDevice, ///< [in] handle of the device to retrieve pointer for.
diff --git a/test/conformance/program/program_adapter_level_zero.match b/test/conformance/program/program_adapter_level_zero.match
@@ -2,5 +2,5 @@ urProgramCreateWithNativeHandleTest.Success/Intel_R__oneAPI_Unified_Runtime_over
 urProgramCreateWithNativeHandleTest.InvalidNullHandleContext/Intel_R__oneAPI_Unified_Runtime_over_Level_Zero___{{.*}}_
 urProgramCreateWithNativeHandleTest.InvalidNullPointerProgram/Intel_R__oneAPI_Unified_Runtime_over_Level_Zero___{{.*}}_
 urProgramGetBuildInfoTest.Success/Intel_R__oneAPI_Unified_Runtime_over_Level_Zero___{{.*}}_UR_PROGRAM_BUILD_INFO_STATUS
-urProgramGetFunctionPointerTest.InvalidFunctionName/Intel_R__oneAPI_Unified_Runtime_over_Level_Zero___{{.*}}_
+urProgramGetFunctionPointerTest.InvalidKernelName/Intel_R__oneAPI_Unified_Runtime_over_Level_Zero___{{.*}}_
 Aborted
diff --git a/test/conformance/program/program_adapter_native_cpu.match b/test/conformance/program/program_adapter_native_cpu.match
@@ -42,7 +42,7 @@
 {{OPT}}urProgramGetBuildInfoTest.InvalidEnumeration/SYCL_NATIVE_CPU___SYCL_Native_CPU___UR_PROGRAM_BUILD_INFO_BINARY_TYPE
 {{OPT}}urProgramGetBuildInfoSingleTest.LogIsNullTerminated/SYCL_NATIVE_CPU___SYCL_Native_CPU_
 {{OPT}}urProgramGetFunctionPointerTest.Success/SYCL_NATIVE_CPU___SYCL_Native_CPU_
-{{OPT}}urProgramGetFunctionPointerTest.InvalidFunctionName/SYCL_NATIVE_CPU___SYCL_Native_CPU_
+{{OPT}}urProgramGetFunctionPointerTest.InvalidKernelName/SYCL_NATIVE_CPU___SYCL_Native_CPU_
 {{OPT}}urProgramGetFunctionPointerTest.InvalidNullHandleDevice/SYCL_NATIVE_CPU___SYCL_Native_CPU_
 {{OPT}}urProgramGetFunctionPointerTest.InvalidNullHandleProgram/SYCL_NATIVE_CPU___SYCL_Native_CPU_
 {{OPT}}urProgramGetFunctionPointerTest.InvalidNullPointerFunctionName/SYCL_NATIVE_CPU___SYCL_Native_CPU_
diff --git a/test/conformance/program/program_adapter_opencl.match b/test/conformance/program/program_adapter_opencl.match
@@ -1,3 +1,2 @@
 urProgramCreateWithILTest.BuildInvalidProgram/Intel_R__OpenCL___{{.*}}_
-urProgramGetFunctionPointerTest.InvalidFunctionName/Intel_R__OpenCL___{{.*}}_
 urProgramGetInfoTest.Success/Intel_R__OpenCL___{{.*}}___UR_PROGRAM_INFO_SOURCE
diff --git a/test/conformance/program/urProgramGetFunctionPointer.cpp b/test/conformance/program/urProgramGetFunctionPointer.cpp
@@ -26,10 +26,10 @@ TEST_P(urProgramGetFunctionPointerTest, Success) {
     ASSERT_NE(function_pointer, nullptr);
 }
 
-TEST_P(urProgramGetFunctionPointerTest, InvalidFunctionName) {
+TEST_P(urProgramGetFunctionPointerTest, InvalidKernelName) {
     void *function_pointer = nullptr;
     std::string missing_function = "aFakeFunctionName";
-    ASSERT_EQ_RESULT(UR_RESULT_ERROR_INVALID_FUNCTION_NAME,
+    ASSERT_EQ_RESULT(UR_RESULT_ERROR_INVALID_KERNEL_NAME,
                      urProgramGetFunctionPointer(device, program,
                                                  missing_function.data(),
                                                  &function_pointer));
diff --git a/test/conformance/program/urProgramGetInfo.cpp b/test/conformance/program/urProgramGetInfo.cpp
@@ -52,8 +52,8 @@ TEST_P(urProgramGetInfoTest, Success) {
                                         sizeof(binaries[0]), binaries,
                                         nullptr));
     } else {
-        ASSERT_SUCCESS(
-            urProgramGetInfo(program, property_name, 0, nullptr, &property_size));
+        ASSERT_SUCCESS(urProgramGetInfo(program, property_name, 0, nullptr,
+                                        &property_size));
         property_value.resize(property_size);
         ASSERT_SUCCESS(urProgramGetInfo(program, property_name, property_size,
                                         property_value.data(), nullptr));

Original file line number	Diff line number	Diff line change
`@@ -503,7 +503,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urProgramGetFunctionPointer(`
`503`	`503`	`UR_CHECK_ERROR(Ret);`
`504`	`504`	`if (Ret == CUDA_ERROR_NOT_FOUND) {`
`505`	`505`	`*ppFunctionPointer = 0;`
`506`		`- Result = UR_RESULT_ERROR_INVALID_FUNCTION_NAME;`
	`506`	`+ Result = UR_RESULT_ERROR_INVALID_KERNEL_NAME;`
`507`	`507`	`}`
`508`	`508`
`509`	`509`	`return Result;`
Original file line number	Diff line number	Diff line change
`@@ -539,7 +539,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urProgramGetFunctionPointer(`
`539`	`539`	`UR_CHECK_ERROR(Ret);`
`540`	`540`	`if (Ret == hipErrorNotFound) {`
`541`	`541`	`*ppFunctionPointer = 0;`
`542`		`- Result = UR_RESULT_ERROR_INVALID_FUNCTION_NAME;`
	`542`	`+ Result = UR_RESULT_ERROR_INVALID_KERNEL_NAME;`
`543`	`543`	`}`
`544`	`544`
`545`	`545`	`return Result;`
Original file line number	Diff line number	Diff line change
`@@ -570,7 +570,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urProgramGetFunctionPointer(`
`570`	`570`	`// exists`
`571`	`571`	`ClResult.pop_back();`
`572`	`572`	`if (is_in_separated_string(ClResult, ';', std::string(FunctionName)))`
`573`		`- return UR_RESULT_ERROR_INVALID_FUNCTION_NAME;`
	`573`	`+ return UR_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE;`
`574`	`574`
`575`	`575`	`return UR_RESULT_ERROR_INVALID_KERNEL_NAME;`
`576`	`576`	`}`