Wave

Wave#

AMD DBG API: Wave

Operations related to AMD GPU waves. More...

Data Structures

struct  amd_dbgapi_wave_id_t
 Opaque wave handle. More...
 

Macros

#define AMD_DBGAPI_WAVE_NONE    AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_wave_id_t, 0)
 The NULL wave handle. More...
 

Enumerations

enum  amd_dbgapi_wave_info_t {
  AMD_DBGAPI_WAVE_INFO_STATE = 1 , AMD_DBGAPI_WAVE_INFO_STOP_REASON = 2 , AMD_DBGAPI_WAVE_INFO_WATCHPOINTS = 3 , AMD_DBGAPI_WAVE_INFO_DISPATCH = 4 ,
  AMD_DBGAPI_WAVE_INFO_QUEUE = 5 , AMD_DBGAPI_WAVE_INFO_AGENT = 6 , AMD_DBGAPI_WAVE_INFO_PROCESS = 7 , AMD_DBGAPI_WAVE_INFO_ARCHITECTURE = 8 ,
  AMD_DBGAPI_WAVE_INFO_PC = 9 , AMD_DBGAPI_WAVE_INFO_EXEC_MASK = 10 , AMD_DBGAPI_WAVE_INFO_WORK_GROUP_COORD = 11 , AMD_DBGAPI_WAVE_INFO_WAVE_NUMBER_IN_WORK_GROUP = 12 ,
  AMD_DBGAPI_WAVE_INFO_LANE_COUNT = 13
}
 Wave queries that are supported by amd_dbgapi_wave_get_info. More...
 
enum  amd_dbgapi_wave_state_t { AMD_DBGAPI_WAVE_STATE_RUN = 1 , AMD_DBGAPI_WAVE_STATE_SINGLE_STEP = 2 , AMD_DBGAPI_WAVE_STATE_STOP = 3 }
 The execution state of a wave. More...
 
enum  amd_dbgapi_wave_stop_reasons_t {
  AMD_DBGAPI_WAVE_STOP_REASON_NONE = 0ULL , AMD_DBGAPI_WAVE_STOP_REASON_BREAKPOINT = (1ULL << 0) , AMD_DBGAPI_WAVE_STOP_REASON_WATCHPOINT = (1ULL << 1) , AMD_DBGAPI_WAVE_STOP_REASON_SINGLE_STEP = (1ULL << 2) ,
  AMD_DBGAPI_WAVE_STOP_REASON_FP_INPUT_DENORMAL = (1ULL << 3) , AMD_DBGAPI_WAVE_STOP_REASON_FP_DIVIDE_BY_0 = (1ULL << 4) , AMD_DBGAPI_WAVE_STOP_REASON_FP_OVERFLOW = (1ULL << 5) , AMD_DBGAPI_WAVE_STOP_REASON_FP_UNDERFLOW = (1ULL << 6) ,
  AMD_DBGAPI_WAVE_STOP_REASON_FP_INEXACT = (1ULL << 7) , AMD_DBGAPI_WAVE_STOP_REASON_FP_INVALID_OPERATION = (1ULL << 8) , AMD_DBGAPI_WAVE_STOP_REASON_INT_DIVIDE_BY_0 = (1ULL << 9) , AMD_DBGAPI_WAVE_STOP_REASON_DEBUG_TRAP = (1ULL << 10) ,
  AMD_DBGAPI_WAVE_STOP_REASON_ASSERT_TRAP = (1ULL << 11) , AMD_DBGAPI_WAVE_STOP_REASON_TRAP = (1ULL << 12) , AMD_DBGAPI_WAVE_STOP_REASON_MEMORY_VIOLATION = (1ULL << 13) , AMD_DBGAPI_WAVE_STOP_REASON_APERTURE_VIOLATION = (1ULL << 14) ,
  AMD_DBGAPI_WAVE_STOP_REASON_ILLEGAL_INSTRUCTION = (1ULL << 15) , AMD_DBGAPI_WAVE_STOP_REASON_ECC_ERROR = (1ULL << 16) , AMD_DBGAPI_WAVE_STOP_REASON_FATAL_HALT = (1ULL << 17)
}
 A bit mask of the reasons that a wave stopped. More...
 
