[UR][L0] Add support for passing device list to urProgramBuild

piProgramBuild receives a list of devices, while urProgramBuild
does not. This produces a series of issues when a UR program
needs to be created for a specific device.

So define a new API, called urProgramBuildExp to pass this
list.

Authored-by: [email protected]

Author: igchor

include/ur.py

@@ -202,6 +202,7 @@ class ur_function_v(IntEnum):
     KERNEL_SUGGEST_MAX_COOPERATIVE_GROUP_COUNT_EXP = 194## Enumerator for ::urKernelSuggestMaxCooperativeGroupCountExp
     COMMAND_BUFFER_APPEND_USM_PREFETCH_EXP = 195    ## Enumerator for ::urCommandBufferAppendUSMPrefetchExp
     COMMAND_BUFFER_APPEND_USM_ADVISE_EXP = 196      ## Enumerator for ::urCommandBufferAppendUSMAdviseExp
+    PROGRAM_BUILD_EXP = 197                         ## Enumerator for ::urProgramBuildExp
 
 class ur_function_t(c_int):
     def __str__(self):
@@ -2612,6 +2613,21 @@ class ur_program_dditable_t(Structure):
         ("pfnCreateWithNativeHandle", c_void_p)                         ## _urProgramCreateWithNativeHandle_t
     ]
 
+###############################################################################
+## @brief Function-pointer for urProgramBuildExp
+if __use_win_types:
+    _urProgramBuildExp_t = WINFUNCTYPE( ur_result_t, ur_context_handle_t, ur_program_handle_t, c_ulong, POINTER(ur_device_handle_t), c_char_p )
+else:
+    _urProgramBuildExp_t = CFUNCTYPE( ur_result_t, ur_context_handle_t, ur_program_handle_t, c_ulong, POINTER(ur_device_handle_t), c_char_p )
+
+
+###############################################################################
+## @brief Table of ProgramExp functions pointers
+class ur_program_exp_dditable_t(Structure):
+    _fields_ = [
+        ("pfnBuildExp", c_void_p)                                       ## _urProgramBuildExp_t
+    ]
+
 ###############################################################################
 ## @brief Function-pointer for urKernelCreate
 if __use_win_types:
@@ -3843,6 +3859,7 @@ class ur_dditable_t(Structure):
         ("Context", ur_context_dditable_t),
         ("Event", ur_event_dditable_t),
         ("Program", ur_program_dditable_t),
+        ("ProgramExp", ur_program_exp_dditable_t),
         ("Kernel", ur_kernel_dditable_t),
         ("KernelExp", ur_kernel_exp_dditable_t),
         ("Sampler", ur_sampler_dditable_t),
@@ -3947,6 +3964,16 @@ def __init__(self, version : ur_api_version_t):
         self.urProgramGetNativeHandle = _urProgramGetNativeHandle_t(self.__dditable.Program.pfnGetNativeHandle)
         self.urProgramCreateWithNativeHandle = _urProgramCreateWithNativeHandle_t(self.__dditable.Program.pfnCreateWithNativeHandle)
 
+        # call driver to get function pointers
+        ProgramExp = ur_program_exp_dditable_t()
+        r = ur_result_v(self.__dll.urGetProgramExpProcAddrTable(version, byref(ProgramExp)))
+        if r != ur_result_v.SUCCESS:
+            raise Exception(r)
+        self.__dditable.ProgramExp = ProgramExp
+
+        # attach function interface to function address
+        self.urProgramBuildExp = _urProgramBuildExp_t(self.__dditable.ProgramExp.pfnBuildExp)
+
         # call driver to get function pointers
         Kernel = ur_kernel_dditable_t()
         r = ur_result_v(self.__dll.urGetKernelProcAddrTable(version, byref(Kernel)))

include/ur_api.h

