Skip to content

Commit d4656b5

Browse files
timsherwoodtimsherwood
committed
major restructure of documentation
1 parent 8dd0fa3 commit d4656b5

File tree

12 files changed

+193
-47
lines changed

12 files changed

+193
-47
lines changed

‎docs/advanced.rst‎

Lines changed: 3 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
Passes
2-
======
1+
Transforming Passes
2+
===================
33

44
.. automodule:: pyrtl.passes
55
:members:
@@ -8,12 +8,4 @@ Passes
88
:undoc-members:
99
:exclude-members: __dict__,__weakref__,__module__
1010

11-
Conditional Blocks
12-
==================
13-
14-
.. automodule:: pyrtl.conditional
15-
:members:
16-
:show-inheritance:
17-
:special-members:
18-
:undoc-members:
19-
:exclude-members: __dict__,__weakref__,__module__
11+
.. autoclass:: pyrtl.core.PostSynthBlock

‎docs/analysis.rst‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,6 @@ Provides tools for analyzing aspects of PyRTL designs
1717
1818
.. .. _estimate-ref:
1919
20-
Estimate
21-
--------
22-
2320
.. automodule:: pyrtl.analysis.estimate
2421
:members:
2522
:show-inheritance:

‎docs/basic.rst‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,3 +79,18 @@ ROMs
7979
:members:
8080
:show-inheritance:
8181
:special-members: __init__
82+
83+
84+
Conditionals
85+
==================
86+
87+
.. automodule:: pyrtl.conditional
88+
:members:
89+
:show-inheritance:
90+
:special-members:
91+
:undoc-members:
92+
:exclude-members: __dict__,__weakref__,__module__
93+
94+
.. autodata:: pyrtl.otherwise
95+
96+
.. autodata:: pyrtl.conditional_assignment

‎docs/blocks.rst‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
Logic Nets and Blocks
2+
==========================
3+
4+
LogicNets
5+
---------
6+
7+
.. autoclass:: pyrtl.core.LogicNet
8+
9+
10+
Blocks
11+
------
12+
13+
.. autoclass:: pyrtl.core.Block
14+
15+
.. autofunction:: pyrtl.core.working_block
16+
17+
.. autofunction:: pyrtl.core.reset_working_block
18+
19+
.. autofunction:: pyrtl.core.set_working_block
20+
21+
.. autofunction:: pyrtl.core.temp_working_block

‎docs/export.rst‎

Lines changed: 31 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,34 @@
1+
12
Exporting and Importing Designs
23
===============================
34

4-
.. automodule:: pyrtl.inputoutput
5-
:members:
6-
:show-inheritance:
7-
:special-members:
8-
:undoc-members:
9-
:exclude-members: __dict__,__weakref__,__module__
5+
6+
Exporting Hardware Designs
7+
--------------------------
8+
9+
.. autofunction:: pyrtl.verilog.output_to_verilog
10+
11+
.. autofunction:: pyrtl.inputoutput.output_to_firrtl
12+
13+
Exporting Testbenches
14+
------------------------
15+
16+
.. autofunction:: pyrtl.verilog.output_verilog_testbench
17+
18+
19+
Importing Verilog
20+
-----------------
21+
22+
.. autofunction:: pyrtl.inputoutput.input_from_blif
23+
24+
25+
Outputing for Visualization
26+
---------------------------
27+
28+
.. autofunction:: pyrtl.inputoutput.output_to_trivialgraph
29+
.. autofunction:: pyrtl.inputoutput.output_to_graphviz
30+
.. autofunction:: pyrtl.inputoutput.output_to_svg
31+
.. autofunction:: pyrtl.inputoutput.block_to_graphviz_string
32+
.. autofunction:: pyrtl.inputoutput.block_to_svg
33+
.. autofunction:: pyrtl.inputoutput.trace_to_html
34+

‎docs/helpers.rst‎

Lines changed: 94 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,99 @@
11
Helper Functions
22
================
33

4-
Built-in Hardware Generators
4+
Cutting and Extending WireVectors
5+
---------------------------------
6+
7+
The functions below provide ways of combining, slicing, and extending WireVectors in
8+
ways that are often useful in hardware design. The functions below extend those member
9+
functions of the WireVector class iself (which provides support for the python builtin
10+
``len``, slicing as just as in a python list e.g. ``wire[3:6]``, ``zero_extend``, ``sign_extend``,
11+
and many operators such as addition and multiplication).
12+
13+
.. autofunction:: pyrtl.corecircuits.concat
14+
.. autofunction:: pyrtl.corecircuits.concat_list
15+
.. autofunction:: pyrtl.corecircuits.match_bitwidth
16+
.. autofunction:: pyrtl.helperfuncs.truncate
17+
.. autofunction:: pyrtl.helperfuncs.chop
18+
19+
Coercion to WireVector
20+
----------------------
21+
22+
In PyRTL there is only one function in charge of coercing values into WireVectors, and that is
23+
``as_wires``. This function is called in almost all helper functions and classes to manage
24+
the mixture of constants and WireVectors that naturally occur in hardware development.
25+
26+
.. autofunction:: pyrtl.corecircuits.as_wires
27+
28+
Control Flow Hardware
29+
---------------------
30+
31+
.. autofunction:: pyrtl.corecircuits.mux
32+
.. autofunction:: pyrtl.corecircuits.select
33+
.. autofunction:: pyrtl.corecircuits.enum_mux
34+
.. autofunction:: pyrtl.corecircuits.bitfield_update
35+
.. autofunction:: pyrtl.corecircuits.bitfield_update_set
36+
.. autofunction:: pyrtl.helperfuncs.match_bitpattern
37+
38+
Creating Lists of WireVectors
39+
-----------------------------
40+
41+
.. autofunction:: pyrtl.helperfuncs.input_list
42+
.. autofunction:: pyrtl.helperfuncs.output_list
43+
.. autofunction:: pyrtl.helperfuncs.register_list
44+
.. autofunction:: pyrtl.helperfuncs.wirevector_list
45+
46+
Interpreting Vectors of Bits
547
----------------------------
648

