Classes
struct	hsa_region_s
	A memory region represents a block of virtual memory with certain properties. More...

Typedefs
typedef struct hsa_region_s	hsa_region_t
	A memory region represents a block of virtual memory with certain properties. More...

Enumerations
enum	hsa_region_segment_t { HSA_REGION_SEGMENT_GLOBAL = 0, HSA_REGION_SEGMENT_READONLY = 1, HSA_REGION_SEGMENT_PRIVATE = 2, HSA_REGION_SEGMENT_GROUP = 3, HSA_REGION_SEGMENT_KERNARG = 4 }
	Memory segments associated with a region. More...

enum	hsa_region_global_flag_t { HSA_REGION_GLOBAL_FLAG_KERNARG = 1, HSA_REGION_GLOBAL_FLAG_FINE_GRAINED = 2, HSA_REGION_GLOBAL_FLAG_COARSE_GRAINED = 4 }
	Global region flags. More...

enum	hsa_region_info_t { HSA_REGION_INFO_SEGMENT = 0, HSA_REGION_INFO_GLOBAL_FLAGS = 1, HSA_REGION_INFO_SIZE = 2, HSA_REGION_INFO_ALLOC_MAX_SIZE = 4, HSA_REGION_INFO_ALLOC_MAX_PRIVATE_WORKGROUP_SIZE = 8, HSA_REGION_INFO_RUNTIME_ALLOC_ALLOWED = 5, HSA_REGION_INFO_RUNTIME_ALLOC_GRANULE = 6, HSA_REGION_INFO_RUNTIME_ALLOC_ALIGNMENT = 7 }
	Attributes of a memory region. More...

Functions
hsa_status_t HSA_API	hsa_region_get_info (hsa_region_t region, hsa_region_info_t attribute, void *value)
	Get the current value of an attribute of a region. More...

hsa_status_t HSA_API	hsa_agent_iterate_regions (hsa_agent_t agent, hsa_status_t(callback)(hsa_region_t region, void data), void *data)
	Iterate over the memory regions associated with a given agent, and invoke an application-defined callback on every iteration. More...

hsa_status_t HSA_API	hsa_memory_allocate (hsa_region_t region, size_t size, void **ptr)
	Allocate a block of memory in a given region. More...

hsa_status_t HSA_API	hsa_memory_free (void *ptr)
	Deallocate a block of memory previously allocated using hsa_memory_allocate. More...

hsa_status_t HSA_API	hsa_memory_copy (void dst, const void src, size_t size)
	Copy a block of memory from the location pointed to by `src` to the memory block pointed to by `dst`. More...

hsa_status_t HSA_API	hsa_memory_assign_agent (void *ptr, hsa_agent_t agent, hsa_access_permission_t access)
	Change the ownership of a global, coarse-grained buffer. More...

hsa_status_t HSA_API	hsa_memory_register (void *ptr, size_t size)
	Register a global, fine-grained buffer. More...

hsa_status_t HSA_API	hsa_memory_deregister (void *ptr, size_t size)
	Deregister memory previously registered using hsa_memory_register. More...

Variables
bool	Trace::InstRecord::mem_valid

Detailed Description

Typedef Documentation

◆ hsa_region_t

typedef struct hsa_region_s hsa_region_t

A memory region represents a block of virtual memory with certain properties.

For example, the HSA runtime represents fine-grained memory in the global segment using a region. A region might be associated with more than one agent.

Enumeration Type Documentation

◆ hsa_region_global_flag_t

enum hsa_region_global_flag_t

Global region flags.

Enumerator

HSA_REGION_GLOBAL_FLAG_KERNARG

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

If this flag is set, then HSA_REGION_GLOBAL_FLAG_FINE_GRAINED must be set.

HSA_REGION_GLOBAL_FLAG_FINE_GRAINED

Updates to memory in this region are immediately visible to all the agents under the terms of the HSA memory model.

If this flag is set, then HSA_REGION_GLOBAL_FLAG_COARSE_GRAINED must not be set.

HSA_REGION_GLOBAL_FLAG_COARSE_GRAINED

Updates to memory in this region can be performed by a single agent at a time.

