From b4d4d9abb322ed0807d2ba0888e73820499aa338 Mon Sep 17 00:00:00 2001 From: Unai Martinez-Corral <38422348+umarcor@users.noreply.github.com> Date: Sat, 26 Jun 2021 19:40:25 +0100 Subject: Codacy issues, Travis cleanup and update ghdl.texi (#1807) * ghw: fix memleaks reported by codacy * ghw: printf issues and style (GNU indent) * testsuite/gna: minor printf issues * testsuite: fix issues reported by codacy * scripts/ci-run: clean travis stuff (deprecated) * scripts: fix issues reported by codacy * doc/Makefile: add .PHONY * doc: update ghdl.texi * testsuite/synth: use synth_tb --- doc/Makefile | 2 + doc/ghdl.texi | 50979 +++++++++++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 47053 insertions(+), 3928 deletions(-) (limited to 'doc') diff --git a/doc/Makefile b/doc/Makefile index b094368e1..0bad2ab5b 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -12,6 +12,8 @@ ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees -T -D language=en $(PAPEROPT_$(PAPER)) all: ghdl.info +.PHONY: ghdl.texi + #--- man: diff --git a/doc/ghdl.texi b/doc/ghdl.texi index 16a2e2d70..da2aa4d51 100644 --- a/doc/ghdl.texi +++ b/doc/ghdl.texi @@ -3,7 +3,7 @@ @setfilename GHDL.info @documentencoding UTF-8 @ifinfo -@*Generated by Sphinx 1.8.2.@* +@*Generated by Sphinx 3.3.1.@* @end ifinfo @settitle GHDL Documentation @defindex ge @@ -21,11 +21,11 @@ @copying @quotation -GHDL 0.37-dev, Sep 20, 2019 +GHDL 2.0.0-dev, Jun 26, 2021 Tristan Gingold and contributors -Copyright @copyright{} 2002-2019, Tristan Gingold and contributors +Copyright @copyright{} 2002-2021, Tristan Gingold and contributors @end quotation @end copying @@ -47,8 +47,10 @@ Copyright @copyright{} 2002-2019, Tristan Gingold and contributors @end ifnottex @c %**start of body -@anchor{index doc}@anchor{0} -@c # preload commonly known graphical characters like (c) +@anchor{index doc}@anchor{3c} +@c # Load pre-defined aliases and graphical characters like © from docutils +@c # is used to denote the special path +@c # \Lib\site-packages\docutils\parsers\rst\include @c This data file has been placed in the public domain. @@ -57,23 +59,27 @@ Copyright @copyright{} 2002-2019, Tristan Gingold and contributors @c Processed by unicode2rstsubs.py, part of Docutils: @c . -@c # define a hard kine break for HTML - - +@c This data file has been placed in the public domain. -__________________________________________________________________ +@c Derived from the Unicode character mappings available from +@c . +@c Processed by unicode2rstsubs.py, part of Docutils: +@c . +@c # define a hard line break for HTML -This manual 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. +@c # Load pre-defined aliases and graphical characters like © from docutils +@c # is used to denote the special path +@c # \Lib\site-packages\docutils\parsers\rst\include -This document was generated on Sep 20, 2019 - 03:55. +@c This data file has been placed in the public domain. -@c # preload commonly known graphical characters like (c) +@c Derived from the Unicode character mappings available from +@c . +@c Processed by unicode2rstsubs.py, part of Docutils: +@c . @c This data file has been placed in the public domain. @@ -82,279 +88,487 @@ This document was generated on Sep 20, 2019 - 03:55. @c Processed by unicode2rstsubs.py, part of Docutils: @c . -@c # define a hard kine break for HTML +@c # define a hard line break for HTML @menu -* About GHDL:: -* Contributing:: -* Copyrights | Licenses:: -* Quick Start Guide:: -* Invoking GHDL:: -* Simulation and runtime:: -* Interfacing to other languages:: -* Releases and sources:: -* Building GHDL from Sources:: -* Precompile Vendor Primitives:: -* Command Reference:: -* Coding Style:: -* Implementation of VHDL:: -* Implementation of VITAL:: -* Roadmap | Future Improvements:: -* Meta:: -* Index: Index<2>. -* Index:: +* About:: +* Getting | Installing:: +* Contributing:: +* Copyrights | Licenses:: +* Quick Start Guide:: +* Invoking GHDL:: +* Simulation (runtime): Simulation runtime. +* Synthesis:: +* Additional Command Reference:: +* Implementation of VHDL:: +* Implementation of VITAL:: +* Directory structure:: +* Building GHDL from Sources:: +* pyGHDL:: +* GHDL Waveform (GHW): GHDL Waveform GHW. +* Debugging:: +* Coding Style:: +* Scripts:: +* Overview:: +* Front-end:: +* AST:: +* Run Time Information (RTI): Run Time Information RTI. +* GNATdoc:: +* Index: Index<2>. +* Python Module Index: Python Module Index<2>. +* Python Module Index:: +* Index:: @detailmenu --- The Detailed Node Listing --- -About GHDL +About + +* What is VHDL?:: +* What is GHDL?:: +* Who uses GHDL?:: + +Getting | Installing + +* Package managers:: +* Nightly packages:: +* Precompile Vendor Primitives:: -* What is VHDL?:: -* What is GHDL?:: -* Who uses GHDL?:: +Precompile Vendor Primitives + +* Supported Vendors Libraries:: +* Supported Simulation and Verification Libraries:: +* Script Configuration:: +* Compiling in Bash:: +* Compiling in PowerShell:: +* Configuration Files:: +* Additional Script Parameters:: + +Configuration Files + +* For Bash; config.sh: For Bash config sh. +* For PowerShell; config.psm1: For PowerShell config psm1. + +Additional Script Parameters + +* For Bash Scripts;: For Bash Scripts. +* For PowerShell Scripts;: For PowerShell Scripts. Contributing -* Reporting bugs:: -* Requesting enhancements:: -* Improving the documentation:: -* Fork@comma{} modify and pull-request: Fork modify and pull-request. -* Related interesting projects:: +* Reporting bugs:: +* Requesting enhancements:: +* Improving the documentation:: +* Fork@comma{} modify and pull-request: Fork modify and pull-request. +* Related interesting projects:: Copyrights | Licenses -* GNU GPLv2:: -* CC-BY-SA:: -* List of Contributors:: +* GNU GPLv2:: +* CC-BY-SA:: +* List of Contributors:: Quick Start Guide -* The ‘Hello world’ program:: -* The heartbeat program:: -* A full adder:: -* Starting with a design:: -* Starting with your design:: +* Simulation:: +* Python Interfaces:: + +Simulation + +* Hello world program:: +* Heartbeat module:: +* Full adder module and testbench:: +* Working with non-trivial designs:: + +Python Interfaces + +* Language Server:: + +Language Server + +* ghdl-ls:: + +ghdl-ls + +* optional arguments:: Invoking GHDL -* Design building commands:: -* Design rebuilding commands:: -* Options:: -* Warnings:: -* Diagnostics Control:: -* Library commands:: -* VPI build commands:: -* IEEE library pitfalls:: +* Design building commands:: +* Design rebuilding commands:: +* Options:: +* Warnings:: +* Diagnostics Control:: +* Library commands:: +* VPI/VHPI build commands:: +* IEEE library pitfalls:: Design building commands -* Analysis [-a]:: -* Elaboration [-e]:: -* Run [-r]:: -* Elaborate and run [--elab-run]:: -* Check syntax [-s]:: -* Analyze and elaborate [-c]:: +* Analysis [-a]:: +* Elaboration [-e]:: +* Run [-r]:: +* Elaborate and run [--elab-run]:: +* Check syntax [-s]:: +* Analyze and elaborate [-c]:: Design rebuilding commands -* Import [-i]:: -* Make [-m]:: -* Generate Makefile [--gen-makefile]:: -* Generate dependency file command [--gen-depends]:: +* Import [-i]:: +* Elab-order [--elab-order]:: +* Make [-m]:: +* Generate Makefile [--gen-makefile]:: +* Generate dependency file command [--gen-depends]:: -Library commands +Simulation (runtime) -* Directory [--dir]:: -* Clean [--clean]:: -* Remove [--remove]:: -* Copy [--copy]:: +* Simulation options:: +* Export waveforms:: +* Export hierarchy and references:: -VPI build commands +Synthesis -* compile [--vpi-compile]:: -* link [--vpi-link]:: -* cflags [--vpi-cflags]:: -* ldflags [--vpi-ldflags]:: -* include dir [--vpi-include-dir]:: -* library dir [--vpi-library-dir]:: +* Synthesis [--synth]:: +* Synthesis options:: +* Yosys plugin:: -Simulation and runtime +Synthesis options -* Simulation options:: -* Export waveforms:: -* Export hierarchy and references:: -* Debugging:: +* Assertions@comma{} PSL and formal verification: Assertions PSL and formal verification. -Debugging +Yosys plugin -* GNU Debugger (GDB): GNU Debugger GDB. +* Convert (V)HDL to other formats: Convert V HDL to other formats. -Interfacing to other languages +Convert (V)HDL to other formats -* Foreign declarations:: -* Linking foreign object files to GHDL:: -* Wrapping and starting a GHDL simulation from a foreign program:: -* Linking GHDL to Ada/C:: -* Dynamically loading foreign objects from GHDL:: -* Dynamically loading GHDL:: -* Using GRT from Ada:: +* To Verilog:: +* To EDIF:: +* To SMT:: +* To BTOR2:: +* To FIRRTL:: +* To VHDL:: -Foreign declarations +Additional Command Reference -* Restrictions on foreign declarations:: +* Environment variables:: +* Misc commands:: +* File commands:: +* GCC/LLVM only commands:: +* Options: Options<2>. +* Passing options to other programs:: -Releases and sources +Misc commands + +* Help [-h]:: +* Display config [--disp-config]:: +* Display standard [--disp-standard]:: +* Version [--version]:: + +File commands + +* Format [fmt]:: +* Pretty print [--pp-html]:: +* Find [-f]:: +* Chop [--chop]:: +* Lines [--lines]:: +* XML tree generation [--file-to-xml]:: + +GCC/LLVM only commands + +* Bind [--bind]:: +* Link [--link]:: +* List link [--list-link]:: + +Implementation of VHDL + +* VHDL standards:: +* PSL support:: +* Source representation:: +* Library database:: +* Top entity:: +* Using vendor libraries:: + +PSL support + +* PSL implementation:: +* PSL usage:: + +PSL usage + +* PSL annotations embedded in comments:: +* PSL annotations (VHDL-2008 only): PSL annotations VHDL-2008 only. +* PSL vunit files (VHDL-2008 / Synthesis only): PSL vunit files VHDL-2008 / Synthesis only. + +Implementation of VITAL -* Downloading pre-built packages:: -* Downloading Source Files:: +* VITAL packages:: +* VHDL restrictions for VITAL:: +* Backannotation:: +* Negative constraint calculation:: Building GHDL from Sources -* Directory structure:: -* mcode backend:: -* LLVM backend:: -* GCC backend:: +* Sources:: +* mcode backend:: +* LLVM backend:: +* GCC backend:: +* TL;DR:: mcode backend -* GCC/GNAT; GNU/Linux or Windows (MinGW/MSYS2): GCC/GNAT GNU/Linux or Windows MinGW/MSYS2. -* GNAT GPL; Windows: GNAT GPL Windows. +* GCC/GNAT; GNU/Linux or Windows (MinGW/MSYS2): GCC/GNAT GNU/Linux or Windows MinGW/MSYS2. +* GNAT GPL; Windows: GNAT GPL Windows. LLVM backend -* GCC/GNAT; GNU/Linux or Windows (MinGW/MSYS2): GCC/GNAT GNU/Linux or Windows MinGW/MSYS2<2>. +* GCC/GNAT; GNU/Linux or Windows (MinGW/MSYS2): GCC/GNAT GNU/Linux or Windows MinGW/MSYS2<2>. + +pyGHDL + +* pyGHDL.cli: pyGHDL cli. +* pyGHDL.dom: pyGHDL dom. +* pyGHDL.libghdl: pyGHDL libghdl. +* pyGHDL.lsp: pyGHDL lsp. + +pyGHDL.cli + +* pyGHDL.cli.DOM: pyGHDL cli DOM. +* pyGHDL.cli.lsp: pyGHDL cli lsp. + +pyGHDL.dom + +* pyGHDL.dom.Aggregates: pyGHDL dom Aggregates. +* pyGHDL.dom.Common: pyGHDL dom Common. +* pyGHDL.dom.DesignUnit: pyGHDL dom DesignUnit. +* pyGHDL.dom.Expression: pyGHDL dom Expression. +* pyGHDL.dom.InterfaceItem: pyGHDL dom InterfaceItem. +* pyGHDL.dom.Literal: pyGHDL dom Literal. +* pyGHDL.dom.Misc: pyGHDL dom Misc. +* pyGHDL.dom.NonStandard: pyGHDL dom NonStandard. +* pyGHDL.dom.Object: pyGHDL dom Object. +* pyGHDL.dom.Range: pyGHDL dom Range. +* pyGHDL.dom.Subprogram: pyGHDL dom Subprogram. +* pyGHDL.dom.Symbol: pyGHDL dom Symbol. +* pyGHDL.dom.Type: pyGHDL dom Type. +* pyGHDL.dom._Translate: pyGHDL dom _Translate. +* pyGHDL.dom._Utils: pyGHDL dom _Utils. +* pyGHDL.dom.formatting: pyGHDL dom formatting. + +pyGHDL.dom.formatting + +* pyGHDL.dom.formatting.prettyprint: pyGHDL dom formatting prettyprint. + +pyGHDL.libghdl + +* pyGHDL.libghdl._decorator: pyGHDL libghdl _decorator. +* pyGHDL.libghdl._types: pyGHDL libghdl _types. +* pyGHDL.libghdl.errorout: pyGHDL libghdl errorout. +* pyGHDL.libghdl.errorout_console: pyGHDL libghdl errorout_console. +* pyGHDL.libghdl.errorout_memory: pyGHDL libghdl errorout_memory. +* pyGHDL.libghdl.files_map: pyGHDL libghdl files_map. +* pyGHDL.libghdl.files_map_editor: pyGHDL libghdl files_map_editor. +* pyGHDL.libghdl.flags: pyGHDL libghdl flags. +* pyGHDL.libghdl.libraries: pyGHDL libghdl libraries. +* pyGHDL.libghdl.name_table: pyGHDL libghdl name_table. +* pyGHDL.libghdl.std_names: pyGHDL libghdl std_names. +* pyGHDL.libghdl.utils: pyGHDL libghdl utils. +* pyGHDL.libghdl.version: pyGHDL libghdl version. +* pyGHDL.libghdl.vhdl: pyGHDL libghdl vhdl. + +pyGHDL.libghdl.vhdl + +* pyGHDL.libghdl.vhdl.canon: pyGHDL libghdl vhdl canon. +* pyGHDL.libghdl.vhdl.elocations: pyGHDL libghdl vhdl elocations. +* pyGHDL.libghdl.vhdl.flists: pyGHDL libghdl vhdl flists. +* pyGHDL.libghdl.vhdl.formatters: pyGHDL libghdl vhdl formatters. +* pyGHDL.libghdl.vhdl.ieee: pyGHDL libghdl vhdl ieee. +* pyGHDL.libghdl.vhdl.lists: pyGHDL libghdl vhdl lists. +* pyGHDL.libghdl.vhdl.nodes: pyGHDL libghdl vhdl nodes. +* pyGHDL.libghdl.vhdl.nodes_meta: pyGHDL libghdl vhdl nodes_meta. +* pyGHDL.libghdl.vhdl.nodes_utils: pyGHDL libghdl vhdl nodes_utils. +* pyGHDL.libghdl.vhdl.parse: pyGHDL libghdl vhdl parse. +* pyGHDL.libghdl.vhdl.sem: pyGHDL libghdl vhdl sem. +* pyGHDL.libghdl.vhdl.sem_lib: pyGHDL libghdl vhdl sem_lib. +* pyGHDL.libghdl.vhdl.std_package: pyGHDL libghdl vhdl std_package. +* pyGHDL.libghdl.vhdl.tokens: pyGHDL libghdl vhdl tokens. + +pyGHDL.lsp + +* pyGHDL.lsp.document: pyGHDL lsp document. +* pyGHDL.lsp.lsp: pyGHDL lsp lsp. +* pyGHDL.lsp.lsptools: pyGHDL lsp lsptools. +* pyGHDL.lsp.references: pyGHDL lsp references. +* pyGHDL.lsp.symbols: pyGHDL lsp symbols. +* pyGHDL.lsp.version: pyGHDL lsp version. +* pyGHDL.lsp.vhdl_ls: pyGHDL lsp vhdl_ls. +* pyGHDL.lsp.workspace: pyGHDL lsp workspace. + +GHDL Waveform (GHW) + +* libghw:: +* ghwdump:: -Precompile Vendor Primitives +Debugging -* Supported Vendors Libraries:: -* Supported Simulation and Verification Libraries:: -* Script Configuration:: -* Compiling on Linux:: -* Compiling on Windows:: -* Configuration Files:: +* Simulation and runtime debugging options:: -Configuration Files +Simulation and runtime debugging options -* For Linux; config.sh: For Linux config sh. -* For Windows; config.psm1: For Windows config psm1. -* Selectable Options for the Bash Scripts;: Selectable Options for the Bash Scripts. -* Selectable Options for the PowerShell Scripts;: Selectable Options for the PowerShell Scripts. +* GNU Debugger (GDB): GNU Debugger GDB. -Command Reference +Coding Style -* Environment variables:: -* Misc commands:: -* File commands:: -* GCC/LLVM only commands:: -* Options: Options<2>. -* Passing options to other programs:: +* Ada:: +* Shell:: +* Guidelines to edit the documentation:: +* Documentation configuration:: -Misc commands +Guidelines to edit the documentation -* Help [-h]:: -* Display config [--disp-config]:: -* Display standard [--disp-standard]:: -* Version [--version]:: +* Guidelines to edit section ‘Building’:: -File commands +Scripts -* Pretty print [--pp-html]:: -* Find [-f]:: -* Chop [--chop]:: -* Lines [--lines]:: +* pnodes:: +* pnodespy:: -GCC/LLVM only commands +pnodes -* Bind [--bind]:: -* Link [--link]:: -* List link [--list-link]:: +* positional arguments:: +* optional arguments: optional arguments<2>. -Implementation of VHDL +pnodespy -* VHDL standards:: -* PSL implementation:: -* Source representation:: -* Library database:: -* Top entity:: -* Using vendor libraries:: +* positional arguments: positional arguments<2>. +* optional arguments: optional arguments<3>. -Implementation of VITAL +AST + +* Introduction:: +* The AST in GHDL:: +* Why a meta-model ?:: +* Dealing with ownership:: +* Node Type:: -* VITAL packages:: -* VHDL restrictions for VITAL:: -* Backannotation:: -* Negative constraint calculation:: +Run Time Information (RTI) -Meta +* Useful Definitions:: +* RTI Nodes / RTII Nodes:: -* General guidelines to edit the documentation:: -* Guidelines to edit section ‘Building’:: -* Documentation configuration:: -* Dist:: +RTI Nodes / RTII Nodes + +* Architecture RTI (Ghdl_Rtin_Block): Architecture RTI Ghdl_Rtin_Block. +* Entity RTI (Ghdl_Rtin_Block): Entity RTI Ghdl_Rtin_Block. +* Other Blocks (Package/Process) (Ghdl_Rtin_Block): Other Blocks Package/Process Ghdl_Rtin_Block. +* if_generate / case_generate (Ghdl_Rtin_Block): if_generate / case_generate Ghdl_Rtin_Block. +* for_generate (Ghdl_Rtin_Generate): for_generate Ghdl_Rtin_Generate. +* instance (Ghdl_Rtin_Instance): instance Ghdl_Rtin_Instance. +* Port (Ghdl_Rtin_Object): Port Ghdl_Rtin_Object. +* Array Kinds:: +* Object_To_Base_Bound:: +* Array_Type (Ghdl_Rtin_Type_Array): Array_Type Ghdl_Rtin_Type_Array. +* Array Subtype (Ghdl_Rtin_Subtype_Array): Array Subtype Ghdl_Rtin_Subtype_Array. +* Port / Signal / Generic / Constant / Variable (Ghdl_Rtin_Object): Port / Signal / Generic / Constant / Variable Ghdl_Rtin_Object. +* Record Kinds:: +* Record Type (Ghdl_Rtin_Type_Record): Record Type Ghdl_Rtin_Type_Record. +* Record Type (Ghdl_Rtin_Type_Record): Record Type Ghdl_Rtin_Type_Record<2>. +* Element Type (Ghdl_Rtin_Element): Element Type Ghdl_Rtin_Element. +* Examples:: @end detailmenu @end menu -@node About GHDL,Contributing,Top,Top -@anchor{about doc}@anchor{1}@anchor{about about-ghdl}@anchor{2}@anchor{about ghdl-documentation}@anchor{3} -@chapter About GHDL +@node About,Getting | Installing,Top,Top +@anchor{about doc}@anchor{3d}@anchor{about about}@anchor{3e}@anchor{about ghdl}@anchor{3f} +@chapter About @menu -* What is VHDL?:: -* What is GHDL?:: -* Who uses GHDL?:: +* What is VHDL?:: +* What is GHDL?:: +* Who uses GHDL?:: @end menu -@node What is VHDL?,What is GHDL?,,About GHDL -@anchor{about intro-vhdl}@anchor{4}@anchor{about what-is-vhdl}@anchor{5} +@node What is VHDL?,What is GHDL?,,About +@anchor{about intro-vhdl}@anchor{40}@anchor{about what-is-vhdl}@anchor{41} @section What is @cite{VHDL}? -VHDL@footnote{https://en.wikipedia.org/wiki/VHDL} is an acronym for Very High Speed Integrated Circuit (VHSIC@footnote{https://en.wikipedia.org/wiki/VHSIC}) Hardware Description Language (HDL@footnote{https://en.wikipedia.org/wiki/HDL}), which is a programming language used to describe a logic circuit by function, data flow behavior, or structure. +VHDL@footnote{https://en.wikipedia.org/wiki/VHDL} is an acronym for Very High Speed Integrated Circuit (VHSIC@footnote{https://en.wikipedia.org/wiki/VHSIC}) Hardware Description +Language (HDL@footnote{https://en.wikipedia.org/wiki/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 @emph{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 @cite{C}, @cite{Python}, or @cite{Ada}. Indeed, VHDL derives most of its syntax and semantics from Ada. Knowing @cite{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 @emph{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 @cite{C}, @cite{Python}, or @cite{Ada}. Indeed, VHDL derives most of its syntax and semantics from Ada. Knowing @cite{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 @cite{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 @cite{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 @emph{simulation} is often used instead of @cite{execution}, with the same meaning. At the same time, like a design written in another @cite{HDL}, a set of VHDL sources can be transformed with a @emph{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 +@emph{simulation} is often used instead of @cite{execution}, with the same meaning. At the same time, like a design written in +another @cite{HDL}, a set of VHDL sources can be transformed with a @emph{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@footnote{https://www.ieee.org/} @cite{1076}. Four revisions exist: 1987@footnote{http://ieeexplore.ieee.org/document/26487/}, 1993@footnote{http://ieeexplore.ieee.org/document/392561/}, 2002@footnote{http://ieeexplore.ieee.org/document/1003477/} and 2008@footnote{http://ieeexplore.ieee.org/document/4772740/}. The standardization is handled by the VHDL Analysis and Standardization Group (VASG/P1076@footnote{http://www.eda-twiki.org/vasg/}). +The development of VHDL started in 1983 and the standard is named IEEE@footnote{https://www.ieee.org/} @cite{1076}. Five revisions +exist: 1987@footnote{http://ieeexplore.ieee.org/document/26487/}, 1993@footnote{http://ieeexplore.ieee.org/document/392561/}, +2002@footnote{http://ieeexplore.ieee.org/document/1003477/}, 2008@footnote{http://ieeexplore.ieee.org/document/4772740/} and +2019@footnote{https://ieeexplore.ieee.org/document/8938196}. The standardization is handled by the VHDL Analysis and +Standardization Group (VASG/P1076@footnote{http://www.eda-twiki.org/vasg/}). -@node What is GHDL?,Who uses GHDL?,What is VHDL?,About GHDL -@anchor{about intro-ghdl}@anchor{6}@anchor{about what-is-ghdl}@anchor{7} +@node What is GHDL?,Who uses GHDL?,What is VHDL?,About +@anchor{about intro-ghdl}@anchor{42}@anchor{about what-is-ghdl}@anchor{43} @section What is GHDL? -@cite{GHDL} is a shorthand for @cite{G Hardware Design Language} (currently, @cite{G} has no meaning). It is a VHDL compiler that can execute (nearly) any VHDL program. GHDL is @emph{not} a synthesis tool: you cannot create a netlist with GHDL (yet). - -Unlike some other simulators, GHDL is a compiler: it directly translates a VHDL file to machine code, without using an intermediary language such as @cite{C} or @cite{C++}. Therefore, the compiled code should be faster and the analysis time should be shorter than with a compiler using an intermediary language. +@cite{GHDL} is a shorthand for @cite{G Hardware Design Language} (currently, @cite{G} has no meaning). It is a VHDL analyzer, compiler, +simulator and (experimental) synthesizer that can process (nearly) any VHDL design. -GHDL can use multiple back-ends, i.e. code generators, (GCC@footnote{http://gcc.gnu.org/}, LLVM@footnote{http://llvm.org/} or x86@footnote{https://en.wikipedia.org/wiki/X86-64}/i386@footnote{https://en.wikipedia.org/wiki/Intel_80386} only, a built-in one) and runs on GNU/Linux@footnote{https://en.wikipedia.org/wiki/Linux_distribution}, Windows@footnote{https://en.wikipedia.org/wiki/Microsoft_Windows} ™ and macOS@footnote{https://en.wikipedia.org/wiki/MacOS} ™ , both on x86 and on x86_64. +@cartouche +@quotation Note +For almost 20 years, GHDL was @emph{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{44,,Synthesis} for further details +regarding synthesis. +@end quotation +@end cartouche -The current version of GHDL does not contain any graphical viewer: you cannot see signal waves. You can still check the behavior of your design with a test bench. Moreover, the current version can produce a GHW@footnote{http://ghdl.readthedocs.io/en/latest/using/Simulation.html?highlight=GHW#cmdoption-wave}, VCD@footnote{https://en.wikipedia.org/wiki/Value_change_dump} or @cite{FST} files which can be viewed with a waveform viewer@footnote{https://en.wikipedia.org/wiki/Waveform_viewer}, such as GtkWave@footnote{http://gtkwave.sourceforge.net/}. +Unlike some other simulators, GHDL is a compiler: it directly translates a VHDL file to machine code, without using an +intermediary language such as @cite{C} or @cite{C++}. Therefore, the compiled code should be faster and the analysis time should be +shorter than with a compiler using an intermediary language. -GHDL aims at implementing VHDL as defined by IEEE 1076@footnote{http://ieeexplore.ieee.org/document/4772740/}. It supports the 1987@footnote{http://ieeexplore.ieee.org/document/26487/}, 1993@footnote{http://ieeexplore.ieee.org/document/392561/} and 2002@footnote{http://ieeexplore.ieee.org/document/1003477/} revisions and, partially, the latest, 2008@footnote{http://ieeexplore.ieee.org/document/4772740/}. PSL@footnote{https://en.wikipedia.org/wiki/Property_Specification_Language} is also partially supported. +GHDL can use multiple back-ends, i.e. code generators, (GCC@footnote{http://gcc.gnu.org/}, LLVM@footnote{http://llvm.org/} or +x86@footnote{https://en.wikipedia.org/wiki/X86-64}/i386@footnote{https://en.wikipedia.org/wiki/Intel_80386} only, a built-in one named @emph{mcode}) and runs on GNU/Linux@footnote{https://en.wikipedia.org/wiki/Linux_distribution}, +Windows@footnote{https://en.wikipedia.org/wiki/Microsoft_Windows} ™ and macOS@footnote{https://en.wikipedia.org/wiki/MacOS} ™; on x86, x86_64, armv6/armv7/aarch32/aarch64, +ppc64, etc. -Several third party projects are supported: VUnit@footnote{https://vunit.github.io/}, OSVVM@footnote{http://osvvm.org/}, cocotb@footnote{https://github.com/potentialventures/cocotb} (through the VPI interface@footnote{https://en.wikipedia.org/wiki/Verilog_Procedural_Interface}), … +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@footnote{http://ghdl.readthedocs.io/en/latest/using/Simulation.html?highlight=GHW#cmdoption-wave}, +VCD@footnote{https://en.wikipedia.org/wiki/Value_change_dump} or @cite{FST} files can be produced, which can be viewed with a waveform viewer@footnote{https://en.wikipedia.org/wiki/Waveform_viewer}, +such as GtkWave@footnote{http://gtkwave.sourceforge.net/}. -@cartouche -@quotation Hint -Although synthesis is not supported yet, there is some experimental feature to generate RTL netlists (VHDL or EDIF) from synthesisable code. For subcommand @code{--synth} to be available, GHDL must be configured/built with option @code{--enable-synth} (GCC 8.1>= required, due to some new GNAT features which are only available in recent releases). Since this is a proof-of-concept, the output is mostly a dump of an internal structure for now. Therefore, it is not very useful, except for debugging. +GHDL aims at implementing VHDL as defined by IEEE 1076@footnote{http://ieeexplore.ieee.org/document/4772740/}. It supports the +1987@footnote{http://ieeexplore.ieee.org/document/26487/}, 1993@footnote{http://ieeexplore.ieee.org/document/392561/} and +2002@footnote{http://ieeexplore.ieee.org/document/1003477/} revisions and, partially, 2008@footnote{http://ieeexplore.ieee.org/document/4772740/}. +Property Specification Language (PSL)@footnote{https://en.wikipedia.org/wiki/Property_Specification_Language} is also partially supported. -Moreover, ghdlsynth@footnote{https://github.com/tgingold/ghdlsynth-beta} is a complementary repository that lets GHDL to be loaded by yosys@footnote{http://www.clifford.at/yosys/} as a frontend plugin module, in order to generate bitstreams for some FPGA devices. -@end quotation -@end cartouche +Several third party projects are supported: Yosys@footnote{https://github.com/YosysHQ/yosys} (through the ghdl-yosys-plugin@footnote{https://github.com/ghdl/ghdl-yosys-plugin}) +cocotb@footnote{https://github.com/potentialventures/cocotb} (through the VPI interface@footnote{https://en.wikipedia.org/wiki/Verilog_Procedural_Interface}), +VUnit@footnote{https://vunit.github.io/}, OSVVM@footnote{http://osvvm.org/}, … -@node Who uses GHDL?,,What is GHDL?,About GHDL -@anchor{about intro-who}@anchor{8}@anchor{about who-uses-ghdl}@anchor{9} +@node Who uses GHDL?,,What is GHDL?,About +@anchor{about intro-who}@anchor{45}@anchor{about who-uses-ghdl}@anchor{46} @section Who uses GHDL? -@c # preload commonly known graphical characters like (c) +@c # Load pre-defined aliases and graphical characters like © from docutils +@c # is used to denote the special path +@c # \Lib\site-packages\docutils\parsers\rst\include @c This data file has been placed in the public domain. @@ -363,2550 +577,44890 @@ Moreover, ghdlsynth@footnote{https://github.com/tgingold/ghdlsynth-beta} is a co @c Processed by unicode2rstsubs.py, part of Docutils: @c . -@c # define a hard kine break for HTML - +@c This data file has been placed in the public domain. -@node Contributing,Copyrights | Licenses,About GHDL,Top -@anchor{contribute doc}@anchor{a}@anchor{contribute contributing}@anchor{b}@anchor{contribute intro-contributing}@anchor{c} -@chapter Contributing +@c Derived from the Unicode character mappings available from +@c . +@c Processed by unicode2rstsubs.py, part of Docutils: +@c . +@c # define a hard line break for HTML -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{d,,Quick Start Guide} for an introduction. Furthermore, we encourage you to read @ref{e,,Invoking GHDL}, where the most -commonly used options are explained. You can also check the complete @ref{f,,Command Reference}. +@node Getting | Installing,Contributing,About,Top +@anchor{getting doc}@anchor{47}@anchor{getting getting-installing}@anchor{48}@anchor{getting packages}@anchor{49} +@chapter Getting | Installing -If you are more familiar with GHDL, you might start asking yourself how it works internally. If so, you might find -@ref{10,,Implementation of VHDL} and @ref{11,,Implementation of VITAL} interesting. -While using GHDL, you might find flaws, such as bugs, missing features, typos in the documentation, or topics which still are -not covered. In order to improve GHDL, we welcome bug reports, suggestions, and contributions for any aspect of -GHDL. Whether it’s a bug or an enhancement, have a look at the -@image{/Users/gingold/devel/ghdl/doc/build/doctrees/images/75d23ce669cbc7993d4d057361ad0c2a3d5d5271/ghdl,,,Open issues,svg} - and -@image{/Users/gingold/devel/ghdl/doc/build/doctrees/images/e1c1423669df5839910ed47f754b67708d362d8b/ghdl,,,Closed issues,svg} - to see -if someone already told us about it. You might find a solution there. +@menu +* Package managers:: +* Nightly packages:: +* Precompile Vendor Primitives:: -If you found no information on your topic, please, report so that we are aware! You can reach us through various ways: +@end menu -@image{/Users/gingold/devel/ghdl/doc/build/doctrees/images/16176de4998e1a71b2f57993443202b2d81671f4/chat-on%20gitter-4db797,,,Talk to us on Gitter,svg} - or open a -@image{/Users/gingold/devel/ghdl/doc/build/doctrees/images/dfb2204df41464917807ba7d4295bf10566f1193/new-issue-yellowgreen,,,Open new issue at GitHub,svg} -. +@node Package managers,Nightly packages,,Getting | Installing +@anchor{getting package-managers}@anchor{4a} +@section Package managers -@cartouche -@quotation Hint -Since the development of GHDL started fifteen years ago, multiple platforms have been used as a support for both distribution and getting feedback. However, the development is now centralized in github. -@end quotation -@end cartouche -@cartouche -@quotation Tip -How To Ask Questions The Smart Way@footnote{www.catb.org/~esr/faqs/smart-questions.html} -@end quotation -@end cartouche +Package managers of many popular distributions provide pre-built packages of GHDL. This is the case for @cite{apt} +(Debian/Ubuntu), @cite{dnf} (Fedora), @cite{pacman} (Arch Linux, MSYS2) or @cite{brew} (macOS). Since GHDL supports three different backends +and two library sets (@emph{regular} or @emph{GPL-compatible}), at least six packages with different features might be available in +each package manager. -@menu -* Reporting bugs:: -* Requesting enhancements:: -* Improving the documentation:: -* Fork@comma{} modify and pull-request: Fork modify and pull-request. -* Related interesting projects:: +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{4b,,Building GHDL from Sources}. -@end menu +@node Nightly packages,Precompile Vendor Primitives,Package managers,Getting | Installing +@anchor{getting nightly-packages}@anchor{4c}@anchor{getting release-packages}@anchor{4d} +@section Nightly packages -@node Reporting bugs,Requesting enhancements,,Contributing -@anchor{contribute id1}@anchor{12}@anchor{contribute reporting-bugs}@anchor{13} -@section Reporting bugs +Assets from nightly GHDL builds are available at github.com/ghdl/ghdl/releases/nightly@footnote{https://github.com/ghdl/ghdl/releases/nightly}. +These are mostly meant to be used in Continuous Integration (CI) workflows. Precisely, setup-ghdl-ci@footnote{https://github.com/ghdl/setup-ghdl-ci} +allows to easily setup nightly assets in GitHub Actions workflows. -@cartouche -@quotation Tip +However, users on Windows (MSYS2) or Ubuntu might want to download the tarballs/zipfiles and extract/install them locally. -@itemize * +@node Precompile Vendor Primitives,,Nightly packages,Getting | Installing +@anchor{getting getting-precompvendor}@anchor{4e}@anchor{getting precompile-vendor-primitives}@anchor{4f} +@section Precompile Vendor Primitives -@item -If the compiler crashes, this is a bug. Reliable tools never crash. -@item -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. +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 @footnote{@w{(1)} +OSVVM @indicateurl{http://github.com/OSVVM/OSVVM} +} or +UVVM @footnote{@w{(2)} +UVVM @indicateurl{https://github.com/UVVM/UVVM_All} +}, which can be pre-compiled, too. -@item -If the executable created from your VHDL sources crashes, this may be a bug at runtime or the code itself may be wrong. However, since VHDL has a notion of pointers, an erroneous VHDL program (using invalid pointers for example) may crash. +The compilation scripts are writen in the shell languages: @emph{PowerShell} for +@emph{Windows™} and @emph{Bash} for @emph{GNU/Linux}, @emph{MacOS} and @emph{MSYS2}/@emph{MinGW}. The +compile scripts can colorize the GHDL warning and error lines with the help +of @code{grc/grcat} @footnote{@w{(3)} +Generic Colourizer @indicateurl{http://kassiopeia.juls.savba.sk/~garabik/software/grc.html} +}. -@item -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. -@end itemize +@cartouche +@quotation Hint +Vendor precompile scripts for OSVVM and UVVM are tested periodically in ghdl/extended-tests@footnote{https://github.com/ghdl/extended-tests}. @end quotation @end cartouche -Please, report issues of this kind through -@image{/Users/gingold/devel/ghdl/doc/build/doctrees/images/bac95e4b3b8c2d7bfbc31a7ce9892272a524ef30/new-bug--report-yellowgreen,,,Open new bug report at GitHub,svg} -, 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. - -@cartouche -@quotation Important -As suggested in the bug report template, please elaborate a @cite{Minimal (non) Working Example} (MWE@footnote{https://en.wikipedia.org/wiki/Minimal_Working_Example}) prior to sending the report, so that the possible bug source is isolated. Should it fulfill the format requirements of issue-runner@footnote{https://github.com/1138-4EB/issue-runner}, you would be able to test your bug with the latest GHDL version. Please do so in order to ensure that the bug is not solved already. - -Also, please include enough information in the bug report, for the maintainers to reproduce the problem. The template includes: - +@menu +* Supported Vendors Libraries:: +* Supported Simulation and Verification Libraries:: +* Script Configuration:: +* Compiling in Bash:: +* Compiling in PowerShell:: +* Configuration Files:: +* Additional Script Parameters:: -@itemize * +@end menu -@item -Operating system and version of GHDL (you can get it with @code{ghdl --version}). +@node Supported Vendors Libraries,Supported Simulation and Verification Libraries,,Precompile Vendor Primitives +@anchor{getting supported-vendors-libraries}@anchor{50} +@subsection Supported Vendors Libraries -@item -Whether you have built GHDL from sources (provide short SHA of the used commit) or used the binary distribution (note which release/tag). @itemize * -@item -If you cannot compile, please report which compiler you are using and the version. -@end itemize - -@item -Content of the input files which comprise the MWE - -@item -Description of the problem: +@item +Lattice (3.6 or later): @itemize * -@item -Comment explaining whether the MWE should compile or not; if yes, whether or not is should run until the assertion. - -@item -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. +@item +@code{ec} -@item -Samples of any log. +@item +@code{ecp}, @code{ecp2}, @code{ecp3}, @code{ecp5u} -@item -Anything else that you think would be helpful. -@end itemize -@end itemize -@end quotation -@end cartouche +@item +@code{lptm}, @code{lptm2} -@cartouche -@quotation 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@footnote{http://ieeexplore.ieee.org/document/4772740/}. However, some other tools allow constructs which do not fully follow the standard revisions. Therefore, comparisons with other VHDL is not a solid argument. Some of them are supported by GHDL (see @ref{14,,IEEE library pitfalls}), but any such enhancement will have very low priority. -@end quotation -@end cartouche +@item +@code{machxo}, @code{machxo2}, @code{machxo3l}, @code{machxo3d} -@node Requesting enhancements,Improving the documentation,Reporting bugs,Contributing -@anchor{contribute id2}@anchor{15}@anchor{contribute requesting-enhancements}@anchor{16} -@section Requesting enhancements +@item +@code{sc}, @code{scm} +@item +@code{xp}, @code{xp2} +@item +… +@end itemize -@image{/Users/gingold/devel/ghdl/doc/build/doctrees/images/89dd2439936c60b66feb51ba1c0d6a38facef2d8/1561565e8455e49d1382462c9afb48178cccd06f,,,Open new feature request at GitHub,svg?logo=github&style=flat-square&longCache=true} +@item +Intel (Altera) Quartus (13.0 or later): -@image{/Users/gingold/devel/ghdl/doc/build/doctrees/images/16176de4998e1a71b2f57993443202b2d81671f4/chat-on%20gitter-4db797,,,Talk to us on Gitter,svg} +@itemize * -All enhancements and feature requests are welcome. Please open a new issue@footnote{https://github.com/ghdl/ghdl/issues/new} to report any, so you can track the request’s status and implementation. Depending on the complexity of the request, you may want to chat on Gitter@footnote{https://gitter.im/ghdl/ghdl1}, to polish it before opening an issue. +@item +@code{lpm}, @code{sgate} -@node Improving the documentation,Fork modify and pull-request,Requesting enhancements,Contributing -@anchor{contribute improving-the-documentation}@anchor{17} -@section Improving the documentation +@item +@code{altera}, @code{altera_mf}, @code{altera_lnsim} +@item +@code{arriaii}, @code{arriaii_pcie_hip}, @code{arriaiigz} -If you found a mistake in the documentation, please send a comment. If you didn’t understand some parts of this manual, -please tell us. English is not our mother tongue, so this documentation may not be well-written. +@item +@code{arriav}, @code{arriavgz}, @code{arriavgz_pcie_hip} -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 @cite{reStructuredText} and @cite{Markdown} sources, you can fork, modify and request the -maintainers to pull your copy. See @ref{18,,Fork@comma{} modify and pull-request}. +@item +@code{cycloneiv}, @code{cycloneiv_pcie_hip}, @code{cycloneive} -@node Fork modify and pull-request,Related interesting projects,Improving the documentation,Contributing -@anchor{contribute fork-modify-and-pull-request}@anchor{19}@anchor{contribute pull-request}@anchor{18} -@section Fork, modify and pull-request +@item +@code{cyclonev} +@item +@code{max}, @code{maxii}, @code{maxv} -@cartouche -@quotation Tip +@item +@code{stratixiv}, @code{stratixiv_pcie_hip} -@itemize * +@item +@code{stratixv}, @code{stratixv_pcie_hip} -@item -Before starting any modification, you might want to have a look at -@image{/Users/gingold/devel/ghdl/doc/build/doctrees/images/c3a4692a25333d57bb8c1ce54f97f15c6846ba63/ghdl,,,Open pull requests,svg} - and -@image{/Users/gingold/devel/ghdl/doc/build/doctrees/images/6497f995f9ef9e87d1fe97a236cebe38959dc915/ghdl,,,Closed pull requests,svg} -, to check which other contributions are being made or have been made. If you observe that the modifications you are about to start might conflict with any other, please -@image{/Users/gingold/devel/ghdl/doc/build/doctrees/images/16176de4998e1a71b2f57993443202b2d81671f4/chat-on%20gitter-4db797,,,Talk to us on Gitter,svg} - or open a -@image{/Users/gingold/devel/ghdl/doc/build/doctrees/images/82b759af84cd517081b3c031dfbe444f16595fb9/f125673efc1475d3e54f355fd17e00e44587099a,,,Open new Pull Request (PR) at GitHub,svg?logo=github&style=flat-square&longCache=true} - to coordinate. +@item +@code{fiftyfivenm}, @code{twentynm} -@item -See section @ref{1a,,Directory structure} to faster find the location of the sources you need to modify, and/or to know where to place new ones. +@item +… @end itemize -@end quotation -@end cartouche -Contributing source code/documentation via Git@footnote{https://git-scm.com/} is very easy. Although we don’t provide direct -write access to our repositories, the project is hosted at GitHub, which follows a fork, edit and pull-request -flow@footnote{https://help.github.com/articles/github-flow/} . That is: +@item +Xilinx ISE (14.0 or later): -@enumerate +@itemize * -@item -Make a copy (fork@footnote{https://help.github.com/articles/fork-a-repo/}) of the project. +@item +@code{unisim} (incl. @code{secureip}) -@item -Do the changes you wish (edit, add, rename, move and/or delete). +@item +@code{unimacro} -@item -When you think that the changes are ready to be merged, notify the maintainers by opening a Pull Request@footnote{https://help.github.com/articles/creating-a-pull-request/} (PR). +@item +@code{simprim} (incl. @code{secureip}) -@item -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. +@item +@code{xilinxcorelib} +@end itemize -@item -Last, the maintainers will merge your branch. You will be notified, the PR will be closed, and you’ll be allowed to delete the branch, if you want. -@end enumerate +@item +Xilinx Vivado (2014.1 or later): -@cartouche -@quotation Tip @itemize * -@item -It is recommended to read A successful Git branching model@footnote{http://nvie.com/posts/a-successful-git-branching-model/} for a reference on how maintainers expect to handle multiple branches. However, our actual model is not as exhaustive as explained there. - -@item -Some commit messages can automatically close@footnote{https://help.github.com/articles/closing-issues-via-commit-messages/} issues. This is a very useful feature, which you are not required to use. However beware that using @cite{fix} anywhere in the commit message can have side effects. If you closed any issue unexpectedly, just reply to it (even if it’s closed) so that maintainers can check it. +@item +@code{unisim} (incl. @code{secureip}) -@item -It is recommended to read @ref{1b,,Coding Style} before contributing modifications to Ada sources. +@item +@code{unimacro} +@end itemize @end itemize -@end quotation -@end cartouche -@node Related interesting projects,,Fork modify and pull-request,Contributing -@anchor{contribute related-interesting-projects}@anchor{1c} -@section Related interesting projects +@node Supported Simulation and Verification Libraries,Script Configuration,Supported Vendors Libraries,Precompile Vendor Primitives +@anchor{getting supported-simulation-and-verification-libraries}@anchor{51} +@subsection Supported Simulation and Verification Libraries -If you have an interesting project, please send us feedback or get listed on our @ref{8,,Who uses GHDL?} page. -@c # preload commonly known graphical characters like (c) +@itemize * -@c This data file has been placed in the public domain. +@item +OSVVM @footnote{@w{(1)} +OSVVM @indicateurl{http://github.com/OSVVM/OSVVM} +} (for VHDL-2008) -@c Derived from the Unicode character mappings available from -@c . -@c Processed by unicode2rstsubs.py, part of Docutils: -@c . +@item +UVVM @footnote{@w{(2)} +UVVM @indicateurl{https://github.com/UVVM/UVVM_All} +} (for VHDL-2008) +@end itemize -@c # define a hard kine break for HTML -@node Copyrights | Licenses,Quick Start Guide,Contributing,Top -@anchor{licenses doc}@anchor{1d}@anchor{licenses copyrights-licenses}@anchor{1e}@anchor{licenses intro-copyrights}@anchor{1f} -@chapter Copyrights | Licenses +__________________________________________________________________ +@node Script Configuration,Compiling in Bash,Supported Simulation and Verification Libraries,Precompile Vendor Primitives +@anchor{getting script-configuration}@anchor{52} +@subsection Script Configuration -@itemize - -@item -The GHDL front-end package @code{std.textio}, and the runtime library @code{grt} are given under @ref{20,,GNU GPLv2}. +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 @code{--source} (Bash) or @code{-Source} +(PoSh). -@item -The documentation is given under @ref{21,,CC-BY-SA}. -@end itemize +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 @code{--output} (Bash) or @code{-Output} (PoSh). -@cartouche -@quotation Warning -As a consequence of the runtime copyright, you are not allowed to distribute an executable produced by GHDL without the VHDL sources. To my mind, this is not a real restriction, since it is pointless to distribute VHDL executable. Please, send a comment (@ref{16,,Requesting enhancements}) if you don’t like this policy. -@end quotation -@end cartouche +To compile all source files with GHDL, the simulator executable is searched in +@code{PATH}. The found default GHDL executable can be overwritten by setting the +environment variable @code{GHDL} or by passing the parameter @code{--ghdl} (Bash) or +@code{-GHDL} (PoSh) to the scripts. +If the vendor library compilation is used very often, it’s recommend to configure +these parameters in @code{config.sh} (Bash) or @code{config.psm1} (PoSh), so the command +line can be shortened to the essential parts. -@itemize - -@item -The following packages are copyrighted by third parties (see corresponding sources for more information): +__________________________________________________________________ -@quotation +@node Compiling in Bash,Compiling in PowerShell,Script Configuration,Precompile Vendor Primitives +@anchor{getting compiling-in-bash}@anchor{53} +@subsection Compiling in Bash -@itemize - -@item -These from library @code{ieee} are copyrighted by Institute of Electrical and Electronics Engineers (IEEE)@footnote{https://www.ieee.org} : +The provided Bash scripts support these environments: -@quotation +@itemize * -@itemize - +@item +Linux -@item -@code{numeric_bit} and @code{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@footnote{http://ieeexplore.ieee.org/document/592543/} ] +@item +MacOS -@item -@code{std_logic_1164}, @code{Math_Real} and @code{Math_Complex} +@item +MSYS2 / MinGW -@item -@code{VITAL_Primitives}, @code{VITAL_Timing} and @code{VITAL_Memory} [see also IEEE 1076.4@footnote{http://ieeexplore.ieee.org/document/954750/} ] +@item +WSL (Windows Subsystem for Linux) @end itemize -@end quotation -@item -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. +Follow these steps: -@quotation +@itemize * -@itemize - +@item +@strong{Step 0 - Configure the scripts (optional)} -@item -@code{synopsys} directory: @code{std_logic_arith}, @code{std_logic_signed}, @code{std_logic_unsigned} and @code{std_logic_textio} are copyrighted by Synopsys@comma{} Inc.@footnote{https://www.synopsys.com/} +See the next section for how to configure @code{config.sh}. -@item -@code{mentor} directory: @code{std_logic_arith} is copyrighted by Mentor Graphics@footnote{https://www.mentor.com} -@end itemize -@end quotation -@end itemize -@end quotation -@end itemize +@item +@strong{Step 1 - Browse to your simulation working directory} -@menu -* GNU GPLv2:: -* CC-BY-SA:: -* List of Contributors:: +@example +$ cd +@end example -@end menu +@item +@strong{Step 2 - Start the compilation script(s)} -@node GNU GPLv2,CC-BY-SA,,Copyrights | Licenses -@anchor{licenses gnu-gplv2}@anchor{22}@anchor{licenses lic-gplv2}@anchor{20} -@section GNU GPLv2 +Choose one or multiple of the following scripts to run the pre-compilation +process. +@example +$ /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 +@end example -GHDL is copyright © 2002 - 2019 Tristan Gingold. +In most cases GHDL is installed into @code{/usr/local/}. The scripts are +installed into the @code{lib\ghdl\vendors} directory. -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. +@item +@strong{Step 3 - Viewing the result} -This program is distributed in the hope that it will be useful, but @strong{WITHOUT ANY WARRANTY}; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License@footnote{https://www.gnu.org/licenses/old-licenses/gpl-2.0.html} for more details. +This creates vendor directories in your current working directory and +compiles the vendor files into them. -@node CC-BY-SA,List of Contributors,GNU GPLv2,Copyrights | Licenses -@anchor{licenses cc-by-sa}@anchor{23}@anchor{licenses lic-cc-by-sa}@anchor{21} -@section CC-BY-SA +@example +$ 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 +@end example +@end itemize -This is a free documentation; you can redistribute it and/or modify it under the terms of the Creative Commons Attribution-ShareAlike 4.0@footnote{https://creativecommons.org/licenses/by-sa/4.0/} license. You are free to @strong{share} (copy and redistribute the material in any medium or format) and/or @strong{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: +__________________________________________________________________ -@itemize - +@node Compiling in PowerShell,Configuration Files,Compiling in Bash,Precompile Vendor Primitives +@anchor{getting compiling-in-powershell}@anchor{54} +@subsection Compiling in PowerShell -@item -@strong{Attribution}: you must provide the name of the creator and attribution parties (more info@footnote{https://wiki.creativecommons.org/wiki/License_Versions#Detailed_attribution_comparison_chart}), a copyright notice, a license notice, a disclaimer notice, a link to the material, a link to the license and indicate if changes were made (see marking guide@footnote{https://wiki.creativecommons.org/wiki/Best_practices_for_attribution#This_is_a_good_attribution_for_material_you_modified_slightly} and more info@footnote{https://wiki.creativecommons.org/wiki/License_Versions#Modifications_and_adaptations_must_be_marked_as_such}). You may do so in any reasonable manner, but not in any way that suggests we endorse you or your use. -@item -@strong{ShareAlike}: if you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original. +The provided PowerShell scripts support these environments: -@item -@strong{No additional restrictions}: you may not apply legal terms or technological measures that legally restrict others from doing anything the license permits. + +@itemize * + +@item +Windows™ 10 (PowerShell 5 and PowerShell 6) @end itemize -See CC-BY-SA-4.0 Legal Code@footnote{https://creativecommons.org/licenses/by-sa/4.0/legalcode.txt} for more details. +Follow these steps: -@node List of Contributors,,CC-BY-SA,Copyrights | Licenses -@anchor{licenses lic-contributors}@anchor{24}@anchor{licenses list-of-contributors}@anchor{25} -@section List of Contributors +@itemize * +@item +@strong{Step 0 - Configure the scripts (optional)} -@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} -@headitem +See the next section for how to configure @code{config.psm1}. -Contributor @footnote{ -In alphabetical order -} +@item +@strong{Step 1 - Browse to your simulation working directory} -@tab +@example +PS> cd +@end example -Role +@item +@strong{Step 2 - Start the compilation script(s)} -@item +Choose one or multiple of the following scripts to run the pre-compilation +process. -Baggett, Jonas +@example +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 +@end example -@tab +@c # In most cases GHDL is installed into ``/usr/local/``. -signal selection +The scripts are installed into the @code{lib\ghdl\vendors} directory. -@item +@item +@strong{Step 3 - Viewing the result} -Bertram, Felix +This creates vendor directories in your current working directory and +compiles the vendor files into them. -@tab +@example +PS> dir + Directory: D:\temp\ghdl -VPI interface +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 +@end example +@end itemize -@item -Davis, Brian +__________________________________________________________________ -@tab -Windows Mcode builds +@node Configuration Files,Additional Script Parameters,Compiling in PowerShell,Precompile Vendor Primitives +@anchor{getting configuration-files}@anchor{55} +@subsection Configuration Files -@item -Drummond, Brian +@menu +* For Bash; config.sh: For Bash config sh. +* For PowerShell; config.psm1: For PowerShell config psm1. -@tab +@end menu -GCC 4.8.2 update, OSVVM port, some bugfixes +@node For Bash config sh,For PowerShell config psm1,,Configuration Files +@anchor{getting for-bash-config-sh}@anchor{56} +@subsubsection For Bash: @cite{config.sh} -@item -Gingold, Tristan @footnote{ -Maintainer -} +Please open the @code{config.sh} file and set the dictionary entries for the +installed vendor tools to your tool’s installation directories. Use an empty +string @code{""} for not installed tools. -@tab +@code{config.sh}: -@strong{Sole author of GHDL as a whole} +@example +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" +@end example -@item +@node For PowerShell config psm1,,For Bash config sh,Configuration Files +@anchor{getting for-powershell-config-psm1}@anchor{57} +@subsubsection For PowerShell: @cite{config.psm1} -Jensen, Adam -@tab +Please open the @code{config.psm1} file and set the dictionary entries for the +installed vendor tools to your tool’s installation +folder. Use an empty string @code{""} for not installed tools. -FreeBSD builds +@code{config.psm1}: -@item +@example +$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" +@} +@end example -Koch, Markus +@node Additional Script Parameters,,Configuration Files,Precompile Vendor Primitives +@anchor{getting additional-script-parameters}@anchor{58} +@subsection Additional Script Parameters -@tab -vendor pre-compile script for Lattice (GNU/Linux) +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. -@item +@menu +* For Bash Scripts;: For Bash Scripts. +* For PowerShell Scripts;: For PowerShell Scripts. -Koontz, David +@end menu -@tab +@node For Bash Scripts,For PowerShell Scripts,,Additional Script Parameters +@anchor{getting for-bash-scripts}@anchor{59} +@subsubsection For Bash Scripts: -Mac OSX builds, LRM compliance work, bugfix analyses -@item -Lehmann, Patrick +@itemize * -@tab +@item +Common parameters to most scripts: -Windows compile scripts, vendor library pre-compile scripts (win+lin), building in MinGW, AppVeyor integration. +@example +--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. +@end example -@item +@item +@code{compile-altera.sh} -Martinez-Corral, Unai +Selectable libraries: -@tab +@example +--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 +@end example -Docker builds, Travis-CI & Docker, adapt/fix RTD theme +Compile options: -@item +@example +--vhdl93 Compile selected libraries with VHDL-93 (default). +--vhdl2008 Compile selected libraries with VHDL-2008. +@end example -van Rantwijk, Joris +@item +@code{compile-xilinx-ise.sh} -@tab +Selectable libraries: -Debian packaging +@example +--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 +@end example -@end multitable +Compile options: +@example +--vhdl93 Compile selected libraries with VHDL-93 (default). +--vhdl2008 Compile selected libraries with VHDL-2008. +@end example +@item +@code{compile-xilinx-vivado.sh} -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 -@image{/Users/gingold/devel/ghdl/doc/build/doctrees/images/6f8cd1a5e6840820b92af0cbdd95adc63019ebd5/ghdl,,,Contributors,svg} +Selectable libraries: +@example +--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 +@end example -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@footnote{https://sourceforge.net/p/ghdl-updates/tickets/}. +Compile options: +@example +--vhdl93 Compile selected libraries with VHDL-93 (default). +--vhdl2008 Compile selected libraries with VHDL-2008. +@end example -__________________________________________________________________ +@item +@code{compile-osvvm.sh} +Selectable libraries: -@c # preload commonly known graphical characters like (c) +@example +--all, -a Compile all. +--osvvm Compile the OSVVM library. +@end example -@c This data file has been placed in the public domain. +@item +@code{compile-uvvm.sh} -@c Derived from the Unicode character mappings available from -@c . -@c Processed by unicode2rstsubs.py, part of Docutils: -@c . +Selectable libraries: -@c # define a hard kine break for HTML +@example +--all, -a Compile all. +--uvvm Compile the UVVM libraries. +@end example +@end itemize -@node Quick Start Guide,Invoking GHDL,Copyrights | Licenses,Top -@anchor{using/QuickStartGuide doc}@anchor{26}@anchor{using/QuickStartGuide quick-start-guide}@anchor{27}@anchor{using/QuickStartGuide using-quickstart}@anchor{d} -@chapter Quick Start Guide +@node For PowerShell Scripts,,For Bash Scripts,Additional Script Parameters +@anchor{getting for-powershell-scripts}@anchor{5a} +@subsubsection For PowerShell Scripts: -In this chapter, you will learn how to use @cite{GHDL} by working on a few examples. -@menu -* The ‘Hello world’ program:: -* The heartbeat program:: -* A full adder:: -* Starting with a design:: -* Starting with your design:: +@itemize * -@end menu +@item +Common parameters to all scripts: -@node The ‘Hello world’ program,The heartbeat program,,Quick Start Guide -@anchor{using/QuickStartGuide the-hello-world-program}@anchor{28} -@section The @cite{‘Hello world’} program +@example +-Help Print the embedded help page(s). +-Clean Cleanup directory before analyzing. +-SuppressWarnings Don't show warnings. Report errors only. +@end example +@item +@code{compile-altera.ps1} -To illustrate the general purpose of @cite{VHDL}, here is a commented @cite{‘Hello world’} program which is saved in a file named @code{hello.vhdl}: +Selectable libraries: @example --- Hello world program -use std.textio.all; -- Imports the standard textio package. +-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 +@end example --- Defines a design entity, without any ports. -entity hello_world is -end hello_world; +Compile options: -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; +@example +-VHDL93 Compile selected libraries with VHDL-93 (default). +-VHDL2008 Compile selected libraries with VHDL-2008. @end example -@cartouche -@quotation Tip +@item +@code{compile-xilinx-ise.ps1} -@itemize * +Selectable libraries: -@item -Both @code{.vhdl} and @code{.vhd} extensions are used for VHDL source files, while @code{.v} is used for Verilog. +@example +-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 +@end example -@item -Unless you use especial characters, either @cite{UTF-8} or @cite{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, @ref{29,,--mb-comments} (multi byte), to allow UTF-8 or other encodings in comments. -@end itemize -@end quotation -@end cartouche +Compile options: +@example +-VHDL93 Compile selected libraries with VHDL-93 (default). +-VHDL2008 Compile selected libraries with VHDL-2008. +@end example -@itemize - +@item +@code{compile-xilinx-vivado.ps1} -@item -First, you have to compile the file; this is called @cite{analysis} of a design file in @cite{VHDL} terms. Run @code{ghdl -a hello.vhdl} in the @cite{shell}. This command creates or updates a file @code{work-obj93.cf}, which describes the library @code{work}. +Selectable libraries: -@item -Then, run @code{ghdl -e hello_world} in the @cite{shell}. Option @ref{2a,,-e} means @emph{elaborate}, which is used to build a design, with the @code{hello_world} entity at the top of the hierarchy. +@example +-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 +@end example + +Compile options: + +@example +-VHDL93 Compile selected libraries with VHDL-93 (default). +-VHDL2008 Compile selected libraries with VHDL-2008. +@end example + +@item +@code{compile-osvvm.ps1} + +Selectable libraries: + +@example +-All Compile all. +-OSVVM Compile the OSVVM library. +@end example + +@item +@code{compile-uvvm.ps1} + +Selectable libraries: + +@example +-All Compile all. +-UVVM Compile the UVVM libraries. +@end example +@end itemize + + +__________________________________________________________________ + + +@quotation +@end quotation + +@c # Load pre-defined aliases and graphical characters like © from docutils +@c # is used to denote the special path +@c # \Lib\site-packages\docutils\parsers\rst\include + +@c This data file has been placed in the public domain. + +@c Derived from the Unicode character mappings available from +@c . +@c Processed by unicode2rstsubs.py, part of Docutils: +@c . + +@c This data file has been placed in the public domain. + +@c Derived from the Unicode character mappings available from +@c . +@c Processed by unicode2rstsubs.py, part of Docutils: +@c . + +@c # define a hard line break for HTML + + +@node Contributing,Copyrights | Licenses,Getting | Installing,Top +@anchor{contribute doc}@anchor{5b}@anchor{contribute contributing}@anchor{5c}@anchor{contribute intro-contributing}@anchor{5d} +@chapter Contributing + + +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{5e,,Simulation} for an introduction. Furthermore, we encourage you to read @ref{5f,,Invoking GHDL}, +where the most commonly used options are explained. You can also check the complete @ref{60,,Additional Command Reference}. + +If you are more familiar with GHDL, you might start asking yourself how it works internally. If so, you might find +@ref{61,,Implementation of VHDL} and @ref{62,,Implementation of VITAL} interesting. + +While using GHDL, you might find flaws, such as bugs, missing features, typos in the documentation, or topics which still are +not covered. In order to improve GHDL, we welcome bug reports, suggestions, and contributions for any aspect of +GHDL. Whether it’s a bug or an enhancement, have a look at the +@image{GHDL-figures/D:/data-dev/umarcor/ghdl/ghdl/doc/_build/doctrees/images/75d23ce669cbc7993d4d057361ad0c2a3d5d5271/ghdl,,,Open issues,svg} + and +@image{GHDL-figures/D:/data-dev/umarcor/ghdl/ghdl/doc/_build/doctrees/images/e1c1423669df5839910ed47f754b67708d362d8b/ghdl,,,Closed issues,svg} + 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@footnote{https://github.com/ghdl/ghdl/wiki}. + +If you found no information on your topic, please, report so that we are aware! You can reach us through various ways: + +@image{GHDL-figures/D:/data-dev/umarcor/ghdl/ghdl/doc/_build/doctrees/images/16176de4998e1a71b2f57993443202b2d81671f4/chat-on%20gitter-4db797,,,Talk to us on Gitter,svg} + or open a +@image{GHDL-figures/D:/data-dev/umarcor/ghdl/ghdl/doc/_build/doctrees/images/dfb2204df41464917807ba7d4295bf10566f1193/new-issue-yellowgreen,,,Open new issue at GitHub,svg} +. + +@cartouche +@quotation Hint + +@itemize * + +@item +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@footnote{https://github.com/ghdl}. + +@item +How To Ask Questions The Smart Way@footnote{www.catb.org/~esr/faqs/smart-questions.html} +@end itemize +@end quotation +@end cartouche + +@menu +* Reporting bugs:: +* Requesting enhancements:: +* Improving the documentation:: +* Fork@comma{} modify and pull-request: Fork modify and pull-request. +* Related interesting projects:: + +@end menu + +@node Reporting bugs,Requesting enhancements,,Contributing +@anchor{contribute id1}@anchor{63}@anchor{contribute reporting-bugs}@anchor{64} +@section Reporting bugs + + + +@itemize * + +@item +If the compiler crashes, this is a bug. Reliable tools never crash. + +@item +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. + +@item +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. + +@item +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. + +@item +It is suggested to test synthesis features with @ref{65,,--synth}, before processing the design with @ref{66,,Yosys plugin}. +@end itemize + +Please, report issues through +@image{GHDL-figures/D:/data-dev/umarcor/ghdl/ghdl/doc/_build/doctrees/images/bac95e4b3b8c2d7bfbc31a7ce9892272a524ef30/new-bug--report-yellowgreen,,,Open new bug report at GitHub,svg} +, 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. + +@cartouche +@quotation Important +As suggested in the bug report template, please elaborate a @cite{Minimal (non) Working Example} (MWE@footnote{https://en.wikipedia.org/wiki/Minimal_Working_Example}) +prior to sending the report, so that the possible bug source is isolated. Should it fulfill the format requirements of +issue-runner@footnote{https://github.com/eine/issue-runner}, you would be able to test your bug with the latest GHDL version. +Please do so in order to ensure that the bug is not solved already. + +Also, please include enough information in the bug report, for the maintainers to reproduce the problem. The template +includes: + + +@itemize * + +@item +Operating system and version of GHDL (you can get it with @code{ghdl version} and @code{ghdl hash}). + +@item +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. + +@item +Content of the input files which comprise the MWE. + +@item +Description of the problem: + + +@itemize * + +@item +Comment explaining whether the MWE should compile or not; if yes, whether it should run until the assertion. + +@item +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. + +@item +Samples of any log. + +@item +Anything else that you think would be helpful. +@end itemize +@end itemize +@end quotation +@end cartouche + +@cartouche +@quotation 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@footnote{http://ieeexplore.ieee.org/document/4772740/}. +However, some other tools allow constructs which do not fully follow the standard revisions. Therefore, comparisons +with other VHDL variants is not a solid argument. Some of them are supported by GHDL (see @ref{67,,IEEE library pitfalls}), +but any such enhancement will have very low priority. +@end quotation +@end cartouche + +@node Requesting enhancements,Improving the documentation,Reporting bugs,Contributing +@anchor{contribute id2}@anchor{68}@anchor{contribute requesting-enhancements}@anchor{69} +@section Requesting enhancements + + + +@image{GHDL-figures/D:/data-dev/umarcor/ghdl/ghdl/doc/_build/doctrees/images/16176de4998e1a71b2f57993443202b2d81671f4/chat-on%20gitter-4db797,,,Talk to us on Gitter,svg} + + +All enhancements and feature requests are welcome. Please open a new issue@footnote{https://github.com/ghdl/ghdl/issues/new} +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@footnote{https://gitter.im/ghdl/ghdl1}, for polishing it before opening an issue. + +@node Improving the documentation,Fork modify and pull-request,Requesting enhancements,Contributing +@anchor{contribute improving-the-documentation}@anchor{6a} +@section Improving the documentation + + +If you found a mistake in the documentation, please send a comment. If you didn’t understand some parts of this manual, +please tell us. English is not our mother tongue, so this documentation may not be well-written. + +Likewise, rewriting part of the documentation or missing content (such as examples) is a good way to improve it. Since +it is built automatically from @cite{reStructuredText}, you can fork, modify and push. The documentation will be shown +in the GitHub Pages site of your fork: @code{https://USERNAME.github.io/ghdl}. When you are done, request the maintainers +to pull your copy. See @ref{6b,,Fork@comma{} modify and pull-request}. + +@node Fork modify and pull-request,Related interesting projects,Improving the documentation,Contributing +@anchor{contribute fork-modify-and-pull-request}@anchor{6c}@anchor{contribute pull-request}@anchor{6b} +@section Fork, modify and pull-request + + +@cartouche +@quotation Tip + +@itemize * + +@item +Before starting any modification, you might want to have a look at +@image{GHDL-figures/D:/data-dev/umarcor/ghdl/ghdl/doc/_build/doctrees/images/c3a4692a25333d57bb8c1ce54f97f15c6846ba63/ghdl,,,Open pull requests,svg} + and +@image{GHDL-figures/D:/data-dev/umarcor/ghdl/ghdl/doc/_build/doctrees/images/6497f995f9ef9e87d1fe97a236cebe38959dc915/ghdl,,,Closed pull requests,svg} +, +to check which other contributions are being made or have been made. If you observe that the modifications you are +about to start might conflict with any other, please +@image{GHDL-figures/D:/data-dev/umarcor/ghdl/ghdl/doc/_build/doctrees/images/16176de4998e1a71b2f57993443202b2d81671f4/chat-on%20gitter-4db797,,,Talk to us on Gitter,svg} + or open a to coordinate. + +@item +See section @ref{6d,,Directory structure} to faster find the location of the sources you need to modify, and/or to know +where to place new ones. +@end itemize +@end quotation +@end cartouche + +Contributing source code/documentation is done through git@footnote{https://git-scm.com/}. Although we don’t provide direct +write access to our repositories, the project is hosted at GitHub, which follows a fork, edit and pull-request +flow@footnote{https://help.github.com/articles/github-flow/} . That is: + + +@enumerate + +@item +Make a copy (fork@footnote{https://help.github.com/articles/fork-a-repo/}) of the project. + +@item +Do the changes you wish (edit, add, rename, move and/or delete). + +@item +When you think that the changes are ready to be merged, notify the maintainers by opening a Pull Request@footnote{https://help.github.com/articles/creating-a-pull-request/} (PR). + +@item +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. + +@item +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. +@end enumerate + +@cartouche +@quotation Tip + +@itemize * + +@item +It is recommended to read A successful Git branching model@footnote{http://nvie.com/posts/a-successful-git-branching-model/} +for a reference on how maintainers expect to handle multiple branches. However, our actual model is not as exhaustive +as explained there. + +@item +Some commit messages can automatically close@footnote{https://help.github.com/articles/closing-issues-via-commit-messages/} +issues. This is a very useful feature, which you are not required to use. However beware that using @cite{fix} anywhere +in the commit message can have side effects. If you closed any issue unexpectedly, just reply to it (even if it’s +closed) so that maintainers can check it. + +@item +It is recommended to read @ref{6e,,Coding Style} before contributing modifications to Ada sources. +@end itemize +@end quotation +@end cartouche + +@node Related interesting projects,,Fork modify and pull-request,Contributing +@anchor{contribute related-interesting-projects}@anchor{6f} +@section Related interesting projects + + +If you have an interesting project, please send us feedback or get listed on our @ref{45,,Who uses GHDL?} page. + +@c # Load pre-defined aliases and graphical characters like © from docutils +@c # is used to denote the special path +@c # \Lib\site-packages\docutils\parsers\rst\include + +@c This data file has been placed in the public domain. + +@c Derived from the Unicode character mappings available from +@c . +@c Processed by unicode2rstsubs.py, part of Docutils: +@c . + +@c This data file has been placed in the public domain. + +@c Derived from the Unicode character mappings available from +@c . +@c Processed by unicode2rstsubs.py, part of Docutils: +@c . + +@c # define a hard line break for HTML + +@node Copyrights | Licenses,Quick Start Guide,Contributing,Top +@anchor{licenses doc}@anchor{70}@anchor{licenses copyrights-licenses}@anchor{71}@anchor{licenses intro-copyrights}@anchor{72} +@chapter Copyrights | Licenses + + + +@itemize - + +@item +The GHDL front-end package @code{std.textio}, and the runtime library @code{GRT} are given under @ref{73,,GNU GPLv2}. + +@item +The documentation is given under @ref{74,,CC-BY-SA}. +@end itemize + +@cartouche +@quotation 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{69,,Requesting enhancements}) if you don’t like this policy. +@end quotation +@end cartouche + +The following packages are copyrighted by third parties (see corresponding sources for more information): + + +@itemize * + +@item +These from library @code{ieee} are copyrighted by Institute of Electrical and Electronics Engineers (IEEE)@footnote{https://www.ieee.org}: + + +@itemize * + +@item +Since December 2019, standard and IEEE libraries are distributed under Apache 2.0 and available at +opensource.ieee.org/vasg/Packages@footnote{https://opensource.ieee.org/vasg/Packages}. GHDL includes backports of those +libraries for earlier revisions of the standard. + +@item +@code{VITAL_Primitives}, @code{VITAL_Timing} and @code{VITAL_Memory} are not include in the open source distribution of IEEE (see IEEE 1076.4@footnote{http://ieeexplore.ieee.org/document/954750/}). +@end itemize + +@item +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. + + +@itemize * + +@item +@code{synopsys} directory: @code{std_logic_arith}, @code{std_logic_signed}, @code{std_logic_unsigned} and @code{std_logic_textio} are +copyrighted by Synopsys@comma{} Inc.@footnote{https://www.synopsys.com/} + +@item +@code{mentor} directory: @code{std_logic_arith} is copyrighted by Mentor Graphics@footnote{https://www.mentor.com}. +@end itemize +@end itemize + +@menu +* GNU GPLv2:: +* CC-BY-SA:: +* List of Contributors:: + +@end menu + +@node GNU GPLv2,CC-BY-SA,,Copyrights | Licenses +@anchor{licenses gnu-gplv2}@anchor{75}@anchor{licenses lic-gplv2}@anchor{73} +@section GNU GPLv2 + + +GHDL is copyright © 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 @strong{WITHOUT ANY WARRANTY}; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License@footnote{https://www.gnu.org/licenses/old-licenses/gpl-2.0.html} for more details. + +@node CC-BY-SA,List of Contributors,GNU GPLv2,Copyrights | Licenses +@anchor{licenses cc-by-sa}@anchor{76}@anchor{licenses lic-cc-by-sa}@anchor{74} +@section 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@footnote{https://creativecommons.org/licenses/by-sa/4.0/} license. You are free to @strong{share} (copy and redistribute the material in any medium or format) and/or @strong{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: + + +@itemize - + +@item +@strong{Attribution}: you must provide the name of the creator and attribution parties (more info@footnote{https://wiki.creativecommons.org/wiki/License_Versions#Detailed_attribution_comparison_chart}), a copyright notice, a license notice, a disclaimer notice, a link to the material, a link to the license and indicate if changes were made (see marking guide@footnote{https://wiki.creativecommons.org/wiki/Best_practices_for_attribution#This_is_a_good_attribution_for_material_you_modified_slightly} and more info@footnote{https://wiki.creativecommons.org/wiki/License_Versions#Modifications_and_adaptations_must_be_marked_as_such}). You may do so in any reasonable manner, but not in any way that suggests we endorse you or your use. + +@item +@strong{ShareAlike}: if you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original. + +@item +@strong{No additional restrictions}: you may not apply legal terms or technological measures that legally restrict others from doing anything the license permits. +@end itemize + +See CC-BY-SA-4.0 Legal Code@footnote{https://creativecommons.org/licenses/by-sa/4.0/legalcode.txt} for more details. + +@node List of Contributors,,CC-BY-SA,Copyrights | Licenses +@anchor{licenses lic-contributors}@anchor{77}@anchor{licenses list-of-contributors}@anchor{78} +@section List of Contributors + + + +@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} +@headitem + +Contributor @footnote{@w{(1)} +In alphabetical order +} + +@tab + +Role + +@item + +Baggett, Jonas + +@tab + +signal selection + +@item + +Bertram, Felix + +@tab + +VPI interface + +@item + +Davis, Brian + +@tab + +Windows Mcode builds + +@item + +Drummond, Brian + +@tab + +GCC 4.8.2 update, OSVVM port, some bugfixes + +@item + +Gingold, Tristan @footnote{@w{(2)} +Maintainer +} + +@tab + +@strong{Sole author of GHDL as a whole} + +@item + +Jensen, Adam + +@tab + +FreeBSD builds + +@item + +Koch, Markus + +@tab + +vendor pre-compile script for Lattice (GNU/Linux) + +@item + +Koontz, David + +@tab + +Mac OSX builds, LRM compliance work, bugfix analyses + +@item + +Lehmann, Patrick + +@tab + +Windows compile scripts, vendor library pre-compile scripts (win+lin), building in MinGW, AppVeyor integration. + +@item + +Meißner, Torsten + +@tab + +Property Specification Language (PSL): docs, tests, synthesis support + +@item + +Martinez-Corral, Unai @footnote{@w{(2)} +Maintainer +} + +@tab + +ghdl-cosim, setup-ghdl-ci, docs, docker/CI, MSYS2 packaging, building/testing on ARM, termux builds + +@item + +van Rantwijk, Joris + +@tab + +Debian packaging + +@end multitable + + + +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 +@image{GHDL-figures/D:/data-dev/umarcor/ghdl/ghdl/doc/_build/doctrees/images/6f8cd1a5e6840820b92af0cbdd95adc63019ebd5/ghdl,,,Contributors,svg} + + +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@footnote{https://sourceforge.net/p/ghdl-updates/tickets/}. + + +__________________________________________________________________ + + +@c # Load pre-defined aliases and graphical characters like © from docutils +@c # is used to denote the special path +@c # \Lib\site-packages\docutils\parsers\rst\include + +@c This data file has been placed in the public domain. + +@c Derived from the Unicode character mappings available from +@c . +@c Processed by unicode2rstsubs.py, part of Docutils: +@c . + +@c This data file has been placed in the public domain. + +@c Derived from the Unicode character mappings available from +@c . +@c Processed by unicode2rstsubs.py, part of Docutils: +@c . + +@c # define a hard line break for HTML + +@node Quick Start Guide,Invoking GHDL,Copyrights | Licenses,Top +@anchor{quick_start/index doc}@anchor{79}@anchor{quick_start/index quick-start-guide}@anchor{7a}@anchor{quick_start/index using-quickstart}@anchor{7b} +@chapter Quick Start Guide + + +Since this is the user and reference manual for @cite{GHDL}, it does not contain an introduction to @cite{VHDL}. Thus, the reader +should have at least a basic knowledge of @cite{VHDL}. A good knowledge of @cite{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 @cite{GHDL} and @cite{VHDL}. + +@c # Load pre-defined aliases and graphical characters like © from docutils +@c # is used to denote the special path +@c # \Lib\site-packages\docutils\parsers\rst\include + +@c This data file has been placed in the public domain. + +@c Derived from the Unicode character mappings available from +@c . +@c Processed by unicode2rstsubs.py, part of Docutils: +@c . + +@c This data file has been placed in the public domain. + +@c Derived from the Unicode character mappings available from +@c . +@c Processed by unicode2rstsubs.py, part of Docutils: +@c . + +@c # define a hard line break for HTML + +@menu +* Simulation:: +* Python Interfaces:: + +@end menu + +@node Simulation,Python Interfaces,,Quick Start Guide +@anchor{quick_start/simulation/index doc}@anchor{7c}@anchor{quick_start/simulation/index simulation}@anchor{7d}@anchor{quick_start/simulation/index using-quickstart-simulation}@anchor{5e} +@section Simulation + + +As explained in @ref{42,,What is GHDL?}, @cite{GHDL} is a compiler which translates @cite{VHDL} +files to machine code. Hence, the regular workflow is composed of three steps: + + +@itemize * + +@item +@ref{7e,,Analysis [-a]}: convert design units (@cite{VHDL} sources) to an internal +representation. + +@item +@ref{7f,,Elaboration [-e]}: generate executable machine code for a target module +(top-level entity). + +@item +@ref{80,,Run [-r]}: execute the design to test the behaviour, generate +output/waveforms, etc. +@end itemize + +The following tips might be useful: + + +@itemize * + +@item +Don’t forget to select the version of the VHDL standard you want to use (see +@ref{81,,VHDL standards}). The default is @ref{82,,--std=93c}. Use +@ref{82,,--std=08} for VHDL-2008 (albeit not fully implemented). + + +@itemize * + +@item +Use @ref{83,,--ieee=synopsys} if your design depends on a non-standard +implementation of the IEEE library. + +@item +Use @ref{84,,-fexplicit} and @ref{85,,-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 @code{--std=08 -frelaxed-rules}. +@end itemize + +@item +Use @ref{86,,--work=LIB_NAME} to analyze files into the @code{LIB_NAME} library. +To use files analyzed to a different directory, give the path +to the @code{LIB_NAME} library using @ref{87,,-P/path/to/name/directory/}. + +@item +Use the same options for analysis and elaboration. E.g., first analyse with +@code{ghdl -a --std=08 --work=mylib myfile.vhdl}; and then elaborate and run with +@code{ghdl --elab-run --std=08 top}. +@end itemize + +Due to the fact that @cite{VHDL} is processed as a general purpose language +(instead of an @cite{HDL}), all the language features are to be supported. I.e., @cite{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: + +@c # Load pre-defined aliases and graphical characters like © from docutils +@c # is used to denote the special path +@c # \Lib\site-packages\docutils\parsers\rst\include + +@c This data file has been placed in the public domain. + +@c Derived from the Unicode character mappings available from +@c . +@c Processed by unicode2rstsubs.py, part of Docutils: +@c . + +@c This data file has been placed in the public domain. + +@c Derived from the Unicode character mappings available from +@c . +@c Processed by unicode2rstsubs.py, part of Docutils: +@c . + +@c # define a hard line break for HTML + +@menu +* Hello world program:: +* Heartbeat module:: +* Full adder module and testbench:: +* Working with non-trivial designs:: + +@end menu + +@node Hello world program,Heartbeat module,,Simulation +@anchor{quick_start/simulation/hello/index doc}@anchor{88}@anchor{quick_start/simulation/hello/index hello-world-program}@anchor{89}@anchor{quick_start/simulation/hello/index quickstart-hello}@anchor{8a} +@subsection @cite{Hello world} program + + +To illustrate the general purpose of @cite{VHDL}, the following block is a commented @cite{Hello world} program which is saved in +a file named @code{hello.vhdl}: + +@example +-- 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; +@end example + +@cartouche +@quotation Tip + +@itemize * + +@item +Both @code{.vhdl} and @code{.vhd} extensions are used for @cite{VHDL} source files, while @code{.v} is used for Verilog. + +@quotation + + +@itemize * + +@item +Since, extension @code{.vhd} is also interpreted as a Virtual Hard Disk@footnote{https://en.wikipedia.org/wiki/VHD_(file_format)} +file format, some users prefer @code{.vhdl}, to avoid ambiguity. This is the case with @cite{GHDL}’s codebase. However, in order +to maintain backward-compatibility@footnote{https://en.wikipedia.org/wiki/8.3_filename} with legacy DOS systems, +other users prefer @code{.vhd}. +@end itemize +@end quotation + +@item +Unless you use especial characters, either @cite{UTF-8} or @cite{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, @ref{8b,,--mb-comments} (multi byte), to allow UTF-8 or other encodings in +comments. +@end itemize +@end quotation +@end cartouche + + +@itemize - + +@item +First, you have to compile the file; this is called @ref{7e,,analysis} of a design file in @cite{VHDL} +terms. Run @code{ghdl -a hello.vhdl} in the @cite{shell}. This command creates or updates a file @code{work-obj93.cf}, which +describes the library @code{work}. + +@item +Then, run @code{ghdl -e hello_world} in the @cite{shell}. Command @ref{8c,,-e} means @ref{7f,,elaborate}, +which is used to build a design, with the @code{hello_world} entity at the top of the hierarchy. + +@item +Last, you can directly launch the simulation @ref{80,,running} @code{ghdl -r hello_world} in the @cite{shell}. The +result of the simulation will be shown on screen: +@end itemize + +@example +Hello world! +@end example + +@cartouche +@quotation Hint +If a GCC/LLVM variant of @cite{GHDL} is used: + + +@itemize * + +@item +@ref{7e,,Analysis} generates a file, @code{hello.o}, which is the object file corresponding to +your @cite{VHDL} program. This is not created with @ref{4b,,mcode}. These kind of object files can be +compiled into foreign programs (see Linking GHDL object files to Ada/C@footnote{https://ghdl.github.io/ghdl-cosim/vhpidirect/linking.html#linking-with-ada}). + +@item +The @ref{7f,,elaboration} step is mandatory after running the analysis and prior to launching the +simulation. This will generate an executable binary named @code{hello_world}. + +@item +As a result, @ref{8d,,-r} is just a passthrough to the binary generated in the @cite{elaboration}. Therefore, the +executable can be run directly: @code{./hello_world}. See @ref{8d,,-r} for more informartion. +@end itemize +@end quotation +@end cartouche + +@cartouche +@quotation Hint +@ref{8c,,-e} can be bypassed with @ref{4b,,mcode}, since @ref{8d,,-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. +@end quotation +@end cartouche + +@c # Load pre-defined aliases and graphical characters like © from docutils +@c # is used to denote the special path +@c # \Lib\site-packages\docutils\parsers\rst\include + +@c This data file has been placed in the public domain. + +@c Derived from the Unicode character mappings available from +@c . +@c Processed by unicode2rstsubs.py, part of Docutils: +@c . + +@c This data file has been placed in the public domain. + +@c Derived from the Unicode character mappings available from +@c . +@c Processed by unicode2rstsubs.py, part of Docutils: +@c . + +@c # define a hard line break for HTML + +@node Heartbeat module,Full adder module and testbench,Hello world program,Simulation +@anchor{quick_start/simulation/heartbeat/index doc}@anchor{8e}@anchor{quick_start/simulation/heartbeat/index heartbeat-module}@anchor{8f}@anchor{quick_start/simulation/heartbeat/index quickstart-heartbeat}@anchor{90} +@subsection @cite{Heartbeat} module + + +Although @ref{8a,,Hello world} illustrates that @cite{VHDL} is supported as a general purpose language, the main use case +of @cite{GHDL} is to simulate hardware descriptions. The following block, which is saved in a file named +@code{heartbeat.vhdl}, is an example of how to generate a 100 MHz clock signal with non-synthesisable VHDL: + +@example +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; +@end example + +It can be @ref{7e,,analysed}, @ref{7f,,elaborated} and @ref{80,,run}, as you already know: + +@example +ghdl -a heartbeat.vhdl +ghdl -e heartbeat +ghdl -r heartbeat +@end example + +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@footnote{https://en.wikipedia.org/wiki/Waveform_viewer}, +which is supported by @cite{GHDL} (see @ref{91,,Export waveforms}). You can use either @ref{92,,--wave}, @ref{93,,--vcd}, +@ref{94,,--vcdgz} or @ref{95,,--fst} to save the signals of the simulation to a file. Then, terminate the execution +(@code{C-c}) and you can inspect the wave with a viewer, such as GtkWave@footnote{http://gtkwave.sourceforge.net/}. As +explained in the manual@footnote{http://gtkwave.sourceforge.net/gtkwave.pdf}, GtkWave @emph{‘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: + +@example +ghdl -r heartbeat --wave=wave.ghw +@end example + +Then, you can view the dump: + +@example +gtkwave wave.ghw +@end example + +Of course, manually terminating the simulation is for illustration purposes only. In @ref{96,,Full adder} and +@ref{97,,Working with non-trivial designs}, you will see how to write a testbench to terminate the simulation programmatically. + +@c # Load pre-defined aliases and graphical characters like © from docutils +@c # is used to denote the special path +@c # \Lib\site-packages\docutils\parsers\rst\include + +@c This data file has been placed in the public domain. + +@c Derived from the Unicode character mappings available from +@c . +@c Processed by unicode2rstsubs.py, part of Docutils: +@c . + +@c This data file has been placed in the public domain. + +@c Derived from the Unicode character mappings available from +@c . +@c Processed by unicode2rstsubs.py, part of Docutils: +@c . + +@c # define a hard line break for HTML + +@node Full adder module and testbench,Working with non-trivial designs,Heartbeat module,Simulation +@anchor{quick_start/simulation/adder/index doc}@anchor{98}@anchor{quick_start/simulation/adder/index full-adder-module-and-testbench}@anchor{99}@anchor{quick_start/simulation/adder/index quickstart-adder}@anchor{96} +@subsection @cite{Full adder} module and testbench + + +Unlike @ref{90,,Heartbeat}, the target hardware design in this example is written using the +synthesisable subset of @cite{VHDL}. It is a full adder@footnote{https://en.wikipedia.org/wiki/Adder_(electronics)#Full_adder} +described in a file named @code{adder.vhdl}: + +@example +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; +@end example + +You can @ref{7e,,analyse} this design file, @code{ghdl -a adder.vhdl}, and try to execute the @cite{adder} +design. But this is useless, since nothing externally visible will happen. In order to check this full adder, a +@emph{testbench} has to be run. The @emph{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 +@code{adder_tb.vhdl} contains the testbench for the adder: + +@example +-- 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; +@end example + +As usual, you should analyze the file, @code{ghdl -a adder_tb.vhdl}. + +@cartouche +@quotation Hint +Then, if required, @ref{7f,,elaborate} the testbench: @code{ghdl -e adder_tb}. You do not need to +specify which object files are required, since @cite{GHDL} knows them and automatically adds them. +@end quotation +@end cartouche + +Now, it is time to @ref{80,,run} the testbench, @code{ghdl -r adder_tb}, and check the result on screen: + +@example +adder_tb.vhdl:52:7:(assertion note): end of test +@end example + +If your design is rather complex, you’d like to inspect signals as explained in @ref{90,,Heartbeat}. + +See section @ref{9a,,Simulation options}, for more details on other runtime options. + +@c # Load pre-defined aliases and graphical characters like © from docutils +@c # is used to denote the special path +@c # \Lib\site-packages\docutils\parsers\rst\include + +@c This data file has been placed in the public domain. + +@c Derived from the Unicode character mappings available from +@c . +@c Processed by unicode2rstsubs.py, part of Docutils: +@c . + +@c This data file has been placed in the public domain. + +@c Derived from the Unicode character mappings available from +@c . +@c Processed by unicode2rstsubs.py, part of Docutils: +@c . + +@c # define a hard line break for HTML + +@node Working with non-trivial designs,,Full adder module and testbench,Simulation +@anchor{quick_start/simulation/DLXModelSuite doc}@anchor{9b}@anchor{quick_start/simulation/DLXModelSuite quickstart-dlx}@anchor{97}@anchor{quick_start/simulation/DLXModelSuite working-with-non-trivial-designs}@anchor{9c} +@subsection 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@footnote{http://ghdl.free.fr/dlx.tar.gz} . + + +@itemize - + +@item +First, untar the sources: @code{tar zxvf dlx.tar.gz}. +@end itemize + +@cartouche +@quotation Hint +@quotation + +In order not to pollute the sources with the artifacts (@cite{WORK} library), it is a good idea to create a +@code{work/} subdirectory. To any GHDL commands, we will add the @ref{9d,,--workdir=work} option, so +that all files generated by the compiler (except the executable) will be placed in this directory. +@end quotation + +@example +$ cd dlx +$ mkdir work +@end example +@end quotation +@end cartouche + + +@itemize * + +@item +Then, we will run the @code{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{9e,,importing} the +sources: @code{ghdl -i --workdir=work *.vhdl}. + +@item +GHDL knows all the design units of the DLX, but none of them has been analysed. Run the @ref{9f,,make} +command, @code{ghdl -m --workdir=work dlx_test_behaviour}, which analyses and elaborates a design. This creates many +files in the @code{work/} directory, and (GCC/LLVM only) the @code{dlx_test_behaviour} executable in the current +directory. +@end itemize + +@cartouche +@quotation Hint +The simulation needs to have a DLX program contained in the file @code{dlx.out}. This memory image will be loaded +in the DLX memory. Just take one sample: @code{cp test_loop.out dlx.out}. +@end quotation +@end cartouche + + +@itemize * + +@item +Now, you can @ref{80,,run} the test suite: @code{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: + +@example +dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction + encountered, execution halted +@end example + +@item +Last, since the clock is still running, you have to manually stop the program with the @code{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: +@code{ghdl -r --workdir=work dlx_test_behaviour --assert-level=note`}. With @ref{a0,,--assert-level}, the program stops +just after the previous message: + +@example +dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction + encountered, execution halted +error: assertion failed +@end example +@end itemize + +@cartouche +@quotation Tip +If you want to make room on your hard drive, you can either: + + +@itemize * + +@item +@ref{a1,,Clean} the design library with @code{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. + +@item +@ref{a2,,Remove} the design library with @code{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. + +@item +Remove the @code{work/} directory: @code{rm -rf work}. Only the executable is kept. If you want to rebuild the design, create the @code{work/} directory, import the sources, and make the design. +@end itemize +@end quotation +@end cartouche + +@cartouche +@quotation Warning +Sometimes, a design does not fully follow the VHDL standards. For example it might use the badly engineered @code{std_logic_unsigned} package. GHDL supports this VHDL dialect through some options: @ref{83,,--ieee=synopsys}, @ref{84,,-fexplicit}, etc. See section @ref{67,,IEEE library pitfalls}, for more details. +@end quotation +@end cartouche + +@cartouche +@quotation Tip +See Learning VHDL with GHDL@footnote{https://github.com/ghdl/ghdl/issues/1291}. +@end quotation +@end cartouche + +@c # Load pre-defined aliases and graphical characters like © from docutils +@c # is used to denote the special path +@c # \Lib\site-packages\docutils\parsers\rst\include + +@c This data file has been placed in the public domain. + +@c Derived from the Unicode character mappings available from +@c . +@c Processed by unicode2rstsubs.py, part of Docutils: +@c . + +@c This data file has been placed in the public domain. + +@c Derived from the Unicode character mappings available from +@c . +@c Processed by unicode2rstsubs.py, part of Docutils: +@c . + +@c # define a hard line break for HTML + +@node Python Interfaces,,Simulation,Quick Start Guide +@anchor{quick_start/python/index doc}@anchor{a3}@anchor{quick_start/python/index python-interfaces}@anchor{a4}@anchor{quick_start/python/index using-quickstart-python}@anchor{a5} +@section 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 @code{libghdl}). +Installing from @code{master} is discouraged, because it might contain changes to the internal AST. Instead, @code{ghdl version hash} +allows getting the commit hash of the version the installed binary was built from. Since @code{pip} allows installing packages +by providing the URL to the git repo, this is the recommended installation procedure: + +@example +pip install git+https://github.com/ghdl/ghdl.git@@$(ghdl version hash) +@end example + +@menu +* Language Server:: + +@end menu + +@node Language Server,,,Python Interfaces +@anchor{quick_start/python/index cmdref}@anchor{a6}@anchor{quick_start/python/index language-server}@anchor{a7} +@subsection Language Server + + +When installed through @code{pip}, pyGHDL provides executable entrypoints registered in the search PATH, such as @code{ghdl-ls}. + +@c # +@c This files requires a Python module called 'AutoProgram' to be located in the +@c 'doc' root folder. It expects a variable 'parser' of type ArgumentParser. + +@menu +* ghdl-ls:: + +@end menu + +@node ghdl-ls,,,Language Server +@anchor{quick_start/python/index cmdref-ghdlls}@anchor{a8}@anchor{quick_start/python/index ghdl-ls}@anchor{a9} +@subsubsection ghdl-ls + + +VHDL Language Protocol Server. Find info about clients in ghdl/ghdl-language-server@footnote{https://github.com/ghdl/ghdl-language-server}. + +@example +usage: ghdl-ls [-h] [--version] [--verbose] [--log-file LOG_FILE] + [--trace-file TRACE_FILE] [--input INPUT] [--disp-config] +@end example + +@menu +* optional arguments:: + +@end menu + +@node optional arguments,,,ghdl-ls +@anchor{quick_start/python/index optional-arguments}@anchor{aa} +@subsubsection optional arguments + + +@geindex ghdl-ls command line option; -h +@geindex ghdl-ls command line option; --help +@anchor{quick_start/python/index cmdoption-ghdl-ls-h}@anchor{ab}@anchor{quick_start/python/index cmdoption-ghdl-ls-help}@anchor{ac} +@deffn {Option} @w{-}h, @w{-}@w{-}help + +show this help message and exit +@end deffn + +@geindex ghdl-ls command line option; --version +@geindex ghdl-ls command line option; -V +@anchor{quick_start/python/index cmdoption-ghdl-ls-version}@anchor{ad}@anchor{quick_start/python/index cmdoption-ghdl-ls-V}@anchor{ae}@anchor{quick_start/python/index cmdoption-ghdl-ls-v}@anchor{af} +@deffn {Option} @w{-}@w{-}version, @w{-}V + +show program’s version number and exit +@end deffn + +@geindex ghdl-ls command line option; --verbose +@geindex ghdl-ls command line option; -v +@anchor{quick_start/python/index cmdoption-ghdl-ls-verbose}@anchor{b0}@anchor{quick_start/python/index cmdoption-ghdl-ls-0}@anchor{b1} +@deffn {Option} @w{-}@w{-}verbose, @w{-}v + +Show debug output +@end deffn + +@geindex ghdl-ls command line option; --log-file +@anchor{quick_start/python/index cmdoption-ghdl-ls-log-file}@anchor{b2} +@deffn {Option} @w{-}@w{-}log@w{-}file + +Redirect logs to the given file instead of stderr +@end deffn + +@geindex ghdl-ls command line option; --trace-file +@anchor{quick_start/python/index cmdoption-ghdl-ls-trace-file}@anchor{b3} +@deffn {Option} @w{-}@w{-}trace@w{-}file + +Save RPC data to FILE.in and FILE.out (overrides +@geindex GHDL_LS_TRACE +@geindex environment variable; GHDL_LS_TRACE +@code{GHDL_LS_TRACE}) +@end deffn + +@geindex ghdl-ls command line option; --input +@geindex ghdl-ls command line option; -i +@anchor{quick_start/python/index cmdoption-ghdl-ls-input}@anchor{b4}@anchor{quick_start/python/index cmdoption-ghdl-ls-i}@anchor{b5} +@deffn {Option} @w{-}@w{-}input , @w{-}i + +Read request from file +@end deffn + +@geindex ghdl-ls command line option; --disp-config +@anchor{quick_start/python/index cmdoption-ghdl-ls-disp-config}@anchor{b6} +@deffn {Option} @w{-}@w{-}disp@w{-}config + +Display installation configuration and exit +@end deffn + +@c # Load pre-defined aliases and graphical characters like © from docutils +@c # is used to denote the special path +@c # \Lib\site-packages\docutils\parsers\rst\include + +@c This data file has been placed in the public domain. + +@c Derived from the Unicode character mappings available from +@c . +@c Processed by unicode2rstsubs.py, part of Docutils: +@c . + +@c This data file has been placed in the public domain. + +@c Derived from the Unicode character mappings available from +@c . +@c Processed by unicode2rstsubs.py, part of Docutils: +@c . + +@c # define a hard line break for HTML + +@node Invoking GHDL,Simulation runtime,Quick Start Guide,Top +@anchor{using/InvokingGHDL doc}@anchor{b7}@anchor{using/InvokingGHDL invoking-ghdl}@anchor{b8}@anchor{using/InvokingGHDL using-invoking}@anchor{5f} +@chapter Invoking GHDL + + +The form of the @code{ghdl} command is @code{ghdl command [options...]}. +There are multiple available commands, but these general rules apply: + + +@itemize * + +@item +The first argument selects the command. +The options are used to slightly modify the action. + +@item +No option is allowed before the command. +Except for the run command, no option is allowed after a filename or a unit name. +@end itemize + +@cartouche +@quotation Hint +If the number of options is large and the command line length is beyond the system limit, you can use a response file. +An argument that starts with a @code{@@} is considered as a response file; it is replaced by arguments read from the file +(separated by blanks and end of line). +@end quotation +@end cartouche + +@cartouche +@quotation Hint +Only the most common commands and options are shown here. For the most advanced and experimental features see section +@ref{60,,Additional Command Reference}. +@end quotation +@end cartouche + +@cartouche +@quotation Warning +During analysis and elaboration GHDL may read the @code{std} and @code{ieee} files. +The location of these files is based on the prefix, which is (in order of priority): + + +@itemize * + +@item +the @ref{b9,,--PREFIX} command line option + +@item +the +@geindex GHDL_PREFIX +@geindex environment variable; GHDL_PREFIX +@ref{ba,,GHDL_PREFIX} environment variable + +@item +a built-in default path. It is a hard-coded path on GNU/Linux, and it corresponds to the value of the +@code{HKLM\Software\Ghdl\Install_Dir} registry entry on Windows. +@end itemize + +You should use the @ref{bb,,--disp-config} command to display and debug installation problems. +@end quotation +@end cartouche + +@menu +* Design building commands:: +* Design rebuilding commands:: +* Options:: +* Warnings:: +* Diagnostics Control:: +* Library commands:: +* VPI/VHPI build commands:: +* IEEE library pitfalls:: + +@end menu + +@node Design building commands,Design rebuilding commands,,Invoking GHDL +@anchor{using/InvokingGHDL design-building-commands}@anchor{bc} +@section Design building commands + + +The most commonly used commands of GHDL are those to analyze and elaborate a design. + +@geindex cmd analysis + +@menu +* Analysis [-a]:: +* Elaboration [-e]:: +* Run [-r]:: +* Elaborate and run [--elab-run]:: +* Check syntax [-s]:: +* Analyze and elaborate [-c]:: + +@end menu + +@node Analysis [-a],Elaboration [-e],,Design building commands +@anchor{using/InvokingGHDL analysis-a}@anchor{bd}@anchor{using/InvokingGHDL analysis-command}@anchor{7e} +@subsection Analysis [@code{-a}] + + +@geindex ghdl command line option; -a <[options...] file...> +@anchor{using/InvokingGHDL cmdoption-ghdl-a}@anchor{be} +@deffn {Option} @w{-}a <[options...] file...> +@end deffn + +Analyzes/compiles one or more files, and creates an object file for each source file. +Any argument starting with a dash is an option, the others are filenames. +No options are allowed after a filename argument. +GHDL analyzes each filename in the given order, and stops the analysis in case of error (remaining files are not +analyzed). + +See @ref{bf,,Options}, for details on the GHDL options. +For example, to produce debugging information such as line numbers, use: @code{ghdl -a -g my_design.vhdl}. + +@geindex cmd elaboration + +@node Elaboration [-e],Run [-r],Analysis [-a],Design building commands +@anchor{using/InvokingGHDL elaboration-command}@anchor{7f}@anchor{using/InvokingGHDL elaboration-e}@anchor{c0} +@subsection Elaboration [@code{-e}] + + +@geindex ghdl command line option; -e <[options...] [library.]top_unit [arch]> +@anchor{using/InvokingGHDL cmdoption-ghdl-e}@anchor{8c} +@deffn {Option} @w{-}e <[options...] [library.]top_unit [arch]> +@end deffn + +Re-analyzes all the configurations, entities, architectures and package declarations, and creates the default +configurations and the default binding indications according to the LRM rules. +It also generates the list of object files required for the executable. +Then, it links all these files with the runtime library (GRT). + +The elaboration command, @ref{8c,,-e}, must be followed by a @code{top_unit} name denoting either of: + +@quotation + + +@itemize * + +@item +a configuration unit + +@item +an entity unit + +@item +an entity unit followed by a secondary unit (the name of an architecture unit) +@end itemize +@end quotation + + +@itemize * + +@item +Name of the top units can be either a simple name (without dots), or the name of a logical library followed by a dot +and a simple name. +The latter is equivalent to using @ref{86,,--work=NAME} described in @ref{bf,,Options}: +@code{-e <[options...] --work=library top_unit [arch]>}. +It selects the name of the library to be used as @code{WORK}. +See section @ref{c1,,Top entity}, for the restrictions on the root/top unit of a hierarchy. + +@item +Name of the secondary units must be a simple name; they cannot contain any dot. +@end itemize + +With regard to the artifacts: + + +@itemize * + +@item +If the GCC/LLVM backend was enabled during the compilation of GHDL, the elaboration command creates an executable +containing the code of the VHDL sources, the elaboration code and simulation code for executing a design hierarchy. +The executable is created in the current directory and the the filename is the name of the primary unit, or for the +latter case, the concatenation of the name of the primary unit, a dash, and the name of the secondary unit. +Option @code{-o} followed by a filename can override the default executable filename. + +@item +If mcode is used, this command elaborates the design but does not generate anything. +Since the run command also elaborates the design, this can be skipped. +@end itemize + +@cartouche +@quotation Warning +This elaboration command is not a complete elaboration in terms of the VHDL standard. +The actual elaboration is performed at runtime. +Therefore, in order to get a complete VHDL elaboration without running the simulation, @code{ghdl --elab-run --no-run} +is required. +See @ref{c2,,--no-run}. +@end quotation +@end cartouche + +@geindex cmd run + +@node Run [-r],Elaborate and run [--elab-run],Elaboration [-e],Design building commands +@anchor{using/InvokingGHDL run-command}@anchor{80}@anchor{using/InvokingGHDL run-r}@anchor{c3} +@subsection Run [@code{-r}] + + +@geindex ghdl command line option; -r <[options...] [library.]top_unit [arch] [simulation_options...]> +@anchor{using/InvokingGHDL cmdoption-ghdl-r}@anchor{8d} +@deffn {Option} @w{-}r <[options...] [library.]top_unit [arch] [simulation_options...]> +@end deffn + +Runs/simulates a design. +Two sets of options are accepted, both of them being separated by @code{[library.]top_unit [arch]}. +For the first set, @code{options...}, arguments are the same as for the @ref{7f,,elaboration command}. +For the second set, @code{simulation_options...}, arguments are defined in @ref{c4,,Simulation (runtime)}. + + +@itemize * + +@item +GGC/LLVM: the filename of the executable is determined and it is executed. +Elaboration options are ignored. +You may also directly execute the program. +The executable must be in the current directory. + +@item +mcode: the design is elaborated and the simulation is launched. +As a consequence, you must use the same options used during analysis. +@end itemize + +This command exists for three reasons: + + +@itemize * + +@item +It works with mcode implementation, where the executable code is generated in memory. + +@item +You are using GCC/LLVM, but you don’t need to create the executable program name. + +@item +It is coherent with the @ref{be,,-a} and @ref{8c,,-e} commands. +@end itemize + +@geindex cmd elaborate and run + +@node Elaborate and run [--elab-run],Check syntax [-s],Run [-r],Design building commands +@anchor{using/InvokingGHDL elab-and-run-command}@anchor{c5}@anchor{using/InvokingGHDL elaborate-and-run-elab-run}@anchor{c6} +@subsection Elaborate and run [@code{--elab-run}] + + +@geindex ghdl command line option; --elab-run <[options...] [library.]top_unit [arch] [simulation_options...]> +@anchor{using/InvokingGHDL cmdoption-ghdl-elab-run}@anchor{c7} +@deffn {Option} @w{-}@w{-}elab@w{-}run <[options...] [library.]top_unit [arch] [simulation_options...]> +@end deffn + +Acts like the elaboration command followed by the run command. +Note that this command accepts two sets of options. +See @ref{8c,,-e}, @ref{8d,,-r} and @ref{c4,,Simulation (runtime)}. + +@geindex cmd checking syntax + +@node Check syntax [-s],Analyze and elaborate [-c],Elaborate and run [--elab-run],Design building commands +@anchor{using/InvokingGHDL check-syntax-s}@anchor{c8} +@subsection Check syntax [@code{-s}] + + +@geindex ghdl command line option; -s <[options...] file...> +@anchor{using/InvokingGHDL cmdoption-ghdl-s}@anchor{c9} +@deffn {Option} @w{-}s <[options...] file...> +@end deffn + +Analyze files but do not generate code. +This command may be used to check the syntax of files. +It does not update the library. + +@geindex cmd analyze and elaborate + +@node Analyze and elaborate [-c],,Check syntax [-s],Design building commands +@anchor{using/InvokingGHDL analyze-and-elaborate-c}@anchor{ca} +@subsection Analyze and elaborate [@code{-c}] + + +@geindex ghdl command line option; -c <[options...] file... - top_unit [arch]> +@anchor{using/InvokingGHDL cmdoption-ghdl-c}@anchor{cb} +@deffn {Option} @w{-}c <[options...] file... @w{-} top_unit [arch]> +@end deffn + +@cartouche +@quotation Hint +With GCC/LLVM, @ref{8c,,-e} should be used, and @ref{8d,,-r} with mcode. +@end quotation +@end cartouche + +The files are first parsed, and then a elaboration is performed, which drives an analysis. +Effectively, analysis and elaboration are combined, but there is no explicit call to @ref{be,,-a}. +With GCC/LLVM, code is generated during the elaboration. +With mcode, the simulation is launched after the elaboration. + +All the units of the files are put into the @cite{work} library. +But, the work library is neither read from disk nor saved. +Therefore, you must give all the files of the @cite{work} library your design needs. + +The advantages over the traditional approach (analyze and then elaborate) are: + + +@itemize * + +@item +The compilation cycle is achieved in one command. + +@item +Since the files are only parsed once, the compilation cycle may be faster. + +@item +You don’t need to know an analysis order. + +@item +This command produces a smaller executable, since unused units and subprograms do not generate code. +@end itemize + +@cartouche +@quotation Hint +However, you should know that most of the time is spent in code generation and the analyze and elaborate command +generates code for all units needed, even units of @code{std} and @code{ieee} libraries. +Therefore, according to the design, the time for this command may be higher than the time for the analyze command +followed by the elaborate command. +@end quotation +@end cartouche + +@cartouche +@quotation Warning +This command is still under development. In case of problems, you should go back to the traditional way. +@end quotation +@end cartouche + +@node Design rebuilding commands,Options,Design building commands,Invoking GHDL +@anchor{using/InvokingGHDL design-rebuilding-commands}@anchor{cc} +@section Design rebuilding commands + + +Analyzing and elaborating a design consisting of several files can be tricky, due to dependencies. +GHDL has a few commands for rebuilding a design. + +@geindex cmd importing files + +@menu +* Import [-i]:: +* Elab-order [--elab-order]:: +* Make [-m]:: +* Generate Makefile [--gen-makefile]:: +* Generate dependency file command [--gen-depends]:: + +@end menu + +@node Import [-i],Elab-order [--elab-order],,Design rebuilding commands +@anchor{using/InvokingGHDL import-command}@anchor{9e}@anchor{using/InvokingGHDL import-i}@anchor{cd} +@subsection Import [@code{-i}] + + +@geindex ghdl command line option; -i <[options...] file...> +@anchor{using/InvokingGHDL cmdoption-ghdl-i}@anchor{ce} +@deffn {Option} @w{-}i <[options...] file...> +@end deffn + +All the files specified in the command line are scanned, parsed and added into the libraries but as not yet analyzed. +No object files are created. +Its purpose is to localize design units in the design files. +The make command will then be able to recursively build a hierarchy from an entity name or a configuration name. + +@cartouche +@quotation Hint + +@itemize * + +@item +Note that all the files are added to the work library. +If you have many libraries, you must use the command for each library. + +@item +Since the files are parsed, there must be correct files. +However, since they are not analyzed, many errors are tolerated by this command. +@end itemize +@end quotation +@end cartouche + +See @ref{cf,,-m}, to actually build the design. +See also @ref{d0,,--elab-order}, for retrieving the compilation order guessed recursively. + +@geindex cmd elaboration order + +@node Elab-order [--elab-order],Make [-m],Import [-i],Design rebuilding commands +@anchor{using/InvokingGHDL elab-order-elab-order}@anchor{d1} +@subsection Elab-order [@code{--elab-order}] + + +@geindex ghdl command line option; --elab-order <[options...] [libray.]top_unit [arch]> +@anchor{using/InvokingGHDL cmdoption-ghdl-elab-order}@anchor{d0} +@deffn {Option} @w{-}@w{-}elab@w{-}order <[options...] [libray.]top_unit [arch]> +@end deffn + +Print the list of sources required for elaborating a unit, in order for them to be analyzed without dependency issues. +This is expected to be used after @ref{ce,,-i}, or for retrieving the order for some unit analyzed through third-party +scripts. + +@cartouche +@quotation Attention +Currently, the list does not include information about the logical library names where each source needs to be +analyzed. +Hence, it is mostly useful when all sources belong to the same @code{WORK} library. +@end quotation +@end cartouche + +@geindex cmd make + +@node Make [-m],Generate Makefile [--gen-makefile],Elab-order [--elab-order],Design rebuilding commands +@anchor{using/InvokingGHDL make-command}@anchor{9f}@anchor{using/InvokingGHDL make-m}@anchor{d2} +@subsection Make [@code{-m}] + + +@geindex ghdl command line option; -m <[options...] [library.]top_unit [arch]> +@anchor{using/InvokingGHDL cmdoption-ghdl-m}@anchor{cf} +@deffn {Option} @w{-}m <[options...] [library.]top_unit [arch]> +@end deffn + +Analyze automatically outdated files and elaborate a design. +The primary unit denoted by the @code{[library.]top_unit} argument must already be known by the system, either because you +have already analyzed it (even if you have modified it) or because you have imported it. +A file may be outdated because it has been modified (e.g. you have just edited it), or because a design unit contained +in the file depends on a unit which is outdated. +This rule is recursive. + + +@itemize * + +@item +With option @code{--bind}, GHDL will stop before the final linking step. +This is useful when the main entry point is not GHDL and you’re linking GHDL object files into a foreign program. + +@item +With option @code{-f} (force), GHDL analyzes all the units of the work library needed to create the design hierarchy. +Outdated units are recompiled. +This is useful if you want to compile a design hierarchy with new compilation flags (for example, to add the @code{-g} +debugging option). +@end itemize + +@cartouche +@quotation Important +The make command will only re-analyze design units in the work library. +GHDL fails if it has to analyze an outdated unit from another library. +@end quotation +@end cartouche + +The purpose of this command is to be able to compile a design without prior knowledge of file order. +In the VHDL model, some units must be analyzed before others (e.g. an entity before its architecture). +It might be a nightmare to analyze a full design of several files if you don’t have the ordered list of files. +This command computes an analysis order. + +The make command fails when a unit was not previously parsed. +For example, if you split a file containing several design units into several files, you must either import these new +files or analyze them so that GHDL knows in which file these units are. + +The make command imports files which have been modified. +Then, a design hierarchy is internally built as if no units are outdated. +Then, all outdated design units, using the dependencies of the design hierarchy, are analyzed. +If necessary, the design hierarchy is elaborated. + +@cartouche +@quotation Hint +This is not perfect, since the default architecture (the most recently analyzed one) may change while outdated design +files are analyzed. +In such a case, re-run the make command of GHDL. +@end quotation +@end cartouche + +@geindex cmd generate makefile + +@node Generate Makefile [--gen-makefile],Generate dependency file command [--gen-depends],Make [-m],Design rebuilding commands +@anchor{using/InvokingGHDL generate-makefile-gen-makefile}@anchor{d3} +@subsection Generate Makefile [@code{--gen-makefile}] + + +@geindex ghdl command line option; --gen-makefile <[options...] [library.]top_unit [arch]> +@anchor{using/InvokingGHDL cmdoption-ghdl-gen-makefile}@anchor{d4} +@deffn {Option} @w{-}@w{-}gen@w{-}makefile <[options...] [library.]top_unit [arch]> +@end deffn + +This command works like the make command (see @ref{cf,,-m}), but only a makefile is generated on the standard output. + +@geindex --gen-depends command + +@node Generate dependency file command [--gen-depends],,Generate Makefile [--gen-makefile],Design rebuilding commands +@anchor{using/InvokingGHDL generate-dependency-file-command-gen-depends}@anchor{d5} +@subsection Generate dependency file command [@code{--gen-depends}] + + +@geindex ghdl command line option; --gen-depends <[options...] [library.]top_unit [arch]> +@anchor{using/InvokingGHDL cmdoption-ghdl-gen-depends}@anchor{d6} +@deffn {Option} @w{-}@w{-}gen@w{-}depends <[options...] [library.]top_unit [arch]> +@end deffn + +Generate a Makefile containing only dependencies to build a design unit. + +This command works like the make and gen-makefile commands (see @ref{cf,,-m}), but instead of a full makefile only +dependencies without rules are generated on the standard output. +Theses rules can then be integrated in another Makefile. + +@node Options,Warnings,Design rebuilding commands,Invoking GHDL +@anchor{using/InvokingGHDL ghdl-options}@anchor{bf}@anchor{using/InvokingGHDL options}@anchor{d7} +@section Options + + +@geindex IEEE 1164 + +@geindex 1164 + +@geindex IEEE 1076.3 + +@geindex 1076.3 + +@geindex WORK library + +@geindex ghdl command line option; --work= +@anchor{using/InvokingGHDL cmdoption-ghdl-work}@anchor{86} +@deffn {Option} @w{-}@w{-}work= + +Specify the name of the @code{WORK} library. Analyzed units are always placed in the library logically named @code{WORK}. +With this option, you can set its name. +By default, the name is @code{work}. + +@cite{GHDL} checks whether @code{WORK} is a valid identifier. +Although being more or less supported, the @code{WORK} identifier should not be an extended identifier, since the +filesystem may prevent it from working correctly (due to case sensitivity or forbidden characters in filenames). + +@cartouche +@quotation Attention +@cite{VHDL} rules forbid you from adding units to the @code{std} library. +Furthermore, you should not put units in the @code{ieee} library. +@end quotation +@end cartouche + +@cartouche +@quotation Hint +Since 849a25e0@footnote{https://github.com/ghdl/ghdl/commit/849a25e02cfb359e3d9313060156b0643495548b}, this option can +be alternatively provided to several commands by prepending the library name to the top unit name. +See, for instance, @ref{8c,,-e}. +@end quotation +@end cartouche +@end deffn + +@geindex ghdl command line option; --workdir= +@anchor{using/InvokingGHDL cmdoption-ghdl-workdir}@anchor{9d} +@deffn {Option} @w{-}@w{-}workdir= + +Specify the directory where the @code{WORK} library is located. +When this option is not present, the @code{WORK} library is in the current directory. +The object files created by the compiler are always placed in the same directory as the @code{WORK} library. + +Use option @ref{87,,-P} to specify where libraries other than @code{WORK} are placed. +@end deffn + +@geindex ghdl command line option; --std= +@anchor{using/InvokingGHDL cmdoption-ghdl-std}@anchor{82} +@deffn {Option} @w{-}@w{-}std= + +Specify the standard to use. By default, the standard is @code{93c}, which means VHDL-93 with relaxed rules. +For details on @code{STANDARD} values see section @ref{81,,VHDL standards}. + +@cartouche +@quotation Important +This option resets the effect of @ref{d8,,-frelaxed}, so it should be the first option. +@end quotation +@end cartouche +@end deffn + +@geindex ghdl command line option; -fsynopsys +@anchor{using/InvokingGHDL cmdoption-ghdl-fsynopsys}@anchor{d9} +@deffn {Option} @w{-}fsynopsys + +Allow the use of synopsys non-standard packages (@code{std_logic_arith}, @code{std_logic_signed}, @code{std_logic_unsigned}, +@code{std_logic_textio}). +These packages are present in the ieee library but without this option it’s an error to use them. + +The synopsys packages were created by some companies, and are popular. +However they are not standard packages, and have been placed in the @cite{IEEE} library without the permission from the +@code{ieee}. +@end deffn + +@geindex ghdl command line option; --ieee= +@anchor{using/InvokingGHDL cmdoption-ghdl-ieee}@anchor{83} +@deffn {Option} @w{-}@w{-}ieee= + +@geindex ieee library + +@geindex synopsys library + +Select the @code{IEEE} library to use. @code{IEEE_VAR} must be one of: + + +@table @asis + +@item none + +Do not supply an @cite{IEEE} library. Any library clause with the @code{IEEE} identifier will fail, unless you have created +your own library with the @cite{IEEE} name. + +@item standard + +Supply an @cite{IEEE} library containing only packages defined by @code{ieee} standards. +Currently, there are the multivalue logic system package @code{std_logic_1164} defined by IEEE 1164, the synthesis +packages @code{numeric_bit} and @code{numeric_std} defined by IEEE 1076.3, and the @code{vital} packages @code{vital_timing} and +@code{vital_primitives}, defined by IEEE 1076.4. +The version of these packages is defined by the VHDL standard used. +See section @ref{da,,VITAL packages}, for more details. + +@item synopsys + +This option is now deprecated. +It is equivalent to @code{--ieee=standard} and @code{-fsynopsys}. +@end table + +To avoid errors, you must use the same @cite{IEEE} library for all units of your design, and during elaboration. +@end deffn + +@geindex ghdl command line option; -P +@anchor{using/InvokingGHDL cmdoption-ghdl-P}@anchor{87}@anchor{using/InvokingGHDL cmdoption-ghdl-p}@anchor{db} +@deffn {Option} @w{-}P + +Add @cite{DIRECTORY} to the end of the list of directories to be searched for library files. +A library is searched in @cite{DIRECTORY} and also in @cite{DIRECTORY/LIB/vVV} (where @cite{LIB} is the name of the library and @cite{VV} +the vhdl standard). + +The @cite{WORK} library is always searched in the path specified by the @ref{9d,,--workdir} option, or in the current +directory if the latter option is not specified. +@end deffn + +@geindex ghdl command line option; -fexplicit +@anchor{using/InvokingGHDL cmdoption-ghdl-fexplicit}@anchor{84} +@deffn {Option} @w{-}fexplicit + +When two operators are overloaded, give preference to the explicit declaration. +This may be used to avoid the most common pitfall of the @code{std_logic_arith} package. +See section @ref{67,,IEEE library pitfalls}, for an example. +@end deffn + +@cartouche +@quotation Warning +This option is not set by default. +We don’t think this option is a good feature, because it breaks the encapsulation rule. +When set, an operator can be silently overridden in another package. +You’d do better to fix your design and use the @code{numeric_std} package. +@end quotation +@end cartouche + +@geindex ghdl command line option; -frelaxed +@anchor{using/InvokingGHDL cmdoption-ghdl-frelaxed}@anchor{d8} +@deffn {Option} @w{-}frelaxed +@end deffn + +@geindex ghdl command line option; -frelaxed-rules +@anchor{using/InvokingGHDL cmdoption-ghdl-frelaxed-rules}@anchor{85} +@deffn {Option} @w{-}frelaxed@w{-}rules + +@cartouche +@quotation Important +The effects of this option are reset by @ref{82,,--std}, so it should be placed @emph{after} that option. +@end quotation +@end cartouche + +Slightly relax some rules to be compatible with various other simulators or synthesizers: + + +@itemize * + +@item +VHDL-87 file declarations are accepted; + +@item +Default binding indication rules of VHDL-02 are used. Default binding rules are often used, but they are +particularly obscure before VHDL-02. + +@item +Within an object declaration, allow references to the name (which references the hidden declaration). +This ignores the error in the following code: + +@example +package pkg1 is + type state is (state1, state2, state3); +end pkg1; + +use work.pkg1.all; +package pkg2 is + constant state1 : state := state1; +end pkg2; +@end example + +Some code (such as Xilinx packages) have such constructs, which are invalid. + +(The scope of the @code{state1} constant starts at the @cite{constant} keyword. +Because the constant @code{state1} and the enumeration literal @code{state1} are homographs, the enumeration literal is +hidden in the immediate scope of the constant). +@end itemize + +This option also relaxes the rules about pure functions. +Violations result in warnings instead of errors. +@end deffn + +@geindex ghdl command line option; -fpsl +@anchor{using/InvokingGHDL cmdoption-ghdl-fpsl}@anchor{dc} +@deffn {Option} @w{-}fpsl + +Enable parsing of PSL assertions within comments. +See section @ref{dd,,PSL support} for more details. +@end deffn + +@geindex ghdl command line option; --mb-comments +@geindex ghdl command line option; -C +@anchor{using/InvokingGHDL cmdoption-ghdl-mb-comments}@anchor{8b}@anchor{using/InvokingGHDL cmdoption-ghdl-C}@anchor{de} +@deffn {Option} @w{-}@w{-}mb@w{-}comments, @w{-}C + +Allow UTF8 or multi-bytes chars in a comment. + +According to the VHDL standards before 2002, the only characters allowed in a source file (and that includes the +comments) are the graphical characters of the ISO 8859-1 character set. +This is incompatible with comments using UTF-8 or some other encoding. +This option lift this restriction. +@end deffn + +@geindex ghdl command line option; --syn-binding +@anchor{using/InvokingGHDL cmdoption-ghdl-syn-binding}@anchor{df} +@deffn {Option} @w{-}@w{-}syn@w{-}binding + +Use synthesizer rules for component binding. +During elaboration, if a component is not bound to an entity using VHDL LRM rules, try to find in any known library an +entity whose name is the same as the component name. + +This rule is known as the synthesizer rule. + +There are two key points: normal VHDL LRM rules are tried first and entities are searched only in known libraries. +A known library is a library which has been named in your design. + +This option is only useful during elaboration. +@end deffn + +@geindex ghdl command line option; --format= +@anchor{using/InvokingGHDL cmdoption-ghdl-format}@anchor{e0} +@deffn {Option} @w{-}@w{-}format= + +Define the output format of some options, such as @ref{e1,,--pp-html} or @ref{e2,,--xref-html}. + + +@itemize * + +@item +By default or when @ref{e0,,--format=html2} is specified, generated files follow the HTML 2.0 standard, +and colours are specified with @cite{} tags. +However, colours are hard-coded. + +@item +If @ref{e0,,--format=css} is specified, generated files follow the HTML 4.0 standard, and use the CSS-1 +file @code{ghdl.css} to specify colours. +This file is generated only if it does not already exist (it is never overwritten) and can be customized by the user +to change colours or appearance. +Refer to a generated file and its comments for more information. +@end itemize +@end deffn + +@geindex ghdl command line option; --no-vital-checks +@anchor{using/InvokingGHDL cmdoption-ghdl-no-vital-checks}@anchor{e3} +@deffn {Option} @w{-}@w{-}no@w{-}vital@w{-}checks +@end deffn + +@geindex ghdl command line option; --vital-checks +@anchor{using/InvokingGHDL cmdoption-ghdl-vital-checks}@anchor{e4} +@deffn {Option} @w{-}@w{-}vital@w{-}checks + +Disable or enable checks of restriction on VITAL units. Checks are enabled by default. + +Checks are performed only when a design unit is decorated by a VITAL attribute. +The VITAL attributes are @code{VITAL_Level0} and @code{VITAL_Level1}, both declared in the @code{ieee.VITAL_Timing} package. + +Currently, VITAL checks are only partially implemented. +See section @ref{e5,,VHDL restrictions for VITAL} for more details. +@end deffn + +@geindex ghdl command line option; --PREFIX= +@anchor{using/InvokingGHDL cmdoption-ghdl-PREFIX}@anchor{b9}@anchor{using/InvokingGHDL cmdoption-ghdl-prefix}@anchor{e6} +@deffn {Option} @w{-}@w{-}PREFIX= + +Use @code{PATH} as the prefix path to find commands and pre-installed (@code{std} and @code{ieee}) libraries. +@end deffn + +@geindex ghdl command line option; -v +@anchor{using/InvokingGHDL cmdoption-ghdl-v}@anchor{e7} +@deffn {Option} @w{-}v + +Be verbose. For example, for analysis, elaboration and make commands, GHDL displays the commands executed. +@end deffn + +@geindex ghdl command line option; -o= +@anchor{using/InvokingGHDL cmdoption-ghdl-o}@anchor{e8} +@deffn {Option} @w{-}o= + +All the commands that perform a link (@ref{8c,,-e}, @ref{c7,,--elab-run}, @ref{e9,,--link}, @ref{cb,,-c}, +@ref{cf,,-m}, etc.) support overriding the location and name of the generated artifact. +@end deffn + +@geindex ghdl command line option; --time-resolution= +@anchor{using/InvokingGHDL cmdoption-ghdl-time-resolution}@anchor{ea} +@deffn {Option} @w{-}@w{-}time@w{-}resolution= + +@cartouche +@quotation Attention +This feature is supported with @emph{mcode} backend only. +It is not possible to support it with either LLVM or GCC backends, because it needs to apply globally. +@end quotation +@end cartouche + +Set the base time resolution of the simulation. +This option is supported in commands @ref{be,,-a} and @ref{8d,,-r} only. +Allowed values are @code{auto} (default), @code{fs}, @code{ps}, @code{ns}, @code{us}, @code{ms} or @code{sec}. +With LLVM/GCC, the value is fixed to @code{fs}. + +@cartouche +@quotation Hint +When overriding the time resolution, all the time units that are used in the design must be larger. +Using units below the resolution will produce a failure. +@end quotation +@end cartouche +@end deffn + +@node Warnings,Diagnostics Control,Options,Invoking GHDL +@anchor{using/InvokingGHDL warnings}@anchor{eb} +@section Warnings + + +Some constructions are not erroneous but dubious. +Warnings are diagnostic messages that report such constructions. +Some warnings are reported only during analysis, others during elaboration. + +@cartouche +@quotation Hint +You could disable a warning by using the @code{--warn-no-XXX} or @code{-Wno-XXX} instead of @code{--warn-XXX} or @code{-WXXX}. +@end quotation +@end cartouche + +@cartouche +@quotation Hint +The warnings @code{-Wbinding}, @code{-Wlibrary}, @code{-Wshared}, @code{-Wpure}, @code{-Wspecs}, @code{-Whide}, @code{-Wport} are enabled +by default. +@end quotation +@end cartouche + +@geindex ghdl command line option; --warn-library +@anchor{using/InvokingGHDL cmdoption-ghdl-warn-library}@anchor{ec} +@deffn {Option} @w{-}@w{-}warn@w{-}library + +Warns if a design unit replaces another design unit with the same name. +@end deffn + +@geindex ghdl command line option; --warn-default-binding +@anchor{using/InvokingGHDL cmdoption-ghdl-warn-default-binding}@anchor{ed} +@deffn {Option} @w{-}@w{-}warn@w{-}default@w{-}binding + +During analyze, warns if a component instantiation has neither configuration specification nor default binding. +This may be useful if you want to detect during analyze possibly unbound components if you don’t use configuration. +See section @ref{81,,VHDL standards} for more details about default binding rules. +@end deffn + +@geindex ghdl command line option; --warn-binding +@anchor{using/InvokingGHDL cmdoption-ghdl-warn-binding}@anchor{ee} +@deffn {Option} @w{-}@w{-}warn@w{-}binding + +During elaboration, warns if a component instantiation is not bound (and not explicitly left unbound). +Also warns if a port of an entity is not bound in a configuration specification or in a component configuration. +This warning is enabled by default, since default binding rules are somewhat complex and an unbound component is most +often unexpected. + +However, warnings are still emitted if a component instantiation is inside a generate statement. +As a consequence, if you use the conditional generate statement to select a component according to the implementation, +you will certainly get warnings. +@end deffn + +@geindex ghdl command line option; --warn-reserved +@anchor{using/InvokingGHDL cmdoption-ghdl-warn-reserved}@anchor{ef} +@deffn {Option} @w{-}@w{-}warn@w{-}reserved + +Emit a warning if an identifier is a reserved word in a later VHDL standard. +@end deffn + +@geindex ghdl command line option; --warn-nested-comment +@anchor{using/InvokingGHDL cmdoption-ghdl-warn-nested-comment}@anchor{f0} +@deffn {Option} @w{-}@w{-}warn@w{-}nested@w{-}comment + +Emit a warning if a @code{/*} appears within a block comment (vhdl 2008). +@end deffn + +@geindex ghdl command line option; --warn-parenthesis +@anchor{using/InvokingGHDL cmdoption-ghdl-warn-parenthesis}@anchor{f1} +@deffn {Option} @w{-}@w{-}warn@w{-}parenthesis + +Emit a warning in case of weird use of parentheses. +@end deffn + +@geindex ghdl command line option; --warn-vital-generic +@anchor{using/InvokingGHDL cmdoption-ghdl-warn-vital-generic}@anchor{f2} +@deffn {Option} @w{-}@w{-}warn@w{-}vital@w{-}generic + +Warns if a generic name of a vital entity is not a vital generic name. This +is set by default. +@end deffn + +@geindex ghdl command line option; --warn-delayed-checks +@anchor{using/InvokingGHDL cmdoption-ghdl-warn-delayed-checks}@anchor{f3} +@deffn {Option} @w{-}@w{-}warn@w{-}delayed@w{-}checks + +Warns for checks that cannot be done during analysis time and are postponed to elaboration time. +This is because not all procedure bodies are available during analysis (either because a package body has not yet been +analysed or because @cite{GHDL} doesn’t read not required package bodies). + +These are checks for no wait statements in a procedure called in a sensitized process and checks for pure rules of a +function. +@end deffn + +@geindex ghdl command line option; --warn-body +@anchor{using/InvokingGHDL cmdoption-ghdl-warn-body}@anchor{f4} +@deffn {Option} @w{-}@w{-}warn@w{-}body + +Emit a warning if a package body which is not required is analyzed. If a package does not declare a subprogram or a +deferred constant, the package does not require a body. +@end deffn + +@geindex ghdl command line option; --warn-specs +@anchor{using/InvokingGHDL cmdoption-ghdl-warn-specs}@anchor{f5} +@deffn {Option} @w{-}@w{-}warn@w{-}specs + +Emit a warning if an all or others specification does not apply. +@end deffn + +@geindex ghdl command line option; --warn-runtime-error +@anchor{using/InvokingGHDL cmdoption-ghdl-warn-runtime-error}@anchor{f6} +@deffn {Option} @w{-}@w{-}warn@w{-}runtime@w{-}error + +Emit a warning in case of runtime error that is detected during analysis. +@end deffn + +@geindex ghdl command line option; --warn-shared +@anchor{using/InvokingGHDL cmdoption-ghdl-warn-shared}@anchor{f7} +@deffn {Option} @w{-}@w{-}warn@w{-}shared + +Emit a warning when a shared variable is declared and its type it not a protected type. +@end deffn + +@geindex ghdl command line option; --warn-hide +@anchor{using/InvokingGHDL cmdoption-ghdl-warn-hide}@anchor{f8} +@deffn {Option} @w{-}@w{-}warn@w{-}hide + +Emit a warning when a declaration hides a previous hide. +@end deffn + +@geindex ghdl command line option; --warn-unused +@anchor{using/InvokingGHDL cmdoption-ghdl-warn-unused}@anchor{f9} +@deffn {Option} @w{-}@w{-}warn@w{-}unused + +Emit a warning when a subprogram is never used. +@end deffn + +@geindex ghdl command line option; --warn-others +@anchor{using/InvokingGHDL cmdoption-ghdl-warn-others}@anchor{fa} +@deffn {Option} @w{-}@w{-}warn@w{-}others + +Emit a warning is an @cite{others} choice is not required because all the choices have been explicitly covered. +@end deffn + +@geindex ghdl command line option; --warn-pure +@anchor{using/InvokingGHDL cmdoption-ghdl-warn-pure}@anchor{fb} +@deffn {Option} @w{-}@w{-}warn@w{-}pure + +Emit a warning when a pure rules is violated (like declaring a pure function with access parameters). +@end deffn + +@geindex ghdl command line option; --warn-static +@anchor{using/InvokingGHDL cmdoption-ghdl-warn-static}@anchor{fc} +@deffn {Option} @w{-}@w{-}warn@w{-}static + +Emit a warning when a non-static expression is used at a place where the standard requires a static expression. +@end deffn + +@geindex ghdl command line option; --warn-error +@anchor{using/InvokingGHDL cmdoption-ghdl-warn-error}@anchor{fd} +@deffn {Option} @w{-}@w{-}warn@w{-}error + +When this option is set, warnings are considered as errors. +@end deffn + +@node Diagnostics Control,Library commands,Warnings,Invoking GHDL +@anchor{using/InvokingGHDL diagnostics-control}@anchor{fe} +@section Diagnostics Control + + +@geindex ghdl command line option; -fcolor-diagnostics +@anchor{using/InvokingGHDL cmdoption-ghdl-fcolor-diagnostics}@anchor{ff} +@deffn {Option} @w{-}fcolor@w{-}diagnostics +@end deffn + +@geindex ghdl command line option; -fno-color-diagnostics +@anchor{using/InvokingGHDL cmdoption-ghdl-fno-color-diagnostics}@anchor{100} +@deffn {Option} @w{-}fno@w{-}color@w{-}diagnostics + +Control whether diagnostic messages are displayed in color. The default is on when the standard output is a terminal. +@end deffn + +@geindex ghdl command line option; -fdiagnostics-show-option +@anchor{using/InvokingGHDL cmdoption-ghdl-fdiagnostics-show-option}@anchor{101} +@deffn {Option} @w{-}fdiagnostics@w{-}show@w{-}option +@end deffn + +@geindex ghdl command line option; -fno-diagnostics-show-option +@anchor{using/InvokingGHDL cmdoption-ghdl-fno-diagnostics-show-option}@anchor{102} +@deffn {Option} @w{-}fno@w{-}diagnostics@w{-}show@w{-}option + +Control whether the warning option is displayed at the end of warning messages, so that the user can easily know how +to disable it. +@end deffn + +@geindex ghdl command line option; -fcaret-diagnostics +@anchor{using/InvokingGHDL cmdoption-ghdl-fcaret-diagnostics}@anchor{103} +@deffn {Option} @w{-}fcaret@w{-}diagnostics +@end deffn + +@geindex ghdl command line option; -fno-caret-diagnostics +@anchor{using/InvokingGHDL cmdoption-ghdl-fno-caret-diagnostics}@anchor{104} +@deffn {Option} @w{-}fno@w{-}caret@w{-}diagnostics + +Control whether the source line of the error is displayed with a caret indicating the column of the error. +@end deffn + +@node Library commands,VPI/VHPI build commands,Diagnostics Control,Invoking GHDL +@anchor{using/InvokingGHDL library-commands}@anchor{105} +@section Library commands + +@anchor{using/InvokingGHDL create-a-library}@anchor{106} +@geindex create your own library + +A new library is created implicitly, by compiling entities (packages etc.) into it: +@code{ghdl -a --work=my_custom_lib my_file.vhdl}. + +A library’s source code is usually stored and compiled into its own directory, that you specify with the +@ref{9d,,--workdir} option: +@code{ghdl -a --work=my_custom_lib --workdir=my_custom_libdir my_custom_lib_srcdir/my_file.vhdl}. +See also the @ref{87,,-P} command line option. + +Furthermore, GHDL provides a few commands which act on a library: + +@geindex cmd library directory + +@geindex ghdl command line option; --dir <[options...] [libs]> +@anchor{using/InvokingGHDL cmdoption-ghdl-dir}@anchor{107} +@deffn {Option} @w{-}@w{-}dir <[options...] [libs]> +@end deffn + +Displays the content of the design libraries (by default the @code{work} library). +All options are allowed, but only a few are meaningful: @ref{86,,--work}, @ref{9d,,--workdir} and @ref{82,,--std}. + +@geindex cmd library clean +@anchor{using/InvokingGHDL clean-command}@anchor{a1} +@geindex ghdl command line option; --clean <[options...]> +@anchor{using/InvokingGHDL cmdoption-ghdl-clean}@anchor{108} +@deffn {Option} @w{-}@w{-}clean <[options...]> +@end deffn + +Try to remove any object, executable or temporary file it could have created. +Source files are not removed. +The library is kept. + +@geindex cmd library remove +@anchor{using/InvokingGHDL remove-command}@anchor{a2} +@geindex ghdl command line option; --remove <[options...]> +@anchor{using/InvokingGHDL cmdoption-ghdl-remove}@anchor{109} +@deffn {Option} @w{-}@w{-}remove <[options...]> +@end deffn + +Acts like the clean command but removes the library too. +Note that after removing a design library, the files are not known anymore by GHDL. + +@geindex cmd library copy + +@geindex ghdl command line option; --copy <--work=name [options...]> +@anchor{using/InvokingGHDL cmdoption-ghdl-copy}@anchor{10a} +@deffn {Option} @w{-}@w{-}copy <@w{-}@w{-}work=name [options...]> +@end deffn + +Make a local copy of an existing library. +This is very useful if you want to add units to the @code{ieee} library: + +@example +ghdl --copy --work=ieee --ieee=synopsys +ghdl -a --work=ieee numeric_unsigned.vhd +@end example + +@node VPI/VHPI build commands,IEEE library pitfalls,Library commands,Invoking GHDL +@anchor{using/InvokingGHDL vpi-build-commands}@anchor{10b}@anchor{using/InvokingGHDL vpi-vhpi-build-commands}@anchor{10c} +@section VPI/VHPI build commands + + +These commands simplify the compile and the link of a user VPI or VHPI module. +They are all wrappers: the arguments are in fact a whole command line that is executed with additional switches. +Currently a unix-like compiler (like @cite{cc}, @cite{gcc} or @cite{clang}) is expected: the additional switches use their syntax. +The only option is @cite{-v} which displays the command before its execution. + +@geindex cmd VPI compile + +@geindex ghdl command line option; --vpi-compile +@anchor{using/InvokingGHDL cmdoption-ghdl-vpi-compile}@anchor{10d} +@deffn {Option} @w{-}@w{-}vpi@w{-}compile +@end deffn + +Add an include path to the command and execute it: + +@example +ghdl --vpi-compile command +@end example + +This will execute: + +@example +command -Ixxx/include +@end example + +For example, @code{ghdl --vpi-compile gcc -c vpi1.c} executes @code{gcc -c vpi1.c -fPIC -Ixxx/include}. +@anchor{using/InvokingGHDL vpi-link-command}@anchor{10e} +@geindex cmd VPI link + +@geindex ghdl command line option; --vpi-link +@anchor{using/InvokingGHDL cmdoption-ghdl-vpi-link}@anchor{10f} +@deffn {Option} @w{-}@w{-}vpi@w{-}link +@end deffn + +Add a library path and name to the command and execute it: + +@example +ghdl --vpi-link command +@end example + +This will execute: + +@example +command -Lxxx/lib -lghdlvpi +@end example + +For example, @code{ghdl --vpi-link gcc -o vpi1.vpi vpi1.o} executes @code{gcc -o vpi1.vpi vpi1.o --shared -Lxxx/lib -lghdlvpi}. +@anchor{using/InvokingGHDL vpi-cflags-command}@anchor{110} +@geindex cmd VPI cflags + +@geindex ghdl command line option; --vpi-cflags +@anchor{using/InvokingGHDL cmdoption-ghdl-vpi-cflags}@anchor{111} +@deffn {Option} @w{-}@w{-}vpi@w{-}cflags +@end deffn + +Display flags added by @ref{10d,,--vpi-compile}. + +@geindex cmd VPI ldflags + +@geindex ghdl command line option; --vpi-ldflags +@anchor{using/InvokingGHDL cmdoption-ghdl-vpi-ldflags}@anchor{112} +@deffn {Option} @w{-}@w{-}vpi@w{-}ldflags +@end deffn + +Display flags added by @ref{10f,,--vpi-link}. + +@geindex cmd VPI include dir + +@geindex ghdl command line option; --vpi-include-dir +@anchor{using/InvokingGHDL cmdoption-ghdl-vpi-include-dir}@anchor{113} +@deffn {Option} @w{-}@w{-}vpi@w{-}include@w{-}dir +@end deffn + +Display the include directory added by the compile flags. + +@geindex cmd VPI library dir + +@geindex ghdl command line option; --vpi-library-dir +@anchor{using/InvokingGHDL cmdoption-ghdl-vpi-library-dir}@anchor{114} +@deffn {Option} @w{-}@w{-}vpi@w{-}library@w{-}dir +@end deffn + +Display the library directory added by the link flags. + +@geindex ghdl command line option; --vpi-library-dir-unix +@anchor{using/InvokingGHDL cmdoption-ghdl-vpi-library-dir-unix}@anchor{115} +@deffn {Option} @w{-}@w{-}vpi@w{-}library@w{-}dir@w{-}unix +@end deffn + +Display the library directory added by the link flags, forcing UNIX syntax. + +@node IEEE library pitfalls,,VPI/VHPI build commands,Invoking GHDL +@anchor{using/InvokingGHDL id1}@anchor{116}@anchor{using/InvokingGHDL ieee-library-pitfalls}@anchor{67} +@section IEEE library pitfalls + + +When you use options @ref{83,,--ieee=synopsys}, the @code{ieee} library contains non standard packages such as +@code{std_logic_arith}. +These packages are not standard because there are not described by an IEEE standard, even if they have been put in the +@cite{IEEE} library. +Furthermore, they are not really de-facto standard, because there are slight differences between the packages of Mentor +and those of Synopsys. +Furthermore, since they are not well thought out, their use has pitfalls. +For example, this description has an error during compilation: + +@example +library ieee; +use ieee.std_logic_1164.all; + +-- A counter from 0 to 10. +entity counter is + port (val : out std_logic_vector (3 downto 0); + ck : std_logic; + rst : std_logic); +end counter; + +library ieee; +use ieee.std_logic_unsigned.all; + +architecture bad of counter +is + signal v : std_logic_vector (3 downto 0); +begin + process (ck, rst) + begin + if rst = '1' then + v <= x"0"; + elsif rising_edge (ck) then + if v = "1010" then -- Error + v <= x"0"; + else + v <= v + 1; + end if; + end if; + end process; + + val <= v; +end bad; +@end example + +When you analyze this design, GHDL does not accept it (two long lines have been split for readability): + +@example +ghdl -a --ieee=synopsys bad_counter.vhdl +bad_counter.vhdl:13:14: operator "=" is overloaded +bad_counter.vhdl:13:14: possible interpretations are: +../../libraries/ieee/std_logic_1164.v93:69:5: implicit function "=" + [std_logic_vector, std_logic_vector return boolean] +../../libraries/synopsys/std_logic_unsigned.vhdl:64:5: function "=" + [std_logic_vector, std_logic_vector return boolean] +../translate/ghdldrv/ghdl: compilation error +@end example + +Indeed, the @cite{“=”} operator is defined in both packages, and both are visible at the place it is used. +The first declaration is an implicit one, which occurs when the @cite{std_logic_vector} type is declared and is an element to +element comparison. +The second one is an explicit declared function, with the semantics of an unsigned comparison. + +With some analysers, the explicit declaration has priority over the implicit declaration, and this design can be +analyzed without error. +However, this is not the rule given by the VHDL LRM, and since GHDL follows these rules, it emits an error. + +You can force GHDL to use this rule with the @emph{-fexplicit} option (see @ref{bf,,Options} for further details). +However it is easy to fix this error, by using a selected name: + +@example +library ieee; +use ieee.std_logic_unsigned.all; + +architecture fixed_bad of counter +is + signal v : std_logic_vector (3 downto 0); +begin + process (ck, rst) + begin + if rst = '1' then + v <= x"0"; + elsif rising_edge (ck) then + if ieee.std_logic_unsigned."=" (v, "1010") then + v <= x"0"; + else + v <= v + 1; + end if; + end if; + end process; + + val <= v; +end fixed_bad; +@end example + +It is better to only use the standard packages defined by IEEE, which provide the same functionalities: + +@example +library ieee; +use ieee.numeric_std.all; + +architecture good of counter +is + signal v : unsigned (3 downto 0); +begin + process (ck, rst) + begin + if rst = '1' then + v <= x"0"; + elsif rising_edge (ck) then + if v = "1010" then + v <= x"0"; + else + v <= v + 1; + end if; + end if; + end process; + + val <= std_logic_vector (v); +end good; +@end example + +@geindex Math_Real + +@geindex Math_Complex + +@cartouche +@quotation Hint +The @code{ieee} math packages (@code{math_real} and @code{math_complex}) provided with @cite{GHDL} are fully compliant with the +@cite{IEEE} standard. +@end quotation +@end cartouche + +@c # Load pre-defined aliases and graphical characters like © from docutils +@c # is used to denote the special path +@c # \Lib\site-packages\docutils\parsers\rst\include + +@c This data file has been placed in the public domain. + +@c Derived from the Unicode character mappings available from +@c . +@c Processed by unicode2rstsubs.py, part of Docutils: +@c . + +@c This data file has been placed in the public domain. + +@c Derived from the Unicode character mappings available from +@c . +@c Processed by unicode2rstsubs.py, part of Docutils: +@c . + +@c # define a hard line break for HTML + +@node Simulation runtime,Synthesis,Invoking GHDL,Top +@anchor{using/Simulation doc}@anchor{117}@anchor{using/Simulation simulation-runtime}@anchor{118}@anchor{using/Simulation using-simulation}@anchor{c4} +@chapter Simulation (runtime) + + +@menu +* Simulation options:: +* Export waveforms:: +* Export hierarchy and references:: + +@end menu + +@node Simulation options,Export waveforms,,Simulation runtime +@anchor{using/Simulation id1}@anchor{119}@anchor{using/Simulation simulation-options}@anchor{9a} +@section Simulation options + + +In most system environments, it is possible to pass CLI options while +invoking a program. Contrary to most programming languages, there is no +standard method in VHDL to obtain the arguments or to set the exit +status. +However, the GHDL runtime behaviour can be modified with some options: + + +@itemize - + +@item +It is possible to pass parameters to your design through the generic +interfaces of the top entity. + +@item +It is also possible to stop simulation after a certain time. The exit +status of the simulation is @code{EXIT_SUCCESS} (@code{0}) if the simulation +completes, or @code{EXIT_FAILURE} (@code{1}) in case of error (assertion +failure, overflow or any constraint error). +@end itemize + +Here is the list of the most useful options. For further info, see @ref{11a,,Debugging}. + +@cartouche +@quotation Hint +Note that these arguments are represented as @code{simulation_options...} in this documentation. +For analysis/elaboration options, see @ref{5f,,Invoking GHDL}. +@end quotation +@end cartouche + +@geindex ghdl command line option; -gGENERIC=VALUE +@anchor{using/Simulation cmdoption-ghdl-gGENERIC}@anchor{11b}@anchor{using/Simulation cmdoption-ghdl-ggeneric}@anchor{11c} +@deffn {Option} @w{-}gGENERIC=VALUE + +Set value @cite{VALUE} to generic with name @cite{GENERIC}. + +Example: + +@example +$ ghdl -r --std=08 my_unit -gDEPTH=12 +@end example + +@cartouche +@quotation Note +This is currently a run option; but in the (not near) future it might be deprecated to +become an elaboration option only. As a result, now you can generate a single binary and +execute it multiple times with different arguments. That might not be possible in the future. + +As explained in @ref{8c,,-e}, performing a complete elaboration in terms of the LRM requires +to get rid of the compile and link model. This is mostly because delaying certain elaboration +steps to the runtime prevents elaboration-time optimisions. +@end quotation +@end cartouche + +@cartouche +@quotation Hint +Currently, GHDL has limited support for generic types in the CLI. It is suggested to use strings or integers. Nonetheless, project JSON-for-VHDL@footnote{https://github.com/Paebbels/JSON-for-VHDL} allows to encode a set of parameters as stringified JSON, and it provides VHDL functions to read specific values from it. It is valid for synthesis. +@end quotation +@end cartouche +@end deffn + +@geindex ghdl command line option; --assert-level= +@anchor{using/Simulation cmdoption-ghdl-assert-level}@anchor{a0} +@deffn {Option} @w{-}@w{-}assert@w{-}level= + +Select the assertion level at which an assertion violation stops the +simulation. @cite{LEVEL} is the name from the @cite{severity_level} +enumerated type defined in the @cite{standard} package or the +@code{none} name. + +By default, only assertion violation of severity level @code{failure} +stops the simulation. + +For example, if @cite{LEVEL} was @code{warning}, any assertion violation +with severity level @code{warning}, @code{error} or @code{failure} would +stop simulation, but the assertion violation at the @code{note} severity +level would only display a message. + +Option @ref{a0,,--assert-level=none} prevents any +assertion violation from stopping simulation. +@end deffn + +@geindex ghdl command line option; --backtrace-severity= +@anchor{using/Simulation cmdoption-ghdl-backtrace-severity}@anchor{11d} +@deffn {Option} @w{-}@w{-}backtrace@w{-}severity= + +Select the assertion level at which an assertion violation display a +backtrace (if available). + +This is useful when the assertion is generated by a function (like +assertions in @code{ieee.numeric_std}) whose location is not very +useful. +@end deffn + +@geindex ghdl command line option; --ieee-asserts= +@anchor{using/Simulation cmdoption-ghdl-ieee-asserts}@anchor{11e} +@deffn {Option} @w{-}@w{-}ieee@w{-}asserts= +@end deffn + +@geindex ghdl command line option; --asserts= +@anchor{using/Simulation cmdoption-ghdl-asserts}@anchor{11f} +@deffn {Option} @w{-}@w{-}asserts= + +Select how assertions are handled. @cite{POLICY} can be @code{enable} (the +default), @code{disable} which disables all assertions and +@code{disable-at-0} which disables only at the start of simulation. + +The @code{--ieee-asserts} applies only to assertions from @code{ieee} +package. This option can be useful to avoid assertion messages from +@code{ieee.numeric_std} (and other @code{ieee} packages). + +The @code{--asserts} option applies to all assertions, including those +from the @code{ieee} units. The behaviour of the latter can be +overridden by using the @code{--ieee-asserts} option after the +@code{--asserts} option. +@end deffn + +@geindex ghdl command line option; --stop-time=