Generating a core dump of a process#
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:
- The client suspends the execution of all host threads.
- The client sets the progress mode for the process to AMD_DBGAPI_PROGRESS_NO_FORWARD and stops wave creation.
- The client calls amd_dbgapi_process_freeze to suspend execution on the agents.
- 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.
- The client includes in the core dump all the information required to form a core dump of the host process.
- The client unfreezes the process using amd_dbgapi_process_unfreeze.
- 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 byprocess_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.