PrologWinDbg

Una extensión nativa de WinDbg para x64 y ARM64 con un trabajador persistente de SWI-Prolog. Expone hilos, marcos de pila, símbolos, módulos cargados y memoria desde un volcado de modo usuario o un proceso nativo x64 o ARM64 detenido. Cargue sus propios archivos Prolog y ejecute consultas desde la ventana de comandos del depurador.

Versión: 0.2.0 (experimental; soporte nativo para ARM64).

Utilice la DLL compilada para la arquitectura de su depurador. El depurador, la DLL y el objetivo nativo deben coincidir: x64/AMD64 juntos o ARM64 juntos. Los contextos de ámbito entre arquitecturas, WOW64, ARM32 y los objetivos ARM64EC están fuera del alcance de esta versión. Las compilaciones nativas x64 y ARM64 superaron las 99 comprobaciones portables y las pruebas de humo de volcado/en vivo de CDB. Consulte docs/VALIDATION.md para la ejecución, los registros y las comprobaciones manuales restantes.

Inicio rápido

El repositorio de código fuente no contiene binarios compilados. Compílelo usando las instrucciones de Windows a continuación para poblar dist/x64/ o dist/arm64/. Los archivos de lanzamiento se denominan PrologWinDbg-v0.2.0-win-x64.zip y PrologWinDbg-v0.2.0-win-arm64.zip; cada uno coloca sus binarios seleccionados en dist/. Los ejemplos a continuación usan esa estructura del archivo de lanzamiento. Para una compilación desde el código fuente, sustituya dist/arm64 o dist/x64 en las rutas.

1. Instale la versión de consola para Windows de SWI-Prolog. Los instaladores nativos para ARM64 están disponibles en las descargas de desarrollo. La matriz de CI usa SWI-Prolog nativo 10.1.18-1 en ambas arquitecturas. SWI se ejecuta como un proceso separado; no está enlazado ni incluido en la DLL.

2. Mantenga dist/prolog.dll junto con los directorios dist/prolog y dist/examples.

3. Abra un volcado nativo de modo usuario en el WinDbg x64 o ARM64 correspondiente, o adjúntese a un proceso nativo de esa arquitectura e interrúmpalo. Para obtener un volcado reproducible, ejecute esto en PowerShell:

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

4. En WinDbg, reemplaza estas rutas con la ruta real de tu directorio de proyecto. Usa barras inclinadas en las rutas entre comillas: el depurador trata las barras invertidas como 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).
   

La extensión utiliza la ruta de tiempo de ejecución explícita, la variable de entorno PROLOGDBG_SWIPL, o la instalación estándar Program Files\swipl\bin\swipl.exe. Inicia el worker cuando es necesario por primera vez. Toda la comunicación utiliza pipes locales.

Para el objetivo proporcionado, inspeccione el marcador conocido de ocho bytes:

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

Veredicto esperado: matched(prologdb, Address). Los bytes del marcador deletrean PROLOGDB. El objetivo exporta estos nombres, por lo que este ejemplo no requiere un PDB. Los PDB privados son útiles para otras funciones y aplicaciones.

Depuración en vivo

Inicie prologdbg_target.exe --live bajo WinDbg. Continúe más allá del punto de interrupción inicial del cargador. A continuación, el objetivo se detiene en CapturePoint después de que se hayan iniciado dos hilos de trabajo. Utilice las mismas consultas que para un volcado.

Como alternativa, ejecute prologdbg_target.exe --wait, adjúntese a su PID impreso y deténgase en él. Este modo finaliza después de diez minutos si no se detiene antes.

Utilice los comandos normales de WinDbg bp, g, p y t para controlar la ejecución. Cada !prolog.query recopila una instantánea nueva. Las acciones de punto de interrupción de Prolog registradas y la continuación automática están previstas para una versión posterior.

Comandos

Comando	Propósito
!prolog.help	Mostrar la ayuda de comandos
!prolog.runtime "ruta absoluta a swipl.exe"	Seleccionar el runtime y detener cualquier worker existente
!prolog.info	Iniciar el worker e informar su versión
!prolog.consult "ruta absoluta a rules.pl"	Cargar o recargar el código fuente de Prolog
!prolog.query Goal.	Recopilar evidencia y enumerar soluciones
!prolog.queryfile "ruta absoluta a goal.txt"	Leer un único objetivo UTF-8 desde un archivo y luego consultar
!prolog.eval Goal.	Evaluar Prolog sin evidencia del depurador
!prolog.limits	Mostrar los límites actuales
!prolog.limits 5000 100 128 10000000	Establecer milisegundos, número de respuestas, frames por hilo y límite de inferencias
!prolog.reset	Detener el worker; las reglas cargadas y el estado personalizado del runtime se pierden

Los objetivos simples se pasan directamente después del comando. Las comillas simples estándar de Prolog delimitan átomos. Puede omitir el punto final. Utilice un objetivo por comando, uniendo subobjetivos con comas. Para la disyunción de Prolog (;), encierre el objetivo completo entre comillas dobles para protegerlo del separador de comandos de WinDbg:

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

Para citas complejas, texto Unicode u objetivos multilínea, coloque el objetivo en un archivo de texto UTF-8 y use !prolog.queryfile "C:/rules/goal.txt". Su contenido va directamente a Prolog, omitiendo el análisis del texto de comando de WinDbg. El límite del archivo es de 1 MiB. Para lógica reutilizable, defina predicados en un archivo .pl consultado.

Ejemplo sin un objetivo:

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

Las respuestas se imprimen como bindings([Name=Value, ...], ResidualGoals). La segunda lista conserva las restricciones residuales. Un estado final distingue entre búsqueda agotada, fallo, límites de respuestas, límites de inferencia, tiempos de espera y excepciones. Alcanzar un límite de respuestas no afirma que existan más soluciones.

Consultar un archivo ejecuta la carga e inicialización normales de Prolog. Los errores de carga se informan, pero la carga de Prolog no es transaccional: algunas cláusulas pueden haberse cargado antes de un error. Corrija y recargue el archivo, o reinicie el worker.

Escribir una regla

:- 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, _).

Luego:

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

Consulta docs/API.md para los modos de predicado y la semántica de evidencia. Las reglas iniciales proporcionan coincidencia de pila, funciones compartidas entre hilos, evidencia explícita de pila, direcciones ilegibles y un diagnóstico de firma de memoria con un resultado no concluyente.

Límites y cancelación

El presupuesto de consulta predeterminado es de 5 segundos, 100 respuestas, 128 marcos por hilo y 10 millones de inferencias. La recopilación de instantáneas recibe su propio presupuesto de tiempo del mismo tamaño. La carga inicial de símbolos puede ser lenta: calienta la caché de símbolos o eleva el primer valor con !prolog.limits.