Merge pull request #337 from pllab/typos-and-docs

Add documentation to inputoutput functions.

Author: mdko

docs/export.rst

@@ -22,13 +22,15 @@ Importing Verilog
 .. autofunction:: pyrtl.inputoutput.input_from_blif
 
 
-Outputing for Visualization
+Outputting for Visualization
 ---------------------------
 
 .. autofunction:: pyrtl.inputoutput.output_to_trivialgraph
 .. autofunction:: pyrtl.inputoutput.output_to_graphviz
+.. autofunction:: pyrtl.inputoutput.graphviz_detailed_namer
 .. autofunction:: pyrtl.inputoutput.output_to_svg
 .. autofunction:: pyrtl.inputoutput.block_to_graphviz_string
 .. autofunction:: pyrtl.inputoutput.block_to_svg
 .. autofunction:: pyrtl.inputoutput.trace_to_html
+.. autofunction:: pyrtl.inputoutput.net_graph
 

pyrtl/__init__.py

@@ -85,12 +85,14 @@
 # input and output to file format routines
 from .inputoutput import input_from_blif
 from .inputoutput import output_to_trivialgraph
+from .inputoutput import graphviz_detailed_namer
 from .inputoutput import output_to_graphviz
 from .inputoutput import output_to_svg
 from .inputoutput import output_to_firrtl
 from .inputoutput import block_to_graphviz_string
 from .inputoutput import block_to_svg
 from .inputoutput import trace_to_html
+from .inputoutput import net_graph
 
 # extraction to verilog and verilog testbench
 from .verilog import output_to_verilog

pyrtl/helperfuncs.py

@@ -138,16 +138,16 @@ def log2(integer_val):
 
 
 def truncate(wirevector_or_integer, bitwidth):
-    """ Returns a wirevector or integer truncated to the specified bitwidth
+    """ Returns a WireVector or integer truncated to the specified bitwidth
 
-    :param wirevector_or_integer: Either a wirevector or an integer to be truncated
+    :param wirevector_or_integer: Either a WireVector or an integer to be truncated.
     :param bitwidth: The length to which the first argument should be truncated.
-    :return: Returns a tuncated wirevector or integer as appropriate
+    :return: A truncated WireVector or integer as appropriate.
 
     This function truncates the most significant bits of the input, leaving a result
     that is only "bitwidth" bits wide.  For integers this is performed with a simple
-    bitmask of size "bitwidth".  For wirevectors the function calls WireVector.truncate
-    and returns a wirevector of the specified bitwidth.
+    bitmask of size "bitwidth".  For WireVectors the function calls 'WireVector.truncate'
+    and returns a WireVector of the specified bitwidth.
 
     Examples: ::
 
@@ -177,26 +177,26 @@ def __exit__(self, *execinfo):
 
 
 def match_bitpattern(w, bitpattern, field_map=None):
-    """ Returns a single-bit wirevector that is 1 if and only if 'w' matches the bitpattern,
+    """ Returns a single-bit WireVector that is 1 if and only if 'w' matches the bitpattern,
     and a tuple containining the matched fields, if any. Compatible with the 'with' statement.
 
-    :param w: The wirevector to be compared to the bitpattern
+    :param w: The WireVector to be compared to the bitpattern
     :param bitpattern: A string holding the pattern (of bits and wildcards) to match
     :param field_map: (optional) A map from single-character field name in the bitpattern
         to the desired name of field in the returned namedtuple. If given, all non-"1"/"0"/"?"
         characters in the bitpattern must be present in the map.
-    :return: A tuple of 1-bit wirevector carrying the result of the comparison, followed
+    :return: A tuple of 1-bit WireVector carrying the result of the comparison, followed
         by a named tuple containing the matched fields, if any.
 
-    This function will compare a multi-bit wirevector to a specified pattern of bits, where some
+    This function will compare a multi-bit WireVector to a specified pattern of bits, where some
     of the pattern can be "wildcard" bits.  If any of the "1" or "0" values specified in the
-    bitpattern fail to match the wirevector during execution, a "0" will be produced, otherwise
+    bitpattern fail to match the WireVector during execution, a "0" will be produced, otherwise
     the value carried on the wire will be "1".  The wildcard characters can be any other
     alphanumeric character, with characters other than "?" having special functionality (see below).
     The string must have length equal to the wirevector specified, although whitespace and
     underscore characters will be ignored and can be used for pattern readability.
 
