AMD_DBGAPI: Generating a core dump of a process

AMD_DBGAPI 0.77.4

Loading...
Searching...
No Matches
Functions
Generating a core dump of a process
Processes

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

Collaboration diagram for Generating a core dump of a process:

## 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`.
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`.

## 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_id | The client handle of the process to freeze.

Return values

  AMD_DBGAPI_STATUS_SUCCESS | The function has been executed successfully and the process is in the frozen state.
  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.
  AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_ID | `process_id` is invalid.
  AMD_DBGAPI_STATUS_ERROR_INCOMPATIBLE_PROCESS_STATE | if 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_FROZEN | The 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_id | The client handle of the process to unfreeze.

Return values

  AMD_DBGAPI_STATUS_SUCCESS | The function has been executed successfully and the process is unfrozen.
  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.
  AMD_DBGAPI_STATUS_ERROR_INVALID_PROCESS_ID | `process_id` is invalid.
  AMD_DBGAPI_STATUS_ERROR_PROCESS_NOT_FROZEN | The process `process_id` is not frozen. The process is not changed.