Adding documentation to the csr modules.

mithro · sbourdeauducq · commit 2775558eb321 · 2016-12-21T10:51:52.000+01:00
A lot of the documentation is comes from https://github.com/m-labs/migen/blob/legacy/doc/bus.rst
diff --git a/misoc/interconnect/csr.py b/misoc/interconnect/csr.py
@@ -1,3 +1,29 @@
+"""
+Configuration and Status Registers
+**********************************
+
+The lowest-level description of a register is provided by the ``CSR`` class,
+which maps to the value at a single address on the target bus. Also provided
+are helper classes for dealing with values larger than the CSR buses data
+width.
+
+ * ``CSRConstant``, for constant values.
+ * ``CSRStatus``, for providing information to the CPU.
+ * ``CSRStorage``, for allowing control via the CPU.
+
+Generating register banks
+=========================
+A module can provide bus-independent CSRs by implementing a ``get_csrs`` method
+that returns a list of instances of the classes described above.
+
+Similarly, bus-independent memories can be returned as a list by a
+``get_memories`` method.
+
+To avoid listing those manually, a module can inherit from the ``AutoCSR``
+class, which provides ``get_csrs`` and ``get_memories`` methods that scan for
+CSR and memory attributes and return their list.
+"""
+
 from migen import *
 from migen.util.misc import xdir
 from migen.fhdl.tracer import get_obj_var_name
@@ -13,6 +39,12 @@ def __init__(self, size, name):
 
 
 class CSRConstant(DUID):
+    """Register which contains a constant value.
+
+    Useful for providing information on how a HDL was instantiated to firmware
+    running on the device.
+    """
+
     def __init__(self, value, bits_sign=None, name=None):
         DUID.__init__(self)
         self.value = Constant(value, bits_sign)
@@ -21,20 +53,49 @@ def __init__(self, value, bits_sign=None, name=None):
             raise ValueError("Cannot extract CSR name from code, need to specify.")
 
     def read(self):
+        """Read method for simulation."""
         return self.value.value
 
 
 class CSR(_CSRBase):
+    """Basic CSR register.
+
+    Parameters
+    ----------
+    size : int
+        Size of the CSR register in bits.
+        Must be less than CSR bus width!
+
+    name : string
+        Provide (or override the name) of the CSR register.
+
+    Attributes
+    ----------
+    r : Signal(size), out
+        Contains the data written from the bus interface.
+        ``r`` is only valid when ``re`` is high.
+
+    re : Signal(), out
+        The strobe signal for ``r``.
+        It is active for one cycle, after or during a write from the bus.
+
+    w : Signal(size), in
+        The value to be read from the bus.
+        Must be provided at all times.
+    """
+
     def __init__(self, size=1, name=None):
         _CSRBase.__init__(self, size, name)
         self.re = Signal(name=self.name + "_re")
         self.r = Signal(self.size, name=self.name + "_r")
         self.w = Signal(self.size, name=self.name + "_w")
 
     def read(self):
+        """Read method for simulation."""
         return (yield self.w)
 
     def write(self, value):
+        """Write method for simulation."""
         yield self.r.eq(value)
         yield self.re.eq(1)
         yield
@@ -56,6 +117,39 @@ def do_finalize(self, busword):
 
 
 class CSRStatus(_CompoundCSR):
+    """Status Register.
+
+    The ``CSRStatus`` class is meant to be used as a status register that is
+    read-only from the CPU.
+
+    The user design is expected to drive its ``status`` signal.
+
+    The advantage of using ``CSRStatus`` instead of using ``CSR`` and driving
+    ``w`` is that the width of ``CSRStatus`` can be arbitrary.
+
+    Status registers larger than the bus word width are automatically broken
+    down into several ``CSR`` registers to span several addresses.
+
+    *Be careful, though:* the atomicity of reads is not guaranteed.
+
+    Parameters
+    ----------
+    size : int
+        Size of the CSR register in bits.
+        Can be bigger than the CSR bus width.
+
+    reset : string
+        Value of the register after reset.
+
+    name : string
+        Provide (or override the name) of the ``CSRStatus`` register.
+
+    Attributes
+    ----------
+    status : Signal(size), in
+        The value of the CSRStatus register.
+    """
+
     def __init__(self, size=1, reset=0, name=None):
         _CompoundCSR.__init__(self, size, name)
         self.status = Signal(self.size, reset=reset)
