Merge branch 'aaron/clarifyProgramGetFunctionPointer' into aaron/specMotivatedRefactors

aarongreig · aarongreig · commit 69ddf0137420 · 2024-02-09T15:00:28.000Z
diff --git a/include/ur_api.h b/include/ur_api.h
@@ -465,7 +465,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
@@ -4247,8 +4248,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.
@@ -4268,6 +4269,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
@@ -1433,8 +1433,8 @@ inline std::ostream &operator<<(std::ostream &os, 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
@@ -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
@@ -288,7 +288,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:
@@ -310,6 +310,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
@@ -484,7 +484,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
@@ -490,7 +490,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
@@ -45,9 +45,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
@@ -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
@@ -568,7 +568,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
@@ -87,7 +87,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
@@ -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
@@ -3145,8 +3145,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.
@@ -3166,6 +3166,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
@@ -2672,8 +2672,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.
@@ -2693,6 +2693,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_opencl.match b/test/conformance/program/program_adapter_opencl.match
@@ -1,2 +1 @@
-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));

Original file line number	Diff line number	Diff line change
`@@ -484,7 +484,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urProgramGetFunctionPointer(`
`484`	`484`	`UR_CHECK_ERROR(Ret);`
`485`	`485`	`if (Ret == CUDA_ERROR_NOT_FOUND) {`
`486`	`486`	`*ppFunctionPointer = 0;`
`487`		`- Result = UR_RESULT_ERROR_INVALID_FUNCTION_NAME;`
	`487`	`+ Result = UR_RESULT_ERROR_INVALID_KERNEL_NAME;`
`488`	`488`	`}`
`489`	`489`
`490`	`490`	`return Result;`
Original file line number	Diff line number	Diff line change
`@@ -490,7 +490,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urProgramGetFunctionPointer(`
`490`	`490`	`UR_CHECK_ERROR(Ret);`
`491`	`491`	`if (Ret == hipErrorNotFound) {`
`492`	`492`	`*ppFunctionPointer = 0;`
`493`		`- Result = UR_RESULT_ERROR_INVALID_FUNCTION_NAME;`
	`493`	`+ Result = UR_RESULT_ERROR_INVALID_KERNEL_NAME;`
`494`	`494`	`}`
`495`	`495`
`496`	`496`	`return Result;`
Original file line number	Diff line number	Diff line change
`@@ -568,7 +568,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urProgramGetFunctionPointer(`
`568`	`568`	`// exists`
`569`	`569`	`ClResult.pop_back();`
`570`	`570`	`if (is_in_separated_string(ClResult, ';', std::string(FunctionName)))`
`571`		`- return UR_RESULT_ERROR_INVALID_FUNCTION_NAME;`
	`571`	`+ return UR_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE;`
`572`	`572`
`573`	`573`	`return UR_RESULT_ERROR_INVALID_KERNEL_NAME;`
`574`	`574`	`}`