Memory#

AMD DBG API: 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...
 

Enumerations

enum  amd_dbgapi_address_class_info_t { AMD_DBGAPI_ADDRESS_CLASS_INFO_NAME = 1, AMD_DBGAPI_ADDRESS_CLASS_INFO_ADDRESS_SPACE = 2, AMD_DBGAPI_ADDRESS_CLASS_INFO_DWARF = 3 }
 Source language address class queries that are supported by amd_dbgapi_address_class_get_info. More...
 
enum  amd_dbgapi_address_space_access_t { AMD_DBGAPI_ADDRESS_SPACE_ACCESS_ALL = 1, AMD_DBGAPI_ADDRESS_SPACE_ACCESS_PROGRAM_CONSTANT = 2, AMD_DBGAPI_ADDRESS_SPACE_ACCESS_DISPATCH_CONSTANT = 3 }
 Indication of how the address space is accessed. More...
 
enum  amd_dbgapi_address_space_info_t {
  AMD_DBGAPI_ADDRESS_SPACE_INFO_NAME = 1, AMD_DBGAPI_ADDRESS_SPACE_INFO_ADDRESS_SIZE = 2, AMD_DBGAPI_ADDRESS_SPACE_INFO_NULL_ADDRESS = 3, AMD_DBGAPI_ADDRESS_SPACE_INFO_ACCESS = 4,
  AMD_DBGAPI_ADDRESS_SPACE_INFO_DWARF = 5
}
 Address space queries that are supported by amd_dbgapi_address_space_get_info. More...
 
enum  amd_dbgapi_segment_address_dependency_t {
  AMD_DBGAPI_SEGMENT_ADDRESS_DEPENDENCE_NONE = 0, AMD_DBGAPI_SEGMENT_ADDRESS_DEPENDENCE_LANE = 1, AMD_DBGAPI_SEGMENT_ADDRESS_DEPENDENCE_WAVE = 2, AMD_DBGAPI_SEGMENT_ADDRESS_DEPENDENCE_WORKGROUP = 3,
  AMD_DBGAPI_SEGMENT_ADDRESS_DEPENDENCE_AGENT = 4, AMD_DBGAPI_SEGMENT_ADDRESS_DEPENDENCE_PROCESS = 5
}
 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. More...
 
enum  amd_dbgapi_address_class_state_t { AMD_DBGAPI_ADDRESS_CLASS_STATE_NOT_MEMBER = 0, AMD_DBGAPI_ADDRESS_CLASS_STATE_MEMBER = 1 }
 Indication of whether a segment address in an address space is a member of an source language address class. More...
 
enum  amd_dbgapi_memory_precision_t { AMD_DBGAPI_MEMORY_PRECISION_NONE = 0, AMD_DBGAPI_MEMORY_PRECISION_PRECISE = 1 }
 Memory access precision. More...
 

Functions

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) AMD_DBGAPI_VERSION_0_62
 Query information about a source language address class of an architecture. More...
 
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) AMD_DBGAPI_VERSION_0_54
 Report the list of source language address classes supported by the architecture. More...
 
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) AMD_DBGAPI_VERSION_0_54
 Return the architecture source language address class from a DWARF address class number for an architecture. More...
 
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) AMD_DBGAPI_VERSION_0_62
 Query information about an address space. More...
 
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) AMD_DBGAPI_VERSION_0_54
 Report the list of address spaces supported by the architecture. More...
 
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) AMD_DBGAPI_VERSION_0_54
 Return the address space from an AMD GPU DWARF address space number for an architecture. More...
 
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) AMD_DBGAPI_VERSION_0_62
 Convert a source segment address in the source address space into a destination segment address in the destination address space. More...
 
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) AMD_DBGAPI_VERSION_0_64
 Determine the dependency of a segment address value in a particular address space. More...
 
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) AMD_DBGAPI_VERSION_0_54
 Determine if a segment address in an address space is a member of a source language address class. More...
 
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) AMD_DBGAPI_VERSION_0_54
 Read memory. More...
 
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) AMD_DBGAPI_VERSION_0_54
 Write memory. More...
 
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) AMD_DBGAPI_VERSION_0_54
 Control precision of memory access reporting. 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.

