[SPEC] Add urProgramGetGlobalVariablePointer entrypoint

include/ur_api.h

@@ -215,6 +215,7 @@ typedef enum ur_function_t {
  UR_FUNCTION_COMMAND_BUFFER_APPEND_USM_ADVISE_EXP = 213, ///< Enumerator for ::urCommandBufferAppendUSMAdviseExp
  UR_FUNCTION_ENQUEUE_COOPERATIVE_KERNEL_LAUNCH_EXP = 214, ///< Enumerator for ::urEnqueueCooperativeKernelLaunchExp
  UR_FUNCTION_KERNEL_SUGGEST_MAX_COOPERATIVE_GROUP_COUNT_EXP = 215, ///< Enumerator for ::urKernelSuggestMaxCooperativeGroupCountExp
+ UR_FUNCTION_PROGRAM_GET_GLOBAL_VARIABLE_POINTER = 216, ///< Enumerator for ::urProgramGetGlobalVariablePointer
  /// @cond
  UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
  /// @endcond
@@ -4262,6 +4263,42 @@ urProgramGetFunctionPointer(
  void **ppFunctionPointer ///< [out] Returns the pointer to the function if it is found in the program.
 );
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Retrieves a pointer to a device global variable.
+///
+/// @details
+/// - Retrieves a pointer to a device global variable.
+/// - The application may call this function from simultaneous threads for
+/// the same device.
+/// - The implementation of this function should be thread-safe.
+///
+/// @remarks
+/// _Analogues_
+/// - **clGetDeviceGlobalVariablePointerINTEL**
+///
+/// @returns
+/// - ::UR_RESULT_SUCCESS
+/// - ::UR_RESULT_ERROR_UNINITIALIZED
+/// - ::UR_RESULT_ERROR_DEVICE_LOST
+/// - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
+/// - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
+/// + `NULL == hDevice`
+/// + `NULL == hProgram`
+/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+/// + `NULL == pGlobalVariableName`
+/// + `NULL == ppGlobalVariablePointerRet`
+/// - ::UR_RESULT_ERROR_INVALID_SIZE
+/// + `name` is not a valid variable in the program.
+UR_APIEXPORT ur_result_t UR_APICALL
+urProgramGetGlobalVariablePointer(
+ ur_device_handle_t hDevice, ///< [in] handle of the device to retrieve the pointer for.
+ ur_program_handle_t hProgram, ///< [in] handle of the program where the global variable is.
+ const char *pGlobalVariableName, ///< [in] mangled name of the global variable to retrieve the pointer for.
+ size_t *pGlobalVariableSizeRet, ///< [out][optional] Returns the size of the global variable if it is found
+ ///< in the program.
+ void **ppGlobalVariablePointerRet ///< [out] Returns the pointer to the global variable if it is found in the program.
+);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Get Program object information
 typedef enum ur_program_info_t {
@@ -9144,6 +9181,18 @@ typedef struct ur_program_get_function_pointer_params_t {
  void ***pppFunctionPointer;
 } ur_program_get_function_pointer_params_t;
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urProgramGetGlobalVariablePointer
+/// @details Each entry is a pointer to the parameter passed to the function;
+/// allowing the callback the ability to modify the parameter's value
+typedef struct ur_program_get_global_variable_pointer_params_t {
+ ur_device_handle_t *phDevice;
+ ur_program_handle_t *phProgram;
+ const char **ppGlobalVariableName;
+ size_t **ppGlobalVariableSizeRet;
+ void ***pppGlobalVariablePointerRet;
+} ur_program_get_global_variable_pointer_params_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function parameters for urProgramGetInfo
 /// @details Each entry is a pointer to the parameter passed to the function;

include/ur_ddi.h

@@ -329,6 +329,15 @@ typedef ur_result_t(UR_APICALL *ur_pfnProgramGetFunctionPointer_t)(
  const char *,
  void **);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urProgramGetGlobalVariablePointer
+typedef ur_result_t(UR_APICALL *ur_pfnProgramGetGlobalVariablePointer_t)(
+ ur_device_handle_t,
+ ur_program_handle_t,
+ const char *,
+ size_t *,
+ void **);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function-pointer for urProgramGetInfo
 typedef ur_result_t(UR_APICALL *ur_pfnProgramGetInfo_t)(
@@ -380,6 +389,7 @@ typedef struct ur_program_dditable_t {
  ur_pfnProgramRetain_t pfnRetain;
  ur_pfnProgramRelease_t pfnRelease;
  ur_pfnProgramGetFunctionPointer_t pfnGetFunctionPointer;
+ ur_pfnProgramGetGlobalVariablePointer_t pfnGetGlobalVariablePointer;
  ur_pfnProgramGetInfo_t pfnGetInfo;
  ur_pfnProgramGetBuildInfo_t pfnGetBuildInfo;
  ur_pfnProgramSetSpecializationConstants_t pfnSetSpecializationConstants;

include/ur_print.hpp

@@ -879,6 +879,9 @@ inline std::ostream &operator<<(std::ostream &os, ur_function_t value) {
  case UR_FUNCTION_KERNEL_SUGGEST_MAX_COOPERATIVE_GROUP_COUNT_EXP:
  os << "UR_FUNCTION_KERNEL_SUGGEST_MAX_COOPERATIVE_GROUP_COUNT_EXP";
  break;
+ case UR_FUNCTION_PROGRAM_GET_GLOBAL_VARIABLE_POINTER:
+ os << "UR_FUNCTION_PROGRAM_GET_GLOBAL_VARIABLE_POINTER";
+ break;
  default:
  os << "unknown enumerator";
  break;
@@ -10257,6 +10260,44 @@ inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct
  return os;
 }
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print operator for the ur_program_get_global_variable_pointer_params_t type
+/// @returns
+/// std::ostream &
+inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_program_get_global_variable_pointer_params_t *params) {
+
+ os << ".hDevice = ";
+
+ ur::details::printPtr(os,
+ *(params->phDevice));
+
+ os << ", ";
+ os << ".hProgram = ";
+
+ ur::details::printPtr(os,
+ *(params->phProgram));
+
+ os << ", ";
+ os << ".pGlobalVariableName = ";
+
+ ur::details::printPtr(os,
+ *(params->ppGlobalVariableName));
+
+ os << ", ";
+ os << ".pGlobalVariableSizeRet = ";
+
+ ur::details::printPtr(os,
+ *(params->ppGlobalVariableSizeRet));
+
+ os << ", ";
+ os << ".ppGlobalVariablePointerRet = ";
+
+ ur::details::printPtr(os,
+ *(params->pppGlobalVariablePointerRet));
+
+ return os;
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print operator for the ur_program_get_info_params_t type
 /// @returns
@@ -15992,6 +16033,9 @@ inline ur_result_t UR_APICALL printFunctionParams(std::ostream &os, ur_function_
  case UR_FUNCTION_PROGRAM_GET_FUNCTION_POINTER: {
  os << (const struct ur_program_get_function_pointer_params_t *)params;
  } break;
+ case UR_FUNCTION_PROGRAM_GET_GLOBAL_VARIABLE_POINTER: {
+ os << (const struct ur_program_get_global_variable_pointer_params_t *)params;
+ } break;
  case UR_FUNCTION_PROGRAM_GET_INFO: {
  os << (const struct ur_program_get_info_params_t *)params;
  } break;

scripts/core/program.yml

@@ -311,6 +311,43 @@ params:
  desc: |
  [out] Returns the pointer to the function if it is found in the program.
 --- #--------------------------------------------------------------------------
+type: function
+desc: "Retrieves a pointer to a device global variable."
+class: $xProgram
+name: GetGlobalVariablePointer
+decl: static
+ordinal: "7"
+analogue:
+ - "**clGetDeviceGlobalVariablePointerINTEL**"
+details:
+ - "Retrieves a pointer to a device global variable."
+ - "The application may call this function from simultaneous threads for the same device."
+ - "The implementation of this function should be thread-safe."
+params:
+ - type: "$x_device_handle_t"
+ name: hDevice
+ desc: |
+ [in] handle of the device to retrieve the pointer for.
+ - type: "$x_program_handle_t"
+ name: hProgram
+ desc: |
+ [in] handle of the program where the global variable is.
+ - type: "const char*"
+ name: pGlobalVariableName
+ desc: |
+ [in] mangled name of the global variable to retrieve the pointer for.
+ - type: "size_t*"
+ name: pGlobalVariableSizeRet
+ desc: |
+ [out][optional] Returns the size of the global variable if it is found in the program.
+ - type: "void**"
+ name: ppGlobalVariablePointerRet
+ desc: |
+ [out] Returns the pointer to the global variable if it is found in the program.
+returns:
+ - $X_RESULT_ERROR_INVALID_SIZE:
+ - "`name` is not a valid variable in the program."
+--- #--------------------------------------------------------------------------
 type: enum
 desc: "Get Program object information"
 class: $xProgram

scripts/core/registry.yml

@@ -559,6 +559,9 @@ etors:
 - name: KERNEL_SUGGEST_MAX_COOPERATIVE_GROUP_COUNT_EXP
  desc: Enumerator for $xKernelSuggestMaxCooperativeGroupCountExp
  value: '215'
+- name: PROGRAM_GET_GLOBAL_VARIABLE_POINTER
+ desc: Enumerator for $xProgramGetGlobalVariablePointer
+ value: '216'
 ---
 type: enum
 desc: Defines structure types

source/adapters/cuda/program.cpp

@@ -489,3 +489,34 @@ UR_APIEXPORT ur_result_t UR_APICALL urProgramGetFunctionPointer(
 
  return Result;
 }
+
+UR_APIEXPORT ur_result_t UR_APICALL urProgramGetGlobalVariablePointer(
+ ur_device_handle_t, ur_program_handle_t hProgram,
+ const char *pGlobalVariableName, size_t *pGlobalVariableSizeRet,
+ void **ppGlobalVariablePointerRet) {
+
+ /* Since CUDA requires a global variable to be referenced by name, we use
+ * metadata to find the correct name to access it by. */
+ auto DeviceGlobalNameIt = hProgram->GlobalIDMD.find(pGlobalVariableName);
+ if (DeviceGlobalNameIt == hProgram->GlobalIDMD.end())
+ return UR_RESULT_ERROR_INVALID_VALUE;
+ std::string DeviceGlobalName = DeviceGlobalNameIt->second;
+
+ ur_result_t Result = UR_RESULT_SUCCESS;
+ try {
+ CUdeviceptr DeviceGlobal = 0;
+ size_t DeviceGlobalSize = 0;
+ UR_CHECK_ERROR(cuModuleGetGlobal(&DeviceGlobal, &DeviceGlobalSize,
+ hProgram->get(),
+ DeviceGlobalName.c_str()));
+
+ if (pGlobalVariableSizeRet) {
+ *pGlobalVariableSizeRet = DeviceGlobalSize;
+ }
+ *ppGlobalVariablePointerRet = reinterpret_cast<void *>(DeviceGlobal);
+
+ } catch (ur_result_t Err) {
+ Result = Err;
+ }
+ return Result;
+}

source/adapters/cuda/ur_interface_loader.cpp

@@ -93,6 +93,7 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetProgramProcAddrTable(
  pDdiTable->pfnCreateWithNativeHandle = urProgramCreateWithNativeHandle;
  pDdiTable->pfnGetBuildInfo = urProgramGetBuildInfo;
  pDdiTable->pfnGetFunctionPointer = urProgramGetFunctionPointer;
+ pDdiTable->pfnGetGlobalVariablePointer = urProgramGetGlobalVariablePointer;
  pDdiTable->pfnGetInfo = urProgramGetInfo;
  pDdiTable->pfnGetNativeHandle = urProgramGetNativeHandle;
  pDdiTable->pfnLink = urProgramLink;

source/adapters/hip/program.cpp

@@ -495,3 +495,8 @@ UR_APIEXPORT ur_result_t UR_APICALL urProgramGetFunctionPointer(
 
  return Result;
 }
+
+UR_APIEXPORT ur_result_t UR_APICALL urProgramGetGlobalVariablePointer(
+ ur_device_handle_t, ur_program_handle_t, const char *, size_t *, void **) {
+ return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
+}

source/adapters/hip/ur_interface_loader.cpp

@@ -93,6 +93,7 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetProgramProcAddrTable(
  pDdiTable->pfnCreateWithNativeHandle = urProgramCreateWithNativeHandle;
  pDdiTable->pfnGetBuildInfo = urProgramGetBuildInfo;
  pDdiTable->pfnGetFunctionPointer = urProgramGetFunctionPointer;
+ pDdiTable->pfnGetGlobalVariablePointer = urProgramGetGlobalVariablePointer;
  pDdiTable->pfnGetInfo = urProgramGetInfo;
  pDdiTable->pfnGetNativeHandle = urProgramGetNativeHandle;
  pDdiTable->pfnLink = urProgramLink;

source/adapters/level_zero/program.cpp

@@ -558,6 +558,11 @@ UR_APIEXPORT ur_result_t UR_APICALL urProgramGetFunctionPointer(
  return ze2urResult(ZeResult);
 }
 
+UR_APIEXPORT ur_result_t UR_APICALL urProgramGetGlobalVariablePointer(
+ ur_device_handle_t, ur_program_handle_t, const char *, size_t *, void **) {
+ return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
+}
+
 UR_APIEXPORT ur_result_t UR_APICALL urProgramGetInfo(
  ur_program_handle_t Program, ///< [in] handle of the Program object
  ur_program_info_t PropName, ///< [in] name of the Program property to query

source/adapters/level_zero/ur_interface_loader.cpp

@@ -215,6 +215,7 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetProgramProcAddrTable(
  pDdiTable->pfnRetain = urProgramRetain;
  pDdiTable->pfnRelease = urProgramRelease;
  pDdiTable->pfnGetFunctionPointer = urProgramGetFunctionPointer;
+ pDdiTable->pfnGetGlobalVariablePointer = urProgramGetGlobalVariablePointer;
  pDdiTable->pfnGetInfo = urProgramGetInfo;
  pDdiTable->pfnGetBuildInfo = urProgramGetBuildInfo;
  pDdiTable->pfnSetSpecializationConstants =

source/adapters/null/ur_nullddi.cpp

@@ -1872,6 +1872,39 @@ __urdlllocal ur_result_t UR_APICALL urProgramGetFunctionPointer(
  return exceptionToResult(std::current_exception());
 }
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Intercept function for urProgramGetGlobalVariablePointer
+__urdlllocal ur_result_t UR_APICALL urProgramGetGlobalVariablePointer(
+ ur_device_handle_t
+ hDevice, ///< [in] handle of the device to retrieve the pointer for.
+ ur_program_handle_t
+ hProgram, ///< [in] handle of the program where the global variable is.
+ const char *
+ pGlobalVariableName, ///< [in] mangled name of the global variable to retrieve the pointer for.
+ size_t *
+ pGlobalVariableSizeRet, ///< [out][optional] Returns the size of the global variable if it is found
+ ///< in the program.
+ void **
+ ppGlobalVariablePointerRet ///< [out] Returns the pointer to the global variable if it is found in the program.
+ ) try {
+ ur_result_t result = UR_RESULT_SUCCESS;
+
+ // if the driver has created a custom function, then call it instead of using the generic path
+ auto pfnGetGlobalVariablePointer =
+ d_context.urDdiTable.Program.pfnGetGlobalVariablePointer;
+ if (nullptr != pfnGetGlobalVariablePointer) {
+ result = pfnGetGlobalVariablePointer(
+ hDevice, hProgram, pGlobalVariableName, pGlobalVariableSizeRet,
+ ppGlobalVariablePointerRet);
+ } else {
+ // generic implementation
+ }
+
+ return result;
+} catch (...) {
+ return exceptionToResult(std::current_exception());
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Intercept function for urProgramGetInfo
 __urdlllocal ur_result_t UR_APICALL urProgramGetInfo(
@@ -5941,6 +5974,9 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetProgramProcAddrTable(
 
  pDdiTable->pfnGetFunctionPointer = driver::urProgramGetFunctionPointer;
 
+ pDdiTable->pfnGetGlobalVariablePointer =
+ driver::urProgramGetGlobalVariablePointer;
+
  pDdiTable->pfnGetInfo = driver::urProgramGetInfo;
 
  pDdiTable->pfnGetBuildInfo = driver::urProgramGetBuildInfo;

source/adapters/opencl/common.hpp

@@ -39,7 +39,7 @@
  * error is mapped to UR
  */
 #define CL_RETURN_ON_FAILURE_AND_SET_NULL(clCall, outPtr) \
- if (const cl_int cl_result_macro = clCall != CL_SUCCESS) {  \
+ if (const cl_int cl_result_macro = clCall; cl_result_macro != CL_SUCCESS) { \
  if (outPtr != nullptr) { \
  *outPtr = nullptr; \
  } \
@@ -197,6 +197,8 @@ CONSTFIX char SetProgramSpecializationConstantName[] =
  "clSetProgramSpecializationConstant";
 CONSTFIX char GetDeviceFunctionPointerName[] =
  "clGetDeviceFunctionPointerINTEL";
+CONSTFIX char GetDeviceGlobalVariablePointerName[] =
+ "clGetDeviceGlobalVariablePointerINTEL";
 CONSTFIX char EnqueueWriteGlobalVariableName[] =
  "clEnqueueWriteGlobalVariableINTEL";
 CONSTFIX char EnqueueReadGlobalVariableName[] =
@@ -221,6 +223,10 @@ using clGetDeviceFunctionPointer_fn = CL_API_ENTRY
 cl_int(CL_API_CALL *)(cl_device_id device, cl_program program,
  const char *FuncName, cl_ulong *ret_ptr);
 
+using clGetDeviceGlobalVariablePointer_fn = CL_API_ENTRY cl_int(CL_API_CALL *)(
+ cl_device_id device, cl_program program, const char *globalVariableName,
+ size_t *globalVariableSizeRet, void **globalVariablePointerRet);
+
 using clEnqueueWriteGlobalVariable_fn = CL_API_ENTRY
 cl_int(CL_API_CALL *)(cl_command_queue, cl_program, const char *, cl_bool,
  size_t, size_t, const void *, cl_uint, const cl_event *,
@@ -314,6 +320,8 @@ struct ExtFuncPtrCacheT {
  FuncPtrCache<clDeviceMemAllocINTEL_fn> clDeviceMemAllocINTELCache;
  FuncPtrCache<clSharedMemAllocINTEL_fn> clSharedMemAllocINTELCache;
  FuncPtrCache<clGetDeviceFunctionPointer_fn> clGetDeviceFunctionPointerCache;
+ FuncPtrCache<clGetDeviceGlobalVariablePointer_fn>
+ clGetDeviceGlobalVariablePointerCache;
  FuncPtrCache<clCreateBufferWithPropertiesINTEL_fn>
  clCreateBufferWithPropertiesINTELCache;
  FuncPtrCache<clMemBlockingFreeINTEL_fn> clMemBlockingFreeINTELCache;