Rename INVALID_FUNCTION_NAME to FUNCTION_ADDRESS_NOT_AVAILABLE.

aarongreig · aarongreig · commit 98624fc608c6 · 2023-11-29T16:29:01.000Z
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.py b/include/ur.py
@@ -428,7 +428,8 @@ class ur_result_v(IntEnum):
     ERROR_UNSUPPORTED_IMAGE_FORMAT = 56             ## [Validation] image format is not supported by the device
     ERROR_INVALID_NATIVE_BINARY = 57                ## [Validation] native binary is not supported by the device
     ERROR_INVALID_GLOBAL_NAME = 58                  ## [Validation] global variable is not found in the program
-    ERROR_INVALID_FUNCTION_NAME = 59                ## [Validation] function name is not found in the program
+    ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE = 59       ## [Validation] function name is in the program but its address could not
+                                                    ## be determined
     ERROR_INVALID_GROUP_SIZE_DIMENSION = 60         ## [Validation] group size dimension is not valid for the kernel or
                                                     ## device
     ERROR_INVALID_GLOBAL_WIDTH_DIMENSION = 61       ## [Validation] global width dimension is not valid for the kernel or
diff --git a/include/ur_api.h b/include/ur_api.h
@@ -456,7 +456,8 @@ typedef enum ur_result_t {
     UR_RESULT_ERROR_UNSUPPORTED_IMAGE_FORMAT = 56,                            ///< [Validation] image format is not supported by the device
     UR_RESULT_ERROR_INVALID_NATIVE_BINARY = 57,                               ///< [Validation] native binary is not supported by the device
     UR_RESULT_ERROR_INVALID_GLOBAL_NAME = 58,                                 ///< [Validation] global variable is not found in the program
-    UR_RESULT_ERROR_INVALID_FUNCTION_NAME = 59,                               ///< [Validation] function name is not found in the program
+    UR_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE = 59,                      ///< [Validation] function name is in the program but its address could not
+                                                                              ///< be determined
     UR_RESULT_ERROR_INVALID_GROUP_SIZE_DIMENSION = 60,                        ///< [Validation] group size dimension is not valid for the kernel or
                                                                               ///< device
     UR_RESULT_ERROR_INVALID_GLOBAL_WIDTH_DIMENSION = 61,                      ///< [Validation] global width dimension is not valid for the kernel or
@@ -4132,8 +4133,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.
+///     - RESULT_ERROR_INVALID_FUNCTION_NAME 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.
@@ -4153,6 +4154,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/scripts/core/common.yml b/scripts/core/common.yml
@@ -253,8 +253,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
@@ -287,7 +287,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."
+    - "RESULT_ERROR_INVALID_FUNCTION_NAME 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:
@@ -309,6 +309,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: enum
 desc: "Get Program object information"
diff --git a/source/adapters/cuda/command_buffer.hpp b/source/adapters/cuda/command_buffer.hpp
@@ -135,8 +135,8 @@ static inline const char *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/cuda/program.cpp b/source/adapters/cuda/program.cpp
@@ -482,7 +482,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_FUNCTION_ADDRESS_NOT_AVAILABLE;
   }
 
   return Result;
diff --git a/source/adapters/hip/program.cpp b/source/adapters/hip/program.cpp
@@ -481,7 +481,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_FUNCTION_ADDRESS_NOT_AVAILABLE;
   }
 
   return Result;
