diff options
Diffstat (limited to 'en/devices')
21 files changed, 829 insertions, 2618 deletions
diff --git a/en/devices/_toc-interfaces.yaml b/en/devices/_toc-interfaces.yaml index a4331e12..148c5630 100644 --- a/en/devices/_toc-interfaces.yaml +++ b/en/devices/_toc-interfaces.yaml @@ -1,41 +1,14 @@ toc: - title: Overview path: /devices/ -- title: Accessories - path: /devices/accessories +- title: Architecture section: - - title: Audio Accessories - section: - - title: Overview - path: /devices/accessories/audio - - title: Headset - section: - - title: Overview - path: /devices/accessories/headset/ - - title: 3.5 mm Headset Spec - path: /devices/accessories/headset/plug-headset-spec - - title: 3.5 mm Jack Spec - path: /devices/accessories/headset/jack-headset-spec - - title: USB Headset Spec - path: /devices/accessories/headset/usb-headset-spec - - title: Expected Behavior - path: /devices/accessories/headset/expected-behavior - - title: Testing - path: /devices/accessories/headset/testing - - title: Custom Accessories - section: - - title: Overview - path: /devices/accessories/custom - - title: AOA - section: - - title: Overview - path: /devices/accessories/protocol - - title: AOA 2.0 - path: /devices/accessories/aoa2 - - title: AOA 1.0 - path: /devices/accessories/aoa - - title: Stylus - path: /devices/accessories/stylus + - title: Overview + path: /devices/architecture/ + - title: Hardware Abstraction Layer (HAL) + path: /devices/architecture/hal + - title: Treble + path: /devices/architecture/treble - title: Audio section: - title: Overview @@ -95,7 +68,11 @@ toc: - title: TV Audio path: /devices/audio/tv - title: Automotive - path: /devices/automotive + section: + - title: Overview + path: /devices/automotive/ + - title: Vehicle Properties + path: /devices/automotive/properties - title: Bluetooth path: /devices/bluetooth - title: Camera @@ -206,6 +183,41 @@ toc: path: /devices/media/soc - title: OEM Dependencies path: /devices/media/oem +- title: Peripherals + path: /devices/accessories + section: + - title: Audio Accessories + section: + - title: Overview + path: /devices/accessories/audio + - title: Headset + section: + - title: Overview + path: /devices/accessories/headset/ + - title: 3.5 mm Headset Spec + path: /devices/accessories/headset/plug-headset-spec + - title: 3.5 mm Jack Spec + path: /devices/accessories/headset/jack-headset-spec + - title: USB Headset Spec + path: /devices/accessories/headset/usb-headset-spec + - title: Expected Behavior + path: /devices/accessories/headset/expected-behavior + - title: Testing + path: /devices/accessories/headset/testing + - title: Custom Accessories + section: + - title: Overview + path: /devices/accessories/custom + - title: AOA + section: + - title: Overview + path: /devices/accessories/protocol + - title: AOA 2.0 + path: /devices/accessories/aoa2 + - title: AOA 1.0 + path: /devices/accessories/aoa + - title: Stylus + path: /devices/accessories/stylus - title: Sensors section: - title: Overview diff --git a/en/devices/architecture/hal.html b/en/devices/architecture/hal.html new file mode 100644 index 00000000..17ccea71 --- /dev/null +++ b/en/devices/architecture/hal.html @@ -0,0 +1,140 @@ +<html devsite> + <head> + <title>Hardware Abstraction Layer (HAL)</title> + <meta name="project_path" value="/_project.yaml" /> + <meta name="book_path" value="/_book.yaml" /> + </head> + <body> + <!-- + Copyright 2017 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. + --> + + + +<p>A HAL defines a standard interface for hardware vendors to implement, +which enables Android to be agnostic about lower-level driver implementations. +Using a HAL allows you to implement functionality without affecting or modifying +the higher level system. HAL implementations are packaged into modules and +loaded by the Android system at the appropriate time.</p> + +<img src="../images/ape_fwk_hal.png"> + +<p class="img-caption"><strong>Figure 1.</strong> HAL components</p> + +<p>You must implement the corresponding HAL (and driver) for the specific +hardware your product provides. HAL implementations are typically built into +shared library modules (<code>.so</code> files), but as Android does not mandate +a standard interaction between a HAL implementation and device drivers, you can +do what is best for your situation. However, to enable the Android system to +correctly interact with your hardware, you <strong>must</strong> abide by the +contract defined in each hardware-specific HAL interface.</p> + +<p>To guarantee that HALs have a predictable structure, each hardware-specific +HAL interface has properties defined in +<code>hardware/libhardware/include/hardware/hardware.h</code>. This interface +allows the Android system to load correct versions of your HAL modules in a +consistent way. A HAL interface consists of two components: modules and devices. +</p> + +<h2 id="hal-module">HAL modules</h2> +<p>A module represents your packaged HAL implementation, which is stored as a +shared library (<code>.so file</code>). The +<code>hardware/libhardware/include/hardware/hardware.h</code> header file +defines a struct (<code>hw_module_t</code>) that represents a module and +contains metadata such as the version, name, and author of the module. Android +uses this metadata to find and load the HAL module correctly.</p> + +<p>In addition, the <code>hw_module_t</code> struct contains a pointer to +another struct, <code>hw_module_methods_t</code>, that contains a pointer to +an open function for the module. This open function is used to initiate +communication with the hardware for which the HAL is serving as an abstraction. +Each hardware-specific HAL usually extends the generic <code>hw_module_t</code> +struct with additional information for that specific piece of hardware. For +example, in the camera HAL, the <code>camera_module_t</code> struct contains a +<code>hw_module_t</code> struct along with other camera-specific function +pointers:</p> + +<pre class="devsite-click-to-copy"> +typedef struct camera_module { + hw_module_t common; + int (*get_number_of_cameras)(void); + int (*get_camera_info)(int camera_id, struct camera_info *info); +} camera_module_t; +</pre> + +<p>When you implement a HAL and create the module struct, you must name it +<code>HAL_MODULE_INFO_SYM</code>. Example from the Nexus 9 audio HAL:</p> + +<pre class="devsite-click-to-copy"> +struct audio_module HAL_MODULE_INFO_SYM = { + .common = { + .tag = HARDWARE_MODULE_TAG, + .module_api_version = AUDIO_MODULE_API_VERSION_0_1, + .hal_api_version = HARDWARE_HAL_API_VERSION, + .id = AUDIO_HARDWARE_MODULE_ID, + .name = "NVIDIA Tegra Audio HAL", + .author = "The Android Open Source Project", + .methods = &hal_module_methods, + }, +}; +</pre> + +<h2 id="hal-device">HAL devices</h2> +<p>A device abstracts the hardware of your product. For example, an audio +module can contain a primary audio device, a USB audio device, or a Bluetooth +A2DP audio device.</p> + +<p>A device is represented by the <code>hw_device_t</code> struct. Similar to a +module, each type of device defines a detailed version of the generic +<code>hw_device_t</code> that contains function pointers for specific features +of the hardware. For example, the <code>audio_hw_device_t</code> struct type +contains function pointers to audio device operations:</p> + +<pre class="devsite-click-to-copy"> +struct audio_hw_device { + struct hw_device_t common; + + /** + * used by audio flinger to enumerate what devices are supported by + * each audio_hw_device implementation. + * + * Return value is a bitmask of 1 or more values of audio_devices_t + */ + uint32_t (*get_supported_devices)(const struct audio_hw_device *dev); + ... +}; +typedef struct audio_hw_device audio_hw_device_t; +</pre> + +<p>In addition to these standard properties, each hardware-specific HAL +interface can define more of its own features and requirements. For details, +see the <a href="/reference/hal/">HAL reference documentation</a> as well as +the individual instructions for each HAL.</p> + +<h2 id="hal-building">Building HAL modules</h2> +<p>HAL implementations are built into modules (<code>.so</code>) files and are +dynamically linked by Android when appropriate. You can build your modules by +creating <code>Android.mk</code> files for each of your HAL implementations +and pointing to your source files. In general, your shared libraries must be +named in a specific format so they can be found and loaded properly. The naming +scheme varies slightly from module to module, but follows the general pattern +of: <code><module_type>.<device_name></code>. +</p> + +<p>For details on setting up the build for each HAL, see the HAL-specific +documentation through the Porting section of this website.</p> + + </body> +</html> diff --git a/en/devices/architecture/images/ape_fwk_hal.png b/en/devices/architecture/images/ape_fwk_hal.png Binary files differnew file mode 100644 index 00000000..0b931194 --- /dev/null +++ b/en/devices/architecture/images/ape_fwk_hal.png diff --git a/en/devices/architecture/images/treble_blog_after.png b/en/devices/architecture/images/treble_blog_after.png Binary files differnew file mode 100644 index 00000000..c82bc0a5 --- /dev/null +++ b/en/devices/architecture/images/treble_blog_after.png diff --git a/en/devices/architecture/images/treble_blog_before.png b/en/devices/architecture/images/treble_blog_before.png Binary files differnew file mode 100644 index 00000000..47affe2e --- /dev/null +++ b/en/devices/architecture/images/treble_blog_before.png diff --git a/en/devices/architecture/index.html b/en/devices/architecture/index.html new file mode 100644 index 00000000..a4a415e3 --- /dev/null +++ b/en/devices/architecture/index.html @@ -0,0 +1,79 @@ +<html devsite> + <head> + <title>Architecture</title> + <meta name="project_path" value="/_project.yaml" /> + <meta name="book_path" value="/_book.yaml" /> + </head> + <body> + <!-- + Copyright 2017 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. + --> + + + +<p> +Android system architecture contains the following components: +</p> + +<img src="../images/ape_fwk_all.png"> + +<p class="img-caption"><strong>Figure 1.</strong> Android system architecture</p> + +<h2 id="application-framework">Application framework</h2> + +<p>The application framework is used most often by application developers. As a +hardware developer, you should be aware of developer APIs as many map directly +to the underlying HAL interfaces and can provide helpful information about +implementing drivers.</p> + +<h2 id="binder-ipc">Binder IPC</h2> +<p>The Binder Inter-Process Communication (IPC) mechanism allows the application +framework to cross process boundaries and call into the Android system services +code. This enables high level framework APIs to interact with Android system +services. At the application framework level, this communication is hidden from +the developer and things appear to "just work".</p> + +<h2 id="system-services">System services</h2> +<p>System services are modular, focused components such as Window Manager, +Search Service, or Notification Manager. Functionality exposed by application +framework APIs communicates with system services to access the underlying +hardware. Android includes two groups of services: <em>system</em> (such as +Window Manager and Notification Manager) and <em>media</em> (services involved +in playing and recording media).</p> + +<h2 id="hal">Hardware abstraction layer (HAL)</h2> +<p>A HAL defines a standard interface for hardware vendors to implement, +which enables Android to be agnostic about lower-level driver implementations. +Using a HAL allows you to implement functionality without affecting or modifying +the higher level system. HAL implementations are packaged into modules and +loaded by the Android system at the appropriate time. For details, see +<a href="/devices/architecture/hal.html">Hardware Abstraction Layer (HAL)</a>. +</p> + +<h2 id="Linux-kernel">Linux kernel</h2> +<p>Developing your device drivers is similar to developing a typical Linux +device driver. Android uses a version of the Linux kernel with a few special +additions such as wake locks (a memory management system that is more aggressive +in preserving memory), the Binder IPC driver, and other features important for a +mobile embedded platform. These additions are primarily for system functionality +and do not affect driver development.</p> + +<p>You can use any version of the kernel as long as it supports the required +features (such as the binder driver). However, we recommend using the latest +version of the Android kernel. For details, see +<a href="/source/building-kernels.html">Building Kernels</a>.</p> + + </body> +</html> diff --git a/en/devices/architecture/treble.html b/en/devices/architecture/treble.html new file mode 100644 index 00000000..343858df --- /dev/null +++ b/en/devices/architecture/treble.html @@ -0,0 +1,73 @@ +<html devsite> + <head> + <title>Treble</title> + <meta name="project_path" value="/_project.yaml" /> + <meta name="book_path" value="/_book.yaml" /> + </head> + <body> + <!-- + Copyright 2017 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. + --> + + +<p>The upcoming Android O release includes Project Treble, a major re-architect +of the Android OS framework designed to make it easier, faster, and less costly +for manufacturers to update devices to a new version of Android.</p> + +<h2 id=about-treble>Android updates</h2> +<p>Project Treble separates the vendor implementation (device-specific, +lower-level software written by silicon manufacturers) from the Android OS +framework via a new vendor interface.</p> + +<p>In Android 7.x and earlier, no formal vendor interface exists so device +makers must update large portions of the Android code to move a device to a +newer version of Android:</p> + +<img src="images/treble_blog_before.png"> + +<p class="img-caption"><strong>Figure 1.</strong> Pre-Treble Android update +environment</p> + +<p>With Treble, a new stable vendor interface provides access to the +hardware-specific parts of Android, enabling device makers to deliver new +Android releases simply by updating the Android OS framework—without any +additional work required from the silicon manufacturers:</p> + +<img src="images/treble_blog_after.png"> + +<p class="img-caption"><strong>Figure 2.</strong> Treble Android update +environment</p> + +<h2 id=testing-treble>Testing Treble</h2> +<p>To ensure forward compatibility of the vendor implementation, the new vendor +interface will be validated by the Vendor Test Suite (VTS), which is analogous +to the <a href="/compatibility/cts/">Compatibility Test Suite (CTS)</a>. VTS is +already launched and can be used to automate HAL and OS kernel testing even in +pre-Treble environments; for details, see +<a href="/devices/tech/test_infra/tradefed/fundamentals/vts">Systems Testing +With VTS</a>.</p> + +<h2 id=launching-treble>Coming soon</h2> +<p>Project Treble is coming to all new devices launching with Android O and +beyond, and the new architecture is already running on the Developer Preview of +O for Pixel phones. When Android O launches, we'll have full details here (on +<a href="https://source.android.com/">source.android.com</a>). In the interim, +you can find more details on Treble over at the +<a href="https://android-developers.googleblog.com/2017/05/here-comes-treble-modular-base-for.html">Android +Developers Blog</a>.</p> + + + </body> +</html> diff --git a/en/devices/automotive/index.html b/en/devices/automotive/index.html new file mode 100644 index 00000000..83a7a6ef --- /dev/null +++ b/en/devices/automotive/index.html @@ -0,0 +1,109 @@ +<html devsite> + <head> + <title>Automotive</title> + <meta name="project_path" value="/_project.yaml" /> + <meta name="book_path" value="/_book.yaml" /> + </head> + <body> + <!-- + Copyright 2017 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. + --> + + + +<img style="float: right; margin: 0px 15px 15px 15px;" +src="../images/ape_fwk_hal_vehicle.png" alt="Android vehicle HAL icon"/> + +<p>Many car subsystems interconnect with each other and the in-vehicle +infotainment (IVI) system via various bus topologies. The exact bus type and +protocols vary widely between manufacturers (and even between different vehicle +models of the same brand); examples include Controller Area Network (CAN) bus, +Local Interconnect Network (LIN) bus, Media Oriented Systems Transport (MOST), +as well as automotive-grade Ethernet and TCP/IP networks such as BroadR-Reach. +</p> +<p>the Android Automotive hardware abstraction layer (HAL) provides a +consistent interface to the Android framework regardless of physical transport +layer. This vehicle HAL is the interface for developing Android Automotive +implementations.</p> +<p>System integrators can implement a vehicle HAL module by connecting +function-specific platform HAL interfaces (e.g. HVAC) with technology-specific +network interfaces (e.g. CAN bus). Typical implementations may include a +dedicated Microcontroller Unit (MCU) running a proprietary real-time operating +system (RTOS) for CAN bus access or similar, which may be connected via a serial +link to the CPU running Android Automotive. Instead of a dedicated MCU, it may +also be possible to implement the bus access as a virtualized CPU. It is up to +each partner to choose the architecture suitable for the hardware as long as the +implementation fulfills the interface requirements for the vehicle HAL.</p> + +<h2 id=arch>Architecture</h2> +<p>The vehicle HAL is the interface definition between the car and the vehicle +network service:</p> + +<img src="../images/vehicle_hal_arch.png" alt="Android vehicle HAL architecture"> +<p class="img-caption"><strong>Figure 1</strong>. Vehicle HAL and Android +automotive architecture</p> + +<ul> +<li><strong>Car API</strong>. Contains the APIs such as CarHvacManager, +CarSensorManager, and CarCameraManager. For details on supported APIs, +refer to <code>/platform/packages/services/Car/car-lib</code>.</li> +<li><strong>CarService</strong>. Located at +<code>/platform/packages/services/Car/</code>.</li> +<li><strong>VehicleNetworkService</strong>. Controls vehicle HAL with built-in +security. Access restricted to system components only (non-system components +such as third party apps should use car API instead). OEMs can control access +using <code>vns_policy.xml</code> and <code>vendor_vns_policy.xml</code>. +Located at <code>/platform/packages/services/Car/vehicle_network_service/</code>; +for libraries to access the vehicle network, refer to +<code>/platform/packages/services/Car/libvehiclenetwork/</code>.</li> +<li><strong>Vehicle HAL</strong>. Interface that defines the vehicle properties +OEMs can implement. Contains property metadata (for example, whether the vehicle +property is an int and which change modes are allowed). Located at +<code>hardware/libhardware/include/hardware/vehicle.h</code>. For a basic +reference implementation, refer to +<code>hardware/libhardware/modules/vehicle/</code>.</li> +</ul> +<p>For more details, see <a href="/devices/automotive/properties.html">Vehicle +Properties</a>. + +<h2 id=security>Security</h2> +<p>The vehicle HAL supports three levels of security for accessing data:</p> +<ul> +<li>System only (controlled by <code>vns_policy.xml</code>)</li> +<li>Accessible to app with permission (through car service)</li> +<li>Accessible without permission (through car service)</li> +</ul> +<p>Direct access to vehicle properties is allowed only to selected system +components with vehicle network service acting as the gatekeeper. Most +applications go through additional gatekeeping by car service (for example, only +system applications can control HVAC as it requires system permission granted +only to system apps).</p> + +<h2 id=validation>Validation</h2> +<p>AOSP includes the following testing resources for use in development:</p> +<ul> +<li><code>hardware/libhardware/tests/vehicle/vehicle-hal-tool.c</code><br> +Command-line native tool to load vehicle HAL and do simple operations. Useful +for getting the system up and running in the early stages of development.</li> +<li><code>packages/services/Car/tests/carservice_test/</code><br>Contains car +service testing with mocked vehicle HAL properties. For each property, expected +behavior is implemented in the test. This can be a good starting point to +understand expected behavior.</li> +<li><code>hardware/libhardware/modules/vehicle/</code><br>A basic reference +implementation.</li> +</ul> + + </body> +</html> diff --git a/en/devices/automotive.html b/en/devices/automotive/properties.html index d77e5645..5a69edef 100644 --- a/en/devices/automotive.html +++ b/en/devices/automotive/properties.html @@ -1,6 +1,6 @@ <html devsite> <head> - <title>Automotive</title> + <title>Vehicle Properties</title> <meta name="project_path" value="/_project.yaml" /> <meta name="book_path" value="/_book.yaml" /> </head> @@ -22,67 +22,57 @@ --> +<p>The vehicle HAL interface defines the properties OEMs can implement and +contains property metadata (for example, whether the property is an int and +which change modes are allowed). The vehicle HAL interface is based on accessing +(read, write, subscribe) a property, which is an abstraction for a specific +function.</p> -<img style="float: right; margin: 0px 15px 15px 15px;" -src="images/ape_fwk_hal_vehicle.png" alt="Android vehicle HAL icon"/> - -<p>Many car subsystems interconnect with each other and the in-vehicle -infotainment (IVI) system via various bus topologies. The exact bus type and -protocols vary widely between manufacturers (and even between different vehicle -models of the same brand); examples include Controller Area Network (CAN) bus, -Local Interconnect Network (LIN) bus, Media Oriented Systems Transport (MOST), -as well as automotive-grade Ethernet and TCP/IP networks such as BroadR-Reach. -</p> -<p>Android Automotive has a hardware abstraction layer (HAL) that provides a -consistent interface to the Android framework regardless of physical transport -layer. This vehicle HAL is the interface for developing Android Automotive -implementations.</p> -<p>System integrators can implement a vehicle HAL module by connecting -function-specific platform HAL interfaces (e.g. HVAC) with technology-specific -network interfaces (e.g. CAN bus). Typical implementations may include a -dedicated Microcontroller Unit (MCU) running a proprietary real-time operating -system (RTOS) for CAN bus access or similar, which may be connected via a serial -link to the CPU running Android Automotive. Instead of a dedicated MCU, it may -also be possible to implement the bus access as a virtualized CPU. It is up to -each partner to choose the architecture suitable for the hardware as long as the -implementation fulfills the interface requirements for the vehicle HAL.</p> - -<h2 id=arch>Architecture</h2> -<p>The vehicle HAL is the interface definition between the car and the vehicle -network service:</p> - -<img src="images/vehicle_hal_arch.png" alt="Android vehicle HAL architecture"> -<p class="img-caption"><strong>Figure 1</strong>. Vehicle HAL and Android -automotive architecture</p> +<h2 id=interfaces>HAL interfaces</h2> +<p>The vehicle HAL uses the following interfaces:</p> +<ul> +<li><code>vehicle_prop_config_t const *(*list_properties)(..., int* +num_properties)</code> +<br>List configuration of all properties supported by the vehicle HAL. Only +supported properties are used by vehicle network service. +</li> +<li><code>(*get)(..., vehicle_prop_value_t *data)</code> +<br>Read the current value of the property. For zoned property, each zone may +have different value.</li> +<li><code>(*set)(..., const vehicle_prop_value_t *data)</code> +<br>Write a value to property. Result of write is defined per property.</li> +<li><code>(*subscribe)(..., int32_t prop, float sample_rate, int32_t +zones)</code> +<ul> +<li>Start monitoring a property value change. For zoned property, subscription +applies to requested zones. Zones = 0 is used to request all zones supported. +</li> +<li>Vehicle HAL should call separate callback when the property's value changes +(=on change) or in const interval (=continuous type).</li> +</ul></li> +<li><code>(*release_memory_from_get)(struct vehicle_hw_device* device, +vehicle_prop_value_t *data)</code> +<br>Release memory allocated from get call.</li> +</ul> +<p>The vehicle HAL uses the following callback interfaces:</p> <ul> -<li><strong>Car API</strong>. Contains the APIs such as CarHvacManager, -CarSensorManager, and CarCameraManager. For details on all supported APIs, -refer to <code>/platform/packages/services/Car/car-lib</code>.</li> -<li><strong>CarService</strong>. Located at -<code>/platform/packages/services/Car/</code>.</li> -<li><strong>VehicleNetworkService</strong>. Controls vehicle HAL with built-in -security. Access restricted to system components only (non-system components -such as third party apps should use car API instead). OEMs can control access -using <code>vns_policy.xml</code> and <code>vendor_vns_policy.xml</code>. -Located at <code>/platform/packages/services/Car/vehicle_network_service/</code>; -for libraries to access the vehicle network, refer to -<code>/platform/packages/services/Car/libvehiclenetwork/</code>.</li> -<li><strong>Vehicle HAL</strong>. Interface that defines the properties OEMs can -implement and contains property metadata (for example, whether the property is -an int and which change modes are allowed). Located at -<code>hardware/libhardware/include/hardware/vehicle.h</code>. For a basic -reference implementation, refer to -<code>hardware/libhardware/modules/vehicle/</code>.</li> +<li><code>(*vehicle_event_callback_fn)(const vehicle_prop_value_t +*event_data)</code> +<br>Notifies vehicle property's value change. Should be done only for +subscribed properties.</li> +<li><code>(*vehicle_error_callback_fn)(int32_t error_code, int32_t property, +int32_t operation)</code> +<br>Return global vehicle HAL level error or error per property. Global error +causes HAL restart, which can lead to restarting other components (including +applications).</li> </ul> -<h2 id=prop>Vehicle properties</h2> -<p>The vehicle HAL interface is based on accessing (read, write, subscribe) a -property, which is an abstraction for a specific function. Properties can be -read-only, write-only (used to pass information to vehicle HAL level), or read -and write. Support of most properties is optional.</p> -<p>Each property is uniquely identified by an int32 key and has a predefined -type (<code>value_type</code>):</p> +<h2 id=properties>Vehicle properties</h2> +<p>Properties can be read-only, write-only (used to pass information to vehicle +HAL level), or read and write (support of most properties is optional). Each +property is uniquely identified by an int32 key and has a predefined type +(<code>value_type</code>):</p> <ul> <li><code>INT32</code> (and array), <code>INT64</code>, <code>BOOLEAN</code>, @@ -90,18 +80,21 @@ type (<code>value_type</code>):</p> <li>Zoned type has zone in addition to value.</li> </ul> -<h3 id-=zone_type>Zone types</h3> +<h2 id-=zone_type>Zone types</h2> <p>The vehicle HAL defines three zone types:</p> <ul> -<li><code>vehicle_zone</code>: Zone based on rows.</li> -<li><code>vehicle_seat</code>: Zone based on seats.</li> -<li><code>vehicle_window</code>: Zone based on windows.</li> +<li><code>vehicle_zone</code> +<br>Zone based on rows.</li> +<li><code>vehicle_seat</code> +<br>Zone based on seats.</li> +<li><code>vehicle_window</code> +<br>Zone based on windows.</li> </ul> <p>Each zoned property should use pre-defined zone type. If necessary, you can use a custom zone type for each property (for details, see <a href=#prop_custom>Handling custom properties</a>).</p> -<h3 id=prop_config>Configuring a property</h3> +<h2 id=prop_config>Configuring a property</h2> <p>Use <code>vehicle_prop_config_t</code> to provide configuration information for each property. Information includes:</p> <ul> @@ -119,40 +112,6 @@ float, int64)</li> <p>In addition, some properties have specific configuration flags to represent capability.</p> -<h2 id=interfaces>HAL interfaces</h2> -<p>The vehicle HAL uses the following interfaces:</p> -<ul> -<li><code>vehicle_prop_config_t const *(*list_properties)(..., int* -num_properties)</code>. List configuration of all properties supported by the -vehicle HAL. Only supported properties will be used by vehicle network service. -</li> -<li><code>(*get)(..., vehicle_prop_value_t *data)</code>. Read the current value -of the property. For zoned property, each zone may have different value.</li> -<li><code>(*set)(..., const vehicle_prop_value_t *data)</code>. Write a value to -property. Result of write is defined per each property.</li> -<li><code>(*subscribe)(..., int32_t prop, float sample_rate, int32_t -zones)</code>.<ul> -<li>Start monitoring property value's change. For zoned property, subscription -applies to requested zones. Zones = 0 is used to request all zones supported. -</li> -<li>Vehicle HAL should call separate callback when the property's value changes -(=on change) or in const interval (=continuous type).</ul></li> -<li><code>(*release_memory_from_get)(struct vehicle_hw_device* device, -vehicle_prop_value_t *data)</code>. Release memory allocated from get call.</ul> -</li> -</ul> - -<p>The vehicle HAL uses the following callback interfaces:</p> -<ul> -<li><code>(*vehicle_event_callback_fn)(const vehicle_prop_value_t -*event_data)</code>. Notifies vehicle property's value change. Should be done -only for subscribed properties.</li> -<li><code>(*vehicle_error_callback_fn)(int32_t error_code, int32_t property, -int32_t operation).</code> Return global vehicle HAL level error or error per -each property. Global error causes HAL restart, which can lead to restarting -other components, including applications.</li> -</ul> - <h2 id=zone_prop>Handling zone properties</h2> <p>A zoned property is equivalent to a collection of multiple properties where each sub property is accessible by specified zone value.</p> @@ -182,8 +141,8 @@ such cases, use special values to represent such state.</p> </ul> <p>Example: get HVAC Temperature</p> -<img src="images/vehicle_hvac_get.png" alt="Vehicle HAL get HVAC example"> -<p class="img-caption"><strong>Figure 2</strong>. Get HVAC temperature (CS = +<img src="../images/vehicle_hvac_get.png" alt="Vehicle HAL get HVAC example"> +<p class="img-caption"><strong>Figure 1</strong>. Get HVAC temperature (CS = CarService, VNS = VehicleNetworkService, VHAL = Vehicle HAL)</p> <h3 id=set>Set calls</h3> @@ -205,8 +164,8 @@ notifies change only when it is set by external component outside Android (for example, clock properties such as <code>VEHICLE_PROPERTY_UNIX_TIME</code>).</p> <p>Example: set HVAC Temperature</p> -<img src="images/vehicle_hvac_set.png" alt="Vehicle HAL set HVAC example"> -<p class="img-caption"><strong>Figure 3</strong>. Set HVAC temperature (CD = +<img src="../images/vehicle_hvac_set.png" alt="Vehicle HAL set HVAC example"> +<p class="img-caption"><strong>Figure 2</strong>. Set HVAC temperature (CD = CarService, VNS = VehicleNetworkService, VHAL = Vehicle HAL)</p> <h2 id=prop_custom>Handling custom properties</h2> @@ -233,10 +192,10 @@ can lead to compatibility issues in the future.</li> properties. Most HVAC properties are zoned properties, but a few are non-zoned (global) properties. Example properties defined include:</p> <ul> -<li><code>VEHICLE_PROPERTY_HVAC_TEMPERATURE_SET</code> (set temperature per each -zone).</li> -<li><code>VEHICLE_PROPERTY_HVAC_RECIRC_ON</code> (control recirculation per each -zone).</li> +<li><code>VEHICLE_PROPERTY_HVAC_TEMPERATURE_SET</code> +<br>Set temperature per zone.</li> +<li><code>VEHICLE_PROPERTY_HVAC_RECIRC_ON</code> +<br>Control recirculation per zone).</li> </ul> <p>For full list of HVAC properties, search for <code>VEHICLE_PROPERTY_HVAC_*</code> in <code>vehicle.h</code>.</p> @@ -250,45 +209,22 @@ data is mandatory to build a safe vehicle application. Other sensor information users can manage.</p> <p>Supported sensor properties include:</p> <ul> -<li><code>DRIVING_STATUS</code> (should support). Represents allowed operations -in the current driving state. This information is used to block unsafe -applications while driving.</li> -<li><code>NIGHT_MODE</code> (should support). Determines day/night mode of -display.</li> -<li><code>GEAR_SELECTION/CURRENT_GEAR</code>. Gear selected by driver vs. -actual gear.</li> -<li><code>VEHICLE_SPEED</code>. Vehicle speed. Protected with permission.</li> -<li><code>ODOMETER</code>. Current odometer reading. Protected with permission. +<li><code>DRIVING_STATUS</code> +<br>Should support. Represents allowed operations in the current driving state. +This information is used to block unsafe applications while driving.</li> +<li><code>NIGHT_MODE</code> +<br>Should support. Determines day/night mode of display.</li> +<li><code>GEAR_SELECTION/CURRENT_GEAR</code> +<br>Gear selected by driver vs. actual gear.</li> +<li><code>VEHICLE_SPEED</code> +<br>Vehicle speed. Protected with permission.</li> +<li><code>ODOMETER</code> +<br>Current odometer reading. Protected with permission. </li> -<li><code>FUEL_LEVEL</code>. Current fuel level in %.</li> -<li><code>FUEL_LEVEL_LOW</code>. Fuel level is low or not (boolean).</li> -</ul> - -<h2 id=security>Security</h2> -<p>The vehicle HAL supports three levels of security for accessing data:</p> -<ul> -<li>System only (controlled by <code>vns_policy.xml</code>)</li> -<li>Accessible to app with permission (through car service)</li> -<li>Accessible without permission (through car service)</li> -</ul> -<p>Direct access to vehicle properties is allowed only to selected system -components with vehicle network service acting as the gatekeeper. Most -applications go through additional gatekeeping by car service (for example, only -system applications can control HVAC as it requires system permission granted -only to system apps).</p> - -<h2 id=validation>Validation</h2> -<p>AOSP includes the following testing resources for use in development:</p> -<ul> -<li><code>hardware/libhardware/tests/vehicle/vehicle-hal-tool.c</code>. -Command-line native tool to load vehicle HAL and do simple operations. Useful -for getting the system up and running in the early stages of development.</li> -<li><code>packages/services/Car/tests/carservice_test/</code>. Contains car -service testing with mocked vehicle HAL properties. For each property, expected -behavior is implemented in the test. This can be a good starting point to -understand expected behavior.</li> -<li><code>hardware/libhardware/modules/vehicle/</code>. A basic reference -implementation.</li> +<li><code>FUEL_LEVEL</code> +<br>Current fuel level in %.</li> +<li><code>FUEL_LEVEL_LOW</code> +<br>Fuel level is low or not (boolean).</li> </ul> </body> diff --git a/en/devices/images/ape_fwk_hal.png b/en/devices/images/ape_fwk_hal.png Binary files differindex 03f27e94..c22b2984 100644 --- a/en/devices/images/ape_fwk_hal.png +++ b/en/devices/images/ape_fwk_hal.png diff --git a/en/devices/index.html b/en/devices/index.html index 49bea636..e6d7b152 100644 --- a/en/devices/index.html +++ b/en/devices/index.html @@ -21,190 +21,27 @@ limitations under the License. --> - - -<p> -Android gives you the freedom to implement your own device specifications and +<p>Android gives you the freedom to implement your own device specifications and drivers. The hardware abstraction layer (HAL) provides a standard method for creating software hooks between the Android platform stack and your hardware. The Android operating system is also open source, so you can contribute your own -interfaces and enhancements. -</p> - -<p> -To ensure devices maintain a high level of quality and offer a consistent user -experience, each device must pass tests in the compatibility test suite (CTS). -The CTS verifies devices meet a quality standard that ensures apps run reliably -and users have a good experience. For details on the CTS, see -<a href="/compatibility/index.html">Compatibility</a>. -</p> - -<p> -Before porting Android to your hardware, take a moment to understand the Android -system architecture at a high level. Because your drivers and the HAL interact -with Android, knowing how Android works can help you navigate the many layers of -code in the Android Open Source Project (AOSP) source tree. -</p> - -<img src="images/ape_fwk_all.png"> - -<p class="img-caption"><strong>Figure 1.</strong> Android System Architecture</p> - -<h2 id="Application-framework">Application framework</h2> -<p> -The application framework is used most often by application developers. As a -hardware developer, you should be aware of developer APIs as many map directly -to the underlying HAL interfaces and can provide helpful information about -implementing drivers. -</p> - -<h2 id="Binder-IPC">Binder IPC</h2> -<p> -The Binder Inter-Process Communication (IPC) mechanism allows the application -framework to cross process boundaries and call into the Android system services -code. This enables high level framework APIs to interact with Android system -services. At the application framework level, this communication is hidden from -the developer and things appear to "just work." -</p> - -<h2 id="System-services">System services</h2> -<p> -Functionality exposed by application framework APIs communicates with system -services to access the underlying hardware. Services are modular, focused -components such as Window Manager, Search Service, or Notification Manager. -Android includes two groups of services: <em>system</em> (services such as -Window Manager and Notification Manager) and <em>media</em> (services involved -in playing and recording media). -</p> - -<h2 id="Hardware-Abstraction-Layer">Hardware abstraction layer (HAL)</h2> -<p> -The hardware abstraction layer (HAL) defines a standard interface for hardware -vendors to implement and allows Android to be agnostic about lower-level driver -implementations. The HAL allows you to implement functionality without -affecting or modifying the higher level system. HAL implementations are -packaged into modules (<code>.so</code>) file and loaded by the Android system -at the appropriate time. -</p> - -<img src="images/ape_fwk_hal.png"> - -<p class="img-caption"><strong>Figure 2.</strong> Hardware abstraction layer -(HAL) components</p> - -<p> -You must implement the corresponding HAL (and driver) for the specific hardware -your product provides. HAL implementations are typically built into shared -library modules (<code>.so</code> files). Android does not mandate a standard -interaction between your HAL implementation and your device drivers, so you have -free reign to do what is best for your situation. However, to enable the Android -system to correctly interact with your hardware, you <strong>must</strong> abide -by the contract defined in each hardware-specific HAL interface. -</p> - -<h3 id="structure">Standard HAL structure</h3> -<p> - Each hardware-specific HAL interface has properties that are defined in - <code>hardware/libhardware/include/hardware/hardware.h</code>, which - guarantee that HALs have a predictable structure. - This interface allows the Android system to load the correct versions of your - HAL modules in a consistent way. There are two general components - that a HAL interface consists of: a module and a device. -</p> -<p> - A module represents your packaged HAL implementation, which is stored as a shared library (<code>.so file</code>). It contains - metadata such as the version, name, and author of the module, which helps Android find and load it correctly. The - <code>hardware/libhardware/include/hardware/hardware.h</code> header file defines a - struct, <code>hw_module_t</code>, that represents a module and contains information such as - the module version, author, and name.</p> - - <p>In addition, the <code>hw_module_t</code> struct contains - a pointer to another struct, <code>hw_module_methods_t</code>, that contains a pointer to - an "open" function for the module. This open function is used to initiate communication with - the hardware that the HAL is serving as an abstraction for. Each hardware-specific HAL usually - extends the generic <code>hw_module_t</code> struct with additional information - for that specific piece of hardware. For example in the camera HAL, the <code>camera_module_t</code> struct - contains a <code>hw_module_t</code> struct along with other camera-specific function pointers: -</p> - -<pre class="devsite-click-to-copy"> -typedef struct camera_module { - hw_module_t common; - int (*get_number_of_cameras)(void); - int (*get_camera_info)(int camera_id, struct camera_info *info); -} camera_module_t; -</pre> - -<p>When you implement a HAL and create the module struct, you must name it - <code>HAL_MODULE_INFO_SYM</code>. For instance, here is an example from the Nexus 9 audio HAL:</p> - -<pre class="devsite-click-to-copy"> -struct audio_module HAL_MODULE_INFO_SYM = { - .common = { - .tag = HARDWARE_MODULE_TAG, - .module_api_version = AUDIO_MODULE_API_VERSION_0_1, - .hal_api_version = HARDWARE_HAL_API_VERSION, - .id = AUDIO_HARDWARE_MODULE_ID, - .name = "NVIDIA Tegra Audio HAL", - .author = "The Android Open Source Project", - .methods = &hal_module_methods, - }, -}; -</pre> -<p> - A device abstracts the actual hardware of your product. For example, an audio module can contain - a primary audio device, a USB audio device, or a Bluetooth A2DP audio device. A device - is represented by the <code>hw_device_t</code> struct. Like a module, each type of device - defines a more-detailed version of the generic <code>hw_device_t</code> that contains - function pointers for specific features of the hardware. For example, the - <code>audio_hw_device_t</code> struct type contains function pointers to audio device operations: -</p> - -<pre class="devsite-click-to-copy"> -struct audio_hw_device { - struct hw_device_t common; - - /** - * used by audio flinger to enumerate what devices are supported by - * each audio_hw_device implementation. - * - * Return value is a bitmask of 1 or more values of audio_devices_t - */ - uint32_t (*get_supported_devices)(const struct audio_hw_device *dev); - ... -}; -typedef struct audio_hw_device audio_hw_device_t; -</pre> - -<p> - In addition to these standard properties, each hardware-specific HAL interface can define more of its - own features and requirements. See the <a href="/reference/hal/">HAL reference documentation</a> - as well as the individual instructions for each HAL for more information on how to implement a specific interface. -</p> - -<h3 id="modules">HAL modules</h3> -<p>HAL implementations are built into modules (<code>.so</code>) files and are dynamically linked by Android when appropriate. - You can build your modules by creating <code>Android.mk</code> files for each of your HAL implementations - and pointing to your source files. In general, your shared libraries must be named in a certain format, so that - they can be found and loaded properly. The naming scheme varies slightly from module to module, but they follow - the general pattern of: <code><module_type>.<device_name></code>.</p> - - <p>For more information about setting up the build for each HAL, see its respective documentation.</p> - -<h2 id="Linux-kernel">Linux kernel</h2> -<p> -Developing your device drivers is similar to developing a typical Linux device -driver. Android uses a version of the Linux kernel with a few special additions -such as wake locks (a memory management system that is more aggressive in -preserving memory), the Binder IPC driver, and other features important for a -mobile embedded platform. These additions are primarily for system functionality -and do not affect driver development. - -<p> -You can use any version of the kernel as long as it supports the required -features (such as the binder driver). However, we recommend using the latest -version of the Android kernel. For details on the latest Android kernel, see <a href="/source/building-kernels.html" >Building Kernels</a>. -</p> +interfaces and enhancements.</p> + +<p>Before porting Android to your hardware, take a moment to understand the +<a href="/devices/architecture/index.html">Android system architecture</a>. +Because your drivers and the HAL interact with Android, knowing its structure +can help you navigate the many layers of code in the Android Open Source Project +(AOSP) source tree. When you are comfortable with the basic Android +architecture, review the interface-specific documentation in this section to +learn about specific HALs and how to build them for your device.</p> + +<p>To maintain a high level of quality and offer a consistent user experience, +Android requires that all implementations meet the requirements stated in the +<a href="/compatibility/cdd.html">Compatibility Definition Document (CDD)</a> +and that all devices pass tests in the +<a href="/compatibility/cts.html">Compatibility Test Suite (CTS)</a>. For +details on the Android compatibility program, see +<a href="/compatibility/index.html">Compatibility</a>.</p> </body> </html> diff --git a/en/devices/input/diagnostics.html b/en/devices/input/diagnostics.html deleted file mode 100644 index 160ceaed..00000000 --- a/en/devices/input/diagnostics.html +++ /dev/null @@ -1,495 +0,0 @@ -<html devsite> - <head> - <title>Dumpsys Input Diagnostics</title> - <meta name="project_path" value="/_project.yaml" /> - <meta name="book_path" value="/_book.yaml" /> - </head> - <body> - <!-- - Copyright 2017 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. - --> - - - -<p>The <code>dumpsys</code> input command dumps the state of the -system’s input devices, such as keyboards and touchscreens, and the -processing of input events.</p> - -<h2 id="input">Input</h2> -<p>To dump the input system’s state, run the following command:</p> -<pre class="devsite-terminal devsite-click-to-copy"> -adb shell dumpsys input -</pre> - -<h2 id="output">Output</h2> - -<p>The set of information reported varies depending on the version of Android -but consists of three sections:</p> - -<ul> - <li> Event Hub State - <li> Input Reader State - <li> Input Dispatcher State -</ul> - -<h3 id="event_hub_state">Event Hub State</h3> - -<pre class="devsite-click-to-copy"> -INPUT MANAGER (dumpsys input) - -Event Hub State: - BuiltInKeyboardId: -2 - Devices: - -1: Virtual - Classes: 0x40000023 - Path: <virtual> - Descriptor: a718a782d34bc767f4689c232d64d527998ea7fd - Location: - ControllerNumber: 0 - UniqueId: <virtual> - Identifier: bus=0x0000, vendor=0x0000, product=0x0000, version=0x0000 - KeyLayoutFile: /system/usr/keylayout/Generic.kl - KeyCharacterMapFile: /system/usr/keychars/Virtual.kcm - ConfigurationFile: - HaveKeyboardLayoutOverlay: false - 1: msm8974-taiko-mtp-snd-card Headset Jack - Classes: 0x00000080 - Path: /dev/input/event5 - Descriptor: c8e3782483b4837ead6602e20483c46ff801112c - Location: ALSA - ControllerNumber: 0 - UniqueId: - Identifier: bus=0x0000, vendor=0x0000, product=0x0000, version=0x0000 - KeyLayoutFile: - KeyCharacterMapFile: - ConfigurationFile: - HaveKeyboardLayoutOverlay: false - 2: msm8974-taiko-mtp-snd-card Button Jack - Classes: 0x00000001 - Path: /dev/input/event4 - Descriptor: 96fe62b244c555351ec576b282232e787fb42bab - Location: ALSA - ControllerNumber: 0 - UniqueId: - Identifier: bus=0x0000, vendor=0x0000, product=0x0000, version=0x0000 - KeyLayoutFile: /system/usr/keylayout/msm8974-taiko-mtp-snd-card_Button_Jack.kl - KeyCharacterMapFile: /system/usr/keychars/msm8974-taiko-mtp-snd-card_Button_Jack.kcm - ConfigurationFile: - HaveKeyboardLayoutOverlay: false - 3: hs_detect - Classes: 0x00000081 - Path: /dev/input/event3 - Descriptor: 485d69228e24f5e46da1598745890b214130dbc4 - Location: - ControllerNumber: 0 - UniqueId: - Identifier: bus=0x0000, vendor=0x0001, product=0x0001, version=0x0001 - KeyLayoutFile: /system/usr/keylayout/hs_detect.kl - KeyCharacterMapFile: /system/usr/keychars/hs_detect.kcm - ConfigurationFile: - HaveKeyboardLayoutOverlay: false - 4: touch_dev - Classes: 0x00000014 - Path: /dev/input/event1 - Descriptor: 4e2720e99bd2b59adae8529881343531fff7c98e - Location: - ControllerNumber: 0 - UniqueId: - Identifier: bus=0x0000, vendor=0x0000, product=0x0000, version=0x0000 - KeyLayoutFile: - KeyCharacterMapFile: - ConfigurationFile: /system/usr/idc/touch_dev.idc - HaveKeyboardLayoutOverlay: false - 5: qpnp_pon - Classes: 0x00000001 - Path: /dev/input/event0 - Descriptor: fb60d4f4370f5dbe8267b63d38dea852987571ab - Location: qpnp_pon/input0 - ControllerNumber: 0 - UniqueId: - Identifier: bus=0x0000, vendor=0x0000, product=0x0000, version=0x0000 - KeyLayoutFile: /system/usr/keylayout/qpnp_pon.kl - KeyCharacterMapFile: /system/usr/keychars/qpnp_pon.kcm - ConfigurationFile: - HaveKeyboardLayoutOverlay: false - 6: gpio-keys - Classes: 0x00000081 - Path: /dev/input/event2 - Descriptor: d2c52ff0f656fac4cd7b7a118d575e0109a9fe1c - Location: gpio-keys/input0 - ControllerNumber: 0 - UniqueId: - Identifier: bus=0x0019, vendor=0x0001, product=0x0001, version=0x0100 - KeyLayoutFile: /system/usr/keylayout/gpio-keys.kl - KeyCharacterMapFile: /system/usr/keychars/gpio-keys.kcm - ConfigurationFile: - HaveKeyboardLayoutOverlay: false -</code></pre> - -<h4 id="things-to-look-for">Things to check</h4> - -<ul> - <li> All of the expected input devices are present.</li> - - <li> Each input device has an appropriate key layout file, key character map - file and input device configuration file. If the files are missing or contain - syntax errors, then they will not be loaded.</li> - - <li> Each input device is being classified correctly. The bits in the - <code>Classes</code> field correspond to flags in <code>EventHub.h</code> such - as <code>INPUT_DEVICE_CLASS_TOUCH_MT</code>.</li> - - <li> The <code>BuiltInKeyboardId</code> is correct. If the device does not - have a built-in keyboard, then the id must be <code>-2</code>, otherwise it - should be the id of the built-in keyboard.</li> - - <li>If you observe that the <code>BuiltInKeyboardId</code> is not - <code>-2</code> but it should be, then you are missing a key character map file - for a special function keypad somewhere. Special function keypad devices - should have key character map files that contain just the line <code>type - SPECIAL_FUNCTION</code> (that's what in the <code>tuna-gpio-keykad.kcm</code> - file we see mentioned above).</li> -</ul> - -<h3 id="input-reader-state">Input Reader State</h3> -<p>The <code>InputReader</code> is responsible for decoding input events from the kernel. -Its state dump shows information about how each input device is configured -and recent state changes that have occurred, such as key presses or touches on -the touch screen.</p> - -<p>As an example, this is what a special function keypad looks like:</p> - -<pre class="devsite-click-to-copy"> -Input Reader State -... - Device 3: tuna-gpio-keypad - IsExternal: false - Sources: 0x00000101 - KeyboardType: 1 - Keyboard Input Mapper: - Parameters: - AssociatedDisplayId: -1 - OrientationAware: false - KeyboardType: 1 - Orientation: 0 - KeyDowns: 0 keys currently down - MetaState: 0x0 - DownTime: 75816923828000 -</pre> - -<p>Here is a touch screen. Notice all of the information about the resolution of -the device and the calibration parameters that were used.</p> - -<pre class="devsite-click-to-copy"> -Input Reader State -... - Device 6: Melfas MMSxxx Touchscreen - IsExternal: false - Sources: 0x00001002 - KeyboardType: 0 - Motion Ranges: - X: source=0x00001002, min=0.000, max=719.001, flat=0.000, fuzz=0.999 - Y: source=0x00001002, min=0.000, max=1279.001, flat=0.000, fuzz=0.999 - PRESSURE: source=0x00001002, min=0.000, max=1.000, flat=0.000, fuzz=0.000 - SIZE: source=0x00001002, min=0.000, max=1.000, flat=0.000, fuzz=0.000 - TOUCH_MAJOR: source=0x00001002, min=0.000, max=1468.605, flat=0.000, fuzz=0.000 - TOUCH_MINOR: source=0x00001002, min=0.000, max=1468.605, flat=0.000, fuzz=0.000 - TOOL_MAJOR: source=0x00001002, min=0.000, max=1468.605, flat=0.000, fuzz=0.000 - TOOL_MINOR: source=0x00001002, min=0.000, max=1468.605, flat=0.000, fuzz=0.000 - Touch Input Mapper: - Parameters: - GestureMode: spots - DeviceType: touchScreen - AssociatedDisplay: id=0, isExternal=false - OrientationAware: true - Raw Touch Axes: - X: min=0, max=720, flat=0, fuzz=0, resolution=0 - Y: min=0, max=1280, flat=0, fuzz=0, resolution=0 - Pressure: min=0, max=255, flat=0, fuzz=0, resolution=0 - TouchMajor: min=0, max=30, flat=0, fuzz=0, resolution=0 - TouchMinor: unknown range - ToolMajor: unknown range - ToolMinor: unknown range - Orientation: unknown range - Distance: unknown range - TiltX: unknown range - TiltY: unknown range - TrackingId: min=0, max=65535, flat=0, fuzz=0, resolution=0 - Slot: min=0, max=9, flat=0, fuzz=0, resolution=0 - Calibration: - touch.size.calibration: diameter - touch.size.scale: 10.000 - touch.size.bias: 0.000 - touch.size.isSummed: false - touch.pressure.calibration: amplitude - touch.pressure.scale: 0.005 - touch.orientation.calibration: none - touch.distance.calibration: none - SurfaceWidth: 720px - SurfaceHeight: 1280px - SurfaceOrientation: 0 - Translation and Scaling Factors: - XScale: 0.999 - YScale: 0.999 - XPrecision: 1.001 - YPrecision: 1.001 - GeometricScale: 0.999 - PressureScale: 0.005 - SizeScale: 0.033 - OrientationCenter: 0.000 - OrientationScale: 0.000 - DistanceScale: 0.000 - HaveTilt: false - TiltXCenter: 0.000 - TiltXScale: 0.000 - TiltYCenter: 0.000 - TiltYScale: 0.000 - Last Button State: 0x00000000 - Last Raw Touch: pointerCount=0 - Last Cooked Touch: pointerCount=0 -</pre> - -<p>Here is an external keyboard / mouse combo HID device. (This device doesn't actually -have a mouse but its HID descriptor says it does.)</p> - -<pre class="devsite-click-to-copy"> - Device 7: Motorola Bluetooth Wireless Keyboard - IsExternal: true - Sources: 0x00002103 - KeyboardType: 2 - Motion Ranges: - X: source=0x00002002, min=0.000, max=719.000, flat=0.000, fuzz=0.000 - Y: source=0x00002002, min=0.000, max=1279.000, flat=0.000, fuzz=0.000 - PRESSURE: source=0x00002002, min=0.000, max=1.000, flat=0.000, fuzz=0.000 - VSCROLL: source=0x00002002, min=-1.000, max=1.000, flat=0.000, fuzz=0.000 - Keyboard Input Mapper: - Parameters: - AssociatedDisplayId: -1 - OrientationAware: false - KeyboardType: 2 - Orientation: 0 - KeyDowns: 0 keys currently down - MetaState: 0x0 - DownTime: 75868832946000 - Cursor Input Mapper: - Parameters: - AssociatedDisplayId: 0 - Mode: pointer - OrientationAware: false - XScale: 1.000 - YScale: 1.000 - XPrecision: 1.000 - YPrecision: 1.000 - HaveVWheel: true - HaveHWheel: false - VWheelScale: 1.000 - HWheelScale: 1.000 - Orientation: 0 - ButtonState: 0x00000000 - Down: false - DownTime: 0 -</pre> -<p>Here is a joystick. Notice how all of the axes have been scaled to a normalized -range. The axis mapping can be configured using key layout files.</p> -<pre class="devsite-click-to-copy"> -Device 18: Logitech Logitech Cordless RumblePad 2 - IsExternal: true - Sources: 0x01000511 - KeyboardType: 1 - Motion Ranges: - X: source=0x01000010, min=-1.000, max=1.000, flat=0.118, fuzz=0.000 - Y: source=0x01000010, min=-1.000, max=1.000, flat=0.118, fuzz=0.000 - Z: source=0x01000010, min=-1.000, max=1.000, flat=0.118, fuzz=0.000 - RZ: source=0x01000010, min=-1.000, max=1.000, flat=0.118, fuzz=0.000 - HAT_X: source=0x01000010, min=-1.000, max=1.000, flat=0.000, fuzz=0.000 - HAT_Y: source=0x01000010, min=-1.000, max=1.000, flat=0.000, fuzz=0.000 - Keyboard Input Mapper: - Parameters: - AssociatedDisplayId: -1 - OrientationAware: false - KeyboardType: 1 - Orientation: 0 - KeyDowns: 0 keys currently down - MetaState: 0x0 - DownTime: 675270841000 - Joystick Input Mapper: - Axes: - X: min=-1.00000, max=1.00000, flat=0.11765, fuzz=0.00000 - scale=0.00784, offset=-1.00000, highScale=0.00784, highOffset=-1.00000 - rawAxis=0, rawMin=0, rawMax=255, rawFlat=15, rawFuzz=0, rawResolution=0 - Y: min=-1.00000, max=1.00000, flat=0.11765, fuzz=0.00000 - scale=0.00784, offset=-1.00000, highScale=0.00784, highOffset=-1.00000 - rawAxis=1, rawMin=0, rawMax=255, rawFlat=15, rawFuzz=0, rawResolution=0 - Z: min=-1.00000, max=1.00000, flat=0.11765, fuzz=0.00000 - scale=0.00784, offset=-1.00000, highScale=0.00784, highOffset=-1.00000 - rawAxis=2, rawMin=0, rawMax=255, rawFlat=15, rawFuzz=0, rawResolution=0 - RZ: min=-1.00000, max=1.00000, flat=0.11765, fuzz=0.00000 - scale=0.00784, offset=-1.00000, highScale=0.00784, highOffset=-1.00000 - rawAxis=5, rawMin=0, rawMax=255, rawFlat=15, rawFuzz=0, rawResolution=0 - HAT_X: min=-1.00000, max=1.00000, flat=0.00000, fuzz=0.00000 - scale=1.00000, offset=0.00000, highScale=1.00000, highOffset=0.00000 - rawAxis=16, rawMin=-1, rawMax=1, rawFlat=0, rawFuzz=0, rawResolution=0 - HAT_Y: min=-1.00000, max=1.00000, flat=0.00000, fuzz=0.00000 - scale=1.00000, offset=0.00000, highScale=1.00000, highOffset=0.00000 - rawAxis=17, rawMin=-1, rawMax=1, rawFlat=0, rawFuzz=0, rawResolution=0 -</pre> -<p>At the end of the input reader dump there is some information about global configuration -parameters such as the mouse pointer speed.</p> -<pre class="devsite-click-to-copy"> - Configuration: - ExcludedDeviceNames: [] - VirtualKeyQuietTime: 0.0ms - PointerVelocityControlParameters: scale=1.000, lowThreshold=500.000, highThreshold=3000.000, acceleration=3.000 - WheelVelocityControlParameters: scale=1.000, lowThreshold=15.000, highThreshold=50.000, acceleration=4.000 - PointerGesture: - Enabled: true - QuietInterval: 100.0ms - DragMinSwitchSpeed: 50.0px/s - TapInterval: 150.0ms - TapDragInterval: 300.0ms - TapSlop: 20.0px - MultitouchSettleInterval: 100.0ms - MultitouchMinDistance: 15.0px - SwipeTransitionAngleCosine: 0.3 - SwipeMaxWidthRatio: 0.2 - MovementSpeedRatio: 0.8 - ZoomSpeedRatio: 0.3 -</pre> -<h4 id="things-to-look-for_1">Things To Look For</h4> -<ol> -<li> -<p>All of the expected input devices are present.</p> -</li> -<li> -<p>Each input device has been configured appropriately. Especially check the - touch screen and joystick axes.</p> -</li> -</ol> -<h3 id="input-dispatcher-state">Input Dispatcher State</h3> -<p>The <code>InputDispatcher</code> is responsible for sending input events to applications. -Its state dump shows information about which window is being touched, the -state of the input queue, whether an ANR is in progress, and so on.</p> -<pre class="devsite-click-to-copy"> -Input Dispatcher State: - DispatchEnabled: 1 - DispatchFrozen: 0 - FocusedApplication: <null> - FocusedWindow: name='Window{3fb06dc3 u0 StatusBar}' - TouchStates: <no displays touched> - Windows: - 0: name='Window{357bbbfe u0 SearchPanel}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01820100, type=0x000007e8, layer=211000, frame=[0,0][1080,1920], scale=1.000000, touchableRegion=[0,0][1080,1920], inputFeatures=0x00000000, ownerPid=22674, ownerUid=10020, dispatchingTimeout=5000.000ms - 1: name='Window{3b14c0ca u0 NavigationBar}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01840068, type=0x000007e3, layer=201000, frame=[0,1776][1080,1920], scale=1.000000, touchableRegion=[0,1776][1080,1920], inputFeatures=0x00000000, ownerPid=22674, ownerUid=10020, dispatchingTimeout=5000.000ms - 2: name='Window{2c7e849c u0 com.vito.lux}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=true, canReceiveKeys=false, flags=0x0089031a, type=0x000007d6, layer=191000, frame=[-495,-147][1575,1923], scale=1.000000, touchableRegion=[-495,-147][1575,1923], inputFeatures=0x00000000, ownerPid=4697, ownerUid=10084, dispatchingTimeout=5000.000ms - 3: name='Window{31c9f22 u0 Heads Up}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01820328, type=0x000007de, layer=161000, frame=[0,0][1794,750], scale=1.000000, touchableRegion=[0,0][1794,192], inputFeatures=0x00000000, ownerPid=22674, ownerUid=10020, dispatchingTimeout=5000.000ms - 4: name='Window{3fb06dc3 u0 StatusBar}', displayId=0, paused=false, hasFocus=true, hasWallpaper=false, visible=true, canReceiveKeys=true, flags=0x81960040, type=0x000007d0, layer=151000, frame=[0,0][1080,1920], scale=1.000000, touchableRegion=[0,0][1080,1920], inputFeatures=0x00000004, ownerPid=22674, ownerUid=10020, dispatchingTimeout=5000.000ms - 5: name='Window{278c1d65 u0 KeyguardScrim}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01110900, type=0x000007ed, layer=131000, frame=[0,0][1080,1776], scale=1.000000, touchableRegion=[0,0][1080,1776], inputFeatures=0x00000000, ownerPid=745, ownerUid=1000, dispatchingTimeout=5000.000ms - 6: name='Window{869f213 u0 com.android.systemui.ImageWallpaper}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=true, canReceiveKeys=false, flags=0x00000318, type=0x000007dd, layer=21025, frame=[0,0][2328,1920], scale=1.000000, touchableRegion=[0,0][2328,1920], inputFeatures=0x00000000, ownerPid=22674, ownerUid=10020, dispatchingTimeout=5000.000ms - 7: name='Window{16ab6320 u0 InputMethod}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01800108, type=0x000007db, layer=21020, frame=[0,75][1080,1920], scale=1.000000, touchableRegion=[0,986][1080,1920], inputFeatures=0x00000000, ownerPid=8409, ownerUid=10056, dispatchingTimeout=5000.000ms - 8: name='Window{cf4ff0b u0 com.google.android.googlequicksearchbox/com.google.android.launcher.GEL}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x81910120, type=0x00000001, layer=21015, frame=[0,0][1080,1920], scale=1.000000, touchableRegion=[0,0][1080,1920], inputFeatures=0x00000000, ownerPid=14722, ownerUid=10022, dispatchingTimeout=5000.000ms - 9: name='Window{1a7be08a u0 com.android.systemui/com.android.systemui.recents.RecentsActivity EXITING}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x81910120, type=0x00000001, layer=21010, frame=[0,0][1080,1920], scale=1.000000, touchableRegion=[0,0][1080,1920], inputFeatures=0x00000000, ownerPid=22674, ownerUid=10020, dispatchingTimeout=5000.000ms - 10: name='Window{2280455f u0 com.google.android.gm/com.google.android.gm.ConversationListActivityGmail}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x81810120, type=0x00000001, layer=21005, frame=[0,0][1080,1920], scale=1.000000, touchableRegion=[0,0][1080,1920], inputFeatures=0x00000000, ownerPid=9897, ownerUid=10070, dispatchingTimeout=5000.000ms - 11: name='Window{657fee5 u0 com.mobilityware.freecell/com.mobilityware.freecell.FreeCell}', displayId=0, paused=false, hasFocus=false, hasWallpaper=false, visible=false, canReceiveKeys=false, flags=0x01810520, type=0x00000001, layer=21000, frame=[0,0][1080,1776], scale=1.000000, touchableRegion=[0,0][1080,1920], inputFeatures=0x00000000, ownerPid=3189, ownerUid=10085, dispatchingTimeout=5000.000ms - MonitoringChannels: - 0: 'WindowManager (server)' - RecentQueue: length=10 - MotionEvent(deviceId=4, source=0x00001002, action=2, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (335.0, 1465.0)]), policyFlags=0x62000000, age=217264.0ms - MotionEvent(deviceId=4, source=0x00001002, action=1, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (335.0, 1465.0)]), policyFlags=0x62000000, age=217255.7ms - MotionEvent(deviceId=4, source=0x00001002, action=0, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (330.0, 1283.0)]), policyFlags=0x62000000, age=216805.0ms - MotionEvent(deviceId=4, source=0x00001002, action=2, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (330.0, 1287.0)]), policyFlags=0x62000000, age=216788.3ms - MotionEvent(deviceId=4, source=0x00001002, action=2, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (331.0, 1297.0)]), policyFlags=0x62000000, age=216780.0ms - MotionEvent(deviceId=4, source=0x00001002, action=2, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (332.0, 1316.0)]), policyFlags=0x62000000, age=216771.6ms - MotionEvent(deviceId=4, source=0x00001002, action=2, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (333.0, 1340.0)]), policyFlags=0x62000000, age=216763.3ms - MotionEvent(deviceId=4, source=0x00001002, action=2, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (333.0, 1362.0)]), policyFlags=0x62000000, age=216755.0ms - MotionEvent(deviceId=4, source=0x00001002, action=2, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (332.0, 1384.0)]), policyFlags=0x62000000, age=216747.2ms - MotionEvent(deviceId=4, source=0x00001002, action=1, flags=0x00000000, metaState=0x00000000, buttonState=0x00000000, edgeFlags=0x00000000, xPrecision=1.0, yPrecision=1.0, displayId=0, pointers=[0: (332.0, 1384.0)]), policyFlags=0x62000000, age=216738.9ms - PendingEvent: <none> - InboundQueue: <empty> - ReplacedKeys: <empty> - Connections: - 0: channelName='WindowManager (server)', windowName='monitor', status=NORMAL, monitor=true, inputPublisherBlocked=false - OutboundQueue: <empty> - WaitQueue: <empty> - 1: channelName='278c1d65 KeyguardScrim (server)', windowName='Window{278c1d65 u0 KeyguardScrim}', status=NORMAL, monitor=false, inputPublisherBlocked=false - OutboundQueue: <empty> - WaitQueue: <empty> - 2: channelName='357bbbfe SearchPanel (server)', windowName='Window{357bbbfe u0 SearchPanel}', status=NORMAL, monitor=false, inputPublisherBlocked=false - OutboundQueue: <empty> - WaitQueue: <empty> - 3: channelName='869f213 com.android.systemui.ImageWallpaper (server)', windowName='Window{869f213 u0 com.android.systemui.ImageWallpaper}', status=NORMAL, monitor=false, inputPublisherBlocked=false - OutboundQueue: <empty> - WaitQueue: <empty> - 4: channelName='3fb06dc3 StatusBar (server)', windowName='Window{3fb06dc3 u0 StatusBar}', status=NORMAL, monitor=false, inputPublisherBlocked=false - OutboundQueue: <empty> - WaitQueue: <empty> - 5: channelName='2c7e849c (server)', windowName='Window{2c7e849c u0 com.vito.lux}', status=NORMAL, monitor=false, inputPublisherBlocked=false - OutboundQueue: <empty> - WaitQueue: <empty> - 6: channelName='cf4ff0b com.google.android.googlequicksearchbox/com.google.android.launcher.GEL (server)', windowName='Window{cf4ff0b -u0 com.google.android.googlequicksearchbox/com.google.android.launcher.GEL}', status=NORMAL, monitor=false, inputPublisherBlocked=false - OutboundQueue: <empty> - WaitQueue: <empty> - 7: channelName='2280455f com.google.android.gm/com.google.android.gm.ConversationListActivityGmail (server)', windowName='Window{2280455f u0 com.google.android.gm/com.google.android.gm.ConversationListActivityGmail}', status=NORMAL, monitor=false, inputPublisherBlocked=false - OutboundQueue: <empty> - WaitQueue: <empty> - 8: channelName='1a7be08a com.android.systemui/com.android.systemui.recents.RecentsActivity (server)', windowName='Window{1a7be08a u0 com.android.systemui/com.android.systemui.recents.RecentsActivity EXITING}', status=NORMAL, monitor=false, inputPublisherBlocked=false - OutboundQueue: <empty> - WaitQueue: <empty> - 9: channelName='3b14c0ca NavigationBar (server)', windowName='Window{3b14c0ca u0 NavigationBar}', status=NORMAL, monitor=false, inputPublisherBlocked=false - OutboundQueue: <empty> - WaitQueue: <empty> - 10: channelName='16ab6320 InputMethod (server)', windowName='Window{16ab6320 u0 InputMethod}', status=NORMAL, monitor=false, inputPublisherBlocked=false - OutboundQueue: <empty> - WaitQueue: <empty> - 11: channelName='657fee5 com.mobilityware.freecell/com.mobilityware.freecell.FreeCell (server)', windowName='Window{657fee5 u0 com.mobilityware.freecell/com.mobilityware.freecell.FreeCell}', status=NORMAL, monitor=false, inputPublisherBlocked=false - OutboundQueue: <empty> - WaitQueue: <empty> - 12: channelName='31c9f22 Heads Up (server)', windowName='Window{31c9f22 u0 Heads Up}', status=NORMAL, monitor=false, inputPublisherBlocked=false - OutboundQueue: <empty> - WaitQueue: <empty> - AppSwitch: not pending - 7: channelName='2280455f com.google.android.gm/com.google.android.gm.ConversationListActivityGmail (server)', windowName='Window{2280455f u0 com.google.android.gm/com.google.android.gm.ConversationListActivityGmail}', status=NORMAL, monitor=false, inputPublisherBlocked=false - OutboundQueue: <empty> - WaitQueue: <empty> - 8: channelName='1a7be08a com.android.systemui/com.android.systemui.recents.RecentsActivity (server)', windowName='Window{1a7be08a u0 com.android.systemui/com.android.systemui.recents.RecentsActivity EXITING}', status=NORMAL, monitor=false, inputPublisherBlocked=false - OutboundQueue: <empty> - WaitQueue: <empty> - 9: channelName='3b14c0ca NavigationBar (server)', windowName='Window{3b14c0ca u0 NavigationBar}', status=NORMAL, monitor=false, inputPublisherBlocked=false - OutboundQueue: <empty> - WaitQueue: <empty> - 10: channelName='16ab6320 InputMethod (server)', windowName='Window{16ab6320 u0 InputMethod}', status=NORMAL, monitor=false, inputPublisherBlocked=false - OutboundQueue: <empty> - WaitQueue: <empty> - 11: channelName='657fee5 com.mobilityware.freecell/com.mobilityware.freecell.FreeCell (server)', windowName='Window{657fee5 u0 com.mobilityware.freecell/com.mobilityware.freecell.FreeCell}', status=NORMAL, monitor=false, inputPublisherBlocked=false - OutboundQueue: <empty> - WaitQueue: <empty> - 12: channelName='31c9f22 Heads Up (server)', windowName='Window{31c9f22 u0 Heads Up}', status=NORMAL, monitor=false, inputPublisherBlocked=false - OutboundQueue: <empty> - WaitQueue: <empty> - AppSwitch: not pending - Configuration: - KeyRepeatDelay: 50.0ms - KeyRepeatTimeout: 500.0ms -</pre> -<h4 id="things-to-look-for_2">Things To Look For</h4> -<ol> - <li> In general, all input events are being processed as expected. </li> - <li> If you touch the touch screen and run dumpsys at the same time, - then the <code>TouchStates</code> line should show the window that - you are touching. </li> -</ol> - - - </body> -</html> diff --git a/en/devices/input/migration-guide.html b/en/devices/input/migration-guide.html index 4ddc8274..6f50f004 100644 --- a/en/devices/input/migration-guide.html +++ b/en/devices/input/migration-guide.html @@ -44,8 +44,9 @@ USB product id / vendor id or by device name.</p> function input devices. These files should simple contain a line to set the keyboard type to <code>SPECIAL_FUNCTION</code>.</p> <p>A good way to ensure that all built-in input devices are appropriately configured -is to run <a href="dumpsys.html">Dumpsys</a> and look for devices that -are inappropriately using <code>Generic.kcm</code>.</p> +is to run <a + href="https://developer.android.com/studio/command-line/dumpsys.html">Dumpsys</a> +and look for devices that are inappropriately using <code>Generic.kcm</code>.</p> <h2 id="migrating-to-android-honeycomb-32">Migrating to Android Honeycomb 3.2</h2> <p>In Honeycomb 3.2, we added support for joysticks and extended the key layout file format to enable joystick axis mapping.</p> diff --git a/en/devices/storage/adoptable.html b/en/devices/storage/adoptable.html index 7bef04da..7d167628 100644 --- a/en/devices/storage/adoptable.html +++ b/en/devices/storage/adoptable.html @@ -28,10 +28,16 @@ these accessories were historically limited to simple file storage, due to their expected impermanence and the minimal data protection offered to <a href="/devices/storage/traditional.html">traditional external storage</a>. -Android 6.0 introduces the ability to +Android 6.0 introduced the ability to <a href="http://developer.android.com/about/versions/marshmallow/android-6.0.html#adoptable-storage">adopt</a> external storage media to act like internal storage.</p> +<p class="warning"><strong>Warning:</strong> <a +href="/security/encryption/file-based.html">File-based encryption</a> cannot +currently be used together with adoptable storage. On devices using file-based +encryption, new storage media (such as an SD card) must be used as <a +href="/devices/storage/traditional.html">traditional storage</a>.</p> + <p>When external storage media is adopted, it’s formatted and encrypted to only work with a single Android device at a time. Because the media is strongly tied to the Android device that adopted it, it can safely store both apps and diff --git a/en/devices/tech/dalvik/configure.html b/en/devices/tech/dalvik/configure.html index 2018b9c5..b6868f76 100644 --- a/en/devices/tech/dalvik/configure.html +++ b/en/devices/tech/dalvik/configure.html @@ -24,9 +24,8 @@ <p>This page discusses how to configure ART and its compilation options. Topics addressed here -include configuration of pre-compilation of the system image, dex2oat compilation options at -first boot (and post-OTA), and how to trade off system partition space, data partition space, -and performance.</p> +include configuration of pre-compilation of the system image, dex2oat compilation options, +and how to trade off system partition space, data partition space, and performance.</p> <p>See <a href="http://source.android.com/devices/tech/dalvik/index.html">ART and Dalvik</a>, the <a @@ -39,105 +38,105 @@ properly.</p> <h2 id=how_art_works>How ART works</h2> -<p>ART is the new Android runtime for the Android 5.0 (Lollipop or L) release and -beyond. Dalvik is no longer available. </p> - -<p>Please note, this section merely summarizes ART’s configuration. For an -in-depth description, see the <a -href="https://www.google.com/events/io/io14videos/b750c8da-aebe-e311-b297-00155d5066d7">Android -runtime</a> presentation conducted at Google I/O 2014. </p> - -<p>ART uses ahead-of-time (AOT) compilation. This means that, at installation, dex -code is compiled to native code in OAT files, which replace Dalvik’s odex -files. This has several implications:</p> - +<p>ART uses ahead-of-time (AOT) compilation, and starting in Android 7.0 +(Nougat or N), it uses a hybrid combination of AOT, just-in-time (JIT) +compilation, and profile-guided compilation. The combination of all these +compilation modes is configurable and will be discussed in this section. As an +example, Pixel devices are configured with the following compilation flow:</p> +<ol> +<li>An application is initially installed without any AOT compilation. The + first few times the application runs, it will be interpreted, and methods + frequently executed will be JIT compiled.</li> +<li>When the device is idle and charging, a compilation daemon runs to + AOT-compile frequently used code based on a profile generated during the + first runs.</li> +<li>The next restart of an application will use the profile-guided code and + avoid doing JIT compilation at runtime for methods already compiled. Methods + that get JIT-compiled during the new runs will be added to the profile, which + will then be picked up by the compilation daemon.</li> +</ol> + +<p>ART comprises a compiler (the <code>dex2oat</code> tool) and a runtime +(<code>libart.so</code>) that is loaded for starting the Zygote. The +<code>dex2oat</code> tool takes an APK file and generates one or more +compilation artifact files that the runtime loads. The number of files, their +extensions, and names are subject to change across releases, but as of the +Android O release, the files being generated are:</p> <ul> - <li> Performance is improved over Dalvik. There is also a commensurate improvement -in power consumption measured in the lab. - <li> There is no runtime code cache. The OAT files are mapped to memory (and are -thus page-able). The RAM memory footprint for OAT files might seem larger in -terms of Proportional Set Size (PSS, or the memory shared across processes -divided evenly between the processes). But because they are pageable we have -found the system impact is improved in terms of real memory pressure effects as -the Dalvik JIT cache was not pageable. - <li> Similar to preloaded classes in the zygote, ART attempts to pre-initialize a -set of classes at compile time. This creates a ‘boot.art’ file that comprises -an image of the compacted heap of pre-initialized classes and related objects. -This file is mapped into memory upon zygote startup. While this consumes -additional storage (typically 10MB), it speeds zygote startup and creates -opportunities for the system to swap out some preloaded classes under memory -pressure. This also contributes to improved <a -href="http://source.android.com/devices/tech/config/low-ram.html">low-RAM</a> performance -for ART, since in Dalvik much of this class information would have -been stored in dirty pages in the linear alloc space. - <li> Dex file compilation uses a tool called dex2oat and takes more time than -dexopt. The increase in time varies, but 2-3x increases in compile time are not -unusual. For example, apps that typically take a second to install using dexopt -might take 2-3 seconds. - <li> OAT files are larger than odex files if full compilation is enabled. We discuss -options to mitigate this cost later in this document. +<li><code>.vdex</code>: contains the uncompressed DEX code of the + APK, with some additional metadata to speed up verification.</li> +<li><code>.odex</code>: contains AOT compiled code for methods in the + APK.</li> +<li><code>.art (optional)</code>: contains ART internal + representations of some strings and classes listed in the APK, used to speed + application startup. </li> </ul> <h2 id=compilation_options>Compilation options</h2> -<p>Dex file compilation takes more time than dexopt, which can be noticeable when -all of a user’s apps must be compiled during first boot (after factory reset or -after receiving an OTA). To reduce the amount of compilation needed, ART -supports the option of pre-optimizing libraries and applications in the system -partition. Including the pre-optimized dex files takes space in the system -image, so these options trade first boot time for system image size. Note that -OTAs are relatively infrequent and subsequent boot times should be the same -with or without pre-optimization.</p> - -<h3 id=undefined>WITH_DEXPREOPT</h3> - -<p>Pre-optimization is controlled by the build option -<code>WITH_DEXPREOPT</code>. Before the L release, this was enabled by default -in “user” builds. Starting in L, this option is opt-in and needs to be enabled -in the product configuration such as a device’s BoardConfig.mk file.</p> - -<p>Enabling <code>WITH_DEXPREOPT</code> causes everything in the system image to be -pre-optimized. If this makes the system image too large, additional options can -be specified to reduce the amount of pre-optimization. Note that all the -following build options with “PREOPT” in the name must have <code>WITH_DEXPREOPT</code> -enabled to work.</p> - -<p>Example usage (in product’s BoardConfig.mk):</p> - -<pre class="devsite-click-to-copy">WITH_DEXPREOPT := true</pre> - -<h3 id=dont_dexpreopt_prebuilts>DONT_DEXPREOPT_PREBUILTS</h3> +<p>Compilation options for ART are of two categories: +<ol> +<li>System ROM configuration: what code gets AOT-compiled when building a + system image.</li> +<li>Runtime configuration: how ART compiles and runs applications on a + device.</li> +</ol> +</p> + +<p>One core ART option to configure these two categories is <em>compiler +filters</em>. Compiler filters drive how ART compiles DEX code and is an +option passed to the <code>dex2oat</code> tool. Starting in Android O, there +are four officially supported filters:</p> +<ul> +<li><em>verify</em>: only run DEX code verification.</li> +<li><em>quicken</em>: run DEX code verification and optimize some DEX + instructions to get better interpreter performance.</li> +<li><em>speed</em>: run DEX code verification and AOT-compile all methods.</li> +<li><em>speed-profile</em>: run DEX code verification and AOT-compile methods + listed in a profile file.</li> +</ul> -<p>Enabling <code>DONT_DEXPREOPT_PREBUILTS</code> prevents the prebuilts from being -pre-optimized. These are apps that have <code>include $(BUILD_PREBUILT)</code> specified -in their Android.mk, such as Gmail. Skipping pre-optimization of prebuilt apps -that are likely to be updated via Google Play saves /system space but does add -to first boot time.</p> +<h3 id=system_rom>System ROM configuration</h3> -<p>Example usage (in product’s BoardConfig.mk):</p> +<p>There are a number of ART build options available for configuring a system +ROM. How to configure these options depends on the available storage space for +<code>/system</code> and the number of pre-installed applications. The +JARs/APKs that are compiled into a system ROM can be divided in four +categories:</p> +<ul> +<li>Boot classpath code: compiled with the <em>speed</em> compiler filter by + default.</li> +<li>System server code: compiled with the <em>speed</em> compiler filter by + default.</li> +<li>Product-specific core applications: compiled with the <em>speed</em> + compiler filter by default.</li> +<li>All other applications: compiled with the <em>quicken</em> compiler filter + by default.</li> +</ul> -<pre class="devsite-click-to-copy"> -WITH_DEXPREOPT := true -DONT_DEXPREOPT_PREBUILTS := true -</pre> +<h4 id=build_options>Makefile options</h4> +<ul> -<h3 id=with_dexpreopt_boot_img_only>WITH_DEXPREOPT_BOOT_IMG_ONLY</h3> +<li><code>WITH_DEXPREOPT</code></li> +<p> +Whether <code>dex2oat</code> is invoked on DEX code installed on the system image. Enabled by default. +</p> -<p>Enabling <code>WITH_DEXPREOPT_BOOT_IMG_ONLY</code> only pre-optimizes the -boot image, which consists of boot.art with the image classes and boot.oat with -code for the boot classpath. Enabling this saves significant /system space but -means all apps will be optimized at first boot. Typically it is better to -selectively disable app pre-optimization via -<code>DONT_DEXPREOPT_PREBUILTS</code> or add-product-dex-preopt-module-config.</p> +<li><code>DONT_DEXPREOPT_PREBUILTS</code> (since Android 5.0)</li> +<p> +Enabling <code>DONT_DEXPREOPT_PREBUILTS</code> prevents the prebuilts from being +pre-optimized. These are apps that have <code>include $(BUILD_PREBUILT)</code> +specified in their <code>Android.mk</code>, such as Gmail. Skipping +pre-optimization of prebuilt apps that are likely to be updated via Google Play +saves <code>/system</code> space but does add to first boot time. +</p> -<p>Example usage (in product’s BoardConfig.mk):</p> +<li><code>WITH_DEXPREOPT_BOOT_IMG_ONLY</code></li> -<pre class="devsite-click-to-copy"> -WITH_DEXPREOPT := true -WITH_DEXPREOPT_BOOT_IMG_ONLY := true -</pre> +<p>Enabling <code>WITH_DEXPREOPT_BOOT_IMG_ONLY</code> pre-optimizes only the +boot classpath. -<h3 id=local_dex_preopt>LOCAL_DEX_PREOPT</h3> +<li><code>LOCAL_DEX_PREOPT</code></li> <p>Pre-optimization can also be enabled or disabled on an individual app basis by specifying the <code>LOCAL_DEX_PREOPT</code> option in the module definition. @@ -148,84 +147,69 @@ version upgrade OTAs since users may already have newer versions of apps in the data partition.</p> <p><code>LOCAL_DEX_PREOPT</code> supports the values ‘true’ or ‘false’ to -enable or disable pre-optimization respectively. In addition, ‘nostripping’ can -be specified if pre-optimization should not strip the classes.dex file from the -apk or jar file. Normally this file is stripped since it’s no longer needed -after pre-optimization, but this last option is necessary to allow third-party -APK signatures to remain valid.</p> - -<p>Example usage (in app’s Android.mk):</p> - -<pre class="devsite-click-to-copy"> -LOCAL_DEX_PREOPT := false -</pre> - -<h3 id=product_dex_preopt_*>PRODUCT_DEX_PREOPT_*</h3> - -<p>Beginning post-L release in the Android Open Source Project (AOSP), a number of -flags have been added that give further control to how pre-optimization is -done. <code>PRODUCT_DEX_PREOPT_BOOT_FLAGS</code> passes options to dex2oat to control how -the boot image is compiled. It can be used to specify customized image classes -lists, compiled classes lists, and compiler filters, all of which are described -in later sections. Similarly, <code>PRODUCT_DEX_PREOPT_DEFAULT_FLAGS</code> -controls default flags to pass to dex2oat for compilation of everything besides -the boot image, namely jar and apk files.</p> - -<p><code>PRODUCT_DEX_PREOPT_MODULE_CONFIGS</code> provides the ability to pass -dex2oat options for a particular module and product configuration. It is set in -a product’s device.mk file by <code>$(call -add-product-dex-preopt-module-config,<modules>,<option>)</code> -where <modules> is a list of <code>LOCAL_MODULE</code> and -<code>LOCAL_PACKAGE</code> names for jar and apk files respectively. Through -this flag, it is possible to have fine-grained control of pre-optimization for -each dex file and a specific device. Such tuning allows /system space to be -maximally used to improve first boot time.</p> - -<p>Example usage (in product’s device.mk):</p> - -<pre class="devsite-click-to-copy"> -PRODUCT_DEX_PREOPT_DEFAULT_FLAGS := --compiler-filter=interpret-only -$(call add-product-dex-preopt-module-config,services,--compiler-filter=space) -</pre> - -<p>These flags can also be used to selectively disable pre-optimization of a -particular module or package by specifying <code>$(call -add-product-dex-preopt-module-config,<modules>,disable)</code> in a -product's device.mk file.</p> - -<p>Example usage (in product’s device.mk):</p> - -<pre class="devsite-click-to-copy"> -$(call add-product-dex-preopt-module-config,Calculator,disable) -</pre> +enable or disable pre-optimization, respectively. In addition, ‘nostripping’ can +be specified if pre-optimization should not strip the <code>classes.dex</code> +file from the APK or JAR file. Normally this file is stripped since it’s no +longer needed after pre-optimization, but this last option is necessary to +allow third-party APK signatures to remain valid.</p> + +<li><code>PRODUCT_DEX_PREOPT_BOOT_FLAGS</code></li> +<p> +Passes options to <code>dex2oat</code> to control how the boot image is +compiled. It can be used to specify customized image classes lists, compiled +classes lists, and compiler filters. +</p> + +<li><code>PRODUCT_DEX_PREOPT_DEFAULT_FLAGS</code></li> +<p> +Passes options to <code>dex2oat</code> to control how everything besides the +boot image is compiled. +</p> + +<li><code>PRODUCT_DEX_PREOPT_MODULE_CONFIGS</code></li> +<p> +Provides the ability to pass <code>dex2oat</code> options for a particular +module and product configuration. It is set in a product’s +<code>device.mk</code> file by <code>$(call add-product-dex-preopt-module-config,<modules>,<option>)</code> +where <code><modules></code> is a list of LOCAL_MODULE and LOCAL_PACKAGE names +for JAR and APK files, respectively. +</p> + +<li><code>PRODUCT_DEXPREOPT_SPEED_APPS (New in Android O)</code></li> +<p> +List of applications that have been identified as core to the products and +which are desirable to compile with the <em>speed</em> compiler filter. For +example, persistent apps such as SystemUI get a chance to use +profile-guided compilation only at the next reboot, so it may be better for the +product to have these apps always AOT-compiled. +</p> + +<li><code>PRODUCT_SYSTEM_SERVER_APPS (New in Android O)</code></li> +<p> +List of applications that are loaded by the system server. These applications +will be compiled by default with the <em>speed</em> compiler filter. +</p> + +<li><code>WITH_DEXPREOPT_PIC (Removed in Android O)</code></li> -<h2 id=other_odex>First boot installation of DEX_PREOPT files</h2> +<p>In Android 5.1.0 through Android 6.0.1, <code>WITH_DEXPREOPT_PIC</code> can +be specified to enable position-independent code (PIC). With this, compiled +code from the image doesn’t have to be relocated from /system into +/data/dalvik-cache, saving space in the data partition. However, there is a +slight runtime impact because it disables an optimization that takes advantage +of position-dependent code. Typically, devices wanting to save space in /data +should enable PIC compilation.</p> -<p>Starting in Android 7.0, devices may use two system partitions to enable -<a href="/devices/tech/ota/ab_updates.html">A/B system updates</a>. -To allow use of DEX_PREOPT while keeping the size of system partitions down and allowing -performant first boot, the preopted files can be installed in the unused second system -partition. They are then copied to the data partition on first boot.</p> +<p>In Android 7.0, PIC compilation was enabled by default.</p> -<p>Example usage (in device-common.mk):</p> +</ul> -<pre class="devsite-click-to-copy"> -PRODUCT_PACKAGES += \ - cppreopts.sh -PRODUCT_PROPERTY_OVERRIDES += \ - ro.cp_system_other_odex=1 -</pre> -<p>And in device's BoardConfig.mk:</p> -<pre class="devsite-click-to-copy"> -BOARD_USES_SYSTEM_OTHER_ODEX := true -</pre> -<p>See <a href="/devices/tech/ota/ab_updates.html#compilation">App -compilation in background</a> to optionally include the compilation script and -binaries in the system image.</p> +<h4 id=boot_classpath>Boot classpath configuration</h4> -<h2 id=preloaded_classes_list>Preloaded Classes List</h2> +<ul> +<li>Preloaded Classes List</li> <p>The preloaded classes list is a list of classes the zygote will initialize on startup. This saves each app from having to run these class initializers @@ -244,10 +228,10 @@ PRODUCT_COPY_FILES += <filename>:system/etc/preloaded-classes </pre> <p class="note"><strong>Note:</strong> This line must be placed before -inheriting any product configuration makefiles that get the default one from -build/target/product/base.mk.</p> +inheriting any product configuration makefiles that get the default one from: +<code>build/target/product/base.mk</code></p> -<h2 id=image_classes_list>Image Classes List</h2> +<li>Image Classes List</li> <p>The image classes list is a list of classes that dex2oat initializes ahead of time and stores in the boot.art file. This allows the zygote to load these @@ -256,16 +240,19 @@ for these classes itself during preloading. A key feature of this is that the pages loaded from the image and shared between processes can be clean, allowing them to be swapped out easily in low-memory situations. In L, by default the image classes list uses the same list as the preloaded classes list. Beginning -post-L in AOSP, a custom image classes list can be specified using -<code>PRODUCT_DEX_PREOPT_BOOT_FLAGS</code>.</p> +post-L in AOSP, a custom image classes list can be specified using:</p> -<p>Example usage (in product’s device.mk):</p> +<pre class="devsite-click-to-copy"> +PRODUCT_DEX_PREOPT_BOOT_FLAGS +</pre> + +<p>Example use (in product’s <code>device.mk</code>):</p> <pre class="devsite-click-to-copy"> PRODUCT_DEX_PREOPT_BOOT_FLAGS += --image-classes=<filename> </pre> -<h2 id=compiled_classes_list>Compiled Classes List</h2> +<li>Compiled Classes List</li> <p>In post-L AOSP, a subset of classes from the boot classpath can be specified to be compiled during pre-optimization using the compiled classes list. This can @@ -275,93 +262,104 @@ list will not be compiled - not even on the device - and must be interpreted, potentially affecting runtime performance. By default, dex2oat will look for a compiled classes list in $OUT/system/etc/compiled-classes, so a custom one can be copied to that location by the device.mk. A particular file location can -also be specified using <code>PRODUCT_DEX_PREOPT_BOOT_FLAGS</code>.</p> +also be specified using: -<p>Example usage (in product’s device.mk):</p> +<pre class="devsite-click-to-copy"> +PRODUCT_DEX_PREOPT_BOOT_FLAGS +</pre> + +<p>Example usage (in product’s <code>device.mk</code>):</p> <pre class="devsite-click-to-copy"> PRODUCT_COPY_FILES += <filename>:system/etc/compiled-classes </pre> <p class="note"><strong>Note:</strong> This line must be placed before -inheriting any product configuration makefiles that get the default one from -build/target/product/base.mk.</p> - -<h2 id=compiler_filters>Compiler Filters</h2> - -<p>In L, dex2oat takes a variety of --compiler-filter options to control how it -compiles. Passing in a compiler filter flag for a particular app specifies how -it’s pre-optimized. Here’s a description of each available option:</p> - -<ul> - <li><em>everything</em> - compiles almost everything, excluding class initializers and some rare -methods that are too large to be represented by the compiler’s internal -representation. - <li><em>speed</em> - compiles most methods and maximizes runtime performance, which is the -default option. - <li><em>speed-profile</em> - compiles methods passed from a profile file - through the <em>--profile-file</em> option or <em>--profile-file-fd</em> option. - <li><em>balanced</em> - attempts to get the best performance return on compilation investment. - <li><em>space</em> - compiles a limited number of methods, prioritizing storage space. - <li><em>interpret-only</em> - skips all compilation and relies on the interpreter to run code. - <li><em>verify-profile</em> - skips all compilation and only performs verification of methods passed - from a profile file through the <em>--profile-file</em> option or <em>--profile-file-fd</em> option. - <li><em>verify-none</em> - special option that skips verification and compilation, should be used only -for trusted system code. +inheriting any product configuration makefiles that get the default one from: +<code>build/target/product/base.mk</code></p> </ul> -<h2 id=with_dexpreopt_pic>WITH_DEXPREOPT_PIC</h2> - -<p>In Android 5.1.0 through Android 6.0.1, <code>WITH_DEXPREOPT_PIC</code> can -be specified to enable position-independent code (PIC). With this, compiled -code from the image doesn’t have to be relocated from /system into -/data/dalvik-cache, saving space in the data partition. However, there is a -slight runtime impact because it disables an optimization that takes advantage -of position-dependent code. Typically, devices wanting to save space in /data -should enable PIC compilation.</p> - -<p>Example usage (in product’s device.mk):</p> +<h3 id=runtime_configuration>Runtime configuration</h3> -<pre class="devsite-click-to-copy"> -WITH_DEXPREOPT := true -WITH_DEXPREOPT_PIC := true -</pre> +<h4 id=undefined>Jit options</h4> -<p>Starting in Android 7.0, PIC compilation is enabled by default.</p> +<p>The following options affect Android releases only where the ART JIT compiler +is available.</p> -<h2 id=with_art_small_mode>WITH_ART_SMALL_MODE</h2> +<ul> +<li>dalvik.vm.usejit: whether or not the JIT is enabled.</li> +<li>dalvik.vm.jitinitialsize (default 64K): the initial capacity +of the code cache. The code cache will regularly GC and increase if needed. +<li>dalvik.vm.jitmaxsize (default 64M): the maximum capacity of the code cache. +<li>dalvik.vm.jitthreshold: (default 10000) - This +is the threshold that the "hotness" counter of a method needs to pass in order +for the method to be JIT compiled. The "hotness" counter is a metric internal +to the runtime. It includes the number of calls, backward branches, and other +factors. +<li>dalvik.vm.usejitprofiles: whether or not +JIT profiles are enabled; this may be used even if dalvik.vm.usejit is false. +Note that if this is false, the compiler filter <em>speed-profile</em> does +not AOT-compile any method and is equivalent to <em>quicken</em>. +<li>dalvik.vm.jitprithreadweight (default to +dalvik.vm.jitthreshold / 20) - The weight of the JIT "samples" +(see jitthreshold) for the application UI thread. Use to speed up compilation +of methods that directly affect users experience when interacting with the +app. +<li>dalvik.vm.jittransitionweight: (default to dalvik.vm.jitthreshold / 10) +the weight of the method +invocation that transitions between compile code and interpreter. This helps +make sure the methods involved are compiled to minimize transitions (which are +expensive). +</li> +</ul> -<p>For devices with very limited space, <code>WITH_ART_SMALL_MODE</code> can be -enabled. This option compiles the boot classpath and nothing else, greatly -reducing first boot time since most compilation is skipped. It also saves on -storage because there is no compiled code for apps. However, this impacts -runtime performance since app code has to be interpreted. The impact is limited -since most performance sensitive code in the framework is still compiled, but -regressions may appear in benchmarking.</p> +<h4 id=undefined>Package manager options</h4> -<p>Example usage (in product’s device.mk):</p> +<p> +Since Android 7.0, there's a generic way to specify the level of +compilation/verification that happened at various stages. +The compilation levels can be configured via system properties +with the defaults being: +</p> -<pre class="devsite-click-to-copy"> -WITH_ART_SMALL_MODE := true -</pre> +<ul> +<li>pm.dexopt.install=quicken</li> +<p>This is the compilation filter used when installing applications through Google +Play. For faster installs, try the <em>quicken</em> compiler filter. +</p> +<li>pm.dexopt.bg-dexopt=speed-profile</li> +<p> +This is the compilation filter used when the device is idle, charging and +fully charged. Try the <em>speed-profile</em> compiler filter +to take advantage of profile-guided compilation and save on storage. +</p> +<li>pm.dexopt.boot=verify</li> +<p> +The compilation filter used after an over-the-air update. We +<strong>strongly</strong> recommend the <em>verify</em> compiler filter for this +option to avoid very long boot times. +</p> +<li>pm.dexopt.first-boot=quicken<li> +<p> +The compilation filter for the first time the device ever boots. The filter +used here will only affect the boot time after factory. We recommend the filter +<em>quicken</em> for it to avoid long times before a user gets to +use the phone for the very first time. Note that if all applications in +<code>/system</code> are already compiled with the <em>quicken</em> compiler +filter or are compiled with the <em>speed</em> or <em>speed-profile</em> +compiler filter, the <code>pm.dexopt.first-boot</code> has no effect. +</p> -<p>In future releases, this build option will be removed since it can be done with -this (in product’s device.mk):</p> +</ul> -<pre class="devsite-click-to-copy"> -PRODUCT_PROPERTY_OVERRIDES += \ - dalvik.vm.dex2oat-filter=interpret-only \ - dalvik.vm.image-dex2oat-filter=speed -</pre> +<h4 id=undefined>Dex2oat options</h4> -<h2 id=dalvik_vm_properties>dalvik.vm Properties</h2> -<p>Most dalvik.vm properties in ART are similar to Dalvik, but there are a few -additional ones as described below. Note that these options affect dex2oat +<p>Note that these options affect <code>dex2oat</code> during on-device compilation as well as during pre-optimization, whereas most of the options discussed above affect only pre-optimization.</p> -<p>To control dex2oat while it’s compiling the boot image:</p> +<p>To control <code>dex2oat</code> while it’s compiling the boot image:</p> <ul> <li>dalvik.vm.image-dex2oat-Xms: initial heap size @@ -370,7 +368,7 @@ of the options discussed above affect only pre-optimization.</p> <li>dalvik.vm.image-dex2oat-threads: number of threads to use </ul> -<p>To control dex2oat while it’s compiling everything besides the boot image:</p> +<p>To control <code>dex2oat</code> while it’s compiling everything besides the boot image:</p> <ul> <li>dalvik.vm.dex2oat-Xms: initial heap size @@ -398,125 +396,65 @@ compiling everything besides the boot image:</p> <li>dalvik.vm.dex2oat-swap: use dex2oat swap file (for low-memory devices) </ul> -<p>The options that control initial and maximum heap size for dex2oat should not -be reduced since they could limit what applications can be compiled.</p> +<p>The options that control initial and maximum heap size for +<code>dex2oat</code> should not be reduced since they could limit what +applications can be compiled.</p> -<h2 id=sample_usage>Sample Usage</h2> +<h2 id=other_odex>A/B specific configuration</h2> -<p>The goal of these compiler options is to utilize available space in the system -and data partition to reduce the amount of dex2oat that must be performed by -the device. </p> +<h3 id=undefined>ROM configuration</h3> -<p>For devices with ample system and data space, enabling dex pre-optimization is -all that is necessary. - -<p>BoardConfig.mk:</p> - -<pre class="devsite-click-to-copy"> -WITH_DEXPREOPT := true -</pre> - -<p>If this causes the system image to become too large, the next thing to try is -disabling pre-optimization of the prebuilts. - -<p>BoardConfig.mk:</p> - -<pre class="devsite-click-to-copy"> -WITH_DEXPREOPT := true -DONT_DEXPREOPT_PREBUILTS := true -</pre> - -<p>Again, if the system image is still too large, try pre-optimizing only the boot -image. - -<p>BoardConfig.mk:</p> - -<pre class="devsite-click-to-copy"> -WITH_DEXPREOPT := true -WITH_DEXPREOPT_BOOT_IMG_ONLY := true -</pre> - -<p>However, limiting to pre-optimizing only the boot-image means all apps will -have to be optimized on first boot. In order to avoid this, it is possible to -combine these high level flags with more fine-grained controls to maximize the -amount of pre-optimized apps.</p> - -<p>For instance, if disabling the pre-optimization of the prebuilts almost fits -into the system partition, compiling the boot classpath with the ‘space’ option -may make it fit. Note this compiles fewer methods in the boot classpath, -potentially interpreting more code and impacting runtime performance. - -<p>BoardConfig.mk:</p> - -<pre class="devsite-click-to-copy"> -WITH_DEXPREOPT := true -DONT_DEXPREOPT_PREBUILTS := true -</pre> - -<p>device.mk:</p> - -<pre class="devsite-click-to-copy"> -PRODUCT_DEX_PREOPT_BOOT_FLAGS := --compiler-filter=space -</pre> - -<p>If a device has very limited system partition space, it’s possible to compile a -subset of classes in the boot classpath using the compiled classes list. Boot -classpath methods that aren’t in this list will have to be interpreted, which -could affect runtime performance. +<p>Starting in Android 7.0, devices may use two system partitions to enable +<a href="/devices/tech/ota/ab_updates.html">A/B system updates</a>. +To save on the system partition size, the preopted files can be installed in +the unused second system partition. They are then copied to the data partition +on first boot.</p> -<p>BoardConfig.mk:</p> +<p>Example usage (in <code>device-common.mk</code>):</p> <pre class="devsite-click-to-copy"> -WITH_DEXPREOPT := true -WITH_DEXPREOPT_BOOT_IMG_ONLY := true +PRODUCT_PACKAGES += \ + cppreopts.sh +PRODUCT_PROPERTY_OVERRIDES += \ + ro.cp_system_other_odex=1 </pre> -<p>device.mk:</p> +<p>And in device's <code>BoardConfig.mk</code>:</p> <pre class="devsite-click-to-copy"> -PRODUCT_COPY_FILES += <filename>:system/etc/compiled-classes +BOARD_USES_SYSTEM_OTHER_ODEX := true </pre> -<p>If a device has both limited space in the system and data partitions, compiler -filter flags can be used to disable compilation of certain apps. This will save -space in both system and data, as there won’t be any compiled code, but these -apps will have to be interpreted. This example configuration would pre-optimize -the boot classpath but prevent compilation of other apps that are not -prebuilts. However, to prevent noticeable performance degradation of -system_server, the services.jar is still compiled but optimized for space. Note -that user-installed applications will still use the default compiler filter of -speed. - -<p>BoardConfig.mk:</p> +<p> +Note that boot classpath code, system server code, and product-specific core +applications always compile to the system partition. By default, all other +applications get compiled to the unused second system partition. This can be +controlled with the <code>SYSTEM_OTHER_ODEX_FILTER</code>, which has a value by +default of:</p> <pre class="devsite-click-to-copy"> -WITH_DEXPREOPT := true -DONT_DEXPREOPT_PREBUILTS := true +SYSTEM_OTHER_ODEX_FILTER ?= app/% priv-app/% </pre> -<p>device.mk:</p> +<h3 id=undefined>Background dexopt OTA</h3> +<p>With A/B enabled devices, applications can be compiled in the background for +updating to the new system image. See <a +href="/devices/tech/ota/ab_updates.html#compilation">App compilation in +background</a> to optionally include the compilation script and +binaries in the system image. The compilation filter used for this compilation +is controlled with:</p> <pre class="devsite-click-to-copy"> -PRODUCT_DEX_PREOPT_DEFAULT_FLAGS := --compiler-filter=interpret-only -$(call add-product-dex-preopt-module-config,services,--compiler-filter=space) +pm.dexopt.ab-ota=speed-profile </pre> -<p>For a major version upgrade OTA, it can be useful to blacklist certain apps -from being pre-optimized since they will likely be out of date. This can be -done by specifying <code>LOCAL_DEX_PREOPT</code> (for all products) or with -<code>PRODUCT_DEX_PREOPT_MODULE_CONFIGS</code> (for a particular product). +<p> +We recommend using <em>speed-profile</em> to take advantage of profile guided +compilation and save on storage. +</p> -<p>BoardConfig.mk:</p> -<pre class="devsite-click-to-copy"> -WITH_DEXPREOPT := true -</pre> -<p>Android.mk (of blacklisted apps):</p> - -<pre class="devsite-click-to-copy"> -LOCAL_DEX_PREOPT := false -</pre> </body> </html> diff --git a/en/devices/tech/dalvik/jit-compiler.html b/en/devices/tech/dalvik/jit-compiler.html index 9090349c..74ac6de0 100644 --- a/en/devices/tech/dalvik/jit-compiler.html +++ b/en/devices/tech/dalvik/jit-compiler.html @@ -46,12 +46,6 @@ do OSR compilation (on stack replacement) which will again generate a bit different code. </p> -<p> -See <a -href="https://developer.android.com/preview/api-overview.html#jit_aot">Profile-guided -JIT/AOT Compilation</a> on developer.android.com for a more thorough overview. -</p> - <h2 id="architectural-overview">Architectural Overview</h2> <img src="/devices/tech/dalvik/images/jit-arch.png" alt="JIT architecture" width="633" id="JIT-architecture" /> @@ -132,82 +126,7 @@ memory than small apps. In general, big apps stabilize around 4 MB.</li></ul> </li> </ul> -<h2 id="system-properties">System Properties</h2> - -<p> -These system properties control JIT behavior: -</p><ul> -<li><code>dalvik.vm.usejit <true|false></code> - Whether or not the JIT is -enabled. -<li><code>dalvik.vm.jitinitialsize</code> (default 64K) - The initial capacity -of the code cache. The code cache will regularly GC and increase if needed. It -is possible to view the size of the code cache for your app with:<br> -<code> $ adb shell dumpsys meminfo -d <pid></code> -<li><code>dalvik.vm.jitmaxsize</code> (default 64M) - The maximum capacity of -the code cache. -<li><code>dalvik.vm.jitthreshold <integer></code> (default 10000) - This -is the threshold that the "hotness" counter of a method needs to pass in order -for the method to be JIT compiled. The "hotness" counter is a metric internal -to the runtime. It includes the number of calls, backward branches & other -factors. -<li><code>dalvik.vm.usejitprofiles <true|false></code> - Whether or not -JIT profiles are enabled; this may be used even if usejit is false. -<li><code>dalvik.vm.jitprithreadweight <integer></code> (default to -<code>dalvik.vm.jitthreshold</code> / 20) - The weight of the JIT "samples" -(see jitthreshold) for the application UI thread. Use to speed up compilation -of methods that directly affect users experience when interacting with the -app. -<li><code>dalvik.vm.jittransitionweight <integer></code> -(<code>dalvik.vm.jitthreshold</code> / 10) - The weight of the method -invocation that transitions between compile code and interpreter. This helps -make sure the methods involved are compiled to minimize transitions (which are -expensive). -</li> -</ul> - -<h2 id="tuning">Tuning</h2> - -<p> -Device implementers may precompile (some of) the system apps if they want so. -Initial JIT performance vs pre-compiled depends on the app, but in general -they are quite close. It might be worth noting that precompiled apps will not -be profiled and as such will take more space and may miss on other -optimizations. -</p> - -<p> -In Android 7.0, there's a generic way to specify the level of -compilation/verification based on the different use cases. For example, the -default option for install time is to do only verification (and postpone -compilation to a later stage). The compilation levels can be configured via -system properties with the defaults being: -</p> - -<pre class="devsite-click-to-copy"> -pm.dexopt.install=interpret-only -pm.dexopt.bg-dexopt=speed-profile -pm.dexopt.ab-ota=speed-profile -pm.dexopt.nsys-library=speed -pm.dexopt.shared-apk=speed -pm.dexopt.forced-dexopt=speed -pm.dexopt.core-app=speed -pm.dexopt.first-boot=interpret-only -pm.dexopt.boot=verify-profile -</pre> - -<p> -See the <a href="#recommendation">Recommendation</a> section for use. -</p> - -<p> -Note the reference to A/B over-the-air (OTA) updates here. -</p> - -<p> -Check <code>$ adb shell cmd package compile</code> for usage. Note all commands -in this document are preceded by a dollar ($) sign that should be excluded when -copying and pasting. A few common use cases: -</p> +<h2 id="tuning">Useful tips</h2> <h3 id="turn-on-jit-logging">Turn on JIT logging</h3> @@ -230,6 +149,10 @@ copying and pasting. A few common use cases: <h3 id="force-compilation-of-a-specific-package">Force compilation of a specific package</h3> +<p> +Check <code>$ adb shell cmd package compile</code> for usage. A few common use cases: +</p> + <ul> <li>Profile-based: <pre class="devsite-terminal devsite-click-to-copy"> @@ -275,142 +198,5 @@ adb shell cmd package compile --reset -a </li> </ul> -<h2 id="recommendation">Recommendation</h2> - -<h3 id="runtime_compilation_level">Level of compilation/verification</h3> - -<p> -Note that it is strongly recommended to use the default following -<code>pm.dexopt</code> settings and it is the only path we have tested and will -support. -</p> - -<pre class="devsite-click-to-copy"> -pm.dexopt.install=interpret-only -pm.dexopt.bg-dexopt=speed-profile -pm.dexopt.boot=verify-profile (or interpret-only) -</pre> - -<p> -Here’s a detailed explanation about the <code>pm.dexopt</code> options, and the -reasoning for our recommendations: -</p> - -<pre class="devsite-click-to-copy"> -pm.dexopt.install -</pre> - -<p> -This is the compilation filter used when installing application through the -Play Store. For faster installs we recommend <code>interpret-only</code>. -</p> - -<pre class="devsite-click-to-copy"> -pm.dexopt.bg-dexopt -</pre> - -<p> -This is the compilation filter used when the device is idle and charging and -fully charged. We recommend using <code>speed-profile</code> to take advantage -of profile guided compilation and save on storage. -</p> - -<pre class="devsite-click-to-copy"> -pm.dexopt.ab-ota -</pre> - -<p> -This is the compilation filter used when doing an A/B over-the-air (OTA) -update. If the device supports A/B OTA, we recommend using -<code>speed-profile</code> to take advantage of profile guided compilation and -save on storage. -</p> - -<pre class="devsite-click-to-copy"> -pm.dexopt.nsys-library -pm.dexopt.shared-apk -pm.dexopt.core-app -</pre> - -<p> -You can use these different options to control how to compile essentially -applications used by other applications. For such applications, we recommend -the <code>speed</code> filter, as the platform does not support efficient -profiling of them. -</p> - -<pre class="devsite-click-to-copy"> -pm.dexopt.first-boot -</pre> - -<p> -The compilation filter for the first time the device ever boots. The filter -used here will only affect the boot time after factory. We recommend the filter -<code>interpret-only</code> for it, to avoid long times before a user gets to -use the phone for the very first time. Note that if all applications in /system -are already speed compiled, <code>pm.dexopt.first-boot</code> has no effect. -</p> - -<pre class="devsite-click-to-copy"> -pm.dexopt.boot -</pre> - -<p> -The compilation filter used after an over-the-air update. We -<strong>strongly</strong> recommend <code>verify-profile</code> for this -option, to avoid very long updates. -</p> - -<h3 id="system_image_compilation_level">System image</h3> - -<p> -This section gives recommendations on how to minimize the system image size -while retaining the highest possible level of performance. -Note these complement the above guidelines on the -<a href="#runtime_compilation_level">level of compilation/verification</a>. -</p> - -<p> -System image size can be reduced by opting for a lower level of compilation for -prebuilts. To achieve the best compromise between app performance and image size, -we strongly recommend compiling prebuilts with the <code>interpret-only</code> -filter. To do this, edit the following files to include these entries. -</p> - -<p>Add the following entry to <code>BoardConfig.mk</code>:</p> - -<pre class="devsite-click-to-copy"> -WITH_DEXPREOPT := true -</pre> - -<p>Add the following entry to <code>device.mk</code>:</p> - -<pre class="devsite-click-to-copy"> -PRODUCT_DEX_PREOPT_DEFAULT_FLAGS := --compiler-filter=interpret-only -</pre> - -<p> -Using the <code>interpret-only</code> filter will reduce the optimized code -size for prebuilts by roughly half (depending on the application) when -compared with the <code>speed</code> filter. It also allows the runtime to -profile the prebuilts and perform profile-guided compilation to further -save on data partition storage. -</p> - -<p> -We advise against using a lower compilation/verification level -(e.g. <code>verify-none</code>) or disabling the optimization for prebuilts -as an effort to further save space on the system image. That will lead to slower -application startup and increased memory consumption. -</p> - -<h2 id="validation">Validation</h2> - -<p> -To ensure their version of the feature works as intended, device implementers -should run the ART test in <code>android/art/test</code>. Also, see the CTS -test <code>hostsidetests/compilation</code> for userdedug builds. -</p> - </body> </html> diff --git a/en/devices/tech/debug/dumpsys.html b/en/devices/tech/debug/dumpsys.html deleted file mode 100644 index e87722ba..00000000 --- a/en/devices/tech/debug/dumpsys.html +++ /dev/null @@ -1,109 +0,0 @@ -<html devsite> - <head> - <title>Dumpsys System Diagnostics</title> - <meta name="project_path" value="/_project.yaml" /> - <meta name="book_path" value="/_book.yaml" /> - </head> - <body> - <!-- - Copyright 2017 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. - --> - - - -<p>The <code>dumpsys</code> tool runs on the device and provides information about the status -of system services. </p> - -<h2 id=how_to_use_dumpsys>How to use dumpsys</h2> - -<p>If you run <code>adb shell dumpsys</code>, you’ll get diagnostic output for -all system services, which is usually more than you want. For more manageable -output, specify the service you would like to examine. </p> - -<p>For example, the following command:</p> - -<pre class="devsite-terminal devsite-click-to-copy"> -adb shell dumpsys input -</pre> - -<p>provides system data for input components such as touchscreens or built-in -keyboards.</p> - -<h2 id=list_of_system_services>List of system services</h2> - - -<p>For a complete list of system services that you can use with dumpsys, try the -following command:</p> - -<pre class="devsite-terminal devsite-click-to-copy"> -adb shell dumpsys -l -</pre> - -<p>Example output:</p> -<pre class="devsite-click-to-copy"> -Currently running services: - DockObserver - SurfaceFlinger - accessibility - account - activity - alarm - android.security.keystore - appops - appwidget - assetatlas - audio - backup - battery - batteryproperties - batterystats - bluetooth_manager - clipboard - connectivity - consumer_ir - content - country_detector - cpuinfo - dbinfo -... -</pre> - -<h2 id=dumpsys_command-line_options>Dumpsys command-line options</h2> - -<p>Command-line options are different for different services. Here are a few -common ones:</p> - -<ul> - <li> For many services, you can append <code>-h</code> to see the help -text. - <li> For some services, you can append <code>-c</code> to view the data in -a machine-friendly format. </ul> - -<h2 id=understanding_diagnostic_output>Understanding diagnostic output</h2> - -<p>For details on some of the most commonly used dumpsys services, see the -following articles:</p> - -<ul> - <li> <a - href="/devices/input/diagnostics.html">Viewing Input Diagnostics (dumpsys input)</a> - <li> <a href="procstats.html">Viewing RAM Usage Data (dumpsys procstats)</a> - <li> <a href="netstats.html">Viewing Network Data (dumpsys netstats)</a> - <li> <a href="/devices/tech/power/batterystats.html">Viewing Battery Usage Data (dumpsys batterystats)</a> -</ul> - - - </body> -</html> diff --git a/en/devices/tech/debug/index.html b/en/devices/tech/debug/index.html index 268f24ee..5400bb9e 100644 --- a/en/devices/tech/debug/index.html +++ b/en/devices/tech/debug/index.html @@ -30,10 +30,10 @@ platform-level features.</p> <p>This page covers use of <code>debuggerd</code>, a daemon process for collecting error information after applications crash. Other pages in this section explore system services with -<a href="/devices/tech/debug/dumpsys.html">Dumpsys</a>, viewing +<a href="https://developer.android.com/studio/command-line/dumpsys.html">Dumpsys</a>, viewing <a href="/devices/tech/debug/native-memory.html">native memory</a>, -<a href="/devices/tech/debug/netstats.html">network</a>, and -<a href="/devices/tech/debug/procstats.html">RAM</a> usage, using +<a href="https://developer.android.com/studio/command-line/dumpsys.html#network">network</a>, and +<a href="https://developer.android.com/studio/command-line/dumpsys.html#procstats">RAM</a> usage, using <a href="/devices/tech/debug/asan.html">AddressSanitizer</a> to detect memory bugs in native code, evaluating <a href="/devices/tech/debug/eval_perf.html"> performance issues</a> (includes diff --git a/en/devices/tech/debug/netstats.html b/en/devices/tech/debug/netstats.html deleted file mode 100644 index 78ddef02..00000000 --- a/en/devices/tech/debug/netstats.html +++ /dev/null @@ -1,151 +0,0 @@ -<html devsite> - <head> - <title>Viewing Network Usage Data</title> - <meta name="project_path" value="/_project.yaml" /> - <meta name="book_path" value="/_book.yaml" /> - </head> - <body> - <!-- - Copyright 2017 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. - --> - - - -<p>Using the command <code>adb shell dumpsys netstats detail</code> provides -network usage statistics collected since the device booted up.</p> - -<h2 id=input>Input</h2> - - -<p>To view network usage statistics, run the following command:</p> - -<pre class="devsite-terminal devsite-click-to-copy"> -adb shell dumpsys netstats detail -</pre> - - -<h2 id=output>Output</h2> - - -<p>The set of information reported varies depending on the version of Android but -consists of several sections: </p> - -<ul> - <li> Active interfaces - <li> Active UID interfaces - <li> Dev statistics - <li> Xt statistics - <li> UID statistics (sometimes also called "Detailed UID statistics") - <li> UID tag statistics -</ul> - -<h3 id=active_interfaces_active_uid_interfaces>Active interfaces/Active UID interfaces</h3> - -<p>Here is sample output for the active interfaces and active UID interfaces -sections:</p> - -<pre class="devsite-click-to-copy"> -Active interfaces: - iface=wlan0 ident=[{type=WIFI, subType=COMBINED, networkId="GoogleGuest"}] -Active UID interfaces: - iface=wlan0 ident=[{type=WIFI, subType=COMBINED, networkId="GoogleGuest"}] -</pre> - - -<p>This shows network statistics for the whole device. In most cases, the -information in these two section is the same.</p> - -<h3 id=dev_stats_xt_stats>Dev statistics/Xt statistics</h3> - - -<p>Here is sample output for the Dev statistics section:</p> - -<pre class="devsite-click-to-copy"> -Dev stats: - Pending bytes: 170775 - Complete history: - ident=[[type=MOBILE_HIPRI, subType=COMBINED, subscriberId=311111...]] uid=-1 set=ALL tag=0x0 - NetworkStatsHistory: bucketDuration=3600000 - bucketStart=1406138400000 activeTime=3603995 rxBytes=19467 rxPackets=53 txBytes=7500 txPackets=61 operations=0 - bucketStart=1406142000000 activeTime=20730 rxBytes=25403 rxPackets=66 txBytes=9140 txPackets=74 operations=0 - bucketStart=1406145600000 activeTime=29161 rxBytes=9263 rxPackets=37 txBytes=5180 txPackets=38 operations=0 - bucketStart=1406149200000 activeTime=9054 rxBytes=12387 rxPackets=31 txBytes=4052 txPackets=35 operations=0 - ident=[[type=WIFI, subType=COMBINED, networkId="MySSID"]] uid=-1 set=ALL tag=0x0 - NetworkStatsHistory: bucketDuration=3600000 - bucketStart=1406138400000 activeTime=4811082 rxBytes=335913292 rxPackets=265144 txBytes=9729261 txPackets=117220 operations=0 - bucketStart=1406142000000 activeTime=3513477 rxBytes=1193606876 rxPackets=956855 txBytes=29450792 txPackets=306634 operations=0 - bucketStart=1406145600000 activeTime=3297986 rxBytes=729381849 rxPackets=586396 txBytes=24247211 txPackets=237438 operations=0 - bucketStart=1406149200000 activeTime=3580941 rxBytes=57168575 rxPackets=51610 txBytes=5291167 txPackets=29260 operations=0 - ident=[[type=WIFI, subType=COMBINED, networkId="MySecondSSID"]] uid=-1 set=ALL tag=0x0 - NetworkStatsHistory: bucketDuration=3600000 -</pre> - -<h3 id=uid_stats>UID stats</h3> - -<pre class="devsite-click-to-copy"> -UID stats: - Pending bytes: 744 - Complete history: - ident=[[type=MOBILE_SUPL, subType=COMBINED, subscriberId=311111...], [type=MOBILE, subType=COMBINED, subscriberId=311111...]] uid=10007 set=DEFAULT tag=0x0 - NetworkStatsHistory: bucketDuration=7200000 - bucketStart=1406167200000 activeTime=7200000 rxBytes=4666 rxPackets=7 txBytes=1597 txPackets=10 operations=0 - ident=[[type=WIFI, subType=COMBINED, networkId="MySSID"]] uid=10007 set=DEFAULT tag=0x0 - NetworkStatsHistory: bucketDuration=7200000 - bucketStart=1406138400000 activeTime=7200000 rxBytes=17086802 rxPackets=15387 txBytes=1214969 txPackets=8036 operations=28 - bucketStart=1406145600000 activeTime=7200000 rxBytes=2396424 rxPackets=2946 txBytes=464372 txPackets=2609 operations=70 - bucketStart=1406152800000 activeTime=7200000 rxBytes=200907 rxPackets=606 txBytes=187418 txPackets=739 operations=0 - bucketStart=1406160000000 activeTime=7200000 rxBytes=826017 rxPackets=1126 txBytes=267342 txPackets=1175 operations=35 -</pre> - - -<h3 id=interpreting_the_results>Interpreting the results</h3> - - -<p>To find the UID for your application, you can run this command: -<code>adb shell dumpsys package <your package name></code>. -Then look for the line labeled <code>userId</code>.</p> - -<p>In our example, suppose we are trying to find network usage for our app -“com.example.myapp”. We would run the following command:</p> - -<pre class="devsite-terminal devsite-click-to-copy"> -adb shell dumpsys package com.example.myapp | grep userId -</pre> -<p>This returns the following output:</p> -<pre class="devsite-click-to-copy"> - userId=10007 gids=[3003, 1028, 1015] -</pre> - -<p>Looking at the dump above, we look for lines that have uid=10007. Two such -lines exist, the first indicating a mobile connection, and the second a Wi-Fi -connection. Underneath each line, the number of bytes and packets sent and -received can be seen, bucketed into two-hour windows. </p> - -<p>A bit more explanation:</p> - -<ul> - <li> <code>set=DEFAULT</code> indicates foreground - network usage, while <code>set=BACKGROUND</code> indicates -background usage. <code>set=ALL</code> implies both. - <li> <code>tag=0x0</code> indicates the socket tag associated with the traffic. - <li> <code>rxBytes</code> and <code>rxPackets</code> represent received bytes and received packets in the -corresponding time interval. - <li> <code>txBytes</code> and <code>txPackets</code> represent sent (transmitted) bytes and sent packets in -the corresponding time interval. -</ul> - - - </body> -</html> diff --git a/en/devices/tech/debug/procstats.html b/en/devices/tech/debug/procstats.html deleted file mode 100644 index 285ea7e0..00000000 --- a/en/devices/tech/debug/procstats.html +++ /dev/null @@ -1,371 +0,0 @@ -<html devsite> - <head> - <title>Viewing RAM Usage Data (procstats)</title> - <meta name="project_path" value="/_project.yaml" /> - <meta name="book_path" value="/_book.yaml" /> - </head> - <body> - <!-- - Copyright 2017 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. - --> - - - -<p>The <code>procstats</code> tool is used to analyze application memory usage over time (versus at a -particular snapshot in time, like <code>meminfo</code>). Its state dump displays statistics about every application’s runtime, -proportional set size (PSS) and unique set size (USS).</p> - -<h2 id=input>Input</h2> - - -<p>To get application memory usage stats for the last three hours, in -human-readable form, run the following command:</p> - -<pre class="devsite-terminal devsite-click-to-copy"> -adb shell dumpsys procstats --hours 3 -</pre> - - - -<h2 id=output>Output</h2> - - -<p>As can be seen in the example below, percentages display what percentage of -time the application was running, while the numbers following show PSS and USS -as minPSS-avgPSS-maxPSS/minUSS-avgUSS-maxUSS over samples.</p> - -<pre class="devsite-click-to-copy"> -AGGREGATED OVER LAST 3 HOURS: - * com.android.systemui / u0a20 / v22: - TOTAL: 100% (109MB-126MB-159MB/108MB-125MB-157MB over 18) - Persistent: 100% (109MB-126MB-159MB/108MB-125MB-157MB over 18) - * com.android.nfc / 1027 / v22: - TOTAL: 100% (17MB-17MB-17MB/16MB-16MB-16MB over 18) - Persistent: 100% (17MB-17MB-17MB/16MB-16MB-16MB over 18) - * android.process.acore / u0a4 / v22: - TOTAL: 100% (14MB-15MB-15MB/14MB-14MB-14MB over 20) - Imp Fg: 100% (14MB-15MB-15MB/14MB-14MB-14MB over 20) - * com.google.android.inputmethod.latin / u0a56 / v21483: - TOTAL: 100% (57MB-59MB-59MB/56MB-58MB-58MB over 19) - Imp Fg: 100% (57MB-59MB-59MB/56MB-58MB-58MB over 19) - * com.redbend.vdmc / 1001 / v1: - TOTAL: 100% (9.5MB-9.6MB-9.7MB/8.8MB-8.9MB-9.0MB over 18) - Persistent: 100% (9.5MB-9.6MB-9.7MB/8.8MB-8.9MB-9.0MB over 18) - * com.android.phone / 1001 / v22: - TOTAL: 100% (19MB-22MB-27MB/18MB-21MB-26MB over 18) - Persistent: 100% (19MB-22MB-27MB/18MB-21MB-26MB over 18) - * com.google.android.gms.persistent / u0a8 / v7319438: - TOTAL: 100% (32MB-35MB-40MB/30MB-33MB-37MB over 19) - Imp Fg: 100% (32MB-35MB-40MB/30MB-33MB-37MB over 19) - * com.android.bluetooth / 1002 / v22: - TOTAL: 100% (9.3MB-9.7MB-10MB/8.5MB-8.9MB-9.2MB over 19) - Imp Fg: 100% (9.3MB-9.7MB-10MB/8.5MB-8.9MB-9.2MB over 19) - * com.google.android.googlequicksearchbox:interactor / u0a22 / v300404573: - TOTAL: 100% (3.4MB-3.5MB-3.6MB/2.8MB-2.8MB-2.8MB over 19) - Imp Fg: 100% (3.4MB-3.5MB-3.6MB/2.8MB-2.8MB-2.8MB over 19) - * com.google.process.gapps / u0a8 / v7306438: - TOTAL: 100% (23MB-24MB-28MB/21MB-22MB-26MB over 19) - Imp Fg: 100% (23MB-24MB-28MB/21MB-22MB-26MB over 19) - * com.vito.lux / u0a84 / v237: - TOTAL: 100% (32MB-48MB-83MB/31MB-47MB-82MB over 134) - Imp Fg: 100% (32MB-48MB-83MB/31MB-47MB-82MB over 134) - Service: 0.05% - * system / 1000 / v22: - TOTAL: 100% (79MB-85MB-102MB/78MB-83MB-100MB over 18) - Persistent: 100% (79MB-85MB-102MB/78MB-83MB-100MB over 18) - * com.rhapsody / u0a83 / v125: - TOTAL: 100% (7.9MB-12MB-19MB/6.9MB-11MB-17MB over 15) - Service: 100% (7.9MB-12MB-19MB/6.9MB-11MB-17MB over 15) - Service Rs: 0.04% - * com.qualcomm.qcrilmsgtunnel / 1001 / v22: - TOTAL: 100% (2.5MB-2.6MB-2.7MB/1.7MB-1.8MB-1.9MB over 15) - Service: 100% (2.5MB-2.6MB-2.7MB/1.7MB-1.8MB-1.9MB over 15) - Service Rs: 0.13% - * com.amazon.kindle / u0a82 / v1143472216: - TOTAL: 100% (44MB-54MB-77MB/43MB-52MB-74MB over 17) - Service: 100% (44MB-54MB-77MB/43MB-52MB-74MB over 17) - Service Rs: 0.04% - * com.outplaylab.VideoDiet2 / u0a93 / v21: - TOTAL: 100% (2.8MB-3.1MB-4.0MB/2.0MB-2.2MB-3.0MB over 15) - Service: 100% (2.8MB-3.1MB-4.0MB/2.0MB-2.2MB-3.0MB over 15) - Service Rs: 0.03% - * android.process.media / u0a6 / v800: - TOTAL: 99% (4.6MB-5.9MB-8.1MB/3.4MB-4.7MB-6.7MB over 25) - Imp Fg: 0.02% - Service: 99% (4.6MB-5.9MB-8.1MB/3.4MB-4.7MB-6.7MB over 25) - Service Rs: 0.02% - (Cached): 0.94% - * kr.sira.sound / u0a108 / v41: - TOTAL: 77% (117MB-191MB-219MB/111MB-187MB-213MB over 68) - Top: 77% (117MB-191MB-219MB/111MB-187MB-213MB over 68) - (Last Act): 18% (58MB-127MB-161MB/53MB-123MB-158MB over 3) - (Cached): 0.06% - * com.google.android.gms / u0a8 / v7319438: - TOTAL: 37% (41MB-45MB-57MB/38MB-42MB-53MB over 23) - Top: 13% (41MB-46MB-57MB/39MB-42MB-53MB over 16) - Imp Fg: 13% (41MB-44MB-47MB/39MB-41MB-44MB over 5) - Imp Bg: 0.38% - Service: 11% (42MB-42MB-42MB/38MB-38MB-38MB over 2) - Receiver: 0.03% - (Last Act): 2.0% (38MB-38MB-38MB/36MB-36MB-36MB over 1) - (Cached): 61% (39MB-40MB-43MB/37MB-37MB-40MB over 28) - * com.google.android.googlequicksearchbox / u0a22 / v300404573: - TOTAL: 22% (129MB-153MB-162MB/125MB-149MB-156MB over 20) - Top: 22% (129MB-153MB-162MB/125MB-149MB-156MB over 20) - Imp Bg: 0.04% - Receiver: 0.01% - (Home): 78% (75MB-84MB-122MB/74MB-82MB-117MB over 12) - * com.google.android.apps.thehub / u0a102 / v12: - TOTAL: 21% (6.4MB-7.6MB-8.7MB/4.8MB-6.0MB-7.2MB over 2) - Service: 21% (6.4MB-7.6MB-8.7MB/4.8MB-6.0MB-7.2MB over 2) - * com.google.android.talk / u0a54 / v22314462: - TOTAL: 9.3% - Top: 0.04% - Service: 9.3% - Receiver: 0.01% - (Last Act): 3.9% (69MB-70MB-71MB/67MB-68MB-69MB over 6) - (Cached): 87% (42MB-53MB-77MB/40MB-51MB-74MB over 137) - * com.google.android.apps.plus / u0a67 / v413836278: - TOTAL: 8.2% (9.6MB-12MB-18MB/8.1MB-11MB-16MB over 3) - Imp Bg: 0.10% - Service: 8.0% (9.6MB-12MB-18MB/8.1MB-11MB-16MB over 3) - Receiver: 0.05% - (Cached): 59% (7.8MB-19MB-33MB/6.8MB-18MB-31MB over 22) - * com.android.providers.calendar / u0a2 / v22: - TOTAL: 3.5% (7.3MB-7.7MB-8.0MB/5.9MB-6.5MB-6.9MB over 10) - Imp Bg: 0.32% - Service: 3.2% (7.3MB-7.7MB-8.0MB/5.9MB-6.5MB-6.9MB over 10) - Receiver: 0.01% - (Cached): 69% (4.7MB-6.6MB-7.8MB/3.5MB-5.5MB-6.7MB over 23) - * com.amazon.mShop.android / u0a104 / v5030102: - TOTAL: 2.7% (25MB-40MB-47MB/24MB-37MB-43MB over 6) - Service: 2.6% (25MB-40MB-47MB/24MB-37MB-43MB over 6) - Receiver: 0.15% - (Cached): 97% (25MB-33MB-48MB/24MB-31MB-44MB over 46) - * com.google.android.gm / u0a70 / v51001620: - TOTAL: 2.2% (209MB-209MB-209MB/203MB-203MB-203MB over 1) - Top: 0.48% (209MB-209MB-209MB/203MB-203MB-203MB over 1) - Imp Bg: 0.70% - Service: 1.0% - Receiver: 0.01% - (Last Act): 0.02% - (Cached): 94% (25MB-67MB-116MB/23MB-63MB-109MB over 61) - * com.google.android.googlequicksearchbox:search / u0a22 / v300404573: - TOTAL: 2.1% (66MB-66MB-66MB/63MB-63MB-63MB over 1) - Top: 1.4% (66MB-66MB-66MB/63MB-63MB-63MB over 1) - Imp Fg: 0.01% - Service: 0.66% - Receiver: 0.02% - (Cached): 98% (52MB-59MB-79MB/50MB-56MB-77MB over 56) - * com.google.android.calendar / u0a31 / v2015030452: - TOTAL: 1.4% - Imp Bg: 0.33% - Service: 1.1% - Receiver: 0.02% - (Cached): 80% (7.4MB-12MB-17MB/5.8MB-9.8MB-14MB over 18) - * com.android.vending / u0a16 / v80341100: - TOTAL: 1.3% (88MB-154MB-220MB/85MB-151MB-217MB over 2) - Top: 1.3% (88MB-154MB-220MB/85MB-151MB-217MB over 2) - Service: 0.06% - Receiver: 0.02% - (Last Act): 4.4% (46MB-68MB-89MB/45MB-66MB-87MB over 2) - (Cached): 11% (15MB-74MB-133MB/13MB-72MB-131MB over 2) - * com.google.android.apps.photos / u0a65 / v5616: - TOTAL: 0.94% - Service: 0.90% - Receiver: 0.04% - (Cached): 80% (9.2MB-12MB-17MB/7.5MB-11MB-15MB over 20) - * com.amazon.avod.thirdpartyclient / u0a107 / v451210: - TOTAL: 0.52% - Service: 0.49% - Receiver: 0.03% - (Cached): 97% (14MB-24MB-34MB/13MB-22MB-31MB over 40) - * com.google.android.gms.wearable / u0a8 / v7319438: - TOTAL: 0.51% - Imp Fg: 0.47% - Service: 0.04% - (Cached): 65% (4.7MB-6.5MB-8.2MB/3.6MB-4.2MB-5.4MB over 10) - * com.amazon.mShop.android.shopping / u0a103 / v5040011: - TOTAL: 0.50% - Service: 0.37% - Receiver: 0.13% - (Cached): 77% (13MB-17MB-21MB/11MB-15MB-19MB over 15) - * com.google.android.gms:car / u0a8 / v7319438: - TOTAL: 0.49% (7.1MB-7.1MB-7.1MB/4.3MB-4.3MB-4.3MB over 1) - Top: 0.05% - Imp Fg: 0.39% (7.1MB-7.1MB-7.1MB/4.3MB-4.3MB-4.3MB over 1) - Service: 0.05% - (Cached): 0.60% (6.6MB-6.6MB-6.6MB/3.6MB-3.6MB-3.6MB over 1) - * com.amazon.mp3 / u0a92 / v4033010: - TOTAL: 0.46% - Service: 0.43% - Receiver: 0.03% - (Cached): 84% (12MB-16MB-23MB/9.7MB-14MB-21MB over 25) - * com.android.chrome:privileged_process1 / u0a34 / v2272096: - TOTAL: 0.43% - Service: 0.04% - Service Rs: 0.39% - (Cached): 100% (2.9MB-4.0MB-4.9MB/1.7MB-2.9MB-3.9MB over 18) - * com.google.android.dialer / u0a10 / v20100: - TOTAL: 0.39% (93MB-93MB-93MB/89MB-89MB-89MB over 1) - Top: 0.23% (93MB-93MB-93MB/89MB-89MB-89MB over 1) - Imp Fg: 0.16% - (Cached): 16% (5.0MB-31MB-57MB/4.1MB-29MB-54MB over 2) - * com.google.android.apps.maps / u0a58 / v906101124: - TOTAL: 0.38% - Service: 0.33% - Receiver: 0.05% - (Cached): 69% (8.7MB-15MB-18MB/7.2MB-14MB-17MB over 8) - * com.google.android.youtube / u0a80 / v101451214: - TOTAL: 0.26% - Service: 0.26% - (Cached): 36% (15MB-22MB-29MB/13MB-19MB-27MB over 5) - * com.google.android.apps.fitness / u0a45 / v2015109100: - TOTAL: 0.26% - Service: 0.23% - Receiver: 0.02% - (Cached): 82% (3.9MB-6.4MB-9.2MB/2.8MB-5.3MB-7.9MB over 19) - * com.google.android.apps.enterprise.dmagent / u0a37 / v630: - TOTAL: 0.06% - Service: 0.06% - Receiver: 0.01% - (Cached): 2.2% (6.5MB-7.4MB-8.2MB/4.8MB-5.8MB-6.8MB over 2) - * com.audible.application / u0a95 / v3068: - TOTAL: 0.06% - Receiver: 0.06% - (Cached): 34% (14MB-16MB-19MB/11MB-14MB-17MB over 7) - * com.android.defcontainer / u0a5 / v22: - TOTAL: 0.06% - Imp Fg: 0.06% - (Cached): 0.12% - * com.google.android.music:main / u0a60 / v1847: - TOTAL: 0.04% - Top: 0.01% - Service: 0.02% - Receiver: 0.01% - (Cached): 9.8% (10MB-12MB-14MB/8.3MB-9.6MB-11MB over 2) - * com.google.android.apps.magazines / u0a61 / v2015040100: - TOTAL: 0.03% - Top: 0.02% - Receiver: 0.01% - (Cached): 8.7% (12MB-14MB-16MB/9.7MB-11MB-13MB over 2) - * com.google.android.videos / u0a77 / v37191: - TOTAL: 0.03% - Imp Fg: 0.01% - Service: 0.02% - (Cached): 1.3% (11MB-12MB-13MB/9.1MB-10MB-12MB over 2) - * com.google.android.apps.books / u0a28 / v30336: - TOTAL: 0.03% - Imp Fg: 0.01% - Service: 0.02% - (Cached): 1.3% (7.9MB-9.6MB-11MB/6.3MB-8.0MB-9.7MB over 2) - * com.google.android.keep / u0a71 / v3115: - TOTAL: 0.02% - Service: 0.01% - Receiver: 0.01% - (Cached): 11% (6.3MB-8.7MB-9.6MB/5.1MB-7.4MB-8.3MB over 4) - * com.android.chrome / u0a34 / v2272096: - TOTAL: 0.02% - Service: 0.01% - Receiver: 0.02% - (Cached): 90% (5.1MB-70MB-96MB/3.4MB-66MB-92MB over 15) - * com.google.android.apps.gcs / u0a94 / v14: - TOTAL: 0.02% - Service: 0.02% - (Cached): 17% (5.8MB-5.9MB-6.0MB/4.6MB-4.7MB-4.8MB over 2) - * com.android.chrome:privileged_process0 / u0a34 / v2272096: - TOTAL: 0.02% - Service: 0.01% - Receiver: 0.01% - (Cached): 73% (162MB-163MB-164MB/157MB-157MB-157MB over 13) - * com.android.chrome:sandboxed_process12 / u0a34 / v2272096: - TOTAL: 0.02% - Service: 0.01% - Receiver: 0.01% - (Cached): 73% (48MB-49MB-51MB/46MB-47MB-50MB over 13) - * com.google.android.apps.docs / u0a40 / v51410735: - TOTAL: 0.01% - Receiver: 0.01% - (Cached): 0.45% (10MB-10MB-10MB/9.3MB-9.3MB-9.3MB over 1) - * com.google.android.deskclock / u0a38 / v303: - TOTAL: 0.01% - Receiver: 0.01% - (Cached): 82% (2.5MB-3.3MB-4.3MB/1.7MB-2.3MB-3.2MB over 13) - * com.google.android.gm.exchange / u0a69 / v500065: - TOTAL: 0.01% - Imp Bg: 0.01% - (Cached): 27% (3.3MB-3.7MB-3.9MB/2.2MB-2.7MB-2.9MB over 6) - * com.android.cellbroadcastreceiver / u0a3 / v22: - TOTAL: 0.01% - Service: 0.01% - (Cached): 1.1% (3.5MB-3.5MB-3.5MB/2.5MB-2.5MB-2.5MB over 1) - * com.coulombtech / u0a106 / v26: - TOTAL: 0.01% - Receiver: 0.01% - (Cached): 21% (4.9MB-5.0MB-5.2MB/3.8MB-3.9MB-4.1MB over 2) - * com.softcoil.mms / u0a86 / v32: - TOTAL: 0.01% - (Cached): 0.25% - * com.udemy.android / u0a91 / v38: - TOTAL: 0.01% - Receiver: 0.01% - (Cached): 0.75% (9.8MB-9.8MB-9.8MB/8.5MB-8.5MB-8.5MB over 1) - * com.qualcomm.timeservice / u0a76 / v22: - (Cached): 16% (2.3MB-2.4MB-2.4MB/1.6MB-1.6MB-1.6MB over 4) - * com.lge.SprintHiddenMenu / 1000 / v22: - (Cached): 0.16% - * com.android.chrome:sandboxed_process13 / u0a34 / v2272096: - (Cached): 0.01% - * com.google.android.partnersetup / u0a13 / v22: - (Cached): 0.14% - * com.android.musicfx / u0a15 / v10400: - (Cached): 0.41% (2.5MB-2.5MB-2.5MB/1.6MB-1.6MB-1.6MB over 1) - * com.android.chrome:sandboxed_process9 / u0a34 / v2272096: - (Cached): 30% (34MB-34MB-34MB/32MB-32MB-32MB over 9) - * com.android.chrome:sandboxed_process11 / u0a34 / v2272096: - (Cached): 7.2% (56MB-56MB-56MB/54MB-54MB-54MB over 3) - -Run time Stats: - SOff/Norm: +32m52s226ms - SOn /Norm: +2h10m8s364ms - Mod : +17s930ms - TOTAL: +2h43m18s520ms - -Memory usage: - Kernel : 265MB (38 samples) - Native : 73MB (38 samples) - Persist: 262MB (90 samples) - Top : 190MB (325 samples) - ImpFg : 204MB (569 samples) - ImpBg : 754KB (345 samples) - Service: 93MB (1912 samples) - Receivr: 227KB (1169 samples) - Home : 66MB (12 samples) - LastAct: 30MB (255 samples) - CchAct : 220MB (450 samples) - CchCAct: 193MB (71 samples) - CchEmty: 182MB (652 samples) - Cached : 58MB (38 samples) - Free : 60MB (38 samples) - TOTAL : 1.9GB - ServRst: 50KB (278 samples) - - Start time: 2015-04-08 13:44:18 - Total elapsed time: +2h43m18s521ms (partial) libart.so -</pre> - - - </body> -</html> diff --git a/en/devices/tech/power/batterystats.html b/en/devices/tech/power/batterystats.html deleted file mode 100644 index 10cf934f..00000000 --- a/en/devices/tech/power/batterystats.html +++ /dev/null @@ -1,580 +0,0 @@ -<html devsite> - <head> - <title>Viewing Battery Use Data</title> - <meta name="project_path" value="/_project.yaml" /> - <meta name="book_path" value="/_book.yaml" /> - </head> - <body> - <!-- - Copyright 2017 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. - --> - - - - <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>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 to understand and diagnose battery-related issues.</p> - - <h2 id="command-line_options">Command input</h2> - <p>The basic <code>batterystats</code> command is:</p> -<pre class="devsite-terminal devsite-click-to-copy"> -adb shell dumpsys batterystats -</pre> - <p>Supported options:</p> - <ul> - <li><code>--help</code> displays additional options for tailoring the output. - </li> - <li><code>--checkin</code> exports results in machine-readable csv format. - </li> - </ul> - <p>For example, to print battery usage statistics in csv format for all apps - since the device was last charged, run the command:</p> -<pre class="devsite-terminal devsite-click-to-copy"> -adb shell dumpsys batterystats --charged --checkin -</pre> - <p>You can also specify a package name to get statistics for a single app. For - example, to print battery usage statistics for a given app package - since the device was last charged, run the command:</p> -<pre class="devsite-terminal devsite-click-to-copy"> -adb shell dumpsys batterystats --charged <package-name> -</pre> - - <h2 id="output">Command output</h2> - - <p>The <code>batterystats</code> command generates aggregated observations - about battery use on the device since it was last charged. Observations may be - per-UID or system-level; data is selected for inclusion based on its - usefulness in analyzing battery performance. Output includes one (1) entry - per observation, and each entry consists of a comma-separated list of values - in the format: - <em>int</em>,<em>uid</em>,<em>mode</em>,<em>section</em>,<em>fields</em> - (one or more).</p> - - <p>The first four values correspond to the following:</p> - - <ul> - <li>Dummy integer</li> - - <li>UID</li> - - <li>Aggregation mode - - <ul> - <li>"i" for information not tied to charged/uncharged status.</li> - <li>"l" for --charged (usage since last charge).</li> - <li>"u" for --unplugged (usage since last unplugged). Deprecated in - Android 5.1.1.</li> - </ul> - </li> - - <li><a href="#interpreting_the_output">Section identifier</a>, which - determines how to interpret subsequent values in the line.</li> - </ul> - -<p>Sample output:</p> - - <pre class="devsite-click-to-copy"> - 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,0,l,pwi,blue,0.0273 - 9,0,l,pwi,cell,14.0 - 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">Section identifiers</h2> - - <p>Command output for <code>batterystats</code> supports the following - sections:</p> - - <table id="batterystats-section-ids"> - - <tr> - <th width="10%">Section Identifier</th> - <th width="20%">Description</th> - <th width="70%">Remaining Fields</th> - </tr> - - <tr> - <td><p>vers</p></td> - <td><p>Version</p></td> - <td><p>checkin version, parcel version, start platform version, end - platform version</p></td> - </tr> - - <tr> - <td><p>uid</p></td> - <td><p>UID</p></td> - <td><p>uid, package name</p></td> - </tr> - - <tr> - <td><p>apk</p></td> - <td><p>APK</p></td> - <td><p>wakeups, APK, service, start time, starts, launches</p></td> - </tr> - - <tr> - <td><p>pr</p></td> - <td><p>Process</p></td> - <td><p>process, user, system, foreground, starts</p></td> - </tr> - - <tr> - <td><p>sr</p></td> - <td><p>Sensor</p></td> - <td><p>sensor number, time, count</p></td> - </tr> - - <tr> - <td><p>vib</p></td> - <td><p>Vibrator</p></td> - <td><p>time, count</p></td> - </tr> - - <tr> - <td><p>fg</p></td> - <td><p>Foreground</p></td> - <td><p>time, count</p></td> - </tr> - - <tr> - <td><p>st</p></td> - <td><p>State Time</p></td> - <td><p>foreground, active, running</p></td> - </tr> - - <tr> - <td><p>wl</p></td> - <td><p>Wake lock</p></td> - <td><p>wake lock, full time, 'f', full count, partial time, 'p', partial - count, window time, 'w', window count</p></td> - </tr> - - <tr> - <td><p>sy</p></td> - <td><p>Sync</p></td> - <td><p>sync, time, count</p></td> - </tr> - - <tr> - <td><p>jb</p></td> - <td><p>Job</p></td> - <td><p>job, time, count</p></td> - </tr> - - <tr> - <td><p>kwl</p></td> - <td><p>Kernel Wake Lock</p></td> - <td><p>kernel wake lock, time, count</p></td> - </tr> - - <tr> - <td><p>wr</p></td> - <td><p>Wakeup Reason</p></td> - <td><p>wakeup reason, time, count</p></td> - </tr> - - <tr> - <td><p>nt</p></td> - <td><p>Network</p></td> - <td><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>ua</p></td> - <td><p>User Activity</p></td> - <td><p>other, button, touch</p></td> - </tr> - - <tr> - <td><p>bt</p></td> - <td><p>Battery</p></td> - <td><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>dc</p></td> - <td><p>Battery Discharge</p></td> - <td><p>low, high, screen on, screen off</p></td> - </tr> - - <tr> - <td><p>lv</p></td> - <td><p>Battery Level</p></td> - <td><p>start level, current level</p></td> - </tr> - - <tr> - <td><p>wfl</p></td> - <td><p>Wi-Fi</p></td> - <td><p>full Wi-Fi lock on time, Wi-Fi scan time, Wi-Fi running time, Wi-Fi - scan count, Wi-Fi idle time, Wi-Fi receive time, Wi-Fi transmit time</p> - </td> - </tr> - - <tr> - <td><p>gwfl</p></td> - <td><p>Global Wi-Fi</p></td> - <td><p>Wi-Fi on time, Wi-Fi running time, Wi-Fi idle time, Wi-Fi receive - time, Wi-Fi transmit time, Wi-Fi power (mAh)</p></td> - </tr> - - <tr> - <td><p>gble</p></td> - <td><p>Global Bluetooth</p></td> - <td><p>BT idle time, BT receive time, BT transmit time, BT power (mAh)</p> - </td> - </tr> - - <tr> - <td><p>m</p></td> - <td><p>Misc</p></td> - <td><p>screen on time, phone on time, full wakelock time total, partial - wakelock time total, mobile radio active time, mobile radio active - adjusted time, interactive time, power save mode enabled time, - connectivity changes, device idle mode enabled time, device idle mode - enabled count, device idling time, device idling count, mobile radio - active count, mobile radio active unknown time</p></td> - </tr> - - <tr> - <td><p>gn</p></td> - <td><p>Global Network</p></td> - <td><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>br</p></td> - <td><p>Screen Brightness</p></td> - <td><p>dark, dim, medium, light, bright</p></td> - </tr> - - <tr> - <td><p>sst</p></td> - <td><p>Signal Scanning Time</p></td> - <td><p>signal scanning time</p></td> - </tr> - - <tr> - <td><p>sgt</p></td> - <td><p>Signal Strength Time</p></td> - <td><p>none, poor, moderate, good, great</p></td> - </tr> - - <tr> - <td><p>sgc</p></td> - <td><p>Signal Strength Count</p></td> - <td><p>none, poor, moderate, good, great</p></td> - </tr> - - <tr> - <td><p>dct</p></td> - <td><p>Data Connection Time</p></td> - <td><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>dcc</p></td> - <td><p>Data Connection Count</p></td> - <td><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>wst</p></td> - <td><p>Wi-Fi State Time</p></td> - <td><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>wsc</p></td> - <td><p>Wi-Fi State Count</p></td> - <td><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>wsst</p></td> - <td><p>Wi-Fi Supplicant State Time</p></td> - <td><p>invalid, disconnected, interface disabled, inactive, scanning, - authenticating, associating, associated, four-way handshake, group - handshake, completed, dormant, uninitialized</p></td> - </tr> - - <tr> - <td><p>wssc</p></td> - <td><p>Wi-Fi Supplicant State Count</p></td> - <td><p>invalid, disconnected, interface disabled, inactive, scanning, - authenticating, associating, associated, four-way handshake, group - handshake, completed, dormant, uninitialized</p></td> - </tr> - - <tr> - <td><p>wsgt</p></td> - <td><p>Wi-Fi Signal Strength Time</p></td> - <td><p>none, poor, moderate, good, great</p></td> - </tr> - - <tr> - <td><p>wsgc</p></td> - <td><p>Wi-Fi Signal Strength Count</p></td> - <td><p>none, poor, moderate, good, great</p></td> - </tr> - - <tr> - <td><p>bst</p></td> - <td><p>Bluetooth State Time</p></td> - <td><p>inactive, low, med, high</p></td> - </tr> - - <tr> - <td><p>bsc</p></td> - <td><p>Bluetooth State Count</p></td> - <td><p>inactive, low, med, high</p></td> - </tr> - - <tr> - <td><p>pws</p></td> - <td><p>Power Use Summary</p></td> - <td><p>battery capacity, computed power, minimum drained power, maximum - drained power</p></td> - </tr> - - <tr> - <td><p>pwi</p></td> - <td><p>Power Use Item</p></td> - <td><p>label, mAh</p></td> - </tr> - - <tr> - <td><p>dsd</p></td> - <td><p>Discharge Step</p></td> - <td><p>duration, level, screen, power-save</p></td> - </tr> - - <tr> - <td><p>csd</p></td> - <td><p>Charge Step</p></td> - <td><p>duration, level, screen, power-save</p></td> - </tr> - - <tr> - <td><p>dtr</p></td> - <td><p>Discharge Time Remaining</p></td> - <td><p>battery time remaining</p></td> - </tr> - - <tr> - <td><p>ctr</p></td> - <td><p>Charge Time Remaining</p></td> - <td><p>charge time remaining</p></td> - </tr> - - </table> - -<h2 id="wifi-reqs">Bluetooth, cellular, and Wi-Fi usage</h2> - -<p>Support for battery usage data on Bluetooth, cellular, and Wi-Fi data -requires the device Bluetooth, cellular, and Wif-Fi chipsets implement radio -support and the chipset firmware passes usage data to the framework. OEMs must -work with their chipset providers to facilitate in-field firmware updates on -existing chipsets and compatible firmware on new chipsets.</p> - -<p>Additionally, OEMs must continue to configure and submit the power profile -for their devices. However, when the platform detects that Bluetooth, cellular -(as of Android 7.0), or Wi-Fi radio power data is available from the chipset, it -uses chipset data instead of power profile data. For details, see -<a href="/devices/tech/power/values.html#values">Power values</a>.</p> - -<p class="note"><strong>Note</strong>: Prior to Android 6.0, power use for -Bluetooth radio, cellular radio, and Wi-Fi was tracked in the <em>m</em> (Misc) -section category. In Android 6.0 and higher, power use for these components is -tracked in the <em>pwi</em> (Power Use Item) section with individual labels -(<em>wifi</em>, <em>blue</em>, <em>cell</em>) for each component.</p> - - </body> -</html> |
