blob: 866f1f099add851f60f9de7ee11df9f8f6b19444 [file] [log] [blame]
// Copyright 2022 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.
@available(added=7)
library fuchsia.power.systemmode;
using fuchsia.power.clientlevel;
/// Enumerates the supported system power modes.
///
/// Power modes in the system are non-exclusive -- more than one could be active
/// at any given time. They typically define a system-wide low-power state or
/// power goal, like "battery-saver mode". See the
/// [README.md](/src/power/power-manager/system_power_mode_config/README.md) for
/// more details.
///
/// Note when adding a new variant: update [`MAX_MODE_MATCHES_PER_CLIENT`] to be
/// equal to the number of `SystemMode` variants to support the "worst case"
/// client configuration.
// This is an empty placeholder for now, but will eventually grow to include a
// variant for each of the supported system power modes.
type SystemMode = flexible enum {};
/// Possible error values returned by [`Requester.Request`].
type ModeRequestError = flexible enum {
/// A generic error has occurred.
GENERIC = 1;
};
/// A protocol that can be used to request a change to the currently active
/// system power modes.
@discoverable
protocol Requester {
/// Requests to set or clear a system power mode.
///
/// The call returns immediately after the request has been received,
/// validated, and accepted. Actual system changes to be applied as a result
/// of this request will occur after the call has returned. Therefore, any
/// errors that occur while updating clients according to the new system
/// power mode are not propagated back to the caller. Instead, client
/// updates are applied on a "best effort" basis.
///
/// An error returned by this method means the request itself is not valid
/// and was rejected. Details of the specific rejection reason are reflected
/// by the error value. In the event of an error, the channel will remain
/// open.
///
/// A client can use this method to set or clear system power mode variants
/// independently. For example:
///
/// // battery is below the "low" threshold
/// Request(LOW_BATTERY, true);
///
/// // device is now plugged into the wall
/// Request(ON_AC_POWER, true);
///
/// // battery is now above the "low" threshold
/// Request(LOW_BATTERY, false);
///
/// + `mode` is the `SystemMode` to request to be set or cleared
/// + `set` should be true to request to set `mode`, or false to clear it
/// * error a [`ModeRequestError`] value indicating why the request was
/// rejected.
Request(struct {
mode SystemMode;
set bool;
}) -> (struct {}) error ModeRequestError;
};
/// Maximum number of [`ModeMatch`] entries that a [`ClientConfig`] may contain.
///
/// This value should be set equal to the number of [`SystemMode`] variants, as
/// that is the number of entries required to support the "worst case" client
/// configuration ("worst case" means a configuration where a mode match entry
/// is needed for each of the supported power modes).
const MAX_MODE_MATCHES_PER_CLIENT uint32 = 0;
/// Defines the power configuration for a [`ClientType`].
///
/// For a client connected with a given [`ClientType`], the PowerManager will
/// use the configured [`ClientConfig`] for that [`ClientType`] to choose the
/// appropriate power level based on the currently active system power modes.
/// The power level selection process is as follows for a given [`ClientType`]:
/// 1. Iterate through the [`ClientConfig.mode_matches`] entries. If the
/// `mode` value specified by an entry is contained in the currently active
/// system power modes, then the corresponding `power_level` from that entry
/// will be selected as this client’s current power level, and iteration for
/// this client will stop.
/// 2. If no entry in `mode_matches` was matched, then `default_level` will be
/// selected as the client's current power level.
type ClientConfig = struct {
mode_matches vector<ModeMatch>:MAX_MODE_MATCHES_PER_CLIENT;
default_level uint64;
};
/// Defines the mode-based match criterion for selecting a power level.
///
/// The power configuration for a given [`ClientType`] is made up of a
/// collection of these `ModeMatch` entries. If an entry's specified `mode` is
/// contained in the currently active system power modes, then its `power_level`
/// will be selected as the client's power level.
type ModeMatch = struct {
mode SystemMode;
power_level uint64;
};
/// A protocol that can be used to update the power configuration for a given
/// [`ClientType`].
@discoverable
protocol ClientConfigurator {
/// Gets the power configuration for the given [`ClientType`].
///
/// If there is no power configuration for `client_type` then the returned
/// value will be absent.
///
/// + `client_type` specifies which [`ClientType`] [`ClientConfig`] to get
/// - `config` is the returned client-specific configuration, or an absent
/// value if `client_type` does not have an existing configuration
Get(struct {
client_type fuchsia.power.clientlevel.ClientType;
}) -> (struct {
config box<ClientConfig>;
});
/// Sets the power configuration for the given [`ClientType`].
///
/// This method should be used in tandem with [`GetConfig`] in order to
/// update the existing power configuration for a given [`ClientType`]
/// without fully overwriting it.
///
/// When the power configuration for a given [`ClientType`] is changed, the
/// Power Manager will reevaluate current power level of that [`ClientType`]
/// according to the new configuration. This reevaluation may result in a
/// new power level being sent to the connected client.
///
/// The call returns immediately after the new config has been received and
/// validated. Actual system changes to be applied as a result of changing a
/// client's configuration will occur after the call has returned.
/// Therefore, any errors that occur while updating clients according to the
/// new system power mode are not propagated back to the caller. Instead,
/// client updates are applied on a "best effort" basis.
///
/// If the provided `config` is not valid, then no changes will be applied
/// and the channel will be closed. Validation will fail if a given
/// `SystemMode` is repeated across multiple `mode_match` entries contained
/// by the `ClientConfig`.
///
/// + `client_type` specifies which [`ClientType`]'s [`ClientConfig`] to set
/// + `config` is the [`ClientConfig`] that will be set for [`client_type`]
Set(struct {
client_type fuchsia.power.clientlevel.ClientType;
config ClientConfig;
}) -> ();
};