ZPU Evo Guia del Desarrollador

English

Introduccion

Bienvenido a la Guia del Desarrollador de la ZPU Evolution. Esta guia esta dirigida a estudiantes, aficionados e ingenieros que deseen comprender, construir, modificar y ampliar el procesador ZPU Evolution. Ya sea que este cursando un curso de microprocesadores, aprendiendo desarrollo de FPGA o explorando el diseno de CPU soft-core, esta guia le acompanara a traves de todo, desde conceptos basicos hasta personalizacion avanzada.

La ZPU es un microprocesador de 32 bits basado en pila, originalmente disenado por Øyvind Harboe de Zylin AS. La ZPU Evolution (Evo) es una version mejorada creada por Philip Smart que anade mejoras significativas de rendimiento, caching, instrucciones extendidas y un amplio framework System-on-Chip (SoC). El diseno completo es open source e implementado en VHDL para sintesis en FPGAs Intel/Altera.

Lo que aprendera

Trabajando con esta guia, usted sera capaz de:

• Comprender la arquitectura de CPU basada en pila y como difiere de los disenos basados en registros
• Aprender como funciona el conjunto de instrucciones de la ZPU a nivel de hardware
• Ser capaz de configurar, construir y programar bitstreams FPGA para multiples placas de desarrollo
• Saber como anadir nuevas instrucciones hardware a la CPU
• Comprender la arquitectura SoC, incluyendo controladores de memoria, UARTs, temporizadores y manejo de interrupciones
• Ser capaz de escribir, compilar y ejecutar programas C en la ZPU
• Configurar builds CI/CD automatizados con Jenkins y Docker

Requisitos previos

Para obtener el maximo de esta guia, deberia tener:

• Conocimientos basicos de logica digital - Comprension de flip-flops, multiplexores, maquinas de estados y estructuras de bus
• Algo de experiencia con VHDL - Capacidad de leer declaraciones de entidades VHDL, asignaciones de senales y bloques de proceso
• Programacion en C - Familiaridad con la sintaxis C, punteros y compilacion
• Una placa de desarrollo FPGA - Una de las placas soportadas (DE10 Nano, E115, CYC1000, QMV o DE0 Nano)
• Intel Quartus Prime - Version 17.1.1 Standard Edition (o la version containerizada Docker)

Parte 1: Comprender la arquitectura ZPU

Procesadores basados en pila vs. basados en registros

La mayoria de los procesadores que encontrara (ARM, x86, RISC-V) son basados en registros: tienen un conjunto fijo de registros nombrados (R0-R15, EAX, etc.) y las instrucciones especifican con que registros operar. Por ejemplo, ADD R0, R1, R2 significa “sumar R1 y R2, almacenar en R0”.

La ZPU es un procesador basado en pila. En lugar de registros nombrados, utiliza una pila Last-In-First-Out (LIFO). Las operaciones trabajan implicitamente con los elementos superiores de la pila:

Pila antes de ADD:          Pila despues de ADD:
  ┌─────┐                    ┌─────┐
  │  3  │ ← TOS              │  7  │ ← TOS (3+4)
  ├─────┤                    ├─────┤
  │  4  │ ← NOS              │ ... │
  ├─────┤                    └─────┘
  │ ... │
  └─────┘

TOS = Top of Stack, NOS = Next on Stack.

Por que una arquitectura de pila?

1. Codificacion minima de instrucciones - No se necesitan campos de registro. ADD es solo un byte (opcode 00000101), mientras que un ADD basado en registros necesita campos de registro fuente y destino (2-4 bytes).
2. Huella FPGA muy pequena - El decodificador es trivial y requiere elementos logicos minimos.
3. Objetivo facil para el compilador - La evaluacion de expresiones se mapea naturalmente a operaciones de pila (Notacion Polaca Inversa).
4. Compromiso - Las maquinas de pila son tipicamente mas lentas por operacion que las maquinas de registros debido a la manipulacion adicional de la pila, pero el sistema de cache de la ZPU Evo mitiga significativamente esto.

