/home/docs/checkouts/readthedocs.org/user_builds/advanced-micro-devices-hip/checkouts/ROCR-Runtime/src/inc/hsa_ext_amd.h File Reference

/home/docs/checkouts/readthedocs.org/user_builds/advanced-micro-devices-hip/checkouts/ROCR-Runtime/src/inc/hsa_ext_amd.h File Reference#

HIP Runtime API Reference: /home/docs/checkouts/readthedocs.org/user_builds/advanced-micro-devices-hip/checkouts/ROCR-Runtime/src/inc/hsa_ext_amd.h File Reference
hsa_ext_amd.h File Reference
#include "hsa.h"
#include "hsa_ext_image.h"
#include "hsa_ven_amd_pc_sampling.h"
Include dependency graph for hsa_ext_amd.h:

Go to the source code of this file.

Data Structures

struct  hsa_amd_vendor_packet_header_t
 AMD vendor specific AQL packet header. More...
 
struct  hsa_amd_barrier_value_packet_t
 AMD barrier value packet. Halts packet processing and waits for (signal_value & mask) cond value to be satisfied, where signal_value is the value of the signal signal. More...
 
struct  hsa_amd_hdp_flush_t
 
struct  hsa_amd_profiling_dispatch_time_t
 Structure containing profiling dispatch time information. More...
 
struct  hsa_amd_profiling_async_copy_time_t
 Structure containing profiling async copy time information. More...
 
struct  hsa_amd_memory_pool_t
 A memory pool encapsulates physical storage on an agent along with a memory access model. More...
 
struct  hsa_pitched_ptr_t
 
struct  hsa_amd_memory_pool_link_info_t
 Link properties when accessing the memory pool from the specified agent. More...
 
struct  hsa_amd_image_descriptor_t
 Encodes an opaque vendor specific image format. The length of data depends on the underlying format. This structure must not be copied as its true length can not be determined. More...
 
struct  hsa_amd_pointer_info_t
 Describes a memory allocation known to ROCr. Within a ROCr major version this structure can only grow. More...
 
struct  hsa_amd_ipc_memory_t
 256-bit process independent identifier for a ROCr shared memory allocation. More...
 
struct  hsa_amd_gpu_memory_fault_info_t
 AMD GPU memory fault event data. More...
 
struct  hsa_amd_gpu_hw_exception_info_t
 AMD GPU HW Exception event data. More...
 
struct  hsa_amd_event_t
 AMD GPU event data passed to event handler. More...
 
struct  hsa_amd_svm_attribute_pair_t
 
struct  hsa_amd_vmem_alloc_handle_t
 Struct containing an opaque handle to a memory allocation handle. More...
 
struct  hsa_amd_memory_access_desc_t
 

Macros

#define HSA_AMD_INTERFACE_VERSION_MAJOR   1
 
#define HSA_AMD_INTERFACE_VERSION_MINOR   6
 

Typedefs

typedef uint32_t hsa_signal_condition32_t
 A fixed-size type used to represent ::hsa_signal_condition_t constants.
 
typedef uint8_t hsa_amd_packet_type8_t
 A fixed-size type used to represent hsa_amd_packet_type_t constants.
 
typedef bool(* hsa_amd_signal_handler) (hsa_signal_value_t value, void *arg)
 Asyncronous signal handler function type.
 
typedef hsa_amd_ipc_memory_t hsa_amd_ipc_signal_t
 256-bit process independent identifier for a ROCr IPC signal.
 
typedef hsa_status_t(* hsa_amd_system_event_callback_t) (const hsa_amd_event_t *event, void *data)
 
typedef void(* hsa_amd_deallocation_callback_t) (void *ptr, void *user_data)
 Deallocation notifier function type.
 

Enumerations

enum  hsa_amd_packet_type_t { HSA_AMD_PACKET_TYPE_BARRIER_VALUE = 2 }
 AMD vendor specific packet type. More...
 
enum  {
  HSA_STATUS_ERROR_INVALID_MEMORY_POOL = 40 ,
  HSA_STATUS_ERROR_MEMORY_APERTURE_VIOLATION = 41 ,
  HSA_STATUS_ERROR_ILLEGAL_INSTRUCTION = 42 ,
  HSA_STATUS_ERROR_MEMORY_FAULT = 43 ,
  HSA_STATUS_CU_MASK_REDUCED = 44 ,
  HSA_STATUS_ERROR_OUT_OF_REGISTERS = 45 ,
  HSA_STATUS_ERROR_RESOURCE_BUSY = 46
}
 Enumeration constants added to ::hsa_status_t. More...
 
enum  hsa_amd_iommu_version_t {
  HSA_IOMMU_SUPPORT_NONE = 0 ,
  HSA_IOMMU_SUPPORT_V2 = 1
}
 IOMMU version supported. More...
 
enum  hsa_amd_agent_info_t {
  HSA_AMD_AGENT_INFO_CHIP_ID = 0xA000 ,
  HSA_AMD_AGENT_INFO_CACHELINE_SIZE = 0xA001 ,
  HSA_AMD_AGENT_INFO_COMPUTE_UNIT_COUNT = 0xA002 ,
  HSA_AMD_AGENT_INFO_MAX_CLOCK_FREQUENCY = 0xA003 ,
  HSA_AMD_AGENT_INFO_DRIVER_NODE_ID = 0xA004 ,
  HSA_AMD_AGENT_INFO_MAX_ADDRESS_WATCH_POINTS = 0xA005 ,
  HSA_AMD_AGENT_INFO_BDFID = 0xA006 ,
  HSA_AMD_AGENT_INFO_MEMORY_WIDTH = 0xA007 ,
  HSA_AMD_AGENT_INFO_MEMORY_MAX_FREQUENCY = 0xA008 ,
  HSA_AMD_AGENT_INFO_PRODUCT_NAME = 0xA009 ,
  HSA_AMD_AGENT_INFO_MAX_WAVES_PER_CU = 0xA00A ,
  HSA_AMD_AGENT_INFO_NUM_SIMDS_PER_CU = 0xA00B ,
  HSA_AMD_AGENT_INFO_NUM_SHADER_ENGINES = 0xA00C ,
  HSA_AMD_AGENT_INFO_NUM_SHADER_ARRAYS_PER_SE = 0xA00D ,
  HSA_AMD_AGENT_INFO_HDP_FLUSH = 0xA00E ,
  HSA_AMD_AGENT_INFO_DOMAIN = 0xA00F ,
  HSA_AMD_AGENT_INFO_COOPERATIVE_QUEUES = 0xA010 ,
  HSA_AMD_AGENT_INFO_UUID = 0xA011 ,
  HSA_AMD_AGENT_INFO_ASIC_REVISION = 0xA012 ,
  HSA_AMD_AGENT_INFO_SVM_DIRECT_HOST_ACCESS = 0xA013 ,
  HSA_AMD_AGENT_INFO_COOPERATIVE_COMPUTE_UNIT_COUNT = 0xA014 ,
  HSA_AMD_AGENT_INFO_MEMORY_AVAIL = 0xA015 ,
  HSA_AMD_AGENT_INFO_TIMESTAMP_FREQUENCY = 0xA016 ,
  HSA_AMD_AGENT_INFO_ASIC_FAMILY_ID = 0xA107 ,
  HSA_AMD_AGENT_INFO_UCODE_VERSION = 0xA108 ,
  HSA_AMD_AGENT_INFO_SDMA_UCODE_VERSION = 0xA109 ,
  HSA_AMD_AGENT_INFO_NUM_SDMA_ENG = 0xA10A ,
  HSA_AMD_AGENT_INFO_NUM_SDMA_XGMI_ENG = 0xA10B ,
  HSA_AMD_AGENT_INFO_IOMMU_SUPPORT = 0xA110 ,
  HSA_AMD_AGENT_INFO_NUM_XCC = 0xA111 ,
  HSA_AMD_AGENT_INFO_DRIVER_UID = 0xA112 ,
  HSA_AMD_AGENT_INFO_NEAREST_CPU = 0xA113 ,
  HSA_AMD_AGENT_INFO_MEMORY_PROPERTIES = 0xA114 ,
  HSA_AMD_AGENT_INFO_AQL_EXTENSIONS = 0xA115
}
 Agent attributes. More...
 
enum  hsa_amd_agent_memory_properties_t { HSA_AMD_MEMORY_PROPERTY_AGENT_IS_APU = (1 << 0) }
 Agent memory properties attributes. More...
 
enum  hsa_amd_sdma_engine_id_t {
  HSA_AMD_SDMA_ENGINE_0 = 0x1 ,
  HSA_AMD_SDMA_ENGINE_1 = 0x2 ,
  HSA_AMD_SDMA_ENGINE_2 = 0x4 ,
  HSA_AMD_SDMA_ENGINE_3 = 0x8 ,
  HSA_AMD_SDMA_ENGINE_4 = 0x10 ,
  HSA_AMD_SDMA_ENGINE_5 = 0x20 ,
  HSA_AMD_SDMA_ENGINE_6 = 0x40 ,
  HSA_AMD_SDMA_ENGINE_7 = 0x80 ,
  HSA_AMD_SDMA_ENGINE_8 = 0x100 ,
  HSA_AMD_SDMA_ENGINE_9 = 0x200 ,
  HSA_AMD_SDMA_ENGINE_10 = 0x400 ,
  HSA_AMD_SDMA_ENGINE_11 = 0x800 ,
  HSA_AMD_SDMA_ENGINE_12 = 0x1000 ,
  HSA_AMD_SDMA_ENGINE_13 = 0x2000 ,
  HSA_AMD_SDMA_ENGINE_14 = 0x4000 ,
  HSA_AMD_SDMA_ENGINE_15 = 0x8000
}
 SDMA engine IDs unique by single set bit position. More...
 
enum  hsa_amd_region_info_t {
  HSA_AMD_REGION_INFO_HOST_ACCESSIBLE = 0xA000 ,
  HSA_AMD_REGION_INFO_BASE = 0xA001 ,
  HSA_AMD_REGION_INFO_BUS_WIDTH = 0xA002 ,
  HSA_AMD_REGION_INFO_MAX_CLOCK_FREQUENCY = 0xA003
}
 Region attributes. More...
 
enum  hsa_amd_coherency_type_t {
  HSA_AMD_COHERENCY_TYPE_COHERENT = 0 ,
  HSA_AMD_COHERENCY_TYPE_NONCOHERENT = 1
}
 Coherency attributes of fine grain region. More...
 
enum  hsa_amd_signal_attribute_t {
  HSA_AMD_SIGNAL_AMD_GPU_ONLY = 1 ,
  HSA_AMD_SIGNAL_IPC = 2
}
 Signal attribute flags. More...
 
enum  hsa_amd_segment_t {
  HSA_AMD_SEGMENT_GLOBAL = 0 ,
  HSA_AMD_SEGMENT_READONLY = 1 ,
  HSA_AMD_SEGMENT_PRIVATE = 2 ,
  HSA_AMD_SEGMENT_GROUP = 3
}
 Memory segments associated with a memory pool. More...
 
enum  hsa_amd_memory_pool_global_flag_t {
  HSA_AMD_MEMORY_POOL_GLOBAL_FLAG_KERNARG_INIT = 1 ,
  HSA_AMD_MEMORY_POOL_GLOBAL_FLAG_FINE_GRAINED = 2 ,
  HSA_AMD_MEMORY_POOL_GLOBAL_FLAG_COARSE_GRAINED = 4 ,
  HSA_AMD_MEMORY_POOL_GLOBAL_FLAG_EXTENDED_SCOPE_FINE_GRAINED = 8
}
 
enum  hsa_amd_memory_pool_location_t {
  HSA_AMD_MEMORY_POOL_LOCATION_CPU = 0 ,
  HSA_AMD_MEMORY_POOL_LOCATION_GPU = 1
}
 
enum  hsa_amd_memory_pool_info_t {
  HSA_AMD_MEMORY_POOL_INFO_SEGMENT = 0 ,
  HSA_AMD_MEMORY_POOL_INFO_GLOBAL_FLAGS = 1 ,
  HSA_AMD_MEMORY_POOL_INFO_SIZE = 2 ,
  HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_ALLOWED = 5 ,
  HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_GRANULE = 6 ,
  HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_ALIGNMENT = 7 ,
  HSA_AMD_MEMORY_POOL_INFO_ACCESSIBLE_BY_ALL = 15 ,
  HSA_AMD_MEMORY_POOL_INFO_ALLOC_MAX_SIZE = 16 ,
  HSA_AMD_MEMORY_POOL_INFO_LOCATION = 17 ,
  HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_REC_GRANULE = 18
}
 Memory pool features. More...
 
enum  hsa_amd_memory_pool_flag_t {
  HSA_AMD_MEMORY_POOL_STANDARD_FLAG = 0 ,
  HSA_AMD_MEMORY_POOL_PCIE_FLAG = (1 << 0) ,
  HSA_AMD_MEMORY_POOL_CONTIGUOUS_FLAG = (1 << 1)
}
 Memory pool flag used to specify allocation directives. More...
 
enum  hsa_amd_copy_direction_t {
  hsaHostToHost = 0 ,
  hsaHostToDevice = 1 ,
  hsaDeviceToHost = 2 ,
  hsaDeviceToDevice = 3
}
 
enum  hsa_amd_memory_pool_access_t {
  HSA_AMD_MEMORY_POOL_ACCESS_NEVER_ALLOWED = 0 ,
  HSA_AMD_MEMORY_POOL_ACCESS_ALLOWED_BY_DEFAULT = 1 ,
  HSA_AMD_MEMORY_POOL_ACCESS_DISALLOWED_BY_DEFAULT = 2
}
 Type of accesses to a memory pool from a given agent. More...
 
enum  hsa_amd_link_info_type_t {
  HSA_AMD_LINK_INFO_TYPE_HYPERTRANSPORT = 0 ,
  HSA_AMD_LINK_INFO_TYPE_QPI = 1 ,
  HSA_AMD_LINK_INFO_TYPE_PCIE = 2 ,
  HSA_AMD_LINK_INFO_TYPE_INFINBAND = 3 ,
  HSA_AMD_LINK_INFO_TYPE_XGMI = 4
}
 Properties of the relationship between an agent a memory pool. More...
 
enum  hsa_amd_agent_memory_pool_info_t {
  HSA_AMD_AGENT_MEMORY_POOL_INFO_ACCESS = 0 ,
  HSA_AMD_AGENT_MEMORY_POOL_INFO_NUM_LINK_HOPS = 1 ,
  HSA_AMD_AGENT_MEMORY_POOL_INFO_LINK_INFO = 2
}
 Properties of the relationship between an agent a memory pool. More...
 
enum  hsa_amd_pointer_type_t {
  HSA_EXT_POINTER_TYPE_UNKNOWN = 0 ,
  HSA_EXT_POINTER_TYPE_HSA = 1 ,
  HSA_EXT_POINTER_TYPE_LOCKED = 2 ,
  HSA_EXT_POINTER_TYPE_GRAPHICS = 3 ,
  HSA_EXT_POINTER_TYPE_IPC = 4
}
 Denotes the type of memory in a pointer info query. More...
 
enum  hsa_amd_event_type_t {
  HSA_AMD_GPU_MEMORY_FAULT_EVENT = 0 ,
  HSA_AMD_GPU_HW_EXCEPTION_EVENT
}
 GPU system event type. More...
 
