Digital design lab: Verilog, VHDL and yosys on one private Ubuntu VM

What students learn

How a circuit is described and tested. A half adder is given and a full adder is written, in Verilog and again in VHDL, so the same circuit is seen in both languages. A counter shows what a clock does: its signals are recorded in a VCD file and read as rows of text. Then the student finishes a 4-bit counter with an enable and a synchronous reset, and counts the gates yosys makes from it, which shows that a flip-flop remembers a bit and a latch is a mistake.

The five parts

First a combinational circuit in Verilog: read the truth table of a half adder, then write a full adder. Second a clock and a waveform: a given counter, its VCD file, vcd2txt and vcd2svg. Third the same full adder in VHDL with GHDL’s three steps, analyse, elaborate and run. Fourth a counter with enable and reset, finished by the student. Fifth yosys, with hdl gates, to see how many cells a design needs. Everything the student edits is in the folder hdl, and README.md in the home folder says what to do and gives none of the answers.

Run it in your browser

VM labs are set as a lab task in a module, and the sample is on the lab’s page. The machine is small: one CPU, 1 GB of memory and 10 GB of disk. The simulators use a few megabytes of it.

1. Add the lab. In a module you teach, add a task and choose the Ubuntu VM lab card. The page shows a short description of the machine instead of a compose file.
2. Start from the sample. The page offers ready-made labs to start from. Choose Digital design. Using a sample replaces the text, and Undo brings yours back.
3. Publish and start your own copy. Publish, then Start. The lab’s own setup script installs Icarus Verilog, GHDL and yosys from Ubuntu’s archive and writes the helper commands, the files to work on and the README, the first time the VM starts, in a few minutes.
4. Open the terminal. Open its terminal and read README.md in the home folder. The lab’s port 8000 shows the folder of pictures the student draws.

A basic lesson on this lab

Digital Design Basics is a small lesson worked in this lab, which is an Ubuntu VM. It has a hook, an I can outcome, key words, a starter, a check after each idea, a common mistake and an exit check, and each step has a Run button that types its command into the machine’s terminal. A student reads a half adder, simulates it and reads its truth table, runs a counter and reads its waveform as text, and simulates the same half adder in VHDL with GHDL.

The lesson looks around and leaves the lab’s own task, the full adder and the counter, to the student, so it hands out no answers.

How it is marked

The lab has a check. It runs on a copy of the saved machine and compiles three of the student’s files, full_adder.v, full_adder.vhd and counter4.v, with testbenches the student never sees. Each testbench holds a reference model and compares it with the design, the counter before and after every clock edge, so a reset that is not synchronous is caught. The testbench prints a result line with a number the check draws afresh, so a design cannot print the right line itself, and a design that calls finish or system is refused. Then yosys must read the design with no latch, and the counter needs flip-flops and no more cells than a plain design. The first line of what the check printed says why.

1. Hand it out. Assign the lab like any task, with a due date if you want one. Each student gets a VM of their own, kept between sessions.
2. Run the check. On a student’s row in the class list, press Run the check. It starts a copy of their saved machine that is not saved back, runs the lab’s check script as root and shows whether it passed, what it printed and when. The student is not told the result.
3. Mark it. Read the first line of what the check printed: it says what is not right, such as hidden checks that gave a wrong output or a design that makes a latch. Send the work back with a reason if it needs more.

The definition on GitHub

The file is the whole lab definition, the same text the platform runs: size, port, setup script, helper commands, the files to work on, the README and the check. Copy it and change the circuits or the testbenches to make a longer lab.

• The repository on GitHub
• The lab definition for this lab
• The README
• The licence (MIT)

Try this lab, and what it costs

A free personal account can work through the basic lessons in this lab, with enough free credit each month to follow most lessons and no card. For a class, a school or college has its first 365 days free for up to 50 students, then pays per student a year, with every lab included and staff free.

• Prices for schools and colleges
• Open a free account or set up your school

Questions people ask

Does the lab need a licence or a board?

No. Icarus Verilog, GHDL and yosys are open source and in Ubuntu’s archive. They are installed when the student’s VM starts, so we distribute none of them. No board is needed because nothing is placed or routed.

Why are waveforms read as text?

A graphical viewer needs a desktop, which a terminal VM does not have. The lab reads a VCD file as rows of text with vcd2txt and draws a picture with vcd2svg. Ubuntu 26.04 gives GHDL with the GCC backend, which compiles the testbench to a program, so ghdl -e writes an executable beside the files.

Can students harm anything?

Only their own copy. The machine of a visitor without an account reaches Ubuntu’s archive and nothing else, and if a student breaks a file, hdl reset puts it back as it was given.

Was the lab tested in a real student VM?

The setup, the lesson’s commands and the check, with each way of faking it, were run in a real Ubuntu 26.04 container standing in for the VM, on an arm64 machine. A booted student VM, which serves the pictures from a systemd unit on port 8000, and the amd64 packages of the student machines are worth one try before a class.