Skip to content

Commit deb399b

Browse files
ThomasLeykimphil
ThomasLeyk
authored and
imphil
committed
Added doc for DEM_UART
fixes #19
1 parent cc5a9a1 commit deb399b

File tree

8 files changed

+228
-0
lines changed

8 files changed

+228
-0
lines changed

‎src/02_spec/07_modules/dem_uart/datainterface.rst

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
Programmer Interface: Data
2+
--------------------------
3+
4+
The Device Emulation Module only generates one type of event packet: **DEM-UART Data Packet**
5+
6+
DEM-UART Data Packet
7+
^^^^^^^^^^^^^^^^^^^^
8+
9+
A DEM-UART Data packet contains one 8-bit character, that has been sent to a UART interface by a CPU, as the only payload.
10+
All packets of this type are sent to the DI Address ``MOD_EVENT_DEST``.
11+
12+
The following fields in the header of the DI packet are set:
13+
14+
- ``FLAGS.TYPE`` is set to ``EVENT``
15+
- ``FLAGS.TYPE_SUB`` is set to ``0x00``
16+
17+
The resulting Debug Interconnect packet has the following structure.
18+
19+
.. tabularcolumns:: |p{\dimexpr 0.20\linewidth-2\tabcolsep}|p{\dimexpr 0.30\linewidth-2\tabcolsep}|p{\dimexpr 0.50\linewidth-2\tabcolsep}|
20+
.. flat-table:: Structure of a DEM-UART data packet
21+
:widths: 2 3 5
22+
:header-rows: 1
23+
24+
* - Word
25+
- Field
26+
- Description
27+
28+
* - 1
29+
- ``CHARACTER``
30+
- Contains the character that is being sent, the MSB is always ``0x00``

‎src/02_spec/07_modules/dem_uart/dbgregisters.rst

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
Programmer Interface: Control Registers
2+
---------------------------------------
3+
4+
The Device Emulation modules implements the Base Register Map. (:ref:`sec:spec:api:base_register_map`)
5+
The reset values are listed below.
6+
7+
.. tabularcolumns:: |p{\dimexpr 0.20\linewidth-2\tabcolsep}|p{\dimexpr 0.20\linewidth-2\tabcolsep}|p{\dimexpr 0.40\linewidth-2\tabcolsep}|p{\dimexpr 0.20\linewidth-2\tabcolsep}|
8+
.. flat-table:: DEM-UART base register reset values
9+
:widths: 2 2 4 2
10+
:header-rows: 1
11+
12+
* - address
13+
- name
14+
- description
15+
- reset value
16+
17+
* - 0x0000
18+
- ``MOD_VENDOR``
19+
- module vendor
20+
- 0x0001
21+
22+
* - 0x0001
23+
- ``MOD_TYPE``
24+
- module type identifier
25+
- 0x0002
26+
27+
* - 0x0002
28+
- ``MOD_VERSION``
29+
- module version
30+
- 0x0000
31+
32+
* - 0x0003
33+
- ``MOD_CS``
34+
- module control and status
35+
- 0x0000
36+
37+
* - 0x0004
38+
- ``MOD_EVENT_DEST``
39+
- destination of debug events
40+
- impl.-specific
41+
42+
There are no additional registers implemented in this module.

‎src/02_spec/07_modules/dem_uart/img/bus_read_diagram.svg

Lines changed: 4 additions & 0 deletions
Loading

‎src/02_spec/07_modules/dem_uart/img/bus_write_diagram.svg

Lines changed: 4 additions & 0 deletions
Loading

‎src/02_spec/07_modules/dem_uart/img/osd_dem_uart.svg

