scripts/signrom.py: Allow option ROM checksum script to write the size header.
[qemu/ar7.git] / scripts / dump-guest-memory.py
blobeb24f7874b5d3b9ce5daf43be10ff58dfaebc13e
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.
6 Copyright (C) 2013, Red Hat, Inc.
8 Authors:
9 Laszlo Ersek <lersek@redhat.com>
10 Janosch Frank <frankja@linux.vnet.ibm.com>
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 """
16 import ctypes
18 UINTPTR_T = gdb.lookup_type("uintptr_t")
20 TARGET_PAGE_SIZE = 0x1000
21 TARGET_PAGE_MASK = 0xFFFFFFFFFFFFF000
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
28 EV_CURRENT = 1
30 ELFCLASS32 = 1
31 ELFCLASS64 = 2
33 ELFDATA2LSB = 1
34 ELFDATA2MSB = 2
36 ET_CORE = 4
38 PT_LOAD = 1
39 PT_NOTE = 4
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
48 class ELF(object):
49 """Representation of a ELF file."""
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
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
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
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
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
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
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
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
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")
102 self.add_segment(PT_NOTE, 0, 0)
104 def add_note(self, n_name, n_desc, n_type):
105 """Adds a note to the ELF."""
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
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))
119 self.notes.append(note)
120 self.segments[0].p_filesz += ctypes.sizeof(note)
121 self.segments[0].p_memsz += ctypes.sizeof(note)
123 def add_segment(self, p_type, p_paddr, p_size):
124 """Adds a segment to the elf."""
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
134 def to_file(self, elf_file):
135 """Writes all ELF structures to the the passed file.
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
145 elf_file.write(self.ehdr)
146 off = ctypes.sizeof(self.ehdr) + \
147 len(self.segments) * ctypes.sizeof(self.segments[0])
149 for phdr in self.segments:
150 phdr.p_offset = off
151 elf_file.write(phdr)
152 off += phdr.p_filesz
154 for note in self.notes:
155 elf_file.write(note)
158 def get_arch_note(endianness, len_name, len_desc):
159 """Returns a Note class with the specified endianness."""
161 if endianness == ELFDATA2LSB:
162 superclass = ctypes.LittleEndianStructure
163 else:
164 superclass = ctypes.BigEndianStructure
166 len_name = len_name + 1
168 class Note(superclass):
169 """Represents an ELF note, includes the content."""
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()
179 class Ident(ctypes.Structure):
180 """Represents the ELF ident array in the ehdr structure."""
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)]
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
203 def get_arch_ehdr(endianness, elfclass):
204 """Returns a EHDR64 class with the specified endianness."""
206 if endianness == ELFDATA2LSB:
207 superclass = ctypes.LittleEndianStructure
208 else:
209 superclass = ctypes.BigEndianStructure
211 class EHDR64(superclass):
212 """Represents the 64 bit ELF header struct."""
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)]
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
240 class EHDR32(superclass):
241 """Represents the 32 bit ELF header struct."""
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)]
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
268 # End get_arch_ehdr
269 if elfclass == ELFCLASS64:
270 return EHDR64()
271 else:
272 return EHDR32()
275 def get_arch_phdr(endianness, elfclass):
276 """Returns a 32 or 64 bit PHDR class with the specified endianness."""
278 if endianness == ELFDATA2LSB:
279 superclass = ctypes.LittleEndianStructure
280 else:
281 superclass = ctypes.BigEndianStructure
283 class PHDR64(superclass):
284 """Represents the 64 bit ELF program header struct."""
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)]
295 class PHDR32(superclass):
296 """Represents the 32 bit ELF program header struct."""
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)]
307 # End get_arch_phdr
308 if elfclass == ELFCLASS64:
309 return PHDR64()
310 else:
311 return PHDR32()
314 def int128_get64(val):
315 """Returns low 64bit part of Int128 struct."""
317 assert val["hi"] == 0
318 return val["lo"]
321 def qlist_foreach(head, field_str):
322 """Generator for qlists."""
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
331 def qemu_get_ram_block(ram_addr):
332 """Returns the RAMBlock struct to which the given address belongs."""
334 ram_blocks = gdb.parse_and_eval("ram_list.blocks")
336 for block in qlist_foreach(ram_blocks, "next"):
337 if (ram_addr - block["offset"]) < block["used_length"]:
338 return block
340 raise gdb.GdbError("Bad ram offset %x" % ram_addr)
343 def qemu_get_ram_ptr(ram_addr):
344 """Returns qemu vaddr for given guest physical address."""
346 block = qemu_get_ram_block(ram_addr)
347 return block["host"] + (ram_addr - block["offset"])
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"])
355 return qemu_get_ram_ptr(memory_region["ram_block"]["offset"])
358 def get_guest_phys_blocks():
359 """Returns a list of ram blocks.
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
367 guest_phys_blocks = []
369 print("guest RAM blocks:")
370 print("target_start target_end host_addr message "
371 "count")
372 print("---------------- ---------------- ---------------- ------- "
373 "-----")
375 current_map_p = gdb.parse_and_eval("address_space_memory.current_map")
376 current_map = current_map_p.dereference()
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()
385 # we only care about RAM
386 if not memory_region["ram"]:
387 continue
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
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"])
402 # the memory API guarantees monotonically increasing
403 # traversal
404 assert predecessor["target_end"] <= target_start
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
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"
424 print("%016x %016x %016x %-7s %5u" %
425 (target_start, target_end, host_addr.cast(UINTPTR_T),
426 message, len(guest_phys_blocks)))
428 return guest_phys_blocks
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.
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.
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.
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.
452 Currently aarch64-be, aarch64-le, X86_64, 386, s390, ppc64-be,
453 ppc64-le guests are supported.
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.
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."""
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
474 def dump_init(self, vmcore):
475 """Prepares and writes ELF structures to core file."""
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)
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
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)
492 self.elf.to_file(vmcore)
494 def dump_iterate(self, vmcore):
495 """Writes guest core to file."""
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))
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
511 def invoke(self, args, from_tty):
512 """Handles command invocation from gdb."""
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()
518 argv = gdb.string_to_argv(args)
519 if len(argv) != 2:
520 raise gdb.GdbError("usage: dump-guest-memory FILE ARCH")
522 self.elf = ELF(argv[1])
523 self.guest_phys_blocks = get_guest_phys_blocks()
525 with open(argv[0], "wb") as vmcore:
526 self.dump_init(vmcore)
527 self.dump_iterate(vmcore)
529 DumpGuestMemory()