Google is committed to advancing racial equity for Black communities. See how.

fuchsia.time.external

Defines the protocols used to sample UTC time using time synchronization protocols such as NTP.

New time protocols may be added to the system by implementing the server side of one or more of these protocols. The core timekeeper system acts as the client and uses produced samples to update the system time.

Implementing PushSource is preferred, as it allows the server to decide when to produce samples. The server has knowledge of the particular protocol it understands and is therefore better informed when to produce a timesample.

UTC time is distributed by the system. Clients that need to obtain UTC time should use the standard libraries provided by their runtime.

PROTOCOLS

PullSource

Defined in fuchsia.time.external/external.fidl

A protocol for time sources that produce time samples on demand.

NextPossibleSampleTime

Returns the monotonic time at which the PullSource is willing to produce another sample. If the PullSource is not rate limited it may return the current monotonic time or earlier.

Request

NameType

Response

NameType
next_possible_time zx/time

Sample

Produce a new time sample.

Returns a RATE_LIMITED error if the client should wait before requesting another sample. For example, this can occur if a server requests that the source make less frequent requests. In this case, the client should call NextSampleTime to retrieve the next time it may request a sample.

Request

NameType

Response

NameType
result PullSource_Sample_Result

UpdateDeviceProperties

Notifies the time source of changes to global properties of the device that it may use to increase accuracy of time measurements.

Request

NameType
properties Properties

PushSource

Defined in fuchsia.time.external/external.fidl

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.

UpdateDeviceProperties

Notifies the time source of changes to global properties of the device that it may use to increase accuracy of time measurements.

Request

NameType
properties Properties

WatchSample

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 and 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.

Request

NameType

Response

NameType
sample TimeSample

WatchStatus

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.

Request

NameType

Response

NameType
status Status

TimeSource

Defined in fuchsia.time.external/external.fidl

A protocol which defines common methods for all time sources. Should not be implemented directly.

UpdateDeviceProperties

Notifies the time source of changes to global properties of the device that it may use to increase accuracy of time measurements.

Request

NameType
properties Properties

STRUCTS

PullSource_Sample_Response

Defined in fuchsia.time.external/external.fidl

NameTypeDescriptionDefault
sample TimeSample No default

ENUMS

Error

Type: uint32

Defined in fuchsia.time.external/external.fidl

Enum of reasons why producing a time sample failed.

NameValueDescription
UNKNOWN 1

An error occurred that cannot be classified as one of the more specific error statuses.

INTERNAL 2

An internal error occurred. This usually indicates a bug in the component implementation.

RESOURCE 3

A local resource error occurred such as IO, FIDL, or memory allocation failure.

NETWORK 4

A network error occurred.

HARDWARE 5

Some hardware that the time source depends on failed.

PROTOCOL 6

A retriable error specific to the implemented time protocol occurred, such as a malformed response from a remote server.

PROTOCOL_UNRECOVERABLE 7

Sampling failed in a nonretriable way. Examples include failed authentication, or a missing configuration.

RATE_LIMITED 8

The request was made too soon and the client should wait before making another request.

Status

Type: uint32

Defined in fuchsia.time.external/external.fidl

Enum of states a PullSource may be in.

NameValueDescription
INITIALIZING 0

The time source is performing setup steps or waiting for dependencies such as network to become available.

OK 1

The time source is healthy and expects to produce time samples.

UNKNOWN_UNHEALTHY 2

The time source does not expect to produce time samples for reasons that cannot be classified as one of the more specific statuses.

NETWORK 3

The time source is unable to produce time samples due to network availability issues.

HARDWARE 4

The time source is unable to produce time samples due to hardware issues.

PROTOCOL 5

The time source is unable to produce time samples due to errors specific to the implemented time protocol.

RESOURCE 6

The time source is unable to produce time samples due to local resource errors such as IO, FIDL, or memory allocation.

TABLES

Properties

Defined in fuchsia.time.external/external.fidl

Device global properties a time source may use to help it sample time.

OrdinalNameTypeDescription

TimeSample

Defined in fuchsia.time.external/external.fidl

A correspondence pair that describes a UTC time and the monotonic time at which the time was measured.

OrdinalNameTypeDescription
1 utc zx/time

The UTC time sample. Must always be provided.

2 monotonic zx/time

The monotonic time at which the sample was most valid. Must always be provided.

UNIONS

PullSource_Sample_Result

Defined in fuchsia.time.external/external.fidl

NameTypeDescription
response PullSource_Sample_Response
err Error