wip (wishbone)

Author: jfng

amaranth_soc/wishbone/bus.py

@@ -42,62 +42,71 @@ class Signature(wiring.Signature):
     of the Wishbone signals. The ``RST_I`` and ``CLK_I`` signals are provided as a part of
     the clock domain that drives the interface.
 
-    Parameters
-    ----------
-    addr_width : int
+    The correspondence between the Amaranth-SoC signals and the Wishbone signals changes depending
+    on whether the interface acts as an initiator or a target.
+
+    Arguments
+    ---------
+    addr_width : :class:`int`
         Width of the address signal.
-    data_width : int
+    data_width : :class:`int`
         Width of the data signals ("port size" in Wishbone terminology).
         One of 8, 16, 32, 64.
-    granularity : int
+    granularity : :class:`int`
         Granularity of select signals ("port granularity" in Wishbone terminology).
         One of 8, 16, 32, 64.
         Optional. If ``None`` (by default), the granularity is equal to ``data_width``.
-    features : iter(:class:`Feature`)
+    features : iterable of :class:`Feature`
         Selects additional signals that will be a part of this interface.
         Optional.
 
-    Interface attributes
-    --------------------
-    The correspondence between the Amaranth-SoC signals and the Wishbone signals changes depending
-    on whether the interface acts as an initiator or a target.
-
-    adr : Signal(addr_width)
+    Attributes
+    ----------
+    adr : :pc:`unsigned(addr_width)`
         Corresponds to Wishbone signal ``ADR_O`` (initiator) or ``ADR_I`` (target).
-    dat_w : Signal(data_width)
+    dat_w : :pc:`unsigned(data_width)`
         Corresponds to Wishbone signal ``DAT_O`` (initiator) or ``DAT_I`` (target).
-    dat_r : Signal(data_width)
+    dat_r : :pc:`unsigned(data_width)`
         Corresponds to Wishbone signal ``DAT_I`` (initiator) or ``DAT_O`` (target).
