Within the hrtimer API there are quite a number of functions that can only
be safely called from one of two contexts:

* When we have exclusive access to the hrtimer and the timer is not active.
* When we're within the hrtimer's callback context as it is being executed.

This commit adds bindings for hrtimer_forward() for the first such context,
along with HrTimer::raw_forward() for later use in implementing the
hrtimer_forward() in the latter context.

Signed-off-by: Lyude Paul <lyude@redhat.com>

---
V4:
* Fix the safety contract for raw_forward()
* Require Pin<&mut Self>, not &mut self
* Drop incorrect UniquePin example
* Rewrite documentation a bit (re: Andreas)
V6:
* Remove the reference to HrTimerCallbackContext::forward() until this
  function gets added.

Signed-off-by: Lyude Paul <lyude@redhat.com>
---
 rust/kernel/time/hrtimer.rs | 40 +++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/rust/kernel/time/hrtimer.rs b/rust/kernel/time/hrtimer.rs
index be1bad4aacaad..5ccdd1b0b8021 100644
--- a/rust/kernel/time/hrtimer.rs
+++ b/rust/kernel/time/hrtimer.rs
@@ -168,6 +168,46 @@ pub(crate) unsafe fn raw_cancel(this: *const Self) -> bool {
         // handled on the C side.
         unsafe { bindings::hrtimer_cancel(c_timer_ptr) != 0 }
     }
+
+    /// Forward the timer expiry for a given timer pointer.
+    ///
+    /// # Safety
+    ///
+    /// - `self_ptr` must point to a valid `Self`.
+    /// - The caller must either have exclusive access to the data pointed at by `self_ptr`, or be
+    ///   within the context of the timer callback.
+    #[inline]
+    unsafe fn raw_forward(self_ptr: *mut Self, now: HrTimerInstant<T>, interval: Delta) -> u64
+    where
+        T: HasHrTimer<T>,
+    {
+        // SAFETY:
+        // * The C API requirements for this function are fulfilled by our safety contract.
+        // * `self_ptr` is guaranteed to point to a valid `Self` via our safety contract
+        unsafe {
+            bindings::hrtimer_forward(Self::raw_get(self_ptr), now.as_nanos(), interval.as_nanos())
+        }
+    }
+
+    /// Conditionally forward the timer.
+    ///
+    /// If the timer expires after `now`, this function does nothing and returns 0. If the timer
+    /// expired at or before `now`, this function forwards the timer by `interval` until the timer
+    /// expires after `now` and then returns the number of times the timer was forwarded by
+    /// `interval`.
+    ///
+    /// Returns the number of overruns that occurred as a result of the timer expiry change.
+    pub fn forward(self: Pin<&mut Self>, now: HrTimerInstant<T>, interval: Delta) -> u64
+    where
+        T: HasHrTimer<T>,
+    {
+        // SAFETY:
+        // - `raw_forward` does not move `self`.
+        // - Self is a mutable reference and thus always points to a valid `HrTimer`
+        // - The only way that we could hold a mutable reference to `HrTimer<T>` is if we have
+        //   exclusive access to it - fulfilling the requirements of the C API.
+        unsafe { Self::raw_forward(self.get_unchecked_mut(), now, interval) }
+    }
 }
 
 /// Implemented by pointer types that point to structs that contain a [`HrTimer`].
-- 
2.50.0

"Lyude Paul" <lyude@redhat.com> writes:

