From a251d7121152222ee2c96819b2b51343a5741c82 Mon Sep 17 00:00:00 2001 From: Sean Cross Date: Thu, 2 Jan 2020 15:36:35 +0800 Subject: [PATCH 1/3] cores: timer: fix documentation formatting The ReStructured Text used was not properly formatted, resulting in confusing and broken output. This corrects the output and lets it format correctly when using sphinx. Signed-off-by: Sean Cross --- litex/soc/cores/timer.py | 33 ++++++++++++++++++--------------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/litex/soc/cores/timer.py b/litex/soc/cores/timer.py index 3de9572ef..55e8483db 100644 --- a/litex/soc/cores/timer.py +++ b/litex/soc/cores/timer.py @@ -18,31 +18,34 @@ 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.""" + From 2d75aee7e0192d9be74271c5d0e7d8bd1bfb4b3e Mon Sep 17 00:00:00 2001 From: Sean Cross Date: Thu, 2 Jan 2020 15:37:45 +0800 Subject: [PATCH 2/3] soc_core: ctrl: document registers This adds a small amount of documentation to the three registers present inside the `CTRL` module. Signed-off-by: Sean Cross --- litex/soc/integration/soc_core.py | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/litex/soc/integration/soc_core.py b/litex/soc/integration/soc_core.py index 22e714875..6260f9a52 100644 --- a/litex/soc/integration/soc_core.py +++ b/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.""") # # # From c5aa929d4c89337964f8bdba8908ddedec84c146 Mon Sep 17 00:00:00 2001 From: Sean Cross Date: Thu, 2 Jan 2020 16:24:12 +0800 Subject: [PATCH 3/3] cores: timer: clean up wording for timer documentation This fixes some formatting errors with the timer documentation, such as the lack of a space between the first and second sentences. It also fixes some grammar for documentation of various fields. Signed-off-by: Sean Cross --- litex/soc/cores/timer.py | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/litex/soc/cores/timer.py b/litex/soc/cores/timer.py index 55e8483db..570bf650d 100644 --- a/litex/soc/cores/timer.py +++ b/litex/soc/cores/timer.py @@ -48,17 +48,18 @@ class Timer(Module, AutoCSR, ModuleDoc): 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()