even more docs

docs/interception.md

@@ -0,0 +1,32 @@
+# Interception of Binary Functions
+
+The mach-detours library enables interception of function calls. Interception code is applied dynamically at runtime. mach-detours replaces the first few instructions of the *target function* with an unconditional jump to the user-provided *detour function*. Instructions from the target function are preserved in a *trampoline function*. The trampoline consists of the instructions removed from the target function and an unconditional branch to the remainder of the target function.
+
+When execution reaches the target function, control jumps directly to the user-supplied detour function. The detour function performs whatever interception *preprocessing* is appropriate. The detour function can return control to the *source* function or it can call the trampoline function, which invokes the target function without interception. When the target function completes, it returns control to the detour function. The detour function performs appropriate *postprocessing* and returns control to the source function. **Figure 1** shows the logical flow of control for function invocation with and without interception.
+
+------------------------------------------------------------------------
+
+<figure>
+  <img src="img/interception-figure-1-control-flow.png">
+  <figcaption>Figure 1. Control flow of invocation without and with a detour in place.</figcaption>
+</figure>
+
+------------------------------------------------------------------------
+
+The mach-detours library intercepts target functions by rewriting their in-process binary image. For each target function, mach-detours actually rewrites two functions, the target function and the matching trampoline function, and one function pointer, the target pointer. The trampoline function is allocated dynamically by mach-detours. The trampoline contains the initial instructions from the target function and a jump to the remainder of the target function.
+
+The *target pointer* is initialized by the user to point to the target function. After a detour is attached to the target function, the target pointer is modified to point to the trampoline function. After the detour is detached from the target function, the target pointer is restored to point to the original target function.
+
+------------------------------------------------------------------------
+
+<figure>
+  <img src="img/interception-figure-2-instructions.png">
+  <figcaption>Figure 2. Trampoline and target functions, before (on the left) and after (on the right) insertion of the detour.</figcaption>
+</figure>
+
+------------------------------------------------------------------------
+
+**Figure 2** shows the insertion of a detour. To detour a target function, mach-detours first allocates memory for the dynamic trampoline function and then enables write access to both the target and the trampoline. (Note: Making the memory containing these functions writable means it also has to be non-executable under modern macOS. This poses some restrictions on the code that can be run while the detour is being inserted. Often the user would want to suspend other threads, mach-detours provides APIs for that.)
+
+Starting with the first instruction, mach-detours copies instructions from the target to the trampoline until enough bytes have been copied to insert an unconditional jump to the detour. If the target function is too short, mach-detours aborts and returns an error code.<br/>
+To copy instructions, mach-detours uses a simple table-driven disassembler. mach-detours adds a jump instruction from the end of the trampoline to the first non-copied instruction of the target function. mach-detours writes an unconditional jump instruction to the detour function as the first instruction of the target function. To finish, mach-detours restores the original page permissions on both the target and trampoline functions.