Memory#
Operations related to AMD GPU memory access. More...
Data Structures | |
struct | amd_dbgapi_address_class_id_t |
Opaque source language address class handle. More... | |
struct | amd_dbgapi_address_space_id_t |
Opaque address space handle. More... | |
Macros | |
#define | AMD_DBGAPI_LANE_NONE ((amd_dbgapi_lane_id_t) (-1)) |
The NULL lane handle. More... | |
#define | AMD_DBGAPI_ADDRESS_CLASS_NONE AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_address_class_id_t, 0) |
The NULL address class handle. More... | |
#define | AMD_DBGAPI_ADDRESS_SPACE_NONE AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_address_space_id_t, 0) |
The NULL address space handle. More... | |
#define | AMD_DBGAPI_ADDRESS_SPACE_GLOBAL AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_address_space_id_t, 1) |
The global address space handle. More... | |
Typedefs | |
typedef uint32_t | amd_dbgapi_lane_id_t |
A wave lane handle. More... | |
typedef uint64_t | amd_dbgapi_segment_address_t |
Each address space has its own linear address to access it termed a segment address. More... | |
Detailed Description
Operations related to AMD GPU memory access.
The AMD GPU supports allocating memory in different address spaces. See User Guide for AMDGPU Backend - LLVM - Address Spaces.
Macro Definition Documentation
◆ AMD_DBGAPI_ADDRESS_CLASS_NONE
#define AMD_DBGAPI_ADDRESS_CLASS_NONE AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_address_class_id_t, 0) |
The NULL address class handle.
◆ AMD_DBGAPI_ADDRESS_SPACE_GLOBAL
#define AMD_DBGAPI_ADDRESS_SPACE_GLOBAL AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_address_space_id_t, 1) |
The global address space handle.
Every architecture supports a global address space that uses the same address space ID.
◆ AMD_DBGAPI_ADDRESS_SPACE_NONE
#define AMD_DBGAPI_ADDRESS_SPACE_NONE AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_address_space_id_t, 0) |
The NULL address space handle.
◆ AMD_DBGAPI_LANE_NONE
#define AMD_DBGAPI_LANE_NONE ((amd_dbgapi_lane_id_t) (-1)) |
The NULL lane handle.
Typedef Documentation
◆ amd_dbgapi_lane_id_t
typedef uint32_t amd_dbgapi_lane_id_t |
A wave lane handle.
A wave can have one or more lanes controlled by an execution mask. Vector instructions will be performed for each lane of the wave that the execution mask has enabled. Vector instructions can access registers that are vector registers. A vector register has a separate value for each lane, and vector instructions will access the corresponding component for each lane's evaluation of the instruction.
The number of lanes of a wave can be obtained with the AMD_DBGAPI_WAVE_INFO_LANE_COUNT query. Different waves of the same architecture can have different lane counts.
The AMD GPU compiler may map source language threads of execution to lanes of a wave. The DWARF debug information which maps such source languages to the generated architecture specific code must include information about the lane mapping.
The DW_ASPACE_AMDGPU_private_lane
DWARF address space supports memory allocated independently for each lane of a wave.
Lanes are numbered from 0 to AMD_DBGAPI_WAVE_INFO_LANE_COUNT minus 1.
Only unique for a single wave of a single process.
◆ amd_dbgapi_segment_address_t
typedef uint64_t amd_dbgapi_segment_address_t |
Each address space has its own linear address to access it termed a segment address.
Different address spaces may have memory locations that alias each other, but the segment address for such memory locations may be different in each address space. Consequently a segment address is specific to an address space.
Some address spaces may access memory that is allocated independently for each workgroup, for each wave, or for each lane of of a wave. Consequently a segment address may be specific to a wave or lane of a wave.
Enumeration Type Documentation
◆ amd_dbgapi_address_class_info_t
Source language address class queries that are supported by amd_dbgapi_address_class_get_info.
Each query specifies the type of data returned in the value
argument to amd_dbgapi_address_class_get_info.
Enumerator | |
---|---|
AMD_DBGAPI_ADDRESS_CLASS_INFO_NAME | Return the source language address class name. The type of this attribute is a pointer to a NUL terminated |
AMD_DBGAPI_ADDRESS_CLASS_INFO_ADDRESS_SPACE | Return the architecture specific address space that is used to implement a pointer or reference to the source language address class. The type of this attribute is amd_dbgapi_address_class_id_t. See User Guide for AMDGPU Backend - Code Object - DWARF - Address Class Mapping. |
AMD_DBGAPI_ADDRESS_CLASS_INFO_DWARF | Return the AMD GPU DWARF address class number for the address class' architecture. The type of this attribute is |
◆ amd_dbgapi_address_class_state_t
Indication of whether a segment address in an address space is a member of an source language address class.
◆ amd_dbgapi_address_space_access_t
Indication of how the address space is accessed.
◆ amd_dbgapi_address_space_info_t
Address space queries that are supported by amd_dbgapi_address_space_get_info.
Each query specifies the type of data returned in the value
argument to amd_dbgapi_address_space_get_info.
Enumerator | |
---|---|
AMD_DBGAPI_ADDRESS_SPACE_INFO_NAME | Return the address space name. The type of this attribute is a pointer to a NUL terminated |
AMD_DBGAPI_ADDRESS_SPACE_INFO_ADDRESS_SIZE | Return the byte size of an address in the address space. The type of this attribute is amd_dbgapi_size_t. |
AMD_DBGAPI_ADDRESS_SPACE_INFO_NULL_ADDRESS | Return the NULL segment address value in the address space. The type of this attribute is |
AMD_DBGAPI_ADDRESS_SPACE_INFO_ACCESS | Return the address space access. The type of this attribute is |
AMD_DBGAPI_ADDRESS_SPACE_INFO_DWARF | Return the AMD GPU DWARF address space number for the address space's architecture. The type of this attribute is |
◆ amd_dbgapi_memory_precision_t
Memory access precision.
The AMD GPU can overlap the execution of memory instructions with other instructions. This can result in a wave stopping due to a memory violation or hardware data watchpoint hit with a program counter beyond the instruction that caused the wave to stop.
Some architectures allow the hardware to be configured to always wait for memory operations to complete before continuing. This will result in the wave stopping at the instruction immediately after the one that caused the stop event. Enabling this mode can make execution of waves significantly slower.
The AMD_DBGAPI_PROCESS_INFO_PRECISE_MEMORY_SUPPORTED query can be used to determine if the architectures of all the agents of a process support controlling precise memory accesses.
◆ amd_dbgapi_segment_address_dependency_t
The dependency when reading or writing a specific segment address of an address space using the amd_dbgapi_read_memory and amd_dbgapi_write_memory operations.
Function Documentation
◆ amd_dbgapi_address_class_get_info()
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_address_class_get_info | ( | amd_dbgapi_address_class_id_t | address_class_id, |
amd_dbgapi_address_class_info_t | query, | ||
size_t | value_size, | ||
void * | value | ||
) |
Query information about a source language address class of an architecture.
amd_dbgapi_address_class_info_t specifies the queries supported and the type returned using the value
argument.
- Parameters
-
[in] address_class_id The handle of the source language address class being queried. [in] query The query being requested. [in] value_size Size of the memory pointed to by value
. Must be equal to the byte size of the query result.[out] value Pointer to memory where the query result is stored.
- Return values
-
AMD_DBGAPI_STATUS_SUCCESS The function has been executed successfully and the result is stored in value
.AMD_DBGAPI_STATUS_FATAL A fatal error occurred. The library is left uninitialized and value
is unaltered.AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED The library is not initialized. The library is left uninitialized and value
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_CLASS_ID address_class_id
is invalid.value
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT value
is NULL orquery
is invalid.value
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY value_size
does not match the size of thequery
result.value
is unaltered.AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACK This will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate value
returns NULL.value
is unaltered.
◆ amd_dbgapi_address_dependency()
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_address_dependency | ( | amd_dbgapi_address_space_id_t | address_space_id, |
amd_dbgapi_segment_address_t | segment_address, | ||
amd_dbgapi_segment_address_dependency_t * | segment_address_dependency | ||
) |
Determine the dependency of a segment address value in a particular address space.
This indicates which arguments amd_dbgapi_read_memory and amd_dbgapi_write_memory require when reading and writing memory when given a specific segment address in an address space.
- Parameters
-
[in] address_space_id The address space of the segment_address
.[in] segment_address The integral value of the segment address. Only the bits corresponding to the address size for the address_space_id
requested are used. The address size is provided by the AMD_DBGAPI_ADDRESS_SPACE_INFO_ADDRESS_SIZE query.[out] segment_address_dependency The dependency of the segment_address
value inaddress_space_id
. Will be a value of amd_dbgapi_segment_address_dependency_t other than AMD_DBGAPI_SEGMENT_ADDRESS_DEPENDENCE_NONE.
- Return values
-
AMD_DBGAPI_STATUS_SUCCESS The function has been executed successfully and the result is stored in segment_address_dependencies
.AMD_DBGAPI_STATUS_FATAL A fatal error occurred. The library is left uninitialized and segment_address_dependencies
is unaltered.AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED The library is not initialized. The library is left uninitialized and destination_segment_address
andsegment_address_dependencies
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_SPACE_ID address_space_id
is invalid.segment_address_dependencies
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT segment_address_dependencies
is NULL.segment_address_dependencies
is unaltered.
◆ amd_dbgapi_address_is_in_address_class()
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_address_is_in_address_class | ( | amd_dbgapi_wave_id_t | wave_id, |
amd_dbgapi_lane_id_t | lane_id, | ||
amd_dbgapi_address_space_id_t | address_space_id, | ||
amd_dbgapi_segment_address_t | segment_address, | ||
amd_dbgapi_address_class_id_t | address_class_id, | ||
amd_dbgapi_address_class_state_t * | address_class_state | ||
) |
Determine if a segment address in an address space is a member of a source language address class.
The address space and source language address class must both belong to the same architecture.
The address space, source language address class, and wave must all belong to the same architecture.
- Parameters
-
[in] wave_id The wave that is using the address. If the address_space
is AMD_DBGAPI_ADDRESS_SPACE_GLOBAL thenwave_id
may be AMD_DBGAPI_WAVE_NONE, as the address space does not depend on the active wave, in which caseprocess_id
is used.[in] lane_id The lane of the wave_id
that is using the address. If theaddress_space
does not depend on the active lane then this may be AMD_DBGAPI_LANE_NONE. For example, the AMD_DBGAPI_ADDRESS_SPACE_GLOBAL address space does not depend on the lane.[in] address_space_id The address space of the segment_address
. If the address space is dependent on: the active lane then thelane_id
with in thewave_id
is used; the active workgroup then the workgroup ofwave_id
is used; or the active wave then thewave_id
is used.[in] segment_address The integral value of the segment address. Only the bits corresponding to the address size for the address_space
requested are used. The address size is provided by the AMD_DBGAPI_ADDRESS_SPACE_INFO_ADDRESS_SIZE query.[in] address_class_id The handle of the source language address class. [out] address_class_state AMD_DBGAPI_ADDRESS_CLASS_STATE_NOT_MEMBER if the address is not in the address class. AMD_DBGAPI_ADDRESS_CLASS_STATE_MEMBER if the address is in the address class.
- Return values
-
AMD_DBGAPI_STATUS_SUCCESS The function has been executed successfully and the result is stored in address_class_state
.AMD_DBGAPI_STATUS_FATAL A fatal error occurred. The library is left uninitialized and address_class_state
is unaltered.AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED The library is not initialized. The library is left uninitialized and address_class_state
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_ID wave_id
is invalid, orwave_id
is AMD_DBGAPI_WAVE_NONE andaddress_space
is not AMD_DBGAPI_ADDRESS_SPACE_GLOBAL.address_class_state
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_LANE_ID wave_id
is AMD_DBGAPI_WAVE_NONE andlane_id
is not AMD_DBGAPI_LANE_NONE.wave_id
is not AMD_DBGAPI_WAVE_NONE andlane_id
is not AMD_DBGAPI_LANE_NONE and is not valid forwave_id
.lane_id
is AMD_DBGAPI_LANE_NONE andaddress_space_id
depends on the active lane.address_class_state
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_SPACE_ID address_space_id
is invalid.address_class_state
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_CLASS_ID address_class_id
is invalid.address_class_state
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT address_class_state
is NULL.address_class_state
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY The architectures of wave_id
,address_space_id
, andaddress_class_id
are not the same.address_class_state
is unaltered.
◆ amd_dbgapi_address_space_get_info()
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_address_space_get_info | ( | amd_dbgapi_address_space_id_t | address_space_id, |
amd_dbgapi_address_space_info_t | query, | ||
size_t | value_size, | ||
void * | value | ||
) |
Query information about an address space.
amd_dbgapi_address_space_info_t specifies the queries supported and the type returned using the value
argument.
- Parameters
-
[in] address_space_id The address space. [in] query The query being requested. [in] value_size Size of the memory pointed to by value
. Must be equal to the byte size of the query result.[out] value Pointer to memory where the query result is stored.
- Return values
-
AMD_DBGAPI_STATUS_SUCCESS The function has been executed successfully and the result is stored in value
.AMD_DBGAPI_STATUS_FATAL A fatal error occurred. The library is left uninitialized and value
is unaltered.AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED The library is not initialized. The library is left uninitialized and value
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_SPACE_ID address_space_id
is invalid.value
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT query
is invalid orvalue
is NULL.value
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY value_size
does not match the size of thequery
result.value
is unaltered.AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACK This will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate value
returns NULL.value
is unaltered.
◆ amd_dbgapi_architecture_address_class_list()
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_architecture_address_class_list | ( | amd_dbgapi_architecture_id_t | architecture_id, |
size_t * | address_class_count, | ||
amd_dbgapi_address_class_id_t ** | address_classes | ||
) |
Report the list of source language address classes supported by the architecture.
The order of the source language address class handles in the list is stable between calls.
- Parameters
-
[in] architecture_id The architecture being queried. [out] address_class_count The number of architecture source language address classes. [out] address_classes A pointer to an array of amd_dbgapi_address_class_id_t with address_class_count
elements. It is allocated by the amd_dbgapi_callbacks_s::allocate_memory callback and is owned by the client.
- Return values
-
AMD_DBGAPI_STATUS_SUCCESS The function has been executed successfully and the result is stored in address_class_count
andaddress_classes
.AMD_DBGAPI_STATUS_FATAL A fatal error occurred. The library is left uninitialized; and address_class_count
andaddress_classes
are unaltered.AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED The library is not initialized. The library is left uninitialized; and address_class_count
andaddress_classes
are unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_ID architecture_id
is invalid.address_class_count
andaddress_classes
are unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT address_class_count
oraddress_classes
are NULL.address_class_count
andaddress_classes
are unaltered.AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACK This will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate address_classes
returns NULL.address_class_count
andaddress_classes
are unaltered.
◆ amd_dbgapi_architecture_address_space_list()
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_architecture_address_space_list | ( | amd_dbgapi_architecture_id_t | architecture_id, |
size_t * | address_space_count, | ||
amd_dbgapi_address_space_id_t ** | address_spaces | ||
) |
Report the list of address spaces supported by the architecture.
The order of the address space handles in the list is stable between calls.
- Parameters
-
[in] architecture_id The architecture being queried. [out] address_space_count The number of architecture address spaces. [out] address_spaces A pointer to an array of amd_dbgapi_address_space_id_t with address_space_count
elements. It is allocated by the amd_dbgapi_callbacks_s::allocate_memory callback and is owned by the client.
- Return values
-
AMD_DBGAPI_STATUS_SUCCESS The function has been executed successfully and the result is stored in address_space_count
andaddress_spaces
.AMD_DBGAPI_STATUS_FATAL A fatal error occurred. The library is left uninitialized; and address_space_count
andaddress_spaces
are unaltered.AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED The library is not initialized. The library is left uninitialized; and address_space_count
andaddress_spaces
are unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_ID architecture_id
is invalid.address_space_count
andaddress_spaces
are unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT address_space_count
andaddress_spaces
are NULL.address_space_count
andaddress_spaces
are unaltered.AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACK This will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate address_spaces
returns NULL.address_space_count
andaddress_spaces
are unaltered.
◆ amd_dbgapi_convert_address_space()
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_convert_address_space | ( | amd_dbgapi_wave_id_t | wave_id, |
amd_dbgapi_lane_id_t | lane_id, | ||
amd_dbgapi_address_space_id_t | source_address_space_id, | ||
amd_dbgapi_segment_address_t | source_segment_address, | ||
amd_dbgapi_address_space_id_t | destination_address_space_id, | ||
amd_dbgapi_segment_address_t * | destination_segment_address, | ||
amd_dbgapi_size_t * | destination_contiguous_bytes | ||
) |
Convert a source segment address in the source address space into a destination segment address in the destination address space.
If the source segment address is the NULL value in the source address space then it is converted to the NULL value in the destination address space. The NULL address is provided by the AMD_DBGAPI_ADDRESS_SPACE_INFO_NULL_ADDRESS query.
An error is returned if the source segment address has no corresponding segment address in the destination address space.
The source and destination address spaces do not have to have the same linear ordering. For example, for AMD GPU the private_swizzled
address space is implemented as global
address space memory that interleaves the dwords of the wave's lanes. So converting a private_swizzled
address to a global
address will result in the corresponding scratch backing memory address. The destination_contiguous_bytes
will indicate how many bytes, starting at the destination_segment_address
, before the scratch backing memory corresponds to a dword of the adjacent lane. To get the scratch backing memory address of the byte after destination_contiguous_bytes
bytes requires amd_dbgapi_convert_address_space to be called again with the address source_segment_address
plus destination_contiguous_bytes
.
A client can use this operation to help manage caching the bytes of different address spaces. An address in an address space that is being accessed can attempt to be converted to the various address spaces being cached to see if it aliases with bytes being cached under a different address space. For example, an address in the AMD GPU generic
address space may alias with an address in the global
, private_swizzled
, or local
address spaces.
- Parameters
-
[in] wave_id The wave that is using the address. If the address_space
is AMD_DBGAPI_ADDRESS_SPACE_GLOBAL thenwave_id
may be AMD_DBGAPI_WAVE_NONE, as the address space does not depend on the active wave, in which caseprocess_id
is used.[in] lane_id The lane of the wave_id
that is using the address. If theaddress_space
does not depend on the active lane then this may be AMD_DBGAPI_LANE_NONE. For example, the AMD_DBGAPI_ADDRESS_SPACE_GLOBAL address space does not depend on the lane.[in] source_address_space_id The address space of the source_segment_address
.[in] source_segment_address The integral value of the source segment address. Only the bits corresponding to the address size for the source_address_space_id
requested are used. The address size is provided by the AMD_DBGAPI_ADDRESS_SPACE_INFO_ADDRESS_SIZE query.[in] destination_address_space_id The address space to which to convert source_segment_address
that is insource_address_space_id
.[out] destination_segment_address The integral value of the segment address in destination_address_space_id
that corresponds tosource_segment_address
insource_address_space_id
. The bits corresponding to the address size for thedestination_address_space_id
are updated, and any remaining bits are set to zero. The address size is provided by the AMD_DBGAPI_ADDRESS_SPACE_INFO_ADDRESS_SIZE query.[out] destination_contiguous_bytes The number of contiguous bytes for which the converted destination_segment_address
continues to correspond to thesource_segment_address
.
- Return values
-
AMD_DBGAPI_STATUS_SUCCESS The function has been executed successfully and the result is stored in destination_segment_address
anddestination_contiguous_bytes
.AMD_DBGAPI_STATUS_FATAL A fatal error occurred. The library is left uninitialized and destination_segment_address
anddestination_contiguous_bytes
are unaltered.AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED The library is not initialized. The library is left uninitialized and destination_segment_address
anddestination_contiguous_bytes
are unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_ID wave_id
is invalid, orwave_id
is AMD_DBGAPI_WAVE_NONE andsource_address_space_id
ordestination_address_space_id
depends on the active wave.destination_segment_address
anddestination_contiguous_bytes
are unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_LANE_ID wave_id
is AMD_DBGAPI_WAVE_NONE andlane_id
is not AMD_DBGAPI_LANE_NONE.wave_id
is not AMD_DBGAPI_WAVE_NONE andlane_id
is not AMD_DBGAPI_LANE_NONE and is not valid forwave_id
.lane_id
is AMD_DBGAPI_LANE_NONE andsource_address_space_id
ordestination_address_space_id
depends on the active lane.destination_segment_address
anddestination_contiguous_bytes
are unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_SPACE_ID source_address_space_id
ordestination_address_space_id
are invalid.destination_segment_address
anddestination_contiguous_bytes
are unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_SPACE_CONVERSION The source_segment_address
in thesource_address_space_id
is not an address that can be represented in thedestination_address_space_id
.destination_segment_address
anddestination_contiguous_bytes
are unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT destination_segment_address
ordestination_contiguous_bytes
are NULL.destination_segment_address
anddestination_contiguous_bytes
are unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY source_address_space_id
ordestination_address_space_id
address spaces are not supported by the architecture ofwave_id
(if not AMD_DBGAPI_WAVE_NONE).destination_segment_address
anddestination_contiguous_bytes
are unaltered.
◆ amd_dbgapi_dwarf_address_class_to_address_class()
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_dwarf_address_class_to_address_class | ( | amd_dbgapi_architecture_id_t | architecture_id, |
uint64_t | dwarf_address_class, | ||
amd_dbgapi_address_class_id_t * | address_class_id | ||
) |
Return the architecture source language address class from a DWARF address class number for an architecture.
The AMD GPU DWARF address class number must be valid for the architecture.
See User Guide for AMDGPU Backend - Code Object - DWARF - Address Class Mapping.
- Parameters
-
[in] architecture_id The architecture of the source language address class. [in] dwarf_address_class The DWARF source language address class. [out] address_class_id The source language address class that corresponds to the DWARF address class for the architecture.
- Return values
-
AMD_DBGAPI_STATUS_SUCCESS The function has been executed successfully and the result is stored in address_class_id
.AMD_DBGAPI_STATUS_FATAL A fatal error occurred. The library is left uninitialized and address_class_id
is unaltered.AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED The library is not initialized. The library is left uninitialized and address_class_id
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_ID architecture_id
is invalid.address_class_id
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT address_class_id
is NULL.address_class_id
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY dwarf_address_class
is not valid for thearchitecture_id
.address_class_id
is unaltered.
◆ amd_dbgapi_dwarf_address_space_to_address_space()
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_dwarf_address_space_to_address_space | ( | amd_dbgapi_architecture_id_t | architecture_id, |
uint64_t | dwarf_address_space, | ||
amd_dbgapi_address_space_id_t * | address_space_id | ||
) |
Return the address space from an AMD GPU DWARF address space number for an architecture.
A DWARF address space describes the architecture specific address spaces. It is used in DWARF location expressions that calculate addresses. See User Guide for AMDGPU Backend - Code Object - DWARF - Address Space Mapping.
The AMD GPU DWARF address space number must be valid for the architecture.
- Parameters
-
[in] architecture_id The architecture of the address space. [in] dwarf_address_space The AMD GPU DWARF address space. [out] address_space_id The address space that corresponds to the DWARF address space for the architecture architecture_id
.
- Return values
-
AMD_DBGAPI_STATUS_SUCCESS The function has been executed successfully and the result is stored in address_space_id
.AMD_DBGAPI_STATUS_FATAL A fatal error occurred. The library is left uninitialized and address_space_id
is unaltered.AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED The library is not initialized. The library is left uninitialized and address_space_id
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_ID architecture_id
is invalid.address_space_id
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT address_space_id
is NULL.address_space_id
is unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY dwarf_address_space
is not valid forarchitecture_id
.address_class_id
is unaltered.
◆ amd_dbgapi_read_memory()
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_read_memory | ( | amd_dbgapi_process_id_t | process_id, |
amd_dbgapi_wave_id_t | wave_id, | ||
amd_dbgapi_lane_id_t | lane_id, | ||
amd_dbgapi_address_space_id_t | address_space_id, | ||
amd_dbgapi_segment_address_t | segment_address, | ||
amd_dbgapi_size_t * | value_size, | ||
void * | value | ||
) |
Read memory.
The memory bytes in address_space
are read for lane_id
of wave_id
starting at segment_address
sequentially into value
until value_size
bytes have been read or an invalid memory address is reached. value_size
is set to the number of bytes read successfully.
If wave_id
is not AMD_DBGAPI_WAVE_NONE then it must be stopped, must belong to process_id
, and its architecture must be the same as that of the address space.
The library performs all necessary hardware cache management so that the memory values read are coherent with the wave_id
if not AMD_DBGAPI_WAVE_NONE. In order for the memory values read to be coherent with other waves, the waves must be stopped when invoking this operation. Stopping wave creation, stopping all waves, performing this operation, resuming any stopped waves, and then allowing wave creation can achieve this requirement. This requirement also applies if memory is read by other operating system supported means.
- Parameters
-
[in] process_id The process to read memory from if wave_id
is AMD_DBGAPI_WAVE_NONE theaddress_space
is AMD_DBGAPI_ADDRESS_SPACE_GLOBAL.[in] wave_id The wave that is accessing the memory. If the address_space
is AMD_DBGAPI_ADDRESS_SPACE_GLOBAL thenwave_id
may be AMD_DBGAPI_WAVE_NONE, as the address space does not depend on the active wave, in which caseprocess_id
is used.[in] lane_id The lane of wave_id
that is accessing the memory. If theaddress_space
does not depend on the active lane then this may be AMD_DBGAPI_LANE_NONE. For example, the AMD_DBGAPI_ADDRESS_SPACE_GLOBAL address space does not depend on the lane.[in] address_space_id The address space of the segment_address
. If the address space is dependent on: the active lane then thelane_id
with in thewave_id
is used; the active workgroup then the workgroup ofwave_id
is used; or the active wave then thewave_id
is used.[in] segment_address The integral value of the segment address. Only the bits corresponding to the address size for the address_space
requested are used. The address size is provided by the AMD_DBGAPI_ADDRESS_SPACE_INFO_ADDRESS_SIZE query.[in,out] value_size Pass in the number of bytes to read from memory. Return the number of bytes successfully read from memory. [out] value Pointer to memory where the result is stored. Must be an array of at least input value_size
bytes.
- Return values
-
AMD_DBGAPI_STATUS_SUCCESS Either the input value_size
was 0, or the inputvalue_size
was greater than 0 and one or more bytes have been read successfully. The outputvalue_size
is set to the number of bytes successfully read, which will be 0 if the inputvalue_size
was 0. The first outputvalue_size
bytes ofvalue
are set to the bytes successfully read, all other bytes invalue
are unaltered.AMD_DBGAPI_STATUS_FATAL A fatal error occurred. The library is left uninitialized; and value_size
andvalue
are unaltered.AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED The library is not initialized. The library is left uninitialized; and value_size
andvalue
are unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_ID process_id
is invalid.value_size
andvalue
are unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_ID wave_id
is invalid, orwave_id
is AMD_DBGAPI_WAVE_NONE andaddress_space
is not AMD_DBGAPI_ADDRESS_SPACE_GLOBAL.value_size
andvalue
are unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_LANE_ID wave_id
is AMD_DBGAPI_WAVE_NONE andlane_id
is not AMD_DBGAPI_LANE_NONE.wave_id
is not AMD_DBGAPI_WAVE_NONE andlane_id
is not AMD_DBGAPI_LANE_NONE and is not valid forwave_id
.lane_id
is AMD_DBGAPI_LANE_NONE andaddress_space_id
depends on the active lane.value_size
andvalue
are unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_SPACE_ID address_space_id
is invalid.value
is unaltered.AMD_DBGAPI_STATUS_ERROR_WAVE_NOT_STOPPED wave_id
is not stopped.value_size
andvalue
are unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT value
orvalue_size
are NULL.value_size
andvalue
are unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY wave_id
in not AMD_DBGAPI_WAVE_NONE and does not belong toprocess_id
or have the same the architecture asaddress_space_id
.value_size
andvalue
are unaltered.AMD_DBGAPI_STATUS_ERROR_MEMORY_ACCESS The input value_size
was greater than 0 and no bytes were successfully read. The outputvalue_size
is set to 0.value
is unaltered.
◆ amd_dbgapi_set_memory_precision()
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_set_memory_precision | ( | amd_dbgapi_process_id_t | process_id, |
amd_dbgapi_memory_precision_t | memory_precision | ||
) |
Control precision of memory access reporting.
A process can be set to AMD_DBGAPI_MEMORY_PRECISION_NONE to disable precise memory reporting. Use the AMD_DBGAPI_PROCESS_INFO_PRECISE_MEMORY_SUPPORTED query to determine if the architectures of all the agents of a process support another memory precision.
The memory precision is set independently for each process, and only affects the waves executing on the agents of that process. The setting may be changed at any time, including when waves are executing, and takes effect immediately.
- Parameters
-
[in] process_id The process being configured. [in] memory_precision The memory precision to set.
- Return values
-
AMD_DBGAPI_STATUS_SUCCESS The function has been executed successfully and the agents of the process have been configured. AMD_DBGAPI_STATUS_FATAL A fatal error occurred. The library is left uninitialized. AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED The library is not initialized. The library is left uninitialized and no configuration is changed. AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_ID process_id
is invalid. No configuration is changed.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT memory_precision
is an invalid value. No configuration is changed.AMD_DBGAPI_STATUS_ERROR_NOT_SUPPORTED The requested memory_precision
is not supported by the architecture of all the agents ofprocess_id
. No configuration is changed.
◆ amd_dbgapi_write_memory()
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_write_memory | ( | amd_dbgapi_process_id_t | process_id, |
amd_dbgapi_wave_id_t | wave_id, | ||
amd_dbgapi_lane_id_t | lane_id, | ||
amd_dbgapi_address_space_id_t | address_space_id, | ||
amd_dbgapi_segment_address_t | segment_address, | ||
amd_dbgapi_size_t * | value_size, | ||
const void * | value | ||
) |
Write memory.
The memory bytes in address_space
are written for lane_id
of wave_id
starting at segment_address
sequentially from value
until value_size
bytes have been written or an invalid memory address is reached. value_size
is set to the number of bytes written successfully.
If wave_id
is not AMD_DBGAPI_WAVE_NONE then it must be stopped, must belong to process_id
, and its architecture must be the same as that of the address space.
The library performs all necessary hardware cache management so that the memory values written are coherent with the wave_id
if not AMD_DBGAPI_WAVE_NONE. In order for the memory values written to be coherent with other waves, the waves must be stopped when invoking this operation. Stopping wave creation, stopping all waves, performing this operation, resuming any stopped waves, and then allowing wave creation can achieve this requirement. This requirement also applies if memory is written by other operating system supported means.
- Parameters
-
[in] process_id The process to write memory to if wave_id
is AMD_DBGAPI_WAVE_NONE theaddress_space
is AMD_DBGAPI_ADDRESS_SPACE_GLOBAL.[in] wave_id The wave that is accessing the memory. If the address_space
is AMD_DBGAPI_ADDRESS_SPACE_GLOBAL thenwave_id
may be AMD_DBGAPI_WAVE_NONE, as the address space does not depend on the active wave, in which caseprocess_id
is used.[in] lane_id The lane of wave_id
that is accessing the memory. If theaddress_space
does not depend on the active lane then this may be AMD_DBGAPI_LANE_NONE. For example, the AMD_DBGAPI_ADDRESS_SPACE_GLOBAL address space does not depend on the lane.[in] address_space_id The address space of the segment_address
. If the address space is dependent on: the active lane then thelane_id
with in thewave_id
is used; the active workgroup then the workgroup ofwave_id
is used; or the active wave then thewave_id
is used.[in] segment_address The integral value of the segment address. Only the bits corresponding to the address size for the address_space
requested are used. The address size is provided by the AMD_DBGAPI_ADDRESS_SPACE_INFO_ADDRESS_SIZE query.[in,out] value_size Pass in the number of bytes to write to memory. Return the number of bytes successfully written to memory. [in] value The bytes to write to memory. Must point to an array of at least input value_size
bytes.
- Return values
-
AMD_DBGAPI_STATUS_SUCCESS Either the input value_size
was 0, or the inputvalue_size
was greater than 0 and one or more bytes have been written successfully. The outputvalue_size
is set to the number of bytes successfully written, which will be 0 if the inputvalue_size
was 0. The first outputvalue_size
bytes of memory starting atsegment_address
are updated, all other memory is unaltered.AMD_DBGAPI_STATUS_FATAL A fatal error occurred. The library is left uninitialized; and the memory and value_size
are unaltered.AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED The library is not initialized. The library is left uninitialized; the memory and value_size
are unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_ID process_id
is invalid. The memory andvalue_size
are unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_ID wave_id
is invalid, orwave_id
is AMD_DBGAPI_WAVE_NONE andaddress_space
is AMD_DBGAPI_ADDRESS_SPACE_GLOBAL. The memory andvalue_size
are unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_LANE_ID wave_id
is AMD_DBGAPI_WAVE_NONE andlane_id
is not AMD_DBGAPI_LANE_NONE.wave_id
is not AMD_DBGAPI_WAVE_NONE andlane_id
is not AMD_DBGAPI_LANE_NONE and is not valid forwave_id
.lane_id
is AMD_DBGAPI_LANE_NONE andaddress_space_id
depends on the active lane. The memory andvalue_size
are unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_SPACE_ID address_space_id
is invalid. The memory andvalue_size
are unaltered.AMD_DBGAPI_STATUS_ERROR_WAVE_NOT_STOPPED wave_id
is not stopped. The memory andvalue_size
are unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT value
orvalue_size
are NULL. The memory andvalue_size
are unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY wave_id
in not AMD_DBGAPI_WAVE_NONE and does not belong toprocess_id
or have the same the architecture asaddress_space_id
. The memory andvalue_size
are unaltered.AMD_DBGAPI_STATUS_ERROR_MEMORY_ACCESS The input value_size
was greater than 0 and no bytes were successfully written. The outputvalue_size
is set to 0. The memory andvalue_size
are unaltered.AMD_DBGAPI_STATUS_ERROR_PROCESS_FROZEN This operation is not permitted because the process is frozen. The memory and value_size
are unaltered.