[ur] Introduce virtual memory interfaces

Fixes #357 by introducing a port of the PI changes from intel/llvm#8954
which add the ability to reserve virtual memory regions separately from
physical memory backing allocations.

* [x] Define interfaces in the spec & header
* [ ] Add conformance tests exercising interfaces

include/ur.py

@@ -103,6 +103,11 @@ class ur_sampler_handle_t(c_void_p):
 class ur_mem_handle_t(c_void_p):
  pass
 
+###############################################################################
+## @brief Handle of physical memory object
+class ur_physical_mem_handle_t(c_void_p):
+ pass
+
 ###############################################################################
 ## @brief Generic macro for enumerator bit masks
 def UR_BIT( _i ):
@@ -225,6 +230,7 @@ class ur_structure_type_v(IntEnum):
  PROGRAM_NATIVE_PROPERTIES = 23 ## ::ur_program_native_properties_t
  SAMPLER_NATIVE_PROPERTIES = 24 ## ::ur_sampler_native_properties_t
  QUEUE_NATIVE_DESC = 25 ## ::ur_queue_native_desc_t
+ PHYSICAL_MEM_PROPERTIES = 26 ## ::ur_physical_mem_properties_t
 
 class ur_structure_type_t(c_int):
  def __str__(self):
@@ -562,6 +568,8 @@ class ur_device_info_v(IntEnum):
  HOST_PIPE_READ_WRITE_SUPPORTED = 111 ## [::ur_bool_t] Return true if the device supports enqueing commands to
  ## read and write pipes from the host.
  MAX_REGISTERS_PER_WORK_GROUP = 112 ## [uint32_t] The maximum number of registers available per block.
+ VIRTUAL_MEM_SUPPORT = 113 ## [::ur_bool_t] Return true is the device supports mapping virtual
+ ## memory ranges to physical memory allocations.
 
 class ur_device_info_t(c_int):
  def __str__(self):
@@ -1236,6 +1244,59 @@ def __str__(self):
  return str(ur_usm_pool_info_v(self.value))
 
 
+###############################################################################
+## @brief Virtual memory granularity info
+class ur_virtual_mem_granularity_info_v(IntEnum):
+ MINIMUM = 0x30100 ## [size_t] size in bytes of the minimum virtual memory granularity.
+ RECOMMENDED = 0x30101 ## [size_t] size in bytes of the recommended virtual memory granularity.
+
+class ur_virtual_mem_granularity_info_t(c_int):
+ def __str__(self):
+ return str(ur_virtual_mem_granularity_info_v(self.value))
+
+
+###############################################################################
+## @brief Virtual memory access mode flags.
+class ur_virtual_mem_access_flags_v(IntEnum):
+ READ_WRITE = UR_BIT(0) ## Virtual memory both read and write accessible
+ READ_ONLY = UR_BIT(1) ## 
+
+class ur_virtual_mem_access_flags_t(c_int):
+ def __str__(self):
+ return hex(self.value)
+
+
+###############################################################################
+## @brief Virtual memory range info queries.
+class ur_virtual_mem_info_v(IntEnum):
+ ACCESS_MODE = 0 ## [::ur_virtual_mem_access_flags_t] access flags of a mapped virtual
+ ## memory range.
+
+class ur_virtual_mem_info_t(c_int):
+ def __str__(self):
+ return str(ur_virtual_mem_info_v(self.value))
+
+
+###############################################################################
+## @brief Physical memory creation properties.
+class ur_physical_mem_flags_v(IntEnum):
+ TBD = UR_BIT(0) ## reserved for future use.
+
+class ur_physical_mem_flags_t(c_int):
+ def __str__(self):
+ return hex(self.value)
+
+
+###############################################################################
+## @brief Physical memory creation properties.
+class ur_physical_mem_properties_t(Structure):
+ _fields_ = [
+ ("stype", ur_structure_type_t), ## [in] type of this structure, must be
+ ## ::UR_STRUCTURE_TYPE_PHYSICAL_MEM_PROPERTIES
+ ("pNext", c_void_p), ## [in,out][optional] pointer to extension-specific structure
+ ("flags", ur_physical_mem_flags_t) ## [in] physical memory creation flags
+ ]
+
 ###############################################################################
 ## @brief Program metadata property type.
 class ur_program_metadata_type_v(IntEnum):
