From 6871bbba1bdc4332cf68e1494e3c6f1615fefbcb Mon Sep 17 00:00:00 2001 From: 1138-4EB <1138-4EB@users.noreply.github.com> Date: Fri, 24 Feb 2017 19:00:45 +0100 Subject: Files in the root not capitalized. Second chapter ready for first review: Invoking reordered, some content moved to Command Reference, information compacted, command shortcuts added to titles. Known features which are missing in the doc added to TODOs or to Roadmap. Add export subsections to Using/Simulation Directory structure described in Building --- doc/About.rst | 53 --- doc/Contributing.rst | 95 ----- doc/Licenses.rst | 83 ---- doc/_static/theme_overrides.css | 8 +- doc/about.rst | 53 +++ doc/changelog/Roadmap.rst | 33 +- doc/contribute.rst | 95 +++++ doc/getting/Building.rst | 39 +- doc/getting/VendorPrimitives.md | 16 +- doc/licenses.rst | 83 ++++ doc/references/CommandReference.rst | 212 +++++++++ doc/using/InvokingGHDL.rst | 831 +++++++----------------------------- doc/using/QuickStartGuide.rst | 201 ++------- doc/using/Simulation.rst | 108 +++-- 14 files changed, 786 insertions(+), 1124 deletions(-) delete mode 100644 doc/About.rst delete mode 100644 doc/Contributing.rst delete mode 100644 doc/Licenses.rst create mode 100644 doc/about.rst create mode 100644 doc/contribute.rst create mode 100644 doc/licenses.rst (limited to 'doc') diff --git a/doc/About.rst b/doc/About.rst deleted file mode 100644 index 9b11ed5bf..000000000 --- a/doc/About.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. include:: shieldswho.txt - -About GHDL -############ - -.. _INTRO:VHDL: - -What is `VHDL`? -============== - -:wikipedia:`VHDL ` is an acronym for Very High Speed Integrated Circuit (:wikipedia:`VHSIC `) Hardware Description Language (:wikipedia:`HDL `), which is a programming language used to describe a logic circuit by function, data flow behavior, or structure. - -Although VHDL was not designed for writing general purpose programs, VHDL *is* a programming language, and you can write any algorithm with it. If you are able to write programs, you will find in VHDL features similar to those found in procedural languages such as `C`, `Python`, or `Ada`. Indeed, VHDL derives most of its syntax and semantics from Ada. Knowing `Ada` is an advantage for learning VHDL (it is an advantage in general as well). - -However, VHDL was not designed as a general purpose language but as an `HDL`. As the name implies, VHDL aims at modeling or documenting electronics systems. Due to the nature of hardware components which are always running, VHDL is a highly concurrent language, built upon an event-based timing model. - -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 `_ `1076`. Four revisions exist: `1987 `_, `1993 `_, `2002 `_ and `2008 `_. The standarization is handled by the VHDL Analysis and Standardization Group (`VASG/P1076 `_). - -.. _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). - -Unlike some other simulators, GHDL is a compiler: it directly translates a VHDL file to machine code, without using an intermediary language such as `C` or `C++`. Therefore, the compiled code should be faster and the analysis time should be shorter than with a compiler using an intermediary language. - -GHDL can use multiple back-ends, i.e. code generators, (`GCC `_, `LLVM `_ or :wikipedia:`x86 `/:wikipedia:`i386 ` only, a built-in one) and runs on :wikipedia:`GNU/Linux `, :wikipedia:`Windows ` |trade| and :wikipedia:`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 `_, :wikipedia:`VCD ` or `FST` files which can be viewed with a :wikipedia:`waveform viewer `, such as `GtkWave `_. - -GHDL aims at implementing VHDL as defined by `IEEE 1076 `_. It supports the `1987 `_, `1993 `_ and `2002 `_ revisions and, partially, the latest, `2008 `_. :wikipedia:`PSL ` is also partially supported. - -Several third party projects are supported: `VUnit `_, `OSVVM `_, `cocotb `_ (through the `VPI interface `_), ... - -.. _INTRO:WHO: - -Who uses GHDL? -============== - -.. container:: whouses - - +-------------------+--------------------+---------------------------------------------------+----------------------------------------------------------------+ - | Project hub | Documentation | Name | Brief description | - +===================+====================+===================================================+================================================================+ - | |SHIELD:gh-poc| | |SHIELD:rtd-poc| | `PoC-Library `_ | A Vendor-Independent, Open-Source IP Core and Utility Library. | - +-------------------+--------------------+---------------------------------------------------+----------------------------------------------------------------+ - | |SHIELD:gh-vunit| | |SHIELD:doc-vunit| | `VUnit `_ | A unit testing framework for VHDL/SystemVerilog | - +-------------------+--------------------+---------------------------------------------------+----------------------------------------------------------------+ - | |SHIELD:gl-p1076| | |SHIELD:tw-p1076| | `IEEE P1076 WG `_ | IEEE P1076 Working Group [VASG] | - +-------------------+--------------------+---------------------------------------------------+----------------------------------------------------------------+ diff --git a/doc/Contributing.rst b/doc/Contributing.rst deleted file mode 100644 index 36a3c0f38..000000000 --- a/doc/Contributing.rst +++ /dev/null @@ -1,95 +0,0 @@ -.. include:: shields.txt -.. _INTRO:Contributing: - -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 ` and :ref:`Implementation of VITAL ` 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 `. - -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| - -.. 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|. - - Therefore it is suggested to use the channels listed above instead of `gna.org/bugs/?=group=ghdl `_ or `sourceforge.net/p/ghdl-updates/tickets `_ . Still, these are checked from time to time. - -.. TIP:: - `How To Ask Questions The Smart Way `_ - -.. _reporting_bugs: - -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. - -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 `_) 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. - - - 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 `_. 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 `_ 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 `_, to polish it before opening an issue. If you don't have a `GitHub `_ user account, you can reach the developers through the `mailing-list `_ . - -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. - -Contibuting source code/documentation via `Git `_ 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 `_ . That is: - -1. Make a copy (`fork `_) of the project. -2. Do the changes you wish (edit, add, rename, move and/or delete). -3. When you think that the changes are ready to be merged, you notify the maintainers by opening a `Pull Request `_ (PR). -4. The maintainers will review the proposed changes and will reply in the corresponding thread if any further modification is required. If so, you can keep adding commits to the same branch, and the PR will be automatically updated. -5. Last, the maintainers will merge your branch. You will be notified, the PR will be closed, and you'll be allowed to delete the branch, if you want. - -.. TIP:: - * It is recommended to read `A successful Git branching model `_ for a reference on how maintainers expect to handle multiple branches. However, our actual model is not as exhaustive as explained there. - * Some commit messages can `automatically close `_ 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/Licenses.rst b/doc/Licenses.rst deleted file mode 100644 index a7e70d0c3..000000000 --- a/doc/Licenses.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. include:: shields.txt -.. include:: -.. _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`. - -.. WARNING:: - As a consequence of the runtime copyright, you are not allowed to distribute an executable produced by GHDL without the VHDL sources. To my mind, this is not a real restriction, since it is pointless to distribute VHDL executable. Please, send a comment (:ref:`requesting_enhancements`) if you don't like this policy. - -- The following packages are copyrighted by third parties (see corresponding sources for more information): - - - These from library :samp:`ieee` are copyrighted by `Institute of Electrical and Electronics Engineers (IEEE) `_ : - - - :samp:`numeric_bit` and :samp:`numeric_std`: the source files may be distributed without change, except as permitted by the standard; these may not be sold or distributed for profit. [see also `IEEE 1076.3 `_ ] - - :samp:`std_logic_1164`, :samp:`Math_Real` and :samp:`Math_Complex` - - :samp:`VITAL_Primitives`, :samp:`VITAL_Timing` and :samp:`VITAL_Memory` [see also `IEEE 1076.4 `_ ] - - - The following sources may be used and distributed without restriction, provided that the copyright statements are not removed from the files and that any derivative work contains the copyright notice. - - - :samp:`synopsys` directory: :samp:`std_logic_arith`, :samp:`std_logic_signed`, :samp:`std_logic_unsigned` and :samp:`std_logic_textio` are copyrighted by `Synopsys, Inc. `_ - - :samp:`mentor` directory: :samp:`std_logic_arith` is copyrighted by `Mentor Graphics `_ - -.. _LIC:GPLv2: - -GNU GPLv2 -============== - -GHDL is copyright |copy| 2002 - 2017 Tristan Gingold. - -This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. - -This program is distributed in the hope that it will be useful, but **WITHOUT ANY WARRANTY**; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the `GNU General Public License `_ for more details. - -.. _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 `_ 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: - -- **Attribution**: you must provide the name of the creator and attribution parties (`more info `_), a copyright notice, a license notice, a disclaimer notice, a link to the material, a link to the license and indicate if changes were made (see `marking guide `_ and `more info `_ ). You may do so in any reasonable manner, but not in any way that suggests we endorses you or your use. -- **ShareAlike**: if you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original. -- No additional restrictions: you may not apply legal terms or technological measures that legally restrict others from doing anything the license permits. - -See `CC-BY-SA-4.0 Legal Code `_ for more details. - -.. _LIC:contributors: - -List of Contributors -============== - -========================= ============================================================ -Contributor [#f1]_ Role -========================= ============================================================ -Baggett, Jonas signal selection -Bertram, Felix VPI interface -Davis, Brian Windows Mcode builds -Drummond, Brian GCC 4.8.2 update, OSVVM port, some bugfixes -Gingold, Tristan [#f2]_ **Sole author of GHDL as a whole** -Jensen, Adam FreeBSD builds -Koch, Markus vendor pre-compile script for Lattice (GNU/Linux) -Koontz, David Mac OSX builds, LRM compliance work, bugfix analyses -Lehmann, Patrick Windows compile scripts, vendor library pre-compile scripts (win+lin), building in MinGW, AppVeyor integration. -Martinez-Corral, Unai Docker builds, Travis-CI & Docker, adapt/fix STD theme -van Rantwijk, Joris Debian packaging -========================= ============================================================ - -Only those who made substantial contributions are shown in the table above, but many others contributed with minor patches. You can find a list at |SHIELD:contributors| - -With apologies to anyone who ought to be either on this table or in the GitHub contributor list, but isn't. Thanks also to all those who have reported bugs and support issues, and often patches and testcases to either `gna.org/bugs/?=group=ghdl `_ or `sourceforge.net/p/ghdl-updates/tickets `_ . - --------------------------------------------------------------------------------- - -.. container:: footnotes - - .. rubric:: Footnotes - - .. [#f1] In alphabetical order. - .. [#f2] Maintainer. diff --git a/doc/_static/theme_overrides.css b/doc/_static/theme_overrides.css index a1a61eae9..7f808783b 100644 --- a/doc/_static/theme_overrides.css +++ b/doc/_static/theme_overrides.css @@ -1,6 +1,6 @@ /* Change font sizes*/ html,body{font-size:98%;} -p{font-size:95%} +p{font-size:95%;margin-bottom:12px} .wy-breadcrumbs li.wy-breadcrumbs-aside{font-size:95%} .rst-versions{font-size:50%} .rst-versions .rst-current-version {font-size: 165%} @@ -62,4 +62,8 @@ div.wy-menu.rst-pro{display: none !important;max-width: 260px} /* Set text justification in paragraphs and list items to fully justified [borrowed from PoC-Library]*/ .section p {text-align:justify;} -.simple li {text-align:justify;} \ No newline at end of file +.simple li {text-align:justify;} + +/*Reduce margin below lists*/ +.rst-content .section ul, .rst-content .toctree-wrapper ul, article ul {margin-bottom: 12px} +.rst-content blockquote {margin-bottom: 12px;} \ No newline at end of file diff --git a/doc/about.rst b/doc/about.rst new file mode 100644 index 000000000..9b11ed5bf --- /dev/null +++ b/doc/about.rst @@ -0,0 +1,53 @@ +.. include:: shieldswho.txt + +About GHDL +############ + +.. _INTRO:VHDL: + +What is `VHDL`? +============== + +:wikipedia:`VHDL ` is an acronym for Very High Speed Integrated Circuit (:wikipedia:`VHSIC `) Hardware Description Language (:wikipedia:`HDL `), which is a programming language used to describe a logic circuit by function, data flow behavior, or structure. + +Although VHDL was not designed for writing general purpose programs, VHDL *is* a programming language, and you can write any algorithm with it. If you are able to write programs, you will find in VHDL features similar to those found in procedural languages such as `C`, `Python`, or `Ada`. Indeed, VHDL derives most of its syntax and semantics from Ada. Knowing `Ada` is an advantage for learning VHDL (it is an advantage in general as well). + +However, VHDL was not designed as a general purpose language but as an `HDL`. As the name implies, VHDL aims at modeling or documenting electronics systems. Due to the nature of hardware components which are always running, VHDL is a highly concurrent language, built upon an event-based timing model. + +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 `_ `1076`. Four revisions exist: `1987 `_, `1993 `_, `2002 `_ and `2008 `_. The standarization is handled by the VHDL Analysis and Standardization Group (`VASG/P1076 `_). + +.. _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). + +Unlike some other simulators, GHDL is a compiler: it directly translates a VHDL file to machine code, without using an intermediary language such as `C` or `C++`. Therefore, the compiled code should be faster and the analysis time should be shorter than with a compiler using an intermediary language. + +GHDL can use multiple back-ends, i.e. code generators, (`GCC `_, `LLVM `_ or :wikipedia:`x86 `/:wikipedia:`i386 ` only, a built-in one) and runs on :wikipedia:`GNU/Linux `, :wikipedia:`Windows ` |trade| and :wikipedia:`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 `_, :wikipedia:`VCD ` or `FST` files which can be viewed with a :wikipedia:`waveform viewer `, such as `GtkWave `_. + +GHDL aims at implementing VHDL as defined by `IEEE 1076 `_. It supports the `1987 `_, `1993 `_ and `2002 `_ revisions and, partially, the latest, `2008 `_. :wikipedia:`PSL ` is also partially supported. + +Several third party projects are supported: `VUnit `_, `OSVVM `_, `cocotb `_ (through the `VPI interface `_), ... + +.. _INTRO:WHO: + +Who uses GHDL? +============== + +.. container:: whouses + + +-------------------+--------------------+---------------------------------------------------+----------------------------------------------------------------+ + | Project hub | Documentation | Name | Brief description | + +===================+====================+===================================================+================================================================+ + | |SHIELD:gh-poc| | |SHIELD:rtd-poc| | `PoC-Library `_ | A Vendor-Independent, Open-Source IP Core and Utility Library. | + +-------------------+--------------------+---------------------------------------------------+----------------------------------------------------------------+ + | |SHIELD:gh-vunit| | |SHIELD:doc-vunit| | `VUnit `_ | A unit testing framework for VHDL/SystemVerilog | + +-------------------+--------------------+---------------------------------------------------+----------------------------------------------------------------+ + | |SHIELD:gl-p1076| | |SHIELD:tw-p1076| | `IEEE P1076 WG `_ | IEEE P1076 Working Group [VASG] | + +-------------------+--------------------+---------------------------------------------------+----------------------------------------------------------------+ diff --git a/doc/changelog/Roadmap.rst b/doc/changelog/Roadmap.rst index d5b3be9fb..5dfba58b1 100644 --- a/doc/changelog/Roadmap.rst +++ b/doc/changelog/Roadmap.rst @@ -13,9 +13,36 @@ I have several axes for `GHDL` improvements: * Style checks * VITAL acceleration -.. TODO:: +TODOs +================= - - Convert VendorPrimitives Markdown to RST - - SVG images are not shown in the PDF. That's because LaTeX is used. Can any package be added to allow so? +- RTD builds fail if EPUB is activated. +- Convert VendorPrimitives Markdown to RST +- SVG images are not shown in the PDF. That's because LaTeX is used. Can any package be added to allow so? + +Options shown in the command line help, but not found in the doc: + +* :samp:`--expect-failure invert exit status` +* :samp:`--has-feature=X test presence of feature X` +* :samp:`--list-features display the list of features` +* :samp:`--vpi=FILENAME load VPI module` +* :samp:`--vpi-trace[=FILE] trace vpi calls to FILE` +* :samp:`--dump-rti dump Run Time Information` +* :samp:`--trace-signals disp signals after each cycle` +* :samp:`--trace-processes disp process name before each cycle` +* :samp:`--stats display run-time statistics` +* :samp:`--disp-order disp signals order` +* :samp:`--disp-sources disp sources while displaying signals` +* :samp:`--disp-sig-types disp signal types` +* :samp:`--disp-signals-map disp map bw declared sigs and internal sigs` +* :samp:`--disp-signals-table disp internal signals` +* :samp:`--checks do internal checks after each process run` +* :samp:`--activity=LEVEL watch activity of LEVEL signals: LEVEL is all, min (default) or none (unsafe)` +* :samp:`-C --mb-comments allow multi-bytes chars in a comment` + + * https://github.com/tgingold/ghdl/issues/132 + +* :samp:`--bootstrap allow --work=std` +* :samp:`--syn-binding use synthesis default binding rule` .. todolist:: \ No newline at end of file diff --git a/doc/contribute.rst b/doc/contribute.rst new file mode 100644 index 000000000..36a3c0f38 --- /dev/null +++ b/doc/contribute.rst @@ -0,0 +1,95 @@ +.. include:: shields.txt +.. _INTRO:Contributing: + +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 ` and :ref:`Implementation of VITAL ` 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 `. + +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| + +.. 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|. + + Therefore it is suggested to use the channels listed above instead of `gna.org/bugs/?=group=ghdl `_ or `sourceforge.net/p/ghdl-updates/tickets `_ . Still, these are checked from time to time. + +.. TIP:: + `How To Ask Questions The Smart Way `_ + +.. _reporting_bugs: + +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. + +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 `_) 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. + + - 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 `_. 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 `_ 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 `_, to polish it before opening an issue. If you don't have a `GitHub `_ user account, you can reach the developers through the `mailing-list `_ . + +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. + +Contibuting source code/documentation via `Git `_ 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 `_ . That is: + +1. Make a copy (`fork `_) of the project. +2. Do the changes you wish (edit, add, rename, move and/or delete). +3. When you think that the changes are ready to be merged, you notify the maintainers by opening a `Pull Request `_ (PR). +4. The maintainers will review the proposed changes and will reply in the corresponding thread if any further modification is required. If so, you can keep adding commits to the same branch, and the PR will be automatically updated. +5. Last, the maintainers will merge your branch. You will be notified, the PR will be closed, and you'll be allowed to delete the branch, if you want. + +.. TIP:: + * It is recommended to read `A successful Git branching model `_ for a reference on how maintainers expect to handle multiple branches. However, our actual model is not as exhaustive as explained there. + * Some commit messages can `automatically close `_ 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/getting/Building.rst b/doc/getting/Building.rst index 68f086c56..9c357b476 100644 --- a/doc/getting/Building.rst +++ b/doc/getting/Building.rst @@ -20,11 +20,11 @@ GHDL currently supports three supported different backends (code generators): `m | | - Easier to build than GCC | | +------------------------+------------------------------------------------------------------------------------------+---------------------------------------------------------+ -.. HINT:: The output of both GCC and LLVM is an executable file, but `mcode` does not generate any. Therefore, if using GCC/LLVM, the call with argument :samp:`-r` can be replaced with direct execution of the binary. +.. HINT:: The output of both GCC and LLVM is an executable file, but `mcode` does not generate any. Therefore, if using GCC/LLVM, the call with argument :samp:`-r` can be replaced with direct execution of the binary. See section :ref:`USING:QuickStart`. After making your choice, you can jump to the corresponding section below. However, we suggest you to read :ref:`BUILD:dir_structure` before, so that you know where the content is placed and which temporal files are expected to be created. -.. HINT:: Since GHDL is written in `Ada`, independently of the code generator you use, the `GNU Ada compiler`, `GNAT GPL`, is required, 2014 (or later) for :samp:`x86` (32 or 64 bits). `GNAT GPL` can be downloaded anonymously from `libre.adacore.com `_ . Then, untar and run the doinstall script. Alternatively, most GNU/Linux provide a package named :samp:`gcc-ada` or :samp:`gcc-gnat`. +.. HINT:: Since GHDL is written in `Ada`, independently of the code generator you use, the `GNU Ada compiler`, `GNAT GPL`, is required, 2014 (or later) for :samp:`x86` (32 or 64 bits). `GNAT GPL` can be downloaded anonymously from `libre.adacore.com `_. Then, untar and run the doinstall script. Alternatively, most GNU/Linux provide a package named :samp:`gcc-ada` or :samp:`gcc-gnat`. .. TODO:: @@ -37,9 +37,41 @@ After making your choice, you can jump to the corresponding section below. Howev Directory structure ================= +* :samp:`src`: sources of GHDL, all of them in Ada. + +* :samp:`libraries`: mostly third party libraries such as, `ieee`, `mentor`, `std`, `synopsys` and `vital`. Except a few shell and `Python` scripts, all the content is written in VHDL. + + * Vendors like Altera, Lattice and Xilinx have their own simulation libraries, especially for FPGA primitives, soft and hard macros. These libraries can not be shipped with GHDL, but we offer prepared compile scripts to pre-compile the vendor libraries, if the vendor tool is present on the computer. These are located in :samp:`libraries/vendor`. See `Vendor Primitives `_ for information on how to use them. + +* :samp:`dist`: scripts and auxiliar files to build GHDL in different environments: + + * :samp:`gcc`: header and configuration files to build GHDL with GCC (all the platforms). + + * :samp:`linux`: build and test script written in shell, and other auxiliar files used to i) launch docker containers and ii) automate multiple builds in `Travis CI `_. + + * :samp:`windows`: + + * :samp:`mcode`: + + * :samp:`appveyor`: + +* :samp:`doc`: `Markdown` and `reStructuredText` sources and auxiliar files to build the documentation with `Sphinx `_. Indeed, `Read the docs `_ (RTD) is used to automatically build and deploy this site and/or PDF you are reading. + +* :samp:`testsuite`: see section :ref:`test_suites`. + +* `.yml` configuration files for CI environments (:samp:`readthedocs`, :samp:`travis` and :samp:`appveyor`) and `ignore` files for source control management tools (:samp:`git` and :samp:`.hg`). + +* Files for building GHDL: :samp:`configure` and :samp:`Makefile.in`. + +* Auxiliar files for development: :samp:`.gdbinit` and :samp:`ghdl.gpr.in` (GNAT project file). + +* Text files: :samp:`COPYING.md`, :samp:`NEWS.md` and :samp:`README.md`. + .. TODO:: - Directory structure of the main branch [1138: #279] + - [@1138-4EB|@Paebbels] Replace link to VendorPrimitives, when the file is translated from md to rst. + + - [@Paebbels] Add brief description of how the content in dist/windows is ordered. Mcode backend ================= @@ -157,6 +189,7 @@ Windows? Install file for the binary distribution of GHDL. The binary are installed in /usr/local directory. You cannot change this default location, unless you set links. You must be root to install this distribution. To install ghdl: `tar -C / -jxvf @TARFILE@.tar.bz2`. Note: you must also have a C compiler and zlib installed. +.. _test_suites: Test suites ================= diff --git a/doc/getting/VendorPrimitives.md b/doc/getting/VendorPrimitives.md index 3b9c9b11f..b25b4bb9a 100644 --- a/doc/getting/VendorPrimitives.md +++ b/doc/getting/VendorPrimitives.md @@ -1,16 +1,12 @@ ## Vendor Primitives -Vendors like Altera, Lattice and Xilinx have their own simulation libraries, especially for FPGA primitives, soft and hard macros. These libraries can not be shipped with *GHDL*, but we offer prepared compile scripts to pre-compile the vendor libraries, if the vendor tool is present on the computer. There are also popular simulation and verification libraries like [OSVVM][osvvm] and [VUnit][vunit], which can be pre-compiled, too. +Vendors like Altera, Lattice and Xilinx have their own simulation libraries, especially for FPGA primitives, soft and hard macros. These libraries can not be shipped with *GHDL*, but we offer prepared compile scripts to pre-compile the vendor libraries, if the vendor tool is present on the computer. There are also popular simulation and verification libraries like [OSVVM](http://osvvm.org) and [VUnit](https://github.com/LarsAsplund/vunit), which can be pre-compiled, too. -The compilation scripts are writen in the shell languages: *PowerShell* for *Windows* |trade| and *Bash* for *GNU/Linux*. The compile scripts can colorize the *GHDL* warning and error lines with the help of `grc/grcat` ([generic colourizer][grc]). - -- [osvvm]: http://osvvm.org/ -- [vunit]: https://github.com/LarsAsplund/vunit -- [grc]: http://kassiopeia.juls.savba.sk/~garabik/software/grc.html +The compilation scripts are writen in the shell languages: *PowerShell* for *Windows* |trade| and *Bash* for *GNU/Linux*. The compile scripts can colorize the *GHDL* warning and error lines with the help of `grc/grcat` ([generic colourizer](http://kassiopeia.juls.savba.sk/~garabik/software/grc.html)). ##### Supported Vendors Libraries - - Altera/Intel Quartus (≥13.0): + - Altera/Intel Quartus (13.0 or later): - `lpm`, `sgate` - `altera`, `altera_mf`, `altera_lnsim` - `arriaii`, `arriaii_pcie_hip`, `arriaiigz` @@ -21,19 +17,19 @@ The compilation scripts are writen in the shell languages: *PowerShell* for *Win - `stratixiv`, `stratixiv_pcie_hip` - `stratixv`, `stratixv_pcie_hip` - `fiftyfivenm`, `twentynm` - - Lattice (≥3.6): + - Lattice (3.6 or later): - `ec` - `ecp`, `ecp2`, `ecp3`, `ecp5u` - `lptm`, `lptm2` - `machxo`, `machxo2`, `machxo3l` - `sc`, `scm` - `xp`, `xp2` - - Xilinx ISE (≥14.0): + - Xilinx ISE (14.0 or later): - `unisim` (incl. `secureip`) - `unimacro` - `simprim` (incl. `secureip`) - `xilinxcorelib` - - Xilinx Vivado (≥2014.1): + - Xilinx Vivado (2014.1 or later): - `unisim` (incl. `secureip`) - `unimacro` diff --git a/doc/licenses.rst b/doc/licenses.rst new file mode 100644 index 000000000..078d43199 --- /dev/null +++ b/doc/licenses.rst @@ -0,0 +1,83 @@ +.. include:: shields.txt +.. include:: +.. _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`. + +.. WARNING:: + As a consequence of the runtime copyright, you are not allowed to distribute an executable produced by GHDL without the VHDL sources. To my mind, this is not a real restriction, since it is pointless to distribute VHDL executable. Please, send a comment (:ref:`requesting_enhancements`) if you don't like this policy. + +- The following packages are copyrighted by third parties (see corresponding sources for more information): + + - These from library :samp:`ieee` are copyrighted by `Institute of Electrical and Electronics Engineers (IEEE) `_ : + + - :samp:`numeric_bit` and :samp:`numeric_std`: the source files may be distributed without change, except as permitted by the standard; these may not be sold or distributed for profit. [see also `IEEE 1076.3 `_ ] + - :samp:`std_logic_1164`, :samp:`Math_Real` and :samp:`Math_Complex` + - :samp:`VITAL_Primitives`, :samp:`VITAL_Timing` and :samp:`VITAL_Memory` [see also `IEEE 1076.4 `_ ] + + - The following sources may be used and distributed without restriction, provided that the copyright statements are not removed from the files and that any derivative work contains the copyright notice. + + - :samp:`synopsys` directory: :samp:`std_logic_arith`, :samp:`std_logic_signed`, :samp:`std_logic_unsigned` and :samp:`std_logic_textio` are copyrighted by `Synopsys, Inc. `_ + - :samp:`mentor` directory: :samp:`std_logic_arith` is copyrighted by `Mentor Graphics `_ + +.. _LIC:GPLv2: + +GNU GPLv2 +============== + +GHDL is copyright |copy| 2002 - 2017 Tristan Gingold. + +This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, but **WITHOUT ANY WARRANTY**; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the `GNU General Public License `_ for more details. + +.. _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 `_ 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: + +- **Attribution**: you must provide the name of the creator and attribution parties (`more info `_), a copyright notice, a license notice, a disclaimer notice, a link to the material, a link to the license and indicate if changes were made (see `marking guide `_ and `more info `_ ). You may do so in any reasonable manner, but not in any way that suggests we endorses you or your use. +- **ShareAlike**: if you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original. +- No additional restrictions: you may not apply legal terms or technological measures that legally restrict others from doing anything the license permits. + +See `CC-BY-SA-4.0 Legal Code `_ for more details. + +.. _LIC:contributors: + +List of Contributors +============== + +========================= ============================================================ +Contributor [#f1]_ Role +========================= ============================================================ +Baggett, Jonas signal selection +Bertram, Felix VPI interface +Davis, Brian Windows Mcode builds +Drummond, Brian GCC 4.8.2 update, OSVVM port, some bugfixes +Gingold, Tristan [#f2]_ **Sole author of GHDL as a whole** +Jensen, Adam FreeBSD builds +Koch, Markus vendor pre-compile script for Lattice (GNU/Linux) +Koontz, David Mac OSX builds, LRM compliance work, bugfix analyses +Lehmann, Patrick Windows compile scripts, vendor library pre-compile scripts (win+lin), building in MinGW, AppVeyor integration. +Martinez-Corral, Unai Docker builds, Travis-CI & Docker, adapt/fix RTD theme +van Rantwijk, Joris Debian packaging +========================= ============================================================ + +Only those who made substantial contributions are shown in the table above, but many others contributed with minor patches. You can find a list at |SHIELD:contributors| + +With apologies to anyone who ought to be either on this table or in the GitHub contributor list, but isn't. Thanks also to all those who have reported bugs and support issues, and often patches and testcases to either `gna.org/bugs/?=group=ghdl `_ or `sourceforge.net/p/ghdl-updates/tickets `_ . + +-------------------------------------------------------------------------------- + +.. container:: footnotes + + .. rubric:: Footnotes + + .. [#f1] In alphabetical order. + .. [#f2] Maintainer. diff --git a/doc/references/CommandReference.rst b/doc/references/CommandReference.rst index ed7869dba..771d2386e 100644 --- a/doc/references/CommandReference.rst +++ b/doc/references/CommandReference.rst @@ -3,4 +3,216 @@ Command Reference ################# +.. HINT:: The most common commands and options are shown in section :ref:`USING:Invoking`. Here the advanced and experimental features are described. +Misc commands +============= + +There are a few GHDL commands which are seldom useful. + +.. _Help_command: + +Help [:samp:`-h`] +------------ + +.. index:: -h command + +.. index:: --help command + +Display (on the standard output) a short description of the all the commands +available. If the help switch is followed by a command switch, then options +for this later command are displayed:: + + ghdl --help + ghdl -h + ghdl -h command + + +.. _Disp_config_command: + +Display config [:samp:`--disp-config`] +------------------- + +.. index:: --disp-config command + +.. index:: display configuration + +:samp:`ghdl --disp-config [options]` + +Display the program paths and options used by GHDL. This may be useful to track installation errors. + +Display standard [:samp:`--disp-standard`] +--------------------- + +.. index:: --disp-standard command + +.. index:: display :samp:`std.standard` + +:samp:`ghdl --disp-standard [options]` + +Display the :samp:`std.standard` package. + +Version [:samp:`--version`] +--------------- + +.. index:: --version command + +.. index:: version + +:samp:`ghdl --version` + +Display the `GHDL` version and exit. + +File commands +============= + +The following commands act on one or several files. These are not analyzed, therefore, they work even if a file has semantic errors. + +Pretty print [:samp:`--pp-html`] +-------------------- + +.. index:: --pp-html command + +.. index:: pretty printing + +.. index:: vhdl to html + +:samp:`ghdl --pp-html [options] file...` + +The files are just scanned and an html file, with syntax highlighting is generated on standard output. Since the files are not even parsed, erroneous files or incomplete designs can be pretty printed. + +The style of the html file can be modified with the :option:`--format=` option: + +* By default or when the :option:`--format=html2` option is specified, the output is an HTML 2.0 file, with colours set through `` tags. +* When the :option:`--format=css` option is specified, the output is an HTML 4.0 file, with colours set through a CSS file, whose name is :file:`ghdl.css`. See :ref:`Cross-reference_command`, for more details about this CSS file. + +Find [:samp:`-f`] +------------ + +.. index:: -f command + +:samp:`ghdl -f file...` + +The files are scanned, parsed and the names of design units are displayed. Design units marked with two stars are candidate to be at the apex of a design hierarchy. + +Chop [:samp:`--chop`] +------------ + +.. index:: --chop command + +:samp:`ghdl --chop files` + +The provided files are read, and a file is written in the current directory for every design unit. Each filename is build according to the type: + +* For an entity declaration, a package declaration or a configuration the file name is :file:`NAME.vhdl`, where `NAME` is the name of the design unit. +* For a package body, the filename is :file:`NAME-body.vhdl`. +* Finally, for an architecture `ARCH` of an entity `ENTITY`, the filename is :file:`ENTITY-ARCH.vhdl`. + +Since the input files are parsed, this command aborts in case of syntax error. The command aborts too if a file to be written already exists. + +Comments between design units are stored into the most adequate files. + +This command may be useful to split big files, if your computer has not enough memory to compile such files. The size of the executable is reduced too. + +Lines [:samp:`--lines`] +------------- + +.. index:: --lines command + +:samp:`ghdl --lines files` + +Display on the standard output lines of files preceded by line number. + +GCC/LLVM only commands +================= + +.. _Bind_command: + +Bind [:samp:`--bind`] +------------ + +.. index:: binding + +.. index:: --bind command + +:samp:`ghdl --bind [options] primary_unit [secondary_unit]` + +Performs only the first stage of the elaboration command; the list of objects files is created but the executable is not built. This command should be used only when the main entry point is not GHDL. + +.. _Link_command: + +Link [:samp:`--link`] +------------ + +.. index:: linking + +.. index:: --link command + +:samp:`ghdl --link [options] primary_unit [secondary_unit]` + +Performs only the second stage of the elaboration command: the executable is created by linking the files of the object files list. This command is available only for completeness. The elaboration command is equivalent to the bind command followed by the link command. + +.. _List_link_command: + +List link [:samp:`--list-link`] +----------------- + +.. index:: --list-link command + +:samp:`ghdl --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. + +GHDL options +================= + +.. option:: --syn-binding + + Use synthesizer rules for component binding. During elaboration, if a + component is not bound to an entity using VHDL LRM rules, try to find + in any known library an entity whose name is the same as the component + name. + + This rule is known as synthesizer rule. + + There are two key points: normal VHDL LRM rules are tried first and + entities are searched only in known library. A known library is a + library which has been named in your design. + + This option is only useful during elaboration. + +.. option:: --GHDL1= + + Use :samp:`COMMAND` as the command name for the compiler. If :samp:`COMMAND` is + not a path, then it is searched in the path. + +.. option:: --AS= + + Use :samp:`COMMAND` as the command name for the assembler. If :samp:`COMMAND` is + not a path, then it is searched in the path. The default is :samp:`as`. + +.. option:: --LINK= + + Use :samp:`COMMAND` as the linker driver. If :samp:`COMMAND` is + not a path, then it is searched in the path. The default is :samp:`gcc`. + +Passing options to other programs +================================= + +.. WARNING:: These options are only available with GCC/LLVM. + +For many commands, GHDL acts as a driver: it invokes programs to perform the command. You can pass arbitrary options to these programs. + +Both the compiler and the linker are in fact GCC programs. See the GCC manual for details on GCC options. + +.. option:: -Wc,