# Examples
Each subdirectory demonstrates one `sighook` API as a Cargo example target.
Current supported host targets:
- `aarch64-apple-darwin`
- `x86_64-apple-darwin`
- `aarch64-unknown-linux-gnu`
- `x86_64-unknown-linux-gnu`
Build all examples from repository root:
```bash
cargo build --examples
```
Build feature-gated asm example:
```bash
cargo build --example patch_asm_add_to_mul --features patch_asm
```
Artifacts are generated under the root `target/debug/examples/` directory.
Available examples:
- `patchcode_add_to_mul`: patch one opcode directly
- `patch_asm_add_to_mul` (requires `patch_asm`): assemble one instruction from string and patch
- `instrument_with_original`: BRK instrumentation + execute original opcode
- `instrument_no_original`: BRK instrumentation + skip original opcode
- `instrument_unhook_restore`: install instruction hook, then unhook and verify original behavior
- `instrument_adrp_no_original`: aarch64 `adrp` patch-point via `instrument_no_original` + manual callback emulation
- `instrument_adrp_with_original`: aarch64 `adrp` patch-point via `instrument(...)` + automatic replay
- `inline_hook_signal`: function-entry signal hook; callback writes return value and returns to caller
- `inline_hook_fpregs`: function-entry signal hook; callback writes FP/SIMD return registers (`v0` / `xmm0` / `ymm0`)
- `inline_hook_far`: function-entry detour with `inline_hook_jump`
## Coverage matrix
- `aarch64-apple-darwin`: `patchcode` / `instrument` / `instrument_no_original` / `inline_hook` / `inline_hook_fpregs` / `inline_hook_jump`
- `aarch64-apple-darwin`: plus optional `patch_asm` smoke (`--features patch_asm`)
- `x86_64-apple-darwin`: runtime smoke coverage for 7 base examples (CI), plus optional `patch_asm` build
- `aarch64-unknown-linux-gnu`: runtime smoke coverage for all 9 core examples (CI, includes `instrument_adrp_no_original` and `instrument_adrp_with_original`)
- `aarch64-unknown-linux-gnu`: plus optional `patch_asm` smoke (`--features patch_asm`)
- `x86_64-unknown-linux-gnu`: runtime smoke coverage for 7 base examples (CI), plus optional `patch_asm` smoke (`--features patch_asm`)
## Notes by architecture
- On `aarch64-unknown-linux-gnu`, `calc` examples expose dedicated patchpoint symbols (`calc_add_insn` and `calc_adrp_insn`) and resolve patch points by symbol (no fixed offset dependency).
- `instrument_adrp_no_original` demonstrates `adrp` interception via `instrument_no_original` and manual callback emulation.
- `instrument_adrp_with_original` demonstrates `instrument(...)` replaying a displaced `adrp` patch point directly.
- On `aarch64-apple-darwin`, `calc` examples keep fixed `ADD_INSN_OFFSET=0x14` for the naked function layout.
- On `x86_64-unknown-linux-gnu`, `calc` examples use fixed offsets in dedicated assembly stubs (`instrument*`: `+0x4`, `patchcode_add_to_mul`: `+0x6`). `patchcode_add_to_mul` patches `add eax, edx; nop; nop` into one-operand `imul edx` (result in `eax`).
- `patch_asm_add_to_mul` uses equivalent patches via assembly text (`aarch64`: `mul w0, w8, w9`; `x86_64`: `imul %edx`).
- `inline_hook_fpregs` validates FP/SIMD callback context mutation: `aarch64`/macOS `x86_64` replace the 128-bit return register, while Linux `x86_64` replaces the 256-bit AVX return register (`ymm0`).