From 922875b410bf5debcef2d5f799944362f557d751 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   |  3 ++-
 doc/uart.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 48 insertions(+), 1 deletion(-)
 create mode 100644 doc/uart.md

diff --git a/README.md b/README.md
index 0ad4c04..a6f3112 100644
--- a/README.md
+++ b/README.md
@@ -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/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.