-    For all other characters besides "1", "0", or "?", a tuple of wirevectors will be returned as
+    For all other characters besides "1", "0", or "?", a tuple of WireVectors will be returned as
     the second return value. Each character will be treated as the name of a field,
     and non-consecutive fields with the same name will be concatenated together, left-to-right, into
     a single field in the resultant tuple. For example, "01aa1?bbb11a" will match a string such
@@ -267,13 +267,13 @@ def field_name(name):
 
 
 def chop(w, *segment_widths):
-    """ Returns a list of wirevectors each a slice of the original 'w'
+    """ Returns a list of WireVectors each a slice of the original 'w'
 
-    :param w: The wirevector to be chopped up into segments
+    :param w: The WireVector to be chopped up into segments
     :param segment_widths: Additional arguments are integers which are bitwidths
-    :return: A list of wirevectors each with a proper segment width
+    :return: A list of WireVectors each with a proper segment width
 
-    This function chops a wirevector into a set of smaller wirevectors of different
+    This function chops a WireVector into a set of smaller WireVectors of different
     lengths.  It is most useful when multiple "fields" are contained with a single
     wirevector, for example when breaking apart an instruction.  For example, if
     you wish to break apart a 32-bit MIPS I-type (Immediate) instruction you know

pyrtl/inputoutput.py

@@ -25,12 +25,26 @@
 
 
 def input_from_blif(blif, block=None, merge_io_vectors=True, clock_name='clk'):
-    """ Read an open blif file or string as input, updating the block appropriately.
-
-    Assumes the blif has been flattened and their is only a single module.
-    Assumes that there is only one single shared clock and reset.
-    Assumes that output is generated by Yosys with formals in a particular order.
-    Ignores reset signal (which it assumes is input only to the flip flops).
+    """ Read an open BLIF file or string as input, updating the block appropriately.
+
+    :param blif: An open BLIF file to read
+    :param block: The block where the logic will be added
+    :param merge_io_vectors: If True, Input/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 Input/Output (e.g. a 2-bit wire 'a').
+    :param clock_name: The name of the clock (defaults to 'clk')
+
+    If merge_io_vectors is True, then given 1-bit Input wires 'a[0]' and 'a[1]', these
+    wires will be combined into a single 2-bit 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 Input wires of the block. This holds similarly for Outputs.
+
+    This assumes the following:
+      * The BLIF has been flattened and there is only a single module
+      * There is only one single shared clock and reset
+      * Output is generated by Yosys with formals in a particular order
+
+    It currently ignores the reset signal (which it assumes is input only to the flip flops).
     """
     import pyparsing
     import six
@@ -285,7 +299,11 @@ def _name_sorted(wires, name_mapper=lambda w: w.name):
 def output_to_firrtl(open_file, rom_blocks=None, block=None):
     """ Output the block as FIRRTL code to the output file.
 
