badline 0.12.1 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8872c5d5117a691aa38d054acd5dd7e84f7abf737c977a2dc309c6dc3072381d
-  data.tar.gz: fa4f4e5b3729989c78443f73bd655c2083555d62a8d3ee45437d147bfe0e5fb8
+  metadata.gz: 2a074ca0626351bec4132e06bc5e4ab951f7a4b18cf9e78ddc3c16adfd4194b8
+  data.tar.gz: 878629423f450e6c6440649b00d87646c1ff59d5ccb99801d5909fedc14f9108
 SHA512:
-  metadata.gz: d278ba0e0341242af3e1782a8c003bc4cbdb1594be434021b5bbccae126ddf12dd89ffa0520dd615075a77f89b1285595d2101868db0e6679b69130586ed210c
-  data.tar.gz: 5dabb1d53a29dc43b619f90abd67495ab3847d3ba8d8f89275d45f276aac4fbe3ca37a4963f048e300e88cd50228b35bd39da7efbd431f46527b893b1c4bd95c
+  metadata.gz: 8eb5553980d187ccafd1ac4906b8a3d7fb6a80a8219375ef872f208411c362bf3724e721946ed166b91595177ce3adf38632e2b69008d9a4082032239cfcb697
+  data.tar.gz: dcb3a6ab34cceff4e85b56d09c2e38eaeab8350f57928c07e23ba7c6f5de38b32a88a0735802a2d196bb2ccf89a6a058579a47daf85ca8ac275f5b6bce90a975

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.13.0](https://github.com/elektronaut/badline/compare/v0.12.1...v0.13.0) (2026-10-11)
+
+
+### Features
+
+* read and write memory through the machine ([0a71be9](https://github.com/elektronaut/badline/commit/0a71be914fda736bdc10c320b86cf9e0bf91b05b))
+
+
+### Bug Fixes
+
+* take dead keys such as ´ on a Mac as key presses ([44bc087](https://github.com/elektronaut/badline/commit/44bc087a0def79a3d1f8837d7e479297aca7094f))
+
+
+### Performance Improvements
+
+* type the values a snapshot restores ([71e6e62](https://github.com/elektronaut/badline/commit/71e6e6229880d413adf2071a69263f7930536157))
+
 ## [0.12.1](https://github.com/elektronaut/badline/compare/v0.12.0...v0.12.1) (2026-10-10)
 
 

data/CLAUDE.md

@@ -6,42 +6,61 @@ This file covers how to work on the code.
 
 ## Orientation
 
-`lib/badline/` holds one file per chip or subsystem, and namespaced groups
-live in subdirectories:
-
-- **Machine**: `computer.rb` clocks everything once per cycle (`cycle!`:
-  VIC, both CIAs, SID and the datasette, then the CPU unless the VIC holds
-  BA low). `address_bus.rb` handles banking and page-table dispatch
-- **CPU**: `cpu.rb`, `instruction.rb` and `instruction_set/`, plus
-  `interrupts.rb`
-- **VIC-II**: `vic.rb` and `vic/`, covering the sequencer, sprites, graphics
-  modes, border and register timing
-- **CIA**: `cia.rb` and `cia/` (timers, serial), plus `time_of_day.rb`
-- **REU**: `reu.rb` and `reu/`, the RAM Expansion Unit's registers and
-  its DMA, which `Computer#cycle!` clocks in place of the CPU while it
-  holds the bus
-- **SID**: `sid.rb` and `sid/`. `audio/` plays and renders tunes for
-  `badline-ruby --headless` and `--audio-out`
+`lib/badline/` is grouped by namespace, and a constant's path follows its
+directory: `chips/vic.rb` is `Badline::Chips::VIC`.
+
+- **Machine**: `c64.rb` (`Badline::C64`) clocks everything once per cycle
+  (`cycle!`: VIC, both CIAs, SID and the datasette, then the CPU unless
+  the VIC holds BA low). `c64/` holds the rest of the C64's board:
+  `c64/bus.rb` handles banking and page-table dispatch, and
+  `c64/banked_ram.rb` and `c64/banked_ram/` the +60K and +256K boards
+  that bank in extra RAM through `$D100`. `vic20.rb` and `vic20/`, and
+  `c128.rb` and `c128/`, are the other two families, and `machine.rb`
+  builds each by name. Every family reads and writes memory as its CPU
+  sees it with `peek` and `poke`
+- **CPU**: `chips/cpu.rb` and `chips/cpu/`: the 6502 core
+  (`Chips::CPU::Core`, which each family's and each drive's CPU
+  includes), `instruction.rb` and `instruction_set/`, `interrupts.rb`,
+  `traps.rb` and the 6510's I/O port, `port.rb`. `chips/z80.rb` is the
+  C128's Z80
+- **VIC-II**: `chips/vic.rb` and `chips/vic/`, covering the sequencer,
+  sprites, graphics modes, border and register timing. `chips/vic_i.rb`
+  is the VIC-20's VIC-I and its sound, and `chips/vdc.rb` the C128's VDC
+- **CIA**: `chips/cia.rb` and `chips/cia/` (timers, serial and the TOD
+  clock, `time_of_day.rb`). `chips/via.rb` is the 6522 of the VIC-20 and
+  the drives
+- **REU**: `c64/reu.rb` and `c64/reu/`, the RAM Expansion Unit's
+  registers and its DMA, which `C64#cycle!` clocks in place of the CPU
+  while it holds the bus
+- **SID**: `chips/sid.rb` and `chips/sid/`. `audio/` plays and renders
+  tunes for `badline-ruby --headless` and `--audio-out`, and `sid_tune/`
+  reads `.sid` files, the HVSC's song lengths and its STIL
 - **Media and host I/O**: `storage/` (disk, tape and cartridge image
-  formats), `cartridge/` (mappers), `kernal_trap/` (the LOAD/SAVE and IEC
-  traps that stand in for a drive), `media.rb` (attach and autostart),
-  `datasette.rb`, and `input/` (the mouse and paddles)
+  formats), `c64/cartridge/` (mappers), `kernal_trap/` (the LOAD/SAVE
+  and IEC traps, and `kernal_trap/dos/`, the virtual DOS that stands in
+  for a drive), `media.rb` (attach and autostart), `drives/` (the true
+  1541, 1571 and 1581, the engine they share, the serial bus and the
+  datasette), and `input/` (the keyboard, joysticks, control ports,
+  mouse and paddles)
 - **Front end**: `frontend/`, the SDL window both builds run (app loop,
   screen, pacer, sound, controls, gamepads, snapshots), in Spinel's
   subset, over the one binding in `sdl.rb` (`ffi.rb` implements it on
   CRuby)
 - **Native**: `native/` holds the native `badline`, the core and the
   front end compiled with Spinel (`rake native:build`, `native/README.md`).
-  `spinel/` holds the Spinel test harnesses
+  `spinel/` holds the Spinel test harnesses, and `support/` the
+  checkpoints they and `bin/machine_diff` digest a machine with, which
+  stay out of the core
 
-Timing-critical code lives in `cpu`, `interrupts`, `vic`, `cia` and `sid` and
-in the order `Computer#cycle!` clocks them. Changes there move the test
+Timing-critical code lives in `chips/` (`cpu`, `vic`, `cia` and `sid`) and
+in the order `C64#cycle!` clocks them. Changes there move the test
 suites below. `frontend/` changes move none of them.
 
 Namespaced groups live in `lib/badline/<namespace>/`, with a sibling
 `lib/badline/<namespace>.rb` that requires the members, directly or through
 other members. `lib/badline.rb`
-requires only the namespace file.
+requires only the namespace file. `chips/` and `drives/` have no sibling
+file: `core.rb` requires their members one by one.
 
 ### Oracles
 
@@ -54,7 +73,7 @@ requires only the namespace file.
 | VICE testbench | `bin/testbench <subtree>` | `VICII/`, `CIA/`, `interrupts/`, `CPU/`, cartridges with `--carts`, the true 1541 drive with `--drive`, the VIC-20 with `--vic20`, the C128 in C64 mode with `--c128c64`, in C128 mode with `--c128`, and its Z80 with `--c128-z80` |
 | VICE SID testprogs | `bin/sidtests` | SID |
 | Drive scenarios | `bin/drive_scenarios` | The true 1541 running the DOS ROM: save, format, the error channel, idle, write protect and autostart |
-| CIA offline grids | `bundle exec rspec --tag slow spec/badline/cia` | CIA timers and shift register, against a bare CIA in about 2 min |
+| CIA offline grids | `bundle exec rspec --tag slow spec/badline/chips/cia` | CIA timers and shift register, against a bare CIA in about 2 min |
 
 The CIA offline grids replay Lorenz's `cia1ta` and `cia1tb` sweeps (about
 8 s) and the `cia-sdr-icr` loop for every timer A latch (about 2 min),
@@ -67,21 +86,23 @@ documents the baseline format, the suites and how rows are compared.
 
 `bin/machine_diff <scenario|media> --against <rev>` checks that a change
 leaves emulation alone. It runs the scenario on this tree and on `<rev>`'s
-`lib/` side by side, digests the CPU, RAM, VIC, CIAs and SID every million
-cycles, and names the first component that differs. Use it for refactors
-and speed work.
+`lib/` side by side, digests each chip every million cycles (the CPU, RAM,
+VIC, CIAs and SID, the VIC-20's VIAs and sound, the C128's VDC, MMU and
+Z80), and names the first component that differs. It builds a C64 unless
+`--family vic20` or `--family c128` (with `--mode c64|c128`) says
+otherwise. Use it for refactors and speed work.
 
 ## Driving the emulator headlessly
 
 `exe/badline-ruby <media>` opens the SDL window, which is no use for checking
-work. Drive a `Badline::Computer` from Ruby instead, as the `bin/` runners do:
+work. Drive a `Badline::C64` from Ruby instead, as the `bin/` runners do:
 
 ```ruby
-computer = Badline::Computer.new
+computer = Badline::C64.new
 Badline::Media.attach(computer, path)  # PRG, disk, tape, CRT or directory; autostarts
 computer.on_init { computer.type_text("print 6*7\r") }  # after boot (~2.5M cycles)
 3_500_000.times { computer.cycle! }
-computer.address_bus.peek(0x0400)      # screen RAM starts at $0400
+computer.peek(0x0400)                  # screen RAM starts at $0400
 ```
 
 - `computer.capture_output` traps CHROUT and records what the machine prints
@@ -196,7 +217,7 @@ the rows your change can't reach tell you nothing about it.
   `(suite)` row too. Explain every moved row in the pull request. Never
   re-record just to make a diff go away
 - For a change whose reach you can't bound to a set of filters, such as
-  reordering `Computer#cycle!` or changing the LOAD trap every suite loads
+  reordering `C64#cycle!` or changing the LOAD trap every suite loads
   through, push and let CI run the suites
 - The Regression workflow runs the suites on CRuby, started by hand from
   the Actions tab, for a person checking that CRuby and Spinel agree.
@@ -248,6 +269,13 @@ you change code a pinned rule governs, re-derive the rule against its test
 and update the doc if the rule moves. A green suite alone isn't enough,
 because the suite can stay green while the rule breaks.
 
+## Rubocop
+
+The Metrics limits in `.rubocop.yml` are house limits, set with headroom
+above the largest class, module and method in the tree. A change that needs
+more should raise the limit in the same pull request and say why, rather
+than split a class or shorten an unrelated method to fit.
+
 ## Issues and pull requests
 
 Before filing an issue or opening a pull request, read CONTRIBUTING.md and follow it. Use the exact headings from its skeletons. Report only what you observed or verified, and don't include hypotheses about causes. Open an issue before writing non-trivial code; only changes with one obvious fix (typos, broken links, clear-cut fixes) go straight to a pull request.

data/README.md

@@ -22,7 +22,7 @@ It comes in two builds of the same emulator:
   sound, so it's the one to play games with.
 - **`badline-ruby`**, which comes with the Ruby gem and runs on CRuby. It
   runs slower than a real C64, so its sound is off by default. The gem is
-  also a library, which runs a `Badline::Computer` from Ruby without a
+  also a library, which runs a `Badline::C64` from Ruby without a
   window.
 
 ## Installation

data/doc/library.md

@@ -1,16 +1,16 @@
 # Using badline from Ruby
 
-The gem is also a library, which runs a `Badline::Computer` from Ruby
+The gem is also a library, which runs a `Badline::C64` from Ruby
 without a window.
 
 ```ruby
 require "badline"
 
-computer = Badline::Computer.new
+computer = Badline::C64.new
 Badline::Media.attach(computer, "game.d64")         # attaches and autostarts
 computer.on_init { computer.type_text("print 6*7\r") } # once the machine has booted
 3_500_000.times { computer.cycle! }
-computer.address_bus.peek(0x0400)                   # screen RAM starts at $0400
+computer.peek(0x0400)                               # screen RAM starts at $0400
 ```
 
 [media.md](media.md) covers attaching and swapping media, and
@@ -18,7 +18,7 @@ computer.address_bus.peek(0x0400)                   # screen RAM starts at $0400
 
 ## Building a machine
 
-`Badline::Computer.new` builds the default machine: a PAL C64 with the
+`Badline::C64.new` builds the default machine: a PAL C64 with the
 6569 VIC-II, 6526 CIAs and a 6581 SID. Its keywords build others, and
 `Badline::Model.named("c64c")` gives the ones `--model` names for each
 model (`Badline::Model::ALL`):
@@ -41,11 +41,11 @@ model (`Badline::Model::ALL`):
 - `reu: 512` plugs in a RAM Expansion Unit of that many K.
 - `kernal: :sx64` fits the SX-64's KERNAL, and `datasette: false`
   leaves the cassette port empty, so inserting a tape raises
-  `Badline::Datasette::Missing`. The SX-64 has both.
+  `Badline::Drives::Datasette::Missing`. The SX-64 has both.
 - `kernal: :pet64` fits the PET 64's KERNAL, and `board: :pet64` its
   green monochrome monitor: the VIC's `palette` is
-  `Badline::VIC::GREEN_PALETTE`, each colour's luminance in green. The
-  PET 64 has both.
+  `Badline::Chips::VIC::GREEN_PALETTE`, each colour's luminance in
+  green. The PET 64 has both.
 - `kernal: :gs` fits the C64GS's BASIC and KERNAL, and `board: :gs` its
   case, which has no keyboard: `computer.keyboard` takes no keys. The
   C64GS has both, and no datasette.
@@ -68,7 +68,7 @@ Am29F040 EAPI on attach, as VICE does. Flash writes stay in memory and
 are lost when the emulator quits: the `.crt` file is never overwritten.
 
 A GEO-RAM takes the expansion port, so it can't sit alongside a
-cartridge: `computer.attach_cartridge(Badline::Cartridge::GeoRAM.new(size: 512))`.
+cartridge: `computer.attach_cartridge(Badline::C64::Cartridge::GeoRAM.new(size: 512))`.
 Its contents are lost when the emulator quits.
 
 ## ROMs
@@ -79,5 +79,5 @@ directory that holds `kernal.rom`, `basic.rom` and `character.rom`, plus
 `kernal-sx64.rom` for the SX-64, `kernal-pet64.rom` for the PET 64,
 `c64gs.rom` for the C64GS and `eapi/eapi-am29f040-14` if you
 attach EasyFlash cartridges.
-`Badline.rom_path = dir` does the same before a `Badline::Computer` is
+`Badline.rom_path = dir` does the same before a `Badline::C64` is
 built, and `nil` restores the bundled set.