diff options
| -rw-r--r-- | COPYING.md | 434 | ||||
| -rw-r--r-- | README.md | 4 | ||||
| -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 |
19 files changed, 997 insertions, 491 deletions
diff --git a/COPYING.md b/COPYING.md index af5153d8f..b57bd4f35 100644 --- a/COPYING.md +++ b/COPYING.md @@ -1,4 +1,4 @@ -### GNU GENERAL PUBLIC LICENSE +## GNU GENERAL PUBLIC LICENSE Version 2, June 1991 @@ -358,4 +358,434 @@ you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the [GNU Lesser General Public License](http://www.gnu.org/licenses/lgpl.html) instead of this -License.
\ No newline at end of file + +--- + +License.Attribution-ShareAlike 4.0 International + +======================================================================= + +Creative Commons Corporation ("Creative Commons") is not a law firm and +does not provide legal services or legal advice. Distribution of +Creative Commons public licenses does not create a lawyer-client or +other relationship. Creative Commons makes its licenses and related +information available on an "as-is" basis. Creative Commons gives no +warranties regarding its licenses, any material licensed under their +terms and conditions, or any related information. Creative Commons +disclaims all liability for damages resulting from their use to the +fullest extent possible. + +Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and +conditions that creators and other rights holders may use to share +original works of authorship and other material subject to copyright +and certain other rights specified in the public license below. The +following considerations are for informational purposes only, are not +exhaustive, and do not form part of our licenses. + + Considerations for licensors: Our public licenses are + intended for use by those authorized to give the public + permission to use material in ways otherwise restricted by + copyright and certain other rights. Our licenses are + irrevocable. Licensors should read and understand the terms + and conditions of the license they choose before applying it. + Licensors should also secure all rights necessary before + applying our licenses so that the public can reuse the + material as expected. Licensors should clearly mark any + material not subject to the license. This includes other CC- + licensed material, or material used under an exception or + limitation to copyright. More considerations for licensors: + wiki.creativecommons.org/Considerations_for_licensors + + Considerations for the public: By using one of our public + licenses, a licensor grants the public permission to use the + licensed material under specified terms and conditions. If + the licensor's permission is not necessary for any reason--for + example, because of any applicable exception or limitation to + copyright--then that use is not regulated by the license. Our + licenses grant only permissions under copyright and certain + other rights that a licensor has authority to grant. Use of + the licensed material may still be restricted for other + reasons, including because others have copyright or other + rights in the material. A licensor may make special requests, + such as asking that all changes be marked or described. + Although not required by our licenses, you are encouraged to + respect those requests where reasonable. More_considerations + for the public: + wiki.creativecommons.org/Considerations_for_licensees + +======================================================================= + +Creative Commons Attribution-ShareAlike 4.0 International Public +License + +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution-ShareAlike 4.0 International Public License ("Public +License"). To the extent this Public License may be interpreted as a +contract, You are granted the Licensed Rights in consideration of Your +acceptance of these terms and conditions, and the Licensor grants You +such rights in consideration of benefits the Licensor receives from +making the Licensed Material available under these terms and +conditions. + + +Section 1 -- Definitions. + + a. Adapted Material means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. + + b. Adapter's License means the license You apply to Your Copyright + and Similar Rights in Your contributions to Adapted Material in + accordance with the terms and conditions of this Public License. + + c. BY-SA Compatible License means a license listed at + creativecommons.org/compatiblelicenses, approved by Creative + Commons as essentially the equivalent of this Public License. + + d. Copyright and Similar Rights means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. + + e. Effective Technological Measures means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. + + f. Exceptions and Limitations means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. + + g. License Elements means the license attributes listed in the name + of a Creative Commons Public License. The License Elements of this + Public License are Attribution and ShareAlike. + + h. Licensed Material means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. + + i. Licensed Rights means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. + + j. Licensor means the individual(s) or entity(ies) granting rights + under this Public License. + + k. Share means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. + + l. Sui Generis Database Rights means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. + + m. You means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. + + +Section 2 -- Scope. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: + + a. reproduce and Share the Licensed Material, in whole or + in part; and + + b. produce, reproduce, and Share Adapted Material. + + 2. Exceptions and Limitations. For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. + + 3. Term. The term of this Public License is specified in Section + 6(a). + + 4. Media and formats; technical modifications allowed. The + Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. + + 5. Downstream recipients. + + a. Offer from the Licensor -- Licensed Material. Every + recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. + + b. Additional offer from the Licensor -- Adapted Material. + Every recipient of Adapted Material from You + automatically receives an offer from the Licensor to + exercise the Licensed Rights in the Adapted Material + under the conditions of the Adapter's License You apply. + + c. No downstream restrictions. You may not offer or impose + any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. + + 6. No endorsement. Nothing in this Public License constitutes or + may be construed as permission to assert or imply that You + are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this + Public License. + + 3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. + + +Section 3 -- License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified + form), You must: + + a. retain the following if it is supplied by the Licensor + with the Licensed Material: + + i. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of + warranties; + + v. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; + + b. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and + + c. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + + 3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + + b. ShareAlike. + + In addition to the conditions in Section 3(a), if You Share + Adapted Material You produce, the following conditions also apply. + + 1. The Adapter's License You apply must be a Creative Commons + license with the same License Elements, this version or + later, or a BY-SA Compatible License. + + 2. You must include the text of, or the URI or hyperlink to, the + Adapter's License You apply. You may satisfy this condition + in any reasonable manner based on the medium, means, and + context in which You Share Adapted Material. + + 3. You may not offer or impose any additional or different terms + or conditions on, or apply any Effective Technological + Measures to, Adapted Material that restrict exercise of the + rights granted under the Adapter's License You apply. + + +Section 4 -- Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database; + + b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material, + + including for purposes of Section 3(b); and + c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + + +Section 5 -- Disclaimer of Warranties and Limitation of Liability. + + a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + + b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + + c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + + +Section 6 -- Term and Termination. + + a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any + right the Licensor may have to seek remedies for Your violations + of this Public License. + + c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + + d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + + +Section 7 -- Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + + +Section 8 -- Interpretation. + + a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + + c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + + d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + + +======================================================================= + +Creative Commons is not a party to its public +licenses. Notwithstanding, Creative Commons may elect to apply one of +its public licenses to material it publishes and in those instances +will be considered the “Licensor.” The text of the Creative Commons +public licenses is dedicated to the public domain under the CC0 Public +Domain Dedication. Except for the limited purpose of indicating that +material is shared under a Creative Commons public license or as +otherwise permitted by the Creative Commons policies published at +creativecommons.org/policies, Creative Commons does not authorize the +use of the trademark "Creative Commons" or any other trademark or logo +of Creative Commons without its prior written consent including, +without limitation, in connection with any unauthorized modifications +to any of its public licenses or any other arrangements, +understandings, or agreements concerning use of licensed material. For +the avoidance of doubt, this paragraph does not form part of the +public licenses. + +Creative Commons may be contacted at creativecommons.org. + @@ -1,4 +1,4 @@ -[](http://ghdl.readthedocs.io/en/latest/?badge=latest) [](https://gitter.im/ghdl1/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [](https://github.com/tgingold/ghdl/blob/master/COPYING.md) [](https://github.com/tgingold/ghdl/blob/master/COPYING.md) +[](http://ghdl.readthedocs.io) [](https://gitter.im/ghdl1/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [](https://github.com/tgingold/ghdl/blob/master/COPYING.md) [](https://github.com/tgingold/ghdl/blob/master/COPYING.md) [](https://travis-ci.org/tgingold/ghdl) [](https://ci.appveyor.com/project/tgingold/ghdl)  [](https://github.com/tgingold/ghdl/releases) # GHDL @@ -22,7 +22,7 @@ Supported third party projects: [VUnit](https://vunit.github.io), [OSVVM](http:/ GHDL is free software: - [](https://github.com/tgingold/ghdl/blob/master/COPYING.md) -- [](https://github.com/tgingold/ghdl/blob/master/COPYING.md) available at [](https://ghdl.readthedocs.org) +- [](https://github.com/tgingold/ghdl/blob/master/COPYING.md) available at [](https://ghdl.readthedocs.io) - Some of the runtime libraries, are under different terms; see the individual source files for details. ## Getting GHDL 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 |