Improve I2C and SPI register documentation

Signed-off-by: gatecat <gatecat@ds0.me>

Author: gatecat

chipflow_digital_ip/io/i2c.py

@@ -15,17 +15,47 @@
 
 
 class I2CPeripheral(wiring.Component):
+    """
+    A minimal I2C controller wrapping the Glasgow core
+
+    Support for customisable clock frequency and byte-wise transfers.
+    """
+
     class Divider(csr.Register, access="rw"):
-        """I2C SCK clock divider, 1 = divide by 4"""
+        """Divider register.
+
+        This :class:`Register` is used to configure the clock frequency of the I2C peripheral.
+
+        The SCK frequency is the input clock frequency divided by 4 times the value in this register.
+        For example, for a SCK of 1/12 the system clock, this register would be set to 3.
+        """
         val: csr.Field(csr.action.RW, unsigned(12))
 
     class Action(csr.Register, access="w"):
-        """
-        reset: reset the core, e.g. in case of a bus lockup
-        start: write 1 to trigger I2C start
-        stop: write 1 to trigger I2C stop
-        read_ack: write 1 to trigger I2C read and ACK
-        read_nack: write 1 to trigger I2C read and NACK
+        """Action register.
+
+        This :class:`Register` is written to in order to perform various actions on the I2C bus.
+        Writing ``0b1`` to a field performs that action, it is only valid to set one field at a time.
+
+        It has the following fields:
+
+        .. bitfield::
+            :bits: 8
+
+                [
+                    { "name": "reset", "bits": 1, "attr": "W" },
+                    { "name": "start", "bits": 1, "attr": "W" },
+                    { "name": "stop", "bits": 1, "attr": "W" },
+                    { "name": "read_ack", "bits": 1, "attr": "W" },
+                    { "name": "read_nack", "bits": 1, "attr": "W" },
+                    { "bits": 3, "attr": "ResR0W0" },
+                ]
+
+        - The ``reset`` field is used to reset the PHY in case of a lock-up (e.g. SCK stuck low)
+        - The ``start`` field sends an I2C start
+        - The ``stop`` field sends an I2C stop
+        - The ``read_ack`` field begins an I2C read, followed by an ACK
+        - The ``read_nack`` field begins an I2C read, followed by a NACK
         """
         reset: csr.Field(csr.action.W, unsigned(1))
         start: csr.Field(csr.action.W, unsigned(1))
@@ -35,20 +65,61 @@ class Action(csr.Register, access="w"):
 
 
     class SendData(csr.Register, access="w"):
-        """writes the given data onto the I2C bus when written to"""
+        """SendData register.
+
+        Writing to this :class:`Register` sends a byte on the I2C bus. 
+
+        It has the following fields:
+
+        .. bitfield::
+            :bits: 8
+
+                [
+                    { "name": "val", "bits": 8, "attr": "W" },
+                ]
+
+        """
         val: csr.Field(csr.action.W, unsigned(8))
 
     class ReceiveData(csr.Register, access="r"):
-        """data received from the last read"""
+        """ReceiveData register.
+
+        This :class:`Register` contains the result of the last read started using `read_ack` or `read_nack`.
+
+        It has the following fields:
+
+        .. bitfield::
+            :bits: 8
+
+                [
+                    { "name": "val", "bits": 8, "attr": "R" },
+                ]
+
+        """
         val: csr.Field(csr.action.R, unsigned(8))
 
     class Status(csr.Register, access="r"):
+        """Status register.
+
+        This :class:`Register` contains the status of the peripheral.
+
+        It has the following fields:
+
+        .. bitfield::
+            :bits: 8
+
+                [
+                    { "name": "busy", "bits": 1, "attr": "R" },
+                    { "name": "ack", "bits": 1, "attr": "R" },
+                    { "bits": 6, "attr": "ResR0" },
+                ]
+
+        - The ``busy`` field is set when the PHY is currently performing an action, and unable to accept any requests.
+        - The ``ack`` field contains the ACK/NACK value of the last write.
+        """
         busy: csr.Field(csr.action.R, unsigned(1))
         ack: csr.Field(csr.action.R, unsigned(1))
 
-    """
-    A minimal I2C controller wrapping the Glasgow core
-    """
     def __init__(self):
         regs = csr.Builder(addr_width=5, data_width=8)
 

chipflow_digital_ip/io/spi.py

@@ -111,40 +111,108 @@ def elaborate(self, platform):
 
 
 class SPIPeripheral(wiring.Component):
+    """
+    A custom, minimal SPI controller
+
+    Transfers up to a width of 32 bits are supported, as are all SPI modes.
+    """
+
     class Config(csr.Register, access="rw"):
-        """
-        sck_idle: idle state of sck, '1' to invert sck
-        sck_edge:
-            1 to latch output on rising sck edge, read input on falling sck edge
-            0 to read input on rising sck edge, latch output on falling sck edge
-        chip_select: write '1' to assert (bring low) chip select output
-        width: width of transfer, minus 1
+        """Config register.
+
+        This :class:`Register` is written to in order to configure the SPI mode and transaction.
+
+        It has the following fields:
+
+        .. bitfield::
+            :bits: 8
+
+                [
+                    { "name": "sck_idle", "bits": 1, "attr": "RW" },
+                    { "name": "sck_edge", "bits": 1, "attr": "RW" },
+                    { "name": "chip_select", "bits": 1, "attr": "RW" },
+                    { "name": "width", "bits": 5, "attr": "RW" },
+                ]
+
+        - The ``sck_idle`` field is used to invert the SCK polarity, ``0b0`` for an idle low SCK, ``0b1`` for an idle high SCK
+        - The ``sck_edge`` field selects which edge is used for input and output data.
+            - ``0b0`` to read input on rising SCK edge, latch output on falling SCK edge
+            - ``0b1`` to latch output on rising SCK edge, read input on falling SCK edge
+        - The ``chip_select`` field controls the CS pin; setting it to ``0b1`` asserts (brings low) chip select.
+        - The ``width`` field configures the width of the transfer. It is set to the width of the transfer minus 1,
+        ``31`` gives the maximum width of 32.
         """
         sck_idle: csr.Field(csr.action.RW, unsigned(1))
         sck_edge: csr.Field(csr.action.RW, unsigned(1))
         chip_select: csr.Field(csr.action.RW, unsigned(1))
         width: csr.Field(csr.action.RW, unsigned(5))
 
     class Divider(csr.Register, access="rw"):
