memory: add support for address space extension.

* MemoryMap.add_resource(extend=True) (resp. MemoryMap.add_window())
  can be used to add a resource (resp. window) that would otherwise not
  fit inside the memory map. The address space upper bound is raised
  accordingly, which increases addr_width.

* MemoryMap.freeze() can be called to prevent a memory map from being
  extended further. It must be called before the memory map is used to
  instantiate anything, because its public attributes must not change
  from then on.

Author: Jean-François Nguyen

nmigen_soc/memory.py

@@ -1,5 +1,7 @@
 import bisect
 
+from nmigen.utils import bits_for
+
 
 __all__ = ["MemoryMap"]
 
@@ -84,15 +86,50 @@ def __init__(self, *, addr_width, data_width, alignment=0):
             raise ValueError("Alignment must be a non-negative integer, not {!r}"
                              .format(alignment))
 
-        self.addr_width = addr_width
-        self.data_width = data_width
-        self.alignment  = alignment
+        self._addr_width = addr_width
+        self._data_width = data_width
+        self._alignment  = alignment
+
+        self._ranges     = _RangeMap()
+        self._resources  = dict()
+        self._windows    = dict()
+
+        self._next_addr  = 0
+        self._frozen     = False
+
+    @property
+    def addr_width(self):
+        return self._addr_width
 
-        self._ranges    = _RangeMap()
-        self._resources = dict()
-        self._windows   = dict()
+    @addr_width.setter
+    def addr_width(self, addr_width):
+        if self._frozen:
+            raise ValueError("Memory map has been frozen. Address width cannot be extended "
+                             "further")
+        if not isinstance(addr_width, int) or addr_width <= 0:
+            raise ValueError("Address width must be a positive integer, not {!r}"
+                             .format(addr_width))
+        if addr_width < self._addr_width:
+            raise ValueError("Address width {!r} must not be less than its previous value {!r}, "
+                             "because resources that were previously added may not fit anymore"
+                             .format(addr_width, self._addr_width))
+        self._addr_width = addr_width
 
-        self._next_addr = 0
+    @property
+    def data_width(self):
+        return self._data_width
+
+    @property
+    def alignment(self):
+        return self._alignment
+
+    def freeze(self):
+        """Freeze the memory map.
+
+        Once frozen, the memory map cannot be extended anymore. Resources and windows may
+        still be added, as long as they fit within the address space bounds.
+        """
+        self._frozen = True
 
     @staticmethod
     def _align_up(value, alignment):
@@ -119,7 +156,7 @@ def align_to(self, alignment):
         self._next_addr = self._align_up(self._next_addr, max(alignment, self.alignment))
         return self._next_addr
 
-    def _compute_addr_range(self, addr, size, step=1, *, alignment):
+    def _compute_addr_range(self, addr, size, step=1, *, alignment, extend):
         if addr is not None:
             if not isinstance(addr, int) or addr < 0:
                 raise ValueError("Address must be a non-negative integer, not {!r}"
@@ -137,9 +174,12 @@ def _compute_addr_range(self, addr, size, step=1, *, alignment):
         size = self._align_up(size, alignment)
 
         if addr > (1 << self.addr_width) or addr + size > (1 << self.addr_width):
-            raise ValueError("Address range {:#x}..{:#x} out of bounds for memory map spanning "
-                             "range {:#x}..{:#x} ({} address bits)"
-                             .format(addr, addr + size, 0, 1 << self.addr_width, self.addr_width))
+            if extend:
+                self.addr_width = bits_for(addr + size)
+            else:
+                raise ValueError("Address range {:#x}..{:#x} out of bounds for memory map spanning "
+                                 "range {:#x}..{:#x} ({} address bits)"
+                                 .format(addr, addr + size, 0, 1 << self.addr_width, self.addr_width))
 
         addr_range = range(addr, addr + size, step)
         overlaps = self._ranges.overlaps(addr_range)
@@ -159,7 +199,7 @@ def _compute_addr_range(self, addr, size, step=1, *, alignment):
 
         return addr_range
 
-    def add_resource(self, resource, *, size, addr=None, alignment=None):
+    def add_resource(self, resource, *, size, addr=None, alignment=None, extend=False):
         """Add a resource.
 
         A resource is any device on the bus that is a destination for bus transactions, e.g.
@@ -178,6 +218,9 @@ def add_resource(self, resource, *, size, addr=None, alignment=None):
             ``2 ** max(alignment, self.alignment)``.
         alignment : int or None
             Alignment of the resource. If not specified, the memory map alignment is used.
+        extend: bool
+            Allow memory map extension. If ``True``, the upper bound of the address space is
+            raised as needed, in order to fit a resource that would otherwise be out of bounds.
 
         Return value
         ------------
@@ -201,7 +244,7 @@ def add_resource(self, resource, *, size, addr=None, alignment=None):
         else:
             alignment = self.alignment
 
-        addr_range = self._compute_addr_range(addr, size, alignment=alignment)
+        addr_range = self._compute_addr_range(addr, size, alignment=alignment, extend=extend)
         self._ranges.insert(addr_range, resource)
         self._resources[resource] = addr_range
         self._next_addr = addr_range.stop
@@ -219,7 +262,7 @@ def resources(self):
         for resource, resource_range in self._resources.items():
             yield resource, (resource_range.start, resource_range.stop)
 
-    def add_window(self, window, *, addr=None, sparse=None):
+    def add_window(self, window, *, addr=None, sparse=None, extend=False):
         """Add a window.
 
         A window is a device on a bus that provides access to a different bus, i.e. a bus bridge.
@@ -248,6 +291,9 @@ def add_window(self, window, *, addr=None, sparse=None):
         sparse : bool or None
             Address translation type. Ignored if the datapath widths of both memory maps are
             equal; must be specified otherwise.
+        extend : bool
+            Allow memory map extension. If ``True``, the upper bound of the address space is
+            raised as needed, in order to fit a window that would otherwise be out of bounds.
 
         Return value
         ------------
@@ -288,6 +334,8 @@ def add_window(self, window, *, addr=None, sparse=None):
                                  "data width {}"
                                  .format(self.data_width, window.data_width))
 
