diff options
Diffstat (limited to 'doc/Starting_with_GHDL.rst')
| -rw-r--r-- | doc/Starting_with_GHDL.rst | 356 |
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. |