DxDmp tools reference

PIX includes two interfaces for reading DirectX Dump Files:

  • DxDmp.exe is a command-line interface (CLI) for agents, scripts, build systems, and crash-triage pipelines.
  • DxDmpMcp.exe is a Model Context Protocol (MCP) server for MCP-compatible agent hosts.

Both tools are in the PIX installation folder, usually %ProgramFiles%\Microsoft PIX\<version>\. They accept .dxdmp files.

For more information about configuring an agent to use these tools, see Analyze DirectX Dump Files with AI agents.

DxDmp CLI

The CLI syntax is:

DxDmp.exe <command> "<dump-path>" [options]

Run DxDmp.exe --help to list commands. Run DxDmp.exe <command> --help for the complete syntax of one command.

Common options

Every command accepts these options:

Option Description
--output <FORMAT> Sets the output format to text, json, or markdown. The default is text when output goes to a terminal and JSON when output is redirected.
--out <FILE> Writes the result to a file instead of standard output.
--quiet Suppresses informational messages and prints only the result.
--max-lines <N> Limits text or Markdown output to the specified number of lines. Use 0 for no limit. This option can't be used with JSON output.
--full Returns the long form of a result. For list commands, returns all rows instead of applying --limit.
--help Prints help for the selected command.

Commands that return lists also accept:

Option Description
--limit <N> Sets the maximum number of items to return. The default is 50. This option is ignored when you specify --full.
--offset <N> Sets the zero-based index of the first item to return. The default is 0.

Commands

Command Description Command-specific options
adapter Prints the GPU adapter identity, memory, driver version, and feature level. None.
api-objects Lists the live Direct3D 12 API objects recorded in the dump. Supports --limit and --offset.
application Prints the application name, executable, version, and engine recorded in the dump. None.
blobs Lists application-authored blobs and their metadata, or extracts their complete contents. --out-dir <DIR> extracts every blob to the specified directory. Also supports --limit and --offset when listing.
cpu-info Prints host CPU details, including per-package information. None.
device-config Prints the Direct3D 12 device configuration recorded in the dump. None.
dred Prints Device Removed Extended Data (DRED) breadcrumbs and page-fault information. None.
driver-config Prints the overhead level and content flags that configured what the dump captured. None.
events Lists compact event summaries for a GPU queue. --queue <INDEX> selects the zero-based queue index. The default is 0. Also supports --limit and --offset.
feature-caps Prints dump fidelity, the driver tier, and the types of diagnostic content that the driver can emit. None.
file-metadata Prints the dump GUID, version, creation time, Watson or live-debug status, and device error code. None.
gpu-state Prints the GPU hardware state tables supplied by the graphics driver plug-in. None.
gpu-status Prints driver-authored status text for each GPU block. None.
journal Lists recent Direct3D 12 runtime journal entries. Supports --limit and --offset.
memory Prints host system-memory details recorded in the dump. None.
os-info Prints operating-system details recorded in the dump. None.
page-faults Lists document-level GPU page faults. Supports --limit and --offset.
queues Lists GPU queues and their status. Supports --limit and --offset.
resources Lists recorded resources, or only resources that cover a specified GPU virtual address. --address <ADDR> accepts a hexadecimal or decimal GPU virtual address. Also supports --limit and --offset.
shader Returns ISA, IL, or HLSL source for a shader wave. --wave <INDEX> is required. --type <ISA\|IL\|HLSL> selects the code type. --start-line <N> and --end-line <N> select a source window. --shader-object <PATH> supplies the matching compiled object for IL. --pdb <PATH> supplies the matching PDB for HLSL.
shader-fault-locations Lists shader code locations that the graphics driver plug-in identified as suspected fault causes. --wave <INDEX> is required. --type <ISA\|IL\|HLSL> selects the code type. Currently, the plug-in reports only ISA locations.
summary Prints the crash classification, key facts, dump fidelity, and a content map that reports which sections are available. --full also returns the device error code and detailed driver-authored description.
waves Lists shader waves, including their stage, status, exception, instruction pointer, and shader hash. --filter <all\|faulting> selects all waves or only faulting waves. The default is all. Also supports --limit and --offset.

Shader source files

ISA comes from the dump and doesn't require external files. IL and HLSL require explicit paths to files from the build that produced the dump:

  • --shader-object <PATH> supplies a compiled shader object (.cso, .dxbc, or .dxil) and enables IL.
  • --pdb <PATH> supplies the matching shader PDB. The shader object and PDB together enable HLSL.

DxDmp doesn't automatically use the search paths configured in the PIX UI. It reads the supplied files and passes them to the PIX API, which verifies that they match the shader wave.

