tools/gdbinit

# Copyright 2014 the V8 project authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.

# Print tagged object.
define job
call (void) _v8_internal_Print_Object((void*)($arg0))
end
document job
Print a v8 JavaScript object
Usage: job tagged_ptr
end

# Print content of V8 handles.
python
import gdb
import gdb.printing
import gdb.types

class PrintV8HandleCommand(gdb.Command):
  """Print content of a V8 object, accessed through a handle."""

  def __init__(self, command_name):
    self.command_name = command_name
    super(PrintV8HandleCommand, self).__init__(command_name, gdb.COMMAND_DATA)

  @staticmethod
  def print_direct(value, from_tty):
    CMD = "call (void) _v8_internal_Print_Object((v8::internal::Address*)({}))"
    gdb.execute(CMD.format(value.format_string()), from_tty)
    return True

  @staticmethod
  def print_indirect(value, from_tty):
    CMD = "call (void) _v8_internal_Print_Object(*(v8::internal::Address**)({}))"
    gdb.execute(CMD.format(value.format_string()), from_tty)
    return True

  def invoke(self, arg, from_tty):
    argv = gdb.string_to_argv(arg)
    if len(argv) != 1:
      raise gdb.GdbError("{} takes exactly one argument.".format(
          self.command_name))
    value = gdb.parse_and_eval(argv[0])
    if not self.print_handle(value, from_tty):
      raise gdb.GdbError("{} cannot print a value of type {}".format(
        self.command_name, value.type))


class PrintV8LocalCommand(PrintV8HandleCommand):
  """Print content of v8::(Maybe)?Local."""

  def __init__(self):
    super(PrintV8LocalCommand, self).__init__("print-v8-local")

  def print_handle(self, value, from_tty):
    if gdb.types.get_basic_type(value.type).code != gdb.TYPE_CODE_STRUCT:
      return False
    # After https://crrev.com/c/4335544, v8::MaybeLocal contains a local_.
    if gdb.types.has_field(value.type, "local_"):
      value = value["local_"]
    # After https://crrev.com/c/4335544, v8::Local contains a location_.
    if gdb.types.has_field(value.type, "location_"):
      return self.print_indirect(value["location_"], from_tty)
    # Before https://crrev.com/c/4335544, v8::Local contained a val_.
    if gdb.types.has_field(value.type, "val_"):
      return self.print_indirect(value["val_"], from_tty)
    # With v8_enable_direct_handle=true, v8::Local contains a ptr_.
    if gdb.types.has_field(value.type, "ptr_"):
      return self.print_direct(value["ptr_"], from_tty)
    # We don't know how to print this...
    return False

class PrintV8InternalHandleCommand(PrintV8HandleCommand):
  """Print content of v8::internal::(Maybe)?(Direct|Indirect)?Handle."""

  def __init__(self):
    super(PrintV8InternalHandleCommand, self).__init__("print-v8-internal-handle")

  def print_handle(self, value, from_tty):
    if gdb.types.get_basic_type(value.type).code != gdb.TYPE_CODE_STRUCT:
      return False
    # Indirect handles contain a location_.
    if gdb.types.has_field(value.type, "location_"):
      return self.print_indirect(value["location_"], from_tty)
    # With v8_enable_direct_handle=true, direct handles contain a obj_.
    if gdb.types.has_field(value.type, "obj_"):
      return self.print_direct(value["obj_"], from_tty)
    # Without v8_enable_direct_handle=true, direct handles contain a handle_.
    if gdb.types.has_field(value.type, "handle_"):
      return self.print_handle(value["handle_"], from_tty)
    # We don't know how to print this...
    return False

PrintV8LocalCommand()
PrintV8InternalHandleCommand()
end

python
class TryAliasCommand(gdb.Command):
  """Create an alias, but don't error if it already exists."""

  def __init__ (self):
    super (TryAliasCommand, self).__init__ ("try-alias", gdb.COMMAND_FILES)

  def invoke (self, arg, from_tty):
    try:
      gdb.execute('alias ' + arg)
    except:
      pass