enum  hsa_amd_memory_fault_reason_t {
  HSA_AMD_MEMORY_FAULT_PAGE_NOT_PRESENT = 1 << 0 ,
  HSA_AMD_MEMORY_FAULT_READ_ONLY = 1 << 1 ,
  HSA_AMD_MEMORY_FAULT_NX = 1 << 2 ,
  HSA_AMD_MEMORY_FAULT_HOST_ONLY = 1 << 3 ,
  HSA_AMD_MEMORY_FAULT_DRAMECC = 1 << 4 ,
  HSA_AMD_MEMORY_FAULT_IMPRECISE = 1 << 5 ,
  HSA_AMD_MEMORY_FAULT_SRAMECC = 1 << 6 ,
  HSA_AMD_MEMORY_FAULT_HANG = 1U << 31
}
 Flags denoting the cause of a memory fault. More...
 
enum  hsa_amd_hw_exception_reset_type_t { HSA_AMD_HW_EXCEPTION_RESET_TYPE_OTHER = 1 << 0 }
 Flags denoting the type of a HW exception. More...
 
enum  hsa_amd_hw_exception_reset_cause_t {
  HSA_AMD_HW_EXCEPTION_CAUSE_GPU_HANG = 1 << 0 ,
  HSA_AMD_HW_EXCEPTION_CAUSE_ECC = 1 << 1
}
 Flags denoting the cause of a HW exception. More...
 
enum  hsa_amd_queue_priority_t {
  HSA_AMD_QUEUE_PRIORITY_LOW = 0 ,
  HSA_AMD_QUEUE_PRIORITY_NORMAL = 1 ,
  HSA_AMD_QUEUE_PRIORITY_HIGH = 2
}
 Per-queue dispatch and wavefront scheduling priority. More...
 
enum  hsa_amd_svm_model_t {
  HSA_AMD_SVM_GLOBAL_FLAG_FINE_GRAINED = 0 ,
  HSA_AMD_SVM_GLOBAL_FLAG_COARSE_GRAINED = 1 ,
  HSA_AMD_SVM_GLOBAL_FLAG_INDETERMINATE = 2
}
 
enum  hsa_amd_svm_attribute_t {
  HSA_AMD_SVM_ATTRIB_GLOBAL_FLAG = 0 ,
  HSA_AMD_SVM_ATTRIB_READ_ONLY = 1 ,
  HSA_AMD_SVM_ATTRIB_HIVE_LOCAL = 2 ,
  HSA_AMD_SVM_ATTRIB_MIGRATION_GRANULARITY = 3 ,
  HSA_AMD_SVM_ATTRIB_PREFERRED_LOCATION = 4 ,
  HSA_AMD_SVM_ATTRIB_PREFETCH_LOCATION = 5 ,
  HSA_AMD_SVM_ATTRIB_READ_MOSTLY = 6 ,
  HSA_AMD_SVM_ATTRIB_GPU_EXEC = 7 ,
  HSA_AMD_SVM_ATTRIB_AGENT_ACCESSIBLE = 0x200 ,
  HSA_AMD_SVM_ATTRIB_AGENT_ACCESSIBLE_IN_PLACE = 0x201 ,
  HSA_AMD_SVM_ATTRIB_AGENT_NO_ACCESS = 0x202 ,
  HSA_AMD_SVM_ATTRIB_ACCESS_QUERY = 0x203
}
 
enum  hsa_amd_memory_type_t {
  MEMORY_TYPE_NONE ,
  MEMORY_TYPE_PINNED
}
 
enum  hsa_queue_info_attribute_t {
  HSA_AMD_QUEUE_INFO_AGENT ,
  HSA_AMD_QUEUE_INFO_DOORBELL_ID
}
 

Functions

 return ((uint8_t *) value)[index] &(1<< subBit)
 
hsa_status_t HSA_API hsa_amd_coherency_get_type (hsa_agent_t agent, hsa_amd_coherency_type_t *type)
 Get the coherency type of the fine grain region of an agent.
 
hsa_status_t HSA_API hsa_amd_coherency_set_type (hsa_agent_t agent, hsa_amd_coherency_type_t type)
 Set the coherency type of the fine grain region of an agent. Deprecated. This is supported on KV platforms. For backward compatibility other platforms will spuriously succeed.
 
hsa_status_t HSA_API hsa_amd_profiling_set_profiler_enabled (hsa_queue_t *queue, int enable)
 Enable or disable profiling capability of a queue.
 
hsa_status_t HSA_API hsa_amd_profiling_async_copy_enable (bool enable)
 Enable or disable asynchronous memory copy profiling.
 
hsa_status_t HSA_API hsa_amd_profiling_get_dispatch_time (hsa_agent_t agent, hsa_signal_t signal, hsa_amd_profiling_dispatch_time_t *time)
 Retrieve packet processing time stamps.
 
hsa_status_t HSA_API hsa_amd_profiling_get_async_copy_time (hsa_signal_t signal, hsa_amd_profiling_async_copy_time_t *time)
 Retrieve asynchronous copy timestamps.
 
hsa_status_t HSA_API hsa_amd_profiling_convert_tick_to_system_domain (hsa_agent_t agent, uint64_t agent_tick, uint64_t *system_tick)
 Computes the frequency ratio and offset between the agent clock and HSA system clock and converts the agent's tick to HSA system domain tick.
 
hsa_status_t HSA_API hsa_amd_signal_create (hsa_signal_value_t initial_value, uint32_t num_consumers, const hsa_agent_t *consumers, uint64_t attributes, hsa_signal_t *signal)
 Create a signal with specific attributes.
 
hsa_status_t hsa_amd_signal_value_pointer (hsa_signal_t signal, volatile hsa_signal_value_t **value_ptr)
 Returns a pointer to the value of a signal.
 
hsa_status_t HSA_API hsa_amd_signal_async_handler (hsa_signal_t signal, hsa_signal_condition_t cond, hsa_signal_value_t value, hsa_amd_signal_handler handler, void *arg)
 Register asynchronous signal handler function.
 
hsa_status_t HSA_API hsa_amd_async_function (void(*callback)(void *arg), void *arg)
 Call a function asynchronously.
 
uint32_t HSA_API hsa_amd_signal_wait_any (uint32_t signal_count, hsa_signal_t *signals, hsa_signal_condition_t *conds, hsa_signal_value_t *values, uint64_t timeout_hint, hsa_wait_state_t wait_hint, hsa_signal_value_t *satisfying_value)
 Wait for any signal-condition pair to be satisfied.
 
hsa_status_t HSA_API hsa_amd_image_get_info_max_dim (hsa_agent_t agent, hsa_agent_info_t attribute, void *value)
 Query image limits.
 
hsa_status_t HSA_API hsa_amd_queue_cu_set_mask (const hsa_queue_t *queue, uint32_t num_cu_mask_count, const uint32_t *cu_mask)
 Set a queue's CU affinity mask.
 
hsa_status_t HSA_API hsa_amd_queue_cu_get_mask (const hsa_queue_t *queue, uint32_t num_cu_mask_count, uint32_t *cu_mask)
 Retrieve a queue's CU affinity mask.
 
hsa_status_t HSA_API hsa_amd_memory_pool_get_info (hsa_amd_memory_pool_t memory_pool, hsa_amd_memory_pool_info_t attribute, void *value)
 Get the current value of an attribute of a memory pool.
 
hsa_status_t HSA_API hsa_amd_agent_iterate_memory_pools (hsa_agent_t agent, hsa_status_t(*callback)(hsa_amd_memory_pool_t memory_pool, void *data), void *data)
 Iterate over the memory pools associated with a given agent, and invoke an application-defined callback on every iteration.
 
hsa_status_t HSA_API hsa_amd_memory_pool_allocate (hsa_amd_memory_pool_t memory_pool, size_t size, uint32_t flags, void **ptr)
 Allocate a block of memory (or buffer) in the specified pool.
 
hsa_status_t HSA_API hsa_amd_memory_pool_free (void *ptr)
 Deallocate a block of memory previously allocated using hsa_amd_memory_pool_allocate.
 
hsa_status_t HSA_API hsa_amd_memory_async_copy (void *dst, hsa_agent_t dst_agent, const void *src, hsa_agent_t src_agent, size_t size, uint32_t num_dep_signals, const hsa_signal_t *dep_signals, hsa_signal_t completion_signal)
 Asynchronously copy a block of memory from the location pointed to by src on the src_agent to the memory block pointed to by dst on the dst_agent. Because the DMA engines used may not be in the same coherency domain, the caller must ensure that buffers are system-level coherent. In general this requires the sending device to have released the buffer to system scope prior to executing the copy API and the receiving device must execute a system scope acquire fence prior to use of the destination buffer.
 
hsa_status_t HSA_API hsa_amd_memory_async_copy_on_engine (void *dst, hsa_agent_t dst_agent, const void *src, hsa_agent_t src_agent, size_t size, uint32_t num_dep_signals, const hsa_signal_t *dep_signals, hsa_signal_t completion_signal, hsa_amd_sdma_engine_id_t engine_id, bool force_copy_on_sdma)
 Asynchronously copy a block of memory from the location pointed to by src on the src_agent to the memory block pointed to by dst on the dst_agent on engine_id.
 
hsa_status_t HSA_API hsa_amd_memory_copy_engine_status (hsa_agent_t dst_agent, hsa_agent_t src_agent, uint32_t *engine_ids_mask)
 Reports the availability of SDMA copy engines.
 
hsa_status_t HSA_API hsa_amd_memory_async_copy_rect (const hsa_pitched_ptr_t *dst, const hsa_dim3_t *dst_offset, const hsa_pitched_ptr_t *src, const hsa_dim3_t *src_offset, const hsa_dim3_t *range, hsa_agent_t copy_agent, hsa_amd_copy_direction_t dir, uint32_t num_dep_signals, const hsa_signal_t *dep_signals, hsa_signal_t completion_signal)
 
hsa_status_t HSA_API hsa_amd_agent_memory_pool_get_info (hsa_agent_t agent, hsa_amd_memory_pool_t memory_pool, hsa_amd_agent_memory_pool_info_t attribute, void *value)
 Get the current value of an attribute of the relationship between an agent and a memory pool.
 
hsa_status_t HSA_API hsa_amd_agents_allow_access (uint32_t num_agents, const hsa_agent_t *agents, const uint32_t *flags, const void *ptr)
 Enable direct access to a buffer from a given set of agents.
 
hsa_status_t HSA_API hsa_amd_memory_pool_can_migrate (hsa_amd_memory_pool_t src_memory_pool, hsa_amd_memory_pool_t dst_memory_pool, bool *result)
 Query if buffers currently located in some memory pool can be relocated to a destination memory pool.
 
hsa_status_t HSA_API hsa_amd_memory_migrate (const void *ptr, hsa_amd_memory_pool_t memory_pool, uint32_t flags)
 Relocate a buffer to a new memory pool.
 
hsa_status_t HSA_API hsa_amd_memory_lock (void *host_ptr, size_t size, hsa_agent_t *agents, int num_agent, void **agent_ptr)
 Pin a host pointer allocated by C/C++ or OS allocator (i.e. ordinary system DRAM) and return a new pointer accessible by the agents. If the host_ptr overlaps with previously locked memory, then the overlap area is kept locked (i.e multiple mappings are permitted). In this case, the same input host_ptr may give different locked agent_ptr and when it does, they are not necessarily coherent (i.e. accessing either agent_ptr is not equivalent). Accesses to agent_ptr are coarse grained.
 
hsa_status_t HSA_API hsa_amd_memory_lock_to_pool (void *host_ptr, size_t size, hsa_agent_t *agents, int num_agent, hsa_amd_memory_pool_t pool, uint32_t flags, void **agent_ptr)
 Pin a host pointer allocated by C/C++ or OS allocator (i.e. ordinary system DRAM) and return a new pointer accessible by the agents. If the host_ptr overlaps with previously locked memory, then the overlap area is kept locked (i.e. multiple mappings are permitted). In this case, the same input host_ptr may give different locked agent_ptr and when it does, they are not necessarily coherent (i.e. accessing either agent_ptr is not equivalent). Acesses to the memory via agent_ptr have the same access properties as memory allocated from pool as determined by hsa_amd_memory_pool_get_info and hsa_amd_agent_memory_pool_get_info (ex. coarse/fine grain, platform atomic support, link info). Physical composition and placement of the memory (ex. page size, NUMA binding) is not changed.
 
hsa_status_t HSA_API hsa_amd_memory_unlock (void *host_ptr)
 Unpin the host pointer previously pinned via hsa_amd_memory_lock or hsa_amd_memory_lock_to_pool.
 
hsa_status_t HSA_API hsa_amd_memory_fill (void *ptr, uint32_t value, size_t count)
 Sets the first count of uint32_t of the block of memory pointed by ptr to the specified value.
 
hsa_status_t HSA_API hsa_amd_interop_map_buffer (uint32_t num_agents, hsa_agent_t *agents, int interop_handle, uint32_t flags, size_t *size, void **ptr, size_t *metadata_size, const void **metadata)
 Maps an interop object into the HSA flat address space and establishes memory residency. The metadata pointer is valid during the lifetime of the map (until hsa_amd_interop_unmap_buffer is called). Multiple calls to hsa_amd_interop_map_buffer with the same interop_handle result in multiple mappings with potentially different addresses and different metadata pointers. Concurrent operations on these addresses are not coherent. Memory must be fenced to system scope to ensure consistency, between mappings and with any views of this buffer in the originating software stack.
 
hsa_status_t HSA_API hsa_amd_interop_unmap_buffer (void *ptr)
 Removes a previously mapped interop object from HSA's flat address space. Ends lifetime for the mapping's associated metadata pointer.
 
hsa_status_t HSA_API hsa_amd_image_create (hsa_agent_t agent, const hsa_ext_image_descriptor_t *image_descriptor, const hsa_amd_image_descriptor_t *image_layout, const void *image_data, hsa_access_permission_t access_permission, hsa_ext_image_t *image)
 Creates an image from an opaque vendor specific image format. Does not modify data at image_data. Intended initially for accessing interop images.
 
hsa_status_t HSA_API hsa_amd_pointer_info (const void *ptr, hsa_amd_pointer_info_t *info, void *(*alloc)(size_t), uint32_t *num_agents_accessible, hsa_agent_t **accessible)
 Retrieves information about the allocation referenced by the given pointer. Optionally returns the number and list of agents which can directly access the allocation. In case this virtual address is unknown, the pointer type returned will be HSA_EXT_POINTER_TYPE_UNKNOWN and the only fields that are valid after hsa_amd_pointer_info returns are size and type.
 
hsa_status_t HSA_API hsa_amd_pointer_info_set_userdata (const void *ptr, void *userdata)
 Associates an arbitrary pointer with an allocation known to ROCr. The pointer can be fetched by hsa_amd_pointer_info in the userData field.
 
