# Z80 UART monitor

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
optional `0x` prefix is accepted.

| Command | Action |
| --- | --- |
| `D 8000` | Dump 40 bytes starting at address 8000 |
| `D 8000 20` | Dump 20 bytes starting at address 8000 |
| `W 8000 3E 41 D3 25 C9` | Write bytes starting at address 8000 |
| `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
`RET` returns to the monitor. Code that changes the stack pointer, interrupt
mode, or UART/CTC setup must restore it before returning.

Build the ROM and programmer-format images with:

```sh
make
```

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-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`.
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.