HSA runtime API for ROCm#
The following functions are located in the ROCm/ROCR-Runtime repository.
-
hsa_status_t hsa_amd_vmem_address_reserve(void **va, size_t size, uint64_t address, uint64_t flags)#
Allocate a reserved address range.
Reserve a virtual address range. The size must be a multiple of the system page size. If it is not possible to allocate the address specified by
address
, thenva
will be a different address range. Address range should be released by calling hsa_amd_vmem_address_free.Note that this API will be deprecated in a future release and replaced by hsa_amd_vmem_address_reserve_align
- Parameters:
va – [out] virtual address allocated
size – [in] of address range requested
address – [in] requested
flags – [in] currently unsupported
- Return values:
::HSA_STATUS_SUCCESS – Address range allocated successfully
::HSA_STATUS_ERROR_NOT_INITIALIZED – The HSA runtime has not been initialized.
::HSA_STATUS_ERROR_OUT_OF_RESOURCES – Insufficient resources to allocate an address range of this size.
-
hsa_status_t hsa_amd_vmem_address_free(void *va, size_t size)#
Free a reserved address range.
Free a previously allocated address range. The size must match the size of a previously allocated address range.
- Parameters:
va – [out] virtual address to be freed
size – [in] of address range
- Return values:
::HSA_STATUS_SUCCESS – Address range released successfully
::HSA_STATUS_ERROR_INVALID_ALLOCATION – Invalid va specified
::HSA_STATUS_ERROR_INVALID_ARGUMENT – Invalid size specified
::HSA_STATUS_ERROR_RESOURCE_FREE – Address range is still in use
::HSA_STATUS_ERROR – Internal unexpected error
-
hsa_status_t hsa_amd_vmem_handle_create(hsa_amd_memory_pool_t pool, size_t size, hsa_amd_memory_type_t type, uint64_t flags, hsa_amd_vmem_alloc_handle_t *memory_handle)#
Create a virtual memory handle.
Create a virtual memory handle within this pool
size
must be a aligned to allocation granule size for this memory pool, see HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_GRANULE To minimize internal memory fragmentation, align the size to the recommended allocation granule size, see HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_REC_GRANULE- Parameters:
pool – [in] memory to use
size – [in] of the memory allocation
type – [in] of memory
flags – [in] - currently unsupported
memory_handle – [out] - handle for the allocation
- Return values:
::HSA_STATUS_SUCCESS – memory allocated successfully
::HSA_STATUS_ERROR_NOT_INITIALIZED – The HSA runtime has not been initialized.
::HSA_STATUS_ERROR_INVALID_ARGUMENT – Invalid arguments
::HSA_STATUS_ERROR_INVALID_ALLOCATION – This memory pool does not support allocations
::HSA_STATUS_ERROR_OUT_OF_RESOURCES – Insufficient resources to allocate this memory
-
hsa_status_t hsa_amd_vmem_handle_release(hsa_amd_vmem_alloc_handle_t memory_handle)#
Release a virtual memory handle.
- Parameters:
memory – [in] handle that was previously allocated
- Return values:
::HSA_STATUS_SUCCESS – Address range allocated successfully
::HSA_STATUS_ERROR_INVALID_ALLOCATION – Invalid memory handle
-
hsa_status_t hsa_amd_vmem_map(void *va, size_t size, size_t in_offset, hsa_amd_vmem_alloc_handle_t memory_handle, uint64_t flags)#
Map a virtual memory handle.
Map a virtual memory handle to a reserved address range. The virtual address requested must be within a previously reserved address range.
va
and (va
+ size) must be must be within (va + size) of the previous allocated address range.size
must be equal to size of thememory_handle
hsa_amd_vmem_set_access needs to be called to make the memory accessible to specific agents- Parameters:
va – [in] virtual address range where memory will be mapped
size – [in] of memory mapping
in_offset – [in] offset into memory. Currently unsupported
memory_handle – [in] virtual memory handle to be mapped
flags. – [in] Currently unsupported
- Return values:
::HSA_STATUS_SUCCESS – Memory mapped successfully
::HSA_STATUS_ERROR_INVALID_ARGUMENT – va, size or memory_handle are invalid
::HSA_STATUS_ERROR_OUT_OF_RESOURCES – Insufficient resources
::HSA_STATUS_ERROR – Unexpected internal error
-
hsa_status_t hsa_amd_vmem_unmap(void *va, size_t size)#
Unmap a virtual memory handle.
Unmap previously mapped virtual address range
- Parameters:
va – [in] virtual address range where memory will be mapped
size – [in] of memory mapping
- Return values:
::HSA_STATUS_SUCCESS – Memory backing unmapped successfully
::HSA_STATUS_ERROR_INVALID_ALLOCATION – memory_handle is invalid
::HSA_STATUS_ERROR_INVALID_ARGUMENT – size is invalid
::HSA_STATUS_ERROR – Unexpected internal error
-
hsa_status_t hsa_amd_vmem_set_access(void *va, size_t size, const hsa_amd_memory_access_desc_t *desc, size_t desc_cnt)#
Make a memory mapping accessible.
Make previously mapped virtual address accessible to specific agents.
size
must be equal to size of previously mapped virtual memory handle. Calling hsa_amd_vmem_set_access multiple times on the sameva
will overwrite previous permissions for all agents- Parameters:
va – [in] previously mapped virtual address
size – [in] of memory mapping
desc – [in] list of access permissions for each agent
desc_cnt – [in] number of elements in desc
- Return values:
::HSA_STATUS_SUCCESS –
::HSA_STATUS_ERROR_INVALID_ARGUMENT – va, size or memory_handle are invalid
::HSA_STATUS_ERROR_INVALID_ALLOCATION – memory_handle is invalid
::HSA_STATUS_ERROR_OUT_OF_RESOURCES – Insufficient resources
::HSA_STATUS_ERROR_INVALID_AGENT – Invalid agent in desc
::HSA_STATUS_ERROR – Unexpected internal error
-
hsa_status_t hsa_amd_vmem_get_access(void *va, hsa_access_permission_t *perms, hsa_agent_t agent_handle)#
Get current access permissions for memory mapping.
Get access permissions for memory mapping for specific agent.
- Parameters:
va – [in] previously mapped virtual address
perms – [in] current permissions
agent_handle – [in] agent
- Return values:
::HSA_STATUS_SUCCESS –
::HSA_STATUS_ERROR_INVALID_AGENT – Invalid agent
::HSA_STATUS_ERROR_INVALID_ALLOCATION – va is not mapped or permissions never set for this agent
::HSA_STATUS_ERROR – Unexpected internal error
Get an exportable shareable handle.
Get an exportable shareable handle for a memory_handle. This shareabl handle can then be used to re-create a virtual memory handle using hsa_amd_vmem_import_shareable_handle. The shareable handle can be transferred using mechanisms that support posix file descriptors Once all shareable handles are closed, the memory_handle is released.
- Parameters:
dmabuf_fd – [out] shareable handle
handle – [in] previously allocated virtual memory handle
flags – [in] Currently unsupported
- Return values:
::HSA_STATUS_SUCCESS –
::HSA_STATUS_ERROR_INVALID_ALLOCATION – Invalid memory handle
::HSA_STATUS_ERROR_OUT_OF_RESOURCES – Out of resources
::HSA_STATUS_ERROR – Unexpected internal error
Import a shareable handle.
Import a shareable handle for a memory handle. Importing a shareable handle that has been closed and released results in undefined behavior.
- Parameters:
dmabuf_fd – [in] shareable handle exported with hsa_amd_vmem_export_shareable_handle
handle – [out] virtual memory handle
- Return values:
::HSA_STATUS_SUCCESS –
::HSA_STATUS_ERROR_INVALID_ALLOCATION – Invalid memory handle
::HSA_STATUS_ERROR_OUT_OF_RESOURCES – Out of resources
::HSA_STATUS_ERROR – Unexpected internal error
-
hsa_status_t hsa_amd_vmem_retain_alloc_handle(hsa_amd_vmem_alloc_handle_t *memory_handle, void *addr)#
Returns memory handle for mapped memory.
Return a memory handle for previously mapped memory. The handle will be the same value of handle used to map the memory. The returned handle must be released with corresponding number of calls to hsa_amd_vmem_handle_release.
- Parameters:
memory_handle – [out] memory handle for this mapped address
mapped – [in] address
- Return values:
::HSA_STATUS_SUCCESS –
::HSA_STATUS_ERROR_INVALID_ALLOCATION – Invalid address
-
hsa_status_t hsa_amd_vmem_get_alloc_properties_from_handle(hsa_amd_vmem_alloc_handle_t memory_handle, hsa_amd_memory_pool_t *pool, hsa_amd_memory_type_t *type)#
Returns the current allocation properties of a handle.
Returns the allocation properties of an existing handle
- Parameters:
memory_handle – [in] memory handle to be queried
pool – [out] memory pool that owns this handle
memory – [out] type
- Return values:
::HSA_STATUS_SUCCESS –
::HSA_STATUS_ERROR_INVALID_ALLOCATION – Invalid memory_handle