From 75ef931f4a7a0a4f3ddca1727d6f63ea6f4d2482 Mon Sep 17 00:00:00 2001 From: umarcor Date: Tue, 5 Jan 2021 22:34:14 +0100 Subject: doc: reorganise and update --- README.md | 81 ++-- doc/about.rst | 80 ++-- doc/contribute.rst | 70 ++- doc/development/CodingStyle.rst | 2 +- doc/development/Directories.rst | 31 ++ doc/development/Scripts.rst | 23 + doc/development/building/GCC.rst | 75 ++++ doc/development/building/LLVM.rst | 43 ++ doc/development/building/Sources.rst | 82 ++++ doc/development/building/index.rst | 106 +++++ doc/development/building/mcode.rst | 74 ++++ doc/getting.rst | 490 +++++++++++++++++++++ doc/getting/Directories.rst | 50 --- doc/getting/GCC.rst | 75 ---- doc/getting/LLVM.rst | 43 -- doc/getting/PrecompileVendorPrimitives.rst | 458 ------------------- doc/getting/Releases.rst | 147 ------- doc/getting/index.rst | 86 ---- doc/getting/mcode.rst | 74 ---- doc/gnatdoc/index.rst | 2 +- doc/helpers.py | 193 +------- doc/index.rst | 77 ++-- doc/licenses.rst | 62 +-- doc/pyGHDL/index.rst | 44 -- doc/quick_start/DLXModelSuite.rst | 67 --- doc/quick_start/README.rst | 50 --- doc/quick_start/adder/README.rst | 36 -- doc/quick_start/adder/adder.vhdl | 14 - doc/quick_start/adder/adder_tb.vhdl | 57 --- doc/quick_start/heartbeat/README.rst | 42 -- doc/quick_start/heartbeat/heartbeat.vhdl | 20 - doc/quick_start/hello/README.rst | 53 --- doc/quick_start/hello/hello.vhdl | 17 - doc/quick_start/index.rst | 17 + doc/quick_start/python/index.rst | 33 ++ doc/quick_start/simulation/DLXModelSuite.rst | 67 +++ doc/quick_start/simulation/adder/adder.vhdl | 14 + doc/quick_start/simulation/adder/adder_tb.vhdl | 57 +++ doc/quick_start/simulation/adder/index.rst | 36 ++ .../simulation/heartbeat/heartbeat.vhdl | 20 + doc/quick_start/simulation/heartbeat/index.rst | 42 ++ doc/quick_start/simulation/hello/hello.vhdl | 17 + doc/quick_start/simulation/hello/index.rst | 53 +++ doc/quick_start/simulation/index.rst | 52 +++ testsuite/sanity/005examples/testsuite.sh | 2 +- 45 files changed, 1529 insertions(+), 1705 deletions(-) create mode 100644 doc/development/Directories.rst create mode 100644 doc/development/Scripts.rst create mode 100644 doc/development/building/GCC.rst create mode 100644 doc/development/building/LLVM.rst create mode 100644 doc/development/building/Sources.rst create mode 100644 doc/development/building/index.rst create mode 100644 doc/development/building/mcode.rst create mode 100644 doc/getting.rst delete mode 100644 doc/getting/Directories.rst delete mode 100644 doc/getting/GCC.rst delete mode 100644 doc/getting/LLVM.rst delete mode 100644 doc/getting/PrecompileVendorPrimitives.rst delete mode 100644 doc/getting/Releases.rst delete mode 100644 doc/getting/index.rst delete mode 100644 doc/getting/mcode.rst delete mode 100644 doc/pyGHDL/index.rst delete mode 100644 doc/quick_start/DLXModelSuite.rst delete mode 100644 doc/quick_start/README.rst delete mode 100644 doc/quick_start/adder/README.rst delete mode 100644 doc/quick_start/adder/adder.vhdl delete mode 100644 doc/quick_start/adder/adder_tb.vhdl delete mode 100644 doc/quick_start/heartbeat/README.rst delete mode 100644 doc/quick_start/heartbeat/heartbeat.vhdl delete mode 100644 doc/quick_start/hello/README.rst delete mode 100644 doc/quick_start/hello/hello.vhdl create mode 100644 doc/quick_start/index.rst create mode 100644 doc/quick_start/python/index.rst create mode 100644 doc/quick_start/simulation/DLXModelSuite.rst create mode 100644 doc/quick_start/simulation/adder/adder.vhdl create mode 100644 doc/quick_start/simulation/adder/adder_tb.vhdl create mode 100644 doc/quick_start/simulation/adder/index.rst create mode 100644 doc/quick_start/simulation/heartbeat/heartbeat.vhdl create mode 100644 doc/quick_start/simulation/heartbeat/index.rst create mode 100644 doc/quick_start/simulation/hello/hello.vhdl create mode 100644 doc/quick_start/simulation/hello/index.rst create mode 100644 doc/quick_start/simulation/index.rst diff --git a/README.md b/README.md index 66cbabc38..73d907fce 100644 --- a/README.md +++ b/README.md @@ -3,21 +3,25 @@

- - - - - +

+

'Test' workflow Status - + +