If a different agent in the system is allowed to access the region, the application must explicitely invoke hsa_memory_assign_agent in order to transfer ownership to that agent for a particular buffer.

Definition at line 3146 of file hsa.h.

◆ hsa_region_info_t

enum hsa_region_info_t

Attributes of a memory region.

Enumerator
HSA_REGION_INFO_SEGMENT	Segment where memory in the region can be used. The type of this attribute is hsa_region_segment_t.
HSA_REGION_INFO_GLOBAL_FLAGS	Flag mask. The value of this attribute is undefined if the value of HSA_REGION_INFO_SEGMENT is not HSA_REGION_SEGMENT_GLOBAL. The type of this attribute is uint32_t, a bit-field of hsa_region_global_flag_t values.
HSA_REGION_INFO_SIZE	Size of this region, in bytes. The type of this attribute is size_t.
HSA_REGION_INFO_ALLOC_MAX_SIZE	Maximum allocation size in this region, in bytes. Must not exceed the value of HSA_REGION_INFO_SIZE. The type of this attribute is size_t. If the region is in the global or readonly segments, this is the maximum size that the application can pass to hsa_memory_allocate. If the region is in the group segment, this is the maximum size (per work-group) that can be requested for a given kernel dispatch. If the region is in the private segment, this is the maximum size (per work-item) that can be requested for a specific kernel dispatch, and must be at least 256 bytes.
HSA_REGION_INFO_ALLOC_MAX_PRIVATE_WORKGROUP_SIZE	Maximum size (per work-group) of private memory that can be requested for a specific kernel dispatch. Must be at least 65536 bytes. The type of this attribute is uint32_t. The value of this attribute is undefined if the region is not in the private segment.
HSA_REGION_INFO_RUNTIME_ALLOC_ALLOWED	Indicates whether memory in this region can be allocated using hsa_memory_allocate. The type of this attribute is bool. The value of this flag is always false for regions in the group and private segments.
HSA_REGION_INFO_RUNTIME_ALLOC_GRANULE	Allocation granularity of buffers allocated by hsa_memory_allocate in this region. The size of a buffer allocated in this region is a multiple of the value of this attribute. The value of this attribute is only defined if HSA_REGION_INFO_RUNTIME_ALLOC_ALLOWED is true for this region. The type of this attribute is size_t.
HSA_REGION_INFO_RUNTIME_ALLOC_ALIGNMENT	Alignment of buffers allocated by hsa_memory_allocate in this region. The value of this attribute is only defined if HSA_REGION_INFO_RUNTIME_ALLOC_ALLOWED is true for this region, and must be a power of 2. The type of this attribute is size_t.

Definition at line 3171 of file hsa.h.

◆ hsa_region_segment_t

enum hsa_region_segment_t

Memory segments associated with a region.

Enumerator
HSA_REGION_SEGMENT_GLOBAL	Global segment. Used to hold data that is shared by all agents.
HSA_REGION_SEGMENT_READONLY	Read-only segment. Used to hold data that remains constant during the execution of a kernel.
HSA_REGION_SEGMENT_PRIVATE	Private segment. Used to hold data that is local to a single work-item.
HSA_REGION_SEGMENT_GROUP	Group segment. Used to hold data that is shared by the work-items of a work-group.
HSA_REGION_SEGMENT_KERNARG	Kernarg segment. Used to store kernel arguments.

Definition at line 3118 of file hsa.h.

Function Documentation

◆ hsa_agent_iterate_regions()

hsa_status_t HSA_API hsa_agent_iterate_regions	(	hsa_agent_t	agent,
		hsa_status_t()(hsa_region_t region, void data)	callback,
		void *	data
	)

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

Parameters

[in]	agent	A valid agent.
[in]	callback	Callback to be invoked once per region that is accessible from the agent. The HSA runtime passes two arguments to the callback, the region and the application data. If `callback` returns a status other than HSA_STATUS_SUCCESS for a particular iteration, the traversal stops and hsa_agent_iterate_regions returns that status value.
[in]	data	Application data that is passed to `callback` on every iteration. May be NULL.

Return values

HSA_STATUS_SUCCESS	The function has been executed successfully.
HSA_STATUS_ERROR_NOT_INITIALIZED	The HSA runtime has not been initialized.
HSA_STATUS_ERROR_INVALID_AGENT	The agent is invalid.
HSA_STATUS_ERROR_INVALID_ARGUMENT	`callback` is NULL.

