powerstats: Refine PowerStats HAL 2.0 documentation
Bug: 169864180
Test: m
Change-Id: I988ff3508fdb09803a0ffdafc9d40cac3b72e075
diff --git a/powerstats/aidl/aidl_api/android.hardware.powerstats/current/android/hardware/powerstats/ChannelInfo.aidl b/powerstats/aidl/aidl_api/android.hardware.powerstats/current/android/hardware/powerstats/ChannelInfo.aidl
index 6681df1..51ac7bf 100644
--- a/powerstats/aidl/aidl_api/android.hardware.powerstats/current/android/hardware/powerstats/ChannelInfo.aidl
+++ b/powerstats/aidl/aidl_api/android.hardware.powerstats/current/android/hardware/powerstats/ChannelInfo.aidl
@@ -19,5 +19,5 @@
@VintfStability
parcelable ChannelInfo {
int channelId;
- String channelName;
+ @utf8InCpp String channelName;
}
diff --git a/powerstats/aidl/aidl_api/android.hardware.powerstats/current/android/hardware/powerstats/IPowerStats.aidl b/powerstats/aidl/aidl_api/android.hardware.powerstats/current/android/hardware/powerstats/IPowerStats.aidl
index 2f251f3..cc668ea 100644
--- a/powerstats/aidl/aidl_api/android.hardware.powerstats/current/android/hardware/powerstats/IPowerStats.aidl
+++ b/powerstats/aidl/aidl_api/android.hardware.powerstats/current/android/hardware/powerstats/IPowerStats.aidl
@@ -19,7 +19,7 @@
@VintfStability
interface IPowerStats {
android.hardware.powerstats.PowerEntityInfo[] getPowerEntityInfo();
- android.hardware.powerstats.StateResidencyResult[] getPowerEntityStateResidency(in int[] powerEntityIds);
+ android.hardware.powerstats.StateResidencyResult[] getStateResidency(in int[] powerEntityIds);
android.hardware.powerstats.EnergyConsumerId[] getEnergyConsumerInfo();
android.hardware.powerstats.EnergyConsumerResult[] getEnergyConsumed(in android.hardware.powerstats.EnergyConsumerId[] energyConsumerIds);
android.hardware.powerstats.ChannelInfo[] getEnergyMeterInfo();
diff --git a/powerstats/aidl/aidl_api/android.hardware.powerstats/current/android/hardware/powerstats/PowerEntityInfo.aidl b/powerstats/aidl/aidl_api/android.hardware.powerstats/current/android/hardware/powerstats/PowerEntityInfo.aidl
index 105bab7..28939a3 100644
--- a/powerstats/aidl/aidl_api/android.hardware.powerstats/current/android/hardware/powerstats/PowerEntityInfo.aidl
+++ b/powerstats/aidl/aidl_api/android.hardware.powerstats/current/android/hardware/powerstats/PowerEntityInfo.aidl
@@ -19,6 +19,6 @@
@VintfStability
parcelable PowerEntityInfo {
int powerEntityId;
- String powerEntityName;
+ @utf8InCpp String powerEntityName;
android.hardware.powerstats.StateInfo[] states;
}
diff --git a/powerstats/aidl/aidl_api/android.hardware.powerstats/current/android/hardware/powerstats/StateInfo.aidl b/powerstats/aidl/aidl_api/android.hardware.powerstats/current/android/hardware/powerstats/StateInfo.aidl
index 6ad3418..46d89ee 100644
--- a/powerstats/aidl/aidl_api/android.hardware.powerstats/current/android/hardware/powerstats/StateInfo.aidl
+++ b/powerstats/aidl/aidl_api/android.hardware.powerstats/current/android/hardware/powerstats/StateInfo.aidl
@@ -19,5 +19,5 @@
@VintfStability
parcelable StateInfo {
int stateId;
- String stateName;
+ @utf8InCpp String stateName;
}
diff --git a/powerstats/aidl/android/hardware/powerstats/ChannelInfo.aidl b/powerstats/aidl/android/hardware/powerstats/ChannelInfo.aidl
index 77d2289..61cce85 100644
--- a/powerstats/aidl/android/hardware/powerstats/ChannelInfo.aidl
+++ b/powerstats/aidl/android/hardware/powerstats/ChannelInfo.aidl
@@ -19,14 +19,12 @@
@VintfStability
parcelable ChannelInfo {
/**
- * Unique ID
+ * Unique ID of this ChannelInfo
*/
int channelId;
/**
- * Unique name of the ChannelInfo:
- *
- * Vendor/device specific. Opaque to framework
+ * Unique name of the ChannelInfo. Vendor/device specific. Opaque to framework
*/
- String channelName;
+ @utf8InCpp String channelName;
}
diff --git a/powerstats/aidl/android/hardware/powerstats/EnergyConsumerResult.aidl b/powerstats/aidl/android/hardware/powerstats/EnergyConsumerResult.aidl
index 2c4e9e4..c52e638 100644
--- a/powerstats/aidl/android/hardware/powerstats/EnergyConsumerResult.aidl
+++ b/powerstats/aidl/android/hardware/powerstats/EnergyConsumerResult.aidl
@@ -21,15 +21,15 @@
@VintfStability
parcelable EnergyConsumerResult {
/**
- * Unique ID associated with the given EnergyMeterInfo
+ * ID of the EnergyConsumer associated with this result
*/
EnergyConsumerId energyConsumerId;
/**
- * Time since device boot in milliseconds
+ * Time since boot in milliseconds
*/
long timestampMs;
/**
- * Accumulated energy since device boot in microwatt-seconds (uWs)
+ * Accumulated energy since boot in microwatt-seconds (uWs)
*/
long energyUWs;
}
diff --git a/powerstats/aidl/android/hardware/powerstats/EnergyMeasurement.aidl b/powerstats/aidl/android/hardware/powerstats/EnergyMeasurement.aidl
index 3b31b46..7c98646 100644
--- a/powerstats/aidl/android/hardware/powerstats/EnergyMeasurement.aidl
+++ b/powerstats/aidl/android/hardware/powerstats/EnergyMeasurement.aidl
@@ -19,15 +19,15 @@
@VintfStability
parcelable EnergyMeasurement {
/**
- * Unique ID corresponding to the given ChannelInfo
+ * ID of the Channel associated with this measurement
*/
int channelId;
/**
- * Time since device boot(CLOCK_BOOTTIME) in milli-seconds
+ * Time since boot in milliseconds
*/
long timestampMs;
/**
- * Accumulated energy since device boot in microwatt-seconds (uWs)
+ * Accumulated energy since boot in microwatt-seconds (uWs)
*/
long energyUWs;
}
diff --git a/powerstats/aidl/android/hardware/powerstats/IPowerStats.aidl b/powerstats/aidl/android/hardware/powerstats/IPowerStats.aidl
index 9943605..bb13b8e 100644
--- a/powerstats/aidl/android/hardware/powerstats/IPowerStats.aidl
+++ b/powerstats/aidl/android/hardware/powerstats/IPowerStats.aidl
@@ -26,58 +26,70 @@
@VintfStability
interface IPowerStats {
/**
- * Reports information related to all supported PowerEntity(s) for which
- * data is available. A PowerEntity is defined as a platform subsystem,
- * peripheral, or power domain that impacts the total device power
- * consumption.
+ * Return information related to all supported PowerEntity(s) for which state residency data
+ * is available.
+ *
+ * A PowerEntity is defined as a platform subsystem, peripheral, or power domain that impacts
+ * the total device power consumption.
*
* @return List of information on each PowerEntity
*/
PowerEntityInfo[] getPowerEntityInfo();
/**
- * Reports accumulated residency data for each specified PowerEntity.
+ * Reports the accumulated state residency for each requested PowerEntity.
+ *
* Each PowerEntity may reside in one of multiple states. It may also
* transition from one state to another. StateResidency is defined as
* an accumulation of time that a PowerEntity resided in each
* of its possible states, the number of times that each state was
* entered, and a timestamp corresponding to the last time that state
- * was entered. Data is accumulated starting from the last time the
- * PowerEntity was reset.
+ * was entered.
*
- * @param powerEntityIds IDs of PowerEntities for which data is required.
- * To get data for all PowerEntities pass an empty vector. PowerEntity name to
- * ID mapping can be queried from getPowerEntityInfo() API.
- * @return StateResidency since boot for all requested PowerEntity(s).
+ * Data is accumulated starting at device boot.
+ *
+ * @param powerEntityIds List of IDs of PowerEntities for which data is requested.
+ * Passing an empty list will return state residency for all available PowerEntitys.
+ * ID of each PowerEntity is contained in PowerEntityInfo.
+ *
+ * @return StateResidency since boot for each requested PowerEntity
+ *
+ * Returns the following service-specific exceptions in order of highest priority:
+ * - STATUS_BAD_VALUE if an invalid powerEntityId is provided
+ * - STATUS_FAILED_TRANSACTION if any StateResidencyResult fails to be returned
*/
- StateResidencyResult[] getPowerEntityStateResidency(in int[] powerEntityIds);
+ StateResidencyResult[] getStateResidency(in int[] powerEntityIds);
/**
- * Reports a list of IDs corresponding to all enabled EnergyConsumers.
+ * Return the list IDs for all supported EnergyConsumers for which energy consumption data is
+ * available.
*
- * @return list of EnergyConsumersIds that are available.
+ * An EnergyConsumer is a device subsystem or peripheral that consumes energy. Energy
+ * consumption data may be used by framework for the purpose of power attribution.
+ *
+ * @return List of EnergyConsumersIds that are available.
*/
EnergyConsumerId[] getEnergyConsumerInfo();
/**
- * Returns any available energy consumption results.
+ * Reports the energy consumed since boot by each requested EnergyConsumer.
*
- * @param energyConsumerIds IDs of EnergyConsumers for which data is requested.
- * To get data for all EnergyConsumers pass an empty list.
- * @return List of EnergyConsumerResults reporting energy consumed since boot for each requested
- * EnergyConsumerId.
+ * @param energyConsumerIds List of IDs of EnergyConsumers for which data is requested.
+ * Passing an empty list will return state residency for all available EnergyConsumers.
*
- * Returns the following service-specific exceptions:
- * STATUS_FAILED_TRANSACTION if any of the requested energy results is unavailable
- * STATUS_BAD_VALUE if an invalid EnergyConsumer Id is provided
+ * @return Energy consumed since boot for each requested EnergyConsumer
+ *
+ * Returns the following service-specific exceptions in order of highest priority:
+ * - STATUS_BAD_VALUE if an invalid energyConsumerId is provided
+ * - STATUS_FAILED_TRANSACTION if any EnergyConsumerResult fails to be returned
*/
EnergyConsumerResult[] getEnergyConsumed(in EnergyConsumerId[] energyConsumerIds);
/**
- * Reports channels monitored by Energy Meters.
- * Each channel has a name, which may correspond to the name of a power rail on the device,
- * and an Id which is used to relate EnergyMeasurements returned by readEnergyMeters() with a
- * given ChannelInfo.
+ * Return information related to all channels monitored by Energy Meters.
+ *
+ * An Energy Meter is a device that monitors energy and may support monitoring multiple
+ * channels simultaneously. A channel may correspond a bus, sense resistor, or power rail.
*
* @return Information about channels monitored by Energy Meters.
*/
@@ -87,13 +99,14 @@
* Reports accumulated energy since boot for each specified channel.
*
* @param channelIds IDs of channels for which data is requested.
- * To get data for all channels pass an empty list. Channel name to
- * ID mapping can be queried from getEnergyMeterInfo() API.
- * @return Energy measured since boot for all requested channels.
+ * Passing an empty list will return energy measurements for all available channels.
+ * ID of each channel is contained in ChannelInfo.
*
- * Returns the following service-specific exceptions:
- * STATUS_FAILED_TRANSACTION if any of the requested energy measurements are unavailable
- * STATUS_BAD_VALUE if an invalid channelId is provided
+ * @return Energy measured since boot for each requested channel
+ *
+ * Returns the following service-specific exceptions in order of highest priority:
+ * - STATUS_BAD_VALUE if an invalid channelId is provided
+ * - STATUS_FAILED_TRANSACTION if any EnergyMeasurement fails to be returned
*/
EnergyMeasurement[] readEnergyMeters(in int[] channelIds);
}
\ No newline at end of file
diff --git a/powerstats/aidl/android/hardware/powerstats/PowerEntityInfo.aidl b/powerstats/aidl/android/hardware/powerstats/PowerEntityInfo.aidl
index a8ca0f6..bd09d66 100644
--- a/powerstats/aidl/android/hardware/powerstats/PowerEntityInfo.aidl
+++ b/powerstats/aidl/android/hardware/powerstats/PowerEntityInfo.aidl
@@ -18,20 +18,16 @@
import android.hardware.powerstats.StateInfo;
-/**
- * PowerEntityInfo contains information, such as the ID, name, and type of a
- * given PowerEntity.
- */
@VintfStability
parcelable PowerEntityInfo {
/**
- * Unique ID corresponding to the PowerEntity
+ * Unique ID of this PowerEntityInfo
*/
int powerEntityId;
/**
- * Unique name of the PowerEntity. Vendor/device specific. Opaque to framework.
+ * Unique name of the PowerEntity. Vendor/device specific. Opaque to framework
*/
- String powerEntityName;
+ @utf8InCpp String powerEntityName;
/**
* List of states that the PowerEntity may reside in
*/
diff --git a/powerstats/aidl/android/hardware/powerstats/StateInfo.aidl b/powerstats/aidl/android/hardware/powerstats/StateInfo.aidl
index 756fd87..5035f7c 100644
--- a/powerstats/aidl/android/hardware/powerstats/StateInfo.aidl
+++ b/powerstats/aidl/android/hardware/powerstats/StateInfo.aidl
@@ -19,13 +19,13 @@
@VintfStability
parcelable StateInfo {
/**
- * ID corresponding to the state. Unique for a given PowerEntityInfo
+ * Unique (for a given PowerEntityInfo) ID of this StateInfo
*/
int stateId;
/**
* Unique (for a given PowerEntityInfo) name of the state. Vendor/device specific.
- * Opaque to framework.
+ * Opaque to framework
*/
- String stateName;
+ @utf8InCpp String stateName;
}
diff --git a/powerstats/aidl/android/hardware/powerstats/StateResidency.aidl b/powerstats/aidl/android/hardware/powerstats/StateResidency.aidl
index 882ba5b..2a8f541 100644
--- a/powerstats/aidl/android/hardware/powerstats/StateResidency.aidl
+++ b/powerstats/aidl/android/hardware/powerstats/StateResidency.aidl
@@ -22,20 +22,20 @@
@VintfStability
parcelable StateResidency {
/**
- * ID of the corresponding StateInfo
+ * ID of the state associated with this residency
*/
int stateId;
/**
* Total time in milliseconds that the corresponding PowerEntity resided
- * in since device boot
+ * in this state since boot
*/
long totalTimeInStateMs;
/**
- * Total number of times that the state was entered since device boot
+ * Total number of times that the state was entered since boot
*/
long totalStateEntryCount;
/**
- * Last time this state was entered. Time in milliseconds since device boot
+ * Last time this state was entered. Time in milliseconds since boot
*/
long lastEntryTimestampMs;
}
\ No newline at end of file
diff --git a/powerstats/aidl/android/hardware/powerstats/StateResidencyResult.aidl b/powerstats/aidl/android/hardware/powerstats/StateResidencyResult.aidl
index d6ac4ea..b3a9f03 100644
--- a/powerstats/aidl/android/hardware/powerstats/StateResidencyResult.aidl
+++ b/powerstats/aidl/android/hardware/powerstats/StateResidencyResult.aidl
@@ -21,11 +21,11 @@
@VintfStability
parcelable StateResidencyResult {
/**
- * ID of the corresponding PowerEntity
+ * ID of the PowerEntity associated with this result
*/
int powerEntityId;
/**
- * Residency data for each state the PowerEntity's state space
+ * Residency for each state in the PowerEntity's state space
*/
StateResidency[] stateResidencyData;
}
diff --git a/powerstats/aidl/default/PowerStats.cpp b/powerstats/aidl/default/PowerStats.cpp
index 9f3e76e..d1c97db 100644
--- a/powerstats/aidl/default/PowerStats.cpp
+++ b/powerstats/aidl/default/PowerStats.cpp
@@ -28,9 +28,8 @@
return ndk::ScopedAStatus::ok();
}
-ndk::ScopedAStatus PowerStats::getPowerEntityStateResidency(
- const std::vector<int32_t>& in_powerEntityIds,
- std::vector<StateResidencyResult>* _aidl_return) {
+ndk::ScopedAStatus PowerStats::getStateResidency(const std::vector<int32_t>& in_powerEntityIds,
+ std::vector<StateResidencyResult>* _aidl_return) {
(void)in_powerEntityIds;
(void)_aidl_return;
return ndk::ScopedAStatus::ok();
diff --git a/powerstats/aidl/default/PowerStats.h b/powerstats/aidl/default/PowerStats.h
index 0007efa..6d2d460 100644
--- a/powerstats/aidl/default/PowerStats.h
+++ b/powerstats/aidl/default/PowerStats.h
@@ -28,9 +28,8 @@
PowerStats() = default;
// Methods from aidl::android::hardware::powerstats::IPowerStats
ndk::ScopedAStatus getPowerEntityInfo(std::vector<PowerEntityInfo>* _aidl_return) override;
- ndk::ScopedAStatus getPowerEntityStateResidency(
- const std::vector<int32_t>& in_powerEntityIds,
- std::vector<StateResidencyResult>* _aidl_return) override;
+ ndk::ScopedAStatus getStateResidency(const std::vector<int32_t>& in_powerEntityIds,
+ std::vector<StateResidencyResult>* _aidl_return) override;
ndk::ScopedAStatus getEnergyConsumerInfo(std::vector<EnergyConsumerId>* _aidl_return) override;
ndk::ScopedAStatus getEnergyConsumed(const std::vector<EnergyConsumerId>& in_energyConsumerIds,
std::vector<EnergyConsumerResult>* _aidl_return) override;
diff --git a/powerstats/aidl/vts/VtsHalPowerStatsTargetTest.cpp b/powerstats/aidl/vts/VtsHalPowerStatsTargetTest.cpp
index 34d1b22..e71e495 100644
--- a/powerstats/aidl/vts/VtsHalPowerStatsTargetTest.cpp
+++ b/powerstats/aidl/vts/VtsHalPowerStatsTargetTest.cpp
@@ -115,9 +115,9 @@
}
}
-TEST_P(PowerStatsAidl, TestGetStateResidencyData) {
- std::vector<StateResidencyResult> data;
- ASSERT_TRUE(powerstats->getPowerEntityStateResidency({}, &data).isOk());
+TEST_P(PowerStatsAidl, TestGetStateResidency) {
+ std::vector<StateResidencyResult> results;
+ ASSERT_TRUE(powerstats->getStateResidency({}, &results).isOk());
}
TEST_P(PowerStatsAidl, TestGetEnergyMeterInfo) {