Skip to content

Commit

Permalink
Update the debugger docs for the memory region API change
Browse files Browse the repository at this point in the history
  • Loading branch information
xusheng6 committed Jun 19, 2024
1 parent 7a47a1a commit 46631b6
Show file tree
Hide file tree
Showing 2 changed files with 9 additions and 24 deletions.
33 changes: 9 additions & 24 deletions docs/guide/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -226,26 +226,19 @@ Right now, the debugger comes with two debug adapters. The `LLDBAdapter` uses [L

New debug adapters can be created by subclassing `DebugAdapter` to support other targets.

Remote debugging is a planned feature. Specifically, the capacity to connect to a target via [RSP protocol](https://sourceware.org/gdb/current/onlinedocs/gdb/Remote-Protocol.html) is already baked into the LLDBAdapter, though not tested.

### The Debugger Memory Region

### The Debugger BinaryView
Starting from 4.1.5542-dev (0ad6b08b), the debugger no longer involves two binary views during debugging. Instead,
it always uses the incoming binary view (e.g., PE view) that is used to create the controller. Memory regions
that are not present in the original binary view are represented using the new Memory Map/Region API.

To represent the memory space of the target, the debugger creates a specialized `BinaryView` called `DebugProcessView`. Throughout this document, it is also called the `Debugger` BinaryView.
These regions get added automatically when the target is launched, and gets removed after debugging. Analysis is no longer lost after debugging.

[//]: # (On the other hand, there is a `base` BinaryView that is the BinaryView used to create the debugger. The base binaryView gets rebased to the correct location when the target launches. )
During debugging, the binary view reads and writes its memory from the connected `DebugAdapter` backend.
Writing to it will also cause the target's memory to change.

The Debugger BinaryView reads and writes its memory from the connected `DebugAdapter`. To save on data transfer, the debugger caches all read operations from the adapter. Whenever the debugger executes instructions or writes data, the cached data is cleared.

When the target is launched, the debugger automatically switches the view to the Debugger BinaryView.

![](../../img/debugger/debuggerview.png)

The debugger automatically applies all analysis data to the Debugger BinaryView, including functions and types, etc. This means the user can conveniently use types that are present in the static analysis.

The Debugger BinaryView can be accessed by `dbg.live_view` once the target is launched. You can read/write to it in the normal way. Writing to it will also cause the target's memory to change.

Right now, the Debugger BinaryView is discarded once the target exits. It cannot be easily reused due to ASLR, which makes the base of the program different in each run. As a result, any changes the user made to the Debugger BinaryView will be discarded after the target exits.
The binary view can be accessed by the ``data`` property of the controller.

## API

Expand Down Expand Up @@ -304,7 +297,7 @@ There are several ways to launch the target:
### View/Edit Memory

- Switch to Linear or hex view of the Debugger BinaryView, and view/edit in the normal way
- Get the Debugger BinaryView by `dbg.live_view`, and read/write it in the normal way
- Get the BinaryView by `dbg.data`, and read/write it in the normal way


### Navigating the binary
Expand Down Expand Up @@ -363,14 +356,6 @@ If the target contains self-modifying code (SMC), when the target stops, the cod
To avoid the need to manually force an update frequently, set `debugger.aggressiveAnalysisUpdate` to true. Then the debugger will explicitly refresh the memory cache and re-analyze all functions every time the target stops. This is very helpful for obfuscated code with lots of SMC. However, it could cause lag in response if the target is large and has a lot of functions.


### Changes made to the debugger binary view are lost after debugging

Any changes, e.g., annotations, comments, are lost after the target exits. This is because the debugger binary view is a separate binary view, and edits to it would not carry over to the original binary view.
As a temporary workaround, try to apply changes to the original binary view, whose changes will always be carried over to the debugger binary view when the target launches.

We are also working on [an issue](https://github.com/Vector35/debugger/issues/213) which will resolve the problem by offering a viable way to selectively carry over some changes made to the debugger binary view to the original binary view.


## Troubleshooting

While we have tested the debugger in many scenarios, it may still malfunction in certain cases. Here are some basic steps to troubleshoot the situation.
Expand Down
Binary file removed docs/img/debugger/debuggerview.png
Binary file not shown.

0 comments on commit 46631b6

Please sign in to comment.