From 6d3b4ba2d28e3e356a67098ca83786270f81c456 Mon Sep 17 00:00:00 2001
From: Andrew Haberlandt <ahaberla@andrew.cmu.edu>
Date: Tue, 9 Jul 2024 05:15:15 +0000
Subject: [PATCH] docs: readme

---
 README.md | 37 ++++++++++++++-----------------------
 1 file changed, 14 insertions(+), 23 deletions(-)

diff --git a/README.md b/README.md
index 4f2b05c..112d584 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@ going through GDB or ptrace.
 
 
 Features:
-- **Asynchronous Breakpoints/Hooks**: Inspect and modify registers
+- **Breakpoints/Hooks**: Inspect and modify registers
 and memory at any instruction.
 - **Redirect execution**: Hooks can directly modify the program
 counter; for example, to cause a function to return early or to
@@ -25,11 +25,11 @@ in the same address space as the target.
 - **Graceful multithreading**: All threads share the same Python interpreter
 (including globals), making it easy to write tools that
 aggregate over several threads.  Unlike GDB/ptrace, which suspends *all* threads
-when *any* thread reaches a breakpoint, Pyda hooks execute asynchronously[*](#how-it-works)
-and do not interrupt other threads. 
+when *any* thread reaches a breakpoint, Pyda hooks do not interrupt
+other threads[*](#how-it-works).
 
 
-It is intended to fufill many of the same use-cases as debuggers (e.g. GDB/Pwndbg),
+Pyda is intended to fufill many of the same use-cases as debuggers (e.g. GDB/Pwndbg),
 or complex dynamic instrumentation frameworks (Frida, Dynamorio, DynInst, PIN, etc.).
 It was designed with CTF challenges (pwn/rev) in mind.
 
@@ -40,8 +40,7 @@ docker run -it ghcr.io/ndrewh/pyda pyda examples/ltrace.py -- ls -al
 ```
 
 
-Example
------
+## Example
 > [!WARNING]
 > This API is not stable and may change. Please provide
 > feedback on the API by filing an issue.
@@ -78,22 +77,22 @@ at main, rsp=0x7fff1303f078
 return address: 0x7f3c50420d90
 ```
 
+
+### More examples
 See [examples/](examples/) for additional examples.
 
-Current features:
------
-- Hooks (aka "breakpoints" if you prefer) at arbitrary instructions
-- Syscall pre/post hooks
-- Read and write memory
-- Read and modify registers
-- Supports multithreaded programs
+- [`ltrace.py`](examples/ltrace.py): Hook all calls to library functions, and print out their arguments
+- [`strace.py`](examples/strace.py): Hook all syscalls and print out their arguments
+- [`resolve_indirect_calls.py`](examples/resolve_indirect_calls.py): dump a list of indirect calls with `objdump`, and then
+print out the targets during execution
+
 
 ## Limitations
-- Currently Linux only
+- Currently Linux only (please contribute Windows support!)
 - Currently X86_64 only (please contribute ARM64 support!)
 - All of the limitations of Dynamorio apply. The program must be reasonably well behaved.
 - Some state may be shared with the target process; while Dynamorio
-attempts to isolate our libc from the target, OS structures (e.g. fds)
+attempts to isolate our libc (and other libraries) from the target, OS structures (e.g. fds)
 are shared.
 
 ## Getting started
@@ -124,14 +123,6 @@ pyda <script_path> [script_args] -- <bin_path> [bin_args]
 ```sh
 pyda examples/ltrace.py -- ls
 ```
-
-### Examples
-
-- [`ltrace.py`](examples/ltrace.py): Hook all calls to library functions, and print out their arguments
-- [`resolve_indirect_calls.py`](examples/resolve_indirect_calls.py): dump a list of indirect calls with `objdump`, and then
-print out the targets during execution
-- [`strace.py`](examples/strace.py): Hook all syscalls and print out their arguments
-
 ### API
 
 You can view all of the available APIs in [process.py](https://github.com/ndrewh/dynamorio-tool/blob/master/lib/pyda/process.py), but in summary: