From 75ef931f4a7a0a4f3ddca1727d6f63ea6f4d2482 Mon Sep 17 00:00:00 2001
From: umarcor <unai.martinezcorral@ehu.eus>
Date: Tue, 5 Jan 2021 22:34:14 +0100
Subject: doc: reorganise and update

---
 doc/quick_start/simulation/adder/index.rst | 36 ++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)
 create mode 100644 doc/quick_start/simulation/adder/index.rst

(limited to 'doc/quick_start/simulation/adder/index.rst')

diff --git a/doc/quick_start/simulation/adder/index.rst b/doc/quick_start/simulation/adder/index.rst
new file mode 100644
index 000000000..5ff607801
--- /dev/null
+++ b/doc/quick_start/simulation/adder/index.rst
@@ -0,0 +1,36 @@
+.. program:: ghdl
+.. _QuickStart:adder:
+
+`Full adder` module and testbench
+=================================
+
+Unlike :ref:`Heartbeat <QuickStart:heartbeat>`, the target hardware design in this example is written using the
+synthesisable subset of `VHDL`. It is a `full adder <https://en.wikipedia.org/wiki/Adder_(electronics)#Full_adder>`_
+described in a file named :file:`adder.vhdl`:
+
+.. literalinclude:: adder.vhdl
+   :language: vhdl
+
+You can :ref:`analyse <Analysis:command>` this design file, ``ghdl -a adder.vhdl``, and try to execute the `adder`
+design. But this is useless, since nothing externally visible will happen. In order to check this full adder, a
+:dfn:`testbench` has to be run. The :dfn:`testbench` is a description of how to generate inputs and how to check the
+outputs of the Unit Under Test (UUT). This one is very simple, since the adder is also simple: it checks exhaustively
+all inputs. Note that only the behaviour is tested, timing constraints are not checked. A file named
+:file:`adder_tb.vhdl` contains the testbench for the adder:
+
+.. literalinclude:: adder_tb.vhdl
+   :language: vhdl
+
+As usual, you should analyze the file, ``ghdl -a adder_tb.vhdl``.
+
+.. HINT::
+   Then, if required, :ref:`elaborate <Elaboration:command>` the testbench: ``ghdl -e adder_tb``. You do not need to
+   specify which object files are required, since `GHDL` knows them and automatically adds them.
+
+Now, it is time to :ref:`run <Run:command>` the testbench, ``ghdl -r adder_tb``, and check the result on screen::
+
+  adder_tb.vhdl:52:7:(assertion note): end of test
+
+If your design is rather complex, you'd like to inspect signals as explained in :ref:`Heartbeat <QuickStart:heartbeat>`.
+
+See section :ref:`simulation_options`, for more details on other runtime options.
-- 
cgit v1.2.3