From 6dc7c2718cc361485a847d68aeeb5f8f188d9f2f Mon Sep 17 00:00:00 2001 From: Catherine Date: Tue, 27 Feb 2024 09:03:32 +0000 Subject: [PATCH] docs/guide: fix a bunch of TODOs. --- docs/guide.rst | 25 ++++++------------------- 1 file changed, 6 insertions(+), 19 deletions(-) diff --git a/docs/guide.rst b/docs/guide.rst index cd4e23b..adb4c14 100644 --- a/docs/guide.rst +++ b/docs/guide.rst @@ -255,9 +255,7 @@ Any Python value that implements the :class:`ShapeCastable` interface can extend Value casting ============= -Like shapes, values may be *cast* from other objects, which are called *value-like*. Casting to values allows objects that are not provided by Amaranth, such as integers or enumeration members, to be used in Amaranth expressions directly. Values are value-like objects as well. - -.. TODO: link to ValueCastable +Like shapes, values may be *cast* from other objects, which are called *value-like*. Casting to values allows objects that are not provided by Amaranth, such as integers or enumeration members, to be used in Amaranth expressions directly. Custom value-like objects can be defined by implementing the :class:`~amaranth.hdl.ValueCastable` interface. Values are value-like objects as well. Casting to a value can be done explicitly with :meth:`Value.cast`, but is usually implicit, since value-like objects are accepted anywhere values are. @@ -422,9 +420,7 @@ Signals :ref:`assigned ` in a :ref:`combinatorial ` dom Reset-less signals ------------------ -Signals assigned in a :ref:`synchronous ` domain can be *resettable* or *reset-less*, specified with the ``reset_less=`` parameter. If the parameter is not specified, signals are resettable by default. Resettable signals assume their :ref:`initial value ` on explicit reset, which can be asserted via the clock domain or by using ``ResetInserter``. Reset-less signals are not affected by explicit reset. - -.. TODO: link to clock domain and ResetInserter docs +Signals assigned in a :ref:`synchronous ` domain can be *resettable* or *reset-less*, specified with the ``reset_less=`` parameter. If the parameter is not specified, signals are resettable by default. Resettable signals assume their :ref:`initial value ` on explicit reset, which can be asserted via the :ref:`clock domain ` or by :ref:`modifying control flow ` with :class:`ResetInserter`. Reset-less signals are not affected by explicit reset. Signals assigned in a :ref:`combinatorial ` domain are not affected by the ``reset_less`` parameter. @@ -774,8 +770,6 @@ The ``.as_signed()`` and ``.as_unsigned()`` conversion operators reinterpret the For example, ``(pc + imm[:7].as_signed()).as_unsigned()`` sign-extends the 7 least significant bits of ``imm`` to the width of ``pc``, performs the addition, and produces an unsigned result. -.. TODO: more general shape conversion? https://github.com/amaranth-lang/amaranth/issues/381 - .. _lang-muxop: @@ -993,8 +987,6 @@ Control flow Although it is possible to write any decision tree as a combination of :ref:`assignments ` and :ref:`choice expressions `, Amaranth provides *control flow syntax* tailored for this task: :ref:`If/Elif/Else `, :ref:`Switch/Case `, and :ref:`FSM/State `. The control flow syntax uses :py:`with` blocks (it is implemented using :ref:`context managers `), for example: -.. TODO: link to relevant subsections - .. testcode:: timer = Signal(8) @@ -1133,8 +1125,6 @@ Case comparison, where a single value is examined against several different *pat with m.Default(): m.d.comb += too_big.eq(1) -.. TODO: diagnostic for `Case` blocks after `Default`? - Within a single :py:`Switch` block, the statements within at most one block will be active at any time. This will be the first :py:`Case` block in the order of definition whose pattern :ref:`matches ` the value, or the first :py:`Default` block, whichever is earlier. If a :py:`Default` block is present, or the patterns in the :py:`Case` blocks cover every possible :py:`Switch` value, then the statements within exactly one block will be active at any time, and the sequence as a whole is called a *full condition*. @@ -1275,9 +1265,7 @@ A combinatorial signal that is computed directly or indirectly based on its own Synchronous evaluation ====================== -Signals in synchronous :ref:`control domains ` change whenever the *active edge* (a 0-to-1 or 1-to-0 transition, configured when :ref:`creating the domain `) occurs on the clock of the synchronous domain. In addition, the signals in clock domains with an asynchronous reset change when such a reset is asserted. The final value of a synchronous signal is equal to its :ref:`initial value ` if the reset (of any type) is asserted, or to its current value updated by the :ref:`active assignments ` in the :ref:`assignment order ` otherwise. Synchronous signals always hold state. - -.. TODO: link to clock domains +Signals in synchronous :ref:`control domains ` change whenever the *active edge* (a 0-to-1 or 1-to-0 transition, configured when :ref:`creating the domain `) occurs on the clock of the synchronous domain. In addition, the signals in :ref:`clock domains ` with an asynchronous reset change when such a reset is asserted. The final value of a synchronous signal is equal to its :ref:`initial value ` if the reset (of any type) is asserted, or to its current value updated by the :ref:`active assignments ` in the :ref:`assignment order ` otherwise. Synchronous signals always hold state. Consider the following code: @@ -1337,7 +1325,9 @@ A clock domain also has a reset signal, which can be accessed through the :attr: m.domains.startup = ClockDomain(reset_less=True, local=True) -If a clock domain is defined in a module, all of its submodules can refer to that domain under the same name. +Signals in a reset-less clock domain can still be explicitly reset using the :class:`ResetInserter` :ref:`control flow modifier `. + +If a clock domain is defined in a module, all of its :ref:`submodules ` can refer to that domain under the same name. .. warning:: @@ -1353,9 +1343,6 @@ If a clock domain is defined in a module, all of its submodules can refer to tha A new asynchronous control set is necessary when some signals must change on a different active edge of a clock, at a different frequency, with a different phase, or when a different asynchronous reset signal is asserted. -.. TODO: mention that ResetInserter will add a reset even to a reset-less domain -.. TODO: link to hierarchy section - .. _lang-latesignals: