1# Power data sources 2 3On Android Perfetto bundles data sources to retrieve power 4counters from the device power management units (where supported). 5 6## Battery counters 7 8_This data source has been introduced in Android 10 (Q) and requires the 9presence of power-management hardware on the device. This is available on 10most Google Pixel smartphones._ 11 12Modern smartphones are equipped with a power monitoring IC which is able to 13measure the charge flowing in and out of the battery. This allows Perfetto to 14observe the total and instantaneous charge drained from the battery by the 15overall device (the union of SoC, display, radios and all other hardware 16units). 17 18A simplified block diagram: 19 20 21 22These counters report: 23 24* The remaining battery capacity in %. 25* The remaining battery charge in microampere-hours (µAh). 26* The instantaneous (typically the average over a small window of time) current 27 in microampere (µA) 28 29The presence and the resolution of these counters depends on the device 30manufacturer. At the platform level this data is obtained polling the 31Android [IHealth HAL][health-hal]. 32For more details on HW specs and resolution see 33[Measuring Device Power](https://source.android.com/devices/tech/power/device). 34 35[health-hal]: https://cs.android.com/android/platform/superproject/+/master:hardware/interfaces/health/2.0/IHealth.hal?q=IHealth 36 37#### Measuring charge while plugged on USB 38 39Battery counters measure the charge flowing *in* and *out* of 40the battery. If the device is plugged to a USB cable, you will likely observe 41a negative instantaneous current and an increase of the total charge, denoting 42the fact that charge is flowing in the battery (i.e. charging it) rather 43than out. 44 45This can make measurements in lab settings problematic. The known workarounds 46for this are: 47 48* Using specialized USB hubs that allow to electrically disconnect the USB ports 49 from the host side. This allows to effectively disconnect the phone while the 50 tests are running. 51 52* On rooted phones the power management IC driver allows to disconnect the USB 53 charging while keeping the USB data link active. This feature is 54 SoC-specific, is undocumented and not exposed through any HAL. 55 For instance on a Pixel 2 this can be achieved running, as root: 56 `echo 1 > /sys/devices/soc/800f000.qcom,spmi/spmi-0/spmi0-02/800f000.qcom,spmi:qcom,pmi8998@2:qcom,qpnp-smb2/power_supply/battery/input_suspend`. 57 Note that in most devices the kernel USB driver holds a wakelock to keep the 58 USB data link active, so the device will never fully suspend even when turning 59 the screen off. 60 61### UI 62 63 64 65### SQL 66 67```sql 68select ts, t.name, value from counter as c left join counter_track t on c.track_id = t.id 69``` 70 71ts | name | value 72---|------|------ 73338297039804951 | batt.charge_uah | 2085000 74338297039804951 | batt.capacity_pct | 75 75338297039804951 | batt.current_ua | -1469687 76338297145212097 | batt.charge_uah | 2085000 77338297145212097 | batt.capacity_pct | 75 78338297145212097 | batt.current_ua | -1434062 79 80### TraceConfig 81 82Trace proto: 83[BatteryCounters](/docs/reference/trace-packet-proto.autogen#BatteryCounters) 84 85Config proto: 86[AndroidPowerConfig](/docs/reference/trace-config-proto.autogen#AndroidPowerConfig) 87 88Sample config: 89 90```protobuf 91data_sources: { 92 config { 93 name: "android.power" 94 android_power_config { 95 battery_poll_ms: 250 96 battery_counters: BATTERY_COUNTER_CAPACITY_PERCENT 97 battery_counters: BATTERY_COUNTER_CHARGE 98 battery_counters: BATTERY_COUNTER_CURRENT 99 } 100 } 101} 102``` 103 104## Power rails 105 106_This data source has been introduced in Android 10 (Q) and requires the 107dedicated hardware on the device. This hardware is not yet available on 108most production phones._ 109 110Recent version of Android introduced the support for more advanced power 111monitoring at the hardware subsystem level, known as "Power rail counters". 112These counters measure the energy drained by (groups of) hardware units. 113 114Unlike the battery counters, they are not affected by the charging/discharging 115state of the battery, because they measure power downstream of the battery. 116 117The presence and the resolution of power rail counters depends on the device 118manufacturer. At the platform level this data is obtained polling the 119Android [IPowerStats HAL][power-hal]. 120 121[power-hal]: https://cs.android.com/android/platform/superproject/+/master:hardware/interfaces/power/stats/1.0/IPowerStats.hal 122 123Simplified block diagram: 124 125 126 127### TraceConfig 128 129Trace proto: 130[PowerRails](/docs/reference/trace-packet-proto.autogen#PowerRails) 131 132Config proto: 133[AndroidPowerConfig](/docs/reference/trace-config-proto.autogen#AndroidPowerConfig) 134 135Sample config: 136 137```protobuf 138data_sources: { 139 config { 140 name: "android.power" 141 android_power_config { 142 battery_poll_ms: 250 143 collect_power_rails: true 144 # Note: it is possible to specify both rails and battery counters 145 # in this section. 146 } 147 } 148} 149``` 150 151## Related data sources 152 153See also the [CPU -> Frequency scaling](cpu-freq.md) data source. 154
