Rewrap comments and docstrings to 88 columns.

Author: fdxmw

examples/example1-combologic.py

@@ -1,64 +1,62 @@
-"""Example 1:  A simple combination logic block example.
-
-This example declares a block of hardware with three one-bit inputs,
-(a,b,c) and two one-bit outputs (sum, cout).  The logic declared is a
-simple one-bit adder and the definition uses some of the most common
-parts of PyRTL. The adder is then simulated on random data, the
-wave form is printed to the screen, and the resulting trace is
-compared to a "correct" addition.  If the result is correct then a 0
-is returned, else 1.
+"""
+Example 1: A simple combination logic block example.
+
+This example declares a block of hardware with three one-bit inputs, (a,b,c) and two
+one-bit outputs (sum, cout). The logic declared is a simple one-bit adder and the
+definition uses some of the most common parts of PyRTL. The adder is then simulated on
+random data, the wave form is printed to the screen, and the resulting trace is compared
+to a "correct" addition. If the result is correct then a 0 is returned, else 1.
 """
 
 import random
 
 import pyrtl
 
-# The basic idea of PyRTL is to specify the component of a some hardware block
-# through the declaration of wires and operations on those wires.  The current
-# working block, an instance of a class devilishly named "Block", is implicit
-# in all of the below code -- it is easiest to start with the way wires work.
+# The basic idea of PyRTL is to specify the component of a some hardware block through
+# the declaration of wires and operations on those wires. The current working block, an
+# instance of a class devilishly named "Block", is implicit in all of the below code --
+# it is easiest to start with the way wires work.
 
 # --- Step 1: Define Logic -------------------------------------------------
 
-# One of the most fundamental types in PyRTL is the "WireVector" which acts
-# very much like a Python list of 1-bit wires.  Unlike a normal list, though, the
-# number of bits is explicitly declared.
+# One of the most fundamental types in PyRTL is the "WireVector" which acts very much
+# like a Python list of 1-bit wires. Unlike a normal list, though, the number of bits is
+# explicitly declared.
 temp1 = pyrtl.WireVector(bitwidth=1, name="temp1")
 
-# Both arguments are in fact optional and default to a bitwidth of 1 and a unique
-# name generated by PyRTL starting with 'tmp'
+# Both arguments are in fact optional and default to a bitwidth of 1 and a unique name
+# generated by PyRTL starting with 'tmp'
 temp2 = pyrtl.WireVector()
 
-# Two special types of WireVectors are Input and Output, which are used to specify
-# an interface to the hardware block.
+# Two special types of WireVectors are Input and Output, which are used to specify an
+# interface to the hardware block.
 a, b, c = pyrtl.Input(1, "a"), pyrtl.Input(1, "b"), pyrtl.Input(1, "c")
 sum, carry_out = pyrtl.Output(1, "sum"), pyrtl.Output(1, "carry_out")
 
-# Okay, let's build a one-bit adder.  To do this we need to use the assignment
-# operator, which is '<<='.  This takes an already declared wire and "connects"
-# it to some other already declared wire.  Let's start with the sum bit, which is
-# of course just the xor of the three inputs
+# Okay, let's build a one-bit adder. To do this we need to use the assignment operator,
+# which is '<<='. This takes an already declared wire and "connects" it to some other
+# already declared wire. Let's start with the sum bit, which is of course just the xor
+# of the three inputs
 sum <<= a ^ b ^ c
 
 # The carry_out bit would just be "carry_out <<= a & b | a & c | b & c" but let's break
-# than down a bit to see what is really happening.  What if we want to give names
-# to the partial signals in the middle of that computation?  When you take
-# "a & b" in PyRTL, what that really means is "make an AND gate, connect one input
-# to 'a' and the other to 'b' and return the result of the gate".  The result of
-# that AND gate can then be assigned to temp1 or it can be used like any other
-# Python variable.
+# than down a bit to see what is really happening. What if we want to give names to the
+# partial signals in the middle of that computation? When you take "a & b" in PyRTL,
+# what that really means is "make an AND gate, connect one input to 'a' and the other to
+# 'b' and return the result of the gate". The result of that AND gate can then be
+# assigned to temp1 or it can be used like any other Python variable.
 
 temp1 <<= a & b  # connect the result of a & b to the pre-allocated wirevector
 temp2 <<= a & c
 temp3 = b & c  # temp3 IS the result of b & c (this is the first mention of temp3)
 carry_out <<= temp1 | temp2 | temp3
 
-# You can access the working block through pyrtl.working_block(), and for most
-# things one block is all you will need.  Example 2 discusses this in more detail,
-# but for now we can just print the block to see that in fact it looks like the
-# hardware we described.  The format is a bit weird, but roughly translates to
-# a list of gates (the 'w' gates are just wires).  The ins and outs of the gates
-# are printed 'name'/'bitwidth''WireVectorType'
+# You can access the working block through pyrtl.working_block(), and for most things
+# one block is all you will need. Example 2 discusses this in more detail, but for now
+# we can just print the block to see that in fact it looks like the hardware we
+# described. The format is a bit weird, but roughly translates to a list of gates (the
+# 'w' gates are just wires). The ins and outs of the gates are printed
+# 'name'/'bitwidth''WireVectorType'
 
 print("--- One Bit Adder Implementation ---")
 print(pyrtl.working_block())
@@ -70,12 +68,11 @@
 
 sim = pyrtl.Simulation()
 
-# Now all we need to do is call "sim.step" to simulate each clock cycle of our
-# design.  We just need to pass in some input each cycle, which is a dictionary
-# mapping inputs (the *names* of the inputs, not the actual Input instances)
-# to their value for that signal each cycle.  In this simple example, we
-# can just specify a random value of 0 or 1 with Python's random module.  We
-# call step 15 times to simulate 15 cycles.
+# Now all we need to do is call "sim.step" to simulate each clock cycle of our design.
+# We just need to pass in some input each cycle, which is a dictionary mapping inputs
+# (the *names* of the inputs, not the actual Input instances) to their value for that
+# signal each cycle. In this simple example, we can just specify a random value of 0 or
+# 1 with Python's random module. We call step 15 times to simulate 15 cycles.
 
 for _cycle in range(15):
     sim.step(
@@ -92,19 +89,19 @@
 sim.tracer.render_trace(symbol_len=2)
 
 a_value = sim.inspect(a)
-print("The latest value of 'a' was: " + str(a_value))
+print("The latest value of 'a' was: ", a_value)
 
 # --- Step 3: Verification of Simulated Design ---------------------------------------
 
 # Now finally, let's check the trace to make sure that sum and carry_out are actually
-# the right values when compared to Python's addition operation.  Note that
-# all the simulation is done at this point and we are just checking the waveform,
-# but there is no reason you could not do this at simulation time if you had a
-# really long-running design.
+# the right values when compared to Python's addition operation. Note that all the
+# simulation is done at this point and we are just checking the waveform, but there is
+# no reason you could not do this at simulation time if you had a really long-running
+# design.
 
 for cycle in range(15):
-    # Note that we are doing all arithmetic on values, NOT wirevectors, here.
-    # We can add the inputs together to get a value for the result
+    # Note that we are doing all arithmetic on values, NOT wirevectors, here. We can add
+    # the inputs together to get a value for the result
     add_result = (
         sim.tracer.trace["a"][cycle]
         + sim.tracer.trace["b"][cycle]

examples/example2-counter.py

@@ -1,9 +1,10 @@
-"""Example 2:  A Counter with Ripple Carry Adder.
+"""
+Example 2: A Counter with Ripple Carry Adder.
 
-This next example shows how you make stateful things with registers
-and more complex hardware structures with functions.  We generate
-a 3-bit ripple carry adder building off of the 1-bit adder from
-the prior example, and then hook it to a register to count up modulo 8.
+This next example shows how you make stateful things with registers and more complex
+hardware structures with functions. We generate a 3-bit ripple carry adder building off
+of the 1-bit adder from the prior example, and then hook it to a register to count up
+modulo 8.
 """
 
 import pyrtl
