wishbone: fix docstring & unneeded parameter for InterconnectShared

diff --git a/nmigen_soc/wishbone/bus.py b/nmigen_soc/wishbone/bus.py
index 2ae27331ff5e736b05abf34d1d353ace74c0c5d9..039413dff018847be07524e1a02e6d559006602a 100644 (file)
--- a/nmigen_soc/wishbone/bus.py
+++ b/nmigen_soc/wishbone/bus.py
@@ -45,13 +45,14 @@ class Interface(Record):
     data_width : int
         Width of the data signals ("port size" in Wishbone terminology).
         One of 8, 16, 32, 64.
-    granularity : int
+    granularity : int or None
         Granularity of select signals ("port granularity" in Wishbone terminology).
-        One of 8, 16, 32, 64.
+        One of 8, 16, 32, 64. Optional and defaults to None, meaning it is equal
+        to the address width.
     features : iter(str)
         Selects the optional signals that will be a part of this interface.
     alignment : int
-        Resource and window alignment. See :class:`MemoryMap`.
+        Resource and window alignment. Optional. See :class:`MemoryMap`.
     name : str
         Name of the underlying record.
 
@@ -185,12 +186,12 @@ class Decoder(Elaboratable):
         Address width. See :class:`Interface`.
     data_width : int
         Data width. See :class:`Interface`.
-    granularity : int
-        Granularity. See :class:`Interface`
+    granularity : int or None
+        Granularity. Optional. See :class:`Interface`
     features : iter(str)
         Optional signal set. See :class:`Interface`.
     alignment : int
-        Window alignment. See :class:`Interface`.
+        Window alignment. Optional. See :class:`Interface`.
 
     Attributes
     ----------
@@ -313,12 +314,12 @@ class Arbiter(Elaboratable):
         Address width of the shared bus. See :class:`Interface`.
     data_width : int
         Data width of the shared bus. See :class:`Interface`.
-    granularity : int
-        Granularity of the shared bus. See :class:`Interface`.
+    granularity : int or None
+        Granularity of the shared bus. Optional. See :class:`Interface`.
     features : iter(str)
         Optional signal set for the shared bus. See :class:`Interface`.
