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

Generating a core dump of a process

Generating a core dump of a process#

AMD DBG API: Generating a core dump of a process
Functions
Generating a core dump of a process
Processes

Operations related to generating and using core dumps. More...

Functions

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_process_freeze (amd_dbgapi_process_id_t process_id) AMD_DBGAPI_VERSION_0_76
 Freeze the process identified by process_id. More...
 
amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_process_unfreeze (amd_dbgapi_process_id_t process_id) AMD_DBGAPI_VERSION_0_76
 Unfreeze the process identified by process_id. More...
 

Detailed Description

Operations related to generating and using core dumps.

When the client needs to generate a core dump of a process, the following steps are followed:

  1. The client suspends the execution of all host threads.
  2. The client sets the progress mode for the process to AMD_DBGAPI_PROGRESS_NO_FORWARD and stops wave creation.
  3. The client calls amd_dbgapi_process_freeze to suspend execution on the agents.
  4. The client queries AMD_DBGAPI_PROCESS_INFO_CORE_STATE and stores the content of the returned buffer in a note in the generated core file.
  5. The client includes in the core dump all the information required to form a core dump of the host process.
  6. The client unfreezes the process using amd_dbgapi_process_unfreeze.
  7. The client can set progress to AMD_DBGAPI_PROGRESS_NORMAL and resume the execution of host threads as desired.

Function Documentation

◆ amd_dbgapi_process_freeze()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_process_freeze ( amd_dbgapi_process_id_t  process_id)

Freeze the process identified by process_id.

The library ensures that all queues belonging to process process_id are stopped. All waves are stopped and left in a state suitable to be discovered by another instance of the library. Any cached updates to memory or registers are flushed.

It is required that the client sets the process's progress to AMD_DBGAPI_PROGRESS_NO_FORWARD and the wave creation mode to AMD_DBGAPI_WAVE_CREATION_STOP before calling this procedure.

It is expected that all displaced stepping buffers are disabled before calling this operation. If displaced stepping buffers are still enabled when performing this operation, then another instance of the library will see an invalid program counter for the associated wave(s).

It is expected that all host threads are suspended by the client before calling this method as executing threads might create queues and submit dispatches. If any thread is running on the host process, the behavior and state of the library are undefined.

Parameters
[in]process_idThe client handle of the process to freeze.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully and the process is in the frozen state.
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.
AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_IDprocess_id is invalid.
AMD_DBGAPI_STATUS_ERROR_INCOMPATIBLE_PROCESS_STATEif either progress mode for the process identified by process_id is not AMD_DBGAPI_PROGRESS_NO_FORWARD or if wave creation mode for the process identified by process_id is not AMD_DBGAPI_WAVE_CREATION_STOP.
AMD_DBGAPI_STATUS_ERROR_PROCESS_ALREADY_FROZENThe process process_id is already frozen. The process is not changed.

◆ amd_dbgapi_process_unfreeze()

amd_dbgapi_status_t AMD_DBGAPI amd_dbgapi_process_unfreeze ( amd_dbgapi_process_id_t  process_id)

Unfreeze the process identified by process_id.

After calling this, the library is allowed to keep writes to registers and memory in an internal cache until the effects are needed to resume execution.

Parameters
[in]process_idThe client handle of the process to unfreeze.
Return values
AMD_DBGAPI_STATUS_SUCCESSThe function has been executed successfully and the process is unfrozen.
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.
AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_IDprocess_id is invalid.
AMD_DBGAPI_STATUS_ERROR_PROCESS_NOT_FROZENThe process process_id is not frozen. The process is not changed.