Lines changed: 2 additions & 0 deletions
Loading

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

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
UART Device Emulation Module (DEM-UART)
2+
=======================================
3+
4+
.. figure:: img/osd_dem_uart.*
5+
:alt: Device Emulation Module UART
6+
7+
The UART Device Emulation Module connects to the bus of a given CPU on one side, and to the Debug Interconnect on the other.
8+
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.
9+
10+
.. _uart-registers:
11+
12+
16550 UART Registers
13+
--------------------
14+
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>`_.
15+
No FIFOs are present in hardware.
16+
No Modem or DMA-Mode related features, registers or interrupts are implemented.
17+
Writing to a register that is not implemented has no effect, reading from such a register will always return ``0x00``.
18+
19+
All registers are 8 bit wide.
20+
21+
.. 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}|
22+
.. flat-table:: 16550 UART Registers
23+
:widths: 1 1 2 1 5
24+
:header-rows: 1
25+
26+
* - Address
27+
- Register
28+
- Access Type
29+
- Reset Value
30+
- Description
31+
32+
* - ``0x00``
33+
- ``RBR``
34+
- Read only
35+
- ``0x00``
36+
- Receiver Buffer Register
37+
38+
* - ``0x00``
39+
- ``THR``
40+
- Write only
41+
- ``0x00``
42+
- Transmitter Holding Register
43+
44+
* - ``0x01``
45+
- ``IER``
46+
- Read/Write
47+
- ``0x00``
48+
- Enable(1)/Disable(0) interrupts. See `this <http://caro.su/msx/ocm_de1/16550.pdf>`_ for more details on each interrupt.
49+
50+
* - ``0x02``
51+
- ``IIR``
52+
- Read only
53+
- ``0x01``
54+
- Information which interrupt occurred
55+
56+
* - ``0x02``
57+
- ``FCR``
58+
- Write only
59+
- ``0x00``
60+
- Control behavior of the internal FIFOs. Currently writing to this Register has no effect.
61+
62+
* - ``0x03``
63+
- ``LCR``
64+
- Read/Write
65+
- ``0x00``
66+
- 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.
67+
68+
* - ``0x05``
69+
- ``LSR``
70+
- Read only
71+
- ``0x60``
72+
- Information about state of the UART. After the UART is reset, ``0x60`` indicates when it is ready to transmit data.
73+
74+
.. toctree::
75+
:maxdepth: 1
76+
77+
systemif
78+
dbgregisters
79+
datainterface

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

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
System Interface
2+
----------------
3+
4+
The DEM-UART module provides a generic bus interface, which can be used by wrapper modules to support actual bus interfaces.
5+
We specify a Wishbone wrapper interface below.
6+
7+
+-----------------+-------------+---------------+-------------------------------------------------+
8+
| Signal | Width (bit) | Direction | Description |
9+
+=================+=============+===============+=================================================+
10+
| ``bus_req`` | 1 | CPU->DEM | ``1`` indicates an active request from the CPU |
11+
+-----------------+-------------+---------------+-------------------------------------------------+
12+
| ``bus_addr`` | 3 | CPU->DEM | Address to be used with write/read operation |
13+
+-----------------+-------------+---------------+-------------------------------------------------+
14+
| ``bus_write`` | 1 | CPU->DEM | ``1`` indicates a register write request |
15+
+-----------------+-------------+---------------+-------------------------------------------------+
16+
| ``bus_wdata`` | 8 | CPU->DEM | Data to be written into the register |
17+
+-----------------+-------------+---------------+-------------------------------------------------+
18+
| ``bus_ack`` | 1 | DEM->CPU | Acknowledge last request |
19+
+-----------------+-------------+---------------+-------------------------------------------------+
20+
| ``bus_rdata`` | 8 | DEM->CPU | Data that was read from the register |
21+
+-----------------+-------------+---------------+-------------------------------------------------+
22+
23+
.. figure:: img/bus_write_diagram.*
24+
:alt: A typical write cycle
25+
26+
.. figure:: img/bus_read_diagram.*
27+
:alt: A typical read cycle
28+
29+
A new request is made by asserting ``bus_req``, unless ``bus_req`` is asserted, no other signal is valid.
30+
``bus_write`` indicates whether it is a read (0) or a write (1) request.
31+
``bus_addr`` may be any of the values documented under :ref:`uart-registers`.
32+
Finally ``bus_ack`` is asserted to confirm the request and end the cycle.
33+
34+
``bus_req``, ``bus_addr`` and ``bus_write`` are asserted in the same cycle, if it is a write cycle
35+
``bus_wdata`` is also set in the same cycle.
36+
``bus_ack may`` be asserted any number of cycles after ``bus_req`` has been asserted.
37+
``bus_rdata`` is only valid when ``bus_ack`` is asserted and ``bus_write`` is negated.
38+
39+
40+
Wishbone Bus
41+
------------
42+
If a wishbone interface is present, it should wrap around the generic bus described above and take
43+
care of translating all the signals.
44+
The following signals MUST be present on a compatible WISHBONE bus.
45+
46+
+-----------------+-------------+---------------+-------------------------------------------------+
47+
| Signal | Width (bit) | Direction | Description |
48+
+=================+=============+===============+=================================================+
49+
| ``wb_adr_i`` | 3 | CPU->DEM | Address to be used with write/read operation |
50+
+-----------------+-------------+---------------+-------------------------------------------------+
51+
| ``wb_cyc_i`` | 1 | CPU->DEM | ``1`` indicates valid bus cycle is in progress |
52+
+-----------------+-------------+---------------+-------------------------------------------------+
53+
| ``wb_dat_i`` | 32 | CPU->DEM | Data to be written into the register |
54+
+-----------------+-------------+---------------+-------------------------------------------------+
55+
| ``wb_sel_i`` | 4 | CPU->DEM | Bitfield indicating validity of data on dat_i |
56+
+-----------------+-------------+---------------+-------------------------------------------------+
57+
| ``wb_stb_i`` | 1 | CPU->DEM | ``1`` indicates that DEM is selected |
58+
+-----------------+-------------+---------------+-------------------------------------------------+
59+
| ``wb_we_i`` | 8 | CPU->DEM | ``1`` indicates a write request by the WB-Master|
60+
+-----------------+-------------+---------------+-------------------------------------------------+
61+
| ``wb_ack_o`` | 1 | DEM->CPU | ``1`` indicates termination of normal bus cycle |
62+
+-----------------+-------------+---------------+-------------------------------------------------+
63+
| ``wb_dat_o`` | 32 | DEM->CPU | Data that was read from the register |
64+
+-----------------+-------------+---------------+-------------------------------------------------+
65+
66+
For more information see the `WISHBONE specification <https://cdn.opencores.org/downloads/wbspec_b3.pdf>`_

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,4 @@ Open SoC Debug specifies a set of modules with commonly used functionality.
1313
stm/index
1414
cdm/index
1515
ctm/index
16+
dem_uart/index

0 commit comments

Comments
 (0)