Update doc (#1003)

* doc: update makefile and build scripts

* actions: add workflow 'doc'

* doc: reorganize sections

* doc: fix 'unknown option' warnings, headings, spaces, etc.

* doc: add subdir 'examples', move 'quick_start' sources

* doc: add section 'Development/Debugging'

* doc: add section'Development/Synthesis'

* doc: update roadmap

* doc: add section examples

* doc: use standard domain

* doc: add comment about 'vhd' vs 'vhdl'

1 files changed, 66 insertions, 0 deletions

diff --git a/doc/examples/quick_start/DLXModelSuite.rst b/doc/examples/quick_start/DLXModelSuite.rst
new file mode 100644
index 000000000..0c8259cac
--- /dev/null
+++ b/doc/examples/quick_start/DLXModelSuite.rst
@@ -0,0 +1,66 @@
+.. _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.