sdk/fidl/fuchsia.time.external/external.fidl

// Copyright 2020 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
//
/// Defines the protocols used to sample UTC time using time synchronization
/// protocols such as NTP or Roughtime.
///
/// New time protocols may be added to the system by implementing the server
/// side of one or more of these protocols. The Timekeeper component acts as
/// the client and uses produced samples to update the system time.
///
/// Implementing PushSource lets the server decide when to produce samples and
/// implies that the time source will stay running between samples. Implementing
/// PullSource places Timekeeper in control of when to produce samples and lets
/// the time source be stopped between samples.
///
/// UTC time is distributed by the system. Clients that need to obtain UTC time
/// should use the standard libraries provided by their runtime.
library fuchsia.time.external;
using zx;

/// A protocol which defines common methods for all time sources. Should not be
/// implemented directly.
closed protocol TimeSource {
    /// Notifies the time source of changes to global properties of the device
    /// that it may use to increase accuracy of time measurements.
    strict UpdateDeviceProperties(struct {
        properties Properties;
    });
};

/// A protocol for time sources that produce time samples on demand.
@discoverable
closed protocol PullSource {
    compose TimeSource;
    /// Produce a new time sample.
    ///
    /// The server may consider the supplied urgency and will potentially
    /// produce a sample more quickly but with lower accuracy when a request
    /// is marked urgent.
    ///
    /// The server will return an error for permanent errors but will block
    /// on conditions that are not known to be permanent (e.g. network not
    /// connected).
    ///
    /// The server will return a RATE_LIMITED error if the client should wait
    /// before requesting another sample. In this case the client may call
    /// `NextPossibleSampleTime` to determine when the time source will be
    /// willing to produce another sample.
    strict Sample(struct {
        urgency Urgency;
    }) -> (struct {
        sample TimeSample;
    }) error Error;

    /// Returns the monotonic time at which the PullSource is willing to produce
    /// another sample. If the PullSource is not rate limited it will return a
    /// time less than or equal to current monotonic time.
    strict NextPossibleSampleTime() -> (struct {
        next_possible_time zx.Time;
    });
};

/// A protocol for time sources that produce time samples on a schedule that it
/// dictates. A PushSource does not report errors to clients as it is
/// responsible for handling them internally. Instead, a PushSource reports a
/// general health indication through the `WatchHealth` method to reflect
/// whether or not it expects to successfully produce time samples.
@discoverable
closed protocol PushSource {
    compose TimeSource;
    /// Watch for new time samples from the time source. This method is a
    /// hanging get and returns the latest time sample if one is available and
    /// has not already been returned to the client. If no such sample is
    /// available, the method will hang until one is produced and return it
    /// then.
    ///
    /// Note that it is entirely at the discretion of the PushSource
    /// implementation when to produce a sample; a call to WatchSample does
    /// not necessarily trigger sample collection.
    ///
    /// In the case a client sends a second WatchSample request while another
    /// request is active, the channel is closed with a ZX_ERR_BAD_STATE
    /// epitaph.
    strict WatchSample() -> (struct {
        sample TimeSample;
    });

    /// Watch for changes in the status of the time source.
    ///
    /// This method is a hanging get that returns when the status changes from
    /// the last status reported to the client.
    ///
    /// In the case a client sends a second WatchStatus request while another
    /// request is active, the channel is closed with a ZX_ERR_BAD_STATE
    /// epitaph.
    strict WatchStatus() -> (struct {
        status Status;
    });
};

/// A correspondence pair that describes a UTC time and the monotonic time at
/// which the time was measured.
type TimeSample = table {
    /// The UTC time sample. Must always be provided.
    1: utc zx.Time;
    /// The monotonic time at which the sample was most valid. Must always be
    /// provided.
    2: monotonic zx.Time;
    /// The standard deviation representing the error distribution of the UTC
    /// measurement. Must always be provided.
    3: standard_deviation zx.Duration;
};

/// Enum of urgencies used when requesting a sample from a PullSource. The time
/// source may use this information to balance the need to produce a response
/// quickly against the desire to produce an accurate sample.
type Urgency = flexible enum {
    /// The client is blocked until the requested sample is received. For
    /// example, the sample may be required to start a clock for the first time.
    HIGH = 1;
    /// The client will receive a significant benefit from the requested sample.
    /// For example, the sample may be required to set the error bound on a
    /// clock that is running with unknown accuracy.
    MEDIUM = 2;
    /// The client can wait as long as needed to receive a high-quality sample.
    /// For example, the sample may be required for a periodic update on a clock
    /// that is already running within an acceptable error bound.
    LOW = 3;
};

/// Enum of states a PushSource may be in.
type Status = strict enum {
    /// The time source is performing setup steps or waiting for dependencies
    /// such as network to become available.
    INITIALIZING = 0;
    /// The time source is healthy and expects to produce time samples.
    OK = 1;
    /// The time source does not expect to produce time samples for reasons that
    /// cannot be classified as one of the more specific statuses.
    UNKNOWN_UNHEALTHY = 2;
    /// The time source is unable to produce time samples due to network
    /// availability issues.
    NETWORK = 3;
    /// The time source is unable to produce time samples due to hardware
    /// issues.
    HARDWARE = 4;
    /// The time source is unable to produce time samples due to errors specific
    /// to the implemented time protocol.
    PROTOCOL = 5;
    /// The time source is unable to produce time samples due to local resource
    /// errors such as IO, FIDL, or memory allocation.
    RESOURCE = 6;
};

/// Enum of reasons why producing a time sample failed.
type Error = strict enum {
    /// An error occurred that cannot be classified as one of the more specific
    /// error statuses.
    UNKNOWN = 1;
    /// An internal error occurred. This usually indicates a bug in the
    /// component implementation.
    INTERNAL = 2;
    /// A local resource error occurred such as IO, FIDL, or memory allocation
    /// failure.
    RESOURCE = 3;
    /// A network error occurred.
    NETWORK = 4;
    /// Some hardware that the time source depends on failed.
    HARDWARE = 5;
    /// A retriable error specific to the implemented time protocol occurred,
    /// such as a malformed response from a remote server.
    PROTOCOL = 6;
    /// Sampling failed in a nonretriable way. Examples include failed
    /// authentication, or a missing configuration.
    PROTOCOL_UNRECOVERABLE = 7;
    /// The request was made too soon and the client should wait before making
    /// another request.
    RATE_LIMITED = 8;
};

/// Device global properties a time source may use to help it sample time.
type Properties = table {};