Refactoring, rework how <mode> is specified in the Verilog

Signed-off-by: David Shah <davey1576@gmail.com>
diff --git a/tests/adder/pb_type.xml b/tests/adder/pb_type.xml
index 509ce66..05124b1 100644
--- a/tests/adder/pb_type.xml
+++ b/tests/adder/pb_type.xml
@@ -1,4 +1,4 @@
-<pb_type blif_model=".subckt adder" name="adder" num_pb="1">
+<pb_type xmlns:xi="http://www.w3.org/2001/XInclude" name="adder" num_pb="1">
   <input equivalent="false" name="a" num_pins="1"/>
   <input equivalent="false" name="b" num_pins="1"/>
   <input equivalent="false" name="ci" num_pins="1"/>
diff --git a/tests/dff/pb_type.xml b/tests/dff/pb_type.xml
index 4bf0c6e..4b92f05 100644
--- a/tests/dff/pb_type.xml
+++ b/tests/dff/pb_type.xml
@@ -1,4 +1,4 @@
-<pb_type blif_model=".latch" class="flipflop" name="dff" num_pb="1">
+<pb_type xmlns:xi="http://www.w3.org/2001/XInclude" blif_model=".latch" class="flipflop" name="dff" num_pb="1">
   <clock equivalent="false" name="clk" num_pins="1"/>
   <input equivalent="false" name="rst" num_pins="1"/>
   <input equivalent="false" name="d" num_pins="1"/>
diff --git a/tests/lut2/pb_type.xml b/tests/lut2/pb_type.xml
index af537d1..96896f1 100644
--- a/tests/lut2/pb_type.xml
+++ b/tests/lut2/pb_type.xml
@@ -1,4 +1,4 @@
-<pb_type blif_model=".subckt lut2" name="lut2" num_pb="1">
+<pb_type xmlns:xi="http://www.w3.org/2001/XInclude" name="lut2" num_pb="1">
   <input equivalent="false" name="a" num_pins="1"/>
   <input equivalent="false" name="b" num_pins="1"/>
   <output equivalent="false" name="y" num_pins="1"/>
diff --git a/tests/model.xml b/tests/model.xml
index 97d527b..a1985e3 100644
--- a/tests/model.xml
+++ b/tests/model.xml
@@ -1,14 +1,14 @@
 <models>
   <model name="test_pb">
     <input_ports>
-      <port is_clock="1" name="clk"/>
-      <port clock="clk" name="rst"/>
-      <port clock="clk" name="a"/>
-      <port clock="clk" name="b"/>
-      <port clock="clk" name="ci"/>
+      <port name="clk"/>
+      <port name="rst"/>
+      <port name="a"/>
+      <port name="b"/>
+      <port name="ci"/>
     </input_ports>
     <output_ports>
-      <port clock="clk" name="q"/>
+      <port name="q"/>
       <port name="co"/>
     </output_ports>
   </model>
diff --git a/tests/pb_type.xml b/tests/pb_type.xml
index cafd613..095c270 100644
--- a/tests/pb_type.xml
+++ b/tests/pb_type.xml
@@ -1,34 +1,36 @@
-<pb_type blif_model=".subckt test_pb" name="test_pb" num_pb="1">
-  <clock equivalent="false" name="clk" num_pins="1"/>
+<pb_type xmlns:xi="http://www.w3.org/2001/XInclude" name="test_pb" num_pb="1">
+  <input equivalent="false" name="clk" num_pins="1"/>
   <input equivalent="false" name="rst" num_pins="1"/>
   <input equivalent="false" name="a" num_pins="1"/>
   <input equivalent="false" name="b" num_pins="1"/>
   <input equivalent="false" name="ci" num_pins="1"/>
   <output equivalent="false" name="q" num_pins="1"/>
   <output equivalent="false" name="co" num_pins="1"/>
-  <mode name="ADD">
-    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="adder/pb_type.xml"/>
-    <interconn>
-      <direct input="test_pb.a" name="test_pb_a_to_adder_a" output="adder.a"/>
-      <direct input="test_pb.b" name="test_pb_b_to_adder_b" output="adder.b"/>
-      <direct input="test_pb.ci" name="test_pb_ci_to_adder_ci" output="adder.ci"/>
-      <direct input="adder.co" name="adder_co_to_test_pb_co" output="test_pb.co"/>
-      <direct input="adder.y" name="adder_y_to_dff_d" output="dff.d"/>
-    </interconn>
+  <mode name="test_add">
+    <xi:include href="adder/pb_type.xml"/>
+    <xi:include href="dff/pb_type.xml"/>
+    <interconnect>
+      <direct input="test_add.a" name="adder_a" output="adder.a"/>
+      <direct input="test_add.b" name="adder_b" output="adder.b"/>
+      <direct input="test_add.ci" name="adder_ci" output="adder.ci"/>
+      <direct input="adder.co" name="test_add_co" output="test_add.co"/>
+      <direct input="test_add.clk" name="dff_clk" output="dff.clk"/>
+      <direct input="adder.y" name="dff_d" output="dff.d"/>
+      <direct input="test_add.rst" name="dff_rst" output="dff.rst"/>
+      <direct input="dff.q" name="test_add_q" output="test_add.q"/>
+    </interconnect>
   </mode>
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dff/pb_type.xml"/>
-  <mode name="LUT">
-    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="lut2/pb_type.xml"/>
-    <interconn>
-      <direct input="test_pb.a" name="test_pb_a_to_lut2_a" output="lut2.a"/>
-      <direct input="test_pb.b" name="test_pb_b_to_lut2_b" output="lut2.b"/>
-      <direct input="lut2.co" name="lut2_co_to_test_pb_co" output="test_pb.co"/>
-      <direct input="lut2.y" name="lut2_y_to_dff_d" output="dff.d"/>
-    </interconn>
+  <mode name="test_lut">
+    <xi:include href="dff/pb_type.xml"/>
+    <xi:include href="lut2/pb_type.xml"/>
+    <interconnect>
+      <direct input="test_lut.clk" name="dff_clk" output="dff.clk"/>
+      <direct input="lut2.y" name="dff_d" output="dff.d"/>
+      <direct input="test_lut.rst" name="dff_rst" output="dff.rst"/>
+      <direct input="dff.q" name="test_lut_q" output="test_lut.q"/>
+      <direct input="test_lut.a" name="lut2_a" output="lut2.a"/>
+      <direct input="test_lut.b" name="lut2_b" output="lut2.b"/>
+      <direct input="lut2.co" name="test_lut_co" output="test_lut.co"/>
+    </interconnect>
   </mode>
-  <interconnect>
-    <direct input="test_pb.clk" name="test_pb_clk_to_dff_clk" output="dff.clk"/>
-    <direct input="test_pb.rst" name="test_pb_rst_to_dff_rst" output="dff.rst"/>
-    <direct input="dff.q" name="dff_q_to_test_pb_q" output="test_pb.q"/>
-  </interconnect>
 </pb_type>
diff --git a/tests/sim.v b/tests/sim.v
index ffee6e2..0500920 100644
--- a/tests/sim.v
+++ b/tests/sim.v
@@ -2,13 +2,25 @@
 `include "dff/sim.v"
 `include "lut2/sim.v"
 
+
+(* blackbox *)
 module test_pb(input clk, rst, a, b, ci, output q, co);
+endmodule
+
+(* ALTERNATIVE_TO="test_pb" *)
+module test_add(input clk, rst, a, b, ci, output q, co);
 
 wire d;
+adder adder_i(.a(a), .b(b), .ci(ci), .y(d), .co(co));
+dff dff_i(.clk(clk), .rst(rst), .d(d), .q(q));
 
-(* MODE="ADD" *) adder adder_i(.a(a), .b(b), .ci(ci), .y(d), .co(co));
-(* MODE="LUT" *) lut2 lut2_i(.a(a), .b(b), .y(d), .co(co));
+endmodule
 
