From c23caecdba47a5e44d825185cbde119ab8fd0175 Mon Sep 17 00:00:00 2001
From: Kennedy Caisley <kcaisley@uni-bonn.de>
Date: Wed, 27 May 2026 18:18:49 +0200
Subject: [PATCH 1/2] fix(docs): Add missing pointers to README.rst files in
 docs

---
 .../{Readme.rst => README.rst}                |  0
 .../tdl_tdc/{Readme.rst => README.rst}        |  0
 docs/modules.rst                              | 65 +++++++++++++++++++
 3 files changed, 65 insertions(+)
 rename basil/firmware/arduino/EnvironmentReadout/{Readme.rst => README.rst} (100%)
 rename basil/firmware/modules/tdl_tdc/{Readme.rst => README.rst} (100%)

diff --git a/basil/firmware/arduino/EnvironmentReadout/Readme.rst b/basil/firmware/arduino/EnvironmentReadout/README.rst
similarity index 100%
rename from basil/firmware/arduino/EnvironmentReadout/Readme.rst
rename to basil/firmware/arduino/EnvironmentReadout/README.rst
diff --git a/basil/firmware/modules/tdl_tdc/Readme.rst b/basil/firmware/modules/tdl_tdc/README.rst
similarity index 100%
rename from basil/firmware/modules/tdl_tdc/Readme.rst
rename to basil/firmware/modules/tdl_tdc/README.rst
diff --git a/docs/modules.rst b/docs/modules.rst
index 1bc6cb42..a2d60731 100644
--- a/docs/modules.rst
+++ b/docs/modules.rst
@@ -144,6 +144,32 @@ No Python driver — this module operates autonomously in the FPGA fabric.
 .. autoclass:: tdc_s3
     :members:
 
+.. !!!!!!!!!!!!!
+.. !TDL_TDC!
+.. !!!!!!!!!!!!!
+
+.. include:: ../basil/firmware/modules/tdl_tdc/README.rst
+
+**Driver:**
+
+.. automodule:: basil.HL.tdl_tdc
+
+.. autoclass:: tdl_tdc
+    :members:
+
+.. !!!!!!!!!!!!!
+.. !TIMESTAMP!
+.. !!!!!!!!!!!!!
+
+.. include:: ../basil/firmware/modules/timestamp/README.rst
+
+**Driver:**
+
+.. automodule:: basil.HL.timestamp
+
+.. autoclass:: timestamp
+    :members:
+
 .. !!!!!!!!!!!!!
 .. !BRAM_FIFO!
 .. !!!!!!!!!!!!!
@@ -171,6 +197,19 @@ No Python driver — this module operates autonomously in the FPGA fabric.
 .. autoclass:: fadc_rx
     :members:
 
+.. !!!!!!!!!!!!!
+.. !M26_RX!
+.. !!!!!!!!!!!!!
+
+.. include:: ../basil/firmware/modules/m26_rx/README.rst
+
+**Driver:**
+
+.. automodule:: basil.HL.m26_rx
+
+.. autoclass:: m26_rx
+    :members:
+
 .. !!!!!!!!!!!!!
 .. !I2C!
 .. !!!!!!!!!!!!!
@@ -184,7 +223,18 @@ No Python driver — this module operates autonomously in the FPGA fabric.
 .. autoclass:: i2c
     :members:
 
+.. !!!!!!!!!!!!!
+.. !JTAG_MASTER!
+.. !!!!!!!!!!!!!
+
+.. include:: ../basil/firmware/modules/jtag_master/README.rst
+
+**Driver:**
 
+.. automodule:: basil.HL.JtagMaster
+
+.. autoclass:: JtagMaster
+    :members:
 
 .. !!!!!!!!!!!!!
 .. !UART!
@@ -198,3 +248,18 @@ No Python driver — this module operates autonomously in the FPGA fabric.
 .. !!!!!!!!!!!!!
 
 .. include:: ../basil/firmware/modules/utils/README.rst
+
+.. !!!!!!!!!!!!!
+.. !ARDUINO FIRMWARE!
+.. !!!!!!!!!!!!!
+
+Arduino firmware
+================
+
+.. include:: ../basil/firmware/arduino/EnvironmentReadout/README.rst
+
+.. include:: ../basil/firmware/arduino/NTCReadout/README.rst
+
+.. include:: ../basil/firmware/arduino/RelayBoard/README.rst
+
+.. include:: ../basil/firmware/arduino/SerialToI2C/README.rst

