treewide: nuke old repo and replace with rewrite from @phip1611 #41

phip1611 · 2026-01-17T17:29:48Z

TL;DR

As discussed [0], this is my 100% rewrite of the crate. It is 100% spec
complete, highly configurable (usable in kernel drivers) while still
preserving a very simple entry-level abstraction that "just works".

It also runs on real hardware now! The original code wasn't mature
enough for all the caveats. Further, we have one common abstraction for
x86 port I/O and MMIO.

Background

As part of a learning project, I conducted an in-depth exploration of
UART 16550 devices and driver development. During this process, I
identified a key limitation in the current crate: the inability to
configure the baud rate. This functionality is essential for real
hardware usage, and addressing it was my primary motivation.

As I continued, I recognized additional areas for improvement.
Incremental changes quickly proved insufficient to meet the standards
of code quality, completeness, and maintainability I aimed for.
Consequently, I undertook a full rewrite, resulting in a driver that
is fully spec-compliant while maintaining seamless and idiomatic Rust
integration.

While I could release this as a separate crate, I prefer not to fragment
the ecosystem - especially given that rust-osdev already maintains a
crate in this space. I fully acknowledge that this presents a "take it
or leave it" ("friss oder stirb") scenario 😞 . That said, I am eager to
collaborate toward a solution that serves the community effectively,
and I am confident this rewrite provides a strong, forward-looking
foundation.

Notes about Real Hardware Tests

To properly operate with real hardware, I had to specifically
investigate the behavior and especially adapt try_send_bytes()
and test_loopback().

Further, the source and the destination must agree on the baud
rate. Tests in VMs would behave differently (have fewer caveats),
especially as the baud rate is mostly irrelevant there.

About API and Implementation

Please look into lib.rs, I suggest using cargo doc. A small except from README is also here:

Example (Minimalistic)

⚠️ PLEASE NOTE THAT THIS MAY BE SLIGHTLY OUTDATED. THE CURRENT TRUTH IS ONLY IN lib.rs

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

fn main() {
  // SAFETY: The I/O port is valid and we have exclusive access.
  let mut uart = unsafe { Uart16550Tty::new_port(0x3f8, Config::default()).expect("should initialize device") };
  //                                    ^ you could also use `new_mmio(0x1000 as *mut _)` here
  uart.write_str("hello world\nhow's it going?");
}

Example (More low-level control)

⚠️ PLEASE NOTE THAT THIS MAY BE SLIGHTLY OUTDATED. THE CURRENT TRUTH IS ONLY IN lib.rs

use uart_16550::{Config, Uart16550};

fn main() {
  // SAFETY: The I/O port is valid and we have exclusive access.
  let mut uart = unsafe { Uart16550::new_port(0x3f8).expect("should be valid port") };
  //                                 ^ you could also use `new_mmio(0x1000 as *mut _)` here
  uart.init(Config::default()).expect("should init device successfully");
  uart.test_loopback().expect("should have working loopback mode");
  uart.check_remote_ready_to_receive().expect("should have physically connected receiver");
  uart.send_bytes_all(b"hello world!");
}

Hints for Reviewers

I tested this on real hardware, in QEMU, and in Cloud Hypervisor. I
suggest checking this out and using cargo doc --open to get a nice
overview.

I didn't use a LLM to write the code, only for this cover letter
(commit message) to improve it.

Steps to Undraft

[0] https://rust-osdev.zulipchat.com/#narrow/channel/426430-general/topic/uart.2016550.20.2F.20serial/near/566528969

Closes #37 #38 #30

Wasabi375

First off I want to say that this looks great and I'm all for merging this. Thanks for the great work.

That said, I'm not a maintainer here so please feel free to ignore my comments (especially the style based ones if you don't agree).

src/lib.rs

src/backend.rs

src/spec.rs

src/lib.rs

src/backend.rs

src/lib.rs

phip1611 · 2026-01-18T16:13:17Z

