scripts/dump-guest-memory.py

   1 """
   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)
   4 prompt.
   5
   6 Copyright (C) 2013, Red Hat, Inc.
   7
   8 Authors:
   9    Laszlo Ersek <lersek@redhat.com>
  10    Janosch Frank <frankja@linux.vnet.ibm.com>
  11
  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.
  14 """
  15
  16 import ctypes
  17 import struct
  18
  19 try:
  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.")
  25
  26 TARGET_PAGE_SIZE = 0x1000
  27 TARGET_PAGE_MASK = 0xFFFFFFFFFFFFF000
  28
  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.
  32 PN_XNUM = 0xFFFF
  33
  34 EV_CURRENT = 1
  35
  36 ELFCLASS32 = 1
  37 ELFCLASS64 = 2
  38
  39 ELFDATA2LSB = 1
  40 ELFDATA2MSB = 2
  41
  42 ET_CORE = 4
  43
  44 PT_LOAD = 1
  45 PT_NOTE = 4
  46
  47 EM_386 = 3
  48 EM_PPC = 20
  49 EM_PPC64 = 21
  50 EM_S390 = 22
  51 EM_AARCH = 183
  52 EM_X86_64 = 62
  53
  54 VMCOREINFO_FORMAT_ELF = 1
  55
  56 def le16_to_cpu(val):
  57     return struct.unpack("<H", struct.pack("=H", val))[0]
  58
  59 def le32_to_cpu(val):
  60     return struct.unpack("<I", struct.pack("=I", val))[0]
  61
  62 def le64_to_cpu(val):
  63     return struct.unpack("<Q", struct.pack("=Q", val))[0]
  64
  65 class ELF(object):
  66     """Representation of a ELF file."""
  67
  68     def __init__(self, arch):
  69         self.ehdr = None
  70         self.notes = []
  71         self.segments = []
  72         self.notes_size = 0
  73         self.endianness = None
  74         self.elfclass = ELFCLASS64
  75
  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
  81
  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
  86
  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
  91
  92         elif arch == '386':
  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
  97
  98         elif arch == 's390':
  99             self.endianness = ELFDATA2MSB
 100             self.ehdr = get_arch_ehdr(self.endianness, self.elfclass)
 101             self.ehdr.e_machine = EM_S390
 102
 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
 107
 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
 112
 113         else:
 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")
 118
 119         self.add_segment(PT_NOTE, 0, 0)
 120
 121     def add_note(self, n_name, n_desc, n_type):
 122         """Adds a note to the ELF."""
 123
 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()
 128         note.n_type = n_type
 129
 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
 133         # string into it.
 134         ctypes.memmove(note.n_desc, n_desc.encode(), len(n_desc))
 135
 136         self.notes.append(note)
 137         self.segments[0].p_filesz += ctypes.sizeof(note)
 138         self.segments[0].p_memsz += ctypes.sizeof(note)
 139
 140
 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')
 149             return
 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))
 154
 155         self.notes.append(note)
 156         self.segments[0].p_filesz += ctypes.sizeof(note)
 157         self.segments[0].p_memsz += ctypes.sizeof(note)
 158
 159     def add_segment(self, p_type, p_paddr, p_size):
 160         """Adds a segment to the elf."""
 161
 162         phdr = get_arch_phdr(self.endianness, self.elfclass)
 163         phdr.p_type = p_type
 164         phdr.p_paddr = p_paddr
 165         phdr.p_filesz = p_size
 166         phdr.p_memsz = p_size
 167         self.segments.append(phdr)
 168         self.ehdr.e_phnum += 1
 169
 170     def to_file(self, elf_file):
 171         """Writes all ELF structures to the the passed file.
 172
 173         Structure:
 174         Ehdr
 175         Segment 0:PT_NOTE
 176         Segment 1:PT_LOAD
 177         Segment N:PT_LOAD
 178         Note    0..N
 179         Dump contents
 180         """
 181         elf_file.write(self.ehdr)
 182         off = ctypes.sizeof(self.ehdr) + \
 183               len(self.segments) * ctypes.sizeof(self.segments[0])
 184
 185         for phdr in self.segments:
 186             phdr.p_offset = off
 187             elf_file.write(phdr)
 188             off += phdr.p_filesz
 189
 190         for note in self.notes:
 191             elf_file.write(note)
 192
 193
 194 def get_arch_note(endianness, len_name, len_desc):
 195     """Returns a Note class with the specified endianness."""
 196
 197     if endianness == ELFDATA2LSB:
 198         superclass = ctypes.LittleEndianStructure
 199     else:
 200         superclass = ctypes.BigEndianStructure
 201
 202     len_name = len_name + 1
 203
 204     class Note(superclass):
 205         """Represents an ELF note, includes the content."""
 206
 207         _fields_ = [("n_namesz", ctypes.c_uint32),
 208                     ("n_descsz", ctypes.c_uint32),
 209                     ("n_type", ctypes.c_uint32),
 210                     ("n_name", ctypes.c_char * len_name),
 211                     ("n_desc", ctypes.c_uint32 * ((len_desc + 3) // 4))]
 212     return Note()
 213
 214
 215 class Ident(ctypes.Structure):
 216     """Represents the ELF ident array in the ehdr structure."""
 217
 218     _fields_ = [('ei_mag0', ctypes.c_ubyte),
 219                 ('ei_mag1', ctypes.c_ubyte),
 220                 ('ei_mag2', ctypes.c_ubyte),
 221                 ('ei_mag3', ctypes.c_ubyte),
 222                 ('ei_class', ctypes.c_ubyte),
 223                 ('ei_data', ctypes.c_ubyte),
 224                 ('ei_version', ctypes.c_ubyte),
 225                 ('ei_osabi', ctypes.c_ubyte),
 226                 ('ei_abiversion', ctypes.c_ubyte),
 227                 ('ei_pad', ctypes.c_ubyte * 7)]
 228
 229     def __init__(self, endianness, elfclass):
 230         self.ei_mag0 = 0x7F
 231         self.ei_mag1 = ord('E')
 232         self.ei_mag2 = ord('L')
 233         self.ei_mag3 = ord('F')
 234         self.ei_class = elfclass
 235         self.ei_data = endianness
 236         self.ei_version = EV_CURRENT
 237
 238
 239 def get_arch_ehdr(endianness, elfclass):
 240     """Returns a EHDR64 class with the specified endianness."""
 241
 242     if endianness == ELFDATA2LSB:
 243         superclass = ctypes.LittleEndianStructure
 244     else:
 245         superclass = ctypes.BigEndianStructure
 246
 247     class EHDR64(superclass):
 248         """Represents the 64 bit ELF header struct."""
 249
 250         _fields_ = [('e_ident', Ident),
 251                     ('e_type', ctypes.c_uint16),
 252                     ('e_machine', ctypes.c_uint16),
 253                     ('e_version', ctypes.c_uint32),
 254                     ('e_entry', ctypes.c_uint64),
 255                     ('e_phoff', ctypes.c_uint64),
 256                     ('e_shoff', ctypes.c_uint64),
 257                     ('e_flags', ctypes.c_uint32),
 258                     ('e_ehsize', ctypes.c_uint16),
 259                     ('e_phentsize', ctypes.c_uint16),
 260                     ('e_phnum', ctypes.c_uint16),
 261                     ('e_shentsize', ctypes.c_uint16),
 262                     ('e_shnum', ctypes.c_uint16),
 263                     ('e_shstrndx', ctypes.c_uint16)]
 264
 265         def __init__(self):
 266             super(superclass, self).__init__()
 267             self.e_ident = Ident(endianness, elfclass)
 268             self.e_type = ET_CORE
 269             self.e_version = EV_CURRENT
 270             self.e_ehsize = ctypes.sizeof(self)
 271             self.e_phoff = ctypes.sizeof(self)
 272             self.e_phentsize = ctypes.sizeof(get_arch_phdr(endianness, elfclass))
 273             self.e_phnum = 0
 274
 275
 276     class EHDR32(superclass):
 277         """Represents the 32 bit ELF header struct."""
 278
 279         _fields_ = [('e_ident', Ident),
 280                     ('e_type', ctypes.c_uint16),
 281                     ('e_machine', ctypes.c_uint16),
 282                     ('e_version', ctypes.c_uint32),
 283                     ('e_entry', ctypes.c_uint32),
 284                     ('e_phoff', ctypes.c_uint32),
 285                     ('e_shoff', ctypes.c_uint32),
 286                     ('e_flags', ctypes.c_uint32),
 287                     ('e_ehsize', ctypes.c_uint16),
 288                     ('e_phentsize', ctypes.c_uint16),
 289                     ('e_phnum', ctypes.c_uint16),
 290                     ('e_shentsize', ctypes.c_uint16),
 291                     ('e_shnum', ctypes.c_uint16),
 292                     ('e_shstrndx', ctypes.c_uint16)]
 293
 294         def __init__(self):
 295             super(superclass, self).__init__()
 296             self.e_ident = Ident(endianness, elfclass)
 297             self.e_type = ET_CORE
 298             self.e_version = EV_CURRENT
 299             self.e_ehsize = ctypes.sizeof(self)
 300             self.e_phoff = ctypes.sizeof(self)
 301             self.e_phentsize = ctypes.sizeof(get_arch_phdr(endianness, elfclass))
 302             self.e_phnum = 0
 303
 304     # End get_arch_ehdr
 305     if elfclass == ELFCLASS64:
 306         return EHDR64()
 307     else:
 308         return EHDR32()
 309
 310
 311 def get_arch_phdr(endianness, elfclass):
 312     """Returns a 32 or 64 bit PHDR class with the specified endianness."""
 313
 314     if endianness == ELFDATA2LSB:
 315         superclass = ctypes.LittleEndianStructure
 316     else:
 317         superclass = ctypes.BigEndianStructure
 318
 319     class PHDR64(superclass):
 320         """Represents the 64 bit ELF program header struct."""
 321
 322         _fields_ = [('p_type', ctypes.c_uint32),
 323                     ('p_flags', ctypes.c_uint32),
 324                     ('p_offset', ctypes.c_uint64),
 325                     ('p_vaddr', ctypes.c_uint64),
 326                     ('p_paddr', ctypes.c_uint64),
 327                     ('p_filesz', ctypes.c_uint64),
 328                     ('p_memsz', ctypes.c_uint64),
 329                     ('p_align', ctypes.c_uint64)]
 330
 331     class PHDR32(superclass):
 332         """Represents the 32 bit ELF program header struct."""
 333
 334         _fields_ = [('p_type', ctypes.c_uint32),
 335                     ('p_offset', ctypes.c_uint32),
 336                     ('p_vaddr', ctypes.c_uint32),
 337                     ('p_paddr', ctypes.c_uint32),
 338                     ('p_filesz', ctypes.c_uint32),
 339                     ('p_memsz', ctypes.c_uint32),
 340                     ('p_flags', ctypes.c_uint32),
 341                     ('p_align', ctypes.c_uint32)]
 342
 343     # End get_arch_phdr
 344     if elfclass == ELFCLASS64:
 345         return PHDR64()
 346     else:
 347         return PHDR32()
 348
 349
 350 def int128_get64(val):
 351     """Returns low 64bit part of Int128 struct."""
 352
 353     try:
 354         assert val["hi"] == 0
 355         return val["lo"]
 356     except gdb.error:
 357         u64t = gdb.lookup_type('uint64_t').array(2)
 358         u64 = val.cast(u64t)
 359         if sys.byteorder == 'little':
 360             assert u64[1] == 0
 361             return u64[0]
 362         else:
 363             assert u64[0] == 0
 364             return u64[1]
 365
 366
 367 def qlist_foreach(head, field_str):
 368     """Generator for qlists."""
 369
 370     var_p = head["lh_first"]
 371     while var_p != 0:
 372         var = var_p.dereference()
 373         var_p = var[field_str]["le_next"]
 374         yield var
 375
 376
 377 def qemu_map_ram_ptr(block, offset):
 378     """Returns qemu vaddr for given guest physical address."""
 379
 380     return block["host"] + offset
 381
 382
 383 def memory_region_get_ram_ptr(memory_region):
 384     if memory_region["alias"] != 0:
 385         return (memory_region_get_ram_ptr(memory_region["alias"].dereference())
 386                 + memory_region["alias_offset"])
 387
 388     return qemu_map_ram_ptr(memory_region["ram_block"], 0)
 389
 390
 391 def get_guest_phys_blocks():
 392     """Returns a list of ram blocks.
 393
 394     Each block entry contains:
 395     'target_start': guest block phys start address
 396     'target_end':   guest block phys end address
 397     'host_addr':    qemu vaddr of the block's start
 398     """
 399
 400     guest_phys_blocks = []
 401
 402     print("guest RAM blocks:")
 403     print("target_start     target_end       host_addr        message "
 404           "count")
 405     print("---------------- ---------------- ---------------- ------- "
 406           "-----")
 407
 408     current_map_p = gdb.parse_and_eval("address_space_memory.current_map")
 409     current_map = current_map_p.dereference()
 410
 411     # Conversion to int is needed for python 3
 412     # compatibility. Otherwise range doesn't cast the value itself and
 413     # breaks.
 414     for cur in range(int(current_map["nr"])):
 415         flat_range = (current_map["ranges"] + cur).dereference()
 416         memory_region = flat_range["mr"].dereference()
 417
 418         # we only care about RAM
 419         if not memory_region["ram"]:
 420             continue
 421
 422         section_size = int128_get64(flat_range["addr"]["size"])
 423         target_start = int128_get64(flat_range["addr"]["start"])
 424         target_end = target_start + section_size
 425         host_addr = (memory_region_get_ram_ptr(memory_region)
 426                      + flat_range["offset_in_region"])
 427         predecessor = None
 428
 429         # find continuity in guest physical address space
 430         if len(guest_phys_blocks) > 0:
 431             predecessor = guest_phys_blocks[-1]
 432             predecessor_size = (predecessor["target_end"] -
 433                                 predecessor["target_start"])
 434
 435             # the memory API guarantees monotonically increasing
 436             # traversal
 437             assert predecessor["target_end"] <= target_start
 438
 439             # we want continuity in both guest-physical and
 440             # host-virtual memory
 441             if (predecessor["target_end"] < target_start or
 442                 predecessor["host_addr"] + predecessor_size != host_addr):
 443                 predecessor = None
 444
 445         if predecessor is None:
 446             # isolated mapping, add it to the list
 447             guest_phys_blocks.append({"target_start": target_start,
 448                                       "target_end":   target_end,
 449                                       "host_addr":    host_addr})
 450             message = "added"
 451         else:
 452             # expand predecessor until @target_end; predecessor's
 453             # start doesn't change
 454             predecessor["target_end"] = target_end
 455             message = "joined"
 456
 457         print("%016x %016x %016x %-7s %5u" %
 458               (target_start, target_end, host_addr.cast(UINTPTR_T),
 459                message, len(guest_phys_blocks)))
 460
 461     return guest_phys_blocks
 462
 463
 464 # The leading docstring doesn't have idiomatic Python formatting. It is
 465 # printed by gdb's "help" command (the first line is printed in the
 466 # "help data" summary), and it should match how other help texts look in
 467 # gdb.
 468 class DumpGuestMemory(gdb.Command):
 469     """Extract guest vmcore from qemu process coredump.
 470
 471 The two required arguments are FILE and ARCH:
 472 FILE identifies the target file to write the guest vmcore to.
 473 ARCH specifies the architecture for which the core will be generated.
 474
 475 This GDB command reimplements the dump-guest-memory QMP command in
 476 python, using the representation of guest memory as captured in the qemu
 477 coredump. The qemu process that has been dumped must have had the
 478 command line option "-machine dump-guest-core=on" which is the default.
 479
 480 For simplicity, the "paging", "begin" and "end" parameters of the QMP
 481 command are not supported -- no attempt is made to get the guest's
 482 internal paging structures (ie. paging=false is hard-wired), and guest
 483 memory is always fully dumped.
 484
 485 Currently aarch64-be, aarch64-le, X86_64, 386, s390, ppc64-be,
 486 ppc64-le guests are supported.
 487
 488 The CORE/NT_PRSTATUS and QEMU notes (that is, the VCPUs' statuses) are
 489 not written to the vmcore. Preparing these would require context that is
 490 only present in the KVM host kernel module when the guest is alive. A
 491 fake ELF note is written instead, only to keep the ELF parser of "crash"
 492 happy.
 493
 494 Dependent on how busted the qemu process was at the time of the
 495 coredump, this command might produce unpredictable results. If qemu
 496 deliberately called abort(), or it was dumped in response to a signal at
 497 a halfway fortunate point, then its coredump should be in reasonable
 498 shape and this command should mostly work."""
 499
 500     def __init__(self):
 501         super(DumpGuestMemory, self).__init__("dump-guest-memory",
 502                                               gdb.COMMAND_DATA,
 503                                               gdb.COMPLETE_FILENAME)
 504         self.elf = None
 505         self.guest_phys_blocks = None
 506
 507     def dump_init(self, vmcore):
 508         """Prepares and writes ELF structures to core file."""
 509
 510         # Needed to make crash happy, data for more useful notes is
 511         # not available in a qemu core.
 512         self.elf.add_note("NONE", "EMPTY", 0)
 513
 514         # We should never reach PN_XNUM for paging=false dumps,
 515         # there's just a handful of discontiguous ranges after
 516         # merging.
 517         # The constant is needed to account for the PT_NOTE segment.
 518         phdr_num = len(self.guest_phys_blocks) + 1
 519         assert phdr_num < PN_XNUM
 520
 521         for block in self.guest_phys_blocks:
 522             block_size = block["target_end"] - block["target_start"]
 523             self.elf.add_segment(PT_LOAD, block["target_start"], block_size)
 524
 525         self.elf.to_file(vmcore)
 526
 527     def dump_iterate(self, vmcore):
 528         """Writes guest core to file."""
 529
 530         qemu_core = gdb.inferiors()[0]
 531         for block in self.guest_phys_blocks:
 532             cur = block["host_addr"]
 533             left = block["target_end"] - block["target_start"]
 534             print("dumping range at %016x for length %016x" %
 535                   (cur.cast(UINTPTR_T), left))
 536
 537             while left > 0:
 538                 chunk_size = min(TARGET_PAGE_SIZE, left)
 539                 chunk = qemu_core.read_memory(cur, chunk_size)
 540                 vmcore.write(chunk)
 541                 cur += chunk_size
 542                 left -= chunk_size
 543
 544     def phys_memory_read(self, addr, size):
 545         qemu_core = gdb.inferiors()[0]
 546         for block in self.guest_phys_blocks:
 547             if block["target_start"] <= addr \
 548                and addr + size <= block["target_end"]:
 549                 haddr = block["host_addr"] + (addr - block["target_start"])
 550                 return qemu_core.read_memory(haddr, size)
 551         return None
 552
 553     def add_vmcoreinfo(self):
 554         if gdb.lookup_symbol("vmcoreinfo_realize")[0] is None:
 555             return
 556         vmci = 'vmcoreinfo_realize::vmcoreinfo_state'
 557         if not gdb.parse_and_eval("%s" % vmci) \
 558            or not gdb.parse_and_eval("(%s)->has_vmcoreinfo" % vmci):
 559             return
 560
 561         fmt = gdb.parse_and_eval("(%s)->vmcoreinfo.guest_format" % vmci)
 562         addr = gdb.parse_and_eval("(%s)->vmcoreinfo.paddr" % vmci)
 563         size = gdb.parse_and_eval("(%s)->vmcoreinfo.size" % vmci)
 564
 565         fmt = le16_to_cpu(fmt)
 566         addr = le64_to_cpu(addr)
 567         size = le32_to_cpu(size)
 568
 569         if fmt != VMCOREINFO_FORMAT_ELF:
 570             return
 571
 572         vmcoreinfo = self.phys_memory_read(addr, size)
 573         if vmcoreinfo:
 574             self.elf.add_vmcoreinfo_note(bytes(vmcoreinfo))
 575
 576     def invoke(self, args, from_tty):
 577         """Handles command invocation from gdb."""
 578
 579         # Unwittingly pressing the Enter key after the command should
 580         # not dump the same multi-gig coredump to the same file.
 581         self.dont_repeat()
 582
 583         argv = gdb.string_to_argv(args)
 584         if len(argv) != 2:
 585             raise gdb.GdbError("usage: dump-guest-memory FILE ARCH")
 586
 587         self.elf = ELF(argv[1])
 588         self.guest_phys_blocks = get_guest_phys_blocks()
 589         self.add_vmcoreinfo()
 590
 591         with open(argv[0], "wb") as vmcore:
 592             self.dump_init(vmcore)
 593             self.dump_iterate(vmcore)
 594
 595 DumpGuestMemory()