enum  amd_dbgapi_resume_mode_t { AMD_DBGAPI_RESUME_MODE_NORMAL = 0 , AMD_DBGAPI_RESUME_MODE_SINGLE_STEP = 1 }
 The mode in which to resuming the execution of a wave. More...
 

Functions

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_wave_get_info (amd_dbgapi_wave_id_t wave_id, amd_dbgapi_wave_info_t query, size_t value_size, void *value) AMD_DBGAPI_VERSION_0_58
 Query information about a wave. More...
 
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_process_wave_list (amd_dbgapi_process_id_t process_id, size_t *wave_count, amd_dbgapi_wave_id_t **waves, amd_dbgapi_changed_t *changed) AMD_DBGAPI_VERSION_0_54
 Return the list of existing waves. More...
 
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_wave_stop (amd_dbgapi_wave_id_t wave_id) AMD_DBGAPI_VERSION_0_54
 Request a wave to stop executing. More...
 
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_wave_resume (amd_dbgapi_wave_id_t wave_id, amd_dbgapi_resume_mode_t resume_mode, amd_dbgapi_exceptions_t exceptions) AMD_DBGAPI_VERSION_0_58
 Resume execution of a stopped wave. More...
 

Detailed Description

Operations related to AMD GPU waves.

Macro Definition Documentation

◆ AMD_DBGAPI_WAVE_NONE

#define AMD_DBGAPI_WAVE_NONE    AMD_DBGAPI_HANDLE_LITERAL (amd_dbgapi_wave_id_t, 0)

The NULL wave handle.

Enumeration Type Documentation

◆ amd_dbgapi_resume_mode_t

The mode in which to resuming the execution of a wave.

Enumerator
AMD_DBGAPI_RESUME_MODE_NORMAL 

Resume normal execution.

AMD_DBGAPI_RESUME_MODE_SINGLE_STEP 

Resume execution in in single step mode.

◆ amd_dbgapi_wave_info_t

Wave queries that are supported by amd_dbgapi_wave_get_info.

Each query specifies the type of data returned in the value argument to amd_dbgapi_wave_get_info.

Enumerator
AMD_DBGAPI_WAVE_INFO_STATE 

Return the wave's state.

The type of this attribute is uint32_t with values define by amd_dbgapi_wave_state_t.

AMD_DBGAPI_WAVE_INFO_STOP_REASON 

Return the reason the wave stopped as a bit set.

The type of this attribute is uint32_t with values defined by amd_dbgapi_wave_stop_reasons_t. The wave must be stopped to make this query.

AMD_DBGAPI_WAVE_INFO_WATCHPOINTS 

Return the watchpoint(s) the wave triggered.

The type of this attribute is amd_dbgapi_watchpoint_list_t. The amd_dbgapi_watchpoint_list_t::count field is set to the number of watchpoints that were triggered. The amd_dbgapi_watchpoint_list_t::watchpoint_ids field is set to a pointer to an array of amd_dbgapi_watchpoint_id_t with amd_dbgapi_watchpoint_list_t::count elements comprising the triggered watchpoint handles. The array is allocated by the amd_dbgapi_callbacks_s::allocate_memory callback and is owned by the client. The wave must be stopped to make this query.

AMD_DBGAPI_WAVE_INFO_DISPATCH 

Return the dispatch to which this wave belongs.

The type of this attribute is amd_dbgapi_dispatch_id_t.

If the dispatch associated with a wave is not available then amd_dbgapi_wave_get_info returns the AMD_DBGAPI_STATUS_ERROR_NOT_AVAILABLE error. See the Known Limitations and Restrictions section.

AMD_DBGAPI_WAVE_INFO_QUEUE 

Return the queue to which this wave belongs.

The type of this attribute is amd_dbgapi_queue_id_t.

AMD_DBGAPI_WAVE_INFO_AGENT 

Return the agent to which this wave belongs.

The type of this attribute is amd_dbgapi_agent_id_t.

AMD_DBGAPI_WAVE_INFO_PROCESS 

Return the process to which this wave belongs.

The type of this attribute is amd_dbgapi_process_id_t.

AMD_DBGAPI_WAVE_INFO_ARCHITECTURE 

Return the architecture of this wave.

The type of this attribute is amd_dbgapi_architecture_id_t.

AMD_DBGAPI_WAVE_INFO_PC 

Return the current program counter value of the wave.

The type of this attribute is amd_dbgapi_global_address_t. The wave must be stopped to make this query.

AMD_DBGAPI_WAVE_INFO_EXEC_MASK 

Return the current execution mask of the wave.

Each bit of the mask maps to a lane with the least significant bit corresponding to the lane with a amd_dbgapi_lane_id_t value of 0 and so forth. If the bit is 1 then the lane is active, otherwise the lane is not active. The type of this attribute is uint64_t. The wave must be stopped to make this query.

AMD_DBGAPI_WAVE_INFO_WORK_GROUP_COORD 

The wave workgroup coordinate in the dispatch grid dimensions.

The type of this attribute is uint32_t[3] with elements 1, 2, and 3 corresponding to the X, Y, and Z coordinates respectively.

If the dispatch associated with a wave is not available then amd_dbgapi_wave_get_info returns AMD_DBGAPI_STATUS_ERROR_NOT_AVAILABLE. See the Known Limitations and Restrictions section.

AMD_DBGAPI_WAVE_INFO_WAVE_NUMBER_IN_WORK_GROUP 

The wave's number in the workgroup.

The type of this attribute is uint32_t. The work-items of a workgroup are mapped to the lanes of the waves of the workgroup in flattened work-item ID order, with the first work-item corresponding to lane 0 of wave 0, and so forth.

If the dispatch associated with a wave is not available then amd_dbgapi_wave_get_info returns AMD_DBGAPI_STATUS_ERROR_NOT_AVAILABLE. See the Known Limitations and Restrictions section.

AMD_DBGAPI_WAVE_INFO_LANE_COUNT 

The number of lanes supported by the wave.

The type of this attribute is size_t.

◆ amd_dbgapi_wave_state_t

The execution state of a wave.

Enumerator
AMD_DBGAPI_WAVE_STATE_RUN 

The wave is running.

AMD_DBGAPI_WAVE_STATE_SINGLE_STEP 

The wave is running in single-step mode.

It will execute a single instruction and then stop.

AMD_DBGAPI_WAVE_STATE_STOP 

The wave is stopped.

Note that a wave may stop at any time due to the instructions it executes or because the queue it is executing on enters the error state. This will cause a AMD_DBGAPI_EVENT_KIND_WAVE_STOP event to be created. However, until amd_dbgapi_process_next_pending_event returns the event, the wave will continue to be reported as in the AMD_DBGAPI_WAVE_STATE_RUN state. Only when the AMD_DBGAPI_EVENT_KIND_WAVE_STOP event is returned by amd_dbgapi_process_next_pending_event will the wave be reported in the AMD_DBGAPI_WAVE_STATE_STOP state.

◆ amd_dbgapi_wave_stop_reasons_t

A bit mask of the reasons that a wave stopped.

The stop reason of a wave is available using the AMD_DBGAPI_WAVE_INFO_STOP_REASON query.

Enumerator
AMD_DBGAPI_WAVE_STOP_REASON_NONE 

If none of the bits are set, then amd_dbgapi_wave_stop stopped the wave.

AMD_DBGAPI_WAVE_STOP_REASON_BREAKPOINT 

The wave stopped due to executing a breakpoint instruction.

Use the AMD_DBGAPI_ARCHITECTURE_INFO_BREAKPOINT_INSTRUCTION_PC_ADJUST query to determine the address of the breakpoint instruction.

AMD_DBGAPI_WAVE_STOP_REASON_WATCHPOINT 

The wave stopped due to triggering a data watchpoint.

The AMD_DBGAPI_WAVE_INFO_WATCHPOINTS query can be used to determine which watchpoint(s) were triggered.