First off I want to say that this looks great and I'm all for merging this. Thanks for the great work.

That said, I'm not a maintainer here so please feel free to ignore my comments (especially the style based ones if you don't agree).

thanks, your review was already very helpful!

phip1611 · 2026-01-19T16:18:06Z

@phil-opp @mkroening This PR is now in a state that fullfills my personal high CI, coding and API standards including excellent documentation. We have a basic integration test in QEMU and I tested everything on real hardware! I am very happy to maintain this crate from now on and I'd be very happy to get the corresponding admin rights to publish this crate as well as maintain the repository.

PS: This is not a hostile takeover but a friendly offer to improve the ecosystem! :) I hope we can find a path forward thats works for everyone and that we can publish this soon. If you could give me repository admin rights, I can set the necessary changes for the new CI jobs.

PPS: I didn't have a chance to test the MMIO backend in a VM or real hardware. But I'm confident it should work. I have a unit test for it tho.

src/lib.rs

## TL;DR As discussed [0], this is my 100% rewrite of the crate. It is 100% spec compliant, highly configurable (usable in kernel drivers) while still preserving a very simple entry-level abstraction that "just works". **It also runs on real hardware now!** The original code wasn't mature enough for all the caveats. Further, we have one common abstraction for x86 port I/O and MMIO. ## Background As part of a learning project, I conducted an in-depth exploration of UART 16550 devices and driver development. During this process, I identified a key limitation in the current crate: the inability to configure the baud rate. This functionality is essential for real hardware usage, and addressing it was my primary motivation. As I continued, I recognized additional areas for improvement. Incremental changes quickly proved insufficient to meet the standards of code quality, completeness, and maintainability I aimed for. Consequently, I undertook a full rewrite, resulting in a driver that is fully spec-compliant while maintaining seamless and idiomatic Rust integration. While I could release this as a separate crate, I prefer not to fragment the ecosystem - especially given that rust-osdev already maintains a crate in this space. **I fully acknowledge that this presents a "take it or leave it" ("friss oder stirb") scenario** 😞 . That said, I am eager to collaborate toward a solution that serves the community effectively, and I am confident this rewrite provides a strong, forward-looking foundation. ## Notes about Real Hardware Tests To properly operate with real hardware, I had to specifically investigate the behavior and especially adapt try_send_bytes() and test_loopback(). Further, the source and the destination must agree on the baud rate. Tests in VMs would behave differently (have fewer caveats), especially as the baud rate is mostly irrelevant there. ## About API and Implementation Please look into `lib.rs`, I suggest using `cargo doc`. A small except from README is also here: [0] https://rust-osdev.zulipchat.com/#narrow/channel/426430-general/topic/uart.2016550.20.2F.20serial/near/566528969

This is a basic integration test that runs the code in a VM machine that uses a x86 port I/O backed UART16550.

This enables to compile the crate normally even on non-x86. We could work around using combinations of #[cfg] and #[doc], but this would be very ugly.

This is best practice in Rust. It is a private API helper anyway that just must be public to a certain degree.

mkroening

Thanks, this is great!

While I did not take a close look at every single line of code, this looks extremely solid to me.

This does not break anything with Hermit (hermit-os/kernel#2191), and I have created an issue for adding 16550 UART device support on AArch64 and RISC-V (hermit-os/kernel#2192).

I have a few comments, but nothing blocking. I would be personally fine with merging this, though @phil-opp would need to create a team for this repo and add you.

I don't know whether @phil-opp would prefer some attribution somewhere in the new repo.

mkroening · 2026-01-26T15:03:04Z

test/src/main.rs

+struct DummyGlobalAlloc;
+
+#[global_allocator]
+static GLOBAL_ALLOCATOR: DummyGlobalAlloc = DummyGlobalAlloc;
+
+unsafe impl GlobalAlloc for DummyGlobalAlloc {
+    unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
+        panic!("unsupported! layout={layout:?}");
+    }
+
+    unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
+        panic!("unsupported! ptr={ptr:?}, layout={layout:?}");
+    }
+}


