adding/augmenting documentation and fixing typos

Author: mdko

pyrtl/analysis/estimate.py

@@ -260,7 +260,7 @@ def max_length(self):
         The result assumes that the circuit is implemented in a 130nm process, and that there is no
         setup or hold time associated with the circuit.  The resulting value is in picoseconds.  If
         an proper estimation of timing is required it is recommended to us "max_freq" to determine
-        the clock period as it more accurately consideres scaling and setup/hold.
+        the clock period as it more accurately considers scaling and setup/hold.
         """
         return max(self.timing_map.values())
 
@@ -315,7 +315,7 @@ def critical_path_pass(old_critical_path, first_wire):
     @staticmethod
     def print_critical_paths(critical_paths):
         """ Prints the results of the critical path length analysis.
-            Done by default by the `timing_critical_path()` function.
+            Done by default by the `TimingAnalysis().critical_path()` function.
         """
         line_indent = " " * 2
         #  print the critical path

pyrtl/compilesim.py

@@ -234,8 +234,8 @@ def _sort_tuple(t):
     def run(self, inputs):
         """Run many steps of the simulation.
 
-        The argument is a list of input mappings for each step,
-        and its length is the number of steps to be executed.
+        :param inputs: A list of input mappings for each step;
+          its length is the number of steps to be executed.
         """
         steps = len(inputs)
         # create i/o arrays of the appropriate length

pyrtl/conditional.py

@@ -76,7 +76,7 @@ def __exit__(self, *exc_info):
             _finalize()
         finally:
             # even if the above finalization throws an error we need to
-            # return reset the state to prevent errors from bleeding over
+            # reset the state to prevent errors from bleeding over
             _reset_conditional_state()  # sets _depth back to 0
 
 

pyrtl/core.py

@@ -144,7 +144,7 @@ def __eq__(self, other):
         # We can't be going and calling __eq__ recursively on the logic nets for all of
         # the args and dests because that will actually *create* new logic nets which is
         # very much not what people would expect to happen.  Instead we define equality
-        # as the immutable fields as being equal and the list of args and dests as being
+        # as the immutable fields being equal and the list of args and dests being
         # references to the same objects.
         return (self.op == other.op
                 and self.op_param == other.op_param
@@ -186,20 +186,20 @@ class Block(object):
 
     1) the op (a single character describing the operation such as '+' or 'r'),
     2) a set of hard parameters to that primitives (such as the constants to
-       select from the "selection" op.
+       select from the "selection" op).
     3) the tuple "args" which list the wirevectors hooked up as inputs to
        this particular net.
     4) the tuple "dests" which list the wirevectors hooked up as output for
        this particular net.
 
     Below is a list of the basic operations.  These properties (more formally
-    specified) should all be checked by the class method sanity_check.
+    specified) should all be checked by the class method 'sanity_check'.
 
-    * Most logical and arithmetic ops are pretty self explanatory, each takes
-      exactly two arguments and they should perform the arithmetic or logical
+    * Most logical and arithmetic ops are pretty self explanatory. Each takes
+      exactly two arguments, and they should perform the arithmetic or logical
       operation specified. OPS: ('&','|','^','n','~','+','-','*').  All inputs must
       be the same bitwidth.  Logical operations produce as many bits as are in
-      the input, while '+' and '-' produce n+1 bits, and '*' produced 2n bits.
+      the input, while '+' and '-' produce n+1 bits, and '*' produces 2n bits.
 
     * In addition there are some operations for performing comparisons
       that should perform the operation specified.  The '=' op is checking
@@ -210,29 +210,29 @@ class Block(object):
     * The 'w' operator is simply a directional wire and has no logic function.
 
     * The 'x' operator is a mux which takes a select bit and two signals.
-      If the value of the select bit is 0 it selects the second argument, if
+      If the value of the select bit is 0 it selects the second argument; if
       it is 1 it selects the third argument.  Select must be a single bit, while
       the other two arguments must be the same length.
 
-    * The 'c' operator is the concatiation operator and combines any number of
+    * The 'c' operator is the concatenation operator and combines any number of
       wirevectors (a,b,...,z) into a single new wirevector with "a" in the MSB
       and "z" (or whatever is last) in the LSB position.
 
     * The 's' operator is the selection operator and chooses, based on the
-      op_param specificied, a subset of the logic bits from a WireVector to
+      op_param specified, a subset of the logic bits from a WireVector to
       select.  Repeats are accepted.
 
     * The 'r' operator is a register and on posedge, simply copies the value
-      from the input to the output of the register
+      from the input to the output of the register.
 
     * The 'm' operator is a memory block read port, which supports async reads (acting
-      like combonational logic). Multiple read (and write) ports are possible to
+      like combinational logic). Multiple read (and write) ports are possible to
       the same memory but each 'm' defines only one of those. The op_param
       is a tuple containing two references: the mem id, and a reference to the
       MemBlock containing this port. The MemBlock should only be used for debug and
       sanity checks. Each read port has one addr (an arg) and one data (a dest).
 
-    * The '@' (update) operator is a memory block write port, which supports syncronous writes
+    * The '@' (update) operator is a memory block write port, which supports synchronous writes
       (writes are "latched" at posedge).  Multiple write (and read) ports are possible
       to the same memory but each '@' defines only one of those. The op_param
       is a tuple containing two references: the mem id, and a reference to the MemoryBlock.
@@ -243,13 +243,13 @@ class Block(object):
 
     The connecting elements (args and dests) should be WireVectors or derived
     from WireVector, and should be registered with the block using
-    the method add_wirevector.  Nets should be registered using add_net.
+    the method 'add_wirevector'.  Nets should be registered using 'add_net'.
 
-    In addition, there is a member legal_ops which defines the set of operations
+    In addition, there is a member 'legal_ops' which defines the set of operations
     that can be legally added to the block.  By default it is set to all of the above
     defined operations, but it can be useful in certain cases to only allow a
     subset of operations (such as when transforms are being done that are "lowering"
-    the blocks to more primitive ops.
+    the blocks to more primitive ops).
     """
 
     def __init__(self):
