Add DbgEng process dump smoke workflow

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: awakecoding

.github/workflows/smoke-tests.yml

@@ -0,0 +1,119 @@
+name: Smoke tests
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  dump-smoke:
+    name: Process dump smoke test
+    runs-on: windows-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Select stable Rust
+        shell: pwsh
+        run: rustup default stable
+
+      - name: Restore debugger dependencies
+        shell: pwsh
+        run: cargo xtask deps
+
+      - name: Build windbg-tool
+        shell: pwsh
+        run: cargo build -p windbg-tool
+
+      - name: Create and inspect ping dump
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = 'Stop'
+
+          $tool = Join-Path $PWD 'target\debug\windbg-tool.exe'
+          $dumpDir = Join-Path $env:RUNNER_TEMP 'windbg-tool-smoke'
+          New-Item -ItemType Directory -Path $dumpDir -Force | Out-Null
+          $dumpPath = Join-Path $dumpDir 'ping.dmp'
+          Remove-Item -Path $dumpPath -Force -ErrorAction SilentlyContinue
+
+          $ping = Start-Process `
+            -FilePath 'C:\Windows\System32\ping.exe' `
+            -ArgumentList @('127.0.0.1', '-n', '10') `
+            -PassThru
+
+          try {
+            Start-Sleep -Seconds 1
+
+            & $tool dump create `
+              --process-id $ping.Id `
+              --output $dumpPath `
+              --kind mini `
+              --overwrite | ConvertFrom-Json | Out-Null
+
+            if (-not (Test-Path $dumpPath)) {
+              throw "Expected dump file was not created: $dumpPath"
+            }
+
+            $dumpFile = Get-Item $dumpPath
+            if ($dumpFile.Length -le 0) {
+              throw "Dump file is empty: $dumpPath"
+            }
+          }
+          finally {
+            if (-not $ping.HasExited) {
+              Stop-Process -Id $ping.Id -Force
+              $ping.WaitForExit()
+            }
+          }
+
+          & $tool daemon ensure | ConvertFrom-Json | Out-Null
+
+          $opened = & $tool dump open $dumpPath | ConvertFrom-Json
+          if (-not $opened.target_id) {
+            throw "dump open did not return a target_id"
+          }
+          $target = $opened.target_id
+
+          $status = & $tool target status --target $target | ConvertFrom-Json
+          if ($status.target.kind -ne 'dump') {
+            throw "Expected dump target kind, got '$($status.target.kind)'"
+          }
+
+          $modules = & $tool target modules --target $target | ConvertFrom-Json
+          $pingModule = $modules.modules | Where-Object {
+            ($_.module_name -like '*ping*') -or
+            ($_.image_name -like '*ping.exe*') -or
+            ($_.loaded_image_name -like '*ping.exe*')
+          } | Select-Object -First 1
+          if (-not $pingModule) {
+            throw "Expected loaded modules to include ping.exe"
+          }
+
+          $threads = & $tool target threads --target $target | ConvertFrom-Json
+          if (-not $threads.threads -or $threads.threads.Count -lt 1) {
+            throw "Expected at least one thread in the dump"
+          }
+
+          $registers = & $tool target registers --target $target | ConvertFrom-Json
+          if (
+            -not $registers.registers.instruction_offset -and
+            -not $registers.registers.stack_offset -and
+            -not $registers.registers.frame_offset
+          ) {
+            throw "Expected at least one current-thread register offset in the dump"
+          }
+
+          $stack = & $tool target stack --target $target --max-frames 8 | ConvertFrom-Json
+          if (-not $stack.frames -or $stack.frames.Count -lt 1) {
+            throw "Expected at least one stack frame in the dump"
+          }
+
+      - name: Upload dump on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: ping-dump-smoke
+          path: ${{ runner.temp }}\windbg-tool-smoke\ping.dmp
+          if-no-files-found: ignore
+          retention-days: 3

README.md

@@ -70,7 +70,7 @@ Representative command areas:
 - Discovery: `discover`, `recipes`, `tools`, `schema`
 - Session and replay: `open`, `load`, `sessions`, `info`, `position set`, `step`, `replay to`
 - Analysis: `symbols diagnose`, `disasm`, `memory dump`, `memory strings`, `memory chase`, `stack recover`, `stack backtrace`
-- Platform helpers: `remote explain`, `dbgeng server`, `live launch`, `windbg status`
+- Platform helpers: `remote explain`, `dbgeng server`, `live launch`, `dump create`, `windbg status`
 
 For a fuller CLI walkthrough, output-shaping flags, and command map, see [the CLI guide](docs/cli.md).
 

crates/windbg-dbgeng/src/lib.rs

@@ -1,4 +1,4 @@
-use anyhow::Context;
+use anyhow::{bail, Context};
 use serde::Serialize;
 use std::path::PathBuf;
 
@@ -37,6 +37,27 @@ pub struct DumpOpenOptions {
     pub path: PathBuf,
 }
 
+#[derive(Debug, Clone)]
+pub struct DumpWriteOptions {
+    pub path: PathBuf,
+    pub kind: DumpKind,
+    pub overwrite: bool,
+}
+
+#[derive(Debug, Clone)]
+pub struct ProcessDumpOptions {
+    pub process_id: u32,
+    pub initial_break_timeout_ms: u32,
+    pub write: DumpWriteOptions,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum DumpKind {
+    Mini,
+    Full,
+}
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
 #[serde(rename_all = "snake_case")]
 pub enum LiveLaunchEnd {
@@ -61,6 +82,18 @@ pub struct LiveLaunchResult {
     pub end: LiveLaunchEnd,
 }
 
+#[derive(Debug, Clone, Serialize)]
+pub struct DumpWriteResult {
+    pub path: PathBuf,
+    pub kind: DumpKind,
+    pub qualifier: u32,
+    pub format_flags: u32,
+    pub overwrite: bool,
+    pub target: String,
+    pub process_id: Option<u32>,
+    pub detached: bool,
+}
+
 #[derive(Debug, Clone, Serialize)]
 pub struct DebuggerExecutionStatus {
     pub raw: Option<u32>,
@@ -196,6 +229,10 @@ pub fn open_dump_session(options: DumpOpenOptions) -> anyhow::Result<DebuggerSes
     open_dump_session_impl(options)
 }
 
+pub fn write_process_dump(options: ProcessDumpOptions) -> anyhow::Result<DumpWriteResult> {
+    write_process_dump_impl(options)
+}
+
 #[cfg(windows)]
 pub struct DebuggerSession {
     kind: DebuggerSessionKind,
@@ -281,6 +318,23 @@ impl DebuggerSession {
         Ok(())
     }
 
+    pub fn write_dump(&self, options: DumpWriteOptions) -> anyhow::Result<DumpWriteResult> {
+        if self.kind != DebuggerSessionKind::Live {
+            bail!("DbgEng dump writing requires a live target session");
+        }
+        write_dump_file(&self.client, &options)?;
+        Ok(DumpWriteResult {
+            path: options.path,
+            kind: options.kind,
+            qualifier: dump_kind_qualifier(options.kind),
+            format_flags: dump_format_flags(options.overwrite),
+            overwrite: options.overwrite,
+            target: self.target.clone(),
+            process_id: self.current_process_system_id().ok().or(self.process_id),
+            detached: false,
+        })
+    }
+
     pub fn core_registers(&self) -> anyhow::Result<CoreRegisterState> {
         let instruction_offset = unsafe { self.registers.GetInstructionOffset().ok() };
         let stack_offset = unsafe { self.registers.GetStackOffset().ok() };
@@ -699,6 +753,10 @@ impl DebuggerSession {
         anyhow::bail!("DbgEng sessions are only supported on Windows")
     }
 
+    pub fn write_dump(&self, _options: DumpWriteOptions) -> anyhow::Result<DumpWriteResult> {
+        anyhow::bail!("DbgEng dump writing is only supported on Windows")
+    }
+
     pub fn core_registers(&self) -> anyhow::Result<CoreRegisterState> {
         anyhow::bail!("DbgEng sessions are only supported on Windows")
     }
@@ -952,6 +1010,27 @@ fn open_dump_session_impl(options: DumpOpenOptions) -> anyhow::Result<DebuggerSe
     })
 }
 
+#[cfg(windows)]
+fn write_process_dump_impl(options: ProcessDumpOptions) -> anyhow::Result<DumpWriteResult> {
+    let session = attach_live_session_impl(LiveAttachOptions {
+        process_id: options.process_id,
+        initial_break_timeout_ms: options.initial_break_timeout_ms,
+    })?;
+    let write_result = session.write_dump(options.write);
+    let detach_result = session.detach();
+    match (write_result, detach_result) {
+        (Ok(mut result), Ok(())) => {
+            result.detached = true;
+            Ok(result)
+        }
+        (Ok(_), Err(error)) => Err(error).context("dump was written, but DbgEng detach failed"),
+        (Err(error), Ok(())) => Err(error),
+        (Err(write_error), Err(detach_error)) => Err(write_error).with_context(|| {
+            format!("DbgEng detach also failed after dump write failed: {detach_error}")
+        }),
+    }
+}
+
 #[cfg(windows)]
 fn read_wide_string<F>(mut reader: F) -> anyhow::Result<String>
 where
@@ -999,6 +1078,26 @@ fn debug_value_type_name(value_type: u32) -> &'static str {
     }
 }
 
+const DEBUG_DUMP_SMALL_VALUE: u32 = 1024;
+const DEBUG_DUMP_FULL_VALUE: u32 = 1026;
+const DEBUG_FORMAT_DEFAULT_VALUE: u32 = 0x0000_0000;
+const DEBUG_FORMAT_NO_OVERWRITE_VALUE: u32 = 0x8000_0000;
+
+fn dump_kind_qualifier(kind: DumpKind) -> u32 {
+    match kind {
+        DumpKind::Mini => DEBUG_DUMP_SMALL_VALUE,
+        DumpKind::Full => DEBUG_DUMP_FULL_VALUE,
+    }
+}
+
+fn dump_format_flags(overwrite: bool) -> u32 {
+    if overwrite {
+        DEBUG_FORMAT_DEFAULT_VALUE
+    } else {
+        DEBUG_FORMAT_NO_OVERWRITE_VALUE
+    }
+}
+
 fn encode_hex(bytes: &[u8]) -> String {
     let mut result = String::with_capacity(bytes.len() * 2);
     for byte in bytes {
@@ -1008,6 +1107,28 @@ fn encode_hex(bytes: &[u8]) -> String {
     result
 }
 
+#[cfg(windows)]
+fn write_dump_file(
+    client: &windows::Win32::System::Diagnostics::Debug::Extensions::IDebugClient5,
+    options: &DumpWriteOptions,
+) -> anyhow::Result<()> {
+    use windows::core::PCWSTR;
+
+    let path_string = options.path.to_string_lossy().to_string();
+    let mut path = path_string.encode_utf16().collect::<Vec<_>>();
+    path.push(0);
+    unsafe {
+        client.WriteDumpFileWide(
+            PCWSTR(path.as_ptr()),
+            0,
+            dump_kind_qualifier(options.kind),
+            dump_format_flags(options.overwrite),
+            PCWSTR(std::ptr::null()),
+        )?;
+    }
+    Ok(())
+}
+
 #[cfg(not(windows))]
 fn start_process_server_impl(options: ProcessServerOptions) -> anyhow::Result<ProcessServerResult> {
     let _ = options;
@@ -1037,3 +1158,26 @@ fn open_dump_session_impl(options: DumpOpenOptions) -> anyhow::Result<DebuggerSe
     let _ = options;
     anyhow::bail!("DbgEng dump sessions are only supported on Windows")
 }
+
+#[cfg(not(windows))]
+fn write_process_dump_impl(options: ProcessDumpOptions) -> anyhow::Result<DumpWriteResult> {
+    let _ = options;
+    anyhow::bail!("DbgEng dump writing is only supported on Windows")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn maps_dump_kinds_to_dbgeng_qualifiers() {
+        assert_eq!(dump_kind_qualifier(DumpKind::Mini), 1024);
+        assert_eq!(dump_kind_qualifier(DumpKind::Full), 1026);
+    }
+
+    #[test]
+    fn uses_no_overwrite_by_default() {
+        assert_eq!(dump_format_flags(false), 0x8000_0000);
+        assert_eq!(dump_format_flags(true), 0);
+    }
+}