memory: use a ResourceInfo data class to answer resource queries.

Breaking changes:
* MemoryMap.all_resources() and MemoryMap.find_resource() return an
  instance of ResourceInfo describing the resource and its assigned name
  and address range, instead of a tuple.

Fixes #20.

Author: Jean-François Nguyen

nmigen_soc/memory.py

@@ -3,7 +3,7 @@
 from nmigen.utils import bits_for
 
 
-__all__ = ["MemoryMap"]
+__all__ = ["ResourceInfo", "MemoryMap"]
 
 
 class _RangeMap:
@@ -47,6 +47,71 @@ def items(self):
             yield key, self._values[key]
 
 
+class ResourceInfo:
+    """Resource metadata.
+
+    A wrapper class for resource objects, with their assigned name and address range.
+
+    Parameters
+    ----------
+    resource : object
+        Arbitrary object representing a resource. See :meth:`MemoryMap.add_resource` for details.
+    name : iter(str)
+        Name assigned to the resource. It is prefixed by the name of each window sitting between
+        the resource and the memory map from which this :class:`ResourceInfo` was obtained.
+        See :meth:`MemoryMap.add_window` for details.
+    start : int
+        Start of the address range assigned to the resource.
+    end : int
+        End of the address range assigned to the resource.
+    width : int
+        Amount of data bits accessed at each address. It may be equal to the data width of the
+        memory map from which this :class:`ResourceInfo` was obtained, or less if the resource
+        is located behind a window that uses sparse addressing.
+    """
+    def __init__(self, resource, name, start, end, width):
+        if isinstance(name, str):
+            name = (name,)
+        if not name or not all(isinstance(part, str) and part for part in name):
+            raise TypeError("Name must be a non-empty sequence of non-empty strings, not {!r}"
+                            .format(name))
+        if not isinstance(start, int) or start < 0:
+            raise TypeError("Start address must be a non-negative integer, not {!r}"
+                            .format(start))
+        if not isinstance(end, int) or end <= start:
+            raise TypeError("End address must be an integer greater than the start address, "
+                            "not {!r}".format(end))
+        if not isinstance(width, int) or width < 0:
+            raise TypeError("Width must be a non-negative integer, not {!r}"
+                            .format(width))
+
+        self._resource = resource
+        self._name     = tuple(name)
+        self._start    = start
+        self._end      = end
+        self._width    = width
+
+    @property
+    def resource(self):
+        return self._resource
+
+    @property
+    def name(self):
+        return self._name
+
+    @property
+    def start(self):
+        return self._start
+
+    @property
+    def end(self):
+        return self._end
+
+    @property
+    def width(self):
+        return self._width
+
+
 class MemoryMap:
     """Memory map.
 
@@ -450,15 +515,17 @@ def window_patterns(self):
             yield window, (pattern, window_range.step)
 
     @staticmethod
-    def _translate(start, end, width, window, window_range):
-        assert (end - start) % window_range.step == 0
+    def _translate(resource_info, window, window_range):
+        assert (resource_info.end - resource_info.start) % window_range.step == 0
         # Accessing a resource through a dense and then a sparse window results in very strange
         # layouts that cannot be easily represented, so reject those.
-        assert window_range.step == 1 or width == window.data_width
-        size   = (end - start) // window_range.step
-        start += window_range.start
-        width *= window_range.step
-        return start, start + size, width
+        assert window_range.step == 1 or resource_info.width == window.data_width
+
+        name  = resource_info.name if window.name is None else (window.name, *resource_info.name)
+        size  = (resource_info.end - resource_info.start) // window_range.step
+        start = resource_info.start + window_range.start
+        width = resource_info.width * window_range.step
+        return ResourceInfo(resource_info.resource, name, start, start + size, width)
 
     def all_resources(self):
         """Iterate all resources and their address ranges.
@@ -468,17 +535,16 @@ def all_resources(self):
 
         Yield values
         ------------
