docs: add two more 'misc features' to emulator docs

Author: msm-code

docs/emulator.md

@@ -112,8 +112,8 @@ reusable scripts, but `emu["EAX"]` is faster to type when working interactively.
 
 ### Hooks
 
-Often we are very interested in the details of the execution, and we want to
-process every executed instruction. For this we can use the `callback` parameter:
+Often we are interested in the details of the execution, and we want to
+process every instruction in some way. We can easily do this using the `callback` parameter:
 
 ```python
 >>> emu = Emulator()
@@ -349,7 +349,7 @@ Especially if you're emulatingh random pieces of code, setting maxsteps
 to something reasonable (like 2000 instructions) may save you from accidentaly
 executing an infinite loops.
 
-**breakpoints**
+**Breakpoints**
 
 You can set and remove breakpoints using `add_breakpoint` and `clear_breakpoint`
 methods
@@ -365,6 +365,52 @@ The downside is that it doesn't support callbacks or instruction counting -
 you can only emulate until a specific address. As an upside, function hooks
 are supprted.
 
+**Emulation shorthands**
+
+To save precious keystrokes you may combine creating an emulator, running it,
+and inspecting the result into one step with:
+
+```python
+>>> Emulator.new("main", maxsteps=100)["EAX"]
+128
+```
+
+This convenience wrapper is equivalent to the following code:
+
+```python
+>>> emu = Emulator()
+>>> emu.emulate("main", maxsteps=100)
+>>> emu["EAX"]
+128
+```
+
+Some other objects also provide helpers to do the obvious thing with emulator.
+For example, you can emulate a function call with:
+
+
+```python
+>>> emu = Function("test").emulate(10)
+>>> emu["EAX"]
+113
+>>> # Or an even shorter version
+>>> Function("test").emulate_simple(10)
+113
+```
+
+**Unicorn compatibility**
+
+There is a very, very thin compatibility layer with Unicorn. There are aliases
+provided for the following Unicorn methods: `reg_write`, `reg_read`, `mem_write`,
+`mem_read`, `mem_map`, `emu_start`. Why? The idea is that many people already
+know Unicorn. It may make it a tiny bit easier for them if they can use familiar
+method names instead of learning a completely new set.
+
+The goal is not to provide actual compatibility layer - Unicorn is a very different
+library and `ghidralib` won't replace it. The only goal is really so Unicorn users
+can use familiar names if they forget ghidralib equivalents. If you are not
+an Unicorn user, don't use them.
+
+
 ### Learn more
 
 Check out relevant examples in the `examples` directory, especially:

ghidralib.py

@@ -2308,18 +2308,16 @@ def infer_context(self):  # type: () -> Emulator
         """Emulate the code before this function call, and return the state.
 
         The goal of this function is to recover the state of the CPU
-        before the function call, as well as possible. This will work well in case
-        the assembly looks like, for example:
+        before the function call, as well as possible. This will work well when
+        parameters are constants written just before the call, for example:
 
             mov eax, 30
             mov ebx, DAT_encrypted_string
             call decrypt_string
 
-        Then recovering eax them is as simple as call.infer_context()["eax"]."""
+        Then recovering eax is as simple as call.infer_context()["eax"]."""
         basicblock = BasicBlock(self._address)
-        emu = Emulator()
-        emu.emulate(basicblock.start_address, self._address)
-        return emu
+        return Emulator.new(basicblock.start_address, self._address)
 
     @property
     def high_pcodeop(self):  # type: () -> PcodeOp|None
@@ -3593,7 +3591,7 @@ def single_step(self):  # type: () -> bool
         return False
 
     @staticmethod
-    def emulate_new(
+    def new(
         start,
         ends=[],
         callback=lambda emu: None,
@@ -3602,8 +3600,20 @@ def emulate_new(
     ):  # type: (Addr, Addr|list[Addr], Callable[[Emulator], str|None], Callable[[Emulator], bool], int) -> Emulator
         """Emulate from start to end address, with callback for each executed address.
 
-        This function creates a new emulator, runs emulate on it, and returns it.
-        See emulate documentation for information about the parameters."""
+            >>> Emulator.new("main", maxsteps=100)["EAX"]
+            128
+
+        This function is a convenience wrapper around emulate and can be always
+        replaced by three lines of code. The above is equivalent to:
+
+            >>> emu = Emulator()
+            >>> emu.emulate("main", maxsteps=100)
+            >>> emu["EAX"]
+            128
+
+        This function may be used for quickly doing one-off emulations.
+
+        See `emulate` documentation for info about this method parameters."""
         emu = Emulator()
         emu.emulate(start, ends, callback, stop_when, maxsteps)
         return emu
@@ -3621,7 +3631,7 @@ def emulate(
             >>> emu = Emulator()
             >>> def callback(emu):
             >>>     print("executing {:x}'.format(emu.pc))
-            >>> emu.trace(Function("main").entrypoint, callback=callback, maxsteps=3)
+            >>> emu.emulate(Function("main").entrypoint, callback=callback, maxsteps=3)
             SUB ESP,0x2d4
             PUSH EBX
             PUSH EBP
@@ -3678,6 +3688,17 @@ def is_at_breakpoint(self):  # type: () -> bool
         """Check if the emulator is at a breakpoint"""
         return self.raw.getEmulator().isAtBreakpoint()
 
+    # Basic unicorn compatibility, because why not
+    # You may prefer these aliases if you already know Unicorn API.
+    reg_write = write_register
+    reg_read = read_register
+    mem_write = write_bytes
+    mem_read = read_bytes
+    mem_map = (
+        lambda _1, _2, _3: None
+    )  # This is a noop - all memory is already available.
+    emu_start = lambda self, begin, until: self.emulate(begin, until)
+
 
 class MemoryBlock(GhidraWrapper, BodyTrait):
     """A Ghidra wrapper for a Ghidra MemoryBlock"""

tests/ghidralib_test.py

@@ -556,6 +556,7 @@ def test_emulator():
     emu = Emulator()
     emu.add_breakpoint(0x403ED0)
     emu.emulate(0x403EC1)
+    assert emu["esi"] == 0xFFFF
     assert emu.pc == 0x403ED0
 
     emu = Emulator()
@@ -564,6 +565,10 @@ def test_emulator():
     assert emu["esi"] == 0xFFFF
     assert emu.pc == 0x403ED0
 
+    emu = Emulator.new(0x403ECB, 0x403ED0)
+    assert emu["esi"] == 0xFFFF
+    assert emu.pc == 0x403ED0
+
     emu.single_step()
     assert emu.pc == 0x405F96