/*
 * Copyright (C) 2016 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package android.hardware.power@1.0;

/**
 * Constructor for the interface performs power management setup actions at
 * runtime startup, such as to set default cpufreq parameters.
 */
interface IPower {
    /**
     * setInteractive() performs power management actions upon the
     * system entering interactive state (that is, the system is awake
     * and ready for interaction, often with UI devices such as
     * display and touchscreen enabled) or non-interactive state (the
     * system appears asleep, display usually turned off). The
     * non-interactive state may be entered after a period of
     * inactivity in order to conserve battery power during
     * such inactive periods.
     *
     * Typical actions are to turn on or off devices and adjust
     * cpufreq parameters. This function may also call the
     * appropriate interfaces to allow the kernel to suspend the
     * system to low-power sleep state when entering non-interactive
     * state, and to disallow low-power suspend when the system is in
     * interactive state. When low-power suspend state is allowed, the
     * kernel may suspend the system whenever no wakelocks are held.
     *
     * For example,
     * This function can be called to enter non-interactive state after
     * turning off the screen (if present) and called to enter
     * interactive state prior to turning on the screen.
     *
     * @param interactive is true when the system is transitioning to an
     * interactive state and false when transitioning to a
     * non-interactive state.
     */
    setInteractive(bool interactive);

    /**
     * powerHint() is called to pass hints on power requirements which
     * may result in adjustment of power/performance parameters of the
     * cpufreq governor and other controls.
     *
     * A particular platform may choose to ignore any hint.
     *
     * @param hint PowerHint which is passed
     * @param data contains additional information about the hint
     * and is described along with the comments for each of the hints.
     */
    powerHint(PowerHint hint, int32_t data);

    /**
     * setFeature() is called to turn on or off a particular feature
     * depending on the state parameter.
     *
     * @param feature Feature which needs to be set
     * @param activate true/false to enable/disable the feature
     */
    setFeature(Feature feature, bool activate);

    /**
     * Platform-level sleep state stats:
     * Report cumulative info on the statistics on platform-level sleep states
     * since boot.
     *
     * Higher the index in the returned <states> vector deeper the state is
     * i.e. lesser steady-state power is consumed by the platform to be
     * resident in that state.
     *
     * @return states of power states the device supports
     * @return retval SUCCESS on success or FILESYSTEM_ERROR on filesystem
     * nodes access error.
     */
    getPlatformLowPowerStats()
            generates (vec<PowerStatePlatformSleepState> states, Status retval);
};