+(* ALTERNATIVE_TO="test_pb" *)
+module test_lut(input clk, rst, a, b, ci, output q, co);
+
+wire d;
+lut2 lut2_i(.a(a), .b(b), .y(d), .co(co));
 dff dff_i(.clk(clk), .rst(rst), .d(d), .q(q));
 
 endmodule
diff --git a/vlog_to_model.py b/vlog_to_model.py
index 85ae87a..53b6f83 100755
--- a/vlog_to_model.py
+++ b/vlog_to_model.py
@@ -39,11 +39,11 @@
 else:
     yj = YosysJson(aig_json)
 
-top = yj.get_top()
-tmod = yj.get_top_module()
+top = yj.top
+tmod = yj.top_module
 models_xml = ET.Element("models")
 model_xml = ET.SubElement(models_xml, "model", {'name': top})
-ports = tmod.get_ports()
+ports = tmod.ports
 
 inports_xml = ET.SubElement(model_xml, "input_ports")
 outports_xml = ET.SubElement(model_xml, "output_ports")
diff --git a/vlog_to_pbtype.py b/vlog_to_pbtype.py
index eabc847..ca5ffa2 100755
--- a/vlog_to_pbtype.py
+++ b/vlog_to_pbtype.py
@@ -11,8 +11,9 @@
     - (* CLASS="lut|routing|flipflop|mem" *) : specify the class of an given
     instance. Must be specified for BELs
 
-    - (* PB_NAME="name" *) : override the name of the pb_type
-    (default: name of module)
+    - (* ALTERNATIVE_TO="module" *) : specify the module is one of several
+    modes of another module (i.e. a <mode> in the pb_type). Note that all modes
+    must be visible at the time of pb_type generation.
 
 The following are allowed on nets within modules (TODO: use proper Verilog timing):
     All are NYI at the moment!
@@ -22,10 +23,8 @@
 
     - (* CLK_TO_Q="clk 10e-12" *) : specify clock-to-output time for a given clock
 