-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`).

Codecov - Branch Coverage

-- **[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 ` is an acronym for Very High Speed Integrated Circuit (:wikipedia:`VHSIC `) Hardware Description Language (:wikipedia:`HDL `), which is a programming language used to describe a logic circuit by function, data flow behavior, or structure. +:wikipedia:`VHDL ` is an acronym for Very High Speed Integrated Circuit (:wikipedia:`VHSIC `) Hardware Description +Language (:wikipedia:`HDL `), which is a programming language used to describe a logic circuit by function, data flow +behavior, or structure. -Although VHDL was not designed for writing general purpose programs, VHDL *is* a programming language, and you can write any algorithm with it. If you are able to write programs, you will find in VHDL features similar to those found in procedural languages such as `C`, `Python`, or `Ada`. Indeed, VHDL derives most of its syntax and semantics from Ada. Knowing `Ada` is an advantage for learning VHDL (it is an advantage in general as well). +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 `_ `1076`. Five revisions exist: `1987 `_, `1993 `_, `2002 `_, `2008 `_ and `2019 `_. The standardization is handled by the VHDL Analysis and Standardization Group (`VASG/P1076 `_). +The development of VHDL started in 1983 and the standard is named `IEEE `__ `1076`. Five revisions +exist: `1987 `__, `1993 `__, +`2002 `__, `2008 `__ and +`2019 `__. The standardization is handled by the VHDL Analysis and +Standardization Group (`VASG/P1076 `__). .. _INTRO:GHDL: What is GHDL? ============= -`GHDL` is a shorthand for `G Hardware Design Language` (currently, `G` has no meaning). It is a VHDL 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 `_, `LLVM `_ or :wikipedia:`x86 `/:wikipedia:`i386 ` only, a built-in one named *mcode*) and runs on :wikipedia:`GNU/Linux `, :wikipedia:`Windows ` |trade| and :wikipedia:`macOS ` |trade|; on x86, x86_64, armv6/armv7/aarch32/aarch64, etc. +GHDL can use multiple back-ends, i.e. code generators, (`GCC `__, `LLVM `__ or +:wikipedia:`x86 `/:wikipedia:`i386 ` only, a built-in one named *mcode*) and runs on :wikipedia:`GNU/Linux `, +:wikipedia:`Windows ` |trade| and :wikipedia:`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 `_, :wikipedia:`VCD ` or `FST` files can be produced, which can be viewed with a :wikipedia:`waveform viewer `, such as `GtkWave `_. +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 `__, +:wikipedia:`VCD ` or `FST` files can be produced, which can be viewed with a :wikipedia:`waveform viewer `, +such as `GtkWave `__. -GHDL aims at implementing VHDL as defined by `IEEE 1076 `_. It supports the `1987 `_, `1993 `_ and `2002 `_ revisions and, partially, `2008 `_. :wikipedia:`PSL ` is also partially supported. +GHDL aims at implementing VHDL as defined by `IEEE 1076 `__. It supports the +`1987 `__, `1993 `__ and +`2002 `__ revisions and, partially, `2008 `__. +:wikipedia:`Property Specification Language (PSL) ` is also partially supported. -Several third party projects are supported: `VUnit `_, `OSVVM `_, `cocotb `_ (through the `VPI interface `_), ... +Several third party projects are supported: `Yosys `__ (through the `ghdl-yosys-plugin `__) +`cocotb `__ (through the `VPI interface `__), +`VUnit `__, `OSVVM `__, ... .. _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 `_ | A Vendor-Independent, Open-Source IP Core and Utility Library. | - +-------------------+--------------------+----------------------------------------------------+----------------------------------------------------------------+ - | |SHIELD:gh-vunit| | |SHIELD:doc-vunit| | `VUnit `_ | A unit testing framework for VHDL/SystemVerilog | - +-------------------+--------------------+----------------------------------------------------+----------------------------------------------------------------+ - | |SHIELD:gl-p1076| | |SHIELD:tw-p1076| | `IEEE P1076 WG `_ | IEEE P1076 Working Group [VASG] | - +-------------------+--------------------+----------------------------------------------------+----------------------------------------------------------------+ - | |SHIELD:gh-tce| | |SHIELD:doc-tce| | `TCE `_ | TTA-Based Co-Design Environment - an open-source ASIP toolset. | - +-------------------+--------------------+----------------------------------------------------+----------------------------------------------------------------+ + +-------------------+--------------------+-----------------------------------------------------+----------------------------------------------------------------+ + | Project hub | Documentation | Name | Brief description | + +===================+====================+=====================================================+================================================================+ + | |SHIELD:gh-poc| | |SHIELD:rtd-poc| | `PoC-Library `__ | A Vendor-Independent, Open-Source IP Core and Utility Library. | + +-------------------+--------------------+-----------------------------------------------------+----------------------------------------------------------------+ + | |SHIELD:gh-vunit| | |SHIELD:doc-vunit| | `VUnit `__ | A unit testing framework for VHDL/SystemVerilog | + +-------------------+--------------------+-----------------------------------------------------+----------------------------------------------------------------+ + | |SHIELD:gl-p1076| | |SHIELD:tw-p1076| | `IEEE P1076 WG `__ | IEEE P1076 Working Group [VASG] | + +-------------------+--------------------+-----------------------------------------------------+----------------------------------------------------------------+ + | |SHIELD:gh-tce| | |SHIELD:doc-tce| | `TCE `__ | 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 ` and :ref:`Implementation of VITAL ` 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 `_. +Ideas for future work, enhancements, documentation, and internship programs are shown in the `GitHub 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 `_ + * 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 `__. + * `How To Ask Questions The Smart Way `_ .. _reporting_bugs: Reporting bugs ============== -.. TIP:: - * If the compiler crashes, this is a bug. Reliable tools never crash. - * If the compiler emits an error message for a perfectly valid input or does not emit an error message for an invalid - input, this may be a bug. - * If the executable created from your VHDL sources crashes, this may be a bug at runtime or the code itself may be - wrong. 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 `_) @@ -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 `_. + according to it. GHDL aims at implementing VHDL as defined in `IEEE 1076 `__. However, some other tools allow constructs which do not fully follow the standard revisions. Therefore, comparisons with other VHDL 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 `_ -to report any, so you can track the request's status and implementation. Depending on the complexity of the request, -you may want to `chat on Gitter `_, to polish it before opening an issue. +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 `_, 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 `_ is very easy. Although we don't provide direct +Contributing source code/documentation is done through `git `__. Although we don't provide direct write access to our repositories, the project is hosted at GitHub, which follows a fork, edit and pull-request -`flow `_ . That is: +`flow `__ . That is: 1. Make a copy (`fork `_) of the project. 2. Do the changes you wish (edit, add, rename, move and/or delete). -3. When you think that the changes are ready to be merged, notify the maintainers by opening a `Pull Request `_ (PR). +3. When you think that the changes are ready to be merged, notify the maintainers by opening a `Pull Request `__ (PR). 4. The maintainers will review the proposed changes and will reply in the corresponding thread if any further modification is required. If so, you can keep adding commits to the same branch, and the PR will be automatically updated. -5. Last, the maintainers will merge your branch. You will be notified, the PR will be closed, and you'll be allowed to +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 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 `_. + 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 `. + +* ``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 `. + +* ``src``: sources of GHDL. Most of them are written in Ada, some in C. + +* ``testsuite``: files used for testing. diff --git a/doc/development/Scripts.rst b/doc/development/Scripts.rst new file mode 100644 index 000000000..85695358e --- /dev/null +++ b/doc/development/Scripts.rst @@ -0,0 +1,23 @@ +.. _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-pnodes: + +.. autoprogram:: AutoProgram:pnodes_parser + :prog: pnodes + :groups: + :label: CmdRef:pnodes: + +.. _CMDREF-pnodespy: + +.. autoprogram:: AutoProgram:pnodespy_parser + :prog: pnodespy + :groups: + :label: CmdRef:pnodespy: diff --git a/doc/development/building/GCC.rst b/doc/development/building/GCC.rst new file mode 100644 index 000000000..7a8cd9b56 --- /dev/null +++ b/doc/development/building/GCC.rst @@ -0,0 +1,75 @@ +.. _BUILD:gcc: + +GCC backend +########### + +.. TODO :: Instructions to build GHDL with GCC backend on Windows are not available yet. + +.. rubric:: Requirements + +* GCC (Gnu Compiler Collection) +* GNAT (Ada compiler for GCC) +* GCC source files. Download and untar the sources of version 4.9.x, 5.x, 6.x, 7.x, 8.x, 9.x or 10.x. + +.. HINT :: There are some dependencies for building GCC (``gmp``, ``mpfr`` and ``mpc``). If you have not installed them on your system, you can either build them manually or use the ``download_prerequisites`` script provided in the GCC source tree (recommended): ``cd /path/to/gcc/source/dir && ./contrib/download_prerequisites``. + +* First configure GHDL, specify GCC source directory and installation prefix (like ``/usr/local`` or ``/opt/ghdl``). +* Next, invoke ``make copy-sources`` to copy GHDL sources in the source directory. +* Then, configure GCC. The list of ``--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. +* Now, build and install GCC with ``make``. +* Last, build and install GHDL libraries. + +.. rubric:: Example: + +.. code-block:: Bash + + $ cd + $ mkdir build + $ cd build + $ ../configure --with-gcc=/path/to/gcc/source/dir --prefix=/usr/local + $ make copy-sources + $ mkdir gcc-objs; cd gcc-objs + $ /path/to/gcc/source/dir/configure --prefix=/usr/local --enable-languages=c,vhdl \ + --disable-bootstrap --disable-lto --disable-multilib --disable-libssp \ + --disable-libgomp --disable-libquadmath + $ make -j2 && make install + $ cd /path/to/ghdl/source/dir/build + $ make ghdllib + $ make install + +.. HINT :: Note that the prefix directory to configure ``gcc`` 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``. + +.. HINT :: If your system gcc was configured with ``--enable-default-pie`` (check if that option appears in the output of ``gcc -v``), you should also add it. + +.. HINT :: If you don't want to install ``makeinfo``, do ``make install MAKEINFO=true`` instead. + +.. HINT :: 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 install.vpi.local # Locally install vpi files + + In ``src/ortho/gcc``, create a ``Makefile.conf`` file that sets the following + variables: + + .. CODE:: Bash + + AGCC_GCCSRC_DIR=/path/to/gcc/sources + AGCC_GCCOBJ_DIR=/path/to/gcc/build + + If your system gcc was built with ``--enable-default-pie``, add + ``-no-pie`` option for linking. + +.. HINT :: For ppc64/ppc64le platform, the object file format contains an identifier for the source language. Because gcc doesn't know about VHDL, gcc crashes very early. This could be fixed with a very simple change in ``gcc/config/rs6000/rs6000.c`` (``gcc/config/rs6000/rs6000-logue.c`` since gcc 10), function ``rs6000_output_function_epilogue``: + + .. CODE:: diff + + || ! strcmp (language_string, "GNU GIMPLE") + || ! strcmp (language_string, "GNU Go") + || ! strcmp (language_string, "GNU D") + - || ! strcmp (language_string, "libgccjit")) + + || ! strcmp (language_string, "libgccjit") + + || ! strcmp (language_string, "vhdl")) + i = 0; diff --git a/doc/development/building/LLVM.rst b/doc/development/building/LLVM.rst new file mode 100644 index 000000000..b8dde9735 --- /dev/null +++ b/doc/development/building/LLVM.rst @@ -0,0 +1,43 @@ +.. _BUILD:llvm: + +LLVM backend +############ + +.. rubric:: Requirements + +* GCC (Gnu Compiler Collection) +* GNAT (Ada compiler for GCC) +* LLVM (Low-Level-Virtual Machine) and CLANG (Compiler front-end for LLVM): 3.5, 3.8, 3.9, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0 or 11.0 + +.. _BUILD:llvm:GNAT: + +GCC/GNAT: GNU/Linux or Windows (MinGW/MSYS2) +============================================ + +.. HINT:: You need to install LLVM (usually depends on ``libedit``, see :ghdlsharp:`29`). Debugging is supported with LLVM 3.5 or ``>=6``. + +GHDL is configured by ``configure`` and built by ``make``. + +* First, GHDL needs to be configured. It is common to specify a ``PREFIX`` + (installation directory like ``/usr/local`` or ``/opt/ghdl``). Set the proper + arg, ``./configure --with-llvm-config``, to select LLVM backend. If + ``llvm-config`` is not in your path, you can specify it: + ``./configure --with-llvm-config=LLVM_INSTALL/bin/llvm-config``. + +* Next, ``make`` starts the compilation process. + +* Finally, ``make install`` installs GHDL into the installation directory + specified by ``PREFIX``. + +.. rubric:: Example: + +.. code-block:: Bash + + $ cd + $ mkdir build + $ cd build + $ ../configure --with-llvm-config --prefix=PREFIX + $ make + $ make install + +.. HINT:: 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). Then add the following arg to configure: ``--with-backtrace-lib=/path-to-gcc-build/libbacktrace/.libs/libbacktrace.a`` diff --git a/doc/development/building/Sources.rst b/doc/development/building/Sources.rst new file mode 100644 index 000000000..523028961 --- /dev/null +++ b/doc/development/building/Sources.rst @@ -0,0 +1,82 @@ +.. _SOURCES: + +Sources +####### + +.. HINT:: + + All the following procedures will retrieve the latest development version of GHDL, i.e., the `master` branch at + `github.com/ghdl/ghdl `_. We do our best to keep it stable, but bugs can seldom be + published. See `HINT` boxes below for instructions to get older releases. + +.. _RELEASE:Sources:Zip: + +.. 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: + +.. only:: html + + .. |zip-master| image:: https://img.shields.io/badge/ZIP-archive/master-323131.svg?longCache=true&style=flat-square&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAMAAABEpIrGAAACE1BMVEUAAAAAAABcXFwAAACpqakAAABXV1cAAAAAAADAwMBYWFgAAACcnJxzc3MiIiKPj4%2FExMRaWlohISHo6OgbGxs5OTnMzMw9PT3AwMBWVlZkZGSGhoanp6eLi4vMzMyAgIC3t7eUlJSysrKNjY2Wlparq6uysrKlpaW1tbV6enqzs7PR0dGrq6uEhISwsLDFxcW9vb3Kysrg4OC8vLy3t7fPz8%2FDw8Ojo6OsrKzS0tLQ0NC9vb3ExMTm5ua9vb3Q0NChoaGsrKyurq7e3t7U1NSWlpaJiYmNjY3R0dG0tLSVlZXCwsK8vLzDw8Ph4eHk5OTW1tbW1tbm5ube3t7g4ODKysq3t7fOzs7f39%2FW1tbR0dHOzs7CwsLe3t7c3Nzn5%2BfW1tbq6urIyMjb29vW1tbe3t7X19fa2trb29vt7e3q6urHx8ft7e3k5OTh4eHPz8%2FV1dXT09Pm5ubh4eHg4ODm5ub9%2Ff3%2F%2F%2F%2F%2F%2F%2F%2Fk5OTp6enY2Njo6OjZ2dnn5%2Bfp6enc3Nzu7u76%2Bvr09PTk5OTw8PDn5%2Bf5%2Bfnf39%2Fq6urg4ODo6Ojk5OT4%2BPjm5ubm5ubs7Ozu7u76%2Bvrk5OTu7u739%2Ffq6urr6%2Bvx8fH6%2Bvrt7e34%2BPj6%2Bvr%2B%2Fv7s7Oz5%2Bfn%2B%2Fv7%2F%2F%2F%2Fp6enr6%2Bvt7e3v7%2B%2Fx8fHy8vLz8%2FP09PT29vb39%2Ff5%2Bfn8%2FPz9%2Ff3%2B%2Fv7%2F%2F%2F9qYR%2FuAAAAonRSTlMAAQECAgMDBAYGBwgKCwwMDQ4SEhQUGhwdHiIjIyQkJygpMDIzMzQ1NTY3OTo8PDw%2FP0ZITk9RUlNTVldXV1hYWlpaWltdYGBiY2ZpbHB1dXZ3d3t8fX5%2Ff4aHiIqKj5WXn6KjpKmssrK0t7u8vb7BwsPEyszNzc3O0dLT09fY2tvf4OXm5ufn6ers7O3w8fLy8vL09fX29%2Ff4%2Bvv7%2FP39%2Ff5qibsTAAABrElEQVR4AX2LhfcSURCFBxHBbkWxuwW7Q7AbQ7AbuwMMRQxRVAwMxRBWBRSX%2BRN%2F97y3y9ldlv3OmfPu3PkemfBsVbaQAwsrzPxnLrVh4huc65h3I8iGno9walyj6wzu9CIrVxk86YvU%2BxVS6SKZOP4D5ccxJJnxHtvnvdRk10sUlUVEJy4NFIV33d8S89P1JJj3GOfaDqQlG4%2BcX7tdlL6DKtr7UwgwuOwRdY85h08vuD1A5MFnGEgB7OlGkg0XZj5bPFXEcW91oQHj37Iu0uh%2BYNqXlZtFvKkLN%2FZ9g%2FJ7Qiep9JutjD25AiGpC0nqehZG4%2BEQaXQe%2BX3oUbNA1P8uFPWWTyqzPo2yCGDSAyj%2FT4ncZ%2F%2FzFgEs%2FwClQmDptvk2AtjJsht275C9QJqwevIxZ2ETf3UWrjBPdxR%2B7V6zykkYfY5ek0HIWIXx%2FGIQnowucC1mFmg4JlbTlngRoRw2CiBcRizGSZCoY8mHDEIoj1BPUJOUiiLr1wR%2FFo%2BaIiPeHIO0ENIMcl6yECig%2FqlNIUCtuIMKS5Sgm2xxRao4VyMuaos7qkQtvzsAWpTtdh6JoYQAAAAASUVORK5CYII%3D + :target: https://github.com/ghdl/ghdl/archive/master.zip + :alt: Source Code from GitHub - 'master' branch. + + .. |tgz-master| image:: https://img.shields.io/badge/TGZ-archive/master-323131.svg?longCache=true&style=flat-square&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAMAAABEpIrGAAACE1BMVEUAAAAAAABcXFwAAACpqakAAABXV1cAAAAAAADAwMBYWFgAAACcnJxzc3MiIiKPj4%2FExMRaWlohISHo6OgbGxs5OTnMzMw9PT3AwMBWVlZkZGSGhoanp6eLi4vMzMyAgIC3t7eUlJSysrKNjY2Wlparq6uysrKlpaW1tbV6enqzs7PR0dGrq6uEhISwsLDFxcW9vb3Kysrg4OC8vLy3t7fPz8%2FDw8Ojo6OsrKzS0tLQ0NC9vb3ExMTm5ua9vb3Q0NChoaGsrKyurq7e3t7U1NSWlpaJiYmNjY3R0dG0tLSVlZXCwsK8vLzDw8Ph4eHk5OTW1tbW1tbm5ube3t7g4ODKysq3t7fOzs7f39%2FW1tbR0dHOzs7CwsLe3t7c3Nzn5%2BfW1tbq6urIyMjb29vW1tbe3t7X19fa2trb29vt7e3q6urHx8ft7e3k5OTh4eHPz8%2FV1dXT09Pm5ubh4eHg4ODm5ub9%2Ff3%2F%2F%2F%2F%2F%2F%2F%2Fk5OTp6enY2Njo6OjZ2dnn5%2Bfp6enc3Nzu7u76%2Bvr09PTk5OTw8PDn5%2Bf5%2Bfnf39%2Fq6urg4ODo6Ojk5OT4%2BPjm5ubm5ubs7Ozu7u76%2Bvrk5OTu7u739%2Ffq6urr6%2Bvx8fH6%2Bvrt7e34%2BPj6%2Bvr%2B%2Fv7s7Oz5%2Bfn%2B%2Fv7%2F%2F%2F%2Fp6enr6%2Bvt7e3v7%2B%2Fx8fHy8vLz8%2FP09PT29vb39%2Ff5%2Bfn8%2FPz9%2Ff3%2B%2Fv7%2F%2F%2F9qYR%2FuAAAAonRSTlMAAQECAgMDBAYGBwgKCwwMDQ4SEhQUGhwdHiIjIyQkJygpMDIzMzQ1NTY3OTo8PDw%2FP0ZITk9RUlNTVldXV1hYWlpaWltdYGBiY2ZpbHB1dXZ3d3t8fX5%2Ff4aHiIqKj5WXn6KjpKmssrK0t7u8vb7BwsPEyszNzc3O0dLT09fY2tvf4OXm5ufn6ers7O3w8fLy8vL09fX29%2Ff4%2Bvv7%2FP39%2Ff5qibsTAAABrElEQVR4AX2LhfcSURCFBxHBbkWxuwW7Q7AbQ7AbuwMMRQxRVAwMxRBWBRSX%2BRN%2F97y3y9ldlv3OmfPu3PkemfBsVbaQAwsrzPxnLrVh4huc65h3I8iGno9walyj6wzu9CIrVxk86YvU%2BxVS6SKZOP4D5ccxJJnxHtvnvdRk10sUlUVEJy4NFIV33d8S89P1JJj3GOfaDqQlG4%2BcX7tdlL6DKtr7UwgwuOwRdY85h08vuD1A5MFnGEgB7OlGkg0XZj5bPFXEcW91oQHj37Iu0uh%2BYNqXlZtFvKkLN%2FZ9g%2FJ7Qiep9JutjD25AiGpC0nqehZG4%2BEQaXQe%2BX3oUbNA1P8uFPWWTyqzPo2yCGDSAyj%2FT4ncZ%2F%2FzFgEs%2FwClQmDptvk2AtjJsht275C9QJqwevIxZ2ETf3UWrjBPdxR%2B7V6zykkYfY5ek0HIWIXx%2FGIQnowucC1mFmg4JlbTlngRoRw2CiBcRizGSZCoY8mHDEIoj1BPUJOUiiLr1wR%2FFo%2BaIiPeHIO0ENIMcl6yECig%2FqlNIUCtuIMKS5Sgm2xxRao4VyMuaos7qkQtvzsAWpTtdh6JoYQAAAAASUVORK5CYII%3D + :target: https://github.com/ghdl/ghdl/archive/master.tar.gz + :alt: Source Code from GitHub - 'master' branch. + + +----------+------------------------+ + | Branch | Download Link | + +==========+========================+ + | master | |zip-master| | + +----------+------------------------+ + | master | |tgz-master| | + +----------+------------------------+ + +.. HINT:: + + To download a specific version of GHDL, use this alternative URL, where ```` is ``tar.gz`` or ``zip``: + ``https://codeload.github.com/ghdl/ghdl//``. + +.. _RELEASE:Sources:GitClone: + +.. 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. + ++----------+----------------------------------------+ +| Protocol | GitHub Repository URL | ++==========+========================================+ +| HTTPS | https://github.com/ghdl/ghdl.git | ++----------+----------------------------------------+ +| SSH | ssh://git@github.com:ghdl/ghdl.git | ++----------+----------------------------------------+ + +.. HINT:: + + Execute ``git checkout -b stable `` after ``git clone``, to checkout a specific version of GHDL. + +Command line instructions to clone GHDL with HTTPS protocol: + +.. code-block:: Bash + + cd GitRoot + git clone "https://github.com/ghdl/ghdl.git" ghdl + cd ghdl + git remote rename origin github + +Command line instructions to clone GHDL with SSH protocol: + +.. code-block:: Bash + + cd GitRoot + git clone "ssh://git@github.com:ghdl/ghdl.git" ghdl + cd ghdl + git remote rename origin github + +.. 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. diff --git a/doc/development/building/index.rst b/doc/development/building/index.rst new file mode 100644 index 000000000..2c9f09d8d --- /dev/null +++ b/doc/development/building/index.rst @@ -0,0 +1,106 @@ +.. _BUILD: + +Building GHDL from Sources +########################## + +.. toctree:: + :hidden: + + Sources + mcode + LLVM + GCC + +GHDL can be downloaded as a `tarball `__/`zipfile `__ +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, 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 `_ (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``. + +GHDL currently supports three different back-ends (code generators): + +* mcode - built-in in-memory x86 (or x86_64) code generator +* GCC - Gnu Compiler Collection (`gcc.gnu.org `_) +* LLVM - Low-Level Virtual Machine (`llvm.org `_) + +Here is a short comparison, so that you can choose the one you want to use: + ++----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+ +| Back-end | Pros | Cons | ++============================+============================================================================+=========================================================+ +| :ref:`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 ` | * Generated code is faster | * Build is more complex than mcode | +| | * Generated code can be debugged (with ``-g``) | | +| | * Easier to build than GCC | | +| | * Ported to many platforms (x86, x86_64, armv7/aarch64) | | ++----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+ +| :ref:`GCC ` | * Generated code is faster (particularly with ``-O`` or ``-O2``) | * Build is even more complex | +| | * Generated code can be debugged (with ``-g``) | * Analysis can take time (particularly for large units) | +| | * Ported to many platforms (x86, x86_64, PowerPC, SPARC) | * Code coverage collection (``gcov``) is unique to 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: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 +know where the content will be placed and which files are expected to be +created. + +.. HINT :: + In these instructions, the configure script is executed in the source directory; but you can execute in a different + directory too, like this: + + .. CODE:: Bash + + $ mkdir ghdl-objs + $ 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 straightaway. MINGW/MSYS2 builds depend on the environment/runtime. See :ghdlsharp:`1560`. + +.. HINT :: + 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/development/building/mcode.rst b/doc/development/building/mcode.rst new file mode 100644 index 000000000..9e46a29b6 --- /dev/null +++ b/doc/development/building/mcode.rst @@ -0,0 +1,74 @@ +.. _BUILD:mcode: + +mcode backend +############# + +The mcode backend is available for all supported platforms and is also the +simplest procedure, because it requires the fewest dependencies and configuration +options. + +.. _BUILD:mcode:GNAT: + +GCC/GNAT: GNU/Linux or Windows (MinGW/MSYS2) +============================================ + +.. rubric:: Requirements + +* GCC (Gnu Compiler Collection) +* GNAT (Ada compiler for GCC) + +GHDL is configured by ``configure`` and built by ``make``. + +* First, GHDL needs to be configured. It is common to specify a ``PREFIX`` + (installation directory like ``/usr/local`` or ``/opt/ghdl``). Without any + other option, ``configure`` selects `mcode` as the backend. + +* Next, ``make`` starts the compilation process. + +* Finally, ``make install`` installs GHDL into the installation directory + specified by ``PREFIX``. + +.. HINT :: ON GNU/Linux, you may need super user privileges (``sudo ...``). + + +.. rubric:: Example: + +.. code-block:: Bash + + $ cd + $ mkdir build + $ cd build + $ ../configure --prefix=PREFIX + $ make + $ make install + +.. _BUILD:mcode:GNATGPL-Windows: + +GNAT GPL: Windows +================= + +.. rubric:: Requirements + +* GNAT GPL from http://libre.adacore.com +* PowerShell 4 +* PowerShell Community Extensions (PSCX) + +.. rubric:: `compile.ps1` + +.. code-block:: + + Commands Description + -------------------------------------------------------------------- + -Help Display the integrated help pages + -Clean Clean up all files and directories + -Compile Compile GHDL + -Install Install all files into a directory (xcopy deployment) + -Uninstall Uninstall all files from a directory + -Update Update files in the installation directory + -CreatePackage create an installer package + + Install options: + -InstallPath Installation directory + + CreatePackage options: + -Zip Create a zip-file for xcopy deployment diff --git a/doc/getting.rst b/doc/getting.rst new file mode 100644 index 000000000..4abab4530 --- /dev/null +++ b/doc/getting.rst @@ -0,0 +1,490 @@ +.. _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 `__. +These are mostly meant to be used in Continuous Integration (CI) workflows. Precisely, `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 +be shipped with GHDL, but GHDL offers prepared compile scripts to pre-compile +these vendor libraries, if the vendor tool is present in the environment. There +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* 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 `__. + +Supported Vendors Libraries +=========================== + +* Lattice (3.6 or later): + + * ``ec`` + * ``ecp``, ``ecp2``, ``ecp3``, ``ecp5u`` + * ``lptm``, ``lptm2`` + * ``machxo``, ``machxo2``, ``machxo3l``, ``machxo3d`` + * ``sc``, ``scm`` + * ``xp``, ``xp2`` + * ... + +* Intel (Altera) Quartus (13.0 or later): + + * ``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`` + * ... + +* Xilinx ISE (14.0 or later): + + * ``unisim`` (incl. ``secureip``) + * ``unimacro`` + * ``simprim`` (incl. ``secureip``) + * ``xilinxcorelib`` + +* Xilinx Vivado (2014.1 or later): + + * ``unisim`` (incl. ``secureip``) + * ``unimacro`` + +Supported Simulation and Verification Libraries +=============================================== + +* OSVVM [#f1]_ (for VHDL-2008) +* UVVM [#f2]_ (for VHDL-2008) + + +--------------------------------------------------------------------- + +Script Configuration +==================== + +The vendor library compile scripts need to know where the used / latest vendor +tool chain is installed. Therefore, the scripts implement a default installation +directory search as well as environment variable checks. If a vendor tool cannot +be detected or the script chooses the wrong vendor library source directory, +then it's possible to provide the path via ``--source`` (Bash) or ``-Source`` +(PoSh). + +The generated output is stored relative to the current working directory. The +scripts create a sub-directory for each vendor. The default output directory can +be overwritten by the parameter ``--output`` (Bash) or ``-Output`` (PoSh). + +To compile all source files with GHDL, the simulator executable is searched in +``PATH``. The found default GHDL executable can be overwritten by setting the +environment variable ``GHDL`` or by passing the parameter ``--ghdl`` (Bash) or +``-GHDL`` (PoSh) to the scripts. + +If the vendor library compilation is used very often, it's recommend to configure +these parameters in ``config.sh`` (Bash) or ``config.psm1`` (PoSh), so the command +line can be shortened to the essential parts. + +--------------------------------------------------------------------- + +Compiling in Bash +================= + +The provided Bash scripts support these environments: + +* Linux +* MacOS +* MSYS2 / MinGW +* WSL (Windows Subsystem for Linux) + + +Follow these steps: + +* **Step 0 - Configure the scripts (optional)** + + See the next section for how to configure ``config.sh``. + +* **Step 1 - Browse to your simulation working directory** + + .. code-block:: Bash + + $ cd + + +* **Step 2 - Start the compilation script(s)** + + Choose one or multiple of the following scripts to run the pre-compilation + process. + + .. code-block:: Bash + + $ /usr/local/lib/ghdl/vendors/compile-altera.sh --all + $ /usr/local/lib/ghdl/vendors/compile-intel.sh --all + $ /usr/local/lib/ghdl/vendors/compile-lattice.sh --all + $ /usr/local/lib/ghdl/vendors/compile-osvvm.sh --all + $ /usr/local/lib/ghdl/vendors/compile-uvvm.sh --all + $ /usr/local/lib/ghdl/vendors/compile-xilinx-ise.sh --all + $ /usr/local/lib/ghdl/vendors/compile-xilinx-vivado.sh --all + + + In most cases GHDL is installed into ``/usr/local/``. The scripts are + installed into the ``lib\ghdl\vendors`` directory. + +* **Step 3 - Viewing the result** + + This creates vendor directories in your current working directory and + compiles the vendor files into them. + + + .. code-block:: Bash + + $ ls -ahl + ... + drwxr-xr-x 2 56K Mar 09 17:41 altera + drwxr-xr-x 2 56K Mar 09 17:42 intel + drwxr-xr-x 2 56K Mar 09 17:42 lattice + drwxr-xr-x 2 56K Mar 09 17:48 osvvm + drwxr-xr-x 2 56K Mar 09 17:58 uvvm + drwxr-xr-x 2 56K Mar 09 17:58 xilinx-ise + drwxr-xr-x 2 56K Mar 09 17:48 xilinx-vivado + + + +--------------------------------------------------------------------- + +Compiling in PowerShell +======================= + +The provided PowerShell scripts support these environments: + +* Windows™ 10 (PowerShell 5 and PowerShell 6) + + +Follow these steps: + +* **Step 0 - Configure the scripts (optional)** + + See the next section for how to configure ``config.psm1``. + +* **Step 1 - Browse to your simulation working directory** + + .. code-block:: PowerShell + + PS> cd + +* **Step 2 - Start the compilation script(s)** + + Choose one or multiple of the following scripts to run the pre-compilation + process. + + .. code-block:: PowerShell + + PS> \lib\ghdl\vendors\compile-altera.ps1 -All + PS> \lib\ghdl\vendors\compile-intel.ps1 -All + PS> \lib\ghdl\vendors\compile-lattice.ps1 -All + PS> \lib\ghdl\vendors\compile-osvvm.ps1 -All + PS> \lib\ghdl\vendors\compile-uvvm.ps1 -All + PS> \lib\ghdl\vendors\compile-xilinx-ise.ps1 -All + PS> \lib\ghdl\vendors\compile-xilinx-vivado.ps1 -All + + .. # In most cases GHDL is installed into ``/usr/local/``. + + The scripts are installed into the ``lib\ghdl\vendors`` directory. + +* **Step 3 - Viewing the result** + + This creates vendor directories in your current working directory and + compiles the vendor files into them. + + .. code-block:: + + PS> dir + Directory: D:\temp\ghdl + + Mode LastWriteTime Length Name + ---- ------------- ------ ---- + d---- 09.03.2018 19:33 altera + d---- 09.03.2018 19:38 intel + d---- 09.03.2018 19:38 lattice + d---- 09.03.2018 19:38 osvvm + d---- 09.03.2018 19:45 uvvm + d---- 09.03.2018 19:06 xilinx-ise + d---- 09.03.2018 19:40 xilinx-vivado + + +--------------------------------------------------------------------- + +Configuration Files +=================== + +For Bash: `config.sh` +--------------------- + +Please open the ``config.sh`` file and set the dictionary entries for the +installed vendor tools to your tool's installation directories. Use an empty +string ``""`` for not installed tools. + +``config.sh``: + +.. code-block:: Bash + + declare -A InstallationDirectory + InstallationDirectory[AlteraQuartus]="/opt/Altera/16.0" + InstallationDirectory[IntelQuartus]="/opt/intelFPGA/20.1" + InstallationDirectory[LatticeDiamond]="/opt/Diamond/3.10_x64" + InstallationDirectory[OSVVM]="/home//git/GitHub/OSVVM" + InstallationDirectory[UVVM]="/home//git/GitHub/UVVM" + InstallationDirectory[XilinxISE]="/opt/Xilinx/14.7" + InstallationDirectory[XilinxVivado]="/opt/Xilinx/Vivado/2020.2" + + +For PowerShell: `config.psm1` +----------------------------- + +Please open the ``config.psm1`` file and set the dictionary entries for the +installed vendor tools to your tool's installation +folder. Use an empty string ``""`` for not installed tools. + +``config.psm1``: + +.. code-block:: PowerShell + + $InstallationDirectory = @{ + "AlteraQuartus" = "C:\Altera\16.0"; + "IntelQuartus" = "C:\Altera\20.1"; + "LatticeDiamond" = "C:\Lattice\Diamond\3.10_x64"; + "XilinxISE" = "C:\Xilinx\14.7\ISE_DS"; + "XilinxVivado" = "C:\Xilinx\Vivado\2020.2"; + "OSVVM" = "C:\git\GitHub\OSVVM"; + "UVVM" = "C:\git\GitHub\UVVM" + } + + +Additional Script Parameters +============================ + +Each script supports partial compilations e.g. of shared packages and +individual parts. In addition, the amount of printout to the console can be +controlled. Some scripts may offer vendor specific options. + + +For Bash Scripts: +----------------- + +* Common parameters to most scripts: + + .. code-block:: none + + --help, -h Print the embedded help page(s). + --clean, -c Cleanup directory before analyzing. + --no-warnings, -n Don't show warnings. Report errors only. + --skip-existing, -s Skip already compiled files (an *.o file exists). + --skip-largefiles, -S Don't compile large entities like DSP and PCIe primitives. + --halt-on-error, -H Stop compiling if an error occurred. + +* ``compile-altera.sh`` + + Selectable libraries: + + .. code-block:: none + + --all, -a Compile all libraries, including common libraries, packages and device libraries. + --altera Compile base libraries like 'altera' and 'altera_mf' + --max Compile device libraries for Max CPLDs + --arria Compile device libraries for Arria FPGAs + --cyclone Compile device libraries for Cyclone FPGAs + --stratix Compile device libraries for Stratix FPGAs + + Compile options: + + .. code-block:: none + + --vhdl93 Compile selected libraries with VHDL-93 (default). + --vhdl2008 Compile selected libraries with VHDL-2008. + +* ``compile-xilinx-ise.sh`` + + Selectable libraries: + + .. code-block:: none + + --all, -a Compile all libraries, including common libraries, packages and device libraries. + --unisim Compile the unisim primitives + --unimacro Compile the unimacro macros + --simprim Compile the simprim primitives + --corelib Compile the xilinxcorelib macros + --secureip Compile the secureip primitives + + Compile options: + + .. code-block:: none + + --vhdl93 Compile selected libraries with VHDL-93 (default). + --vhdl2008 Compile selected libraries with VHDL-2008. + +* ``compile-xilinx-vivado.sh`` + + Selectable libraries: + + .. code-block:: none + + --all, -a Compile all libraries, including common libraries, packages and device libraries. + --unisim Compile the unisim primitives + --unimacro Compile the unimacro macros + --secureip Compile the secureip primitives + + Compile options: + + .. code-block:: none + + --vhdl93 Compile selected libraries with VHDL-93 (default). + --vhdl2008 Compile selected libraries with VHDL-2008. + +* ``compile-osvvm.sh`` + + Selectable libraries: + + .. code-block:: none + + --all, -a Compile all. + --osvvm Compile the OSVVM library. + +* ``compile-uvvm.sh`` + + Selectable libraries: + + .. code-block:: none + + --all, -a Compile all. + --uvvm Compile the UVVM libraries. + + +For PowerShell Scripts: +----------------------- + +* Common parameters to all scripts: + + .. code-block:: none + + -Help Print the embedded help page(s). + -Clean Cleanup directory before analyzing. + -SuppressWarnings Don't show warnings. Report errors only. + +* ``compile-altera.ps1`` + + Selectable libraries: + + .. code-block:: none + + -All Compile all libraries, including common libraries, packages and device libraries. + -Altera Compile base libraries like 'altera' and 'altera_mf' + -Max Compile device libraries for Max CPLDs + -Arria Compile device libraries for Arria FPGAs + -Cyclone Compile device libraries for Cyclone FPGAs + -Stratix Compile device libraries for Stratix FPGAs + + Compile options: + + .. code-block:: none + + -VHDL93 Compile selected libraries with VHDL-93 (default). + -VHDL2008 Compile selected libraries with VHDL-2008. + +* ``compile-xilinx-ise.ps1`` + + Selectable libraries: + + .. code-block:: none + + -All Compile all libraries, including common libraries, packages and device libraries. + -Unisim Compile the unisim primitives + -Unimacro Compile the unimacro macros + -Simprim Compile the simprim primitives + -CoreLib Compile the xilinxcorelib macros + -Secureip Compile the secureip primitives + + Compile options: + + .. code-block:: none + + -VHDL93 Compile selected libraries with VHDL-93 (default). + -VHDL2008 Compile selected libraries with VHDL-2008. + +* ``compile-xilinx-vivado.ps1`` + + Selectable libraries: + + .. code-block:: none + + -All Compile all libraries, including common libraries, packages and device libraries. + -Unisim Compile the unisim primitives + -Unimacro Compile the unimacro macros + -Secureip Compile the secureip primitives + + Compile options: + + .. code-block:: none + + -VHDL93 Compile selected libraries with VHDL-93 (default). + -VHDL2008 Compile selected libraries with VHDL-2008. + +* ``compile-osvvm.ps1`` + + Selectable libraries: + + .. code-block:: none + + -All Compile all. + -OSVVM Compile the OSVVM library. + +* ``compile-uvvm.ps1`` + + Selectable libraries: + + .. code-block:: none + + -All Compile all. + -UVVM Compile the UVVM libraries. + +-------------------------------------------------------------------------------- + +.. container:: footnotes + + .. rubric:: Footnotes + + .. [#f1] OSVVM http://github.com/OSVVM/OSVVM + .. [#f2] UVVM https://github.com/UVVM/UVVM_All + .. [#f4] Generic Colourizer http://kassiopeia.juls.savba.sk/~garabik/software/grc.html 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 `_. - - * ``windows``: - - * ``mcode``: - * ``appveyor``: - -* ``doc``: `Markdown` and `reStructuredText` sources and auxiliary files to - build the documentation with `Sphinx `_. In fact, - `Read the Docs `_ (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/getting/GCC.rst b/doc/getting/GCC.rst deleted file mode 100644 index 7a8cd9b56..000000000 --- a/doc/getting/GCC.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. _BUILD:gcc: - -GCC backend -########### - -.. TODO :: Instructions to build GHDL with GCC backend on Windows are not available yet. - -.. rubric:: Requirements - -* GCC (Gnu Compiler Collection) -* GNAT (Ada compiler for GCC) -* GCC source files. Download and untar the sources of version 4.9.x, 5.x, 6.x, 7.x, 8.x, 9.x or 10.x. - -.. HINT :: There are some dependencies for building GCC (``gmp``, ``mpfr`` and ``mpc``). If you have not installed them on your system, you can either build them manually or use the ``download_prerequisites`` script provided in the GCC source tree (recommended): ``cd /path/to/gcc/source/dir && ./contrib/download_prerequisites``. - -* First configure GHDL, specify GCC source directory and installation prefix (like ``/usr/local`` or ``/opt/ghdl``). -* Next, invoke ``make copy-sources`` to copy GHDL sources in the source directory. -* Then, configure GCC. The list of ``--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. -* Now, build and install GCC with ``make``. -* Last, build and install GHDL libraries. - -.. rubric:: Example: - -.. code-block:: Bash - - $ cd - $ mkdir build - $ cd build - $ ../configure --with-gcc=/path/to/gcc/source/dir --prefix=/usr/local - $ make copy-sources - $ mkdir gcc-objs; cd gcc-objs - $ /path/to/gcc/source/dir/configure --prefix=/usr/local --enable-languages=c,vhdl \ - --disable-bootstrap --disable-lto --disable-multilib --disable-libssp \ - --disable-libgomp --disable-libquadmath - $ make -j2 && make install - $ cd /path/to/ghdl/source/dir/build - $ make ghdllib - $ make install - -.. HINT :: Note that the prefix directory to configure ``gcc`` 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``. - -.. HINT :: If your system gcc was configured with ``--enable-default-pie`` (check if that option appears in the output of ``gcc -v``), you should also add it. - -.. HINT :: If you don't want to install ``makeinfo``, do ``make install MAKEINFO=true`` instead. - -.. HINT :: 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 install.vpi.local # Locally install vpi files - - In ``src/ortho/gcc``, create a ``Makefile.conf`` file that sets the following - variables: - - .. CODE:: Bash - - AGCC_GCCSRC_DIR=/path/to/gcc/sources - AGCC_GCCOBJ_DIR=/path/to/gcc/build - - If your system gcc was built with ``--enable-default-pie``, add - ``-no-pie`` option for linking. - -.. HINT :: For ppc64/ppc64le platform, the object file format contains an identifier for the source language. Because gcc doesn't know about VHDL, gcc crashes very early. This could be fixed with a very simple change in ``gcc/config/rs6000/rs6000.c`` (``gcc/config/rs6000/rs6000-logue.c`` since gcc 10), function ``rs6000_output_function_epilogue``: - - .. CODE:: diff - - || ! strcmp (language_string, "GNU GIMPLE") - || ! strcmp (language_string, "GNU Go") - || ! strcmp (language_string, "GNU D") - - || ! strcmp (language_string, "libgccjit")) - + || ! strcmp (language_string, "libgccjit") - + || ! strcmp (language_string, "vhdl")) - i = 0; diff --git a/doc/getting/LLVM.rst b/doc/getting/LLVM.rst deleted file mode 100644 index b8dde9735..000000000 --- a/doc/getting/LLVM.rst +++ /dev/null @@ -1,43 +0,0 @@ -.. _BUILD:llvm: - -LLVM backend -############ - -.. rubric:: Requirements - -* GCC (Gnu Compiler Collection) -* GNAT (Ada compiler for GCC) -* LLVM (Low-Level-Virtual Machine) and CLANG (Compiler front-end for LLVM): 3.5, 3.8, 3.9, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0 or 11.0 - -.. _BUILD:llvm:GNAT: - -GCC/GNAT: GNU/Linux or Windows (MinGW/MSYS2) -============================================ - -.. HINT:: You need to install LLVM (usually depends on ``libedit``, see :ghdlsharp:`29`). Debugging is supported with LLVM 3.5 or ``>=6``. - -GHDL is configured by ``configure`` and built by ``make``. - -* First, GHDL needs to be configured. It is common to specify a ``PREFIX`` - (installation directory like ``/usr/local`` or ``/opt/ghdl``). Set the proper - arg, ``./configure --with-llvm-config``, to select LLVM backend. If - ``llvm-config`` is not in your path, you can specify it: - ``./configure --with-llvm-config=LLVM_INSTALL/bin/llvm-config``. - -* Next, ``make`` starts the compilation process. - -* Finally, ``make install`` installs GHDL into the installation directory - specified by ``PREFIX``. - -.. rubric:: Example: - -.. code-block:: Bash - - $ cd - $ mkdir build - $ cd build - $ ../configure --with-llvm-config --prefix=PREFIX - $ make - $ make install - -.. HINT:: 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). Then add the following arg to configure: ``--with-backtrace-lib=/path-to-gcc-build/libbacktrace/.libs/libbacktrace.a`` diff --git a/doc/getting/PrecompileVendorPrimitives.rst b/doc/getting/PrecompileVendorPrimitives.rst deleted file mode 100644 index aa322d3b7..000000000 --- a/doc/getting/PrecompileVendorPrimitives.rst +++ /dev/null @@ -1,458 +0,0 @@ -.. _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 -be shipped with GHDL, but GHDL offers prepared compile scripts to pre-compile -these vendor libraries, if the vendor tool is present in the environment. There -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 -compile scripts can colorize the GHDL warning and error lines with the help -of ``grc/grcat`` [#f4]_. - -Supported Vendors Libraries -=========================== - -* Lattice (3.6 or later): - - * ``ec`` - * ``ecp``, ``ecp2``, ``ecp3``, ``ecp5u`` - * ``lptm``, ``lptm2`` - * ``machxo``, ``machxo2``, ``machxo3l``, ``machxo3d`` - * ``sc``, ``scm`` - * ``xp``, ``xp2`` - * ... - -* Intel (Altera) Quartus (13.0 or later): - - * ``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`` - * ... - -* Xilinx ISE (14.0 or later): - - * ``unisim`` (incl. ``secureip``) - * ``unimacro`` - * ``simprim`` (incl. ``secureip``) - * ``xilinxcorelib`` - -* Xilinx Vivado (2014.1 or later): - - * ``unisim`` (incl. ``secureip``) - * ``unimacro`` - -Supported Simulation and Verification Libraries -=============================================== - -* OSVVM [#f1]_ (for VHDL-2008) -* UVVM [#f2]_ (for VHDL-2008) - - ---------------------------------------------------------------------- - -Script Configuration -==================== - -The vendor library compile scripts need to know where the used / latest vendor -tool chain is installed. Therefore, the scripts implement a default installation -directory search as well as environment variable checks. If a vendor tool cannot -be detected or the script chooses the wrong vendor library source directory, -then it's possible to provide the path via ``--source`` (Bash) or ``-Source`` -(PoSh). - -The generated output is stored relative to the current working directory. The -scripts create a sub-directory for each vendor. The default output directory can -be overwritten by the parameter ``--output`` (Bash) or ``-Output`` (PoSh). - -To compile all source files with GHDL, the simulator executable is searched in -``PATH``. The found default GHDL executable can be overwritten by setting the -environment variable ``GHDL`` or by passing the parameter ``--ghdl`` (Bash) or -``-GHDL`` (PoSh) to the scripts. - -If the vendor library compilation is used very often, it's recommend to configure -these parameters in ``config.sh`` (Bash) or ``config.psm1`` (PoSh), so the command -line can be shortened to the essential parts. - ---------------------------------------------------------------------- - -Compiling in Bash -================= - -The provided Bash scripts support these environments: - -* Linux -* MacOS -* MSYS2 / MinGW -* WSL (Windows Subsystem for Linux) - - -Follow these steps: - -* **Step 0 - Configure the scripts (optional)** - - See the next section for how to configure ``config.sh``. - -* **Step 1 - Browse to your simulation working directory** - - .. code-block:: Bash - - $ cd - - -* **Step 2 - Start the compilation script(s)** - - Choose one or multiple of the following scripts to run the pre-compilation - process. - - .. code-block:: Bash - - $ /usr/local/lib/ghdl/vendors/compile-altera.sh --all - $ /usr/local/lib/ghdl/vendors/compile-intel.sh --all - $ /usr/local/lib/ghdl/vendors/compile-lattice.sh --all - $ /usr/local/lib/ghdl/vendors/compile-osvvm.sh --all - $ /usr/local/lib/ghdl/vendors/compile-uvvm.sh --all - $ /usr/local/lib/ghdl/vendors/compile-xilinx-ise.sh --all - $ /usr/local/lib/ghdl/vendors/compile-xilinx-vivado.sh --all - - - In most cases GHDL is installed into ``/usr/local/``. The scripts are - installed into the ``lib\ghdl\vendors`` directory. - -* **Step 3 - Viewing the result** - - This creates vendor directories in your current working directory and - compiles the vendor files into them. - - - .. code-block:: Bash - - $ ls -ahl - ... - drwxr-xr-x 2 56K Mar 09 17:41 altera - drwxr-xr-x 2 56K Mar 09 17:42 intel - drwxr-xr-x 2 56K Mar 09 17:42 lattice - drwxr-xr-x 2 56K Mar 09 17:48 osvvm - drwxr-xr-x 2 56K Mar 09 17:58 uvvm - drwxr-xr-x 2 56K Mar 09 17:58 xilinx-ise - drwxr-xr-x 2 56K Mar 09 17:48 xilinx-vivado - - - ---------------------------------------------------------------------- - -Compiling in PowerShell -======================= - -The provided PowerShell scripts support these environments: - -* Windows™ 10 (PowerShell 5 and PowerShell 6) - - -Follow these steps: - -* **Step 0 - Configure the scripts (optional)** - - See the next section for how to configure ``config.psm1``. - -* **Step 1 - Browse to your simulation working directory** - - .. code-block:: PowerShell - - PS> cd - -* **Step 2 - Start the compilation script(s)** - - Choose one or multiple of the following scripts to run the pre-compilation - process. - - .. code-block:: PowerShell - - PS> \lib\ghdl\vendors\compile-altera.ps1 -All - PS> \lib\ghdl\vendors\compile-intel.ps1 -All - PS> \lib\ghdl\vendors\compile-lattice.ps1 -All - PS> \lib\ghdl\vendors\compile-osvvm.ps1 -All - PS> \lib\ghdl\vendors\compile-uvvm.ps1 -All - PS> \lib\ghdl\vendors\compile-xilinx-ise.ps1 -All - PS> \lib\ghdl\vendors\compile-xilinx-vivado.ps1 -All - - .. # In most cases GHDL is installed into ``/usr/local/``. - - The scripts are installed into the ``lib\ghdl\vendors`` directory. - -* **Step 3 - Viewing the result** - - This creates vendor directories in your current working directory and - compiles the vendor files into them. - - .. code-block:: - - PS> dir - Directory: D:\temp\ghdl - - Mode LastWriteTime Length Name - ---- ------------- ------ ---- - d---- 09.03.2018 19:33 altera - d---- 09.03.2018 19:38 intel - d---- 09.03.2018 19:38 lattice - d---- 09.03.2018 19:38 osvvm - d---- 09.03.2018 19:45 uvvm - d---- 09.03.2018 19:06 xilinx-ise - d---- 09.03.2018 19:40 xilinx-vivado - - ---------------------------------------------------------------------- - -Configuration Files -=================== - -For Bash: `config.sh` ---------------------- - -Please open the ``config.sh`` file and set the dictionary entries for the -installed vendor tools to your tool's installation directories. Use an empty -string ``""`` for not installed tools. - -``config.sh``: - -.. code-block:: Bash - - declare -A InstallationDirectory - InstallationDirectory[AlteraQuartus]="/opt/Altera/16.0" - InstallationDirectory[IntelQuartus]="/opt/intelFPGA/20.1" - InstallationDirectory[LatticeDiamond]="/opt/Diamond/3.10_x64" - InstallationDirectory[OSVVM]="/home//git/GitHub/OSVVM" - InstallationDirectory[UVVM]="/home//git/GitHub/UVVM" - InstallationDirectory[XilinxISE]="/opt/Xilinx/14.7" - InstallationDirectory[XilinxVivado]="/opt/Xilinx/Vivado/2020.2" - - -For PowerShell: `config.psm1` ------------------------------ - -Please open the ``config.psm1`` file and set the dictionary entries for the -installed vendor tools to your tool's installation -folder. Use an empty string ``""`` for not installed tools. - -``config.psm1``: - -.. code-block:: PowerShell - - $InstallationDirectory = @{ - "AlteraQuartus" = "C:\Altera\16.0"; - "IntelQuartus" = "C:\Altera\20.1"; - "LatticeDiamond" = "C:\Lattice\Diamond\3.10_x64"; - "XilinxISE" = "C:\Xilinx\14.7\ISE_DS"; - "XilinxVivado" = "C:\Xilinx\Vivado\2020.2"; - "OSVVM" = "C:\git\GitHub\OSVVM"; - "UVVM" = "C:\git\GitHub\UVVM" - } - - -Additional Script Parameters -============================ - -Each script supports partial compilations e.g. of shared packages and -individual parts. In addition, the amount of printout to the console can be -controlled. Some scripts may offer vendor specific options. - - -For Bash Scripts: ------------------ - -* Common parameters to most scripts: - - .. code-block:: none - - --help, -h Print the embedded help page(s). - --clean, -c Cleanup directory before analyzing. - --no-warnings, -n Don't show warnings. Report errors only. - --skip-existing, -s Skip already compiled files (an *.o file exists). - --skip-largefiles, -S Don't compile large entities like DSP and PCIe primitives. - --halt-on-error, -H Stop compiling if an error occurred. - -* ``compile-altera.sh`` - - Selectable libraries: - - .. code-block:: none - - --all, -a Compile all libraries, including common libraries, packages and device libraries. - --altera Compile base libraries like 'altera' and 'altera_mf' - --max Compile device libraries for Max CPLDs - --arria Compile device libraries for Arria FPGAs - --cyclone Compile device libraries for Cyclone FPGAs - --stratix Compile device libraries for Stratix FPGAs - - Compile options: - - .. code-block:: none - - --vhdl93 Compile selected libraries with VHDL-93 (default). - --vhdl2008 Compile selected libraries with VHDL-2008. - -* ``compile-xilinx-ise.sh`` - - Selectable libraries: - - .. code-block:: none - - --all, -a Compile all libraries, including common libraries, packages and device libraries. - --unisim Compile the unisim primitives - --unimacro Compile the unimacro macros - --simprim Compile the simprim primitives - --corelib Compile the xilinxcorelib macros - --secureip Compile the secureip primitives - - Compile options: - - .. code-block:: none - - --vhdl93 Compile selected libraries with VHDL-93 (default). - --vhdl2008 Compile selected libraries with VHDL-2008. - -* ``compile-xilinx-vivado.sh`` - - Selectable libraries: - - .. code-block:: none - - --all, -a Compile all libraries, including common libraries, packages and device libraries. - --unisim Compile the unisim primitives - --unimacro Compile the unimacro macros - --secureip Compile the secureip primitives - - Compile options: - - .. code-block:: none - - --vhdl93 Compile selected libraries with VHDL-93 (default). - --vhdl2008 Compile selected libraries with VHDL-2008. - -* ``compile-osvvm.sh`` - - Selectable libraries: - - .. code-block:: none - - --all, -a Compile all. - --osvvm Compile the OSVVM library. - -* ``compile-uvvm.sh`` - - Selectable libraries: - - .. code-block:: none - - --all, -a Compile all. - --uvvm Compile the UVVM libraries. - - -For PowerShell Scripts: ------------------------ - -* Common parameters to all scripts: - - .. code-block:: none - - -Help Print the embedded help page(s). - -Clean Cleanup directory before analyzing. - -SuppressWarnings Don't show warnings. Report errors only. - -* ``compile-altera.ps1`` - - Selectable libraries: - - .. code-block:: none - - -All Compile all libraries, including common libraries, packages and device libraries. - -Altera Compile base libraries like 'altera' and 'altera_mf' - -Max Compile device libraries for Max CPLDs - -Arria Compile device libraries for Arria FPGAs - -Cyclone Compile device libraries for Cyclone FPGAs - -Stratix Compile device libraries for Stratix FPGAs - - Compile options: - - .. code-block:: none - - -VHDL93 Compile selected libraries with VHDL-93 (default). - -VHDL2008 Compile selected libraries with VHDL-2008. - -* ``compile-xilinx-ise.ps1`` - - Selectable libraries: - - .. code-block:: none - - -All Compile all libraries, including common libraries, packages and device libraries. - -Unisim Compile the unisim primitives - -Unimacro Compile the unimacro macros - -Simprim Compile the simprim primitives - -CoreLib Compile the xilinxcorelib macros - -Secureip Compile the secureip primitives - - Compile options: - - .. code-block:: none - - -VHDL93 Compile selected libraries with VHDL-93 (default). - -VHDL2008 Compile selected libraries with VHDL-2008. - -* ``compile-xilinx-vivado.ps1`` - - Selectable libraries: - - .. code-block:: none - - -All Compile all libraries, including common libraries, packages and device libraries. - -Unisim Compile the unisim primitives - -Unimacro Compile the unimacro macros - -Secureip Compile the secureip primitives - - Compile options: - - .. code-block:: none - - -VHDL93 Compile selected libraries with VHDL-93 (default). - -VHDL2008 Compile selected libraries with VHDL-2008. - -* ``compile-osvvm.ps1`` - - Selectable libraries: - - .. code-block:: none - - -All Compile all. - -OSVVM Compile the OSVVM library. - -* ``compile-uvvm.ps1`` - - Selectable libraries: - - .. code-block:: none - - -All Compile all. - -UVVM Compile the UVVM libraries. - --------------------------------------------------------------------------------- - -.. container:: footnotes - - .. rubric:: Footnotes - - .. [#f1] OSVVM http://github.com/OSVVM/OSVVM - .. [#f2] UVVM https://github.com/UVVM/UVVM_All - .. [#f4] Generic Colourizer http://kassiopeia.juls.savba.sk/~garabik/software/grc.html diff --git a/doc/getting/Releases.rst b/doc/getting/Releases.rst deleted file mode 100644 index 2a80d8591..000000000 --- a/doc/getting/Releases.rst +++ /dev/null @@ -1,147 +0,0 @@ -.. _RELEASE: - -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 `__. -These are mostly meant to be used in Continuous Integration (CI) workflows. Precisely, `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 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 -************************ - -.. HINT:: - - All the following procedures will retrieve the latest development version of GHDL, i.e., the `master` branch at - `github.com/ghdl/ghdl `_. We do our best to keep it stable, but bugs can seldom be - published. See `HINT` boxes below for instructions to get older releases. - -.. _RELEASE:Sources:Zip: - -.. 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: - -.. only:: html - - .. |zip-master| image:: https://img.shields.io/badge/ZIP-archive/master-323131.svg?longCache=true&style=flat-square&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAMAAABEpIrGAAACE1BMVEUAAAAAAABcXFwAAACpqakAAABXV1cAAAAAAADAwMBYWFgAAACcnJxzc3MiIiKPj4%2FExMRaWlohISHo6OgbGxs5OTnMzMw9PT3AwMBWVlZkZGSGhoanp6eLi4vMzMyAgIC3t7eUlJSysrKNjY2Wlparq6uysrKlpaW1tbV6enqzs7PR0dGrq6uEhISwsLDFxcW9vb3Kysrg4OC8vLy3t7fPz8%2FDw8Ojo6OsrKzS0tLQ0NC9vb3ExMTm5ua9vb3Q0NChoaGsrKyurq7e3t7U1NSWlpaJiYmNjY3R0dG0tLSVlZXCwsK8vLzDw8Ph4eHk5OTW1tbW1tbm5ube3t7g4ODKysq3t7fOzs7f39%2FW1tbR0dHOzs7CwsLe3t7c3Nzn5%2BfW1tbq6urIyMjb29vW1tbe3t7X19fa2trb29vt7e3q6urHx8ft7e3k5OTh4eHPz8%2FV1dXT09Pm5ubh4eHg4ODm5ub9%2Ff3%2F%2F%2F%2F%2F%2F%2F%2Fk5OTp6enY2Njo6OjZ2dnn5%2Bfp6enc3Nzu7u76%2Bvr09PTk5OTw8PDn5%2Bf5%2Bfnf39%2Fq6urg4ODo6Ojk5OT4%2BPjm5ubm5ubs7Ozu7u76%2Bvrk5OTu7u739%2Ffq6urr6%2Bvx8fH6%2Bvrt7e34%2BPj6%2Bvr%2B%2Fv7s7Oz5%2Bfn%2B%2Fv7%2F%2F%2F%2Fp6enr6%2Bvt7e3v7%2B%2Fx8fHy8vLz8%2FP09PT29vb39%2Ff5%2Bfn8%2FPz9%2Ff3%2B%2Fv7%2F%2F%2F9qYR%2FuAAAAonRSTlMAAQECAgMDBAYGBwgKCwwMDQ4SEhQUGhwdHiIjIyQkJygpMDIzMzQ1NTY3OTo8PDw%2FP0ZITk9RUlNTVldXV1hYWlpaWltdYGBiY2ZpbHB1dXZ3d3t8fX5%2Ff4aHiIqKj5WXn6KjpKmssrK0t7u8vb7BwsPEyszNzc3O0dLT09fY2tvf4OXm5ufn6ers7O3w8fLy8vL09fX29%2Ff4%2Bvv7%2FP39%2Ff5qibsTAAABrElEQVR4AX2LhfcSURCFBxHBbkWxuwW7Q7AbQ7AbuwMMRQxRVAwMxRBWBRSX%2BRN%2F97y3y9ldlv3OmfPu3PkemfBsVbaQAwsrzPxnLrVh4huc65h3I8iGno9walyj6wzu9CIrVxk86YvU%2BxVS6SKZOP4D5ccxJJnxHtvnvdRk10sUlUVEJy4NFIV33d8S89P1JJj3GOfaDqQlG4%2BcX7tdlL6DKtr7UwgwuOwRdY85h08vuD1A5MFnGEgB7OlGkg0XZj5bPFXEcW91oQHj37Iu0uh%2BYNqXlZtFvKkLN%2FZ9g%2FJ7Qiep9JutjD25AiGpC0nqehZG4%2BEQaXQe%2BX3oUbNA1P8uFPWWTyqzPo2yCGDSAyj%2FT4ncZ%2F%2FzFgEs%2FwClQmDptvk2AtjJsht275C9QJqwevIxZ2ETf3UWrjBPdxR%2B7V6zykkYfY5ek0HIWIXx%2FGIQnowucC1mFmg4JlbTlngRoRw2CiBcRizGSZCoY8mHDEIoj1BPUJOUiiLr1wR%2FFo%2BaIiPeHIO0ENIMcl6yECig%2FqlNIUCtuIMKS5Sgm2xxRao4VyMuaos7qkQtvzsAWpTtdh6JoYQAAAAASUVORK5CYII%3D - :target: https://github.com/ghdl/ghdl/archive/master.zip - :alt: Source Code from GitHub - 'master' branch. - - .. |tgz-master| image:: https://img.shields.io/badge/TGZ-archive/master-323131.svg?longCache=true&style=flat-square&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAMAAABEpIrGAAACE1BMVEUAAAAAAABcXFwAAACpqakAAABXV1cAAAAAAADAwMBYWFgAAACcnJxzc3MiIiKPj4%2FExMRaWlohISHo6OgbGxs5OTnMzMw9PT3AwMBWVlZkZGSGhoanp6eLi4vMzMyAgIC3t7eUlJSysrKNjY2Wlparq6uysrKlpaW1tbV6enqzs7PR0dGrq6uEhISwsLDFxcW9vb3Kysrg4OC8vLy3t7fPz8%2FDw8Ojo6OsrKzS0tLQ0NC9vb3ExMTm5ua9vb3Q0NChoaGsrKyurq7e3t7U1NSWlpaJiYmNjY3R0dG0tLSVlZXCwsK8vLzDw8Ph4eHk5OTW1tbW1tbm5ube3t7g4ODKysq3t7fOzs7f39%2FW1tbR0dHOzs7CwsLe3t7c3Nzn5%2BfW1tbq6urIyMjb29vW1tbe3t7X19fa2trb29vt7e3q6urHx8ft7e3k5OTh4eHPz8%2FV1dXT09Pm5ubh4eHg4ODm5ub9%2Ff3%2F%2F%2F%2F%2F%2F%2F%2Fk5OTp6enY2Njo6OjZ2dnn5%2Bfp6enc3Nzu7u76%2Bvr09PTk5OTw8PDn5%2Bf5%2Bfnf39%2Fq6urg4ODo6Ojk5OT4%2BPjm5ubm5ubs7Ozu7u76%2Bvrk5OTu7u739%2Ffq6urr6%2Bvx8fH6%2Bvrt7e34%2BPj6%2Bvr%2B%2Fv7s7Oz5%2Bfn%2B%2Fv7%2F%2F%2F%2Fp6enr6%2Bvt7e3v7%2B%2Fx8fHy8vLz8%2FP09PT29vb39%2Ff5%2Bfn8%2FPz9%2Ff3%2B%2Fv7%2F%2F%2F9qYR%2FuAAAAonRSTlMAAQECAgMDBAYGBwgKCwwMDQ4SEhQUGhwdHiIjIyQkJygpMDIzMzQ1NTY3OTo8PDw%2FP0ZITk9RUlNTVldXV1hYWlpaWltdYGBiY2ZpbHB1dXZ3d3t8fX5%2Ff4aHiIqKj5WXn6KjpKmssrK0t7u8vb7BwsPEyszNzc3O0dLT09fY2tvf4OXm5ufn6ers7O3w8fLy8vL09fX29%2Ff4%2Bvv7%2FP39%2Ff5qibsTAAABrElEQVR4AX2LhfcSURCFBxHBbkWxuwW7Q7AbQ7AbuwMMRQxRVAwMxRBWBRSX%2BRN%2F97y3y9ldlv3OmfPu3PkemfBsVbaQAwsrzPxnLrVh4huc65h3I8iGno9walyj6wzu9CIrVxk86YvU%2BxVS6SKZOP4D5ccxJJnxHtvnvdRk10sUlUVEJy4NFIV33d8S89P1JJj3GOfaDqQlG4%2BcX7tdlL6DKtr7UwgwuOwRdY85h08vuD1A5MFnGEgB7OlGkg0XZj5bPFXEcW91oQHj37Iu0uh%2BYNqXlZtFvKkLN%2FZ9g%2FJ7Qiep9JutjD25AiGpC0nqehZG4%2BEQaXQe%2BX3oUbNA1P8uFPWWTyqzPo2yCGDSAyj%2FT4ncZ%2F%2FzFgEs%2FwClQmDptvk2AtjJsht275C9QJqwevIxZ2ETf3UWrjBPdxR%2B7V6zykkYfY5ek0HIWIXx%2FGIQnowucC1mFmg4JlbTlngRoRw2CiBcRizGSZCoY8mHDEIoj1BPUJOUiiLr1wR%2FFo%2BaIiPeHIO0ENIMcl6yECig%2FqlNIUCtuIMKS5Sgm2xxRao4VyMuaos7qkQtvzsAWpTtdh6JoYQAAAAASUVORK5CYII%3D - :target: https://github.com/ghdl/ghdl/archive/master.tar.gz - :alt: Source Code from GitHub - 'master' branch. - - +----------+------------------------+ - | Branch | Download Link | - +==========+========================+ - | master | |zip-master| | - +----------+------------------------+ - | master | |tgz-master| | - +----------+------------------------+ - -.. HINT:: - - To download a specific version of GHDL, use this alternative URL, where ```` is ``tar.gz`` or ``zip``: - ``https://codeload.github.com/ghdl/ghdl//``. - -.. _RELEASE:Sources:GitClone: - -.. 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. - -+----------+----------------------------------------+ -| Protocol | GitHub Repository URL | -+==========+========================================+ -| HTTPS | https://github.com/ghdl/ghdl.git | -+----------+----------------------------------------+ -| SSH | ssh://git@github.com:ghdl/ghdl.git | -+----------+----------------------------------------+ - -.. HINT:: - - Execute ``git checkout -b stable `` after ``git clone``, to checkout a specific version of GHDL. - -Command line instructions to clone GHDL with HTTPS protocol: - -.. code-block:: Bash - - cd GitRoot - git clone "https://github.com/ghdl/ghdl.git" ghdl - cd ghdl - git remote rename origin github - -Command line instructions to clone GHDL with SSH protocol: - -.. code-block:: Bash - - cd GitRoot - git clone "ssh://git@github.com:ghdl/ghdl.git" ghdl - cd ghdl - git remote rename origin github - -.. 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 `_. diff --git a/doc/getting/index.rst b/doc/getting/index.rst deleted file mode 100644 index b256472b2..000000000 --- a/doc/getting/index.rst +++ /dev/null @@ -1,86 +0,0 @@ -.. _BUILD: - -Building GHDL from Sources -########################## - -.. rubric :: Download - -GHDL can be downloaded as a `zip-file `_/`tar-file `_ -(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. - -.. 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 `_ (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 - -GHDL currently supports three different back-ends (code generators): - -* mcode - built-in x86 (or x86_64) code generator -* GCC - Gnu Compiler Collection (`gcc.gnu.org `_) -* LLVM - Low-Level Virtual Machine (`llvm.org `_) - -Here is a short comparison, so that you can choose the one you want to use: - -+----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+ -| Back-end | Pros | Cons | -+============================+============================================================================+=========================================================+ -| :ref:`mcode ` | * Very easy to build | * Simulation is slower | -| | * Very quick analysis | * x86_64/i386 only | -| | * Can handle very large designs | | -+----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+ -| :ref:`LLVM ` | * Generated code is faster | * Build is more complex than mcode | -| | * Generated code can be debugged (with ``-g``) | | -| | * Easier to build than GCC | | -| | * Ported to many platforms (x86, x86_64, armv7/aarch64) | | -+----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+ -| :ref:`GCC ` | * Generated code is faster (particularly with ``-O`` or ``-O2``) | * Build is even more complex | -| | * Generated code can be debugged (with ``-g``) | * Analysis can take time (particularly for large units) | -| | * 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`. - -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 -know where the content will be placed and which files are expected to be -created. - -.. HINT :: - In these instructions, the configure script is executed in the source directory; but you can execute in a different - directory too, like this: - - .. CODE:: Bash - - $ mkdir ghdl-objs - $ 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 :: - For MacOS 10.15 (Catalina), see `https://github.com/ghdl/ghdl/issues/1368` for - workarounds to link failures. diff --git a/doc/getting/mcode.rst b/doc/getting/mcode.rst deleted file mode 100644 index 9e46a29b6..000000000 --- a/doc/getting/mcode.rst +++ /dev/null @@ -1,74 +0,0 @@ -.. _BUILD:mcode: - -mcode backend -############# - -The mcode backend is available for all supported platforms and is also the -simplest procedure, because it requires the fewest dependencies and configuration -options. - -.. _BUILD:mcode:GNAT: - -GCC/GNAT: GNU/Linux or Windows (MinGW/MSYS2) -============================================ - -.. rubric:: Requirements - -* GCC (Gnu Compiler Collection) -* GNAT (Ada compiler for GCC) - -GHDL is configured by ``configure`` and built by ``make``. - -* First, GHDL needs to be configured. It is common to specify a ``PREFIX`` - (installation directory like ``/usr/local`` or ``/opt/ghdl``). Without any - other option, ``configure`` selects `mcode` as the backend. - -* Next, ``make`` starts the compilation process. - -* Finally, ``make install`` installs GHDL into the installation directory - specified by ``PREFIX``. - -.. HINT :: ON GNU/Linux, you may need super user privileges (``sudo ...``). - - -.. rubric:: Example: - -.. code-block:: Bash - - $ cd - $ mkdir build - $ cd build - $ ../configure --prefix=PREFIX - $ make - $ make install - -.. _BUILD:mcode:GNATGPL-Windows: - -GNAT GPL: Windows -================= - -.. rubric:: Requirements - -* GNAT GPL from http://libre.adacore.com -* PowerShell 4 -* PowerShell Community Extensions (PSCX) - -.. rubric:: `compile.ps1` - -.. code-block:: - - Commands Description - -------------------------------------------------------------------- - -Help Display the integrated help pages - -Clean Clean up all files and directories - -Compile Compile GHDL - -Install Install all files into a directory (xcopy deployment) - -Uninstall Uninstall all files from a directory - -Update Update files in the installation directory - -CreatePackage create an installer package - - Install options: - -InstallPath Installation directory - - CreatePackage options: - -Zip Create a zip-file for xcopy deployment 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'): @@ -17,63 +18,15 @@ def getJSON(tag='all'): json.dump(d, open(f+'.json', 'w'), indent=4) 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', @@ -81,148 +34,6 @@ def printShieldSrc(label, alt, img, target, latex=False): ' :height: 22\n', ' :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// 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 `__ 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 `_. - * GitHub Action `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 `__. + * GitHub Action `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 `_ to - `ghdl/ghdl-yosys-plugin `_. - * Repository `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 `_. - * A `Wiki `_ was created. The roadmap and ideas for documentation and internship - programs were moved there. If you want to contribute anyhow, `have a look `_! + * The plugin for Yosys was moved from `tgingold/ghdlsynth-beta `__ to + `ghdl/ghdl-yosys-plugin `__. + * Repository `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 `__. + * A `Wiki `__ was created. The roadmap and ideas for documentation and internship + programs were moved there. If you want to contribute anyhow, `have a look `__! - 28.02.2020 - `GHDL v0.37 was released `_ - =========================================================================================== + 28.02.2020 - `GHDL v0.37 was released `__ + ============================================================================================ 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 `_ - =========================================================================================== + 03.03.2019 - `GHDL v0.36 was released `__ + ============================================================================================ 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 `_ to - `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 `__ to + `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 `_ - ========================================================================================== + 14.12.2017 - `GHDL 0.35 was released `__ + =========================================================================================== - 15.08.2017 - `GHDL 0.34 was released `_ - ========================================================================================== + 15.08.2017 - `GHDL 0.34 was released `__ + =========================================================================================== 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/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 using/ImplementationOfVHDL using/ImplementationOfVITAL @@ -153,10 +157,12 @@ GHDL :caption: Development :hidden: + development/Directories + Building GHDL + Python Interfaces 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) `_ : +* These from library ``ieee`` are copyrighted by `Institute of Electrical and Electronics Engineers (IEEE) `__: - - ``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 `_ ] - - ``std_logic_1164``, ``Math_Real`` and ``Math_Complex`` - - ``VITAL_Primitives``, ``VITAL_Timing`` and ``VITAL_Memory`` [see also `IEEE 1076.4 `_ ] + * Since December 2019, standard and IEEE libraries are distributed under Apache 2.0 and available at + `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 `__). - - 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. `_ - - ``mentor`` directory: ``std_logic_arith`` is copyrighted by `Mentor Graphics `_ + * ``synopsys`` directory: ``std_logic_arith``, ``std_logic_signed``, ``std_logic_unsigned`` and ``std_logic_textio`` are + copyrighted by `Synopsys, Inc. `__ + * ``mentor`` directory: ``std_logic_arith`` is copyrighted by `Mentor Graphics `__. .. _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 `_ 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 `__ for more details. .. _LIC:CC-BY-SA: CC-BY-SA ======== -This is a free documentation; you can redistribute it and/or modify it under the terms of the `Creative Commons Attribution-ShareAlike 4.0 `_ license. You are free to **share** (copy and redistribute the material in any medium or format) and/or **adapt** (remix, transform, and build upon the material for any purpose, even commercially). We cannot revoke these freedoms as long as you follow the these terms: +This is a free documentation; you can redistribute it and/or modify it under the terms of the `Creative Commons Attribution-ShareAlike 4.0 `__ license. You are free to **share** (copy and redistribute the material in any medium or format) and/or **adapt** (remix, transform, and build upon the material for any purpose, even commercially). We cannot revoke these freedoms as long as you follow the these terms: - **Attribution**: you must provide the name of the creator and attribution parties (`more info `__), a copyright notice, a license notice, a disclaimer notice, a link to the material, a link to the license and indicate if changes were made (see `marking guide `__ and `more info `__). You may do so in any reasonable manner, but not in any way that suggests we 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 `_ for more details. +See `CC-BY-SA-4.0 Legal Code `__ for more details. .. _LIC:contributors: List of Contributors ==================== -========================= ============================================================ -Contributor [#f1]_ Role -========================= ============================================================ -Baggett, Jonas signal selection -Bertram, Felix VPI interface -Davis, Brian Windows Mcode builds -Drummond, Brian GCC 4.8.2 update, OSVVM port, some bugfixes -Gingold, Tristan [#f2]_ **Sole author of GHDL as a whole** -Jensen, Adam FreeBSD builds -Koch, Markus vendor pre-compile script for Lattice (GNU/Linux) -Koontz, David Mac OSX builds, LRM compliance work, bugfix analyses -Lehmann, Patrick Windows compile scripts, vendor library pre-compile scripts (win+lin), building in MinGW, AppVeyor integration. -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 `_. +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 `__. -------------------------------------------------------------------------------- diff --git a/doc/pyGHDL/index.rst b/doc/pyGHDL/index.rst deleted file mode 100644 index 76462fd63..000000000 --- a/doc/pyGHDL/index.rst +++ /dev/null @@ -1,44 +0,0 @@ -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``. - - -.. # - 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 - :prog: pnodes - :groups: - :label: CmdRef:pnodes: - -.. _CMDREF-pnodespy: - -.. autoprogram:: AutoProgram:pnodespy_parser - :prog: pnodespy - :groups: - :label: CmdRef:pnodespy: diff --git a/doc/quick_start/DLXModelSuite.rst b/doc/quick_start/DLXModelSuite.rst deleted file mode 100644 index 0cdc8be86..000000000 --- a/doc/quick_start/DLXModelSuite.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. program:: ghdl -.. _QuickStart:DLX: - -Working with non-trivial designs -================================ - -Designs are usually more complex than the previous examples. Unless you are only studying VHDL, you will work with -larger designs. Let's see how to analyse a design such as the DLX model suite written by Peter Ashenden, which is -distributed under the terms of the GNU General Public License. A copy is kept at `ghdl.free.fr/dlx.tar.gz `_ . - -- First, untar the sources: ``tar zxvf dlx.tar.gz``. - -.. HINT:: - - In order not to pollute the sources with the artifacts (`WORK` library), it is a good idea to create a - :file:`work/` subdirectory. To any GHDL commands, we will add the :option:`--workdir=work <--workdir>` option, so - that all files generated by the compiler (except the executable) will be placed in this directory. - - .. code-block:: shell - - $ cd dlx - $ mkdir work - -* Then, we will run the ``dlx_test_behaviour`` design. We need to analyse all the design units for the design - hierarchy, in the correct order. GHDL provides an easy way to do this, by :ref:`importing ` the - sources: ``ghdl -i --workdir=work *.vhdl``. - -* GHDL knows all the design units of the DLX, but none of them has been analysed. Run the :ref:`make ` - command, ``ghdl -m --workdir=work dlx_test_behaviour``, which analyses and elaborates a design. This creates many - files in the :file:`work/` directory, and (GCC/LLVM only) the :file:`dlx_test_behaviour` executable in the current - directory. - -.. HINT:: - - The simulation needs to have a DLX program contained in the file :file:`dlx.out`. This memory image will be loaded - in the DLX memory. Just take one sample: ``cp test_loop.out dlx.out``. - -* Now, you can :ref:`run ` the test suite: ``ghdl -r --workdir=work dlx_test_behaviour``. The test bench - monitors the bus and displays each executed instruction. It finishes with an assertion of severity level note: - - .. code-block:: shell - - dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction - encountered, execution halted - -* Last, since the clock is still running, you have to manually stop the program with the :kbd:`C-c` key sequence. This - behavior prevents you from running the testbench in batch mode. However, you may force the simulator to stop when an - assertion above or equal a certain severity level occurs. To do so, call run with this option instead: - ``ghdl -r --workdir=work dlx_test_behaviour --assert-level=note```. With :option:`--assert-level`, the program stops - just after the previous message: - - .. code-block:: shell - - dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction - encountered, execution halted - error: assertion failed - -.. TIP:: If you want to make room on your hard drive, you can either: - - * :ref:`Clean ` the design library with ``ghdl --clean --workdir=work``. This removes the executable - and all the object files. If you want to rebuild the design at this point, just do the make command as shown above. - * :ref:`Remove ` the design library with ``ghdl --remove --workdir=work``. This removes the - executable, all the object files and the library file. If you want to rebuild the design, you have to import the - sources again and make the design. - * Remove the :file:`work/` directory: ``rm -rf work``. Only the executable is kept. If you want to rebuild the design, create the :file:`work/` directory, import the sources, and make the design. - -.. WARNING:: Sometimes, a design does not fully follow the VHDL standards. For example it might use the badly engineered ``std_logic_unsigned`` package. GHDL supports this VHDL dialect through some options: :option:`--ieee=synopsys <--ieee>`, :option:`-fexplicit`, etc. See section :ref:`IEEE_library_pitfalls`, for more details. diff --git a/doc/quick_start/README.rst b/doc/quick_start/README.rst deleted file mode 100644 index fc5f1a81a..000000000 --- a/doc/quick_start/README.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. 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 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: - -* :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). - - * 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:`--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``. - -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, -in the hope of helping understand the different use cases: - -.. toctree:: - - hello/README - heartbeat/README - adder/README - DLXModelSuite diff --git a/doc/quick_start/adder/README.rst b/doc/quick_start/adder/README.rst deleted file mode 100644 index 5ff607801..000000000 --- a/doc/quick_start/adder/README.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. program:: ghdl -.. _QuickStart:adder: - -`Full adder` module and testbench -================================= - -Unlike :ref:`Heartbeat `, the target hardware design in this example is written using the -synthesisable subset of `VHDL`. It is a `full adder `_ -described in a file named :file:`adder.vhdl`: - -.. literalinclude:: adder.vhdl - :language: vhdl - -You can :ref:`analyse ` this design file, ``ghdl -a adder.vhdl``, and try to execute the `adder` -design. But this is useless, since nothing externally visible will happen. In order to check this full adder, a -:dfn:`testbench` has to be run. The :dfn:`testbench` is a description of how to generate inputs and how to check the -outputs of the Unit Under Test (UUT). This one is very simple, since the adder is also simple: it checks exhaustively -all inputs. Note that only the behaviour is tested, timing constraints are not checked. A file named -:file:`adder_tb.vhdl` contains the testbench for the adder: - -.. literalinclude:: adder_tb.vhdl - :language: vhdl - -As usual, you should analyze the file, ``ghdl -a adder_tb.vhdl``. - -.. HINT:: - Then, if required, :ref:`elaborate ` the testbench: ``ghdl -e adder_tb``. You do not need to - specify which object files are required, since `GHDL` knows them and automatically adds them. - -Now, it is time to :ref:`run ` the testbench, ``ghdl -r adder_tb``, and check the result on screen:: - - adder_tb.vhdl:52:7:(assertion note): end of test - -If your design is rather complex, you'd like to inspect signals as explained in :ref:`Heartbeat `. - -See section :ref:`simulation_options`, for more details on other runtime options. diff --git a/doc/quick_start/adder/adder.vhdl b/doc/quick_start/adder/adder.vhdl deleted file mode 100644 index cf60e8fbe..000000000 --- a/doc/quick_start/adder/adder.vhdl +++ /dev/null @@ -1,14 +0,0 @@ -entity adder is - -- `i0`, `i1`, and the carry-in `ci` are inputs of the adder. - -- `s` is the sum output, `co` is the carry-out. - port (i0, i1 : in bit; ci : in bit; s : out bit; co : out bit); -end adder; - -architecture rtl of adder is -begin - -- This full-adder architecture contains two concurrent assignments. - -- Compute the sum. - s <= i0 xor i1 xor ci; - -- Compute the carry. - co <= (i0 and i1) or (i0 and ci) or (i1 and ci); -end rtl; diff --git a/doc/quick_start/adder/adder_tb.vhdl b/doc/quick_start/adder/adder_tb.vhdl deleted file mode 100644 index 4a3fca5e4..000000000 --- a/doc/quick_start/adder/adder_tb.vhdl +++ /dev/null @@ -1,57 +0,0 @@ --- A testbench has no ports. -entity adder_tb is -end adder_tb; - -architecture behav of adder_tb is - -- Declaration of the component that will be instantiated. - component adder - port (i0, i1 : in bit; ci : in bit; s : out bit; co : out bit); - end component; - - -- Specifies which entity is bound with the component. - for adder_0: adder use entity work.adder; - signal i0, i1, ci, s, co : bit; -begin - -- Component instantiation. - adder_0: adder port map (i0 => i0, i1 => i1, ci => ci, s => s, co => co); - - -- This process does the real job. - process - type pattern_type is record - -- The inputs of the adder. - i0, i1, ci : bit; - -- The expected outputs of the adder. - s, co : bit; - end record; - -- The patterns to apply. - type pattern_array is array (natural range <>) of pattern_type; - constant patterns : pattern_array := - (('0', '0', '0', '0', '0'), - ('0', '0', '1', '1', '0'), - ('0', '1', '0', '1', '0'), - ('0', '1', '1', '0', '1'), - ('1', '0', '0', '1', '0'), - ('1', '0', '1', '0', '1'), - ('1', '1', '0', '0', '1'), - ('1', '1', '1', '1', '1')); - begin - -- Check each pattern. - for i in patterns'range loop - -- Set the inputs. - i0 <= patterns(i).i0; - i1 <= patterns(i).i1; - ci <= patterns(i).ci; - -- Wait for the results. - wait for 1 ns; - -- Check the outputs. - assert s = patterns(i).s - report "bad sum value" severity error; - assert co = patterns(i).co - report "bad carry out value" severity error; - end loop; - assert false report "end of test" severity note; - -- Wait forever; this will finish the simulation. - wait; - end process; - -end behav; diff --git a/doc/quick_start/heartbeat/README.rst b/doc/quick_start/heartbeat/README.rst deleted file mode 100644 index e95145095..000000000 --- a/doc/quick_start/heartbeat/README.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. program:: ghdl -.. _QuickStart:heartbeat: - -`Heartbeat` module -================== - -Although :ref:`Hello world ` illustrates that `VHDL` is supported as a general purpose language, the main use case -of `GHDL` is to simulate hardware descriptions. The following block, which is saved in a file named -:file:`heartbeat.vhdl`, is an example of how to generate a 100 MHz clock signal with non-synthesisable VHDL: - -.. literalinclude:: heartbeat.vhdl - :language: vhdl - -It can be :ref:`analysed `, :ref:`elaborated ` and :ref:`run `, as you already know: - -.. code-block:: shell - - ghdl -a heartbeat.vhdl - ghdl -e heartbeat - ghdl -r heartbeat - -However, execution of the design does not terminate. At the same time, no output is shown on screen. This is because, -traditionally, hardware designs are continuously running devices which do not have a screen where to print. In this -context, inspection and verification of the behaviour is done through `waveforms `_, -which is supported by `GHDL` (see :ref:`export_waves`). You can use either :option:`--wave`, :option:`--vcd`, -:option:`--vcdgz` or :option:`--fst` to save the signals of the simulation to a file. Then, terminate the execution -(:kbd:`C-c`) and you can inspect the wave with a viewer, such as `GtkWave `_. As -explained in the `manual `_, GtkWave *'relies on a post-mortem approach -through the use of dumpfiles'*. Therefore, you should first simulate your design and dump a waveform file, say GHW: - -.. code-block:: shell - - ghdl -r heartbeat --wave=wave.ghw - -Then, you can view the dump: - -.. code-block:: shell - - gtkwave wave.ghw - -Of course, manually terminating the simulation is for illustration purposes only. In :ref:`Full adder ` and -:ref:`QuickStart:DLX`, you will see how to write a testbench to terminate the simulation programmatically. diff --git a/doc/quick_start/heartbeat/heartbeat.vhdl b/doc/quick_start/heartbeat/heartbeat.vhdl deleted file mode 100644 index 0a312641e..000000000 --- a/doc/quick_start/heartbeat/heartbeat.vhdl +++ /dev/null @@ -1,20 +0,0 @@ -library ieee; -use ieee.std_logic_1164.all; - -entity heartbeat is - port ( clk: out std_logic); -end heartbeat; - -architecture behaviour of heartbeat -is - constant clk_period : time := 10 ns; -begin - -- Clock process definition - clk_process: process - begin - clk <= '0'; - wait for clk_period/2; - clk <= '1'; - wait for clk_period/2; - end process; -end behaviour; diff --git a/doc/quick_start/hello/README.rst b/doc/quick_start/hello/README.rst deleted file mode 100644 index 104a12efa..000000000 --- a/doc/quick_start/hello/README.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. program:: ghdl -.. _QuickStart:hello: - -`Hello world` program -===================== - -To illustrate the general purpose of `VHDL`, the following block is a commented `Hello world` program which is saved in -a file named :file:`hello.vhdl`: - -.. literalinclude:: hello.vhdl - :language: vhdl - -.. TIP:: - - * Both ``.vhdl`` and ``.vhd`` extensions are used for `VHDL` source files, while ``.v`` is used for Verilog. - - * Since, extension ``.vhd`` is also interpreted as a `Virtual Hard Disk `_ - file format, some users prefer ``.vhdl``, to avoid ambiguity. This is the case with `GHDL`'s codebase. However, in order - to maintain `backward-compatibility `_ with legacy DOS systems, - other users prefer ``.vhd``. - - * Unless you use especial characters, either `UTF-8` or `ISO-8859-1` encodings can be used. However, if you do, the - latter should be used. The standard defines ASCII (7-bit encoding) or ISO Latin-1 (ISO-8859-1) as default. - However, GHDL has a relaxing option, :option:`--mb-comments` (multi byte), to allow UTF-8 or other encodings in - comments. - -- First, you have to compile the file; this is called :ref:`analysis ` of a design file in `VHDL` - terms. Run ``ghdl -a hello.vhdl`` in the `shell`. This command creates or updates a file :file:`work-obj93.cf`, which - describes the library ``work``. -- Then, run ``ghdl -e hello_world`` in the `shell`. Command :option:`-e` means :ref:`elaborate `, - which is used to build a design, with the ``hello_world`` entity at the top of the hierarchy. -- Last, you can directly launch the simulation :ref:`running ` ``ghdl -r hello_world`` in the `shell`. The - result of the simulation will be shown on screen: - -.. code-block:: shell - - Hello world! - -.. HINT:: - If a GCC/LLVM variant of `GHDL` is used: - - * :ref:`Analysis ` generates a file, :file:`hello.o`, which is the object file corresponding to - your `VHDL` program. This is not created with :ref:`mcode `. These kind of object files can be - compiled into foreign programs (see :ref:`Linking_with_Ada`). - * The :ref:`elaboration ` step is mandatory after running the analysis and prior to launching the - simulation. This will generate an executable binary named :file:`hello_world`. - * As a result, :option:`-r` is just a passthrough to the binary generated in the `elaboration`. Therefore, the - executable can be run directly: ``./hello_world``. See :option:`-r` for more informartion. - -.. HINT:: - - :option:`-e` can be bypassed with :ref:`mcode `, since :option:`-r` actually elaborates the design and saves - it on memory before running the simulation. But you can still use it to check for some elaboration problems. diff --git a/doc/quick_start/hello/hello.vhdl b/doc/quick_start/hello/hello.vhdl deleted file mode 100644 index 4d969c6a8..000000000 --- a/doc/quick_start/hello/hello.vhdl +++ /dev/null @@ -1,17 +0,0 @@ --- Hello world program -use std.textio.all; -- Imports the standard textio package. - --- Defines a design entity, without any ports. -entity hello_world is -end hello_world; - -architecture behaviour of hello_world is -begin - process - variable l : line; - begin - write (l, String'("Hello world!")); - writeline (output, l); - wait; - end process; -end behaviour; 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 + 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/simulation/DLXModelSuite.rst b/doc/quick_start/simulation/DLXModelSuite.rst new file mode 100644 index 000000000..0cdc8be86 --- /dev/null +++ b/doc/quick_start/simulation/DLXModelSuite.rst @@ -0,0 +1,67 @@ +.. program:: ghdl +.. _QuickStart:DLX: + +Working with non-trivial designs +================================ + +Designs are usually more complex than the previous examples. Unless you are only studying VHDL, you will work with +larger designs. Let's see how to analyse a design such as the DLX model suite written by Peter Ashenden, which is +distributed under the terms of the GNU General Public License. A copy is kept at `ghdl.free.fr/dlx.tar.gz `_ . + +- First, untar the sources: ``tar zxvf dlx.tar.gz``. + +.. HINT:: + + In order not to pollute the sources with the artifacts (`WORK` library), it is a good idea to create a + :file:`work/` subdirectory. To any GHDL commands, we will add the :option:`--workdir=work <--workdir>` option, so + that all files generated by the compiler (except the executable) will be placed in this directory. + + .. code-block:: shell + + $ cd dlx + $ mkdir work + +* Then, we will run the ``dlx_test_behaviour`` design. We need to analyse all the design units for the design + hierarchy, in the correct order. GHDL provides an easy way to do this, by :ref:`importing ` the + sources: ``ghdl -i --workdir=work *.vhdl``. + +* GHDL knows all the design units of the DLX, but none of them has been analysed. Run the :ref:`make ` + command, ``ghdl -m --workdir=work dlx_test_behaviour``, which analyses and elaborates a design. This creates many + files in the :file:`work/` directory, and (GCC/LLVM only) the :file:`dlx_test_behaviour` executable in the current + directory. + +.. HINT:: + + The simulation needs to have a DLX program contained in the file :file:`dlx.out`. This memory image will be loaded + in the DLX memory. Just take one sample: ``cp test_loop.out dlx.out``. + +* Now, you can :ref:`run ` the test suite: ``ghdl -r --workdir=work dlx_test_behaviour``. The test bench + monitors the bus and displays each executed instruction. It finishes with an assertion of severity level note: + + .. code-block:: shell + + dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction + encountered, execution halted + +* Last, since the clock is still running, you have to manually stop the program with the :kbd:`C-c` key sequence. This + behavior prevents you from running the testbench in batch mode. However, you may force the simulator to stop when an + assertion above or equal a certain severity level occurs. To do so, call run with this option instead: + ``ghdl -r --workdir=work dlx_test_behaviour --assert-level=note```. With :option:`--assert-level`, the program stops + just after the previous message: + + .. code-block:: shell + + dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction + encountered, execution halted + error: assertion failed + +.. TIP:: If you want to make room on your hard drive, you can either: + + * :ref:`Clean ` the design library with ``ghdl --clean --workdir=work``. This removes the executable + and all the object files. If you want to rebuild the design at this point, just do the make command as shown above. + * :ref:`Remove ` the design library with ``ghdl --remove --workdir=work``. This removes the + executable, all the object files and the library file. If you want to rebuild the design, you have to import the + sources again and make the design. + * Remove the :file:`work/` directory: ``rm -rf work``. Only the executable is kept. If you want to rebuild the design, create the :file:`work/` directory, import the sources, and make the design. + +.. WARNING:: Sometimes, a design does not fully follow the VHDL standards. For example it might use the badly engineered ``std_logic_unsigned`` package. GHDL supports this VHDL dialect through some options: :option:`--ieee=synopsys <--ieee>`, :option:`-fexplicit`, etc. See section :ref:`IEEE_library_pitfalls`, for more details. diff --git a/doc/quick_start/simulation/adder/adder.vhdl b/doc/quick_start/simulation/adder/adder.vhdl new file mode 100644 index 000000000..cf60e8fbe --- /dev/null +++ b/doc/quick_start/simulation/adder/adder.vhdl @@ -0,0 +1,14 @@ +entity adder is + -- `i0`, `i1`, and the carry-in `ci` are inputs of the adder. + -- `s` is the sum output, `co` is the carry-out. + port (i0, i1 : in bit; ci : in bit; s : out bit; co : out bit); +end adder; + +architecture rtl of adder is +begin + -- This full-adder architecture contains two concurrent assignments. + -- Compute the sum. + s <= i0 xor i1 xor ci; + -- Compute the carry. + co <= (i0 and i1) or (i0 and ci) or (i1 and ci); +end rtl; diff --git a/doc/quick_start/simulation/adder/adder_tb.vhdl b/doc/quick_start/simulation/adder/adder_tb.vhdl new file mode 100644 index 000000000..4a3fca5e4 --- /dev/null +++ b/doc/quick_start/simulation/adder/adder_tb.vhdl @@ -0,0 +1,57 @@ +-- A testbench has no ports. +entity adder_tb is +end adder_tb; + +architecture behav of adder_tb is + -- Declaration of the component that will be instantiated. + component adder + port (i0, i1 : in bit; ci : in bit; s : out bit; co : out bit); + end component; + + -- Specifies which entity is bound with the component. + for adder_0: adder use entity work.adder; + signal i0, i1, ci, s, co : bit; +begin + -- Component instantiation. + adder_0: adder port map (i0 => i0, i1 => i1, ci => ci, s => s, co => co); + + -- This process does the real job. + process + type pattern_type is record + -- The inputs of the adder. + i0, i1, ci : bit; + -- The expected outputs of the adder. + s, co : bit; + end record; + -- The patterns to apply. + type pattern_array is array (natural range <>) of pattern_type; + constant patterns : pattern_array := + (('0', '0', '0', '0', '0'), + ('0', '0', '1', '1', '0'), + ('0', '1', '0', '1', '0'), + ('0', '1', '1', '0', '1'), + ('1', '0', '0', '1', '0'), + ('1', '0', '1', '0', '1'), + ('1', '1', '0', '0', '1'), + ('1', '1', '1', '1', '1')); + begin + -- Check each pattern. + for i in patterns'range loop + -- Set the inputs. + i0 <= patterns(i).i0; + i1 <= patterns(i).i1; + ci <= patterns(i).ci; + -- Wait for the results. + wait for 1 ns; + -- Check the outputs. + assert s = patterns(i).s + report "bad sum value" severity error; + assert co = patterns(i).co + report "bad carry out value" severity error; + end loop; + assert false report "end of test" severity note; + -- Wait forever; this will finish the simulation. + wait; + end process; + +end behav; diff --git a/doc/quick_start/simulation/adder/index.rst b/doc/quick_start/simulation/adder/index.rst new file mode 100644 index 000000000..5ff607801 --- /dev/null +++ b/doc/quick_start/simulation/adder/index.rst @@ -0,0 +1,36 @@ +.. program:: ghdl +.. _QuickStart:adder: + +`Full adder` module and testbench +================================= + +Unlike :ref:`Heartbeat `, the target hardware design in this example is written using the +synthesisable subset of `VHDL`. It is a `full adder `_ +described in a file named :file:`adder.vhdl`: + +.. literalinclude:: adder.vhdl + :language: vhdl + +You can :ref:`analyse ` this design file, ``ghdl -a adder.vhdl``, and try to execute the `adder` +design. But this is useless, since nothing externally visible will happen. In order to check this full adder, a +:dfn:`testbench` has to be run. The :dfn:`testbench` is a description of how to generate inputs and how to check the +outputs of the Unit Under Test (UUT). This one is very simple, since the adder is also simple: it checks exhaustively +all inputs. Note that only the behaviour is tested, timing constraints are not checked. A file named +:file:`adder_tb.vhdl` contains the testbench for the adder: + +.. literalinclude:: adder_tb.vhdl + :language: vhdl + +As usual, you should analyze the file, ``ghdl -a adder_tb.vhdl``. + +.. HINT:: + Then, if required, :ref:`elaborate ` the testbench: ``ghdl -e adder_tb``. You do not need to + specify which object files are required, since `GHDL` knows them and automatically adds them. + +Now, it is time to :ref:`run ` the testbench, ``ghdl -r adder_tb``, and check the result on screen:: + + adder_tb.vhdl:52:7:(assertion note): end of test + +If your design is rather complex, you'd like to inspect signals as explained in :ref:`Heartbeat `. + +See section :ref:`simulation_options`, for more details on other runtime options. diff --git a/doc/quick_start/simulation/heartbeat/heartbeat.vhdl b/doc/quick_start/simulation/heartbeat/heartbeat.vhdl new file mode 100644 index 000000000..0a312641e --- /dev/null +++ b/doc/quick_start/simulation/heartbeat/heartbeat.vhdl @@ -0,0 +1,20 @@ +library ieee; +use ieee.std_logic_1164.all; + +entity heartbeat is + port ( clk: out std_logic); +end heartbeat; + +architecture behaviour of heartbeat +is + constant clk_period : time := 10 ns; +begin + -- Clock process definition + clk_process: process + begin + clk <= '0'; + wait for clk_period/2; + clk <= '1'; + wait for clk_period/2; + end process; +end behaviour; diff --git a/doc/quick_start/simulation/heartbeat/index.rst b/doc/quick_start/simulation/heartbeat/index.rst new file mode 100644 index 000000000..e95145095 --- /dev/null +++ b/doc/quick_start/simulation/heartbeat/index.rst @@ -0,0 +1,42 @@ +.. program:: ghdl +.. _QuickStart:heartbeat: + +`Heartbeat` module +================== + +Although :ref:`Hello world ` illustrates that `VHDL` is supported as a general purpose language, the main use case +of `GHDL` is to simulate hardware descriptions. The following block, which is saved in a file named +:file:`heartbeat.vhdl`, is an example of how to generate a 100 MHz clock signal with non-synthesisable VHDL: + +.. literalinclude:: heartbeat.vhdl + :language: vhdl + +It can be :ref:`analysed `, :ref:`elaborated ` and :ref:`run `, as you already know: + +.. code-block:: shell + + ghdl -a heartbeat.vhdl + ghdl -e heartbeat + ghdl -r heartbeat + +However, execution of the design does not terminate. At the same time, no output is shown on screen. This is because, +traditionally, hardware designs are continuously running devices which do not have a screen where to print. In this +context, inspection and verification of the behaviour is done through `waveforms `_, +which is supported by `GHDL` (see :ref:`export_waves`). You can use either :option:`--wave`, :option:`--vcd`, +:option:`--vcdgz` or :option:`--fst` to save the signals of the simulation to a file. Then, terminate the execution +(:kbd:`C-c`) and you can inspect the wave with a viewer, such as `GtkWave `_. As +explained in the `manual `_, GtkWave *'relies on a post-mortem approach +through the use of dumpfiles'*. Therefore, you should first simulate your design and dump a waveform file, say GHW: + +.. code-block:: shell + + ghdl -r heartbeat --wave=wave.ghw + +Then, you can view the dump: + +.. code-block:: shell + + gtkwave wave.ghw + +Of course, manually terminating the simulation is for illustration purposes only. In :ref:`Full adder ` and +:ref:`QuickStart:DLX`, you will see how to write a testbench to terminate the simulation programmatically. diff --git a/doc/quick_start/simulation/hello/hello.vhdl b/doc/quick_start/simulation/hello/hello.vhdl new file mode 100644 index 000000000..4d969c6a8 --- /dev/null +++ b/doc/quick_start/simulation/hello/hello.vhdl @@ -0,0 +1,17 @@ +-- Hello world program +use std.textio.all; -- Imports the standard textio package. + +-- Defines a design entity, without any ports. +entity hello_world is +end hello_world; + +architecture behaviour of hello_world is +begin + process + variable l : line; + begin + write (l, String'("Hello world!")); + writeline (output, l); + wait; + end process; +end behaviour; diff --git a/doc/quick_start/simulation/hello/index.rst b/doc/quick_start/simulation/hello/index.rst new file mode 100644 index 000000000..104a12efa --- /dev/null +++ b/doc/quick_start/simulation/hello/index.rst @@ -0,0 +1,53 @@ +.. program:: ghdl +.. _QuickStart:hello: + +`Hello world` program +===================== + +To illustrate the general purpose of `VHDL`, the following block is a commented `Hello world` program which is saved in +a file named :file:`hello.vhdl`: + +.. literalinclude:: hello.vhdl + :language: vhdl + +.. TIP:: + + * Both ``.vhdl`` and ``.vhd`` extensions are used for `VHDL` source files, while ``.v`` is used for Verilog. + + * Since, extension ``.vhd`` is also interpreted as a `Virtual Hard Disk `_ + file format, some users prefer ``.vhdl``, to avoid ambiguity. This is the case with `GHDL`'s codebase. However, in order + to maintain `backward-compatibility `_ with legacy DOS systems, + other users prefer ``.vhd``. + + * Unless you use especial characters, either `UTF-8` or `ISO-8859-1` encodings can be used. However, if you do, the + latter should be used. The standard defines ASCII (7-bit encoding) or ISO Latin-1 (ISO-8859-1) as default. + However, GHDL has a relaxing option, :option:`--mb-comments` (multi byte), to allow UTF-8 or other encodings in + comments. + +- First, you have to compile the file; this is called :ref:`analysis ` of a design file in `VHDL` + terms. Run ``ghdl -a hello.vhdl`` in the `shell`. This command creates or updates a file :file:`work-obj93.cf`, which + describes the library ``work``. +- Then, run ``ghdl -e hello_world`` in the `shell`. Command :option:`-e` means :ref:`elaborate `, + which is used to build a design, with the ``hello_world`` entity at the top of the hierarchy. +- Last, you can directly launch the simulation :ref:`running ` ``ghdl -r hello_world`` in the `shell`. The + result of the simulation will be shown on screen: + +.. code-block:: shell + + Hello world! + +.. HINT:: + If a GCC/LLVM variant of `GHDL` is used: + + * :ref:`Analysis ` generates a file, :file:`hello.o`, which is the object file corresponding to + your `VHDL` program. This is not created with :ref:`mcode `. These kind of object files can be + compiled into foreign programs (see :ref:`Linking_with_Ada`). + * The :ref:`elaboration ` step is mandatory after running the analysis and prior to launching the + simulation. This will generate an executable binary named :file:`hello_world`. + * As a result, :option:`-r` is just a passthrough to the binary generated in the `elaboration`. Therefore, the + executable can be run directly: ``./hello_world``. See :option:`-r` for more informartion. + +.. HINT:: + + :option:`-e` can be bypassed with :ref:`mcode `, since :option:`-r` actually elaborates the design and saves + it on memory before running the simulation. But you can still use it to check for some elaboration problems. diff --git a/doc/quick_start/simulation/index.rst b/doc/quick_start/simulation/index.rst new file mode 100644 index 000000000..8e41a453b --- /dev/null +++ b/doc/quick_start/simulation/index.rst @@ -0,0 +1,52 @@ +.. program:: ghdl +.. _USING:QuickStart:Simulation: + +Simulation +########## + +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. + +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). + + * 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:`--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``. + +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, +in the hope of helping understand the different use cases: + +.. toctree:: + + 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 -- cgit v1.2.3