From e9f9a248facfcb9f249e7817bbc1264e2ea1ca32 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Sun, 19 Feb 2017 04:57:17 +0100 Subject: New documentation structure for GHDL. --- doc/0_Intro/.gitempty | 0 doc/0_Intro/Contributing.rst | 6 + doc/0_Intro/WhatIsGHDL.rst | 29 + doc/0_Intro/WhatIsVHDL.rst | 29 + doc/1_Using/InvokingGHDL.rst | 6 + doc/1_Using/QuickStartGuide.rst | 6 + doc/1_Using/Simulation.rst | 6 + doc/2_Releases/index.rst | 6 + doc/3_Building/index.rst | 6 + doc/4_References/CommandReference.rst | 6 + doc/4_References/ImplementationOfVHDL.rst | 6 + doc/4_References/ImplementationOfVITAL.rst | 6 + doc/Copyrights.rst | 45 - doc/Flaws_and_bugs_report.rst | 72 -- doc/GHDL_implementation_of_VHDL.rst | 485 ---------- doc/GHDL_implementation_of_VITAL.rst | 92 -- doc/Introduction.rst | 73 -- doc/Invoking_GHDL.rst | 1293 -------------------------- doc/Simulation_and_runtime.rst | 292 ------ doc/Starting_with_GHDL.rst | 356 ------- doc/X_ChangeLog/2014/index.rst | 20 + doc/X_ChangeLog/2014/v0.30.rst | 4 + doc/X_ChangeLog/2015/index.rst | 20 + doc/X_ChangeLog/2015/v0.31.rst | 4 + doc/X_ChangeLog/2016/index.rst | 22 + doc/X_ChangeLog/2016/v0.32.rst | 4 + doc/X_ChangeLog/2016/v0.33.rst | 4 + doc/X_ChangeLog/2017/index.rst | 20 + doc/X_ChangeLog/2017/v0.34.rst | 4 + doc/X_ChangeLog/index.rst | 24 + doc/_extensions/.gitempty | 0 doc/_static/icons/.gitempty | 0 doc/_static/images/.gitempty | 0 doc/_static/logos/GitHub-Mark-32px.png | Bin 0 -> 1714 bytes doc/conf.py | 52 +- doc/genindex.rst | 4 + doc/index.rst | 149 ++- doc/make.ps1 | 242 +++++ doc/old_Copyrights.rst.txt | 45 + doc/old_Flaws_and_bugs_report.rst.txt | 72 ++ doc/old_GHDL_implementation_of_VHDL.rst.txt | 485 ++++++++++ doc/old_GHDL_implementation_of_VITAL.rst.txt | 92 ++ doc/old_Introduction.rst.txt | 73 ++ doc/old_Invoking_GHDL.rst.txt | 1293 ++++++++++++++++++++++++++ doc/old_Simulation_and_runtime.rst.txt | 292 ++++++ doc/old_Starting_with_GHDL.rst.txt | 356 +++++++ doc/old_index.rst.txt | 28 + 47 files changed, 3396 insertions(+), 2733 deletions(-) create mode 100644 doc/0_Intro/.gitempty create mode 100644 doc/0_Intro/Contributing.rst create mode 100644 doc/0_Intro/WhatIsGHDL.rst create mode 100644 doc/0_Intro/WhatIsVHDL.rst create mode 100644 doc/1_Using/InvokingGHDL.rst create mode 100644 doc/1_Using/QuickStartGuide.rst create mode 100644 doc/1_Using/Simulation.rst create mode 100644 doc/2_Releases/index.rst create mode 100644 doc/3_Building/index.rst create mode 100644 doc/4_References/CommandReference.rst create mode 100644 doc/4_References/ImplementationOfVHDL.rst create mode 100644 doc/4_References/ImplementationOfVITAL.rst delete mode 100644 doc/Copyrights.rst delete mode 100644 doc/Flaws_and_bugs_report.rst delete mode 100644 doc/GHDL_implementation_of_VHDL.rst delete mode 100644 doc/GHDL_implementation_of_VITAL.rst delete mode 100644 doc/Introduction.rst delete mode 100644 doc/Invoking_GHDL.rst delete mode 100644 doc/Simulation_and_runtime.rst delete mode 100644 doc/Starting_with_GHDL.rst create mode 100644 doc/X_ChangeLog/2014/index.rst create mode 100644 doc/X_ChangeLog/2014/v0.30.rst create mode 100644 doc/X_ChangeLog/2015/index.rst create mode 100644 doc/X_ChangeLog/2015/v0.31.rst create mode 100644 doc/X_ChangeLog/2016/index.rst create mode 100644 doc/X_ChangeLog/2016/v0.32.rst create mode 100644 doc/X_ChangeLog/2016/v0.33.rst create mode 100644 doc/X_ChangeLog/2017/index.rst create mode 100644 doc/X_ChangeLog/2017/v0.34.rst create mode 100644 doc/X_ChangeLog/index.rst create mode 100644 doc/_extensions/.gitempty create mode 100644 doc/_static/icons/.gitempty create mode 100644 doc/_static/images/.gitempty create mode 100644 doc/_static/logos/GitHub-Mark-32px.png create mode 100644 doc/genindex.rst create mode 100644 doc/make.ps1 create mode 100644 doc/old_Copyrights.rst.txt create mode 100644 doc/old_Flaws_and_bugs_report.rst.txt create mode 100644 doc/old_GHDL_implementation_of_VHDL.rst.txt create mode 100644 doc/old_GHDL_implementation_of_VITAL.rst.txt create mode 100644 doc/old_Introduction.rst.txt create mode 100644 doc/old_Invoking_GHDL.rst.txt create mode 100644 doc/old_Simulation_and_runtime.rst.txt create mode 100644 doc/old_Starting_with_GHDL.rst.txt create mode 100644 doc/old_index.rst.txt (limited to 'doc') diff --git a/doc/0_Intro/.gitempty b/doc/0_Intro/.gitempty new file mode 100644 index 000000000..e69de29bb diff --git a/doc/0_Intro/Contributing.rst b/doc/0_Intro/Contributing.rst new file mode 100644 index 000000000..7a9b4fe75 --- /dev/null +++ b/doc/0_Intro/Contributing.rst @@ -0,0 +1,6 @@ +.. _INTRO:Contributing: + +Contributing +############ + + diff --git a/doc/0_Intro/WhatIsGHDL.rst b/doc/0_Intro/WhatIsGHDL.rst new file mode 100644 index 000000000..449ef5d01 --- /dev/null +++ b/doc/0_Intro/WhatIsGHDL.rst @@ -0,0 +1,29 @@ +.. include:: + +.. _INTRO:GHDL: + +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\ |trade| 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/0_Intro/WhatIsVHDL.rst b/doc/0_Intro/WhatIsVHDL.rst new file mode 100644 index 000000000..b78ddda9a --- /dev/null +++ b/doc/0_Intro/WhatIsVHDL.rst @@ -0,0 +1,29 @@ +.. _INTRO:VHDL: + +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 behavior, 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. diff --git a/doc/1_Using/InvokingGHDL.rst b/doc/1_Using/InvokingGHDL.rst new file mode 100644 index 000000000..559b9f84e --- /dev/null +++ b/doc/1_Using/InvokingGHDL.rst @@ -0,0 +1,6 @@ +.. _USING:Invoking: + +Invoking GHDL +############# + + diff --git a/doc/1_Using/QuickStartGuide.rst b/doc/1_Using/QuickStartGuide.rst new file mode 100644 index 000000000..098749ec4 --- /dev/null +++ b/doc/1_Using/QuickStartGuide.rst @@ -0,0 +1,6 @@ +.. _USING:QuickStart: + +Quick Start Guide +################# + + diff --git a/doc/1_Using/Simulation.rst b/doc/1_Using/Simulation.rst new file mode 100644 index 000000000..0246c20f4 --- /dev/null +++ b/doc/1_Using/Simulation.rst @@ -0,0 +1,6 @@ +.. _USING:Simulation: + +Simulation +########## + + diff --git a/doc/2_Releases/index.rst b/doc/2_Releases/index.rst new file mode 100644 index 000000000..9e06f65af --- /dev/null +++ b/doc/2_Releases/index.rst @@ -0,0 +1,6 @@ +.. _RELEASE: + +Releases +######## + + diff --git a/doc/3_Building/index.rst b/doc/3_Building/index.rst new file mode 100644 index 000000000..98468fd7f --- /dev/null +++ b/doc/3_Building/index.rst @@ -0,0 +1,6 @@ +.. _BUILD: + +Building GHDL +############# + + diff --git a/doc/4_References/CommandReference.rst b/doc/4_References/CommandReference.rst new file mode 100644 index 000000000..ed7869dba --- /dev/null +++ b/doc/4_References/CommandReference.rst @@ -0,0 +1,6 @@ +.. _REF:Command: + +Command Reference +################# + + diff --git a/doc/4_References/ImplementationOfVHDL.rst b/doc/4_References/ImplementationOfVHDL.rst new file mode 100644 index 000000000..aa2940c30 --- /dev/null +++ b/doc/4_References/ImplementationOfVHDL.rst @@ -0,0 +1,6 @@ +.. _REF:ImplVHDL: + +Building GHDL +############# + + diff --git a/doc/4_References/ImplementationOfVITAL.rst b/doc/4_References/ImplementationOfVITAL.rst new file mode 100644 index 000000000..959058a2d --- /dev/null +++ b/doc/4_References/ImplementationOfVITAL.rst @@ -0,0 +1,6 @@ +.. _REF:ImplVITAL: + +Building GHDL +############# + + diff --git a/doc/Copyrights.rst b/doc/Copyrights.rst deleted file mode 100644 index 038a9291b..000000000 --- a/doc/Copyrights.rst +++ /dev/null @@ -1,45 +0,0 @@ -********** -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 deleted file mode 100644 index d4b269dc2..000000000 --- a/doc/Flaws_and_bugs_report.rst +++ /dev/null @@ -1,72 +0,0 @@ -********************* -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 deleted file mode 100644 index 5df2ec5d1..000000000 --- a/doc/GHDL_implementation_of_VHDL.rst +++ /dev/null @@ -1,485 +0,0 @@ -*************************** -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 - -.. index:: v08 - -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. - -The latest version is 2008. Many features have been added, and GHDL -doesn't implement all of them. - -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). - -The 93, 93c, 00 and 02 standards are considered as compatible: you can -elaborate a design mixing these standards. However, 87, 93 and 08 are -not compatible. - -.. _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, -93 or 08) 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 deleted file mode 100644 index 675510048..000000000 --- a/doc/GHDL_implementation_of_VITAL.rst +++ /dev/null @@ -1,92 +0,0 @@ -**************************** -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 deleted file mode 100644 index 135c8cb28..000000000 --- a/doc/Introduction.rst +++ /dev/null @@ -1,73 +0,0 @@ -************ -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 deleted file mode 100644 index f1f1c2e59..000000000 --- a/doc/Invoking_GHDL.rst +++ /dev/null @@ -1,1293 +0,0 @@ -************* -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. - -If the number of options is large and the command line length is -beyond the system limit, you can use a response file. An argument that -starts with a :samp:`@` is considered as a response file; it is replaced -by arguments read from the file (separated by blanks and end of line). - -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 several 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, if the GCC backend was enabled during the compilation of `GHDL`, -the elaboration command creates an executable containing the code of the `VHDL` -sources, the elaboration code and simulation code to execute a design -hierarchy. The executable is created in the current directory. -On Windows or if the GCC backend was not enabled, 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. The executable must be in the current directory. - -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. A library is searched in `DIRECTORY` and also in - `DIRECTORY/LIB/vVV` (where `LIB` is the name of the library and `VV` - the vhdl standard). - - 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). - - This option also relaxes the rules about pure functions. Violations - result in warnings instead of errors. - - -.. 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 searched in the path. - - -.. option:: --AS= - - Use :samp:`COMMAND` as the command name for the assembler. If :samp:`COMMAND` is - not a path, then it is searched in the path. The default is :samp:`as`. - - -.. option:: --LINK= - - Use :samp:`COMMAND` as the linker driver. If :samp:`COMMAND` is - not a path, then it is searched in the path. The default is :samp:`gcc`. - - -.. 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,