hdl.ir: rename .get_fragment() to .elaborate().

Closes #9.
m-labs · Jan 26, 2019 · 4948162 · 4948162 · alsrgv · Feb 23, 2019
1 parent 4922a73
commit 4948162
Show file tree

Hide file tree

Showing 28 changed files with 108 additions and 88 deletions.
diff --git a/examples/alu.py b/examples/alu.py
@@ -10,7 +10,7 @@ def __init__(self, width):
         self.o   = Signal(width)
         self.co  = Signal()
 
-    def get_fragment(self, platform):
+    def elaborate(self, platform):
         m = Module()
         with m.If(self.sel == 0b00):
             m.d.comb += self.o.eq(self.a | self.b)
@@ -20,7 +20,7 @@ def get_fragment(self, platform):
             m.d.comb += self.o.eq(self.a ^ self.b)
         with m.Else():
             m.d.comb += Cat(self.o, self.co).eq(self.a - self.b)
-        return m.lower(platform)
+        return m
 
 
 if __name__ == "__main__":

diff --git a/examples/alu_hier.py b/examples/alu_hier.py
@@ -8,10 +8,10 @@ def __init__(self, width):
         self.b   = Signal(width)
         self.o   = Signal(width)
 
-    def get_fragment(self, platform):
+    def elaborate(self, platform):
         m = Module()
         m.d.comb += self.o.eq(self.a + self.b)
-        return m.lower(platform)
+        return m
 
 
 class Subtractor:
@@ -20,10 +20,10 @@ def __init__(self, width):
         self.b   = Signal(width)
         self.o   = Signal(width)
 
-    def get_fragment(self, platform):
+    def elaborate(self, platform):
         m = Module()
         m.d.comb += self.o.eq(self.a - self.b)
-        return m.lower(platform)
+        return m
 
 
 class ALU:
@@ -36,7 +36,7 @@ def __init__(self, width):
         self.add = Adder(width)
         self.sub = Subtractor(width)
 
-    def get_fragment(self, platform):
+    def elaborate(self, platform):
         m = Module()
         m.submodules.add = self.add
         m.submodules.sub = self.sub
@@ -50,7 +50,7 @@ def get_fragment(self, platform):
             m.d.comb += self.o.eq(self.sub.o)
         with m.Else():
             m.d.comb += self.o.eq(self.add.o)
-        return m.lower(platform)
+        return m
 
 
 if __name__ == "__main__":

diff --git a/examples/arst.py b/examples/arst.py
@@ -7,15 +7,15 @@ def __init__(self, factor):
         self.v = Signal(factor)
         self.o = Signal()
 
-    def get_fragment(self, platform):
+    def elaborate(self, platform):
         m = Module()
         m.d.sync += self.v.eq(self.v + 1)
         m.d.comb += self.o.eq(self.v[-1])
-        return m.lower(platform)
+        return m
 
 
 if __name__ == "__main__":
     ctr  = ClockDivisor(factor=16)
-    frag = ctr.get_fragment(platform=None)
+    frag = ctr.elaborate(platform=None)
     frag.add_domains(ClockDomain("sync", async_reset=True))
     main(frag, ports=[ctr.o])
diff --git a/examples/ctr.py b/examples/ctr.py
@@ -7,11 +7,11 @@ def __init__(self, width):
         self.v = Signal(width, reset=2**width-1)
         self.o = Signal()
 
-    def get_fragment(self, platform):
+    def elaborate(self, platform):
         m = Module()
         m.d.sync += self.v.eq(self.v + 1)
         m.d.comb += self.o.eq(self.v[-1])
-        return m.lower(platform)
+        return m
 
 
 ctr = Counter(width=16)

diff --git a/examples/ctr_ce.py b/examples/ctr_ce.py
@@ -8,15 +8,15 @@ def __init__(self, width):
         self.o = Signal()
         self.ce = Signal()
 
