VHDL projects
Design in VHDL: make or import a VHDL project, simulate it in GHDL, synthesize it and build the chip.
On this page
What works with VHDLStart a VHDL projectBring a VHDL project in from GitHubWhen does a VHDL test pass?If you add a file or rename an entityMore with VHDLYou can design in VHDL as well as Verilog and SystemVerilog. A VHDL project goes through the same steps: Simulate, Synthesize and Build the chip.
What works with VHDL#
| Step | What happens with VHDL |
|---|---|
| New project | Choose VHDL as the language. You get an 8-bit counter (rtl/top.vhd) and its test (tb/tb_top.vhd). |
| Import from GitHub | .vhd and .vhdl files are taken, as well as .v and .sv. |
| Simulate | Your VHDL testbench runs in GHDL 4.1 (VHDL-2008). The Results page names the file and line where it stopped, with Open at line. |
| Waveform | Shown after Simulate, as for Verilog. |
| Synthesize | Yosys reads the VHDL through GHDL, then shows the cells and the block diagram. |
| Build the chip | OpenLane's VHDL flow builds the layout on SKY130, GF180MCU or IHP SG13G2 (and ASAP7, learning only: see below). Two Verilog-only checks (Verilator lint and the EQY equivalence check) do not run for VHDL. |
| Nelix Agent | Debug with Nelix Agent on a failed test finds the cause, writes a fix and tests it on a copy. A VHDL fix can be labelled Verified when it passes your tests and the formal rules written from your design description (see Verified fixes for VHDL below); otherwise it is Passes your tests at best, so read the change before you accept it. |
Start a VHDL project#
On the Projects page, choose New project, give it a name, choose VHDL under Language, pick a Process and choose Create project. The starter is an 8-bit counter with a test that passes, so Simulate passes straight away.
Bring a VHDL project in from GitHub#
- Choose Import from GitHub and paste the address of a public repository (or a folder in it).
- Tick the design's
.vhdfiles and one testbench. The testbench is kept intb/and never goes into the chip. - Choose the top entity: the chip itself, not the testbench.
- Keep Python (cocotb) tests ticked if you want them to run: Simulate runs them on the VHDL design (see More with VHDL).
When does a VHDL test pass?#
- The testbench runs to its end, no assertion of severity error or failure fires, and no line says FAIL, FAILED, ERROR or FATAL.
- The usual old ending, one
report "... completed" severity failure;(orassert false report "... passed" severity failure;), counts as a pass when nothing else failed. - Time limit: a testbench still running after 100 ms of simulated time is stopped and does not pass. If yours should run longer, or its clock never stops, add a line to the
Makefile, for exampleSIM_STOP_TIME = 1ms: the run then ends there and passes when nothing failed. - A testbench still running after 4 minutes of real time is stopped.
- Designs that use
ieee.std_logic_arithorieee.std_logic_unsignedwork: GHDL runs with-fsynopsys.
If you add a file or rename an entity#
Change the Makefile (VHDL_SOURCES, TOPLEVEL, TB_SOURCES, TB_TOPLEVEL), hierarchy -top in synth.ys, and DESIGN_NAME and VHDL_FILES in openlane/config.json.
In a mixed Verilog + VHDL project (below), a VHDL file goes in NELIX_VHDL_SOURCES in the Makefile and nowhere else. A Verilog file goes in VERILOG_SOURCES, in a read_verilog line in synth.ys, and in VERILOG_FILES in openlane/config.json. Keep gen/vhdl_parts.v in all three. If a step is missing, the run stops and names it.
More with VHDL#
- Python (cocotb) tests on a VHDL design: Simulate runs them with cocotb and GHDL. The GitHub import keeps them ticked. To add one by hand, the
MakefileneedsTOPLEVEL_LANG = vhdl,SIM = ghdl,COCOTB_TEST_MODULES = <test name>and the lab's lineGHDL_BIN_DIR = /opt/nelix-ghdl/bin. - Verilog and VHDL in one project: choose Verilog + VHDL on the New project page, or keep both kinds of file ticked in the import. The lab translates the VHDL into Verilog (GHDL + Yosys) before each Simulate, Synthesize and Build the chip, then everything runs as Verilog. Your own files are never changed. VHDL names follow the spelling your Verilog uses; a VHDL block uses its default generics or plain numbers set from Verilog, and the same block can be used with different settings (each is translated on its own).
- VHDL on ASAP7 (learning only), from the same translation.
- Memory files (
.mem,.hex,.data,.dat) taken by the import and put where the design reads them. With several Verilog testbenches, the import picks the one for the top you chose. - Generics of the top entity: Build settings lists the top's generics; set whole-number ones (for example
WIDTH=16) and Simulate, Synthesize and Build the chip all use them. With a VHDL testbench, the testbench must declare the same generic and pass it on (WIDTH => WIDTH), so the chip you build is the design you tested. - Nelix Agent fixes also work on projects with Python (cocotb) tests on VHDL and on mixed Verilog + VHDL projects: the Agent runs the same translation and the same GHDL as Simulate before it tests a fix on a copy. These fixes can be Verified too (next point).
- Verified fixes for VHDL: a VHDL or mixed Verilog + VHDL fix can be labelled Verified. Nelix translates the VHDL into Verilog with GHDL + Yosys (the same tools as Synthesize), and a formal checker (SymbiYosys) proves rules written from your design description (
docs/DESIGN.md) on the fixed design, for every possible input over the clocks it explores. On projects with Python (cocotb) tests, the extra tests written from your description run too. What is proved is the translated design. Without a design description, or when the translation fails, a fix stays Passes your tests at best. Accepting and merging are still yours. - Import file order: the import lists your VHDL files so each one comes after the packages and entities it uses (packages first), and puts only real cocotb test files in the test list.
Something unclear or missing? Send feedbackSign in and use Feedback to tell us.