-    scheduler : str or None
-        Method for bus arbitration. Defaults to "rr" (Round Robin, see
+    scheduler : str
+        Method for bus arbitration. Optional and defaults to "rr" (Round Robin, see
         :class:`scheduler.RoundRobin`).
 
     Attributes
@@ -442,24 +443,36 @@ class InterconnectShared(Elaboratable):
 
     Parameters
     ----------
-    shared_bus : :class:`Interface`
-        Shared bus for the interconnect module between the arbiter and decoder.
-    itors : list of :class:`Interface`
+    addr_width : int
+        Address width of the shared bus. See :class:`Interface`.
+    data_width : int
+        Data width of the shared bus. See :class:`Interface`.
+    itors : list of (:class:`Interface` OR :class:`Record`)
         List of MASTERs on the arbiter to request access to the shared bus.
-    targets : list of :class:`Interface`
+        If the item is a :class:`Record`, its fields must be named using the
+        convention of :class:`Interface`.
+    targets : list of (:class:`Interface` OR tuple of (:class:`Interface`, int))
         List of SLAVEs on the decoder whose accesses are to be targeted by the shared bus.
+        If the item is a tuple of (intf, addr), the :class:`Interface`-type intf is added
+        at the (address width + granularity bits)-wide address of the int-type addr.
+    granularity : int or None
+        Granularity of the shared bus. Optional. See :class:`Interface`.
+    features : iter(str)
+        Optional signal set for the shared bus. See :class:`Interface`.
+    scheduler : str
+        Method for bus arbitration for the arbiter. Optional and defaults to "rr" (Round Robin, see
+        :class:`scheduler.RoundRobin`).
+    alignment : int
+        Window alignment for the decoder. Optional. See :class:`Interface`.
 
     Attributes
     ----------
-    addr_width : int
-        Address width of the shared bus. See :class:`Interface`.
-    data_width : int
-        Data width of the shared bus. See :class:`Interface`.
-    granularity : int
-        Granularity of the shared bus. See :class:`Interface`
+    arbiter : :class:`Arbiter`
+        The arbiter that connects the list of MASTERs to a shared bus.
+    decoder : :class:`Decoder`
+        The decoder that connects the shared bus to the list of SLAVEs.
     """
-    def __init__(self, *, addr_width, data_width, itors, targets, 
-                 scheduler="rr", **kwargs):
+    def __init__(self, *, addr_width, data_width, itors, targets, **kwargs):
         self.addr_width = addr_width
         self.data_width = data_width
 

diff --git a/nmigen_soc/wishbone/sram.py b/nmigen_soc/wishbone/sram.py
index b72687dd544a80f7b4dcb5149ed930b5b000a7e4..84faeeda80f7d98b68e6d1565e380e5be1397e23 100644 (file)
--- a/nmigen_soc/wishbone/sram.py
+++ b/nmigen_soc/wishbone/sram.py
@@ -8,16 +8,46 @@ __all__ = ["SRAM"]
 
 
 class SRAM(Elaboratable):
+    """SRAM module carrying a volatile memory block (implemented with :class:`Memory`)
+    that can be read and write (or only read if the SRAM is read-only) through a Wishbone bus.
+
+    If no Wishbone bus is specified during initialisation, this creates one whose address width
+    is just enough to fit the whole memory (i.e. equals to the log2(memory depth) rounded up), and
+    whose data width is equal to the memory width.
+
+    Parameters
+    ----------
+    memory : :class:`Memory`
+        The memory to be accessed via the Wishbone bus.
+    read_only : bool
+        Whether or not the memory is read-only. Defaults to False.
+    bus : :class:`Interface` or None
+        The Wishbone bus interface providing access to the read/write ports of the memory.
+        Optional and defaults to None, which lets this module to instantiate one as described
+        above, having the granularity, features and alignment as specified by their
+        corresponding parameters.
+    granularity : int or None
+        If the Wishbone bus is not sepcified, this is the granularity of the Wishbone bus.
+        Optional. See :class:`Interface`.
+    features : iter(str)
+        If the Wishbone bus is not sepcified, this is the optional signal set for the Wishbone bus.
+        See :class:`Interface`.
+
+    Attributes
+    ----------
+    memory : :class:`Memory`
+        The memory to be accessed via the Wishbone bus.
+    bus : :class:`Interface`
+        The Wishbone bus interface providing access to the read/write ports of the memory.
     """
-    """
-    def __init__(self, memory, read_only=False, bus=None, 
+    def __init__(self, memory, read_only=False, bus=None,
                  granularity=None, features=frozenset()):
         if not isinstance(memory, Memory):
             raise TypeError("Memory {!r} is not a Memory"
                             .format(memory))
         self.memory = memory
         self.read_only = read_only
-        # Define total address space: 
+        # Define total address space:
         # - Base: equals memory.depth
         # - Has an additional ReadPort: add rdport.depth
         # - Has an additional WirtePort: add wrport.depth
@@ -39,7 +69,7 @@ class SRAM(Elaboratable):
 
         if self.memory.width > len(self.bus.dat_r):
             raise NotImplementedError
-    
+
         # read
         m.submodules.rdport = rdport = self.memory.read_port()
         m.d.comb += [
@@ -55,7 +85,8 @@ class SRAM(Elaboratable):
                 wrport.data.eq(self.bus.dat_w)
             ]
             for i in range(4):
-                m.d.comb += wrport.en[i].eq(self.bus.cyc & self.bus.stb & self.bus.we & self.bus.sel[i])
+                m.d.comb += wrport.en[i].eq(self.bus.cyc & self.bus.stb &
+                                            self.bus.we & self.bus.sel[i])
 
         # generate ack
         m.d.sync += self.bus.ack.eq(0)