| // 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; |
| |
| // TODO(ravoorir): When the system power states are properly defined, |
| // remove the suspend flags. For now, treat each suspend flag as a system |
| // power state. |
| 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; |
| }; |
| 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(fxbug.dev/52274): 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 fxbug.dev/58348): |
| /// 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 |
| protocol Admin { |
| /// Asks the device to enter a fully on state. |
| PowerFullyOn() -> (struct {}) error zx.status; |
| |
| /// Asks the device to reboot. |
| Reboot(struct { |
| reason RebootReason; |
| }) -> (struct {}) error zx.status; |
| |
| /// Asks the device to reboot into the bootloader. |
| RebootToBootloader() -> (struct {}) error zx.status; |
| |
| /// Asks the device to reboot into the recovery partition. |
| RebootToRecovery() -> (struct {}) error zx.status; |
| |
| /// Asks all devices to enter a powered off state. |
| Poweroff() -> (struct {}) 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. |
| Mexec(resource struct { |
| kernel_zbi zx.handle:VMO; |
| data_zbi zx.handle:VMO; |
| }) -> (struct {}) error zx.status; |
| |
| SuspendToRam() -> (struct {}) error zx.status; |
| }; |
| |
| // Component Framework's orderly shutdown is tracked with bug 51034. |
| /// 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 |
| 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. |
| Register(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. |
| protocol RebootMethodsWatcher { |
| OnReboot(struct { |
| reason RebootReason; |
| }) -> (); |
| }; |