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
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
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
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
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
| Name | Type |
|---|---|
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
| Name | Type |
|---|---|
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
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
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
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
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
| Name | Type |
|---|---|
properties |
Properties
|
STRUCTS
PullSource_Sample_Response
Defined in fuchsia.time.external/external.fidl
| Name | Type | Description | Default |
|---|---|---|---|
sample |
TimeSample
|
No default |
ENUMS
Error
Type: uint32
Defined in fuchsia.time.external/external.fidl
Enum of reasons why producing a time sample failed.
| Name | Value | Description |
|---|---|---|
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.
| Name | Value | Description |
|---|---|---|
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.
| Ordinal | Name | Type | Description |
|---|
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.
| Ordinal | Name | Type | Description |
|---|---|---|---|
| 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. |
| 3 | standard_deviation |
zx/duration
|
The standard deviation representing the error distribution of the UTC measurement. Must always be provided. |
UNIONS
PullSource_Sample_Result
Defined in fuchsia.time.external/external.fidl
| Name | Type | Description |
|---|---|---|
response |
PullSource_Sample_Response
|
|
err |
Error
|