Add configuration page and documentation on VHDL/GHDL support

Signed-off-by: Michael Riegert <michael@eowyn.net>

Author: nobodywasishere

README.rst

@@ -30,7 +30,7 @@ sphinxcontrib-hdl-diagrams
 ----
 
 Sphinx Extension which generates various types of diagrams from HDL code, supporting Verilog,
-nMigen and RTLIL.
+nMigen, RTLIL, and VHDL.
 
 `sphinxcontrib-hdl-diagrams <https://github.com/SymbiFlow/sphinxcontrib-hdl-diagrams>`_
 is a Sphinx extension to make it easier to write nice documentation from
@@ -84,19 +84,19 @@ Required
 .. |yosys| replace:: ``yosys``
 .. _yosys: https://github.com/YosysHQ/yosys
 
-By default, ``verilog-diagram`` uses the ``yowasp-yosys`` package provided in PyPI.
+By default, ``hdl-diagram`` uses the ``yowasp-yosys`` package provided in PyPI.
 It can be installed by running ``pip install -r requirements.txt``.
 However, you could also use Yosys that is installed on your system,
-or point to the specific Yosys binary using ``verilog_diagram_yosys`` variable
+or point to the specific Yosys binary using ``hdl_diagram_yosys`` variable
 in the Sphinx ``conf.py`` file:
 
 To use Yosys that is available in your system, use the following setting::
 
-    verilog_diagram_yosys = "system"
+    hdl_diagram_yosys = "system"
 
 If you want to point to the specific Yosys binary, provide the path to the program::
 
-    verilog_diagram_yosys = "<path-to-Yosys>"
+    hdl_diagram_yosys = "<path-to-Yosys>"
 
 Optional
 ~~~~~~~~
@@ -106,6 +106,27 @@ Optional
 .. |netlistsvg| replace:: ``netlistsvg``
 .. _netlistsvg: https://github.com/nturley/netlistsvg
 
+* |ghdl|_
+
+.. |ghdl| replace:: ``ghdl``
+.. _ghdl: https://github.com/ghdl/ghdl
+
+GHDL and ghdl-yosys-plugin are required for VHDL support. If ghdl-yosys-plugin is built into Yosys,
+add this configuration option to let Yosys know::
+
+    hdl_diagram_ghdl = "built-in"
+
+Otherwise, to load GHDL as a runtime module, set this configuration option to::
+
+    hdl_diagram_ghdl = "module"
+
+Which will pass ``-m ghdl`` to Yosys when calling it. Similarly, setting this to the path of a
+ghdl-yosys-plugin shared library will also work.
+
+Unfortunately, at this time GHDL and ghdl-yosys-plugin aren't supported by YoWASP. However, we'd
+love to have it available. Are you aware of some proof-of-concept linking WASM compiled from both
+C++ and Ada? Do you want to give it a try? Let us know!
+
 Usage
 -----
 

docs/code/vhdl/alu.vhdl

@@ -0,0 +1,40 @@
+--
+-- Copyright (C) 2020  The SymbiFlow Authors.
+--
+-- Licensed under the Apache License, Version 2.0 (the "License");
+-- you may not use this file except in compliance with the License.
+-- You may obtain a copy of the License at
+--
+--     https://www.apache.org/licenses/LICENSE-2.0
+--
+-- Unless required by applicable law or agreed to in writing, software
+-- distributed under the License is distributed on an "AS IS" BASIS,
+-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+-- See the License for the specific language governing permissions and
+-- limitations under the License.
+--
+-- SPDX-License-Identifier: Apache-2.0
+
+library IEEE;
+use IEEE.std_logic_1164.all;
+use IEEE.numeric_std.all;
+
+entity alu is
+    port(
+        a : in unsigned(3 downto 0);
+        b : in unsigned(3 downto 0);
+        s : in unsigned(1 downto 0);
+        y : out unsigned(3 downto 0)
+    );
+end alu;
+
+architecture rtl of alu is
+
+begin
+
+    y <= a when s="00" else
+        b when s="01" else
+        "0000" when s="10" else
+        a + b when s="11" else (others => '0');
+
+end;

docs/configuration/index.rst

