Briefly document traps

README.md

@@ -127,9 +127,13 @@ It could be broken up into multiple files, usefully.
 
 ## Changes
 
-Compared to [the original project](https://github.com/skx/simple.vm) there is currently only one change:
+Compared to [the original project](https://github.com/skx/simple.vm) there are two main changes:
 
 * The `DB`/`DATA` operation allows storing string data directly in the generated bytecode.
+* There is a notion of `traps`.
+ * Rather than defining opcodes for complex tasks it is now possible to callback into the CPU-emulator to do work.
+
+#### DB/DATA Changes
 
 For example in simple.vm project this is possible:
 
@@ -142,6 +146,16 @@ But this is not:
 
 `go.vm` supports this, and it is demonstrated in [examples/peek-strlen.in](examples/peek-strlen.in).
 
+#### Traps
+
+The instruction `int` can be used to call back to the emulator to do some work
+on behalf of a program. Only two traps are defined right now:
+
+* `int 0x00`
+ * Set the contents of the register `#0` with the length of the string in register `#0`.
+* `int 0x01`
+ * Set the contents of the register `#0` with a string entered by the user.
+ * See [examples/trap.stdin.in](examples/trap.stdin.in).
 
 Steve
 --

examples/trap.stdin.in

@@ -0,0 +1,9 @@
+ store #1, "Enter a string:"
+ print_str #1
+
+ # Reads a string from the console - sets the result in register #0
+ int 0x01
+
+ store #1, "\nYou entered:\n"
+ print_str #1
+ print_str #0