diff options
| author | Patrick Lehmann <Patrick.Lehmann@tu-dresden.de> | 2017-03-04 18:47:08 +0100 |
|---|---|---|
| committer | tgingold <tgingold@users.noreply.github.com> | 2017-12-10 12:02:05 +0100 |
| commit | 7b2b91900e8217fd75fcc755f14c5f098662f1f8 (patch) | |
| tree | a627a96ad6af99e0ec38b6ab6d6dad2c6e35c0ce /doc | |
| parent | 660998b341f810b8a37fed12cbf00e8d301ec3d7 (diff) | |
| download | ghdl-7b2b91900e8217fd75fcc755f14c5f098662f1f8.tar.gz ghdl-7b2b91900e8217fd75fcc755f14c5f098662f1f8.tar.bz2 ghdl-7b2b91900e8217fd75fcc755f14c5f098662f1f8.zip | |
Fixed typos, indentation and headline underlining.
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/about.rst | 32 | ||||
| -rw-r--r-- | doc/contribute.rst | 60 | ||||
| -rw-r--r-- | doc/genindex.rst | 2 | ||||
| -rw-r--r-- | doc/index.rst | 2 | ||||
| -rw-r--r-- | doc/licenses.rst | 17 | ||||
| -rw-r--r-- | doc/references/CodingStyle.rst | 170 | ||||
| -rw-r--r-- | doc/references/CommandReference.rst | 28 | ||||
| -rw-r--r-- | doc/shields.inc (renamed from doc/shields.txt) | 71 | ||||
| -rw-r--r-- | doc/shieldswho.inc (renamed from doc/shieldswho.txt) | 28 | ||||
| -rw-r--r-- | doc/using/InvokingGHDL.rst | 100 | ||||
| -rw-r--r-- | doc/using/QuickStartGuide.rst | 240 | ||||
| -rw-r--r-- | doc/using/Simulation.rst | 19 |
12 files changed, 417 insertions, 352 deletions
diff --git a/doc/about.rst b/doc/about.rst index 9b11ed5bf..ee0ced2e0 100644 --- a/doc/about.rst +++ b/doc/about.rst @@ -1,12 +1,12 @@ -.. include:: shieldswho.txt +.. include:: shieldswho.inc About GHDL -############ +########## .. _INTRO:VHDL: What is `VHDL`? -============== +=============== :wikipedia:`VHDL <VHDL>` is an acronym for Very High Speed Integrated Circuit (:wikipedia:`VHSIC <VHSIC>`) Hardware Description Language (:wikipedia:`HDL <HDL>`), which is a programming language used to describe a logic circuit by function, data flow behavior, or structure. @@ -16,12 +16,13 @@ However, VHDL was not designed as a general purpose language but as an `HDL`. As Like a program written in any other language, a VHDL program can be executed. Since VHDL is used to model designs, the term :dfn:`simulation` is often used instead of `execution`, with the same meaning. At the same time, like a design written in another `HDL`, a set of VHDL sources can be transformed with a :dfn:`synthesis tool` into a netlist, that is, a detailed gate-level implementation. -The development of VHDL started in 1983 and the standard is named `IEEE <https://www.ieee.org/>`_ `1076`. Four revisions exist: `1987 <http://ieeexplore.ieee.org/document/26487/>`_, `1993 <http://ieeexplore.ieee.org/document/392561/>`_, `2002 <http://ieeexplore.ieee.org/document/1003477/>`_ and `2008 <http://ieeexplore.ieee.org/document/4772740/>`_. The standarization is handled by the VHDL Analysis and Standardization Group (`VASG/P1076 <http://www.eda-twiki.org/vasg/>`_). +The development of VHDL started in 1983 and the standard is named `IEEE <https://www.ieee.org/>`_ `1076`. Four revisions exist: `1987 <http://ieeexplore.ieee.org/document/26487/>`_, `1993 <http://ieeexplore.ieee.org/document/392561/>`_, `2002 <http://ieeexplore.ieee.org/document/1003477/>`_ and `2008 <http://ieeexplore.ieee.org/document/4772740/>`_. The standardization is handled by the VHDL Analysis and Standardization Group (`VASG/P1076 <http://www.eda-twiki.org/vasg/>`_). + .. _INTRO:GHDL: What is GHDL? -============== +============= `GHDL` is a shorthand for `G Hardware Design Language` (currently, `G` has no meaning). It is a VHDL compiler that can execute (nearly) any VHDL program. GHDL is *not* a synthesis tool: you cannot create a netlist with GHDL (yet). @@ -29,12 +30,13 @@ Unlike some other simulators, GHDL is a compiler: it directly translates a VHDL GHDL can use multiple back-ends, i.e. code generators, (`GCC <http://gcc.gnu.org/>`_, `LLVM <http://llvm.org/>`_ or :wikipedia:`x86 <X86-64>`/:wikipedia:`i386 <Intel_80386>` only, a built-in one) and runs on :wikipedia:`GNU/Linux <Linux_distribution>`, :wikipedia:`Windows <Microsoft_Windows>` |trade| and :wikipedia:`macOS <MacOS>` |trade| , both on x86 and on x86_64. -The current version of GHDL does not contain any graphical viewer: you cannot see signal waves. You can still check the behaviour of your design with a test bench. Moreover, the current version can produce a `GHW <http://ghdl.readthedocs.io/en/latest/using/Simulation.html?highlight=GHW#cmdoption-wave>`_, :wikipedia:`VCD <Value_change_dump>` or `FST` files which can be viewed with a :wikipedia:`waveform viewer <Waveform_viewer>`, such as `GtkWave <http://gtkwave.sourceforge.net/>`_. +The current version of GHDL does not contain any graphical viewer: you cannot see signal waves. You can still check the behavior of your design with a test bench. Moreover, the current version can produce a `GHW <http://ghdl.readthedocs.io/en/latest/using/Simulation.html?highlight=GHW#cmdoption-wave>`_, :wikipedia:`VCD <Value_change_dump>` or `FST` files which can be viewed with a :wikipedia:`waveform viewer <Waveform_viewer>`, such as `GtkWave <http://gtkwave.sourceforge.net/>`_. GHDL aims at implementing VHDL as defined by `IEEE 1076 <http://ieeexplore.ieee.org/document/4772740/>`_. It supports the `1987 <http://ieeexplore.ieee.org/document/26487/>`_, `1993 <http://ieeexplore.ieee.org/document/392561/>`_ and `2002 <http://ieeexplore.ieee.org/document/1003477/>`_ revisions and, partially, the latest, `2008 <http://ieeexplore.ieee.org/document/4772740/>`_. :wikipedia:`PSL <Property_Specification_Language>` is also partially supported. Several third party projects are supported: `VUnit <https://vunit.github.io/>`_, `OSVVM <http://osvvm.org/>`_, `cocotb <https://github.com/potentialventures/cocotb>`_ (through the `VPI interface <https://en.wikipedia.org/wiki/Verilog_Procedural_Interface>`_), ... + .. _INTRO:WHO: Who uses GHDL? @@ -42,12 +44,12 @@ Who uses GHDL? .. container:: whouses - +-------------------+--------------------+---------------------------------------------------+----------------------------------------------------------------+ - | Project hub | Documentation | Name | Brief description | - +===================+====================+===================================================+================================================================+ - | |SHIELD:gh-poc| | |SHIELD:rtd-poc| | `PoC-Library <https://github.com/VLSI-EDA/PoC>`_ | A Vendor-Independent, Open-Source IP Core and Utility Library. | - +-------------------+--------------------+---------------------------------------------------+----------------------------------------------------------------+ - | |SHIELD:gh-vunit| | |SHIELD:doc-vunit| | `VUnit <http://vunit.github.io/>`_ | A unit testing framework for VHDL/SystemVerilog | - +-------------------+--------------------+---------------------------------------------------+----------------------------------------------------------------+ - | |SHIELD:gl-p1076| | |SHIELD:tw-p1076| | `IEEE P1076 WG <http://www.eda-twiki.org/vasg/>`_ | IEEE P1076 Working Group [VASG] | - +-------------------+--------------------+---------------------------------------------------+----------------------------------------------------------------+ + +-------------------+--------------------+---------------------------------------------------+----------------------------------------------------------------+ + | Project hub | Documentation | Name | Brief description | + +===================+====================+===================================================+================================================================+ + | |SHIELD:gh-poc| | |SHIELD:rtd-poc| | `PoC-Library <https://github.com/VLSI-EDA/PoC>`_ | A Vendor-Independent, Open-Source IP Core and Utility Library. | + +-------------------+--------------------+---------------------------------------------------+----------------------------------------------------------------+ + | |SHIELD:gh-vunit| | |SHIELD:doc-vunit| | `VUnit <http://vunit.github.io/>`_ | A unit testing framework for VHDL/SystemVerilog | + +-------------------+--------------------+---------------------------------------------------+----------------------------------------------------------------+ + | |SHIELD:gl-p1076| | |SHIELD:tw-p1076| | `IEEE P1076 WG <http://www.eda-twiki.org/vasg/>`_ | IEEE P1076 Working Group [VASG] | + +-------------------+--------------------+---------------------------------------------------+----------------------------------------------------------------+ diff --git a/doc/contribute.rst b/doc/contribute.rst index 36a3c0f38..a362f57e0 100644 --- a/doc/contribute.rst +++ b/doc/contribute.rst @@ -1,4 +1,4 @@ -.. include:: shields.txt +.. include:: shields.inc .. _INTRO:Contributing: Contributing @@ -6,11 +6,11 @@ Contributing The first step might be to use GHDL and explore it's possibilities in an own project. If you are new to VHDL, see the :ref:`USING:QuickStart` for an introduction. Furthermore, we encourage you to read :ref:`USING:Invoking`, where the most commonly used options are explained. You can also check the complete :ref:`REF:Command`. -If you are more familiar with GHDL, you might start asking yourself how it works internally. Then, you migh find :ref:`Implementation of VHDL <REF:ImplVHDL>` and :ref:`Implementation of VITAL <REF:ImplVITAL>` interesting. +If you are more familiar with GHDL, you might start asking yourself how it works internally. Then, you might find :ref:`Implementation of VHDL <REF:ImplVHDL>` and :ref:`Implementation of VITAL <REF:ImplVITAL>` interesting. While using GHDL, you might find flaws, such as bugs, missing features, typos in the documentation or topics which are still not covered. In order to improve GHDL, we welcome bug reports, suggestions and contributions for any aspect of GHDL. Either if it's a bug or an enhancement, have a look at the |SHIELD:issues-open| and |SHIELD:issues-closed| to see if someone already told us about it. You might find a solution there. To get a broader view, you can also check the :ref:`Roadmap <CHANGE>`. -If you found no information on your topic, please, report so that we are aware! You can reach us through various ways: |SHIELD:gitter|, open a |SHIELD:issues-new| and/or suscribe to |SHIELD:mailing| +If you found no information on your topic, please, report so that we are aware! You can reach us through various ways: |SHIELD:gitter|, open a |SHIELD:issues-new| and/or subscribe to |SHIELD:mailing| .. HINT:: Since the development of GHDL started fifteen years ago, multiple platforms have been used as a support for both distribution and getting feedback. However, the development is now centralized in |SHIELD:gh-logo|. @@ -25,59 +25,61 @@ Reporting bugs ============== .. TIP:: - * If the compiler crashes, this is a bug. Reliable tools never crash. - * If the compiler emits an error message for a perfectly valid input or does not emit an error message for an invalid input, this may be a bug. - * If the executable created from your VHDL sources crashes, this may be a bug at runtime or the code itself may be wrong. However, since VHDL has a notion of pointers, an erroneous VHDL program (using invalid pointers for example) may crash. - * If a compiler message is not clear enough, please tell us. The error messages can be improved, but we have not enough experience with them. + * If the compiler crashes, this is a bug. Reliable tools never crash. + * If the compiler emits an error message for a perfectly valid input or does not emit an error message for an invalid input, this may be a bug. + * If the executable created from your VHDL sources crashes, this may be a bug at runtime or the code itself may be wrong. However, since VHDL has a notion of pointers, an erroneous VHDL program (using invalid pointers for example) may crash. + * If a compiler message is not clear enough, please tell us. The error messages can be improved, but we have not enough experience with them. Please, report issues of this kind through |SHIELD:issues-new|, as this allows us to categorize issues into groups and assign developers to them. You can track the issue’s state and see how it’s getting solved. .. IMPORTANT:: - To make it easier, please elaborate a `Minimum (non) Working Example` (`MWE <https://en.wikipedia.org/wiki/Minimal_Working_Example>`_) prior to sending the report, so that the possible bug source is isolated. Shall the MWE compile and run, it is a good idea to make it look like a test and make an assert statement should finish the execution; the severity level `note` indicates success, while a severity level `failure` indicates failure. - - Then, please include enough information for the maintainers to reproduce the problem. This includes: - - - Operating system and version of GHDL (you can get it with :samp:`ghdl --version`). - - Whether you have built GHDL from sources (provide short SHA of the used commit) or used the binary distribution (teel which realease/tag). - - - If you cannot compile, please report which compiler you are using and the version. + To make it easier, please elaborate a `Minimum (non) Working Example` (`MWE <https://en.wikipedia.org/wiki/Minimal_Working_Example>`_) prior to sending the report, so that the possible bug source is isolated. Shall the MWE compile and run, it is a good idea to make it look like a test and make an assert statement should finish the execution; the severity level `note` indicates success, while a severity level `failure` indicates failure. - - Content of the input files which make the MWE - - Description of the problem: - - - Comment explaining whether the MWE should compile or not; if yes, whether or not is should run until the assertion. - - What you expected to happen and what you actually get. If you know the LRM well enough, please specify the paragraph which might be not well implemented. - - Samples of any log. - - Anything else that you think would be helpful. + Then, please include enough information for the maintainers to reproduce the problem. This includes: + + * Operating system and version of GHDL (you can get it with :samp:`ghdl --version`). + * Whether you have built GHDL from sources (provide short SHA of the used commit) or used the binary distribution (teel which realease/tag). + + * If you cannot compile, please report which compiler you are using and the version. + + * Content of the input files which make the MWE + * Description of the problem: + + * Comment explaining whether the MWE should compile or not; if yes, whether or not is should run until the assertion. + * What you expected to happen and what you actually get. If you know the LRM well enough, please specify the paragraph which might be not well implemented. + * Samples of any log. + * Anything else that you think would be helpful. .. NOTE:: If you don't know the LRM, be aware that an issue claimed as bug report may be rejected because there is no bug according to it. GHDL aims at implementing VHDL as defined in `IEEE 1076 <http://ieeexplore.ieee.org/document/4772740/>`_. However, some other tools allow constructs which do not fully follow the standard revisions. Therefore, comparisons with other VHDL is not a solid argument. Some of them are supported by GHDL (see :ref:`IEEE_library_pitfalls`), but any such enhancement will have very low priority. + .. _requesting_enhancements: Requesting enhancements -============== +======================= |SHIELD:issues-new| |SHIELD:gitter| |SHIELD:mailing| All enhancements and feature requests are welcome. Please `open a new issue <https://github.com/tgingold/ghdl/issues/new>`_ to report any, so you can track the request's status and implementation. Depending on the complexity of the request, you may want to `chat on Gitter <https://gitter.im/ghdl/ghdl1>`_, to polish it before opening an issue. If you don't have a `GitHub <https://github.com>`_ user account, you can reach the developers through the `mailing-list <https://mail.gna.org/listinfo/ghdl-discuss/>`_ . Improving the documentation -============== +=========================== If you found a mistake in the documentation, please send a comment. If you didn't understand some parts of this manual, please tell us. English is not our mother tongue, so this documentation may not be well-written. Likewise, rewriting part of the documentation or missing content (such as, examples) is a good way to improve it. Since it automatically is built from `reStructuredText` and `Markdown` sources, you can fork, modify and request the maintainers to pull your copy. See :ref:`pull_request`. + .. _pull_request: Fork, modify and pull-request -============== +============================= .. TIP:: - - Before starting any modification, you might want to have a look at |SHIELD:issues-pr| and |SHIELD:issues-pr-closed|, to check which other contributions are being made or have been made. If you observe that the modifications you are about to start might conflict with any other, please |SHIELD:gitter| or open a |SHIELD:issues-new| to coordinate. - - See section :ref:`'BUILD:dir_structure'` to faster find the location of the sources you need to modify, and/or to know where to place new ones. + * Before starting any modification, you might want to have a look at |SHIELD:issues-pr| and |SHIELD:issues-pr-closed|, to check which other contributions are being made or have been made. If you observe that the modifications you are about to start might conflict with any other, please |SHIELD:gitter| or open a |SHIELD:issues-new| to coordinate. + * See section :ref:`'BUILD:dir_structure'` to faster find the location of the sources you need to modify, and/or to know where to place new ones. -Contibuting source code/documentation via `Git <https://git-scm.com/>`_ is very easy. Although we don't provide direct write access to our repositories, the project is hosted at GitHub, which follows a fork, edit and pull-request `flow <https://help.github.com/articles/github-flow/>`_ . That is: +Contributing source code/documentation via `Git <https://git-scm.com/>`_ is very easy. Although we don't provide direct write access to our repositories, the project is hosted at GitHub, which follows a fork, edit and pull-request `flow <https://help.github.com/articles/github-flow/>`_ . That is: 1. Make a copy (`fork <https://help.github.com/articles/fork-a-repo/>`_) of the project. 2. Do the changes you wish (edit, add, rename, move and/or delete). @@ -90,6 +92,6 @@ Contibuting source code/documentation via `Git <https://git-scm.com/>`_ is very * Some commit messages can `automatically close <https://help.github.com/articles/closing-issues-via-commit-messages/>`_ issues. This is a very useful feature, which you are not required to use. However beware that using `fix` anywhere in the commit message can have side effects. If you closed any issue unexpectedly, just reply to it (even if it's closed) so that maintainers can check it. Related interesting projects -============== +============================ If you have an interesting project, please send us feedback or get listed on our :ref:`INTRO:WHO` page. diff --git a/doc/genindex.rst b/doc/genindex.rst index c07da40d1..d4fc2f48f 100644 --- a/doc/genindex.rst +++ b/doc/genindex.rst @@ -1,4 +1,4 @@ -.. This file is a placeholder and will be replaced +.. # This file is a placeholder and will be replaced Index ##### diff --git a/doc/index.rst b/doc/index.rst index 262575b6e..934b97d6e 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,4 +1,4 @@ -.. include:: shields.txt +.. include:: shields.inc |SHIELD:gh-logo| |SHIELD:gitter| |SHIELD:code-lic| |SHIELD:doc-lic| |br| |SHIELD:travis-ci| |SHIELD:appveyor| |SHIELD:tag| |SHIELD:release| diff --git a/doc/licenses.rst b/doc/licenses.rst index 078d43199..a55d62093 100644 --- a/doc/licenses.rst +++ b/doc/licenses.rst @@ -1,9 +1,8 @@ -.. include:: shields.txt -.. include:: <isonum.txt> +.. include:: shields.inc .. _INTRO:Copyrights: Copyrights | Licenses -############ +##################### - The GHDL front-end, package :samp:`std.textio` and the runtime library, :samp:`grt`, are given under :ref:`LIC:GPLv2`. - The documentation is given under :ref:`LIC:CC-BY-SA`. @@ -27,7 +26,7 @@ Copyrights | Licenses .. _LIC:GPLv2: GNU GPLv2 -============== +========= GHDL is copyright |copy| 2002 - 2017 Tristan Gingold. @@ -38,7 +37,7 @@ This program is distributed in the hope that it will be useful, but **WITHOUT AN .. _LIC:CC-BY-SA: CC-BY-SA -============== +======== This is a free documentation; you can redistribute it and/or modify it under the terms of the `Creative Commons Attribution-ShareAlike 4.0 <https://creativecommons.org/licenses/by-sa/4.0/>`_ license. You are free to **share** (copy and redistribute the material in any medium or format) and/or **adapt** (remix, transform, and build upon the material for any purpose, even commercially). We cannot revoke these freedoms as long as you follow the these terms: @@ -51,7 +50,7 @@ See `CC-BY-SA-4.0 Legal Code <https://creativecommons.org/licenses/by-sa/4.0/leg .. _LIC:contributors: List of Contributors -============== +==================== ========================= ============================================================ Contributor [#f1]_ Role @@ -77,7 +76,7 @@ With apologies to anyone who ought to be either on this table or in the GitHub c .. container:: footnotes - .. rubric:: Footnotes + .. rubric:: Footnotes - .. [#f1] In alphabetical order. - .. [#f2] Maintainer. + .. [#f1] In alphabetical order. + .. [#f2] Maintainer. diff --git a/doc/references/CodingStyle.rst b/doc/references/CodingStyle.rst index 76d33b5ca..ddecb6339 100644 --- a/doc/references/CodingStyle.rst +++ b/doc/references/CodingStyle.rst @@ -1,7 +1,7 @@ .. _REF:Style: -Coding style -################# +Coding Style +############ Ada subset: use only a simple (VHDL like) subset of Ada: no tasking, no controlled types... VHDL users should easily understand that subset. @@ -15,77 +15,125 @@ But: 3 spaces for indentation. No trailing spaces, not TAB (HT). Subprograms must have a comment before to describe it, like: + +.. code-block:: Ada + -- Analyze the concurrent statements of PARENT. procedure Sem_Concurrent_Statement_Chain (Parent : Iir); + The line before the comment must be a blank line (unless this is the first declaration). Don't repeat the comment before the subprogram body. * For subprograms: -1) Declare on one line when possible: - function Translate_Static_Aggregate (Aggr : Iir) return O_Cnode - -2) If not possible, put the return on the next line: - function Translate_Static_String (Str_Type : Iir; Str_Ident : Name_Id) - return O_Cnode - -3) If not possible, put parameters and return on the next line: - function Create_String_Literal_Var_Inner - (Str : Iir; Element_Type : Iir; Str_Type : O_Tnode) return Var_Type - -4) If not possible, return on the next line: - function Translate_Shortcut_Operator - (Imp : Iir_Implicit_Function_Declaration; Left, Right : Iir) - return O_Enode - -5) If not possible, one parameter per line, just after subprogram name: - procedure Translate_Static_Aggregate_1 (List : in out O_Array_Aggr_List; - Aggr : Iir; - Info : Iir; - El_Type : Iir) -6) If not possible, add a return after subprogram name: - function Translate_Predefined_TF_Array_Element - (Op : Predefined_Boolean_Logical; - Left, Right : Iir; - Res_Type : Iir; - Loc : Iir) - return O_Enode - -7) If not possible, ask yourself what is wrong! Shorten a name. + + 1. Declare on one line when possible: + + .. code-block:: Ada + + function Translate_Static_Aggregate (Aggr : Iir) return O_Cnode + + 2. If not possible, put the return on the next line: + + .. code-block:: Ada + + function Translate_Static_String (Str_Type : Iir; Str_Ident : Name_Id) + return O_Cnode + + 3. If not possible, put parameters and return on the next line: + + .. code-block:: Ada + + function Create_String_Literal_Var_Inner + (Str : Iir; Element_Type : Iir; Str_Type : O_Tnode) return Var_Type + + 4. If not possible, return on the next line: + + .. code-block:: Ada + + function Translate_Shortcut_Operator + (Imp : Iir_Implicit_Function_Declaration; Left, Right : Iir) + return O_Enode + + 5. If not possible, one parameter per line, just after subprogram name: + + .. code-block:: Ada + + procedure Translate_Static_Aggregate_1 (List : in out O_Array_Aggr_List; + Aggr : Iir; + Info : Iir; + El_Type : Iir) + + 6. If not possible, add a return after subprogram name: + + .. code-block:: Ada + + function Translate_Predefined_TF_Array_Element + (Op : Predefined_Boolean_Logical; + Left, Right : Iir; + Res_Type : Iir; + Loc : Iir) + return O_Enode + + 7) If not possible, ask yourself what is wrong! Shorten a name. * Rule for the 'is': one a new line only if the declarative part is not empty: - procedure Translate_Assign (Target : Mnode; Expr : Iir; Target_Type : Iir) - is - Val : O_Enode; - begin -vs - function Translate_Static_Range_Dir (Expr : Iir) return O_Cnode is - begin - -If the parametere line is too long with the 'is', put in on a separate line: - procedure Predeclare_Scope_Type - (Scope : in out Var_Scope_Type; Name : O_Ident) is + + .. code-block:: Ada + + procedure Translate_Assign (Target : Mnode; Expr : Iir; Target_Type : Iir) + is + Val : O_Enode; + begin + + vs. + + .. code-block:: Ada + + function Translate_Static_Range_Dir (Expr : Iir) return O_Cnode is + begin + + If the parametere line is too long with the 'is', put in on a separate line: + + .. code-block:: Ada + + procedure Predeclare_Scope_Type + (Scope : in out Var_Scope_Type; Name : O_Ident) is * Generic instantiation: put the generic actual part on a new line: - procedure Free is new Ada.Unchecked_Deallocation - (Action_List, Action_List_Acc); + + .. code-block:: Ada + + procedure Free is new Ada.Unchecked_Deallocation + (Action_List, Action_List_Acc); * For if/then statement: -1) 'then' on the same line: - if Get_Expr_Staticness (Decl) = Locally then - -2) If not possible, 'then' is alone on its line aligned with the 'if': - if Expr = Null_Iir - or else Get_Kind (Expr) = Iir_Kind_Overflow_Literal - then -3) For a multiline condition, 'or else' and 'and then' should start lines. + 1. 'then' on the same line: + + .. code-block:: Ada + + if Get_Expr_Staticness (Decl) = Locally then + + 2. If not possible, 'then' is alone on its line aligned with the 'if': + + .. code-block:: Ada + + if Expr = Null_Iir + or else Get_Kind (Expr) = Iir_Kind_Overflow_Literal + then + + 3. For a multiline condition, 'or else' and 'and then' should start lines. * 'Local' variable declaration: -Do not initialize variables, constants must be declared before variables: - is - N_Info : constant Iir := Get_Sub_Aggregate_Info (Info); - Assoc : Iir; - Sub : Iir; - begin -If the initialization expression has a side effect (such as allocation), do -not use a constant.
\ No newline at end of file + Do not initialize variables, constants must be declared before variables: + + .. code-block:: Ada + + is + N_Info : constant Iir := Get_Sub_Aggregate_Info (Info); + Assoc : Iir; + Sub : Iir; + begin + + If the initialization expression has a side effect (such as allocation), do + not use a constant.
\ No newline at end of file diff --git a/doc/references/CommandReference.rst b/doc/references/CommandReference.rst index 4adb2dd36..2d7dc491a 100644 --- a/doc/references/CommandReference.rst +++ b/doc/references/CommandReference.rst @@ -7,7 +7,7 @@ Command Reference .. HINT:: The most common commands and options are shown in section :ref:`USING:Invoking`. Here the advanced and experimental features are described. Environment variables -============= +===================== .. envvar:: GHDL_PREFIX @@ -21,7 +21,7 @@ There are a few GHDL commands which are seldom useful. .. index:: cmd help Help [:samp:`-h`] ------------- +----------------- .. option:: --help, -h @@ -36,7 +36,7 @@ for this later command are displayed:: .. index:: cmd display configuration Display config [:samp:`--disp-config`] -------------------- +-------------------------------------- .. option:: --disp-config <[options]> @@ -46,7 +46,7 @@ Display the program paths and options used by GHDL. This may be useful to track .. index:: display :samp:`std.standard` Display standard [:samp:`--disp-standard`] ---------------------- +------------------------------------------ .. option:: --disp-standard <[options]> @@ -55,7 +55,7 @@ Display the :samp:`std.standard` package. .. index:: cmd version Version [:samp:`--version`] ---------------- +--------------------------- .. option:: --version, -v @@ -70,7 +70,7 @@ The following commands act on one or several files. These are not analyzed, ther .. index:: vhdl to html Pretty print [:samp:`--pp-html`] --------------------- +-------------------------------- .. option:: --pp-html <[options] file...> @@ -84,7 +84,7 @@ The style of the html file can be modified with the :option:`--format=` option: .. index:: cmd file find Find [:samp:`-f`] ------------- +----------------- .. option:: -f <file...> @@ -93,7 +93,7 @@ The files are scanned, parsed and the names of design units are displayed. Desig .. index:: cmd file chop Chop [:samp:`--chop`] ------------- +--------------------- .. option:: --chop <files...> @@ -112,19 +112,19 @@ This command may be useful to split big files, if your computer has not enough m .. index:: cmd file lines Lines [:samp:`--lines`] -------------- +----------------------- .. option:: --lines <files...> Display on the standard output lines of files preceded by line number. GCC/LLVM only commands -================= +====================== .. index:: cmd GCC/LLVM binding Bind [:samp:`--bind`] ------------- +--------------------- .. option:: --bind <[options] primary_unit [secondary_unit]> @@ -133,7 +133,7 @@ Performs only the first stage of the elaboration command; the list of objects fi .. index:: cmd GCC/LLVM linking Link [:samp:`--link`] ------------- +--------------------- .. option:: --link <[options] primary_unit [secondary_unit]> @@ -142,14 +142,14 @@ Performs only the second stage of the elaboration command: the executable is cre .. index:: cmd GCC/LLVM list link List link [:samp:`--list-link`] ------------------ +------------------------------- .. option:: --list-link <primary_unit [secondary_unit]> This command may be used only after a bind command. GHDL displays all the files which will be linked to create an executable. This command is intended to add object files in a link of a foreign program. Options -================= +======= .. option:: --mb-comments, -C diff --git a/doc/shields.txt b/doc/shields.inc index f1fac33b3..50dc2c89f 100644 --- a/doc/shields.txt +++ b/doc/shields.inc @@ -1,66 +1,71 @@ -.. This file provides the following shields: travis-ci appveyor tag release license mailing gitter issues-new issues-open issues-closed issues-pr issues-pr-closed github gh-logo +.. # This file provides the following shields: travis-ci appveyor tag release + # license mailing gitter issues-new issues-open issues-closed issues-pr + # issues-pr-closed github gh-logo -.. Use http://b64.io/ to encode any image to base64. Then replace `/` with `%2F` and `+` with `%2B` (or use http://meyerweb.com/eric/tools/dencoder/). Beware that `?logo=data:image/png;base64,` must also be converted to percent encoding so that the URL is properly parsed. +.. # Use http://b64.io/ to encode any image to base64. Then replace `/` with + # `%2F` and `+` with `%2B` (or use http://meyerweb.com/eric/tools/dencoder/). + # Beware that `?logo=data:image/png;base64,` must also be converted to + # percent encoding so that the URL is properly parsed. .. |SHIELD:travis-ci| image:: https://img.shields.io/travis/tgingold/ghdl/master.svg?style=flat&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAIP0lEQVR42qVXaUyUWRaFycyP%2BTVLemaSSfrPJN3JZJKOPyY6uBLTQgGlUMVeFHuxFaioKGpcAFFQUaOigAsmo7ghikZtxZVFCCKgqOi4ICoqqLjghqjcOeem%2B5sQFZnuL3l5VV%2B9d%2B9595577iuX%2F%2FcZNWrUX7y8vMyJiYmbpk6d2pKamto5bdq0LnxuT05OPhgUFOQcOXLkP35a7%2Bvr6%2FKLnmXLlun87t27X02YMKFkzpw5va2trXL37l158OCBPHz4UEdXV5fcu3dPbt26Jdu3b%2B%2Fz8%2FNrM5vNf%2BNeAPxlIHAi06xZs7rOnj0rL168kPb2dnn8%2BLE8evToo0EgHPfv35e1a9cKQOT9LKc2m03nyMhIv%2FXr18uzZ8%2F0pDU1NXLz5k0xTzSLycs0cHibBClhBOTJkycKqKmpSZCyGkTv10N27unpqfPw4cNDSkpK5OrVqzSmAHbu3CnXr1%2BXhIQECQkNkeCQYHEkxAPQRHEmJ0taWposWbJEOjs7dX1bW5s0NjYyEtW0OXny5KGBMJlMf1ixYsUHOqYRGmPYi4qK5PLly5KUlCSLFi0S5FqCAaSutk6io6MlMzNTtmzZIkwX9zASdXV10tLSQhALaRtEHdy5iLhYrdbbP53gxo0baqy7u1tWrlxJAErA7sfdYrFYNBINZxv0XUdHh5SXl8uhQ4eMPbW1tfqZqQwODv7rF0%2F%2FPZ6GhoZ%2B5v3AgQNKqqdPnyoBly9fztMxJeSFAeDcuXN8p9Wxf%2F9%2BBfH8%2BXMFcP78eSMlWN%2F8SafDhg0zPqOmG2%2Ffvi137tzRkF%2B6dEny8vLE399fUA1y%2BvRpGtMT%2B1n8JMQWKhUVFQTKiKlzkE7XHjlyRJqbm7lWI3n06NG%2B0aNHfzvAOVDq7Obm9mcIzIbS0lK5cuWKVFVVyerVq2Xv3r2aw5kzZ0pubq6cOnWKNa8njYyKlKRkpyBlPL2yPiUlhfzQVJ04cUI2bdrE1CmI%2Bvp6Wbp06bkRI0ZYBoAA4u9JIIAxGL9jxw5GgeRjCjT8GzdulM2bN2s5btu2TcJsNgmz2yU8IkIBHz58WIm4atUq6enpoS21iagyJbTL1BEYQe8zALi7u%2BdiAxcYg8iZd4a2srJST%2B9wOMTb25tk0gqYiPLjmDRpkkYhJCRE4uPjBeUmBw8e1JJ9%2Ffo108GDGLYJJjw8XAwAY8eOzedLIuZCkoY1Tzbv2rVLEV%2B4cIE5NpSOPCHrORh%2BpoX7GDVqx5kzZ2Tfvn2yZ88eVUVKOG1zMAoRiJoBADnJpEHmiMTh5prqaimHgeLiYs2p0%2BkkETUCXt5eUD8dVDod0A7OjIhGYcGCBVJQUCBlZWVMD21yZjQ1Aj4%2BPv8DMGbMmDCemDJKR%2BPGjRNfhNgeES7hkREML0tIAfiYzWK3h6kA2TBjPUNMkPjdKgmJiRIHdXTEIV0%2B3poWdEqBrGvYs7Oz5dixY0zhfwwAULGvwsLCVMvt4XaJdcRKQlIinahTdEE60FxDyQDOl1Whsrt48WI1Ghpqkxjso3OSkpGaN2%2Be5OfnGwNiRBUlSQnMNqAScEpvi9UiMbGxgj4uqFcl2ty5c2XGjBn6vbCwkGlibbM0WWpaEdAurX0eonhLMbmjJM7JyWFZ0h4JrLYCAwM%2FIJpRsOPqAlTqHPX%2FDXKHU4T2BAYFfsAirQA%2B1HNupNo1NTeR1RzqnJrBCGVkZGiX5MO%2BsBm86evrE9wjpL%2B%2Fn6%2B1R0yfPp0cqfxICRGuDoweEKkxJiaGZaSsfvnypTK8EyLCfK4tLEClPKQ9rqFCsu45U%2FO19gODgmXm7NkQsDICpQ0dGzZsoLBRP%2FrHjx%2F%2Fb5gwnFeDkeunTJnye7J0zZo1zB1DrBtfvXql9ezp4SFubv8Ci09rmeGmQxAsNQWB2xMdajpGurmRI4Zz2KBdKiJ1gNVyLC4uztUFOR6NcJsJBMz%2FHUrwPRWQqnfy5EluplHKL0nIk%2FIdDWl%2Bjx8%2FLu%2Ffv9eajgV33rx5w9Qoy69du8Zy43qt%2B6ysLA7VDcj%2BVj09yuMbzgDBLvhb3AHuV1ZWybp168h8CpPm8O3bt4IOSSlWIwsXLmQFkB%2FMNVlNpSQXWBX8TcO9detW2b17t8yfP5%2BVwshSrlnmjoEXTwWT4moyeda0tl6mkGhIESYC4elY6zCcg%2Fe5MDhPAJZEZYSUgLORd4Cjc%2B4FoBxGjaCQogyWMEVIbYP0f%2FzMXWD8KKvV8i4gIOA8ygcLEzhQQrEwvBgdsBzt%2BSLCeJcRYYulLCvDS3eXwvFSSO4lKF4l0lCB0%2B9CNPORqgpwIq3Fw8PDirT%2F8xOuSUbTgO%2FZ2Yva6uvr0GIb0UrvoSM%2B0ZGenk6RgSL6yAQQc5y7u5ghq%2F4BARJqs1ELlAe9vb1IUTd7B%2FZ3Qaq9nHDugVI3D3YdcwWzv0Y5uqI%2FpOMKTgYbTKYexMXHSaIz6bOD94OJCDfTwT7CywrbMWz24MLbi1R8DdJ%2B5NsQJSxIxeIqCExAVFRU%2B8WLF6WosEiNhIbZ6GRIIzo2WiIiI9gvMEeqPCMFJS6DPUQGyfwNkHZAlhnmtww3DTlTkj%2FliNrPvvHFqFihmC5DfXDyP1nQAZO%2BfFIoXxDb82cdE3gwOiLELuPHxje4c%2Bi1ziZPUzxuPjTyScMcDvCBf1IKCwpBQn90UYfEo2qiYqKVjAGBAc%2B9fXxqQdL0H1V3aBFAGeqMlpnKjmgQD62UTtiy%2FSwWtmYqm5IUXKFeMM%2FsomV2u%2F3vtAEuufysByfgRJX8DshTPU2mPPy7yQBBYzGWgC%2FVkOSXWVmZZHwnSPoD%2FlOmodXSsWFjsOe%2FCAcrQqMD2awAAAAASUVORK5CYII%3D - :target: https://travis-ci.org/tgingold/ghdl - :alt: Build status by Travis-CI + :target: https://travis-ci.org/tgingold/ghdl + :alt: Build status by Travis-CI .. |SHIELD:appveyor| image:: https://ci.appveyor.com/api/projects/status/rsq60m5wcly3og8j?svg=true - :target: https://ci.appveyor.com/project/Paebbels/poc/branch/release - :alt: Build status by AppVeyor + :target: https://ci.appveyor.com/project/Paebbels/poc/branch/release + :alt: Build status by AppVeyor .. |SHIELD:tag| image:: https://img.shields.io/github/tag/tgingold/ghdl.svg?label=latest%20tag&style=flat - :target: https://github.com/tgingold/ghdl/tags - :alt: Latest tag + :target: https://github.com/tgingold/ghdl/tags + :alt: Latest tag .. |SHIELD:release| image:: https://img.shields.io/github/release/tgingold/ghdl.svg?label=latest%20release&style=flat - :target: https://github.com/tgingold/ghdl/releases - :alt: Latest release + :target: https://github.com/tgingold/ghdl/releases + :alt: Latest release .. |SHIELD:code-lic| image:: https://img.shields.io/badge/code%20license-GPLv2-bd0000.svg?style=flat - :target: Licenses.html - :alt: GNU General Public License 2 + :target: Licenses.html + :alt: GNU General Public License 2 .. |SHIELD:doc-lic| image:: https://img.shields.io/badge/doc%20license-CC--BY--SA--4.0-aab2ab.svg?style=flat - :target: Licenses.html - :alt: Creative Commons Attribution-ShareAlike 4.0 + :target: Licenses.html + :alt: Creative Commons Attribution-ShareAlike 4.0 .. |SHIELD:mailing| image:: https://img.shields.io/badge/mail.gna.org-ghdl--discuss-ff69b4.svg?style=flat - :target: https://mail.gna.org/listinfo/ghdl-discuss/ + :target: https://mail.gna.org/listinfo/ghdl-discuss/ .. |SHIELD:gitter| image:: https://img.shields.io/gitter/room/ghdl1/Lobby.svg?colorB=4cb696 - :target: https://gitter.im/ghdl1/Lobby - :alt: Talk to us on Gitter + :target: https://gitter.im/ghdl1/Lobby + :alt: Talk to us on Gitter .. |SHIELD:issues-new| image:: https://img.shields.io/badge/new-issue-yellowgreen.svg?style=flat - :target: https://github.com/tgingold/ghdl/issues/new - :alt: Open new issue at GitHub + :target: https://github.com/tgingold/ghdl/issues/new + :alt: Open new issue at GitHub .. |SHIELD:issues-open| image:: https://img.shields.io/github/issues/tgingold/ghdl.svg - :target: https://github.com/tgingold/ghdl/issues - :alt: Open issues + :target: https://github.com/tgingold/ghdl/issues + :alt: Open issues .. |SHIELD:issues-closed| image:: https://img.shields.io/github/issues-closed-raw/tgingold/ghdl.svg?style=flat - :target: https://github.com/tgingold/ghdl/issues?q=is%3Aissue+is%3Aclosed - :alt: Closed issues + :target: https://github.com/tgingold/ghdl/issues?q=is%3Aissue+is%3Aclosed + :alt: Closed issues .. |SHIELD:issues-pr| image:: https://img.shields.io/github/issues-pr/tgingold/ghdl.svg?style=flat - :target: https://github.com/tgingold/ghdl/pulls - :alt: Open pull requests + :target: https://github.com/tgingold/ghdl/pulls + :alt: Open pull requests .. |SHIELD:issues-pr-closed| image:: https://img.shields.io/github/issues-pr-closed-raw/tgingold/ghdl.svg?style=flat - :target: https://github.com/tgingold/ghdl/pulls - :alt: Closed pull requests + :target: https://github.com/tgingold/ghdl/pulls + :alt: Closed pull requests .. |SHIELD:contributors| image:: https://img.shields.io/github/contributors/tgingold/ghdl.svg?style=flat - :target: https://github.com/tgingold/ghdl/graphs/contributors - :alt: Contributors + :target: https://github.com/tgingold/ghdl/graphs/contributors + :alt: Contributors .. |SHIELD:github| image:: https://img.shields.io/badge/GitHub-tgingold/ghdl-323131.svg?style=flat&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAMAAABEpIrGAAABKVBMVEX%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FOe9X6AAAAYnRSTlMAAQIDBAcIDA0PEBESFBUWGBkeHyEoMTIzNDU4OTw%2BP0JGWVxeX2BiY2RlZ2hvc3R1eHp%2Bio%2BXm52epKmqq62usLe5wcLDxMnQ0dLW2tvc3t%2Fh4uPo6uvs8fLz9fb3%2Bvv8%2FsuNaVkAAAF7SURBVHgBjdHZW9NAFAXwE0iElCARZCkuIotEUFyQBSJERBEILaAo6d6e%2F%2F%2BPcO58aZslD%2Fxe5mHuPfOdbzA06R1e1sn65aE3ibw5v8OBjj%2BHNHuvx5Tenp1av2bOdSJkKWKBaAmxhYiFogVoEzckw%2BModXcckryZgDigsgLLu1MVT09V1TvPwgqVAyhlinmpMjsCZWRWCsxTlAEEFIvIWKQIALdLsYaMNYqui02KPw4ynN8Um%2FAp1pGzTuEj1Ek2cmz9dogmlVsUuKXSBEUFBaoUoKihQI0iPqaQMxWvnlOsImeV4hz7FBcmMswLin0sU9tBxg61ZYw3qB25SHhyRK0xDuySX179INtfN8qjOvz5u6BNjbsAplvsbVm%2FqAQGFOMb%2B1rTULZJPnsqf%2FMC2kv2bUOYZ%2BR3lLzPr0ehPWbszITmVsn3GCqRWtVFbKZC%2Fvz45tOj1EBlBgPOCUUpOXDiIMF4%2Bzc98G%2FDQNrY1tW9Bc26v%2Fowhof6D6AkqSgsdGGuAAAAAElFTkSuQmCC - :target: https://www.github.com/tgingold/ghdl - :alt: Source Code on GitHub + :target: https://www.github.com/tgingold/ghdl + :alt: Source Code on GitHub .. |SHIELD:gh-logo| image:: https://img.shields.io/badge/-tgingold/ghdl-323131.svg?style=flat&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAMAAABEpIrGAAABKVBMVEX%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FOe9X6AAAAYnRSTlMAAQIDBAcIDA0PEBESFBUWGBkeHyEoMTIzNDU4OTw%2BP0JGWVxeX2BiY2RlZ2hvc3R1eHp%2Bio%2BXm52epKmqq62usLe5wcLDxMnQ0dLW2tvc3t%2Fh4uPo6uvs8fLz9fb3%2Bvv8%2FsuNaVkAAAF7SURBVHgBjdHZW9NAFAXwE0iElCARZCkuIotEUFyQBSJERBEILaAo6d6e%2F%2F%2BPcO58aZslD%2Fxe5mHuPfOdbzA06R1e1sn65aE3ibw5v8OBjj%2BHNHuvx5Tenp1av2bOdSJkKWKBaAmxhYiFogVoEzckw%2BModXcckryZgDigsgLLu1MVT09V1TvPwgqVAyhlinmpMjsCZWRWCsxTlAEEFIvIWKQIALdLsYaMNYqui02KPw4ynN8Um%2FAp1pGzTuEj1Ek2cmz9dogmlVsUuKXSBEUFBaoUoKihQI0iPqaQMxWvnlOsImeV4hz7FBcmMswLin0sU9tBxg61ZYw3qB25SHhyRK0xDuySX179INtfN8qjOvz5u6BNjbsAplvsbVm%2FqAQGFOMb%2B1rTULZJPnsqf%2FMC2kv2bUOYZ%2BR3lLzPr0ehPWbszITmVsn3GCqRWtVFbKZC%2Fvz45tOj1EBlBgPOCUUpOXDiIMF4%2Bzc98G%2FDQNrY1tW9Bc26v%2Fowhof6D6AkqSgsdGGuAAAAAElFTkSuQmCC - :target: https://www.github.com/tgingold/ghdl - :alt: Source Code on GitHub + :target: https://www.github.com/tgingold/ghdl + :alt: Source Code on GitHub diff --git a/doc/shieldswho.txt b/doc/shieldswho.inc index 0e824023e..fae9c50ab 100644 --- a/doc/shieldswho.txt +++ b/doc/shieldswho.inc @@ -1,27 +1,23 @@ .. |SHIELD:gh-poc| image:: https://img.shields.io/badge/-VLSI--EDA/PoC-323131.svg?style=flat&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAMAAABEpIrGAAABKVBMVEX%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FOe9X6AAAAYnRSTlMAAQIDBAcIDA0PEBESFBUWGBkeHyEoMTIzNDU4OTw%2BP0JGWVxeX2BiY2RlZ2hvc3R1eHp%2Bio%2BXm52epKmqq62usLe5wcLDxMnQ0dLW2tvc3t%2Fh4uPo6uvs8fLz9fb3%2Bvv8%2FsuNaVkAAAF7SURBVHgBjdHZW9NAFAXwE0iElCARZCkuIotEUFyQBSJERBEILaAo6d6e%2F%2F%2BPcO58aZslD%2Fxe5mHuPfOdbzA06R1e1sn65aE3ibw5v8OBjj%2BHNHuvx5Tenp1av2bOdSJkKWKBaAmxhYiFogVoEzckw%2BModXcckryZgDigsgLLu1MVT09V1TvPwgqVAyhlinmpMjsCZWRWCsxTlAEEFIvIWKQIALdLsYaMNYqui02KPw4ynN8Um%2FAp1pGzTuEj1Ek2cmz9dogmlVsUuKXSBEUFBaoUoKihQI0iPqaQMxWvnlOsImeV4hz7FBcmMswLin0sU9tBxg61ZYw3qB25SHhyRK0xDuySX179INtfN8qjOvz5u6BNjbsAplvsbVm%2FqAQGFOMb%2B1rTULZJPnsqf%2FMC2kv2bUOYZ%2BR3lLzPr0ehPWbszITmVsn3GCqRWtVFbKZC%2Fvz45tOj1EBlBgPOCUUpOXDiIMF4%2Bzc98G%2FDQNrY1tW9Bc26v%2Fowhof6D6AkqSgsdGGuAAAAAElFTkSuQmCC - :target: https://www.github.com/VLSI-EDA/PoC - :alt: Source Code on GitHub + :target: https://www.github.com/VLSI-EDA/PoC + :alt: Source Code on GitHub .. |SHIELD:rtd-poc| image:: https://img.shields.io/badge/-poc--library-2980b9.svg?style=flat&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAABmJLR0QA%2FwD%2FAP%2BgvaeTAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH4QIWAi8BeOHlMQAAAB1pVFh0Q29tbWVudAAAAAAAQ3JlYXRlZCB3aXRoIEdJTVBkLmUHAAADpklEQVRYw%2B2XT2hcVRTGf%2B%2Fl1TRjpq3GIiFIQ20V3VhshDCCcchRkC78ByKC6MKVIAqu3LgX3boQKSgK4sKFFZSQMxkHS7RohdJorYrYVBtrqR1rZ5p0Ou%2B68JvyHCbTmTQgqAcub96fufd75%2Fu%2B886FtiiVSvQa5XKZK40oe%2BLumFnr9xbgWmAjkABNYAU4B5wxs5W1LFgqlZienu4MQAtvBx4Hbge2AZsF4gJQA04Di8DXwFHgR2AJ%2BB1YFtgh%2FWcTsBW4AajlcrkPCoVCyK6XdAD5BPBil5f4EtgNPKbzM8AfwHmgAcTABo2NQF7HfYVCYV%2F7ZJ0AbNJxAXgLWIiiaCmEMAa8D7yuMRhF0c4Qws3AKHC9FkLZOq3MHAOez9y7LIAY%2BNjMiu6eB8ZCCFuVykg6GAXuCyGUgA%2BBixpphtoBIDazZXd%2FSgB7AhCAXe7%2BLvBQ2zOpANwJvAC8qvT%2FBPwiOgCGgRGgUS6Xp5rNZmvengFsAR4BPgOOA2eB64D7gSEz2%2Bvu88CtwDgwJsds1hzHgSPAyXw%2BH6rV6qqCSlax5oLe%2FoSZ1ebm5obTNN0lAJfCzGbaHBTpemi3dz8AAAal9NfcfXeapom0EYCauz8DvOLuVeAAcAj4QZnC3Yekk9jMXspktmcKdgLvyFbLElgsYLkM9%2FcCdwB3S3QDGa0EoFapVF5uNBp9U1AD3gMc%2BEbVbxvwkd4qBd7QaKV5VJ4HqANVMzu3FgoiCeg5oAjco4mvaZVjdzfgyUw1XAROyvstCsfdPTKzw91KcycAKXCbuB2VpbL0RMDPAvWs6kNN46KeG1DhuapSqeRFQehHhBukg076SMzsiLs%2FrIWGgVuA7cDV0soycAr4ampqKl2LC7pFcPecNPGryu4BM9vfZr0BgaFfF1wuVlQP9soJ3wHfuvsSUBVFOVXCZH5%2B%2Ful6vb6uGRgE3lbpvUmpHwcKogBRcBY4EcfxumcgMrMGUP6rKSpHzWYzJ2Ct%2BZoSZG1ycjKstwb%2BFsViMWRc0FU7rPLp%2FUfjPwXgfwr%2BPRm40Eun02sGkjUA3uPui8CnKki9RKOfQtS6dh44rPoe9IW8EXgUeBA45e6HgP3AQeBoHMe%2FpWmanWsMmFRfcbBXAJ8Ab5rZF60mM9OEtr6Ed6lrfgDYc6mRSNPQZe8519fmdHZ2liRJKBaLHe9nru1QX7hDu6phNTV1dUjHgM%2FN7PuZmRlGRkaYmJi4cvVWKpU17Yzb40%2B0JFzTjEp6egAAAABJRU5ErkJggg%3D%3D - :target: http://poc-library.readthedocs.io/en/latest/?badge=latest - :alt: Documentation on ReadTheDocs + :target: http://poc-library.readthedocs.io/en/latest/?badge=latest + :alt: Documentation on ReadTheDocs .. |SHIELD:gh-vunit| image:: https://img.shields.io/badge/-VUnit/vunit-323131.svg?style=flat&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAMAAABEpIrGAAABKVBMVEX%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FOe9X6AAAAYnRSTlMAAQIDBAcIDA0PEBESFBUWGBkeHyEoMTIzNDU4OTw%2BP0JGWVxeX2BiY2RlZ2hvc3R1eHp%2Bio%2BXm52epKmqq62usLe5wcLDxMnQ0dLW2tvc3t%2Fh4uPo6uvs8fLz9fb3%2Bvv8%2FsuNaVkAAAF7SURBVHgBjdHZW9NAFAXwE0iElCARZCkuIotEUFyQBSJERBEILaAo6d6e%2F%2F%2BPcO58aZslD%2Fxe5mHuPfOdbzA06R1e1sn65aE3ibw5v8OBjj%2BHNHuvx5Tenp1av2bOdSJkKWKBaAmxhYiFogVoEzckw%2BModXcckryZgDigsgLLu1MVT09V1TvPwgqVAyhlinmpMjsCZWRWCsxTlAEEFIvIWKQIALdLsYaMNYqui02KPw4ynN8Um%2FAp1pGzTuEj1Ek2cmz9dogmlVsUuKXSBEUFBaoUoKihQI0iPqaQMxWvnlOsImeV4hz7FBcmMswLin0sU9tBxg61ZYw3qB25SHhyRK0xDuySX179INtfN8qjOvz5u6BNjbsAplvsbVm%2FqAQGFOMb%2B1rTULZJPnsqf%2FMC2kv2bUOYZ%2BR3lLzPr0ehPWbszITmVsn3GCqRWtVFbKZC%2Fvz45tOj1EBlBgPOCUUpOXDiIMF4%2Bzc98G%2FDQNrY1tW9Bc26v%2Fowhof6D6AkqSgsdGGuAAAAAElFTkSuQmCC - :target: https://www.github.com/VUnit/vunit - :alt: Source Code on GitHub + :target: https://www.github.com/VUnit/vunit + :alt: Source Code on GitHub .. |SHIELD:doc-vunit| image:: https://img.shields.io/badge/doc-vunit.github.io-blue.svg?style=flat - :target: https://vunit.github.io/documentation - :alt: Documentation on vunit.github.io + :target: https://vunit.github.io/documentation + :alt: Documentation on vunit.github.io .. |SHIELD:gl-p1076| image:: https://img.shields.io/badge/-IEEE--P1076-323131.svg?style=flat&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAD%2FElEQVR42r2VR2gUURjHJ3oRUUwU9CCIWN7MBEQ8iAQbMWLsikY92BYLhiQmKxZiN4rYsaJELHFdC7ajBy8q4kFBJIoHQcWSaDTrJkbT3Ff8v0dmM5OZzCbZ4IMfW%2BYr%2F6%2B8Xa3t%2BZxlSnqAnvLzl6x0LdkjY1nxPkzWExqngNlgaTcktl5XglxV0FTT18ESUA6eggHqQfJCvoDq95P0DhkPBgI0glHdkHwi%2BAMaQHZH2rUNiBZyQUqSAg4DCjg42xGHdzYBD9VCTjG7mrw3eGKL9xyk%2BjmkA2EHyQclUX0G%2BGaLFwGZfu0%2FCkQbCpMQkO8Rb7Ofw1sPhzeWyE4m7wPueMS7D1K9qp8AfgLhwdAuVD8E1HrEagTDvRx2A9aOgJLOdgG2OUC0Q8Bh%2FCEjve%2BnTPP%2Bpymm8ALPyjvbgQTxHkubplNEU6cmoI%2F%2BucT4HMkxOGAe1FbNNvbBWS7V%2BkRUZBt50cU6846H7xYZormUpGlKxV2i0RtkGTtCBCsChW7oeiKiSwylHgn8UDaRhYbgQa9YoACcQMww2aAE0KukF7gJBN1NGC1QCZ3A8U9A5%2Fgj4YkEfMw0ReManbliABV7L3KEiEC%2B15aANFAPRYKWEU6LYZDvdm7OJfzbzAQCUH1FtmkV4aYY8S8BFAs4GCEFzAdCEQYX8SAInEFU%2B6oXGNy3%2Fag%2ButignskLEbOUMJnDJmCnFHAPCAdnCFroFlC3QmcYg9%2F8ecNqnXu2%2FgSh9JozD3ghBUSAcHGAuAL9zSOsYlr7Y%2Fg602ByVK7k%2B5H8ujsHqJcCckGN66Hchx2OTqjN%2FjHPYD7b7xxdPtiplo57JG8AxdYijgflDoMwkAuzgTD7GH4HdOp1HeUNqVuuM9i0Vr4F%2Fhc8k78C4zT7wRe9wW2XiPPqVnCbCIzAPYbK6SZvWmfrWBCctpbOQRnoV1dKHMnt7%2FPAL4eI45hhgeM2sLZdqJprcFZkm%2F9BwtrMvRps0to7sRDRWJhYIsaAh3HnENjXWh02nX3MdAr4tRTtL2qZ%2Bx7YOjf%2BEZjgKtjvwKg%2FKIkHuYzqtgIIiCFJZbbjn5PLG6KSb8drWXzuDOwFA1TMsK7FroxIlHgkGGuJ6AEyQE18H9DmGMYRyWkZA6iaY1BV%2FUbCYWMlrwXTm0PDUvyr9u%2BC9ZoKHqi2nlSjUP8NEMDlrx%2B2n7Kg2hVOw0rAM9DfitGIqrt8aCguoicowWJFsWCiaS3hlTNMLjugbsl%2BtbBR2XJ7Ackf9y3JgqinsRIivmPzv6P9dJda1JfoUJZ9lNbpfhFhMpCVkmM1q3RRn6d%2BsM7RWyTNbvtfzu%2BgHmg%2BRGbJ9%2Byqrv31q7r7u7Gy9fOZrlf8DwydcgOFUML4AAAAAElFTkSuQmCC - :target: https://gitlab.com/IEEE-P1076 - :alt: Source Code on GitLab + :target: https://gitlab.com/IEEE-P1076 + :alt: Source Code on GitLab .. |SHIELD:tw-p1076| image:: https://img.shields.io/badge/-eda--twiki.org-orange.svg?style=flat&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAABmJLR0QA%2FwD%2FAP%2BgvaeTAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH4QIWAhImtwMY5AAAAB1pVFh0Q29tbWVudAAAAAAAQ3JlYXRlZCB3aXRoIEdJTVBkLmUHAAACwUlEQVRYw%2B1XTWgTQRT%2BZpOokURDg6GiaAwoCEX8QQpevFTQHgTBY8FrERSstKLePVSleLSH3qUFRSx48CR4CIJU8BC0WKqVULQiJsZmZ94%2BD83GJPOTDR68dGHZXYb3vu99882bWWDz%2Bs%2BXCF%2F408Au%2BD9GoaqXoIICFAQUAAWAGk%2FXTQCkAFSwhiAxD94%2BJS6vLEQiwOULp1B5Og9JGS2xbCEgDcDheOcYxQhb%2BibF2NdbTgL8%2BWQOv98sQlJaSyQ7qpeW6k0kQkWyR86Jq2%2Bf2wh4qK%2BMdgWXBnBpeaoWMpKB1dIztwKl9BL8Sl4DF6lXkMGyltT%2BruCrs%2FD9nJYre%2FCMuP3hhYlAHH5tvz5%2FAJL5B%2BL0u9leHM13My8h%2FZyWq1ot2KdAsdACFAAVxHpeUzZ%2F1Nc9BwHD3IXf%2F0og9A4Ja0jcCC4B8PfjPJuqNsfFtkUx8q3UlJvZw730eRBUI2YdvuzTTBrmdRIggwfqq%2BNQGG%2BuBtAkgBstsTHUfz1ur5j1FSEBJBBBAW2Nc8d0cKBFh4BdO6SLADk6XOs392A61YsCUcBVD6YzKeAwtOfs%2FW1O7kJAWjYtW6zmAVcFBCBwEJBdPKCimpAcVQkLARlxu3YSkBZg6pLAthWbVHWakAwHj04fmJopORSI2FXNCpBBjaBHBWQEBTf6gAdQ4PaATQFlUa6TmE9sJ4DkEmTlgBOcABD385XUMZAQUGBcP5To2v3CnIE3DOAhXxwUYq7I7QeS6d038bN8xwm%2B0QsYBO4Y89o2Hd%2BigAQwMDgl5opjeiOKZ6fBW9esFfxtRAISXgPUawO3kW7N97p4jQ%2FvfMQjw%2Fv0U%2FHM0X6U339BreZZk5gAQol9B7huygB7CvfFwseJ9v%2BCmaEMlosTUBhCfMcJqJY2TQ7DKccyNHVUBcAPgESSsDf%2FZPPXbPP6A13nhms8bYukAAAAAElFTkSuQmCC - :target: http://www.eda-twiki.org/cgi-bin/view.cgi/P1076/WebHome - :alt: Documentation on eda-twiki.org - - - -
\ No newline at end of file + :target: http://www.eda-twiki.org/cgi-bin/view.cgi/P1076/WebHome + :alt: Documentation on eda-twiki.org diff --git a/doc/using/InvokingGHDL.rst b/doc/using/InvokingGHDL.rst index bf7619b7b..ceb25b1a6 100644 --- a/doc/using/InvokingGHDL.rst +++ b/doc/using/InvokingGHDL.rst @@ -1,20 +1,22 @@ .. program:: ghdl .. _USING:Invoking: -************* Invoking GHDL -************* +############# The form of the :program:`ghdl` command is :samp:`ghdl command [options...]`. There are multiple available commands, but these general rules apply: * The first argument selects the command. The options are used to slightly modify the action. * No option is allowed before the command. Except for the run command, no option is allowed after a filename or a unit name. -.. HINT:: If the number of options is large and the command line length is beyond the system limit, you can use a response file. An argument that starts with a :samp:`@` is considered as a response file; it is replaced by arguments read from the file (separated by blanks and end of line). +.. HINT:: + If the number of options is large and the command line length is beyond the system limit, you can use a response file. An argument that starts with a :samp:`@` is considered as a response file; it is replaced by arguments read from the file (separated by blanks and end of line). -.. HINT:: Only the most common commands and options are shown here. For most advanced and experimental features see section :ref:`REF:Command`. +.. HINT:: + Only the most common commands and options are shown here. For most advanced and experimental features see section :ref:`REF:Command`. -.. WARNING:: During analysis and elaboration GHDL may read the :samp:`std` and :samp:`ieee` files. The location of these files is based on the prefix, which is (in priority order): +.. WARNING:: + During analysis and elaboration GHDL may read the :samp:`std` and :samp:`ieee` files. The location of these files is based on the prefix, which is (in priority order): * the :option:`--PREFIX` command line option * the :envvar:`GHDL_PREFIX` environment variable @@ -23,14 +25,15 @@ The form of the :program:`ghdl` command is :samp:`ghdl command [options...]`. Th You should use the :option:`--disp-config` command to display and debug installation problems. Design building commands -================= +======================== The mostly used commands of GHDL are those to analyze and elaborate a design. + .. index:: cmd analysis Analysis [:samp:`-a`] ----------------- +--------------------- .. option:: -a <[options...] file...> @@ -38,10 +41,11 @@ Analyzes/compiles one or more files, and creates an object file for each source See :ref:`GHDL_options`, for details on the GHDL options. For example, to produce debugging information such as line numbers, use: :samp:`ghdl -a -g my_design.vhdl`. + .. index:: cmd elaboration Elaboration [:samp:`-e`] -------------------- +------------------------ .. option:: -e <[options...] primary_unit [secondary_unit]> @@ -59,10 +63,11 @@ Name of the units must be a simple name, without any dot. You can select the na * If mcode is used, this command elaborates the design but does not generate anything. Since the run command also elaborates the design, this con be skipped. + .. index:: cmd run Run [:samp:`-r`] ------------ +---------------- .. option:: -r <[options...] primary_unit [secondary_unit] [simulation_options...]> @@ -79,32 +84,36 @@ This command exists for three reasons: See section ':ref:`USING:Simulation`', for details on options. + .. index:: cmd elaborate and run Elaborate and run [:samp:`--elab-run`] -------------------------- +-------------------------------------- .. option:: --elab-run <[elab_options...] primary_unit [secondary_unit] [run_options...]> Acts like the elaboration command (see :option:`-e`) followed by the run command (see :option:`-r`). + .. index:: cmd checking syntax Check syntax [:samp:`-s`] --------------------- +------------------------- .. option:: -s <[options] files> Analyze files but do not generate code. This command may be used to check the syntax of files. It does not update the library. + .. index:: cmd analyze and elaborate Analyze and elaborate [:samp:`-c`] ------------------------------ +---------------------------------- .. option:: -c <[options] file... -<e|r> primary_unit [secondary_unit]> -.. HINT:: With GCC/LLVM, :option:`-e` should be used, and :option:`-r` with mcode. +.. HINT:: + With GCC/LLVM, :option:`-e` should be used, and :option:`-r` with mcode. The files are first parsed, and then a elaboration is performed, which drives an analysis. Effectively, analysis and elaboration are combined, but there is no explicit call to :option:`-a`. With GCC/LLVM, code is generated during the elaboration. With mcode, the simulation is launched after the elaboration. @@ -117,19 +126,23 @@ The advantages over the traditional approach (analyze and then elaborate) are: * You don't need to know an analysis order. * This command produces smaller executable, since unused units and subprograms do not generate code. -.. HINT:: However, you should know that currently most of the time is spent in code generation and the analyze and elaborate command generate code for all units needed, even units of :samp:`std` and :samp:`ieee` libraries. Therefore, according to the design, the time for this command may be higher than the time for the analyze command followed by the elaborate command. +.. HINT:: + However, you should know that currently most of the time is spent in code generation and the analyze and elaborate command generate code for all units needed, even units of :samp:`std` and :samp:`ieee` libraries. Therefore, according to the design, the time for this command may be higher than the time for the analyze command followed by the elaborate command. + +.. WARNING:: + This command is still under development. In case of problems, you should go back to the traditional way. -.. WARNING:: This command is still under development. In case of problems, you should go back to the traditional way. Design rebuilding commands -=================== +========================== Analyzing and elaborating a design consisting in several files can be tricky, due to dependencies. GHDL has a few commands to rebuild a design. + .. index:: cmd importing files Import [:samp:`-i`] --------------- +------------------- .. option:: -i <[options] file...> @@ -138,22 +151,21 @@ All the files specified in the command line are scanned, parsed and added in the .. HINT:: * Note that all the files are added to the work library. If you have many libraries, you must use the command for each library. - * Since the files are parsed, there must be correct files. However, since they are not analyzed, many errors are tolerated by this command. See :option:`-m`, to actually build the design. + .. index:: cmd make Make [:samp:`-m`] ------------- +----------------- .. option:: -m <[options] primary [secondary]> Analyze automatically outdated files and elaborate a design. The primary unit denoted by the :samp:`primary` argument must already be known by the system, either because you have already analyzed it (even if you have modified it) or because you have imported it. A file may be outdated because it has been modified (e.g. you just have edited it), or because a design unit contained in the file depends on a unit which is outdated. This rule is of course recursive. * With option :option:`--bind`, GHDL will stop before the final linking step. This is useful when the main entry point is not GHDL and you're linking GHDL object files into a foreign program. - * With option :option:`-f` (force), GHDL analyzes all the units of the work library needed to create the design hierarchy. Not outdated units are recompiled. This is useful if you want to compile a design hierarchy with new compilation flags (for example, to add the *-g* debugging option). The make command will only re-analyze design units in the work library. GHDL fails if it has to analyze an outdated unit from another library. @@ -166,17 +178,19 @@ The make command imports files which have been modified. Then, a design hierarch This is not perfect, since the default architecture (the most recently analyzed one) may change while outdated design files are analyzed. In such a case, re-run the make command of GHDL. + .. index:: cmd generate makefile Generate Makefile [:samp:`--gen-makefile`] -------------------------- +------------------------------------------ .. option:: --gen-makefile <[options] primary [secondary]> This command works like the make command (see :option:`-m`), but only a makefile is generated on the standard output. + Options -============ +======= .. index:: IEEE 1164 .. index:: 1164 @@ -306,12 +320,14 @@ Options Be verbose. For example, for analysis, elaboration and make commands, GHDL displays the commands executed. + Warnings -============= +======== Some constructions are not erroneous but dubious. Warnings are diagnostic messages that report such constructions. Some warnings are reported only during analysis, others during elaboration. -.. HINT:: You could disable a warning by using the :samp:`--warn-no-XXX` or :samp:`-Wno-XX` instead of :samp:`--warn-XXX` or :samp:`-WXXX`. +.. HINT:: + You could disable a warning by using the :samp:`--warn-no-XXX` or :samp:`-Wno-XX` instead of :samp:`--warn-XXX` or :samp:`-WXXX`. .. option:: --warn-reserved @@ -371,8 +387,9 @@ Some constructions are not erroneous but dubious. Warnings are diagnostic messag Emit a warning in case of runtime error that is detected during analysis. + Diagnostics Control -======================== +=================== .. option:: -fcolor-diagnostics .. option:: -fno-color-diagnostics @@ -383,7 +400,8 @@ Diagnostics Control .. option:: -fno-diagnostics-show-option Control whether the warning option is displayed at the end of warning messages, so that user can easily know how to disable it. - + + Library commands ================ @@ -396,38 +414,42 @@ A library's source code is usually stored and compiled into its own directory, t Furthermore, GHDL provides a few commands which act on a library: + .. index:: cmd library directory Directory [:samp:`--dir`] ------------------ +------------------------- .. option:: --dir <[options] [libs]> Displays the content of the design libraries (by default the :samp:`work` library). All options are allowed, but only a few are meaningful: :option:`--work`, :option:`--workdir` and :option:`--std`. + .. index:: cmd library clean Clean [:samp:`--clean`] -------------- +----------------------- .. option:: --clean <[options]> Try to remove any object, executable or temporary file it could have created. Source files are not removed. The library is kept. + .. index:: cmd library remove Remove [:samp:`--remove`] --------------- +------------------------- .. option:: --remove <[options]> Do like the clean command but remove the library too. Note that after removing a design library, the files are not known anymore by GHDL. + .. index:: cmd library copy Copy [:samp:`--copy`] ------------- +--------------------- .. option:: --copy <--work=name [options]> @@ -438,16 +460,18 @@ Make a local copy of an existing library. This is very useful if you want to ad ghdl --copy --work=ieee --ieee=synopsys ghdl -a --work=ieee numeric_unsigned.vhd + VPI build commands ================== These commands simplify the compile and the link of a user vpi module. They are all wrapper: the arguments are in fact a whole command line that is executed with additional switches. Currently a unix-like compiler (like `cc`, `gcc` or `clang`) is expected: the additional switches use their syntax. The only option is `-v` which displays the command before its execution. + .. index:: cmd VPI compile compile [:samp:`--vpi-compile`] -------------------- +------------------------------- .. option:: --vpi-compile <command> @@ -472,7 +496,7 @@ executes:: .. index:: cmd VPI link link [:samp:`--vpi-link`] ----------------- +------------------------- .. option:: --vpi-link <command> @@ -498,7 +522,7 @@ executes:: .. index:: cmd VPI cflags cflags [:samp:`--vpi-cflags`] ------------------- +----------------------------- .. option:: --vpi-cflags @@ -507,7 +531,7 @@ Display flags added by :option:`--vpi-compile`. .. index:: cmd VPI ldflags ldflags [:samp:`--vpi-ldflags`] -------------------- +------------------------------- .. option:: --vpi-ldflags @@ -516,7 +540,7 @@ Display flags added by :option:`--vpi-link`. .. index:: cmd VPI include dir include dir [:samp:`--vpi-include-dir`] ------------------------ +--------------------------------------- .. option:: --vpi-include-dir @@ -525,12 +549,13 @@ Display the include directory added by the compile flags. .. index:: cmd VPI library dir library dir [:samp:`--vpi-library-dir`] ------------------------ +--------------------------------------- .. option:: --vpi-library-dir Display the library directory added by the link flags. + .. _ieee_library_pitfalls: IEEE library pitfalls @@ -651,4 +676,5 @@ It is better to only use the standard packages defined by IEEE, which provides t .. index:: Math_Complex -.. HINT:: The :samp:`ieee` math packages (:samp:`math_real` and :samp:`math_complex`) provided with `GHDL` are fully compliant with the `IEEE` standard. +.. HINT:: + The :samp:`ieee` math packages (:samp:`math_real` and :samp:`math_complex`) provided with `GHDL` are fully compliant with the `IEEE` standard. diff --git a/doc/using/QuickStartGuide.rst b/doc/using/QuickStartGuide.rst index 4cbbe8027..f61a86d5d 100644 --- a/doc/using/QuickStartGuide.rst +++ b/doc/using/QuickStartGuide.rst @@ -1,41 +1,40 @@ .. program:: ghdl .. _USING:QuickStart: -****************** Quick Start Guide -****************** +################# In this chapter, you will learn how to use `GHDL` by working on a few examples. The `'Hello world'` program -======================= +=========================== To illustrate the large purpose of `VHDL`, here is a commented `'Hello world'` program which saved in a file named :file:`hello.vhdl`: .. code-block:: VHDL - -- Hello world program. - use std.textio.all; -- Imports the standard textio package. + -- 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; + -- 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; + 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; .. TIP:: - * Both :samp:`.vhdl` and :samp:`.vhd` extensions are used for VHDL source files, while :samp:`.v` is used for Verilog. - * 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. + * Both :samp:`.vhdl` and :samp:`.vhd` extensions are used for VHDL source files, while :samp:`.v` is used for Verilog. + * 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 `analysis` of a design file in `VHDL` terms. Run :samp:`ghdl -a hello.vhdl` in the `shell`. This command creates or updates a file :file:`work-obj93.cf`, which describes the library :samp:`work`. - Then, run :samp:`ghdl -e hello_world` in the `shell`. Option :option:`-e` means :dfn:`elaborate`, which is used to build a design, with the :samp:`hello_world` entity at the top of the hierarchy. @@ -43,14 +42,15 @@ To illustrate the large purpose of `VHDL`, here is a commented `'Hello world'` p .. code-block:: shell - Hello world! + Hello world! -.. HINT:: If a GCC/LLVM variant of `GHDL` is used: +.. HINT:: + If a GCC/LLVM variant of `GHDL` is used: + + * `Analysis` generates a file, :file:`hello.o`, which is the object file corresponding to your `VHDL` program. This is not created with mcode. + * The elaboration step is compulsory after the analysis and prior to launching the simulation; This wil 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, :samp:`./hello_world`. See :option:`-r` for more informartion. - * `Analysis` generates a file, :file:`hello.o`, which is the object file corresponding to your `VHDL` program. This is not created with mcode. - * The elaboration step is compulsory after the analysis and prior to launching the simulation; This wil 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, :samp:`./hello_world`. See :option:`-r` for more informartion. - .. HINT:: :option:`-e` can be bypassed with 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. The `heartbeat` program @@ -74,9 +74,6 @@ The `heartbeat` program end process; end behaviour; -.. TODO:: Complete `heartbeat` example program - - A full adder ============ @@ -84,87 +81,88 @@ VHDL is generally used for hardware design. This example starts with a `full ad .. 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; + 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, :samp:`ghdl -a adder.vhdl`, and try to execute the `adder` design. But this is useless, since nothing externally visible will happen. In order to check this full adder, a :dfn:`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. A file named :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; + -- 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, :samp:`ghdl -a adder_tb.vhdl`. -.. HINT:: Then, if required, elaborate the testbench: :samp:`ghdl -e adder_tb`. You do not need to specify which object files are required, since GHDL knows them and automatically adds them. +.. HINT:: + Then, if required, elaborate the testbench: :samp:`ghdl -e adder_tb`. You do not need to specify which object files are required, since GHDL knows them and automatically adds them. Now, it is time to run the testbench, :samp:`ghdl -r adder_tb`, and check the result on screen:: @@ -187,46 +185,34 @@ Unless you are only studying VHDL, you will work with larger designs than the on .. code-block:: shell - $ cd dlx - $ mkdir work + $ cd dlx + $ mkdir work -- Then, 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, :samp:`ghdl -i --workdir=work *.vhdl`. +* Then, 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, :samp:`ghdl -i --workdir=work *.vhdl`. -- GHDL knows all the design units of the DLX, but no one have been analyzed. Run the make option, :samp:`ghdl -m --workdir=work dlx_test_behaviour`, which analyzes and elaborates a design. This creates many files in the :file:`work/` directory, and (GCC/LLVM only) the :file:`dlx_test_behaviour` executable in the current directory. +* GHDL knows all the design units of the DLX, but no one have been analyzed. Run the make option, :samp:`ghdl -m --workdir=work dlx_test_behaviour`, which analyzes and elaborates a design. This creates many files in the :file:`work/` directory, and (GCC/LLVM only) the :file:`dlx_test_behaviour` executable in the current directory. .. HINT:: The simulation needs to have a DLX program contained in the file :file:`dlx.out`. This memory image will be loaded in the DLX memory. Just take one sample: :samp:`cp test_loop.out dlx.out`. -- Now, you can run the test suite: :samp:`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: +* Now, you can run the test suite: :samp:`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 - + dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction + encountered, execution halted -- Last, 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. To do so, call run with this option instead: :samp:`ghdl -r --workdir=work dlx_test_behaviour --assert-level=note``. With this option, the program stops just after the previous message: +* Last, 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. To do so, call run with this option instead: :samp:`ghdl -r --workdir=work dlx_test_behaviour --assert-level=note``. With this option, the program stops just after the previous message: .. code-block:: shell - dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction - encountered, execution halted - error: assertion failed + dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction + encountered, execution halted + error: assertion failed .. TIP:: If you want to make room on your hard drive, you can either: - * Clean the design library with the GHDL command :samp:`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 :samp:`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: :samp:`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. + * Clean the design library with the GHDL command :samp:`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 :samp:`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: :samp:`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. .. WARNING:: 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: :samp:`--ieee=synopsys -fexplicit`. See section ':ref:`IEEE_library_pitfalls`', for more details. - -Further examples -======================= - -.. TODO:: - - * Add references to examples/tutorials with GHDL. - * Shall `René Doß <https://mail.gna.org/public/ghdl-discuss/2017-01/msg00000.html>` want to contribute adapting his article to RST? - * https://github.com/Obijuan/open-fpga-verilog-tutorial/wiki
\ No newline at end of file diff --git a/doc/using/Simulation.rst b/doc/using/Simulation.rst index 5445bc830..5945588df 100644 --- a/doc/using/Simulation.rst +++ b/doc/using/Simulation.rst @@ -2,12 +2,12 @@ .. _USING:Simulation: Simulation and runtime -********************** +###################### .. _simulation_options: Simulation options -============ +================== In most system environments, it is possible to pass options while invoking a program. Contrary to most programming languages, there is no @@ -109,7 +109,7 @@ all options available, including the debugging one. .. _export_waves: Export waveforms -============ +================ .. option:: --read-opt-file<=FILENAME> @@ -231,7 +231,7 @@ Export waveforms - `Source code annotation is currently not available for VHDL, however all of GTKWave's other debug features are readily accessible. VHDL support is planned for a future release`. That's something that could be added in the future, but I have no plan for it. Export hierarchy and references -============ +=============================== .. option:: --disp-tree<[=KIND]> @@ -274,20 +274,21 @@ The set of :samp:`file` are analyzed, and then, if the analysis is successful, h Write a report for PSL at the end of simulation. For each PSL cover and assert statements, the name, source location and whether it passed or failed is reported. The file is written using the JSON format, but still being human readable. .. TODO:: - * Maybe worth adding a small example of how to generate a JSON file? + * Maybe worth adding a small example of how to generate a JSON file? .. option:: --file-to-xml Outputs an XML representation of the decorated syntax tree for the input file and its dependencies. It can be used for VHDL tooling using semantic information, like style checkers, documentation extraction, complexity estimation... .. WARNING:: - * The AST slightly changes from time to time (particularly when new nodes are added for new language features), so be liberal in what is allowed by your tool. Also, the XML can be quite large so consider it only during prototyping. - * Note that at this time there is no XML dump of the elaborated design. + * The AST slightly changes from time to time (particularly when new nodes are added for new language features), so be liberal in what is allowed by your tool. Also, the XML can be quite large so consider it only during prototyping. + * Note that at this time there is no XML dump of the elaborated design. + .. index:: debugging Debugging -============ +========= .. option:: --trace-signals @@ -338,7 +339,7 @@ Dump Run Time Information (RTI). Allow :samp:`--work=std` GNU Debugger (GDB) -------------------- +------------------ .. index:: `__ghdl_fatal` |