Major rework of rtllib's documentation, lots of changes:

* Discourage use of many functions and stop publishing their documentation:
  * MultiSelector (use conditional assignment)
  * Matrix.multiply (use Matrix.__mul__)
  * libutil.match_bitwidth (use pyrtl.match_bitwidth)
  * partition_wire (use wire_matrix or chop)
  * str_to_int_array (use a list comprehension)
  * rev_twos_comp_repr (use val_to_signed_integer)
  * _shifted_reg_next (use shift_left_logical, shift_right_logical)
  * sim_and_ret_out, sim_and_ret_outws (use step_multiple)
* Fix `shift_left_logical`, `shift_right_logical`, `shift_right_arithmetic` so
  they work when the integer shift amount is greater than or equal to the
  bitwidth. Previously they would raise an exception while attempting to slice
  the input.
* Define a `Direction` enum for `barrel_shifter` to improve readability.
* Don't explicitly instantiate `SimulationTrace()` since `Simulation` will do
  it for us.
* Add references to basic hardware implementations available in PyRTL's core
  library.
* Add documentation for Matrix's dunder methods.
* Add documentation for PRNGs.
* Move AES documentation from module level to class level.
* Add type annotations.
* Fix formatting.
* Add links.

Author: fdxmw

docs/index.rst

@@ -106,15 +106,14 @@ different classes help you do that: :class:`.Simulation`,
 interchangeably.  Typically one starts with :class:`.Simulation` and then moves
 up to :class:`.FastSimulation` when performance begins to matter.
 
-Both :class:`.Simulation` and :class:`.FastSimulation` take an instance of
-:class:`.SimulationTrace` as an argument (or makes an empty
-:class:`.SimulationTrace` by default), which stores a list of the signals as
-they are simulated. This trace can then be rendered to the terminal with
-:meth:`~.SimulationTrace.render_trace`.
+Both :class:`.Simulation` and :class:`.FastSimulation` store a list of each
+wire's value in each cycle in :attr:`.Simulation.tracer`, which is an instance
+of :class:`.SimulationTrace`. Traces can then be rendered to the terminal with
+:meth:`.SimulationTrace.render_trace`.
 :class:`SimulationTraces<.SimulationTrace>` can be handled in other ways, for
-example they can be extracted as a test bench
-(:func:`.output_verilog_testbench`) or exported to a VCD file
-(:meth:`~.SimulationTrace.print_vcd`).
+example they can be extracted as a test bench with
+:func:`.output_verilog_testbench`, or exported to a VCD file with
+:meth:`~.SimulationTrace.print_vcd`.
 
 Optimization
 ------------

docs/rtllib.rst

@@ -1,9 +1,14 @@
-.. PyRTL rtllib master file
-
 RTL Library
 ===========
 
-Useful circuits, functions, and testing utilities.
+Useful circuits, functions, and utilities.
+
+Multiplexers
+------------
+
+.. automodule:: pyrtl.rtllib.muxes
+   :members:
+   :exclude-members: MultiSelector
 
 Adders
 ------
@@ -12,47 +17,42 @@ Adders
    :members:
    :undoc-members:
 
-AES-128
--------
+Multipliers
+-----------
 
-.. automodule:: pyrtl.rtllib.aes
+.. automodule:: pyrtl.rtllib.multipliers
    :members:
-   :undoc-members:
 
-Barrel
-------
+Barrel Shifter
+--------------
 
 .. automodule:: pyrtl.rtllib.barrel
    :members:
    :undoc-members:
 
-Library Utilities
------------------
-
-.. automodule:: pyrtl.rtllib.libutils
-   :members:
-
-Multipliers
------------
+Matrix
+------
 
-.. automodule:: pyrtl.rtllib.multipliers
+.. automodule:: pyrtl.rtllib.matrix
    :members:
+   :special-members: __init__, __len__, __getitem__, __reversed__, __add__, __sub__, __mul__, __matmul__, __pow__
+   :exclude-members: multiply
 
-Muxes
------
+Pseudo-Random Numbers
+---------------------
 
-.. automodule:: pyrtl.rtllib.muxes
+.. automodule:: pyrtl.rtllib.prngs
    :members:
 
-Matrix
-------
+AES-128
+-------
 
-.. automodule:: pyrtl.rtllib.matrix
+.. autoclass:: pyrtl.rtllib.aes.AES
    :members:
-   :special-members: __init__
 
 Testing Utilities
 -----------------
 
 .. automodule:: pyrtl.rtllib.testingutils
    :members:
+   :exclude-members: generate_in_wire_and_values, sim_and_ret_out, sim_and_ret_outws, sim_multicycle, multi_sim_multicycle

examples/example1-combologic.py

@@ -65,12 +65,9 @@
 
 # --- Step 2: Simulate Design  -----------------------------------------------
 
