Clean up analysis and import/export documentation:

* Fix some type annotations
* Fix some formatting
* Add more links

Author: fdxmw

pyrtl/analysis.py

@@ -331,31 +331,31 @@ def print_critical_paths(critical_paths):
 #      |  \__/ .__/  |  .__/
 #
 
-def yosys_area_delay(library, abc_cmd=None, leave_in_dir=None, block=None):
-    """Synthesize with `Yosys <https://yosyshq.net/yosys/>`_ and return
-    estimate of area and delay.
+def yosys_area_delay(library: str, abc_cmd: str = None, leave_in_dir: str = None,
+                     block: Block = None) -> tuple[float, float]:
+    """Synthesize with `Yosys <https://yosyshq.net/yosys/>`_ and return estimate of area
+    and delay.
 
-    :param library: stdcell library file to target in liberty format
-    :param abc_cmd: string of commands for :program:`yosys` to pass to
-        :program:`abc` for synthesis
-    :param dir: the directory where temporary files should be left
-    :param block: PyRTL block to analyze
-    :return: a tuple of numbers: area, delay
-
-    If `dir` is specified, that directory will be used to create any temporary
-    files, and the resulting files will be left behind there (which can be
+    If ``leave_in_dir`` is specified, that directory will be used to create any
+    temporary files, and the resulting files will be left behind there (which can be
     useful for manual exploration or debugging)
 
-    The area and delay are returned in units as defined by the stdcell
-    library.  In the standard vsc 130nm library, the area is in a number of
-    "tracks", each of which is about 1.74 square um (see area estimation
-    for more details) and the delay is in ps.
+    The area and delay are returned in units as defined by the stdcell library. In the
+    standard vsc 130nm library, the area is in a number of "tracks", each of which is
+    about 1.74 square um (see area estimation for more details) and the delay is in ps.
 
     http://www.vlsitechnology.org/html/vsc_description.html
 
-    May raise :class:`PyrtlError` if :program:`yosys` is not configured correctly, and
-    :class:`PyrtlInternalError` if the call to :program:`yosys` was not successful
+    :param library: stdcell library file to target in liberty format
+    :param abc_cmd: string of commands for :program:`yosys` to pass to :program:`abc`
+        for synthesis
+    :param leave_in_dir: the directory where temporary files should be left
+    :param block: PyRTL block to analyze. Defaults to the :ref:`working_block`.
+
+    :raise PyrtlError: If :program:`yosys` is not configured correctly.
+    :raise PyrtlInternalError: If the call to :program:`yosys` was not successful
 
+    :return: a tuple of numbers: area, delay
     """
 
     if abc_cmd is None:
@@ -546,19 +546,19 @@ def dfs(w, curr_path):
     return PathsResult(all_paths)
 
 
-def distance(src: WireVector, dst: WireVector, f: Callable[[LogicNet], int],
-             block: Block = None) -> dict[list[LogicNet], int]:
-    """ Calculate the 'distance' along each path from `src` to `dst` according to `f`
+def distance(src: WireVector, dst: WireVector, f: Callable[list[LogicNet], int],
+             block: Block = None) -> dict[tuple[LogicNet], int]:
+    """Calculate the distance along each path from ``src`` to ``dst`` according to ``f``
+
+    This calls the given function ``f`` on each net in a path, summing the result.
 
     :param src: wire to start from
     :param dst: wire to end on
-    :param f: function from a net to number,
-        representing the 'value' of a net that you want to sum
-        across all nets in the path
+    :param f: function from a net to number, representing the 'value' of a net that you
+              want to sum across all nets in the path
     :param block: block to use (defaults to :ref:`working_block`)
-    :return: a map from each path (a tuple) to its calculated distance
 
-    This calls the given function `f` on each net in a path, summing the result.
+    :return: a map from each path (a tuple) to its calculated distance
     """
     ps = paths(src, dst, block=block)
     ps = ps[src][dst]

pyrtl/importexport.py

@@ -16,7 +16,7 @@
 import sys
 import functools
 import operator
-import typing
+from typing import Union, TYPE_CHECKING
 
 from pyrtl.pyrtlexceptions import PyrtlError, PyrtlInternalError
 from pyrtl.core import working_block, _NameSanitizer, Block
@@ -25,6 +25,9 @@
 from pyrtl.memory import RomBlock
 from pyrtl.passes import two_way_concat, one_bit_selects
 
+if TYPE_CHECKING:
+    from pyrtl.simulation import SimulationTrace
+
 
 def _natural_sort_key(key):
     """ Convert the key into a form such that it will be sorted naturally,
@@ -103,31 +106,33 @@ def input_from_blif(
         clock_name: str = 'clk', top_model: str = None):
     """Read an open BLIF file or string as input, updating the block appropriately.
 
+    If ``merge_io_vectors`` is ``True``, then given 1-bit :class:`Input` wires ``a[0]``
+    and ``a[1]``, these wires will be combined into a single 2-bit :class:`Input` wire
+    ``a`` that can be accessed by name ``a`` in the block. Otherwise if
+    ``merge_io_vectors`` is ``False``, the original 1-bit wires will be :class:`Input`
+    wires of the block. This holds similarly for :class:`Output`.
+
+    ``input_from_blif`` assumes the following:
+
+    - There is only one single shared clock and reset
+
+    - Output is generated by Yosys with formals in a particular order
+
+    ``input_from_blif`` currently supports multi-module (unflattened) BLIF, though we
+    recommend importing a flattened BLIF with a single module when possible. It
+    currently ignores the reset signal (which it assumes is input only to the flip
+    flops).
+
     :param blif: An open BLIF file to read.
     :param block: The block where the logic will be added. Defaults to the
         :ref:`working_block`.
-    :param merge_io_vectors: If True, :class:`Input`/:class:`Output` wires whose
+    :param merge_io_vectors: If ``True``, :class:`Input`/:class:`Output` wires whose
         names differ only by a indexing subscript (e.g. 1-bit wires ``a[0]`` and
-        ``a[1]``) will be combined into a single :class:`Input`/:class:`Output`
-        (e.g. a 2-bit wire ``a``).
-    :param clock_name: The name of the clock (defaults to ``clk``). :param top_model:
-        name of top-level model to instantiate; if None, defaults to first model listed
-        in the BLIF.
-
-    If ``merge_io_vectors`` is ``True``, then given 1-bit :class:`Input` wires
-    ``a[0]`` and ``a[1]``, these wires will be combined into a single 2-bit
-    :class:`Input` wire ``a`` that can be accessed by name ``a`` in the block.
-    Otherwise if ``merge_io_vectors`` is ``False``, the original 1-bit wires will be
-    :class:`Input` wires of the block. This holds similarly for :class:`Output`.
-
-    This assumes the following:
-      * There is only one single shared clock and reset
-      * Output is generated by Yosys with formals in a particular order
-
-    It currently supports multi-module (unflattened) BLIF, though we recommend importing
-    a flattened BLIF with a single module when possible. It currently ignores the reset
-    signal (which it assumes is input only to the flip flops).
-
+        ``a[1]``) will be combined into a single :class:`Input`/:class:`Output` (e.g. a
+        2-bit wire ``a``).
+    :param clock_name: The name of the clock (defaults to ``clk``).
+    :param top_model: name of top-level model to instantiate; if ``None``, defaults to
+        first model listed in the BLIF.
     """
     import pyparsing
     from pyparsing import (Word, Literal, OneOrMore, ZeroOrMore,
@@ -536,23 +541,23 @@ def input_from_verilog(
     """Read an open Verilog file or string as input via `Yosys
     <https://github.com/YosysHQ/yosys>`_ conversion, updating the block.
 
