Text file src/runtime/runtime-gdb.py

Documentation: runtime

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

View as plain text