@@ -18,18 +19,18 @@ def one_bit_add(a, b, carry_in):
     return sum, carry_out
 
 
-# A function in PyRTL is nothing special -- it just so happens that the statements
-# it encapsulate tell PyRTL to build some hardware.  If we call "one_bit_add"
-# above with the arguments "x", "y", and "z", it will make a one-bit adder to add
-# those values together and return the wires for sum and carry_out as applied to "x",
-# "y", and "z".  If I call it again on "i", "j", and "k" it will build a new one-bit
-# adder for those inputs and return the resulting sum and carry_out for that adder.
+# A function in PyRTL is nothing special -- it just so happens that the statements it
+# encapsulate tell PyRTL to build some hardware. If we call "one_bit_add" above with the
+# arguments "x", "y", and "z", it will make a one-bit adder to add those values together
+# and return the wires for sum and carry_out as applied to "x", "y", and "z". If I call
+# it again on "i", "j", and "k" it will build a new one-bit adder for those inputs and
+# return the resulting sum and carry_out for that adder.
 
 
-# While PyRTL actually provides an "+" operator for WireVectors which generates
-# adders, a ripple carry adder is something people can understand easily but has
-# enough structure to be mildly interesting.  Let's define an adder of arbitrary
-# length recursively and (hopefully) Pythonically.  More comments after the code.
+# While PyRTL actually provides an "+" operator for WireVectors which generates adders,
+# a ripple carry adder is something people can understand easily but has enough
+# structure to be mildly interesting. Let's define an adder of arbitrary length
+# recursively and (hopefully) Pythonically. More comments after the code.
 
 
 def ripple_add(a, b, carry_in=0):