-    def get_fragment(self, platform):
+    def elaborate(self, platform):
         m = Module()
         m.d.sync += self.v.eq(self.v + 1)
         m.d.comb += self.o.eq(self.v[-1])
         return CEInserter(self.ce)(m.lower(platform))
 
 
 ctr  = Counter(width=16)
-frag = ctr.get_fragment(platform=None)
+frag = ctr.elaborate(platform=None)
 
 # print(rtlil.convert(frag, ports=[ctr.o, ctr.ce]))
 print(verilog.convert(frag, ports=[ctr.o, ctr.ce]))

diff --git a/examples/fsm.py b/examples/fsm.py
@@ -12,7 +12,7 @@ def __init__(self, divisor):
         self.ack  = Signal()
         self.err  = Signal()
 
-    def get_fragment(self, platform):
+    def elaborate(self, platform):
         m = Module()
 
         ctr = Signal(max=self.divisor)
@@ -56,7 +56,7 @@ def get_fragment(self, platform):
             with m.State("ERROR"):
                 pass
 
-        return m.lower(platform)
+        return m
 
 
 if __name__ == "__main__":

diff --git a/examples/gpio.py b/examples/gpio.py
@@ -8,12 +8,12 @@ def __init__(self, pins, bus):
         self.pins = pins
         self.bus  = bus
 
-    def get_fragment(self, platform):
+    def elaborate(self, platform):
         m = Module()
         m.d.comb += self.bus.r_data.eq(self.pins[self.bus.addr])
         with m.If(self.bus.we):
             m.d.sync += self.pins[self.bus.addr].eq(self.bus.w_data)
-        return m.lower(platform)
+        return m
 
 
 if __name__ == "__main__":

diff --git a/examples/inst.py b/examples/inst.py
@@ -9,7 +9,7 @@ def __init__(self):
         self.dat_w = Signal(8)
         self.we    = Signal()
 
-    def get_fragment(self, platform):
+    def elaborate(self, platform):
         m = Module()
         m.submodules.cpu = Instance("CPU",
             p_RESET_ADDR=0xfff0,
@@ -18,7 +18,7 @@ def get_fragment(self, platform):
             o_d_dat_w=self.dat_w,
             i_d_we   =self.we,
         )
-        return m.lower(platform)
+        return m
 
 
 if __name__ == "__main__":

diff --git a/examples/mem.py b/examples/mem.py
@@ -10,7 +10,7 @@ def __init__(self):
         self.we    = Signal()
         self.mem   = Memory(width=8, depth=16, init=[0xaa, 0x55])
 
-    def get_fragment(self, platform):
+    def elaborate(self, platform):
         m = Module()
         m.submodules.rdport = rdport = self.mem.read_port()
         m.submodules.wrport = wrport = self.mem.write_port()
@@ -21,7 +21,7 @@ def get_fragment(self, platform):
             wrport.data.eq(self.dat_w),
             wrport.en.eq(self.we),
         ]
-        return m.lower(platform)
+        return m
 
 
 if __name__ == "__main__":

diff --git a/examples/pmux.py b/examples/pmux.py
@@ -10,7 +10,7 @@ def __init__(self, width):
         self.c = Signal(width)
         self.o = Signal(width)
 
-    def get_fragment(self, platform):
+    def elaborate(self, platform):
         m = Module()
         with m.Switch(self.s):
             with m.Case("--1"):
@@ -21,7 +21,7 @@ def get_fragment(self, platform):
                 m.d.comb += self.o.eq(self.c)
             with m.Case():
                 m.d.comb += self.o.eq(0)
-        return m.lower(platform)
+        return m
 
 
 if __name__ == "__main__":

diff --git a/nmigen/back/pysim.py b/nmigen/back/pysim.py
@@ -347,7 +347,7 @@ def run(state):
 
 class Simulator:
     def __init__(self, fragment, vcd_file=None, gtkw_file=None, traces=()):
-        self._fragment        = fragment
+        self._fragment        = Fragment.get(fragment, platform=None)
 
         self._signal_slots    = SignalDict()  # Signal -> int/slot
         self._slot_signals    = list()        # int/slot -> Signal