> Within the hrtimer API there are quite a number of functions that can only
> be safely called from one of two contexts:
>
> * When we have exclusive access to the hrtimer and the timer is not active.
> * When we're within the hrtimer's callback context as it is being executed.
>
> This commit adds bindings for hrtimer_forward() for the first such context,
> along with HrTimer::raw_forward() for later use in implementing the
> hrtimer_forward() in the latter context.
>
> Signed-off-by: Lyude Paul <lyude@redhat.com>
>
> ---
> V4:
> * Fix the safety contract for raw_forward()
> * Require Pin<&mut Self>, not &mut self
> * Drop incorrect UniquePin example
> * Rewrite documentation a bit (re: Andreas)
> V6:
> * Remove the reference to HrTimerCallbackContext::forward() until this
>   function gets added.
>
> Signed-off-by: Lyude Paul <lyude@redhat.com>
> ---
>  rust/kernel/time/hrtimer.rs | 40 +++++++++++++++++++++++++++++++++++++
>  1 file changed, 40 insertions(+)
>
> diff --git a/rust/kernel/time/hrtimer.rs b/rust/kernel/time/hrtimer.rs
> index be1bad4aacaad..5ccdd1b0b8021 100644
> --- a/rust/kernel/time/hrtimer.rs
> +++ b/rust/kernel/time/hrtimer.rs
> @@ -168,6 +168,46 @@ pub(crate) unsafe fn raw_cancel(this: *const Self) -> bool {
>          // handled on the C side.
>          unsafe { bindings::hrtimer_cancel(c_timer_ptr) != 0 }
>      }
> +
> +    /// Forward the timer expiry for a given timer pointer.
> +    ///
> +    /// # Safety
> +    ///
> +    /// - `self_ptr` must point to a valid `Self`.
> +    /// - The caller must either have exclusive access to the data pointed at by `self_ptr`, or be
> +    ///   within the context of the timer callback.
> +    #[inline]
> +    unsafe fn raw_forward(self_ptr: *mut Self, now: HrTimerInstant<T>, interval: Delta) -> u64
> +    where
> +        T: HasHrTimer<T>,
> +    {
> +        // SAFETY:
> +        // * The C API requirements for this function are fulfilled by our safety contract.
> +        // * `self_ptr` is guaranteed to point to a valid `Self` via our safety contract
> +        unsafe {
> +            bindings::hrtimer_forward(Self::raw_get(self_ptr), now.as_nanos(), interval.as_nanos())
> +        }
> +    }
> +
> +    /// Conditionally forward the timer.
> +    ///
> +    /// If the timer expires after `now`, this function does nothing and returns 0. If the timer
> +    /// expired at or before `now`, this function forwards the timer by `interval` until the timer
> +    /// expires after `now` and then returns the number of times the timer was forwarded by
> +    /// `interval`.
> +    ///
> +    /// Returns the number of overruns that occurred as a result of the timer expiry change.
> +    pub fn forward(self: Pin<&mut Self>, now: HrTimerInstant<T>, interval: Delta) -> u64
> +    where
> +        T: HasHrTimer<T>,
> +    {
> +        // SAFETY:
> +        // - `raw_forward` does not move `self`.
> +        // - Self is a mutable reference and thus always points to a valid `HrTimer`
> +        // - The only way that we could hold a mutable reference to `HrTimer<T>` is if we have
> +        //   exclusive access to it - fulfilling the requirements of the C API.

C API requirements are not relevant for this call. Maybe you can replace
the last two lines by:

  By existence of `Pin<&mut Self>`, the pointer passed to `raw_forward`
  points to a valid `Self` that we have exclusive access to.

It is slightly obscure because we coerce `self.get_unchecked_mut() ->
&mut Self` to `*mut Self` in one go. Perhaps split it up:

  let self_ptr: *mut Self = self.get_unchecked_mut();
  // SAFETY: ...
  unsafe { Self::raw_forward(self_ptr, now, interval) }

Best regards,
Andreas Hindborg

[…]


> +
> +    /// Conditionally forward the timer.
> +    ///
> +    /// If the timer expires after `now`, this function does nothing and returns 0. If the timer
> +    /// expired at or before `now`, this function forwards the timer by `interval` until the timer
> +    /// expires after `now` and then returns the number of times the timer was forwarded by
> +    /// `interval`.
> +    ///
> +    /// Returns the number of overruns that occurred as a result of the timer expiry change.
> +    pub fn forward(self: Pin<&mut Self>, now: HrTimerInstant<T>, interval: Delta) -> u64
> +    where
> +        T: HasHrTimer<T>,
> +    {
> +        // SAFETY:
> +        // - `raw_forward` does not move `self`.
> +        // - Self is a mutable reference and thus always points to a valid `HrTimer`

I get what you're trying to say, but IMHO using the word "mutable" here is
confusing. Mutability has nothing to do on whether something is valid. This
should be rephrased, IMHO.

> +        // - The only way that we could hold a mutable reference to `HrTimer<T>` is if we have
> +        //   exclusive access to it - fulfilling the requirements of the C API.
> +        unsafe { Self::raw_forward(self.get_unchecked_mut(), now, interval) }
> +    }
> }
> 
> /// Implemented by pointer types that point to structs that contain a [`HrTimer`].
> -- 
> 2.50.0
> 
> 

"Daniel Almeida" <daniel.almeida@collabora.com> writes:

> […]
>
>
>> +
>> +    /// Conditionally forward the timer.
>> +    ///
>> +    /// If the timer expires after `now`, this function does nothing and returns 0. If the timer
>> +    /// expired at or before `now`, this function forwards the timer by `interval` until the timer
>> +    /// expires after `now` and then returns the number of times the timer was forwarded by
>> +    /// `interval`.
>> +    ///
>> +    /// Returns the number of overruns that occurred as a result of the timer expiry change.
>> +    pub fn forward(self: Pin<&mut Self>, now: HrTimerInstant<T>, interval: Delta) -> u64
>> +    where
>> +        T: HasHrTimer<T>,
>> +    {
>> +        // SAFETY:
>> +        // - `raw_forward` does not move `self`.
>> +        // - Self is a mutable reference and thus always points to a valid `HrTimer`
>
> I get what you're trying to say, but IMHO using the word "mutable" here is
> confusing. Mutability has nothing to do on whether something is valid. This
> should be rephrased, IMHO.

Having a reference to something implies validity. We could do:

  The coertion of `&mut Self` to `*mut Self` results in a pointer to a
  valid `Self`.


Best regards,
Andreas Hindborg