* or1k/or1k_uart.c: Write bugfix and cleanup/documentation.

	* or1k/or1k_uart.h: Cleanup.

2 files changed, 100 insertions, 57 deletions

diff --git a/libgloss/or1k/or1k_uart.c b/libgloss/or1k/or1k_uart.c
index 3d79f4516..e5b539af4 100644
--- a/libgloss/or1k/or1k_uart.c
+++ b/libgloss/or1k/or1k_uart.c
@@ -3,6 +3,7 @@
  *Copyright (c) 2014 Authors
  *
  * Contributor Stefan Wallentowitz <stefan.wallentowitz@tum.de>
+ * Contributor Olof Kindgren <olof.kindgren@gmail.com>
  *
  * The authors hereby grant permission to use, copy, modify, distribute,
  * and license this software and its documentation for any purpose, provided
@@ -20,10 +21,86 @@
 
 #include <stdint.h>
 
+// Register interface
+#define RB  _or1k_board_uart_base + 0 // Receiver Buffer (R)
+#define THR _or1k_board_uart_base + 0 // Transmitter Holding Register (W)
+#define IER _or1k_board_uart_base + 1 // Interrupt Enable Register (RW)
+#define IIR _or1k_board_uart_base + 2 // Interrupt Identification Register (R)
+#define FCR _or1k_board_uart_base + 2 // FIFO Control Register (W)
+#define LCR _or1k_board_uart_base + 3 // Line Control Register (RW)
+#define MCR _or1k_board_uart_base + 4 // Modem Control Register (W)
+#define LSR _or1k_board_uart_base + 5 // Line Status Register (R)
+#define MSR _or1k_board_uart_base + 6 // Modem Status Register (R)
+
+// Divisor Register (Accessed when DLAB bit in LCR is set)
+#define DLB1 _or1k_board_uart_base + 0 // Divisor Latch LSB (RW)
+#define DLB2 _or1k_board_uart_base + 1 // Divisor Latch MSB (RW)
+
+// Interrupt Enable Register bits
+#define IER_RDAI 0 // Receiver Data Available Interrupt
+#define IER_TEI  1 // Transmitter Holding Register Empty Interrupt
+#define IER_RLSI 2 // Receiver Line Status Interrupt
+#define IER_MSI  3 // Modem Status Interrupt
+
+// Interrupt Identification Register Values
+#define IIR_RLS  0xC6 // Receiver Line Status
+#define IIR_RDA  0xC4 // Receiver Data Available
+#define IIR_TO   0xCC // Timeout
+#define IIR_THRE 0xC2 // Transmitter Holding Register Empty
+#define IIT_MS   0xC0 // Modem Status
+
+// FIFO Control Register bits
+#define FCR_CLRRECV 0x1  // Clear receiver FIFO
+#define FCR_CLRTMIT 0x2  // Clear transmitter FIFO
+
+// FIFO Control Register bit 7-6 values
+#define FCR_TRIG_1  0x0  // Trigger level 1 byte
+#define FCR_TRIG_4  0x40 // Trigger level 4 bytes
+#define FCR_TRIG_8  0x80 // Trigger level 8 bytes
+#define FCR_TRIG_14 0xC0 // Trigger level 14 bytes
+
+// Line Control Reigster values and bits
+#define LCR_BPC_5 0x0  // 5 bits per character
+#define LCR_BPC_6 0x1  // 6 bits per character
+#define LCR_BPC_7 0x2  // 7 bits per character
+#define LCR_BPC_8 0x3  // 8 bits per character
+#define LCR_SB_1  0x0  // 1 stop bit
+#define LCR_SB_2  0x4  // 1.5 stop bits (LCR_BPC_5) or 2 stop bits (else)
+#define LCR_PE    0x8  // Parity Enabled
+#define LCR_EPS   0x10 // Even Parity Select
+#define LCR_SP    0x20 // Stick Parity
+#define LCR_BC    0x40 // Break Control
+#define LCR_DLA   0x80 // Divisor Latch Access
+
+// Line Status Register
+#define LSR_DR  0x0  // Data Ready
+#define LSR_OE  0x2  // Overrun Error
+#define LSR_PE  0x4  // Parity Error
+#define LSR_FE  0x8  // Framing Error
+#define LSR_BI  0x10 // Break Interrupt
+#define LSR_TFE 0x20 // Transmitter FIFO Empty
+#define LSR_TEI 0x40 // Transmitter Empty Indicator
+
+/**
+ * The registered callback function
+ */
 void (*_or1k_uart_read_cb)(char c);
 
+/**
+ * This is the interrupt handler that is registered for the callback
+ * function.
+ */
 void _or1k_uart_interrupt_handler(uint32_t data)
 {
+	uint8_t iir = REG8(IIR);
+
+	// Check if this is a read fifo interrupt, bit 0 indicates pending
+	// interrupt and the other bits are IIR_RDA
+	if (!(iir & 0x1) || ((iir & 0xfe) != IIR_RDA)) {
+		return;
+	}
+
+	// Read character and call callback function
 	_or1k_uart_read_cb(REG8(RB));
 }
 
@@ -33,7 +110,7 @@ int _or1k_uart_init(void)
 
 	// Is uart present?
 	if (!_or1k_board_uart_base) {
-			return -1;
+		return -1;
 	}
 
 	// Reset the callback function
@@ -64,19 +141,25 @@ int _or1k_uart_init(void)
 
 void _or1k_uart_write(char c)
 {
-	while (!REG8(LSR) & LSR_TFE) {}
+	// Wait until FIFO is empty
+	while (!(REG8(LSR) & LSR_TFE)) {}
 
+	// Write character to device
 	REG8(THR) = c;
 }
 
 void or1k_uart_set_read_cb(void (*cb)(char c))
 {
+	// Set callback function
 	_or1k_uart_read_cb = cb;
 
 	// Enable interrupt
 	REG8(IER) = 1 << IER_RDAI;
 
+	// Add the interrupt handler that calls the callback function
 	or1k_interrupt_handler_add(_or1k_board_uart_IRQ,
 			_or1k_uart_interrupt_handler, 0);
+
+	// Enable UART interrupt
 	or1k_interrupt_enable(_or1k_board_uart_IRQ);
 }
diff --git a/libgloss/or1k/or1k_uart.h b/libgloss/or1k/or1k_uart.h
index dc8a3dbce..4cbb68350 100644
--- a/libgloss/or1k/or1k_uart.h
+++ b/libgloss/or1k/or1k_uart.h
@@ -15,69 +15,29 @@
  * they apply.
  */
 
-/* This is the generic board support for the OpenCores UART device */
+/* This is the generic board support for the OpenCores UART device, internal
+ * header. */
 
 #include <stdint.h>
 
 #include "board.h"
 
+/**
+ * Registered callback function
+ */
 extern void (*_or1k_uart_read_cb)(char c);
 
+/**
+ * The UART interrupt handler
+ */
 void _or1k_uart_interrupt_handler(uint32_t data);
 
+/**
+ * Initialize UART
+ */
 int _or1k_uart_init(void);
-void _or1k_uart_write(char c);
-
-#define RB  _or1k_board_uart_base + 0
-#define THR _or1k_board_uart_base + 0
-#define IER _or1k_board_uart_base + 1
-#define IIR _or1k_board_uart_base + 2
-#define FCR _or1k_board_uart_base + 2
-#define LCR _or1k_board_uart_base + 3
-#define MCR _or1k_board_uart_base + 4
-#define LSR _or1k_board_uart_base + 5
-#define MSR _or1k_board_uart_base + 6
-
-#define DLB1 _or1k_board_uart_base + 0
-#define DLB2 _or1k_board_uart_base + 1
-
-#define IER_RDAI 0
-#define IER_TEI  1
-#define IER_RLSI 2
-#define IER_MSI  3
 
-#define IIR_RLS  0xC3
-#define IIR_RDA  0xC2
-#define IIR_TO   0xC6
-#define IIR_THRE 0xC1
-#define IIT_MS   0xC0
-
-#define FCR_CLRRECV 0x1
-#define FCR_CLRTMIT 0x2
-#define FCR_TRIG_1  0x0
-#define FCR_TRIG_4  0x40
-#define FCR_TRIG_8  0x80
-#define FCR_TRIG_14 0xC0
-
-#define LCR_BPC_MASK 0x3
-#define LCR_SB_MASK  0x4
-
-#define LCR_BPC_5 0x0
-#define LCR_BPC_6 0x1
-#define LCR_BPC_7 0x2
-#define LCR_BPC_8 0x3
-#define LCR_SB_1  0x0
-#define LCR_SB_2  0x4
-#define LCR_PE    0x8
-#define LCR_EPS   0x10
-#define LCR_SP    0x20
-#define LCR_BC    0x40
-#define LCR_DLA   0x80
-
-#define LSR_DR  0x0
-#define LSR_OE  0x2
-#define LSR_PE  0x4
-#define LSR_FE  0x8
-#define LSR_BI  0x10
-#define LSR_TFE 0x20
-#define LSR_TEI 0x40
+/**
+ * Write character to UART
+ */
+void _or1k_uart_write(char c);