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... | |
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_64 |
| 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
◆ 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 |
| AMD_DBGAPI_WAVE_INFO_STOP_REASON | Return the reason the wave stopped as a bit set. The type of this attribute is |
| 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_WORKGROUP | Return the workgroup to which this wave belongs. The type of this attribute is amd_dbgapi_workgroup_id_t. If the workgroup 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_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 |
| AMD_DBGAPI_WAVE_INFO_WORKGROUP_COORD | The wave workgroup coordinate in the dispatch grid dimensions. The type of this attribute is 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_WORKGROUP | The wave's number in the workgroup. The type of this attribute is 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 |
◆ 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 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 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 a 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_id If AMD_DBGAPI_PROCESS_NONE then the wave list for all processes is requested. Otherwise, the wave list of process process_idis requested.[out] wave_count The number of waves executing in the process. [out] waves If changedis 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 withwave_countelements. It is allocated by the amd_dbgapi_callbacks_s::allocate_memory callback and is owned by the client.[in,out] changed If 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_SUCCESS The function has been executed successfully and the result is stored in changed,wave_count, andwaves.AMD_DBGAPI_STATUS_FATAL A fatal error occurred. The library is left uninitialized; and changed,wave_count, andwavesare unaltered.AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED The library is not initialized. The library is left uninitialized; and wave_count,waves, andchangedare unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_ID process_idis invalid.wave_count,waves, andunchangedare unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT wave_countorwavesare NULL, orchangedis invalid.wave_count,waves, andchangedare unaltered.AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACK This will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate wavesreturns NULL.wave_count,waves, andchangedare 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_id The handle of the wave 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 valueis unaltered.AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED The library is not initialized. The library is left uninitialized and valueis unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_ID wave_idis invalid.valueis unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT valueis NULL orqueryis invalid.valueis unaltered.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY value_sizedoes not match the size of thequeryresult.valueis unaltered.AMD_DBGAPI_STATUS_ERROR_NOT_AVAILABLE Therequested information is not available. See amd_dbgapi_wave_info_t for queries that can produce this error.valueis unaltered.AMD_DBGAPI_STATUS_ERROR_WAVE_NOT_STOPPED queryhas 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_CALLBACK This will be reported if the amd_dbgapi_callbacks_s::allocate_memory callback used to allocate valuereturns NULL.valueis 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_id The wave being requested to resume. [in] resume_mode If 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] exceptions If 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_SUCCESS The 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_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 wave is resumed. AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_ID wave_idis invalid. No wave is resumed.AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT resume_modeis invalid orexceptionsdoes not contain only wave exceptions. No wave is resumed.AMD_DBGAPI_STATUS_ERROR_WAVE_NOT_STOPPED wave_idis not stopped. The wave remains running.AMD_DBGAPI_STATUS_ERROR_WAVE_NOT_RESUMABLE The event that put wave_idin the stop state has not yet been completed using the amd_dbgapi_event_processed operation.AMD_DBGAPI_STATUS_ERROR_RESUME_DISPLACED_STEPPING wave_idis stopped and has an associated displaced stepping buffer. Theresume_modeis either not AMD_DBGAPI_RESUME_MODE_SINGLE_STEP, or thewave_idhas 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 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_id The wave being requested to stop.
- Return values
-
AMD_DBGAPI_STATUS_SUCCESS The 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_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 wave is stopped. AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_ID wave_idis invalid. No wave is stopped.AMD_DBGAPI_STATUS_ERROR_WAVE_STOPPED wave_idis already stopped. The wave remains stopped.AMD_DBGAPI_STATUS_ERROR_WAVE_OUTSTANDING_STOP The wave already has an outstanding stop request. This stop request is ignored and the previous stop request continues to stop the wave.