Generating a core dump of a process

Generating a core dump of a process#

AMD DBG API: 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 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.