zx/
clock_update.rs

1// Copyright 2021 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5//! Type-safe bindings for Zircon clock update objects.
6//!
7//! Example usage:
8//! ```rust
9//! clock.update(ClockUpdate::builder().approximate_value(updated_time)).expect("update failed");
10//!
11//! let update = ClockUpdate::builder().rate_adjust(42).error_bounds(1_000_000).build();
12//! clock.update(update).expect("update failed");
13//! ```
14
15use crate::{sys, Instant, Timeline};
16use std::fmt::Debug;
17
18/// A trait implemented by all components of a ClockUpdateBuilder's state.
19pub trait State {
20    /// Records the validity in the supplied bitfield.
21    fn add_options(&self, options: &mut u64);
22}
23
24/// A trait implemented by states that describe how to set a clock value.
25pub trait ValueState: State {
26    type ReferenceTimeline: Timeline;
27    type OutputTimeline: Timeline;
28    fn reference_value(&self) -> Option<Instant<Self::ReferenceTimeline>>;
29    fn synthetic_value(&self) -> Option<Instant<Self::OutputTimeline>>;
30}
31
32/// A trait implemented by states that describe how to set a clock rate.
33pub trait RateState: State {
34    fn rate_adjustment(&self) -> Option<i32>;
35}
36
37/// A trait implemented by states that describe how to set a clock error.
38pub trait ErrorState: State {
39    fn error_bound(&self) -> Option<u64>;
40}
41
42/// A `ClockUpdateBuilder` state indicating no change.
43pub struct Null<R, O>(std::marker::PhantomData<(R, O)>);
44
45impl<R: Timeline, O: Timeline> State for Null<R, O> {
46    fn add_options(&self, _: &mut u64) {}
47}
48
49impl<R: Timeline, O: Timeline> ValueState for Null<R, O> {
50    type ReferenceTimeline = R;
51    type OutputTimeline = O;
52    fn reference_value(&self) -> Option<Instant<R>> {
53        None
54    }
55    fn synthetic_value(&self) -> Option<Instant<O>> {
56        None
57    }
58}
59impl<R: Timeline, O: Timeline> RateState for Null<R, O> {
60    fn rate_adjustment(&self) -> Option<i32> {
61        None
62    }
63}
64impl<R: Timeline, O: Timeline> ErrorState for Null<R, O> {
65    fn error_bound(&self) -> Option<u64> {
66        None
67    }
68}
69
70/// A `ClockUpdateBuilder` state indicating value should be set using a
71/// (reference time, synthetic time) tuple.
72pub struct AbsoluteValue<R, O> {
73    reference_value: Instant<R>,
74    synthetic_value: Instant<O>,
75}
76
77impl<R: Timeline + Copy, O: Timeline + Copy> State for AbsoluteValue<R, O> {
78    #[inline]
79    fn add_options(&self, opts: &mut u64) {
80        *opts |= sys::ZX_CLOCK_UPDATE_OPTION_REFERENCE_VALUE_VALID
81            | sys::ZX_CLOCK_UPDATE_OPTION_SYNTHETIC_VALUE_VALID;
82    }
83}
84
85impl<R: Timeline + Copy, O: Timeline + Copy> ValueState for AbsoluteValue<R, O> {
86    type ReferenceTimeline = R;
87    type OutputTimeline = O;
88    fn reference_value(&self) -> Option<Instant<R>> {
89        Some(self.reference_value)
90    }
91    fn synthetic_value(&self) -> Option<Instant<O>> {
92        Some(self.synthetic_value)
93    }
94}
95
96/// A `ClockUpdateBuilder` state indicating value should be set using only a synthetic time.
97pub struct ApproximateValue<R, O>(Instant<O>, std::marker::PhantomData<R>);
98
99impl<R: Timeline + Copy, O: Timeline + Copy> State for ApproximateValue<R, O> {
100    #[inline]
101    fn add_options(&self, opts: &mut u64) {
102        *opts |= sys::ZX_CLOCK_UPDATE_OPTION_SYNTHETIC_VALUE_VALID;
103    }
104}
105
106impl<R: Timeline + Copy, O: Timeline + Copy> ValueState for ApproximateValue<R, O> {
107    type ReferenceTimeline = R;
108    type OutputTimeline = O;
109    fn reference_value(&self) -> Option<Instant<R>> {
110        None
111    }
112    fn synthetic_value(&self) -> Option<Instant<O>> {
113        Some(self.0)
114    }
115}
116
117/// A clock update state indicating the rate should be set using the contained ppm offset.
118pub struct Rate(i32);
119
120impl State for Rate {
121    #[inline]
122    fn add_options(&self, opts: &mut u64) {
123        *opts |= sys::ZX_CLOCK_UPDATE_OPTION_RATE_ADJUST_VALID;
124    }
125}
126
127impl RateState for Rate {
128    fn rate_adjustment(&self) -> Option<i32> {
129        Some(self.0)
130    }
131}
132
133/// A clock update state indicating the clock error should be set using the contained bound in
134/// nanoseconds.
135pub struct Error(u64);
136
137impl State for Error {
138    #[inline]
139    fn add_options(&self, opts: &mut u64) {
140        *opts |= sys::ZX_CLOCK_UPDATE_OPTION_ERROR_BOUND_VALID;
141    }
142}
143
144impl ErrorState for Error {
145    fn error_bound(&self) -> Option<u64> {
146        Some(self.0)
147    }
148}
149
150/// Builder to specify how zero or more properties of a clock should be updated.
151/// See [`Clock::update`].
152///
153/// A `ClockUpdateBuilder` may be created using `ClockUpdate::builder()`.
154#[derive(Debug, Eq, PartialEq)]
155pub struct ClockUpdateBuilder<Val, Rate, Err, Ref, Out> {
156    value_state: Val,
157    rate_state: Rate,
158    error_state: Err,
159    _output_marker: std::marker::PhantomData<(Ref, Out)>,
160}
161
162impl<
163        Val: ValueState<ReferenceTimeline = Ref, OutputTimeline = Out>,
164        Rate: RateState,
165        Err: ErrorState,
166        Ref: Timeline,
167        Out: Timeline,
168    > ClockUpdateBuilder<Val, Rate, Err, Ref, Out>
169{
170    /// Converts this `ClockUpdateBuilder` to a `ClockUpdate`.
171    #[inline]
172    pub fn build(self) -> ClockUpdate<Ref, Out> {
173        ClockUpdate::from(self)
174    }
175}
176
177impl<R: Timeline, O: Timeline> ClockUpdateBuilder<Null<R, O>, Null<R, O>, Null<R, O>, R, O> {
178    /// Returns an empty `ClockUpdateBuilder`.
179    #[inline]
180    fn new() -> Self {
181        Self {
182            value_state: Null(std::marker::PhantomData),
183            rate_state: Null(std::marker::PhantomData),
184            error_state: Null(std::marker::PhantomData),
185            _output_marker: std::marker::PhantomData,
186        }
187    }
188}
189
190impl<Rate: RateState, Err: ErrorState, Ref: Timeline, Out: Timeline>
191    ClockUpdateBuilder<Null<Ref, Out>, Rate, Err, Ref, Out>
192{
193    /// Sets an absolute value for this `ClockUpdate` using a (reference time, synthetic time) pair.
194    ///
195    /// Reference time is typically monotonic and synthetic time is the time tracked by the clock.
196    /// Adding an absolute value is only possible when no other value has been set.
197    #[inline]
198    pub fn absolute_value(
199        self,
200        reference_value: Instant<Ref>,
201        synthetic_value: Instant<Out>,
202    ) -> ClockUpdateBuilder<AbsoluteValue<Ref, Out>, Rate, Err, Ref, Out> {
203        ClockUpdateBuilder {
204            value_state: AbsoluteValue { reference_value, synthetic_value },
205            rate_state: self.rate_state,
206            error_state: self.error_state,
207            _output_marker: std::marker::PhantomData,
208        }
209    }
210}
211
212impl<Err: ErrorState, Ref: Timeline, Out: Timeline>
213    ClockUpdateBuilder<Null<Ref, Out>, Null<Ref, Out>, Err, Ref, Out>
214{
215    /// Sets an approximate value for this `ClockUpdateBuilder` using a synthetic time only.
216    ///
217    /// Synthetic time is the time tracked by the clock. The reference time will be set to current
218    /// monotonic time when the kernel applies this clock update, meaning any delay between
219    /// calculating synthetic time and applying the update will result in a clock error. Adding an
220    /// approximate value is only possible when no other value has been set and when no rate has
221    /// been set.
222    #[inline]
223    pub fn approximate_value(
224        self,
225        synthetic_value: Instant<Out>,
226    ) -> ClockUpdateBuilder<ApproximateValue<Ref, Out>, Null<Ref, Out>, Err, Ref, Out> {
227        ClockUpdateBuilder {
228            value_state: ApproximateValue(synthetic_value, std::marker::PhantomData),
229            rate_state: self.rate_state,
230            error_state: self.error_state,
231            _output_marker: std::marker::PhantomData,
232        }
233    }
234}
235
236impl<Err: ErrorState, Ref: Timeline, Out: Timeline>
237    ClockUpdateBuilder<Null<Ref, Out>, Null<Ref, Out>, Err, Ref, Out>
238{
239    /// Adds a rate change in parts per million to this `ClockUpdateBuilder`.
240    ///
241    /// Adding a rate is only possible when the value is either not set or set to an absolute value
242    /// and when no rate has been set previously.
243    #[inline]
244    pub fn rate_adjust(
245        self,
246        rate_adjust_ppm: i32,
247    ) -> ClockUpdateBuilder<Null<Ref, Out>, Rate, Err, Ref, Out> {
248        ClockUpdateBuilder {
249            value_state: self.value_state,
250            rate_state: Rate(rate_adjust_ppm),
251            error_state: self.error_state,
252            _output_marker: std::marker::PhantomData,
253        }
254    }
255}
256
257impl<Err: ErrorState, Ref: Timeline, Out: Timeline>
258    ClockUpdateBuilder<AbsoluteValue<Ref, Out>, Null<Ref, Out>, Err, Ref, Out>
259{
260    /// Adds a rate change in parts per million to this `ClockUpdateBuilder`.
261    ///
262    /// Adding a rate is only possible when the value is either not set or set to an absolute value
263    /// and when no rate has been set previously.
264    #[inline]
265    pub fn rate_adjust(
266        self,
267        rate_adjust_ppm: i32,
268    ) -> ClockUpdateBuilder<AbsoluteValue<Ref, Out>, Rate, Err, Ref, Out> {
269        ClockUpdateBuilder {
270            value_state: self.value_state,
271            rate_state: Rate(rate_adjust_ppm),
272            error_state: self.error_state,
273            _output_marker: std::marker::PhantomData,
274        }
275    }
276}
277
278impl<Val: ValueState, Rate: RateState, Ref: Timeline, Out: Timeline>
279    ClockUpdateBuilder<Val, Rate, Null<Ref, Out>, Ref, Out>
280{
281    /// Adds an error bound in nanoseconds to this `ClockUpdateBuilder`.
282    #[inline]
283    pub fn error_bounds(
284        self,
285        error_bound_ns: u64,
286    ) -> ClockUpdateBuilder<Val, Rate, Error, Ref, Out> {
287        ClockUpdateBuilder {
288            value_state: self.value_state,
289            rate_state: self.rate_state,
290            error_state: Error(error_bound_ns),
291            _output_marker: std::marker::PhantomData,
292        }
293    }
294}
295
296/// Specifies an update to zero or more properties of a clock. See [`Clock::update`]
297#[derive(Debug, Eq, PartialEq)]
298pub struct ClockUpdate<Reference, Output> {
299    options: u64,
300    rate_adjust: i32,
301    synthetic_value: Instant<Output>,
302    reference_value: Instant<Reference>,
303    error_bound: u64,
304}
305
306impl<R: Timeline, O: Timeline> ClockUpdate<R, O> {
307    /// Returns a new, empty, `ClockUpdateBuilder`.
308    #[inline]
309    pub fn builder() -> ClockUpdateBuilder<Null<R, O>, Null<R, O>, Null<R, O>, R, O> {
310        ClockUpdateBuilder::new()
311    }
312
313    /// Returns a bitfield of options to pass to [`sys::zx_clock_update`] in conjunction with a
314    /// `zx_clock_update_args_v2_t` generated from this `ClockUpdate`.
315    #[inline]
316    pub fn options(&self) -> u64 {
317        self.options
318    }
319
320    pub(crate) fn args(self) -> sys::zx_clock_update_args_v2_t {
321        let mut ret = sys::zx_clock_update_args_v2_t::default();
322        ret.rate_adjust = self.rate_adjust;
323        ret.synthetic_value = self.synthetic_value.into_nanos();
324        ret.reference_value = self.reference_value.into_nanos();
325        ret.error_bound = self.error_bound;
326        ret
327    }
328}
329
330impl<
331        Val: ValueState<ReferenceTimeline = Ref, OutputTimeline = Out>,
332        Rate: RateState,
333        Err: ErrorState,
334        Ref: Timeline,
335        Out: Timeline,
336    > From<ClockUpdateBuilder<Val, Rate, Err, Ref, Out>> for ClockUpdate<Ref, Out>
337{
338    fn from(builder: ClockUpdateBuilder<Val, Rate, Err, Ref, Out>) -> Self {
339        let mut options = sys::ZX_CLOCK_ARGS_VERSION_2;
340        builder.value_state.add_options(&mut options);
341        builder.rate_state.add_options(&mut options);
342        builder.error_state.add_options(&mut options);
343
344        Self {
345            options,
346            rate_adjust: builder.rate_state.rate_adjustment().unwrap_or_default(),
347            synthetic_value: builder.value_state.synthetic_value().unwrap_or_default(),
348            reference_value: builder.value_state.reference_value().unwrap_or_default(),
349            error_bound: builder.error_state.error_bound().unwrap_or_default(),
350        }
351    }
352}
353
354#[cfg(test)]
355mod tests {
356    use super::*;
357    use crate::{MonotonicInstant, MonotonicTimeline, SyntheticInstant, SyntheticTimeline};
358
359    #[test]
360    fn empty_update() {
361        let update =
362            ClockUpdateBuilder::<_, _, _, MonotonicTimeline, SyntheticTimeline>::new().build();
363        assert_eq!(update.options(), sys::ZX_CLOCK_ARGS_VERSION_2);
364        assert_eq!(update.args(), sys::zx_clock_update_args_v2_t::default(),);
365    }
366
367    #[test]
368    fn rate_only() {
369        let update = ClockUpdate::<MonotonicTimeline, SyntheticTimeline>::from(
370            ClockUpdateBuilder::new().rate_adjust(52),
371        );
372        assert_eq!(
373            update.options(),
374            sys::ZX_CLOCK_ARGS_VERSION_2 | sys::ZX_CLOCK_UPDATE_OPTION_RATE_ADJUST_VALID
375        );
376        let args = update.args();
377        assert_eq!(args.rate_adjust, 52);
378        assert_eq!(args.reference_value, 0);
379        assert_eq!(args.synthetic_value, 0);
380        assert_eq!(args.error_bound, 0);
381    }
382
383    #[test]
384    fn approximate_value() {
385        let update = ClockUpdateBuilder::<_, _, _, MonotonicTimeline, SyntheticTimeline>::new()
386            .approximate_value(SyntheticInstant::from_nanos(42))
387            .error_bounds(62)
388            .build();
389        assert_eq!(
390            update.options(),
391            sys::ZX_CLOCK_ARGS_VERSION_2
392                | sys::ZX_CLOCK_UPDATE_OPTION_SYNTHETIC_VALUE_VALID
393                | sys::ZX_CLOCK_UPDATE_OPTION_ERROR_BOUND_VALID
394        );
395        let args = update.args();
396        assert_eq!(args.rate_adjust, 0);
397        assert_eq!(args.reference_value, 0);
398        assert_eq!(args.synthetic_value, 42);
399        assert_eq!(args.error_bound, 62);
400    }
401
402    #[test]
403    fn absolute_value() {
404        let update = ClockUpdateBuilder::<_, _, _, MonotonicTimeline, SyntheticTimeline>::new()
405            .absolute_value(MonotonicInstant::from_nanos(1000), SyntheticInstant::from_nanos(42))
406            .rate_adjust(52)
407            .error_bounds(62)
408            .build();
409        assert_eq!(
410            update.options(),
411            sys::ZX_CLOCK_ARGS_VERSION_2
412                | sys::ZX_CLOCK_UPDATE_OPTION_REFERENCE_VALUE_VALID
413                | sys::ZX_CLOCK_UPDATE_OPTION_SYNTHETIC_VALUE_VALID
414                | sys::ZX_CLOCK_UPDATE_OPTION_RATE_ADJUST_VALID
415                | sys::ZX_CLOCK_UPDATE_OPTION_ERROR_BOUND_VALID
416        );
417
418        let args = update.args();
419        assert_eq!(args.rate_adjust, 52);
420        assert_eq!(args.reference_value, 1000);
421        assert_eq!(args.synthetic_value, 42);
422        assert_eq!(args.error_bound, 62);
423    }
424}
zx/clock_update.rs

zx/
clock_update.rs
