diff options
| author | Tristan Gingold | 2015-11-24 05:25:05 +0100 |
|---|---|---|
| committer | Tristan Gingold | 2015-11-24 05:25:05 +0100 |
| commit | 10c4523636a7b2afbd6401c623edd9d7619f028c (patch) | |
| tree | 35540ca99a9ae902efd806f66c26586340427ded /doc | |
| parent | 60fd762fa36f72b9ddad8cda84b6c16c6936d942 (diff) | |
| download | ghdl-10c4523636a7b2afbd6401c623edd9d7619f028c.tar.gz ghdl-10c4523636a7b2afbd6401c623edd9d7619f028c.tar.bz2 ghdl-10c4523636a7b2afbd6401c623edd9d7619f028c.zip | |
doc: generate ghdl.html and ghdl.texi
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile | 58 | ||||
| -rw-r--r-- | doc/ghdl.html | 2042 | ||||
| -rw-r--r-- | doc/ghdl.texi | 3126 |
3 files changed, 5226 insertions, 0 deletions
diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..41ec46a --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,58 @@ +SRC_FILES= \ + Copyrights.rst \ + Flaws_and_bugs_report.rst \ + GHDL_implementation_of_VHDL.rst \ + GHDL_implementation_of_VITAL.rst \ + Introduction.rst \ + Invoking_GHDL.rst \ + Simulation_and_runtime.rst \ + Starting_with_GHDL.rst \ + index.rst + +CP=cp + +# Sphinx options. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = build + +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +all: ghdl.info + +info: ghdl.info +ghdl.info: ghdl.texi + makeinfo -o $@ $< + +dvi: ghdl.dvi +ghdl.dvi: ghdl.texi + texi2dvi $< + +ghdl.ps: ghdl.dvi + dvips $< + +pdf: ghdl.pdf +ghdl.pdf: ghdl.dvi + dvipdf $< + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + +ghdl.html: $(SRC_FILES) + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + $(CP) $(BUILDDIR)/singlehtml/index.html $@ + +ghdl.texi: $(SRC_FILES) + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + $(CP) $(BUILDDIR)/texinfo/GHDL.texi $@ + +clean: + $(RM) *~ *.dvi *.info ghdl.aux ghdl.cp ghdl.fn ghdl.ky ghdl.log + $(RM) ghdl.pdf ghdl.pg ghdl.toc ghdl.tp ghdl.vr + $(RM) -rf build + +maintainer-clean: clean + $(RM) ghdl.html ghdl.texi diff --git a/doc/ghdl.html b/doc/ghdl.html new file mode 100644 index 0000000..85864d7 --- /dev/null +++ b/doc/ghdl.html @@ -0,0 +1,2042 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>GHDL 0.33 documentation</title> + + <link rel="stylesheet" href="_static/alabaster.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: './', + VERSION: '0.33', + COLLAPSE_INDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/underscore.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <link rel="top" title="None" href="index.html#document-index" /> + + + <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9"> + + </head> + <body role="document"> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <div class="section" id="welcome-to-ghdl-s-documentation"> +<h1>Welcome to GHDL’s documentation!<a class="headerlink" href="#welcome-to-ghdl-s-documentation" title="Permalink to this headline">¶</a></h1> +<p>Contents:</p> +<div class="toctree-wrapper compound"> +<span id="document-Introduction"></span><div class="section" id="introduction"> +<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> +<div class="section" id="content-of-this-manual"> +<h3>Content of this manual<a class="headerlink" href="#content-of-this-manual" title="Permalink to this headline">¶</a></h3> +<p>This manual is the user and reference manual for GHDL. It does not +contain an introduction to VHDL. Thus, the reader should have at least +a basic knowledge of VHDL. A good knowledge of VHDL language reference +manual (usually called LRM) is a plus.</p> +</div> +<div class="section" id="what-is-vhdl"> +<h3>What is <cite>VHDL</cite>?<a class="headerlink" href="#what-is-vhdl" title="Permalink to this headline">¶</a></h3> +<p><cite>VHDL</cite> is an acronym for Very High Speed Integrated Circuit Hardware +Description Language which is a programming language used to describe a +logic circuit by function, data flow behaviour, or structure.</p> +<p><cite>VHDL</cite> <em>is</em> a programming language: although <cite>VHDL</cite> was +not designed for writing general purpose programs, you can write any +algorithm with the <cite>VHDL</cite> language. If you are able to write +programs, you will find in <cite>VHDL</cite> features similar to those found +in procedural languages such as <cite>C</cite>, <cite>Python</cite>, or <cite>Ada</cite>. +<cite>VHDL</cite> derives most of its syntax and semantics from <cite>Ada</cite>. +Knowing <cite>Ada</cite> is an advantage for learning <cite>VHDL</cite> (it is an +advantage in general as well).</p> +<p>However, <cite>VHDL</cite> was not designed as a general purpose language but as an +<cite>HDL</cite> (hardware description language). As the name implies, <cite>VHDL</cite> +aims at modeling or documenting electronics systems. Due to the nature +of hardware components which are always running, <cite>VHDL</cite> is a highly +concurrent language, built upon an event-based timing model.</p> +<p>Like a program written in any other language, a <cite>VHDL</cite> program +can be executed. Since <cite>VHDL</cite> is used to model designs, the term +<em class="dfn">simulation</em> is often used instead of <cite>execution</cite>, with the +same meaning.</p> +<p>Like a program written in another hardware description language, a +<cite>VHDL</cite> program can be transformed with a <em class="dfn">synthesis tool</em> +into a netlist, that is, a detailed gate-level implementation.</p> +</div> +<div class="section" id="what-is-ghdl"> +<h3>What is <cite>GHDL</cite>?<a class="headerlink" href="#what-is-ghdl" title="Permalink to this headline">¶</a></h3> +<p><cite>GHDL</cite> is a shorthand for G Hardware Design Language. Currently, +<cite>G</cite> has no meaning.</p> +<p><cite>GHDL</cite> is a <cite>VHDL</cite> compiler that can execute (nearly) any +<cite>VHDL</cite> program. <cite>GHDL</cite> is <em>not</em> a synthesis tool: you cannot +create a netlist with <cite>GHDL</cite>.</p> +<p>Unlike some other simulators, <cite>GHDL</cite> is a compiler: it directly +translates a <cite>VHDL</cite> file to machine code, using the <cite>GCC</cite> or <cite>LLVM</cite> +back-end and without using an intermediary language such as <cite>C</cite> +or <cite>C++</cite>. Therefore, the compiled code should be faster and +the analysis time should be shorter than with a compiler using an +intermediary language.</p> +<p>The Windows(TM) version of <cite>GHDL</cite> is not based on <cite>GCC</cite> but on +an internal code generator.</p> +<p>The current version of <cite>GHDL</cite> does not contain any graphical +viewer: you cannot see signal waves. You can still check with a test +bench. The current version can produce a <cite>VCD</cite> file which can be +viewed with a wave viewer, as well as <cite>ghw</cite> files to be viewed by +<cite>gtkwave</cite>.</p> +<p><cite>GHDL</cite> aims at implementing <cite>VHDL</cite> as defined by IEEE 1076. +It supports most of the 1987 standard and most features added by the +1993 standard.</p> +</div> +</div> +<span id="document-Starting_with_GHDL"></span><div class="section" id="starting-with-ghdl"> +<h2>Starting with GHDL<a class="headerlink" href="#starting-with-ghdl" title="Permalink to this headline">¶</a></h2> +<p>In this chapter, you will learn how to use the GHDL compiler by +working on two examples.</p> +<div class="section" id="the-hello-world-program"> +<h3>The hello world program<a class="headerlink" href="#the-hello-world-program" title="Permalink to this headline">¶</a></h3> +<p>To illustrate the large purpose of VHDL, here is a commented VHDL +“Hello world” program.</p> +<div class="highlight-VHDL"><div class="highlight"><pre><span class="c1">-- Hello world program.</span> +<span class="k">use</span> <span class="nn">std.textio.all</span><span class="p">;</span> <span class="c1">-- Imports the standard textio package.</span> + +<span class="c1">-- Defines a design entity, without any ports.</span> +<span class="k">entity</span> <span class="nc">hello_world</span> <span class="k">is</span> +<span class="k">end</span> <span class="nc">hello_world</span><span class="p">;</span> + +<span class="k">architecture</span> <span class="nc">behaviour</span> <span class="k">of</span> <span class="nc">hello_world</span> <span class="k">is</span> +<span class="k">begin</span> + <span class="k">process</span> + <span class="k">variable</span> <span class="n">l</span> <span class="o">:</span> <span class="n">line</span><span class="p">;</span> + <span class="k">begin</span> + <span class="n">write</span> <span class="p">(</span><span class="n">l</span><span class="p">,</span> <span class="kt">String</span><span class="p">'(</span><span class="s">"Hello world!"</span><span class="p">));</span> + <span class="n">writeline</span> <span class="p">(</span><span class="n">output</span><span class="p">,</span> <span class="n">l</span><span class="p">);</span> + <span class="k">wait</span><span class="p">;</span> + <span class="k">end</span> <span class="k">process</span><span class="p">;</span> +<span class="k">end</span> <span class="nc">behaviour</span><span class="p">;</span> +</pre></div> +</div> +<p>Suppose this program is contained in the file <code class="file docutils literal"><span class="pre">hello.vhdl</span></code>. +First, you have to compile the file; this is called <cite>analysis</cite> of a design +file in VHDL terms.</p> +<div class="highlight-shell"><div class="highlight"><pre><span class="nv">$ </span>ghdl -a hello.vhdl +</pre></div> +</div> +<p>This command creates or updates a file <code class="file docutils literal"><span class="pre">work-obj93.cf</span></code>, which +describes the library <cite>work</cite>. On GNU/Linux, this command generates a +file <code class="file docutils literal"><span class="pre">hello.o</span></code>, which is the object file corresponding to your +VHDL program. The object file is not created on Windows.</p> +<p>Then, you have to build an executable file.</p> +<div class="highlight-shell"><div class="highlight"><pre><span class="nv">$ </span>ghdl -e hello_world +</pre></div> +</div> +<p>The <code class="xref std std-option docutils literal"><span class="pre">-e</span></code> option means <em class="dfn">elaborate</em>. With this option, <cite>GHDL</cite> +creates code in order to elaborate a design, with the <code class="samp docutils literal"><span class="pre">hello</span></code> +entity at the top of the hierarchy.</p> +<p>On GNU/Linux, the result is an executable program called <code class="file docutils literal"><span class="pre">hello</span></code> +which can be run:</p> +<div class="highlight-shell"><div class="highlight"><pre><span class="nv">$ </span>ghdl -r hello_world +</pre></div> +</div> +<p>or directly:</p> +<div class="highlight-shell"><div class="highlight"><pre><span class="nv">$ </span>./hello_world +</pre></div> +</div> +<p>On Windows, no file is created. The simulation is launched using this command:</p> +<div class="highlight-shell"><div class="highlight"><pre>> ghdl -r hello_world +</pre></div> +</div> +<p>The result of the simulation appears on the screen:</p> +<div class="highlight-python"><div class="highlight"><pre>Hello world! +</pre></div> +</div> +</div> +<div class="section" id="a-full-adder"> +<h3>A full adder<a class="headerlink" href="#a-full-adder" title="Permalink to this headline">¶</a></h3> +<p>VHDL is generally used for hardware design. This example starts with +a full adder described in the <code class="file docutils literal"><span class="pre">adder.vhdl</span></code> file:</p> +<div class="highlight-VHDL"><div class="highlight"><pre><span class="k">entity</span> <span class="nc">adder</span> <span class="k">is</span> + <span class="c1">-- `i0`, `i1` and the carry-in `ci` are inputs of the adder.</span> + <span class="c1">-- `s` is the sum output, `co` is the carry-out.</span> + <span class="k">port</span> <span class="p">(</span><span class="n">i0</span><span class="p">,</span> <span class="n">i1</span> <span class="o">:</span> <span class="k">in</span> <span class="kt">bit</span><span class="p">;</span> <span class="n">ci</span> <span class="o">:</span> <span class="k">in</span> <span class="kt">bit</span><span class="p">;</span> <span class="n">s</span> <span class="o">:</span> <span class="k">out</span> <span class="kt">bit</span><span class="p">;</span> <span class="n">co</span> <span class="o">:</span> <span class="k">out</span> <span class="kt">bit</span><span class="p">);</span> +<span class="k">end</span> <span class="nc">adder</span><span class="p">;</span> + +<span class="k">architecture</span> <span class="nc">rtl</span> <span class="k">of</span> <span class="nc">adder</span> <span class="k">is</span> +<span class="k">begin</span> + <span class="c1">-- This full-adder architecture contains two concurrent assignment.</span> + <span class="c1">-- Compute the sum.</span> + <span class="n">s</span> <span class="o"><=</span> <span class="n">i0</span> <span class="k">xor</span> <span class="n">i1</span> <span class="k">xor</span> <span class="n">ci</span><span class="p">;</span> + <span class="c1">-- Compute the carry.</span> + <span class="n">co</span> <span class="o"><=</span> <span class="p">(</span><span class="n">i0</span> <span class="k">and</span> <span class="n">i1</span><span class="p">)</span> <span class="k">or</span> <span class="p">(</span><span class="n">i0</span> <span class="k">and</span> <span class="n">ci</span><span class="p">)</span> <span class="k">or</span> <span class="p">(</span><span class="n">i1</span> <span class="k">and</span> <span class="n">ci</span><span class="p">);</span> +<span class="k">end</span> <span class="nc">rtl</span><span class="p">;</span> +</pre></div> +</div> +<p>You can analyze this design file:</p> +<div class="highlight-shell"><div class="highlight"><pre><span class="nv">$ </span>ghdl -a adder.vhdl +</pre></div> +</div> +<p>You can try to execute the <cite>adder</cite> design, but this is useless, +since nothing externally visible will happen. In order to +check this full adder, a testbench has to be run. This testbench 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. The file <code class="file docutils literal"><span class="pre">adder_tb.vhdl</span></code> contains the testbench for +the adder:</p> +<div class="highlight-VHDL"><div class="highlight"><pre><span class="c1">-- A testbench has no ports.</span> +<span class="k">entity</span> <span class="nc">adder_tb</span> <span class="k">is</span> +<span class="k">end</span> <span class="nc">adder_tb</span><span class="p">;</span> + +<span class="k">architecture</span> <span class="nc">behav</span> <span class="k">of</span> <span class="nc">adder_tb</span> <span class="k">is</span> + <span class="c1">-- Declaration of the component that will be instantiated.</span> + <span class="k">component</span> <span class="nc">adder</span> + <span class="k">port</span> <span class="p">(</span><span class="n">i0</span><span class="p">,</span> <span class="n">i1</span> <span class="o">:</span> <span class="k">in</span> <span class="kt">bit</span><span class="p">;</span> <span class="n">ci</span> <span class="o">:</span> <span class="k">in</span> <span class="kt">bit</span><span class="p">;</span> <span class="n">s</span> <span class="o">:</span> <span class="k">out</span> <span class="kt">bit</span><span class="p">;</span> <span class="n">co</span> <span class="o">:</span> <span class="k">out</span> <span class="kt">bit</span><span class="p">);</span> + <span class="k">end</span> <span class="k">component</span><span class="p">;</span> + + <span class="c1">-- Specifies which entity is bound with the component.</span> + <span class="k">for</span> <span class="n">adder_0</span><span class="o">:</span> <span class="n">adder</span> <span class="k">use</span> <span class="k">entity</span> <span class="n">work</span><span class="p">.</span><span class="n">adder</span><span class="p">;</span> + <span class="k">signal</span> <span class="n">i0</span><span class="p">,</span> <span class="n">i1</span><span class="p">,</span> <span class="n">ci</span><span class="p">,</span> <span class="n">s</span><span class="p">,</span> <span class="n">co</span> <span class="o">:</span> <span class="kt">bit</span><span class="p">;</span> +<span class="k">begin</span> + <span class="c1">-- Component instantiation.</span> + <span class="n">adder_0</span><span class="o">:</span> <span class="n">adder</span> <span class="k">port</span> <span class="k">map</span> <span class="p">(</span><span class="n">i0</span> <span class="o">=></span> <span class="n">i0</span><span class="p">,</span> <span class="n">i1</span> <span class="o">=></span> <span class="n">i1</span><span class="p">,</span> <span class="n">ci</span> <span class="o">=></span> <span class="n">ci</span><span class="p">,</span> + <span class="n">s</span> <span class="o">=></span> <span class="n">s</span><span class="p">,</span> <span class="n">co</span> <span class="o">=></span> <span class="n">co</span><span class="p">);</span> + + <span class="c1">-- This process does the real job.</span> + <span class="k">process</span> + <span class="k">type</span> <span class="n">pattern_type</span> <span class="k">is</span> <span class="k">record</span> + <span class="c1">-- The inputs of the adder.</span> + <span class="n">i0</span><span class="p">,</span> <span class="n">i1</span><span class="p">,</span> <span class="n">ci</span> <span class="o">:</span> <span class="kt">bit</span><span class="p">;</span> + <span class="c1">-- The expected outputs of the adder.</span> + <span class="n">s</span><span class="p">,</span> <span class="n">co</span> <span class="o">:</span> <span class="kt">bit</span><span class="p">;</span> + <span class="k">end</span> <span class="k">record</span><span class="p">;</span> + <span class="c1">-- The patterns to apply.</span> + <span class="k">type</span> <span class="n">pattern_array</span> <span class="k">is</span> <span class="k">array</span> <span class="p">(</span><span class="kt">natural</span> <span class="k">range</span> <span class="o"><></span><span class="p">)</span> <span class="k">of</span> <span class="n">pattern_type</span><span class="p">;</span> + <span class="k">constant</span> <span class="n">patterns</span> <span class="o">:</span> <span class="n">pattern_array</span> <span class="o">:=</span> + <span class="p">((</span><span class="sc">'0'</span><span class="p">,</span> <span class="sc">'0'</span><span class="p">,</span> <span class="sc">'0'</span><span class="p">,</span> <span class="sc">'0'</span><span class="p">,</span> <span class="sc">'0'</span><span class="p">),</span> + <span class="p">(</span><span class="sc">'0'</span><span class="p">,</span> <span class="sc">'0'</span><span class="p">,</span> <span class="sc">'1'</span><span class="p">,</span> <span class="sc">'1'</span><span class="p">,</span> <span class="sc">'0'</span><span class="p">),</span> + <span class="p">(</span><span class="sc">'0'</span><span class="p">,</span> <span class="sc">'1'</span><span class="p">,</span> <span class="sc">'0'</span><span class="p">,</span> <span class="sc">'1'</span><span class="p">,</span> <span class="sc">'0'</span><span class="p">),</span> + <span class="p">(</span><span class="sc">'0'</span><span class="p">,</span> <span class="sc">'1'</span><span class="p">,</span> <span class="sc">'1'</span><span class="p">,</span> <span class="sc">'0'</span><span class="p">,</span> <span class="sc">'1'</span><span class="p">),</span> + <span class="p">(</span><span class="sc">'1'</span><span class="p">,</span> <span class="sc">'0'</span><span class="p">,</span> <span class="sc">'0'</span><span class="p">,</span> <span class="sc">'1'</span><span class="p">,</span> <span class="sc">'0'</span><span class="p">),</span> + <span class="p">(</span><span class="sc">'1'</span><span class="p">,</span> <span class="sc">'0'</span><span class="p">,</span> <span class="sc">'1'</span><span class="p">,</span> <span class="sc">'0'</span><span class="p">,</span> <span class="sc">'1'</span><span class="p">),</span> + <span class="p">(</span><span class="sc">'1'</span><span class="p">,</span> <span class="sc">'1'</span><span class="p">,</span> <span class="sc">'0'</span><span class="p">,</span> <span class="sc">'0'</span><span class="p">,</span> <span class="sc">'1'</span><span class="p">),</span> + <span class="p">(</span><span class="sc">'1'</span><span class="p">,</span> <span class="sc">'1'</span><span class="p">,</span> <span class="sc">'1'</span><span class="p">,</span> <span class="sc">'1'</span><span class="p">,</span> <span class="sc">'1'</span><span class="p">));</span> + <span class="k">begin</span> + <span class="c1">-- Check each pattern.</span> + <span class="k">for</span> <span class="n">i</span> <span class="k">in</span> <span class="n">patterns</span><span class="na">'range</span> <span class="k">loop</span> + <span class="c1">-- Set the inputs.</span> + <span class="n">i0</span> <span class="o"><=</span> <span class="n">patterns</span><span class="p">(</span><span class="n">i</span><span class="p">).</span><span class="n">i0</span><span class="p">;</span> + <span class="n">i1</span> <span class="o"><=</span> <span class="n">patterns</span><span class="p">(</span><span class="n">i</span><span class="p">).</span><span class="n">i1</span><span class="p">;</span> + <span class="n">ci</span> <span class="o"><=</span> <span class="n">patterns</span><span class="p">(</span><span class="n">i</span><span class="p">).</span><span class="n">ci</span><span class="p">;</span> + <span class="c1">-- Wait for the results.</span> + <span class="k">wait</span> <span class="k">for</span> <span class="mi">1</span> <span class="n">ns</span><span class="p">;</span> + <span class="c1">-- Check the outputs.</span> + <span class="k">assert</span> <span class="n">s</span> <span class="o">=</span> <span class="n">patterns</span><span class="p">(</span><span class="n">i</span><span class="p">).</span><span class="n">s</span> + <span class="n">report</span> <span class="s">"bad sum value"</span> <span class="k">severity</span> <span class="n">error</span><span class="p">;</span> + <span class="k">assert</span> <span class="n">co</span> <span class="o">=</span> <span class="n">patterns</span><span class="p">(</span><span class="n">i</span><span class="p">).</span><span class="n">co</span> + <span class="n">report</span> <span class="s">"bad carray out value"</span> <span class="k">severity</span> <span class="n">error</span><span class="p">;</span> + <span class="k">end</span> <span class="k">loop</span><span class="p">;</span> + <span class="k">assert</span> <span class="n">false</span> <span class="n">report</span> <span class="s">"end of test"</span> <span class="k">severity</span> <span class="n">note</span><span class="p">;</span> + <span class="c1">-- Wait forever; this will finish the simulation.</span> + <span class="k">wait</span><span class="p">;</span> + <span class="k">end</span> <span class="k">process</span><span class="p">;</span> +<span class="k">end</span> <span class="nc">behav</span><span class="p">;</span> +</pre></div> +</div> +<p>As usual, you should analyze the design:</p> +<div class="highlight-shell"><div class="highlight"><pre><span class="nv">$ </span>ghdl -a adder_tb.vhdl +</pre></div> +</div> +<p>And build an executable for the testbench:</p> +<div class="highlight-shell"><div class="highlight"><pre><span class="nv">$ </span>ghdl -e adder_tb +</pre></div> +</div> +<p>You do not need to specify which object files are required: GHDL knows them +and automatically adds them in the executable. Now, it is time to run the +testbench:</p> +<div class="highlight-shell"><div class="highlight"><pre><span class="nv">$ </span>ghdl -r adder_tb +adder_tb.vhdl:52:7:<span class="o">(</span>assertion note<span class="o">)</span>: end of <span class="nb">test</span> +</pre></div> +</div> +<p>If your design is rather complex, you’d like to inspect signals. Signals +value can be dumped using the VCD file format. The resulting file can be +read with a wave viewer such as GTKWave. First, you should simulate your +design and dump a waveform file:</p> +<div class="highlight-shell"><div class="highlight"><pre><span class="nv">$ </span>ghdl -r adder_tb --vcd<span class="o">=</span>adder.vcd +</pre></div> +</div> +<p>Then, you may now view the waves:</p> +<div class="highlight-shell"><div class="highlight"><pre><span class="nv">$ </span>gtkwave adder.vcd +</pre></div> +</div> +<p>See <a class="reference internal" href="index.html#simulation-options"><span>Simulation options</span></a>, for more details on the <a class="reference internal" href="index.html#cmdoption--vcd"><code class="xref std std-option docutils literal"><span class="pre">--vcd</span></code></a> option and +other runtime options.</p> +</div> +<div class="section" id="starting-with-a-design"> +<h3>Starting with a design<a class="headerlink" href="#starting-with-a-design" title="Permalink to this headline">¶</a></h3> +<p>Unless you are only studying VHDL, you will work with bigger designs than +the ones of the previous examples.</p> +<p>Let’s see how to analyze and run a bigger 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 on +<a class="reference external" href="http://ghdl.free.fr/dlx.tar.gz">http://ghdl.free.fr/dlx.tar.gz</a></p> +<p>First, untar the sources:</p> +<div class="highlight-shell"><div class="highlight"><pre><span class="nv">$ </span>tar zxvf dlx.tar.gz +</pre></div> +</div> +<p>In order not to pollute the sources with the library, it is a good idea +to create a <code class="file docutils literal"><span class="pre">work/</span></code> subdirectory for the <cite>WORK</cite> library. To +any GHDL commands, we will add the <code class="xref std std-option docutils literal"><span class="pre">--workdir=work</span></code> option, so +that all files generated by the compiler (except the executable) will be +placed in this directory.</p> +<div class="highlight-shell"><div class="highlight"><pre><span class="nv">$ </span><span class="nb">cd </span>dlx +<span class="nv">$ </span>mkdir work +</pre></div> +</div> +<p>We will run the <code class="samp docutils literal"><span class="pre">dlx_test_behaviour</span></code> design. We need to analyze +all the design units for the design hierarchy, in the correct order. +GHDL provides an easy way to do this, by importing the sources:</p> +<div class="highlight-shell"><div class="highlight"><pre><span class="nv">$ </span>ghdl -i --workdir<span class="o">=</span>work *.vhdl +</pre></div> +</div> +<p>and making a design:</p> +<div class="highlight-shell"><div class="highlight"><pre><span class="nv">$ </span>ghdl -m --workdir<span class="o">=</span>work dlx_test_behaviour +</pre></div> +</div> +<p>Before this second stage, GHDL knows all the design units of the DLX, +but no one have been analyzed. The make command of GHDL analyzes and +elaborates a design. This creates many files in the <code class="file docutils literal"><span class="pre">work/</span></code> +directory, and the <code class="file docutils literal"><span class="pre">dlx_test_behaviour</span></code> executable in the current +directory.</p> +<p>The simulation needs to have a DLX program contained in the file +<code class="file docutils literal"><span class="pre">dlx.out</span></code>. This memory image will be be loaded in the DLX memory. +Just take one sample:</p> +<div class="highlight-shell"><div class="highlight"><pre><span class="nv">$ </span>cp test_loop.out dlx.out +</pre></div> +</div> +<p>And you can run the test suite:</p> +<div class="highlight-shell"><div class="highlight"><pre><span class="nv">$ </span>ghdl -r dlx_test_behaviour +</pre></div> +</div> +<p>The test bench monitors the bus and displays each instruction executed. +It finishes with an assertion of severity level note:</p> +<div class="highlight-shell"><div class="highlight"><pre>dlx-behaviour.vhdl:395:11:<span class="o">(</span>assertion note<span class="o">)</span>: TRAP instruction + encountered, execution halted +</pre></div> +</div> +<p>Since the clock is still running, you have to manually stop the program +with the <code class="kbd docutils literal"><span class="pre">C-c</span></code> key sequence. This behavior prevents you from running the +test bench in batch mode. However, you may force the simulator to +stop when an assertion above or equal a certain severity level occurs:</p> +<div class="highlight-shell"><div class="highlight"><pre><span class="nv">$ </span>ghdl -r dlx_test_behaviour --assert-level<span class="o">=</span>note +</pre></div> +</div> +<p>With this option, the program stops just after the previous message:</p> +<div class="highlight-python"><div class="highlight"><pre>dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction + encountered, execution halted +error: assertion failed +</pre></div> +</div> +<p>If you want to make room on your hard drive, you can either:</p> +<ul> +<li><p class="first">clean the design library with the GHDL command:</p> +<div class="highlight-shell"><div class="highlight"><pre><span class="nv">$ </span>ghdl --clean --workdir<span class="o">=</span>work +</pre></div> +</div> +<p>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.</p> +</li> +<li><p class="first">remove the design library with the GHDL command:</p> +<div class="highlight-shell"><div class="highlight"><pre><span class="nv">$ </span>ghdl --remove --workdir<span class="o">=</span>work +</pre></div> +</div> +<p>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 to make the design.</p> +</li> +<li><p class="first">remove the <code class="file docutils literal"><span class="pre">work/</span></code> directory:</p> +<div class="highlight-shell"><div class="highlight"><pre><span class="nv">$ </span>rm -rf work +</pre></div> +</div> +<p>Only the executable is kept. If you want to rebuild the design, create +the <code class="file docutils literal"><span class="pre">work/</span></code> directory, import the sources, and make the design.</p> +</li> +</ul> +<p>Sometimes, a design does not fully follow the VHDL standards. For example it +uses the badly engineered <code class="samp docutils literal"><span class="pre">std_logic_unsigned</span></code> package. GHDL supports +this VHDL dialect through some options:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="o">--</span><span class="n">ieee</span><span class="o">=</span><span class="n">synopsys</span> <span class="o">-</span><span class="n">fexplicit</span> +</pre></div> +</div> +<p>See <a class="reference internal" href="index.html#ieee-library-pitfalls"><span>IEEE library pitfalls</span></a>, for more details.</p> +</div> +</div> +<span id="document-Invoking_GHDL"></span><div class="section" id="invoking-ghdl"> +<h2>Invoking GHDL<a class="headerlink" href="#invoking-ghdl" title="Permalink to this headline">¶</a></h2> +<p>The form of the <strong class="program">ghdl</strong> command is:</p> +<div class="highlight-python"><div class="highlight"><pre>ghdl command [options...] +</pre></div> +</div> +<p>The GHDL program has several commands. The first argument selects +the command. The options are used to slightly modify the action.</p> +<p>No option is allowed before the command. Except for the run command, +no option is allowed after a filename or a unit name.</p> +<div class="section" id="building-commands"> +<h3>Building commands<a class="headerlink" href="#building-commands" title="Permalink to this headline">¶</a></h3> +<p>The mostly used commands of GHDL are those to analyze and elaborate a design.</p> +<div class="section" id="analysis-command"> +<h4>Analysis command<a class="headerlink" href="#analysis-command" title="Permalink to this headline">¶</a></h4> +<span class="target" id="index-0"></span><p id="index-1">Analyze one or severals files:</p> +<div class="highlight-python"><div class="highlight"><pre>ghdl -a [options...] file... +</pre></div> +</div> +<p>The analysis command compiles one or more files, and creates an +object file for each source file. The analysis command is selected with +<code class="xref std std-option docutils literal"><span class="pre">-a</span></code> switch. 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 (the following files are not analyzed).</p> +<p>See <a class="reference internal" href="#ghdl-options"><span>GHDL options</span></a>, for details on the GHDL options. For example, +to produce debugging information such as line numbers, use:</p> +<div class="highlight-python"><div class="highlight"><pre>ghdl -a -g my_design.vhdl +</pre></div> +</div> +</div> +<div class="section" id="elaboration-command"> +<span id="id1"></span><h4>Elaboration command<a class="headerlink" href="#elaboration-command" title="Permalink to this headline">¶</a></h4> +<span class="target" id="index-2"></span><p id="index-3">Elaborate a design:</p> +<div class="highlight-python"><div class="highlight"><pre>ghdl -e [options..] primary_unit [secondary_unit] +</pre></div> +</div> +<p>On GNU/Linux the elaboration command creates an executable +containing the code of the <cite>VHDL</cite> sources, the elaboration code +and simulation code to execute a design hierarchy. On Windows this +command elaborates the design but does not generate anything.</p> +<p>The elaboration command is selected with <code class="xref std std-option docutils literal"><span class="pre">-e</span></code> switch, and must be +followed by either:</p> +<ul class="simple"> +<li>a name of a configuration unit</li> +<li>a name of an entity unit</li> +<li>a name of an entity unit followed by a name of an architecture unit</li> +</ul> +<p>Name of the units must be a simple name, without any dot. You can +select the name of the <cite>WORK</cite> library with the <code class="xref std std-option docutils literal"><span class="pre">--work=NAME</span></code> +option, as described in <a class="reference internal" href="#ghdl-options"><span>GHDL options</span></a>.</p> +<p>See <a class="reference internal" href="index.html#top-entity"><span>Top entity</span></a>, for the restrictions on the root design of a +hierarchy.</p> +<p>On GNU/Linux the filename of the executable is the name of the +primary unit, or for the later case, the concatenation of the name of +the primary unit, a dash, and the name of the secondary unit (or +architecture). On Windows there is no executable generated.</p> +<p>The <code class="xref std std-option docutils literal"><span class="pre">-o</span></code> followed by a filename can override the default +executable filename.</p> +<p>For the elaboration command, <cite>GHDL</cite> 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 objects files +required for the executable. Then, it links all these files with the +runtime library.</p> +<p>The actual elaboration is performed at runtime.</p> +<p>On Windows this command can be skipped because it is also done by the +run command.</p> +</div> +<div class="section" id="run-command"> +<span id="id2"></span><h4>Run command<a class="headerlink" href="#run-command" title="Permalink to this headline">¶</a></h4> +<span class="target" id="index-4"></span><p id="index-5">Run (or simulate) a design:</p> +<div class="highlight-python"><div class="highlight"><pre>ghdl -r [options...] primary_unit [secondary_unit] [simulation_options...] +</pre></div> +</div> +<p>The options and arguments are the same as for the elaboration command, <a class="reference internal" href="#elaboration-command"><span>Elaboration command</span></a>.</p> +<p>On GNU/Linux this command simply determines the filename of the executable +and executes it. Options are ignored. You may also directly execute +the program.</p> +<p>This command exists for three reasons:</p> +<ul class="simple"> +<li>You don’t have to create the executable program name.</li> +<li>It is coherent with the <code class="xref std std-option docutils literal"><span class="pre">-a</span></code> and <code class="xref std std-option docutils literal"><span class="pre">-e</span></code> commands.</li> +<li>It works with the Windows implementation, where the code is generated in +memory.</li> +</ul> +<p>On Windows this command elaborates and launches the simulation. As a consequence +you must use the same options used during analysis.</p> +<p>See <a class="reference internal" href="index.html#simulation-and-runtime"><span>Simulation and runtime</span></a>, for details on options.</p> +</div> +<div class="section" id="elaborate-and-run-command"> +<h4>Elaborate and run command<a class="headerlink" href="#elaborate-and-run-command" title="Permalink to this headline">¶</a></h4> +<span class="target" id="index-6"></span><p id="index-7">Elaborate and then simulate a design unit:</p> +<div class="highlight-python"><div class="highlight"><pre>ghdl --elab-run [elab_options...] primary_unit [secondary_unit] [run_options...] +</pre></div> +</div> +<p>This command acts like the elaboration command (see <a class="reference internal" href="#elaboration-command"><span>Elaboration command</span></a>) +followed by the run command (see <a class="reference internal" href="#run-command"><span>Run command</span></a>).</p> +</div> +<div class="section" id="bind-command"> +<span id="id3"></span><h4>Bind command<a class="headerlink" href="#bind-command" title="Permalink to this headline">¶</a></h4> +<span class="target" id="index-8"></span><p id="index-9">Bind a design unit and prepare the link step:</p> +<div class="highlight-python"><div class="highlight"><pre>ghdl --bind [options] primary_unit [secondary_unit] +</pre></div> +</div> +<p>This command is only available on GNU/Linux.</p> +<p>This performs only the first stage of the elaboration command; the list +of objects files is created but the executable is not built. This +command should be used only when the main entry point is not ghdl.</p> +</div> +<div class="section" id="link-command"> +<span id="id4"></span><h4>Link command<a class="headerlink" href="#link-command" title="Permalink to this headline">¶</a></h4> +<span class="target" id="index-10"></span><p id="index-11">Link an already bound design unit:</p> +<div class="highlight-python"><div class="highlight"><pre>ghdl --link [options] primary_unit [secondary_unit] +</pre></div> +</div> +<p>This performs only the second stage of the elaboration command: the +executable is created by linking the files of the object files list. +This command is available only for completeness. The elaboration command is +equivalent to the bind command followed by the link command.</p> +</div> +<div class="section" id="list-link-command"> +<span id="id5"></span><h4>List link command<a class="headerlink" href="#list-link-command" title="Permalink to this headline">¶</a></h4> +<p id="index-12">Display files which will be linked:</p> +<div class="highlight-python"><div class="highlight"><pre>ghdl --list-link primary_unit [secondary_unit] +</pre></div> +</div> +<p>This command is only available on GNU/Linux.</p> +<p>This command may be used only after a bind command. GHDL displays all +the files which will be linked to create an executable. This command is +intended to add object files in a link of a foreign program.</p> +</div> +<div class="section" id="check-syntax-command"> +<span id="id6"></span><h4>Check syntax command<a class="headerlink" href="#check-syntax-command" title="Permalink to this headline">¶</a></h4> +<span class="target" id="index-13"></span><p id="index-14">Analyze files but do not generate code:</p> +<div class="highlight-python"><div class="highlight"><pre>ghdl -s [options] files +</pre></div> +</div> +<p>This command may be used to check the syntax of files. It does not update +the library.</p> +</div> +<div class="section" id="analyze-and-elaborate-command"> +<span id="id7"></span><h4>Analyze and elaborate command<a class="headerlink" href="#analyze-and-elaborate-command" title="Permalink to this headline">¶</a></h4> +<span class="target" id="index-15"></span><p id="index-16">Analyze files and elaborate them at the same time.</p> +<p>On GNU/Linux:</p> +<div class="highlight-python"><div class="highlight"><pre>ghdl -c [options] file... -e primary_unit [secondary_unit] +</pre></div> +</div> +<p>On Windows:</p> +<div class="highlight-python"><div class="highlight"><pre>ghdl -c [options] file... -r primary_unit [secondary_unit] +</pre></div> +</div> +<p>This command combines analysis and elaboration: files are analyzed and +the unit is then elaborated. However, code is only generated during the +elaboration. On Windows the simulation is launched.</p> +<p>To be more precise, the files are first parsed, and then the elaboration +drives the analysis. Therefore, there is no analysis order, and you don’t +need to care about it.</p> +<p>All the units of the files are put into the <cite>work</cite> library. But, the +work library is neither read from disk nor saved. Therefore, you must give +all the files of the <cite>work</cite> library your design needs.</p> +<p>The advantages over the traditional approach (analyze and then elaborate) are:</p> +<ul class="simple"> +<li>The compilation cycle is achieved in one command.</li> +<li>Since the files are only parsed once, the compilation cycle may be faster.</li> +<li>You don’t need to know an analysis order</li> +<li>This command produces smaller executable, since unused units and subprograms +do not generate code.</li> +</ul> +<p>However, you should know that currently most of the time is spent in code +generation and the analyze and elaborate command generate code for all units +needed, even units of <code class="samp docutils literal"><span class="pre">std</span></code> and <code class="samp docutils literal"><span class="pre">ieee</span></code> 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.</p> +<p>This command is still experimental. In case of problems, you should go back +to the traditional way.</p> +</div> +</div> +<div class="section" id="ghdl-options"> +<span id="id8"></span><h3>GHDL options<a class="headerlink" href="#ghdl-options" title="Permalink to this headline">¶</a></h3> +<span class="target" id="index-17"></span><span class="target" id="index-18"></span><span class="target" id="index-19"></span><p id="index-20">Besides the options described below, <cite>GHDL</cite> passes any debugging options +(those that begin with <code class="xref std std-option docutils literal"><span class="pre">-g</span></code>) and optimizations options (those that +begin with <code class="xref std std-option docutils literal"><span class="pre">-O</span></code> or <code class="xref std std-option docutils literal"><span class="pre">-f</span></code>) to <cite>GCC</cite>. Refer to the <cite>GCC</cite> +manual for details.</p> +<dl class="option"> +<dt id="cmdoption--workdir"> +<code class="descname">--workdir</code><code class="descclassname">=<DIR></code><a class="headerlink" href="#cmdoption--workdir" title="Permalink to this definition">¶</a></dt> +<dd><p>Specify the directory where the <code class="samp docutils literal"><span class="pre">WORK</span></code> library is located. When this +option is not present, the <code class="samp docutils literal"><span class="pre">WORK</span></code> library is in the current +directory. The object files created by the compiler are always placed +in the same directory as the <code class="samp docutils literal"><span class="pre">WORK</span></code> library.</p> +<p>Use option <a class="reference internal" href="#cmdoption-P"><code class="xref std std-option docutils literal"><span class="pre">-P</span></code></a> to specify where libraries other than <code class="samp docutils literal"><span class="pre">WORK</span></code> +are placed.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption--std"> +<code class="descname">--std</code><code class="descclassname">=<STD></code><a class="headerlink" href="#cmdoption--std" title="Permalink to this definition">¶</a></dt> +<dd><p>Specify the standard to use. By default, the standard is <code class="samp docutils literal"><span class="pre">93c</span></code>, which +means VHDL-93 accepting VHDL-87 syntax. For details on <code class="samp docutils literal"><span class="pre">STD</span></code> values see +<a class="reference internal" href="index.html#vhdl-standards"><span>VHDL standards</span></a>.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption--ieee"> +<code class="descname">--ieee</code><code class="descclassname">=<VER></code><a class="headerlink" href="#cmdoption--ieee" title="Permalink to this definition">¶</a></dt> +<dd><span class="target" id="index-21"></span><span class="target" id="index-22"></span><p id="index-23">Select the <code class="samp docutils literal"><span class="pre">IEEE</span></code> library to use. <code class="samp docutils literal"><span class="pre">VER</span></code> must be one of:</p> +<dl class="docutils"> +<dt>none</dt> +<dd>Do not supply an <cite>IEEE</cite> library. Any library clause with the <code class="samp docutils literal"><span class="pre">IEEE</span></code> +identifier will fail, unless you have created by your own a library with +the <cite>IEEE</cite> name.</dd> +<dt>standard</dt> +<dd>Supply an <cite>IEEE</cite> library containing only packages defined by +<code class="samp docutils literal"><span class="pre">ieee</span></code> standards. Currently, there are the multivalue logic system +packages <code class="samp docutils literal"><span class="pre">std_logic_1164</span></code> defined by IEEE 1164, the synthesis +packages , <code class="samp docutils literal"><span class="pre">numeric_bit</span></code> and <code class="samp docutils literal"><span class="pre">numeric_std</span></code> defined by IEEE +1076.3, and the <code class="samp docutils literal"><span class="pre">vital</span></code> packages <code class="samp docutils literal"><span class="pre">vital_timing</span></code> and +<code class="samp docutils literal"><span class="pre">vital_primitives</span></code>, defined by IEEE 1076.4. The version of these +packages is defined by the VHDL standard used. See <a class="reference internal" href="index.html#vital-packages"><span>VITAL packages</span></a>, +for more details.</dd> +<dt>synopsys</dt> +<dd><p class="first">Supply the former packages and the following additional packages: +<code class="samp docutils literal"><span class="pre">std_logic_arith</span></code>, <code class="samp docutils literal"><span class="pre">std_logic_signed</span></code>, +<code class="samp docutils literal"><span class="pre">std_logic_unsigned</span></code>, <code class="samp docutils literal"><span class="pre">std_logic_textio</span></code>.</p> +<p class="last">These packages were created by some companies, and are popular. However +they are not standard packages, and have been placed in the <cite>IEEE</cite> +library without the permission from the <code class="samp docutils literal"><span class="pre">ieee</span></code>.</p> +</dd> +<dt>mentor</dt> +<dd>Supply the standard packages and the following additional package: +<code class="samp docutils literal"><span class="pre">std_logic_arith</span></code>. The package is a slight variation of a definitely +not standard but widely mis-used package.</dd> +</dl> +<p>To avoid errors, you must use the same <cite>IEEE</cite> library for all units of +your design, and during elaboration.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption-P"> +<code class="descname">-P</code><code class="descclassname"><DIRECTORY></code><a class="headerlink" href="#cmdoption-P" title="Permalink to this definition">¶</a></dt> +<dd><p>Add <cite>DIRECTORY</cite> to the end of the list of directories to be searched for +library files.</p> +<p>The <cite>WORK</cite> library is always searched in the path specified by the +<code class="xref std std-option docutils literal"><span class="pre">--workdir=</span></code> option, or in the current directory if the latter +option is not specified.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption-fexplicit"> +<code class="descname">-fexplicit</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fexplicit" title="Permalink to this definition">¶</a></dt> +<dd><p>When two operators are overloaded, give preference to the explicit declaration. +This may be used to avoid the most common pitfall of the <code class="samp docutils literal"><span class="pre">std_logic_arith</span></code> +package. See <a class="reference internal" href="#ieee-library-pitfalls"><span>IEEE library pitfalls</span></a>, for an example.</p> +<p>This option is not set by default. I 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 better to fix +your design and use the <code class="samp docutils literal"><span class="pre">numeric_std</span></code> package.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption-frelaxed-rules"> +<code class="descname">-frelaxed-rules</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-frelaxed-rules" title="Permalink to this definition">¶</a></dt> +<dd><p>Within an object declaration, allow to reference the name (which +references the hidden declaration). This ignores the error in the +following code:</p> +<div class="highlight-VHDL"><div class="highlight"><pre><span class="k">package</span> <span class="n">pkg1</span> <span class="k">is</span> + <span class="k">type</span> <span class="n">state</span> <span class="k">is</span> <span class="p">(</span><span class="n">state1</span><span class="p">,</span> <span class="n">state2</span><span class="p">,</span> <span class="n">state3</span><span class="p">);</span> +<span class="k">end</span> <span class="nc">pkg1</span><span class="p">;</span> + +<span class="k">use</span> <span class="nn">work.pkg1.all</span><span class="p">;</span> +<span class="k">package</span> <span class="n">pkg2</span> <span class="k">is</span> + <span class="k">constant</span> <span class="n">state1</span> <span class="o">:</span> <span class="n">state</span> <span class="o">:=</span> <span class="n">state1</span><span class="p">;</span> +<span class="k">end</span> <span class="nc">pkg2</span><span class="p">;</span> +</pre></div> +</div> +<p>Some code (such as Xilinx packages) have such constructs, which +are valid.</p> +<p>(The scope of the <code class="samp docutils literal"><span class="pre">state1</span></code> constant start at the <cite>constant</cite> +word. Because the constant <code class="samp docutils literal"><span class="pre">state1</span></code> and the enumeration literal +<code class="samp docutils literal"><span class="pre">state1</span></code> are homograph, the enumeration literal is hidden in the +immediate scope of the constant).</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption-fpsl"> +<code class="descname">-fpsl</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fpsl" title="Permalink to this definition">¶</a></dt> +<dd><p>Enable parsing of PSL assertions within comments. See <a class="reference internal" href="index.html#psl-implementation"><span>PSL implementation</span></a>, +for more details.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption--no-vital-checks"> +<code class="descname">--no-vital-checks</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption--no-vital-checks" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<dl class="option"> +<dt id="cmdoption--vital-checks"> +<code class="descname">--vital-checks</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption--vital-checks" title="Permalink to this definition">¶</a></dt> +<dd><p>Disable or enable checks of restriction on VITAL units. Checks are enabled +by default.</p> +<p>Checks are performed only when a design unit is decorated by a VITAL attribute. +The VITAL attributes are <code class="samp docutils literal"><span class="pre">VITAL_Level0</span></code> and <code class="samp docutils literal"><span class="pre">VITAL_Level1</span></code>, both +declared in the <code class="samp docutils literal"><span class="pre">ieee.VITAL_Timing</span></code> package.</p> +<p>Currently, VITAL checks are only partially implemented. See +<a class="reference internal" href="index.html#vhdl-restrictions-for-vital"><span>VHDL restrictions for VITAL</span></a>, for more details.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption--syn-binding"> +<code class="descname">--syn-binding</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption--syn-binding" title="Permalink to this definition">¶</a></dt> +<dd><p>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.</p> +<p>This rule is known as synthesizer rule.</p> +<p>There are two key points: normal VHDL LRM rules are tried first and +entities are searched only in known library. A known library is a +library which has been named in your design.</p> +<p>This option is only useful during elaboration.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption--PREFIX"> +<code class="descname">--PREFIX</code><code class="descclassname">=<PATH></code><a class="headerlink" href="#cmdoption--PREFIX" title="Permalink to this definition">¶</a></dt> +<dd><p>Use <code class="file docutils literal"><span class="pre">PATH</span></code> as the prefix path to find commands and pre-installed (std and +ieee) libraries.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption--GHDL1"> +<code class="descname">--GHDL1</code><code class="descclassname">=<COMMAND></code><a class="headerlink" href="#cmdoption--GHDL1" title="Permalink to this definition">¶</a></dt> +<dd><p>Use <code class="samp docutils literal"><span class="pre">COMMAND</span></code> as the command name for the compiler. If <code class="samp docutils literal"><span class="pre">COMMAND</span></code> is +not a path, then it is search in the list of program directories.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption-v"> +<code class="descname">-v</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-v" title="Permalink to this definition">¶</a></dt> +<dd><p>Be verbose. For example, for analysis, elaboration and make commands, GHDL +displays the commands executed.</p> +</dd></dl> + +</div> +<div class="section" id="passing-options-to-other-programs"> +<h3>Passing options to other programs<a class="headerlink" href="#passing-options-to-other-programs" title="Permalink to this headline">¶</a></h3> +<p>These options are only available on GNU/Linux.</p> +<p>For many commands, <cite>GHDL</cite> acts as a driver: it invokes programs to perform +the command. You can pass arbitrary options to these programs.</p> +<p>Both the compiler and the linker are in fact GCC programs. See the +GCC manual for details on GCC options.</p> +<dl class="option"> +<dt id="cmdoption-Wc"> +<code class="descname">-Wc</code><code class="descclassname">,<OPTION></code><a class="headerlink" href="#cmdoption-Wc" title="Permalink to this definition">¶</a></dt> +<dd><p>Pass <cite>OPTION</cite> as an option to the compiler.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption-Wa"> +<code class="descname">-Wa</code><code class="descclassname">,<OPTION></code><a class="headerlink" href="#cmdoption-Wa" title="Permalink to this definition">¶</a></dt> +<dd><p>Pass <cite>OPTION</cite> as an option to the assembler.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption-Wl"> +<code class="descname">-Wl</code><code class="descclassname">,<OPTION></code><a class="headerlink" href="#cmdoption-Wl" title="Permalink to this definition">¶</a></dt> +<dd><p>Pass <cite>OPTION</cite> as an option to the linker.</p> +</dd></dl> + +</div> +<div class="section" id="ghdl-warnings"> +<h3>GHDL warnings<a class="headerlink" href="#ghdl-warnings" title="Permalink to this headline">¶</a></h3> +<p>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.</p> +<p>You could disable a warning by using the <code class="samp docutils literal"><span class="pre">--warn-no-XXX</span></code> +instead of <code class="samp docutils literal"><span class="pre">--warn-XXX</span></code>.</p> +<dl class="option"> +<dt id="cmdoption--warn-reserved"> +<code class="descname">--warn-reserved</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption--warn-reserved" title="Permalink to this definition">¶</a></dt> +<dd><p>Emit a warning if an identifier is a reserved word in a later VHDL standard.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption--warn-default-binding"> +<code class="descname">--warn-default-binding</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption--warn-default-binding" title="Permalink to this definition">¶</a></dt> +<dd><p>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 component if you don’t use +configuration. <a class="reference internal" href="index.html#vhdl-standards"><span>VHDL standards</span></a>, for more details about default binding +rules.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption--warn-binding"> +<code class="descname">--warn-binding</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption--warn-binding" title="Permalink to this definition">¶</a></dt> +<dd><p>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.</p> +<p>However, warnings are even 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.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption--warn-library"> +<code class="descname">--warn-library</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption--warn-library" title="Permalink to this definition">¶</a></dt> +<dd><p>Warns if a design unit replaces another design unit with the same name.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption--warn-vital-generic"> +<code class="descname">--warn-vital-generic</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption--warn-vital-generic" title="Permalink to this definition">¶</a></dt> +<dd><p>Warns if a generic name of a vital entity is not a vital generic name. This +is set by default.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption--warn-delayed-checks"> +<code class="descname">--warn-delayed-checks</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption--warn-delayed-checks" title="Permalink to this definition">¶</a></dt> +<dd><p>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</cite> doesn’t read not required +package bodies).</p> +<p>These are checks for no wait statement in a procedure called in a +sensitized process and checks for pure rules of a function.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption--warn-body"> +<code class="descname">--warn-body</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption--warn-body" title="Permalink to this definition">¶</a></dt> +<dd><p>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.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption--warn-specs"> +<code class="descname">--warn-specs</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption--warn-specs" title="Permalink to this definition">¶</a></dt> +<dd><p>Emit a warning if an all or others specification does not apply.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption--warn-unused"> +<code class="descname">--warn-unused</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption--warn-unused" title="Permalink to this definition">¶</a></dt> +<dd><p>Emit a warning when a subprogram is never used.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption--warn-error"> +<code class="descname">--warn-error</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption--warn-error" title="Permalink to this definition">¶</a></dt> +<dd><p>When this option is set, warnings are considered as errors.</p> +</dd></dl> + +</div> +<div class="section" id="rebuilding-commands"> +<h3>Rebuilding commands<a class="headerlink" href="#rebuilding-commands" title="Permalink to this headline">¶</a></h3> +<p>Analyzing and elaborating a design consisting in several files can be tricky, +due to dependencies. GHDL has a few commands to rebuild a design.</p> +<div class="section" id="import-command"> +<h4>Import command<a class="headerlink" href="#import-command" title="Permalink to this headline">¶</a></h4> +<span class="target" id="index-24"></span><p id="index-25">Add files in the work design library:</p> +<div class="highlight-python"><div class="highlight"><pre>ghdl -i [options] file... +</pre></div> +</div> +<p>All the files specified in the command line are scanned, parsed and added in +the libraries but as not yet analyzed. No object files are created.</p> +<p>The purpose of this command 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.</p> +<p>Since the files are parsed, there must be correct files. However, since they +are not analyzed, many errors are tolerated by this command.</p> +<p>Note that all the files are added to the work library. If you have many +libraries, you must use the command for each library.</p> +<p>See <a class="reference internal" href="#make-command"><span>Make command</span></a>, to actually build the design.</p> +</div> +<div class="section" id="make-command"> +<span id="id9"></span><h4>Make command<a class="headerlink" href="#make-command" title="Permalink to this headline">¶</a></h4> +<span class="target" id="index-26"></span><p id="index-27">Analyze automatically outdated files and elaborate a design:</p> +<div class="highlight-python"><div class="highlight"><pre>ghdl -m [options] primary [secondary] +</pre></div> +</div> +<p>The primary unit denoted by the <code class="samp docutils literal"><span class="pre">primary</span></code> 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. GHDL analyzes +all outdated files. A file may be outdated because it has been modified +(e.g. you just have edited it), or because a design unit contained in +the file depends on a unit which is outdated. This rule is of course +recursive.</p> +<p>With the <code class="xref std std-option docutils literal"><span class="pre">-f</span></code> (force) option, GHDL analyzes all the units of the +work library needed to create the design hierarchy. Not outdated units +are recompiled. This is useful if you want to compile a design hierarchy +with new compilation flags (for example, to add the <em>-g</em> +debugging option).</p> +<p>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.</p> +<p>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 file. This command computes an analysis order.</p> +<p>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.</p> +<p>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.</p> +<p>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.</p> +</div> +<div class="section" id="generate-makefile-command"> +<h4>Generate Makefile command<a class="headerlink" href="#generate-makefile-command" title="Permalink to this headline">¶</a></h4> +<p id="index-28">Generate a Makefile to build a design unit:</p> +<div class="highlight-python"><div class="highlight"><pre>ghdl --gen-makefile [options] primary [secondary] +</pre></div> +</div> +<p>This command works like the make command (see <a class="reference internal" href="#make-command"><span>Make command</span></a>), but only a +makefile is generated on the standard output.</p> +</div> +</div> +<div class="section" id="library-commands"> +<h3>Library commands<a class="headerlink" href="#library-commands" title="Permalink to this headline">¶</a></h3> +<p>GHDL has a few commands which act on a library.</p> +<div class="section" id="directory-command"> +<h4>Directory command<a class="headerlink" href="#directory-command" title="Permalink to this headline">¶</a></h4> +<span class="target" id="index-29"></span><p id="index-30">Display the name of the units contained in a design library:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="n">ghdl</span> <span class="o">-</span><span class="n">d</span> <span class="p">[</span><span class="n">options</span><span class="p">]</span> +</pre></div> +</div> +<p>The directory command, selected with the <cite>-d</cite> command line argument +displays the content of the work design library. All options are +allowed, but only a few are meaningful: <code class="xref std std-option docutils literal"><span class="pre">--work=NAME</span></code>, +<code class="xref std std-option docutils literal"><span class="pre">--workdir=PATH</span></code> and <code class="xref std std-option docutils literal"><span class="pre">--std=VER</span></code>.</p> +</div> +<div class="section" id="clean-command"> +<h4>Clean command<a class="headerlink" href="#clean-command" title="Permalink to this headline">¶</a></h4> +<span class="target" id="index-31"></span><p id="index-32">Remove object and executable files but keep the library:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="n">ghdl</span> <span class="o">--</span><span class="n">clean</span> <span class="p">[</span><span class="n">options</span><span class="p">]</span> +</pre></div> +</div> +<p>GHDL tries to remove any object, executable or temporary file it could +have created. Source files are not removed.</p> +<p>There is no short command line form for this option to prevent accidental +clean up.</p> +</div> +<div class="section" id="remove-command"> +<span id="id10"></span><h4>Remove command<a class="headerlink" href="#remove-command" title="Permalink to this headline">¶</a></h4> +<span class="target" id="index-33"></span><p id="index-34">Do like the clean command but remove the library too:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="n">ghdl</span> <span class="o">--</span><span class="n">remove</span> <span class="p">[</span><span class="n">options</span><span class="p">]</span> +</pre></div> +</div> +<p>There is no short command line form for this option to prevent accidental +clean up. Note that after removing a design library, the files are not +known anymore by GHDL.</p> +</div> +<div class="section" id="copy-command"> +<span id="id11"></span><h4>Copy command<a class="headerlink" href="#copy-command" title="Permalink to this headline">¶</a></h4> +<span class="target" id="index-35"></span><p id="index-36">Make a local copy of an existing library:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="n">ghdl</span> <span class="o">--</span><span class="n">copy</span> <span class="o">--</span><span class="n">work</span><span class="o">=</span><span class="n">name</span> <span class="p">[</span><span class="n">options</span><span class="p">]</span> +</pre></div> +</div> +<p>Make a local copy of an existing library. This is very useful if you want to +add unit to the <code class="samp docutils literal"><span class="pre">ieee</span></code> library:</p> +<div class="highlight-shell"><div class="highlight"><pre>ghdl --copy --work<span class="o">=</span>ieee --ieee<span class="o">=</span>synopsys +ghdl -a --work<span class="o">=</span>ieee numeric_unsigned.vhd +</pre></div> +</div> +</div> +<div class="section" id="create-a-library"> +<span id="id12"></span><h4>Create a Library<a class="headerlink" href="#create-a-library" title="Permalink to this headline">¶</a></h4> +<p id="index-37">A new library is created by compiling entities (packages etc.) into it:</p> +<div class="highlight-python"><div class="highlight"><pre>ghdl -a --work=my_custom_lib my_file.vhd +</pre></div> +</div> +<p>A library’s source code is usually stored and compiled into its own directory, +that you specify with the <a class="reference internal" href="#cmdoption--workdir"><code class="xref std std-option docutils literal"><span class="pre">--workdir</span></code></a> option:</p> +<div class="highlight-python"><div class="highlight"><pre>ghdl -a --work=my_custom_lib --workdir=my_custom_libdir my_custom_lib_srcdir/my_file.vhd +</pre></div> +</div> +<p>See also the <code class="xref std std-option docutils literal"><span class="pre">-PPATH</span></code> command line option.</p> +</div> +</div> +<div class="section" id="cross-reference-command"> +<span id="id13"></span><h3>Cross-reference command<a class="headerlink" href="#cross-reference-command" title="Permalink to this headline">¶</a></h3> +<p>To easily navigate through your sources, you may generate cross-references:</p> +<div class="highlight-python"><div class="highlight"><pre>ghdl --xref-html [options] file... +</pre></div> +</div> +<p>This command generates an html file for each <code class="samp docutils literal"><span class="pre">file</span></code> given in the command +line, with syntax highlighting and full cross-reference: every identifier is +a link to its declaration. Besides, an index of the files is created too.</p> +<p>The set of <code class="samp docutils literal"><span class="pre">file</span></code> are analyzed, and then, if the analysis is +successful, html files are generated in the directory specified by the +<code class="xref std std-option docutils literal"><span class="pre">-o</span> <span class="pre">dir</span></code> option, or <code class="file docutils literal"><span class="pre">html/</span></code> directory by default.</p> +<p>If the option <code class="xref std std-option docutils literal"><span class="pre">--format=html2</span></code> is specified, then the generated html +files follow the HTML 2.0 standard, and colours are specified with +<cite><FONT></cite> tags. However, colours are hard-coded.</p> +<p>If the option <code class="xref std std-option docutils literal"><span class="pre">--format=css</span></code> is specified, then the generated html files +follow the HTML 4.0 standard, and use the CSS-1 file <code class="file docutils literal"><span class="pre">ghdl.css</span></code> 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.</p> +</div> +<div class="section" id="file-commands"> +<h3>File commands<a class="headerlink" href="#file-commands" title="Permalink to this headline">¶</a></h3> +<p>The following commands act on one or several files. They do not analyze +files, therefore, they work even if a file has semantic errors.</p> +<div class="section" id="pretty-print-command"> +<h4>Pretty print command<a class="headerlink" href="#pretty-print-command" title="Permalink to this headline">¶</a></h4> +<span class="target" id="index-38"></span><span class="target" id="index-39"></span><p id="index-40">Generate HTML on standard output from VHDL:</p> +<div class="highlight-python"><div class="highlight"><pre>ghdl --pp-html [options] file... +</pre></div> +</div> +<p>The files are just scanned and an html file, with syntax highlighting is +generated on standard output.</p> +<p>Since the files are not even parsed, erroneous files or incomplete designs +can be pretty printed.</p> +<p>The style of the html file can be modified with the <code class="xref std std-option docutils literal"><span class="pre">--format=</span></code> option. +By default or when the <code class="xref std std-option docutils literal"><span class="pre">--format=html2</span></code> option is specified, the output +is an HTML 2.0 file, with colours set through <cite><FONT></cite> tags. When the +<code class="xref std std-option docutils literal"><span class="pre">--format=css</span></code> option is specified, the output is an HTML 4.0 file, +with colours set through a CSS file, whose name is <code class="file docutils literal"><span class="pre">ghdl.css</span></code>. +See <a class="reference internal" href="#cross-reference-command"><span>Cross-reference command</span></a>, for more details about this CSS file.</p> +</div> +<div class="section" id="find-command"> +<h4>Find command<a class="headerlink" href="#find-command" title="Permalink to this headline">¶</a></h4> +<p id="index-41">Display the name of the design units in files:</p> +<div class="highlight-python"><div class="highlight"><pre>ghdl -f file... +</pre></div> +</div> +<p>The files are scanned, parsed and the names of design units are displayed. +Design units marked with two stars are candidate to be at the apex of a +design hierarchy.</p> +</div> +<div class="section" id="chop-command"> +<h4>Chop command<a class="headerlink" href="#chop-command" title="Permalink to this headline">¶</a></h4> +<p id="index-42">Chop (or split) files at design unit:</p> +<div class="highlight-python"><div class="highlight"><pre>ghdl --chop files +</pre></div> +</div> +<p><cite>GHDL</cite> reads files, and writes a file in the current directory for +every design unit.</p> +<p>The filename of a design unit is build according to the unit. For an +entity declaration, a package declaration or a configuration the file +name is <code class="file docutils literal"><span class="pre">NAME.vhdl</span></code>, where <cite>NAME</cite> is the name of the design +unit. For a package body, the filename is <code class="file docutils literal"><span class="pre">NAME-body.vhdl</span></code>. +Finally, for an architecture <cite>ARCH</cite> of an entity <cite>ENTITY</cite>, the +filename is <code class="file docutils literal"><span class="pre">ENTITY-ARCH.vhdl</span></code>.</p> +<p>Since the input files are parsed, this command aborts in case of syntax +error. The command aborts too if a file to be written already exists.</p> +<p>Comments between design units are stored into the most adequate files.</p> +<p>This command may be useful to split big files, if your computer has not +enough memory to compile such files. The size of the executable is +reduced too.</p> +</div> +<div class="section" id="lines-command"> +<h4>Lines command<a class="headerlink" href="#lines-command" title="Permalink to this headline">¶</a></h4> +<p id="index-43">Display on the standard output lines of files preceded by line number:</p> +<div class="highlight-python"><div class="highlight"><pre>ghdl --lines files +</pre></div> +</div> +</div> +</div> +<div class="section" id="misc-commands"> +<h3>Misc commands<a class="headerlink" href="#misc-commands" title="Permalink to this headline">¶</a></h3> +<p>There are a few GHDL commands which are seldom useful.</p> +<div class="section" id="help-command"> +<span id="id14"></span><h4>Help command<a class="headerlink" href="#help-command" title="Permalink to this headline">¶</a></h4> +<span class="target" id="index-44"></span><p id="index-45">Display (on the standard output) a short description of the all the commands +available. If the help switch is followed by a command switch, then options +for this later command are displayed:</p> +<div class="highlight-python"><div class="highlight"><pre>ghdl --help +ghdl -h +ghdl -h command +</pre></div> +</div> +</div> +<div class="section" id="disp-config-command"> +<span id="id15"></span><h4>Disp config command<a class="headerlink" href="#disp-config-command" title="Permalink to this headline">¶</a></h4> +<span class="target" id="index-46"></span><p id="index-47">Display the program paths and options used by GHDL:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="n">ghdl</span> <span class="o">--</span><span class="n">disp</span><span class="o">-</span><span class="n">config</span> <span class="p">[</span><span class="n">options</span><span class="p">]</span> +</pre></div> +</div> +<p>This may be useful to track installation errors.</p> +</div> +<div class="section" id="disp-standard-command"> +<h4>Disp standard command<a class="headerlink" href="#disp-standard-command" title="Permalink to this headline">¶</a></h4> +<span class="target" id="index-48"></span><p id="index-49">Display the <code class="samp docutils literal"><span class="pre">std.standard</span></code> package:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="n">ghdl</span> <span class="o">--</span><span class="n">disp</span><span class="o">-</span><span class="n">standard</span> <span class="p">[</span><span class="n">options</span><span class="p">]</span> +</pre></div> +</div> +</div> +<div class="section" id="version-command"> +<h4>Version command<a class="headerlink" href="#version-command" title="Permalink to this headline">¶</a></h4> +<span class="target" id="index-50"></span><p id="index-51">Display the <cite>GHDL</cite> version and exit:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="n">ghdl</span> <span class="o">--</span><span class="n">version</span> +</pre></div> +</div> +</div> +</div> +<div class="section" id="installation-directory"> +<h3>Installation Directory<a class="headerlink" href="#installation-directory" title="Permalink to this headline">¶</a></h3> +<p>During analysis and elaboration <cite>GHDL</cite> may read the <cite>std</cite> +and <cite>ieee</cite> files. The location of these files is based on the prefix, +which is (in priority order):</p> +<ul class="simple"> +<li>the <code class="xref std std-option docutils literal"><span class="pre">--PREFIX=</span></code> command line option</li> +<li>the <span class="target" id="index-52"></span><code class="xref std std-envvar docutils literal"><span class="pre">GHDL_PREFIX</span></code> environment variable</li> +<li>a built-in default path. It is a hard-coded path on GNU/Linux and the +value of the <code class="samp docutils literal"><span class="pre">HKLMSoftwareGhdlInstall_Dir</span></code> registry entry on Windows.</li> +</ul> +<p>You should use the <code class="xref std std-option docutils literal"><span class="pre">--disp-config</span></code> command (<a class="reference internal" href="#disp-config-command"><span>Disp config command</span></a> for details) to disp and debug installation problems.</p> +</div> +<div class="section" id="ieee-library-pitfalls"> +<span id="id16"></span><h3>IEEE library pitfalls<a class="headerlink" href="#ieee-library-pitfalls" title="Permalink to this headline">¶</a></h3> +<p>When you use options <code class="xref std std-option docutils literal"><span class="pre">--ieee=synopsys</span></code> or <code class="xref std std-option docutils literal"><span class="pre">--ieee=mentor</span></code>, +the <cite>IEEE</cite> library contains non standard packages such as +<code class="samp docutils literal"><span class="pre">std_logic_arith</span></code>.</p> +<p>These packages are not standard because there are not described by an IEEE +standard, even if they have been put in the <cite>IEEE</cite> library. Furthermore, +they are not really de-facto standard, because there are slight differences +between the packages of Mentor and those of Synopsys.</p> +<p>Furthermore, since they are not well-thought, their use has pitfalls. For +example, this description has error during compilation:</p> +<div class="highlight-VHDL"><div class="highlight"><pre><span class="k">library</span> <span class="nn">ieee</span><span class="p">;</span> +<span class="k">use</span> <span class="nn">ieee.std_logic_1164.all</span><span class="p">;</span> + +<span class="c1">-- A counter from 0 to 10.</span> +<span class="k">entity</span> <span class="nc">counter</span> <span class="k">is</span> + <span class="k">port</span> <span class="p">(</span><span class="n">val</span> <span class="o">:</span> <span class="k">out</span> <span class="kt">std_logic_vector</span> <span class="p">(</span><span class="mi">3</span> <span class="k">downto</span> <span class="mi">0</span><span class="p">);</span> + <span class="n">ck</span> <span class="o">:</span> <span class="kt">std_logic</span><span class="p">;</span> + <span class="n">rst</span> <span class="o">:</span> <span class="kt">std_logic</span><span class="p">);</span> +<span class="k">end</span> <span class="nc">counter</span><span class="p">;</span> + +<span class="k">library</span> <span class="nn">ieee</span><span class="p">;</span> +<span class="k">use</span> <span class="nn">ieee.std_logic_unsigned.all</span><span class="p">;</span> + +<span class="k">architecture</span> <span class="nc">bad</span> <span class="k">of</span> <span class="nc">counter</span> +<span class="k">is</span> + <span class="k">signal</span> <span class="n">v</span> <span class="o">:</span> <span class="kt">std_logic_vector</span> <span class="p">(</span><span class="mi">3</span> <span class="k">downto</span> <span class="mi">0</span><span class="p">);</span> +<span class="k">begin</span> + <span class="k">process</span> <span class="p">(</span><span class="n">ck</span><span class="p">,</span> <span class="n">rst</span><span class="p">)</span> + <span class="k">begin</span> + <span class="k">if</span> <span class="n">rst</span> <span class="o">=</span> <span class="sc">'1'</span> <span class="k">then</span> + <span class="n">v</span> <span class="o"><=</span> <span class="mh">x"0"</span><span class="p">;</span> + <span class="k">elsif</span> <span class="n">rising_edge</span> <span class="p">(</span><span class="n">ck</span><span class="p">)</span> <span class="k">then</span> + <span class="k">if</span> <span class="n">v</span> <span class="o">=</span> <span class="s">"1010"</span> <span class="k">then</span> <span class="c1">-- Error</span> + <span class="n">v</span> <span class="o"><=</span> <span class="mh">x"0"</span><span class="p">;</span> + <span class="k">else</span> + <span class="n">v</span> <span class="o"><=</span> <span class="n">v</span> <span class="o">+</span> <span class="mi">1</span><span class="p">;</span> + <span class="k">end</span> <span class="k">if</span><span class="p">;</span> + <span class="k">end</span> <span class="k">if</span><span class="p">;</span> + <span class="k">end</span> <span class="k">process</span><span class="p">;</span> + + <span class="n">val</span> <span class="o"><=</span> <span class="n">v</span><span class="p">;</span> +<span class="k">end</span> <span class="nc">bad</span><span class="p">;</span> +</pre></div> +</div> +<p>When you analyze this design, GHDL does not accept it (too long lines +have been split for readability):</p> +<div class="highlight-shell"><div class="highlight"><pre>ghdl -a --ieee<span class="o">=</span>synopsys bad_counter.vhdl +bad_counter.vhdl:13:14: operator <span class="s2">"="</span> is overloaded +bad_counter.vhdl:13:14: possible interpretations are: +../../libraries/ieee/std_logic_1164.v93:69:5: implicit <span class="k">function</span> <span class="s2">"="</span> + <span class="o">[</span>std_logic_vector, std_logic_vector <span class="k">return</span> boolean<span class="o">]</span> +../../libraries/synopsys/std_logic_unsigned.vhdl:64:5: <span class="k">function</span> <span class="s2">"="</span> + <span class="o">[</span>std_logic_vector, std_logic_vector <span class="k">return</span> boolean<span class="o">]</span> +../translate/ghdldrv/ghdl: compilation error +</pre></div> +</div> +<p>Indeed, the <cite>“=”</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</cite> type is +declared and is an element to element comparison, the second one is an +explicit declared function, with the semantic of an unsigned comparison.</p> +<p>With some analyser, 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.</p> +<p>You can force GHDL to use this rule with the <em>-fexplicit</em> option. +<a class="reference internal" href="#ghdl-options"><span>GHDL options</span></a>, for more details.</p> +<p>However it is easy to fix this error, by using a selected name:</p> +<div class="highlight-VHDL"><div class="highlight"><pre><span class="k">library</span> <span class="nn">ieee</span><span class="p">;</span> +<span class="k">use</span> <span class="nn">ieee.std_logic_unsigned.all</span><span class="p">;</span> + +<span class="k">architecture</span> <span class="nc">fixed_bad</span> <span class="k">of</span> <span class="nc">counter</span> +<span class="k">is</span> + <span class="k">signal</span> <span class="n">v</span> <span class="o">:</span> <span class="kt">std_logic_vector</span> <span class="p">(</span><span class="mi">3</span> <span class="k">downto</span> <span class="mi">0</span><span class="p">);</span> +<span class="k">begin</span> + <span class="k">process</span> <span class="p">(</span><span class="n">ck</span><span class="p">,</span> <span class="n">rst</span><span class="p">)</span> + <span class="k">begin</span> + <span class="k">if</span> <span class="n">rst</span> <span class="o">=</span> <span class="sc">'1'</span> <span class="k">then</span> + <span class="n">v</span> <span class="o"><=</span> <span class="mh">x"0"</span><span class="p">;</span> + <span class="k">elsif</span> <span class="n">rising_edge</span> <span class="p">(</span><span class="n">ck</span><span class="p">)</span> <span class="k">then</span> + <span class="k">if</span> <span class="n">ieee</span><span class="p">.</span><span class="n">std_logic_unsigned</span><span class="p">.</span><span class="s">"=" (v, "1010"</span><span class="p">)</span> <span class="k">then</span> + <span class="n">v</span> <span class="o"><=</span> <span class="mh">x"0"</span><span class="p">;</span> + <span class="k">else</span> + <span class="n">v</span> <span class="o"><=</span> <span class="n">v</span> <span class="o">+</span> <span class="mi">1</span><span class="p">;</span> + <span class="k">end</span> <span class="k">if</span><span class="p">;</span> + <span class="k">end</span> <span class="k">if</span><span class="p">;</span> + <span class="k">end</span> <span class="k">process</span><span class="p">;</span> + + <span class="n">val</span> <span class="o"><=</span> <span class="n">v</span><span class="p">;</span> +<span class="k">end</span> <span class="nc">fixed_bad</span><span class="p">;</span> +</pre></div> +</div> +<p>It is better to only use the standard packages defined by IEEE, which +provides the same functionalities:</p> +<div class="highlight-VHDL"><div class="highlight"><pre><span class="k">library</span> <span class="nn">ieee</span><span class="p">;</span> +<span class="k">use</span> <span class="nn">ieee.numeric_std.all</span><span class="p">;</span> + +<span class="k">architecture</span> <span class="nc">good</span> <span class="k">of</span> <span class="nc">counter</span> +<span class="k">is</span> + <span class="k">signal</span> <span class="n">v</span> <span class="o">:</span> <span class="n">unsigned</span> <span class="p">(</span><span class="mi">3</span> <span class="k">downto</span> <span class="mi">0</span><span class="p">);</span> +<span class="k">begin</span> + <span class="k">process</span> <span class="p">(</span><span class="n">ck</span><span class="p">,</span> <span class="n">rst</span><span class="p">)</span> + <span class="k">begin</span> + <span class="k">if</span> <span class="n">rst</span> <span class="o">=</span> <span class="sc">'1'</span> <span class="k">then</span> + <span class="n">v</span> <span class="o"><=</span> <span class="mh">x"0"</span><span class="p">;</span> + <span class="k">elsif</span> <span class="n">rising_edge</span> <span class="p">(</span><span class="n">ck</span><span class="p">)</span> <span class="k">then</span> + <span class="k">if</span> <span class="n">v</span> <span class="o">=</span> <span class="s">"1010"</span> <span class="k">then</span> + <span class="n">v</span> <span class="o"><=</span> <span class="mh">x"0"</span><span class="p">;</span> + <span class="k">else</span> + <span class="n">v</span> <span class="o"><=</span> <span class="n">v</span> <span class="o">+</span> <span class="mi">1</span><span class="p">;</span> + <span class="k">end</span> <span class="k">if</span><span class="p">;</span> + <span class="k">end</span> <span class="k">if</span><span class="p">;</span> + <span class="k">end</span> <span class="k">process</span><span class="p">;</span> + + <span class="n">val</span> <span class="o"><=</span> <span class="kt">std_logic_vector</span> <span class="p">(</span><span class="n">v</span><span class="p">);</span> +<span class="k">end</span> <span class="nc">good</span><span class="p">;</span> +</pre></div> +</div> +</div> +<div class="section" id="ieee-math-packages"> +<h3>IEEE math packages<a class="headerlink" href="#ieee-math-packages" title="Permalink to this headline">¶</a></h3> +<span class="target" id="index-53"></span><p id="index-54">The <code class="samp docutils literal"><span class="pre">ieee</span></code> math packages (<code class="samp docutils literal"><span class="pre">math_real</span></code> and +<code class="samp docutils literal"><span class="pre">math_complex</span></code>) provided with <cite>GHDL</cite> are fully compliant with +the <cite>IEEE</cite> standard.</p> +</div> +</div> +<span id="document-Simulation_and_runtime"></span><div class="section" id="simulation-and-runtime"> +<span id="id1"></span><h2>Simulation and runtime<a class="headerlink" href="#simulation-and-runtime" title="Permalink to this headline">¶</a></h2> +<div class="section" id="simulation-options"> +<span id="id2"></span><h3>Simulation options<a class="headerlink" href="#simulation-options" title="Permalink to this headline">¶</a></h3> +<p>In most system environments, it is possible to pass 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.</p> +<p>In GHDL, it is impossible to pass parameters to your design. A later version +could do it through the generics interfaces of the top entity.</p> +<p>However, the GHDL runtime behaviour can be modified with some options; for +example, it is possible to stop simulation after a certain time.</p> +<p>The exit status of the simulation is <code class="samp docutils literal"><span class="pre">EXIT_SUCCESS</span></code> (0) if the +simulation completes, or <code class="samp docutils literal"><span class="pre">EXIT_FAILURE</span></code> (1) in case of error +(assertion failure, overflow or any constraint error).</p> +<p>Here is the list of the most useful options. Some debugging options are +also available, but not described here. The <a class="reference internal" href="#cmdoption--help"><code class="xref std std-option docutils literal"><span class="pre">--help</span></code></a> options lists +all options available, including the debugging one.</p> +<dl class="option"> +<dt id="cmdoption--assert-level"> +<code class="descname">--assert-level</code><code class="descclassname">=<LEVEL></code><a class="headerlink" href="#cmdoption--assert-level" title="Permalink to this definition">¶</a></dt> +<dd><p>Select the assertion level at which an assertion violation stops the +simulation. <cite>LEVEL</cite> is the name from the <cite>severity_level</cite> +enumerated type defined in the <cite>standard</cite> package or the +<code class="samp docutils literal"><span class="pre">none</span></code> name.</p> +<p>By default, only assertion violation of severity level <code class="samp docutils literal"><span class="pre">failure</span></code> +stops the simulation.</p> +<p>For example, if <cite>LEVEL</cite> was <code class="samp docutils literal"><span class="pre">warning</span></code>, any assertion violation +with severity level <code class="samp docutils literal"><span class="pre">warning</span></code>, <code class="samp docutils literal"><span class="pre">error</span></code> or <code class="samp docutils literal"><span class="pre">failure</span></code> would +stop simulation, but the assertion violation at the <code class="samp docutils literal"><span class="pre">note</span></code> severity +level would only display a message.</p> +<p>Option <code class="xref std std-option docutils literal"><span class="pre">--assert-level=none</span></code> prevents any assertion violation to stop +simulation.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption--ieee-asserts"> +<code class="descname">--ieee-asserts</code><code class="descclassname">=<POLICY></code><a class="headerlink" href="#cmdoption--ieee-asserts" title="Permalink to this definition">¶</a></dt> +<dd><p>Select how the assertions from <code class="samp docutils literal"><span class="pre">ieee</span></code> units are +handled. <cite>POLICY</cite> can be <code class="samp docutils literal"><span class="pre">enable</span></code> (the default), +<code class="samp docutils literal"><span class="pre">disable</span></code> which disables all assertion from <code class="samp docutils literal"><span class="pre">ieee</span></code> packages +and <code class="samp docutils literal"><span class="pre">disable-at-0</span></code> which disables only at start of simulation.</p> +<p>This option can be useful to avoid assertion message from +<code class="samp docutils literal"><span class="pre">ieee.numeric_std</span></code> (and other <code class="samp docutils literal"><span class="pre">ieee</span></code> packages).</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption--stop-time"> +<code class="descname">--stop-time</code><code class="descclassname">=<TIME></code><a class="headerlink" href="#cmdoption--stop-time" title="Permalink to this definition">¶</a></dt> +<dd><p>Stop the simulation after <code class="samp docutils literal"><span class="pre">TIME</span></code>. <code class="samp docutils literal"><span class="pre">TIME</span></code> is expressed as a time +value, <em>without</em> any space. The time is the simulation time, not +the real clock time.</p> +<p>For example:</p> +<div class="highlight-python"><div class="highlight"><pre>$ ./my_design --stop-time=10ns +$ ./my_design --stop-time=ps +</pre></div> +</div> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption--stop-delta"> +<code class="descname">--stop-delta</code><code class="descclassname">=<N></code><a class="headerlink" href="#cmdoption--stop-delta" title="Permalink to this definition">¶</a></dt> +<dd><p>Stop the simulation after <cite>N</cite> delta cycles in the same current time.</p> +<span class="target" id="index-0"></span></dd></dl> + +<dl class="option"> +<dt id="cmdoption--disp-time"> +<code class="descname">--disp-time</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption--disp-time" title="Permalink to this definition">¶</a></dt> +<dd><p>Display the time and delta cycle number as simulation advances.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption--disp-tree"> +<code class="descname">--disp-tree</code><code class="descclassname">[=<KIND>]</code><a class="headerlink" href="#cmdoption--disp-tree" title="Permalink to this definition">¶</a></dt> +<dd><p id="index-1">Display the design hierarchy as a tree of instantiated design entities. +This may be useful to understand the structure of a complex +design. <cite>KIND</cite> is optional, but if set must be one of:</p> +<ul class="simple"> +<li>none +Do not display hierarchy. Same as if the option was not present.</li> +<li>inst +Display entities, architectures, instances, blocks and generates statements.</li> +<li>proc +Like <code class="samp docutils literal"><span class="pre">inst</span></code> but also display processes.</li> +<li>port +Like <code class="samp docutils literal"><span class="pre">proc</span></code> but display ports and signals too. +If <cite>KIND</cite> is not specified, the hierarchy is displayed with the +<code class="samp docutils literal"><span class="pre">port</span></code> mode.</li> +</ul> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption--no-run"> +<code class="descname">--no-run</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption--no-run" title="Permalink to this definition">¶</a></dt> +<dd><p>Do not simulate, only elaborate. This may be used with +<a class="reference internal" href="#cmdoption--disp-tree"><code class="xref std std-option docutils literal"><span class="pre">--disp-tree</span></code></a> to display the tree without simulating the whole +design.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption--vcd"> +<code class="descname">--vcd</code><code class="descclassname">=<FILENAME></code><a class="headerlink" href="#cmdoption--vcd" title="Permalink to this definition">¶</a></dt> +<dd></dd></dl> + +<dl class="option"> +<dt id="cmdoption--vcdgz"> +<code class="descname">--vcdgz</code><code class="descclassname">=<FILENAME></code><a class="headerlink" href="#cmdoption--vcdgz" title="Permalink to this definition">¶</a></dt> +<dd><span class="target" id="index-2"></span><span class="target" id="index-3"></span><p id="index-4">Option <a class="reference internal" href="#cmdoption--vcd"><code class="xref std std-option docutils literal"><span class="pre">--vcd</span></code></a> dumps into the VCD file <cite>FILENAME</cite> the signal +values before each non-delta cycle. If <cite>FILENAME</cite> is <code class="samp docutils literal"><span class="pre">-</span></code>, +then the standard output is used, otherwise a file is created or +overwritten.</p> +<p>The <a class="reference internal" href="#cmdoption--vcdgz"><code class="xref std std-option docutils literal"><span class="pre">--vcdgz</span></code></a> option is the same as the <em>–vcd</em> option, +but the output is compressed using the <cite>zlib</cite> (<cite>gzip</cite> +compression). However, you can’t use the <code class="samp docutils literal"><span class="pre">-</span></code> filename. +Furthermore, only one VCD file can be written.</p> +<p><em class="dfn">VCD</em> (value change dump) is a file format defined +by the <cite>verilog</cite> standard and used by virtually any wave viewer.</p> +<p>Since it comes from <cite>verilog</cite>, only a few VHDL types can be dumped. GHDL +dumps only signals whose base type is of the following:</p> +<ul class="simple"> +<li>types defined in the <code class="samp docutils literal"><span class="pre">std.standard</span></code> package:</li> +<li><code class="samp docutils literal"><span class="pre">bit</span></code></li> +<li><code class="samp docutils literal"><span class="pre">bit_vector</span></code></li> +<li>types defined in the <code class="samp docutils literal"><span class="pre">ieee.std_logic_1164</span></code> package:</li> +<li><code class="samp docutils literal"><span class="pre">std_ulogic</span></code></li> +<li><code class="samp docutils literal"><span class="pre">std_logic</span></code> (because it is a subtype of <code class="samp docutils literal"><span class="pre">std_ulogic</span></code>)</li> +<li><code class="samp docutils literal"><span class="pre">std_ulogic_vector</span></code></li> +<li><code class="samp docutils literal"><span class="pre">std_logic_vector</span></code></li> +<li>any integer type</li> +</ul> +<p>I have successfully used <cite>gtkwave</cite> to view VCD files.</p> +<p>Currently, there is no way to select signals to be dumped: all signals are +dumped, which can generate big files.</p> +<p>It is very unfortunate there is no standard or well-known wave file +format supporting VHDL types. If you are aware of such a free format, +please mail me (<a class="reference internal" href="index.html#reporting-bugs"><span>Reporting bugs</span></a>).</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption--fst"> +<code class="descname">--fst</code><code class="descclassname">=<FILENAME></code><a class="headerlink" href="#cmdoption--fst" title="Permalink to this definition">¶</a></dt> +<dd><p>Write the waveforms into a <cite>fst</cite>, that can be displayed by +<cite>gtkwave</cite>. The <cite>fst</cite> files are much smaller than VCD or +<cite>GHW</cite> files, but it handles only the same signals as the VCD format.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption--wave"> +<code class="descname">--wave</code><code class="descclassname">=<FILENAME></code><a class="headerlink" href="#cmdoption--wave" title="Permalink to this definition">¶</a></dt> +<dd><p>Write the waveforms into a <cite>ghw</cite> (GHdl Waveform) file. Currently, all +the signals are dumped into the waveform file, you cannot select a hierarchy +of signals to be dumped.</p> +<p>The format of this file was defined by myself and is not yet completely fixed. +It may change slightly. The <code class="samp docutils literal"><span class="pre">gtkwave</span></code> tool can read the GHW files.</p> +<p>Contrary to VCD files, any VHDL type can be dumped into a GHW file.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption--sdf"> +<code class="descname">--sdf</code><code class="descclassname">=<PATH>=<FILENAME></code><a class="headerlink" href="#cmdoption--sdf" title="Permalink to this definition">¶</a></dt> +<dd><p>Do VITAL annotation on <cite>PATH</cite> with SDF file <code class="file docutils literal"><span class="pre">FILENAME</span></code>.</p> +<p><cite>PATH</cite> is a path of instances, separated with <code class="samp docutils literal"><span class="pre">.</span></code> or <code class="samp docutils literal"><span class="pre">/</span></code>. +Any separator can be used. Instances are component instantiation labels, +generate labels or block labels. Currently, you cannot use an indexed name.</p> +<p>Specifying a delay:</p> +<div class="highlight-python"><div class="highlight"><pre>--sdf=min=<PATH>=<FILENAME> +--sdf=typ=<PATH>=<FILENAME> +--sdf=max=<PATH>=<FILENAME> +</pre></div> +</div> +<p>If the option contains a type of delay, that is <code class="samp docutils literal"><span class="pre">min=</span></code>, +<code class="samp docutils literal"><span class="pre">typ=</span></code> or <code class="samp docutils literal"><span class="pre">max=</span></code>, the annotator use respectively minimum, +typical or maximum values. If the option does not contain a type of delay, +the annotator use the typical delay.</p> +<p>See <a class="reference internal" href="index.html#backannotation"><span>Backannotation</span></a>, for more details.</p> +</dd></dl> + +<dl class="option"> +<dt id="cmdoption--help"> +<code class="descname">--help</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption--help" title="Permalink to this definition">¶</a></dt> +<dd><p>Display a short description of the options accepted by the runtime library.</p> +</dd></dl> + +</div> +<div class="section" id="debugging-vhdl-programs"> +<h3>Debugging VHDL programs<a class="headerlink" href="#debugging-vhdl-programs" title="Permalink to this headline">¶</a></h3> +<span class="target" id="index-5"></span><p id="index-6">Debugging VHDL programs using <cite>GDB</cite> is possible only on GNU/Linux systems.</p> +<p><cite>GDB</cite> is a general purpose debugger for programs compiled by <cite>GCC</cite>. +Currently, there is no VHDL support for <cite>GDB</cite>. It may be difficult +to inspect variables or signals in <cite>GDB</cite>, however, <cite>GDB</cite> is +still able to display the stack frame in case of error or to set a breakpoint +at a specified line.</p> +<p><cite>GDB</cite> can be useful to precisely catch a runtime error, such as indexing +an array beyond its bounds. All error check subprograms call the +<cite>__ghdl_fatal</cite> procedure. Therefore, to catch runtime error, set +a breakpoint like this:</p> +<blockquote> +<div>(gdb) break __ghdl_fatal</div></blockquote> +<p>When the breakpoint is hit, use the <cite>where</cite> or <cite>bt</cite> command to +display the stack frames.</p> +</div> +</div> +<span id="document-GHDL_implementation_of_VHDL"></span><div class="section" id="ghdl-implementation-of-vhdl"> +<h2>GHDL implementation of VHDL<a class="headerlink" href="#ghdl-implementation-of-vhdl" title="Permalink to this headline">¶</a></h2> +<p>This chapter describes several implementation defined aspect of VHDL in GHDL.</p> +<div class="section" id="vhdl-standards"> +<span id="id1"></span><h3>VHDL standards<a class="headerlink" href="#vhdl-standards" title="Permalink to this headline">¶</a></h3> +<span class="target" id="index-0"></span><span class="target" id="index-1"></span><span class="target" id="index-2"></span><span class="target" id="index-3"></span><span class="target" id="index-4"></span><span class="target" id="index-5"></span><span class="target" id="index-6"></span><span class="target" id="index-7"></span><span class="target" id="index-8"></span><p id="index-9">This is very unfortunate, but there are many versions of the VHDL +language, and they aren’t backward compatible.</p> +<p>The VHDL language was first standardized in 1987 by IEEE as IEEE 1076-1987, and +is commonly referred as VHDL-87. This is certainly the most important version, +since most of the VHDL tools are still based on this standard.</p> +<p>Various problems of this first standard have been analyzed by experts groups +to give reasonable ways of interpreting the unclear portions of the standard.</p> +<p>VHDL was revised in 1993 by IEEE as IEEE 1076-1993. This revision is still +well-known.</p> +<p>Unfortunately, VHDL-93 is not fully compatible with VHDL-87, i.e. some perfectly +valid VHDL-87 programs are invalid VHDL-93 programs. Here are some of the +reasons:</p> +<ul class="simple"> +<li>the syntax of file declaration has changed (this is the most visible source +of incompatibility),</li> +<li>new keywords were introduced (group, impure, inertial, literal, +postponed, pure, reject, rol, ror, shared, sla, sll, sra, srl, +unaffected, xnor),</li> +<li>some dynamic behaviours have changed (the concatenation is one of them),</li> +<li>rules have been added.</li> +</ul> +<p>Shared variables were replaced by protected types in the 2000 revision of +the VHDL standard. This modification is also known as 1076a. Note that this +standard is not fully backward compatible with VHDL-93, since the type of a +shared variable must now be a protected type (there was no such restriction +before).</p> +<p>Minors corrections were added by the 2002 revision of the VHDL standard. This +revision is not fully backward compatible with VHDL-00 since, for example, +the value of the <cite>‘instance_name</cite> attribute has slightly changed.</p> +<p>You can select the VHDL standard expected by GHDL with the +<code class="samp docutils literal"><span class="pre">--std=VER</span></code> option, where <code class="samp docutils literal"><span class="pre">VER</span></code> is one of the left column of the +table below:</p> +<dl class="docutils"> +<dt>87</dt> +<dd>Select VHDL-87 standard as defined by IEEE 1076-1987. LRM bugs corrected by +later revisions are taken into account.</dd> +<dt>93</dt> +<dd>Select VHDL-93; VHDL-87 file declarations are not accepted.</dd> +<dt>93c</dt> +<dd><p class="first">Select VHDL-93 standard with relaxed rules:</p> +<ul class="last simple"> +<li>VHDL-87 file declarations are accepted;</li> +<li>default binding indication rules of VHDL-02 are used. Default binding rules +are often used, but they are particularly obscure before VHDL-02.</li> +</ul> +</dd> +<dt>00</dt> +<dd>Select VHDL-2000 standard, which adds protected types.</dd> +<dt>02</dt> +<dd>Select VHDL-2002 standard</dd> +<dt>08</dt> +<dd>Select VHDL-2008 standard (partially implemented).</dd> +</dl> +<p>You cannot mix VHDL-87 and VHDL-93 units. A design hierarchy must have been +completely analyzed using either the 87 or the 93 version of the VHDL standard.</p> +</div> +<div class="section" id="psl-implementation"> +<span id="id2"></span><h3>PSL implementation<a class="headerlink" href="#psl-implementation" title="Permalink to this headline">¶</a></h3> +<p>GHDL understands embedded PSL annotations in VHDL files, but not in +separate files.</p> +<p>As PSL annotations are embedded within comments, you must analyze and elaborate +your design with option <em>-fpsl</em> to enable PSL annotations.</p> +<p>A PSL assertion statement must appear within a comment that starts +with the <cite>psl</cite> keyword. The keyword must be followed (on the +same line) by a PSL keyword such as <cite>assert</cite> or <cite>default</cite>. +To continue a PSL statement on the next line, just start a new comment.</p> +<p>A PSL statement is considered as a process. So it is not allowed within +a process.</p> +<p>All PSL assertions must be clocked (GHDL doesn’t support unclocked assertion). +Furthermore only one clock per assertion is allowed.</p> +<p>You can either use a default clock like this:</p> +<div class="highlight-VHDL"><div class="highlight"><pre><span class="c1">-- psl default clock is rising_edge (CLK);</span> +<span class="c1">-- psl assert always</span> +<span class="c1">-- a -> eventually! b;</span> +</pre></div> +</div> +<p>or use a clocked expression (note the use of parenthesis):</p> +<div class="highlight-VHDL"><div class="highlight"><pre><span class="c1">-- psl assert (always a -> next[3](b)) @rising_edge (clk);</span> +</pre></div> +</div> +<p>Of course only the simple subset of PSL is allowed.</p> +<p>Currently the built-in functions are not implemented.</p> +</div> +<div class="section" id="source-representation"> +<h3>Source representation<a class="headerlink" href="#source-representation" title="Permalink to this headline">¶</a></h3> +<p>According to the VHDL standard, design units (i.e. entities, +architectures, packages, package bodies and configurations) may be +independently analyzed.</p> +<p>Several design units may be grouped into a design file.</p> +<p>In GHDL, a system file represents a design file. That is, a file compiled by +GHDL may contain one or more design units.</p> +<p>It is common to have several design units in a design file.</p> +<p>GHDL does not impose any restriction on the name of a design file +(except that the filename may not contain any control character or +spaces).</p> +<p>GHDL do not keep a binary representation of the design units analyzed like +other VHDL analyzers. The sources of the design units are re-read when +needed (for example, an entity is re-read when one of its architecture is +analyzed). Therefore, if you delete or modify a source file of a unit +analyzed, GHDL will refuse to use it.</p> +</div> +<div class="section" id="library-database"> +<span id="id3"></span><h3>Library database<a class="headerlink" href="#library-database" title="Permalink to this headline">¶</a></h3> +<p>Each design unit analyzed is placed into a design library. By default, +the name of this design library is <code class="samp docutils literal"><span class="pre">work</span></code>; however, this can be +changed with the <code class="xref std std-option docutils literal"><span class="pre">--work=NAME</span></code> option of GHDL.</p> +<p>To keep the list of design units in a design library, GHDL creates +library files. The name of these files is <code class="file docutils literal"><span class="pre">NAME-objVER.cf</span></code>, where +<cite>NAME</cite> is the name of the library, and <cite>VER</cite> the VHDL version (87 +or 93) used to analyze the design units.</p> +<p>You don’t have to know how to read a library file. You can display it +using the <em>-d</em> of <cite>ghdl</cite>. The file contains the name of the +design units, as well as the location and the dependencies.</p> +<p>The format may change with the next version of GHDL.</p> +</div> +<div class="section" id="top-entity"> +<span id="id4"></span><h3>Top entity<a class="headerlink" href="#top-entity" title="Permalink to this headline">¶</a></h3> +<p>There are some restrictions on the entity being at the apex of a design +hierarchy:</p> +<ul class="simple"> +<li>The generic must have a default value, and the value of a generic is its +default value;</li> +<li>The ports type must be constrained.</li> +</ul> +</div> +<div class="section" id="using-vendor-libraries"> +<h3>Using vendor libraries<a class="headerlink" href="#using-vendor-libraries" title="Permalink to this headline">¶</a></h3> +<p>Many vendors libraries have been analyzed with GHDL. There are +usually no problems. Be sure to use the <code class="xref std std-option docutils literal"><span class="pre">--work=</span></code> option. +However, some problems have been encountered.</p> +<p>GHDL follows the VHDL LRM (the manual which defines VHDL) more +strictly than other VHDL tools. You could try to relax the +restrictions by using the <code class="xref std std-option docutils literal"><span class="pre">--std=93c</span></code>, <a class="reference internal" href="index.html#cmdoption-fexplicit"><code class="xref std std-option docutils literal"><span class="pre">-fexplicit</span></code></a>, +<a class="reference internal" href="index.html#cmdoption-frelaxed-rules"><code class="xref std std-option docutils literal"><span class="pre">-frelaxed-rules</span></code></a> and <code class="xref std std-option docutils literal"><span class="pre">--warn-no-vital-generic</span></code>.</p> +</div> +<div class="section" id="interfacing-to-other-languages"> +<h3>Interfacing to other languages<a class="headerlink" href="#interfacing-to-other-languages" title="Permalink to this headline">¶</a></h3> +<span class="target" id="index-10"></span><span class="target" id="index-11"></span><span class="target" id="index-12"></span><span class="target" id="index-13"></span><p id="index-14">Interfacing with foreign languages is possible only on GNU/Linux systems.</p> +<p>You can define a subprogram in a foreign language (such as <cite>C</cite> or +<cite>Ada</cite>) and import it in a VHDL design.</p> +<div class="section" id="foreign-declarations"> +<h4>Foreign declarations<a class="headerlink" href="#foreign-declarations" title="Permalink to this headline">¶</a></h4> +<p>Only subprograms (functions or procedures) can be imported, using the foreign +attribute. In this example, the <cite>sin</cite> function is imported:</p> +<div class="highlight-VHDL"><div class="highlight"><pre><span class="k">package</span> <span class="n">math</span> <span class="k">is</span> + <span class="k">function</span> <span class="n">sin</span> <span class="p">(</span><span class="n">v</span> <span class="o">:</span> <span class="n">real</span><span class="p">)</span> <span class="k">return</span> <span class="n">real</span><span class="p">;</span> + <span class="k">attribute</span> <span class="n">foreign</span> <span class="k">of</span> <span class="n">sin</span> <span class="o">:</span> <span class="k">function</span> <span class="k">is</span> <span class="s">"VHPIDIRECT sin"</span><span class="p">;</span> +<span class="k">end</span> <span class="nc">math</span><span class="p">;</span> + +<span class="k">package</span> <span class="k">body</span> <span class="n">math</span> <span class="k">is</span> + <span class="k">function</span> <span class="n">sin</span> <span class="p">(</span><span class="n">v</span> <span class="o">:</span> <span class="n">real</span><span class="p">)</span> <span class="k">return</span> <span class="n">real</span> <span class="k">is</span> + <span class="k">begin</span> + <span class="k">assert</span> <span class="n">false</span> <span class="k">severity</span> <span class="n">failure</span><span class="p">;</span> + <span class="k">end</span> <span class="nc">sin</span><span class="p">;</span> +<span class="k">end</span> <span class="nc">math</span><span class="p">;</span> +</pre></div> +</div> +<p>A subprogram is made foreign if the <cite>foreign</cite> attribute decorates +it. This attribute is declared in the 1993 revision of the +<code class="samp docutils literal"><span class="pre">std.standard</span></code> package. Therefore, you cannot use this feature in +VHDL 1987.</p> +<p>The decoration is achieved through an attribute specification. The +attribute specification must be in the same declarative part as the +subprogram and must be after it. This is a general rule for specifications. +The value of the specification must be a locally static string.</p> +<p>Even when a subprogram is foreign, its body must be present. However, since +it won’t be called, you can made it empty or simply but an assertion.</p> +<p>The value of the attribute must start with <code class="samp docutils literal"><span class="pre">VHPIDIRECT</span></code> (an +upper-case keyword followed by one or more blanks). The linkage name of the +subprogram follows.</p> +</div> +<div class="section" id="restrictions-on-foreign-declarations"> +<span id="id5"></span><h4>Restrictions on foreign declarations<a class="headerlink" href="#restrictions-on-foreign-declarations" title="Permalink to this headline">¶</a></h4> +<p>Any subprogram can be imported. GHDL puts no restrictions on foreign +subprograms. However, the representation of a type or of an interface in a +foreign language may be obscure. Most of non-composite types are easily imported:</p> +<dl class="docutils"> +<dt><em>integer types</em></dt> +<dd>They are represented on a 32 bits word. This generally corresponds to +<cite>int</cite> for <cite>C</cite> or <cite>Integer</cite> for <cite>Ada</cite>.</dd> +<dt><em>physical types</em></dt> +<dd>They are represented on a 64 bits word. This generally corresponds to the +<cite>long long</cite> for <cite>C</cite> or <cite>Long_Long_Integer</cite> for <cite>Ada</cite>.</dd> +<dt><em>floating point types</em></dt> +<dd>They are represented on a 64 bits floating point word. This generally +corresponds to <cite>double</cite> for <cite>C</cite> or <cite>Long_Float</cite> for <cite>Ada</cite>.</dd> +<dt><em>enumeration types</em></dt> +<dd>They are represented on 8 bits or 32 bits word, if the number of literals is +greater than 256. There is no corresponding C types, since arguments are +not promoted.</dd> +</dl> +<p>Non-composite types are passed by value. For the <cite>in</cite> mode, this +corresponds to the <cite>C</cite> or <cite>Ada</cite> mechanism. The <cite>out</cite> and +<cite>inout</cite> interfaces of non-composite types are gathered in a record +and this record is passed by reference as the first argument to the +subprogram. As a consequence, you shouldn’t use <cite>in</cite> and +<cite>inout</cite> modes in foreign subprograms, since they are not portable.</p> +<p>Records are represented like a <cite>C</cite> structure and are passed by reference +to subprograms.</p> +<p>Arrays with static bounds are represented like a <cite>C</cite> array, whose +length is the number of elements, and are passed by reference to subprograms.</p> +<p>Unconstrained array are represented by a fat pointer. Do not use unconstrained +arrays in foreign subprograms.</p> +<p>Accesses to an unconstrained array is a fat pointer. Other accesses correspond to an address and are passed to a subprogram like other non-composite types.</p> +<p>Files are represented by a 32 bits word, which corresponds to an index +in a table.</p> +</div> +<div class="section" id="linking-with-foreign-object-files"> +<span id="id6"></span><h4>Linking with foreign object files<a class="headerlink" href="#linking-with-foreign-object-files" title="Permalink to this headline">¶</a></h4> +<p>You may add additional files or options during the link using the +<em>-Wl,</em> of <cite>GHDL</cite>, as described in <a class="reference internal" href="index.html#elaboration-command"><span>Elaboration command</span></a>. +For example:</p> +<div class="highlight-python"><div class="highlight"><pre>ghdl -e -Wl,-lm math_tb +</pre></div> +</div> +<p>will create the <code class="file docutils literal"><span class="pre">math_tb</span></code> executable with the <code class="file docutils literal"><span class="pre">lm</span></code> (mathematical) +library.</p> +<p>Note the <code class="file docutils literal"><span class="pre">c</span></code> library is always linked with an executable.</p> +</div> +<div class="section" id="starting-a-simulation-from-a-foreign-program"> +<span id="id7"></span><h4>Starting a simulation from a foreign program<a class="headerlink" href="#starting-a-simulation-from-a-foreign-program" title="Permalink to this headline">¶</a></h4> +<p>You may run your design from an external program. You just have to call +the <code class="samp docutils literal"><span class="pre">ghdl_main</span></code> function which can be defined:</p> +<p>in C:</p> +<div class="highlight-C"><div class="highlight"><pre><span class="k">extern</span> <span class="kt">int</span> <span class="nf">ghdl_main</span> <span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span> <span class="o">**</span><span class="n">argv</span><span class="p">);</span> +</pre></div> +</div> +<p>in Ada:</p> +<div class="highlight-Ada"><div class="highlight"><pre><span class="kn">with</span> <span class="nn">System</span><span class="p">;</span> +<span class="p">...</span> +<span class="kd">function</span> <span class="nf">Ghdl_Main</span> <span class="p">(</span><span class="nv">Argc</span> <span class="p">: </span><span class="nv">Integer</span><span class="p">;</span> <span class="nv">Argv</span> <span class="p">: </span><span class="nv">System</span><span class="p">.</span><span class="nv">Address</span><span class="p">)</span> + <span class="kr">return</span> <span class="kt">Integer</span><span class="p">;</span> +<span class="kr">pragma</span> <span class="cp">import</span> <span class="p">(</span><span class="n">C</span><span class="p">,</span> <span class="n">Ghdl_Main</span><span class="p">,</span> <span class="s">"ghdl_main"</span><span class="p">);</span> +</pre></div> +</div> +<p>This function must be called once, and returns 0 at the end of the simulation. +In case of failure, this function does not return. This has to be fixed.</p> +</div> +<div class="section" id="linking-with-ada"> +<span id="id8"></span><h4>Linking with Ada<a class="headerlink" href="#linking-with-ada" title="Permalink to this headline">¶</a></h4> +<p>As explained previously in <a class="reference internal" href="#starting-a-simulation-from-a-foreign-program"><span>Starting a simulation from a foreign program</span></a>, +you can start a simulation from an <cite>Ada</cite> program. However the build +process is not trivial: you have to elaborate your <cite>Ada</cite> program and your +<cite>VHDL</cite> design.</p> +<p>First, you have to analyze all your design files. In this example, we +suppose there is only one design file, <code class="file docutils literal"><span class="pre">design.vhdl</span></code>.</p> +<div class="highlight-python"><div class="highlight"><pre>$ ghdl -a design.vhdl +</pre></div> +</div> +<p>Then, bind your design. In this example, we suppose the entity at the +design apex is <code class="samp docutils literal"><span class="pre">design</span></code>.</p> +<div class="highlight-python"><div class="highlight"><pre>$ ghdl --bind design +</pre></div> +</div> +<p>Finally, compile, bind your <cite>Ada</cite> program at link it with your <cite>VHDL</cite> +design:</p> +<div class="highlight-python"><div class="highlight"><pre>$ gnatmake my_prog -largs `ghdl --list-link design` +</pre></div> +</div> +</div> +<div class="section" id="using-grt-from-ada"> +<h4>Using GRT from Ada<a class="headerlink" href="#using-grt-from-ada" title="Permalink to this headline">¶</a></h4> +<div class="admonition warning"> +<p class="first admonition-title">Warning</p> +<p class="last">This topic is only for advanced users knowing how to use <cite>Ada</cite> +and <cite>GNAT</cite>. This is provided only for reference, I have tested +this once before releasing <cite>GHDL</cite> 0.19 but this is not checked at +each release.</p> +</div> +<p>The simulator kernel of <cite>GHDL</cite> named <em class="dfn">GRT</em> is written in +<cite>Ada95</cite> and contains a very light and slightly adapted version +of <cite>VHPI</cite>. Since it is an <cite>Ada</cite> implementation it is +called <em class="dfn">AVHPI</em>. Although being tough, you may interface to <cite>AVHPI</cite>.</p> +<p>For using <cite>AVHPI</cite>, you need the sources of <cite>GHDL</cite> and to recompile +them (at least the <cite>GRT</cite> library). This library is usually compiled with +a <cite>No_Run_Time</cite> pragma, so that the user does not need to install the +<cite>GNAT</cite> runtime library. However, you certainly want to use the usual +runtime library and want to avoid this pragma. For this, reset the +<cite>GRT_PRAGMA_FLAG</cite> variable.</p> +<div class="highlight-python"><div class="highlight"><pre>$ make GRT_PRAGMA_FLAG= grt-all +</pre></div> +</div> +<p>Since <cite>GRT</cite> is a self-contained library, you don’t want +<cite>gnatlink</cite> to fetch individual object files (furthermore this +doesn’t always work due to tricks used in <cite>GRT</cite>). For this, +remove all the object files and make the <code class="file docutils literal"><span class="pre">.ali</span></code> files read-only.</p> +<div class="highlight-python"><div class="highlight"><pre>$ rm *.o +$ chmod -w *.ali +</pre></div> +</div> +<p>You may then install the sources files and the <code class="file docutils literal"><span class="pre">.ali</span></code> files. I have never +tested this step.</p> +<p>You are now ready to use it.</p> +<p>For example, here is an example, <code class="file docutils literal"><span class="pre">test_grt.adb</span></code> which displays the top +level design name.</p> +<div class="highlight-Ada"><div class="highlight"><pre><span class="kn">with</span> <span class="nn">System</span><span class="p">;</span> <span class="kn">use</span> <span class="nn">System</span><span class="p">;</span> +<span class="kn">with</span> <span class="nn">Grt.Avhpi</span><span class="p">;</span> <span class="kn">use</span> <span class="nn">Grt.Avhpi</span><span class="p">;</span> +<span class="kn">with</span> <span class="nn">Ada.Text_IO</span><span class="p">;</span> <span class="kn">use</span> <span class="nn">Ada.Text_IO</span><span class="p">;</span> +<span class="kn">with</span> <span class="nn">Ghdl_Main</span><span class="p">;</span> + +<span class="kd">procedure</span> <span class="nf">Test_Grt</span> <span class="kr">is</span> + <span class="c1">-- VHPI handle.</span> + <span class="n">H</span> <span class="p">:</span> <span class="n">VhpiHandleT</span><span class="p">;</span> + <span class="n">Status</span> <span class="p">:</span> <span class="kt">Integer</span><span class="p">;</span> + + <span class="c1">-- Name.</span> + <span class="n">Name</span> <span class="p">:</span> <span class="kt">String</span> <span class="p">(</span><span class="mi">1</span> <span class="p">..</span> <span class="mi">64</span><span class="p">);</span> + <span class="n">Name_Len</span> <span class="p">:</span> <span class="kt">Integer</span><span class="p">;</span> +<span class="kr">begin</span> + <span class="c1">-- Elaborate and run the design.</span> + <span class="n">Status</span> <span class="p">:=</span> <span class="n">Ghdl_Main</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="n">Null_Address</span><span class="p">);</span> + + <span class="c1">-- Display the status of the simulation.</span> + <span class="n">Put_Line</span> <span class="p">(</span><span class="s">"Status is "</span> <span class="o">&</span> <span class="kt">Integer</span><span class="p">'</span><span class="na">Image</span> <span class="p">(</span><span class="n">Status</span><span class="p">));</span> + + <span class="c1">-- Get the root instance.</span> + <span class="n">Get_Root_Inst</span><span class="p">(</span><span class="n">H</span><span class="p">);</span> + + <span class="c1">-- Disp its name using vhpi API.</span> + <span class="n">Vhpi_Get_Str</span> <span class="p">(</span><span class="n">VhpiNameP</span><span class="p">,</span> <span class="n">H</span><span class="p">,</span> <span class="n">Name</span><span class="p">,</span> <span class="n">Name_Len</span><span class="p">);</span> + <span class="n">Put_Line</span> <span class="p">(</span><span class="s">"Root instance name: "</span> <span class="o">&</span> <span class="n">Name</span> <span class="p">(</span><span class="mi">1</span> <span class="p">..</span> <span class="n">Name_Len</span><span class="p">));</span> +<span class="kr">end</span> <span class="nf">Test_Grt</span><span class="p">;</span> +</pre></div> +</div> +<p>First, analyze and bind your design:</p> +<div class="highlight-python"><div class="highlight"><pre>$ ghdl -a counter.vhdl +$ ghdl --bind counter +</pre></div> +</div> +<p>Then build the whole:</p> +<div class="highlight-python"><div class="highlight"><pre>$ gnatmake test_grt -aL`grt_ali_path` -aI`grt_src_path` -largs + `ghdl --list-link counter` +</pre></div> +</div> +<p>Finally, run your design:</p> +<div class="highlight-python"><div class="highlight"><pre>$ ./test_grt +Status is 0 +Root instance name: counter +</pre></div> +</div> +</div> +</div> +</div> +<span id="document-GHDL_implementation_of_VITAL"></span><div class="section" id="ghdl-implementation-of-vital"> +<h2>GHDL implementation of VITAL<a class="headerlink" href="#ghdl-implementation-of-vital" title="Permalink to this headline">¶</a></h2> +<span class="target" id="index-0"></span><span class="target" id="index-1"></span><p id="index-2">This chapter describes how VITAL is implemented in GHDL. Support of VITAL is +really in a preliminary stage. Do not expect too much of it as now.</p> +<div class="section" id="vital-packages"> +<span id="id1"></span><h3>VITAL packages<a class="headerlink" href="#vital-packages" title="Permalink to this headline">¶</a></h3> +<p>The VITAL standard or IEEE 1076.4 was first published in 1995, and revised in +2000.</p> +<p>The version of the VITAL packages depends on the VHDL standard. VITAL +1995 packages are used with the VHDL 1987 standard, while VITAL 2000 +packages are used with other standards. This choice is based on the +requirements of VITAL: VITAL 1995 requires the models follow the VHDL +1987 standard, while VITAL 2000 requires the models follow VHDL 1993.</p> +<p>The VITAL 2000 packages were slightly modified so that they conform to +the VHDL 1993 standard (a few functions are made pure and a few one +impure).</p> +</div> +<div class="section" id="vhdl-restrictions-for-vital"> +<span id="id2"></span><h3>VHDL restrictions for VITAL<a class="headerlink" href="#vhdl-restrictions-for-vital" title="Permalink to this headline">¶</a></h3> +<p>The VITAL standard (partially) implemented is the IEEE 1076.4 standard +published in 1995.</p> +<p>This standard defines restriction of the VHDL language usage on VITAL +model. A <em class="dfn">VITAL model</em> is a design unit (entity or architecture) +decorated by the <cite>VITAL_Level0</cite> or <cite>VITAL_Level1</cite> attribute. +These attributes are defined in the <cite>ieee.VITAL_Timing</cite> package.</p> +<p>Currently, only VITAL level 0 checks are implemented. VITAL level 1 models +can be analyzed, but GHDL doesn’t check they comply with the VITAL standard.</p> +<p>Moreover, GHDL doesn’t check (yet) that timing generics are not read inside +a VITAL level 0 model prior the VITAL annotation.</p> +<p>The analysis of a non-conformant VITAL model fails. You can disable the +checks of VITAL restrictions with the <em>–no-vital-checks</em>. Even when +restrictions are not checked, SDF annotation can be performed.</p> +</div> +<div class="section" id="backannotation"> +<span id="id3"></span><h3>Backannotation<a class="headerlink" href="#backannotation" title="Permalink to this headline">¶</a></h3> +<p id="index-3"><em class="dfn">Backannotation</em> is the process of setting VITAL generics with timing +information provided by an external files.</p> +<p>The external files must be SDF (Standard Delay Format) files. GHDL +supports a tiny subset of SDF version 2.1, other version number can be +used, provided no features added by the next version are used.</p> +<p>Hierarchical instance names are not supported. However you can use a list of +instances. If there is no instance, the top entity will be annotated and +the celltype must be the name of the top entity. If there is at least one +instance, the last instance name must be a component instantiation label, and +the celltype must be the name of the component declaration instantiated.</p> +<p>Instances being annotated are not required to be VITAL compliant. However +generics being annotated must follow rules of VITAL (e.g., type must be a +suitable vital delay type).</p> +<p>Currently, only timing constraints applying on a timing generic of type +<cite>VitalDelayType01</cite> has been implemented. This SDF annotator is +just a proof of concept. Features will be added with the following GHDL +release.</p> +</div> +<div class="section" id="negative-constraint-calculation"> +<h3>Negative constraint calculation<a class="headerlink" href="#negative-constraint-calculation" title="Permalink to this headline">¶</a></h3> +<p>Negative constraint delay adjustment are necessary to handle negative +constraint such as a negative setup time. This step is defined in the VITAL +standard and should occur after backannotation.</p> +<p>GHDL does not do negative constraint calculation. It fails to handle models +with negative constraint. I hope to be able to add this phase soon.</p> +</div> +</div> +<span id="document-Flaws_and_bugs_report"></span><div class="section" id="flaws-and-bugs-report"> +<h2>Flaws and bugs report<a class="headerlink" href="#flaws-and-bugs-report" title="Permalink to this headline">¶</a></h2> +<p>Despite all the testing and already reported issues, you can find bugs +or propose enhancements.</p> +<blockquote> +<div></div></blockquote> +<div class="section" id="reporting-bugs"> +<span id="id1"></span><h3>Reporting bugs<a class="headerlink" href="#reporting-bugs" title="Permalink to this headline">¶</a></h3> +<p>In order to improve GHDL, we welcome bugs report and suggestions for +any aspect of GHDL. Please create an issue on +<a class="reference external" href="https://github.com/tgingold/ghdl/issues">https://github.com/tgingold/ghdl/issues</a></p> +<p>If the compiler crashes, this is a bug. Reliable tools never crash.</p> +<p>If your compiled VHDL executable crashes, this may be a bug at +runtime or the code produced may be wrong. However, since VHDL +has a notion of pointers, an erroneous VHDL program (using invalid +pointers for example) may crash.</p> +<p>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. +Please send the input file and what you expected. If you know the LRM +well enough, please specify the paragraph which has not been well +implemented. If you don’t know the LRM, maybe your bug report will be +rejected simply because there is no bug. In the latter case, it may be +difficult to discuss the issue; and comparisons with other VHDL tools +is not a very strong argument.</p> +<p>If a compiler message is not clear enough for you, please tell me. The +error messages can be improved, but I have not enough experience with +them.</p> +<p>If you have found a mistake in the manual, please send a comment. If +you have not understood some parts of this manual, please tell me. +English is not my mother tongue, so this manual may not be well-written. +Again, rewriting part of it is a good way to improve it.</p> +<p>If you send a <cite>VHDL</cite> file producing a bug, it is a good idea to try +to make it as short as possible. It is also a good idea to make it +looking like a test: write a comment which explains whether the file +should compile, and if yes, whether or not it should run successfully. +In the latter case, an assert statement should finish the test; the +severity level note indicates success, while a severity level failure +indicates failure.</p> +<p>For bug reports, please include enough information for the maintainers to +reproduce the problem. This includes:</p> +<ul class="simple"> +<li>the version of <cite>GHDL</cite> (you can get it with <code class="samp docutils literal"><span class="pre">ghdl</span> <span class="pre">--version</span></code>).</li> +<li>the operating system</li> +<li>whether you have built <cite>GHDL</cite> from sources or used the binary +distribution.</li> +<li>the content of the input files</li> +<li>a description of the problem and samples of any erroneous input</li> +<li>anything else that you think would be helpful.</li> +</ul> +</div> +<div class="section" id="future-improvements"> +<h3>Future improvements<a class="headerlink" href="#future-improvements" title="Permalink to this headline">¶</a></h3> +<p>I have several axes for <cite>GHDL</cite> improvements:</p> +<ul class="simple"> +<li>Documentation.</li> +<li>Better diagnostics messages (warning and error).</li> +<li>Full support of VHDL-2008.</li> +<li>Optimization (simulation speed).</li> +<li>Graphical tools (to see waves and to debug)</li> +<li>Style checks</li> +<li>VITAL acceleration</li> +</ul> +</div> +</div> +<span id="document-Copyrights"></span><div class="section" id="copyrights"> +<h2>Copyrights<a class="headerlink" href="#copyrights" title="Permalink to this headline">¶</a></h2> +<p>The GHDL front-end, the <code class="samp docutils literal"><span class="pre">std.textio</span></code> package and the runtime +library (<code class="samp docutils literal"><span class="pre">grt</span></code>) are copyrighted Tristan Gingold, come with <strong>absolutely +no warranty</strong>, and are distributed under the conditions of the General +Public License.</p> +<p>The <code class="samp docutils literal"><span class="pre">ieee.numeric_bit</span></code> and <code class="samp docutils literal"><span class="pre">ieee.numeric_std</span></code> packages are +copyrighted by the IEEE. The source files may be distributed without +change, except as permitted by the standard.</p> +<p>This source file may not be +sold or distributed for profit. See the source file and the IEEE 1076.3 +standard for more information.</p> +<p>The <code class="samp docutils literal"><span class="pre">ieee.std_logic_1164</span></code>, <code class="samp docutils literal"><span class="pre">ieee.Math_Real</span></code> and +<code class="samp docutils literal"><span class="pre">ieee.Math_Complex</span></code> packages are copyrighted by the IEEE. See +source files for more information.</p> +<p>The <code class="samp docutils literal"><span class="pre">ieee.VITAL_Primitives</span></code>, <code class="samp docutils literal"><span class="pre">ieee.VITAL_Timing</span></code> and +<code class="samp docutils literal"><span class="pre">ieee.VITAL_Memory</span></code> packages are copyrighted by IEEE. See source +file and the IEEE 1076.4 standards for more information.</p> +<p>The packages <code class="samp docutils literal"><span class="pre">std_logic_arith</span></code>, +<code class="samp docutils literal"><span class="pre">std_logic_signed</span></code>, <code class="samp docutils literal"><span class="pre">std_logic_unsigned</span></code> and +<code class="samp docutils literal"><span class="pre">std_logic_textio</span></code> contained in the <code class="samp docutils literal"><span class="pre">synopsys</span></code> directory are +copyrighted by Synopsys, Inc. The source files 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. See the source files for more information.</p> +<p>The package <code class="samp docutils literal"><span class="pre">std_logic_arith</span></code> contained in the <code class="samp docutils literal"><span class="pre">mentor</span></code> +directory is copyrighted by Mentor Graphics. The source files may be +distributed in whole without restriction provided that the copyright +statement is not removed from the file and that any derivative work +contains this copyright notice. See the source files for more information.</p> +<p>As a consequence of the runtime copyright, you may not be allowed to +distribute an executable produced by <cite>GHDL</cite> without the VHDL +sources. To my mind, this is not a real restriction, since there is no +points in distributing VHDL executable. Please, send a comment +(<a class="reference internal" href="index.html#reporting-bugs"><span>Reporting bugs</span></a>) if you don’t like this policy.</p> +</div> +</div> +</div> +<div class="section" id="indices-and-tables"> +<h1>Indices and tables<a class="headerlink" href="#indices-and-tables" title="Permalink to this headline">¶</a></h1> +<ul class="simple"> +<li><a class="reference internal" href="genindex.html"><span>Index</span></a></li> +<li><a class="reference internal" href="search.html"><span>Search Page</span></a></li> +</ul> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html#document-index">Table Of Contents</a></h3> + <ul> +<li class="toctree-l1"><a class="reference internal" href="index.html#document-Introduction">Introduction</a><ul> +<li class="toctree-l2"><a class="reference internal" href="index.html#content-of-this-manual">Content of this manual</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#what-is-vhdl">What is <cite>VHDL</cite>?</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#what-is-ghdl">What is <cite>GHDL</cite>?</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="index.html#document-Starting_with_GHDL">Starting with GHDL</a><ul> +<li class="toctree-l2"><a class="reference internal" href="index.html#the-hello-world-program">The hello world program</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#a-full-adder">A full adder</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#starting-with-a-design">Starting with a design</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="index.html#document-Invoking_GHDL">Invoking GHDL</a><ul> +<li class="toctree-l2"><a class="reference internal" href="index.html#building-commands">Building commands</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#ghdl-options">GHDL options</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#passing-options-to-other-programs">Passing options to other programs</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#ghdl-warnings">GHDL warnings</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#rebuilding-commands">Rebuilding commands</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#library-commands">Library commands</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#cross-reference-command">Cross-reference command</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#file-commands">File commands</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#misc-commands">Misc commands</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#installation-directory">Installation Directory</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#ieee-library-pitfalls">IEEE library pitfalls</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#ieee-math-packages">IEEE math packages</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="index.html#document-Simulation_and_runtime">Simulation and runtime</a><ul> +<li class="toctree-l2"><a class="reference internal" href="index.html#simulation-options">Simulation options</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#debugging-vhdl-programs">Debugging VHDL programs</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="index.html#document-GHDL_implementation_of_VHDL">GHDL implementation of VHDL</a><ul> +<li class="toctree-l2"><a class="reference internal" href="index.html#vhdl-standards">VHDL standards</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#psl-implementation">PSL implementation</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#source-representation">Source representation</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#library-database">Library database</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#top-entity">Top entity</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#using-vendor-libraries">Using vendor libraries</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#interfacing-to-other-languages">Interfacing to other languages</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="index.html#document-GHDL_implementation_of_VITAL">GHDL implementation of VITAL</a><ul> +<li class="toctree-l2"><a class="reference internal" href="index.html#vital-packages">VITAL packages</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#vhdl-restrictions-for-vital">VHDL restrictions for VITAL</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#backannotation">Backannotation</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#negative-constraint-calculation">Negative constraint calculation</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="index.html#document-Flaws_and_bugs_report">Flaws and bugs report</a><ul> +<li class="toctree-l2"><a class="reference internal" href="index.html#reporting-bugs">Reporting bugs</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#future-improvements">Future improvements</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="index.html#document-Copyrights">Copyrights</a></li> +</ul> +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="index.html#document-index">Documentation overview</a><ul> + </ul></li> +</ul> +</div> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + ©2015, Tristan Gingold. + + | + Powered by <a href="http://sphinx-doc.org/">Sphinx 1.3.1</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.6</a> + + </div> + + + + + </body> +</html>
\ No newline at end of file diff --git a/doc/ghdl.texi b/doc/ghdl.texi new file mode 100644 index 0000000..e06f957 --- /dev/null +++ b/doc/ghdl.texi @@ -0,0 +1,3126 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename GHDL.info +@documentencoding UTF-8 +@ifinfo +@*Generated by Sphinx 1.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 0.33, November 24, 2015 + +Tristan Gingold + +Copyright @copyright{} 2015, Tristan Gingold +@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{0} +@c GHDL documentation master file, created by +@c sphinx-quickstart on Fri Nov 20 20:33:03 2015. +@c You can adapt this file completely to your liking, but it should at least +@c contain the root `toctree` directive. + +Contents: + +@menu +* Introduction:: +* Starting with GHDL:: +* Invoking GHDL:: +* Simulation and runtime:: +* GHDL implementation of VHDL:: +* GHDL implementation of VITAL:: +* Flaws and bugs report:: +* Copyrights:: +* Indices and tables:: +* Index:: + +@detailmenu + --- The Detailed Node Listing --- + +Introduction + +* Content of this manual:: +* What is VHDL?:: +* What is GHDL?:: + +Starting with GHDL + +* The hello world program:: +* A full adder:: +* Starting with a design:: + +Invoking GHDL + +* Building commands:: +* GHDL options:: +* Passing options to other programs:: +* GHDL warnings:: +* Rebuilding commands:: +* Library commands:: +* Cross-reference command:: +* File commands:: +* Misc commands:: +* Installation Directory:: +* IEEE library pitfalls:: +* IEEE math packages:: + +Building commands + +* Analysis command:: +* Elaboration command:: +* Run command:: +* Elaborate and run command:: +* Bind command:: +* Link command:: +* List link command:: +* Check syntax command:: +* Analyze and elaborate command:: + +Rebuilding commands + +* Import command:: +* Make command:: +* Generate Makefile command:: + +Library commands + +* Directory command:: +* Clean command:: +* Remove command:: +* Copy command:: +* Create a Library:: + +File commands + +* Pretty print command:: +* Find command:: +* Chop command:: +* Lines command:: + +Misc commands + +* Help command:: +* Disp config command:: +* Disp standard command:: +* Version command:: + +Simulation and runtime + +* Simulation options:: +* Debugging VHDL programs:: + +GHDL implementation of VHDL + +* VHDL standards:: +* PSL implementation:: +* Source representation:: +* Library database:: +* Top entity:: +* Using vendor libraries:: +* Interfacing to other languages:: + +Interfacing to other languages + +* Foreign declarations:: +* Restrictions on foreign declarations:: +* Linking with foreign object files:: +* Starting a simulation from a foreign program:: +* Linking with Ada:: +* Using GRT from Ada:: + +GHDL implementation of VITAL + +* VITAL packages:: +* VHDL restrictions for VITAL:: +* Backannotation:: +* Negative constraint calculation:: + +Flaws and bugs report + +* Reporting bugs:: +* Future improvements:: + +@end detailmenu +@end menu + +@node Introduction,Starting with GHDL,Top,Top +@anchor{Introduction welcome-to-ghdl-s-documentation}@anchor{1}@anchor{Introduction introduction}@anchor{2}@anchor{Introduction doc}@anchor{3} +@chapter Introduction + + +@menu +* Content of this manual:: +* What is VHDL?:: +* What is GHDL?:: + +@end menu + +@node Content of this manual,What is VHDL?,,Introduction +@anchor{Introduction content-of-this-manual}@anchor{4} +@section Content of this manual + + +This manual is the user and reference manual for GHDL. It does not +contain an introduction to VHDL. Thus, the reader should have at least +a basic knowledge of VHDL. A good knowledge of VHDL language reference +manual (usually called LRM) is a plus. + +@node What is VHDL?,What is GHDL?,Content of this manual,Introduction +@anchor{Introduction what-is-vhdl}@anchor{5} +@section What is @cite{VHDL}? + + +@cite{VHDL} is an acronym for Very High Speed Integrated Circuit Hardware +Description Language which is a programming language used to describe a +logic circuit by function, data flow behaviour, or structure. + +@cite{VHDL} @emph{is} a programming language: although @cite{VHDL} was +not designed for writing general purpose programs, you can write any +algorithm with the @cite{VHDL} language. If you are able to write +programs, you will find in @cite{VHDL} features similar to those found +in procedural languages such as @cite{C}, @cite{Python}, or @cite{Ada}. +@cite{VHDL} derives most of its syntax and semantics from @cite{Ada}. +Knowing @cite{Ada} is an advantage for learning @cite{VHDL} (it is an +advantage in general as well). + +However, @cite{VHDL} was not designed as a general purpose language but as an +@cite{HDL} (hardware description language). As the name implies, @cite{VHDL} +aims at modeling or documenting electronics systems. Due to the nature +of hardware components which are always running, @cite{VHDL} is a highly +concurrent language, built upon an event-based timing model. + +Like a program written in any other language, a @cite{VHDL} program +can be executed. Since @cite{VHDL} is used to model designs, the term +@emph{simulation} is often used instead of @cite{execution}, with the +same meaning. + +Like a program written in another hardware description language, a +@cite{VHDL} program can be transformed with a @emph{synthesis tool} +into a netlist, that is, a detailed gate-level implementation. + +@node What is GHDL?,,What is VHDL?,Introduction +@anchor{Introduction what-is-ghdl}@anchor{6} +@section What is @cite{GHDL}? + + +@cite{GHDL} is a shorthand for G Hardware Design Language. Currently, +@cite{G} has no meaning. + +@cite{GHDL} is a @cite{VHDL} compiler that can execute (nearly) any +@cite{VHDL} program. @cite{GHDL} is @emph{not} a synthesis tool: you cannot +create a netlist with @cite{GHDL}. + +Unlike some other simulators, @cite{GHDL} is a compiler: it directly +translates a @cite{VHDL} file to machine code, using the @cite{GCC} or @cite{LLVM} +back-end and without using an intermediary language such as @cite{C} +or @cite{C++}. Therefore, the compiled code should be faster and +the analysis time should be shorter than with a compiler using an +intermediary language. + +The Windows(TM) version of @cite{GHDL} is not based on @cite{GCC} but on +an internal code generator. + +The current version of @cite{GHDL} does not contain any graphical +viewer: you cannot see signal waves. You can still check with a test +bench. The current version can produce a @cite{VCD} file which can be +viewed with a wave viewer, as well as @cite{ghw} files to be viewed by +@cite{gtkwave}. + +@cite{GHDL} aims at implementing @cite{VHDL} as defined by IEEE 1076. +It supports most of the 1987 standard and most features added by the +1993 standard. + +@node Starting with GHDL,Invoking GHDL,Introduction,Top +@anchor{Starting_with_GHDL doc}@anchor{7}@anchor{Starting_with_GHDL starting-with-ghdl}@anchor{8} +@chapter Starting with GHDL + + +In this chapter, you will learn how to use the GHDL compiler by +working on two examples. + +@menu +* The hello world program:: +* A full adder:: +* Starting with a design:: + +@end menu + +@node The hello world program,A full adder,,Starting with GHDL +@anchor{Starting_with_GHDL the-hello-world-program}@anchor{9} +@section The hello world program + + +To illustrate the large purpose of VHDL, here is a commented VHDL +"Hello world" program. + +@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 + +Suppose this program is contained in the file @code{hello.vhdl}. +First, you have to compile the file; this is called @cite{analysis} of a design +file in VHDL terms. + +@example +$ ghdl -a hello.vhdl +@end example + +This command creates or updates a file @code{work-obj93.cf}, which +describes the library @cite{work}. On GNU/Linux, this command generates a +file @code{hello.o}, which is the object file corresponding to your +VHDL program. The object file is not created on Windows. + +Then, you have to build an executable file. + +@example +$ ghdl -e hello_world +@end example + +The @code{-e} option means @emph{elaborate}. With this option, @cite{GHDL} +creates code in order to elaborate a design, with the @code{hello} +entity at the top of the hierarchy. + +On GNU/Linux, the result is an executable program called @code{hello} +which can be run: + +@example +$ ghdl -r hello_world +@end example + +or directly: + +@example +$ ./hello_world +@end example + +On Windows, no file is created. The simulation is launched using this command: + +@example +> ghdl -r hello_world +@end example + +The result of the simulation appears on the screen: + +@example +Hello world! +@end example + +@node A full adder,Starting with a design,The hello world program,Starting with GHDL +@anchor{Starting_with_GHDL a-full-adder}@anchor{a} +@section A full adder + + +VHDL is generally used for hardware design. This example starts with +a full adder described in the @code{adder.vhdl} file: + +@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 assignment. + -- 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 analyze this design file: + +@example +$ ghdl -a adder.vhdl +@end example + +You can try to execute the @cite{adder} design, but this is useless, +since nothing externally visible will happen. In order to +check this full adder, a testbench has to be run. This testbench 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. The file @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 carray 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 design: + +@example +$ ghdl -a adder_tb.vhdl +@end example + +And build an executable for the testbench: + +@example +$ ghdl -e adder_tb +@end example + +You do not need to specify which object files are required: GHDL knows them +and automatically adds them in the executable. Now, it is time to run the +testbench: + +@example +$ ghdl -r adder_tb +adder_tb.vhdl:52:7:(assertion note): end of test +@end example + +If your design is rather complex, you'd like to inspect signals. Signals +value can be dumped using the VCD file format. The resulting file can be +read with a wave viewer such as GTKWave. First, you should simulate your +design and dump a waveform file: + +@example +$ ghdl -r adder_tb --vcd=adder.vcd +@end example + +Then, you may now view the waves: + +@example +$ gtkwave adder.vcd +@end example + +See @ref{b,,Simulation options}, for more details on the @ref{c,,--vcd} option and +other runtime options. + +@node Starting with a design,,A full adder,Starting with GHDL +@anchor{Starting_with_GHDL starting-with-a-design}@anchor{d} +@section Starting with a design + + +Unless you are only studying VHDL, you will work with bigger designs than +the ones of the previous examples. + +Let's see how to analyze and run a bigger 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 on +@indicateurl{http://ghdl.free.fr/dlx.tar.gz} + +First, untar the sources: + +@example +$ tar zxvf dlx.tar.gz +@end example + +In order not to pollute the sources with the library, it is a good idea +to create a @code{work/} subdirectory for the @cite{WORK} library. To +any GHDL commands, we will add the @code{--workdir=work} option, so +that all files generated by the compiler (except the executable) will be +placed in this directory. + +@example +$ cd dlx +$ mkdir work +@end example + +We will run the @code{dlx_test_behaviour} design. We need to analyze +all the design units for the design hierarchy, in the correct order. +GHDL provides an easy way to do this, by importing the sources: + +@example +$ ghdl -i --workdir=work *.vhdl +@end example + +and making a design: + +@example +$ ghdl -m --workdir=work dlx_test_behaviour +@end example + +Before this second stage, GHDL knows all the design units of the DLX, +but no one have been analyzed. The make command of GHDL analyzes and +elaborates a design. This creates many files in the @code{work/} +directory, and the @code{dlx_test_behaviour} executable in the current +directory. + +The simulation needs to have a DLX program contained in the file +@code{dlx.out}. This memory image will be be loaded in the DLX memory. +Just take one sample: + +@example +$ cp test_loop.out dlx.out +@end example + +And you can run the test suite: + +@example +$ ghdl -r dlx_test_behaviour +@end example + +The test bench monitors the bus and displays each instruction executed. +It finishes with an assertion of severity level note: + +@example +dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction + encountered, execution halted +@end example + +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 +test bench in batch mode. However, you may force the simulator to +stop when an assertion above or equal a certain severity level occurs: + +@example +$ ghdl -r dlx_test_behaviour --assert-level=note +@end example + +With this option, 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 + +If you want to make room on your hard drive, you can either: + + +@itemize * + +@item +clean the design library with the GHDL command: + +@example +$ ghdl --clean --workdir=work +@end example + +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 +remove the design library with the GHDL command: + +@example +$ ghdl --remove --workdir=work +@end example + +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 to make the design. + +@item +remove the @code{work/} directory: + +@example +$ rm -rf work +@end example + +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 + +Sometimes, a design does not fully follow the VHDL standards. For example it +uses the badly engineered @code{std_logic_unsigned} package. GHDL supports +this VHDL dialect through some options: + +@example +--ieee=synopsys -fexplicit +@end example + +See @ref{e,,IEEE library pitfalls}, for more details. + +@node Invoking GHDL,Simulation and runtime,Starting with GHDL,Top +@anchor{Invoking_GHDL invoking-ghdl}@anchor{f}@anchor{Invoking_GHDL doc}@anchor{10} +@chapter Invoking GHDL + + +The form of the @code{ghdl} command is: + +@example +ghdl command [options...] +@end example + +The GHDL program has several commands. The first argument selects +the command. The options are used to slightly modify the action. + +No option is allowed before the command. Except for the run command, +no option is allowed after a filename or a unit name. + +@menu +* Building commands:: +* GHDL options:: +* Passing options to other programs:: +* GHDL warnings:: +* Rebuilding commands:: +* Library commands:: +* Cross-reference command:: +* File commands:: +* Misc commands:: +* Installation Directory:: +* IEEE library pitfalls:: +* IEEE math packages:: + +@end menu + +@node Building commands,GHDL options,,Invoking GHDL +@anchor{Invoking_GHDL building-commands}@anchor{11} +@section Building commands + + +The mostly used commands of GHDL are those to analyze and elaborate a design. + +@menu +* Analysis command:: +* Elaboration command:: +* Run command:: +* Elaborate and run command:: +* Bind command:: +* Link command:: +* List link command:: +* Check syntax command:: +* Analyze and elaborate command:: + +@end menu + +@node Analysis command,Elaboration command,,Building commands +@anchor{Invoking_GHDL analysis-command}@anchor{12} +@subsection Analysis command + + +@geindex analysis + +@geindex *-a* command + +Analyze one or severals files: + +@example +ghdl -a [options...] file... +@end example + +The analysis command compiles one or more files, and creates an +object file for each source file. The analysis command is selected with +@code{-a} switch. 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 (the following files are not analyzed). + +See @ref{13,,GHDL options}, for details on the GHDL options. For example, +to produce debugging information such as line numbers, use: + +@example +ghdl -a -g my_design.vhdl +@end example + +@node Elaboration command,Run command,Analysis command,Building commands +@anchor{Invoking_GHDL id1}@anchor{14}@anchor{Invoking_GHDL elaboration-command}@anchor{15} +@subsection Elaboration command + + +@geindex elaboration + +@geindex *-e* command + +Elaborate a design: + +@example +ghdl -e [options..] primary_unit [secondary_unit] +@end example + +On GNU/Linux the elaboration command creates an executable +containing the code of the @cite{VHDL} sources, the elaboration code +and simulation code to execute a design hierarchy. On Windows this +command elaborates the design but does not generate anything. + +The elaboration command is selected with @code{-e} switch, and must be +followed by either: + + +@itemize * + +@item +a name of a configuration unit + +@item +a name of an entity unit + +@item +a name of an entity unit followed by a name of an architecture unit +@end itemize + +Name of the units must be a simple name, without any dot. You can +select the name of the @cite{WORK} library with the @code{--work=NAME} +option, as described in @ref{13,,GHDL options}. + +See @ref{16,,Top entity}, for the restrictions on the root design of a +hierarchy. + +On GNU/Linux the filename of the executable is the name of the +primary unit, or for the later case, the concatenation of the name of +the primary unit, a dash, and the name of the secondary unit (or +architecture). On Windows there is no executable generated. + +The @code{-o} followed by a filename can override the default +executable filename. + +For the elaboration command, @cite{GHDL} 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 objects files +required for the executable. Then, it links all these files with the +runtime library. + +The actual elaboration is performed at runtime. + +On Windows this command can be skipped because it is also done by the +run command. + +@node Run command,Elaborate and run command,Elaboration command,Building commands +@anchor{Invoking_GHDL run-command}@anchor{17}@anchor{Invoking_GHDL id2}@anchor{18} +@subsection Run command + + +@geindex run + +@geindex *-r* command + +Run (or simulate) a design: + +@example +ghdl -r [options...] primary_unit [secondary_unit] [simulation_options...] +@end example + +The options and arguments are the same as for the elaboration command, @ref{15,,Elaboration command}. + +On GNU/Linux this command simply determines the filename of the executable +and executes it. Options are ignored. You may also directly execute +the program. + +This command exists for three reasons: + + +@itemize * + +@item +You don't have to create the executable program name. + +@item +It is coherent with the @code{-a} and @code{-e} commands. + +@item +It works with the Windows implementation, where the code is generated in +memory. +@end itemize + +On Windows this command elaborates and launches the simulation. As a consequence +you must use the same options used during analysis. + +See @ref{19,,Simulation and runtime}, for details on options. + +@node Elaborate and run command,Bind command,Run command,Building commands +@anchor{Invoking_GHDL elaborate-and-run-command}@anchor{1a} +@subsection Elaborate and run command + + +@geindex elaborate and run + +@geindex *--elab-run* command + +Elaborate and then simulate a design unit: + +@example +ghdl --elab-run [elab_options...] primary_unit [secondary_unit] [run_options...] +@end example + +This command acts like the elaboration command (see @ref{15,,Elaboration command}) +followed by the run command (see @ref{17,,Run command}). + +@node Bind command,Link command,Elaborate and run command,Building commands +@anchor{Invoking_GHDL bind-command}@anchor{1b}@anchor{Invoking_GHDL id3}@anchor{1c} +@subsection Bind command + + +@geindex binding + +@geindex *--bind* command + +Bind a design unit and prepare the link step: + +@example +ghdl --bind [options] primary_unit [secondary_unit] +@end example + +This command is only available on GNU/Linux. + +This performs only the first stage of the elaboration command; the list +of objects files is created but the executable is not built. This +command should be used only when the main entry point is not ghdl. + +@node Link command,List link command,Bind command,Building commands +@anchor{Invoking_GHDL link-command}@anchor{1d}@anchor{Invoking_GHDL id4}@anchor{1e} +@subsection Link command + + +@geindex linking + +@geindex *--link* command + +Link an already bound design unit: + +@example +ghdl --link [options] primary_unit [secondary_unit] +@end example + +This performs only the second stage of the elaboration command: the +executable is created by linking the files of the object files list. +This command is available only for completeness. The elaboration command is +equivalent to the bind command followed by the link command. + +@node List link command,Check syntax command,Link command,Building commands +@anchor{Invoking_GHDL list-link-command}@anchor{1f}@anchor{Invoking_GHDL id5}@anchor{20} +@subsection List link command + + +@geindex *--list-link* command + +Display files which will be linked: + +@example +ghdl --list-link primary_unit [secondary_unit] +@end example + +This command is only available on GNU/Linux. + +This command may be used only after a bind command. GHDL displays all +the files which will be linked to create an executable. This command is +intended to add object files in a link of a foreign program. + +@node Check syntax command,Analyze and elaborate command,List link command,Building commands +@anchor{Invoking_GHDL id6}@anchor{21}@anchor{Invoking_GHDL check-syntax-command}@anchor{22} +@subsection Check syntax command + + +@geindex checking syntax + +@geindex *-s* command + +Analyze files but do not generate code: + +@example +ghdl -s [options] files +@end example + +This command may be used to check the syntax of files. It does not update +the library. + +@node Analyze and elaborate command,,Check syntax command,Building commands +@anchor{Invoking_GHDL analyze-and-elaborate-command}@anchor{23}@anchor{Invoking_GHDL id7}@anchor{24} +@subsection Analyze and elaborate command + + +@geindex Analyze and elaborate command + +@geindex *-c* command + +Analyze files and elaborate them at the same time. + +On GNU/Linux: + +@example +ghdl -c [options] file... -e primary_unit [secondary_unit] +@end example + +On Windows: + +@example +ghdl -c [options] file... -r primary_unit [secondary_unit] +@end example + +This command combines analysis and elaboration: files are analyzed and +the unit is then elaborated. However, code is only generated during the +elaboration. On Windows the simulation is launched. + +To be more precise, the files are first parsed, and then the elaboration +drives the analysis. Therefore, there is no analysis order, and you don't +need to care about it. + +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 smaller executable, since unused units and subprograms +do not generate code. +@end itemize + +However, you should know that currently most of the time is spent in code +generation and the analyze and elaborate command generate 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. + +This command is still experimental. In case of problems, you should go back +to the traditional way. + +@node GHDL options,Passing options to other programs,Building commands,Invoking GHDL +@anchor{Invoking_GHDL ghdl-options}@anchor{13}@anchor{Invoking_GHDL id8}@anchor{25} +@section GHDL options + + +@geindex IEEE 1164 + +@geindex 1164 + +@geindex IEEE 1076.3 + +@geindex 1076.3 + +Besides the options described below, @cite{GHDL} passes any debugging options +(those that begin with @code{-g}) and optimizations options (those that +begin with @code{-O} or @code{-f}) to @cite{GCC}. Refer to the @cite{GCC} +manual for details. + +@c option::--work=<NAME> +@c +@c .. index:: WORK library +@c +@c Specify the name of the :samp:`WORK` library. Analyzed units are always +@c placed in the library logically named :samp:`WORK`. With this option, +@c you can set its name. By default, the name is :samp:`work`. +@c +@c `GHDL` checks whether :samp:`WORK` is a valid identifier. Although being +@c more or less supported, the :samp:`WORK` identifier should not be an +@c extended identifier, since the filesystem may prevent it from correctly +@c working (due to case sensitivity or forbidden characters in filenames). +@c +@c `VHDL` rules forbid you to add units to the :samp:`std` library. +@c Furthermore, you should not put units in the :samp:`ieee` library. + +@geindex command line option; --workdir=<DIR> +@anchor{Invoking_GHDL cmdoption--workdir}@anchor{26} +@deffn {Option} @w{-}@w{-}workdir=<DIR> + +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{27,,-P} to specify where libraries other than @code{WORK} +are placed. +@end deffn + +@geindex command line option; --std=<STD> +@anchor{Invoking_GHDL cmdoption--std}@anchor{28} +@deffn {Option} @w{-}@w{-}std=<STD> + +Specify the standard to use. By default, the standard is @code{93c}, which +means VHDL-93 accepting VHDL-87 syntax. For details on @code{STD} values see +@ref{29,,VHDL standards}. +@end deffn + +@geindex command line option; --ieee=<VER> +@anchor{Invoking_GHDL cmdoption--ieee}@anchor{2a} +@deffn {Option} @w{-}@w{-}ieee=<VER> + +@geindex ieee library + +@geindex synopsys library + +@geindex mentor library + +Select the @code{IEEE} library to use. @code{VER} 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 by your own a 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 +packages @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 @ref{2b,,VITAL packages}, +for more details. + +@item synopsys + +Supply the former packages and the following additional packages: +@code{std_logic_arith}, @code{std_logic_signed}, +@code{std_logic_unsigned}, @code{std_logic_textio}. + +These 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}. + +@item mentor + +Supply the standard packages and the following additional package: +@code{std_logic_arith}. The package is a slight variation of a definitely +not standard but widely mis-used package. +@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 command line option; -P<DIRECTORY> +@anchor{Invoking_GHDL cmdoption-P}@anchor{27} +@deffn {Option} @w{-}P<DIRECTORY> + +Add @cite{DIRECTORY} to the end of the list of directories to be searched for +library files. + +The @cite{WORK} library is always searched in the path specified by the +@code{--workdir=} option, or in the current directory if the latter +option is not specified. +@end deffn + +@geindex command line option; -fexplicit +@anchor{Invoking_GHDL cmdoption-fexplicit}@anchor{2c} +@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 @ref{e,,IEEE library pitfalls}, for an example. + +This option is not set by default. I 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 better to fix +your design and use the @code{numeric_std} package. +@end deffn + +@geindex command line option; -frelaxed-rules +@anchor{Invoking_GHDL cmdoption-frelaxed-rules}@anchor{2d} +@deffn {Option} @w{-}frelaxed@w{-}rules + +Within an object declaration, allow to reference 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 valid. + +(The scope of the @code{state1} constant start at the @cite{constant} +word. Because the constant @code{state1} and the enumeration literal +@code{state1} are homograph, the enumeration literal is hidden in the +immediate scope of the constant). +@end deffn + +@geindex command line option; -fpsl +@anchor{Invoking_GHDL cmdoption-fpsl}@anchor{2e} +@deffn {Option} @w{-}fpsl + +Enable parsing of PSL assertions within comments. See @ref{2f,,PSL implementation}, +for more details. +@end deffn + +@geindex command line option; --no-vital-checks +@anchor{Invoking_GHDL cmdoption--no-vital-checks}@anchor{30} +@deffn {Option} @w{-}@w{-}no@w{-}vital@w{-}checks +@end deffn + +@geindex command line option; --vital-checks +@anchor{Invoking_GHDL cmdoption--vital-checks}@anchor{31} +@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 +@ref{32,,VHDL restrictions for VITAL}, for more details. +@end deffn + +@geindex command line option; --syn-binding +@anchor{Invoking_GHDL cmdoption--syn-binding}@anchor{33} +@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 synthesizer rule. + +There are two key points: normal VHDL LRM rules are tried first and +entities are searched only in known library. A known library is a +library which has been named in your design. + +This option is only useful during elaboration. +@end deffn + +@geindex command line option; --PREFIX=<PATH> +@anchor{Invoking_GHDL cmdoption--PREFIX}@anchor{34} +@deffn {Option} @w{-}@w{-}PREFIX=<PATH> + +Use @code{PATH} as the prefix path to find commands and pre-installed (std and +ieee) libraries. +@end deffn + +@geindex command line option; --GHDL1=<COMMAND> +@anchor{Invoking_GHDL cmdoption--GHDL1}@anchor{35} +@deffn {Option} @w{-}@w{-}GHDL1=<COMMAND> + +Use @code{COMMAND} as the command name for the compiler. If @code{COMMAND} is +not a path, then it is search in the list of program directories. +@end deffn + +@geindex command line option; -v +@anchor{Invoking_GHDL cmdoption-v}@anchor{36} +@deffn {Option} @w{-}v + +Be verbose. For example, for analysis, elaboration and make commands, GHDL +displays the commands executed. +@end deffn + +@node Passing options to other programs,GHDL warnings,GHDL options,Invoking GHDL +@anchor{Invoking_GHDL passing-options-to-other-programs}@anchor{37} +@section Passing options to other programs + + +These options are only available on GNU/Linux. + +For many commands, @cite{GHDL} acts as a driver: it invokes programs to perform +the command. You can pass arbitrary options to these programs. + +Both the compiler and the linker are in fact GCC programs. See the +GCC manual for details on GCC options. + +@geindex command line option; -Wc@comma{}<OPTION> +@anchor{Invoking_GHDL cmdoption-Wc}@anchor{38} +@deffn {Option} @w{-}Wc,<OPTION> + +Pass @cite{OPTION} as an option to the compiler. +@end deffn + +@geindex command line option; -Wa@comma{}<OPTION> +@anchor{Invoking_GHDL cmdoption-Wa}@anchor{39} +@deffn {Option} @w{-}Wa,<OPTION> + +Pass @cite{OPTION} as an option to the assembler. +@end deffn + +@geindex command line option; -Wl@comma{}<OPTION> +@anchor{Invoking_GHDL cmdoption-Wl}@anchor{3a} +@deffn {Option} @w{-}Wl,<OPTION> + +Pass @cite{OPTION} as an option to the linker. +@end deffn + +@node GHDL warnings,Rebuilding commands,Passing options to other programs,Invoking GHDL +@anchor{Invoking_GHDL ghdl-warnings}@anchor{3b} +@section GHDL 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. + +You could disable a warning by using the @code{--warn-no-XXX} +instead of @code{--warn-XXX}. + +@geindex command line option; --warn-reserved +@anchor{Invoking_GHDL cmdoption--warn-reserved}@anchor{3c} +@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 command line option; --warn-default-binding +@anchor{Invoking_GHDL cmdoption--warn-default-binding}@anchor{3d} +@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 component if you don't use +configuration. @ref{29,,VHDL standards}, for more details about default binding +rules. +@end deffn + +@geindex command line option; --warn-binding +@anchor{Invoking_GHDL cmdoption--warn-binding}@anchor{3e} +@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 even 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 command line option; --warn-library +@anchor{Invoking_GHDL cmdoption--warn-library}@anchor{3f} +@deffn {Option} @w{-}@w{-}warn@w{-}library + +Warns if a design unit replaces another design unit with the same name. +@end deffn + +@geindex command line option; --warn-vital-generic +@anchor{Invoking_GHDL cmdoption--warn-vital-generic}@anchor{40} +@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 command line option; --warn-delayed-checks +@anchor{Invoking_GHDL cmdoption--warn-delayed-checks}@anchor{41} +@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 statement in a procedure called in a +sensitized process and checks for pure rules of a function. +@end deffn + +@geindex command line option; --warn-body +@anchor{Invoking_GHDL cmdoption--warn-body}@anchor{42} +@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 command line option; --warn-specs +@anchor{Invoking_GHDL cmdoption--warn-specs}@anchor{43} +@deffn {Option} @w{-}@w{-}warn@w{-}specs + +Emit a warning if an all or others specification does not apply. +@end deffn + +@geindex command line option; --warn-unused +@anchor{Invoking_GHDL cmdoption--warn-unused}@anchor{44} +@deffn {Option} @w{-}@w{-}warn@w{-}unused + +Emit a warning when a subprogram is never used. +@end deffn + +@geindex command line option; --warn-error +@anchor{Invoking_GHDL cmdoption--warn-error}@anchor{45} +@deffn {Option} @w{-}@w{-}warn@w{-}error + +When this option is set, warnings are considered as errors. +@end deffn + +@node Rebuilding commands,Library commands,GHDL warnings,Invoking GHDL +@anchor{Invoking_GHDL rebuilding-commands}@anchor{46} +@section Rebuilding commands + + +Analyzing and elaborating a design consisting in several files can be tricky, +due to dependencies. GHDL has a few commands to rebuild a design. + +@menu +* Import command:: +* Make command:: +* Generate Makefile command:: + +@end menu + +@node Import command,Make command,,Rebuilding commands +@anchor{Invoking_GHDL import-command}@anchor{47} +@subsection Import command + + +@geindex importing files + +@geindex *-i* command + +Add files in the work design library: + +@example +ghdl -i [options] file... +@end example + +All the files specified in the command line are scanned, parsed and added in +the libraries but as not yet analyzed. No object files are created. + +The purpose of this command 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. + +Since the files are parsed, there must be correct files. However, since they +are not analyzed, many errors are tolerated by this command. + +Note that all the files are added to the work library. If you have many +libraries, you must use the command for each library. + +See @ref{48,,Make command}, to actually build the design. + +@node Make command,Generate Makefile command,Import command,Rebuilding commands +@anchor{Invoking_GHDL make-command}@anchor{48}@anchor{Invoking_GHDL id9}@anchor{49} +@subsection Make command + + +@geindex make + +@geindex *-m* command + +Analyze automatically outdated files and elaborate a design: + +@example +ghdl -m [options] primary [secondary] +@end example + +The primary unit denoted by the @code{primary} 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. GHDL analyzes +all outdated files. A file may be outdated because it has been modified +(e.g. you just have edited it), or because a design unit contained in +the file depends on a unit which is outdated. This rule is of course +recursive. + +With the @code{-f} (force) option, GHDL analyzes all the units of the +work library needed to create the design hierarchy. Not outdated units +are recompiled. This is useful if you want to compile a design hierarchy +with new compilation flags (for example, to add the @emph{-g} +debugging option). + +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. + +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 file. 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. + +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. + +@node Generate Makefile command,,Make command,Rebuilding commands +@anchor{Invoking_GHDL generate-makefile-command}@anchor{4a} +@subsection Generate Makefile command + + +@geindex *--gen-makefile* command + +Generate a Makefile to build a design unit: + +@example +ghdl --gen-makefile [options] primary [secondary] +@end example + +This command works like the make command (see @ref{48,,Make command}), but only a +makefile is generated on the standard output. + +@node Library commands,Cross-reference command,Rebuilding commands,Invoking GHDL +@anchor{Invoking_GHDL library-commands}@anchor{4b} +@section Library commands + + +GHDL has a few commands which act on a library. + +@menu +* Directory command:: +* Clean command:: +* Remove command:: +* Copy command:: +* Create a Library:: + +@end menu + +@node Directory command,Clean command,,Library commands +@anchor{Invoking_GHDL directory-command}@anchor{4c} +@subsection Directory command + + +@geindex displaying library + +@geindex *-d* command + +Display the name of the units contained in a design library: + +@example +ghdl -d [options] +@end example + +The directory command, selected with the @cite{-d} command line argument +displays the content of the work design library. All options are +allowed, but only a few are meaningful: @code{--work=NAME}, +@code{--workdir=PATH} and @code{--std=VER}. + +@node Clean command,Remove command,Directory command,Library commands +@anchor{Invoking_GHDL clean-command}@anchor{4d} +@subsection Clean command + + +@geindex cleaning + +@geindex *--clean* command + +Remove object and executable files but keep the library: + +@example +ghdl --clean [options] +@end example + +GHDL tries to remove any object, executable or temporary file it could +have created. Source files are not removed. + +There is no short command line form for this option to prevent accidental +clean up. + +@node Remove command,Copy command,Clean command,Library commands +@anchor{Invoking_GHDL id10}@anchor{4e}@anchor{Invoking_GHDL remove-command}@anchor{4f} +@subsection Remove command + + +@geindex cleaning all + +@geindex *--remove* command + +Do like the clean command but remove the library too: + +@example +ghdl --remove [options] +@end example + +There is no short command line form for this option to prevent accidental +clean up. Note that after removing a design library, the files are not +known anymore by GHDL. + +@node Copy command,Create a Library,Remove command,Library commands +@anchor{Invoking_GHDL id11}@anchor{50}@anchor{Invoking_GHDL copy-command}@anchor{51} +@subsection Copy command + + +@geindex copying library + +@geindex *--copy* command + +Make a local copy of an existing library: + +@example +ghdl --copy --work=name [options] +@end example + +Make a local copy of an existing library. This is very useful if you want to +add unit to the @code{ieee} library: + +@example +ghdl --copy --work=ieee --ieee=synopsys +ghdl -a --work=ieee numeric_unsigned.vhd +@end example + +@node Create a Library,,Copy command,Library commands +@anchor{Invoking_GHDL id12}@anchor{52}@anchor{Invoking_GHDL create-a-library}@anchor{53} +@subsection Create a Library + + +@geindex create your own library + +A new library is created by compiling entities (packages etc.) into it: + +@example +ghdl -a --work=my_custom_lib my_file.vhd +@end example + +A library's source code is usually stored and compiled into its own directory, +that you specify with the @ref{26,,--workdir} option: + +@example +ghdl -a --work=my_custom_lib --workdir=my_custom_libdir my_custom_lib_srcdir/my_file.vhd +@end example + +See also the @code{-PPATH} command line option. + +@node Cross-reference command,File commands,Library commands,Invoking GHDL +@anchor{Invoking_GHDL id13}@anchor{54}@anchor{Invoking_GHDL cross-reference-command}@anchor{55} +@section Cross-reference command + + +To easily navigate through your sources, you may generate cross-references: + +@example +ghdl --xref-html [options] file... +@end example + +This command generates an html file for each @code{file} given in the command +line, with syntax highlighting and full cross-reference: every identifier is +a link to its declaration. Besides, an index of the files is created too. + +The set of @code{file} are analyzed, and then, if the analysis is +successful, html files are generated in the directory specified by the +@code{-o dir} option, or @code{html/} directory by default. + +If the option @code{--format=html2} is specified, then the generated html +files follow the HTML 2.0 standard, and colours are specified with +@cite{<FONT>} tags. However, colours are hard-coded. + +If the option @code{--format=css} is specified, then the generated html 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. + +@node File commands,Misc commands,Cross-reference command,Invoking GHDL +@anchor{Invoking_GHDL file-commands}@anchor{56} +@section File commands + + +The following commands act on one or several files. They do not analyze +files, therefore, they work even if a file has semantic errors. + +@menu +* Pretty print command:: +* Find command:: +* Chop command:: +* Lines command:: + +@end menu + +@node Pretty print command,Find command,,File commands +@anchor{Invoking_GHDL pretty-print-command}@anchor{57} +@subsection Pretty print command + + +@geindex *--pp-html* command + +@geindex pretty printing + +@geindex vhdl to html + +Generate HTML on standard output from VHDL: + +@example +ghdl --pp-html [options] file... +@end example + +The files are just scanned and an html file, with syntax highlighting is +generated on standard output. + +Since the files are not even parsed, erroneous files or incomplete designs +can be pretty printed. + +The style of the html file can be modified with the @code{--format=} option. +By default or when the @code{--format=html2} option is specified, the output +is an HTML 2.0 file, with colours set through @cite{<FONT>} tags. When the +@code{--format=css} option is specified, the output is an HTML 4.0 file, +with colours set through a CSS file, whose name is @code{ghdl.css}. +See @ref{55,,Cross-reference command}, for more details about this CSS file. + +@node Find command,Chop command,Pretty print command,File commands +@anchor{Invoking_GHDL find-command}@anchor{58} +@subsection Find command + + +@geindex *-f* command + +Display the name of the design units in files: + +@example +ghdl -f file... +@end example + +The files are scanned, parsed and the names of design units are displayed. +Design units marked with two stars are candidate to be at the apex of a +design hierarchy. + +@node Chop command,Lines command,Find command,File commands +@anchor{Invoking_GHDL chop-command}@anchor{59} +@subsection Chop command + + +@geindex *--chop* command + +Chop (or split) files at design unit: + +@example +ghdl --chop files +@end example + +@cite{GHDL} reads files, and writes a file in the current directory for +every design unit. + +The filename of a design unit is build according to the unit. For an +entity declaration, a package declaration or a configuration the file +name is @code{NAME.vhdl}, where @cite{NAME} is the name of the design +unit. For a package body, the filename is @code{NAME-body.vhdl}. +Finally, for an architecture @cite{ARCH} of an entity @cite{ENTITY}, the +filename is @code{ENTITY-ARCH.vhdl}. + +Since the input files are parsed, this command aborts in case of syntax +error. The command aborts too if a file to be written already exists. + +Comments between design units are stored into the most adequate files. + +This command may be useful to split big files, if your computer has not +enough memory to compile such files. The size of the executable is +reduced too. + +@node Lines command,,Chop command,File commands +@anchor{Invoking_GHDL lines-command}@anchor{5a} +@subsection Lines command + + +@geindex *--lines* command + +Display on the standard output lines of files preceded by line number: + +@example +ghdl --lines files +@end example + +@node Misc commands,Installation Directory,File commands,Invoking GHDL +@anchor{Invoking_GHDL misc-commands}@anchor{5b} +@section Misc commands + + +There are a few GHDL commands which are seldom useful. + +@menu +* Help command:: +* Disp config command:: +* Disp standard command:: +* Version command:: + +@end menu + +@node Help command,Disp config command,,Misc commands +@anchor{Invoking_GHDL id14}@anchor{5c}@anchor{Invoking_GHDL help-command}@anchor{5d} +@subsection Help command + + +@geindex *-h* command + +@geindex *--help* command + +Display (on the standard output) a short description of the all the commands +available. If the help switch is followed by a command switch, then options +for this later command are displayed: + +@example +ghdl --help +ghdl -h +ghdl -h command +@end example + +@node Disp config command,Disp standard command,Help command,Misc commands +@anchor{Invoking_GHDL disp-config-command}@anchor{5e}@anchor{Invoking_GHDL id15}@anchor{5f} +@subsection Disp config command + + +@geindex *--disp-config* command + +@geindex display configuration + +Display the program paths and options used by GHDL: + +@example +ghdl --disp-config [options] +@end example + +This may be useful to track installation errors. + +@node Disp standard command,Version command,Disp config command,Misc commands +@anchor{Invoking_GHDL disp-standard-command}@anchor{60} +@subsection Disp standard command + + +@geindex *--disp-standard* command + +@geindex display ;samp;`std.standard` + +Display the @code{std.standard} package: + +@example +ghdl --disp-standard [options] +@end example + +@node Version command,,Disp standard command,Misc commands +@anchor{Invoking_GHDL version-command}@anchor{61} +@subsection Version command + + +@geindex *--version* command + +@geindex version + +Display the @cite{GHDL} version and exit: + +@example +ghdl --version +@end example + +@node Installation Directory,IEEE library pitfalls,Misc commands,Invoking GHDL +@anchor{Invoking_GHDL installation-directory}@anchor{62} +@section Installation Directory + + +During analysis and elaboration @cite{GHDL} may read the @cite{std} +and @cite{ieee} files. The location of these files is based on the prefix, +which is (in priority order): + + +@itemize * + +@item +the @code{--PREFIX=} command line option + +@item +the +@geindex GHDL_PREFIX +@geindex environment variable; GHDL_PREFIX +@code{GHDL_PREFIX} environment variable + +@item +a built-in default path. It is a hard-coded path on GNU/Linux and the +value of the @code{HKLMSoftwareGhdlInstall_Dir} registry entry on Windows. +@end itemize + +You should use the @code{--disp-config} command (@ref{5e,,Disp config command} for details) to disp and debug installation problems. + +@node IEEE library pitfalls,IEEE math packages,Installation Directory,Invoking GHDL +@anchor{Invoking_GHDL ieee-library-pitfalls}@anchor{e}@anchor{Invoking_GHDL id16}@anchor{63} +@section IEEE library pitfalls + + +When you use options @code{--ieee=synopsys} or @code{--ieee=mentor}, +the @cite{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, their use has pitfalls. For +example, this description has 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 (too 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 semantic of an unsigned comparison. + +With some analyser, 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. +@ref{13,,GHDL options}, for more 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 +provides 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 + +@node IEEE math packages,,IEEE library pitfalls,Invoking GHDL +@anchor{Invoking_GHDL ieee-math-packages}@anchor{64} +@section IEEE math packages + + +@geindex Math_Real + +@geindex Math_Complex + +The @code{ieee} math packages (@code{math_real} and +@code{math_complex}) provided with @cite{GHDL} are fully compliant with +the @cite{IEEE} standard. + +@node Simulation and runtime,GHDL implementation of VHDL,Invoking GHDL,Top +@anchor{Simulation_and_runtime simulation-and-runtime}@anchor{19}@anchor{Simulation_and_runtime doc}@anchor{65}@anchor{Simulation_and_runtime id1}@anchor{66} +@chapter Simulation and runtime + + +@menu +* Simulation options:: +* Debugging VHDL programs:: + +@end menu + +@node Simulation options,Debugging VHDL programs,,Simulation and runtime +@anchor{Simulation_and_runtime simulation-options}@anchor{b}@anchor{Simulation_and_runtime id2}@anchor{67} +@section Simulation options + + +In most system environments, it is possible to pass 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. + +In GHDL, it is impossible to pass parameters to your design. A later version +could do it through the generics interfaces of the top entity. + +However, the GHDL runtime behaviour can be modified with some options; for +example, it is possible to stop simulation after a certain time. + +The exit status of the simulation is @code{EXIT_SUCCESS} (0) if the +simulation completes, or @code{EXIT_FAILURE} (1) in case of error +(assertion failure, overflow or any constraint error). + +Here is the list of the most useful options. Some debugging options are +also available, but not described here. The @ref{68,,--help} options lists +all options available, including the debugging one. + +@geindex command line option; --assert-level=<LEVEL> +@anchor{Simulation_and_runtime cmdoption--assert-level}@anchor{69} +@deffn {Option} @w{-}@w{-}assert@w{-}level=<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 @code{--assert-level=none} prevents any assertion violation to stop +simulation. +@end deffn + +@geindex command line option; --ieee-asserts=<POLICY> +@anchor{Simulation_and_runtime cmdoption--ieee-asserts}@anchor{6a} +@deffn {Option} @w{-}@w{-}ieee@w{-}asserts=<POLICY> + +Select how the assertions from @code{ieee} units are +handled. @cite{POLICY} can be @code{enable} (the default), +@code{disable} which disables all assertion from @code{ieee} packages +and @code{disable-at-0} which disables only at start of simulation. + +This option can be useful to avoid assertion message from +@code{ieee.numeric_std} (and other @code{ieee} packages). +@end deffn + +@geindex command line option; --stop-time=<TIME> +@anchor{Simulation_and_runtime cmdoption--stop-time}@anchor{6b} +@deffn {Option} @w{-}@w{-}stop@w{-}time=<TIME> + +Stop the simulation after @code{TIME}. @code{TIME} is expressed as a time +value, @emph{without} any space. The time is the simulation time, not +the real clock time. + +For example: + +@example +$ ./my_design --stop-time=10ns +$ ./my_design --stop-time=ps +@end example +@end deffn + +@geindex command line option; --stop-delta=<N> +@anchor{Simulation_and_runtime cmdoption--stop-delta}@anchor{6c} +@deffn {Option} @w{-}@w{-}stop@w{-}delta=<N> + +Stop the simulation after @cite{N} delta cycles in the same current time. + +@geindex display time +@end deffn + +@geindex command line option; --disp-time +@anchor{Simulation_and_runtime cmdoption--disp-time}@anchor{6d} +@deffn {Option} @w{-}@w{-}disp@w{-}time + +Display the time and delta cycle number as simulation advances. +@end deffn + +@geindex command line option; --disp-tree[=<KIND>] +@anchor{Simulation_and_runtime cmdoption--disp-tree}@anchor{6e} +@deffn {Option} @w{-}@w{-}disp@w{-}tree[=<KIND>] + +@geindex display design hierarchy + +Display the design hierarchy as a tree of instantiated design entities. +This may be useful to understand the structure of a complex +design. @cite{KIND} is optional, but if set must be one of: + + +@itemize * + +@item +none +Do not display hierarchy. Same as if the option was not present. + +@item +inst +Display entities, architectures, instances, blocks and generates statements. + +@item +proc +Like @code{inst} but also display processes. + +@item +port +Like @code{proc} but display ports and signals too. +If @cite{KIND} is not specified, the hierarchy is displayed with the +@code{port} mode. +@end itemize +@end deffn + +@geindex command line option; --no-run +@anchor{Simulation_and_runtime cmdoption--no-run}@anchor{6f} +@deffn {Option} @w{-}@w{-}no@w{-}run + +Do not simulate, only elaborate. This may be used with +@ref{6e,,--disp-tree} to display the tree without simulating the whole +design. +@end deffn + +@geindex command line option; --vcd=<FILENAME> +@anchor{Simulation_and_runtime cmdoption--vcd}@anchor{c} +@deffn {Option} @w{-}@w{-}vcd=<FILENAME> +@end deffn + +@geindex command line option; --vcdgz=<FILENAME> +@anchor{Simulation_and_runtime cmdoption--vcdgz}@anchor{70} +@deffn {Option} @w{-}@w{-}vcdgz=<FILENAME> + +@geindex vcd + +@geindex value change dump + +@geindex dump of signals + +Option @ref{c,,--vcd} dumps into the VCD file @cite{FILENAME} the signal +values before each non-delta cycle. If @cite{FILENAME} is @code{-}, +then the standard output is used, otherwise a file is created or +overwritten. + +The @ref{70,,--vcdgz} option is the same as the @emph{--vcd} option, +but the output is compressed using the @cite{zlib} (@cite{gzip} +compression). However, you can't use the @code{-} filename. +Furthermore, only one VCD file can be written. + +@emph{VCD} (value change dump) is a file format defined +by the @cite{verilog} standard and used by virtually any wave viewer. + +Since it comes from @cite{verilog}, only a few VHDL types can be dumped. GHDL +dumps only signals whose base type is of the following: + + +@itemize * + +@item +types defined in the @code{std.standard} package: + +@item +@code{bit} + +@item +@code{bit_vector} + +@item +types defined in the @code{ieee.std_logic_1164} package: + +@item +@code{std_ulogic} + +@item +@code{std_logic} (because it is a subtype of @code{std_ulogic}) + +@item +@code{std_ulogic_vector} + +@item +@code{std_logic_vector} + +@item +any integer type +@end itemize + +I have successfully used @cite{gtkwave} to view VCD files. + +Currently, there is no way to select signals to be dumped: all signals are +dumped, which can generate big files. + +It is very unfortunate there is no standard or well-known wave file +format supporting VHDL types. If you are aware of such a free format, +please mail me (@ref{71,,Reporting bugs}). +@end deffn + +@geindex command line option; --fst=<FILENAME> +@anchor{Simulation_and_runtime cmdoption--fst}@anchor{72} +@deffn {Option} @w{-}@w{-}fst=<FILENAME> + +Write the waveforms into a @cite{fst}, that can be displayed by +@cite{gtkwave}. The @cite{fst} files are much smaller than VCD or +@cite{GHW} files, but it handles only the same signals as the VCD format. +@end deffn + +@geindex command line option; --wave=<FILENAME> +@anchor{Simulation_and_runtime cmdoption--wave}@anchor{73} +@deffn {Option} @w{-}@w{-}wave=<FILENAME> + +Write the waveforms into a @cite{ghw} (GHdl Waveform) file. Currently, all +the signals are dumped into the waveform file, you cannot select a hierarchy +of signals to be dumped. + +The format of this file was defined by myself and is not yet completely fixed. +It may change slightly. The @code{gtkwave} tool can read the GHW files. + +Contrary to VCD files, any VHDL type can be dumped into a GHW file. +@end deffn + +@geindex command line option; --sdf=<PATH>=<FILENAME> +@anchor{Simulation_and_runtime cmdoption--sdf}@anchor{74} +@deffn {Option} @w{-}@w{-}sdf=<PATH>=<FILENAME> + +Do VITAL annotation on @cite{PATH} with SDF file @code{FILENAME}. + +@cite{PATH} is a path of instances, separated with @code{.} or @code{/}. +Any separator can be used. Instances are component instantiation labels, +generate labels or block labels. Currently, you cannot use an indexed name. + +Specifying a delay: + +@example +--sdf=min=<PATH>=<FILENAME> +--sdf=typ=<PATH>=<FILENAME> +--sdf=max=<PATH>=<FILENAME> +@end example + +If the option contains a type of delay, that is @code{min=}, +@code{typ=} or @code{max=}, the annotator use respectively minimum, +typical or maximum values. If the option does not contain a type of delay, +the annotator use the typical delay. + +See @ref{75,,Backannotation}, for more details. +@end deffn + +@geindex command line option; --help +@anchor{Simulation_and_runtime cmdoption--help}@anchor{68} +@deffn {Option} @w{-}@w{-}help + +Display a short description of the options accepted by the runtime library. +@end deffn + +@node Debugging VHDL programs,,Simulation options,Simulation and runtime +@anchor{Simulation_and_runtime debugging-vhdl-programs}@anchor{76} +@section Debugging VHDL programs + + +@geindex debugging + +@geindex `__ghdl_fatal` + +Debugging VHDL programs using @cite{GDB} is possible only on GNU/Linux systems. + +@cite{GDB} is a general purpose debugger for programs compiled by @cite{GCC}. +Currently, there is no VHDL support for @cite{GDB}. It may be difficult +to inspect variables or signals in @cite{GDB}, however, @cite{GDB} is +still able to display the stack frame in case of error or to set a breakpoint +at a specified line. + +@cite{GDB} can be useful to precisely catch a runtime error, such as indexing +an array beyond its bounds. All error check subprograms call the +@cite{__ghdl_fatal} procedure. Therefore, to catch runtime error, set +a breakpoint like this: + +@quotation + +(gdb) break __ghdl_fatal +@end quotation + +When the breakpoint is hit, use the @cite{where} or @cite{bt} command to +display the stack frames. + +@node GHDL implementation of VHDL,GHDL implementation of VITAL,Simulation and runtime,Top +@anchor{GHDL_implementation_of_VHDL doc}@anchor{77}@anchor{GHDL_implementation_of_VHDL ghdl-implementation-of-vhdl}@anchor{78} +@chapter GHDL implementation of VHDL + + +This chapter describes several implementation defined aspect of VHDL in GHDL. + +@menu +* VHDL standards:: +* PSL implementation:: +* Source representation:: +* Library database:: +* Top entity:: +* Using vendor libraries:: +* Interfacing to other languages:: + +@end menu + +@node VHDL standards,PSL implementation,,GHDL implementation of VHDL +@anchor{GHDL_implementation_of_VHDL vhdl-standards}@anchor{29}@anchor{GHDL_implementation_of_VHDL id1}@anchor{79} +@section VHDL standards + + +@geindex VHDL standards + +@geindex IEEE 1076 + +@geindex IEEE 1076a + +@geindex 1076 + +@geindex 1076a + +@geindex v87 + +@geindex v93 + +@geindex v93c + +@geindex v00 + +@geindex v02 + +This is very unfortunate, but there are many versions of the VHDL +language, and they aren't backward compatible. + +The VHDL language was first standardized in 1987 by IEEE as IEEE 1076-1987, and +is commonly referred as VHDL-87. This is certainly the most important version, +since most of the VHDL tools are still based on this standard. + +Various problems of this first standard have been analyzed by experts groups +to give reasonable ways of interpreting the unclear portions of the standard. + +VHDL was revised in 1993 by IEEE as IEEE 1076-1993. This revision is still +well-known. + +Unfortunately, VHDL-93 is not fully compatible with VHDL-87, i.e. some perfectly +valid VHDL-87 programs are invalid VHDL-93 programs. Here are some of the +reasons: + + +@itemize * + +@item +the syntax of file declaration has changed (this is the most visible source +of incompatibility), + +@item +new keywords were introduced (group, impure, inertial, literal, +postponed, pure, reject, rol, ror, shared, sla, sll, sra, srl, +unaffected, xnor), + +@item +some dynamic behaviours have changed (the concatenation is one of them), + +@item +rules have been added. +@end itemize + +Shared variables were replaced by protected types in the 2000 revision of +the VHDL standard. This modification is also known as 1076a. Note that this +standard is not fully backward compatible with VHDL-93, since the type of a +shared variable must now be a protected type (there was no such restriction +before). + +Minors corrections were added by the 2002 revision of the VHDL standard. This +revision is not fully backward compatible with VHDL-00 since, for example, +the value of the @cite{'instance_name} attribute has slightly changed. + +You can select the VHDL standard expected by GHDL with the +@code{--std=VER} option, where @code{VER} is one of the left column of the +table below: + + +@table @asis + +@item 87 + +Select VHDL-87 standard as defined by IEEE 1076-1987. LRM bugs corrected by +later revisions are taken into account. + +@item 93 + +Select VHDL-93; VHDL-87 file declarations are not accepted. + +@item 93c + +Select VHDL-93 standard with relaxed rules: + + +@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. +@end itemize + +@item 00 + +Select VHDL-2000 standard, which adds protected types. + +@item 02 + +Select VHDL-2002 standard + +@item 08 + +Select VHDL-2008 standard (partially implemented). +@end table + +You cannot mix VHDL-87 and VHDL-93 units. A design hierarchy must have been +completely analyzed using either the 87 or the 93 version of the VHDL standard. + +@node PSL implementation,Source representation,VHDL standards,GHDL implementation of VHDL +@anchor{GHDL_implementation_of_VHDL id2}@anchor{7a}@anchor{GHDL_implementation_of_VHDL psl-implementation}@anchor{2f} +@section PSL implementation + + +GHDL understands embedded PSL annotations in VHDL files, but not in +separate files. + +As PSL annotations are embedded within comments, you must analyze and elaborate +your design with option @emph{-fpsl} to enable PSL annotations. + +A PSL assertion statement must appear within a comment that starts +with the @cite{psl} keyword. The keyword must be followed (on the +same line) by a PSL keyword such as @cite{assert} or @cite{default}. +To continue a PSL statement on the next line, just start a new comment. + +A PSL statement is considered as a process. So it is not allowed within +a process. + +All PSL assertions must be clocked (GHDL doesn't support unclocked assertion). +Furthermore only one clock per assertion is allowed. + +You can either use a default clock like this: + +@example +-- psl default clock is rising_edge (CLK); +-- psl assert always +-- a -> eventually! b; +@end example + +or use a clocked expression (note the use of parenthesis): + +@example +-- psl assert (always a -> next[3](b)) @@rising_edge (clk); +@end example + +Of course only the simple subset of PSL is allowed. + +Currently the built-in functions are not implemented. + +@node Source representation,Library database,PSL implementation,GHDL implementation of VHDL +@anchor{GHDL_implementation_of_VHDL source-representation}@anchor{7b} +@section Source representation + + +According to the VHDL standard, design units (i.e. entities, +architectures, packages, package bodies and configurations) may be +independently analyzed. + +Several design units may be grouped into a design file. + +In GHDL, a system file represents a design file. That is, a file compiled by +GHDL may contain one or more design units. + +It is common to have several design units in a design file. + +GHDL does not impose any restriction on the name of a design file +(except that the filename may not contain any control character or +spaces). + +GHDL do not keep a binary representation of the design units analyzed like +other VHDL analyzers. The sources of the design units are re-read when +needed (for example, an entity is re-read when one of its architecture is +analyzed). Therefore, if you delete or modify a source file of a unit +analyzed, GHDL will refuse to use it. + +@node Library database,Top entity,Source representation,GHDL implementation of VHDL +@anchor{GHDL_implementation_of_VHDL library-database}@anchor{7c}@anchor{GHDL_implementation_of_VHDL id3}@anchor{7d} +@section Library database + + +Each design unit analyzed is placed into a design library. By default, +the name of this design library is @code{work}; however, this can be +changed with the @code{--work=NAME} option of GHDL. + +To keep the list of design units in a design library, GHDL creates +library files. The name of these files is @code{NAME-objVER.cf}, where +@cite{NAME} is the name of the library, and @cite{VER} the VHDL version (87 +or 93) used to analyze the design units. + +You don't have to know how to read a library file. You can display it +using the @emph{-d} of @cite{ghdl}. The file contains the name of the +design units, as well as the location and the dependencies. + +The format may change with the next version of GHDL. + +@node Top entity,Using vendor libraries,Library database,GHDL implementation of VHDL +@anchor{GHDL_implementation_of_VHDL top-entity}@anchor{16}@anchor{GHDL_implementation_of_VHDL id4}@anchor{7e} +@section Top entity + + +There are some restrictions on the entity being at the apex of a design +hierarchy: + + +@itemize * + +@item +The generic must have a default value, and the value of a generic is its +default value; + +@item +The ports type must be constrained. +@end itemize + +@node Using vendor libraries,Interfacing to other languages,Top entity,GHDL implementation of VHDL +@anchor{GHDL_implementation_of_VHDL using-vendor-libraries}@anchor{7f} +@section Using vendor libraries + + +Many vendors libraries have been analyzed with GHDL. There are +usually no problems. Be sure to use the @code{--work=} option. +However, some problems have been encountered. + +GHDL follows the VHDL LRM (the manual which defines VHDL) more +strictly than other VHDL tools. You could try to relax the +restrictions by using the @code{--std=93c}, @ref{2c,,-fexplicit}, +@ref{2d,,-frelaxed-rules} and @code{--warn-no-vital-generic}. + +@node Interfacing to other languages,,Using vendor libraries,GHDL implementation of VHDL +@anchor{GHDL_implementation_of_VHDL interfacing-to-other-languages}@anchor{80} +@section Interfacing to other languages + + +@geindex interfacing + +@geindex other languages + +@geindex foreign + +@geindex VHPI + +@geindex VHPIDIRECT + +Interfacing with foreign languages is possible only on GNU/Linux systems. + +You can define a subprogram in a foreign language (such as @cite{C} or +@cite{Ada}) and import it in a VHDL design. + +@menu +* Foreign declarations:: +* Restrictions on foreign declarations:: +* Linking with foreign object files:: +* Starting a simulation from a foreign program:: +* Linking with Ada:: +* Using GRT from Ada:: + +@end menu + +@node Foreign declarations,Restrictions on foreign declarations,,Interfacing to other languages +@anchor{GHDL_implementation_of_VHDL foreign-declarations}@anchor{81} +@subsection Foreign declarations + + +Only subprograms (functions or procedures) can be imported, using the foreign +attribute. In this example, the @cite{sin} function is imported: + +@example +package math is + function sin (v : real) return real; + attribute foreign of sin : function is "VHPIDIRECT sin"; +end math; + +package body math is + function sin (v : real) return real is + begin + assert false severity failure; + end sin; +end math; +@end example + +A subprogram is made foreign if the @cite{foreign} attribute decorates +it. This attribute is declared in the 1993 revision of the +@code{std.standard} package. Therefore, you cannot use this feature in +VHDL 1987. + +The decoration is achieved through an attribute specification. The +attribute specification must be in the same declarative part as the +subprogram and must be after it. This is a general rule for specifications. +The value of the specification must be a locally static string. + +Even when a subprogram is foreign, its body must be present. However, since +it won't be called, you can made it empty or simply but an assertion. + +The value of the attribute must start with @code{VHPIDIRECT} (an +upper-case keyword followed by one or more blanks). The linkage name of the +subprogram follows. + +@node Restrictions on foreign declarations,Linking with foreign object files,Foreign declarations,Interfacing to other languages +@anchor{GHDL_implementation_of_VHDL restrictions-on-foreign-declarations}@anchor{82}@anchor{GHDL_implementation_of_VHDL id5}@anchor{83} +@subsection Restrictions on foreign declarations + + +Any subprogram can be imported. GHDL puts no restrictions on foreign +subprograms. However, the representation of a type or of an interface in a +foreign language may be obscure. Most of non-composite types are easily imported: + + +@table @asis + +@item @emph{integer types} + +They are represented on a 32 bits word. This generally corresponds to +@cite{int} for @cite{C} or @cite{Integer} for @cite{Ada}. + +@item @emph{physical types} + +They are represented on a 64 bits word. This generally corresponds to the +@cite{long long} for @cite{C} or @cite{Long_Long_Integer} for @cite{Ada}. + +@item @emph{floating point types} + +They are represented on a 64 bits floating point word. This generally +corresponds to @cite{double} for @cite{C} or @cite{Long_Float} for @cite{Ada}. + +@item @emph{enumeration types} + +They are represented on 8 bits or 32 bits word, if the number of literals is +greater than 256. There is no corresponding C types, since arguments are +not promoted. +@end table + +Non-composite types are passed by value. For the @cite{in} mode, this +corresponds to the @cite{C} or @cite{Ada} mechanism. The @cite{out} and +@cite{inout} interfaces of non-composite types are gathered in a record +and this record is passed by reference as the first argument to the +subprogram. As a consequence, you shouldn't use @cite{in} and +@cite{inout} modes in foreign subprograms, since they are not portable. + +Records are represented like a @cite{C} structure and are passed by reference +to subprograms. + +Arrays with static bounds are represented like a @cite{C} array, whose +length is the number of elements, and are passed by reference to subprograms. + +Unconstrained array are represented by a fat pointer. Do not use unconstrained +arrays in foreign subprograms. + +Accesses to an unconstrained array is a fat pointer. Other accesses correspond to an address and are passed to a subprogram like other non-composite types. + +Files are represented by a 32 bits word, which corresponds to an index +in a table. + +@node Linking with foreign object files,Starting a simulation from a foreign program,Restrictions on foreign declarations,Interfacing to other languages +@anchor{GHDL_implementation_of_VHDL id6}@anchor{84}@anchor{GHDL_implementation_of_VHDL linking-with-foreign-object-files}@anchor{85} +@subsection Linking with foreign object files + + +You may add additional files or options during the link using the +@emph{-Wl,} of @cite{GHDL}, as described in @ref{15,,Elaboration command}. +For example: + +@example +ghdl -e -Wl,-lm math_tb +@end example + +will create the @code{math_tb} executable with the @code{lm} (mathematical) +library. + +Note the @code{c} library is always linked with an executable. + +@node Starting a simulation from a foreign program,Linking with Ada,Linking with foreign object files,Interfacing to other languages +@anchor{GHDL_implementation_of_VHDL id7}@anchor{86}@anchor{GHDL_implementation_of_VHDL starting-a-simulation-from-a-foreign-program}@anchor{87} +@subsection Starting a simulation from a foreign program + + +You may run your design from an external program. You just have to call +the @code{ghdl_main} function which can be defined: + +in C: + +@example +extern int ghdl_main (int argc, char **argv); +@end example + +in Ada: + +@example +with System; +... +function Ghdl_Main (Argc : Integer; Argv : System.Address) + return Integer; +pragma import (C, Ghdl_Main, "ghdl_main"); +@end example + +This function must be called once, and returns 0 at the end of the simulation. +In case of failure, this function does not return. This has to be fixed. + +@node Linking with Ada,Using GRT from Ada,Starting a simulation from a foreign program,Interfacing to other languages +@anchor{GHDL_implementation_of_VHDL linking-with-ada}@anchor{88}@anchor{GHDL_implementation_of_VHDL id8}@anchor{89} +@subsection Linking with Ada + + +As explained previously in @ref{87,,Starting a simulation from a foreign program}, +you can start a simulation from an @cite{Ada} program. However the build +process is not trivial: you have to elaborate your @cite{Ada} program and your +@cite{VHDL} design. + +First, you have to analyze all your design files. In this example, we +suppose there is only one design file, @code{design.vhdl}. + +@example +$ ghdl -a design.vhdl +@end example + +Then, bind your design. In this example, we suppose the entity at the +design apex is @code{design}. + +@example +$ ghdl --bind design +@end example + +Finally, compile, bind your @cite{Ada} program at link it with your @cite{VHDL} +design: + +@example +$ gnatmake my_prog -largs `ghdl --list-link design` +@end example + +@node Using GRT from Ada,,Linking with Ada,Interfacing to other languages +@anchor{GHDL_implementation_of_VHDL using-grt-from-ada}@anchor{8a} +@subsection Using GRT from Ada + + +@cartouche +@quotation Warning +This topic is only for advanced users knowing how to use @cite{Ada} +and @cite{GNAT}. This is provided only for reference, I have tested +this once before releasing @cite{GHDL} 0.19 but this is not checked at +each release. +@end quotation +@end cartouche + +The simulator kernel of @cite{GHDL} named @emph{GRT} is written in +@cite{Ada95} and contains a very light and slightly adapted version +of @cite{VHPI}. Since it is an @cite{Ada} implementation it is +called @emph{AVHPI}. Although being tough, you may interface to @cite{AVHPI}. + +For using @cite{AVHPI}, you need the sources of @cite{GHDL} and to recompile +them (at least the @cite{GRT} library). This library is usually compiled with +a @cite{No_Run_Time} pragma, so that the user does not need to install the +@cite{GNAT} runtime library. However, you certainly want to use the usual +runtime library and want to avoid this pragma. For this, reset the +@cite{GRT_PRAGMA_FLAG} variable. + +@example +$ make GRT_PRAGMA_FLAG= grt-all +@end example + +Since @cite{GRT} is a self-contained library, you don't want +@cite{gnatlink} to fetch individual object files (furthermore this +doesn't always work due to tricks used in @cite{GRT}). For this, +remove all the object files and make the @code{.ali} files read-only. + +@example +$ rm *.o +$ chmod -w *.ali +@end example + +You may then install the sources files and the @code{.ali} files. I have never +tested this step. + +You are now ready to use it. + +For example, here is an example, @code{test_grt.adb} which displays the top +level design name. + +@example +with System; use System; +with Grt.Avhpi; use Grt.Avhpi; +with Ada.Text_IO; use Ada.Text_IO; +with Ghdl_Main; + +procedure Test_Grt is + -- VHPI handle. + H : VhpiHandleT; + Status : Integer; + + -- Name. + Name : String (1 .. 64); + Name_Len : Integer; +begin + -- Elaborate and run the design. + Status := Ghdl_Main (0, Null_Address); + + -- Display the status of the simulation. + Put_Line ("Status is " & Integer'Image (Status)); + + -- Get the root instance. + Get_Root_Inst(H); + + -- Disp its name using vhpi API. + Vhpi_Get_Str (VhpiNameP, H, Name, Name_Len); + Put_Line ("Root instance name: " & Name (1 .. Name_Len)); +end Test_Grt; +@end example + +First, analyze and bind your design: + +@example +$ ghdl -a counter.vhdl +$ ghdl --bind counter +@end example + +Then build the whole: + +@example +$ gnatmake test_grt -aL`grt_ali_path` -aI`grt_src_path` -largs + `ghdl --list-link counter` +@end example + +Finally, run your design: + +@example +$ ./test_grt +Status is 0 +Root instance name: counter +@end example + +@node GHDL implementation of VITAL,Flaws and bugs report,GHDL implementation of VHDL,Top +@anchor{GHDL_implementation_of_VITAL ghdl-implementation-of-vital}@anchor{8b}@anchor{GHDL_implementation_of_VITAL doc}@anchor{8c} +@chapter GHDL implementation of VITAL + + +@geindex VITAL + +@geindex IEEE 1076.4 + +@geindex 1076.4 + +This chapter describes how VITAL is implemented in GHDL. Support of VITAL is +really in a preliminary stage. Do not expect too much of it as now. + +@menu +* VITAL packages:: +* VHDL restrictions for VITAL:: +* Backannotation:: +* Negative constraint calculation:: + +@end menu + +@node VITAL packages,VHDL restrictions for VITAL,,GHDL implementation of VITAL +@anchor{GHDL_implementation_of_VITAL vital-packages}@anchor{2b}@anchor{GHDL_implementation_of_VITAL id1}@anchor{8d} +@section VITAL packages + + +The VITAL standard or IEEE 1076.4 was first published in 1995, and revised in +2000. + +The version of the VITAL packages depends on the VHDL standard. VITAL +1995 packages are used with the VHDL 1987 standard, while VITAL 2000 +packages are used with other standards. This choice is based on the +requirements of VITAL: VITAL 1995 requires the models follow the VHDL +1987 standard, while VITAL 2000 requires the models follow VHDL 1993. + +The VITAL 2000 packages were slightly modified so that they conform to +the VHDL 1993 standard (a few functions are made pure and a few one +impure). + +@node VHDL restrictions for VITAL,Backannotation,VITAL packages,GHDL implementation of VITAL +@anchor{GHDL_implementation_of_VITAL id2}@anchor{8e}@anchor{GHDL_implementation_of_VITAL vhdl-restrictions-for-vital}@anchor{32} +@section VHDL restrictions for VITAL + + +The VITAL standard (partially) implemented is the IEEE 1076.4 standard +published in 1995. + +This standard defines restriction of the VHDL language usage on VITAL +model. A @emph{VITAL model} is a design unit (entity or architecture) +decorated by the @cite{VITAL_Level0} or @cite{VITAL_Level1} attribute. +These attributes are defined in the @cite{ieee.VITAL_Timing} package. + +Currently, only VITAL level 0 checks are implemented. VITAL level 1 models +can be analyzed, but GHDL doesn't check they comply with the VITAL standard. + +Moreover, GHDL doesn't check (yet) that timing generics are not read inside +a VITAL level 0 model prior the VITAL annotation. + +The analysis of a non-conformant VITAL model fails. You can disable the +checks of VITAL restrictions with the @emph{--no-vital-checks}. Even when +restrictions are not checked, SDF annotation can be performed. + +@node Backannotation,Negative constraint calculation,VHDL restrictions for VITAL,GHDL implementation of VITAL +@anchor{GHDL_implementation_of_VITAL backannotation}@anchor{75}@anchor{GHDL_implementation_of_VITAL id3}@anchor{8f} +@section Backannotation + + +@geindex SDF + +@emph{Backannotation} is the process of setting VITAL generics with timing +information provided by an external files. + +The external files must be SDF (Standard Delay Format) files. GHDL +supports a tiny subset of SDF version 2.1, other version number can be +used, provided no features added by the next version are used. + +Hierarchical instance names are not supported. However you can use a list of +instances. If there is no instance, the top entity will be annotated and +the celltype must be the name of the top entity. If there is at least one +instance, the last instance name must be a component instantiation label, and +the celltype must be the name of the component declaration instantiated. + +Instances being annotated are not required to be VITAL compliant. However +generics being annotated must follow rules of VITAL (e.g., type must be a +suitable vital delay type). + +Currently, only timing constraints applying on a timing generic of type +@cite{VitalDelayType01} has been implemented. This SDF annotator is +just a proof of concept. Features will be added with the following GHDL +release. + +@node Negative constraint calculation,,Backannotation,GHDL implementation of VITAL +@anchor{GHDL_implementation_of_VITAL negative-constraint-calculation}@anchor{90} +@section Negative constraint calculation + + +Negative constraint delay adjustment are necessary to handle negative +constraint such as a negative setup time. This step is defined in the VITAL +standard and should occur after backannotation. + +GHDL does not do negative constraint calculation. It fails to handle models +with negative constraint. I hope to be able to add this phase soon. + +@node Flaws and bugs report,Copyrights,GHDL implementation of VITAL,Top +@anchor{Flaws_and_bugs_report doc}@anchor{91}@anchor{Flaws_and_bugs_report flaws-and-bugs-report}@anchor{92} +@chapter Flaws and bugs report + + +Despite all the testing and already reported issues, you can find bugs +or propose enhancements. + +@quotation +@anchor{Flaws_and_bugs_report reporting-bugs}@anchor{71} +@end quotation + +@menu +* Reporting bugs:: +* Future improvements:: + +@end menu + +@node Reporting bugs,Future improvements,,Flaws and bugs report +@anchor{Flaws_and_bugs_report id1}@anchor{93} +@section Reporting bugs + + +In order to improve GHDL, we welcome bugs report and suggestions for +any aspect of GHDL. Please create an issue on +@indicateurl{https://github.com/tgingold/ghdl/issues} + +If the compiler crashes, this is a bug. Reliable tools never crash. + +If your compiled VHDL executable crashes, this may be a bug at +runtime or the code produced may be wrong. However, since VHDL +has a notion of pointers, an erroneous VHDL program (using invalid +pointers for example) may crash. + +If the compiler emits an error message for a perfectly valid input or +does not emit an error message for an invalid input, this may be a bug. +Please send the input file and what you expected. If you know the LRM +well enough, please specify the paragraph which has not been well +implemented. If you don't know the LRM, maybe your bug report will be +rejected simply because there is no bug. In the latter case, it may be +difficult to discuss the issue; and comparisons with other VHDL tools +is not a very strong argument. + +If a compiler message is not clear enough for you, please tell me. The +error messages can be improved, but I have not enough experience with +them. + +If you have found a mistake in the manual, please send a comment. If +you have not understood some parts of this manual, please tell me. +English is not my mother tongue, so this manual may not be well-written. +Again, rewriting part of it is a good way to improve it. + +If you send a @cite{VHDL} file producing a bug, it is a good idea to try +to make it as short as possible. It is also a good idea to make it +looking like a test: write a comment which explains whether the file +should compile, and if yes, whether or not it should run successfully. +In the latter case, an assert statement should finish the test; the +severity level note indicates success, while a severity level failure +indicates failure. + +For bug reports, please include enough information for the maintainers to +reproduce the problem. This includes: + + +@itemize * + +@item +the version of @cite{GHDL} (you can get it with @code{ghdl --version}). + +@item +the operating system + +@item +whether you have built @cite{GHDL} from sources or used the binary +distribution. + +@item +the content of the input files + +@item +a description of the problem and samples of any erroneous input + +@item +anything else that you think would be helpful. +@end itemize + +@node Future improvements,,Reporting bugs,Flaws and bugs report +@anchor{Flaws_and_bugs_report future-improvements}@anchor{94} +@section Future improvements + + +I have several axes for @cite{GHDL} improvements: + + +@itemize * + +@item +Documentation. + +@item +Better diagnostics messages (warning and error). + +@item +Full support of VHDL-2008. + +@item +Optimization (simulation speed). + +@item +Graphical tools (to see waves and to debug) + +@item +Style checks + +@item +VITAL acceleration +@end itemize + +@node Copyrights,Indices and tables,Flaws and bugs report,Top +@anchor{Copyrights copyrights}@anchor{95}@anchor{Copyrights doc}@anchor{96} +@chapter Copyrights + + +The GHDL front-end, the @code{std.textio} package and the runtime +library (@code{grt}) are copyrighted Tristan Gingold, come with @strong{absolutely +no warranty}, and are distributed under the conditions of the General +Public License. + +The @code{ieee.numeric_bit} and @code{ieee.numeric_std} packages are +copyrighted by the IEEE. The source files may be distributed without +change, except as permitted by the standard. + +This source file may not be +sold or distributed for profit. See the source file and the IEEE 1076.3 +standard for more information. + +The @code{ieee.std_logic_1164}, @code{ieee.Math_Real} and +@code{ieee.Math_Complex} packages are copyrighted by the IEEE. See +source files for more information. + +The @code{ieee.VITAL_Primitives}, @code{ieee.VITAL_Timing} and +@code{ieee.VITAL_Memory} packages are copyrighted by IEEE. See source +file and the IEEE 1076.4 standards for more information. + +The packages @code{std_logic_arith}, +@code{std_logic_signed}, @code{std_logic_unsigned} and +@code{std_logic_textio} contained in the @code{synopsys} directory are +copyrighted by Synopsys, Inc. The source files 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. See the source files for more information. + +The package @code{std_logic_arith} contained in the @code{mentor} +directory is copyrighted by Mentor Graphics. The source files may be +distributed in whole without restriction provided that the copyright +statement is not removed from the file and that any derivative work +contains this copyright notice. See the source files for more information. + +As a consequence of the runtime copyright, you may not be allowed to +distribute an executable produced by @cite{GHDL} without the VHDL +sources. To my mind, this is not a real restriction, since there is no +points in distributing VHDL executable. Please, send a comment +(@ref{71,,Reporting bugs}) if you don't like this policy. + +@node Indices and tables,Index,Copyrights,Top +@anchor{index indices-and-tables}@anchor{97} +@unnumbered Indices and tables + + + +@itemize * + +@item +genindex + +@item +search +@end itemize + +@node Index,,Indices and tables,Top +@unnumbered Index + + +@printindex ge + + +@c %**end of body +@bye |