233 lines
11 KiB
C
233 lines
11 KiB
C
/*
|
|
* Copyright (c) 2019-2021, NVIDIA CORPORATION. All rights reserved.
|
|
*
|
|
* NVIDIA CORPORATION and its licensors retain all intellectual property
|
|
* and proprietary rights in and to this software, related documentation
|
|
* and any modifications thereto. Any use, reproduction, disclosure or
|
|
* distribution of this software and related documentation without an express
|
|
* license agreement from NVIDIA CORPORATION is strictly prohibited.
|
|
*/
|
|
|
|
/*
|
|
* █████ █████ ██████ ████ ████ ███████ ████ ██████ ██ ██
|
|
* ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
|
|
* ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
|
|
* ██████ ████ ██ ████ █████ ██ ██ ██ ██████ ██ ███████
|
|
* ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
|
|
* ██ ██ ██ ██ █████ ██ ██ ██ ██ ██ ██ ██ ██ ██ DEBUGGER
|
|
* ██ ██
|
|
* ████████████████████████████████████████████████████████ ██ █ ██ ████████████
|
|
*
|
|
*
|
|
* HOW TO USE AFTERMATH GPU CRASH DUMP COLLECTION:
|
|
* -----------------------------------------------
|
|
*
|
|
* 1) Call 'GFSDK_Aftermath_EnableGpuCrashDumps', to enable GPU crash dump collection.
|
|
* This must be done before any other library calls are made and before any D3D
|
|
* device is created by the application.
|
|
*
|
|
* With this call the application can register a callback function that is invoked
|
|
* with the GPU crash dump data once a TDR/hang occurs. In addition, it is also
|
|
* possible to provide optional callback functions for collecting shader debug
|
|
* information and for providing additional descriptive data from the application to
|
|
* include in the crash dump.
|
|
*
|
|
* Enabling GPU crash dumps will also override any settings from an also active
|
|
* Nsight Graphics GPU crash dump monitor for the calling process.
|
|
*
|
|
*
|
|
* 2) On DX11/DX12, call 'GFSDK_Aftermath_DXxx_Initialize', to initialize the library and
|
|
* to enable additional Aftermath features that will affect the data captured in the
|
|
* GPU crash dumps, such as Aftermath event markers; automatic call stack markers for
|
|
* all draw calls, compute dispatches, ray dispatches, or copy operations; resource
|
|
* tracking; or shader debug information. See GFSDK_Aftermath.h for more details.
|
|
*
|
|
* On Vulkan use the VK_NV_device_diagnostics_config extension to enable additional
|
|
* Aftermath features, such as automatic call stack markers for all draw calls, compute
|
|
* dispatches, ray dispatches, or copy operations; resource tracking; or shader debug
|
|
* information. See GFSDK_Aftermath.h for more details.
|
|
*
|
|
*
|
|
* 4) Before the application shuts down, call 'GFSDK_Aftermath_DisableGpuCrashDumps' to
|
|
* disable GPU crash dump collection.
|
|
*
|
|
* Disabling GPU crash dumps will also re-establish any settings from an also active
|
|
* Nsight Graphics GPU crash dump monitor for the calling process.
|
|
*
|
|
*
|
|
* OPTIONAL:
|
|
*
|
|
* o) (Optional) Instrument the application with event markers as described in
|
|
* GFSDK_Aftermath.h.
|
|
* o) (Optional, D3D12) Register D3D12 resource pointers with Aftermath as described in
|
|
* GFSDK_Aftermath.h.
|
|
* o) (Optional) To disable all GPU crash dump functionality at runtime:
|
|
* On Windows, set the registry key: 'HKEY_CURRENT_USER\Software\NVIDIA Corporation\Nsight Aftermath\ForceOff'.
|
|
* On Linux, set environment 'NV_AFTERMATH_FORCE_OFF'.
|
|
*
|
|
*
|
|
* PERFORMANCE TIPS:
|
|
*
|
|
* o) Enabling shader debug information creation will introduce shader compile time
|
|
* overhead as well as memory overhead for handling the debug information.
|
|
*
|
|
* o) User event markers cause considerable overhead and should be used very carefully.
|
|
* Using automatic callstack markers for draw calls, compute dispatches, ray dispatches,
|
|
* and copy operations may be a less costly alternative to injecting an event marker for
|
|
* every draw call. However, they also do not come for free and using them should be
|
|
* also considered carefully.
|
|
*
|
|
*/
|
|
|
|
#ifndef GFSDK_Aftermath_GpuCrashDump_H
|
|
#define GFSDK_Aftermath_GpuCrashDump_H
|
|
|
|
#include "GFSDK_Aftermath_Defines.h"
|
|
|
|
#pragma pack(push, 8)
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
// Flags to configure for which graphisc APIs to enable GPU crash dumps
|
|
GFSDK_AFTERMATH_DECLARE_ENUM(GpuCrashDumpWatchedApiFlags)
|
|
{
|
|
// Default setting
|
|
GFSDK_Aftermath_GpuCrashDumpWatchedApiFlags_None = 0x0,
|
|
|
|
// Enable GPU crash dump tracking for the DX API
|
|
GFSDK_Aftermath_GpuCrashDumpWatchedApiFlags_DX = 0x1,
|
|
|
|
// Enable GPU crash dump tracking for the Vulkan API
|
|
GFSDK_Aftermath_GpuCrashDumpWatchedApiFlags_Vulkan = 0x2,
|
|
};
|
|
|
|
// Flags to configure GPU crash dump-specific Aftermath features
|
|
GFSDK_AFTERMATH_DECLARE_ENUM(GpuCrashDumpFeatureFlags)
|
|
{
|
|
// Default settings
|
|
GFSDK_Aftermath_GpuCrashDumpFeatureFlags_Default = 0x0,
|
|
|
|
// Defer shader debug information callbacks until an actual GPU crash
|
|
// dump is generated and also provide shader debug information
|
|
// for the shaders related to the crash dump only.
|
|
// Note: using this option will increase the memory footprint of the
|
|
// application.
|
|
GFSDK_Aftermath_GpuCrashDumpFeatureFlags_DeferDebugInfoCallbacks = 0x1,
|
|
};
|
|
|
|
// Key definitions for user-defined GPU crash dump description
|
|
GFSDK_AFTERMATH_DECLARE_ENUM(GpuCrashDumpDescriptionKey)
|
|
{
|
|
// Predefined key for application name
|
|
GFSDK_Aftermath_GpuCrashDumpDescriptionKey_ApplicationName = 0x00000001,
|
|
|
|
// Predefined key for application version
|
|
GFSDK_Aftermath_GpuCrashDumpDescriptionKey_ApplicationVersion = 0x00000002,
|
|
|
|
// Base key for creating user-defined key-value pairs.
|
|
// Any value >= GFSDK_Aftermath_GpuCrashDumpDescriptionKey_UserDefined
|
|
// will create a user-defined key-value pair.
|
|
GFSDK_Aftermath_GpuCrashDumpDescriptionKey_UserDefined = 0x00010000,
|
|
};
|
|
|
|
// Function for adding user-defined description key-value pairs.
|
|
// Key must be one of the predefined keys of GFSDK_Aftermath_GpuCrashDumpDescriptionKey
|
|
// or a user-defined key based on GFSDK_Aftermath_GpuCrashDumpDescriptionKey_UserDefined.
|
|
// All keys greater than the last predefined key in GFSDK_Aftermath_GpuCrashDumpDescriptionKey
|
|
// and smaller than GFSDK_Aftermath_GpuCrashDumpDescriptionKey_UserDefined are
|
|
// considered illegal and ignored.
|
|
typedef void (GFSDK_AFTERMATH_CALL *PFN_GFSDK_Aftermath_AddGpuCrashDumpDescription)(uint32_t key, const char* value);
|
|
|
|
// GPU crash dump callback definitions.
|
|
// NOTE: Except for the pUserData pointer, all pointer values passed to the
|
|
// callbacks are only valid for the duration of the call! An implementation
|
|
// must make copies of the data, if it intends to store it beyond that.
|
|
typedef void (GFSDK_AFTERMATH_CALL *PFN_GFSDK_Aftermath_GpuCrashDumpCb)(const void* pGpuCrashDump, const uint32_t gpuCrashDumpSize, void* pUserData);
|
|
typedef void (GFSDK_AFTERMATH_CALL *PFN_GFSDK_Aftermath_ShaderDebugInfoCb)(const void* pShaderDebugInfo, const uint32_t shaderDebugInfoSize, void* pUserData);
|
|
typedef void (GFSDK_AFTERMATH_CALL *PFN_GFSDK_Aftermath_GpuCrashDumpDescriptionCb)(PFN_GFSDK_Aftermath_AddGpuCrashDumpDescription addValue, void* pUserData);
|
|
|
|
/////////////////////////////////////////////////////////////////////////
|
|
// GFSDK_Aftermath_EnableGpuCrashDumps
|
|
// ---------------------------------
|
|
//
|
|
// apiVersion;
|
|
// Must be set to GFSDK_Aftermath_Version_API. Used for checking against library
|
|
// version.
|
|
//
|
|
// watchedApis;
|
|
// Controls which graphics APIs to watch for crashes. A combination (with OR) of
|
|
// GFSDK_Aftermath_GpuCrashDumpWatchedApiFlags.
|
|
//
|
|
// flags;
|
|
// Controls GPU crash dump specific behavior. A combination (with OR) of
|
|
// GFSDK_Aftermath_GpuCrashDumpFeatureFlags.
|
|
//
|
|
// gpuCrashDumpCb;
|
|
// Callback function to be called when new GPU crash dump data is available.
|
|
// Callback is free-threaded, ensure the provided function is thread-safe.
|
|
//
|
|
// shaderDebugInfoCb;
|
|
// Callback function to be called when new shader debug information data is
|
|
// available.
|
|
// Callback is free-threaded, ensure the provided function is thread-safe.
|
|
// Optional, can be NULL.
|
|
// Note: if not using GFSDK_Aftermath_GpuCrashDumpFeatureFlags_DeferDebugInfoCallbacks
|
|
// shaderDebugInfoCb will be invoked for every shader compilation trigegred by the
|
|
// application, even if there will be never an invocation of gpuCrashDumpCb.
|
|
//
|
|
// descriptionCb;
|
|
// Callback function that allows the application to provide additional
|
|
// descriptive values to be include in crash dumps. This will be called
|
|
// before gpuCrashDumpCb.
|
|
// Callback is free-threaded, ensure the provided function is thread-safe.
|
|
// Optional, can be NULL.
|
|
//
|
|
// pUserData;
|
|
// User data made available in the callbacks.
|
|
//
|
|
//// DESCRIPTION;
|
|
// Device independent initialization call to enable Aftermath GPU crash dump
|
|
// creation. Overrides any settings from an also active GPU crash dump monitor
|
|
// for this process! This function must be called before any D3D device is
|
|
// created by the application.
|
|
//
|
|
/////////////////////////////////////////////////////////////////////////
|
|
GFSDK_Aftermath_API GFSDK_Aftermath_EnableGpuCrashDumps(
|
|
GFSDK_Aftermath_Version apiVersion,
|
|
uint32_t watchedApis,
|
|
uint32_t flags,
|
|
PFN_GFSDK_Aftermath_GpuCrashDumpCb gpuCrashDumpCb,
|
|
PFN_GFSDK_Aftermath_ShaderDebugInfoCb shaderDebugInfoCb,
|
|
PFN_GFSDK_Aftermath_GpuCrashDumpDescriptionCb descriptionCb,
|
|
void* pUserData);
|
|
|
|
/////////////////////////////////////////////////////////////////////////
|
|
// GFSDK_Aftermath_DisableGpuCrashDumps
|
|
// ---------------------------------
|
|
//
|
|
//// DESCRIPTION;
|
|
// Device independent call to disable Aftermath GPU crash dump creation.
|
|
// Re-enables settings from an also active GPU crash dump monitor for
|
|
// the current process!
|
|
//
|
|
/////////////////////////////////////////////////////////////////////////
|
|
GFSDK_Aftermath_API GFSDK_Aftermath_DisableGpuCrashDumps();
|
|
|
|
/////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// NOTE: Function table provided - if dynamic loading is preferred.
|
|
//
|
|
/////////////////////////////////////////////////////////////////////////
|
|
GFSDK_Aftermath_PFN(GFSDK_AFTERMATH_CALL *PFN_GFSDK_Aftermath_EnableGpuCrashDumps)(GFSDK_Aftermath_Version apiVersion, uint32_t watchedApis, uint32_t flags, PFN_GFSDK_Aftermath_GpuCrashDumpCb gpuCrashDumpCb, PFN_GFSDK_Aftermath_ShaderDebugInfoCb shaderDebugInfoCb, PFN_GFSDK_Aftermath_GpuCrashDumpDescriptionCb descriptionCb, void* pUserData);
|
|
GFSDK_Aftermath_PFN(GFSDK_AFTERMATH_CALL *PFN_GFSDK_Aftermath_DisableGpuCrashDumps)();
|
|
|
|
#ifdef __cplusplus
|
|
} // extern "C"
|
|
#endif
|
|
|
|
#pragma pack(pop)
|
|
|
|
#endif // GFSDK_Aftermath_GpuCrashDump_H
|