-# Okay, let's simulate our one-bit adder.  To keep track of the output of
-# the simulation we need to make a new "SimulationTrace" and a "Simulation"
-# that then uses that trace.
+# Okay, let's simulate our one-bit adder.
 
-sim_trace = pyrtl.SimulationTrace()
-sim = pyrtl.Simulation(tracer=sim_trace)
+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
@@ -89,7 +86,7 @@
 # Now all we need to do is print the trace results to the screen. Here we use
 # "render_trace" with some size information.
 print('--- One Bit Adder Simulation ---')
-sim_trace.render_trace(symbol_len=2)
+sim.tracer.render_trace(symbol_len=2)
 
 a_value = sim.inspect(a)
 print("The latest value of 'a' was: " + str(a_value))
@@ -105,13 +102,13 @@
 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
-    add_result = (sim_trace.trace['a'][cycle]
-                  + sim_trace.trace['b'][cycle]
-                  + sim_trace.trace['c'][cycle])
+    add_result = (sim.tracer.trace['a'][cycle]
+                  + sim.tracer.trace['b'][cycle]
+                  + sim.tracer.trace['c'][cycle])
     # We can select off the bits and compare
     python_sum = add_result & 0x1
     python_cout = (add_result >> 1) & 0x1
-    if (python_sum != sim_trace.trace['sum'][cycle]
-            or python_cout != sim_trace.trace['carry_out'][cycle]):
+    if (python_sum != sim.tracer.trace['sum'][cycle]
+            or python_cout != sim.tracer.trace['carry_out'][cycle]):
         print('This Example is Broken!!!')
         exit(1)

examples/example2-counter.py

@@ -74,9 +74,8 @@ def ripple_add(a, b, carry_in=0):
 # 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_trace = pyrtl.SimulationTrace()
-sim = pyrtl.Simulation(tracer=sim_trace)
+sim = pyrtl.Simulation()
 for cycle in range(15):
     sim.step()
     assert sim.value[counter] == cycle % 8
-sim_trace.render_trace()
+sim.tracer.render_trace()

examples/example3-statemachine.py

@@ -101,8 +101,7 @@ class State(enum.IntEnum):
 
 # Now let's build and test our state machine.
 
-sim_trace = pyrtl.SimulationTrace()
-sim = pyrtl.Simulation(tracer=sim_trace)
+sim = pyrtl.Simulation()
 
 # Rather than just give some random inputs, let's specify some specific 1-bit
 # values. To make it easier to simulate it over several steps, we'll use
@@ -119,7 +118,7 @@ class State(enum.IntEnum):
 # Also, to make our input/output easy to reason about let's specify an order to
 # the traces. We also use `enum_name` to display the state names (WAIT, TOK1,
 # ...) rather than their numbers (0, 1, ...).
