Skip to content

Commit a37e8fe

Browse files
xusheng6xusheng6
authored
Document the target memory map being mirrored as segments (#1120) (#1183)
1 parent 9494abf commit a37e8fe

1 file changed

Lines changed: 42 additions & 0 deletions

File tree

‎docs/guide/index.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -399,6 +399,28 @@ Writing to it will also cause the target's memory to change.
399399

400400
The binary view can be accessed by the ``data`` property of the controller.
401401

402+
Starting from 5.4.10157-dev (aba9ec4), when the debug adapter reports a memory map, these regions mirror it: one bounded
403+
region per mapped range, each with the target's page permissions, instead of a single region spanning the entire address
404+
space. They are listed as `debugger:<N>` in the Memory Map sidebar:
405+
406+
![](../../img/debugger/memory_map_segments.png)
407+
408+
This is what makes `Find` work while debugging: search only scans the ranges the binary view has backed, so bounded
409+
regions let it skip the unmapped gaps. A single region covering the whole 64-bit address space cannot bound a search, so
410+
search is disabled there.
411+
412+
The regions are refreshed when the target stops, but only rebuilt if the map changed, and they are removed when the
413+
target exits or you detach. LLDB, DbgEng, Windows Native, GDB, and GDB MI report a memory map; adapters that do not keep
414+
using the single whole-address-space region.
415+
416+
The `debugger.useMemoryMapSegments` setting (`Apply the target memory map as segments`, enabled by default) selects
417+
between the two models. Disable it to always use the single region, which is worth doing for a target with so many
418+
mappings that rebuilding them slows down each stop. It is read when the session starts, so a change applies to the next
419+
launch/attach.
420+
421+
The map is also available from the API, see [Reading the Target Memory Map](#reading-the-target-memory-map).
422+
423+
402424
## API
403425

404426
The debugger exposes its functionality in both the Python and C++ APIs. The Python documentation can be accessed online, for [stable](https://api.binary.ninja/binaryninja.debugger.debuggercontroller-module.html)
@@ -798,6 +820,26 @@ controller.remove_all_loaded_symbols()
798820

799821
The symbols are added as auto symbols and are tracked internally, so they can be removed cleanly and are cleared automatically when the target exits or you detach.
800822

823+
### Reading the Target Memory Map
824+
825+
The target's memory map -- every mapped range with its permissions -- is available from the controller. This is the map
826+
the debugger mirrors into the binary view, see [The Debugger Memory Region](#the-debugger-memory-region).
827+
828+
```python
829+
from binaryninja.debugger import DebuggerController
830+
831+
controller = DebuggerController(bv)
832+
# ... launch or attach, and stop the target ...
833+
834+
# Refreshed when the target stops. Empty for adapters that do not report a memory map.
835+
for region in controller.memory_map:
836+
perm = f"{'r' if region.read else '-'}{'w' if region.write else '-'}{'x' if region.execute else '-'}"
837+
print(f"{region.start:#x}-{region.start + region.size:#x} {perm} {region.name}")
838+
```
839+
840+
A region's `name` is its backing: a file path, a name such as `[stack]` or `[heap]` where the backend provides one, or
841+
empty for anonymous mappings.
842+
801843
### Listing Symbol At/Near an Address
802844

803845
To check the symbol at or near a specific address without loading a module's symbols into the Binary View, you can run a backend command directly.

0 commit comments

Comments
 (0)