The program counter may not be positioned at the instruction that caused the watchpoint(s) to be triggered as the AMD GPU can continue executing instructions after initiating a memory operation. If the architecture supports it, the amd_dbgapi_set_memory_precision can be used to control the precision, but may significantly reduce performance.

AMD_DBGAPI_WAVE_STOP_REASON_SINGLE_STEP 

The wave stopped due to completing an instruction single-step.

AMD_DBGAPI_WAVE_STOP_REASON_FP_INPUT_DENORMAL 

The wave stopped due to triggering an enabled floating point input denormal exception.

This stop reason would normally put the wave's queue into the queue error state and include the AMD_DBGAPI_EXCEPTION_WAVE_TRAP queue error reason.

AMD_DBGAPI_WAVE_STOP_REASON_FP_DIVIDE_BY_0 

The wave stopped due to triggering an enabled floating point divide by zero exception.

This stop reason would normally put the wave's queue into the queue error state and include the AMD_DBGAPI_EXCEPTION_WAVE_TRAP queue error reason.

AMD_DBGAPI_WAVE_STOP_REASON_FP_OVERFLOW 

The wave stopped due to triggering an enabled floating point overflow exception.

This stop reason would normally put the wave's queue into the queue error state and include the AMD_DBGAPI_EXCEPTION_WAVE_TRAP queue error reason.

AMD_DBGAPI_WAVE_STOP_REASON_FP_UNDERFLOW 

The wave stopped due to triggering an enabled floating point underflow exception.

This stop reason would normally put the wave's queue into the queue error state and include the AMD_DBGAPI_EXCEPTION_WAVE_TRAP queue error reason.

AMD_DBGAPI_WAVE_STOP_REASON_FP_INEXACT 

The wave stopped due to triggering an enabled floating point inexact exception.

This stop reason would normally put the wave's queue into the queue error state and include the AMD_DBGAPI_EXCEPTION_WAVE_TRAP queue error reason.

AMD_DBGAPI_WAVE_STOP_REASON_FP_INVALID_OPERATION 

The wave stopped due to triggering an enabled floating point invalid operation exception.

This stop reason would normally put the wave's queue into the queue error state and include the AMD_DBGAPI_EXCEPTION_WAVE_TRAP queue error reason.

AMD_DBGAPI_WAVE_STOP_REASON_INT_DIVIDE_BY_0 

The wave stopped due to triggering an enabled integer divide by zero exception.

This stop reason would normally put the wave's queue into the queue error state and include the AMD_DBGAPI_EXCEPTION_WAVE_TRAP queue error reason.

AMD_DBGAPI_WAVE_STOP_REASON_DEBUG_TRAP 

The wave stopped due to executing a debug trap instruction.

The program counter is left positioned after the trap instruction. The wave can be resumed using amd_dbgapi_wave_resume.

The debug trap instruction can be generated using the llvm.debugtrap compiler intrinsic. See User Guide for AMDGPU Backend - Code Conventions - AMDHSA - Trap Handler ABI.

A debug trap can be used to explicitly insert stop points in a program to help debugging. They behave as no operations if a debugger is not connected and stop the wave if executed with the debugger attached.

AMD_DBGAPI_WAVE_STOP_REASON_ASSERT_TRAP 

The wave stopped due to executing an assert trap instruction.

The program counter is left positioned at the assert trap instruction.

The trap instruction can be generated using the llvm.trap compiler intrinsic. See User Guide for AMDGPU Backend - Code Conventions - AMDHSA - Trap Handler ABI.

An assert trap can be used to abort the execution of the dispatches executing on a queue.

This stop reason would normally put the wave's queue into the queue error state and include the AMD_DBGAPI_EXCEPTION_WAVE_TRAP queue error reason.

AMD_DBGAPI_WAVE_STOP_REASON_TRAP 

The wave stopped due to executing an trap instruction other than the AMD_DBGAPI_WAVE_STOP_REASON_DEBUG_TRAP or AMD_DBGAPI_WAVE_STOP_REASON_ASSERT_TRAP trap instruction.

The program counter is left positioned at the trap instruction.

This stop reason would normally put the wave's queue into the queue error state and include the AMD_DBGAPI_EXCEPTION_WAVE_TRAP queue error reason.

AMD_DBGAPI_WAVE_STOP_REASON_MEMORY_VIOLATION 

The wave stopped due to a memory violation.

It indicates a non-existent page was accessed or a page without the necessary permission (such as writing to a readonly page or executing a non-execute page).

The program counter may not be positioned at the instruction that caused the memory violation as the AMD GPU can continue executing instructions after initiating a memory operation. If the architecture supports it, the amd_dbgapi_set_memory_precision can be used to control the memory exception reporting precision, but may significantly reduce performance.

This stop reason would normally put the wave's queue into the queue error state and include the AMD_DBGAPI_EXCEPTION_WAVE_MEMORY_VIOLATION queue error reason.

AMD_DBGAPI_WAVE_STOP_REASON_APERTURE_VIOLATION 

The wave stopped due to an aperture violation.

It indicates the memory address is outside the virtual address range.

The program counter may not be positioned at the instruction that caused the aperture violation as the AMD GPU can continue executing instructions after initiating a memory operation. If the architecture supports it, the amd_dbgapi_set_memory_precision can be used to control the precision, but may significantly reduce performance.

This stop reason would normally put the wave's queue into the queue error state and include the AMD_DBGAPI_EXCEPTION_WAVE_APERTURE_VIOLATION queue error reason.

AMD_DBGAPI_WAVE_STOP_REASON_ILLEGAL_INSTRUCTION 

The wave stopped due to executing an illegal instruction.

The program counter is left positioned at the illegal instruction.

This stop reason would normally put the wave's queue into the queue error state and include the AMD_DBGAPI_EXCEPTION_WAVE_ILLEGAL_INSTRUCTION queue error reason.

AMD_DBGAPI_WAVE_STOP_REASON_ECC_ERROR 

The wave stopped due to detecting an unrecoverable ECC error.

The program counter may not be positioned at the instruction that caused the memory violation as the AMD GPU can continue executing instructions after initiating a memory operation. If the architecture supports it, the amd_dbgapi_set_memory_precision can be used to control the precision, but may significantly reduce performance.

This stop reason would normally put the wave's queue into the queue error state and include the AMD_DBGAPI_EXCEPTION_WAVE_TRAP queue error reason.

AMD_DBGAPI_WAVE_STOP_REASON_FATAL_HALT 

The wave stopped after causing a hardware fatal halt.

This stop reason would normally put the wave's queue into the queue error state and include the AMD_DBGAPI_EXCEPTION_WAVE_TRAP queue error reason.

Function Documentation

◆ amd_dbgapi_process_wave_list()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_process_wave_list ( amd_dbgapi_process_id_t  process_id,
size_t *  wave_count,
amd_dbgapi_wave_id_t **  waves,
amd_dbgapi_changed_t changed 
)

Return the list of existing waves.

The order of the wave handles in the list is unspecified and can vary between calls.

Parameters
[in]process_idIf AMD_DBGAPI_PROCESS_NONE then the wave list for all processes is requested. Otherwise, the wave list of process process_id is requested.
[out]wave_countThe number of waves executing in the process.
[out]wavesIf changed is not NULL and the wave list of all of the processes requested have not changed since the last call(s) to amd_dbgapi_process_wave_list for each of them, then return NULL. Otherwise, return a pointer to an array of amd_dbgapi_wave_id_t with wave_count elements. It is allocated by the amd_dbgapi_callbacks_s::allocate_memory callback and is owned by the client.
[in,out]changedIf NULL then left unaltered. If non-NULL, set to AMD_DBGAPI_CHANGED_NO if the list of waves for each requested process is the same as when amd_dbgapi_process_wave_list was last called for them. Otherwise, set to AMD_DBGAPI_CHANGED_YES.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully and the result is stored in changed, wave_count, and waves.
AMD_DBGAPI_STATUS_FATALA fatal error occurred. The library is left uninitialized; and changed, wave_count, and waves are unaltered.
AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZEDThe library is not initialized. The library is left uninitialized; and wave_count, waves, and changed are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_IDprocess_id is invalid. wave_count, waves, and unchanged are unaltered.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTwave_count or waves are NULL, or changed is invalid. wave_count, waves, and changed are unaltered.
AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACKThis will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate waves returns NULL. wave_count, waves, and changed are unaltered.

