HSA runtime API for ROCm

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, then va 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 the memory_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 same va 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

hsa_status_t hsa_amd_vmem_export_shareable_handle(int *dmabuf_fd, hsa_amd_vmem_alloc_handle_t handle, uint64_t flags)#

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

hsa_status_t hsa_amd_vmem_import_shareable_handle(int dmabuf_fd, hsa_amd_vmem_alloc_handle_t *handle)#

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