-    - (* PB_MUX=1 *) : if the signal is driven by a $mux cell, generate a pb_type <mux> element for it
-
-The following are allowed on instances within modules:
-    - (* MODE="mode" *) : specify pb_type is only valid within a given mode
+    - (* PB_MUX=1 *) : if the signal is driven by a $mux cell, generate a
+    pb_type <mux> element for it
 """
 
 import yosys.run
@@ -61,42 +60,88 @@
 vjson = yosys.run.vlog_to_json(args.infiles, False, False)
 yj = YosysJson(vjson)
 
-ET.register_namespace("xi", "http://www.w3.org/2001/XInclude")
+xi_url = "http://www.w3.org/2001/XInclude"
+ET.register_namespace('xi', xi_url)
+xi_include = "{%s}include" % xi_url
+
+def include_xml(parent, href):
+    return ET.SubElement(parent, xi_include, {'href': href})
 
 if args.top is not None:
     top = args.top
 else:
-    top = yj.get_top()
-tmod = yj.get_module(top)
+    top = yj.top
+tmod = yj.module(top)
 
-def make_pb_type(mod, xml_parent = None):
-    cname_to_pb_name = dict()
-
+def make_pb_content(mod, xml_parent):
+    """Build the pb_type content - child pb_types, timing and direct interconnect,
+    but not IO. This may be put directly inside <pb_type>, or inside <mode>."""
     def get_full_pin_name(pin):
         cname, cellpin = pin
-        if cname != mod.get_name():
-            cname = cname_to_pb_name[cname]
+        if cname != mod.name:
+            cname = mod.cell_type(cname)
         return ("%s.%s" % (cname, cellpin))
 
     def make_direct_conn(ic_xml, source, dest):
         source_pin = get_full_pin_name(source)
         dest_pin = get_full_pin_name(dest)
-        # TODO: should we use this, or determine a net name from the Verilog?
-        ic_name = source_pin.replace(".","_") + "_to_" + dest_pin.replace(".","_")
+        ic_name = dest_pin.replace(".","_")
         dir_xml = ET.SubElement(ic_xml, 'direct', {
             'name': ic_name,
             'input': source_pin,
             'output': dest_pin
         })
+    # List of entries in format ((from_cell, from_pin), (to_cell, to_pin))
+    interconn = []
 
-    attrs = mod.get_module_attrs()
+    # Process cells. First build the list of cnames.
+    for cname, i_of in mod.cells:
+        pb_name = i_of
+        module_path = os.path.dirname(yj.get_module_file(i_of))
+        pb_type_path = "%s/pb_type.xml" % module_path
+        include_xml(xml_parent, pb_type_path)
+        # In order to avoid overspecifying interconnect, there are two directions we currently
+        # consider. All interconnect going INTO a cell, and interconnect going out of a cell
+        # into a top level output - or all outputs if "mode" is used.
+        inp_cons = mod.cell_conns(cname, "input")
+        for pin, net in inp_cons:
+            drvs = mod.net_drivers(net)
+            if len(drvs) == 0:
+                print("ERROR: pin %s.%s has no driver, interconnect will be missing" % (pb_name, pin))
+                assert False
+            elif len(drvs) > 1:
+                print("ERROR: pin %s.%s has multiple drivers, interconnect will be overspecified" % (pb_name, pin))
+                assert False
+            for drv_cell, drv_pin in drvs:
+                interconn.append(((drv_cell, drv_pin), (cname, pin)))
+
+        out_cons = mod.cell_conns(cname, "output")
+        for pin, net in out_cons:
+            sinks = mod.net_sinks(net)
+            for sink_cell, sink_pin in sinks:
+                if sink_cell == mod.name:
+                     #Only consider outputs from cell to top level IO. Inputs to other cells will be dealt with
+                     #in those cells.
+                    interconn.append(((cname, pin), (sink_cell, sink_pin)))
+
+    ic_xml = ET.SubElement(xml_parent, "interconnect")
+    # Process interconnect
+    for source, dest in interconn:
+        make_direct_conn(ic_xml, source, dest)
+
+
+def make_pb_type(mod):
+    """Build the pb_type for a given module. mod is the YosysModule object to
+    generate."""
+
+    attrs = mod.module_attrs
     pb_xml_attrs = dict()
 
-    pb_xml_attrs["name"] = mod.get_attr("PB_NAME", mod.get_name())
+    pb_xml_attrs["name"] = mod.name
 
     # Process type and class of module
-    mod_type = mod.get_attr("TYPE", "blackbox") #TODO: is blackbox a good default?
-    mod_cls = mod.get_attr("CLASS")
+    mod_type = mod.attr("TYPE")
+    mod_cls = mod.attr("CLASS")
     if mod_type == "bel":
         assert mod_cls is not None
         if mod_cls == "lut":
@@ -111,31 +156,24 @@
         else:
             assert False
     elif mod_type == "blackbox":
-        pb_xml_attrs["blif_model"] = ".subckt " + mod.get_name()
+        pb_xml_attrs["blif_model"] = ".subckt " + mod.name
         if mod_cls is not None:
             if mod_cls == "mem":
                 pb_xml_attrs["class"] = "memory"
             else:
                 assert False
+    elif mod_type is None:
+        pass
     else:
         assert False
 
     #TODO: might not always be the case? should be use Verilog `generate`s to detect this?
     pb_xml_attrs["num_pb"] = "1"
-
-    if xml_parent is None:
-        pb_type_xml = ET.Element("pb_type", pb_xml_attrs)
-    else:
-        pb_type_xml = ET.SubElement(xml_parent, "pb_type", pb_xml_attrs)
-
-    # List of entries in format ((from_cell, from_pin), (to_cell, to_pin))
-    interconn = []
-    # List of interconnect to ignore, because it was generated inside a <mode>
-    ignore_interconn = []
+    pb_type_xml = ET.Element("pb_type", pb_xml_attrs, nsmap = {'xi': xi_url})
 
     # Process IOs
-    clocks = yosys.run.list_clocks(args.infiles, mod.get_name())
-    for name, width, iodir in mod.get_ports():
+    clocks = yosys.run.list_clocks(args.infiles, mod.name)
+    for name, width, iodir in mod.ports:
         ioattrs = {"name": name, "num_pins": str(width), "equivalent": "false"}
         if name in clocks:
             ET.SubElement(pb_type_xml, "clock", ioattrs)
@@ -145,61 +183,20 @@
             ET.SubElement(pb_type_xml, "output", ioattrs)
         else:
             assert False
-    # Process cells. First build the list of cnames.
-    for cname, i_of in mod.get_cells(False):
-        cname_to_pb_name[cname] = mod.get_cell_attr(cname, "PB_NAME", i_of)
 
-    for cname, i_of in mod.get_cells(False):
-        pb_name = mod.get_cell_attr(cname, "PB_NAME", i_of)
-        module_path = os.path.dirname(yj.get_module_file(i_of))
-        pb_type_path = "%s/pb_type.xml" % module_path
-        pb_mode = mod.get_cell_attr(cname, "MODE", "")
-        # If MODE is used, need to wrap cell pb_type and interconnect in "mode"
-        is_modal = (pb_mode != "")
-        if is_modal:
-            mode_xml = ET.SubElement(pb_type_xml, "mode", {'name': pb_mode})
-            ET.SubElement(mode_xml, "{http://www.w3.org/2001/XInclude}include", {'href': pb_type_path})
-            mode_ic = ET.SubElement(mode_xml, "interconn")
-        else:
-            ET.SubElement(pb_type_xml, "{http://www.w3.org/2001/XInclude}include", {'href': pb_type_path})
-        # In order to avoid overspecifying interconnect, there are two directions we currently
-        # consider. All interconnect going INTO a cell, and interconnect going out of a cell
-        # into a top level output - or all outputs if "mode" is used.
-        inp_cons = mod.get_cell_conns(cname, "input")
-        for pin, net in inp_cons:
-            drvs = mod.get_net_drivers(net)
-            if len(drvs) == 0:
-                print("WARNING: pin %s.%s has no driver, interconnect will be missing" % (pb_name, pin))
-            elif len(drvs) > 1:
-                print("WARNING: pin %s.%s has multiple drivers, interconnect will be overspecified" % (pb_name, pin))
-            for drv_cell, drv_pin in drvs:
-                 # When mode is used, interconnect goes directly in the <mode>
-                if is_modal:
-                    make_direct_conn(mode_ic, (drv_cell, drv_pin), (cname, pin))
-                    ignore_interconn.append(((drv_cell, drv_pin), (cname, pin)))
-                else:
-                    interconn.append(((drv_cell, drv_pin), (cname, pin)))
+    modes = yj.modules_with_attr("ALTERNATIVE_TO", mod.name)
 
-        out_cons = mod.get_cell_conns(cname, "output")
-        for pin, net in out_cons:
-            sinks = mod.get_net_sinks(net)
-            for sink_cell, sink_pin in sinks:
-                if is_modal: # When mode is used, interconnect goes directly in the <mode>. Also, all sinks are considered
-                    make_direct_conn(mode_ic, (cname, pin), (sink_cell, sink_pin))
-                    ignore_interconn.append(((cname, pin), (sink_cell, sink_pin)))
-                elif sink_cell == mod.get_name():
-                    interconn.append(((cname, pin), (sink_cell, sink_pin)))
+    if len(modes) > 0:
+        for mode_mod in modes:
+            mode_xml = ET.SubElement(pb_type_xml, "mode", {"name" : mode_mod.name})
+            make_pb_content(mode_mod, mode_xml)
+    else:
+        make_pb_content(mod, pb_type_xml)
 
-    ic_xml = ET.SubElement(pb_type_xml, "interconnect")
-    # Process interconnect
-    for source, dest in interconn:
-        if (source, dest) not in ignore_interconn:
-            make_direct_conn(ic_xml, source, dest)
     # TODO: timing
-    # TODO: muxes
     return pb_type_xml
 
-pb_type_xml = make_pb_type(tmod, None)
+pb_type_xml = make_pb_type(tmod)
 
 outfile = "pb_type.xml"
 if "o" in args and args.o is not None:
diff --git a/yosys/json.py b/yosys/json.py
index c443692..517b465 100755
--- a/yosys/json.py
+++ b/yosys/json.py
@@ -14,44 +14,71 @@
         self.name = name
         self.data = module_data
 
-    # Return the name of the module
-    def get_name(self):
-        return self.name
+    @property
+    def ports(self):
+        """List of ports on a module.
 
