Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
PIX can open DirectX Dump Files and show the state of the GPU at the moment of a crash. This article explains how to open a dump file, and what each view shows. To create dump files, see Generate DirectX Dump Files.
You can also get the data in each view with the PIX API, for example to automate crash triage. Each section below names the API methods to use. This article uses the C++ names, and the C# and Python bindings use similar names. For more information, see Analyze DirectX Dump Files programmatically.
Open a dump file
- In PIX, select File > Open.
- Browse to the dump file. By default, dump files are in
%LOCALAPPDATA%\CrashDumps. - Select the file, and then select Open.
Dump files use the .dxdmp extension. Preview versions of the Agility SDK create preview dump files (.dxdmp_preview) instead, which only preview builds of PIX can open.
Some views only have data if the driver supports DirectX Dump Files, or if particular options were turned on when the dump was created. When a view has no data, it shows a message that explains why. For more information, see Full and partial dump files.
Investigate a crash
A typical investigation follows these steps:
- Start with the Summary view to see what kind of error occurred and which resources and shaders PIX suspects.
- Use the Event List view to find how far the GPU got through the frame.
- For a page fault, use the Page Faults view to find which resource was at the faulting address, and when it was created and destroyed.
- For a hang or a shader exception, use the Shader Waves and Shaders views to find which shader instruction was executing.
- Use the Autos, Resources, and D3D12 API Objects views for more detail.
Many views link to each other. For example, select a resource or shader link in the Summary view to go to it in the related view.
Summary view
The Summary view diagnoses the cause of the device error, and links to other views with more detail. For a page fault, it lists the faulting GPU virtual addresses, the resources at each address, and the shaders that might have caused the fault.
The DRED Info panel shows which DRED features were turned on when the dump file was created.
To get this data programmatically, call IPixDxDumpFileDocument::GetBriefSummary or GetDetailedSummary for the diagnosis, and GetDeviceErrorBucket for the error bucket. The DRED features are flags in the D3D12_DEVICE_CONFIGURATION_DESC that GetDeviceConfigDesc returns.
For a partial dump file, the summary is based on Direct3D runtime and DRED data only:
Event List view
The Event List view shows a hierarchy of the Direct3D 12 API calls, driver events, and PIX markers recorded in the dump file. For each event, it shows the execution status, and whether the event is related to an executing shader or a recorded resource.
Use the toolbar to:
- Switch between the Tree and Flat layouts.
- Switch between the event list from the Driver and the auto-breadcrumbs timeline from DRED. DRED breadcrumbs are available only if auto-breadcrumbs were turned on.
- Choose which queue to show.
PIX markers appear in this view only if retail annotations were turned on. For more information, see Include PIX markers in dump files.
To get this data programmatically, call IPixDxDumpFileDocument::GetQueues for the driver events, and GetDeviceRemovedExtendedData for the DRED auto-breadcrumbs.
GPU State view
The GPU State view shows tables of GPU state that the driver recorded when the dump file was created. Each table is on its own tab. You can filter, search, and sort the rows.
To get this data programmatically, call IPixDxDumpFileDocument::GetGpuStateTables.
Page Faults view
The Page Faults view lists each faulting GPU virtual address. Use the toolbar to switch between page fault data from the Driver and from DRED:
- The driver data lists the resources the driver recorded whose virtual address range includes the faulting address.
- The DRED data lists the active and recently freed allocations that the Direct3D runtime recorded. It's available only if DRED page fault reporting was turned on.
The Resource Timeline panel lists, in order, the events for the resources at the selected address, such as when each resource was created, made resident, and destroyed.
To get this data programmatically, call IPixDxDumpFileDocument::GetPageFaults for the driver data, and GetDeviceRemovedExtendedData for the DRED data.
Resources view
The Resources view lists the Direct3D 12 resources that the runtime and the driver recorded. Select a resource to see its events, in order, in the Resource Timeline panel. If nothing is selected, the panel shows the events for all resources.
To get this data programmatically, call IPixDxDumpFileDocument::GetResources.
Shader Waves view
The Shader Waves view lists the shader waves that were executing when the dump file was created. For each wave, it shows:
- The execution status.
- The active lanes and lane count.
- The shader stage.
- Whether the wave hit an exception.
- The shader hash.
- The instruction that was executing.
Select a wave to see its shader in the Shaders view, and its registers in the Autos view.
To get this data programmatically, call IPixDxDumpFileDocument::GetShaderDebuggingData.
Shaders view
The Shaders view shows the code of the shaders that were executing. PIX highlights instructions to investigate with an error icon, and marks where the active waves are in each shader.
The shader ISA can include annotations. For example, if an instruction uses a descriptor for an image, buffer, sampler, or acceleration structure, PIX highlights the registers that hold it. Select an annotation to decode the descriptor in the Annotation Details panel.
To get this data programmatically, call IPixShaderWave::GetShader for the code, and IPixShaderWave::GetOffendingCodeLocations for the instructions to investigate.
Show DXIL and HLSL
To show DXIL and HLSL for a shader, PIX needs the shader object and the shader PDB that the HLSL compiler produced:
- Shader objects let PIX show DXIL and find the shader PDB hash. To tell PIX where to find them, select File > Settings > Shader Object Options, and add folders to Shader Object Search Paths.
- Shader PDBs let PIX show HLSL. PIX supports full PDBs (
-Zi -Fd) and slim PDBs (-Zs -Fd). To tell PIX where to find them, select File > Settings > Symbol / PDB Options. For more information, see Use automatic shader PDB resolution in PIX.
If you compile with -Zi -Qembed_debug, the PDB is embedded in the shader object, so PIX needs only the shader object to show both DXIL and HLSL.
The PIX API doesn't use these search paths. To get DXIL and HLSL programmatically, pass the shader object, and the PDB if it isn't embedded, to IPixShaderWave::GetShader.
An icon next to each shader in the Shaders panel shows whether PIX found its shader object and PDB. To find them manually, select the shader, and then select Resolve Shader Object or Resolve Shader PDB. You need to resolve the shader object before you can resolve the PDB.
PIX doesn't yet map between the shader ISA, DXIL, and HLSL.
Autos view
The Autos view shows the registers of the wave and lane selected in the Shader Waves view. Register data is available only if the driver collected it, for example with the Shader Registers option or a higher overhead level.
To get this data programmatically, call IPixShaderWave::GetVariables for the wave registers, and IPixShaderLane::GetVariables for the lane registers.
D3D12 API Objects view
The D3D12 API Objects view lists Direct3D 12 objects that the runtime recorded when the dump file was created, such as command queues and command allocators.
To get this data programmatically, call IPixDxDumpFileDocument::GetApiObjects.
Application Blobs view
The Application Blobs view shows the data and metadata that the application added with AddBlobToDumpFile. For more information, see Add application data and get the file path.
To get this data programmatically, call IPixDxDumpFileDocument::GetApplicationBlobs.
File Details view
The File Details view shows how the system was configured when the dump file was created, including:
- The driver configuration and dump file options.
- The application that crashed.
- The adapter and device configuration.
- The OS.
To get this data programmatically, call these IPixDxDumpFileDocument methods:
GetConfigurationandGetFeatureDatafor the dump file options and driver support.GetApplicationDescriptionfor the application.GetAdapterInfoandGetDeviceConfigDescfor the adapter and device configuration.GetOsInfo,GetCpuInfo, andGetSystemMemoryInfofor the system.