@@ -45,18 +46,21 @@ def ripple_add(a, b, carry_in=0):
     return sumbits, carry_out
 
 
-# The above code breaks down into two cases.  1) If the size of the inputs
-# is one-bit just do one_bit_add.  2) If they are more than one bit, do
-# a one-bit add on the least significant bits, a ripple carry on the rest,
-# and then stick the results back together into one WireVector.  A couple
-# interesting features of PyRTL can be seen here:  WireVectors can be indexed
-# like lists, with [0] accessing the least significant bit and [1:] being an
-# example of the use of Python slicing syntax.  While you can add two lists
-# together in Python, a WireVector + WireVector means "make an adder", so to
-# concatenate the bits of two vectors one needs to use "concat".  Finally,
-# if we look at "carry_in" it seems to have a default value of the integer "0" but
-# is a WireVector at other times.  Python supports polymorphism throughout
-# and PyRTL will cast integers and some other types to WireVectors when it can.
+# The above code breaks down into two cases:
+#
+# 1) If the size of the inputs is one-bit just do one_bit_add.
+# 2) If they are more than one bit, do a one-bit add on the least significant bits, a
+#    ripple carry on the rest, and then stick the results back together into one
+#    WireVector.
+#
+# A couple interesting features of PyRTL can be seen here: WireVectors can be indexed
+# like lists, with [0] accessing the least significant bit and [1:] being an example of
+# the use of Python slicing syntax. While you can add two lists together in Python, a
+# WireVector + WireVector means "make an adder", so to concatenate the bits of two
+# vectors one needs to use "concat". Finally, if we look at "carry_in" it seems to have
+# a default value of the integer "0" but is a WireVector at other times. Python supports
+# polymorphism throughout and PyRTL will cast integers and some other types to
+# WireVectors when it can.
 
 
 # Now let's build a 3-bit counter from our N-bit ripple carry adder.
@@ -65,17 +69,17 @@ def ripple_add(a, b, carry_in=0):
 sum, carry_out = ripple_add(counter, pyrtl.Const("1'b1"))
 counter.next <<= sum
 
-# A couple new things in the above code.  The two remaining types of basic
-# WireVectors, Const and Register, both appear.  Const, unsurprisingly, is just for
-# holding constants (such as the 0 in ripple_add), but here we create one directly
-# from a Verilog-like string which includes both the value and the bitwidth.
-# Registers are just like wires, except their updates are delayed to the next
-# clock cycle.  This is made explicit in the syntax through the property '.next'
-# which should always be set for registers.  In this simple example, we make the
-# counter's value on the next cycle equal to the counter's value this cycle plus one.
-
-# Now let's run the bugger.  No need for inputs, as it doesn't have any.
-# Finally we'll print the trace to the screen and check that it counts up correctly.
+# A couple new things in the above code. The two remaining types of basic WireVectors,
+# Const and Register, both appear. Const, unsurprisingly, is just for holding constants
+# (such as the 0 in ripple_add), but here we create one directly from a Verilog-like
+# string which includes both the value and the bitwidth. Registers are just like wires,
+# except their updates are delayed to the next clock cycle. This is made explicit in the
+# syntax through the property '.next' which should always be set for registers. In this
+# simple example, we make the counter's value on the next cycle equal to the counter's
+# value this cycle plus one.
+
+# Now let's run the bugger. No need for inputs, as it doesn't have any. Finally we'll
+# print the trace to the screen and check that it counts up correctly.
 
 sim = pyrtl.Simulation()
 for cycle in range(15):