-        A tuple ``resource, (start, end, width)`` describing the address range assigned to
-        the resource. ``width`` is the amount of data bits accessed at each address, which may be
-        equal to ``self.data_width``, or less if the resource is located behind a window that
-        uses sparse addressing.
+        An instance of :class:`ResourceInfo` describing the resource and its address range.
         """
         for addr_range, assignment in self._ranges.items():
             if id(assignment) in self._resources:
-                yield assignment, (addr_range.start, addr_range.stop, self.data_width)
+                _, resource_name, _ = self._resources[id(assignment)]
+                yield ResourceInfo(assignment, resource_name, addr_range.start, addr_range.stop,
+                                   self.data_width)
             elif id(assignment) in self._windows:
-                for sub_resource, sub_descr in assignment.all_resources():
-                    yield sub_resource, self._translate(*sub_descr, assignment, addr_range)
+                for resource_info in assignment.all_resources():
+                    yield self._translate(resource_info, assignment, addr_range)
             else:
                 assert False # :nocov:
 
@@ -495,22 +561,20 @@ def find_resource(self, resource):
 
         Return value
         ------------
-        A tuple ``(start, end, width)`` describing the address range assigned to the resource.
-        ``width`` is the amount of data bits accessed at each address, which may be equal to
-        ``self.data_width``, or less if the resource is located behind a window that uses sparse
-        addressing.
+        An instance of :class:`ResourceInfo` describing the resource and its address range.
 
         Exceptions
         ----------
         Raises :exn:`KeyError` if the resource is not found.
         """
         if id(resource) in self._resources:
-            _, _, resource_range = self._resources[id(resource)]
-            return resource_range.start, resource_range.stop, self.data_width
+            _, resource_name, resource_range = self._resources[id(resource)]
+            return ResourceInfo(resource, resource_name, resource_range.start, resource_range.stop,
+                                self.data_width)
 
         for window, window_range in self._windows.values():
             try:
-                return self._translate(*window.find_resource(resource), window, window_range)
+                return self._translate(window.find_resource(resource), window, window_range)
             except KeyError:
                 pass
 

nmigen_soc/test/test_csr_bus.py

@@ -364,8 +364,10 @@ def test_sim(self):
         mux_2.add(elem_2, addr=2)
         self.dut.add(mux_2.bus)
 
-        elem_1_addr, _, _ = self.dut.bus.memory_map.find_resource(elem_1)
-        elem_2_addr, _, _ = self.dut.bus.memory_map.find_resource(elem_2)
+        elem_1_info = self.dut.bus.memory_map.find_resource(elem_1)
+        elem_2_info = self.dut.bus.memory_map.find_resource(elem_2)
+        elem_1_addr = elem_1_info.start
+        elem_2_addr = elem_2_info.start
         self.assertEqual(elem_1_addr, 0x0000)
         self.assertEqual(elem_2_addr, 0x0402)
 

nmigen_soc/test/test_memory.py

@@ -1,6 +1,6 @@
 import unittest
 
-from ..memory import _RangeMap, MemoryMap
+from ..memory import _RangeMap, ResourceInfo, MemoryMap
 
 
 class RangeMapTestCase(unittest.TestCase):
@@ -40,6 +40,54 @@ def test_get(self):
         self.assertEqual(range_map.get(15), None)
 
 
+class ResourceInfoTestCase(unittest.TestCase):
+    def test_simple(self):
+        info = ResourceInfo("a", name=("foo", "bar"), start=0, end=1, width=8)
+        self.assertEqual(info.name, ("foo", "bar"))
+        self.assertEqual(info.start, 0)
+        self.assertEqual(info.end, 1)
+        self.assertEqual(info.width, 8)
+
+    def test_name_cast(self):
+        info = ResourceInfo("a", name="foo", start=0, end=1, width=8)
+        self.assertEqual(info.name, ("foo",))
+
+    def test_wrong_name(self):
+        with self.assertRaisesRegex(TypeError,
+                r"Name must be a non-empty sequence of non-empty strings, not \(1,\)"):
+            ResourceInfo("a", name=(1,), start=0, end=1, width=8)
+        with self.assertRaisesRegex(TypeError,
+                r"Name must be a non-empty sequence of non-empty strings, not \(\)"):
+            ResourceInfo("a", name=(), start=0, end=1, width=8)
+        with self.assertRaisesRegex(TypeError,
+                r"Name must be a non-empty sequence of non-empty strings, not \('foo', ''\)"):
+            ResourceInfo("a", name=("foo", ""), start=0, end=1, width=8)
+
+    def test_wrong_start_addr(self):
+        with self.assertRaisesRegex(TypeError,
+                r"Start address must be a non-negative integer, not 'foo'"):
+            ResourceInfo("a", name="b", start="foo", end=1, width=8)
+        with self.assertRaisesRegex(TypeError,
+                r"Start address must be a non-negative integer, not -1"):
+            ResourceInfo("a", name="b", start=-1, end=1, width=8)
+
+    def test_wrong_end_addr(self):
+        with self.assertRaisesRegex(TypeError,
+                r"End address must be an integer greater than the start address, not 'foo'"):
+            ResourceInfo("a", name="b", start=0, end="foo", width=8)
+        with self.assertRaisesRegex(TypeError,
+                r"End address must be an integer greater than the start address, not 0"):
+            ResourceInfo("a", name="b", start=0, end=0, width=8)
+
+    def test_wrong_width(self):
+        with self.assertRaisesRegex(TypeError,
+                r"Width must be a non-negative integer, not 'foo'"):
+            ResourceInfo("a", name="b", start=0, end=1, width="foo")
+        with self.assertRaisesRegex(TypeError,
+                r"Width must be a non-negative integer, not -1"):
+            ResourceInfo("a", name="b", start=0, end=1, width=-1)
+
+
 class MemoryMapTestCase(unittest.TestCase):
     def test_name(self):
         memory_map_0 = MemoryMap(addr_width=1, data_width=8)
