hilda 3.0.0__py3-none-any.whl → 3.1.0__py3-none-any.whl

hilda/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '3.0.0'
-__version_tuple__ = version_tuple = (3, 0, 0)
+__version__ = version = '3.1.0'
+__version_tuple__ = version_tuple = (3, 1, 0)

hilda/breakpoints.py

@@ -124,12 +124,30 @@ class HildaBreakpoint:
         for name in names_to_add:
             self.lldb_breakpoint.AddName(name)
 
+    @property
+    def enabled(self) -> bool:
+        """
+        Configures whether this breakpoint is enabled or not.
+        """
+        return self.lldb_breakpoint.IsEnabled()
+
+    @enabled.setter
+    def enabled(self, value: bool) -> None:
+        self.lldb_breakpoint.SetEnabled(value)
+
     def __repr__(self) -> str:
-        return (f'<{self.__class__.__name__} LLDB:{self.lldb_breakpoint} GUARDED:{self.guarded} '
+        enabled_repr = 'ENABLED' if self.enabled else 'DISABLED'
+        guarded_repr = 'GUARDED' if self.guarded else 'NOT-GUARDED'
+        return (f'<{self.__class__.__name__} LLDB:{self.lldb_breakpoint} {enabled_repr} {guarded_repr} '
                 f'CALLBACK:{self.callback}>')
 
     def __str__(self) -> str:
-        result = f'🚨 Breakpoint #{self.id} (guarded: {self.guarded}):\n'
+        emoji = '🚨' if self.enabled else '🔕'
+        enabled_str = 'enabled' if self.enabled else 'disabled'
+        guarded_str = 'guarded' if self.guarded else 'not-guarded'
+
+        result = f'{emoji} Breakpoint #{self.id} ({enabled_str}, {guarded_str})\n'
+
         if self.description is not None:
             result += f'\tDescription: {self.description}\n'
 
@@ -137,10 +155,13 @@ class HildaBreakpoint:
             result += f'\tWhere: {self.where}\n'
 
         # A single breakpoint may be related to several locations (addresses)
+        locations = self.locations
+        if len(locations) == 0:
+            result += f'\tNo locations\n'
         for location in self.locations:
             result += f'\tLocation {location}\n'
 
-        return result
+        return result.strip('\n')
 
     def remove(self, remove_guarded: bool = False) -> None:
         """
@@ -441,8 +462,10 @@ class BreakpointList:
 
     def show(self) -> None:
         """ Show existing breakpoints. """
+        if len(self) == 0:
+            self._hilda.log_info('No breakpoints')
         for bp in self:
-            print(bp)
+            self._hilda.log_info(bp)
 
     def items(self):
         """

hilda/decorators.py

@@ -0,0 +1,45 @@
+from hilda.breakpoints import WhereType
+from hilda.lldb_importer import lldb
+p = lldb.hilda_client
+
+
+def breakpoint(where: WhereType, enable: bool = False):
+    """
+    A decorator to define a breakpoint, e.g.,
+
+    ```
+    @breakpoint('symbol_name')
+    def my_breakpoint(hilda, *args):
+        print('Hit!')
+        hilda.cont()
+
+    my_breakpoint.enabled = True
+    ```
+    """
+    def decorator(callback):
+        bp = p.breakpoints.add(where, callback=callback)
+        bp.enabled = enable
+        return bp
+
+    return decorator
+
+
+def watchpoint(where: int, enable: bool = False):
+    """
+    A decorator to define a watchpoint, e.g.,
+
+    ```
+    @watchpoint(0x11223344)
+    def my_watchpoint(hilda, *args):
+        print('Hit!')
+        hilda.cont()
+
+    my_watchpoint.enabled = True
+    ```
+    """
+    def decorator(callback):
+        wp = p.watchpoints.add(where, callback=callback)
+        wp.enabled = enable
+        return wp
+
+    return decorator

hilda/hilda_client.py

@@ -42,6 +42,7 @@ from hilda.snippets.mach import CFRunLoopServiceMachPort_hooks
 from hilda.symbol import Symbol
 from hilda.symbols_jar import SymbolsJar
 from hilda.ui.ui_manager import UiManager
+from hilda.watchpoints import WatchpointList
 
 lldb.KEYSTONE_SUPPORT = True
 try:
@@ -128,6 +129,7 @@ class HildaClient:
         self.process = self.target.GetProcess()
         self.symbols = SymbolsJar.create(self)
         self.breakpoints = BreakpointList(self)
+        self.watchpoints = WatchpointList(self)
         self.captured_objects = {}
         self.registers = Registers(self)
         self.arch = self.target.GetTriple().split('-')[0]

hilda/launch_lldb.py

@@ -61,6 +61,33 @@ class LLDBListenerThread(Thread, ABC):
                 sys.stderr.write(stderr)
             stderr = self.process.GetSTDERR(1024)
 
+    def _process_potential_watchpoint_event(self) -> None:
+        stopped_threads = self._get_stopped_threads(lldb.eStopReasonWatchpoint)
+        for thread in stopped_threads:
+            watchpoint_id = thread.GetStopReasonDataAtIndex(0)
+            frame = thread.GetFrameAtIndex(0)
+            if lldb.hilda_client is not None:
+                lldb.hilda_client.watchpoints._dispatch_watchpoint_callback(watchpoint_id, thread, frame)
+
+    def _get_stopped_threads(self, reason: Optional[int] = None) -> list[lldb.SBThread]:
+        if reason is None:
+            stop_reasons = [
+                lldb.eStopReasonSignal, lldb.eStopReasonException,
+                lldb.eStopReasonBreakpoint, lldb.eStopReasonWatchpoint,
+                lldb.eStopReasonPlanComplete, lldb.eStopReasonTrace,
+            ]
+        else:
+            stop_reasons = [reason]
+
+        return [thread for thread in self.process if thread.GetStopReason() in stop_reasons]
+
+    def _set_selected_thread_to_stopped_thread(self) -> None:
+        stopped_threads = self._get_stopped_threads()
+        if len(stopped_threads) < 1:
+            return
+        thread = stopped_threads[0]
+        self.process.SetSelectedThread(thread)
+
     def run(self):
         event = lldb.SBEvent()
         last_state = lldb.eStateStopped
@@ -87,18 +114,8 @@ class LLDBListenerThread(Thread, ABC):
                 logger.debug('Process Continued')
             elif state == lldb.eStateStopped and last_state == lldb.eStateRunning:
                 logger.debug('Process Stopped')
-                for thread in self.process:
-                    frame = thread.GetFrameAtIndex(0)
-                    stop_reason = thread.GetStopReason()
-                    logger.debug(f'tid = {hex(thread.GetThreadID())} pc = {frame.GetPC()}')
-                    if stop_reason not in [lldb.eStopReasonSignal, lldb.eStopReasonException,
-                                           lldb.eStopReasonBreakpoint,
-                                           lldb.eStopReasonWatchpoint, lldb.eStopReasonPlanComplete,
-                                           lldb.eStopReasonTrace,
-                                           lldb.eStopReasonSignal]:
-                        continue
-                    self.process.SetSelectedThread(thread)
-                    break
+                self._set_selected_thread_to_stopped_thread()
+                self._process_potential_watchpoint_event()
 
             last_state = state
 

hilda/symbol.py

@@ -145,6 +145,9 @@ class Symbol(int):
     def monitor(self, **args):
         return self._client.monitor(self, **args)
 
+    def watch(self, **args):
+        return self._client.watchpoints.add(self, **args)
+
     def bp(self, callback=None, **args):
         return self._client.bp(self, callback, **args)
 

hilda/watchpoints.py

@@ -0,0 +1,269 @@
+from typing import Callable, Generator, Optional, Union
+
+from hilda.lldb_importer import lldb
+
+
+class HildaWatchpoint:
+    """
+    Hilda's class representing an LLDB watchpoint, with some optional additional properties
+    """
+
+    def __init__(self, hilda, lldb_watchpoint: lldb.SBWatchpoint, where: Optional[int] = None) -> None:
+        """
+        Initialize a watchpoint list.
+
+        :param hilda.hilda_client.HildaClient hilda: Hilda client
+        """
+        self._hilda = hilda
+        self._where = where
+        self._callback = None
+
+        # Actual watchpoint from LLDB API
+        self.lldb_watchpoint = lldb_watchpoint
+
+    @property
+    def where(self) -> Optional[int]:
+        """
+        A value identifying where the watchpoint was set (when it was created).
+
+        It could be either an address (int) or a Hilda symbol object (Symbol, that inherits from int).
+        Note that self.address is similar, but self.where is where the watchpoit was set when it was
+        created (using Hilda API), and self.address is the actual address. They should have the same
+        value, although self.where may be a Hilda Symbol.
+        """
+        return self._where
+
+    @property
+    def id(self) -> int:
+        """ A number identifying the watchpoint. """
+        return self.lldb_watchpoint.GetID()
+
+    @property
+    def callback(self) -> Optional[Callable]:
+        """
+        A callback that will be executed when the watchpoint is hit.
+
+        Note that unless the callback explicitly continues (by calling `cont()`), the program will not continue.
+        The callback will be invoked as callback(hilda, *args), where hilda is the 'HildaClient'.
+        """
+        return self._callback
+
+    @callback.setter
+    def callback(self, callback: Optional[Callable]) -> None:
+        self._callback = callback
+
+    @property
+    def condition(self) -> Optional[str]:
+        """
+        An LLDB expression to make this a conditional watchpoint.
+        """
+        return self.lldb_watchpoint.GetCondition()
+
+    @condition.setter
+    def condition(self, condition: Optional[str]) -> None:
+        self.lldb_watchpoint.SetCondition(condition)
+
+    @property
+    def address(self) -> int:
+        """
+        Get the address this wathpoint watches (also see self.where).
+        """
+        return self.lldb_watchpoint.GetWatchAddress()
+
+    @property
+    def size(self) -> int:
+        """
+        Get the size this wathpoint watches.
+        """
+        return self.lldb_watchpoint.GetWatchSize()
+
+    @property
+    def enabled(self) -> bool:
+        """
+        Configures whether this watchpoint is enabled or not.
+        """
+        return self.lldb_watchpoint.IsEnabled()
+
+    @enabled.setter
+    def enabled(self, value: bool) -> None:
+        self.lldb_watchpoint.SetEnabled(value)
+
+    def __repr__(self) -> str:
+        return f'<{self.__class__.__name__} LLDB:{self.lldb_watchpoint} CALLBACK:{self.callback}>'
+
+    def __str__(self) -> str:
+        emoji = '🚨' if self.enabled else '🔕'
+        enabled_str = 'enabled' if self.enabled else 'disabled'
+        result = f'{emoji} Watchpoint #{self.id} ({enabled_str})\n'
+
+        if self.where is not None:
+            result += f'\tWhere: {self.where}\n'
+
+        return result.strip('\n')
+
+    def remove(self) -> None:
+        """
+        Remove the watchpoint.
+        """
+        self._hilda.watchpoints.remove(self)
+
+
+class WatchpointList:
+    """
+    Manager for `HildaWatchpoint` objects, each one wrapping another native LLDB watchpoint.
+    """
+
+    def __init__(self, hilda) -> None:
+        """
+        Initialize a watchpoint list.
+
+        :param hilda.hilda_client.HildaClient hilda: Hilda client
+        """
+        self._hilda = hilda
+        self._watchpoints = {}
+
+    def __contains__(self, id_or_wp: Union[int, HildaWatchpoint]) -> bool:
+        return self.get(id_or_wp) is not None
+
+    def __iter__(self) -> Generator[HildaWatchpoint, None, None]:
+        for wp in self._hilda.target.watchpoint_iter():
+            yield self[wp.GetID()]
+
+    def __len__(self) -> int:
+        return self._hilda.target.GetNumWatchpoints()
+
+    def __getitem__(self, id_or_wp: Union[int, HildaWatchpoint]) -> HildaWatchpoint:
+        """
+        Get a watchpoint by ID (or the watchpoint itself, though it usually makes little sense)
+
+        :param id_or_wp: Watchpoint's ID (or the watchpoint itself)
+        """
+        wp = self.get(id_or_wp)
+        if wp is None:
+            raise KeyError(id_or_wp)
+
+        return wp
+
+    def __delitem__(self, id_or_wp: Union[int, HildaWatchpoint]):
+        """
+        Remove a watchpoint.
+
+        :param id_or_wp: Watchpoint's ID (or the watchpoint itself)
+        """
+        self.remove(id_or_wp)
+
+    def __repr__(self) -> str:
+        return repr(dict(self.items()))
+
+    def __str__(self) -> str:
+        return repr(self)
+
+    def get(self, id_or_wp: Union[int, HildaWatchpoint]) -> Optional[HildaWatchpoint]:
+        """
+        Get a watchpoint by ID or the watchpoint itself.
+
+        :param id_or_wp: Watchpoint's ID (or the watchpoint itself)
+        :return: `HildaWatchpoint` is one exists, or `None` otherwise
+        """
+
+        if isinstance(id_or_wp, int):
+            wp = self._hilda.target.FindWatchpointByID(id_or_wp)
+        elif isinstance(id_or_wp, HildaWatchpoint):
+            wp = id_or_wp.lldb_watchpoint
+        else:
+            raise KeyError(f'Watchpoint "{id_or_wp}" could not be found')
+
+        if not wp.IsValid():
+            return None
+
+        wp_id = wp.GetID()
+        if wp_id not in self._watchpoints:
+            self._hilda.log_debug(f'Found a watchpoint added outside of the Hilda API {wp}')
+            self._watchpoints[wp_id] = HildaWatchpoint(self._hilda, wp)
+
+        return self._watchpoints[wp_id]
+
+    def add(self, where: int, size: int = 8, read: bool = True, write: bool = True,
+            callback: Optional[Callable] = None, condition: str = None) -> HildaWatchpoint:
+        """
+        Add a watchpoint.
+
+        :param where: The address of the watchpoint.
+        :param size: The size of the watchpoint (the address span to watch).
+        :param read: The watchpoint should monitor reads from memory in the specified address (and size).
+        :param write: The watchpoint should monitor writes to memory in the specified address (and size).
+        :param callback: A callback that will be executed when the watchpoint is hit.
+            Note that unless the callback explicitly continues (by calling cont()), the program will not continue.
+            The callback will be invoked as callback(hilda, *args), where hilda is the 'HildaClient'.
+        :param condition: An LLDB expression to make this a conditional watchpoint.
+        :return: The new watchpoint
+        """
+
+        error = lldb.SBError()
+        wp = self._hilda.target.WatchAddress(where, size, read, write, error)
+        if not wp.IsValid():
+            raise Exception(f'Failed to create watchpoint at {where} ({error})')
+
+        wp = HildaWatchpoint(self._hilda, wp, where)
+        wp.callback = callback
+        wp.condition = condition
+
+        self._watchpoints[wp.id] = wp
+
+        self._hilda.log_info(f'Watchpoint #{wp.id} has been set')
+        return wp
+
+    def remove(self, id_or_wp: Union[int, HildaWatchpoint]) -> None:
+        """
+        Remove a watchpoint.
+
+        :param id_or_wp: Watchpoint's ID (or the watchpoint itself)
+        """
+        wp = self[id_or_wp]
+        watchpoint_id = wp.id
+        self._hilda.target.DeleteWatchpoint(watchpoint_id)
+        self._hilda.log_debug(f'Watchpoint #{watchpoint_id} has been removed')
+
+    def clear(self) -> None:
+        """
+        Remove all watchpoints
+        """
+        for wp in list(self):
+            self.remove(wp)
+
+    def show(self) -> None:
+        """ Show existing watchpoints. """
+        if len(self) == 0:
+            self._hilda.log_info('No watchpoints')
+        for wp in self:
+            self._hilda.log_info(wp)
+
+    def items(self) -> Generator[tuple[int, HildaWatchpoint], None, None]:
+        """
+        Get a watchpoint ID and watchpoint object tuple for every watchpoint.
+        """
+        return ((wp.id, wp) for wp in self)
+
+    def keys(self) -> Generator[int, None, None]:
+        """
+        Get the watchpoint ID for every watchpoint.
+        """
+        return (wp.id for wp in self)
+
+    def values(self) -> Generator[HildaWatchpoint, None, None]:
+        """
+        Get the watchpoint object for every watchpoint.
+        """
+        return (wp for wp in self)
+
+    def _dispatch_watchpoint_callback(self, watchpoint_id: int, _, frame) -> None:
+        """
+        Route the watchpoint callback the specific watchpoint callback.
+        """
+        self._hilda._bp_frame = frame
+        try:
+            callback = self[watchpoint_id].callback
+            if callback is not None:
+                callback(self._hilda, frame, None, self[watchpoint_id])
+        finally:
+            self._hilda._bp_frame = None