@@ -69,10 +163,64 @@ def do_finalize(self, busword):
             self.simple_csrs.append(sc)
 
     def read(self):
+        """Read method for simulation."""
         return (yield self.status)
 
 
 class CSRStorage(_CompoundCSR):
+    """Control Register.
+
+    The ``CSRStorage`` class provides a memory location that can be read and
+    written by the CPU, and read and optionally written by the design.
+
+    It can span several CSR addresses.
+
+    Parameters
+    ----------
+    size : int
+        Size of the CSR register in bits.
+        Can be bigger than the CSR bus width.
+
+    reset : string
+        Value of the register after reset.
+
+    atomic_write : bool
+        Provide an mechanism for atomic CPU writes is provided.
+        When enabled, writes to the first CSR addresses go to a back-buffer
+        whose contents are atomically copied to the main buffer when the last
+        address is written.
+
+    write_from_dev : bool
+        Allow the design to update the CSRStorage value.
+        *Warning*: The atomicity of reads by the CPU is not guaranteed.
+
+    alignment_bits : int
+        ???
+
+    name : string
+        Provide (or override the name) of the ``CSRStatus`` register.
+
+    Attributes
+    ----------
+    storage_full : Signal(size), out
+        ???
+
+    storage : Signal(size), out
+        Signal providing the value of the ``CSRStorage`` object.
+
+    re : Signal(), in
+        The strobe signal indicating a write to the ``CSRStorage`` register.
+        It is active for one cycle, after or during a write from the bus.
+
+    we : Signal(), out
+        Only available when ``write_from_dev == True``
+        ???
+
+    dat_w : Signal(), out
+        Only available when ``write_from_dev == True``
+        ???
+    """
+
     def __init__(self, size=1, reset=0, atomic_write=False, write_from_dev=False, alignment_bits=0, name=None):
         _CompoundCSR.__init__(self, size, name)
         self.alignment_bits = alignment_bits
@@ -115,9 +263,11 @@ def do_finalize(self, busword):
         self.sync += self.re.eq(sc.re)
 
     def read(self):
+        """Read method for simulation."""
         return (yield self.storage) << self.alignment_bits
 
     def write(self, value):
+        """Write method for simulation."""
         yield self.storage.eq(value >> self.alignment_bits)
         yield self.re.eq(1)
         yield
@@ -162,6 +312,17 @@ def gatherer(self):
 
 
 class AutoCSR:
+    """MixIn to provide bus independent access to CSR registers.
+
+    A module can inherit from the ``AutoCSR`` class, which provides
+    ``get_csrs``, ``get_memories`` and ``get_constants`` methods that scan for
+    CSR and memory attributes and return their list.
+
+    If the module has child objects that implement ``get_csrs``,
+    ``get_memories`` or ``get_constants``, they will be called by the
+    ``AutoCSR`` methods and their CSR and memories added to the lists returned,
+    with the child objects' names as prefixes.
+    """
     get_memories = _make_gatherer("get_memories", Memory, memprefix)
     get_csrs = _make_gatherer("get_csrs", _CSRBase, csrprefix)
     get_constants = _make_gatherer("get_constants", CSRConstant, csrprefix)
diff --git a/misoc/interconnect/csr_bus.py b/misoc/interconnect/csr_bus.py
@@ -1,3 +1,11 @@
+"""
+CSR-2 bus
+=========
+
+The CSR-2 bus is a low-bandwidth, resource-sensitive bus designed for accessing
+the configuration and status registers of cores from software.
+"""
+
 from migen import *
 from migen.genlib.record import *
 from migen.genlib.misc import chooser
