.. program:: ghdl
.. _QuickStart:DLX:

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 `ghdl.free.fr/dlx.tar.gz <http://ghdl.free.fr/dlx.tar.gz>`_ .

- First, untar the sources: ``tar zxvf dlx.tar.gz``.

.. HINT::

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

  .. code-block:: shell

     $ 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 :ref:`importing <Import:command>` 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 :ref:`make <Make:command>`
  command, ``ghdl -m --workdir=work dlx_test_behaviour``, which analyses and elaborates a design. This creates many
  files in the :file:`work/` directory, and (GCC/LLVM only) the :file:`dlx_test_behaviour` executable in the current
  directory.

.. HINT::

   The simulation needs to have a DLX program contained in the file :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 :ref:`run <Run:command>` 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:

  .. code-block:: shell

     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 :kbd:`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 :option:`--assert-level`, the program stops
  just after the previous message:

  .. code-block:: shell

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

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

   * :ref:`Clean <Clean:command>` 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.
   * :ref:`Remove <Remove:command>` 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 :file:`work/` directory: ``rm -rf work``. Only the executable is kept. If you want to rebuild the design, create the :file:`work/` directory, import the sources, and make the design.

.. WARNING:: 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: :option:`--ieee=synopsys <--ieee>`, :option:`-fexplicit`, etc. See section :ref:`IEEE_library_pitfalls`, for more details.