Crate statime

source ·
Expand description

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:

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:

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

Modules§

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

Structs§

  • 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.
  • A PTP node.
  • The inner state of a PtpInstance
  • A wrapper for stateful statime::Clock implementations to make them behave like e.g. statime_linux::LinuxClock - clones share state with each other

Traits§