diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/About.rst | 53 | ||||
| -rw-r--r-- | doc/Contributing.rst | 95 | ||||
| -rw-r--r-- | doc/Licenses.rst | 83 | ||||
| -rw-r--r-- | doc/_static/theme_overrides.css | 65 | ||||
| -rw-r--r-- | doc/building/index.rst | 178 | ||||
| -rw-r--r-- | doc/changelog/Roadmap.rst | 4 | ||||
| -rw-r--r-- | doc/conf.py | 15 | ||||
| -rw-r--r-- | doc/getting/Building.rst | 166 | ||||
| -rw-r--r-- | doc/getting/VendorPrimitives.md (renamed from doc/building/VendorPrimitives.md) | 84 | ||||
| -rw-r--r-- | doc/index.rst | 14 | ||||
| -rw-r--r-- | doc/intro/Contributing.rst | 97 | ||||
| -rw-r--r-- | doc/intro/Copyrights.rst | 73 | ||||
| -rw-r--r-- | doc/intro/WhatIsGHDL.rst | 18 | ||||
| -rw-r--r-- | doc/intro/WhatIsVHDL.rst | 14 | ||||
| -rw-r--r-- | doc/shields.txt | 21 | ||||
| -rw-r--r-- | doc/shieldswho.txt | 27 | ||||
| -rw-r--r-- | doc/using/QuickStartGuide.rst | 43 |
17 files changed, 563 insertions, 487 deletions
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 <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. + +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 <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/>`_). + +.. _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 <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/>`_. + +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? +============== + +.. 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] | + +-------------------+--------------------+---------------------------------------------------+----------------------------------------------------------------+ diff --git a/doc/Contributing.rst b/doc/Contributing.rst new file mode 100644 index 000000000..36a3c0f38 --- /dev/null +++ b/doc/Contributing.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 <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| + +.. 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 <https://gna.org/bugs/?group=ghdl>`_ or `sourceforge.net/p/ghdl-updates/tickets <https://sourceforge.net/p/ghdl-updates/tickets/>`_ . Still, these are checked from time to time. + +.. TIP:: + `How To Ask Questions The Smart Way <www.catb.org/~esr/faqs/smart-questions.html>`_ + +.. _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 <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. + + - 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. + +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: + +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). +3. When you think that the changes are ready to be merged, you notify the maintainers by opening a `Pull Request <https://help.github.com/articles/creating-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 <http://nvie.com/posts/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 <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/Licenses.rst b/doc/Licenses.rst new file mode 100644 index 000000000..a7e70d0c3 --- /dev/null +++ b/doc/Licenses.rst @@ -0,0 +1,83 @@ +.. include:: shields.txt +.. include:: <isonum.txt> +.. _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) <https://www.ieee.org>`_ : + + - :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 <http://ieeexplore.ieee.org/document/592543/>`_ ] + - :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 <http://ieeexplore.ieee.org/document/954750/>`_ ] + + - 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. <https://www.synopsys.com/>`_ + - :samp:`mentor` directory: :samp:`std_logic_arith` is copyrighted by `Mentor Graphics <https://www.mentor.com>`_ + +.. _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 <https://www.gnu.org/licenses/old-licenses/gpl-2.0.html>`_ 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 <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: + +- **Attribution**: you must provide the name of the creator and attribution parties (`more info <https://wiki.creativecommons.org/wiki/License_Versions#Detailed_attribution_comparison_chart>`_), 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 <https://wiki.creativecommons.org/wiki/Best_practices_for_attribution#This_is_a_good_attribution_for_material_you_modified_slightly>`_ and `more info <https://wiki.creativecommons.org/wiki/License_Versions#Modifications_and_adaptations_must_be_marked_as_such>`_ ). 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 <https://creativecommons.org/licenses/by-sa/4.0/legalcode.txt>`_ 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 <https://gna.org/bugs/?group=ghdl>`_ or `sourceforge.net/p/ghdl-updates/tickets <https://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 new file mode 100644 index 000000000..cb4555384 --- /dev/null +++ b/doc/_static/theme_overrides.css @@ -0,0 +1,65 @@ +/* Change font sizes*/ +html,body{font-size:98%;} +p{font-size:95%} +.wy-breadcrumbs li.wy-breadcrumbs-aside{font-size:95%} +.rst-versions{font-size:50%} +.rst-versions .rst-current-version {font-size: 165%} +.rst-versions dd{font-size:175%} +footer {font-size: 75%;} +.rst-footer-buttons {font-size: 140%;} + +/*Header and footer margins*/ +footer p {margin-bottom: 0px} +footer hr {margin-bottom: 10px} +[role=navigation] hr {margin-top: 5px} + +/*Do not center main content and allow wider display*/ +.wy-nav-content{margin: auto; max-width: 1020px} + +/*Shrink left nav to 260px*/ +.wy-nav-side,.rst-versions,.wy-side-nav-search,.wy-menu-vertical{width: 260px} +.wy-nav-content-wrap{margin-left:260px;background:#fcfcfc;min-height:100%} +@media screen and (max-width: 768px){ + .wy-nav-top i {padding-top:7px} + .wy-nav-content-wrap{margin-left:0px} + .wy-nav-content-wrap.shift{margin-left:265px;position: static;} + .wy-nav-side.shift{width:265px;padding-bottom: 40px;} + .rst-versions{width:265px} + .wy-side-scroll{width:260px;} +} + +/*Fix shields in small screens*/ +@media screen and (max-width: 768px){img{width: auto}} +/*Fix shield sizes in WhoUsesGHDL*/ +.whouses>.wy-table-responsive img {width:auto;height:20px !important;;display:inline} +.whouses>.wy-table-responsive td {text-align:center} +.whouses>.wy-table-responsive>table>thead th{min-width:130px !important} +.whouses>.wy-table-responsive td:last-child{text-align: left} + +/*Remove 1 indentation space in the sidemenu items*/ +.wy-menu-vertical li.current a, .wy-menu-vertical li.toctree-l2.current > a{padding:0.4045em 1.618em} +.wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a{padding: 0.4045em 1.8em} + +/*Remove empty add*/ +div.wy-menu.rst-pro{display: none !important;max-width: 260px} + +/*Simplify 'versions' tab*/ +.rst-versions dt{display:none} +.rst-versions dd a[href$='.rst'] {display: none} +.rst-versions dd a[href$='/downloads/'] {display: none} +.rst-versions .wy-form{display:none !important;} +.rst-versions .rst-other-versions dd a{padding: 3px} +.rst-versions .rst-other-versions strong dd a{color: #27AE60} +.rst-versions .rst-other-versions hr{margin: 5px 0; margin-top: -14px} + +.rst-versions {border-top: none} + +/*Last doc build date*/ +.lastdocbuilddate {position:fixed;padding-top:30px;font-size:70%;color:#999} + +/*Reduce space between footnotes*/ +.footnotes > .wy-table-responsive {margin-top:-12px;margin-bottom:12px} + +/* 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 diff --git a/doc/building/index.rst b/doc/building/index.rst deleted file mode 100644 index 9cdc812f9..000000000 --- a/doc/building/index.rst +++ /dev/null @@ -1,178 +0,0 @@ -.. _BUILD: - -Building GHDL -############# - -GHDL currently supports three supported different backends (code generators): mcode, GCC and LLVM. Here is a short comparison, so that you can choose the one you want to use: - -* mcode (an internal code generator) -+ very easy to build -- but x86_64/i386 only -+ very quick analysis time -+ can analyze very big designs -- simulation is slower -- no executable created - -* GCC -+ generated code is faster (particularly with -O or -O2) -+ generated code can be debugged (with -g) -+ the output is an executable -+ ported to many platforms (x86, x86_64, powerpc, sparc) -- analyze can takes time (particularly for big units) -- build is more complex - -* LLVM -+ same advantages of gcc (good generated code, debuggable) -+ easier to build than gcc - -As GHDL is written in Ada, you need to use the GNU Ada compiler (GNAT). I recommend to use GNAT GPL from http://libre.adacore.com (free). GHDL was tested with GNAT GPL 2014. Any later version should work. -The only other dependency is zlib (On ubuntu/debian, install zlib1g-dev). - -.. TODO:: - - - `./doc/oldmds/BUILD.txt <https://github.com/tgingold/ghdl/blob/master/doc/oldmds/BUILD.txt>`_ - - Directory structure of the main branch [1138: #279] - - Coverage, `gcov`, is unique to gcc. That specific difference is not explained anywhere. Should be added. - - @1138 Backtraces optional -patchable- - - Very briefly, why is mode faster for analysis and GCC/LLVM for simulation? - -Mcode backend -================= - -- Linux - -This is as simple as: - -$ ./configure --prefix=PREFIX - - where PREFIX is the directory for installation - -$ make - - This builds the ghdl_mcode executable, which can be used as is. - -$ make install - - To install within PREFIX - -- Windows MinGW 32/64 -- Windows GNAT GPL (32 only) - -.. TODO:: - - Note: this was tested with Windows XP SP2 familly edition. - - Note: If you want to create the installer, GHDL should be built on a FAT partition. NSIS rounds files date to be FAT compliant (seconds are always even) and because GHDL stores dates, the files date must not be modified. - - The Ada95 GNAT compiler (GNAT GPL 2005 is known to work), along with NSIS to create the installer. Then unzip, edit winbuild to use correct path for makensis, and run winbuild. The installer is in the windows directory. - -LLVM backend -================= - -- Linux - -You need to build and install llvm. The supported versions are 3.5 -till 3.9, but only debugging is only supported with llvm 3.5 -(Usually llvm also depends on libedit). - -First configure ghdl with '--with-llvm-config' -$ ./configure --with-llvm-config - -If llvm-config is not in your path, you can specify it: -$ ./configure --with-llvm-config=LLVM_INSTALL/bin/llvm-config - -If you want to have stack backtraces on errors (like assert failure or -index of out bounds), you need to configure and build libbacktrace from gcc -(you don't need to configure gcc), and add to configure: - --with-backtrace-lib=/path-to-gcc-build/libbacktrace/.libs/libbacktrace.a - -Then build with 'make' and install with 'make install'. - -- Mac OS? -- Windows MinGW 32/64 - -GCC backend -================= - -- Linux - -You need to download and untar the sources of -gcc version 4.9 [do not modify this line as this is read by scripts]. - -First configure ghdl, specify gcc source dir and prefix. -(replace /usr/local by your prefix directory): -$ ./configure --with-gcc=/path/to/gcc/source/dir --prefix=/usr/local - -Then invoke make to copy ghdl sources in the source dir: -$ make copy-sources - -There are some dependencies for building gcc (gmp, mpfr and mpc). If you have -not them installed on your system, you can either build them manually or use -the 'download_prerequisite' script provided in gcc source tree (recommended). - -$ cd /path/to/gcc/source/dir -$ ./contrib/download_prerequisites - -Then configure gcc. The list of --disable configure options could be -adjusted for your needs. GHDL don't require all these optional -libraries and disabling them speed-up the build. Note the prefix -directory must be the same as the one used to configure ghdl. -If you have manually built gmp/mpfr/mpc (without using the script -in contrib) and if you have installed them in a non-standard -directory, you may need to add --with-gmp=GMP_INSTALL_DIR. - -$ mkdir gcc-objs; cd gcc-objs -$ ../gcc-4.9.3/configure --prefix=/usr/local --enable-languages=c,vhdl \ - --disable-bootstrap --disable-lto --disable-multilib \ - --disable-libssp --disable-libgomp --disable-libquadmath -$ make -j2 - -Install gcc: -$ make install -or if you don't want to install makeinfo: -$ make install MAKEINFO=true - -Build and install vhdl libraries: -$ cd /path/to/ghdl/source/dir -$ make ghdllib -$ make install - -- Windows? - -.. TODO: - - Since the content of BUILD.txt is moved to the docs, what shall we do with this line? +gcc version 6.3 [do not modify this line as this is read by scripts]. - - Note for ppc64 (and AIX ?) platform: the object file format contains an identifier for the source language. Because gcc doesn't know about the VHDL, gcc crashes very early. This could be fixed with a very simple change in gcc/config/rs6000/rs6000.c, function rs6000_output_function_epilogue (as of gcc 4.8): - else if (! strcmp (language_string, "GNU Objective-C")) - i = 14; - else -- gcc_unreachable (); -+ i = 0; - fprintf (file, "%d,", i); - - /* 8 single bit fields: global linkage (not set for C extern linkage, - - 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. - -- Notes for developpers - -Developping with the gcc backend: -Once gcc (with ghdl) has been built once, it is possible to work on ghdl -sources tree without copying them in gcc tree. Commands are: -$ make ghdl1-gcc # To build the compiler -$ make ghdl_gcc # To build the driver -$ make libs.vhdl.local_gcc # To compile the vhdl libraries -$ make grt-all # To build the ghdl runtime -$ make grt.links # To locally install the ghdl runtime - -.. TODO:: - - gcc object dir - -Test suites -================= - -.. TODO:: - - @1138 explain that there are two (maybe three with vhdl08 tests)
\ No newline at end of file diff --git a/doc/changelog/Roadmap.rst b/doc/changelog/Roadmap.rst index 57998ce58..6138e8ea9 100644 --- a/doc/changelog/Roadmap.rst +++ b/doc/changelog/Roadmap.rst @@ -13,4 +13,8 @@ I have several axes for `GHDL` improvements: * Style checks * VITAL acceleration +.. TODO:: + + - Convert VendorPrimitives Markdown to RST + .. todolist::
\ No newline at end of file diff --git a/doc/conf.py b/doc/conf.py index 2d431acfe..7a6ff7219 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -150,10 +150,10 @@ todo_link_only = True # reST settings rst_prolog = """\ +.. include:: <isonum.txt> .. |br| raw:: html <br /> - """ # -- Options for HTML output ---------------------------------------------- @@ -161,7 +161,15 @@ rst_prolog = """\ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. #html_theme = 'alabaster' -html_theme = "sphinx_rtd_theme" +#html_theme = "sphinx_rtd_theme" +# Override default css to get a larger width for ReadTheDoc build +html_context = { + 'css_files': [ + 'https://media.readthedocs.org/css/sphinx_rtd_theme.css', + 'https://media.readthedocs.org/css/readthedocs-doc-embed.css', + '_static/theme_overrides.css', + ], +} # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -350,5 +358,6 @@ intersphinx_mapping = { extlinks = { 'ghdlissue': ('https://github.com/tgingold/ghdl/issues/%s', 'issue #'), 'ghdlpull': ('https://github.com/tgingold/ghdl/pull/%s', 'pull request #'), - 'ghdlsrc': ('https://github.com/tgingold/ghdl/blob/master/src/%s', None) + 'ghdlsrc': ('https://github.com/tgingold/ghdl/blob/master/src/%s', None), + 'wikipedia': ('https://en.wikipedia.org/wiki/%s', None) } diff --git a/doc/getting/Building.rst b/doc/getting/Building.rst new file mode 100644 index 000000000..c52d3f5da --- /dev/null +++ b/doc/getting/Building.rst @@ -0,0 +1,166 @@ +.. _BUILD: + +Building GHDL +############# + +GHDL currently supports three supported different backends (code generators): `mcode` (built-in), `GCC <http://gcc.gnu.org/>`_ and `LLVM <http://llvm.org/>`_ . Here is a short comparison, so that you can choose the one you want to use: + ++------------------------+------------------------------------------------------------------------------------------+---------------------------------------------------------+ +| | pros | cons | ++========================+==========================================================================================+=========================================================+ +| `mcode` | - very easy to build | - :samp:`x86_64`/:samp:`i386` only | +| | - very quick analysis | - simulation is slower | +| | - can handle very large designs | | ++------------------------+------------------------------------------------------------------------------------------+---------------------------------------------------------+ +| `GCC` | - generated code is faster (particularly with :samp:`-O` or :samp:`-O2`) | - analysis can take time (particularly for large units) | +| | - generated code can be debugged (with :samp:`-g`) | - build is more complex | +| | - ported to many platforms (:samp:`x86`, :samp:`x86_64`, :samp:`powerpc`, :samp:`sparc`) | | ++------------------------+------------------------------------------------------------------------------------------+---------------------------------------------------------+ +| `LLVM` | - Same as `GCC` | Coverage, :samp:`gcov`, is unique to `GCC` | +| | - 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. + +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 <http://libre.adacore.com/tools/gnat-gpl-edition/>`_ . Then, untar and run the doinstall script. Alternatively, most GNU/Linux provide a package named :samp:`gcc-ada` or :samp:`gcc-gnat`. + +.. TODO:: + + - @1138 Backtraces optional -patchable- + - Very briefly, why is mcode faster for analysis and GCC/LLVM for simulation? + - The only other dependency is zlib (On ubuntu/debian, install zlib1g-dev). + +.. _BUILD:dir_structure: + +Directory structure +================= + +.. TODO:: + + Directory structure of the main branch [1138: #279] + +Mcode backend +================= + +This is the most simple procedure, because it requires the least dependencies and configuration options. + +GNU/Linux +---------------- + +- First, execute :samp:`./configure --prefix=PREFIX`, where :samp:`PREFIX` is the directory for installation. +- Then :samp:`make`, that builds the :samp:`ghdl_mcode` executable, which can be used as is. +- Last, :samp:`make install` to install within :samp:`PREFIX`. +- That's all! + +Windows MinGW 32/64 +---------------- + +.. TODO:: For example, on Windows, you may want to set it to :samp:`--prefix=/c/Program Files (x86)/GHDL` . + +Windows GNAT GPL (32 only) +---------------- + +.. TODO:: + Note: this was tested with Windows XP SP2 familly edition. + Note: If you want to create the installer, GHDL should be built on a FAT partition. NSIS rounds files date to be FAT compliant (seconds are always even) and because GHDL stores dates, the files date must not be modified. + The Ada95 GNAT compiler (GNAT GPL 2005 is known to work), along with NSIS to create the installer. Then unzip, edit winbuild to use correct path for makensis, and run winbuild. The installer is in the windows directory. + +LLVM backend +================= + +GNU/Linux +---------------- + +You need to install `LLVM` (usually depends on :samp:`libedit`). The supported versions are 3.5 till 3.9, but debugging is only supported with `LLVM` 3.5. + +- First configure GHDL with the proper arg :samp:`./configure --with-llvm-config`. If :samp:`llvm-config` is not in your path, you can specify it: :samp:`./configure --with-llvm-config=LLVM_INSTALL/bin/llvm-config`. + +.. HINT:: If you want to have stack backtraces on errors (like assert failure or index of out bounds), you need to configure and build :samp:`libbacktrace` from `GCC` (you don't need to configure `GCC`). Then add the following arg to configure: :samp:`--with-backtrace-lib=/path-to-gcc-build/libbacktrace/.libs/libbacktrace.a` + +- Then build with :samp:`make` and install with :samp:`make install`. + +Mac OS? +---------------- + +Windows MinGW 32/64 +---------------- + +GCC backend +================= + +.. TODO:: + + - You need to download and untar the sources of `GCC` version 4.9 [do not modify this line as this is read by scripts]. + - gcc object dir + - Notes for developpers developping with the GCC backend: once `GCC` (with GHDL) has been built once, it is possible to work on the GHDL source tree without copying it in the `GCC` tree. Commands are:: + + $ make ghdl1-gcc # Build the compiler + $ make ghdl_gcc # Build the driver + $ make libs.vhdl.local_gcc # Compile the vhdl libraries + $ make grt-all # Build the GHDL runtime + $ make grt.links # Locally install the GHDL runtime + +GNU/Linux +---------------- + +- First configure GHDL, specify `GCC` source dir and :samp:`prefix` (replace :samp:`/usr/local` with your desired installation directory):: + + ./configure --with-gcc=/path/to/gcc/source/dir --prefix=/usr/local + +- Then, invoke :samp:`make` to copy GHDL sources in the source dir:: + + make copy-sources + +.. HINT:: There are some dependencies for building `GCC` (:samp:`gmp`, :samp:`mpfr` and :samp:`mpc`). If you have not them installed on your system, you can either build them manually or use the :samp:`download_prerequisite` script provided in the `GCC` source tree (recommended): :samp:`cd /path/to/gcc/source/dir && ./contrib/download_prerequisites` + +- Then, configure `GCC`. The list of :samp:`--disable` configure options can be adjusted to your needs. GHDL does not require all these optional libraries and disabling them will speed-up the build:: + + ../gcc-4.9.3/configure --prefix=/usr/local --enable-languages=c,vhdl \ + --disable-bootstrap --disable-lto --disable-multilib --disable-libssp \ + --disable-libgomp --disable-libquadmath ``. + +.. HINT:: Note that the prefix directory must be the same as the one used to configure GHDL. If you have manually built :samp:`gmp`/:samp:`mpfr`/:samp:`mpc` (without using the script in :samp:`contrib`) and if you have installed them in a non-standard directory, you may need to add :samp:`--with-gmp=GMP_INSTALL_DIR`. + +- Then, build and install `GCC`:: + + make -j2 && make install + +.. HINT:: If you don't want to install :samp:`makeinfo`, do :samp:`make install MAKEINFO=false` instead. + +- Last, build and install GHDL libraries:: + + cd /path/to/ghdl/source/dir + make ghdllib + make install + +Windows? +---------------- + +.. TODO: + + Since the content of BUILD.txt is moved to the docs, what shall we do with this line? +gcc version 6.3 [do not modify this line as this is read by scripts]. + + Note for ppc64 (and AIX ?) platform: the object file format contains an identifier for the source language. Because gcc doesn't know about the VHDL, gcc crashes very early. This could be fixed with a very simple change in gcc/config/rs6000/rs6000.c, function rs6000_output_function_epilogue (as of gcc 4.8): + + .. CODE:: C + + else if (! strcmp (language_string, "GNU Objective-C")) + i = 14; + else + - gcc_unreachable (); + + i = 0; + fprintf (file, "%d,", i); + + /* 8 single bit fields: global linkage (not set for C extern linkage, + + 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 +================= + +.. TODO:: + + @1138 explain that there are two (maybe three with vhdl08 tests)
\ No newline at end of file diff --git a/doc/building/VendorPrimitives.md b/doc/getting/VendorPrimitives.md index b608c0825..3b9c9b11f 100644 --- a/doc/building/VendorPrimitives.md +++ b/doc/getting/VendorPrimitives.md @@ -1,54 +1,41 @@ -.. _VENDOR: +## Vendor Primitives -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. -## Compile Scripts for Vendor VHDL Libraries +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]). -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-compile, too. - -The compilation scripts are writen in the shell languages: PowerShell for Windows -and Bash for 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 +- [osvvm]: http://osvvm.org/ +- [vunit]: https://github.com/LarsAsplund/vunit +- [grc]: http://kassiopeia.juls.savba.sk/~garabik/software/grc.html ##### Supported Vendors Libraries - - Altera Quartus (≥13.0): - - lpm, sgate - - altera, altera_mf, altera_lnsim - - arriaii, arriaii_pcie_hip, arriaiigz - - arriav, arriavgz, arriavgz_pcie_hip - - cycloneiv, cycloneiv_pcie_hip, cycloneive - - cyclonev - - max, maxii, maxv - - stratixiv, stratixiv_pcie_hip - - stratixv, stratixv_pcie_hip - - fiftyfivenm, twentynm + - Altera/Intel Quartus (≥13.0): + - `lpm`, `sgate` + - `altera`, `altera_mf`, `altera_lnsim` + - `arriaii`, `arriaii_pcie_hip`, `arriaiigz` + - `arriav`, `arriavgz`, `arriavgz_pcie_hip` + - `cycloneiv`, `cycloneiv_pcie_hip`, `cycloneive` + - `cyclonev` + - `max`, `maxii`, `maxv` + - `stratixiv`, `stratixiv_pcie_hip` + - `stratixv`, `stratixv_pcie_hip` + - `fiftyfivenm`, `twentynm` - Lattice (≥3.6): - - ec - - ecp, ecp2, ecp3, ecp5u - - lptm, lptm2 - - machxo, machxo2, machxo3l - - sc, scm - - xp, xp2 + - `ec` + - `ecp`, `ecp2`, `ecp3`, `ecp5u` + - `lptm`, `lptm2` + - `machxo`, `machxo2`, `machxo3l` + - `sc`, `scm` + - `xp`, `xp2` - Xilinx ISE (≥14.0): - - unisim (incl. secureip) - - unimacro - - simprim (incl. secureip) - - xilinxcorelib + - `unisim` (incl. `secureip`) + - `unimacro` + - `simprim` (incl. `secureip`) + - `xilinxcorelib` - Xilinx Vivado (≥2014.1): - - unisim (incl. secureip) - - unimacro + - `unisim` (incl. `secureip`) + - `unimacro` ##### Supported Simulation and Verification Libraries @@ -315,15 +302,4 @@ $InstallationDirectory = @{ Author: Patrick Lehmann Last update: 28.10.2016 ------------------------- - -.. TODO:: - - - Convert Markdown to RST - - Vendor Primitives - - Alters / Intel - - Lattice - - OSVVM - - UVVM - - Xilinx ISE - - Xilinx Vivado +------------------------
\ No newline at end of file diff --git a/doc/index.rst b/doc/index.rst index 38f2e9a3b..262575b6e 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -24,20 +24,11 @@ LRM) is a plus. .. rubric:: 23.10.2015 - GHDL 0.33 was released. -Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod -tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At -vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, -no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit -amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut -labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam -et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata -sanctus est Lorem ipsum dolor sit amet - ------------------------------------- +Lorem ipsum dolor sit amet... .. |docdate| date:: %b %d, %Y - %H:%M -.. only:: html +.. container:: lastdocbuilddate This document was generated on |docdate|. @@ -72,7 +63,6 @@ sanctus est Lorem ipsum dolor sit amet :hidden: 2_Getting/Releases - 2_Getting/Docker 3_Building/index 3_Building/VendorPrimitives diff --git a/doc/intro/Contributing.rst b/doc/intro/Contributing.rst deleted file mode 100644 index 66b5675bd..000000000 --- a/doc/intro/Contributing.rst +++ /dev/null @@ -1,97 +0,0 @@ -.. _INTRO:Contributing: - -Contributing -############ - -.. include:: ../shields.txt - -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:`Quick Start Guide <USING:QuickStart>` for an introduction. Furthermore, we encourage you to read :ref:`Invoking GHDL <USING:Invoking>`, where the most commonly used options are explained. You can also check the complete :ref:`Command Reference <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. - -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 bugs report and suggestions for any aspect of GHDL. So, please report them so that we are aware! - -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>`. Then, you can reach us through various ways: - -- |SHIELD:gitter| -- Open a |SHIELD:issues-new| -- Fork, modify and create a Pull Request on |SHIELD:issues-pr| |SHIELD:issues-pr-closed| -- Suscribe to the mailing-list |SHIELD:mailing| - -The indications below shall help you choose which one to take. - -improve doc -examples - - -If you have an interresting project, please send us feedback or get listed on our :doc:`Who uses GHDL?` page. - - -Related interesting projects -============== - -Asking for enhancements -============== - - .. _reporting_bugs: - -Reporting bugs -============== - - If you cannot compile, please report the gcc version, GNAT version and gcc source version. - - Minimum-(non)-Working-Example (MWE) -`How To Ask Questions The Smart Way <www.catb.org/~esr/faqs/smart-questions.html>`_ - -If the compiler crashes, this is a bug. Reliable tools never crash. - -If your compiled VHDL executable crashes, this may be a bug at -runtime or the code produced may be wrong. However, since VHDL -has a notion of pointers, an erroneous VHDL program (using invalid -pointers for example) may 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. -Please send the input file and what you expected. If you know the LRM -well enough, please specify the paragraph which has not been well -implemented. If you don't know the LRM, maybe your bug report will be -rejected simply because there is no bug. In the latter case, it may be -difficult to discuss the issue; and comparisons with other VHDL tools -is not a very strong argument. - -If a compiler message is not clear enough for you, please tell me. The -error messages can be improved, but I have not enough experience with -them. - -If you send a `VHDL` file producing a bug, it is a good idea to try -to make it as short as possible. It is also a good idea to make it -looking like a test: write a comment which explains whether the file -should compile, and if yes, whether or not it should run successfully. -In the latter case, an assert statement should finish the test; the -severity level note indicates success, while a severity level failure -indicates failure. - -For bug reports, please include enough information for the maintainers to -reproduce the problem. This includes: - -* the version of `GHDL` (you can get it with :samp:`ghdl --version`). -* the operating system -* whether you have built `GHDL` from sources or used the binary - distribution. -* the content of the input files -* a description of the problem and samples of any erroneous input -* anything else that you think would be helpful. - -Documentation -============== - -If you have found a mistake in the manual, please send a comment. If -you have not understood some parts of this manual, please tell me. -English is not my mother tongue, so this manual may not be well-written. -Again, rewriting part of it is a good way to improve it. - -.. TODO:: - - - Pull Requests (PRs) - - Check Building -> GHDL -> Directory Structure] - - Beware that some commit messages can `automatically close <https://help.github.com/articles/closing-issues-via-commit-messages/>`_ PRs] -
\ No newline at end of file diff --git a/doc/intro/Copyrights.rst b/doc/intro/Copyrights.rst deleted file mode 100644 index a178bcd55..000000000 --- a/doc/intro/Copyrights.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. _INTRO:Copyrights: - -Copyrights | License -############ - -The GHDL front-end, the :samp:`std.textio` package and the runtime -library (:samp:`grt`) are copyrighted Tristan Gingold, come with **absolutely -no warranty**, and are distributed under the conditions of the General -Public License. - -The :samp:`ieee.numeric_bit` and :samp:`ieee.numeric_std` packages are -copyrighted by the IEEE. The source files may be distributed without -change, except as permitted by the standard. - -This source file may not be -sold or distributed for profit. See the source file and the IEEE 1076.3 -standard for more information. - -The :samp:`ieee.std_logic_1164`, :samp:`ieee.Math_Real` and -:samp:`ieee.Math_Complex` packages are copyrighted by the IEEE. See -source files for more information. - -The :samp:`ieee.VITAL_Primitives`, :samp:`ieee.VITAL_Timing` and -:samp:`ieee.VITAL_Memory` packages are copyrighted by IEEE. See source -file and the IEEE 1076.4 standards for more information. - -The packages :samp:`std_logic_arith`, -:samp:`std_logic_signed`, :samp:`std_logic_unsigned` and -:samp:`std_logic_textio` contained in the :samp:`synopsys` directory are -copyrighted by Synopsys, Inc. The source files 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. See the source files for more information. - -The package :samp:`std_logic_arith` contained in the :samp:`mentor` -directory is copyrighted by Mentor Graphics. The source files may be -distributed in whole without restriction provided that the copyright -statement is not removed from the file and that any derivative work -contains this copyright notice. See the source files for more information. - -As a consequence of the runtime copyright, you may not be allowed to -distribute an executable produced by `GHDL` without the VHDL -sources. To my mind, this is not a real restriction, since there is no -points in distributing VHDL executable. Please, send a comment -(:ref:`Reporting_bugs`) if you don't like this policy. - -.. TODO:: - - - https://www.gnu.org/licenses/old-licenses/gpl-2.0.html - - Available in the following formats: plain text, Texinfo, LaTeX, standalone HTML, Docbook, Markdown, ODF, RT - - See `#280 <https://github.com/tgingold/ghdl/issues/280#issuecomment-279595802>`_ - - GHDL is copyright (c) 2002 - 2015 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. - - You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. - - - Contributors to ghdl: - - Tristan Gingold (sole author of ghdl as a whole) - - Brian Drummond (gcc4.8.2 update, OSVVM port, some bugfixes) - - David Koontz (Mac OSX builds, LRM compliance work, bugfix analyses) - - Joris van Rantwijk (Debian packaging) - - Brian Davis (Windows Mcode builds) - - Adam Jensen (FreeBSD builds) - - Felix Bertram (VPI interface) - - with apologies to anyone who ought to be on this list but isn't. Thanks also to all those who have reported bugs and support issues, and often patches and testcases to either: https://gna.org/bugs/?group=ghdl or https://sourceforge.net/p/ghdl-updates/tickets/ - - https://en.wikipedia.org/wiki/Wikipedia:Copyrights#Reusers.27_rights_and_obligations - https://en.wikipedia.org/wiki/Wikipedia:General_disclaimer
\ No newline at end of file diff --git a/doc/intro/WhatIsGHDL.rst b/doc/intro/WhatIsGHDL.rst deleted file mode 100644 index 5733c6869..000000000 --- a/doc/intro/WhatIsGHDL.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. include:: <isonum.txt> - -.. _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 <http://gcc.gnu.org/>`_, `LLVM <http://llvm.org/>`_ or `x86 <https://en.wikipedia.org/wiki/X86-64>`_/`i386 <https://en.wikipedia.org/wiki/Intel_80386>`_ only, a built-in one) and runs on `GNU/Linux <http://en.wikipedia.org/wiki/Linux_distribution>`_, `Windows <http://en.wikipedia.org/wiki/Microsoft_Windows>`_ |trade| and `macOS <http://en.wikipedia.org/wiki/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>`_, `VCD <https://en.wikipedia.org/wiki/Value_change_dump>`_ or `FST` files which can be viewed with a `waveform viewer <https://en.wikipedia.org/wiki/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/>`_. `PSL <https://en.wikipedia.org/wiki/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>`_), ... diff --git a/doc/intro/WhatIsVHDL.rst b/doc/intro/WhatIsVHDL.rst deleted file mode 100644 index 06696d75d..000000000 --- a/doc/intro/WhatIsVHDL.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _INTRO:VHDL: - -What is `VHDL`? -############### - -`VHDL <https://en.wikipedia.org/wiki/VHDL>`_ is an acronym for Very High Speed Integrated Circuit (`VHSIC <https://en.wikipedia.org/wiki/VHSIC>`_) `Hardware Description Language <https://en.wikipedia.org/wiki/Hardware_description_language>`_ 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 <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/>`_). diff --git a/doc/shields.txt b/doc/shields.txt index 1bdd98bac..bb521789d 100644 --- a/doc/shields.txt +++ b/doc/shields.txt @@ -19,35 +19,44 @@ :alt: Latest release .. |SHIELD:code-lic| image:: https://img.shields.io/badge/code%20license-GPLv2-bd0000.svg?style=flat - :target: intro/Copyrights.html + :target: Licenses.html :alt: GNU General Public License 2 -.. |SHIELD:doc-lic| image:: https://img.shields.io/badge/doc%20license-CC--BY--SA-aab2ab.svg?style=flat - :target: intro/Copyrights.html - :alt: Creative Commons Attribution-ShareAlike +.. |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 -.. |SHIELD:mailing| image:: https://img.shields.io/badge/mailgnaorgghdl-discuss-ff69b4.svg?style=flat +.. |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/ .. |SHIELD:gitter| image:: https://img.shields.io/gitter/room/ghdl1/Lobby.svg?colorB=4cb696 :target: https://gitter.im/ghdl/ghdl1 :alt: Talk to us on Gitter -.. |SHIELD:issues-new| image:: https://img.shields.io/badge/tgingold/issues-new-yellow.svg?style=flat +.. |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 .. |SHIELD:issues-open| image:: https://img.shields.io/github/issues/tgingold/ghdl.svg :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 .. |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 .. |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 +.. |SHIELD:contributors| image:: https://img.shields.io/github/contributors/tgingold/ghdl.svg?style=flat + :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 diff --git a/doc/shieldswho.txt b/doc/shieldswho.txt new file mode 100644 index 000000000..0e824023e --- /dev/null +++ b/doc/shieldswho.txt @@ -0,0 +1,27 @@ +.. |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 + +.. |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 + +.. |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 + +.. |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 + +.. |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 + +.. |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 diff --git a/doc/using/QuickStartGuide.rst b/doc/using/QuickStartGuide.rst index e921199fa..7fd3c946f 100644 --- a/doc/using/QuickStartGuide.rst +++ b/doc/using/QuickStartGuide.rst @@ -4,14 +4,12 @@ Quick Start Guide ****************** -In this chapter, you will learn how to use the GHDL compiler by -working on two examples. +In this chapter, you will learn how to use `GHDL` by working on a few examples. -The hello world program +The `'Hello world'` program ======================= -To illustrate the large purpose of VHDL, here is a commented VHDL -"Hello world" program. +To illustrate the large purpose of `VHDL`, here is a commented `'Hello world'` program: .. code-block:: VHDL @@ -33,31 +31,18 @@ To illustrate the large purpose of VHDL, here is a commented VHDL end process; end behaviour; -Suppose this program is contained in the file :file:`hello.vhdl`. -First, you have to compile the file; this is called `analysis` of a design -file in VHDL terms. +Suppose this program is contained in a file named :file:`hello.vhdl`. 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`. -.. code-block:: shell - - $ ghdl -a hello.vhdl +.. TIP:: If a `GCC`/`LLVM` variant of `GHDL` is used, this command generates a file :file:`hello.o`, which is the object file corresponding to your `VHDL` program. This is not created on Windows. -This command creates or updates a file :file:`work-obj93.cf`, which -describes the library `work`. On GNU/Linux, this command generates a -file :file:`hello.o`, which is the object file corresponding to your -VHDL program. The object file is not created on Windows. +Then, you have to build an executable file. Again, 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. -Then, you have to build an executable file. +Last, launch the simulation running :samp:`ghdl -r hello_world` in the `shell`. The result of the simulation will be shown on the screen:: -.. code-block:: shell - - $ ghdl -e hello_world + Hello world! -The :option:`-e` option means :dfn:`elaborate`. With this option, `GHDL` -creates code in order to elaborate a design, with the :samp:`hello_world` -entity at the top of the hierarchy. +.. TIP:: If a `GCC`/`LLVM` variant of `GHDL` is used, an executable program called :file:`hello_world` is generated at this step. which can be run -On GNU/Linux, if you have enabled the GCC backend during the compilation of `GHDL`, -an executable program called :file:`hello_world` which can be run is generated: .. code-block:: shell @@ -69,18 +54,11 @@ or directly: $ ./hello_world - On Windows or if the GCC backend was not enabled, no file is created. The simulation is launched using this command: -.. code-block:: shell - - > ghdl -r hello_world -The result of the simulation appears on the screen:: - - Hello world! A full adder @@ -362,4 +340,5 @@ Further examples .. TODO:: - Add references to examples/tutorials with GHDL.
\ No newline at end of file + * 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?
\ No newline at end of file |