badline 0.16.1 → 0.18.0

data/README.md

@@ -12,8 +12,8 @@ are modelled at the cycle level.
 
 It runs programs, disk and tape images, cartridges and SID tunes, and
 the SDL2 front end supports the keyboard, joysticks, game controllers,
-paddles and a 1351 mouse. It also runs a PAL VIC-20, as
-`badline vic20`, the C128, in C128 mode on 40 or 80 columns and in C64 mode, as `badline c128`, the Plus/4, the C16 and the C116, as `badline plus4`, and the PET and CBM, as `badline pet`. See [What's emulated](#whats-emulated) for the details.
+paddles and a 1351 mouse. It also runs the VIC-20, PAL or NTSC, as
+`badline vic20`, the C128, in C128 mode on 40 or 80 columns and in C64 mode, as `badline c128`, the Plus/4, the C16 and the C116, as `badline plus4`, the PET and CBM, as `badline pet`, the CBM-II, the B series and the P500, as `badline cbm2`, and the MOS KIM-1, as `badline kim1`. See [What's emulated](#whats-emulated) for the details.
 
 It comes in two builds of the same emulator:
 
@@ -70,8 +70,9 @@ from it.
 The first argument can name the machine, as in `badline c64 game.prg`.
 The C64 is the default, and `--model` picks which C64. See
 [The VIC-20](#the-vic-20) for `badline vic20`, [The C128](#the-c128)
-for `badline c128`, [The Plus/4](#the-plus4) for `badline plus4` and
-[The PET](#the-pet) for `badline pet`.
+for `badline c128`, [The Plus/4](#the-plus4) for `badline plus4`,
+[The PET](#the-pet) for `badline pet`, [The CBM-II](#the-cbm-ii) for
+`badline cbm2` and [The KIM-1](#the-kim-1) for `badline kim1`.
 
 `badline-ruby` takes the same media and the same options, with the
 differences noted in the table. `--help` lists the options for either.
@@ -82,20 +83,26 @@ differences noted in the table. `--help` lists the options for either.
 | --- | --- |
 | `--no-autostart` | Attach the media and stop at `READY.`, so you can type the `LOAD` yourself |
 | `--writable` | Let the machine write to disk images. Without it, a disk goes in write-protected: the drive reports `26,WRITE PROTECT ON` for any write and the image file stays as it was |
-| `--true-drive` | Put an emulated 1541 on device 8 instead of the KERNAL traps, a 1551 on the Plus/4, or a 2031 on the PET. See [Media](#media) |
-| `--drive-type 1541` | On the Plus/4, make the true drive on device 8 an emulated 1541 on the serial bus in place of the 1551. It implies `--true-drive`. See [The Plus/4](#the-plus4) |
+| `--true-drive` | Put an emulated 1541 on device 8 instead of the KERNAL traps, a 1551 on the Plus/4, or a 2031 on the PET or the CBM-II, or for a `.d80` or `.d82` an 8050 or 8250. A `.d90` always goes in a D9060 or D9090. See [Media](#media) |
+| `--drive-type MODEL` | On the Plus/4, `1541` makes the true drive on device 8 an emulated 1541 on the serial bus in place of the 1551. On the PET and the CBM-II, `2031` (the default), `8050`, `8250`, `1001` (an SFD-1001, which reads `.d82` images), `4040` or `3040` (two drives reading `.d64` images, with DOS 2.1), `2040` (DOS 1.2's `.d67` images), `9060` or `9090` names the drive `--true-drive` puts on the IEEE-488 bus. It implies `--true-drive`. See [The Plus/4](#the-plus4) and [The PET](#the-pet) |
 | `-s`, `--subtune N` | Pick a subtune of a `.sid` file, counting from 1 |
 | `--sid 6581`, `--sid 8580` | Fit the older or newer SID. `--sid auto`, the default, takes a `.sid` tune's own |
-| `--ram SIZE` | Give a VIC-20 the RAM expansion `SIZE`: `unexpanded`, `3k`, `8k`, `16k`, `24k`, `32k` or `all`. Without it, the VIC-20 gets the expansion its media needs. See [The VIC-20](#the-vic-20). On the Plus/4, `16k`, `32k` or `64k` of RAM in place of the model's own, and on the PET `4k`, `8k`, `16k` or `32k` |
-| `--60hz` | Run a CRTC PET's 60 Hz editor in place of its 50 Hz one. See [The PET](#the-pet) |
+| `--ram SIZE` | Give a VIC-20 the RAM expansion `SIZE`: `unexpanded`, `3k`, `8k`, `16k`, `24k`, `32k` or `all`. Without it, the VIC-20 gets the expansion its media needs. See [The VIC-20](#the-vic-20). On the Plus/4, `16k`, `32k` or `64k` of RAM in place of the model's own, on the PET `4k`, `8k`, `16k` or `32k`, and on the KIM-1 `1k` (the default), `5k` or `expanded`. See [The KIM-1](#the-kim-1) |
+| `--60hz` | Run a CRTC PET's 60 Hz editor in place of its 50 Hz one, or a CBM-II on 60 Hz mains. See [The PET](#the-pet) and [The CBM-II](#the-cbm-ii) |
+| `--kernal 04a`, `--kernal 03b` | Fit a B series CBM-II with KERNAL 901244-04a (the default) or 901244-03b. The P500 takes its own, `02`. See [The CBM-II](#the-cbm-ii) |
 | `--basic VERSION`, `--editor NAME` | Fit a PET with an upgrade ROM its board takes: BASIC `1`, `2` or `4`, or an editor. See [The PET](#the-pet) |
 | `--c1lo FILE`, `--c1hi FILE`, `--c2lo FILE`, `--c2hi FILE` | Put a raw `.bin` ROM image in one of the Plus/4's cartridge slots: cartridge 1 or 2, low (`$8000`) or high (`$C000`). See [The Plus/4](#the-plus4) |
 | `--sid-card 6581`, `--sid-card 8580` | Fit a Plus/4 or C16 with a SID card at `$FD40`. See [The Plus/4](#the-plus4) |
 | `--sid-card-address fd40`, `--sid-card-address fe80` | Put the SID card at `$FD40` (the default) or at `$FE80` |
 | `--ram-expansion NAME` | Fit a Plus/4 or C16 with a RAM expansion: `hannes256`, `hannes1m` or `csory256`. See [The Plus/4](#the-plus4) |
 | `--reu SIZE` | Plug in a RAM Expansion Unit of `SIZE` K: 128, 256, 512 (a 1750) or up to 16384 |
-| `--model NAME` | Run another model of the machine, named as in VICE. For the C64: `c64` (the default, a PAL C64 with the 6569 VIC-II, 6526 CIAs and the 6581 SID), `c64c` (the PAL C64C, with the 8565, 6526As and the 8580), `ntsc` (the 6567R8), `newntsc` (the NTSC C64C, with the 8562, 6526As and the 8580), `oldntsc` (the first NTSC C64s' 6567R56A), `drean` (the Drean C64 of Argentina, PAL-N with the 6572), `sx64` (the portable SX-64, with its own KERNAL and no datasette), `pet64` (the PET 64 or Educator 64, a PAL C64 in a PET's case with its own KERNAL and a green monochrome monitor) `c64gs` (the C64GS games console, a PAL C64C with its own BASIC and KERNAL, and no keyboard or datasette) or `ultimax` (the MAX Machine of Japan, NTSC with 2K of RAM, one CIA and no ROMs, which runs only a cartridge). `--sid` or a `.sid` tune's own SID takes the model's place. The VIC-20, the C128, the Plus/4 and the PET have models of their own: see their sections |
-| `--ntsc` | Run an NTSC C64, as `--model ntsc` does |
+| `--model NAME` | Run another model of the machine, named as in VICE. For the C64: `c64` (the default, a PAL C64 with the 6569 VIC-II, 6526 CIAs and the 6581 SID), `c64c` (the PAL C64C, with the 8565, 6526As and the 8580), `ntsc` (the 6567R8), `newntsc` (the NTSC C64C, with the 8562, 6526As and the 8580), `oldntsc` (the first NTSC C64s' 6567R56A), `drean` (the Drean C64 of Argentina, PAL-N with the 6572), `sx64` (the portable SX-64, with its own KERNAL and no datasette), `pet64` (the PET 64 or Educator 64, a PAL C64 in a PET's case with its own KERNAL and a green monochrome monitor) `c64gs` (the C64GS games console, a PAL C64C with its own BASIC and KERNAL, and no keyboard or datasette) or `ultimax` (the MAX Machine of Japan, NTSC with 2K of RAM, one CIA and no ROMs, which runs only a cartridge). `--sid` or a `.sid` tune's own SID takes the model's place. The VIC-20, the C128, the Plus/4, the PET and the CBM-II have models of their own: see their sections |
+| `--ntsc` | Run an NTSC C64 or VIC-20, as `--model ntsc` does |
+| `--tty` | Fit the KIM-1's TTY/KB jumper, so its monitor talks to a teletype: a page in the window, or the terminal with `--headless`. See [The KIM-1](#the-kim-1) |
+| `--baud N` | Run the KIM-1's teletype at `110`, `300`, `1200`, `2400`, `4800` or `9600` baud (the default) |
+| `--tty-load` | Load the KIM-1's `.ptp` or `.pap` through its monitor's `L` command on the teletype, in real time, instead of straight into RAM. It implies `--tty` |
+| `--load-address ADDR` | Where the KIM-1 loads a `.bin`, in hex: `0200` (the default), `$0200` or `0x0200` |
+| `--start-address ADDR` | Where the KIM-1 starts its program, in hex, when that isn't where it loads |
 | `--c64` | Start a C128 in C64 mode, holding `C=` at power-on. See [The C128](#the-c128) |
 | `--no-sound` | Don't play the SID (`badline` only, where sound is on by default) |
 | `--sound` | Play the SID (`badline-ruby`, where sound is off by default) |
@@ -115,7 +122,7 @@ differences noted in the table. `--help` lists the options for either.
 | `--script FILE` | Run the events in `FILE`, one `FRAME:EVENT` a line |
 | `--screenshot FILE` | Save the last frame as a `.bmp` |
 | `--save-snapshot FILE` | Save the machine as a `.vsf` snapshot after the last frame |
-| `--vice` | Add VICE's modules to `--save-snapshot`'s C64 or PET snapshot, so x64sc or xpet opens it too |
+| `--vice` | Add VICE's modules to `--save-snapshot`'s C64, PET or CBM-II snapshot, so x64sc, xpet, xcbm2 or xcbm5x0 opens it too |
 
 ```sh
 badline --unpaced --frames 12000 --true-drive disk1.d64 \
@@ -136,12 +143,14 @@ library, are covered in [doc/library.md](doc/library.md).
 | `.prg`, `.p00` | Loaded into memory after boot. A program at the BASIC start (`$0801`) is `RUN`, anything else is left for you to `SYS` |
 | `.d64`, `.d71`, `.d81` | Mounted as device 8, then `LOAD"*",8,1` and `RUN`. On a C128 in C128 mode a boot disk goes in a true drive instead and boots at power-on. See [Media](doc/media.md#c128-boot-disks). Write-protected unless `--writable` |
 | `.g64` | Put in a true 1541, then `LOAD"*",8,1` and `RUN`. It holds the disk's raw GCR, so copy protection that reads it works. Write-protected unless `--writable` |
+| `.d80`, `.d82`, `.d67` | A PET's or a CBM-II's disk: an 8050's, an 8250's or SFD-1001's, or a 2040's with DOS 1. It starts a PET, and is mounted as device 8 or put in the true drive that reads it. See [The PET](#the-pet) |
+| `.d90` | A D9060's or D9090's hard disk. It starts a PET, and always goes in the true drive, the D9060 or the D9090 by its size. See [The PET](#the-pet) |
 | `.m3u`, `.vfl` | A list of disk images, one path a line, relative to the list: an `.m3u` playlist, or a VICE flip list, which only unit 8's entries are taken from. Its first disk goes in as above, and the list is its set for the pause menu |
 | `.t64` | Mounted read-only as device 8 and loaded like a disk image. The files load by name, and no tape is involved |
 | `.tap` | Inserted in the datasette with PLAY pressed, then `LOAD` and `RUN`. It loads at the speed of a real tape |
 | `.crt` | The hardware types listed under [Cartridges](#whats-emulated). Other types are rejected |
 | `.sid` | PSID and RSID tunes, started through a small driver after boot |
-| `.vsf` | A snapshot of a running machine, badline's own or one VICE's x64sc saved. See [Snapshots](#snapshots) |
+| `.vsf` | A snapshot of a running machine, badline's own or one VICE's x64sc, xpet, xcbm2 or xcbm5x0 saved. See [Snapshots](#snapshots) |
 | A directory | Mounted as device 8. It serves the `.prg` and `.p00` files in it and the contents of any `.t64`, and `SAVE` writes a new `.prg` |
 
 Without `--true-drive`, device 8 is no drive at all but traps on the
@@ -156,11 +165,14 @@ from Ruby.
 
 ## The VIC-20
 
-`badline vic20` runs a PAL VIC-20, and takes the same media as the C64
-apart from SID tunes:
+`badline vic20` runs a PAL VIC-20, with the 6561 VIC-I, and
+`badline vic20 --ntsc` (or `--model ntsc`) an NTSC one, with the 6560 and
+the NTSC KERNAL, at 1,022,727 Hz and 60 frames a second. Either takes the
+same media as the C64 apart from SID tunes:
 
 ```sh
 badline vic20             # READY.
+badline vic20 --ntsc      # READY., on an NTSC VIC-20
 badline vic20 game.prg    # Load and run a program
 badline vic20 game.d64    # Mount a disk image as device 8 and load it
 badline vic20 game.tap    # Insert a tape and load it
@@ -305,7 +317,8 @@ the business keyboard), `8096` (an 8032 with the 64K board at `$FFF0`),
 `8296` (128K on one board, below), `4032` (40 columns on a CRTC and the
 graphics keyboard), `3032` (the
 discrete 40-column board with BASIC 2), `3032b` (the same with the
-business keyboard) and `2001` (8K, BASIC 1 and the chiclet keyboard).
+business keyboard), `2001` (8K, BASIC 1 and the chiclet keyboard) and
+`superpet` (an 8032 with the Waterloo board, below).
 `--ram 4k`, `8k` or `16k` fits less RAM in place of the model's own, as
 the 3008, 3016 and 4016 had.
 
@@ -339,6 +352,44 @@ runs its own 50 Hz editor, `4-80-b-50hz-8296`, with lines of 59 cycles,
 fits the German boards' 4K character ROM, whose two halves R12's bit 5
 picks between.
 
+The SuperPET, the SP9000 or MMF 9000, is an 8032 with the University of
+Waterloo's board: 64K of RAM in 16 banks of 4K, one at a time at `$9000`
+through the bank latch at `$EFFC`, the system latch at `$EFF8`, a 6551
+ACIA at `$EFF0` with nothing on its RS-232 port, the 6702 protection
+chip at `$EFE0`, and the 901640-01 character ROM, whose first half is the
+8032's and whose second half holds an ASCII and an APL set. It starts in
+6502 mode, as an 8032 with the board, and `--cpu 6809` sets its CPU switch
+to the 6809, which runs the Waterloo ROMs to their microSystems menu. The
+menu loads its languages from disk: a language disk given with `--cpu
+6809` goes in device 8, which answers the Waterloo ROM's IEEE-488
+routines through traps as it answers the KERNAL's, so typing `basic` at
+the menu loads microBASIC in about 20 seconds of the machine's time. The
+menu loads from drive 1 of a dual drive, and the traps' one disk answers
+as drive 1 too. With `--true-drive` the disk goes in a true drive
+instead: a `.d80` or `.d82` in drive 1 of an 8050 or 8250, where typing
+`basic` loads microBASIC in about twice the time, and a `.d64` in a
+2031's only drive, where `disk/0.BASIC` does. In 6502 mode a disk goes in
+drive 0, as on the 8032. The original language
+disks' copy protection finds its 6702, so they run unpatched. `--cpu
+prog` leaves the CPU to bit 0 of the system latch, and `--bank-ram read`
+write-protects the 64K bank RAM, or `prog` leaves it to bit 1, R/W by
+default. The pause menu's power page has both switches: moving the CPU
+switch resets the machine onto the CPU it picks, and the RAM switch
+takes effect at once. While a Waterloo language shows its APL
+characters, as microAPL does, the keys go by position: each presses the
+SuperPET key that types its unshifted character, with the host's SHIFT,
+so it types the APL symbol on that keycap. The menu's KEYBOARD page
+says which set is up. It takes the 8032's editors and `--60hz`,
+which picks the Waterloo ROM with the 60 Hz CRTC table, and no `--ram`.
+Its snapshots save and load in both modes, and xpet's `-model SuperPET`
+opens those saved with `--vice`.
+
+```sh
+badline pet --model superpet --cpu 6809                   # The SuperPET's Waterloo menu
+badline pet --model superpet --cpu 6809 sp9000lang.d80    # The same with the language disk
+badline pet --model superpet --bank-ram read              # The bank RAM write-protected
+```
+
 ```sh
 badline pet --model 8296 --jumpers ram9,rama  # An 8296 with RAM at $9000 and $A000
 badline pet --model 2001 --basic 2   # A 2001 with BASIC 2
@@ -354,11 +405,26 @@ goes into memory as a program file does. `--basic 2`, the upgrade
 Commodore sold, loads from disk.
 
 A program loads at the start of BASIC, `$0401`, and runs. A `.d80`, a
-`.d82` or a tape made for the PET starts a PET without `pet`, but a
+`.d82`, a `.d67`, a `.d90` or a tape made for the PET starts a PET
+without `pet`, but a
 program that loads at `$0401` starts a C64, since a VIC-20 with 3K loads
 there too. Disks go through the KERNAL traps on the IEEE-488 bus as
 device 8, or with `--true-drive` an emulated 2031 on the bus, which
-reads `.d64` and `.g64` images, and tapes play on cassette port 1. The keys type what the host's
+reads `.d64` and `.g64` images, and an 8050 for a `.d80` or an 8250 for
+a `.d82`. `--drive-type 8050` or `8250` plugs either in from the start,
+and `--drive-type 1001` an SFD-1001, the single drive that takes the
+8250's disks, for a `.d82`. `--drive-type 4040` or `3040` puts a `.d64`
+in a 4040 or a 3040 with DOS 2.1 in place of the 2031. A `.d67`, a DOS 1
+disk, goes in a 2040 running DOS 1.2, the only DOS 1 there is an image
+of, which takes `I0` before it reads a disk and `0:` before a file name,
+and works from BASIC 2. The traps mount a `.d67` as they do the others.
+A `.d90` hard disk image always goes in an emulated D9060 or D9090, by
+its size, since the traps don't read one; `--drive-type 9060` or `9090`
+picks the drive whatever the image's size. Its `N` skips the test
+patterns the DOS writes over the whole disk, an hour on the hardware.
+The pause menu's Drive 8 page lists the drive types under DRIVE TYPE,
+and the one picked goes on the bus as device 8, with the disk device 8
+had if it reads it. Tapes play on cassette port 1. The keys type what the host's
 keys type, on either keyboard, and `Alt` adds the PET's `SHIFT`:
 [Input](#input) lists the rest. The pause
 menu's Power page names the model, its RAM and its frame rate, and its
@@ -367,6 +433,133 @@ jumpers. The PET has no
 joysticks. `F11` and the Snapshots page save it as they do the others,
 but not for VICE.
 
+## The CBM-II
+
+`badline cbm2` runs a CBM 610 of the B series, with BASIC 128 and 80
+columns on a green screen, and takes programs, disks and cartridges:
+
+```sh
+badline cbm2                        # READY., in BASIC 128
+badline cbm2 game.prg               # Load and run a program
+badline cbm2 game.d82               # Mount an 8250's disk as device 8 and load it
+badline cbm2 game.crt               # Put a cartridge in and start the machine
+badline cbm2 --model 720            # A 720, with 256K and the 700's monitor
+badline cbm2 --model 510 game.d82   # A P500, the CBM 510, on the VIC-II
+```
+
+`--model` picks the machine: `610` (the default, 128K), `620` (256K,
+with BASIC 256), `710` and `720` (the same with the 700's monitor and
+character ROM, 25 rows of 14 lines). `--kernal 03b` fits the 1983
+KERNAL, 901244-03b, in place of 901244-04a, the default, which VICE
+runs too, and on a 610 or a 710 BASIC 128's 1983 release, 02b, with it. The machine runs on 50 Hz mains, and
+`--60hz` on 60 Hz, which also sets a 600's jumper for its editor's
+60 Hz table. The mains is the system tick and the clock of the CIA's
+time of day.
+
+A program loads at the start of BASIC, `$0003` in segment 1, and runs.
+Disks of every kind, `.d80` and `.d82` among them, go through the
+KERNAL traps on the IEEE-488 bus as device 8, or with `--true-drive` an
+emulated 2031 on the bus, which reads `.d64` and `.g64` images, and an
+8050 for a `.d80` or an 8250 for a `.d82`, and `--drive-type` names the
+drive to start with, as on the PET. A 610's first `LOAD` from a
+2031 after power-on finds no file, as on xcbm2, and the second loads.
+A `.d80` or `.d82` on its own starts a PET, so `cbm2` names the machine
+for one, but a cartridge made for the CBM-II starts it without `cbm2`.
+The cartridge goes in from the command line or Quick open. There is no
+datasette. The SID plays through the host's audio device at
+the machine's 2 MHz, as the C64's does. The keys type what the host's
+keys type, as on the PET, and `Alt` with a key presses the keys the
+host has none for: [Input](#input) lists them. The pause menu's Power
+page names the model, its RAM, the mains and the KERNAL, and its
+Expansion port page its RAM. The B series has no joysticks. `F11` and
+the Snapshots page save it as they do the others, and `--vice` adds
+xcbm2's modules, so xcbm2 opens the file too.
+
+`--model 510` runs the P500, the CBM 510: the B series' CPU, SID, CIA,
+ACIA and keyboard at about 1 MHz, with a VIC-II for 40 columns in
+colour, 128K of RAM and its own KERNAL, 901234-02. `510` is PAL on
+50 Hz mains, and `510ntsc` NTSC on 60 Hz. A program loads at `$0003` in
+segment 0. Its keys are the B series', and it has two joysticks on its
+control ports: `Tab` switches the keys to them, as on the C64, and game
+controllers drive them. The pause menu's Ports page plugs a 1351 mouse
+or a pair of paddles into either port, as on the C64, and while the
+keys type, says where its keys are.
+
+## The KIM-1
+
+`badline kim1` runs a MOS KIM-1, the single-board computer of 1976,
+with its 1K of RAM and the monitor in its 6530-002. The window shows its
+six LED digits and its keypad, and the monitor starts on address 0000:
+
+```sh
+badline kim1                        # The monitor, on the keypad and display
+badline kim1 --tty                  # The monitor on a teletype, in the window
+badline kim1 --headless             # The monitor on a teletype, in the terminal
+badline game.ptp                    # Load a papertape and run it
+badline kim1 --ram 5k game.bin      # Load a .bin at $0200 on a board with 5K
+```
+
+| Host key | KIM-1 key |
+|----------|-----------|
+| `0`-`9`, `A`-`F`, the keypad's digits | The hex keys |
+| `,` | AD, address mode |
+| `.` | DA, data mode |
+| `Space`, `+`, the keypad's `+` | +, the next address |
+| `G`, `Return`, `Enter` | GO |
+| `P` | PC |
+| `S`, `Esc` | ST, which stops a program |
+| `R` | RS, reset |
+| `T` | The SST switch, which steps a program an instruction at a time |
+
+A click on a key the window draws presses it too. Each digit is lit
+only while a program scans it, as on the board, so the monitor's
+display is steady, a program that scans more slowly shows dimmer, and
+one that doesn't scan leaves it dark. ST and SST work once the NMI
+vector at `$17FA` holds `$1C00`, as the User Manual's section 4.1 sets
+it up. The sound is U2's PB7, the tape output music programs toggle.
+The pause menu's Panel page sets SST and the TTY/KB jumper, wires U3's
+PB7, its timer's interrupt, to IRQ, and plays a speaker on U3's PA0 in
+place of PB7.
+
+With `--tty`, or the jumper on the Panel page, the monitor talks to a
+teletype on its 20 mA loop instead, as the User Manual's section 2.6
+describes, at `--baud`'s rate, 9600 by default. The window shows the
+teletype's page, the host keys type on it, `Backspace` sends RUBOUT and
+`Down` LINE FEED, and the board echoes what's typed, as its hardware
+does. `--headless` puts the teletype on the terminal, until `Ctrl-C`.
+After a reset the teletype sends RUBOUT for the monitor to time, and
+then each character once the monitor has had time to take the last.
+
+The KIM-1 loads MOS papertapes, `.ptp` and `.pap` files as the
+monitor's `Q` command punches them, which start a KIM-1 without
+`kim1`, and `.bin` files of bare bytes, at `--load-address`. The
+program goes straight into RAM once the monitor runs, the NMI and IRQ
+vectors at `$17FA` and `$17FE` are set to `$1C00`, so ST and `BRK`
+stop it in the monitor, and the monitor starts it as you would: `AD`,
+the address and `GO` on the keypad, or the address, a space and `G` on
+the teletype. It starts where it loads unless `--start-address` says
+otherwise, and with `--no-autostart` the monitor stops at that address.
+`--tty-load` feeds a papertape through the monitor's `L` command
+instead, as a teletype's tape reader would. A program that loads over
+the monitor's own bytes at `$00EF`-`$00FF`, `$01F8`-`$01FF` or
+`$17E7`-`$17FF` can't load that way on the board either.
+
+The stock board has 1K of RAM at `$0000`-`$03FF`. `--ram 5k` fills
+`$0400`-`$13FF` with RAM, as a board on the expansion connector does,
+and `--ram expanded` adds `$2000`-`$DFFF` too, with the first 8K
+repeated at `$E000`-`$FFFF` for the vectors, as most software beyond
+the First Book of KIM needs. The KIM-1 saves snapshots as the others
+do, without VICE's modules.
+
+The pause menu's Datasette page is the KIM-1's cassette deck. INSERT,
+Quick open, a drop or `badline kim1 tape.wav` puts a `.wav` recording of a
+KIM tape in it, 8-bit or 16-bit, without starting anything, and DECK presses
+PLAY, RECORD or STOP. The monitor's LOADT, at `$1873`, reads the tape
+while it plays, and DUMPT, at `$1800`, writes it while it records, as the
+User Manual's appendix E describes. A recording goes over the tape from
+where the deck is, and STOP writes it to its `.wav`. With no tape in,
+RECORD puts a new one in the `tapes` folder in badline's data folder.
+
 ## Snapshots
 
 `F11` quicksaves the whole machine to the next of five slots in
@@ -375,8 +568,8 @@ newest, even after badline has quit and started again. badline also
 autosaves every two minutes of play, and the pause menu's Snapshots page
 saves under a name and loads any of them. Snapshots from badline 0.14.0
 on load in every later version. They use VICE's `.vsf` format: badline
-opens those x64sc and xpet save, and x64sc and xpet open badline's saved
-with `--vice`.
+opens those x64sc, xpet, xcbm2 and xcbm5x0 save, and they open
+badline's saved with `--vice`.
 See [doc/snapshots.md](doc/snapshots.md) for where they're kept, what
 they hold and how far the two agree.
 
@@ -458,6 +651,31 @@ listing them too:
 
 On the PET `Tab` is a key, since there are no joysticks to switch to.
 
+The CBM-II types the characters on the host's keys as the PET does, so
+Shift and `'` type `"` with the CBM-II's `SHIFT` and `'`. `F9` and
+`F10` keep opening the pause menu and muting, and `F12` is `RUN/STOP`
+in place of loading a snapshot. Its keys without a character are here,
+with the pause menu's Keyboard page listing them too:
+
+| CBM-II | Host |
+|--------|------|
+| `ESC` | `Escape` |
+| `RUN/STOP` | `F12` |
+| `CLR/HOME` | `Home` |
+| `INST/DEL` | `Backspace` |
+| `TAB` | `Tab` |
+| `CTRL` | `Ctrl` |
+| `F1`-`F8` | `F1`-`F8` |
+| `F9` / `F10` | `Alt` and `F9` / `F10` |
+| `CRSR ←` / `→` / `↑` / `↓` | `Left` / `Right` / `Up` / `Down` |
+| `←` | `_` or `` ` ``, and with `SHIFT` it's `\` |
+| Keypad | The keypad, and `Alt` and `0` for `00` |
+| `C=` | `Alt` and `C` |
+| `CE` | `Alt` and `E` |
+| `NORM/GRAPH` | `Alt` and `G` |
+| `OFF/RVS` | `Alt` and `R` |
+| `π` | `Alt` and `P` |
+
 `Tab` switches the keys between the C64 keyboard and the joysticks. The
 window title shows where they go, and any device plugged into a control
 port:
@@ -499,11 +717,11 @@ too.
 |------|---------------|
 | Snapshots | Quicksave, save under a name, load a named save, and the latest quicksaves and autosaves |
 | Drive 8 | The disk: insert, eject, the previous or next disk of its set, and whether it's writable |
-| Datasette | The tape: insert, eject, PLAY and REWIND |
+| Datasette | The tape: insert, eject, PLAY and REWIND. On the KIM-1, its deck's PLAY, RECORD and STOP too |
 | Expansion port | The cartridge's name: a `.crt`'s own, or a raw image's file name. Insert, remove, and its freeze button if it has one. On the VIC-20, the cartridge and the RAM expansion |
-| Ports | The device in each control port, and where the keys go. On the PET, Keyboard: where its keys are |
+| Ports | The device in each control port, and where the keys go. On the PET and the CBM-II's B series, Keyboard: where its keys are, and on the P500 also where its keys are while they type. On the KIM-1, Panel: SST, the TTY/KB jumper and U3's wiring |
 | Sound | Mute, and the SID's model |
-| Power | Reset, power cycle and quit, on a C128 its model and mode, and on a Plus/4 or a PET its model and RAM |
+| Power | Reset, power cycle and quit, on a C128 its model and mode, on a Plus/4 or a PET its model and RAM, and on a CBM-II its model, RAM, mains and KERNAL |
 
 INSERT opens a file browser. A disk's set is the `.m3u` or `.vfl` list it
 was opened from, or one in its folder that lists it. Without one, it comes
@@ -537,8 +755,9 @@ in cartridge 1 as it does from the command line.
 - **REU**: the 1700, 1764 and 1750 and bigger units up to 16M
   (`--reu`), with DMA timed against the VIC's bad lines and sprites.
 - **Datasette**: `.tap` playback.
-- **VIC-20**: the 6502, the PAL 6561 VIC-I with its picture and sound,
-  both 6522 VIAs, the keyboard, the joystick and RESTORE, RAM
+- **VIC-20**: the 6502, the PAL 6561 and NTSC 6560 VIC-I with its
+  picture and sound and the 6560's interlaced fields' timing, both 6522
+  VIAs, the keyboard, the joystick and RESTORE, RAM
   expansions up to 35K (`--ram`), cartridges, the datasette and the
   serial bus to device 8 (`badline vic20`).
 - **C128**: C128 mode with BASIC 7.0 and C64 mode, on the 8502 with its
@@ -557,9 +776,29 @@ in cartridge 1 as it does from the command line.
   with BASIC 1, 2 or 4, the discrete video and the 6545 CRTC on 40 and 80
   columns, both 6520 PIAs and the 6522 VIA, the graphics and business
   keyboards, the sound on the VIA's CB2, the 8096's 64K board, the
-  8296's 128K with its jumpers, RA4 and 4K character ROM, both
+  8296's 128K with its jumpers, RA4 and 4K character ROM, the
+  SuperPET's bank RAM, latches, ACIA, 6702 and 6809 with the Waterloo
+  languages loading from disk, both
   cassette ports and device 8 on the IEEE-488 bus through the KERNAL
-  traps, `.d80` and `.d82` among its disks (`badline pet`).
+  traps, `.d80` and `.d82` among its disks, and the D9060 and D9090
+  hard disks on `.d90` images (`badline pet`).
+- **CBM-II**: the B series' 610, 620, 710 and 720, with the 6509 at
+  2 MHz and its sixteen segments, 128K or 256K of RAM, BASIC 128 or 256
+  with KERNAL 04a or 03b, the 6845 CRTC on 80 columns, the SID, the
+  6526 CIA, the 6551 ACIA, both 6525 TPIs, the keyboard, the 50 or 60 Hz
+  mains, cartridges, and device 8 on the IEEE-488 bus through the
+  KERNAL traps (`badline cbm2`).
+- **P500**: the CBM 510, PAL and NTSC, with the B series' 6509, SID,
+  CIA, ACIA and TPIs at the VIC-II's clock, the VIC-II on the P500's
+  video bus, 128K of RAM, the keyboard, both joysticks, a 1351 mouse or
+  paddles on either port, and device 8
+  on the IEEE-488 bus through the KERNAL traps
+  (`badline cbm2 --model 510`).
+- **KIM-1**: the 6502 at 1 MHz, 1K, 5K or 53K of RAM, the two 6530 RRIOTs with
+  the monitor's and the tape routines' ROMs, the keypad and the six
+  multiplexed LED digits, the SST switch, ST and RS, PB7's sound, the
+  teletype on its 20 mA loop, papertape and `.bin` programs, and the
+  cassette as `.wav` (`badline kim1`).
 - **2031**: the PET's single drive, the 1541's board and DOS 2.6 on the
   IEEE-488 bus, with the bus's handshake on every line
   (`badline pet --true-drive`).

data/doc/media.md

@@ -15,8 +15,11 @@ the directory of any medium mounted there, as a 1541 does.
 The command channel answers `I`, `B-P` and `U1` block reads, which
 covers loaders that read blocks directly. On a writable disk image it
 also takes `SAVE` (with `@0:` to replace a file), files opened for
-writing or appending, `S` to scratch, `U2` and `B-W` block writes, and
-`B-A` and `B-F`. It doesn't rename, copy, format or validate disks.
+writing or appending, `S` to scratch, `U2` and `B-W` block writes,
+`B-A` and `B-F`, `N` to format the disk (or, without an ID, clear it),
+`R` to rename a file and `C` to copy or join files, with the reports a
+2031 or 8050 gives. It acts as a single drive, so it doesn't duplicate
+or copy whole disks (`D`, `C1=0`), and it doesn't validate disks.
 Loaders that upload their own code to the drive with `M-W` and `M-E`,
 and copy protection that reads raw GCR, won't work there, but do on a
 true drive.

data/doc/pinned-behaviour.md

@@ -50,6 +50,12 @@ only catches the rows that happen to move.
 - [`.sid` tune banking](#sid-tune-banking)
 - [PET discrete video](#pet-discrete-video)
 - [PET CRTC](#pet-crtc)
+- [CBM-II DRAM refresh](#cbm-ii-dram-refresh)
+- [6509 indirection segment](#6509-indirection-segment)
+- [KIM-1 single step](#kim-1-single-step)
+- [6809 dead cycles](#6809-dead-cycles)
+- [6809 interrupts, SYNC, CWAI, HALT and reset](#6809-interrupts-sync-cwai-halt-and-reset)
+- [6809 undocumented opcodes](#6809-undocumented-opcodes)
 
 ## CPU interrupt recognition
 
@@ -2214,6 +2220,21 @@ testprogs named.
   - Spec guard: *past an R1 it missed*, *repeats a row*, *past an R9 it
     missed* and *past an R6 it missed* in
     [`chips/crtc_spec.rb`](../spec/badline/chips/crtc_spec.rb).
+- The R5 lines of vertical adjust end no row: the line counter counts
+  them from 0 to R5, and passing R9 neither restarts it nor moves the
+  next row's start, so every adjust line starts where the last row left
+  off. The datasheets (MOS 6545-1, sheets 7-11) give R5 as extra scan
+  lines to complete the frame, apart from the R4 rows, and the address
+  sequence of their figure 4 moves on only per row. The 8032's 901474-04
+  editor dated 0283 sets R5 above R9 (16 lines against 9-line rows, 17
+  against 8 in graphics mode) and its 313-line frame runs on real 8032s,
+  so passing R9 can't end a row there, and the same compare moving the
+  start would be a row end that doesn't happen. xpet's black box agrees.
+  Only a frame whose display runs on through the adjust (R6 past R4)
+  shows it; no editor's does, and the PET has no light pen wired.
+  - Not pinned by a test row: no testbench row runs the 0283 editor.
+  - Spec guard: *with a vertical adjust longer than a row* in
+    [`chips/crtc_spec.rb`](../spec/badline/chips/crtc_spec.rb).
 - The picture is framed as xpet frames its screenshots: R1's characters
   in the middle of 704 dots (80 columns) or 384 (40); each character as
   far right as it comes after its line's horizontal sync, so lines whose
@@ -2229,3 +2250,171 @@ testprogs named.
     cycle dot for dot.
   - Spec guard:
     [`pet/crtc_video_spec.rb`](../spec/badline/pet/crtc_video_spec.rb).
+
+## CBM-II DRAM refresh
+
+- The B series' DRAM refresh takes the 6509's clock away for one cycle:
+  a counter of the CPU's cycles asks for a refresh once it reaches 20
+  and stops there, the refresh comes on the next opcode fetch, which it
+  holds off a cycle, and it clears the counter. A JMP loop, fetching
+  every third cycle, loses one cycle in 22. Read off sheet 3 of
+  schematic 8256043 (U89, U88 and U55: the request at count 20, gated
+  with SYNC, clocked by SPhi1, driving RDY and REFEN) and sheet 2 (REFEN
+  clearing the CPU's phi2 flip-flop U57).
+  - Pinned by `CBM2/cbm2-burnin.d80`'s 6526 timer test, which starts
+    timer A at $8888 and counts a 12-cycle loop until its interrupt
+    flag rises, and passes only at exactly 10 pages and $DB: 2,779
+    loops. Without the refresh badline counts 2,895, and stealing a
+    cycle in every 24 or 25, or five a line, misses by one or more.
+    xcbm2, which steals nothing, shows the cell BAD.
+  - Spec guard: *takes a cycle for the DRAM's refresh* in
+    [`cbm2_spec.rb`](../spec/badline/cbm2_spec.rb).
+
+## 6509 indirection segment
+
+- LDA (zp),Y and STA (zp),Y take the indirection segment for every
+  access at the address they index: the dummy read before the data, as
+  well as the data. The opcode and the zero-page pointer stay in the
+  execution segment.
+  - Pinned by `CBM2/cbm2-burnin.d80`'s 6526 TOD test. It sets the time
+    with STA (zp),Y into segment 15, hours first, polls the tenths until
+    they leave the value written, then checks the tenths, seconds,
+    minutes and hours against the time one tenth on, which leaves the
+    clock latched. In the run that steps the seconds from 01:00:01.9,
+    each step starts latched at the previous step's result, tenths 0,
+    and with that latch held the first poll reads the stale 0, matches
+    the expected tenths and fails on the live seconds, one short. The
+    store's dummy read of the tenths releases the latch before they are
+    written. With the dummy read in the execution segment it reads RAM,
+    and the burn-in's grid grades $FF.
+  - The CIA keeps its latch through writes: `CIA/ciavarious/cia15.prg`'s
+    test B sets X:59:59.8 with absolute stores, hours first, after
+    reading the hours, and its reference has the hour unchanged for odd
+    X, where the first wait reads the stale latched tenths 0 and falls
+    through. A write to the tenths that released the latch fails it.
+  - Spec guard: *makes STA (zp),Y's dummy read in the indirection
+    segment* in [`cbm2/cpu_spec.rb`](../spec/badline/cbm2/cpu_spec.rb).
+
+## KIM-1 single step
+
+- With the SST switch on, the board pulls NMI through each opcode fetch
+  outside K7 ($1C00-$1FFF and its mirrors), and the CPU takes it at the
+  end of the instruction that fetch starts, a 2-cycle one included: the
+  board raises the NMI latch ahead of the fetch cycle's poll, so the
+  sample the boundary commits, the one from the second-to-last cycle,
+  holds it. The pull on the cycle that starts the interrupt sequence is
+  taken up by the same NMI.
+  - Pinned by the KIM-1 User Manual's figure 5.6, which single-steps the
+    sample program of figure 5.4 from $0200: the display shows 0202 after
+    the first GO, the 2-cycle LDA #$01, and 020F after TAX. With the
+    latch raised a cycle later, after the fetch cycle has polled, NMI
+    waits an instruction more and the first GO shows 0205.
+  - The monitor's display scan, SCANDS ($1F1F) and the key scan AK
+    ($1EFE) in its idle loop, repeats every 4,258 cycles, and lights the
+    six digits 676, 687, 676, 687, 676 and 657 cycles each. That follows
+    from the ROM and the 6502 core's cycle counts, which SingleStepTests
+    checks, not from a test of the board.
+  - Spec guards: *takes the NMI single-step pulls right after a 2-cycle
+    instruction* in [`kim1/cpu_spec.rb`](../spec/badline/kim1/cpu_spec.rb),
+    and *figure 5.6* and *scans the six digits every 4,258 cycles* in
+    [`kim1_spec.rb`](../spec/badline/kim1_spec.rb).
+
+## 6809 dead cycles
+
+6809 dead cycles follow the MC6809E flowcharts, not MAME. The
+neetandev/m6809 vectors (`rake test`) are MAME's, and on these dead
+("Don't Care") cycles they read another address than Figure 17 of the
+MC6809E datasheet gives. The core reads the datasheet's address, and the
+runner checks each of these cycles against it, through the rules in
+[`m6809_divergences.rb`](../test/support/m6809_divergences.rb). Every
+other cycle, and every cycle count but X18's, is the vectors'.
+
+- A read-modify-write (NEG, COM, LSR, ROR, ASR, ASL, ROL, DEC, INC, CLR
+  and the undocumented aliases, in memory) reads `$FFFF` between its read
+  and its write, where the vectors read PC. Pinned by MC6809E Fig. 17
+  sheet 5 and the datasheet's DEC extended example.
+- ADDD, SUBD, CMPD, CMPX, CMPY, CMPU, CMPS and the undocumented XADDD and
+  XADDU end on a dead read of `$FFFF`, where the vectors read PC. Pinned
+  by MC6809E Fig. 17 sheet 5.
+- JSR's first dead cycle after its address reads the subroutine's
+  address, where the vectors read PC. BSR and LBSR read it on the dead
+  cycle before their last `$FFFF`, where the vectors read `$FFFF`. Pinned
+  by MC6809E Fig. 17 sheets 1 and 5 and the datasheet's LBSR example.
+- RTS ends on a dead read of `$FFFF`, where the vectors read the stack.
+  Pinned by MC6809E Fig. 17 sheet 2.
+- TSTA and TSTB read NNNN+1 after the opcode, as every one-byte inherent
+  opcode does, where the vectors read `$FFFF`. Pinned by MC6809E Fig. 17
+  sheet 2.
+- Indexed: an 8-bit offset from R is followed by a dead read of `$FFFF`,
+  where the vectors read PC. A 16-bit offset from R or PC, a D offset and
+  extended indirect read NNNN+4 (NNNN+5 after a prefix) on the cycle
+  after the offset, where the vectors read `$FFFF`. Pinned by MC6809E
+  Fig. 17 sheet 4.
+- Spec guard: *dead cycles* in
+  [`m6809_spec.rb`](../spec/badline/chips/m6809_spec.rb).
+
+## 6809 interrupts, SYNC, CWAI, HALT and reset
+
+The vectors leave these out. The core follows the MC6809E datasheet, and
+reyco2000's `6809_interrupt_test` and `6809_cycle_test`
+(`rake test`) pass on it.
+
+- The lines are sampled once a cycle, and an instruction boundary sees the
+  sample of two cycles before: IRQ or FIRQ asserted on an instruction's
+  next-to-last cycle is taken once it ends, and on its last cycle only
+  after the next instruction. NMI is an edge, latched until taken, and
+  ignored until a program loads S after reset (LDS, LEAS, TFR or EXG
+  into S, PULU S). Pinned by MC6809E Figs. 8 and 9.
+- IRQ and NMI take 19 cycles from the cycle that would have fetched the
+  opcode: PC twice, `$FFFF`, the 12 bytes from PC low to CC with E set,
+  `$FFFF`, the vector, `$FFFF`. FIRQ takes 10, stacking PC and CC with E
+  clear. The masks take effect as the vector's first byte is read. Pinned
+  by MC6809E Figs. 8 and 9.
+- SYNC reads NNNN+1 and then leaves the bus alone until any interrupt line
+  is asserted, masked or not, and for one cycle more. A masked interrupt
+  goes on to the next instruction; an unmasked one runs its usual
+  sequence. Pinned by MC6809E Fig. 16 and Fig. 17 sheet 2.
+- CWAI reads its operand, NNNN+2 and `$FFFF`, ANDs CC with the operand,
+  sets E, stacks all 12 bytes, then reads `$FFFF` until an interrupt it
+  may take comes, and reads that interrupt's vector and `$FFFF`: 20
+  cycles when the interrupt is already there. Pinned by MC6809E Fig. 17
+  sheet 2.
+- HALT stops the CPU at the next instruction boundary, sampled as IRQ is,
+  and leaves the bus alone until it is released.
+- After RESET the CPU reads `$FFFE` twice, the vector at `$FFFE` and
+  `$FFFF`, and `$FFFF`, and fetches its first opcode on the sixth cycle.
+  It masks FIRQ and IRQ and clears DP. Pinned by MC6809E Fig. 6.
+- Spec guard: [`m6809_spec.rb`](../spec/badline/chips/m6809_spec.rb).
+
+## 6809 undocumented opcodes
+
+The undocumented opcodes follow David Banks' "Undocumented 6809
+Behaviours" (github.com/hoglet67/6809Decoder/wiki), which was checked on
+real chips, where it and the vectors (MAME's) disagree. The runner checks
+these cases against the rules in
+[`m6809_divergences.rb`](../test/support/m6809_divergences.rb).
+
+- X18 (`$18`) takes 3 cycles, where the vectors take 2, and sets V to
+  (C AND bit 0) OR (Z AND bit 2) of the byte after the opcode, where the
+  vectors take Z alone. Banks doesn't give the third cycle's address; the
+  core reads `$FFFF`. Pinned by Banks, X18.
+- XADDU adds the operand to U OR `$FF00`, where the vectors add U. Pinned
+  by Banks, XADDU.
+- DAA sets V to C XOR bit 7 of the result, where the vectors (and the
+  datasheet) clear it. Pinned by Banks, Undefined values of the Overflow
+  Flag.
+- The stores immediate set N and clear Z and V when prefixed. Unprefixed,
+  N, Z and V hang on the group of the instruction before (CMPA and BITA;
+  LDA and LDD; the A arithmetic and logic; the A shifts, DEC, INC, NEG,
+  COM, TSTA, DAA and SUBD; SEX; the 16-bit compares and XADDD/XADDU; LEA;
+  anything else). The 16-bit ones also clear Z unless the register's low
+  byte is 0. The vectors set N and Z from the register and clear V. The
+  vectors start every case after no instruction, the "anything else"
+  group: N set, Z and V clear. Pinned by Banks, Store Immediate and Flags
+  for unprefixed Store Immediate.
+- What the vectors leave out also comes from Banks: `$14`, `$15` and `$CD`
+  read on from PC, a byte a cycle, until reset; a chain of `$10` and `$11`
+  prefixes takes the first, a cycle for each; an opcode page 2 or 3
+  doesn't define runs as on page 1, a cycle later.
+- Spec guard: *the flags of the unprefixed stores immediate* in
+  [`m6809_spec.rb`](../spec/badline/chips/m6809_spec.rb).