Crate statime

Statime is a library providing an implementation of PTP version 2.1 (IEEE1588-2019). It provides all the building blocks to setup PTP ordinary and boundary clocks.

statime is designed to be able to work with many different underlying platforms, including embedded targets. This does mean that it cannot use the standard library and platform specific libraries to interact with the system clock and to access the network. That needs to be provided by the user of the library.

On modern linux kernels, the statime-linux crate provides ready to use implementations of these interfaces. For other platforms the user will need to implement these themselves.

The statime-stm32 crate gives an example of how to use statime on an embedded target.

Implementing a PTP clock with statime

Implementing a clock device requires three parts. The PtpInstance handles the logic for the Best Master Clock Algorithm (BMCA). A Port handles the logic for a single network interface of the device. And a Clock per Port that is a struct provided by the user that can read and control a clock device that is associated with a Port.

Setup

The first step for a new implementation is to gather the configurations needed, these are:

• A InstanceConfig that describes the device
• A TimePropertiesDS that describes the timescale that is used
• A PortConfig per Port to configure its behavior

The PtpInstance can then be created with PtpInstance::new, providing InstanceConfig and TimePropertiesDS. From that instance Ports can be created using PtpInstance::add_port proviging it PortConfig, its Clock and a Filter.

Running

The PtpInstance expects to execute the BMCA periodically. For this the user must provide a slice containing all ports in the InBmca state.

Ports start out in the InBmca state and can be turned into Running mode by calling Port::end_bmca. And for running the BMCA Port::start_bmca turns it back into the InBmca state.

While Running a Port expects the user to keep track of a few different timers as well as two network sockets. The Port is informed about any events via one of the Port::handle_* methods. Actions the Port expects to be performed are returned in the form of PortActions.

Testing a new implementation

A basic option for testing is to run statime-linux on your developer machine and connecting your new implementation to a dedicated network port. Now both the time synchronization can be observed e.g. by using a pulse-per-second (PPS) pin. Additionally the protocol excahnge can be observed with a tool like Wireshark.

Cargo Features

This crate exposes two features std and fuzz. std enables a dependency on the Rust standard library providing:

• std::error::Error implementations for error types
• Implementations of the config::AcceptableMasterList trait on types in std
• Usage of methods on f32 and f64 directly from std instead of [libm]

The fuzz feature exposes internal types for fuzzing implementations in the statime::fuzz module.

Modules

• config
  Configuration structures
• filters
  Definitions and implementations for the abstracted measurement filters
• observability
  Serializable implementations of datastructures to be used for observability
• port
  Abstraction of a network Port of a device.
• time
  Types that describe points in time (Time), and durations between two instants (Duration, Interval)

Structs

• OverlayClock
  An overlay over other, read-only clock, frequency-locked to it. In other words, a virtual clock which can be tuned in software without affecting the underlying system or hardware clock.
• PtpInstance
  A PTP node.
• PtpInstanceState
  The inner state of a PtpInstance
• SharedClock
  A wrapper for stateful statime::Clock implementations to make them behave like e.g. statime_linux::LinuxClock - clones share state with each other

Traits

• Clock
  Clock manipulation and querying interface
• PtpInstanceStateMutex
  A mutex over a PtpInstanceState