basic: add usr command

apps/basic/README.md

@@ -160,6 +160,19 @@ Then, there's the *special stuff*. This is the list of things you can query for:
 
 * `$`: the scratchpad.
 
+**usr**: This calls the memory address specified as an expression argument.
+Before doing so, it sets the registers according to a specific logic: Variable
+`A`'s LSB goes in register `A`, variable `D` goes in register `DE`, `H` in `HL`
+`B` in `BC` and `X` in `IX`. `IY` can't be used because it's used for the jump.
+Then, after the call, the value of the registers are put back into the
+variables following the same logic.
+
+Let's say, for example, that you want to use the kernel's `printstr` to print
+the contents of the scratchpad. First, you would call `addr $` to put the
+address of the scratchpad in `A`, then do `h=a` to have that address in `HL`
+and, if printstr is, for example, the 21st entry in your jump table, you'd do
+`usr 21*3` and see the scratchpad printed!
+
 ## Optional modules
 
 As explained in "glueing" section abolve, this folder contains optional modules.

apps/basic/main.asm

@@ -399,6 +399,31 @@ basADDR:
 	.dw	SCRATCHPAD
 	.db	0
 
+basUSR:
+	call	rdExpr
+	ret	nz
+	push	ix \ pop iy
+	; We have our address to call. Now, let's set up our registers.
+	; HL comes from variable H. H's index is 7*2.
+	ld	hl, (VAR_TBL+14)
+	; DE comes from variable D. D's index is 3*2
+	ld	de, (VAR_TBL+6)
+	; BC comes from variable B. B's index is 1*2
+	ld	bc, (VAR_TBL+2)
+	; IX comes from variable X. X's index is 23*2
+	ld	ix, (VAR_TBL+46)
+	; and finally, A
+	ld	a, (VAR_TBL)
+	call	callIY
+	; Same dance, opposite way
+	ld	(VAR_TBL), a
+	ld	(VAR_TBL+46), ix
+	ld	(VAR_TBL+2), bc
+	ld	(VAR_TBL+6), de
+	ld	(VAR_TBL+14), hl
+	cp	a		; USR never errors out
+	ret
+
 ; direct only
 basCmds1:
 	.dw	basBYE
@@ -435,4 +460,6 @@ basCmds2:
 	.db	"sleep", 0
 	.dw	basADDR
 	.db	"addr", 0, 0
+	.dw	basUSR
+	.db	"usr", 0, 0, 0
 	.db	0xff, 0xff, 0xff	; end of table