@@ -314,7 +314,7 @@ def get_memblock_by_name(self, name, strict=False):
         This useful for when a block defines its own internal memory block, and
         during simulation you want to instantiate that memory with certain values
         for testing. Since the Simulation constructor requires a reference to the
-        memory object itself, but the block your testing defines the memory internally,
+        memory object itself, but the block you're testing defines the memory internally,
         this allows you to get the object reference.
 
         Note that this requires you know the name of the memory block, meaning that
@@ -410,16 +410,16 @@ def net_connections(self, include_virtual_nodes=False):
           signal an external source or sink (such as the source for an Input net).
           If disabled, these nodes will be excluded from the adjacency dictionaries
         :return wire_src_dict, wire_sink_dict
-          Returns two dictionaries: one that map WireVectors to the logic
-          nets that creates their signal and one that maps WireVectors to
+          Returns two dictionaries: one that maps WireVectors to the logic
+          net that creates their signal and one that maps WireVectors to
           a list of logic nets that use the signal
 
         These dictionaries make the creation of a graph much easier, as
         well as facilitate other places in which one would need wire source
-        and wire sink information
+        and wire sink information.
 
         Look at inputoutput.net_graph for one such graph that uses the information
-        from this function
+        from this function.
         """
         src_list = {}
         dst_list = {}
@@ -466,8 +466,8 @@ def __iter__(self):
         that all of its "parents" have already been returned earlier in the iteration.
 
         Note: this method will throw an error if there are loops in the
-        logic that do not involve registers
-        Also, the order of the nets is not guaranteed to be the the same
+        logic that do not involve registers.
+        Also, the order of the nets is not guaranteed to be the same
         over multiple iterations"""
         from .wire import Input, Const, Register
         src_dict, dest_dict = self.net_connections()

pyrtl/corecircuits.py

@@ -19,7 +19,7 @@ def mux(index, *mux_ins, **kwargs):
     :param WireVector index: used as the select input to the multiplexer
     :param WireVector mux_ins: additional WireVector arguments selected when select>1
     :param WireVector kwargs: additional WireVectors, keyword arg "default"
-      If you are selecting between less items than your index can address, you can
+      If you are selecting between fewer items than your index can address, you can
       use the "default" keyword argument to auto-expand those terms.  For example,
       if you have a 3-bit index but are selecting between 6 options, you need to specify
       a value for those other 2 possible values of index (0b110 and 0b111).
@@ -91,7 +91,7 @@ def select(sel, truecase, falsecase):
 
     The hardware this generates is exactly the same as "mux" but by putting the
     true case as the first argument it matches more of the C-style ternary operator