@@ -1779,13 +1840,23 @@ class ur_function_v(IntEnum):
  USM_FREE = 110 ## Enumerator for ::urUSMFree
  USM_GET_MEM_ALLOC_INFO = 111 ## Enumerator for ::urUSMGetMemAllocInfo
  USM_POOL_CREATE = 112 ## Enumerator for ::urUSMPoolCreate
+ VIRTUAL_MEM_GRANULARITY_GET_INFO = 113 ## Enumerator for ::urVirtualMemGranularityGetInfo
  PLATFORM_GET_BACKEND_OPTION = 114 ## Enumerator for ::urPlatformGetBackendOption
  MEM_BUFFER_CREATE_WITH_NATIVE_HANDLE = 115 ## Enumerator for ::urMemBufferCreateWithNativeHandle
  MEM_IMAGE_CREATE_WITH_NATIVE_HANDLE = 116 ## Enumerator for ::urMemImageCreateWithNativeHandle
  ENQUEUE_WRITE_HOST_PIPE = 117 ## Enumerator for ::urEnqueueWriteHostPipe
  USM_POOL_RETAIN = 118 ## Enumerator for ::urUSMPoolRetain
  USM_POOL_RELEASE = 119 ## Enumerator for ::urUSMPoolRelease
  USM_POOL_GET_INFO = 120 ## Enumerator for ::urUSMPoolGetInfo
+ VIRTUAL_MEM_RESERVE = 121 ## Enumerator for ::urVirtualMemReserve
+ VIRTUAL_MEM_FREE = 122 ## Enumerator for ::urVirtualMemFree
+ VIRTUAL_MEM_MAP = 123 ## Enumerator for ::urVirtualMemMap
+ VIRTUAL_MEM_UNMAP = 124 ## Enumerator for ::urVirtualMemUnmap
+ VIRTUAL_MEM_SET_ACCESS = 125 ## Enumerator for ::urVirtualMemSetAccess
+ VIRTUAL_MEM_GET_INFO = 126 ## Enumerator for ::urVirtualMemGetInfo
+ PHYSICAL_MEM_CREATE = 127 ## Enumerator for ::urPhysicalMemCreate
+ PHYSICAL_MEM_RETAIN = 128 ## Enumerator for ::urPhysicalMemRetain
+ PHYSICAL_MEM_RELEASE = 129 ## Enumerator for ::urPhysicalMemRelease
 
 class ur_function_t(c_int):
  def __str__(self):
@@ -2386,6 +2457,37 @@ class ur_mem_dditable_t(Structure):
  ("pfnImageGetInfo", c_void_p) ## _urMemImageGetInfo_t
  ]
 
+###############################################################################
+## @brief Function-pointer for urPhysicalMemCreate
+if __use_win_types:
+ _urPhysicalMemCreate_t = WINFUNCTYPE( ur_result_t, ur_context_handle_t, ur_device_handle_t, c_size_t, POINTER(ur_physical_mem_properties_t), POINTER(ur_physical_mem_handle_t) )
+else:
+ _urPhysicalMemCreate_t = CFUNCTYPE( ur_result_t, ur_context_handle_t, ur_device_handle_t, c_size_t, POINTER(ur_physical_mem_properties_t), POINTER(ur_physical_mem_handle_t) )
+
+###############################################################################
+## @brief Function-pointer for urPhysicalMemRetain
+if __use_win_types:
+ _urPhysicalMemRetain_t = WINFUNCTYPE( ur_result_t, ur_physical_mem_handle_t )
+else:
+ _urPhysicalMemRetain_t = CFUNCTYPE( ur_result_t, ur_physical_mem_handle_t )
+
+###############################################################################
+## @brief Function-pointer for urPhysicalMemRelease
+if __use_win_types:
+ _urPhysicalMemRelease_t = WINFUNCTYPE( ur_result_t, ur_physical_mem_handle_t )
+else:
+ _urPhysicalMemRelease_t = CFUNCTYPE( ur_result_t, ur_physical_mem_handle_t )
+
+
+###############################################################################
+## @brief Table of PhysicalMem functions pointers
+class ur_physical_mem_dditable_t(Structure):
+ _fields_ = [
+ ("pfnCreate", c_void_p), ## _urPhysicalMemCreate_t
+ ("pfnRetain", c_void_p), ## _urPhysicalMemRetain_t
+ ("pfnRelease", c_void_p) ## _urPhysicalMemRelease_t
+ ]
+
 ###############################################################################
 ## @brief Function-pointer for urEnqueueKernelLaunch
 if __use_win_types:
