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