◆ amd_dbgapi_wave_get_info()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_wave_get_info ( amd_dbgapi_wave_id_t  wave_id,
amd_dbgapi_wave_info_t  query,
size_t  value_size,
void *  value 
)

Query information about a wave.

amd_dbgapi_wave_info_t specifies the queries supported and the type returned using the value argument.

Parameters
[in]wave_idThe handle of the wave 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_WAVE_IDwave_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_NOT_AVAILABLEThe requested information is not available. See amd_dbgapi_wave_info_t for queries that can produce this error. value is unaltered.
AMD_DBGAPI_STATUS_ERROR_WAVE_NOT_STOPPEDquery has a value of amd_dbgapi_wave_info_t that requires the wave to be stopped, but the wave is not stopped.
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_wave_resume()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_wave_resume ( amd_dbgapi_wave_id_t  wave_id,
amd_dbgapi_resume_mode_t  resume_mode,
amd_dbgapi_exceptions_t  exceptions 
)

Resume execution of a stopped wave.

The wave can be resumed normally in which case it will be in the AMD_DBGAPI_WAVE_STATE_RUN state and be available for the hardware to execute instructions. Just because it is in the run state does not mean the hardware will start executing instructions immediately as that depends on the AMD GPU hardware scheduler.

If while in the AMD_DBGAPI_WAVE_STATE_RUN state, the wave encounters something that stops its execution, or amd_dbgapi_wave_stop is used to stop the wave execution, then a AMD_DBGAPI_EVENT_KIND_WAVE_STOP event will be created.

If while in the AMD_DBGAPI_WAVE_STATE_RUN state the wave terminates, no event is created.

The wave can be resumed in single step mode in which case it will be in the AMD_DBGAPI_WAVE_STATE_SINGLE_STEP state. It is available for the hardware to execute one instruction. After completing execution of a regular instruction, a AMD_DBGAPI_EVENT_KIND_WAVE_STOP event will be created that indicates the wave has stopped. The stop reason of the wave will include AMD_DBGAPI_WAVE_STOP_REASON_SINGLE_STEP. After completing execution of a wave termination instruction, a AMD_DBGAPI_EVENT_KIND_WAVE_COMMAND_TERMINATED event will be created that indicates that the wave has terminated.

Resuming a wave in single step mode does not necessarily cause it to execute any instructions as it is up to the AMD GPU hardware scheduler to decide what waves to execute. For example, the AMD GPU hardware scheduler may not execute any instructions of a wave until other waves have terminated. If the client has stopped other waves this can prevent a wave from ever performing a single step. The client should handle this gracefully and not rely on a single step request always resulting in a AMD_DBGAPI_EVENT_KIND_WAVE_STOP event. If necessary, the client should respond to the stop events of other waves to allow them to make forward progress, and handle the single step stop request when it finally arrives. If necessary, the client can cancel the single step request by using amd_dbgapi_wave_stop and allow the user to attempt it again later when other waves have terminated.

It is an error to resume a wave that has terminated. The wave handle will be reported as invalid. It is up to the client to use amd_dbgapi_process_wave_list to determine what waves have been created and terminated. No event is reported when a wave is created or terminates.

It is an error to request a wave to resume that is not in the AMD_DBGAPI_WAVE_STATE_STOP state, or is in the AMD_DBGAPI_WAVE_STATE_STOP state but the AMD_DBGAPI_EVENT_KIND_WAVE_STOP event that put it in the stop state has not yet been completed using the amd_dbgapi_event_processed operation. Therefore, it is not allowed to execute multiple resume requests as all but the first one will give an error.

