How to Edit Crash Dumps

The Nsight Aftermath SDK provides a crash dump editing API that allows applications to modify GPU crash dump data after it has been generated. This is useful for post-processing crash dumps, for example to resolve event marker data or to add additional description key-value pairs. To use the crash dump editing API, include the GFSDK_Aftermath_GpuCrashDumpEditing.h header file.

The editing workflow consists of the following steps:

1. Create an editor object from raw crash dump data using GFSDK_Aftermath_GpuCrashDump_CreateEditor.

2. Call one or more editing functions to modify the crash dump:

   • GFSDK_Aftermath_GpuCrashDumpEditor_ResolveEventMarkers to resolve event marker data using a callback.

   • GFSDK_Aftermath_GpuCrashDumpEditor_AddDescription to add description key-value pairs.

3. Retrieve the modified crash dump data using GFSDK_Aftermath_GpuCrashDumpEditor_GetCrashDumpData.

4. Destroy the editor object using GFSDK_Aftermath_GpuCrashDump_DestroyEditor.

Here is an example that creates an editor, resolves event markers, adds a description, and retrieves the edited crash dump data:

void GpuCrashTracker::EditCrashDump(const void* pGpuCrashDump, const uint32_t gpuCrashDumpSize)
{
    // Create an editor object from the crash dump data.
    GFSDK_Aftermath_GpuCrashDump_Editor editor = {};
    AFTERMATH_CHECK_ERROR(GFSDK_Aftermath_GpuCrashDump_CreateEditor(
        GFSDK_Aftermath_Version_API,
        pGpuCrashDump,
        gpuCrashDumpSize,
        &editor));

    // Resolve event markers. The callback is invoked for each event marker
    // in the crash dump. Calling the resolveMarker functor inside the callback
    // replaces the marker data; not calling it keeps the existing data.
    AFTERMATH_CHECK_ERROR(GFSDK_Aftermath_GpuCrashDumpEditor_ResolveEventMarkers(
        editor,
        ResolveMarkerCallback,
        this));

    // Add additional description key-value pairs.
    AFTERMATH_CHECK_ERROR(GFSDK_Aftermath_GpuCrashDumpEditor_AddDescription(
        editor,
        GFSDK_Aftermath_GpuCrashDumpDescriptionKey_UserDefined + 10,
        "Post-processed by crash dump editing API"));

    // Query the size of the edited crash dump data.
    uint32_t editedSize = 0;
    AFTERMATH_CHECK_ERROR(GFSDK_Aftermath_GpuCrashDumpEditor_GetCrashDumpData(
        editor,
        nullptr,
        0,
        &editedSize));

    // Retrieve the edited crash dump data.
    std::vector<uint8_t> editedDump(editedSize);
    AFTERMATH_CHECK_ERROR(GFSDK_Aftermath_GpuCrashDumpEditor_GetCrashDumpData(
        editor,
        editedDump.data(),
        editedSize,
        &editedSize));

    // Write the edited crash dump to file.
    WriteGpuCrashDumpToFile(editedDump.data(), editedSize);

    // Destroy the editor object.
    AFTERMATH_CHECK_ERROR(GFSDK_Aftermath_GpuCrashDump_DestroyEditor(editor));
}

Note

The ResolveEventMarkers editing function uses the same PFN_GFSDK_Aftermath_ResolveMarkerCb callback type as GFSDK_Aftermath_EnableGpuCrashDumps. However, unlike during driver-side crash dump generation where individual event marker payloads may be truncated to 1024 bytes, post-generation editing via this API does not impose an additional size limit. To avoid truncation at generation time, prefer application-managed markers by setting markerDataSize = 0 in GFSDK_Aftermath_SetEventMarker and providing the full payload via the editor.