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.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 158def 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 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, 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 203def 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 275def 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 314def int128_get64(val): 315 """Returns low 64bit part of Int128 struct.""" 316 317 try: 318 assert val["hi"] == 0 319 return val["lo"] 320 except gdb.error: 321 u64t = gdb.lookup_type('uint64_t').array(2) 322 u64 = val.cast(u64t) 323 if sys.byteorder == 'little': 324 assert u64[1] == 0 325 return u64[0] 326 else: 327 assert u64[0] == 0 328 return u64[1] 329 330 331def qlist_foreach(head, field_str): 332 """Generator for qlists.""" 333 334 var_p = head["lh_first"] 335 while var_p != 0: 336 var = var_p.dereference() 337 var_p = var[field_str]["le_next"] 338 yield var 339 340 341def qemu_map_ram_ptr(block, offset): 342 """Returns qemu vaddr for given guest physical address.""" 343 344 return block["host"] + offset 345 346 347def memory_region_get_ram_ptr(memory_region): 348 if memory_region["alias"] != 0: 349 return (memory_region_get_ram_ptr(memory_region["alias"].dereference()) 350 + memory_region["alias_offset"]) 351 352 return qemu_map_ram_ptr(memory_region["ram_block"], 0) 353 354 355def get_guest_phys_blocks(): 356 """Returns a list of ram blocks. 357 358 Each block entry contains: 359 'target_start': guest block phys start address 360 'target_end': guest block phys end address 361 'host_addr': qemu vaddr of the block's start 362 """ 363 364 guest_phys_blocks = [] 365 366 print("guest RAM blocks:") 367 print("target_start target_end host_addr message " 368 "count") 369 print("---------------- ---------------- ---------------- ------- " 370 "-----") 371 372 current_map_p = gdb.parse_and_eval("address_space_memory.current_map") 373 current_map = current_map_p.dereference() 374 375 # Conversion to int is needed for python 3 376 # compatibility. Otherwise range doesn't cast the value itself and 377 # breaks. 378 for cur in range(int(current_map["nr"])): 379 flat_range = (current_map["ranges"] + cur).dereference() 380 memory_region = flat_range["mr"].dereference() 381 382 # we only care about RAM 383 if not memory_region["ram"]: 384 continue 385 386 section_size = int128_get64(flat_range["addr"]["size"]) 387 target_start = int128_get64(flat_range["addr"]["start"]) 388 target_end = target_start + section_size 389 host_addr = (memory_region_get_ram_ptr(memory_region) 390 + flat_range["offset_in_region"]) 391 predecessor = None 392 393 # find continuity in guest physical address space 394 if len(guest_phys_blocks) > 0: 395 predecessor = guest_phys_blocks[-1] 396 predecessor_size = (predecessor["target_end"] - 397 predecessor["target_start"]) 398 399 # the memory API guarantees monotonically increasing 400 # traversal 401 assert predecessor["target_end"] <= target_start 402 403 # we want continuity in both guest-physical and 404 # host-virtual memory 405 if (predecessor["target_end"] < target_start or 406 predecessor["host_addr"] + predecessor_size != host_addr): 407 predecessor = None 408 409 if predecessor is None: 410 # isolated mapping, add it to the list 411 guest_phys_blocks.append({"target_start": target_start, 412 "target_end": target_end, 413 "host_addr": host_addr}) 414 message = "added" 415 else: 416 # expand predecessor until @target_end; predecessor's 417 # start doesn't change 418 predecessor["target_end"] = target_end 419 message = "joined" 420 421 print("%016x %016x %016x %-7s %5u" % 422 (target_start, target_end, host_addr.cast(UINTPTR_T), 423 message, len(guest_phys_blocks))) 424 425 return guest_phys_blocks 426 427 428# The leading docstring doesn't have idiomatic Python formatting. It is 429# printed by gdb's "help" command (the first line is printed in the 430# "help data" summary), and it should match how other help texts look in 431# gdb. 432class DumpGuestMemory(gdb.Command): 433 """Extract guest vmcore from qemu process coredump. 434 435The two required arguments are FILE and ARCH: 436FILE identifies the target file to write the guest vmcore to. 437ARCH specifies the architecture for which the core will be generated. 438 439This GDB command reimplements the dump-guest-memory QMP command in 440python, using the representation of guest memory as captured in the qemu 441coredump. The qemu process that has been dumped must have had the 442command line option "-machine dump-guest-core=on" which is the default. 443 444For simplicity, the "paging", "begin" and "end" parameters of the QMP 445command are not supported -- no attempt is made to get the guest's 446internal paging structures (ie. paging=false is hard-wired), and guest 447memory is always fully dumped. 448 449Currently aarch64-be, aarch64-le, X86_64, 386, s390, ppc64-be, 450ppc64-le guests are supported. 451 452The CORE/NT_PRSTATUS and QEMU notes (that is, the VCPUs' statuses) are 453not written to the vmcore. Preparing these would require context that is 454only present in the KVM host kernel module when the guest is alive. A 455fake ELF note is written instead, only to keep the ELF parser of "crash" 456happy. 457 458Dependent on how busted the qemu process was at the time of the 459coredump, this command might produce unpredictable results. If qemu 460deliberately called abort(), or it was dumped in response to a signal at 461a halfway fortunate point, then its coredump should be in reasonable 462shape and this command should mostly work.""" 463 464 def __init__(self): 465 super(DumpGuestMemory, self).__init__("dump-guest-memory", 466 gdb.COMMAND_DATA, 467 gdb.COMPLETE_FILENAME) 468 self.elf = None 469 self.guest_phys_blocks = None 470 471 def dump_init(self, vmcore): 472 """Prepares and writes ELF structures to core file.""" 473 474 # Needed to make crash happy, data for more useful notes is 475 # not available in a qemu core. 476 self.elf.add_note("NONE", "EMPTY", 0) 477 478 # We should never reach PN_XNUM for paging=false dumps, 479 # there's just a handful of discontiguous ranges after 480 # merging. 481 # The constant is needed to account for the PT_NOTE segment. 482 phdr_num = len(self.guest_phys_blocks) + 1 483 assert phdr_num < PN_XNUM 484 485 for block in self.guest_phys_blocks: 486 block_size = block["target_end"] - block["target_start"] 487 self.elf.add_segment(PT_LOAD, block["target_start"], block_size) 488 489 self.elf.to_file(vmcore) 490 491 def dump_iterate(self, vmcore): 492 """Writes guest core to file.""" 493 494 qemu_core = gdb.inferiors()[0] 495 for block in self.guest_phys_blocks: 496 cur = block["host_addr"] 497 left = block["target_end"] - block["target_start"] 498 print("dumping range at %016x for length %016x" % 499 (cur.cast(UINTPTR_T), left)) 500 501 while left > 0: 502 chunk_size = min(TARGET_PAGE_SIZE, left) 503 chunk = qemu_core.read_memory(cur, chunk_size) 504 vmcore.write(chunk) 505 cur += chunk_size 506 left -= chunk_size 507 508 def invoke(self, args, from_tty): 509 """Handles command invocation from gdb.""" 510 511 # Unwittingly pressing the Enter key after the command should 512 # not dump the same multi-gig coredump to the same file. 513 self.dont_repeat() 514 515 argv = gdb.string_to_argv(args) 516 if len(argv) != 2: 517 raise gdb.GdbError("usage: dump-guest-memory FILE ARCH") 518 519 self.elf = ELF(argv[1]) 520 self.guest_phys_blocks = get_guest_phys_blocks() 521 522 with open(argv[0], "wb") as vmcore: 523 self.dump_init(vmcore) 524 self.dump_iterate(vmcore) 525 526DumpGuestMemory() 527