1/*
2 * Copyright (C) 2018 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16package [email protected];
17
18interface IPowerStats {
19
20    /**
21     * Rail information:
22     * Reports information related to the rails being monitored.
23     *
24     * @return rails Information about monitored rails.
25     * @return status SUCCESS on success or NOT_SUPPORTED if
26     *     feature is not enabled or FILESYSTEM_ERROR on filesystem nodes
27     *     access error.
28     */
29    getRailInfo()
30        generates(vec<RailInfo> rails, Status status);
31
32    /**
33     * Rail level energy measurements for low frequency clients:
34     * Reports accumulated energy since boot on each rail.
35     *
36     * @param railIndices Indices of rails for which data is required.
37     *     To get data for all rails pass an empty vector. Rail name to
38     *     index mapping can be queried from getRailInfo() API.
39     * @return data Energy values since boot for all requested rails.
40     * @return status SUCCESS on success or NOT_SUPPORTED if
41     *     feature is not enabled or FILESYSTEM_ERROR on filesystem nodes
42     *     access error.
43     */
44    getEnergyData(vec<uint32_t> railIndices)
45        generates(vec<EnergyData> data, Status status);
46
47    /**
48     * Stream rail level power measurements for high frequency clients:
49     * Streams accumulated energy since boot on each rail. This API is
50     * asynchronous.
51     *
52     * @param timeMs Time(in ms) for which energyData should be streamed
53     * @param samplingRate Frequency(in Hz) at which samples should be
54     *     captured. If the requested sampling rate is not supported then
55     *     SUCCESS is returned and numSamples are reported back according
56     *     to the supported sampling rate.
57     * @return mqDesc Blocking Synchronous Fast Message Queue descriptor - One
58     *     writer(power.stats HAL) and one reader are supported. Data is
59     *     present in the following format in the queue:
60     *     +-----------------------+       <--
61     *     | EnergyData for rail 1 |         |
62     *     +-----------------------+         |
63     *     | EnergyData for rail 2 |         |
64     *     +-----------------------+         |
65     *     |          .            |         |-- 1st Sample
66     *     |          .            |         |
67     *     |          .            |         |
68     *     +-----------------------+         |
69     *     | EnergyData for rail n |         |
70     *     +-----------------------+       <--
71     *     |          .            |
72     *     |          .            |
73     *     |          .            |
74     *     +-----------------------+       <--
75     *     | EnergyData for rail 1 |         |
76     *     +-----------------------+         |
77     *     | EnergyData for rail 2 |         |
78     *     +-----------------------+         |
79     *     |          .            |         |-- kth Sample
80     *     |          .            |         |
81     *     |          .            |         |
82     *     +-----------------------+         |
83     *     | EnergyData for rail n |         |
84     *     +-----------------------+       <--
85     *
86     *     where,
87     *     n = railsPerSample
88     *     k = numSamples
89     *
90     * @return numSamples Number of samples which will be generated in timeMs.
91     * @return railsPerSample Number of rails measured per sample.
92     * @return status SUCCESS on success or FILESYSTEM_ERROR on filesystem
93     *     nodes access or NOT_SUPPORTED if feature is not enabled or
94     *     INSUFFICIENT_RESOURCES if there are not enough resources.
95     */
96    streamEnergyData(uint32_t timeMs, uint32_t samplingRate)
97        generates(fmq_sync<EnergyData> mqDesc, uint32_t numSamples,
98                uint32_t railsPerSample, Status status);
99
100    /**
101     * PowerEntity information:
102     * Reports information related to all supported PowerEntity(s) for which
103     * data is available. A PowerEntity is defined as a platform subsystem,
104     * peripheral, or power domain that impacts the total device power
105     * consumption.
106     *
107     * @return powerEntityInfos List of information on each PowerEntity
108     * @return status SUCCESS on success, NOT_SUPPORTED if feature is not
109     *     enabled, FILESYSTEM_ERROR if there was an error accessing the
110     *     filesystem.
111     */
112    getPowerEntityInfo()
113        generates(vec<PowerEntityInfo> powerEntityInfos, Status status);
114
115    /**
116     * PowerEntity state information:
117     * Reports the set of power states for which the specified
118     * PowerEntity(s) provide residency data.
119     *
120     * @param powerEntityIds collection of IDs of PowerEntity(s) for which
121     *     state information is requested. PowerEntity name to ID mapping may
122     *     be queried from getPowerEntityInfo(). To get state space
123     *     information for all PowerEntity(s) pass an empty vector.
124     *
125     * @return powerEntityStateSpaces PowerEntity state space information for
126     *     each specified PowerEntity that provides state space information.
127     * @return status SUCCESS on success, NOT_SUPPORTED if feature is not
128     *     enabled, FILESYSTEM_ERROR if there was an error accessing the
129     *     filesystem, INVALID_INPUT if any requested PowerEntity(s) do not
130     *     provide state space information and there was not a filesystem error.
131     */
132    getPowerEntityStateInfo(vec<uint32_t> powerEntityIds)
133        generates(vec<PowerEntityStateSpace> powerEntityStateSpaces,
134                  Status status);
135
136    /**
137     * PowerEntity residencies for low frequency clients:
138     * Reports accumulated residency data for each specified PowerEntity.
139     * Each PowerEntity may reside in one of multiple states. It may also
140     * transition to another state. Residency data is an accumulation of time
141     * that a specified PowerEntity resided in each of its possible states,
142     * the number of times that each state was entered, and a timestamp
143     * corresponding to the last time that state was entered. Data is
144     * accumulated starting from the last time the PowerEntity was reset.
145     *
146     * @param powerEntityId collection of IDs of PowerEntity(s) for which
147     *     residency data is requested. PowerEntity name to ID mapping may
148     *     be queried from getPowerEntityInfo(). To get state residency
149     *     data for all PowerEntity(s) pass an empty vector.
150     * @return stateResidencyResults state residency data for each specified
151     *     PowerEntity that provides state residency data.
152     * @return status SUCCESS on success, NOT_SUPPORTED if feature is not
153     *     enabled, FILESYSTEM_ERROR if there was an error accessing the
154     *     filesystem, INVALID_INPUT if any requested PowerEntity(s) do not
155     *     provide state residency data and there was not a filesystem error.
156     */
157    getPowerEntityStateResidencyData(vec<uint32_t> powerEntityIds)
158        generates(vec<PowerEntityStateResidencyResult> stateResidencyResults,
159                  Status status);
160};
161