-    semantics which can be helpful for readablity.
+    semantics which can be helpful for readability.
 
     Example of mux as "ternary operator" to take the min of 'a' and 5: ::
 
@@ -145,9 +145,9 @@ def concat_list(wire_list):
     :param wire_list: list of WireVectors to concat
     :return: WireVector with length equal to the sum of the args' lengths
 
-    This take a list of wirevectors and concats them all into a single wire
-    vector with the element at index 0 serving as the least significant bits.
-    This is useful when you have a variable number of wirevectors to concatenate,
+    This take a list of WireVectors and concats them all into a single
+    WireVector with the element at index 0 serving as the least significant bits.
+    This is useful when you have a variable number of WireVectors to concatenate,
     otherwise "concat" is prefered.
 
     Example using concat to combine two bytes into a 16-bit quantity: ::
@@ -160,12 +160,12 @@ def concat_list(wire_list):
 
 
 def signed_add(a, b):
-    """ Return wirevector for result of signed addition.
+    """ Return a WireVector for result of signed addition.
 
-    :param a: a wirevector to serve as first input to addition
-    :param b: a wirevector to serve as second input to addition
+    :param a: a WireVector to serve as first input to addition
+    :param b: a WireVector to serve as second input to addition
 
-    Given a length n and length m wirevector the result of the
+    Given a length n and length m WireVector the result of the
     signed addition is length max(n,m)+1.  The inputs are twos
     complement sign extended to the same length before adding.
     If an integer is passed to either a or b, it will be converted
@@ -259,7 +259,7 @@ def shift_left_arithmetic(bits_to_shift, shift_amount):
     of the input `bits_to_shift` but where the bits have been shifted
     to the left.  An arithemetic shift is one that treats the value as
     as signed number, although for left shift arithmetic and logic shift
-    are identical.  Note that `shift_amount` is treated as unsigned.
+    they are identical.  Note that `shift_amount` is treated as unsigned.
     """
     # shift left arithmetic and logical are the same thing
     return shift_left_logical(bits_to_shift, shift_amount)
@@ -324,7 +324,8 @@ def shift_right_logical(bits_to_shift, shift_amount):
 
 
 def match_bitwidth(*args, **opt):
-    """ Matches the bitwidth of all of the input arguments with zero or sign extend
+    """ Matches the bitwidth of all of the input arguments with zero or sign extension,
+        returning new WireVectors
 
     :param args: WireVectors of which to match bitwidths
     :param opt: Optional keyword argument 'signed=True' (defaults to False)
@@ -333,12 +334,12 @@ def match_bitwidth(*args, **opt):
     Example of matching the bitwidths of two WireVectors `a` and `b` with
     with zero extention: ::
 
-        a,b = match_bitwidth(a, b)
+        a, b = match_bitwidth(a, b)
 
     Example of matching the bitwidths of three WireVectors `a`,`b`, and `c` with
     with sign extention: ::
 
-        a,b = match_bitwidth(a, b, c, signed=True)
+        a, b = match_bitwidth(a, b, c, signed=True)
     """
     # TODO: when we drop 2.7 support, this code should be cleaned up with explicit
     # kwarg support for "signed" rather than the less than helpful "**opt"
@@ -376,7 +377,7 @@ def myhardware(input_a, input_b):
             b = as_wires(input_b)
         myhardware(3, x)
 
-    The function as_wires will covert the 3 to Const but keep `x` unchanged
+    The function as_wires will convert the 3 to Const but keep `x` unchanged
     assuming it is a WireVector.
 
     """
@@ -407,19 +408,19 @@ def myhardware(input_a, input_b):
 
 
 def bitfield_update(w, range_start, range_end, newvalue, truncating=False):
-    """ Return wirevector w but with some of the bits overwritten by newvalue.
+    """ Return WireVector w but with some of the bits overwritten by newvalue.
 
-    :param w: a wirevector to use as the starting point for the update
+    :param w: a WireVector to use as the starting point for the update
     :param range_start: the start of the range of bits to be updated
     :param range_end: the end of the range of bits to be updated
     :param newvalue: the value to be written in to the start:end range
     :param truncating: if true, silently clip newvalue to the proper bitwidth rather than
           throw an error if the value provided is too large
 
-    Given a wirevector w, this function returns a new wirevector that
+    Given a WireVector w, this function returns a new WireVector that
     is identical to w except in the range of bits specified.  In that
     specified range, the value newvalue is swapped in.  For example:
-    `bitfield_update(w, 20, 23, 0x7)` will return return a wirevector
+    `bitfield_update(w, 20, 23, 0x7)` will return return a WireVector
     of the same length as w, and with the same values as w, but with
     bits 20, 21, and 22 all set to 1.
 
@@ -463,16 +464,16 @@ def bitfield_update(w, range_start, range_end, newvalue, truncating=False):
 def enum_mux(cntrl, table, default=None, strict=True):
     """ Build a mux for the control signals specified by an enum.
 