@@ -0,0 +1,82 @@
+Configuration
+=============
+
+This is the list of possible configurations that go in ``conf.py``.
+
+Yosys
++++++
+
+``hdl_diagram_yosys`` tells the program what version or binary of Yosys to use.
+By default it is set to ``YoWASP``. Setting it to ``system``, the program will
+use Yosys available in the current PATH. It can also contain the path to a specific
+Yosys binary.::
+
+    hdl_diagram_yosys = "yowasp" # default
+
+    hdl_diagram_yosys = "system" # use yosys from PATH
+
+    hdl_diagram_yosys = "<path-to-Yosys>" # use specific yosys binary
+
+
+netlistsvg
+++++++++++
+
+netlistsvg can take various skin files for use when creating diagrams. It is
+set to ``default`` by default, using the built-in netlistsvg skin.::
+
+    hdl_diagram_skin = "<path-to-skin>"
+
+
+Output format
++++++++++++++
+
+The output format for the generated diagrams can either be set to ``svg`` or ``png``.::
+
+    hdl_diagram_output_format = "svg"
+
+    hdl_diagram_output_format = "png"
+
+
+GHDL
+++++
+
+ghdl-yosys-plugin can either be built into Yosys or loaded at runtime. If it is built into Yosys,
+then set this configuration option to ``built-in``. If it is loaded at runtime, then this can
+either be set to ``module`` if the shared library is located at ``YOSYS_PREFIX/share/yosys/plugins/
+ghdl.so``, or as a path to the ``ghdl.so`` shared library. ::
+
+    hdl_diagram_ghdl = "built-in" # default, if ghdl-yosys-plugin is built into Yosys
+
+    hdl_diagram_ghdl = "module" # passes `-m ghdl` to Yosys
+
+    hdl_diagram_ghdl = "<path-to-GHDL-shared-library>" # path to specific ghdl.so,
+                                                       # passes `-m '<path>'` to Yosys
+
+The VHDL standard used for GHDL can be set globally using this configuration option.::
+
+    hdl_diagram_ghdl_std = "08" # default, for VHDL 2008
+
+    hdl_diagram_ghdl_std = "97" # for VHDL 1993
+
+Common Errors
++++++++++++++
+
+.. code-block::
+
+    ERROR:
+      This version of Yosys cannot load plugins at runtime.
+      Some plugins may have been included at build time.
+      Use option `-H' to see the available built-in and plugin commands.
+
+This error signifies that the current version of Yosys cannot load plugins
+at runtime, and so all plugins must be prebuit. For VHDL, ``hdl_diagram_ghdl``
+must be set to ``built-in``.
+
+.. code-block::
+
+    ERROR: Can't guess frontend for input file `' (missing -f option)!
+
+This error signifies that the version of Yosys being used cannot figure out
+how to interpret the input file. For VHDL, this signifies that either GHDL
+isn't being loaded properly, or that the current version of Yosys isn't compatible
+with GHDL.

docs/examples/alu-vhdl.rst

@@ -0,0 +1,89 @@
+4 bit ALU in VHDL
+=================
+
+VHDL Code
++++++++++
+
+RST Directive
+*************
+
+.. code-block:: rst
+   :linenos:
+
+   .. no-license:: ../code/vhdl/alu.vhdl
+      :language: vhdl
+      :linenos:
+
+
+Result
+******
+
+.. no-license:: ../code/vhdl/alu.vhdl
+   :language: vhdl
+   :linenos:
+
+Yosys BlackBox Diagram
+++++++++++++++++++++++
+
+RST Directive
+*************
+
+.. code-block:: rst
+   :linenos:
+   :emphasize-lines: 2
+
+   .. hdl-diagram:: ../code/vhdl/alu.vhdl
+      :type: yosys-bb
+      :module: alu
+
+Result
+******
+
+.. hdl-diagram:: ../code/vhdl/alu.vhdl
+   :type: yosys-bb
+   :module: alu
+
+
+Yosys AIG Diagram
++++++++++++++++++
+
+RST Directive
+*************
+
+.. code-block:: rst
+   :linenos:
+   :emphasize-lines: 2
+
+   .. hdl-diagram:: ../code/vhdl/alu.vhdl
+      :type: yosys-aig
+      :module: alu
+
+Result
+******
+
+.. hdl-diagram:: ../code/vhdl/alu.vhdl
+   :type: yosys-aig
+   :module: alu
+
+
+NetlistSVG Diagram
+++++++++++++++++++
+
+RST Directive
+*************
+
+.. code-block:: rst
+   :linenos:
+   :emphasize-lines: 2
+
+   .. hdl-diagram:: ../code/vhdl/alu.vhdl
+      :type: netlistsvg
+      :module: alu
+
+
+Result
+******
+
+.. hdl-diagram:: ../code/vhdl/alu.vhdl
+   :type: netlistsvg
+   :module: alu

docs/examples/index.rst

@@ -4,6 +4,7 @@ Examples
 .. toctree::
    :maxdepth: 1
    :glob:
-   
+
    comb-full-adder
-   carry4
+   carry4
+   alu-vhdl

docs/index.rst

@@ -3,14 +3,14 @@ Sphinx HDL Diagrams
 
 sphinx-hdl-diagrams is an extension to Sphinx to make it easier to write
 nice documentation from HDL source files, in the form of Verilog, nMigen,
-or RTLIL code.
+RTLIL, or VHDL code.
 
 You use the |hdl-diagram|_ RST directive to generate various styles of
 diagrams from HDL code.
 
-Most of the time there will be a license header at the top of source code, 
-which we might not want to show in the documentation. 
-This extension also provides the |no-license|_ RST directive which works exactly 
+Most of the time there will be a license header at the top of source code,
+which we might not want to show in the documentation.
+This extension also provides the |no-license|_ RST directive which works exactly
 like the `.. literalinclude` directive, but the `lines` option is overridden
 to only show the lines after the license header.
 
@@ -56,6 +56,8 @@ conda `environment.yml <https://github.com/SymbiFlow/sphinxcontrib-hdl-diagrams/
 
 - `yosys <https://github.com/YosysHQ/yosys>`_ (required)
 - `netlistsvg <https://github.com/nturley/netlistsvg>`_ (optional)
+- `GHDL <https://github.com/ghdl/ghdl>`_ (required for VHDL)
+- `ghdl-yosys-plugin <https://github.com/ghdl/ghdl-yosys-plugin>`_ (required for VHDL)
 
 Usage
 -----
@@ -106,6 +108,7 @@ So, refer to `literalinclude` for the available options.
    :maxdepth: 1
    :glob:
    :hidden:
-   
+
+   configuration/index
    directives/index
    examples/index