# risc-v-gsp-rm-debugger plugins

A plugin is a Python module exposing `register(ge)`:

```python
def register(ge):
    ge.log("my plugin loaded")
    ge.add_command("mycmd", mycmd, help="does a thing")
    ge.hook("rpc_sum", on_enter=lambda hit: ge.log(f"sum a0={hit.arg(0):#x}"))
```

`ge` provides:
* `session`, `memory`, `symbols`, `recorder` — the live objects;
* `hook(target, on_enter=, on_leave=)` / `watch(target, size=, kind=, callback=)`;
* `on_event(kind, callback)` — react to every stop of a kind;
* `add_command(name, fn, help=)` — new REPL commands (`fn(session, args) -> int`);
* `log(message, **fields)` — recorded plugin notes.

Discovery: `--plugin PATH` (file or directory), then `GREENEYE_PLUGINS`
(colon-separated), then the bundled `plugins/` directory. A plugin that raises
is recorded as `plugin_error` and never breaks the session.

Types of plugins that fit risc-v-gsp-rm-debugger:
1. **Runtime RE tools** — new watchpoint strategies, coverage collectors,
   structure probes, heap/allocator graphs.
2. **Harnesses** — stimulus drivers that poke mailboxes/rings and assert on
   recorded events.
3. **Virtualization-environment updates** — replay/record wrappers, QEMU
   argument tweaks, device-model shims.
4. **AI/harness integration** — export sessions to analysis services; the
   **MCP server is implemented as a bundled plugin** (`mcp_server.py`, see
   `docs/20-MCP-SERVER.md`), stdlib-only and read-only by default.

The example plugin is `example_plugin.py`.