From 977ff5e02c6d2f9bfdabcf8b4e98b81e2d83e849 Mon Sep 17 00:00:00 2001 From: gingold Date: Sat, 24 Sep 2005 05:10:24 +0000 Subject: First import from sources --- doc/ghdl.texi | 2371 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 2371 insertions(+) create mode 100644 doc/ghdl.texi (limited to 'doc') diff --git a/doc/ghdl.texi b/doc/ghdl.texi new file mode 100644 index 000000000..4824cdf84 --- /dev/null +++ b/doc/ghdl.texi @@ -0,0 +1,2371 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename ghdl.info +@settitle GHDL guide +@c %**end of header + +@titlepage +@title GHDL guide +@subtitle GHDL, a VHDL compiler +@subtitle For GHDL version 0.19 (Sokcho edition) +@author Tristan Gingold +@c The following two commands start the copyright page. +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 2002, 2003, 2004, 2005 Tristan Gingold. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation. +@end titlepage + +@ignore +Part I: User guide +1) Intro: what is vhdl, what is ghdl +2) starting with ghdl: a few examples +2.1) hello world +2.2) a nand gate +2.3) testsuite for a nand gate +2.4) a nand3 gate (using components) +2.5) testsuite for the nand3 + +Part II: Reference guide +1) command line options +1.1) filename extension. +2) Current standards +2.w) what is 93c +3) Linking with Ada or C code. FOREIGN use. +3) library organization +4) built-in libraries and pathes. +5) debugging your program. +6) report messages (run time errors, boundary errors, assertion) +7) Error message, improve it. +8) current bugs, how to report a bug. +9) Copyright + +done: ?) source representation +done: ?) copyright +done: ?) debugging +done: ?) executable options +done: ?) top entity characteristics +done: ?) work library +done: ?) ieee library +done: ?) file format (textio/not textio) + +TODO: +XX: indexes +XXX: signals cannot be forced, only viewed in depth. +x: implementation dependant: files (see 4.3.1.4) + +To check: +model vs modeling vs modelize +behaviour vs behavior +analyze vs analyse + +Internal overview + ortho + grt subprograms +@end ignore + +@contents + +@ifnottex +@node Top +@top GHDL guide +GHDL, a VHDL compiler. + +Copyright @copyright{} 2002, 2003, 2004 Tristan Gingold. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 +or any later version published by the Free Software Foundation. + +@menu +* Introduction:: What is GHDL, what is VHDL +* Starting with GHDL:: Build a VHDL program with GHDL +* Invoking GHDL:: +* Simulation and run time:: +* GHDL implementation of VHDL:: +* GHDL implementation of VITAL:: +* Flaws and bugs report:: +* Copyrights:: +* Index:: + +@end menu + +@end ifnottex + +@node Introduction, Starting with GHDL, Top, Top +@comment node-name, next, previous, up +@chapter Introduction + +@menu +* What is VHDL:: +* What is GHDL:: +@end menu + +@section Content of this manual +This manual is the user and reference manual for GHDL. It does not +contain an introduction to VHDL. Thus, the reader should have at least +a basic knowledge of VHDL. A good knowledge of VHDL language reference +manual (usually called LRM) is a plus. + +@c FIXME: references: URL, LRM reference. + +@node What is VHDL, What is GHDL, Introduction, Introduction +@comment node-name, next, previous, up +@section What is @code{VHDL}? +@dfn{VHDL} is an acronym for Very High Speed Integrated Circuit Hardware +Description Language which is a programming language used to describe a +logic circuit by function, data flow behaviour, or structure. + +@code{VHDL} @emph{is} a programming language: although @code{VHDL} was +not designed for writing general purpose programs, you can write any +algorithm with the @code{VHDL} language. If you are able to write +programs, you will find in @code{VHDL} features similar to those found +in procedural languages such as @code{C}, @code{Pascal} or @code{Ada}. +@code{VHDL} derives most of its syntax and semantics from @code{Ada}. +Knowing @code{Ada} is an advantage for learning @code{VHDL} (it is an +advantage in general as well). + +However, @code{VHDL} was not designed as a general purpose language but as an +@code{HDL} (hardware description language). As the name implies, @code{VHDL} +aims at modeling or documenting electronics systems. Due to the nature +of hardware components which are always running, @code{VHDL} is a highly +concurrent language, built upon an event-based timing model. + +Like a program written in any other language, a @code{VHDL} program +can be executed. Since @code{VHDL} is used to model designs, the term +@dfn{simulation} is often used instead of @dfn{execution}, with the +same meaning. + +Like a program written in another hardware description language, a +@code{VHDL} program can be transformed with a @code{synthesis tool} +into a netlist, that is, a detailed gate-level implementation. + +@node What is GHDL, , What is VHDL, Introduction +@comment node-name, next, previous, up +@section What is @code{GHDL}? +@dfn{GHDL} is a shorthand for G Hardware Design Language. Currently, +@code{G} has no meaning. + +@dfn{GHDL} is a @code{VHDL} compiler that can execute (nearly) any +@code{VHDL} program. @code{GHDL} is @emph{not} a synthesis tool: you cannot +create a netlist with @code{GHDL}. + +Unlike some other simulators, @code{GHDL} is a compiler: it directly +translates a @code{VHDL} file to machine code, using the @code{GCC} +back-end and without using an intermediary language such as @code{C} +or @code{C++}. Therefore, the compiled code should be faster and +the analysis time should be shorter than with a compiler using an +intermediary language. + +The current version of @code{GHDL} does not contain any graphical +viewer: you cannot see signal waves. You can still check with a test +bench. The current version can produce a @code{VCD} file which can be +viewed with a wave viewer. + +@code{GHDL} aims at implementing @code{VHDL} as defined by IEEE 1076. +It supports most of the 1987 standard and most features added by the +1993 standard. + + +@node Starting with GHDL, Invoking GHDL, Introduction, Top +@comment node-name, next, previous, up +@chapter Starting with GHDL +In this chapter, you will learn how to use the GHDL compiler by +working on two examples. + +@menu +* The hello word program:: +* A full adder:: +* Starting with a design:: +@end menu + +@node The hello word program, A full adder, Starting with GHDL, Starting with GHDL +@comment node-name, next, previous, up +@section The hello world program +To illustrate the large purpose of VHDL, here is a commented VHDL +"Hello world" program. + +@example +-- @r{Hello world program.} +use std.textio.all; -- @r{Imports the standard textio package.} + +-- @r{Defines a design entity, without any ports.} +entity hello_world is +end hello_world; + +architecture behaviour of hello_world is +begin + process + variable l : line; + begin + write (l, String'("Hello world!")); + writeline (output, l); + wait; + end process; +end behaviour; +@end example + +Suppose this program is contained in the file @file{hello.vhdl}. +First, you have to compile the file; this is called @dfn{analysis} of a design +file in VHDL terms. +@smallexample +$ ghdl -a hello.vhdl +@end smallexample +This command generates a file @file{hello.o}, which is the object file +corresponding to your VHDL program. This command also creates or updates +a file @file{work-obj93.cf}, which describes the library @samp{work}. + +Then, you have to build an executable file. +@smallexample +$ ghdl -e hello_world +@end smallexample +The @samp{-e} option means @dfn{elaborate}. With this option, @code{GHDL} +creates code in order to elaborate a design, with the @samp{hello} +entity at the top of the hierarchy. + +The result is an executable program called @file{hello} which can be run: +@smallexample +$ ghdl -r hello_world +@end smallexample +or directly: +@smallexample +$ ./hello_world +@end smallexample + +and which should display: +@smallexample +Hello world! +@end smallexample + +@node A full adder, Starting with a design, The hello word program, Starting with GHDL +@comment node-name, next, previous, up +@section A full adder +VHDL is generally used for hardware design. This example starts with +a full adder described in the @file{adder.vhdl} file: + +@example +entity adder is + -- @r{@var{i0}, @var{i1} and the carry-in @var{ci} are inputs of the adder.} + -- @r{@var{s} is the sum output, @var{co} is the carry-out.} + port (i0, i1 : in bit; ci : in bit; s : out bit; co : out bit); +end adder; + +architecture rtl of adder is +begin + -- @r{This full-adder architecture contains two concurrent assignment.} + -- @r{Compute the sum.} + s <= i0 xor i1 xor ci; + -- @r{Compute the carry.} + co <= (i0 and i1) or (i0 and ci) or (i1 and ci); +end rtl; +@end example + +You can analyze this design file: +@smallexample +$ ghdl -a adder.vhdl +@end smallexample + +You can try to execute the @samp{adder} design, but this is useless, +since nothing externally visible will happen. In order to +check this full adder, a testbench has to be run. This testbench is +very simple, since the adder is also simple: it checks exhaustively all +inputs. Note that only the behaviour is tested, timing constraints are +not checked. The file @file{adder_tb.vhdl} contains the testbench for +the adder: +@example +-- @r{A testbench has no ports.} +entity adder_tb is +end adder_tb; + +architecture behav of adder_tb is + -- @r{Declaration of the component that will be instantiated.} + component adder + port (i0, i1 : in bit; ci : in bit; s : out bit; co : out bit); + end component; + -- @r{Specifies which entity is bound with the component.} + for adder_0: adder use entity work.adder; + signal i0, i1, ci, s, co : bit; +begin + -- @r{Component instantiation.} + adder_0: adder port map (i0 => i0, i1 => i1, ci => ci, + s => s, co => co); + + -- @r{This process does the real job.} + process + type pattern_type is record + -- @r{The inputs of the adder.} + i0, i1, ci : bit; + -- @r{The expected outputs of the adder.} + s, co : bit; + end record; + -- @r{The patterns to apply.} + type pattern_array is array (natural range <>) of pattern_type; + constant patterns : pattern_array := + (('0', '0', '0', '0', '0'), + ('0', '0', '1', '1', '0'), + ('0', '1', '0', '1', '0'), + ('0', '1', '1', '0', '1'), + ('1', '0', '0', '1', '0'), + ('1', '0', '1', '0', '1'), + ('1', '1', '0', '0', '1'), + ('1', '1', '1', '1', '1')); + begin + -- @r{Check each pattern.} + for i in patterns'range loop + -- @r{Set the inputs.} + i0 <= patterns(i).i0; + i1 <= patterns(i).i1; + ci <= patterns(i).ci; + -- @r{Wait for the results.} + wait for 1 ns; + -- @r{Check the outputs.} + assert s = patterns(i).s + report "bad sum value" severity error; + assert co = patterns(i).co + report "bad carray out value" severity error; + end loop; + assert false report "end of test" severity note; + -- @r{Wait forever; this will finish the simulation.} + wait; + end process; +end behav; +@end example + +As usual, you should analyze the design: +@smallexample +$ ghdl -a adder_tb.vhdl +@end smallexample +And build an executable for the testbench: +@smallexample +$ ghdl -e adder_tb +@end smallexample +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: +@smallexample +$ ghdl -r adder_tb +adder_tb.vhdl:52:7:(assertion note): end of test +@end smallexample + +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: +@smallexample +$ ghdl -r adder_tb --vcd=adder.vcd +@end smallexample +Then, you may now view the waves: +@smallexample +$ gtkwave adder.vcd +@end smallexample + +@xref{Simulation options}, for more details on the @option{--vcd} option and +other run time options. + +@node Starting with a design, , A full adder, Starting with GHDL +@comment node-name, next, previous, up +@section Starting with a design +Unless you are only studying VHDL, you will work with bigger designs than +the ones of the previous examples. + +Let's see how to analyze and run a bigger design, such as the DLX model +suite written by Peter Ashenden which is distributed under the terms of the +GNU General Public License. + +First, untar the sources: +@smallexample +$ tar zxvf dlx.tar.Z +@end smallexample + +In order not to pollute the sources with the library, it is a good idea +to create a @file{work/} subdirectory for the @samp{WORK} library. To +any GHDL commands, we will add the @option{--workdir=work} option, so +that all files generated by the compiler (except the executable) will be +placed in this directory. +@smallexample +$ cd dlx +$ mkdir work +@end smallexample + +We will run the @samp{dlx_test_behaviour} design. We need to analyze +all the design units for the design hierarchy, in the correct order. +GHDL provides an easy way to do this, by importing the sources: +@smallexample +$ ghdl -i --workdir=work *.vhdl +@end smallexample + +and making a design: +@smallexample +$ ghdl -m --workdir=work dlx_test_behaviour +@end smallexample + +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 @file{work/} +directory, and the @file{dlx_test_behaviour} executable in the current +directory. + +The simulation needs to have a DLX program contained in the file +@file{dlx.out}. This memory image will be be loaded in the DLX memory. +Just take one sample: +@smallexample +$ cp test_loop.out dlx.out +@end smallexample + +And you can run the test suite: +@smallexample +$ ghdl -r dlx_test_behaviour +@end smallexample + +The test bench monitors the bus and displays each instruction executed. +It finishes with an assertion of severity level note: +@smallexample +dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction + encountered, execution halted +@end smallexample + +Since the clock is still running, you have to manually stop the program +with the @kbd{C-c} key sequence. This behavior prevents you from running the +test bench in batch mode. However, you may force the simulator to +stop when an assertion above or equal a certain severity level occurs: +@smallexample +$ ghdl -r dlx_test_behaviour --assert-level=note +@end smallexample + +With this option, the program stops just after the previous message: +@smallexample +dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction + encountered, execution halted +error: assertion failed +@end smallexample + +If you want to make room on your hard drive, you can either: +@itemize @bullet{} +@item +clean the design library with the GHDL command: +@smallexample +$ ghdl --clean --workdir=work +@end smallexample +This removes the executable and all the object files. If you want to +rebuild the design at this point, just do the make command as shown above. +@item +remove the design library with the GHDL command: +@smallexample +$ ghdl --remove --workdir=work +@end smallexample +This removes the executable, all the object files and the library file. +If you want to rebuild the design, you have to import the sources again, +and to make the design. +@item +remove the @file{work/} directory: +@smallexample +$ rm -rf work +@end smallexample +Only the executable is kept. If you want to rebuild the design, create +the @file{work/} directory, import the sources, and make the design. +@end itemize + +Sometimes, a design does not fully follow the VHDL standards. For example it +uses the badly engineered @samp{std_logic_unsigned} package. GHDL supports +this VHDL dialect through some options: +@smallexample +--ieee=synopsys -fexplicit +@end smallexample +@xref{IEEE library pitfalls}, for more details. + +@node Invoking GHDL, Simulation and run time, Starting with GHDL, Top +@comment node-name, next, previous, up +@chapter Invoking GHDL +The form of the @code{ghdl} command is + +@smallexample +$ ghdl @var{command} [@var{options@dots{}}] +@end smallexample + +The GHDL program has several commands. The first argument selects +the commands. The options are used to slighly modify the action. + +No options are allowed before the command. Except for the run commands, +no options are allowed after a filename or a unit name. + +@menu +* Building commands:: +* GHDL options:: +* Passing options to other programs:: +* GHDL warnings:: +* Rebuilding commands:: +* Library commands:: +* Cross-reference command:: +* File commands:: +* Misc commands:: +* IEEE library pitfalls:: +@end menu + +@node Building commands, GHDL options, Invoking GHDL, Invoking GHDL +@comment node-name, next, previous, up +@section Building commands +The mostly used commands of GHDL are those to analyze and elaborate a design. + +@menu +* Analysis command:: +* Elaboration command:: +* Run command:: +* Elaborate and run command:: +* Bind command:: +* Link command:: +* List link command:: +* Check syntax command:: +* Analyze and elaborate command:: +@end menu + +@node Analysis command, Elaboration command, Building commands, Building commands +@comment node-name, next, previous, up +@subsection Analysis command +@cindex analysis +@cindex @option{-a} command +@smallexample +$ ghdl -a [@var{options}] @var{files} +@end smallexample + +The @dfn{analysis} command compiles one or more files, and creates an +object file for each source file. The analysis command is selected with +@var{-a} switch. Any argument starting with a dash is a 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). +@c FIXME: check this. + +@xref{GHDL options}, for details on the GHDL options. For example, +to produce debugging information such as line numbers, use: + +@smallexample +$ ghdl -a -g my_design.vhdl +@end smallexample + +@node Elaboration command, Run command, Analysis command, Building commands +@comment node-name, next, previous, up +@subsection Elaboration command +@cindex elaboration +@cindex @option{-e} command +@smallexample +$ ghdl -e [@var{options}] @var{primary_unit} [@var{secondary_unit}] +@end smallexample + +The @dfn{elaboration} command creates an executable containing the +code of the @code{VHDL} sources, the elaboration code and simulation +code to execute a design hiearachy. The elaboration command is selected +with @var{-e} switch, and must be followed by either: + +@itemize @bullet +@item a name of a configuration unit +@item a name of an entity unit +@item a name of an entity unit followed by a name of an architecture unit +@end itemize + +Name of the units must be a simple name, without any dot. You can +select the name of the @samp{WORK} library with the @option{--work=NAME} +option, as described in @ref{GHDL options}. + +@xref{Top entity}, for the restrictions on the root design of a +hierarchy. + +The file name 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). + +The @option{-o} followed by a file name can override the default +executable file name. + +For the elaboration command, @code{GHDL} re-analyzes all the +configurations, entities, architectures and package declarations, and +creates the default configurations and the default binding indications +according to the LRM rules. It also generates the list of objects files +required for the executable. Then, it links all these files with the +run time library. + +The actual elaboration is performed at run-time. + +@node Run command, Elaborate and run command, Elaboration command, Building commands +@comment node-name, next, previous, up +@subsection Run command +@cindex run +@cindex @option{-r} command +Run (or simulate) an elaborated design hierarchy. + +@smallexample +$ ghdl -r @var{primary_unit} [@var{secondary_unit}] [@var{simulation_options}] +@end smallexample + +The arguments are the same as the @xref{Elaboration command}. This command +simply build the filename of the executable and execute it. You may also +directly execute the program. + +This command exists for three reasons: +@itemize @bullet{} +@item +You don't have to create the executable program name. +@item +It is coherent with the @samp{-a} and @samp{-e} commands. +@item +It will work with future implementations, where the code is generated in +memory. +@end itemize + +@xref{Simulation and run time}, for details on options. + +@node Elaborate and run command, Bind command, Run command, Building commands +@comment node-name, next, previous, up +@subsection Elaborate and run command +@cindex elaborate and run +@cindex @option{--elab-run} command +Elaborate and then simulate a design unit. + +@smallexample +$ ghdl --elab-run [@var{elab_options}] @var{primary_unit} [@var{secondary_unit}] [@var{run_options}] +@end smallexample + +This command acts like the elaboration command (@pxref{Elaboration command}) +followed by the run command (@pxref{Run command}). + +@node Bind command, Link command, Elaborate and run command, Building commands +@subsection Bind command +@cindex binding +@cindex @option{--bind} command +Bind a design unit and prepare the link step. + +@smallexample +$ ghdl --bind [@var{options}] @var{primary_unit} [@var{secondary_unit}] +@end smallexample + +This performs only the first stage of the elaboration command; the list +of objects files is created but the executable is not built. This +command should be used only when the main entry point is not ghdl. + +@node Link command, List link command, Bind command, Building commands +@subsection Link command +@cindex linking +@cindex @option{--link} command +Link an already bound design unit. + +@smallexample +$ ghdl --link [@var{options}] @var{primary_unit} [@var{secondary_unit}] +@end smallexample + +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 completness. The elaboration command is +equivalent to the bind command followed by the link command. + +@node List link command, Check syntax command, Link command, Building commands +@subsection List link command +@cindex @option{--list-link} command +Disp files which will be linked. + +@smallexample +$ ghdl --list-link @var{primary_unit} [@var{secondary_unit}] +@end smallexample + +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 an foreign program. + +@node Check syntax command, Analyze and elaborate command, List link command, Building commands +@subsection Check syntax command +@cindex checking syntax +@cindex @option{-s} command +Analyze files but do not generate code. + +@smallexample +$ ghdl -a [@var{options}] @var{files} +@end smallexample + +This command may be used to check the syntax of files. It does not update +the library. + +@node Analyze and elaborate command, , Check syntax command, Building commands +@subsection Analyze and elaborate command +@cindex Analyze and elaborate command +@cindex @option{-c} command +Analyze files and elaborate in the same time. + +@smallexample +$ ghdl -c [@var{options}] @var{file}@dots{} -e @var{primary_unit} [@var{secondary_unit}] +@end smallexample + +This command combines analyze and elaboration: @var{file}s are analyzed and +the unit is then elaborated. However, code is only generated during the +elaboration. + +To be more precise, the files are first parsed, and then the elaboration +drives the analysis. Therefore, there is no analysis order, and you don't +need to care about it. + +All the units of the files are put into the @samp{work} library. But, the +work library is neither read from disk nor saved. Therefore, you must give +all the files of the @samp{work} library your design needs. + +The advantages over the traditionnal approach (analyze and then elaborate) are: +@itemize +@item +The compilation cycle is achieved in one command. +@item +Since the files are only parsed once, the compilation cycle may be faster. +@item +You don't need to know an analysis order +@item +This command produces smaller executable, since unused units and subprograms +do not generate code. +@end itemize +However, you should know that currently most of the time is spent in code +generation and the analyze and elaborate command generate code for all units +needed, even units of @samp{std} and @samp{ieee} libraries. Therefore, +according to the design, the time for this command may be higher than the time +for the analyze command followed by the elaborate command. + +This command is still experimental. In case of problems, you should go back +to the traditionnal way. + +@comment node-name, next, previous, up +@node GHDL options, Passing options to other programs, Building commands, Invoking GHDL +@comment node-name, next, previous, up +@section GHDL options +@cindex IEEE 1164 +@cindex 1164 +@cindex IEEE 1076.3 +@cindex 1076.3 +@c document gcc options +Besides the options described below, @code{GHDL} passes any debugging options +(those that begin with @option{-g}) and optimizations options (those that +begin with @option{-O} or @option{-f}) to @code{GCC}. Refer to the @code{GCC} +manual for details. + +@table @code +@item --work=@var{NAME} +@cindex @option{--work} switch +@cindex WORK library +Specify the name of the @samp{WORK} library. Analyzed units are always +placed in the library logically named @samp{WORK}. With this option, +you can set its name. By default, the name is @var{work}. + +@code{GHDL} checks @samp{WORK} is a valid identifier. Although being +more or less supported, the @samp{WORK} identifier should not be an +extended identifier, since the filesystem may prevent it from correctly +working (due to case sensitivity or forbidden characters in filenames). + +@code{VHDL} rules forbides you to add units in the @samp{std} library. +Furthermode, you should not put units in the @samp{ieee} library. + +@item --workdir=@var{PATH} +@cindex @option{--workdir} switch +Specify the directory where the @samp{WORK} library is. When this +option is not present, the @samp{WORK} library is in the current +directory. The object files created by the compiler are always placed +in the same directory as the @samp{WORK} library. + +@item --std=@var{STD} +@cindex @option{--std} switch +Specify the standard to use. By default, the standard is @samp{93c}, which +means VHDL-93 accepting VHDL-87 syntax. For details on @var{STD} values see +@ref{VHDL standards}. + +@item --ieee=@var{VER} +@cindex @option{--ieee} switch +@cindex ieee library +@cindex synopsys library +@cindex mentor library +Select the @code{IEEE} library to use. @var{VER} must be one of: + +@table @samp +@item none +Do not supply an @code{IEEE} library. Any library clause with the @samp{IEEE} +identifier will fail, unless you have created by your own a library with +the @code{IEEE} name. + +@item standard +Supply an @code{IEEE} library containing only packages defined by +@sc{ieee} standards. Currently, there are the multivalue logic system +packages @samp{std_logic_1164} defined by IEEE 1164, the synthesis +packages , @samp{numeric_bit} and @samp{numeric_std} defined by IEEE +1076.3, and the @sc{vital} packages @samp{vital_timing} and +@samp{vital_primitives}, defined by IEEE 1076.4. The version of these +packages is defined by the VHDL standard used. @xref{VITAL packages}, +for more details. + +@item synopsys +Supply the former packages and the following additionnal packages: +@samp{std_logic_arith}, @samp{std_logic_signed}, +@samp{std_logic_unsigned}, @samp{std_logic_textio}. +@c @samp{std_logic_misc}. +These packages were created by some companies, and are popular. However +they are not standard packages, and have been placed in the @code{IEEE} +library without the @sc{ieee} permission. + +@item mentor +Supply the standardr packages and the following additionnal package: +@samp{std_logic_arith}. The package is a slight variation on a definitly +not standard but widely mis-used package. +@end table + +To avoid errors, you must use the same @code{IEEE} library for all units of +your design, and during elaboration. + +@item -P@var{PATH} +@cindex @option{-P} switch +Add @var{PATH} to the end of the list of directories to be searched for +library files. + +The @code{WORK} library is always searched in the path specified by the +@option{--workdir=} option, or in the current directory if the later +option is not specified. + +@item -fexplicit +@cindex @option{-fexplicit} switch +When two operators are overloaded, give preference to the explicit declaration. +This may be used to avoid the most common pitfall of the @samp{std_logic_arith} +package. @xref{IEEE library pitfalls}, for an example. + +This option is not set by default. I don't think this option is a +good feature, because it breaks the encapsulation rule. When set, an +operator can be silently overriden in another package. You'd better to fix +your design and use the @samp{numeric_std} package. + +@item --no-vital-checks +@item --vital-checks +@cindex @option{--no-vital-checks} switch +@cindex @option{--vital-checks} switch +Disable or enable checks of restriction on VITAL units. Checks are enabled +by default. + +Checks are performed only when a design unit is decorated by a VITAL attribute. +The VITAL attributes are @samp{VITAL_Level0} and @samp{VITAL_Level1}, both +declared in the @samp{ieee.VITAL_Timing} package. + +Currently, VITAL checks are only partially implemented. @xref{VHDL +restrictions for VITAL}, for more details. + +@item --GHDL1=@var{COMMAND} +@cindex @option{--GHLD1} switch +Use @var{COMMAND} as the command name for the compiler. If @var{COMMAND} is +not a path, then it is search in the list of program directories. + +@item -v +Be verbose. For example, for analysis, elaboration and make commands, GHDL +displays the commands executed. +@end table + +@node Passing options to other programs, GHDL warnings, GHDL options, Invoking GHDL +@comment node-name, next, previous, up +@section Passing options to other programs +For many commands, @code{GHDL} acts as a driver: it invokes programs to perform +the command. You can pass arbritrary options to these programs. + +Both the compiler and the linker are in fact GCC programs. @xref{Invoking GCC, +GCC options, GCC Command Options, gcc, GCC manual}, for details on GCC +options. + +@table @code +@item -Wc,@var{OPTION} +@cindex @option{-W} switch +Pass @var{OPTION} as an option to the compiler. + +@item -Wa,@var{OPTION} +@cindex @option{-Wa} switch +Pass @var{OPTION} as an option to the assembler. + +@item -Wl,@var{OPTION} +@cindex @option{-Wl} switch +Pass @var{OPTION} as an option to the linker. +@end table + +@node GHDL warnings, Rebuilding commands, Passing options to other programs, Invoking GHDL +@comment node-name, next, previous, up +@section GHDL warnings +Some contructions are not erroneous but dubious. Warnings are diagnostic +messages that report such constructions. Some warnings are reported only +during analysis, others during elaboration. + +@table @code +@item --warn-reserved +@cindex @option{--warn-reserved} switch +Emit a warning if an identifier is a reserved word in a latter VHDL standard. + +@item --warn-default-binding +@cindex @option{--warn-default-binding} switch +During analyze, warns if a component instantiation has neither +configuration specification nor default binding. This may be usefull if you +want to detect during analyze possibly unbound component if you don't use +configuration. @xref{VHDL standards}, for more details about default binding +rules. + +@item --warn-binding +@cindex @option{--warn-binding} switch +During elaboration, warns if a component instantiation is not bound +(and not explicitly left unbound). Also warns if a port of an entity +is not bound in a configuration specification or in a component +configuration. This warning is enabled by default, since default +binding rules are somewhat complex and an unbound component is most +often unexpected. + +However, warnings are even emitted if a component instantiation is +inside a generate statement. As a consequence, if you use conditionnal +generate statement to select a component according to the implementation, +you will certainly get warnings. + +@item --warn-library +@cindex @option{--warn-library} switch +Warns if a design unit replaces another design unit with the same name. + +@item --warn-vital-generic +@cindex @option{--warn-vital-generic} switch +Warns if a generic name of a vital entity is not a vital generic name. This +is set by default. + +@item --warn-delayed-checks +@cindex @option{--warn-delayed-checks} switch +Warns for checks that cannot be done during analysis time and are postponed to +elaboration time. These checks are checks for no wait statement in a procedure +called in a sensitized process. If the body of the procedure is not known +at analysis time, the check will be performed during elaboration. + +@item --warn-body +@cindex @option{--warn-body} switch +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. + +@item --warn-specs +@cindex @option{--warn-specs} switch +Emit a warning if an all or others specification does not apply. + +@item --warn-unused +@cindex @option{--warn-unused} switch +Emit a warning when a subprogram is never used. + +@item --warn-error +@cindex @option{--warn-error} switch +When this option is set, warnings are considered as errors. + +@end table + +@node Rebuilding commands, Library commands, GHDL warnings, Invoking GHDL +@comment node-name, next, previous, up +@section Rebuilding commands +Analyzing and elaborating a design consisting in severals files can be tricky, +due to dependences. GHDL has a few commands to rebuild a design. + +@menu +* Import command:: +* Make command:: +* Generate Makefile command:: +@end menu + +@node Import command, Make command, Rebuilding commands, Rebuilding commands +@comment node-name, next, previous, up +@subsection Import command +@cindex importing files +@cindex @option{-i} coomand +Add files in the work design library. + +@smallexample +$ ghdl -i [@var{options}] @var{file}@dots{} +@end smallexample + +All the files specified in the command line are scanned, parsed and added in +the libraries but as not yet analyzed. No object files are created. + +The purpose of this command is to localize design units in the design files. +The make command will then be able to recursively build a hierarchy from +an entity name or a configuration name. + +Since the files are parsed, there must be correct files. However, since they +are not analyzed, many errors are tolerated by this command. + +Note that all the files are added in the work library. If you have many +libraries, you must use the command for each library. + +@c Due to the LRM rules, there may be many analysis orders, producing +@c different results. For example, if an entity has several architectures, +@c the last architecture analyzed is the default one in default binding +@c indications. + +@xref{Make command}, to actually build the design. + +@node Make command, Generate Makefile command, Import command, Rebuilding commands +@comment node-name, next, previous, up +@subsection Make command +@cindex make +@cindex @option{-m} command +@smallexample +$ ghdl -m [@var{options}] @var{primary} [@var{secondary}] +@end smallexample + +Analyze automatically outdated files and elaborate a design. + +The primary unit denoted by the @var{primary} argument must already be +known by the system, either because you have already analyzed it (even +if you have modified it) or because you have imported it. GHDL analyzes +all outdated files. A file may be outdated because it has been modified +(e.g. you just have edited it), or because a design unit contained in +the file depends on a unit which is outdated. This rule is of course +recursive. + +With the @option{-f} (force) option, GHDL analyzes all the units of the +work library needed to create the design hierarchy. Not outdated units +are recompiled. This is useful if you want to compile a design hierarch +with new compilation flags (for example, to add the @option{-g} +debugging option). + +The make command will only re-analyze design units in the work library. +GHDL fails if it has to analyze an outdated unit from another library. + +The purpose of this command is to be able to compile a design without prior +knowledge of file order. In the VHDL model, some units must be analyzed +before others (e.g. an entity before its architecture). It might be a +nightmare to analyze a full design of several files, if you don't have +the ordered list of file. This command computes an analysis order. + +The make command fails when a unit was not previously parsed. For +example, if you split a file containing several design units into +several files, you must either import these new files or analyze them so +that GHDL knows in which file these units are. + +The make command imports files which have been modified. Then, a design +hierarchy is internally built as if no units are outdated. Then, all outdated +design units, using the dependences of the design hierarchy, are analyzed. +If necessary, the design hierarchy is elaborated. + +This is not perfect, since defaults 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. + +@c does not exists: @section GHDL robust make command + +@node Generate Makefile command, , Make command, Rebuilding commands +@comment node-name, next, previous, up +@subsection Generate Makefile command +@cindex @option{--gen-makefile} command +Generate a Makefile to build a design unit. + +@smallexample +$ ghdl --gen-makefile [@var{options}] @var{primary} [@var{secondary}] +@end smallexample + +This command works like the make command (@pxref{Make command}), but only a +makefile is generated on the standard output. + +@node Library commands, Cross-reference command, Rebuilding commands, Invoking GHDL +@comment node-name, next, previous, up +@section Library commands +GHDL has a few commands which act on a library. + +@comment node-name, next, previous, up +@menu +* Directory command:: +* Clean command:: +* Remove command:: +@end menu + +@node Directory command, Clean command, Library commands, Library commands +@comment node-name, next, previous, up +@subsection Directory command +@cindex displaying library +@cindex @option{-d} command +Display the name of the units contained in a design library. +@smallexample +$ ghdl -d [@var{options}] +@end smallexample + +The directory command, selected with the @var{-d} command line argument +displays the content of the work design library. All options are +allowed, but only a few are meaningful: @option{--work=NAME}, +@option{--workdir=PATH} and @option{--std=VER}. + +@node Clean command, Remove command, Directory command, Library commands +@comment node-name, next, previous, up +@subsection Clean command +@cindex cleaning +@cindex @option{--clean} command +Remove object and executable files but keep the library. + +@smallexample +$ ghdl --clean [@var{options}] +@end smallexample + +GHDL tries to remove any object, executable or temporary file it could +have created. Source files are not removed. + +There is no short command line form for this option to prevent accidental +clean up. + +@node Remove command, , Clean command, Library commands +@subsection Remove command +@cindex cleaning all +@cindex @option{--remove} command +Do like the clean command but remove the library too. + +@smallexample +$ ghdl --remove [@var{options}] +@end smallexample + +There is no short command line form for this option to prevent accidental +clean up. Note that after removing a design library, the files are not +known anymore by GHDL. + +@node Cross-reference command, File commands, Library commands, Invoking GHDL +@comment node-name, next, previous, up +@section Cross-reference command +To easily navigate through your sources, you may generate cross-references. + +@smallexample +$ ghdl --xref-html [@var{options}] @var{file}@dots{} +@end smallexample + +This command generates an html file for each @var{file} given in the command +line, with syntax highlighting and full cross-reference: every identifier is +a link to its declaration. Besides, an index of the files is created too. + +The set of @var{file} are analyzed, and then, if the analyze is +successful, html files are generated in the directory specified by the +@option{-o @var{dir}} option, or @file{html/} directory by default. + +If the @option{--format=html2} is specified, then the generated html +files follow the HTML 2.0 standard, and colours are specified with +@samp{} tags. However, colours are hard-coded. + +If the @option{--format=css} is specified, then the generated html files +follow the HTML 4.0 standard, and use the CSS-1 file @file{ghdl.css} to +specify colours. This file is generated only if it does not already exist (it +is never overwritten) and can be customized by the user to change colours or +appearance. Refer to a generated file and its comments for more informations. + +@node File commands, Misc commands, Cross-reference command, Invoking GHDL +@comment node-name, next, previous, up +@section File commands +The following commands act on one or severals files. They do not analysis +files, therefore, they work even if a file has semantic errors. + +@menu +* Pretty print command:: +* Find command:: +* Chop command:: +* Lines command:: +@end menu + +@node Pretty print command, Find command, File commands, File commands +@comment node-name, next, previous, up +@subsection Pretty print command +@cindex @option{--pp-html} command +@cindex pretty printing +@cindex vhdl to html + +Generate HTML on standard output from VHDL. + +@smallexample +$ ghdl --pp-html [@var{options}] @var{file}@dots{} +@end smallexample + +The files are just scanned and an html file, with syntax highlighting is +generated on standard output. + +Since the files are not even parsed, erroneous files or uncomplete designs +can be pretty printed. + +The style of the html file can be modified with the @option{--format=} option. +By default or when the @option{--format=html2} option is specified, the output +is an HTML 2.0 file, with colours set throught @samp{} tags. When the +@option{--format=css} option is specified, the output is an HTML 4.0 file, +with colours set through a CSS file, whose name is @samp{ghdl.css}. +@xref{Cross-reference command}, for more details about this CSS file. + +@node Find command, Chop command, Pretty print command, File commands +@comment node-name, next, previous, up +@subsection Find command +@cindex @option{-f} command +Display the name of the design units in files. + +@smallexample +$ ghdl -f @var{file}@dots{} +@end smallexample + +The files are scanned, parsed and the names of design units are displayed. +Design units marked with two stars are candidate to be at the apex of a +design hierarchy. + + +@node Chop command, Lines command, Find command, File commands +@comment node-name, next, previous, up +@subsection Chop command +@cindex @option{--chop} command +Chop (or split) files at design unit. + +@smallexample +$ ghdl --chop @var{files} +@end smallexample + +@code{GHDL} reads files, and writes a file in the current directory for +every design unit. + +The file name of a design unit is build according to the unit. For an +entity declaration, a package declaration or a configuration the file +name is @file{NAME.vhdl}, where @var{NAME} is the name of the design +unit. For a package body, the file name is @file{NAME-body.vhdl}. +Finally, for an architecture @var{ARCH} of an entity @var{ENTITY}, the +file name is @file{ENTITY-ARCH.vhdl}. + +Since the input files are parsed, this command aborts in case of syntax +error. The command aborts too if a file to be written already exists. + +Comments between design units are stored into the most adequate files. + +This command may be useful to split big files, if your computer has not +enough memory to compile such files. The size of the executable is +reduced too. + +@node Lines command, , Chop command, File commands +@comment node-name, next, previous, up +@subsection Lines command +@cindex @option{--lines} command +Display on the standard output lines of files preceded by line number. + +@smallexample +$ ghdl --lines @var{files} +@end smallexample + +@node Misc commands, IEEE library pitfalls, File commands, Invoking GHDL +@comment node-name, next, previous, up +@section Misc commands +There are a few GHDL commands which are seldom useful. + +@menu +* Help command:: +* Dispconfig command:: +* Disp standard command:: +* Version command:: +@end menu + +@node Help command, Dispconfig command, Misc commands, Misc commands +@subsection Help command +@cindex @option{-h} command +@cindex @option{--help} command +Display (on the standard output) a short description of the all the commands +available. If the help switch is followed by an command switch, then options +for this later command are displayed. + +@smallexample +$ ghdl --help +$ ghdl -h +$ ghdl -h @var{command} +@end smallexample + +@node Dispconfig command, Disp standard command, Help command, Misc commands +@comment node-name, next, previous, up +@subsection Dispconfig command +@cindex @option{--dispconfig} command +@cindex display configuration +Display the program pathes and options used by GHDL. + +@smallexample +$ ghdl --dispconfig [@var{options}] +@end smallexample + +This may be useful to track installation errors. + +@node Disp standard command, Version command, Dispconfig command, Misc commands +@comment node-name, next, previous, up +@subsection Disp standard command +@cindex @option{--disp-standard} command +@cindex display @samp{std.standard} +Display the @samp{std.standard} package: + +@smallexample +$ ghdl --disp-standard [@var{options}] +@end smallexample + +@node Version command, , Disp standard command, Misc commands +@comment node-name, next, previous, up +@subsection Version command +@cindex @option{--version} command +@cindex version +Display the @code{GHDL} version and exit. + +@smallexample +$ ghdl --version +@end smallexample + +@node IEEE library pitfalls, , Misc commands, Invoking GHDL +@comment node-name, next, previous, up +@section IEEE library pitfalls +When you use options @option{--ieee=synopsys} or @option{--ieee=mentor}, +the @code{IEEE} library contains non standard packages such as +@samp{std_logic_arith}. @c FIXME: ref + +These packages are not standard because there are not described by an IEEE +standard, even if they have been put in the @code{IEEE} library. Furthermore, +they are not really de-facto standard, because there a slight differences +between the packages of Mentor and those of Synopsys. + +Furthermore, since they are not well-thought, their use have pitfalls. For +example, this description has error during compilation: +@example +library ieee; +use ieee.std_logic_1164.all; + +-- @r{A counter from 0 to 10}. +entity counter is + port (val : out std_logic_vector (3 downto 0); + ck : std_logic; + rst : std_logic); +end counter; + +library ieee; +use ieee.std_logic_unsigned.all; + +architecture bad of counter +is + signal v : std_logic_vector (3 downto 0); +begin + process (ck, rst) + begin + if rst = '1' then + v <= x"0"; + elsif rising_edge (ck) then + if v = "1010" then -- @r{Error} + v <= x"0"; + else + v <= v + 1; + end if; + end if; + end process; + + val <= v; +end bad; +@end example + +When you analyze this design, GHDL does not accept it (too long lines +have been split for readability): +@smallexample +$ ghdl -a --ieee=synopsys bad_counter.vhdl +bad_counter.vhdl:13:14: operator "=" is overloaded +bad_counter.vhdl:13:14: possible interpretations are: +../../libraries/ieee/std_logic_1164.v93:69:5: implicit function "=" + [std_logic_vector, std_logic_vector return boolean] +../../libraries/synopsys/std_logic_unsigned.vhdl:64:5: function "=" + [std_logic_vector, std_logic_vector return boolean] +../translate/ghdldrv/ghdl: compilation error +@end smallexample +Indeed, the @code{"="} 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 @code{std_logic_vector} type is +declared and is a element to element comparaison, the second one is an +explicit declared function, with the semantic of an unsigned comparaison. + +With some analyser, the explicit declaration has priority on the implicit +declaration, and this design can be analyzed without error. However, this +is not the rule given by the VHDL LRM, and since GHDL follows these rules, +it emits an error. + +You can force GHDL to use this rule with the @option{-fexplicit} option. +@xref{GHDL options}, for more details. + +However it is easy to fix this error, by using a selected name: +@example +library ieee; +use ieee.std_logic_unsigned.all; + +architecture fixed_bad of counter +is + signal v : std_logic_vector (3 downto 0); +begin + process (ck, rst) + begin + if rst = '1' then + v <= x"0"; + elsif rising_edge (ck) then + if ieee.std_logic_unsigned."=" (v, "1010") then + v <= x"0"; + else + v <= v + 1; + end if; + end if; + end process; + + val <= v; +end fixed_bad; +@end example + +It is better to only use the standard packages defined by IEEE, which +provides the same functionnalities: +@example +library ieee; +use ieee.numeric_std.all; + +architecture good of counter +is + signal v : unsigned (3 downto 0); +begin + process (ck, rst) + begin + if rst = '1' then + v <= x"0"; + elsif rising_edge (ck) then + if v = "1010" then + v <= x"0"; + else + v <= v + 1; + end if; + end if; + end process; + + val <= std_logic_vector (v); +end good; +@end example + +@node Simulation and run time, GHDL implementation of VHDL, Invoking GHDL, Top +@comment node-name, next, previous, up +@chapter Simulation and run time + +@menu +* Simulation options:: +* Debugging VHDL programs:: +@end menu + +@node Simulation options, Debugging VHDL programs, Simulation and run time, Simulation and run time +@comment node-name, next, previous, up +@section Simulation options +In most system environments, it is possible to pass options while +invoking a program. Contrary to most programming language, there is no +standard method in VHDL to obtain the arguments or to set the exit +status. + +In GHDL, it is impossible to pass parameters to your design. A later version +could do it through the generics interfaces of the top entity. + +However, the GHDL run time behaviour can be modified with some options; for +example, it is possible to stop simulation after a certain time. + +The exit status of the simulation is @samp{EXIT_SUCCESS} (0) if the +simulation completes, or @samp{EXIT_FAILURE} (1) in case of error +(assertion failure, overflow or any constraint error). + +Here is the list of the most useful options. Some debugging options are +also available, but not described here. The @samp{--help} options lists +all options available, including the debugging one. + +@table @code +@item --assert-level=@var{LEVEL} +@cindex @option{--assert-level} option +Select the assertion level at which an assertion violation stops the +simulation. @var{LEVEL} is the name from the @code{severity_level} +enumerated type defined in the @code{standard} package or the +@samp{none} name. + +By default, only assertion violation of severity level @samp{failure} +stops the simulation. + +For example, if @var{LEVEL} was @samp{warning}, any assertion violation +with severity level @samp{warning}, @samp{error} or @samp{failure} would +stop simulation, but the assertion violation at the @samp{note} severity +level would only display a message. + +@samp{--assert-level=none} prevents any assertion violation to stop +simulation. + +@item --stop-time=@var{TIME} +@cindex @option{--stop-time} option +Stop the simulation after @var{TIME}. @var{TIME} is expressed as a time +value, @emph{without} any space. The time is the simulation time, not +the real clock time. + +For examples: + +@smallexample +$ ./my_design --stop-time=10ns +$ ./my_design --stop-time=ps +@end smallexample + +@item --stop-delta=@var{N} +@cindex @option{--stop-delta} option +Stop the simulation after @var{N} delta cycles in the same current time. +@c Delta cycles is a simulation technic used by VHDL to + +@item --disp-time +@cindex @option{--disp-time} option +@cindex display time +Display the time and delta cycle number as simulation advances. + +@item --disp-tree[@var{=KIND}] +@cindex @option{--disp-tree} option +@cindex display design hierarchy +Display the design hierarchy as a tree of instantiated design entities. +This may be useful to understand the structure of a complex +design. @var{KIND} is optional, but if set must be one of: +@table @samp +@item none +Do not display hierarchy. Same as if the option was not present. +@item inst +Display entities, architectures, instances, blocks and generates statements. +@item proc +Like @samp{inst} but also display processes. +@item port +Like @samp{proc} but display ports and signals too. +@end table +If @var{KIND} is not specified, the hierarchy is displayed with the +@samp{port} mode. + +@item --no-run +@cindex @option{--no-run} option +Do not simulate, only elaborate. This may be used with +@option{--disp-tree} to display the tree without simulating the whole +design. + +@item --vcd=@var{FILENAME} +@cindex @option{--vcd} option +@cindex vcd +@cindex value change dump +@cindex dump of signals +Dump into the VCD file @var{FILENAME} the signal values before each +non-delta cycle. If @var{FILENAME} is @samp{-}, then the standard output is +used, otherwise a file is created or overwritten. + +@dfn{VCD} (value change dump) is a file format defined +by the @code{verilog} standard and used by virtually any wave viewer. + +Since it comes from @code{verilog}, only a few VHDL types can be dumped. GHDL +dumps only signals whose base type is of the following: +@itemize @bullet +@item +types defined in the @samp{std.standard} package: +@itemize @bullet +@item +@samp{bit} +@item +@samp{bit_vector} +@end itemize +@item +types defined in the @samp{ieee.std_logic_1164} package: +@itemize @bullet +@item +@samp{std_ulogic} +@item +@samp{std_logic} (because it is a subtype of @samp{std_ulogic}) +@item +@samp{std_ulogic_vector} +@item +@samp{std_logic_vector} +@end itemize +@item +any integer type +@end itemize + +I have successfully used @code{gtkwave} to view VCD files. + +Currently, there is no way to select signals to be dumped: all signals are +dumped, which can generate big files. + +It is very unfortunate there is no standard or well-known wave file +format supporting VHDL types. If you are aware of such a free format, +please mail me (@pxref{Reporting bugs}). + +@item --wave=@var{FILENAME} +@cindex @option{--wave} option +Write the waveforms into a @code{ghw} (GHdl Waveform) file. Currently, all +the signals are dumped into the waveform file, you cannot select a hierarchy +of signals to be dumped. + +The format of this file was defined by myself and is not yet completly fixed. +It may change slightly. + +There is a patch against @code{gtkwave 1.3.56} on the ghdl website at +@uref{ghdl.free.fr}, so that it can read such files. + +Contrary to VCD files, any VHDL type can be dumped into a GHW file. + +@item --sdf=@var{PATH}=@var{FILENAME} +@item --sdf=min=@var{PATH}=@var{FILENAME} +@item --sdf=typ=@var{PATH}=@var{FILENAME} +@item --sdf=max=@var{PATH}=@var{FILENAME} +@cindex @option{--sdf} option +Do VITAL annotation on @var{PATH} with SDF file @var{FILENAME}. + +@var{PATH} is a path of instances, separated with @samp{.} or @samp{/}. +Any separator can be used. Instances are component instantiation labels, +generate labels or block labels. Currently, you cannot use an indexed name. + +If the option contains a type of delay, that is @option{min=}, +@option{typ=} or @option{max=}, the annotator use respectively minimum, +typical or maximum values. If the option does not contain a type of delay, +the annotator use the typical delay. + +@xref{Backannotation}, for more details. + +@item --stack-max-size=@var{SIZE} +@cindex @option{--stack-max-size} option +Set the maximum size in bytes of the non-sensitized processes stacks. + +If the value @var{SIZE} is followed (without any space) by the @samp{k}, +@samp{K}, @samp{kb}, @samp{Kb}, @samp{ko} or @samp{Ko} multiplier, then +the size is the numeric value multiplied by 1024. + +If the value @var{SIZE} is followed (without any space) by the @samp{m}, +@samp{M}, @samp{mb}, @samp{Mb}, @samp{mo} or @samp{Mo} multiplier, then +the size is the numeric value multiplied by 1024 * 1024 = 1048576. + +Each non-sensitized process has its own stack, while the sensitized processes +share the same and main stack. This stack is the stack created by the +operating system. + +Using too small stacks may result in simulation failure due to lack of memory. +Using too big stacks may reduce the maximum number of processes. + +@item --stack-size=@var{SIZE} +@cindex @option{--stack-size} option +Set the initial size in bytes of the non-sensitized processes stack. +The @var{SIZE} value has the same format as the previous option. + +The stack of the non-sensitized processes grows until reaching the +maximum size limit. + +@item --help +Display a short description of the options accepted by the run time library. +@end table + +@node Debugging VHDL programs, , Simulation options, Simulation and run time +@comment node-name, next, previous, up +@section Debugging VHDL programs +@cindex debugging +@cindex @code{__ghdl_fatal} +@code{GDB} is a general purpose debugger for programs compiled by @code{GCC}. +Currently, there is no VHDL support for @code{GDB}. It may be difficult +to inspect variables or signals in @code{GDB}, however, @code{GDB} is +still able to display the stack frame in case of error or to set a breakpoint +at a specified line. + +@code{GDB} can be useful to precisely catch a run-time error, such as indexing +an array beyond its bounds. All error check subprograms call the +@code{__ghdl_fatal} procedure. Therefore, to catch run-time error, set +a breakpoint like this: +@smallexample +(gdb) break __ghdl_fatal +@end smallexample +When the breakpoint is hit, use the @code{where} or @code{bt} command to +display the stack frames. + +@node GHDL implementation of VHDL, GHDL implementation of VITAL, Simulation and run time, Top +@comment node-name, next, previous, up +@chapter GHDL implementation of VHDL + +This chapter describes several implementation defined aspect of VHDL in GHDL. + +@menu +* VHDL standards:: +* Source representation:: +* Library database:: +* VHDL files format:: +* Top entity:: +* Interfacing to other languages:: +@end menu + +@node VHDL standards, Source representation, GHDL implementation of VHDL, GHDL implementation of VHDL +@comment node-name, next, previous, up +@section VHDL standards +@cindex VHDL standards +@cindex IEEE 1076 +@cindex IEEE 1076a +@cindex 1076 +@cindex 1076a +@cindex v87 +@cindex v93 +@cindex v93c +@cindex v00 +@cindex v02 +This is very unfortunate, but there are many versions of the VHDL language. + +The VHDL language was first standardized in 1987 by IEEE as IEEE 1076-1987, and +is commonly referred as VHDL-87. This is certainly the most important version, +since most of the VHDL tools are still based on this standard. + +Various problems of this first standard have been analyzed by experts groups +to give reasonable ways of interpreting the unclear portions of the standard. + +VHDL was revised in 1993 by IEEE as IEEE 1076-1993. This revision is still +well-known. + +Unfortunatly, VHDL-93 is not fully compatible with VHDL-87, ie some perfectly +valid VHDL-87 programs are invalid VHDL-93 programs. Here are some of the +reasons: + +@itemize @bullet +@item +the syntax of file declaration has changed (this is the most visible source +of incompatibility), +@item +new keywords were introduced (group, impure, inertial, literal, +postponed, pure, reject, rol, ror, shared, sla, sll, sra, srl, +unaffected, xnor), +@item +some dynamic behaviours have changed (the concatenation is one of them), +@item +rules have been added. +@end itemize + +Shared variables were replaced by protected types in the 2000 revision of +the VHDL standard. This modification is also known as 1076a. Note that this +standard is not fully backward compatible with VHDL-93, since the type of a +shared variable must now be a protected type (there was no such restriction +before). + +Minors corrections were added by the 2002 revision of the VHDL standard. This +revision is not fully backward compatible with VHDL-00 since, for example, +the value of the @code{'instance_name} attribute has slighly changed. + +You can select the VHDL standard expected by GHDL with the +@samp{--std=VER} option, where @var{VER} is one of the left column of the +table below: + +@table @samp +@item 87 +Select VHDL-87 standard as defined by IEEE 1076-1987. LRM bugs corrected by +later revisions are taken into account. +@item 93 +Select VHDL-93; VHDL-87 file declarations are not accepted. +@item 93c +Select VHDL-93 standard with relaxed rules: +@itemize @bullet +@item +VHDL-87 file declarations are accepted; +@item +default binding indication rules of VHDL-02 are used. Default binding rules +are often used, but they are particulary obscure before VHDL-02. +@end itemize +@item 00 +Select VHDL-2000 standard, which adds protected types. +@item 02 +Select VHDL-2002 standard (partially implemented). +@end table + +You cannot mix VHDL-87 and VHDL-93 units. A design hierarchy must have been +completly analyzed using either the 87 or the 93 version of the VHDL standard. + +@node Source representation, Library database, VHDL standards, GHDL implementation of VHDL +@comment node-name, next, previous, up +@section Source representation +According to the VHDL standard, design units (i.e. entities, +architectures, packages, package bodies and configurations) may be +independently analyzed. + +Several design units may be grouped into a design file. + +In GHDL, a system file represents a design file. That is, a file compiled by +GHDL may contain one or more design units. + +It is common to have several design units in a design file. + +GHDL does not impose any restriction on the name of a design file +(except that the file name may not contain any control character or +spaces). + +GHDL do not keep a binary representation of the design units analyzed like +other VHDL analyzers. The sources of the design units are re-read when +needed (for example, an entity is re-read when one of its architecture is +analyzed). Therefore, if you delete or modify a source file of a unit +analyzed, GHDL will refuse to use it. + +@node Library database, VHDL files format, Source representation, GHDL implementation of VHDL +@section Library database +Each design unit analyzed is placed into a design library. By default, +the name of this design library is @samp{work}; however, this can be +changed with the @option{--work=NAME} option of GHDL. + +To keep the list of design units in a design library, GHDL creates +library files. The name of these files is @samp{NAME-objVER.cf}, where +@var{NAME} is the name of the library, and @var{VER} the VHDL version (87 +or 93) used to analyze the design units. + +You don't have to know how to read a library file. You can display it +using the @option{-d} of @code{ghdl}. The file contains the name of the +design units, as well as the location and the dependences. + +The format may change with the next version of GHDL. + +@node VHDL files format, Top entity, Library database, GHDL implementation of VHDL +@comment node-name, next, previous, up +@section VHDL files format +@cindex file format +@cindex logical name +VHDL has features to handle files. + +GHDL associates a file logical name (the VHDL file name) to an operating +system file name. The logical name @samp{STD_INPUT} is associated to +the standard input as defined by @samp{stdin} stream of the C library, +while the logical name @samp{STD_OUTPUT} is associated to the standard +output, as defined by the @samp{stdout} stream of the C library. Other +logical name are directly mapped to a file name as defined by the first +(@samp{path}) argument of the @samp{fopen} function of the C library. +For a binary file, the @samp{b} character is appended to the mode argument +(binary mode). + +If multiple file objects are associated with the same external file, a stream +is created for each object, except for the standard input or output. + +GHDL has no internal restrictions on the number of file objects that are +associated at one time with a given external file, but the operating system +may restrict the maximum number of file open at the same time. + +For more details about these point, please refer to your operation system +documentation. + +@c tell more about possible errors. + +There are two kinds of files: binary or text files. + +Text files are files of type @samp{std.textio.text}. The format is the +same as the format of any ascii file. In VHDL-87, only the first 128 +characters (7 bits) are allowed, since the character type has only 128 +literals. The end of line is system dependent. Note that the stdio +functions with the text mode are used to handle text files: the fgets +function is used to read lines. Please, refer to the manual of your C +library for more information. + +There are two kind of binary files, according to the type mark of the +file. According to the VHDL standard, binary files must be read using +the same type they are written. + +If the type mark is a non-composite type (integer, floating type +enumeration, physical), the file is a raw stream: +elements are read or written using the same format as is used to represent +the data in memory. This is highly non-portable, but you should be able +to read file written by a non-@code{GHDL} program. + +If the type mark is a composite type (record or array), the file is composed +of a 2 lines signature, followed by a raw stream. + +@node Top entity, Interfacing to other languages, VHDL files format, GHDL implementation of VHDL +@comment node-name, next, previous, up +@section Top entity +There are some restrictions on the entity being at the apex of a design +hierarchy: + +@itemize @bullet +@item +The generic must have a default value, and the value of a generic is its +default value; +@item +The ports type must be constrained. +@end itemize + +@node Interfacing to other languages, , Top entity, GHDL implementation of VHDL +@comment node-name, next, previous, up@section Interfacing with other languages +@section Interfacing to other languages +@cindex interfacing +@cindex other languages +@cindex foreign +@cindex VHPI +@cindex VHPIDIRECT +You can define a subprogram in a foreign language (such as @code{C} or +@code{Ada}) and import it in a VHDL design. + +@subsection Foreign declarations +Only subprograms (functions or procedures) can be imported, using the foreign +attribute. In this example, the @code{sin} function is imported: + +@example +package math is + function sin (v : real) return real; + attribute foreign of sin : function is "VHPIDIRECT sin"; +end math; + +package body math is + function sin (v : real) return real is + begin + assert false severity failure; + end sin; +end math; +@end example + +A subprogram is made foreign if the @var{foreign} attribute decorates +it. This attribute is declared in the 1993 revision of the +@samp{std.standard} package. Therefore, you cannot use this feature in +VHDL 1987. + +The decoration is achived through an attribute specification. The +attribute specification must be in the same declarative part as the +subprogram and must be after it. This is a general rule for specifications. +The value of the specification must be a locally static string. + +Even when a subprogram is foreign, its body must be present. However, since +it won't be called, you can made it empty or simply but an assertion. + +The value of the attribute must start with @samp{VHPIDIRECT } (an +upper-case keyword followed by one or more blanks). The linkage name of the +subprogram follows. + + +@menu +* Restrictions on foreign declarations:: +* Linking with foreign object files:: +* Starting a simulation from a foreign program:: +* Linking with Ada:: +* Using GRT from Ada:: +@end menu + +@node Restrictions on foreign declarations, Linking with foreign object files, Interfacing to other languages, Interfacing to other languages +@subsection Restrictions on foreign declarations + +Any subprogram can be imported. GHDL puts no restrictions on foreign +subprograms. However, the representation of a type or of an interface in a +foreign language may be obscur. Most of non-composite types are easily imported: +@table @samp +@item integer types +They are represented on a 32 bits word. This generally corresponds to +@code{int} for @code{C} or @code{Integer} for @code{Ada}. +@item physical types +They are represented on a 64 bits word. This generally corresponds to the +@code{long long} for @code{C} or @code{Long_Long_Integer} for @code{Ada}. +@item floating point types +They are represented on a 64 bits floating point word. This generally +corresponds to @code{double} for @code{C} or @code{Long_Float} for @code{Ada}. +@item enumeration types +They are represented on 8 bits or 32 bits word, if the number of literals is +greater than 256. There is no corresponding C types, since arguments are +not promoted. +@end table + +Non-composite types are passed by value. For the @code{in} mode, this +corresponds to the @code{C} or @code{Ada} mechanism. The @code{out} and +@code{inout} interfaces of non-composite types are gathered in a record +and this record is passed by reference as the first argument to the +subprogram. As a consequence, you shouldn't use @code{in} and +@code{inout} modes in foreign subprograms, since they are not portable. + +Records are represented like a @code{C} structure and are passed by reference +to subprograms. + +Arrays with static bounds are represented like a @code{C} array, whose +length is the number of elements, and are passed by reference to subprograms. + +Unconstrained array are represented by a fat pointer. Do not use unconstrained +arrays in foreign subprograms. + +Accesses to an unconstrained array is a fat pointer. Other accesses corresponds a an address and are passed to a subprogram like other non-composite types. + +Files are represented by a 32 bits word, which corresponds to an index +in a table. + +@node Linking with foreign object files, Starting a simulation from a foreign program, Restrictions on foreign declarations, Interfacing to other languages +@subsection Linking with foreign object files +You may add additionnal files or options during the link using the +@option{-Wl,} of @code{GHDL}, as described in @ref{Elaboration command}. +For example: + +@example +$ ghdl -e -Wl,-lm math_tb +@end example +will create the @file{math_tb} executable with the @file{lm} (mathematical) +library. + +Note the @file{c} library is always linked with an executable. + +@node Starting a simulation from a foreign program, Linking with Ada, Linking with foreign object files, Interfacing to other languages +@subsection Starting a simulation from a foreign program +You main run your design from an external program. You just have to call +the @samp{ghdl_main} function which can be defined: + +in C: +@smallexample +extern int ghdl_main (int argc, char **argv); +@end smallexample + +in Ada: +@smallexample +with System; +@dots{} +function Ghdl_Main (Argc : Integer; Argv : System.Address) + return Integer; +pragma import (C, Ghdl_Main, "ghdl_main"); +@end smallexample + +This function must be called once, and returns 0 at the end of the simulation. +In case of failure, this function does not return. This has to be fixed. + +@node Linking with Ada, Using GRT from Ada, Starting a simulation from a foreign program, Interfacing to other languages +@subsection Linking with Ada +As explained previously in @ref{Starting a simulation from a foreign program}, +you can start a simulation from an @code{Ada} program. However the build +process is not trivial: you have to elaborate your @code{Ada} program and your +@code{VHDL} design. + +First, you have to analyze all your design files. In this example, we +suppose there is only one design file, @file{design.vhdl}. +@smallexample +$ ghdl -a design.vhdl +@end smallexample +Then, bind your design. In this example, we suppose the entity at the +design apex is @samp{design}. +@smallexample +$ ghdl --bind design +@end smallexample +Finally, compile, bind your @code{Ada} program at link it with your @code{VHDL} +design: +@smallexample +$ gnatmake my_prog -largs `ghdl --list-link design` +@end smallexample + +@node Using GRT from Ada, , Linking with Ada, Interfacing to other languages +@comment node-name, next, previous, up +@subsection Using GRT from Ada +@quotation Warning +This topic is only for advanced users knowing how to use @code{Ada} +and @code{GNAT}. This is provided only for reference, I have tested +this once before releasing @code{GHDL} 0.19 but this is not checked at +each release. +@end quotation + +The simulator kernel of @code{GHDL} named @dfn{GRT} is written in +@code{Ada95} and contains a very light and slighly adapted version +of @code{VHPI}. Since it is an @code{Ada} implementation it is +called @dfn{AVHPI}. Although being tough, you may interface to @code{AVHPI}. + +For using @code{AVHPI}, you need the sources of @code{GHDL} and to recompile +them (at least the @code{GRT} library). This library is usually compiled with +a @code{No_Run_Time} pragma, so that the user does not need to install the +@code{GNAT} run time library. However, you certainly want to use the usual +run time library and want to avoid this pragma. For this, reset the +@var{GRT_PRAGMA_FLAG} variable. +@smallexample +$ make GRT_PRAGMA_FLAG= grt-all +@end smallexample + +Since @code{GRT} is a self-contained library, you don't want +@code{gnatlink} to fetch individual object files (furthermore this +doesn't always work due to tricks used in @code{GRT}). For this, +remove all the object files and make the @file{.ali} files read-only. +@smallexample +$ rm *.o +$ chmod -w *.ali +@end smallexample + +You may then install the sources files and the @file{.ali} files. I have never +tested this step. + +You are now ready to use it. + +For example, here is an example, @file{test_grt.adb} which displays the top +level design name. +@example +with System; use System; +with Grt.Avhpi; use Grt.Avhpi; +with Ada.Text_IO; use Ada.Text_IO; +with Ghdl_Main; + +procedure Test_Grt is + -- VHPI handle. + H : VhpiHandleT; + Status : Integer; + + -- Name. + Name : String (1 .. 64); + Name_Len : Integer; +begin + -- Elaborate and run the design. + Status := Ghdl_Main (0, Null_Address); + + -- Display the status of the simulation. + Put_Line ("Status is " & Integer'Image (Status)); + + -- Get the root instance. + Get_Root_Inst(H); + + -- Disp its name using vhpi API. + Vhpi_Get_Str (VhpiNameP, H, Name, Name_Len); + Put_Line ("Root instance name: " & Name (1 .. Name_Len)); +end Test_Grt; +@end example + +First, analyze and bind your design: +@smallexample +$ ghdl -a counter.vhdl +$ ghdl --bind counter +@end smallexample + +Then build the whole: +@smallexample +$ gnatmake test_grt -aL@var{grt_ali_path} -aI@var{grt_src_path} -largs + `ghdl --list-link counter` +@end smallexample + +Finally, run your design: +@smallexample +$ ./test_grt +Status is 0 +Root instance name: counter +@end smallexample + +@node GHDL implementation of VITAL, Flaws and bugs report, GHDL implementation of VHDL, Top +@comment node-name, next, previous, up +@chapter GHDL implementation of VITAL +@cindex VITAL +@cindex IEEE 1076.4 +@cindex 1076.4 +This chapter describes how VITAL is implemented in GHDL. Support of VITAL is +really in a preliminary stage. Do not expect too much of it as now. + +@menu +* VITAL packages:: +* VHDL restrictions for VITAL:: +* Backannotation:: +* Negative constraint calculation:: +@end menu + +@node VITAL packages, VHDL restrictions for VITAL, GHDL implementation of VITAL, GHDL implementation of VITAL +@comment node-name, next, previous, up +@section VITAL packages +The VITAL standard or IEEE 1076.4 was first published in 1995, and revised in +2000. + +The version of the VITAL packages depends on the VHDL standard. VITAL +1995 packages are used with the VHDL 1987 standard, while VITAL 2000 +packages are used with other standards. This choice is based on the +requirements of VITAL: VITAL 1995 requires the models follow the VHDL +1987 standard, while VITAL 2000 requires the models follow VHDL 1993. + +The VITAL 2000 packages were slighly modified so that they conform to +the VHDL 1993 standard (a few functions are made pure and a few one +impure). + +@node VHDL restrictions for VITAL, Backannotation, VITAL packages, GHDL implementation of VITAL +@comment node-name, next, previous, up +@section VHDL restrictions for VITAL +The VITAL standard (partially) implemented is the IEEE 1076.4 standard +published in 1995. + +This standard defines restriction of the VHDL language usage on VITAL +model. A @dfn{VITAL model} is a design unit (entity or architecture) +decorated by the @code{VITAL_Level0} or @code{VITAL_Level1} attribute. +These attributes are defined in the @code{ieee.VITAL_Timing} package. + +Currently, only VITAL level 0 checks are implemented. VITAL level 1 models +can be analyzed, but GHDL doesn't check they comply with the VITAL standard. + +Moreover, GHDL doesn't check (yet) that timing generics are not read inside +a VITAL level 0 model prior the VITAL annotation. + +The analysis of a non-conformant VITAL model fails. You can disable the +checks of VITAL restrictions with the @option{--no-vital-checks}. Even when +restrictions are not checked, SDF annotation can be performed. + +@node Backannotation, Negative constraint calculation, VHDL restrictions for VITAL, GHDL implementation of VITAL +@comment node-name, next, previous, up +@section Backannotation +@cindex SDF +@dfn{Backannotation} is the process of setting VITAL generics with timing +information provided by an external files. + +The external files must be SDF (Standard Delay Format) files. GHDL +supports a tiny subset of SDF version 2.1, other version number can be +used, provided no features added by the next version are used. + +Hierarchical instance names are not supported. However you can use a list of +instances. If there is no instance, the top entity will be annotated and +the celltype must be the name of the top entity. If there is at least one +instance, the last instance name must be a component instantiation labe, and +the celltype must be the name of the component declaration instantiated. + +Instances being annotated are not required to be VITAL compliant. However +generics being annotated must follow rules of VITAL (eg, type must be a +suitable vital delay type). + +Currently, only timing constraints applying on a timing generic of type +@code{VitalDelayType01} has been implemented. This SDF annotator is +just a proof of concept. Features will be added with the following GHDL +release. + +@node Negative constraint calculation, , Backannotation, GHDL implementation of VITAL +@comment node-name, next, previous, up +@section Negative constraint calculation +Negative constraint delay adjustement are necessary to handle negative +constraint such as a negative setup time. This step is defined in the VITAL +standard and should occurs after backannotation. + +GHDL does not do negative constraint calculation. It fails to handle models +with negative constraint. I hope to be able to add this phase soon. + +@node Flaws and bugs report, Copyrights, GHDL implementation of VITAL, Top +@comment node-name, next, previous, up +@chapter Flaws and bugs report + +The current version of GHDL is really a beta version. Some features of +VHDL have not been implemented or are only partially implemented. Besides, +GHDL has not been extensively tested yet. + +@menu +* Deficiencies:: +* Reporting bugs:: +* Future improvements:: +@end menu + +@node Deficiencies, Reporting bugs, Flaws and bugs report, Flaws and bugs report +@comment node-name, next, previous, up +@section Deficiencies +Here is the non-exhaustive list of flaws: + +@itemize @bullet +@item +So far, @code{GHDL} has been compiled and tested only on @samp{i386-linux} systems. +@item +Overflow detection is not yet implemented. +@item +Some contraint checks are missing. +@item +VHDL-93 is not completly implemented. +@item +There are no checks for elaboration order. +@item +This list is not exhaustive. +@item +@dots{} +@end itemize + +@node Reporting bugs, Future improvements, Deficiencies, Flaws and bugs report +@comment node-name, next, previous, up +@section Reporting bugs +In order to improve GHDL, we welcome bugs report and suggestions for any +aspect of GHDL. Please email them to @email{ghdl@@free.fr}. + +If the compiler crashes, this is a bug. Reliable tools never crash. + +If your compiled VHDL executable crashes, this may be a bug at +run time or the code produced may be wrong. However, since VHDL +has a notion of pointers, an erroneous VHDL program (using invalid +pointers for example) may crash. + +If the compiler emits an error message for a perfectly valid input or +does not emit an error message for an invalid input, this may be a bug. +Please send the input file and what you expected. If you know the LRM +well enough, please specify the paragraph which has not been well +implemented. If you don't know the LRM, maybe your bug report will be +rejected simply because there is no bug. In the latter case, it may be +difficult to discuss the issue; and comparisons with other VHDL tools +is not a very strong argument. + +If a compiler message is not clear enough for you, please tell me. The +error messages can be improved, but I have not enough experience with +them. + +If you have found a mistake in the manual, please send a comment. If +you have not understood some parts of this manual, please tell me. +English is not my mother tongue, so this manual may not be well-written. +Again, rewriting part of it is a good way to improve it. + +If you send a @code{VHDL} file producing a bug, it is a good idea to try +to make it as short as possible. It is also a good idea to make it +looking like a test: write a comment which explains wether the file +should compile, and if yes, whether or not it should run successfully. +In the latter case, an assert statement should finish the test; the +severity level note indicates success, while a severity level failure +indicates failure. + +For bug reports, please include enough information for the maintainers to +reproduce the problem. This includes: + +@itemize @bullet +@item +the version of @code{GHDL} (you can get it with @samp{ghdl --version}). +@item +the operating system +@item +whether you have built @code{GHDL} from sources or used the binary +distribution. +@item +the content of the input files +@item +a description of the problem and samples of any erroneous input +@item +anything else that you think would be helpful. +@end itemize + +@node Future improvements, , Reporting bugs, Flaws and bugs report +@comment node-name, next, previous, up +@section Future improvements +I have several axes for @code{GHDL} improvements: +@itemize @bullet +@item +Documentation. +@item +Better diagnostics messages (warning and error). +@item +Full support of VHDL-87 and VHDL-93. +@item +Support of VHDL-02. +@item +Optimization (simulation speed). +@item +Graphical tools (to see waves and to debug) +@item +Style checks +@item +VITAL acceleration +@end itemize + +@c And without any order: +@c VHPI +@c FOREIGN +@c AMS +@c verilog + +@node Copyrights, Index, Flaws and bugs report, Top +@comment node-name, next, previous, up +@chapter Copyrights + +The GHDL front-end, the @samp{std.textio} package and the run-time +library (grt) are copyrighted Tristan Gingold, come with @emph{absolutely +no warranty}, and are distributed under the conditions of the General +Public License. + +The @samp{ieee.numeric_bit} and @samp{ieee.numeric_std} packages are +copyrighted by the IEEE. The source files may be distributed without +change, except as permitted by the standard. +@comment FIXME: this sounds strange +This source file may not be +sold or distributed for profit. See the source file and the IEEE 1076.3 +standard for more information. + +The @samp{ieee.std_logic_1164} package is copyrighted by the IEEE. See +source file and the IEEE 1164 standard for more information. + +The @samp{ieee.VITAL_Primitives}, @samp{ieee.VITAL_Timing} and +@samp{ieee.VITAL_Memory} packages are copyrighted by IEEE. See source +file and the IEEE 1076.4 standards for more information. + +The @samp{ieee.Math_Real} and @samp{ieee.Math_Complex} packages are +copyrighted by IEEE. These are draft versions which may used and distributed +without restriction. These packages cannot be sold or distributed for profit. +See source files for more information. + +The packages @samp{std_logic_arith}, @c @samp{std_logic_misc}, +@samp{std_logic_signed}, @samp{std_logic_unsigned} and +@samp{std_logic_textio} contained in the @samp{synopsys} directory are +copyrighted by Synopsys, Inc. The source files may be used and +distributed without restriction provided that the copyright statements +are not removed from the files and that any derivative work contains the +copyright notice. See the source files for more information. + +The package @samp{std_logic_arith} contained in the @samp{mentor} +directory is copyrighted by Mentor Graphics. The source files may be +distributed in whole without restriction provided that the copyright +statement is not removed from the file and that any derivative work +contains this copyright notice. See the source files for more information. + +As a consequence of the run-time copyright, you may not be allowed to +distribute an executable produced by @code{GHDL} without the VHDL +sources. To my mind, this is not a real restriction, since there is no +points in distributing VHDL executable. Please, send a comment +(@pxref{Reporting bugs}) if you don't like this policy. + +@node Index, , Copyrights, Top +@unnumbered Index +@printindex cp + +@bye -- cgit v1.2.3