-    # Return a list of ports of a module (default: top), as a 3-tuple (name, width, dir)
-    def get_ports(self):
+        Returns a list of tuples:
+        -------
+        name : str
+        width : int
+            The width in bits
+        dir : str
+            The direction, should be either `input` or `output`
+        """
         plist = []
         for port, pdata in self.data["ports"].items():
             plist.append((port, len(pdata["bits"]), pdata["direction"]))
         return plist
 
-    # Return a list of cells of a module, as a 2-tuple (name, type)
-    def get_cells(self, include_internal = False):
+    @property
+    def cells(self):
+        """List of cells of a module, excluding Yosys-internal cells
+        beginning with $.
+
+        Returns a list of tuples:
+        -------
+        name : str
+        type: str
+        """
         clist = []
         for cell, cdata in self.data["cells"].items():
-            if cell.startswith("$") and not include_internal:
+            if cell.startswith("$"):
                 continue
             clist.append((cell, cdata["type"]))
         return clist
-    # Return the attributes of a module as a dictionary
-    def get_module_attrs(self):
+
+    def cell_type(self, cell):
+        """Return the type of a given cell"""
+        for cname, cdata in self.data["cells"].items():
+            if cname == cell:
+                return cdata["type"]
+        return None
+
+    @property
+    def module_attrs(self):
+        """All attributes of a module as a dictionary"""
         return self.data["attributes"]
 
-    # Return the value of an attribute, or the default value if not set
-    def get_attr(self, attr, defval = None):
-        if attr in self.get_module_attrs():
-            return self.get_module_attrs()[attr]
+    def attr(self, attr, defval = None):
+        """Get an attribute, or defval is not set"""
+        if attr in self.module_attrs:
+            return self.module_attrs[attr]
         else:
             return defval
 
-    # Return the attributes of a cell instance as a dictionary
-    def get_cell_attrs(self, cell):
+    def has_attr(self, attr):
+        """Return true if an attribute exists"""
+        return attr in self.module_attrs
+
+    def cell_attrs(self, cell):
+        """All attributes of a given cell as a dictionary"""
         return self.data["cells"][cell]["attributes"]
 
-    # Return the value of an attribute of a cell, or the default value if not set
-    def get_cell_attr(self, cell, attr, defval = None):
-        if attr in self.get_cell_attrs(cell):
-            return self.get_cell_attrs(cell)[attr]
+    def cell_attr(self, cell, attr, defval = None):
+        """Get an attribute of a given cell, or defval is not set"""
+        if attr in self.cell_attrs(cell):
+            return self.cell_attrs(cell)[attr]
         else:
             return defval
 
@@ -59,8 +86,14 @@
     # specifications are inconsistent in how they are represented in the JSON,
     # it's hard to make any nicer...
 
-    # Return cell connections in a given direction as a 2-tuple (cell pin name, module net number)
-    def get_cell_conns(self, cell, direction = "input"):
+    def cell_conns(self, cell, direction = "input"):
+        """The connections of a cell in a given direction as a 2-tuple
+
+        Returns a list of tuples:
+        -------
+        port : str
+        net : int
+        """
         cdata = self.data["cells"][cell]
         conns = []
         for port, condata in cdata["connections"].items():
@@ -73,10 +106,13 @@
                         conns.append(("%s[%d]" % (port, N), condata[i]))
         return conns
 
-    # Returns any top level IO matching a direction and connected net number
-    # Result is a list containing entries of the form A or A[15] for single bit
-    # or bus ports respectively
-    def get_conn_io(self, net, iodir):
+    def conn_io(self, net, iodir):
+        """Returns a list of top level IO matching a direction and connected net number
+
+        Returns a list:
+        -------
+        port : str
+        """
         conn_io = []
         for port, pdata in self.data["ports"].items():
             if pdata["direction"] == iodir:
@@ -87,12 +123,17 @@
                         conn_io.append("%s[%d]" % (port, pdata["bits"].index(net)))
         return conn_io
 
-    # Returns any cell ports matching a direction and connected net number
-    # Result is a list of tuples (cell, port)
-    def get_conn_ports(self, net, pdir, include_internal = False):
+    def conn_ports(self, net, pdir):
+        """Returns any cell ports matching a direction and connected net number
+
+        Returns a list of tuples:
+        -------
+        cell : str
+        port : str
+        """
         conn_ports = []
         for cell in self.data["cells"]:
-            if cell.startswith("$") and not include_internal:
+            if cell.startswith("$"):
                 continue
             cdata = self.data["cells"][cell]
             for port, condata in cdata["connections"].items():
@@ -104,24 +145,43 @@
                             conn_ports.append((cell, "%s[%d]" % (port, condata.index(net))))
         return conn_ports
 
-    # Return a list of drivers of a net (usually should only be one...) as a 2-tuple
-    # (cell, port). cell is set to the name of the module for top level IOs
-    def get_net_drivers(self, net):
+
+    def net_drivers(self, net):
+        """Returns a list of drivers of a given net, both top level inputs.
+        and cell outputs. "cell" is set to the name of the module for top level
+        IO.
+
+        Returns a list of tuples:
+        -------
+        cell : str
+        port : str
+        """
         # top level *inputs* and cell outputs are both drivers
-        io_drivers = [(self.name, _) for _ in self.get_conn_io(net, "input")]
-        cell_drivers = self.get_conn_ports(net, "output")
+        io_drivers = [(self.name, _) for _ in self.conn_io(net, "input")]
+        cell_drivers = self.conn_ports(net, "output")
         return io_drivers + cell_drivers
 
-    # Return a list of sinks of a net, as a 2-tuple as above
-    def get_net_sinks(self, net):
+    def net_sinks(self, net):
+        """Returns a list of sinks of a given net, both top level outputs.
+        and cell inputs. "cell" is set to the name of the module for top level
+        IO.
+
+        Returns a list of tuples:
+        -------
+        cell : str
+        port : str
+        """
         # top level *outputs* and cell inputs are both drivers
-        io_drivers = [(self.name, _) for _ in self.get_conn_io(net, "output")]
-        cell_drivers = self.get_conn_ports(net, "input")
+        io_drivers = [(self.name, _) for _ in self.conn_io(net, "output")]
+        cell_drivers = self.conn_ports(net, "input")
         return io_drivers + cell_drivers
+
 class YosysJson:
-    # Takes either a filename, or already parsed JSON as a dictionary
-    # Also optionally pass the top level module
+
     def __init__(self, j, top = None):
+        """Takes either the filename to a JSON file, or already parsed JSON
+        data as a dictionary. Optionally the top level module can be specified
+        too."""
         if(isinstance(j, str)):
             with open(j, 'r') as f:
                 self.data = json.load(f)
@@ -135,27 +195,30 @@
         else:
             self.top = top
 
-    # Get the name of the top level module
-    def get_top(self):
-        if self.top is None:
-            print("no top module selected")
-            assert(False)
-        return self.top
-
-    # Get a given module (by name) as a YosysModule
-    def get_module(self, module):
+    def module(self, module):
+        """Get a given module (by name) as a `YosysModule`"""
         return YosysModule(module, self.data["modules"][module])
 
-    # Get the top module (by name) as a YosysModule
-    def get_top_module(self):
-        return self.get_module(self.get_top())
+    def modules_with_attr(self, attr_name, attr_value):
+        """Return a list of `YosysModule`s, selecting based on a given attribute"""
+        mods = []
+        for mod in self.data["modules"]:
+            ymod = self.module(mod)
+            if ymod.has_attr(attr_name) and ymod.attr(attr_name) == attr_value:
+                mods.append(ymod)
+        return mods
 
-    # Return true if a module exists
+    @property
+    def top_module(self):
+        """Get a given module (by name) as a `YosysModule`"""
+        return self.module(self.top)
+
     def has_module(self, module):
+        """Return true if a module exists"""
         return module in self.data["modules"]
 
-    # Return the filename in which a given module lives
     def get_module_file(self, module):
-        src = self.get_module(module).get_attr("src")
+        """Return the filename in which a given module lives"""
+        src = self.module(module).attr("src")
         cpos = src.rfind(":")
         return src[0:cpos]
diff --git a/yosys/run.py b/yosys/run.py
index f45a3a6..de471d9 100755
--- a/yosys/run.py
+++ b/yosys/run.py
@@ -18,6 +18,15 @@
     return yosys_get_output(params)
 
 def vlog_to_json(infiles, flatten = False, aig = False):
+    """
+    Convert Verilog to a JSON representation using Yosys
+
+    Inputs
+    -------
+    infiles : list of input files
+    flatten : set to flatten output hierarchy
+    aig : generate And-Inverter-Graph modules for gates
+    """
     prep_opts = "-flatten" if flatten else ""
     json_opts = "-aig" if aig else ""
     cmds = "prep %s; write_json %s" % (prep_opts, json_opts)
@@ -26,10 +35,11 @@
         print(j,file=dbg)"""
     return json.loads(j)
 
