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