From 4c1118d130c5b2dd8aef5ef486138db002dcfda7 Mon Sep 17 00:00:00 2001
From: 1138-4EB <1138-4EB@users.noreply.github.com>
Date: Sun, 19 Feb 2017 08:12:30 +0100
Subject: Removed numbers from folder names.
---
doc/0_Intro/Contributing.rst | 77 --
doc/0_Intro/Copyrights.rst | 55 --
doc/0_Intro/WhatIsGHDL.rst | 29 -
doc/0_Intro/WhatIsVHDL.rst | 35 -
doc/1_Using/InvokingGHDL.rst | 1281 ----------------------------
doc/1_Using/QuickStartGuide.rst | 359 --------
doc/1_Using/Simulation.rst | 292 -------
doc/2_Getting/Docker.rst | 31 -
doc/2_Getting/Releases.rst | 8 -
doc/3_Building/VendorPrimitives.rst | 328 -------
doc/3_Building/index.rst | 42 -
doc/4_References/CommandReference.rst | 6 -
doc/4_References/ImplementationOfVHDL.rst | 487 -----------
doc/4_References/ImplementationOfVITAL.rst | 94 --
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/Roadmap.rst | 14 -
doc/X_ChangeLog/index.rst | 30 -
doc/building/VendorPrimitives.rst | 328 +++++++
doc/building/index.rst | 42 +
doc/changelog/2014/index.rst | 20 +
doc/changelog/2014/v0.30.rst | 4 +
doc/changelog/2015/index.rst | 20 +
doc/changelog/2015/v0.31.rst | 4 +
doc/changelog/2016/index.rst | 22 +
doc/changelog/2016/v0.32.rst | 4 +
doc/changelog/2016/v0.33.rst | 4 +
doc/changelog/2017/index.rst | 20 +
doc/changelog/2017/v0.34.rst | 4 +
doc/changelog/Roadmap.rst | 14 +
doc/changelog/index.rst | 30 +
doc/getting/Docker.rst | 31 +
doc/getting/Releases.rst | 8 +
doc/intro/Contributing.rst | 77 ++
doc/intro/Copyrights.rst | 55 ++
doc/intro/WhatIsGHDL.rst | 29 +
doc/intro/WhatIsVHDL.rst | 35 +
doc/old_index.rst.txt | 28 -
doc/references/CommandReference.rst | 6 +
doc/references/ImplementationOfVHDL.rst | 487 +++++++++++
doc/references/ImplementationOfVITAL.rst | 94 ++
doc/using/InvokingGHDL.rst | 1281 ++++++++++++++++++++++++++++
doc/using/QuickStartGuide.rst | 359 ++++++++
doc/using/Simulation.rst | 292 +++++++
51 files changed, 3270 insertions(+), 3298 deletions(-)
delete mode 100644 doc/0_Intro/Contributing.rst
delete mode 100644 doc/0_Intro/Copyrights.rst
delete mode 100644 doc/0_Intro/WhatIsGHDL.rst
delete mode 100644 doc/0_Intro/WhatIsVHDL.rst
delete mode 100644 doc/1_Using/InvokingGHDL.rst
delete mode 100644 doc/1_Using/QuickStartGuide.rst
delete mode 100644 doc/1_Using/Simulation.rst
delete mode 100644 doc/2_Getting/Docker.rst
delete mode 100644 doc/2_Getting/Releases.rst
delete mode 100644 doc/3_Building/VendorPrimitives.rst
delete mode 100644 doc/3_Building/index.rst
delete mode 100644 doc/4_References/CommandReference.rst
delete mode 100644 doc/4_References/ImplementationOfVHDL.rst
delete mode 100644 doc/4_References/ImplementationOfVITAL.rst
delete mode 100644 doc/X_ChangeLog/2014/index.rst
delete mode 100644 doc/X_ChangeLog/2014/v0.30.rst
delete mode 100644 doc/X_ChangeLog/2015/index.rst
delete mode 100644 doc/X_ChangeLog/2015/v0.31.rst
delete mode 100644 doc/X_ChangeLog/2016/index.rst
delete mode 100644 doc/X_ChangeLog/2016/v0.32.rst
delete mode 100644 doc/X_ChangeLog/2016/v0.33.rst
delete mode 100644 doc/X_ChangeLog/2017/index.rst
delete mode 100644 doc/X_ChangeLog/2017/v0.34.rst
delete mode 100644 doc/X_ChangeLog/Roadmap.rst
delete mode 100644 doc/X_ChangeLog/index.rst
create mode 100644 doc/building/VendorPrimitives.rst
create mode 100644 doc/building/index.rst
create mode 100644 doc/changelog/2014/index.rst
create mode 100644 doc/changelog/2014/v0.30.rst
create mode 100644 doc/changelog/2015/index.rst
create mode 100644 doc/changelog/2015/v0.31.rst
create mode 100644 doc/changelog/2016/index.rst
create mode 100644 doc/changelog/2016/v0.32.rst
create mode 100644 doc/changelog/2016/v0.33.rst
create mode 100644 doc/changelog/2017/index.rst
create mode 100644 doc/changelog/2017/v0.34.rst
create mode 100644 doc/changelog/Roadmap.rst
create mode 100644 doc/changelog/index.rst
create mode 100644 doc/getting/Docker.rst
create mode 100644 doc/getting/Releases.rst
create mode 100644 doc/intro/Contributing.rst
create mode 100644 doc/intro/Copyrights.rst
create mode 100644 doc/intro/WhatIsGHDL.rst
create mode 100644 doc/intro/WhatIsVHDL.rst
delete mode 100644 doc/old_index.rst.txt
create mode 100644 doc/references/CommandReference.rst
create mode 100644 doc/references/ImplementationOfVHDL.rst
create mode 100644 doc/references/ImplementationOfVITAL.rst
create mode 100644 doc/using/InvokingGHDL.rst
create mode 100644 doc/using/QuickStartGuide.rst
create mode 100644 doc/using/Simulation.rst
diff --git a/doc/0_Intro/Contributing.rst b/doc/0_Intro/Contributing.rst
deleted file mode 100644
index 8a0ba30bc..000000000
--- a/doc/0_Intro/Contributing.rst
+++ /dev/null
@@ -1,77 +0,0 @@
-.. _INTRO:Contributing:
-
-Contributing
-############
-
-Despite all the testing and already reported `issues <https://github.com/tgingold/ghdl/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 <https://help.github.com/articles/closing-issues-via-commit-messages/>`_ PRs]
\ No newline at end of file
diff --git a/doc/0_Intro/Copyrights.rst b/doc/0_Intro/Copyrights.rst
deleted file mode 100644
index 06cc7e4a9..000000000
--- a/doc/0_Intro/Copyrights.rst
+++ /dev/null
@@ -1,55 +0,0 @@
-.. _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: topic
-
- 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 <https://github.com/tgingold/ghdl/issues/280#issuecomment-279595802>`_
\ No newline at end of file
diff --git a/doc/0_Intro/WhatIsGHDL.rst b/doc/0_Intro/WhatIsGHDL.rst
deleted file mode 100644
index 449ef5d01..000000000
--- a/doc/0_Intro/WhatIsGHDL.rst
+++ /dev/null
@@ -1,29 +0,0 @@
-.. include:: <isonum.txt>
-
-.. _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
deleted file mode 100644
index b70b3a723..000000000
--- a/doc/0_Intro/WhatIsVHDL.rst
+++ /dev/null
@@ -1,35 +0,0 @@
-.. _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.
-
-----------------
-
-.. TODO: topic
-
- @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
deleted file mode 100644
index d4bcda438..000000000
--- a/doc/1_Using/InvokingGHDL.rst
+++ /dev/null
@@ -1,1281 +0,0 @@
-.. _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=<NAME>
-
- .. index:: WORK library
-
- Specify the name of the :samp:`WORK` library. Analyzed units are always
- placed in the library logically named :samp:`WORK`. With this option,
- you can set its name. By default, the name is :samp:`work`.
-
- `GHDL` checks whether :samp:`WORK` is a valid identifier. Although being
- more or less supported, the :samp:`WORK` identifier should not be an
- extended identifier, since the filesystem may prevent it from correctly
- working (due to case sensitivity or forbidden characters in filenames).
-
- `VHDL` rules forbid you to add units to the :samp:`std` library.
- Furthermore, you should not put units in the :samp:`ieee` library.
-
-
-.. option:: --workdir=<DIR>
-
- Specify the directory where the :samp:`WORK` library is located. When this
- option is not present, the :samp:`WORK` library is in the current
- directory. The object files created by the compiler are always placed
- in the same directory as the :samp:`WORK` library.
-
- Use option :option:`-P` to specify where libraries other than :samp:`WORK`
- are placed.
-
-
-.. option:: --std=<STD>
-
- Specify the standard to use. By default, the standard is :samp:`93c`, which
- means VHDL-93 accepting VHDL-87 syntax. For details on :samp:`STD` values see
- :ref:`VHDL_standards`.
-
-
-.. option:: --ieee=<VER>
-
- .. index:: ieee library
- .. index:: synopsys library
- .. index:: mentor library
-
- Select the :samp:`IEEE` library to use. :samp:`VER` must be one of:
-
- none
- Do not supply an `IEEE` library. Any library clause with the :samp:`IEEE`
- identifier will fail, unless you have created by your own a library with
- the `IEEE` name.
-
- standard
- Supply an `IEEE` library containing only packages defined by
- :samp:`ieee` standards. Currently, there are the multivalue logic system
- packages :samp:`std_logic_1164` defined by IEEE 1164, the synthesis
- packages , :samp:`numeric_bit` and :samp:`numeric_std` defined by IEEE
- 1076.3, and the :samp:`vital` packages :samp:`vital_timing` and
- :samp:`vital_primitives`, defined by IEEE 1076.4. The version of these
- packages is defined by the VHDL standard used. See :ref:`VITAL_packages`,
- for more details.
-
- synopsys
- Supply the former packages and the following additional packages:
- :samp:`std_logic_arith`, :samp:`std_logic_signed`,
- :samp:`std_logic_unsigned`, :samp:`std_logic_textio`.
-
- These packages were created by some companies, and are popular. However
- they are not standard packages, and have been placed in the `IEEE`
- library without the permission from the :samp:`ieee`.
-
- mentor
- Supply the standard packages and the following additional package:
- :samp:`std_logic_arith`. The package is a slight variation of a definitely
- not standard but widely mis-used package.
-
- To avoid errors, you must use the same `IEEE` library for all units of
- your design, and during elaboration.
-
-
-.. option:: -P<DIRECTORY>
-
- Add `DIRECTORY` to the end of the list of directories to be searched for
- library files. 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=<PATH>
-
- Use :file:`PATH` as the prefix path to find commands and pre-installed (std and
- ieee) libraries.
-
-
-.. option:: --GHDL1=<COMMAND>
-
- Use :samp:`COMMAND` as the command name for the compiler. If :samp:`COMMAND` is
- not a path, then it is searched in the path.
-
-
-.. option:: --AS=<COMMAND>
-
- 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=<COMMAND>
-
- 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,<OPTION>
-
- Pass `OPTION` as an option to the compiler.
-
-
-.. option:: -Wa,<OPTION>
-
- Pass `OPTION` as an option to the assembler.
-
-
-.. option:: -Wl,<OPTION>
-
- Pass `OPTION` as an option to the linker.
-
-GHDL Diagnostics Control
-========================
-
-.. option:: -fcolor-diagnostics
-.. option:: -fno-color-diagnostics
-
- Control whether diagnostic messages are displayed in color. The
- default is on when the standard output is a terminal.
-
-.. option:: -fdiagnostics-show-option
-.. option:: -fno-diagnostics-show-option
-
- Control whether the warning option is displayed at the end of
- warning messages, so that user can easily know how to disable it.
-
-
-GHDL warnings
-=============
-
-Some constructions are not erroneous but dubious. Warnings are diagnostic
-messages that report such constructions. Some warnings are reported only
-during analysis, others during elaboration.
-
-You could disable a warning by using the :samp:`--warn-no-XXX` or
-:samp:`-Wno-XX` instead of :samp:`--warn-XXX` or :samp:`-WXXX`.
-
-
-.. option:: --warn-reserved
-
- Emit a warning if an identifier is a reserved word in a later VHDL standard.
-
-
-.. option:: --warn-default-binding
-
- During analyze, warns if a component instantiation has neither
- configuration specification nor default binding. This may be useful if you
- want to detect during analyze possibly unbound component if you don't use
- configuration. :ref:`VHDL_standards`, for more details about default binding
- rules.
-
-
-.. option:: --warn-binding
-
- During elaboration, warns if a component instantiation is not bound
- (and not explicitly left unbound). Also warns if a port of an entity
- is not bound in a configuration specification or in a component
- configuration. This warning is enabled by default, since default
- binding rules are somewhat complex and an unbound component is most
- often unexpected.
-
- However, warnings are even emitted if a component instantiation is
- inside a generate statement. As a consequence, if you use the conditional
- generate statement to select a component according to the implementation,
- you will certainly get warnings.
-
-
-.. option:: --warn-library
-
- Warns if a design unit replaces another design unit with the same name.
-
-
-.. option:: --warn-vital-generic
-
- Warns if a generic name of a vital entity is not a vital generic name. This
- is set by default.
-
-
-.. option:: --warn-delayed-checks
-
- Warns for checks that cannot be done during analysis time and are
- postponed to elaboration time. This is because not all procedure
- bodies are available during analysis (either because a package body
- has not yet been analysed or because `GHDL` doesn't read not required
- package bodies).
-
- These are checks for no wait statement in a procedure called in a
- sensitized process and checks for pure rules of a function.
-
-
-.. option:: --warn-body
-
- Emit a warning if a package body which is not required is analyzed. If a
- package does not declare a subprogram or a deferred constant, the package
- does not require a body.
-
-
-.. option:: --warn-specs
-
- Emit a warning if an all or others specification does not apply.
-
-
-.. option:: --warn-unused
-
- Emit a warning when a subprogram is never used.
-
-
-.. option:: --warn-error
-
- When this option is set, warnings are considered as errors.
-
-
-.. option:: --warn-nested-comment
-
- Emit a warning if a :samp:`/*` appears within a block comment (vhdl 2008).
-
-
-.. option:: --warn-parenthesis
-
- Emit a warning in case of weird use of parenthesis
-
-
-.. option:: --warn-runtime-error
-
- Emit a warning in case of runtime error that is detected during
- analysis.
-
-
-Rebuilding commands
-===================
-
-Analyzing and elaborating a design consisting in several files can be tricky,
-due to dependencies. GHDL has a few commands to rebuild a design.
-
-Import command
---------------
-
-.. index:: importing files
-
-.. index:: -i command
-
-Add files in the work design library::
-
- ghdl -i [options] file...
-
-
-All the files specified in the command line are scanned, parsed and added in
-the libraries but as not yet analyzed. No object files are created.
-
-The purpose of this command is to localize design units in the design files.
-The make command will then be able to recursively build a hierarchy from
-an entity name or a configuration name.
-
-Since the files are parsed, there must be correct files. However, since they
-are not analyzed, many errors are tolerated by this command.
-
-Note that all the files are added to the work library. If you have many
-libraries, you must use the command for each library.
-
-See :ref:`Make_command`, to actually build the design.
-
-.. _Make_command:
-
-Make command
-------------
-
-.. index:: make
-
-.. index:: -m command
-
-
-Analyze automatically outdated files and elaborate a design::
-
- ghdl -m [options] primary [secondary]
-
-
-The primary unit denoted by the :samp:`primary` argument must already be
-known by the system, either because you have already analyzed it (even
-if you have modified it) or because you have imported it. GHDL analyzes
-all outdated files. A file may be outdated because it has been modified
-(e.g. you just have edited it), or because a design unit contained in
-the file depends on a unit which is outdated. This rule is of course
-recursive.
-
-With the @code{-b} (bind only) option, GHDL will stop before the final linking
-step. This is useful when the main entry point is not GHDL and you're linking
-GHDL object files into a foreign program.
-
-With the :option:`-f` (force) option, GHDL analyzes all the units of the
-work library needed to create the design hierarchy. Not outdated units
-are recompiled. This is useful if you want to compile a design hierarchy
-with new compilation flags (for example, to add the *-g*
-debugging option).
-
-The make command will only re-analyze design units in the work library.
-GHDL fails if it has to analyze an outdated unit from another library.
-
-The purpose of this command is to be able to compile a design without prior
-knowledge of file order. In the VHDL model, some units must be analyzed
-before others (e.g. an entity before its architecture). It might be a
-nightmare to analyze a full design of several files, if you don't have
-the ordered list of file. This command computes an analysis order.
-
-The make command fails when a unit was not previously parsed. For
-example, if you split a file containing several design units into
-several files, you must either import these new files or analyze them so
-that GHDL knows in which file these units are.
-
-The make command imports files which have been modified. Then, a design
-hierarchy is internally built as if no units are outdated. Then, all outdated
-design units, using the dependencies of the design hierarchy, are analyzed.
-If necessary, the design hierarchy is elaborated.
-
-This is not perfect, since the default architecture (the most recently
-analyzed one) may change while outdated design files are analyzed. In
-such a case, re-run the make command of GHDL.
-
-Generate Makefile command
--------------------------
-
-.. index:: --gen-makefile command
-
-Generate a Makefile to build a design unit::
-
- ghdl --gen-makefile [options] primary [secondary]
-
-
-This command works like the make command (see :ref:`Make_command`), but only a
-makefile is generated on the standard output.
-
-Library commands
-================
-
-GHDL has a few commands which act on a library.
-
-Directory command
------------------
-
-.. index:: displaying library
-
-.. index:: --dir command
-.. option::--dir
-
-Display the name of the units contained in a design library::
-
- ghdl --dir [options] [libs]
-
-The directory command, selected with the `--dir` command line argument
-displays the content of the design libraries (by default the
-:samp:`work` library). All options are
-allowed, but only a few are meaningful: :option:`--work=NAME`,
-:option:`--workdir=PATH` and :option:`--std=VER`.
-
-Clean command
--------------
-
-.. index:: cleaning
-
-.. index:: --clean command
-
-Remove object and executable files but keep the library::
-
- ghdl --clean [options]
-
-
-GHDL tries to remove any object, executable or temporary file it could
-have created. Source files are not removed.
-
-There is no short command line form for this option to prevent accidental
-clean up.
-
-.. _Remove_command:
-
-Remove command
---------------
-
-.. index:: cleaning all
-
-.. index:: --remove command
-
-Do like the clean command but remove the library too::
-
- ghdl --remove [options]
-
-
-There is no short command line form for this option to prevent accidental
-clean up. Note that after removing a design library, the files are not
-known anymore by GHDL.
-
-.. _Copy_command:
-
-Copy command
-------------
-
-.. index:: copying library
-
-.. index:: --copy command
-
-Make a local copy of an existing library::
-
- ghdl --copy --work=name [options]
-
-
-Make a local copy of an existing library. This is very useful if you want to
-add unit to the :samp:`ieee` library:
-
-.. code-block:: shell
-
- ghdl --copy --work=ieee --ieee=synopsys
- ghdl -a --work=ieee numeric_unsigned.vhd
-
-
-.. _Create_a_Library:
-
-Create a Library
-----------------
-
-.. index:: create your own library
-
-A new library is created by compiling entities (packages etc.) into it::
-
- ghdl -a --work=my_custom_lib my_file.vhd
-
-
-A library's source code is usually stored and compiled into its own directory,
-that you specify with the :option:`--workdir` option::
-
- ghdl -a --work=my_custom_lib --workdir=my_custom_libdir my_custom_lib_srcdir/my_file.vhd
-
-
-See also the :option:`-PPATH` command line option.
-
-.. _Cross-reference_command:
-
-Cross-reference command
-=======================
-
-To easily navigate through your sources, you may generate cross-references::
-
- ghdl --xref-html [options] file...
-
-
-This command generates an html file for each :samp:`file` given in the command
-line, with syntax highlighting and full cross-reference: every identifier is
-a link to its declaration. Besides, an index of the files is created too.
-
-The set of :samp:`file` are analyzed, and then, if the analysis is
-successful, html files are generated in the directory specified by the
-:option:`-o dir` option, or :file:`html/` directory by default.
-
-If the option :option:`--format=html2` is specified, then the generated html
-files follow the HTML 2.0 standard, and colours are specified with
-`<FONT>` tags. However, colours are hard-coded.
-
-If the option :option:`--format=css` is specified, then the generated html files
-follow the HTML 4.0 standard, and use the CSS-1 file :file:`ghdl.css` to
-specify colours. This file is generated only if it does not already exist (it
-is never overwritten) and can be customized by the user to change colours or
-appearance. Refer to a generated file and its comments for more information.
-
-File commands
-=============
-
-The following commands act on one or several files. They do not analyze
-files, therefore, they work even if a file has semantic errors.
-
-Pretty print command
---------------------
-
-.. index:: --pp-html command
-
-.. index:: pretty printing
-
-.. index:: vhdl to html
-
-Generate HTML on standard output from VHDL::
-
- ghdl --pp-html [options] file...
-
-
-The files are just scanned and an html file, with syntax highlighting is
-generated on standard output.
-
-Since the files are not even parsed, erroneous files or incomplete designs
-can be pretty printed.
-
-The style of the html file can be modified with the :option:`--format=` option.
-By default or when the :option:`--format=html2` option is specified, the output
-is an HTML 2.0 file, with colours set through `<FONT>` tags. When the
-:option:`--format=css` option is specified, the output is an HTML 4.0 file,
-with colours set through a CSS file, whose name is :file:`ghdl.css`.
-See :ref:`Cross-reference_command`, for more details about this CSS file.
-
-Find command
-------------
-
-.. index:: -f command
-
-Display the name of the design units in files::
-
- ghdl -f file...
-
-
-The files are scanned, parsed and the names of design units are displayed.
-Design units marked with two stars are candidate to be at the apex of a
-design hierarchy.
-
-Chop command
-------------
-
-.. index:: --chop command
-
-Chop (or split) files at design unit::
-
- ghdl --chop files
-
-
-`GHDL` reads files, and writes a file in the current directory for
-every design unit.
-
-The filename of a design unit is build according to the unit. For an
-entity declaration, a package declaration or a configuration the file
-name is :file:`NAME.vhdl`, where `NAME` is the name of the design
-unit. For a package body, the filename is :file:`NAME-body.vhdl`.
-Finally, for an architecture `ARCH` of an entity `ENTITY`, the
-filename is :file:`ENTITY-ARCH.vhdl`.
-
-Since the input files are parsed, this command aborts in case of syntax
-error. The command aborts too if a file to be written already exists.
-
-Comments between design units are stored into the most adequate files.
-
-This command may be useful to split big files, if your computer has not
-enough memory to compile such files. The size of the executable is
-reduced too.
-
-Lines command
--------------
-
-.. index:: --lines command
-
-Display on the standard output lines of files preceded by line number::
-
- ghdl --lines files
-
-
-Misc commands
-=============
-
-There are a few GHDL commands which are seldom useful.
-
-.. _Help_command:
-
-Help command
-------------
-
-.. index:: -h command
-
-.. index:: --help command
-
-Display (on the standard output) a short description of the all the commands
-available. If the help switch is followed by a command switch, then options
-for this later command are displayed::
-
- ghdl --help
- ghdl -h
- ghdl -h command
-
-
-.. _Disp_config_command:
-
-Disp config command
--------------------
-
-.. index:: --disp-config command
-
-.. index:: display configuration
-
-Display the program paths and options used by GHDL::
-
- ghdl --disp-config [options]
-
-
-This may be useful to track installation errors.
-
-Disp standard command
----------------------
-
-.. index:: --disp-standard command
-
-.. index:: display :samp:`std.standard`
-
-Display the :samp:`std.standard` package::
-
- ghdl --disp-standard [options]
-
-
-Version command
----------------
-
-.. index:: --version command
-
-.. index:: version
-
-Display the `GHDL` version and exit::
-
- ghdl --version
-
-
-VPI build commands
-==================
-
-These commands simplify the compile and the link of a user vpi
-module. They are all wrapper: the arguments are in fact a whole
-command line that is executed with additional switches. Currently a
-unix-like compiler (like `cc`, `gcc` or `clang`) is expected: the additional
-switches use their syntax. The only option is `-v` which displays the
-command before its execution.
-
-.. _VPI_compile_command:
-
-VPI compile command
--------------------
-
-.. index:: --vpi-compile command
-
-Add include path to the command and execute it::
-
- ghdl --vpi-compile command
-
-This will execute::
-
- command -Ixxx/include
-
-For example::
-
- ghdl --vpi-compile gcc -c vpi1.c
-
-executes::
-
- gcc -c vpi1.c -fPIC -Ixxx/include
-
-.. _VPI_link_command:
-
-VPI link command
-----------------
-
-.. index:: --vpi-link command
-
-Add library path and name to the command and execute it::
-
- ghdl --vpi-link command
-
-This will execute::
-
- command -Lxxx/lib -lghdlvpi
-
-For example::
-
- ghdl --vpi-link gcc -o vpi1.vpi vpi1.o
-
-executes::
-
- gcc -o vpi1.vpi vpi1.o --shared -Lxxx/lib -lghdlvpi
-
-
-.. _VPI_cflags_command:
-
-VPI cflags command
-------------------
-
-.. index:: --vpi-cflags command
-
-Display flags added by :option:`--vpi-compile`::
-
- ghdl --vpi-cflags
-
-
-.. _VPI_ldflags_command:
-
-VPI ldflags command
--------------------
-
-.. index:: --vpi-ldflags command
-
-Display flags added by :option:`--vpi-link`::
-
- ghdl --vpi-ldflags
-
-.. _VPI_include_dir_command:
-
-VPI include dir command
------------------------
-
-.. index:: --vpi-include-dir command
-
-Display the include directory added by the compile flags::
-
- ghdl --vpi-include-dir
-
-.. _VPI_library_dir_command:
-
-VPI library dir command
------------------------
-
-.. index:: --vpi-library-dir command
-
-Display the library directory added by the link flags::
-
- ghdl --vpi-library-dir
-
-
-Installation Directory
-======================
-
-During analysis and elaboration `GHDL` may read the `std`
-and `ieee` files. The location of these files is based on the prefix,
-which is (in priority order):
-
-* the :option:`--PREFIX=` command line option
-
-* the :envvar:`GHDL_PREFIX` environment variable
-
-*
- a built-in default path. It is a hard-coded path on GNU/Linux and the
- value of the :samp:`HKLM\Software\Ghdl\Install_Dir` registry entry on Windows.
-
-You should use the :option:`--disp-config` command (:ref:`Disp_config_command` for details) to disp and debug installation problems.
-
-.. _ieee_library_pitfalls:
-
-IEEE library pitfalls
-=====================
-
-When you use options :option:`--ieee=synopsys` or :option:`--ieee=mentor`,
-the `IEEE` library contains non standard packages such as
-:samp:`std_logic_arith`.
-
-These packages are not standard because there are not described by an IEEE
-standard, even if they have been put in the `IEEE` library. Furthermore,
-they are not really de-facto standard, because there are slight differences
-between the packages of Mentor and those of Synopsys.
-
-Furthermore, since they are not well-thought, their use has pitfalls. For
-example, this description has error during compilation:
-
-.. code-block:: VHDL
-
- library ieee;
- use ieee.std_logic_1164.all;
-
- -- A counter from 0 to 10.
- entity counter is
- port (val : out std_logic_vector (3 downto 0);
- ck : std_logic;
- rst : std_logic);
- end counter;
-
- library ieee;
- use ieee.std_logic_unsigned.all;
-
- architecture bad of counter
- is
- signal v : std_logic_vector (3 downto 0);
- begin
- process (ck, rst)
- begin
- if rst = '1' then
- v <= x"0";
- elsif rising_edge (ck) then
- if v = "1010" then -- Error
- v <= x"0";
- else
- v <= v + 1;
- end if;
- end if;
- end process;
-
- val <= v;
- end bad;
-
-
-When you analyze this design, GHDL does not accept it (too long lines
-have been split for readability):
-
-.. code-block:: shell
-
- ghdl -a --ieee=synopsys bad_counter.vhdl
- bad_counter.vhdl:13:14: operator "=" is overloaded
- bad_counter.vhdl:13:14: possible interpretations are:
- ../../libraries/ieee/std_logic_1164.v93:69:5: implicit function "="
- [std_logic_vector, std_logic_vector return boolean]
- ../../libraries/synopsys/std_logic_unsigned.vhdl:64:5: function "="
- [std_logic_vector, std_logic_vector return boolean]
- ../translate/ghdldrv/ghdl: compilation error
-
-Indeed, the `"="` operator is defined in both packages, and both
-are visible at the place it is used. The first declaration is an
-implicit one, which occurs when the `std_logic_vector` type is
-declared and is an element to element comparison, the second one is an
-explicit declared function, with the semantic of an unsigned comparison.
-
-With some analyser, the explicit declaration has priority over the implicit
-declaration, and this design can be analyzed without error. However, this
-is not the rule given by the VHDL LRM, and since GHDL follows these rules,
-it emits an error.
-
-You can force GHDL to use this rule with the *-fexplicit* option.
-:ref:`GHDL_options`, for more details.
-
-However it is easy to fix this error, by using a selected name:
-
-.. code-block:: VHDL
-
- library ieee;
- use ieee.std_logic_unsigned.all;
-
- architecture fixed_bad of counter
- is
- signal v : std_logic_vector (3 downto 0);
- begin
- process (ck, rst)
- begin
- if rst = '1' then
- v <= x"0";
- elsif rising_edge (ck) then
- if ieee.std_logic_unsigned."=" (v, "1010") then
- v <= x"0";
- else
- v <= v + 1;
- end if;
- end if;
- end process;
-
- val <= v;
- end fixed_bad;
-
-
-It is better to only use the standard packages defined by IEEE, which
-provides the same functionalities:
-
-.. code-block:: VHDL
-
- library ieee;
- use ieee.numeric_std.all;
-
- architecture good of counter
- is
- signal v : unsigned (3 downto 0);
- begin
- process (ck, rst)
- begin
- if rst = '1' then
- v <= x"0";
- elsif rising_edge (ck) then
- if v = "1010" then
- v <= x"0";
- else
- v <= v + 1;
- end if;
- end if;
- end process;
-
- val <= std_logic_vector (v);
- end good;
-
-
-IEEE math packages
-==================
-
-.. index:: Math_Real
-
-.. index:: Math_Complex
-
-The :samp:`ieee` math packages (:samp:`math_real` and
-:samp:`math_complex`) provided with `GHDL` are fully compliant with
-the `IEEE` standard.
diff --git a/doc/1_Using/QuickStartGuide.rst b/doc/1_Using/QuickStartGuide.rst
deleted file mode 100644
index bbaf3894d..000000000
--- a/doc/1_Using/QuickStartGuide.rst
+++ /dev/null
@@ -1,359 +0,0 @@
-.. _USING:QuickStart:
-
-******************
-Quick Start Guide
-******************
-
-In this chapter, you will learn how to use the GHDL compiler by
-working on two examples.
-
-The hello world program
-=======================
-
-To illustrate the large purpose of VHDL, here is a commented VHDL
-"Hello world" program.
-
-.. code-block:: VHDL
-
- -- Hello world program.
- use std.textio.all; -- Imports the standard textio package.
-
- -- Defines a design entity, without any ports.
- entity hello_world is
- end hello_world;
-
- architecture behaviour of hello_world is
- begin
- process
- variable l : line;
- begin
- write (l, String'("Hello world!"));
- writeline (output, l);
- wait;
- end process;
- end behaviour;
-
-Suppose this program is contained in the file :file:`hello.vhdl`.
-First, you have to compile the file; this is called `analysis` of a design
-file in VHDL terms.
-
-.. code-block:: shell
-
- $ ghdl -a hello.vhdl
-
-This command creates or updates a file :file:`work-obj93.cf`, which
-describes the library `work`. On GNU/Linux, this command generates a
-file :file:`hello.o`, which is the object file corresponding to your
-VHDL program. The object file is not created on Windows.
-
-Then, you have to build an executable file.
-
-.. code-block:: shell
-
- $ ghdl -e hello_world
-
-The :option:`-e` option means :dfn:`elaborate`. With this option, `GHDL`
-creates code in order to elaborate a design, with the :samp:`hello_world`
-entity at the top of the hierarchy.
-
-On GNU/Linux, if you have enabled the GCC backend during the compilation of `GHDL`,
-an executable program called :file:`hello_world` which can be run is generated:
-
-.. code-block:: shell
-
- $ ghdl -r hello_world
-
-or directly:
-
-.. code-block:: shell
-
- $ ./hello_world
-
-
-On Windows or if the GCC backend was not enabled, no file is created.
-The simulation is launched using this command:
-
-.. code-block:: shell
-
- > ghdl -r hello_world
-
-
-The result of the simulation appears on the screen::
-
- Hello world!
-
-
-A full adder
-============
-
-VHDL is generally used for hardware design. This example starts with
-a full adder described in the :file:`adder.vhdl` file:
-
-.. code-block:: VHDL
-
- entity adder is
- -- `i0`, `i1` and the carry-in `ci` are inputs of the adder.
- -- `s` is the sum output, `co` is the carry-out.
- port (i0, i1 : in bit; ci : in bit; s : out bit; co : out bit);
- end adder;
-
- architecture rtl of adder is
- begin
- -- This full-adder architecture contains two concurrent assignment.
- -- Compute the sum.
- s <= i0 xor i1 xor ci;
- -- Compute the carry.
- co <= (i0 and i1) or (i0 and ci) or (i1 and ci);
- end rtl;
-
-
-You can analyze this design file:
-
-.. code-block:: shell
-
- $ ghdl -a adder.vhdl
-
-
-You can try to execute the `adder` design, but this is useless,
-since nothing externally visible will happen. In order to
-check this full adder, a testbench has to be run. This testbench is
-very simple, since the adder is also simple: it checks exhaustively all
-inputs. Note that only the behaviour is tested, timing constraints are
-not checked. The file :file:`adder_tb.vhdl` contains the testbench for
-the adder:
-
-.. code-block:: VHDL
-
- -- A testbench has no ports.
- entity adder_tb is
- end adder_tb;
-
- architecture behav of adder_tb is
- -- Declaration of the component that will be instantiated.
- component adder
- port (i0, i1 : in bit; ci : in bit; s : out bit; co : out bit);
- end component;
-
- -- Specifies which entity is bound with the component.
- for adder_0: adder use entity work.adder;
- signal i0, i1, ci, s, co : bit;
- begin
- -- Component instantiation.
- adder_0: adder port map (i0 => i0, i1 => i1, ci => ci,
- s => s, co => co);
-
- -- This process does the real job.
- process
- type pattern_type is record
- -- The inputs of the adder.
- i0, i1, ci : bit;
- -- The expected outputs of the adder.
- s, co : bit;
- end record;
- -- The patterns to apply.
- type pattern_array is array (natural range <>) of pattern_type;
- constant patterns : pattern_array :=
- (('0', '0', '0', '0', '0'),
- ('0', '0', '1', '1', '0'),
- ('0', '1', '0', '1', '0'),
- ('0', '1', '1', '0', '1'),
- ('1', '0', '0', '1', '0'),
- ('1', '0', '1', '0', '1'),
- ('1', '1', '0', '0', '1'),
- ('1', '1', '1', '1', '1'));
- begin
- -- Check each pattern.
- for i in patterns'range loop
- -- Set the inputs.
- i0 <= patterns(i).i0;
- i1 <= patterns(i).i1;
- ci <= patterns(i).ci;
- -- Wait for the results.
- wait for 1 ns;
- -- Check the outputs.
- assert s = patterns(i).s
- report "bad sum value" severity error;
- assert co = patterns(i).co
- report "bad carry out value" severity error;
- end loop;
- assert false report "end of test" severity note;
- -- Wait forever; this will finish the simulation.
- wait;
- end process;
- end behav;
-
-
-As usual, you should analyze the design:
-
-.. code-block:: shell
-
- $ ghdl -a adder_tb.vhdl
-
-And build an executable for the testbench:
-
-.. code-block:: shell
-
- $ ghdl -e adder_tb
-
-You do not need to specify which object files are required: GHDL knows them
-and automatically adds them in the executable. Now, it is time to run the
-testbench:
-
-.. code-block:: shell
-
- $ ghdl -r adder_tb
- adder_tb.vhdl:52:7:(assertion note): end of test
-
-
-If your design is rather complex, you'd like to inspect signals. Signals
-value can be dumped using the VCD file format. The resulting file can be
-read with a wave viewer such as GTKWave. First, you should simulate your
-design and dump a waveform file:
-
-.. code-block:: shell
-
- $ ghdl -r adder_tb --vcd=adder.vcd
-
-Then, you may now view the waves:
-
-.. code-block:: shell
-
- $ gtkwave adder.vcd
-
-See :ref:`Simulation_options`, for more details on the :option:`--vcd` option and
-other runtime options.
-
-
-Starting with a design
-======================
-
-Unless you are only studying VHDL, you will work with bigger designs than
-the ones of the previous examples.
-
-Let's see how to analyze and run a bigger design, such as the DLX model
-suite written by Peter Ashenden which is distributed under the terms of the
-GNU General Public License. A copy is kept on
-http://ghdl.free.fr/dlx.tar.gz
-
-First, untar the sources:
-
-.. code-block:: shell
-
- $ tar zxvf dlx.tar.gz
-
-
-In order not to pollute the sources with the library, it is a good idea
-to create a :file:`work/` subdirectory for the `WORK` library. To
-any GHDL commands, we will add the :option:`--workdir=work` option, so
-that all files generated by the compiler (except the executable) will be
-placed in this directory.
-
-.. code-block:: shell
-
- $ cd dlx
- $ mkdir work
-
-
-We will run the :samp:`dlx_test_behaviour` design. We need to analyze
-all the design units for the design hierarchy, in the correct order.
-GHDL provides an easy way to do this, by importing the sources:
-
-.. code-block:: shell
-
- $ ghdl -i --workdir=work *.vhdl
-
-
-and making a design:
-
-.. code-block:: shell
-
- $ ghdl -m --workdir=work dlx_test_behaviour
-
-
-Before this second stage, GHDL knows all the design units of the DLX,
-but no one have been analyzed. The make command of GHDL analyzes and
-elaborates a design. This creates many files in the :file:`work/`
-directory, and the :file:`dlx_test_behaviour` executable in the current
-directory.
-
-The simulation needs to have a DLX program contained in the file
-:file:`dlx.out`. This memory image will be be loaded in the DLX memory.
-Just take one sample:
-
-.. code-block:: shell
-
- $ cp test_loop.out dlx.out
-
-
-And you can run the test suite:
-
-.. code-block:: shell
-
- $ ghdl -r --workdir=work dlx_test_behaviour
-
-
-The test bench monitors the bus and displays each instruction executed.
-It finishes with an assertion of severity level note:
-
-.. code-block:: shell
-
- dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction
- encountered, execution halted
-
-
-Since the clock is still running, you have to manually stop the program
-with the :kbd:`C-c` key sequence. This behavior prevents you from running the
-test bench in batch mode. However, you may force the simulator to
-stop when an assertion above or equal a certain severity level occurs:
-
-.. code-block:: shell
-
- $ ghdl -r --workdir=work dlx_test_behaviour --assert-level=note
-
-
-With this option, the program stops just after the previous message::
-
- dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction
- encountered, execution halted
- error: assertion failed
-
-
-If you want to make room on your hard drive, you can either:
-
-* clean the design library with the GHDL command:
-
- .. code-block:: shell
-
- $ ghdl --clean --workdir=work
-
- This removes the executable and all the object files. If you want to
- rebuild the design at this point, just do the make command as shown
- above.
-
-* remove the design library with the GHDL command:
-
- .. code-block:: shell
-
- $ ghdl --remove --workdir=work
-
- This removes the executable, all the object files and the library file.
- If you want to rebuild the design, you have to import the sources again,
- and to make the design.
-
-* remove the :file:`work/` directory:
-
- .. code-block:: shell
-
- $ rm -rf work
-
- Only the executable is kept. If you want to rebuild the design, create
- the :file:`work/` directory, import the sources, and make the design.
-
-Sometimes, a design does not fully follow the VHDL standards. For example it
-uses the badly engineered :samp:`std_logic_unsigned` package. GHDL supports
-this VHDL dialect through some options::
-
- --ieee=synopsys -fexplicit
-
-See :ref:`IEEE_library_pitfalls`, for more details.
-
diff --git a/doc/1_Using/Simulation.rst b/doc/1_Using/Simulation.rst
deleted file mode 100644
index 73c74bcd0..000000000
--- a/doc/1_Using/Simulation.rst
+++ /dev/null
@@ -1,292 +0,0 @@
-.. _USING:Simulation:
-
-**********************
-Simulation and runtime
-**********************
-
-.. _simulation_options:
-
-Simulation options
-==================
-
-In most system environments, it is possible to pass options while
-invoking a program. Contrary to most programming languages, there is no
-standard method in VHDL to obtain the arguments or to set the exit
-status.
-
-In GHDL, it is impossible to pass parameters to your design. A later version
-could do it through the generics interfaces of the top entity.
-
-However, the GHDL runtime behaviour can be modified with some options; for
-example, it is possible to stop simulation after a certain time.
-
-The exit status of the simulation is :samp:`EXIT_SUCCESS` (0) if the
-simulation completes, or :samp:`EXIT_FAILURE` (1) in case of error
-(assertion failure, overflow or any constraint error).
-
-Here is the list of the most useful options. Some debugging options are
-also available, but not described here. The :option:`--help` options lists
-all options available, including the debugging one.
-
-
-
-.. option:: --assert-level=<LEVEL>
-
- Select the assertion level at which an assertion violation stops the
- simulation. `LEVEL` is the name from the `severity_level`
- enumerated type defined in the `standard` package or the
- :samp:`none` name.
-
- By default, only assertion violation of severity level :samp:`failure`
- stops the simulation.
-
- For example, if `LEVEL` was :samp:`warning`, any assertion violation
- with severity level :samp:`warning`, :samp:`error` or :samp:`failure` would
- stop simulation, but the assertion violation at the :samp:`note` severity
- level would only display a message.
-
- Option :option:`--assert-level=none` prevents any assertion violation to stop
- simulation.
-
-.. option:: --ieee-asserts=<POLICY>
-
- Select how the assertions from :samp:`ieee` units are
- handled. `POLICY` can be :samp:`enable` (the default),
- :samp:`disable` which disables all assertion from :samp:`ieee` packages
- and :samp:`disable-at-0` which disables only at start of simulation.
-
- This option can be useful to avoid assertion message from
- :samp:`ieee.numeric_std` (and other :samp:`ieee` packages).
-
-
-.. option:: --stop-time=<TIME>
-
- Stop the simulation after :samp:`TIME`. :samp:`TIME` is expressed as a time
- value, *without* any space. The time is the simulation time, not
- the real clock time.
-
- For example::
-
- $ ./my_design --stop-time=10ns
- $ ./my_design --stop-time=ps
-
-
-.. option:: --stop-delta=<N>
-
- Stop the simulation after `N` delta cycles in the same current time.
-
- .. index:: display time
-
-.. option:: --disp-time
-
- Display the time and delta cycle number as simulation advances.
-
-
-.. option:: --disp-tree[=<KIND>]
-
- .. index:: display design hierarchy
-
- Display the design hierarchy as a tree of instantiated design entities.
- This may be useful to understand the structure of a complex
- design. `KIND` is optional, but if set must be one of:
-
-
- * none
- Do not display hierarchy. Same as if the option was not present.
-
- * inst
- Display entities, architectures, instances, blocks and generates statements.
-
- * proc
- Like :samp:`inst` but also display processes.
-
- * port
- Like :samp:`proc` but display ports and signals too.
- If `KIND` is not specified, the hierarchy is displayed with the
- :samp:`port` mode.
-
-
-.. option:: --no-run
-
- Do not simulate, only elaborate. This may be used with
- :option:`--disp-tree` to display the tree without simulating the whole
- design.
-
-
-.. option:: --unbuffered
-
- Disable buffering on stdout, stderr and files opened in write or append mode (TEXTIO).
-
-
-.. option:: --read-opt-file=<FILENAME>
-
- Filter signals to be dumped to the wave file according to the wave option
- file provided.
-
- Here is a description of the wave option file format currently supported :
-
- $ version = 1.1 # Optional
-
- # Path format for signals in packages :
- my_pkg.global_signal_a
-
- # Path format for signals in entities :
- /top/sub/clk
-
- # Dumps every signals named reset in first level sub entities of top
- /top/*/reset
-
- # Dumps every signals named reset in recursive sub entities of top
- /top/**/reset
-
- # Dump every signals of sub2 which could be anywhere in design except on
- # top level
- /**/sub2/*
-
- # Dump every signals of sub3 which must be a first level sub entity of the
- # top level
- /*/sub3/*
-
- # Dump every signals of the first level sub entities of sub3 (but not
- # those of sub3)
- /**/sub3/*/*
-
-
-.. option:: --write-opt-file=<FILENAME>
-
- If the wave option file doesn't exist, creates it with all the signals of
- the design. Otherwise throws an error, because it won't erase an existing
- file.
-
-
-.. option:: --vcd=<FILENAME>
-
-.. option:: --vcdgz=<FILENAME>
-
- .. index:: vcd
-
- .. index:: value change dump
-
- .. index:: dump of signals
-
- Option :option:`--vcd` dumps into the VCD file `FILENAME` the signal
- values before each non-delta cycle. If `FILENAME` is :samp:`-`,
- then the standard output is used, otherwise a file is created or
- overwritten.
-
- The :option:`--vcdgz` option is the same as the *--vcd* option,
- but the output is compressed using the `zlib` (`gzip`
- compression). However, you can't use the :samp:`-` filename.
- Furthermore, only one VCD file can be written.
-
- :dfn:`VCD` (value change dump) is a file format defined
- by the `verilog` standard and used by virtually any wave viewer.
-
- Since it comes from `verilog`, only a few VHDL types can be dumped. GHDL
- dumps only signals whose base type is of the following:
-
-
- * types defined in the :samp:`std.standard` package:
-
- * :samp:`bit`
-
- * :samp:`bit_vector`
-
- * types defined in the :samp:`ieee.std_logic_1164` package:
-
- * :samp:`std_ulogic`
-
- * :samp:`std_logic` (because it is a subtype of :samp:`std_ulogic`)
-
- * :samp:`std_ulogic_vector`
-
- * :samp:`std_logic_vector`
-
- * any integer type
-
- I have successfully used `gtkwave` to view VCD files.
-
- Currently, there is no way to select signals to be dumped: all signals are
- dumped, which can generate big files.
-
- It is very unfortunate there is no standard or well-known wave file
- format supporting VHDL types. If you are aware of such a free format,
- please mail me (:ref:`Reporting_bugs`).
-
-
-.. option:: --fst=<FILENAME>
-
- Write the waveforms into a `fst`, that can be displayed by
- `gtkwave`. The `fst` files are much smaller than VCD or
- `GHW` files, but it handles only the same signals as the VCD format.
-
-
-.. option:: --wave=<FILENAME>
-
- Write the waveforms into a `ghw` (GHdl Waveform) file. Currently, all
- the signals are dumped into the waveform file, you cannot select a hierarchy
- of signals to be dumped.
-
- The format of this file was defined by myself and is not yet completely fixed.
- It may change slightly. The :samp:`gtkwave` tool can read the GHW files.
-
- Contrary to VCD files, any VHDL type can be dumped into a GHW file.
-
-
-.. option:: --psl-report=<FILENAME>
-
- Write a report for PSL assertions and coverage at the end of
- simulation. The file is written using the JSON format, but still
- being human readable.
-
-
-.. option:: --sdf=<PATH>=<FILENAME>
-
- Do VITAL annotation on `PATH` with SDF file :file:`FILENAME`.
-
- `PATH` is a path of instances, separated with :samp:`.` or :samp:`/`.
- Any separator can be used. Instances are component instantiation labels,
- generate labels or block labels. Currently, you cannot use an indexed name.
-
- Specifying a delay::
-
- --sdf=min=<PATH>=<FILENAME>
- --sdf=typ=<PATH>=<FILENAME>
- --sdf=max=<PATH>=<FILENAME>
-
- If the option contains a type of delay, that is :samp:`min=`,
- :samp:`typ=` or :samp:`max=`, the annotator use respectively minimum,
- typical or maximum values. If the option does not contain a type of delay,
- the annotator use the typical delay.
-
- See :ref:`Backannotation`, for more details.
-
-
-.. option:: --help
-
- Display a short description of the options accepted by the runtime library.
-
-Debugging VHDL programs
-=======================
-
-.. index:: debugging
-
-.. index:: `__ghdl_fatal`
-
-Debugging VHDL programs using `GDB` is possible only on GNU/Linux systems.
-
-`GDB` is a general purpose debugger for programs compiled by `GCC`.
-Currently, there is no VHDL support for `GDB`. It may be difficult
-to inspect variables or signals in `GDB`, however, `GDB` is
-still able to display the stack frame in case of error or to set a breakpoint
-at a specified line.
-
-`GDB` can be useful to precisely catch a runtime error, such as indexing
-an array beyond its bounds. All error check subprograms call the
-`__ghdl_fatal` procedure. Therefore, to catch runtime error, set
-a breakpoint like this:
-
- (gdb) break __ghdl_fatal
-
-When the breakpoint is hit, use the `where` or `bt` command to
-display the stack frames.
diff --git a/doc/2_Getting/Docker.rst b/doc/2_Getting/Docker.rst
deleted file mode 100644
index 35a1c11b6..000000000
--- a/doc/2_Getting/Docker.rst
+++ /dev/null
@@ -1,31 +0,0 @@
-.. _DOCKER:
-
-Docker containers
-#############
-
-What is docker? A primer
-=================
-
-Where are images hosted?
-=================
-
-docker-hub
-ghdl-tools
-Dockerfiles
-
-Launch options
-=================
-
-With(out) shared folder
-----------------
-
-Interactive/daemon
-----------------
-
-Shrinking
-----------------
-
-Additional tools, with(out) GUI
-----------------
-
-GtkWave, PoC, VUnit, OSVVM, UVVM
\ No newline at end of file
diff --git a/doc/2_Getting/Releases.rst b/doc/2_Getting/Releases.rst
deleted file mode 100644
index 0fbd4542d..000000000
--- a/doc/2_Getting/Releases.rst
+++ /dev/null
@@ -1,8 +0,0 @@
-.. _RELEASE:
-
-Releases
-########
-
-.. TODO: topic
-
- naming, stable, development, nightly
\ No newline at end of file
diff --git a/doc/3_Building/VendorPrimitives.rst b/doc/3_Building/VendorPrimitives.rst
deleted file mode 100644
index 49c35b5a4..000000000
--- a/doc/3_Building/VendorPrimitives.rst
+++ /dev/null
@@ -1,328 +0,0 @@
-.. _VENDOR:
-
-Vendor Primitives
-#############
-
-## Compile Scripts for Vendor VHDL Libraries
-
-Vendors like Altera, Lattice and Xilinx have their own simulation libraries,
-especially for FPGA primitives, soft and hard macros. These libraries can not be
-shipped with GHDL, but we offer prepared compile scripts to pre-compile the
-vendor libraries, if the vendor tool is present on the computer.
-
-There are also popular simulation and verification libraries like [OSVVM][osvvm]
-and [VUnit][vunit], which can be pre-compile, too.
-
-The compilation scripts are writen in the shell languages: PowerShell for Windows
-and Bash for Linux. The compile scripts can colorize the GHDL warning and error
-lines with the help of grc/grcat ([generic colourizer][grc]).
-
- [osvvm]: http://osvvm.org/
- [vunit]: https://github.com/LarsAsplund/vunit
- [grc]: http://kassiopeia.juls.savba.sk/~garabik/software/grc.html
-
-##### Supported Vendors Libraries
-
- - Altera Quartus (≥13.0):
- - lpm, sgate
- - altera, altera_mf, altera_lnsim
- - arriaii, arriaii_pcie_hip, arriaiigz
- - arriav, arriavgz, arriavgz_pcie_hip
- - cycloneiv, cycloneiv_pcie_hip, cycloneive
- - cyclonev
- - max, maxii, maxv
- - stratixiv, stratixiv_pcie_hip
- - stratixv, stratixv_pcie_hip
- - fiftyfivenm, twentynm
- - Lattice (≥3.6):
- - ec
- - ecp, ecp2, ecp3, ecp5u
- - lptm, lptm2
- - machxo, machxo2, machxo3l
- - sc, scm
- - xp, xp2
- - Xilinx ISE (≥14.0):
- - unisim (incl. secureip)
- - unimacro
- - simprim (incl. secureip)
- - xilinxcorelib
- - Xilinx Vivado (≥2014.1):
- - unisim (incl. secureip)
- - unimacro
-
-##### Supported Simulation and Verification Libraries
-
- - OSVVM (for VHDL-2008)
- - osvvm
- - VUnit (for VHDL-2008)
- - vunit_lib
-
----------------------------------------------------------------------
-### Script Configuration
-
-The vendor library compile scripts need to know where the used / latest vendor
-tool chain is installed. Therefore, the script implement a default installation
-directory search as well as environment variable checks. If a vendor tool could
-not be detected or the script choses the wrong vendor library source directory,
-then it's possible to provide the path via `--source` or `-Source`.
-
-The generated output is stored relative to the current working directory. The
-scripts create a sub-directory for each vendor. The default output directory can
-be overwritten by the parameter `--output` or `-Output`.
-
-To compile all source files with GHDL, the simulator executable is searched in
-`PATH`. The found default GHDL executable can be overwritten by setting the
-environment variable `GHDL` or by passing the parameter `--ghdl` or `-GHDL` to
-the scripts.
-
-If the vendor library compilation is used very often, we recommend to configure
-these parameters in `config.sh` or `config.psm1`, so the command line can be
-shortened to the essential parts.
-
----------------------------------------------------------------------
-### Compiling on Linux
-
- - **Step 0 - Configure the scripts (optional)**
- See next section for how to configure `config.sh`.
-
- - **Step 1 - Browse to your simulation working directory**
- ```Bash
- $ cd <MySimulationFolder>
- ```
-
- - **Step 2 - Start the compilation script(s)**
- ```Bash
- $ /usr/local/lib/ghdl/vendors/compile-altera.sh --all
- $ /usr/local/lib/ghdl/vendors/compile-lattice.sh --all
- $ /usr/local/lib/ghdl/vendors/compile-xilinx-ise.sh --all
- $ /usr/local/lib/ghdl/vendors/compile-xilinx-vivado.sh --all
- $ /usr/local/lib/ghdl/vendors/compile-osvvm.sh --all
- $ /usr/local/lib/ghdl/vendors/compile-vunit.sh --all
- ```
-
- In most cases GHDL is installed into `/usr/local/`. The scripts are
- installed into the `lib` directory.
-
- - **Step 3 - Viewing the result**
- This creates vendor directories in your current working directory and
- compiles the vendor files into them.
-
- ```Bash
- $ ls -ahl
- ...
- drwxr-xr-x 2 <user> <group> 56K Nov 30 17:41 altera
- drwxr-xr-x 2 <user> <group> 56K Nov 30 17:42 lattice
- drwxr-xr-x 2 <user> <group> 56K Nov 30 17:48 osvvm
- drwxr-xr-x 2 <user> <group> 56K Nov 30 17:58 vunit
- drwxr-xr-x 2 <user> <group> 56K Nov 30 17:58 xilinx-ise
- drwxr-xr-x 2 <user> <group> 56K Nov 30 17:48 xilinx-vivado
- ```
-
-
----------------------------------------------------------------------
-### Compiling on Windows
-
- - **Step 0 - Configure the scripts (optional)**
- See next section for how to configure `config.psm1`.
-
- - **Step 1 - Browse to your simulation working directory**
- ```PowerShell
- PS> cd <MySimulationFolder>
- ```
-
- - **Step 2 - Start the compilation script(s)**
- ```PowerShell
- PS> <GHDL>\libraries\vendors\compile-altera.ps1 -All
- PS> <GHDL>\libraries\vendors\compile-lattice.ps1 -All
- PS> <GHDL>\libraries\vendors\compile-xilinx-ise.ps1 -All
- PS> <GHDL>\libraries\vendors\compile-xilinx-vivado.ps1 -All
- PS> <GHDL>\libraries\vendors\compile-osvvm.ps1 -All
- PS> <GHDL>\libraries\vendors\compile-vunit.ps1 -All
- ```
-
- - **Step 3 - Viewing the result**
- This creates vendor directories in your current working directory and
- compiles the vendor files into them.
-
- ```PowerShell
- PS> dir
- Directory: D:\temp\ghdl
-
- Mode LastWriteTime Length Name
- ---- ------------- ------ ----
- d---- 20.11.2015 19:33 <DIR> altera
- d---- 20.11.2015 19:38 <DIR> lattice
- d---- 20.11.2015 19:38 <DIR> osvvm
- d---- 20.11.2015 19:45 <DIR> vunit_lib
- d---- 20.11.2015 19:06 <DIR> xilinx-ise
- d---- 20.11.2015 19:40 <DIR> xilinx-vivado
- ```
-
----------------------------------------------------------------------
-### Configuration Files
-
-#### For Linux: `config.sh`
-
-Please open the `config.sh` file and set the dictionary entries for the
-installed vendor tools to the appropriate directory to your tool's installation
-directories. Use an empty string `""` for not installed tools.
-
-`config.sh`:
-```Bash
-declare -A InstallationDirectory
-InstallationDirectory[AlteraQuartus]="/opt/Altera/16.0"
-InstallationDirectory[LatticeDiamond]="/opt/Diamond/3.8_x64"
-InstallationDirectory[OSVVM]="/home/<user>/git/GitHub/osvvm"
-InstallationDirectory[VUnit]="/home/<user>/git/GitHub/vunit"
-InstallationDirectory[XilinxISE]="/opt/Xilinx/14.7"
-InstallationDirectory[XilinxVivado]="/opt/Xilinx/Vivado/2016.3"
-```
-
-#### For Windows: `config.psm1`
-
-Please open the `config.psm1` file and set the dictionary entries for the
-installed vendor tools to the appropriate directory to your tool's installation
-folder. Use an empty string `""` for not installed tools.
-
-`config.psm1`:
-```PowerShell
-$InstallationDirectory = @{
- "AlteraQuartus" = "C:\Altera\16.0";
- "LatticeDiamond" = "C:\Lattice\Diamond\3.8_x64";
- "XilinxISE" = "C:\Xilinx\14.7\ISE_DS";
- "XilinxVivado" = "C:\Xilinx\Vivado\2016.3";
- "OSVVM" = "D:\git\GitHub\osvvm";
- "VUnit" = "D:\git\GitHub\vunit"
-}
-```
-
-### Selectable Options for the Bash Scripts:
-
-*First I should translate the scripts before writing the docu...*
-
- - Common parameters to most scripts:
-
- -h --help Print the embedded help page(s).
- -c --clean Cleanup directory before analyzing.
- -n --no-warnings Don't show warnings. Report errors only.
- -s --skip-existing Skip already compiled files (an *.o file exists).
- -S --skip-largefiles Don't compile large entities like DSP and PCIe primitives.
- -H --halt-on-error Stop compiling if an error occured.
- - `compile-altera.sh`
- Selectable libraries:
-
- -a --all Compile all libraries, including common libraries, packages and device libraries.
- --altera Compile base libraries like 'altera' and 'altera_mf'
- --max Compile device libraries for Max CPLDs
- --arria Compile device libraries for Arria FPGAs
- --cyclone Compile device libraries for Cyclone FPGAs
- --stratix Compile device libraries for Stratix FPGAs
- Compile options:
-
- --vhdl93 Compile selected libraries with VHDL-93 (default).
- --vhdl2008 Compile selected libraries with VHDL-2008.
- - `compile-xilinx-ise.sh`
- Selectable libraries:
-
- -a --all Compile all libraries, including common libraries, packages and device libraries.
- --unisim Compile the unisim primitives
- --unimacro Compile the unimacro macros
- --simprim Compile the simprim primitives
- --corelib Compile the xilinxcorelib macros
- --secureip Compile the secureip primitives
- Compile options:
-
- --vhdl93 Compile selected libraries with VHDL-93 (default).
- --vhdl2008 Compile selected libraries with VHDL-2008.
- - `compile-xilinx-vivado.sh`
- Selectable libraries:
-
- -a --all Compile all libraries, including common libraries, packages and device libraries.
- --unisim Compile the unisim primitives
- --unimacro Compile the unimacro macros
- --secureip Compile the secureip primitives
- Compile options:
-
- --vhdl93 Compile selected libraries with VHDL-93 (default).
- --vhdl2008 Compile selected libraries with VHDL-2008.
- - `compile-osvvm.sh`
- Selectable libraries:
-
- -a --all Compile all.
- --osvvm Compile the OSVVM library.
- - `compile-vunit.sh`
- Selectable libraries:
-
- -a --all Compile all.
- --osvvm Compile the VUnit library.
-
-### Selectable Options for the PowerShell Scripts:
-
- - Common parameters to all scripts:
-
- -Help Print the embedded help page(s).
- -Clean Cleanup directory before analyzing.
- -SuppressWarnings Don't show warnings. Report errors only.
- - `compile-altera.ps1`
- Selectable libraries:
-
- -All Compile all libraries, including common libraries, packages and device libraries.
- -Altera Compile base libraries like 'altera' and 'altera_mf'
- -Max Compile device libraries for Max CPLDs
- -Arria Compile device libraries for Arria FPGAs
- -Cyclone Compile device libraries for Cyclone FPGAs
- -Stratix Compile device libraries for Stratix FPGAs
- Compile options:
-
- -VHDL93 Compile selected libraries with VHDL-93 (default).
- -VHDL2008 Compile selected libraries with VHDL-2008.
- - `compile-xilinx-ise.ps1`
- Selectable libraries:
-
- -All Compile all libraries, including common libraries, packages and device libraries.
- -Unisim Compile the unisim primitives
- -Unimacro Compile the unimacro macros
- -Simprim Compile the simprim primitives
- -CoreLib Compile the xilinxcorelib macros
- -Secureip Compile the secureip primitives
- Compile options:
-
- -VHDL93 Compile selected libraries with VHDL-93 (default).
- -VHDL2008 Compile selected libraries with VHDL-2008.
- - `compile-xilinx-vivado.ps1`
- Selectable libraries:
-
- -All Compile all libraries, including common libraries, packages and device libraries.
- -Unisim Compile the unisim primitives
- -Unimacro Compile the unimacro macros
- -Secureip Compile the secureip primitives
- Compile options:
-
- -VHDL93 Compile selected libraries with VHDL-93 (default).
- -VHDL2008 Compile selected libraries with VHDL-2008.
- - `compile-osvvm.ps1`
- Selectable libraries:
-
- -All Compile all.
- -OSVVM Compile the OSVVM library.
- - `compile-vunit.ps1`
- Selectable libraries:
-
- -All Compile all.
- -VUnit Compile the VUnit library.
-
-------------------------
-Author: Patrick Lehmann
-Last update: 28.10.2016
-
-------------------------
-
-.. TODO: topic
-
- - Vendor Primitives
- - Alters / Intel
- - Lattice
- - OSVVM
- - UVVM
- - Xilinx ISE
- - Xilinx Vivado
diff --git a/doc/3_Building/index.rst b/doc/3_Building/index.rst
deleted file mode 100644
index d240ff94d..000000000
--- a/doc/3_Building/index.rst
+++ /dev/null
@@ -1,42 +0,0 @@
-.. _BUILD:
-
-Building GHDL
-#############
-
-.. TODO: topic
-
- `./BUILD.txt <https://github.com/tgingold/ghdl/blob/master/BUILD.txt>`_
- Directory structure of the main branch [1138: #279]
- Coverage, `gcov`, is unique to gcc. That specific difference is not explained anywhere. Should be added.
- @1138 Backtraces optional -patchable-
-
-GCC backend
-=================
-
-- ./dist/gcc/INSTALL
-- ./gcc/README
-- Linux
-
-LLVM backend
-=================
-
-- Linux
-- Mac OS?
-- Windows MinGW 32/64
-
-Mcode backend
-=================
-
-- ./dist/mcode/README
-- Linux
-- Windows GNAT GPL (32 only)
-- Windows MinGW 32/64
-
-Test suites
-=================
-
-----------------
-
-.. TODO: topic
-
- @1138 explain that there are two (maybe three with vhdl08 tests)
\ No newline at end of file
diff --git a/doc/4_References/CommandReference.rst b/doc/4_References/CommandReference.rst
deleted file mode 100644
index ed7869dba..000000000
--- a/doc/4_References/CommandReference.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-.. _REF:Command:
-
-Command Reference
-#################
-
-
diff --git a/doc/4_References/ImplementationOfVHDL.rst b/doc/4_References/ImplementationOfVHDL.rst
deleted file mode 100644
index 6919d0ef8..000000000
--- a/doc/4_References/ImplementationOfVHDL.rst
+++ /dev/null
@@ -1,487 +0,0 @@
-.. _REF:ImplVHDL:
-
-***************************
-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/4_References/ImplementationOfVITAL.rst b/doc/4_References/ImplementationOfVITAL.rst
deleted file mode 100644
index 4ffb8159b..000000000
--- a/doc/4_References/ImplementationOfVITAL.rst
+++ /dev/null
@@ -1,94 +0,0 @@
-.. _REF:ImplVITAL:
-
-****************************
-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/X_ChangeLog/2014/index.rst b/doc/X_ChangeLog/2014/index.rst
deleted file mode 100644
index 5822e67e7..000000000
--- a/doc/X_ChangeLog/2014/index.rst
+++ /dev/null
@@ -1,20 +0,0 @@
-.. _CHANGE:2014:
-
-2014
-####
-
-.. contents:: Content of this page
- :local:
-
-.. only:: html
-
- .. toctree::
-
- v0.30 <v0.30>
-
-
-.. only:: latex
-
- .. toctree::
-
- v0.30 <v0.30>
diff --git a/doc/X_ChangeLog/2014/v0.30.rst b/doc/X_ChangeLog/2014/v0.30.rst
deleted file mode 100644
index 87ebef22f..000000000
--- a/doc/X_ChangeLog/2014/v0.30.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-.. _CHANGE:v0.30:
-
-New in 0.30 (xx.yy.2014)
-================================================================================================================================================================
diff --git a/doc/X_ChangeLog/2015/index.rst b/doc/X_ChangeLog/2015/index.rst
deleted file mode 100644
index 3a3dc1ed5..000000000
--- a/doc/X_ChangeLog/2015/index.rst
+++ /dev/null
@@ -1,20 +0,0 @@
-.. _CHANGE:2015:
-
-2015
-####
-
-.. contents:: Content of this page
- :local:
-
-.. only:: html
-
- .. toctree::
-
- v0.31 <v0.31>
-
-
-.. only:: latex
-
- .. toctree::
-
- v0.31 <v0.31>
diff --git a/doc/X_ChangeLog/2015/v0.31.rst b/doc/X_ChangeLog/2015/v0.31.rst
deleted file mode 100644
index 71bab8013..000000000
--- a/doc/X_ChangeLog/2015/v0.31.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-.. _CHANGE:v0.31:
-
-New in 0.31 (xx.yy.2015)
-================================================================================================================================================================
diff --git a/doc/X_ChangeLog/2016/index.rst b/doc/X_ChangeLog/2016/index.rst
deleted file mode 100644
index 340fb915d..000000000
--- a/doc/X_ChangeLog/2016/index.rst
+++ /dev/null
@@ -1,22 +0,0 @@
-.. _CHANGE:2016:
-
-2016
-####
-
-.. contents:: Content of this page
- :local:
-
-.. only:: html
-
- .. toctree::
-
- v0.33 <v0.33>
- v0.32 <v0.32>
-
-
-.. only:: latex
-
- .. toctree::
-
- v0.32 <v0.32>
- v0.33 <v0.33>
diff --git a/doc/X_ChangeLog/2016/v0.32.rst b/doc/X_ChangeLog/2016/v0.32.rst
deleted file mode 100644
index ae6ff7a12..000000000
--- a/doc/X_ChangeLog/2016/v0.32.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-.. _CHANGE:v0.32:
-
-New in 0.32 (xx.yy.2016)
-================================================================================================================================================================
diff --git a/doc/X_ChangeLog/2016/v0.33.rst b/doc/X_ChangeLog/2016/v0.33.rst
deleted file mode 100644
index 676390771..000000000
--- a/doc/X_ChangeLog/2016/v0.33.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-.. _CHANGE:v0.33:
-
-New in 0.33 (xx.yy.2016)
-================================================================================================================================================================
diff --git a/doc/X_ChangeLog/2017/index.rst b/doc/X_ChangeLog/2017/index.rst
deleted file mode 100644
index fa4ed0f1c..000000000
--- a/doc/X_ChangeLog/2017/index.rst
+++ /dev/null
@@ -1,20 +0,0 @@
-.. _CHANGE:2017:
-
-2017
-####
-
-.. contents:: Content of this page
- :local:
-
-.. only:: html
-
- .. toctree::
-
- v0.34 <v0.34>
-
-
-.. only:: latex
-
- .. toctree::
-
- v0.34 <v0.34>
diff --git a/doc/X_ChangeLog/2017/v0.34.rst b/doc/X_ChangeLog/2017/v0.34.rst
deleted file mode 100644
index 874a36728..000000000
--- a/doc/X_ChangeLog/2017/v0.34.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-.. _CHANGE:v0.34:
-
-New in 0.34 (xx.yy.2017)
-================================================================================================================================================================
diff --git a/doc/X_ChangeLog/Roadmap.rst b/doc/X_ChangeLog/Roadmap.rst
deleted file mode 100644
index 3577bc704..000000000
--- a/doc/X_ChangeLog/Roadmap.rst
+++ /dev/null
@@ -1,14 +0,0 @@
-.. _INTRO:Contributing:
-
-Roadmap | 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
\ No newline at end of file
diff --git a/doc/X_ChangeLog/index.rst b/doc/X_ChangeLog/index.rst
deleted file mode 100644
index 959d68486..000000000
--- a/doc/X_ChangeLog/index.rst
+++ /dev/null
@@ -1,30 +0,0 @@
-.. _CHANGE:
-
-Change Log
-##########
-
-.. only:: html
-
- .. toctree::
-
- 2017/index
- 2016/index
- 2015/index
- 2014/index
-
-
-
-.. only:: latex
-
- .. toctree::
-
- 2014/index
- 2015/index
- 2016/index
- 2017/index
-
-------------------------
-
-.. TODO: topic
-
- `./NEWS <https://github.com/tgingold/ghdl/blob/master/NEWS>`_
diff --git a/doc/building/VendorPrimitives.rst b/doc/building/VendorPrimitives.rst
new file mode 100644
index 000000000..49c35b5a4
--- /dev/null
+++ b/doc/building/VendorPrimitives.rst
@@ -0,0 +1,328 @@
+.. _VENDOR:
+
+Vendor Primitives
+#############
+
+## Compile Scripts for Vendor VHDL Libraries
+
+Vendors like Altera, Lattice and Xilinx have their own simulation libraries,
+especially for FPGA primitives, soft and hard macros. These libraries can not be
+shipped with GHDL, but we offer prepared compile scripts to pre-compile the
+vendor libraries, if the vendor tool is present on the computer.
+
+There are also popular simulation and verification libraries like [OSVVM][osvvm]
+and [VUnit][vunit], which can be pre-compile, too.
+
+The compilation scripts are writen in the shell languages: PowerShell for Windows
+and Bash for Linux. The compile scripts can colorize the GHDL warning and error
+lines with the help of grc/grcat ([generic colourizer][grc]).
+
+ [osvvm]: http://osvvm.org/
+ [vunit]: https://github.com/LarsAsplund/vunit
+ [grc]: http://kassiopeia.juls.savba.sk/~garabik/software/grc.html
+
+##### Supported Vendors Libraries
+
+ - Altera Quartus (≥13.0):
+ - lpm, sgate
+ - altera, altera_mf, altera_lnsim
+ - arriaii, arriaii_pcie_hip, arriaiigz
+ - arriav, arriavgz, arriavgz_pcie_hip
+ - cycloneiv, cycloneiv_pcie_hip, cycloneive
+ - cyclonev
+ - max, maxii, maxv
+ - stratixiv, stratixiv_pcie_hip
+ - stratixv, stratixv_pcie_hip
+ - fiftyfivenm, twentynm
+ - Lattice (≥3.6):
+ - ec
+ - ecp, ecp2, ecp3, ecp5u
+ - lptm, lptm2
+ - machxo, machxo2, machxo3l
+ - sc, scm
+ - xp, xp2
+ - Xilinx ISE (≥14.0):
+ - unisim (incl. secureip)
+ - unimacro
+ - simprim (incl. secureip)
+ - xilinxcorelib
+ - Xilinx Vivado (≥2014.1):
+ - unisim (incl. secureip)
+ - unimacro
+
+##### Supported Simulation and Verification Libraries
+
+ - OSVVM (for VHDL-2008)
+ - osvvm
+ - VUnit (for VHDL-2008)
+ - vunit_lib
+
+---------------------------------------------------------------------
+### Script Configuration
+
+The vendor library compile scripts need to know where the used / latest vendor
+tool chain is installed. Therefore, the script implement a default installation
+directory search as well as environment variable checks. If a vendor tool could
+not be detected or the script choses the wrong vendor library source directory,
+then it's possible to provide the path via `--source` or `-Source`.
+
+The generated output is stored relative to the current working directory. The
+scripts create a sub-directory for each vendor. The default output directory can
+be overwritten by the parameter `--output` or `-Output`.
+
+To compile all source files with GHDL, the simulator executable is searched in
+`PATH`. The found default GHDL executable can be overwritten by setting the
+environment variable `GHDL` or by passing the parameter `--ghdl` or `-GHDL` to
+the scripts.
+
+If the vendor library compilation is used very often, we recommend to configure
+these parameters in `config.sh` or `config.psm1`, so the command line can be
+shortened to the essential parts.
+
+---------------------------------------------------------------------
+### Compiling on Linux
+
+ - **Step 0 - Configure the scripts (optional)**
+ See next section for how to configure `config.sh`.
+
+ - **Step 1 - Browse to your simulation working directory**
+ ```Bash
+ $ cd <MySimulationFolder>
+ ```
+
+ - **Step 2 - Start the compilation script(s)**
+ ```Bash
+ $ /usr/local/lib/ghdl/vendors/compile-altera.sh --all
+ $ /usr/local/lib/ghdl/vendors/compile-lattice.sh --all
+ $ /usr/local/lib/ghdl/vendors/compile-xilinx-ise.sh --all
+ $ /usr/local/lib/ghdl/vendors/compile-xilinx-vivado.sh --all
+ $ /usr/local/lib/ghdl/vendors/compile-osvvm.sh --all
+ $ /usr/local/lib/ghdl/vendors/compile-vunit.sh --all
+ ```
+
+ In most cases GHDL is installed into `/usr/local/`. The scripts are
+ installed into the `lib` directory.
+
+ - **Step 3 - Viewing the result**
+ This creates vendor directories in your current working directory and
+ compiles the vendor files into them.
+
+ ```Bash
+ $ ls -ahl
+ ...
+ drwxr-xr-x 2 <user> <group> 56K Nov 30 17:41 altera
+ drwxr-xr-x 2 <user> <group> 56K Nov 30 17:42 lattice
+ drwxr-xr-x 2 <user> <group> 56K Nov 30 17:48 osvvm
+ drwxr-xr-x 2 <user> <group> 56K Nov 30 17:58 vunit
+ drwxr-xr-x 2 <user> <group> 56K Nov 30 17:58 xilinx-ise
+ drwxr-xr-x 2 <user> <group> 56K Nov 30 17:48 xilinx-vivado
+ ```
+
+
+---------------------------------------------------------------------
+### Compiling on Windows
+
+ - **Step 0 - Configure the scripts (optional)**
+ See next section for how to configure `config.psm1`.
+
+ - **Step 1 - Browse to your simulation working directory**
+ ```PowerShell
+ PS> cd <MySimulationFolder>
+ ```
+
+ - **Step 2 - Start the compilation script(s)**
+ ```PowerShell
+ PS> <GHDL>\libraries\vendors\compile-altera.ps1 -All
+ PS> <GHDL>\libraries\vendors\compile-lattice.ps1 -All
+ PS> <GHDL>\libraries\vendors\compile-xilinx-ise.ps1 -All
+ PS> <GHDL>\libraries\vendors\compile-xilinx-vivado.ps1 -All
+ PS> <GHDL>\libraries\vendors\compile-osvvm.ps1 -All
+ PS> <GHDL>\libraries\vendors\compile-vunit.ps1 -All
+ ```
+
+ - **Step 3 - Viewing the result**
+ This creates vendor directories in your current working directory and
+ compiles the vendor files into them.
+
+ ```PowerShell
+ PS> dir
+ Directory: D:\temp\ghdl
+
+ Mode LastWriteTime Length Name
+ ---- ------------- ------ ----
+ d---- 20.11.2015 19:33 <DIR> altera
+ d---- 20.11.2015 19:38 <DIR> lattice
+ d---- 20.11.2015 19:38 <DIR> osvvm
+ d---- 20.11.2015 19:45 <DIR> vunit_lib
+ d---- 20.11.2015 19:06 <DIR> xilinx-ise
+ d---- 20.11.2015 19:40 <DIR> xilinx-vivado
+ ```
+
+---------------------------------------------------------------------
+### Configuration Files
+
+#### For Linux: `config.sh`
+
+Please open the `config.sh` file and set the dictionary entries for the
+installed vendor tools to the appropriate directory to your tool's installation
+directories. Use an empty string `""` for not installed tools.
+
+`config.sh`:
+```Bash
+declare -A InstallationDirectory
+InstallationDirectory[AlteraQuartus]="/opt/Altera/16.0"
+InstallationDirectory[LatticeDiamond]="/opt/Diamond/3.8_x64"
+InstallationDirectory[OSVVM]="/home/<user>/git/GitHub/osvvm"
+InstallationDirectory[VUnit]="/home/<user>/git/GitHub/vunit"
+InstallationDirectory[XilinxISE]="/opt/Xilinx/14.7"
+InstallationDirectory[XilinxVivado]="/opt/Xilinx/Vivado/2016.3"
+```
+
+#### For Windows: `config.psm1`
+
+Please open the `config.psm1` file and set the dictionary entries for the
+installed vendor tools to the appropriate directory to your tool's installation
+folder. Use an empty string `""` for not installed tools.
+
+`config.psm1`:
+```PowerShell
+$InstallationDirectory = @{
+ "AlteraQuartus" = "C:\Altera\16.0";
+ "LatticeDiamond" = "C:\Lattice\Diamond\3.8_x64";
+ "XilinxISE" = "C:\Xilinx\14.7\ISE_DS";
+ "XilinxVivado" = "C:\Xilinx\Vivado\2016.3";
+ "OSVVM" = "D:\git\GitHub\osvvm";
+ "VUnit" = "D:\git\GitHub\vunit"
+}
+```
+
+### Selectable Options for the Bash Scripts:
+
+*First I should translate the scripts before writing the docu...*
+
+ - Common parameters to most scripts:
+
+ -h --help Print the embedded help page(s).
+ -c --clean Cleanup directory before analyzing.
+ -n --no-warnings Don't show warnings. Report errors only.
+ -s --skip-existing Skip already compiled files (an *.o file exists).
+ -S --skip-largefiles Don't compile large entities like DSP and PCIe primitives.
+ -H --halt-on-error Stop compiling if an error occured.
+ - `compile-altera.sh`
+ Selectable libraries:
+
+ -a --all Compile all libraries, including common libraries, packages and device libraries.
+ --altera Compile base libraries like 'altera' and 'altera_mf'
+ --max Compile device libraries for Max CPLDs
+ --arria Compile device libraries for Arria FPGAs
+ --cyclone Compile device libraries for Cyclone FPGAs
+ --stratix Compile device libraries for Stratix FPGAs
+ Compile options:
+
+ --vhdl93 Compile selected libraries with VHDL-93 (default).
+ --vhdl2008 Compile selected libraries with VHDL-2008.
+ - `compile-xilinx-ise.sh`
+ Selectable libraries:
+
+ -a --all Compile all libraries, including common libraries, packages and device libraries.
+ --unisim Compile the unisim primitives
+ --unimacro Compile the unimacro macros
+ --simprim Compile the simprim primitives
+ --corelib Compile the xilinxcorelib macros
+ --secureip Compile the secureip primitives
+ Compile options:
+
+ --vhdl93 Compile selected libraries with VHDL-93 (default).
+ --vhdl2008 Compile selected libraries with VHDL-2008.
+ - `compile-xilinx-vivado.sh`
+ Selectable libraries:
+
+ -a --all Compile all libraries, including common libraries, packages and device libraries.
+ --unisim Compile the unisim primitives
+ --unimacro Compile the unimacro macros
+ --secureip Compile the secureip primitives
+ Compile options:
+
+ --vhdl93 Compile selected libraries with VHDL-93 (default).
+ --vhdl2008 Compile selected libraries with VHDL-2008.
+ - `compile-osvvm.sh`
+ Selectable libraries:
+
+ -a --all Compile all.
+ --osvvm Compile the OSVVM library.
+ - `compile-vunit.sh`
+ Selectable libraries:
+
+ -a --all Compile all.
+ --osvvm Compile the VUnit library.
+
+### Selectable Options for the PowerShell Scripts:
+
+ - Common parameters to all scripts:
+
+ -Help Print the embedded help page(s).
+ -Clean Cleanup directory before analyzing.
+ -SuppressWarnings Don't show warnings. Report errors only.
+ - `compile-altera.ps1`
+ Selectable libraries:
+
+ -All Compile all libraries, including common libraries, packages and device libraries.
+ -Altera Compile base libraries like 'altera' and 'altera_mf'
+ -Max Compile device libraries for Max CPLDs
+ -Arria Compile device libraries for Arria FPGAs
+ -Cyclone Compile device libraries for Cyclone FPGAs
+ -Stratix Compile device libraries for Stratix FPGAs
+ Compile options:
+
+ -VHDL93 Compile selected libraries with VHDL-93 (default).
+ -VHDL2008 Compile selected libraries with VHDL-2008.
+ - `compile-xilinx-ise.ps1`
+ Selectable libraries:
+
+ -All Compile all libraries, including common libraries, packages and device libraries.
+ -Unisim Compile the unisim primitives
+ -Unimacro Compile the unimacro macros
+ -Simprim Compile the simprim primitives
+ -CoreLib Compile the xilinxcorelib macros
+ -Secureip Compile the secureip primitives
+ Compile options:
+
+ -VHDL93 Compile selected libraries with VHDL-93 (default).
+ -VHDL2008 Compile selected libraries with VHDL-2008.
+ - `compile-xilinx-vivado.ps1`
+ Selectable libraries:
+
+ -All Compile all libraries, including common libraries, packages and device libraries.
+ -Unisim Compile the unisim primitives
+ -Unimacro Compile the unimacro macros
+ -Secureip Compile the secureip primitives
+ Compile options:
+
+ -VHDL93 Compile selected libraries with VHDL-93 (default).
+ -VHDL2008 Compile selected libraries with VHDL-2008.
+ - `compile-osvvm.ps1`
+ Selectable libraries:
+
+ -All Compile all.
+ -OSVVM Compile the OSVVM library.
+ - `compile-vunit.ps1`
+ Selectable libraries:
+
+ -All Compile all.
+ -VUnit Compile the VUnit library.
+
+------------------------
+Author: Patrick Lehmann
+Last update: 28.10.2016
+
+------------------------
+
+.. TODO: topic
+
+ - Vendor Primitives
+ - Alters / Intel
+ - Lattice
+ - OSVVM
+ - UVVM
+ - Xilinx ISE
+ - Xilinx Vivado
diff --git a/doc/building/index.rst b/doc/building/index.rst
new file mode 100644
index 000000000..d240ff94d
--- /dev/null
+++ b/doc/building/index.rst
@@ -0,0 +1,42 @@
+.. _BUILD:
+
+Building GHDL
+#############
+
+.. TODO: topic
+
+ `./BUILD.txt <https://github.com/tgingold/ghdl/blob/master/BUILD.txt>`_
+ Directory structure of the main branch [1138: #279]
+ Coverage, `gcov`, is unique to gcc. That specific difference is not explained anywhere. Should be added.
+ @1138 Backtraces optional -patchable-
+
+GCC backend
+=================
+
+- ./dist/gcc/INSTALL
+- ./gcc/README
+- Linux
+
+LLVM backend
+=================
+
+- Linux
+- Mac OS?
+- Windows MinGW 32/64
+
+Mcode backend
+=================
+
+- ./dist/mcode/README
+- Linux
+- Windows GNAT GPL (32 only)
+- Windows MinGW 32/64
+
+Test suites
+=================
+
+----------------
+
+.. TODO: topic
+
+ @1138 explain that there are two (maybe three with vhdl08 tests)
\ No newline at end of file
diff --git a/doc/changelog/2014/index.rst b/doc/changelog/2014/index.rst
new file mode 100644
index 000000000..5822e67e7
--- /dev/null
+++ b/doc/changelog/2014/index.rst
@@ -0,0 +1,20 @@
+.. _CHANGE:2014:
+
+2014
+####
+
+.. contents:: Content of this page
+ :local:
+
+.. only:: html
+
+ .. toctree::
+
+ v0.30 <v0.30>
+
+
+.. only:: latex
+
+ .. toctree::
+
+ v0.30 <v0.30>
diff --git a/doc/changelog/2014/v0.30.rst b/doc/changelog/2014/v0.30.rst
new file mode 100644
index 000000000..87ebef22f
--- /dev/null
+++ b/doc/changelog/2014/v0.30.rst
@@ -0,0 +1,4 @@
+.. _CHANGE:v0.30:
+
+New in 0.30 (xx.yy.2014)
+================================================================================================================================================================
diff --git a/doc/changelog/2015/index.rst b/doc/changelog/2015/index.rst
new file mode 100644
index 000000000..3a3dc1ed5
--- /dev/null
+++ b/doc/changelog/2015/index.rst
@@ -0,0 +1,20 @@
+.. _CHANGE:2015:
+
+2015
+####
+
+.. contents:: Content of this page
+ :local:
+
+.. only:: html
+
+ .. toctree::
+
+ v0.31 <v0.31>
+
+
+.. only:: latex
+
+ .. toctree::
+
+ v0.31 <v0.31>
diff --git a/doc/changelog/2015/v0.31.rst b/doc/changelog/2015/v0.31.rst
new file mode 100644
index 000000000..71bab8013
--- /dev/null
+++ b/doc/changelog/2015/v0.31.rst
@@ -0,0 +1,4 @@
+.. _CHANGE:v0.31:
+
+New in 0.31 (xx.yy.2015)
+================================================================================================================================================================
diff --git a/doc/changelog/2016/index.rst b/doc/changelog/2016/index.rst
new file mode 100644
index 000000000..340fb915d
--- /dev/null
+++ b/doc/changelog/2016/index.rst
@@ -0,0 +1,22 @@
+.. _CHANGE:2016:
+
+2016
+####
+
+.. contents:: Content of this page
+ :local:
+
+.. only:: html
+
+ .. toctree::
+
+ v0.33 <v0.33>
+ v0.32 <v0.32>
+
+
+.. only:: latex
+
+ .. toctree::
+
+ v0.32 <v0.32>
+ v0.33 <v0.33>
diff --git a/doc/changelog/2016/v0.32.rst b/doc/changelog/2016/v0.32.rst
new file mode 100644
index 000000000..ae6ff7a12
--- /dev/null
+++ b/doc/changelog/2016/v0.32.rst
@@ -0,0 +1,4 @@
+.. _CHANGE:v0.32:
+
+New in 0.32 (xx.yy.2016)
+================================================================================================================================================================
diff --git a/doc/changelog/2016/v0.33.rst b/doc/changelog/2016/v0.33.rst
new file mode 100644
index 000000000..676390771
--- /dev/null
+++ b/doc/changelog/2016/v0.33.rst
@@ -0,0 +1,4 @@
+.. _CHANGE:v0.33:
+
+New in 0.33 (xx.yy.2016)
+================================================================================================================================================================
diff --git a/doc/changelog/2017/index.rst b/doc/changelog/2017/index.rst
new file mode 100644
index 000000000..fa4ed0f1c
--- /dev/null
+++ b/doc/changelog/2017/index.rst
@@ -0,0 +1,20 @@
+.. _CHANGE:2017:
+
+2017
+####
+
+.. contents:: Content of this page
+ :local:
+
+.. only:: html
+
+ .. toctree::
+
+ v0.34 <v0.34>
+
+
+.. only:: latex
+
+ .. toctree::
+
+ v0.34 <v0.34>
diff --git a/doc/changelog/2017/v0.34.rst b/doc/changelog/2017/v0.34.rst
new file mode 100644
index 000000000..874a36728
--- /dev/null
+++ b/doc/changelog/2017/v0.34.rst
@@ -0,0 +1,4 @@
+.. _CHANGE:v0.34:
+
+New in 0.34 (xx.yy.2017)
+================================================================================================================================================================
diff --git a/doc/changelog/Roadmap.rst b/doc/changelog/Roadmap.rst
new file mode 100644
index 000000000..3577bc704
--- /dev/null
+++ b/doc/changelog/Roadmap.rst
@@ -0,0 +1,14 @@
+.. _INTRO:Contributing:
+
+Roadmap | 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
\ No newline at end of file
diff --git a/doc/changelog/index.rst b/doc/changelog/index.rst
new file mode 100644
index 000000000..959d68486
--- /dev/null
+++ b/doc/changelog/index.rst
@@ -0,0 +1,30 @@
+.. _CHANGE:
+
+Change Log
+##########
+
+.. only:: html
+
+ .. toctree::
+
+ 2017/index
+ 2016/index
+ 2015/index
+ 2014/index
+
+
+
+.. only:: latex
+
+ .. toctree::
+
+ 2014/index
+ 2015/index
+ 2016/index
+ 2017/index
+
+------------------------
+
+.. TODO: topic
+
+ `./NEWS <https://github.com/tgingold/ghdl/blob/master/NEWS>`_
diff --git a/doc/getting/Docker.rst b/doc/getting/Docker.rst
new file mode 100644
index 000000000..35a1c11b6
--- /dev/null
+++ b/doc/getting/Docker.rst
@@ -0,0 +1,31 @@
+.. _DOCKER:
+
+Docker containers
+#############
+
+What is docker? A primer
+=================
+
+Where are images hosted?
+=================
+
+docker-hub
+ghdl-tools
+Dockerfiles
+
+Launch options
+=================
+
+With(out) shared folder
+----------------
+
+Interactive/daemon
+----------------
+
+Shrinking
+----------------
+
+Additional tools, with(out) GUI
+----------------
+
+GtkWave, PoC, VUnit, OSVVM, UVVM
\ No newline at end of file
diff --git a/doc/getting/Releases.rst b/doc/getting/Releases.rst
new file mode 100644
index 000000000..0fbd4542d
--- /dev/null
+++ b/doc/getting/Releases.rst
@@ -0,0 +1,8 @@
+.. _RELEASE:
+
+Releases
+########
+
+.. TODO: topic
+
+ naming, stable, development, nightly
\ No newline at end of file
diff --git a/doc/intro/Contributing.rst b/doc/intro/Contributing.rst
new file mode 100644
index 000000000..8a0ba30bc
--- /dev/null
+++ b/doc/intro/Contributing.rst
@@ -0,0 +1,77 @@
+.. _INTRO:Contributing:
+
+Contributing
+############
+
+Despite all the testing and already reported `issues <https://github.com/tgingold/ghdl/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 <https://help.github.com/articles/closing-issues-via-commit-messages/>`_ PRs]
\ No newline at end of file
diff --git a/doc/intro/Copyrights.rst b/doc/intro/Copyrights.rst
new file mode 100644
index 000000000..06cc7e4a9
--- /dev/null
+++ b/doc/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: topic
+
+ 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 <https://github.com/tgingold/ghdl/issues/280#issuecomment-279595802>`_
\ No newline at end of file
diff --git a/doc/intro/WhatIsGHDL.rst b/doc/intro/WhatIsGHDL.rst
new file mode 100644
index 000000000..449ef5d01
--- /dev/null
+++ b/doc/intro/WhatIsGHDL.rst
@@ -0,0 +1,29 @@
+.. include:: <isonum.txt>
+
+.. _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/intro/WhatIsVHDL.rst b/doc/intro/WhatIsVHDL.rst
new file mode 100644
index 000000000..b70b3a723
--- /dev/null
+++ b/doc/intro/WhatIsVHDL.rst
@@ -0,0 +1,35 @@
+.. _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.
+
+----------------
+
+.. TODO: topic
+
+ @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/old_index.rst.txt b/doc/old_index.rst.txt
deleted file mode 100644
index fef600002..000000000
--- a/doc/old_index.rst.txt
+++ /dev/null
@@ -1,28 +0,0 @@
-.. GHDL documentation master file, created by
- sphinx-quickstart on Fri Nov 20 20:33:03 2015.
- You can adapt this file completely to your liking, but it should at least
- contain the root `toctree` directive.
-
-Welcome to GHDL's documentation!
-================================
-
-Contents:
-
-.. toctree::
- :maxdepth: 2
-
- Introduction
- Starting_with_GHDL
- Invoking_GHDL
- Simulation_and_runtime
- GHDL_implementation_of_VHDL
- GHDL_implementation_of_VITAL
- Flaws_and_bugs_report
- Copyrights
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`search`
-
diff --git a/doc/references/CommandReference.rst b/doc/references/CommandReference.rst
new file mode 100644
index 000000000..ed7869dba
--- /dev/null
+++ b/doc/references/CommandReference.rst
@@ -0,0 +1,6 @@
+.. _REF:Command:
+
+Command Reference
+#################
+
+
diff --git a/doc/references/ImplementationOfVHDL.rst b/doc/references/ImplementationOfVHDL.rst
new file mode 100644
index 000000000..6919d0ef8
--- /dev/null
+++ b/doc/references/ImplementationOfVHDL.rst
@@ -0,0 +1,487 @@
+.. _REF:ImplVHDL:
+
+***************************
+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/references/ImplementationOfVITAL.rst b/doc/references/ImplementationOfVITAL.rst
new file mode 100644
index 000000000..4ffb8159b
--- /dev/null
+++ b/doc/references/ImplementationOfVITAL.rst
@@ -0,0 +1,94 @@
+.. _REF:ImplVITAL:
+
+****************************
+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/using/InvokingGHDL.rst b/doc/using/InvokingGHDL.rst
new file mode 100644
index 000000000..d4bcda438
--- /dev/null
+++ b/doc/using/InvokingGHDL.rst
@@ -0,0 +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=<NAME>
+
+ .. index:: WORK library
+
+ Specify the name of the :samp:`WORK` library. Analyzed units are always
+ placed in the library logically named :samp:`WORK`. With this option,
+ you can set its name. By default, the name is :samp:`work`.
+
+ `GHDL` checks whether :samp:`WORK` is a valid identifier. Although being
+ more or less supported, the :samp:`WORK` identifier should not be an
+ extended identifier, since the filesystem may prevent it from correctly
+ working (due to case sensitivity or forbidden characters in filenames).
+
+ `VHDL` rules forbid you to add units to the :samp:`std` library.
+ Furthermore, you should not put units in the :samp:`ieee` library.
+
+
+.. option:: --workdir=<DIR>
+
+ Specify the directory where the :samp:`WORK` library is located. When this
+ option is not present, the :samp:`WORK` library is in the current
+ directory. The object files created by the compiler are always placed
+ in the same directory as the :samp:`WORK` library.
+
+ Use option :option:`-P` to specify where libraries other than :samp:`WORK`
+ are placed.
+
+
+.. option:: --std=<STD>
+
+ Specify the standard to use. By default, the standard is :samp:`93c`, which
+ means VHDL-93 accepting VHDL-87 syntax. For details on :samp:`STD` values see
+ :ref:`VHDL_standards`.
+
+
+.. option:: --ieee=<VER>
+
+ .. index:: ieee library
+ .. index:: synopsys library
+ .. index:: mentor library
+
+ Select the :samp:`IEEE` library to use. :samp:`VER` must be one of:
+
+ none
+ Do not supply an `IEEE` library. Any library clause with the :samp:`IEEE`
+ identifier will fail, unless you have created by your own a library with
+ the `IEEE` name.
+
+ standard
+ Supply an `IEEE` library containing only packages defined by
+ :samp:`ieee` standards. Currently, there are the multivalue logic system
+ packages :samp:`std_logic_1164` defined by IEEE 1164, the synthesis
+ packages , :samp:`numeric_bit` and :samp:`numeric_std` defined by IEEE
+ 1076.3, and the :samp:`vital` packages :samp:`vital_timing` and
+ :samp:`vital_primitives`, defined by IEEE 1076.4. The version of these
+ packages is defined by the VHDL standard used. See :ref:`VITAL_packages`,
+ for more details.
+
+ synopsys
+ Supply the former packages and the following additional packages:
+ :samp:`std_logic_arith`, :samp:`std_logic_signed`,
+ :samp:`std_logic_unsigned`, :samp:`std_logic_textio`.
+
+ These packages were created by some companies, and are popular. However
+ they are not standard packages, and have been placed in the `IEEE`
+ library without the permission from the :samp:`ieee`.
+
+ mentor
+ Supply the standard packages and the following additional package:
+ :samp:`std_logic_arith`. The package is a slight variation of a definitely
+ not standard but widely mis-used package.
+
+ To avoid errors, you must use the same `IEEE` library for all units of
+ your design, and during elaboration.
+
+
+.. option:: -P<DIRECTORY>
+
+ Add `DIRECTORY` to the end of the list of directories to be searched for
+ library files. 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=<PATH>
+
+ Use :file:`PATH` as the prefix path to find commands and pre-installed (std and
+ ieee) libraries.
+
+
+.. option:: --GHDL1=<COMMAND>
+
+ Use :samp:`COMMAND` as the command name for the compiler. If :samp:`COMMAND` is
+ not a path, then it is searched in the path.
+
+
+.. option:: --AS=<COMMAND>
+
+ 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=<COMMAND>
+
+ 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,<OPTION>
+
+ Pass `OPTION` as an option to the compiler.
+
+
+.. option:: -Wa,<OPTION>
+
+ Pass `OPTION` as an option to the assembler.
+
+
+.. option:: -Wl,<OPTION>
+
+ Pass `OPTION` as an option to the linker.
+
+GHDL Diagnostics Control
+========================
+
+.. option:: -fcolor-diagnostics
+.. option:: -fno-color-diagnostics
+
+ Control whether diagnostic messages are displayed in color. The
+ default is on when the standard output is a terminal.
+
+.. option:: -fdiagnostics-show-option
+.. option:: -fno-diagnostics-show-option
+
+ Control whether the warning option is displayed at the end of
+ warning messages, so that user can easily know how to disable it.
+
+
+GHDL warnings
+=============
+
+Some constructions are not erroneous but dubious. Warnings are diagnostic
+messages that report such constructions. Some warnings are reported only
+during analysis, others during elaboration.
+
+You could disable a warning by using the :samp:`--warn-no-XXX` or
+:samp:`-Wno-XX` instead of :samp:`--warn-XXX` or :samp:`-WXXX`.
+
+
+.. option:: --warn-reserved
+
+ Emit a warning if an identifier is a reserved word in a later VHDL standard.
+
+
+.. option:: --warn-default-binding
+
+ During analyze, warns if a component instantiation has neither
+ configuration specification nor default binding. This may be useful if you
+ want to detect during analyze possibly unbound component if you don't use
+ configuration. :ref:`VHDL_standards`, for more details about default binding
+ rules.
+
+
+.. option:: --warn-binding
+
+ During elaboration, warns if a component instantiation is not bound
+ (and not explicitly left unbound). Also warns if a port of an entity
+ is not bound in a configuration specification or in a component
+ configuration. This warning is enabled by default, since default
+ binding rules are somewhat complex and an unbound component is most
+ often unexpected.
+
+ However, warnings are even emitted if a component instantiation is
+ inside a generate statement. As a consequence, if you use the conditional
+ generate statement to select a component according to the implementation,
+ you will certainly get warnings.
+
+
+.. option:: --warn-library
+
+ Warns if a design unit replaces another design unit with the same name.
+
+
+.. option:: --warn-vital-generic
+
+ Warns if a generic name of a vital entity is not a vital generic name. This
+ is set by default.
+
+
+.. option:: --warn-delayed-checks
+
+ Warns for checks that cannot be done during analysis time and are
+ postponed to elaboration time. This is because not all procedure
+ bodies are available during analysis (either because a package body
+ has not yet been analysed or because `GHDL` doesn't read not required
+ package bodies).
+
+ These are checks for no wait statement in a procedure called in a
+ sensitized process and checks for pure rules of a function.
+
+
+.. option:: --warn-body
+
+ Emit a warning if a package body which is not required is analyzed. If a
+ package does not declare a subprogram or a deferred constant, the package
+ does not require a body.
+
+
+.. option:: --warn-specs
+
+ Emit a warning if an all or others specification does not apply.
+
+
+.. option:: --warn-unused
+
+ Emit a warning when a subprogram is never used.
+
+
+.. option:: --warn-error
+
+ When this option is set, warnings are considered as errors.
+
+
+.. option:: --warn-nested-comment
+
+ Emit a warning if a :samp:`/*` appears within a block comment (vhdl 2008).
+
+
+.. option:: --warn-parenthesis
+
+ Emit a warning in case of weird use of parenthesis
+
+
+.. option:: --warn-runtime-error
+
+ Emit a warning in case of runtime error that is detected during
+ analysis.
+
+
+Rebuilding commands
+===================
+
+Analyzing and elaborating a design consisting in several files can be tricky,
+due to dependencies. GHDL has a few commands to rebuild a design.
+
+Import command
+--------------
+
+.. index:: importing files
+
+.. index:: -i command
+
+Add files in the work design library::
+
+ ghdl -i [options] file...
+
+
+All the files specified in the command line are scanned, parsed and added in
+the libraries but as not yet analyzed. No object files are created.
+
+The purpose of this command is to localize design units in the design files.
+The make command will then be able to recursively build a hierarchy from
+an entity name or a configuration name.
+
+Since the files are parsed, there must be correct files. However, since they
+are not analyzed, many errors are tolerated by this command.
+
+Note that all the files are added to the work library. If you have many
+libraries, you must use the command for each library.
+
+See :ref:`Make_command`, to actually build the design.
+
+.. _Make_command:
+
+Make command
+------------
+
+.. index:: make
+
+.. index:: -m command
+
+
+Analyze automatically outdated files and elaborate a design::
+
+ ghdl -m [options] primary [secondary]
+
+
+The primary unit denoted by the :samp:`primary` argument must already be
+known by the system, either because you have already analyzed it (even
+if you have modified it) or because you have imported it. GHDL analyzes
+all outdated files. A file may be outdated because it has been modified
+(e.g. you just have edited it), or because a design unit contained in
+the file depends on a unit which is outdated. This rule is of course
+recursive.
+
+With the @code{-b} (bind only) option, GHDL will stop before the final linking
+step. This is useful when the main entry point is not GHDL and you're linking
+GHDL object files into a foreign program.
+
+With the :option:`-f` (force) option, GHDL analyzes all the units of the
+work library needed to create the design hierarchy. Not outdated units
+are recompiled. This is useful if you want to compile a design hierarchy
+with new compilation flags (for example, to add the *-g*
+debugging option).
+
+The make command will only re-analyze design units in the work library.
+GHDL fails if it has to analyze an outdated unit from another library.
+
+The purpose of this command is to be able to compile a design without prior
+knowledge of file order. In the VHDL model, some units must be analyzed
+before others (e.g. an entity before its architecture). It might be a
+nightmare to analyze a full design of several files, if you don't have
+the ordered list of file. This command computes an analysis order.
+
+The make command fails when a unit was not previously parsed. For
+example, if you split a file containing several design units into
+several files, you must either import these new files or analyze them so
+that GHDL knows in which file these units are.
+
+The make command imports files which have been modified. Then, a design
+hierarchy is internally built as if no units are outdated. Then, all outdated
+design units, using the dependencies of the design hierarchy, are analyzed.
+If necessary, the design hierarchy is elaborated.
+
+This is not perfect, since the default architecture (the most recently
+analyzed one) may change while outdated design files are analyzed. In
+such a case, re-run the make command of GHDL.
+
+Generate Makefile command
+-------------------------
+
+.. index:: --gen-makefile command
+
+Generate a Makefile to build a design unit::
+
+ ghdl --gen-makefile [options] primary [secondary]
+
+
+This command works like the make command (see :ref:`Make_command`), but only a
+makefile is generated on the standard output.
+
+Library commands
+================
+
+GHDL has a few commands which act on a library.
+
+Directory command
+-----------------
+
+.. index:: displaying library
+
+.. index:: --dir command
+.. option::--dir
+
+Display the name of the units contained in a design library::
+
+ ghdl --dir [options] [libs]
+
+The directory command, selected with the `--dir` command line argument
+displays the content of the design libraries (by default the
+:samp:`work` library). All options are
+allowed, but only a few are meaningful: :option:`--work=NAME`,
+:option:`--workdir=PATH` and :option:`--std=VER`.
+
+Clean command
+-------------
+
+.. index:: cleaning
+
+.. index:: --clean command
+
+Remove object and executable files but keep the library::
+
+ ghdl --clean [options]
+
+
+GHDL tries to remove any object, executable or temporary file it could
+have created. Source files are not removed.
+
+There is no short command line form for this option to prevent accidental
+clean up.
+
+.. _Remove_command:
+
+Remove command
+--------------
+
+.. index:: cleaning all
+
+.. index:: --remove command
+
+Do like the clean command but remove the library too::
+
+ ghdl --remove [options]
+
+
+There is no short command line form for this option to prevent accidental
+clean up. Note that after removing a design library, the files are not
+known anymore by GHDL.
+
+.. _Copy_command:
+
+Copy command
+------------
+
+.. index:: copying library
+
+.. index:: --copy command
+
+Make a local copy of an existing library::
+
+ ghdl --copy --work=name [options]
+
+
+Make a local copy of an existing library. This is very useful if you want to
+add unit to the :samp:`ieee` library:
+
+.. code-block:: shell
+
+ ghdl --copy --work=ieee --ieee=synopsys
+ ghdl -a --work=ieee numeric_unsigned.vhd
+
+
+.. _Create_a_Library:
+
+Create a Library
+----------------
+
+.. index:: create your own library
+
+A new library is created by compiling entities (packages etc.) into it::
+
+ ghdl -a --work=my_custom_lib my_file.vhd
+
+
+A library's source code is usually stored and compiled into its own directory,
+that you specify with the :option:`--workdir` option::
+
+ ghdl -a --work=my_custom_lib --workdir=my_custom_libdir my_custom_lib_srcdir/my_file.vhd
+
+
+See also the :option:`-PPATH` command line option.
+
+.. _Cross-reference_command:
+
+Cross-reference command
+=======================
+
+To easily navigate through your sources, you may generate cross-references::
+
+ ghdl --xref-html [options] file...
+
+
+This command generates an html file for each :samp:`file` given in the command
+line, with syntax highlighting and full cross-reference: every identifier is
+a link to its declaration. Besides, an index of the files is created too.
+
+The set of :samp:`file` are analyzed, and then, if the analysis is
+successful, html files are generated in the directory specified by the
+:option:`-o dir` option, or :file:`html/` directory by default.
+
+If the option :option:`--format=html2` is specified, then the generated html
+files follow the HTML 2.0 standard, and colours are specified with
+`<FONT>` tags. However, colours are hard-coded.
+
+If the option :option:`--format=css` is specified, then the generated html files
+follow the HTML 4.0 standard, and use the CSS-1 file :file:`ghdl.css` to
+specify colours. This file is generated only if it does not already exist (it
+is never overwritten) and can be customized by the user to change colours or
+appearance. Refer to a generated file and its comments for more information.
+
+File commands
+=============
+
+The following commands act on one or several files. They do not analyze
+files, therefore, they work even if a file has semantic errors.
+
+Pretty print command
+--------------------
+
+.. index:: --pp-html command
+
+.. index:: pretty printing
+
+.. index:: vhdl to html
+
+Generate HTML on standard output from VHDL::
+
+ ghdl --pp-html [options] file...
+
+
+The files are just scanned and an html file, with syntax highlighting is
+generated on standard output.
+
+Since the files are not even parsed, erroneous files or incomplete designs
+can be pretty printed.
+
+The style of the html file can be modified with the :option:`--format=` option.
+By default or when the :option:`--format=html2` option is specified, the output
+is an HTML 2.0 file, with colours set through `<FONT>` tags. When the
+:option:`--format=css` option is specified, the output is an HTML 4.0 file,
+with colours set through a CSS file, whose name is :file:`ghdl.css`.
+See :ref:`Cross-reference_command`, for more details about this CSS file.
+
+Find command
+------------
+
+.. index:: -f command
+
+Display the name of the design units in files::
+
+ ghdl -f file...
+
+
+The files are scanned, parsed and the names of design units are displayed.
+Design units marked with two stars are candidate to be at the apex of a
+design hierarchy.
+
+Chop command
+------------
+
+.. index:: --chop command
+
+Chop (or split) files at design unit::
+
+ ghdl --chop files
+
+
+`GHDL` reads files, and writes a file in the current directory for
+every design unit.
+
+The filename of a design unit is build according to the unit. For an
+entity declaration, a package declaration or a configuration the file
+name is :file:`NAME.vhdl`, where `NAME` is the name of the design
+unit. For a package body, the filename is :file:`NAME-body.vhdl`.
+Finally, for an architecture `ARCH` of an entity `ENTITY`, the
+filename is :file:`ENTITY-ARCH.vhdl`.
+
+Since the input files are parsed, this command aborts in case of syntax
+error. The command aborts too if a file to be written already exists.
+
+Comments between design units are stored into the most adequate files.
+
+This command may be useful to split big files, if your computer has not
+enough memory to compile such files. The size of the executable is
+reduced too.
+
+Lines command
+-------------
+
+.. index:: --lines command
+
+Display on the standard output lines of files preceded by line number::
+
+ ghdl --lines files
+
+
+Misc commands
+=============
+
+There are a few GHDL commands which are seldom useful.
+
+.. _Help_command:
+
+Help command
+------------
+
+.. index:: -h command
+
+.. index:: --help command
+
+Display (on the standard output) a short description of the all the commands
+available. If the help switch is followed by a command switch, then options
+for this later command are displayed::
+
+ ghdl --help
+ ghdl -h
+ ghdl -h command
+
+
+.. _Disp_config_command:
+
+Disp config command
+-------------------
+
+.. index:: --disp-config command
+
+.. index:: display configuration
+
+Display the program paths and options used by GHDL::
+
+ ghdl --disp-config [options]
+
+
+This may be useful to track installation errors.
+
+Disp standard command
+---------------------
+
+.. index:: --disp-standard command
+
+.. index:: display :samp:`std.standard`
+
+Display the :samp:`std.standard` package::
+
+ ghdl --disp-standard [options]
+
+
+Version command
+---------------
+
+.. index:: --version command
+
+.. index:: version
+
+Display the `GHDL` version and exit::
+
+ ghdl --version
+
+
+VPI build commands
+==================
+
+These commands simplify the compile and the link of a user vpi
+module. They are all wrapper: the arguments are in fact a whole
+command line that is executed with additional switches. Currently a
+unix-like compiler (like `cc`, `gcc` or `clang`) is expected: the additional
+switches use their syntax. The only option is `-v` which displays the
+command before its execution.
+
+.. _VPI_compile_command:
+
+VPI compile command
+-------------------
+
+.. index:: --vpi-compile command
+
+Add include path to the command and execute it::
+
+ ghdl --vpi-compile command
+
+This will execute::
+
+ command -Ixxx/include
+
+For example::
+
+ ghdl --vpi-compile gcc -c vpi1.c
+
+executes::
+
+ gcc -c vpi1.c -fPIC -Ixxx/include
+
+.. _VPI_link_command:
+
+VPI link command
+----------------
+
+.. index:: --vpi-link command
+
+Add library path and name to the command and execute it::
+
+ ghdl --vpi-link command
+
+This will execute::
+
+ command -Lxxx/lib -lghdlvpi
+
+For example::
+
+ ghdl --vpi-link gcc -o vpi1.vpi vpi1.o
+
+executes::
+
+ gcc -o vpi1.vpi vpi1.o --shared -Lxxx/lib -lghdlvpi
+
+
+.. _VPI_cflags_command:
+
+VPI cflags command
+------------------
+
+.. index:: --vpi-cflags command
+
+Display flags added by :option:`--vpi-compile`::
+
+ ghdl --vpi-cflags
+
+
+.. _VPI_ldflags_command:
+
+VPI ldflags command
+-------------------
+
+.. index:: --vpi-ldflags command
+
+Display flags added by :option:`--vpi-link`::
+
+ ghdl --vpi-ldflags
+
+.. _VPI_include_dir_command:
+
+VPI include dir command
+-----------------------
+
+.. index:: --vpi-include-dir command
+
+Display the include directory added by the compile flags::
+
+ ghdl --vpi-include-dir
+
+.. _VPI_library_dir_command:
+
+VPI library dir command
+-----------------------
+
+.. index:: --vpi-library-dir command
+
+Display the library directory added by the link flags::
+
+ ghdl --vpi-library-dir
+
+
+Installation Directory
+======================
+
+During analysis and elaboration `GHDL` may read the `std`
+and `ieee` files. The location of these files is based on the prefix,
+which is (in priority order):
+
+* the :option:`--PREFIX=` command line option
+
+* the :envvar:`GHDL_PREFIX` environment variable
+
+*
+ a built-in default path. It is a hard-coded path on GNU/Linux and the
+ value of the :samp:`HKLM\Software\Ghdl\Install_Dir` registry entry on Windows.
+
+You should use the :option:`--disp-config` command (:ref:`Disp_config_command` for details) to disp and debug installation problems.
+
+.. _ieee_library_pitfalls:
+
+IEEE library pitfalls
+=====================
+
+When you use options :option:`--ieee=synopsys` or :option:`--ieee=mentor`,
+the `IEEE` library contains non standard packages such as
+:samp:`std_logic_arith`.
+
+These packages are not standard because there are not described by an IEEE
+standard, even if they have been put in the `IEEE` library. Furthermore,
+they are not really de-facto standard, because there are slight differences
+between the packages of Mentor and those of Synopsys.
+
+Furthermore, since they are not well-thought, their use has pitfalls. For
+example, this description has error during compilation:
+
+.. code-block:: VHDL
+
+ library ieee;
+ use ieee.std_logic_1164.all;
+
+ -- A counter from 0 to 10.
+ entity counter is
+ port (val : out std_logic_vector (3 downto 0);
+ ck : std_logic;
+ rst : std_logic);
+ end counter;
+
+ library ieee;
+ use ieee.std_logic_unsigned.all;
+
+ architecture bad of counter
+ is
+ signal v : std_logic_vector (3 downto 0);
+ begin
+ process (ck, rst)
+ begin
+ if rst = '1' then
+ v <= x"0";
+ elsif rising_edge (ck) then
+ if v = "1010" then -- Error
+ v <= x"0";
+ else
+ v <= v + 1;
+ end if;
+ end if;
+ end process;
+
+ val <= v;
+ end bad;
+
+
+When you analyze this design, GHDL does not accept it (too long lines
+have been split for readability):
+
+.. code-block:: shell
+
+ ghdl -a --ieee=synopsys bad_counter.vhdl
+ bad_counter.vhdl:13:14: operator "=" is overloaded
+ bad_counter.vhdl:13:14: possible interpretations are:
+ ../../libraries/ieee/std_logic_1164.v93:69:5: implicit function "="
+ [std_logic_vector, std_logic_vector return boolean]
+ ../../libraries/synopsys/std_logic_unsigned.vhdl:64:5: function "="
+ [std_logic_vector, std_logic_vector return boolean]
+ ../translate/ghdldrv/ghdl: compilation error
+
+Indeed, the `"="` operator is defined in both packages, and both
+are visible at the place it is used. The first declaration is an
+implicit one, which occurs when the `std_logic_vector` type is
+declared and is an element to element comparison, the second one is an
+explicit declared function, with the semantic of an unsigned comparison.
+
+With some analyser, the explicit declaration has priority over the implicit
+declaration, and this design can be analyzed without error. However, this
+is not the rule given by the VHDL LRM, and since GHDL follows these rules,
+it emits an error.
+
+You can force GHDL to use this rule with the *-fexplicit* option.
+:ref:`GHDL_options`, for more details.
+
+However it is easy to fix this error, by using a selected name:
+
+.. code-block:: VHDL
+
+ library ieee;
+ use ieee.std_logic_unsigned.all;
+
+ architecture fixed_bad of counter
+ is
+ signal v : std_logic_vector (3 downto 0);
+ begin
+ process (ck, rst)
+ begin
+ if rst = '1' then
+ v <= x"0";
+ elsif rising_edge (ck) then
+ if ieee.std_logic_unsigned."=" (v, "1010") then
+ v <= x"0";
+ else
+ v <= v + 1;
+ end if;
+ end if;
+ end process;
+
+ val <= v;
+ end fixed_bad;
+
+
+It is better to only use the standard packages defined by IEEE, which
+provides the same functionalities:
+
+.. code-block:: VHDL
+
+ library ieee;
+ use ieee.numeric_std.all;
+
+ architecture good of counter
+ is
+ signal v : unsigned (3 downto 0);
+ begin
+ process (ck, rst)
+ begin
+ if rst = '1' then
+ v <= x"0";
+ elsif rising_edge (ck) then
+ if v = "1010" then
+ v <= x"0";
+ else
+ v <= v + 1;
+ end if;
+ end if;
+ end process;
+
+ val <= std_logic_vector (v);
+ end good;
+
+
+IEEE math packages
+==================
+
+.. index:: Math_Real
+
+.. index:: Math_Complex
+
+The :samp:`ieee` math packages (:samp:`math_real` and
+:samp:`math_complex`) provided with `GHDL` are fully compliant with
+the `IEEE` standard.
diff --git a/doc/using/QuickStartGuide.rst b/doc/using/QuickStartGuide.rst
new file mode 100644
index 000000000..bbaf3894d
--- /dev/null
+++ b/doc/using/QuickStartGuide.rst
@@ -0,0 +1,359 @@
+.. _USING:QuickStart:
+
+******************
+Quick Start Guide
+******************
+
+In this chapter, you will learn how to use the GHDL compiler by
+working on two examples.
+
+The hello world program
+=======================
+
+To illustrate the large purpose of VHDL, here is a commented VHDL
+"Hello world" program.
+
+.. code-block:: VHDL
+
+ -- Hello world program.
+ use std.textio.all; -- Imports the standard textio package.
+
+ -- Defines a design entity, without any ports.
+ entity hello_world is
+ end hello_world;
+
+ architecture behaviour of hello_world is
+ begin
+ process
+ variable l : line;
+ begin
+ write (l, String'("Hello world!"));
+ writeline (output, l);
+ wait;
+ end process;
+ end behaviour;
+
+Suppose this program is contained in the file :file:`hello.vhdl`.
+First, you have to compile the file; this is called `analysis` of a design
+file in VHDL terms.
+
+.. code-block:: shell
+
+ $ ghdl -a hello.vhdl
+
+This command creates or updates a file :file:`work-obj93.cf`, which
+describes the library `work`. On GNU/Linux, this command generates a
+file :file:`hello.o`, which is the object file corresponding to your
+VHDL program. The object file is not created on Windows.
+
+Then, you have to build an executable file.
+
+.. code-block:: shell
+
+ $ ghdl -e hello_world
+
+The :option:`-e` option means :dfn:`elaborate`. With this option, `GHDL`
+creates code in order to elaborate a design, with the :samp:`hello_world`
+entity at the top of the hierarchy.
+
+On GNU/Linux, if you have enabled the GCC backend during the compilation of `GHDL`,
+an executable program called :file:`hello_world` which can be run is generated:
+
+.. code-block:: shell
+
+ $ ghdl -r hello_world
+
+or directly:
+
+.. code-block:: shell
+
+ $ ./hello_world
+
+
+On Windows or if the GCC backend was not enabled, no file is created.
+The simulation is launched using this command:
+
+.. code-block:: shell
+
+ > ghdl -r hello_world
+
+
+The result of the simulation appears on the screen::
+
+ Hello world!
+
+
+A full adder
+============
+
+VHDL is generally used for hardware design. This example starts with
+a full adder described in the :file:`adder.vhdl` file:
+
+.. code-block:: VHDL
+
+ entity adder is
+ -- `i0`, `i1` and the carry-in `ci` are inputs of the adder.
+ -- `s` is the sum output, `co` is the carry-out.
+ port (i0, i1 : in bit; ci : in bit; s : out bit; co : out bit);
+ end adder;
+
+ architecture rtl of adder is
+ begin
+ -- This full-adder architecture contains two concurrent assignment.
+ -- Compute the sum.
+ s <= i0 xor i1 xor ci;
+ -- Compute the carry.
+ co <= (i0 and i1) or (i0 and ci) or (i1 and ci);
+ end rtl;
+
+
+You can analyze this design file:
+
+.. code-block:: shell
+
+ $ ghdl -a adder.vhdl
+
+
+You can try to execute the `adder` design, but this is useless,
+since nothing externally visible will happen. In order to
+check this full adder, a testbench has to be run. This testbench is
+very simple, since the adder is also simple: it checks exhaustively all
+inputs. Note that only the behaviour is tested, timing constraints are
+not checked. The file :file:`adder_tb.vhdl` contains the testbench for
+the adder:
+
+.. code-block:: VHDL
+
+ -- A testbench has no ports.
+ entity adder_tb is
+ end adder_tb;
+
+ architecture behav of adder_tb is
+ -- Declaration of the component that will be instantiated.
+ component adder
+ port (i0, i1 : in bit; ci : in bit; s : out bit; co : out bit);
+ end component;
+
+ -- Specifies which entity is bound with the component.
+ for adder_0: adder use entity work.adder;
+ signal i0, i1, ci, s, co : bit;
+ begin
+ -- Component instantiation.
+ adder_0: adder port map (i0 => i0, i1 => i1, ci => ci,
+ s => s, co => co);
+
+ -- This process does the real job.
+ process
+ type pattern_type is record
+ -- The inputs of the adder.
+ i0, i1, ci : bit;
+ -- The expected outputs of the adder.
+ s, co : bit;
+ end record;
+ -- The patterns to apply.
+ type pattern_array is array (natural range <>) of pattern_type;
+ constant patterns : pattern_array :=
+ (('0', '0', '0', '0', '0'),
+ ('0', '0', '1', '1', '0'),
+ ('0', '1', '0', '1', '0'),
+ ('0', '1', '1', '0', '1'),
+ ('1', '0', '0', '1', '0'),
+ ('1', '0', '1', '0', '1'),
+ ('1', '1', '0', '0', '1'),
+ ('1', '1', '1', '1', '1'));
+ begin
+ -- Check each pattern.
+ for i in patterns'range loop
+ -- Set the inputs.
+ i0 <= patterns(i).i0;
+ i1 <= patterns(i).i1;
+ ci <= patterns(i).ci;
+ -- Wait for the results.
+ wait for 1 ns;
+ -- Check the outputs.
+ assert s = patterns(i).s
+ report "bad sum value" severity error;
+ assert co = patterns(i).co
+ report "bad carry out value" severity error;
+ end loop;
+ assert false report "end of test" severity note;
+ -- Wait forever; this will finish the simulation.
+ wait;
+ end process;
+ end behav;
+
+
+As usual, you should analyze the design:
+
+.. code-block:: shell
+
+ $ ghdl -a adder_tb.vhdl
+
+And build an executable for the testbench:
+
+.. code-block:: shell
+
+ $ ghdl -e adder_tb
+
+You do not need to specify which object files are required: GHDL knows them
+and automatically adds them in the executable. Now, it is time to run the
+testbench:
+
+.. code-block:: shell
+
+ $ ghdl -r adder_tb
+ adder_tb.vhdl:52:7:(assertion note): end of test
+
+
+If your design is rather complex, you'd like to inspect signals. Signals
+value can be dumped using the VCD file format. The resulting file can be
+read with a wave viewer such as GTKWave. First, you should simulate your
+design and dump a waveform file:
+
+.. code-block:: shell
+
+ $ ghdl -r adder_tb --vcd=adder.vcd
+
+Then, you may now view the waves:
+
+.. code-block:: shell
+
+ $ gtkwave adder.vcd
+
+See :ref:`Simulation_options`, for more details on the :option:`--vcd` option and
+other runtime options.
+
+
+Starting with a design
+======================
+
+Unless you are only studying VHDL, you will work with bigger designs than
+the ones of the previous examples.
+
+Let's see how to analyze and run a bigger design, such as the DLX model
+suite written by Peter Ashenden which is distributed under the terms of the
+GNU General Public License. A copy is kept on
+http://ghdl.free.fr/dlx.tar.gz
+
+First, untar the sources:
+
+.. code-block:: shell
+
+ $ tar zxvf dlx.tar.gz
+
+
+In order not to pollute the sources with the library, it is a good idea
+to create a :file:`work/` subdirectory for the `WORK` library. To
+any GHDL commands, we will add the :option:`--workdir=work` option, so
+that all files generated by the compiler (except the executable) will be
+placed in this directory.
+
+.. code-block:: shell
+
+ $ cd dlx
+ $ mkdir work
+
+
+We will run the :samp:`dlx_test_behaviour` design. We need to analyze
+all the design units for the design hierarchy, in the correct order.
+GHDL provides an easy way to do this, by importing the sources:
+
+.. code-block:: shell
+
+ $ ghdl -i --workdir=work *.vhdl
+
+
+and making a design:
+
+.. code-block:: shell
+
+ $ ghdl -m --workdir=work dlx_test_behaviour
+
+
+Before this second stage, GHDL knows all the design units of the DLX,
+but no one have been analyzed. The make command of GHDL analyzes and
+elaborates a design. This creates many files in the :file:`work/`
+directory, and the :file:`dlx_test_behaviour` executable in the current
+directory.
+
+The simulation needs to have a DLX program contained in the file
+:file:`dlx.out`. This memory image will be be loaded in the DLX memory.
+Just take one sample:
+
+.. code-block:: shell
+
+ $ cp test_loop.out dlx.out
+
+
+And you can run the test suite:
+
+.. code-block:: shell
+
+ $ ghdl -r --workdir=work dlx_test_behaviour
+
+
+The test bench monitors the bus and displays each instruction executed.
+It finishes with an assertion of severity level note:
+
+.. code-block:: shell
+
+ dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction
+ encountered, execution halted
+
+
+Since the clock is still running, you have to manually stop the program
+with the :kbd:`C-c` key sequence. This behavior prevents you from running the
+test bench in batch mode. However, you may force the simulator to
+stop when an assertion above or equal a certain severity level occurs:
+
+.. code-block:: shell
+
+ $ ghdl -r --workdir=work dlx_test_behaviour --assert-level=note
+
+
+With this option, the program stops just after the previous message::
+
+ dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction
+ encountered, execution halted
+ error: assertion failed
+
+
+If you want to make room on your hard drive, you can either:
+
+* clean the design library with the GHDL command:
+
+ .. code-block:: shell
+
+ $ ghdl --clean --workdir=work
+
+ This removes the executable and all the object files. If you want to
+ rebuild the design at this point, just do the make command as shown
+ above.
+
+* remove the design library with the GHDL command:
+
+ .. code-block:: shell
+
+ $ ghdl --remove --workdir=work
+
+ This removes the executable, all the object files and the library file.
+ If you want to rebuild the design, you have to import the sources again,
+ and to make the design.
+
+* remove the :file:`work/` directory:
+
+ .. code-block:: shell
+
+ $ rm -rf work
+
+ Only the executable is kept. If you want to rebuild the design, create
+ the :file:`work/` directory, import the sources, and make the design.
+
+Sometimes, a design does not fully follow the VHDL standards. For example it
+uses the badly engineered :samp:`std_logic_unsigned` package. GHDL supports
+this VHDL dialect through some options::
+
+ --ieee=synopsys -fexplicit
+
+See :ref:`IEEE_library_pitfalls`, for more details.
+
diff --git a/doc/using/Simulation.rst b/doc/using/Simulation.rst
new file mode 100644
index 000000000..73c74bcd0
--- /dev/null
+++ b/doc/using/Simulation.rst
@@ -0,0 +1,292 @@
+.. _USING:Simulation:
+
+**********************
+Simulation and runtime
+**********************
+
+.. _simulation_options:
+
+Simulation options
+==================
+
+In most system environments, it is possible to pass options while
+invoking a program. Contrary to most programming languages, there is no
+standard method in VHDL to obtain the arguments or to set the exit
+status.
+
+In GHDL, it is impossible to pass parameters to your design. A later version
+could do it through the generics interfaces of the top entity.
+
+However, the GHDL runtime behaviour can be modified with some options; for
+example, it is possible to stop simulation after a certain time.
+
+The exit status of the simulation is :samp:`EXIT_SUCCESS` (0) if the
+simulation completes, or :samp:`EXIT_FAILURE` (1) in case of error
+(assertion failure, overflow or any constraint error).
+
+Here is the list of the most useful options. Some debugging options are
+also available, but not described here. The :option:`--help` options lists
+all options available, including the debugging one.
+
+
+
+.. option:: --assert-level=<LEVEL>
+
+ Select the assertion level at which an assertion violation stops the
+ simulation. `LEVEL` is the name from the `severity_level`
+ enumerated type defined in the `standard` package or the
+ :samp:`none` name.
+
+ By default, only assertion violation of severity level :samp:`failure`
+ stops the simulation.
+
+ For example, if `LEVEL` was :samp:`warning`, any assertion violation
+ with severity level :samp:`warning`, :samp:`error` or :samp:`failure` would
+ stop simulation, but the assertion violation at the :samp:`note` severity
+ level would only display a message.
+
+ Option :option:`--assert-level=none` prevents any assertion violation to stop
+ simulation.
+
+.. option:: --ieee-asserts=<POLICY>
+
+ Select how the assertions from :samp:`ieee` units are
+ handled. `POLICY` can be :samp:`enable` (the default),
+ :samp:`disable` which disables all assertion from :samp:`ieee` packages
+ and :samp:`disable-at-0` which disables only at start of simulation.
+
+ This option can be useful to avoid assertion message from
+ :samp:`ieee.numeric_std` (and other :samp:`ieee` packages).
+
+
+.. option:: --stop-time=<TIME>
+
+ Stop the simulation after :samp:`TIME`. :samp:`TIME` is expressed as a time
+ value, *without* any space. The time is the simulation time, not
+ the real clock time.
+
+ For example::
+
+ $ ./my_design --stop-time=10ns
+ $ ./my_design --stop-time=ps
+
+
+.. option:: --stop-delta=<N>
+
+ Stop the simulation after `N` delta cycles in the same current time.
+
+ .. index:: display time
+
+.. option:: --disp-time
+
+ Display the time and delta cycle number as simulation advances.
+
+
+.. option:: --disp-tree[=<KIND>]
+
+ .. index:: display design hierarchy
+
+ Display the design hierarchy as a tree of instantiated design entities.
+ This may be useful to understand the structure of a complex
+ design. `KIND` is optional, but if set must be one of:
+
+
+ * none
+ Do not display hierarchy. Same as if the option was not present.
+
+ * inst
+ Display entities, architectures, instances, blocks and generates statements.
+
+ * proc
+ Like :samp:`inst` but also display processes.
+
+ * port
+ Like :samp:`proc` but display ports and signals too.
+ If `KIND` is not specified, the hierarchy is displayed with the
+ :samp:`port` mode.
+
+
+.. option:: --no-run
+
+ Do not simulate, only elaborate. This may be used with
+ :option:`--disp-tree` to display the tree without simulating the whole
+ design.
+
+
+.. option:: --unbuffered
+
+ Disable buffering on stdout, stderr and files opened in write or append mode (TEXTIO).
+
+
+.. option:: --read-opt-file=<FILENAME>
+
+ Filter signals to be dumped to the wave file according to the wave option
+ file provided.
+
+ Here is a description of the wave option file format currently supported :
+
+ $ version = 1.1 # Optional
+
+ # Path format for signals in packages :
+ my_pkg.global_signal_a
+
+ # Path format for signals in entities :
+ /top/sub/clk
+
+ # Dumps every signals named reset in first level sub entities of top
+ /top/*/reset
+
+ # Dumps every signals named reset in recursive sub entities of top
+ /top/**/reset
+
+ # Dump every signals of sub2 which could be anywhere in design except on
+ # top level
+ /**/sub2/*
+
+ # Dump every signals of sub3 which must be a first level sub entity of the
+ # top level
+ /*/sub3/*
+
+ # Dump every signals of the first level sub entities of sub3 (but not
+ # those of sub3)
+ /**/sub3/*/*
+
+
+.. option:: --write-opt-file=<FILENAME>
+
+ If the wave option file doesn't exist, creates it with all the signals of
+ the design. Otherwise throws an error, because it won't erase an existing
+ file.
+
+
+.. option:: --vcd=<FILENAME>
+
+.. option:: --vcdgz=<FILENAME>
+
+ .. index:: vcd
+
+ .. index:: value change dump
+
+ .. index:: dump of signals
+
+ Option :option:`--vcd` dumps into the VCD file `FILENAME` the signal
+ values before each non-delta cycle. If `FILENAME` is :samp:`-`,
+ then the standard output is used, otherwise a file is created or
+ overwritten.
+
+ The :option:`--vcdgz` option is the same as the *--vcd* option,
+ but the output is compressed using the `zlib` (`gzip`
+ compression). However, you can't use the :samp:`-` filename.
+ Furthermore, only one VCD file can be written.
+
+ :dfn:`VCD` (value change dump) is a file format defined
+ by the `verilog` standard and used by virtually any wave viewer.
+
+ Since it comes from `verilog`, only a few VHDL types can be dumped. GHDL
+ dumps only signals whose base type is of the following:
+
+
+ * types defined in the :samp:`std.standard` package:
+
+ * :samp:`bit`
+
+ * :samp:`bit_vector`
+
+ * types defined in the :samp:`ieee.std_logic_1164` package:
+
+ * :samp:`std_ulogic`
+
+ * :samp:`std_logic` (because it is a subtype of :samp:`std_ulogic`)
+
+ * :samp:`std_ulogic_vector`
+
+ * :samp:`std_logic_vector`
+
+ * any integer type
+
+ I have successfully used `gtkwave` to view VCD files.
+
+ Currently, there is no way to select signals to be dumped: all signals are
+ dumped, which can generate big files.
+
+ It is very unfortunate there is no standard or well-known wave file
+ format supporting VHDL types. If you are aware of such a free format,
+ please mail me (:ref:`Reporting_bugs`).
+
+
+.. option:: --fst=<FILENAME>
+
+ Write the waveforms into a `fst`, that can be displayed by
+ `gtkwave`. The `fst` files are much smaller than VCD or
+ `GHW` files, but it handles only the same signals as the VCD format.
+
+
+.. option:: --wave=<FILENAME>
+
+ Write the waveforms into a `ghw` (GHdl Waveform) file. Currently, all
+ the signals are dumped into the waveform file, you cannot select a hierarchy
+ of signals to be dumped.
+
+ The format of this file was defined by myself and is not yet completely fixed.
+ It may change slightly. The :samp:`gtkwave` tool can read the GHW files.
+
+ Contrary to VCD files, any VHDL type can be dumped into a GHW file.
+
+
+.. option:: --psl-report=<FILENAME>
+
+ Write a report for PSL assertions and coverage at the end of
+ simulation. The file is written using the JSON format, but still
+ being human readable.
+
+
+.. option:: --sdf=<PATH>=<FILENAME>
+
+ Do VITAL annotation on `PATH` with SDF file :file:`FILENAME`.
+
+ `PATH` is a path of instances, separated with :samp:`.` or :samp:`/`.
+ Any separator can be used. Instances are component instantiation labels,
+ generate labels or block labels. Currently, you cannot use an indexed name.
+
+ Specifying a delay::
+
+ --sdf=min=<PATH>=<FILENAME>
+ --sdf=typ=<PATH>=<FILENAME>
+ --sdf=max=<PATH>=<FILENAME>
+
+ If the option contains a type of delay, that is :samp:`min=`,
+ :samp:`typ=` or :samp:`max=`, the annotator use respectively minimum,
+ typical or maximum values. If the option does not contain a type of delay,
+ the annotator use the typical delay.
+
+ See :ref:`Backannotation`, for more details.
+
+
+.. option:: --help
+
+ Display a short description of the options accepted by the runtime library.
+
+Debugging VHDL programs
+=======================
+
+.. index:: debugging
+
+.. index:: `__ghdl_fatal`
+
+Debugging VHDL programs using `GDB` is possible only on GNU/Linux systems.
+
+`GDB` is a general purpose debugger for programs compiled by `GCC`.
+Currently, there is no VHDL support for `GDB`. It may be difficult
+to inspect variables or signals in `GDB`, however, `GDB` is
+still able to display the stack frame in case of error or to set a breakpoint
+at a specified line.
+
+`GDB` can be useful to precisely catch a runtime error, such as indexing
+an array beyond its bounds. All error check subprograms call the
+`__ghdl_fatal` procedure. Therefore, to catch runtime error, set
+a breakpoint like this:
+
+ (gdb) break __ghdl_fatal
+
+When the breakpoint is hit, use the `where` or `bt` command to
+display the stack frames.
--
cgit v1.2.3