Migración del Esqueleto de CPU a C++ (CoreCPU)

Resumen

Se ha completado la migración del esqueleto básico de la CPU a C++, estableciendo el patrón de inyección de dependencias en código nativo. La CPU ahora ejecuta el ciclo Fetch-Decode-Execute en C++ puro, accediendo a MMU y Registros mediante punteros directos. Se implementaron dos opcodes de prueba (NOP y LD A, d8) para validar el patrón arquitectónico antes de migrar el resto de instrucciones.

Concepto de Hardware

La CPU LR35902 de la Game Boy ejecuta instrucciones en un ciclo continuo llamado Fetch-Decode-Execute:

1. Fetch: Lee el byte apuntado por PC (Program Counter) de memoria
2. Increment: Avanza PC al siguiente byte
3. Decode/Execute: Identifica el opcode y ejecuta la operación correspondiente

Cada instrucción consume un número específico de M-Cycles (Machine Cycles). Un M-Cycle corresponde típicamente a una operación de memoria. Por ejemplo:

• NOP (0x00): 1 M-Cycle (no hace nada, solo consume tiempo)
• LD A, d8 (0x3E): 2 M-Cycles (lee opcode + lee valor inmediato)

La CPU no posee la MMU ni los Registros; solo mantiene referencias (punteros) a ellos. Esto permite que múltiples componentes compartan el mismo estado, siguiendo el patrón de inyección de dependencias.

Fuente: Pan Docs - CPU Instruction Set

Implementación

Se creó la clase C++ CPU que implementa el ciclo de instrucción básico. La arquitectura utiliza punteros a MMU y CoreRegisters (no los posee), siguiendo el principio de inyección de dependencias. Esto permite que Python sea el dueño de la memoria, mientras que C++ opera a máxima velocidad con punteros directos.

Componentes creados/modificados

• CPU.hpp / CPU.cpp: Clase C++ que implementa el ciclo Fetch-Decode-Execute
  • Miembros: punteros a MMU y CoreRegisters, contador de ciclos
  • Método step(): Ejecuta un ciclo de instrucción
  • Helper fetch_byte(): Lee byte de memoria e incrementa PC
  • Switch optimizado por compilador para decodificación de opcodes
• cpu.pxd / cpu.pyx: Wrapper Cython que expone CPU a Python
  • Clase PyCPU: Wrapper Python para CPU
  • Constructor recibe PyMMU y PyRegisters
  • Extrae punteros C++ subyacentes para inyección de dependencias
• setup.py: Añadido CPU.cpp a las fuentes de compilación
• native_core.pyx: Incluido cpu.pyx en el módulo principal
• test_core_cpu.py: Suite completa de tests de integración (6 tests)

Decisiones de diseño

1. Inyección de Dependencias en C++: La CPU recibe punteros a MMU y Registros en lugar de poseerlos. Esto permite que Python gestione el ciclo de vida de los objetos, mientras que C++ opera con punteros directos (máximo rendimiento).

2. Switch Statement para Decodificación: Se usa un switch en lugar de una tabla de funciones. El compilador puede optimizar esto en una tabla de saltos (jump table), proporcionando O(1) decodificación de opcodes.

3. Opcodes Mínimos para Validación: Solo se implementaron 2 opcodes (NOP y LD A, d8) para validar el patrón arquitectónico. El resto de opcodes se migrarán en pasos posteriores.

4. Manejo de Errores: Los opcodes desconocidos retornan 0 (error) en lugar de lanzar excepciones. Esto evita overhead en el bucle crítico de emulación.

5. Acceso a Miembros Privados en Cython: Como mmu.pyx y registers.pyx están incluidos en native_core.pyx, podemos acceder directamente a los miembros privados _mmu y _regs desde cpu.pyx (mismo módulo compilado).

Archivos Afectados

• src/core/cpp/CPU.hpp - Declaración de la clase CPU en C++
• src/core/cpp/CPU.cpp - Implementación del ciclo de instrucción
• src/core/cython/cpu.pxd - Definición Cython de la clase C++
• src/core/cython/cpu.pyx - Wrapper Python para CPU
• src/core/cython/native_core.pyx - Incluido cpu.pyx
• src/core/cython/mmu.pyx - Comentario sobre acceso a miembros privados
• src/core/cython/registers.pyx - Comentario sobre acceso a miembros privados
• setup.py - Añadido CPU.cpp a fuentes
• tests/test_core_cpu.py - Suite de tests de integración (6 tests)

Tests y Verificación

Se creó una suite completa de tests de integración que valida:

• Inicialización: La CPU se crea correctamente con MMU y Registros
• NOP (0x00): Consume 1 M-Cycle, incrementa PC correctamente
• LD A, d8 (0x3E): Lee valor inmediato, lo guarda en A, consume 2 M-Cycles
• Múltiples ejecuciones: Secuencia de instrucciones funciona correctamente
• Opcodes desconocidos: Retornan 0 (error) sin crashear
• Inyección de dependencias: Múltiples CPUs pueden compartir MMU y Registros

Resultados de ejecución:

============================= test session starts =============================
platform win32 -- Python 3.13.5, pytest-9.0.2
collected 6 items

tests/test_core_cpu.py::TestCoreCPU::test_cpu_initialization PASSED      [ 16%]
tests/test_core_cpu.py::TestCoreCPU::test_nop_instruction PASSED         [ 33%]
tests/test_core_cpu.py::TestCoreCPU::test_ld_a_d8_instruction PASSED     [ 50%]
tests/test_core_cpu.py::TestCoreCPU::test_ld_a_d8_multiple_executions PASSED [ 66%]
tests/test_core_cpu.py::TestCoreCPU::test_unknown_opcode_returns_zero PASSED [ 83%]
tests/test_core_cpu.py::TestCoreCPU::test_cpu_with_shared_mmu_and_registers PASSED [100%]

============================== 6 passed in 0.06s =============================

✅ Todos los tests pasan (6/6)

Compilación: Exitosa con Visual Studio 2022 (MSVC 14.44.35207). Warnings menores de Cython esperados (no afectan funcionalidad).

Fuentes Consultadas

• Pan Docs: CPU Instruction Set - Especificación de opcodes y ciclos de máquina
• Arquitectura LR35902: Conocimiento general del ciclo Fetch-Decode-Execute
• Cython Documentation: Acceso a miembros privados en módulos incluidos

Integridad Educativa

Próximos Pasos

• [ ] Migrar más opcodes básicos (LD, ADD, SUB, etc.)
• [ ] Implementar manejo de interrupciones (IME, HALT)
• [ ] Añadir profiling para medir rendimiento real vs Python
• [ ] Migrar opcodes CB (prefijo 0xCB)
• [ ] Integrar CPU nativa con el bucle principal de emulación