1# Copyright 2010 The Go Authors. All rights reserved.
2# Use of this source code is governed by a BSD-style
3# license that can be found in the LICENSE file.
4
5"""GDB Pretty printers and convenience functions for Go's runtime structures.
6
7This script is loaded by GDB when it finds a .debug_gdb_scripts
8section in the compiled binary. The [68]l linkers emit this with a
9path to this file based on the path to the runtime package.
10"""
11
12# Known issues:
13#    - pretty printing only works for the 'native' strings. E.g. 'type
14#      foo string' will make foo a plain struct in the eyes of gdb,
15#      circumventing the pretty print triggering.
16
17
18from __future__ import print_function
19import re
20import sys
21import gdb
22
23print("Loading Go Runtime support.", file=sys.stderr)
24#http://python3porting.com/differences.html
25if sys.version > '3':
26	xrange = range
27# allow to manually reload while developing
28goobjfile = gdb.current_objfile() or gdb.objfiles()[0]
29goobjfile.pretty_printers = []
30
31# G state (runtime2.go)
32
33def read_runtime_const(varname, default):
34  try:
35    return int(gdb.parse_and_eval(varname))
36  except Exception:
37    return int(default)
38
39
40G_IDLE = read_runtime_const("'runtime._Gidle'", 0)
41G_RUNNABLE = read_runtime_const("'runtime._Grunnable'", 1)
42G_RUNNING = read_runtime_const("'runtime._Grunning'", 2)
43G_SYSCALL = read_runtime_const("'runtime._Gsyscall'", 3)
44G_WAITING = read_runtime_const("'runtime._Gwaiting'", 4)
45G_MORIBUND_UNUSED = read_runtime_const("'runtime._Gmoribund_unused'", 5)
46G_DEAD = read_runtime_const("'runtime._Gdead'", 6)
47G_ENQUEUE_UNUSED = read_runtime_const("'runtime._Genqueue_unused'", 7)
48G_COPYSTACK = read_runtime_const("'runtime._Gcopystack'", 8)
49G_SCAN = read_runtime_const("'runtime._Gscan'", 0x1000)
50G_SCANRUNNABLE = G_SCAN+G_RUNNABLE
51G_SCANRUNNING = G_SCAN+G_RUNNING
52G_SCANSYSCALL = G_SCAN+G_SYSCALL
53G_SCANWAITING = G_SCAN+G_WAITING
54
55sts = {
56    G_IDLE: 'idle',
57    G_RUNNABLE: 'runnable',
58    G_RUNNING: 'running',
59    G_SYSCALL: 'syscall',
60    G_WAITING: 'waiting',
61    G_MORIBUND_UNUSED: 'moribund',
62    G_DEAD: 'dead',
63    G_ENQUEUE_UNUSED: 'enqueue',
64    G_COPYSTACK: 'copystack',
65    G_SCAN: 'scan',
66    G_SCANRUNNABLE: 'runnable+s',
67    G_SCANRUNNING: 'running+s',
68    G_SCANSYSCALL: 'syscall+s',
69    G_SCANWAITING: 'waiting+s',
70}
71
72
73#
74#  Value wrappers
75#
76
77class SliceValue:
78	"Wrapper for slice values."
79
80	def __init__(self, val):
81		self.val = val
82
83	@property
84	def len(self):
85		return int(self.val['len'])
86
87	@property
88	def cap(self):
89		return int(self.val['cap'])
90
91	def __getitem__(self, i):
92		if i < 0 or i >= self.len:
93			raise IndexError(i)
94		ptr = self.val["array"]
95		return (ptr + i).dereference()
96
97
98#
99#  Pretty Printers
100#
101
102# The patterns for matching types are permissive because gdb 8.2 switched to matching on (we think) typedef names instead of C syntax names.
103class StringTypePrinter:
104	"Pretty print Go strings."
105
106	pattern = re.compile(r'^(struct string( \*)?|string)$')
107
108	def __init__(self, val):
109		self.val = val
110
111	def display_hint(self):
112		return 'string'
113
114	def to_string(self):
115		l = int(self.val['len'])
116		return self.val['str'].string("utf-8", "ignore", l)
117
118
119class SliceTypePrinter:
120	"Pretty print slices."
121
122	pattern = re.compile(r'^(struct \[\]|\[\])')
123
124	def __init__(self, val):
125		self.val = val
126
127	def display_hint(self):
128		return 'array'
129
130	def to_string(self):
131		t = str(self.val.type)
132		if (t.startswith("struct ")):
133			return t[len("struct "):]
134		return t
135
136	def children(self):
137		sval = SliceValue(self.val)
138		if sval.len > sval.cap:
139			return
140		for idx, item in enumerate(sval):
141			yield ('[{0}]'.format(idx), item)
142
143
144class MapTypePrinter:
145	"""Pretty print map[K]V types.
146
147	Map-typed go variables are really pointers. dereference them in gdb
148	to inspect their contents with this pretty printer.
149	"""
150
151	pattern = re.compile(r'^map\[.*\].*$')
152
153	def __init__(self, val):
154		self.val = val
155
156	def display_hint(self):
157		return 'map'
158
159	def to_string(self):
160		return str(self.val.type)
161
162	def children(self):
163		MapBucketCount = 8 # see internal/abi.go:MapBucketCount
164		B = self.val['B']
165		buckets = self.val['buckets']
166		oldbuckets = self.val['oldbuckets']
167		flags = self.val['flags']
168		inttype = self.val['hash0'].type
169		cnt = 0
170		for bucket in xrange(2 ** int(B)):
171			bp = buckets + bucket
172			if oldbuckets:
173				oldbucket = bucket & (2 ** (B - 1) - 1)
174				oldbp = oldbuckets + oldbucket
175				oldb = oldbp.dereference()
176				if (oldb['overflow'].cast(inttype) & 1) == 0:  # old bucket not evacuated yet
177					if bucket >= 2 ** (B - 1):
178						continue    # already did old bucket
179					bp = oldbp
180			while bp:
181				b = bp.dereference()
182				for i in xrange(MapBucketCount):
183					if b['tophash'][i] != 0:
184						k = b['keys'][i]
185						v = b['values'][i]
186						if flags & 1:
187							k = k.dereference()
188						if flags & 2:
189							v = v.dereference()
190						yield str(cnt), k
191						yield str(cnt + 1), v
192						cnt += 2
193				bp = b['overflow']
194
195
196class ChanTypePrinter:
197	"""Pretty print chan[T] types.
198
199	Chan-typed go variables are really pointers. dereference them in gdb
200	to inspect their contents with this pretty printer.
201	"""
202
203	pattern = re.compile(r'^chan ')
204
205	def __init__(self, val):
206		self.val = val
207
208	def display_hint(self):
209		return 'array'
210
211	def to_string(self):
212		return str(self.val.type)
213
214	def children(self):
215		# see chan.c chanbuf(). et is the type stolen from hchan<T>::recvq->first->elem
216		et = [x.type for x in self.val['recvq']['first'].type.target().fields() if x.name == 'elem'][0]
217		ptr = (self.val.address["buf"]).cast(et)
218		for i in range(self.val["qcount"]):
219			j = (self.val["recvx"] + i) % self.val["dataqsiz"]
220			yield ('[{0}]'.format(i), (ptr + j).dereference())
221
222
223def paramtypematch(t, pattern):
224	return t.code == gdb.TYPE_CODE_TYPEDEF and str(t).startswith(".param") and pattern.match(str(t.target()))
225
226#
227#  Register all the *Printer classes above.
228#
229
230def makematcher(klass):
231	def matcher(val):
232		try:
233			if klass.pattern.match(str(val.type)):
234				return klass(val)
235			elif paramtypematch(val.type, klass.pattern):
236				return klass(val.cast(val.type.target()))
237		except Exception:
238			pass
239	return matcher
240
241goobjfile.pretty_printers.extend([makematcher(var) for var in vars().values() if hasattr(var, 'pattern')])
242#
243#  Utilities
244#
245
246def pc_to_int(pc):
247	# python2 will not cast pc (type void*) to an int cleanly
248	# instead python2 and python3 work with the hex string representation
249	# of the void pointer which we can parse back into an int.
250	# int(pc) will not work.
251	try:
252		# python3 / newer versions of gdb
253		pc = int(pc)
254	except gdb.error:
255		# str(pc) can return things like
256		# "0x429d6c <runtime.gopark+284>", so
257		# chop at first space.
258		pc = int(str(pc).split(None, 1)[0], 16)
259	return pc
260
261
262#
263#  For reference, this is what we're trying to do:
264#  eface: p *(*(struct 'runtime.rtype'*)'main.e'->type_->data)->string
265#  iface: p *(*(struct 'runtime.rtype'*)'main.s'->tab->Type->data)->string
266#
267# interface types can't be recognized by their name, instead we check
268# if they have the expected fields.  Unfortunately the mapping of
269# fields to python attributes in gdb.py isn't complete: you can't test
270# for presence other than by trapping.
271
272
273def is_iface(val):
274	try:
275		return str(val['tab'].type) == "struct runtime.itab *" and str(val['data'].type) == "void *"
276	except gdb.error:
277		pass
278
279
280def is_eface(val):
281	try:
282		return str(val['_type'].type) == "struct runtime._type *" and str(val['data'].type) == "void *"
283	except gdb.error:
284		pass
285
286
287def lookup_type(name):
288	try:
289		return gdb.lookup_type(name)
290	except gdb.error:
291		pass
292	try:
293		return gdb.lookup_type('struct ' + name)
294	except gdb.error:
295		pass
296	try:
297		return gdb.lookup_type('struct ' + name[1:]).pointer()
298	except gdb.error:
299		pass
300
301
302def iface_commontype(obj):
303	if is_iface(obj):
304		go_type_ptr = obj['tab']['_type']
305	elif is_eface(obj):
306		go_type_ptr = obj['_type']
307	else:
308		return
309
310	return go_type_ptr.cast(gdb.lookup_type("struct reflect.rtype").pointer()).dereference()
311
312
313def iface_dtype(obj):
314	"Decode type of the data field of an eface or iface struct."
315	# known issue: dtype_name decoded from runtime.rtype is "nested.Foo"
316	# but the dwarf table lists it as "full/path/to/nested.Foo"
317
318	dynamic_go_type = iface_commontype(obj)
319	if dynamic_go_type is None:
320		return
321	dtype_name = dynamic_go_type['string'].dereference()['str'].string()
322
323	dynamic_gdb_type = lookup_type(dtype_name)
324	if dynamic_gdb_type is None:
325		return
326
327	type_size = int(dynamic_go_type['size'])
328	uintptr_size = int(dynamic_go_type['size'].type.sizeof)	 # size is itself a uintptr
329	if type_size > uintptr_size:
330			dynamic_gdb_type = dynamic_gdb_type.pointer()
331
332	return dynamic_gdb_type
333
334
335def iface_dtype_name(obj):
336	"Decode type name of the data field of an eface or iface struct."
337
338	dynamic_go_type = iface_commontype(obj)
339	if dynamic_go_type is None:
340		return
341	return dynamic_go_type['string'].dereference()['str'].string()
342
343
344class IfacePrinter:
345	"""Pretty print interface values
346
347	Casts the data field to the appropriate dynamic type."""
348
349	def __init__(self, val):
350		self.val = val
351
352	def display_hint(self):
353		return 'string'
354
355	def to_string(self):
356		if self.val['data'] == 0:
357			return 0x0
358		try:
359			dtype = iface_dtype(self.val)
360		except Exception:
361			return "<bad dynamic type>"
362
363		if dtype is None:  # trouble looking up, print something reasonable
364			return "({typename}){data}".format(
365				typename=iface_dtype_name(self.val), data=self.val['data'])
366
367		try:
368			return self.val['data'].cast(dtype).dereference()
369		except Exception:
370			pass
371		return self.val['data'].cast(dtype)
372
373
374def ifacematcher(val):
375	if is_iface(val) or is_eface(val):
376		return IfacePrinter(val)
377
378goobjfile.pretty_printers.append(ifacematcher)
379
380#
381#  Convenience Functions
382#
383
384
385class GoLenFunc(gdb.Function):
386	"Length of strings, slices, maps or channels"
387
388	how = ((StringTypePrinter, 'len'), (SliceTypePrinter, 'len'), (MapTypePrinter, 'count'), (ChanTypePrinter, 'qcount'))
389
390	def __init__(self):
391		gdb.Function.__init__(self, "len")
392
393	def invoke(self, obj):
394		typename = str(obj.type)
395		for klass, fld in self.how:
396			if klass.pattern.match(typename) or paramtypematch(obj.type, klass.pattern):
397				return obj[fld]
398
399
400class GoCapFunc(gdb.Function):
401	"Capacity of slices or channels"
402
403	how = ((SliceTypePrinter, 'cap'), (ChanTypePrinter, 'dataqsiz'))
404
405	def __init__(self):
406		gdb.Function.__init__(self, "cap")
407
408	def invoke(self, obj):
409		typename = str(obj.type)
410		for klass, fld in self.how:
411			if klass.pattern.match(typename) or paramtypematch(obj.type, klass.pattern):
412				return obj[fld]
413
414
415class DTypeFunc(gdb.Function):
416	"""Cast Interface values to their dynamic type.
417
418	For non-interface types this behaves as the identity operation.
419	"""
420
421	def __init__(self):
422		gdb.Function.__init__(self, "dtype")
423
424	def invoke(self, obj):
425		try:
426			return obj['data'].cast(iface_dtype(obj))
427		except gdb.error:
428			pass
429		return obj
430
431#
432#  Commands
433#
434
435def linked_list(ptr, linkfield):
436	while ptr:
437		yield ptr
438		ptr = ptr[linkfield]
439
440
441class GoroutinesCmd(gdb.Command):
442	"List all goroutines."
443
444	def __init__(self):
445		gdb.Command.__init__(self, "info goroutines", gdb.COMMAND_STACK, gdb.COMPLETE_NONE)
446
447	def invoke(self, _arg, _from_tty):
448		# args = gdb.string_to_argv(arg)
449		vp = gdb.lookup_type('void').pointer()
450		for ptr in SliceValue(gdb.parse_and_eval("'runtime.allgs'")):
451			if ptr['atomicstatus']['value'] == G_DEAD:
452				continue
453			s = ' '
454			if ptr['m']:
455				s = '*'
456			pc = ptr['sched']['pc'].cast(vp)
457			pc = pc_to_int(pc)
458			blk = gdb.block_for_pc(pc)
459			status = int(ptr['atomicstatus']['value'])
460			st = sts.get(status, "unknown(%d)" % status)
461			print(s, ptr['goid'], "{0:8s}".format(st), blk.function)
462
463
464def find_goroutine(goid):
465	"""
466	find_goroutine attempts to find the goroutine identified by goid.
467	It returns a tuple of gdb.Value's representing the stack pointer
468	and program counter pointer for the goroutine.
469
470	@param int goid
471
472	@return tuple (gdb.Value, gdb.Value)
473	"""
474	vp = gdb.lookup_type('void').pointer()
475	for ptr in SliceValue(gdb.parse_and_eval("'runtime.allgs'")):
476		if ptr['atomicstatus']['value'] == G_DEAD:
477			continue
478		if ptr['goid'] == goid:
479			break
480	else:
481		return None, None
482	# Get the goroutine's saved state.
483	pc, sp = ptr['sched']['pc'], ptr['sched']['sp']
484	status = ptr['atomicstatus']['value']&~G_SCAN
485	# Goroutine is not running nor in syscall, so use the info in goroutine
486	if status != G_RUNNING and status != G_SYSCALL:
487		return pc.cast(vp), sp.cast(vp)
488
489	# If the goroutine is in a syscall, use syscallpc/sp.
490	pc, sp = ptr['syscallpc'], ptr['syscallsp']
491	if sp != 0:
492		return pc.cast(vp), sp.cast(vp)
493	# Otherwise, the goroutine is running, so it doesn't have
494	# saved scheduler state. Find G's OS thread.
495	m = ptr['m']
496	if m == 0:
497		return None, None
498	for thr in gdb.selected_inferior().threads():
499		if thr.ptid[1] == m['procid']:
500			break
501	else:
502		return None, None
503	# Get scheduler state from the G's OS thread state.
504	curthr = gdb.selected_thread()
505	try:
506		thr.switch()
507		pc = gdb.parse_and_eval('$pc')
508		sp = gdb.parse_and_eval('$sp')
509	finally:
510		curthr.switch()
511	return pc.cast(vp), sp.cast(vp)
512
513
514class GoroutineCmd(gdb.Command):
515	"""Execute gdb command in the context of goroutine <goid>.
516
517	Switch PC and SP to the ones in the goroutine's G structure,
518	execute an arbitrary gdb command, and restore PC and SP.
519
520	Usage: (gdb) goroutine <goid> <gdbcmd>
521
522	You could pass "all" as <goid> to apply <gdbcmd> to all goroutines.
523
524	For example: (gdb) goroutine all <gdbcmd>
525
526	Note that it is ill-defined to modify state in the context of a goroutine.
527	Restrict yourself to inspecting values.
528	"""
529
530	def __init__(self):
531		gdb.Command.__init__(self, "goroutine", gdb.COMMAND_STACK, gdb.COMPLETE_NONE)
532
533	def invoke(self, arg, _from_tty):
534		goid_str, cmd = arg.split(None, 1)
535		goids = []
536
537		if goid_str == 'all':
538			for ptr in SliceValue(gdb.parse_and_eval("'runtime.allgs'")):
539				goids.append(int(ptr['goid']))
540		else:
541			goids = [int(gdb.parse_and_eval(goid_str))]
542
543		for goid in goids:
544			self.invoke_per_goid(goid, cmd)
545
546	def invoke_per_goid(self, goid, cmd):
547		pc, sp = find_goroutine(goid)
548		if not pc:
549			print("No such goroutine: ", goid)
550			return
551		pc = pc_to_int(pc)
552		save_frame = gdb.selected_frame()
553		gdb.parse_and_eval('$save_sp = $sp')
554		gdb.parse_and_eval('$save_pc = $pc')
555		# In GDB, assignments to sp must be done from the
556		# top-most frame, so select frame 0 first.
557		gdb.execute('select-frame 0')
558		gdb.parse_and_eval('$sp = {0}'.format(str(sp)))
559		gdb.parse_and_eval('$pc = {0}'.format(str(pc)))
560		try:
561			gdb.execute(cmd)
562		finally:
563			# In GDB, assignments to sp must be done from the
564			# top-most frame, so select frame 0 first.
565			gdb.execute('select-frame 0')
566			gdb.parse_and_eval('$pc = $save_pc')
567			gdb.parse_and_eval('$sp = $save_sp')
568			save_frame.select()
569
570
571class GoIfaceCmd(gdb.Command):
572	"Print Static and dynamic interface types"
573
574	def __init__(self):
575		gdb.Command.__init__(self, "iface", gdb.COMMAND_DATA, gdb.COMPLETE_SYMBOL)
576
577	def invoke(self, arg, _from_tty):
578		for obj in gdb.string_to_argv(arg):
579			try:
580				#TODO fix quoting for qualified variable names
581				obj = gdb.parse_and_eval(str(obj))
582			except Exception as e:
583				print("Can't parse ", obj, ": ", e)
584				continue
585
586			if obj['data'] == 0:
587				dtype = "nil"
588			else:
589				dtype = iface_dtype(obj)
590
591			if dtype is None:
592				print("Not an interface: ", obj.type)
593				continue
594
595			print("{0}: {1}".format(obj.type, dtype))
596
597# TODO: print interface's methods and dynamic type's func pointers thereof.
598#rsc: "to find the number of entries in the itab's Fn field look at
599# itab.inter->numMethods
600# i am sure i have the names wrong but look at the interface type
601# and its method count"
602# so Itype will start with a commontype which has kind = interface
603
604#
605# Register all convenience functions and CLI commands
606#
607GoLenFunc()
608GoCapFunc()
609DTypeFunc()
610GoroutinesCmd()
611GoroutineCmd()
612GoIfaceCmd()
613