From 8599d9ddd15b15afdeced6059b1e1b7a972f4db1 Mon Sep 17 00:00:00 2001 From: 1138-4EB <1138-4EB@users.noreply.github.com> Date: Mon, 11 Nov 2019 18:46:36 +0000 Subject: 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' --- .github/workflows/doc.yml | 9 + doc/Makefile | 34 ++- doc/about.rst | 8 +- doc/appendix/Meta.rst | 96 ------- doc/appendix/Roadmap.rst | 15 -- doc/build.sh | 27 -- doc/conf.py | 3 +- doc/contribute.rst | 2 +- doc/development/CodingStyle.rst | 238 +++++++++++++++++ doc/development/Debugging.rst | 75 ++++++ doc/development/Roadmap.rst | 26 ++ doc/development/Synthesis.rst | 8 + doc/examples/README.rst | 12 + doc/examples/VHPIDIRECT.rst | 18 ++ doc/examples/quick_start/DLXModelSuite.rst | 66 +++++ doc/examples/quick_start/README.rst | 49 ++++ doc/examples/quick_start/adder/README.rst | 35 +++ doc/examples/quick_start/adder/adder.vhdl | 14 + doc/examples/quick_start/adder/adder_tb.vhdl | 57 +++++ doc/examples/quick_start/heartbeat/README.rst | 41 +++ doc/examples/quick_start/heartbeat/heartbeat.vhdl | 20 ++ doc/examples/quick_start/hello/README.rst | 52 ++++ doc/examples/quick_start/hello/hello.vhdl | 17 ++ doc/getting/PrecompileVendorPrimitives.rst | 74 +++--- doc/getting/mcode.rst | 2 +- doc/index.rst | 55 ++-- doc/make.sh | 28 ++ doc/references/CodingStyle.rst | 139 ---------- doc/references/CommandReference.rst | 210 --------------- doc/references/ImplementationOfVHDL.rst | 297 --------------------- doc/references/ImplementationOfVITAL.rst | 94 ------- doc/using/CommandReference.rst | 206 +++++++++++++++ doc/using/ImplementationOfVHDL.rst | 299 ++++++++++++++++++++++ doc/using/ImplementationOfVITAL.rst | 94 +++++++ doc/using/InvokingGHDL.rst | 99 ++++--- doc/using/QuickStartGuide.rst | 249 ------------------ doc/using/Simulation.rst | 120 ++------- testsuite/sanity/005examples/extract_vhdl.py | 30 --- testsuite/sanity/005examples/testsuite.sh | 11 +- 39 files changed, 1542 insertions(+), 1387 deletions(-) create mode 100644 .github/workflows/doc.yml delete mode 100644 doc/appendix/Meta.rst delete mode 100644 doc/appendix/Roadmap.rst delete mode 100644 doc/build.sh create mode 100644 doc/development/CodingStyle.rst create mode 100644 doc/development/Debugging.rst create mode 100644 doc/development/Roadmap.rst create mode 100644 doc/development/Synthesis.rst create mode 100644 doc/examples/README.rst create mode 100644 doc/examples/VHPIDIRECT.rst create mode 100644 doc/examples/quick_start/DLXModelSuite.rst create mode 100644 doc/examples/quick_start/README.rst create mode 100644 doc/examples/quick_start/adder/README.rst create mode 100644 doc/examples/quick_start/adder/adder.vhdl create mode 100644 doc/examples/quick_start/adder/adder_tb.vhdl create mode 100644 doc/examples/quick_start/heartbeat/README.rst create mode 100644 doc/examples/quick_start/heartbeat/heartbeat.vhdl create mode 100644 doc/examples/quick_start/hello/README.rst create mode 100644 doc/examples/quick_start/hello/hello.vhdl create mode 100755 doc/make.sh delete mode 100644 doc/references/CodingStyle.rst delete mode 100644 doc/references/CommandReference.rst delete mode 100644 doc/references/ImplementationOfVHDL.rst delete mode 100644 doc/references/ImplementationOfVITAL.rst create mode 100644 doc/using/CommandReference.rst create mode 100644 doc/using/ImplementationOfVHDL.rst create mode 100644 doc/using/ImplementationOfVITAL.rst delete mode 100644 doc/using/QuickStartGuide.rst delete mode 100644 testsuite/sanity/005examples/extract_vhdl.py diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml new file mode 100644 index 000000000..ca57d00e2 --- /dev/null +++ b/.github/workflows/doc.yml @@ -0,0 +1,9 @@ +name: 'doc' +on: [push, pull_request] +jobs: + linux: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - name: build doc + run: ./doc/make.sh 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 `_ `1076`. Four revisions exist: `1987 `_, `1993 `_, `2002 `_ and `2008 `_. The standardization is handled by the VHDL Analysis and Standardization Group (`VASG/P1076 `_). - .. _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 `_, `LLVM `_ or :wikipedia:`x86 `/:wikipedia:`i386 ` only, a built-in one) and runs on :wikipedia:`GNU/Linux `, :wikipedia:`Windows ` |trade| and :wikipedia:`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 `_, :wikipedia:`VCD ` or `FST` files which can be viewed with a :wikipedia:`waveform viewer `, such as `GtkWave `_. +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 `_, :wikipedia:`VCD ` or `FST` files which can be viewed with a :wikipedia:`waveform viewer `, such as `GtkWave `_. GHDL aims at implementing VHDL as defined by `IEEE 1076 `_. It supports the `1987 `_, `1993 `_ and `2002 `_ revisions and, partially, the latest, `2008 `_. :wikipedia:`PSL ` is also partially supported. @@ -42,9 +41,8 @@ Several third party projects are supported: `VUnit `_, .. 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 `_ is a complementary repository that lets GHDL to be loaded by `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 - 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 `_. - * External ref and link to section:: - - :ref:`GHDL 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 `_ 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 `_ 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 + 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 `_. + * External ref and link to section:: + + :ref:`GHDL 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= + + 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 `_ is a complementary repository that lets GHDL to be loaded by `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 `_ 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 `_ for details about the API. + +ghdlex and netpp +================ + +`netpp (network property protocol) `_ 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 `_ 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 `_ 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 `_, 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 `_ . + +- 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 ` 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 ` + 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 ` 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 ` 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 ` 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>`. + +* 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 `, the target hardware design in this example is written using the +synthesisable subset of `VHDL`. It is a `full adder `_ +described in a file named :file:`adder.vhdl`: + +.. literalinclude:: adder.vhdl + :language: vhdl + +You can :ref:`analyse ` 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 ` 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 ` 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 `. + +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 ` 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 `, :ref:`elaborated ` and :ref:`run `, 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 `_, +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 `_. As +explained in the `manual `_, 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 ` 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 `_ + file format, some users prefer ``.vhdl``, to avoid ambiguity. This is the case with `GHDL`'s codebase. However, in order + to maintain `backward-compatibility `_ 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 ` 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 `, + 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 ` ``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 ` generates a file, :file:`hello.o`, which is the object file corresponding to + your `VHDL` program. This is not created with :ref:`mcode `. These kind of object files can be + compiled into foreign programs (see :ref:`Linking_with_Ada`). + * The :ref:`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 :ref:`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. 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 ``` * **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 * **Step 2 - Start the compilation script(s)** - + .. code-block:: PowerShell PS> \libraries\vendors\compile-altera.ps1 -All @@ -169,6 +172,7 @@ Compiling on Windows PS> \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: @@ -81,19 +65,6 @@ LRM) is a plus. contribute licenses -.. raw:: latex - - \part{GHDL usage} - -.. toctree:: - :caption: GHDL usage - :hidden: - - using/QuickStartGuide - using/InvokingGHDL - using/Simulation - using/Foreign - .. raw:: latex \part{Getting GHDL} @@ -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- . < - -Display the program paths and options used by GHDL. This may be useful to track installation errors. - -.. index:: cmd display standard -.. index:: display ``std.standard`` - -Display standard [``--disp-standard``] ------------------------------------------- - -.. option:: --disp-standard <[options]> - -Display the ``std.standard`` package. - -.. index:: cmd version - -Version [``--version``] ---------------------------- - -.. option:: --version, -v - -Display the GHDL version. - -File commands -============= - -The following commands act on one or several files. These are not analyzed, therefore, they work even if a file has semantic errors. - -.. index:: cmd file pretty printing -.. index:: vhdl to html - -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 `` 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. - -.. index:: cmd file find - -Find [``-f``] ------------------ - -.. option:: -f - -The files are scanned, parsed and the names of design units are displayed. Design units marked with two stars are candidates to be at the apex of a design hierarchy. - -.. index:: cmd file chop - -Chop [``--chop``] ---------------------- - -.. option:: --chop - -The provided files are read, and a file is written in the current directory for every design unit. Each filename is built according to the type: - -* For an entity declaration, a package declaration, or a configuration the file name is :file:`NAME.vhdl`, where `NAME` is the name of the design unit. -* For a package body, the filename is :file:`NAME-body.vhdl`. -* Finally, for an architecture `ARCH` of an entity `ENTITY`, the filename is :file:`ENTITY-ARCH.vhdl`. - -Since the input files are parsed, this command aborts in case of syntax error. The command aborts too if a file to be written already exists. - -Comments between design units are stored into the most adequate files. - -This command may be useful to split big files, if your computer doesn't have enough memory to compile such files. The size of the executable is reduced too. - -.. index:: cmd file lines - -Lines [``--lines``] ------------------------ - -.. option:: --lines - -Display on the standard output lines of files preceded by line number. - -.. _gccllvm-only-programs: - -GCC/LLVM only commands -====================== - -.. index:: cmd GCC/LLVM binding - -Bind [``--bind``] ---------------------- - -.. option:: --bind <[options] primary_unit [secondary_unit]> - -Performs only the first stage of the elaboration command; the list of object files is created but the executable is not built. This command should be used only when the main entry point is not GHDL. - -.. 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. - -.. index:: cmd GCC/LLVM linking - -Link [``--link``] ---------------------- - -.. option:: --link <[options] primary_unit [secondary_unit]> - -Performs only the second stage of the elaboration command: the executable is created by linking the files of the object files list. This command is available only for completeness. The elaboration command is equivalent to the bind command followed by the link command. - -.. index:: cmd GCC/LLVM list link - -List link [``--list-link``] -------------------------------- - -.. option:: --list-link - -This command may be used only after a bind command. GHDL displays all the files which will be linked to create an executable and additional arguments for the linker. This command is intended to add object files in a link of a foreign program. This command should be used only after ``ghdl --bind``, as some files generated by it are looked for in the current path. - -.. HINT:: - One of the arguments returned by ``--list-link`` is ``-Wl,--version-script=PREFIX/lib/ghdl/grt.ver``, where `PREFIX` is the installation path of GHDL. This will hide most of the symbols when the target executable binary is built. In some contexts, where the binary is to be loaded dynamically, the user might want additional symbols to be accessible. There are two possible approaches to have it done: - - * Filter the output of ``--list-link`` with e.g. ``sed``. - * Provide an additional non-anonymous version script: ``-Wl,-Wl,--version-script=file.ver``. - -Options -======= - -.. option:: --mb-comments, -C - -Allow multi-bytes chars in a comment. - -.. option:: --syn-binding - -Use synthesizer rules for component binding. During elaboration, if a component is not bound to an entity using VHDL LRM rules, try to find in any known library an entity whose name is the same as the component name. - -This rule is known as the synthesizer rule. - -There are two key points: normal VHDL LRM rules are tried first and entities are searched only in known libraries. A known library is a library which has been named in your design. - -This option is only useful during elaboration. - -.. option:: --GHDL1<=COMMAND> - -Use ``COMMAND`` as the command name for the compiler. If ``COMMAND`` is not a path, then it is searched in the path. - -.. option:: --AS<=COMMAND> - -Use ``COMMAND`` as the command name for the assembler. If ``COMMAND`` is not a path, then it is searched in the path. The default is ``as``. - -.. option:: --LINK<=COMMAND> - -Use ``COMMAND`` as the linker driver. If ``COMMAND`` is not a path, then it is searched in the path. The default is ``gcc``. - -.. _passing-options-to-other-programs: - -Passing options to other programs -================================= - -.. WARNING:: These options are only available with GCC/LLVM. - -For many commands, GHDL acts as a driver: it invokes programs to perform the command. You can pass arbitrary options to these programs. - -Both the compiler and the linker are in fact GCC programs. See the GCC manual for details on GCC options. - -.. option:: -Wc,