hilda 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

hilda/hilda_client.py

@@ -9,12 +9,13 @@ import os
 import pickle
 import textwrap
 import time
+import typing
 from collections import namedtuple
 from contextlib import contextmanager, suppress
 from datetime import datetime, timezone
 from functools import cached_property, partial
 from pathlib import Path
-from typing import Union
+from typing import List, Optional, Union
 
 import docstring_parser
 import hexdump
@@ -40,6 +41,7 @@ from hilda.registers import Registers
 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
 
 IsaMagic = namedtuple('IsaMagic', 'mask value')
 ISA_MAGICS = [
@@ -81,6 +83,7 @@ class HildaClient(metaclass=CommandsMeta):
         self.captured_objects = {}
         self.registers = Registers(self)
         self.arch = self.target.GetTriple().split('-')[0]
+        self.ui_manager = UiManager(self)
         # should unwind the stack on errors. change this to False in order to debug self-made calls
         # within hilda
         self._evaluation_unwind_on_error = True
@@ -120,16 +123,22 @@ class HildaClient(metaclass=CommandsMeta):
         return {int(k): v for k, v in result.items()}
 
     @command()
-    def bt(self):
+    def bt(self, should_print=True, depth: Optional[int] = None) -> List:
         """ Print an improved backtrace. """
+        backtrace = []
         for i, frame in enumerate(self.thread.frames):
+            if i == depth:
+                break
             row = ''
             row += html_to_ansi(f'<span style="color: cyan">0x{frame.addr.GetFileAddress():x}</span> ')
             row += str(frame)
             if i == 0:
                 # first line
                 row += ' 👈'
-            print(row)
+            backtrace.append([f'0x{frame.addr.file_addr:016x}', frame])
+            if should_print:
+                print(row)
+        return backtrace
 
     @command()
     def disable_jetsam_memory_checks(self):
@@ -514,12 +523,16 @@ class HildaClient(metaclass=CommandsMeta):
         """ Step into current instruction. """
         with self.sync_mode():
             self.thread.StepInto()
+        if self.ui_manager.active:
+            self.ui_manager.show()
 
     @command()
     def step_over(self):
         """ Step over current instruction. """
         with self.sync_mode():
             self.thread.StepOver()
+        if self.ui_manager.active:
+            self.ui_manager.show()
 
     @command()
     def remove_all_hilda_breakpoints(self, remove_forced=False):
@@ -1008,7 +1021,7 @@ class HildaClient(metaclass=CommandsMeta):
 
         return value
 
-    def interactive(self):
+    def interactive(self, additional_namespace: typing.Mapping = None):
         """ Start an interactive Hilda shell """
         if not self._dynamic_env_loaded:
             self.init_dynamic_environment()
@@ -1024,6 +1037,8 @@ class HildaClient(metaclass=CommandsMeta):
         ]
         namespace = globals()
         namespace.update(locals())
+        if additional_namespace is not None:
+            namespace.update(additional_namespace)
 
         IPython.start_ipython(config=c, user_ns=namespace)
 

hilda/lldb_entrypoint.py

@@ -15,7 +15,9 @@ lldb.hilda_client = None
 def hilda(debugger, command, result, internal_dict):
     if lldb.hilda_client is None:
         lldb.hilda_client = HildaClient(debugger)
-    lldb.hilda_client.interactive()
+
+    additional_namespace = {'ui': lldb.hilda_client.ui_manager}
+    lldb.hilda_client.interactive(additional_namespace=additional_namespace)
 
 
 def __lldb_init_module(debugger, internal_dict):

hilda/snippets/xpc.py

@@ -54,6 +54,15 @@ def from_xpc_object(address: int):
     return lldb.hilda_client.from_ns(f'_CFXPCCreateCFObjectFromXPCObject({address})')
 
 
