1c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor/*
2c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor * Copyright (C) 2012 The Android Open Source Project
3c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor *
4c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor * Licensed under the Apache License, Version 2.0 (the "License");
5c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor * you may not use this file except in compliance with the License.
6c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor * You may obtain a copy of the License at
7c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor *
8c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor *      http://www.apache.org/licenses/LICENSE-2.0
9c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor *
10c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor * Unless required by applicable law or agreed to in writing, software
11c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor * distributed under the License is distributed on an "AS IS" BASIS,
12c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor * See the License for the specific language governing permissions and
14c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor * limitations under the License.
15c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor */
16c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor
17c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor#ifndef ANDROID_INCLUDE_HARDWARE_POWER_H
18c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor#define ANDROID_INCLUDE_HARDWARE_POWER_H
19c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor
20c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor#include <stdint.h>
21c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor#include <sys/cdefs.h>
22c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor#include <sys/types.h>
23c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor
24c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor#include <hardware/hardware.h>
25c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor
26c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor__BEGIN_DECLS
27c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor
285cb1de89a905dd13c858779d73721bbc36cd4be1Mathias Agopian#define POWER_MODULE_API_VERSION_0_1  HARDWARE_MODULE_API_VERSION(0, 1)
295cb1de89a905dd13c858779d73721bbc36cd4be1Mathias Agopian#define POWER_MODULE_API_VERSION_0_2  HARDWARE_MODULE_API_VERSION(0, 2)
305cb1de89a905dd13c858779d73721bbc36cd4be1Mathias Agopian
315cb1de89a905dd13c858779d73721bbc36cd4be1Mathias Agopian
32c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor/**
33c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor * The id of this module
34c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor */
35c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor#define POWER_HARDWARE_MODULE_ID "power"
36c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor
372f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor/*
382f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor * Power hint identifiers passed to (*powerHint)
392f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor */
402f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor
412f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynortypedef enum {
422f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor    POWER_HINT_VSYNC = 0x00000001,
43bcdb4cd34b9c2a4a3ccebf0048137892e5586fe8Todd Poynor    POWER_HINT_INTERACTION = 0x00000002,
442f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor} power_hint_t;
452f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor
46c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor/**
47c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
48c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor * and the fields of this data structure must begin with hw_module_t
49c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor * followed by module specific information.
50c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor */
51c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynortypedef struct power_module {
52c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor    struct hw_module_t common;
53c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor
54c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor    /*
55c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     * (*init)() performs power management setup actions at runtime
562f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor     * startup, such as to set default cpufreq parameters.  This is
572f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor     * called only by the Power HAL instance loaded by
582f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor     * PowerManagerService.
59c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     */
60c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor    void (*init)(struct power_module *module);
61c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor
62c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor    /*
63c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     * (*setInteractive)() performs power management actions upon the
64c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     * system entering interactive state (that is, the system is awake
65c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     * and ready for interaction, often with UI devices such as
66c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     * display and touchscreen enabled) or non-interactive state (the
67c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     * system appears asleep, display usually turned off).  The
68c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     * non-interactive state is usually entered after a period of
69c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     * inactivity, in order to conserve battery power during
70c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     * such inactive periods.
71c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     *
72c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     * Typical actions are to turn on or off devices and adjust
73c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     * cpufreq parameters.  This function may also call the
74c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     * appropriate interfaces to allow the kernel to suspend the
75c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     * system to low-power sleep state when entering non-interactive
76c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     * state, and to disallow low-power suspend when the system is in
77c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     * interactive state.  When low-power suspend state is allowed, the
78c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     * kernel may suspend the system whenever no wakelocks are held.
79c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     *
80c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     * on is non-zero when the system is transitioning to an
81c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     * interactive / awake state, and zero when transitioning to a
82c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     * non-interactive / asleep state.
83c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     *
84c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     * This function is called to enter non-interactive state after
85c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     * turning off the screen (if present), and called to enter
86c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     * interactive state prior to turning on the screen.
87c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor     */
88c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor    void (*setInteractive)(struct power_module *module, int on);
892f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor
902f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor    /*
912f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor     * (*powerHint) is called to pass hints on power requirements, which
922f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor     * may result in adjustment of power/performance parameters of the
932f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor     * cpufreq governor and other controls.  The possible hints are:
942f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor     *
952f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor     * POWER_HINT_VSYNC
962f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor     *
972f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor     *     Foreground app has started or stopped requesting a VSYNC pulse
982f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor     *     from SurfaceFlinger.  If the app has started requesting VSYNC
992f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor     *     then CPU and GPU load is expected soon, and it may be appropriate
1002f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor     *     to raise speeds of CPU, memory bus, etc.  The data parameter is
1012f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor     *     non-zero to indicate VSYNC pulse is now requested, or zero for
1022f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor     *     VSYNC pulse no longer requested.
1032f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor     *
104bcdb4cd34b9c2a4a3ccebf0048137892e5586fe8Todd Poynor     * POWER_HINT_INTERACTION
105bcdb4cd34b9c2a4a3ccebf0048137892e5586fe8Todd Poynor     *
106bcdb4cd34b9c2a4a3ccebf0048137892e5586fe8Todd Poynor     *     User is interacting with the device, for example, touchscreen
107bcdb4cd34b9c2a4a3ccebf0048137892e5586fe8Todd Poynor     *     events are incoming.  CPU and GPU load may be expected soon,
108bcdb4cd34b9c2a4a3ccebf0048137892e5586fe8Todd Poynor     *     and it may be appropriate to raise speeds of CPU, memory bus,
109bcdb4cd34b9c2a4a3ccebf0048137892e5586fe8Todd Poynor     *     etc.  The data parameter is unused.
110bcdb4cd34b9c2a4a3ccebf0048137892e5586fe8Todd Poynor     *
1112f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor     * A particular platform may choose to ignore any hint.
1125cb1de89a905dd13c858779d73721bbc36cd4be1Mathias Agopian     *
1135cb1de89a905dd13c858779d73721bbc36cd4be1Mathias Agopian     * availability: version 0.2
1145cb1de89a905dd13c858779d73721bbc36cd4be1Mathias Agopian     *
1152f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor     */
1162f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor    void (*powerHint)(struct power_module *module, power_hint_t hint,
1172f143fba74f6be91fe8805ef8bbdffe5b8ece8b4Todd Poynor                      void *data);
118c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor} power_module_t;
119c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor
120c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor
121c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor__END_DECLS
122c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor
123c82792c0a4135c1a5de4e4f0ca47318fa5dd7e14Todd Poynor#endif  // ANDROID_INCLUDE_HARDWARE_POWER_H
124