toolbox 0.1.4 → 0.2.0

data/data/toolbox/constants.py

@@ -0,0 +1,200 @@
+import debugger
+
+# Global shared cache for Ruby constants
+_CACHE = {}
+
+# Global shared cache for debugger type lookups
+_TYPE_CACHE = {}
+
+# Default values for Ruby type constants (ruby_value_type enum)
+_TYPE_DEFAULTS = {
+	'RUBY_T_NONE': 0x00,
+	'RUBY_T_OBJECT': 0x01,
+	'RUBY_T_CLASS': 0x02,
+	'RUBY_T_MODULE': 0x03,
+	'RUBY_T_FLOAT': 0x04,
+	'RUBY_T_STRING': 0x05,
+	'RUBY_T_REGEXP': 0x06,
+	'RUBY_T_ARRAY': 0x07,
+	'RUBY_T_HASH': 0x08,
+	'RUBY_T_STRUCT': 0x09,
+	'RUBY_T_BIGNUM': 0x0a,
+	'RUBY_T_FILE': 0x0b,
+	'RUBY_T_DATA': 0x0c,
+	'RUBY_T_MATCH': 0x0d,
+	'RUBY_T_COMPLEX': 0x0e,
+	'RUBY_T_RATIONAL': 0x0f,
+	'RUBY_T_NIL': 0x11,
+	'RUBY_T_TRUE': 0x12,
+	'RUBY_T_FALSE': 0x13,
+	'RUBY_T_SYMBOL': 0x14,
+	'RUBY_T_FIXNUM': 0x15,
+	'RUBY_T_UNDEF': 0x16,
+	'RUBY_T_IMEMO': 0x1a,
+	'RUBY_T_NODE': 0x1b,
+	'RUBY_T_ICLASS': 0x1c,
+	'RUBY_T_ZOMBIE': 0x1d,
+	'RUBY_T_MOVED': 0x1e,
+	'RUBY_T_MASK': 0x1f,
+}
+
+# Default values for Ruby flag constants (ruby_fl_type enum)
+_FLAG_DEFAULTS = {
+	'RUBY_FL_USHIFT': 12,
+	'RUBY_FL_USER1': 1 << 13,
+	'RUBY_FL_USER2': 1 << 14,
+	'RUBY_FL_USER3': 1 << 15,
+	'RUBY_FL_USER4': 1 << 16,
+	'RUBY_FL_USER5': 1 << 17,
+	'RUBY_FL_USER6': 1 << 18,
+	'RUBY_FL_USER7': 1 << 19,
+	'RUBY_FL_USER8': 1 << 20,
+	'RUBY_FL_USER9': 1 << 21,
+}
+
+def get(name, default=None):
+	"""Get a Ruby constant value, with caching.
+	
+	Arguments:
+		name: The constant name (e.g., 'RUBY_T_STRING', 'RUBY_FL_USER1')
+		default: Default value if constant cannot be found
+	
+	Returns:
+		The integer value of the constant, or default if not found
+	
+	Raises:
+		Exception if constant not found and no default provided
+	"""
+	if name in _CACHE:
+		return _CACHE[name]
+	
+	# Try direct evaluation (works in GDB with debug info, LLDB with macros/variables)
+	try:
+		val = int(debugger.parse_and_eval(name))
+		# Only cache if we got a non-zero value or if it's a known zero constant
+		if val != 0 or name in ['Qfalse', 'RUBY_Qfalse', 'RUBY_T_NONE']:
+			_CACHE[name] = val
+		return val
+	except Exception:
+		pass
+	
+	# Couldn't find the constant
+	if default is None:
+		raise Exception(f"Constant {name} not found and no default provided")
+	
+	# Return default but don't cache (might be available later with a process)
+	return default
+
+def get_enum(enum_name, member_name, default=None):
+	"""Get an enum member value from a specific enum.
+	
+	This is more explicit than get() and works better in LLDB.
+	
+	Arguments:
+		enum_name: The enum type name (e.g., 'ruby_value_type')
+		member_name: The member name (e.g., 'RUBY_T_STRING')
+		default: Default value if enum member cannot be found
+	
+	Returns:
+		The integer value of the enum member, or default if not found
+	
+	Raises:
+		Exception if member not found and no default provided
+	
+	Examples:
+		>>> constants.get_enum('ruby_value_type', 'RUBY_T_STRING', 0x05)
+		5
+	"""
+	cache_key = f"{enum_name}::{member_name}"
+	
+	if cache_key in _CACHE:
+		return _CACHE[cache_key]
+	
+	# Use the debugger abstraction (handles GDB vs LLDB differences)
+	try:
+		val = debugger.get_enum_value(enum_name, member_name)
+		_CACHE[cache_key] = val
+		return val
+	except Exception:
+		pass
+	
+	# Couldn't find the enum member
+	if default is None:
+		raise Exception(f"Enum member {enum_name}::{member_name} not found and no default provided")
+	
+	return default
+
+def type_struct(type_name):
+	"""Get a C struct/type from the debugger, with caching.
+	
+	Arguments:
+		type_name: The type name (e.g., 'struct RString', 'struct RArray', 'VALUE')
+	
+	Returns:
+		The debugger type object
+	
+	Raises:
+		Exception if type cannot be found
+	
+	Examples:
+		>>> rbasic_type = constants.type_struct('struct RBasic')
+		>>> value_type = constants.type_struct('VALUE')
+	"""
+	if type_name in _TYPE_CACHE:
+		return _TYPE_CACHE[type_name]
+	
+	dbg_type = debugger.lookup_type(type_name)
+	_TYPE_CACHE[type_name] = dbg_type
+	return dbg_type
+
+def type(name):
+	"""Get a Ruby type constant (RUBY_T_*) value.
+	
+	This is a convenience wrapper around get_enum() for ruby_value_type enum.
+	Uses built-in defaults for all standard Ruby type constants.
+	
+	Arguments:
+		name: The type constant name (e.g., 'RUBY_T_STRING', 'RUBY_T_ARRAY')
+	
+	Returns:
+		The integer value of the type constant
+	
+	Raises:
+		Exception if constant is not found and not in default table
+	
+	Examples:
+		>>> constants.type('RUBY_T_STRING')
+		5
+	"""
+	default = _TYPE_DEFAULTS.get(name)
+	return get_enum('ruby_value_type', name, default)
+
+def flag(name):
+	"""Get a Ruby flag constant (RUBY_FL_*) value.
+	
+	This is a convenience wrapper around get_enum() for ruby_fl_type enum.
+	Uses built-in defaults for all standard Ruby flag constants.
+	
+	Arguments:
+		name: The flag constant name (e.g., 'RUBY_FL_USER1', 'RUBY_FL_USHIFT')
+	
+	Returns:
+		The integer value of the flag constant
+	
+	Raises:
+		Exception if constant is not found and not in default table
+	
+	Examples:
+		>>> constants.flag('RUBY_FL_USER1')
+		8192
+	"""
+	default = _FLAG_DEFAULTS.get(name)
+	return get_enum('ruby_fl_type', name, default)
+
+def clear():
+	"""Clear the constants and type caches.
+	
+	Useful when switching between different Ruby processes or versions.
+	"""
+	_CACHE.clear()
+	_TYPE_CACHE.clear()

