kernel/uart.c

What this file drives

The “16550a” is a serial-port chip first made in the 1980s and still emulated by almost every virtual machine. QEMU’s virt machine provides one, and its programming interface is what the register definitions below describe.

Headers

kernel/memlayout.h provides UART0, the chip’s address. kernel/sleeplock.h and kernel/spinlock.h are needed for the transmit lock, and kernel/proc.h is included because kernel/defs.h and the sleep functions refer to process structures. kernel/riscv.h is part of the standard set every kernel file includes.

Turn a register number into a memory access

The UART’s registers appear as consecutive bytes in the physical address space, starting at UART0 = 0x10000000. Register n is the byte at UART0 + n. These three macros hide the pointer arithmetic: ReadReg(LSR) loads the byte at 0x10000005 and WriteReg(THR, c) stores c at 0x10000000.

The address is used as-is both before and after paging is turned on, because kvminit maps the UART’s page at the same virtual address (kernel/vm.c:30).

The 16550 registers and bits xv6 uses

These names follow the 16550 datasheet; see 16550 UART registers for the whole map. Each register is one byte. The comment’s warning matters: the chip decodes the direction of the access as well as the address. Offset 0 is the receive holding register when read and the transmit holding register when written, so RHR and THR are both 0. Offset 2 is likewise the interrupt status register (read) and the FIFO control register (write).

A second twist, used only in uartinit: while bit 7 of LCR is 1, offsets 0 and 1 stop meaning RHR/THR and IER and instead reach the two bytes of the baud-rate divisor.

Only the bits xv6 actually uses get names. Each is explained on its own line.

Transmit lock and wait channel

tx_lock makes writers take turns: only one process at a time runs the transmit loop in uartwrite. It is a sleep lock, not a spinlock, because its holder goes to sleep while waiting for the UART, and a process must never sleep while holding a spinlock.

tx_chan is never read or written. Only its address is used, as the “channel” that uartwrite sleeps on and uartintr wakes up (see sleep and wakeup). Any unique address would do; a dedicated variable guarantees no one else uses the same one.

The panic flags

Both flags live in kernel/printk.c. uartputc_sync checks them: while panicking is set it avoids the interrupt bookkeeping, and once panicked is set it freezes any CPU that tries to print. They are volatile because another CPU may set them at any time, and the compiler must re-read them from memory on every check instead of reusing an old value.

uartinit(): configure the chip

Called once, on hart 0, by consoleinit at the very start of main (kernel/main.c:14), before paging, before the first printk. It puts the chip into a known state: interrupts off, a fixed speed and character format, FIFOs on and empty, then interrupts on. The order matters: the chip should not raise an interrupt while it is half configured, so interrupts are disabled first and enabled last.

Enabling interrupts here only lets the UART signal them. They reach a CPU later, once plicinit and plicinithart have configured the PLIC and the CPU has turned interrupts on.

Set the speed

A UART sends each bit for a fixed time, and both ends of the wire must agree on it. The 16550 derives its bit rate by dividing its input clock by 16 × divisor. With the 1.8432 MHz crystal of a classic PC serial card, divisor 3 gives 1,843,200 / 48 = 38,400 bits per second, which is where the comments’ “38.4K” comes from. The actual rate depends on the clock feeding the chip.

The divisor is 16 bits wide but there is no register for it in the normal map. Setting the divisor latch access bit (LCR_BAUD_LATCH, bit 7 of LCR) temporarily redirects offset 0 to the divisor’s low byte (DLL) and offset 1 to its high byte (DLM). That is why lines 58 and 61 write to “registers” 0 and 1, which would otherwise be THR and IER.

(On QEMU the setting has no visible effect: QEMU’s model computes a nominal rate of about 133,000 baud from this divisor, but hands each byte to your terminal immediately rather than timing it.)

Character format, FIFOs, interrupts

Line 65 writes LCR = 0x03. Bits 1–0 = 11 select 8 data bits; bit 2 = 0 selects one stop bit; bit 3 = 0 means no parity bit; and bit 7 = 0 leaves divisor-latch mode, so offsets 0 and 1 are RHR/THR and IER again.

Line 68 writes FCR = 0x07. Bit 0 turns on the two 16-byte FIFOs (queues inside the chip for received and outgoing bytes); bits 1 and 2 empty the receive and transmit FIFOs (the chip clears these two bits by itself). Bits 7–6 are left 0, which sets the receive FIFO’s interrupt threshold to 1 byte: the chip asks for attention as soon as one byte has arrived, so typed keys are handled immediately.

Line 71 writes IER = 0x03: bit 0 requests an interrupt when received data is available, bit 1 requests one when the transmit holding register becomes empty. uartintr handles both.

Initialize the transmit lock

Gives tx_lock its name (“uart”, shown in debugging output) and marks it unlocked. It has to be ready before the first write() system call reaches uartwrite.

uartwrite(): send a buffer, sleeping while the UART is busy

The output path for write() on the console: consolewrite copies at most 32 bytes from the user program into a kernel buffer and calls this function. It sends the bytes one at a time. If the UART cannot take another byte yet, the process sleeps until the UART’s transmit interrupt says it can, so the CPU is free to run other processes in the meantime.

There is no software output buffer in this version of xv6. The only place bytes wait is the caller’s buffer, and the caller waits with them: uartwrite returns only when the last byte has been handed to the chip.