TryAliasCommand()
end

try-alias jlh = print-v8-local
try-alias jl = print-v8-local
try-alias jh = print-v8-internal-handle

# Print Code objects containing given PC.
define jco
  if $argc == 0
    call (void) _v8_internal_Print_Code((void*)($pc))
  else
    call (void) _v8_internal_Print_Code((void*)($arg0))
  end
end
document jco
Print a v8 Code object from an internal code address
Usage: jco pc
end

# Print JSDispatchEntry object in the JSDispatchTable with the given dispatch handle
define jdh
  call (void) _v8_internal_Print_Dispatch_Handle((uint32_t)($arg0))
end
document jdh
Print JSDispatchEntry object in the JSDispatchTable with the given dispatch handle
Usage: jdh dispatch_handle
end

# Print Code objects assembly code surrounding given PC.
define jca
  if $argc == 0
    call (void) _v8_internal_Print_OnlyCode((void*)($pc), 30)
  else
    if $argc == 1
      call (void) _v8_internal_Print_OnlyCode((void*)($arg0), 30)
    else
      call (void) _v8_internal_Print_OnlyCode((void*)($arg0), (size_t)($arg1))
    end
  end
end
document jca
Print a v8 Code object assembly code from an internal code address
Usage: jca pc
end

# Print TransitionTree.
define jtt
call (void) _v8_internal_Print_TransitionTree((void*)($arg0), false)
end
document jtt
Print the complete transition tree starting at the given v8 map.
Usage: jtt tagged_ptr
end

# Print TransitionTree starting from the root map.
define jttr
call (void) _v8_internal_Print_TransitionTree((void*)($arg0), true)
end
document jttr
Print the complete transition tree starting at the root map of the given v8 map.
Usage: jttr tagged_ptr
end

# Print JavaScript stack trace.
define jst
call (void) _v8_internal_Print_StackTrace()
end
document jst
Print the current JavaScript stack trace
Usage: jst
end

# Print TurboFan graph node.
define pn
call _v8_internal_Node_Print((void*)($arg0))
end
document pn
Print a v8 TurboFan graph node
Usage: pn node_address
end

# Skip the JavaScript stack.
define jss
set $js_entry_sp=v8::internal::Isolate::Current()->thread_local_top()->js_entry_sp_
set $rbp=*(void**)$js_entry_sp
set $rsp=$js_entry_sp + 2*sizeof(void*)
set $pc=*(void**)($js_entry_sp+sizeof(void*))
end
document jss
Skip the jitted stack on x64 to where we entered JS last.
Usage: jss
end

# Print v8::FunctionCallbackInfo<T>& info.
define jfci
call _v8_internal_Print_FunctionCallbackInfo((void*)(&$arg0))
end
document jfci
Print v8::FunctionCallbackInfo<T>& info.
Usage: jfci info
end

# Print v8::PropertyCallbackInfo<T>& info.
define jpci
call _v8_internal_Print_PropertyCallbackInfo((void*)(&$arg0))
end
document jpci
Print v8::PropertyCallbackInfo<T>& info.
Usage: jpci info
end

# Print whether the object is marked, the mark-bit cell and index. The address
# of the cell is handy for reverse debugging to check when the object was
# marked/unmarked.
define jomb
call _v8_internal_Print_Object_MarkBit((void*)($arg0))
end
document jomb
Print whether the object is marked, the markbit cell and index.
Usage: jomb tagged_ptr
end

# Execute a simulator command.
python
import gdb

class SimCommand(gdb.Command):
  """Sim the current program."""

  def __init__ (self):
    super (SimCommand, self).__init__ ("sim", gdb.COMMAND_SUPPORT)

  def invoke (self, arg, from_tty):
    arg_bytes = arg.encode("utf-8") + b'\0'
    arg_c_string = gdb.Value(arg_bytes, gdb.lookup_type('char').array(len(arg_bytes) - 1))
    cmd_func = gdb.selected_frame().read_var("_v8_internal_Simulator_ExecDebugCommand")
    cmd_func(arg_c_string)

