r.GPUCrashDebugging

r.GPUCrashDebugging

#Overview

name: r.GPUCrashDebugging

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

This variable is created as a Console Variable (cvar).

It is referenced in 8 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.GPUCrashDebugging is to enable vendor-specific GPU crash analysis tools. This variable is primarily used for debugging and diagnosing GPU-related issues in Unreal Engine.

This setting variable is utilized by multiple Unreal Engine subsystems and modules, including:

  1. The RHI (Rendering Hardware Interface) module
  2. Metal RHI for Apple platforms
  3. D3D12 RHI for Windows
  4. Vulkan RHI
  5. D3D11 RHI for Windows

The value of this variable is typically set through the console or configuration files. It can also be influenced by command-line arguments such as “gpucrashdebugging”.

This variable interacts with other debugging-related variables and systems, such as:

  1. GMetalCommandBufferDebuggingEnabled (for Metal RHI)
  2. GPUCrashDebuggingModes (for D3D12)
  3. GGPUCrashDebuggingEnabled (for Vulkan)
  4. GDX11NVAfterMathEnabled (for D3D11 on NVIDIA GPUs)

Developers should be aware that:

  1. This variable is marked as ECVF_ReadOnly, meaning it should not be changed during runtime.
  2. Its behavior may differ between shipping/test builds and development builds.
  3. It can have performance implications when enabled.

Best practices when using this variable include:

  1. Enable it only when necessary for debugging GPU crashes or performance issues.
  2. Be aware of the potential performance impact in shipping builds.
  3. Use in conjunction with platform-specific debugging tools (e.g., NVAftermath for NVIDIA GPUs).
  4. Consider using more specific debug variables (e.g., r.D3D12.BreadCrumbs) for targeted debugging when possible.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEngine.ini:3427, section: [/Script/Engine.RendererSettings]

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Private/RHI.cpp:1116

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarGPUCrashDebugging(
	TEXT("r.GPUCrashDebugging"),
	0,
	TEXT("Enable vendor specific GPU crash analysis tools"),
	ECVF_ReadOnly
	);

static TAutoConsoleVariable<int32> CVarGPUCrashDump(

#Loc: <Workspace>/Engine/Source/Runtime/Apple/MetalRHI/Private/MetalCommandQueue.cpp:153

Scope: file

Source code excerpt:

                        
		// The below implies tile shaders which are necessary to order the draw calls and generate a buffer that shows what PSOs/draws ran on each tile.
		IConsoleVariable* GPUCrashDebuggingCVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.GPUCrashDebugging"));
#if UE_BUILD_SHIPPING || UE_BUILD_TEST
		GMetalCommandBufferDebuggingEnabled = (GPUCrashDebuggingCVar && GPUCrashDebuggingCVar->GetInt() != 0) || FParse::Param(FCommandLine::Get(), TEXT("metalgpudebug"));
#else
        GMetalCommandBufferDebuggingEnabled = true;
#endif
	}

#Loc: <Workspace>/Engine/Source/Runtime/Apple/MetalRHI/Private/MetalCommandQueue.cpp:210

Scope: file

Source code excerpt:

		}
            
		IConsoleVariable* GPUCrashDebuggingCVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.GPUCrashDebugging"));
#if UE_BUILD_SHIPPING || UE_BUILD_TEST
        GMetalCommandBufferDebuggingEnabled = (GPUCrashDebuggingCVar && GPUCrashDebuggingCVar->GetInt() != 0) || FParse::Param(FCommandLine::Get(), TEXT("metalgpudebug"));
#else
        GMetalCommandBufferDebuggingEnabled = true;
#endif

#Loc: <Workspace>/Engine/Source/Runtime/D3D12RHI/Private/D3D12Adapter.cpp:1413

Scope (from outer to inner):

file
function     void FD3D12Adapter::SetupGPUCrashDebuggingModesCommon

Source code excerpt:

{
	// Multiple ways to enable the different D3D12 crash debugging modes:
	// - via RHI independent r.GPUCrashDebugging cvar: by default enable low overhead breadcrumbs and NvAftermath are enabled
	// - via 'gpucrashdebugging' command line argument: enable all possible GPU crash debug modes (minor performance impact)
	// - via 'r.D3D12.BreadCrumbs', 'r.D3D12.AfterMath' or 'r.D3D12.Dred' each type of GPU crash debugging mode can be enabled
	// - via '-gpubreadcrumbs(=0)', '-nvaftermath(=0)' or '-dred(=0)' command line argument: each type of gpu crash debugging mode can enabled/disabled
	if (FParse::Param(FCommandLine::Get(), TEXT("gpucrashdebugging")))
	{
		GPUCrashDebuggingModes = ED3D12GPUCrashDebuggingModes::All;

#Loc: <Workspace>/Engine/Source/Runtime/D3D12RHI/Private/D3D12Adapter.cpp:1432

Scope (from outer to inner):

file
function     void FD3D12Adapter::SetupGPUCrashDebuggingModesCommon

Source code excerpt:

			}
		};
		ParseCVar(TEXT("r.GPUCrashDebugging"), ED3D12GPUCrashDebuggingModes((int)ED3D12GPUCrashDebuggingModes::NvAftermath | (int)ED3D12GPUCrashDebuggingModes::DRED));
		ParseCVar(TEXT("r.D3D12.BreadCrumbs"), ED3D12GPUCrashDebuggingModes::BreadCrumbs);
		ParseCVar(TEXT("r.D3D12.NvAfterMath"), ED3D12GPUCrashDebuggingModes::NvAftermath);
		ParseCVar(TEXT("r.D3D12.DRED"), ED3D12GPUCrashDebuggingModes::DRED);

		// Enable/disable specific crash debugging modes if requested via command line argument
		const auto ParseCommandLine = [this](const TCHAR* CommandLineArgument, ED3D12GPUCrashDebuggingModes DebuggingMode)

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Private/Windows/WindowsDynamicRHI.cpp:919

Scope (from outer to inner):

file
function     static IDynamicRHIModule* LoadDynamicRHIModule

Source code excerpt:

	if (!GIsEditor && GConfig->GetBool(TEXT("D3DRHIPreference"), TEXT("bUseGPUCrashDebugging"), bUseGPUCrashDebugging, GGameUserSettingsIni))
	{
		auto GPUCrashDebuggingCVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.GPUCrashDebugging"));
		*GPUCrashDebuggingCVar = bUseGPUCrashDebugging;
	}

	const FParsedWindowsDynamicRHIConfig Config = ParseWindowsDynamicRHIConfig();

	// RHI is chosen by the project settings (first DefaultGraphicsRHI, then TargetedRHIs are consulted, "Default" maps to D3D12).

#Loc: <Workspace>/Engine/Source/Runtime/VulkanRHI/Private/VulkanRHI.cpp:530

Scope (from outer to inner):

file
function     FVulkanDynamicRHI::FVulkanDynamicRHI

Source code excerpt:


	{
		IConsoleVariable* GPUCrashDebuggingCVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.GPUCrashDebugging"));
		GGPUCrashDebuggingEnabled = (GPUCrashDebuggingCVar && GPUCrashDebuggingCVar->GetInt() != 0) || FParse::Param(FCommandLine::Get(), TEXT("gpucrashdebugging"));
	}



	CreateInstance();

#Loc: <Workspace>/Engine/Source/Runtime/Windows/D3D11RHI/Private/Windows/WindowsD3D11Device.cpp:1309

Scope (from outer to inner):

file
function     static void CacheNVAftermathEnabled

Source code excerpt:

	if (GNVAftermathModuleLoaded && IsRHIDeviceNVIDIA() && !FParse::Param(FCommandLine::Get(), TEXT("nogpucrashdebugging")))
	{
		// Two ways to enable aftermath, command line or the r.GPUCrashDebugging variable
		// Note: If intending to change this please alert game teams who use this for user support.
		if (FParse::Param(FCommandLine::Get(), TEXT("gpucrashdebugging")))
		{
			GDX11NVAfterMathEnabled = true;
		}
		else
		{
			static IConsoleVariable* GPUCrashDebugging = IConsoleManager::Get().FindConsoleVariable(TEXT("r.GPUCrashDebugging"));
			if (GPUCrashDebugging)
			{
				GDX11NVAfterMathEnabled = GPUCrashDebugging->GetInt() != 0;
			}
		}
	}