hsa_status_t HSA_API hsa_amd_ipc_memory_create (void *ptr, size_t len, hsa_amd_ipc_memory_t *handle)
 Prepares an allocation for interprocess sharing and creates a handle of type hsa_amd_ipc_memory_t uniquely identifying the allocation. A handle is valid while the allocation it references remains accessible in any process. In general applications should confirm that a shared memory region has been attached (via hsa_amd_ipc_memory_attach) in the remote process prior to releasing that memory in the local process. Repeated calls for the same allocation may, but are not required to, return unique handles. The allocation needs to be on memory on an agent of type HSA_DEVICE_TYPE_GPU.
 
hsa_status_t HSA_API hsa_amd_ipc_memory_attach (const hsa_amd_ipc_memory_t *handle, size_t len, uint32_t num_agents, const hsa_agent_t *mapping_agents, void **mapped_ptr)
 Imports shared memory into the local process and makes it accessible by the given agents. If a shared memory handle is attached multiple times in a process each attach may return a different address. Each returned address is refcounted and requires a matching number of calls to hsa_amd_ipc_memory_detach to release the shared memory mapping.
 
hsa_status_t HSA_API hsa_amd_ipc_memory_detach (void *mapped_ptr)
 Decrements the reference count for the shared memory mapping and releases access to shared memory imported with hsa_amd_ipc_memory_attach.
 
hsa_status_t HSA_API hsa_amd_ipc_signal_create (hsa_signal_t signal, hsa_amd_ipc_signal_t *handle)
 Obtains an interprocess sharing handle for a signal. The handle is valid while the signal it references remains valid in any process. In general applications should confirm that the signal has been attached (via hsa_amd_ipc_signal_attach) in the remote process prior to destroying that signal in the local process. Repeated calls for the same signal may, but are not required to, return unique handles.
 
hsa_status_t HSA_API hsa_amd_ipc_signal_attach (const hsa_amd_ipc_signal_t *handle, hsa_signal_t *signal)
 Imports an IPC capable signal into the local process. If an IPC signal handle is attached multiple times in a process each attach may return a different signal handle. Each returned signal handle is refcounted and requires a matching number of calls to hsa_signal_destroy to release the shared signal.
 
hsa_status_t HSA_API hsa_amd_register_system_event_handler (hsa_amd_system_event_callback_t callback, void *data)
 Register AMD GPU event handler.
 
hsa_status_t HSA_API hsa_amd_queue_set_priority (hsa_queue_t *queue, hsa_amd_queue_priority_t priority)
 Modifies the dispatch and wavefront scheduling prioirty for a given compute queue. The default is HSA_AMD_QUEUE_PRIORITY_NORMAL.
 
hsa_status_t HSA_API hsa_amd_register_deallocation_callback (void *ptr, hsa_amd_deallocation_callback_t callback, void *user_data)
 Registers a deallocation notifier monitoring for release of agent accessible address ptr. If successful, callback will be invoked when ptr is removed from accessibility from all agents.
 
hsa_status_t HSA_API hsa_amd_deregister_deallocation_callback (void *ptr, hsa_amd_deallocation_callback_t callback)
 Removes a deallocation notifier previously registered with hsa_amd_register_deallocation_callback. Arguments must be identical to those given in hsa_amd_register_deallocation_callback.
 
hsa_status_t hsa_amd_svm_attributes_set (void *ptr, size_t size, hsa_amd_svm_attribute_pair_t *attribute_list, size_t attribute_count)
 Sets SVM memory attributes.
 
hsa_status_t hsa_amd_svm_attributes_get (void *ptr, size_t size, hsa_amd_svm_attribute_pair_t *attribute_list, size_t attribute_count)
 Gets SVM memory attributes.
 
hsa_status_t hsa_amd_svm_prefetch_async (void *ptr, size_t size, hsa_agent_t agent, uint32_t num_dep_signals, const hsa_signal_t *dep_signals, hsa_signal_t completion_signal)
 Asynchronously migrates memory to an agent.
 
hsa_status_t hsa_amd_spm_acquire (hsa_agent_t preferred_agent)
 Acquire Stream Performance Monitor on an agent.
 
hsa_status_t hsa_amd_spm_release (hsa_agent_t preferred_agent)
 Release Stream Performance Monitor on an agent.
 
hsa_status_t hsa_amd_spm_set_dest_buffer (hsa_agent_t preferred_agent, size_t size_in_bytes, uint32_t *timeout, uint32_t *size_copied, void *dest, bool *is_data_loss)
 Set up the current destination user mode buffer for stream performance counter data. KFD will start writing SPM data into the destination buffer. KFD will continue to copy data into the current destination buffer until any of the following functions are called.
 
hsa_status_t hsa_amd_portable_export_dmabuf (const void *ptr, size_t size, int *dmabuf, uint64_t *offset)
 Obtains an OS specific, vendor neutral, handle to a memory allocation.
 
hsa_status_t hsa_amd_portable_close_dmabuf (int dmabuf)
 Closes an OS specific, vendor neutral, handle to a memory allocation.
 
hsa_status_t hsa_amd_vmem_address_reserve (void **va, size_t size, uint64_t address, uint64_t flags)
 Allocate a reserved address range.
 
hsa_status_t hsa_amd_vmem_address_reserve_align (void **va, size_t size, uint64_t address, uint64_t alignment, uint64_t flags)
 Allocate a reserved address range.
 
hsa_status_t hsa_amd_vmem_address_free (void *va, size_t size)
 Free a reserved address range.
 
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.
 
hsa_status_t hsa_amd_vmem_handle_release (hsa_amd_vmem_alloc_handle_t memory_handle)
 Release a virtual 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.
 
hsa_status_t hsa_amd_vmem_unmap (void *va, size_t size)
 Unmap a virtual memory handle.
 
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.
 
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.
 
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.
 
hsa_status_t hsa_amd_vmem_import_shareable_handle (int dmabuf_fd, hsa_amd_vmem_alloc_handle_t *handle)
 Import a shareable handle.
 
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.
 
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.
 
hsa_status_t HSA_API hsa_amd_agent_set_async_scratch_limit (hsa_agent_t agent, size_t threshold)
 Set the asynchronous scratch limit threshold on all the queues for this agent. Dispatches that are enqueued on HW queues on this agent that are smaller than threshold will not result in a scratch use-once method.
 
hsa_status_t hsa_amd_queue_get_info (hsa_queue_t *queue, hsa_queue_info_attribute_t attribute, void *value)
 

Variables

static __inline__ uint32_t bit
 
unsigned int subBit = bit % 8
 

Macro Definition Documentation

◆ HSA_AMD_INTERFACE_VERSION_MAJOR

#define HSA_AMD_INTERFACE_VERSION_MAJOR   1
  • 1.0 - initial version
  • 1.1 - dmabuf export
  • 1.2 - hsa_amd_memory_async_copy_on_engine
  • 1.3 - HSA_AMD_MEMORY_POOL_GLOBAL_FLAG_EXTENDED_SCOPE_FINE_GRAINED pool
  • 1.4 - Virtual Memory API
  • 1.5 - hsa_amd_agent_info: HSA_AMD_AGENT_INFO_MEMORY_PROPERTIES
  • 1.6 - Virtual Memory API: hsa_amd_vmem_address_reserve_align

◆ HSA_AMD_INTERFACE_VERSION_MINOR

#define HSA_AMD_INTERFACE_VERSION_MINOR   6

Typedef Documentation

◆ hsa_amd_deallocation_callback_t

typedef void(* hsa_amd_deallocation_callback_t) (void *ptr, void *user_data)

Deallocation notifier function type.

◆ hsa_amd_ipc_signal_t

256-bit process independent identifier for a ROCr IPC signal.

◆ hsa_amd_signal_handler

typedef bool(* hsa_amd_signal_handler) (hsa_signal_value_t value, void *arg)

Asyncronous signal handler function type.

Type definition of callback function to be used with hsa_amd_signal_async_handler. This callback is invoked if the associated signal and condition are met. The callback receives the value of the signal which satisfied the associated wait condition and a user provided value. If the callback returns true then the callback will be called again if the associated signal and condition are satisfied again. If the callback returns false then it will not be called again.

Parameters
[in]valueContains the value of the signal observed by hsa_amd_signal_async_handler which caused the signal handler to be invoked.
[in]argContains the user provided value given when the signal handler was registered with hsa_amd_signal_async_handler
Return values
trueresumes monitoring the signal with this handler (as if calling hsa_amd_signal_async_handler again with identical parameters)
falsestops monitoring the signal with this handler (handler will not be called again for this signal)

◆ hsa_amd_system_event_callback_t

typedef hsa_status_t(* hsa_amd_system_event_callback_t) (const hsa_amd_event_t *event, void *data)

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Enumeration constants added to ::hsa_status_t.

Remarks
Additions to hsa_status_t
Enumerator
HSA_STATUS_ERROR_INVALID_MEMORY_POOL 

The memory pool is invalid.

HSA_STATUS_ERROR_MEMORY_APERTURE_VIOLATION 

Agent accessed memory beyond the maximum legal address.

HSA_STATUS_ERROR_ILLEGAL_INSTRUCTION 

Agent executed an invalid shader instruction.

HSA_STATUS_ERROR_MEMORY_FAULT 

Agent attempted to access an inaccessible address. See hsa_amd_register_system_event_handler and HSA_AMD_GPU_MEMORY_FAULT_EVENT for more information on illegal accesses.

HSA_STATUS_CU_MASK_REDUCED 

The CU mask was successfully set but the mask attempted to enable a CU which was disabled for the process. CUs disabled for the process remain disabled.

HSA_STATUS_ERROR_OUT_OF_REGISTERS 

Exceeded number of VGPRs available on this agent

HSA_STATUS_ERROR_RESOURCE_BUSY 

Resource is busy or temporarily unavailable

◆ hsa_amd_agent_info_t

Agent attributes.

Enumerator
HSA_AMD_AGENT_INFO_CHIP_ID 

Chip identifier. The type of this attribute is uint32_t.

HSA_AMD_AGENT_INFO_CACHELINE_SIZE 

Size of a cacheline in bytes. The type of this attribute is uint32_t.

HSA_AMD_AGENT_INFO_COMPUTE_UNIT_COUNT 

The number of compute unit available in the agent. The type of this attribute is uint32_t.

HSA_AMD_AGENT_INFO_MAX_CLOCK_FREQUENCY 

The maximum clock frequency of the agent in MHz. The type of this attribute is uint32_t.

HSA_AMD_AGENT_INFO_DRIVER_NODE_ID 

Internal driver node identifier. The type of this attribute is uint32_t.

HSA_AMD_AGENT_INFO_MAX_ADDRESS_WATCH_POINTS 

Max number of watch points on memory address ranges to generate exception events when the watched addresses are accessed. The type of this attribute is uint32_t.

HSA_AMD_AGENT_INFO_BDFID 

Agent BDF_ID, named LocationID in thunk. The type of this attribute is uint32_t.

HSA_AMD_AGENT_INFO_MEMORY_WIDTH 

Memory Interface width, the return value type is uint32_t. This attribute is deprecated.

HSA_AMD_AGENT_INFO_MEMORY_MAX_FREQUENCY 

Max Memory Clock, the return value type is uint32_t.

HSA_AMD_AGENT_INFO_PRODUCT_NAME 

Board name of Agent - populated from MarketingName of Kfd Node The value is an Ascii string of 64 chars.

HSA_AMD_AGENT_INFO_MAX_WAVES_PER_CU 

Maximum number of waves possible in a Compute Unit. The type of this attribute is uint32_t.

HSA_AMD_AGENT_INFO_NUM_SIMDS_PER_CU 

Number of SIMD's per compute unit CU The type of this attribute is uint32_t.

HSA_AMD_AGENT_INFO_NUM_SHADER_ENGINES 

Number of Shader Engines (SE) in Gpu The type of this attribute is uint32_t.

HSA_AMD_AGENT_INFO_NUM_SHADER_ARRAYS_PER_SE 

Number of Shader Arrays Per Shader Engines in Gpu The type of this attribute is uint32_t.

HSA_AMD_AGENT_INFO_HDP_FLUSH 

Address of the HDP flush registers. Use of these registers does not conform to the HSA memory model and should be treated with caution. The type of this attribute is hsa_amd_hdp_flush_t.

HSA_AMD_AGENT_INFO_DOMAIN 

PCIe domain for the agent. Pairs with HSA_AMD_AGENT_INFO_BDFID to give the full physical location of the Agent. The type of this attribute is uint32_t.

HSA_AMD_AGENT_INFO_COOPERATIVE_QUEUES 

Queries for support of cooperative queues. See ::HSA_QUEUE_TYPE_COOPERATIVE. The type of this attribute is bool.

HSA_AMD_AGENT_INFO_UUID 

Queries UUID of an agent. The value is an Ascii string with a maximum of 21 chars including NUL. The string value consists of two parts: header and body. The header identifies device type (GPU, CPU, DSP) while body encodes UUID as a 16 digit hex string

Agents that do not support UUID will return the string "GPU-XX" or "CPU-XX" or "DSP-XX" depending upon their device type ::hsa_device_type_t

HSA_AMD_AGENT_INFO_ASIC_REVISION 

Queries for the ASIC revision of an agent. The value is an integer that increments for each revision. This can be used by user-level software to change how it operates, depending on the hardware version. This allows selective workarounds for hardware errata. The type of this attribute is uint32_t.

HSA_AMD_AGENT_INFO_SVM_DIRECT_HOST_ACCESS 

Queries whether or not the host can directly access SVM memory that is physically resident in the agent's local memory. The type of this attribute is bool.

HSA_AMD_AGENT_INFO_COOPERATIVE_COMPUTE_UNIT_COUNT 

Some processors support more CUs than can reliably be used in a cooperative dispatch. This queries the count of CUs which are fully enabled for cooperative dispatch. The type of this attribute is uint32_t.

HSA_AMD_AGENT_INFO_MEMORY_AVAIL 

Queries the amount of memory available in bytes accross all global pools owned by the agent. The type of this attribute is uint64_t.

HSA_AMD_AGENT_INFO_TIMESTAMP_FREQUENCY 

Timestamp value increase rate, in Hz. The timestamp (clock) frequency is in the range 1-400MHz. The type of this attribute is uint64_t.

HSA_AMD_AGENT_INFO_ASIC_FAMILY_ID 

Queries for the ASIC family ID of an agent. The type of this attribute is uint32_t.

HSA_AMD_AGENT_INFO_UCODE_VERSION 

Queries for the Packet Processor(CP Firmware) ucode version of an agent. The type of this attribute is uint32_t.

HSA_AMD_AGENT_INFO_SDMA_UCODE_VERSION 

Queries for the SDMA engine ucode of an agent. The type of this attribute is uint32_t.

HSA_AMD_AGENT_INFO_NUM_SDMA_ENG 

Queries the number of SDMA engines. If HSA_AMD_AGENT_INFO_NUM_SDMA_XGMI_ENG query returns non-zero, this query returns the the number of SDMA engines optimized for host to device bidirectional traffic. The type of this attribute is uint32_t.

HSA_AMD_AGENT_INFO_NUM_SDMA_XGMI_ENG 

Queries the number of additional SDMA engines optimized for D2D xGMI copies. The type of this attribute is uint32_t.

HSA_AMD_AGENT_INFO_IOMMU_SUPPORT 

Queries for version of IOMMU supported by agent. The type of this attribute is hsa_amd_iommu_version_t.

HSA_AMD_AGENT_INFO_NUM_XCC 