@@ -375,28 +423,62 @@ def setUp(self):
         self.root.add_window(self.win3, sparse=False)
 
     def test_iter_all_resources(self):
-        self.assertEqual(list(self.root.all_resources()), [
-            (self.res1, (0x00000000, 0x00000010, 32)),
-            (self.res2, (0x00010000, 0x00010020, 32)),
-            (self.res3, (0x00010020, 0x00010040, 32)),
-            (self.res4, (0x00020000, 0x00020001, 32)),
-            (self.res5, (0x00030000, 0x00030010, 8)),
-            (self.res6, (0x00040000, 0x00040004, 32)),
-        ])
+        res_info = list(self.root.all_resources())
+
+        self.assertIs(res_info[0].resource, self.res1)
+        self.assertEqual(res_info[0].name,  ("name1",))
+        self.assertEqual(res_info[0].start, 0x00000000)
+        self.assertEqual(res_info[0].end,   0x00000010)
+        self.assertEqual(res_info[0].width, 32)
+
+        self.assertIs(res_info[1].resource, self.res2)
+        self.assertEqual(res_info[1].name,  ("name2",))
+        self.assertEqual(res_info[1].start, 0x00010000)
+        self.assertEqual(res_info[1].end,   0x00010020)
+        self.assertEqual(res_info[1].width, 32)
+
+        self.assertIs(res_info[2].resource, self.res3)
+        self.assertEqual(res_info[2].name,  ("name3",))
+        self.assertEqual(res_info[2].start, 0x00010020)
+        self.assertEqual(res_info[2].end,   0x00010040)
+        self.assertEqual(res_info[2].width, 32)
+
+        self.assertIs(res_info[3].resource, self.res4)
+        self.assertEqual(res_info[3].name,  ("name4",))
+        self.assertEqual(res_info[3].start, 0x00020000)
+        self.assertEqual(res_info[3].end,   0x00020001)
+        self.assertEqual(res_info[3].width, 32)
+
+        self.assertIs(res_info[4].resource, self.res5)
+        self.assertEqual(res_info[4].name,  ("name5",))
+        self.assertEqual(res_info[4].start, 0x00030000)
+        self.assertEqual(res_info[4].end,   0x00030010)
+        self.assertEqual(res_info[4].width, 8)
+
+        self.assertIs(res_info[5].resource, self.res6)
+        self.assertEqual(res_info[5].name,  ("win3", "name6"))
+        self.assertEqual(res_info[5].start, 0x00040000)
+        self.assertEqual(res_info[5].end,   0x00040004)
+        self.assertEqual(res_info[5].width, 32)
 
     def test_find_resource(self):
-        for res, loc in self.root.all_resources():
-            self.assertEqual(self.root.find_resource(res), loc)
+        for res_info in self.root.all_resources():
+            other = self.root.find_resource(res_info.resource)
+            self.assertIs(other.resource, res_info.resource)
+            self.assertEqual(other.name,  res_info.name)
+            self.assertEqual(other.start, res_info.start)
+            self.assertEqual(other.end,   res_info.end)
+            self.assertEqual(other.width, res_info.width)
 
     def test_find_resource_wrong(self):
         with self.assertRaises(KeyError) as error:
             self.root.find_resource("resNA")
         self.assertEqual(error.exception.args, ("resNA",))
 
     def test_decode_address(self):
-        for res, (start, end, width) in self.root.all_resources():
-            self.assertEqual(self.root.decode_address(start), res)
-            self.assertEqual(self.root.decode_address(end - 1), res)
+        for res_info in self.root.all_resources():
+            self.assertEqual(self.root.decode_address(res_info.start),   res_info.resource)
+            self.assertEqual(self.root.decode_address(res_info.end - 1), res_info.resource)
 
     def test_decode_address_missing(self):
         self.assertIsNone(self.root.decode_address(address=0x00000100))