DEM UART: Fix headline hierarchies

And include captions for the labels.

Author: imphil

src/02_spec/07_modules/dem_uart/index.rst

@@ -4,76 +4,15 @@ UART Device Emulation Module (DEM-UART)
 .. figure:: img/osd_dem_uart.*
    :alt: Device Emulation Module UART
 
+   High-Level Overview of the Device Emulation Module for UART (DEM-UART)
+
 The UART Device Emulation Module connects to the bus of a given CPU on one side, and to the Debug Interconnect on the other.
 Towards the CPU it behaves like a UART-16550A device, but instead of transmitting information over a UART-Interface it instead passes it to a host PC via the Debug Interconnect.
 
-.. _uart-registers:
-
-16550 UART Registers
---------------------
-The following UART registers are implemented and accessible via the bus, the address mapping is in accordance with the UART-16550(A) standard as specified in this `Datasheet <http://caro.su/msx/ocm_de1/16550.pdf>`_.
-No FIFOs are present in hardware.
-No Modem or DMA-Mode related features, registers or interrupts are implemented.
-Writing to a register that is not implemented has no effect, reading from such a register will always return ``0x00``.
-
-All registers are 8 bit wide.
-
-.. tabularcolumns:: |p{\dimexpr 0.10\linewidth-2\tabcolsep}|p{\dimexpr 0.10\linewidth-2\tabcolsep}|p{\dimexpr 0.20\linewidth-2\tabcolsep}|p{\dimexpr 0.10\linewidth-2\tabcolsep}|p{\dimexpr 0.50\linewidth-2\tabcolsep}|
-.. flat-table:: 16550 UART Registers
-  :widths: 1 1 2 1 5
-  :header-rows: 1
-
-  * - Address
-    - Register
-    - Access Type
-    - Reset Value
-    - Description
-
-  * - ``0x00``
-    - ``RBR``
-    - Read only
-    - ``0x00``
-    - Receiver Buffer Register
-
-  * - ``0x00``
-    - ``THR``
-    - Write only
-    - ``0x00``
-    - Transmitter Holding Register
-
-  * - ``0x01``
-    - ``IER``
-    - Read/Write
-    - ``0x00``
-    - Enable(1)/Disable(0) interrupts. See `this <http://caro.su/msx/ocm_de1/16550.pdf>`_ for more details on each interrupt.
-
-  * - ``0x02``
-    - ``IIR``
-    - Read only
-    - ``0x01``
-    - Information which interrupt occurred
-
-  * - ``0x02``
-    - ``FCR``
-    - Write only
-    - ``0x00``
-    - Control behavior of the internal FIFOs. Currently writing to this Register has no effect.
-
-  * - ``0x03``
-    - ``LCR``
-    - Read/Write
-    - ``0x00``
-    - The only bit in this register that has any meaning is ``LCR7`` aka the DLAB, all other bits hold their written value but have no meaning.
-
-  * - ``0x05``
-    - ``LSR``
-    - Read only
-    - ``0x60``
-    - Information about state of the UART. After the UART is reset, ``0x60`` indicates when it is ready to transmit data.
-
 .. toctree::
    :maxdepth: 1
 
-   systemif
    dbgregisters
    datainterface
+   uartspec
+   systemif

src/02_spec/07_modules/dem_uart/systemif.rst

@@ -23,9 +23,14 @@ We specify a Wishbone wrapper interface below.
 .. figure:: img/bus_write_diagram.*
    :alt: A typical write cycle
 
+   A typical write cycle
+
+
 .. figure:: img/bus_read_diagram.*
    :alt: A typical read cycle
 
+   A typical read cycle
+
 A new request is made by asserting ``bus_req``, unless ``bus_req`` is asserted, no other signal is valid.
 ``bus_write`` indicates whether it is a read (0) or a write (1) request.
 ``bus_addr`` may be any of the values documented under :ref:`uart-registers`.
@@ -37,8 +42,9 @@ Finally ``bus_ack`` is asserted to confirm the request and end the cycle.
 ``bus_rdata`` is only valid when ``bus_ack`` is asserted and ``bus_write`` is negated.
 
 
-Wishbone Bus
-------------
+Wishbone Bus Interface
+^^^^^^^^^^^^^^^^^^^^^^
+
 If a wishbone interface is present, it should wrap around the generic bus described above and take
 care of translating all the signals.
 The following signals MUST be present on a compatible WISHBONE bus.
@@ -63,4 +69,4 @@ The following signals MUST be present on a compatible WISHBONE bus.
 | ``wb_dat_o``    | 32          | DEM->CPU      | Data that was read from the register            |
 +-----------------+-------------+---------------+-------------------------------------------------+
 
-For more information see the `WISHBONE specification <https://cdn.opencores.org/downloads/wbspec_b3.pdf>`_
+For more information see the `Wishbone B3 specification <https://cdn.opencores.org/downloads/wbspec_b3.pdf>`_

src/02_spec/07_modules/dem_uart/uartspec.rst

@@ -0,0 +1,64 @@
+.. _uart-registers:
+
+16550 UART Registers
+--------------------
+
+The following UART registers are implemented and accessible via the bus, the address mapping is in accordance with the UART-16550(A) standard as specified in this `Datasheet <http://caro.su/msx/ocm_de1/16550.pdf>`_.
+No FIFOs are present in hardware.
+No Modem or DMA-Mode related features, registers or interrupts are implemented.
+Writing to a register that is not implemented has no effect, reading from such a register will always return ``0x00``.
+
+All registers are 8 bit wide.
+
+.. tabularcolumns:: |p{\dimexpr 0.10\linewidth-2\tabcolsep}|p{\dimexpr 0.10\linewidth-2\tabcolsep}|p{\dimexpr 0.20\linewidth-2\tabcolsep}|p{\dimexpr 0.10\linewidth-2\tabcolsep}|p{\dimexpr 0.50\linewidth-2\tabcolsep}|
+.. flat-table:: 16550 UART Registers
+  :widths: 1 1 2 1 5
+  :header-rows: 1
+
+  * - Address
+    - Register
+    - Access Type
+    - Reset Value
+    - Description
+
+  * - ``0x00``
+    - ``RBR``
+    - Read only
+    - ``0x00``
+    - Receiver Buffer Register
+
+  * - ``0x00``
+    - ``THR``
+    - Write only
+    - ``0x00``
+    - Transmitter Holding Register
+
+  * - ``0x01``
+    - ``IER``
+    - Read/Write
+    - ``0x00``
+    - Enable(1)/Disable(0) interrupts. See `this <http://caro.su/msx/ocm_de1/16550.pdf>`_ for more details on each interrupt.
+
+  * - ``0x02``
+    - ``IIR``
+    - Read only
+    - ``0x01``
+    - Information which interrupt occurred
+
+  * - ``0x02``
+    - ``FCR``
+    - Write only
+    - ``0x00``
+    - Control behavior of the internal FIFOs. Currently writing to this Register has no effect.
+
+  * - ``0x03``
+    - ``LCR``
+    - Read/Write
+    - ``0x00``
+    - The only bit in this register that has any meaning is ``LCR7`` aka the DLAB, all other bits hold their written value but have no meaning.
+
+  * - ``0x05``
+    - ``LSR``
+    - Read only
+    - ``0x60``
+    - Information about state of the UART. After the UART is reset, ``0x60`` indicates when it is ready to transmit data.