badline 0.17.0 → 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`, the PET and CBM, as `badline pet`, and the CBM-II, the B series and the P500, as `badline cbm2`. 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:
 
@@ -71,8 +71,8 @@ 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`,
-[The PET](#the-pet) for `badline pet` and [The CBM-II](#the-cbm-ii) for
-`badline cbm2`.
+[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.
@@ -83,11 +83,11 @@ 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 or the CBM-II, or for a `.d80` or `.d82` an 8050 or 8250. 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` |
+| `--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) |
@@ -97,7 +97,12 @@ differences noted in the table. `--help` lists the options for either.
 | `--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, the PET and the CBM-II have models of their own: see their sections |
-| `--ntsc` | Run an NTSC C64, as `--model ntsc` does |
+| `--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) |
@@ -138,6 +143,8 @@ 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 |
@@ -158,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
@@ -307,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.
 
@@ -341,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
@@ -356,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
@@ -396,7 +460,8 @@ 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`. A 610's first `LOAD` from a
+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`.
@@ -420,6 +485,81 @@ 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
@@ -577,9 +717,9 @@ 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 and the CBM-II's B series, Keyboard: where its keys are, and on the P500 also where its keys are while they type |
+| 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, on a Plus/4 or a PET its model and RAM, and on a CBM-II its model, RAM, mains and KERNAL |
 
@@ -615,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
@@ -635,9 +776,12 @@ 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
@@ -650,6 +794,11 @@ in cartridge 1 as it does from the command line.
   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/pinned-behaviour.md

@@ -52,6 +52,10 @@ only catches the rows that happen to move.
 - [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
 
@@ -2290,3 +2294,127 @@ testprogs named.
     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).