This page contains changes for a test release of ROCm. Read the latest Linux release of ROCm documentation for your production environments.

Status Codes

Status Codes#

AMD DBG API: Status Codes
Status Codes

Most operations return a status code to indicate success or error. More...

Enumerations

enum  amd_dbgapi_status_t {
  AMD_DBGAPI_STATUS_SUCCESS = 0 , AMD_DBGAPI_STATUS_ERROR = -1 , AMD_DBGAPI_STATUS_FATAL = -2 , AMD_DBGAPI_STATUS_ERROR_NOT_IMPLEMENTED = -3 ,
  AMD_DBGAPI_STATUS_ERROR_NOT_AVAILABLE = -4 , AMD_DBGAPI_STATUS_ERROR_NOT_SUPPORTED = -5 , AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT = -6 , AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY = -7 ,
  AMD_DBGAPI_STATUS_ERROR_ALREADY_INITIALIZED = -8 , AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED = -9 , AMD_DBGAPI_STATUS_ERROR_RESTRICTION = -10 , AMD_DBGAPI_STATUS_ERROR_ALREADY_ATTACHED = -11 ,
  AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_ID = -12 , AMD_DBGAPI_STATUS_ERROR_ILLEGAL_INSTRUCTION = -13 , AMD_DBGAPI_STATUS_ERROR_INVALID_CODE_OBJECT_ID = -14 , AMD_DBGAPI_STATUS_ERROR_INVALID_ELF_AMDGPU_MACHINE = -15 ,
  AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_ID = -16 , AMD_DBGAPI_STATUS_ERROR_PROCESS_EXITED = -17 , AMD_DBGAPI_STATUS_ERROR_INVALID_AGENT_ID = -18 , AMD_DBGAPI_STATUS_ERROR_INVALID_QUEUE_ID = -19 ,
  AMD_DBGAPI_STATUS_ERROR_INVALID_DISPATCH_ID = -20 , AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_ID = -21 , AMD_DBGAPI_STATUS_ERROR_WAVE_NOT_STOPPED = -22 , AMD_DBGAPI_STATUS_ERROR_WAVE_STOPPED = -23 ,
  AMD_DBGAPI_STATUS_ERROR_WAVE_OUTSTANDING_STOP = -24 , AMD_DBGAPI_STATUS_ERROR_WAVE_NOT_RESUMABLE = -25 , AMD_DBGAPI_STATUS_ERROR_INVALID_DISPLACED_STEPPING_ID = -26 , AMD_DBGAPI_STATUS_ERROR_DISPLACED_STEPPING_BUFFER_NOT_AVAILABLE = -27 ,
  AMD_DBGAPI_STATUS_ERROR_DISPLACED_STEPPING_ACTIVE = -28 , AMD_DBGAPI_STATUS_ERROR_RESUME_DISPLACED_STEPPING = -29 , AMD_DBGAPI_STATUS_ERROR_INVALID_WATCHPOINT_ID = -30 , AMD_DBGAPI_STATUS_ERROR_NO_WATCHPOINT_AVAILABLE = -31 ,
  AMD_DBGAPI_STATUS_ERROR_INVALID_REGISTER_CLASS_ID = -32 , AMD_DBGAPI_STATUS_ERROR_INVALID_REGISTER_ID = -33 , AMD_DBGAPI_STATUS_ERROR_INVALID_LANE_ID = -34 , AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_CLASS_ID = -35 ,
  AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_SPACE_ID = -36 , AMD_DBGAPI_STATUS_ERROR_MEMORY_ACCESS = -37 , AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_SPACE_CONVERSION = -38 , AMD_DBGAPI_STATUS_ERROR_INVALID_EVENT_ID = -39 ,
  AMD_DBGAPI_STATUS_ERROR_INVALID_BREAKPOINT_ID = -40 , AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACK = -41 , AMD_DBGAPI_STATUS_ERROR_INVALID_CLIENT_PROCESS_ID = -42 , AMD_DBGAPI_STATUS_ERROR_SYMBOL_NOT_FOUND = -43 ,
  AMD_DBGAPI_STATUS_ERROR_REGISTER_NOT_AVAILABLE = -44 , AMD_DBGAPI_STATUS_ERROR_INVALID_WORKGROUP_ID = -45 , AMD_DBGAPI_STATUS_ERROR_INCOMPATIBLE_PROCESS_STATE = -46 , AMD_DBGAPI_STATUS_ERROR_PROCESS_FROZEN = -47 ,
  AMD_DBGAPI_STATUS_ERROR_PROCESS_ALREADY_FROZEN = -48 , AMD_DBGAPI_STATUS_ERROR_PROCESS_NOT_FROZEN = -49
}
 AMD debugger API status codes. More...
 