It might make sense to not build alloc and remove the global allocator and the anyhow crate that requires it.

As far as I know, creating anyhow errors requires boxing, so handling errors without an allocator is not possible anyway.

ah yes make sense! thanks :)

mkroening · 2026-01-26T15:13:56Z

test/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "kernel"
+version = "0.1.0"


Since this is not meant for publication, we could remove the version, which then implies publish = false.

mkroening · 2026-01-26T15:18:17Z

Cargo.toml

+authors = [
+  "Philipp Schuster <phip1611@gmail.com>",
+]
+resolver = "3"


I think this is implied by edition = "2024". If this was intentional, you can leave it, of course.

ah I think there was a weird situation in another project where this was needed. I'm not too sure about the context right now

Maybe some situation with workspaces? I have not tested this myself, but the docs read like it should work to me. If you prefer being explicit, though, that's fine with me. 👍

mkroening · 2026-01-26T15:49:25Z

src/lib.rs

I would really appreciate some integration with embedded-io. This could also be an optional dependency if you prefer that.

The implementation could look something like this:

impl<B: Backend> embedded_io::ErrorType for Uart16550 { type Error = Infallible; } impl<B: Backend> embedded_io::Write for Uart16550 { fn write(&mut self, buf: &[u8]) -> Result<usize, Self::Error> { loop { if let Ok(n) = self.try_send_bytes(buf) { return Ok(n); } hint::spin_loop() } } fn flush(&mut self) -> Result<(), Self::Error> { Ok(()) } } impl<B: Backend> embedded_io::WriteReady for Uart16550 { fn write_ready(&mut self) -> Result<bool, Self::Error> { let lsr = self.lsr(); let msr = self.msr(); let mcr = self.mcr(); if !lsr.contains(LSR::THR_EMPTY) { return Ok(false); } if !mcr.contains(MCR::LOOP_BACK) && !msr.contains(MSR::CTS) { return Ok(false); } Ok(true) } } impl<B: Backend> embedded_io::Read for Uart16550 { fn read(&mut self, buf: &mut [u8]) -> Result<usize, Self::Error> { loop { let n = self.receive_bytes(buf); if n > 0 { return Ok(n); } hint::spin_loop(); } } } impl<B: Backend> embedded_io::ReadReady for Uart16550 { fn read_ready(&mut self) -> Result<bool, Self::Error> { let lsr = self.lsr(); Ok(lsr.contains(LSR::DATA_READY)) } }

Let me know if you would rather

integrate these changes into this PR yourselves,

have me create a PR against your PR, or

have me create a PR after your PR is merged.

great idea!

have me create a PR after your PR is merged.

would be better for reviewability I guess :)

mkroening · 2026-01-26T15:52:00Z

src/lib.rs

+#![deny(
+    clippy::all,
+    clippy::cargo,
+    clippy::nursery,
+    clippy::must_use_candidate,
+    clippy::missing_safety_doc,
+    clippy::undocumented_unsafe_blocks,
+    clippy::needless_pass_by_value
+)]
+#![deny(missing_docs)]
+#![deny(missing_debug_implementations)]
+#![deny(rustdoc::all)]


Could we make these warnings and enforce them in the CI? For me, development is easier if the code does compile, even if it is still imperfect.

Could we make these warnings and enforce them in the CI? For me, development is easier if the code does compile, even if it is still imperfect.

Hm, matter of taste of course. :) I use this in all my projects and am very happy with that. I don't have a strong opinion tho

If you prefer this, this is fine to me. I will adjust accordingly. :D

phip1611 · 2026-01-26T16:10:38Z

Thanks, this is great!

While I did not take a close look at every single line of code, this looks extremely solid to me.

Thanks :)

