2 This python script adds a new gdb command, "dump-guest-memory". It
3 should be loaded with "source dump-guest-memory.py" at the (gdb)
6 Copyright (C) 2013, Red Hat, Inc.
9 Laszlo Ersek <lersek@redhat.com>
10 Janosch Frank <frankja@linux.vnet.ibm.com>
12 This work is licensed under the terms of the GNU GPL, version 2 or later. See
13 the COPYING file in the top-level directory.
20 UINTPTR_T
= gdb
.lookup_type("uintptr_t")
21 except Exception as inst
:
22 raise gdb
.GdbError("Symbols must be loaded prior to sourcing dump-guest-memory.\n"
23 "Symbols may be loaded by 'attach'ing a QEMU process id or by "
24 "'load'ing a QEMU binary.")
26 TARGET_PAGE_SIZE
= 0x1000
27 TARGET_PAGE_MASK
= 0xFFFFFFFFFFFFF000
29 # Special value for e_phnum. This indicates that the real number of
30 # program headers is too large to fit into e_phnum. Instead the real
31 # value is in the field sh_info of section 0.
54 VMCOREINFO_FORMAT_ELF
= 1
57 return struct
.unpack("<H", struct
.pack("=H", val
))[0]
60 return struct
.unpack("<I", struct
.pack("=I", val
))[0]
63 return struct
.unpack("<Q", struct
.pack("=Q", val
))[0]
66 """Representation of a ELF file."""
68 def __init__(self
, arch
):
73 self
.endianness
= None
74 self
.elfclass
= ELFCLASS64
76 if arch
== 'aarch64-le':
77 self
.endianness
= ELFDATA2LSB
78 self
.elfclass
= ELFCLASS64
79 self
.ehdr
= get_arch_ehdr(self
.endianness
, self
.elfclass
)
80 self
.ehdr
.e_machine
= EM_AARCH
82 elif arch
== 'aarch64-be':
83 self
.endianness
= ELFDATA2MSB
84 self
.ehdr
= get_arch_ehdr(self
.endianness
, self
.elfclass
)
85 self
.ehdr
.e_machine
= EM_AARCH
87 elif arch
== 'X86_64':
88 self
.endianness
= ELFDATA2LSB
89 self
.ehdr
= get_arch_ehdr(self
.endianness
, self
.elfclass
)
90 self
.ehdr
.e_machine
= EM_X86_64
93 self
.endianness
= ELFDATA2LSB
94 self
.elfclass
= ELFCLASS32
95 self
.ehdr
= get_arch_ehdr(self
.endianness
, self
.elfclass
)
96 self
.ehdr
.e_machine
= EM_386
99 self
.endianness
= ELFDATA2MSB
100 self
.ehdr
= get_arch_ehdr(self
.endianness
, self
.elfclass
)
101 self
.ehdr
.e_machine
= EM_S390
103 elif arch
== 'ppc64-le':
104 self
.endianness
= ELFDATA2LSB
105 self
.ehdr
= get_arch_ehdr(self
.endianness
, self
.elfclass
)
106 self
.ehdr
.e_machine
= EM_PPC64
108 elif arch
== 'ppc64-be':
109 self
.endianness
= ELFDATA2MSB
110 self
.ehdr
= get_arch_ehdr(self
.endianness
, self
.elfclass
)
111 self
.ehdr
.e_machine
= EM_PPC64
114 raise gdb
.GdbError("No valid arch type specified.\n"
115 "Currently supported types:\n"
116 "aarch64-be, aarch64-le, X86_64, 386, s390, "
117 "ppc64-be, ppc64-le")
119 self
.add_segment(PT_NOTE
, 0, 0)
121 def add_note(self
, n_name
, n_desc
, n_type
):
122 """Adds a note to the ELF."""
124 note
= get_arch_note(self
.endianness
, len(n_name
), len(n_desc
))
125 note
.n_namesz
= len(n_name
) + 1
126 note
.n_descsz
= len(n_desc
)
127 note
.n_name
= n_name
.encode()
130 # Desc needs to be 4 byte aligned (although the 64bit spec
131 # specifies 8 byte). When defining n_desc as uint32 it will be
132 # automatically aligned but we need the memmove to copy the
134 ctypes
.memmove(note
.n_desc
, n_desc
.encode(), len(n_desc
))
136 self
.notes
.append(note
)
137 self
.segments
[0].p_filesz
+= ctypes
.sizeof(note
)
138 self
.segments
[0].p_memsz
+= ctypes
.sizeof(note
)
141 def add_vmcoreinfo_note(self
, vmcoreinfo
):
142 """Adds a vmcoreinfo note to the ELF dump."""
143 # compute the header size, and copy that many bytes from the note
144 header
= get_arch_note(self
.endianness
, 0, 0)
145 ctypes
.memmove(ctypes
.pointer(header
),
146 vmcoreinfo
, ctypes
.sizeof(header
))
147 if header
.n_descsz
> 1 << 20:
148 print('warning: invalid vmcoreinfo size')
150 # now get the full note
151 note
= get_arch_note(self
.endianness
,
152 header
.n_namesz
- 1, header
.n_descsz
)
153 ctypes
.memmove(ctypes
.pointer(note
), vmcoreinfo
, ctypes
.sizeof(note
))
155 self
.notes
.append(note
)
156 self
.segments
[0].p_filesz
+= ctypes
.sizeof(note
)
157 self
.segments
[0].p_memsz
+= ctypes
.sizeof(note
)
159 def add_segment(self
, p_type
, p_paddr
, p_size
):
160 """Adds a segment to the elf."""
162 phdr
= get_arch_phdr(self
.endianness
, self
.elfclass
)
164 phdr
.p_paddr
= p_paddr
165 phdr
.p_vaddr
= p_paddr
166 phdr
.p_filesz
= p_size
167 phdr
.p_memsz
= p_size
168 self
.segments
.append(phdr
)
169 self
.ehdr
.e_phnum
+= 1
171 def to_file(self
, elf_file
):
172 """Writes all ELF structures to the passed file.
182 elf_file
.write(self
.ehdr
)
183 off
= ctypes
.sizeof(self
.ehdr
) + \
184 len(self
.segments
) * ctypes
.sizeof(self
.segments
[0])
186 for phdr
in self
.segments
:
191 for note
in self
.notes
:
195 def get_arch_note(endianness
, len_name
, len_desc
):
196 """Returns a Note class with the specified endianness."""
198 if endianness
== ELFDATA2LSB
:
199 superclass
= ctypes
.LittleEndianStructure
201 superclass
= ctypes
.BigEndianStructure
203 len_name
= len_name
+ 1
205 class Note(superclass
):
206 """Represents an ELF note, includes the content."""
208 _fields_
= [("n_namesz", ctypes
.c_uint32
),
209 ("n_descsz", ctypes
.c_uint32
),
210 ("n_type", ctypes
.c_uint32
),
211 ("n_name", ctypes
.c_char
* len_name
),
212 ("n_desc", ctypes
.c_uint32
* ((len_desc
+ 3) // 4))]
216 class Ident(ctypes
.Structure
):
217 """Represents the ELF ident array in the ehdr structure."""
219 _fields_
= [('ei_mag0', ctypes
.c_ubyte
),
220 ('ei_mag1', ctypes
.c_ubyte
),
221 ('ei_mag2', ctypes
.c_ubyte
),
222 ('ei_mag3', ctypes
.c_ubyte
),
223 ('ei_class', ctypes
.c_ubyte
),
224 ('ei_data', ctypes
.c_ubyte
),
225 ('ei_version', ctypes
.c_ubyte
),
226 ('ei_osabi', ctypes
.c_ubyte
),
227 ('ei_abiversion', ctypes
.c_ubyte
),
228 ('ei_pad', ctypes
.c_ubyte
* 7)]
230 def __init__(self
, endianness
, elfclass
):
232 self
.ei_mag1
= ord('E')
233 self
.ei_mag2
= ord('L')
234 self
.ei_mag3
= ord('F')
235 self
.ei_class
= elfclass
236 self
.ei_data
= endianness
237 self
.ei_version
= EV_CURRENT
240 def get_arch_ehdr(endianness
, elfclass
):
241 """Returns a EHDR64 class with the specified endianness."""
243 if endianness
== ELFDATA2LSB
:
244 superclass
= ctypes
.LittleEndianStructure
246 superclass
= ctypes
.BigEndianStructure
248 class EHDR64(superclass
):
249 """Represents the 64 bit ELF header struct."""
251 _fields_
= [('e_ident', Ident
),
252 ('e_type', ctypes
.c_uint16
),
253 ('e_machine', ctypes
.c_uint16
),
254 ('e_version', ctypes
.c_uint32
),
255 ('e_entry', ctypes
.c_uint64
),
256 ('e_phoff', ctypes
.c_uint64
),
257 ('e_shoff', ctypes
.c_uint64
),
258 ('e_flags', ctypes
.c_uint32
),
259 ('e_ehsize', ctypes
.c_uint16
),
260 ('e_phentsize', ctypes
.c_uint16
),
261 ('e_phnum', ctypes
.c_uint16
),
262 ('e_shentsize', ctypes
.c_uint16
),
263 ('e_shnum', ctypes
.c_uint16
),
264 ('e_shstrndx', ctypes
.c_uint16
)]
267 super(superclass
, self
).__init
__()
268 self
.e_ident
= Ident(endianness
, elfclass
)
269 self
.e_type
= ET_CORE
270 self
.e_version
= EV_CURRENT
271 self
.e_ehsize
= ctypes
.sizeof(self
)
272 self
.e_phoff
= ctypes
.sizeof(self
)
273 self
.e_phentsize
= ctypes
.sizeof(get_arch_phdr(endianness
, elfclass
))
277 class EHDR32(superclass
):
278 """Represents the 32 bit ELF header struct."""
280 _fields_
= [('e_ident', Ident
),
281 ('e_type', ctypes
.c_uint16
),
282 ('e_machine', ctypes
.c_uint16
),
283 ('e_version', ctypes
.c_uint32
),
284 ('e_entry', ctypes
.c_uint32
),
285 ('e_phoff', ctypes
.c_uint32
),
286 ('e_shoff', ctypes
.c_uint32
),
287 ('e_flags', ctypes
.c_uint32
),
288 ('e_ehsize', ctypes
.c_uint16
),
289 ('e_phentsize', ctypes
.c_uint16
),
290 ('e_phnum', ctypes
.c_uint16
),
291 ('e_shentsize', ctypes
.c_uint16
),
292 ('e_shnum', ctypes
.c_uint16
),
293 ('e_shstrndx', ctypes
.c_uint16
)]
296 super(superclass
, self
).__init
__()
297 self
.e_ident
= Ident(endianness
, elfclass
)
298 self
.e_type
= ET_CORE
299 self
.e_version
= EV_CURRENT
300 self
.e_ehsize
= ctypes
.sizeof(self
)
301 self
.e_phoff
= ctypes
.sizeof(self
)
302 self
.e_phentsize
= ctypes
.sizeof(get_arch_phdr(endianness
, elfclass
))
306 if elfclass
== ELFCLASS64
:
312 def get_arch_phdr(endianness
, elfclass
):
313 """Returns a 32 or 64 bit PHDR class with the specified endianness."""
315 if endianness
== ELFDATA2LSB
:
316 superclass
= ctypes
.LittleEndianStructure
318 superclass
= ctypes
.BigEndianStructure
320 class PHDR64(superclass
):
321 """Represents the 64 bit ELF program header struct."""
323 _fields_
= [('p_type', ctypes
.c_uint32
),
324 ('p_flags', ctypes
.c_uint32
),
325 ('p_offset', ctypes
.c_uint64
),
326 ('p_vaddr', ctypes
.c_uint64
),
327 ('p_paddr', ctypes
.c_uint64
),
328 ('p_filesz', ctypes
.c_uint64
),
329 ('p_memsz', ctypes
.c_uint64
),
330 ('p_align', ctypes
.c_uint64
)]
332 class PHDR32(superclass
):
333 """Represents the 32 bit ELF program header struct."""
335 _fields_
= [('p_type', ctypes
.c_uint32
),
336 ('p_offset', ctypes
.c_uint32
),
337 ('p_vaddr', ctypes
.c_uint32
),
338 ('p_paddr', ctypes
.c_uint32
),
339 ('p_filesz', ctypes
.c_uint32
),
340 ('p_memsz', ctypes
.c_uint32
),
341 ('p_flags', ctypes
.c_uint32
),
342 ('p_align', ctypes
.c_uint32
)]
345 if elfclass
== ELFCLASS64
:
351 def int128_get64(val
):
352 """Returns low 64bit part of Int128 struct."""
355 assert val
["hi"] == 0
358 u64t
= gdb
.lookup_type('uint64_t').array(2)
360 if sys
.byteorder
== 'little':
368 def qlist_foreach(head
, field_str
):
369 """Generator for qlists."""
371 var_p
= head
["lh_first"]
373 var
= var_p
.dereference()
374 var_p
= var
[field_str
]["le_next"]
378 def qemu_map_ram_ptr(block
, offset
):
379 """Returns qemu vaddr for given guest physical address."""
381 return block
["host"] + offset
384 def memory_region_get_ram_ptr(memory_region
):
385 if memory_region
["alias"] != 0:
386 return (memory_region_get_ram_ptr(memory_region
["alias"].dereference())
387 + memory_region
["alias_offset"])
389 return qemu_map_ram_ptr(memory_region
["ram_block"], 0)
392 def get_guest_phys_blocks():
393 """Returns a list of ram blocks.
395 Each block entry contains:
396 'target_start': guest block phys start address
397 'target_end': guest block phys end address
398 'host_addr': qemu vaddr of the block's start
401 guest_phys_blocks
= []
403 print("guest RAM blocks:")
404 print("target_start target_end host_addr message "
406 print("---------------- ---------------- ---------------- ------- "
409 current_map_p
= gdb
.parse_and_eval("address_space_memory.current_map")
410 current_map
= current_map_p
.dereference()
412 # Conversion to int is needed for python 3
413 # compatibility. Otherwise range doesn't cast the value itself and
415 for cur
in range(int(current_map
["nr"])):
416 flat_range
= (current_map
["ranges"] + cur
).dereference()
417 memory_region
= flat_range
["mr"].dereference()
419 # we only care about RAM
420 if (not memory_region
["ram"] or
421 memory_region
["ram_device"] or
422 memory_region
["nonvolatile"]):
425 section_size
= int128_get64(flat_range
["addr"]["size"])
426 target_start
= int128_get64(flat_range
["addr"]["start"])
427 target_end
= target_start
+ section_size
428 host_addr
= (memory_region_get_ram_ptr(memory_region
)
429 + flat_range
["offset_in_region"])
432 # find continuity in guest physical address space
433 if len(guest_phys_blocks
) > 0:
434 predecessor
= guest_phys_blocks
[-1]
435 predecessor_size
= (predecessor
["target_end"] -
436 predecessor
["target_start"])
438 # the memory API guarantees monotonically increasing
440 assert predecessor
["target_end"] <= target_start
442 # we want continuity in both guest-physical and
443 # host-virtual memory
444 if (predecessor
["target_end"] < target_start
or
445 predecessor
["host_addr"] + predecessor_size
!= host_addr
):
448 if predecessor
is None:
449 # isolated mapping, add it to the list
450 guest_phys_blocks
.append({"target_start": target_start
,
451 "target_end": target_end
,
452 "host_addr": host_addr
})
455 # expand predecessor until @target_end; predecessor's
456 # start doesn't change
457 predecessor
["target_end"] = target_end
460 print("%016x %016x %016x %-7s %5u" %
461 (target_start
, target_end
, host_addr
.cast(UINTPTR_T
),
462 message
, len(guest_phys_blocks
)))
464 return guest_phys_blocks
467 # The leading docstring doesn't have idiomatic Python formatting. It is
468 # printed by gdb's "help" command (the first line is printed in the
469 # "help data" summary), and it should match how other help texts look in
471 class DumpGuestMemory(gdb
.Command
):
472 """Extract guest vmcore from qemu process coredump.
474 The two required arguments are FILE and ARCH:
475 FILE identifies the target file to write the guest vmcore to.
476 ARCH specifies the architecture for which the core will be generated.
478 This GDB command reimplements the dump-guest-memory QMP command in
479 python, using the representation of guest memory as captured in the qemu
480 coredump. The qemu process that has been dumped must have had the
481 command line option "-machine dump-guest-core=on" which is the default.
483 For simplicity, the "paging", "begin" and "end" parameters of the QMP
484 command are not supported -- no attempt is made to get the guest's
485 internal paging structures (ie. paging=false is hard-wired), and guest
486 memory is always fully dumped.
488 Currently aarch64-be, aarch64-le, X86_64, 386, s390, ppc64-be,
489 ppc64-le guests are supported.
491 The CORE/NT_PRSTATUS and QEMU notes (that is, the VCPUs' statuses) are
492 not written to the vmcore. Preparing these would require context that is
493 only present in the KVM host kernel module when the guest is alive. A
494 fake ELF note is written instead, only to keep the ELF parser of "crash"
497 Dependent on how busted the qemu process was at the time of the
498 coredump, this command might produce unpredictable results. If qemu
499 deliberately called abort(), or it was dumped in response to a signal at
500 a halfway fortunate point, then its coredump should be in reasonable
501 shape and this command should mostly work."""
504 super(DumpGuestMemory
, self
).__init
__("dump-guest-memory",
506 gdb
.COMPLETE_FILENAME
)
508 self
.guest_phys_blocks
= None
510 def dump_init(self
, vmcore
):
511 """Prepares and writes ELF structures to core file."""
513 # Needed to make crash happy, data for more useful notes is
514 # not available in a qemu core.
515 self
.elf
.add_note("NONE", "EMPTY", 0)
517 # We should never reach PN_XNUM for paging=false dumps,
518 # there's just a handful of discontiguous ranges after
520 # The constant is needed to account for the PT_NOTE segment.
521 phdr_num
= len(self
.guest_phys_blocks
) + 1
522 assert phdr_num
< PN_XNUM
524 for block
in self
.guest_phys_blocks
:
525 block_size
= block
["target_end"] - block
["target_start"]
526 self
.elf
.add_segment(PT_LOAD
, block
["target_start"], block_size
)
528 self
.elf
.to_file(vmcore
)
530 def dump_iterate(self
, vmcore
):
531 """Writes guest core to file."""
533 qemu_core
= gdb
.inferiors()[0]
534 for block
in self
.guest_phys_blocks
:
535 cur
= block
["host_addr"]
536 left
= block
["target_end"] - block
["target_start"]
537 print("dumping range at %016x for length %016x" %
538 (cur
.cast(UINTPTR_T
), left
))
541 chunk_size
= min(TARGET_PAGE_SIZE
, left
)
542 chunk
= qemu_core
.read_memory(cur
, chunk_size
)
547 def phys_memory_read(self
, addr
, size
):
548 qemu_core
= gdb
.inferiors()[0]
549 for block
in self
.guest_phys_blocks
:
550 if block
["target_start"] <= addr \
551 and addr
+ size
<= block
["target_end"]:
552 haddr
= block
["host_addr"] + (addr
- block
["target_start"])
553 return qemu_core
.read_memory(haddr
, size
)
556 def add_vmcoreinfo(self
):
557 if gdb
.lookup_symbol("vmcoreinfo_realize")[0] is None:
559 vmci
= 'vmcoreinfo_realize::vmcoreinfo_state'
560 if not gdb
.parse_and_eval("%s" % vmci
) \
561 or not gdb
.parse_and_eval("(%s)->has_vmcoreinfo" % vmci
):
564 fmt
= gdb
.parse_and_eval("(%s)->vmcoreinfo.guest_format" % vmci
)
565 addr
= gdb
.parse_and_eval("(%s)->vmcoreinfo.paddr" % vmci
)
566 size
= gdb
.parse_and_eval("(%s)->vmcoreinfo.size" % vmci
)
568 fmt
= le16_to_cpu(fmt
)
569 addr
= le64_to_cpu(addr
)
570 size
= le32_to_cpu(size
)
572 if fmt
!= VMCOREINFO_FORMAT_ELF
:
575 vmcoreinfo
= self
.phys_memory_read(addr
, size
)
577 self
.elf
.add_vmcoreinfo_note(bytes(vmcoreinfo
))
579 def invoke(self
, args
, from_tty
):
580 """Handles command invocation from gdb."""
582 # Unwittingly pressing the Enter key after the command should
583 # not dump the same multi-gig coredump to the same file.
586 argv
= gdb
.string_to_argv(args
)
588 raise gdb
.GdbError("usage: dump-guest-memory FILE ARCH")
590 self
.elf
= ELF(argv
[1])
591 self
.guest_phys_blocks
= get_guest_phys_blocks()
592 self
.add_vmcoreinfo()
594 with
open(argv
[0], "wb") as vmcore
:
595 self
.dump_init(vmcore
)
596 self
.dump_iterate(vmcore
)