Debian Codegraph @

cross-project-tests/debuginfo-tests/dexter/dex/debugger/dbgeng/README.md

raw
1 # Debugger Engine backend
2
3 This directory contains the Dexter backend for the Windows Debugger Engine
4 (DbgEng), which powers tools such as WinDbg and CDB.
5
6 ## Overview
7
8 DbgEng is available as a collection of unregistered COM-"like" objects that
9 one accesses by calling DebugCreate in DbgEng.dll. The unregistered nature
10 means normal COM tooling can't access them; as a result, this backend uses
11 ctypes to describe the COM objects and call their methods.
12
13 This is obviously not a huge amount of fun; on the other hand, COM has
14 maintained ABI compatible interfaces for decades, and nothing is for free.
15
16 The dexter backend follows the same formula as others; it creates a process
17 and breaks on "main", then steps through the program, observing states and
18 stack frames along the way.
19
20 ## Implementation details
21
22 This backend uses a mixture of both APIs for accessing information, and the
23 direct command-string interface to DbgEng for performing some actions. We
24 have to use the DbgEng stepping interface, or we would effectively be
25 building a new debugger, but certain things (like enabling source-line
26 stepping) only seem to be possible from the command interface.
27
28 Each segment of debugger responsibility has its own COM object: Client,
29 Control, Symbols, SymbolGroups, Breakpoint, SystemObjects. In this python
30 wrapper, each COM object gets a python object wrapping it. COM methods
31 that are relevant to our interests have a python method that wraps the COM
32 one and performs data marshalling. Some additional helper methods are added
33 to the python objects to extract data.
34
35 The majority of the work occurs in setup.py and probe_process.py. The
36 former contains routines to launch a process and attach the debugger to
37 it, while the latter extracts as much information as possible from a
38 stopped process, returning a list of stack frames with associated variable
39 information.
40
41 ## Sharp edges
42
43 On process startup, we set a breakpoint on main and then continue running
44 to it. This has the potential to never complete -- although of course,
45 there's no guarantee that the debuggee will ever do anything anyway.
46
47 There doesn't appear to be a way to instruct DbgEng to "step into" a
48 function call, thus after reaching main, we scan the module for all
49 functions with line numbers in the source directory, and put breakpoints
50 on them. An alternative implementation would be putting breakpoints on
51 every known line number.
52
53 Finally, it's unclear whether arbitrary expressions can be evaluated in
54 arbitrary stack frames, although this isn't something that Dexter currently
55 supports.
56