New documentation structure for GHDL.

1 files changed, 0 insertions, 356 deletions

diff --git a/doc/Starting_with_GHDL.rst b/doc/Starting_with_GHDL.rst
deleted file mode 100644
index c7cd00f96..000000000
--- a/doc/Starting_with_GHDL.rst
+++ /dev/null
@@ -1,356 +0,0 @@
-******************
-Starting with GHDL
-******************
-
-In this chapter, you will learn how to use the GHDL compiler by
-working on two examples.
-
-The hello world program
-=======================
-
-To illustrate the large purpose of VHDL, here is a commented VHDL
-"Hello world" program.
-
-.. code-block:: VHDL
-
-  --  Hello world program.
-  use std.textio.all; -- Imports the standard textio package.
-
-  --  Defines a design entity, without any ports.
-  entity hello_world is
-  end hello_world;
-
-  architecture behaviour of hello_world is
-  begin
-     process
-        variable l : line;
-     begin
-        write (l, String'("Hello world!"));
-        writeline (output, l);
-        wait;
-     end process;
-  end behaviour;
-
-Suppose this program is contained in the file :file:`hello.vhdl`.
-First, you have to compile the file; this is called `analysis` of a design
-file in VHDL terms.
-
-.. code-block:: shell
-
-  $ ghdl -a hello.vhdl
-
-This command creates or updates a file :file:`work-obj93.cf`, which
-describes the library `work`.  On GNU/Linux, this command generates a
-file :file:`hello.o`, which is the object file corresponding to your
-VHDL program.  The object file is not created on Windows.
-
-Then, you have to build an executable file.
-
-.. code-block:: shell
-
-  $ ghdl -e hello_world
-
-The :option:`-e` option means :dfn:`elaborate`.  With this option, `GHDL`
-creates code in order to elaborate a design, with the :samp:`hello_world`
-entity at the top of the hierarchy.
-
-On GNU/Linux, if you have enabled the GCC backend during the compilation of `GHDL`,
-an executable program called :file:`hello_world` which can be run is generated:
-
-.. code-block:: shell
-
-  $ ghdl -r hello_world
-
-or directly:
-
-.. code-block:: shell
-
-  $ ./hello_world
-
-
-On Windows or if the GCC backend was not enabled, no file is created.
-The simulation is launched using this command:
-
-.. code-block:: shell
-
-  > ghdl -r hello_world
-
-
-The result of the simulation appears on the screen::
-
-  Hello world!
-
-
-A full adder
-============
-
-VHDL is generally used for hardware design.  This example starts with
-a full adder described in the :file:`adder.vhdl` file:
-
-.. code-block:: VHDL
-
-  entity adder is
-    -- `i0`, `i1` and the carry-in `ci` are inputs of the adder.
-    -- `s` is the sum output, `co` is the carry-out.
-    port (i0, i1 : in bit; ci : in bit; s : out bit; co : out bit);
-  end adder;
-
-  architecture rtl of adder is
-  begin
-     --  This full-adder architecture contains two concurrent assignment.
-     --  Compute the sum.
-     s <= i0 xor i1 xor ci;
-     --  Compute the carry.
-     co <= (i0 and i1) or (i0 and ci) or (i1 and ci);
-  end rtl;
-
-
-You can analyze this design file:
-
-.. code-block:: shell
-
-  $ ghdl -a adder.vhdl
-
-
-You can try to execute the `adder` design, but this is useless,
-since nothing externally visible will happen.  In order to
-check this full adder, a testbench has to be run.  This testbench 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.  The file :file:`adder_tb.vhdl` contains the testbench for
-the adder:
-
-.. code-block:: VHDL
-
-  --  A testbench has no ports.
-  entity adder_tb is
-  end adder_tb;
-
-  architecture behav of adder_tb is
-     --  Declaration of the component that will be instantiated.
-     component adder
-       port (i0, i1 : in bit; ci : in bit; s : out bit; co : out bit);
-     end component;
-
-     --  Specifies which entity is bound with the component.
-     for adder_0: adder use entity work.adder;
-     signal i0, i1, ci, s, co : bit;
-  begin
-     --  Component instantiation.
-     adder_0: adder port map (i0 => i0, i1 => i1, ci => ci,
-                              s => s, co => co);
-
-     --  This process does the real job.
-     process
-        type pattern_type is record
-           --  The inputs of the adder.
-           i0, i1, ci : bit;
-           --  The expected outputs of the adder.
-           s, co : bit;
-        end record;
-        --  The patterns to apply.
-        type pattern_array is array (natural range <>) of pattern_type;
-        constant patterns : pattern_array :=
-          (('0', '0', '0', '0', '0'),
-           ('0', '0', '1', '1', '0'),
-           ('0', '1', '0', '1', '0'),
-           ('0', '1', '1', '0', '1'),
-           ('1', '0', '0', '1', '0'),
-           ('1', '0', '1', '0', '1'),
-           ('1', '1', '0', '0', '1'),
-           ('1', '1', '1', '1', '1'));
-     begin
-        --  Check each pattern.
-        for i in patterns'range loop
-           --  Set the inputs.
-           i0 <= patterns(i).i0;
-           i1 <= patterns(i).i1;
-           ci <= patterns(i).ci;
-           --  Wait for the results.
-           wait for 1 ns;
-           --  Check the outputs.
-           assert s = patterns(i).s
-              report "bad sum value" severity error;
-           assert co = patterns(i).co
-              report "bad carry out value" severity error;
-        end loop;
-        assert false report "end of test" severity note;
-        --  Wait forever; this will finish the simulation.
-        wait;
-     end process;
-  end behav;
-
-
-As usual, you should analyze the design:
-
-.. code-block:: shell
-
-  $ ghdl -a adder_tb.vhdl
-
-And build an executable for the testbench:
-
-.. code-block:: shell
-
-  $ ghdl -e adder_tb
-
-You do not need to specify which object files are required: GHDL knows them
-and automatically adds them in the executable.  Now, it is time to run the
-testbench:
-
-.. code-block:: shell
-
-  $ ghdl -r adder_tb
-  adder_tb.vhdl:52:7:(assertion note): end of test
-
-
-If your design is rather complex, you'd like to inspect signals.  Signals
-value can be dumped using the VCD file format.  The resulting file can be
-read with a wave viewer such as GTKWave.  First, you should simulate your
-design and dump a waveform file:
-
-.. code-block:: shell
-
-  $ ghdl -r adder_tb --vcd=adder.vcd
-
-Then, you may now view the waves:
-
-.. code-block:: shell
-
-  $ gtkwave adder.vcd
-
-See :ref:`Simulation_options`, for more details on the :option:`--vcd` option and
-other runtime options.
-
-
-Starting with a design
-======================
-
-Unless you are only studying VHDL, you will work with bigger designs than
-the ones of the previous examples.
-
-Let's see how to analyze and run a bigger 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 on
-http://ghdl.free.fr/dlx.tar.gz
-
-First, untar the sources:
-
-.. code-block:: shell
-
-  $ tar zxvf dlx.tar.gz
-
-
-In order not to pollute the sources with the library, it is a good idea
-to create a :file:`work/` subdirectory for the `WORK` library.  To
-any GHDL commands, we will add the :option:`--workdir=work` 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
-
-
-We will run the :samp:`dlx_test_behaviour` design.  We need to analyze
-all the design units for the design hierarchy, in the correct order.
-GHDL provides an easy way to do this, by importing the sources:
-
-.. code-block:: shell
-
-  $ ghdl -i --workdir=work *.vhdl
-
-
-and making a design:
-
-.. code-block:: shell
-
-  $ ghdl -m --workdir=work dlx_test_behaviour
-
-
-Before this second stage, GHDL knows all the design units of the DLX,
-but no one have been analyzed.  The make command of GHDL analyzes and
-elaborates a design.  This creates many files in the :file:`work/`
-directory, and the :file:`dlx_test_behaviour` executable in the current
-directory.
-
-The simulation needs to have a DLX program contained in the file
-:file:`dlx.out`.  This memory image will be be loaded in the DLX memory.
-Just take one sample:
-
-.. code-block:: shell
-
-  $ cp test_loop.out dlx.out
-
-
-And you can run the test suite:
-
-.. code-block:: shell
-
-  $ ghdl -r --workdir=work dlx_test_behaviour
-
-
-The test bench monitors the bus and displays each instruction executed.
-It finishes with an assertion of severity level note:
-
-.. code-block:: shell
-
-  dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction
-   encountered, execution halted
-
-
-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
-test bench in batch mode.  However, you may force the simulator to
-stop when an assertion above or equal a certain severity level occurs:
-
-.. code-block:: shell
-
-  $ ghdl -r --workdir=work dlx_test_behaviour --assert-level=note
-
-
-With this option, 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 the GHDL command:
-
-  .. code-block:: shell
-
-    $ 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 the GHDL command:
-
-  .. code-block:: shell
-
-    $ 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 to make the design.
-  
-* remove the :file:`work/` directory:
-
-  .. code-block:: shell
-
-    $ 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.
-
-Sometimes, a design does not fully follow the VHDL standards.  For example it
-uses the badly engineered :samp:`std_logic_unsigned` package.  GHDL supports
-this VHDL dialect through some options::
-
-  --ieee=synopsys -fexplicit
-
-See :ref:`IEEE_library_pitfalls`, for more details.