-    If rom is intialized in PyRTL code, you can pass in the rom_blocks as a list [rom1, rom2, ...].
+    :param open_file: File to write to
+    :param rom_blocks: List of ROM blocks to be initialized
+    :param block: Block to use (defaults to working block)
+
+    If ROM is initialized in PyRTL code, you can pass in the rom_blocks as a list [rom1, rom2, ...].
     """
     block = working_block(block)
 
@@ -463,9 +481,9 @@ def net_graph(block=None, split_state=False):
     :param split_state: if True, split connections to/from a register update net; this
         means that registers will be appear as source nodes of the network, and
         'r' nets (i.e. the logic for setting a register's next value) will
-        be treated as sink nodes of the network
+        be treated as sink nodes of the network.
 
-    Graph has the following form:
+    The graph has the following form:
         { node1: { nodeA: edge1A, nodeB: edge1B},
           node2: { nodeB: edge2B, nodeC: edge2C},
           ...
@@ -474,8 +492,8 @@ def net_graph(block=None, split_state=False):
     aka: edge = graph[source][dest]
 
     Each node can be either a logic net or a WireVector (e.g. an Input, an Output, a
-    Const or even an undriven WireVector (which acts as a source or sink in the network)
-    Each edge is a WireVector or derived type (Input, Output, Register, etc.)
+    Const or even an undriven WireVector (which acts as a source or sink in the network).
+    Each edge is a WireVector or derived type (Input, Output, Register, etc.).
     Note that inputs, consts, and outputs will be both "node" and "edge".
     WireVectors that are not connected to any nets are not returned as part
     of the graph.
@@ -521,7 +539,18 @@ def net_graph(block=None, split_state=False):
 
 
 def output_to_trivialgraph(file, namer=_trivialgraph_default_namer, block=None, split_state=False):
-    """ Walk the block and output it in trivial graph format to the open file. """
+    """ Walk the block and output it in trivial graph format to the open file.
+
+    :param file: Open file to write to
+    :param namer: A function that takes in an object (a wire or logicnet) as the first argument and
+        a boolean `is_edge` as the second that is set True if the object is a wire, and returns
+        a string representing that object.
+    :param block: Block to use (defaults to current working block)
+    :param split_state: if True, split connections to/from a register update net; this
+        means that registers will be appear as source nodes of the network, and
+        'r' nets (i.e. the logic for setting a register's next value) will
+        be treated as sink nodes of the network.
+    """
     graph = net_graph(block, split_state)
     node_index_map = {}  # map node -> index
 
@@ -549,7 +578,7 @@ def _default_edge_namer(edge, is_to_splitmerge=False, extra_edge_info=None):
     :param is_to_splitmerge: if the node to which the edge points
         is a select or concat operation
     :param extra_edge_info: a map from edge to any additional data you want
-        to print associated with it (e.g. timing data).
+        to print associated with it (e.g. timing data)
     :return: a function that can be called by graph namer function you pass
         in to block_to_graphviz_string
     """
@@ -569,9 +598,22 @@ def _default_edge_namer(edge, is_to_splitmerge=False, extra_edge_info=None):
 
 
 def _default_node_namer(node, split_state=False, extra_node_info=None):
+    """
+    A function for naming a node for use in the graphviz graph.
+
+    :param node: the node (i.e. WireVector or deriving class, or a logic net)
+    :param split_state: if True, split connections to/from a register update net; this
+        means that registers will be appear as source nodes of the network, and
+        'r' nets (i.e. the logic for setting a register's next value) will
+        be treated as sink nodes of the network.
+    :param extra_node_info: a map from node to any additional data you want
+        to print associated with it (e.g. delay data)
+    :return: a function that can be called by graph namer function you pass
+        in to block_to_graphviz_string
+    """
     def label(v):
         if extra_node_info and node in extra_node_info:
-            v = v + "(" + str(extra_node_info[node]) + ")"
+            v = v + " (" + str(extra_node_info[node]) + ")"
         return v
 
     if isinstance(node, Const):
@@ -619,14 +661,27 @@ def label(v):
             raise PyrtlError('no naming rule for "%s"' % str(node))
 
 
-def graphviz_default_namer(
+def _graphviz_default_namer(
         thing,
         is_edge,
         is_to_splitmerge,
         split_state,
         node_namer=_default_node_namer,
         edge_namer=_default_edge_namer):
-    """ Returns a "good" graphviz label for thing. """
+    """ Returns a "good" Graphviz label for thing.
+
+    :param thing: The edge (wire) or node (logic net or Input/Output/Const) to name
+    :param is_edge: True if thing is an edge
+    :param is_to_splitmerge: if the node to which the edge points
+        is a select or concat operation
+    :param split_state: If True, visually split the connections to/from a register update net.
+    :param node_namer: A function mapping a node to a label; one of its arguments
+        is a dict mapping nodes to nodes to additional user-supplied information.
+    :param edge_namer: A function mapping an edge to a label; one of its arguments
+        is a dict mapping nodes to nodes to additional user-supplied information.
+    :return: A function that knows how to label each element in the graph, which
+        can be passed to 'output_to_graphviz' or 'block_to_graphviz_string'
+    """
     if is_edge:
         return edge_namer(thing, is_to_splitmerge=is_to_splitmerge)
     else:
@@ -636,13 +691,18 @@ def graphviz_default_namer(
 def graphviz_detailed_namer(
         extra_node_info=None,
         extra_edge_info=None):
-    """ Returns a detailed namer that prints extra information about nodes/edges in the given maps.
+    """ Returns a detailed Graphviz namer that prints extra information
+    about nodes/edges in the given maps.
 
-    :param extra_node_info: A map from node to some object about that node
+    :param extra_node_info: A dict from node to some object about that node
         (its string representation will be printed next to the node's label)
-    :param extra_edge_info: A map from edge to some object about that edge
+    :param extra_edge_info: A dict from edge to some object about that edge
         (its string representation will be printed next to the edge's label)
-    :return: a function that can be used as the namer function for block_to_graphviz_string
+    :return: A function that knows how to label each element in the graph, which
+        can be passed to 'output_to_graphviz' or 'block_to_graphviz_string'
+
+    If both dict arguments are None, the returned namer behaves identically
+    to the default Graphviz namer.
     """
 
     def node_namer(node, split_state):
@@ -652,19 +712,55 @@ def edge_namer(edge, is_to_splitmerge):
         return _default_edge_namer(edge, is_to_splitmerge, extra_edge_info)
 
     def namer(thing, is_edge, is_to_splitmerge, split_state):
-        return graphviz_default_namer(
+        return _graphviz_default_namer(
             thing, is_edge, is_to_splitmerge, split_state,
             node_namer=node_namer, edge_namer=edge_namer)
     return namer
 
 
-def output_to_graphviz(file, namer=graphviz_default_namer, block=None, split_state=True):
-    """ Walk the block and output it in graphviz format to the open file. """
+def output_to_graphviz(file, block=None, namer=_graphviz_default_namer, split_state=True):
+    """ Walk the block and output it in Graphviz format to the open file.
+
+    :param file: Open file to write to
+    :param block: Block to use (defaults to current working block)
+    :param namer: Function used to label each edge and node; see 'block_to_graphviz_string'
+        for more information.
+    :param split_state: If True, visually split the connections to/from a register update net.
+    """
     print(block_to_graphviz_string(block, namer, split_state), file=file)
 
 
-def block_to_graphviz_string(block=None, namer=graphviz_default_namer, split_state=True):
-    """ Return a graphviz string for the block. """
+def block_to_graphviz_string(block=None, namer=_graphviz_default_namer, split_state=True):
+    """ Return a Graphviz string for the block.
+
+    :param namer: A function mapping graph objects (wires/logic nets) to labels.
+        If you want a more detailed namer, pass in a call to `graphviz_detailed_namer` (see below).
+    :param block: Block to use (defaults to current working block)
+    :param split_state: If True, split connections to/from a register update net; this
+        means that registers will be appear as source nodes of the network, and
+        'r' nets (i.e. the logic for setting a register's next value) will
+        be treated as sink nodes of the network.
+
+    The normal namer function will label user-named wires with their names and label the nodes
+    (logic nets or Input/Output/Const terminals) with their operator symbol or name/value,
+    respectively. If custom information about each node in the graph is desired, you can pass
+    in a custom namer function which must have the same signature as the default namer,
+    `_graphviz_default_namer`. However, we recommend you instead pass in a call to
+    `graphviz_detailed_namer`, supplying it with your own dicts mapping wires and nodes to labels.
+    For any wire/node found in these maps, that additional information will be printed in
+    parentheses alongside the node in the graphviz graph.
+
+    For example, if you wanted to print the delay of each wire and the fanout of each
+    gate, you could pass in two maps to the `graphviz_detailed_namer` call, which returns a namer
+    function that can subsequently be passed to 'output_to_graphviz' or
+    'block_to_graphviz_string'. ::
+
+        node_fanout = {n: "Fanout: %d" % my_fanout_func(n) for n in working_block().logic}
+        wire_delay = {w: "Delay: %.2f" % my_delay_func(w) for w in working_block().wirevector_set}
+
+        with open("out.gv", "w") as f:
+            output_to_graphviz(f, namer=graphviz_detailed_namer(node_fanout, wire_delay))
+    """
     graph = net_graph(block, split_state)
     node_index_map = {}  # map node -> index
 
@@ -698,12 +794,22 @@ def block_to_graphviz_string(block=None, namer=graphviz_default_namer, split_sta
 
 
 def output_to_svg(file, block=None, split_state=True):
-    """ Output the block as an SVG to the open file. """
+    """ Output the block as an SVG to the open file.
+
+    :param file: Open file to write to
+    :param block: Block to use (defaults to current working block)
+    :param split_state: If True, visually split the connections to/from a register update net.
+    """
     print(block_to_svg(block, split_state), file=file)
 
 
 def block_to_svg(block=None, split_state=True):
-    """ Return an SVG for the block. """
+    """ Return an SVG for the block.
+
+    :param block: Block to use (defaults to current working block)
+    :param split_state: If True, visually split the connections to/from a register update net.
+    :return: The SVG representation of the block
+    """
     try:
         from graphviz import Source
         return Source(block_to_graphviz_string(block, split_state=split_state))._repr_svg_()
@@ -712,7 +818,13 @@ def block_to_svg(block=None, split_state=True):
 
 
 def trace_to_html(simtrace, trace_list=None, sortkey=None):
-    """ Return a HTML block showing the trace. """
+    """ Return a HTML block showing the trace.
+
+    :param simtrace: A SimulationTrace object
+    :param trace_list: (optional) A list of wires to display
+    :param sortkey: (optional) The key with which to sort the trace_list
+    :return: An HTML block showing the trace
+    """
 
     from .simulation import SimulationTrace, _trace_sort_key
     if not isinstance(simtrace, SimulationTrace):