Skip to content

Commit 1b6df05

Browse files
committedMar 21, 2022
README: add python binding instructions
1 parent dea7b42 commit 1b6df05

File tree

1 file changed

+44
-1
lines changed

1 file changed

+44
-1
lines changed
 

‎README.md

+44-1
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ Bindings (PoC) for [Microsoft WinDBG Time Travel Debugging (TTD)](https://docs.m
1010
* `example_api/` highlights some of the wrapping
1111
* `example_diff/` shows how to use the wrapping to perform naive trace diffing
1212
* `example_calltree/` produces a call tree of a trace excerpt
13+
* `python-bindings/` provides Python bindings over TTD
1314

1415
After performing one or several traces using Windbg Preview, one can open the `.run` file:
1516
```C++
@@ -275,8 +276,50 @@ ModuleList:
275276
...
276277
```
277278

279+
## Python
280+
281+
### Setup
282+
283+
Either:
284+
285+
* use the latest `pyTTD.pyd` [release](https://github.com/commial/ttd-bindings/releases/latest)
286+
* or compile the `python-bindings` project.
287+
288+
### Usage
289+
290+
With `pyTTD.pyd`, `TTDReplay.dll` and `TTDReplayCPU.dll` in the directory, one can import `pyTTD`:
291+
292+
```python
293+
import pyTTD
294+
295+
# Open the trace
296+
eng = pyTTD.ReplayEngine()
297+
eng.initialize("D:\\traces\\trace.run")
298+
299+
# Get positions
300+
first = eng.get_first_position()
301+
last = eng.get_last_position()
302+
print(f"Trace from {first} to {last}")
303+
304+
# Get a cursor
305+
cursor = eng.new_cursor()
306+
cursor.set_position(first)
307+
308+
# Retrieve PC
309+
print(f"PC: {cursor.get_program_counter():x}")
310+
311+
# Print RCX
312+
ctxt = cursor.get_crossplatform_context()
313+
print("RCX: %x" % ctxt.rcx)
314+
315+
# Read the memory at RCX on 16 bytes
316+
print("@128[RCX]: %s" % cursor.read_mem(ctxt.rcx, 16))
317+
```
318+
319+
More API example are available in `example_api/example_api.py`.
320+
278321
## References
279322

280323
* [MSDN - Time Travel Debugging - Overview](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/time-travel-debugging-overview)
281324
* [TTD analysis](https://www.synacktiv.com/ressources/rumpinrennes-ttd.pdf) by @w4kfu at Rump'in Rennes 2019
282-
* [Initial iDNA paper](https://www.usenix.org/legacy/events/vee06/full_papers/p154-bhansali.pdf) : S. Bhansali, W.-K. Chen, S. de Jong, A. Edwards, R. Murray, M. Drinic, D. Mihocka, and J. Chau. Framework for "Instruction-level tracing and analysis of program executions" in VEE, 2006.
325+
* [Initial iDNA paper](https://www.usenix.org/legacy/events/vee06/full_papers/p154-bhansali.pdf) : S. Bhansali, W.-K. Chen, S. de Jong, A. Edwards, R. Murray, M. Drinic, D. Mihocka, and J. Chau. Framework for "Instruction-level tracing and analysis of program executions" in VEE, 2006.

0 commit comments

Comments
 (0)