DxDmp MCP server

The MCP server syntax is:

DxDmpMcp.exe [options]

Server options

Option Description
--transport <TRANSPORT> Selects the transport. The only supported value, and the default, is stdio.
--knowledge <PATH> Overrides the knowledge-base directory. The default is Tools\DxDmp\agent-kit\knowledge under the PIX installation folder.
--open <PATH> Opens a dump when the server starts. Specify this option more than once to open multiple dumps.
--version Prints the server version and exits.

The MCP server runs locally and communicates with its host through standard input/output (stdio).

Common MCP parameters

Most diagnostic tools require dumpId, the session-scoped ID returned by open_dump. Tools that return lists use offset and limit for paging. The default limit is 50.

Dump management tools

Tool Parameters Description
list_dump_files directory, recursive, offset, limit Lists .dxdmp files in a directory, newest first.
open_dump path Opens a dump and returns its session-scoped ID and summary.
close_dump dumpId Closes a dump and releases its analysis resources.
list_open_dumps None. Lists the dumps open in the current MCP session.

Diagnostic tools

Tool Parameters Description
get_dump_summary dumpId, full Returns the recommended first-call summary and content map. Set full to include the detailed description.
get_capabilities dumpId Returns dump fidelity, driver tier, and captured-content capabilities.
get_file_metadata dumpId Returns the dump GUID, version, creation time, error code, and Watson metadata.
get_application_info dumpId Returns the application, executable, engine, and version.
get_adapter_info dumpId Returns GPU adapter identity, memory, driver, and feature-level details.
get_driver_configuration dumpId Returns the overhead and optional content that the dump was configured to capture.
get_device_configuration dumpId Returns the Direct3D 12 device configuration recorded in the dump.
get_os_info dumpId Returns operating-system details.
get_memory_info dumpId Returns host memory details.
get_cpu_info dumpId Returns host CPU and package details.
get_dred dumpId Returns DRED breadcrumbs and page-fault information when present.
list_queues dumpId, offset, limit Lists GPU queues and their hang or fence status.
get_queue_events dumpId, queueIndex, offset, limit Lists compact event summaries for a queue.
list_page_faults dumpId, offset, limit Lists document-level GPU page faults.
list_resources dumpId, address, offset, limit Lists resources, optionally restricted to a hexadecimal or decimal GPU virtual address.
get_page_fault_resources dumpId, address, offset, limit Lists resources that cover a page-fault GPU virtual address.
get_gpu_state_tables dumpId Returns graphics driver-provided GPU hardware state tables.
get_gpu_status dumpId Returns driver-authored status text for each GPU block.
get_shader_waves dumpId, filter, offset, limit Lists shader waves. Set filter to faulting to return only faulting waves.
get_shader_source dumpId, waveIndex, codeType, startLine, endLine, shaderObjectPath, pdbPath Returns a window of ISA, IL, or HLSL for a wave. IL requires an explicit matching shader object. HLSL also requires its matching PDB.
get_offending_shader_locations dumpId, waveIndex, codeType Returns shader lines that the graphics driver plug-in identified as suspected fault causes. Currently, the plug-in reports only ISA locations.
get_d3d_journal dumpId, offset, limit Returns recent Direct3D 12 runtime journal entries.
get_api_objects dumpId, offset, limit Lists live Direct3D 12 API objects recorded in the dump.
get_application_blobs dumpId, offset, limit Lists application blobs with 64-byte previews and resource URIs for the complete binary data.

Knowledge tools

Tool Parameters Description
list_knowledge_articles category Lists knowledge article metadata, optionally within one category.
read_knowledge_article path Returns one knowledge article by its path relative to the knowledge directory.
query_known_issues gpu, symptom, format, pipelineStage, severity Finds knowledge articles by structured symptoms. Fields are combined with AND; values within one field are combined with OR.

MCP resources

MCP resources expose data through URIs instead of tool calls. An MCP host can discover a resource and read it when the agent needs its contents. Resource discovery and access vary by host.

The methodology:// resources return Markdown from the packaged knowledge base. The pix:// resource returns the complete bytes of an application-authored blob. get_application_blobs returns a preview and a resource URI. The host reads the URI when it needs the complete blob. Blob resources are session-scoped and remain available only while their dump is open.

URI Description
methodology://diagnostic-workflow Step-by-step methodology for investigating a GPU hang.
methodology://triage-title-vs-driver Criteria for attributing a GPU hang to the application or the driver.
methodology://tool-ordering Recommended order for progressively querying dump data.
pix://dump-{dumpId}/blob/{blobIndex} Complete binary contents of an application-authored dump blob.

Related content

  • Last updated on