SimCommand()
end

# Print stack trace with assertion scopes.
define bta
python
import re
frame_re = re.compile("^#(\d+)\s*(?:0x[a-f\d]+ in )?(.+) \(.+ at (.+)")
assert_re = re.compile("^\s*(\S+) = .+<v8::internal::Per\w+AssertScope<v8::internal::(\S*), (false|true)>")
btl = gdb.execute("backtrace full", to_string = True).splitlines()
for l in btl:
  match = frame_re.match(l)
  if match:
    print("[%-2s] %-60s %-40s" % (match.group(1), match.group(2), match.group(3)))
  match = assert_re.match(l)
  if match:
    if match.group(3) == "false":
      prefix = "Disallow"
      color = "\033[91m"
    else:
      prefix = "Allow"
      color = "\033[92m"
    print("%s -> %s %s (%s)\033[0m" % (color, prefix, match.group(2), match.group(1)))
end
end
document bta
Print stack trace with assertion scopes
Usage: bta
end

# Search for a pointer inside all valid pages.
define space_find
  set $space = $arg0
  set $current_page = $space->first_page()
  while ($current_page != 0)
    printf "#   Searching in %p - %p\n", $current_page->area_start(), $current_page->area_end()-1
    find $current_page->area_start(), $current_page->area_end()-1, $arg1
    set $current_page = $current_page->next_page()
  end
end

define heap_find
  set $heap = v8::internal::Isolate::Current()->heap()
  printf "# Searching for %p in old_space  ===============================\n", $arg0
  space_find $heap->old_space() ($arg0)
  printf "# Searching for %p in map_space  ===============================\n", $arg0
  space_find $heap->map_space() $arg0
  printf "# Searching for %p in code_space ===============================\n", $arg0
  space_find $heap->code_space() $arg0
end
document heap_find
Find the location of a given address in V8 pages.
Usage: heap_find address
end

# The 'disassembly-flavor' command is only available on i386 and x84_64.
python
try:
  gdb.execute("set disassembly-flavor intel")
except gdb.error:
  pass
end

# Configuring ASLR may not be possible on some platforms, such running via the
# `rr` debugger.
python
try:
  gdb.execute("set disable-randomization off")
except gdb.error:
  pass
end

# Install a handler whenever the debugger stops due to a signal. It walks up the
# stack looking for V8_Dcheck / V8_Fatal / OS::DebugBreak frame and moves the
# frame to the one above it so it's immediately at the line of code that
# triggered the stop condition.
python
def v8_stop_handler(event):
  frame = gdb.selected_frame()
  select_frame = None
  message = None
  count = 0
  # Limit stack scanning since the frames we look for are near the top anyway,
  # and otherwise stack overflows can be very slow.
  while frame is not None and count < 10:
    count += 1
    # If we are in a frame created by gdb (e.g. for `(gdb) call foo()`), gdb
    # emits a dummy frame between its stack and the program's stack. Abort the
    # walk if we see this frame.
    if frame.type() == gdb.DUMMY_FRAME: break

    frame_name = frame.name()
    if frame_name is None:
      frame = frame.older()
      continue
    if frame_name == 'V8_Dcheck' or frame_name.endswith('::DefaultDcheckHandler'):
      try:
        frame_message = gdb.lookup_symbol('message', frame.block())[0]
        if frame_message:
          message = frame_message.value(frame).string()
      except:
        pass
      select_frame = frame.older()
    if any([
        frame_name.startswith('V8_Fatal'),
        frame_name == 'v8::base::OS::DebugBreak',
        frame_name == '__GI_abort',
        frame_name == '__GI_raise',
        frame_name == 'v8::base::OS::Abort',
        frame_name == 'v8::Utils::ApiCheck',
      ]):
      select_frame = frame.older()
    frame = frame.older()

  if select_frame is not None:
    select_frame.select()
    gdb.execute('frame')
    if message:
      print('==> DCHECK error: {}'.format(message))

