Echo RAM Implementation (The Mirror)

Summary

Step 0237 autopsy and Step 0238 forensic analysis revealed root cause of infinite loop in Tetris: the direction0xE645belongs to the region ofEcho RAM (0xE000-0xFDFF), which on real hardware is an exact mirror of theWRAM (0xC000-0xDDFF). The game wrote0xFDin0xC645(real memory) and then read0xE645(mirror) for verify memory integrity. Since our MMU did not implement Echo RAM, it returned0x00, causing the comparisonCP 0xFDwill fail and the loop will never end.

This Step implements the Echo RAM logic inMMU.cpp, automatically redirecting any access to0xE000-0xFDFFtoward0xC000-0xDDFFboth in reading and writing.

Hardware Concept

Echo RAM (Mirror RAM)is a Game Boy hardware quirk caused by wiring of the address bus. Due to limitations in chip design, accessing addresses in the range0xE000-0xFDFFphysically accesses the same memory as0xC000-0xDDFF.

• WRAM (Work RAM): 0xC000-0xDDFF(8KB of real memory).
• Echo RAM: 0xE000-0xFDFF(WRAM mirror, same physical memory).
• Relationship: Echo_RAM_Address = WRAM_Address + 0x2000

Why does Echo RAM exist?In real hardware, this is a side effect of the design of the address bus. The address bits are not fully decoded, causing certain ranges are "reflected" in others. Games sometimes use this feature to check memory integrity: They write a value to WRAM and then read its mirror in Echo RAM to confirm that the memory is working properly.

Behavior:

• Read0xE645should return the value stored in0xC645.
• Write0xFDin0xE645must modify0xC645.
• Both addresses point to the same physical memory cell.

Fountain: Bread Docs -Memory Map, "Echo RAM" section.

Implementation

Echo RAM implementation is done in the methodsread()andwrite()ofMMU.cpp, automatically redirecting any access to the range0xE000-0xFDFFtoward0xC000-0xDDFF.

Modification in MMU::read()

uint8_t MMU::read(uint16_t addr) const {
    addr &= 0xFFFF;
    
    // --- Step 0239: IMPLEMENTATION OF ECHO RAM ---
    // Echo RAM (0xE000-0xFDFF) is a mirror of WRAM (0xC000-0xDDFF)
    if (addr >= 0xE000 && addr<= 0xFDFF) {
        addr = addr - 0x2000;  // Redirigir a WRAM: 0xE645 ->0xC645
    }
    // -----------------------------------------
    
    //... rest of the reading code...
}

Modification in MMU::write()

void MMU::write(uint16_t addr, uint8_t value) {
    addr &= 0xFFFF;
    
    // --- Step 0239: IMPLEMENTATION OF ECHO RAM ---
    // Echo RAM (0xE000-0xFDFF) is a mirror of WRAM (0xC000-0xDDFF)
    if (addr >= 0xE000 && addr<= 0xFDFF) {
        addr = addr - 0x2000;  // Redirigir a WRAM: 0xE645 ->0xC645
    }
    // -----------------------------------------
    
    //...rest of the writing code...
}

Cleaning Debug Logs

We also delete the "Sniper" logs (Step 0237) inCPU.cppwho fulfilled their mission to identify the problem. These logs slowed down the execution and are no longer necessary.

Design Decisions

• Early redirect: The redirection is done at the beginning ofread()andwrite(), before any other processing, to ensure that all accesses to Echo RAM are handled correctly.
• Address modification: Instead of creating separate logic, we simply modify the addressaddrto point to WRAM. This ensures that all existing logic (I/O registers, STAT, etc.) work correctly without additional changes.
• Exact range: We use0xE000-0xFDFF(No0xE000-0xFE00) because the range0xFE00-0xFEFFIt's OAM (Object Attribute Memory), not Echo RAM.

Affected Files

• src/core/cpp/MMU.cpp- Implementation of Echo RAM inread()andwrite()
• src/core/cpp/CPU.cpp- Deletion of Sniper logs (Step 0237)
• docs/bitacora/entries/2025-12-22__0239__implementacion-echo-ram.html- This entry

Tests and Verification

The implementation was validated by:

• Compilation: python setup.py build_ext --inplace- No compilation errors.
• Tetris execution: python main.py roms/tetris.gb- The game should exit infinite loop on0x2B2Aand advance to the Copyright screen.
• Memory validation: Verify what to write in0xE645modifies0xC645and vice versa.

Expected result: When Tetris reads0xE645after writing0xFDin0xC645, you should get0xFD, the comparisonCP 0xFDwill pass (Z=1), and the jump conditionalJR NZwill not be taken, allowing the game to continue.

Sources consulted

• Bread Docs:Memory Map- "Echo RAM" section
• Forensic Analysis of Step 0238: Address Identification0xE645as cause of loop

Educational Integrity

Next Steps

• [ ] Run Tetris and verify that it exits the infinite loop
• [ ] Confirm that the game advances to the Copyright screen
• [ ] If the game continues to crash, investigate other possible causes (WRAM initialization, copy routines, etc.)
• [ ] Verify that other games that use Echo RAM work correctly