sdk/fidl/fuchsia.time.test/rtc.fidl

// Copyright 2024 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 test-only access to the Timekeeper subsystem.
///
/// See the [Rtc] protocol below for runtime configuration of the Real Time
/// Clock (RTC) access, on devices where an RTC is available.
library fuchsia.time.test;

/// The error type returned from the methods of the [RTC] protocol.
type Error = flexible enum : int32 {
    /// Something unspecified went wrong. Check the Timekeeper component logs
    /// for possible clues.
    ///
    /// If more specific error messages are needed, extend the [Error] enum.
    INTERNAL = 1;
};

/// Connect to the RTC protocol to send messages to Timekeeper instructing it
/// to modify its default behavior for testing purposes.
///
/// On devices that do not have a real time clock, this protocol is not useful.
@discoverable
closed protocol Rtc {
    /// Call [PersistentDisable] to instruct Timekeeper not to update the RTC with
    /// the latest UTC clock estimate. Once a reply is received, the Timekeeper
    /// will not update the RTC.
    ///
    /// This is useful in tests that exercise the RTC and must therefore write
    /// to it exclusively, possibly entering a race with Timekeeper's own
    /// RTC updates.
    ///
    /// NOTE: The setting persists across reboots, due to the testing
    /// persistence requirements. Implementations should have a way to
    /// limit the number of reboots for which this setting takes effect. This
    /// is to avoid a lasting behavior change resulting from problems in the
    /// test fixture.
    strict PersistentDisable() -> () error Error;

    /// Undoes the effects of [PersistentDisable].
    ///
    /// The test fixture should always attempt to call this method, and have it
    /// succeed. See also the `NOTE` section on [PersistentDisable].
    strict PersistentEnable() -> () error Error;
};