From 78cf122a7535f79d9bfd6398eb30a43005a3863c Mon Sep 17 00:00:00 2001 From: umarcor Date: Mon, 7 Feb 2022 15:47:21 +0100 Subject: doc/internals/Overview: update --- doc/_static/internals.png | Bin 0 -> 141392 bytes doc/index.rst | 2 +- doc/internals/Overview.rst | 25 ------------------------- doc/internals/img/internals.png | Bin 80333 -> 0 bytes doc/internals/index.rst | 34 ++++++++++++++++++++++++++++++++++ 5 files changed, 35 insertions(+), 26 deletions(-) create mode 100644 doc/_static/internals.png delete mode 100644 doc/internals/Overview.rst delete mode 100644 doc/internals/img/internals.png create mode 100644 doc/internals/index.rst diff --git a/doc/_static/internals.png b/doc/_static/internals.png new file mode 100644 index 000000000..01399b5d9 Binary files /dev/null and b/doc/_static/internals.png differ diff --git a/doc/index.rst b/doc/index.rst index e114f3965..8cddac6bf 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -178,7 +178,7 @@ GHDL :caption: Internals :hidden: - internals/Overview + internals/index internals/Frontend internals/AST internals/RTI diff --git a/doc/internals/Overview.rst b/doc/internals/Overview.rst deleted file mode 100644 index fd29f5832..000000000 --- a/doc/internals/Overview.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _INT:Overview: - -Overview -######## - -.. image:: img/internals.png - :width: 350px - :align: center - -`GHDL` is architectured like a traditionnal compiler. It has: - -* a driver (sources in :ghdlsrc:`src/ghdldrv `) to call the programs (compiler, assembler, linker) if needed. - -* a runtime library named GRT (sources in :ghdlsrc:`src/grt `) to help execution at run-time. This ensures that execution is cycle-accurate. - -* a front-end (sources in :ghdlsrc:`src/vhdl `) to parse and analyse VHDL. See :ref:`INT:Frontend` and :ref:`INT:AST`. - -* multiple back-ends to generate either code or netlists. - - * Three for :ref:`simulation ` (sources are in :ghdlsrc:`src/ortho `): mcode, LLVM and GCC. See :ref:`BUILD`. - * Two for :ref:`synthesis ` (sources in :ghdlsrc:`src/synth `): :ref:`--synth ` and :ref:`Synth:plugin`. - -The architecture is modular. For example, the front-end in the ``libghdl`` library is used for the language server. - -The main work is performed by the front-end, which is documented in the next chapter. diff --git a/doc/internals/img/internals.png b/doc/internals/img/internals.png deleted file mode 100644 index cc6714287..000000000 Binary files a/doc/internals/img/internals.png and /dev/null differ diff --git a/doc/internals/index.rst b/doc/internals/index.rst new file mode 100644 index 000000000..4614d0edc --- /dev/null +++ b/doc/internals/index.rst @@ -0,0 +1,34 @@ +.. _INT:Overview: + +Overview +######## + +.. figure:: ../_static/internals.png + :width: 100% + :align: center + + Architecture overview of the GHDL toolkit (CLI, libghdl, pyGHDL and ghdl-yosys-plugin). + +`GHDL` is architectured like a traditionnal compiler. It has: + +* a driver (sources in :ghdlsrc:`src/ghdldrv `) to call the programs (compiler, assembler, linker) if needed. + +* a runtime library named GRT (sources in :ghdlsrc:`src/grt `) to help execution at run-time. + This ensures that execution is cycle-accurate. + +* a front-end (sources in :ghdlsrc:`src/vhdl `) to parse and analyse VHDL. + See :ref:`INT:Frontend` and :ref:`INT:AST`. + +* multiple back-ends to generate either code or netlists. + + * Three for :ref:`simulation ` (sources are in :ghdlsrc:`src/ortho `): mcode, LLVM and GCC. + See :ref:`BUILD`. + * Two for :ref:`synthesis ` (sources in :ghdlsrc:`src/synth `): + :ref:`--synth ` and :ref:`Synth:plugin`. + +The architecture is modular and some of the components are available through the shared library ``libghdl``. +``libghdl`` is used by the :ref:`Synth:plugin`, the Language Server Protocol (LSP) server, and to fill the data of +pyVHDLModel (see :doc:`vhdlmodel:index`). + +The main work with regard to understanding the VHDL language is performed by the front-end, which is documented in the +next section. -- cgit v1.2.3 From 348388efb66ab7dbfe42539de613ccc80310eb7b Mon Sep 17 00:00:00 2001 From: umarcor Date: Mon, 7 Feb 2022 17:36:20 +0100 Subject: doc/conf: add interpshinx target 'vasg' --- doc/conf.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 4071310a5..b01d17329 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -191,10 +191,11 @@ extensions = [ # Sphinx.Ext.InterSphinx # ============================================================================== intersphinx_mapping = { - 'python': ('https://docs.python.org/3.6/', None), - 'cosim': ('https://ghdl.github.io/ghdl-cosim', None), - 'poc': ('https://poc-library.readthedocs.io/en/release', None), + 'python': ('https://docs.python.org/3.6/', None), + 'cosim': ('https://ghdl.github.io/ghdl-cosim', None), + 'poc': ('https://poc-library.readthedocs.io/en/release', None), 'vhdlmodel': ('https://vhdl.github.io/pyVHDLModel', None), + 'vasg': ('https://ieee-p1076.gitlab.io', None) } -- cgit v1.2.3 From 6f972aaf43085c362239e3980a26868df18c2fd8 Mon Sep 17 00:00:00 2001 From: umarcor Date: Mon, 7 Feb 2022 17:36:28 +0100 Subject: doc/About: update --- doc/about.rst | 38 ++++++++++++++++++++++++++++---------- 1 file changed, 28 insertions(+), 10 deletions(-) diff --git a/doc/about.rst b/doc/about.rst index fea576f21..388e75d15 100644 --- a/doc/about.rst +++ b/doc/about.rst @@ -12,20 +12,27 @@ About What is `VHDL`? =============== -:wikipedia:`VHDL ` is an acronym for Very High Speed Integrated Circuit (:wikipedia:`VHSIC `) Hardware -Description Language (:wikipedia:`HDL `), which is a programming language used to describe a logic circuit by -function, data flow behavior, or structure. +:wikipedia:`VHDL ` is an acronym for *Verification and Hardware Description Language* (:wikipedia:`HDL `), +which is a programming language used to describe a logic circuit by function, data flow behavior, or structure. -Although VHDL was not designed for writing general purpose programs, VHDL *is* a programming language, and you can write -any algorithm with it. +.. NOTE:: + Historically the 'V' in the language's acronym came from the Very High Speed Integrated Circuit (:wikipedia:`VHSIC `), + which was the U.S. government program that funded the early work on the standard. + Changing the 'V' to mean verification reflects the language's increasing usage for verification as well as design. + See `VHDL 202X PAR `__ via :ref:`vasg:VHDL202X`. + +Although VHDL was not designed for writing general purpose programs, VHDL *is* a programming language: you can write any +algorithm with it, you can interact with files, with the environment, etc. If you are able to write programs, you will find in VHDL features similar to those found in procedural languages such as -`C`, `Python`, or `Ada`. +:wikipedia:`C `, +:wikipedia:`Python `, +or :wikipedia:`Ada `. Indeed, VHDL derives most of its syntax and semantics from Ada. Knowing `Ada` is an advantage for learning VHDL (it is an advantage in general as well). However, VHDL was not designed as a general purpose language but as an `HDL`. As the name implies, VHDL aims at modeling or documenting electronics systems. -Due to the nature of hardware components which are always running, VHDL is a highly concurrent language, built upon an +Due to the nature of hardware components --which are always running--, VHDL is a highly concurrent language, built upon an event-based timing model. Like a program written in any other language, a VHDL program can be executed. @@ -41,13 +48,21 @@ Five revisions exist: `2002 `__, `2008 `__ and `2019 `__. -The standardization is handled by the VHDL Analysis and Standardization Group (`VASG/P1076 `__). +The standardization is handled by the :doc:`vasg:index`. +Find on-going work towards *VHDL 202X* in `gitlab.com/IEEE-P1076/VHDL-Issues `__. .. _INTRO:GHDL: What is GHDL? ============= +.. figure:: _static/internals.png + :width: 100% + :align: center + :target: internals/index.html + + Architecture overview of the GHDL toolkit (CLI, libghdl, pyGHDL and ghdl-yosys-plugin). + `GHDL` is a shorthand for `G Hardware Design Language` (currently, `G` has no meaning). It is a VHDL analyzer, compiler, simulator and (experimental) synthesizer that can process (nearly) any VHDL design. @@ -83,9 +98,12 @@ It supports the Several third party projects are supported: `Yosys `__ (through the `ghdl-yosys-plugin `__) -`cocotb `__ +`cocotb `__, (through the `VPI interface `__), -`VUnit `__, `OSVVM `__, ... +`VUnit `__, +`OSVVM `__, +:doc:`vhdlmodel:index`, +... .. _INTRO:WHO: -- cgit v1.2.3 From d275c83869d154f2f6529f1e64391f90de9ee64b Mon Sep 17 00:00:00 2001 From: umarcor Date: Mon, 7 Feb 2022 17:52:26 +0100 Subject: doc: use theme_overrides and class 'shield' to fix the width of SHIELDs --- doc/_static/theme_overrides.css | 59 ++----------------------------------- doc/_static/theme_overrides.old.css | 58 ++++++++++++++++++++++++++++++++++++ doc/conf.py | 3 ++ doc/helpers.py | 18 +++++++---- 4 files changed, 75 insertions(+), 63 deletions(-) create mode 100644 doc/_static/theme_overrides.old.css diff --git a/doc/_static/theme_overrides.css b/doc/_static/theme_overrides.css index 4a5cae28e..c87b7353d 100644 --- a/doc/_static/theme_overrides.css +++ b/doc/_static/theme_overrides.css @@ -1,58 +1,3 @@ -/* Change font sizes*/ -html,body{font-size:98%;} -p{font-size:95%;margin-bottom:12px} -.wy-breadcrumbs li.wy-breadcrumbs-aside{font-size:95%} -.rst-versions{font-size:50%} -.rst-versions .rst-current-version {font-size: 165%} -.rst-versions dd{font-size:175%} -footer {font-size: 75%;} -.rst-footer-buttons {font-size: 140%;} - -/*Shrink left nav to 260px*/ -.wy-nav-side,.rst-versions,.wy-side-nav-search,.wy-menu-vertical{width: 260px} -.wy-nav-content-wrap{margin-left:260px;background:#fcfcfc;min-height:100%} -@media screen and (max-width: 768px){ - .wy-nav-top i {padding-top:7px} - .wy-nav-content-wrap{margin-left:0px} - .wy-nav-content-wrap.shift{margin-left:260px;position: static;} - .wy-nav-side.shift{width:260px;padding-bottom: 40px;} - .rst-versions{width:260px} - .wy-side-scroll{width:280px;} +.rst-content img.shield { + max-width: unset; } - -/*Fix shields in small screens*/ -@media screen and (max-width: 768px){img{width: auto}} -/*Fix shield sizes in WhoUsesGHDL*/ -.whouses>.wy-table-responsive img {width:auto;height:20px !important;;display:inline} -.whouses>.wy-table-responsive td {text-align:center} -.whouses>.wy-table-responsive>table>thead th{min-width:130px !important} -.whouses>.wy-table-responsive td:last-child{text-align: left} - -/*Remove 1 indentation space in the sidemenu items*/ -.wy-menu-vertical li.current a, .wy-menu-vertical li.toctree-l2.current > a{padding:0.4045em 1.618em} -.wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a{padding: 0.4045em 1.8em} -.wy-menu-vertical li.toctree-l3.current li.toctree-l4 > a{padding: 0.4045em 2.618em} - -/*Remove empty add*/ -div.wy-menu.rst-pro{display: none !important;max-width: 260px} - -/*Simplify 'versions' tab*/ -.rst-versions dt{display:none} -.rst-versions dd a[href$='.rst'] {display: none} -.rst-versions dd a[href$='/downloads/'] {display: none} -.rst-versions .wy-form{display:none !important;} -.rst-versions .rst-other-versions dd a{padding: 3px} -.rst-versions .rst-other-versions strong dd a{color: #27AE60} -.rst-versions .rst-other-versions hr{margin: 5px 0; margin-top: -14px} - -.rst-versions {border-top: none} - -/*Last doc build date*/ -.lastdocbuilddate {position:fixed;padding-top:30px;font-size:70%;color:#999} - -/*Reduce space between footnotes*/ -.footnotes > .wy-table-responsive {margin-top:-12px;margin-bottom:12px} - -/*Reduce margin below lists*/ -.rst-content .section ul, .rst-content .toctree-wrapper ul, article ul {margin-bottom: 12px} -.rst-content blockquote {margin-bottom: 12px;} diff --git a/doc/_static/theme_overrides.old.css b/doc/_static/theme_overrides.old.css new file mode 100644 index 000000000..4a5cae28e --- /dev/null +++ b/doc/_static/theme_overrides.old.css @@ -0,0 +1,58 @@ +/* Change font sizes*/ +html,body{font-size:98%;} +p{font-size:95%;margin-bottom:12px} +.wy-breadcrumbs li.wy-breadcrumbs-aside{font-size:95%} +.rst-versions{font-size:50%} +.rst-versions .rst-current-version {font-size: 165%} +.rst-versions dd{font-size:175%} +footer {font-size: 75%;} +.rst-footer-buttons {font-size: 140%;} + +/*Shrink left nav to 260px*/ +.wy-nav-side,.rst-versions,.wy-side-nav-search,.wy-menu-vertical{width: 260px} +.wy-nav-content-wrap{margin-left:260px;background:#fcfcfc;min-height:100%} +@media screen and (max-width: 768px){ + .wy-nav-top i {padding-top:7px} + .wy-nav-content-wrap{margin-left:0px} + .wy-nav-content-wrap.shift{margin-left:260px;position: static;} + .wy-nav-side.shift{width:260px;padding-bottom: 40px;} + .rst-versions{width:260px} + .wy-side-scroll{width:280px;} +} + +/*Fix shields in small screens*/ +@media screen and (max-width: 768px){img{width: auto}} +/*Fix shield sizes in WhoUsesGHDL*/ +.whouses>.wy-table-responsive img {width:auto;height:20px !important;;display:inline} +.whouses>.wy-table-responsive td {text-align:center} +.whouses>.wy-table-responsive>table>thead th{min-width:130px !important} +.whouses>.wy-table-responsive td:last-child{text-align: left} + +/*Remove 1 indentation space in the sidemenu items*/ +.wy-menu-vertical li.current a, .wy-menu-vertical li.toctree-l2.current > a{padding:0.4045em 1.618em} +.wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a{padding: 0.4045em 1.8em} +.wy-menu-vertical li.toctree-l3.current li.toctree-l4 > a{padding: 0.4045em 2.618em} + +/*Remove empty add*/ +div.wy-menu.rst-pro{display: none !important;max-width: 260px} + +/*Simplify 'versions' tab*/ +.rst-versions dt{display:none} +.rst-versions dd a[href$='.rst'] {display: none} +.rst-versions dd a[href$='/downloads/'] {display: none} +.rst-versions .wy-form{display:none !important;} +.rst-versions .rst-other-versions dd a{padding: 3px} +.rst-versions .rst-other-versions strong dd a{color: #27AE60} +.rst-versions .rst-other-versions hr{margin: 5px 0; margin-top: -14px} + +.rst-versions {border-top: none} + +/*Last doc build date*/ +.lastdocbuilddate {position:fixed;padding-top:30px;font-size:70%;color:#999} + +/*Reduce space between footnotes*/ +.footnotes > .wy-table-responsive {margin-top:-12px;margin-bottom:12px} + +/*Reduce margin below lists*/ +.rst-content .section ul, .rst-content .toctree-wrapper ul, article ul {margin-bottom: 12px} +.rst-content blockquote {margin-bottom: 12px;} diff --git a/doc/conf.py b/doc/conf.py index b01d17329..fc1888b6a 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -86,6 +86,9 @@ html_theme_options = { 'home_breadcrumbs': False, 'vcs_pageview_mode': 'blob', } +html_css_files = [ + "theme_overrides.css", +] html_static_path = ['_static'] # '/public' will contain the output from gnatdoc diff --git a/doc/helpers.py b/doc/helpers.py index 9baddf700..5d099e729 100644 --- a/doc/helpers.py +++ b/doc/helpers.py @@ -26,13 +26,19 @@ def printShieldSrc(label, alt, img, target, latex=False): if latex: if label[-6:] == '/total': label = label[:-6] - print('.. |l' + re.compile('[\W_]+').sub('', label) + '| replace:: `' + label + '`_') - print('.. _' + label + ': ' + target + '\n') + idx = re.compile('[\W_]+').sub('', label) + print(f""" +.. |l{idx}| replace:: `{label}`_ +.. _{label}: {target} +""") else: - print('.. |' + label + '| image:: '+ img + '\n', - ' :target: ' + target + '\n', - ' :height: 22\n', - ' :alt: ' + alt + '\n') + print(f''' +.. |{label}| image:: {img} + :target: {target} + :height: 22 + :alt: {alt} + :class: shield +''') # # Create shields/badges from JSON file -- cgit v1.2.3 From 76b17599cb66d757e1ced79a8a786c924e409a26 Mon Sep 17 00:00:00 2001 From: umarcor Date: Mon, 7 Feb 2022 18:17:18 +0100 Subject: doc: move toctrees to a file --- doc/index.rst | 66 +---------------------------------------------------------- doc/toc.rst | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 66 insertions(+), 65 deletions(-) create mode 100644 doc/toc.rst diff --git a/doc/index.rst b/doc/index.rst index 8cddac6bf..58c5fcb16 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -129,68 +129,4 @@ GHDL .. rubric:: 23.10.2015 - GHDL 0.33 was released. -.. toctree:: - :caption: Introduction - :hidden: - - about - getting - contribute - licenses - -.. raw:: latex - - \part{Usage} - -.. toctree:: - :caption: GHDL usage - :hidden: - - quick_start/index - using/InvokingGHDL - using/Simulation - using/Synthesis - using/CommandReference - using/ImplementationOfVHDL - using/ImplementationOfVITAL - -.. raw:: latex - - \part{Development} - -.. toctree:: - :caption: Development - :hidden: - - development/Directories - Building GHDL - Python Interfaces - ghw/index - development/Debugging - development/CodingStyle - development/Scripts - -.. raw:: latex - - \part{Internals} - -.. toctree:: - :caption: Internals - :hidden: - - internals/index - internals/Frontend - internals/AST - internals/RTI - gnatdoc/index - -.. raw:: latex - - \part{Index} - -.. toctree:: - :caption: Index - :hidden: - - genindex - py-modindex +.. include:: toc.rst diff --git a/doc/toc.rst b/doc/toc.rst new file mode 100644 index 000000000..51c52fbf6 --- /dev/null +++ b/doc/toc.rst @@ -0,0 +1,65 @@ +.. toctree:: + :caption: Introduction + :hidden: + + about + getting + contribute + licenses + +.. raw:: latex + + \part{Usage} + +.. toctree:: + :caption: GHDL usage + :hidden: + + quick_start/index + using/InvokingGHDL + using/Simulation + using/Synthesis + using/CommandReference + using/ImplementationOfVHDL + using/ImplementationOfVITAL + +.. raw:: latex + + \part{Development} + +.. toctree:: + :caption: Development + :hidden: + + development/Directories + Building GHDL + Python Interfaces + ghw/index + development/Debugging + development/CodingStyle + development/Scripts + +.. raw:: latex + + \part{Internals} + +.. toctree:: + :caption: Internals + :hidden: + + internals/index + internals/Frontend + internals/AST + internals/RTI + gnatdoc/index + +.. raw:: latex + + \part{Index} + +.. toctree:: + :caption: Index + :hidden: + + genindex + py-modindex -- cgit v1.2.3 From ea18eb25e53567a979d40d6cc2d69e1d3e289c93 Mon Sep 17 00:00:00 2001 From: umarcor Date: Mon, 7 Feb 2022 18:20:07 +0100 Subject: doc/conf: fall back to 'alabaster' if '_theme' does not exist --- doc/conf.py | 38 +++++++++++++++++++++++--------------- 1 file changed, 23 insertions(+), 15 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index fc1888b6a..8b01b32c7 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -2,10 +2,14 @@ import sys from os.path import abspath from pathlib import Path -from json import loads +from json import loads as json_loads from pyTooling.Packaging import extractVersionInformation + +ROOT = Path(__file__).resolve().parent + + # 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. @@ -79,16 +83,24 @@ except Exception as ex: # ============================================================================== # Options for HTML output # ============================================================================== -html_theme = "_theme" -html_theme_path = ["."] -html_theme_options = { - 'logo_only': True, - 'home_breadcrumbs': False, - 'vcs_pageview_mode': 'blob', -} -html_css_files = [ - "theme_overrides.css", -] +html_context = {} +ctx = ROOT / "context.json" +if ctx.is_file(): + html_context.update(json_loads(ctx.open("r").read())) + +if (ROOT / "_theme").is_dir(): + html_theme_path = ["."] + html_theme = "_theme" + html_theme_options = { + "logo_only": True, + "home_breadcrumbs": False, + "vcs_pageview_mode": "blob", + } + html_css_files = [ + "theme_overrides.css", + ] +else: + html_theme = "alabaster" html_static_path = ['_static'] # '/public' will contain the output from gnatdoc @@ -97,10 +109,6 @@ html_extra_path = [str(Path(__file__).resolve().parent.parent / 'public')] # F html_logo = str(Path(html_static_path[0]) / 'logo.png') html_favicon = str(Path(html_static_path[0]) / 'icon.png') -html_context = {} -ctx = Path(__file__).resolve().parent / 'context.json' -if ctx.is_file(): - html_context.update(loads(ctx.open('r').read())) # ============================================================================== # Options for manual page output -- cgit v1.2.3 From 6a694dd839a18cdf0382753fffc17aa1fbd41f9d Mon Sep 17 00:00:00 2001 From: umarcor Date: Mon, 7 Feb 2022 19:28:23 +0100 Subject: doc: use extlinks more --- doc/about.rst | 2 +- doc/conf.py | 4 +-- doc/contribute.rst | 4 +-- doc/quick_start/simulation/adder/index.rst | 4 +-- doc/quick_start/simulation/heartbeat/index.rst | 17 +++++---- doc/quick_start/simulation/hello/index.rst | 48 ++++++++++++++------------ doc/quick_start/simulation/index.rst | 48 ++++++++++++-------------- doc/using/ImplementationOfVHDL.rst | 2 +- pyGHDL/__init__.py | 8 ++--- 9 files changed, 70 insertions(+), 67 deletions(-) diff --git a/doc/about.rst b/doc/about.rst index 388e75d15..413a8348d 100644 --- a/doc/about.rst +++ b/doc/about.rst @@ -99,7 +99,7 @@ Several third party projects are supported: `Yosys `__ (through the `ghdl-yosys-plugin `__) `cocotb `__, -(through the `VPI interface `__), +(through the :wikipedia:`VPI interface `), `VUnit `__, `OSVVM `__, :doc:`vhdlmodel:index`, diff --git a/doc/conf.py b/doc/conf.py index 8b01b32c7..bae26d1ec 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -241,11 +241,11 @@ todo_link_only = True # Sphinx.Ext.ExtLinks # ============================================================================== extlinks = { - 'wikipedia': ('https://en.wikipedia.org/wiki/%s', None), + 'wikipedia': ('https://en.wikipedia.org/wiki/%s', ''), 'ghdlsharp': ('https://github.com/ghdl/ghdl/issues/%s', '#'), 'ghdlissue': ('https://github.com/ghdl/ghdl/issues/%s', 'issue #'), 'ghdlpull': ('https://github.com/ghdl/ghdl/pull/%s', 'pull request #'), - 'ghdlsrc': ('https://github.com/ghdl/ghdl/blob/master/src/%s', None) + 'ghdlsrc': ('https://github.com/ghdl/ghdl/blob/master/src/%s', '') } diff --git a/doc/contribute.rst b/doc/contribute.rst index 8c39b1d37..ec7391635 100644 --- a/doc/contribute.rst +++ b/doc/contribute.rst @@ -52,9 +52,9 @@ Please, report issues through |SHIELD:bug-report|, as this allows us to categori to them. You can track the state and see how it's getting solved. .. IMPORTANT:: - As suggested in the bug report template, please elaborate a `Minimal (non) Working Example` (`MWE `_) + As suggested in the bug report template, please elaborate a `Minimal (non) Working Example` (:wikipedia:`MWE `) prior to sending the report, so that the possible bug source is isolated. Should it fulfill the format requirements of - `issue-runner `_, you would be able to test your bug with the latest GHDL version. + `issue-runner `_, you would be able to test your bug with the latest GHDL version. Please do so in order to ensure that the bug is not solved already. Also, please include enough information in the bug report, for the maintainers to reproduce the problem. The template diff --git a/doc/quick_start/simulation/adder/index.rst b/doc/quick_start/simulation/adder/index.rst index 5ff607801..693d42ef3 100644 --- a/doc/quick_start/simulation/adder/index.rst +++ b/doc/quick_start/simulation/adder/index.rst @@ -5,8 +5,8 @@ ================================= 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`: +synthesisable subset of `VHDL`. It is a :wikipedia:`full adder ` described in a file +named :file:`adder.vhdl`: .. literalinclude:: adder.vhdl :language: vhdl diff --git a/doc/quick_start/simulation/heartbeat/index.rst b/doc/quick_start/simulation/heartbeat/index.rst index e95145095..57e348e89 100644 --- a/doc/quick_start/simulation/heartbeat/index.rst +++ b/doc/quick_start/simulation/heartbeat/index.rst @@ -4,14 +4,16 @@ `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: +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: +It can be :ref:`analysed `, :ref:`elaborated ` and :ref:`run `, as +you already know: .. code-block:: shell @@ -21,7 +23,7 @@ It can be :ref:`analysed `, :ref:`elaborated `_, +context, inspection and verification of the behaviour is done through :wikipedia:`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 @@ -38,5 +40,6 @@ Then, you can view the dump: 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. +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/quick_start/simulation/hello/index.rst b/doc/quick_start/simulation/hello/index.rst index 104a12efa..005706df8 100644 --- a/doc/quick_start/simulation/hello/index.rst +++ b/doc/quick_start/simulation/hello/index.rst @@ -14,23 +14,26 @@ a file named :file:`hello.vhdl`: * 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. + * Since, extension ``.vhd`` is also interpreted as a :wikipedia:`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 :wikipedia:`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: +* 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 @@ -40,14 +43,15 @@ a file named :file:`hello.vhdl`: 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`). + 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. + 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. + :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/quick_start/simulation/index.rst b/doc/quick_start/simulation/index.rst index 8e41a453b..8feab2760 100644 --- a/doc/quick_start/simulation/index.rst +++ b/doc/quick_start/simulation/index.rst @@ -4,43 +4,39 @@ Simulation ########## -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: +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. +* :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). +* 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:`--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. For instance, - if you would like to use VHDL 2008 and also use shared variables with an - ordinary type (deprecated in VHDL 2000), you can use ``--std=08 -frelaxed-rules``. + * Use :option:`-fexplicit` and :option:`-frelaxed-rules` if needed. + For instance, if you would like to use VHDL 2008 and also use shared variables with an ordinary type (deprecated in + VHDL 2000), you can use ``--std=08 -frelaxed-rules``. * 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>`. + 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 +* 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: +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:: diff --git a/doc/using/ImplementationOfVHDL.rst b/doc/using/ImplementationOfVHDL.rst index a623801db..42681dcc9 100644 --- a/doc/using/ImplementationOfVHDL.rst +++ b/doc/using/ImplementationOfVHDL.rst @@ -142,7 +142,7 @@ or use a clocked expression (note the use of parentheses): Of course only the simple subset of PSL is allowed. -Currently the built-in functions are not implemented, see `issue #662 `_. +Currently the built-in functions are not implemented, see :ghdlsharp:`662`. PSL functions `prev()`, `stable()`, `rose()`, `fell()`, `onehot()` and `onehot0()` are supported with GHDL synthesis. PSL usage diff --git a/pyGHDL/__init__.py b/pyGHDL/__init__.py index bd5e1b8d7..8113f5254 100644 --- a/pyGHDL/__init__.py +++ b/pyGHDL/__init__.py @@ -39,12 +39,12 @@ GHDL offers two Python interfaces and a language server protocol service. All this is provided from a ``pyGHDL`` packages with four sub-packages: * ``pyGHDL.cli`` - Command line interface (CLI) applications. -* ``pyGHDL.dom`` - A high-level API offering a document object model (DOM). The underlying abstract VHDL language model is - provided by `pyVHDLModel `__. The DOM is using ``libghdl`` for file analysis and - parsing. +* ``pyGHDL.dom`` - A high-level API offering a document object model (DOM). + The underlying abstract VHDL language model is provided by :doc:`pyVHDLModel `. + The DOM is using ``libghdl`` for file analysis and parsing. * ``pyGHDL.libghdl`` - A low-level API directly interacting with the shared library ``libghdl....so``/``libghdl....dll``. This is a procedural and C-like interface. It comes with some Python generators for easier iterating linked lists. -* ``pyGHDL.lsp`` - A `language server protocol `__ (LSP) +* ``pyGHDL.lsp`` - A :wikipedia:`language server protocol ` (LSP) written in Python. The implementation offers an HTTPS service that can be used e.g. by editors and IDEs supporting LSP. """ __author__ = "Tristan Gingold and contributors" -- cgit v1.2.3 From 77a5930bf7998382e2ce3d3f3f88a2e8d29e95ff Mon Sep 17 00:00:00 2001 From: Unai Martinez-Corral <38422348+umarcor@users.noreply.github.com> Date: Tue, 8 Feb 2022 02:47:12 +0000 Subject: doc/about: 's/programming language/computer language/' Co-authored-by: Patrick Lehmann --- doc/about.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/about.rst b/doc/about.rst index 413a8348d..6798aacfe 100644 --- a/doc/about.rst +++ b/doc/about.rst @@ -13,7 +13,7 @@ What is `VHDL`? =============== :wikipedia:`VHDL ` is an acronym for *Verification and Hardware Description Language* (:wikipedia:`HDL `), -which is a programming language used to describe a logic circuit by function, data flow behavior, or structure. +which is a computer language used to describe a logic circuit by function, data flow behavior, or structure. .. NOTE:: Historically the 'V' in the language's acronym came from the Very High Speed Integrated Circuit (:wikipedia:`VHSIC `), -- cgit v1.2.3 From 990a22f51ca38e54a3c8a1d614f4be38c6c21a5c Mon Sep 17 00:00:00 2001 From: Unai Martinez-Corral <38422348+umarcor@users.noreply.github.com> Date: Tue, 8 Feb 2022 02:47:35 +0000 Subject: doc/about: update Co-authored-by: Patrick Lehmann --- doc/about.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/about.rst b/doc/about.rst index 6798aacfe..17eeabc7e 100644 --- a/doc/about.rst +++ b/doc/about.rst @@ -18,7 +18,7 @@ which is a computer language used to describe a logic circuit by function, data .. NOTE:: Historically the 'V' in the language's acronym came from the Very High Speed Integrated Circuit (:wikipedia:`VHSIC `), which was the U.S. government program that funded the early work on the standard. - Changing the 'V' to mean verification reflects the language's increasing usage for verification as well as design. + Changing the 'V' to mean *verification* reflects the language's increasing usage for verification as well as design. See `VHDL 202X PAR `__ via :ref:`vasg:VHDL202X`. Although VHDL was not designed for writing general purpose programs, VHDL *is* a programming language: you can write any -- cgit v1.2.3 From 91b9bca47d3a5a8b68793c0c378ba6035c967fb8 Mon Sep 17 00:00:00 2001 From: Unai Martinez-Corral <38422348+umarcor@users.noreply.github.com> Date: Tue, 8 Feb 2022 02:48:43 +0000 Subject: doc/about: 's/event-based timing/event-driven execution/' Co-authored-by: Patrick Lehmann --- doc/about.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/about.rst b/doc/about.rst index 17eeabc7e..0ab41a26a 100644 --- a/doc/about.rst +++ b/doc/about.rst @@ -33,7 +33,7 @@ an advantage in general as well). However, VHDL was not designed as a general purpose language but as an `HDL`. As the name implies, VHDL aims at modeling or documenting electronics systems. Due to the nature of hardware components --which are always running--, VHDL is a highly concurrent language, built upon an -event-based timing model. +event-driven execution model. Like a program written in any other language, a VHDL program can be executed. Since VHDL is used to model designs, the term :dfn:`simulation` is often used instead of `execution`, with the same -- cgit v1.2.3 From 4e0922f742d74f950c1d542e086187e564f22111 Mon Sep 17 00:00:00 2001 From: umarcor Date: Tue, 8 Feb 2022 05:18:40 +0100 Subject: doc: update overview diagram --- doc/_static/internals.png | Bin 141392 -> 159818 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/doc/_static/internals.png b/doc/_static/internals.png index 01399b5d9..498a70fe0 100644 Binary files a/doc/_static/internals.png and b/doc/_static/internals.png differ -- cgit v1.2.3 From 9139188bd5ce877467e54b805f2bbf3f877b5d15 Mon Sep 17 00:00:00 2001 From: umarcor Date: Tue, 8 Feb 2022 05:24:51 +0100 Subject: doc/about: change 'you' to formal english --- doc/about.rst | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/doc/about.rst b/doc/about.rst index 0ab41a26a..088f98b3a 100644 --- a/doc/about.rst +++ b/doc/about.rst @@ -21,9 +21,9 @@ which is a computer language used to describe a logic circuit by function, data Changing the 'V' to mean *verification* reflects the language's increasing usage for verification as well as design. See `VHDL 202X PAR `__ via :ref:`vasg:VHDL202X`. -Although VHDL was not designed for writing general purpose programs, VHDL *is* a programming language: you can write any -algorithm with it, you can interact with files, with the environment, etc. -If you are able to write programs, you will find in VHDL features similar to those found in procedural languages such as +Although VHDL was not designed for writing general purpose programs, VHDL *is* a programming language: any algorithm can +be written with it, it can interact with files, the environment, stdin and stdout, etc. +VHDL has features similar to those found in procedural languages such as :wikipedia:`C `, :wikipedia:`Python `, or :wikipedia:`Ada `. @@ -32,8 +32,8 @@ an advantage in general as well). However, VHDL was not designed as a general purpose language but as an `HDL`. As the name implies, VHDL aims at modeling or documenting electronics systems. -Due to the nature of hardware components --which are always running--, VHDL is a highly concurrent language, built upon an -event-driven execution model. +Due to the nature of hardware components --which are always running--, VHDL is a highly concurrent language, built upon +an event-driven execution model. Like a program written in any other language, a VHDL program can be executed. Since VHDL is used to model designs, the term :dfn:`simulation` is often used instead of `execution`, with the same @@ -67,7 +67,7 @@ What is GHDL? It is a VHDL analyzer, compiler, simulator and (experimental) synthesizer that can process (nearly) any VHDL design. .. NOTE:: - For almost 20 years, GHDL was *not* a synthesis tool: you could not create a netlist. + For almost 20 years, GHDL was *not* a synthesis tool: a netlist could not be created. Hence, most of the content in this documentation corresponds to the usage of GHDL as a compiler/simulator. See :ref:`USING:Synthesis` for further details regarding synthesis. @@ -81,11 +81,10 @@ GHDL can use multiple back-ends, i.e. code generators, (`GCC `, :wikipedia:`Windows ` |trade| and :wikipedia:`macOS ` |trade|; on x86, x86_64, armv6/armv7/aarch32/aarch64, ppc64, etc. -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, :ref:`GHW`, :wikipedia:`VCD ` or `FST` files can be produced, 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: signal waves cannot be seen through GHDL. +However, the behavior of the designs can still be checked through test benches and verification frameworks. +Moreover, :ref:`GHW`, :wikipedia:`VCD ` or `FST` files can be produced, which can be viewed with an +external :wikipedia:`waveform viewer `, such as `GtkWave `__. GHDL aims at implementing VHDL as defined by `IEEE 1076 `__. It supports the -- cgit v1.2.3 From a8913e8fa4ee1c92ee008a77487a614014c45fb6 Mon Sep 17 00:00:00 2001 From: umarcor Date: Wed, 23 Feb 2022 22:09:19 +0100 Subject: doc: update diagram 'internals' --- doc/_static/internals.png | Bin 159818 -> 143025 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/doc/_static/internals.png b/doc/_static/internals.png index 498a70fe0..4baed711b 100644 Binary files a/doc/_static/internals.png and b/doc/_static/internals.png differ -- cgit v1.2.3