VHDLearn

Learn VHDL in your browser - write real hardware, simulate it with GHDL, and watch the waveform.

VHDLearn is an interactive, browser-based platform for learning digital design in VHDL. You write real VHDL in a Monaco editor, a backend compiles and simulates it with GHDL, and the resulting waveform is rendered live as SVG. A ten-lesson curriculum takes you from a single logic gate to a complete, self-verified traffic-light controller - with automatic, behavior-based grading.

Live demo: vhdlearn-1019019880712.us-central1.run.app No install required - it runs in the browser against a hosted GHDL backend.

---

What it does

• Two modes. Learn walks you through guided lessons with hidden testbenches that grade your design automatically; Just Code is a free playground - bring your own design and testbench.
• Real simulation. Every Run invokes ghdl -a / -e / -r on your VHDL plus a hidden testbench, producing an actual VCD - not a fake or hard-coded result.
• Live waveforms. The VCD is parsed and drawn as a zoomable, scrubbable SVG: scalar signals as step lines, buses as hex/binary lanes.
• Device visualizations. Lessons drive live widgets - LEDs, 7-segment digits, a traffic light, an animated state diagram - that play back in sync with the waveform.
• Behavioral grading. Challenges are graded on what your circuit actually does (a self-checking testbench), so any correct implementation passes, not just one exact string.
• In-app feedback. A "Report a problem" button on every screen sends a bug report with the lesson, your code, and the last error attached.

The one architectural decision that defines everything

GHDL cannot run in the browser. GHDL is a compiler, not an interpreter - every backend ends in native machine code, which a WASM sandbox forbids, and there is no usable ghdl.wasm. So VHDLearn is deliberately a browser frontend + a thin GHDL backend, not a 100% client-side app. The frontend is a single self-contained index.html; the backend is a small hardened Node/Express service that shells out to GHDL inside a locked-down container.

vhdl-poc/
├─ Dockerfile             # node:20 + native GHDL (mcode) + bundled frontend
├─ docker-compose.yml     # container hardening (read-only FS, cap_drop, limits)
├─ backend/
│  ├─ server.js           # Express: /api/simulate, /api/lessons, /api/feedback, ...
│  └─ lessons/<id>/       # lesson.json (the course content) + hidden tb.vhd
└─ frontend/
   └─ index.html          # Monaco editor + VCD parser + SVG waveform + lesson engine

Run it locally

docker compose up --build      # serves the app + API on http://localhost:8080

Lesson files are baked into the image at build time, so rebuild after editing anything under backend/lessons/.

Without Docker (needs native GHDL on the host, e.g. apt install ghdl):

cd backend && npm install && npm start

Tech stack

• Frontend: vanilla JS, Monaco editor, Tailwind (CDN), hand-written VCD parser and SVG waveform renderer - intentionally a single file, no build step.
• Backend: Node.js + Express, shelling out to GHDL (mcode).
• Packaging: Docker; deployable to any container host.

Security model - running untrusted VHDL

ghdl -r executes native code generated from user input, so isolation is mandatory.

• Per request (server.js): new process group with SIGKILL on a wall-clock timeout; ulimit caps on CPU, memory, file size, and process count (fork-bomb guard); bounded stdout/stderr/VCD; --stop-time bounds simulation time; a concurrency limiter; body-size cap; lesson-id path-traversal guard; per-request temp dir deleted afterward. Per-IP rate limits on /api/simulate and /api/feedback. CORS lockable to a single origin via ALLOWED_ORIGIN.
• Per container (docker-compose.yml): non-root user, read-only root filesystem with an in-memory /tmp, cap_drop: ALL, no-new-privileges, and pids/memory/CPU limits.
• For a fully public deployment: run on a host that adds kernel-level isolation (e.g. Google Cloud Run, which sandboxes every container under gVisor), keeping the per-request and per-container limits above as defense in depth.

See .env.example for configuration (access gate, rate limits, telemetry, feedback webhook).

The course

Ten lessons plus a foundations primer, built on progressive disclosure:

0. Anatomy of VHDL · 1. Logic Gates · 2. Combinational Logic & Buses ·
1. Combinational Building Blocks · 4. Processes & Sequential Statements ·
2. Sequential Logic - Memory & Clock · 6. Registers, Counters & Timing ·
3. Finite State Machines · 8. Structural Design & Hierarchy ·
4. Testbenches & Verification · 10. Final Project: Traffic Light Controller

License

MIT © Dvir Ben Hamo