diff --git a/source/adapters/level_zero/common.cpp b/source/adapters/level_zero/common.cpp
@@ -47,7 +47,7 @@ ur_result_t ze2urResult(ze_result_t ZeResult) {
   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_FUNCTION_ADDRESS_NOT_AVAILABLE;
   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
@@ -147,8 +147,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
@@ -521,7 +521,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/native_cpu/kernel.cpp b/source/adapters/native_cpu/kernel.cpp
@@ -86,7 +86,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urKernelGetInfo(ur_kernel_handle_t hKernel,
     if (hKernel->_name) {
       return ReturnValue(hKernel->_name);
     }
-    return UR_RESULT_ERROR_INVALID_FUNCTION_NAME;
+    return UR_RESULT_ERROR_INVALID_KERNEL;
     //  case UR_KERNEL_INFO_NUM_ARGS:
     //    return ReturnValue(uint32_t{ Kernel->ZeKernelProperties->numKernelArgs
     //    });
diff --git a/source/adapters/opencl/program.cpp b/source/adapters/opencl/program.cpp
@@ -443,10 +443,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
@@ -480,7 +476,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/common/ur_params.hpp b/source/common/ur_params.hpp
@@ -1814,8 +1814,8 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_result_t value) {
         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:
diff --git a/source/loader/ur_libapi.cpp b/source/loader/ur_libapi.cpp
@@ -3093,8 +3093,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.
+///     - RESULT_ERROR_INVALID_FUNCTION_NAME 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.
@@ -3114,6 +3114,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
@@ -2613,8 +2613,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.
+///     - RESULT_ERROR_INVALID_FUNCTION_NAME 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.
@@ -2634,6 +2634,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_opencl.match b/test/conformance/program/program_adapter_opencl.match
@@ -15,7 +15,6 @@ urProgramGetBuildInfoTest.InvalidNullHandleDevice/Intel_R__OpenCL___{{.*}}___UR_
 urProgramGetBuildInfoTest.InvalidNullHandleDevice/Intel_R__OpenCL___{{.*}}___UR_PROGRAM_BUILD_INFO_OPTIONS
 urProgramGetBuildInfoTest.InvalidNullHandleDevice/Intel_R__OpenCL___{{.*}}___UR_PROGRAM_BUILD_INFO_LOG
 urProgramGetBuildInfoTest.InvalidNullHandleDevice/Intel_R__OpenCL___{{.*}}___UR_PROGRAM_BUILD_INFO_BINARY_TYPE
-urProgramGetFunctionPointerTest.InvalidFunctionName/Intel_R__OpenCL___{{.*}}_
 urProgramGetInfoTest.Success/Intel_R__OpenCL___{{.*}}___UR_PROGRAM_INFO_SOURCE
 urProgramGetInfoTest.Success/Intel_R__OpenCL___{{.*}}___UR_PROGRAM_INFO_NUM_KERNELS
 urProgramGetInfoTest.Success/Intel_R__OpenCL___{{.*}}___UR_PROGRAM_INFO_KERNEL_NAMES
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));

Original file line number	Diff line number	Diff line change
`@@ -482,7 +482,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urProgramGetFunctionPointer(`
`482`	`482`	`UR_CHECK_ERROR(Ret);`
`483`	`483`	`if (Ret == CUDA_ERROR_NOT_FOUND) {`
`484`	`484`	`*ppFunctionPointer = 0;`
`485`		`- Result = UR_RESULT_ERROR_INVALID_FUNCTION_NAME;`
	`485`	`+ Result = UR_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE;`
`486`	`486`	`}`
`487`	`487`
`488`	`488`	`return Result;`
Original file line number	Diff line number	Diff line change
`@@ -481,7 +481,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urProgramGetFunctionPointer(`
`481`	`481`	`UR_CHECK_ERROR(Ret);`
`482`	`482`	`if (Ret == hipErrorNotFound) {`
`483`	`483`	`*ppFunctionPointer = 0;`
`484`		`- Result = UR_RESULT_ERROR_INVALID_FUNCTION_NAME;`
	`484`	`+ Result = UR_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE;`
`485`	`485`	`}`
`486`	`486`
`487`	`487`	`return Result;`
Original file line number	Diff line number	Diff line change
`@@ -521,7 +521,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urProgramGetFunctionPointer(`
`521`	`521`	`// exists`
`522`	`522`	`ClResult.pop_back();`
`523`	`523`	`if (is_in_separated_string(ClResult, ';', std::string(FunctionName)))`
`524`		`- return UR_RESULT_ERROR_INVALID_FUNCTION_NAME;`
	`524`	`+ return UR_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE;`
`525`	`525`
`526`	`526`	`return UR_RESULT_ERROR_INVALID_KERNEL_NAME;`
`527`	`527`	`}`