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 17 18UINTPTR_T = gdb.lookup_type("uintptr_t") 19 20TARGET_PAGE_SIZE = 0x1000 21TARGET_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. 26PN_XNUM = 0xFFFF 27 28EV_CURRENT = 1 29 30ELFCLASS32 = 1 31ELFCLASS64 = 2 32 33ELFDATA2LSB = 1 34ELFDATA2MSB = 2 35 36ET_CORE = 4 37 38PT_LOAD = 1 39PT_NOTE = 4 40 41EM_386 = 3 42EM_PPC = 20 43EM_PPC64 = 21 44EM_S390 = 22 45EM_AARCH = 183 46EM_X86_64 = 62 47 48class 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.endianess = None 57 self.elfclass = ELFCLASS64 58 59 if arch == 'aarch64-le': 60 self.endianess = ELFDATA2LSB 61 self.elfclass = ELFCLASS64 62 self.ehdr = get_arch_ehdr(self.endianess, self.elfclass) 63 self.ehdr.e_machine = EM_AARCH 64 65 elif arch == 'aarch64-be': 66 self.endianess = ELFDATA2MSB 67 self.ehdr = get_arch_ehdr(self.endianess, self.elfclass) 68 self.ehdr.e_machine = EM_AARCH 69 70 elif arch == 'X86_64': 71 self.endianess = ELFDATA2LSB 72 self.ehdr = get_arch_ehdr(self.endianess, self.elfclass) 73 self.ehdr.e_machine = EM_X86_64 74 75 elif arch == '386': 76 self.endianess = ELFDATA2LSB 77 self.elfclass = ELFCLASS32 78 self.ehdr = get_arch_ehdr(self.endianess, self.elfclass) 79 self.ehdr.e_machine = EM_386 80 81 elif arch == 's390': 82 self.endianess = ELFDATA2MSB 83 self.ehdr = get_arch_ehdr(self.endianess, self.elfclass) 84 self.ehdr.e_machine = EM_S390 85 86 elif arch == 'ppc64-le': 87 self.endianess = ELFDATA2LSB 88 self.ehdr = get_arch_ehdr(self.endianess, self.elfclass) 89 self.ehdr.e_machine = EM_PPC64 90 91 elif arch == 'ppc64-be': 92 self.endianess = ELFDATA2MSB 93 self.ehdr = get_arch_ehdr(self.endianess, 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.endianess, 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.endianess, 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 158def get_arch_note(endianess, len_name, len_desc): 159 """Returns a Note class with the specified endianess.""" 160 161 if endianess == 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 179class 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, endianess, 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 = endianess 200 self.ei_version = EV_CURRENT 201 202 203def get_arch_ehdr(endianess, elfclass): 204 """Returns a EHDR64 class with the specified endianess.""" 205 206 if endianess == 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(endianess, 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(endianess, 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(endianess, 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(endianess, 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 275def get_arch_phdr(endianess, elfclass): 276 """Returns a 32 or 64 bit PHDR class with the specified endianess.""" 277 278 if endianess == 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 314def int128_get64(val): 315 """Returns low 64bit part of Int128 struct.""" 316 317 assert val["hi"] == 0 318 return val["lo"] 319 320 321def 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 331def 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 343def 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 350def 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_addr"] & TARGET_PAGE_MASK) 356 357 358def 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. 435class DumpGuestMemory(gdb.Command): 436 """Extract guest vmcore from qemu process coredump. 437 438The two required arguments are FILE and ARCH: 439FILE identifies the target file to write the guest vmcore to. 440ARCH specifies the architecture for which the core will be generated. 441 442This GDB command reimplements the dump-guest-memory QMP command in 443python, using the representation of guest memory as captured in the qemu 444coredump. The qemu process that has been dumped must have had the 445command line option "-machine dump-guest-core=on" which is the default. 446 447For simplicity, the "paging", "begin" and "end" parameters of the QMP 448command are not supported -- no attempt is made to get the guest's 449internal paging structures (ie. paging=false is hard-wired), and guest 450memory is always fully dumped. 451 452Currently aarch64-be, aarch64-le, X86_64, 386, s390, ppc64-be, 453ppc64-le guests are supported. 454 455The CORE/NT_PRSTATUS and QEMU notes (that is, the VCPUs' statuses) are 456not written to the vmcore. Preparing these would require context that is 457only present in the KVM host kernel module when the guest is alive. A 458fake ELF note is written instead, only to keep the ELF parser of "crash" 459happy. 460 461Dependent on how busted the qemu process was at the time of the 462coredump, this command might produce unpredictable results. If qemu 463deliberately called abort(), or it was dumped in response to a signal at 464a halfway fortunate point, then its coredump should be in reasonable 465shape 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 529DumpGuestMemory() 530