El modelo de memoria de la ZPU

La ZPU tiene un espacio de memoria plano, direccionable por byte, de 32 bits. Todos los dispositivos de memoria e IO comparten este espacio:

Address Space (24-bit example, configurable):
┌──────────────────────────────────────────────┐
│ 0x000000 - 0x01FFFF : Boot BRAM (128KB)      │  ← Program + Stack
│                        Reset vector at 0x0000 │
│                        Emulation vectors      │
│                        0x0000-0x0400          │
├──────────────────────────────────────────────┤
│ 0x020000 - 0x03FFFF : Application RAM (opt)   │  ← Secondary BRAM
├──────────────────────────────────────────────┤
│ 0x040000 - 0xFEFFFF : SDRAM (optional)        │  ← External memory
├──────────────────────────────────────────────┤
│ 0xFF0000 - 0xFFFFFF : Memory-Mapped I/O       │  ← Peripherals
├──────────────────────────────────────────────┤
│ 0x1000000 - 0x1FFFFFF: Wishbone bus (optional) │  ← Extended region
└──────────────────────────────────────────────┘

Puntos importantes:

• La pila reside en la parte superior de la BRAM y crece hacia abajo
• El programa comienza en la direccion 0x0000 (configurable)
• Las direcciones 0x0000-0x0400 estan reservadas para vectores de emulacion (explicados mas adelante)
• Los dispositivos IO estan mapeados en memoria en la parte superior del espacio de direcciones
• El bus Wishbone, cuando esta habilitado, duplica el espacio de direcciones

Los cinco modelos de CPU

El SoC ZPU Evolution soporta cinco modelos de CPU intercambiables, seleccionables en tiempo de build. Solo uno puede estar activo:

Model	Logic Elements	Performance	Wishbone	Best For
Small	~400 LEs	Baseline	No	Minimum footprint applications
Medium	~600 LEs	~1.5x Small	No	Better performance, still small
Flex	~800 LEs	~1.8x Small	No	Good balance of size and speed
Evo	~2500 LEs	~3x Small	Yes	Maximum performance, full features
Evo Minimal	~1200 LEs	~2x Small	Yes	Evo with reduced instruction set

El modelo Evo anade:

• Cache de instrucciones L1 (basada en registros, configurable 8-256 entradas)
• Cache de instrucciones L2 (basada en BRAM, configurable 256-4096 bytes)
• Memory Transaction Processor (cola para operaciones de memoria)
• Bus de memoria dual (bus de sistema + bus Wishbone opcional)
• Bus de instrucciones opcional (puerto BRAM separado para fetch de instrucciones)
• Hardware Byte/Word Write (eliminacion de ciclos Read-Modify-Write)
• Soporte de instrucciones extendidas (instrucciones multi-byte)

Codificacion de instrucciones

Las instrucciones de la ZPU tienen 8 bits de ancho. La codificacion es notablemente simple:

Bit 7 = 1: IM instruction (7-bit immediate value in bits 6:0)
Bit 7 = 0:
  Bits 6:5 = 00: Core instructions (opcode in bits 4:0)
  Bits 6:5 = 01: STORESP (store to stack offset in bits 4:0)
  Bits 6:5 = 10: EMULATE (emulation vector index in bits 4:0)
  Bits 6:5 = 11: LOADSP (load from stack offset in bits 4:0)

Carga de una constante de 32 bits: Dado que cada instruccion IM solo puede transportar 7 bits, cargar un valor completo de 32 bits requiere hasta 5 instrucciones IM consecutivas. La cache L1 en la Evo permite ejecutar hasta 5 instrucciones IM en un solo ciclo, haciendo la carga de constantes muy eficiente.

Vectores de emulacion

Una caracteristica clave de la ZPU es la emulacion de instrucciones. Las instrucciones marcadas como EMULATE (bits de opcode 6:5 = 10) se bifurcan a un vector en el rango 0x0000-0x0400. Cada vector es de 32 bytes:

Vector address = instruction[4:0] * 32

Si una instruccion hardware no esta implementada (deshabilitada en la configuracion), activa la ruta EMULATE, donde el microcodigo software implementa la operacion. Esto permite que la CPU ejecute el mismo software independientemente de que instrucciones esten presentes en hardware – solo a diferentes velocidades.

Esto es lo que hace a la ZPU unicamente flexible: puede intercambiar recursos FPGA por rendimiento habilitando/deshabilitando selectivamente instrucciones hardware.

Parte 2: Estructura del proyecto

Disposicion de directorios

ZPU/
├── cpu/                          # CPU core implementations
│   ├── zpu_core_evo.vhd          # ZPU Evolution CPU (3688 lines)
│   ├── zpu_core_small.vhd        # ZPU Small CPU
│   ├── zpu_core_medium.vhd       # ZPU Medium CPU
│   ├── zpu_core_flex.vhd         # ZPU Flex CPU
│   ├── zpu_pkg.vhd               # CPU package (opcodes, config)
│   └── zpu_uart_debug.vhd        # Debug serialiser
│
├── devices/                      # Peripheral IP cores
│   ├── sysbus/                   # System bus peripherals
│   └── WishBone/                 # Wishbone bus peripherals
│
├── build/                        # FPGA board build files
│   ├── Makefile                  # Build targets for all boards/CPUs
│   └── *_zpu.qpf/qsf            # Board-specific Quartus projects
│
├── zpu_soc.vhd                   # SoC top level (2346 lines)
├── zpu_soc_pkg.vhd               # SoC configuration package
├── zpu_soc_pkg.tmpl.vhd          # Template for build system
└── README.md                     # Project documentation

Archivos fuente principales explicados

zpu_pkg.vhd - El paquete de configuracion a nivel de CPU. Contiene definiciones de opcodes, configuracion del ancho del bus de direcciones, declaraciones de componentes para los nucleos CPU, configuracion de depuracion y flags de habilitacion del bus de instrucciones.

zpu_soc_pkg.vhd - La configuracion a nivel de SoC. Contiene la seleccion del modelo de CPU, frecuencias de reloj de la placa, geometria de memoria, flags de habilitacion/deshabilitacion de perifericos, parametros de tamano de cache y constantes del mapa de memoria.

zpu_soc.vhd - El modulo SoC principal. Aqui todo se une: instanciacion del nucleo CPU seleccionado, conexion de BRAM, SDRAM, UART, temporizadores, tarjeta SD, etc.

cpu/zpu_core_evo.vhd - La implementacion de la CPU Evo (3688 lineas). Contiene el decodificador de instrucciones y la maquina de estados de ejecucion, cache L1, cache L2, Memory Transaction Processor y gestion de la pila.

Parte 3: Configurar el SoC

Los detalles completos de configuracion – seleccion del modelo de CPU, configuracion de memoria, habilitacion de perifericos y ajuste de cache Evo – son identicos a la version en ingles y se explican en detalle alli.

Parte 4: Construir los bitstreams FPGA

Si solo desea un bitstream funcional rapidamente, utilice el script de instalacion automatizada para su plataforma (vea Instalacion y build automatizados justo debajo). Instala toda la cadena de herramientas (Intel Quartus Prime Lite 17.1 y, cuando es necesario, Docker), clona el repositorio, le permite elegir la placa y la CPU, y construye hasta completar -- sin necesidad de conocimientos previos de las herramientas. Los flujos de trabajo con `Makefile`, Quartus directo y Docker que siguen son para quienes desean manejar las herramientas manualmente.

Instalacion y build automatizados (recomendado)

