diff options
| author | Tristan Gingold | 2015-11-24 06:01:52 +0100 |
|---|---|---|
| committer | Tristan Gingold | 2015-11-24 06:04:42 +0100 |
| commit | 3a9c90b39150a636c27b362ab01b6090a213455c (patch) | |
| tree | 09480c0e3751dd6702d25b3043b982987e25a0f3 | |
| parent | 5ad9818cbc2725f4fdb424271c17a2b99454d4c3 (diff) | |
| download | ghdl-3a9c90b39150a636c27b362ab01b6090a213455c.tar.gz ghdl-3a9c90b39150a636c27b362ab01b6090a213455c.tar.bz2 ghdl-3a9c90b39150a636c27b362ab01b6090a213455c.zip | |
doc: add dependency on conf.py, remove ghdl.html
Due to use of css, better to view doc from the web.
| -rw-r--r-- | doc/Makefile | 9 | ||||
| -rw-r--r-- | doc/ghdl.html | 2042 |
2 files changed, 3 insertions, 2048 deletions
diff --git a/doc/Makefile b/doc/Makefile index 41ec46a..eb08aa6 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -7,7 +7,8 @@ SRC_FILES= \ Invoking_GHDL.rst \ Simulation_and_runtime.rst \ Starting_with_GHDL.rst \ - index.rst + index.rst \ + conf.py CP=cp @@ -41,10 +42,6 @@ ghdl.pdf: ghdl.dvi 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 $@ @@ -55,4 +52,4 @@ clean: $(RM) -rf build maintainer-clean: clean - $(RM) ghdl.html ghdl.texi + $(RM) ghdl.texi diff --git a/doc/ghdl.html b/doc/ghdl.html deleted file mode 100644 index 85864d7..0000000 --- a/doc/ghdl.html +++ /dev/null @@ -1,2042 +0,0 @@ -<!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 |