// Copyright 2019 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.
library fuchsia.hardware.power.statecontrol;

using zx;

@available(removed=11)
type SystemPowerState = strict enum : uint8 {
    FULLY_ON = 1;
    REBOOT = 2;
    REBOOT_BOOTLOADER = 3;
    REBOOT_RECOVERY = 4;
    POWEROFF = 5;
    MEXEC = 6;
    SUSPEND_RAM = 7;
    REBOOT_KERNEL_INITIATED = 8;
};

@available(removed=11)
const MAX_SYSTEM_POWER_STATES uint32 = 8;

/// The maxium number of seconds the server will wait for responses from all RebootMethodsWatchers
/// before changing the system power state.
// TODO(https://fxbug.dev/42129558): Track how long it takes to persist the reboot reason and adjust this value.
const MAX_REBOOT_WATCHER_RESPONSE_TIME_SECONDS uint32 = 5;

/// Provides methods to request that the system be transitioned into a supported power state.
///
/// Note (see https://fxbug.dev/42136295):
/// These methods do not return until after the state transition has been completed. In most cases
/// (e.g. Reboot), a successful transition means that the caller does not actually observe the
/// completion because the system will be rebooted before the call is completed. The implication is
/// that using a synchronous FIDL client with these methods will result in a blocked thread for the
/// duration of the call, or even for the remainder of the component's life (in the case of Reboot).
/// Therefore, if a synchronous FIDL client is to be used with this protocol then care should be
/// taken to avoid handling any shutdown-induced callbacks on the same thread that was used to
/// initiate the transition. Example callbacks include [`fuchsia.process.lifecycle/Lifecycle.Stop`]
/// and [`fuchsia.hardware.power.statecontrol/RebootMethodsWatcher.OnReboot`].
/// Alternatively, the caller could choose to use an asynchronous FIDL client with this protocol to
/// avoid blocking their calling thread.
@discoverable(server="platform")
closed protocol Admin {
    /// Asks the device to enter a fully on state.
    strict PowerFullyOn() -> () error zx.Status;

    /// Asks the device to reboot.
    strict Reboot(struct {
        reason RebootReason;
    }) -> () error zx.Status;

    /// Asks the device to reboot into the bootloader.
    strict RebootToBootloader() -> () error zx.Status;

    /// Asks the device to reboot into the recovery partition.
    strict RebootToRecovery() -> () error zx.Status;

    /// Asks all devices to enter a powered off state.
    strict Poweroff() -> () error zx.Status;

    /// Performs a kernel mexec.
    ///
    /// It is expected that the ZBI items specified by
    /// `zx_system_mexec_payload_get()` have not yet been appended to the
    /// provided data ZBI.
    strict Mexec(resource struct {
        kernel_zbi zx.Handle:VMO;
        data_zbi zx.Handle:VMO;
    }) -> () error zx.Status;

    /// Asks the device to enter the suspend to RAM (S3) power state. Currently only supported on
    /// x64. If a system state transition is already in progress then ZX_ERR_ALREADY_EXISTS is
    /// returned. If the device fails to reach the suspend power state then ZX_ERR_INTERNAL is
    /// returned. If the device successfully suspends, ZX_OK is returned when the device resumes.
    strict SuspendToRam() -> () error zx.Status;
};

/// Allows components to register a callback that will be executed when a Reboot
/// method is called. The main purpose of this protocol is to be able to track
/// reboot reasons. Consider relying on Component Framework's orderly shutdown
/// if you're looking at using this protocol.
@discoverable(server="platform")
closed protocol RebootMethodsWatcherRegister {
    /// Register a watcher to be notified when a Reboot method is called. The
    /// Register channel will be used at most once to notify the watcher of an
    /// impending reboot and allow it the chance to respond.
    ///
    /// Watchers can unregister by closing the underlying channel.
    // TODO(https://fxbug.dev/42061712): Remove this method after all clients have been
    // moved to `RegisterWithAck`. After removal, consider renaming
    // `RegisterWithAck` back to `Register`.
    @available(deprecated=HEAD)
    strict Register(resource struct {
        watcher client_end:RebootMethodsWatcher;
    });

    /// Registers a watcher to be notified when a Reboot method is called.
    ///
    /// Once the watcher has been successfully registered with the server, then
    /// the request will be completed and the RebootMethodsWatcherRegister
    /// channel will be left open (though a client is free to close it at this
    /// time).
    ///
    /// If there is an error in registering the watcher, then the
    /// RebootMethodsWatcherRegister channel will be closed without completing
    /// the request.
    ///
    /// The provided `watcher` channel will be used at most once to notify the
    /// watcher of an impending reboot and allow it the chance to respond.
    ///
    /// Watchers can unregister by closing their `RebootMethodsWatcher` channel.
    @available(added=HEAD)
    strict RegisterWithAck(resource struct {
        watcher client_end:RebootMethodsWatcher;
    }) -> ();
};

/// Allows components to be notified when Reboot related methods are called.
/// Watchers will be given 'MAX_REBOOT_WATCHER_RESPONSE_TIME_SECONDS' to return
/// before the system power state is changed. The channel will be used once to
/// send a notification to the watcher. Once the watcher responds or the timeout
/// expires, the channel will be closed by the client of RebootMethodsWatcher.
closed protocol RebootMethodsWatcher {
    strict OnReboot(struct {
        reason RebootReason;
    }) -> ();
};