@@ -211,6 +211,7 @@ typedef enum ur_function_t {
     UR_FUNCTION_KERNEL_SUGGEST_MAX_COOPERATIVE_GROUP_COUNT_EXP = 194,          ///< Enumerator for ::urKernelSuggestMaxCooperativeGroupCountExp
     UR_FUNCTION_COMMAND_BUFFER_APPEND_USM_PREFETCH_EXP = 195,                  ///< Enumerator for ::urCommandBufferAppendUSMPrefetchExp
     UR_FUNCTION_COMMAND_BUFFER_APPEND_USM_ADVISE_EXP = 196,                    ///< Enumerator for ::urCommandBufferAppendUSMAdviseExp
+    UR_FUNCTION_PROGRAM_BUILD_EXP = 197,                                       ///< Enumerator for ::urProgramBuildExp
     /// @cond
     UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
     /// @endcond
@@ -4031,6 +4032,43 @@ urProgramBuild(
     const char *pOptions          ///< [in][optional] pointer to build options null-terminated string.
 );
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Produces an executable program from one program, negates need for the
+///        linking step.
+///
+/// @details
+///     - The application may call this function from simultaneous threads.
+///     - Following a successful call to this entry point, the program passed
+///       will contain a binary of the ::UR_PROGRAM_BINARY_TYPE_EXECUTABLE type
+///       for each device in `hContext`.
+///
+/// @remarks
+///   _Analogues_
+///     - **clBuildProgram**
+///
+/// @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 == hContext`
+///         + `NULL == hProgram`
+///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+///         + `NULL == phDevices`
+///     - ::UR_RESULT_ERROR_INVALID_PROGRAM
+///         + If `hProgram` isn't a valid program object.
+///     - ::UR_RESULT_ERROR_PROGRAM_BUILD_FAILURE
+///         + If an error occurred when building `hProgram`.
+UR_APIEXPORT ur_result_t UR_APICALL
+urProgramBuildExp(
+    ur_context_handle_t hContext,  ///< [in] handle of the context instance.
+    ur_program_handle_t hProgram,  ///< [in] Handle of the program to build.
+    uint32_t numDevices,           ///< [in] number of devices
+    ur_device_handle_t *phDevices, ///< [in][range(0, numDevices)] pointer to array of device handles
+    const char *pOptions           ///< [in][optional] pointer to build options null-terminated string.
+);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Produces an executable program from one or more programs.
 ///
@@ -8865,6 +8903,18 @@ typedef struct ur_program_build_params_t {
     const char **ppOptions;
 } ur_program_build_params_t;
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urProgramBuildExp
+/// @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_build_exp_params_t {
+    ur_context_handle_t *phContext;
+    ur_program_handle_t *phProgram;
+    uint32_t *pnumDevices;
+    ur_device_handle_t **pphDevices;
+    const char **ppOptions;
+} ur_program_build_exp_params_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function parameters for urProgramCompile
 /// @details Each entry is a pointer to the parameter passed to the function;

include/ur_ddi.h

@@ -408,6 +408,42 @@ typedef ur_result_t(UR_APICALL *ur_pfnGetProgramProcAddrTable_t)(
     ur_api_version_t,
     ur_program_dditable_t *);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urProgramBuildExp
