> ## Documentation Index
> Fetch the complete documentation index at: https://kernel.mvhcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Serial UART Driver: 16550 Serial Output in MVH Kernel

> MVH Kernel's 16550 UART serial driver mirrors all shell and kernel log output to COM1, making it ideal for QEMU debugging and headless operation.

The serial UART driver (`serial-uart-16550`) attaches to the first serial port (COM1) at I/O base address `0x3F8` and mirrors every byte of kernel output to the wire. Any text written to the VGA display — shell command output, kernel log messages, and kernel panic output — is also sent through `serial_put` so you can capture a complete runtime transcript without a monitor. This makes the serial driver especially useful when running MVH Kernel under QEMU or other emulators where a physical display is inconvenient.

## What Gets Mirrored

The serial driver receives every character the kernel emits, with no filtering or buffering delay. This includes:

* All interactive shell output (`ls`, `cat`, `cpuinfo`, `lspci`, `dmesg`, and every other command)
* The structured kernel log ring (viewable live, not just via `dmesg`)
* Kernel panic output: panic code, exception details, register dump, and stack trace
* The kernel boot sequence messages

<Note>
  The serial port is write-only from the kernel's perspective in the current release — the driver does not implement serial input. All user input is handled exclusively by the PS/2 keyboard driver.
</Note>

## Using Serial Output with QEMU

QEMU routes COM1 serial output to whatever backend you specify with the `-serial` flag. Two common workflows:

**Capture output to a log file:**

```bash theme={null}
qemu-system-x86_64 -kernel mvhkernel.elf -serial file:serial.log
```

**Stream output to your terminal (stdio):**

```bash theme={null}
qemu-system-x86_64 -kernel mvhkernel.elf -serial stdio
```

When you use `-serial stdio`, QEMU mixes serial output with its own console. If you want clean separation, use `-nographic` together with `-serial stdio` to redirect the entire session:

```bash theme={null}
qemu-system-x86_64 -kernel mvhkernel.elf -nographic -serial stdio
```

## Port and Baud Rate

| Parameter | Value          |
| --------- | -------------- |
| Port      | COM1 (`0x3F8`) |
| Baud rate | 38400          |
| Data bits | 8              |
| Stop bits | 1              |
| Parity    | None           |

The driver initializes the 16550 UART at boot via `serial_init()`, configures the baud rate divisor, enables the FIFO, and sets the line control register for 8N1 framing before the shell becomes interactive.

## API Reference

The serial driver exposes two functions from `include/mvh/serial.h`:

```c theme={null}
void serial_init(void); // Initialize the 16550 UART (baud rate, FIFO, line control)
void serial_put(char value); // Transmit one character over COM1
```

Both functions are called internally by the kernel's output layer — you do not need to call them directly unless you are extending the kernel.

## Driver ID

The device manager registers this driver under the ID `serial-uart-16550`. Run `devices` in the shell to confirm it is online.