improve documentation for serial console

Signed-off-by: Laura Loghin <[email protected]>

Author: lauralt

README.md

@@ -9,25 +9,30 @@ this support only for the
 
 ### Design
 
-The console emulation is done by emulating a hybrid between
-[UART 8250 serial port](https://en.wikibooks.org/w/index.php?title=Serial_Programming/8250_UART_Programming&section=15#Serial_COM_Port_Memory_and_I/O_Allocation)
-and [UART 16550 serial port](https://en.wikipedia.org/wiki/16550_UART).
+The console emulation is done by emulating a simple
+[UART 16550A serial port](https://en.wikipedia.org/wiki/16550_UART).
+This UART is an improvement of the original
+[UART 8250 serial port](https://en.wikibooks.org/w/index.php?title=Serial_Programming/8250_UART_Programming&section=15#Serial_COM_Port_Memory_and_I/O_Allocation),
+mostly because of the FIFO buffers that allow storing more than one byte at a
+time, which, in virtualized environments, is essential.
 For a VMM to be able to use this device, besides the emulation part which is
 covered in this crate, the serial port should be added to the microVM’s PIO bus,
 the serial backend should be defined and if and how the event handling is done.
 
 The following UART registers are emulated via the
 [`Serial` structure](src/serial.rs): DLL, IER, DLH, IIR, LCR, LSR, MCR, MSR and
-SR (more details about these,
-[here](http://%20https//en.wikibooks.org/w/index.php?title=Serial_Programming/8250_UART_Programming%C2%A7ion=15#UART_Registers)).
+SR (a brief, but nice presentation about these,
+[here](https://www.lammertbies.nl/comm/info/serial-uart#regs)).
 The Fifo Control Register (FCR) is not emulated since we are not interested in
-directly controlling the FIFOs and The Receiver Buffer and Transmitter Holding
-Buffer registers (THR and RBR) functionality is simplified, yet extended by
-using a single buffer. This buffer helps in testing the UART when running in
-loopback mode and for keeping the guest output to a `Write` object (`out`).
-The VMM that will use the serial console, when instantiating a `Serial`, will
-have to provide a `Write` object for it (for example `io::Stdout` or
-`io::Sink`).
+directly controlling the FIFOs (which, in our case, are always enabled) and
+The Receiver Buffer and Transmitter Holding Buffer registers (THR and RBR)
+functionality is simplified, yet extended by using a single FIFO buffer. When
+reading from RBR, the oldest unread byte from the FIFO is returned and when
+writing to THR, the FIFO buffer is extended with the new byte. This buffer helps
+in testing the UART when running in loopback mode and for keeping the guest
+output to a `Write` object (`out`). The VMM that will use the serial console,
+when instantiating a `Serial`, will have to provide a `Write` object for it (for
+example `io::Stdout` or `io::Sink`).
 The `interrupt_evt` fd is the currently used mechanism for notifying the driver
 when changes in the previously mentioned buffer happened that need to be
 handled, but further abstractions may come here; see

src/serial.rs

@@ -51,7 +51,10 @@ const LCR_DLAB_BIT: u8 = 0b1000_0000;
 const LSR_DATA_READY_BIT: u8 = 0b0000_0001;
 // These two bits help the driver know if the device is ready to accept
 // another character.
+// THR is empty.
 const LSR_EMPTY_THR_BIT: u8 = 0b0010_0000;
+// The shift register, which takes a byte from THR and breaks it in bits
+// for sending them on the line, is empty.
 const LSR_IDLE_BIT: u8 = 0b0100_0000;
 
 // The following five MCR bits allow direct manipulation of the device and
@@ -84,9 +87,9 @@ const DEFAULT_BAUD_DIVISOR_LOW: u8 = 0x0C;
 const DEFAULT_INTERRUPT_ENABLE: u8 = 0x00;
 // No pending interrupt.
 const DEFAULT_INTERRUPT_IDENTIFICATION: u8 = IIR_NONE_BIT;
-// We're setting the default to include LSR_EMPTY_THR_BIT and never update
-// that bit because we're working with a virtual device, hence we should
-// always be ready to receive more data.
+// We're setting the default to include LSR_EMPTY_THR_BIT and LSR_IDLE_BIT
+// and never update those bits because we're working with a virtual device,
+// hence we should always be ready to receive more data.
 const DEFAULT_LINE_STATUS: u8 = LSR_EMPTY_THR_BIT | LSR_IDLE_BIT;
 // 8 bits word length.
 const DEFAULT_LINE_CONTROL: u8 = 0b0000_0011;
@@ -114,10 +117,10 @@ pub struct Serial<W: Write> {
     modem_control: u8,
     modem_status: u8,
     scratch: u8,
-    // A simplified way to achieve (and extend) the Receiver and Transmitter
-    // registers functionality. It is worth mentioning these registers can
-    // store only one byte when having in mind the UART specification, but we
-    // are somehow simulating here the FIFO capability too.
+    // This is the buffer, that is used for achieving the Receiver and Transmitter
+    // registers functionality in FIFO mode. Reading from RBR will return the oldest
+    // unread byte from the buffer and writing to THR will expand this buffer with
+    // one byte.
     in_buffer: VecDeque<u8>,
 
     // Used for notifying the driver about some in/out events.