◆ hsa_memory_allocate()

hsa_status_t HSA_API hsa_memory_allocate	(	hsa_region_t	region,
		size_t	size,
		void **	ptr
	)

Allocate a block of memory in a given region.

Parameters

[in]	region	Region where to allocate memory from. The region must have the HSA_REGION_INFO_RUNTIME_ALLOC_ALLOWED flag set.
[in]	size	Allocation size, in bytes. Must not be zero. This value is rounded up to the nearest multiple of HSA_REGION_INFO_RUNTIME_ALLOC_GRANULE in `region`.
[out]	ptr	Pointer to the location where to store the base address of the allocated block. The returned base address is aligned to the value of HSA_REGION_INFO_RUNTIME_ALLOC_ALIGNMENT in `region`. If the allocation fails, the returned value is undefined.

Return values

HSA_STATUS_SUCCESS	The function has been executed successfully.
HSA_STATUS_ERROR_NOT_INITIALIZED	The HSA runtime has not been initialized.
HSA_STATUS_ERROR_OUT_OF_RESOURCES	The HSA runtime failed to allocate the required resources.
HSA_STATUS_ERROR_INVALID_REGION	The region is invalid.
HSA_STATUS_ERROR_INVALID_ALLOCATION	The host is not allowed to allocate memory in `region`, or `size` is greater than the value of HSA_REGION_INFO_ALLOC_MAX_SIZE in `region`.
HSA_STATUS_ERROR_INVALID_ARGUMENT	`ptr` is NULL, or `size` is 0.

◆ hsa_memory_assign_agent()

hsa_status_t HSA_API hsa_memory_assign_agent	(	void *	ptr,
		hsa_agent_t	agent,
		hsa_access_permission_t	access
	)

Change the ownership of a global, coarse-grained buffer.

The contents of a coarse-grained buffer are visible to an agent only after ownership has been explicitely transferred to that agent. Once the operation completes, the previous owner cannot longer access the data in the buffer.

An implementation of the HSA runtime is allowed, but not required, to change the physical location of the buffer when ownership is transferred to a different agent. In general the application must not assume this behavior. The virtual location (address) of the passed buffer is never modified.

Parameters

[in]	ptr	Base address of a global buffer. The pointer must match an address previously returned by hsa_memory_allocate. The size of the buffer affected by the ownership change is identical to the size of that previous allocation. If `ptr` points to a fine-grained global buffer, no operation is performed and the function returns success. If `ptr` does not point to global memory, the behavior is undefined.
[in]	agent	Agent that becomes the owner of the buffer. The application is responsible for ensuring that `agent` has access to the region that contains the buffer. It is allowed to change ownership to an agent that is already the owner of the buffer, with the same or different access permissions.
[in]	access	Access permissions requested for the new owner.

Return values

HSA_STATUS_SUCCESS	The function has been executed successfully.
HSA_STATUS_ERROR_NOT_INITIALIZED	The HSA runtime has not been initialized.
HSA_STATUS_ERROR_INVALID_AGENT	The agent is invalid.
HSA_STATUS_ERROR_OUT_OF_RESOURCES	The HSA runtime failed to allocate the required resources.
HSA_STATUS_ERROR_INVALID_ARGUMENT	`ptr` is NULL, or `access` is not a valid access value.

◆ hsa_memory_copy()

hsa_status_t HSA_API hsa_memory_copy	(	void *	dst,
		const void *	src,
		size_t	size
	)

Copy a block of memory from the location pointed to by src to the memory block pointed to by dst.

Parameters

[out]	dst	Buffer where the content is to be copied. If `dst` is in coarse-grained memory, the copied data is only visible to the agent currently assigned (hsa_memory_assign_agent) to `dst`.
[in]	src	A valid pointer to the source of data to be copied. The source buffer must not overlap with the destination buffer. If the source buffer is in coarse-grained memory then it must be assigned to an agent, from which the data will be retrieved.
[in]	size	Number 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.

Return values