7-
.. automodule:: pyrtl.corecircuits
8-
:members:
9-
:show-inheritance:
10-
:special-members: __init__ __iter__ __str__
11-
:undoc-members:
12-
13-
Hardware Design Helper Functions
14-
--------------------------------
15-
16-
.. automodule:: pyrtl.helperfuncs
17-
:members:
18-
:show-inheritance:
19-
:special-members:
20-
:undoc-members:
21-
:exclude-members: __dict__,__weakref__,__module__
49+
Under the hood, every single `value` a PyRTL design operates on is a bit vector (which is, in turn, simply
50+
an integer of bounded power-of-two size. Interpreting these bit vectors as humans, and turning human
51+
understandable values into their corresponding bit vectors, can both be a bit of a pain. The functions
52+
below do not create any hardware but rather help in the process of reasoning about bit vector representations
53+
of human understandable values.
54+
55+
.. autofunction:: pyrtl.helperfuncs.val_to_signed_integer
56+
.. autofunction:: pyrtl.helperfuncs.val_to_formatted_str
57+
.. autofunction:: pyrtl.helperfuncs.formatted_str_to_val
58+
.. autofunction:: pyrtl.helperfuncs.infer_val_and_bitwidth
59+
.. autofunction:: pyrtl.helperfuncs.log2
60+
61+
Debugging
62+
---------
63+
64+
.. autofunction:: pyrtl.core.set_debug_mode
65+
.. autofunction:: pyrtl.helperfuncs.probe
66+
.. autofunction:: pyrtl.helperfuncs.rtl_assert
67+
.. autofunction:: pyrtl.helperfuncs.check_rtl_assertions
68+
.. autofunction:: pyrtl.helperfuncs.find_loop
69+
.. autofunction:: pyrtl.helperfuncs.find_and_print_loop
70+
71+
Reductions
72+
----------
73+
74+
.. autofunction:: pyrtl.corecircuits.and_all_bits
75+
.. autofunction:: pyrtl.corecircuits.or_all_bits
76+
.. autofunction:: pyrtl.corecircuits.xor_all_bits
77+
.. autofunction:: pyrtl.corecircuits.parity
78+
.. autofunction:: pyrtl.corecircuits.rtl_any
79+
.. autofunction:: pyrtl.corecircuits.rtl_all
80+
.. autofunction:: pyrtl.corecircuits.tree_reduce
81+
82+
Extended Logic and Arithmetic
83+
-----------------------------
84+
85+
The functions below provide ways of comparing and arithmetically combining WireVectors
86+
in ways that are often useful in hardware design. The functions below extend those member
87+
functions of the WireVector class iself (which provides support for addition, unsigned
88+
multiplication, unsigned comparison, and many others).
89+
90+
.. autofunction:: pyrtl.corecircuits.signed_add
91+
.. autofunction:: pyrtl.corecircuits.signed_mult
92+
.. autofunction:: pyrtl.corecircuits.signed_lt
93+
.. autofunction:: pyrtl.corecircuits.signed_le
94+
.. autofunction:: pyrtl.corecircuits.signed_gt
95+
.. autofunction:: pyrtl.corecircuits.signed_ge
96+
.. autofunction:: pyrtl.corecircuits.shift_left_arithmetic
97+
.. autofunction:: pyrtl.corecircuits.shift_right_arithmetic
98+
.. autofunction:: pyrtl.corecircuits.shift_left_logical
99+
.. autofunction:: pyrtl.corecircuits.shift_right_logical

‎docs/index.rst‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
You can adapt this file completely to your liking, but it should at least
44
contain the root `toctree` directive.
55
6+
=====
67
PYRTL
78
=====
89

@@ -65,6 +66,14 @@ view results with your favorite waveform viewer, build hardware transformation p
6566
simulations, design, test, and even verify hugely complex digital systems, and much more. Most critically of
6667
all it is easy to extend with your own approaches to digital hardware development as you find necessary.
6768

69+
70+
Overview of PyRTL
71+
=================
72+
73+
If you are brand new to PyRTL we recommend that you start with going through the
74+
`Examples of PyRTL Code <https://github.com/UCSBarchlab/PyRTL/tree/master/examples>`_ which will show you
75+
most of the core functionality in the context of a complete design.
76+
6877
PyRTL Classes:
6978
--------------
7079

@@ -178,8 +187,9 @@ PyRTL Functionality:
178187
:caption: Contents:
179188

180189
basic
181-
helpers
182190
simtest
191+
blocks
192+
helpers
183193
analysis
184194
export
185195
rtllib

‎pyrtl/conditional.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ def currently_under_condition():
6767
# instances (hopefully the only and unchanging instances) of the following two types.
6868

6969
class _ConditionalAssignment(object):
70-
""" Helper type of global "conditional_assignment". """
70+
""" Context providing funcitionality of "conditional_assignment". """
7171
def __enter__(self):
7272
global _depth
7373
_check_no_nesting()
@@ -83,7 +83,7 @@ def __exit__(self, *exc_info):
8383

8484

8585
class _Otherwise(object):
86-
""" Helper type of global "otherwise". """
86+
""" Context providing functionality of pyrtl "otherwise". """
8787
def __enter__(self):
8888
_push_condition(otherwise)
8989

‎pyrtl/core.py‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -858,7 +858,16 @@ def temp_working_block():
858858

859859

860860
def set_debug_mode(debug=True):
861-
""" Set the global debug mode. """
861+
""" Set the global debug mode.
862+
863+
:param debug: Optional boolean paramter to which debug mode will be set
864+
865+
This function will set the debug mode to the specified value. Debug mode
866+
is, by default, set to off to keep the performance of the system. With debug
867+
mode set to true, all temporary WireVectors created will be given a name based
868+
on the line of code on which they were created and a snapshot of the call-stack
869+
for those WireVectors will be kept as well.
870+
"""
862871
global debug_mode
863872
global _setting_keep_wirevector_call_stack
864873
global _setting_slower_but_more_descriptive_tmps

‎pyrtl/corecircuits.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -509,7 +509,8 @@ def enum_mux(cntrl, table, default=None, strict=True):
509509
Note that if a default is set, then this check is not performed as
510510
the default will provide valid values for any underspecified keys.
511511
:return: a WireVector which is the result of the mux.
512-
::
512+
513+
Examples::
513514
514515
from enum import IntEnum
515516

0 commit comments

Comments
 (0)