aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--doc/about.rst2
-rw-r--r--doc/conf.py4
-rw-r--r--doc/contribute.rst4
-rw-r--r--doc/quick_start/simulation/adder/index.rst4
-rw-r--r--doc/quick_start/simulation/heartbeat/index.rst17
-rw-r--r--doc/quick_start/simulation/hello/index.rst48
-rw-r--r--doc/quick_start/simulation/index.rst48
-rw-r--r--doc/using/ImplementationOfVHDL.rst2
-rw-r--r--pyGHDL/__init__.py8
9 files changed, 70 insertions, 67 deletions
diff --git a/doc/about.rst b/doc/about.rst
index 388e75d15..413a8348d 100644
--- a/doc/about.rst
+++ b/doc/about.rst
@@ -99,7 +99,7 @@ Several third party projects are supported:
`Yosys <https://github.com/YosysHQ/yosys>`__
(through the `ghdl-yosys-plugin <https://github.com/ghdl/ghdl-yosys-plugin>`__)
`cocotb <https://github.com/potentialventures/cocotb>`__,
-(through the `VPI interface <https://en.wikipedia.org/wiki/Verilog_Procedural_Interface>`__),
+(through the :wikipedia:`VPI interface <Verilog_Procedural_Interface>`),
`VUnit <https://vunit.github.io/>`__,
`OSVVM <http://osvvm.org/>`__,
:doc:`vhdlmodel:index`,
diff --git a/doc/conf.py b/doc/conf.py
index 8b01b32c7..bae26d1ec 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -241,11 +241,11 @@ todo_link_only = True
# Sphinx.Ext.ExtLinks
# ==============================================================================
extlinks = {
- 'wikipedia': ('https://en.wikipedia.org/wiki/%s', None),
+ 'wikipedia': ('https://en.wikipedia.org/wiki/%s', ''),
'ghdlsharp': ('https://github.com/ghdl/ghdl/issues/%s', '#'),
'ghdlissue': ('https://github.com/ghdl/ghdl/issues/%s', 'issue #'),
'ghdlpull': ('https://github.com/ghdl/ghdl/pull/%s', 'pull request #'),
- 'ghdlsrc': ('https://github.com/ghdl/ghdl/blob/master/src/%s', None)
+ 'ghdlsrc': ('https://github.com/ghdl/ghdl/blob/master/src/%s', '')
}
diff --git a/doc/contribute.rst b/doc/contribute.rst
index 8c39b1d37..ec7391635 100644
--- a/doc/contribute.rst
+++ b/doc/contribute.rst
@@ -52,9 +52,9 @@ Please, report issues through |SHIELD:bug-report|, as this allows us to categori
to them. You can track the state and see how it's getting solved.
.. IMPORTANT::
- As suggested in the bug report template, please elaborate a `Minimal (non) Working Example` (`MWE <https://en.wikipedia.org/wiki/Minimal_Working_Example>`_)
+ As suggested in the bug report template, please elaborate a `Minimal (non) Working Example` (:wikipedia:`MWE <Minimal_Working_Example>`)
prior to sending the report, so that the possible bug source is isolated. Should it fulfill the format requirements of
- `issue-runner <https://github.com/eine/issue-runner>`_, you would be able to test your bug with the latest GHDL version.
+ `issue-runner <https://github.com/umarcor/issue-runner>`_, you would be able to test your bug with the latest GHDL version.
Please do so in order to ensure that the bug is not solved already.
Also, please include enough information in the bug report, for the maintainers to reproduce the problem. The template
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 <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`:
+synthesisable subset of `VHDL`. It is a :wikipedia:`full adder <Adder_(electronics)#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 <QuickStart:hello>` 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 <QuickStart:hello>` 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 <Analysis:command>`, :ref:`elaborated <Elaboration:command>` and :ref:`run <Run:command>`, as you already know:
+It can be :ref:`analysed <Analysis:command>`, :ref:`elaborated <Elaboration:command>` and :ref:`run <Run:command>`, as
+you already know:
.. code-block:: shell
@@ -21,7 +23,7 @@ It can be :ref:`analysed <Analysis:command>`, :ref:`elaborated <Elaboration:comm
However, execution of the design does not terminate. At the same time, no output is shown on screen. This is because,
traditionally, hardware designs are continuously running devices which do not have a screen where to print. In this
-context, inspection and verification of the behaviour is done through `waveforms <https://en.wikipedia.org/wiki/Waveform_viewer>`_,
+context, inspection and verification of the behaviour is done through :wikipedia:`waveforms <Waveform_viewer>`,
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 <http://gtkwave.sourceforge.net/>`_. 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 <QuickStart: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 <QuickStart: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 <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.
+ * Since, extension ``.vhd`` is also interpreted as a :wikipedia:`Virtual Hard Disk <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 :wikipedia:`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:
+* 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
@@ -40,14 +43,15 @@ a file named :file:`hello.vhdl`:
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`).
+ 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.
+ 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.
+ :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.
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::
diff --git a/doc/using/ImplementationOfVHDL.rst b/doc/using/ImplementationOfVHDL.rst
index a623801db..42681dcc9 100644
--- a/doc/using/ImplementationOfVHDL.rst
+++ b/doc/using/ImplementationOfVHDL.rst
@@ -142,7 +142,7 @@ or use a clocked expression (note the use of parentheses):
Of course only the simple subset of PSL is allowed.
-Currently the built-in functions are not implemented, see `issue #662 <https://github.com/ghdl/ghdl/issues/662>`_.
+Currently the built-in functions are not implemented, see :ghdlsharp:`662`.
PSL functions `prev()`, `stable()`, `rose()`, `fell()`, `onehot()` and `onehot0()` are supported with GHDL synthesis.
PSL usage
diff --git a/pyGHDL/__init__.py b/pyGHDL/__init__.py
index bd5e1b8d7..8113f5254 100644
--- a/pyGHDL/__init__.py
+++ b/pyGHDL/__init__.py
@@ -39,12 +39,12 @@ GHDL offers two Python interfaces and a language server protocol service. All
this is provided from a ``pyGHDL`` packages with four sub-packages:
* ``pyGHDL.cli`` - Command line interface (CLI) applications.
-* ``pyGHDL.dom`` - A high-level API offering a document object model (DOM). The underlying abstract VHDL language model is
- provided by `pyVHDLModel <https://github.com/VHDL/pyVHDLModel>`__. The DOM is using ``libghdl`` for file analysis and
- parsing.
+* ``pyGHDL.dom`` - A high-level API offering a document object model (DOM).
+ The underlying abstract VHDL language model is provided by :doc:`pyVHDLModel <vhdlmodel:index>`.
+ The DOM is using ``libghdl`` for file analysis and parsing.
* ``pyGHDL.libghdl`` - A low-level API directly interacting with the shared library ``libghdl....so``/``libghdl....dll``.
This is a procedural and C-like interface. It comes with some Python generators for easier iterating linked lists.
-* ``pyGHDL.lsp`` - A `language server protocol <https://en.wikipedia.org/wiki/Language_Server_Protocol>`__ (LSP)
+* ``pyGHDL.lsp`` - A :wikipedia:`language server protocol <Language_Server_Protocol>` (LSP)
written in Python. The implementation offers an HTTPS service that can be used e.g. by editors and IDEs supporting LSP.
"""
__author__ = "Tristan Gingold and contributors"