Functions

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_get_status_string (amd_dbgapi_status_t status, const char **status_string) AMD_DBGAPI_VERSION_0_54
 Query a textual description of a status code. More...
 

Detailed Description

Most operations return a status code to indicate success or error.

Enumeration Type Documentation

◆ amd_dbgapi_status_t

AMD debugger API status codes.

Enumerator
AMD_DBGAPI_STATUS_SUCCESS 

The function has executed successfully.

AMD_DBGAPI_STATUS_ERROR 

A generic error has occurred.

AMD_DBGAPI_STATUS_FATAL 

A fatal error has occurred.

The library encountered an error from which it cannot recover. All processes are detached. All breakpoints inserted by amd_dbgapi_callbacks_s::insert_breakpoint are attempted to be removed. All handles are invalidated. The library is left in an uninitialized state. The logging level is reset to AMD_DBGAPI_LOG_LEVEL_NONE.

To resume using the library the client must re-initialize the library; re-attach to any processes; re-fetch the list of code objects, agents, queues, dispatches, and waves; and update the state of all waves as appropriate. While in the uninitialized state the inferior processes will continue executing but any execution of a breakpoint instruction will put the queue into an error state, aborting any executing waves. Note that recovering from a fatal error most likely will require the user of the client to re-start their session.

The cause of possible fatal errors is that resources became exhausted or unique handle numbers became exhausted.

AMD_DBGAPI_STATUS_ERROR_NOT_IMPLEMENTED 

The operation is not currently implemented.

This error may be reported by any function. Check the Known Limitations and Restrictions section to determine the status of the library implementation of the interface.

AMD_DBGAPI_STATUS_ERROR_NOT_AVAILABLE 

The requested information is not available.

AMD_DBGAPI_STATUS_ERROR_NOT_SUPPORTED 

The operation is not supported.

AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT 

An invalid argument was given to the function.

AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENT_COMPATIBILITY 

An invalid combination of arguments was given to the function.

AMD_DBGAPI_STATUS_ERROR_ALREADY_INITIALIZED 

The library is already initialized.

AMD_DBGAPI_STATUS_ERROR_NOT_INITIALIZED 

The library is not initialized.

AMD_DBGAPI_STATUS_ERROR_RESTRICTION 

There is a restriction error that prevents the operation to complete.

Reasons which could prevent debugging the process include:

  • The AMD GPU driver is not installed.
  • The installed AMD GPU driver version is not compatible with the library.
  • The installed AMD GPU driver's debug support version is not compatible with the library.
  • A limitation on the number of debuggers that can be active for an AMD GPU agent has been exceeded.
  • The process has the same address space as another process to which the library is already attached. For example, attaching to a process created by the Linux vfork system call while attached to the parent process.

On some configurations, this error is returned instead of creating a core dump containing an ambiguous state.

AMD_DBGAPI_STATUS_ERROR_ALREADY_ATTACHED 

The process is already attached to the given inferior process.

AMD_DBGAPI_STATUS_ERROR_INVALID_ARCHITECTURE_ID 

The architecture handle is invalid.

AMD_DBGAPI_STATUS_ERROR_ILLEGAL_INSTRUCTION 

The bytes being disassembled are not a legal instruction.

AMD_DBGAPI_STATUS_ERROR_INVALID_CODE_OBJECT_ID 

The code object handle is invalid.

AMD_DBGAPI_STATUS_ERROR_INVALID_ELF_AMDGPU_MACHINE 

The ELF AMD GPU machine value is invalid or unsupported.

AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_ID 

The process handle is invalid.

AMD_DBGAPI_STATUS_ERROR_PROCESS_EXITED 

The native operating system process associated with a client process has exited.

AMD_DBGAPI_STATUS_ERROR_INVALID_AGENT_ID 

The agent handle is invalid.

AMD_DBGAPI_STATUS_ERROR_INVALID_QUEUE_ID 

The queue handle is invalid.

AMD_DBGAPI_STATUS_ERROR_INVALID_DISPATCH_ID 