diff --git a/misoc/interconnect/csr_eventmanager.py b/misoc/interconnect/csr_eventmanager.py
@@ -1,3 +1,8 @@
+"""
+The event manager provides a systematic way to generate standard interrupt
+controllers.
+"""
+
 from functools import reduce
 from operator import or_
 
@@ -8,16 +13,44 @@
 
 
 class _EventSource(DUID):
+    """Base class for EventSources.
+
+    Attributes
+    ----------
+    trigger : Signal(), in
+        Signal which interfaces with the user design.
+
+    status : Signal(), out
+        Contains the current level of the trigger signal.
+        This value ends up in the ``status`` register.
+
+    pending : Signal(), out
+        A trigger event has occurred and not yet cleared.
+        This value ends up in the ``pending`` register.
+
+    clear : Signal(), in
+        Clear after a trigger event.
+        Ignored by some event sources.
+    """
+
     def __init__(self):
         DUID.__init__(self)
-        self.status = Signal()  # value in the status register
-        self.pending = Signal()  # value in the pending register + assert irq if unmasked
-        self.trigger = Signal()  # trigger signal interface to the user design
-        self.clear = Signal()  # clearing attempt by W1C to pending register, ignored by some event sources
+        self.status = Signal()
+        self.pending = Signal()
+        self.trigger = Signal()
+        self.clear = Signal()
 
 
-# set on a positive trigger pulse
 class EventSourcePulse(Module, _EventSource):
+    """EventSource which triggers on a pulse.
+
+    The event stays asserted after the ``trigger`` signal goes low, and until
+    software acknowledges it.
+
+    An example use is to pulse ``trigger`` high for 1 cycle after the reception
+    of a character in a UART.
+    """
+
     def __init__(self):
         _EventSource.__init__(self)
         self.comb += self.status.eq(0)
@@ -27,8 +60,15 @@ def __init__(self):
         ]
 
 
-# set on the falling edge of the trigger, status = trigger
 class EventSourceProcess(Module, _EventSource):
+    """EventSource which triggers on a falling edge.
+
+    The purpose of this event source is to monitor the status of processes and
+    generate an interrupt on their completion.
+
+    The signal ``trigger`` can be connected to the ``busy`` signal of a
+    dataflow actor, for example.
+    """
     def __init__(self):
         _EventSource.__init__(self)
         self.comb += self.status.eq(self.trigger)
@@ -40,8 +80,13 @@ def __init__(self):
         ]
 
 
-# all status set by external trigger
 class EventSourceLevel(Module, _EventSource):
+    """EventSource which trigger contains the instantaneous state of the event.
+
+    It must be set and released by the user design. For example, a DMA
+    controller with several slots can use this event source to signal that one
+    or more slots require CPU attention.
+    """
     def __init__(self):
         _EventSource.__init__(self)
         self.comb += [
@@ -51,6 +96,31 @@ def __init__(self):
 
 
 class EventManager(Module, AutoCSR):
+    """Provide an IRQ and CSR registers for a set of event sources.
+
+    Each event source is assigned one bit in each of those registers.
+
+    Attributes
+    ----------
+    irq : Signal(), out
+        A signal which is driven high whenever there is a pending and unmasked
+        event.
+        It is typically connected to an interrupt line of a CPU.
+
+    status : CSR(n), read-only
+        Contains the current level of the trigger line of
+        ``EventSourceProcess`` and ``EventSourceLevel`` sources.
+        It is always 0 for ``EventSourcePulse``
+
+    pending : CSR(n), read-write
+        Contains the currently asserted events. Writing 1 to the bit assigned
+        to an event clears it.
+
+    enable : CSR(n), read-write
+        Defines which asserted events will cause the ``irq`` line to be
+        asserted.
+    """
+
     def __init__(self):
         self.irq = Signal()
 
@@ -81,6 +151,8 @@ def __setattr__(self, name, value):
 
 
 class SharedIRQ(Module):
+    """Allow an IRQ signal to be shared between multiple EventManager objects."""
+
     def __init__(self, *event_managers):
         self.irq = Signal()
         self.comb += self.irq.eq(reduce(or_, [ev.irq for ev in event_managers]))