From 18352ccb12aa6ea767bc34d50ddd8c3d70bcf6b5 Mon Sep 17 00:00:00 2001
From: Kennedy Caisley <kcaisley@uni-bonn.de>
Date: Thu, 28 May 2026 12:57:26 +0200
Subject: [PATCH 2/2] docs: document missing firmware READMEs

---
 basil/HL/bram_fifo.py                         |  31 +-
 basil/HL/sram_fifo.py                         | 280 ++++++++++--------
 .../arduino/EnvironmentReadout/README.rst     |   4 +-
 basil/firmware/modules/sram_fifo/README.rst   |  79 +++++
 basil/firmware/modules/tdl_tdc/README.rst     |   4 +-
 docs/README.md                                |  53 ++++
 docs/modules.rst                              |  15 +-
 docs/requirements.txt                         |   1 +
 pyproject.toml                                |   4 +
 9 files changed, 341 insertions(+), 130 deletions(-)
 create mode 100644 basil/firmware/modules/sram_fifo/README.rst
 create mode 100644 docs/README.md

diff --git a/basil/HL/bram_fifo.py b/basil/HL/bram_fifo.py
index f3affc2c..9e1a1d26 100644
--- a/basil/HL/bram_fifo.py
+++ b/basil/HL/bram_fifo.py
@@ -16,7 +16,16 @@
 
 
 class bram_fifo(RegisterHardwareLayer):
