Refactor the compiler API.

The module object has been removed, and the program object now more closely
mirrors its OpenCL and PI equivalents.

Author: aarongreig

include/ur.py

@@ -253,12 +253,11 @@ typedef ur_result_t(UR_APICALL *ur_pfnGetEventProcAddrTable_t)(
     ur_event_dditable_t *);
 
 ///////////////////////////////////////////////////////////////////////////////
-/// @brief Function-pointer for urProgramCreate
-typedef ur_result_t(UR_APICALL *ur_pfnProgramCreate_t)(
+/// @brief Function-pointer for urProgramCreateWithIL
+typedef ur_result_t(UR_APICALL *ur_pfnProgramCreateWithIL_t)(
     ur_context_handle_t,
-    uint32_t,
-    const ur_module_handle_t *,
-    const char *,
+    const void *,
+    size_t,
     const ur_program_properties_t *,
     ur_program_handle_t *);
 
@@ -272,6 +271,29 @@ typedef ur_result_t(UR_APICALL *ur_pfnProgramCreateWithBinary_t)(
     const ur_program_properties_t *,
     ur_program_handle_t *);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urProgramBuild
+typedef ur_result_t(UR_APICALL *ur_pfnProgramBuild_t)(
+    ur_context_handle_t,
+    ur_program_handle_t,
+    const char *);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urProgramCompile
+typedef ur_result_t(UR_APICALL *ur_pfnProgramCompile_t)(
+    ur_context_handle_t,
+    ur_program_handle_t,
+    const char *);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urProgramLink
+typedef ur_result_t(UR_APICALL *ur_pfnProgramLink_t)(
+    ur_context_handle_t,
+    uint32_t,
+    const ur_program_handle_t *,
+    const char *,
+    ur_program_handle_t *);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function-pointer for urProgramRetain
 typedef ur_result_t(UR_APICALL *ur_pfnProgramRetain_t)(
@@ -332,8 +354,11 @@ typedef ur_result_t(UR_APICALL *ur_pfnProgramCreateWithNativeHandle_t)(
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Table of Program functions pointers
 typedef struct ur_program_dditable_t {
-    ur_pfnProgramCreate_t pfnCreate;
+    ur_pfnProgramCreateWithIL_t pfnCreateWithIL;
     ur_pfnProgramCreateWithBinary_t pfnCreateWithBinary;
+    ur_pfnProgramBuild_t pfnBuild;
+    ur_pfnProgramCompile_t pfnCompile;
+    ur_pfnProgramLink_t pfnLink;
     ur_pfnProgramRetain_t pfnRetain;
     ur_pfnProgramRelease_t pfnRelease;
     ur_pfnProgramGetFunctionPointer_t pfnGetFunctionPointer;
@@ -365,71 +390,6 @@ typedef ur_result_t(UR_APICALL *ur_pfnGetProgramProcAddrTable_t)(
     ur_api_version_t,
     ur_program_dditable_t *);
 
-///////////////////////////////////////////////////////////////////////////////
-/// @brief Function-pointer for urModuleCreate
-typedef ur_result_t(UR_APICALL *ur_pfnModuleCreate_t)(
-    ur_context_handle_t,
-    const void *,
-    size_t,
-    const char *,
-    ur_modulecreate_callback_t,
-    void *,
-    ur_module_handle_t *);
-
-///////////////////////////////////////////////////////////////////////////////
-/// @brief Function-pointer for urModuleRetain
-typedef ur_result_t(UR_APICALL *ur_pfnModuleRetain_t)(
-    ur_module_handle_t);
-
-///////////////////////////////////////////////////////////////////////////////
-/// @brief Function-pointer for urModuleRelease
-typedef ur_result_t(UR_APICALL *ur_pfnModuleRelease_t)(
-    ur_module_handle_t);
-
-///////////////////////////////////////////////////////////////////////////////
-/// @brief Function-pointer for urModuleGetNativeHandle
-typedef ur_result_t(UR_APICALL *ur_pfnModuleGetNativeHandle_t)(
-    ur_module_handle_t,
-    ur_native_handle_t *);
-
-///////////////////////////////////////////////////////////////////////////////
-/// @brief Function-pointer for urModuleCreateWithNativeHandle
-typedef ur_result_t(UR_APICALL *ur_pfnModuleCreateWithNativeHandle_t)(
-    ur_native_handle_t,
-    ur_context_handle_t,
-    ur_module_handle_t *);
-
-///////////////////////////////////////////////////////////////////////////////
-/// @brief Table of Module functions pointers
-typedef struct ur_module_dditable_t {
-    ur_pfnModuleCreate_t pfnCreate;
-    ur_pfnModuleRetain_t pfnRetain;
-    ur_pfnModuleRelease_t pfnRelease;
-    ur_pfnModuleGetNativeHandle_t pfnGetNativeHandle;
-    ur_pfnModuleCreateWithNativeHandle_t pfnCreateWithNativeHandle;
-} ur_module_dditable_t;
-
-///////////////////////////////////////////////////////////////////////////////
-/// @brief Exported function for filling application's Module 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
-urGetModuleProcAddrTable(
-    ur_api_version_t version,       ///< [in] API version requested
-    ur_module_dditable_t *pDdiTable ///< [in,out] pointer to table of DDI function pointers
-);
-
-///////////////////////////////////////////////////////////////////////////////
-/// @brief Function-pointer for urGetModuleProcAddrTable
-typedef ur_result_t(UR_APICALL *ur_pfnGetModuleProcAddrTable_t)(
-    ur_api_version_t,
-    ur_module_dditable_t *);
-
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function-pointer for urKernelCreate
 typedef ur_result_t(UR_APICALL *ur_pfnKernelCreate_t)(
@@ -1451,7 +1411,6 @@ typedef struct ur_dditable_t {
     ur_context_dditable_t Context;
     ur_event_dditable_t Event;
     ur_program_dditable_t Program;
-    ur_module_dditable_t Module;
     ur_kernel_dditable_t Kernel;
     ur_sampler_dditable_t Sampler;
     ur_mem_dditable_t Mem;

include/ur_api.h

@@ -163,39 +163,46 @@ events, and programs are explicitly created against a context. A trivial work wi
     // Release the context handle
     ${x}ContextRelease(hContext);    
 
-Modules and Programs
+Programs and Kernels
 ====================
 
-There are multiple levels of constructs needed for executing kernels on the device:
+There are two constructs we need to prepare code for execution on the device:
 
-* Modules represent a single translation unit that consists of kernels and globals that have been compiled together.
-* Programs represent one or more modules that have been linked together.
-* Kernels represent the kernel within a program that will be launched onto the device.
+* Programs serve as containers for device code. They typically encapsulate a
+  collection of functions and global variables represented in an intermediate
+  language, and one or more device-native binaries compiled from that
+  collection.
+* Kernels represent a handle to a function within a program that can be
+  launched on a device.
 
-.. image:: ../images/modules_programs.png
 
-Modules and Programs
---------------------
+Programs
+--------
 
-A module is the compiled code or object for a single compilation unit. Modules can be created from a SPIR-V module. A program
-are a collection of modules that are linked together.
+Programs can be constructed with an intermediate language binary or a
+device-native binary. Programs constructed with IL must be further compiled
+through either ${x}ProgramCompile and ${x}ProgramLink or ${x}ProgramBuild
+before they can be used to create a kernel object.
 
 .. parsed-literal::
 
-    // Create module
-    ${x}_module_handle_t hModule;
-    ${x}ModuleCreate(hContext, (const void*)pIL, length, nullptr, nullptr, nullptr, hModule);
-
-    // Create program from module
+    // Create a program with IL
     ${x}_program_handle_t hProgram;
-    ${x}ProgramCreate(hContext, 1, &hModule, nullptr, nullptr, hProgram);
+    ${x}ProgramCreateWithIL(hContext, ILBin, ILBinSize, nullptr, &hProgram);
+
+    // Build the program.
+    ${x}ProgramBuild(hContext, hProgram, nullptr);
+
+The diagram below shows the possible paths to obtaining a program that can be
+used to create a kernel:
 
+.. image:: ../images/programs.png
 
 Kernels
 -------
 
-A Kernel is a reference to a kernel within a module and it supports both explicit and implicit kernel
-arguments along with data needed for launch.
+A Kernel is a reference to a kernel within a program and it supports both
+explicit and implicit kernel arguments along with data needed for launch.
 
 .. parsed-literal::
 

include/ur_ddi.h

@@ -83,12 +83,7 @@ class: $xProgram
 name: "$x_program_handle_t"
 --- #--------------------------------------------------------------------------
 type: handle
-desc: "Handle of Module object"
-class: $xModule
-name: "$x_module_handle_t"
---- #--------------------------------------------------------------------------
-type: handle
-desc: "Handle of module's Kernel object"
+desc: "Handle of program's Kernel object"
 class: $xKernel
 name: "$x_kernel_handle_t"
 --- #--------------------------------------------------------------------------
@@ -152,8 +147,6 @@ etors:
       desc: "Returned when the event wait list or the events in the wait list are invalid."
     - name: ERROR_MISALIGNED_SUB_BUFFER_OFFSET
       desc: "Misaligned sub buffer offset"
-    - name: ERROR_BUILD_PROGRAM_FAILURE
-      desc: "Build program failure"
     - name: ERROR_INVALID_WORK_GROUP_SIZE
       desc: "Invalid work group size"
     - name: ERROR_COMPILER_NOT_AVAILABLE
@@ -183,7 +176,7 @@ etors:
     - name: ERROR_INVALID_KERNEL
       desc: "Invalid kernel"
     - name: ERROR_INVALID_KERNEL_NAME
-      desc: "[Validation] kernel name is not found in the module"
+      desc: "[Validation] kernel name is not found in the program"
     - name: ERROR_INVALID_KERNEL_ARGUMENT_INDEX
       desc: "[Validation] kernel argument index is not valid for kernel"
     - name: ERROR_INVALID_KERNEL_ARGUMENT_SIZE
@@ -208,10 +201,10 @@ etors:
       desc: "Insufficient device memory to satisfy call"
     - name: ERROR_OUT_OF_RESOURCES
       desc: "Out of resources"
-    - name: ERROR_MODULE_BUILD_FAILURE
-      desc: "Error occurred when building module, see build log for details"
-    - name: ERROR_MODULE_LINK_FAILURE
-      desc: "Error occurred when linking modules, see build log for details"
+    - name: ERROR_PROGRAM_BUILD_FAILURE
+      desc: "Error occurred when building program, see build log for details"
+    - name: ERROR_PROGRAM_LINK_FAILURE
+      desc: "Error occurred when linking programs, see build log for details"
     - name: ERROR_UNSUPPORTED_VERSION
       desc: "[Validation] generic error code for unsupported versions"
     - name: ERROR_UNSUPPORTED_FEATURE
@@ -241,15 +234,15 @@ etors:
     - name: ERROR_INVALID_NATIVE_BINARY
       desc: "[Validation] native binary is not supported by the device"
     - name: ERROR_INVALID_GLOBAL_NAME
-      desc: "[Validation] global variable is not found in the module"
+      desc: "[Validation] global variable is not found in the program"
     - name: ERROR_INVALID_FUNCTION_NAME
-      desc: "[Validation] function name is not found in the module"
+      desc: "[Validation] function name is not found in the program"
     - 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
       desc: "[Validation] global width dimension is not valid for the kernel or device"
-    - name: ERROR_MODULE_UNLINKED
-      desc: "[Validation] module with imports needs to be linked before kernels can be created from it."
+    - name: ERROR_PROGRAM_UNLINKED
+      desc: "[Validation] compiled program or program with imports needs to be linked before kernels can be created from it."
     - name: ERROR_OVERLAPPING_REGIONS
       desc: "[Validation] copy operations do not support overlapping regions of memory"
     - name: ERROR_INVALID_HOST_PTR

scripts/assets/images/modules_programs.png

@@ -430,7 +430,7 @@ name: SelectBinary
 decl: static
 ordinal: "0"
 details:
-    - "The input binaries are various AOT images, and possibly a SPIR-V binary for JIT compilation."
+    - "The input binaries are various AOT images, and possibly an IL binary for JIT compilation."
     - "The selected binary will be able to be run on the target device."
     - "If no suitable binary can be found then function returns ${X}_INVALID_BINARY."
     - "The application may call this function from simultaneous threads for the same device."