This does not break anything with Hermit (hermit-os/kernel#2191), and I have created an issue for adding 16550 UART device support on AArch64 and RISC-V (hermit-os/kernel#2192).

Awesome!

I don't know whether @phil-opp would prefer some attribution somewhere in the new repo.

Sure! Please let me know what the best option is.

treewide: nuke old repo

e1dc01e

phip1611 self-assigned this Jan 17, 2026

phip1611 requested review from mkroening and phil-opp January 17, 2026 17:32

phip1611 force-pushed the rewrite branch 3 times, most recently from d3473f7 to a43ff67 Compare January 17, 2026 17:44

This was referenced Jan 17, 2026

Add try_create and loopback_test for SerialPort #31

Open

mmio: Add ability to supply custom values for UART init #25

Open

Use traits for register and uart #39

Open

phip1611 force-pushed the rewrite branch from a43ff67 to a706c0c Compare January 18, 2026 10:42

Wasabi375 reviewed Jan 18, 2026

View reviewed changes

phip1611 force-pushed the rewrite branch from 961ceb6 to d2cd029 Compare January 18, 2026 16:01

phip1611 force-pushed the rewrite branch 10 times, most recently from 9a3ca6a to 05934be Compare January 19, 2026 16:15

phip1611 marked this pull request as ready for review January 19, 2026 16:15

phip1611 force-pushed the rewrite branch 3 times, most recently from b6cadd0 to 880be9e Compare January 19, 2026 16:41

phip1611 commented Jan 19, 2026

View reviewed changes

src/lib.rs Show resolved Hide resolved

phip1611 force-pushed the rewrite branch 4 times, most recently from 6feb766 to e0e4418 Compare January 24, 2026 16:00

phip1611 added 6 commits January 26, 2026 07:38

test: init integration test

d6dba25

This is a basic integration test that runs the code in a VM machine that uses a x86 port I/O backed UART16550.

doc: favor new_mmio() over new_pio()

749b3ab

This enables to compile the crate normally even on non-x86. We could work around using combinations of #[cfg] and #[doc], but this would be very ugly.

uart/mmio: add stride parameter

c5fc5d2

uart/mmio: add dummy unit test

4911c9a

backend: seal traits

41b5135

This is best practice in Rust. It is a private API helper anyway that just must be public to a certain degree.

phip1611 force-pushed the rewrite branch from e0e4418 to 41b5135 Compare January 26, 2026 06:38

This was referenced Jan 26, 2026

build(deps): update uart_16550 to 0.5 hermit-os/kernel#2191

Draft

Support 16550 UART devices on all architectures hermit-os/kernel#2192

Open

mkroening approved these changes Jan 26, 2026

View reviewed changes

treewide: nuke old repo and replace with rewrite from @phip1611 #41

Are you sure you want to change the base?

treewide: nuke old repo and replace with rewrite from @phip1611 #41

Uh oh!

Conversation

phip1611 commented Jan 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

TL;DR

Background

Notes about Real Hardware Tests

About API and Implementation

Example (Minimalistic)

Example (More low-level control)

Hints for Reviewers

Steps to Undraft

Uh oh!

Wasabi375 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

phip1611 commented Jan 18, 2026

Uh oh!

phip1611 commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

mkroening left a comment

Choose a reason for hiding this comment

Uh oh!

mkroening Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

phip1611 Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mkroening Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

mkroening Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

phip1611 Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

mkroening Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

mkroening Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

phip1611 Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mkroening Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

phip1611 Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mkroening Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

phip1611 commented Jan 26, 2026

Uh oh!

Reviewers

Assignees

Labels

phip1611 commented Jan 17, 2026 •

edited

Loading

phip1611 commented Jan 19, 2026 •

edited

Loading

phip1611 Jan 26, 2026 •

edited

Loading

mkroening Jan 26, 2026 •

edited

Loading

phip1611 Jan 26, 2026 •

edited

Loading

phip1611 Jan 26, 2026 •

edited

Loading