Rename Mux2xNone to Mux2 and change decorator to m.circuit.combinational

doc/circuit_definitions.md

@@ -1,7 +1,7 @@
-# Circuit Definitions
-Circuit defintions can be marked with the `@m.circuit_def` decorator.
-This introduces a set of syntax level features for magma circuit definitions,
-including the use of `if` statements to generate `Mux`es.
+# Combinational Circuit Definitions
+Circuit defintions can be marked with the `@m.circuit.combinational` decorator.
+This introduces a set of syntax level features for defining combinational magma
+circuits, including the use of `if` statements to generate `Mux`es.
 
 This feature is currently experimental, and therefor expect bugs to occur.
 Please file any issues on the magma GitHub repository.
@@ -13,7 +13,7 @@ Basic example:
 ```python
 class IfStatementBasic(m.Circuit):
     IO = ["I", m.In(m.Bits(2)), "S", m.In(m.Bit), "O", m.Out(m.Bit)]
-     @m.circuit_def
+     @m.circuit.combinational
     def definition(io):
         if io.S:
             O = io.I[0]
@@ -27,7 +27,7 @@ Basic nesting:
 ```python
 class IfStatementNested(m.Circuit):
     IO = ["I", m.In(m.Bits(4)), "S", m.In(m.Bits(2)), "O", m.Out(m.Bit)]
-     @m.circuit_def
+     @m.circuit.combinational
     def definition(io):
         if io.S[0]:
             if io.S[1]:
@@ -46,7 +46,7 @@ Terneray expressions
 ```python
 class Ternary(m.Circuit):
     IO = ["I", m.In(m.Bits(2)), "S", m.In(m.Bit), "O", m.Out(m.Bit)]
-     @m.circuit_def
+     @m.circuit.combinational
     def definition(io):
         m.wire(io.O, io.I[0] if io.S else io.I[1])
 ```
