\input texinfo @c -*-texinfo-*- @c %**start of header @setfilename GHDL.info @documentencoding UTF-8 @ifinfo @*Generated by Sphinx 3.3.1.@* @end ifinfo @settitle GHDL Documentation @defindex ge @paragraphindent 0 @exampleindent 4 @finalout @dircategory Miscellaneous @direntry * GHDL: (GHDL.info). VHDL simulator. @end direntry @definfoenclose strong,`,' @definfoenclose emph,`,' @c %**end of header @copying @quotation GHDL 2.0.0-dev, Jun 26, 2021 Tristan Gingold and contributors Copyright @copyright{} 2002-2021, 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{3c} @c # Load pre-defined aliases and graphical characters like © from docutils @c # is used to denote the special path @c # \Lib\site-packages\docutils\parsers\rst\include @c This data file has been placed in the public domain. @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>. * 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 only): PSL annotations VHDL-2008 only. * PSL vunit files (VHDL-2008 / Synthesis only): PSL vunit files VHDL-2008 / 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.Common: pyGHDL dom Common. * pyGHDL.dom.DesignUnit: pyGHDL dom DesignUnit. * pyGHDL.dom.Expression: pyGHDL dom Expression. * pyGHDL.dom.InterfaceItem: pyGHDL dom InterfaceItem. * pyGHDL.dom.Literal: pyGHDL dom Literal. * pyGHDL.dom.Misc: pyGHDL dom Misc. * pyGHDL.dom.NonStandard: pyGHDL dom NonStandard. * pyGHDL.dom.Object: pyGHDL dom Object. * pyGHDL.dom.Range: pyGHDL dom Range. * pyGHDL.dom.Subprogram: pyGHDL dom Subprogram. * pyGHDL.dom.Symbol: pyGHDL dom Symbol. * pyGHDL.dom.Type: pyGHDL dom Type. * pyGHDL.dom._Translate: pyGHDL dom _Translate. * pyGHDL.dom._Utils: pyGHDL dom _Utils. * pyGHDL.dom.formatting: pyGHDL dom formatting. pyGHDL.dom.formatting * pyGHDL.dom.formatting.prettyprint: pyGHDL dom formatting prettyprint. pyGHDL.libghdl * pyGHDL.libghdl._decorator: pyGHDL libghdl _decorator. * pyGHDL.libghdl._types: pyGHDL libghdl _types. * pyGHDL.libghdl.errorout: pyGHDL libghdl errorout. * pyGHDL.libghdl.errorout_console: pyGHDL libghdl errorout_console. * pyGHDL.libghdl.errorout_memory: pyGHDL libghdl errorout_memory. * pyGHDL.libghdl.files_map: pyGHDL libghdl files_map. * pyGHDL.libghdl.files_map_editor: pyGHDL libghdl files_map_editor. * pyGHDL.libghdl.flags: pyGHDL libghdl flags. * pyGHDL.libghdl.libraries: pyGHDL libghdl libraries. * pyGHDL.libghdl.name_table: pyGHDL libghdl name_table. * pyGHDL.libghdl.std_names: pyGHDL libghdl std_names. * pyGHDL.libghdl.utils: pyGHDL libghdl utils. * pyGHDL.libghdl.version: pyGHDL libghdl version. * pyGHDL.libghdl.vhdl: pyGHDL libghdl vhdl. pyGHDL.libghdl.vhdl * pyGHDL.libghdl.vhdl.canon: pyGHDL libghdl vhdl canon. * pyGHDL.libghdl.vhdl.elocations: pyGHDL libghdl vhdl elocations. * pyGHDL.libghdl.vhdl.flists: pyGHDL libghdl vhdl flists. * pyGHDL.libghdl.vhdl.formatters: pyGHDL libghdl vhdl formatters. * pyGHDL.libghdl.vhdl.ieee: pyGHDL libghdl vhdl ieee. * pyGHDL.libghdl.vhdl.lists: pyGHDL libghdl vhdl lists. * pyGHDL.libghdl.vhdl.nodes: pyGHDL libghdl vhdl nodes. * pyGHDL.libghdl.vhdl.nodes_meta: pyGHDL libghdl vhdl nodes_meta. * pyGHDL.libghdl.vhdl.nodes_utils: pyGHDL libghdl vhdl nodes_utils. * pyGHDL.libghdl.vhdl.parse: pyGHDL libghdl vhdl parse. * pyGHDL.libghdl.vhdl.sem: pyGHDL libghdl vhdl sem. * pyGHDL.libghdl.vhdl.sem_lib: pyGHDL libghdl vhdl sem_lib. * pyGHDL.libghdl.vhdl.std_package: pyGHDL libghdl vhdl std_package. * pyGHDL.libghdl.vhdl.tokens: pyGHDL libghdl vhdl tokens. pyGHDL.lsp * pyGHDL.lsp.document: pyGHDL lsp document. * pyGHDL.lsp.lsp: pyGHDL lsp lsp. * pyGHDL.lsp.lsptools: pyGHDL lsp lsptools. * pyGHDL.lsp.references: pyGHDL lsp references. * pyGHDL.lsp.symbols: pyGHDL lsp symbols. * pyGHDL.lsp.version: pyGHDL lsp version. * pyGHDL.lsp.vhdl_ls: pyGHDL lsp vhdl_ls. * pyGHDL.lsp.workspace: pyGHDL lsp workspace. GHDL Waveform (GHW) * libghw:: * ghwdump:: 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{3d}@anchor{about about}@anchor{3e}@anchor{about ghdl}@anchor
/*
    ChibiOS - Copyright (C) 2006..2016 Giovanni Di Sirio

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
*/

/**
 * @file    hal_gpt.c
 * @brief   GPT Driver code.
 *
 * @addtogroup GPT
 * @{
 */

#include "hal.h"

#if (HAL_USE_GPT == TRUE) || defined(__DOXYGEN__)

/*===========================================================================*/
/* Driver local definitions.                                                 */
/*===========================================================================*/

/*===========================================================================*/
/* Driver exported variables.                                                */
/*===========================================================================*/

/*===========================================================================*/
/* Driver local variables and types.                                         */
/*===========================================================================*/

/*===========================================================================*/
/* Driver local functions.                                                   */
/*===========================================================================*/

/*===========================================================================*/
/* Driver exported functions.                                                */
/*===========================================================================*/

/**
 * @brief   GPT Driver initialization.
 * @note    This function is implicitly invoked by @p halInit(), there is
 *          no need to explicitly initialize the driver.
 *
 * @init
 */
void gptInit(void) {

  gpt_lld_init();
}

/**
 * @brief   Initializes the standard part of a @p GPTDriver structure.
 *
 * @param[out] gptp     pointer to the @p GPTDriver object
 *
 * @init
 */
void gptObjectInit(GPTDriver *gptp) {

  gptp->state  = GPT_STOP;
  gptp->config = NULL;
}

/**
 * @brief   Configures and activates the GPT peripheral.
 *
 * @param[in] gptp      pointer to the @p GPTDriver object
 * @param[in] config    pointer to the @p GPTConfig object
 *
 * @api
 */
void gptStart(GPTDriver *gptp, const GPTConfig *config) {

  osalDbgCheck((gptp != NULL) && (config != NULL));

  osalSysLock();
  osalDbgAssert((gptp->state == GPT_STOP) || (gptp->state == GPT_READY),
              "invalid state");
  gptp->config = config;
  gpt_lld_start(gptp);
  gptp->state = GPT_READY;
  osalSysUnlock();
}

/**
 * @brief   Deactivates the GPT peripheral.
 *
 * @param[in] gptp      pointer to the @p GPTDriver object
 *
 * @api
 */
void gptStop(GPTDriver *gptp) {

  osalDbgCheck(gptp != NULL);

  osalSysLock();

  osalDbgAssert((gptp->state == GPT_STOP) || (gptp->state == GPT_READY),
                "invalid state");

  gpt_lld_stop(gptp);
  gptp->config = NULL;
  gptp->state  = GPT_STOP;

  osalSysUnlock();
}

/**
 * @brief   Changes the interval of GPT peripheral.
 * @details This function changes the interval of a running GPT unit.
 * @pre     The GPT unit must be running in continuous mode.
 * @post    The GPT unit interval is changed to the new value.
 *
 * @param[in] gptp      pointer to a @p GPTDriver object
 * @param[in] interval  new cycle time in timer ticks
 *
 * @api
 */
void gptChangeInterval(GPTDriver *gptp, gptcnt_t interval) {

  osalDbgCheck(gptp != NULL);

  osalSysLock();
  osalDbgAssert(gptp->state == GPT_CONTINUOUS,
                "invalid state");
  gptChangeIntervalI(gptp, interval);
  osalSysUnlock();
}

/**
 * @brief   Starts the timer in continuous mode.
 *
 * @param[in] gptp      pointer to the @p GPTDriver object
 * @param[in] interval  period in ticks
 *
 * @api
 */
void gptStartContinuous(GPTDriver *gptp, gptcnt_t interval) {

  osalSysLock();
  gptStartContinuousI(gptp, interval);
  osalSysUnlock();
}

/**
 * @brief   Starts the timer in continuous mode.
 *
 * @param[in] gptp      pointer to the @p GPTDriver object
 * @param[in] interval  period in ticks
 *
 * @iclass
 */
void gptStartContinuousI(GPTDriver *gptp, gptcnt_t interval) {

  osalDbgCheckClassI();
  osalDbgCheck(gptp != NULL);
  osalDbgAssert(gptp->state == GPT_READY,
                "invalid state");

  gptp->state = GPT_CONTINUOUS;
  gpt_lld_start_timer(gptp, interval);
}

/**
 * @brief   Starts the timer in one shot mode.
 *
 * @param[in] gptp      pointer to the @p GPTDriver object
 * @param[in] interval  time interval in ticks
 *
 * @api
 */
void gptStartOneShot(GPTDriver *gptp, gptcnt_t interval) {

  osalSysLock();
  gptStartOneShotI(gptp, interval);
  osalSysUnlock();
}

/**
 * @brief   Starts the timer in one shot mode.
 *
 * @param[in] gptp      pointer to the @p GPTDriver object
 * @param[in] interval  time interval in ticks
 *
 * @api
 */
void gptStartOneShotI(GPTDriver *gptp, gptcnt_t interval) {

  osalDbgCheckClassI();
  osalDbgCheck(gptp != NULL);
  osalDbgCheck(gptp->config->callback != NULL);
  osalDbgAssert(gptp->state == GPT_READY,
                "invalid state");

  gptp->state = GPT_ONESHOT;
  gpt_lld_start_timer(gptp, interval);
}

/**
 * @brief   Stops the timer.
 *
 * @param[in] gptp      pointer to the @p GPTDriver object
 *
 * @api
 */
void gptStopTimer(GPTDriver *gptp) {

  osalSysLock();
  gptStopTimerI(gptp);
  osalSysUnlock();
}

/**
 * @brief   Stops the timer.
 *
 * @param[in] gptp      pointer to the @p GPTDriver object
 *
 * @api
 */
void gptStopTimerI(GPTDriver *gptp) {

  osalDbgCheckClassI();
  osalDbgCheck(gptp != NULL);
  osalDbgAssert((gptp->state == GPT_READY) || (gptp->state == GPT_CONTINUOUS) ||
                (gptp->state == GPT_ONESHOT),
                "invalid state");

  gptp->state = GPT_READY;
  gpt_lld_stop_timer(gptp);
}

/**
 * @brief   Starts the timer in one shot mode and waits for completion.
 * @details This function specifically polls the timer waiting for completion
 *          in order to not have extra delays caused by interrupt servicing,
 *          this function is only recommended for short delays.
 * @note    The configured callback is not invoked when using this function.
 *
 * @param[in] gptp      pointer to the @p GPTDriver object
 * @param[in] interval  time interval in ticks
 *
 * @api
 */
void gptPolledDelay(GPTDriver *gptp, gptcnt_t interval) {

  osalDbgAssert(gptp->state == GPT_READY,
                "invalid state");

  gptp->state = GPT_ONESHOT;
  gpt_lld_polled_delay(gptp, interval);
  gptp->state = GPT_READY;
}

#endif /* HAL_USE_GPT == TRUE */