-sim_trace.render_trace(
+sim.tracer.render_trace(
     trace_list=['token_in', 'req_refund', 'state', 'dispense', 'refund'],
     repr_per_name={'state': pyrtl.enum_name(State)})
 

examples/example4-debuggingtools.py

@@ -51,8 +51,7 @@
 vals2 = [int(2**random.uniform(1, 8) - 2) for _ in range(20)]
 vals3 = [int(2**random.uniform(1, 8) - 2) for _ in range(20)]
 
-sim_trace = pyrtl.SimulationTrace()
-sim = pyrtl.Simulation(tracer=sim_trace)
+sim = pyrtl.Simulation()
 sim.step_multiple({
     'in1': vals1,
     'in2': vals2,
@@ -62,16 +61,18 @@
 # In order to get the result data, you do not need to print a waveform of the trace.
 # You always have the option to just pull the data out of the tracer directly
 print("---- Inputs and debug_out ----")
-print("in1:       ", str(sim_trace.trace['in1']))
-print("in2:       ", str(sim_trace.trace['in2']))
-print("debug_out: ", str(sim_trace.trace['debug_out']))
+print("in1:       ", str(sim.tracer.trace['in1']))
+print("in2:       ", str(sim.tracer.trace['in2']))
+print("debug_out: ", str(sim.tracer.trace['debug_out']))
 print('\n')
 
 # Below, I am using the ability to directly retrieve the trace data to
 # verify the correctness of the first adder
 
 for i in range(len(vals1)):
-    assert sim_trace.trace['debug_out'][i] == sim_trace.trace['in1'][i] + sim_trace.trace['in2'][i]
+    actual = sim.tracer.trace['debug_out'][i]
+    expected = sim.tracer.trace['in1'][i] + sim.tracer.trace['in2'][i]
+    assert actual == expected
 
 
 # --- Probe ----
@@ -118,8 +119,7 @@
 vals1 = [int(2**random.uniform(1, 8) - 2) for _ in range(10)]
 vals2 = [int(2**random.uniform(1, 8) - 2) for _ in range(10)]
 
-sim_trace = pyrtl.SimulationTrace()
-sim = pyrtl.Simulation(tracer=sim_trace)
+sim = pyrtl.Simulation()
 sim.step_multiple({
     'in1': vals1,
     'in2': vals2,
@@ -128,8 +128,8 @@
 # Now we will show the values of the inputs and probes
 # and look at that, we didn't need to make any outputs!
 # (although we did, to demonstrate the power and convenience of probes)
-sim_trace.render_trace()
-sim_trace.print_trace()
+sim.tracer.render_trace()
+sim.tracer.print_trace()
 
 print("--- Probe w/ debugging: ---")
 # Say we wanted to have gotten more information about

examples/example5-introspection.py

@@ -71,7 +71,6 @@ def stage4(self):
 simplepipeline = SimplePipelineExample()
 print(pyrtl.working_block())
 # Simulation of the core
-sim_trace = pyrtl.SimulationTrace()
-sim = pyrtl.Simulation(tracer=sim_trace)
+sim = pyrtl.Simulation()
 sim.step_multiple({}, nsteps=15)
-sim_trace.render_trace()
+sim.tracer.render_trace()

examples/example6-memory.py

@@ -90,10 +90,9 @@
 # value map.
 print("---------memories----------")
 print(pyrtl.working_block())
-sim_trace = pyrtl.SimulationTrace()
-sim = pyrtl.Simulation(tracer=sim_trace, memory_value_map=memvals)
+sim = pyrtl.Simulation(memory_value_map=memvals)
 sim.step_multiple(simvals)
-sim_trace.render_trace()
+sim.tracer.render_trace()
 
 # Cleanup in preparation for the ROM example
 pyrtl.reset_working_block()
@@ -164,7 +163,6 @@ def rom_data_func(address):
 # supply a memory value map because ROMs are defined with the values
 # predefined.
 
-sim_trace = pyrtl.SimulationTrace()
-sim = pyrtl.Simulation(tracer=sim_trace)
+sim = pyrtl.Simulation()
 sim.step_multiple(simvals)
-sim_trace.render_trace()
+sim.tracer.render_trace()

examples/example8-verilog.py

@@ -70,17 +70,16 @@
 io_vectors = pyrtl.working_block().wirevector_subset((pyrtl.Input, pyrtl.Output))
 
 # We are only going to trace the input and output vectors for clarity
-sim_trace = pyrtl.SimulationTrace(wires_to_track=io_vectors)
 # Now simulate the logic with some random inputs
-sim = pyrtl.Simulation(tracer=sim_trace)
+sim = pyrtl.Simulation(tracer=pyrtl.SimulationTrace(wires_to_track=io_vectors))
 for i in range(15):
     # here we actually generate random booleans for the inputs
     sim.step({
         'x': random.choice([0, 1]),
         'y': random.choice([0, 1]),
         'cin': random.choice([0, 1])
     })
-sim_trace.render_trace(symbol_len=2)
+sim.tracer.render_trace(symbol_len=2)
 
 
 # ---- Exporting to Verilog ----
@@ -115,11 +114,10 @@
     print(vfile.getvalue())
 
 print("--- Simulation Results ---")
-sim_trace = pyrtl.SimulationTrace([counter_output, zero])
-sim = pyrtl.Simulation(tracer=sim_trace)
+sim = pyrtl.Simulation(tracer=pyrtl.SimulationTrace([counter_output, zero]))
 for cycle in range(15):
     sim.step({'zero': random.choice([0, 0, 0, 1])})
-sim_trace.render_trace()
+sim.tracer.render_trace()
 
 # We already did the "hard" work of generating a test input for this simulation, so
 # we might want to reuse that work when we take this design through a Verilog toolchain.
@@ -128,7 +126,7 @@
 
 print("--- Verilog for the TestBench ---")
 with io.StringIO() as tbfile:
-    pyrtl.output_verilog_testbench(dest_file=tbfile, simulation_trace=sim_trace)
+    pyrtl.output_verilog_testbench(dest_file=tbfile, simulation_trace=sim.tracer)
     print(tbfile.getvalue())
 
 

examples/introduction-to-hardware.py

@@ -175,14 +175,13 @@ def attempt4_hardware_fibonacci(n, req, bitwidth):
 fib_out <<= output[0]
 done_out <<= output[1]
 
-sim_trace = pyrtl.SimulationTrace()
-sim = pyrtl.Simulation(tracer=sim_trace)
+sim = pyrtl.Simulation()
 
 sim.step({'n_in': 7, 'req_in': 1})
 
 sim.step({'n_in': 0, 'req_in': 0})
 while not sim.inspect('done_out'):
     sim.step({'n_in': 0, 'req_in': 0})
 
-sim_trace.render_trace(
+sim.tracer.render_trace(
     trace_list=['n_in', 'req_in', 'i', 'fib_out', 'done_out'], repr_func=int)