The dispatch handle is invalid.

AMD_DBGAPI_STATUS_ERROR_INVALID_WAVE_ID 

The wave handle is invalid.

AMD_DBGAPI_STATUS_ERROR_WAVE_NOT_STOPPED 

The wave is not stopped.

AMD_DBGAPI_STATUS_ERROR_WAVE_STOPPED 

The wave is stopped.

AMD_DBGAPI_STATUS_ERROR_WAVE_OUTSTANDING_STOP 

The wave has an outstanding stop request.

AMD_DBGAPI_STATUS_ERROR_WAVE_NOT_RESUMABLE 

The wave cannot be resumed.

AMD_DBGAPI_STATUS_ERROR_INVALID_DISPLACED_STEPPING_ID 

The displaced stepping handle is invalid.

AMD_DBGAPI_STATUS_ERROR_DISPLACED_STEPPING_BUFFER_NOT_AVAILABLE 

No more displaced stepping buffers are available that are suitable for the requested wave.

AMD_DBGAPI_STATUS_ERROR_DISPLACED_STEPPING_ACTIVE 

The wave has an active displaced stepping buffer.

AMD_DBGAPI_STATUS_ERROR_RESUME_DISPLACED_STEPPING 

The wave cannot be resumed in the manner requested due to displaced stepping restrictions.

AMD_DBGAPI_STATUS_ERROR_INVALID_WATCHPOINT_ID 

The watchpoint handle is invalid.

AMD_DBGAPI_STATUS_ERROR_NO_WATCHPOINT_AVAILABLE 

No more watchpoints available.

AMD_DBGAPI_STATUS_ERROR_INVALID_REGISTER_CLASS_ID 

The register class handle is invalid.

AMD_DBGAPI_STATUS_ERROR_INVALID_REGISTER_ID 

The register handle is invalid.

AMD_DBGAPI_STATUS_ERROR_INVALID_LANE_ID 

The lane handle is invalid.

AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_CLASS_ID 

The address class handle is invalid.

AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_SPACE_ID 

The address space handle is invalid.

AMD_DBGAPI_STATUS_ERROR_MEMORY_ACCESS 

An error occurred while trying to access memory in the inferior.

AMD_DBGAPI_STATUS_ERROR_INVALID_ADDRESS_SPACE_CONVERSION 

The segment address cannot be converted to the requested address space.

AMD_DBGAPI_STATUS_ERROR_INVALID_EVENT_ID 

The event handle is invalid.

AMD_DBGAPI_STATUS_ERROR_INVALID_BREAKPOINT_ID 

The breakpoint handle is invalid.

AMD_DBGAPI_STATUS_ERROR_CLIENT_CALLBACK 

A callback to the client reported an error.

AMD_DBGAPI_STATUS_ERROR_INVALID_CLIENT_PROCESS_ID 

The client process handle is invalid.

AMD_DBGAPI_STATUS_ERROR_SYMBOL_NOT_FOUND 

The symbol was not found.

AMD_DBGAPI_STATUS_ERROR_REGISTER_NOT_AVAILABLE 

The register handle is valid, but specifies a register that is not allocated in the associated wave.

AMD_DBGAPI_STATUS_ERROR_INVALID_WORKGROUP_ID 

The workgroup handle is invalid.

AMD_DBGAPI_STATUS_ERROR_INCOMPATIBLE_PROCESS_STATE 

The current process state is not compatible with the requested operation.

AMD_DBGAPI_STATUS_ERROR_PROCESS_FROZEN 

This operation is not allowed when the process is frozen.

AMD_DBGAPI_STATUS_ERROR_PROCESS_ALREADY_FROZEN 

The process is already frozen.

AMD_DBGAPI_STATUS_ERROR_PROCESS_NOT_FROZEN 

This operation is not allowed when the process is not frozen.

Function Documentation

◆ amd_dbgapi_get_status_string()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_get_status_string ( amd_dbgapi_status_t  status,
const char **  status_string 
)

Query a textual description of a status code.

This function can be used even when the library is uninitialized.

Parameters
[in]statusStatus code.
[out]status_stringA NUL terminated string that describes the status code. The string is read only and owned by the library.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully. status_string has been updated.
AMD_DBGAPI_STATUS_ERROR_INVALID_ARGUMENTstatus is an invalid status code or status_string is NULL. status_string is unaltered.