From 97e3e25d98db7afe77fc1e3df1c5f917aec16208 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Joachim=20Str=C3=B6mbergson?= <joachim@assured.se>
Date: Mon, 8 May 2023 14:50:10 +0200
Subject: [PATCH] Update the UART README with info about the core and its API
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Joachim Strömbergson <joachim@assured.se>
---
 hw/application_fpga/core/uart/README.md | 39 +++++++++++++++++++++++--
 1 file changed, 36 insertions(+), 3 deletions(-)

diff --git a/hw/application_fpga/core/uart/README.md b/hw/application_fpga/core/uart/README.md
index 8afebca..f680e6f 100644
--- a/hw/application_fpga/core/uart/README.md
+++ b/hw/application_fpga/core/uart/README.md
@@ -2,8 +2,41 @@ uart
 ====
 
 A simple universal asynchronous receiver/transmitter (UART) core
-implemented in Verilog.
+implemented in Verilog. The core is completed and has been used in
+several FPGA designs.
 
 
-# Status
-The core is completed and has been used in several FPGA designs.
+## Introduction
+
+The UART core is used as main communication channel between the TKey
+device System on Chip (SoC) and the TKey client. The UART contains a
+512 byte receive buffer, allowing the SW running on the SoC to not
+have to wait for bytes and poll them as soon as they are received. The
+number of bytes in the FIFO is also exposed to the SW through the
+ADDR_RX_BYTES address.
+
+The number of data and data bits can be set by SW. The default is
+eight data bits and one stop bit.
+
+The default bit rate is based on target clock frequency divided by the
+bit rate times in order to hit the center of the bits. I.e.  Clock: 18
+MHz, 62500 bps Divisor = 18E6 / 62500 = 288
+
+## API
+
+```
+  ADDR_BIT_RATE:  0x10
+  ADDR_DATA_BITS: 0x11
+  ADDR_STOP_BITS: 0x12
+
+  ADDR_RX_STATUS: 0x20
+  ADDR_RX_DATA:   0x21
+  ADDR_RX_BYTES:  0x22
+
+  ADDR_TX_STATUS: 0x40
+  ADDR_TX_DATA:   0x41
+```
+
+## Implementation notes.
+
+The FIFO allocates a single block RAM (EBR).