It also means it is an error to resume a wave that has already stopped, but whose AMD_DBGAPI_EVENT_KIND_WAVE_STOP event has not yet been returned by amd_dbgapi_process_next_pending_event, since the wave is still in the AMD_DBGAPI_WAVE_STATE_RUN state. The AMD_DBGAPI_EVENT_KIND_WAVE_STOP must be processed first.

Since a resume request can only be sent to a wave that has stopped, there is no issue of the wave terminating while making the request. However, the wave may terminate after being resumed. Except for single stepping the wave termination instruction described above, no event is reported when the wave terminates.

Resuming a wave that is in the halt state or belongs to a queue that is in the queue error state will not result in it executing any further instructions. Resuming a wave in single step mode that does not belong to a queue that is in the queue error state will therefore not report a AMD_DBGAPI_EVENT_KIND_WAVE_STOP event that includes the AMD_DBGAPI_WAVE_STOP_REASON_SINGLE_STEP until the wave is no longer in the halt state.

Resuming a wave in single step mode that does belong to a queue that is in the queue error state, or if the queue enters the queue error state after the wave has been resumed in single step mode but before it actually executes an instruction, will report a AMD_DBGAPI_EVENT_KIND_WAVE_COMMAND_TERMINATED event to indicate that the single step request has been cancelled. Waves in such queues are inhibited from executing any further instructions. The application can delete the queue, which will result in all the associated waves to also be deleted, and then create a new queue.

A wave may stop with stop reasons that would normally cause the inferior's runtime to put the queue into the queue error state (see amd_dbgapi_wave_stop_reasons_t). However, when the AMD_DBGAPI_EVENT_KIND_WAVE_STOP event is reported, the inferior's runtime will not have been notified, and so the exception will not have caused the queue to enter the queue error state. This allows the user to inspect the wave state before the inferior's runtime may cause the queue and all its waves to be deleted.

In order to deliver the stop reason exceptions to the inferior's runtime, the client can resume the wave and specify the exceptions using the exceptions argument. The client may use AMD_DBGAPI_EXCEPTION_NONE so no exceptions are delivered, effectively ignoring the exceptions, or the client may pass different exceptions. The client may also pass exceptions to any wave even if it did not stop with a stop reason that includes any exceptions. Note that resuming a wave and ignoring exceptions may result in unpredictable behavior. For example, the AMD_DBGAPI_WAVE_STOP_REASON_ASSERT_TRAP stop reason assumes that execution will not be continued, and so the following bytes may not be legal instructions, or may be unrelated instructions.

Parameters
[in]wave_idThe wave being requested to resume.
[in]resume_modeIf AMD_DBGAPI_RESUME_MODE_NORMAL, then resume normal execution of the wave. If AMD_DBGAPI_RESUME_MODE_SINGLE_STEP, then resume the wave in single step mode.
[in]exceptionsIf AMD_DBGAPI_EXCEPTION_NONE, indicates the wave execution is resumed without delivering any exceptions. Any other value of amd_dbgapi_exceptions_t causes the wave to be put in the halt state and the inferior's runtime notified of the specified exceptions. The inferior's runtime will put the wave's queue into the queue error state such that the queue's AMD_DBGAPI_QUEUE_INFO_ERROR_REASON query will include the exceptions specified by exceptions. See AMD_DBGAPI_QUEUE_STATE_ERROR for information in the events created when a queue is put in the queue error state.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully and the wave will either terminate or be stopped. In either case a AMD_DBGAPI_EVENT_KIND_WAVE_STOP event will be reported.
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 wave is resumed.
AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_IDwave_id is invalid. No wave is resumed.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTresume_mode is invalid or exceptions does not contain only wave exceptions. No wave is resumed.
AMD_DBGAPI_STATUS_ERROR_WAVE_NOT_STOPPEDwave_id is not stopped. The wave remains running.
AMD_DBGAPI_STATUS_ERROR_WAVE_NOT_RESUMABLEThe event that put wave_id in the stop state has not yet been completed using the amd_dbgapi_event_processed operation.
AMD_DBGAPI_STATUS_ERROR_RESUME_DISPLACED_STEPPINGwave_id is stopped and has an associated displaced stepping buffer. The resume_mode is either not AMD_DBGAPI_RESUME_MODE_SINGLE_STEP, or the wave_id has already been single stepped by one instruction and so amd_dbgapi_displaced_stepping_complete must be used before the wave can be resumed.

◆ amd_dbgapi_wave_stop()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_wave_stop ( amd_dbgapi_wave_id_t  wave_id)

Request a wave to stop executing.

The wave may or may not immediately stop. If the wave does not immediately stop, the stop request is termed outstanding until the wave does stop or the wave terminates before stopping. When the wave does stop it will create a AMD_DBGAPI_EVENT_KIND_WAVE_STOP event. If the wave terminates before stopping it will create a AMD_DBGAPI_EVENT_KIND_WAVE_COMMAND_TERMINATED event.

A process in the AMD_DBGAPI_PROGRESS_NO_FORWARD progress mode will report the AMD_DBGAPI_EVENT_KIND_WAVE_STOP or AMD_DBGAPI_EVENT_KIND_WAVE_COMMAND_TERMINATED event. It is not necessary to change the progress mode to AMD_DBGAPI_PROGRESS_NORMAL for these events to be reported.

It is not necessary for the process AMD_DBGAPI_PROGRESS_NO_FORWARD

It is an error to request a wave to stop that has terminated. The wave handle will be reported as invalid. It is up to the client to use amd_dbgapi_process_wave_list to determine what waves have been created and terminated. No event is reported when a wave is created or terminates.

It is an error to request a wave to stop that is already in the AMD_DBGAPI_WAVE_STATE_STOP state.

It is an error to request a wave to stop for which there is an outstanding amd_dbgapi_wave_stop request.

Sending a stop request to a wave that has already stopped, but whose AMD_DBGAPI_EVENT_KIND_WAVE_STOP event has not yet been returned by amd_dbgapi_process_next_pending_event, is allowed since the wave is still in the AMD_DBGAPI_WAVE_STATE_RUN state. In this case the wave is not affected and the already existing AMD_DBGAPI_EVENT_KIND_WAVE_STOP will notify the client that the stop request has completed. The client must be prepared that a wave may stop for other reasons in response to a stop request. It can use the AMD_DBGAPI_WAVE_INFO_STOP_REASON query to determine if there are other reason(s). See AMD_DBGAPI_WAVE_STATE_STOP for more information.

Sending a stop request to a wave that is in the AMD_DBGAPI_WAVE_STATE_SINGLE_STEP state will attempt to stop the wave and either report a AMD_DBGAPI_EVENT_KIND_WAVE_STOP or AMD_DBGAPI_EVENT_KIND_WAVE_COMMAND_TERMINATED event. If the wave did stop, the setting of the AMD_DBGAPI_WAVE_STOP_REASON_SINGLE_STEP stop reason will indicate whether the wave completed the single step. If the single step does complete, but terminates the wave, then AMD_DBGAPI_EVENT_KIND_WAVE_COMMAND_TERMINATED will be reported.

Sending a stop request to a wave that is present at the time of the request, and does stop, will result in a AMD_DBGAPI_EVENT_KIND_WAVE_STOP event.

Sending a stop request to a wave that is present at the time of the request, but terminates before completing the stop request, will result in a AMD_DBGAPI_EVENT_KIND_WAVE_COMMAND_TERMINATED event.

Parameters
[in]wave_idThe wave being requested to stop.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully and the wave will either report a AMD_DBGAPI_EVENT_KIND_WAVE_STOP or AMD_DBGAPI_EVENT_KIND_WAVE_COMMAND_TERMINATED event.
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 wave is stopped.
AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_IDwave_id is invalid. No wave is stopped.
AMD_DBGAPI_STATUS_ERROR_WAVE_STOPPEDwave_id is already stopped. The wave remains stopped.
AMD_DBGAPI_STATUS_ERROR_WAVE_OUTSTANDING_STOPThe wave already has an outstanding stop request. This stop request is ignored and the previous stop request continues to stop the wave.