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

/// Provides access to a UTC clock for the purposes of
/// keeping it up-to-date with external time sources.
///
/// This is a sensitive capability as it allows the process
/// that has access to it to change the UTC clock and affect
/// certificate checking decisions, for example.
library fuchsia.time;

using zx;

/// Provides access to a UTC clock for the purposes of
/// keeping it up-to-date with external time sources.
///
/// The client does not own the UTC clock, but is given
/// a lease in order to keep the time synchronized.
@discoverable
closed protocol Maintenance {
    /// Retrieve a UTC clock handle with write rights.
    strict GetWritableUtcClock() -> (resource struct {
        utc_clock zx.Handle:CLOCK;
    });
};

/// A user signal that indicates that the UTC clock has been synchronized with
/// an external time source.
///
/// We assume that the external time source has a better estimate
/// of the actual "wall clock" UTC time than our device.
///
/// You may wait on this signal if you want your code to sleep until the UTC
/// clock gets synchronized with an external time source.
///
/// When this signal is active, the clock was synchronized with an
/// external source reasonably recently. The error bounds represent the system's
/// best estimate of wall clock UTC time.
///
/// When this signal is inactive, the clock was last updated from a source
/// that is not external or was never updated at all. This can occur after a
/// reboot, or a resume. The UTC clock may have been set from the
/// real time clock (RTC), but we may not know if RTC matches wall clock.
///
/// If you need finer-grained info on the UTC clock error, you must
/// check the error bounds via [`zx_clock_get_details`][det].
///
/// This signal being active does *not* establish clock trust, and should not
/// be used as such. Also, we can not guarantee that the signal
/// will stay active after a notification. Clients should not
/// assume that the clock remains in a certain state after a signal.
///
/// The value is an alias for `ZX_USER_SIGNAL_0`.
///
/// [det]: https://fuchsia.dev/fuchsia-src/reference/kernel_objects/clock#error-bound
const SIGNAL_UTC_CLOCK_SYNCHRONIZED uint32 = 0x01000000;

/// Signaled on the UTC clock handle when the UTC clock is determined to have
/// reached logging quality.
///
/// Logging quality timestamps are low-confidence, but presumed good enough for
/// debug logging.
///
/// The value is an alias for `ZX_USER_SIGNAL_1`
const SIGNAL_UTC_CLOCK_LOGGING_QUALITY uint32 = 0x02000000;