Queries for number of XCCs within the agent. The type of this attribute is uint32_t.

HSA_AMD_AGENT_INFO_DRIVER_UID 

Queries for driver unique identifier. The type of this attribute is uint32_t.

HSA_AMD_AGENT_INFO_NEAREST_CPU 

Returns the hsa_agent_t of the nearest CPU agent The type of this attribute is hsa_agent_t.

HSA_AMD_AGENT_INFO_MEMORY_PROPERTIES 

Bit-mask indicating memory properties of this agent. A memory property is set if the flag bit is set at that position. User may use the hsa_flag_isset64 macro to verify whether a flag is set. The type of this attribute is uint8_t[8].

HSA_AMD_AGENT_INFO_AQL_EXTENSIONS 

Bit-mask indicating AQL Extensions supported by this agent. An AQL extension is set if the flag bit is set at that position. User may use the hsa_flag_isset64 macro to verify whether a flag is set. The type of this attribute is uint8_t[8].

◆ hsa_amd_agent_memory_pool_info_t

Properties of the relationship between an agent a memory pool.

Enumerator
HSA_AMD_AGENT_MEMORY_POOL_INFO_ACCESS 

Access to buffers located in the memory pool. The type of this attribute is hsa_amd_memory_pool_access_t.

An agent can always directly access buffers currently located in a memory pool that is associated (the memory_pool is one of the values returned by hsa_amd_agent_iterate_memory_pools on the agent) with that agent. If the buffer is currently located in a memory pool that is not associated with the agent, and the value returned by this function for the given combination of agent and memory pool is not HSA_AMD_MEMORY_POOL_ACCESS_NEVER_ALLOWED, the application still needs to invoke hsa_amd_agents_allow_access in order to gain direct access to the buffer.

If the given agent can directly access buffers the pool, the result is not HSA_AMD_MEMORY_POOL_ACCESS_NEVER_ALLOWED. If the memory pool is associated with the agent, or it is of fined-grained type, the result must not be HSA_AMD_MEMORY_POOL_ACCESS_NEVER_ALLOWED. If the memory pool is not associated with the agent, and does not reside in the global segment, the result must be HSA_AMD_MEMORY_POOL_ACCESS_NEVER_ALLOWED.

HSA_AMD_AGENT_MEMORY_POOL_INFO_NUM_LINK_HOPS 

Number of links to hop when accessing the memory pool from the specified agent. The value of this attribute is zero if the memory pool is associated with the agent, or if the access type is HSA_AMD_MEMORY_POOL_ACCESS_NEVER_ALLOWED. The type of this attribute is uint32_t.

HSA_AMD_AGENT_MEMORY_POOL_INFO_LINK_INFO 

Details of each link hop when accessing the memory pool starting from the specified agent. The type of this attribute is an array size of HSA_AMD_AGENT_MEMORY_POOL_INFO_NUM_LINK_HOPS with each element containing hsa_amd_memory_pool_link_info_t.

◆ hsa_amd_agent_memory_properties_t

Agent memory properties attributes.

Enumerator
HSA_AMD_MEMORY_PROPERTY_AGENT_IS_APU 

◆ hsa_amd_coherency_type_t

Coherency attributes of fine grain region.

Enumerator
HSA_AMD_COHERENCY_TYPE_COHERENT 

Coherent region.

HSA_AMD_COHERENCY_TYPE_NONCOHERENT 

Non coherent region.

◆ hsa_amd_copy_direction_t

Enumerator
hsaHostToHost 
hsaHostToDevice 
hsaDeviceToHost 
hsaDeviceToDevice 

◆ hsa_amd_event_type_t

GPU system event type.

Enumerator
HSA_AMD_GPU_MEMORY_FAULT_EVENT 
HSA_AMD_GPU_HW_EXCEPTION_EVENT 

◆ hsa_amd_hw_exception_reset_cause_t

Flags denoting the cause of a HW exception.

Enumerator
HSA_AMD_HW_EXCEPTION_CAUSE_GPU_HANG 
HSA_AMD_HW_EXCEPTION_CAUSE_ECC 

◆ hsa_amd_hw_exception_reset_type_t

Flags denoting the type of a HW exception.

Enumerator
HSA_AMD_HW_EXCEPTION_RESET_TYPE_OTHER 

◆ hsa_amd_iommu_version_t

IOMMU version supported.

Enumerator
HSA_IOMMU_SUPPORT_NONE 

IOMMU not supported

HSA_IOMMU_SUPPORT_V2 

IOMMU V2 supported

◆ hsa_amd_link_info_type_t

Properties of the relationship between an agent a memory pool.

Enumerator
HSA_AMD_LINK_INFO_TYPE_HYPERTRANSPORT 

Hyper-transport bus type.

HSA_AMD_LINK_INFO_TYPE_QPI 

QPI bus type.

HSA_AMD_LINK_INFO_TYPE_PCIE 

PCIe bus type.

HSA_AMD_LINK_INFO_TYPE_INFINBAND 

Infiniband bus type.

HSA_AMD_LINK_INFO_TYPE_XGMI 

xGMI link type.

◆ hsa_amd_memory_fault_reason_t

Flags denoting the cause of a memory fault.

Enumerator
HSA_AMD_MEMORY_FAULT_PAGE_NOT_PRESENT 
HSA_AMD_MEMORY_FAULT_READ_ONLY 
HSA_AMD_MEMORY_FAULT_NX 
HSA_AMD_MEMORY_FAULT_HOST_ONLY 
HSA_AMD_MEMORY_FAULT_DRAMECC 
HSA_AMD_MEMORY_FAULT_IMPRECISE 
HSA_AMD_MEMORY_FAULT_SRAMECC 
HSA_AMD_MEMORY_FAULT_HANG 

◆ hsa_amd_memory_pool_access_t

Type of accesses to a memory pool from a given agent.

Enumerator
HSA_AMD_MEMORY_POOL_ACCESS_NEVER_ALLOWED 

The agent cannot directly access any buffer in the memory pool.

HSA_AMD_MEMORY_POOL_ACCESS_ALLOWED_BY_DEFAULT 

The agent can directly access a buffer located in the pool; the application does not need to invoke hsa_amd_agents_allow_access.

HSA_AMD_MEMORY_POOL_ACCESS_DISALLOWED_BY_DEFAULT 

The agent can directly access a buffer located in the pool, but only if the application has previously requested access to that buffer using hsa_amd_agents_allow_access.

◆ hsa_amd_memory_pool_flag_t

Memory pool flag used to specify allocation directives.

Enumerator
HSA_AMD_MEMORY_POOL_STANDARD_FLAG 

Allocates memory that conforms to standard HSA memory consistency model

HSA_AMD_MEMORY_POOL_PCIE_FLAG 

Allocates fine grain memory type where memory ordering is per point to point connection. Atomic memory operations on these memory buffers are not guaranteed to be visible at system scope.

HSA_AMD_MEMORY_POOL_CONTIGUOUS_FLAG 

Allocates physically contiguous memory

◆ hsa_amd_memory_pool_global_flag_t

Enumerator
HSA_AMD_MEMORY_POOL_GLOBAL_FLAG_KERNARG_INIT 

The application can use allocations in the memory pool to store kernel arguments, and provide the values for the kernarg segment of a kernel dispatch.

HSA_AMD_MEMORY_POOL_GLOBAL_FLAG_FINE_GRAINED 

Updates to memory in this pool conform to HSA memory consistency model. If this flag is set, then HSA_AMD_MEMORY_POOL_GLOBAL_FLAG_COARSE_GRAINED must not be set.

HSA_AMD_MEMORY_POOL_GLOBAL_FLAG_COARSE_GRAINED 

Writes to memory in this pool can be performed by a single agent at a time.

HSA_AMD_MEMORY_POOL_GLOBAL_FLAG_EXTENDED_SCOPE_FINE_GRAINED 

Updates to memory in this memory pool have extended scope, acting as system-scope atomics for variables in memory regions of this type. Note: On non-compliant systems, device-specific actions may be required for system-scope coherence.

◆ hsa_amd_memory_pool_info_t

Memory pool features.

Enumerator
HSA_AMD_MEMORY_POOL_INFO_SEGMENT 

Segment where the memory pool resides. The type of this attribute is hsa_amd_segment_t.

HSA_AMD_MEMORY_POOL_INFO_GLOBAL_FLAGS 

Flag mask. The value of this attribute is undefined if the value of HSA_AMD_MEMORY_POOL_INFO_SEGMENT is not HSA_AMD_SEGMENT_GLOBAL. The type of this attribute is uint32_t, a bit-field of hsa_amd_memory_pool_global_flag_t values.

HSA_AMD_MEMORY_POOL_INFO_SIZE 

Size of this pool, in bytes. The type of this attribute is size_t.

HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_ALLOWED 

Indicates whether memory in this pool can be allocated using hsa_amd_memory_pool_allocate. The type of this attribute is bool.

The value of this flag is always false for memory pools in the group and private segments.

HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_GRANULE 

Allocation granularity of buffers allocated by hsa_amd_memory_pool_allocate in this memory pool. The size of a buffer allocated in this pool is a multiple of the value of this attribute. While this is the minimum size of allocation allowed, it is recommened to use HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_REC_GRANULE to obtain the recommended allocation granularity size for this pool. The value of this attribute is only defined if HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_ALLOWED is true for this pool. The type of this attribute is size_t.

HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_ALIGNMENT 

Alignment of buffers allocated by hsa_amd_memory_pool_allocate in this pool. The value of this attribute is only defined if HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_ALLOWED is true for this pool, and must be a power of 2. The type of this attribute is size_t.

HSA_AMD_MEMORY_POOL_INFO_ACCESSIBLE_BY_ALL 

This memory_pool can be made directly accessible by all the agents in the system (hsa_amd_agent_memory_pool_get_info does not return HSA_AMD_MEMORY_POOL_ACCESS_NEVER_ALLOWED for any agent). The type of this attribute is bool.

HSA_AMD_MEMORY_POOL_INFO_ALLOC_MAX_SIZE 

Maximum aggregate allocation size in bytes. The type of this attribute is size_t.

HSA_AMD_MEMORY_POOL_INFO_LOCATION 

Location of this memory pool. The type of this attribute is hsa_amd_memory_pool_location_t.

HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_REC_GRANULE 

Internal block size for allocations. This would also be the recommended granularity size for allocations as this prevents internal fragmentation. The value of this attribute is only defined if HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_ALLOWED is true for this pool. The size of this attribute is size_t.

◆ hsa_amd_memory_pool_location_t

Enumerator
HSA_AMD_MEMORY_POOL_LOCATION_CPU 

This memory pool resides on the host (CPU)

HSA_AMD_MEMORY_POOL_LOCATION_GPU 

This memory pool resides on a GPU

◆ hsa_amd_memory_type_t

Enumerator
MEMORY_TYPE_NONE 
MEMORY_TYPE_PINNED 

◆ hsa_amd_pointer_type_t

Denotes the type of memory in a pointer info query.

Enumerator
HSA_EXT_POINTER_TYPE_UNKNOWN 
HSA_EXT_POINTER_TYPE_HSA 
HSA_EXT_POINTER_TYPE_LOCKED 
HSA_EXT_POINTER_TYPE_GRAPHICS 
HSA_EXT_POINTER_TYPE_IPC 

◆ hsa_amd_queue_priority_t

Per-queue dispatch and wavefront scheduling priority.

Enumerator
HSA_AMD_QUEUE_PRIORITY_LOW 
HSA_AMD_QUEUE_PRIORITY_NORMAL 
HSA_AMD_QUEUE_PRIORITY_HIGH 

◆ hsa_amd_region_info_t

Region attributes.

Enumerator
HSA_AMD_REGION_INFO_HOST_ACCESSIBLE 

Determine if host can access the region. The type of this attribute is bool.

HSA_AMD_REGION_INFO_BASE 

Base address of the region in flat address space.

HSA_AMD_REGION_INFO_BUS_WIDTH 

Memory Interface width, the return value type is uint32_t. This attribute is deprecated. Use HSA_AMD_AGENT_INFO_MEMORY_WIDTH.

HSA_AMD_REGION_INFO_MAX_CLOCK_FREQUENCY 

Max Memory Clock, the return value type is uint32_t. This attribute is deprecated. Use HSA_AMD_AGENT_INFO_MEMORY_MAX_FREQUENCY.

◆ hsa_amd_sdma_engine_id_t

SDMA engine IDs unique by single set bit position.

Enumerator
HSA_AMD_SDMA_ENGINE_0 
HSA_AMD_SDMA_ENGINE_1 
HSA_AMD_SDMA_ENGINE_2 
HSA_AMD_SDMA_ENGINE_3 
HSA_AMD_SDMA_ENGINE_4 
HSA_AMD_SDMA_ENGINE_5 
HSA_AMD_SDMA_ENGINE_6 
HSA_AMD_SDMA_ENGINE_7 
HSA_AMD_SDMA_ENGINE_8 
HSA_AMD_SDMA_ENGINE_9 
HSA_AMD_SDMA_ENGINE_10 
HSA_AMD_SDMA_ENGINE_11 
HSA_AMD_SDMA_ENGINE_12 
HSA_AMD_SDMA_ENGINE_13 
HSA_AMD_SDMA_ENGINE_14 
HSA_AMD_SDMA_ENGINE_15 

◆ hsa_amd_segment_t

Memory segments associated with a memory pool.

Enumerator
HSA_AMD_SEGMENT_GLOBAL 

Global segment. Used to hold data that is shared by all agents.

HSA_AMD_SEGMENT_READONLY 

Read-only segment. Used to hold data that remains constant during the execution of a kernel.

HSA_AMD_SEGMENT_PRIVATE 

Private segment. Used to hold data that is local to a single work-item.

HSA_AMD_SEGMENT_GROUP 

Group segment. Used to hold data that is shared by the work-items of a work-group.

◆ hsa_amd_signal_attribute_t

Signal attribute flags.

Enumerator
HSA_AMD_SIGNAL_AMD_GPU_ONLY 

Signal will only be consumed by AMD GPUs. Limits signal consumption to AMD GPU agents only. Ignored if num_consumers is not zero (all agents).

HSA_AMD_SIGNAL_IPC 

Signal may be used for interprocess communication. IPC signals can be read, written, and waited on from any process. Profiling using an IPC enabled signal is only supported in a single process at a time. Producing profiling data in one process and consuming it in another process is undefined.

◆ hsa_amd_svm_attribute_t

Enumerator
HSA_AMD_SVM_ATTRIB_GLOBAL_FLAG 
HSA_AMD_SVM_ATTRIB_READ_ONLY 
HSA_AMD_SVM_ATTRIB_HIVE_LOCAL 
HSA_AMD_SVM_ATTRIB_MIGRATION_GRANULARITY 
HSA_AMD_SVM_ATTRIB_PREFERRED_LOCATION 
HSA_AMD_SVM_ATTRIB_PREFETCH_LOCATION 
HSA_AMD_SVM_ATTRIB_READ_MOSTLY 
HSA_AMD_SVM_ATTRIB_GPU_EXEC 
HSA_AMD_SVM_ATTRIB_AGENT_ACCESSIBLE 
HSA_AMD_SVM_ATTRIB_AGENT_ACCESSIBLE_IN_PLACE 
HSA_AMD_SVM_ATTRIB_AGENT_NO_ACCESS 
HSA_AMD_SVM_ATTRIB_ACCESS_QUERY 

