feat(serial): model disconnected multiplayer configuration

docs/architecture.md

@@ -65,11 +65,13 @@ The repository is a Cargo workspace with three crates:
 | `crates/gba-core/tests/pulse_sound/channel2.rs` | Channel 2 mapping, register gaps, independent state, shared clocks, and sum-before-rounding mixing |
 | `crates/gba-core/tests/direct_sound.rs` | FIFO lanes/reset, signed mixing, timer selection, DMA refill, and HALT/STOP |
 | `crates/gba-core/src/memory/audio_step_tests.rs` | Audio access phases, shadow validation, and CPU/DMA failure rollback |
-| `crates/gba-core/src/io/serial.rs` | Disconnected normal serial shifter, internal clocks, external waiting, GPIO latches, and live-write validation |
+| `crates/gba-core/src/io/serial.rs` | Disconnected normal serial shifter, internal clocks, external waiting, idle multiplayer registers, GPIO latches, and live-write validation |
 | `crates/gba-core/tests/inactive_devices.rs` | Device masks, wave RAM, GPIO pull-ups, serial data, and failed CPU/DMA write isolation |
 | `crates/gba-core/tests/serial_control.rs` | RCNT mode gating, inactive bits, byte/halfword lanes, CPU/DMA diagnostics, and interrupt isolation |
 | `crates/gba-core/tests/serial_external.rs` | External-clock waiting, cancellation, HALT/STOP, ARM/Thumb/DMA starts, and atomic diagnostics |
 | `crates/gba-core/tests/serial_internal.rs` | Nominal bit edges, widths/rates, cancellation, completion IRQs, HALT/STOP, and live-write limits |
+| `crates/gba-core/tests/serial_multiplayer.rs` | Disconnected child status, receive/send lanes, mode aliases, ignored child start, HALT/STOP, and ARM/Thumb/DMA access |
+| `crates/gba-core/src/memory/multiplayer_step_tests.rs` | Multiplayer mode changes at normal completion, block-transfer preflight, staged reads, and atomic diagnostics |
 | `crates/gba-core/src/memory/serial_step_tests.rs` | Serial bus-phase observations, preflight validation, DMA, IF ordering, capture isolation, and rollback |
 | `crates/gba-core/src/io/timer_step.rs` | Staged timer/audio/serial state, divider phase, timer/serial IF bits, and sound refill requests at ordered CPU/DMA bus phases |
 | `crates/gba-core/src/memory/timer_step_tests.rs` | Timer access phases, coherent lanes, cascades, IF ordering, rollback, DMA, idle, and clock ownership |

docs/hardware/cartridge.md

@@ -39,7 +39,8 @@ Both modes call `bios::boot` with the loaded bytes.
 The [original BIOS replacement](bios.md) executes its minimal boot before entering `0x08000000` in ARM System mode.
 There is no command-line option for external BIOS files.
 Unsupported services remain diagnostics. RegisterRamReset now accepts sound/serial reset flags, including `r0=0xff`, within the initialization subset.
-Active sound and serial transfers still fail with device-specific diagnostics; accepting reset does not establish game compatibility.
+Supported [sound](audio.md) and [serial](serial.md) behavior extends beyond reset, but remaining unsupported operations still produce diagnostics.
+Accepting reset does not establish game compatibility.
 
 ## Terminal execution limits and results
 

docs/hardware/serial.md

@@ -1,8 +1,8 @@
 # Disconnected serial subset
 
-The core supports disconnected normal-mode transfers, external-clock waiting, and general-purpose pins.
+The core supports disconnected normal-mode transfers, external-clock waiting, idle multiplayer configuration, and general-purpose pins.
 Internal clocks shift pulled-high input at nominal GBA rates. No link partner is emulated.
-External clock edges, multiplayer, UART, Joybus communication, and GPIO interrupts remain unsupported.
+External clock edges, connected multiplayer transfers, UART, Joybus communication, and GPIO interrupts remain unsupported.
 Unsupported activity remains diagnostic rather than reporting a fabricated completion.
 
 ## Registers
@@ -13,13 +13,13 @@ Unsupported activity remains diagnostic rather than reporting a fabricated compl
 - `SIOCNT` at `0x04000128` retains normal 8/32-bit mode, IRQ configuration, clock selection, and the output-data bit.
   The retained mask is `0x508b`. The disconnected serial input is high, except when a general-purpose output drives it low.
   Start bit 7 requests a transfer. Bit 0 selects external or internal clock; bit 1 selects the internal rate.