gdb.events.stop.connect(v8_stop_handler)
end

# Code imported from chromium/src/tools/gdb/gdbinit
python

import os
import subprocess
import sys

compile_dirs = set()
src_dir = None

def get_current_debug_file_directories():
  dir = gdb.execute("show debug-file-directory", to_string=True)
  dir = dir[
      len('The directory where separate debug symbols are searched for is "'
         ):-len('".') - 1]
  return set(dir.split(":"))


def add_debug_file_directory(dir):
  # gdb has no function to add debug-file-directory, simulates that by using
  # `show debug-file-directory` and `set debug-file-directory <directories>`.
  current_dirs = get_current_debug_file_directories()
  current_dirs.add(dir)
  gdb.execute(
      "set debug-file-directory %s" % ":".join(current_dirs), to_string=True)


def load_libcxx_pretty_printers(src_dir):
  libcxx_pretty_printers = os.path.join(src_dir, 'third_party', 'libc++', 'src',
                                        'utils', 'gdb', 'libcxx')
  if not os.path.isdir(libcxx_pretty_printers):
    return
  sys.path.insert(1, libcxx_pretty_printers)
  from printers import register_libcxx_printer_loader
  register_libcxx_printer_loader()


def set_src_dir(compile_dir):
  global src_dir
  git = subprocess.Popen(
      ['git', '-C', compile_dir, 'rev-parse', '--show-toplevel'],
      stdout=subprocess.PIPE,
      stderr=subprocess.PIPE)
  src_dir, _ = git.communicate()
  if git.returncode:
    return
  if isinstance(src_dir, str):
    src_dir = src_dir.rstrip()
  else:
    src_dir = src_dir.decode('utf-8').rstrip()

  # If there's no LICENSE.v8 file in the repo root, we got the wrong git repo.
  # The most common way to have this happen is to be in a git checkout of
  # another project that vendors chromium in its own third_party directory. In
  # that case, try falling back to the current working directory.
  if not os.path.isfile(os.path.join(src_dir, 'LICENSE.v8')):
    src_dir = os.path.abspath(os.getcwd())

  load_libcxx_pretty_printers(src_dir)


def newobj_handler(event):
  global compile_dirs
  compile_dir = os.path.dirname(event.new_objfile.filename)
  if not compile_dir:
    return
  if compile_dir in compile_dirs:
    return
  compile_dirs.add(compile_dir)

  # Add source path
  gdb.execute("dir %s" % compile_dir)

  # Need to tell the location of .dwo files.
  # https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html
  # https://crbug.com/603286#c35
  add_debug_file_directory(compile_dir)
  
  global src_dir
  if not src_dir:
    set_src_dir(compile_dir)

# Event hook for newly loaded objfiles.
# https://sourceware.org/gdb/onlinedocs/gdb/Events-In-Python.html
gdb.events.new_objfile.connect(newobj_handler)

gdb.execute("set environment V8_GDBINIT_SOURCED=1")

end

### CppGC helpers.

# Pretty printer for cppgc::Member.
python

import re


class CppGCMemberPrinter(object):
  """Print cppgc Member types."""

  def __init__(self, val, category, pointee_type):
    self.val = val
    self.category = category
    self.pointee_type = pointee_type

  def to_string(self):
    pointer = gdb.parse_and_eval(
        "_cppgc_internal_Uncompress_Member((void*){})".format(
            self.val.address))
    return "{}Member<{}> pointing to {}".format(
        '' if self.category is None else self.category, self.pointee_type,
        pointer)

  def display_hint(self):
    return "{}Member<{}>".format('' if self.category is None else self.category,
                                 self.pointee_type)