@@ -2774,6 +2876,69 @@ class ur_usm_dditable_t(Structure):
  ("pfnPoolGetInfo", c_void_p) ## _urUSMPoolGetInfo_t
  ]
 
+###############################################################################
+## @brief Function-pointer for urVirtualMemGranularityGetInfo
+if __use_win_types:
+ _urVirtualMemGranularityGetInfo_t = WINFUNCTYPE( ur_result_t, ur_context_handle_t, ur_device_handle_t, ur_virtual_mem_granularity_info_t, c_size_t, c_void_p, POINTER(c_size_t) )
+else:
+ _urVirtualMemGranularityGetInfo_t = CFUNCTYPE( ur_result_t, ur_context_handle_t, ur_device_handle_t, ur_virtual_mem_granularity_info_t, c_size_t, c_void_p, POINTER(c_size_t) )
+
+###############################################################################
+## @brief Function-pointer for urVirtualMemReserve
+if __use_win_types:
+ _urVirtualMemReserve_t = WINFUNCTYPE( ur_result_t, ur_context_handle_t, c_void_p, c_size_t, POINTER(c_void_p) )
+else:
+ _urVirtualMemReserve_t = CFUNCTYPE( ur_result_t, ur_context_handle_t, c_void_p, c_size_t, POINTER(c_void_p) )
+
+###############################################################################
+## @brief Function-pointer for urVirtualMemFree
+if __use_win_types:
+ _urVirtualMemFree_t = WINFUNCTYPE( ur_result_t, ur_context_handle_t, c_void_p, c_size_t )
+else:
+ _urVirtualMemFree_t = CFUNCTYPE( ur_result_t, ur_context_handle_t, c_void_p, c_size_t )
+
+###############################################################################
+## @brief Function-pointer for urVirtualMemMap
+if __use_win_types:
+ _urVirtualMemMap_t = WINFUNCTYPE( ur_result_t, ur_context_handle_t, c_void_p, c_size_t, ur_physical_mem_handle_t, c_size_t, ur_virtual_mem_access_flags_t )
+else:
+ _urVirtualMemMap_t = CFUNCTYPE( ur_result_t, ur_context_handle_t, c_void_p, c_size_t, ur_physical_mem_handle_t, c_size_t, ur_virtual_mem_access_flags_t )
+
+###############################################################################
+## @brief Function-pointer for urVirtualMemUnmap
+if __use_win_types:
+ _urVirtualMemUnmap_t = WINFUNCTYPE( ur_result_t, ur_context_handle_t, c_void_p, c_size_t )
+else:
+ _urVirtualMemUnmap_t = CFUNCTYPE( ur_result_t, ur_context_handle_t, c_void_p, c_size_t )
+
+###############################################################################
+## @brief Function-pointer for urVirtualMemSetAccess
+if __use_win_types:
+ _urVirtualMemSetAccess_t = WINFUNCTYPE( ur_result_t, ur_context_handle_t, c_void_p, c_size_t, ur_virtual_mem_access_flags_t )
+else:
+ _urVirtualMemSetAccess_t = CFUNCTYPE( ur_result_t, ur_context_handle_t, c_void_p, c_size_t, ur_virtual_mem_access_flags_t )
+
+###############################################################################
+## @brief Function-pointer for urVirtualMemGetInfo
+if __use_win_types:
+ _urVirtualMemGetInfo_t = WINFUNCTYPE( ur_result_t, ur_context_handle_t, c_void_p, c_size_t, ur_virtual_mem_info_t, c_size_t, c_void_p, POINTER(c_size_t) )
+else:
+ _urVirtualMemGetInfo_t = CFUNCTYPE( ur_result_t, ur_context_handle_t, c_void_p, c_size_t, ur_virtual_mem_info_t, c_size_t, c_void_p, POINTER(c_size_t) )
+
+
+###############################################################################
+## @brief Table of VirtualMem functions pointers
+class ur_virtual_mem_dditable_t(Structure):
+ _fields_ = [
+ ("pfnGranularityGetInfo", c_void_p), ## _urVirtualMemGranularityGetInfo_t
+ ("pfnReserve", c_void_p), ## _urVirtualMemReserve_t
+ ("pfnFree", c_void_p), ## _urVirtualMemFree_t
+ ("pfnMap", c_void_p), ## _urVirtualMemMap_t
+ ("pfnUnmap", c_void_p), ## _urVirtualMemUnmap_t
+ ("pfnSetAccess", c_void_p), ## _urVirtualMemSetAccess_t
+ ("pfnGetInfo", c_void_p) ## _urVirtualMemGetInfo_t
+ ]
+
 ###############################################################################
 ## @brief Function-pointer for urDeviceGet
 if __use_win_types:
