Working with non-trivial designs

Designs are usually more complex than the previous examples. Unless you are only studying VHDL, you will work with larger designs. Let’s see how to analyse a design such as the DLX model suite written by Peter Ashenden, which is distributed under the terms of the GNU General Public License. A copy is kept at .

  • First, untar the sources: tar zxvf dlx.tar.gz.


In order not to pollute the sources with the artifacts (WORK library), it is a good idea to create a work/ subdirectory. To any GHDL commands, we will add the --workdir=work option, so that all files generated by the compiler (except the executable) will be placed in this directory.

$ cd dlx
$ mkdir work
  • Then, we will run the dlx_test_behaviour design. We need to analyse all the design units for the design hierarchy, in the correct order. GHDL provides an easy way to do this, by importing the sources: ghdl -i --workdir=work *.vhdl.

  • GHDL knows all the design units of the DLX, but none of them has been analysed. Run the make command, ghdl -m --workdir=work dlx_test_behaviour, which analyses and elaborates a design. This creates many files in the work/ directory, and (GCC/LLVM only) the dlx_test_behaviour executable in the current directory.


The simulation needs to have a DLX program contained in the file dlx.out. This memory image will be loaded in the DLX memory. Just take one sample: cp test_loop.out dlx.out.

  • Now, you can run the test suite: ghdl -r --workdir=work dlx_test_behaviour. The test bench monitors the bus and displays each executed instruction. It finishes with an assertion of severity level note:

    dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction
     encountered, execution halted
  • Last, since the clock is still running, you have to manually stop the program with the C-c key sequence. This behavior prevents you from running the testbench in batch mode. However, you may force the simulator to stop when an assertion above or equal a certain severity level occurs. To do so, call run with this option instead: ghdl -r --workdir=work dlx_test_behaviour --assert-level=note`. With --assert-level, the program stops just after the previous message:

    dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction
     encountered, execution halted
    error: assertion failed


If you want to make room on your hard drive, you can either:

  • Clean the design library with ghdl --clean --workdir=work. This removes the executable and all the object files. If you want to rebuild the design at this point, just do the make command as shown above.

  • Remove the design library with ghdl --remove --workdir=work. This removes the executable, all the object files and the library file. If you want to rebuild the design, you have to import the sources again and make the design.

  • Remove the work/ directory: rm -rf work. Only the executable is kept. If you want to rebuild the design, create the work/ directory, import the sources, and make the design.


Sometimes, a design does not fully follow the VHDL standards. For example it might use the badly engineered std_logic_unsigned package. GHDL supports this VHDL dialect through some options: --ieee=synopsys, -fexplicit, etc. See section IEEE library pitfalls, for more details.