diff options
author | Tristan Gingold <gingold@adacore.com> | 2015-11-21 05:54:42 +0100 |
---|---|---|
committer | Tristan Gingold <gingold@adacore.com> | 2015-11-24 05:22:09 +0100 |
commit | 60fd762fa36f72b9ddad8cda84b6c16c6936d942 (patch) | |
tree | bf6fe454ca4ed09519203f188b932408f6ceee5c | |
parent | 27a4852201a41e7d6f8098cc05b7b0949ebc6af4 (diff) | |
download | ghdl-60fd762fa36f72b9ddad8cda84b6c16c6936d942.tar.gz ghdl-60fd762fa36f72b9ddad8cda84b6c16c6936d942.tar.bz2 ghdl-60fd762fa36f72b9ddad8cda84b6c16c6936d942.zip |
Convert documentation to sphinx.
-rw-r--r-- | doc/Copyrights.rst | 45 | ||||
-rw-r--r-- | doc/Flaws_and_bugs_report.rst | 72 | ||||
-rw-r--r-- | doc/GHDL_implementation_of_VHDL.rst | 479 | ||||
-rw-r--r-- | doc/GHDL_implementation_of_VITAL.rst | 92 | ||||
-rw-r--r-- | doc/Introduction.rst | 73 | ||||
-rw-r--r-- | doc/Invoking_GHDL.rst | 1114 | ||||
-rw-r--r-- | doc/Simulation_and_runtime.rst | 239 | ||||
-rw-r--r-- | doc/Starting_with_GHDL.rst | 355 | ||||
-rw-r--r-- | doc/conf.py | 284 | ||||
-rw-r--r-- | doc/ghdl.html | 3032 | ||||
-rw-r--r-- | doc/ghdl.texi | 2591 | ||||
-rw-r--r-- | doc/index.rst | 28 |
12 files changed, 2781 insertions, 5623 deletions
diff --git a/doc/Copyrights.rst b/doc/Copyrights.rst new file mode 100644 index 000000000..038a9291b --- /dev/null +++ b/doc/Copyrights.rst @@ -0,0 +1,45 @@ +********** +Copyrights +********** + +The GHDL front-end, the :samp:`std.textio` package and the runtime +library (:samp:`grt`) are copyrighted Tristan Gingold, come with **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. + +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`, :samp:`ieee.Math_Real` and +:samp:`ieee.Math_Complex` packages are copyrighted by the IEEE. See +source files 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 packages :samp:`std_logic_arith`, +: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 runtime copyright, you may not be allowed to +distribute an executable produced by `GHDL` without the VHDL +sources. To my mind, this is not a real restriction, since there is no +points in distributing VHDL executable. Please, send a comment +(:ref:`Reporting_bugs`) if you don't like this policy. + diff --git a/doc/Flaws_and_bugs_report.rst b/doc/Flaws_and_bugs_report.rst new file mode 100644 index 000000000..d4b269dc2 --- /dev/null +++ b/doc/Flaws_and_bugs_report.rst @@ -0,0 +1,72 @@ +********************* +Flaws and bugs report +********************* + +Despite all the testing and already reported issues, you can find bugs +or propose enhancements. + + .. _reporting_bugs: + +Reporting bugs +============== + +In order to improve GHDL, we welcome bugs report and suggestions for +any aspect of GHDL. Please create an issue on +https://github.com/tgingold/ghdl/issues + +If the compiler crashes, this is a bug. Reliable tools never crash. + +If your compiled VHDL executable crashes, this may be a bug at +runtime or the code produced may be wrong. However, since VHDL +has a notion of pointers, an erroneous VHDL program (using invalid +pointers for example) may crash. + +If the compiler emits an error message for a perfectly valid input or +does not emit an error message for an invalid input, this may be a bug. +Please send the input file and what you expected. If you know the LRM +well enough, please specify the paragraph which has not been well +implemented. If you don't know the LRM, maybe your bug report will be +rejected simply because there is no bug. In the latter case, it may be +difficult to discuss the issue; and comparisons with other VHDL tools +is not a very strong argument. + +If a compiler message is not clear enough for you, please tell me. The +error messages can be improved, but I have not enough experience with +them. + +If you have found a mistake in the manual, please send a comment. If +you have not understood some parts of this manual, please tell me. +English is not my mother tongue, so this manual may not be well-written. +Again, rewriting part of it is a good way to improve it. + +If you send a `VHDL` file producing a bug, it is a good idea to try +to make it as short as possible. It is also a good idea to make it +looking like a test: write a comment which explains whether the file +should compile, and if yes, whether or not it should run successfully. +In the latter case, an assert statement should finish the test; the +severity level note indicates success, while a severity level failure +indicates failure. + +For bug reports, please include enough information for the maintainers to +reproduce the problem. This includes: + +* the version of `GHDL` (you can get it with :samp:`ghdl --version`). +* the operating system +* whether you have built `GHDL` from sources or used the binary + distribution. +* the content of the input files +* a description of the problem and samples of any erroneous input +* anything else that you think would be helpful. + +Future improvements +=================== + +I have several axes for `GHDL` improvements: + +* Documentation. +* Better diagnostics messages (warning and error). +* Full support of VHDL-2008. +* Optimization (simulation speed). +* Graphical tools (to see waves and to debug) +* Style checks +* VITAL acceleration diff --git a/doc/GHDL_implementation_of_VHDL.rst b/doc/GHDL_implementation_of_VHDL.rst new file mode 100644 index 000000000..808c39140 --- /dev/null +++ b/doc/GHDL_implementation_of_VHDL.rst @@ -0,0 +1,479 @@ +*************************** +GHDL implementation of VHDL +*************************** + +This chapter describes several implementation defined aspect of VHDL in GHDL. + +.. _VHDL_standards: + +VHDL standards +============== + +.. index:: VHDL standards + +.. index:: IEEE 1076 + +.. index:: IEEE 1076a + +.. index:: 1076 + +.. index:: 1076a + +.. index:: v87 + +.. index:: v93 + +.. index:: v93c + +.. index:: v00 + +.. index:: v02 + +This is very unfortunate, but there are many versions of the VHDL +language, and they aren't backward compatible. + +The VHDL language was first standardized in 1987 by IEEE as IEEE 1076-1987, and +is commonly referred as VHDL-87. This is certainly the most important version, +since most of the VHDL tools are still based on this standard. + +Various problems of this first standard have been analyzed by experts groups +to give reasonable ways of interpreting the unclear portions of the standard. + +VHDL was revised in 1993 by IEEE as IEEE 1076-1993. This revision is still +well-known. + +Unfortunately, VHDL-93 is not fully compatible with VHDL-87, i.e. some perfectly +valid VHDL-87 programs are invalid VHDL-93 programs. Here are some of the +reasons: + +* the syntax of file declaration has changed (this is the most visible source + of incompatibility), +* new keywords were introduced (group, impure, inertial, literal, + postponed, pure, reject, rol, ror, shared, sla, sll, sra, srl, + unaffected, xnor), +* some dynamic behaviours have changed (the concatenation is one of them), +* rules have been added. + +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 `'instance_name` attribute has slightly changed. + +You can select the VHDL standard expected by GHDL with the +:samp:`--std=VER` option, where :samp:`VER` is one of the left column of the +table below: + + +87 + Select VHDL-87 standard as defined by IEEE 1076-1987. LRM bugs corrected by + later revisions are taken into account. + +93 + Select VHDL-93; VHDL-87 file declarations are not accepted. + +93c + Select VHDL-93 standard with relaxed rules: + + + * VHDL-87 file declarations are accepted; + + * default binding indication rules of VHDL-02 are used. Default binding rules + are often used, but they are particularly obscure before VHDL-02. + +00 + Select VHDL-2000 standard, which adds protected types. + +02 + Select VHDL-2002 standard + +08 + Select VHDL-2008 standard (partially implemented). + +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. + +.. _psl_implementation: + +PSL implementation +================== + +GHDL understands embedded PSL annotations in VHDL files, but not in +separate files. + +As PSL annotations are embedded within comments, you must analyze and elaborate +your design with option *-fpsl* to enable PSL annotations. + +A PSL assertion statement must appear within a comment that starts +with the `psl` keyword. The keyword must be followed (on the +same line) by a PSL keyword such as `assert` or `default`. +To continue a PSL statement on the next line, just start a new comment. + +A PSL statement is considered as a process. So it is not allowed within +a process. + +All PSL assertions must be clocked (GHDL doesn't support unclocked assertion). +Furthermore only one clock per assertion is allowed. + +You can either use a default clock like this: + +.. code-block:: VHDL + + -- psl default clock is rising_edge (CLK); + -- psl assert always + -- a -> eventually! b; + +or use a clocked expression (note the use of parenthesis): + +.. code-block:: VHDL + + -- psl assert (always a -> next[3](b)) @rising_edge (clk); + + +Of course only the simple subset of PSL is allowed. + +Currently the built-in functions are not implemented. + +Source representation +===================== + +According to the VHDL standard, design units (i.e. entities, +architectures, packages, package bodies and configurations) may be +independently analyzed. + +Several design units may be grouped into a design file. + +In GHDL, a system file represents a design file. That is, a file compiled by +GHDL may contain one or more design units. + +It is common to have several design units in a design file. + +GHDL does not impose any restriction on the name of a design file +(except that the filename may not contain any control character or +spaces). + +GHDL do not keep a binary representation of the design units analyzed like +other VHDL analyzers. The sources of the design units are re-read when +needed (for example, an entity is re-read when one of its architecture is +analyzed). Therefore, if you delete or modify a source file of a unit +analyzed, GHDL will refuse to use it. + +.. _Library_database: + +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 :file:`NAME-objVER.cf`, where +`NAME` is the name of the library, and `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 *-d* of `ghdl`. The file contains the name of the +design units, as well as the location and the dependencies. + +The format may change with the next version of GHDL. + +.. _Top_entity: + +Top entity +========== + +There are some restrictions on the entity being at the apex of a design +hierarchy: + +* The generic must have a default value, and the value of a generic is its + default value; +* The ports type must be constrained. + +Using vendor libraries +====================== + +Many vendors libraries have been analyzed with GHDL. There are +usually no problems. Be sure to use the :option:`--work=` option. +However, some problems have been encountered. + +GHDL follows the VHDL LRM (the manual which defines VHDL) more +strictly than other VHDL tools. You could try to relax the +restrictions by using the :option:`--std=93c`, :option:`-fexplicit`, +:option:`-frelaxed-rules` and :option:`--warn-no-vital-generic`. + +Interfacing to other languages +============================== + +.. index:: interfacing + +.. index:: other languages + +.. index:: foreign + +.. index:: VHPI + +.. index:: VHPIDIRECT + +Interfacing with foreign languages is possible only on GNU/Linux systems. + +You can define a subprogram in a foreign language (such as `C` or +`Ada`) and import it in a VHDL design. + +Foreign declarations +-------------------- + +Only subprograms (functions or procedures) can be imported, using the foreign +attribute. In this example, the `sin` function is imported: + +.. code-block:: VHDL + + 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; + + +A subprogram is made foreign if the `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 achieved through an attribute specification. The +attribute specification must be in the same declarative part as the +subprogram and must be after it. This is a general rule for specifications. +The value of the specification must be a locally static string. + +Even when a subprogram is foreign, its body must be present. However, since +it won't be called, you can made it empty or simply but an assertion. + +The value of the attribute must start with :samp:`VHPIDIRECT` (an +upper-case keyword followed by one or more blanks). The linkage name of the +subprogram follows. + +.. _Restrictions_on_foreign_declarations: + +Restrictions on foreign declarations +------------------------------------ + +Any subprogram can be imported. GHDL puts no restrictions on foreign +subprograms. However, the representation of a type or of an interface in a +foreign language may be obscure. Most of non-composite types are easily imported: + + +*integer types* + They are represented on a 32 bits word. This generally corresponds to + `int` for `C` or `Integer` for `Ada`. + +*physical types* + They are represented on a 64 bits word. This generally corresponds to the + `long long` for `C` or `Long_Long_Integer` for `Ada`. + +*floating point types* + They are represented on a 64 bits floating point word. This generally + corresponds to `double` for `C` or `Long_Float` for `Ada`. + +*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. + +Non-composite types are passed by value. For the `in` mode, this +corresponds to the `C` or `Ada` mechanism. The `out` and +`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 `in` and +`inout` modes in foreign subprograms, since they are not portable. + +Records are represented like a `C` structure and are passed by reference +to subprograms. + +Arrays with static bounds are represented like a `C` array, whose +length is the number of elements, and are passed by reference to subprograms. + +Unconstrained array are represented by a fat pointer. Do not use unconstrained +arrays in foreign subprograms. + +Accesses to an unconstrained array is a fat pointer. Other accesses correspond to an address and are passed to a subprogram like other non-composite types. + +Files are represented by a 32 bits word, which corresponds to an index +in a table. + +.. _Linking_with_foreign_object_files: + +Linking with foreign object files +--------------------------------- + +You may add additional files or options during the link using the +*-Wl,* of `GHDL`, as described in :ref:`Elaboration_command`. +For example:: + + ghdl -e -Wl,-lm math_tb + +will create the :file:`math_tb` executable with the :file:`lm` (mathematical) +library. + +Note the :file:`c` library is always linked with an executable. + +.. _Starting_a_simulation_from_a_foreign_program: + +Starting a simulation from a foreign program +-------------------------------------------- + +You may run your design from an external program. You just have to call +the :samp:`ghdl_main` function which can be defined: + +in C: + +.. code-block:: C + + extern int ghdl_main (int argc, char **argv); + +in Ada: + +.. code-block:: Ada + + with System; + ... + function Ghdl_Main (Argc : Integer; Argv : System.Address) + return Integer; + pragma import (C, Ghdl_Main, "ghdl_main"); + + +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. + +.. _Linking_with_Ada: + +Linking with Ada +---------------- + +As explained previously in :ref:`Starting_a_simulation_from_a_foreign_program`, +you can start a simulation from an `Ada` program. However the build +process is not trivial: you have to elaborate your `Ada` program and your +`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`. + +:: + + $ ghdl -a design.vhdl + +Then, bind your design. In this example, we suppose the entity at the +design apex is :samp:`design`. + +:: + + $ ghdl --bind design + +Finally, compile, bind your `Ada` program at link it with your `VHDL` +design:: + + $ gnatmake my_prog -largs `ghdl --list-link design` + + +Using GRT from Ada +------------------ + +.. warning:: + This topic is only for advanced users knowing how to use `Ada` + and `GNAT`. This is provided only for reference, I have tested + this once before releasing `GHDL` 0.19 but this is not checked at + each release. + +The simulator kernel of `GHDL` named :dfn:`GRT` is written in +`Ada95` and contains a very light and slightly adapted version +of `VHPI`. Since it is an `Ada` implementation it is +called :dfn:`AVHPI`. Although being tough, you may interface to `AVHPI`. + +For using `AVHPI`, you need the sources of `GHDL` and to recompile +them (at least the `GRT` library). This library is usually compiled with +a `No_Run_Time` pragma, so that the user does not need to install the +`GNAT` runtime library. However, you certainly want to use the usual +runtime library and want to avoid this pragma. For this, reset the +`GRT_PRAGMA_FLAG` variable. + +:: + + $ make GRT_PRAGMA_FLAG= grt-all + + +Since `GRT` is a self-contained library, you don't want +`gnatlink` to fetch individual object files (furthermore this +doesn't always work due to tricks used in `GRT`). For this, +remove all the object files and make the :file:`.ali` files read-only. + +:: + + $ rm *.o + $ chmod -w *.ali + + +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. + +.. code-block:: Ada + + 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; + + +First, analyze and bind your design:: + + $ ghdl -a counter.vhdl + $ ghdl --bind counter + + +Then build the whole:: + + $ gnatmake test_grt -aL`grt_ali_path` -aI`grt_src_path` -largs + `ghdl --list-link counter` + + +Finally, run your design:: + + $ ./test_grt + Status is 0 + Root instance name: counter diff --git a/doc/GHDL_implementation_of_VITAL.rst b/doc/GHDL_implementation_of_VITAL.rst new file mode 100644 index 000000000..675510048 --- /dev/null +++ b/doc/GHDL_implementation_of_VITAL.rst @@ -0,0 +1,92 @@ +**************************** +GHDL implementation of VITAL +**************************** + +.. index:: VITAL + +.. index:: IEEE 1076.4 + +.. index:: 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. + +.. _vital_packages: + +VITAL packages +============== + +The VITAL standard or IEEE 1076.4 was first published in 1995, and revised in +2000. + +The version of the VITAL packages depends on the VHDL standard. VITAL +1995 packages are used with the VHDL 1987 standard, while VITAL 2000 +packages are used with other standards. This choice is based on the +requirements of VITAL: VITAL 1995 requires the models follow the VHDL +1987 standard, while VITAL 2000 requires the models follow VHDL 1993. + +The VITAL 2000 packages were slightly modified so that they conform to +the VHDL 1993 standard (a few functions are made pure and a few one +impure). + +.. _vhdl_restrictions_for_vital: + +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 `VITAL_Level0` or `VITAL_Level1` attribute. +These attributes are defined in the `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 *--no-vital-checks*. Even when +restrictions are not checked, SDF annotation can be performed. + +.. _backannotation: + +Backannotation +============== + +.. index:: 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 label, and +the celltype must be the name of the component declaration instantiated. + +Instances being annotated are not required to be VITAL compliant. However +generics being annotated must follow rules of VITAL (e.g., type must be a +suitable vital delay type). + +Currently, only timing constraints applying on a timing generic of type +`VitalDelayType01` has been implemented. This SDF annotator is +just a proof of concept. Features will be added with the following GHDL +release. + +Negative constraint calculation +=============================== + +Negative constraint delay adjustment are necessary to handle negative +constraint such as a negative setup time. This step is defined in the VITAL +standard and should occur after backannotation. + +GHDL does not do negative constraint calculation. It fails to handle models +with negative constraint. I hope to be able to add this phase soon. diff --git a/doc/Introduction.rst b/doc/Introduction.rst new file mode 100644 index 000000000..135c8cb28 --- /dev/null +++ b/doc/Introduction.rst @@ -0,0 +1,73 @@ +************ +Introduction +************ + + +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. + +What is `VHDL`? +=============== + +`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. + +`VHDL` *is* a programming language: although `VHDL` was +not designed for writing general purpose programs, you can write any +algorithm with the `VHDL` language. If you are able to write +programs, you will find in `VHDL` features similar to those found +in procedural languages such as `C`, `Python`, or `Ada`. +`VHDL` derives most of its syntax and semantics from `Ada`. +Knowing `Ada` is an advantage for learning `VHDL` (it is an +advantage in general as well). + +However, `VHDL` was not designed as a general purpose language but as an +`HDL` (hardware description language). As the name implies, `VHDL` +aims at modeling or documenting electronics systems. Due to the nature +of hardware components which are always running, `VHDL` is a highly +concurrent language, built upon an event-based timing model. + +Like a program written in any other language, a `VHDL` program +can be executed. Since `VHDL` is used to model designs, the term +:dfn:`simulation` is often used instead of `execution`, with the +same meaning. + +Like a program written in another hardware description language, a +`VHDL` program can be transformed with a :dfn:`synthesis tool` +into a netlist, that is, a detailed gate-level implementation. + +What is `GHDL`? +=============== + +`GHDL` is a shorthand for G Hardware Design Language. Currently, +`G` has no meaning. + +`GHDL` is a `VHDL` compiler that can execute (nearly) any +`VHDL` program. `GHDL` is *not* a synthesis tool: you cannot +create a netlist with `GHDL`. + +Unlike some other simulators, `GHDL` is a compiler: it directly +translates a `VHDL` file to machine code, using the `GCC` or `LLVM` +back-end and without using an intermediary language such as `C` +or `C++`. Therefore, the compiled code should be faster and +the analysis time should be shorter than with a compiler using an +intermediary language. + +The Windows(TM) version of `GHDL` is not based on `GCC` but on +an internal code generator. + +The current version of `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 `VCD` file which can be +viewed with a wave viewer, as well as `ghw` files to be viewed by +`gtkwave`. + +`GHDL` aims at implementing `VHDL` as defined by IEEE 1076. +It supports most of the 1987 standard and most features added by the +1993 standard. diff --git a/doc/Invoking_GHDL.rst b/doc/Invoking_GHDL.rst new file mode 100644 index 000000000..c126c255f --- /dev/null +++ b/doc/Invoking_GHDL.rst @@ -0,0 +1,1114 @@ +************* +Invoking GHDL +************* + +The form of the :program:`ghdl` command is:: + + ghdl command [options...] + +The GHDL program has several commands. The first argument selects +the command. The options are used to slightly modify the action. + +No option is allowed before the command. Except for the run command, +no option is allowed after a filename or a unit name. + +Building commands +================= + +The mostly used commands of GHDL are those to analyze and elaborate a design. + +Analysis command +---------------- + +.. index:: analysis + +.. index:: *-a* command + +Analyze one or severals files:: + + ghdl -a [options...] file... + +The analysis command compiles one or more files, and creates an +object file for each source file. The analysis command is selected with +:option:`-a` switch. Any argument starting with a dash is an option, the +others are filenames. No options are allowed after a filename +argument. GHDL analyzes each filename in the given order, and stops the +analysis in case of error (the following files are not analyzed). + +See :ref:`GHDL_options`, for details on the GHDL options. For example, +to produce debugging information such as line numbers, use:: + + ghdl -a -g my_design.vhdl + + +.. _Elaboration_command: + +Elaboration command +------------------- + +.. index:: elaboration + +.. index:: *-e* command + +Elaborate a design:: + + ghdl -e [options..] primary_unit [secondary_unit] + + +On GNU/Linux the elaboration command creates an executable +containing the code of the `VHDL` sources, the elaboration code +and simulation code to execute a design hierarchy. On Windows this +command elaborates the design but does not generate anything. + +The elaboration command is selected with :option:`-e` switch, and must be +followed by either: + +* a name of a configuration unit +* a name of an entity unit +* a name of an entity unit followed by a name of an architecture unit + +Name of the units must be a simple name, without any dot. You can +select the name of the `WORK` library with the :option:`--work=NAME` +option, as described in :ref:`GHDL_options`. + +See :ref:`Top_entity`, for the restrictions on the root design of a +hierarchy. + +On GNU/Linux the filename of the executable is the name of the +primary unit, or for the later case, the concatenation of the name of +the primary unit, a dash, and the name of the secondary unit (or +architecture). On Windows there is no executable generated. + +The :option:`-o` followed by a filename can override the default +executable filename. + +For the elaboration command, `GHDL` re-analyzes all the +configurations, entities, architectures and package declarations, and +creates the default configurations and the default binding indications +according to the LRM rules. It also generates the list of objects files +required for the executable. Then, it links all these files with the +runtime library. + +The actual elaboration is performed at runtime. + +On Windows this command can be skipped because it is also done by the +run command. + +.. _Run_command: + +Run command +----------- + +.. index:: run + +.. index:: *-r* command + +Run (or simulate) a design:: + + ghdl -r [options...] primary_unit [secondary_unit] [simulation_options...] + + +The options and arguments are the same as for the elaboration command, :ref:`Elaboration_command`. + +On GNU/Linux this command simply determines the filename of the executable +and executes it. Options are ignored. You may also directly execute +the program. + +This command exists for three reasons: + +* You don't have to create the executable program name. +* It is coherent with the :option:`-a` and :option:`-e` commands. +* It works with the Windows implementation, where the code is generated in + memory. + +On Windows this command elaborates and launches the simulation. As a consequence +you must use the same options used during analysis. + +See :ref:`Simulation_and_runtime`, for details on options. + +Elaborate and run command +------------------------- + +.. index:: elaborate and run + +.. index:: *--elab-run* command + +Elaborate and then simulate a design unit:: + + ghdl --elab-run [elab_options...] primary_unit [secondary_unit] [run_options...] + + +This command acts like the elaboration command (see :ref:`Elaboration_command`) +followed by the run command (see :ref:`Run_command`). + +.. _Bind_command: + +Bind command +------------ + +.. index:: binding + +.. index:: *--bind* command + +Bind a design unit and prepare the link step:: + + ghdl --bind [options] primary_unit [secondary_unit] + + +This command is only available on GNU/Linux. + +This performs only the first stage of the elaboration command; the list +of objects files is created but the executable is not built. This +command should be used only when the main entry point is not ghdl. + +.. _Link_command: + +Link command +------------ + +.. index:: linking + +.. index:: *--link* command + +Link an already bound design unit:: + + ghdl --link [options] primary_unit [secondary_unit] + +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. + +.. _List_link_command: + +List link command +----------------- + +.. index:: *--list-link* command + +Display files which will be linked:: + + ghdl --list-link primary_unit [secondary_unit] + +This command is only available on GNU/Linux. + +This command may be used only after a bind command. GHDL displays all +the files which will be linked to create an executable. This command is +intended to add object files in a link of a foreign program. + +.. _Check_syntax_command: + +Check syntax command +-------------------- + +.. index:: checking syntax + +.. index:: *-s* command + +Analyze files but do not generate code:: + + ghdl -s [options] files + +This command may be used to check the syntax of files. It does not update +the library. + +.. _Analyze_and_elaborate_command: + +Analyze and elaborate command +----------------------------- + +.. index:: Analyze and elaborate command + +.. index:: *-c* command + +Analyze files and elaborate them at the same time. + +On GNU/Linux:: + + ghdl -c [options] file... -e primary_unit [secondary_unit] + + +On Windows:: + + ghdl -c [options] file... -r primary_unit [secondary_unit] + + +This command combines analysis and elaboration: files are analyzed and +the unit is then elaborated. However, code is only generated during the +elaboration. On Windows the simulation is launched. + +To be more precise, the files are first parsed, and then the elaboration +drives the analysis. Therefore, there is no analysis order, and you don't +need to care about it. + +All the units of the files are put into the `work` library. But, the +work library is neither read from disk nor saved. Therefore, you must give +all the files of the `work` library your design needs. + +The advantages over the traditional approach (analyze and then elaborate) are: + +* The compilation cycle is achieved in one command. +* Since the files are only parsed once, the compilation cycle may be faster. +* You don't need to know an analysis order +* This command produces smaller executable, since unused units and subprograms + do not generate code. + +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 traditional way. + +.. _GHDL_Options: + +GHDL options +============ + +.. index:: IEEE 1164 + +.. index:: 1164 + +.. index:: IEEE 1076.3 + +.. index:: 1076.3 + +Besides the options described below, `GHDL` passes any debugging options +(those that begin with :option:`-g`) and optimizations options (those that +begin with :option:`-O` or :option:`-f`) to `GCC`. Refer to the `GCC` +manual for details. + + + +.. option::--work=<NAME> + + .. index:: 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 :samp:`work`. + + `GHDL` checks whether :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). + + `VHDL` rules forbid you to add units to the :samp:`std` library. + Furthermore, you should not put units in the :samp:`ieee` library. + + +.. option:: --workdir=<DIR> + + Specify the directory where the :samp:`WORK` library is located. 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. + + Use option :option:`-P` to specify where libraries other than :samp:`WORK` + are placed. + + +.. option:: --std=<STD> + + Specify the standard to use. By default, the standard is :samp:`93c`, which + means VHDL-93 accepting VHDL-87 syntax. For details on :samp:`STD` values see + :ref:`VHDL_standards`. + + +.. option:: --ieee=<VER> + + .. index:: ieee library + .. index:: synopsys library + .. index:: mentor library + + Select the :samp:`IEEE` library to use. :samp:`VER` must be one of: + + none + Do not supply an `IEEE` library. Any library clause with the :samp:`IEEE` + identifier will fail, unless you have created by your own a library with + the `IEEE` name. + + standard + Supply an `IEEE` library containing only packages defined by + :samp:`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 :samp:`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. See :ref:`VITAL_packages`, + for more details. + + synopsys + Supply the former packages and the following additional packages: + :samp:`std_logic_arith`, :samp:`std_logic_signed`, + :samp:`std_logic_unsigned`, :samp:`std_logic_textio`. + + These packages were created by some companies, and are popular. However + they are not standard packages, and have been placed in the `IEEE` + library without the permission from the :samp:`ieee`. + + mentor + Supply the standard packages and the following additional package: + :samp:`std_logic_arith`. The package is a slight variation of a definitely + not standard but widely mis-used package. + + To avoid errors, you must use the same `IEEE` library for all units of + your design, and during elaboration. + + +.. option:: -P<DIRECTORY> + + Add `DIRECTORY` to the end of the list of directories to be searched for + library files. + + The `WORK` library is always searched in the path specified by the + :option:`--workdir=` option, or in the current directory if the latter + option is not specified. + + +.. option:: -fexplicit + + 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. See :ref:`IEEE_library_pitfalls`, for an example. + + This option is not set by default. I don't think this option is a + good feature, because it breaks the encapsulation rule. When set, an + operator can be silently overridden in another package. You'd better to fix + your design and use the :samp:`numeric_std` package. + + +.. option:: -frelaxed-rules + + Within an object declaration, allow to reference the name (which + references the hidden declaration). This ignores the error in the + following code: + + .. code-block:: VHDL + + package pkg1 is + type state is (state1, state2, state3); + end pkg1; + + use work.pkg1.all; + package pkg2 is + constant state1 : state := state1; + end pkg2; + + Some code (such as Xilinx packages) have such constructs, which + are valid. + + (The scope of the :samp:`state1` constant start at the `constant` + word. Because the constant :samp:`state1` and the enumeration literal + :samp:`state1` are homograph, the enumeration literal is hidden in the + immediate scope of the constant). + + +.. option:: -fpsl + + Enable parsing of PSL assertions within comments. See :ref:`PSL_implementation`, + for more details. + + +.. option:: --no-vital-checks +.. option:: --vital-checks + + Disable or enable checks of restriction on VITAL units. Checks are enabled + by default. + + Checks are performed only when a design unit is decorated by a VITAL attribute. + The VITAL attributes are :samp:`VITAL_Level0` and :samp:`VITAL_Level1`, both + declared in the :samp:`ieee.VITAL_Timing` package. + + Currently, VITAL checks are only partially implemented. See + :ref:`VHDL_restrictions_for_VITAL`, for more details. + + +.. option:: --syn-binding + + Use synthesizer rules for component binding. During elaboration, if a + component is not bound to an entity using VHDL LRM rules, try to find + in any known library an entity whose name is the same as the component + name. + + This rule is known as synthesizer rule. + + There are two key points: normal VHDL LRM rules are tried first and + entities are searched only in known library. A known library is a + library which has been named in your design. + + This option is only useful during elaboration. + + +.. option:: --PREFIX=<PATH> + + Use :file:`PATH` as the prefix path to find commands and pre-installed (std and + ieee) libraries. + + +.. option:: --GHDL1=<COMMAND> + + Use :samp:`COMMAND` as the command name for the compiler. If :samp:`COMMAND` is + not a path, then it is search in the list of program directories. + + +.. option:: -v + + Be verbose. For example, for analysis, elaboration and make commands, GHDL + displays the commands executed. + +Passing options to other programs +================================= + +These options are only available on GNU/Linux. + +For many commands, `GHDL` acts as a driver: it invokes programs to perform +the command. You can pass arbitrary options to these programs. + +Both the compiler and the linker are in fact GCC programs. See the +GCC manual for details on GCC options. + + + +.. option:: -Wc,<OPTION> + + Pass `OPTION` as an option to the compiler. + + +.. option:: -Wa,<OPTION> + + Pass `OPTION` as an option to the assembler. + + +.. option:: -Wl,<OPTION> + + Pass `OPTION` as an option to the linker. + +GHDL warnings +============= + +Some constructions are not erroneous but dubious. Warnings are diagnostic +messages that report such constructions. Some warnings are reported only +during analysis, others during elaboration. + +You could disable a warning by using the :samp:`--warn-no-XXX` +instead of :samp:`--warn-XXX`. + + +.. option:: --warn-reserved + + Emit a warning if an identifier is a reserved word in a later VHDL standard. + + +.. option:: --warn-default-binding + + During analyze, warns if a component instantiation has neither + configuration specification nor default binding. This may be useful if you + want to detect during analyze possibly unbound component if you don't use + configuration. :ref:`VHDL_standards`, for more details about default binding + rules. + + +.. option:: --warn-binding + + During elaboration, warns if a component instantiation is not bound + (and not explicitly left unbound). Also warns if a port of an entity + is not bound in a configuration specification or in a component + configuration. This warning is enabled by default, since default + binding rules are somewhat complex and an unbound component is most + often unexpected. + + However, warnings are even emitted if a component instantiation is + inside a generate statement. As a consequence, if you use the conditional + generate statement to select a component according to the implementation, + you will certainly get warnings. + + +.. option:: --warn-library + + Warns if a design unit replaces another design unit with the same name. + + +.. option:: --warn-vital-generic + + Warns if a generic name of a vital entity is not a vital generic name. This + is set by default. + + +.. option:: --warn-delayed-checks + + Warns for checks that cannot be done during analysis time and are + postponed to elaboration time. This is because not all procedure + bodies are available during analysis (either because a package body + has not yet been analysed or because `GHDL` doesn't read not required + package bodies). + + These are checks for no wait statement in a procedure called in a + sensitized process and checks for pure rules of a function. + + +.. option:: --warn-body + + Emit a warning if a package body which is not required is analyzed. If a + package does not declare a subprogram or a deferred constant, the package + does not require a body. + + +.. option:: --warn-specs + + Emit a warning if an all or others specification does not apply. + + +.. option:: --warn-unused + + Emit a warning when a subprogram is never used. + + +.. option:: --warn-error + + When this option is set, warnings are considered as errors. + + +Rebuilding commands +=================== + +Analyzing and elaborating a design consisting in several files can be tricky, +due to dependencies. GHDL has a few commands to rebuild a design. + +Import command +-------------- + +.. index:: importing files + +.. index:: *-i* command + +Add files in the work design library:: + + ghdl -i [options] file... + + +All the files specified in the command line are scanned, parsed and added in +the libraries but as not yet analyzed. No object files are created. + +The purpose of this command is to localize design units in the design files. +The make command will then be able to recursively build a hierarchy from +an entity name or a configuration name. + +Since the files are parsed, there must be correct files. However, since they +are not analyzed, many errors are tolerated by this command. + +Note that all the files are added to the work library. If you have many +libraries, you must use the command for each library. + +See :ref:`Make_command`, to actually build the design. + +.. _Make_command: + +Make command +------------ + +.. index:: make + +.. index:: *-m* command + + +Analyze automatically outdated files and elaborate a design:: + + ghdl -m [options] primary [secondary] + + +The primary unit denoted by the :samp:`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 hierarchy +with new compilation flags (for example, to add the *-g* +debugging option). + +The make command will only re-analyze design units in the work library. +GHDL fails if it has to analyze an outdated unit from another library. + +The purpose of this command is to be able to compile a design without prior +knowledge of file order. In the VHDL model, some units must be analyzed +before others (e.g. an entity before its architecture). It might be a +nightmare to analyze a full design of several files, if you don't have +the ordered list of file. This command computes an analysis order. + +The make command fails when a unit was not previously parsed. For +example, if you split a file containing several design units into +several files, you must either import these new files or analyze them so +that GHDL knows in which file these units are. + +The make command imports files which have been modified. Then, a design +hierarchy is internally built as if no units are outdated. Then, all outdated +design units, using the dependencies of the design hierarchy, are analyzed. +If necessary, the design hierarchy is elaborated. + +This is not perfect, since the default architecture (the most recently +analyzed one) may change while outdated design files are analyzed. In +such a case, re-run the make command of GHDL. + +Generate Makefile command +------------------------- + +.. index:: *--gen-makefile* command + +Generate a Makefile to build a design unit:: + + ghdl --gen-makefile [options] primary [secondary] + + +This command works like the make command (see :ref:`Make_command`), but only a +makefile is generated on the standard output. + +Library commands +================ + +GHDL has a few commands which act on a library. + +Directory command +----------------- + +.. index:: displaying library + +.. index:: *-d* command + +Display the name of the units contained in a design library:: + + ghdl -d [options] + + +The directory command, selected with the `-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`. + +Clean command +------------- + +.. index:: cleaning + +.. index:: *--clean* command + +Remove object and executable files but keep the library:: + + ghdl --clean [options] + + +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. + +.. _Remove_command: + +Remove command +-------------- + +.. index:: cleaning all + +.. index:: *--remove* command + +Do like the clean command but remove the library too:: + + ghdl --remove [options] + + +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. + +.. _Copy_command: + +Copy command +------------ + +.. index:: copying library + +.. index:: *--copy* command + +Make a local copy of an existing library:: + + ghdl --copy --work=name [options] + + +Make a local copy of an existing library. This is very useful if you want to +add unit to the :samp:`ieee` library: + +.. code-block:: shell + + ghdl --copy --work=ieee --ieee=synopsys + ghdl -a --work=ieee numeric_unsigned.vhd + + +.. _Create_a_Library: + +Create a Library +---------------- + +.. index:: create your own library + +A new library is created by compiling entities (packages etc.) into it:: + + ghdl -a --work=my_custom_lib my_file.vhd + + +A library's source code is usually stored and compiled into its own directory, +that you specify with the :option:`--workdir` option:: + + ghdl -a --work=my_custom_lib --workdir=my_custom_libdir my_custom_lib_srcdir/my_file.vhd + + +See also the :option:`-PPATH` command line option. + +.. _Cross-reference_command: + +Cross-reference command +======================= + +To easily navigate through your sources, you may generate cross-references:: + + ghdl --xref-html [options] file... + + +This command generates an html file for each :samp:`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 :samp:`file` are analyzed, and then, if the analysis is +successful, html files are generated in the directory specified by the +:option:`-o dir` option, or :file:`html/` directory by default. + +If the option :option:`--format=html2` is specified, then the generated html +files follow the HTML 2.0 standard, and colours are specified with +`<FONT>` tags. However, colours are hard-coded. + +If the option :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 information. + +File commands +============= + +The following commands act on one or several files. They do not analyze +files, therefore, they work even if a file has semantic errors. + +Pretty print command +-------------------- + +.. index:: *--pp-html* command + +.. index:: pretty printing + +.. index:: vhdl to html + +Generate HTML on standard output from VHDL:: + + ghdl --pp-html [options] file... + + +The files are just scanned and an html file, with syntax highlighting is +generated on standard output. + +Since the files are not even parsed, erroneous files or incomplete designs +can be pretty printed. + +The style of the html file can be modified with the :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 through `<FONT>` 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 :file:`ghdl.css`. +See :ref:`Cross-reference_command`, for more details about this CSS file. + +Find command +------------ + +.. index:: *-f* command + +Display the name of the design units in files:: + + ghdl -f file... + + +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. + +Chop command +------------ + +.. index:: *--chop* command + +Chop (or split) files at design unit:: + + ghdl --chop files + + +`GHDL` reads files, and writes a file in the current directory for +every design unit. + +The filename of a design unit is build according to the unit. For an +entity declaration, a package declaration or a configuration the file +name is :file:`NAME.vhdl`, where `NAME` is the name of the design +unit. For a package body, the filename is :file:`NAME-body.vhdl`. +Finally, for an architecture `ARCH` of an entity `ENTITY`, the +filename 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. + +Lines command +------------- + +.. index:: *--lines* command + +Display on the standard output lines of files preceded by line number:: + + ghdl --lines files + + +Misc commands +============= + +There are a few GHDL commands which are seldom useful. + +.. _Help_command: + +Help command +------------ + +.. index:: *-h* command + +.. index:: *--help* command + +Display (on the standard output) a short description of the all the commands +available. If the help switch is followed by a command switch, then options +for this later command are displayed:: + + ghdl --help + ghdl -h + ghdl -h command + + +.. _Disp_config_command: + +Disp config command +------------------- + +.. index:: *--disp-config* command + +.. index:: display configuration + +Display the program paths and options used by GHDL:: + + ghdl --disp-config [options] + + +This may be useful to track installation errors. + +Disp standard command +--------------------- + +.. index:: *--disp-standard* command + +.. index:: display :samp:`std.standard` + +Display the :samp:`std.standard` package:: + + ghdl --disp-standard [options] + + +Version command +--------------- + +.. index:: *--version* command + +.. index:: version + +Display the `GHDL` version and exit:: + + ghdl --version + + +Installation Directory +====================== + +During analysis and elaboration `GHDL` may read the `std` +and `ieee` files. The location of these files is based on the prefix, +which is (in priority order): + +* the :option:`--PREFIX=` command line option + +* the :envvar:`GHDL_PREFIX` environment variable + +* + a built-in default path. It is a hard-coded path on GNU/Linux and the + value of the :samp:`HKLM\Software\Ghdl\Install_Dir` registry entry on Windows. + +You should use the :option:`--disp-config` command (:ref:`Disp_config_command` for details) to disp and debug installation problems. + +.. _ieee_library_pitfalls: + +IEEE library pitfalls +===================== + +When you use options :option:`--ieee=synopsys` or :option:`--ieee=mentor`, +the `IEEE` library contains non standard packages such as +:samp:`std_logic_arith`. + +These packages are not standard because there are not described by an IEEE +standard, even if they have been put in the `IEEE` library. Furthermore, +they are not really de-facto standard, because there are slight differences +between the packages of Mentor and those of Synopsys. + +Furthermore, since they are not well-thought, their use has pitfalls. For +example, this description has error during compilation: + +.. code-block:: VHDL + + library ieee; + use ieee.std_logic_1164.all; + + -- A counter from 0 to 10. + entity counter is + port (val : out std_logic_vector (3 downto 0); + ck : std_logic; + rst : std_logic); + end counter; + + library ieee; + use ieee.std_logic_unsigned.all; + + architecture bad of counter + is + signal v : std_logic_vector (3 downto 0); + begin + process (ck, rst) + begin + if rst = '1' then + v <= x"0"; + elsif rising_edge (ck) then + if v = "1010" then -- Error + v <= x"0"; + else + v <= v + 1; + end if; + end if; + end process; + + val <= v; + end bad; + + +When you analyze this design, GHDL does not accept it (too long lines +have been split for readability): + +.. code-block:: shell + + 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 + +Indeed, the `"="` 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 `std_logic_vector` type is +declared and is an element to element comparison, the second one is an +explicit declared function, with the semantic of an unsigned comparison. + +With some analyser, the explicit declaration has priority over the implicit +declaration, and this design can be analyzed without error. However, this +is not the rule given by the VHDL LRM, and since GHDL follows these rules, +it emits an error. + +You can force GHDL to use this rule with the *-fexplicit* option. +:ref:`GHDL_options`, for more details. + +However it is easy to fix this error, by using a selected name: + +.. code-block:: VHDL + + 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; + + +It is better to only use the standard packages defined by IEEE, which +provides the same functionalities: + +.. code-block:: VHDL + + 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; + + +IEEE math packages +================== + +.. index:: Math_Real + +.. index:: Math_Complex + +The :samp:`ieee` math packages (:samp:`math_real` and +:samp:`math_complex`) provided with `GHDL` are fully compliant with +the `IEEE` standard. diff --git a/doc/Simulation_and_runtime.rst b/doc/Simulation_and_runtime.rst new file mode 100644 index 000000000..329dca8d8 --- /dev/null +++ b/doc/Simulation_and_runtime.rst @@ -0,0 +1,239 @@ +.. _simulation_and_runtime: + +********************** +Simulation and runtime +********************** + +.. _simulation_options: + +Simulation options +================== + +In most system environments, it is possible to pass options while +invoking a program. Contrary to most programming languages, there is no +standard method in VHDL to obtain the arguments or to set the exit +status. + +In GHDL, it is impossible to pass parameters to your design. A later version +could do it through the generics interfaces of the top entity. + +However, the GHDL runtime behaviour can be modified with some options; for +example, it is possible to stop simulation after a certain time. + +The exit status of the simulation is :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 :option:`--help` options lists +all options available, including the debugging one. + + + +.. option:: --assert-level=<LEVEL> + + Select the assertion level at which an assertion violation stops the + simulation. `LEVEL` is the name from the `severity_level` + enumerated type defined in the `standard` package or the + :samp:`none` name. + + By default, only assertion violation of severity level :samp:`failure` + stops the simulation. + + For example, if `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. + + Option :option:`--assert-level=none` prevents any assertion violation to stop + simulation. + +.. option:: --ieee-asserts=<POLICY> + + Select how the assertions from :samp:`ieee` units are + handled. `POLICY` can be :samp:`enable` (the default), + :samp:`disable` which disables all assertion from :samp:`ieee` packages + and :samp:`disable-at-0` which disables only at start of simulation. + + This option can be useful to avoid assertion message from + :samp:`ieee.numeric_std` (and other :samp:`ieee` packages). + + +.. option:: --stop-time=<TIME> + + Stop the simulation after :samp:`TIME`. :samp:`TIME` is expressed as a time + value, *without* any space. The time is the simulation time, not + the real clock time. + + For example:: + + $ ./my_design --stop-time=10ns + $ ./my_design --stop-time=ps + + +.. option:: --stop-delta=<N> + + Stop the simulation after `N` delta cycles in the same current time. + + .. index:: display time + +.. option:: --disp-time + + Display the time and delta cycle number as simulation advances. + + +.. option:: --disp-tree[=<KIND>] + + .. index:: 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. `KIND` is optional, but if set must be one of: + + + * none + Do not display hierarchy. Same as if the option was not present. + + * inst + Display entities, architectures, instances, blocks and generates statements. + + * proc + Like :samp:`inst` but also display processes. + + * port + Like :samp:`proc` but display ports and signals too. + If `KIND` is not specified, the hierarchy is displayed with the + :samp:`port` mode. + + +.. option:: --no-run + + Do not simulate, only elaborate. This may be used with + :option:`--disp-tree` to display the tree without simulating the whole + design. + + +.. option:: --vcd=<FILENAME> + +.. option:: --vcdgz=<FILENAME> + + .. index:: vcd + + .. index:: value change dump + + .. index:: dump of signals + + Option :option:`--vcd` dumps into the VCD file `FILENAME` the signal + values before each non-delta cycle. If `FILENAME` is :samp:`-`, + then the standard output is used, otherwise a file is created or + overwritten. + + The :option:`--vcdgz` option is the same as the *--vcd* option, + but the output is compressed using the `zlib` (`gzip` + compression). However, you can't use the :samp:`-` filename. + Furthermore, only one VCD file can be written. + + :dfn:`VCD` (value change dump) is a file format defined + by the `verilog` standard and used by virtually any wave viewer. + + Since it comes from `verilog`, only a few VHDL types can be dumped. GHDL + dumps only signals whose base type is of the following: + + + * types defined in the :samp:`std.standard` package: + + * :samp:`bit` + + * :samp:`bit_vector` + + * types defined in the :samp:`ieee.std_logic_1164` package: + + * :samp:`std_ulogic` + + * :samp:`std_logic` (because it is a subtype of :samp:`std_ulogic`) + + * :samp:`std_ulogic_vector` + + * :samp:`std_logic_vector` + + * any integer type + + I have successfully used `gtkwave` to view VCD files. + + Currently, there is no way to select signals to be dumped: all signals are + dumped, which can generate big files. + + It is very unfortunate there is no standard or well-known wave file + format supporting VHDL types. If you are aware of such a free format, + please mail me (:ref:`Reporting_bugs`). + + +.. option:: --fst=<FILENAME> + + Write the waveforms into a `fst`, that can be displayed by + `gtkwave`. The `fst` files are much smaller than VCD or + `GHW` files, but it handles only the same signals as the VCD format. + + +.. option:: --wave=<FILENAME> + + Write the waveforms into a `ghw` (GHdl Waveform) file. Currently, all + the signals are dumped into the waveform file, you cannot select a hierarchy + of signals to be dumped. + + The format of this file was defined by myself and is not yet completely fixed. + It may change slightly. The :samp:`gtkwave` tool can read the GHW files. + + Contrary to VCD files, any VHDL type can be dumped into a GHW file. + + +.. option:: --sdf=<PATH>=<FILENAME> + + Do VITAL annotation on `PATH` with SDF file :file:`FILENAME`. + + `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. + + Specifying a delay:: + + --sdf=min=<PATH>=<FILENAME> + --sdf=typ=<PATH>=<FILENAME> + --sdf=max=<PATH>=<FILENAME> + + If the option contains a type of delay, that is :samp:`min=`, + :samp:`typ=` or :samp:`max=`, the annotator use respectively minimum, + typical or maximum values. If the option does not contain a type of delay, + the annotator use the typical delay. + + See :ref:`Backannotation`, for more details. + + +.. option:: --help + + Display a short description of the options accepted by the runtime library. + +Debugging VHDL programs +======================= + +.. index:: debugging + +.. index:: `__ghdl_fatal` + +Debugging VHDL programs using `GDB` is possible only on GNU/Linux systems. + +`GDB` is a general purpose debugger for programs compiled by `GCC`. +Currently, there is no VHDL support for `GDB`. It may be difficult +to inspect variables or signals in `GDB`, however, `GDB` is +still able to display the stack frame in case of error or to set a breakpoint +at a specified line. + +`GDB` can be useful to precisely catch a runtime error, such as indexing +an array beyond its bounds. All error check subprograms call the +`__ghdl_fatal` procedure. Therefore, to catch runtime error, set +a breakpoint like this: + + (gdb) break __ghdl_fatal + +When the breakpoint is hit, use the `where` or `bt` command to +display the stack frames. diff --git a/doc/Starting_with_GHDL.rst b/doc/Starting_with_GHDL.rst new file mode 100644 index 000000000..92818c781 --- /dev/null +++ b/doc/Starting_with_GHDL.rst @@ -0,0 +1,355 @@ +****************** +Starting with GHDL +****************** + +In this chapter, you will learn how to use the GHDL compiler by +working on two examples. + +The hello world program +======================= + +To illustrate the large purpose of VHDL, here is a commented VHDL +"Hello world" program. + +.. code-block:: VHDL + + -- Hello world program. + use std.textio.all; -- Imports the standard textio package. + + -- Defines a design entity, without any ports. + entity hello_world is + end hello_world; + + architecture behaviour of hello_world is + begin + process + variable l : line; + begin + write (l, String'("Hello world!")); + writeline (output, l); + wait; + end process; + end behaviour; + +Suppose this program is contained in the file :file:`hello.vhdl`. +First, you have to compile the file; this is called `analysis` of a design +file in VHDL terms. + +.. code-block:: shell + + $ ghdl -a hello.vhdl + +This command creates or updates a file :file:`work-obj93.cf`, which +describes the library `work`. On GNU/Linux, this command generates a +file :file:`hello.o`, which is the object file corresponding to your +VHDL program. The object file is not created on Windows. + +Then, you have to build an executable file. + +.. code-block:: shell + + $ ghdl -e hello_world + +The :option:`-e` option means :dfn:`elaborate`. With this option, `GHDL` +creates code in order to elaborate a design, with the :samp:`hello` +entity at the top of the hierarchy. + +On GNU/Linux, the result is an executable program called :file:`hello` +which can be run: + +.. code-block:: shell + + $ ghdl -r hello_world + +or directly: + +.. code-block:: shell + + $ ./hello_world + + +On Windows, no file is created. The simulation is launched using this command: + +.. code-block:: shell + + > ghdl -r hello_world + + +The result of the simulation appears on the screen:: + + Hello world! + + +A full adder +============ + +VHDL is generally used for hardware design. This example starts with +a full adder described in the :file:`adder.vhdl` file: + +.. code-block:: VHDL + + entity adder is + -- `i0`, `i1` and the carry-in `ci` are inputs of the adder. + -- `s` is the sum output, `co` is the carry-out. + port (i0, i1 : in bit; ci : in bit; s : out bit; co : out bit); + end adder; + + architecture rtl of adder is + begin + -- This full-adder architecture contains two concurrent assignment. + -- Compute the sum. + s <= i0 xor i1 xor ci; + -- Compute the carry. + co <= (i0 and i1) or (i0 and ci) or (i1 and ci); + end rtl; + + +You can analyze this design file: + +.. code-block:: shell + + $ ghdl -a adder.vhdl + + +You can try to execute the `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: + +.. code-block:: VHDL + + -- A testbench has no ports. + entity adder_tb is + end adder_tb; + + architecture behav of adder_tb is + -- Declaration of the component that will be instantiated. + component adder + port (i0, i1 : in bit; ci : in bit; s : out bit; co : out bit); + end component; + + -- Specifies which entity is bound with the component. + for adder_0: adder use entity work.adder; + signal i0, i1, ci, s, co : bit; + begin + -- Component instantiation. + adder_0: adder port map (i0 => i0, i1 => i1, ci => ci, + s => s, co => co); + + -- This process does the real job. + process + type pattern_type is record + -- The inputs of the adder. + i0, i1, ci : bit; + -- The expected outputs of the adder. + s, co : bit; + end record; + -- The patterns to apply. + type pattern_array is array (natural range <>) of pattern_type; + constant patterns : pattern_array := + (('0', '0', '0', '0', '0'), + ('0', '0', '1', '1', '0'), + ('0', '1', '0', '1', '0'), + ('0', '1', '1', '0', '1'), + ('1', '0', '0', '1', '0'), + ('1', '0', '1', '0', '1'), + ('1', '1', '0', '0', '1'), + ('1', '1', '1', '1', '1')); + begin + -- Check each pattern. + for i in patterns'range loop + -- Set the inputs. + i0 <= patterns(i).i0; + i1 <= patterns(i).i1; + ci <= patterns(i).ci; + -- Wait for the results. + wait for 1 ns; + -- Check the outputs. + assert s = patterns(i).s + report "bad sum value" severity error; + assert co = patterns(i).co + report "bad carray out value" severity error; + end loop; + assert false report "end of test" severity note; + -- Wait forever; this will finish the simulation. + wait; + end process; + end behav; + + +As usual, you should analyze the design: + +.. code-block:: shell + + $ ghdl -a adder_tb.vhdl + +And build an executable for the testbench: + +.. code-block:: shell + + $ ghdl -e adder_tb + +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: + +.. code-block:: shell + + $ ghdl -r adder_tb + adder_tb.vhdl:52:7:(assertion note): end of test + + +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: + +.. code-block:: shell + + $ ghdl -r adder_tb --vcd=adder.vcd + +Then, you may now view the waves: + +.. code-block:: shell + + $ gtkwave adder.vcd + +See :ref:`Simulation_options`, for more details on the :option:`--vcd` option and +other runtime options. + + +Starting with a design +====================== + +Unless you are only studying VHDL, you will work with bigger designs than +the ones of the previous examples. + +Let's see how to analyze and run a bigger design, such as the DLX model +suite written by Peter Ashenden which is distributed under the terms of the +GNU General Public License. A copy is kept on +http://ghdl.free.fr/dlx.tar.gz + +First, untar the sources: + +.. code-block:: shell + + $ tar zxvf dlx.tar.gz + + +In order not to pollute the sources with the library, it is a good idea +to create a :file:`work/` subdirectory for the `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. + +.. code-block:: shell + + $ cd dlx + $ mkdir work + + +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: + +.. code-block:: shell + + $ ghdl -i --workdir=work *.vhdl + + +and making a design: + +.. code-block:: shell + + $ ghdl -m --workdir=work dlx_test_behaviour + + +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: + +.. code-block:: shell + + $ cp test_loop.out dlx.out + + +And you can run the test suite: + +.. code-block:: shell + + $ ghdl -r dlx_test_behaviour + + +The test bench monitors the bus and displays each instruction executed. +It finishes with an assertion of severity level note: + +.. code-block:: shell + + dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction + encountered, execution halted + + +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: + +.. code-block:: shell + + $ ghdl -r dlx_test_behaviour --assert-level=note + + +With this option, the program stops just after the previous message:: + + dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction + encountered, execution halted + error: assertion failed + + +If you want to make room on your hard drive, you can either: + +* clean the design library with the GHDL command: + + .. code-block:: shell + + $ ghdl --clean --workdir=work + + This removes the executable and all the object files. If you want to + rebuild the design at this point, just do the make command as shown + above. + +* remove the design library with the GHDL command: + + .. code-block:: shell + + $ ghdl --remove --workdir=work + + This removes the executable, all the object files and the library file. + If you want to rebuild the design, you have to import the sources again, + and to make the design. + +* remove the :file:`work/` directory: + + .. code-block:: shell + + $ rm -rf work + + Only the executable is kept. If you want to rebuild the design, create + the :file:`work/` directory, import the sources, and make the design. + +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:: + + --ieee=synopsys -fexplicit + +See :ref:`IEEE_library_pitfalls`, for more details. diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 000000000..0ae2ca7f7 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,284 @@ +# -*- coding: utf-8 -*- +# +# GHDL documentation build configuration file, created by +# sphinx-quickstart on Fri Nov 20 20:33:03 2015. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os +import shlex + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'GHDL' +copyright = u'2015, Tristan Gingold' +author = u'Tristan Gingold' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.33' +# The full version, including alpha/beta/rc tags. +release = '0.33' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' +#html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# Now only 'ja' uses this config value +#html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +#html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'GHDLdoc' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', + +# Latex figure (float) alignment +#'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'GHDL.tex', u'GHDL Documentation', + u'Tristan Gingold', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'ghdl', u'GHDL Documentation', + [author], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'GHDL', u'GHDL Documentation', + author, 'GHDL', 'VHDL simulator.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False diff --git a/doc/ghdl.html b/doc/ghdl.html deleted file mode 100644 index e5b203f0b..000000000 --- a/doc/ghdl.html +++ /dev/null @@ -1,3032 +0,0 @@ -<html lang="en"> -<head> -<title>GHDL guide</title> -<meta http-equiv="Content-Type" content="text/html"> -<meta name="description" content="GHDL guide"> -<meta name="generator" content="makeinfo 4.11"> -<link title="Top" rel="top" href="#Top"> -<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> -<meta http-equiv="Content-Style-Type" content="text/css"> -<style type="text/css"><!-- - pre.display { font-family:inherit } - pre.format { font-family:inherit } - pre.smalldisplay { font-family:inherit; font-size:smaller } - pre.smallformat { font-family:inherit; font-size:smaller } - pre.smallexample { font-size:smaller } - pre.smalllisp { font-size:smaller } - span.sc { font-variant:small-caps } - span.roman { font-family:serif; font-weight:normal; } - span.sansserif { font-family:sans-serif; font-weight:normal; } ---></style> -</head> -<body> -<h1 class="settitle">GHDL guide</h1> -<div class="contents"> -<h2>Table of Contents</h2> -<ul> -<li><a name="toc_Top" href="#Top">GHDL guide</a> -<li><a name="toc_Introduction" href="#Introduction">1 Introduction</a> -<ul> -<li><a href="#Introduction">1.1 Content of this manual</a> -<li><a href="#What-is-VHDL">1.2 What is <code>VHDL</code>?</a> -<li><a href="#What-is-GHDL">1.3 What is <code>GHDL</code>?</a> -</li></ul> -<li><a name="toc_Starting-with-GHDL" href="#Starting-with-GHDL">2 Starting with GHDL</a> -<ul> -<li><a href="#The-hello-word-program">2.1 The hello world program</a> -<li><a href="#A-full-adder">2.2 A full adder</a> -<li><a href="#Starting-with-a-design">2.3 Starting with a design</a> -</li></ul> -<li><a name="toc_Invoking-GHDL" href="#Invoking-GHDL">3 Invoking GHDL</a> -<ul> -<li><a href="#Building-commands">3.1 Building commands</a> -<ul> -<li><a href="#Analysis-command">3.1.1 Analysis command</a> -<li><a href="#Elaboration-command">3.1.2 Elaboration command</a> -<li><a href="#Run-command">3.1.3 Run command</a> -<li><a href="#Elaborate-and-run-command">3.1.4 Elaborate and run command</a> -<li><a href="#Bind-command">3.1.5 Bind command</a> -<li><a href="#Link-command">3.1.6 Link command</a> -<li><a href="#List-link-command">3.1.7 List link command</a> -<li><a href="#Check-syntax-command">3.1.8 Check syntax command</a> -<li><a href="#Analyze-and-elaborate-command">3.1.9 Analyze and elaborate command</a> -</li></ul> -<li><a href="#GHDL-options">3.2 GHDL options</a> -<li><a href="#Passing-options-to-other-programs">3.3 Passing options to other programs</a> -<li><a href="#GHDL-warnings">3.4 GHDL warnings</a> -<li><a href="#Rebuilding-commands">3.5 Rebuilding commands</a> -<ul> -<li><a href="#Import-command">3.5.1 Import command</a> -<li><a href="#Make-command">3.5.2 Make command</a> -<li><a href="#Generate-Makefile-command">3.5.3 Generate Makefile command</a> -</li></ul> -<li><a href="#Library-commands">3.6 Library commands</a> -<ul> -<li><a href="#Directory-command">3.6.1 Directory command</a> -<li><a href="#Clean-command">3.6.2 Clean command</a> -<li><a href="#Remove-command">3.6.3 Remove command</a> -<li><a href="#Copy-command">3.6.4 Copy command</a> -</li></ul> -<li><a href="#Cross_002dreference-command">3.7 Cross-reference command</a> -<li><a href="#File-commands">3.8 File commands</a> -<ul> -<li><a href="#Pretty-print-command">3.8.1 Pretty print command</a> -<li><a href="#Find-command">3.8.2 Find command</a> -<li><a href="#Chop-command">3.8.3 Chop command</a> -<li><a href="#Lines-command">3.8.4 Lines command</a> -</li></ul> -<li><a href="#Misc-commands">3.9 Misc commands</a> -<ul> -<li><a href="#Help-command">3.9.1 Help command</a> -<li><a href="#Dispconfig-command">3.9.2 Dispconfig command</a> -<li><a href="#Disp-standard-command">3.9.3 Disp standard command</a> -<li><a href="#Version-command">3.9.4 Version command</a> -</li></ul> -<li><a href="#Installation-Directory">3.10 Installation Directory</a> -<li><a href="#IEEE-library-pitfalls">3.11 IEEE library pitfalls</a> -<li><a href="#IEEE-math-packages">3.12 IEEE math packages</a> -</li></ul> -<li><a name="toc_Simulation-and-runtime" href="#Simulation-and-runtime">4 Simulation and runtime</a> -<ul> -<li><a href="#Simulation-options">4.1 Simulation options</a> -<li><a href="#Debugging-VHDL-programs">4.2 Debugging VHDL programs</a> -</li></ul> -<li><a name="toc_GHDL-implementation-of-VHDL" href="#GHDL-implementation-of-VHDL">5 GHDL implementation of VHDL</a> -<ul> -<li><a href="#VHDL-standards">5.1 VHDL standards</a> -<li><a href="#Source-representation">5.2 Source representation</a> -<li><a href="#Library-database">5.3 Library database</a> -<li><a href="#VHDL-files-format">5.4 VHDL files format</a> -<li><a href="#Top-entity">5.5 Top entity</a> -<li><a href="#Using-vendor-libraries">5.6 Using vendor libraries</a> -<li><a href="#Using-ieee_002emath_005freal-or-ieee_002emath_005fcomplex">5.7 Using ieee.math_real or ieee.math_complex</a> -<li><a href="#Interfacing-to-other-languages">5.8 Interfacing to other languages</a> -<ul> -<li><a href="#Interfacing-to-other-languages">5.8.1 Foreign declarations</a> -<li><a href="#Restrictions-on-foreign-declarations">5.8.2 Restrictions on foreign declarations</a> -<li><a href="#Linking-with-foreign-object-files">5.8.3 Linking with foreign object files</a> -<li><a href="#Starting-a-simulation-from-a-foreign-program">5.8.4 Starting a simulation from a foreign program</a> -<li><a href="#Linking-with-Ada">5.8.5 Linking with Ada</a> -<li><a href="#Using-GRT-from-Ada">5.8.6 Using GRT from Ada</a> -</li></ul> -</li></ul> -<li><a name="toc_GHDL-implementation-of-VITAL" href="#GHDL-implementation-of-VITAL">6 GHDL implementation of VITAL</a> -<ul> -<li><a href="#VITAL-packages">6.1 VITAL packages</a> -<li><a href="#VHDL-restrictions-for-VITAL">6.2 VHDL restrictions for VITAL</a> -<li><a href="#Backannotation">6.3 Backannotation</a> -<li><a href="#Negative-constraint-calculation">6.4 Negative constraint calculation</a> -</li></ul> -<li><a name="toc_Flaws-and-bugs-report" href="#Flaws-and-bugs-report">7 Flaws and bugs report</a> -<ul> -<li><a href="#Deficiencies">7.1 Deficiencies</a> -<li><a href="#Reporting-bugs">7.2 Reporting bugs</a> -<li><a href="#Future-improvements">7.3 Future improvements</a> -</li></ul> -<li><a name="toc_Copyrights" href="#Copyrights">8 Copyrights</a> -<li><a name="toc_Index" href="#Index">Index</a> -</li></ul> -</div> - - - -<div class="node"> -<p><hr> -<a name="Top"></a> -Next: <a rel="next" accesskey="n" href="#Introduction">Introduction</a>, -Previous: <a rel="previous" accesskey="p" href="#dir">(dir)</a>, -Up: <a rel="up" accesskey="u" href="#dir">(dir)</a> - -</div> - -<h2 class="unnumbered">GHDL guide</h2> - -<p>GHDL, a VHDL compiler. - - <p>Copyright © 2002, 2003, 2004, 2005, 2006, 2007 Tristan Gingold. - - <p>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. - -<ul class="menu"> -<li><a accesskey="1" href="#Introduction">Introduction</a>: What is GHDL, what is VHDL -<li><a accesskey="2" href="#Starting-with-GHDL">Starting with GHDL</a>: Build a VHDL program with GHDL -<li><a accesskey="3" href="#Invoking-GHDL">Invoking GHDL</a> -<li><a accesskey="4" href="#Simulation-and-runtime">Simulation and runtime</a> -<li><a accesskey="5" href="#GHDL-implementation-of-VHDL">GHDL implementation of VHDL</a> -<li><a accesskey="6" href="#GHDL-implementation-of-VITAL">GHDL implementation of VITAL</a> -<li><a accesskey="7" href="#Flaws-and-bugs-report">Flaws and bugs report</a> -<li><a accesskey="8" href="#Copyrights">Copyrights</a> -<li><a accesskey="9" href="#Index">Index</a> -</ul> - -<div class="node"> -<p><hr> -<a name="Introduction"></a> -Next: <a rel="next" accesskey="n" href="#Starting-with-GHDL">Starting with GHDL</a>, -Previous: <a rel="previous" accesskey="p" href="#Top">Top</a>, -Up: <a rel="up" accesskey="u" href="#Top">Top</a> - -</div> - -<!-- node-name, next, previous, up --> -<h2 class="chapter">1 Introduction</h2> - -<ul class="menu"> -<li><a accesskey="1" href="#What-is-VHDL">What is VHDL</a> -<li><a accesskey="2" href="#What-is-GHDL">What is GHDL</a> -</ul> - -<h3 class="section">1.1 Content of this manual</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. - -<!-- FIXME: references: URL, LRM reference. --> -<div class="node"> -<p><hr> -<a name="What-is-VHDL"></a> -Next: <a rel="next" accesskey="n" href="#What-is-GHDL">What is GHDL</a>, -Previous: <a rel="previous" accesskey="p" href="#Introduction">Introduction</a>, -Up: <a rel="up" accesskey="u" href="#Introduction">Introduction</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">1.2 What is <code>VHDL</code>?</h3> - -<p><dfn>VHDL</dfn> 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><code>VHDL</code> <em>is</em> a programming language: although <code>VHDL</code> was -not designed for writing general purpose programs, you can write any -algorithm with the <code>VHDL</code> language. If you are able to write -programs, you will find in <code>VHDL</code> features similar to those found -in procedural languages such as <code>C</code>, <code>Pascal</code> or <code>Ada</code>. -<code>VHDL</code> derives most of its syntax and semantics from <code>Ada</code>. -Knowing <code>Ada</code> is an advantage for learning <code>VHDL</code> (it is an -advantage in general as well). - - <p>However, <code>VHDL</code> was not designed as a general purpose language but as an -<code>HDL</code> (hardware description language). As the name implies, <code>VHDL</code> -aims at modeling or documenting electronics systems. Due to the nature -of hardware components which are always running, <code>VHDL</code> is a highly -concurrent language, built upon an event-based timing model. - - <p>Like a program written in any other language, a <code>VHDL</code> program -can be executed. Since <code>VHDL</code> is used to model designs, the term -<dfn>simulation</dfn> is often used instead of <dfn>execution</dfn>, with the -same meaning. - - <p>Like a program written in another hardware description language, a -<code>VHDL</code> program can be transformed with a <code>synthesis tool</code> -into a netlist, that is, a detailed gate-level implementation. - -<div class="node"> -<p><hr> -<a name="What-is-GHDL"></a> -Previous: <a rel="previous" accesskey="p" href="#What-is-VHDL">What is VHDL</a>, -Up: <a rel="up" accesskey="u" href="#Introduction">Introduction</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">1.3 What is <code>GHDL</code>?</h3> - -<p><dfn>GHDL</dfn> is a shorthand for G Hardware Design Language. Currently, -<code>G</code> has no meaning. - - <p><dfn>GHDL</dfn> is a <code>VHDL</code> compiler that can execute (nearly) any -<code>VHDL</code> program. <code>GHDL</code> is <em>not</em> a synthesis tool: you cannot -create a netlist with <code>GHDL</code>. - - <p>Unlike some other simulators, <code>GHDL</code> is a compiler: it directly -translates a <code>VHDL</code> file to machine code, using the <code>GCC</code> -back-end and without using an intermediary language such as <code>C</code> -or <code>C++</code>. Therefore, the compiled code should be faster and -the analysis time should be shorter than with a compiler using an -intermediary language. - - <p>The Windows(TM) version of <code>GHDL</code> is not based on <code>GCC</code> but on -an internal code generator. - - <p>The current version of <code>GHDL</code> 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</code> file which can be -viewed with a wave viewer, as well as <code>ghw</code> files to be viewed by -‘<samp><span class="samp">gtkwave</span></samp>’. - - <p><code>GHDL</code> aims at implementing <code>VHDL</code> as defined by IEEE 1076. -It supports most of the 1987 standard and most features added by the -1993 standard. - -<div class="node"> -<p><hr> -<a name="Starting-with-GHDL"></a> -Next: <a rel="next" accesskey="n" href="#Invoking-GHDL">Invoking GHDL</a>, -Previous: <a rel="previous" accesskey="p" href="#Introduction">Introduction</a>, -Up: <a rel="up" accesskey="u" href="#Top">Top</a> - -</div> - -<!-- node-name, next, previous, up --> -<h2 class="chapter">2 Starting with GHDL</h2> - -<p>In this chapter, you will learn how to use the GHDL compiler by -working on two examples. - -<ul class="menu"> -<li><a accesskey="1" href="#The-hello-word-program">The hello word program</a> -<li><a accesskey="2" href="#A-full-adder">A full adder</a> -<li><a accesskey="3" href="#Starting-with-a-design">Starting with a design</a> -</ul> - -<div class="node"> -<p><hr> -<a name="The-hello-word-program"></a> -Next: <a rel="next" accesskey="n" href="#A-full-adder">A full adder</a>, -Previous: <a rel="previous" accesskey="p" href="#Starting-with-GHDL">Starting with GHDL</a>, -Up: <a rel="up" accesskey="u" href="#Starting-with-GHDL">Starting with GHDL</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">2.1 The hello world program</h3> - -<p>To illustrate the large purpose of VHDL, here is a commented VHDL -"Hello world" program. - -<pre class="example"> -- <span class="roman">Hello world program.</span> - use std.textio.all; -- <span class="roman">Imports the standard textio package.</span> - - -- <span class="roman">Defines a design entity, without any ports.</span> - 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; -</pre> - <p>Suppose this program is contained in the file <samp><span class="file">hello.vhdl</span></samp>. -First, you have to compile the file; this is called <dfn>analysis</dfn> of a design -file in VHDL terms. -<pre class="smallexample"> $ ghdl -a hello.vhdl -</pre> - <p>This command creates or updates a file <samp><span class="file">work-obj93.cf</span></samp>, which -describes the library ‘<samp><span class="samp">work</span></samp>’. On GNU/Linux, this command generates a -file <samp><span class="file">hello.o</span></samp>, which is the object file corresponding to your -VHDL program. The object file is not created on Windows. - - <p>Then, you have to build an executable file. -<pre class="smallexample"> $ ghdl -e hello_world -</pre> - <p>The ‘<samp><span class="samp">-e</span></samp>’ option means <dfn>elaborate</dfn>. With this option, <code>GHDL</code> -creates code in order to elaborate a design, with the ‘<samp><span class="samp">hello</span></samp>’ -entity at the top of the hierarchy. - - <p>On GNU/Linux, the result is an executable program called <samp><span class="file">hello</span></samp> -which can be run: -<pre class="smallexample"> $ ghdl -r hello_world -</pre> - <p>or directly: -<pre class="smallexample"> $ ./hello_world -</pre> - <p>On Windows, no file is created. The simulation is launched using this command: -<pre class="smallexample"> > ghdl -r hello_world -</pre> - <p>The result of the simulation appears on the screen: -<pre class="smallexample"> Hello world! -</pre> - <div class="node"> -<p><hr> -<a name="A-full-adder"></a> -Next: <a rel="next" accesskey="n" href="#Starting-with-a-design">Starting with a design</a>, -Previous: <a rel="previous" accesskey="p" href="#The-hello-word-program">The hello word program</a>, -Up: <a rel="up" accesskey="u" href="#Starting-with-GHDL">Starting with GHDL</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">2.2 A full adder</h3> - -<p>VHDL is generally used for hardware design. This example starts with -a full adder described in the <samp><span class="file">adder.vhdl</span></samp> file: - -<pre class="example"> entity adder is - -- <var>i0</var><span class="roman">, </span><var>i1</var><span class="roman"> and the carry-in </span><var>ci</var><span class="roman"> are inputs of the adder.</span> - -- <var>s</var><span class="roman"> is the sum output, </span><var>co</var><span class="roman"> is the carry-out.</span> - port (i0, i1 : in bit; ci : in bit; s : out bit; co : out bit); - end adder; - - architecture rtl of adder is - begin - -- <span class="roman">This full-adder architecture contains two concurrent assignment.</span> - -- <span class="roman">Compute the sum.</span> - s <= i0 xor i1 xor ci; - -- <span class="roman">Compute the carry.</span> - co <= (i0 and i1) or (i0 and ci) or (i1 and ci); - end rtl; -</pre> - <p>You can analyze this design file: -<pre class="smallexample"> $ ghdl -a adder.vhdl -</pre> - <p>You can try to execute the ‘<samp><span class="samp">adder</span></samp>’ 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 <samp><span class="file">adder_tb.vhdl</span></samp> contains the testbench for -the adder: -<pre class="example"> -- <span class="roman">A testbench has no ports.</span> - entity adder_tb is - end adder_tb; - - architecture behav of adder_tb is - -- <span class="roman">Declaration of the component that will be instantiated.</span> - component adder - port (i0, i1 : in bit; ci : in bit; s : out bit; co : out bit); - end component; - -- <span class="roman">Specifies which entity is bound with the component.</span> - for adder_0: adder use entity work.adder; - signal i0, i1, ci, s, co : bit; - begin - -- <span class="roman">Component instantiation.</span> - adder_0: adder port map (i0 => i0, i1 => i1, ci => ci, - s => s, co => co); - - -- <span class="roman">This process does the real job.</span> - process - type pattern_type is record - -- <span class="roman">The inputs of the adder.</span> - i0, i1, ci : bit; - -- <span class="roman">The expected outputs of the adder.</span> - s, co : bit; - end record; - -- <span class="roman">The patterns to apply.</span> - 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 - -- <span class="roman">Check each pattern.</span> - for i in patterns'range loop - -- <span class="roman">Set the inputs.</span> - i0 <= patterns(i).i0; - i1 <= patterns(i).i1; - ci <= patterns(i).ci; - -- <span class="roman">Wait for the results.</span> - wait for 1 ns; - -- <span class="roman">Check the outputs.</span> - 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; - -- <span class="roman">Wait forever; this will finish the simulation.</span> - wait; - end process; - end behav; -</pre> - <p>As usual, you should analyze the design: -<pre class="smallexample"> $ ghdl -a adder_tb.vhdl -</pre> - <p>And build an executable for the testbench: -<pre class="smallexample"> $ ghdl -e adder_tb -</pre> - <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: -<pre class="smallexample"> $ ghdl -r adder_tb - adder_tb.vhdl:52:7:(assertion note): end of test -</pre> - <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: -<pre class="smallexample"> $ ghdl -r adder_tb --vcd=adder.vcd -</pre> - <p>Then, you may now view the waves: -<pre class="smallexample"> $ gtkwave adder.vcd -</pre> - <p>See <a href="#Simulation-options">Simulation options</a>, for more details on the <samp><span class="option">--vcd</span></samp> option and -other runtime options. - -<div class="node"> -<p><hr> -<a name="Starting-with-a-design"></a> -Previous: <a rel="previous" accesskey="p" href="#A-full-adder">A full adder</a>, -Up: <a rel="up" accesskey="u" href="#Starting-with-GHDL">Starting with GHDL</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">2.3 Starting with a design</h3> - -<p>Unless you are only studying VHDL, you will work with bigger designs than -the ones of the previous examples. - - <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 -<<code>http://ghdl.free.fr/dlx.tar.gz</code>> - - <p>First, untar the sources: -<pre class="smallexample"> $ tar zxvf dlx.tar.gz -</pre> - <p>In order not to pollute the sources with the library, it is a good idea -to create a <samp><span class="file">work/</span></samp> subdirectory for the ‘<samp><span class="samp">WORK</span></samp>’ library. To -any GHDL commands, we will add the <samp><span class="option">--workdir=work</span></samp> option, so -that all files generated by the compiler (except the executable) will be -placed in this directory. -<pre class="smallexample"> $ cd dlx - $ mkdir work -</pre> - <p>We will run the ‘<samp><span class="samp">dlx_test_behaviour</span></samp>’ 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: -<pre class="smallexample"> $ ghdl -i --workdir=work *.vhdl -</pre> - <p>and making a design: -<pre class="smallexample"> $ ghdl -m --workdir=work dlx_test_behaviour -</pre> - <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 <samp><span class="file">work/</span></samp> -directory, and the <samp><span class="file">dlx_test_behaviour</span></samp> executable in the current -directory. - - <p>The simulation needs to have a DLX program contained in the file -<samp><span class="file">dlx.out</span></samp>. This memory image will be be loaded in the DLX memory. -Just take one sample: -<pre class="smallexample"> $ cp test_loop.out dlx.out -</pre> - <p>And you can run the test suite: -<pre class="smallexample"> $ ghdl -r dlx_test_behaviour -</pre> - <p>The test bench monitors the bus and displays each instruction executed. -It finishes with an assertion of severity level note: -<pre class="smallexample"> dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction - encountered, execution halted -</pre> - <p>Since the clock is still running, you have to manually stop the program -with the <kbd>C-c</kbd> 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: -<pre class="smallexample"> $ ghdl -r dlx_test_behaviour --assert-level=note -</pre> - <p>With this option, the program stops just after the previous message: -<pre class="smallexample"> dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction - encountered, execution halted - error: assertion failed -</pre> - <p>If you want to make room on your hard drive, you can either: - <ul> -<li>clean the design library with the GHDL command: - <pre class="smallexample"> $ ghdl --clean --workdir=work -</pre> - <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. -<li>remove the design library with the GHDL command: - <pre class="smallexample"> $ ghdl --remove --workdir=work -</pre> - <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. -<li>remove the <samp><span class="file">work/</span></samp> directory: - <pre class="smallexample"> $ rm -rf work -</pre> - <p>Only the executable is kept. If you want to rebuild the design, create -the <samp><span class="file">work/</span></samp> directory, import the sources, and make the design. -</ul> - - <p>Sometimes, a design does not fully follow the VHDL standards. For example it -uses the badly engineered ‘<samp><span class="samp">std_logic_unsigned</span></samp>’ package. GHDL supports -this VHDL dialect through some options: -<pre class="smallexample"> --ieee=synopsys -fexplicit -</pre> - <p>See <a href="#IEEE-library-pitfalls">IEEE library pitfalls</a>, for more details. - -<div class="node"> -<p><hr> -<a name="Invoking-GHDL"></a> -Next: <a rel="next" accesskey="n" href="#Simulation-and-runtime">Simulation and runtime</a>, -Previous: <a rel="previous" accesskey="p" href="#Starting-with-GHDL">Starting with GHDL</a>, -Up: <a rel="up" accesskey="u" href="#Top">Top</a> - -</div> - -<!-- node-name, next, previous, up --> -<h2 class="chapter">3 Invoking GHDL</h2> - -<p>The form of the <code>ghdl</code> command is - -<pre class="smallexample"> $ ghdl <var>command</var> [<var>options<small class="dots">...</small></var>] -</pre> - <p>The GHDL program has several commands. The first argument selects -the commands. The options are used to slightly modify the action. - - <p>No options are allowed before the command. Except for the run commands, -no options are allowed after a filename or a unit name. - -<ul class="menu"> -<li><a accesskey="1" href="#Building-commands">Building commands</a> -<li><a accesskey="2" href="#GHDL-options">GHDL options</a> -<li><a accesskey="3" href="#Passing-options-to-other-programs">Passing options to other programs</a> -<li><a accesskey="4" href="#GHDL-warnings">GHDL warnings</a> -<li><a accesskey="5" href="#Rebuilding-commands">Rebuilding commands</a> -<li><a accesskey="6" href="#Library-commands">Library commands</a> -<li><a accesskey="7" href="#Cross_002dreference-command">Cross-reference command</a> -<li><a accesskey="8" href="#File-commands">File commands</a> -<li><a accesskey="9" href="#Misc-commands">Misc commands</a> -<li><a href="#Installation-Directory">Installation Directory</a> -<li><a href="#IEEE-library-pitfalls">IEEE library pitfalls</a> -<li><a href="#IEEE-math-packages">IEEE math packages</a> -</ul> - -<div class="node"> -<p><hr> -<a name="Building-commands"></a> -Next: <a rel="next" accesskey="n" href="#GHDL-options">GHDL options</a>, -Previous: <a rel="previous" accesskey="p" href="#Invoking-GHDL">Invoking GHDL</a>, -Up: <a rel="up" accesskey="u" href="#Invoking-GHDL">Invoking GHDL</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">3.1 Building commands</h3> - -<p>The mostly used commands of GHDL are those to analyze and elaborate a design. - -<ul class="menu"> -<li><a accesskey="1" href="#Analysis-command">Analysis command</a> -<li><a accesskey="2" href="#Elaboration-command">Elaboration command</a> -<li><a accesskey="3" href="#Run-command">Run command</a> -<li><a accesskey="4" href="#Elaborate-and-run-command">Elaborate and run command</a> -<li><a accesskey="5" href="#Bind-command">Bind command</a> -<li><a accesskey="6" href="#Link-command">Link command</a> -<li><a accesskey="7" href="#List-link-command">List link command</a> -<li><a accesskey="8" href="#Check-syntax-command">Check syntax command</a> -<li><a accesskey="9" href="#Analyze-and-elaborate-command">Analyze and elaborate command</a> -</ul> - -<div class="node"> -<p><hr> -<a name="Analysis-command"></a> -Next: <a rel="next" accesskey="n" href="#Elaboration-command">Elaboration command</a>, -Previous: <a rel="previous" accesskey="p" href="#Building-commands">Building commands</a>, -Up: <a rel="up" accesskey="u" href="#Building-commands">Building commands</a> - -</div> - -<!-- node-name, next, previous, up --> -<h4 class="subsection">3.1.1 Analysis command</h4> - -<p><a name="index-analysis-1"></a><a name="index-g_t_0040option_007b_002da_007d-command-2"></a> -<pre class="smallexample"> $ ghdl -a [<var>options</var>] <var>files</var> -</pre> - <p>The <dfn>analysis</dfn> command compiles one or more files, and creates an -object file for each source file. The analysis command is selected with -<var>-a</var> 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). -<!-- FIXME: check this. --> - - <p>See <a href="#GHDL-options">GHDL options</a>, for details on the GHDL options. For example, -to produce debugging information such as line numbers, use: - -<pre class="smallexample"> $ ghdl -a -g my_design.vhdl -</pre> - <div class="node"> -<p><hr> -<a name="Elaboration-command"></a> -Next: <a rel="next" accesskey="n" href="#Run-command">Run command</a>, -Previous: <a rel="previous" accesskey="p" href="#Analysis-command">Analysis command</a>, -Up: <a rel="up" accesskey="u" href="#Building-commands">Building commands</a> - -</div> - -<!-- node-name, next, previous, up --> -<h4 class="subsection">3.1.2 Elaboration command</h4> - -<p><a name="index-elaboration-3"></a><a name="index-g_t_0040option_007b_002de_007d-command-4"></a> -<pre class="smallexample"> $ ghdl -e [<var>options</var>] <var>primary_unit</var> [<var>secondary_unit</var>] -</pre> - <p>On GNU/Linux the <dfn>elaboration</dfn> command creates an executable -containing the code of the <code>VHDL</code> 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>The elaboration command is selected with <var>-e</var> switch, and must be -followed by either: - - <ul> -<li>a name of a configuration unit -<li>a name of an entity unit -<li>a name of an entity unit followed by a name of an architecture unit -</ul> - - <p>Name of the units must be a simple name, without any dot. You can -select the name of the ‘<samp><span class="samp">WORK</span></samp>’ library with the <samp><span class="option">--work=NAME</span></samp> -option, as described in <a href="#GHDL-options">GHDL options</a>. - - <p>See <a href="#Top-entity">Top entity</a>, for the restrictions on the root design of a -hierarchy. - - <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>The <samp><span class="option">-o</span></samp> followed by a filename can override the default -executable filename. - - <p>For the elaboration command, <code>GHDL</code> 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>The actual elaboration is performed at runtime. - - <p>On Windows this command can be skipped because it is also done by the -run command. - -<div class="node"> -<p><hr> -<a name="Run-command"></a> -Next: <a rel="next" accesskey="n" href="#Elaborate-and-run-command">Elaborate and run command</a>, -Previous: <a rel="previous" accesskey="p" href="#Elaboration-command">Elaboration command</a>, -Up: <a rel="up" accesskey="u" href="#Building-commands">Building commands</a> - -</div> - -<!-- node-name, next, previous, up --> -<h4 class="subsection">3.1.3 Run command</h4> - -<p><a name="index-run-5"></a><a name="index-g_t_0040option_007b_002dr_007d-command-6"></a>Run (or simulate) a design. - -<pre class="smallexample"> $ ghdl -r [<var>options</var>] <var>primary_unit</var> [<var>secondary_unit</var>] [<var>simulation_options</var>] -</pre> - <p>The options and arguments are the same as for the elaboration command, see <a href="#Elaboration-command">Elaboration command</a>. - - <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>This command exists for three reasons: - <ul> -<li>You don't have to create the executable program name. -<li>It is coherent with the ‘<samp><span class="samp">-a</span></samp>’ and ‘<samp><span class="samp">-e</span></samp>’ commands. -<li>It works with the Windows implementation, where the code is generated in -memory. -</ul> - - <p>On Windows this command elaborates and launches the simulation. As a consequence -you must use the same options used during analysis. - - <p>See <a href="#Simulation-and-runtime">Simulation and runtime</a>, for details on options. - -<div class="node"> -<p><hr> -<a name="Elaborate-and-run-command"></a> -Next: <a rel="next" accesskey="n" href="#Bind-command">Bind command</a>, -Previous: <a rel="previous" accesskey="p" href="#Run-command">Run command</a>, -Up: <a rel="up" accesskey="u" href="#Building-commands">Building commands</a> - -</div> - -<!-- node-name, next, previous, up --> -<h4 class="subsection">3.1.4 Elaborate and run command</h4> - -<p><a name="index-elaborate-and-run-7"></a><a name="index-g_t_0040option_007b_002d_002delab_002drun_007d-command-8"></a>Elaborate and then simulate a design unit. - -<pre class="smallexample"> $ ghdl --elab-run [<var>elab_options</var>] <var>primary_unit</var> [<var>secondary_unit</var>] [<var>run_options</var>] -</pre> - <p>This command acts like the elaboration command (see <a href="#Elaboration-command">Elaboration command</a>) -followed by the run command (see <a href="#Run-command">Run command</a>). - -<div class="node"> -<p><hr> -<a name="Bind-command"></a> -Next: <a rel="next" accesskey="n" href="#Link-command">Link command</a>, -Previous: <a rel="previous" accesskey="p" href="#Elaborate-and-run-command">Elaborate and run command</a>, -Up: <a rel="up" accesskey="u" href="#Building-commands">Building commands</a> - -</div> - -<h4 class="subsection">3.1.5 Bind command</h4> - -<p><a name="index-binding-9"></a><a name="index-g_t_0040option_007b_002d_002dbind_007d-command-10"></a>Bind a design unit and prepare the link step. - -<pre class="smallexample"> $ ghdl --bind [<var>options</var>] <var>primary_unit</var> [<var>secondary_unit</var>] -</pre> - <p>This command is only available on GNU/Linux. - - <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. - -<div class="node"> -<p><hr> -<a name="Link-command"></a> -Next: <a rel="next" accesskey="n" href="#List-link-command">List link command</a>, -Previous: <a rel="previous" accesskey="p" href="#Bind-command">Bind command</a>, -Up: <a rel="up" accesskey="u" href="#Building-commands">Building commands</a> - -</div> - -<h4 class="subsection">3.1.6 Link command</h4> - -<p><a name="index-linking-11"></a><a name="index-g_t_0040option_007b_002d_002dlink_007d-command-12"></a>Link an already bound design unit. - -<pre class="smallexample"> $ ghdl --link [<var>options</var>] <var>primary_unit</var> [<var>secondary_unit</var>] -</pre> - <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. - -<div class="node"> -<p><hr> -<a name="List-link-command"></a> -Next: <a rel="next" accesskey="n" href="#Check-syntax-command">Check syntax command</a>, -Previous: <a rel="previous" accesskey="p" href="#Link-command">Link command</a>, -Up: <a rel="up" accesskey="u" href="#Building-commands">Building commands</a> - -</div> - -<h4 class="subsection">3.1.7 List link command</h4> - -<p><a name="index-g_t_0040option_007b_002d_002dlist_002dlink_007d-command-13"></a>Display files which will be linked. - -<pre class="smallexample"> $ ghdl --list-link <var>primary_unit</var> [<var>secondary_unit</var>] -</pre> - <p>This command is only available on GNU/Linux. - - <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. - -<div class="node"> -<p><hr> -<a name="Check-syntax-command"></a> -Next: <a rel="next" accesskey="n" href="#Analyze-and-elaborate-command">Analyze and elaborate command</a>, -Previous: <a rel="previous" accesskey="p" href="#List-link-command">List link command</a>, -Up: <a rel="up" accesskey="u" href="#Building-commands">Building commands</a> - -</div> - -<h4 class="subsection">3.1.8 Check syntax command</h4> - -<p><a name="index-checking-syntax-14"></a><a name="index-g_t_0040option_007b_002ds_007d-command-15"></a>Analyze files but do not generate code. - -<pre class="smallexample"> $ ghdl -s [<var>options</var>] <var>files</var> -</pre> - <p>This command may be used to check the syntax of files. It does not update -the library. - -<div class="node"> -<p><hr> -<a name="Analyze-and-elaborate-command"></a> -Previous: <a rel="previous" accesskey="p" href="#Check-syntax-command">Check syntax command</a>, -Up: <a rel="up" accesskey="u" href="#Building-commands">Building commands</a> - -</div> - -<h4 class="subsection">3.1.9 Analyze and elaborate command</h4> - -<p><a name="index-Analyze-and-elaborate-command-16"></a><a name="index-g_t_0040option_007b_002dc_007d-command-17"></a>Analyze files and elaborate them at the same time. - - <p>On GNU/Linux: -<pre class="smallexample"> $ ghdl -c [<var>options</var>] <var>file</var>... -e <var>primary_unit</var> [<var>secondary_unit</var>] -</pre> - <p>On Windows: -<pre class="smallexample"> $ ghdl -c [<var>options</var>] <var>file</var>... -r <var>primary_unit</var> [<var>secondary_unit</var>] -</pre> - <p>This command combines analysis and elaboration: <var>file</var>s are analyzed and -the unit is then elaborated. However, code is only generated during the -elaboration. On Windows the simulation is launched. - - <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>All the units of the files are put into the ‘<samp><span class="samp">work</span></samp>’ library. But, the -work library is neither read from disk nor saved. Therefore, you must give -all the files of the ‘<samp><span class="samp">work</span></samp>’ library your design needs. - - <p>The advantages over the traditional approach (analyze and then elaborate) are: - <ul> -<li>The compilation cycle is achieved in one command. -<li>Since the files are only parsed once, the compilation cycle may be faster. -<li>You don't need to know an analysis order -<li>This command produces smaller executable, since unused units and subprograms -do not generate code. -</ul> - 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><span class="samp">std</span></samp>’ and ‘<samp><span class="samp">ieee</span></samp>’ 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>This command is still experimental. In case of problems, you should go back -to the traditional way. - -<!-- node-name, next, previous, up --> -<div class="node"> -<p><hr> -<a name="GHDL-options"></a> -Next: <a rel="next" accesskey="n" href="#Passing-options-to-other-programs">Passing options to other programs</a>, -Previous: <a rel="previous" accesskey="p" href="#Building-commands">Building commands</a>, -Up: <a rel="up" accesskey="u" href="#Invoking-GHDL">Invoking GHDL</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">3.2 GHDL options</h3> - -<p><a name="index-IEEE-1164-18"></a><a name="index-g_t1164-19"></a><a name="index-IEEE-1076_002e3-20"></a><a name="index-g_t1076_002e3-21"></a><!-- document gcc options --> -Besides the options described below, <code>GHDL</code> passes any debugging options -(those that begin with <samp><span class="option">-g</span></samp>) and optimizations options (those that -begin with <samp><span class="option">-O</span></samp> or <samp><span class="option">-f</span></samp>) to <code>GCC</code>. Refer to the <code>GCC</code> -manual for details. - - <dl> -<dt><code>--work=</code><var>NAME</var><dd><a name="index-g_t_0040option_007b_002d_002dwork_007d-switch-22"></a><a name="index-WORK-library-23"></a>Specify the name of the ‘<samp><span class="samp">WORK</span></samp>’ library. Analyzed units are always -placed in the library logically named ‘<samp><span class="samp">WORK</span></samp>’. With this option, -you can set its name. By default, the name is <var>work</var>. - - <p><code>GHDL</code> checks whether ‘<samp><span class="samp">WORK</span></samp>’ is a valid identifier. Although being -more or less supported, the ‘<samp><span class="samp">WORK</span></samp>’ 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). - - <p><code>VHDL</code> rules forbid you to add units to the ‘<samp><span class="samp">std</span></samp>’ library. -Furthermore, you should not put units in the ‘<samp><span class="samp">ieee</span></samp>’ library. - - <br><dt><code>--workdir=</code><var>DIR</var><dd><a name="index-g_t_0040option_007b_002d_002dworkdir_007d-switch-24"></a>Specify the directory where the ‘<samp><span class="samp">WORK</span></samp>’ library is located. When this -option is not present, the ‘<samp><span class="samp">WORK</span></samp>’ library is in the current -directory. The object files created by the compiler are always placed -in the same directory as the ‘<samp><span class="samp">WORK</span></samp>’ library. - - <p>Use option <samp><span class="option">-P</span></samp> to specify where libraries other than ‘<samp><span class="samp">WORK</span></samp>’ -are placed. - - <br><dt><code>--std=</code><var>STD</var><dd><a name="index-g_t_0040option_007b_002d_002dstd_007d-switch-25"></a>Specify the standard to use. By default, the standard is ‘<samp><span class="samp">93c</span></samp>’, which -means VHDL-93 accepting VHDL-87 syntax. For details on <var>STD</var> values see -<a href="#VHDL-standards">VHDL standards</a>. - - <br><dt><code>--ieee=</code><var>VER</var><dd><a name="index-g_t_0040option_007b_002d_002dieee_007d-switch-26"></a><a name="index-ieee-library-27"></a><a name="index-synopsys-library-28"></a><a name="index-mentor-library-29"></a>Select the <code>IEEE</code> library to use. <var>VER</var> must be one of: - - <dl> -<dt>‘<samp><span class="samp">none</span></samp>’<dd>Do not supply an <code>IEEE</code> library. Any library clause with the ‘<samp><span class="samp">IEEE</span></samp>’ -identifier will fail, unless you have created by your own a library with -the <code>IEEE</code> name. - - <br><dt>‘<samp><span class="samp">standard</span></samp>’<dd>Supply an <code>IEEE</code> library containing only packages defined by -<span class="sc">ieee</span> standards. Currently, there are the multivalue logic system -packages ‘<samp><span class="samp">std_logic_1164</span></samp>’ defined by IEEE 1164, the synthesis -packages , ‘<samp><span class="samp">numeric_bit</span></samp>’ and ‘<samp><span class="samp">numeric_std</span></samp>’ defined by IEEE -1076.3, and the <span class="sc">vital</span> packages ‘<samp><span class="samp">vital_timing</span></samp>’ and -‘<samp><span class="samp">vital_primitives</span></samp>’, defined by IEEE 1076.4. The version of these -packages is defined by the VHDL standard used. See <a href="#VITAL-packages">VITAL packages</a>, -for more details. - - <br><dt>‘<samp><span class="samp">synopsys</span></samp>’<dd>Supply the former packages and the following additional packages: -‘<samp><span class="samp">std_logic_arith</span></samp>’, ‘<samp><span class="samp">std_logic_signed</span></samp>’, -‘<samp><span class="samp">std_logic_unsigned</span></samp>’, ‘<samp><span class="samp">std_logic_textio</span></samp>’. -<!-- @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</code> -library without the permission from the <span class="sc">ieee</span>. - - <br><dt>‘<samp><span class="samp">mentor</span></samp>’<dd>Supply the standard packages and the following additional package: -‘<samp><span class="samp">std_logic_arith</span></samp>’. The package is a slight variation of a definitely -not standard but widely mis-used package. -</dl> - - <p>To avoid errors, you must use the same <code>IEEE</code> library for all units of -your design, and during elaboration. - - <br><dt><code>-P</code><var>DIRECTORY</var><dd><a name="index-g_t_0040option_007b_002dP_007d-switch-30"></a>Add <var>DIRECTORY</var> to the end of the list of directories to be searched for -library files. - - <p>The <code>WORK</code> library is always searched in the path specified by the -<samp><span class="option">--workdir=</span></samp> option, or in the current directory if the latter -option is not specified. - - <br><dt><code>-fexplicit</code><dd><a name="index-g_t_0040option_007b_002dfexplicit_007d-switch-31"></a>When two operators are overloaded, give preference to the explicit declaration. -This may be used to avoid the most common pitfall of the ‘<samp><span class="samp">std_logic_arith</span></samp>’ -package. See <a href="#IEEE-library-pitfalls">IEEE library pitfalls</a>, for an example. - - <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 ‘<samp><span class="samp">numeric_std</span></samp>’ package. - - <br><dt><code>--no-vital-checks</code><br><dt><code>--vital-checks</code><dd><a name="index-g_t_0040option_007b_002d_002dno_002dvital_002dchecks_007d-switch-32"></a><a name="index-g_t_0040option_007b_002d_002dvital_002dchecks_007d-switch-33"></a>Disable or enable checks of restriction on VITAL units. Checks are enabled -by default. - - <p>Checks are performed only when a design unit is decorated by a VITAL attribute. -The VITAL attributes are ‘<samp><span class="samp">VITAL_Level0</span></samp>’ and ‘<samp><span class="samp">VITAL_Level1</span></samp>’, both -declared in the ‘<samp><span class="samp">ieee.VITAL_Timing</span></samp>’ package. - - <p>Currently, VITAL checks are only partially implemented. See <a href="#VHDL-restrictions-for-VITAL">VHDL restrictions for VITAL</a>, for more details. - - <br><dt><code>--syn-binding</code><dd><a name="index-g_t_0040option_007b_002d_002dsyn_002dbinding_007d-switch-34"></a>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>This rule is known as synthesizer rule. - - <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>This option is only useful during elaboration. - - <br><dt><code>--PREFIX=</code><var>PATH</var><dd><a name="index-g_t_0040option_007b_002d_002dPREFIX_007d-switch-35"></a>Use <var>PATH</var> as the prefix path to find commands and pre-installed (std and -ieee) libraries. - - <br><dt><code>--GHDL1=</code><var>COMMAND</var><dd><a name="index-g_t_0040option_007b_002d_002dGHLD1_007d-switch-36"></a>Use <var>COMMAND</var> as the command name for the compiler. If <var>COMMAND</var> is -not a path, then it is search in the list of program directories. - - <br><dt><code>-v</code><dd>Be verbose. For example, for analysis, elaboration and make commands, GHDL -displays the commands executed. -</dl> - -<div class="node"> -<p><hr> -<a name="Passing-options-to-other-programs"></a> -Next: <a rel="next" accesskey="n" href="#GHDL-warnings">GHDL warnings</a>, -Previous: <a rel="previous" accesskey="p" href="#GHDL-options">GHDL options</a>, -Up: <a rel="up" accesskey="u" href="#Invoking-GHDL">Invoking GHDL</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">3.3 Passing options to other programs</h3> - -<p>These options are only available on GNU/Linux. - - <p>For many commands, <code>GHDL</code> acts as a driver: it invokes programs to perform -the command. You can pass arbitrary options to these programs. - - <p>Both the compiler and the linker are in fact GCC programs. See <a href="gcc.html#Invoking-GCC">GCC options</a>, for details on GCC -options. - - <dl> -<dt><code>-Wc,</code><var>OPTION</var><dd><a name="index-g_t_0040option_007b_002dW_007d-switch-37"></a>Pass <var>OPTION</var> as an option to the compiler. - - <br><dt><code>-Wa,</code><var>OPTION</var><dd><a name="index-g_t_0040option_007b_002dWa_007d-switch-38"></a>Pass <var>OPTION</var> as an option to the assembler. - - <br><dt><code>-Wl,</code><var>OPTION</var><dd><a name="index-g_t_0040option_007b_002dWl_007d-switch-39"></a>Pass <var>OPTION</var> as an option to the linker. -</dl> - -<div class="node"> -<p><hr> -<a name="GHDL-warnings"></a> -Next: <a rel="next" accesskey="n" href="#Rebuilding-commands">Rebuilding commands</a>, -Previous: <a rel="previous" accesskey="p" href="#Passing-options-to-other-programs">Passing options to other programs</a>, -Up: <a rel="up" accesskey="u" href="#Invoking-GHDL">Invoking GHDL</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">3.4 GHDL warnings</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>You could disable a warning by using the <samp><span class="option">--warn-no-XXX</span></samp> -instead of <samp><span class="option">--warn-XXX</span></samp>. - - <dl> -<dt><code>--warn-reserved</code><dd><a name="index-g_t_0040option_007b_002d_002dwarn_002dreserved_007d-switch-40"></a>Emit a warning if an identifier is a reserved word in a later VHDL standard. - - <br><dt><code>--warn-default-binding</code><dd><a name="index-g_t_0040option_007b_002d_002dwarn_002ddefault_002dbinding_007d-switch-41"></a>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. See <a href="#VHDL-standards">VHDL standards</a>, for more details about default binding -rules. - - <br><dt><code>--warn-binding</code><dd><a name="index-g_t_0040option_007b_002d_002dwarn_002dbinding_007d-switch-42"></a>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>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. - - <br><dt><code>--warn-library</code><dd><a name="index-g_t_0040option_007b_002d_002dwarn_002dlibrary_007d-switch-43"></a>Warns if a design unit replaces another design unit with the same name. - - <br><dt><code>--warn-vital-generic</code><dd><a name="index-g_t_0040option_007b_002d_002dwarn_002dvital_002dgeneric_007d-switch-44"></a>Warns if a generic name of a vital entity is not a vital generic name. This -is set by default. - - <br><dt><code>--warn-delayed-checks</code><dd><a name="index-g_t_0040option_007b_002d_002dwarn_002ddelayed_002dchecks_007d-switch-45"></a>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 <code>GHDL</code> doesn't read not required -package bodies). - - <p>These are checks for no wait statement in a procedure called in a -sensitized process and checks for pure rules of a function. - - <br><dt><code>--warn-body</code><dd><a name="index-g_t_0040option_007b_002d_002dwarn_002dbody_007d-switch-46"></a>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. - - <br><dt><code>--warn-specs</code><dd><a name="index-g_t_0040option_007b_002d_002dwarn_002dspecs_007d-switch-47"></a>Emit a warning if an all or others specification does not apply. - - <br><dt><code>--warn-unused</code><dd><a name="index-g_t_0040option_007b_002d_002dwarn_002dunused_007d-switch-48"></a>Emit a warning when a subprogram is never used. - - <br><dt><code>--warn-error</code><dd><a name="index-g_t_0040option_007b_002d_002dwarn_002derror_007d-switch-49"></a>When this option is set, warnings are considered as errors. - - </dl> - -<div class="node"> -<p><hr> -<a name="Rebuilding-commands"></a> -Next: <a rel="next" accesskey="n" href="#Library-commands">Library commands</a>, -Previous: <a rel="previous" accesskey="p" href="#GHDL-warnings">GHDL warnings</a>, -Up: <a rel="up" accesskey="u" href="#Invoking-GHDL">Invoking GHDL</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">3.5 Rebuilding commands</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. - -<ul class="menu"> -<li><a accesskey="1" href="#Import-command">Import command</a> -<li><a accesskey="2" href="#Make-command">Make command</a> -<li><a accesskey="3" href="#Generate-Makefile-command">Generate Makefile command</a> -</ul> - -<div class="node"> -<p><hr> -<a name="Import-command"></a> -Next: <a rel="next" accesskey="n" href="#Make-command">Make command</a>, -Previous: <a rel="previous" accesskey="p" href="#Rebuilding-commands">Rebuilding commands</a>, -Up: <a rel="up" accesskey="u" href="#Rebuilding-commands">Rebuilding commands</a> - -</div> - -<!-- node-name, next, previous, up --> -<h4 class="subsection">3.5.1 Import command</h4> - -<p><a name="index-importing-files-50"></a><a name="index-g_t_0040option_007b_002di_007d-command-51"></a>Add files in the work design library. - -<pre class="smallexample"> $ ghdl -i [<var>options</var>] <var>file</var>... -</pre> - <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>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>Since the files are parsed, there must be correct files. However, since they -are not analyzed, many errors are tolerated by this command. - - <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. - -<!-- Due to the LRM rules, there may be many analysis orders, producing --> -<!-- different results. For example, if an entity has several architectures, --> -<!-- the last architecture analyzed is the default one in default binding --> -<!-- indications. --> - <p>See <a href="#Make-command">Make command</a>, to actually build the design. - -<div class="node"> -<p><hr> -<a name="Make-command"></a> -Next: <a rel="next" accesskey="n" href="#Generate-Makefile-command">Generate Makefile command</a>, -Previous: <a rel="previous" accesskey="p" href="#Import-command">Import command</a>, -Up: <a rel="up" accesskey="u" href="#Rebuilding-commands">Rebuilding commands</a> - -</div> - -<!-- node-name, next, previous, up --> -<h4 class="subsection">3.5.2 Make command</h4> - -<p><a name="index-make-52"></a><a name="index-g_t_0040option_007b_002dm_007d-command-53"></a> -<pre class="smallexample"> $ ghdl -m [<var>options</var>] <var>primary</var> [<var>secondary</var>] -</pre> - <p>Analyze automatically outdated files and elaborate a design. - - <p>The primary unit denoted by the <var>primary</var> 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>With the <samp><span class="option">-f</span></samp> (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 <samp><span class="option">-g</span></samp> -debugging option). - - <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>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>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>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>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. - -<!-- does not exists: @section GHDL robust make command --> -<div class="node"> -<p><hr> -<a name="Generate-Makefile-command"></a> -Previous: <a rel="previous" accesskey="p" href="#Make-command">Make command</a>, -Up: <a rel="up" accesskey="u" href="#Rebuilding-commands">Rebuilding commands</a> - -</div> - -<!-- node-name, next, previous, up --> -<h4 class="subsection">3.5.3 Generate Makefile command</h4> - -<p><a name="index-g_t_0040option_007b_002d_002dgen_002dmakefile_007d-command-54"></a>Generate a Makefile to build a design unit. - -<pre class="smallexample"> $ ghdl --gen-makefile [<var>options</var>] <var>primary</var> [<var>secondary</var>] -</pre> - <p>This command works like the make command (see <a href="#Make-command">Make command</a>), but only a -makefile is generated on the standard output. - -<div class="node"> -<p><hr> -<a name="Library-commands"></a> -Next: <a rel="next" accesskey="n" href="#Cross_002dreference-command">Cross-reference command</a>, -Previous: <a rel="previous" accesskey="p" href="#Rebuilding-commands">Rebuilding commands</a>, -Up: <a rel="up" accesskey="u" href="#Invoking-GHDL">Invoking GHDL</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">3.6 Library commands</h3> - -<p>GHDL has a few commands which act on a library. - -<!-- node-name, next, previous, up --> -<ul class="menu"> -<li><a accesskey="1" href="#Directory-command">Directory command</a> -<li><a accesskey="2" href="#Clean-command">Clean command</a> -<li><a accesskey="3" href="#Remove-command">Remove command</a> -<li><a accesskey="4" href="#Copy-command">Copy command</a> -</ul> - -<div class="node"> -<p><hr> -<a name="Directory-command"></a> -Next: <a rel="next" accesskey="n" href="#Clean-command">Clean command</a>, -Previous: <a rel="previous" accesskey="p" href="#Library-commands">Library commands</a>, -Up: <a rel="up" accesskey="u" href="#Library-commands">Library commands</a> - -</div> - -<!-- node-name, next, previous, up --> -<h4 class="subsection">3.6.1 Directory command</h4> - -<p><a name="index-displaying-library-55"></a><a name="index-g_t_0040option_007b_002dd_007d-command-56"></a>Display the name of the units contained in a design library. -<pre class="smallexample"> $ ghdl -d [<var>options</var>] -</pre> - <p>The directory command, selected with the <var>-d</var> command line argument -displays the content of the work design library. All options are -allowed, but only a few are meaningful: <samp><span class="option">--work=NAME</span></samp>, -<samp><span class="option">--workdir=PATH</span></samp> and <samp><span class="option">--std=VER</span></samp>. - -<div class="node"> -<p><hr> -<a name="Clean-command"></a> -Next: <a rel="next" accesskey="n" href="#Remove-command">Remove command</a>, -Previous: <a rel="previous" accesskey="p" href="#Directory-command">Directory command</a>, -Up: <a rel="up" accesskey="u" href="#Library-commands">Library commands</a> - -</div> - -<!-- node-name, next, previous, up --> -<h4 class="subsection">3.6.2 Clean command</h4> - -<p><a name="index-cleaning-57"></a><a name="index-g_t_0040option_007b_002d_002dclean_007d-command-58"></a>Remove object and executable files but keep the library. - -<pre class="smallexample"> $ ghdl --clean [<var>options</var>] -</pre> - <p>GHDL tries to remove any object, executable or temporary file it could -have created. Source files are not removed. - - <p>There is no short command line form for this option to prevent accidental -clean up. - -<div class="node"> -<p><hr> -<a name="Remove-command"></a> -Next: <a rel="next" accesskey="n" href="#Copy-command">Copy command</a>, -Previous: <a rel="previous" accesskey="p" href="#Clean-command">Clean command</a>, -Up: <a rel="up" accesskey="u" href="#Library-commands">Library commands</a> - -</div> - -<h4 class="subsection">3.6.3 Remove command</h4> - -<p><a name="index-cleaning-all-59"></a><a name="index-g_t_0040option_007b_002d_002dremove_007d-command-60"></a>Do like the clean command but remove the library too. - -<pre class="smallexample"> $ ghdl --remove [<var>options</var>] -</pre> - <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. - -<div class="node"> -<p><hr> -<a name="Copy-command"></a> -Previous: <a rel="previous" accesskey="p" href="#Remove-command">Remove command</a>, -Up: <a rel="up" accesskey="u" href="#Library-commands">Library commands</a> - -</div> - -<h4 class="subsection">3.6.4 Copy command</h4> - -<p><a name="index-copying-library-61"></a><a name="index-g_t_0040option_007b_002d_002dcopy_007d-command-62"></a>Make a local copy of an existing library. - -<pre class="smallexample"> $ ghdl --copy --work=<var>name</var> [<var>options</var>] -</pre> - <p>Make a local copy of an existing library. This is very useful if you want to -add unit to the ‘<samp><span class="samp">ieee</span></samp>’ library: -<pre class="example"> $ ghdl --copy --work=ieee --ieee=synopsys - $ ghdl -a --work=ieee numeric_unsigned.vhd -</pre> - <div class="node"> -<p><hr> -<a name="Cross-reference-command"></a> -<a name="Cross_002dreference-command"></a> -Next: <a rel="next" accesskey="n" href="#File-commands">File commands</a>, -Previous: <a rel="previous" accesskey="p" href="#Library-commands">Library commands</a>, -Up: <a rel="up" accesskey="u" href="#Invoking-GHDL">Invoking GHDL</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">3.7 Cross-reference command</h3> - -<p>To easily navigate through your sources, you may generate cross-references. - -<pre class="smallexample"> $ ghdl --xref-html [<var>options</var>] <var>file</var>... -</pre> - <p>This command generates an html file for each <var>file</var> 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>The set of <var>file</var> are analyzed, and then, if the analysis is -successful, html files are generated in the directory specified by the -<samp><span class="option">-o </span><var>dir</var></samp> option, or <samp><span class="file">html/</span></samp> directory by default. - - <p>If the <samp><span class="option">--format=html2</span></samp> is specified, then the generated html -files follow the HTML 2.0 standard, and colours are specified with -‘<samp><span class="samp"><FONT></span></samp>’ tags. However, colours are hard-coded. - - <p>If the <samp><span class="option">--format=css</span></samp> is specified, then the generated html files -follow the HTML 4.0 standard, and use the CSS-1 file <samp><span class="file">ghdl.css</span></samp> 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. - -<div class="node"> -<p><hr> -<a name="File-commands"></a> -Next: <a rel="next" accesskey="n" href="#Misc-commands">Misc commands</a>, -Previous: <a rel="previous" accesskey="p" href="#Cross_002dreference-command">Cross-reference command</a>, -Up: <a rel="up" accesskey="u" href="#Invoking-GHDL">Invoking GHDL</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">3.8 File commands</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. - -<ul class="menu"> -<li><a accesskey="1" href="#Pretty-print-command">Pretty print command</a> -<li><a accesskey="2" href="#Find-command">Find command</a> -<li><a accesskey="3" href="#Chop-command">Chop command</a> -<li><a accesskey="4" href="#Lines-command">Lines command</a> -</ul> - -<div class="node"> -<p><hr> -<a name="Pretty-print-command"></a> -Next: <a rel="next" accesskey="n" href="#Find-command">Find command</a>, -Previous: <a rel="previous" accesskey="p" href="#File-commands">File commands</a>, -Up: <a rel="up" accesskey="u" href="#File-commands">File commands</a> - -</div> - -<!-- node-name, next, previous, up --> -<h4 class="subsection">3.8.1 Pretty print command</h4> - -<p><a name="index-g_t_0040option_007b_002d_002dpp_002dhtml_007d-command-63"></a><a name="index-pretty-printing-64"></a><a name="index-vhdl-to-html-65"></a> -Generate HTML on standard output from VHDL. - -<pre class="smallexample"> $ ghdl --pp-html [<var>options</var>] <var>file</var>... -</pre> - <p>The files are just scanned and an html file, with syntax highlighting is -generated on standard output. - - <p>Since the files are not even parsed, erroneous files or incomplete designs -can be pretty printed. - - <p>The style of the html file can be modified with the <samp><span class="option">--format=</span></samp> option. -By default or when the <samp><span class="option">--format=html2</span></samp> option is specified, the output -is an HTML 2.0 file, with colours set through ‘<samp><span class="samp"><FONT></span></samp>’ tags. When the -<samp><span class="option">--format=css</span></samp> option is specified, the output is an HTML 4.0 file, -with colours set through a CSS file, whose name is ‘<samp><span class="samp">ghdl.css</span></samp>’. -See <a href="#Cross_002dreference-command">Cross-reference command</a>, for more details about this CSS file. - -<div class="node"> -<p><hr> -<a name="Find-command"></a> -Next: <a rel="next" accesskey="n" href="#Chop-command">Chop command</a>, -Previous: <a rel="previous" accesskey="p" href="#Pretty-print-command">Pretty print command</a>, -Up: <a rel="up" accesskey="u" href="#File-commands">File commands</a> - -</div> - -<!-- node-name, next, previous, up --> -<h4 class="subsection">3.8.2 Find command</h4> - -<p><a name="index-g_t_0040option_007b_002df_007d-command-66"></a>Display the name of the design units in files. - -<pre class="smallexample"> $ ghdl -f <var>file</var>... -</pre> - <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. - -<div class="node"> -<p><hr> -<a name="Chop-command"></a> -Next: <a rel="next" accesskey="n" href="#Lines-command">Lines command</a>, -Previous: <a rel="previous" accesskey="p" href="#Find-command">Find command</a>, -Up: <a rel="up" accesskey="u" href="#File-commands">File commands</a> - -</div> - -<!-- node-name, next, previous, up --> -<h4 class="subsection">3.8.3 Chop command</h4> - -<p><a name="index-g_t_0040option_007b_002d_002dchop_007d-command-67"></a>Chop (or split) files at design unit. - -<pre class="smallexample"> $ ghdl --chop <var>files</var> -</pre> - <p><code>GHDL</code> reads files, and writes a file in the current directory for -every design unit. - - <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 <samp><span class="file">NAME.vhdl</span></samp>, where <var>NAME</var> is the name of the design -unit. For a package body, the filename is <samp><span class="file">NAME-body.vhdl</span></samp>. -Finally, for an architecture <var>ARCH</var> of an entity <var>ENTITY</var>, the -filename is <samp><span class="file">ENTITY-ARCH.vhdl</span></samp>. - - <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>Comments between design units are stored into the most adequate files. - - <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. - -<div class="node"> -<p><hr> -<a name="Lines-command"></a> -Previous: <a rel="previous" accesskey="p" href="#Chop-command">Chop command</a>, -Up: <a rel="up" accesskey="u" href="#File-commands">File commands</a> - -</div> - -<!-- node-name, next, previous, up --> -<h4 class="subsection">3.8.4 Lines command</h4> - -<p><a name="index-g_t_0040option_007b_002d_002dlines_007d-command-68"></a>Display on the standard output lines of files preceded by line number. - -<pre class="smallexample"> $ ghdl --lines <var>files</var> -</pre> - <div class="node"> -<p><hr> -<a name="Misc-commands"></a> -Next: <a rel="next" accesskey="n" href="#Installation-Directory">Installation Directory</a>, -Previous: <a rel="previous" accesskey="p" href="#File-commands">File commands</a>, -Up: <a rel="up" accesskey="u" href="#Invoking-GHDL">Invoking GHDL</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">3.9 Misc commands</h3> - -<p>There are a few GHDL commands which are seldom useful. - -<ul class="menu"> -<li><a accesskey="1" href="#Help-command">Help command</a> -<li><a accesskey="2" href="#Dispconfig-command">Dispconfig command</a> -<li><a accesskey="3" href="#Disp-standard-command">Disp standard command</a> -<li><a accesskey="4" href="#Version-command">Version command</a> -</ul> - -<div class="node"> -<p><hr> -<a name="Help-command"></a> -Next: <a rel="next" accesskey="n" href="#Dispconfig-command">Dispconfig command</a>, -Previous: <a rel="previous" accesskey="p" href="#Misc-commands">Misc commands</a>, -Up: <a rel="up" accesskey="u" href="#Misc-commands">Misc commands</a> - -</div> - -<h4 class="subsection">3.9.1 Help command</h4> - -<p><a name="index-g_t_0040option_007b_002dh_007d-command-69"></a><a name="index-g_t_0040option_007b_002d_002dhelp_007d-command-70"></a>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. - -<pre class="smallexample"> $ ghdl --help - $ ghdl -h - $ ghdl -h <var>command</var> -</pre> - <div class="node"> -<p><hr> -<a name="Dispconfig-command"></a> -Next: <a rel="next" accesskey="n" href="#Disp-standard-command">Disp standard command</a>, -Previous: <a rel="previous" accesskey="p" href="#Help-command">Help command</a>, -Up: <a rel="up" accesskey="u" href="#Misc-commands">Misc commands</a> - -</div> - -<!-- node-name, next, previous, up --> -<h4 class="subsection">3.9.2 Dispconfig command</h4> - -<p><a name="index-g_t_0040option_007b_002d_002ddispconfig_007d-command-71"></a><a name="index-display-configuration-72"></a>Display the program paths and options used by GHDL. - -<pre class="smallexample"> $ ghdl --dispconfig [<var>options</var>] -</pre> - <p>This may be useful to track installation errors. - -<div class="node"> -<p><hr> -<a name="Disp-standard-command"></a> -Next: <a rel="next" accesskey="n" href="#Version-command">Version command</a>, -Previous: <a rel="previous" accesskey="p" href="#Dispconfig-command">Dispconfig command</a>, -Up: <a rel="up" accesskey="u" href="#Misc-commands">Misc commands</a> - -</div> - -<!-- node-name, next, previous, up --> -<h4 class="subsection">3.9.3 Disp standard command</h4> - -<p><a name="index-g_t_0040option_007b_002d_002ddisp_002dstandard_007d-command-73"></a><a name="index-display-_0040samp_007bstd_002estandard_007d-74"></a>Display the ‘<samp><span class="samp">std.standard</span></samp>’ package: - -<pre class="smallexample"> $ ghdl --disp-standard [<var>options</var>] -</pre> - <div class="node"> -<p><hr> -<a name="Version-command"></a> -Previous: <a rel="previous" accesskey="p" href="#Disp-standard-command">Disp standard command</a>, -Up: <a rel="up" accesskey="u" href="#Misc-commands">Misc commands</a> - -</div> - -<!-- node-name, next, previous, up --> -<h4 class="subsection">3.9.4 Version command</h4> - -<p><a name="index-g_t_0040option_007b_002d_002dversion_007d-command-75"></a><a name="index-version-76"></a>Display the <code>GHDL</code> version and exit. - -<pre class="smallexample"> $ ghdl --version -</pre> - <div class="node"> -<p><hr> -<a name="Installation-Directory"></a> -Next: <a rel="next" accesskey="n" href="#IEEE-library-pitfalls">IEEE library pitfalls</a>, -Previous: <a rel="previous" accesskey="p" href="#Misc-commands">Misc commands</a>, -Up: <a rel="up" accesskey="u" href="#Invoking-GHDL">Invoking GHDL</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">3.10 Installation Directory</h3> - -<!-- @code{GHDL} is installed with the @code{std} and @code{ieee} libraries. --> -<p>During analysis and elaboration <code>GHDL</code> may read the <code>std</code> -and <code>ieee</code> files. The location of these files is based on the prefix, -which is (in priority order): - <ol type=1 start=1> -<li>the <samp><span class="option">--PREFIX=</span></samp> command line option - - <li>the <var>GHDL_PREFIX</var> environment variable - - <li>a built-in default path. It is a hard-coded path on GNU/Linux and the -value of the ‘<samp><span class="samp">HKLM\Software\Ghdl\Install_Dir</span></samp>’ registry entry on Windows. - </ol> - - <p>You should use the <samp><span class="option">--dispconfig</span></samp> command (see <a href="#Dispconfig-command">Dispconfig command</a> for details) to disp and debug installation problems. - -<div class="node"> -<p><hr> -<a name="IEEE-library-pitfalls"></a> -Next: <a rel="next" accesskey="n" href="#IEEE-math-packages">IEEE math packages</a>, -Previous: <a rel="previous" accesskey="p" href="#Installation-Directory">Installation Directory</a>, -Up: <a rel="up" accesskey="u" href="#Invoking-GHDL">Invoking GHDL</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">3.11 IEEE library pitfalls</h3> - -<p>When you use options <samp><span class="option">--ieee=synopsys</span></samp> or <samp><span class="option">--ieee=mentor</span></samp>, -the <code>IEEE</code> library contains non standard packages such as -‘<samp><span class="samp">std_logic_arith</span></samp>’. <!-- FIXME: ref --> - - <p>These packages are not standard because there are not described by an IEEE -standard, even if they have been put in the <code>IEEE</code> library. Furthermore, -they are not really de-facto standard, because there are slight differences -between the packages of Mentor and those of Synopsys. - - <p>Furthermore, since they are not well-thought, their use has pitfalls. For -example, this description has error during compilation: -<pre class="example"> library ieee; - use ieee.std_logic_1164.all; - - -- <span class="roman">A counter from 0 to 10</span>. - 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 -- <span class="roman">Error</span> - v <= x"0"; - else - v <= v + 1; - end if; - end if; - end process; - - val <= v; - end bad; -</pre> - <p>When you analyze this design, GHDL does not accept it (too long lines -have been split for readability): -<pre class="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 -</pre> - <p>Indeed, the <code>"="</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</code> 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>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>You can force GHDL to use this rule with the <samp><span class="option">-fexplicit</span></samp> option. -See <a href="#GHDL-options">GHDL options</a>, for more details. - - <p>However it is easy to fix this error, by using a selected name: -<pre class="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; -</pre> - <p>It is better to only use the standard packages defined by IEEE, which -provides the same functionalities: -<pre class="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; -</pre> - <div class="node"> -<p><hr> -<a name="IEEE-math-packages"></a> -Previous: <a rel="previous" accesskey="p" href="#IEEE-library-pitfalls">IEEE library pitfalls</a>, -Up: <a rel="up" accesskey="u" href="#Invoking-GHDL">Invoking GHDL</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">3.12 IEEE math packages</h3> - -<p><a name="index-Math_005fReal-77"></a><a name="index-Math_005fComplex-78"></a> -The ‘<samp><span class="samp">ieee</span></samp>’ math packages (‘<samp><span class="samp">math_real</span></samp>’ and -‘<samp><span class="samp">math_complex</span></samp>’) provided with <code>GHDL</code> are not fully compliant with -the <code>IEEE</code> standard. They are based on an early draft which can be -redistributed contrary to the final version of the package. - - <p>This is unfortunate and may generate errors as some declarations are missing -or have slightly changed. - - <p>If you have bought the standard from ‘<samp><span class="samp">ieee</span></samp>’ then you can download -the sources of the packages from -<a href="http://standards.ieee.org/downloads/1076/1076.2-1996">http://standards.ieee.org/downloads/1076/1076.2-1996</a> -(unrestricted access). You'd better to just download -<samp><span class="file">math_real.vhdl</span></samp>, <samp><span class="file">math_real-body.vhdl</span></samp>, -<samp><span class="file">math_complex.vhdl</span></samp> and <samp><span class="file">math_complex-body.vhdl</span></samp>. The other files -are not necessary: the ‘<samp><span class="samp">std_logic_1164</span></samp>’ package has to be updated for -<code>VHDL</code> 1993 (the <code>xnor</code> functions are commented out). - - <p>If you want to replace math packages for the standard version of the -<code>ieee</code> library, do: -<pre class="smallexample"> $ cp math_real.vhdl math_real-body.vhdl <samp><span class="file">ieee_install_dir</span></samp> - $ cp math_complex.vhdl math_complex-body.vhdl <samp><span class="file">ieee_install_dir</span></samp> - $ cd <samp><span class="file">ieee_install_dir</span></samp> - $ ghdl -a --work=ieee math_real.vhdl math_real-body.vhdl - $ ghdl -a --work=ieee math_complex.vhdl math_complex-body.vhdl -</pre> - <p>(Replace <samp><span class="file">ieee_install_dir</span></samp> by the location of the <code>ieee</code> library as -displayed by ‘<samp><span class="samp">ghdl -dispconfig</span></samp>’). - - <p>You can repeat this for the ‘<samp><span class="samp">synopsys</span></samp>’ version of the <code>ieee</code> library. - - <p>Don't forget that the math packages are only defined for the 1993 standard. - -<div class="node"> -<p><hr> -<a name="Simulation-and-runtime"></a> -Next: <a rel="next" accesskey="n" href="#GHDL-implementation-of-VHDL">GHDL implementation of VHDL</a>, -Previous: <a rel="previous" accesskey="p" href="#Invoking-GHDL">Invoking GHDL</a>, -Up: <a rel="up" accesskey="u" href="#Top">Top</a> - -</div> - -<!-- node-name, next, previous, up --> -<h2 class="chapter">4 Simulation and runtime</h2> - -<ul class="menu"> -<li><a accesskey="1" href="#Simulation-options">Simulation options</a> -<li><a accesskey="2" href="#Debugging-VHDL-programs">Debugging VHDL programs</a> -</ul> - -<div class="node"> -<p><hr> -<a name="Simulation-options"></a> -Next: <a rel="next" accesskey="n" href="#Debugging-VHDL-programs">Debugging VHDL programs</a>, -Previous: <a rel="previous" accesskey="p" href="#Simulation-and-runtime">Simulation and runtime</a>, -Up: <a rel="up" accesskey="u" href="#Simulation-and-runtime">Simulation and runtime</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">4.1 Simulation options</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>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>However, the GHDL runtime behaviour can be modified with some options; for -example, it is possible to stop simulation after a certain time. - - <p>The exit status of the simulation is ‘<samp><span class="samp">EXIT_SUCCESS</span></samp>’ (0) if the -simulation completes, or ‘<samp><span class="samp">EXIT_FAILURE</span></samp>’ (1) in case of error -(assertion failure, overflow or any constraint error). - - <p>Here is the list of the most useful options. Some debugging options are -also available, but not described here. The ‘<samp><span class="samp">--help</span></samp>’ options lists -all options available, including the debugging one. - - <dl> -<dt><code>--assert-level=</code><var>LEVEL</var><dd><a name="index-g_t_0040option_007b_002d_002dassert_002dlevel_007d-option-79"></a>Select the assertion level at which an assertion violation stops the -simulation. <var>LEVEL</var> is the name from the <code>severity_level</code> -enumerated type defined in the <code>standard</code> package or the -‘<samp><span class="samp">none</span></samp>’ name. - - <p>By default, only assertion violation of severity level ‘<samp><span class="samp">failure</span></samp>’ -stops the simulation. - - <p>For example, if <var>LEVEL</var> was ‘<samp><span class="samp">warning</span></samp>’, any assertion violation -with severity level ‘<samp><span class="samp">warning</span></samp>’, ‘<samp><span class="samp">error</span></samp>’ or ‘<samp><span class="samp">failure</span></samp>’ would -stop simulation, but the assertion violation at the ‘<samp><span class="samp">note</span></samp>’ severity -level would only display a message. - - <p>‘<samp><span class="samp">--assert-level=none</span></samp>’ prevents any assertion violation to stop -simulation. - - <br><dt><code>--ieee-asserts=</code><var>POLICY</var><dd><a name="index-g_t_0040option_007b_002d_002dieee_002dasserts_007d-option-80"></a>Select how the assertions from ‘<samp><span class="samp">ieee</span></samp>’ units are -handled. <var>POLICY</var> can be ‘<samp><span class="samp">enable</span></samp>’ (the default), -‘<samp><span class="samp">disable</span></samp>’ which disables all assertion from ‘<samp><span class="samp">ieee</span></samp>’ packages -and ‘<samp><span class="samp">disable-at-0</span></samp>’ which disables only at start of simulation. - - <p>This option can be useful to avoid assertion message from -‘<samp><span class="samp">ieee.numeric_std</span></samp>’ (and other ‘<samp><span class="samp">ieee</span></samp>’ packages). - - <br><dt><code>--stop-time=</code><var>TIME</var><dd><a name="index-g_t_0040option_007b_002d_002dstop_002dtime_007d-option-81"></a>Stop the simulation after <var>TIME</var>. <var>TIME</var> is expressed as a time -value, <em>without</em> any space. The time is the simulation time, not -the real clock time. - - <p>For examples: - - <pre class="smallexample"> $ ./my_design --stop-time=10ns - $ ./my_design --stop-time=ps -</pre> - <br><dt><code>--stop-delta=</code><var>N</var><dd><a name="index-g_t_0040option_007b_002d_002dstop_002ddelta_007d-option-82"></a>Stop the simulation after <var>N</var> delta cycles in the same current time. -<!-- Delta cycles is a simulation technic used by VHDL to --> - - <br><dt><code>--disp-time</code><dd><a name="index-g_t_0040option_007b_002d_002ddisp_002dtime_007d-option-83"></a><a name="index-display-time-84"></a>Display the time and delta cycle number as simulation advances. - - <br><dt><code>--disp-tree[</code><var>=KIND</var><code>]</code><dd><a name="index-g_t_0040option_007b_002d_002ddisp_002dtree_007d-option-85"></a><a name="index-display-design-hierarchy-86"></a>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</var> is optional, but if set must be one of: - <dl> -<dt>‘<samp><span class="samp">none</span></samp>’<dd>Do not display hierarchy. Same as if the option was not present. -<br><dt>‘<samp><span class="samp">inst</span></samp>’<dd>Display entities, architectures, instances, blocks and generates statements. -<br><dt>‘<samp><span class="samp">proc</span></samp>’<dd>Like ‘<samp><span class="samp">inst</span></samp>’ but also display processes. -<br><dt>‘<samp><span class="samp">port</span></samp>’<dd>Like ‘<samp><span class="samp">proc</span></samp>’ but display ports and signals too. -</dl> - If <var>KIND</var> is not specified, the hierarchy is displayed with the -‘<samp><span class="samp">port</span></samp>’ mode. - - <br><dt><code>--no-run</code><dd><a name="index-g_t_0040option_007b_002d_002dno_002drun_007d-option-87"></a>Do not simulate, only elaborate. This may be used with -<samp><span class="option">--disp-tree</span></samp> to display the tree without simulating the whole -design. - - <br><dt><code>--vcd=</code><var>FILENAME</var><br><dt><code>--vcdgz=</code><var>FILENAME</var><dd><a name="index-g_t_0040option_007b_002d_002dvcd_007d-option-88"></a><a name="index-g_t_0040option_007b_002d_002dvcdgz_007d-option-89"></a><a name="index-vcd-90"></a><a name="index-value-change-dump-91"></a><a name="index-dump-of-signals-92"></a><samp><span class="option">--vcd</span></samp> dumps into the VCD file <var>FILENAME</var> the signal -values before each non-delta cycle. If <var>FILENAME</var> is ‘<samp><span class="samp">-</span></samp>’, -then the standard output is used, otherwise a file is created or -overwritten. - - <p>The <samp><span class="option">--vcdgz</span></samp> option is the same as the <samp><span class="option">--vcd</span></samp> option, -but the output is compressed using the <code>zlib</code> (<code>gzip</code> -compression). However, you can't use the ‘<samp><span class="samp">-</span></samp>’ filename. -Furthermore, only one VCD file can be written. - - <p><dfn>VCD</dfn> (value change dump) is a file format defined -by the <code>verilog</code> standard and used by virtually any wave viewer. - - <p>Since it comes from <code>verilog</code>, only a few VHDL types can be dumped. GHDL -dumps only signals whose base type is of the following: - <ul> -<li>types defined in the ‘<samp><span class="samp">std.standard</span></samp>’ package: - <ul> -<li>‘<samp><span class="samp">bit</span></samp>’ -<li>‘<samp><span class="samp">bit_vector</span></samp>’ -</ul> - <li>types defined in the ‘<samp><span class="samp">ieee.std_logic_1164</span></samp>’ package: - <ul> -<li>‘<samp><span class="samp">std_ulogic</span></samp>’ -<li>‘<samp><span class="samp">std_logic</span></samp>’ (because it is a subtype of ‘<samp><span class="samp">std_ulogic</span></samp>’) -<li>‘<samp><span class="samp">std_ulogic_vector</span></samp>’ -<li>‘<samp><span class="samp">std_logic_vector</span></samp>’ -</ul> - <li>any integer type -</ul> - - <p>I have successfully used <code>gtkwave</code> to view VCD files. - - <p>Currently, there is no way to select signals to be dumped: all signals are -dumped, which can generate big files. - - <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 (see <a href="#Reporting-bugs">Reporting bugs</a>). - - <br><dt><code>--wave=</code><var>FILENAME</var><dd><a name="index-g_t_0040option_007b_002d_002dwave_007d-option-93"></a>Write the waveforms into a <code>ghw</code> (GHdl Waveform) file. Currently, all -the signals are dumped into the waveform file, you cannot select a hierarchy -of signals to be dumped. - - <p>The format of this file was defined by myself and is not yet completely fixed. -It may change slightly. - - <p>There is a patch against <code>gtkwave 1.3.72</code> on the ghdl website at -<a href="ghdl.free.fr">ghdl.free.fr</a>, so that it can read such files. - - <p>Contrary to VCD files, any VHDL type can be dumped into a GHW file. - - <br><dt><code>--sdf=</code><var>PATH</var><code>=</code><var>FILENAME</var><br><dt><code>--sdf=min=</code><var>PATH</var><code>=</code><var>FILENAME</var><br><dt><code>--sdf=typ=</code><var>PATH</var><code>=</code><var>FILENAME</var><br><dt><code>--sdf=max=</code><var>PATH</var><code>=</code><var>FILENAME</var><dd><a name="index-g_t_0040option_007b_002d_002dsdf_007d-option-94"></a>Do VITAL annotation on <var>PATH</var> with SDF file <var>FILENAME</var>. - - <p><var>PATH</var> is a path of instances, separated with ‘<samp><span class="samp">.</span></samp>’ or ‘<samp><span class="samp">/</span></samp>’. -Any separator can be used. Instances are component instantiation labels, -generate labels or block labels. Currently, you cannot use an indexed name. - - <p>If the option contains a type of delay, that is <samp><span class="option">min=</span></samp>, -<samp><span class="option">typ=</span></samp> or <samp><span class="option">max=</span></samp>, 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>See <a href="#Backannotation">Backannotation</a>, for more details. - - <br><dt><code>--stack-max-size=</code><var>SIZE</var><dd><a name="index-g_t_0040option_007b_002d_002dstack_002dmax_002dsize_007d-option-95"></a>Set the maximum size in bytes of the non-sensitized processes stacks. - - <p>If the value <var>SIZE</var> is followed (without any space) by the ‘<samp><span class="samp">k</span></samp>’, -‘<samp><span class="samp">K</span></samp>’, ‘<samp><span class="samp">kb</span></samp>’, ‘<samp><span class="samp">Kb</span></samp>’, ‘<samp><span class="samp">ko</span></samp>’ or ‘<samp><span class="samp">Ko</span></samp>’ multiplier, then -the size is the numeric value multiplied by 1024. - - <p>If the value <var>SIZE</var> is followed (without any space) by the ‘<samp><span class="samp">m</span></samp>’, -‘<samp><span class="samp">M</span></samp>’, ‘<samp><span class="samp">mb</span></samp>’, ‘<samp><span class="samp">Mb</span></samp>’, ‘<samp><span class="samp">mo</span></samp>’ or ‘<samp><span class="samp">Mo</span></samp>’ multiplier, then -the size is the numeric value multiplied by 1024 * 1024 = 1048576. - - <p>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. - - <p>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. - - <br><dt><code>--stack-size=</code><var>SIZE</var><dd><a name="index-g_t_0040option_007b_002d_002dstack_002dsize_007d-option-96"></a>Set the initial size in bytes of the non-sensitized processes stack. -The <var>SIZE</var> value has the same format as the previous option. - - <p>The stack of the non-sensitized processes grows until reaching the -maximum size limit. - - <br><dt><code>--help</code><dd>Display a short description of the options accepted by the runtime library. -</dl> - -<div class="node"> -<p><hr> -<a name="Debugging-VHDL-programs"></a> -Previous: <a rel="previous" accesskey="p" href="#Simulation-options">Simulation options</a>, -Up: <a rel="up" accesskey="u" href="#Simulation-and-runtime">Simulation and runtime</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">4.2 Debugging VHDL programs</h3> - -<p><a name="index-debugging-97"></a><a name="index-g_t_0040code_007b_005f_005fghdl_005ffatal_007d-98"></a>Debugging VHDL programs using <code>GDB</code> is possible only on GNU/Linux systems. - - <p><code>GDB</code> is a general purpose debugger for programs compiled by <code>GCC</code>. -Currently, there is no VHDL support for <code>GDB</code>. It may be difficult -to inspect variables or signals in <code>GDB</code>, however, <code>GDB</code> is -still able to display the stack frame in case of error or to set a breakpoint -at a specified line. - - <p><code>GDB</code> can be useful to precisely catch a runtime error, such as indexing -an array beyond its bounds. All error check subprograms call the -<code>__ghdl_fatal</code> procedure. Therefore, to catch runtime error, set -a breakpoint like this: -<pre class="smallexample"> (gdb) break __ghdl_fatal -</pre> - <p>When the breakpoint is hit, use the <code>where</code> or <code>bt</code> command to -display the stack frames. - -<div class="node"> -<p><hr> -<a name="GHDL-implementation-of-VHDL"></a> -Next: <a rel="next" accesskey="n" href="#GHDL-implementation-of-VITAL">GHDL implementation of VITAL</a>, -Previous: <a rel="previous" accesskey="p" href="#Simulation-and-runtime">Simulation and runtime</a>, -Up: <a rel="up" accesskey="u" href="#Top">Top</a> - -</div> - -<!-- node-name, next, previous, up --> -<h2 class="chapter">5 GHDL implementation of VHDL</h2> - -<p>This chapter describes several implementation defined aspect of VHDL in GHDL. - -<ul class="menu"> -<li><a accesskey="1" href="#VHDL-standards">VHDL standards</a> -<li><a accesskey="2" href="#Source-representation">Source representation</a> -<li><a accesskey="3" href="#Library-database">Library database</a> -<li><a accesskey="4" href="#VHDL-files-format">VHDL files format</a> -<li><a accesskey="5" href="#Top-entity">Top entity</a> -<li><a accesskey="6" href="#Using-vendor-libraries">Using vendor libraries</a> -<li><a accesskey="7" href="#Using-ieee_002emath_005freal-or-ieee_002emath_005fcomplex">Using ieee.math_real or ieee.math_complex</a> -<li><a accesskey="8" href="#Interfacing-to-other-languages">Interfacing to other languages</a> -</ul> - -<div class="node"> -<p><hr> -<a name="VHDL-standards"></a> -Next: <a rel="next" accesskey="n" href="#Source-representation">Source representation</a>, -Previous: <a rel="previous" accesskey="p" href="#GHDL-implementation-of-VHDL">GHDL implementation of VHDL</a>, -Up: <a rel="up" accesskey="u" href="#GHDL-implementation-of-VHDL">GHDL implementation of VHDL</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">5.1 VHDL standards</h3> - -<p><a name="index-VHDL-standards-99"></a><a name="index-IEEE-1076-100"></a><a name="index-IEEE-1076a-101"></a><a name="index-g_t1076-102"></a><a name="index-g_t1076a-103"></a><a name="index-v87-104"></a><a name="index-v93-105"></a><a name="index-v93c-106"></a><a name="index-v00-107"></a><a name="index-v02-108"></a>This is very unfortunate, but there are many versions of the VHDL language. - - <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>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>VHDL was revised in 1993 by IEEE as IEEE 1076-1993. This revision is still -well-known. - - <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: - - <ul> -<li>the syntax of file declaration has changed (this is the most visible source -of incompatibility), -<li>new keywords were introduced (group, impure, inertial, literal, -postponed, pure, reject, rol, ror, shared, sla, sll, sra, srl, -unaffected, xnor), -<li>some dynamic behaviours have changed (the concatenation is one of them), -<li>rules have been added. -</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>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</code> attribute has slightly changed. - - <p>You can select the VHDL standard expected by GHDL with the -‘<samp><span class="samp">--std=VER</span></samp>’ option, where <var>VER</var> is one of the left column of the -table below: - - <dl> -<dt>‘<samp><span class="samp">87</span></samp>’<dd>Select VHDL-87 standard as defined by IEEE 1076-1987. LRM bugs corrected by -later revisions are taken into account. -<br><dt>‘<samp><span class="samp">93</span></samp>’<dd>Select VHDL-93; VHDL-87 file declarations are not accepted. -<br><dt>‘<samp><span class="samp">93c</span></samp>’<dd>Select VHDL-93 standard with relaxed rules: - <ul> -<li>VHDL-87 file declarations are accepted; -<li>default binding indication rules of VHDL-02 are used. Default binding rules -are often used, but they are particularly obscure before VHDL-02. -</ul> - <br><dt>‘<samp><span class="samp">00</span></samp>’<dd>Select VHDL-2000 standard, which adds protected types. -<br><dt>‘<samp><span class="samp">02</span></samp>’<dd>Select VHDL-2002 standard (partially implemented). -</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. - -<div class="node"> -<p><hr> -<a name="Source-representation"></a> -Next: <a rel="next" accesskey="n" href="#Library-database">Library database</a>, -Previous: <a rel="previous" accesskey="p" href="#VHDL-standards">VHDL standards</a>, -Up: <a rel="up" accesskey="u" href="#GHDL-implementation-of-VHDL">GHDL implementation of VHDL</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">5.2 Source representation</h3> - -<p>According to the VHDL standard, design units (i.e. entities, -architectures, packages, package bodies and configurations) may be -independently analyzed. - - <p>Several design units may be grouped into a design file. - - <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>It is common to have several design units in a design file. - - <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>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. - -<div class="node"> -<p><hr> -<a name="Library-database"></a> -Next: <a rel="next" accesskey="n" href="#VHDL-files-format">VHDL files format</a>, -Previous: <a rel="previous" accesskey="p" href="#Source-representation">Source representation</a>, -Up: <a rel="up" accesskey="u" href="#GHDL-implementation-of-VHDL">GHDL implementation of VHDL</a> - -</div> - -<h3 class="section">5.3 Library database</h3> - -<p>Each design unit analyzed is placed into a design library. By default, -the name of this design library is ‘<samp><span class="samp">work</span></samp>’; however, this can be -changed with the <samp><span class="option">--work=NAME</span></samp> option of GHDL. - - <p>To keep the list of design units in a design library, GHDL creates -library files. The name of these files is ‘<samp><span class="samp">NAME-objVER.cf</span></samp>’, where -<var>NAME</var> is the name of the library, and <var>VER</var> the VHDL version (87 -or 93) used to analyze the design units. - - <p>You don't have to know how to read a library file. You can display it -using the <samp><span class="option">-d</span></samp> of <code>ghdl</code>. The file contains the name of the -design units, as well as the location and the dependencies. - - <p>The format may change with the next version of GHDL. - -<div class="node"> -<p><hr> -<a name="VHDL-files-format"></a> -Next: <a rel="next" accesskey="n" href="#Top-entity">Top entity</a>, -Previous: <a rel="previous" accesskey="p" href="#Library-database">Library database</a>, -Up: <a rel="up" accesskey="u" href="#GHDL-implementation-of-VHDL">GHDL implementation of VHDL</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">5.4 VHDL files format</h3> - -<p><a name="index-file-format-109"></a><a name="index-logical-name-110"></a>VHDL has features to handle files. - - <p>GHDL associates a file logical name (the VHDL filename) to an operating -system filename. The logical name ‘<samp><span class="samp">STD_INPUT</span></samp>’ is associated to -the standard input as defined by ‘<samp><span class="samp">stdin</span></samp>’ stream of the C library, -while the logical name ‘<samp><span class="samp">STD_OUTPUT</span></samp>’ is associated to the standard -output, as defined by the ‘<samp><span class="samp">stdout</span></samp>’ stream of the C library. Other -logical name are directly mapped to a filename as defined by the first -(‘<samp><span class="samp">path</span></samp>’) argument of the ‘<samp><span class="samp">fopen</span></samp>’ function of the C library. -For a binary file, the ‘<samp><span class="samp">b</span></samp>’ character is appended to the mode argument -(binary mode). - - <p>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. - - <p>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. - - <p>For more details about these point, please refer to your operation system -documentation. - -<!-- tell more about possible errors. --> - <p>There are two kinds of files: binary or text files. - - <p>Text files are files of type ‘<samp><span class="samp">std.textio.text</span></samp>’. 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. - - <p>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. - - <p>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</code> program. - - <p>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. - -<div class="node"> -<p><hr> -<a name="Top-entity"></a> -Next: <a rel="next" accesskey="n" href="#Using-vendor-libraries">Using vendor libraries</a>, -Previous: <a rel="previous" accesskey="p" href="#VHDL-files-format">VHDL files format</a>, -Up: <a rel="up" accesskey="u" href="#GHDL-implementation-of-VHDL">GHDL implementation of VHDL</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">5.5 Top entity</h3> - -<p>There are some restrictions on the entity being at the apex of a design -hierarchy: - - <ul> -<li>The generic must have a default value, and the value of a generic is its -default value; -<li>The ports type must be constrained. -</ul> - -<div class="node"> -<p><hr> -<a name="Using-vendor-libraries"></a> -Next: <a rel="next" accesskey="n" href="#Using-ieee_002emath_005freal-or-ieee_002emath_005fcomplex">Using ieee.math_real or ieee.math_complex</a>, -Previous: <a rel="previous" accesskey="p" href="#Top-entity">Top entity</a>, -Up: <a rel="up" accesskey="u" href="#GHDL-implementation-of-VHDL">GHDL implementation of VHDL</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">5.6 Using vendor libraries</h3> - -<p>Many vendors libraries have been analyzed with GHDL. There are -usually no problems. Be sure to use the <samp><span class="option">--work=</span></samp> option. -However, some problems have been encountered. - - <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 <samp><span class="option">--std=93c</span></samp>, <samp><span class="option">-fexplicit</span></samp> and -<samp><span class="option">--warn-no-vital-generic</span></samp>. - - <p>Even with these relaxations, some broken libraries may fail. - - <p>For example, <code>unisim_VITAL.vhd</code> from <code>Xilinx</code> can't be -compiled because lines such as: -<pre class="smallexample"> variable Write_A_Write_B : memory_collision_type := Write_A_Write_B; - variable Read_A_Write_B : memory_collision_type := Read_A_Write_B; -</pre> - <p>(there are 6 such lines). -According to VHDL visibility rules, ‘<samp><span class="samp">Write_A_Write_B</span></samp>’ cannot be used -while it is defined. This is very logical because it prevents from silly -declarations such as -<pre class="smallexample"> constant k : natural := 2 * k; -</pre> - <p>This files must be modified. Fortunately, in the example the variables -are never written. So it is enough to remove them. - -<div class="node"> -<p><hr> -<a name="Using-ieee.math_real-or-ieee.math_complex"></a> -<a name="Using-ieee_002emath_005freal-or-ieee_002emath_005fcomplex"></a> -Next: <a rel="next" accesskey="n" href="#Interfacing-to-other-languages">Interfacing to other languages</a>, -Previous: <a rel="previous" accesskey="p" href="#Using-vendor-libraries">Using vendor libraries</a>, -Up: <a rel="up" accesskey="u" href="#GHDL-implementation-of-VHDL">GHDL implementation of VHDL</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">5.7 Using ieee.math_real or ieee.math_complex</h3> - -<p><a name="index-math_005freal-111"></a><a name="index-math_005fcomplex-112"></a>Contrary to other ‘<samp><span class="samp">ieee</span></samp>’ libraries, the math packages sources are not -freely available. The sources provided with GHDL are based on an early draft -and use the C libraries. As a consequence, you should link your design -with the ‘<samp><span class="samp">libm.a</span></samp>’ library using the <samp><span class="option">-Wl,</span></samp> option like: -<pre class="smallexample"> $ ghdl -e -Wl,-lm my_design -</pre> - <p>Please, refer to your system manual for more details. - - <p>Please also note that the ‘<samp><span class="samp">ieee</span></samp>’ libraries are not the same as the drafts. - - <p>If you really need the ‘<samp><span class="samp">ieee</span></samp>’ math libraries, they are available on the -web, but they cannot be included in GHDL. - -<div class="node"> -<p><hr> -<a name="Interfacing-to-other-languages"></a> -Previous: <a rel="previous" accesskey="p" href="#Using-ieee_002emath_005freal-or-ieee_002emath_005fcomplex">Using ieee.math_real or ieee.math_complex</a>, -Up: <a rel="up" accesskey="u" href="#GHDL-implementation-of-VHDL">GHDL implementation of VHDL</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">5.8 Interfacing to other languages</h3> - -<p><a name="index-interfacing-113"></a><a name="index-other-languages-114"></a><a name="index-foreign-115"></a><a name="index-VHPI-116"></a><a name="index-VHPIDIRECT-117"></a>Interfacing with foreign languages is possible only on GNU/Linux systems. - - <p>You can define a subprogram in a foreign language (such as <code>C</code> or -<code>Ada</code>) and import it in a VHDL design. - -<h4 class="subsection">5.8.1 Foreign declarations</h4> - -<p>Only subprograms (functions or procedures) can be imported, using the foreign -attribute. In this example, the <code>sin</code> function is imported: - -<pre class="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; -</pre> - <p>A subprogram is made foreign if the <var>foreign</var> attribute decorates -it. This attribute is declared in the 1993 revision of the -‘<samp><span class="samp">std.standard</span></samp>’ package. Therefore, you cannot use this feature in -VHDL 1987. - - <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>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>The value of the attribute must start with ‘<samp><span class="samp">VHPIDIRECT </span></samp>’ (an -upper-case keyword followed by one or more blanks). The linkage name of the -subprogram follows. - -<ul class="menu"> -<li><a accesskey="1" href="#Restrictions-on-foreign-declarations">Restrictions on foreign declarations</a> -<li><a accesskey="2" href="#Linking-with-foreign-object-files">Linking with foreign object files</a> -<li><a accesskey="3" href="#Starting-a-simulation-from-a-foreign-program">Starting a simulation from a foreign program</a> -<li><a accesskey="4" href="#Linking-with-Ada">Linking with Ada</a> -<li><a accesskey="5" href="#Using-GRT-from-Ada">Using GRT from Ada</a> -</ul> - -<div class="node"> -<p><hr> -<a name="Restrictions-on-foreign-declarations"></a> -Next: <a rel="next" accesskey="n" href="#Linking-with-foreign-object-files">Linking with foreign object files</a>, -Previous: <a rel="previous" accesskey="p" href="#Interfacing-to-other-languages">Interfacing to other languages</a>, -Up: <a rel="up" accesskey="u" href="#Interfacing-to-other-languages">Interfacing to other languages</a> - -</div> - -<h4 class="subsection">5.8.2 Restrictions on foreign declarations</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: - <dl> -<dt>‘<samp><span class="samp">integer types</span></samp>’<dd>They are represented on a 32 bits word. This generally corresponds to -<code>int</code> for <code>C</code> or <code>Integer</code> for <code>Ada</code>. -<br><dt>‘<samp><span class="samp">physical types</span></samp>’<dd>They are represented on a 64 bits word. This generally corresponds to the -<code>long long</code> for <code>C</code> or <code>Long_Long_Integer</code> for <code>Ada</code>. -<br><dt>‘<samp><span class="samp">floating point types</span></samp>’<dd>They are represented on a 64 bits floating point word. This generally -corresponds to <code>double</code> for <code>C</code> or <code>Long_Float</code> for <code>Ada</code>. -<br><dt>‘<samp><span class="samp">enumeration types</span></samp>’<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. -</dl> - - <p>Non-composite types are passed by value. For the <code>in</code> mode, this -corresponds to the <code>C</code> or <code>Ada</code> mechanism. The <code>out</code> and -<code>inout</code> 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</code> and -<code>inout</code> modes in foreign subprograms, since they are not portable. - - <p>Records are represented like a <code>C</code> structure and are passed by reference -to subprograms. - - <p>Arrays with static bounds are represented like a <code>C</code> array, whose -length is the number of elements, and are passed by reference to subprograms. - - <p>Unconstrained array are represented by a fat pointer. Do not use unconstrained -arrays in foreign subprograms. - - <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>Files are represented by a 32 bits word, which corresponds to an index -in a table. - -<div class="node"> -<p><hr> -<a name="Linking-with-foreign-object-files"></a> -Next: <a rel="next" accesskey="n" href="#Starting-a-simulation-from-a-foreign-program">Starting a simulation from a foreign program</a>, -Previous: <a rel="previous" accesskey="p" href="#Restrictions-on-foreign-declarations">Restrictions on foreign declarations</a>, -Up: <a rel="up" accesskey="u" href="#Interfacing-to-other-languages">Interfacing to other languages</a> - -</div> - -<h4 class="subsection">5.8.3 Linking with foreign object files</h4> - -<p>You may add additional files or options during the link using the -<samp><span class="option">-Wl,</span></samp> of <code>GHDL</code>, as described in <a href="#Elaboration-command">Elaboration command</a>. -For example: - -<pre class="example"> $ ghdl -e -Wl,-lm math_tb -</pre> - <p>will create the <samp><span class="file">math_tb</span></samp> executable with the <samp><span class="file">lm</span></samp> (mathematical) -library. - - <p>Note the <samp><span class="file">c</span></samp> library is always linked with an executable. - -<div class="node"> -<p><hr> -<a name="Starting-a-simulation-from-a-foreign-program"></a> -Next: <a rel="next" accesskey="n" href="#Linking-with-Ada">Linking with Ada</a>, -Previous: <a rel="previous" accesskey="p" href="#Linking-with-foreign-object-files">Linking with foreign object files</a>, -Up: <a rel="up" accesskey="u" href="#Interfacing-to-other-languages">Interfacing to other languages</a> - -</div> - -<h4 class="subsection">5.8.4 Starting a simulation from a foreign program</h4> - -<p>You may run your design from an external program. You just have to call -the ‘<samp><span class="samp">ghdl_main</span></samp>’ function which can be defined: - - <p>in C: -<pre class="smallexample"> extern int ghdl_main (int argc, char **argv); -</pre> - <p>in Ada: -<pre class="smallexample"> with System; - ... - function Ghdl_Main (Argc : Integer; Argv : System.Address) - return Integer; - pragma import (C, Ghdl_Main, "ghdl_main"); -</pre> - <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. - -<div class="node"> -<p><hr> -<a name="Linking-with-Ada"></a> -Next: <a rel="next" accesskey="n" href="#Using-GRT-from-Ada">Using GRT from Ada</a>, -Previous: <a rel="previous" accesskey="p" href="#Starting-a-simulation-from-a-foreign-program">Starting a simulation from a foreign program</a>, -Up: <a rel="up" accesskey="u" href="#Interfacing-to-other-languages">Interfacing to other languages</a> - -</div> - -<h4 class="subsection">5.8.5 Linking with Ada</h4> - -<p>As explained previously in <a href="#Starting-a-simulation-from-a-foreign-program">Starting a simulation from a foreign program</a>, -you can start a simulation from an <code>Ada</code> program. However the build -process is not trivial: you have to elaborate your <code>Ada</code> program and your -<code>VHDL</code> design. - - <p>First, you have to analyze all your design files. In this example, we -suppose there is only one design file, <samp><span class="file">design.vhdl</span></samp>. -<pre class="smallexample"> $ ghdl -a design.vhdl -</pre> - <p>Then, bind your design. In this example, we suppose the entity at the -design apex is ‘<samp><span class="samp">design</span></samp>’. -<pre class="smallexample"> $ ghdl --bind design -</pre> - <p>Finally, compile, bind your <code>Ada</code> program at link it with your <code>VHDL</code> -design: -<pre class="smallexample"> $ gnatmake my_prog -largs `ghdl --list-link design` -</pre> - <div class="node"> -<p><hr> -<a name="Using-GRT-from-Ada"></a> -Previous: <a rel="previous" accesskey="p" href="#Linking-with-Ada">Linking with Ada</a>, -Up: <a rel="up" accesskey="u" href="#Interfacing-to-other-languages">Interfacing to other languages</a> - -</div> - -<!-- node-name, next, previous, up --> -<h4 class="subsection">5.8.6 Using GRT from Ada</h4> - -<blockquote> -<b>Warning:</b> This topic is only for advanced users knowing how to use <code>Ada</code> -and <code>GNAT</code>. This is provided only for reference, I have tested -this once before releasing <code>GHDL</code> 0.19 but this is not checked at -each release. -</blockquote> - - <p>The simulator kernel of <code>GHDL</code> named <dfn>GRT</dfn> is written in -<code>Ada95</code> and contains a very light and slightly adapted version -of <code>VHPI</code>. Since it is an <code>Ada</code> implementation it is -called <dfn>AVHPI</dfn>. Although being tough, you may interface to <code>AVHPI</code>. - - <p>For using <code>AVHPI</code>, you need the sources of <code>GHDL</code> and to recompile -them (at least the <code>GRT</code> library). This library is usually compiled with -a <code>No_Run_Time</code> pragma, so that the user does not need to install the -<code>GNAT</code> runtime library. However, you certainly want to use the usual -runtime library and want to avoid this pragma. For this, reset the -<var>GRT_PRAGMA_FLAG</var> variable. -<pre class="smallexample"> $ make GRT_PRAGMA_FLAG= grt-all -</pre> - <p>Since <code>GRT</code> is a self-contained library, you don't want -<code>gnatlink</code> to fetch individual object files (furthermore this -doesn't always work due to tricks used in <code>GRT</code>). For this, -remove all the object files and make the <samp><span class="file">.ali</span></samp> files read-only. -<pre class="smallexample"> $ rm *.o - $ chmod -w *.ali -</pre> - <p>You may then install the sources files and the <samp><span class="file">.ali</span></samp> files. I have never -tested this step. - - <p>You are now ready to use it. - - <p>For example, here is an example, <samp><span class="file">test_grt.adb</span></samp> which displays the top -level design name. -<pre class="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; -</pre> - <p>First, analyze and bind your design: -<pre class="smallexample"> $ ghdl -a counter.vhdl - $ ghdl --bind counter -</pre> - <p>Then build the whole: -<pre class="smallexample"> $ gnatmake test_grt -aL<var>grt_ali_path</var> -aI<var>grt_src_path</var> -largs - `ghdl --list-link counter` -</pre> - <p>Finally, run your design: -<pre class="smallexample"> $ ./test_grt - Status is 0 - Root instance name: counter -</pre> - <div class="node"> -<p><hr> -<a name="GHDL-implementation-of-VITAL"></a> -Next: <a rel="next" accesskey="n" href="#Flaws-and-bugs-report">Flaws and bugs report</a>, -Previous: <a rel="previous" accesskey="p" href="#GHDL-implementation-of-VHDL">GHDL implementation of VHDL</a>, -Up: <a rel="up" accesskey="u" href="#Top">Top</a> - -</div> - -<!-- node-name, next, previous, up --> -<h2 class="chapter">6 GHDL implementation of VITAL</h2> - -<p><a name="index-VITAL-118"></a><a name="index-IEEE-1076_002e4-119"></a><a name="index-g_t1076_002e4-120"></a>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. - -<ul class="menu"> -<li><a accesskey="1" href="#VITAL-packages">VITAL packages</a> -<li><a accesskey="2" href="#VHDL-restrictions-for-VITAL">VHDL restrictions for VITAL</a> -<li><a accesskey="3" href="#Backannotation">Backannotation</a> -<li><a accesskey="4" href="#Negative-constraint-calculation">Negative constraint calculation</a> -</ul> - -<div class="node"> -<p><hr> -<a name="VITAL-packages"></a> -Next: <a rel="next" accesskey="n" href="#VHDL-restrictions-for-VITAL">VHDL restrictions for VITAL</a>, -Previous: <a rel="previous" accesskey="p" href="#GHDL-implementation-of-VITAL">GHDL implementation of VITAL</a>, -Up: <a rel="up" accesskey="u" href="#GHDL-implementation-of-VITAL">GHDL implementation of VITAL</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">6.1 VITAL packages</h3> - -<p>The VITAL standard or IEEE 1076.4 was first published in 1995, and revised in -2000. - - <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>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). - -<div class="node"> -<p><hr> -<a name="VHDL-restrictions-for-VITAL"></a> -Next: <a rel="next" accesskey="n" href="#Backannotation">Backannotation</a>, -Previous: <a rel="previous" accesskey="p" href="#VITAL-packages">VITAL packages</a>, -Up: <a rel="up" accesskey="u" href="#GHDL-implementation-of-VITAL">GHDL implementation of VITAL</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">6.2 VHDL restrictions for VITAL</h3> - -<p>The VITAL standard (partially) implemented is the IEEE 1076.4 standard -published in 1995. - - <p>This standard defines restriction of the VHDL language usage on VITAL -model. A <dfn>VITAL model</dfn> is a design unit (entity or architecture) -decorated by the <code>VITAL_Level0</code> or <code>VITAL_Level1</code> attribute. -These attributes are defined in the <code>ieee.VITAL_Timing</code> package. - - <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>Moreover, GHDL doesn't check (yet) that timing generics are not read inside -a VITAL level 0 model prior the VITAL annotation. - - <p>The analysis of a non-conformant VITAL model fails. You can disable the -checks of VITAL restrictions with the <samp><span class="option">--no-vital-checks</span></samp>. Even when -restrictions are not checked, SDF annotation can be performed. - -<div class="node"> -<p><hr> -<a name="Backannotation"></a> -Next: <a rel="next" accesskey="n" href="#Negative-constraint-calculation">Negative constraint calculation</a>, -Previous: <a rel="previous" accesskey="p" href="#VHDL-restrictions-for-VITAL">VHDL restrictions for VITAL</a>, -Up: <a rel="up" accesskey="u" href="#GHDL-implementation-of-VITAL">GHDL implementation of VITAL</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">6.3 Backannotation</h3> - -<p><a name="index-SDF-121"></a><dfn>Backannotation</dfn> is the process of setting VITAL generics with timing -information provided by an external files. - - <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>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>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>Currently, only timing constraints applying on a timing generic of type -<code>VitalDelayType01</code> has been implemented. This SDF annotator is -just a proof of concept. Features will be added with the following GHDL -release. - -<div class="node"> -<p><hr> -<a name="Negative-constraint-calculation"></a> -Previous: <a rel="previous" accesskey="p" href="#Backannotation">Backannotation</a>, -Up: <a rel="up" accesskey="u" href="#GHDL-implementation-of-VITAL">GHDL implementation of VITAL</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">6.4 Negative constraint calculation</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>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. - -<div class="node"> -<p><hr> -<a name="Flaws-and-bugs-report"></a> -Next: <a rel="next" accesskey="n" href="#Copyrights">Copyrights</a>, -Previous: <a rel="previous" accesskey="p" href="#GHDL-implementation-of-VITAL">GHDL implementation of VITAL</a>, -Up: <a rel="up" accesskey="u" href="#Top">Top</a> - -</div> - -<!-- node-name, next, previous, up --> -<h2 class="chapter">7 Flaws and bugs report</h2> - -<p>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. - -<ul class="menu"> -<li><a accesskey="1" href="#Deficiencies">Deficiencies</a> -<li><a accesskey="2" href="#Reporting-bugs">Reporting bugs</a> -<li><a accesskey="3" href="#Future-improvements">Future improvements</a> -</ul> - -<div class="node"> -<p><hr> -<a name="Deficiencies"></a> -Next: <a rel="next" accesskey="n" href="#Reporting-bugs">Reporting bugs</a>, -Previous: <a rel="previous" accesskey="p" href="#Flaws-and-bugs-report">Flaws and bugs report</a>, -Up: <a rel="up" accesskey="u" href="#Flaws-and-bugs-report">Flaws and bugs report</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">7.1 Deficiencies</h3> - -<p>Here is the non-exhaustive list of flaws: - - <ul> -<li>So far, <code>GHDL</code> has been compiled and tested only on ‘<samp><span class="samp">i386-linux</span></samp>’ systems. -<li>Overflow detection is not yet implemented. -<li>Some constraint checks are missing. -<li>VHDL-93 is not completely implemented. -<li>There are no checks for elaboration order. -<li>This list is not exhaustive. -<li><small class="dots">...</small> -</ul> - -<div class="node"> -<p><hr> -<a name="Reporting-bugs"></a> -Next: <a rel="next" accesskey="n" href="#Future-improvements">Future improvements</a>, -Previous: <a rel="previous" accesskey="p" href="#Deficiencies">Deficiencies</a>, -Up: <a rel="up" accesskey="u" href="#Flaws-and-bugs-report">Flaws and bugs report</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">7.2 Reporting bugs</h3> - -<p>In order to improve GHDL, we welcome bugs report and suggestions for -any aspect of GHDL. Please use the bug tracker on -<<code>http://gna.org/projects/ghdl</code>>. You may also send an -email to <a href="mailto:ghdl@free.fr">ghdl@free.fr</a>. - - <p>If the compiler crashes, this is a bug. Reliable tools never crash. - - <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>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>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>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>If you send a <code>VHDL</code> 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>For bug reports, please include enough information for the maintainers to -reproduce the problem. This includes: - - <ul> -<li>the version of <code>GHDL</code> (you can get it with ‘<samp><span class="samp">ghdl --version</span></samp>’). -<li>the operating system -<li>whether you have built <code>GHDL</code> from sources or used the binary -distribution. -<li>the content of the input files -<li>a description of the problem and samples of any erroneous input -<li>anything else that you think would be helpful. -</ul> - -<div class="node"> -<p><hr> -<a name="Future-improvements"></a> -Previous: <a rel="previous" accesskey="p" href="#Reporting-bugs">Reporting bugs</a>, -Up: <a rel="up" accesskey="u" href="#Flaws-and-bugs-report">Flaws and bugs report</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">7.3 Future improvements</h3> - -<p>I have several axes for <code>GHDL</code> improvements: - <ul> -<li>Documentation. -<li>Better diagnostics messages (warning and error). -<li>Full support of VHDL-87 and VHDL-93. -<li>Support of VHDL-02. -<li>Optimization (simulation speed). -<li>Graphical tools (to see waves and to debug) -<li>Style checks -<li>VITAL acceleration -</ul> - -<!-- And without any order: --> -<!-- VHPI --> -<!-- FOREIGN --> -<!-- AMS --> -<!-- verilog --> -<div class="node"> -<p><hr> -<a name="Copyrights"></a> -Next: <a rel="next" accesskey="n" href="#Index">Index</a>, -Previous: <a rel="previous" accesskey="p" href="#Flaws-and-bugs-report">Flaws and bugs report</a>, -Up: <a rel="up" accesskey="u" href="#Top">Top</a> - -</div> - -<!-- node-name, next, previous, up --> -<h2 class="chapter">8 Copyrights</h2> - -<p>The GHDL front-end, the ‘<samp><span class="samp">std.textio</span></samp>’ package and the runtime -library (grt) are copyrighted Tristan Gingold, come with <em>absolutely -no warranty</em>, and are distributed under the conditions of the General -Public License. - - <p>The ‘<samp><span class="samp">ieee.numeric_bit</span></samp>’ and ‘<samp><span class="samp">ieee.numeric_std</span></samp>’ packages are -copyrighted by the IEEE. The source files may be distributed without -change, except as permitted by the standard. -<!-- 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. - - <p>The ‘<samp><span class="samp">ieee.std_logic_1164</span></samp>’ package is copyrighted by the IEEE. See -source file and the IEEE 1164 standard for more information. - - <p>The ‘<samp><span class="samp">ieee.VITAL_Primitives</span></samp>’, ‘<samp><span class="samp">ieee.VITAL_Timing</span></samp>’ and -‘<samp><span class="samp">ieee.VITAL_Memory</span></samp>’ packages are copyrighted by IEEE. See source -file and the IEEE 1076.4 standards for more information. - - <p>The ‘<samp><span class="samp">ieee.Math_Real</span></samp>’ and ‘<samp><span class="samp">ieee.Math_Complex</span></samp>’ 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. - - <p>The packages ‘<samp><span class="samp">std_logic_arith</span></samp>’, <!-- @samp{std_logic_misc}, --> -‘<samp><span class="samp">std_logic_signed</span></samp>’, ‘<samp><span class="samp">std_logic_unsigned</span></samp>’ and -‘<samp><span class="samp">std_logic_textio</span></samp>’ contained in the ‘<samp><span class="samp">synopsys</span></samp>’ 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>The package ‘<samp><span class="samp">std_logic_arith</span></samp>’ contained in the ‘<samp><span class="samp">mentor</span></samp>’ -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>As a consequence of the runtime copyright, you may not be allowed to -distribute an executable produced by <code>GHDL</code> 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 -(see <a href="#Reporting-bugs">Reporting bugs</a>) if you don't like this policy. - -<div class="node"> -<p><hr> -<a name="Index"></a> -Previous: <a rel="previous" accesskey="p" href="#Copyrights">Copyrights</a>, -Up: <a rel="up" accesskey="u" href="#Top">Top</a> - -</div> - -<h2 class="unnumbered">Index</h2> - -<ul class="index-cp" compact> -<li><a href="#index-g_t_0040option_007b_002d_002dassert_002dlevel_007d-option-79"><samp><span class="option">--assert-level</span></samp> option</a>: <a href="#Simulation-options">Simulation options</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dbind_007d-command-10"><samp><span class="option">--bind</span></samp> command</a>: <a href="#Bind-command">Bind command</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dchop_007d-command-67"><samp><span class="option">--chop</span></samp> command</a>: <a href="#Chop-command">Chop command</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dclean_007d-command-58"><samp><span class="option">--clean</span></samp> command</a>: <a href="#Clean-command">Clean command</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dcopy_007d-command-62"><samp><span class="option">--copy</span></samp> command</a>: <a href="#Copy-command">Copy command</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002ddisp_002dstandard_007d-command-73"><samp><span class="option">--disp-standard</span></samp> command</a>: <a href="#Disp-standard-command">Disp standard command</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002ddisp_002dtime_007d-option-83"><samp><span class="option">--disp-time</span></samp> option</a>: <a href="#Simulation-options">Simulation options</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002ddisp_002dtree_007d-option-85"><samp><span class="option">--disp-tree</span></samp> option</a>: <a href="#Simulation-options">Simulation options</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002ddispconfig_007d-command-71"><samp><span class="option">--dispconfig</span></samp> command</a>: <a href="#Dispconfig-command">Dispconfig command</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002delab_002drun_007d-command-8"><samp><span class="option">--elab-run</span></samp> command</a>: <a href="#Elaborate-and-run-command">Elaborate and run command</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dgen_002dmakefile_007d-command-54"><samp><span class="option">--gen-makefile</span></samp> command</a>: <a href="#Generate-Makefile-command">Generate Makefile command</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dGHLD1_007d-switch-36"><samp><span class="option">--GHLD1</span></samp> switch</a>: <a href="#GHDL-options">GHDL options</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dhelp_007d-command-70"><samp><span class="option">--help</span></samp> command</a>: <a href="#Help-command">Help command</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dieee_007d-switch-26"><samp><span class="option">--ieee</span></samp> switch</a>: <a href="#GHDL-options">GHDL options</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dieee_002dasserts_007d-option-80"><samp><span class="option">--ieee-asserts</span></samp> option</a>: <a href="#Simulation-options">Simulation options</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dlines_007d-command-68"><samp><span class="option">--lines</span></samp> command</a>: <a href="#Lines-command">Lines command</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dlink_007d-command-12"><samp><span class="option">--link</span></samp> command</a>: <a href="#Link-command">Link command</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dlist_002dlink_007d-command-13"><samp><span class="option">--list-link</span></samp> command</a>: <a href="#List-link-command">List link command</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dno_002drun_007d-option-87"><samp><span class="option">--no-run</span></samp> option</a>: <a href="#Simulation-options">Simulation options</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dno_002dvital_002dchecks_007d-switch-32"><samp><span class="option">--no-vital-checks</span></samp> switch</a>: <a href="#GHDL-options">GHDL options</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dpp_002dhtml_007d-command-63"><samp><span class="option">--pp-html</span></samp> command</a>: <a href="#Pretty-print-command">Pretty print command</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dPREFIX_007d-switch-35"><samp><span class="option">--PREFIX</span></samp> switch</a>: <a href="#GHDL-options">GHDL options</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dremove_007d-command-60"><samp><span class="option">--remove</span></samp> command</a>: <a href="#Remove-command">Remove command</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dsdf_007d-option-94"><samp><span class="option">--sdf</span></samp> option</a>: <a href="#Simulation-options">Simulation options</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dstack_002dmax_002dsize_007d-option-95"><samp><span class="option">--stack-max-size</span></samp> option</a>: <a href="#Simulation-options">Simulation options</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dstack_002dsize_007d-option-96"><samp><span class="option">--stack-size</span></samp> option</a>: <a href="#Simulation-options">Simulation options</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dstd_007d-switch-25"><samp><span class="option">--std</span></samp> switch</a>: <a href="#GHDL-options">GHDL options</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dstop_002ddelta_007d-option-82"><samp><span class="option">--stop-delta</span></samp> option</a>: <a href="#Simulation-options">Simulation options</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dstop_002dtime_007d-option-81"><samp><span class="option">--stop-time</span></samp> option</a>: <a href="#Simulation-options">Simulation options</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dsyn_002dbinding_007d-switch-34"><samp><span class="option">--syn-binding</span></samp> switch</a>: <a href="#GHDL-options">GHDL options</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dvcd_007d-option-88"><samp><span class="option">--vcd</span></samp> option</a>: <a href="#Simulation-options">Simulation options</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dvcdgz_007d-option-89"><samp><span class="option">--vcdgz</span></samp> option</a>: <a href="#Simulation-options">Simulation options</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dversion_007d-command-75"><samp><span class="option">--version</span></samp> command</a>: <a href="#Version-command">Version command</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dvital_002dchecks_007d-switch-33"><samp><span class="option">--vital-checks</span></samp> switch</a>: <a href="#GHDL-options">GHDL options</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dwarn_002dbinding_007d-switch-42"><samp><span class="option">--warn-binding</span></samp> switch</a>: <a href="#GHDL-warnings">GHDL warnings</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dwarn_002dbody_007d-switch-46"><samp><span class="option">--warn-body</span></samp> switch</a>: <a href="#GHDL-warnings">GHDL warnings</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dwarn_002ddefault_002dbinding_007d-switch-41"><samp><span class="option">--warn-default-binding</span></samp> switch</a>: <a href="#GHDL-warnings">GHDL warnings</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dwarn_002ddelayed_002dchecks_007d-switch-45"><samp><span class="option">--warn-delayed-checks</span></samp> switch</a>: <a href="#GHDL-warnings">GHDL warnings</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dwarn_002derror_007d-switch-49"><samp><span class="option">--warn-error</span></samp> switch</a>: <a href="#GHDL-warnings">GHDL warnings</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dwarn_002dlibrary_007d-switch-43"><samp><span class="option">--warn-library</span></samp> switch</a>: <a href="#GHDL-warnings">GHDL warnings</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dwarn_002dreserved_007d-switch-40"><samp><span class="option">--warn-reserved</span></samp> switch</a>: <a href="#GHDL-warnings">GHDL warnings</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dwarn_002dspecs_007d-switch-47"><samp><span class="option">--warn-specs</span></samp> switch</a>: <a href="#GHDL-warnings">GHDL warnings</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dwarn_002dunused_007d-switch-48"><samp><span class="option">--warn-unused</span></samp> switch</a>: <a href="#GHDL-warnings">GHDL warnings</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dwarn_002dvital_002dgeneric_007d-switch-44"><samp><span class="option">--warn-vital-generic</span></samp> switch</a>: <a href="#GHDL-warnings">GHDL warnings</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dwave_007d-option-93"><samp><span class="option">--wave</span></samp> option</a>: <a href="#Simulation-options">Simulation options</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dwork_007d-switch-22"><samp><span class="option">--work</span></samp> switch</a>: <a href="#GHDL-options">GHDL options</a></li> -<li><a href="#index-g_t_0040option_007b_002d_002dworkdir_007d-switch-24"><samp><span class="option">--workdir</span></samp> switch</a>: <a href="#GHDL-options">GHDL options</a></li> -<li><a href="#index-g_t_0040option_007b_002da_007d-command-2"><samp><span class="option">-a</span></samp> command</a>: <a href="#Analysis-command">Analysis command</a></li> -<li><a href="#index-g_t_0040option_007b_002dc_007d-command-17"><samp><span class="option">-c</span></samp> command</a>: <a href="#Analyze-and-elaborate-command">Analyze and elaborate command</a></li> -<li><a href="#index-g_t_0040option_007b_002dd_007d-command-56"><samp><span class="option">-d</span></samp> command</a>: <a href="#Directory-command">Directory command</a></li> -<li><a href="#index-g_t_0040option_007b_002de_007d-command-4"><samp><span class="option">-e</span></samp> command</a>: <a href="#Elaboration-command">Elaboration command</a></li> -<li><a href="#index-g_t_0040option_007b_002df_007d-command-66"><samp><span class="option">-f</span></samp> command</a>: <a href="#Find-command">Find command</a></li> -<li><a href="#index-g_t_0040option_007b_002dfexplicit_007d-switch-31"><samp><span class="option">-fexplicit</span></samp> switch</a>: <a href="#GHDL-options">GHDL options</a></li> -<li><a href="#index-g_t_0040option_007b_002dh_007d-command-69"><samp><span class="option">-h</span></samp> command</a>: <a href="#Help-command">Help command</a></li> -<li><a href="#index-g_t_0040option_007b_002di_007d-command-51"><samp><span class="option">-i</span></samp> command</a>: <a href="#Import-command">Import command</a></li> -<li><a href="#index-g_t_0040option_007b_002dm_007d-command-53"><samp><span class="option">-m</span></samp> command</a>: <a href="#Make-command">Make command</a></li> -<li><a href="#index-g_t_0040option_007b_002dP_007d-switch-30"><samp><span class="option">-P</span></samp> switch</a>: <a href="#GHDL-options">GHDL options</a></li> -<li><a href="#index-g_t_0040option_007b_002dr_007d-command-6"><samp><span class="option">-r</span></samp> command</a>: <a href="#Run-command">Run command</a></li> -<li><a href="#index-g_t_0040option_007b_002ds_007d-command-15"><samp><span class="option">-s</span></samp> command</a>: <a href="#Check-syntax-command">Check syntax command</a></li> -<li><a href="#index-g_t_0040option_007b_002dW_007d-switch-37"><samp><span class="option">-W</span></samp> switch</a>: <a href="#Passing-options-to-other-programs">Passing options to other programs</a></li> -<li><a href="#index-g_t_0040option_007b_002dWa_007d-switch-38"><samp><span class="option">-Wa</span></samp> switch</a>: <a href="#Passing-options-to-other-programs">Passing options to other programs</a></li> -<li><a href="#index-g_t_0040option_007b_002dWl_007d-switch-39"><samp><span class="option">-Wl</span></samp> switch</a>: <a href="#Passing-options-to-other-programs">Passing options to other programs</a></li> -<li><a href="#index-g_t1076-102">1076</a>: <a href="#VHDL-standards">VHDL standards</a></li> -<li><a href="#index-g_t1076_002e3-21">1076.3</a>: <a href="#GHDL-options">GHDL options</a></li> -<li><a href="#index-g_t1076_002e4-120">1076.4</a>: <a href="#GHDL-implementation-of-VITAL">GHDL implementation of VITAL</a></li> -<li><a href="#index-g_t1076a-103">1076a</a>: <a href="#VHDL-standards">VHDL standards</a></li> -<li><a href="#index-g_t1164-19">1164</a>: <a href="#GHDL-options">GHDL options</a></li> -<li><a href="#index-g_t_0040code_007b_005f_005fghdl_005ffatal_007d-98"><code>__ghdl_fatal</code></a>: <a href="#Debugging-VHDL-programs">Debugging VHDL programs</a></li> -<li><a href="#index-analysis-1">analysis</a>: <a href="#Analysis-command">Analysis command</a></li> -<li><a href="#index-Analyze-and-elaborate-command-16">Analyze and elaborate command</a>: <a href="#Analyze-and-elaborate-command">Analyze and elaborate command</a></li> -<li><a href="#index-binding-9">binding</a>: <a href="#Bind-command">Bind command</a></li> -<li><a href="#index-checking-syntax-14">checking syntax</a>: <a href="#Check-syntax-command">Check syntax command</a></li> -<li><a href="#index-cleaning-57">cleaning</a>: <a href="#Clean-command">Clean command</a></li> -<li><a href="#index-cleaning-all-59">cleaning all</a>: <a href="#Remove-command">Remove command</a></li> -<li><a href="#index-copying-library-61">copying library</a>: <a href="#Copy-command">Copy command</a></li> -<li><a href="#index-debugging-97">debugging</a>: <a href="#Debugging-VHDL-programs">Debugging VHDL programs</a></li> -<li><a href="#index-display-configuration-72">display configuration</a>: <a href="#Dispconfig-command">Dispconfig command</a></li> -<li><a href="#index-display-design-hierarchy-86">display design hierarchy</a>: <a href="#Simulation-options">Simulation options</a></li> -<li><a href="#index-display-_0040samp_007bstd_002estandard_007d-74">display ‘<samp><span class="samp">std.standard</span></samp>’</a>: <a href="#Disp-standard-command">Disp standard command</a></li> -<li><a href="#index-display-time-84">display time</a>: <a href="#Simulation-options">Simulation options</a></li> -<li><a href="#index-displaying-library-55">displaying library</a>: <a href="#Directory-command">Directory command</a></li> -<li><a href="#index-dump-of-signals-92">dump of signals</a>: <a href="#Simulation-options">Simulation options</a></li> -<li><a href="#index-elaborate-and-run-7">elaborate and run</a>: <a href="#Elaborate-and-run-command">Elaborate and run command</a></li> -<li><a href="#index-elaboration-3">elaboration</a>: <a href="#Elaboration-command">Elaboration command</a></li> -<li><a href="#index-file-format-109">file format</a>: <a href="#VHDL-files-format">VHDL files format</a></li> -<li><a href="#index-foreign-115">foreign</a>: <a href="#Interfacing-to-other-languages">Interfacing to other languages</a></li> -<li><a href="#index-IEEE-1076-100">IEEE 1076</a>: <a href="#VHDL-standards">VHDL standards</a></li> -<li><a href="#index-IEEE-1076_002e3-20">IEEE 1076.3</a>: <a href="#GHDL-options">GHDL options</a></li> -<li><a href="#index-IEEE-1076_002e4-119">IEEE 1076.4</a>: <a href="#GHDL-implementation-of-VITAL">GHDL implementation of VITAL</a></li> -<li><a href="#index-IEEE-1076a-101">IEEE 1076a</a>: <a href="#VHDL-standards">VHDL standards</a></li> -<li><a href="#index-IEEE-1164-18">IEEE 1164</a>: <a href="#GHDL-options">GHDL options</a></li> -<li><a href="#index-ieee-library-27">ieee library</a>: <a href="#GHDL-options">GHDL options</a></li> -<li><a href="#index-importing-files-50">importing files</a>: <a href="#Import-command">Import command</a></li> -<li><a href="#index-interfacing-113">interfacing</a>: <a href="#Interfacing-to-other-languages">Interfacing to other languages</a></li> -<li><a href="#index-linking-11">linking</a>: <a href="#Link-command">Link command</a></li> -<li><a href="#index-logical-name-110">logical name</a>: <a href="#VHDL-files-format">VHDL files format</a></li> -<li><a href="#index-make-52">make</a>: <a href="#Make-command">Make command</a></li> -<li><a href="#index-math_005fcomplex-112">math_complex</a>: <a href="#Using-ieee_002emath_005freal-or-ieee_002emath_005fcomplex">Using ieee.math_real or ieee.math_complex</a></li> -<li><a href="#index-Math_005fComplex-78">Math_Complex</a>: <a href="#IEEE-math-packages">IEEE math packages</a></li> -<li><a href="#index-math_005freal-111">math_real</a>: <a href="#Using-ieee_002emath_005freal-or-ieee_002emath_005fcomplex">Using ieee.math_real or ieee.math_complex</a></li> -<li><a href="#index-Math_005fReal-77">Math_Real</a>: <a href="#IEEE-math-packages">IEEE math packages</a></li> -<li><a href="#index-mentor-library-29">mentor library</a>: <a href="#GHDL-options">GHDL options</a></li> -<li><a href="#index-other-languages-114">other languages</a>: <a href="#Interfacing-to-other-languages">Interfacing to other languages</a></li> -<li><a href="#index-pretty-printing-64">pretty printing</a>: <a href="#Pretty-print-command">Pretty print command</a></li> -<li><a href="#index-run-5">run</a>: <a href="#Run-command">Run command</a></li> -<li><a href="#index-SDF-121">SDF</a>: <a href="#Backannotation">Backannotation</a></li> -<li><a href="#index-synopsys-library-28">synopsys library</a>: <a href="#GHDL-options">GHDL options</a></li> -<li><a href="#index-v00-107">v00</a>: <a href="#VHDL-standards">VHDL standards</a></li> -<li><a href="#index-v02-108">v02</a>: <a href="#VHDL-standards">VHDL standards</a></li> -<li><a href="#index-v87-104">v87</a>: <a href="#VHDL-standards">VHDL standards</a></li> -<li><a href="#index-v93-105">v93</a>: <a href="#VHDL-standards">VHDL standards</a></li> -<li><a href="#index-v93c-106">v93c</a>: <a href="#VHDL-standards">VHDL standards</a></li> -<li><a href="#index-value-change-dump-91">value change dump</a>: <a href="#Simulation-options">Simulation options</a></li> -<li><a href="#index-vcd-90">vcd</a>: <a href="#Simulation-options">Simulation options</a></li> -<li><a href="#index-version-76">version</a>: <a href="#Version-command">Version command</a></li> -<li><a href="#index-VHDL-standards-99">VHDL standards</a>: <a href="#VHDL-standards">VHDL standards</a></li> -<li><a href="#index-vhdl-to-html-65">vhdl to html</a>: <a href="#Pretty-print-command">Pretty print command</a></li> -<li><a href="#index-VHPI-116">VHPI</a>: <a href="#Interfacing-to-other-languages">Interfacing to other languages</a></li> -<li><a href="#index-VHPIDIRECT-117">VHPIDIRECT</a>: <a href="#Interfacing-to-other-languages">Interfacing to other languages</a></li> -<li><a href="#index-VITAL-118">VITAL</a>: <a href="#GHDL-implementation-of-VITAL">GHDL implementation of VITAL</a></li> -<li><a href="#index-WORK-library-23">WORK library</a>: <a href="#GHDL-options">GHDL options</a></li> - </ul></body></html> - diff --git a/doc/ghdl.texi b/doc/ghdl.texi deleted file mode 100644 index 4abb3974f..000000000 --- a/doc/ghdl.texi +++ /dev/null @@ -1,2591 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename ghdl.info -@settitle GHDL guide -@c %**end of header - -@direntry -* ghdl: (ghdl). VHDL compiler. -@end direntry - -@titlepage -@title GHDL guide -@subtitle GHDL, a VHDL compiler -@subtitle For GHDL version 0.32 (Dunoon edition) -@author Tristan Gingold -@c The following two commands start the copyright page. -@page -@vskip 0pt plus 1filll -Copyright @copyright{} 2002-2014 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 (runtime 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, Introduction, (dir), (dir) -@top GHDL guide -GHDL, a VHDL compiler. - -Copyright @copyright{} 2002-2014 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 runtime:: -* 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 Windows(TM) version of @code{GHDL} is not based on @code{GCC} but on -an internal code generator. - -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, as well as @code{ghw} files to be viewed by -@samp{gtkwave}. - -@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 creates or updates a file @file{work-obj93.cf}, which -describes the library @samp{work}. On GNU/Linux, this command generates a -file @file{hello.o}, which is the object file corresponding to your -VHDL program. The object file is not created on Windows. - -Then, you have to build an executable file. -@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. - -On GNU/Linux, 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 - -On Windows, no file is created. The simulation is launched using this command: -@smallexample -> ghdl -r hello_world -@end smallexample - -The result of the simulation appears on the screen: -@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 runtime 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. A copy is kept on -@indicateurl{http://ghdl.free.fr/dlx.tar.gz} - -First, untar the sources: -@smallexample -$ tar zxvf dlx.tar.gz -@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 runtime, 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 slightly 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:: -* Installation Directory:: -* IEEE library pitfalls:: -* IEEE math packages:: -@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 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). -@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 - -On GNU/Linux 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 hierarchy. On Windows this -command elaborates the design but does not generate anything. - -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. - -On GNU/Linux the filename of the executable is the name of the -primary unit, or for the later case, the concatenation of the name of -the primary unit, a dash, and the name of the secondary unit (or -architecture). On Windows there is no executable generated. - -The @option{-o} followed by a filename can override the default -executable filename. - -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 -runtime library. - -The actual elaboration is performed at runtime. - -On Windows this command can be skipped because it is also done by the -run command. - -@node Run command, Elaborate and run command, Elaboration command, Building commands -@comment node-name, next, previous, up -@subsection Run command -@cindex run -@cindex @option{-r} command -Run (or simulate) a design. - -@smallexample -$ ghdl -r [@var{options}] @var{primary_unit} [@var{secondary_unit}] [@var{simulation_options}] -@end smallexample - -The options and arguments are the same as for the elaboration command, @pxref{Elaboration command}. - -On GNU/Linux this command simply determines the filename of the executable -and executes it. Options are ignored. You may also directly execute -the program. - -This command exists for three reasons: -@itemize @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 works with the Windows implementation, where the code is generated in -memory. -@end itemize - -On Windows this command elaborates and launches the simulation. As a consequence -you must use the same options used during analysis. - -@xref{Simulation and runtime}, 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 command is only available on GNU/Linux. - -This performs only the first stage of the elaboration command; the list -of objects files is created but the executable is not built. This -command should be used only when the main entry point is not ghdl. - -@node Link command, List link command, Bind command, Building commands -@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 completeness. The elaboration command is -equivalent to the bind command followed by the link command. - -@node List link command, Check syntax command, Link command, Building commands -@subsection List link command -@cindex @option{--list-link} command -Display files which will be linked. - -@smallexample -$ ghdl --list-link @var{primary_unit} [@var{secondary_unit}] -@end smallexample - -This command is only available on GNU/Linux. - -This command may be used only after a bind command. GHDL displays all -the files which will be linked to create an executable. This command is -intended to add object files in a link of a foreign program. - -@node Check syntax command, Analyze and elaborate command, List link command, Building commands -@subsection Check syntax command -@cindex checking syntax -@cindex @option{-s} command -Analyze files but do not generate code. - -@smallexample -$ ghdl -s [@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 them at the same time. - -On GNU/Linux: -@smallexample -$ ghdl -c [@var{options}] @var{file}@dots{} -e @var{primary_unit} [@var{secondary_unit}] -@end smallexample - -On Windows: -@smallexample -$ ghdl -c [@var{options}] @var{file}@dots{} -r @var{primary_unit} [@var{secondary_unit}] -@end smallexample - -This command combines analysis and elaboration: @var{file}s are analyzed and -the unit is then elaborated. However, code is only generated during the -elaboration. On Windows the simulation is launched. - -To be more precise, the files are first parsed, and then the elaboration -drives the analysis. Therefore, there is no analysis order, and you don't -need to care about it. - -All the units of the files are put into the @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 traditional approach (analyze and then elaborate) are: -@itemize -@item -The compilation cycle is achieved in one command. -@item -Since the files are only parsed once, the compilation cycle may be faster. -@item -You don't need to know an analysis order -@item -This command produces smaller executable, since unused units and subprograms -do not generate code. -@end itemize -However, you should know that currently most of the time is spent in code -generation and the analyze and elaborate command generate code for all units -needed, even units of @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 traditional 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 whether @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 forbid you to add units to the @samp{std} library. -Furthermore, you should not put units in the @samp{ieee} library. - -@item --workdir=@var{DIR} -@cindex @option{--workdir} switch -Specify the directory where the @samp{WORK} library is located. 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. - -Use option @option{-P} to specify where libraries other than @samp{WORK} -are placed. - -@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 additional 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 permission from the @sc{ieee}. - -@item mentor -Supply the standard packages and the following additional package: -@samp{std_logic_arith}. The package is a slight variation of a definitely -not standard but widely mis-used package. -@end table - -To avoid errors, you must use the same @code{IEEE} library for all units of -your design, and during elaboration. - -@item -P@var{DIRECTORY} -@cindex @option{-P} switch -Add @var{DIRECTORY} 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 latter -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 overridden in another package. You'd better to fix -your design and use the @samp{numeric_std} package. - -@item -frelaxed-rules -@cindex @option{-frelaxed-rules} switch -Within an object declaration, allow to reference the name (which -references the hidden declaration). This ignores the error in the -following code: - -@example -package pkg1 is - type state is (state1, state2, state3); -end pkg1; - -use work.pkg1.all; -package pkg2 is - constant state1 : state := state1; -end pkg2; -@end example - -Some code (such as Xilinx packages) have such constructs, which -are valid. - -(The scope of the @samp{state1} constant start at the @code{constant} -word. Because the constant @samp{state1} and the enumeration literal -@samp{state1} are homograph, the enumeration literal is hidden in the -immediate scope of the constant). - -@item -fpsl -@cindex @option{-fpsl} switch -Enable parsing of PSL assertions within comments. @xref{PSL implementation}, -for more details. - -@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 --syn-binding -@cindex @option{--syn-binding} switch -Use synthesizer rules for component binding. During elaboration, if a -component is not bound to an entity using VHDL LRM rules, try to find -in any known library an entity whose name is the same as the component -name. - -This rule is known as synthesizer rule. - -There are two key points: normal VHDL LRM rules are tried first and -entities are searched only in known library. A known library is a -library which has been named in your design. - -This option is only useful during elaboration. - -@item --PREFIX=@var{PATH} -@cindex @option{--PREFIX} switch -Use @var{PATH} as the prefix path to find commands and pre-installed (std and -ieee) libraries. - -@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 - -These options are only available on GNU/Linux. - -For many commands, @code{GHDL} acts as a driver: it invokes programs to perform -the command. You can pass arbitrary options to these programs. - -Both the compiler and the linker are in fact GCC programs. @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 constructions are not erroneous but dubious. Warnings are diagnostic -messages that report such constructions. Some warnings are reported only -during analysis, others during elaboration. - -You could disable a warning by using the @option{--warn-no-XXX} -instead of @option{--warn-XXX}. - -@table @code -@item --warn-reserved -@cindex @option{--warn-reserved} switch -Emit a warning if an identifier is a reserved word in a later 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 useful 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 the conditional -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. This is because not all procedure -bodies are available during analysis (either because a package body -has not yet been analysed or because @code{GHDL} doesn't read not required -package bodies). - -These are checks for no wait statement in a procedure called in a -sensitized process and checks for pure rules of a function. - -@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 several files can be tricky, -due to dependencies. GHDL has a few commands to rebuild a design. - -@menu -* Import command:: -* Make command:: -* Generate Makefile command:: -@end menu - -@node Import command, Make command, Rebuilding commands, Rebuilding commands -@comment node-name, next, previous, up -@subsection Import command -@cindex importing files -@cindex @option{-i} command -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 to 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 hierarchy -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 dependencies of the design hierarchy, are analyzed. -If necessary, the design hierarchy is elaborated. - -This is not perfect, since the default architecture (the most recently -analyzed one) may change while outdated design files are analyzed. In -such a case, re-run the make command of GHDL. - -@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:: -* Copy command:: -* Create a Library:: -@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, Copy 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 Copy command, Create a Library, Remove command, Library commands -@subsection Copy command -@cindex copying library -@cindex @option{--copy} command -Make a local copy of an existing library. - -@smallexample -$ ghdl --copy --work=@var{name} [@var{options}] -@end smallexample - -Make a local copy of an existing library. This is very useful if you want to -add unit to the @samp{ieee} library: -@example -$ ghdl --copy --work=ieee --ieee=synopsys -$ ghdl -a --work=ieee numeric_unsigned.vhd -@end example - -@node Create a Library, , Copy command, Library commands -@subsection Create a Library -@cindex create your own library - -A new library is created by compiling entities (packages etc.) into it. - -@smallexample -ghdl -a --work=my_custom_lib my_file.vhd -@end smallexample - -A library's source code is usually stored and compiled into its own directory, -that you specify with the --workdir option. - -@smallexample -ghdl -a --work=my_custom_lib --workdir=my_custom_libdir my_custom_lib_srcdir/my_file.vhd -@end smallexample - -See also the -PPATH command line option. - -@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 analysis 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{<FONT>} 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 information. - -@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 several files. They do not analyze -files, therefore, they work even if a file has semantic errors. - -@menu -* Pretty print command:: -* Find command:: -* Chop command:: -* Lines command:: -@end menu - -@node Pretty print command, Find command, File commands, 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 incomplete 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 through @samp{<FONT>} 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 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 @file{NAME.vhdl}, where @var{NAME} is the name of the design -unit. For a package body, the filename is @file{NAME-body.vhdl}. -Finally, for an architecture @var{ARCH} of an entity @var{ENTITY}, the -filename 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, Installation Directory, 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:: -* Disp config command:: -* Disp standard command:: -* Version command:: -@end menu - -@node Help command, Disp config 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 a command switch, then options -for this later command are displayed. - -@smallexample -$ ghdl --help -$ ghdl -h -$ ghdl -h @var{command} -@end smallexample - -@node Disp config command, Disp standard command, Help command, Misc commands -@comment node-name, next, previous, up -@subsection Disp config command -@cindex @option{--disp-config} command -@cindex display configuration -Display the program paths and options used by GHDL. - -@smallexample -$ ghdl --disp-config [@var{options}] -@end smallexample - -This may be useful to track installation errors. - -@node Disp standard command, Version command, Disp config 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 Installation Directory, IEEE library pitfalls, Misc commands, Invoking GHDL -@comment node-name, next, previous, up -@section Installation Directory -@c @code{GHDL} is installed with the @code{std} and @code{ieee} libraries. -During analysis and elaboration @code{GHDL} may read the @code{std} -and @code{ieee} files. The location of these files is based on the prefix, -which is (in priority order): -@enumerate -@item -the @option{--PREFIX=} command line option - -@item -the @var{GHDL_PREFIX} environment variable - -@item -a built-in default path. It is a hard-coded path on GNU/Linux and the -value of the @samp{HKLM\Software\Ghdl\Install_Dir} registry entry on Windows. -@end enumerate - -You should use the @option{--disp-config} command (@pxref{Disp config command} for details) to disp and debug installation problems. - -@node IEEE library pitfalls, IEEE math packages, Installation Directory, 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 are slight differences -between the packages of Mentor and those of Synopsys. - -Furthermore, since they are not well-thought, their use has pitfalls. For -example, this description has error during compilation: -@example -library ieee; -use ieee.std_logic_1164.all; - --- @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 an element to element comparison, the second one is an -explicit declared function, with the semantic of an unsigned comparison. - -With some analyser, the explicit declaration has priority over the implicit -declaration, and this design can be analyzed without error. However, this -is not the rule given by the VHDL LRM, and since GHDL follows these rules, -it emits an error. - -You can force GHDL to use this rule with the @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 functionalities: -@example -library ieee; -use ieee.numeric_std.all; - -architecture good of counter -is - signal v : unsigned (3 downto 0); -begin - process (ck, rst) - begin - if rst = '1' then - v <= x"0"; - elsif rising_edge (ck) then - if v = "1010" then - v <= x"0"; - else - v <= v + 1; - end if; - end if; - end process; - - val <= std_logic_vector (v); -end good; -@end example - -@node IEEE math packages, , IEEE library pitfalls, Invoking GHDL -@comment node-name, next, previous, up -@section IEEE math packages -@cindex Math_Real -@cindex Math_Complex - -The @samp{ieee} math packages (@samp{math_real} and -@samp{math_complex}) provided with @code{GHDL} are fully compliant with -the @code{IEEE} standard. - -@node Simulation and runtime, GHDL implementation of VHDL, Invoking GHDL, Top -@comment node-name, next, previous, up -@chapter Simulation and runtime - -@menu -* Simulation options:: -* Debugging VHDL programs:: -@end menu - -@node Simulation options, Debugging VHDL programs, Simulation and runtime, Simulation and runtime -@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 languages, there is no -standard method in VHDL to obtain the arguments or to set the exit -status. - -In GHDL, it is impossible to pass parameters to your design. A later version -could do it through the generics interfaces of the top entity. - -However, the GHDL runtime behaviour can be modified with some options; for -example, it is possible to stop simulation after a certain time. - -The exit status of the simulation is @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 --ieee-asserts=@var{POLICY} -@cindex @option{--ieee-asserts} option -Select how the assertions from @samp{ieee} units are -handled. @var{POLICY} can be @samp{enable} (the default), -@samp{disable} which disables all assertion from @samp{ieee} packages -and @samp{disable-at-0} which disables only at start of simulation. - -This option can be useful to avoid assertion message from -@samp{ieee.numeric_std} (and other @samp{ieee} packages). - -@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} -@item --vcdgz=@var{FILENAME} -@cindex @option{--vcd} option -@cindex @option{--vcdgz} option -@cindex vcd -@cindex value change dump -@cindex dump of signals -@option{--vcd} dumps 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. - -The @option{--vcdgz} option is the same as the @option{--vcd} option, -but the output is compressed using the @code{zlib} (@code{gzip} -compression). However, you can't use the @samp{-} filename. -Furthermore, only one VCD file can be written. - -@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 --fst=@var{FILENAME} -@cindex @option{--fst} option -Write the waveforms into a @code{fst}, that can be displayed by -@code{gtkwave}. The @code{fst} files are much smaller than VCD or -@code{GHW} files, but it handles only the same signals as the VCD format. - -@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 completely fixed. -It may change slightly. The @samp{gtkwave} tool can read the GHW 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 --help -Display a short description of the options accepted by the runtime library. -@end table - -@node Debugging VHDL programs, , Simulation options, Simulation and runtime -@comment node-name, next, previous, up -@section Debugging VHDL programs -@cindex debugging -@cindex @code{__ghdl_fatal} -Debugging VHDL programs using @code{GDB} is possible only on GNU/Linux systems. - -@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 runtime error, such as indexing -an array beyond its bounds. All error check subprograms call the -@code{__ghdl_fatal} procedure. Therefore, to catch runtime 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 runtime, 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:: -* PSL implementation:: -* Source representation:: -* Library database:: -* VHDL files format:: -* Top entity:: -* Using vendor libraries:: -* Interfacing to other languages:: -@end menu - -@node VHDL standards, PSL implementation, 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. - -Unfortunately, VHDL-93 is not fully compatible with VHDL-87, i.e. some perfectly -valid VHDL-87 programs are invalid VHDL-93 programs. Here are some of the -reasons: - -@itemize @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 slightly 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 particularly 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 -completely analyzed using either the 87 or the 93 version of the VHDL standard. - -@node PSL implementation, Source representation, VHDL standards, GHDL implementation of VHDL -@comment node-name, next, previous, up -@section PSL implementation -GHDL understands embedded PSL annotations in VHDL files, but not in -separate files. - -As PSL annotations are embedded within comments, you must analyze and elaborate -your design with option @option{-fpsl} to enable PSL annotations. - -A PSL assertion statement must appear within a comment that starts -with the @code{psl} keyword. The keyword must be followed (on the -same line) by a PSL keyword such as @code{assert} or @code{default}. -To continue a PSL statement on the next line, just start a new comment. - -A PSL statement is considered as a process. So it is not allowed within -a process. - -All PSL assertions must be clocked (GHDL doesn't support unclocked assertion). -Furthermore only one clock per assertion is allowed. - -You can either use a default clock like this: -@example - -- psl default clock is rising_edge (CLK); - -- psl assert always - -- a -> eventually! b; -@end example -or use a clocked expression (note the use of parenthesis): -@example - -- psl assert (always a -> next[3](b)) @@rising_edge (clk); -@end example - -Of course only the simple subset of PSL is allowed. - -Currently the built-in functions are not implemented. - -@node Source representation, Library database, PSL implementation, GHDL implementation of VHDL -@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 filename may not contain any control character or -spaces). - -GHDL do not keep a binary representation of the design units analyzed like -other VHDL analyzers. The sources of the design units are re-read when -needed (for example, an entity is re-read when one of its architecture is -analyzed). Therefore, if you delete or modify a source file of a unit -analyzed, GHDL will refuse to use it. - -@node Library database, 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 dependencies. - -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 filename) to an operating -system filename. 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 filename 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, Using vendor libraries, 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 Using vendor libraries, Interfacing to other languages, Top entity, GHDL implementation of VHDL -@comment node-name, next, previous, up -@section Using vendor libraries -Many vendors libraries have been analyzed with GHDL. There are -usually no problems. Be sure to use the @option{--work=} option. -However, some problems have been encountered. - -GHDL follows the VHDL LRM (the manual which defines VHDL) more -strictly than other VHDL tools. You could try to relax the -restrictions by using the @option{--std=93c}, @option{-fexplicit}, -@option{-frelaxed-rules} and @option{--warn-no-vital-generic}. - -@node Interfacing to other languages, , Using vendor libraries, GHDL implementation of VHDL -@comment node-name, next, previous, up -@section Interfacing to other languages -@cindex interfacing -@cindex other languages -@cindex foreign -@cindex VHPI -@cindex VHPIDIRECT -Interfacing with foreign languages is possible only on GNU/Linux systems. - -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 achieved through an attribute specification. The -attribute specification must be in the same declarative part as the -subprogram and must be after it. This is a general rule for specifications. -The value of the specification must be a locally static string. - -Even when a subprogram is foreign, its body must be present. However, since -it won't be called, you can made it empty or simply but an assertion. - -The value of the attribute must start with @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 obscure. 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 correspond to an address and are passed to a subprogram like other non-composite types. - -Files are represented by a 32 bits word, which corresponds to an index -in a table. - -@node Linking with foreign object files, Starting a simulation from a foreign program, Restrictions on foreign declarations, Interfacing to other languages -@subsection Linking with foreign object files -You may add additional 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 may 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 slightly 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} runtime library. However, you certainly want to use the usual -runtime 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 slightly modified so that they conform to -the VHDL 1993 standard (a few functions are made pure and a few one -impure). - -@node VHDL restrictions for VITAL, Backannotation, VITAL packages, GHDL implementation of VITAL -@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 label, and -the celltype must be the name of the component declaration instantiated. - -Instances being annotated are not required to be VITAL compliant. However -generics being annotated must follow rules of VITAL (e.g., type must be a -suitable vital delay type). - -Currently, only timing constraints applying on a timing generic of type -@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 adjustment are necessary to handle negative -constraint such as a negative setup time. This step is defined in the VITAL -standard and should occur after backannotation. - -GHDL does not do negative constraint calculation. It fails to handle models -with negative constraint. I hope to be able to add this phase soon. - -@node Flaws and bugs report, Copyrights, GHDL implementation of VITAL, Top -@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 constraint checks are missing. -@item -VHDL-93 is not completely 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 use the bug tracker on -@indicateurl{http://gna.org/projects/ghdl}. You may also send an -email 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 -runtime or the code produced may be wrong. However, since VHDL -has a notion of pointers, an erroneous VHDL program (using invalid -pointers for example) may crash. - -If the compiler emits an error message for a perfectly valid input or -does not emit an error message for an invalid input, this may be a bug. -Please send the input file and what you expected. If you know the LRM -well enough, please specify the paragraph which has not been well -implemented. If you don't know the LRM, maybe your bug report will be -rejected simply because there is no bug. In the latter case, it may be -difficult to discuss the issue; and comparisons with other VHDL tools -is not a very strong argument. - -If a compiler message is not clear enough for you, please tell me. The -error messages can be improved, but I have not enough experience with -them. - -If you have found a mistake in the manual, please send a comment. If -you have not understood some parts of this manual, please tell me. -English is not my mother tongue, so this manual may not be well-written. -Again, rewriting part of it is a good way to improve it. - -If you send a @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 whether the file -should compile, and if yes, whether or not it should run successfully. -In the latter case, an assert statement should finish the test; the -severity level note indicates success, while a severity level failure -indicates failure. - -For bug reports, please include enough information for the maintainers to -reproduce the problem. This includes: - -@itemize @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 runtime -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 runtime 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 diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 000000000..fef600002 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,28 @@ +.. GHDL documentation master file, created by + sphinx-quickstart on Fri Nov 20 20:33:03 2015. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to GHDL's documentation! +================================ + +Contents: + +.. toctree:: + :maxdepth: 2 + + Introduction + Starting_with_GHDL + Invoking_GHDL + Simulation_and_runtime + GHDL_implementation_of_VHDL + GHDL_implementation_of_VITAL + Flaws_and_bugs_report + Copyrights + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` + |