THUMDER

THe UltiMate Dlx EmulatoR: un simulador del procesador DLX para aprender cómo funciona un pipeline, ciclo a ciclo.

Abrir en el navegador | Descargar la aplicación de escritorio | Documentación

Español | English

¿Qué es THUMDER?

THUMDER es un simulador visual y un entorno de desarrollo para el repertorio de instrucciones DLX, la arquitectura RISC de Hennessy y Patterson con la que se enseña la segmentación. Escribes un programa en ensamblador, lo cargas y ves, ciclo a ciclo, cómo avanza cada instrucción por el pipeline, qué registros y qué posiciones de memoria cambia, y por qué se detiene.

Todo ocurre en tu navegador o en la aplicación de escritorio (Windows, Linux y macOS): el motor de simulación es propio, corre en un Web Worker y no necesita servidor ni cuenta. En el móvil se usa como una aplicación, e incluso se puede instalar en la pantalla de inicio.

Qué puedes hacer

Programar

• Un editor de ensamblador DLX (Monaco) con resaltado, errores al momento, puntos de ruptura y símbolos.
• Un gestor de ficheros con carpetas, importación y descarga de .s y .zip, 20 ejemplos clásicos comentados, de «Hola, mundo» a un DAXPY desenrollado, y 5 para SuperDLX.

Simular

• Ensamblado a código máquina DLX real y simulación del pipeline de WinDLX: IF, ID, EX, MEM y WB, adelantamiento, detenciones y unidades de coma flotante configurables.
• Dos arquitecturas, elegidas en la cabecera: DLX y SuperDLX, un DLX superescalar con ejecución fuera de orden como el de WinSuperDLX (varias instrucciones por ciclo, ventanas de instrucciones, ROB, buffers de cargas y almacenamientos y predicción de saltos), con todos sus parámetros configurables. El mismo programa acaba igual en las dos: solo cambian los ciclos.
• Ejecución continua, ciclo a ciclo, hasta el final sin dibujar y paso atrás. Los atajos son los de un depurador y no chocan con los del navegador: Ctrl+F9 carga, F9 ejecuta o pausa, F8 avanza un ciclo, Mayús+F8 retrocede y Mayús+F9 va al final.
• Consola de entrada y salida para los traps del programa, y sonido opcional: cada ciclo es un arpegio sobre una progresión de acordes, las instrucciones que terminan llevan la melodía y las detenciones y los saltos tomados se oyen.

Entender lo que pasa

Pipeline	Cada instrucción en su etapa y en las unidades de coma flotante. Con cada ciclo se desplaza a la siguiente, y el pie explica qué hace cada etapa con la suya y qué valores mueve.
Ruta de datos	El camino de los datos en el ciclo: el PC que lee la memoria de instrucciones, el banco de registros, la ALU, la memoria de datos, los registros entre etapas (IF/ID, ID/EX, EX/MEM, MEM/WB) y los adelantamientos que se usan.
Diagrama de ciclos	La historia del pipeline. Al pulsar un atasco, THUMDER explica qué registro faltaba, qué instrucción lo produce y si el adelantamiento lo habría evitado. Se exporta a SVG, PNG y CSV.
Registros y memoria	Todos los registros y cada palabra de la memoria, en binario, hexadecimal, enteros, IEEE 754 o instrucciones. Lo que escribe o lee el último ciclo se resalta, y cualquier valor se edita bit a bit.
Código y estadísticas	Qué hace cada instrucción del programa y en qué etapa está. Los ciclos, el CPI, las detenciones por tipo y la comparación con y sin adelantamiento.

Practicar

• Ejercicios guiados que THUMDER comprueba con la propia simulación, y programas compartidos como ejercicio con un enlace.
• Una vista múltiple con varias ventanas a la vez, que se ordenan arrastrando o flotan sobre las demás. En el móvil se eligen con chips.
• La documentación dentro de la aplicación: cómo se usa THUMDER, la arquitectura DLX y un explorador de las 102 instrucciones (su sintaxis, su codificación campo a campo y qué hace en cada etapa), con buscador y el mapa de códigos de operación.

En cualquier sitio

• Sin cuenta: se usa como invitado y los ficheros se guardan en el navegador. Con una cuenta se sincronizan entre dispositivos.
• Para móvil: título de la vista arriba, controles de la simulación abajo al alcance del pulgar y vistas que se desplazan con el dedo.
• Accesible: tema claro u oscuro, alternativas en texto a cada diagrama y comprobación con axe (WCAG 2.1 AA) en cada vista.

Empieza en un minuto

1. Abre https://thumder.netlify.app. En el móvil, el menú del navegador ofrece «Añadir a la pantalla de inicio».
2. En Gestor de ficheros → ejemplos, abre por ejemplo 19-riesgos.s.
3. Pulsa Cargar (Ctrl+F9) y avanza con Paso (F8), mirando el Pipeline y el Diagrama de ciclos.