def cppgc_pretty_printers(val):
  typename = val.type.name or val.type.tag or str(val.type)
  regex = re.compile("^(cppgc|blink)::(Weak|Untraced)?Member<(.*)>$")
  match = regex.match(typename)
  if match is not None:
    return CppGCMemberPrinter(
        val, category=match.group(2), pointee_type=match.group(3))

  # The member type might have been obscured by typedefs and template
  # arguments. Fallback to using the underlying type.
  real_type = val.type.strip_typedefs()
  if (real_type.name is not None and
      real_type.name.startswith('cppgc::internal::BasicMember')):
    inner_type = real_type.template_argument(0)
    return CppGCMemberPrinter(
        val, category='Basic', pointee_type=inner_type.name)

  return None


gdb.pretty_printers.append(cppgc_pretty_printers)

class TaggedPrintCommand(gdb.Command):
    """
    The equivalent of the print command that deals with tagged objects

    Usage: tp <expression>
    Example: tp Isolate::Current()->context()->get(3)
    """

    def __init__(self):
        super(TaggedPrintCommand, self).__init__("tp", gdb.COMMAND_DATA, gdb.COMPLETE_EXPRESSION)

    def invoke(self, arg, from_tty):
        """Called when the 'tp' command is invoked."""
        try:
            # Split the expression by '->' to handle chained calls.
            parts = arg.split("->")
            if not parts:
                print("Error: No expression provided.")
                return

            if len(parts) == 1:
              gdb.execute(f"print {parts[0]}")
            else:
              current_val = gdb.parse_and_eval(parts[0])
              for part in parts[1:-1]:
                  current_val = self._evaluate_part(current_val, part, False)
                  if current_val is None:  # Early exit if an evaluation fails.
                      return

              self._evaluate_part(current_val, parts[-1], True)

        except gdb.error as e:
            print(f"Error: {e}")

    def _evaluate_part(self, current_val, part, last):
        """Evaluates a single part of the expression (method call or member access)."""

        storage = None
        target = f"(({current_val.type}){current_val})"

        type = current_val.type
        if type.tag and type.tag.startswith("v8::internal::Tagged<"):
          storage = gdb.parse_and_eval(f"malloc({type.sizeof})").cast(type.pointer())
          command = f"(({storage.type}){storage})->ptr_ = {current_val['ptr_']}"
          gdb.parse_and_eval(command)
          target = f"(({storage.type}){storage})->ToRawPtr()"

        # Check for a method call (ends with parentheses).
        command = f"{target}->{part}"
        result = None
        if last:
          gdb.execute(f"print {command}")
        else:
          result = gdb.parse_and_eval(command)
        if storage:
          gdb.parse_and_eval(f"free({storage})")
        return result

TaggedPrintCommand()


static_roots_cache = None
def GetStaticRoot(ptr):
  global static_roots_cache
  if static_roots_cache is None:
    static_roots_cache = {}
    try:
      for field in gdb.lookup_type("v8::internal::StaticReadOnlyRoot").fields():
        value = gdb.parse_and_eval("v8::internal::StaticReadOnlyRoot::"+field.name)
        if int(value) in static_roots_cache:
          static_roots_cache[int(value)] += "," + field.name
        else:
          static_roots_cache[int(value)] = field.name
    except Exception as e:
      print("Warning, couldn't find static roots: ", e)
  ptr = ptr & 0xFFFFFFFF
  return static_roots_cache.get(ptr, None)


def InterpretTaggedPointer(pointer):
  if (pointer & 0x1) == 0:
    return f"Smi: {pointer >> 1}"
  
  static_root = GetStaticRoot(pointer)
  if static_root is not None:
    return f"{static_root}"

  return None


def OptimizedOutToNone(val):
  if val is None:
    return None
  if val.is_optimized_out:
    return None
  return val