-    :param verilog: An open Verilog file to read.
-    :param clock_name: The name of the clock (defaults to 'clk').
-    :param toplevel: Name of top-level module to instantiate; if None, defaults to first
-        model defined in the Verilog file.
-    :param leave_in_dir: If True, save the intermediate BLIF file created in the given
-        directory.
-    :param block: The block where the logic will be added. Defaults to the
-        :ref:`working_block`.
+    This function is essentially a wrapper for :func:`input_from_blif`, with the added
+    convenience of turning the Verilog into BLIF for import for you. This function
+    passes a set of commands to Yosys as a script that normally produces BLIF files that
+    can be successfully imported into PyRTL via :func:`input_from_blif`.
 
-    Note: This function is essentially a wrapper for :func:`input_from_blif`, with
-    the added convenience of turning the Verilog into BLIF for import for you. This
-    function passes a set of commands to Yosys as a script that normally produces BLIF
-    files that can be successuflly imported into PyRTL via :func:`input_from_blif`. If the
-    Yosys conversion fails here, we recommend you create your own custom Yosys script to
-    try and produce BLIF yourself. Then you can import BLIF directly via
+    If the Yosys conversion fails, we recommend you create your own custom Yosys script
+    to try and produce BLIF yourself. Then you can import BLIF directly via
     :func:`input_from_blif`.
 