◆ hsa_amd_svm_model_t

Enumerator
HSA_AMD_SVM_GLOBAL_FLAG_FINE_GRAINED 

Updates to memory with this attribute conform to HSA memory consistency model.

HSA_AMD_SVM_GLOBAL_FLAG_COARSE_GRAINED 

Writes to memory with this attribute can be performed by a single agent at a time.

HSA_AMD_SVM_GLOBAL_FLAG_INDETERMINATE 

Memory region queried contains subregions with both HSA_AMD_SVM_GLOBAL_FLAG_COARSE_GRAINED and HSA_AMD_SVM_GLOBAL_FLAG_FINE_GRAINED attributes.

This attribute can not be used in hsa_amd_svm_attributes_set. It is a possible return from hsa_amd_svm_attributes_get indicating that the query region contains both coarse and fine grained memory.

◆ hsa_queue_info_attribute_t

Enumerator
HSA_AMD_QUEUE_INFO_AGENT 
HSA_AMD_QUEUE_INFO_DOORBELL_ID 

Function Documentation

◆ hsa_amd_agent_iterate_memory_pools()

hsa_status_t HSA_API hsa_amd_agent_iterate_memory_pools ( hsa_agent_t  agent,
hsa_status_t(*)(hsa_amd_memory_pool_t memory_pool, void *data)  callback,
void *  data 
)

Iterate over the memory pools associated with a given agent, and invoke an application-defined callback on every iteration.

An agent can directly access buffers located in some memory pool, or be enabled to access them by the application (see hsa_amd_agents_allow_access), yet that memory pool may not be returned by this function for that given agent.

A memory pool of fine-grained type must be associated only with the host.

Parameters
[in]agentA valid agent.
[in]callbackCallback to be invoked on the same thread that called hsa_amd_agent_iterate_memory_pools, serially, once per memory pool that is associated with the agent. The HSA runtime passes two arguments to the callback: the memory pool, and the application data. If callback returns a status other than ::HSA_STATUS_SUCCESS for a particular iteration, the traversal stops and hsa_amd_agent_iterate_memory_pools returns that status value.
[in]dataApplication data that is passed to callback on every iteration. May be NULL.
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_INVALID_AGENTThe agent is invalid.
::HSA_STATUS_ERROR_INVALID_ARGUMENTcallback is NULL.

◆ hsa_amd_agent_memory_pool_get_info()

hsa_status_t HSA_API hsa_amd_agent_memory_pool_get_info ( hsa_agent_t  agent,
hsa_amd_memory_pool_t  memory_pool,
hsa_amd_agent_memory_pool_info_t  attribute,
void *  value 
)

Get the current value of an attribute of the relationship between an agent and a memory pool.

Parameters
[in]agentAgent.
[in]memory_poolMemory pool.
[in]attributeAttribute to query.
[out]valuePointer to a application-allocated buffer where to store the value of the attribute. If the buffer passed by the application is not large enough to hold the value of attribute, the behavior is undefined.
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully.

◆ hsa_amd_agent_set_async_scratch_limit()

hsa_status_t HSA_API hsa_amd_agent_set_async_scratch_limit ( hsa_agent_t  agent,
size_t  threshold 
)

Set the asynchronous scratch limit threshold on all the queues for this agent. Dispatches that are enqueued on HW queues on this agent that are smaller than threshold will not result in a scratch use-once method.

Increasing this threshold will only increase the internal limit and not cause immediate allocation of additional scratch memory. Decreasing this threshold will result in a release in scratch memory on queues where the current amount of allocated scratch exceeds the new limit.

This API is only supported on devices that support asynchronous scratch reclaim.

Parameters
[in]agentA valid agent.
[in]thresholdThreshold size in bytes
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_INVALID_AGENTThe agent is invalid.
::HSA_STATUS_ERROR_INVALID_ARGUMENTThis agent does not support asynchronous scratch reclaim

◆ hsa_amd_agents_allow_access()

hsa_status_t HSA_API hsa_amd_agents_allow_access ( uint32_t  num_agents,
const hsa_agent_t *  agents,
const uint32_t *  flags,
const void *  ptr 
)

Enable direct access to a buffer from a given set of agents.

Upon return, only the listed agents and the agent associated with the buffer's memory pool have direct access to the ptr.

Any agent that has access to the buffer before and after the call to hsa_amd_agents_allow_access will also have access while hsa_amd_agents_allow_access is in progress.

The caller is responsible for ensuring that each agent in the list must be able to access the memory pool containing ptr (using hsa_amd_agent_memory_pool_get_info with HSA_AMD_AGENT_MEMORY_POOL_INFO_ACCESS attribute), otherwise error code is returned.

Parameters
[in]num_agentsSize of agents.
[in]agentsList of agents. If num_agents is 0, this argument is ignored.
[in]flagsA list of bit-field that is used to specify access information in a per-agent basis. This is currently reserved and must be NULL.
[in]ptrA buffer previously allocated using hsa_amd_memory_pool_allocate.
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_INVALID_ARGUMENTnum_agents is 0, or agents is NULL, flags is not NULL, or attempting to enable access to agent(s) because ptr is allocated from an inaccessible pool.

◆ hsa_amd_async_function()

hsa_status_t HSA_API hsa_amd_async_function ( void(*)(void *arg)  callback,
void *  arg 
)

Call a function asynchronously.

Provides access to the runtime's asynchronous event handling thread for general asynchronous functions. Functions queued this way are executed in the same manner as if they were a signal handler who's signal is satisfied.

Parameters
[in]callbackasynchronous function to be invoked
[in]arguser provided value which is provided to handler when handler is invoked
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_INVALID_ARGUMENThandler is invalid (NULL)
::HSA_STATUS_ERROR_OUT_OF_RESOURCESThe HSA runtime is out of resources or blocking signals are not supported by the HSA driver component.

◆ hsa_amd_coherency_get_type()

hsa_status_t HSA_API hsa_amd_coherency_get_type ( hsa_agent_t  agent,
hsa_amd_coherency_type_t type 
)

Get the coherency type of the fine grain region of an agent.

Parameters
[in]agentA valid agent.
[out]typePointer to a memory location where the HSA runtime will store the coherency type of the fine grain region.
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_INVALID_AGENTThe agent is invalid.
::HSA_STATUS_ERROR_INVALID_ARGUMENTtype is NULL.

◆ hsa_amd_coherency_set_type()

hsa_status_t HSA_API hsa_amd_coherency_set_type ( hsa_agent_t  agent,
hsa_amd_coherency_type_t  type 
)

Set the coherency type of the fine grain region of an agent. Deprecated. This is supported on KV platforms. For backward compatibility other platforms will spuriously succeed.

Parameters
[in]agentA valid agent.
[in]typeThe coherency type to be set.
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_INVALID_AGENTThe agent is invalid.
::HSA_STATUS_ERROR_INVALID_ARGUMENTtype is invalid.

◆ hsa_amd_deregister_deallocation_callback()

hsa_status_t HSA_API hsa_amd_deregister_deallocation_callback ( void *  ptr,
hsa_amd_deallocation_callback_t  callback 
)

Removes a deallocation notifier previously registered with hsa_amd_register_deallocation_callback. Arguments must be identical to those given in hsa_amd_register_deallocation_callback.

Parameters
[in]ptrAgent accessible address which was monitored for deallocation.
[in]callbackNotifier to be removed.
Return values
::HSA_STATUS_SUCCESSThe notifier has been removed successfully.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_INVALID_ARGUMENTThe given notifier was not registered.

◆ hsa_amd_image_create()

hsa_status_t HSA_API hsa_amd_image_create ( hsa_agent_t  agent,
const hsa_ext_image_descriptor_t *  image_descriptor,
const hsa_amd_image_descriptor_t image_layout,
const void *  image_data,
hsa_access_permission_t  access_permission,
hsa_ext_image_t *  image 
)

Creates an image from an opaque vendor specific image format. Does not modify data at image_data. Intended initially for accessing interop images.

Parameters
agent[in]Agent on which to create the image
[in]image_descriptor[in]Vendor specific image format
[in]image_dataPointer to image backing store
[in]access_permissionAccess permissions for the image object
[out]imageCreated image object.
Return values
HSA_STATUS_SUCCESSImage created successfully
HSA_STATUS_ERROR_NOT_INITIALIZEDif HSA is not initialized
HSA_STATUS_ERROR_OUT_OF_RESOURCESif there is a failure in allocating necessary resources
HSA_STATUS_ERROR_INVALID_ARGUMENTBad or mismatched descriptor, null image_data, or mismatched access_permission.

◆ hsa_amd_image_get_info_max_dim()

hsa_status_t HSA_API hsa_amd_image_get_info_max_dim ( hsa_agent_t  agent,
hsa_agent_info_t  attribute,
void *  value 
)

Query image limits.

Parameters
[in]agentA valid agent.
[in]attributeHSA image info attribute to query.
[out]valuePointer to an application-allocated buffer where to store the value of the attribute. If the buffer passed by the application is not large enough to hold the value of attribute, the behavior is undefined.
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_INVALID_QUEUEvalue is NULL or attribute < HSA_EXT_AGENT_INFO_IMAGE_1D_MAX_ELEMENTS or attribute > HSA_EXT_AGENT_INFO_IMAGE_ARRAY_MAX_LAYERS.

◆ hsa_amd_interop_map_buffer()

hsa_status_t HSA_API hsa_amd_interop_map_buffer ( uint32_t  num_agents,
hsa_agent_t *  agents,
int  interop_handle,
uint32_t  flags,
size_t *  size,
void **  ptr,
size_t *  metadata_size,
const void **  metadata 
)

Maps an interop object into the HSA flat address space and establishes memory residency. The metadata pointer is valid during the lifetime of the map (until hsa_amd_interop_unmap_buffer is called). Multiple calls to hsa_amd_interop_map_buffer with the same interop_handle result in multiple mappings with potentially different addresses and different metadata pointers. Concurrent operations on these addresses are not coherent. Memory must be fenced to system scope to ensure consistency, between mappings and with any views of this buffer in the originating software stack.

Parameters
[in]num_agentsNumber of agents which require access to the memory
[in]agentsList of accessing agents.
[in]interop_handleHandle of interop buffer (dmabuf handle in Linux)
[in]flagsReserved, must be 0
[out]sizeSize in bytes of the mapped object
[out]ptrBase address of the mapped object
[out]metadata_sizeSize of metadata in bytes, may be NULL
[out]metadataPointer to metadata, may be NULL
Return values
HSA_STATUS_SUCCESSif successfully mapped
HSA_STATUS_ERROR_NOT_INITIALIZEDif HSA is not initialized
HSA_STATUS_ERROR_OUT_OF_RESOURCESif there is a failure in allocating necessary resources
HSA_STATUS_ERROR_INVALID_ARGUMENTall other errors

◆ hsa_amd_interop_unmap_buffer()

hsa_status_t HSA_API hsa_amd_interop_unmap_buffer ( void *  ptr)

Removes a previously mapped interop object from HSA's flat address space. Ends lifetime for the mapping's associated metadata pointer.

◆ hsa_amd_ipc_memory_attach()

hsa_status_t HSA_API hsa_amd_ipc_memory_attach ( const hsa_amd_ipc_memory_t handle,
size_t  len,
uint32_t  num_agents,
const hsa_agent_t *  mapping_agents,
void **  mapped_ptr 
)

Imports shared memory into the local process and makes it accessible by the given agents. If a shared memory handle is attached multiple times in a process each attach may return a different address. Each returned address is refcounted and requires a matching number of calls to hsa_amd_ipc_memory_detach to release the shared memory mapping.

Parameters
[in]handlePointer to the identifier for the shared memory.
[in]lenLength of the shared memory to import. Reserved. Must be the full length of the shared allocation in this version.
[in]num_agentsCount of agents in mapping_agents. May be zero if all agents are to be allowed access.
[in]mapping_agentsList of agents to access the shared memory. Ignored if num_agents is zero.
[out]mapped_ptrRecieves a process local pointer to the shared memory.
Return values
HSA_STATUS_SUCCESSif memory is successfully imported.
HSA_STATUS_ERROR_NOT_INITIALIZEDif HSA is not initialized
HSA_STATUS_ERROR_OUT_OF_RESOURCESif there is a failure in allocating necessary resources
HSA_STATUS_ERROR_INVALID_ARGUMENThandle is not valid, len is incorrect, mapped_ptr is NULL, or some agent for which access was requested can not access the shared memory.

◆ hsa_amd_ipc_memory_create()

hsa_status_t HSA_API hsa_amd_ipc_memory_create ( void *  ptr,
size_t  len,
hsa_amd_ipc_memory_t handle 
)

Prepares an allocation for interprocess sharing and creates a handle of type hsa_amd_ipc_memory_t uniquely identifying the allocation. A handle is valid while the allocation it references remains accessible in any process. In general applications should confirm that a shared memory region has been attached (via hsa_amd_ipc_memory_attach) in the remote process prior to releasing that memory in the local process. Repeated calls for the same allocation may, but are not required to, return unique handles. The allocation needs to be on memory on an agent of type HSA_DEVICE_TYPE_GPU.

Parameters
[in]ptrPointer to device memory allocated via ROCr APIs to prepare for sharing.
[in]lenLength in bytes of the allocation to share.
[out]handleProcess independent identifier referencing the shared allocation.
Return values
HSA_STATUS_SUCCESSallocation is prepared for interprocess sharing.
HSA_STATUS_ERROR_NOT_INITIALIZEDif HSA is not initialized
HSA_STATUS_ERROR_OUT_OF_RESOURCESif there is a failure in allocating necessary resources
HSA_STATUS_ERROR_INVALID_ARGUMENTptr does not point to the first byte of an allocation made through ROCr, or len is not the full length of the allocation or handle is NULL.

◆ hsa_amd_ipc_memory_detach()

hsa_status_t HSA_API hsa_amd_ipc_memory_detach ( void *  mapped_ptr)

Decrements the reference count for the shared memory mapping and releases access to shared memory imported with hsa_amd_ipc_memory_attach.

Parameters
[in]mapped_ptrPointer to the first byte of a shared allocation imported with hsa_amd_ipc_memory_attach.
Return values
HSA_STATUS_SUCCESSif mapped_ptr was imported with hsa_amd_ipc_memory_attach.
HSA_STATUS_ERROR_NOT_INITIALIZEDif HSA is not initialized
HSA_STATUS_ERROR_INVALID_ARGUMENTmapped_ptr was not imported with hsa_amd_ipc_memory_attach.

◆ hsa_amd_ipc_signal_attach()

hsa_status_t HSA_API hsa_amd_ipc_signal_attach ( const hsa_amd_ipc_signal_t handle,
hsa_signal_t *  signal 
)

Imports an IPC capable signal into the local process. If an IPC signal handle is attached multiple times in a process each attach may return a different signal handle. Each returned signal handle is refcounted and requires a matching number of calls to hsa_signal_destroy to release the shared signal.