+def disable_transaction_exit():
+    """
+    xpc_transaction_exit_clean will kill the process when transaction is done.
+    By patching this function the process will stay alive.
+    """
+    hilda = lldb.hilda_client
+    hilda.symbols.xpc_transaction_exit_clean.poke_text('ret')
+
+
 def to_xpc_object(obj: object):
     """
     Convert python object to XPC object.

hilda/ui/colors.json

@@ -0,0 +1,13 @@
+{
+  "title": "green",
+  "address": "bright_blue",
+  "regs_title": "green",
+  "regs_name": "cyan",
+  "regs_value": "white",
+  "mnemonic": "white",
+  "operands": "white",
+  "basename": "yellow",
+  "stack_offset": "white",
+  "stack_data": "white",
+  "diff": "red"
+}

hilda/ui/ui_manager.py

@@ -0,0 +1,74 @@
+import json
+from collections import OrderedDict
+from pathlib import Path
+
+from hilda.ui.views import BackTraceView, DisassemblyView, RegistersView, StackView
+
+
+class DotDict(OrderedDict):
+    """ Extends `OrderedDict` to access items using dot """
+    __slots__ = ["__recursion_lock__"]
+
+    def __getattr__(self, name):
+        try:
+            if name in self.__slots__:
+                return object.__getattribute__(self, name)
+            else:
+                return self[name]
+        except KeyError:
+            raise AttributeError(name)
+
+    def __setattr__(self, name, value):
+        try:
+            if name in self.__slots__:
+                return object.__setattr__(self, name, value)
+            else:
+                self[name] = value
+        except KeyError:
+            raise AttributeError(name)
+
+
+class ColorScheme(DotDict):
+    def __init__(self, scheme: Path):
+        with scheme.open('r') as f:
+            data = json.load(f)
+        super().__init__(data)
+
+
+class ViewsManager(DotDict):
+    pass
+
+
+class UiManager:
+    """
+    Manages Hilda's UI.
+
+    - New views can be added to `ViewManager` (Must be inherent `Views`)
+    - Colors can be changed from terminal (Setting `ui_manager.color.title = 'green'` or be modifying `colors.json`)
+    - Views can be disabled from terminal (Setting `ui_manager.color.title=False`)
+    """
+
+    def __init__(self, hilda_client, scheme_file=Path(__file__).parent / 'colors.json',
+                 active: bool = True):
+        """
+        :param hilda_client: hilda.hilda_client.HildaClient
+        :param scheme_file: pathlib.Path
+        :param active: bool
+        """
+        self.colors = ColorScheme(scheme_file)
+        self.views = ViewsManager({
+            'registers': RegistersView(hilda_client, self.colors),
+            'disassembly': DisassemblyView(hilda_client, self.colors),
+            'stack': StackView(hilda_client, self.colors),
+            'backtrace': BackTraceView(hilda_client, self.colors)
+        })
+        self.active = active
+
+    def show(self, *args) -> None:
+        fmt_parts = []
+
+        for view in self.views.values():
+            if view.active is False:
+                continue
+            fmt_parts.append(str(view))
+        print('\n'.join(fmt_parts))

hilda/ui/views.py

@@ -0,0 +1,217 @@
+import shutil
+from abc import abstractmethod
+from typing import List, Mapping
+
+from click import style
+from lldb import SBAddress
+from tabulate import tabulate
+
+WORD_SIZE = 8
+
+
+def dict_diff(d1: Mapping, d2: Mapping) -> List[str]:
+    """ Returns a list of keys whose values have changed """
+    changed_keys = []
+    if d1 is None or d2 is None:
+        return changed_keys
+    for k, v in d1.items():
+        if k in d2 and d2[k] != v:
+            changed_keys.append(k)
+    return changed_keys
+
+
+class View:
+    """ Base class of view"""
+
+    def __init__(self, hilda_client, title, color_scheme):
+        """
+        :param hilda_client: hilda.hilda_client.HildaClient
+        :param title: str
+        :param color_scheme: hilda.ui.ui_manager.ColorScheme
+        """
+        self.title = title
+        self.hilda = hilda_client
+        self.active = True
+        self.color_scheme = color_scheme
+
+    @abstractmethod
+    def __str__(self) -> str:
+        return self._format_title()
+
+    def _format_title(self) -> str:
+        terminal_size = shutil.get_terminal_size()
+        fmt = style(self.title.center(terminal_size.columns, '─'), fg=self.color_scheme.title)
+        fmt += '\n'
+        return fmt
+
+
+class StackView(View):
+    """ Implements stack view """
+    DEFAULT_STACK_DEPTH = 10
+
+    def __init__(self, hilda_client, color_scheme, depth=DEFAULT_STACK_DEPTH):
+        """
+        :param hilda_client: hilda.hilda_client.HildaClient
+        :param depth: int
+        :param color_scheme: hilda.ui.ui_manager.ColorScheme
+
+        `prev` saves the last stack stats inorder to perform diff check.
+        """
+        super().__init__(hilda_client, 'Stack', color_scheme)
+        self.depth = depth
+        self.prev: Mapping[int, str] = None
+
+    def __str__(self) -> str:
+        """ Format stack view for printing """
+        stack_mapping = self._create_mapping()
+        diff_in_keys = dict_diff(stack_mapping, self.prev)
+        self.prev = stack_mapping.copy()
+        fmt_parts = []
+        offset = 0
+        for k, v in stack_mapping.items():
+            data_color = self.color_scheme.stack_data if k not in diff_in_keys else self.color_scheme.diff
+            fmt = f'{style(hex(k), fg=self.color_scheme.address)}|+' \
+                  f'{style(hex(offset), fg=self.color_scheme.stack_offset)}: ' \
+                  f'{style(v, fg=data_color)}'
+            if offset == 0:
+                fmt += f'{"<-- $sp":^50}'
+            offset += WORD_SIZE
+            fmt_parts.append(fmt)
+
+        return super().__str__() + '\n'.join(fmt_parts)
+
+    def _create_mapping(self) -> Mapping[int, str]:
+        """ Generate mapping of stack address:data"""
+        base_addr = self.hilda.frame.sp
+        stack_mapping = {}
+        for i in range(0, self.depth * WORD_SIZE, WORD_SIZE):
+            current = base_addr + i
+            stack_mapping[current] = '0x' + self.hilda.symbol(current).peek(WORD_SIZE).hex()
+        return stack_mapping
+
+
+class RegistersView(View):
+    """ Implements registers view """
+    DEFAULT_REGISTERS_TYPE = 'general'
+
+    def __init__(self, hilda_client, color_scheme, rtype=DEFAULT_REGISTERS_TYPE):
+        """
+        :param hilda_client: hilda.hilda_client.HildaClient
+        :param rtype: str
+        :param color_scheme: hilda.ui.ui_manager.ColorScheme
+
+        `prev` saves the last registers stats inorder to perform diff check.
+        """
+        super().__init__(hilda_client, 'Registers', color_scheme)
+        self.prev: Mapping[str, str] = None
+        self.rtype = rtype
+
+    def __str__(self) -> str:
+        """ Format registers view for printing"""
+        regs_mapping = self._create_mapping()
+        diff_in_keys = dict_diff(regs_mapping, self.prev)
+        self.prev = regs_mapping.copy()
+        list_of_lists = []
+        names = []
+        values = []
+        i = 0
+
+        # Divide the registers into columns of 16
+        for k, v in regs_mapping.items():
+            if i % 16 == 0 and i != 0:
+                list_of_lists.append(names.copy())
+                list_of_lists.append(values.copy())
+                names = []
+                values = []
+
+            names.append(style(k, fg=self.color_scheme.regs_name))
+            if k in diff_in_keys:
+                values.append(style(v, fg=self.color_scheme.diff))
+            else:
+                values.append(style(v, fg=self.color_scheme.regs_value))
+            i += 1
+
+        return super().__str__() + tabulate(list(zip(*list_of_lists)), tablefmt='plain', numalign='left')
+
+    def _create_mapping(self) -> Mapping[str, str]:
+        """ Generate mapping of registers name:data"""
+        regs = self._get_registers()
+        regs_mapping = {}
+        for reg in regs:
+            regs_mapping[reg.GetName()] = reg.GetValue()
+        return regs_mapping
+
+    def _get_registers(self):
+        """
+        Returns list of registers grouped by type.
+        Available types: [general,floating]
+        :return:  lldb.SBValueList
+        """
+        registers_set = self.hilda.frame.GetRegisters()
+        for value in registers_set:
+            if self.rtype.lower() in value.GetName().lower():
+                return value
+        return None
+
+
+class DisassemblyView(View):
+    """ Implements disassembly view """
+    DEFAULT_INSTRUCTION_COUNT = 5
+    DEFAULT_DISASSEMBLY_FLAVOR = 'intel'
+
+    def __init__(self, hilda_client, color_scheme, instruction_count=DEFAULT_INSTRUCTION_COUNT,
+                 flavor=DEFAULT_DISASSEMBLY_FLAVOR):
+        """
+        :param hilda_client: hilda.hilda_client.HildaClient
+        :param instruction_count: int
+        :param color_scheme: hilda.ui.ui_manager.ColorScheme
+        """
+        super().__init__(hilda_client, 'Disassembly', color_scheme)
+        self.instruction_count = instruction_count
+        self.flavor = flavor
+
+    def __str__(self) -> str:
+        """ Format disassembly view for printing """
+        pc = self.hilda.frame.pc
+        target = self.hilda.target
+
+        disass = target.ReadInstructions(SBAddress(pc, target), self.instruction_count, self.flavor)
+        fmt_parts = []
+        for inst in disass:
+            load_addr = inst.addr.GetLoadAddress(self.hilda.target)
+            base_name = style(inst.addr.module.file.basename, self.color_scheme.basename)
+            addr = style(hex(load_addr), fg=self.color_scheme.address)
+            mnemonic = style(inst.GetMnemonic(self.hilda.target), fg=self.color_scheme.mnemonic)
+            operands = style(inst.GetOperands(self.hilda.target), fg=self.color_scheme.operands)
+            fmt = f'{base_name}[{addr}]: {mnemonic} {operands}'
+            if load_addr == self.hilda.frame.pc:
+                fmt += f'{"<-- $pc":^50}'
+            fmt_parts.append(fmt)
+        return super().__str__() + '\n'.join(fmt_parts)
+
+
+class BackTraceView(View):
+    """ Implements backtrace view """
+    DEFAULT_BACKTRACE_DEPTH = 5
+
+    def __init__(self, hilda_client, color_scheme, depth=DEFAULT_BACKTRACE_DEPTH):
+        """
+        :param hilda_client: hilda.hilda_client.HildaClient
+        :param depth: int
+        :param color_scheme: hilda.ui.ui_manager.ColorScheme
+        """
+        super().__init__(hilda_client, 'BackTrace', color_scheme)
+        self.depth = depth
+
+    def __str__(self) -> str:
+        """ Format backtrace view for printing"""
+        bt = self.hilda.bt(should_print=False, depth=self.depth)
+        bt_colored = []
+        for pair in bt:
+            bt_colored.append(
+                [
+                    style(pair[0], fg=self.color_scheme.address),
+                    pair[1]
+                ]
+            )
+        return super().__str__() + tabulate(bt_colored, tablefmt='plain', numalign='left')

{hilda-0.2.0.dist-info → hilda-0.3.0.dist-info}/METADATA

@@ -1,8 +1,8 @@
 Metadata-Version: 2.1
 Name: hilda
-Version: 0.2.0
+Version: 0.3.0
 Summary: LLDB wrapped and empowered by iPython's features
-Author-email: doronz88 <doron88@gmail.com>, matan <matan1008@gmail.com>
+Author-email: doronz88 <doron88@gmail.com>, matan <matan1008@gmail.com>, netanel <matan1008@gmail.com>
 Maintainer-email: doronz88 <doron88@gmail.com>, matan <matan1008@gmail.com>
 License: Copyright (c) 2012-2023 Doron Zarhi and Metan Perelman
         
@@ -47,6 +47,7 @@ Requires-Dist: click
 Requires-Dist: objc-types-decoder
 Requires-Dist: construct
 Requires-Dist: pymobiledevice3
+Requires-Dist: keystone-engine
 Provides-Extra: test
 Requires-Dist: pytest ; extra == 'test'
 
@@ -312,6 +313,65 @@ capabilities:
 stop?
 ```
 
+## UI Configuration
+
+Hilda contains minimal UI for examining the target state.
+The UI is divided into views:
+
+- Registers
+- Disassembly
+- Stack
+- Backtrace
+
+![img.png](gifs/ui.png)
+
+This UI can be displayed at any time be executing:
+
+```python
+ui.show()
+```
+
+By default `step_into` and `step_over` will show this UI automatically.
+You may disable this behaviour by executing:
+
+```python
+ui.active = False
+```
+
+Attentively, if you want to display UI after hitting a breakpoint, you can register `ui.show` as callback:
+
+```python
+symbol(0x7ff7b97c21b0).bp(ui.show)
+```
+
+Try playing with the UI settings by yourself:
+
+```python
+# Disable stack view
+ui.views.stack.active = False
+
+# View words from the stack
+ui.views.stack.depth = 10
+
+# View last 10 frames
+ui.views.backtrace.depth = 10
+
+# Disassemble 5 instructions
+ui.views.disassembly.instruction_count = 5
+
+# Change disassembly syntax to AT&T
+ui.views.disassembly.flavor = 'att'
+
+# View floating point registers
+ui.views.registers.rtype = 'float'
+
+# Change addresses print color
+ui.colors.address = 'red'
+
+# Change titles color
+ui.color.title = 'green'
+```
+
 ## Symbol objects
 
 In Hilda, almost everything is wrapped using the `Symbol` Object. Symbol is just a nicer way for referring to addresses

{hilda-0.2.0.dist-info → hilda-0.3.0.dist-info}/RECORD

@@ -6,9 +6,9 @@ hilda/from_ns_to_json.m,sha256=5Ddl0UJLQXlDYwR_yjE4yZk1aOsJGxoy1oRnhZHPrTw,2847
 hilda/get_objectivec_class_description.m,sha256=Emqavl1i_qzVUYhg8b22mFhb0kZXQHPNB6vt_w-SUe0,4777
 hilda/get_objectivec_symbol_data.m,sha256=xoxESO2iyMbTAkQPRste3ZWPYjqiC7QuixE3pHOML04,6421
 hilda/hilda_ascii_art.html,sha256=-9YCjAKdGbjtdd6uoKrxkkcJq7j16r4dGka2bZ27b4o,120119
-hilda/hilda_client.py,sha256=XF6Ndyc7NxxQ1y-IlBJdPASD-NwD2Gx8DK2FeFrNsu4,41527
+hilda/hilda_client.py,sha256=lORoJ3K-few_ivri7PPDWN4IpinG0QE7bhHEvysEjUg,42180
 hilda/launch_lldb.py,sha256=QaA5UFxaLWdLiEK839VbnyGLsY6sY0ODi1ge0-DlJsg,2855
-hilda/lldb_entrypoint.py,sha256=Cjj520dApKCiBUNeCbOACFrZV8zU2QUBgHFAmxwWH5w,900
+hilda/lldb_entrypoint.py,sha256=m5cUqnDCcqfgFTdlExMLjcq4F5L0gywuBIfFLnDLy8o,1006
 hilda/lsof.m,sha256=FAtTc76-EFlWq1WTJkxYnNTnj0V8exPsiOH3rzAJAAA,3168
 hilda/objective_c_class.py,sha256=CsvfWEIz8t5ew891DYIgCgf1UFcatiEYlTgpbtKSa44,11403
 hilda/objective_c_symbol.py,sha256=OAH0eL0m__2XpwY-GKuPs-L8KSztWeqrUF8CfUDzGBQ,8611
@@ -24,7 +24,7 @@ hilda/snippets/fs_utils.py,sha256=97BKWXj6yuKxD6tDm3Nlaq6ACfET2oQFVwE2VlArw3E,39
 hilda/snippets/remotepairingd.py,sha256=LxIMyXTl2YFoKMScs16s7vB5b8IFRdWead5tuKd5ZCw,5824
 hilda/snippets/syslog.py,sha256=8qhYHKTElzWifqYAwt72iQ57wf1n0F_au2Vl2L8NPOc,294
 hilda/snippets/uuid.py,sha256=ttw-rq2Wshm7UMZXd5uYP37bi8G_ZE4XcXJbsYIgp1c,273
-hilda/snippets/xpc.py,sha256=Idb6-IZkEIHsfNcv13IN_WgMH1FG5OekX2yriiAvTO0,3629
+hilda/snippets/xpc.py,sha256=GM6AN7UuJ0niE51PXdrh0WzYT-u2V1mPDOUwDTiiAEo,3909
 hilda/snippets/mach/CFRunLoopServiceMachPort_hooks.py,sha256=nAFZ4TjjBy0BlffbsKnTneGa0YE_T9bPNv5qhPVR-Hw,4156
 hilda/snippets/mach/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 hilda/snippets/macho/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -33,9 +33,12 @@ hilda/snippets/macho/apple_version.py,sha256=TTaqZKMviXJoU1o3OYeUskmxSkhVhh3UG1V
 hilda/snippets/macho/image_info.py,sha256=862C3T2-pPCwgdRqJTNNv28gECwGigJiZojUIFGIKqg,1588
 hilda/snippets/macho/macho.py,sha256=X4NQZkO7VCcIMNuPs25ukiBrHM5Kj3UPMJzzeILfuyg,839
 hilda/snippets/macho/macho_load_commands.py,sha256=KF-HCr46iQloOwnLfFPUYi0dn9ehywSoy1R_P-BqMPI,10644
-hilda-0.2.0.dist-info/LICENSE,sha256=M-LVJ0AFAYB82eueyl8brh-QLPe-iLNVgbCi79-3TDo,1078
-hilda-0.2.0.dist-info/METADATA,sha256=BoaHbTOFhMgTqygcngpLjmgJ5RpaW3zmJXJzw3zgx9I,21063
-hilda-0.2.0.dist-info/WHEEL,sha256=pkctZYzUS4AYVn6dJ-7367OJZivF2e8RA9b_ZBjif18,92
-hilda-0.2.0.dist-info/entry_points.txt,sha256=9n3O3j6V3XnVR_GcFqCWNgRAbalfukTSW2WvghsLVmA,46
-hilda-0.2.0.dist-info/top_level.txt,sha256=nyNxC_JClCNn-Oi_JFapvV2VrlMk4x47b2mnwP5OJik,6
-hilda-0.2.0.dist-info/RECORD,,
+hilda/ui/colors.json,sha256=f-ITquY3IInQreviTy23JfmxfJrGM1_MivACf1GKGqM,262
+hilda/ui/ui_manager.py,sha256=BmzI1sBx0PYCQDlB9Al7wsTEAMJxaJ7NW0DS4C7g5-0,2265
+hilda/ui/views.py,sha256=Sd0y7I0iQ4HAWJNyDQ6LjvbEtJYolCaC2sAuPWs6-EE,7693
+hilda-0.3.0.dist-info/LICENSE,sha256=M-LVJ0AFAYB82eueyl8brh-QLPe-iLNVgbCi79-3TDo,1078
+hilda-0.3.0.dist-info/METADATA,sha256=ALa5ZPU4GoOsKqZgMATXZMtQj4oSxEfQUonznBxl3xE,22234
+hilda-0.3.0.dist-info/WHEEL,sha256=AtBG6SXL3KF_v0NxLf0ehyVOh0cold-JbJYXNGorC6Q,92
+hilda-0.3.0.dist-info/entry_points.txt,sha256=9n3O3j6V3XnVR_GcFqCWNgRAbalfukTSW2WvghsLVmA,46
+hilda-0.3.0.dist-info/top_level.txt,sha256=nyNxC_JClCNn-Oi_JFapvV2VrlMk4x47b2mnwP5OJik,6
+hilda-0.3.0.dist-info/RECORD,,

{hilda-0.2.0.dist-info → hilda-0.3.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.40.0)
+Generator: bdist_wheel (0.41.0)
 Root-Is-Purelib: true
 Tag: py3-none-any