The source comment is right that this cannot run in an interrupt handler: it sleeps, and both acquiresleep and sleep need a current process (myproc).

Taking tx_lock for the whole buffer keeps the bytes of one call together. Since consolewrite calls uartwrite once per 32-byte batch, two processes writing long strings at the same time can still interleave in 32-byte pieces. Kernel output from uartputc_sync ignores the lock entirely and can land between any two bytes.

The transmit loop

Each pass either sends one byte or sleeps once. It relies on this version’s two-step sleep (sleep and wakeup): sleep_prepare records “this process is waiting on &tx_chan” before the UART is checked, and sleep then blocks only if no wakeup on that channel has happened since. A wakeup(&tx_chan) clears the record, and sleep() then returns at once.

That order is what prevents a lost wakeup. Suppose the check on line 87 finds the UART busy, and the transmit interrupt arrives on another CPU before line 91 runs. Because the process registered first, uartintr's wakeup(&tx_chan) clears the registration and sleep() does not block. If the registration came after the check, the wakeup would find nobody waiting; with the UART now idle and no more bytes being sent, no further transmit interrupt would come, and the writer would sleep forever.

After a wakeup the loop goes round again and re-checks LSR, so a wakeup that was really caused by received input (which also calls wakeup if the transmitter is idle) does no harm.

(Simplified: in FIFO mode the “transmitter empty” bit means the whole 16-byte transmit FIFO is empty, so this loop puts only one byte into the FIFO at a time and does not use its full depth.)

uartputc_sync(): send one byte by busy-waiting

The output path for everything that cannot sleep: printk (which may run with locks held or inside an interrupt handler) and the echo of typed characters, which consoleintr does from the UART interrupt handler. Both reach it through consputc.

Instead of sleeping, it spins, re-reading LSR until the chip can accept a byte. At 38,400 bits per second one byte takes about a quarter of a millisecond on a real line, so the wait per byte is short. It does not take tx_lock: a sleeplock may not be taken where sleeping is forbidden, and kernel messages must get out even if a writer is stuck.

Turn off interrupts on this CPU

push_off disables interrupts on this CPU (remembering whether they were on), and the matching pop_off on line 119 restores them. The effect is that nothing else can run on this CPU between the readiness check and the write of the byte.

The pair is skipped while a panic message is printed (panicking is set, by any CPU): the commit that introduced this says it makes the panic message more robust “if mycpu()->noff or locks are broken”. The interrupt-nesting bookkeeping that push_off/pop_off maintain may itself be what went wrong. Note that panicking is a single global flag, so this also changes behavior on the other CPUs while one CPU is panicking.

Freeze after a panic

Once panic has finished printing its message it sets panicked. From then on, any thread that tries to print spins here forever, so the panic message stays the last thing on the screen and is not buried by later output.

Because panicking is already set by then, push_off was skipped above, so interrupts stay off only if the caller had already disabled them. Otherwise a timer interrupt can still move this CPU on to another process (kernel/trap.c:157), which will itself freeze when it next prints. What freezes is the printing thread, not necessarily the CPU; code that never prints is not affected.

Wait, write, restore

Line 114 polls bit 5 of LSR. Each pass of the loop really reads the device, because ReadReg goes through a volatile pointer; without volatile the compiler could read the register once and spin forever on a stale value. Line 116 writes the byte to THR, and the chip takes it from there.

uartgetc(): take one received byte, if any

Bit 0 of LSR (data ready) is 1 while the receive FIFO holds at least one byte. Reading RHR removes the oldest byte from the FIFO. The function returns that byte as an int in 0–255, or -1 if nothing is waiting. -1 can never be a real byte value, which is why the return type is int, not char. static: only uartintr uses it.

uartintr(): the UART interrupt handler

The UART is wired to interrupt line UART0_IRQ (10) of the PLIC. When it raises that line, the CPU takes a supervisor external interrupt, and devintr asks the PLIC which device it was and calls this function (kernel/trap.c:199); after it returns, devintr tells the PLIC the interrupt is complete. It may run on any CPU, in the middle of whatever was running there, so it must not sleep.

The chip raises the interrupt for either reason enabled in uartinit (a byte received, the transmitter empty), or both, and the handler does not try to tell which. It checks for both conditions.

Acknowledge

Reads the interrupt status register and throws the value away. In the 16550, reading this register clears a pending “transmitter empty” interrupt, if that is the interrupt it reports (received data has higher priority and is reported first). A pending “received data” interrupt is cleared differently: by reading bytes from RHR until the FIFO is below the threshold, which the loop below does. ReadReg uses a volatile pointer, so the compiler keeps this read even though its result is unused (it compiles to a single lbu from 0x10000002 in kernel/kernel.asm).

Wake a waiting writer

If the transmitter is empty, any process sleeping in uartwrite can send its next byte, so wake it. wakeup on a channel nobody waits on does nothing, so a wakeup sent when no one is writing is harmless.

Pass every received byte up to the console

Several bytes may have arrived since the last interrupt (pasted text, for example), and they are waiting in the receive FIFO. The loop drains it, passing each byte to consoleintr, which does echo and line editing (kernel/console.c). Draining until uartgetc returns -1 also clears the receive interrupt condition, so the UART does not immediately interrupt again for the same bytes.