-  Completion or software cancellation clears start. Multiplayer/UART mode bit 13 remains unsupported.
+  Completion or software cancellation clears start. Multiplayer uses the separate format described below; UART remains diagnostic.
 - `RCNT` at `0x04000134` retains mode bits, interrupt configuration, output latches, and pin directions with mask `0xc1ff`.
   With bit 15 clear, bits 8 and 14 are writable latches without GPIO interrupt or Joybus effects.
   With bit 15 set, bit 14 selects Joybus; otherwise bit 8 enables GPIO interrupts. Both active configurations remain diagnostic.
   In general-purpose mode, each input reads high through its pull-up. Each output reads its output latch.
   `RCNT=0x8000` therefore reads back as `0x800f`, not `0x8000`.
-  Normal-mode low-byte pin readback remains unmapped rather than guessed.
+  Normal and multiplayer low-byte pin readback remains unmapped rather than guessed.
 - `JOYCNT` permits clearing already-empty status flags. Joybus interrupt enable is unsupported.
 - `JOY_RECV` and `JOY_TRANS` permit only zero writes and zero readback for reset initialization.
   Nonzero writes return an explicit error. Joybus status and data-transfer side effects are not implemented.
@@ -95,6 +95,52 @@ The period arithmetic follows documented GBA rates. Activation phase, mid-transf
 No external pin waveform, cable, connected partner, or serial-device protocol is implemented.
 Original tests cover individual shifts, batching, cancellation, IRQ gating, HALT/STOP, bus phases, DMA, capture independence, and rollback.
 
+## Disconnected multiplayer configuration
+
+With RCNT bit 15 clear, SIOCNT mode bits 12–13 equal to `2` select multiplayer format.
+The retained control mask is `0x6f03`: baud selection, unused writable bits 8–11, mode, and IRQ enable.
+This subset models an idle unit without a cable, not a parent with missing players.
+
+- SI reads high in status bit 2, identifying a child rather than a parent.
+- SD reads high in bit 3 because the local idle output is high. This does not establish connected peers.
+- ID bits 4–5 read a deterministic zero placeholder. Hardware does not define the ID before a completed transfer.
+  Zero must not be interpreted as an assigned parent role; SI determines that role.
+- Error bit 6 and busy bit 7 remain clear. No parent supplies the clock that starts a child transfer.
+- Start is read-only for a child. Writing it cannot start a transfer, reset receive data, or request an IRQ.
+
+All baud settings retain this idle behavior. Elapsed cycles, DMA, and repeated start writes cannot create a linked transfer.
+No multiplayer event can wake HALT. STOP retains the configuration without advancing clocks.
+When GPIO is selected, SI/SD status follows the existing GPIO pin model; multiplayer transfers still cannot run.
+RCNT low-byte samples remain unmapped outside GPIO mode. Floating clock-pin timing is not guessed.
+
+### Multiplayer data registers
+
+`SIOMLT_SEND` at `0x0400012a` is a 16-bit latch in multiplayer format.
+It shares its low byte with normal-mode SIODATA8. Normal upper-byte reads return zero and writes are ignored.
+Normal 8-bit shifts change only the low byte. The hidden upper byte survives mode changes in this bounded model.
+A word write to SIOCNT selects the final format before applying both SEND lanes.
+
+`SIOMULTI0` through `SIOMULTI3` occupy halfwords at `0x04000120`, `0x04000122`, `0x04000124`, and `0x04000126`.
+The first two alias SIODATA32. The last two are accessible only with multiplayer format selected, including under GPIO.
+Byte, halfword, and word accesses preserve independent lanes.
+Receive latches start at zero under the synthetic reset policy and retain data across mode changes.
+Selecting multiplayer or writing child start does not replace them with `0xffff`, local SEND data, or invented peer data.
+
+Receive writes follow GBATEK's R/W register description. The pinned mGBA implementation instead leaves these writes unhandled.
+Physical receive-write behavior, reset values, and hidden upper-byte retention have not been independently measured.
+These are bounded register-model choices, not evidence of successful reception or full firmware-reset accuracy.
+
+### Validation and limits
+
+Mode changes use staged serial state at the bus-completion phase.
+A high-byte mode write cannot silently cancel a busy normal transfer through multiplayer's read-only start mask.
+Clear start explicitly, or wait for normal completion. A completion IRQ already requested remains pending after mode selection.
+Block-store preflight observes earlier mode writes and rejects later invalid accesses without committing preceding writes.
+
+Original tests cover control masks, all baud selections, register lanes, aliases, GPIO, HALT/STOP, and ARM/Thumb/DMA stores.
+Bus-phase tests cover normal completion, retryable diagnostics, block loads/stores, and mode-dependent staged reads.
+There is no parent, cable topology, external clock input, multiplayer timeout, or linked-game compatibility claim.
+
 ## BIOS reset
 
 RegisterRamReset always clears the low halfword of SIODATA32, even without bit 5.
