PrologWinDbg

A native x64 and ARM64 WinDbg extension with a persistent SWI-Prolog worker. It exposes threads, stack frames, symbols, loaded modules, and memory from a user-mode dump or a stopped native x64 or ARM64 process. Load your own Prolog files and run queries from the debugger command window.

Version: 0.2.0 (experimental; native ARM64 support).

Use the DLL built for your debugger's architecture. The debugger, DLL, and native target must match: x64/AMD64 together or ARM64 together. Cross-architecture scope contexts, WOW64, ARM32, and ARM64EC targets are outside this release's scope. Native x64 and ARM64 builds passed all 99 portable checks and CDB dump/live smoke tests. See docs/VALIDATION.md for the run, logs, and remaining manual checks.

Quick start

The source repository does not contain compiled binaries. Build it using the Windows instructions below to populate dist/x64/ or dist/arm64/. Release archives are named PrologWinDbg-v0.2.0-win-x64.zip and PrologWinDbg-v0.2.0-win-arm64.zip; each puts its selected binaries in dist/. The examples below use that release archive layout. For a source build, substitute dist/arm64 or dist/x64 in the paths.

1. Install the Windows console version of SWI-Prolog. Native ARM64 installers are available from the development downloads. The CI matrix uses native SWI-Prolog 10.1.18-1 on both architectures. SWI runs as a separate process; it is not linked into or bundled with the DLL.

2. Keep dist/prolog.dll together with the dist/prolog and dist/examples directories.

3. Open a native user-mode dump in the matching x64 or ARM64 WinDbg, or attach to a native process of that architecture and break into it. For a reproducible dump, run this in PowerShell:

   .\dist\prologdbg_target.exe --dump C:\Temp\prologdbg-sample.dmp
   

4. In WinDbg, replace these paths with your actual project directory. Use forward slashes in quoted paths: the debugger treats backslashes as escapes.

   .load C:/PrologWinDbg/dist/prolog.dll
   !prolog.runtime "C:/Program Files/swipl/bin/swipl.exe"
   !prolog.info
   !prolog.consult "C:/PrologWinDbg/dist/examples/patterns.pl"
   !prolog.query wd:current_snapshot(S), wd:architecture(S,Architecture).
   !prolog.query wd:current_snapshot(S), wd:thread_id(S,T,WindowsTid).
   !prolog.query wd:current_snapshot(S), wd:stack_frame(S,T,Depth,IP).
   !prolog.query wd:current_snapshot(S), patterns:stack_contains(S,T,Module,Function).
   

The extension uses the explicit runtime path, PROLOGDBG_SWIPL environment variable, or the standard Program Files\swipl\bin\swipl.exe installation. It starts the worker when first needed. All communication uses local pipes.

For the supplied target, inspect the known eight-byte marker:

!prolog.query wd:current_snapshot(S), wd:lookup(S,'prologdbg_target!g_magic',ok(A)), patterns:inspect_magic(S,A,Verdict).

Expected verdict: matched(prologdb, Address). The marker bytes spell PROLOGDB. The target exports these names, so this example does not require a PDB. Private PDBs are useful for other functions and applications.

Live debugging

Launch prologdbg_target.exe --live under WinDbg. Continue past the initial loader breakpoint. The target then breaks at CapturePoint after two worker threads have started. Use the same queries as for a dump.

Alternatively, run prologdbg_target.exe --wait, attach to its printed PID, and break in. This mode exits after ten minutes if not stopped earlier.

Use normal WinDbg bp, g, p, and t commands to control execution. Every !prolog.query collects a fresh snapshot. Registered Prolog breakpoint actions and automatic continuation are planned for a later version.

Commands

Command	Purpose
!prolog.help	Display command help
!prolog.runtime "absolute path to swipl.exe"	Select runtime and stop any existing worker
!prolog.info	Start the worker and report its version
!prolog.consult "absolute path to rules.pl"	Load or reload Prolog source
!prolog.query Goal.	Collect evidence and enumerate solutions
!prolog.queryfile "absolute path to goal.txt"	Read a single UTF-8 goal from a file, then query
!prolog.eval Goal.	Evaluate Prolog with no debugger evidence
!prolog.limits	Display current limits
!prolog.limits 5000 100 128 10000000	Set milliseconds, answer count, frames per thread, and inference limit
!prolog.reset	Stop the worker; loaded rules and custom runtime state are lost

Simple goals are passed directly after the command. Standard Prolog single quotes delimit atoms. You may omit the final period. Use one goal per command, joining subgoals with commas. For Prolog disjunction (;), enclose the whole goal in double quotes to protect it from WinDbg's command separator:

!prolog.eval "(X=a;X=b), writeln(X)."

For complex quoting, Unicode text, or multiline goals, put the goal in a UTF-8 text file and use !prolog.queryfile "C:/rules/goal.txt". Its contents go directly to Prolog, bypassing WinDbg's command-text parsing. The file limit is 1 MiB. For reusable logic, define predicates in a consulted .pl file.

Example without a target:

!prolog.eval member(X,[1,2,3]), Y is X*X.

Answers are printed as bindings([Name=Value, ...], ResidualGoals). The second list preserves residual constraints. A final status distinguishes exhausted search, failure, answer limits, inference limits, timeouts, and exceptions. Reaching an answer limit does not assert that more solutions exist.

Consulting a file runs normal Prolog loading and initialization. Load errors are reported, but Prolog loading is not transactional: some clauses can have loaded before an error. Correct and reload the file, or reset the worker.

Write a rule

:- module(my_rules, [in_function/4]).
:- use_module('C:/PrologWinDbg/dist/prolog/wd.pl').

in_function(S, T, Module, Function) :-
    wd:stack_frame(S, T, _, IP),
    wd:symbol(S, IP, Module, Function, _).

Then:

!prolog.consult "C:/rules/my_rules.pl"
!prolog.query wd:current_snapshot(S), my_rules:in_function(S,T,myapp,'ProcessRequest').

See docs/API.md for predicate modes and evidence semantics. The initial rules provide stack matching, shared functions across threads, explicit stack evidence, unreadable addresses, and a memory-signature diagnosis with an inconclusive result.

Bounds and cancellation

The default query budget is 5 seconds, 100 answers, 128 frames per thread, and 10 million inferences. Snapshot collection receives its own time budget of the same size. Initial symbol loading can be slow: warm the symbol cache or raise the first value with !prolog.limits.

Memory requests are at most 64 KiB each and 16 MiB total per query. Snapshot capture is capped at 4,096 threads, 4,096 loaded modules, and 8 MiB of fact text. The worker uses a 512 MiB Prolog stack limit and a 768 MiB Windows process-memory limit. The native bridge also limits output, RPC count, and IPC wait time.

Use WinDbg's Break action / Ctrl+Break to interrupt a command. While waiting on the worker or walking snapshot items, the extension checks GetInterrupt. Interrupted IPC resets the worker; consult your rules again afterward. Normal Prolog time/inference limits preserve the worker. A !prolog.reset command is usable after the current command has returned; it is not a concurrent cancel command.

Individual DbgEng calls, especially symbol loading and remote reads, are synchronous. The extension checks elapsed time and interruption between calls; it cannot promise a hard deadline while DbgEng itself is blocked.

Manual interruption check:

!prolog.limits 600000 100 128 1000000000
!prolog.eval sleep(300).