-    """BRAM FIFO controller interface for bram_fifo FPGA module."""
+    """BRAM-backed FIFO controller.
+
+    The corresponding firmware module stores incoming 32-bit FIFO words in
+    FPGA BRAM. The regular ``base_addr`` configuration key addresses the
+    control registers, while ``base_data_addr`` must point to the 32-bit data
+    window used by :meth:`get_data`.
+
+    ``FIFO_SIZE`` reports the amount of buffered data in bytes. The driver
+    rounds this down to complete 32-bit words before reading data.
+    """
 
     _registers = {
         "RESET": {"descr": {"addr": 0, "size": 8, "properties": ["writeonly"]}},
@@ -29,9 +38,20 @@ class bram_fifo(RegisterHardwareLayer):
     _require_version = "==2"
 
     def __init__(self, intf, conf):
+        """Create a BRAM FIFO driver.
+
+        Parameters
+        ----------
+        intf : basil transfer layer
+            Interface used for control-register and data-window access.
+        conf : dict
+            Driver configuration. Requires ``base_addr`` for the control
+            registers and ``base_data_addr`` for the FIFO data window.
+        """
         super(bram_fifo, self).__init__(intf, conf)
 
     def reset(self):
+        """Soft-reset the FIFO and wait briefly for the firmware to settle."""
         self.RESET = 0
         sleep(0.01)  # wait some time for initialization
 
@@ -59,12 +79,17 @@ def get_FIFO_INT_SIZE(self):
         return self.FIFO_INT_SIZE
 
     def get_data(self):
-        """Reading data in BRAM.
+        """Read all currently buffered complete 32-bit words.
+
+        The method reads ``FIFO_SIZE`` twice and uses the smaller value to
+        avoid requesting more data while the FIFO size is changing. Data are
+        read from ``base_data_addr`` and returned as little-endian unsigned
+        32-bit integers.
 
         Returns
         -------
         array : numpy.ndarray
-            Array of unsigned integers (32 bit).
+            Array of unsigned 32-bit FIFO words.
         """
         fifo_int_size_1 = self.FIFO_INT_SIZE
         fifo_int_size_2 = self.FIFO_INT_SIZE
diff --git a/basil/HL/sram_fifo.py b/basil/HL/sram_fifo.py
index 19413ae8..33bd7f6a 100644
--- a/basil/HL/sram_fifo.py
+++ b/basil/HL/sram_fifo.py
@@ -1,122 +1,158 @@
-#
-# ------------------------------------------------------------
-# Copyright (c) All rights reserved
-# SiLab, Institute of Physics, University of Bonn
-# ------------------------------------------------------------
-#
-
-import logging
-from time import sleep
-
-import numpy as np
-
-from basil.HL.RegisterHardwareLayer import RegisterHardwareLayer
-
-logger = logging.getLogger(__name__)
-
-
-class sram_fifo(RegisterHardwareLayer):
-    """SRAM FIFO controller interface for sram_fifo FPGA module."""
-
-    _registers = {
-        "RESET": {"descr": {"addr": 0, "size": 8, "properties": ["writeonly"]}},
-        "VERSION": {"descr": {"addr": 0, "size": 8, "properties": ["ro"]}},
-        "ALMOST_FULL_THRESHOLD": {"descr": {"addr": 1, "size": 8}},
-        "ALMOST_EMPTY_THRESHOLD": {"descr": {"addr": 2, "size": 8}},
-        "READ_ERROR_COUNTER": {"descr": {"addr": 3, "size": 8, "properties": ["ro"]}},
-        "FIFO_SIZE": {"descr": {"addr": 4, "size": 32, "properties": ["ro"]}},
-    }
-    _require_version = "==2"
-
-    def __init__(self, intf, conf):
-        super(sram_fifo, self).__init__(intf, conf)
-
-    def reset(self):
-        self.RESET = 0
-        sleep(0.01)  # wait some time for initialization
-
-    def set_almost_full_threshold(self, value):
-        self.ALMOST_FULL_THRESHOLD = value  # no get function possible
-
-    def set_almost_empty_threshold(self, value):
-        self.ALMOST_EMPTY_THRESHOLD = value  # no get function possible
-
-    def get_fifo_size(self):
-        """*Deprecated* Get FIFO size in units of bytes (8 bit).
-
-        Returns
-        -------
-        fifo_size : int
-            FIFO size in units of bytes (8 bit).
-        """
-        logger.warning("Deprecated: Use get_FIFO_SIZE()")
-        return self.FIFO_SIZE
-
-    @property
-    def FIFO_INT_SIZE(self):
-        """Get FIFO size in units of integers (32 bit).
-
-        Returns
-        -------
-        fifo_size : int
-            FIFO size in units of integers (32 bit).
-        """
-        fifo_size = self.FIFO_SIZE
-        # sometimes reading of FIFO size happens during writing to SRAM, but we want to have a multiplicity of 32 bits
-        return int((fifo_size - (fifo_size % 4)) / 4)
-
-    def get_fifo_int_size(self):
-        """*Deprecated* Get FIFO size in units of integers (32 bit).
-
-        Returns
-        -------
-        fifo_size : int
-            FIFO size in units of integers (32 bit).
-        """
-        logger.warning("Deprecated: Use get_FIFO_INT_SIZE()")
-        return self.FIFO_INT_SIZE
-
-    def get_FIFO_INT_SIZE(self):
-        """Get FIFO size in units of integers (32 bit).
-
-        Returns
-        -------
-        fifo_size : int
-            FIFO size in units of integers (32 bit).
-        """
-        return self.FIFO_INT_SIZE
-
-    def get_read_error_counter(self):
-        """*Deprecated* Get read error counter.
-
-        Returns
-        -------
-        fifo_size : int
-            Read error counter (read attempts when SRAM is empty).
-        """
-        logger.warning("Deprecated: Use get_READ_ERROR_COUNTER()")
-        return self.READ_ERROR_COUNTER
-
-    def get_data(self):
-        """Reading data in SRAM.
-
-        Returns
-        -------
-        array : numpy.ndarray
-            Array of unsigned integers (32 bit).
-        """
-        fifo_int_size_1 = self.FIFO_INT_SIZE
-        fifo_int_size_2 = self.FIFO_INT_SIZE
-        if fifo_int_size_1 > fifo_int_size_2:
-            fifo_int_size = fifo_int_size_2  # use smaller chunk
-            logger.warning("Reading wrong FIFO size. Expected: %d <= %d" % (fifo_int_size_1, fifo_int_size_2))
-        else:
-            fifo_int_size = fifo_int_size_1  # use smaller chunk
-        return np.frombuffer(
-            self._intf.read(self._conf["base_data_addr"], size=4 * fifo_int_size), dtype=np.dtype("<u4")
-        )  # size in number of bytes
-
-    def get_size(self):
-        """*Deprecated*"""
-        logger.warning("Deprecated: Use get_FIFO_SIZE()")
-        return self.FIFO_SIZE
+#
+# ------------------------------------------------------------
+# Copyright (c) All rights reserved
+# SiLab, Institute of Physics, University of Bonn
+# ------------------------------------------------------------
+#
+
+import logging
+from time import sleep
+
+import numpy as np
+
+from basil.HL.RegisterHardwareLayer import RegisterHardwareLayer
+
+logger = logging.getLogger(__name__)
+
+
+class sram_fifo(RegisterHardwareLayer):
+    """External-SRAM-backed FIFO controller.
+
+    The corresponding firmware module stores incoming 32-bit FIFO words in an
+    external 16-bit SRAM. The regular ``base_addr`` configuration key addresses
+    the control registers. ``base_data_addr`` must point to the transfer-layer
+    data path used by :meth:`get_data` to drain buffered FIFO words.
+
+    ``FIFO_SIZE`` reports the amount of buffered data in bytes. The driver
+    rounds this down to complete 32-bit words before reading data.
+    """
+
+    _registers = {
+        "RESET": {"descr": {"addr": 0, "size": 8, "properties": ["writeonly"]}},
+        "VERSION": {"descr": {"addr": 0, "size": 8, "properties": ["ro"]}},
+        "ALMOST_FULL_THRESHOLD": {"descr": {"addr": 1, "size": 8}},
+        "ALMOST_EMPTY_THRESHOLD": {"descr": {"addr": 2, "size": 8}},
+        "READ_ERROR_COUNTER": {"descr": {"addr": 3, "size": 8, "properties": ["ro"]}},
+        "FIFO_SIZE": {"descr": {"addr": 4, "size": 32, "properties": ["ro"]}},
+    }
+    _require_version = "==2"
+
+    def __init__(self, intf, conf):
+        """Create an SRAM FIFO driver.
+
+        Parameters
+        ----------
+        intf : basil transfer layer
+            Interface used for control-register and data-path access.
+        conf : dict
+            Driver configuration. Requires ``base_addr`` for the control
+            registers and ``base_data_addr`` for the FIFO data path.
+        """
+        super(sram_fifo, self).__init__(intf, conf)
+
+    def reset(self):
+        """Soft-reset the FIFO and wait briefly for the firmware to settle."""
+        self.RESET = 0
+        sleep(0.01)  # wait some time for initialization
+
+    def set_almost_full_threshold(self, value):
+        """Set the 8-bit almost-full threshold register.
+
+        The firmware compares this value against the SRAM occupancy as a
+        fraction of ``DEPTH`` and asserts ``FIFO_NEAR_FULL`` once the threshold
+        is reached.
+        """
+        self.ALMOST_FULL_THRESHOLD = value  # no get function possible
+
+    def set_almost_empty_threshold(self, value):
+        """Set the 8-bit almost-empty threshold register.
+
+        ``FIFO_NEAR_FULL`` is deasserted again once the SRAM occupancy falls
+        below the fraction of ``DEPTH`` represented by this value.
+        """
+        self.ALMOST_EMPTY_THRESHOLD = value  # no get function possible
+
+    def get_fifo_size(self):
+        """*Deprecated* Get FIFO size in units of bytes (8 bit).
+
+        Returns
+        -------
+        fifo_size : int
+            FIFO size in units of bytes (8 bit).
+        """
+        logger.warning("Deprecated: Use get_FIFO_SIZE()")
+        return self.FIFO_SIZE
+
+    @property
+    def FIFO_INT_SIZE(self):
+        """Get FIFO size in units of integers (32 bit).
+
+        Returns
+        -------
+        fifo_size : int
+            FIFO size in units of integers (32 bit).
+        """
+        fifo_size = self.FIFO_SIZE
+        # sometimes reading of FIFO size happens during writing to SRAM, but we want to have a multiplicity of 32 bits
+        return int((fifo_size - (fifo_size % 4)) / 4)
+
+    def get_fifo_int_size(self):
+        """*Deprecated* Get FIFO size in units of integers (32 bit).
+
+        Returns
+        -------
+        fifo_size : int
+            FIFO size in units of integers (32 bit).
+        """
+        logger.warning("Deprecated: Use get_FIFO_INT_SIZE()")
+        return self.FIFO_INT_SIZE
+
+    def get_FIFO_INT_SIZE(self):
+        """Get FIFO size in units of integers (32 bit).
+
+        Returns
+        -------
+        fifo_size : int
+            FIFO size in units of integers (32 bit).
+        """
+        return self.FIFO_INT_SIZE
+
+    def get_read_error_counter(self):
+        """*Deprecated* Get read error counter.
+
+        Returns
+        -------
+        fifo_size : int
+            Read error counter (read attempts when SRAM is empty).
+        """
+        logger.warning("Deprecated: Use get_READ_ERROR_COUNTER()")
+        return self.READ_ERROR_COUNTER
+
+    def get_data(self):
+        """Read all currently buffered complete 32-bit words.
+
+        The method reads ``FIFO_SIZE`` twice and uses the smaller value to
+        avoid requesting more data while the FIFO size is changing. Data are
+        read from ``base_data_addr`` and returned as little-endian unsigned
+        32-bit integers.
+
+        Returns
+        -------
+        array : numpy.ndarray
+            Array of unsigned 32-bit FIFO words.
+        """
+        fifo_int_size_1 = self.FIFO_INT_SIZE
+        fifo_int_size_2 = self.FIFO_INT_SIZE
+        if fifo_int_size_1 > fifo_int_size_2:
+            fifo_int_size = fifo_int_size_2  # use smaller chunk
+            logger.warning("Reading wrong FIFO size. Expected: %d <= %d" % (fifo_int_size_1, fifo_int_size_2))
+        else:
+            fifo_int_size = fifo_int_size_1  # use smaller chunk
+        return np.frombuffer(
+            self._intf.read(self._conf["base_data_addr"], size=4 * fifo_int_size), dtype=np.dtype("<u4")
+        )  # size in number of bytes
+
+    def get_size(self):
+        """*Deprecated*"""
+        logger.warning("Deprecated: Use get_FIFO_SIZE()")
+        return self.FIFO_SIZE
diff --git a/basil/firmware/arduino/EnvironmentReadout/README.rst b/basil/firmware/arduino/EnvironmentReadout/README.rst
index b575d06c..7b225954 100644
--- a/basil/firmware/arduino/EnvironmentReadout/README.rst
+++ b/basil/firmware/arduino/EnvironmentReadout/README.rst
@@ -1,6 +1,6 @@
-======================================
+=========================================================================
 Arduino Firmware for Environment Readout (temperature, humidity/pressure)
-======================================
+=========================================================================
 
 Arduino Nano firmware to read out NTCs via the 8 analog input pins A0 to A7 and the internal (multiplexed) ADC.
 
diff --git a/basil/firmware/modules/sram_fifo/README.rst b/basil/firmware/modules/sram_fifo/README.rst
new file mode 100644
index 00000000..05707978
--- /dev/null
+++ b/basil/firmware/modules/sram_fifo/README.rst
@@ -0,0 +1,79 @@
+
+=====================================
+**sram_fifo** - data FIFO (SRAM)
+=====================================
+
+Data FIFO implemented using external 16-bit SRAM memory. Incoming 32-bit FIFO words are buffered internally and written to SRAM as two 16-bit words. Data are read back from SRAM through the ``USB_READ`` / ``USB_DATA`` interface.
+
+**Parameters:**
+    +-----------------------------+---------------------+------------------------------------------------------+
+    | Name                        | Default             | Description                                          |
+    +=============================+=====================+======================================================+
+    | BASEADDR                    | 16'h0000            | Base address for the control register bus            |
+    +-----------------------------+---------------------+------------------------------------------------------+
+    | HIGHADDR                    | 16'h0000            | High address for the control register bus            |
+    +-----------------------------+---------------------+------------------------------------------------------+
+    | ABUSWIDTH                   | 16                  | Address bus width                                    |
+    +-----------------------------+---------------------+------------------------------------------------------+
+    | DEPTH                       | 21'h10_0000         | FIFO depth in 16-bit SRAM words                      |
+    +-----------------------------+---------------------+------------------------------------------------------+
+    | FIFO_ALMOST_FULL_THRESHOLD  | 95                  | Almost-full threshold in percent                     |
+    +-----------------------------+---------------------+------------------------------------------------------+
+    | FIFO_ALMOST_EMPTY_THRESHOLD | 5                   | Almost-empty threshold in percent                    |
+    +-----------------------------+---------------------+------------------------------------------------------+
+
+**Pins:**
+    +--------------------+---------------------+-----------+------------------------------------------------------+
+    | Name               | Size                | Direction | Description                                          |
+    +====================+=====================+===========+======================================================+
+    | SRAM_A             | 20                  | output    | External SRAM address bus                            |
+    +--------------------+---------------------+-----------+------------------------------------------------------+
+    | SRAM_IO            | 16                  | inout     | External SRAM data bus                               |
+    +--------------------+---------------------+-----------+------------------------------------------------------+
+    | SRAM_BHE_B         | 1                   | output    | SRAM upper-byte enable, active low                   |
+    +--------------------+---------------------+-----------+------------------------------------------------------+
+    | SRAM_BLE_B         | 1                   | output    | SRAM lower-byte enable, active low                   |
+    +--------------------+---------------------+-----------+------------------------------------------------------+
+    | SRAM_CE1_B         | 1                   | output    | SRAM chip enable, active low                         |
+    +--------------------+---------------------+-----------+------------------------------------------------------+
+    | SRAM_OE_B          | 1                   | output    | SRAM output enable, active low                       |
+    +--------------------+---------------------+-----------+------------------------------------------------------+
+    | SRAM_WE_B          | 1                   | output    | SRAM write enable, active low                        |
+    +--------------------+---------------------+-----------+------------------------------------------------------+
+    | USB_READ           | 1                   | input     | Read strobe for the USB data output                  |
+    +--------------------+---------------------+-----------+------------------------------------------------------+
+    | USB_DATA           | 8                   | output    | USB data output                                      |
+    +--------------------+---------------------+-----------+------------------------------------------------------+
+    | FIFO_READ_NEXT_OUT | 1                   | output    | Request next 32-bit input FIFO word                  |
+    +--------------------+---------------------+-----------+------------------------------------------------------+
+    | FIFO_EMPTY_IN      | 1                   | input     | Input FIFO empty flag                                |
+    +--------------------+---------------------+-----------+------------------------------------------------------+
+    | FIFO_DATA          | 32                  | input     | Input FIFO data word                                 |
+    +--------------------+---------------------+-----------+------------------------------------------------------+
+    | FIFO_NOT_EMPTY     | 1                   | output    | SRAM FIFO contains data                              |
+    +--------------------+---------------------+-----------+------------------------------------------------------+
+    | FIFO_FULL          | 1                   | output    | SRAM FIFO is full                                    |
+    +--------------------+---------------------+-----------+------------------------------------------------------+
+    | FIFO_NEAR_FULL     | 1                   | output    | SRAM FIFO crossed the almost-full threshold          |
+    +--------------------+---------------------+-----------+------------------------------------------------------+
+    | FIFO_READ_ERROR    | 1                   | output    | A read was attempted while the SRAM FIFO was empty   |
+    +--------------------+---------------------+-----------+------------------------------------------------------+
+
+**Registers:**
+    +------------------------+---------+-------+------------------------------------------------------+
+    | Name                   | Address | r/w   | Description                                          |
+    +========================+=========+=======+======================================================+
+    | RESET                  | 0       | wo    | Soft reset on write to address                       |
+    +------------------------+---------+-------+------------------------------------------------------+
+    | VERSION                | 0       | ro    | Module version                                       |
+    +------------------------+---------+-------+------------------------------------------------------+
+    | ALMOST_FULL_THRESHOLD  | 1       | r/w   | Almost-full threshold value                          |
+    +------------------------+---------+-------+------------------------------------------------------+
+    | ALMOST_EMPTY_THRESHOLD | 2       | r/w   | Almost-empty threshold value                         |
+    +------------------------+---------+-------+------------------------------------------------------+
+    | READ_ERROR_COUNTER     | 3       | ro    | Read attempts while the SRAM FIFO is empty           |
+    +------------------------+---------+-------+------------------------------------------------------+
+    | FIFO_SIZE              | 4 - 7   | ro    | Stored FIFO data size in bytes                       |
+    +------------------------+---------+-------+------------------------------------------------------+
+
+The ``FIFO_SIZE`` register is exposed as a 32-bit value by the Python driver. The firmware currently reports a 22-bit byte count and returns zero for the upper byte at address 7.
diff --git a/basil/firmware/modules/tdl_tdc/README.rst b/basil/firmware/modules/tdl_tdc/README.rst
index 72028042..3bbca19b 100644
--- a/basil/firmware/modules/tdl_tdc/README.rst
+++ b/basil/firmware/modules/tdl_tdc/README.rst
@@ -207,8 +207,8 @@ The TDC is built around the delay line found in the `Link jTDC <https://github.c
 
 In order to sample the delay elements at a high enough rate while still being able to process them, we use a 3x multisampling approach: There is a shift register shifting in the entire information of the delay line using the 3x clock and at every slow clock tick the contents of the shift register are copied for further processing in the slow clock domain. Only then do we detect signal transitions and convert the thermometer code to binary.
 
-.. image:: delayline.png
+.. image:: ../basil/firmware/modules/tdl_tdc/delayline.png
 
 The most distinct design choice in this implementation is that it uses only a single delay line for measuring rising and falling edges of two inputs. As rising and falling edges propagate delay elements differently it makes sense to treat with distinct calibrations or even separate delay lines. To circumvent this additional space requirement and complexity, we use a multiplexer co-ordinating which input, in which polarity, gets seen by the delay elements. This induces a lower bound on width of pulses we can measure as this input multiplexer needs some time to switch between signals. To drive the multiplexer we use a simple state machine, which also drives the word output generation in the ``word_broker`` module.
 
-.. image:: architecture.png
+.. image:: ../basil/firmware/modules/tdl_tdc/architecture.png
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..06dfdcbf
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,53 @@
+# Building the documentation
+
+Basil documentation is built with Sphinx from the files in this directory.
+The build imports the local `basil` Python package for autodoc, so install the package itself in addition to the documentation dependencies.
+
+## System dependency
+
+Install Graphviz so Sphinx can render diagrams from `sphinx.ext.graphviz`.
+
+On Debian/Ubuntu:
+
+```bash
+sudo apt-get update
+sudo apt-get install graphviz
+```
+
+On Fedora/RHEL:
+
+```bash
+sudo dnf install graphviz
+```
+
+## Python environment
+
+From the repository root, create and activate a virtual environment with any supported Python version (Python 3.10 or newer):
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip setuptools wheel
+```
+
+Install using the `docs` optional dependency target:
+
+```bash
+python -m pip install -e ".[docs]"
+```
+
+## Build
+
+Build the HTML documentation:
+
+```bash
+python -m sphinx -b html docs docs/_build/html
+```
+
+For a stricter local check that fails on warnings:
+
+```bash
+python -m sphinx -b html -W --keep-going docs docs/_build/html
+```
+
+Open `docs/_build/html/index.html` in a browser to view the result.
diff --git a/docs/modules.rst b/docs/modules.rst
index a2d60731..952ae3d7 100644
--- a/docs/modules.rst
+++ b/docs/modules.rst
@@ -178,12 +178,24 @@ No Python driver — this module operates autonomously in the FPGA fabric.
 
 **Driver:**
 
+.. automodule:: basil.HL.bram_fifo
+
+.. autoclass:: bram_fifo
+    :members:
+
+.. !!!!!!!!!!!!!
+.. !SRAM_FIFO!
+.. !!!!!!!!!!!!!
+
+.. include:: ../basil/firmware/modules/sram_fifo/README.rst
+
+**Driver:**
+
 .. automodule:: basil.HL.sram_fifo
 
 .. autoclass:: sram_fifo
     :members:
 
-
 .. !!!!!!!!!!!!!
 .. !GPAC_ADC_RX!
 .. !!!!!!!!!!!!!
@@ -253,6 +265,7 @@ No Python driver — this module operates autonomously in the FPGA fabric.
 .. !ARDUINO FIRMWARE!
 .. !!!!!!!!!!!!!
 
+================
 Arduino firmware
 ================
 
diff --git a/docs/requirements.txt b/docs/requirements.txt
index bb21c37e..f2d59b97 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,3 +1,4 @@
+sphinx
 sphinx-book-theme
 bitarray
 pyyaml
diff --git a/pyproject.toml b/pyproject.toml
index a9563103..56435b11 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -35,6 +35,10 @@ dependencies = [
 
 [project.optional-dependencies]
 hw = ["pyserial", "PyVISA"]
+docs = [
+    "sphinx",
+    "sphinx-book-theme",
+]
 
 [tool.setuptools]
 include-package-data = true