\input texinfo @c -*-texinfo-*- @c %**start of header @setfilename GHDL.info @documentencoding UTF-8 @ifinfo @*Generated by Sphinx 6.1.3.@* @end ifinfo @settitle GHDL Documentation @defindex ge @paragraphindent 0 @exampleindent 4 @finalout @dircategory Miscellaneous @direntry * GHDL: (GHDL.info). VHDL simulator. @end direntry @c %**end of header @copying @quotation GHDL 3.0.0, Mar 08, 2023 Tristan Gingold and contributors Copyright @copyright{} 2002-2023, Tristan Gingold and contributors @end quotation @end copying @titlepage @title GHDL Documentation @insertcopying @end titlepage @contents @c %** start of user preamble @c %** end of user preamble @ifnottex @node Top @top GHDL Documentation @insertcopying @end ifnottex @c %**start of body @anchor{index doc}@anchor{45} @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 @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 * 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>. * [Next] 4.0: [Next] 4 0. * [2023-03-08] 3.0.0: [2023-03-08] 3 0 0. * [2022-02-28] 2.0: [2022-02-28] 2 0. * [2021-02-02] 1.0: [2021-02-02] 1 0. * [2021-01-31] 1.0.0rc1: [2021-01-31] 1 0 0rc1. * [2020-05-21] Nightly build assets:: * [2020-05-09] New repositories and a wiki:: * [2020-02-28] 0.37: [2020-02-28] 0 37. * [2019-03-03] 0.36: [2019-03-03] 0 36. * [2019-02-23] 0.36-rc1: [2019-02-23] 0 36-rc1. * [2018-11-29] 20181129:: * [2017-12-20] GitHub organization:: * [2017-12-14] 0.35: [2017-12-14] 0 35. * [2017-08-15] 0.34: [2017-08-15] 0 34. * [2015-10-23] 0.33: [2015-10-23] 0 33. * [2014-11-XX] 0.32: [2014-11-XX] 0 32. * [2014-01-XX] 0.31: [2014-01-XX] 0 31. * 0.30: 0 30. * [2010-01-09] 0.29: [2010-01-09] 0 29. * [2009-09-17] 0.28: [2009-09-17] 0 28. * [2008-07-01] 0.27: [2008-07-01] 0 27. * [2007-04-08] 0.26: [2007-04-08] 0 26. * [2006-08-11] 0.25: [2006-08-11] 0 25. * [2006-06-25] 0.24: [2006-06-25] 0 24. * [2006-05-16] 0.23: [2006-05-16] 0 23. * [2006-03-28] 0.22: [2006-03-28] 0 22. * [2005-12-18] 0.21: [2005-12-18] 0 21. * 0.20 [2005-10-15]: 0 20 [2005-10-15]. * [2005-08-17] 0.19: [2005-08-17] 0 19. * [2005-03-12] 0.18: [2005-03-12] 0 18. * [2005-02-26] 0.17: [2005-02-26] 0 17. * [2005-01-02] 0.16: [2005-01-02] 0 16. * [2004-10-13] 0.15: [2004-10-13] 0 15. * [2004-08-29] 0.14: [2004-08-29] 0 14. * [2004-06-26] 0.13: [2004-06-26] 0 13. * [2004-05-30] 0.12: [2004-05-30] 0 12. * [2004-04-24] 0.11.1: [2004-04-24] 0 11 1. * [2004-04-17] 0.11: [2004-04-17] 0 11. * [2004-02-28] 0.10: [2004-02-28] 0 10. * [2004-02-01] 0.9: [2004-02-01] 0 9. * [2003-11-05] 0.8: [2003-11-05] 0 8. * [2003-08-02] 0.7: [2003-08-02] 0 7. * [2003-06-09] 0.6: [2003-06-09] 0 6. * [2003-05-10] 0.5: [2003-05-10] 0 5. * [2003-04-07] 0.4.1: [2003-04-07] 0 4 1. * [2003-04-02] 0.4: [2003-04-02] 0 4. * Python Module Index:: * Index:: @detailmenu --- The Detailed Node Listing --- About * What is VHDL?:: * What is GHDL?:: * Who uses GHDL?:: Getting | Installing * Package managers:: * Nightly packages:: * Precompile Vendor Primitives:: 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:: Copyrights | Licenses * GNU GPLv2:: * CC-BY-SA:: * List of Contributors:: Quick Start Guide * 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/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]:: Design rebuilding commands * Import [-i]:: * Elab-order [--elab-order]:: * Make [-m]:: * Generate Makefile [--gen-makefile]:: * Generate dependency file command [--gen-depends]:: Simulation (runtime) * Simulation options:: * Export waveforms:: * Export hierarchy and references:: Synthesis * Synthesis [--synth]:: * Synthesis options:: * Yosys plugin:: Synthesis options * Assertions@comma{} PSL and formal verification: Assertions PSL and formal verification. Yosys plugin * Convert (V)HDL to other formats: Convert V HDL to other formats. Convert (V)HDL to other formats * To Verilog:: * To EDIF:: * To SMT:: * To BTOR2:: * To FIRRTL:: * To VHDL:: Additional Command Reference * Environment variables:: * Misc commands:: * File commands:: * GCC/LLVM only commands:: * Options: Options<2>. * Passing options to other programs:: 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 and later): PSL annotations VHDL-2008 and later. * PSL vunit files (VHDL-2008 and later@comma{} synthesis only): PSL vunit files VHDL-2008 and later synthesis only. Implementation of VITAL * VITAL packages:: * VHDL restrictions for VITAL:: * Backannotation:: * Negative constraint calculation:: Building GHDL from Sources * 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. LLVM backend * 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.Attribute: pyGHDL dom Attribute. * pyGHDL.dom.Concurrent: pyGHDL dom Concurrent. * 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.Names: pyGHDL dom Names. * pyGHDL.dom.NonStandard: pyGHDL dom NonStandard. * pyGHDL.dom.Object: pyGHDL dom Object. * pyGHDL.dom.PSL: pyGHDL dom PSL. * pyGHDL.dom.Range: pyGHDL dom Range. * pyGHDL.dom.Sequential: pyGHDL dom Sequential. * 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.GraphML: pyGHDL dom formatting GraphML. * 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.file_comments: pyGHDL libghdl file_comments. * 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.str_table: pyGHDL libghdl str_table. * pyGHDL.libghdl.utils: pyGHDL libghdl utils. * 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.prints: pyGHDL libghdl vhdl prints. * pyGHDL.libghdl.vhdl.scanner: pyGHDL libghdl vhdl scanner. * 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.libghdl.vhdl.utils: pyGHDL libghdl vhdl utils. 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:: Debugging * Simulation and runtime debugging options:: Simulation and runtime debugging options * GNU Debugger (GDB): GNU Debugger GDB. Coding Style * Ada:: * Shell:: * Guidelines to edit the documentation:: * Documentation configuration:: Guidelines to edit the documentation * Guidelines to edit section ‘Building’:: Scripts * pnodes:: * pnodespy:: pnodes * positional arguments:: * optional arguments: optional arguments<2>. pnodespy * positional arguments: positional arguments<2>. * optional arguments: optional arguments<3>. AST * Introduction:: * The AST in GHDL:: * Why a meta-model ?:: * Dealing with ownership:: * Node Type:: Run Time Information (RTI) * Useful Definitions:: * RTI Nodes / RTII Nodes:: 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,Getting | Installing,Top,Top @anchor{about doc}@anchor{46}@anchor{about about}@anchor{47}@anchor{about ghdl}@anchor{48} @chapter About @menu * What is VHDL?:: * What is GHDL?:: * Who uses GHDL?:: @end menu @node What is VHDL?,What is GHDL?,,About @anchor{about intro-vhdl}@anchor{49}@anchor{about what-is-vhdl}@anchor{4a} @section What is @cite{VHDL}? VHDL@footnote{https://en.wikipedia.org/wiki/VHDL} is an acronym for `Verification and Hardware Description Language' (HDL@footnote{https://en.wikipedia.org/wiki/HDL}), which is a computer language used to describe a logic circuit by function, data flow behavior, or structure. @cartouche @quotation Note Historically the ‘V’ in the language’s acronym came from the Very High Speed Integrated Circuit (VHSIC@footnote{https://en.wikipedia.org/wiki/VHSIC}), which was the U.S. government program that funded the early work on the standard. Changing the ‘V’ to mean `verification' reflects the language’s increasing usage for verification as well as design. See VHDL 202X PAR@footnote{http://www.eda-twiki.org/twiki/pub/P1076/PrivateDocuments/Par1076_202X.pdf} via VHDL-202X@footnote{https://ieee-p1076.gitlab.io/VHDL-202X/index.html#vhdl202x}. @end quotation @end cartouche Although VHDL was not designed for writing general purpose programs, VHDL `is' a programming language: any algorithm can be written with it, it can interact with files, the environment, stdin and stdout, etc. VHDL has features similar to those found in procedural languages such as C@footnote{https://en.wikipedia.org/wiki/C_(programming_language)}, Python@footnote{https://en.wikipedia.org/wiki/Python_(programming_language)}, or Ada@footnote{https://en.wikipedia.org/wiki/Ada_(programming_language)}. 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-driven execution model. Like a program written in any other language, a VHDL program can be executed. Since VHDL is used to model designs, the term `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 `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}. 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 IEEE P1076 Working Group: VHDL Analysis and Standardization Group (VASG)@footnote{https://ieee-p1076.gitlab.io/index.html}. Find on-going work towards `VHDL 202X' in gitlab.com/IEEE-P1076/VHDL-Issues@footnote{https://gitlab.com/IEEE-P1076/VHDL-Issues/-/issues}. @node What is GHDL?,Who uses GHDL?,What is VHDL?,About @anchor{about intro-ghdl}@anchor{4b}@anchor{about what-is-ghdl}@anchor{4c} @section What is GHDL? @float Figure @image{GHDL-figures/internals,418.0pt,,,png} @caption{Architecture overview of the GHDL toolkit (CLI, libghdl, pyGHDL and ghdl-yosys-plugin).} @end float @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. @cartouche @quotation Note For almost 20 years, GHDL was `not' a synthesis tool: a netlist could not be created. Hence, most of the content in this documentation corresponds to the usage of GHDL as a compiler/simulator. See @ref{4d,,Synthesis} for further details regarding synthesis. @end quotation @end cartouche 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 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 `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. The current version of GHDL does not contain any built-in graphical viewer: signal waves cannot be seen through GHDL. However, the behavior of the designs can still be checked through test benches and verification frameworks. Moreover, @ref{4e,,GHDL Waveform (GHW)}, VCD@footnote{https://en.wikipedia.org/wiki/Value_change_dump} or @cite{FST} files can be produced, which can be viewed with an external waveform viewer@footnote{https://en.wikipedia.org/wiki/Waveform_viewer}, such as GtkWave@footnote{http://gtkwave.sourceforge.net/}. 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/} and 2019@footnote{https://ieeexplore.ieee.org/document/8938196/}. Property Specification Language (PSL)@footnote{https://en.wikipedia.org/wiki/Property_Specification_Language} is also partially supported. 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/}, The pyVHDLModel Documentation@footnote{https://vhdl.github.io/pyVHDLModel/index.html}, … @node Who uses GHDL?,,What is GHDL?,About @anchor{about intro-who}@anchor{4f}@anchor{about who-uses-ghdl}@anchor{50} @section Who uses GHDL? @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 Getting | Installing,Contributing,About,Top @anchor{getting doc}@anchor{51}@anchor{getting getting-installing}@anchor{52}@anchor{getting packages}@anchor{53} @chapter Getting | Installing @menu * Package managers:: * Nightly packages:: * Precompile Vendor Primitives:: @end menu @node Package managers,Nightly packages,,Getting | Installing @anchor{getting package-managers}@anchor{54} @section Package managers 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 (`regular' or `GPL-compatible'), at least six packages with different features might be available in each package manager. As a rule of thumb, mcode backend is the fastest for analysis and synthesis. It also allows setting the base simulation time for speeding up execution. Therefore, it is the recommended pick if available on your platform (x86/amd64, on Windows x86 only). On other platforms, or for using specific features for co-simulation or code coverage, LLVM or GCC need to be used. See further differences between backends in @ref{55,,Building GHDL from Sources}. @node Nightly packages,Precompile Vendor Primitives,Package managers,Getting | Installing @anchor{getting nightly-packages}@anchor{56}@anchor{getting release-packages}@anchor{57} @section Nightly packages 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. However, users on Windows (MSYS2) or Ubuntu might want to download the tarballs/zipfiles and extract/install them locally. @node Precompile Vendor Primitives,,Nightly packages,Getting | Installing @anchor{getting getting-precompvendor}@anchor{58}@anchor{getting precompile-vendor-primitives}@anchor{59} @section Precompile Vendor Primitives Vendors like Lattice, Intel (Altera) and Xilinx have their own simulation libraries, especially for FPGA primitives, soft and hard macros. These libraries cannot be shipped with GHDL, but GHDL offers prepared compile scripts to pre-compile these vendor libraries, if the vendor tool is present in the environment. There are also popular simulation and verification libraries like OSVVM @footnote{ OSVVM @indicateurl{http://github.com/OSVVM/OSVVM} } or UVVM @footnote{ UVVM @indicateurl{https://github.com/UVVM/UVVM_All} }, which can be pre-compiled, too. The compilation scripts are writen in the shell languages: `PowerShell' for `Windows™' and `Bash' for `GNU/Linux', `MacOS' and `MSYS2'/`MinGW'. The compile scripts can colorize the GHDL warning and error lines with the help of @code{grc/grcat} @footnote{ Generic Colourizer @indicateurl{http://kassiopeia.juls.savba.sk/~garabik/software/grc.html} }. @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 @menu * Supported Vendors Libraries:: * Supported Simulation and Verification Libraries:: * Script Configuration:: * Compiling in Bash:: * Compiling in PowerShell:: * Configuration Files:: * Additional Script Parameters:: @end menu @node Supported Vendors Libraries,Supported Simulation and Verification Libraries,,Precompile Vendor Primitives @anchor{getting supported-vendors-libraries}@anchor{5a} @subsection Supported Vendors Libraries @itemize * @item Lattice (3.6 or later): @itemize * @item @code{ec} @item @code{ecp}, @code{ecp2}, @code{ecp3}, @code{ecp5u} @item @code{lptm}, @code{lptm2} @item @code{machxo}, @code{machxo2}, @code{machxo3l}, @code{machxo3d} @item @code{sc}, @code{scm} @item @code{xp}, @code{xp2} @item … @end itemize @item Intel (Altera) Quartus (13.0 or later): @itemize * @item @code{lpm}, @code{sgate} @item @code{altera}, @code{altera_mf}, @code{altera_lnsim} @item @code{arriaii}, @code{arriaii_pcie_hip}, @code{arriaiigz} @item @code{arriav}, @code{arriavgz}, @code{arriavgz_pcie_hip} @item @code{cycloneiv}, @code{cycloneiv_pcie_hip}, @code{cycloneive} @item @code{cyclonev} @item @code{max}, @code{maxii}, @code{maxv} @item @code{stratixiv}, @code{stratixiv_pcie_hip} @item @code{stratixv}, @code{stratixv_pcie_hip} @item @code{fiftyfivenm}, @code{twentynm} @item … @end itemize @item Xilinx ISE (14.0 or later): @itemize * @item @code{unisim} (incl. @code{secureip}) @item @code{unimacro} @item @code{simprim} (incl. @code{secureip}) @item @code{xilinxcorelib} @end itemize @item Xilinx Vivado (2014.1 or later): @itemize * @item @code{unisim} (incl. @code{secureip}) @item @code{unimacro} @end itemize @end itemize @node Supported Simulation and Verification Libraries,Script Configuration,Supported Vendors Libraries,Precompile Vendor Primitives @anchor{getting supported-simulation-and-verification-libraries}@anchor{5b} @subsection Supported Simulation and Verification Libraries @itemize * @item OSVVM @footnote{ OSVVM @indicateurl{http://github.com/OSVVM/OSVVM} } (for VHDL-2008) @item UVVM @footnote{ UVVM @indicateurl{https://github.com/UVVM/UVVM_All} } (for VHDL-2008) @end itemize __________________________________________________________________ @node Script Configuration,Compiling in Bash,Supported Simulation and Verification Libraries,Precompile Vendor Primitives @anchor{getting script-configuration}@anchor{5c} @subsection Script Configuration The vendor library compile scripts need to know where the used / latest vendor tool chain is installed. Therefore, the scripts implement a default installation directory search as well as environment variable checks. If a vendor tool cannot be detected or the script chooses the wrong vendor library source directory, then it’s possible to provide the path via @code{--source} (Bash) or @code{-Source} (PoSh). The generated output is stored relative to the current working directory. The scripts create a sub-directory for each vendor. The default output directory can be overwritten by the parameter @code{--output} (Bash) or @code{-Output} (PoSh). 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. __________________________________________________________________ @node Compiling in Bash,Compiling in PowerShell,Script Configuration,Precompile Vendor Primitives @anchor{getting compiling-in-bash}@anchor{5d} @subsection Compiling in Bash The provided Bash scripts support these environments: @itemize * @item Linux @item MacOS @item MSYS2 / MinGW @item WSL (Windows Subsystem for Linux) @end itemize Follow these steps: @itemize * @item `Step 0 - Configure the scripts (optional)' See the next section for how to configure @code{config.sh}. @item `Step 1 - Browse to your simulation working directory' @example $ cd @end example @item `Step 2 - Start the compilation script(s)' 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 In most cases GHDL is installed into @code{/usr/local/}. The scripts are installed into the @code{lib\ghdl\vendors} directory. @item `Step 3 - Viewing the result' This creates vendor directories in your current working directory and compiles the vendor files into them. @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 __________________________________________________________________ @node Compiling in PowerShell,Configuration Files,Compiling in Bash,Precompile Vendor Primitives @anchor{getting compiling-in-powershell}@anchor{5e} @subsection Compiling in PowerShell The provided PowerShell scripts support these environments: @itemize * @item Windows™ 10 (PowerShell 5 and PowerShell 6) @end itemize Follow these steps: @itemize * @item `Step 0 - Configure the scripts (optional)' See the next section for how to configure @code{config.psm1}. @item `Step 1 - Browse to your simulation working directory' @example PS> cd @end example @item `Step 2 - Start the compilation script(s)' Choose one or multiple of the following scripts to run the pre-compilation process. @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 @c # In most cases GHDL is installed into ``/usr/local/``. The scripts are installed into the @code{lib\ghdl\vendors} directory. @item `Step 3 - Viewing the result' This creates vendor directories in your current working directory and compiles the vendor files into them. @example PS> dir Directory: D:\temp\ghdl Mode LastWriteTime Length Name ---- ------------- ------ ---- d---- 09.03.2018 19:33 altera d---- 09.03.2018 19:38 intel d---- 09.03.2018 19:38 lattice d---- 09.03.2018 19:38 osvvm d---- 09.03.2018 19:45 uvvm d---- 09.03.2018 19:06 xilinx-ise d---- 09.03.2018 19:40 xilinx-vivado @end example @end itemize __________________________________________________________________ @node Configuration Files,Additional Script Parameters,Compiling in PowerShell,Precompile Vendor Primitives @anchor{getting configuration-files}@anchor{5f} @subsection Configuration Files @menu * For Bash; config.sh: For Bash config sh. * For PowerShell; config.psm1: For PowerShell config psm1. @end menu @node For Bash config sh,For PowerShell config psm1,,Configuration Files @anchor{getting for-bash-config-sh}@anchor{60} @subsubsection For Bash: @cite{config.sh} 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. @code{config.sh}: @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 @node For PowerShell config psm1,,For Bash config sh,Configuration Files @anchor{getting for-powershell-config-psm1}@anchor{61} @subsubsection For PowerShell: @cite{config.psm1} 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. @code{config.psm1}: @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 @node Additional Script Parameters,,Configuration Files,Precompile Vendor Primitives @anchor{getting additional-script-parameters}@anchor{62} @subsection Additional Script Parameters Each script supports partial compilations e.g. of shared packages and individual parts. In addition, the amount of printout to the console can be controlled. Some scripts may offer vendor specific options. @menu * For Bash Scripts;: For Bash Scripts. * For PowerShell Scripts;: For PowerShell Scripts. @end menu @node For Bash Scripts,For PowerShell Scripts,,Additional Script Parameters @anchor{getting for-bash-scripts}@anchor{63} @subsubsection For Bash Scripts: @itemize * @item Common parameters to most scripts: @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 @code{compile-altera.sh} Selectable libraries: @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 Compile options: @example --vhdl93 Compile selected libraries with VHDL-93 (default). --vhdl2008 Compile selected libraries with VHDL-2008. @end example @item @code{compile-xilinx-ise.sh} 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 --simprim Compile the simprim primitives --corelib Compile the xilinxcorelib 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-xilinx-vivado.sh} 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 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: @example --all, -a Compile all. --osvvm Compile the OSVVM library. @end example @item @code{compile-uvvm.sh} Selectable libraries: @example --all, -a Compile all. --uvvm Compile the UVVM libraries. @end example @end itemize @node For PowerShell Scripts,,For Bash Scripts,Additional Script Parameters @anchor{getting for-powershell-scripts}@anchor{64} @subsubsection For PowerShell Scripts: @itemize * @item Common parameters to all scripts: @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} Selectable libraries: @example -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 Compile options: @example -VHDL93 Compile selected libraries with VHDL-93 (default). -VHDL2008 Compile selected libraries with VHDL-2008. @end example @item @code{compile-xilinx-ise.ps1} Selectable libraries: @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 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.ps1} Selectable libraries: @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{65}@anchor{contribute contributing}@anchor{66}@anchor{contribute intro-contributing}@anchor{67} @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{68,,Simulation} for an introduction. Furthermore, we encourage you to read @ref{69,,Invoking GHDL}, where the most commonly used options are explained. You can also check the complete @ref{6a,,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{6b,,Implementation of VHDL} and @ref{6c,,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//Users/gingold/devel/ghdl/doc/_build/doctrees/images/75d23ce669cbc7993d4d057361ad0c2a3d5d5271/ghdl,,,Open issues,svg} and @image{GHDL-figures//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. 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//Users/gingold/devel/ghdl/doc/_build/doctrees/images/16176de4998e1a71b2f57993443202b2d81671f4/chat-on%20gitter-4db797,,,Talk to us on Gitter,svg} or open a @image{GHDL-figures//Users/gingold/devel/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{6d}@anchor{contribute reporting-bugs}@anchor{6e} @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{6f,,--synth}, before processing the design with @ref{70,,Yosys plugin}. @end itemize Please, report issues through @image{GHDL-figures//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 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/umarcor/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{71,,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{72}@anchor{contribute requesting-enhancements}@anchor{73} @section Requesting enhancements @image{GHDL-figures//Users/gingold/devel/ghdl/doc/_build/doctrees/images/89dd2439936c60b66feb51ba1c0d6a38facef2d8/1561565e8455e49d1382462c9afb48178cccd06f,,,Open new feature request at GitHub,svg?logo=github&style=flat-square&longCache=true} @image{GHDL-figures//Users/gingold/devel/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{74} @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{75,,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{76}@anchor{contribute pull-request}@anchor{75} @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//Users/gingold/devel/ghdl/doc/_build/doctrees/images/c3a4692a25333d57bb8c1ce54f97f15c6846ba63/ghdl,,,Open pull requests,svg} and @image{GHDL-figures//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{GHDL-figures//Users/gingold/devel/ghdl/doc/_build/doctrees/images/16176de4998e1a71b2f57993443202b2d81671f4/chat-on%20gitter-4db797,,,Talk to us on Gitter,svg} or open a @image{GHDL-figures//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 See section @ref{77,,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{78,,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{79} @section Related interesting projects If you have an interesting project, please send us feedback or get listed on our @ref{4f,,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{7a}@anchor{licenses copyrights-licenses}@anchor{7b}@anchor{licenses intro-copyrights}@anchor{7c} @chapter Copyrights | Licenses @itemize - @item The GHDL front-end package @code{std.textio}, and the runtime library @code{GRT} are given under @ref{7d,,GNU GPLv2}. @item The documentation is given under @ref{7e,,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{73,,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{7f}@anchor{licenses lic-gplv2}@anchor{7d} @section GNU GPLv2 GHDL is copyright © 2002 - 2023 Tristan Gingold. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but `WITHOUT ANY WARRANTY'; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License@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{80}@anchor{licenses lic-cc-by-sa}@anchor{7e} @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 `share' (copy and redistribute the material in any medium or format) and/or `adapt' (remix, transform, and build upon the material for any purpose, even commercially). We cannot revoke these freedoms as long as you follow the these terms: @itemize - @item `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 `ShareAlike': if you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original. @item `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{81}@anchor{licenses list-of-contributors}@anchor{82} @section List of Contributors @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} @headitem Contributor @footnote{ 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{ Maintainer } @tab `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{ 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//Users/gingold/devel/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{83}@anchor{quick_start/index quick-start-guide}@anchor{84}@anchor{quick_start/index using-quickstart}@anchor{85} @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{86}@anchor{quick_start/simulation/index simulation}@anchor{87}@anchor{quick_start/simulation/index using-quickstart-simulation}@anchor{68} @section Simulation As explained in @ref{4b,,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{88,,Analysis [-a]}: convert design units (@cite{VHDL} sources) to an internal representation. @item @ref{89,,Elaboration [-e]}: generate executable machine code for a target module (top-level entity). @item @ref{8a,,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{8b,,VHDL standards}). The default is @ref{8c,,--std=93c}. Use @ref{8c,,--std=08} for VHDL-2008 (albeit not fully implemented). @itemize * @item Use @ref{8d,,--ieee=synopsys} if your design depends on a non-standard implementation of the IEEE library. @item Use @ref{8e,,-fexplicit} and @ref{8f,,-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{90,,--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{91,,-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{92}@anchor{quick_start/simulation/hello/index hello-world-program}@anchor{93}@anchor{quick_start/simulation/hello/index quickstart-hello}@anchor{94} @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/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{95,,--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{88,,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{96,,-e} means @ref{89,,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{8a,,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{88,,Analysis} generates a file, @code{hello.o}, which is the object file corresponding to your @cite{VHDL} program. This is not created with @ref{55,,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{89,,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{97,,-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{97,,-r} for more informartion. @end itemize @end quotation @end cartouche @cartouche @quotation Hint @ref{96,,-e} can be bypassed with @ref{55,,mcode}, since @ref{97,,-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{98}@anchor{quick_start/simulation/heartbeat/index heartbeat-module}@anchor{99}@anchor{quick_start/simulation/heartbeat/index quickstart-heartbeat}@anchor{9a} @subsection @cite{Heartbeat} module Although @ref{94,,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{88,,analysed}, @ref{89,,elaborated} and @ref{8a,,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{9b,,Export waveforms}). You can use either @ref{9c,,--wave}, @ref{9d,,--vcd}, @ref{9e,,--vcdgz} or @ref{9f,,--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 `‘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{a0,,Full adder} and @ref{a1,,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{a2}@anchor{quick_start/simulation/adder/index full-adder-module-and-testbench}@anchor{a3}@anchor{quick_start/simulation/adder/index quickstart-adder}@anchor{a0} @subsection @cite{Full adder} module and testbench Unlike @ref{9a,,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{88,,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 `testbench' has to be run. The `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{89,,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{8a,,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{9a,,Heartbeat}. See section @ref{a4,,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{a5}@anchor{quick_start/simulation/DLXModelSuite quickstart-dlx}@anchor{a1}@anchor{quick_start/simulation/DLXModelSuite working-with-non-trivial-designs}@anchor{a6} @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{a7,,--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{a8,,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{a9,,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{8a,,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{aa,,--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{ab,,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{ac,,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{8d,,--ieee=synopsys}, @ref{8e,,-fexplicit}, etc. See section @ref{71,,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{ad}@anchor{quick_start/python/index python-interfaces}@anchor{ae}@anchor{quick_start/python/index using-quickstart-python}@anchor{af} @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{b0}@anchor{quick_start/python/index language-server}@anchor{b1} @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{b2}@anchor{quick_start/python/index ghdl-ls}@anchor{b3} @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{b4} @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{b5}@anchor{quick_start/python/index cmdoption-ghdl-ls-help}@anchor{b6} @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{b7}@anchor{quick_start/python/index cmdoption-ghdl-ls-V}@anchor{b8}@anchor{quick_start/python/index cmdoption-ghdl-ls-v}@anchor{b9} @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{ba}@anchor{quick_start/python/index cmdoption-ghdl-ls-0}@anchor{bb} @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{bc} @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{bd} @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{be}@anchor{quick_start/python/index cmdoption-ghdl-ls-i}@anchor{bf} @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{c0} @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{c1}@anchor{using/InvokingGHDL invoking-ghdl}@anchor{c2}@anchor{using/InvokingGHDL using-invoking}@anchor{69} @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{6a,,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{c3,,--PREFIX} command line option @item the @geindex GHDL_PREFIX @geindex environment variable; GHDL_PREFIX @ref{c4,,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{c5,,--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{c6} @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{c7}@anchor{using/InvokingGHDL analysis-command}@anchor{88} @subsection Analysis [@code{-a}] @geindex ghdl command line option; -a @anchor{using/InvokingGHDL cmdoption-ghdl-a}@anchor{c8} @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{c9,,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{89}@anchor{using/InvokingGHDL elaboration-e}@anchor{ca} @subsection Elaboration [@code{-e}] @geindex ghdl command line option; -e @anchor{using/InvokingGHDL cmdoption-ghdl-e}@anchor{96} @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{96,,-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{90,,--work=NAME} described in @ref{c9,,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{cb,,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{cc,,--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{8a}@anchor{using/InvokingGHDL run-r}@anchor{cd} @subsection Run [@code{-r}] @geindex ghdl command line option; -r @anchor{using/InvokingGHDL cmdoption-ghdl-r}@anchor{97} @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{89,,elaboration command}. For the second set, @code{simulation_options...}, arguments are defined in @ref{ce,,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{c8,,-a} and @ref{96,,-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{cf}@anchor{using/InvokingGHDL elaborate-and-run-elab-run}@anchor{d0} @subsection Elaborate and run [@code{--elab-run}] @geindex ghdl command line option; --elab-run @anchor{using/InvokingGHDL cmdoption-ghdl-elab-run}@anchor{d1} @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{96,,-e}, @ref{97,,-r} and @ref{ce,,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{d2} @subsection Check syntax [@code{-s}] @geindex ghdl command line option; -s @anchor{using/InvokingGHDL cmdoption-ghdl-s}@anchor{d3} @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{d4} @subsection Analyze and elaborate [@code{-c}] @geindex ghdl command line option; -c @anchor{using/InvokingGHDL cmdoption-ghdl-c}@anchor{d5} @deffn {Option} @w{-}c <[options...] file... @w{-} top_unit [arch]> @end deffn @cartouche @quotation Hint With GCC/LLVM, @ref{96,,-e} should be used, and @ref{97,,-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{c8,,-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{d6} @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{a8}@anchor{using/InvokingGHDL import-i}@anchor{d7} @subsection Import [@code{-i}] @geindex ghdl command line option; -i @anchor{using/InvokingGHDL cmdoption-ghdl-i}@anchor{d8} @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{d9,,-m}, to actually build the design. See also @ref{da,,--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{db} @subsection Elab-order [@code{--elab-order}] @geindex ghdl command line option; --elab-order @anchor{using/InvokingGHDL cmdoption-ghdl-elab-order}@anchor{da} @deffn {Option} @w{-}@w{-}elab@w{-}order <[options...] [library.]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{d8,,-i}, or for retrieving the order for some unit analyzed through third-party scripts. With the @code{--libraries} option, each line contains first the library name followed by the file name. Without the @code{--libraries} option, the list does not include information about the logical library names where each source needs to be analyzed. Hence, it is useful when all sources belong to the same @code{WORK} library. @geindex cmd make @node Make [-m],Generate Makefile [--gen-makefile],Elab-order [--elab-order],Design rebuilding commands @anchor{using/InvokingGHDL make-command}@anchor{a9}@anchor{using/InvokingGHDL make-m}@anchor{dc} @subsection Make [@code{-m}] @geindex ghdl command line option; -m @anchor{using/InvokingGHDL cmdoption-ghdl-m}@anchor{d9} @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{dd} @subsection Generate Makefile [@code{--gen-makefile}] @geindex ghdl command line option; --gen-makefile @anchor{using/InvokingGHDL cmdoption-ghdl-gen-makefile}@anchor{de} @deffn {Option} @w{-}@w{-}gen@w{-}makefile <[options...] [library.]top_unit [arch]> @end deffn This command works like the make command (see @ref{d9,,-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{df} @subsection Generate dependency file command [@code{--gen-depends}] @geindex ghdl command line option; --gen-depends @anchor{using/InvokingGHDL cmdoption-ghdl-gen-depends}@anchor{e0} @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{d9,,-m}), but instead of a full makefile only dependencies without rules are generated on the standard output. These rules can then be integrated in another Makefile. This command is not available with the mcode backend. @node Options,Warnings,Design rebuilding commands,Invoking GHDL @anchor{using/InvokingGHDL ghdl-options}@anchor{c9}@anchor{using/InvokingGHDL options}@anchor{e1} @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{90} @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{96,,-e}. @end quotation @end cartouche @end deffn @geindex ghdl command line option; --workdir @anchor{using/InvokingGHDL cmdoption-ghdl-workdir}@anchor{a7} @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{91,,-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{8c} @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{8b,,VHDL standards}. @cartouche @quotation Important This option resets the effect of @ref{e2,,-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{e3} @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{8d} @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{e4,,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{91}@anchor{using/InvokingGHDL cmdoption-ghdl-p}@anchor{e5} @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{a7,,--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{8e} @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{71,,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{e2} @deffn {Option} @w{-}frelaxed @end deffn @geindex ghdl command line option; -frelaxed-rules @anchor{using/InvokingGHDL cmdoption-ghdl-frelaxed-rules}@anchor{8f} @deffn {Option} @w{-}frelaxed@w{-}rules @cartouche @quotation Important The effects of this option are reset by @ref{8c,,--std}, so it should be placed `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 Allow a subprogram body to match its declaration when the argument lists are semantically identical but do not satisfy formal rules (e.g when a function declaration uses the keyword @code{in} for an argument but its body does not). @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{e6} @deffn {Option} @w{-}fpsl Enable parsing of PSL assertions within comments. See section @ref{e7,,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{95}@anchor{using/InvokingGHDL cmdoption-ghdl-C}@anchor{e8} @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{e9} @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{ea} @deffn {Option} @w{-}@w{-}format= Define the output format of some options, such as @ref{eb,,--pp-html} or @ref{ec,,--xref-html}. @itemize * @item By default or when @ref{ea,,--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{ea,,--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{ed} @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{ee} @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{ef,,VHDL restrictions for VITAL} for more details. @end deffn @geindex ghdl command line option; --PREFIX @anchor{using/InvokingGHDL cmdoption-ghdl-PREFIX}@anchor{c3}@anchor{using/InvokingGHDL cmdoption-ghdl-prefix}@anchor{f0} @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{f1} @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{f2} @deffn {Option} @w{-}o= All the commands that perform a link (@ref{96,,-e}, @ref{d1,,--elab-run}, @ref{f3,,--link}, @ref{d5,,-c}, @ref{d9,,-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{f4} @deffn {Option} @w{-}@w{-}time@w{-}resolution= @cartouche @quotation Attention This feature is supported with `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{c8,,-a} and @ref{97,,-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{f5} @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{f6} @deffn {Option} @w{-}@w{-}warn@w{-}library @end deffn @geindex ghdl command line option; -Wlibrary @anchor{using/InvokingGHDL cmdoption-ghdl-Wlibrary}@anchor{f7}@anchor{using/InvokingGHDL cmdoption-ghdl-wlibrary}@anchor{f8} @deffn {Option} @w{-}Wlibrary 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{f9} @deffn {Option} @w{-}@w{-}warn@w{-}default@w{-}binding @end deffn @geindex ghdl command line option; -Wdefault-binding @anchor{using/InvokingGHDL cmdoption-ghdl-Wdefault-binding}@anchor{fa}@anchor{using/InvokingGHDL cmdoption-ghdl-wdefault-binding}@anchor{fb} @deffn {Option} @w{-}Wdefault@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{8b,,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{fc} @deffn {Option} @w{-}@w{-}warn@w{-}binding @end deffn @geindex ghdl command line option; -Wbinding @anchor{using/InvokingGHDL cmdoption-ghdl-Wbinding}@anchor{fd}@anchor{using/InvokingGHDL cmdoption-ghdl-wbinding}@anchor{fe} @deffn {Option} @w{-}Wbinding 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-port @anchor{using/InvokingGHDL cmdoption-ghdl-warn-port}@anchor{ff} @deffn {Option} @w{-}@w{-}warn@w{-}port @end deffn @geindex ghdl command line option; -Wport @anchor{using/InvokingGHDL cmdoption-ghdl-Wport}@anchor{100}@anchor{using/InvokingGHDL cmdoption-ghdl-wport}@anchor{101} @deffn {Option} @w{-}Wport Emit a warning on unconnected input port without defaults (in relaxed mode). @end deffn @geindex ghdl command line option; --warn-reserved @anchor{using/InvokingGHDL cmdoption-ghdl-warn-reserved}@anchor{102} @deffn {Option} @w{-}@w{-}warn@w{-}reserved @end deffn @geindex ghdl command line option; -Wreserved @anchor{using/InvokingGHDL cmdoption-ghdl-Wreserved}@anchor{103}@anchor{using/InvokingGHDL cmdoption-ghdl-wreserved}@anchor{104} @deffn {Option} @w{-}Wreserved Emit a warning if an identifier is a reserved word in a later VHDL standard. @end deffn @geindex ghdl command line option; --warn-pragma @anchor{using/InvokingGHDL cmdoption-ghdl-warn-pragma}@anchor{105} @deffn {Option} @w{-}@w{-}warn@w{-}pragma @end deffn @geindex ghdl command line option; -Wpragma @anchor{using/InvokingGHDL cmdoption-ghdl-Wpragma}@anchor{106}@anchor{using/InvokingGHDL cmdoption-ghdl-wpragma}@anchor{107} @deffn {Option} @w{-}Wpragma Emit a warning for unknown pragma @end deffn @geindex ghdl command line option; --warn-nested-comment @anchor{using/InvokingGHDL cmdoption-ghdl-warn-nested-comment}@anchor{108} @deffn {Option} @w{-}@w{-}warn@w{-}nested@w{-}comment @end deffn @geindex ghdl command line option; -Wnested-comment @anchor{using/InvokingGHDL cmdoption-ghdl-Wnested-comment}@anchor{109}@anchor{using/InvokingGHDL cmdoption-ghdl-wnested-comment}@anchor{10a} @deffn {Option} @w{-}Wnested@w{-}comment Emit a warning if a @code{/*} appears within a block comment (vhdl 2008). @end deffn @geindex ghdl command line option; --warn-directive @anchor{using/InvokingGHDL cmdoption-ghdl-warn-directive}@anchor{10b} @deffn {Option} @w{-}@w{-}warn@w{-}directive @end deffn @geindex ghdl command line option; -Wdirective @anchor{using/InvokingGHDL cmdoption-ghdl-Wdirective}@anchor{10c}@anchor{using/InvokingGHDL cmdoption-ghdl-wdirective}@anchor{10d} @deffn {Option} @w{-}Wdirective Emit an option on tool directive @end deffn @geindex ghdl command line option; --warn-parenthesis @anchor{using/InvokingGHDL cmdoption-ghdl-warn-parenthesis}@anchor{10e} @deffn {Option} @w{-}@w{-}warn@w{-}parenthesis @end deffn @geindex ghdl command line option; -Wparenthesis @anchor{using/InvokingGHDL cmdoption-ghdl-Wparenthesis}@anchor{10f}@anchor{using/InvokingGHDL cmdoption-ghdl-wparenthesis}@anchor{110} @deffn {Option} @w{-}Wparenthesis 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{111} @deffn {Option} @w{-}@w{-}warn@w{-}vital@w{-}generic @end deffn @geindex ghdl command line option; -Wvital-generic @anchor{using/InvokingGHDL cmdoption-ghdl-Wvital-generic}@anchor{112}@anchor{using/InvokingGHDL cmdoption-ghdl-wvital-generic}@anchor{113} @deffn {Option} @w{-}Wvital@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{114} @deffn {Option} @w{-}@w{-}warn@w{-}delayed@w{-}checks @end deffn @geindex ghdl command line option; -Wdelayed-checks @anchor{using/InvokingGHDL cmdoption-ghdl-Wdelayed-checks}@anchor{115}@anchor{using/InvokingGHDL cmdoption-ghdl-wdelayed-checks}@anchor{116} @deffn {Option} @w{-}Wdelayed@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{117} @deffn {Option} @w{-}@w{-}warn@w{-}body @end deffn @geindex ghdl command line option; -Wbody @anchor{using/InvokingGHDL cmdoption-ghdl-Wbody}@anchor{118}@anchor{using/InvokingGHDL cmdoption-ghdl-wbody}@anchor{119} @deffn {Option} @w{-}Wbody 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{11a} @deffn {Option} @w{-}@w{-}warn@w{-}specs @end deffn @geindex ghdl command line option; -Wspecs @anchor{using/InvokingGHDL cmdoption-ghdl-Wspecs}@anchor{11b}@anchor{using/InvokingGHDL cmdoption-ghdl-wspecs}@anchor{11c} @deffn {Option} @w{-}Wspecs Emit a warning if an all or others specification does not apply. @end deffn @geindex ghdl command line option; --warn-universal @anchor{using/InvokingGHDL cmdoption-ghdl-warn-universal}@anchor{11d} @deffn {Option} @w{-}@w{-}warn@w{-}universal @end deffn @geindex ghdl command line option; -Wuniversal @anchor{using/InvokingGHDL cmdoption-ghdl-Wuniversal}@anchor{11e}@anchor{using/InvokingGHDL cmdoption-ghdl-wuniversal}@anchor{11f} @deffn {Option} @w{-}Wuniversal Emit a warning on incorrect use of universal values. @end deffn @geindex ghdl command line option; --warn-port-bounds @anchor{using/InvokingGHDL cmdoption-ghdl-warn-port-bounds}@anchor{120} @deffn {Option} @w{-}@w{-}warn@w{-}port@w{-}bounds @end deffn @geindex ghdl command line option; -Wport-bounds @anchor{using/InvokingGHDL cmdoption-ghdl-Wport-bounds}@anchor{121}@anchor{using/InvokingGHDL cmdoption-ghdl-wport-bounds}@anchor{122} @deffn {Option} @w{-}Wport@w{-}bounds Emit a warning on bounds mismatch between the actual and formal in a scalar port association @end deffn @geindex ghdl command line option; --warn-runtime-error @anchor{using/InvokingGHDL cmdoption-ghdl-warn-runtime-error}@anchor{123} @deffn {Option} @w{-}@w{-}warn@w{-}runtime@w{-}error @end deffn @geindex ghdl command line option; -Wruntime-error @anchor{using/InvokingGHDL cmdoption-ghdl-Wruntime-error}@anchor{124}@anchor{using/InvokingGHDL cmdoption-ghdl-wruntime-error}@anchor{125} @deffn {Option} @w{-}Wruntime@w{-}error Emit a warning in case of runtime error that is detected during analysis. @end deffn @geindex ghdl command line option; --warn-delta-cycle @anchor{using/InvokingGHDL cmdoption-ghdl-warn-delta-cycle}@anchor{126} @deffn {Option} @w{-}@w{-}warn@w{-}delta@w{-}cycle @end deffn @geindex ghdl command line option; -Wdelta-cycle @anchor{using/InvokingGHDL cmdoption-ghdl-Wdelta-cycle}@anchor{127}@anchor{using/InvokingGHDL cmdoption-ghdl-wdelta-cycle}@anchor{128} @deffn {Option} @w{-}Wdelta@w{-}cycle Emit a warning if a signal assignemnt creates a delta cycle in a postponed process. @end deffn @geindex ghdl command line option; --warn-no-wait @anchor{using/InvokingGHDL cmdoption-ghdl-warn-no-wait}@anchor{129} @deffn {Option} @w{-}@w{-}warn@w{-}no@w{-}wait @end deffn @geindex ghdl command line option; -Wno-wait @anchor{using/InvokingGHDL cmdoption-ghdl-Wno-wait}@anchor{12a}@anchor{using/InvokingGHDL cmdoption-ghdl-wno-wait}@anchor{12b} @deffn {Option} @w{-}Wno@w{-}wait Emit a warning if there is no wait statement in a non-sensitized process @end deffn @geindex ghdl command line option; --warn-shared @anchor{using/InvokingGHDL cmdoption-ghdl-warn-shared}@anchor{12c} @deffn {Option} @w{-}@w{-}warn@w{-}shared @end deffn @geindex ghdl command line option; -Wshared @anchor{using/InvokingGHDL cmdoption-ghdl-Wshared}@anchor{12d}@anchor{using/InvokingGHDL cmdoption-ghdl-wshared}@anchor{12e} @deffn {Option} @w{-}Wshared 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{12f} @deffn {Option} @w{-}@w{-}warn@w{-}hide @end deffn @geindex ghdl command line option; -Whide @anchor{using/InvokingGHDL cmdoption-ghdl-Whide}@anchor{130}@anchor{using/InvokingGHDL cmdoption-ghdl-whide}@anchor{131} @deffn {Option} @w{-}Whide 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{132} @deffn {Option} @w{-}@w{-}warn@w{-}unused @end deffn @geindex ghdl command line option; -Wunused @anchor{using/InvokingGHDL cmdoption-ghdl-Wunused}@anchor{133}@anchor{using/InvokingGHDL cmdoption-ghdl-wunused}@anchor{134} @deffn {Option} @w{-}Wunused Emit a warning when a subprogram is never used. @end deffn @geindex ghdl command line option; --warn-nowrite @anchor{using/InvokingGHDL cmdoption-ghdl-warn-nowrite}@anchor{135} @deffn {Option} @w{-}@w{-}warn@w{-}nowrite @end deffn @geindex ghdl command line option; -Wnowrite @anchor{using/InvokingGHDL cmdoption-ghdl-Wnowrite}@anchor{136}@anchor{using/InvokingGHDL cmdoption-ghdl-wnowrite}@anchor{137} @deffn {Option} @w{-}Wnowrite Emit a warning if a variable or a signal is never assigned (only for synthesis). @end deffn @geindex ghdl command line option; --warn-others @anchor{using/InvokingGHDL cmdoption-ghdl-warn-others}@anchor{138} @deffn {Option} @w{-}@w{-}warn@w{-}others @end deffn @geindex ghdl command line option; -Wothers @anchor{using/InvokingGHDL cmdoption-ghdl-Wothers}@anchor{139}@anchor{using/InvokingGHDL cmdoption-ghdl-wothers}@anchor{13a} @deffn {Option} @w{-}Wothers 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{13b} @deffn {Option} @w{-}@w{-}warn@w{-}pure @end deffn @geindex ghdl command line option; -Wpure @anchor{using/InvokingGHDL cmdoption-ghdl-Wpure}@anchor{13c}@anchor{using/InvokingGHDL cmdoption-ghdl-wpure}@anchor{13d} @deffn {Option} @w{-}Wpure 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-analyze-assert @anchor{using/InvokingGHDL cmdoption-ghdl-warn-analyze-assert}@anchor{13e} @deffn {Option} @w{-}@w{-}warn@w{-}analyze@w{-}assert @end deffn @geindex ghdl command line option; -Wanalyze-assert @anchor{using/InvokingGHDL cmdoption-ghdl-Wanalyze-assert}@anchor{13f}@anchor{using/InvokingGHDL cmdoption-ghdl-wanalyze-assert}@anchor{140} @deffn {Option} @w{-}Wanalyze@w{-}assert Emit a warning for assertions that are statically evaluated during analysis. @end deffn @geindex ghdl command line option; --warn-attribute @anchor{using/InvokingGHDL cmdoption-ghdl-warn-attribute}@anchor{141} @deffn {Option} @w{-}@w{-}warn@w{-}attribute @end deffn @geindex ghdl command line option; -Wattribute @anchor{using/InvokingGHDL cmdoption-ghdl-Wattribute}@anchor{142}@anchor{using/InvokingGHDL cmdoption-ghdl-wattribute}@anchor{143} @deffn {Option} @w{-}Wattribute Emit a warning on incorrect use of attributes. @end deffn @geindex ghdl command line option; --warn-useless @anchor{using/InvokingGHDL cmdoption-ghdl-warn-useless}@anchor{144} @deffn {Option} @w{-}@w{-}warn@w{-}useless @end deffn @geindex ghdl command line option; -Wuseless @anchor{using/InvokingGHDL cmdoption-ghdl-Wuseless}@anchor{145}@anchor{using/InvokingGHDL cmdoption-ghdl-wuseless}@anchor{146} @deffn {Option} @w{-}Wuseless Emit a warning on useless code (like conditions that are always false or true, assertions that cannot be triggered). @end deffn @geindex ghdl command line option; --warn-no-assoc @anchor{using/InvokingGHDL cmdoption-ghdl-warn-no-assoc}@anchor{147} @deffn {Option} @w{-}@w{-}warn@w{-}no@w{-}assoc @end deffn @geindex ghdl command line option; -Wno-assoc @anchor{using/InvokingGHDL cmdoption-ghdl-Wno-assoc}@anchor{148}@anchor{using/InvokingGHDL cmdoption-ghdl-wno-assoc}@anchor{149} @deffn {Option} @w{-}Wno@w{-}assoc Emit a warning on missing association for a port association. Open associations are required. @end deffn @geindex ghdl command line option; --warn-static @anchor{using/InvokingGHDL cmdoption-ghdl-warn-static}@anchor{14a} @deffn {Option} @w{-}@w{-}warn@w{-}static @end deffn @geindex ghdl command line option; -Wstatic @anchor{using/InvokingGHDL cmdoption-ghdl-Wstatic}@anchor{14b}@anchor{using/InvokingGHDL cmdoption-ghdl-wstatic}@anchor{14c} @deffn {Option} @w{-}Wstatic 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{14d} @deffn {Option} @w{-}@w{-}warn@w{-}error @end deffn @geindex ghdl command line option; --warn-error @anchor{using/InvokingGHDL cmdoption-ghdl-0}@anchor{14e} @deffn {Option} @w{-}@w{-}warn@w{-}error= @end deffn @geindex ghdl command line option; -Werror @anchor{using/InvokingGHDL cmdoption-ghdl-Werror}@anchor{14f}@anchor{using/InvokingGHDL cmdoption-ghdl-werror}@anchor{150} @deffn {Option} @w{-}Werror @end deffn @geindex ghdl command line option; -Werror @anchor{using/InvokingGHDL cmdoption-ghdl-1}@anchor{151} @deffn {Option} @w{-}Werror= @end deffn @geindex ghdl command line option; -Wno-error @anchor{using/InvokingGHDL cmdoption-ghdl-Wno-error}@anchor{152}@anchor{using/InvokingGHDL cmdoption-ghdl-wno-error}@anchor{153} @deffn {Option} @w{-}Wno@w{-}error= When this option is set, warnings are considered as errors. With the parameter, only the specific warning is turned into an error. @end deffn @node Diagnostics Control,Library commands,Warnings,Invoking GHDL @anchor{using/InvokingGHDL diagnostics-control}@anchor{154} @section Diagnostics Control @geindex ghdl command line option; -fcolor-diagnostics @anchor{using/InvokingGHDL cmdoption-ghdl-fcolor-diagnostics}@anchor{155} @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{156} @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. For compatibility with other tools, when colors are enabled the diagnostic level is always displayed. When colors are not enabled, level @code{error} is not displayed. @end deffn @geindex ghdl command line option; -fdiagnostics-show-option @anchor{using/InvokingGHDL cmdoption-ghdl-fdiagnostics-show-option}@anchor{157} @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{158} @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{159} @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{15a} @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{15b} @section Library commands @anchor{using/InvokingGHDL create-a-library}@anchor{15c} @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{a7,,--workdir} option: @code{ghdl -a --work=my_custom_lib --workdir=my_custom_libdir my_custom_lib_srcdir/my_file.vhdl}. See also the @ref{91,,-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 @anchor{using/InvokingGHDL cmdoption-ghdl-dir}@anchor{15d} @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{90,,--work}, @ref{a7,,--workdir} and @ref{8c,,--std}. @geindex cmd library clean @anchor{using/InvokingGHDL clean-command}@anchor{ab} @geindex ghdl command line option; --clean @anchor{using/InvokingGHDL cmdoption-ghdl-clean}@anchor{15e} @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{ac} @geindex ghdl command line option; --remove @anchor{using/InvokingGHDL cmdoption-ghdl-remove}@anchor{15f} @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 @anchor{using/InvokingGHDL cmdoption-ghdl-copy}@anchor{160} @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{161}@anchor{using/InvokingGHDL vpi-vhpi-build-commands}@anchor{162} @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{163} @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{164} @geindex cmd VPI link @geindex ghdl command line option; --vpi-link @anchor{using/InvokingGHDL cmdoption-ghdl-vpi-link}@anchor{165} @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{166} @geindex cmd VPI cflags @geindex ghdl command line option; --vpi-cflags @anchor{using/InvokingGHDL cmdoption-ghdl-vpi-cflags}@anchor{167} @deffn {Option} @w{-}@w{-}vpi@w{-}cflags @end deffn Display flags added by @ref{163,,--vpi-compile}. @geindex cmd VPI ldflags @geindex ghdl command line option; --vpi-ldflags @anchor{using/InvokingGHDL cmdoption-ghdl-vpi-ldflags}@anchor{168} @deffn {Option} @w{-}@w{-}vpi@w{-}ldflags @end deffn Display flags added by @ref{165,,--vpi-link}. @geindex cmd VPI include dir @geindex ghdl command line option; --vpi-include-dir @anchor{using/InvokingGHDL cmdoption-ghdl-vpi-include-dir}@anchor{169} @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{16a} @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{16b} @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{16c}@anchor{using/InvokingGHDL ieee-library-pitfalls}@anchor{71} @section IEEE library pitfalls When you use options @ref{8d,,--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 `-fexplicit' option (see @ref{c9,,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{16d}@anchor{using/Simulation simulation-runtime}@anchor{16e}@anchor{using/Simulation using-simulation}@anchor{ce} @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{16f}@anchor{using/Simulation simulation-options}@anchor{a4} @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{170,,Debugging}. @cartouche @quotation Hint Note that these arguments are represented as @code{simulation_options...} in this documentation. For analysis/elaboration options, see @ref{69,,Invoking GHDL}. @end quotation @end cartouche @geindex ghdl command line option; -gGENERIC @anchor{using/Simulation cmdoption-ghdl-gGENERIC}@anchor{171}@anchor{using/Simulation cmdoption-ghdl-ggeneric}@anchor{172} @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{96,,-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{aa} @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{aa,,--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{173} @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{174} @deffn {Option} @w{-}@w{-}ieee@w{-}asserts= @end deffn @geindex ghdl command line option; --asserts @anchor{using/Simulation cmdoption-ghdl-asserts}@anchor{175} @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 @anchor{using/Simulation cmdoption-ghdl-stop-time}@anchor{176} @deffn {Option} @w{-}@w{-}stop@w{-}time=