-    :param cntrl: is a wirevector and control for the mux.
-    :param table: is a dictionary of the form mapping enum->wirevector.
-    :param default: is a wirevector to use when the key is not present. In addtion
+    :param cntrl: is a WireVector and control for the mux.
+    :param table: is a dictionary of the form mapping enum->WireVector.
+    :param default: is a WireVector to use when the key is not present. In addition
         it is possible to use the key 'otherwise' to specify a default value, but
         it is an error if both are supplied.
     :param strict: is flag, that when set, will cause enum_mux to check
         that the dictionary has an entry for every possible value in the enum.
         Note that if a default is set, then this check is not performed as
         the default will provide valid values for any underspecified keys.
-    :return: a wirevector which is the result of the mux.
+    :return: a WireVector which is the result of the mux.
     ::
 
         from enum import IntEnum
@@ -567,7 +568,7 @@ def _apply_op_over_all_bits(op, vector):
 
 
 def rtl_any(*vectorlist):
-    """ Hardware equivalent of python native "any".
+    """ Hardware equivalent of Python native "any".
 
     :param WireVector vectorlist: all arguments are WireVectors of length 1
     :return: WireVector of length 1
@@ -584,7 +585,7 @@ def rtl_any(*vectorlist):
 
 
 def rtl_all(*vectorlist):
-    """ Hardware equivalent of python native "all".
+    """ Hardware equivalent of Python native "all".
 
     :param WireVector vectorlist: all arguments are WireVectors of length 1
     :return: WireVector of length 1

pyrtl/helperfuncs.py

@@ -329,7 +329,7 @@ def formatted_str_to_val(data, format, enum_set=None):
 
     :param data: a string holding the value to convert
     :param format: a string holding a format which will be used to convert the data string
-    :param enum_set: an iterable of enums which are used as part of the converstion process
+    :param enum_set: an iterable of enums which are used as part of the conversion process
 
     Given a string (not a wirevector!) covert that to an unsigned integer ready for input
     to the simulation enviornment.  This helps deal with signed/unsigned numbers (simulation
@@ -717,7 +717,7 @@ def __init__(self, block=None):
 
     def shrank(self, block=None, percent_diff=0, abs_diff=1):
         """
-        Returns whether a block has less nets than before
+        Returns whether a block has fewer nets than before
 
         :param Block block: block to check (if changed)
         :param Number percent_diff: percentage difference threshold

pyrtl/inputoutput.py

@@ -456,7 +456,7 @@ 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, and Output, a
+    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.)
     Note that inputs, consts, and outputs will be both "node" and "edge".
@@ -488,14 +488,14 @@ def net_graph(block=None, split_state=False):
         try:
             _from = wire_src_dict[w]
         except Exception:
-            _from = w
+            _from = w  # e.g. an Input/Const
         if split_state and isinstance(w, Register):
             _from = w
 
         try:
             _to_list = wire_dst_dict[w]
         except Exception:
-            _to_list = [w]
+            _to_list = [w]  # e.g. an Output
 
         for _to in _to_list:
             graph[_from][_to] = w

pyrtl/memory.py

@@ -5,8 +5,8 @@
 MemBlocks supports any number of the following operations:
 
 * read: `d = mem[address]`
-* write: `mem[address] = d`
-* write with an enable: `mem[address] = MemBlock.EnabledWrite(d,enable=we)`
+* write: `mem[address] <<= d`
+* write with an enable: `mem[address] <<= MemBlock.EnabledWrite(d,enable=we)`
 
 Based on the number of reads and writes a memory will be inferred
 with the correct number of ports to support that
@@ -154,7 +154,7 @@ class MemBlock(_MemReadBase):
 
     Usage::
 
-        data <<= memory[addr]  (infer read port)
+        data = memory[addr]  (infer read port)
         memory[addr] <<= data  (infer write port)
         mem[address] <<= MemBlock.EnabledWrite(data,enable=we)