@@ -55,7 +55,7 @@ Nesting terneray expressions
 ```python
 class TernaryNested(m.Circuit):
     IO = ["I", m.In(m.Bits(3)), "S", m.In(m.Bits(2)), "O", m.Out(m.Bit)]
-     @m.circuit_def
+     @m.circuit.combinational
     def definition(io):
         m.wire(io.O,
                io.I[0] if io.S[0] else io.I[1] if io.S[1] else io.I[2])

magma/__init__.py

@@ -55,6 +55,3 @@ def set_mantle_target(t):
      if mantle_target is not None and mantle_target != t:
          warning('changing mantle target', mantle_target, t )
      mantle_target = t
-
-
-from .circuit_def import circuit_def

magma/circuit.py

@@ -547,3 +547,5 @@ def wrapped(*args, **kwargs):
         result._generator_arguments = GeneratorArguments(args, kwargs)
         return result
     return wrapped
+
+from magma.circuit_def import combinational

magma/circuit_def.py

@@ -3,9 +3,8 @@
 import inspect
 import textwrap
 from collections import OrderedDict
-from magma.logging import warning
+from magma.logging import warning, debug
 import astor
-import inspect
 
 
 class CircuitDefinitionSyntaxError(Exception):
@@ -80,7 +79,7 @@ def visit_IfExp(self, node):
             [])
 
 
-def circuit_def(fn):
+def combinational(fn):
     stack = inspect.stack()
     defn_locals = stack[1].frame.f_locals
     defn_globals = stack[1].frame.f_globals
@@ -89,7 +88,7 @@ def circuit_def(fn):
     tree = ast.fix_missing_locations(tree)
     # TODO: Only remove @m.circuit_def, there could be others
     tree.body[0].decorator_list = []
-    # print(astor.to_source(tree))
+    debug(astor.to_source(tree))
     exec(compile(tree, filename="<ast>", mode="exec"), defn_globals,
          defn_locals)
 

magma/logging.py

@@ -25,6 +25,10 @@ def get_original_wire_call_stack_frame():
         return frame.frame
 
 
+def debug(message, *args, **kwargs):
+    log.debug(message, *args, **kwargs)
+
+
 def info(message, *args, **kwargs):
     log.info(message, *args, **kwargs)
 
@@ -43,3 +47,4 @@ def error(message, include_wire_traceback=False, *args, **kwargs):
     print(message, file=sys.stderr, *args, **kwargs)
     if include_wire_traceback:
         sys.stderr.write("="*80 + "\n")
+

tests/gold/test_if_statement_basic.v

@@ -1,6 +1,6 @@
 module TestIfStatementBasic (input [1:0] I, input  S, output  O);
 wire  inst0_O;
-Mux2xNone inst0 (.I0(I[0]), .I1(I[1]), .S(S), .O(inst0_O));
+Mux2 inst0 (.I0(I[0]), .I1(I[1]), .S(S), .O(inst0_O));
 assign O = inst0_O;
 endmodule
 

tests/gold/test_if_statement_nested.v

@@ -2,9 +2,9 @@ module TestIfStatementNested (input [3:0] I, input [1:0] S, output  O);
 wire  inst0_O;
 wire  inst1_O;
 wire  inst2_O;
-Mux2xNone inst0 (.I0(I[0]), .I1(I[1]), .S(S[1]), .O(inst0_O));
-Mux2xNone inst1 (.I0(I[2]), .I1(I[3]), .S(S[1]), .O(inst1_O));
-Mux2xNone inst2 (.I0(inst0_O), .I1(inst1_O), .S(S[0]), .O(inst2_O));
+Mux2 inst0 (.I0(I[0]), .I1(I[1]), .S(S[1]), .O(inst0_O));
+Mux2 inst1 (.I0(I[2]), .I1(I[3]), .S(S[1]), .O(inst1_O));
+Mux2 inst2 (.I0(inst0_O), .I1(inst1_O), .S(S[0]), .O(inst2_O));
 assign O = inst2_O;
 endmodule
 

tests/gold/test_ternary.v

@@ -1,6 +1,6 @@
 module TestTernary (input [1:0] I, input  S, output  O);
 wire  inst0_O;
-Mux2xNone inst0 (.I0(I[0]), .I1(I[1]), .S(S), .O(inst0_O));
+Mux2 inst0 (.I0(I[0]), .I1(I[1]), .S(S), .O(inst0_O));
 assign O = inst0_O;
 endmodule
 

tests/gold/test_ternary_nested.v

@@ -1,8 +1,8 @@
 module TestTernaryNested (input [2:0] I, input [1:0] S, output  O);
 wire  inst0_O;
 wire  inst1_O;
-Mux2xNone inst0 (.I0(I[1]), .I1(I[2]), .S(S[1]), .O(inst0_O));
-Mux2xNone inst1 (.I0(I[0]), .I1(inst0_O), .S(S[0]), .O(inst1_O));
+Mux2 inst0 (.I0(I[1]), .I1(I[2]), .S(S[1]), .O(inst0_O));
+Mux2 inst1 (.I0(I[0]), .I1(inst0_O), .S(S[0]), .O(inst1_O));
 assign O = inst1_O;
 endmodule
 

tests/gold/test_ternary_nested2.v

@@ -1,8 +1,8 @@
 module TestTernaryNested2 (input [2:0] I, input [1:0] S, output  O);
 wire  inst0_O;
 wire  inst1_O;
-Mux2xNone inst0 (.I0(I[0]), .I1(I[1]), .S(S[0]), .O(inst0_O));
-Mux2xNone inst1 (.I0(inst0_O), .I1(I[2]), .S(S[1]), .O(inst1_O));
+Mux2 inst0 (.I0(I[0]), .I1(I[1]), .S(S[0]), .O(inst0_O));
+Mux2 inst1 (.I0(inst0_O), .I1(I[2]), .S(S[1]), .O(inst1_O));
 assign O = inst1_O;
 endmodule
 

tests/test_circuit_def.py

@@ -20,7 +20,7 @@ def DefineMux(height=2, width=None):
     io += ['O', m.Out(T)]
 
     class _Mux(m.Circuit):
-        name = "Mux{}x{}".format(height, width)
+        name = f"Mux{height}" + (f"_x{width}" if width else "")
         IO = io
     return _Mux
 
@@ -50,7 +50,7 @@ def test_if_statement_basic():
     class TestIfStatementBasic(m.Circuit):
         IO = ["I", m.In(m.Bits(2)), "S", m.In(m.Bit), "O", m.Out(m.Bit)]
 
-        @m.circuit_def
+        @m.circuit.combinational
         def definition(io):
             if io.S:
                 O = io.I[0]
@@ -72,7 +72,7 @@ def test_if_statement_nested():
     class TestIfStatementNested(m.Circuit):
         IO = ["I", m.In(m.Bits(4)), "S", m.In(m.Bits(2)), "O", m.Out(m.Bit)]
 
-        @m.circuit_def
+        @m.circuit.combinational
         def definition(io):
             if io.S[0]:
                 if io.S[1]:
@@ -100,7 +100,7 @@ def test_ternary():
     class TestTernary(m.Circuit):
         IO = ["I", m.In(m.Bits(2)), "S", m.In(m.Bit), "O", m.Out(m.Bit)]
 
-        @m.circuit_def
+        @m.circuit.combinational
         def definition(io):
             m.wire(io.O, io.I[0] if io.S else io.I[1])
             # io.O = io.I[0] if io.S else io.I[1]
@@ -115,7 +115,7 @@ def test_ternary_nested():
     class TestTernaryNested(m.Circuit):
         IO = ["I", m.In(m.Bits(3)), "S", m.In(m.Bits(2)), "O", m.Out(m.Bit)]
 
-        @m.circuit_def
+        @m.circuit.combinational
         def definition(io):
             m.wire(io.O,
                    io.I[0] if io.S[0] else io.I[1] if io.S[1] else io.I[2])
@@ -131,7 +131,7 @@ def test_ternary_nested2():
     class TestTernaryNested2(m.Circuit):
         IO = ["I", m.In(m.Bits(3)), "S", m.In(m.Bits(2)), "O", m.Out(m.Bit)]
 
-        @m.circuit_def
+        @m.circuit.combinational
         def definition(io):
             m.wire(io.O,
                    (io.I[0] if io.S[0] else io.I[1]) if io.S[1] else io.I[2])