/** @} */
generated by cgit v1.2.3 (git 2.25.1) at 2025-10-07 15:59:06 +0000
Contributing,Copyrights | Licenses,Getting | Installing,Top @anchor{contribute doc}@anchor{5b}@anchor{contribute contributing}@anchor{5c}@anchor{contribute intro-contributing}@anchor{5d} @chapter Contributing As in many other free and open source projects, there are many areas requiring different skills where contributions to GHDL are welcome. The first step might be to use GHDL and explore its possibilities in your own project. If you are new to VHDL, see the @ref{5e,,Simulation} for an introduction. Furthermore, we encourage you to read @ref{5f,,Invoking GHDL}, where the most commonly used options are explained. You can also check the complete @ref{60,,Additional Command Reference}. If you are more familiar with GHDL, you might start asking yourself how it works internally. If so, you might find @ref{61,,Implementation of VHDL} and @ref{62,,Implementation of VITAL} interesting. While using GHDL, you might find flaws, such as bugs, missing features, typos in the documentation, or topics which still are not covered. In order to improve GHDL, we welcome bug reports, suggestions, and contributions for any aspect of GHDL. Whether it’s a bug or an enhancement, have a look at the @image{GHDL-figures/D:/data-dev/umarcor/ghdl/ghdl/doc/_build/doctrees/images/75d23ce669cbc7993d4d057361ad0c2a3d5d5271/ghdl,,,Open issues,svg} and @image{GHDL-figures/D:/data-dev/umarcor/ghdl/ghdl/doc/_build/doctrees/images/e1c1423669df5839910ed47f754b67708d362d8b/ghdl,,,Closed issues,svg} to see if someone already told us about it. You might find a solution there. Ideas for future work, enhancements, documentation, and internship programs are shown in the GitHub wiki@footnote{https://github.com/ghdl/ghdl/wiki}. If you found no information on your topic, please, report so that we are aware! You can reach us through various ways: @image{GHDL-figures/D:/data-dev/umarcor/ghdl/ghdl/doc/_build/doctrees/images/16176de4998e1a71b2f57993443202b2d81671f4/chat-on%20gitter-4db797,,,Talk to us on Gitter,svg} or open a @image{GHDL-figures/D:/data-dev/umarcor/ghdl/ghdl/doc/_build/doctrees/images/dfb2204df41464917807ba7d4295bf10566f1193/new-issue-yellowgreen,,,Open new issue at GitHub,svg} . @cartouche @quotation Hint @itemize * @item Since the development of GHDL started in 2002, multiple platforms have been used as a support for both distribution and getting feedback. However, the development is now centralized in github.com/ghdl@footnote{https://github.com/ghdl}. @item How To Ask Questions The Smart Way@footnote{www.catb.org/~esr/faqs/smart-questions.html} @end itemize @end quotation @end cartouche @menu * Reporting bugs:: * Requesting enhancements:: * Improving the documentation:: * Fork@comma{} modify and pull-request: Fork modify and pull-request. * Related interesting projects:: @end menu @node Reporting bugs,Requesting enhancements,,Contributing @anchor{contribute id1}@anchor{63}@anchor{contribute reporting-bugs}@anchor{64} @section Reporting bugs @itemize * @item If the compiler crashes, this is a bug. Reliable tools never crash. @item If the compiler emits an error message for a perfectly valid input or does not emit an error message for an invalid input, this may be a bug. @item If the executable created from your VHDL sources crashes, this may be a bug at runtime or the code itself may be wrong. Since VHDL has a notion of pointers, an erroneous VHDL program (using invalid pointers for example) may crash. @item If a compiler message is not clear enough, please tell us. The error messages can be improved, but we do not have enough experience with them. @item It is suggested to test synthesis features with @ref{65,,--synth}, before processing the design with @ref{66,,Yosys plugin}. @end itemize Please, report issues through @image{GHDL-figures/D:/data-dev/umarcor/ghdl/ghdl/doc/_build/doctrees/images/bac95e4b3b8c2d7bfbc31a7ce9892272a524ef30/new-bug--report-yellowgreen,,,Open new bug report at GitHub,svg} , as this allows us to categorize issues into groups and to assign developers to them. You can track the state and see how it’s getting solved. @cartouche @quotation Important As suggested in the bug report template, please elaborate a @cite{Minimal (non) Working Example} (MWE@footnote{https://en.wikipedia.org/wiki/Minimal_Working_Example}) prior to sending the report, so that the possible bug source is isolated. Should it fulfill the format requirements of issue-runner@footnote{https://github.com/eine/issue-runner}, you would be able to test your bug with the latest GHDL version. Please do so in order to ensure that the bug is not solved already. Also, please include enough information in the bug report, for the maintainers to reproduce the problem. The template includes: @itemize * @item Operating system and version of GHDL (you can get it with @code{ghdl version} and @code{ghdl hash}). @item Whether you have built GHDL from sources (provide short SHA of the used commit) or used the binary distribution (note which release/tag); if you cannot compile, please report which compiler you are using and the version. @item Content of the input files which comprise the MWE. @item Description of the problem: @itemize * @item Comment explaining whether the MWE should compile or not; if yes, whether it should run until the assertion. @item What you expect to happen and what you actually get. If you know the LRM well enough, please specify which paragraph might not be implemented well. @item Samples of any log. @item Anything else that you think would be helpful. @end itemize @end itemize @end quotation @end cartouche @cartouche @quotation Note If you don’t know the LRM, be aware that an issue claimed as a bug report may be rejected because there is no bug according to it. GHDL aims at implementing VHDL as defined in IEEE 1076@footnote{http://ieeexplore.ieee.org/document/4772740/}. However, some other tools allow constructs which do not fully follow the standard revisions. Therefore, comparisons with other VHDL variants is not a solid argument. Some of them are supported by GHDL (see @ref{67,,IEEE library pitfalls}), but any such enhancement will have very low priority. @end quotation @end cartouche @node Requesting enhancements,Improving the documentation,Reporting bugs,Contributing @anchor{contribute id2}@anchor{68}@anchor{contribute requesting-enhancements}@anchor{69} @section Requesting enhancements @image{GHDL-figures/D:/data-dev/umarcor/ghdl/ghdl/doc/_build/doctrees/images/16176de4998e1a71b2f57993443202b2d81671f4/chat-on%20gitter-4db797,,,Talk to us on Gitter,svg} All enhancements and feature requests are welcome. Please open a new issue@footnote{https://github.com/ghdl/ghdl/issues/new} to report any, so you can track the status and implementation. Depending on the complexity of the request, you may want to chat on Gitter@footnote{https://gitter.im/ghdl/ghdl1}, for polishing it before opening an issue. @node Improving the documentation,Fork modify and pull-request,Requesting enhancements,Contributing @anchor{contribute improving-the-documentation}@anchor{6a} @section Improving the documentation If you found a mistake in the documentation, please send a comment. If you didn’t understand some parts of this manual, please tell us. English is not our mother tongue, so this documentation may not be well-written. Likewise, rewriting part of the documentation or missing content (such as examples) is a good way to improve it. Since it is built automatically from @cite{reStructuredText}, you can fork, modify and push. The documentation will be shown in the GitHub Pages site of your fork: @code{https://USERNAME.github.io/ghdl}. When you are done, request the maintainers to pull your copy. See @ref{6b,,Fork@comma{} modify and pull-request}. @node Fork modify and pull-request,Related interesting projects,Improving the documentation,Contributing @anchor{contribute fork-modify-and-pull-request}@anchor{6c}@anchor{contribute pull-request}@anchor{6b} @section Fork, modify and pull-request @cartouche @quotation Tip @itemize * @item Before starting any modification, you might want to have a look at @image{GHDL-figures/D:/data-dev/umarcor/ghdl/ghdl/doc/_build/doctrees/images/c3a4692a25333d57bb8c1ce54f97f15c6846ba63/ghdl,,,Open pull requests,svg} and @image{GHDL-figures/D:/data-dev/umarcor/ghdl/ghdl/doc/_build/doctrees/images/6497f995f9ef9e87d1fe97a236cebe38959dc915/ghdl,,,Closed pull requests,svg} , to check which other contributions are being made or have been made. If you observe that the modifications you are about to start might conflict with any other, please @image{GHDL-figures/D:/data-dev/umarcor/ghdl/ghdl/doc/_build/doctrees/images/16176de4998e1a71b2f57993443202b2d81671f4/chat-on%20gitter-4db797,,,Talk to us on Gitter,svg} or open a to coordinate. @item See section @ref{6d,,Directory structure} to faster find the location of the sources you need to modify, and/or to know where to place new ones. @end itemize @end quotation @end cartouche Contributing source code/documentation is done through git@footnote{https://git-scm.com/}. Although we don’t provide direct write access to our repositories, the project is hosted at GitHub, which follows a fork, edit and pull-request flow@footnote{https://help.github.com/articles/github-flow/} . That is: @enumerate @item Make a copy (fork@footnote{https://help.github.com/articles/fork-a-repo/}) of the project. @item Do the changes you wish (edit, add, rename, move and/or delete). @item When you think that the changes are ready to be merged, notify the maintainers by opening a Pull Request@footnote{https://help.github.com/articles/creating-a-pull-request/} (PR). @item The maintainers will review the proposed changes and will reply in the corresponding thread if any further modification is required. If so, you can keep adding commits to the same branch, and the PR will be automatically updated. @item Last, maintainers will merge your branch. You will be notified, the PR will be closed, and you’ll be allowed to delete the branch, if you want. @end enumerate @cartouche @quotation Tip @itemize * @item It is recommended to read A successful Git branching model@footnote{http://nvie.com/posts/a-successful-git-branching-model/} for a reference on how maintainers expect to handle multiple branches. However, our actual model is not as exhaustive as explained there. @item Some commit messages can automatically close@footnote{https://help.github.com/articles/closing-issues-via-commit-messages/} issues. This is a very useful feature, which you are not required to use. However beware that using @cite{fix} anywhere in the commit message can have side effects. If you closed any issue unexpectedly, just reply to it (even if it’s closed) so that maintainers can check it. @item It is recommended to read @ref{6e,,Coding Style} before contributing modifications to Ada sources. @end itemize @end quotation @end cartouche @node Related interesting projects,,Fork modify and pull-request,Contributing @anchor{contribute related-interesting-projects}@anchor{6f} @section Related interesting projects If you have an interesting project, please send us feedback or get listed on our @ref{45,,Who uses GHDL?} page. @c # Load pre-defined aliases and graphical characters like © from docutils @c # is used to denote the special path @c # \Lib\site-packages\docutils\parsers\rst\include @c This data file has been placed in the public domain. @c Derived from the Unicode character mappings available from @c . @c Processed by unicode2rstsubs.py, part of Docutils: @c . @c This data file has been placed in the public domain. @c Derived from the Unicode character mappings available from @c . @c Processed by unicode2rstsubs.py, part of Docutils: @c . @c # define a hard line break for HTML @node Copyrights | Licenses,Quick Start Guide,Contributing,Top @anchor{licenses doc}@anchor{70}@anchor{licenses copyrights-licenses}@anchor{71}@anchor{licenses intro-copyrights}@anchor{72} @chapter Copyrights | Licenses @itemize - @item The GHDL front-end package @code{std.textio}, and the runtime library @code{GRT} are given under @ref{73,,GNU GPLv2}. @item The documentation is given under @ref{74,,CC-BY-SA}. @end itemize @cartouche @quotation Warning As a consequence of the runtime copyright, you are not allowed to distribute an executable produced by GHDL without allowing access to the VHDL sources. Please, send a comment (@ref{69,,Requesting enhancements}) if you don’t like this policy. @end quotation @end cartouche The following packages are copyrighted by third parties (see corresponding sources for more information): @itemize * @item These from library @code{ieee} are copyrighted by Institute of Electrical and Electronics Engineers (IEEE)@footnote{https://www.ieee.org}: @itemize * @item Since December 2019, standard and IEEE libraries are distributed under Apache 2.0 and available at opensource.ieee.org/vasg/Packages@footnote{https://opensource.ieee.org/vasg/Packages}. GHDL includes backports of those libraries for earlier revisions of the standard. @item @code{VITAL_Primitives}, @code{VITAL_Timing} and @code{VITAL_Memory} are not include in the open source distribution of IEEE (see IEEE 1076.4@footnote{http://ieeexplore.ieee.org/document/954750/}). @end itemize @item The following sources may be used and distributed without restriction, provided that the copyright statements are not removed from the files and that any derivative work contains the copyright notice. @itemize * @item @code{synopsys} directory: @code{std_logic_arith}, @code{std_logic_signed}, @code{std_logic_unsigned} and @code{std_logic_textio} are copyrighted by Synopsys@comma{} Inc.@footnote{https://www.synopsys.com/} @item @code{mentor} directory: @code{std_logic_arith} is copyrighted by Mentor Graphics@footnote{https://www.mentor.com}. @end itemize @end itemize @menu * GNU GPLv2:: * CC-BY-SA:: * List of Contributors:: @end menu @node GNU GPLv2,CC-BY-SA,,Copyrights | Licenses @anchor{licenses gnu-gplv2}@anchor{75}@anchor{licenses lic-gplv2}@anchor{73} @section GNU GPLv2 GHDL is copyright © 2002 - 2021 Tristan Gingold. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but @strong{WITHOUT ANY WARRANTY}; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License@footnote{https://www.gnu.org/licenses/old-licenses/gpl-2.0.html} for more details. @node CC-BY-SA,List of Contributors,GNU GPLv2,Copyrights | Licenses @anchor{licenses cc-by-sa}@anchor{76}@anchor{licenses lic-cc-by-sa}@anchor{74} @section CC-BY-SA This is a free documentation; you can redistribute it and/or modify it under the terms of the Creative Commons Attribution-ShareAlike 4.0@footnote{https://creativecommons.org/licenses/by-sa/4.0/} license. You are free to @strong{share} (copy and redistribute the material in any medium or format) and/or @strong{adapt} (remix, transform, and build upon the material for any purpose, even commercially). We cannot revoke these freedoms as long as you follow the these terms: @itemize - @item @strong{Attribution}: you must provide the name of the creator and attribution parties (more info@footnote{https://wiki.creativecommons.org/wiki/License_Versions#Detailed_attribution_comparison_chart}), a copyright notice, a license notice, a disclaimer notice, a link to the material, a link to the license and indicate if changes were made (see marking guide@footnote{https://wiki.creativecommons.org/wiki/Best_practices_for_attribution#This_is_a_good_attribution_for_material_you_modified_slightly} and more info@footnote{https://wiki.creativecommons.org/wiki/License_Versions#Modifications_and_adaptations_must_be_marked_as_such}). You may do so in any reasonable manner, but not in any way that suggests we endorse you or your use. @item @strong{ShareAlike}: if you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original. @item @strong{No additional restrictions}: you may not apply legal terms or technological measures that legally restrict others from doing anything the license permits. @end itemize See CC-BY-SA-4.0 Legal Code@footnote{https://creativecommons.org/licenses/by-sa/4.0/legalcode.txt} for more details. @node List of Contributors,,CC-BY-SA,Copyrights | Licenses @anchor{licenses lic-contributors}@anchor{77}@anchor{licenses list-of-contributors}@anchor{78} @section List of Contributors @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} @headitem Contributor @footnote{@w{(1)} In alphabetical order } @tab Role @item Baggett, Jonas @tab signal selection @item Bertram, Felix @tab VPI interface @item Davis, Brian @tab Windows Mcode builds @item Drummond, Brian @tab GCC 4.8.2 update, OSVVM port, some bugfixes @item Gingold, Tristan @footnote{@w{(2)} Maintainer } @tab @strong{Sole author of GHDL as a whole} @item Jensen, Adam @tab FreeBSD builds @item Koch, Markus @tab vendor pre-compile script for Lattice (GNU/Linux) @item Koontz, David @tab Mac OSX builds, LRM compliance work, bugfix analyses @item Lehmann, Patrick @tab Windows compile scripts, vendor library pre-compile scripts (win+lin), building in MinGW, AppVeyor integration. @item Meißner, Torsten @tab Property Specification Language (PSL): docs, tests, synthesis support @item Martinez-Corral, Unai @footnote{@w{(2)} Maintainer } @tab ghdl-cosim, setup-ghdl-ci, docs, docker/CI, MSYS2 packaging, building/testing on ARM, termux builds @item van Rantwijk, Joris @tab Debian packaging @end multitable Only those who made substantial contributions are shown in the table above, but many others contributed with minor patches. You can find a list at @image{GHDL-figures/D:/data-dev/umarcor/ghdl/ghdl/doc/_build/doctrees/images/6f8cd1a5e6840820b92af0cbdd95adc63019ebd5/ghdl,,,Contributors,svg} With apologies to anyone who ought to be either on this table or in the GitHub contributor list, but isn’t. Thanks also to all those who have reported bugs and support issues, and often patches and testcases to either the late gna! website or sourceforge.net/p/ghdl-updates/tickets@footnote{https://sourceforge.net/p/ghdl-updates/tickets/}. __________________________________________________________________ @c # Load pre-defined aliases and graphical characters like © from docutils @c # is used to denote the special path @c # \Lib\site-packages\docutils\parsers\rst\include @c This data file has been placed in the public domain. @c Derived from the Unicode character mappings available from @c . @c Processed by unicode2rstsubs.py, part of Docutils: @c . @c This data file has been placed in the public domain. @c Derived from the Unicode character mappings available from @c . @c Processed by unicode2rstsubs.py, part of Docutils: @c . @c # define a hard line break for HTML @node Quick Start Guide,Invoking GHDL,Copyrights | Licenses,Top @anchor{quick_start/index doc}@anchor{79}@anchor{quick_start/index quick-start-guide}@anchor{7a}@anchor{quick_start/index using-quickstart}@anchor{7b} @chapter Quick Start Guide Since this is the user and reference manual for @cite{GHDL}, it does not contain an introduction to @cite{VHDL}. Thus, the reader should have at least a basic knowledge of @cite{VHDL}. A good knowledge of @cite{VHDL} language reference manual (usually called LRM) is a plus. Nevertheless, multiple explained examples are provided, in the hope that they are useful for users to learn about both @cite{GHDL} and @cite{VHDL}. @c # Load pre-defined aliases and graphical characters like © from docutils @c # is used to denote the special path @c # \Lib\site-packages\docutils\parsers\rst\include @c This data file has been placed in the public domain. @c Derived from the Unicode character mappings available from @c . @c Processed by unicode2rstsubs.py, part of Docutils: @c . @c This data file has been placed in the public domain. @c Derived from the Unicode character mappings available from @c . @c Processed by unicode2rstsubs.py, part of Docutils: @c . @c # define a hard line break for HTML @menu * Simulation:: * Python Interfaces:: @end menu @node Simulation,Python Interfaces,,Quick Start Guide @anchor{quick_start/simulation/index doc}@anchor{7c}@anchor{quick_start/simulation/index simulation}@anchor{7d}@anchor{quick_start/simulation/index using-quickstart-simulation}@anchor{5e} @section Simulation As explained in @ref{42,,What is GHDL?}, @cite{GHDL} is a compiler which translates @cite{VHDL} files to machine code. Hence, the regular workflow is composed of three steps: @itemize * @item @ref{7e,,Analysis [-a]}: convert design units (@cite{VHDL} sources) to an internal representation. @item @ref{7f,,Elaboration [-e]}: generate executable machine code for a target module (top-level entity). @item @ref{80,,Run [-r]}: execute the design to test the behaviour, generate output/waveforms, etc. @end itemize The following tips might be useful: @itemize * @item Don’t forget to select the version of the VHDL standard you want to use (see @ref{81,,VHDL standards}). The default is @ref{82,,--std=93c}. Use @ref{82,,--std=08} for VHDL-2008 (albeit not fully implemented). @itemize * @item Use @ref{83,,--ieee=synopsys} if your design depends on a non-standard implementation of the IEEE library. @item Use @ref{84,,-fexplicit} and @ref{85,,-frelaxed-rules} if needed. For instance, if you would like to use VHDL 2008 and also use shared variables with an ordinary type (deprecated in VHDL 2000), you can use @code{--std=08 -frelaxed-rules}. @end itemize @item Use @ref{86,,--work=LIB_NAME} to analyze files into the @code{LIB_NAME} library. To use files analyzed to a different directory, give the path to the @code{LIB_NAME} library using @ref{87,,-P/path/to/name/directory/}. @item Use the same options for analysis and elaboration. E.g., first analyse with @code{ghdl -a --std=08 --work=mylib myfile.vhdl}; and then elaborate and run with @code{ghdl --elab-run --std=08 top}. @end itemize Due to the fact that @cite{VHDL} is processed as a general purpose language (instead of an @cite{HDL}), all the language features are to be supported. I.e., @cite{VHDL} sources do not need to be limited to the synthesisable subset. However, distinction between synthesisable and non-synthesisable (simulation-only) subsets is often misleading for users who are new to the language. Different examples are provided, in the hope of helping understand the different use cases: @c # Load pre-defined aliases and graphical characters like © from docutils @c # is used to denote the special path @c # \Lib\site-packages\docutils\parsers\rst\include @c This data file has been placed in the public domain. @c Derived from the Unicode character mappings available from @c . @c Processed by unicode2rstsubs.py, part of Docutils: @c . @c This data file has been placed in the public domain. @c Derived from the Unicode character mappings available from @c . @c Processed by unicode2rstsubs.py, part of Docutils: @c . @c # define a hard line break for HTML @menu * Hello world program:: * Heartbeat module:: * Full adder module and testbench:: * Working with non-trivial designs:: @end menu @node Hello world program,Heartbeat module,,Simulation @anchor{quick_start/simulation/hello/index doc}@anchor{88}@anchor{quick_start/simulation/hello/index hello-world-program}@anchor{89}@anchor{quick_start/simulation/hello/index quickstart-hello}@anchor{8a} @subsection @cite{Hello world} program To illustrate the general purpose of @cite{VHDL}, the following block is a commented @cite{Hello world} program which is saved in a file named @code{hello.vhdl}: @example -- Hello world program use std.textio.all; -- Imports the standard textio package. -- Defines a design entity, without any ports. entity hello_world is end hello_world; architecture behaviour of hello_world is begin process variable l : line; begin write (l, String'("Hello world!")); writeline (output, l); wait; end process; end behaviour; @end example @cartouche @quotation Tip @itemize * @item Both @code{.vhdl} and @code{.vhd} extensions are used for @cite{VHDL} source files, while @code{.v} is used for Verilog. @quotation @itemize * @item Since, extension @code{.vhd} is also interpreted as a Virtual Hard Disk@footnote{https://en.wikipedia.org/wiki/VHD_(file_format)} file format, some users prefer @code{.vhdl}, to avoid ambiguity. This is the case with @cite{GHDL}’s codebase. However, in order to maintain backward-compatibility@footnote{https://en.wikipedia.org/wiki/8.3_filename} with legacy DOS systems, other users prefer @code{.vhd}. @end itemize @end quotation @item Unless you use especial characters, either @cite{UTF-8} or @cite{ISO-8859-1} encodings can be used. However, if you do, the latter should be used. The standard defines ASCII (7-bit encoding) or ISO Latin-1 (ISO-8859-1) as default. However, GHDL has a relaxing option, @ref{8b,,--mb-comments} (multi byte), to allow UTF-8 or other encodings in comments. @end itemize @end quotation @end cartouche @itemize - @item First, you have to compile the file; this is called @ref{7e,,analysis} of a design file in @cite{VHDL} terms. Run @code{ghdl -a hello.vhdl} in the @cite{shell}. This command creates or updates a file @code{work-obj93.cf}, which describes the library @code{work}. @item Then, run @code{ghdl -e hello_world} in the @cite{shell}. Command @ref{8c,,-e} means @ref{7f,,elaborate}, which is used to build a design, with the @code{hello_world} entity at the top of the hierarchy. @item Last, you can directly launch the simulation @ref{80,,running} @code{ghdl -r hello_world} in the @cite{shell}. The result of the simulation will be shown on screen: @end itemize @example Hello world! @end example @cartouche @quotation Hint If a GCC/LLVM variant of @cite{GHDL} is used: @itemize * @item @ref{7e,,Analysis} generates a file, @code{hello.o}, which is the object file corresponding to your @cite{VHDL} program. This is not created with @ref{4b,,mcode}. These kind of object files can be compiled into foreign programs (see Linking GHDL object files to Ada/C@footnote{https://ghdl.github.io/ghdl-cosim/vhpidirect/linking.html#linking-with-ada}). @item The @ref{7f,,elaboration} step is mandatory after running the analysis and prior to launching the simulation. This will generate an executable binary named @code{hello_world}. @item As a result, @ref{8d,,-r} is just a passthrough to the binary generated in the @cite{elaboration}. Therefore, the executable can be run directly: @code{./hello_world}. See @ref{8d,,-r} for more informartion. @end itemize @end quotation @end cartouche @cartouche @quotation Hint @ref{8c,,-e} can be bypassed with @ref{4b,,mcode}, since @ref{8d,,-r} actually elaborates the design and saves it on memory before running the simulation. But you can still use it to check for some elaboration problems. @end quotation @end cartouche @c # Load pre-defined aliases and graphical characters like © from docutils @c # is used to denote the special path @c # \Lib\site-packages\docutils\parsers\rst\include @c This data file has been placed in the public domain. @c Derived from the Unicode character mappings available from @c . @c Processed by unicode2rstsubs.py, part of Docutils: @c . @c This data file has been placed in the public domain. @c Derived from the Unicode character mappings available from @c . @c Processed by unicode2rstsubs.py, part of Docutils: @c . @c # define a hard line break for HTML @node Heartbeat module,Full adder module and testbench,Hello world program,Simulation @anchor{quick_start/simulation/heartbeat/index doc}@anchor{8e}@anchor{quick_start/simulation/heartbeat/index heartbeat-module}@anchor{8f}@anchor{quick_start/simulation/heartbeat/index quickstart-heartbeat}@anchor{90} @subsection @cite{Heartbeat} module Although @ref{8a,,Hello world} illustrates that @cite{VHDL} is supported as a general purpose language, the main use case of @cite{GHDL} is to simulate hardware descriptions. The following block, which is saved in a file named @code{heartbeat.vhdl}, is an example of how to generate a 100 MHz clock signal with non-synthesisable VHDL: @example library ieee; use ieee.std_logic_1164.all; entity heartbeat is port ( clk: out std_logic); end heartbeat; architecture behaviour of heartbeat is constant clk_period : time := 10 ns; begin -- Clock process definition clk_process: process begin clk <= '0'; wait for clk_period/2; clk <= '1'; wait for clk_period/2; end process; end behaviour; @end example It can be @ref{7e,,analysed}, @ref{7f,,elaborated} and @ref{80,,run}, as you already know: @example ghdl -a heartbeat.vhdl ghdl -e heartbeat ghdl -r heartbeat @end example However, execution of the design does not terminate. At the same time, no output is shown on screen. This is because, traditionally, hardware designs are continuously running devices which do not have a screen where to print. In this context, inspection and verification of the behaviour is done through waveforms@footnote{https://en.wikipedia.org/wiki/Waveform_viewer}, which is supported by @cite{GHDL} (see @ref{91,,Export waveforms}). You can use either @ref{92,,--wave}, @ref{93,,--vcd}, @ref{94,,--vcdgz} or @ref{95,,--fst} to save the signals of the simulation to a file. Then, terminate the execution (@code{C-c}) and you can inspect the wave with a viewer, such as GtkWave@footnote{http://gtkwave.sourceforge.net/}. As explained in the manual@footnote{http://gtkwave.sourceforge.net/gtkwave.pdf}, GtkWave @emph{‘relies on a post-mortem approach through the use of dumpfiles’}. Therefore, you should first simulate your design and dump a waveform file, say GHW: @example ghdl -r heartbeat --wave=wave.ghw @end example Then, you can view the dump: @example gtkwave wave.ghw @end example Of course, manually terminating the simulation is for illustration purposes only. In @ref{96,,Full adder} and @ref{97,,Working with non-trivial designs}, you will see how to write a testbench to terminate the simulation programmatically. @c # Load pre-defined aliases and graphical characters like © from docutils @c # is used to denote the special path @c # \Lib\site-packages\docutils\parsers\rst\include @c This data file has been placed in the public domain. @c Derived from the Unicode character mappings available from @c . @c Processed by unicode2rstsubs.py, part of Docutils: @c . @c This data file has been placed in the public domain. @c Derived from the Unicode character mappings available from @c . @c Processed by unicode2rstsubs.py, part of Docutils: @c . @c # define a hard line break for HTML @node Full adder module and testbench,Working with non-trivial designs,Heartbeat module,Simulation @anchor{quick_start/simulation/adder/index doc}@anchor{98}@anchor{quick_start/simulation/adder/index full-adder-module-and-testbench}@anchor{99}@anchor{quick_start/simulation/adder/index quickstart-adder}@anchor{96} @subsection @cite{Full adder} module and testbench Unlike @ref{90,,Heartbeat}, the target hardware design in this example is written using the synthesisable subset of @cite{VHDL}. It is a full adder@footnote{https://en.wikipedia.org/wiki/Adder_(electronics)#Full_adder} described in a file named @code{adder.vhdl}: @example entity adder is -- `i0`, `i1`, and the carry-in `ci` are inputs of the adder. -- `s` is the sum output, `co` is the carry-out. port (i0, i1 : in bit; ci : in bit; s : out bit; co : out bit); end adder; architecture rtl of adder is begin -- This full-adder architecture contains two concurrent assignments. -- Compute the sum. s <= i0 xor i1 xor ci; -- Compute the carry. co <= (i0 and i1) or (i0 and ci) or (i1 and ci); end rtl; @end example You can @ref{7e,,analyse} this design file, @code{ghdl -a adder.vhdl}, and try to execute the @cite{adder} design. But this is useless, since nothing externally visible will happen. In order to check this full adder, a @emph{testbench} has to be run. The @emph{testbench} is a description of how to generate inputs and how to check the outputs of the Unit Under Test (UUT). This one is very simple, since the adder is also simple: it checks exhaustively all inputs. Note that only the behaviour is tested, timing constraints are not checked. A file named @code{adder_tb.vhdl} contains the testbench for the adder: @example -- A testbench has no ports. entity adder_tb is end adder_tb; architecture behav of adder_tb is -- Declaration of the component that will be instantiated. component adder port (i0, i1 : in bit; ci : in bit; s : out bit; co : out bit); end component; -- Specifies which entity is bound with the component. for adder_0: adder use entity work.adder; signal i0, i1, ci, s, co : bit; begin -- Component instantiation. adder_0: adder port map (i0 => i0, i1 => i1, ci => ci, s => s, co => co); -- This process does the real job. process type pattern_type is record -- The inputs of the adder. i0, i1, ci : bit; -- The expected outputs of the adder. s, co : bit; end record; -- The patterns to apply. type pattern_array is array (natural range <>) of pattern_type; constant patterns : pattern_array := (('0', '0', '0', '0', '0'), ('0', '0', '1', '1', '0'), ('0', '1', '0', '1', '0'), ('0', '1', '1', '0', '1'), ('1', '0', '0', '1', '0'), ('1', '0', '1', '0', '1'), ('1', '1', '0', '0', '1'), ('1', '1', '1', '1', '1')); begin -- Check each pattern. for i in patterns'range loop -- Set the inputs. i0 <= patterns(i).i0; i1 <= patterns(i).i1; ci <= patterns(i).ci; -- Wait for the results. wait for 1 ns; -- Check the outputs. assert s = patterns(i).s report "bad sum value" severity error; assert co = patterns(i).co report "bad carry out value" severity error; end loop; assert false report "end of test" severity note; -- Wait forever; this will finish the simulation. wait; end process; end behav; @end example As usual, you should analyze the file, @code{ghdl -a adder_tb.vhdl}. @cartouche @quotation Hint Then, if required, @ref{7f,,elaborate} the testbench: @code{ghdl -e adder_tb}. You do not need to specify which object files are required, since @cite{GHDL} knows them and automatically adds them. @end quotation @end cartouche Now, it is time to @ref{80,,run} the testbench, @code{ghdl -r adder_tb}, and check the result on screen: @example adder_tb.vhdl:52:7:(assertion note): end of test @end example If your design is rather complex, you’d like to inspect signals as explained in @ref{90,,Heartbeat}. See section @ref{9a,,Simulation options}, for more details on other runtime options. @c # Load pre-defined aliases and graphical characters like © from docutils @c # is used to denote the special path @c # \Lib\site-packages\docutils\parsers\rst\include @c This data file has been placed in the public domain. @c Derived from the Unicode character mappings available from @c . @c Processed by unicode2rstsubs.py, part of Docutils: @c . @c This data file has been placed in the public domain. @c Derived from the Unicode character mappings available from @c . @c Processed by unicode2rstsubs.py, part of Docutils: @c . @c # define a hard line break for HTML @node Working with non-trivial designs,,Full adder module and testbench,Simulation @anchor{quick_start/simulation/DLXModelSuite doc}@anchor{9b}@anchor{quick_start/simulation/DLXModelSuite quickstart-dlx}@anchor{97}@anchor{quick_start/simulation/DLXModelSuite working-with-non-trivial-designs}@anchor{9c} @subsection Working with non-trivial designs Designs are usually more complex than the previous examples. Unless you are only studying VHDL, you will work with larger designs. Let’s see how to analyse a design such as the DLX model suite written by Peter Ashenden, which is distributed under the terms of the GNU General Public License. A copy is kept at ghdl.free.fr/dlx.tar.gz@footnote{http://ghdl.free.fr/dlx.tar.gz} . @itemize - @item First, untar the sources: @code{tar zxvf dlx.tar.gz}. @end itemize @cartouche @quotation Hint @quotation In order not to pollute the sources with the artifacts (@cite{WORK} library), it is a good idea to create a @code{work/} subdirectory. To any GHDL commands, we will add the @ref{9d,,--workdir=work} option, so that all files generated by the compiler (except the executable) will be placed in this directory. @end quotation @example $ cd dlx $ mkdir work @end example @end quotation @end cartouche @itemize * @item Then, we will run the @code{dlx_test_behaviour} design. We need to analyse all the design units for the design hierarchy, in the correct order. GHDL provides an easy way to do this, by @ref{9e,,importing} the sources: @code{ghdl -i --workdir=work *.vhdl}. @item GHDL knows all the design units of the DLX, but none of them has been analysed. Run the @ref{9f,,make} command, @code{ghdl -m --workdir=work dlx_test_behaviour}, which analyses and elaborates a design. This creates many files in the @code{work/} directory, and (GCC/LLVM only) the @code{dlx_test_behaviour} executable in the current directory. @end itemize @cartouche @quotation Hint The simulation needs to have a DLX program contained in the file @code{dlx.out}. This memory image will be loaded in the DLX memory. Just take one sample: @code{cp test_loop.out dlx.out}. @end quotation @end cartouche @itemize * @item Now, you can @ref{80,,run} the test suite: @code{ghdl -r --workdir=work dlx_test_behaviour}. The test bench monitors the bus and displays each executed instruction. It finishes with an assertion of severity level note: @example dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction encountered, execution halted @end example @item Last, since the clock is still running, you have to manually stop the program with the @code{C-c} key sequence. This behavior prevents you from running the testbench in batch mode. However, you may force the simulator to stop when an assertion above or equal a certain severity level occurs. To do so, call run with this option instead: @code{ghdl -r --workdir=work dlx_test_behaviour --assert-level=note`}. With @ref{a0,,--assert-level}, the program stops just after the previous message: @example dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction encountered, execution halted error: assertion failed @end example @end itemize @cartouche @quotation Tip If you want to make room on your hard drive, you can either: @itemize * @item @ref{a1,,Clean} the design library with @code{ghdl --clean --workdir=work}. This removes the executable and all the object files. If you want to rebuild the design at this point, just do the make command as shown above. @item @ref{a2,,Remove} the design library with @code{ghdl --remove --workdir=work}. This removes the executable, all the object files and the library file. If you want to rebuild the design, you have to import the sources again and make the design. @item Remove the @code{work/} directory: @code{rm -rf work}. Only the executable is kept. If you want to rebuild the design, create the @code{work/} directory, import the sources, and make the design. @end itemize @end quotation @end cartouche @cartouche @quotation Warning Sometimes, a design does not fully follow the VHDL standards. For example it might use the badly engineered @code{std_logic_unsigned} package. GHDL supports this VHDL dialect through some options: @ref{83,,--ieee=synopsys}, @ref{84,,-fexplicit}, etc. See section @ref{67,,IEEE library pitfalls}, for more details. @end quotation @end cartouche @cartouche @quotation Tip See Learning VHDL with GHDL@footnote{https://github.com/ghdl/ghdl/issues/1291}. @end quotation @end cartouche @c # Load pre-defined aliases and graphical characters like © from docutils @c # is used to denote the special path @c # \Lib\site-packages\docutils\parsers\rst\include @c This data file has been placed in the public domain. @c Derived from the Unicode character mappings available from @c . @c Processed by unicode2rstsubs.py, part of Docutils: @c . @c This data file has been placed in the public domain. @c Derived from the Unicode character mappings available from @c . @c Processed by unicode2rstsubs.py, part of Docutils: @c . @c # define a hard line break for HTML @node Python Interfaces,,Simulation,Quick Start Guide @anchor{quick_start/python/index doc}@anchor{a3}@anchor{quick_start/python/index python-interfaces}@anchor{a4}@anchor{quick_start/python/index using-quickstart-python}@anchor{a5} @section Python Interfaces Currently, pyGHDL is not distributed through PyPI. Therefore, users need to install it from the git repository. However, the version of the sources must be compatible with the installed version of GHDL (and the shared library @code{libghdl}). Installing from @code{master} is discouraged, because it might contain changes to the internal AST. Instead, @code{ghdl version hash} allows getting the commit hash of the version the installed binary was built from. Since @code{pip} allows installing packages by providing the URL to the git repo, this is the recommended installation procedure: @example pip install git+https://github.com/ghdl/ghdl.git@@$(ghdl version hash) @end example @menu * Language Server:: @end menu @node Language Server,,,Python Interfaces @anchor{quick_start/python/index cmdref}@anchor{a6}@anchor{quick_start/python/index language-server}@anchor{a7} @subsection Language Server When installed through @code{pip}, pyGHDL provides executable entrypoints registered in the search PATH, such as @code{ghdl-ls}. @c # @c This files requires a Python module called 'AutoProgram' to be located in the @c 'doc' root folder. It expects a variable 'parser' of type ArgumentParser. @menu * ghdl-ls:: @end menu @node ghdl-ls,,,Language Server @anchor{quick_start/python/index cmdref-ghdlls}@anchor{a8}@anchor{quick_start/python/index ghdl-ls}@anchor{a9} @subsubsection ghdl-ls VHDL Language Protocol Server. Find info about clients in ghdl/ghdl-language-server@footnote{https://github.com/ghdl/ghdl-language-server}. @example usage: ghdl-ls [-h] [--version] [--verbose] [--log-file LOG_FILE] [--trace-file TRACE_FILE] [--input INPUT] [--disp-config] @end example @menu * optional arguments:: @end menu @node optional arguments,,,ghdl-ls @anchor{quick_start/python/index optional-arguments}@anchor{aa} @subsubsection optional arguments @geindex ghdl-ls command line option; -h @geindex ghdl-ls command line option; --help @anchor{quick_start/python/index cmdoption-ghdl-ls-h}@anchor{ab}@anchor{quick_start/python/index cmdoption-ghdl-ls-help}@anchor{ac} @deffn {Option} @w{-}h, @w{-}@w{-}help show this help message and exit @end deffn @geindex ghdl-ls command line option; --version @geindex ghdl-ls command line option; -V @anchor{quick_start/python/index cmdoption-ghdl-ls-version}@anchor{ad}@anchor{quick_start/python/index cmdoption-ghdl-ls-V}@anchor{ae}@anchor{quick_start/python/index cmdoption-ghdl-ls-v}@anchor{af} @deffn {Option} @w{-}@w{-}version, @w{-}V show program’s version number and exit @end deffn @geindex ghdl-ls command line option; --verbose @geindex ghdl-ls command line option; -v @anchor{quick_start/python/index cmdoption-ghdl-ls-verbose}@anchor{b0}@anchor{quick_start/python/index cmdoption-ghdl-ls-0}@anchor{b1} @deffn {Option} @w{-}@w{-}verbose, @w{-}v Show debug output @end deffn @geindex ghdl-ls command line option; --log-file @anchor{quick_start/python/index cmdoption-ghdl-ls-log-file}@anchor{b2} @deffn {Option} @w{-}@w{-}log@w{-}file Redirect logs to the given file instead of stderr @end deffn @geindex ghdl-ls command line option; --trace-file @anchor{quick_start/python/index cmdoption-ghdl-ls-trace-file}@anchor{b3} @deffn {Option} @w{-}@w{-}trace@w{-}file Save RPC data to FILE.in and FILE.out (overrides @geindex GHDL_LS_TRACE @geindex environment variable; GHDL_LS_TRACE @code{GHDL_LS_TRACE}) @end deffn @geindex ghdl-ls command line option; --input @geindex ghdl-ls command line option; -i @anchor{quick_start/python/index cmdoption-ghdl-ls-input}@anchor{b4}@anchor{quick_start/python/index cmdoption-ghdl-ls-i}@anchor{b5} @deffn {Option} @w{-}@w{-}input , @w{-}i Read request from file @end deffn @geindex ghdl-ls command line option; --disp-config @anchor{quick_start/python/index cmdoption-ghdl-ls-disp-config}@anchor{b6} @deffn {Option} @w{-}@w{-}disp@w{-}config Display installation configuration and exit @end deffn @c # Load pre-defined aliases and graphical characters like © from docutils @c # is used to denote the special path @c # \Lib\site-packages\docutils\parsers\rst\include @c This data file has been placed in the public domain. @c Derived from the Unicode character mappings available from @c . @c Processed by unicode2rstsubs.py, part of Docutils: @c . @c This data file has been placed in the public domain. @c Derived from the Unicode character mappings available from @c . @c Processed by unicode2rstsubs.py, part of Docutils: @c . @c # define a hard line break for HTML @node Invoking GHDL,Simulation runtime,Quick Start Guide,Top @anchor{using/InvokingGHDL doc}@anchor{b7}@anchor{using/InvokingGHDL invoking-ghdl}@anchor{b8}@anchor{using/InvokingGHDL using-invoking}@anchor{5f} @chapter Invoking GHDL The form of the @code{ghdl} command is @code{ghdl command [options...]}. There are multiple available commands, but these general rules apply: @itemize * @item The first argument selects the command. The options are used to slightly modify the action. @item No option is allowed before the command. Except for the run command, no option is allowed after a filename or a unit name. @end itemize @cartouche @quotation Hint If the number of options is large and the command line length is beyond the system limit, you can use a response file. An argument that starts with a @code{@@} is considered as a response file; it is replaced by arguments read from the file (separated by blanks and end of line). @end quotation @end cartouche @cartouche @quotation Hint Only the most common commands and options are shown here. For the most advanced and experimental features see section @ref{60,,Additional Command Reference}. @end quotation @end cartouche @cartouche @quotation Warning During analysis and elaboration GHDL may read the @code{std} and @code{ieee} files. The location of these files is based on the prefix, which is (in order of priority): @itemize * @item the @ref{b9,,--PREFIX} command line option @item the @geindex GHDL_PREFIX @geindex environment variable; GHDL_PREFIX @ref{ba,,GHDL_PREFIX} environment variable @item a built-in default path. It is a hard-coded path on GNU/Linux, and it corresponds to the value of the @code{HKLM\Software\Ghdl\Install_Dir} registry entry on Windows. @end itemize You should use the @ref{bb,,--disp-config} command to display and debug installation problems. @end quotation @end cartouche @menu * Design building commands:: * Design rebuilding commands:: * Options:: * Warnings:: * Diagnostics Control:: * Library commands:: * VPI/VHPI build commands:: * IEEE library pitfalls:: @end menu @node Design building commands,Design rebuilding commands,,Invoking GHDL @anchor{using/InvokingGHDL design-building-commands}@anchor{bc} @section Design building commands The most commonly used commands of GHDL are those to analyze and elaborate a design. @geindex cmd analysis @menu * Analysis [-a]:: * Elaboration [-e]:: * Run [-r]:: * Elaborate and run [--elab-run]:: * Check syntax [-s]:: * Analyze and elaborate [-c]:: @end menu @node Analysis [-a],Elaboration [-e],,Design building commands @anchor{using/InvokingGHDL analysis-a}@anchor{bd}@anchor{using/InvokingGHDL analysis-command}@anchor{7e} @subsection Analysis [@code{-a}] @geindex ghdl command line option; -a <[options...] file...> @anchor{using/InvokingGHDL cmdoption-ghdl-a}@anchor{be} @deffn {Option} @w{-}a <[options...] file...> @end deffn Analyzes/compiles one or more files, and creates an object file for each source file. Any argument starting with a dash is an option, the others are filenames. No options are allowed after a filename argument. GHDL analyzes each filename in the given order, and stops the analysis in case of error (remaining files are not analyzed). See @ref{bf,,Options}, for details on the GHDL options. For example, to produce debugging information such as line numbers, use: @code{ghdl -a -g my_design.vhdl}. @geindex cmd elaboration @node Elaboration [-e],Run [-r],Analysis [-a],Design building commands @anchor{using/InvokingGHDL elaboration-command}@anchor{7f}@anchor{using/InvokingGHDL elaboration-e}@anchor{c0} @subsection Elaboration [@code{-e}] @geindex ghdl command line option; -e <[options...] [library.]top_unit [arch]> @anchor{using/InvokingGHDL cmdoption-ghdl-e}@anchor{8c} @deffn {Option} @w{-}e <[options...] [library.]top_unit [arch]> @end deffn Re-analyzes all the configurations, entities, architectures and package declarations, and creates the default configurations and the default binding indications according to the LRM rules. It also generates the list of object files required for the executable. Then, it links all these files with the runtime library (GRT). The elaboration command, @ref{8c,,-e}, must be followed by a @code{top_unit} name denoting either of: @quotation @itemize * @item a configuration unit @item an entity unit @item an entity unit followed by a secondary unit (the name of an architecture unit) @end itemize @end quotation @itemize * @item Name of the top units can be either a simple name (without dots), or the name of a logical library followed by a dot and a simple name. The latter is equivalent to using @ref{86,,--work=NAME} described in @ref{bf,,Options}: @code{-e <[options...] --work=library top_unit [arch]>}. It selects the name of the library to be used as @code{WORK}. See section @ref{c1,,Top entity}, for the restrictions on the root/top unit of a hierarchy. @item Name of the secondary units must be a simple name; they cannot contain any dot. @end itemize With regard to the artifacts: @itemize * @item If the GCC/LLVM backend was enabled during the compilation of GHDL, the elaboration command creates an executable containing the code of the VHDL sources, the elaboration code and simulation code for executing a design hierarchy. The executable is created in the current directory and the the filename is the name of the primary unit, or for the latter case, the concatenation of the name of the primary unit, a dash, and the name of the secondary unit. Option @code{-o} followed by a filename can override the default executable filename. @item If mcode is used, this command elaborates the design but does not generate anything. Since the run command also elaborates the design, this can be skipped. @end itemize @cartouche @quotation Warning This elaboration command is not a complete elaboration in terms of the VHDL standard. The actual elaboration is performed at runtime. Therefore, in order to get a complete VHDL elaboration without running the simulation, @code{ghdl --elab-run --no-run} is required. See @ref{c2,,--no-run}. @end quotation @end cartouche @geindex cmd run @node Run [-r],Elaborate and run [--elab-run],Elaboration [-e],Design building commands @anchor{using/InvokingGHDL run-command}@anchor{80}@anchor{using/InvokingGHDL run-r}@anchor{c3} @subsection Run [@code{-r}] @geindex ghdl command line option; -r <[options...] [library.]top_unit [arch] [simulation_options...]> @anchor{using/InvokingGHDL cmdoption-ghdl-r}@anchor{8d} @deffn {Option} @w{-}r <[options...] [library.]top_unit [arch] [simulation_options...]> @end deffn Runs/simulates a design. Two sets of options are accepted, both of them being separated by @code{[library.]top_unit [arch]}. For the first set, @code{options...}, arguments are the same as for the @ref{7f,,elaboration command}. For the second set, @code{simulation_options...}, arguments are defined in @ref{c4,,Simulation (runtime)}. @itemize * @item GGC/LLVM: the filename of the executable is determined and it is executed. Elaboration options are ignored. You may also directly execute the program. The executable must be in the current directory. @item mcode: the design is elaborated and the simulation is launched. As a consequence, you must use the same options used during analysis. @end itemize This command exists for three reasons: @itemize * @item It works with mcode implementation, where the executable code is generated in memory. @item You are using GCC/LLVM, but you don’t need to create the executable program name. @item It is coherent with the @ref{be,,-a} and @ref{8c,,-e} commands. @end itemize @geindex cmd elaborate and run @node Elaborate and run [--elab-run],Check syntax [-s],Run [-r],Design building commands @anchor{using/InvokingGHDL elab-and-run-command}@anchor{c5}@anchor{using/InvokingGHDL elaborate-and-run-elab-run}@anchor{c6} @subsection Elaborate and run [@code{--elab-run}] @geindex ghdl command line option; --elab-run <[options...] [library.]top_unit [arch] [simulation_options...]> @anchor{using/InvokingGHDL cmdoption-ghdl-elab-run}@anchor{c7} @deffn {Option} @w{-}@w{-}elab@w{-}run <[options...] [library.]top_unit [arch] [simulation_options...]> @end deffn Acts like the elaboration command followed by the run command. Note that this command accepts two sets of options. See @ref{8c,,-e}, @ref{8d,,-r} and @ref{c4,,Simulation (runtime)}. @geindex cmd checking syntax @node Check syntax [-s],Analyze and elaborate [-c],Elaborate and run [--elab-run],Design building commands @anchor{using/InvokingGHDL check-syntax-s}@anchor{c8} @subsection Check syntax [@code{-s}] @geindex ghdl command line option; -s <[options...] file...> @anchor{using/InvokingGHDL cmdoption-ghdl-s}@anchor{c9} @deffn {Option} @w{-}s <[options...] file...> @end deffn Analyze files but do not generate code. This command may be used to check the syntax of files. It does not update the library. @geindex cmd analyze and elaborate @node Analyze and elaborate [-c],,Check syntax [-s],Design building commands @anchor{using/InvokingGHDL analyze-and-elaborate-c}@anchor{ca} @subsection Analyze and elaborate [@code{-c}] @geindex ghdl command line option; -c <[options...] file... - top_unit [arch]> @anchor{using/InvokingGHDL cmdoption-ghdl-c}@anchor{cb} @deffn {Option} @w{-}c <[options...] file... @w{-} top_unit [arch]> @end deffn @cartouche @quotation Hint With GCC/LLVM, @ref{8c,,-e} should be used, and @ref{8d,,-r} with mcode. @end quotation @end cartouche The files are first parsed, and then a elaboration is performed, which drives an analysis. Effectively, analysis and elaboration are combined, but there is no explicit call to @ref{be,,-a}. With GCC/LLVM, code is generated during the elaboration. With mcode, the simulation is launched after the elaboration. All the units of the files are put into the @cite{work} library. But, the work library is neither read from disk nor saved. Therefore, you must give all the files of the @cite{work} library your design needs. The advantages over the traditional approach (analyze and then elaborate) are: @itemize * @item The compilation cycle is achieved in one command. @item Since the files are only parsed once, the compilation cycle may be faster. @item You don’t need to know an analysis order. @item This command produces a smaller executable, since unused units and subprograms do not generate code. @end itemize @cartouche @quotation Hint However, you should know that most of the time is spent in code generation and the analyze and elaborate command generates code for all units needed, even units of @code{std} and @code{ieee} libraries. Therefore, according to the design, the time for this command may be higher than the time for the analyze command followed by the elaborate command. @end quotation @end cartouche @cartouche @quotation Warning This command is still under development. In case of problems, you should go back to the traditional way. @end quotation @end cartouche @node Design rebuilding commands,Options,Design building commands,Invoking GHDL @anchor{using/InvokingGHDL design-rebuilding-commands}@anchor{cc} @section Design rebuilding commands Analyzing and elaborating a design consisting of several files can be tricky, due to dependencies. GHDL has a few commands for rebuilding a design. @geindex cmd importing files @menu * Import [-i]:: * Elab-order [--elab-order]:: * Make [-m]:: * Generate Makefile [--gen-makefile]:: * Generate dependency file command [--gen-depends]:: @end menu @node Import [-i],Elab-order [--elab-order],,Design rebuilding commands @anchor{using/InvokingGHDL import-command}@anchor{9e}@anchor{using/InvokingGHDL import-i}@anchor{cd} @subsection Import [@code{-i}] @geindex ghdl command line option; -i <[options...] file...> @anchor{using/InvokingGHDL cmdoption-ghdl-i}@anchor{ce} @deffn {Option} @w{-}i <[options...] file...> @end deffn All the files specified in the command line are scanned, parsed and added into the libraries but as not yet analyzed. No object files are created. Its purpose is to localize design units in the design files. The make command will then be able to recursively build a hierarchy from an entity name or a configuration name. @cartouche @quotation Hint @itemize * @item Note that all the files are added to the work library. If you have many libraries, you must use the command for each library. @item Since the files are parsed, there must be correct files. However, since they are not analyzed, many errors are tolerated by this command. @end itemize @end quotation @end cartouche See @ref{cf,,-m}, to actually build the design. See also @ref{d0,,--elab-order}, for retrieving the compilation order guessed recursively. @geindex cmd elaboration order @node Elab-order [--elab-order],Make [-m],Import [-i],Design rebuilding commands @anchor{using/InvokingGHDL elab-order-elab-order}@anchor{d1} @subsection Elab-order [@code{--elab-order}] @geindex ghdl command line option; --elab-order <[options...] [libray.]top_unit [arch]> @anchor{using/InvokingGHDL cmdoption-ghdl-elab-order}@anchor{d0} @deffn {Option} @w{-}@w{-}elab@w{-}order <[options...] [libray.]top_unit [arch]> @end deffn Print the list of sources required for elaborating a unit, in order for them to be analyzed without dependency issues. This is expected to be used after @ref{ce,,-i}, or for retrieving the order for some unit analyzed through third-party scripts. @cartouche @quotation Attention Currently, the list does not include information about the logical library names where each source needs to be analyzed. Hence, it is mostly useful when all sources belong to the same @code{WORK} library. @end quotation @end cartouche @geindex cmd make @node Make [-m],Generate Makefile [--gen-makefile],Elab-order [--elab-order],Design rebuilding commands @anchor{using/InvokingGHDL make-command}@anchor{9f}@anchor{using/InvokingGHDL make-m}@anchor{d2} @subsection Make [@code{-m}] @geindex ghdl command line option; -m <[options...] [library.]top_unit [arch]> @anchor{using/InvokingGHDL cmdoption-ghdl-m}@anchor{cf} @deffn {Option} @w{-}m <[options...] [library.]top_unit [arch]> @end deffn Analyze automatically outdated files and elaborate a design. The primary unit denoted by the @code{[library.]top_unit} argument must already be known by the system, either because you have already analyzed it (even if you have modified it) or because you have imported it. A file may be outdated because it has been modified (e.g. you have just edited it), or because a design unit contained in the file depends on a unit which is outdated. This rule is recursive. @itemize * @item With option @code{--bind}, GHDL will stop before the final linking step. This is useful when the main entry point is not GHDL and you’re linking GHDL object files into a foreign program. @item With option @code{-f} (force), GHDL analyzes all the units of the work library needed to create the design hierarchy. Outdated units are recompiled. This is useful if you want to compile a design hierarchy with new compilation flags (for example, to add the @code{-g} debugging option). @end itemize @cartouche @quotation Important The make command will only re-analyze design units in the work library. GHDL fails if it has to analyze an outdated unit from another library. @end quotation @end cartouche The purpose of this command is to be able to compile a design without prior knowledge of file order. In the VHDL model, some units must be analyzed before others (e.g. an entity before its architecture). It might be a nightmare to analyze a full design of several files if you don’t have the ordered list of files. This command computes an analysis order. The make command fails when a unit was not previously parsed. For example, if you split a file containing several design units into several files, you must either import these new files or analyze them so that GHDL knows in which file these units are. The make command imports files which have been modified. Then, a design hierarchy is internally built as if no units are outdated. Then, all outdated design units, using the dependencies of the design hierarchy, are analyzed. If necessary, the design hierarchy is elaborated. @cartouche @quotation Hint This is not perfect, since the default architecture (the most recently analyzed one) may change while outdated design files are analyzed. In such a case, re-run the make command of GHDL. @end quotation @end cartouche @geindex cmd generate makefile @node Generate Makefile [--gen-makefile],Generate dependency file command [--gen-depends],Make [-m],Design rebuilding commands @anchor{using/InvokingGHDL generate-makefile-gen-makefile}@anchor{d3} @subsection Generate Makefile [@code{--gen-makefile}] @geindex ghdl command line option; --gen-makefile <[options...] [library.]top_unit [arch]> @anchor{using/InvokingGHDL cmdoption-ghdl-gen-makefile}@anchor{d4} @deffn {Option} @w{-}@w{-}gen@w{-}makefile <[options...] [library.]top_unit [arch]> @end deffn This command works like the make command (see @ref{cf,,-m}), but only a makefile is generated on the standard output. @geindex --gen-depends command @node Generate dependency file command [--gen-depends],,Generate Makefile [--gen-makefile],Design rebuilding commands @anchor{using/InvokingGHDL generate-dependency-file-command-gen-depends}@anchor{d5} @subsection Generate dependency file command [@code{--gen-depends}] @geindex ghdl command line option; --gen-depends <[options...] [library.]top_unit [arch]> @anchor{using/InvokingGHDL cmdoption-ghdl-gen-depends}@anchor{d6} @deffn {Option} @w{-}@w{-}gen@w{-}depends <[options...] [library.]top_unit [arch]> @end deffn Generate a Makefile containing only dependencies to build a design unit. This command works like the make and gen-makefile commands (see @ref{cf,,-m}), but instead of a full makefile only dependencies without rules are generated on the standard output. Theses rules can then be integrated in another Makefile. @node Options,Warnings,Design rebuilding commands,Invoking GHDL @anchor{using/InvokingGHDL ghdl-options}@anchor{bf}@anchor{using/InvokingGHDL options}@anchor{d7} @section Options @geindex IEEE 1164 @geindex 1164 @geindex IEEE 1076.3 @geindex 1076.3 @geindex WORK library @geindex ghdl command line option; --work= @anchor{using/InvokingGHDL cmdoption-ghdl-work}@anchor{86} @deffn {Option} @w{-}@w{-}work= Specify the name of the @code{WORK} library. Analyzed units are always placed in the library logically named @code{WORK}. With this option, you can set its name. By default, the name is @code{work}. @cite{GHDL} checks whether @code{WORK} is a valid identifier. Although being more or less supported, the @code{WORK} identifier should not be an extended identifier, since the filesystem may prevent it from working correctly (due to case sensitivity or forbidden characters in filenames). @cartouche @quotation Attention @cite{VHDL} rules forbid you from adding units to the @code{std} library. Furthermore, you should not put units in the @code{ieee} library. @end quotation @end cartouche @cartouche @quotation Hint Since 849a25e0@footnote{https://github.com/ghdl/ghdl/commit/849a25e02cfb359e3d9313060156b0643495548b}, this option can be alternatively provided to several commands by prepending the library name to the top unit name. See, for instance, @ref{8c,,-e}. @end quotation @end cartouche @end deffn @geindex ghdl command line option; --workdir= @anchor{using/InvokingGHDL cmdoption-ghdl-workdir}@anchor{9d} @deffn {Option} @w{-}@w{-}workdir= Specify the directory where the @code{WORK} library is located. When this option is not present, the @code{WORK} library is in the current directory. The object files created by the compiler are always placed in the same directory as the @code{WORK} library. Use option @ref{87,,-P} to specify where libraries other than @code{WORK} are placed. @end deffn @geindex ghdl command line option; --std= @anchor{using/InvokingGHDL cmdoption-ghdl-std}@anchor{82} @deffn {Option} @w{-}@w{-}std= Specify the standard to use. By default, the standard is @code{93c}, which means VHDL-93 with relaxed rules. For details on @code{STANDARD} values see section @ref{81,,VHDL standards}. @cartouche @quotation Important This option resets the effect of @ref{d8,,-frelaxed}, so it should be the first option. @end quotation @end cartouche @end deffn @geindex ghdl command line option; -fsynopsys @anchor{using/InvokingGHDL cmdoption-ghdl-fsynopsys}@anchor{d9} @deffn {Option} @w{-}fsynopsys Allow the use of synopsys non-standard packages (@code{std_logic_arith}, @code{std_logic_signed}, @code{std_logic_unsigned}, @code{std_logic_textio}). These packages are present in the ieee library but without this option it’s an error to use them. The synopsys packages were created by some companies, and are popular. However they are not standard packages, and have been placed in the @cite{IEEE} library without the permission from the @code{ieee}. @end deffn @geindex ghdl command line option; --ieee= @anchor{using/InvokingGHDL cmdoption-ghdl-ieee}@anchor{83} @deffn {Option} @w{-}@w{-}ieee= @geindex ieee library @geindex synopsys library Select the @code{IEEE} library to use. @code{IEEE_VAR} must be one of: @table @asis @item none Do not supply an @cite{IEEE} library. Any library clause with the @code{IEEE} identifier will fail, unless you have created your own library with the @cite{IEEE} name. @item standard Supply an @cite{IEEE} library containing only packages defined by @code{ieee} standards. Currently, there are the multivalue logic system package @code{std_logic_1164} defined by IEEE 1164, the synthesis packages @code{numeric_bit} and @code{numeric_std} defined by IEEE 1076.3, and the @code{vital} packages @code{vital_timing} and @code{vital_primitives}, defined by IEEE 1076.4. The version of these packages is defined by the VHDL standard used. See section @ref{da,,VITAL packages}, for more details. @item synopsys This option is now deprecated. It is equivalent to @code{--ieee=standard} and @code{-fsynopsys}. @end table To avoid errors, you must use the same @cite{IEEE} library for all units of your design, and during elaboration. @end deffn @geindex ghdl command line option; -P @anchor{using/InvokingGHDL cmdoption-ghdl-P}@anchor{87}@anchor{using/InvokingGHDL cmdoption-ghdl-p}@anchor{db} @deffn {Option} @w{-}P Add @cite{DIRECTORY} to the end of the list of directories to be searched for library files. A library is searched in @cite{DIRECTORY} and also in @cite{DIRECTORY/LIB/vVV} (where @cite{LIB} is the name of the library and @cite{VV} the vhdl standard). The @cite{WORK} library is always searched in the path specified by the @ref{9d,,--workdir} option, or in the current directory if the latter option is not specified. @end deffn @geindex ghdl command line option; -fexplicit @anchor{using/InvokingGHDL cmdoption-ghdl-fexplicit}@anchor{84} @deffn {Option} @w{-}fexplicit When two operators are overloaded, give preference to the explicit declaration. This may be used to avoid the most common pitfall of the @code{std_logic_arith} package. See section @ref{67,,IEEE library pitfalls}, for an example. @end deffn @cartouche @quotation Warning This option is not set by default. We don’t think this option is a good feature, because it breaks the encapsulation rule. When set, an operator can be silently overridden in another package. You’d do better to fix your design and use the @code{numeric_std} package. @end quotation @end cartouche @geindex ghdl command line option; -frelaxed @anchor{using/InvokingGHDL cmdoption-ghdl-frelaxed}@anchor{d8} @deffn {Option} @w{-}frelaxed @end deffn @geindex ghdl command line option; -frelaxed-rules @anchor{using/InvokingGHDL cmdoption-ghdl-frelaxed-rules}@anchor{85} @deffn {Option} @w{-}frelaxed@w{-}rules @cartouche @quotation Important The effects of this option are reset by @ref{82,,--std}, so it should be placed @emph{after} that option. @end quotation @end cartouche Slightly relax some rules to be compatible with various other simulators or synthesizers: @itemize * @item VHDL-87 file declarations are accepted; @item Default binding indication rules of VHDL-02 are used. Default binding rules are often used, but they are particularly obscure before VHDL-02. @item Within an object declaration, allow references to the name (which references the hidden declaration). This ignores the error in the following code: @example package pkg1 is type state is (state1, state2, state3); end pkg1; use work.pkg1.all; package pkg2 is constant state1 : state := state1; end pkg2; @end example Some code (such as Xilinx packages) have such constructs, which are invalid. (The scope of the @code{state1} constant starts at the @cite{constant} keyword. Because the constant @code{state1} and the enumeration literal @code{state1} are homographs, the enumeration literal is hidden in the immediate scope of the constant). @end itemize This option also relaxes the rules about pure functions. Violations result in warnings instead of errors. @end deffn @geindex ghdl command line option; -fpsl @anchor{using/InvokingGHDL cmdoption-ghdl-fpsl}@anchor{dc} @deffn {Option} @w{-}fpsl Enable parsing of PSL assertions within comments. See section @ref{dd,,PSL support} for more details. @end deffn @geindex ghdl command line option; --mb-comments @geindex ghdl command line option; -C @anchor{using/InvokingGHDL cmdoption-ghdl-mb-comments}@anchor{8b}@anchor{using/InvokingGHDL cmdoption-ghdl-C}@anchor{de} @deffn {Option} @w{-}@w{-}mb@w{-}comments, @w{-}C Allow UTF8 or multi-bytes chars in a comment. According to the VHDL standards before 2002, the only characters allowed in a source file (and that includes the comments) are the graphical characters of the ISO 8859-1 character set. This is incompatible with comments using UTF-8 or some other encoding. This option lift this restriction. @end deffn @geindex ghdl command line option; --syn-binding @anchor{using/InvokingGHDL cmdoption-ghdl-syn-binding}@anchor{df} @deffn {Option} @w{-}@w{-}syn@w{-}binding Use synthesizer rules for component binding. During elaboration, if a component is not bound to an entity using VHDL LRM rules, try to find in any known library an entity whose name is the same as the component name. This rule is known as the synthesizer rule. There are two key points: normal VHDL LRM rules are tried first and entities are searched only in known libraries. A known library is a library which has been named in your design. This option is only useful during elaboration. @end deffn @geindex ghdl command line option; --format= @anchor{using/InvokingGHDL cmdoption-ghdl-format}@anchor{e0} @deffn {Option} @w{-}@w{-}format= Define the output format of some options, such as @ref{e1,,--pp-html} or @ref{e2,,--xref-html}. @itemize * @item By default or when @ref{e0,,--format=html2} is specified, generated files follow the HTML 2.0 standard, and colours are specified with @cite{} tags. However, colours are hard-coded. @item If @ref{e0,,--format=css} is specified, generated files follow the HTML 4.0 standard, and use the CSS-1 file @code{ghdl.css} to specify colours. This file is generated only if it does not already exist (it is never overwritten) and can be customized by the user to change colours or appearance. Refer to a generated file and its comments for more information. @end itemize @end deffn @geindex ghdl command line option; --no-vital-checks @anchor{using/InvokingGHDL cmdoption-ghdl-no-vital-checks}@anchor{e3} @deffn {Option} @w{-}@w{-}no@w{-}vital@w{-}checks @end deffn @geindex ghdl command line option; --vital-checks @anchor{using/InvokingGHDL cmdoption-ghdl-vital-checks}@anchor{e4} @deffn {Option} @w{-}@w{-}vital@w{-}checks Disable or enable checks of restriction on VITAL units. Checks are enabled by default. Checks are performed only when a design unit is decorated by a VITAL attribute. The VITAL attributes are @code{VITAL_Level0} and @code{VITAL_Level1}, both declared in the @code{ieee.VITAL_Timing} package. Currently, VITAL checks are only partially implemented. See section @ref{e5,,VHDL restrictions for VITAL} for more details. @end deffn @geindex ghdl command line option; --PREFIX= @anchor{using/InvokingGHDL cmdoption-ghdl-PREFIX}@anchor{b9}@anchor{using/InvokingGHDL cmdoption-ghdl-prefix}@anchor{e6} @deffn {Option} @w{-}@w{-}PREFIX= Use @code{PATH} as the prefix path to find commands and pre-installed (@code{std} and @code{ieee}) libraries. @end deffn @geindex ghdl command line option; -v @anchor{using/InvokingGHDL cmdoption-ghdl-v}@anchor{e7} @deffn {Option} @w{-}v Be verbose. For example, for analysis, elaboration and make commands, GHDL displays the commands executed. @end deffn @geindex ghdl command line option; -o= @anchor{using/InvokingGHDL cmdoption-ghdl-o}@anchor{e8} @deffn {Option} @w{-}o= All the commands that perform a link (@ref{8c,,-e}, @ref{c7,,--elab-run}, @ref{e9,,--link}, @ref{cb,,-c}, @ref{cf,,-m}, etc.) support overriding the location and name of the generated artifact. @end deffn @geindex ghdl command line option; --time-resolution= @anchor{using/InvokingGHDL cmdoption-ghdl-time-resolution}@anchor{ea} @deffn {Option} @w{-}@w{-}time@w{-}resolution= @cartouche @quotation Attention This feature is supported with @emph{mcode} backend only. It is not possible to support it with either LLVM or GCC backends, because it needs to apply globally. @end quotation @end cartouche Set the base time resolution of the simulation. This option is supported in commands @ref{be,,-a} and @ref{8d,,-r} only. Allowed values are @code{auto} (default), @code{fs}, @code{ps}, @code{ns}, @code{us}, @code{ms} or @code{sec}. With LLVM/GCC, the value is fixed to @code{fs}. @cartouche @quotation Hint When overriding the time resolution, all the time units that are used in the design must be larger. Using units below the resolution will produce a failure. @end quotation @end cartouche @end deffn @node Warnings,Diagnostics Control,Options,Invoking GHDL @anchor{using/InvokingGHDL warnings}@anchor{eb} @section Warnings Some constructions are not erroneous but dubious. Warnings are diagnostic messages that report such constructions. Some warnings are reported only during analysis, others during elaboration. @cartouche @quotation Hint You could disable a warning by using the @code{--warn-no-XXX} or @code{-Wno-XXX} instead of @code{--warn-XXX} or @code{-WXXX}. @end quotation @end cartouche @cartouche @quotation Hint The warnings @code{-Wbinding}, @code{-Wlibrary}, @code{-Wshared}, @code{-Wpure}, @code{-Wspecs}, @code{-Whide}, @code{-Wport} are enabled by default. @end quotation @end cartouche @geindex ghdl command line option; --warn-library @anchor{using/InvokingGHDL cmdoption-ghdl-warn-library}@anchor{ec} @deffn {Option} @w{-}@w{-}warn@w{-}library Warns if a design unit replaces another design unit with the same name. @end deffn @geindex ghdl command line option; --warn-default-binding @anchor{using/InvokingGHDL cmdoption-ghdl-warn-default-binding}@anchor{ed} @deffn {Option} @w{-}@w{-}warn@w{-}default@w{-}binding During analyze, warns if a component instantiation has neither configuration specification nor default binding. This may be useful if you want to detect during analyze possibly unbound components if you don’t use configuration. See section @ref{81,,VHDL standards} for more details about default binding rules. @end deffn @geindex ghdl command line option; --warn-binding @anchor{using/InvokingGHDL cmdoption-ghdl-warn-binding}@anchor{ee} @deffn {Option} @w{-}@w{-}warn@w{-}binding During elaboration, warns if a component instantiation is not bound (and not explicitly left unbound). Also warns if a port of an entity is not bound in a configuration specification or in a component configuration. This warning is enabled by default, since default binding rules are somewhat complex and an unbound component is most often unexpected. However, warnings are still emitted if a component instantiation is inside a generate statement. As a consequence, if you use the conditional generate statement to select a component according to the implementation, you will certainly get warnings. @end deffn @geindex ghdl command line option; --warn-reserved @anchor{using/InvokingGHDL cmdoption-ghdl-warn-reserved}@anchor{ef} @deffn {Option} @w{-}@w{-}warn@w{-}reserved Emit a warning if an identifier is a reserved word in a later VHDL standard. @end deffn @geindex ghdl command line option; --warn-nested-comment @anchor{using/InvokingGHDL cmdoption-ghdl-warn-nested-comment}@anchor{f0} @deffn {Option} @w{-}@w{-}warn@w{-}nested@w{-}comment Emit a warning if a @code{/*} appears within a block comment (vhdl 2008). @end deffn @geindex ghdl command line option; --warn-parenthesis @anchor{using/InvokingGHDL cmdoption-ghdl-warn-parenthesis}@anchor{f1} @deffn {Option} @w{-}@w{-}warn@w{-}parenthesis Emit a warning in case of weird use of parentheses. @end deffn @geindex ghdl command line option; --warn-vital-generic @anchor{using/InvokingGHDL cmdoption-ghdl-warn-vital-generic}@anchor{f2} @deffn {Option} @w{-}@w{-}warn@w{-}vital@w{-}generic Warns if a generic name of a vital entity is not a vital generic name. This is set by default. @end deffn @geindex ghdl command line option; --warn-delayed-checks @anchor{using/InvokingGHDL cmdoption-ghdl-warn-delayed-checks}@anchor{f3} @deffn {Option} @w{-}@w{-}warn@w{-}delayed@w{-}checks Warns for checks that cannot be done during analysis time and are postponed to elaboration time. This is because not all procedure bodies are available during analysis (either because a package body has not yet been analysed or because @cite{GHDL} doesn’t read not required package bodies). These are checks for no wait statements in a procedure called in a sensitized process and checks for pure rules of a function. @end deffn @geindex ghdl command line option; --warn-body @anchor{using/InvokingGHDL cmdoption-ghdl-warn-body}@anchor{f4} @deffn {Option} @w{-}@w{-}warn@w{-}body Emit a warning if a package body which is not required is analyzed. If a package does not declare a subprogram or a deferred constant, the package does not require a body. @end deffn @geindex ghdl command line option; --warn-specs @anchor{using/InvokingGHDL cmdoption-ghdl-warn-specs}@anchor{f5} @deffn {Option} @w{-}@w{-}warn@w{-}specs Emit a warning if an all or others specification does not apply. @end deffn @geindex ghdl command line option; --warn-runtime-error @anchor{using/InvokingGHDL cmdoption-ghdl-warn-runtime-error}@anchor{f6} @deffn {Option} @w{-}@w{-}warn@w{-}runtime@w{-}error Emit a warning in case of runtime error that is detected during analysis. @end deffn @geindex ghdl command line option; --warn-shared @anchor{using/InvokingGHDL cmdoption-ghdl-warn-shared}@anchor{f7} @deffn {Option} @w{-}@w{-}warn@w{-}shared Emit a warning when a shared variable is declared and its type it not a protected type. @end deffn @geindex ghdl command line option; --warn-hide @anchor{using/InvokingGHDL cmdoption-ghdl-warn-hide}@anchor{f8} @deffn {Option} @w{-}@w{-}warn@w{-}hide Emit a warning when a declaration hides a previous hide. @end deffn @geindex ghdl command line option; --warn-unused @anchor{using/InvokingGHDL cmdoption-ghdl-warn-unused}@anchor{f9} @deffn {Option} @w{-}@w{-}warn@w{-}unused Emit a warning when a subprogram is never used. @end deffn @geindex ghdl command line option; --warn-others @anchor{using/InvokingGHDL cmdoption-ghdl-warn-others}@anchor{fa} @deffn {Option} @w{-}@w{-}warn@w{-}others Emit a warning is an @cite{others} choice is not required because all the choices have been explicitly covered. @end deffn @geindex ghdl command line option; --warn-pure @anchor{using/InvokingGHDL cmdoption-ghdl-warn-pure}@anchor{fb} @deffn {Option} @w{-}@w{-}warn@w{-}pure Emit a warning when a pure rules is violated (like declaring a pure function with access parameters). @end deffn @geindex ghdl command line option; --warn-static @anchor{using/InvokingGHDL cmdoption-ghdl-warn-static}@anchor{fc} @deffn {Option} @w{-}@w{-}warn@w{-}static Emit a warning when a non-static expression is used at a place where the standard requires a static expression. @end deffn @geindex ghdl command line option; --warn-error @anchor{using/InvokingGHDL cmdoption-ghdl-warn-error}@anchor{fd} @deffn {Option} @w{-}@w{-}warn@w{-}error When this option is set, warnings are considered as errors. @end deffn @node Diagnostics Control,Library commands,Warnings,Invoking GHDL @anchor{using/InvokingGHDL diagnostics-control}@anchor{fe} @section Diagnostics Control @geindex ghdl command line option; -fcolor-diagnostics @anchor{using/InvokingGHDL cmdoption-ghdl-fcolor-diagnostics}@anchor{ff} @deffn {Option} @w{-}fcolor@w{-}diagnostics @end deffn @geindex ghdl command line option; -fno-color-diagnostics @anchor{using/InvokingGHDL cmdoption-ghdl-fno-color-diagnostics}@anchor{100} @deffn {Option} @w{-}fno@w{-}color@w{-}diagnostics Control whether diagnostic messages are displayed in color. The default is on when the standard output is a terminal. @end deffn @geindex ghdl command line option; -fdiagnostics-show-option @anchor{using/InvokingGHDL cmdoption-ghdl-fdiagnostics-show-option}@anchor{101} @deffn {Option} @w{-}fdiagnostics@w{-}show@w{-}option @end deffn @geindex ghdl command line option; -fno-diagnostics-show-option @anchor{using/InvokingGHDL cmdoption-ghdl-fno-diagnostics-show-option}@anchor{102} @deffn {Option} @w{-}fno@w{-}diagnostics@w{-}show@w{-}option Control whether the warning option is displayed at the end of warning messages, so that the user can easily know how to disable it. @end deffn @geindex ghdl command line option; -fcaret-diagnostics @anchor{using/InvokingGHDL cmdoption-ghdl-fcaret-diagnostics}@anchor{103} @deffn {Option} @w{-}fcaret@w{-}diagnostics @end deffn @geindex ghdl command line option; -fno-caret-diagnostics @anchor{using/InvokingGHDL cmdoption-ghdl-fno-caret-diagnostics}@anchor{104} @deffn {Option} @w{-}fno@w{-}caret@w{-}diagnostics Control whether the source line of the error is displayed with a caret indicating the column of the error. @end deffn @node Library commands,VPI/VHPI build commands,Diagnostics Control,Invoking GHDL @anchor{using/InvokingGHDL library-commands}@anchor{105} @section Library commands @anchor{using/InvokingGHDL create-a-library}@anchor{106} @geindex create your own library A new library is created implicitly, by compiling entities (packages etc.) into it: @code{ghdl -a --work=my_custom_lib my_file.vhdl}. A library’s source code is usually stored and compiled into its own directory, that you specify with the @ref{9d,,--workdir} option: @code{ghdl -a --work=my_custom_lib --workdir=my_custom_libdir my_custom_lib_srcdir/my_file.vhdl}. See also the @ref{87,,-P} command line option. Furthermore, GHDL provides a few commands which act on a library: @geindex cmd library directory @geindex ghdl command line option; --dir <[options...] [libs]> @anchor{using/InvokingGHDL cmdoption-ghdl-dir}@anchor{107} @deffn {Option} @w{-}@w{-}dir <[options...] [libs]> @end deffn Displays the content of the design libraries (by default the @code{work} library). All options are allowed, but only a few are meaningful: @ref{86,,--work}, @ref{9d,,--workdir} and @ref{82,,--std}. @geindex cmd library clean @anchor{using/InvokingGHDL clean-command}@anchor{a1} @geindex ghdl command line option; --clean <[options...]> @anchor{using/InvokingGHDL cmdoption-ghdl-clean}@anchor{108} @deffn {Option} @w{-}@w{-}clean <[options...]> @end deffn Try to remove any object, executable or temporary file it could have created. Source files are not removed. The library is kept. @geindex cmd library remove @anchor{using/InvokingGHDL remove-command}@anchor{a2} @geindex ghdl command line option; --remove <[options...]> @anchor{using/InvokingGHDL cmdoption-ghdl-remove}@anchor{109} @deffn {Option} @w{-}@w{-}remove <[options...]> @end deffn Acts like the clean command but removes the library too. Note that after removing a design library, the files are not known anymore by GHDL. @geindex cmd library copy @geindex ghdl command line option; --copy <--work=name [options...]> @anchor{using/InvokingGHDL cmdoption-ghdl-copy}@anchor{10a} @deffn {Option} @w{-}@w{-}copy <@w{-}@w{-}work=name [options...]> @end deffn Make a local copy of an existing library. This is very useful if you want to add units to the @code{ieee} library: @example ghdl --copy --work=ieee --ieee=synopsys ghdl -a --work=ieee numeric_unsigned.vhd @end example @node VPI/VHPI build commands,IEEE library pitfalls,Library commands,Invoking GHDL @anchor{using/InvokingGHDL vpi-build-commands}@anchor{10b}@anchor{using/InvokingGHDL vpi-vhpi-build-commands}@anchor{10c} @section VPI/VHPI build commands These commands simplify the compile and the link of a user VPI or VHPI module. They are all wrappers: the arguments are in fact a whole command line that is executed with additional switches. Currently a unix-like compiler (like @cite{cc}, @cite{gcc} or @cite{clang}) is expected: the additional switches use their syntax. The only option is @cite{-v} which displays the command before its execution. @geindex cmd VPI compile @geindex ghdl command line option; --vpi-compile @anchor{using/InvokingGHDL cmdoption-ghdl-vpi-compile}@anchor{10d} @deffn {Option} @w{-}@w{-}vpi@w{-}compile @end deffn Add an include path to the command and execute it: @example ghdl --vpi-compile command @end example This will execute: @example command -Ixxx/include @end example For example, @code{ghdl --vpi-compile gcc -c vpi1.c} executes @code{gcc -c vpi1.c -fPIC -Ixxx/include}. @anchor{using/InvokingGHDL vpi-link-command}@anchor{10e} @geindex cmd VPI link @geindex ghdl command line option; --vpi-link @anchor{using/InvokingGHDL cmdoption-ghdl-vpi-link}@anchor{10f} @deffn {Option} @w{-}@w{-}vpi@w{-}link @end deffn Add a library path and name to the command and execute it: @example ghdl --vpi-link command @end example This will execute: @example command -Lxxx/lib -lghdlvpi @end example For example, @code{ghdl --vpi-link gcc -o vpi1.vpi vpi1.o} executes @code{gcc -o vpi1.vpi vpi1.o --shared -Lxxx/lib -lghdlvpi}. @anchor{using/InvokingGHDL vpi-cflags-command}@anchor{110} @geindex cmd VPI cflags @geindex ghdl command line option; --vpi-cflags @anchor{using/InvokingGHDL cmdoption-ghdl-vpi-cflags}@anchor{111} @deffn {Option} @w{-}@w{-}vpi@w{-}cflags @end deffn Display flags added by @ref{10d,,--vpi-compile}. @geindex cmd VPI ldflags @geindex ghdl command line option; --vpi-ldflags @anchor{using/InvokingGHDL cmdoption-ghdl-vpi-ldflags}@anchor{112} @deffn {Option} @w{-}@w{-}vpi@w{-}ldflags @end deffn Display flags added by @ref{10f,,--vpi-link}. @geindex cmd VPI include dir @geindex ghdl command line option; --vpi-include-dir @anchor{using/InvokingGHDL cmdoption-ghdl-vpi-include-dir}@anchor{113} @deffn {Option} @w{-}@w{-}vpi@w{-}include@w{-}dir @end deffn Display the include directory added by the compile flags. @geindex cmd VPI library dir @geindex ghdl command line option; --vpi-library-dir @anchor{using/InvokingGHDL cmdoption-ghdl-vpi-library-dir}@anchor{114} @deffn {Option} @w{-}@w{-}vpi@w{-}library@w{-}dir @end deffn Display the library directory added by the link flags. @geindex ghdl command line option; --vpi-library-dir-unix @anchor{using/InvokingGHDL cmdoption-ghdl-vpi-library-dir-unix}@anchor{115} @deffn {Option} @w{-}@w{-}vpi@w{-}library@w{-}dir@w{-}unix @end deffn Display the library directory added by the link flags, forcing UNIX syntax. @node IEEE library pitfalls,,VPI/VHPI build commands,Invoking GHDL @anchor{using/InvokingGHDL id1}@anchor{116}@anchor{using/InvokingGHDL ieee-library-pitfalls}@anchor{67} @section IEEE library pitfalls When you use options @ref{83,,--ieee=synopsys}, the @code{ieee} library contains non standard packages such as @code{std_logic_arith}. These packages are not standard because there are not described by an IEEE standard, even if they have been put in the @cite{IEEE} library. Furthermore, they are not really de-facto standard, because there are slight differences between the packages of Mentor and those of Synopsys. Furthermore, since they are not well thought out, their use has pitfalls. For example, this description has an error during compilation: @example library ieee; use ieee.std_logic_1164.all; -- A counter from 0 to 10. entity counter is port (val : out std_logic_vector (3 downto 0); ck : std_logic; rst : std_logic); end counter; library ieee; use ieee.std_logic_unsigned.all; architecture bad of counter is signal v : std_logic_vector (3 downto 0); begin process (ck, rst) begin if rst = '1' then v <= x"0"; elsif rising_edge (ck) then if v = "1010" then -- Error v <= x"0"; else v <= v + 1; end if; end if; end process; val <= v; end bad; @end example When you analyze this design, GHDL does not accept it (two long lines have been split for readability): @example ghdl -a --ieee=synopsys bad_counter.vhdl bad_counter.vhdl:13:14: operator "=" is overloaded bad_counter.vhdl:13:14: possible interpretations are: ../../libraries/ieee/std_logic_1164.v93:69:5: implicit function "=" [std_logic_vector, std_logic_vector return boolean] ../../libraries/synopsys/std_logic_unsigned.vhdl:64:5: function "=" [std_logic_vector, std_logic_vector return boolean] ../translate/ghdldrv/ghdl: compilation error @end example Indeed, the @cite{“=”} operator is defined in both packages, and both are visible at the place it is used. The first declaration is an implicit one, which occurs when the @cite{std_logic_vector} type is declared and is an element to element comparison. The second one is an explicit declared function, with the semantics of an unsigned comparison. With some analysers, the explicit declaration has priority over the implicit declaration, and this design can be analyzed without error. However, this is not the rule given by the VHDL LRM, and since GHDL follows these rules, it emits an error. You can force GHDL to use this rule with the @emph{-fexplicit} option (see @ref{bf,,Options} for further details). However it is easy to fix this error, by using a selected name: @example library ieee; use ieee.std_logic_unsigned.all; architecture fixed_bad of counter is signal v : std_logic_vector (3 downto 0); begin process (ck, rst) begin if rst = '1' then v <= x"0"; elsif rising_edge (ck) then if ieee.std_logic_unsigned."=" (v, "1010") then v <= x"0"; else v <= v + 1; end if; end if; end process; val <= v; end fixed_bad; @end example It is better to only use the standard packages defined by IEEE, which provide the same functionalities: @example library ieee; use ieee.numeric_std.all; architecture good of counter is signal v : unsigned (3 downto 0); begin process (ck, rst) begin if rst = '1' then v <= x"0"; elsif rising_edge (ck) then if v = "1010" then v <= x"0"; else v <= v + 1; end if; end if; end process; val <= std_logic_vector (v); end good; @end example @geindex Math_Real @geindex Math_Complex @cartouche @quotation Hint The @code{ieee} math packages (@code{math_real} and @code{math_complex}) provided with @cite{GHDL} are fully compliant with the @cite{IEEE} standard. @end quotation @end cartouche @c # Load pre-defined aliases and graphical characters like © from docutils @c # is used to denote the special path @c # \Lib\site-packages\docutils\parsers\rst\include @c This data file has been placed in the public domain. @c Derived from the Unicode character mappings available from @c . @c Processed by unicode2rstsubs.py, part of Docutils: @c . @c This data file has been placed in the public domain. @c Derived from the Unicode character mappings available from @c . @c Processed by unicode2rstsubs.py, part of Docutils: @c . @c # define a hard line break for HTML @node Simulation runtime,Synthesis,Invoking GHDL,Top @anchor{using/Simulation doc}@anchor{117}@anchor{using/Simulation simulation-runtime}@anchor{118}@anchor{using/Simulation using-simulation}@anchor{c4} @chapter Simulation (runtime) @menu * Simulation options:: * Export waveforms:: * Export hierarchy and references:: @end menu @node Simulation options,Export waveforms,,Simulation runtime @anchor{using/Simulation id1}@anchor{119}@anchor{using/Simulation simulation-options}@anchor{9a} @section Simulation options In most system environments, it is possible to pass CLI options while invoking a program. Contrary to most programming languages, there is no standard method in VHDL to obtain the arguments or to set the exit status. However, the GHDL runtime behaviour can be modified with some options: @itemize - @item It is possible to pass parameters to your design through the generic interfaces of the top entity. @item It is also possible to stop simulation after a certain time. The exit status of the simulation is @code{EXIT_SUCCESS} (@code{0}) if the simulation completes, or @code{EXIT_FAILURE} (@code{1}) in case of error (assertion failure, overflow or any constraint error). @end itemize Here is the list of the most useful options. For further info, see @ref{11a,,Debugging}. @cartouche @quotation Hint Note that these arguments are represented as @code{simulation_options...} in this documentation. For analysis/elaboration options, see @ref{5f,,Invoking GHDL}. @end quotation @end cartouche @geindex ghdl command line option; -gGENERIC=VALUE @anchor{using/Simulation cmdoption-ghdl-gGENERIC}@anchor{11b}@anchor{using/Simulation cmdoption-ghdl-ggeneric}@anchor{11c} @deffn {Option} @w{-}gGENERIC=VALUE Set value @cite{VALUE} to generic with name @cite{GENERIC}. Example: @example $ ghdl -r --std=08 my_unit -gDEPTH=12 @end example @cartouche @quotation Note This is currently a run option; but in the (not near) future it might be deprecated to become an elaboration option only. As a result, now you can generate a single binary and execute it multiple times with different arguments. That might not be possible in the future. As explained in @ref{8c,,-e}, performing a complete elaboration in terms of the LRM requires to get rid of the compile and link model. This is mostly because delaying certain elaboration steps to the runtime prevents elaboration-time optimisions. @end quotation @end cartouche @cartouche @quotation Hint Currently, GHDL has limited support for generic types in the CLI. It is suggested to use strings or integers. Nonetheless, project JSON-for-VHDL@footnote{https://github.com/Paebbels/JSON-for-VHDL} allows to encode a set of parameters as stringified JSON, and it provides VHDL functions to read specific values from it. It is valid for synthesis. @end quotation @end cartouche @end deffn @geindex ghdl command line option; --assert-level= @anchor{using/Simulation cmdoption-ghdl-assert-level}@anchor{a0} @deffn {Option} @w{-}@w{-}assert@w{-}level= Select the assertion level at which an assertion violation stops the simulation. @cite{LEVEL} is the name from the @cite{severity_level} enumerated type defined in the @cite{standard} package or the @code{none} name. By default, only assertion violation of severity level @code{failure} stops the simulation. For example, if @cite{LEVEL} was @code{warning}, any assertion violation with severity level @code{warning}, @code{error} or @code{failure} would stop simulation, but the assertion violation at the @code{note} severity level would only display a message. Option @ref{a0,,--assert-level=none} prevents any assertion violation from stopping simulation. @end deffn @geindex ghdl command line option; --backtrace-severity= @anchor{using/Simulation cmdoption-ghdl-backtrace-severity}@anchor{11d} @deffn {Option} @w{-}@w{-}backtrace@w{-}severity= Select the assertion level at which an assertion violation display a backtrace (if available). This is useful when the assertion is generated by a function (like assertions in @code{ieee.numeric_std}) whose location is not very useful. @end deffn @geindex ghdl command line option; --ieee-asserts= @anchor{using/Simulation cmdoption-ghdl-ieee-asserts}@anchor{11e} @deffn {Option} @w{-}@w{-}ieee@w{-}asserts= @end deffn @geindex ghdl command line option; --asserts= @anchor{using/Simulation cmdoption-ghdl-asserts}@anchor{11f} @deffn {Option} @w{-}@w{-}asserts= Select how assertions are handled. @cite{POLICY} can be @code{enable} (the default), @code{disable} which disables all assertions and @code{disable-at-0} which disables only at the start of simulation. The @code{--ieee-asserts} applies only to assertions from @code{ieee} package. This option can be useful to avoid assertion messages from @code{ieee.numeric_std} (and other @code{ieee} packages). The @code{--asserts} option applies to all assertions, including those from the @code{ieee} units. The behaviour of the latter can be overridden by using the @code{--ieee-asserts} option after the @code{--asserts} option. @end deffn @geindex ghdl command line option; --stop-time=