Virtual Mem

Virtual Mem#

oneAPI Level Zero Specification - Version 1.18.31

Virtual Mem Functions#

zeVirtualMemReserve#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeVirtualMemReserve(ze_context_handle_t hContext, const void *pStart, size_t size, void **pptr)#

Reserves pages in virtual address space.

  • The application must only use the memory allocation on the context for which it was created.

  • The starting address and size must be page aligned. See zeVirtualMemQueryPageSize.

  • If pStart is not null then implementation will attempt to reserve starting from that address. If not available then will find another suitable starting address.

  • The application may call this function from simultaneous threads.

  • The access attributes will default to none to indicate reservation is inaccessible.

  • The implementation of this function must be thread-safe.

Parameters:

  • hContext – [in] handle of the context object

  • pStart – [in][optional] pointer to start of region to reserve. If nullptr then implementation will choose a start address.

  • size – [in] size in bytes to reserve; must be page aligned.

  • pptr – [out] pointer to virtual reservation.

Returns:

zeVirtualMemFree#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeVirtualMemFree(ze_context_handle_t hContext, const void *ptr, size_t size)#

Free pages in a reserved virtual address range.

  • Any existing virtual mappings for the range will be unmapped.

  • Physical allocations objects that were mapped to this range will not be destroyed. These need to be destroyed explicitly.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Parameters:

  • hContext – [in] handle of the context object

  • ptr – [in] pointer to start of region to free.

  • size – [in] size in bytes to free; must be page aligned.

Returns:

zeVirtualMemQueryPageSize#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeVirtualMemQueryPageSize(ze_context_handle_t hContext, ze_device_handle_t hDevice, size_t size, size_t *pagesize)#

Queries page size to use for aligning virtual memory reservations and physical memory allocations.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Parameters:

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device object

  • size – [in] unaligned allocation size in bytes

  • pagesize – [out] pointer to page size to use for start address and size alignments.

Returns:

zeVirtualMemMap#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeVirtualMemMap(ze_context_handle_t hContext, const void *ptr, size_t size, ze_physical_mem_handle_t hPhysicalMemory, size_t offset, ze_memory_access_attribute_t access)#

Maps pages in virtual address space to pages from physical memory object.

  • The virtual address range must have been reserved using zeVirtualMemReserve.

  • The application must only use the mapped memory allocation on the context for which it was created.

  • The virtual start address and size must be page aligned. See zeVirtualMemQueryPageSize.

  • The application should use, for the starting address and size, the same size alignment used for the physical allocation.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Parameters:

  • hContext – [in] handle of the context object

  • ptr – [in] pointer to start of virtual address range to map.

  • size – [in] size in bytes of virtual address range to map; must be page aligned.

  • hPhysicalMemory – [in] handle to physical memory object.

  • offset – [in] offset into physical memory allocation object; must be page aligned.

  • access – [in] specifies page access attributes to apply to the virtual address range.

Returns:

zeVirtualMemUnmap#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeVirtualMemUnmap(ze_context_handle_t hContext, const void *ptr, size_t size)#

Unmaps pages in virtual address space from pages from a physical memory object.

  • The page access attributes for virtual address range will revert back to none.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Parameters:

  • hContext – [in] handle of the context object

  • ptr – [in] pointer to start of region to unmap.

  • size – [in] size in bytes to unmap; must be page aligned.

Returns:

zeVirtualMemSetAccessAttribute#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeVirtualMemSetAccessAttribute(ze_context_handle_t hContext, const void *ptr, size_t size, ze_memory_access_attribute_t access)#

Set memory access attributes for a virtual address range.

  • This function may be called from simultaneous threads with the same function handle.

  • The implementation of this function should be lock-free.

Parameters:

  • hContext – [in] handle of the context object

  • ptr – [in] pointer to start of reserved virtual address region.

  • size – [in] size in bytes; must be page aligned.

  • access – [in] specifies page access attributes to apply to the virtual address range.

Returns:

zeVirtualMemGetAccessAttribute#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeVirtualMemGetAccessAttribute(ze_context_handle_t hContext, const void *ptr, size_t size, ze_memory_access_attribute_t *access, size_t *outSize)#

Get memory access attribute for a virtual address range.

  • If size and outSize are equal then the pages in the specified virtual address range have the same access attributes.

  • This function may be called from simultaneous threads with the same function handle.

  • The implementation of this function should be lock-free.

Parameters:

  • hContext – [in] handle of the context object

  • ptr – [in] pointer to start of virtual address region for query.

  • size – [in] size in bytes; must be page aligned.

  • access – [out] query result for page access attribute.

  • outSize – [out] query result for size of virtual address range, starting at ptr, that shares same access attribute.

Returns:

Virtual Mem Enums#

ze_memory_access_attribute_t#

Added in version 1.0

enum ze_memory_access_attribute_t#

Virtual memory page access attributes.

Values:

enumerator ZE_MEMORY_ACCESS_ATTRIBUTE_NONE#

Indicates the memory page is inaccessible.

enumerator ZE_MEMORY_ACCESS_ATTRIBUTE_READWRITE#

Indicates the memory page supports read write access.

enumerator ZE_MEMORY_ACCESS_ATTRIBUTE_READONLY#

Indicates the memory page supports read-only access.

enumerator ZE_MEMORY_ACCESS_ATTRIBUTE_FORCE_UINT32#

Value marking end of ZE_MEMORY_ACCESS_ATTRIBUTE_* ENUMs.