HSA_STATUS_SUCCESS	The function has been executed successfully.
HSA_STATUS_ERROR_NOT_INITIALIZED	The HSA runtime has not been initialized.
HSA_STATUS_ERROR_INVALID_ARGUMENT	The source or destination pointers are NULL.

◆ hsa_memory_deregister()

hsa_status_t HSA_API hsa_memory_deregister	(	void *	ptr,
		size_t	size
	)

Deregister memory previously registered using hsa_memory_register.

If the memory interval being deregistered does not match a previous registration (start and end addresses), the behavior is undefined.

Parameters

[in]	ptr	A pointer to the base of the buffer to be deregistered. If a NULL pointer is passed, no operation is performed.
[in]	size	Size of the buffer to be deregistered.

Return values

HSA_STATUS_SUCCESS	The function has been executed successfully.
HSA_STATUS_ERROR_NOT_INITIALIZED	The HSA runtime has not been initialized.

◆ hsa_memory_free()

hsa_status_t HSA_API hsa_memory_free ( void * ptr )

Deallocate a block of memory previously allocated using hsa_memory_allocate.

Parameters

[in] ptr Pointer to a memory block. If ptr does not match a value previously returned by hsa_memory_allocate, the behavior is undefined.

Return values

HSA_STATUS_SUCCESS	The function has been executed successfully.
HSA_STATUS_ERROR_NOT_INITIALIZED	The HSA runtime has not been initialized.

◆ hsa_memory_register()

hsa_status_t HSA_API hsa_memory_register	(	void *	ptr,
		size_t	size
	)

Register a global, fine-grained buffer.

Registering a buffer serves as an indication to the HSA runtime that the memory might be accessed from a kernel agent other than the host. Registration is a performance hint that allows the HSA runtime implementation to know which buffers will be accessed by some of the kernel agents ahead of time.

Registration is only recommended for buffers in the global segment that have not been allocated using the HSA allocator (hsa_memory_allocate), but an OS allocator instead. Registering an OS-allocated buffer in the base profile is equivalent to a no-op.

Registrations should not overlap.

Parameters

[in]	ptr	A buffer in global, fine-grained memory. If a NULL pointer is passed, no operation is performed. If the buffer has been allocated using hsa_memory_allocate, or has already been registered, no operation is performed.
[in]	size	Requested registration size in bytes. A size of 0 is only allowed if `ptr` is NULL.

Return values

HSA_STATUS_SUCCESS	The function has been executed successfully.
HSA_STATUS_ERROR_NOT_INITIALIZED	The HSA runtime has not been initialized.
HSA_STATUS_ERROR_OUT_OF_RESOURCES	The HSA runtime failed to allocate the required resources.
HSA_STATUS_ERROR_INVALID_ARGUMENT	`size` is 0 but `ptr` is not NULL.

◆ hsa_region_get_info()

hsa_status_t HSA_API hsa_region_get_info	(	hsa_region_t	region,
		hsa_region_info_t	attribute,
		void *	value
	)

Get the current value of an attribute of a region.

Parameters

[in]	region	A valid region.
[in]	attribute	Attribute to query.
[out]	value	Pointer 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_SUCCESS	The function has been executed successfully.
HSA_STATUS_ERROR_NOT_INITIALIZED	The HSA runtime has not been initialized.
HSA_STATUS_ERROR_INVALID_REGION	The region is invalid.
HSA_STATUS_ERROR_INVALID_ARGUMENT	`attribute` is an invalid region attribute, or `value` is NULL.

Variable Documentation

◆ mem_valid

bool Trace::InstRecord::mem_valid

protected

Are the memory fields in the record valid?

Definition at line 131 of file insttracer.hh.

Referenced by Trace::InstRecord::getMemValid(), and Trace::InstRecord::setMem().

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ hsa_region_t

Enumeration Type Documentation

◆ hsa_region_global_flag_t

◆ hsa_region_info_t

◆ hsa_region_segment_t

Function Documentation

◆ hsa_agent_iterate_regions()

◆ hsa_memory_allocate()

◆ hsa_memory_assign_agent()

◆ hsa_memory_copy()

◆ hsa_memory_deregister()

◆ hsa_memory_free()

◆ hsa_memory_register()

◆ hsa_region_get_info()

Variable Documentation

◆ mem_valid