+    :param verilog: An open Verilog file to read.
+    :param clock_name: The name of the clock (defaults to ``"clk"``).
+    :param toplevel: Name of top-level module to instantiate; if ``None``, defaults to
+        first model defined in the Verilog file.
+    :param leave_in_dir: If ``True``, save the intermediate BLIF file created in the
+        given directory.
+    :param block: The block where the logic will be added. Defaults to the
+        :ref:`working_block`.
     """
 
     # Dev Notes:
@@ -619,9 +624,16 @@ def input_from_verilog(
             os.remove(tmp_blif_path)
 
 
-def output_to_verilog(dest_file, add_reset: typing.Union[bool, str] = True,
+def output_to_verilog(dest_file, add_reset: Union[bool, str] = True,
                       block: Block = None, initialize_registers: bool = False):
-    """A function to walk the block and output it in Verilog format to the open file.
+    """A function to walk the ``block`` and output it in Verilog format to the open
+    file.
+
+    The Verilog module will be named ``toplevel``, with a clock input named ``clk``.
+
+    When possible, wires keep their names in the Verilog output. Wire names that do not
+    satisfy Verilog's naming requirements, and wires that conflict with Verilog keywords
+    are given new temporary names in the Verilog output.
 
     :param dest_file: Open file where the Verilog output will be written.
     :param add_reset: If reset logic should be added. Allowable options are: ``False``
@@ -633,13 +645,6 @@ def output_to_verilog(dest_file, add_reset: typing.Union[bool, str] = True,
         When this argument is ``True``, a register like ``Register(name='foo',
         bitwidth=8, reset_value=4)`` generates Verilog like ``reg[7:0] foo = 8'd4;``.
     :param block: Block to be walked and exported. Defaults to the :ref:`working_block`.
-
-    The Verilog module will be named ``toplevel``, with a clock input named ``clk``.
-
-    When possible, wires keep their names in the Verilog output. Wire names that do not
-    satisfy Verilog's naming requirements, and wires that conflict with Verilog keywords
-    are given new temporary names in the Verilog output.
-
     """
 
     if not isinstance(add_reset, bool):
@@ -906,39 +911,12 @@ def _to_verilog_footer(file):
 
 
 def output_verilog_testbench(
-        dest_file, simulation_trace=None, toplevel_include: str = None,
-        vcd: str = "waveform.vcd", cmd: str = None,
-        add_reset: typing.Union[bool, str] = True, block: Block = None):
-    """Output a Verilog testbench for the block/inputs used in the simulation
-    trace.
-
-    :param dest_file: an open file to which the test bench will be printed.
-    :param SimulationTrace simulation_trace: a simulation trace from which the inputs
-        will be extracted for inclusion in the test bench. The test bench generated will
-        just replay the inputs played to the simulation cycle by cycle. The default
-        values for all registers and memories will be based on the trace, otherwise they
-        will be initialized to 0.
-    :param toplevel_include: name of the file containing the toplevel module this
-        testbench is testing. If not ``None``, an `include` directive will be added to
-        the top.
-    :param vcd: By default the testbench generator will include a command in the
-        testbench to write the output of the testbench execution to a ``.vcd`` file (via
-        `$dumpfile`), and this parameter is the name of the file to write. If ``None``
-        is specified, then no `dumpfile` will be used.
-    :param cmd: The string passed as ``cmd`` will be copied verbatim into the testbench
-        just before the end of each cycle. This is useful for doing things like printing
-        specific values during testbench evaluation. For example, ``cmd='$display("%d",
-        out);'`` will instruct the testbench to print the value of `out` every cycle,
-        which can be compared with a reference.
-    :param add_reset: If reset logic should be added. Allowable options are: ``False``
-        (meaning no reset logic is added), ``True`` (default, for adding synchronous
-        reset logic), and ``'asynchronous'`` (for adding asynchronous reset logic). The
-        value passed in here should match the argument passed to
-        :func:`output_to_verilog`.
+        dest_file, simulation_trace: SimulationTrace = None,
+        toplevel_include: str = None, vcd: str = "waveform.vcd", cmd: str = None,
+        add_reset: Union[bool, str] = True, block: Block = None):
+    """Output a Verilog testbench for the block/inputs used in the simulation trace.
 
