diff options
| author | 1138-4EB <1138-4EB@users.noreply.github.com> | 2019-11-11 18:46:36 +0000 |
|---|---|---|
| committer | tgingold <tgingold@users.noreply.github.com> | 2019-11-11 19:46:36 +0100 |
| commit | 8599d9ddd15b15afdeced6059b1e1b7a972f4db1 (patch) | |
| tree | 499b9c6fe0f85ce7ed221f72ac31036eefde0194 /doc | |
| parent | 22775978be88c5ea8e5b740734e42eeb2fef0968 (diff) | |
| download | ghdl-8599d9ddd15b15afdeced6059b1e1b7a972f4db1.tar.gz ghdl-8599d9ddd15b15afdeced6059b1e1b7a972f4db1.tar.bz2 ghdl-8599d9ddd15b15afdeced6059b1e1b7a972f4db1.zip | |
Update doc (#1003)
* doc: update makefile and build scripts
* actions: add workflow 'doc'
* doc: reorganize sections
* doc: fix 'unknown option' warnings, headings, spaces, etc.
* doc: add subdir 'examples', move 'quick_start' sources
* doc: add section 'Development/Debugging'
* doc: add section'Development/Synthesis'
* doc: update roadmap
* doc: add section examples
* doc: use standard domain
* doc: add comment about 'vhd' vs 'vhdl'
Diffstat (limited to 'doc')
33 files changed, 999 insertions, 818 deletions
diff --git a/doc/Makefile b/doc/Makefile index d43a1887c..5f111c4d3 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -30,14 +30,36 @@ CP=cp SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = -BUILDDIR = build +BUILDDIR = _build PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees -T -D language=en $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . all: ghdl.info +#--- + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + +#--- + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + +#--- + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + +#--- + +texi: ghdl.texi +ghdl.texi: $(SRCS) + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + $(CP) $(BUILDDIR)/texinfo/GHDL.texi $@ + info: ghdl.info ghdl.info: ghdl.texi makeinfo -o $@ $< @@ -53,13 +75,7 @@ pdf: ghdl.pdf ghdl.pdf: ghdl.dvi dvipdf $< -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - -texi: ghdl.texi -ghdl.texi: $(SRCS) - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - $(CP) $(BUILDDIR)/texinfo/GHDL.texi $@ +#--- clean: $(RM) *~ *.dvi *.info ghdl.aux ghdl.cp ghdl.fn ghdl.ky ghdl.log diff --git a/doc/about.rst b/doc/about.rst index 2256f4afe..32915a05f 100644 --- a/doc/about.rst +++ b/doc/about.rst @@ -22,19 +22,18 @@ Like a program written in any other language, a VHDL program can be executed. Si The development of VHDL started in 1983 and the standard is named `IEEE <https://www.ieee.org/>`_ `1076`. Four revisions exist: `1987 <http://ieeexplore.ieee.org/document/26487/>`_, `1993 <http://ieeexplore.ieee.org/document/392561/>`_, `2002 <http://ieeexplore.ieee.org/document/1003477/>`_ and `2008 <http://ieeexplore.ieee.org/document/4772740/>`_. The standardization is handled by the VHDL Analysis and Standardization Group (`VASG/P1076 <http://www.eda-twiki.org/vasg/>`_). - .. _INTRO:GHDL: What is GHDL? ============= -`GHDL` is a shorthand for `G Hardware Design Language` (currently, `G` has no meaning). It is a VHDL compiler that can execute (nearly) any VHDL program. GHDL is *not* a synthesis tool: you cannot create a netlist with GHDL (yet). +`GHDL` is a shorthand for `G Hardware Design Language` (currently, `G` has no meaning). It is a VHDL analyzer, compiler and simulator that can execute (nearly) any VHDL program. GHDL is *not* a synthesis tool: you cannot create a netlist with GHDL (yet). Unlike some other simulators, GHDL is a compiler: it directly translates a VHDL file to machine code, 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. GHDL can use multiple back-ends, i.e. code generators, (`GCC <http://gcc.gnu.org/>`_, `LLVM <http://llvm.org/>`_ or :wikipedia:`x86 <X86-64>`/:wikipedia:`i386 <Intel_80386>` only, a built-in one) and runs on :wikipedia:`GNU/Linux <Linux_distribution>`, :wikipedia:`Windows <Microsoft_Windows>` |trade| and :wikipedia:`macOS <MacOS>` |trade| , both on x86 and on x86_64. -The current version of GHDL does not contain any graphical viewer: you cannot see signal waves. You can still check the behavior of your design with a test bench. Moreover, the current version can produce a `GHW <http://ghdl.readthedocs.io/en/latest/using/Simulation.html?highlight=GHW#cmdoption-wave>`_, :wikipedia:`VCD <Value_change_dump>` or `FST` files which can be viewed with a :wikipedia:`waveform viewer <Waveform_viewer>`, such as `GtkWave <http://gtkwave.sourceforge.net/>`_. +The current version of GHDL does not contain any built-in graphical viewer: you cannot see signal waves. You can still check the behavior of your design with a test bench. Moreover, the current version can produce `GHW <http://ghdl.readthedocs.io/en/latest/using/Simulation.html?highlight=GHW#cmdoption-wave>`_, :wikipedia:`VCD <Value_change_dump>` or `FST` files which can be viewed with a :wikipedia:`waveform viewer <Waveform_viewer>`, such as `GtkWave <http://gtkwave.sourceforge.net/>`_. GHDL aims at implementing VHDL as defined by `IEEE 1076 <http://ieeexplore.ieee.org/document/4772740/>`_. It supports the `1987 <http://ieeexplore.ieee.org/document/26487/>`_, `1993 <http://ieeexplore.ieee.org/document/392561/>`_ and `2002 <http://ieeexplore.ieee.org/document/1003477/>`_ revisions and, partially, the latest, `2008 <http://ieeexplore.ieee.org/document/4772740/>`_. :wikipedia:`PSL <Property_Specification_Language>` is also partially supported. @@ -42,9 +41,8 @@ Several third party projects are supported: `VUnit <https://vunit.github.io/>`_, .. HINT:: - Although synthesis is not supported yet, there is some experimental feature to generate RTL netlists (VHDL or EDIF) from synthesisable code. For subcommand ``--synth`` to be available, GHDL must be configured/built with option ``--enable-synth`` (GCC 8.1>= required, due to some new GNAT features which are only available in recent releases). Since this is a proof-of-concept, the output is mostly a dump of an internal structure for now. Therefore, it is not very useful, except for debugging. - Moreover, `ghdlsynth <https://github.com/tgingold/ghdlsynth-beta>`_ is a complementary repository that lets GHDL to be loaded by `yosys <http://www.clifford.at/yosys/>`_ as a frontend plugin module, in order to generate bitstreams for some FPGA devices. + Although synthesis is not available yet, there is some experimental support. See :ref:`DEV:Synthesis` for further info. .. _INTRO:WHO: diff --git a/doc/appendix/Meta.rst b/doc/appendix/Meta.rst deleted file mode 100644 index fc4295e75..000000000 --- a/doc/appendix/Meta.rst +++ /dev/null @@ -1,96 +0,0 @@ -Meta -#### - -General guidelines to edit the documentation -******************************************** - - 1) It’s better for version control systems and diff tools to break lines at a sensible number of characters. Long lines appear as one diff. Also merging is more complex because merges are line based. Long unbreakable items may be longer (links, refs, etc.). We chose to use 160 chars. - 2) Please indent all directive content by 3 spaces (not 2, and no tabs). - 3) Please use ``*`` as an itemize character, since ``-`` and ``+`` are supported by docutils, but not officially supported by Sphinx. - 4) Please underline all headlines with at least as many characters as the headline is long. Following the Python pattern for headlines the levels are: - - .. code:: - - ############ - ************ (sometimes skipped in small documents) - ============ - ------------------- - ‘’’’’’’’’’’’’’’’’’’’’’’’ - - 5) It’s not required to write - - .. code:: - - :samp:`code` - - The default role for - - .. code:: - - ``code`` - - is samp. ``:samp:`` is only required when you want to write italic text in code text. - - .. code:: - - :samp:`print 1+{variable}` - - Now, variable becomes italic. - - Please simplify all usages of ``:samp:`code``` to ````code```` for readability. Here are the regular expressions for an editor like Notepad++: - - - Search pattern:: :samp:`(.+?)` - - Replace pattern:: ``\1`` - - 6) Each backend has one folder and each platform/compiler has one file. Please note that page headlines are different from ToC headline: - - .. code:: - - .. toctree:: - :hidden: - - ToC entry <file1> - file2 - - 7) Documentation should not use “you”, “we”, …, because it’s not an interactive conversation or informal letter. It’s like a thesis, everything is structured and formal. However, to make it more friendly to newcomers, we agree to allow informal language in the section :ref:`USING:QuickStart`. - - 8) Please keep errors to a minimum. - -Guidelines to edit section 'Building' -************************************* - -We prefer a text block, which explains how a compilation works, what we can configure for that backend, etc. After that, we prefer a code block with e.g. bash instructions on how to compile a backend. A list of instructions with embedded bash lines is not helpful. An experienced, as well as novice user, would like to copy a set of instructions into the shell. But it should be stated what these instructions will do. Complex flows like for GCC, can be split into multiple shell code blocks. Moreover, we find it essential to demonstrate when and where to change directories. - -We would like to see a list like: - -* gcc (Gnu Compiler Collection) -* gcc-gnat (Ada compiler for GCC) -* llvm-del (LLVM development package) -* ... - -The goal is also to explain what a user is installing and what the few lines in the build description do. Now they know the name, can search for similar names if they have another package manager or distro or can ask Google/Wikipedia. We often find many build receipts with cryptic shell code and to execute this unknown stuff with sudo is not comfortable. We would like to know what it does before hitting enter. - -Documentation configuration -*************************** - -* Python snippet for Sphinx's `conf.py` to extract the current version number from Git (latest tag name). [:ghdlsharp:`200`, :ghdlsharp:`221`] - -* Reference ``genindex.html`` from the navigation bar. [:ghdlsharp:`200`] - -* Create "parts" (LaTeX terminology / chapter headlines) in navigation bar. [:ghdlsharp:`200`] - -* Intersphinx files [:ghdlsharp:`200`] - * To decompress the inventory file: `curl -s http://ghdl.readthedocs.io/en/latest/objects.inv | tail -n+5 | openssl zlib -d`. From `how-to-uncompress-zlib-data-in-unix <http://unix.stackexchange.com/questions/22834/how-to-uncompress-zlib-data-in-unix>`_. - * External ref and link to section:: - - :ref:`GHDL Roadmap <ghdl:CHANGE:Roadmap>` - - * External ref to option (no link):: - - :ghdl:option:`--ieee` - :option:`ghdl:--ieee` - -Dist -**** - -* Ubuntu uses `dash` instead of `bash` when a shell script is run. As a result, some functionalities, such as arrays like ``array[1]``, are not supported. Therefore, build scripts in `dist/linux` should not use those functionalities unless they are sourced in a `bash` shell. That is, :file:`travis-ci.sh` uses arrays, since it is sourced in the Travis CI machine. But :file:`docker-buildtest.sh` and :file:`buildtest.sh` do not use any. The same applies to the scripts in `testsuite`. diff --git a/doc/appendix/Roadmap.rst b/doc/appendix/Roadmap.rst deleted file mode 100644 index 19f673e81..000000000 --- a/doc/appendix/Roadmap.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. _CHANGE:Roadmap: - -Roadmap | Future Improvements -############################# - -We have several axes for `GHDL` improvements: - -* Documentation -* Better diagnostics messages (warning and error) -* Full support of VHDL-2008 -* Optimization (simulation speed) -* Graphical tools (to see waves and to debug) -* Style checks -* VITAL acceleration - diff --git a/doc/build.sh b/doc/build.sh deleted file mode 100644 index 98d9039b9..000000000 --- a/doc/build.sh +++ /dev/null @@ -1,27 +0,0 @@ -#!/bin/sh - -set -e - -cd $(dirname $0)/.. - -$(command -v winpty) docker run --rm -t \ - -v /$(pwd)://src \ - -w //src/doc \ - btdi/sphinx:py3-featured sh -c "$(cat <<-EOF -pip install -r requirements.txt -sphinx-build -T -b html -D language=en . _build/html -sphinx-build -T -b latex -D language=en . _build/latex -EOF -)" - -$(command -v winpty) docker run --rm -t \ - -v /$(pwd)://src \ - -w //src/doc \ - btdi/latex sh -c "$(cat <<-EOF -cd _build/latex -FILE=\"\`ls *.tex | sed -e 's/\.tex//'\`\" -pdflatex -interaction=nonstopmode \$FILE.tex; -makeindex -s python.ist \$FILE.idx; -pdflatex -interaction=nonstopmode \$FILE.tex; -EOF -)" diff --git a/doc/conf.py b/doc/conf.py index 014cbd13b..ef047cb96 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -13,11 +13,12 @@ # serve to show the default. import sys, os, shlex, re, subprocess +from os.path import abspath, join # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -sys.path.insert(0, os.path.abspath('.')) +sys.path.insert(0, abspath('.')) # -- General configuration ------------------------------------------------ diff --git a/doc/contribute.rst b/doc/contribute.rst index 16165e839..8b7710190 100644 --- a/doc/contribute.rst +++ b/doc/contribute.rst @@ -106,7 +106,7 @@ write access to our repositories, the project is hosted at GitHub, which follows .. TIP:: * It is recommended to read `A successful Git branching model <http://nvie.com/posts/a-successful-git-branching-model/>`_ for a reference on how maintainers expect to handle multiple branches. However, our actual model is not as exhaustive as explained there. * Some commit messages can `automatically close <https://help.github.com/articles/closing-issues-via-commit-messages/>`_ issues. This is a very useful feature, which you are not required to use. However beware that using `fix` anywhere in the commit message can have side effects. If you closed any issue unexpectedly, just reply to it (even if it's closed) so that maintainers can check it. - * It is recommended to read :ref:`REF:Style` before contributing modifications to Ada sources. + * It is recommended to read :ref:`DEV:Style` before contributing modifications to Ada sources. Related interesting projects ============================ diff --git a/doc/development/CodingStyle.rst b/doc/development/CodingStyle.rst new file mode 100644 index 000000000..cef9eb993 --- /dev/null +++ b/doc/development/CodingStyle.rst @@ -0,0 +1,238 @@ +.. _DEV:Style: + +Coding Style +############ + +Ada +=== + +Ada subset: use only a simple (VHDL like) subset of Ada: no tasking, no +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, 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). + +Subprograms must have a comment before to describe them, like: + +.. code-block:: Ada + + -- Analyze the concurrent statements of PARENT. + 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. + +* For subprograms: + + 1. Declare on one line when possible: + + .. code-block:: Ada + + function Translate_Static_Aggregate (Aggr : Iir) return O_Cnode + + 2. If not possible, put the return on the next line: + + .. code-block:: Ada + + function Translate_Static_String (Str_Type : Iir; Str_Ident : Name_Id) + return O_Cnode + + 3. If not possible, put parameters and return on the next line: + + .. code-block:: Ada + + function Create_String_Literal_Var_Inner + (Str : Iir; Element_Type : Iir; Str_Type : O_Tnode) return Var_Type + + 4. If not possible, return on the next line: + + .. code-block:: Ada + + function Translate_Shortcut_Operator + (Imp : Iir_Implicit_Function_Declaration; Left, Right : Iir) + return O_Enode + + 5. If not possible, one parameter per line, just after subprogram name: + + .. code-block:: Ada + + procedure Translate_Static_Aggregate_1 (List : in out O_Array_Aggr_List; + Aggr : Iir; + Info : Iir; + El_Type : Iir) + + 6. If not possible, add a return after subprogram name: + + .. code-block:: Ada + + function Translate_Predefined_TF_Array_Element + (Op : Predefined_Boolean_Logical; + Left, Right : Iir; + Res_Type : Iir; + Loc : Iir) + return O_Enode + + 7. If not possible, ask yourself what is wrong! Shorten a name. + +* Rule for the 'is': on a new line only if the declarative part is not empty: + + .. code-block:: Ada + + procedure Translate_Assign (Target : Mnode; Expr : Iir; Target_Type : Iir) + is + Val : O_Enode; + begin + + vs. + + .. code-block:: Ada + + function Translate_Static_Range_Dir (Expr : Iir) return O_Cnode is + begin + + If the parameter line is too long with the 'is', put in on a separate line: + + .. code-block:: Ada + + procedure Predeclare_Scope_Type + (Scope : in out Var_Scope_Type; Name : O_Ident) is + +* Generic instantiation: put the generic actual part on a new line: + + .. code-block:: Ada + + procedure Free is new Ada.Unchecked_Deallocation + (Action_List, Action_List_Acc); + +* For if/then statement: + + 1. 'then' on the same line: + + .. code-block:: Ada + + if Get_Expr_Staticness (Decl) = Locally then + + 2. If not possible, 'then' is alone on its line aligned with the 'if': + + .. code-block:: Ada + + if Expr = Null_Iir + or else Get_Kind (Expr) = Iir_Kind_Overflow_Literal + then + + 3. For a multiline condition, 'or else' and 'and then' should start lines. + +* 'Local' variable declaration: + Do not initialize variables, constants must be declared before variables: + + .. code-block:: Ada + + is + N_Info : constant Iir := Get_Sub_Aggregate_Info (Info); + Assoc : Iir; + Sub : Iir; + begin + + If the initialization expression has a side effect (such as allocation), do + not use a constant. + +Shell +===== + +Ubuntu uses `dash` instead of `bash` when a shell script is run. As a result, some functionalities, such as arrays like +``array[1]``, are not supported. Therefore, build scripts in `dist/linux` should not use those functionalities unless +they are sourced in a `bash` shell. The same applies to the scripts in `testsuite`. + +Guidelines to edit the documentation +==================================== + + 1) It’s better for version control systems and diff tools to break lines at a sensible number of characters. Long lines appear as one diff. Also merging is more complex because merges are line based. Long unbreakable items may be longer (links, refs, etc.). We chose to use 160 chars. + 2) Please indent all directive content by 3 spaces (not 2, and no tabs). + 3) Please use ``*`` as an itemize character, since ``-`` and ``+`` are supported by docutils, but not officially supported by Sphinx. + 4) Please underline all headlines with at least as many characters as the headline is long. Following the Python pattern for headlines the levels are: + + .. code:: + + ############ + ************ (sometimes skipped in small documents) + ============ + ------------------- + ‘’’’’’’’’’’’’’’’’’’’’’’’ + + 5) It’s not required to write + + .. code:: + + :samp:`code` + + The default role for + + .. code:: + + ``code`` + + is samp. ``:samp:`` is only required when you want to write italic text in code text. + + .. code:: + + :samp:`print 1+{variable}` + + Now, variable becomes italic. + + Please simplify all usages of ``:samp:`code``` to ````code```` for readability. Here are the regular expressions for an editor like Notepad++: + + - Search pattern:: :samp:`(.+?)` + - Replace pattern:: ``\1`` + + 6) Each backend has one folder and each platform/compiler has one file. Please note that page headlines are different from ToC headline: + + .. code:: + + .. toctree:: + :hidden: + + ToC entry <file1> + file2 + + 7) Documentation should not use “you”, “we”, …, because it’s not an interactive conversation or informal letter. It’s like a thesis, everything is structured and formal. However, to make it more friendly to newcomers, we agree to allow informal language in the section :ref:`USING:QuickStart`. + + 8) Please keep errors to a minimum. + +Guidelines to edit section 'Building' +------------------------------------- + +We prefer a text block, which explains how a compilation works, what we can configure for that backend, etc. After that, we prefer a code block with e.g. bash instructions on how to compile a backend. A list of instructions with embedded bash lines is not helpful. An experienced, as well as novice user, would like to copy a set of instructions into the shell. But it should be stated what these instructions will do. Complex flows like for GCC, can be split into multiple shell code blocks. Moreover, we find it essential to demonstrate when and where to change directories. + +We would like to see a list like: + +* gcc (Gnu Compiler Collection) +* gcc-gnat (Ada compiler for GCC) +* llvm-del (LLVM development package) +* ... + +The goal is also to explain what a user is installing and what the few lines in the build description do. Now they know the name, can search for similar names if they have another package manager or distro or can ask Google/Wikipedia. We often find many build receipts with cryptic shell code and to execute this unknown stuff with sudo is not comfortable. We would like to know what it does before hitting enter. + +Documentation configuration +=========================== + +* Python snippet for Sphinx's `conf.py` to extract the current version number from Git (latest tag name). [:ghdlsharp:`200`, :ghdlsharp:`221`] + +* Reference ``genindex.html`` from the navigation bar. [:ghdlsharp:`200`] + +* Create "parts" (LaTeX terminology / chapter headlines) in navigation bar. [:ghdlsharp:`200`] + +* Intersphinx files [:ghdlsharp:`200`] + * To decompress the inventory file: `curl -s http://ghdl.readthedocs.io/en/latest/objects.inv | tail -n+5 | openssl zlib -d`. From `how-to-uncompress-zlib-data-in-unix <http://unix.stackexchange.com/questions/22834/how-to-uncompress-zlib-data-in-unix>`_. + * External ref and link to section:: + + :ref:`GHDL Roadmap <ghdl:CHANGE:Roadmap>` + + * External ref to option (no link):: + + :ghdl:option:`--ieee` + :option:`ghdl:--ieee` diff --git a/doc/development/Debugging.rst b/doc/development/Debugging.rst new file mode 100644 index 000000000..9957b1694 --- /dev/null +++ b/doc/development/Debugging.rst @@ -0,0 +1,75 @@ +.. _DEV:Debugging: + +Debugging +######### + +Simulation and runtime debugging options +======================================== + +Besides the options described in :ref:`GHDL:options`, `GHDL` passes any debugging options (those that begin with +``-g``) and optimizations options (those that begin with ``-O`` or ``-f``) to `GCC`. Refer to the `GCC` manual for +details. Moreover, some debugging options are also available, but not described here. The :option:`--help` option lists +all options available, including the debugging ones. + +.. option:: --trace-signals + + Display signals after each cycle. + +.. option:: --trace-processes + + Display process name before each cycle. + +.. option:: --stats + + Display run-time statistics. + +.. option:: --disp-order + + Display signals order. + +.. option:: --disp-sources + + Display sources while displaying signals. + +.. option:: --disp-sig-types + + Display signal types. + +.. option:: --disp-signals-map + + Display map bw declared signals and internal signals. + +.. option:: --disp-signals-table + + Display internal signals. + +.. option:: --checks + + Do internal checks after each process run. + +.. option:: --activity=<LEVEL> + + Watch activity of LEVEL signals: LEVEL is ``all``, ``min`` (default) or ``none`` (unsafe). + +.. option:: --dump-rti + + Dump Run Time Information (RTI). + +.. option:: --bootstrap + + Allow ``--work=std`` + +GNU Debugger (GDB) +------------------ + +.. index:: `__ghdl_fatal` + +.. WARNING:: Debugging VHDL programs using `GDB` is possible only with GCC/LLVM. + +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, it 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 catch a runtime error, such as indexing an array beyond its bounds. All error check subprograms call the ``__ghdl_fatal`` procedure. Therefore, to a 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/development/Roadmap.rst b/doc/development/Roadmap.rst new file mode 100644 index 000000000..799ec7cbc --- /dev/null +++ b/doc/development/Roadmap.rst @@ -0,0 +1,26 @@ +.. _DEV:Roadmap: + +Roadmap | Future Improvements +############################# + +We have several axes for `GHDL` improvements: + +* Synthesis +* Full support of VHDL-2008 +* Optimization (simulation speed) +* Better diagnostics messages (warning and error) +* Graphical tools (to see waves and to debug) +* Style checks +* VITAL acceleration + +* Documentation + + * Development/Synthesis. Synthesis, ghdlsynth-beta, formal verification, etc. Copy the 'Usage' section from ghdlsynth's README (https://github.com/1138-4EB/ghdlsynth-beta#usage). + * Development/libghdl. How to interact with GHDL through ``libghdl`` and/or ``libghdl-py``. + * Development/Related Projects. Brief discussion about similarities/differences with other open source projects such as rust_hdl or pyVHDLParser. + * Usage/Docker. Probably copy/convert :file:`README.md` and :file:`USE_CASES.md` in ghdl/docker :ghdlsharp:`166`. + * Usage/Language Server. + * Usage/Examples/Coverage. Code coverage in GHDL is a side effect of using GCC as a backend. In the future, GCC backend support might be dropped in favour of mcode and LLVM. To do so, code coverage with LLVM should be supported first. Anyway, comments/bits of info should be gathered somewhere in the docs, along with references to gcov, lcov, etc. + * Usage/Examples/UART. Dossmatik's UART and unisim guides. We have ``*.doc`` sources to be converted to Sphinx. + * Usage/Examples/Free Range VHDL. https://github.com/fabriziotappero/Free-Range-VHDL-book + * It is possible to add waveforms with wavedrom, since there is a sphinx extension available. diff --git a/doc/development/Synthesis.rst b/doc/development/Synthesis.rst new file mode 100644 index 000000000..bcd23ff70 --- /dev/null +++ b/doc/development/Synthesis.rst @@ -0,0 +1,8 @@ +.. _DEV:Synthesis: + +Synthesis +######### + +There is an experimental command (``--synth``) to generate RTL netlists (the format, VHDL or EDIF, is yet to be defined) from synthesisable code. For command ``--synth`` to be available, GHDL must be configured/built with option ``--enable-synth`` (GCC 8.1>= required, due to some new GNAT features which are only available in recent releases). Since this is a proof-of-concept, the output is mostly a dump of an internal structure for now. Therefore, it is not very useful, except for debugging. + +Moreover, `ghdlsynth <https://github.com/tgingold/ghdlsynth-beta>`_ is a complementary repository that lets GHDL to be loaded by `yosys <http://www.clifford.at/yosys/>`_ as a frontend plugin module, in order to generate bitstreams for some FPGA devices. diff --git a/doc/examples/README.rst b/doc/examples/README.rst new file mode 100644 index 000000000..921bcf2a3 --- /dev/null +++ b/doc/examples/README.rst @@ -0,0 +1,12 @@ +.. _USING:Examples: + +Examples +######## + +This sections contains advanced examples using specific features of the language, the tool, +or interaction with third-party projects. It is suggested for users who are new to either +`GHDL` or `VHDL` to read :ref:`USING:QuickStart` first. + +.. toctree:: + + ../examples/VHPIDIRECT diff --git a/doc/examples/VHPIDIRECT.rst b/doc/examples/VHPIDIRECT.rst new file mode 100644 index 000000000..f8eddf911 --- /dev/null +++ b/doc/examples/VHPIDIRECT.rst @@ -0,0 +1,18 @@ +.. _Examples:VHPIDIRECT: + +Data exchange through VHPIDIRECT +################################ + +VUnit +===== + +`VUnit <https://github.com/VUnit/vunit>`_ is an open source unit testing framework for VHDL/SystemVerilog. Sharing memory buffers between foreign C or Python applications and VHDL testbenches is supported through GHDL's VHPIDIRECT features. Buffers are accessed from VHDL as either strings, arrays of bytes or arrays of 32 bit integers. See VUnit example `external buffer <https://github.com/VUnit/vunit/tree/master/examples/vhdl/external_buffer>`_ for details about the API. + +ghdlex and netpp +================ + +`netpp (network property protocol) <https://section5.ch/index.php/netpp/>`_ is a communication library allowing to expose variables or other properties of an application to the network as abstract 'Properties'. Its basic philosophy is that a device always knows its capabilities. netpp capable devices can be explored by command line, Python scripts or GUI applications. Properties of a device - be it virtual or real - are typically described by a static description in an XML device description language, but they can also be constructed on the fly. + +`ghdlex <https://github.com/hackfin/ghdlex>`_ is a set of C extensions to facilitate data exchange between a GHDL simulation and external applications. VHPIDIRECT mechanisms are used to wrap GHDL data types into structures usable from a C library. `ghdlex` uses the `netpp <https://section5.ch/index.php/netpp/>`_ library to expose virtual entities (such as pins or RAM) to the network. It also demonstrates simple data I/O through unix pipes. A few VHDL example entities are provided, such as a virtual console, FIFOs, RAM. + +The author of `netpp` and `ghdlex` is also working on `MaSoCist <https://github.com/hackfin/MaSoCist>`_, a linux'ish build system for System on Chip designs, based on GHDL. It allows to handle more complex setup, e.g. how a RISC-V architecture (for example) is regress-tested using a virtual debug interface. diff --git a/doc/examples/quick_start/DLXModelSuite.rst b/doc/examples/quick_start/DLXModelSuite.rst new file mode 100644 index 000000000..0c8259cac --- /dev/null +++ b/doc/examples/quick_start/DLXModelSuite.rst @@ -0,0 +1,66 @@ +.. _QuickStart:DLX: + +Working with non-trivial designs +================================ + +Designs are usually more complex than the previous examples. Unless you are only studying VHDL, you will work with +larger designs. Let's see how to analyse a 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 at `ghdl.free.fr/dlx.tar.gz <http://ghdl.free.fr/dlx.tar.gz>`_ . + +- First, untar the sources: ``tar zxvf dlx.tar.gz``. + +.. HINT:: + + In order not to pollute the sources with the artifacts (`WORK` library), it is a good idea to create a + :file:`work/` subdirectory. To any GHDL commands, we will add the :option:`--workdir=work <--workdir>` 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 + +* Then, we will run the ``dlx_test_behaviour`` design. We need to analyse all the design units for the design + hierarchy, in the correct order. GHDL provides an easy way to do this, by :ref:`importing <Import:command>` the + sources: ``ghdl -i --workdir=work *.vhdl``. + +* GHDL knows all the design units of the DLX, but none of them has been analysed. Run the :ref:`make <Make:command>` + command, ``ghdl -m --workdir=work dlx_test_behaviour``, which analyses and elaborates a design. This creates many + files in the :file:`work/` directory, and (GCC/LLVM only) the :file:`dlx_test_behaviour` executable in the current + directory. + +.. HINT:: + + The simulation needs to have a DLX program contained in the file :file:`dlx.out`. This memory image will be loaded + in the DLX memory. Just take one sample: ``cp test_loop.out dlx.out``. + +* Now, you can :ref:`run <Run:command>` the test suite: ``ghdl -r --workdir=work dlx_test_behaviour``. The test bench + monitors the bus and displays each executed instruction. It finishes with an assertion of severity level note: + + .. code-block:: shell + + dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction + encountered, execution halted + +* Last, 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 testbench in batch mode. However, you may force the simulator to stop when an + assertion above or equal a certain severity level occurs. To do so, call run with this option instead: + ``ghdl -r --workdir=work dlx_test_behaviour --assert-level=note```. With :option:`--assert-level`, the program stops + just after the previous message: + + .. code-block:: shell + + dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction + encountered, execution halted + error: assertion failed + +.. TIP:: If you want to make room on your hard drive, you can either: + + * :ref:`Clean <Clean:command>` the design library with ``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. + * :ref:`Remove <Remove:command>` the design library with ``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 make the design. + * Remove the :file:`work/` directory: ``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. + +.. WARNING:: Sometimes, a design does not fully follow the VHDL standards. For example it might use the badly engineered ``std_logic_unsigned`` package. GHDL supports this VHDL dialect through some options: :option:`--ieee=synopsys <--ieee>`, :option:`-fexplicit`, etc. See section :ref:`IEEE_library_pitfalls`, for more details. diff --git a/doc/examples/quick_start/README.rst b/doc/examples/quick_start/README.rst new file mode 100644 index 000000000..6399996f5 --- /dev/null +++ b/doc/examples/quick_start/README.rst @@ -0,0 +1,49 @@ +.. _USING:QuickStart: + +Quick Start Guide +################# + +Since this is the user and reference manual for `GHDL`, it does not contain an +introduction to `VHDL`. Thus, the reader should have at least a basic knowledge +of `VHDL`. A good knowledge of `VHDL` language reference manual (usually called +LRM) is a plus. Nevertheless, multiple examples are provided, in the hope that +they are useful for users to learn about both `GHDL` and `VHDL`. For advanced +examples using specific features see :ref:`USING:Examples`. + +As explained in :ref:`INTRO:GHDL`, `GHDL` is a compiler which translates `VHDL` files to +machine code. Hence, the regular workflow is composed of three steps: + +* :ref:`Analysis:command`: convert design units (`VHDL` sources) to an internal representation. +* :ref:`Elaboration:command`: generate executable machine code for a target module (top-level entity). +* :ref:`Run:command`: execute the design to test the behaviour, generate output/waveforms, etc. + +The following tips might be useful: + +* Don't forget to select the version of the VHDL standard you want to use (see + :ref:`VHDL_standards`). The default is :option:`--std=93c <--std>`. Use :option:`--std=08 <--std>` for VHDL-2008 + (albeit not fully implemented). + + * Use :option:`--ieee=synopsys <--ieee>` if your design depends on a non-standard implementation of the IEEE library. + + * Use :option:`-fexplicit` and :option:`-frelaxed-rules` if needed. + +* Use :option:`--work=LIB_NAME <--work>` to analyze files into the ``LIB_NAME`` library. + To use files analyzed to a different directory, give the path + to the ``LIB_NAME`` library using :option:`-P/path/to/name/directory/ <-P<DIRECTORY>>`. + +* Use the same options for analysis and elaboration. E.g., first analyse with ``ghdl -a --std=08 --work=mylib myfile.vhdl``; + and then elaborate and run with ``ghdl --elab-run --std=08 top``. + +Due to the fact that `VHDL` is processed as a general purpose language +(instead of an `HDL`), all the language features are to be supported. I.e., `VHDL` +sources do not need to be limited to the synthesisable subset. However, distinction +between synthesisable and non-synthesisable (simulation-only) subsets is often misleading +for users who are new to the language. Different examples are provided, +in the hope of helping understand the different use cases: + +.. toctree:: + + hello/README + heartbeat/README + adder/README + DLXModelSuite diff --git a/doc/examples/quick_start/adder/README.rst b/doc/examples/quick_start/adder/README.rst new file mode 100644 index 000000000..6a0bcea91 --- /dev/null +++ b/doc/examples/quick_start/adder/README.rst @@ -0,0 +1,35 @@ +.. _QuickStart:adder: + +`Full adder` module and testbench +================================= + +Unlike :ref:`Heartbeat <QuickStart:heartbeat>`, the target hardware design in this example is written using the +synthesisable subset of `VHDL`. It is a `full adder <https://en.wikipedia.org/wiki/Adder_(electronics)#Full_adder>`_ +described in a file named :file:`adder.vhdl`: + +.. literalinclude:: adder.vhdl + :language: vhdl + +You can :ref:`analyse <Analysis:command>` this design file, ``ghdl -a adder.vhdl``, and try to execute the `adder` +design. But this is useless, since nothing externally visible will happen. In order to check this full adder, a +:dfn:`testbench` has to be run. The :dfn:`testbench` is a description of how to generate inputs and how to check the +outputs of the Unit Under Test (UUT). This one 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. A file named +:file:`adder_tb.vhdl` contains the testbench for the adder: + +.. literalinclude:: adder_tb.vhdl + :language: vhdl + +As usual, you should analyze the file, ``ghdl -a adder_tb.vhdl``. + +.. HINT:: + Then, if required, :ref:`elaborate <Elaboration:command>` the testbench: ``ghdl -e adder_tb``. You do not need to + specify which object files are required, since `GHDL` knows them and automatically adds them. + +Now, it is time to :ref:`run <Run:command>` the testbench, ``ghdl -r adder_tb``, and check the result on screen:: + + adder_tb.vhdl:52:7:(assertion note): end of test + +If your design is rather complex, you'd like to inspect signals as explained in :ref:`Heartbeat <QuickStart:heartbeat>`. + +See section :ref:`simulation_options`, for more details on other runtime options. diff --git a/doc/examples/quick_start/adder/adder.vhdl b/doc/examples/quick_start/adder/adder.vhdl new file mode 100644 index 000000000..cf60e8fbe --- /dev/null +++ b/doc/examples/quick_start/adder/adder.vhdl @@ -0,0 +1,14 @@ +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 assignments. + -- 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; diff --git a/doc/examples/quick_start/adder/adder_tb.vhdl b/doc/examples/quick_start/adder/adder_tb.vhdl new file mode 100644 index 000000000..4a3fca5e4 --- /dev/null +++ b/doc/examples/quick_start/adder/adder_tb.vhdl @@ -0,0 +1,57 @@ +-- 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; diff --git a/doc/examples/quick_start/heartbeat/README.rst b/doc/examples/quick_start/heartbeat/README.rst new file mode 100644 index 000000000..55f1e20c7 --- /dev/null +++ b/doc/examples/quick_start/heartbeat/README.rst @@ -0,0 +1,41 @@ +.. _QuickStart:heartbeat: + +`Heartbeat` module +================== + +Although :ref:`Hello world <QuickStart:hello>` illustrates that `VHDL` is supported as a general purpose language, the main use case +of `GHDL` is to simulate hardware descriptions. The following block, which is saved in a file named +:file:`heartbeat.vhdl`, is an example of how to generate a 100 MHz clock signal with non-synthesisable VHDL: + +.. literalinclude:: heartbeat.vhdl + :language: vhdl + +It can be :ref:`analysed <Analysis:command>`, :ref:`elaborated <Elaboration:command>` and :ref:`run <Run:command>`, as you already know: + +.. code-block:: shell + + ghdl -a heartbeat.vhdl + ghdl -e heartbeat + ghdl -r heartbeat + +However, execution of the design does not terminate. At the same time, no output is shown on screen. This is because, +traditionally, hardware designs are continuously running devices which do not have a screen where to print. In this +context, inspection and verification of the behaviour is done through `waveforms <https://en.wikipedia.org/wiki/Waveform_viewer>`_, +which is supported by `GHDL` (see :ref:`export_waves`). You can use either :option:`--wave`, :option:`--vcd`, +:option:`--vcdgz` or :option:`--fst` to save the signals of the simulation to a file. Then, terminate the execution +(:kbd:`C-c`) and you can inspect the wave with a viewer, such as `GtkWave <http://gtkwave.sourceforge.net/>`_. As +explained in the `manual <http://gtkwave.sourceforge.net/gtkwave.pdf>`_, GtkWave *'relies on a post-mortem approach +through the use of dumpfiles'*. Therefore, you should first simulate your design and dump a waveform file, say GHW: + +.. code-block:: shell + + ghdl -r --wave=wave.ghw heartbeat + +Then, you can view the dump: + +.. code-block:: shell + + gtkwave wave.ghw + +Of course, manually terminating the simulation is for illustration purposes only. In :ref:`Full adder <QuickStart:adder>` and +:ref:`QuickStart:DLX`, you will see how to write a testbench to terminate the simulation programmatically. diff --git a/doc/examples/quick_start/heartbeat/heartbeat.vhdl b/doc/examples/quick_start/heartbeat/heartbeat.vhdl new file mode 100644 index 000000000..0a312641e --- /dev/null +++ b/doc/examples/quick_start/heartbeat/heartbeat.vhdl @@ -0,0 +1,20 @@ +library ieee; +use ieee.std_logic_1164.all; + +entity heartbeat is + port ( clk: out std_logic); +end heartbeat; + +architecture behaviour of heartbeat +is + constant clk_period : time := 10 ns; +begin + -- Clock process definition + clk_process: process + begin + clk <= '0'; + wait for clk_period/2; + clk <= '1'; + wait for clk_period/2; + end process; +end behaviour; diff --git a/doc/examples/quick_start/hello/README.rst b/doc/examples/quick_start/hello/README.rst new file mode 100644 index 000000000..85d07d2b9 --- /dev/null +++ b/doc/examples/quick_start/hello/README.rst @@ -0,0 +1,52 @@ +.. _QuickStart:hello: + +`Hello world` program +===================== + +To illustrate the general purpose of `VHDL`, the following block is a commented `Hello world` program which is saved in +a file named :file:`hello.vhdl`: + +.. literalinclude:: hello.vhdl + :language: vhdl + +.. TIP:: + + * Both ``.vhdl`` and ``.vhd`` extensions are used for `VHDL` source files, while ``.v`` is used for Verilog. + + * Since, extension ``.vhd`` is also interpreted as a `Virtual Hard Disk <https://en.wikipedia.org/wiki/VHD_(file_format)>`_ + file format, some users prefer ``.vhdl``, to avoid ambiguity. This is the case with `GHDL`'s codebase. However, in order + to maintain `backward-compatibility <https://en.wikipedia.org/wiki/8.3_filename>`_ with legacy DOS systems, + other users prefer ``.vhd``. + + * Unless you use especial characters, either `UTF-8` or `ISO-8859-1` encodings can be used. However, if you do, the + latter should be used. The standard defines ASCII (7-bit encoding) or ISO Latin-1 (ISO-8859-1) as default. + However, GHDL has a relaxing option, :option:`--mb-comments` (multi byte), to allow UTF-8 or other encodings in + comments. + +- First, you have to compile the file; this is called :ref:`analysis <Analysis:command>` of a design file in `VHDL` + terms. Run ``ghdl -a hello.vhdl`` in the `shell`. This command creates or updates a file :file:`work-obj93.cf`, which + describes the library ``work``. +- Then, run ``ghdl -e hello_world`` in the `shell`. Command :option:`-e` means :ref:`elaborate <Elaboration:command>`, + which is used to build a design, with the ``hello_world`` entity at the top of the hierarchy. +- Last, you can directly launch the simulation :ref:`running <Run:command>` ``ghdl -r hello_world`` in the `shell`. The + result of the simulation will be shown on screen: + +.. code-block:: shell + + Hello world! + +.. HINT:: + If a GCC/LLVM variant of `GHDL` is used: + + * :ref:`Analysis <Analysis:command>` generates a file, :file:`hello.o`, which is the object file corresponding to + your `VHDL` program. This is not created with :ref:`mcode <BUILD>`. These kind of object files can be + compiled into foreign programs (see :ref:`Linking_with_Ada`). + * The :ref:`elaboration <Elaboration:command>` step is mandatory after running the analysis and prior to launching the + simulation. This will generate an executable binary named :file:`hello_world`. + * As a result, :option:`-r` is just a passthrough to the binary generated in the `elaboration`. Therefore, the + executable can be run directly: ``./hello_world``. See :option:`-r` for more informartion. + +.. HINT:: + + :option:`-e` can be bypassed with :ref:`mcode <BUILD>`, since :option:`-r` actually elaborates the design and saves + it on memory before running the simulation. But you can still use it to check for some elaboration problems. diff --git a/doc/examples/quick_start/hello/hello.vhdl b/doc/examples/quick_start/hello/hello.vhdl new file mode 100644 index 000000000..4d969c6a8 --- /dev/null +++ b/doc/examples/quick_start/hello/hello.vhdl @@ -0,0 +1,17 @@ +-- 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; diff --git a/doc/getting/PrecompileVendorPrimitives.rst b/doc/getting/PrecompileVendorPrimitives.rst index 714dc053d..6b4d01850 100644 --- a/doc/getting/PrecompileVendorPrimitives.rst +++ b/doc/getting/PrecompileVendorPrimitives.rst @@ -57,7 +57,7 @@ Supported Simulation and Verification Libraries * OSVVM (for VHDL-2008) * osvvm - + * UVVM (for VHDL-2008) * uvvm-utilities @@ -101,17 +101,18 @@ Compiling on Linux ================== * **Step 0 - Configure the scripts (optional)** + See the next section for how to configure `config.sh`. * **Step 1 - Browse to your simulation working directory** - + .. code-block:: Bash $ cd <MySimulationFolder> ``` * **Step 2 - Start the compilation script(s)** - + .. code-block:: Bash $ /usr/local/lib/ghdl/vendors/compile-altera.sh --all @@ -121,15 +122,16 @@ Compiling on Linux $ /usr/local/lib/ghdl/vendors/compile-osvvm.sh --all $ /usr/local/lib/ghdl/vendors/compile-uvvm.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. - + .. code-block:: Bash $ ls -ahl @@ -149,16 +151,17 @@ Compiling on Windows ==================== * **Step 0 - Configure the scripts (optional)** + See the next section for how to configure `config.psm1`. * **Step 1 - Browse to your simulation working directory** - + .. code-block:: PowerShell PS> cd <MySimulationFolder> * **Step 2 - Start the compilation script(s)** - + .. code-block:: PowerShell PS> <GHDL>\libraries\vendors\compile-altera.ps1 -All @@ -169,6 +172,7 @@ Compiling on Windows PS> <GHDL>\libraries\vendors\compile-uvvm.ps1 -All * **Step 3 - Viewing the result** + This creates vendor directories in your current working directory and compiles the vendor files into them. @@ -202,7 +206,7 @@ directories. Use an empty string `""` for not installed tools. `config.sh`: .. code-block:: Bash - + declare -A InstallationDirectory InstallationDirectory[AlteraQuartus]="/opt/Altera/17.1" InstallationDirectory[LatticeDiamond]="/opt/Diamond/3.9_x64" @@ -237,7 +241,7 @@ Selectable Options for the Bash Scripts: ---------------------------------------- * Common parameters to most scripts: - + .. code-block:: none --help, -h Print the embedded help page(s). @@ -250,7 +254,7 @@ Selectable Options for the Bash Scripts: * `compile-altera.sh` Selectable libraries: - + .. code-block:: none --all, -a Compile all libraries, including common libraries, packages and device libraries. @@ -261,18 +265,18 @@ Selectable Options for the Bash Scripts: --stratix Compile device libraries for Stratix FPGAs Compile options: - + .. code-block:: none - + --vhdl93 Compile selected libraries with VHDL-93 (default). --vhdl2008 Compile selected libraries with VHDL-2008. * `compile-xilinx-ise.sh` Selectable libraries: - + .. code-block:: none - + --all, -a Compile all libraries, including common libraries, packages and device libraries. --unisim Compile the unisim primitives --unimacro Compile the unimacro macros @@ -281,45 +285,45 @@ Selectable Options for the Bash Scripts: --secureip Compile the secureip primitives Compile options: - + .. code-block:: none - + --vhdl93 Compile selected libraries with VHDL-93 (default). --vhdl2008 Compile selected libraries with VHDL-2008. * `compile-xilinx-vivado.sh` Selectable libraries: - + .. code-block:: none - + --all, -a 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: - + .. code-block:: none - + --vhdl93 Compile selected libraries with VHDL-93 (default). --vhdl2008 Compile selected libraries with VHDL-2008. * `compile-osvvm.sh` Selectable libraries: - + .. code-block:: none - + --all, -a Compile all. --osvvm Compile the OSVVM library. * `compile-uvvm.sh` Selectable libraries: - + .. code-block:: none - + --all, -a Compile all. --uvvm Compile the UVVM libraries. @@ -328,9 +332,9 @@ Selectable Options for the PowerShell Scripts: ---------------------------------------------- * Common parameters to all scripts: - + .. code-block:: none - + -Help Print the embedded help page(s). -Clean Cleanup directory before analyzing. -SuppressWarnings Don't show warnings. Report errors only. @@ -338,9 +342,9 @@ Selectable Options for the PowerShell Scripts: * `compile-altera.ps1` Selectable libraries: - + .. code-block:: none - + -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 @@ -349,7 +353,7 @@ Selectable Options for the PowerShell Scripts: -Stratix Compile device libraries for Stratix FPGAs Compile options: - + .. code-block:: none -VHDL93 Compile selected libraries with VHDL-93 (default). @@ -358,7 +362,7 @@ Selectable Options for the PowerShell Scripts: * `compile-xilinx-ise.ps1` Selectable libraries: - + .. code-block:: none -All Compile all libraries, including common libraries, packages and device libraries. @@ -369,7 +373,7 @@ Selectable Options for the PowerShell Scripts: -Secureip Compile the secureip primitives Compile options: - + .. code-block:: none -VHDL93 Compile selected libraries with VHDL-93 (default). @@ -378,7 +382,7 @@ Selectable Options for the PowerShell Scripts: * `compile-xilinx-vivado.ps1` Selectable libraries: - + .. code-block:: none -All Compile all libraries, including common libraries, packages and device libraries. @@ -387,7 +391,7 @@ Selectable Options for the PowerShell Scripts: -Secureip Compile the secureip primitives Compile options: - + .. code-block:: none -VHDL93 Compile selected libraries with VHDL-93 (default). @@ -396,7 +400,7 @@ Selectable Options for the PowerShell Scripts: * `compile-osvvm.ps1` Selectable libraries: - + .. code-block:: none -All Compile all. @@ -405,7 +409,7 @@ Selectable Options for the PowerShell Scripts: * `compile-uvvm.ps1` Selectable libraries: - + .. code-block:: none -All Compile all. diff --git a/doc/getting/mcode.rst b/doc/getting/mcode.rst index 5e6fbbf68..9e46a29b6 100644 --- a/doc/getting/mcode.rst +++ b/doc/getting/mcode.rst @@ -55,7 +55,7 @@ GNAT GPL: Windows .. rubric:: `compile.ps1` -.. code-block:: plain +.. code-block:: Commands Description -------------------------------------------------------------------- diff --git a/doc/index.rst b/doc/index.rst index b1bd73c23..7357f11ba 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -6,16 +6,6 @@ |SHIELD:gh-logo| |SHIELD:gitter| |SHIELD:code-lic| |SHIELD:doc-lic| |SHIELD:travis-ci| |SHIELD:appveyor| |SHIELD:release| ------------------------------------- - -GHDL Documentation -################## - -This manual is the user and reference manual for GHDL. It does not contain an -introduction to VHDL. Thus, the reader should have at least a basic knowledge -of VHDL. A good knowledge of VHDL language reference manual (usually called -LRM) is a plus. - .. only:: html News @@ -67,12 +57,6 @@ LRM) is a plus. .. rubric:: 23.10.2015 - GHDL 0.33 was released. -.. |docdate| date:: %b %d, %Y - %H:%M - -.. container:: lastdocbuilddate - - This document was generated on |docdate|. - .. toctree:: :caption: Introduction :hidden: @@ -83,19 +67,6 @@ LRM) is a plus. .. raw:: latex - \part{GHDL usage} - -.. toctree:: - :caption: GHDL usage - :hidden: - - using/QuickStartGuide - using/InvokingGHDL - using/Simulation - using/Foreign - -.. raw:: latex - \part{Getting GHDL} .. toctree:: @@ -108,25 +79,31 @@ LRM) is a plus. .. raw:: latex - \part{References} + \part{GHDL usage} .. toctree:: - :caption: Implementation References + :caption: GHDL usage :hidden: - references/CommandReference - references/CodingStyle - references/ImplementationOfVHDL - references/ImplementationOfVITAL + examples/quick_start/README + using/InvokingGHDL + using/Simulation + using/Foreign + using/CommandReference + using/ImplementationOfVHDL + using/ImplementationOfVITAL + examples/README .. raw:: latex - \part{Appendix} + \part{Development} .. toctree:: - :caption: Appendix + :caption: Development :hidden: - appendix/Roadmap - appendix/Meta genindex + development/Synthesis + development/Debugging + development/CodingStyle + development/Roadmap diff --git a/doc/make.sh b/doc/make.sh new file mode 100755 index 000000000..200c29ac1 --- /dev/null +++ b/doc/make.sh @@ -0,0 +1,28 @@ +#!/usr/bin/env sh + +set -e + +cd "$(dirname $0)" + +docker build -t ghdl/sphinx -f- . <<EOF +FROM btdi/sphinx:py3-featured +COPY requirements.txt / +RUN apk add -U --no-cache make \ + && pip3 install -r /requirements.txt +EOF + +dcmd="docker run --rm -u $(id -u) -v /$(pwd)/..://tmp/src -w //tmp/src/doc" + +$dcmd ghdl/sphinx sh -c "make html latex man" + +set +e + +$dcmd btdi/latex:latest bash -c " +cd _build/latex +#make +pdflatex -interaction=nonstopmode GHDL.tex; +makeindex -s python.ist GHDL.idx; +pdflatex -interaction=nonstopmode GHDL.tex; +" + +set -e diff --git a/doc/references/CodingStyle.rst b/doc/references/CodingStyle.rst deleted file mode 100644 index 6af869067..000000000 --- a/doc/references/CodingStyle.rst +++ /dev/null @@ -1,139 +0,0 @@ -.. _REF:Style: - -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. -Allowed Ada95 features: the standard library, child packages. -Use assertions. - -We try to follow the 'GNU Coding Standards' when possible: comments before -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). - -Subprograms must have a comment before to describe them, like: - -.. code-block:: Ada - - -- Analyze the concurrent statements of PARENT. - 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. - -* For subprograms: - - 1. Declare on one line when possible: - - .. code-block:: Ada - - function Translate_Static_Aggregate (Aggr : Iir) return O_Cnode - - 2. If not possible, put the return on the next line: - - .. code-block:: Ada - - function Translate_Static_String (Str_Type : Iir; Str_Ident : Name_Id) - return O_Cnode - - 3. If not possible, put parameters and return on the next line: - - .. code-block:: Ada - - function Create_String_Literal_Var_Inner - (Str : Iir; Element_Type : Iir; Str_Type : O_Tnode) return Var_Type - - 4. If not possible, return on the next line: - - .. code-block:: Ada - - function Translate_Shortcut_Operator - (Imp : Iir_Implicit_Function_Declaration; Left, Right : Iir) - return O_Enode - - 5. If not possible, one parameter per line, just after subprogram name: - - .. code-block:: Ada - - procedure Translate_Static_Aggregate_1 (List : in out O_Array_Aggr_List; - Aggr : Iir; - Info : Iir; - El_Type : Iir) - - 6. If not possible, add a return after subprogram name: - - .. code-block:: Ada - - function Translate_Predefined_TF_Array_Element - (Op : Predefined_Boolean_Logical; - Left, Right : Iir; - Res_Type : Iir; - Loc : Iir) - return O_Enode - - 7. If not possible, ask yourself what is wrong! Shorten a name. - -* Rule for the 'is': on a new line only if the declarative part is not empty: - - .. code-block:: Ada - - procedure Translate_Assign (Target : Mnode; Expr : Iir; Target_Type : Iir) - is - Val : O_Enode; - begin - - vs. - - .. code-block:: Ada - - function Translate_Static_Range_Dir (Expr : Iir) return O_Cnode is - begin - - If the parameter line is too long with the 'is', put in on a separate line: - - .. code-block:: Ada - - procedure Predeclare_Scope_Type - (Scope : in out Var_Scope_Type; Name : O_Ident) is - -* Generic instantiation: put the generic actual part on a new line: - - .. code-block:: Ada - - procedure Free is new Ada.Unchecked_Deallocation - (Action_List, Action_List_Acc); - -* For if/then statement: - - 1. 'then' on the same line: - - .. code-block:: Ada - - if Get_Expr_Staticness (Decl) = Locally then - - 2. If not possible, 'then' is alone on its line aligned with the 'if': - - .. code-block:: Ada - - if Expr = Null_Iir - or else Get_Kind (Expr) = Iir_Kind_Overflow_Literal - then - - 3. For a multiline condition, 'or else' and 'and then' should start lines. - -* 'Local' variable declaration: - Do not initialize variables, constants must be declared before variables: - - .. code-block:: Ada - - is - N_Info : constant Iir := Get_Sub_Aggregate_Info (Info); - Assoc : Iir; - Sub : Iir; - begin - - If the initialization expression has a side effect (such as allocation), do - not use a constant. diff --git a/doc/references/CommandReference.rst b/doc/using/CommandReference.rst index 2b53e51f3..d90f9334c 100644 --- a/doc/references/CommandReference.rst +++ b/doc/using/CommandReference.rst @@ -1,4 +1,3 @@ -.. program:: ghdl .. _REF:Command: Command Reference @@ -72,12 +71,9 @@ Pretty print [``--pp-html``] .. option:: --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. +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. .. index:: cmd file find @@ -131,7 +127,7 @@ Bind [``--bind``] 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. .. HINT:: - Currently, the objects generated by ``--bind`` are created in the working directory. This behaviour is different from other object files generated with ``-a``, which are always placed in the same directory as the `WORK` library. It is possible to provide an output path with ``ghdl --bind -o path/primary_unit primary_unit``. However, ``ghdl --list-link`` will only search in the current path. + Currently, the objects generated by :option:`--bind` are created in the working directory. This behaviour is different from other object files generated with :option:`-a`, which are always placed in the same directory as the `WORK` library. It is possible to provide an output path with ``ghdl --bind -o path/primary_unit primary_unit``. However, ``ghdl --list-link`` will only search in the current path. .. index:: cmd GCC/LLVM linking diff --git a/doc/references/ImplementationOfVHDL.rst b/doc/using/ImplementationOfVHDL.rst index 7c43aad83..f4ecaf40e 100644 --- a/doc/references/ImplementationOfVHDL.rst +++ b/doc/using/ImplementationOfVHDL.rst @@ -1,10 +1,7 @@ .. _REF:ImplVHDL: -*************************** Implementation of VHDL -*************************** - -This chapter describes several implementation defined aspects of VHDL in GHDL. +###################### .. _VHDL_standards: @@ -72,7 +69,7 @@ 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 -``--std=<STANDARD>`` option, where ``<STANDARD>`` is one of the list below: +:option:`--std=STANDARD <--std>` option, where ``STANDARD`` is one of the list below: 87 @@ -119,12 +116,12 @@ Multiple standards can be used in a design: .. _psl_implementation: PSL support -================== +=========== GHDL implements a subset of :wikipedia:`PSL <Property_Specification_Language>`. PSL implementation ------------------ +------------------ A PSL statement is considered a process, so it's not allowed within a process. @@ -152,78 +149,86 @@ Of course only the simple subset of PSL is allowed. Currently the built-in functions are not implemented, see `issue #662 <https://github.com/ghdl/ghdl/issues/662>`_. PSL usage ------------------ +--------- PSL annotations embedded in comments - GHDL understands embedded PSL annotations in VHDL files: +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +GHDL understands embedded PSL annotations in VHDL files: - .. code-block:: VHDL +.. code-block:: VHDL - -- psl default clock is rising_edge (CLK); - -- psl assert always - -- a -> eventually! b; - end architecture rtl; + -- psl default clock is rising_edge (CLK); + -- psl assert always + -- a -> eventually! b; + end architecture rtl; - * 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 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. - .. HINT:: - As PSL annotations are embedded within comments, you must analyze - your design with option ``-fpsl`` to enable PSL annotations. +.. HINT:: - .. code-block:: bash + As PSL annotations are embedded within comments, you must analyze + your design with option :option:`-fpsl` to enable PSL annotations: - ghdl -a -fpsl vhdl_design.vhd - ghdl -e vhdl_design + .. code-block:: bash + + ghdl -a -fpsl vhdl_design.vhdl + ghdl -e vhdl_design PSL annotations (VHDL-2008 only) - Since VHDL-2008 PSL is integrated in the VHDL language. You can use - PSL in a VHDL(-2008) design without embedding it in comments. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Since VHDL-2008 PSL is integrated in the VHDL language. You can use +PSL in a VHDL(-2008) design without embedding it in comments. - .. code-block:: VHDL +.. code-block:: VHDL + + default clock is rising_edge (CLK); + assert always + a -> eventually! b; + end architecture rtl; - default clock is rising_edge (CLK); - assert always - a -> eventually! b; - end architecture rtl; +.. HINT:: - .. HINT:: - You have to use the ``--std=08`` option + You have to use the :option:`--std=08 <--std>` option: - .. code-block:: bash + .. code-block:: bash - ghdl -a --std=08 vhdl_design.vhd - ghdl -e --std=08 vhdl_design + ghdl -a --std=08 vhdl_design.vhdl + ghdl -e --std=08 vhdl_design PSL vunit files - GHDL supports vunit (Verification Unit) files. +^^^^^^^^^^^^^^^ - .. code-block:: VHDL +GHDL supports vunit (Verification Unit) files. - vunit vunit_name (design_name) - { - default clock is rising_edge(clk); - assert always cnt /= 5 abort rst; - } +.. code-block:: VHDL - * A vunit can contain PSL and VHDL code. + vunit vunit_name (design_name) + { + default clock is rising_edge(clk); + assert always cnt /= 5 abort rst; + } - * It is bound to a VHDL entity or an instance of it. +* A vunit can contain PSL and VHDL code. - * The PSL vunit is in the same scope as the VHDL design it is bound - to. You have access to all objects (ports, types, signals) of the - VHDL design. +* It is bound to a VHDL entity or an instance of it. - .. HINT:: - The PSL vunit file has to be analyzed/elaborated together with the VHDL design file, for example: +* The PSL vunit is in the same scope as the VHDL design it is bound + to. You have access to all objects (ports, types, signals) of the + VHDL design. - .. code-block:: bash +.. HINT:: - ghdl -a --std=08 vhdl_design.vhd vunit.psl - ghdl -e --std=08 vhdl_design + The PSL vunit file has to be analyzed/elaborated together with the VHDL design file, for example: + .. code-block:: bash + + ghdl -a --std=08 vhdl_design.vhdl vunit.psl + ghdl -e --std=08 vhdl_design Source representation @@ -257,7 +262,7 @@ Library database 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=<LIB_NAME>` option of GHDL. +changed with the :option:`--work` 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:`<LIB_NAME>-obj<GROUP>.cf`, where @@ -287,11 +292,8 @@ 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. -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`. +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 <--std>`, :option:`-fexplicit`, :option:`-frelaxed-rules` and +:option:`--warn-no-vital-generic <--warn-vital-generic>`. diff --git a/doc/references/ImplementationOfVITAL.rst b/doc/using/ImplementationOfVITAL.rst index 77e7096c0..77e7096c0 100644 --- a/doc/references/ImplementationOfVITAL.rst +++ b/doc/using/ImplementationOfVITAL.rst diff --git a/doc/using/InvokingGHDL.rst b/doc/using/InvokingGHDL.rst index 94e58866a..bd7d98022 100644 --- a/doc/using/InvokingGHDL.rst +++ b/doc/using/InvokingGHDL.rst @@ -1,4 +1,3 @@ -.. program:: ghdl .. _USING:Invoking: Invoking GHDL @@ -32,14 +31,19 @@ The most commonly used commands of GHDL are those to analyze and elaborate a des .. index:: cmd analysis +.. _Analysis:command: + Analysis [``-a``] ---------------------- +----------------- .. option:: -a <[options...] file...> -Analyzes/compiles one or more files, and creates an object file for each source file. 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 (remaining files are not analyzed). +Analyzes/compiles one or more files, and creates an object file for each source file. 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 (remaining 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``. +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``. .. index:: cmd elaboration @@ -47,11 +51,13 @@ See :ref:`GHDL:options`, for details on the GHDL options. For example, to produc .. _Elaboration:command: Elaboration [``-e``] ------------------------- +-------------------- .. option:: -e <[options...] primary_unit [secondary_unit]> -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 object files required for the executable. Then, it links all these files with the runtime library. +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 object +files required for the executable. Then, it links all these files with the runtime library. * The elaboration command, :option:`-e`, must be followed by a name of either: @@ -59,11 +65,18 @@ Re-analyzes all the configurations, entities, architectures and package declarat * an entity unit * 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 section :ref:`Top_entity`, for the restrictions on the root design of a hierarchy. + 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 <--work>` option, as described in :ref:`GHDL:options`. See section :ref:`Top_entity`, for the + restrictions on the root design of a hierarchy. -* If the GCC/LLVM 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 and the the filename is the name of the primary unit, or for the latter case, the concatenation of the name of the primary unit, a dash, and the name of the secondary unit (or architecture). Option :option:`-o` followed by a filename can override the default executable filename. +* If the GCC/LLVM 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 and the the filename is the name of the primary unit, or for the latter + case, the concatenation of the name of the primary unit, a dash, and the name of the secondary unit (or architecture). + Option ``-o`` followed by a filename can override the default executable filename. -* If mcode is used, this command elaborates the design but does not generate anything. Since the run command also elaborates the design, this can be skipped. +* If mcode is used, this command elaborates the design but does not generate anything. Since the run command also + elaborates the design, this can be skipped. .. WARNING:: This elaboration command is not a complete elaboration in terms of the VHDL standard. The actual elaboration is performed at runtime. Therefore, in order to get a complete VHDL elaboration without running the simulation, ``ghdl --elab-run --no-run`` is required. @@ -71,12 +84,14 @@ Name of the units must be a simple name, without any dot. You can select the nam .. index:: cmd run +.. _Run:command: + Run [``-r``] ----------------- +------------ .. option:: -r <[options...] primary_unit [secondary_unit] [simulation_options...]> -Runs/simulates a design. The options and arguments are the same as for the :ref:`elaboration command <Elaboration_command>`. +Runs/simulates a design. The options and arguments are the same as for the :ref:`elaboration command <Elaboration:command>`. * GGC/LLVM: simply, the filename of the executable is determined and it is executed. Options are ignored. You may also directly execute the program. The executable must be in the current directory. * mcode: the design is elaborated and the simulation is launched. As a consequence, you must use the same options used during analysis. @@ -93,7 +108,7 @@ See section :ref:`USING:Simulation`, for details on options. .. index:: cmd elaborate and run Elaborate and run [``--elab-run``] --------------------------------------- +---------------------------------- .. option:: --elab-run <[elab_options...] primary_unit [secondary_unit] [run_options...]> @@ -103,7 +118,7 @@ Acts like the elaboration command (see :option:`-e`) followed by the run command .. index:: cmd checking syntax Check syntax [``-s``] -------------------------- +--------------------- .. option:: -s <[options] files> @@ -113,7 +128,7 @@ Analyze files but do not generate code. This command may be used to check the sy .. index:: cmd analyze and elaborate Analyze and elaborate [``-c``] ----------------------------------- +------------------------------ .. option:: -c <[options] file... -<e|r> primary_unit [secondary_unit]> @@ -146,8 +161,10 @@ Analyzing and elaborating a design consisting of several files can be tricky, du .. index:: cmd importing files +.. _Import:command: + Import [``-i``] -------------------- +--------------- .. option:: -i <[options] file...> @@ -163,15 +180,17 @@ See :option:`-m`, to actually build the design. .. index:: cmd make +.. _Make:command: + Make [``-m``] ------------------ +------------- .. option:: -m <[options] primary [secondary]> Analyze automatically outdated files and elaborate a design. The primary unit denoted by the ``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. A file may be outdated because it has been modified (e.g. you have just 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 option :option:`--bind`, 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 option :option:`-f` (force), GHDL analyzes all the units of the work library needed to create the design hierarchy. 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). +* With option ``--bind``, 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 option ``-f`` (force), GHDL analyzes all the units of the work library needed to create the design hierarchy. 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. @@ -215,8 +234,6 @@ Options .. index:: IEEE 1076.3 .. index:: 1076.3 -.. HINT:: 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. - .. index:: WORK library .. option:: --work=<LIB_NAME> @@ -231,7 +248,7 @@ Options Specify the directory where the ``WORK`` library is located. When this option is not present, the ``WORK`` library is in the current directory. The object files created by the compiler are always placed in the same directory as the ``WORK`` library. - Use option :option:`-P` to specify where libraries other than ``WORK`` are placed. + Use option :option:`-P <-P<DIRECTORY>>` to specify where libraries other than ``WORK`` are placed. .. option:: --std=<STANDARD> @@ -321,6 +338,14 @@ Options Enable parsing of PSL assertions within comments. See section :ref:`PSL_implementation` for more details. +.. option:: --format=<FORMAT> + + Define the output format of some options, such as :option:`--pp-html` or :option:`--xref-html`. + + * By default or when :option:`--format=html2 <--format>` is specified, generated files follow the HTML 2.0 standard, and colours are specified with `<FONT>` tags. However, colours are hard-coded. + + * If :option:`--format=css <--format>` is specified, generated 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. + .. option:: --no-vital-checks .. option:: --vital-checks @@ -330,7 +355,7 @@ Options Currently, VITAL checks are only partially implemented. See section :ref:`VHDL_restrictions_for_VITAL` for more details. -.. option:: --PREFIX<=PATH> +.. option:: --PREFIX=<PATH> Use :file:`PATH` as the prefix path to find commands and pre-installed (``std`` and ``ieee``) libraries. @@ -461,9 +486,9 @@ Library commands .. _Create_a_Library: .. index:: create your own library -A new library is created implicitly, by compiling entities (packages etc.) into it: ``ghdl -a --work=my_custom_lib my_file.vhd``. +A new library is created implicitly, by compiling entities (packages etc.) into it: ``ghdl -a --work=my_custom_lib my_file.vhdl``. -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:`-P` command line option. +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.vhdl``. See also the :option:`-P <-P<DIRECTORY>>` command line option. Furthermore, GHDL provides a few commands which act on a library: @@ -471,7 +496,7 @@ Furthermore, GHDL provides a few commands which act on a library: .. index:: cmd library directory Directory [``--dir``] -------------------------- +--------------------- .. option:: --dir <[options] [libs]> @@ -480,8 +505,10 @@ Displays the content of the design libraries (by default the ``work`` library). .. index:: cmd library clean +.. _Clean:command: + Clean [``--clean``] ------------------------ +------------------- .. option:: --clean <[options]> @@ -490,8 +517,10 @@ Try to remove any object, executable or temporary file it could have created. So .. index:: cmd library remove +.. _Remove:command: + Remove [``--remove``] -------------------------- +--------------------- .. option:: --remove <[options]> @@ -502,7 +531,7 @@ known anymore by GHDL. .. index:: cmd library copy Copy [``--copy``] ---------------------- +----------------- .. option:: --copy <--work=name [options]> @@ -525,7 +554,7 @@ command before its execution. .. index:: cmd VPI compile compile [``--vpi-compile``] -------------------------------- +--------------------------- .. option:: --vpi-compile <command> @@ -550,7 +579,7 @@ executes:: .. index:: cmd VPI link link [``--vpi-link``] -------------------------- +--------------------- .. option:: --vpi-link <command> @@ -576,7 +605,7 @@ executes:: .. index:: cmd VPI cflags cflags [``--vpi-cflags``] ------------------------------ +------------------------- .. option:: --vpi-cflags @@ -585,7 +614,7 @@ Display flags added by :option:`--vpi-compile`. .. index:: cmd VPI ldflags ldflags [``--vpi-ldflags``] -------------------------------- +--------------------------- .. option:: --vpi-ldflags @@ -594,7 +623,7 @@ Display flags added by :option:`--vpi-link`. .. index:: cmd VPI include dir include dir [``--vpi-include-dir``] ---------------------------------------- +----------------------------------- .. option:: --vpi-include-dir @@ -603,7 +632,7 @@ Display the include directory added by the compile flags. .. index:: cmd VPI library dir library dir [``--vpi-library-dir``] ---------------------------------------- +----------------------------------- .. option:: --vpi-library-dir @@ -615,7 +644,7 @@ Display the library directory added by the link flags. IEEE library pitfalls ===================== -When you use options :option:`--ieee=synopsys` or :option:`--ieee=mentor`, the ``ieee`` library contains non standard packages such as ``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 out, their use has pitfalls. For example, this description has an error during compilation: +When you use options :option:`--ieee=synopsys <--ieee>` or :option:`--ieee=mentor <--ieee>`, the ``ieee`` library contains non standard packages such as ``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 out, their use has pitfalls. For example, this description has an error during compilation: .. code-block:: VHDL diff --git a/doc/using/QuickStartGuide.rst b/doc/using/QuickStartGuide.rst deleted file mode 100644 index 572d7853b..000000000 --- a/doc/using/QuickStartGuide.rst +++ /dev/null @@ -1,249 +0,0 @@ -.. program:: ghdl -.. _USING:QuickStart: - -Quick Start Guide -################# - -In this chapter, you will learn how to use `GHDL` by working on a few examples. - -The `'Hello world'` program -=========================== - -To illustrate the general purpose of `VHDL`, here is a commented `'Hello world'` program which is saved in a file named :file:`hello.vhdl`: - -.. 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; - -.. TIP:: - - * Both ``.vhdl`` and ``.vhd`` extensions are used for VHDL source files, while ``.v`` is used for Verilog. - * Unless you use especial characters, either `UTF-8` or `ISO-8859-1` encodings can be used. However, if you do, the latter should be used. The standard defines ASCII (7-bit encoding) or ISO Latin-1 (ISO-8859-1) as default. However, GHDL has a relaxing option, :option:`--mb-comments` (multi byte), to allow UTF-8 or other encodings in comments. - -- First, you have to compile the file; this is called `analysis` of a design file in `VHDL` terms. Run ``ghdl -a hello.vhdl`` in the `shell`. This command creates or updates a file :file:`work-obj93.cf`, which describes the library ``work``. -- Then, run ``ghdl -e hello_world`` in the `shell`. Option :option:`-e` means :dfn:`elaborate`, which is used to build a design, with the ``hello_world`` entity at the top of the hierarchy. -- Last, you can directly launch the simulation running ``ghdl -r hello_world`` in the `shell`. The result of the simulation will be shown on screen: - -.. code-block:: shell - - Hello world! - -.. HINT:: - If a GCC/LLVM variant of `GHDL` is used: - - * `Analysis` generates a file, :file:`hello.o`, which is the object file corresponding to your `VHDL` program. This is not created with mcode. - * The elaboration step is mandatory after running the analysis and prior to launching the simulation. This will generate an executable binary named :file:`hello_world`. - * As a result, :option:`-r` is just a passthrough to the binary generated in the `elaboration`. Therefore, the executable can be run directly, ``./hello_world``. See :option:`-r` for more informartion. - -.. HINT:: :option:`-e` can be bypassed with mcode, since :option:`-r` actually elaborates the design and saves it on memory before running the simulation. But you can still use it to check for some elaboration problems. - -The `heartbeat` program -======================= - -.. code-block:: VHDL - - library ieee; - use ieee.std_logic_1164.all; - - entity heartbeat is - port ( clk: out std_logic); - end heartbeat; - - architecture behaviour of heartbeat - is - constant clk_period : time := 10 ns; - begin - -- Clock process definition - clk_process: process - begin - clk <= '0'; - wait for clk_period/2; - clk <= '1'; - wait for clk_period/2; - end process; - end behaviour; - -A full adder -============ - -VHDL is generally used for hardware design. This example starts with a `full adder <https://en.wikipedia.org/wiki/Adder_(electronics)#Full_adder>`_ described in a file named :file:`adder.vhdl`: - -.. 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 assignments. - -- 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, ``ghdl -a adder.vhdl``, and try to execute the `adder` design. But this is useless, since nothing externally visible will happen. In order to check this full adder, a :dfn:`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. A file named :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, ``ghdl -a adder_tb.vhdl``. - -.. HINT:: - Then, if required, elaborate the testbench: ``ghdl -e adder_tb``. You do not need to specify which object files are required, since GHDL knows them and automatically adds them. - -Now, it is time to run the testbench, ``ghdl -r adder_tb``, and check the result on screen:: - - adder_tb.vhdl:52:7:(assertion note): end of test - -If your design is rather complex, you'd like to inspect signals. Signal values can be dumped using multiple formats (see section :ref:`export_waves` for more information). The resulting file can be read with a wave viewer such as `GtkWave <http://gtkwave.sourceforge.net/>`_. - -As explained in the `manual <http://gtkwave.sourceforge.net/gtkwave.pdf>`_, GtkWave *'relies on a post-mortem approach through the use of dumpfiles'*. Therefore, you should first simulate your design and dump a waveform file, say VCD: ``ghdl -r adder_tb --vcd=adder.vcd``. Then, you can view the dump: ``gtkwave adder.vcd``. - -See section :ref:`simulation_options`, for more details on other runtime options. - -Starting with a design -====================== - -Unless you are only studying VHDL, you will work with larger 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 `ghdl.free.fr/dlx.tar.gz <http://ghdl.free.fr/dlx.tar.gz>`_ . - -- First, untar the sources: ``tar zxvf dlx.tar.gz``. - -.. HINT:: 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 - -* Then, we will run the ``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, ``ghdl -i --workdir=work *.vhdl``. - -* GHDL knows all the design units of the DLX, but none of them has been analyzed. Run the make option, ``ghdl -m --workdir=work dlx_test_behaviour``, which analyzes and elaborates a design. This creates many files in the :file:`work/` directory, and (GCC/LLVM only) the :file:`dlx_test_behaviour` executable in the current directory. - -.. HINT:: The simulation needs to have a DLX program contained in the file :file:`dlx.out`. This memory image will be loaded in the DLX memory. Just take one sample: ``cp test_loop.out dlx.out``. - -* Now, you can run the test suite: ``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 - -* Lastly, 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. To do so, call run with this option instead: ``ghdl -r --workdir=work dlx_test_behaviour --assert-level=note```. With this option, the program stops just after the previous message: - - .. code-block:: shell - - dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction - encountered, execution halted - error: assertion failed - -.. TIP:: If you want to make room on your hard drive, you can either: - - * Clean the design library with the GHDL command ``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 ``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 make the design. - * Remove the :file:`work/` directory: ``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. - -.. WARNING:: Sometimes, a design does not fully follow the VHDL standards. For example it might use the badly engineered ``std_logic_unsigned`` package. GHDL supports this VHDL dialect through some options: ``--ieee=synopsys -fexplicit``. See section :ref:`IEEE_library_pitfalls`, for more details. - - -Starting with your design -========================= - -Usually your design is more complex than the previous ones. The main -tips are: - -* Don't forget to select the VHDL standard you want to use. The - default is ``--std=93c`` which means VHDL-93 with some relaxed - rules. Use ``--std=08`` for VHDL-2008 (albeit not fully - implemented). All the units must be analyzed with the same standard. - -* Use ``--work=LIB_NAME`` to analyze files into the ``LIB_NAME`` library. - If you analyze other files from a different directory, give the path - of the ``LIB_NAME`` library using ``-P/path/to/name/directory/``. - -* Use ``--ieee=synopsys`` if your design depends on the non-standard - ieee library. - -* Use ``-fexplicit`` if needed. - -* Use the same options for elaboration. - -So, to analyze a file: ``ghdl -a --std=08 --work=mylib myfile.vhdl`` -To elaborate and run: ``ghdl --elab-run --std=08 top``. diff --git a/doc/using/Simulation.rst b/doc/using/Simulation.rst index 012a15621..0718fe079 100644 --- a/doc/using/Simulation.rst +++ b/doc/using/Simulation.rst @@ -1,4 +1,3 @@ -.. program:: ghdl .. _USING:Simulation: Simulation and runtime @@ -23,9 +22,7 @@ The exit status of the simulation is ``EXIT_SUCCESS`` (0) if the simulation completes, or ``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` option lists -all options available, including the debugging ones. +Here is the list of the most useful options. For further info, see :ref:`DEV:Debugging`. .. option:: -gGENERIC=VALUE @@ -35,7 +32,7 @@ all options available, including the debugging ones. This is currently a run option; but in the future it will be deprecated to become an elaboration option only. -.. option:: --assert-level<=LEVEL> +.. option:: --assert-level=<LEVEL> Select the assertion level at which an assertion violation stops the simulation. `LEVEL` is the name from the `severity_level` @@ -50,10 +47,10 @@ all options available, including the debugging ones. stop simulation, but the assertion violation at the ``note`` severity level would only display a message. - Option :option:`--assert-level=none` prevents any assertion violation from stopping + Option :option:`--assert-level=none <--assert-level>` prevents any assertion violation from stopping simulation. -.. option:: --ieee-asserts<=POLICY> +.. option:: --ieee-asserts=<POLICY> Select how the assertions from ``ieee`` units are handled. `POLICY` can be ``enable`` (the default), @@ -63,7 +60,7 @@ all options available, including the debugging ones. This option can be useful to avoid assertion messages from ``ieee.numeric_std`` (and other ``ieee`` packages). -.. option:: --stop-time<=TIME> +.. option:: --stop-time=<TIME> Stop the simulation after ``TIME``. ``TIME`` is expressed as a time value, *without* any space. The time is the simulation time, not @@ -74,7 +71,7 @@ all options available, including the debugging ones. $ ./my_design --stop-time=10ns $ ./my_design --stop-time=ps -.. option:: --stop-delta<=N> +.. option:: --stop-delta=<N> Stop the simulation after `N` delta cycles in the same current time. The default is 5000. @@ -89,12 +86,12 @@ all options available, including the debugging ones. Disable buffering on stdout, stderr and files opened in write or append mode (TEXTIO). -.. option:: --max-stack-alloc<=N> +.. option:: --max-stack-alloc=<N> Emit an error message in case of allocation on the stack of an object larger than `N` KB. Use 0 to disable these checks. -.. option:: --sdf<=PATH=FILENAME> +.. option:: --sdf=<PATH=FILENAME> Do VITAL annotation on `PATH` with SDF file :file:`FILENAME`. @@ -115,11 +112,11 @@ all options available, including the debugging ones. See section :ref:`Backannotation`, for more details. -.. option:: --vpi<=FILENAME> +.. option:: --vpi=<FILENAME> Load VPI module. -.. option:: --vpi-trace<=FILE> +.. option:: --vpi-trace=<FILE> Trace vpi calls to FILE. @@ -171,9 +168,9 @@ Export waveforms the design. Otherwise throws an error, because it won't erase an existing file. -.. option:: --vcd<=FILENAME> +.. option:: --vcd=<FILENAME> -.. option:: --vcdgz<=FILENAME> +.. option:: --vcdgz=<FILENAME> .. index:: vcd @@ -186,7 +183,7 @@ Export waveforms then the standard output is used, otherwise a file is created or overwritten. - The :option:`--vcdgz` option is the same as the *--vcd* option, + The :option:`--vcdgz` option is the same as the :option:`--vcd` option, but the output is compressed using the `zlib` (`gzip` compression). However, you can't use the ``-`` filename. Furthermore, only one VCD file can be written. @@ -224,13 +221,13 @@ Export waveforms Do not write date in the VCD file. -.. option:: --fst<=FILENAME> +.. option:: --fst=<FILENAME> Write the waveforms into an `fst` file 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> +.. 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 @@ -244,7 +241,7 @@ Export waveforms Export hierarchy and references =============================== -.. option:: --disp-tree<[=KIND]> +.. option:: --disp-tree=<KIND> .. index:: display design hierarchy @@ -266,17 +263,17 @@ Export hierarchy and references Stop the simulation before the first cycle. This may be used with :option:`--disp-tree` to display the tree without simulating the whole design. This option actually elaborates the design, so it will catch any bound error in port maps. -.. option:: --xref-html <[options] file...> +.. option:: --xref-html [options] files... - To easily navigate through your sources, you may generate cross-references. This command generates an html file for each ``file`` given in the command line, with syntax highlighting and full cross-reference: every identifier is a link to its declaration. An index of the files is created too. + To easily navigate through your sources, you may generate cross-references. This command generates an html file for + each ``file`` given in the command line, with syntax highlighting and full cross-reference: every identifier is a + link to its declaration. An index of the files is created too. - The set of ``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. + The set of ``files`` are analyzed, and then, if the analysis is successful, html files are generated in the directory + specified by the ``-o <DIR>`` option, or :file:`html/` directory by default. The style of the html file can be + modified with the :option:`--format` option. - * 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. - -.. option:: --psl-report<=FILENAME> +.. option:: --psl-report=<FILENAME> Write a report for PSL at the end of simulation. For each PSL cover and assert statements, the name, source location and whether it passed or failed is reported. The file is written using the JSON format, but is still human readable. @@ -287,72 +284,3 @@ Export hierarchy and references .. WARNING:: * The AST slightly changes from time to time (particularly when new nodes are added for new language features), so be liberal in what is allowed by your tool. Also, the XML can be quite large so consider it only during prototyping. * Note that at this time there is no XML dump of the elaborated design. - - -.. index:: debugging - -Debugging -========= - -.. option:: --trace-signals - - Display signals after each cycle. - -.. option:: --trace-processes - - Display process name before each cycle. - -.. option:: --stats - - Display run-time statistics. - -.. option:: --disp-order - - Display signals order. - -.. option:: --disp-sources - - Display sources while displaying signals. - -.. option:: --disp-sig-types - - Display signal types. - -.. option:: --disp-signals-map - - Display map bw declared signals and internal signals. - -.. option:: --disp-signals-table - - Display internal signals. - -.. option:: --checks - - Do internal checks after each process run. - -.. option:: --activity<=LEVEL> - - Watch activity of LEVEL signals: LEVEL is ``all``, ``min`` (default) or ``none`` (unsafe). - -.. option:: --dump-rti - - Dump Run Time Information (RTI). - -.. option:: --bootstrap - - Allow ``--work=std`` - -GNU Debugger (GDB) ------------------- - -.. index:: `__ghdl_fatal` - -.. WARNING:: Debugging VHDL programs using `GDB` is possible only with GCC/LLVM. - -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, it 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 catch a runtime error, such as indexing an array beyond its bounds. All error check subprograms call the ``__ghdl_fatal`` procedure. Therefore, to a 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. |