gem5  v21.1.0.2
Classes | Typedefs | Enumerations | Functions | Variables
Memory

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 gem5::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

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 3184 of file hsa.h.

◆ 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 3210 of file hsa.h.

◆ 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 3155 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]agentA valid agent.
[in]callbackCallback 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]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_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]regionRegion where to allocate memory from. The region must have the HSA_REGION_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_REGION_INFO_RUNTIME_ALLOC_GRANULE in region.
[out]ptrPointer 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_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_REGIONThe region is invalid.
HSA_STATUS_ERROR_INVALID_ALLOCATIONThe 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_ARGUMENTptr 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]ptrBase 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]agentAgent 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]accessAccess permissions requested for the new owner.
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_OUT_OF_RESOURCESThe HSA runtime failed to allocate the required resources.
HSA_STATUS_ERROR_INVALID_ARGUMENTptr 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]dstBuffer 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]srcA 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]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.
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_ARGUMENTThe 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]ptrA pointer to the base of the buffer to be deregistered. If a NULL pointer is passed, no operation is performed.
[in]sizeSize of the buffer to be deregistered.
Return values
HSA_STATUS_SUCCESSThe function has been executed successfully.
HSA_STATUS_ERROR_NOT_INITIALIZEDThe 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]ptrPointer 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_SUCCESSThe function has been executed successfully.
HSA_STATUS_ERROR_NOT_INITIALIZEDThe 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]ptrA 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]sizeRequested registration size in bytes. A size of 0 is only allowed if ptr is 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_ARGUMENTsize 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]regionA valid region.
[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_STATUS_ERROR_NOT_INITIALIZEDThe HSA runtime has not been initialized.
HSA_STATUS_ERROR_INVALID_REGIONThe region is invalid.
HSA_STATUS_ERROR_INVALID_ARGUMENTattribute is an invalid region attribute, or value is NULL.

Variable Documentation

◆ mem_valid

bool gem5::Trace::InstRecord::mem_valid
protected

Are the memory fields in the record valid?

Definition at line 135 of file insttracer.hh.

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


Generated on Tue Sep 21 2021 12:27:00 for gem5 by doxygen 1.8.17