feat: implement embedded-io traits#42
Open
mkroening wants to merge 8 commits intorust-osdev:masterfrom
Open
Conversation
## 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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR implements
embedded-io's traits.This makes the serial port usable via
std-likeReadandWritetraits.This PR depends on #41.