The Beat of Time: Implementation of the Timer (DIV) in C++

Summary

Milestone reached!The native loop architecture has solved all thedeadlockssynchronization andL.Y.cycle correctly. However, the screen remains blank because the VRAM is empty. Diagnostics of the PPU reveals that the CPU never copies graphics data to VRAM, probably because it is stuck in a time delay loop waiting for the Timer, which was not yet implemented in the C++ kernel.

This Step implements the Timer subsystem (initially just the registerDIV) in C++ and integrates its update into the native emulation loop to allow the CPU to bypass time delay loops. With the Timer running, the CPU will be able to advance through the boot sequence and eventually copy the Nintendo logo data to VRAM.

Hardware Concept: The DIV Registry (The System Metronome)

HeTimeris a stand-alone hardware component used for timing and random number generation. Its most basic component is the registryDIV(Divider, in0xFF04).

Features of the DIV record according toBread Docs:

• Increment Frequency:It is a counter that constantly increments at a fixed frequency of16384Hz.
• Cycle Calculation:Since the main clock is 4.194304 MHz,DIVincreases every256 T-Cycles(4194304 / 16384 = 256).
• Reading:It is read-only from the game's perspective. The value read is the high 8 bits of the internal 16-bit counter.
• Writing:WriteANYvalue in0xFF04has the side effect of resetting the counter to0. The written value is ignored.
• Use in BIOS:The BIOS uses it to generate precise time delays during boot. Without aDIVAs it moves forward, the CPU stays in an infinite loop waiting for the counter to reach a specific value.

Why is it critical for startup?

During the boot sequence, the BIOS and games use register-based time delay loopsDIVfor synchronization. A typical example would be:

; BIOS pseudocode
wait_for_timer:
    ld a, (0xFF04) ; Read DIV
    cp 0x10 ; Compare with target value
    jr c, wait_for_timer ; Yes DIV< 0x10, espera más

YeahDIVnever advances (because the Timer is not implemented), this loop never ends and the CPU is trapped, preventing it from continuing with the next part of the initialization (such as copying the logo data to VRAM).

Implementation

The Timer subsystem was implemented in C++ with the classTimer, which maintains an internal T-Cycles counter and exposes the logDIVthrough the MMU. The Timer is integrated into the native emulation loop via dependency injection, allowing the CPU and MMU to access it without direct coupling.

Created Components

• Timer.hppandTimer.cpp:C++ class that implements the DIV register with an internal 16-bit counter that is incremented with each call tostep().
• timer.pyxandtimer.pxd:Cython wrappers exposing classTimerto Python likePyTimer.

Modifications to Existing Components

• CPU.hppandCPU.cpp:Added methodsetTimer()and update the Timer inrun_scanline()after each instruction.
• MMU.hppandMMU.cpp:Added methodsetTimer()and special read/write handling in0xFF04to access the Timer dynamically.
• cpu.pyxandmmu.pyx:Added methodsset_timer()in the Cython wrappers to connect the Timer from Python.
• viboy.py:Creation of instance ofPyTimerand connection to CPU and MMU during initialization.
• setup.py:AggregateTimer.cppto the list of sources for compilation.

Design Decisions

• Dependency Injection:The Timer is passed as a pointer to the CPU and MMU, maintaining decoupling and allowing the components to operate independently.
• Main Loop Update:The Timer is updated inrun_scanline()after each instruction, ensuring precise synchronization with the emulated time.
• Dynamic Access from MMU:The MMU reads/writes the DIV register directly from the Timer, not from static memory, allowing the value to be updated in real time.
• Internal 16-bit counter:An internal 16-bit counter is used to maintain precision, and only the high 8 bits are exposed as DIV, simulating the behavior of real hardware.

Key Code

Implementation of the Timer in C++:

//Timer.cpp
void Timer::step(int t_cycles) {
    div_counter_ += t_cycles;
}

uint8_t Timer::read_div() const {
    return (div_counter_ >> 8) & 0xFF;
}

void Timer::write_div() {
    div_counter_ = 0;
}

Integration into the emulation loop:

// CPU.cpp - run_scanline()
// Update the Timer with the T-Cycles consumed
if (timer_ != nullptr) {
    timer_->step(t_cycles);
}

Dynamic access from MMU:

// MMU.cpp - read()
if (addr == 0xFF04) {
    if (timer_ != nullptr) {
        return timer_->read_div();
    }
    return 0x00;
}

// MMU.cpp - write()
if (addr == 0xFF04) {
    if (timer_ != nullptr) {
        timer_->write_div();
    }
    return;  // We do not write to memory
}

Affected Files

• src/core/cpp/Timer.hpp- Definition of the Timer class
• src/core/cpp/Timer.cpp- Timer implementation
• src/core/cpp/CPU.hpp- Added setTimer() method and pointer to Timer
• src/core/cpp/CPU.cpp- Timer integration in run_scanline()
• src/core/cpp/MMU.hpp- Added setTimer() method and pointer to Timer
• src/core/cpp/MMU.cpp- Read/write handling of 0xFF04
• src/core/cython/timer.pxd- Cython Definition of Timer
• src/core/cython/timer.pyx- Timer Python Wrapper
• src/core/cython/cpu.pxd- Added setTimer() method
• src/core/cython/cpu.pyx- Implementation of set_timer()
• src/core/cython/mmu.pxd- Added setTimer() method
• src/core/cython/mmu.pyx- Implementation of set_timer()
• src/core/cython/native_core.pyx- Inclusion of timer.pyx
• src/viboy.py- Timer creation and connection
• setup.py- Added Timer.cpp to sources
• tests/test_core_timer.py- Timer unit tests

Tests and Verification

Exhaustive unit tests were created to validate the Timer implementation:

• Command executed: pytest tests/test_core_timer.py -v
• Expected result:All tests pass, validating:
  • DIV initial value (0)
  • Increase every 256 T-Cycles
  • Reset when writing to DIV
  • Wrap-around after 0xFF
  • Correct frequency (16384 Hz)

Test Code (Key Fragment):

def test_div_increment_after_256_cycles():
    """Verify that DIV is incremented every 256 T-Cycles."""
    timer = PyTimer()
    
    # DIV should be 0 after 255 cycles
    timer.step(255)
    assert timer.read_div() == 0
    
    #DIV should be 1 after 1 more cycle (256 total)
    timer.step(1)
    assert timer.read_div() == 1
    
    # DIV should be 2 after 256 more cycles (512 total)
    timer.step(256)
    assert timer.read_div() == 2

C++ Compiled Module Validation:The tests directly validate the C++ implementation through the Cython wrapper, confirming that the Timer works correctly in the native code.

Sources consulted

• Bread Docs:"Timer and Divider Register" section - Description of the DIV register and its behavior
• Bread Docs:"System Clock" section - Main clock frequency (4.194304 MHz) and cycle calculation
• Blind Renderer Diagnosis:Analysis that identified the CPU being trapped in time delay loops

Educational Integrity

Next Steps

• [ ] Recompile the C++ module withpython setup.py build_ext --inplace
• [ ] Run the Timer tests to validate the implementation
• [ ] Run the emulator with a ROM and verify that the CPU advances beyond the delay loops
• [ ] Verify that VRAM is filled with logo data (using debug logs if necessary)
• [ ] Confirm that the Nintendo logo appears on the screen
• [ ] If the logo appears, celebrate the victory and document the milestone
• [ ] If there are still problems, investigate other missing components (other Timer registers, interrupts, etc.)