sdk/fidl/fuchsia.time.external/external.fidl - fuchsia - Git at Google

 // 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.
 @available(added=HEAD)
 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 and the reference clock readings
 /// at the measurement instant.
 type TimeSample = table {
     /// The UTC time sample.  The value of this instant is a value on the UTC
     /// timeline. However, the field is not type safe, as there is no UTC
     /// specific type on the zx level.
     1: utc zx.Time;
     /// The monotonic time at which the sample was most valid. Must always be
     /// provided.
     /// DEPRECATED. Use `reference` below instead.
     2: monotonic zx.Time;
     /// The standard deviation representing the error distribution of the UTC
     /// measurement. Must always be provided.
     3: standard_deviation zx.Duration;
     /// The timestamp on the reference timeline at which the sample was most
     /// valid. Must always be provided.  The reference timeline is tracking
     /// the rate of change of proper time [1].  So, for example, Fuchsia's boot
     /// timeline will generate the appropriate reference instant.
     ///
     /// [1]: https://en.wikipedia.org/wiki/Proper_time
     4: reference zx.InstantBoot;
 };

 /// 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 {};

 /// Report UTC reference adjustment.
 ///
 /// Allows components to request corrections to the reported UTC time.  Very few
 /// components should be expected to have access to this capability.
 @discoverable
 closed protocol Adjust {
     /// Requests that the callee changes its UTC time estimate.
     ///
     /// Reports the caller's desired correspondence between the boot timeline,
     /// and the UTC timeline.
     ///
     /// The caller is required to provide both reference points so that any
     /// FIDL round-trip delays do not affect the callee's interpretation of
     /// the caller's intentions.  For example, were the callee to use its own
     /// `boot_reference` value instead of a caller-provided one, long wall time
     /// delays between the caller's and the callee's sampling of `boot_reference`
     /// would introduce a skew.  While this is unlikely to happen on a device to
     /// a meaningful extent, we established that this is the correct way to
     /// transmit such information.
     ///
     /// To wit, we have observed delays in test environments. This is likely
     /// because test environments run on emulators in shared-resource
     /// settings, where unusually long delays are relatively common.
     strict ReportBootToUtcMapping(struct {
         /// A time instant on the boot timeline, for which the caller is reporting
         /// a presumed UTC reference instant.
         boot_reference zx.InstantBoot;
         /// The time instant on the UTC timeline, corresponding to `boot_reference`.
         utc_reference zx.Time;
     }) -> () error Error;
 };
	// 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.
	@available(added=HEAD)
	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 and the reference clock readings
	/// at the measurement instant.
	type TimeSample = table {
	/// The UTC time sample. The value of this instant is a value on the UTC
	/// timeline. However, the field is not type safe, as there is no UTC
	/// specific type on the zx level.
	1: utc zx.Time;
	/// The monotonic time at which the sample was most valid. Must always be
	/// provided.
	/// DEPRECATED. Use `reference` below instead.
	2: monotonic zx.Time;
	/// The standard deviation representing the error distribution of the UTC
	/// measurement. Must always be provided.
	3: standard_deviation zx.Duration;
	/// The timestamp on the reference timeline at which the sample was most
	/// valid. Must always be provided. The reference timeline is tracking
	/// the rate of change of proper time [1]. So, for example, Fuchsia's boot
	/// timeline will generate the appropriate reference instant.
	///
	/// [1]: https://en.wikipedia.org/wiki/Proper_time
	4: reference zx.InstantBoot;
	};

	/// 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 {};

	/// Report UTC reference adjustment.
	///
	/// Allows components to request corrections to the reported UTC time. Very few
	/// components should be expected to have access to this capability.
	@discoverable
	closed protocol Adjust {
	/// Requests that the callee changes its UTC time estimate.
	///
	/// Reports the caller's desired correspondence between the boot timeline,
	/// and the UTC timeline.
	///
	/// The caller is required to provide both reference points so that any
	/// FIDL round-trip delays do not affect the callee's interpretation of
	/// the caller's intentions. For example, were the callee to use its own
	/// `boot_reference` value instead of a caller-provided one, long wall time
	/// delays between the caller's and the callee's sampling of `boot_reference`
	/// would introduce a skew. While this is unlikely to happen on a device to
	/// a meaningful extent, we established that this is the correct way to
	/// transmit such information.
	///
	/// To wit, we have observed delays in test environments. This is likely
	/// because test environments run on emulators in shared-resource
	/// settings, where unusually long delays are relatively common.
	strict ReportBootToUtcMapping(struct {
	/// A time instant on the boot timeline, for which the caller is reporting
	/// a presumed UTC reference instant.
	boot_reference zx.InstantBoot;
	/// The time instant on the UTC timeline, corresponding to `boot_reference`.
	utc_reference zx.Time;
	}) -> () error Error;
	};