From a067dda0a97332fe2afc7445d05dbd18e7fbad57 Mon Sep 17 00:00:00 2001
From: slederer <dev@insignificance.de>
Date: Fri, 4 Oct 2024 00:29:40 +0200
Subject: [PATCH] docs: add UART documentation

---
 README.md   |  5 +++--
 doc/mem.md  |  4 ++--
 doc/uart.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 51 insertions(+), 4 deletions(-)
 create mode 100644 doc/uart.md

diff --git a/README.md b/README.md
index 0ad4c04..d4b1c56 100644
--- a/README.md
+++ b/README.md
@@ -25,7 +25,7 @@ Everything is open source, so you can read, understand and modify the whole syst
 ## Demos
 ### Videos
 
-|Compiling and Running Hello-World|Moving Lines Demo|
+|Compiling and Running "Hello World"|Moving Lines Demo|
 |---|---|
 |<video src="https://insignificance.de/tridora/tdr-hello.mp4" controls></video>|<video src="https://insignificance.de/tridora/tdr-lines.mp4" controls></video>|
 
@@ -77,7 +77,8 @@ Everything is open source, so you can read, understand and modify the whole syst
 ## Documentation
 - [Instruction Reference](doc/tridoracpu.md)
 - [Memory Layout](doc/mem.md)
+- [UART](doc/uart.md)
 - [SD-Card controller](doc/spisd.md)
 - [VGA controller](doc/vga.md)
 
-More documentation is coming as time permits.
+More documentation is coming, as time permits.
diff --git a/doc/mem.md b/doc/mem.md
index fc0f9e8..e24fbe2 100644
--- a/doc/mem.md
+++ b/doc/mem.md
@@ -31,6 +31,6 @@ Currently, only I/O slots 0-3 are being used.
 |I/O slot| Address | Controller |
 |--------|---------|------------|
 | 0      | $800    | UART       |
-| 1      | $880    | VGA        |
-| 2      | $900    | SPI-SD     |
+| 1      | $880    | SPI-SD     |
+| 2      | $900    | VGA        |
 | 3      | $980    | IRQC       |
diff --git a/doc/uart.md b/doc/uart.md
new file mode 100644
index 0000000..26f6ab8
--- /dev/null
+++ b/doc/uart.md
@@ -0,0 +1,46 @@
+# UART
+The UART a single register at address $900.
+It uses a fixed serial configuration of 115200 bps, 8 data bits, 1 stop bit, no parity.
+
+## Reading the UART register
+
+|_bit_  |31|30|29|28|27|26|25|24|23|22|21|20|19|18|17|16|
+|-      |- |- |- |- |- |- |- |- |- |- |- |- |- |- |- |- |
+|_Value_|u |u |u |u |u |u |u |u |u |u |u |u |u |u |u |u |
+
+|_bit_  |15|14|13|12|11|10|09|08|07|06|05|04|03|02|01|00|
+|-      |- |- |- |- |- |- |- |- |- |- |- |- |- |- |- |- |
+|_Value_|u |u |u |u |u |u |A |B |d |d |d |d |d |d | d | d |
+
+|Bitfields|Description|
+|---------|-----------|
+| _A_    | data available, at least one byte has been received
+| _B_    | TX busy, a byte is being transmitted and no data can be written
+| _d_    | 8 data bits
+| _u_    | unused
+
+## Writing the UART register
+
+|_bit_  |31|30|29|28|27|26|25|24|23|22|21|20|19|18|17|16|
+|-      |- |- |- |- |- |- |- |- |- |- |- |- |- |- |- |- |
+|_Value_|u |u |u |u |u |u |u |u |u |u |u |u |u |u |u |u |
+
+|_bit_  |15|14|13|12|11|10|09|08|07|06|05|04|03|02|01|00|
+|-      |- |- |- |- |- |- |- |- |- |- |- |- |- |- |- |- |
+|_Value_|u |u |u |u |u |T |C |u |d |d |d |d |d |d | d | d |
+
+
+|Bitfields|Description|
+|---------|-----------|
+| _T_     | transmit enable, writes a data byte
+| _C_    | clear receiver, acknowledges a received byte
+| _d_    | 8 data bits
+| _u_    | unused
+
+
+## Notes
+A 16 byte FIFO is used when receiving data.
+
+When reading data, each byte needs to be acknowledged by writing the _C_ flag to the UART register.
+
+When the FIFO is empty, the _A_ flag in the UART register will be 0.