Skip to content

Commit cfdddf0

Browse files
claudesdimitro
authored andcommitted
Add virtual address documentation to quickstart guide
Document the new virt_addr parameter for add_memory_segment() with examples showing how to use it with drgn for virtual address reads. https://claude.ai/code/session_018wj4HefWHH9naQ29a4pwr8
1 parent ca3343c commit cfdddf0

File tree

1 file changed

+42
-0
lines changed

1 file changed

+42
-0
lines changed

docs/quickstart.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -188,6 +188,48 @@ data = io.BytesIO(b'\xff' * 4096)
188188
builder.add_memory_segment(0x3000, data)
189189
```
190190

191+
## Virtual Address Support
192+
193+
Memory segments can have both physical and virtual addresses. This is useful when
194+
creating vmcores from tools that capture memory by virtual address (like debuggers
195+
or tracing tools), allowing drgn to read memory by virtual address directly.
196+
197+
```python
198+
from kdumpling import KdumpBuilder
199+
200+
builder = KdumpBuilder(arch='x86_64')
201+
builder.set_vmcoreinfo("OSRELEASE=5.14.0\n")
202+
203+
# Segment with explicit virtual address (kernel direct mapping)
204+
builder.add_memory_segment(
205+
phys_addr=0x100000,
206+
data=memory_data,
207+
virt_addr=0xffff888000100000
208+
)
209+
210+
# Segment without virt_addr (defaults to phys_addr)
211+
builder.add_memory_segment(phys_addr=0x200000, data=other_data)
212+
213+
builder.write("with_vaddr.vmcore")
214+
```
215+
216+
When loaded with drgn, memory can be read by virtual address:
217+
218+
```python
219+
import drgn
220+
221+
prog = drgn.Program()
222+
prog.set_core_dump("with_vaddr.vmcore")
223+
224+
# Read using the virtual address
225+
data = prog.read(0xffff888000100000, 4096)
226+
```
227+
228+
This is particularly useful for:
229+
- **Debugger integrations**: Tools like SDB that record memory by virtual address
230+
- **Kernel memory captures**: Preserving the kernel's view of memory layout
231+
- **Replay scenarios**: Re-creating the exact virtual address space for analysis
232+
191233
## Validating with drgn
192234

193235
You can verify the generated vmcore using [drgn](https://github.com/osandov/drgn):

0 commit comments

Comments
 (0)