4 files changed, 95 insertions, 0 deletions

diff --git a/embassy-time-queue-driver/Cargo.toml b/embassy-time-queue-driver/Cargo.toml
new file mode 100644
index 000000000..9ce9d79bb
--- /dev/null
+++ b/embassy-time-queue-driver/Cargo.toml
@@ -0,0 +1,26 @@
+[package]
+name = "embassy-time-queue-driver"
+version = "0.1.0"
+edition = "2021"
+description = "Timer queue driver trait for embassy-time"
+repository = "https://github.com/embassy-rs/embassy"
+documentation = "https://docs.embassy.dev/embassy-time-queue-driver"
+readme = "README.md"
+license = "MIT OR Apache-2.0"
+categories = [
+    "embedded",
+    "no-std",
+    "concurrency",
+    "asynchronous",
+]
+
+# Prevent multiple copies of this crate in the same binary.
+# Needed because different copies might get different tick rates, causing
+# wrong delays if the time driver is using one copy and user code is using another.
+# This is especially common when mixing crates from crates.io and git.
+links = "embassy-time-queue"
+
+[package.metadata.embassy_docs]
+src_base = "https://github.com/embassy-rs/embassy/blob/embassy-time-queue-driver-v$VERSION/embassy-time-queue-driver/src/"
+src_base_git = "https://github.com/embassy-rs/embassy/blob/$COMMIT/embassy-time-queue-driver/src/"
+target = "x86_64-unknown-linux-gnu"
diff --git a/embassy-time-queue-driver/README.md b/embassy-time-queue-driver/README.md
new file mode 100644
index 000000000..8852b0358
--- /dev/null
+++ b/embassy-time-queue-driver/README.md
@@ -0,0 +1,8 @@
+# embassy-time-queue-driver
+
+This crate contains the driver trait used by the [`embassy-time`](https://crates.io/crates/embassy-time) timer queue.
+
+You should rarely need to use this crate directly. Only use it when implementing your own timer queue.
+
+There is two timer queue implementations, one in `embassy-time` enabled by the `generic-queue` feature, and 
+another in `embassy-executor` enabled by the `integrated-timers` feature.
diff --git a/embassy-time-queue-driver/build.rs b/embassy-time-queue-driver/build.rs
new file mode 100644
index 000000000..f328e4d9d
--- /dev/null
+++ b/embassy-time-queue-driver/build.rs
@@ -0,0 +1 @@
+fn main() {}
diff --git a/embassy-time-queue-driver/src/lib.rs b/embassy-time-queue-driver/src/lib.rs
new file mode 100644
index 000000000..50736e8c7
--- /dev/null
+++ b/embassy-time-queue-driver/src/lib.rs
@@ -0,0 +1,60 @@
+#![no_std]
+#![doc = include_str!("../README.md")]
+#![warn(missing_docs)]
+
+//! ## Implementing a timer queue
+//!
+//! - Define a struct `MyTimerQueue`
+//! - Implement [`TimerQueue`] for it
+//! - Register it as the global timer queue with [`timer_queue_impl`](crate::timer_queue_impl).
+//!
+//! ## Example
+//!
+//! ```
+//! use core::task::Waker;
+//!
+//! use embassy_time::Instant;
+//! use embassy_time::queue::{TimerQueue};
+//!
+//! struct MyTimerQueue{}; // not public!
+//!
+//! impl TimerQueue for MyTimerQueue {
+//!     fn schedule_wake(&'static self, at: u64, waker: &Waker) {
+//!         todo!()
+//!     }
+//! }
+//!
+//! embassy_time_queue_driver::timer_queue_impl!(static QUEUE: MyTimerQueue = MyTimerQueue{});
+//! ```
+use core::task::Waker;
+
+/// Timer queue
+pub trait TimerQueue {
+    /// Schedules a waker in the queue to be awoken at moment `at`.
+    /// If this moment is in the past, the waker might be awoken immediately.
+    fn schedule_wake(&'static self, at: u64, waker: &Waker);
+}
+
+extern "Rust" {
+    fn _embassy_time_schedule_wake(at: u64, waker: &Waker);
+}
+
+/// Schedule the given waker to be woken at `at`.
+pub fn schedule_wake(at: u64, waker: &Waker) {
+    unsafe { _embassy_time_schedule_wake(at, waker) }
+}
+
+/// Set the TimerQueue implementation.
+///
+/// See the module documentation for an example.
+#[macro_export]
+macro_rules! timer_queue_impl {
+    (static $name:ident: $t: ty = $val:expr) => {
+        static $name: $t = $val;
+
+        #[no_mangle]
+        fn _embassy_time_schedule_wake(at: u64, waker: &core::task::Waker) {
+            <$t as $crate::TimerQueue>::schedule_wake(&$name, at, waker);
+        }
+    };
+}