@@ -102,6 +148,8 @@ The upper halfword remains unchanged in this functional subset.
 With bit 5 selected, the firmware clears SIOCNT and SIODATA8, selects general-purpose inputs, and clears the supported Joybus reset registers.
 It uses ordinary ARM bus stores, not a host-side reset bypass.
 Clearing SIOCNT cancels a pending external-clock request. Unselected serial reset leaves that request pending.
+The firmware writes SIODATA8 after selecting normal format. This does not clear the retained upper multiplayer SEND byte.
+Full multiplayer reset side effects remain unverified; this increment does not extend the firmware reset sequence.
 
 Original tests cover independent byte lanes, input pull-ups, output directions, reset flag selection, and explicit unsupported operations.
 Whole-access and block-store validation prevent a rejected control value from committing preceding bytes or registers.
@@ -113,8 +161,10 @@ Inactive configuration bits do not wake HALT. RCNT word accesses still reject th
 
 - [GBATEK reset functions](https://problemkaputt.de/gbatek-bios-reset-functions.htm): reset flags, general-purpose selection, and the unconditional SIODATA32 side effect.
 - [GBATEK normal serial mode](https://problemkaputt.de/gbatek-sio-normal-mode.htm): data widths, MSB-first shifting, rates, pulled-high SI, start/completion, IRQ selection, and external-clock waiting.
+- [GBATEK multiplayer mode](https://problemkaputt.de/gbatek-sio-multi-player-mode.htm): child start restrictions, SI/SD status, undefined pre-transfer ID, register widths, and R/W receive registers.
+- [LinkRawCable at c61bf351](https://github.com/afska/gba-link-connection/blob/c61bf351f68ad2d6e1c9d72d70e21bec19adfc0b/lib/LinkRawCable.hpp): public API usage for mode selection, SEND, receive words, and separate role/readiness/ID checks. Its disconnected-cable warning is not a pin-level measurement.
 - [GBATEK mode summary](https://problemkaputt.de/gbatek-sio-control-registers-summary.htm): RCNT/SIOCNT mode selection.
-- [mGBA serial implementation at 3a5e34be](https://github.com/mgba-emu/mgba/blob/3a5e34be33dc7f8f707e5bc9db69e8a430046f21/src/gba/sio.c): cross-checked normal transfer-duration arithmetic and completion IRQ handling. Its no-driver scheduled completion and zero receive data are not copied; they do not establish disconnected hardware behavior.
+- [mGBA serial implementation at 3a5e34be](https://github.com/mgba-emu/mgba/blob/3a5e34be33dc7f8f707e5bc9db69e8a430046f21/src/gba/sio.c): cross-checked normal transfer-duration arithmetic and completion IRQ handling. Its no-driver scheduled completion and zero receive data are not copied; they do not establish disconnected hardware behavior. Multiplayer comparison covers SI/SD defaults, receive-write disagreement, and uncertain floating SC timing.
 - [GBATEK](https://mgba-emu.github.io/gbatek/): GBA general-purpose pin directions, internal pull-ups, SI falling-edge interrupts, and the SIO mode-selection table.
 - [mGBA BIOS implementation at 3a5e34be](https://github.com/mgba-emu/mgba/blob/3a5e34be33dc7f8f707e5bc9db69e8a430046f21/src/gba/bios.c): functional serial reset defaults, not copied source.
 

docs/research/emerald-reset.md

@@ -58,13 +58,19 @@ The serial model now handles that unshifted transition and clocks normal 8/32-bi
 It shifts disconnected high input, clears start at completion, and requests serial IRQs through the ordinary device transaction.
 No connected partner, fabricated peer data, or immediate completion was added.
 
-Both runs now reach multiplayer mode selection:
+Normal internal clocks then reached multiplayer selection (`SIOCNT=0x2000`, PC `0x082e4358`).
+The disconnected multiplayer model now accepts that configuration and reports idle child status.
+A child cannot start itself without a parent clock. No linked transfer, assigned player ID, or completion IRQ is fabricated.
+The send register supports 16-bit data; receive latches do not become invented peer data.
+See [the register model and evidence limits](../hardware/serial.md#disconnected-multiplayer-configuration).
+
+Both terminal and native runs now reach a Game Pak GPIO control write:
 
 ```text
-Steps: 955967; instructions: 953287; IRQ entries: 80; DMA units: 2600; HALT idle: 0
-Nominal cycles: 3514542
-PC=0x082e4358
-unsupported multiplayer/UART serial mode: write 0x20 at 0x04000129
+Steps: 956055; instructions: 953375; IRQ entries: 80; DMA units: 2600; HALT idle: 0
+Nominal cycles: 3514932
+PC=0x082e29f8
+read-only memory at 0x080000c8
 ```
 
 The native run captures twelve startup frames. These do not establish a working title screen or gameplay.
@@ -79,10 +85,10 @@ Workspace debug/release tests, strict Clippy, public ARM/Thumb/memory/BIOS check
 Native ROM-window tests and graphics smoke modes pass on Darwin arm64.
 The pinned Pong debug/release reports match.
 
-The next requirement is disconnected multiplayer-mode configuration and status, starting with SIOCNT mode value `0x2000`.
-Research mode selection, absent-partner input levels, ready/error flags, and start behavior before extending the model.
-Do not invent connected players or successful linked transfers to suppress the diagnostic.
-The normal-mode result does not establish linked gameplay or GPIO interrupt support.
+The next requirement is cartridge GPIO, starting with the control register at `0x080000c8`.
+Research the Game Pak data/direction/control registers and real-time clock protocol before implementing them.
+Keep ordinary ROM writes read-only. Do not hide the failure by ignoring every cartridge write.
+This serial result does not establish linked gameplay or serial GPIO interrupt support.
 
 Noise now has deterministic counter clocks and shares tested length/envelope logic with the independent pulse channels.
 Sweep applies only to channel 1. Direct Sound has FIFO clocks and nominal DMA requests.

docs/status.md

@@ -142,9 +142,11 @@ There is no host audio output or cartridge save support.
 The [audio subset](hardware/audio.md) supports Direct Sound, both PSG pulse channels, noise channel 4, idle wave channel 3 state, and instantaneous digital mixing.
 It does not yet provide a continuous sample stream. Wave channel 3 playback and unverified sound-DMA pairings remain diagnostic.
 PSG timing and signed mixing are nominal; hardware startup edges and analog behavior remain unverified.
-The [serial subset](hardware/serial.md) supports disconnected normal 8/32-bit transfers, external-clock waiting, and general-purpose pins.
+The [serial subset](hardware/serial.md) supports disconnected normal 8/32-bit transfers, external-clock waiting, idle multiplayer configuration, and general-purpose pins.
 Internal clocks shift high input at nominal rates, clear busy, and request completion IRQs. External requests retain busy without clock edges.
-Connected links, multiplayer/UART, Joybus, GPIO interrupts, and unverified mid-transfer reconfiguration remain unsupported.
+Disconnected multiplayer exposes child/ready status and 16-bit send/receive registers without inventing transfers or completion IRQs.
+Pre-transfer ID is a zero placeholder; receive-write behavior and reset/alias details lack physical-hardware validation.
+Connected links, multiplayer transfers, UART, Joybus, GPIO interrupts, and unverified mid-transfer reconfiguration remain unsupported.
 RCNT retains inactive bits 8/14 in normal mode. Effective GPIO interrupt enable and Joybus selection remain diagnostic.
 Mapped I/O covers DMA, timers, interrupts, WAITCNT, display control/status, background control/scroll/affine registers, window/effect registers, KEYINPUT/KEYCNT, POSTFLG, and HALTCNT.
 Keypad IRQs use a documented polling model; hardware retrigger edges and asynchronous input timing remain unverified.
@@ -158,7 +160,8 @@ A local Emerald run now completes its all-device reset and master sound enable.
 It also passes the pulse/noise triggers and normal-mode RCNT configuration.
 It also completes a CpuSet call to address zero through the corrected ignored BIOS-write behavior.
 It also accepts an external-clock serial request without inventing clock edges or completion.
-It now also completes internally clocked normal transfers and next stops at multiplayer mode selection (`0x04000129`, PC `0x082e4358`).
+It now also completes internally clocked normal transfers and selects idle multiplayer mode.
+It next stops at a Game Pak GPIO control write (`0x080000c8`, PC `0x082e29f8`). Cartridge GPIO remains unimplemented.
 No title-screen, gameplay, or audible-game compatibility is established.
 See [the startup result](research/emerald-reset.md) for the bounded run and next investigation.
 See [cartridge loading](hardware/cartridge.md) for file limits, step budgets, and exit status.

docs/testing.md

@@ -211,7 +211,7 @@ They check errors for unsupported features and out-of-range fetches without chan
 The CPU tile demo test verifies asset copies, every pixel, wrapping, opposite directions, reset, and VBlank synchronization.
 RegisterRamReset tests check full memory regions and all memory-flag combinations from ARM and Thumb.
 They verify forced blank, reserved flag bits, caller preservation, protected BIOS RAM, and selective serial/sound initialization.
-All-device reset returns from ARM and Thumb; active sound and serial operations remain separately tested diagnostics.
+All-device reset returns from ARM and Thumb; supported sound/serial activity and remaining diagnostics have separate regressions.
 Rendering tests check write-only display state, both identity matrices, and the effect of zeroed sprite attributes.
 Device tests check DMA address/count latches, stopped timer counters, cleared reloads, and IRQ acknowledgement.
 Other checks cover partial clears, preserved input/device state, and callers whose own RAM code is erased.
@@ -295,7 +295,10 @@ Timed and untimed execution are compared across all 65,536 Thumb encodings with
 Normal serial tests cover both widths and internal rates, every bit edge, disconnected high input, batching, and completion IRQs.
 They check external-clock handoff, cancellation, phase retention, HALT bounds, STOP freeze/wake, and explicit live-write limits.
 Bus-phase tests cover start/load timing, IF acknowledgement order, CPU/DMA rollback, block preflight, and capture independence.
-These tests validate the documented nominal serial model, not physical link-pin timing or multiplayer compatibility.
+Disconnected multiplayer tests cover every control value in that format, all baud settings, send/receive lanes, and normal-mode aliases.
+They verify idle child status, ignored start, no completion IRQ or HALT wake, GPIO sampling, and ARM/Thumb/DMA stores.
+Staged tests check mode changes at normal completion, block loads/stores, rollback, and reads after leaving multiplayer format.
+These tests validate the documented bounded serial model, not physical pin timing, receive-write behavior, or linked-game compatibility.
 Timer/IRQ tests verify that changing WAITCNT changes when an interrupt is sampled.
 Timer tests cover all prescalers, reload changes, start/stop behavior, byte writes, large clock advances, and cascades.
 Ordered timer tests cover ARM/Thumb sampling, coherent byte lanes, block-transfer phases, reload/control ordering, and prescaler retention.

docs/usability-roadmap.md

@@ -40,9 +40,10 @@ The native Darwin window also starts and presents frames without a diagnostic.
 This exposed and corrected missing firmware affine-scale initialization, without a game-specific patch.
 Frame-based scenarios and the preparation adapter now make the result repeatable.
 A local Emerald run now passes its initial all-device reset, master sound enable, and pulse/noise triggers.
-It stops at GPIO serial interrupt control. The core has tested Direct Sound, both pulse channels, and noise channel 4.
+It also passes normal serial transfers and idle multiplayer configuration, then stops at Game Pak GPIO control.
+The core has tested Direct Sound, both pulse channels, and noise channel 4.
 Wave channel 3, a continuous sample stream, and desktop audio output remain missing.
-See [the runtime result](research/emerald-reset.md). Serial control-register semantics are the next demonstrated startup requirement.
+See [the runtime result](research/emerald-reset.md). Cartridge GPIO and its real-time clock protocol are the next demonstrated startup investigation.
 The separate save requirement remains cartridge SRAM, followed by safe host save persistence.
 SRAM is byte-addressable battery-backed save memory. Flash and EEPROM remain separate protocols.