@@ -386,9 +386,6 @@ def __init__(self, fragment, vcd_file=None, gtkw_file=None, traces=()):
 
         self._run_called      = False
 
-        while not isinstance(self._fragment, Fragment):
-            self._fragment = self._fragment.get_fragment(platform=None)
-
     @staticmethod
     def _check_process(process):
         if inspect.isgeneratorfunction(process):

diff --git a/nmigen/cli.py b/nmigen/cli.py
@@ -1,5 +1,6 @@
 import argparse
 
+from .hdl.ir import Fragment
 from .back import rtlil, verilog, pysim
 
 
@@ -42,7 +43,7 @@ def main_parser(parser=None):
 
 def main_runner(parser, args, design, platform=None, name="top", ports=()):
     if args.action == "generate":
-        fragment = design.get_fragment(platform=platform)
+        fragment = Fragment.get(design, platform)
         generate_type = args.generate_type
         if generate_type is None and args.generate_file:
             if args.generate_file.name.endswith(".v"):
@@ -61,7 +62,7 @@ def main_runner(parser, args, design, platform=None, name="top", ports=()):
             print(output)
 
     if args.action == "simulate":
-        fragment = design.get_fragment(platform=platform)
+        fragment = Fragment.get(design, platform)
         with pysim.Simulator(fragment,
                 vcd_file=args.vcd_file,
                 gtkw_file=args.gtkw_file,

diff --git a/nmigen/compat/fhdl/specials.py b/nmigen/compat/fhdl/specials.py
@@ -57,7 +57,7 @@ def __init__(self, adr, dat_r, we=None, dat_w=None, async_read=False, re=None,
 
 @extend(NativeMemory)
 @deprecated("it is not necessary or permitted to add Memory as a special or submodule")
-def get_fragment(self, platform):
+def elaborate(self, platform):
     return Fragment()
 
 

diff --git a/nmigen/compat/fhdl/verilog.py b/nmigen/compat/fhdl/verilog.py
@@ -1,5 +1,6 @@
 import warnings
 
+from ...hdl import Fragment
 from ...back import verilog
 from .conv_output import ConvOutput
 
@@ -16,7 +17,7 @@ def convert(fi, ios=None, name="top", special_overrides=dict(),
     # TODO: attr_translate
 
     v_output = verilog.convert(
-        fragment=fi.get_fragment().get_fragment(platform=None),
+        fragment=Fragment.get(fi.get_fragment(), platform=None),
         name=name,
         ports=ios or (),
         ensure_sync_exists=create_clock_domains

diff --git a/nmigen/compat/sim/__init__.py b/nmigen/compat/sim/__init__.py
@@ -12,7 +12,7 @@ def run_simulation(fragment_or_module, generators, clocks={"sync": 10}, vcd_name
     assert not special_overrides
 
     if hasattr(fragment_or_module, "get_fragment"):
-        fragment = fragment_or_module.get_fragment().get_fragment(platform=None)
+        fragment = fragment_or_module.get_fragment()
     else:
         fragment = fragment_or_module
 

diff --git a/nmigen/hdl/dsl.py b/nmigen/hdl/dsl.py
@@ -3,7 +3,7 @@
 from contextlib import contextmanager
 import warnings
 
-from ..tools import flatten, bits_for
+from ..tools import flatten, bits_for, deprecated
 from .ast import *
 from .ir import *
 from .xfrm import *
@@ -367,9 +367,15 @@ def domain_name(domain):
             self._statements.append(assign)
 
     def _add_submodule(self, submodule, name=None):
-        if not hasattr(submodule, "get_fragment"):
-            raise TypeError("Trying to add '{!r}', which does not implement .get_fragment(), as "
-                            "a submodule".format(submodule))
+        if not hasattr(submodule, "elaborate"):
+            if hasattr(submodule, "get_fragment"): # :deprecated:
+                warnings.warn("Adding '{!r}', which implements .get_fragment() but not "
+                              ".elaborate(), as a submodule. .get_fragment() is deprecated, "
+                              "and .elaborate() should be provided instead.".format(submodule),
+                              DeprecationWarning, stacklevel=2)
+            else:
+                raise TypeError("Trying to add '{!r}', which does not implement .elaborate(), as "
+                                "a submodule".format(submodule))
         self._submodules.append((submodule, name))
 
     def _add_domain(self, cd):
@@ -379,18 +385,24 @@ def _flush(self):
         while self._ctrl_stack:
             self._pop_ctrl()
 
-    def lower(self, platform):
+    @deprecated("`m.get_fragment(...)` is deprecated; use `m` instead")
+    def get_fragment(self, platform): # :deprecated:
+        return self.elaborate(platform)
+
+    @deprecated("`m.lower(...)` is deprecated; use `m` instead")
+    def lower(self, platform): # :deprecated:
+        return self.elaborate(platform)
+
+    def elaborate(self, platform):
         self._flush()
 
         fragment = Fragment()
         for submodule, name in self._submodules:
-            fragment.add_subfragment(submodule.get_fragment(platform), name)
+            fragment.add_subfragment(Fragment.get(submodule, platform), name)
         statements = SampleDomainInjector("sync")(self._statements)
         fragment.add_statements(statements)
         for signal, domain in self._driving.items():
             fragment.add_driver(signal, domain)
         fragment.add_domains(self._domains)
         fragment.generated.update(self._generated)
         return fragment
-
-    get_fragment = lower
diff --git a/nmigen/hdl/ir.py b/nmigen/hdl/ir.py
@@ -14,6 +14,14 @@ class DriverConflict(UserWarning):
 
 
 class Fragment:
+    @staticmethod
+    def get(obj, platform):
+        if isinstance(obj, Fragment):
+            return obj
+        if not hasattr(obj, "elaborate"): # :deprecated:
+            return Fragment.get(obj.get_fragment(platform), platform)
+        return Fragment.get(obj.elaborate(platform), platform)
+
     def __init__(self):
         self.ports = SignalDict()
         self.drivers = OrderedDict()
@@ -105,7 +113,7 @@ def find_generated(self, *path):
             item, = path
             return self.generated[item]
 
-    def get_fragment(self, platform):
+    def elaborate(self, platform):
         return self
 
     def _merge_subfragment(self, subfragment):

diff --git a/nmigen/hdl/mem.py b/nmigen/hdl/mem.py
@@ -91,7 +91,7 @@ def __init__(self, memory, domain, synchronous, transparent):
         else:
             self.en = Const(1)
 
-    def get_fragment(self, platform):
+    def elaborate(self, platform):
         f = Instance("$memrd",
             p_MEMID=self.memory,
             p_ABITS=self.addr.nbits,
@@ -154,7 +154,7 @@ def __init__(self, memory, domain, priority, granularity):
         self.en   = Signal(memory.width // granularity,
                            name="{}_w_en".format(memory.name))
 
-    def get_fragment(self, platform):
+    def elaborate(self, platform):
         f = Instance("$memwr",
             p_MEMID=self.memory,
             p_ABITS=self.addr.nbits,

diff --git a/nmigen/lib/cdc.py b/nmigen/lib/cdc.py
@@ -14,12 +14,12 @@ def __init__(self, i, o, odomain="sync", n=2, reset=0):
                              reset=reset, reset_less=True, attrs={"no_retiming": True})
                       for i in range(n)]
 
-    def get_fragment(self, platform):
+    def elaborate(self, platform):
         if hasattr(platform, "get_multi_reg"):
             return platform.get_multi_reg(self)
 
         m = Module()
         for i, o in zip((self.i, *self._regs), self._regs):
             m.d[self.odomain] += o.eq(i)
         m.d.comb += self.o.eq(self._regs[-1])
-        return m.lower(platform)
+        return m