-    :param block: Block containing design to test. Defaults to the :ref:`working_block`.
-
-    If ``add_reset`` is not False, a ``rst`` input wire is added to the instantiated
+    If ``add_reset`` is ``True``, a ``rst`` input wire is added to the instantiated
     ``toplevel`` module. The ``rst`` wire will be held low in the testbench, because
     initialization here occurs via the ``initial`` block. ``add_reset`` is provided for
     consistency with :func:`output_to_verilog`.
@@ -949,17 +927,44 @@ def output_verilog_testbench(
 
     The test bench does not return any values.
 
-    Example 1 (writing testbench to a string)::
+    Example 1, writing testbench to a string::
 
         with io.StringIO() as tbfile:
             pyrtl.output_verilog_testbench(dest_file=tbfile, simulation_trace=sim_trace)
 
-    Example 2 (testbench in same file as verilog)::
+    Example 2, testbench in same file as Verilog::
 
         with open('hardware.v', 'w') as fp:
             output_to_verilog(fp)
             output_verilog_testbench(fp, sim.tracer, vcd=None, cmd='$display("%d", out);')
 
+    :param dest_file: An open file to which the test bench will be printed.
+    :param simulation_trace: A trace from which the inputs will be extracted for
+        inclusion in the test bench. This is typically :attr:`Simulation.tracer`. The
+        generated test bench will replay the :class:`Simulation`'s
+        :class:`Inputs<Input>` cycle by cycle. The default values for all registers and
+        memories will be based on the trace, otherwise they will be initialized to 0.
+    :param toplevel_include: Name of the file containing the ``toplevel`` module this
+        testbench is testing. If not ``None``, an ``include`` directive will be added
+        for this file.
+    :param vcd: By default, the testbench generator will generate a command to write the
+        output of the testbench execution to a ``.vcd`` file, via ``$dumpfile``, and
+        ``vcd`` is the name of the file to write. If ``None``, then no ``dumpfile`` will
+        be used.
+    :param cmd: The string passed as ``cmd`` will be copied verbatim into the testbench
+        just before the end of each cycle. This is useful for doing things like printing
+        specific values during testbench evaluation. For example::
+
+            cmd='$display("%d", out);'
+
+        will instruct the testbench to print the value of ``out`` every cycle.
+
+    :param add_reset: If reset logic should be added. Allowable options are: ``False``
+        (meaning no reset logic is added), ``True`` (default, for adding synchronous
+        reset logic), and ``'asynchronous'`` (for adding asynchronous reset logic). The
+        value passed in here should match the argument passed to
+        :func:`output_to_verilog`.
+    :param block: Block containing design to test. Defaults to the :ref:`working_block`.
     """
     if not isinstance(add_reset, bool):
         if add_reset != 'asynchronous':
@@ -1103,13 +1108,12 @@ def default_value():
 def output_to_firrtl(open_file, rom_blocks: list[RomBlock] = None, block: Block = None):
     """Output the block as FIRRTL code to the output file.
 
-    :param open_file: File to write to.
-    :param rom_blocks: List of ROM blocks to be initialized.
-    :param block: Block to use (defaults to :ref:`working_block`).
-
-    If ROM is initialized in PyRTL code, you can pass in the ``rom_blocks`` as a
+    If ROM is initialized in PyRTL code, you can pass in the :class:`RomBlocks` as a
     list ``[rom1, rom2, ...]``.
 
+    :param open_file: File to write to.
+    :param rom_blocks: List of :class:`RomBlocks<RomBlock>` to be initialized.
+    :param block: Block to use (defaults to :ref:`working_block`).
     """
     block = working_block(block)