From 26ab71043d97c1b06bdd252378b64171cb95b1a9 Mon Sep 17 00:00:00 2001
From: Christian Cunningham <cc@localhost>
Date: Fri, 19 Aug 2022 21:22:18 -0700
Subject: Updated docs

---
 src/uart.rs | 47 +++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 41 insertions(+), 6 deletions(-)

(limited to 'src/uart.rs')

diff --git a/src/uart.rs b/src/uart.rs
index ffd9204..0f66116 100644
--- a/src/uart.rs
+++ b/src/uart.rs
@@ -1,32 +1,58 @@
+//! # UART Console Definition
 use crate::cpu::*;
+use crate::sync::NullLock;
+use core::fmt;
+use crate::sync::interface::Mutex;
 
+/// # Data Register
 const UART0_DR: u32    = 0x3F201000;
+/// # Flag Register
 const UART0_FR: u32    = 0x3F201018;
-const UART0_CR: u32    = 0x3F201030;
-const UART0_ICR: u32   = 0x3F201044;
-const UART0_IBRD: u32  = 0x3F201024;
+/// # Fractional Baud Rate Register
 const UART0_FBRD: u32  = 0x3F201028;
+/// # Line Control Register
 const UART0_LCRH: u32  = 0x3F20102C;
+/// # Control Register
+const UART0_CR: u32    = 0x3F201030;
+/// # Interrupt Mask Set/ Clear Register
 const UART0_IMSC: u32  = 0x3F201038;
+/// # Interrupt Control Register
+const UART0_ICR: u32   = 0x3F201044;
+/// # Integer Baud Rate Register
+const UART0_IBRD: u32  = 0x3F201024;
+
+/// GPIO Register
 const GPPUD: u32       = 0x3F200094;
+/// GPIO Clock 0 Register
 const GPPUDCLK0: u32   = 0x3F200098;
 
+/// # UART Inner Structure
+///
+/// Keeps record of the console statistics.
 struct UartInner {
 	chars_written: usize,
 }
 
-use crate::sync::NullLock;
+/// # UART Structure
+///
+/// Wraps the UART writer in a sharable lock.
 pub struct Uart {
 	inner: NullLock<UartInner>,
 }
 
 impl UartInner {
+	/// # Clear statistics
+	///
+	/// Create the writer with cleared statistics
 	pub const fn new() -> Self {
 		Self {
 			chars_written: 0,
 		}
 	}
 
+	/// # Initialize the UART setup
+	///
+	/// Set baud rate and timings
 	pub fn init(&mut self) {
 		store32(UART0_CR, 0);
 		store32(GPPUD, 0);
@@ -42,6 +68,7 @@ impl UartInner {
 		store32(UART0_CR, (1<<0) | (1<<8) | (1<<9));
 	}
 
+	/// # Write `char` to UART
 	fn write_char(&mut self, ch: char) {
 		while load32(UART0_FR) & 0x20 != 0 {
 			nop();
@@ -50,6 +77,7 @@ impl UartInner {
 		self.chars_written += 1;
 	}
 
+	/// # Flush UART
 	fn flush(&self) {
 		while load32(UART0_FR) & 0x08 != 0 {
 			nop();
@@ -57,8 +85,8 @@ impl UartInner {
 	}
 }
 
-use core::fmt;
 impl fmt::Write for UartInner {
+	/// # Write string to UART console
 	fn write_str(&mut self, s: &str) -> fmt::Result {
 		for c in s.chars() {
 			self.write_char(c);
@@ -67,15 +95,16 @@ impl fmt::Write for UartInner {
 	}
 }
 
-use crate::sync::interface::Mutex;
 
 impl Uart {
+	/// # Create sharable UART wrapper
 	pub const fn new() -> Self {
 		Self {
 			inner: NullLock::new(UartInner::new()),
 		}
 	}
 
+	/// # Call UART initialization
 	pub fn init(&self) -> Result<(), &'static str> {
 		self.inner.lock(|inner| inner.init());
 		Ok(())
@@ -83,25 +112,31 @@ impl Uart {
 }
 
 impl super::console::interface::Write for Uart {
+	/// # Write `char` to UART
 	fn write_char(&self, c: char) {
 		self.inner.lock(|inner| inner.write_char(c));
 	}
 
+	/// # Write formatted string to UART
 	fn write_fmt(&self, args: core::fmt::Arguments) -> fmt::Result {
 		self.inner.lock(|inner| fmt::Write::write_fmt(inner, args))
 	}
 
+	/// # Flush UART
 	fn flush(&self) {
 		self.inner.lock(|inner| inner.flush());
 	}
 }
 
 impl super::console::interface::Statistics for Uart {
+	/// # Get `char` written stats
 	fn chars_written(&self) -> usize {
 		self.inner.lock(|inner| inner.chars_written)
 	}
 }
 
+/// # UART Writer + Stats
 impl super::console::interface::All for Uart {}
 
+/// # Public reference to console.
 pub static UART_WRITER: Uart = Uart::new();
-- 
cgit v1.2.1