La aplicación de escritorio está en las versiones: AppImage para Linux, instalador y portable para Windows, y .dmg y .zip para macOS. No está firmada. Cómo instalar cada versión, también la de Android: Instalar THUMDER. Paso a paso: Primeros pasos.

El simulador

THUMDER ensambla los programas en código máquina DLX real, los carga en memoria y los simula ciclo a ciclo con el pipeline de WinDLX: adelantamiento, detenciones, unidades de coma flotante configurables, traps de entrada y salida, y estadísticas.

• Cómo funciona y cómo se comprueba: docs/simulador.md.
• SuperDLX, el DLX superescalar: docs/superdlx.md.
• El manual de WinDLX en el que se basa: docs/manual-simulador-dlx.md.
• Los 20 ejemplos de DLX y los 5 de SuperDLX, explicados: docs/ejemplos-dlx.md. Están siempre en la carpeta «ejemplos» del gestor de ficheros, de solo lectura, junto a «ejercicios» con los programas de los ejercicios guiados. Si cambias uno, se guarda una copia en tus ficheros.

Desarrollo

Requisitos: Node.js 22 (o 20.19 o posterior) y pnpm 10. corepack enable instala la versión de packageManager.

git clone git@github.com:nonodev96/THUMDER.git
cd THUMDER
pnpm install
pnpm run ng:serve:dev   # http://localhost:4200

pnpm install crea los ficheros de entorno (src/environments/environment.{dev,web,production}.ts) a partir de src/environments/_environment.ts. Están en .gitignore porque llevan las claves de Firebase:

• Sin claves de Firebase (modo local): no hay cuentas, se entra como invitado, los ficheros se guardan en el navegador (IndexedDB) y no hay analítica. Es lo que hace falta para desarrollar y para las pruebas.
• Con claves de Firebase: también se entra como invitado, y una cuenta (correo, Google o GitHub) sincroniza los ficheros con Firestore. Solo hay analítica si se acepta en el aviso de privacidad, y los informes de errores se pueden desactivar en él (ver la política de privacidad). Las reglas de Firestore están en firestore.rules y se prueban con pnpm test:rules.

Comando	Qué hace
pnpm run ng:serve:dev	Arranca la aplicación web en http://localhost:4200
pnpm start	La aplicación web y Electron a la vez (Electron carga localhost:4200)
pnpm test	Pruebas unitarias (Vitest)
pnpm test:electron	Pruebas unitarias de la aplicación de escritorio (src-electron), sin abrir Electron
pnpm test:rules	Las reglas de Firestore en el emulador (necesita Java)
pnpm e2e	Pruebas e2e (Playwright) en escritorio, móvil y tableta, con axe; arranca ng serve
pnpm e2e:electron	Compila la aplicación de escritorio y la prueba (en Linux sin pantalla: xvfb-run -a)
pnpm run lint	Lint y formato (Biome)

Cómo contribuir (estructura, convenciones, pruebas y publicación): CONTRIBUTING.md.

Pruebas e2e

Están en e2e/ y usan Playwright. La primera vez hay que instalar el navegador con pnpm exec playwright install chromium.

• pnpm e2e hace las comprobaciones en escritorio (1440×900), móvil (Pixel 7) y tableta (820×1180), sin errores en la página, y las de móvil y tableta también con WebKit, el motor de iOS (iPhone 15 e iPad). Cubre la interfaz, la simulación, los ejemplos, la configuración, las herramientas para aprender, la interfaz adaptable en 5 tamaños y la accesibilidad de cada vista en los dos temas.
• pnpm e2e:electron prueba la aplicación de escritorio: que carga con file:// y sin Node.js en la página, la barra de título, el tema, el menú y las tarjetas maximizadas. Cada prueba usa su propia carpeta de datos, así que no toca la de quien la ejecuta.

Las pruebas que dependen de un tamaño llevan la etiqueta @movil o @tableta. Las capturas y las trazas de las que fallan quedan en test-results/, y el informe, en playwright-report/.

Compilación y despliegue

Comando	Qué hace
pnpm run ng:build:production	Aplicación web optimizada en dist/browser (la que se despliega en Netlify)
pnpm run build:prod	Aplicación para Electron (--base-href ./) y el proceso principal en dist-electron/
pnpm run electron:build	Ejecutable de escritorio en release/: AppImage, instalador y portable de Windows, .dmg y .zip de macOS
pnpm run mobile:build	La web para las aplicaciones de Android e iOS, copiada en sus proyectos (src-mobile/): ver docs/movil.md

Una versión se publica con pnpm version minor (o patch), que escribe su sección en CHANGELOG.md a partir de los commits convencionales y crea la etiqueta, y luego con git push --follow-tags. Los flujos de GitHub Actions:

