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_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
 170
 171     def to_file(self, elf_file):
 172         """Writes all ELF structures to the passed file.
 173
 174         Structure:
 175         Ehdr
 176         Segment 0:PT_NOTE
 177         Segment 1:PT_LOAD
 178         Segment N:PT_LOAD
 179         Note    0..N
 180         Dump contents
 181         """
 182         elf_file.write(self.ehdr)
 183         off = ctypes.sizeof(self.ehdr) + \
 184               len(self.segments) * ctypes.sizeof(self.segments[0])
 185
 186         for phdr in self.segments:
 187             phdr.p_offset = off
 188             elf_file.write(phdr)
 189             off += phdr.p_filesz
 190
 191         for note in self.notes:
 192             elf_file.write(note)
 193
 194
 195 def get_arch_note(endianness, len_name, len_desc):
 196     """Returns a Note class with the specified endianness."""
 197
 198     if endianness == ELFDATA2LSB:
 199         superclass = ctypes.LittleEndianStructure
 200     else:
 201         superclass = ctypes.BigEndianStructure
 202
 203     len_name = len_name + 1
 204
 205     class Note(superclass):
 206         """Represents an ELF note, includes the content."""
 207
 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))]
 213     return Note()
 214
 215
 216 class Ident(ctypes.Structure):
 217     """Represents the ELF ident array in the ehdr structure."""
 218
 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)]
 229
 230     def __init__(self, endianness, elfclass):
 231         self.ei_mag0 = 0x7F
 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
 238
 239
 240 def get_arch_ehdr(endianness, elfclass):
 241     """Returns a EHDR64 class with the specified endianness."""
 242
 243     if endianness == ELFDATA2LSB:
 244         superclass = ctypes.LittleEndianStructure
 245     else:
 246         superclass = ctypes.BigEndianStructure
 247
 248     class EHDR64(superclass):
 249         """Represents the 64 bit ELF header struct."""
 250
 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)]
 265
 266         def __init__(self):
 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))
 274             self.e_phnum = 0
 275
 276
 277     class EHDR32(superclass):
 278         """Represents the 32 bit ELF header struct."""
 279
 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)]
 294
 295         def __init__(self):
 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))
 303             self.e_phnum = 0
 304
 305     # End get_arch_ehdr
 306     if elfclass == ELFCLASS64:
 307         return EHDR64()
 308     else:
 309         return EHDR32()
 310
 311
 312 def get_arch_phdr(endianness, elfclass):
 313     """Returns a 32 or 64 bit PHDR class with the specified endianness."""
 314
 315     if endianness == ELFDATA2LSB:
 316         superclass = ctypes.LittleEndianStructure
 317     else:
 318         superclass = ctypes.BigEndianStructure
 319
 320     class PHDR64(superclass):
 321         """Represents the 64 bit ELF program header struct."""
 322
 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)]
 331
 332     class PHDR32(superclass):
 333         """Represents the 32 bit ELF program header struct."""
 334
 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)]
 343
 344     # End get_arch_phdr
 345     if elfclass == ELFCLASS64:
 346         return PHDR64()
 347     else:
 348         return PHDR32()
 349
 350
 351 def int128_get64(val):
 352     """Returns low 64bit part of Int128 struct."""
 353
 354     try:
 355         assert val["hi"] == 0
 356         return val["lo"]
 357     except gdb.error:
 358         u64t = gdb.lookup_type('uint64_t').array(2)
 359         u64 = val.cast(u64t)
 360         if sys.byteorder == 'little':
 361             assert u64[1] == 0
 362             return u64[0]
 363         else:
 364             assert u64[0] == 0
 365             return u64[1]
 366
 367
 368 def qlist_foreach(head, field_str):
 369     """Generator for qlists."""
 370
 371     var_p = head["lh_first"]
 372     while var_p != 0:
 373         var = var_p.dereference()
 374         var_p = var[field_str]["le_next"]
 375         yield var
 376
 377
 378 def qemu_map_ram_ptr(block, offset):
 379     """Returns qemu vaddr for given guest physical address."""
 380
 381     return block["host"] + offset
 382
 383
 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"])
 388
 389     return qemu_map_ram_ptr(memory_region["ram_block"], 0)
 390
 391
 392 def get_guest_phys_blocks():
 393     """Returns a list of ram blocks.
 394
 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
 399     """
 400
 401     guest_phys_blocks = []
 402
 403     print("guest RAM blocks:")
 404     print("target_start     target_end       host_addr        message "
 405           "count")
 406     print("---------------- ---------------- ---------------- ------- "
 407           "-----")
 408
 409     current_map_p = gdb.parse_and_eval("address_space_memory.current_map")
 410     current_map = current_map_p.dereference()
 411
 412     # Conversion to int is needed for python 3
 413     # compatibility. Otherwise range doesn't cast the value itself and
 414     # breaks.
 415     for cur in range(int(current_map["nr"])):
 416         flat_range = (current_map["ranges"] + cur).dereference()
 417         memory_region = flat_range["mr"].dereference()
 418
 419         # we only care about RAM
 420         if (not memory_region["ram"] or
 421             memory_region["ram_device"] or
 422             memory_region["nonvolatile"]):
 423             continue
 424
 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"])
 430         predecessor = None
 431
 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"])
 437
 438             # the memory API guarantees monotonically increasing
 439             # traversal
 440             assert predecessor["target_end"] <= target_start
 441
 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):
 446                 predecessor = None
 447
 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})
 453             message = "added"
 454         else:
 455             # expand predecessor until @target_end; predecessor's
 456             # start doesn't change
 457             predecessor["target_end"] = target_end
 458             message = "joined"
 459
 460         print("%016x %016x %016x %-7s %5u" %
 461               (target_start, target_end, host_addr.cast(UINTPTR_T),
 462                message, len(guest_phys_blocks)))
 463
 464     return guest_phys_blocks
 465
 466
 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
 470 # gdb.
 471 class DumpGuestMemory(gdb.Command):
 472     """Extract guest vmcore from qemu process coredump.
 473
 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.
 477
 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.
 482
 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.
 487
 488 Currently aarch64-be, aarch64-le, X86_64, 386, s390, ppc64-be,
 489 ppc64-le guests are supported.
 490
 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"
 495 happy.
 496
 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."""
 502
 503     def __init__(self):
 504         super(DumpGuestMemory, self).__init__("dump-guest-memory",
 505                                               gdb.COMMAND_DATA,
 506                                               gdb.COMPLETE_FILENAME)
 507         self.elf = None
 508         self.guest_phys_blocks = None
 509
 510     def dump_init(self, vmcore):
 511         """Prepares and writes ELF structures to core file."""
 512
 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)
 516
 517         # We should never reach PN_XNUM for paging=false dumps,
 518         # there's just a handful of discontiguous ranges after
 519         # merging.
 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
 523
 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)
 527
 528         self.elf.to_file(vmcore)
 529
 530     def dump_iterate(self, vmcore):
 531         """Writes guest core to file."""
 532
 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))
 539
 540             while left > 0:
 541                 chunk_size = min(TARGET_PAGE_SIZE, left)
 542                 chunk = qemu_core.read_memory(cur, chunk_size)
 543                 vmcore.write(chunk)
 544                 cur += chunk_size
 545                 left -= chunk_size
 546
 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)
 554         return None
 555
 556     def add_vmcoreinfo(self):
 557         if gdb.lookup_symbol("vmcoreinfo_realize")[0] is None:
 558             return
 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):
 562             return
 563
 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)
 567
 568         fmt = le16_to_cpu(fmt)
 569         addr = le64_to_cpu(addr)
 570         size = le32_to_cpu(size)
 571
 572         if fmt != VMCOREINFO_FORMAT_ELF:
 573             return
 574
 575         vmcoreinfo = self.phys_memory_read(addr, size)
 576         if vmcoreinfo:
 577             self.elf.add_vmcoreinfo_note(bytes(vmcoreinfo))
 578
 579     def invoke(self, args, from_tty):
 580         """Handles command invocation from gdb."""
 581
 582         # Unwittingly pressing the Enter key after the command should
 583         # not dump the same multi-gig coredump to the same file.
 584         self.dont_repeat()
 585
 586         argv = gdb.string_to_argv(args)
 587         if len(argv) != 2:
 588             raise gdb.GdbError("usage: dump-guest-memory FILE ARCH")
 589
 590         self.elf = ELF(argv[1])
 591         self.guest_phys_blocks = get_guest_phys_blocks()
 592         self.add_vmcoreinfo()
 593
 594         with open(argv[0], "wb") as vmcore:
 595             self.dump_init(vmcore)
 596             self.dump_iterate(vmcore)
 597
 598 DumpGuestMemory()