Merge pull request #330 from xobs/document-ctrl-timer0

Document CTRL and fix TIMER0 Documentation

litex/soc/cores/timer.py

@@ -18,44 +18,48 @@ class Timer(Module, AutoCSR, ModuleDoc):
     Provides a generic Timer core.
 
     The Timer is implemented as a countdown timer that can be used in various modes:
-    - Polling : Returns current countdown value to software.
-    - One-Shot: Loads itself and stops when value reaches 0.
-    - Periodic: (Re-)Loads itself when value reaches 0.
 
-    `en` register allows the user to enable/disable the Timer. When the Timer is enabled, it is
+    - Polling : Returns current countdown value to software
+    - One-Shot: Loads itself and stops when value reaches ``0``
+    - Periodic: (Re-)Loads itself when value reaches ``0``
+
+    ``en`` register allows the user to enable/disable the Timer. When the Timer is enabled, it is
     automatically loaded with the value of `load` register.
 
-    When the Timer reaches 0, it is automatically reloaded with value of `reload` register.
+    When the Timer reaches ``0``, it is automatically reloaded with value of `reload` register.
 
-    The user can latch the current countdown value by writing to `update_value` register, it will
-    update `value` register with current countdown value.
+    The user can latch the current countdown value by writing to ``update_value`` register, it will
+    update ``value`` register with current countdown value.
 
     To use the Timer in One-Shot mode, the user needs to:
-    - Disable the timer.
-    - Set the `load` register to the expected duration.
-    - (Re-)Enable the Timer.
+
+    - Disable the timer
+    - Set the ``load`` register to the expected duration
+    - (Re-)Enable the Timer
 
     To use the Timer in Periodic mode, the user needs to:
-    - Disable the Timer.
-    - Set the `load` register to 0.
-    - Set the `reload` register to the expected period.
-    - Enable the Timer.
+
+    - Disable the Timer
+    - Set the ``load`` register to 0
+    - Set the ``reload`` register to the expected period
+    - Enable the Timer
 
     For both modes, the CPU can be advertised by an IRQ that the duration/period has elapsed. (The
-    CPU can also do software polling with `update_value` and `value` to know the elapsed duration)
+    CPU can also do software polling with ``update_value`` and ``value`` to know the elapsed duration)
     """
     def __init__(self, width=32):
-        self._load = CSRStorage(width, description="""Load value when Timer is (re-)enabled.""" +
-            """In One-Shot mode, the value written to this register specify the Timer's duration in
+        self._load = CSRStorage(width, description="""Load value when Timer is (re-)enabled.
+            In One-Shot mode, the value written to this register specifies the Timer's duration in
             clock cycles.""")
-        self._reload = CSRStorage(width, description="""Reload value when Timer reaches 0.""" +
-            """In Periodic mode, the value written to this register specify the Timer's period in
+        self._reload = CSRStorage(width, description="""Reload value when Timer reaches ``0``.
+            In Periodic mode, the value written to this register specify the Timer's period in
             clock cycles.""")
-        self._en = CSRStorage(1, description="""Enable of the Timer.""" +
-            """Set if to 1 to enable/start the Timer and 0 to disable the Timer""")
-        self._update_value = CSRStorage(1, description="""Update of the current countdown value."""+
-            """A write to this register latches the current countdown value to `value` register.""")
-        self._value = CSRStatus(width, description="""Latched countdown value""")
+        self._en = CSRStorage(1, description="""Enable flag of the Timer.
+            Set this flag to ``1`` to enable/start the Timer.  Set to ``0`` to disable the Timer.""")
+        self._update_value = CSRStorage(1, description="""Update trigger for the current countdown value.
+            A write to this register latches the current countdown value to ``value`` register.""")
+        self._value = CSRStatus(width, description="""Latched countdown value.
+            This value is updated by writing to ``update_value``.""")
 
         self.submodules.ev = EventManager()
         self.ev.zero       = EventSourceProcess()

litex/soc/integration/soc_core.py

@@ -41,9 +41,15 @@ __all__ = [
 
 class SoCController(Module, AutoCSR):
     def __init__(self):
-        self._reset      = CSR()
-        self._scratch    = CSRStorage(32, reset=0x12345678)
-        self._bus_errors = CSRStatus(32)
+        self._reset      = CSRStorage(1, description="""
+            Write a ``1`` to this register to trigger a system reset.""")
+        self._scratch    = CSRStorage(32, reset=0x12345678, description="""
+            This register is not used by LiteX, and is available
+            for use as scratch space.  For example, you can use
+            this register to ensure the Wishbone bus is working.""")
+        self._bus_errors = CSRStatus(32, description="""
+            A running total of the number of bus errors, such
+            as Wishbone timeouts.""")
 
         # # #