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.
     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).
         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
     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.
 
     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`.
         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
     features : iter(str)
         Optional signal set. See :class:`Interface`.
     alignment : int

-        Window alignment. See :class:`Interface`.
+        Window alignment. Optional. See :class:`Interface`.

 
     Attributes
     ----------
 
     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`.
         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`.
     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
         :class:`scheduler.RoundRobin`).
 
     Attributes


@@ -442,24 +443,36 @@ class InterconnectShared(Elaboratable):
 
     Parameters
     ----------
 
     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.
         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.
         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
     ----------
 
     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
 
         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):
 
 
 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
                  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
         # - 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
 
         if self.memory.width > len(self.bus.dat_r):
             raise NotImplementedError

-    
+

         # read
         m.submodules.rdport = rdport = self.memory.read_port()
         m.d.comb += [
         # 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):
                 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)
 
         # generate ack
         m.d.sync += self.bus.ack.eq(0)