-"""
-Extract the pin from a line of the result of a Yosys select command
-"""
+
 def extract_pin(module, pstr, _regex=re.compile(r"([^/]+)/([^/]+)")):
+    """
+    Extract the pin from a line of the result of a Yosys select command
+    """
     m = re.match(r"([^/]+)/([^/]+)", pstr)
     if m and m.group(1) == module:
         return m.group(2)
@@ -37,16 +47,18 @@
         return None
 
 
-"""
-Run a Yosys select command (given the expression and input files) on a module
-and return the result as a list of pins
 
-TODO: All of these functions involve a fairly large number of calls to Yosys
-Although performance here is unlikely to be a major priority any time soon,
-it might be worth investigating better options?
-
-"""
 def do_select(infiles, module, expr):
+    """
+    Run a Yosys select command (given the expression and input files) on a module
+    and return the result as a list of pins
+    """
+
+    """TODO: All of these functions involve a fairly large number of calls to Yosys
+    Although performance here is unlikely to be a major priority any time soon,
+    it might be worth investigating better options?"""
+
+
     outfile = tempfile.mktemp()
     sel_cmd = "prep -top %s -flatten; cd %s; select -write %s %s" % (module, module, outfile, expr)
     yosys_commands(sel_cmd, infiles)
@@ -62,10 +74,14 @@
     return pins
 
 def get_combinational_sinks(infiles, module, innet):
+    """Return a list of output ports which are combinational sinks of a given
+    input."""
     return do_select(infiles, module, "%s %%coe* o:* %%i %s %%d" % (innet, innet))
 
 def list_clocks(infiles, module):
+    """Return a list of clocks in the module"""
     return do_select(infiles, module, "c:* %x:+[CLK] c:* %d")
 
 def get_clock_assoc_signals(infiles, module, clk):
+    """Return the list of signals associated with a given clock."""
     return do_select(infiles, module, "select -list %s %%x* i:* o:* %%u %%i %s %%d" % (clk, clk))