docs: cover `nmigen.lib.fifo`.

diff --git a/docs/stdlib.rst b/docs/stdlib.rst
index 5dafaddfa199f4f3ed452e1a75ce1938df8f890d..92b0465aa94aaf17dc07b2c26f3d154ff3fbd4bb 100644 (file)
--- a/docs/stdlib.rst
+++ b/docs/stdlib.rst
@@ -10,3 +10,4 @@ Standard library
 
    stdlib/coding
    stdlib/cdc
+   stdlib/fifo
\ No newline at end of file

diff --git a/docs/stdlib/fifo.rst b/docs/stdlib/fifo.rst
new file mode 100644 (file)
index 0000000..f7825e1
--- /dev/null
+++ b/docs/stdlib/fifo.rst
@@ -0,0 +1,18 @@
+First-in first-out queues
+#########################
+
+.. py:module:: nmigen.lib.fifo
+
+The ``nmigen.lib.fifo`` package provides modules for first-in, first-out queues.
+
+
+.. autoclass:: FIFOInterface
+
+   .. note::
+
+      The :class:`FIFOInterface` class can be used directly to substitute a FIFO in tests, or inherited from in a custom FIFO implementation.
+
+.. autoclass:: SyncFIFO(*, width, depth, fwft=True)
+.. autoclass:: SyncFIFOBuffered(*, width, depth)
+.. autoclass:: AsyncFIFO(*, width, depth, r_domain="read", w_domain="write", exact_depth=False)
+.. autoclass:: AsyncFIFOBuffered(*, width, depth, r_domain="read", w_domain="write", exact_depth=False)

diff --git a/nmigen/lib/fifo.py b/nmigen/lib/fifo.py
index defe261ce0e222676ccb8e198421cb26fc112937..49ac192de0f04b517eb998dc159219993e37292e 100644 (file)
--- a/nmigen/lib/fifo.py
+++ b/nmigen/lib/fifo.py
@@ -25,42 +25,42 @@ class FIFOInterface:
     Attributes
     ----------
     {attributes}
-    w_data : in, width
+    w_data : Signal(width), in
         Input data.
-    w_rdy : out
+    w_rdy : Signal(1), out
         Asserted if there is space in the queue, i.e. ``w_en`` can be asserted to write
         a new entry.
-    w_en : in
+    w_en : Signal(1), in
         Write strobe. Latches ``w_data`` into the queue. Does nothing if ``w_rdy`` is not asserted.
-    w_level : out
+    w_level : Signal(range(depth + 1)), out
         Number of unread entries.
     {w_attributes}
-    r_data : out, width
+    r_data : Signal(width), out
         Output data. {r_data_valid}
-    r_rdy : out
+    r_rdy : Signal(1), out
         Asserted if there is an entry in the queue, i.e. ``r_en`` can be asserted to read
         an existing entry.
-    r_en : in
+    r_en : Signal(1), in
         Read strobe. Makes the next entry (if any) available on ``r_data`` at the next cycle.
         Does nothing if ``r_rdy`` is not asserted.
-    r_level : out
+    r_level : Signal(range(depth + 1)), out
         Number of unread entries.
     {r_attributes}
     """
 
     __doc__ = _doc_template.format(description="""
     Data written to the input interface (``w_data``, ``w_rdy``, ``w_en``) is buffered and can be
-    read at the output interface (``r_data``, ``r_rdy``, ``r_en`). The data entry written first
+    read at the output interface (``r_data``, ``r_rdy``, ``r_en``). The data entry written first
     to the input also appears first on the output.
     """,
-    parameters="",
-    r_data_valid="The conditions in which ``r_data`` is valid depends on the type of the queue.",
-    attributes="""
+    parameters="""
     fwft : bool
         First-word fallthrough. If set, when ``r_rdy`` rises, the first entry is already
         available, i.e. ``r_data`` is valid. Otherwise, after ``r_rdy`` rises, it is necessary
         to strobe ``r_en`` for ``r_data`` to become valid.
     """.strip(),
+    r_data_valid="The conditions in which ``r_data`` is valid depends on the type of the queue.",
+    attributes="",
     w_attributes="",
     r_attributes="")
 
@@ -107,11 +107,12 @@ class SyncFIFO(Elaboratable, FIFOInterface):
         that entry becomes available on the output on the same clock cycle. Otherwise, it is
         necessary to assert ``r_en`` for ``r_data`` to become valid.
     """.strip(),
-    r_data_valid="""
-    For FWFT queues, valid if ``r_rdy`` is asserted. For non-FWFT queues, valid on the next
-    cycle after ``r_rdy`` and ``r_en`` have been asserted.
+    r_data_valid="For FWFT queues, valid if ``r_rdy`` is asserted. "
+                 "For non-FWFT queues, valid on the next cycle after ``r_rdy`` and ``r_en`` have been asserted.",
+    attributes="""
+    level : Signal(range(depth + 1)), out
+        Number of unread entries. This level is the same between read and write for synchronous FIFOs.
     """.strip(),
-    attributes="",
     r_attributes="",
     w_attributes="")
 
@@ -211,12 +212,12 @@ class SyncFIFOBuffered(Elaboratable, FIFOInterface):
     fwft : bool
         Always set.
     """.strip(),
-    attributes="",
-    r_data_valid="Valid if ``r_rdy`` is asserted.",
-    r_attributes="""
-    level : out
-        Number of unread entries.
+    attributes="""
+    level : Signal(range(depth + 1)), out
+        Number of unread entries. This level is the same between read and write for synchronous FIFOs.
     """.strip(),
+    r_data_valid="Valid if ``r_rdy`` is asserted.",
+    r_attributes="",
     w_attributes="")
 
     def __init__(self, *, width, depth):
@@ -282,14 +283,13 @@ class AsyncFIFO(Elaboratable, FIFOInterface):
         Read clock domain.
     w_domain : str
         Write clock domain.
-    """.strip(),
-    attributes="""
     fwft : bool
         Always set.
     """.strip(),
+    attributes="",
     r_data_valid="Valid if ``r_rdy`` is asserted.",
     r_attributes="""
-    r_rst : Signal, out
+    r_rst : Signal(1), out
         Asserted while the FIFO is being reset by the write-domain reset (for at least one
         read-domain clock cycle).
     """.strip(),
@@ -462,14 +462,13 @@ class AsyncFIFOBuffered(Elaboratable, FIFOInterface):
         Read clock domain.
     w_domain : str
         Write clock domain.
-    """.strip(),
-    attributes="""
     fwft : bool
         Always set.
     """.strip(),
+    attributes="",
     r_data_valid="Valid if ``r_rdy`` is asserted.",
     r_attributes="""
-    r_rst : Signal, out
+    r_rst : Signal(1), out
         Asserted while the FIFO is being reset by the write-domain reset (for at least one
         read-domain clock cycle).
     """.strip(),