From 6a694dd839a18cdf0382753fffc17aa1fbd41f9d Mon Sep 17 00:00:00 2001 From: umarcor Date: Mon, 7 Feb 2022 19:28:23 +0100 Subject: doc: use extlinks more --- doc/quick_start/simulation/adder/index.rst | 4 +-- doc/quick_start/simulation/heartbeat/index.rst | 17 +++++---- doc/quick_start/simulation/hello/index.rst | 48 ++++++++++++++------------ doc/quick_start/simulation/index.rst | 48 ++++++++++++-------------- 4 files changed, 60 insertions(+), 57 deletions(-) (limited to 'doc/quick_start/simulation') diff --git a/doc/quick_start/simulation/adder/index.rst b/doc/quick_start/simulation/adder/index.rst index 5ff607801..693d42ef3 100644 --- a/doc/quick_start/simulation/adder/index.rst +++ b/doc/quick_start/simulation/adder/index.rst @@ -5,8 +5,8 @@ ================================= Unlike :ref:`Heartbeat `, the target hardware design in this example is written using the -synthesisable subset of `VHDL`. It is a `full adder `_ -described in a file named :file:`adder.vhdl`: +synthesisable subset of `VHDL`. It is a :wikipedia:`full adder ` described in a file +named :file:`adder.vhdl`: .. literalinclude:: adder.vhdl :language: vhdl diff --git a/doc/quick_start/simulation/heartbeat/index.rst b/doc/quick_start/simulation/heartbeat/index.rst index e95145095..57e348e89 100644 --- a/doc/quick_start/simulation/heartbeat/index.rst +++ b/doc/quick_start/simulation/heartbeat/index.rst @@ -4,14 +4,16 @@ `Heartbeat` module ================== -Although :ref:`Hello world ` illustrates that `VHDL` is supported as a general purpose language, the main use case -of `GHDL` is to simulate hardware descriptions. The following block, which is saved in a file named -:file:`heartbeat.vhdl`, is an example of how to generate a 100 MHz clock signal with non-synthesisable VHDL: +Although :ref:`Hello world ` illustrates that `VHDL` is supported as a general purpose language, the +main use case of `GHDL` is to simulate hardware descriptions. +The following block, which is saved in a file named :file:`heartbeat.vhdl`, is an example of how to generate a 100 MHz +clock signal with non-synthesisable VHDL: .. literalinclude:: heartbeat.vhdl :language: vhdl -It can be :ref:`analysed `, :ref:`elaborated ` and :ref:`run `, as you already know: +It can be :ref:`analysed `, :ref:`elaborated ` and :ref:`run `, as +you already know: .. code-block:: shell @@ -21,7 +23,7 @@ It can be :ref:`analysed `, :ref:`elaborated `_, +context, inspection and verification of the behaviour is done through :wikipedia:`waveforms `, which is supported by `GHDL` (see :ref:`export_waves`). You can use either :option:`--wave`, :option:`--vcd`, :option:`--vcdgz` or :option:`--fst` to save the signals of the simulation to a file. Then, terminate the execution (:kbd:`C-c`) and you can inspect the wave with a viewer, such as `GtkWave `_. As @@ -38,5 +40,6 @@ Then, you can view the dump: gtkwave wave.ghw -Of course, manually terminating the simulation is for illustration purposes only. In :ref:`Full adder ` and -:ref:`QuickStart:DLX`, you will see how to write a testbench to terminate the simulation programmatically. +Of course, manually terminating the simulation is for illustration purposes only. +In :ref:`Full adder ` and :ref:`QuickStart:DLX`, you will see how to write a testbench to terminate +the simulation programmatically. diff --git a/doc/quick_start/simulation/hello/index.rst b/doc/quick_start/simulation/hello/index.rst index 104a12efa..005706df8 100644 --- a/doc/quick_start/simulation/hello/index.rst +++ b/doc/quick_start/simulation/hello/index.rst @@ -14,23 +14,26 @@ a file named :file:`hello.vhdl`: * 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 `_ - file format, some users prefer ``.vhdl``, to avoid ambiguity. This is the case with `GHDL`'s codebase. However, in order - to maintain `backward-compatibility `_ 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. + * Since, extension ``.vhd`` is also interpreted as a :wikipedia:`Virtual Hard Disk ` file + format, some users prefer ``.vhdl``, to avoid ambiguity. + This is the case with `GHDL`'s codebase. + However, in order to maintain :wikipedia:`backward-compatibility ` + 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 ` 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 `, - 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 ` ``ghdl -r hello_world`` in the `shell`. The - result of the simulation will be shown on screen: +* First, you have to compile the file; this is called :ref:`analysis ` 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 `, 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 ` ``ghdl -r hello_world`` in the `shell`. + The result of the simulation will be shown on screen: .. code-block:: shell @@ -40,14 +43,15 @@ a file named :file:`hello.vhdl`: If a GCC/LLVM variant of `GHDL` is used: * :ref:`Analysis ` generates a file, :file:`hello.o`, which is the object file corresponding to - your `VHDL` program. This is not created with :ref:`mcode `. These kind of object files can be - compiled into foreign programs (see :ref:`Linking_with_Ada`). + your `VHDL` program. This is not created with :ref:`mcode `. + These kind of object files can be compiled into foreign programs (see :ref:`Linking_with_Ada`). * The :ref:`elaboration ` 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. + 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 `, 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. + :option:`-e` can be bypassed with :ref:`mcode `, 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. diff --git a/doc/quick_start/simulation/index.rst b/doc/quick_start/simulation/index.rst index 8e41a453b..8feab2760 100644 --- a/doc/quick_start/simulation/index.rst +++ b/doc/quick_start/simulation/index.rst @@ -4,43 +4,39 @@ Simulation ########## -As explained in :ref:`INTRO:GHDL`, `GHDL` is a compiler which translates `VHDL` -files to machine code. Hence, the regular workflow is composed of three steps: +As explained in :ref:`INTRO:GHDL`, `GHDL` is a compiler which translates `VHDL` files to machine code. +Hence, the regular workflow is composed of three steps: -* :ref:`Analysis:command`: convert design units (`VHDL` sources) to an internal - representation. -* :ref:`Elaboration:command`: generate executable machine code for a target module - (top-level entity). -* :ref:`Run:command`: execute the design to test the behaviour, generate - output/waveforms, etc. +* :ref:`Analysis:command`: convert design units (`VHDL` sources) to an internal representation. +* :ref:`Elaboration:command`: generate executable machine code for a target module (top-level entity). +* :ref:`Run:command`: execute the design to test the behaviour, generate output/waveforms, etc. The following tips might be useful: -* Don't forget to select the version of the VHDL standard you want to use (see - :ref:`VHDL_standards`). The default is :option:`--std=93c <--std>`. Use - :option:`--std=08 <--std>` for VHDL-2008 (albeit not fully implemented). +* Don't forget to select the version of the VHDL standard you want to use (see :ref:`VHDL_standards`). + The default is :option:`--std=93c <--std>`. + Use :option:`--std=08 <--std>` for VHDL-2008 (albeit not fully implemented). - * Use :option:`--ieee=synopsys <--ieee>` if your design depends on a non-standard - implementation of the IEEE library. + * Use :option:`--ieee=synopsys <--ieee>` if your design depends on a non-standard implementation of the IEEE library. - * Use :option:`-fexplicit` and :option:`-frelaxed-rules` if needed. For instance, - if you would like to use VHDL 2008 and also use shared variables with an - ordinary type (deprecated in VHDL 2000), you can use ``--std=08 -frelaxed-rules``. + * Use :option:`-fexplicit` and :option:`-frelaxed-rules` if needed. + For instance, if you would like to use VHDL 2008 and also use shared variables with an ordinary type (deprecated in + VHDL 2000), you can use ``--std=08 -frelaxed-rules``. * Use :option:`--work=LIB_NAME <--work>` to analyze files into the ``LIB_NAME`` library. - To use files analyzed to a different directory, give the path - to the ``LIB_NAME`` library using :option:`-P/path/to/name/directory/ <-P>`. + To use files analyzed to a different directory, give the path to the ``LIB_NAME`` library using + :option:`-P/path/to/name/directory/ <-P>`. -* Use the same options for analysis and elaboration. E.g., first analyse with - ``ghdl -a --std=08 --work=mylib myfile.vhdl``; and then elaborate and run with +* Use the same options for analysis and elaboration. + E.g., first analyse with ``ghdl -a --std=08 --work=mylib myfile.vhdl``; and then elaborate and run with ``ghdl --elab-run --std=08 top``. -Due to the fact that `VHDL` is processed as a general purpose language -(instead of an `HDL`), all the language features are to be supported. I.e., `VHDL` -sources do not need to be limited to the synthesisable subset. However, distinction -between synthesisable and non-synthesisable (simulation-only) subsets is often -misleading for users who are new to the language. Different examples are provided, -in the hope of helping understand the different use cases: +Due to the fact that `VHDL` is processed as a general purpose language (instead of an `HDL`), all the language features +are to be supported. +I.e., `VHDL` sources do not need to be limited to the synthesisable subset. +However, distinction between synthesisable and non-synthesisable (simulation-only) subsets is often misleading for users +who are new to the language. +Different examples are provided, in the hope of helping understand the different use cases: .. toctree:: -- cgit v1.2.3