Parameters
[in]handlePointer to the identifier for the shared signal.
[out]signalRecieves a process local signal handle to the shared signal.
Return values
HSA_STATUS_SUCCESSif the signal is successfully imported.
HSA_STATUS_ERROR_NOT_INITIALIZEDif HSA is not initialized
HSA_STATUS_ERROR_OUT_OF_RESOURCESif there is a failure in allocating necessary resources
HSA_STATUS_ERROR_INVALID_ARGUMENThandle is not valid.

◆ hsa_amd_ipc_signal_create()

hsa_status_t HSA_API hsa_amd_ipc_signal_create ( hsa_signal_t  signal,
hsa_amd_ipc_signal_t handle 
)

Obtains an interprocess sharing handle for a signal. The handle is valid while the signal it references remains valid in any process. In general applications should confirm that the signal has been attached (via hsa_amd_ipc_signal_attach) in the remote process prior to destroying that signal in the local process. Repeated calls for the same signal may, but are not required to, return unique handles.

Parameters
[in]signalSignal created with attribute HSA_AMD_SIGNAL_IPC.
[out]handleProcess independent identifier referencing the shared signal.
Return values
HSA_STATUS_SUCCESShandle is ready to use for interprocess sharing.
HSA_STATUS_ERROR_NOT_INITIALIZEDif HSA is not initialized
HSA_STATUS_ERROR_OUT_OF_RESOURCESif there is a failure in allocating necessary resources
HSA_STATUS_ERROR_INVALID_ARGUMENTsignal is not a valid signal created with attribute HSA_AMD_SIGNAL_IPC or handle is NULL.

◆ hsa_amd_memory_async_copy()

hsa_status_t HSA_API hsa_amd_memory_async_copy ( void *  dst,
hsa_agent_t  dst_agent,
const void *  src,
hsa_agent_t  src_agent,
size_t  size,
uint32_t  num_dep_signals,
const hsa_signal_t *  dep_signals,
hsa_signal_t  completion_signal 
)

Asynchronously copy a block of memory from the location pointed to by src on the src_agent to the memory block pointed to by dst on the dst_agent. Because the DMA engines used may not be in the same coherency domain, the caller must ensure that buffers are system-level coherent. In general this requires the sending device to have released the buffer to system scope prior to executing the copy API and the receiving device must execute a system scope acquire fence prior to use of the destination buffer.

Parameters
[out]dstBuffer where the content is to be copied.
[in]dst_agentAgent associated with the dst. The agent must be able to directly access both the source and destination buffers in their current locations. May be zero in which case the runtime will attempt to discover the destination agent. Discovery may have variable and/or high latency.
[in]srcA valid pointer to the source of data to be copied. The source buffer must not overlap with the destination buffer, otherwise the copy will succeed but contents of dst is undefined.
[in]src_agentAgent associated with the src. The agent must be able to directly access both the source and destination buffers in their current locations. May be zero in which case the runtime will attempt to discover the destination agent. Discovery may have variable and/or high latency.
[in]sizeNumber of bytes to copy. If size is 0, no copy is performed and the function returns success. Copying a number of bytes larger than the size of the buffers pointed by dst or src results in undefined behavior.
[in]num_dep_signalsNumber of dependent signals. Can be 0.
[in]dep_signalsList of signals that must be waited on before the copy operation starts. The copy will start after every signal has been observed with the value 0. The dependent signal should not include completion signal from hsa_amd_memory_async_copy operation to be issued in future as that can result in a deadlock. If num_dep_signals is 0, this argument is ignored.
[in]completion_signalSignal used to indicate completion of the copy operation. When the copy operation is finished, the value of the signal is decremented. The runtime indicates that an error has occurred during the copy operation by setting the value of the completion signal to a negative number. The signal handle must not be 0.
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully. The application is responsible for checking for asynchronous error conditions (see the description of completion_signal).
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_INVALID_AGENTAn agent is invalid or no discovered agent has access.
::HSA_STATUS_ERROR_INVALID_SIGNALcompletion_signal is invalid.
::HSA_STATUS_ERROR_INVALID_ARGUMENTThe source or destination pointers are NULL, or the completion signal is 0.

◆ hsa_amd_memory_async_copy_on_engine()

hsa_status_t HSA_API hsa_amd_memory_async_copy_on_engine ( void *  dst,
hsa_agent_t  dst_agent,
const void *  src,
hsa_agent_t  src_agent,
size_t  size,
uint32_t  num_dep_signals,
const hsa_signal_t *  dep_signals,
hsa_signal_t  completion_signal,
hsa_amd_sdma_engine_id_t  engine_id,
bool  force_copy_on_sdma 
)

Asynchronously copy a block of memory from the location pointed to by src on the src_agent to the memory block pointed to by dst on the dst_agent on engine_id.

WARNING: Concurrent use of this call with hsa_amd_memory_async_copy can result in resource conflicts as HSA runtime will auto assign engines with the latter call. Approach using both calls concurrently with caution.

All param definitions are identical to hsa_amd_memory_async_copy with the exception of engine_id and force_copy_on_sdma.

Parameters
[in]-engine_id Target engine defined by hsa_amd_sdma_engine_id_t. Client should use hsa_amd_memory_copy_engine_status first to get the ID availability.
[in]-force_copy_on_sdma By default, blit kernel copies are used when dst_agent == src_agent. Setting this to true will force the copy over SDMA1.

All return definitions are identical to hsa_amd_memory_async_copy with the following ammendments:

Return values
::HSA_STATUS_ERROR_INVALID_ARGUMENTThe source or destination pointers are NULL, or the completion signal is 0 or engine_id is improperly bounded.

◆ hsa_amd_memory_async_copy_rect()

hsa_status_t HSA_API hsa_amd_memory_async_copy_rect ( const hsa_pitched_ptr_t dst,
const hsa_dim3_t *  dst_offset,
const hsa_pitched_ptr_t src,
const hsa_dim3_t *  src_offset,
const hsa_dim3_t *  range,
hsa_agent_t  copy_agent,
hsa_amd_copy_direction_t  dir,
uint32_t  num_dep_signals,
const hsa_signal_t *  dep_signals,
hsa_signal_t  completion_signal 
)

◆ hsa_amd_memory_copy_engine_status()

hsa_status_t HSA_API hsa_amd_memory_copy_engine_status ( hsa_agent_t  dst_agent,
hsa_agent_t  src_agent,
uint32_t *  engine_ids_mask 
)

Reports the availability of SDMA copy engines.

Parameters
[in]dst_agentDestination agent of copy status direction.
[in]src_agentSource agent of copy status direction.
[out]engine_ids_maskreturns available SDMA engine IDs that can be masked with hsa_amd_sdma_engine_id_t.
Return values
::HSA_STATUS_SUCCESSAgent has available SDMA engines.
::HSA_STATUS_ERROR_OUT_OF_RESOURCESAgent does not have available SDMA engines.
::HSA_STATUS_ERROR_INVALID_AGENTdst_agent and src_agent are the same as dst_agent == src_agent is generally used for shader copies.

◆ hsa_amd_memory_fill()

hsa_status_t HSA_API hsa_amd_memory_fill ( void *  ptr,
uint32_t  value,
size_t  count 
)

Sets the first count of uint32_t of the block of memory pointed by ptr to the specified value.

Parameters
[in]ptrPointer to the block of memory to fill.
[in]valueValue to be set.
[in]countNumber of uint32_t element to be set to the value.
Return values
HSA_STATUS_SUCCESSThe function has been executed successfully.
HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
HSA_STATUS_ERROR_INVALID_ARGUMENTptr is NULL or not 4 bytes aligned
HSA_STATUS_ERROR_INVALID_ALLOCATIONif the given memory region was not allocated with HSA runtime APIs.

◆ hsa_amd_memory_lock()

hsa_status_t HSA_API hsa_amd_memory_lock ( void *  host_ptr,
size_t  size,
hsa_agent_t *  agents,
int  num_agent,
void **  agent_ptr 
)

Pin a host pointer allocated by C/C++ or OS allocator (i.e. ordinary system DRAM) and return a new pointer accessible by the agents. If the host_ptr overlaps with previously locked memory, then the overlap area is kept locked (i.e multiple mappings are permitted). In this case, the same input host_ptr may give different locked agent_ptr and when it does, they are not necessarily coherent (i.e. accessing either agent_ptr is not equivalent). Accesses to agent_ptr are coarse grained.

Parameters
[in]host_ptrA buffer allocated by C/C++ or OS allocator.
[in]sizeThe size to be locked.
[in]agentsArray of agent handle to gain access to the host_ptr. If this parameter is NULL and the num_agent is 0, all agents in the platform will gain access to the host_ptr.
[out]agent_ptrPointer to the location where to store the new address.
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_OUT_OF_RESOURCESThere is a failure in allocating the necessary resources.
::HSA_STATUS_ERROR_INVALID_AGENTOne or more agent in agents is invalid.
::HSA_STATUS_ERROR_INVALID_ARGUMENTsize is 0 or host_ptr or agent_ptr is NULL or agents not NULL but num_agent is 0 or agents is NULL but num_agent is not 0.

◆ hsa_amd_memory_lock_to_pool()

hsa_status_t HSA_API hsa_amd_memory_lock_to_pool ( void *  host_ptr,
size_t  size,
hsa_agent_t *  agents,
int  num_agent,
hsa_amd_memory_pool_t  pool,
uint32_t  flags,
void **  agent_ptr 
)

Pin a host pointer allocated by C/C++ or OS allocator (i.e. ordinary system DRAM) and return a new pointer accessible by the agents. If the host_ptr overlaps with previously locked memory, then the overlap area is kept locked (i.e. multiple mappings are permitted). In this case, the same input host_ptr may give different locked agent_ptr and when it does, they are not necessarily coherent (i.e. accessing either agent_ptr is not equivalent). Acesses to the memory via agent_ptr have the same access properties as memory allocated from pool as determined by hsa_amd_memory_pool_get_info and hsa_amd_agent_memory_pool_get_info (ex. coarse/fine grain, platform atomic support, link info). Physical composition and placement of the memory (ex. page size, NUMA binding) is not changed.

Parameters
[in]host_ptrA buffer allocated by C/C++ or OS allocator.
[in]sizeThe size to be locked.
[in]agentsArray of agent handle to gain access to the host_ptr. If this parameter is NULL and the num_agent is 0, all agents in the platform will gain access to the host_ptr.
[in]poolGlobal memory pool owned by a CPU agent.
[in]flagsA bit-field that is used to specify allocation directives. Reserved parameter, must be 0.
[out]agent_ptrPointer to the location where to store the new address.
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_OUT_OF_RESOURCESThere is a failure in allocating the necessary resources.
::HSA_STATUS_ERROR_INVALID_AGENTOne or more agent in agents is invalid or can not access pool.
HSA_STATUS_ERROR_INVALID_MEMORY_POOLpool is invalid or not owned by a CPU agent.
::HSA_STATUS_ERROR_INVALID_ARGUMENTsize is 0 or host_ptr or agent_ptr is NULL or agents not NULL but num_agent is 0 or agents is NULL but num_agent is not 0 or flags is not 0.

◆ hsa_amd_memory_migrate()

hsa_status_t HSA_API hsa_amd_memory_migrate ( const void *  ptr,
hsa_amd_memory_pool_t  memory_pool,
uint32_t  flags 
)

Relocate a buffer to a new memory pool.

When a buffer is migrated, its virtual address remains the same but its physical contents are moved to the indicated memory pool.

After migration, only the agent associated with the destination pool will have access.

The caller is also responsible for ensuring that the allocation in the source memory pool where the buffer is currently located can be migrated to the specified destination memory pool (using hsa_amd_memory_pool_can_migrate returns a value of true for the source and destination memory pools), otherwise behavior is undefined.

The caller must ensure that the buffer is not accessed while it is migrated.

Parameters
[in]ptrBuffer to be relocated. The buffer must have been released to system prior to call this API. The buffer will be released to system upon completion.
[in]memory_poolMemory pool where to place the buffer.
[in]flagsA bit-field that is used to specify migration information. Must be zero.
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
HSA_STATUS_ERROR_INVALID_MEMORY_POOLThe destination memory pool is invalid.
::HSA_STATUS_ERROR_OUT_OF_RESOURCESThere is a failure in allocating the necessary resources.
::HSA_STATUS_ERROR_INVALID_ARGUMENTflags is not 0.

◆ hsa_amd_memory_pool_allocate()

hsa_status_t HSA_API hsa_amd_memory_pool_allocate ( hsa_amd_memory_pool_t  memory_pool,
size_t  size,
uint32_t  flags,
void **  ptr 
)

Allocate a block of memory (or buffer) in the specified pool.

Parameters
[in]memory_poolMemory pool where to allocate memory from. The memory pool must have the HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_ALLOWED flag set.
[in]sizeAllocation size, in bytes. Must not be zero. This value is rounded up to the nearest multiple of HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_GRANULE in memory_pool.
[in]flagsA bit-field that is used to specify allocation directives.
[out]ptrPointer to the location where to store the base virtual address of the allocated block. The returned base address is aligned to the value of HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_ALIGNMENT in memory_pool. If the allocation fails, the returned value is undefined.
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_OUT_OF_RESOURCESNo memory is available.
HSA_STATUS_ERROR_INVALID_MEMORY_POOLThe memory pool is invalid.
::HSA_STATUS_ERROR_INVALID_ALLOCATIONThe host is not allowed to allocate memory in memory_pool, or size is greater than the value of HSA_AMD_MEMORY_POOL_INFO_ALLOC_MAX_SIZE in memory_pool.
::HSA_STATUS_ERROR_INVALID_ARGUMENTptr is NULL, or size is 0, or flags is not 0.

◆ hsa_amd_memory_pool_can_migrate()

hsa_status_t HSA_API hsa_amd_memory_pool_can_migrate ( hsa_amd_memory_pool_t  src_memory_pool,
hsa_amd_memory_pool_t  dst_memory_pool,
bool *  result 
)

Query if buffers currently located in some memory pool can be relocated to a destination memory pool.

If the returned value is non-zero, a migration of a buffer to dst_memory_pool using hsa_amd_memory_migrate may nevertheless fail due to resource limitations.

Parameters
[in]src_memory_poolSource memory pool.
[in]dst_memory_poolDestination memory pool.
[out]resultPointer to a memory location where the result of the query is stored. Must not be NULL. If buffers currently located in src_memory_pool can be relocated to dst_memory_pool, the result is true.
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
HSA_STATUS_ERROR_INVALID_MEMORY_POOLOne of the memory pools is invalid.
::HSA_STATUS_ERROR_INVALID_ARGUMENTresult is NULL.

◆ hsa_amd_memory_pool_free()

hsa_status_t HSA_API hsa_amd_memory_pool_free ( void *  ptr)

Deallocate a block of memory previously allocated using hsa_amd_memory_pool_allocate.

Parameters
[in]ptrPointer to a memory block. If ptr does not match a value previously returned by hsa_amd_memory_pool_allocate, the behavior is undefined.
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.

◆ hsa_amd_memory_pool_get_info()

hsa_status_t HSA_API hsa_amd_memory_pool_get_info ( hsa_amd_memory_pool_t  memory_pool,
hsa_amd_memory_pool_info_t  attribute,
void *  value 
)

Get the current value of an attribute of a memory pool.