See User Guide for AMDGPU Backend - LLVM - Address Spaces.

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 char. It is allocated by the amd_dbgapi_callbacks_s::allocate_memory callback and is owned by the client.

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 uint64_t.

◆ 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.

Enumerator
AMD_DBGAPI_ADDRESS_CLASS_STATE_NOT_MEMBER 

The segment address in the address space is not a member of the source language address class.

AMD_DBGAPI_ADDRESS_CLASS_STATE_MEMBER 

The segment address in the address space is a member of the source language address class.

◆ amd_dbgapi_address_space_access_t

Indication of how the address space is accessed.

Enumerator
AMD_DBGAPI_ADDRESS_SPACE_ACCESS_ALL 

The address space supports all accesses.

Values accessed can change during the lifetime of the program.

AMD_DBGAPI_ADDRESS_SPACE_ACCESS_PROGRAM_CONSTANT 

The address space is read only.

Values accessed are always the same value for the lifetime of the program execution.

AMD_DBGAPI_ADDRESS_SPACE_ACCESS_DISPATCH_CONSTANT 

The address space is only read the waves of a kernel dispatch.

Values accessed are always the same value for the lifetime of the dispatch.

◆ 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 char*. It is allocated by the amd_dbgapi_callbacks_s::allocate_memory callback and is owned by the client.

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_segment_address_t.

AMD_DBGAPI_ADDRESS_SPACE_INFO_ACCESS 

Return the address space access.

The type of this attribute is uint32_t with values defined by amd_dbgapi_address_space_access_t.

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 uint64_t.

◆ 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.

Enumerator
AMD_DBGAPI_MEMORY_PRECISION_NONE 

Memory instructions execute normally and a wave does not wait for the memory access to complete.

AMD_DBGAPI_MEMORY_PRECISION_PRECISE 

A wave waits for memory instructions to complete before executing further instructions.

This can cause a wave to execute significantly slower.

◆ 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.

Enumerator
AMD_DBGAPI_SEGMENT_ADDRESS_DEPENDENCE_NONE 

No dependence is available.

AMD_DBGAPI_SEGMENT_ADDRESS_DEPENDENCE_LANE 

Reading or writing the segment address depends on the lane.

AMD_DBGAPI_SEGMENT_ADDRESS_DEPENDENCE_WAVE 

Reading or writing the segment address depends on the wavefront.

AMD_DBGAPI_SEGMENT_ADDRESS_DEPENDENCE_WORKGROUP 

Reading or writing the segment address depends on the workgroup.

AMD_DBGAPI_SEGMENT_ADDRESS_DEPENDENCE_AGENT 

Reading or writing the segment address depends on the agent.

AMD_DBGAPI_SEGMENT_ADDRESS_DEPENDENCE_PROCESS 