Flujo	Cuándo	Qué hace
ci.yaml	cada push a dev y master y cada PR	lint, compilación, pruebas unitarias, reglas de Firestore, e2e (Chromium, WebKit y la aplicación de escritorio) y la compilación de las aplicaciones de Android e iOS
deploy-netlify.yaml	etiqueta v* o a mano (Run workflow)	pruebas unitarias, compilación, atestaciones y SBOM de la web, y despliegue en producción en Netlify
	cada PR y cada push a dev	vista previa en https://pr-<número>--<sitio>.netlify.app y https://dev--<sitio>.netlify.app
create-release.yaml	etiqueta v*	un borrador de versión con los ejecutables de Linux, Windows y macOS (y el AAB y el APK de Android, si está su clave), los latest*.yml, las notas del CHANGELOG, el SBOM y las atestaciones de cada ejecutable

Las acciones de los flujos están fijadas por su commit (una etiqueta se puede mover; un commit, no), y Dependabot propone cada semana sus versiones nuevas (.github/dependabot.yml).

Verificar las descargas

THUMDER no tiene firma de código de Windows ni de macOS (son certificados de pago): SmartScreen y Gatekeeper avisan la primera vez. Lo que sí tiene cada versión es su cadena de suministro comprobable:

• Procedencia (SLSA v1, en formato in-toto): cada ejecutable, y cada fichero de la web, tiene una atestación que dice de qué repositorio, de qué commit y de qué flujo salió (SLSA Build nivel 2). La firma GitHub Actions con Sigstore, sin claves: un certificado de pocos minutos emitido para la identidad del flujo, que queda en el registro público de transparencia.
• SBOM: la lista de lo que lleva THUMDER, en CycloneDX y SPDX, hecha con Syft a partir de pnpm-lock.yaml. Incluye todo con lo que se construye: las dependencias de la aplicación (Electron entre ellas, que va en los ejecutables) y las de compilación y pruebas, y las acciones de los flujos. También está atestada.

Un ejecutable descargado de una versión se comprueba con la CLI de GitHub:

gh attestation verify THUMDER-v1.12.1-linux-x86_64.AppImage --repo nonodev96/THUMDER \
  --signer-workflow nonodev96/THUMDER/.github/workflows/create-release.yaml
# Su SBOM
gh attestation verify THUMDER-v1.12.1-linux-x86_64.AppImage --repo nonodev96/THUMDER --predicate-type https://cyclonedx.org/bom

La versión tiene además los SBOM (THUMDER-v<versión>-sbom.cdx.json y .spdx.json) y las atestaciones de cada sistema (THUMDER-v<versión>-<sistema>-provenance.sigstore.json y -sbom.sigstore.json), en el formato de Sigstore. Se comprueban sin conexión con gh attestation verify <fichero> --bundle <atestación> --repo nonodev96/THUMDER, o con cosign (--type cyclonedx para la del SBOM):

cosign verify-blob-attestation --bundle THUMDER-v1.12.1-linux-provenance.sigstore.json --type slsaprovenance1 \
  --certificate-identity-regexp '^https://github.com/nonodev96/THUMDER/.github/workflows/create-release.yaml@refs/tags/v' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com THUMDER-v1.12.1-linux-x86_64.AppImage

La web de producción publica sus sumas SHA-256 y su SBOM en /integrity/ (sha256sums.txt, sbom.cdx.json y sbom.spdx.json), y cada fichero tiene su atestación. Por ejemplo, el código principal de la aplicación:

curl -O https://thumder.netlify.app/integrity/sha256sums.txt
main=$(grep -oE 'main-[A-Z0-9]+\.js$' sha256sums.txt)
curl -O "https://thumder.netlify.app/$main"
sha256sum -c --ignore-missing sha256sums.txt
gh attestation verify "$main" --repo nonodev96/THUMDER --signer-workflow nonodev96/THUMDER/.github/workflows/deploy-netlify.yaml

Las páginas HTML son la excepción: Netlify les añade un comentario al servirlas, así que no coinciden byte a byte con lo compilado. Y _redirects es la configuración de Netlify: está en las sumas, pero no se sirve.

Para desplegar en Netlify hacen falta dos secretos del repositorio:

• NETLIFY_AUTH_TOKEN: un token personal de Netlify (User settings → Applications).
• NETLIFY_SITE_ID: el identificador del proyecto (Project configuration → Project ID).

Con el secreto opcional ANGULAR_ENVIROTMENT_PRODUCTION (el fichero src/environments/environment.production.ts en base64), la web lleva las claves de Firebase; sin él se compila en modo local. Los PR de forks y de Dependabot no tienen acceso a los secretos y no se despliegan.