@@ -2863,10 +3028,12 @@ class ur_dditable_t(Structure):
  ("Kernel", ur_kernel_dditable_t),
  ("Sampler", ur_sampler_dditable_t),
  ("Mem", ur_mem_dditable_t),
+ ("PhysicalMem", ur_physical_mem_dditable_t),
  ("Enqueue", ur_enqueue_dditable_t),
  ("Queue", ur_queue_dditable_t),
  ("Global", ur_global_dditable_t),
  ("USM", ur_usm_dditable_t),
+ ("VirtualMem", ur_virtual_mem_dditable_t),
  ("Device", ur_device_dditable_t)
  ]
 
@@ -3014,6 +3181,18 @@ def __init__(self, version : ur_api_version_t):
  self.urMemGetInfo = _urMemGetInfo_t(self.__dditable.Mem.pfnGetInfo)
  self.urMemImageGetInfo = _urMemImageGetInfo_t(self.__dditable.Mem.pfnImageGetInfo)
 
+ # call driver to get function pointers
+ PhysicalMem = ur_physical_mem_dditable_t()
+ r = ur_result_v(self.__dll.urGetPhysicalMemProcAddrTable(version, byref(PhysicalMem)))
+ if r != ur_result_v.SUCCESS:
+ raise Exception(r)
+ self.__dditable.PhysicalMem = PhysicalMem
+
+ # attach function interface to function address
+ self.urPhysicalMemCreate = _urPhysicalMemCreate_t(self.__dditable.PhysicalMem.pfnCreate)
+ self.urPhysicalMemRetain = _urPhysicalMemRetain_t(self.__dditable.PhysicalMem.pfnRetain)
+ self.urPhysicalMemRelease = _urPhysicalMemRelease_t(self.__dditable.PhysicalMem.pfnRelease)
+
  # call driver to get function pointers
  Enqueue = ur_enqueue_dditable_t()
  r = ur_result_v(self.__dll.urGetEnqueueProcAddrTable(version, byref(Enqueue)))
@@ -3095,6 +3274,22 @@ def __init__(self, version : ur_api_version_t):
  self.urUSMPoolRelease = _urUSMPoolRelease_t(self.__dditable.USM.pfnPoolRelease)
  self.urUSMPoolGetInfo = _urUSMPoolGetInfo_t(self.__dditable.USM.pfnPoolGetInfo)
 
+ # call driver to get function pointers
+ VirtualMem = ur_virtual_mem_dditable_t()
+ r = ur_result_v(self.__dll.urGetVirtualMemProcAddrTable(version, byref(VirtualMem)))
+ if r != ur_result_v.SUCCESS:
+ raise Exception(r)
+ self.__dditable.VirtualMem = VirtualMem
+
+ # attach function interface to function address
+ self.urVirtualMemGranularityGetInfo = _urVirtualMemGranularityGetInfo_t(self.__dditable.VirtualMem.pfnGranularityGetInfo)
+ self.urVirtualMemReserve = _urVirtualMemReserve_t(self.__dditable.VirtualMem.pfnReserve)
+ self.urVirtualMemFree = _urVirtualMemFree_t(self.__dditable.VirtualMem.pfnFree)
+ self.urVirtualMemMap = _urVirtualMemMap_t(self.__dditable.VirtualMem.pfnMap)
+ self.urVirtualMemUnmap = _urVirtualMemUnmap_t(self.__dditable.VirtualMem.pfnUnmap)
+ self.urVirtualMemSetAccess = _urVirtualMemSetAccess_t(self.__dditable.VirtualMem.pfnSetAccess)
+ self.urVirtualMemGetInfo = _urVirtualMemGetInfo_t(self.__dditable.VirtualMem.pfnGetInfo)
+
  # call driver to get function pointers
  Device = ur_device_dditable_t()
  r = ur_result_v(self.__dll.urGetDeviceProcAddrTable(version, byref(Device)))