-        """SPI SCK clock divider, 1 = divide by 4"""
+        """Divider register.
+
+        This :class:`Register` is used to configure the clock frequency of the I2C peripheral.
+
+        The SCK frequency is the input clock frequency divided by 4 times the value in this register.
+        For example, for a SCK of 1/12 the system clock, this register would be set to 3.
+        """
         val: csr.Field(csr.action.RW, unsigned(8))
 
     class SendData(csr.Register, access="w"):
-        """data to transmit, must be left justified (bits [31..32-N] used)"""
+        """SendData register.
+
+        Writing to this :class:`Register` starts a read/write transfer on the SPI bus, the width of which is configured in `Config`.
+
+        It has the following fields:
+
+        .. bitfield::
+            :bits: 32
+
+                [
+                    { "name": "val", "bits": 32, "attr": "W" },
+                ]
+
+        - The `val` field must be left-justified, so for a transfer of ``N`` bits, bits ``[31..32-N]`` are used.
+        """
+
         val: csr.Field(csr.action.W, unsigned(32))
 
     class ReceiveData(csr.Register, access="r"):
-        """data received, is right justified (bits [N-1..0] used)"""
+        """ReceiveData register.
+
+        This :class:`Register` contains the read data of the last transfer started with a write to ``SendData``.
+
+        It has the following fields:
+
+        .. bitfield::
+            :bits: 8
+
+                [
+                    { "name": "val", "bits": 32, "attr": "R" },
+                ]
+
+        - The `val` field is right-justified, so for a transfer of ``N`` bits, bits ``[N-1..0]`` are used.
+        """
         val: csr.Field(csr.action.R, unsigned(32))
 
     class Status(csr.Register, access="r"):
-        """recv_full is 1 when transfer has been completed. reset to zero by reading receive_data"""
-        recv_full: csr.Field(csr.action.R, unsigned(1))
+        """Status register.
 
+        This :class:`Register` contains the status of the peripheral.
+
+        It has the following fields:
+
+        .. bitfield::
+            :bits: 8
+
+                [
+                    { "name": "recv_full", "bits": 1, "attr": "R" },
+                    { "bits": 7, "attr": "ResR0" },
+                ]
+
+        - The ``recv_full`` field is set to ``0b1`` when a transfer is completed. It is reset to zero by reading ``ReceiveData``.
+        """
+        recv_full: csr.Field(csr.action.R, unsigned(1))
 
-    """
-    A custom, minimal SPI controller
-    """
     def __init__(self):
         regs = csr.Builder(addr_width=5, data_width=8)
 

chipflow_digital_ip/io/uart.py

@@ -130,6 +130,8 @@ def __init__(self):
 
     """Wrapper for amaranth_soc RFC UART with PHY and chipflow_lib.IOSignature support
 
+    See rfc_uart.py for detailed register documentation.
+
     Parameters
     ----------
     addr_width : :class:`int`