La ventana de escritorio (src-electron/) es la de una aplicación del sistema:

• En Windows y Linux no hay barra de título ni menú de Electron: la barra de navegación de THUMDER hace de barra de título (mueve la ventana y la maximiza con doble clic) y los botones de minimizar, maximizar y cerrar se dibujan sobre su derecha, con los colores del tema. macOS conserva su barra de título y su barra de menús.
• El tema «el del sistema» sigue al escritorio y cambia con él. En Linux, además de lo que lee Chromium (la preferencia del portal y el tema GTK), cuenta el tema del propio escritorio (Cinnamon, GNOME, MATE), que puede tener los paneles oscuros y las aplicaciones claras. Los menús, las barras de desplazamiento y los diálogos nativos siguen el tema elegido.
• El menú tiene el zoom (Ctrl++, Ctrl+-, Ctrl+0), la pantalla completa, copiar y pegar, y la ayuda (F1), en el idioma de THUMDER.
• Una tarjeta maximizada empieza debajo de la barra de navegación: sus botones no quedan bajo los de la ventana, y la barra sigue siendo la de título, con los controles de la simulación a mano.
• El menú y la bandeja usan las traducciones de THUMDER (la sección DESKTOP de src/assets/i18n), igual que la página.
• La ventana se abre sin destellos con el color del tema, recuerda su tamaño y su sitio (desktop.json, en la carpeta de datos de la aplicación), y abrir THUMDER otra vez muestra la que ya está abierta. Tiene un icono en la bandeja del sistema.
• Los iconos de los instaladores están en build/ (icons/ para Linux, icon.ico y icon.icns).

La aplicación de escritorio no da a la página acceso a Node.js: lo que necesita de Electron (abrir enlaces en el navegador, el tema del escritorio, la altura de la barra de título y las rutas del menú) lo expone el preload como window.thumder, y el proceso principal solo atiende a las páginas de THUMDER y comprueba lo que le envían. La página tiene una política de seguridad de contenidos (CSP en src/index.html) sin eval ni scripts en línea, y el paquete de escritorio solo lleva dist-electron/ y la aplicación compilada.

src-electron/
  shared/contract.ts   el contrato entre las tres partes: los canales, sus datos y window.thumder (solo tipos)
  preload/             window.thumder (en el sandbox: solo usa tipos del contrato)
  main/
    index.ts           el punto de entrada: una sola instancia
    app.ts             une las piezas: ajustes, tema, ventana, menús, bandeja e IPC
    environment.ts     dónde se ejecuta: rutas de la aplicación, de sus assets y del preload
    settings.ts        lo que recuerda (desktop.json)
    i18n.ts            los textos, de src/assets/i18n
    ipc.ts             lo que pide la página, validado (validation.ts)
    links.ts           qué es una página de THUMDER y qué se abre en el navegador
    menu/              las plantillas del menú y de la bandeja
    theme/             el tema de la ventana y el del escritorio de Linux (gsettings)
    window/            la ventana y sus medidas (dónde se abre, la altura de sus botones, el zoom)

Lo que no necesita Electron (los ajustes, el tema, los menús, los textos, las medidas, la validación) recibe lo que usa de Electron por parámetro y tiene sus pruebas al lado (*.spec.ts, pnpm test:electron). La ventana se prueba con pnpm e2e:electron.

Android e iOS

Las aplicaciones de Android e iOS son la misma aplicación Angular dentro de Capacitor (capacitor.config.ts y src-mobile/): ocupan toda la pantalla con las barras del sistema del color del tema, el botón atrás de Android cierra lo que está abierto antes de volver, los enlaces externos se abren en el navegador del sistema, guardar un fichero abre el menú de compartir y el inicio de sesión con Google, GitHub y Apple es el del sistema. Se compilan con pnpm run mobile:android y pnpm run mobile:ios; cómo configurarlas, firmarlas y publicarlas está en docs/movil.md.

Documentación

La documentación está dentro de THUMDER (Documentación, en el menú lateral), en docs/ y en la wiki, en español y en inglés:

• Empezar: ¿Qué es THUMDER?, Primeros pasos e Instalar THUMDER.
• Usar THUMDER: Ficheros y editor, Simular un programa, Las vistas, Configuración, Cuenta y privacidad y Preguntas frecuentes.
• Aprender DLX: El pipeline de DLX, SuperDLX, Ejemplos comentados y Ejercicios.
• Referencia: la tabla de instrucciones (dentro de THUMDER), el juego de instrucciones y los códigos de operación, en inglés, y el manual de WinDLX, en español.
• Desarrollo: Cómo contribuir, El simulador por dentro y Las aplicaciones de Android e iOS.

Licencia

MIT © Antonio Mudarra Machuca. THUMDER nació como Trabajo Fin de Grado en la Universidad de Jaén.