giles
f3192f7fda
lib/extensions/ becomes the new home for VM extensions, wired in via (include_subdirs unqualified). README documents the registration pattern, opcode-ID range conventions (200-209 guest_vm, 210-219 inline test, 220-229 test_ext, 230-247 ports), and naming rules. extensions/test_ext.ml is the canonical worked example — two operand-less opcodes (220 push 42, 221 double TOS) carrying a per- extension state slot (TestExtState invocation counter). Test_ext.register called from run_tests.ml at the start of the Phase D suite, on top of the inline test_reg from earlier suites (disjoint opcode IDs). Sx_vm.opcode_name now consults extension_opcode_name_ref (forward ref in the same style as extension_dispatch_ref), so disassemble shows extension opcodes by name instead of UNKNOWN_n. Registry maintains name_of_id_table and installs the lookup at module init. Tests: 5 new foundation cases — primitive resolves test_ext name, end-to-end bytecode (push + double + return → 84), disassemble shows "test_ext.OP_TEST_PUSH_42" / "test_ext.OP_TEST_DOUBLE_TOS", unregistered ext opcodes still fall back to UNKNOWN_n, invocation counter records the two dispatches. +5 pass vs Phase C baseline, no regressions across 11 conformance suites.
72 lines
2.5 KiB
Markdown
72 lines
2.5 KiB
Markdown
# SX VM extensions
|
|
|
|
Each `*.ml` file here is a VM extension — a first-class OCaml module that
|
|
registers specialized bytecode opcodes with `Sx_vm_extensions`. See
|
|
[`plans/sx-vm-opcode-extension.md`](../../../../plans/sx-vm-opcode-extension.md)
|
|
for the design.
|
|
|
|
## Pattern
|
|
|
|
```ocaml
|
|
(* lib/extensions/myport.ml *)
|
|
open Sx_types
|
|
|
|
type Sx_vm_extension.extension_state += MyportState of { ... }
|
|
|
|
module M : Sx_vm_extension.EXTENSION = struct
|
|
let name = "myport"
|
|
let init () = MyportState { ... }
|
|
let opcodes _st = [
|
|
(id, "myport.OP_NAME", handler);
|
|
...
|
|
]
|
|
end
|
|
|
|
let register () = Sx_vm_extensions.register (module M)
|
|
```
|
|
|
|
Then call `Myport.register ()` once at startup from any binary that
|
|
should have the extension loaded.
|
|
|
|
## Opcode-ID allocation
|
|
|
|
Range 200-247 (per `Sx_vm_extensions.extension_min` /
|
|
`extension_max`). Conventions:
|
|
|
|
| Range | Use |
|
|
|---------|-------------------------------------------------------------------------|
|
|
| 200-209 | reserved for `lib/guest/vm/` shared opcodes (chiselled out on 2nd use) |
|
|
| 210-219 | inline test extensions defined in `bin/run_tests.ml` |
|
|
| 220-229 | this directory's `test_ext` (the canonical template) |
|
|
| 230-247 | first-come-first-served by language ports (Erlang first) |
|
|
|
|
When a port claims a contiguous block, document it in the table above.
|
|
The registry rejects collisions at startup with a loud error — there is
|
|
no silent shadowing.
|
|
|
|
## Naming
|
|
|
|
Always prefix opcode names with the extension name plus a dot:
|
|
`myport.OP_<NAME>`. The prefix is a hard convention so that multiple
|
|
extensions can share the global opcode-name namespace cleanly.
|
|
|
|
## State
|
|
|
|
`extension_state` is an extensible variant. Add your case (e.g.
|
|
`MyportState of { ... }`) at the top of your file, return it from
|
|
`init`, and pattern-match it inside your handlers. Other extensions
|
|
cannot see your state — the variant case is private to your module.
|
|
|
|
## Testing
|
|
|
|
`test_ext.ml` is the canonical worked example. `bin/run_tests.ml`
|
|
calls `Test_ext.register ()`, then drives bytecode that exercises the
|
|
opcodes end-to-end (push, double, dispatch, disassemble, invocation
|
|
counter). Mirror this shape when adding a real port's extension.
|
|
|
|
## Build wiring
|
|
|
|
`lib/dune` has `(include_subdirs unqualified)`, so any `.ml` you drop
|
|
in here is automatically part of the `sx` library. Module name follows
|
|
the filename verbatim (`test_ext.ml` → `Test_ext`).
|