Los scripts de instalacion incluidos instalan todo lo necesario (Intel Quartus Prime Lite 17.1 y, cuando es necesario, Docker), clonan el repositorio si aun no esta dentro de un checkout, le permiten elegir la placa de destino y la variante de CPU, y construyen el bitstream FPGA hasta completar. Cada script es autonomo -- copie solo el unico archivo para su plataforma y ejecutelo. Han sido verificados de extremo a extremo en Windows (nativo), macOS (Intel, via Docker) y Linux.

Script	Plataforma	Notas
setup_ZPU_windows.cmd	Windows 10 / 11	Recomendado en Windows – lanzador de doble clic; mantiene la ventana abierta y registra todo en setup_ZPU_log.txt. Instalacion nativa, sin WSL.
setup_ZPU_windows_native.ps1	Windows 10 / 11	El script PowerShell subyacente (instala Git for Windows + Quartus 17.1 mediante winget / el instalador de Intel).
setup_ZPU.sh	Linux / macOS	Quartus nativo en Linux; una imagen Docker de Quartus sin interfaz grafica en macOS (solo Macs Intel – Quartus es x86-64).
build_zpu.sh	todas	Wrapper de build portable. Reejecutelo en cualquier momento para reconstruir: ./build_zpu.sh [BOARD] [CPU].

Windows – haga doble clic en setup_ZPU_windows.cmd, o desde PowerShell:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\setup_ZPU_windows_native.ps1

macOS / Linux:

chmod +x setup_ZPU.sh
./setup_ZPU.sh

Cada script pregunta que placa y variante de CPU construir (por defecto QMV / EVO) y, salvo que se ejecute dentro de un checkout, donde clonar el repositorio. Al finalizar tendra build/<BOARD>_<CPU>.sof (el bitstream de configuracion del FPGA) y un build/<BOARD>_<CPU>.rbf comprimido. Placas: QMV (por defecto), DE10_nano, DE0_nano, E115, CYC1000; CPUs: EVO (por defecto), EVO_MINIMAL, FLEX, MEDIUM, SMALL.

Para reconstruir mas tarde sin volver a ejecutar la instalacion (en Windows Git Bash, primero export PATH="/c/altera/17.1/quartus/bin64":$PATH):

./build_zpu.sh E115 EVO           # placa + CPU
./build_zpu.sh --list             # lista todas las placas / CPUs
ZPU_RTL_METHOD=docker ./build_zpu.sh QMV EVO   # fuerza la imagen Docker sin interfaz grafica

Variables de entorno utiles: ZPU_REPO_URL (repositorio a clonar; por defecto el publico https://git.eaw.app/eaw/zpu.git), ZPU_BOARD / ZPU_CPU (omitir las preguntas), ZPU_RTL_METHOD=native|docker, ZPU_DIR (construir en un checkout existente) y ZPU_QUARTUS_BIN (apuntar a un Quartus bin/bin64 existente).

Uso del Makefile

La forma mas sencilla de construir es el Makefile en el directorio build/:

cd ZPU/build
make DE10_nano_EVO        # DE10-Nano con CPU Evo
make E115_SMALL           # E115 con CPU Small
make CYC1000_MEDIUM       # CYC1000 con CPU Medium

Que sucede durante un build:

1. El Makefile copia zpu_soc_pkg.tmpl.vhd y establece el modelo CPU seleccionado a 1 mediante sed
2. El zpu_soc_pkg.vhd generado reemplaza al existente
3. Quartus ejecuta la sintesis – convierte VHDL en una netlist
4. Quartus ejecuta el fitter (Place & Route) – mapea a los recursos FPGA reales
5. Quartus ejecuta el ensamblador – genera el archivo de programacion .sof
6. quartus_cpf convierte el .sof a .rbf (Raw Binary Format)

Partes 5-6: Conjunto de instrucciones y adicion de nuevas instrucciones

Las tablas completas del conjunto de instrucciones (instrucciones nucleares, instrucciones emulables, instrucciones extendidas) y la guia paso a paso para anadir nuevas instrucciones hardware se encuentran en la version en ingles.

Parte 7: El ecosistema de software -- IOCP, zOS y aplicaciones

Vision general de las capas de software

La pila de software estandar en un sistema ZPU Evolution es:

┌───────────────────────────────────────────────────┐
│              Aplicaciones                          │
│  (ed, kilo, tbasic, mbasic, Benchmarks,            │
│   programas propios -- cargados desde SD card)      │
├───────────────────────────────────────────────────┤
│         zOS -- Sistema Operativo                    │
│  (Shell, sistema de archivos, 80+ comandos,         │
│   carga de apps, gestion de memoria, interrupciones)│
├───────────────────────────────────────────────────┤
│         IOCP -- Cargador de arranque                │
│  (Init hardware, arranque desde SD card, carga      │
│   serial, monitor de memoria -- integrado en BRAM)  │
├───────────────────────────────────────────────────┤
│         ZPU Hardware (FPGA)                         │
│  (CPU, BRAM, SDRAM, UART, SD, Timer, Interrupts)    │
└───────────────────────────────────────────────────┘

La secuencia de arranque es: FPGA encendido -> IOCP ejecuta desde BRAM -> IOCP carga zOS desde SD card -> zOS presenta una shell -> el usuario ejecuta aplicaciones.

IOCP -- El cargador de arranque

IOCP (I/O Control Program) es el primer codigo que se ejecuta cuando la ZPU se enciende. Esta integrado directamente en la Block RAM del FPGA durante la sintesis, por lo que siempre esta disponible – no se necesita tarjeta SD ni memoria externa para su ejecucion.

Los niveles de funcionalidad de IOCP van desde Full (~40 KB con todos los comandos) hasta Tiny (~3-5 KB, solo bootstrap). Los detalles sobre protocolos de carga serial, comandos y disposicion de memoria se encuentran en la version en ingles.

zOS -- El sistema operativo

zOS (ZPU Operating System) es el sistema operativo estandar para la ZPU Evolution. Proporciona una shell de linea de comandos, soporte completo de sistema de archivos, gestion de memoria y la capacidad de cargar y ejecutar aplicaciones desde la tarjeta SD – comparable a como CP/M o el primer DOS proporcionaban un entorno de linea de comandos para ejecutar programas.

Las funcionalidades de la shell de zOS incluyen: 80+ comandos, edicion de linea tipo Readline con historial, soporte AUTOEXEC.BAT y un sistema de ayuda.

Aplicaciones

Aplicaciones incluidas: ed (editor de texto VT100), kilo (editor VT100 avanzado), tbasic (interprete Tiny BASIC), mbasic (Mini BASIC v1.0), dhry (Dhrystone v2.1 benchmark), coremark (CoreMark v1.0 benchmark).

Construir el software

Todo el software ZPU (IOCP, zOS y aplicaciones) se construye desde el repositorio zOS con un script build.sh unificado. Los parametros de build completos y comandos de ejemplo se encuentran en la version en ingles.

Partes 8-13: Temas avanzados

Las secciones completas sobre Software personalizado, Arquitectura SoC, Configuracion especifica de placa, CI/CD, Depuracion y Recursos adicionales se encuentran en la version en ingles de este documento.

Ejercicios para estudiantes

1. Basico: Construir la ZPU Small para su placa. Conectar un terminal a 115200 baudios e interactuar con IOCP.
2. Intermedio: Modificar zpu_soc_pkg.vhd para cambiar el tamano de la BRAM. Observar el impacto en el espacio de pila disponible.
3. Intermedio: Habilitar el controlador PS2 y conectar un teclado. Escribir un programa C que devuelva las pulsaciones de teclas.
4. Avanzado: Anadir una instruccion hardware SWAP (como se describe en la Parte 6). Verificarla con ensamblador inline.
5. Avanzado: Portar el diseno a una nueva placa FPGA actualmente no soportada.
6. Experto: Implementar una nueva instruccion extendida utilizando el mecanismo EXTEND.