diff options
author | umarcor <unai.martinezcorral@ehu.eus> | 2021-01-05 22:34:14 +0100 |
---|---|---|
committer | umarcor <unai.martinezcorral@ehu.eus> | 2021-02-01 09:25:35 +0100 |
commit | 75ef931f4a7a0a4f3ddca1727d6f63ea6f4d2482 (patch) | |
tree | 3696139763213050943781d144a18272a24997c2 /doc/quick_start/simulation/hello | |
parent | 835eb73d7c567c3178f6f693153bea3243ecef53 (diff) | |
download | ghdl-75ef931f4a7a0a4f3ddca1727d6f63ea6f4d2482.tar.gz ghdl-75ef931f4a7a0a4f3ddca1727d6f63ea6f4d2482.tar.bz2 ghdl-75ef931f4a7a0a4f3ddca1727d6f63ea6f4d2482.zip |
doc: reorganise and update
Diffstat (limited to 'doc/quick_start/simulation/hello')
-rw-r--r-- | doc/quick_start/simulation/hello/hello.vhdl | 17 | ||||
-rw-r--r-- | doc/quick_start/simulation/hello/index.rst | 53 |
2 files changed, 70 insertions, 0 deletions
diff --git a/doc/quick_start/simulation/hello/hello.vhdl b/doc/quick_start/simulation/hello/hello.vhdl new file mode 100644 index 000000000..4d969c6a8 --- /dev/null +++ b/doc/quick_start/simulation/hello/hello.vhdl @@ -0,0 +1,17 @@ +-- 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; diff --git a/doc/quick_start/simulation/hello/index.rst b/doc/quick_start/simulation/hello/index.rst new file mode 100644 index 000000000..104a12efa --- /dev/null +++ b/doc/quick_start/simulation/hello/index.rst @@ -0,0 +1,53 @@ +.. program:: ghdl +.. _QuickStart:hello: + +`Hello world` program +===================== + +To illustrate the general purpose of `VHDL`, the following block is a commented `Hello world` program which is saved in +a file named :file:`hello.vhdl`: + +.. literalinclude:: hello.vhdl + :language: vhdl + +.. TIP:: + + * Both ``.vhdl`` and ``.vhd`` extensions are used for `VHDL` source files, while ``.v`` is used for Verilog. + + * Since, extension ``.vhd`` is also interpreted as a `Virtual Hard Disk <https://en.wikipedia.org/wiki/VHD_(file_format)>`_ + file format, some users prefer ``.vhdl``, to avoid ambiguity. This is the case with `GHDL`'s codebase. However, in order + to maintain `backward-compatibility <https://en.wikipedia.org/wiki/8.3_filename>`_ with legacy DOS systems, + other users prefer ``.vhd``. + + * Unless you use especial characters, either `UTF-8` or `ISO-8859-1` encodings can be used. However, if you do, the + latter should be used. The standard defines ASCII (7-bit encoding) or ISO Latin-1 (ISO-8859-1) as default. + However, GHDL has a relaxing option, :option:`--mb-comments` (multi byte), to allow UTF-8 or other encodings in + comments. + +- First, you have to compile the file; this is called :ref:`analysis <Analysis:command>` of a design file in `VHDL` + terms. Run ``ghdl -a hello.vhdl`` in the `shell`. This command creates or updates a file :file:`work-obj93.cf`, which + describes the library ``work``. +- Then, run ``ghdl -e hello_world`` in the `shell`. Command :option:`-e` means :ref:`elaborate <Elaboration:command>`, + which is used to build a design, with the ``hello_world`` entity at the top of the hierarchy. +- Last, you can directly launch the simulation :ref:`running <Run:command>` ``ghdl -r hello_world`` in the `shell`. The + result of the simulation will be shown on screen: + +.. code-block:: shell + + Hello world! + +.. HINT:: + If a GCC/LLVM variant of `GHDL` is used: + + * :ref:`Analysis <Analysis:command>` generates a file, :file:`hello.o`, which is the object file corresponding to + your `VHDL` program. This is not created with :ref:`mcode <BUILD>`. These kind of object files can be + compiled into foreign programs (see :ref:`Linking_with_Ada`). + * The :ref:`elaboration <Elaboration:command>` step is mandatory after running the analysis and prior to launching the + simulation. This will generate an executable binary named :file:`hello_world`. + * As a result, :option:`-r` is just a passthrough to the binary generated in the `elaboration`. Therefore, the + executable can be run directly: ``./hello_world``. See :option:`-r` for more informartion. + +.. HINT:: + + :option:`-e` can be bypassed with :ref:`mcode <BUILD>`, since :option:`-r` actually elaborates the design and saves + it on memory before running the simulation. But you can still use it to check for some elaboration problems. |