From 45dfdf3444abe623b4eab42cd1553c8e4b56f139 Mon Sep 17 00:00:00 2001 From: 1138-4EB <1138-4EB@users.noreply.github.com> Date: Sun, 19 Feb 2017 05:42:34 +0100 Subject: Moving old content to new structure --- doc/0_Intro/.gitempty | 0 doc/0_Intro/Contributing.rst | 71 ++ doc/0_Intro/Copyrights.rst | 55 ++ doc/0_Intro/WhatIsVHDL.rst | 4 + doc/1_Using/InvokingGHDL.rst | 1277 ++++++++++++++++++++++++- doc/1_Using/QuickStartGuide.rst | 355 ++++++- doc/1_Using/Simulation.rst | 290 +++++- doc/2_Getting/Docker.rst | 6 + doc/2_Getting/Releases.rst | 6 + doc/2_Releases/index.rst | 6 - doc/3_Building/VendorPrimitives.rst | 317 +++++++ doc/4_References/ImplementationOfVHDL.rst | 485 +++++++++- doc/4_References/ImplementationOfVITAL.rst | 92 +- doc/X_ChangeLog/Roadmap.rst.txt | 14 + doc/index.rst | 77 +- 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 ------- 23 files changed, 3000 insertions(+), 2763 deletions(-) delete mode 100644 doc/0_Intro/.gitempty create mode 100644 doc/0_Intro/Copyrights.rst create mode 100644 doc/2_Getting/Docker.rst create mode 100644 doc/2_Getting/Releases.rst delete mode 100644 doc/2_Releases/index.rst create mode 100644 doc/3_Building/VendorPrimitives.rst create mode 100644 doc/X_ChangeLog/Roadmap.rst.txt delete mode 100644 doc/old_Copyrights.rst.txt delete mode 100644 doc/old_Flaws_and_bugs_report.rst.txt delete mode 100644 doc/old_GHDL_implementation_of_VHDL.rst.txt delete mode 100644 doc/old_GHDL_implementation_of_VITAL.rst.txt delete mode 100644 doc/old_Introduction.rst.txt delete mode 100644 doc/old_Invoking_GHDL.rst.txt delete mode 100644 doc/old_Simulation_and_runtime.rst.txt delete mode 100644 doc/old_Starting_with_GHDL.rst.txt diff --git a/doc/0_Intro/.gitempty b/doc/0_Intro/.gitempty deleted file mode 100644 index e69de29bb..000000000 diff --git a/doc/0_Intro/Contributing.rst b/doc/0_Intro/Contributing.rst index 7a9b4fe75..8a0ba30bc 100644 --- a/doc/0_Intro/Contributing.rst +++ b/doc/0_Intro/Contributing.rst @@ -3,4 +3,75 @@ Contributing ############ +Despite all the testing and already reported `issues `_, you can find bugs +or propose enhancements. + .. _reporting_bugs: + +Asking for enhancements +============== + +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 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. + +Documentation +============== + +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. + +--- + +@TODO: + +- Reporting bugs + - [1138: Issues, search first] + - Minimum-(non)-Working-Example (MWE) +- Pull Requests (PRs) + - [1138: check chapter 2 -> building -> GHDL -> directory structure] + - [1138: beware that some commit messages can `automatically close `_ PRs] \ No newline at end of file diff --git a/doc/0_Intro/Copyrights.rst b/doc/0_Intro/Copyrights.rst new file mode 100644 index 000000000..1684fb035 --- /dev/null +++ b/doc/0_Intro/Copyrights.rst @@ -0,0 +1,55 @@ +.. _INTRO:Copyrights: + +Copyrights | License +############ + +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. + +--- + +@TODO: + +https://www.gnu.org/licenses/old-licenses/gpl-2.0.html + +Available in the following formats: plain text, Texinfo, LaTeX, standalone HTML, Docbook, Markdown, ODF, RT + +See `#280 `_ \ No newline at end of file diff --git a/doc/0_Intro/WhatIsVHDL.rst b/doc/0_Intro/WhatIsVHDL.rst index b78ddda9a..fbf0dbd73 100644 --- a/doc/0_Intro/WhatIsVHDL.rst +++ b/doc/0_Intro/WhatIsVHDL.rst @@ -27,3 +27,7 @@ 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. + +--- + +@TODO: [1138: very very briefly explain that there are four major verions: 87, 93, 02 and 08] \ No newline at end of file diff --git a/doc/1_Using/InvokingGHDL.rst b/doc/1_Using/InvokingGHDL.rst index 559b9f84e..d4bcda438 100644 --- a/doc/1_Using/InvokingGHDL.rst +++ b/doc/1_Using/InvokingGHDL.rst @@ -1,6 +1,1281 @@ .. _USING:Invoking: +************* 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). + +Design 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,