class TaggedPrinter(object):
  """Print Tagged<Foo> types."""

  def __init__(self, val, pointee_type):
    self.val = OptimizedOutToNone(val)
    self.pointee_type = pointee_type.lstrip('v8::internal::')
    self.ptr = self.val["ptr_"] if self.val is not None else None

  def to_string(self):
    if self.ptr is None:
      return f"Tagged<{self.pointee_type}>{{<optimized out>}}"
    pointer = int(self.ptr)
    fmt = f"Tagged<{self.pointee_type}>{{0x{pointer:02x}}}"
    if (label := InterpretTaggedPointer(pointer)) is not None:
      fmt += f" ({label})"          
    return fmt


def tagged_pretty_printers(val):
  # The member type might have been obscured by typedefs and template
  # arguments. Fallback to using the underlying type.
  real_type = val.type.strip_typedefs()
  typename = real_type.name or real_type.tag or str(real_type)
  regex = re.compile("^v8::internal::Tagged<(.*)>$")
  match = regex.match(typename)
  if match is not None:
    return TaggedPrinter(val, pointee_type=match.group(1))

  return None


gdb.pretty_printers.append(tagged_pretty_printers)


class HandlePrinter(object):
  """Print Handle<Foo> types."""

  def __init__(self, val, pointee_type):
    self.val = OptimizedOutToNone(val)
    self.pointee_type = pointee_type.lstrip('v8::internal::')
    self.location = OptimizedOutToNone(self.val["location_"] if self.val is not None else None)
    self.ptr = self.location.dereference() if self.location is not None else None

  def to_string(self):
    if self.location is None:
      return f"Handle<{self.pointee_type}>{{<optimized out>}}"
    location = int(self.location)
    fmt = f"Handle<{self.pointee_type}>{{0x{location:02x}}}: "
    if self.ptr is None:
      fmt += f"<optimized out>"
    else:
      pointer = None
      try:
        pointer = int(self.ptr)
      except Exception as e:
        fmt += f"[{e}]"
      else:
        fmt += f"0x{pointer:02x}"
        if (label := InterpretTaggedPointer(pointer)) is not None:
          fmt += f" ({label})"
          
    return fmt


def handle_pretty_printers(val):
  # The member type might have been obscured by typedefs and template
  # arguments. Fallback to using the underlying type.
  real_type = val.type.strip_typedefs()
  typename = real_type.name or real_type.tag or str(real_type)
  regex = re.compile("^v8::internal::(?:Indirect)?Handle<(.*)>$")
  match = regex.match(typename)
  if match is not None:
    return HandlePrinter(val, pointee_type=match.group(1))

  return None


gdb.pretty_printers.append(handle_pretty_printers)


class DirectHandlePrinter(object):
  """Print DirectHandle<Foo> types."""

  def __init__(self, val, pointee_type):
    self.val = val
    self.pointee_type = pointee_type.lstrip('v8::internal::')
    self.inner = None
    if gdb.types.has_field(self.val.type, "handle_"):
      self.inner = HandlePrinter(val['handle_'], pointee_type)
    elif gdb.types.has_field(self.val.type, "obj_"):
      self.inner = TaggedPrinter(val['obj_'], pointee_type)
    else:
      print("Warning: No recognised DirectHandle field")

  def to_string(self):
    if self.inner is not None:
      return self.inner.to_string()


def direct_handle_pretty_printers(val):
  # The member type might have been obscured by typedefs and template
  # arguments. Fallback to using the underlying type.
  real_type = val.type.strip_typedefs()
  typename = real_type.name or real_type.tag or str(real_type)
  regex = re.compile("^v8::internal::DirectHandle<(.*)>$")
  match = regex.match(typename)
  if match is not None:
    if gdb.types.has_field(real_type, "handle_"):
      handle = None
      if not val.is_optimized_out:
        handle = val['handle_']
      return HandlePrinter(handle, match.group(1))
    elif gdb.types.has_field(real_type, "obj_"):
      obj = None
      if not val.is_optimized_out:
        obj = val['obj_']
      return TaggedPrinter(obj, match.group(1))

  return None

gdb.pretty_printers.append(direct_handle_pretty_printers)

end