From 60fd762fa36f72b9ddad8cda84b6c16c6936d942 Mon Sep 17 00:00:00 2001 From: Tristan Gingold Date: Sat, 21 Nov 2015 05:54:42 +0100 Subject: Convert documentation to sphinx. --- doc/Copyrights.rst | 45 + doc/Flaws_and_bugs_report.rst | 72 + doc/GHDL_implementation_of_VHDL.rst | 479 ++++++ doc/GHDL_implementation_of_VITAL.rst | 92 ++ doc/Introduction.rst | 73 + doc/Invoking_GHDL.rst | 1114 +++++++++++++ doc/Simulation_and_runtime.rst | 239 +++ doc/Starting_with_GHDL.rst | 355 ++++ doc/conf.py | 284 ++++ doc/ghdl.html | 3032 ---------------------------------- doc/ghdl.texi | 2591 ----------------------------- doc/index.rst | 28 + 12 files changed, 2781 insertions(+), 5623 deletions(-) create mode 100644 doc/Copyrights.rst create mode 100644 doc/Flaws_and_bugs_report.rst create mode 100644 doc/GHDL_implementation_of_VHDL.rst create mode 100644 doc/GHDL_implementation_of_VITAL.rst create mode 100644 doc/Introduction.rst create mode 100644 doc/Invoking_GHDL.rst create mode 100644 doc/Simulation_and_runtime.rst create mode 100644 doc/Starting_with_GHDL.rst create mode 100644 doc/conf.py delete mode 100644 doc/ghdl.html delete mode 100644 doc/ghdl.texi create mode 100644 doc/index.rst (limited to 'doc') 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= + + .. 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= + + 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= + + 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= + + .. 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 + + 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= + + Use :file:`PATH` as the prefix path to find commands and pre-installed (std and + ieee) libraries. + + +.. option:: --GHDL1= + + 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,