-    sel : Signal(data_width // granularity)
+    sel : :pc:`unsigned(data_width // granularity)`
         Corresponds to Wishbone signal ``SEL_O`` (initiator) or ``SEL_I`` (target).
-    cyc : Signal()
+    cyc : :pc:`unsigned(1)`
         Corresponds to Wishbone signal ``CYC_O`` (initiator) or ``CYC_I`` (target).
-    stb : Signal()
+    stb : :pc:`unsigned(1)`
         Corresponds to Wishbone signal ``STB_O`` (initiator) or ``STB_I`` (target).
-    we : Signal()
+    we : :pc:`unsigned(1)`
         Corresponds to Wishbone signal ``WE_O``  (initiator) or ``WE_I``  (target).
-    ack : Signal()
+    ack : :pc:`unsigned(1)`
         Corresponds to Wishbone signal ``ACK_I`` (initiator) or ``ACK_O`` (target).
-    err : Signal()
+    err : :pc:`unsigned(1)`
         Optional. Corresponds to Wishbone signal ``ERR_I`` (initiator) or ``ERR_O`` (target).
-    rty : Signal()
+    rty : :pc:`unsigned(1)`
         Optional. Corresponds to Wishbone signal ``RTY_I`` (initiator) or ``RTY_O`` (target).
-    stall : Signal()
+    stall : :pc:`unsigned(1)`
         Optional. Corresponds to Wishbone signal ``STALL_I`` (initiator) or ``STALL_O`` (target).
-    lock : Signal()
+    lock : :pc:`unsigned(1)`
         Optional. Corresponds to Wishbone signal ``LOCK_O`` (initiator) or ``LOCK_I`` (target).
         Amaranth-SoC Wishbone support assumes that initiators that don't want bus arbitration to
         happen in between two transactions need to use ``lock`` feature to guarantee this. An
         initiator without the ``lock`` feature may be arbitrated in between two transactions even
         if ``cyc`` is kept high.
-    cti : Signal()
+    cti : :pc:`unsigned(1)`
         Optional. Corresponds to Wishbone signal ``CTI_O`` (initiator) or ``CTI_I`` (target).
-    bte : Signal()
+    bte : :pc:`unsigned(1)`
         Optional. Corresponds to Wishbone signal ``BTE_O`` (initiator) or ``BTE_I`` (target).
 
     Raises
     ------
-    See :meth:`Signature.check_parameters`.
+    :exc:`TypeError`
+        If ``addr_width`` is not an integer greater than or equal to 0.
+    :exc:`ValueError`
+        If ``data_width`` is not 8, 16, 32 or 64.
+    :exc:`ValueError`
+        If ``granularity`` is not 8, 16, 32 or 64.
+    :exc:`ValueError`
+        If ``granularity`` is greater than ``data_width``.
+    :exc:`ValueError`
+        If ``features`` contains other values than :class:`Feature` members.
     """
     def __init__(self, *, addr_width, data_width, granularity=None, features=frozenset()):
         if granularity is None:
@@ -136,18 +145,42 @@ def __init__(self, *, addr_width, data_width, granularity=None, features=frozens
 
     @property
     def addr_width(self):
+        """Width of the address signal.
+
+        Returns
+        -------
+        :class:`int`
+        """
         return self._addr_width
 
     @property
     def data_width(self):
+        """Width of the data signals ("port size" in Wishbone terminology).
+
+        Returns
+        -------
+        One of 8, 16, 32, 64.
+        """
         return self._data_width
 
     @property
     def granularity(self):
+        """Granularity of select signals ("port granularity" in Wishbone terminology).
+
+        Returns
+        -------
+        One of 8, 16, 32, 64.
+        """
         return self._granularity
 
     @property
     def features(self):
+        """Additional signals that will be a part of this interface.
+
+        Returns
+        -------
+        :class:`frozenset` of :class:`Feature`
+        """
         return self._features
 
     @classmethod
@@ -186,7 +219,7 @@ def create(self, *, path=None, src_loc_at=0):
 
         Returns
         -------
-        An :class:`Interface` object using this signature.
+        :class:`Interface`
         """
         return Interface(addr_width=self.addr_width, data_width=self.data_width,
                          granularity=self.granularity, features=self.features,
@@ -211,31 +244,37 @@ def __repr__(self):
 class Interface(wiring.PureInterface):
     """Wishbone bus interface.
 
-    Note that the data width of the underlying memory map of the interface is equal to port
-    granularity, not port size. If port granularity is less than port size, then the address width
-    of the underlying memory map is extended to reflect that.
+    .. note::
 
-    Parameters
-    ----------
+        The data width of the underlying :class:`MemoryMap` of the interface is equal to port
+        granularity, not port size. If port granularity is less than port size, then the address
+        width of the underlying memory map is extended to reflect that.
+
+    Arguments
+    ---------
     addr_width : :class:`int`
         Width of the address signal. See :class:`Signature`.
     data_width : :class:`int`
         Width of the data signals. See :class:`Signature`.
     granularity : :class:`int`
         Granularity of select signals. Optional. See :class:`Signature`.
-    features : iter(:class:`Feature`)
+    features : iterable of :class:`Feature`
         Describes additional signals of this interface. Optional. See :class:`Signature`.
     path : iter(:class:`str`)
         Path to this Wishbone interface. Optional. See :class:`wiring.PureInterface`.
 
-    Attributes
-    ----------
-    memory_map: :class:`MemoryMap`
-        Memory map of the bus. Optional.
-
     Raises
     ------
-    See :meth:`Signature.check_parameters`.
+    :exc:`TypeError`
+        If ``addr_width`` is not an integer greater than or equal to 0.
+    :exc:`ValueError`
+        If ``data_width`` is not 8, 16, 32 or 64.
+    :exc:`ValueError`
+        If ``granularity`` is not 8, 16, 32 or 64.
+    :exc:`ValueError`
+        If ``granularity`` is greater than ``data_width``.
+    :exc:`ValueError`
+        If ``features`` contains other values than :class:`Feature` members.
     """
     def __init__(self, *, addr_width, data_width, granularity=None, features=frozenset(),
                  path=None, src_loc_at=0):
@@ -246,22 +285,54 @@ def __init__(self, *, addr_width, data_width, granularity=None, features=frozens
 
     @property
     def addr_width(self):
+        """Width of the address signal.
+
+        Returns
+        -------
+        :class:`int`
+        """
         return self.signature.addr_width
 
     @property
     def data_width(self):
+        """Width of the data signals ("port size" in Wishbone terminology).
+
+        Returns
+        -------
+        One of 8, 16, 32, 64.
+        """
         return self.signature.data_width
 
     @property
     def granularity(self):
+        """Granularity of select signals ("port granularity" in Wishbone terminology).
+
+        Returns
+        -------
+        One of 8, 16, 32, 64.
+        """
         return self.signature.granularity
 
     @property
     def features(self):
+        """Additional signals that are part of this interface.
+
+        Returns
+        -------
+        :class:`frozenset` of :class:`Feature`
+        """
         return self.signature.features
 
     @property
     def memory_map(self):
+        """Memory map of the bus.
+
+        .. todo:: setter
+
+        Returns
+        -------
+        :class:`MemoryMap` or ``None``
+        """
         if self._memory_map is None:
             raise AttributeError(f"{self!r} does not have a memory map")
         return self._memory_map
@@ -291,20 +362,20 @@ class Decoder(wiring.Component):
 
     An address decoder for subordinate Wishbone buses.
 
-    Parameters
-    ----------
+    Arguments
+    ---------
     addr_width : :class:`int`
         Address width. See :class:`Signature`.
     data_width : :class:`int`
         Data width. See :class:`Signature`.
     granularity : :class:`int`
         Granularity. See :class:`Signature`
-    features : iter(:class:`Feature`)
+    features : iterable of :class:`Feature`
         Optional signal set. See :class:`Signature`.
-    alignment : int, power-of-2 exponent
-        Window alignment. Optional. See :class:`..memory.MemoryMap`.
+    alignment : :class:`int`, power-of-2 exponent
+        Window alignment. Optional. See :class:`~..memory.MemoryMap`.
     name : :class:`str`
-        Window name. Optional. See :class:`..memory.MemoryMap`.
+        Window name. Optional. See :class:`~..memory.MemoryMap`.
 
     Attributes
     ----------
@@ -326,20 +397,56 @@ def align_to(self, alignment):
         """Align the implicit address of the next window.
 
         See :meth:`MemoryMap.align_to` for details.
+
+        Returns
+        -------
+        :class:`int`
+            Implicit next address.
         """
         return self.bus.memory_map.align_to(alignment)
 
     def add(self, sub_bus, *, addr=None, sparse=False):
         """Add a window to a subordinate bus.
 
-        The decoder can perform either sparse or dense address translation. If dense address
-        translation is used (the default), the subordinate bus must have the same data width as
-        the decoder; the window will be contiguous. If sparse address translation is used,
-        the subordinate bus may have data width less than the data width of the decoder;
-        the window may be discontiguous. In either case, the granularity of the subordinate bus
-        must be equal to or less than the granularity of the decoder.
+        See :meth:`MemoryMap.add_window` for details.
+
+        .. note::
+
+            The :class:`Decoder` can perform either *sparse* or *dense* address translation:
+
+              - If dense address translation is used (the default), the subordinate bus must have
+                the same data width as the :class:`Decoder`; the window will be contiguous.
+              - If sparse address translation is used, the subordinate bus may have data width less
+                than the data width of the :class:`Decoder`; the window may be discontiguous.
+
+            In either case, the granularity of the subordinate bus must be equal to or less than
+            the granularity of the :class:`Decoder`.
 
-        See :meth:`MemoryMap.add_resource` for details.
+        .. todo:: include exceptions raised in :meth:`MemoryMap.add_window`
+
+        Returns
+        -------
+        :class:`tuple` of (:class:`int`, :class:`int`, :class:`int`)
+            A tuple ``(start, end, ratio)`` describing the address range assigned to the window.
+            When bridging buses of unequal data width, ``ratio`` is the amount of contiguous
+            addresses on the narrower bus that are accessed for each transaction on the wider bus.
+            Otherwise, it is always 1.
+
+        Raises
+        ------
+        :exc:`TypeError`
+            If the subordinate bus is not an instance of :class:`Interface`.
+        :exc:`ValueError`
+            If the subordinate bus granularity is greater than the :class:`Decoder` granularity.
+        :exc:`ValueError`
+            If dense address translation is used and the subordinate bus data width is not equal
+            to the :class:`Decoder` data width.
+        :exc:`ValueError`
+            If sparse address translation is used and the subordinate bus data width is not the
+            equal to the subordinate bus granularity.
+        :exc:`ValueError`
+            If the subordinate bus as an optional output signal that is not present in the
+            :class:`Decoder` interface.
         """
         if isinstance(sub_bus, wiring.FlippedInterface):
             sub_bus_unflipped = flipped(sub_bus)
@@ -425,15 +532,15 @@ class Arbiter(wiring.Component):
 
     A round-robin arbiter for initiators accessing a shared Wishbone bus.
 
-    Parameters
-    ----------
-    addr_width : int
+    Arguments
+    ---------
+    addr_width : :class:`int`
         Address width. See :class:`Signature`.
-    data_width : int
+    data_width : :class:`int`
         Data width. See :class:`Signature`.
-    granularity : int
+    granularity : :class:`int`
         Granularity. See :class:`Signature`
-    features : iter(:class:`Feature`)
+    features : iterable of :class:`Feature`
         Optional signal set. See :class:`Signature`.
 
     Attributes
@@ -449,9 +556,19 @@ def __init__(self, *, addr_width, data_width, granularity=None, features=frozens
     def add(self, intr_bus):
         """Add an initiator bus to the arbiter.
 
-        The initiator bus must have the same address width and data width as the arbiter. The
-        granularity of the initiator bus must be greater than or equal to the granularity of
-        the arbiter.
+        Raises
+        ------
+        :exc:`TypeError`
+            If iniatator bus is not an instance of :class:`Interface`.
+        :exc:`ValueError`
+            If the initiator bus address width is not equal to the :class:`Arbiter` address width.
+        :exc:`ValueError`
+            If the initiator bus granularity is lesser than the :class:`Arbiter` granularity.
+        :exc:`ValueError`
+            If the initiator bus data width is not equal to the :class:`Arbiter` data width.
+        :exc:`ValueError`
+            If the :class:`Arbiter` has an optional output signal that is not present in the
+            initiator bus.
         """
         if not isinstance(intr_bus, Interface):
             raise TypeError(f"Initiator bus must be an instance of wishbone.Interface, not "

docs/index.rst

@@ -6,6 +6,7 @@ System on Chip toolkit
    This manual is a work in progress and is seriously incomplete!
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    memory
+   wishbone/bus