uart_16550

Simple yet highly configurable low-level driver for 16550 UART devices, typically known and used as serial ports or COM ports. Easy integration into Rust while providing fine-grained control where needed (e.g., for kernel drivers).

The "serial device" or "COM port" in typical x86 machines is almost always backed by a 16550 UART devices, may it be physical or emulated. This crate offers convenient and powerful abstractions for these devices, and also works for other architectures, such as ARM or RISC-V, by offering support for MMIO-mapped devices.

Serial ports are especially useful for debugging or operating system learning projects. See Uart16550 to get started.

Features

• ✅ Full configure, transmit, receive, and interrupt support for UART 16550–compatible devices
• ✅ High-level, ergonomic abstractions and types paired with support for plain integers
• ✅ Straightforward to integrate, highly configurable when needed
• ✅ Validated on real hardware as well as across different virtual machines
• ✅ Fully type-safe and derived directly from the official specification
• ✅ Supports both x86 port-mapped I/O and memory-mapped I/O (MMIO), as well as custom backends (e.g., hypercall-based I/O in confidential VMs)
• ✅ no_std-compatible and allocation-free by design
• ✅ Compatible with all architectures supported by Rust (x86/x86_64, ARM, RISC-V, ...)

Focus, Scope & Limitations

While serial ports are often used in conjunction with VT102-like terminal emulation, the primary focus of this crate is strict specification compliance and convenient direct access to the underlying hardware for transmitting and receiving bytes, including all necessary device configuration.

For basic terminal-related functionality, such as newline normalization and backspace handling, we provide Uart16550Tty as a basic convenience layer.

Overview

Use Uart16550Tty for a quick start to write to a terminal via your serial connection. For more fine-grained low-level control, please have a look at Uart16550 instead.

Example (Minimal - x86 Port IO)

use uart_16550::{Config, Uart16550Tty};
use core::fmt::Write;

fn main() {
  // SAFETY: The port is valid and we have exclusive access.
  let mut uart = unsafe { Uart16550Tty::new_port(0x3f8, Config::default()).expect("should initialize device") };
  uart.write_str("hello world\nhow's it going?");
}

Example (Minimal - MMIO)

use uart_16550::{Config, Uart16550Tty};
use core::fmt::Write;

fn main() {
  // SAFETY: The address is valid and we have exclusive access.
  let mut uart = unsafe { Uart16550Tty::new_mmio(0x1000 as *mut _, 4, Config::default()).expect("should initialize device") };
  uart.write_str("hello world\nhow's it going?");
}

Example (More low-level control)

use uart_16550::{Config, Uart16550};

fn main() {
  // SAFETY: The address is valid and we have exclusive access.
  let mut uart = unsafe { Uart16550::new_mmio(0x1000 as *mut _, 4).expect("should be valid port") };
  //                                 ^ or `new_port(0x3f8)`
  uart.init(Config::default()).expect("should init device successfully");
  uart.test_loopback().expect("should have working loopback mode");
  // Note: Might fail on real hardware with some null-modem cables
  uart.check_connected().expect("should have physically connected receiver");
  uart.send_bytes_exact(b"hello world!");
}

Testing

• There is a manual integration test packaged as UEFI application that you can boot on real hardware: ./real-hw-test
• There is an integration test that can run as a VM in ./integration-test

License

This project is licensed under either of

• MIT license (LICENSE-MIT)
• Apache License, Version 2.0 (LICENSE-APACHE)

Changelog

See CHANGELOG.md.