This page goes deeper than the timer and interrupt summaries. The register bits are on register bit layouts. The text is our own wording of the raw Pan Docs Markdown (CC0, read 2026-11-19, kept in the site’s sample sources with SHA-256 in the sample README); each section names its file. Since the check of 2026-11-19 it also rests on the Mooneye test suite sources (the tests were read, not run), on SameBoy’s timing.c, sm83_cpu.c and memory.c, and on the gbdev wiki pages. Where these disagree, the text says so and says which one we follow. Nothing was checked on hardware or run in an emulator.
The timer registers
Source: Timer_and_Divider_Registers.md.
- DIV (
$FF04) counts at 16384 Hz (about 16779 Hz on the SGB1). Any write sets it to 0. It is also reset by thestopinstruction and only starts again when STOP mode ends, and also during a speed switch. Pan Docs has a to-do note: how DIV is affected by the wait after a speed switch is not known (what the other sources say is under the speed switch). In Color double speed it counts at 32768 Hz. - TIMA (
$FF05) counts at the rate chosen in TAC. On overflow it is reloaded from TMA and the timer interrupt is requested. - TMA (
$FF06) is the reload value. TMA =$FFgives an interrupt at every TIMA tick.$FEdivides the rate by two,$FDby three, and so on. A write to TMA in the same M-cycle as the reload copy: the sources disagree and we use the new value. Pan Docs’Timer_and_Divider_Registers.mdsays TIMA receives the old TMA value. Pan Docs’ ownTimer_Obscure_Behaviour.md(item 3 of the overflow list), the gbdev wiki (“If TMA is written the same cycle it is loaded to TIMA [B], TIMA is also loaded with that value”), the Mooneye testtma_write_reloadingand SameBoy (memory.c, TMA write: TIMA is set as well unless the timer is running normally) all give the new value. The Mooneye test passes on the DMG, MGB, SGB, SGB2, CGB, AGB and AGS; it expects$7F, the newly written TMA value, in TIMA when the write comes in the reload cycle. The exact rule is in the overflow section. - TAC (
$FF07): bit 2 enables TIMA (DIV always counts); bits 1–0 choose the rate. A write to TAC may add one to TIMA, but on the monochrome models only if the timer was already enabled before the write (see the glitches).
| TAC bits 1–0 | TIMA ticks every | DMG, SGB2, CGB normal speed | SGB1 | CGB double speed |
|---|---|---|---|---|
| 00 | 256 M-cycles | 4096 Hz | about 4194 Hz | 8192 Hz |
| 01 | 4 M-cycles | 262144 Hz | about 268400 Hz | 524288 Hz |
| 10 | 16 M-cycles | 65536 Hz | about 67110 Hz | 131072 Hz |
| 11 | 64 M-cycles | 16384 Hz | about 16780 Hz | 32768 Hz |
The timer has nothing to do with the real-time clock of the MBC3 (see the bank controllers).
The system counter and the falling edge
Source: Timer_Obscure_Behaviour.md.
DIV is only the visible part of the system counter, which increases every M-cycle unless the CPU is in STOP mode. The timer is driven by a bit of that counter, not by a separate divider. A multiplexer, controlled by the TAC clock select bits, picks one bit and sends it, together with the enable bit, to a falling-edge detector. Each time the selected bit goes from 1 to 0 while the timer is enabled, TIMA ticks. The DIV-APU event of the sound unit comes from a bit of the same counter. Pan Docs shows the circuit as drawings for the DMG and the Color. We do not copy them; our own drawing of the wiring, made from the drawings’ labels and lines, is further down.
Which bit, in both numberings
Pan Docs’ text does not list the bit numbers, but three other sources do, and all agree with each other and with the periods. There are two ways to count the same counter. Pan Docs counts the system counter in M-cycles, so it has 14 bits and DIV is its top 8 bits. The Mooneye tests, SameBoy and the gbdev wiki count in T-cycles, so the counter has 16 bits and a bit n of it is bit n − 2 of the M-cycle counter. DIV is the top byte of the 16-bit counter (bits 15 to 8), which is bits 13 to 6 of the M-cycle counter.
| TAC bits 1–0 | M-cycle counter bit | T-cycle counter bit | SameBoy TAC_TRIGGER_BITS | Wiki clocks_array (bit = value ÷ 2) | Mooneye test and comment |
|---|---|---|---|---|---|
| 00 | 7 | 9 | 512 | 1024 (512) | tim00_div_trigger: “bit 9”, 4096 Hz |
| 01 | 1 | 3 | 8 | 16 (8) | tim01_div_trigger: “bit 3”, 262144 Hz |
| 10 | 3 | 5 | 32 | 64 (32) | tim10_div_trigger: “bit 5”, 65536 Hz |
| 11 | 5 | 7 | 128 | 256 (128) | tim11_div_trigger: “bit 7”, 16384 Hz |
SameBoy’s counter (div_counter) grows by 4 for each M-cycle and DIV reads it shifted right by 8, so its masks are in T-cycle bits: TAC_TRIGGER_BITS[] = {512, 8, 32, 128}. The DIV-APU event uses mask 0x1000, T-cycle bit 12 (DIV bit 4, M-cycle bit 10), and 0x2000, bit 13 (DIV bit 5), in double speed. The Mooneye comments also give the delay: 512, 8, 32 and 128 cycles after a DIV reset the selected bit has just become 1. These numbers replace what an earlier version of this page called “our inference”. Pan Docs’ example below uses bit 1 of the low byte of the M-cycle counter for TAC = $FD, rate 01, which is the same bit as T-cycle bit 3.
Because the bits go to a multiplexer and then to a falling-edge detector, four odd things happen:
- Writing to DIV resets the whole system counter. If the selected bit was 1, this is a falling edge, so a timer tick and/or a DIV-APU event comes early.
- Changing the clock select in TAC from a bit that is currently 1 to a bit that is currently 0 sends a timer tick at once. Pan Docs’ example: with the system counter at
$3FF0and TAC at$FC, writing$05or$06to TAC ticks immediately, but$04or$07does not. - On monochrome consoles, switching the timer off while the selected bit is 1 sends one tick. This does not happen on the Color.
- On the Color, a TAC write that meets the condition above and turns the timer on (it was off) may or may not send a tick. Pan Docs says the behaviour varies between individual consoles.
The TAC write rule, with its condition
Pan Docs’ list does not say that the timer must have been enabled before the write for any of this to happen. The gbdev wiki gives the rule as code for the DMG and MGB (with sys_clocks the 16-bit T-cycle counter and clocks_array as in the table above), and SameBoy’s GB_emulate_timer_glitch implements the same rule: it starts with “Glitch only happens when old_tac is enabled” (if (!(old_tac & 4)) return;).
- Old enable bit 0: no tick. Enabling a stopped timer never ticks on these models, whichever the clock select.
- Old enable bit 1 and new enable bit 0: tick if the old selected bit is 1.
- Old and new enable bits both 1: tick if the old selected bit is 1 and the new selected bit is 0.
For the Color, the wiki says the first rule differs: enabling the timer with the same clock select does not tick, and neither does disabling it. When another change is made and the timer is enabled after the write, the result depends on a race and cannot be predicted for every device; this is the same “may or may not” as Pan Docs. The wiki adds that the AGB and AGS seem to behave strangely even in the other rules. SameBoy uses the one rule above for every model; its comment says GiiBiiAdvance reported that the Color behaves differently, “but this was not tested or implemented”. Mooneye rapid_toggle passes on all seven models it lists: it switches the timer on and off in a tight loop that counts BC down from $FFFF, and expects the timer interrupt to arrive when BC is $FFD9 (38 passes, because of these extra ticks). Its comments add that starting or stopping the timer does not reset the counter.
We checked Pan Docs’ example against our bit mapping: $3FF0 has bits 7 and 5 set and bits 3 and 1 clear. TAC $FC selects bit 7 (set). Writing rate 01 or 10 moves to bit 1 or 3 (clear): a tick. Rate 00 keeps bit 7, and rate 11 moves to bit 5 (set): no tick. That matches the example.
What the Mooneye timer tests expect
All of these pass on the DMG, MGB, SGB, SGB2, CGB, AGB and AGS, according to their own comments.
div_write: the timer uses the same counter as DIV. Writing DIV in a loop with TIMA at$FFand the 4096 Hz timer running never lets the counter reach its bit, so no interrupt happens in 65535 passes.div_timing: DIV changes every 64 M-cycles after a reset. With 61nops after the reset the read still gives$00, with 62 it gives$01, and a second reset restarts the count.tim00_div_triggertotim11_div_trigger: a write to DIV when the selected bit is 1 ticks TIMA (see the table above).rapid_toggle: see the rule above.
Overflow and reload delay
Source: Timer_Obscure_Behaviour.md.
When TIMA overflows, TMA is copied into it and the timer flag is set in IF, but one M-cycle later. For that one M-cycle TIMA reads $00. This happens only when TIMA overflows by counting; it cannot be provoked by writing to TIMA. Pan Docs’ example, with TAC $FD and TMA $23 (one column per M-cycle, SYS being the low byte of the system counter):
| M-cycle | SYS | TIMA | TMA | IF |
|---|---|---|---|---|
| before | 2B | FE | 23 | E0 |
| 2C | FF | 23 | E0 | |
| 2D | FF | 23 | E0 | |
| A (overflow) | 2E | 00 | 23 | E0 |
| B (reload) | 2F | 23 | 23 | E4 |
| after | 30 | 24 | 23 | E4 |
| after | 31 | 24 | 23 | E4 |
Pan Docs’ table has a seventh column (SYS 31, TIMA 24, TMA 23, IF E4); it is the last row above. The IF column starts at E0 because the three unused upper bits of IF read as 1 (see IF and IE read-back). The gbdev wiki has a second example, a tick that does not overflow (column C): SYS FD FE FF 00 01 02 03, TIMA 45 45 45 46 46 46 46, TMA 23 throughout, IF E0 throughout. TIMA simply goes up by one at the tick, takes no extra cycle and sets no flag.
Pan Docs lists three surprises. Call the overflow cycle A and the reload cycle B.
- Writing to TIMA during A acts as if the overflow did not happen. TMA is not copied, so the written value stays, and IF bit 2 is not set. Writing to DIV, TAC or other registers does not stop the flag being set or TIMA being reloaded.
- Writing to TIMA during B is ignored. TIMA equals TMA at the end of the cycle anyway.
- Writing to TMA during B copies the same new value to TIMA in the same cycle (the disagreement with the TMA sentence of the timer register section is explained next).
Writes to TMA and TIMA near the reload: all the sources
One sentence in Pan Docs’ Timer_and_Divider_Registers.md says that a TMA write in the same M-cycle as the copy to TIMA leaves the old value in TIMA. That is the only source that says so. We follow the other four, which agree with Pan Docs’ obscure-behaviour page: the new value is copied.
- Pan Docs, Timer_Obscure_Behaviour.md, item 3: “Writing to TMA during cycle B will have the same value copied to TIMA as well, on the same cycle.”
- gbdev wiki, Timer Obscure Behaviour: “If TMA is written the same cycle it is loaded to TIMA [B], TIMA is also loaded with that value.” The wiki’s explanation is that TMA is a latch: as soon as it is written, its output shows the new value, so TIMA sees it too. It adds that this does not affect IF.
- Mooneye
tma_write_reloading(passes on all seven models): TIMA and TMA are both set to$FE, the 65536 Hz timer runs, and a write of$7Fto TMA is made at four spacings of one M-cycle each, each followed by a read of TIMA. The expected reads are$7F,$7F,$FEand$FE. The lead-in is the same as intima_write_reloading, where the second and third writes fall in cycles A and B (reads$7Fand$FE). By that alignment (our reading of the two test sources), the writes of the first two spacings fall in A and B and give$7F(the new value); the third, one cycle after B, comes too late and TIMA stays$FE. - SameBoy,
memory.c: a write to TMA sets TIMA to the same value whenever the timer’s reload state is not “running”, which covers both the overflow cycle and the reload cycle. A TIMA write is ignored only in the reload cycle.
The Mooneye tima_write_reloading test (also on all seven models; the cycle numbers follow the same alignment, with the extra ld a,h before the nops in the write tests): a write to TIMA one cycle before A is counted (TIMA reads $80 after the increment), a write in A stays ($7F), a write in B is ignored (TIMA reads $FE, the TMA value), and a write after B goes through ($7F). tima_reload shows TIMA reading $FF, then $00 for one M-cycle, then $FE (the TMA value), as in Pan Docs’ table.
One more disagreement, on IF. Pan Docs and the wiki say that a TIMA write in cycle A also stops the timer flag from being set. In SameBoy’s source (timing.c, advance_tima_state_machine, and memory.c) the TIMA write in A stores the value, but the flag is set one cycle later all the same. None of the saved Mooneye tests reads IF in that situation, so the two readings are unreconciled; we follow Pan Docs’ text above and mark this point as unsettled.
Pan Docs’ explanation (from its circuit drawing, which is not reproduced): a write to TIMA blocks the falling edge of the increment from being seen, because otherwise writing a value with bit 7 clear (from the CPU or from TMA) while TIMA’s bit 7 is 1 would trigger the bit 7 edge detector and schedule a false interrupt. In B the “load” signal stays on for the whole cycle and TIMA keeps copying its input; the “write to TIMA” signal ends in the middle of the cycle, so the CPU’s write does go through but is overwritten. TIMA and TMA can therefore be emulated as if TMA were copied to TIMA at the very end of cycle B, though that is not exactly what the hardware does.
HALT and the halt bug
Source: halt.md.
halt pauses the CPU, which uses less power. The CPU wakes as soon as an interrupt is pending, meaning IE AND IF is not 0.
- IME set (the usual case): the CPU wakes and, before it runs the instruction after the
halt, calls the handler in the normal way. - IME clear and no interrupt pending when
haltruns: it runs as normal and the CPU continues as soon as an interrupt becomes pending. Since IME is 0, the interrupt is not handled. - IME clear and an interrupt already pending:
haltends at once, and the halt bug happens.
The halt bug
With IME = 0 and [IE] AND [IF] not 0 when halt runs, the instruction ends at once, but PC is not incremented as it should be. Pan Docs links a test by nitro2k01 (double-halt-cancel). The usual result is that the byte after the halt is read twice, and if that byte is another halt the same can repeat. If the halt is followed at once by a jump, the result differs, and there are only two ways for that to be so:
- The
haltcomes straight afterei. The effect ofeiis delayed by one instruction, so IME is still 0 for thehalt. The interrupt is serviced and the handler called, but the handler returns to thehalt, which runs again and waits for another interrupt (Pan Docs cites the SameSuite testei_delay_halt). - The
haltis followed at once byrst. The return address of therstthen points at therstitself, not at the byte after it, so aretreturns to therstand runs it again.
If the bugged halt comes after ei and before rst, the ei case “wins”.
HALT in the Mooneye tests and SameBoy
- The halt bug on the Color. Some online documents say the bug does not happen on a Color. SameBoy’s source says the opposite in a comment in its
haltfunction: “Despite what some online documentations say, the HALT bug also happens on a CGB, in both CGB and DMG modes.” Its code treats all models alike: with IME = 0 and an interrupt already pending, the CPU does not halt and the next opcode byte is read twice. Pan Docs’halt.mddoes not limit the bug to one model either. We have no test that shows it on real Color hardware. - IME = 1 and an interrupt already pending when
haltruns: SameBoy does not halt and steps PC back by one, so the pushed return address is that of thehaltitself. Pan Docs does not describe this case. eidirectly beforehalt, nothing pending (halt_ime0_ei, passes on all seven models): thehaltshows its normal IME = 1 behaviour. The test waits for LY 0, clears IF, enables the VBlank interrupt, runsei,halt, and expects the VBlank handler to run (adiafter thehaltwould mean IME was 0). This is not the halt bug above, which needs an interrupt to be pending whenhaltruns.- IME = 1 services at once (
halt_ime1_timing, all models): with the timer interrupt enabled and about to fire, the handler is entered straight from thehaltand the instruction after it never runs. - IME = 0, nothing pending: no extra delay (
halt_ime0_nointr_timing, all models): thehaltcontinues with exactly the timing of a series ofnops. The test reads DIV after both cases and expects$11and$12. - IME = 1: the models differ (
halt_ime1_timing2-GS). The test expects thathaltadds no delay: the handler is entered with exactly the timing of a series ofnops. It passes on the DMG, MGB, SGB and SGB2 and fails on the CGB, AGB and AGS; the test says nothing about the reason or about what those models do instead. SameBoy’s main loop treats the Color separately: when halted, the wake-up wait is 4 T-cycles at a time on a Color, but on the other models it is 2 T-cycles first (unless thehalthas only just run) and then 2 more. We cannot tie that code to the Mooneye failure; it only shows that a model difference in the halted state is implemented.
IME, IE, IF and interrupt dispatch
Source: Interrupts.md and Interrupt_Sources.md.
- IME is an internal CPU flag that cannot be read.
eisets it,diclears it,retisets it and returns, and running an interrupt handler clears it first. It is clear when the game starts. The effect ofeiis delayed by one instruction, soeidirectly followed bydilets no interrupt through, and thehaltbug above uses this. - IF (
$FF0F): when an interrupt request wire from the PPU, timer or other unit goes from low to high, the matching IF bit is set. A set bit is only a request. A program may also write IF to request or discard interrupts by hand. A requested interrupt is serviced only when both IME and the IE bit allow it. - IE (
$FFFF): bit 0 VBlank, 1 LCD (STAT), 2 timer, 3 serial, 4 joypad.
Dispatch
- The CPU clears the IF bit (“acknowledges” it) and clears IME.
- It calls the handler like a normal
call: push PC, then set PC to the handler address.
In M-cycles: two wait states (the CPU presumably runs nops, says Pan Docs), then two cycles to push PC, then one to set PC to $40, $48, $50, $58 or $60. Five M-cycles in all (Pan Docs cites a gist by SonoSooS).
Priority and nesting
More than one IF bit can be set when several requests come at the same moment, when several were requested while IME or IE did not allow them, or when a program writes several bits to IF. The one with the lowest bit number wins: VBlank first, joypad last. The CPU sets IME to 0 on entering a handler, so another interrupt waits until the handler runs reti. A handler that wants to be interrupted runs ei itself.
EI, DI and RETI timing
Pan Docs says only that ei is delayed by one instruction. The Mooneye tests (read, not run; every one lists the DMG, MGB, SGB, SGB2, CGB, AGB and AGS as passing unless stated) add:
eiis delayed by exactly one instruction (ei_timing). With a serial interrupt requested and enabled,eifollowed by threeinc bleaves B = 1 when the handler runs: oneinc bexecutes, the interrupt is taken, the other two never run before it.- A repeated
eidoes not postpone the interrupt (ei_sequence). The test runs 18eiinstructions in a row with the interrupt pending. The handler’s return address is$01A2: only one instruction after the firstei(which is the secondei) ran. SameBoy does the same:eisets its delayed flag only if IME is 0 and no delay is already pending. eithendi(rapid_di_ei):ei,di,ei,dilets no interrupt through;ei,di,nop,noplets none through;ei,nop,dilets one through, and so doesei,nop,nop,di.eibeforehaltwith nothing pending:haltbehaves as with IME = 1 (see HALT in the tests).retienables interrupts at once (reti_intr_timing). VBlank and serial are both pending;ei, oneinc b, then the VBlank handler (at$40) runsinc dandreti. The serial handler (at$58) runs at once after thatreti, before the secondinc b: B, D and E all end as 1. SameBoy sets IME at once inreti. The gbdev wiki’s old Interrupts article callsreti“the same as the opcode combination EI, RET”; with the one-instruction delay ofeithat gives the same result, interrupts allowed right after the return.reti_timinggives the cycles ofreti: decode, read the low byte of PC from the stack, read the high byte, one internal cycle (four M-cycles).diis immediate on the DMG, MGB and SGB models. For the Color and Advance two sources say different things, and we do not reconcile them. Mooneye,di_timing-GS: “This test is for DMG/MGB, so DI is expected to disable interrupts immediately”, “On CGB/GBA DI has a delay and this test fails in round 2!!”; its list says pass on the DMG, MGB, SGB and SGB2, fail on the CGB, AGB and AGS. SameBoy,sm83_cpu.c, in thedifunction: “DI is NOT delayed, not even on a CGB. Mooneye’s di_timing-GS test fails on a CGB for different reasons.” The gbdev wiki’s list of quirks (“Quirks by difficulty”) says “di is immediate, and ei is delayed by one instruction” without naming models. No source here gives the real behaviour of the Color and Advance, or the “different reasons”.
IF and IE read-back, and a pending request
- IF bits 7 to 5 read as 1. Mooneye
if_ie_registers: after a request for the serial interrupt (bit 3), IF reads$E8; after the interrupt has been served it reads$E0. SameBoy reads IF asvalue | $E0(and TAC asvalue | $F8). Pan Docs’ bit diagram has only bits 4 to 0. - A pending request waits for IE. The same test sets the serial bit in IF with IE = 0 and IME = 1 and waits 64
nops: no interrupt happens. When IE is then set, exactly one interrupt happens (the handler counts them). - IE. SameBoy stores and reads back all eight bits of IE, and uses only the low five to decide. Neither Pan Docs nor the Mooneye tests say what the upper bits of IE read as on real hardware. The wiki’s quirks list has the line “Higher bits of IE / IF should be fixed value (GBC)” without saying the value.
Writing IE during the push (the cancel quirk)
The dispatch pushes the high byte of PC first, then the low byte. If SP points so that one of the two pushed bytes lands on $FFFF, that byte is written to IE in the middle of the dispatch. Mooneye interrupts/ie_push (all seven models) tests four cases; SameBoy’s dispatch code does the same:
- High byte lands on IE. With SP =
$0000and a timer interrupt pending, the high byte of PC ($02) becomes IE, which no longer enables the timer interrupt. The dispatch is cancelled: PC becomes$0000instead of$50, the IF bit stays set, and IME is 0 (a second round with a joypad request pending expects no interrupt after the cancel). - Low byte lands on IE. With SP =
$0001the low byte of PC ($35) clears the serial bit in IE, but that is too late: the interrupt is dispatched normally, to$58, and its IF bit is cleared. - Two interrupts pending, high byte on IE. STAT and VBlank are enabled and pending, the high byte (
$02) clears the VBlank bit only. The STAT interrupt is dispatched normally and VBlank stays requested in IF.
SameBoy reads IE again after the high byte is pushed and decides with that value (and with IF after the low byte): if no enabled request is left it sets PC to 0 and does not clear an IF bit; otherwise it serves the lowest set bit. IME becomes 0 in both cases. The Mooneye test has four rounds: the first, third and fourth are the cases above and the second is the IME check that follows the cancel.
The five sources
- VBlank,
$40: at the start of VBlank (LY = 144), about 59.7 times a second on a handheld Game Boy (DMG or CGB) or a Game Boy Player and about 61.1 on an SGB; VBlank lasts about 1.1 ms and video memory is free. - STAT,
$48: a rising edge on the shared STAT line (see picture unit in depth). - Timer,
$50: when TIMA overflows past$FF(one M-cycle late, see above). - Serial,
$58: eight serial clock cycles after a transfer is started, when the incoming byte is in SB. - Joypad,
$60: when any of P1 bits 0 to 3 goes from high to low. Switch bounce usually gives several. If both button groups are selected and a bit is already held low, another button on the same line makes no difference. Pan Docs says its only meaningful use is to end the STOP standby state, and that the GBA SP seems unaffected by bounce.
Reducing power consumption
Source: Reducing_Power_Consumption.md. Advice for programs; the percentages are Pan Docs’ own estimates.
Use HALT
Use halt whenever possible. It lasts until an interrupt that is enabled in IE is flagged in IF, serves it if IME is set, and goes on with the next instruction. Depending on how much CPU time a game needs, Pan Docs says it can lengthen battery life by 5 % to 50 % or more. Waiting for VBlank by polling LY is the bad example. The better way is a loop of halt and a test of a one-byte flag that the VBlank handler sets, which tells a VBlank wake-up from another interrupt. A VBlank interrupt between the cp and the jr goes unnoticed, so the loop halts again. If a game uses no other interrupt, enable only VBlank and just halt. Handlers must enable interrupts again (ei before returning, or better reti).
Use STOP (rarely)
STOP is meant to give a very low power standby, for example when nobody has pressed a key for a long time. Pan Docs says no licensed ROM uses it apart from Color speed switching. Take care:
- On a DMG, turning the LCD off before STOP leaves the LCD on, drawing a horizontal black line, which Pan Docs says is likely to damage the hardware.
- On a Color, leaving the LCD on when STOP runs gives a black screen, except in mode 3, where it keeps drawing the current screen.
- STOP ends when one of the P10 to P13 lines goes low, so write
$00,$10or$20to P1 first, depending on which buttons should end it. - STOP is normally a 2-byte instruction whose second byte is ignored. Pan Docs says that on the real hardware it can instead enter STOP mode, enter HALT mode, act as a
nop, do the speed switch, become a 1-byte opcode that runs its second byte as another opcode, or glitch the CPU unpredictably, depending on several factors. It shows a flow chart by Lior Halphon (an image,stop_diagram.svg) to decide which. The chart is written out as text below.
The STOP flow chart as text
Source: Pan Docs’ stop_diagram.svg, credited to Lior Halphon. The SVG holds its text clipped, so the full wording was read from the diagram’s editable source stop_diagram.drawio (both in samples/gb/sources/pandocs-more, CC0). In that file the “Yes” and “No” answers are separate text objects placed next to the arrows, so which arrow carries which answer was read from their positions: our reading of the geometry, consistent with the outcomes (no outcome appears twice). The chart is a decision tree that starts at “STOP instruction is reached!”. Questions are answered in this order:
- Is a button being held and selected in JOYP?
- Yes → Is an interrupt pending? (IE & IF ≠ 0)
- Yes → STOP is a 1-byte opcode, the mode does not change, DIV does not reset (the chart’s words end there; “acts like a
nop” is our gloss, and the second byte running as the next opcode follows from “1-byte opcode” and from a comment in SameBoy’sstopfunction: “When entering with IF&IE, the 2nd byte of STOP is actually executed”). - No → STOP is a 2-byte opcode, HALT mode is entered, DIV is not reset.
- Yes → STOP is a 1-byte opcode, the mode does not change, DIV does not reset (the chart’s words end there; “acts like a
- No → go to question 2.
- Yes → Is an interrupt pending? (IE & IF ≠ 0)
- Was a speed switch requested via KEY1?
- No → Is an interrupt pending?
- No → STOP is a 2-byte opcode, STOP mode is entered, DIV is reset.
- Yes → STOP is a 1-byte opcode, STOP mode is entered, DIV is reset.
- Yes → Is an interrupt pending?
- No → STOP is a 2-byte opcode, HALT mode is entered, DIV is reset and the CPU speed changes. The chart adds: unless an interrupt occurs before then, HALT mode exits automatically after about
$20000T-cycles. - Yes → Is IME enabled?
- No → “The CPU glitches non-deterministically, oops!”
- Yes → STOP is a 1-byte opcode, the mode does not change, DIV is reset and the CPU speed changes.
- No → STOP is a 2-byte opcode, HALT mode is entered, DIV is reset and the CPU speed changes. The chart adds: unless an interrupt occurs before then, HALT mode exits automatically after about
- No → Is an interrupt pending?
Seven outcomes in all (one is the glitch). The six questions have twelve answers but the file holds only eleven answer labels: the arrow from “Is IME enabled?” to the 1-byte speed-switch box carries no label, so “Yes = IME enabled → 1-byte, speed changes” and “No = glitch” is read from the one “No” label placed beside the glitch box and the unlabelled arrow (our reading; the text of Pan Docs does not repeat the chart).
Other savings
- Switch the sound off when it is not used: write
$00to NR52 for a saving of 16 % or more. Switch it on again with$80and set every sound register again. Sound is on at power-up and must be turned off by hand. - Avoid Color double speed. It uses more power. A game may use normal speed on the title screen and double speed in play, or the reverse, but the display collapses for a moment during a switch, so do not switch in the middle of a screen.
- Write tight code. The techniques help most with efficient assembly; a high-level language needs more CPU time and gains less. Pan Docs links the WikiTI Z80 optimisation page (the Z80 differs from the SM83) and a Pokémon Crystal disassembly page on optimising assembly.
DIV and interrupts during a speed switch
Pan Docs marks two points about the Color speed switch as to do: how DIV behaves during the wait after the switch, and whether interrupts can happen during it. We looked for more in every source we have. This is what each says. KEY1 itself is on register bit layouts.
- Pan Docs, Timer_and_Divider_Registers.md: DIV is reset when
stopruns, and “only begins ticking again once stop mode ends. This also occurs during a speed switch.” The to-do: “how is it affected by the wait after a speed switch?” - Pan Docs, CGB_Registers.md (KEY1): after the
stopthe CPU stops for 2050 M-cycles (8200 T-cycles). In that time “DIV does not tick, so some audio events are not processed”. Video memory locking is “frozen” and depends on the PPU mode in whichstopran: in HBlank and VBlank the PPU cannot access video memory and draws black pixels; in OAM scan it can read VRAM but not OAM, so the background is drawn without objects; in mode 3 it can access everything and drawing is not affected. The to-do: “confirm whether interrupts can occur (just the joypad one?) during the pause, and consequences if so”. - Pan Docs, the STOP chart (above): a speed switch with no interrupt pending resets DIV, enters HALT mode and changes the speed; unless an interrupt occurs before then, HALT mode ends by itself after about
0x20000T-cycles. With an interrupt pending and IME set, the switch happens at once with a 1-byte STOP, DIV reset; with IME clear the CPU glitches. The two lengths of the pause, 8200 T-cycles in the register text and0x20000(131072) T-cycles in the chart, differ by a factor of about 16, and Pan Docs does not explain it. - SameBoy (
sm83_cpu.c,stop; its comment says “Speed switch timing needs far more tests”): a switch writes 0 to DIV, enters STOP mode and leaves it again at once, and then, if no interrupt is pending, halts with a countdown of0x20008that falls by the cycles the core steps (in its own units, which we do not convert), and the HALT ends when it reaches 0. KEY1 bit 0 is cleared. Because the core is not in STOP mode during the countdown, its DIV does tick then (its timer code skips DIV only in STOP mode). That disagrees with Pan Docs’ “DIV does not tick”, and we cannot tell which is right. A comment in its counter code asks “Can switching to double speed mode trigger an event?”. - Interrupts during the pause: the chart says an interrupt before the timeout ends the pause. SameBoy does the same: any request that is enabled in IE ends the pause. With IME clear the CPU simply wakes; with IME set the interrupt is dispatched. Neither source says which interrupts can really occur (Pan Docs’ question) or what follows.
- Mooneye: none of the test sources we read uses a speed switch. gbdev wiki: its “CGB Registers” article is an older copy of the Pan Docs text without these notes; its “Quirks by difficulty” list names “Timing of STOP instruction when switching to double speed (GBC)” and “to single speed (GBC)” as things an emulator must get right, with no values. The wiki has no article on HALT or STOP: the titles Halt, HALT, Gameboy_Halt and STOP were tried and returned 404, and the wiki’s list of pages has none. Its instruction table says only “halt until interrupt occurs (low power)” and “stop … low power standby mode (VERY low power)”.
What this settles: the interrupt that ends the pause is documented by two sources. What it does not: the value of DIV during and after the pause (Pan Docs and SameBoy differ), and which interrupts can occur and what they do. Those stay under Unknown.
The timer drawings in words
Source: the four SVG drawings that Timer_Obscure_Behaviour.md includes (timer_simplified.svg, timer_tac_bug_dmg.svg, timer_tac_bug_gbc.svg, timer_tima_tma_detailed.svg, in samples/gb/sources/pandocs-more, CC0). Read from their text labels and shapes; the wiring is as drawn, the behaviour is in the sections above. “Falling edge detector” and the “placeholder” boxes are the drawings’ own words.
- Simplified timer circuit. The M-cycle clock increments DIV, and a write to DIV resets it. DIV (with the lower bits of the system counter drawn beside it) feeds two places: a 2-to-1 multiplexer (inputs labelled 1 and 0) controlled by the “Double Speed Mode active?” line from KEY1 bit 7 picks one of two adjacent bits (drawn at DIV bits 5 and 4) and sends it to a falling edge detector whose output is the DIV-APU event (the frame sequencer step, see the sound page); and four DIV bits go into a box marked “See detailed schematic” that makes the timer tick, together with the two TAC fields, TAC.freq (bits 1–0, which DIV bit) and TAC.enable (bit 2). The timer tick goes to a second “See detailed schematic” box that holds TIMA and TMA: TMA is loaded into TIMA (“Load”), a tick increments it (“Inc.”), and an overflow of TIMA sets bit 2 of IF (“Interrupt request”). Bits 7–0 are drawn for DIV, TMA and TIMA; bits 7–0 are not drawn for IF (bits 4–0).
- The TAC write glitch, DMG and Color. Both drawings show the same parts: DIV (bits 7–0) with reset and M-cycle increment, a 4-input multiplexer (inputs 0 to 3) chosen by TAC.freq, TAC.enable, an AND gate, a falling edge detector and the timer tick. DMG: the multiplexer output goes through the AND gate with TAC.enable first, and the AND output goes to the falling edge detector. Color: the falling edge detector comes first, on the multiplexer output, and its output is ANDed with TAC.enable. The consequence is in Pan Docs’ text (above): a reset of the system counter or a change of the clock select can send a tick (or a DIV-APU event) early, and “on monochrome consoles, disabling the timer if the currently selected bit is set will send a timer tick once”, which fits the gate sitting in front of the edge detector on the DMG; the Color drawing, with the detector first, is the reason that last effect is stated for monochrome consoles only (our reading of the two drawings).
- TIMA and TMA in detail. The labels are: TMA (bits 7–0) with “Write to TMA” and a CPU data bus; “Load”; TIMA with “Write to TIMA”, “Timer tick” and “Increment”; a falling edge detector; gates marked NOT, AND, OR; a “Delay” block; a “Set” input on IF (bits 4–0); and a second “Load”. The drawing shows the one-cycle delay between an overflow and the reload described under Overflow and reload delay: the overflow passes a “Delay” before it sets IF and loads TMA into TIMA, and a write to TIMA at the right moment cancels it. The gate connections, read from the lines and arrows of the drawing and not from its labels, are written out below and drawn in our own figure.
The wiring, drawn by us
The two figures are our own drawings. We made them from the lines, arrows and labels of Pan Docs’ four timer drawings (read from the SVG files, which are the only place the connections are given) and from the Pan Docs prose that explains them. They show which signal goes where; they are not a gate-level schematic of the chip, and the gates are the ones the Pan Docs drawing shows. Pan Docs itself says its TIMA and TMA drawing is “not quite what’s happening in hardware” for the copy at the end of the reload cycle.
Reading the first figure. The four inputs are the counter bits of the table above, in the T-cycle numbering. In Pan Docs’ drawing the multiplexer inputs 0, 3, 2 and 1 stand left to right above bits that sit at DIV bit 1 (M-cycle counter bit 7) and at the next three counter bits drawn beside DIV (M-cycle numbering: bits 5, 3 and 1; the positions are our measurement of the drawing); that is the same mapping as the table. The only difference between the two consoles is the order of the AND and the detector. On the DMG, turning the timer off while the selected bit is 1 makes the AND output fall, and the detector sees a falling edge. On the Color the detector watches the multiplexer output alone, so turning the timer off does not fall that signal (our reading, in line with Pan Docs’ statement that the effect is for monochrome consoles only).
Reading the second figure. TMA is a latch that loads from the CPU data bus when TMA is written. In front of TIMA a multiplexer chooses between TMA (input 0) and the bus (input 1); a write to TIMA selects the bus. TIMA is loaded when the OR of two signals is on: the write to TIMA, and the delayed overflow signal. A falling edge of TIMA bit 7 (the overflow) passes the AND only when the load signal is off, which is what stops a write to TIMA from being taken as an overflow. The AND output goes through a delay of one M-cycle. Its output sets IF bit 2 and is also the second input of the OR, so TIMA is loaded from the multiplexer (from TMA, unless a write to TIMA is selecting the bus) in that cycle B. A tick increments TIMA. This is exactly the behaviour Pan Docs lists in the overflow section and explains in its footnote. The timer overview in Pan Docs also draws the DIV-APU output (a multiplexer of DIV bits 4 and 5 controlled by double speed, into a falling edge detector); that part is in the text of the first list item above.
Sources
- Raw Pan Docs Markdown (CC0), read 2026-11-19, in
samples/gb/sources/pandocswith SHA-256 in the sample README:Timer_and_Divider_Registers.md,Timer_Obscure_Behaviour.md,halt.md,Interrupts.md,Interrupt_Sources.md,Reducing_Power_Consumption.md. The drawings:stop_diagram.drawioandstop_diagram.svg,timer_simplified.svg,timer_tac_bug_dmg.svg,timer_tac_bug_gbc.svgandtimer_tima_tma_detailed.svginsamples/gb/sources/pandocs-more. - Mooneye test suite sources (MIT, Joonas Javanainen), read not run, in
samples/gb/sources/mooneye-timingwith SHA-256 in the sample README:div_write,div_timing,rapid_toggle,tim00_div_triggertotim11_div_trigger,tima_reload,tima_write_reloading,tma_write_reloading,ei_timing,ei_sequence,rapid_di_ei,di_timing-GS,reti_intr_timing,reti_timing,halt_ime0_ei,halt_ime0_nointr_timing,halt_ime1_timing,halt_ime1_timing2-GS,if_ie_registers,intr_timing,interrupts/ie_push(saved asie_push). - SameBoy (Expat licence),
Core/timing.c,Core/sm83_cpu.candCore/timing.hinsamples/gb/sources/sameboy-core, andCore/memory.cinsamples/gb/sources/sameboy-src. - The gbdev wiki articles Timer Obscure Behaviour, Interrupts, Timer and Divider Registers, CGB Registers, CPU Instruction Set, Quirks by difficulty, Reducing Power Consumption and Gameboy and Gameboy Color special modes and features, in
samples/gb/sources/wiki. The wiki has no Halt or STOP article. - Timer Obscure Behaviour, HALT, Interrupts, Reducing Power Consumption – Pan Docs
Not described
Known, not yet covered
- Nothing known is left. Pan Docs’ pictures are not copied, but the STOP flow chart is written out as text, and the divider and timer wiring is drawn again by us (the two figures under “The wiring, drawn by us”). The Mooneye timer, EI, DI, RETI, HALT, IF/IE and ie_push behaviours and the SameBoy differences are in their own sections.
Unknown
- The value of DIV during and after the Color speed-switch pause. Pan Docs says DIV does not tick during the pause; SameBoy’s code lets it tick. No source has a measurement. See the speed switch.
- Which interrupts can occur during the speed-switch pause, and what follows (Pan Docs’ to-do). The chart and SameBoy only say that a request enabled in IE ends the pause.
- Why the pause is 2050 M-cycles (8200 T-cycles) in one Pan Docs text and about
0x20000T-cycles in its chart. - Whether
diis delayed on the Color and Advance: Mooneye’sdi_timing-GSsays it is; SameBoy says it never is. Neither gives a measurement beyond the test’s failure list. - What
haltdoes instead on the Color and Advance when IME = 1 (halt_ime1_timing2-GSfails there). No source gives the delay. - Whether a TIMA write in the overflow cycle also stops the timer flag. Pan Docs and the wiki say yes; SameBoy’s source sets the flag. No Mooneye test reads IF in that case.
- The exact result of a TAC write on the Color when the timer is turned on (Pan Docs: varies between consoles) and the odd behaviour of the AGB and AGS that the wiki mentions without detail.
- What the upper bits of IE read as on real hardware.
- Nothing here was checked on hardware or run in an emulator.