+        window.freeze()
+
         if not sparse:
             ratio = self.data_width // window.data_width
         else:
@@ -300,7 +348,8 @@ def add_window(self, window, *, addr=None, sparse=None):
         # a window can still be aligned using align_to().
         alignment = max(self.alignment, window.addr_width // ratio)
 
-        addr_range = self._compute_addr_range(addr, size, ratio, alignment=alignment)
+        addr_range = self._compute_addr_range(addr, size, ratio, alignment=alignment,
+                                              extend=extend)
         self._ranges.insert(addr_range, window)
         self._windows[window] = addr_range
         self._next_addr = addr_range.stop

nmigen_soc/test/test_memory.py

@@ -56,6 +56,27 @@ def test_wrong_alignment(self):
                 r"Alignment must be a non-negative integer, not -1"):
             MemoryMap(addr_width=16, data_width=8, alignment=-1)
 
+    def test_set_addr_width_wrong(self):
+        with self.assertRaisesRegex(ValueError,
+                r"Address width must be a positive integer, not -1"):
+            memory_map = MemoryMap(addr_width=1, data_width=8)
+            memory_map.addr_width = -1
+
+    def test_set_addr_width_wrong_shrink(self):
+        with self.assertRaisesRegex(ValueError,
+                r"Address width 1 must not be less than its previous value 2, "
+                r"because resources that were previously added may not fit anymore"):
+            memory_map = MemoryMap(addr_width=2, data_width=8)
+            memory_map.addr_width = 1
+
+    def test_set_addr_width_wrong_frozen(self):
+        with self.assertRaisesRegex(ValueError,
+                r"Memory map has been frozen. Address width cannot be extended "
+                r"further"):
+            memory_map = MemoryMap(addr_width=1, data_width=8)
+            memory_map.freeze()
+            memory_map.addr_width = 2
+
     def test_add_resource(self):
         memory_map = MemoryMap(addr_width=16, data_width=8)
         self.assertEqual(memory_map.add_resource("a", size=1), (0, 1))
@@ -77,6 +98,12 @@ def test_add_resource_addr(self):
         self.assertEqual(memory_map.add_resource("a", size=1, addr=10), (10, 11))
         self.assertEqual(memory_map.add_resource("b", size=2), (11, 13))
 
+    def test_add_resource_extend(self):
+        memory_map = MemoryMap(addr_width=16, data_width=8)
+        self.assertEqual(memory_map.add_resource("a", size=1, addr=0x10000, extend=True),
+                         (0x10000, 0x10001))
+        self.assertEqual(memory_map.addr_width, 17)
+
     def test_add_resource_wrong_address(self):
         memory_map = MemoryMap(addr_width=16, data_width=8)
         with self.assertRaisesRegex(ValueError,
@@ -154,6 +181,13 @@ def test_add_window_dense(self):
                                                sparse=False),
                          (0, 0x100, 4))
 
+    def test_add_window_extend(self):
+        memory_map = MemoryMap(addr_width=16, data_width=8)
+        self.assertEqual(memory_map.add_window(MemoryMap(addr_width=17, data_width=8),
+                                               extend=True),
+                         (0, 0x20000, 1))
+        self.assertEqual(memory_map.addr_width, 18)
+
     def test_add_window_wrong_window(self):
         memory_map = MemoryMap(addr_width=16, data_width=8)
         with self.assertRaisesRegex(TypeError,
@@ -181,6 +215,13 @@ def test_add_window_wrong_ratio(self):
                 r"16 is not an integer multiple of window data width 7"):
             memory_map.add_window(MemoryMap(addr_width=10, data_width=7), sparse=False)
 
+    def test_add_window_wrong_out_of_bounds(self):
+        memory_map = MemoryMap(addr_width=16, data_width=8)
+        with self.assertRaisesRegex(ValueError,
+                r"Address range 0x0\.\.0x20000 out of bounds for memory map spanning "
+                r"range 0x0\.\.0x10000 \(16 address bits\)"):
+            memory_map.add_window(MemoryMap(addr_width=17, data_width=8))
+
     def test_add_window_wrong_overlap(self):
         memory_map = MemoryMap(addr_width=16, data_width=8)
         memory_map.add_window(MemoryMap(addr_width=10, data_width=8))