diff options
| -rw-r--r-- | README.md | 81 | ||||
| -rw-r--r-- | doc/about.rst | 80 | ||||
| -rw-r--r-- | doc/contribute.rst | 70 | ||||
| -rw-r--r-- | doc/development/CodingStyle.rst | 2 | ||||
| -rw-r--r-- | doc/development/Directories.rst | 31 | ||||
| -rw-r--r-- | doc/development/Scripts.rst (renamed from doc/pyGHDL/index.rst) | 27 | ||||
| -rw-r--r-- | doc/development/building/GCC.rst (renamed from doc/getting/GCC.rst) | 0 | ||||
| -rw-r--r-- | doc/development/building/LLVM.rst (renamed from doc/getting/LLVM.rst) | 0 | ||||
| -rw-r--r-- | doc/development/building/Sources.rst (renamed from doc/getting/Releases.rst) | 83 | ||||
| -rw-r--r-- | doc/development/building/index.rst (renamed from doc/getting/index.rst) | 82 | ||||
| -rw-r--r-- | doc/development/building/mcode.rst (renamed from doc/getting/mcode.rst) | 0 | ||||
| -rw-r--r-- | doc/getting.rst (renamed from doc/getting/PrecompileVendorPrimitives.rst) | 36 | ||||
| -rw-r--r-- | doc/getting/Directories.rst | 50 | ||||
| -rw-r--r-- | doc/gnatdoc/index.rst | 2 | ||||
| -rw-r--r-- | doc/helpers.py | 193 | ||||
| -rw-r--r-- | doc/index.rst | 77 | ||||
| -rw-r--r-- | doc/licenses.rst | 62 | ||||
| -rw-r--r-- | doc/quick_start/index.rst | 17 | ||||
| -rw-r--r-- | doc/quick_start/python/index.rst | 33 | ||||
| -rw-r--r-- | doc/quick_start/simulation/DLXModelSuite.rst (renamed from doc/quick_start/DLXModelSuite.rst) | 0 | ||||
| -rw-r--r-- | doc/quick_start/simulation/adder/adder.vhdl (renamed from doc/quick_start/adder/adder.vhdl) | 0 | ||||
| -rw-r--r-- | doc/quick_start/simulation/adder/adder_tb.vhdl (renamed from doc/quick_start/adder/adder_tb.vhdl) | 0 | ||||
| -rw-r--r-- | doc/quick_start/simulation/adder/index.rst (renamed from doc/quick_start/adder/README.rst) | 0 | ||||
| -rw-r--r-- | doc/quick_start/simulation/heartbeat/heartbeat.vhdl (renamed from doc/quick_start/heartbeat/heartbeat.vhdl) | 0 | ||||
| -rw-r--r-- | doc/quick_start/simulation/heartbeat/index.rst (renamed from doc/quick_start/heartbeat/README.rst) | 0 | ||||
| -rw-r--r-- | doc/quick_start/simulation/hello/hello.vhdl (renamed from doc/quick_start/hello/hello.vhdl) | 0 | ||||
| -rw-r--r-- | doc/quick_start/simulation/hello/index.rst (renamed from doc/quick_start/hello/README.rst) | 0 | ||||
| -rw-r--r-- | doc/quick_start/simulation/index.rst (renamed from doc/quick_start/README.rst) | 54 | ||||
| -rwxr-xr-x | testsuite/sanity/005examples/testsuite.sh | 2 |
29 files changed, 403 insertions, 579 deletions
@@ -3,21 +3,25 @@ </p> <p align="center"> - <a title="Documentation" href="https://ghdl.github.io/ghdl"><img src="https://img.shields.io/website.svg?label=ghdl.github.io%2Fghdl&longCache=true&style=flat-square&url=http%3A%2F%2Fghdl.github.io%2Fghdl%2Findex.html"></a><!-- + <a title="Documentation" href="https://ghdl.github.io/ghdl"><img src="https://img.shields.io/website.svg?label=ghdl.github.io%2Fghdl&longCache=true&style=flat-square&url=http%3A%2F%2Fghdl.github.io%2Fghdl%2Findex.html&label=GitHub"></a><!-- --> - <a title="Join the chat at https://gitter.im/ghdl1/Lobby" href="https://gitter.im/ghdl1/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"><img src="https://img.shields.io/badge/chat-on%20gitter-4db797.svg?longCache=true&style=flat-square&logo=gitter&logoColor=e8ecef"></a><!-- + <a title="Join the chat at https://gitter.im/ghdl1/Lobby" href="https://gitter.im/ghdl1/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"><img src="https://img.shields.io/badge/Chat-on%20gitter-4db797.svg?longCache=true&style=flat-square&logo=gitter&logoColor=e8ecef"></a><!-- --> - <a title="Docker Images" href="https://github.com/ghdl/docker"><img src="https://img.shields.io/docker/pulls/ghdl/ghdl.svg?logo=docker&logoColor=e8ecef&style=flat-square&label=docker"></a><!-- + <a title="Docker Images" href="https://github.com/ghdl/docker"><img src="https://img.shields.io/docker/pulls/ghdl/ghdl.svg?logo=docker&logoColor=e8ecef&style=flat-square&label=Docker"></a><!-- --> - <a title="Releases" href="https://github.com/ghdl/ghdl/releases"><img src="https://img.shields.io/github/commits-since/ghdl/ghdl/latest.svg?longCache=true&style=flat-square"></a> - <a title="CII Best Practices" href="https://bestpractices.coreinfrastructure.org/en/projects/3157"><img src="https://img.shields.io/cii/percentage/3157??longCache=true&style=flat-square"></a><!-- + <a title="Releases" href="https://github.com/ghdl/ghdl/releases"><img src="https://img.shields.io/github/commits-since/ghdl/ghdl/latest.svg?longCache=true&style=flat-square&logo=GitHub"></a><!-- --> +</p> +<p align="center"> <a title="'Test' workflow Status" href="https://github.com/ghdl/ghdl/actions?query=workflow%3ATest"><img alt="'Test' workflow Status" src="https://img.shields.io/github/workflow/status/ghdl/ghdl/Test?longCache=true&style=flat-square&label=Test&logo=github%20actions&logoColor=fff"></a><!-- --> - <a title="AppVeyor" href="https://ci.appveyor.com/project/tgingold/ghdl-psgys/history"><img src="https://img.shields.io/appveyor/ci/tgingold/ghdl-psgys/master.svg?logo=appveyor&logoColor=e8ecef&style=flat-square"></a> + <a title="AppVeyor" href="https://ci.appveyor.com/project/tgingold/ghdl-psgys/history"><img src="https://img.shields.io/appveyor/ci/tgingold/ghdl-psgys/master.svg?logo=appveyor&logoColor=e8ecef&style=flat-square&label=Test"></a><!-- + --> + <a title="CII Best Practices" href="https://bestpractices.coreinfrastructure.org/en/projects/3157"><img src="https://img.shields.io/cii/percentage/3157??longCache=true&style=flat-square&label=CII&logo=Linux%20Foundation"></a><!-- + --> </p> -This directory contains the sources of GHDL, the open-source analyzer, compiler, simulator and (experimental) synthesizer for [VHDL](https://en.wikipedia.org/wiki/VHDL), a Hardware Description Language ([HDL](https://en.wikipedia.org/wiki/Hardware_description_language)). GHDL is not an interpreter: it allows you to analyse and elaborate sources to generate machine code from your design. Native program execution is the only way for high speed simulation. +This directory contains the sources of GHDL, the open-source analyzer, compiler, simulator and (experimental) synthesizer for [VHDL](https://en.wikipedia.org/wiki/VHDL), a Hardware Description Language ([HDL](https://en.wikipedia.org/wiki/Hardware_description_language)). GHDL is not an interpreter: it allows you to analyse and elaborate sources for generating machine code from your design. Native program execution is the only way for high speed simulation. # Main features @@ -27,11 +31,16 @@ Partial support of [PSL](https://en.wikipedia.org/wiki/Property_Specification_La By using a code generator ([LLVM](https://llvm.org/), [GCC](https://gcc.gnu.org/) or, [x86_64](https://en.wikipedia.org/wiki/X86-64)/[i386](https://en.wikipedia.org/wiki/Intel_80386) only, a built-in one), it is much faster than any interpreted simulator. It can handle very large designs, such as [leon3/grlib](https://www.gaisler.com/index.php/downloads/leongrlib). -GHDL runs on [GNU/Linux](https://en.wikipedia.org/wiki/Linux_distribution), [Windows](https://en.wikipedia.org/wiki/Microsoft_Windows) and [macOS](https://en.wikipedia.org/wiki/MacOS); on `x86`, `x86_64`, `armv6/armv7/aarch32` and `aarch64`. You can freely [download](https://github.com/ghdl/ghdl/releases) a binary distribution for your OS, use [GHDL Docker images](https://github.com/ghdl/docker), or try to build it on your own machine (see *'Getting GHDL'* below). +GHDL runs on [GNU/Linux](https://en.wikipedia.org/wiki/Linux_distribution), [Windows](https://en.wikipedia.org/wiki/Microsoft_Windows) and [macOS](https://en.wikipedia.org/wiki/MacOS); on `x86`, `x86_64`, `armv6/armv7/aarch32`, `aarch64` and `ppc64`. You can freely download [nightly](https://github.com/ghdl/ghdl/releases) assets, use OCI images (aka Docker/Podman containers), or try building it on your own machine (see *'Getting GHDL'* below). + +Can write waveforms to [GHW](https://ghdl.github.io/ghdl/using/Simulation.html?highlight=GHW#cmdoption-wave), [VCD](https://en.wikipedia.org/wiki/Value_change_dump) or FST files. Combined with a [GUI](https://en.wikipedia.org/wiki/Graphical_user_interface)-based [waveform viewer](https://en.wikipedia.org/wiki/Waveform_viewer) and a good text editor, GHDL is a very powerful tool for writing, testing and simulating your code. + +Co-simulation with foreign applications is supported through Verilog Procedural Interface (VPI) and/or VHPIDIRECT. See [ghdl.github.io/ghdl-cosim](https://ghdl.github.io/ghdl-cosim). -Can write waveforms to a [GHW](https://ghdl.github.io/ghdl/using/Simulation.html?highlight=GHW#cmdoption-wave), [VCD](https://en.wikipedia.org/wiki/Value_change_dump) or FST file. Combined with a [GUI](https://en.wikipedia.org/wiki/Graphical_user_interface)-based [waveform viewer](https://en.wikipedia.org/wiki/Waveform_viewer) and a good text editor, GHDL is a very powerful tool for writing, testing and simulating your code. +Can synthesize arbitrarily complex VHDL designs into a VHDL 1993 netlist, which can be implicitly or +explicitly used in open source or vendor synthesis frameworks. -Supported third party projects: [cocotb](https://github.com/potentialventures/cocotb) (through the [VPI interface](https://en.wikipedia.org/wiki/Verilog_Procedural_Interface)), [OSVVM](https://osvvm.org), [UVVM](https://github.com/UVVM/UVVM), [VUnit](https://vunit.github.io), ... +Supported third party projects: [Yosys](https://github.com/YosysHQ/yosys) (through [ghdl-yosys-plugin](https://github.com/ghdl/ghdl-yosys-plugin)), [cocotb](https://github.com/potentialventures/cocotb) (through the VPI interface), [OSVVM](https://osvvm.org), [UVVM](https://github.com/UVVM/UVVM), [VUnit](https://vunit.github.io), ... (see [ghdl/extended-tests](https://github.com/ghdl/extended-tests)). GHDL is free software: @@ -42,56 +51,28 @@ GHDL is free software: # Getting GHDL - Pre-built packages: - - Approximately once a year, tagged binary distributions are made available through the [releases](https://github.com/ghdl/ghdl/releases) tab. - - After each succesful CI run, [nightly](https://github.com/ghdl/ghdl/releases/tag/nightly) tarballs/zipfiles for Ubuntu Focal and Windows (MSYS2) are updated. -- For using GHDL in CI, [setup-ghdl-ci](https://github.com/ghdl/setup-ghdl-ci) is provided. It is a GitHub Action (see [github.com/features/actions](https://github.com/features/actions)) to setup GHDL in just 3 lines. -- You may use [GHDL Docker images](https://github.com/ghdl/docker) in case your didn't find a suitable release. -- Build GHDL yourself (see below)! - -## Building GHDL - -GHDL currently supports three different back-ends (code generators). Each has its pros and cons. You can find specific instructions for each of the options in '[Building](https://ghdl.github.io/ghdl/getting/)'. - -### TL;DR - -In order to follow the traditional way to `configure` and `make`, you need an Ada compiler. Most GNU/Linux package managers provide a package named `gcc-ada` or `gcc-gnat`. - -> Alternatively, GNAT GPL can be downloaded anonymously from [libre.adacore.com](https://libre.adacore.com/tools/gnat-gpl-edition/) (later than 2017 is suggested; for x86, 32 or 64 bits). Then, untar and run the *doinstall* script. - -> Depending on the OS and distribution you are using, you will also need to install some toolchain dependencies, such as `zlib`. See '[Building](https://ghdl.github.io/ghdl/getting/)' for specific package names. - -To use mcode backend (easiest to build), in the GHDL base directory, configure and build: - -```sh -$ ./configure --prefix=/usr/local -$ make -``` - -At that place, you can already use the `ghdl_mcode` built in the directory. You can also install GHDL: - -```sh -$ make install -``` - -That's all! - -> The executable is installed as 'ghdl' in `/usr/local`. To install it to a different path, change the `--prefix` in the call to `configure`. For example, on Windows, you may want to set it to `--prefix=/c/Program Files (x86)/GHDL`. + - GHDL is available through the default package manager on most distributions: Debian/Ubuntu, Fedora, Arch Linux, MSYS2, etc. + - After each succesful CI run, [nightly](https://github.com/ghdl/ghdl/releases/tag/nightly) tarballs/zipfiles for Ubuntu and Windows (MSYS2) are updated. + - For using GHDL in CI, [setup-ghdl-ci](https://github.com/ghdl/setup-ghdl-ci) is provided. It is a GitHub Action (see [github.com/features/actions](https://github.com/features/actions)) to setup GHDL in just 3 lines. +- You may use containers from from [ghdl/docker](https://github.com/ghdl/docker) or [hdl/containers](https://github.com/hdl/containers), in case your didn't find a suitable release. +- Build GHDL yourself! See [ghdl.github.io/ghdl: Building GHDL](https:///ghdl.github.io/ghdl/development/building/index.html). # Project structure ## Regular users -- The 'regular' tool allows analysis, compilation, simulation and (very experimental) synthesis of VHDL 1993 netlists. It is written in Ada and C, and three different backends are supported, which are sometimes named `ghdl_mcode`, `ghdl_gcc` and `ghdl_llvm`. This is the entrypoint for most users. +- The CLI tool allows analysis, compilation, simulation and (experimental) synthesis for generating VHDL 1993 netlists. It is written in Ada and C, and three different backends are supported, which are sometimes named `ghdl_mcode`, `ghdl_gcc` and `ghdl_llvm`. This is the entrypoint for most users. -- `ghdl-ls` implements Language Server Protocol (LSP) in Python. VHDL analysis features provided by GHDL are accessed through `libghdl-py`. This can be integrated in text editors or IDES, such as, Vim, Emacs, Atom or Visual Studio Code. +- **[experimental]** [ghdl-yosys-plugin](https://github.com/ghdl/ghdl-yosys-plugin) is the integration of GHDL as a frontend plugin module for [Yosys Open SYnthesis Suite](http://www.clifford.at/yosys/), which uses the `libghdl` library (built with `--enable-synth`). -- [vscode-client](https://github.com/ghdl/ghdl-language-server/tree/master/vscode-client) is an extension for [Visual Studio Code (VSC)](https://code.visualstudio.com/) to provide language support for VHDL by interfacing `ghdl-ls`. +- `ghdl-ls` (part of pyGHDL, see below) implements Language Server Protocol (LSP) in Python. VHDL analysis features provided by GHDL are accessed through `libghdl`. This can be integrated in text editors or IDES, such as, Vim, Emacs, Atom or Visual Studio Code. See [ghdl/ghdl-language-server](https://github.com/ghdl/ghdl-language-server). + - [vscode-client](https://github.com/ghdl/ghdl-language-server/tree/master/vscode-client) is an extension for [Visual Studio Code (VSC)](https://code.visualstudio.com/) to provide language support for VHDL by interfacing `ghdl-ls`. ## Advanced users -- `libghdl` is a shared library that includes a subset of the regular features plus some features to be used by extension tools (i.e. `libghdl-py`). This is built along with the regular GHDL and it supports both non-synthesisable and synthesisable code. Nonetheless, this is not for users, but for tools built on top of the core. When configured along with `--enable-synth`, this shared library includes **[experimental]** synthesis features too. +- `libghdl` is a shared library that includes a subset of the regular features plus some features to be used by extension tools (i.e. `pyGHDL`). This is built along with the regular GHDL and it supports both non-synthesisable and synthesisable code. Nonetheless, this is not for users, but for tools built on top of the core. When configured along with `--enable-synth`, this shared library includes synthesis features too. -- [pyGHDL](pyGHDL) is a Python interface to `libghdl`. Currently, it is only used by `ghdl-ls`; however, it can be useful for advanced users which are willing to build Python utilities based on GHDL. +- [pyGHDL](pyGHDL) is a Python interface to `libghdl`. Currently, it is only used by `ghdl-ls`; however, it can be useful for advanced users which are willing to build Python utilities based on GHDL. There is work in progress for binding libghdl to [pyVHDLModel](https://github.com/vhdl/pyVHDLModel) (see `pyGHDL.dom`). <p align="center"> <a title="Codecov - Branch Coverage" href="https://codecov.io/gh/ghdl/ghdl"><img alt="Codecov - Branch Coverage" src="https://img.shields.io/codecov/c/github/ghdl/ghdl?longCache=true&style=flat-square&logo=Codecov&logoColor=fff"></a><!-- @@ -102,6 +83,4 @@ That's all! --> </p> -- **[experimental]** [ghdl-yosys-plugin](https://github.com/ghdl/ghdl-yosys-plugin) is the integration of GHDL as a frontend plugin module for [Yosys Open SYnthesis Suite](http://www.clifford.at/yosys/), which uses the `libghdl` library (built with `--enable-synth`). - - **[deprecated]** `ghdl_simul`, which supports interpreted simulation, is available for historical reasons and for development/debugging only. It is very slow compared to the 'regular' compiled simulation and not all the features are supported. diff --git a/doc/about.rst b/doc/about.rst index 3e8ea0dd9..b91dd1827 100644 --- a/doc/about.rst +++ b/doc/about.rst @@ -4,43 +4,73 @@ from helpers import createShields createShields('shieldswho') -About GHDL -########## +About +##### .. _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. +: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). +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. +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. +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`. Five revisions exist: `1987 <http://ieeexplore.ieee.org/document/26487/>`_, `1993 <http://ieeexplore.ieee.org/document/392561/>`_, `2002 <http://ieeexplore.ieee.org/document/1003477/>`_, `2008 <http://ieeexplore.ieee.org/document/4772740/>`_ and `2019 <https://ieeexplore.ieee.org/document/8938196>`_. The standardization is handled by the VHDL Analysis and Standardization Group (`VASG/P1076 <http://www.eda-twiki.org/vasg/>`_). +The development of VHDL started in 1983 and the standard is named `IEEE <https://www.ieee.org/>`__ `1076`. Five revisions +exist: `1987 <http://ieeexplore.ieee.org/document/26487/>`__, `1993 <http://ieeexplore.ieee.org/document/392561/>`__, +`2002 <http://ieeexplore.ieee.org/document/1003477/>`__, `2008 <http://ieeexplore.ieee.org/document/4772740/>`__ and +`2019 <https://ieeexplore.ieee.org/document/8938196>`__. The standardization is handled by the VHDL Analysis and +Standardization Group (`VASG/P1076 <http://www.eda-twiki.org/vasg/>`__). .. _INTRO:GHDL: What is GHDL? ============= -`GHDL` is a shorthand for `G Hardware Design Language` (currently, `G` has no meaning). It is a VHDL analyzer, compiler, simulator and (experimental) synthesizer that can process (nearly) any VHDL design. +`GHDL` is a shorthand for `G Hardware Design Language` (currently, `G` has no meaning). It is a VHDL analyzer, compiler, +simulator and (experimental) synthesizer that can process (nearly) any VHDL design. .. NOTE:: - For almost 20 years, GHDL was *not* a synthesis tool: you could not create a netlist. Hence, most of the content in this documentation corresponds to the usage of GHDL as a compiler/simulator. See :ref:`USING:Synthesis` for further details regarding synthesis. + For almost 20 years, GHDL was *not* a synthesis tool: you could not create a netlist. Hence, most of the content in this + documentation corresponds to the usage of GHDL as a compiler/simulator. See :ref:`USING:Synthesis` for further details + regarding synthesis. -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. +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 named *mcode*) and runs on :wikipedia:`GNU/Linux <Linux_distribution>`, :wikipedia:`Windows <Microsoft_Windows>` |trade| and :wikipedia:`macOS <MacOS>` |trade|; on x86, x86_64, armv6/armv7/aarch32/aarch64, etc. +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 named *mcode*) and runs on :wikipedia:`GNU/Linux <Linux_distribution>`, +:wikipedia:`Windows <Microsoft_Windows>` |trade| and :wikipedia:`macOS <MacOS>` |trade|; on x86, x86_64, armv6/armv7/aarch32/aarch64, +ppc64, etc. -The current version of GHDL does not contain any built-in graphical viewer: you cannot see signal waves. You can still check the behavior of your design with a test bench. Moreover, `GHW <http://ghdl.readthedocs.io/en/latest/using/Simulation.html?highlight=GHW#cmdoption-wave>`_, :wikipedia:`VCD <Value_change_dump>` or `FST` files can be produced, which can be viewed with a :wikipedia:`waveform viewer <Waveform_viewer>`, such as `GtkWave <http://gtkwave.sourceforge.net/>`_. +The current version of GHDL does not contain any built-in graphical viewer: you cannot see signal waves. You can still check +the behavior of your design with a test bench. Moreover, `GHW <http://ghdl.readthedocs.io/en/latest/using/Simulation.html?highlight=GHW#cmdoption-wave>`__, +:wikipedia:`VCD <Value_change_dump>` or `FST` files can be produced, 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, `2008 <http://ieeexplore.ieee.org/document/4772740/>`_. :wikipedia:`PSL <Property_Specification_Language>` is also partially supported. +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, `2008 <http://ieeexplore.ieee.org/document/4772740/>`__. +:wikipedia:`Property Specification Language (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>`_), ... +Several third party projects are supported: `Yosys <https://github.com/YosysHQ/yosys>`__ (through the `ghdl-yosys-plugin <https://github.com/ghdl/ghdl-yosys-plugin>`__) +`cocotb <https://github.com/potentialventures/cocotb>`__ (through the `VPI interface <https://en.wikipedia.org/wiki/Verilog_Procedural_Interface>`__), +`VUnit <https://vunit.github.io/>`__, `OSVVM <http://osvvm.org/>`__, ... .. _INTRO:WHO: @@ -52,14 +82,14 @@ Who uses GHDL? .. only:: html - +-------------------+--------------------+----------------------------------------------------+----------------------------------------------------------------+ - | 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 <https://vunit.github.io/>`_ | A unit testing framework for VHDL/SystemVerilog | - +-------------------+--------------------+----------------------------------------------------+----------------------------------------------------------------+ - | |SHIELD:gl-p1076| | |SHIELD:tw-p1076| | `IEEE P1076 WG <https://www.eda-twiki.org/vasg/>`_ | IEEE P1076 Working Group [VASG] | - +-------------------+--------------------+----------------------------------------------------+----------------------------------------------------------------+ - | |SHIELD:gh-tce| | |SHIELD:doc-tce| | `TCE <http://openasip.org/>`_ | TTA-Based Co-Design Environment - an open-source ASIP toolset. | - +-------------------+--------------------+----------------------------------------------------+----------------------------------------------------------------+ + +-------------------+--------------------+-----------------------------------------------------+----------------------------------------------------------------+ + | 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 <https://vunit.github.io/>`__ | A unit testing framework for VHDL/SystemVerilog | + +-------------------+--------------------+-----------------------------------------------------+----------------------------------------------------------------+ + | |SHIELD:gl-p1076| | |SHIELD:tw-p1076| | `IEEE P1076 WG <https://www.eda-twiki.org/vasg/>`__ | IEEE P1076 Working Group [VASG] | + +-------------------+--------------------+-----------------------------------------------------+----------------------------------------------------------------+ + | |SHIELD:gh-tce| | |SHIELD:doc-tce| | `TCE <http://openasip.org/>`__ | TTA-Based Co-Design Environment - an open-source ASIP toolset. | + +-------------------+--------------------+-----------------------------------------------------+----------------------------------------------------------------+ diff --git a/doc/contribute.rst b/doc/contribute.rst index 127f92fca..8c39b1d37 100644 --- a/doc/contribute.rst +++ b/doc/contribute.rst @@ -11,9 +11,10 @@ Contributing ############ -The first step might be to use GHDL and explore its possibilities in your 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`. +As in many other free and open source projects, there are many areas requiring different skills where contributions to GHDL +are welcome. The first step might be to use GHDL and explore its possibilities in your own project. If you are new to VHDL, +see the :ref:`USING:QuickStart:Simulation` 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. If so, you might find :ref:`Implementation of VHDL <REF:ImplVHDL>` and :ref:`Implementation of VITAL <REF:ImplVITAL>` interesting. @@ -23,37 +24,32 @@ not covered. In order to improve GHDL, we welcome bug reports, suggestions, and GHDL. Whether 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. -Ideas for future work, enhancements, documentation, and internship programs are shown in the `GitHub wiki <https://github.com/ghdl/ghdl/wiki>`_. +Ideas for future work, enhancements, documentation, and internship programs are shown in the `GitHub wiki <https://github.com/ghdl/ghdl/wiki>`__. If you found no information on your topic, please, report so that we are aware! You can reach us through various ways: |SHIELD:gitter| or open a |SHIELD:issues-new|. .. HINT:: - Since the development of GHDL started in 2002, multiple platforms have been used as a support for both distribution - and getting feedback. However, the development is now centralized in GitHub. - -.. TIP:: - `How To Ask Questions The Smart Way <www.catb.org/~esr/faqs/smart-questions.html>`_ + * Since the development of GHDL started in 2002, multiple platforms have been used as a support for both distribution + and getting feedback. However, the development is now centralized in `github.com/ghdl <https://github.com/ghdl>`__. + * `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. 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 do not have - enough experience with them. +* If the compiler crashes, this is a bug. Reliable tools never crash. +* If the compiler emits an error message for a perfectly valid input or does not emit an error message for an invalid + input, this may be a bug. +* If the executable created from your VHDL sources crashes, this may be a bug at runtime or the code itself may be + wrong. 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 do not have + enough experience with them. +* It is suggested to test synthesis features with :option:`--synth`, before processing the design with :ref:`Synth:plugin`. -.. TIP:: - It is suggested to test synthesis features with :option:`--synth`, before processing the design with :ref:`Synth:plugin`. - -Please, report issues of this kind through |SHIELD:bug-report|, as this allows us to categorize issues into groups and -to assign developers to them. You can track the issue’s state and see how it’s getting solved. +Please, report issues through |SHIELD:bug-report|, as this allows us to categorize issues into groups and to assign developers +to them. You can track the state and see how it's getting solved. .. IMPORTANT:: As suggested in the bug report template, please elaborate a `Minimal (non) Working Example` (`MWE <https://en.wikipedia.org/wiki/Minimal_Working_Example>`_) @@ -64,16 +60,13 @@ to assign developers to them. You can track the issue’s state and see how it Also, please include enough information in the bug report, for the maintainers to reproduce the problem. The template includes: - * Operating system and version of GHDL (you can get it with :samp:`ghdl --version`). + * Operating system and version of GHDL (you can get it with :samp:`ghdl version` and :samp:`ghdl hash`). * Whether you have built GHDL from sources (provide short SHA of the used commit) or used the binary distribution - (note which release/tag). - - * If you cannot compile, please report which compiler you are using and the version. - - * Content of the input files which comprise the MWE + (note which release/tag); if you cannot compile, please report which compiler you are using and the version. + * Content of the input files which comprise 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. + * Comment explaining whether the MWE should compile or not; if yes, whether it should run until the assertion. * What you expect to happen and what you actually get. If you know the LRM well enough, please specify which paragraph might not be implemented well. * Samples of any log. @@ -81,7 +74,7 @@ to assign developers to them. You can track the issue’s state and see how it .. NOTE:: If you don't know the LRM, be aware that an issue claimed as a 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/>`_. + 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 variants 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. @@ -94,8 +87,8 @@ Requesting enhancements |SHIELD:feature-request| |SHIELD:gitter| All enhancements and feature requests are welcome. Please `open a new issue <https://github.com/ghdl/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. +to report any, so you can track the status and implementation. Depending on the complexity of the request, +you may want to `chat on Gitter <https://gitter.im/ghdl/ghdl1>`_, for polishing it before opening an issue. Improving the documentation =========================== @@ -104,8 +97,9 @@ If you found a mistake in the documentation, please send a comment. If you didn' 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`. +it is built automatically from `reStructuredText`, you can fork, modify and push. The documentation will be shown +in the GitHub Pages site of your fork: ``https://USERNAME.github.io/ghdl``. When you are done, request the maintainers +to pull your copy. See :ref:`pull_request`. .. _pull_request: @@ -119,16 +113,16 @@ Fork, modify and pull-request * 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. -Contributing source code/documentation via `Git <https://git-scm.com/>`_ is very easy. Although we don't provide direct +Contributing source code/documentation is done through `git <https://git-scm.com/>`__. 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: +`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, notify the maintainers by opening a `Pull Request <https://help.github.com/articles/creating-a-pull-request/>`_ (PR). +3. When you think that the changes are ready to be merged, 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 +5. Last, 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:: diff --git a/doc/development/CodingStyle.rst b/doc/development/CodingStyle.rst index a2fc554fd..02870c88c 100644 --- a/doc/development/CodingStyle.rst +++ b/doc/development/CodingStyle.rst @@ -199,7 +199,7 @@ Guidelines to edit the documentation ToC entry <file1> file2 - 7) Documentation should not use “you”, “we”, …, because it’s not an interactive conversation or informal letter. It’s like a thesis, everything is structured and formal. However, to make it more friendly to newcomers, we agree to allow informal language in the section :ref:`USING:QuickStart`. + 7) Documentation should not use “you”, “we”, …, because it’s not an interactive conversation or informal letter. It’s like a thesis, everything is structured and formal. However, to make it more friendly to newcomers, we agree to allow informal language in the Quick Start Guide. 8) Please keep errors to a minimum. diff --git a/doc/development/Directories.rst b/doc/development/Directories.rst new file mode 100644 index 000000000..fbe85f8ef --- /dev/null +++ b/doc/development/Directories.rst @@ -0,0 +1,31 @@ +.. _BUILD:dir_structure: + +Directory structure +################### + +* ``doc``: `reStructuredText` sources and auxiliary files to build the documentation with `Sphinx <http://www.sphinx-doc.org>`_. + A continuous integration (CI) workflow is used to automatically build and deploy this site and/or PDF you are reading. + +* ``libraries``: mostly third party libraries such as `ieee`, `std`, `synopsys` and `vital`. Except for a few shell and + `Python` scripts, all the content is written in VHDL. + +* ``logo``: Python and Gimp sources of the logo and the banners. + +* ``pyGHDL``: sources of the :mod:`Python Interfaces <pyGHDL>`. + +* ``scripts``: scripts and auxiliary files: + + * ``scripts/vendors``: Vendors like Altera, Lattice and Xilinx have their own simulation libraries, especially for FPGA + primitives, soft and hard macros. These libraries cannot 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. See :ref:`GETTING:PrecompVendor` for + information on how to use them. + + * ``scripts/gcc``: header and configuration files to build GHDL with GCC (all platforms). + + * ``scripts/msys2-*``: PKGBUILD recipes for building nightly GHDL packages on MSYS2. + + * ``scripts/pnodes*``: Python scripts for automatically generating some of the sources of :mod:`Python Interfaces <pyGHDL>`. + +* ``src``: sources of GHDL. Most of them are written in Ada, some in C. + +* ``testsuite``: files used for testing. diff --git a/doc/pyGHDL/index.rst b/doc/development/Scripts.rst index 76462fd63..85695358e 100644 --- a/doc/pyGHDL/index.rst +++ b/doc/development/Scripts.rst @@ -1,34 +1,13 @@ -Python Interfaces -################# - -.. toctree:: - :hidden: - - pyGHDL - -.. _CMDREF: - -Scripts and Applications -======================== - -The pyVHDLParser package comes with an executables registered by pip in the -search path. - -* ``VHDLParser`` is a wrapper for ``pyVHDLParser.CLI.VHDLParser:main``. +.. _DEV:Scripts: +Scripts +####### .. # This files requires a Python module called 'Frontend-AutoProgram' to be located in the 'doc' root folder. It expects a variable 'parser' of type ArgumentParser. -.. _CMDREF-ghdlls: - -.. autoprogram:: AutoProgram:lsp_parser - :prog: ghdl-ls - :groups: - :label: CmdRef:ghdlls: - .. _CMDREF-pnodes: .. autoprogram:: AutoProgram:pnodes_parser diff --git a/doc/getting/GCC.rst b/doc/development/building/GCC.rst index 7a8cd9b56..7a8cd9b56 100644 --- a/doc/getting/GCC.rst +++ b/doc/development/building/GCC.rst diff --git a/doc/getting/LLVM.rst b/doc/development/building/LLVM.rst index b8dde9735..b8dde9735 100644 --- a/doc/getting/LLVM.rst +++ b/doc/development/building/LLVM.rst diff --git a/doc/getting/Releases.rst b/doc/development/building/Sources.rst index 2a80d8591..523028961 100644 --- a/doc/getting/Releases.rst +++ b/doc/development/building/Sources.rst @@ -1,68 +1,7 @@ -.. _RELEASE: +.. _SOURCES: -Releases and sources -#################### - -.. contents:: Contents of this Page - :local: - -Using package managers -********************** - -Package managers of many popular distributions provide pre-built packages of GHDL. This is the case for `apt` -(Debian/Ubuntu), `dnf` (Fedora/CentOS) or `pacman` (Arch Linux). Since GHDL supports three different backends and two -library sets (_regular_ or GPL-compatible), at least six packages with different features might be available in each package -manager. See differences between backends in :ref:`BUILD`. - -.. _RELEASE:packages: - -Downloading pre-built packages -****************************** - -Assets from nightly GHDL builds are available at `github.com/ghdl/ghdl/releases/nightly <https://github.com/ghdl/ghdl/releases/nightly>`__. -These are mostly meant to be used in Continuous Integration (CI) workflows. Precisely, `setup-ghdl-ci <https://github.com/ghdl/setup-ghdl-ci>`__ -allows to easily setup nightly assets in GitHub Actions workflows. - -Furthermore, assets from stable builds are available for a larger set of platforms: - -.. TODO How to extend this directive to use `.. only:: html` and `.. only:: html` in the python code passed to it? - -.. exec:: - from helpers import createReleasesShields, printReleaseTab, printReleasesList - - # Optionally, provide a <tag> name to get the assets table of a specific release. By default, the table of 'latest' is returned. - data = createReleasesShields() - -.. only:: html - - .. exec:: - from helpers import printReleaseTab - printReleaseTab('data') - -.. only:: latex - - .. exec:: - from helpers import printReleaseTab - printReleaseTab('data', latex=True) - -.. rubric :: Pre-built packages of older releases - -.. only:: html - - .. exec:: - from helpers import printReleasesList - printReleasesList('data') - -.. only:: latex - - .. exec:: - from helpers import printReleasesList - printReleasesList('data', latex=True) - -.. _RELEASE:Sources: - -Downloading Source Files -************************ +Sources +####### .. HINT:: @@ -74,8 +13,7 @@ Downloading Source Files .. rubric :: Tarball/zip-file -GHDL can be downloaded as a zip-file or tarball from GitHub. See the following table, to -choose your desired format/version: +GHDL can be downloaded as a zip-file or tarball from GitHub. See the following table to choose your desired format/version: .. only:: html @@ -104,10 +42,9 @@ choose your desired format/version: .. rubric :: git clone -GHDL can be downloaded (cloned) with ``git clone`` from GitHub. GitHub offers -the transfer protocols HTTPS and SSH. You should use SSH if you have a GitHub -account and have already uploaded an OpenSSH public key to GitHub, otherwise -use HTTPS if you have no account or you want to use login credentials. +GHDL can be downloaded (cloned) with ``git clone`` from GitHub. GitHub offers the transfer protocols HTTPS and SSH. You should +use SSH if you have a GitHub account and have already uploaded an OpenSSH public key to GitHub, otherwise use HTTPS if you +have no account or you want to use login credentials. +----------+----------------------------------------+ | Protocol | GitHub Repository URL | @@ -141,7 +78,5 @@ Command line instructions to clone GHDL with SSH protocol: .. NOTE:: - Executing the following instructions in Windows Command Prompt (:program:`cmd.exe`) - won't function or will result in errors! All Windows command line instructions are - intended for :program:`Windows PowerShell`, if not marked otherwise. :program:`Windows PowerShell` - can be installed or upgraded to v5.1 by installing the `Windows Management Framework <https://docs.microsoft.com/en-us/powershell/wmf/5.1/install-configure>`_. + Executing the following instructions in Windows Command Prompt (:program:`cmd.exe`) won't function or will result in + errors! All Windows command line instructions are intended for :program:`Windows PowerShell`, if not marked otherwise. diff --git a/doc/getting/index.rst b/doc/development/building/index.rst index b256472b2..2c9f09d8d 100644 --- a/doc/getting/index.rst +++ b/doc/development/building/index.rst @@ -3,30 +3,31 @@ Building GHDL from Sources ########################## -.. rubric :: Download +.. toctree:: + :hidden: -GHDL can be downloaded as a `zip-file <https://github.com/ghdl/ghdl/archive/master.zip>`_/`tar-file <https://github.com/ghdl/ghdl/archive/master.tar.gz>`_ -(latest 'master' branch) or cloned with ``git clone`` from GitHub. GitHub -offers HTTPS and SSH as transfer protocols. See the :ref:`RELEASE:Sources` -page for further details. + Sources + mcode + LLVM + GCC + +GHDL can be downloaded as a `tarball <https://github.com/ghdl/ghdl/archive/master.tar.gz>`__/`zipfile <https://github.com/ghdl/ghdl/archive/master.zip>`__ +or cloned with ``git clone`` from GitHub. GitHub offers HTTPS and SSH as transfer protocols. See the :ref:`SOURCES` page for +further details. .. IMPORTANT:: - Since GHDL is written in `Ada`, independently of the code generator you use, - the a compiler is required. Most GNU/Linux package managers provide a package - named ``gcc-ada`` or ``gcc-gnat``. Alternatively, `GNU Ada compiler`, `GNAT GPL`, - can be downloaded anonymously from `libre.adacore.com <http://libre.adacore.com/tools/gnat-gpl-edition/>`_ (2014, or later; for x86, 32 or 64 bits). + Since GHDL is written in `Ada`, independently of the code generator you use, a compiler is required. Most GNU/Linux package + managers provide a package named ``gcc-ada`` or ``gcc-gnat``. Alternatively, `GNU Ada compiler`, `GNAT GPL`, can be downloaded + anonymously from `libre.adacore.com <http://libre.adacore.com/tools/gnat-gpl-edition/>`_ (2014, or later; for x86, 32 or 64 bits). Then, untar and run the doinstall script. .. ATTENTION:: - Since ``v0.37``, GHDL's synthesis features require GCC >=8.1, due to some new GNAT features which - are not available in previous releases. Users with older versions (who don't need synthesis) - can configure GHDL with option ``--disable-synth``. - -.. rubric :: Available back-ends + Since ``v0.37``, GHDL's synthesis features require GCC >=8.1, due to some new GNAT features which are not available in + previous releases. Users with older versions (who don't need synthesis) can configure GHDL with option ``--disable-synth``. GHDL currently supports three different back-ends (code generators): -* mcode - built-in x86 (or x86_64) code generator +* mcode - built-in in-memory x86 (or x86_64) code generator * GCC - Gnu Compiler Collection (`gcc.gnu.org <http://gcc.gnu.org/>`_) * LLVM - Low-Level Virtual Machine (`llvm.org <http://llvm.org/>`_) @@ -38,6 +39,7 @@ Here is a short comparison, so that you can choose the one you want to use: | :ref:`mcode <BUILD:mcode>` | * Very easy to build | * Simulation is slower | | | * Very quick analysis | * x86_64/i386 only | | | * Can handle very large designs | | +| | * Base simulation time can be modified for speeding up execution | | +----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+ | :ref:`LLVM <BUILD:llvm>` | * Generated code is faster | * Build is more complex than mcode | | | * Generated code can be debugged (with ``-g``) | | @@ -49,18 +51,9 @@ Here is a short comparison, so that you can choose the one you want to use: | | * Ported to many platforms (x86, x86_64, PowerPC, SPARC) | * Code coverage collection (``gcov``) is unique to GCC | +----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+ -.. toctree:: - :hidden: - - Directories - mcode - LLVM - 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 ``-r`` can - be replaced with direct execution of the binary. See section :ref:`USING:QuickStart`. + 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 ``-r`` can be replaced with direct execution of the binary. See section :ref:`USING:QuickStart:Simulation`. After making your choice, you can jump to the corresponding section. However, we suggest you to read :ref:`BUILD:dir_structure` first, so that you @@ -77,10 +70,37 @@ created. $ cd ghdl-objs $ ../path/to/ghdl/configure ... -.. HINT :: On Windows, building GHDL with mcode backend and GNAT GPL 32 bit seems to be the only way to get a standalone native executable. - - * MINGW/MSYS2 builds depend on the environment/runtime. +.. HINT :: + On Windows, building GHDL with mcode backend and GNAT GPL 32 bit seems to be the only way to get a standalone native + executable straightaway. MINGW/MSYS2 builds depend on the environment/runtime. See :ghdlsharp:`1560`. .. HINT :: - For MacOS 10.15 (Catalina), see `https://github.com/ghdl/ghdl/issues/1368` for - workarounds to link failures. + For MacOS 10.15 (Catalina), see :ghdlsharp:`1368` for workarounds to link failures. + +TL;DR +===== + +In order to follow the traditional way to ``configure`` and ``make``, you need an Ada compiler. + +.. HINT:: + Depending on the OS and distribution you are using, you will also need to install some toolchain dependencies, such as + ``zlib``. + +To use mcode backend (easiest to build), in the GHDL base directory, configure and build: + +.. code-block:: + + $ ./configure --prefix=/usr/local + $ make + +At that place, you can already use the `ghdl_mcode` built in the directory. You can also install GHDL: + +.. code-block:: + + $ make install + +That's all! + +.. HINT:: + The executable is installed as 'ghdl' in ``/usr/local``. To install it to a different path, change the ``--prefix`` in the + call to ``configure``. For example, on Windows, you may want to set it to ``--prefix=/c/Program Files (x86)/GHDL``. diff --git a/doc/getting/mcode.rst b/doc/development/building/mcode.rst index 9e46a29b6..9e46a29b6 100644 --- a/doc/getting/mcode.rst +++ b/doc/development/building/mcode.rst diff --git a/doc/getting/PrecompileVendorPrimitives.rst b/doc/getting.rst index aa322d3b7..4abab4530 100644 --- a/doc/getting/PrecompileVendorPrimitives.rst +++ b/doc/getting.rst @@ -1,7 +1,36 @@ +.. _PACKAGES: + +Getting | Installing +#################### + +Package managers +**************** + +Package managers of many popular distributions provide pre-built packages of GHDL. This is the case for `apt` +(Debian/Ubuntu), `dnf` (Fedora), `pacman` (Arch Linux, MSYS2) or `brew` (macOS). Since GHDL supports three different backends +and two library sets (*regular* or *GPL-compatible*), at least six packages with different features might be available in +each package manager. + +As a rule of thumb, mcode backend is the fastest for analysis and synthesis. It also allows setting the base simulation time +for speeding up execution. Therefore, it is the recommended pick if available on your platform (x86/amd64, on Windows x86 +only). On other platforms, or for using specific features for co-simulation or code coverage, LLVM or GCC need to be used. +See further differences between backends in :ref:`BUILD`. + +.. _RELEASE:packages: + +Nightly packages +**************** + +Assets from nightly GHDL builds are available at `github.com/ghdl/ghdl/releases/nightly <https://github.com/ghdl/ghdl/releases/nightly>`__. +These are mostly meant to be used in Continuous Integration (CI) workflows. Precisely, `setup-ghdl-ci <https://github.com/ghdl/setup-ghdl-ci>`__ +allows to easily setup nightly assets in GitHub Actions workflows. + +However, users on Windows (MSYS2) or Ubuntu might want to download the tarballs/zipfiles and extract/install them locally. + .. _GETTING:PrecompVendor: Precompile Vendor Primitives -############################ +**************************** Vendors like Lattice, Intel (Altera) and Xilinx have their own simulation libraries, especially for FPGA primitives, soft and hard macros. These libraries cannot @@ -11,10 +40,13 @@ are also popular simulation and verification libraries like OSVVM [#f1]_ or UVVM [#f2]_, which can be pre-compiled, too. The compilation scripts are writen in the shell languages: *PowerShell* for -*Windows™* and *Bash* for *GNU/Linux*, *MacOS*, *MSYS2*/*MinGW*. The +*Windows™* and *Bash* for *GNU/Linux*, *MacOS* and *MSYS2*/*MinGW*. The compile scripts can colorize the GHDL warning and error lines with the help of ``grc/grcat`` [#f4]_. +.. HINT:: + Vendor precompile scripts for OSVVM and UVVM are tested periodically in `ghdl/extended-tests <https://github.com/ghdl/extended-tests>`__. + Supported Vendors Libraries =========================== diff --git a/doc/getting/Directories.rst b/doc/getting/Directories.rst deleted file mode 100644 index 982dc4813..000000000 --- a/doc/getting/Directories.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. _BUILD:dir_structure: - -Directory structure -################### - -* ``src``: sources of GHDL, all of them in Ada. - -* ``libraries``: mostly third party libraries such as, `ieee`, - `std`, `synopsys` and `vital`. Except for a few shell and `Python` scripts, all - the content is written in VHDL. - - * Vendors like Altera, Lattice and Xilinx have their own simulation libraries, - especially for FPGA primitives, soft and hard macros. These libraries cannot - be shipped with GHDL, but we offer prepared compile scripts to - pre-compile the vendor libraries, if the vendor tool is present on the - computer. These are located in ``libraries/vendor``. - See :ref:`GETTING:PrecompVendor` for information on how to - use them. - -* ``dist``: scripts and auxiliary files to build GHDL in different - environments: - - * ``gcc``: header and configuration files to build GHDL with GCC (all - platforms). - * ``linux``: build and test script written in shell, and other auxiliary - files used to i) launch docker containers and ii) automate multiple builds - in `Travis CI <https://travis-ci.org/>`_. - - * ``windows``: - - * ``mcode``: - * ``appveyor``: - -* ``doc``: `Markdown` and `reStructuredText` sources and auxiliary files to - build the documentation with `Sphinx <http://www.sphinx-doc.org>`_. In fact, - `Read the Docs <http://readthedocs.org>`_ (RTD) is used to automatically build - and deploy this site and/or PDF you are reading. - -* ``testsuite``: files used for testing. - -* `.yml` configuration files for CI environments (``readthedocs``, - ``travis``, and ``appveyor``) and `ignore` files for source control - management tools (``git`` and ``.hg``). - -* Files for building GHDL: ``configure`` and ``Makefile.in``. - -* Auxiliary files for development: ``.gdbinit`` and ``ghdl.gpr.in`` - (GNAT project file). - -* Text files: ``COPYING.md``, ``NEWS.md``, and ``README.md``. diff --git a/doc/gnatdoc/index.rst b/doc/gnatdoc/index.rst index 3bd4d51f1..4f94c6f13 100644 --- a/doc/gnatdoc/index.rst +++ b/doc/gnatdoc/index.rst @@ -1,4 +1,4 @@ .. # This file is a placeholder and will be replaced -gnatdoc +GNATdoc ####### diff --git a/doc/helpers.py b/doc/helpers.py index 0e51be82f..9baddf700 100644 --- a/doc/helpers.py +++ b/doc/helpers.py @@ -1,5 +1,6 @@ from os.path import dirname, join import json +import re # Try to load JSON data from a file. If not found, use the argument as a tag name and retrieve the data from GitHub. def getJSON(tag='all'): @@ -18,62 +19,14 @@ def getJSON(tag='all'): return d # -# Functions to print table with format `[ [], [], [], ... ]` to reStructuredText -# - -# Print a row of data elements. -def printTabRow(l, r): - printTabItem(l, r, '| ') - -# Print a rule. Two characters in 'b' define the type of rule. Expected values are '+-', '+=' or '| '. -def printTabRule(l, b): - printTabItem(l, [b[1] for x in range(len(l))], b) - -# Print a full row, be it a rule or data. -# Extend the width of each field to the size specified in 'l'. -def printTabItem(l, a, b): - for y, z in enumerate(a): - print((b + z).ljust(l[y]+3, b[1]), end='') - print(b[0]) - -# Get number of cols from number of elements in row 0. -# Compute minimum number of characters required for each col. -def getTabColLens(t): - cl = [0 for _ in t[0]] - for row in t: - for y, z in enumerate(row): - cl[y] = max(cl[y], len(z)) - return cl - -# Print a table using the functions above. -# The first row contains the headers. -def printTab(t): - clens = getTabColLens(t) - - printTabRule(clens, '+-') - printTabRow(clens, t[0]) - printTabRule(clens, '+=') - for x in t[1:]: - printTabRow(clens, x) - printTabRule(clens, '+-') - print() - -# # Print two versions of each shield. Onee for 'html' (`image::`) and one for 'latex' (`replace::`) # -# Strip all non-alphanumeric characters when creating the labels -def stripLabel(label): - import re - pattern = re.compile('[\W_]+') - return pattern.sub('', label) - def printShieldSrc(label, alt, img, target, latex=False): if latex: - i = stripLabel(label) if label[-6:] == '/total': label = label[:-6] - print('.. |l' + i + '| replace:: `' + label + '`_') + print('.. |l' + re.compile('[\W_]+').sub('', label) + '| replace:: `' + label + '`_') print('.. _' + label + ': ' + target + '\n') else: print('.. |' + label + '| image:: '+ img + '\n', @@ -82,148 +35,6 @@ def printShieldSrc(label, alt, img, target, latex=False): ' :alt: ' + alt + '\n') # -# Display better OS and Backend names than those represented in the tarball name -# - -def prettyOS(i): - if i == 'fedora28': - return 'Fedora 28' - elif i == 'macosx': - return 'Max OS X' - elif i == 'mingw32': - return 'Windows x86 (MinGW32)' - elif i == 'mingw64': - return 'Windows x86 (MinGW64)' - elif i == 'stretch': - return 'Debian 9 (Stretch)' - elif i == 'gpl': - return 'Debian 9 (Stretch) GPL' - elif i == 'ubuntu14': - return '14.04 LTS (Trusty Tahr)' - return i - -def prettyBackend(i): - if i == 'llvm': - return 'LLVM' - if i == 'llvm-3.8': - return 'LLVM (3.8)' - return i - -# -# Get, extract and process JSON data to create the shields and table with the assets of a release -# - -def createTagShields(data='latest'): - if isinstance(data, str): - data = getJSON(data) - - assets=[['OS', 'Backend', 'Size', 'Downloads']] - tag = data['tag_name'] - for x in data['assets']: - name = x['name'] - s = [] - - p = 'ghdl-gpl-'+tag[1:] - if name[0:len(p)] == p: - s = ['gpl', 'mcode'] - - p = 'ghdl-'+tag[1:] - if name[0:len(p)] == p: - s = name[len(p)+1:-4].split('-',1) - - if len(s) > 1: - assets.append([ - prettyOS(s[0]), - prettyBackend(s[1]), - (str(round(x['size']/1024**2, 2))+' MB').rjust(8), - '|' + tag + '/' + name + '|'] - ) - - assets.append(['Sum:', '', '', '|'+tag+'/total|']) - - for x in assets[1:-1]: - i = x[3][1:-1] - for latex in [False, True]: - printShieldSrc(i, i, - 'https://img.shields.io/github/downloads/ghdl/ghdl/' + i + '?longCache=true&style=flat-square&logo=github&label=%7F', - 'https://github.com/ghdl/ghdl/releases/download/' + i, latex=latex) - - return assets - -# TODO: Is github.com/ghdl/ghdl/releases/download/<tag>/<file> subject to rate limit? Is there an alternative (not documented) domain? - - -# -# Get, extract and process JSON data to create the shields and list/table with all the releases except the latest -# - -def createReleasesShields(tag='latest'): - d = getJSON() - from dateutil.parser import parse as parseTime - releases = [['Date', 'Downloads']] - if tag == 'latest': - t = d[1] if d[0]['name'] == 'nightly' else d[0] - for x in d: - name = x['tag_name'] - if tag == name: - t = x - date = parseTime( x['published_at'] ).strftime("%Y-%m-%d") - releases.append([date, '|'+name+'/total|']) - i = name - for l in [False, True]: - printShieldSrc(i+'/total', i+' Total', - 'https://img.shields.io/github/downloads/ghdl/ghdl/' + i + '/total?longCache=true&style=flat-square&logo=github&label=%7F', - 'https://github.com/ghdl/ghdl/releases/' + i, l) - - out = {'releases': releases, 'assets': createTagShields(t)} - import json - json.dump(out, open('data.json', 'w'), indent=4) - return out - - -# -# Print the table with all the assets of a release/tag -# - -def printReleaseTab(assets, latex=False): - if isinstance(assets, str): - assets = getJSON(assets)["assets"] - - if latex: - for y, z in enumerate(assets[1:]): - assets[y+1] = z[0:3] + ['|l' + stripLabel(z[3][1:-1]) + '|'] - - printTab(assets) - -# -# Print list of releases, except the latest (second row) -# - -def printReleasesList(releases, latex=False): - if isinstance(releases, str): - releases = getJSON(releases)["releases"] - - rs = [releases[0]] - - for x, r in enumerate(releases): - if 'nightly' in r[1]: - releases.remove(r) - break - - rs.extend(releases[2:]) - - if latex: - rs[0] = ['Release/Tag'] + [rs[0][0]] - for x, r in enumerate(rs[1:]): - rs[x+1] = ['|l' + stripLabel(r[1][1:-1]) + '|'] + [r[0]] - else: - rs[0] = ['Release/Tag'] + rs[0] - for x, r in enumerate(rs[1:]): - rs[x+1] = [r[1][1:-7]] + r - - printTab(rs) - -# # Create shields/badges from JSON file # diff --git a/doc/index.rst b/doc/index.rst index f3ca031e4..a7a728a06 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -29,24 +29,38 @@ GHDL News **** + 31.01.2021 - GHDL v1.0.0rc1 was tagged + ====================================== + + * Python bindings were overhauled and renamed to ``pyGHDL``. Three modules are included: ``libghdl``, ``lsp`` and ``dom``. + + * The utility scripts in the codebase were moved into subdir ``scripts``: CI, binding generation, vendors, etc. + + * Repository `ghdl/extended-tests <https://github.com/ghdl/extended-tests>`__ was created for testing `vendors` build scripts. + + * The logo was updated (org, ghdl/ghdl, ghdl/docker and ghdl/ghdl-cosim). + + * Assets are not added to releases or pre-releases anymore. Users should use package managers or nightly assets. + 21.05.2020 - Nightly build assets available =========================================== - * After each successful CI run of branch ``master``, packages are published as assets of pre-release `nightly <https://github.com/ghdl/ghdl/releases/tag/nightly>`_. - * GitHub Action `ghdl/setup-ghdl-ci <https://github.com/ghdl/setup-ghdl-ci>`_ was created, to allow easy installation of nightly GHDL assets in GitHub Actions workflows. + * After each successful CI run of branch ``master``, packages are published as assets of pre-release `nightly <https://github.com/ghdl/ghdl/releases/tag/nightly>`__. + * GitHub Action `ghdl/setup-ghdl-ci <https://github.com/ghdl/setup-ghdl-ci>`__ was created, to allow easy installation of + nightly GHDL assets in GitHub Actions workflows. 09.05.2020 - New repositories and a wiki were created ===================================================== - * The plugin for Yosys was moved from `tgingold/ghdlsynth-beta <https://github.com/tgingold/ghdlsynth-beta>`_ to - `ghdl/ghdl-yosys-plugin <https://github.com/ghdl/ghdl-yosys-plugin>`_. - * Repository `ghdl/ghdl-cosim <https://github.com/ghdl/ghdl-cosim>`_ was created. It contains documentation and code - examples related to VHPIDIRECT, VPI and SystemC. See :ref:`COSIM` and `Previous work and future ideas <https://github.com/ghdl/ghdl-cosim/issues/1>`_. - * A `Wiki <https://github.com/ghdl/ghdl/wiki>`_ was created. The roadmap and ideas for documentation and internship - programs were moved there. If you want to contribute anyhow, `have a look <https://github.com/ghdl/ghdl/wiki>`_! + * The plugin for Yosys was moved from `tgingold/ghdlsynth-beta <https://github.com/tgingold/ghdlsynth-beta>`__ to + `ghdl/ghdl-yosys-plugin <https://github.com/ghdl/ghdl-yosys-plugin>`__. + * Repository `ghdl/ghdl-cosim <https://github.com/ghdl/ghdl-cosim>`__ was created. It contains documentation and code + examples related to VHPIDIRECT, VPI and SystemC. See :ref:`COSIM` and `Previous work and future ideas <https://github.com/ghdl/ghdl-cosim/issues/1>`__. + * A `Wiki <https://github.com/ghdl/ghdl/wiki>`__ was created. The roadmap and ideas for documentation and internship + programs were moved there. If you want to contribute anyhow, `have a look <https://github.com/ghdl/ghdl/wiki>`__! - 28.02.2020 - `GHDL v0.37 was released <https://github.com/ghdl/ghdl/milestone/8?closed=1>`_ - =========================================================================================== + 28.02.2020 - `GHDL v0.37 was released <https://github.com/ghdl/ghdl/milestone/8?closed=1>`__ + ============================================================================================ The major changes are: @@ -56,8 +70,8 @@ GHDL * Last version that supports the Mentor variation of std_logic_arith. The Synopsys one is still available. - 03.03.2019 - `GHDL v0.36 was released <https://github.com/ghdl/ghdl/milestone/7?closed=1>`_ - =========================================================================================== + 03.03.2019 - `GHDL v0.36 was released <https://github.com/ghdl/ghdl/milestone/7?closed=1>`__ + ============================================================================================ 23.02.2019 - GHDL v0.36-rc1 was released ======================================== @@ -73,21 +87,23 @@ GHDL 20.12.2017 - A new GitHub organization was created ================================================== - A new GitHub organization is created and the main repo is moved from `github.com/tgingold/ghdl <https://github.com/tgingold/ghdl>`_ to - `github.com/ghdl/ghdl <https://github.com/ghdl/ghdl>`_. Old refs will continue working, because permanent redirects are set up. However, we suggest + A new GitHub organization is created and the main repo is moved from `github.com/tgingold/ghdl <https://github.com/tgingold/ghdl>`__ to + `github.com/ghdl/ghdl <https://github.com/ghdl/ghdl>`__. Old refs will continue working, because permanent redirects are set up. However, we suggest every contributor to update the remote URLs in their local clones. - 14.12.2017 - `GHDL 0.35 was released <https://github.com/ghdl/ghdl/milestone/3?closed=1>`_ - ========================================================================================== + 14.12.2017 - `GHDL 0.35 was released <https://github.com/ghdl/ghdl/milestone/3?closed=1>`__ + =========================================================================================== - 15.08.2017 - `GHDL 0.34 was released <https://github.com/ghdl/ghdl/milestone/1?closed=1>`_ - ========================================================================================== + 15.08.2017 - `GHDL 0.34 was released <https://github.com/ghdl/ghdl/milestone/1?closed=1>`__ + =========================================================================================== 23.10.2015 - GHDL 0.33 was released =================================== .. only:: latex + .. rubric:: 31.01.2021 - GHDL v1.0.0rc1 was tagged. + .. rubric:: 21.05.2020 - Nightly build assets available. .. rubric:: 09.05.2020 - New repositories and a wiki were created. @@ -113,35 +129,23 @@ GHDL :hidden: about + getting contribute licenses .. raw:: latex - \part{Getting GHDL} - -.. toctree:: - :caption: Getting GHDL - :hidden: - - getting/Releases - Building GHDL <getting/index> - getting/PrecompileVendorPrimitives - -.. raw:: latex - - \part{GHDL usage} + \part{Usage} .. toctree:: :caption: GHDL usage :hidden: - quick_start/README + quick_start/index using/InvokingGHDL using/Simulation using/Synthesis using/CommandReference - Co-Simulation <https://ghdl.github.io/ghdl-cosim> using/ImplementationOfVHDL using/ImplementationOfVITAL @@ -153,10 +157,12 @@ GHDL :caption: Development :hidden: + development/Directories + Building GHDL <development/building/index> + Python Interfaces <pyGHDL/pyGHDL> development/Debugging development/CodingStyle - gnatdoc/index - pyGHDL/index + development/Scripts .. raw:: latex @@ -170,6 +176,7 @@ GHDL internals/Frontend internals/AST internals/RTI + gnatdoc/index .. raw:: latex diff --git a/doc/licenses.rst b/doc/licenses.rst index 76a8bf440..6247a3351 100644 --- a/doc/licenses.rst +++ b/doc/licenses.rst @@ -7,20 +7,24 @@ Copyrights | Licenses - 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 allowing access to the VHDL sources. Please, send a comment (:ref:`requesting_enhancements`) if you don't like this policy. + As a consequence of the runtime copyright, you are not allowed to distribute an executable produced by GHDL without allowing + access to the VHDL sources. 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): +The following packages are copyrighted by third parties (see corresponding sources for more information): - - These from library ``ieee`` are copyrighted by `Institute of Electrical and Electronics Engineers (IEEE) <https://www.ieee.org>`_ : +* These from library ``ieee`` are copyrighted by `Institute of Electrical and Electronics Engineers (IEEE) <https://www.ieee.org>`__: - - ``numeric_bit`` and ``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/>`_ ] - - ``std_logic_1164``, ``Math_Real`` and ``Math_Complex`` - - ``VITAL_Primitives``, ``VITAL_Timing`` and ``VITAL_Memory`` [see also `IEEE 1076.4 <http://ieeexplore.ieee.org/document/954750/>`_ ] + * Since December 2019, standard and IEEE libraries are distributed under Apache 2.0 and available at + `opensource.ieee.org/vasg/Packages <https://opensource.ieee.org/vasg/Packages>`__. GHDL includes backports of those + libraries for earlier revisions of the standard. + * ``VITAL_Primitives``, ``VITAL_Timing`` and ``VITAL_Memory`` are not include in the open source distribution of IEEE (see `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. +* 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. - - ``synopsys`` directory: ``std_logic_arith``, ``std_logic_signed``, ``std_logic_unsigned`` and ``std_logic_textio`` are copyrighted by `Synopsys, Inc. <https://www.synopsys.com/>`_ - - ``mentor`` directory: ``std_logic_arith`` is copyrighted by `Mentor Graphics <https://www.mentor.com>`_ + * ``synopsys`` directory: ``std_logic_arith``, ``std_logic_signed``, ``std_logic_unsigned`` and ``std_logic_textio`` are + copyrighted by `Synopsys, Inc. <https://www.synopsys.com/>`__ + * ``mentor`` directory: ``std_logic_arith`` is copyrighted by `Mentor Graphics <https://www.mentor.com>`__. .. _LIC:GPLv2: @@ -31,42 +35,42 @@ GHDL is copyright |copy| 2002 - 2021 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. +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: +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 endorse 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. +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. -Meißner, Torsten Property Specification Language (PSL): docs, tests, synthesis support -Martinez-Corral, Unai ghdl-cosim, setup-ghdl-ci, docs, docker/CI, termux/MSYS2 builds, building/testing on ARM -van Rantwijk, Joris Debian packaging -========================= ============================================================ +============================= =============================================================================================================== +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. +Meißner, Torsten Property Specification Language (PSL): docs, tests, synthesis support +Martinez-Corral, Unai [#f2]_ ghdl-cosim, setup-ghdl-ci, docs, docker/CI, MSYS2 packaging, building/testing on ARM, termux builds +van Rantwijk, Joris Debian packaging +============================= =============================================================================================================== .. only:: html @@ -76,7 +80,7 @@ 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 the late gna! website or `sourceforge.net/p/ghdl-updates/tickets <https://sourceforge.net/p/ghdl-updates/tickets/>`_. +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 the late gna! website or `sourceforge.net/p/ghdl-updates/tickets <https://sourceforge.net/p/ghdl-updates/tickets/>`__. -------------------------------------------------------------------------------- diff --git a/doc/quick_start/index.rst b/doc/quick_start/index.rst new file mode 100644 index 000000000..22c993855 --- /dev/null +++ b/doc/quick_start/index.rst @@ -0,0 +1,17 @@ +.. program:: ghdl +.. _USING:QuickStart: + +Quick Start Guide +################# + +Since this is the user and reference manual for `GHDL`, it does not contain an introduction to `VHDL`. Thus, the reader +should have at least a basic knowledge of `VHDL`. A good knowledge of `VHDL` language reference manual (usually called LRM) +is a plus. Nevertheless, multiple explained examples are provided, in the hope that they are useful for users to learn +about both `GHDL` and `VHDL`. + +.. toctree:: + :maxdepth: 2 + + simulation/index.rst + Co-Simulation <https://ghdl.github.io/ghdl-cosim> + python/index.rst diff --git a/doc/quick_start/python/index.rst b/doc/quick_start/python/index.rst new file mode 100644 index 000000000..83aea7db5 --- /dev/null +++ b/doc/quick_start/python/index.rst @@ -0,0 +1,33 @@ +.. program:: ghdl +.. _USING:QuickStart:Python: + +Python Interfaces +################# + +Currently, pyGHDL is not distributed through PyPI. Therefore, users need to install it from the git repository. However, the +version of the sources must be compatible with the installed version of GHDL (and the shared library ``libghdl``). +Installing from ``master`` is discouraged, because it might contain changes to the internal AST. Instead, ``ghdl version hash`` +allows getting the commit hash of the version the installed binary was built from. Since ``pip`` allows installing packages +by providing the URL to the git repo, this is the recommended installation procedure: + +.. code-block:: + + pip install git+https://github.com/ghdl/ghdl.git@$(ghdl version hash) + +.. _CMDREF: + +Language Server +*************** + +When installed through ``pip``, pyGHDL provides executable entrypoints registered in the search PATH, such as ``ghdl-ls``. + +.. # + This files requires a Python module called 'AutoProgram' to be located in the + 'doc' root folder. It expects a variable 'parser' of type ArgumentParser. + +.. _CMDREF-ghdlls: + +.. autoprogram:: AutoProgram:lsp_parser + :prog: ghdl-ls + :groups: + :label: CmdRef:ghdlls: diff --git a/doc/quick_start/DLXModelSuite.rst b/doc/quick_start/simulation/DLXModelSuite.rst index 0cdc8be86..0cdc8be86 100644 --- a/doc/quick_start/DLXModelSuite.rst +++ b/doc/quick_start/simulation/DLXModelSuite.rst diff --git a/doc/quick_start/adder/adder.vhdl b/doc/quick_start/simulation/adder/adder.vhdl index cf60e8fbe..cf60e8fbe 100644 --- a/doc/quick_start/adder/adder.vhdl +++ b/doc/quick_start/simulation/adder/adder.vhdl diff --git a/doc/quick_start/adder/adder_tb.vhdl b/doc/quick_start/simulation/adder/adder_tb.vhdl index 4a3fca5e4..4a3fca5e4 100644 --- a/doc/quick_start/adder/adder_tb.vhdl +++ b/doc/quick_start/simulation/adder/adder_tb.vhdl diff --git a/doc/quick_start/adder/README.rst b/doc/quick_start/simulation/adder/index.rst index 5ff607801..5ff607801 100644 --- a/doc/quick_start/adder/README.rst +++ b/doc/quick_start/simulation/adder/index.rst diff --git a/doc/quick_start/heartbeat/heartbeat.vhdl b/doc/quick_start/simulation/heartbeat/heartbeat.vhdl index 0a312641e..0a312641e 100644 --- a/doc/quick_start/heartbeat/heartbeat.vhdl +++ b/doc/quick_start/simulation/heartbeat/heartbeat.vhdl diff --git a/doc/quick_start/heartbeat/README.rst b/doc/quick_start/simulation/heartbeat/index.rst index e95145095..e95145095 100644 --- a/doc/quick_start/heartbeat/README.rst +++ b/doc/quick_start/simulation/heartbeat/index.rst diff --git a/doc/quick_start/hello/hello.vhdl b/doc/quick_start/simulation/hello/hello.vhdl index 4d969c6a8..4d969c6a8 100644 --- a/doc/quick_start/hello/hello.vhdl +++ b/doc/quick_start/simulation/hello/hello.vhdl diff --git a/doc/quick_start/hello/README.rst b/doc/quick_start/simulation/hello/index.rst index 104a12efa..104a12efa 100644 --- a/doc/quick_start/hello/README.rst +++ b/doc/quick_start/simulation/hello/index.rst diff --git a/doc/quick_start/README.rst b/doc/quick_start/simulation/index.rst index fc5f1a81a..8e41a453b 100644 --- a/doc/quick_start/README.rst +++ b/doc/quick_start/simulation/index.rst @@ -1,50 +1,52 @@ .. program:: ghdl -.. _USING:QuickStart: +.. _USING:QuickStart:Simulation: -Quick Start Guide -################# +Simulation +########## -Since this is the user and reference manual for `GHDL`, it does not contain an -introduction to `VHDL`. Thus, the reader should have at least a basic knowledge -of `VHDL`. A good knowledge of `VHDL` language reference manual (usually called -LRM) is a plus. Nevertheless, multiple examples are provided, in the hope that -they are useful for users to learn about both `GHDL` and `VHDL`. +As explained in :ref:`INTRO:GHDL`, `GHDL` is a compiler which translates `VHDL` +files to machine code. Hence, the regular workflow is composed of three steps: -As explained in :ref:`INTRO:GHDL`, `GHDL` is a compiler which translates `VHDL` files to -machine code. Hence, the regular workflow is composed of three steps: - -* :ref:`Analysis:command`: convert design units (`VHDL` sources) to an internal representation. -* :ref:`Elaboration:command`: generate executable machine code for a target module (top-level entity). -* :ref:`Run:command`: execute the design to test the behaviour, generate output/waveforms, etc. +* :ref:`Analysis:command`: convert design units (`VHDL` sources) to an internal + representation. +* :ref:`Elaboration:command`: generate executable machine code for a target module + (top-level entity). +* :ref:`Run:command`: execute the design to test the behaviour, generate + output/waveforms, etc. The following tips might be useful: * Don't forget to select the version of the VHDL standard you want to use (see - :ref:`VHDL_standards`). The default is :option:`--std=93c <--std>`. Use :option:`--std=08 <--std>` for VHDL-2008 - (albeit not fully implemented). + :ref:`VHDL_standards`). The default is :option:`--std=93c <--std>`. Use + :option:`--std=08 <--std>` for VHDL-2008 (albeit not fully implemented). - * Use :option:`--ieee=synopsys <--ieee>` if your design depends on a non-standard implementation of the IEEE library. + * Use :option:`--ieee=synopsys <--ieee>` if your design depends on a non-standard + implementation of the IEEE library. - * Use :option:`-fexplicit` and :option:`-frelaxed-rules` if needed. For instance, if you would like to use VHDL 2008 - and also use shared variables with an ordinary type (deprecated in VHDL 2000), you can use ``--std=08 -frelaxed-rules``. + * Use :option:`-fexplicit` and :option:`-frelaxed-rules` if needed. For instance, + if you would like to use VHDL 2008 and also use shared variables with an + ordinary type (deprecated in VHDL 2000), you can use ``--std=08 -frelaxed-rules``. * Use :option:`--work=LIB_NAME <--work>` to analyze files into the ``LIB_NAME`` library. To use files analyzed to a different directory, give the path to the ``LIB_NAME`` library using :option:`-P/path/to/name/directory/ <-P>`. -* Use the same options for analysis and elaboration. E.g., first analyse with ``ghdl -a --std=08 --work=mylib myfile.vhdl``; - and then elaborate and run with ``ghdl --elab-run --std=08 top``. +* Use the same options for analysis and elaboration. E.g., first analyse with + ``ghdl -a --std=08 --work=mylib myfile.vhdl``; and then elaborate and run with + ``ghdl --elab-run --std=08 top``. Due to the fact that `VHDL` is processed as a general purpose language (instead of an `HDL`), all the language features are to be supported. I.e., `VHDL` sources do not need to be limited to the synthesisable subset. However, distinction -between synthesisable and non-synthesisable (simulation-only) subsets is often misleading -for users who are new to the language. Different examples are provided, +between synthesisable and non-synthesisable (simulation-only) subsets is often +misleading for users who are new to the language. Different examples are provided, in the hope of helping understand the different use cases: .. toctree:: - hello/README - heartbeat/README - adder/README + hello/index + heartbeat/index + adder/index DLXModelSuite + +.. TIP:: See :ghdlissue:`Learning VHDL with GHDL <1291>`. diff --git a/testsuite/sanity/005examples/testsuite.sh b/testsuite/sanity/005examples/testsuite.sh index 7ce252fdb..7c708b2b9 100755 --- a/testsuite/sanity/005examples/testsuite.sh +++ b/testsuite/sanity/005examples/testsuite.sh @@ -8,7 +8,7 @@ if [ ! -d ../../../doc ]; then exit 0 fi -for d in ../../../doc/quick_start/*/; do +for d in ../../../doc/quick_start/simulation/*/; do cp "$d"*.vhdl ./ done |