Reading or writing the segment address depends on the process.

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_idThe handle of the source language address class being queried.
[in]queryThe query being requested.
[in]value_sizeSize of the memory pointed to by value. Must be equal to the byte size of the query result.
[out]valuePointer to memory where the query result is stored.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully and the result is stored in value.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized and value is unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized and value is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_CLASS_IDaddress_class_id is invalid. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTvalue is NULL or query is invalid. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITYvalue_size does not match the size of the query result. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACKThis 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_idThe address space of the segment_address.
[in]segment_addressThe 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_dependencyThe dependency of the segment_address value in address_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_SUCCESSThe function has been executed successfully and the result is stored in segment_address_dependencies.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized and segment_address_dependencies is unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized and destination_segment_address and segment_address_dependencies is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_SPACE_IDaddress_space_id is invalid. segment_address_dependencies is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTsegment_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_idThe wave that is using the address. If the address_space is AMD_DBGAPI_ADDRESS_SPACE_GLOBAL then wave_id may be AMD_DBGAPI_WAVE_NONE, as the address space does not depend on the active wave, in which case process_id is used.
[in]lane_idThe lane of the wave_id that is using the address. If the address_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_idThe address space of the segment_address. If the address space is dependent on: the active lane then the lane_id with in the wave_id is used; the active workgroup then the workgroup of wave_id is used; or the active wave then the wave_id is used.
[in]segment_addressThe 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_idThe handle of the source language address class.
[out]address_class_stateAMD_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_SUCCESSThe function has been executed successfully and the result is stored in address_class_state.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized and address_class_state is unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized and address_class_state is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_IDwave_id is invalid, or wave_id is AMD_DBGAPI_WAVE_NONE and address_space is not AMD_DBGAPI_ADDRESS_SPACE_GLOBAL. address_class_state is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_LANE_IDwave_id is AMD_DBGAPI_WAVE_NONE and lane_id is not AMD_DBGAPI_LANE_NONE. wave_id is not AMD_DBGAPI_WAVE_NONE and lane_id is not AMD_DBGAPI_LANE_NONE and is not valid for wave_id. lane_id is AMD_DBGAPI_LANE_NONE and address_space_id depends on the active lane. address_class_state is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_SPACE_IDaddress_space_id is invalid. address_class_state is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_CLASS_IDaddress_class_id is invalid. address_class_state is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTaddress_class_state is NULL. address_class_state is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITYThe architectures of wave_id, address_space_id, and address_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_idThe address space.
[in]queryThe query being requested.
[in]value_sizeSize of the memory pointed to by value. Must be equal to the byte size of the query result.
[out]valuePointer to memory where the query result is stored.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully and the result is stored in value.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized and value is unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized and value is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_SPACE_IDaddress_space_id is invalid. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTquery is invalid or value is NULL. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITYvalue_size does not match the size of the query result. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACKThis 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_idThe architecture being queried.
[out]address_class_countThe number of architecture source language address classes.
[out]address_classesA 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_SUCCESSThe function has been executed successfully and the result is stored in address_class_count and address_classes.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized; and address_class_count and address_classes are unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized; and address_class_count and address_classes are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_IDarchitecture_id is invalid. address_class_count and address_classes are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTaddress_class_count or address_classes are NULL. address_class_count and address_classes are unaltered.
AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACKThis will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate address_classes returns NULL. address_class_count and address_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_idThe architecture being queried.
[out]address_space_countThe number of architecture address spaces.
[out]address_spacesA 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_SUCCESSThe function has been executed successfully and the result is stored in address_space_count and address_spaces.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized; and address_space_count and address_spaces are unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized; and address_space_count and address_spaces are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_IDarchitecture_id is invalid. address_space_count and address_spaces are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTaddress_space_count and address_spaces are NULL. address_space_count and address_spaces are unaltered.
AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACKThis will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate address_spaces returns NULL. address_space_count and address_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_idThe wave that is using the address. If the address_space is AMD_DBGAPI_ADDRESS_SPACE_GLOBAL then wave_id may be AMD_DBGAPI_WAVE_NONE, as the address space does not depend on the active wave, in which case process_id is used.
[in]lane_idThe lane of the wave_id that is using the address. If the address_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_idThe address space of the source_segment_address.
[in]source_segment_addressThe 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_idThe address space to which to convert source_segment_address that is in source_address_space_id.
[out]destination_segment_addressThe integral value of the segment address in destination_address_space_id that corresponds to source_segment_address in source_address_space_id. The bits corresponding to the address size for the destination_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_bytesThe number of contiguous bytes for which the converted destination_segment_address continues to correspond to the source_segment_address.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully and the result is stored in destination_segment_address and destination_contiguous_bytes.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized and destination_segment_address and destination_contiguous_bytes are unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized and destination_segment_address and destination_contiguous_bytes are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_IDwave_id is invalid, or wave_id is AMD_DBGAPI_WAVE_NONE and source_address_space_id or destination_address_space_id depends on the active wave. destination_segment_address and destination_contiguous_bytes are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_LANE_IDwave_id is AMD_DBGAPI_WAVE_NONE and lane_id is not AMD_DBGAPI_LANE_NONE. wave_id is not AMD_DBGAPI_WAVE_NONE and lane_id is not AMD_DBGAPI_LANE_NONE and is not valid for wave_id. lane_id is AMD_DBGAPI_LANE_NONE and source_address_space_id or destination_address_space_id depends on the active lane. destination_segment_address and destination_contiguous_bytes are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_SPACE_IDsource_address_space_id or destination_address_space_id are invalid. destination_segment_address and destination_contiguous_bytes are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_SPACE_CONVERSIONThe source_segment_address in the source_address_space_id is not an address that can be represented in the destination_address_space_id. destination_segment_address and destination_contiguous_bytes are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTdestination_segment_address or destination_contiguous_bytes are NULL. destination_segment_address and destination_contiguous_bytes are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITYsource_address_space_id or destination_address_space_id address spaces are not supported by the architecture of wave_id (if not AMD_DBGAPI_WAVE_NONE). destination_segment_address and destination_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_idThe architecture of the source language address class.
[in]dwarf_address_classThe DWARF source language address class.
[out]address_class_idThe source language address class that corresponds to the DWARF address class for the architecture.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully and the result is stored in address_class_id.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized and address_class_id is unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized and address_class_id is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_IDarchitecture_id is invalid. address_class_id is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTaddress_class_id is NULL. address_class_id is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITYdwarf_address_class is not valid for the architecture_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_idThe architecture of the address space.
[in]dwarf_address_spaceThe AMD GPU DWARF address space.
[out]address_space_idThe address space that corresponds to the DWARF address space for the architecture architecture_id.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully and the result is stored in address_space_id.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized and address_space_id is unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized and address_space_id is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_IDarchitecture_id is invalid. address_space_id is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTaddress_space_id is NULL. address_space_id is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITYdwarf_address_space is not valid for architecture_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_idThe process to read memory from if wave_id is AMD_DBGAPI_WAVE_NONE the address_space is AMD_DBGAPI_ADDRESS_SPACE_GLOBAL.
[in]wave_idThe wave that is accessing the memory. If the address_space is AMD_DBGAPI_ADDRESS_SPACE_GLOBAL then wave_id may be AMD_DBGAPI_WAVE_NONE, as the address space does not depend on the active wave, in which case process_id is used.
[in]lane_idThe lane of wave_id that is accessing the memory. If the address_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_idThe address space of the segment_address. If the address space is dependent on: the active lane then the lane_id with in the wave_id is used; the active workgroup then the workgroup of wave_id is used; or the active wave then the wave_id is used.
[in]segment_addressThe 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_sizePass in the number of bytes to read from memory. Return the number of bytes successfully read from memory.
[out]valuePointer to memory where the result is stored. Must be an array of at least input value_size bytes.
Return values
AMD_DBGAPI_STATUS_SUCCESSEither the input value_size was 0, or the input value_size was greater than 0 and one or more bytes have been read successfully. The output value_size is set to the number of bytes successfully read, which will be 0 if the input value_size was 0. The first output value_size bytes of value are set to the bytes successfully read, all other bytes in value are unaltered.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized; and value_size and value are unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized; and value_size and value are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_IDprocess_id is invalid. value_size and value are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_IDwave_id is invalid, or wave_id is AMD_DBGAPI_WAVE_NONE and address_space is not AMD_DBGAPI_ADDRESS_SPACE_GLOBAL. value_size and value are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_LANE_IDwave_id is AMD_DBGAPI_WAVE_NONE and lane_id is not AMD_DBGAPI_LANE_NONE. wave_id is not AMD_DBGAPI_WAVE_NONE and lane_id is not AMD_DBGAPI_LANE_NONE and is not valid for wave_id. lane_id is AMD_DBGAPI_LANE_NONE and address_space_id depends on the active lane. value_size and value are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_SPACE_IDaddress_space_id is invalid. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_WAVE_NOT_STOPPEDwave_id is not stopped. value_size and value are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTvalue or value_size are NULL. value_size and value are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITYwave_id in not AMD_DBGAPI_WAVE_NONE and does not belong to process_id or have the same the architecture as address_space_id. value_size and value are unaltered.
AMD_DBGAPI_STATUS_ERROR_MEMORY_ACCESSThe input value_size was greater than 0 and no bytes were successfully read. The output value_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_idThe process being configured.
[in]memory_precisionThe memory precision to set.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully and the agents of the process have been configured.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized and no configuration is changed.
AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_IDprocess_id is invalid. No configuration is changed.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTmemory_precision is an invalid value. No configuration is changed.
AMD_DBGAPI_STATUS_ERROR_NOT_SUPPORTEDThe requested memory_precision is not supported by the architecture of all the agents of process_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_idThe process to write memory to if wave_id is AMD_DBGAPI_WAVE_NONE the address_space is AMD_DBGAPI_ADDRESS_SPACE_GLOBAL.
[in]wave_idThe wave that is accessing the memory. If the address_space is AMD_DBGAPI_ADDRESS_SPACE_GLOBAL then wave_id may be AMD_DBGAPI_WAVE_NONE, as the address space does not depend on the active wave, in which case process_id is used.
[in]lane_idThe lane of wave_id that is accessing the memory. If the address_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_idThe address space of the segment_address. If the address space is dependent on: the active lane then the lane_id with in the wave_id is used; the active workgroup then the workgroup of wave_id is used; or the active wave then the wave_id is used.
[in]segment_addressThe 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_sizePass in the number of bytes to write to memory. Return the number of bytes successfully written to memory.
[in]valueThe bytes to write to memory. Must point to an array of at least input value_size bytes.
Return values
AMD_DBGAPI_STATUS_SUCCESSEither the input value_size was 0, or the input value_size was greater than 0 and one or more bytes have been written successfully. The output value_size is set to the number of bytes successfully written, which will be 0 if the input value_size was 0. The first output value_size bytes of memory starting at segment_address are updated, all other memory is unaltered.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized; and the memory and value_size are unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized; the memory and value_size are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_IDprocess_id is invalid. The memory and value_size are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_IDwave_id is invalid, or wave_id is AMD_DBGAPI_WAVE_NONE and address_space is AMD_DBGAPI_ADDRESS_SPACE_GLOBAL. The memory and value_size are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_LANE_IDwave_id is AMD_DBGAPI_WAVE_NONE and lane_id is not AMD_DBGAPI_LANE_NONE. wave_id is not AMD_DBGAPI_WAVE_NONE and lane_id is not AMD_DBGAPI_LANE_NONE and is not valid for wave_id. lane_id is AMD_DBGAPI_LANE_NONE and address_space_id depends on the active lane. The memory and value_size are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_SPACE_IDaddress_space_id is invalid. The memory and value_size are unaltered.
AMD_DBGAPI_STATUS_ERROR_WAVE_NOT_STOPPEDwave_id is not stopped. The memory and value_size are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTvalue or value_size are NULL. The memory and value_size are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITYwave_id in not AMD_DBGAPI_WAVE_NONE and does not belong to process_id or have the same the architecture as address_space_id. The memory and value_size are unaltered.
AMD_DBGAPI_STATUS_ERROR_MEMORY_ACCESSThe input value_size was greater than 0 and no bytes were successfully written. The output value_size is set to 0. The memory and value_size are unaltered.