Parameters
[in]memory_poolA valid memory pool.
[in]attributeAttribute to query.
[out]valuePointer to a application-allocated buffer where to store the value of the attribute. If the buffer passed by the application is not large enough to hold the value of attribute, the behavior is undefined.
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully.

◆ hsa_amd_memory_unlock()

hsa_status_t HSA_API hsa_amd_memory_unlock ( void *  host_ptr)

Unpin the host pointer previously pinned via hsa_amd_memory_lock or hsa_amd_memory_lock_to_pool.

The behavior is undefined if the host pointer being unpinned does not match previous pinned address or if the host pointer was already deallocated.

Parameters
[in]host_ptrA buffer allocated by C/C++ or OS allocator that was pinned previously via hsa_amd_memory_lock or hsa_amd_memory_lock_to_pool.
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.

◆ hsa_amd_pointer_info()

hsa_status_t HSA_API hsa_amd_pointer_info ( const void *  ptr,
hsa_amd_pointer_info_t info,
void *(*)(size_t)  alloc,
uint32_t *  num_agents_accessible,
hsa_agent_t **  accessible 
)

Retrieves information about the allocation referenced by the given pointer. Optionally returns the number and list of agents which can directly access the allocation. In case this virtual address is unknown, the pointer type returned will be HSA_EXT_POINTER_TYPE_UNKNOWN and the only fields that are valid after hsa_amd_pointer_info returns are size and type.

Parameters
[in]ptrPointer which references the allocation to retrieve info for.
[in,out]infoPointer to structure to be filled with allocation info. Data member size must be set to the size of the structure prior to calling hsa_amd_pointer_info. On return size will be set to the size of the pointer info structure supported by the runtime, if smaller. Members beyond the returned value of size will not be updated by the API. Must not be NULL.
[in]allocFunction pointer to an allocator used to allocate the accessible array. If NULL accessible will not be returned.
[out]num_agents_accessibleRecieves the count of agents in accessible. If NULL accessible will not be returned.
[out]accessibleRecieves a pointer to the array, allocated by alloc, holding the list of agents which may directly access the allocation. May be NULL.
Return values
HSA_STATUS_SUCCESSInfo retrieved successfully
HSA_STATUS_ERROR_NOT_INITIALIZEDif HSA is not initialized
HSA_STATUS_ERROR_OUT_OF_RESOURCESif there is a failure in allocating necessary resources
HSA_STATUS_ERROR_INVALID_ARGUMENTNULL in ptr or info.

◆ hsa_amd_pointer_info_set_userdata()

hsa_status_t HSA_API hsa_amd_pointer_info_set_userdata ( const void *  ptr,
void *  userdata 
)

Associates an arbitrary pointer with an allocation known to ROCr. The pointer can be fetched by hsa_amd_pointer_info in the userData field.

Parameters
[in]ptrPointer to the first byte of an allocation known to ROCr with which to associate userdata.
[in]userdataAbitrary pointer to associate with the allocation.
Return values
HSA_STATUS_SUCCESSuserdata successfully stored.
HSA_STATUS_ERROR_NOT_INITIALIZEDif HSA is not initialized
HSA_STATUS_ERROR_OUT_OF_RESOURCESif there is a failure in allocating necessary resources
HSA_STATUS_ERROR_INVALID_ARGUMENTptr is not known to ROCr.

◆ hsa_amd_portable_close_dmabuf()

hsa_status_t hsa_amd_portable_close_dmabuf ( int  dmabuf)

Closes an OS specific, vendor neutral, handle to a memory allocation.

Closes an OS specific handle to GPU agent memory.

Applications should close a handle after imports are complete. The handle is not required to remain open for the lifetime of imported mappings. The referenced allocation will remain valid until all handles and mappings are closed.

Parameters
[in]dmabufHandle to be closed.
Return values
::HSA_STATUS_SUCCESSHandle closed successfully.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_RESOURCE_FREEA generic error was encountered when closing the handle. The handle may have been closed already or an async IO error may have occured.

◆ hsa_amd_portable_export_dmabuf()

hsa_status_t hsa_amd_portable_export_dmabuf ( const void *  ptr,
size_t  size,
int *  dmabuf,
uint64_t *  offset 
)

Obtains an OS specific, vendor neutral, handle to a memory allocation.

Obtains an OS specific handle to GPU agent memory. The memory must be part of a single allocation from an hsa_amd_memory_pool_t exposed by a GPU Agent. The handle may be used with other APIs (e.g. Vulkan) to obtain shared access to the allocation.

Shared access to the memory is not guaranteed to be fine grain coherent even if the allocation exported is from a fine grain pool. The shared memory consistency model will be no stronger than the model exported from, consult the importing API to determine the final consistency model.

The allocation's memory remains valid as long as the handle and any mapping of the handle remains valid. When the handle and all mappings are closed the backing memory will be released for reuse.

Parameters
[in]ptrPointer to the allocation being exported.
[in]sizeSize in bytes to export following ptr. The entire range being exported must be contained within a single allocation.
[out]dmabufPointer to a dma-buf file descriptor holding a reference to the allocation. Contents will not be altered in the event of failure.
[out]offsetOffset in bytes into the memory referenced by the dma-buf object at which ptr resides. Contents will not be altered in the event of failure.
Return values
::HSA_STATUS_SUCCESSExport completed successfully.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_INVALID_ARGUMENTOne or more arguments is NULL.
::HSA_STATUS_ERROR_INVALID_ALLOCATIONThe address range described by ptr and size are not contained within a single allocation.
::HSA_STATUS_ERROR_INVALID_AGENTThe allocation described by ptr and size was allocated on a device which can not export memory.
::HSA_STATUS_ERROR_OUT_OF_RESOURCESThe return file descriptor, dmabuf, could not be created.

◆ hsa_amd_profiling_async_copy_enable()

hsa_status_t HSA_API hsa_amd_profiling_async_copy_enable ( bool  enable)

Enable or disable asynchronous memory copy profiling.

The runtime will provide the copy processing start timestamp and completion timestamp of each call to hsa_amd_memory_async_copy if the async copy profiling is enabled prior to the call to hsa_amd_memory_async_copy. The completion signal object is used to hold the last async copy start and end timestamp. The client can retrieve these timestamps via call to hsa_amd_profiling_get_async_copy_time.

Parameters
[in]enableTrue to enable profiling. False to disable profiling.
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_OUT_OF_RESOURCESFailed on allocating resources needed to profile the asynchronous copy.

◆ hsa_amd_profiling_convert_tick_to_system_domain()

hsa_status_t HSA_API hsa_amd_profiling_convert_tick_to_system_domain ( hsa_agent_t  agent,
uint64_t  agent_tick,
uint64_t *  system_tick 
)

Computes the frequency ratio and offset between the agent clock and HSA system clock and converts the agent's tick to HSA system domain tick.

Parameters
[in]agentThe agent used to retrieve the agent_tick. It is user's responsibility to make sure the tick number is from this agent, otherwise, the behavior is undefined.
[in]agent_tickThe tick count retrieved from the specified agent.
[out]system_tickThe translated HSA system domain clock counter tick.
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_INVALID_AGENTThe agent is invalid.
::HSA_STATUS_ERROR_INVALID_ARGUMENTsystem_tick is NULL;

◆ hsa_amd_profiling_get_async_copy_time()

hsa_status_t HSA_API hsa_amd_profiling_get_async_copy_time ( hsa_signal_t  signal,
hsa_amd_profiling_async_copy_time_t time 
)

Retrieve asynchronous copy timestamps.

Async copy profiling is enabled via call to hsa_amd_profiling_async_copy_enable.

Parameters
[in]signalA signal used as the completion signal of the call to hsa_amd_memory_async_copy.
[out]timeAsync copy processing timestamps in the HSA system clock domain.
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_INVALID_SIGNALThe signal is invalid.
::HSA_STATUS_ERROR_INVALID_ARGUMENTtime is NULL.

◆ hsa_amd_profiling_get_dispatch_time()

hsa_status_t HSA_API hsa_amd_profiling_get_dispatch_time ( hsa_agent_t  agent,
hsa_signal_t  signal,
hsa_amd_profiling_dispatch_time_t time 
)

Retrieve packet processing time stamps.

Parameters
[in]agentThe agent with which the signal was last used. For instance, if the profiled dispatch packet is dispatched onto queue Q, which was created on agent A, then this parameter must be A.
[in]signalA signal used as the completion signal of the dispatch packet to retrieve time stamps from. This dispatch packet must have been issued to a queue with profiling enabled and have already completed. Also the signal must not have yet been used in any other packet following the completion of the profiled dispatch packet.
[out]timePacket processing timestamps in the HSA system clock domain.
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_INVALID_AGENTThe agent is invalid.
::HSA_STATUS_ERROR_INVALID_SIGNALThe signal is invalid.
::HSA_STATUS_ERROR_INVALID_ARGUMENTtime is NULL.

◆ hsa_amd_profiling_set_profiler_enabled()

hsa_status_t HSA_API hsa_amd_profiling_set_profiler_enabled ( hsa_queue_t *  queue,
int  enable 
)

Enable or disable profiling capability of a queue.

Parameters
[in]queueA valid queue.
[in]enable1 to enable profiling. 0 to disable profiling.
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_INVALID_QUEUEThe queue is invalid.
::HSA_STATUS_ERROR_INVALID_ARGUMENTqueue is NULL.

◆ hsa_amd_queue_cu_get_mask()

hsa_status_t HSA_API hsa_amd_queue_cu_get_mask ( const hsa_queue_t *  queue,
uint32_t  num_cu_mask_count,
uint32_t *  cu_mask 
)

Retrieve a queue's CU affinity mask.

Returns the first num_cu_mask_count bits of a queue's CU mask. Ensure that num_cu_mask_count is at least as large as HSA_AMD_AGENT_INFO_COMPUTE_UNIT_COUNT to retrieve the entire mask.

Parameters
[in]queueA pointer to HSA queue.
[in]num_cu_mask_countSize of CUMask bit array passed in, in bits.
[out]cu_maskBit-vector representing the CU mask.
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_INVALID_QUEUEqueue is NULL or invalid.
::HSA_STATUS_ERROR_INVALID_ARGUMENTnum_cu_mask_count is 0, not a multiple of 32 or cu_mask is NULL.

◆ hsa_amd_queue_cu_set_mask()

hsa_status_t HSA_API hsa_amd_queue_cu_set_mask ( const hsa_queue_t *  queue,
uint32_t  num_cu_mask_count,
const uint32_t *  cu_mask 
)

Set a queue's CU affinity mask.

Enables the queue to run on only selected CUs. The given mask is combined by bitwise AND with any device wide mask in HSA_CU_MASK before being applied. If num_cu_mask_count is 0 then the request is interpreted as a request to enable all CUs and no cu_mask array need be given.

Parameters
[in]queueA pointer to HSA queue.
[in]num_cu_mask_countSize of CUMask bit array passed in, in bits.
[in]cu_maskBit-vector representing the CU mask.
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully.
HSA_STATUS_CU_MASK_REDUCEDThe function was successfully executed but the given mask attempted to enable a CU which was disabled by HSA_CU_MASK. CUs disabled by HSA_CU_MASK remain disabled.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_INVALID_QUEUEqueue is NULL or invalid.
::HSA_STATUS_ERROR_INVALID_ARGUMENTnum_cu_mask_count is not a multiple of 32 or num_cu_mask_count is not 0 and cu_mask is NULL. Devices with work group processors must even-index contiguous pairwise CU enable e.g. 0x33(b'110011) is valid while 0x5(0x101) and 0x6(b'0110) are invalid.

◆ hsa_amd_queue_get_info()

hsa_status_t hsa_amd_queue_get_info ( hsa_queue_t *  queue,
hsa_queue_info_attribute_t  attribute,
void *  value 
)

◆ hsa_amd_queue_set_priority()

hsa_status_t HSA_API hsa_amd_queue_set_priority ( hsa_queue_t *  queue,
hsa_amd_queue_priority_t  priority 
)

Modifies the dispatch and wavefront scheduling prioirty for a given compute queue. The default is HSA_AMD_QUEUE_PRIORITY_NORMAL.

Parameters
[in]queueCompute queue to apply new priority to.
[in]priorityPriority to associate with queue.
Return values
HSA_STATUS_SUCCESSif priority was changed successfully.
HSA_STATUS_ERROR_INVALID_QUEUEif queue is not a valid compute queue handle.
HSA_STATUS_ERROR_INVALID_ARGUMENTif priority is not a valid value from hsa_amd_queue_priority_t.

◆ hsa_amd_register_deallocation_callback()

hsa_status_t HSA_API hsa_amd_register_deallocation_callback ( void *  ptr,
hsa_amd_deallocation_callback_t  callback,
void *  user_data 
)

Registers a deallocation notifier monitoring for release of agent accessible address ptr. If successful, callback will be invoked when ptr is removed from accessibility from all agents.

Notification callbacks are automatically deregistered when they are invoked.

Note: The current version supports notifications of address release originating from hsa_amd_memory_pool_free. Support for other address release APIs will follow.

Parameters
[in]ptrAgent accessible address to monitor for deallocation. Passed to callback.
[in]callbackNotifier to be invoked when ptr is released from agent accessibility.
[in]user_dataUser provided value passed to callback. May be NULL.
Return values
::HSA_STATUS_SUCCESSThe notifier registered successfully
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_INVALID_ALLOCATIONptr does not refer to a valid agent accessible address.
::HSA_STATUS_ERROR_INVALID_ARGUMENTcallback is NULL or ptr is NULL.
::HSA_STATUS_ERROR_OUT_OF_RESOURCESif there is a failure in allocating necessary resources

◆ hsa_amd_register_system_event_handler()

hsa_status_t HSA_API hsa_amd_register_system_event_handler ( hsa_amd_system_event_callback_t  callback,
void *  data 
)

Register AMD GPU event handler.

Parameters
[in]callbackCallback to be invoked when an event is triggered. The HSA runtime passes two arguments to the callback: event is defined per event by the HSA runtime, and data is the user data.
[in]dataUser data that is passed to callback. May be NULL.
Return values
HSA_STATUS_SUCCESSThe handler has been registered successfully.
HSA_STATUS_ERRORAn event handler has already been registered.
HSA_STATUS_ERROR_INVALID_ARGUMENTevent is invalid.

◆ hsa_amd_signal_async_handler()

hsa_status_t HSA_API hsa_amd_signal_async_handler ( hsa_signal_t  signal,
hsa_signal_condition_t  cond,
hsa_signal_value_t  value,
hsa_amd_signal_handler  handler,
void *  arg 
)

Register asynchronous signal handler function.

Allows registering a callback function and user provided value with a signal and wait condition. The callback will be invoked if the associated signal and wait condition are satisfied. Callbacks will be invoked serially but in an arbitrary order so callbacks should be independent of each other. After being invoked a callback may continue to wait for its associated signal and condition and, possibly, be invoked again. Or the callback may stop waiting. If the callback returns true then it will continue waiting and may be called again. If false then the callback will not wait again and will not be called again for the associated signal and condition. It is possible to register the same callback multiple times with the same or different signals and/or conditions. Each registration of the callback will be treated entirely independently.

