# Toki turbo flicker investigation

## Status: closed for now (2026-09-15)

After further game testing, the user reports no similar issue in the other
games tested and asks to leave this investigation closed for now. The Toki
turbo-only strobe remains reproducible; software timing at the higher speed
is a plausible explanation, not a confirmed cause. NORMAL remains the
reported workaround. No further Toki-directed RTL changes are planned.

R4 remains the published, tested baseline. Broader game and hardware memory
testing continue separately. The next CPU compatibility comparison will
use this same image with the TF030; that result is still pending.

## Hardware report

The user tested R3 (`260915R3`, BIN SHA256
`a6feb672529a822a1f2a9d2afb9f96021c56aaaa5d6194a987cbb167cf3675ab`).
Workbench corruption is gone. Toki appears stable, but the character's feet
flicker continuously when in a pit in the lower gameplay area, only in turbo.
The user confirmed WHDLoad, a slave dated 17.05.2013 (official v2.3), and a
clean NORMAL comparison. Memory is 2 MB chip, 1.5 MB slow and 2 MB fast
(`memory_config=4'b1111`), outside the 512K+512K cache-alias case fixed in R3.
The character's rendering method is not yet established.

After the verified R4 SD copy, the user reports that a character/sprite
entering the lower screen area still rapidly blinks or strobes in turbo.
The targeted visual symptom has therefore not improved with R4. The user
raised the possibility of a game/WHDLoad-specific issue, rather than a
general core defect. The user subsequently reported Alien Breed looking
clean, described 60 MHz operation as solid, and authorized publication of
the tested R4 image and source. A hardware memory test and more games are
still to be tested. These reports make a Toki-specific issue plausible but
do not establish its cause or full core compatibility.

## Software compatibility lead

The [official WHDLoad Toki notes](https://www.whdload.de/games/Toki.html)
document `CUSTOM3=1` to force Blitter waits on 68000 CPUs. The
[bundled slave source](https://www.whdload.de/games/Toki.lha) tests CPU type,
not clock speed. Its rerelease loader conditionally adds waits; the original
release has a separate unconditional wait path. The option's effect therefore
depends on the installation. The user added this option and relaunched on
the same R3 core at 60 MHz; the flicker did not change. This does not rule
out every software timing issue, especially on the original-release path
where waits are already installed.

## Core investigation

The Toki object has not been identified as an Amiga hardware sprite; games
also draw objects into bitplanes with the Blitter. Both paths need checking.

In R3, sprite DMA outranks Blitter DMA. Turbo changes the availability of
Blitter slots, without adding a sprite-specific priority branch. DMACONR
directly exposes Blitter busy and is not cached. Busy asserts at the captured
BLTSIZE write; the delayed write acknowledgment preserves that ordering.

The inherited Blitter pipeline clears busy before flushing its final held
word. Existing golden tests cover that tail and immediate restarts. The new
CPU/WaitBlit integration passes 19 cases and 1,824 partial blits, including
word/high-byte status polling, both speeds, Blitter priority, starvation
relief and original-Blitter controls. It observes early busy-clear events
without admitting the next job's pointer/control update before the final
write. Omitting the software wait produces actual destination corruption,
which verifies that the test detects premature Blitter reuse. See
[the test and its limits](../tests/blitter/README.waitblit.txt).

The focused sprite DMA/scanout comparison passes four normal/turbo and
vertical-wrap cases: 376 fetched words and 11,640 scanout samples across all
eight channels, under a long concurrent blit. Turbo changes the Blitter
grant count but not the sprite stream. This does not identify how Toki draws
its character or cover final RGB compositing. See [limits](../tests/sprites/README.txt).

Adding a controlled higher-priority DMA burst to the CPU/WaitBlit test
reproduces corruption in R3. While that burst holds the Blitter's final
destination write, CPU starvation relief lets the CPU observe busy clear
and update the destination pointer for its next job. The old final word
then lands at the new address. The test uses the real Agnus arbiter and
SRAM bridge with synthetic bitplane requests; it is not an execution of
Toki or the full graphics.library WaitBlit routine.

Resetting the CPU slowdown request at local bus retirement did not remove
this failure. Slowing only the Blitter to NORMAL cadence was also unsafe
in the same CPU polling scenario. Neither experiment is part of R4.

## R4 candidate

R4 retains R3's CPU interface and fast Blitter cadence. Area blits that
write a destination now complete when the final held word is accepted by
DMA. Busy, the completion interrupt, start bookkeeping and B-shifter
initialization use the same completion event. Line and no-destination
jobs keep their original completion point.

This deliberately changes the inherited early completion timing, which
matches a documented OCS/ECS behavior. Commodore's
[WaitBlit autodoc](https://www.theflatnet.de/pub/cbm/amiga/amigadev.elowar.com/read/ADCD_2.1/Includes_and_Autodocs_2._guide/node05A6.html)
describes busy becoming clear before the final destination write. Moving
that event also delays the Blitter interrupt and Copper busy-dependent
WAIT/SKIP decisions, in both NORMAL and turbo. Software relying on precise
early completion may therefore behave differently.

The candidate passes the reproduced corruption test and the independent
Blitter memory checks, but the user's R4 board test leaves Toki's strobe
unchanged. This weakens the link between the synthetic final-write race
and the reported game symptom. Because early busy clear is documented
hardware behavior, the synthetic failure alone does not establish that
R3 is incompatible with a real Amiga for this sequence. R4 remains an
experimental completion policy, with no demonstrated benefit for this Toki
symptom. Its released image and package remain preserved unchanged.

## Comparisons if the investigation is reopened

Keep R3 as the pre-experiment reference. If the symptom needs further
investigation, these comparisons could help distinguish the workload from
the core:

- Compare several other games at NORMAL/turbo, paying attention to objects
  entering the bottom of the screen. A shared symptom would strengthen the
  case for a general display/core issue; clean comparisons would narrow the
  investigation without proving the core fault-free.
- If an original disk/ADF installation is already available, compare Toki
  without WHDLoad at the same speeds and location. A difference implicates
  the installation/patch interaction; matching symptoms can still arise in
  either the original game timing or the core.
- The strongest software-specific comparison would use the same Toki
  installation on a known-good accelerated Amiga or a carefully matched
  emulator, while accounting for differences in CPU/chipset behavior.

The current official package is labelled 2.3a (31.05.2020), but its change
is an install-script correction for the Hit Squad release. It still contains
the 17.05.2013 version 2.3 slave. The reported slave date therefore does not
by itself show an obsolete runtime patch, and an update is not an established
fix. See the official notes linked above.
