mirror of
https://github.com/rkujawa/rk65c02.git
synced 2026-03-11 03:16:11 +00:00
96 lines
4.2 KiB
Markdown
96 lines
4.2 KiB
Markdown
# MS BASIC example
|
||
|
||
This example runs [Microsoft BASIC](https://github.com/mist64/msbasic) (6502 port by mist64) inside the rk65c02 emulator. You can type BASIC programs and run them, with terminal I/O and optional Ctrl-C break support.
|
||
|
||
## Prerequisites
|
||
|
||
- **ca65 / ld65** (cc65 toolchain) for assembling and linking the BASIC ROM and I/O stub
|
||
- **Git** with the `msbasic` submodule initialised
|
||
- **librk65c02** built (from `src/`); JIT is used when available (Lightning)
|
||
|
||
## Submodule and patches
|
||
|
||
The BASIC source is included as a git submodule. After cloning the repo, initialise and update it:
|
||
|
||
```bash
|
||
git submodule update --init examples/msbasic/msbasic
|
||
```
|
||
|
||
The example applies small patches to the submodule so it can build the `rk65c02` platform. Patches are under `examples/msbasic/patches/` and are applied automatically when you run `make` in `examples/msbasic/` (they add the rk65c02 branch to `defines.s`, `extra.s`, `iscntc.s`, `loadsave.s`, and `init.s`). The `init.s` patches set the output vector (GOSTROUT) to STROUT for rk65c02 so that prompts and output work correctly; `init.s.patch` applies the first three changes and `init.s.hunk4.patch` applies the fourth (run in that order).
|
||
|
||
## Build
|
||
|
||
From the project root or from `examples/`:
|
||
|
||
```bash
|
||
make msbasic
|
||
```
|
||
|
||
Or from this directory:
|
||
|
||
```bash
|
||
make
|
||
```
|
||
|
||
This builds:
|
||
|
||
- **basic.bin** — BASIC ROM (loaded at $B000)
|
||
- **iostub.bin** — I/O stub (loaded at $F002)
|
||
- **run_msbasic** — host program
|
||
|
||
The host links against `../../src/librk65c02.a`. To build without JIT (e.g. if Lightning is not installed), build the library with `NO_LIGHTNING=1` and then build this example with `make NO_LIGHTNING=1`.
|
||
|
||
## Run
|
||
|
||
From `examples/msbasic/`:
|
||
|
||
```bash
|
||
./run_msbasic
|
||
```
|
||
|
||
On startup, BASIC will prompt for **MEMORY SIZE** and **TERMINAL WIDTH**. You can press Enter to accept defaults, or type values (e.g. `65535` then Enter for memory, then `72` then Enter for width). After that you get the BASIC prompt and can type programs:
|
||
|
||
```
|
||
PRINT 1+1
|
||
RUN
|
||
```
|
||
|
||
To exit: type `END` and press Enter, or press Ctrl-C (if supported; the host sets bit 0 of the status port $F001 when SIGINT is received so that BASIC’s ISCNTC can break).
|
||
|
||
## I/O and memory map
|
||
|
||
- **$0000–$7FFF** — 32 KB RAM (program, variables, input buffer)
|
||
- **$B000–$DFFF** — BASIC ROM and init (from ld65 `BASROM` segment)
|
||
- **$F000** — I/O data port: **write** = character output (host `putchar`), **read** = character input (host `getchar`, blocking)
|
||
- **$F001** — Status port: **read** returns bit 0 = 1 when Ctrl-C has been pressed (for ISCNTC)
|
||
- **$F002–$F00F** — I/O stub code: MONCOUT ($F002), MONRDKEY ($F006), MONRDKEY2 ($F00A); these access $F000 for actual I/O
|
||
|
||
Entry point is **COLD_START**, read from `basic.lbl` at build time.
|
||
|
||
## JIT
|
||
|
||
The host enables the emulator JIT with `rk65c02_jit_enable(&e, true)`. I/O is performed via the bus device at $F000; when the guest executes the stub at $F002 (e.g. STA $F000), the write is handled by the device and the host’s `putchar` runs. Blocking `getchar` in the device is fine while the emulator is running.
|
||
|
||
## Optional timer
|
||
|
||
BASIC’s RND uses an in-memory seed (RNDSEED); no hardware timer is required for basic operation. The plan allowed for an optional jiffy counter at $F002/$F003; this example does not implement it. You can add a timer device and drive it from a tick or idle callback if you want time-based RND or similar.
|
||
|
||
## Files in this directory
|
||
|
||
| File | Purpose |
|
||
|------|--------|
|
||
| `defines_rk65c02.s` | Platform defines (ZP, CONFIG_*, MONCOUT/MONRDKEY addresses) |
|
||
| `rk65c02_extra.s` | EXTRA segment (minimal) |
|
||
| `rk65c02_iscntc.s` | ISCNTC (Ctrl-C via $F001) |
|
||
| `rk65c02_loadsave.s` | SAVE/LOAD stubs (messages only) |
|
||
| `rk65c02_io.s` | I/O stub assembly (MONCOUT, MONRDKEY, MONRDKEY2 at $F002) |
|
||
| `rk65c02.cfg` / `iostub.cfg` | ld65 configs for BASIC and stub |
|
||
| `patches/*.patch` | Patches applied to the msbasic submodule |
|
||
| `msbasic_host.c` | Host program (bus, device, load ROM/stub, run with JIT) |
|
||
| `Makefile` | Build BASIC, stub, and host |
|
||
|
||
## References
|
||
|
||
- [mist64/msbasic](https://github.com/mist64/msbasic) — Microsoft 6502 BASIC source (submodule)
|
||
- rk65c02 examples: `hello_serial`, `jit_bench` for bus device and JIT usage
|