+typedef ur_result_t(UR_APICALL *ur_pfnProgramBuildExp_t)(
+    ur_context_handle_t,
+    ur_program_handle_t,
+    uint32_t,
+    ur_device_handle_t *,
+    const char *);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Table of ProgramExp functions pointers
+typedef struct ur_program_exp_dditable_t {
+    ur_pfnProgramBuildExp_t pfnBuildExp;
+} ur_program_exp_dditable_t;
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Exported function for filling application's ProgramExp table
+///        with current process' addresses
+///
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_UNINITIALIZED
+///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_VERSION
+UR_DLLEXPORT ur_result_t UR_APICALL
+urGetProgramExpProcAddrTable(
+    ur_api_version_t version,            ///< [in] API version requested
+    ur_program_exp_dditable_t *pDdiTable ///< [in,out] pointer to table of DDI function pointers
+);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urGetProgramExpProcAddrTable
+typedef ur_result_t(UR_APICALL *ur_pfnGetProgramExpProcAddrTable_t)(
+    ur_api_version_t,
+    ur_program_exp_dditable_t *);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function-pointer for urKernelCreate
 typedef ur_result_t(UR_APICALL *ur_pfnKernelCreate_t)(
@@ -2250,6 +2286,7 @@ typedef struct ur_dditable_t {
     ur_context_dditable_t Context;
     ur_event_dditable_t Event;
     ur_program_dditable_t Program;
+    ur_program_exp_dditable_t ProgramExp;
     ur_kernel_dditable_t Kernel;
     ur_kernel_exp_dditable_t KernelExp;
     ur_sampler_dditable_t Sampler;

scripts/core/program.yml

@@ -182,6 +182,39 @@ returns:
       - "If an error occurred when building `hProgram`."
 --- #--------------------------------------------------------------------------
 type: function
+desc: "Produces an executable program from one program, negates need for the linking step."
+class: $xProgram
+name: BuildExp
+ordinal: "2"
+decl: static
+analogue:
+    - "**clBuildProgram**"
+details:
+    - "The application may call this function from simultaneous threads."
+    - "Following a successful call to this entry point, the program passed will contain a binary of the $X_PROGRAM_BINARY_TYPE_EXECUTABLE type for each device in `hContext`."
+params:
+    - type: $x_context_handle_t
+      name: hContext
+      desc: "[in] handle of the context instance."
+    - type: $x_program_handle_t
+      name: hProgram
+      desc: "[in] Handle of the program to build."
+    - type: uint32_t
+      name: numDevices
+      desc: "[in] number of devices"
+    - type: $x_device_handle_t*
+      name: phDevices
+      desc: "[in][range(0, numDevices)] pointer to array of device handles" 
+    - type: const char*
+      name: pOptions
+      desc: "[in][optional] pointer to build options null-terminated string."
+returns:
+    - $X_RESULT_ERROR_INVALID_PROGRAM:
+      - "If `hProgram` isn't a valid program object."
+    - $X_RESULT_ERROR_PROGRAM_BUILD_FAILURE:
+      - "If an error occurred when building `hProgram`."
+--- #--------------------------------------------------------------------------
+type: function
 desc: "Produces an executable program from one or more programs."
 class: $xProgram
 name: Compile

scripts/core/registry.yml

@@ -547,6 +547,9 @@ etors:
 - name: COMMAND_BUFFER_APPEND_USM_ADVISE_EXP
   desc: Enumerator for $xCommandBufferAppendUSMAdviseExp
   value: '196'
+- name: PROGRAM_BUILD_EXP
+  desc: Enumerator for $xProgramBuildExp
+  value: '197'
 ---
 type: enum
 desc: Defines structure types

source/adapters/null/ur_nullddi.cpp

@@ -1749,6 +1749,33 @@ __urdlllocal ur_result_t UR_APICALL urProgramBuild(
     return exceptionToResult(std::current_exception());
 }
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Intercept function for urProgramBuildExp
+__urdlllocal ur_result_t UR_APICALL urProgramBuildExp(
+    ur_context_handle_t hContext, ///< [in] handle of the context instance.
+    ur_program_handle_t hProgram, ///< [in] Handle of the program to build.
+    uint32_t numDevices,          ///< [in] number of devices
+    ur_device_handle_t *
+        phDevices, ///< [in][range(0, numDevices)] pointer to array of device handles
+    const char *
+        pOptions ///< [in][optional] pointer to build options null-terminated string.
+    ) 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 pfnBuildExp = d_context.urDdiTable.ProgramExp.pfnBuildExp;
+    if (nullptr != pfnBuildExp) {
+        result =
+            pfnBuildExp(hContext, hProgram, numDevices, phDevices, pOptions);
+    } else {
+        // generic implementation
+    }
+
+    return result;
+} catch (...) {
+    return exceptionToResult(std::current_exception());
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Intercept function for urProgramCompile
 __urdlllocal ur_result_t UR_APICALL urProgramCompile(
@@ -5853,6 +5880,36 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetProgramProcAddrTable(
     return exceptionToResult(std::current_exception());
 }
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Exported function for filling application's ProgramExp table
+///        with current process' addresses
+///
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_VERSION
+UR_DLLEXPORT ur_result_t UR_APICALL urGetProgramExpProcAddrTable(
+    ur_api_version_t version, ///< [in] API version requested
+    ur_program_exp_dditable_t
+        *pDdiTable ///< [in,out] pointer to table of DDI function pointers
+    ) try {
+    if (nullptr == pDdiTable) {
+        return UR_RESULT_ERROR_INVALID_NULL_POINTER;
+    }
+
+    if (driver::d_context.version < version) {
+        return UR_RESULT_ERROR_UNSUPPORTED_VERSION;
+    }
+
+    ur_result_t result = UR_RESULT_SUCCESS;
+
+    pDdiTable->pfnBuildExp = driver::urProgramBuildExp;
+
+    return result;
+} catch (...) {
+    return exceptionToResult(std::current_exception());
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Exported function for filling application's Queue table
 ///        with current process' addresses

source/common/ur_params.hpp

@@ -1202,6 +1202,10 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_function_t value) {
     case UR_FUNCTION_COMMAND_BUFFER_APPEND_USM_ADVISE_EXP:
         os << "UR_FUNCTION_COMMAND_BUFFER_APPEND_USM_ADVISE_EXP";
         break;
+
+    case UR_FUNCTION_PROGRAM_BUILD_EXP:
+        os << "UR_FUNCTION_PROGRAM_BUILD_EXP";
+        break;
     default:
         os << "unknown enumerator";
         break;
@@ -14429,6 +14433,44 @@ operator<<(std::ostream &os,
     return os;
 }
 
+inline std::ostream &operator<<(
+    std::ostream &os,
+    [[maybe_unused]] const struct ur_program_build_exp_params_t *params) {
+
+    os << ".hContext = ";
+
+    ur_params::serializePtr(os, *(params->phContext));
+
+    os << ", ";
+    os << ".hProgram = ";
+
+    ur_params::serializePtr(os, *(params->phProgram));
+
+    os << ", ";
+    os << ".numDevices = ";
+
+    os << *(params->pnumDevices);
+
+    os << ", ";
+    os << ".phDevices = {";
+    for (size_t i = 0;
+         *(params->pphDevices) != NULL && i < *params->pnumDevices; ++i) {
+        if (i != 0) {
+            os << ", ";
+        }
+
+        ur_params::serializePtr(os, (*(params->pphDevices))[i]);
+    }
+    os << "}";
+
+    os << ", ";
+    os << ".pOptions = ";
+
+    ur_params::serializePtr(os, *(params->ppOptions));
+
+    return os;
+}
+
 inline std::ostream &
 operator<<(std::ostream &os,
            [[maybe_unused]] const struct ur_program_compile_params_t *params) {
@@ -16215,6 +16257,9 @@ inline int serializeFunctionParams(std::ostream &os, uint32_t function,
     case UR_FUNCTION_PROGRAM_BUILD: {
         os << (const struct ur_program_build_params_t *)params;
     } break;
+    case UR_FUNCTION_PROGRAM_BUILD_EXP: {
+        os << (const struct ur_program_build_exp_params_t *)params;
+    } break;
     case UR_FUNCTION_PROGRAM_COMPILE: {
         os << (const struct ur_program_compile_params_t *)params;
     } break;