Added tinybasic

README.md

@@ -1,12 +1,12 @@
 # Z80 UART monitor
 
-This ROM provides a small interactive monitor on the UART/CTC card at I/O base
-`20`. At reset, a small ROM bootstrap copies the monitor into the top 16 KiB of
-RAM at `C000-FFFF` and starts it there. Only the occupied vector/code bytes are
-stored and copied; uninitialized data is cleared directly in high RAM. The low ROM can subsequently be disabled
-without taking the monitor, its data, or its interrupt table away. Runtime code
-and vectors occupy the lower part of this window, globals begin at `F000`, and
-the stack grows downward from `FFFF`; no RAM below `C000` is used.
+This ROM provides a small interactive monitor and a bundled Z80 Tiny BASIC
+interpreter on the UART/CTC card at I/O base `20`. At reset, a small ROM
+bootstrap copies both programs into the top 16 KiB of RAM and starts the
+monitor. Only occupied code/vector bytes are stored and copied; uninitialized
+data is cleared directly in high RAM. The low ROM can subsequently be disabled
+without taking away the monitor, Tiny BASIC, monitor data, or interrupt table.
+No runtime RAM below `C000` is used.
 
 Connect a terminal at **2400 baud, 8 data bits, no parity, 1 stop bit**.
 Commands are case-insensitive and all numeric arguments are hexadecimal; an
@@ -20,6 +20,8 @@ optional `0x` prefix is accepted.
 | `I 20` | Read I/O port 20 |
 | `O 20 57` | Write 57 to I/O port 20 |
 | `G 8000` | Execute code at address 8000 |
+| `G D000` | Start the bundled Z80 Tiny BASIC interpreter |
+| `B` or `BASIC` | Shortcut for `G D000` |
 | `HELP` | Show the command summary |
 
 `G` transfers control with a return address on the stack, so code ending in
@@ -32,13 +34,65 @@ Build the ROM and programmer-format images with:
 make
 ```
 
-The outputs are `build/metal/monitor.bin` (32 KiB ROM image) and
-`build/metal/monitor.prog.bin` (compact programmer image). The ROM layout is:
+The outputs are:
+
+- `build/metal/monitor.bin`: complete 32 KiB ROM image
+- `build/metal/monitor.prog.bin`: compact image ending at the last occupied byte
+- `build/tinybasic/tinybasic.bin`: standalone relocated Tiny BASIC payload
+
+The current compact image is 6,157 bytes. Its ROM layout is:
 
 - `0000-007F`: reset/copy bootstrap
-- `0080...`: compact vector/code image copied to RAM starting at `C000`
-- Remaining bytes: unused and available for additional ROM content
+- `0080-0F6E`: monitor image copied to RAM at `C000-CEEE`
+- `0F6F-0FFF`: unused space reserved for monitor growth
+- `1000-180C`: Tiny BASIC image copied to RAM at `D000-D80C`
+- `180D-7FFF`: unused space available for additional ROM content
 
 The monitor executable starts at `C080`; its IM 2 vector table is at `C040`.
-`monitor.prog.bin` ends immediately after the occupied payload, while
-`monitor.bin` remains a complete 32 KiB chip image.
+The bootstrap obtains both copy lengths from generated/linker symbols, so the
+copied sizes track changes to the programs automatically.
+
+The resulting high-RAM layout is:
+
+- `C000-CEEE`: monitor vectors, services, and code
+- `CEEF-CFFF`: free
+- `D000-D80C`: Tiny BASIC code
+- `D80D-DFFF`: free
+- `E000-E7FF`: Tiny BASIC workspace and BASIC program text
+- `E800-E877`: Tiny BASIC variables and input buffer
+- `E878-EFFF`: Tiny BASIC stack space
+- `F000-FFFF`: monitor globals and monitor stack
+
+## Tiny BASIC
+
+The original GNU-z80asm listing is retained as `tinybasic/tinybasic.asm`. Its
+`sdasz80` port is `tinybasic/tinybasic_sdas.asm` and is built automatically.
+The port replaces fixed low-page `RST` calls with relocatable calls and uses a
+marker-based command table so addresses in the `D000` page work correctly.
+
+At reset the bootstrap copies Tiny BASIC from ROM offset `1000` to `D000`.
+Start it from the monitor with:
+
+```text
+B
+```
+
+`BASIC` and `G D000` are equivalent alternatives.
+
+Tiny BASIC calls the monitor ABI at `C050` for output and `C053` for
+non-blocking input. The assembly ABI wrappers preserve the working registers,
+and Tiny BASIC keeps interrupts enabled so it can share the monitor's configured
+interrupt-driven UART.
+
+Line editing accepts either `BS` (`08`) or `DEL` (`7F`) for backspace and emits
+`BS SPACE BS` so ANSI-style terminals erase the character visually. Ctrl-U
+clears the complete input line.
+
+During execution, Ctrl-O toggles output suppression without stopping the BASIC
+program. Press Ctrl-O again to resume output. Ctrl-C stops execution and
+returns to the Tiny BASIC prompt.
+
+Tiny BASIC resets the stack pointer when it starts, so it does not currently
+return through the monitor's `G` call. Reset the machine to return to the
+monitor. The first currently unused ROM byte is `180D`; `1900` is a convenient
+aligned starting point for another ROM payload.