diff options
Diffstat (limited to 'doc/references')
| -rw-r--r-- | doc/references/CodingStyle.rst | 6 | ||||
| -rw-r--r-- | doc/references/CommandReference.rst | 14 | ||||
| -rw-r--r-- | doc/references/ImplementationOfVHDL.rst | 100 | ||||
| -rw-r--r-- | doc/references/ImplementationOfVITAL.rst | 34 |
4 files changed, 77 insertions, 77 deletions
diff --git a/doc/references/CodingStyle.rst b/doc/references/CodingStyle.rst index b9da53804..6af869067 100644 --- a/doc/references/CodingStyle.rst +++ b/doc/references/CodingStyle.rst @@ -4,12 +4,12 @@ Coding Style ############ Ada subset: use only a simple (VHDL like) subset of Ada: no tasking, no -controlled types... VHDL users should easily understand that subset. +controlled types... VHDL users should easily understand that subset. Allowed Ada95 features: the standard library, child packages. Use assertions. We try to follow the 'GNU Coding Standards' when possible: comments before -declarations, two spaces at end of sentences, finish sentences with a dot. +declarations, one space at the end of sentences, finish sentences with a dot. But: 2 spaces for indentation in code blocks. No trailing spaces, no TAB (HT). @@ -22,7 +22,7 @@ Subprograms must have a comment before to describe them, like: procedure Sem_Concurrent_Statement_Chain (Parent : Iir); The line before the comment must be a blank line (unless this is the first -declaration). Don't repeat the comment before the subprogram body. +declaration). Don't repeat the comment before the subprogram body. * For subprograms: diff --git a/doc/references/CommandReference.rst b/doc/references/CommandReference.rst index 06fdb7396..de6ff5415 100644 --- a/doc/references/CommandReference.rst +++ b/doc/references/CommandReference.rst @@ -24,7 +24,7 @@ Help [``-h``] .. option:: --help, -h 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 +available. If the help switch is followed by a command switch, then options for that second command are displayed:: ghdl --help @@ -126,7 +126,7 @@ Bind [``--bind``] .. option:: --bind <[options] primary_unit [secondary_unit]> -Performs only the first stage of the elaboration command; the list of object files is created but the executable is not built. This command should be used only when the main entry point is not GHDL. +Performs only the first stage of the elaboration command; the list of object files is created but the executable is not built. This command should be used only when the main entry point is not GHDL. .. index:: cmd GCC/LLVM linking @@ -155,25 +155,25 @@ Allow multi-bytes chars in a comment. .. 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. +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 the synthesizer rule. -There are two key points: normal VHDL LRM rules are tried first and entities are searched only in known libraries. A known library is a library which has been named in your design. +There are two key points: normal VHDL LRM rules are tried first and entities are searched only in known libraries. A known library is a library which has been named in your design. This option is only useful during elaboration. .. option:: --GHDL1<=COMMAND> -Use ``COMMAND`` as the command name for the compiler. If ``COMMAND`` is not a path, then it is searched in the path. +Use ``COMMAND`` as the command name for the compiler. If ``COMMAND`` is not a path, then it is searched in the path. .. option:: --AS<=COMMAND> -Use ``COMMAND`` as the command name for the assembler. If ``COMMAND`` is not a path, then it is searched in the path. The default is ``as``. +Use ``COMMAND`` as the command name for the assembler. If ``COMMAND`` is not a path, then it is searched in the path. The default is ``as``. .. option:: --LINK<=COMMAND> -Use ``COMMAND`` as the linker driver. If ``COMMAND`` is not a path, then it is searched in the path. The default is ``gcc``. +Use ``COMMAND`` as the linker driver. If ``COMMAND`` is not a path, then it is searched in the path. The default is ``gcc``. Passing options to other programs ================================= diff --git a/doc/references/ImplementationOfVHDL.rst b/doc/references/ImplementationOfVHDL.rst index 3cb766e2c..90cedc825 100644 --- a/doc/references/ImplementationOfVHDL.rst +++ b/doc/references/ImplementationOfVHDL.rst @@ -43,11 +43,11 @@ 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 +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 +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 @@ -59,16 +59,16 @@ reasons: * 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 +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). -Minor corrections were added by the 2002 revision of the VHDL standard. This +Minor 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 +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 @@ -77,7 +77,7 @@ table below: 87 - Select VHDL-87 standard as defined by IEEE 1076-1987. LRM bugs corrected by + Select VHDL-87 standard as defined by IEEE 1076-1987. LRM bugs corrected by later revisions are taken into account. 93 @@ -89,7 +89,7 @@ table below: * VHDL-87 file declarations are accepted; - * default binding indication rules of VHDL-02 are used. Default binding rules + * default binding indication rules of VHDL-02 are used. Default binding rules are often used, but they are particularly obscure before VHDL-02. 00 @@ -102,7 +102,7 @@ table below: Select VHDL-2008 standard (partially implemented). The 93, 93c, 00 and 02 standards are considered compatible: you can -elaborate a design mixing these standards. However, 87, 93 and 08 are +elaborate a design mixing these standards. However, 87, 93 and 08 are not compatible. .. _psl_implementation: @@ -117,7 +117,7 @@ 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 +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. @@ -155,7 +155,7 @@ 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 +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. @@ -165,9 +165,9 @@ GHDL does not impose any restriction on the name of a design file spaces). GHDL does not keep a binary representation of the design units analyzed like -other VHDL analyzers. The sources of the design units are re-read when +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 architectures is -analyzed). Therefore, if you delete or modify a source file of a unit +analyzed). Therefore, if you delete or modify a source file of a unit analyzed, GHDL will refuse to use it. .. _Library_database: @@ -175,17 +175,17 @@ analyzed, GHDL will refuse to use it. Library database ================ -Each design unit analyzed is placed into a design library. By default, +Each design unit analyzed is placed into a design library. By default, the name of this design library is ``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 +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 +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. @@ -205,12 +205,12 @@ hierarchy: Using vendor libraries ====================== -Many vendors libraries have been analyzed with GHDL. There are -usually no problems. Be sure to use the :option:`--work=` option. +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 +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`. @@ -236,7 +236,7 @@ Foreign declarations -------------------- Only subprograms (functions or procedures) can be imported, using the foreign -attribute. In this example, the `sin` function is imported: +attribute. In this example, the `sin` function is imported: .. code-block:: VHDL @@ -254,20 +254,20 @@ attribute. In this example, the `sin` function is imported: A subprogram is made foreign if the `foreign` attribute decorates -it. This attribute is declared in the 1993 revision of the -``std.standard`` package. Therefore, you cannot use this feature in +it. This attribute is declared in the 1993 revision of the +``std.standard`` package. Therefore, you cannot use this feature in VHDL 1987. -The decoration is achieved through an attribute specification. The +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. +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 +Even when a subprogram is foreign, its body must be present. However, since it won't be called, you can make it empty or simply put an assertion. The value of the attribute must start with ``VHPIDIRECT`` (an -upper-case keyword followed by one or more blanks). The linkage name of the +upper-case keyword followed by one or more blanks). The linkage name of the subprogram follows. .. _Restrictions_on_foreign_declarations: @@ -275,33 +275,33 @@ subprogram follows. 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 non-composite types are easily imported: +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 non-composite types are easily imported: *integer types* - They are represented by a 32 bit word. This generally corresponds to + They are represented by a 32 bit word. This generally corresponds to `int` for `C` or `Integer` for `Ada`. *physical types* - They are represented by a 64 bit word. This generally corresponds to the + They are represented by a 64 bit word. This generally corresponds to the `long long` for `C` or `Long_Long_Integer` for `Ada`. *floating point types* - They are represented by a 64 bit floating point word. This generally + They are represented by a 64 bit floating point word. This generally corresponds to `double` for `C` or `Long_Float` for `Ada`. *enumeration types* They are represented by an 8 bit word, or, if the number of literals is - greater than 256, by a 32 bit word. There is no corresponding C type, since arguments are + greater than 256, by a 32 bit word. There is no corresponding C type, 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 +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 +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 @@ -310,10 +310,10 @@ 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 arrays are represented by a fat pointer. Do not use unconstrained +Unconstrained arrays are represented by a fat pointer. Do not use unconstrained arrays in foreign subprograms. -Accesses to an unconstrained array are fat pointers. Other accesses correspond to an address and are passed to a subprogram like other non-composite types. +Accesses to an unconstrained array are fat pointers. Other accesses correspond to an address and are passed to a subprogram like other non-composite types. Files are represented by a 32 bit word, which corresponds to an index in a table. @@ -339,7 +339,7 @@ Note the :file:`c` library is always linked with an executable. Starting a simulation from a foreign program -------------------------------------------- -You may run your design from an external program. You just have to call +You may run your design from an external program. You just have to call the ``ghdl_main`` function which can be defined: in C: @@ -360,7 +360,7 @@ in Ada: 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. +In case of failure, this function does not return. This has to be fixed. .. _Linking_with_Ada: @@ -368,18 +368,18 @@ 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 +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 +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 +Then, bind your design. In this example, we suppose the entity at the design apex is ``design``. :: @@ -397,20 +397,20 @@ Using GRT from Ada .. warning:: This topic is only for advanced users who know how to use `Ada` - and `GNAT`. This is provided only for reference; we have tested + and `GNAT`. This is provided only for reference; we 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 +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 +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 +`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. :: @@ -420,7 +420,7 @@ runtime library and want to avoid this pragma. For this, reset the 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, +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. :: @@ -429,7 +429,7 @@ remove all the object files and make the :file:`.ali` files read-only. $ chmod -w *.ali -You may then install the sources files and the :file:`.ali` files. I have never +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. diff --git a/doc/references/ImplementationOfVITAL.rst b/doc/references/ImplementationOfVITAL.rst index a3e0aeb98..77e7096c0 100644 --- a/doc/references/ImplementationOfVITAL.rst +++ b/doc/references/ImplementationOfVITAL.rst @@ -10,8 +10,8 @@ Implementation of VITAL .. 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 of right now. +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 of right now. .. _vital_packages: @@ -21,9 +21,9 @@ 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 +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 +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. @@ -40,18 +40,18 @@ 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) +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 +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 +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: @@ -64,31 +64,31 @@ Backannotation :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 +The external files must be SDF (Standard Delay Format) files. GHDL supports a tiny subset of SDF version 2.1. Other version numbers can be used, provided no features added by later versions 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 +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 +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 +`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 adjustments are necessary to handle negative -constraints such as a negative setup time. This step is defined in the VITAL +constraints 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. +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. |