Parameters
[in]signalhsa signal to be asynchronously monitored
[in]condcondition value to monitor for
[in]valuesignal value used in condition expression
[in]handlerasynchronous signal handler invoked when signal's condition is met
[in]arguser provided value which is provided to handler when handler is invoked
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_INVALID_SIGNALsignal is not a valid hsa_signal_t
::HSA_STATUS_ERROR_INVALID_ARGUMENThandler is invalid (NULL)
::HSA_STATUS_ERROR_OUT_OF_RESOURCESThe HSA runtime is out of resources or blocking signals are not supported by the HSA driver component.

◆ hsa_amd_signal_create()

hsa_status_t HSA_API hsa_amd_signal_create ( hsa_signal_value_t  initial_value,
uint32_t  num_consumers,
const hsa_agent_t *  consumers,
uint64_t  attributes,
hsa_signal_t *  signal 
)

Create a signal with specific attributes.

Parameters
[in]initial_valueInitial value of the signal.
[in]num_consumersSize of consumers. A value of 0 indicates that any agent might wait on the signal.
[in]consumersList of agents that might consume (wait on) the signal. If num_consumers is 0, this argument is ignored; otherwise, the HSA runtime might use the list to optimize the handling of the signal object. If an agent not listed in consumers waits on the returned signal, the behavior is undefined. The memory associated with consumers can be reused or freed after the function returns.
[in]attributesRequested signal attributes. Multiple signal attributes may be requested by combining them with bitwise OR. Requesting no attributes (attributes == 0) results in the same signal as would have been obtained via hsa_signal_create.
[out]signalPointer to a memory location where the HSA runtime will store the newly created signal handle. Must not be NULL.
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_OUT_OF_RESOURCESThe HSA runtime failed to allocate the required resources.
::HSA_STATUS_ERROR_INVALID_ARGUMENTsignal is NULL, num_consumers is greater than 0 but consumers is NULL, or consumers contains duplicates.

◆ hsa_amd_signal_value_pointer()

hsa_status_t hsa_amd_signal_value_pointer ( hsa_signal_t  signal,
volatile hsa_signal_value_t **  value_ptr 
)

Returns a pointer to the value of a signal.

Use of this API does not modify the lifetime of ::signal and any hsa_signal_value_t retrieved by this API has lifetime equal to that of ::signal.

This API is intended for partial interoperability with non-HSA compatible devices and should not be used where HSA interfaces are available.

Use of the signal value must comply with use restritions of ::signal. Use may result in data races if the operations performed are not platform atomic. Use with HSA_AMD_SIGNAL_AMD_GPU_ONLY or HSA_AMD_SIGNAL_IPC attributed signals is required.

Parameters
[in]Signalhandle to extract the signal value pointer from.
[out]Locationwhere the extracted signal value pointer will be placed.
Return values
::HSA_STATUS_SUCCESSThe function has been executed successfully.
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_INVALID_SIGNALsignal is not a valid hsa_signal_t
::HSA_STATUS_ERROR_INVALID_ARGUMENTvalue_ptr is NULL.

◆ hsa_amd_signal_wait_any()

uint32_t HSA_API hsa_amd_signal_wait_any ( uint32_t  signal_count,
hsa_signal_t *  signals,
hsa_signal_condition_t *  conds,
hsa_signal_value_t *  values,
uint64_t  timeout_hint,
hsa_wait_state_t  wait_hint,
hsa_signal_value_t *  satisfying_value 
)

Wait for any signal-condition pair to be satisfied.

Allows waiting for any of several signal and conditions pairs to be satisfied. The function returns the index into the list of signals of the first satisfying signal-condition pair. The value of the satisfying signal's value is returned in satisfying_value unless satisfying_value is NULL. This function provides only relaxed memory semantics.

◆ hsa_amd_spm_acquire()

hsa_status_t hsa_amd_spm_acquire ( hsa_agent_t  preferred_agent)

Acquire Stream Performance Monitor on an agent.

Acquire exclusive use of SPM on preferred_agent. See hsa_amd_spm_set_dest_buffer to provide a destination buffer to KFD to start recording and retrieve this data.

Parameters
[in]preferred_agentAgent on which to acquire SPM

◆ hsa_amd_spm_release()

hsa_status_t hsa_amd_spm_release ( hsa_agent_t  preferred_agent)

Release Stream Performance Monitor on an agent.

Release exclusive use of SPM on preferred_agent. This will stop KFD writing SPM data. If a destination buffer is set, then data in the destination buffer is available to user when this function returns.

Parameters
[in]preferred_agentAgent on which to release SPM

◆ hsa_amd_spm_set_dest_buffer()

hsa_status_t hsa_amd_spm_set_dest_buffer ( hsa_agent_t  preferred_agent,
size_t  size_in_bytes,
uint32_t *  timeout,
uint32_t *  size_copied,
void *  dest,
bool *  is_data_loss 
)

Set up the current destination user mode buffer for stream performance counter data. KFD will start writing SPM data into the destination buffer. KFD will continue to copy data into the current destination buffer until any of the following functions are called.

  • hsa_amd_spm_release
  • hsa_amd_spm_set_dest_buffer with dest set to NULL
  • hsa_amd_spm_set_dest_buffer with dest set to a new buffer

if timeout is non-0, the call will wait for up to timeout ms for the previous buffer to be filled. If previous buffer to be filled before timeout, the timeout will be updated value with the time remaining. If the timeout is exceeded, the function copies any partial data available into the previous user buffer and returns success. User should not access destination data while KFD is copying data. If the previous destination buffer was full, then is_data_loss flag is set. dest is CPU accessible memory. It could be malloc'ed memory or host allocated memory

Parameters
[in]preferred_agentAgent on which to set the dest buffer
[in]size_in_bytessize of the buffer
[in/out]timeout timeout in milliseconds
[out]size_copiednumber of bytes copied
[in]destdestination address. Set to NULL to stop copy on previous buffer
[out]is_data_losstrue is data was lost

◆ hsa_amd_svm_attributes_get()

hsa_status_t hsa_amd_svm_attributes_get ( void *  ptr,
size_t  size,
hsa_amd_svm_attribute_pair_t attribute_list,
size_t  attribute_count 
)

Gets SVM memory attributes.

Attributes HSA_AMD_SVM_ATTRIB_AGENT_ACCESSIBLE, HSA_AMD_SVM_ATTRIB_AGENT_ACCESSIBLE_IN_PLACE and HSA_AMD_SVM_ATTRIB_PREFETCH_LOCATION may not be used with this API.

Note that attribute HSA_AMD_SVM_ATTRIB_ACCESS_QUERY takes as input an hsa_agent_t and returns the current access type through its attribute field.

Parameters
[in]ptrWill be aligned down to nearest page boundary.
[in]sizeWill be aligned up to nearest page boundary.
[in]attribute_listList of attributes to set for the address range.
[in]attribute_countLength of attribute_list.

◆ hsa_amd_svm_attributes_set()

hsa_status_t hsa_amd_svm_attributes_set ( void *  ptr,
size_t  size,
hsa_amd_svm_attribute_pair_t attribute_list,
size_t  attribute_count 
)

Sets SVM memory attributes.

If HSA_AMD_SYSTEM_INFO_SVM_ACCESSIBLE_BY_DEFAULT returns false then enabling access to an Agent via this API (setting HSA_AMD_SVM_ATTRIB_AGENT_ACCESSIBLE or HSA_AMD_SVM_ATTRIB_AGENT_ACCESSIBLE_IN_PLACE) is required prior to SVM memory access by that Agent.

Attributes HSA_AMD_SVM_ATTRIB_ACCESS_QUERY and HSA_AMD_SVM_ATTRIB_PREFETCH_LOCATION may not be used with this API.

Parameters
[in]ptrWill be aligned down to nearest page boundary.
[in]sizeWill be aligned up to nearest page boundary.
[in]attribute_listList of attributes to set for the address range.
[in]attribute_countLength of attribute_list.

◆ hsa_amd_svm_prefetch_async()

hsa_status_t hsa_amd_svm_prefetch_async ( void *  ptr,
size_t  size,
hsa_agent_t  agent,
uint32_t  num_dep_signals,
const hsa_signal_t *  dep_signals,
hsa_signal_t  completion_signal 
)

Asynchronously migrates memory to an agent.

Schedules memory migration to agent when dep_signals have been observed equal to zero. completion_signal will decrement when the migration is complete.

Parameters
[in]ptrWill be aligned down to nearest page boundary.
[in]sizeWill be aligned up to nearest page boundary.
[in]agentAgent to migrate to.
[in]num_dep_signalsNumber of dependent signals. Can be 0.
[in]dep_signalsList of signals that must be waited on before the migration operation starts. The migration will start after every signal has been observed with the value 0. If num_dep_signals is 0, this argument is ignored.
[in]completion_signalSignal used to indicate completion of the migration operation. When the migration operation is finished, the value of the signal is decremented. The runtime indicates that an error has occurred during the copy operation by setting the value of the completion signal to a negative number. If no completion signal is required this handle may be null.

◆ hsa_amd_vmem_address_free()

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
[out]vavirtual address to be freed
[in]sizeof address range
Return values
::HSA_STATUS_SUCCESSAddress range released successfully
::HSA_STATUS_ERROR_INVALID_ALLOCATIONInvalid va specified
::HSA_STATUS_ERROR_INVALID_ARGUMENTInvalid size specified
::HSA_STATUS_ERROR_RESOURCE_FREEAddress range is still in use
::HSA_STATUS_ERRORInternal unexpected error

◆ hsa_amd_vmem_address_reserve()

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.

Parameters
[out]vavirtual address allocated
[in]sizeof address range requested
[in]addressrequested
[in]flagscurrently unsupported
Return values
::HSA_STATUS_SUCCESSAddress range allocated successfully
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_OUT_OF_RESOURCESInsufficient resources to allocate an address range of this size.

Note that this API will be deprecated in a future release and replaced by hsa_amd_vmem_address_reserve_align

◆ hsa_amd_vmem_address_reserve_align()

hsa_status_t hsa_amd_vmem_address_reserve_align ( void **  va,
size_t  size,
uint64_t  address,
uint64_t  alignment,
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.

Parameters
[out]vavirtual address allocated
[in]sizeof address range requested
[in]addressrequested
[in]alignmentrequested. 0 for default. Must be >= page-size and a power of 2
[in]flagscurrently unsupported
Return values
::HSA_STATUS_SUCCESSAddress range allocated successfully
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_OUT_OF_RESOURCESInsufficient resources to allocate an address range of this size.

◆ hsa_amd_vmem_export_shareable_handle()

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
[out]dmabuf_fdshareable handle
[in]handlepreviously allocated virtual memory handle
[in]flagsCurrently unsupported
Return values
::HSA_STATUS_SUCCESS
::HSA_STATUS_ERROR_INVALID_ALLOCATIONInvalid memory handle
::HSA_STATUS_ERROR_OUT_OF_RESOURCESOut of resources
::HSA_STATUS_ERRORUnexpected internal error

◆ hsa_amd_vmem_get_access()

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
[in]vapreviously mapped virtual address
[in]permscurrent permissions
[in]agent_handleagent
Return values
::HSA_STATUS_SUCCESS
::HSA_STATUS_ERROR_INVALID_AGENTInvalid agent
::HSA_STATUS_ERROR_INVALID_ALLOCATIONva is not mapped or permissions never set for this agent
::HSA_STATUS_ERRORUnexpected internal error

◆ hsa_amd_vmem_get_alloc_properties_from_handle()

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
[in]memory_handlememory handle to be queried
[out]poolmemory pool that owns this handle
[out]memorytype
Return values
::HSA_STATUS_SUCCESS
::HSA_STATUS_ERROR_INVALID_ALLOCATIONInvalid memory_handle

◆ hsa_amd_vmem_handle_create()

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
[in]poolmemory to use
[in]sizeof the memory allocation
[in]typeof memory
[in]flags- currently unsupported
[out]memory_handle- handle for the allocation
Return values
::HSA_STATUS_SUCCESSmemory allocated successfully
::HSA_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
::HSA_STATUS_ERROR_INVALID_ARGUMENTInvalid arguments
::HSA_STATUS_ERROR_INVALID_ALLOCATIONThis memory pool does not support allocations
::HSA_STATUS_ERROR_OUT_OF_RESOURCESInsufficient resources to allocate this memory

◆ hsa_amd_vmem_handle_release()

hsa_status_t hsa_amd_vmem_handle_release ( hsa_amd_vmem_alloc_handle_t  memory_handle)

Release a virtual memory handle.

Parameters
[in]memoryhandle that was previously allocated
Return values
::HSA_STATUS_SUCCESSAddress range allocated successfully
::HSA_STATUS_ERROR_INVALID_ALLOCATIONInvalid memory handle

◆ hsa_amd_vmem_import_shareable_handle()

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
[in]dmabuf_fdshareable handle exported with hsa_amd_vmem_export_shareable_handle
[out]handlevirtual memory handle
Return values
::HSA_STATUS_SUCCESS
::HSA_STATUS_ERROR_INVALID_ALLOCATIONInvalid memory handle
::HSA_STATUS_ERROR_OUT_OF_RESOURCESOut of resources
::HSA_STATUS_ERRORUnexpected internal error

◆ hsa_amd_vmem_map()

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
[in]vavirtual address range where memory will be mapped
[in]sizeof memory mapping
[in]in_offsetoffset into memory. Currently unsupported
[in]memory_handlevirtual memory handle to be mapped
[in]flags.Currently unsupported
Return values
::HSA_STATUS_SUCCESSMemory mapped successfully
::HSA_STATUS_ERROR_INVALID_ARGUMENTva, size or memory_handle are invalid
::HSA_STATUS_ERROR_OUT_OF_RESOURCESInsufficient resources
::HSA_STATUS_ERRORUnexpected internal error

◆ hsa_amd_vmem_retain_alloc_handle()

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
[out]memory_handlememory handle for this mapped address
[in]mappedaddress
Return values
::HSA_STATUS_SUCCESS
::HSA_STATUS_ERROR_INVALID_ALLOCATIONInvalid address

◆ hsa_amd_vmem_set_access()

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
[in]vapreviously mapped virtual address
[in]sizeof memory mapping
[in]desclist of access permissions for each agent
[in]desc_cntnumber of elements in desc
Return values
::HSA_STATUS_SUCCESS
::HSA_STATUS_ERROR_INVALID_ARGUMENTva, size or memory_handle are invalid
::HSA_STATUS_ERROR_INVALID_ALLOCATIONmemory_handle is invalid
::HSA_STATUS_ERROR_OUT_OF_RESOURCESInsufficient resources
::HSA_STATUS_ERROR_INVALID_AGENTInvalid agent in desc
::HSA_STATUS_ERRORUnexpected internal error

◆ hsa_amd_vmem_unmap()

hsa_status_t hsa_amd_vmem_unmap ( void *  va,
size_t  size 
)

Unmap a virtual memory handle.

Unmap previously mapped virtual address range

Parameters
[in]vavirtual address range where memory will be mapped
[in]sizeof memory mapping
Return values
::HSA_STATUS_SUCCESSMemory backing unmapped successfully
::HSA_STATUS_ERROR_INVALID_ALLOCATIONmemory_handle is invalid
::HSA_STATUS_ERROR_INVALID_ARGUMENTsize is invalid
::HSA_STATUS_ERRORUnexpected internal error