Memory

Data Structures | Macros | Typedefs | Enumerations | Functions

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

enum 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

enum 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

enum 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

enum 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

enum 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

enum 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_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 or query is invalid. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY	value_size does not match the size of the query 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 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_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 and segment_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 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_id	The 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_id	The 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_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, 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_ID	wave_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_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, 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_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 or value is NULL. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY	value_size does not match the size of the query 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 and address_classes.
AMD_DBGAPI_STATUS_FATAL	A fatal error occurred. The library is left uninitialized; and address_class_count and address_classes are unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED	The library is not initialized. The library is left uninitialized; and address_class_count and address_classes are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_ID	architecture_id is invalid. address_class_count and address_classes are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT	address_class_count or address_classes are NULL. address_class_count and address_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 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_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 and address_spaces.
AMD_DBGAPI_STATUS_FATAL	A fatal error occurred. The library is left uninitialized; and address_space_count and address_spaces are unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED	The library is not initialized. The library is left uninitialized; and address_space_count and address_spaces are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_ID	architecture_id is invalid. address_space_count and address_spaces are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT	address_space_count and address_spaces are NULL. address_space_count and address_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 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_id	The 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_id	The 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_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 in source_address_space_id.
[out]	destination_segment_address	The 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_bytes	The number of contiguous bytes for which the converted destination_segment_address continues to correspond to the source_segment_address.

Return values

AMD_DBGAPI_STATUS_SUCCESS	The function has been executed successfully and the result is stored in destination_segment_address and destination_contiguous_bytes.
AMD_DBGAPI_STATUS_FATAL	A fatal error occurred. The library is left uninitialized and destination_segment_address and destination_contiguous_bytes are unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED	The 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_ID	wave_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_ID	wave_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_ID	source_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_CONVERSION	The 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_ARGUMENT	destination_segment_address or destination_contiguous_bytes are NULL. destination_segment_address and destination_contiguous_bytes are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY	source_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_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 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_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 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_id	The process to read memory from if wave_id is AMD_DBGAPI_WAVE_NONE the address_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 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_id	The 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_id	The 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_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 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_FATAL	A fatal error occurred. The library is left uninitialized; and value_size and value are unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED	The library is not initialized. The library is left uninitialized; and value_size and value are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_ID	process_id is invalid. value_size and value are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_ID	wave_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_ID	wave_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_ID	address_space_id is invalid. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_WAVE_NOT_STOPPED	wave_id is not stopped. value_size and value are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT	value or value_size are NULL. value_size and value are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY	wave_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_ACCESS	The 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_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 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_id	The process to write memory to if wave_id is AMD_DBGAPI_WAVE_NONE the address_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 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_id	The 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_id	The 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_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 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_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 and value_size are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_ID	wave_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_ID	wave_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_ID	address_space_id is invalid. The memory and value_size are unaltered.
AMD_DBGAPI_STATUS_ERROR_WAVE_NOT_STOPPED	wave_id is not stopped. The memory and value_size are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT	value or value_size are NULL. The memory and value_size are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY	wave_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_ACCESS	The 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.