statime/
ptp_instance.rs

1use core::{
2    cell::RefCell,
3    marker::PhantomData,
4    sync::atomic::{AtomicI8, Ordering},
5};
6
7use rand::Rng;
8
9#[allow(unused_imports)]
10use crate::float_polyfill::FloatPolyfill;
11use crate::{
12    bmc::{acceptable_master::AcceptableMasterList, bmca::Bmca},
13    clock::Clock,
14    config::{ClockQuality, InstanceConfig, PortConfig},
15    datastructures::{
16        common::PortIdentity,
17        datasets::{
18            InternalCurrentDS, InternalDefaultDS, InternalParentDS, PathTraceDS, TimePropertiesDS,
19        },
20    },
21    filters::{Filter, FilterEstimate},
22    observability::{current::CurrentDS, default::DefaultDS, parent::ParentDS},
23    port::{InBmca, Port},
24    time::Duration,
25};
26
27/// A PTP node.
28///
29/// This object handles the complete running of the PTP protocol once created.
30/// It provides all the logic for both ordinary and boundary clock mode.
31///
32/// # Example
33///
34/// ```no_run
35/// # struct MockClock;
36/// # impl statime::Clock for MockClock {
37/// #     type Error = ();
38/// #     fn now(&self) -> statime::time::Time {
39/// #         unimplemented!()
40/// #     }
41/// #     fn step_clock(&mut self, _: statime::time::Duration) -> Result<statime::time::Time, Self::Error> {
42/// #         unimplemented!()
43/// #     }
44/// #     fn set_frequency(&mut self, _: f64) -> Result<statime::time::Time, Self::Error> {
45/// #         unimplemented!()
46/// #     }
47/// #     fn set_properties(&mut self, _: &TimePropertiesDS) -> Result<(), Self::Error> {
48/// #         unimplemented!()
49/// #     }
50/// # }
51/// # mod system {
52/// #     pub fn get_mac() -> [u8; 6] { unimplemented!() }
53/// #     pub fn sleep(time: core::time::Duration) { unimplemented!() }
54/// # }
55/// # let port_config: statime::config::PortConfig<AcceptAnyMaster> = unimplemented!();
56/// # let filter_config = unimplemented!();
57/// # let clock: MockClock = unimplemented!();
58/// # let rng: rand::rngs::mock::StepRng = unimplemented!();
59/// #
60/// use statime::PtpInstance;
61/// use statime::config::{AcceptAnyMaster, ClockIdentity, ClockQuality, InstanceConfig, TimePropertiesDS, TimeSource};
62/// use statime::filters::BasicFilter;
63///
64/// let instance_config = InstanceConfig {
65///     clock_identity: ClockIdentity::from_mac_address(system::get_mac()),
66///     priority_1: 128,
67///     priority_2: 128,
68///     domain_number: 0,
69///     slave_only: false,
70///     sdo_id: Default::default(),
71///     path_trace: false,
72///     clock_quality: ClockQuality::default(),
73/// };
74/// let time_properties_ds = TimePropertiesDS::new_arbitrary_time(false, false, TimeSource::InternalOscillator);
75///
76/// let mut instance = PtpInstance::<BasicFilter>::new(
77///     instance_config,
78///     time_properties_ds,
79/// );
80///
81/// let mut port = instance.add_port(port_config, filter_config, clock, rng);
82///
83/// // Send of port to its own thread/task to do its work
84///
85/// loop {
86///     instance.bmca(&mut [&mut port]);
87///     system::sleep(instance.bmca_interval());
88/// }
89/// ```
90pub struct PtpInstance<F, S = RefCell<PtpInstanceState>> {
91    state: S,
92    log_bmca_interval: AtomicI8,
93    _filter: PhantomData<F>,
94}
95
96/// The inner state of a [`PtpInstance`]
97#[derive(Debug)]
98pub struct PtpInstanceState {
99    pub(crate) default_ds: InternalDefaultDS,
100    pub(crate) current_ds: InternalCurrentDS,
101    pub(crate) parent_ds: InternalParentDS,
102    pub(crate) path_trace_ds: PathTraceDS,
103    pub(crate) time_properties_ds: TimePropertiesDS,
104}
105
106impl PtpInstanceState {
107    fn bmca<A: AcceptableMasterList, C: Clock, F: Filter, R: Rng, S: PtpInstanceStateMutex>(
108        &mut self,
109        ports: &mut [&mut Port<'_, InBmca, A, R, C, F, S>],
110        bmca_interval: Duration,
111    ) {
112        debug_assert_eq!(self.default_ds.number_ports as usize, ports.len());
113
114        for port in ports.iter_mut() {
115            port.calculate_best_local_announce_message()
116        }
117
118        let ebest = Bmca::<()>::find_best_announce_message(
119            ports
120                .iter()
121                .filter_map(|port| port.best_local_announce_message_for_bmca()),
122        );
123
124        for port in ports.iter_mut() {
125            let recommended_state = Bmca::<()>::calculate_recommended_state(
126                &self.default_ds,
127                ebest,
128                port.best_local_announce_message_for_state(), // erbest
129                port.state(),
130            );
131
132            log::debug!(
133                "Recommended state port {}: {recommended_state:?}",
134                port.number(),
135            );
136
137            if let Some(recommended_state) = recommended_state {
138                port.set_recommended_state(
139                    recommended_state,
140                    &mut self.path_trace_ds,
141                    &mut self.time_properties_ds,
142                    &mut self.current_ds,
143                    &mut self.parent_ds,
144                    &self.default_ds,
145                );
146            }
147        }
148
149        // And update announce message ages
150        for port in ports.iter_mut() {
151            port.step_announce_age(bmca_interval);
152        }
153    }
154}
155
156impl<F, S: PtpInstanceStateMutex> PtpInstance<F, S> {
157    /// Construct a new [`PtpInstance`] with the given config and time
158    /// properties
159    pub fn new(config: InstanceConfig, time_properties_ds: TimePropertiesDS) -> Self {
160        let default_ds = InternalDefaultDS::new(config);
161
162        Self {
163            state: S::new(PtpInstanceState {
164                default_ds,
165                current_ds: Default::default(),
166                parent_ds: InternalParentDS::new(default_ds),
167                path_trace_ds: PathTraceDS::new(config.path_trace),
168                time_properties_ds,
169            }),
170            log_bmca_interval: AtomicI8::new(i8::MAX),
171            _filter: PhantomData,
172        }
173    }
174
175    /// Return IEEE-1588 defaultDS for introspection
176    pub fn default_ds(&self) -> DefaultDS {
177        self.state.with_ref(|s| (&s.default_ds).into())
178    }
179
180    /// Return IEEE-1588 currentDS for introspection
181    pub fn current_ds(&self, port_contribution: Option<FilterEstimate>) -> CurrentDS {
182        self.state
183            .with_ref(|s| CurrentDS::from_state(&s.current_ds, port_contribution))
184    }
185
186    /// Return IEEE-1588 parentDS for introspection
187    pub fn parent_ds(&self) -> ParentDS {
188        self.state.with_ref(|s| (&s.parent_ds).into())
189    }
190
191    /// Return IEEE-1588 timePropertiesDS for introspection
192    pub fn time_properties_ds(&self) -> TimePropertiesDS {
193        self.state.with_ref(|s| s.time_properties_ds)
194    }
195
196    /// Return IEEE-1588 pathTraceDS for introspection
197    pub fn path_trace_ds(&self) -> PathTraceDS {
198        self.state.with_ref(|s| s.path_trace_ds.clone())
199    }
200}
201
202impl<F: Filter, S: PtpInstanceStateMutex> PtpInstance<F, S> {
203    /// Add and initialize this port
204    ///
205    /// We start in the BMCA state because that is convenient
206    ///
207    /// When providing the port with a different clock than the instance clock,
208    /// the caller is responsible for propagating any property changes to this
209    /// clock, and for synchronizing this clock with the instance clock as
210    /// appropriate based on the ports state.
211    pub fn add_port<A, C, R: Rng>(
212        &self,
213        config: PortConfig<A>,
214        filter_config: F::Config,
215        clock: C,
216        rng: R,
217    ) -> Port<'_, InBmca, A, R, C, F, S> {
218        self.log_bmca_interval
219            .fetch_min(config.announce_interval.as_log_2(), Ordering::Relaxed);
220        let port_identity = self.state.with_mut(|state| {
221            state.default_ds.number_ports += 1;
222            PortIdentity {
223                clock_identity: state.default_ds.clock_identity,
224                port_number: state.default_ds.number_ports,
225            }
226        });
227
228        Port::new(
229            &self.state,
230            config,
231            filter_config,
232            clock,
233            port_identity,
234            rng,
235        )
236    }
237
238    /// Run the best master clock algorithm (BMCA)
239    ///
240    /// The caller must pass all the ports that were created on this instance in
241    /// the slice!
242    pub fn bmca<A: AcceptableMasterList, C: Clock, R: Rng>(
243        &self,
244        ports: &mut [&mut Port<'_, InBmca, A, R, C, F, S>],
245    ) {
246        self.state.with_mut(|state| {
247            state.bmca(
248                ports,
249                Duration::from_seconds(
250                    2f64.powi(self.log_bmca_interval.load(Ordering::Relaxed) as i32),
251                ),
252            );
253        });
254    }
255
256    /// Time to wait between calls to [`PtpInstance::bmca`]
257    pub fn bmca_interval(&self) -> core::time::Duration {
258        core::time::Duration::from_secs_f64(
259            2f64.powi(self.log_bmca_interval.load(Ordering::Relaxed) as i32),
260        )
261    }
262
263    /// Set the clock quality of the instance
264    ///
265    /// This allows changing the clock quality after the instance has been
266    /// created. The change will be reflected in all subsequent PTP messages
267    /// sent by this instance and the BMCA algorithm will use the new clock
268    /// quality.
269    pub fn set_clock_quality(&self, clock_quality: ClockQuality) {
270        self.state.with_mut(|state| {
271            state.default_ds.clock_quality = clock_quality;
272        });
273    }
274
275    /// Set whether this instance is allowed to become a master.
276    ///
277    /// This allows toggling `slave_only` after the instance has been created.
278    /// The change takes effect during subsequent BMCA decisions and timeout handling.
279    /// After a BMCA run, ports that are currently master will be moved back to the
280    /// listening state, and other ports will be prevented from becoming master.
281    pub fn set_slave_only(&self, slave_only: bool) {
282        self.state.with_mut(|state| {
283            state.default_ds.slave_only = slave_only;
284        })
285    }
286}
287
288/// A mutex over a [`PtpInstanceState`]
289///
290/// This provides an abstraction for locking state in various environments.
291/// Implementations are provided for [`core::cell::RefCell`] and
292/// [`std::sync::RwLock`].
293pub trait PtpInstanceStateMutex {
294    /// Creates a new instance of the mutex
295    fn new(state: PtpInstanceState) -> Self;
296
297    /// Takes a shared reference to the contained state and calls `f` with it
298    fn with_ref<R, F: FnOnce(&PtpInstanceState) -> R>(&self, f: F) -> R;
299
300    /// Takes a mutable reference to the contained state and calls `f` with it
301    fn with_mut<R, F: FnOnce(&mut PtpInstanceState) -> R>(&self, f: F) -> R;
302}
303
304impl PtpInstanceStateMutex for RefCell<PtpInstanceState> {
305    fn new(state: PtpInstanceState) -> Self {
306        RefCell::new(state)
307    }
308
309    fn with_ref<R, F: FnOnce(&PtpInstanceState) -> R>(&self, f: F) -> R {
310        f(&RefCell::borrow(self))
311    }
312
313    fn with_mut<R, F: FnOnce(&mut PtpInstanceState) -> R>(&self, f: F) -> R {
314        f(&mut RefCell::borrow_mut(self))
315    }
316}
317
318#[cfg(feature = "std")]
319impl PtpInstanceStateMutex for std::sync::RwLock<PtpInstanceState> {
320    fn new(state: PtpInstanceState) -> Self {
321        std::sync::RwLock::new(state)
322    }
323
324    fn with_ref<R, F: FnOnce(&PtpInstanceState) -> R>(&self, f: F) -> R {
325        f(&self.read().unwrap())
326    }
327
328    fn with_mut<R, F: FnOnce(&mut PtpInstanceState) -> R>(&self, f: F) -> R {
329        f(&mut self.write().unwrap())
330    }
331}
332
333#[cfg(test)]
334mod tests {
335    use super::*;
336    use crate::{
337        config::{
338            ClockAccuracy, ClockIdentity, ClockQuality, InstanceConfig, TimePropertiesDS,
339            TimeSource,
340        },
341        filters::BasicFilter,
342    };
343
344    fn create_test_instance() -> PtpInstance<BasicFilter> {
345        let config = InstanceConfig {
346            clock_identity: ClockIdentity::from_mac_address([1, 2, 3, 4, 5, 6]),
347            priority_1: 128,
348            priority_2: 128,
349            domain_number: 0,
350            slave_only: false,
351            sdo_id: Default::default(),
352            path_trace: false,
353            clock_quality: ClockQuality::default(),
354        };
355        let time_properties_ds =
356            TimePropertiesDS::new_arbitrary_time(false, false, TimeSource::InternalOscillator);
357        PtpInstance::new(config, time_properties_ds)
358    }
359
360    #[test]
361    fn test_set_clock_quality_basic() {
362        let instance = create_test_instance();
363
364        let default_ds = instance.default_ds();
365        assert_eq!(default_ds.clock_quality.clock_class, 248);
366        assert_eq!(
367            default_ds.clock_quality.clock_accuracy,
368            ClockAccuracy::Unknown
369        );
370
371        // Set custom clock quality and verify that it is applied
372        let custom_quality = ClockQuality {
373            clock_class: 6,
374            clock_accuracy: ClockAccuracy::NS1,
375            offset_scaled_log_variance: 0x8000 - (20 * 256),
376        };
377
378        instance.set_clock_quality(custom_quality);
379
380        let updated_ds = instance.default_ds();
381        assert_eq!(updated_ds.clock_quality.clock_class, 6);
382        assert_eq!(updated_ds.clock_quality.clock_accuracy, ClockAccuracy::NS1);
383        assert_eq!(
384            updated_ds.clock_quality.offset_scaled_log_variance,
385            0x8000 - (20 * 256)
386        );
387    }
388
389    #[test]
390    fn test_set_slave_only() {
391        let instance = create_test_instance();
392
393        instance.set_slave_only(false);
394        assert!(!instance.default_ds().slave_only);
395
396        instance.set_slave_only(true);
397        assert!(instance.default_ds().slave_only);
398    }
399}
statime/ptp_instance.rs

statime/
ptp_instance.rs
