2 files changed, 61 insertions, 0 deletions

diff --git a/embassy-executor/Cargo.toml b/embassy-executor/Cargo.toml
index 60fe7087a..2a64b9c83 100644
--- a/embassy-executor/Cargo.toml
+++ b/embassy-executor/Cargo.toml
@@ -92,6 +92,22 @@ trace = []
 ## Enable support for rtos-trace framework
 rtos-trace = ["dep:rtos-trace", "trace", "dep:embassy-time-driver"]
 
+#! ### Timer Item Payload Size
+#! Sets the size of the payload for timer items, allowing integrated timer implementors to store
+#! additional data in the timer item. The payload field will be aligned to this value as well.
+#! If these features are not defined, the timer item will contain no payload field.
+
+_timer-item-payload = [] # A size was picked
+
+## 1 bytes
+timer-item-payload-size-1 = ["_timer-item-payload"]
+## 2 bytes
+timer-item-payload-size-2 = ["_timer-item-payload"]
+## 4 bytes
+timer-item-payload-size-4 = ["_timer-item-payload"]
+## 8 bytes
+timer-item-payload-size-8 = ["_timer-item-payload"]
+
 #! ### Task Arena Size
 #! Sets the [task arena](#task-arena) size. Necessary if you’re not using `nightly`.
 #!
diff --git a/embassy-executor/src/raw/timer_queue.rs b/embassy-executor/src/raw/timer_queue.rs
index 2ba0e00a9..c4dba18ff 100644
--- a/embassy-executor/src/raw/timer_queue.rs
+++ b/embassy-executor/src/raw/timer_queue.rs
@@ -4,6 +4,45 @@ use core::cell::Cell;
 
 use super::TaskRef;
 
+#[cfg(feature = "_timer-item-payload")]
+macro_rules! define_opaque {
+    ($size:tt) => {
+        /// An opaque data type.
+        #[repr(align($size))]
+        pub struct OpaqueData {
+            data: [u8; $size],
+        }
+
+        impl OpaqueData {
+            const fn new() -> Self {
+                Self { data: [0; $size] }
+            }
+
+            /// Access the data as a reference to a type `T`.
+            ///
+            /// Safety:
+            ///
+            /// The caller must ensure that the size of the type `T` is less than, or equal to
+            /// the size of the payload, and must ensure that the alignment of the type `T` is
+            /// less than, or equal to the alignment of the payload.
+            ///
+            /// The type must be valid when zero-initialized.
+            pub unsafe fn as_ref<T>(&self) -> &T {
+                &*(self.data.as_ptr() as *const T)
+            }
+        }
+    };
+}
+
+#[cfg(feature = "timer-item-payload-size-1")]
+define_opaque!(1);
+#[cfg(feature = "timer-item-payload-size-2")]
+define_opaque!(2);
+#[cfg(feature = "timer-item-payload-size-4")]
+define_opaque!(4);
+#[cfg(feature = "timer-item-payload-size-8")]
+define_opaque!(8);
+
 /// An item in the timer queue.
 pub struct TimerQueueItem {
     /// The next item in the queue.
@@ -14,6 +53,10 @@ pub struct TimerQueueItem {
 
     /// The time at which this item expires.
     pub expires_at: Cell<u64>,
+
+    /// Some implementation-defined, zero-initialized piece of data.
+    #[cfg(feature = "_timer-item-payload")]
+    pub payload: OpaqueData,
 }
 
 unsafe impl Sync for TimerQueueItem {}
@@ -23,6 +66,8 @@ impl TimerQueueItem {
         Self {
             next: Cell::new(None),
             expires_at: Cell::new(0),
+            #[cfg(feature = "_timer-item-payload")]
+            payload: OpaqueData::new(),
         }
     }
 }