1""" 2This python script adds a new gdb command, "dump-guest-memory". It 3should be loaded with "source dump-guest-memory.py" at the (gdb) 4prompt. 5 6Copyright (C) 2013, Red Hat, Inc. 7 8Authors: 9 Laszlo Ersek <lersek@redhat.com> 10 Janosch Frank <frankja@linux.vnet.ibm.com> 11 12This work is licensed under the terms of the GNU GPL, version 2 or later. See 13the COPYING file in the top-level directory. 14""" 15 16import ctypes 17import struct 18 19try: 20 UINTPTR_T = gdb.lookup_type("uintptr_t") 21except 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 26TARGET_PAGE_SIZE = 0x1000 27TARGET_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. 32PN_XNUM = 0xFFFF 33 34EV_CURRENT = 1 35 36ELFCLASS32 = 1 37ELFCLASS64 = 2 38 39ELFDATA2LSB = 1 40ELFDATA2MSB = 2 41 42ET_CORE = 4 43 44PT_LOAD = 1 45PT_NOTE = 4 46 47EM_386 = 3 48EM_PPC = 20 49EM_PPC64 = 21 50EM_S390 = 22 51EM_AARCH = 183 52EM_X86_64 = 62 53 54VMCOREINFO_FORMAT_ELF = 1 55 56def le16_to_cpu(val): 57 return struct.unpack("<H", struct.pack("=H", val))[0] 58 59def le32_to_cpu(val): 60 return struct.unpack("<I", struct.pack("=I", val))[0] 61 62def le64_to_cpu(val): 63 return struct.unpack("<Q", struct.pack("=Q", val))[0] 64 65class 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 194def 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 215class 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 239def 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 311def 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 350def 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 367def 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 377def qemu_map_ram_ptr(block, offset): 378 """Returns qemu vaddr for given guest physical address.""" 379 380 return block["host"] + offset 381 382 383def 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 391def 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. 468class DumpGuestMemory(gdb.Command): 469 """Extract guest vmcore from qemu process coredump. 470 471The two required arguments are FILE and ARCH: 472FILE identifies the target file to write the guest vmcore to. 473ARCH specifies the architecture for which the core will be generated. 474 475This GDB command reimplements the dump-guest-memory QMP command in 476python, using the representation of guest memory as captured in the qemu 477coredump. The qemu process that has been dumped must have had the 478command line option "-machine dump-guest-core=on" which is the default. 479 480For simplicity, the "paging", "begin" and "end" parameters of the QMP 481command are not supported -- no attempt is made to get the guest's 482internal paging structures (ie. paging=false is hard-wired), and guest 483memory is always fully dumped. 484 485Currently aarch64-be, aarch64-le, X86_64, 386, s390, ppc64-be, 486ppc64-le guests are supported. 487 488The CORE/NT_PRSTATUS and QEMU notes (that is, the VCPUs' statuses) are 489not written to the vmcore. Preparing these would require context that is 490only present in the KVM host kernel module when the guest is alive. A 491fake ELF note is written instead, only to keep the ELF parser of "crash" 492happy. 493 494Dependent on how busted the qemu process was at the time of the 495coredump, this command might produce unpredictable results. If qemu 496deliberately called abort(), or it was dumped in response to a signal at 497a halfway fortunate point, then its coredump should be in reasonable 498shape 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 595DumpGuestMemory() 596