memory: use path= instead of name= in ResourceInfo().

See amaranth-lang/amaranth#909.

Author: jfng

amaranth_soc/memory.py

@@ -50,14 +50,14 @@ def items(self):
 class ResourceInfo:
     """Resource metadata.
 
-    A wrapper class for resource objects, with their assigned name and address range.
+    A wrapper class for resource objects, with their assigned path 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
+    path : iter(str)
+        Path of the resource. It is composed of the names 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
@@ -69,12 +69,10 @@ class ResourceInfo:
         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))
+    def __init__(self, resource, path, start, end, width):
+        if not path or not all(isinstance(part, str) and part for part in path):
+            raise TypeError("Path must be a non-empty sequence of non-empty strings, not {!r}"
+                            .format(path))
         if not isinstance(start, int) or start < 0:
             raise TypeError("Start address must be a non-negative integer, not {!r}"
                             .format(start))
@@ -86,7 +84,7 @@ def __init__(self, resource, name, start, end, width):
                             .format(width))
 
         self._resource = resource
-        self._name     = tuple(name)
+        self._path     = tuple(path)
         self._start    = start
         self._end      = end
         self._width    = width
@@ -96,8 +94,8 @@ def resource(self):
         return self._resource
 
     @property
-    def name(self):
-        return self._name
+    def path(self):
+        return self._path
 
     @property
     def start(self):
@@ -497,11 +495,11 @@ def _translate(resource_info, window, window_range):
         # layouts that cannot be easily represented, so reject those.
         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)
+        path  = resource_info.path if window.name is None else (window.name, *resource_info.path)
         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)
+        return ResourceInfo(resource_info.resource, path, start, start + size, width)
 
     def all_resources(self):
         """Iterate all resources and their address ranges.
@@ -516,7 +514,8 @@ def all_resources(self):
         for addr_range, assignment in self._ranges.items():
             if id(assignment) in self._resources:
                 _, resource_name, _ = self._resources[id(assignment)]
-                yield ResourceInfo(assignment, resource_name, addr_range.start, addr_range.stop,
+                resource_path = (resource_name,)
+                yield ResourceInfo(assignment, resource_path, addr_range.start, addr_range.stop,
                                    self.data_width)
             elif id(assignment) in self._windows:
                 for resource_info in assignment.all_resources():
@@ -545,7 +544,8 @@ def find_resource(self, resource):
         """
         if id(resource) in self._resources:
             _, resource_name, resource_range = self._resources[id(resource)]
-            return ResourceInfo(resource, resource_name, resource_range.start, resource_range.stop,
+            resource_path = (resource_name,)
+            return ResourceInfo(resource, resource_path, resource_range.start, resource_range.stop,
                                 self.data_width)
 
         for window, window_range in self._windows.values():

tests/test_memory.py

@@ -42,50 +42,46 @@ def test_get(self):
 
 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"))
+        info = ResourceInfo("a", path=("foo", "bar"), start=0, end=1, width=8)
+        self.assertEqual(info.path, ("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):
+    def test_wrong_path(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)
+                r"Path must be a non-empty sequence of non-empty strings, not \(1,\)"):
+            ResourceInfo("a", path=(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)
+                r"Path must be a non-empty sequence of non-empty strings, not \(\)"):
+            ResourceInfo("a", path=(), 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)
+                r"Path must be a non-empty sequence of non-empty strings, not \('foo', ''\)"):
+            ResourceInfo("a", path=("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)
+            ResourceInfo("a", path=("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)
+            ResourceInfo("a", path=("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)
+            ResourceInfo("a", path=("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)
+            ResourceInfo("a", path=("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")
+            ResourceInfo("a", path=("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)
+            ResourceInfo("a", path=("b",), start=0, end=1, width=-1)
 
 
 class MemoryMapTestCase(unittest.TestCase):
@@ -391,37 +387,37 @@ def test_iter_all_resources(self):
         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].path,  ("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].path,  ("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].path,  ("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].path,  ("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].path,  ("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].path,  ("win3", "name6"))
         self.assertEqual(res_info[5].start, 0x00040000)
         self.assertEqual(res_info[5].end,   0x00040004)
         self.assertEqual(res_info[5].width, 32)
@@ -430,7 +426,7 @@ def test_find_resource(self):
         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.path,  res_info.path)
             self.assertEqual(other.start, res_info.start)
             self.assertEqual(other.end,   res_info.end)
             self.assertEqual(other.width, res_info.width)