docs: Add article on batterstats, create power dir.
Bug ID: 18334705
Change-Id: I9ce773d42f27d2cb94120d01bede002a0c73d652
Change-Id: I992d76ec7c640de45eeccd48cebb03e61eec8eff
docs: Add Batterysys article, create Power dir, and change nav.
Bug ID: 18334705
diff --git a/src/devices/tech/power/batterystats.jd b/src/devices/tech/power/batterystats.jd
new file mode 100644
index 0000000..92aeb04
--- /dev/null
+++ b/src/devices/tech/power/batterystats.jd
@@ -0,0 +1,1037 @@
+page.title=Viewing Battery Usage Data
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+ <p>The <code>dumpsys batterystats</code> command generates interesting
+ statistical data about battery usage on a device, organized by unique user
+ ID (UID). The statistics include the following:</p>
+
+ <ul>
+ <li>History of battery-related events</li>
+
+ <li>Global statistics for the device</li>
+
+ <li>Approximate power use per UID and system component</li>
+
+ <li>Per-app mobile milliseconds per packet</li>
+
+ <li>System UID aggregated statistics</li>
+
+ <li>App UID aggregated statistics</li>
+ </ul>
+
+ <p class="note">You can use the <a href=
+ "https://github.com/google/battery-historian">Battery Historian</a> tool on
+ the output of the dumpsys command to generate an HTML visualization of
+ power-related events from the logs. This information makes it easier for
+ you to understand and diagnose any battery-related issues.</p>
+
+ <h2 id="command-line_options">Command line options</h2>
+
+ <p>Use the <code>--help</code> option to learn about the various options
+ for tailoring the output.</p>
+
+ <p>Use the <code>--checkin</code> option to get the results in
+ machine-readable csv format.</p>
+
+ <p>To print battery usage statistics for a given app package since the
+ device was last charged, run this command:</p>
+ <pre class="prettyprint">
+$ adb shell dumpsys batterystats --charged <package-name>
+ </pre>
+
+ <h2 id="sample_input">Input</h2>
+
+ <p>To print battery usage statistics for all apps since the device was last
+ charged, in machine-readable format, run this command:</p>
+ <pre class="prettyprint">
+$ adb shell dumpsys batterystats --charged --checkin
+ </pre>
+
+ <h2 id="output">Output</h2>
+
+ <p>The output looks like this:</p>
+
+ <p>$ adb shell dumpsys batterystats --charged --checkin</p>
+
+ <pre class="no-pretty=print">
+ 9,0,i,vers,11,116,K,L 9,0,i,uid,1000,android
+ 9,0,i,uid,1000,com.android.providers.settings
+ 9,0,i,uid,1000,com.android.inputdevices
+ 9,0,i,uid,1000,com.android.server.telecom
+ 9,0,i,uid,1000,com.android.keychain 9,0,i,uid,1000,com.android.settings
+ 9,0,i,uid,1000,com.android.location.fused
+ 9,0,i,uid,1001,com.android.providers.telephony
+ 9,0,i,uid,1001,com.android.mms.service 9,0,i,uid,1001,com.android.stk
+ 9,0,i,uid,1001,com.android.phone 9,0,i,uid,1027,com.android.nfc
+ 9,0,i,uid,2000,com.android.shell
+ 9,0,i,uid,10002,com.android.providers.calendar
+ 9,0,i,uid,10003,com.android.cellbroadcastreceiver
+ 9,0,i,uid,10004,com.android.providers.userdictionary
+ 9,0,i,uid,10004,com.android.providers.contacts
+ 9,0,i,uid,10005,com.google.android.apps.enterprise.dmagent
+ 9,0,i,uid,10006,com.android.defcontainer
+ 9,0,i,uid,10007,com.android.providers.media
+ 9,0,i,uid,10007,com.android.providers.downloads
+ 9,0,i,uid,10007,com.android.providers.downloads.ui
+ 9,0,i,uid,10008,com.android.externalstorage
+ 9,0,i,uid,10009,com.google.android.syncadapters.contacts
+ 9,0,i,uid,10009,com.google.android.gms
+ 9,0,i,uid,10009,com.google.android.gsf
+ 9,0,i,uid,10009,com.google.android.gsf.login
+ 9,0,i,uid,10009,com.google.android.backuptransport
+ 9,0,i,uid,10011,com.google.android.dialer
+ 9,0,i,uid,10013,com.google.android.onetimeinitializer
+ 9,0,i,uid,10014,com.google.android.partnersetup
+ 9,0,i,uid,10015,com.android.launcher
+ 9,0,i,uid,10016,com.android.managedprovisioning
+ 9,0,i,uid,10017,com.android.mms 9,0,i,uid,10018,com.android.musicfx
+ 9,0,i,uid,10019,com.android.vending
+ 9,0,i,uid,10022,com.android.sharedstoragebackup
+ 9,0,i,uid,10023,com.android.systemui
+ 9,0,i,uid,10025,com.google.android.googlequicksearchbox
+ 9,0,i,uid,10027,com.google.android.apps.walletnfcrel
+ 9,0,i,uid,10029,com.google.android.marvin.talkback
+ 9,0,i,uid,10031,com.google.android.apps.books
+ 9,0,i,uid,10034,com.google.android.calendar
+ 9,0,i,uid,10037,com.android.chrome
+ 9,0,i,uid,10039,com.google.android.configupdater
+ 9,0,i,uid,10040,com.google.android.deskclock
+ 9,0,i,uid,10041,com.android.documentsui
+ 9,0,i,uid,10042,com.google.android.apps.docs
+ 9,0,i,uid,10047,com.google.android.ears
+ 9,0,i,uid,10054,com.google.android.talk
+ 9,0,i,uid,10057,com.google.android.inputmethod.latin
+ 9,0,i,uid,10061,com.google.android.music
+ 9,0,i,uid,10064,com.android.packageinstaller
+ 9,0,i,uid,10068,com.google.android.apps.plus
+ 9,0,i,uid,10069,com.google.android.gm
+ 9,0,i,uid,10070,com.google.android.keep
+ 9,0,i,uid,10071,com.google.android.apps.genie.geniewidget
+ 9,0,i,uid,10072,com.android.printspooler
+ 9,0,i,uid,10076,com.google.android.videos
+ 9,0,i,uid,10079,com.google.android.youtube
+ 9,0,i,uid,10084,com.google.android.apps.magazines
+ 9,0,i,dsd,1820451,97,s-,p- 9,0,i,dsd,3517481,98,s-,p-
+ 9,0,l,bt,0,8548446,1000983,8566645,1019182,1418672206045,8541652,994188
+ 9,0,l,gn,0,0,666932,495312,0,0,2104,1444
+ 9,0,l,m,6794,0,8548446,8548446,0,0,0,666932,495312,0,697728,0,0,0,5797,0,0
+ 9,0,l,br,9,0,6785,0,0 9,0,l,sgt,8548446,0,0,0,0 9,0,l,sst,9000
+ 9,0,l,sgc,0,0,0,0,0 9,0,l,dct,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
+ 9,0,l,dcc,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 9,0,l,wst,0,0,0,0,0,0,0,0
+ 9,0,l,wsc,0,0,0,0,0,0,0,0 9,0,l,wsst,0,0,0,0,0,0,0,52,0,0,8548394,0,0
+ 9,0,l,wssc,0,0,0,0,0,0,0,2,0,0,2,0,0 9,0,l,wsgt,0,0,0,3016,8545430
+ 9,0,l,wsgc,0,0,0,2,1 9,0,l,bst,0,0,0,0 9,0,l,bsc,0,0,0,0 9,0,l,dc,2,3,0,3
+ 9,0,l,kwl,msm_ipc_read00000001:00000001,0,0
+ 9,0,l,kwl,rpm_regulator_tcxo,0,0 9,0,l,kwl,wlan,25423,32
+ 9,0,l,kwl,event4-648,0,0 9,0,l,kwl,qcril,187,2 9,0,l,kwl,ssr(dsps),0,0
+ 9,0,l,kwl,bq51051b_wireless_chip,0,0 9,0,l,kwl,qmi0,0,0
+ 9,0,l,kwl,event5-648,7755,1231
+ 9,0,l,kwl,PowerManagerService.WakeLocks,680435,3908
+ 9,0,l,kwl,msm_hsic_host,66258,35 9,0,l,kwl,qcom_sap_wakelock,0,0
+ 9,0,l,kwl,sns_async_ev_wakelock,91954,1244 9,0,l,kwl,qmuxd_port_wl_12,0,0
+ 9,0,l,kwl,pil-wcnss,0,0 9,0,l,kwl,event0-648,11364,1212
+ 9,0,l,kwl,dofstrim,0,0 9,0,l,kwl,ssr(lpass),0,0
+ 9,0,l,kwl,qmuxd_port_wl_11,0,0 9,0,l,kwl,event2-648,0,0
+ 9,0,l,kwl,pil-vidc,0,0 9,0,l,kwl,mmc0,0,0
+ 9,0,l,kwl,tabla_gpio_irq_resend,0,0 9,0,l,kwl,pil-q6,0,0
+ 9,0,l,kwl,radio-interface,0,0 9,0,l,kwl,msm_ipc_read00000001:00000002,0,0
+ 9,0,l,kwl,event3-648,8143,1231 9,0,l,kwl,ssr(wcnss),0,0
+ 9,0,l,kwl,ssr(gss),0,0 9,0,l,kwl,KeyEvents,98,1263
+ 9,0,l,kwl,unknown_wakeups,0,0 9,0,l,kwl,qmuxd_port_wl_10,0,0
+ 9,0,l,kwl,pil-gss,0,0 9,0,l,kwl,qcom_rx_wakelock,161828,3205
+ 9,0,l,kwl,ssr(external_modem),0,0 9,0,l,kwl,power-supply,228,23
+ 9,0,l,kwl,pil-dsps,0,0 9,0,l,kwl,wcnss,0,0 9,0,l,kwl,msm_otg,0,0
+ 9,0,l,kwl,pm8921_eoc,0,0 9,0,l,kwl,slimport_wake_lock,0,0
+ 9,0,l,kwl,smsm_snapshot,0,0 9,0,l,kwl,suspend_backoff,239760,24
+ 9,0,l,kwl,event1-648,9331,1212 9,0,l,kwl,main,429,0
+ 9,0,l,kwl,alarm,2892,270 9,0,l,kwl,PowerManagerService.Display,432,1
+ 9,0,l,kwl,qmi1,0,0 9,0,l,kwl,kickstart,211,1
+ 9,0,l,kwl,qmuxd_port_wl_9,9,102 9,0,l,kwl,ear_hook,0,0
+ 9,0,l,kwl,mmc0_detect,52,1232 9,0,l,kwl,deleted_wake_locks,0,0
+ 9,0,l,kwl,PowerManagerService.Broadcasts,7331,0 9,0,l,kwl,qmi2,0,0
+ 9,0,l,kwl,smd_sns_dsps,456,1340 9,0,l,kwl,alarm_rtc,36084,122
+ 9,0,l,pws,2100,64.4,42.0,63.0 9,10009,l,pwi,uid,20.6 9,0,l,pwi,cell,18.5
+ 9,0,l,pwi,idle,8.73 9,0,l,pwi,uid,5.46 9,1000,l,pwi,uid,5.11
+ 9,0,l,pwi,wifi,3.28 9,10019,l,pwi,uid,0.847 9,10069,l,pwi,uid,0.408
+ 9,0,l,pwi,scrn,0.385 9,10034,l,pwi,uid,0.322 9,10025,l,pwi,uid,0.185
+ 9,10002,l,pwi,uid,0.180 9,10023,l,pwi,uid,0.168 9,1001,l,pwi,uid,0.0297
+ 9,10068,l,pwi,uid,0.0296 9,10057,l,pwi,uid,0.0234 9,1027,l,pwi,uid,0.0157
+ 9,10079,l,pwi,uid,0.00905 9,10054,l,pwi,uid,0.00527
+ 9,10005,l,pwi,uid,0.00341 9,10004,l,pwi,uid,0.00204
+ 9,2000,l,pwi,uid,0.00192 9,10070,l,pwi,uid,0.00144
+ 9,10061,l,pwi,uid,0.000860 9,10014,l,pwi,uid,0.000495
+ 9,10040,l,pwi,uid,0.000286 9,1014,l,pwi,uid,0.00000157 9,0,l,pwi,over,1.36
+ 9,0,l,nt,0,0,127699,11159,0,0,975,163,0,0
+ 9,0,l,pr,file-storage,0,140,0,0,0,0 9,0,l,pr,TX_Thread,0,440,0,0,0,0
+ 9,0,l,pr,flush-179:0,0,850,0,0,0,0 9,0,l,pr,sync_supers,10,0,0,0,0,0
+ 9,0,l,pr,dhcpcd,0,30,0,0,0,0 9,0,l,pr,kauditd,50,10,0,0,0,0
+ 9,0,l,pr,sdcard,20,110,0,0,0,0 9,0,l,pr,flush-0:18,40,100,0,0,0,0
+ 9,0,l,pr,zygote,250,90,0,0,0,0 9,0,l,pr,bdi-default,0,610,0,0,0,0
+ 9,0,l,pr,ueventd,940,2630,0,0,0,0 9,0,l,pr,kswapd0,0,180,0,0,0,0
+ 9,0,l,pr,debuggerd,180,610,0,0,0,0 9,0,l,pr,jbd2/mmcblk0p20,0,50,0,0,0,0
+ 9,0,l,pr,jbd2/mmcblk0p21,0,250,0,0,0,0
+ 9,0,l,pr,jbd2/mmcblk0p22,0,90,0,0,0,0
+ 9,0,l,pr,jbd2/mmcblk0p23,0,1150,0,0,0,0 9,0,l,pr,MC_Thread,0,1270,0,0,0,0
+ 9,0,l,pr,adbd,10,40,0,0,0,0 9,0,l,pr,lmkd,360,990,0,0,0,0
+ 9,0,l,pr,logd,1550,1670,0,0,0,0 9,0,l,pr,netd,80,330,0,0,0,0
+ 9,0,l,pr,rild,160,0,0,0,0,0 9,0,l,pr,vold,50,100,0,0,0,0
+ 9,0,l,pr,/init,0,70,0,0,0,0 9,0,l,pr,mpdecision,1400,7820,0,0,0,0
+ 9,0,l,pr,khubd,0,10,0,0,0,0 9,0,l,pr,kthreadd,0,600,0,0,0,0
+ 9,0,l,pr,kworker/0:0,0,3520,0,0,0,0 9,0,l,pr,sensors.qcom,380,720,0,0,0,0
+ 9,0,l,pr,healthd,20,190,0,0,0,0 9,0,l,pr,thermald,60,360,0,0,0,0
+ 9,0,l,pr,mmcqd/0,0,8700,0,0,0,0 9,0,l,pr,qseecomd,0,90,0,0,0,0
+ 9,0,l,pr,ksoftirqd/0,0,420,0,0,0,0 9,0,l,pr,wpa_supplicant,170,160,0,0,0,0
+ 9,0,l,pr,migration/0,0,1630,0,0,0,0 9,0,l,pr,migration/1,20,0,0,0,0,0
+ 9,0,l,pr,RX_Thread,0,790,0,0,0,0 9,0,l,pr,netmgrd,40,20,0,0,0,0
+ 9,1000,l,nt,0,0,11054,11216,0,0,26,29,0,0 9,1000,l,ua,2,0,0
+ 9,1000,l,sr,5,6813,1 9,1000,l,wl,*alarm*,0,f,0,23856,p,151,0,w,0
+ 9,1000,l,st,8548446,8548446,8548446 9,1000,l,pr,system,83310,35060,0,0,0,0
+ 9,1000,l,pr,surfaceflinger,6620,9330,0,0,0,0 9,1000,l,pr,ks,0,60,0,0,0,0
+ 9,1000,l,pr,qcks,0,90,0,0,0,0 9,1000,l,pr,efsks,0,50,0,0,0,0
+ 9,1000,l,pr,com.android.server.telecom,110,100,0,0,0,0
+ 9,1000,l,pr,servicemanager,40,110,0,0,0,0
+ 9,1001,l,st,8548446,8548446,8548446 9,1001,l,pr,qmuxd,0,30,0,0,0,0
+ 9,1001,l,pr,com.android.phone,450,300,0,0,0,0
+ 9,1014,l,nt,0,0,3410,3370,0,0,10,10,0,0 9,1027,l,st,8548446,8548446,8548446
+ 9,1027,l,pr,com.android.nfc,250,160,0,0,0,0
+ 9,10002,l,apk,15,com.android.providers.calendar,com.android.providers.calendar.CalendarProviderIntentService,2383,15,15
+ 9,10005,l,nt,0,0,1241,2488,0,0,6,10,0,0
+ 9,10009,l,nt,0,0,232255,258511,0,0,472,600,0,0
+ 9,10009,l,wfl,7689000,9814000,0
+ 9,10009,l,jb,com.google.android.gms/.gcm.nts.TaskExecutionService,81,3
+ 9,10009,l,sr,0,43643,46 9,10025,l,nt,0,0,152461,42850,0,0,267,243,0,0
+ 9,10025,l,wfl,1593000,629000,0 9,10034,l,nt,0,0,77657,40093,0,0,172,170,0,0
+ 9,10068,l,nt,0,0,11929,8383,0,0,50,47,0,0
+ 9,10069,l,nt,0,0,41553,22886,0,0,85,91,0,0</pre>
+
+ <h2 id="interpreting_the_output">Interpreting the output</h2>
+
+ <p>The sample output is in CSV format. Each line in the output contains
+ statistics related to battery usage.</p>
+
+ <p>The first four values in each line correspond to the following:</p>
+
+ <ul>
+ <li>Dummy integer</li>
+
+ <li>UID</li>
+
+ <li>Aggregation mode
+
+ <ul>
+ <li>"l" for --charged, means usage since last charge.</li>
+ <li>"u" for --unplugged, which means usage since last unplugged.</li>
+ <li>"i" for information that is not
+ tied to charged/uncharged status.</li>
+ </ul>
+ </li>
+
+ <li>Section identifier, which determines how to interpret the fifth
+ value and the following ones in the line.</li>
+ </ul>
+
+ <p>Currently, there are 41 sections and the interpretation for each section
+ is shown in the following table:</p>
+
+ <table>
+ <tr>
+ <td>
+ <p><strong>Order</strong></p>
+ </td>
+
+ <td class="tab0">
+ <p><strong>Section Identifier</strong></p>
+ </td>
+
+ <td class="tab0">
+ <p><strong>Description</strong></p>
+ </td>
+
+ <td class="tab0">
+ <p><strong>Remaining Fields</strong></p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>1</p>
+ </td>
+
+ <td class="tab0">
+ <p>vers</p>
+ </td>
+
+ <td class="tab0">
+ <p>Version</p>
+ </td>
+
+ <td class="tab0">
+ <p>checkin version, parcel version, start platform version, end
+ platform version</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>2</p>
+ </td>
+
+ <td class="tab0">
+ <p>uid</p>
+ </td>
+
+ <td class="tab0">
+ <p>UID</p>
+ </td>
+
+ <td class="tab0">
+ <p>uid, package name</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>3</p>
+ </td>
+
+ <td class="tab0">
+ <p>apk</p>
+ </td>
+
+ <td class="tab0">
+ <p>APK</p>
+ </td>
+
+ <td class="tab0">
+ <p>wakeups, APK, service, start time, starts, launches</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>4</p>
+ </td>
+
+ <td class="tab0">
+ <p>pr</p>
+ </td>
+
+ <td class="tab0">
+ <p>Process</p>
+ </td>
+
+ <td class="tab0">
+ <p>process, user, system, foreground, starts</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>5</p>
+ </td>
+
+ <td class="tab0">
+ <p>sr</p>
+ </td>
+
+ <td class="tab0">
+ <p>Sensor</p>
+ </td>
+
+ <td class="tab0">
+ <p>sensor number, time, count</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>6</p>
+ </td>
+
+ <td class="tab0">
+ <p>vib</p>
+ </td>
+
+ <td class="tab0">
+ <p>Vibrator</p>
+ </td>
+
+ <td class="tab0">
+ <p>time, count</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>7</p>
+ </td>
+
+ <td class="tab0">
+ <p>fg</p>
+ </td>
+
+ <td class="tab0">
+ <p>Foreground</p>
+ </td>
+
+ <td class="tab0">
+ <p>time, count</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>8</p>
+ </td>
+
+ <td class="tab0">
+ <p>st</p>
+ </td>
+
+ <td class="tab0">
+ <p>State Time</p>
+ </td>
+
+ <td class="tab0">
+ <p>foreground, active, running</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>9</p>
+ </td>
+
+ <td class="tab0">
+ <p>wl</p>
+ </td>
+
+ <td class="tab0">
+ <p>Wake lock</p>
+ </td>
+
+ <td class="tab0">
+ <p>wake lock, full time, 'f', full count, partial time, 'p', partial
+ count, window time, 'w', window count</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>10</p>
+ </td>
+
+ <td class="tab0">
+ <p>sy</p>
+ </td>
+
+ <td class="tab0">
+ <p>Sync</p>
+ </td>
+
+ <td class="tab0">
+ <p>sync, time, count</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>11</p>
+ </td>
+
+ <td class="tab0">
+ <p>jb</p>
+ </td>
+
+ <td class="tab0">
+ <p>Job</p>
+ </td>
+
+ <td class="tab0">
+ <p>job, time, count</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>12</p>
+ </td>
+
+ <td class="tab0">
+ <p>kwl</p>
+ </td>
+
+ <td class="tab0">
+ <p>Kernel Wake Lock</p>
+ </td>
+
+ <td class="tab0">
+ <p>kernel wake lock, time, count</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>13</p>
+ </td>
+
+ <td class="tab0">
+ <p>wr</p>
+ </td>
+
+ <td class="tab0">
+ <p>Wakeup Reason</p>
+ </td>
+
+ <td class="tab0">
+ <p>wakeup reason, time, count</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>14</p>
+ </td>
+
+ <td class="tab0">
+ <p>nt</p>
+ </td>
+
+ <td class="tab0">
+ <p>Network</p>
+ </td>
+
+ <td class="tab0">
+ <p>mobile bytes RX, mobile bytes TX, Wi-Fi bytes RX, Wi-Fi bytes TX,
+ mobile packets RX, mobile packets TX, Wi-Fi packets RX, Wi-Fi packets
+ TX, mobile active time, mobile active count</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>15</p>
+ </td>
+
+ <td class="tab0">
+ <p>ua</p>
+ </td>
+
+ <td class="tab0">
+ <p>User Activity</p>
+ </td>
+
+ <td class="tab0">
+ <p>other, button, touch</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>16</p>
+ </td>
+
+ <td class="tab0">
+ <p>bt</p>
+ </td>
+
+ <td class="tab0">
+ <p>Battery</p>
+ </td>
+
+ <td class="tab0">
+ <p>start count, battery realtime, battery uptime, total realtime,
+ total uptime, start clock time, battery screen off realtime, battery
+ screen off uptime</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>17</p>
+ </td>
+
+ <td class="tab0">
+ <p>dc</p>
+ </td>
+
+ <td class="tab0">
+ <p>Battery Discharge</p>
+ </td>
+
+ <td class="tab0">
+ <p>low, high, screen on, screen off</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>18</p>
+ </td>
+
+ <td class="tab0">
+ <p>lv</p>
+ </td>
+
+ <td class="tab0">
+ <p>Battery Level</p>
+ </td>
+
+ <td class="tab0">
+ <p>start level, current level</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>19</p>
+ </td>
+
+ <td class="tab0">
+ <p>wfl</p>
+ </td>
+
+ <td class="tab0">
+ <p>Wi-Fi</p>
+ </td>
+
+ <td class="tab0">
+ <p>full Wi-Fi lock on time, Wi-Fi scan time, Wi-Fi running time</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>20</p>
+ </td>
+
+ <td class="tab0">
+ <p>m</p>
+ </td>
+
+ <td class="tab0">
+ <p>Misc</p>
+ </td>
+
+ <td class="tab0">
+ <p>screen on time, phone on time, Wi-Fi on time, Wi-Fi running time,
+ Bluetooth on time, mobile RX total bytes, mobile TX total bytes,
+ Wi-Fi RX total bytes, Wi-Fi TX total bytes, full wake lock time
+ total, partial wake lock time total, legacy input event count, mobile
+ radio active time, mobile radio active adjusted time, interactive
+ time, low-power mode enabled time</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>21</p>
+ </td>
+
+ <td class="tab0">
+ <p>gn</p>
+ </td>
+
+ <td class="tab0">
+ <p>Global Network</p>
+ </td>
+
+ <td class="tab0">
+ <p>mobile RX total bytes, mobile TX total bytes, Wi-Fi RX total
+ bytes, Wi-Fi TX total bytes, mobile RX total packets, mobile TX total
+ packets, Wi-Fi RX total packets, Wi-Fi TX total packets</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>22</p>
+ </td>
+
+ <td class="tab0">
+ <p>br</p>
+ </td>
+
+ <td class="tab0">
+ <p>Screen Brightness</p>
+ </td>
+
+ <td class="tab0">
+ <p>dark, dim, medium, light, bright</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>23</p>
+ </td>
+
+ <td class="tab0">
+ <p>sst</p>
+ </td>
+
+ <td class="tab0">
+ <p>Signal Scanning Time</p>
+ </td>
+
+ <td class="tab0">
+ <p>signal scanning time</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>24</p>
+ </td>
+
+ <td class="tab0">
+ <p>sgt</p>
+ </td>
+
+ <td class="tab0">
+ <p>Signal Strength Time</p>
+ </td>
+
+ <td class="tab0">
+ <p>none, poor, moderate, good, great</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>25</p>
+ </td>
+
+ <td class="tab0">
+ <p>sgc</p>
+ </td>
+
+ <td class="tab0">
+ <p>Signal Strength Count</p>
+ </td>
+
+ <td class="tab0">
+ <p>none, poor, moderate, good, great</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>26</p>
+ </td>
+
+ <td class="tab0">
+ <p>dct</p>
+ </td>
+
+ <td class="tab0">
+ <p>Data Connection Time</p>
+ </td>
+
+ <td class="tab0">
+ <p>none, GPRS, EDGE, UMTS, CDMA, EVDO_0, EVDO_A, 1xRTT, HSDPA, HSUPA,
+ HSPA, IDEN, EVDO_B, LTE, EHRPD, HSPAP, other</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>27</p>
+ </td>
+
+ <td class="tab0">
+ <p>dcc</p>
+ </td>
+
+ <td class="tab0">
+ <p>Data Connection Count</p>
+ </td>
+
+ <td class="tab0">
+ <p>none, GPRS, EDGE, UMTS, CDMA, EVDO_0, EVDO_A, 1xRTT, HSDPA, HSUPA,
+ HSPA, IDEN, EVDO_B, LTE, EHRPD, HSPAP, other</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>28</p>
+ </td>
+
+ <td class="tab0">
+ <p>wst</p>
+ </td>
+
+ <td class="tab0">
+ <p>Wi-Fi State Time</p>
+ </td>
+
+ <td class="tab0">
+ <p>off, off scanning, on no networks, on disconnected, on connected
+ STA, on connected P2P, on connected STA P2P, soft AP</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>29</p>
+ </td>
+
+ <td class="tab0">
+ <p>wsc</p>
+ </td>
+
+ <td class="tab0">
+ <p>Wi-Fi State Count</p>
+ </td>
+
+ <td class="tab0">
+ <p>off, off scanning, on no networks, on disconnected, on connected
+ STA, on connected P2P, on connected STA P2P, soft AP</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>30</p>
+ </td>
+
+ <td class="tab0">
+ <p>wsst</p>
+ </td>
+
+ <td class="tab0">
+ <p>Wi-Fi Supplicant State Time</p>
+ </td>
+
+ <td class="tab0">
+ <p>invalid, disconnected, interface disabled, inactive, scanning,
+ authenticating, associating, associated, four-way handshake, group
+ handshake, completed, dormant, uninitialized</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>31</p>
+ </td>
+
+ <td class="tab0">
+ <p>wssc</p>
+ </td>
+
+ <td class="tab0">
+ <p>Wi-Fi Supplicant State Count</p>
+ </td>
+
+ <td class="tab0">
+ <p>invalid, disconnected, interface disabled, inactive, scanning,
+ authenticating, associating, associated, four-way handshake, group
+ handshake, completed, dormant, uninitialized</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>32</p>
+ </td>
+
+ <td class="tab0">
+ <p>wsgt</p>
+ </td>
+
+ <td class="tab0">
+ <p>Wi-Fi Signal Strength Time</p>
+ </td>
+
+ <td class="tab0">
+ <p>none, poor, moderate, good, great</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>33</p>
+ </td>
+
+ <td class="tab0">
+ <p>wsgc</p>
+ </td>
+
+ <td class="tab0">
+ <p>Wi-Fi Signal Strength Count</p>
+ </td>
+
+ <td class="tab0">
+ <p>none, poor, moderate, good, great</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>34</p>
+ </td>
+
+ <td class="tab0">
+ <p>bst</p>
+ </td>
+
+ <td class="tab0">
+ <p>Bluetooth State Time</p>
+ </td>
+
+ <td class="tab0">
+ <p>inactive, low, med, high</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>35</p>
+ </td>
+
+ <td class="tab0">
+ <p>bsc</p>
+ </td>
+
+ <td class="tab0">
+ <p>Bluetooth State Count</p>
+ </td>
+
+ <td class="tab0">
+ <p>inactive, low, med, high</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>36</p>
+ </td>
+
+ <td class="tab0">
+ <p>pws</p>
+ </td>
+
+ <td class="tab0">
+ <p>Power Use Summary</p>
+ </td>
+
+ <td class="tab0">
+ <p>battery capacity, computed power, minimum drained power, maximum
+ drained power</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>37</p>
+ </td>
+
+ <td class="tab0">
+ <p>pwi</p>
+ </td>
+
+ <td class="tab0">
+ <p>Power Use Item</p>
+ </td>
+
+ <td class="tab0">
+ <p>label, mAh</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>38</p>
+ </td>
+
+ <td class="tab0">
+ <p>dsd</p>
+ </td>
+
+ <td class="tab0">
+ <p>Discharge Step</p>
+ </td>
+
+ <td class="tab0">
+ <p>duration, level, screen, power-save</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>39</p>
+ </td>
+
+ <td class="tab0">
+ <p>csd</p>
+ </td>
+
+ <td class="tab0">
+ <p>Charge Step</p>
+ </td>
+
+ <td class="tab0">
+ <p>duration, level, screen, power-save</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>40</p>
+ </td>
+
+ <td class="tab0">
+ <p>dtr</p>
+ </td>
+
+ <td class="tab0">
+ <p>Discharge Time Remaining</p>
+ </td>
+
+ <td class="tab0">
+ <p>battery time remaining</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <p>41</p>
+ </td>
+
+ <td class="tab0">
+ <p>ctr</p>
+ </td>
+
+ <td class="tab0">
+ <p>Charge Time Remaining</p>
+ </td>
+
+ <td class="tab0">
+ <p>charge time remaining</p>
+ </td>
+ </tr>
+ </table>
diff --git a/src/devices/tech/power/index.jd b/src/devices/tech/power/index.jd
new file mode 100644
index 0000000..c3a6a9a
--- /dev/null
+++ b/src/devices/tech/power/index.jd
@@ -0,0 +1,766 @@
+page.title=Power Profiles for Android
+@jd:body
+
+<!--
+ Copyright 2015 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.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc"></ol>
+ </div>
+</div>
+
+<p>Battery usage information is derived from battery usage statistics and power profile values.</p>
+
+<h2 id="usage-statistics">Battery Usage Statistics</h2>
+
+<p>The framework automatically determines battery usage statistics by tracking how long device
+components spend in different states. As components (Wi-Fi chipset, cellular radio, Bluetooth, GPS,
+display, CPU) change states (OFF/ON, idle/full power, low/high brightness, etc.), the controlling
+service reports to the framework BatteryStats service. BatteryStats collects information over time and
+stores it for use across reboots. The service doesn’t track battery current draw directly,
+but instead collects timing information that can be used to approximate battery
+consumption by different components.</p>
+
+<p>The framework gathers statistics using the following methods:</p>
+
+<ul>
+<li><strong>Push</strong>. Services aware of component changes push state changes to the
+BatteryStats service.</li>
+<li><strong>Pull</strong>. For components such as the CPU usage by apps, the framework automatically
+pulls the data at transition points (such as starting or stopping an activity) to take a
+snapshot.</li>
+</ul>
+
+<p>Resource consumption is associated with the application using the resource. When multiple
+applications simultaneously use a resource (such as wakelocks that prevent the system from
+suspending), the framework spreads consumption across those applications, although not necessarily
+equally.</p>
+
+<p>To avoid losing usage statistics for a shutdown event, which may indicate battery power
+consumption problems (i.e. shutdown occurs because the battery reached zero remaining capacity), the
+framework flashes statistics approximately every 30 minutes.</p>
+
+<p>Battery usage statistics are handled entirely by the framework and do not require OEM
+modifications.</p>
+
+<h2 id="profile-values">Power Profile Values</h2>
+
+<p class="caution"><strong>Caution:</strong> Device manufacturers must
+provide a component power profile that defines the current consumption value
+for the component and the approximate battery drain caused by the component
+over time. This profile is defined in <a
+href="https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/xml/power_profile.xml">platform/frameworks/base/core/res/res/xml/power_profile.xml</a>.
+See the <a href="#power-values">Power Values</a> table for guidance on these
+settings.</p>
+
+<p>Within a power profile, power consumption is specified in milliamps (mA) of
+current draw at a nominal voltage and can be a fractional value specified in microamps (uA). The
+value should be the mA consumed at the battery and not a value applicable to a power rail that does
+not correspond to current consumed from the battery.</p>
+
+<p>For example, a display power profile specifies the mA of current required to keep the display on
+at minimum brightness and at maximum brightness. To determine the power cost (i.e the battery
+drained by the display component) of keeping the display on, the framework tracks the time spent at
+each brightness level, then multiplies those time intervals by an interpolated display brightness
+cost.</p>
+
+<p>The framework also multiplies the CPU time for each application by the mA required to run the CPU
+at a specific speed. This calculation establishes a comparative ranking of how much battery an
+application consumes by executing CPU code (time as the foreground app and total time including
+background activity are reported separately).</p>
+
+<h2 id="component-power">Measuring Component Power</h2>
+
+<p>You can determine individual component power consumption by comparing the current drawn by the
+device when the component is in the desired state (on, active, scanning, etc.) and when the
+component is off. Measure the average instantaneous current drawn on the device at a
+nominal voltage using an external power monitor, such as a bench power supply or specialized
+battery-monitoring tools (such as Monsoon Solution Inc. Power Monitor and Power Tool software).</p>
+
+<p class="note">
+<strong>Note:</strong> Manufacturers often supply information about the current consumed by an
+individual component. Use this information if it accurately represents the current drawn from the
+device battery in practice. However, validate manufacturer-provided values before
+using those values in your device power profile.</p>
+
+<p>When measuring, ensure the device does not have a connection to an external charge source, such
+as a USB connection to a development host used when running Android Debug Bridge (adb). The device
+under test might draw current from the host, thus lowering measurements at the battery. Avoid USB
+On-The-Go (OTG) connections, as the OTG device might draw current from the device under test.</p>
+
+<p>Excluding the component being measured, the system should run at a constant level of power
+consumption to avoid inaccurate measurements caused by changes in other components. System
+activities that can introduce unwanted changes to power measurements include:</p>
+
+<ul>
+<li><strong>Cellular, Wi-Fi, and Bluetooth receive, transmit, or scanning activity</strong>. When
+not measuring cell radio power, set the device to airplane mode and enable Wi-Fi or Bluetooth as
+appropriate.</li>
+<li><strong>Screen on/off</strong>. Colors displayed while the screen is on can affect power draw on
+some screen technologies. Turn the screen off when measuring values for non-screen components.</li>
+<li><strong>System suspend/resume</strong>. A screen off state can trigger a system suspension,
+placing parts of the device in a low-power or off state. This can affect power consumption of the
+component being measured and introduce large variances in power readings as the system periodically
+resumes to send alarms, etc. For details, see <a href="#control-suspend">Controlling System
+Suspend</a>.</li>
+<li><strong>CPUs changing speed and entering/exiting low-power scheduler idle state</strong>. During
+normal operation, the system makes frequent adjustments to CPU speeds, the number of online CPU
+cores, and other system core states such as memory bus speed and voltages of power rails associated
+with CPUs and memory. During testing, these adjustments affect power measurements:
+
+<ul>
+<li>CPU speed scaling operations can reduce the amount of clock and voltage scaling of memory buses
+and other system core components.</li>
+<li>Scheduling activity can affect the percentage of the time CPUs spend in low-power idle states.
+For details on preventing these adjustments from occurring during testing, see
+<a href="#control-cpu">Controlling CPU Speeds</a>.</li>
+</ul>
+
+</li>
+</ul>
+
+<p>For example, Joe Droid wants to compute the <code>screen.on</code> value for a device. He enables
+airplane mode on the device, runs the device at a stable current state, holds the CPU speed constant
+, and uses a partial wakelock to prevent system suspend. Joe then turns the device screen off and
+takes a measurement (200mA). Next, Joe turns the device screen on at minimum brightness and takes
+another measurement (300mA). The <code>screen.on</code> value is 100mA (300 - 200).</p>
+
+<p>For components that don’t have a flat waveform of current consumption when active (such as
+cellular radio or Wi-Fi), measure the average current over time using a power monitoring tool.</p>
+
+<p>When using an external power source in place of the device battery, the system might experience
+problems due to an unconnected battery thermistor or integrated fuel gauge pins (i.e. an invalid
+reading for battery temperature or remaining battery capacity could shut down the kernel or Android
+system). Fake batteries can provide signals on thermistor or fuel gauge pins that mimic temperature
+and state of charge readings for a normal system, and may also provide convenient leads for
+connecting to external power supplies. Alternatively, you can modify the system to ignore the
+invalid data from the missing battery.</p>
+
+<h3 id="control-suspend">Controlling System Suspend</h3>
+
+<p>This section describes how to avoid system suspend state when you don’t want it to interfere with
+other measurements, and how to measure the power draw of system suspend state when you do want to
+measure it.</p>
+
+<h4>Preventing System Suspend</h4>
+
+<p>System suspend can introduce unwanted variance in power measurements and place system components
+in low-power states inappropriate for measuring active power use. To prevent the system from
+suspending while the screen is off, use a temporary partial wakelock. Using a USB cable, connect the
+device to a development host, then issue the following command:</p>
+
+<pre>
+$ adb shell "echo temporary > /sys/power/wake_lock"
+</pre>
+
+<p>While in wake_lock, the screen off state does not trigger a system suspend. (Remember to
+disconnect the USB cable from the device before measuring power consumption.)</p>
+
+<p>To remove the wakelock:</p>
+
+<pre>
+$ adb shell "echo temporary > /sys/power/wake_unlock"
+</pre>
+
+<h4>Measuring System Suspend</h4>
+
+<p>To measure the power draw during the system suspend state, measure the value of cpu.idle in the
+power profile. Before measuring:
+
+<ul>
+<li>Remove existing wakelocks (as described above).</li>
+<li>Place the device in airplane mode to avoid concurrent activity by the cellular radio, which
+might run on a processor separate from the SoC portions controlled by the system suspend.</li>
+<li>Ensure the system is in suspend state by:
+<ul>
+<li>Confirming current readings settle to a steady value. Readings should be within the expected
+range for the power consumption of the SoC suspend state plus the power consumption of system
+components that remain powered (such as the USB PHY).</li>
+<li>Checking the system console output.</li>
+<li>Watching for external indications of system status (such as an LED turning off when not in
+suspend).</li>
+</ul>
+</li>
+</ul>
+
+<h3 id="control-cpu">Controlling CPU Speeds</h3>
+
+<p>Active CPUs can be brought online or put offline, have their clock speeds and associated voltages
+changed (possibly also affecting memory bus speeds and other system core power states), and
+can enter lower power idle states while in the kernel idle loop. When measuring different CPU power
+states for the power profile, avoid the power draw variance when measuring other parameters. The
+power profile assumes all CPUs have the same available speeds and power characteristics.</p>
+
+<p>While measuring CPU power, or while holding CPU power constant to make other measurements, keep
+the number of CPUs brought online constant (such as having one CPU online and the rest
+offline/hotplugged out). Keeping all CPUs except one in scheduling idle may product acceptable
+results. Stopping the Android framework with <code>adb shell stop</code> can reduce system
+scheduling activity.</p>
+
+<p>You must specify the available CPU speeds for your device in the power profile cpu.speeds
+entry. To get a list of available CPU speeds, run:</p>
+
+<pre>
+adb shell cat /sys/devices/system/cpu/cpu0/cpufreq/stats/time_in_state
+</pre>
+
+<p>These speeds match the corresponding power measurements in value <code>cpu.active</code>.</p>
+
+<p>For platforms where number of cores brought online significantly affects power consumption, you
+might need to modify the cpufreq driver or governor for the platform. Most platforms support
+controlling CPU speed using the “userspace” cpufreq governor and using sysfs interfaces to
+set the speed. For example, to set speed for 200MHz on a system with only 1 CPU or all CPUs sharing
+a common cpufreq policy, use the system console or adb shell to run the following commands:</p>
+
+<pre>
+echo userspace > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor
+echo 200000 > /sys/devices/system/cpu/cpu0/cpufreq/scaling_max_freq
+echo 200000 > /sys/devices/system/cpu/cpu0/cpufreq/scaling_min_freq
+echo 200000 > /sys/devices/system/cpu/cpu0/cpufreq/scaling_setspeed
+cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq
+</pre>
+
+<p class="note">
+<strong>Note</strong>: The exact commands differ depending on the platform cpufreq implementation.
+</p>
+
+<p>These commands ensure the new speed is not outside the allowed bounds, set the new speed, then
+print the speed at which the CPU is actually running (for verification). If the current
+minimum speed prior to execution is higher than 200000, you might need to reverse the order
+of the first two lines, or execute the first line again to drop the minimum speed prior to
+setting the maximum speed.</p>
+
+<p>To measure current consumed by a CPU running at various speeds, use the system console place the
+CPU in a CPU-bound loop using the command:</p>
+<pre>
+# while true; do true; done
+</pre>
+
+<p>Take the measurement while the loop executes.</p>
+
+<p>Some devices can limit maximum CPU speed while performing thermal throttling due to a high
+temperature measurement (i.e. after running CPUs at high speeds for sustained periods). Watch for
+such limiting, either using the system console output when taking measurements or by checking the
+kernel log after measuring.</p>
+
+<p>For the <code>cpu.awake</code> value, measure the power consumed when the system is not in
+suspend and not executing tasks. The CPU should be in a low-power scheduler <em>idle loop
+</em>, possibly executing an ARM Wait For Event instruction or in an SoC-specific low-power state
+with a fast-exit latency suitable for idle use.</p>
+
+<p>For the <code>cpu.active</code> value, power needs to be measured when the
+system is not in suspend mode and not executing tasks. One of the CPU (usually
+the primary CPU) should be running the task, and all the other CPUs should be in
+an idle state.</p>
+
+<h3 id="screen-power">Measuring Screen Power</h3>
+
+<p>When measuring screen on power, ensure that other devices normally turned on when the screen is
+enabled are also on. For example, if the touchscreen and display backlight would normally be on when
+the screen is on, ensure these devices are on when you measure to get a realistic example of screen
+on power usage.</p>
+
+<p>Some display technologies vary in power consumption according to the colors displayed, causing
+power measurements to vary considerably depending on what is displayed on the screen at the time of
+measurement. When measuring, ensure the screen is displaying something that has power
+characteristics of a realistic screen. Aim between the extremes of an all-black screen (which
+consumes the lowest power for some technologies) and an all-white screen. A common choice is a view
+of a schedule in the calendar app, which has a mix of white background and non-white elements.</p>
+
+<p>Measure screen on power at <em>minimum</em> and <em>maximum</em> display/backlight brightness.
+To set minimum brightness:</p>
+
+<ul>
+<li><strong>Use the Android UI</strong> (not recommended). Set the Settings > Display Brightness
+slider to the minimum display brightness. However, the Android UI allows setting brightness only to
+a minimum of 10-20% of the possible panel/backlight brightness, and does not allow setting
+brightness so low that the screen might not be visible without great effort.</li>
+<li><strong>Use a sysfs file</strong> (recommended). If available, use a sysfs file to control panel
+brightness all the way down to the minimum brightness supported by the hardware.</li>
+</ul>
+
+<p>Additionally, if the platform sysfs file enables turning the LCD panel, backlight, and
+touchscreen on and off, use the file to take measurements with the screen on and off. Otherwise,
+set a partial wakelock so the system does not suspend, then turn on and off the
+screen with the power button.</p>
+
+<h3 id="wifi-power">Measuring Wi-Fi Power</h3>
+
+<p>Perform Wi-Fi measurements on a relatively quiet network. Avoid introducing additional work
+processing high volumes of broadcast traffic that is unrelated to the activity being measured.</p>
+
+<p>The <code>wifi.on</code> value measures the power consumed when Wi-Fi is enabled but not actively
+transmitting or receiving. This is often measured as the delta between the current draw in
+system suspend (sleep) state with Wi-Fi enabled vs. disabled.</p>
+
+<p>The <code>wifi.scan</code> value measures the power consumed during a Wi-Fi scan for access
+points. Applications can trigger Wi-Fi scans using the WifiManager class
+<a href ="http://developer.android.com/reference/android/net/wifi/WifiManager.html">
+<code>startScan()</code>API</a>. You can also open Settings > Wi-Fi, which performs access point
+scans every few seconds with an apparent jump in power consumption, but you must subtract screen
+power from these measurements.</p>
+
+<p class="note">
+<strong>Note</strong>: Use a controlled setup (such as
+<a href="http://en.wikipedia.org/wiki/Iperf">iperf</a>) to generate network receive and transmit
+traffic.</p>
+
+<h2 id="device-power">Measuring Device Power</h2>
+
+<p>You can determine device power consumption for Android devices that include a battery fuel gauge
+such as a Summit SMB347 or Maxim MAX17050 (available on many Nexus devices). Use the in-system
+battery fuel gauge when external measurement equipment is not available or is inconvenient to
+connect to a device (such as in mobile usage).</p>
+
+<p>Measurements can include instantaneous current, remaining charge, battery capacity at test start
+and end, and more depending on the supported properties of the device (see below). For best results,
+perform device power measurements during long-running A/B tests that use the same device type with
+the same fuel gauge and same current sense resistor. Ensure the starting battery charge is the same
+for each device to avoid differing fuel gauge behavior at different points in the battery discharge
+curve.</p>
+
+<p>Even with identical test environments, measurements are not guaranteed to be of high absolute
+accuracy. However, most inaccuracies specific to the fuel gauge and sense resistor are consistent
+between test runs, making comparisons between identical devices useful. We recommend running
+multiple tests in different configurations to identify significant differences and relative power
+consumption between configurations.</p>
+
+<h3 id="power-consumption">Reading Power Consumption</h3>
+
+<p>To read power consumption data, insert calls to the API in your testing code.</p>
+
+<pre>
+import android.os.BatteryManager;
+import android.os.ServiceManager;
+import android.content.Context;
+BatteryManager mBatteryManager =
+(BatteryManager)Context.getSystemService(Context.BATTERY_SERVICE);
+Long energy =
+mBatteryManager.getLongProperty(BatteryManager.BATTERY_PROPERTY_ENERGY_COUNTER);
+Slog.i(TAG, "Remaining energy = " + energy + "nWh");
+</pre>
+
+<h3 id="avail-props">Available Properties</h3>
+
+<p>Android supports the following battery fuel gauge properties:</p>
+
+<pre>
+BATTERY_PROPERTY_CHARGE_COUNTER Remaining battery capacity in microampere-hours
+BATTERY_PROPERTY_CURRENT_NOW Instantaneous battery current in microamperes
+BATTERY_PROPERTY_CURRENT_AVERAGE Average battery current in microamperes
+BATTERY_PROPERTY_CAPACITY Remaining battery capacity as an integer percentage
+BATTERY_PROPERTY_ENERGY_COUNTER Remaining energy in nanowatt-hours
+</pre>
+
+<p>Most properties are read from kernel power_supply subsystem attributes of similar names.
+However, the exact properties, resolution of property values, and update frequency
+available for a specific device depend on:</p>
+
+<ul>
+<li>Fuel gauge hardware, such as a Summit SMB347 or Maxim MAX17050.</li>
+<li>Fuel gauge-to-system connection, such as the value of external current sense resistors.</li>
+<li>Fuel gauge chip software configuration, such as values chosen for average current computation
+intervals in the kernel driver.</li>
+</ul>
+
+<p>For details, see the properties available for <a href="#nexus-devices">Nexus devices</a>.</p>
+
+<h3 id="maxim-fuel">Maxim Fuel Gauge</h3>
+
+<p>When determining battery state-of-charge over a long period of time, the Maxim fuel gauge
+(MAX17050, BC15) corrects for coulomb-counter offset measurements. For measurements made over a
+short period of time (such as power consumption metering tests), the fuel gauge does not make
+corrections, making the offset the primary source of error when current measurements are too small
+(although no amount of time can eliminate the offset error completely).</p>
+
+<p>For a typical 10mOhm sense resistor design, the offset current should be better than 1.5mA,
+meaning any measurement is +/-1.5mA (PCBoard layout can also affect this variation). For example,
+when measuring a large current (200mA) you can expect the following:</p>
+
+<ul>
+<li>2mA (1% gain error of 200mA due to fuel gauge gain error)</li>
+<li>+2mA (1% gain error of 200mA due to sense resistor error)</li>
+<li>+1.5mA (current sense offset error from fuel gauge)</li>
+</ul>
+
+<p>The total error is 5.5mA (2.75%). Compare this to a medium current (50mA) where the same error
+percentages give a total error of 7% or to a small current (15mA) where +/-1.5mA gives a total error
+of 10%.</p>
+
+<p>For best results, we recommend measuring greater than 20mA. Gain measurement errors are
+systematic and repeatable, enabling you to test a device in multiple modes and get clean relative
+measurements (with exceptions for the 1.5mA offset).</p>
+
+<p>For +/-100uA relative measurements, required measurement time depends on:</p>
+
+<ul>
+<li><b>ADC sampling noise</b>. The MAX17050 with its normal factory configuration produces +/-1.5mA
+sample-to-sample variation due to noise, with each sample delivered at 175.8ms. You can expect a
+rough +/-100uA for a 1 minute test window and a clean 3-sigma noise less than 100uA (or 1-sigma
+noise at 33uA) for a 6 minute test window.</li>
+<li><b>Sample Aliasing because of load variation</b>. Variation exaggerates errors, so for samples
+with variation inherent in the loading, consider using a longer test window.</li>
+</ul>
+
+<h3 id="nexus-devices">Supported Nexus Devices</h3>
+
+<h5 id="nexus-5">Nexus 5</h5>
+
+<table>
+<tbody>
+<tr>
+<th>Model</th>
+<td>Nexus 5</td>
+</tr>
+<tr>
+<th>Fuel Gauge</th>
+<td>Maxim MAX17048 fuel gauge (ModelGauge™, no coulomb counter)</td>
+</tr>
+<tr>
+<th>Properties</th>
+<td>BATTERY_PROPERTY_CAPACITY</td>
+</tr>
+<tr>
+<th>Measurements</th>
+<td>The fuel gauge does not support any measurements other than battery State Of Charge to a
+resolution of %/256 (1/256th of a percent of full battery capacity).</td>
+</tr>
+</tbody>
+</table>
+
+
+<h5 id="nexus-6">Nexus 6</h5>
+
+<table>
+<tbody>
+<tr>
+<th>Model</th>
+<td>Nexus 6</td>
+</tr>
+<tr>
+<th>Fuel Gauge</th>
+<td>Maxim MAX17050 fuel gauge (a coulomb counter with Maxim ModelGauge™ adjustments), and a 10mohm
+current sense resistor.</td>
+</tr>
+<tr>
+<th>Properties</th>
+<td>BATTERY_PROPERTY_CAPACITY<br>
+BATTERY_PROPERTY_CURRENT_NOW<br>
+BATTERY_PROPERTY_CURRENT_AVERAGE<br>
+BATTERY_PROPERTY_CHARGE_COUNTER<br>
+BATTERY_PROPERTY_ENERGY_COUNTER</td>
+</tr>
+<tr>
+<th>Measurements</th>
+<td>CURRENT_NOW resolution 156.25uA, update period is 175.8ms.<br>
+CURRENT_AVERAGE resolution 156.25uA, update period configurable 0.7s - 6.4h, default 11.25 secs.<br>
+CHARGE_COUNTER (accumulated current, non-extended precision) resolution is 500uAh (raw coulomb
+counter read, not adjusted by fuel gauge for coulomb counter offset, plus inputs from the ModelGauge
+m3 algorithm including empty compensation).<br>
+CHARGE_COUNTER_EXT (extended precision in kernel) resolution 8nAh.<br>
+ENERGY_COUNTER is CHARGE_COUNTER_EXT at nominal voltage of 3.7V.</td>
+</tr>
+</tbody>
+</table>
+
+
+<h5 id="nexus-9">Nexus 9</h5>
+
+<table>
+<tbody>
+<tr>
+<th>Model</th>
+<td>Nexus 9</td>
+</tr>
+<tr>
+<th>Fuel Gauge</th>
+<td>Maxim MAX17050 fuel gauge (a coulomb counter with Maxim ModelGauge™ adjustments), and a 10mohm
+current sense resistor.</td>
+</tr>
+<tr>
+<th>Properties</th>
+<td>BATTERY_PROPERTY_CAPACITY<br>
+BATTERY_PROPERTY_CURRENT_NOW<br>
+BATTERY_PROPERTY_CURRENT_AVERAGE<br>
+BATTERY_PROPERTY_CHARGE_COUNTER<br>
+BATTERY_PROPERTY_ENERGY_COUNTER</td>
+</tr>
+<tr>
+<th>Measurements</th>
+<td>CURRENT_NOW resolution 156.25uA, update period is 175.8ms.<br>
+CURRENT_AVERAGE resolution 156.25uA, update period configurable 0.7s - 6.4h, default 11.25 secs.<br>
+CHARGE_COUNTER (accumulated current, non-extended precision) resolution is 500uAh.<br>
+CHARGE_COUNTER_EXT (extended precision in kernel) resolution 8nAh.<br>
+ENERGY_COUNTER is CHARGE_COUNTER_EXT at nominal voltage of 3.7V.<br>
+Accumulated current update period 175.8ms.<br>
+ADC sampled at 175ms quantization with a 4ms sample period. Can adjust duty cycle.</td>
+</tr>
+</tbody>
+</table>
+
+
+<h5 id="nexus-10">Nexus 10</h5>
+
+<table>
+<tbody>
+<tr>
+<th>Model</th>
+<td>Nexus 10</td>
+</tr>
+<tr>
+<th>Fuel Gauge</th>
+<td>Dallas Semiconductor DS2784 fuel gauge (a coulomb counter), with a 10mohm current sense
+resistor.</td>
+</tr>
+<tr>
+<th>Properties</th>
+<td>BATTERY_PROPERTY_CAPACITY<br>
+BATTERY_PROPERTY_CURRENT_NOW<br>
+BATTERY_PROPERTY_CURRENT_AVERAGE<br>
+BATTERY_PROPERTY_CHARGE_COUNTER<br>
+BATTERY_PROPERTY_ENERGY_COUNTER</td>
+</tr>
+<tr>
+<th>Measurements</th>
+<td>Current measurement (instantaneous and average) resolution is 156.3uA.<br>
+CURRENT_NOW instantaneous current update period is 3.5 seconds.<br>
+CURRENT_AVERAGE update period is 28 seconds (not configurable).<br>
+CHARGE_COUNTER (accumulated current, non-extended precision) resolution is 625uAh.<br>
+CHARGE_COUNTER_EXT (extended precision in kernel) resolution is 144nAh.<br>
+ENERGY_COUNTER is CHARGE_COUNTER_EXT at nominal voltage of 3.7V.<br>
+Update period for all is 3.5 seconds.</td>
+</tr>
+</tbody>
+</table>
+
+
+<h2 id="viewing-usage">Viewing Battery Usage Data</h2>
+
+See <a href="{@docRoot}devices/tech/power/batterystats.html">Viewing Battery Usage Data</a>.
+
+<h2 id="power-values">Power Values</h2>
+
+<p>Device manufacturers must provide a component power profile defined in
+<em><device></em>/frameworks/base/core/res/res/xml/power_profile.xml. To
+determine these values, use hardware that measures the power being used by
+the device and perform the various operations for which information is needed.
+Measure the power use during those operations and compute the values (deriving
+differences from other base-line power uses as appropriate).</p>
+
+<table>
+<tr>
+ <th>Name</th>
+ <th>Description</th>
+ <th>Example Value</th>
+ <th>Notes</th>
+</tr>
+<tr>
+ <td>none</td>
+ <td>Nothing</td>
+ <td>0</td>
+ <td></td>
+</tr>
+
+<tr>
+ <td>screen.on</td>
+ <td>Additional power used when screen is turned on at minimum brightness.</td>
+ <td>200mA</td>
+ <td>Includes touch controller and display backlight. At 0 brightness, not the Android minimum which tends to be 10 or 20%.</td>
+</tr>
+
+<tr>
+ <td>screen.full</td>
+ <td>Additional power used when screen is at maximum brightness, compared to screen at minimum brightness.</td>
+ <td>100mA-300mA</td>
+ <td>A fraction of this value (based on screen brightness) is added to the screen.on value to compute the power usage of the screen.</td>
+</tr>
+
+<tr>
+ <td>bluetooth.active</td>
+ <td>Additional power used when playing audio through bluetooth A2DP.</td>
+ <td>14mA</td>
+ <td></td>
+</tr>
+
+<tr>
+ <td>bluetooth.on</td>
+ <td>Additional power used when bluetooth is turned on but idle.</td>
+ <td>1.4mA</td>
+ <td></td>
+</tr>
+
+<tr>
+ <td>wifi.on</td>
+ <td>Additional power used when Wi-Fi is turned on but not receiving, transmitting, or scanning.</td>
+ <td>2mA</td>
+ <td></td>
+</tr>
+
+<tr>
+ <td>wifi.active</td>
+ <td>Additional power used when transmitting or receiving over Wi-Fi.</td>
+ <td>31mA</td>
+ <td></td>
+</tr>
+
+<tr>
+ <td>wifi.scan</td>
+ <td>Additional power used when Wi-Fi is scanning for access points.</td>
+ <td>100mA</td>
+ <td></td>
+</tr>
+
+<tr>
+ <td>dsp.audio</td>
+ <td>Additional power used when audio decoding/encoding via DSP.</td>
+ <td>14.1mA</td>
+ <td>Reserved for future use.</td>
+</tr>
+
+
+<tr>
+ <td>dsp.video</td>
+ <td>Additional power used when video decoding via DSP.</td>
+ <td>54mA</td>
+ <td>Reserved for future use.</td>
+</tr>
+
+<tr>
+ <td>gps.on</td>
+ <td>Additional power used when GPS is acquiring a signal.</td>
+ <td>50mA</td>
+ <td></td>
+</tr>
+
+<tr>
+ <td>radio.active</td>
+ <td>Additional power used when cellular radio is transmitting/receiving.</td>
+ <td>100mA-300mA</td>
+ <td></td>
+</tr>
+
+<tr>
+ <td>radio.scanning</td>
+ <td>Additional power used when cellular radio is paging the tower.</td>
+ <td>1.2mA</td>
+ <td></td>
+</tr>
+
+<tr>
+ <td>radio.on</td>
+ <td>Additional power used when the cellular radio is on. Multi-value entry, one per signal strength (no signal, weak, moderate, strong).</td>
+ <td>1.2mA</td>
+ <td>Some radios boost power when they search for a cell tower and do not detect a signal. These
+ numbers could all be the same or decreasing with increasing signal strength. If you provide only
+ one value, the same value will be used for all strengths. If you provide 2 values, the first will
+ be for no-signal and the second for all other strengths, and so on.</td>
+</tr>
+
+<tr>
+ <td>cpu.speeds</td>
+ <td>Multi-value entry that lists each possible CPU speed in KHz.</td>
+ <td>125000KHz, 250000KHz, 500000KHz, 1000000KHz, 1500000KHz</td>
+ <td>The number and order of entries must correspond to the mA entries in cpu.active.</td>
+</tr>
+
+<tr>
+ <td>cpu.idle</td>
+ <td>Total power drawn by the system when CPUs (and the SoC) are in system suspend state.</td>
+ <td>3mA</td>
+ <td></td>
+</tr>
+
+<tr>
+ <td>cpu.awake</td>
+ <td>Additional power used when CPUs are in scheduling idle state (kernel idle loop); system is not
+ in system suspend state.</td>
+ <td>50mA</td>
+ <td>Your platform might have more than one idle state in use with differing
+levels of power consumption; choose a representative idle state for longer
+periods of scheduler idle (several milliseconds). Examine the power graph on
+your measurement equipment and choose samples where the CPU is at its lowest
+consumption, discarding higher samples where the CPU exited idle.</td>
+</tr>
+
+<tr>
+ <td>cpu.active</td>
+ <td>Additional power used by CPUs when running at different speeds.</td>
+ <td>100mA, 120mA, 140mA, 160mA, 200mA</td>
+ <td>Set the max speed in the kernel to each of the allowed speeds and peg the CPU at that
+speed. The number of entries here correspond to the number of entries in cpu.speeds, in the
+same order.</td>
+</tr>
+
+<tr>
+ <td>battery.capacity</td>
+ <td>The total battery capacity in mAh.</td>
+ <td>3000mAh</td>
+ <td></td>
+</tr>
+
+</table>
+
+<h3 id="sample">Sample file</h3>
+
+<pre>
+<!-- Most values are the incremental current used by a feature, in mA (measured at
+nominal voltage). OEMs must measure and provide actual values before shipping a device.
+Example real-world values are given, but are dependent on the platform
+and can vary significantly, so should be measured on the shipping platform with a power meter.
+-->
+0
+200
+160
+10
+<!-- Bluetooth stereo audio playback 10.0 mA -->
+1.3
+0.5
+30
+100
+12
+50
+50
+75
+1.1
+<!-- Strength 0 to BINS-1 (4) -->
+1.1
+
+<!-- Different CPU speeds as reported in
+/sys/devices/system/cpu/cpu0/cpufreq/stats/time_in_state -->
+
+250000 <!-- 250 MHz -->
+500000 <!-- 500 MHz -->
+750000 <!-- 750 MHz -->
+1000000 <!-- 1 GHz -->
+1200000 <!-- 1.2 GHz -->
+
+<!-- Power consumption when CPU is idle -->
+3.0
+50.1
+<!-- Power consumption at different speeds -->
+
+100 <!-- 250 MHz -->
+120 <!-- 500 MHz -->
+140 <!-- 750 MHz -->
+155 <!-- 1 GHz -->
+175 <!-- 1.2 GHz -->
+
+<!-- This is the battery capacity in mAh -->
+3000
+<!-- Battery capacity is 3000 mAH (at 3.6 Volts) -->
+
+</pre>