tree: 22eab4c50a9c19b58a69717ce44ed1b21f9b6427 [path history] [tgz]
  1. BUILD.gn
  2. README.md
  3. meta/
  4. service.config
  5. src/
  6. test/
src/sys/time/timekeeper/README.md

Timekeeper

Overview

Timekeeper is responsible for starting and maintaining the UTC clock. For more information on the design of UTC on Fuchsia please refer to UTC architecture. To understand the observable behavior of UTC on Fuchsia please refer to UTC behavior

Timekeeper connects to the fuchsia.time.Maintenance service to acquire a writable handle to the UTC clock on launch. It launches and connects to a time source component (or components) and connects to fuchsia.time.external.PushSource to receive time synchronization information.

Timekeeper also connects to the Real Time Clock (RTC) driver using fuchsia.hardware.rtc if one is found in /dev/class/rtc, reading the RTC at initialization and updating it each time a new time sample is received from a time source.

The algorithms used in Timekeeper are documented and explained at UTC algorithms.

Design

Timekeeper is composed of the following Rust modules:

ModuleDescription
mainEntry point for the component that handles initialization and delegation to the other modules.
enumsA collection of simple enumerations that are used across the other modules and in particular are used to bridge the operational and diagnostics modules.
rtcAbstracts discovery of and interaction with the real time clock driver away from other modules.
time_sourceAbstracts the launching and interaction with time sources away from other modules. Produces a stream of time source events.
time_source_managerMaintains a functional connection to a time source by using time_source to launch and relaunch the component as needed. time_source_manager validates the time samples received from time_source and produces a stream of validated time samples.
estimatorAbstracts the details of the Kalman filter and frequency correction algorithms away from other modules. estimator maintains a best estimate of the current UTC and frequency given a sequence of valid time samples.
clock_managerMaintains a kernel clock object using time_source_manager to supply valid time samples and estimator to maintain the best estimate of UTC given these samples. clock_manager determines the most appropriate clock updates to converge the reported time with the estimated time.
diagnosticsProvides a common trait to supply timekeeping events of note to diagnostics systems and implements this trait for Cobalt and Inspect.

Development and testing

Because timekeeper is implemented in Rust, we recommend that you consult the Fuchsia Rust documentation.

timekeeper itself is included in the core product configuration, no specific fx set is needed to ensure it is included in an image.

Timekeeper is covered by both unit tests and integration tests. These are not included by default so should be added to the available packages using fx set or fx args:

  • Unit tests are at //src/sys/time/timekeeper:tests and may be executed with fx test timekeeper-tests.
  • Integration tests are at //src/sys/time/timekeeper_integration and may be executed with fx test timekeeper-integration