Removed numbers from folder names.

3 files changed, 587 insertions, 0 deletions

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.