Files
Seele/external/aftermath/include/GFSDK_Aftermath.h
T

484 lines
21 KiB
C

/*
* Copyright (c) 2017-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 for DX11 and DX12
* --------------------------------------
*
* Call 'GFSDK_Aftermath_DXxx_Initialize', to initialize the library and to enable
* the desired Aftermath feature set. See 'GFSDK_Aftermath_FeatureFlags' below for
* the list of supported features.
* This must be done before any other library calls are made, and the method must
* return 'GFSDK_Aftermath_Result_Success' for initialization to be complete.
*
* Initialization of Aftermath may fail for a variety of reasons, including:
*
* o) The initialization function was already called for the device:
* GFSDK_Aftermath_Result_FAIL_AlreadyInitialized.
*
*
* o) Aftermath isn't supported on the GPU associated with the device or the NVIDIA
* display driver version installed:
* GFSDK_Aftermath_Result_FAIL_InvalidAdapter,
* GFSDK_Aftermath_Result_FAIL_DriverInitFailed,
* GFSDK_Aftermath_Result_FAIL_DriverVersionNotSupported,
* GFSDK_Aftermath_Result_FAIL_NvApiIncompatible.
*
*
* o) A D3D API debug layer, such as PIX, was detected that is incompatible with
* Aftermath:
* GFSDK_Aftermath_Result_FAIL_D3dDllInterceptionNotSupported
*
*
* o) Aftermath was disabled on the system by the current user setting the
* 'HKEY_CURRENT_USER\Software\NVIDIA Corporation\Nsight Aftermath\ForceOff'
* Windows registry key:
* GFSDK_Aftermath_Result_FAIL_Disabled
*
*
* After detecting D3D device lost (TDR):
*
* o) To query the fault reason after TDR, use the 'GFSDK_Aftermath_GetDeviceStatus'
* call. See 'GFSDK_Aftermath_Device_Status', for the full list of possible
* status.
*
*
* o) In the event of a GPU page fault, use the'GFSDK_Aftermath_GetPageFaultInformation'
* method to return more information about what might of gone wrong. A GPU VA is
* returned, along with the resource descriptor of the resource that VA lands in.
* NOTE: It's not 100% certain that this is the resource which caused the fault,
* only that the faulting VA lands within this resource in memory.
*
*
* Optionally, instrument the application with Aftermath event markers:
*
* 1) For each commandlist/device context you expect to use with Aftermath,
* initialize them using the 'GFSDK_Aftermath_DXxx_CreateContextHandle',
* function.
*
*
* 2) Call 'GFSDK_Aftermath_SetEventMarker', to inject an event
* marker directly into the command stream at that point.
*
* PERFORMANCE TIP:
*
* Do not use 'GFSDK_Aftermath_SetEventMarker' in high frequency code paths.
* Injecting event markers introduces considerable CPU overhead. For reduced CPU
* overhead, use 'GFSDK_Aftermath_SetEventMarker' with markerSize=0. This
* instructs Aftermath not to allocate and copy off memory internally, relying on
* the application to manage marker pointers itself.
*
*
* 3) Once TDR/hang occurs, call the 'GFSDK_Aftermath_GetData' API
* to fetch the event marker last processed by the GPU for each context.
* This API also supports fetching the current execution state for each
* the GPU.
*
*
* 4) Before the app shuts down, each Aftermath context handle must be cleaned
* up, this is done with the 'GFSDK_Aftermath_ReleaseContextHandle' call.
*
*
* HOW TO USE AFTERMATH for Vulkan
* -------------------------------
*
* For Vulkan use the VK_NV_device_diagnostics_config extension to initialize and
* configure the Aftermath feature set to use.
*
* Use the VK_NV_device_diagnostic_checkpoints extension to add event markers into
* the command stream.
*
*/
#ifndef GFSDK_Aftermath_H
#define GFSDK_Aftermath_H
#include "GFSDK_Aftermath_Defines.h"
#pragma pack(push, 8)
#ifdef __cplusplus
extern "C" {
#endif
// Here is defined a set of features that can be enabled/disable when using Aftermath
GFSDK_AFTERMATH_DECLARE_ENUM(FeatureFlags)
{
// The minimal flag only allows use of the GetDeviceStatus entry point.
GFSDK_Aftermath_FeatureFlags_Minimum = 0x00000000,
// With this flag set, the SetEventMarker and GetData entry points are available.
//
// Using event markers should be considered carefully as they can cause very high
// CPU overhead when used in high frequency code paths.
//
GFSDK_Aftermath_FeatureFlags_EnableMarkers = 0x00000001,
// With this flag set, resources are tracked, and information about
// possible page fault candidates can be accessed using GetPageFaultInformation.
GFSDK_Aftermath_FeatureFlags_EnableResourceTracking = 0x00000002,
// With this flag set, event markers are automatically set for all draw calls,
// compute dispatches and copy operations to capture the call stack for the
// corresponding API call as the event marker payload.
// Requires also GFSDK_Aftermath_FeatureFlags_EnableMarkers to be set.
//
// Using this option should be considered carefully. Enabling call stack capturing
// can cause considerable CPU overhead.
//
GFSDK_Aftermath_FeatureFlags_CallStackCapturing = 0x40000000,
// With this flag set, shader debug information is generated.
// Not supported for UWP applications.
GFSDK_Aftermath_FeatureFlags_GenerateShaderDebugInfo = 0x00000008,
// Use all Aftermath features
// Be careful when using this! Some features can cause considerable performance overhead,
// for example, GFSDK_Aftermath_FeatureFlags_EnableMarkers.
GFSDK_Aftermath_FeatureFlags_Maximum = GFSDK_Aftermath_FeatureFlags_Minimum |
GFSDK_Aftermath_FeatureFlags_EnableMarkers |
GFSDK_Aftermath_FeatureFlags_EnableResourceTracking |
GFSDK_Aftermath_FeatureFlags_CallStackCapturing |
GFSDK_Aftermath_FeatureFlags_GenerateShaderDebugInfo,
};
#if defined(__d3d11_h__) || defined(__d3d12_h__)
// Used with Aftermath entry points to reference an API object.
GFSDK_AFTERMATH_DECLARE_HANDLE(GFSDK_Aftermath_ContextHandle);
GFSDK_AFTERMATH_DECLARE_HANDLE(GFSDK_Aftermath_ResourceHandle);
// Used with, 'GFSDK_Aftermath_GetData'. Filled with information,
// about each requested context.
typedef struct GFSDK_Aftermath_ContextData
{
GFSDK_AFTERMATH_DECLARE_POINTER_MEMBER(void*, markerData);
uint32_t markerSize;
GFSDK_Aftermath_Context_Status status;
} GFSDK_Aftermath_ContextData;
// Minimal description of a graphics resource.
typedef struct GFSDK_Aftermath_ResourceDescriptor
{
// This is available in DX12 only and only if the application registers the
// resource pointers using GFSDK_Aftermath_DX12_RegisterResource().
#ifdef __d3d12_h__
GFSDK_AFTERMATH_DECLARE_POINTER_MEMBER(ID3D12Resource*, pAppResource);
#else
GFSDK_AFTERMATH_DECLARE_POINTER_MEMBER(void*, pAppResource);
#endif
uint64_t size;
uint32_t width;
uint32_t height;
uint32_t depth;
uint32_t mipLevels;
uint32_t format; // DXGI_FORMAT
GFSDK_AFTERMATH_DECLARE_BOOLEAN_MEMBER(bIsBufferHeap);
GFSDK_AFTERMATH_DECLARE_BOOLEAN_MEMBER(bIsStaticTextureHeap);
GFSDK_AFTERMATH_DECLARE_BOOLEAN_MEMBER(bIsRtvDsvTextureHeap);
GFSDK_AFTERMATH_DECLARE_BOOLEAN_MEMBER(bPlacedResource);
GFSDK_AFTERMATH_DECLARE_BOOLEAN_MEMBER(bWasDestroyed);
} GFSDK_Aftermath_ResourceDescriptor
;
// Used with GFSDK_Aftermath_GetPageFaultInformation
typedef struct GFSDK_Aftermath_PageFaultInformation
{
uint64_t faultingGpuVA;
GFSDK_Aftermath_ResourceDescriptor resourceDesc;
GFSDK_AFTERMATH_DECLARE_BOOLEAN_MEMBER(bHasPageFaultOccured);
} GFSDK_Aftermath_PageFaultInformation;
/////////////////////////////////////////////////////////////////////////
// GFSDK_Aftermath_DX11_Initialize
// GFSDK_Aftermath_DX12_Initialize
// ---------------------------------
//
// [pDx11Device]; DX11-Only
// the current dx11 device pointer.
//
// [pDx12Device]; DX12-Only
// the current dx12 device pointer.
//
// flags;
// set of features to enable when initializing Aftermath
//
// version;
// Must be set to GFSDK_Aftermath_Version_API. Used for checking
// against library version.
//
//// DESCRIPTION;
// Library must be initialized before any other call is made.
// This should be done after device creation.
// Aftermath currently only supports one D3D device,
// the first one that is initialized.
//
/////////////////////////////////////////////////////////////////////////
#ifdef __d3d11_h__
GFSDK_Aftermath_API GFSDK_Aftermath_DX11_Initialize(GFSDK_Aftermath_Version version, uint32_t flags, ID3D11Device* const pDx11Device);
#endif
#ifdef __d3d12_h__
GFSDK_Aftermath_API GFSDK_Aftermath_DX12_Initialize(GFSDK_Aftermath_Version version, uint32_t flags, ID3D12Device* const pDx12Device);
#endif
/////////////////////////////////////////////////////////////////////////
// GFSDK_Aftermath_DX11_CreateContextHandle
// GFSDK_Aftermath_DX12_CreateContextHandle
// ---------------------------------
//
// (pDx11DeviceContext); DX11-Only
// Device context to use with Aftermath.
//
// (pDx12Unknown); DX12-Only
// Command list, Command Queue, or Device to use with Aftermath
// If a device, must be the same device given to GFSDK_Aftermath_DX12_Initialize()
//
// pOutContextHandle;
// The context handle for the specified context/command list/command queue/device
// to be used with future Aftermath calls.
//
//// DESCRIPTION;
// Before Aftermath event markers can be inserted,
// a context handle reference must first be fetched.
//
/////////////////////////////////////////////////////////////////////////
#ifdef __d3d11_h__
GFSDK_Aftermath_API GFSDK_Aftermath_DX11_CreateContextHandle(ID3D11DeviceContext* const pDx11DeviceContext, GFSDK_Aftermath_ContextHandle* pOutContextHandle);
#endif
#ifdef __d3d12_h__
GFSDK_Aftermath_API GFSDK_Aftermath_DX12_CreateContextHandle(IUnknown* const pDx12Unknown, GFSDK_Aftermath_ContextHandle* pOutContextHandle);
#endif
/////////////////////////////////////////////////////////////////////////
// GFSDK_Aftermath_API GFSDK_Aftermath_ReleaseContextHandle
// -------------------------------------
//
// contextHandle;
// Context to release
//
// DESCRIPTION;
// Cleans up any resources associated with an Aftermath context
//
/////////////////////////////////////////////////////////////////////////
GFSDK_Aftermath_API GFSDK_Aftermath_ReleaseContextHandle(const GFSDK_Aftermath_ContextHandle contextHandle);
/////////////////////////////////////////////////////////////////////////
// GFSDK_Aftermath_SetEventMarker
// -------------------------------------
//
// contextHandle;
// Command list currently being populated.
//
// markerData;
// Pointer to data used for event marker.
// NOTE: If markerSize is also provided, an internal copy will be
// made of this data. In that case there is no need to keep it
// around after this call - stack alloc is safe.
//
// markerSize;
// Size of event marker data in bytes.
// NOTE: Passing a 0 for this parameter is valid, and will instruct
// Aftermath to only copy off the pointer supplied by markerData,
// rather than internally making a copy. This, however, precludes
// Aftermath from storing the marker data in GPU crash dumps.
// NOTE: Aftermath will internally truncate marker data to a maximum
// size of 1024 bytes. Use markerSize=0 and manually manage
// memory for markers if the application requires larger ones.
//
// DESCRIPTION;
// Drops a event into the command stream with a payload that can be
// linked back to the data given here, 'markerData'. It's
// safe to call from multiple threads simultaneously, normal D3D
// API threading restrictions apply.
//
// Using event markers should be considered carefully as they can cause considerable
// CPU overhead when used in high frequency code paths.
//
/////////////////////////////////////////////////////////////////////////
GFSDK_Aftermath_API GFSDK_Aftermath_SetEventMarker(const GFSDK_Aftermath_ContextHandle contextHandle, const void* markerData, const uint32_t markerSize);
/////////////////////////////////////////////////////////////////////////
// GFSDK_Aftermath_GetData
// ------------------------------
//
// numContexts;
// Number of contexts to fetch information for.
//
// pContextHandles;
// Array of contexts containing Aftermath event markers.
//
// pOutContextData;
// OUTPUT: context data for each context requested. Contains event
// last reached on the GPU, and status of context if
// applicable (DX12-Only).
// NOTE: must allocate enough space for 'numContexts' worth of structures.
// stack allocation is fine.
//
// DESCRIPTION;
// Once a TDR/crash/hang has occurred (or whenever you like), call
// this API to retrieve the event last processed by the GPU on the
// given context.
//
/////////////////////////////////////////////////////////////////////////
GFSDK_Aftermath_API GFSDK_Aftermath_GetData(const uint32_t numContexts, const GFSDK_Aftermath_ContextHandle* pContextHandles, GFSDK_Aftermath_ContextData* pOutContextData);
/////////////////////////////////////////////////////////////////////////
// GFSDK_Aftermath_GetContextError()
// ------------------------------
//
// pContextData;
// Context data for which to determine error status.
//
// DESCRIPTION;
// Call this to determine the detailed failure reason for GFSDK_Aftermath_ContextData
// with 'status == GFSDK_Aftermath_Context_Status_Invalid'.
//
/////////////////////////////////////////////////////////////////////////
GFSDK_Aftermath_API GFSDK_Aftermath_GetContextError(const GFSDK_Aftermath_ContextData* pContextData);
/////////////////////////////////////////////////////////////////////////
// GFSDK_Aftermath_GetDeviceStatus
// ---------------------------------
//
// pOutStatus;
// OUTPUT: Device status.
//
//// DESCRIPTION;
// Return the status of a D3D device. See GFSDK_Aftermath_Device_Status.
//
/////////////////////////////////////////////////////////////////////////
GFSDK_Aftermath_API GFSDK_Aftermath_GetDeviceStatus(GFSDK_Aftermath_Device_Status* pOutStatus);
/////////////////////////////////////////////////////////////////////////
// GFSDK_Aftermath_GetPageFaultInformation
// ---------------------------------
//
// pOutPageFaultInformation;
// OUTPUT: Information about a page fault which may have occurred.
//
//// DESCRIPTION;
// Return any information available about a recent page fault which
// may have occurred, causing a device removed scenario.
// See GFSDK_Aftermath_PageFaultInformation.
//
// Requires WDDMv2 (Windows 10) or later
//
/////////////////////////////////////////////////////////////////////////
GFSDK_Aftermath_API GFSDK_Aftermath_GetPageFaultInformation(GFSDK_Aftermath_PageFaultInformation* pOutPageFaultInformation);
/////////////////////////////////////////////////////////////////////////
// GFSDK_Aftermath_DX12_RegisterResource
// ---------------------------------
//
// pResource;
// ID3D12Resource to register.
//
// pOutResourceHandle;
// OUTPUT: Aftermath resource handle for the resource that was registered.
//
//// DESCRIPTION;
// Register an ID3D12Resource with Aftermath. This allows Aftermath
// to map a GpuVA of a page fault to the corresponding ID3D12Resource.
//
// NOTE1: This function is only supported on Windows 10 RS4 and RS5.
// It will return GFSDK_Aftermath_Result_FAIL_D3dDllNotSupported, if the
// version of the D3D DLL is not supported.
// NOTE2: This function is not supported in UWP applications.
// NOTE3: This function is not compatible with graphics debuggers, such as
// Nsight Graphics or the Visual Studio Graphics Debugger. It may fail with
// GFSDK_Aftermath_Result_FAIL_D3dDllInterceptionNotSupported when called,
// if such a debugger is active.
//
// This is a BETA FEATURE and may not work with all versions of Windows.
//
/////////////////////////////////////////////////////////////////////////
#if defined(__d3d12_h__)
GFSDK_Aftermath_API GFSDK_Aftermath_DX12_RegisterResource(ID3D12Resource* const pResource, GFSDK_Aftermath_ResourceHandle* pOutResourceHandle);
#endif
/////////////////////////////////////////////////////////////////////////
// GFSDK_Aftermath_DX12_UnregisterResource
// ---------------------------------
//
// resourceHandle;
// Aftermath resource handle for a resource that was reagister earlier
// with GFSDK_Aftermath_DX12_RegisterResource().
//
//// DESCRIPTION;
// Unregisters a previously registered resource.
//
// This is a BETA FEATURE and may not work with all versions of Windows.
//
/////////////////////////////////////////////////////////////////////////
#if defined(__d3d12_h__)
GFSDK_Aftermath_API GFSDK_Aftermath_DX12_UnregisterResource(const GFSDK_Aftermath_ResourceHandle resourceHandle);
#endif
/////////////////////////////////////////////////////////////////////////
//
// NOTE: Function table provided - if dynamic loading is preferred.
//
/////////////////////////////////////////////////////////////////////////
#if defined(__d3d11_h__)
GFSDK_Aftermath_PFN(GFSDK_AFTERMATH_CALL *PFN_GFSDK_Aftermath_DX11_Initialize)(GFSDK_Aftermath_Version version, uint32_t flags, ID3D11Device* const pDx11Device);
GFSDK_Aftermath_PFN(GFSDK_AFTERMATH_CALL *PFN_GFSDK_Aftermath_DX11_CreateContextHandle)(ID3D11DeviceContext* const pDx11DeviceContext, GFSDK_Aftermath_ContextHandle* pOutContextHandle);
#endif
#if defined(__d3d12_h__)
GFSDK_Aftermath_PFN(GFSDK_AFTERMATH_CALL *PFN_GFSDK_Aftermath_DX12_Initialize)(GFSDK_Aftermath_Version version, uint32_t flags, ID3D12Device* const pDx12Device);
GFSDK_Aftermath_PFN(GFSDK_AFTERMATH_CALL *PFN_GFSDK_Aftermath_DX12_CreateContextHandle)(IUnknown* const pDx12CommandList, GFSDK_Aftermath_ContextHandle* pOutContextHandle);
#endif
#if defined(__d3d11_h__) || defined(__d3d12_h__)
GFSDK_Aftermath_PFN(GFSDK_AFTERMATH_CALL *PFN_GFSDK_Aftermath_ReleaseContextHandle)(const GFSDK_Aftermath_ContextHandle contextHandle);
GFSDK_Aftermath_PFN(GFSDK_AFTERMATH_CALL *PFN_GFSDK_Aftermath_SetEventMarker)(const GFSDK_Aftermath_ContextHandle contextHandle, const void* markerData, const uint32_t markerSize);
GFSDK_Aftermath_PFN(GFSDK_AFTERMATH_CALL *PFN_GFSDK_Aftermath_GetData)(const uint32_t numContexts, const GFSDK_Aftermath_ContextHandle* ppContextHandles, GFSDK_Aftermath_ContextData* pOutContextData);
GFSDK_Aftermath_PFN(GFSDK_AFTERMATH_CALL *PFN_GFSDK_Aftermath_GetContextError)(const GFSDK_Aftermath_ContextData* pContextData);
GFSDK_Aftermath_PFN(GFSDK_AFTERMATH_CALL *PFN_GFSDK_Aftermath_GetDeviceStatus)(GFSDK_Aftermath_Device_Status* pOutStatus);
GFSDK_Aftermath_PFN(GFSDK_AFTERMATH_CALL *PFN_GFSDK_Aftermath_GetPageFaultInformation)(GFSDK_Aftermath_PageFaultInformation* pOutPageFaultInformation);
#endif
#if defined(__d3d12_h__)
GFSDK_Aftermath_PFN(GFSDK_AFTERMATH_CALL *PFN_GFSDK_Aftermath_DX12_RegisterResource)(ID3D12Resource* const pResource, GFSDK_Aftermath_ResourceHandle* pOutResourceHandle);
GFSDK_Aftermath_PFN(GFSDK_AFTERMATH_CALL *PFN_GFSDK_Aftermath_DX12_UnregisterResource)(const GFSDK_Aftermath_ResourceHandle resourceHandle);
#endif
#endif // defined(__d3d11_h__) || defined(__d3d12_h__)
#if defined(VULKAN_H_)
// See VK_NV_device_diagnostics_config
// See VK_NV_device_diagnostic_checkpoints
#endif
#ifdef __cplusplus
} // extern "C"
#endif
#pragma pack(pop)
#endif // GFSDK_Aftermath_H