data/data/toolbox/context.py

@@ -0,0 +1,295 @@
+"""Ruby execution context utilities and commands."""
+
+import debugger
+import format
+import value
+import rexception
+
+
+class RubyContext:
+    """Wrapper for Ruby execution context (rb_execution_context_t).
+    
+    Provides a high-level interface for working with Ruby execution contexts,
+    including inspection, convenience variable setup, and information display.
+    
+    Example:
+        ctx = RubyContext.current()
+        if ctx:
+            ctx.print_info(terminal)
+            ctx.setup_convenience_variables()
+    """
+    
+    def __init__(self, ec):
+        """Create a RubyContext wrapper.
+        
+        Args:
+            ec: Execution context pointer (rb_execution_context_t *)
+        """
+        self.ec = ec
+        self._cfp = None
+        self._errinfo = None
+        self._vm_stack = None
+        self._vm_stack_size = None
+    
+    @classmethod
+    def current(cls):
+        """Get the current execution context from the running thread.
+        
+        Tries multiple approaches in order of preference:
+        1. ruby_current_ec - TLS variable (works in GDB, some LLDB)
+        2. rb_current_ec_noinline() - function call (works in most cases)
+        3. rb_current_ec() - macOS-specific function
+        
+        Returns:
+            RubyContext instance, or None if not available
+        """
+        # Try ruby_current_ec variable first
+        try:
+            ec = debugger.parse_and_eval('ruby_current_ec')
+            if ec is not None and int(ec) != 0:
+                return cls(ec)
+        except debugger.Error:
+            pass
+        
+        # Fallback to rb_current_ec_noinline() function
+        try:
+            ec = debugger.parse_and_eval('rb_current_ec_noinline()')
+            if ec is not None and int(ec) != 0:
+                return cls(ec)
+        except debugger.Error:
+            pass
+        
+        # Last resort: rb_current_ec() (macOS-specific)
+        try:
+            ec = debugger.parse_and_eval('rb_current_ec()')
+            if ec is not None and int(ec) != 0:
+                return cls(ec)
+        except debugger.Error:
+            pass
+        
+        return None
+    
+    @property
+    def cfp(self):
+        """Get control frame pointer (lazy load)."""
+        if self._cfp is None:
+            try:
+                self._cfp = self.ec['cfp']
+            except Exception:
+                pass
+        return self._cfp
+    
+    @property
+    def errinfo(self):
+        """Get exception VALUE (lazy load)."""
+        if self._errinfo is None:
+            try:
+                self._errinfo = self.ec['errinfo']
+            except Exception:
+                pass
+        return self._errinfo
+    
+    @property
+    def has_exception(self):
+        """Check if there's a real exception (not nil/special value)."""
+        if self.errinfo is None:
+            return False
+        return rexception.is_exception(self.errinfo)
+    
+    @property
+    def vm_stack(self):
+        """Get VM stack pointer (lazy load)."""
+        if self._vm_stack is None:
+            try:
+                self._vm_stack = self.ec['vm_stack']
+            except Exception:
+                pass
+        return self._vm_stack
+    
+    @property
+    def vm_stack_size(self):
+        """Get VM stack size (lazy load)."""
+        if self._vm_stack_size is None:
+            try:
+                self._vm_stack_size = int(self.ec['vm_stack_size'])
+            except Exception:
+                pass
+        return self._vm_stack_size
+    
+    def setup_convenience_variables(self):
+        """Set up convenience variables for this execution context.
+        
+        Sets:
+            $ec       - Execution context pointer
+            $cfp      - Control frame pointer
+            $errinfo  - Current exception (if any)
+        
+        Returns:
+            dict with keys: 'ec', 'cfp', 'errinfo' (values are the set variables)
+        """
+        result = {}
+        
+        # Set $ec
+        debugger.set_convenience_variable('ec', self.ec)
+        result['ec'] = self.ec
+        
+        # Set $cfp (control frame pointer)
+        if self.cfp is not None:
+            debugger.set_convenience_variable('cfp', self.cfp)
+            result['cfp'] = self.cfp
+        else:
+            result['cfp'] = None
+        
+        # Set $errinfo if there's an exception
+        if self.has_exception:
+            debugger.set_convenience_variable('errinfo', self.errinfo)
+            result['errinfo'] = self.errinfo
+        else:
+            result['errinfo'] = None
+        
+        return result
+    
+    def print_info(self, terminal):
+        """Print detailed information about this execution context.
+        
+        Args:
+            terminal: Terminal formatter for output
+        """
+        print("Execution Context:")
+        print(f"  $ec = ", end='')
+        print(terminal.print_type_tag('rb_execution_context_t', int(self.ec), None))
+        
+        # VM Stack info
+        if self.vm_stack is not None and self.vm_stack_size is not None:
+            print(f"  VM Stack: ", end='')
+            print(terminal.print_type_tag('VALUE', int(self.vm_stack), f'size={self.vm_stack_size}'))
+        else:
+            print(f"  VM Stack: <unavailable>")
+        
+        # Control Frame info
+        if self.cfp is not None:
+            print(f"  $cfp = ", end='')
+            print(terminal.print_type_tag('rb_control_frame_t', int(self.cfp), None))
+        else:
+            print(f"  $cfp = <unavailable>")
+        
+        # Exception info
+        if self.has_exception:
+            print(f"  $errinfo = ", end='')
+            print(terminal.print_type_tag('VALUE', int(self.errinfo), None))
+            print("    Exception present!")
+        else:
+            errinfo_int = int(self.errinfo) if self.errinfo else 0
+            if errinfo_int == 4:  # Qnil
+                print("  Exception: None")
+            elif errinfo_int == 0:  # Qfalse
+                print("  Exception: None (false)")
+            else:
+                print(f"  Exception: None")
+        
+        # Tag info (for ensure blocks)
+        try:
+            tag = self.ec['tag']
+            tag_int = int(tag)
+            if tag_int != 0:
+                print(f"  Tag: ", end='')
+                print(terminal.print_type_tag('rb_vm_tag', tag_int, None))
+                try:
+                    retval = tag['retval']
+                    retval_int = int(retval)
+                    is_retval_special = (retval_int & 0x03) != 0 or retval_int == 0
+                    if not is_retval_special:
+                        print(f"    $retval available (in ensure block)")
+                except Exception:
+                    pass
+        except Exception:
+            pass
+
+
+class RubyContextCommand(debugger.Command):
+    """Show current execution context and set convenience variables.
+    
+    This command automatically discovers the current thread's execution context
+    and displays detailed information about it, while also setting up convenience
+    variables for easy inspection.
+    
+    Usage:
+        rb-context
+    
+    Displays:
+        - Execution context pointer and details
+        - VM stack information
+        - Control frame pointer
+        - Exception information (if any)
+    
+    Sets these convenience variables:
+        $ec       - Current execution context (rb_execution_context_t *)
+        $cfp      - Current control frame pointer
+        $errinfo  - Current exception (if any)
+    
+    Example:
+        (gdb) rb-context
+        Execution Context:
+          $ec = <rb_execution_context_t *@0x...>
+          VM Stack: <VALUE *@0x...> size=1024
+          $cfp = <rb_control_frame_t *@0x...>
+          Exception: None
+        
+        (gdb) rb-object-print $errinfo
+        (gdb) rb-object-print $ec->cfp->sp[-1]
+    """
+    
+    def __init__(self):
+        super(RubyContextCommand, self).__init__("rb-context", debugger.COMMAND_USER)
+    
+    def invoke(self, arg, from_tty):
+        """Execute the rb-context command."""
+        try:
+            terminal = format.create_terminal(from_tty)
+            
+            # Get current execution context
+            ctx = RubyContext.current()
+            
+            if ctx is None:
+                print("Error: Could not get current execution context")
+                print()
+                print("Possible reasons:")
+                print("  • Ruby symbols not loaded (compile with debug symbols)")
+                print("  • Process not stopped at a Ruby frame")
+                print("  • Ruby not fully initialized yet")
+                print()
+                print("Try:")
+                print("  • Break at a Ruby function: break rb_vm_exec")
+                print("  • Use rb-fiber-scan-switch to switch to a fiber")
+                print("  • Ensure Ruby debug symbols are available")
+                return
+            
+            # Print context information
+            ctx.print_info(terminal)
+            
+            # Set convenience variables
+            vars = ctx.setup_convenience_variables()
+            
+            print()
+            print("Convenience variables set:")
+            print(f"  $ec      - Execution context")
+            if vars.get('cfp'):
+                print(f"  $cfp     - Control frame pointer")
+            if vars.get('errinfo'):
+                print(f"  $errinfo - Exception object")
+            
+            print()
+            print("Now you can use:")
+            print("  rb-object-print $errinfo")
+            print("  rb-object-print $ec->cfp->sp[-1]")
+            print("  rb-stack-trace")
+            
+        except Exception as e:
+            print(f"Error: {e}")
+            import traceback
+            traceback.print_exc()
+
+
+# Register command
+RubyContextCommand()
+

data/data/toolbox/debugger/__init__.py

@@ -0,0 +1,99 @@
+"""
+Unified debugger abstraction layer for GDB and LLDB.
+
+This module provides a common interface for debugger operations,
+automatically loading the appropriate backend (GDB or LLDB) at runtime.
+"""
+
+import sys
+import os
+
+# Detect which debugger we're running under
+_backend = None
+DEBUGGER_NAME = None
+
+# Add parent directory to path so we can import debugger.gdb / debugger.lldb
+_toolbox_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if _toolbox_dir not in sys.path:
+	sys.path.insert(0, _toolbox_dir)
+
+# Try importing the real GDB or LLDB modules first
+# We need to verify they're the actual debugger modules, not namespace packages
+_gdb_available = False
+_lldb_available = False
+
+try:
+	import gdb as _gdb_module
+	# Verify it's the real GDB module by checking for a key attribute
+	if hasattr(_gdb_module, 'COMMAND_DATA'):
+		_gdb_available = True
+except ImportError:
+	pass
+
+try:
+	import lldb as _lldb_module
+	# Verify it's the real LLDB module by checking for a key class
+	if hasattr(_lldb_module, 'SBDebugger'):
+		_lldb_available = True
+except ImportError:
+	pass
+
+# Now load the appropriate backend based on which module is available
+if _gdb_available:
+	from debugger import gdb_backend as _backend
+	DEBUGGER_NAME = 'gdb'
+elif _lldb_available:
+	from debugger import lldb_backend as _backend
+	DEBUGGER_NAME = 'lldb'
+else:
+	raise RuntimeError("Must be run under GDB or LLDB - neither module found")
+
+if _backend is None:
+	raise RuntimeError("Failed to load debugger backend")
+
+# Export the backend's interface
+Value = _backend.Value
+Type = _backend.Type
+Command = _backend.Command
+Error = _backend.Error
+MemoryError = _backend.MemoryError
+
+parse_and_eval = _backend.parse_and_eval
+lookup_type = _backend.lookup_type
+set_convenience_variable = _backend.set_convenience_variable
+execute = _backend.execute
+lookup_symbol = _backend.lookup_symbol
+invalidate_cached_frames = _backend.invalidate_cached_frames
+get_enum_value = _backend.get_enum_value
+read_memory = _backend.read_memory
+read_cstring = _backend.read_cstring
+create_value = _backend.create_value
+create_value_from_int = _backend.create_value_from_int
+create_value_from_address = _backend.create_value_from_address
+
+# Constants
+COMMAND_DATA = _backend.COMMAND_DATA
+COMMAND_USER = _backend.COMMAND_USER
+
+__all__ = [
+	'DEBUGGER_NAME',
+	'Value',
+	'Type',
+	'Command',
+	'Error',
+	'MemoryError',
+	'parse_and_eval',
+	'lookup_type',
+	'set_convenience_variable',
+	'execute',
+	'lookup_symbol',
+	'invalidate_cached_frames',
+	'get_enum_value',
+	'read_memory',
+	'read_cstring',
+	'create_value',
+	'create_value_from_int',
+	'create_value_from_address',
+	'COMMAND_DATA',
+	'COMMAND_USER',
+]