Merge "Docs: Changes to source.android.com"
diff --git a/en/_book.yaml b/en/_book.yaml
index 1f58232..a2875e9 100644
--- a/en/_book.yaml
+++ b/en/_book.yaml
@@ -1,34 +1,114 @@
+
upper_tabs:
-- name: Setup
+- name: Set up
lower_tabs:
other:
- - name: Setup
+ - name: Overview
contents:
- - include: /setup/_toc.yaml
-- name: Security
- lower_tabs:
- other:
- - name: Security
+ - title: Overview
+ path: /setup/
+ - name: Start
contents:
- - include: /security/_toc.yaml
-- name: Porting
- lower_tabs:
- other:
- - name: Porting
+ - include: /setup/_toc-start.yaml
+ - name: Download
contents:
- - include: /devices/_toc-interfaces.yaml
-- name: Tuning
- lower_tabs:
- other:
- - name: Tuning
+ - include: /setup/_toc-download.yaml
+ - name: Build
contents:
- - include: /devices/_toc-tech.yaml
-- name: Compatibility
+ - include: /setup/_toc-build.yaml
+ - name: Create
+ contents:
+ - include: /setup/_toc-create.yaml
+ - name: Contribute
+ contents:
+ - include: /setup/_toc-contribute.yaml
+ - name: Contact
+ contents:
+ - include: /setup/_toc-contact.yaml
+- name: Design
lower_tabs:
other:
+ - name: Overview
+ contents:
+ - include: /compatibility/_toc-purpose.yaml
+ - name: Architecture
+ contents:
+ - include: /compatibility/_toc-architecture.yaml
- name: Compatibility
contents:
- include: /compatibility/_toc-compatibility.yaml
+ - name: Display
+ contents:
+ - include: /compatibility/_toc-display.yaml
+ - name: Settings
+ contents:
+ - include: /compatibility/_toc-settings.yaml
+ - name: Tests
+ contents:
+ - include: /compatibility/_toc-tests.yaml
+- name: Secure
+ lower_tabs:
+ other:
+ - name: Overview
+ contents:
+ - include: /security/_toc-overview.yaml
+ - name: Bulletins
+ contents:
+ - include: /security/_toc-bulletins.yaml
+ - name: Features
+ contents:
+ - include: /security/_toc-features.yaml
+ - name: Dynamic Analysis
+ contents:
+ - include: /security/_toc-fuzz.yaml
+- name: Develop
+ lower_tabs:
+ other:
+ - name: Audio
+ contents:
+ - include: /devices/_toc-audio.yaml
+ - name: Camera
+ contents:
+ - include: /devices/_toc-camera.yaml
+ - name: Connectivity
+ contents:
+ - include: /devices/_toc-connectivity.yaml
+ - name: Graphics
+ contents:
+ - include: /devices/_toc-graphics.yaml
+ - name: Interaction
+ contents:
+ - include: /devices/_toc-interaction.yaml
+ - name: Media
+ contents:
+ - include: /devices/_toc-media.yaml
+ - name: Storage
+ contents:
+ - include: /devices/_toc-storage.yaml
+- name: Configure
+ lower_tabs:
+ other:
+ - name: ART
+ contents:
+ - include: /devices/_toc-runtime.yaml
+ - name: Data
+ contents:
+ - include: /devices/_toc-data.yaml
+ - name: Enterprise
+ contents:
+ - include: /devices/_toc-enterprise.yaml
+ - name: Performance
+ contents:
+ - include: /devices/_toc-performance.yaml
+ - name: Permissions
+ contents:
+ - include: /devices/_toc-permissions.yaml
+ - name: Power
+ contents:
+ - include: /devices/_toc-power.yaml
+ - name: Updates
+ contents:
+ - include: /devices/_toc-update.yaml
- name: Reference
lower_tabs:
other:
diff --git a/en/_dac_versions.html b/en/_dac_versions.html
index 4c11f41..bc8c244 100644
--- a/en/_dac_versions.html
+++ b/en/_dac_versions.html
@@ -30,5 +30,5 @@
{% setvar playCoreLibVersion %}1.3.0{% endsetvar %}
{# PLATFORM VERSIONS #}
-{% setvar androidPVersionNumber %}P{% endsetvar %}
+{% setvar androidPVersionNumber %}9{% endsetvar %}
{% setvar androidPApiLevel %}P{% endsetvar %}
diff --git a/en/_index.yaml b/en/_index.yaml
index 6a8fd99..a359a2f 100644
--- a/en/_index.yaml
+++ b/en/_index.yaml
@@ -7,7 +7,7 @@
path: /setup/downloading
rows:
- items:
- - heading: 8.1 interfaces and architecture
+ - heading: 9 interfaces and architecture
description: >
Port the latest Android platform using simple HIDL interfaces to create
compelling devices for your customers.
@@ -22,7 +22,7 @@
</style>
buttons:
- label: Learn Treble
- path: /devices/architecture/treble
+ path: /devices/architecture/
image_path: /images/landing_icon-porting.png
- heading: Securing Android is essential
description: >
@@ -32,7 +32,7 @@
buttons:
- label: Implement Security
path: /security/
- - heading: Get compatible, get apps
+ - heading: Design compatible devices
description: >
Offer a consistent experience with other Android-powered devices and
get the ability to include more apps.
@@ -69,29 +69,30 @@
image_path: /images/android_stack.png
- heading: News
items:
- - heading: Settings Design Guidelines
+ - heading: Android 9 Documentation
description: >
- A new article describing the principles and guidelines for designing
- Android platform settings, GMS core settings, and Android app settings
- has been published.
+ Android 9 has been released! This site includes documentation for
+ implementing the features, improvements, and enhancements
+ in the newest version of Android.
buttons:
- - label: July 18th, 2018
- path: /devices/tech/settings/settings-guidelines
- - heading: July Security Bulletins
+ - label: August 6th, 2018
+ path: /setup/start/p-release-notes
+ - heading: Site Updates
description: >
- The July 2018 Android and Pixel/Nexus Security Bulletins have been
+ This site has been overhauled to make it easier for you to navigate,
+ search, and read its ever-growing set of information. Check out our
+ reorganized sections and new navigation.
+ buttons:
+ - label: August 6th, 2018
+ path: /setup/start/site-updates
+ - heading: August Security Bulletins
+ description: >
+ The August 2018 Android and Pixel/Nexus Security Bulletins have been
published along with links to associated fixes and new build numbers
- to support the July security release.
+ to support the August security release.
buttons:
- - label: July 3rd, 2018
- path: /security/bulletin/2018-07-01
- - heading: Camera HAL
- description: >
- The camera Hardware Abstraction Layer (HAL) documentation has been
- updated to include references to the camera HIDL interface.
- buttons:
- - label: May 23rd, 2018
- path: /devices/camera/
+ - label: August 6th, 2018
+ path: /security/bulletin/2018-08-01
- classname: devsite-landing-row-100 tf-row-centered
items:
- buttons:
diff --git a/en/_versions.html b/en/_versions.html
index a3855b5..ef50a83 100644
--- a/en/_versions.html
+++ b/en/_versions.html
@@ -17,4 +17,3 @@
{# SAC SPECIFIC VERSIONS #}
{% setvar putVersionNameHere %}X.x{% endsetvar %}
-
diff --git a/en/compatibility/9.0/android-9.0-cdd.html b/en/compatibility/9.0/android-9.0-cdd.html
new file mode 100644
index 0000000..8f93b15
--- /dev/null
+++ b/en/compatibility/9.0/android-9.0-cdd.html
@@ -0,0 +1,10015 @@
+<html devsite="">
+ <head>
+ <title>
+ Android 9 Compatibility Definition
+ </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.
+ -->
+ <h2 id="1_introduction">
+ 1. Introduction
+ </h2>
+ <p>
+ This document enumerates the requirements that must be met in order for devices to be compatible with Android 9.
+ </p>
+ <p>
+ The use of “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” is per the IETF standard defined in <a href="http://www.ietf.org/rfc/rfc2119.txt">RFC2119</a>.
+ </p>
+ <p>
+ As used in this document, a “device implementer” or “implementer” is a person or organization developing a hardware/software solution running Android 9. A “device implementation” or “implementation" is the hardware/software solution so developed.
+ </p>
+ <p>
+ To be considered compatible with Android 9, device implementations MUST meet the requirements presented in this Compatibility Definition, including any documents incorporated via reference.
+ </p>
+ <p>
+ Where this definition or the software tests described in <a href="#10_software_compatibility_testing">section 10</a> are silent, ambiguous, or incomplete, it is the responsibility of the device implementer to ensure compatibility with existing implementations.
+ </p>
+ <p>
+ For this reason, the <a href="http://source.android.com/">Android Open Source Project</a> is both the reference and preferred implementation of Android. Device implementers are STRONGLY RECOMMENDED to base their implementations to the greatest extent possible on the “upstream” source code available from the Android Open Source Project. While some components can hypothetically be replaced with alternate implementations, it is STRONGLY RECOMMENDED to not follow this practice, as passing the software tests will become substantially more difficult. It is the implementer’s responsibility to ensure full behavioral compatibility with the standard Android implementation, including and beyond the Compatibility Test Suite. Finally, note that certain component substitutions and modifications are explicitly forbidden by this document.
+ </p>
+ <p>
+ Many of the resources linked to in this document are derived directly or indirectly from the Android SDK and will be functionally identical to the information in that SDK’s documentation. In any cases where this Compatibility Definition or the Compatibility Test Suite disagrees with the SDK documentation, the SDK documentation is considered authoritative. Any technical details provided in the linked resources throughout this document are considered by inclusion to be part of this Compatibility Definition.
+ </p>
+ <h3 id="1_1_document_structure">
+ 1.1 Document Structure
+ </h3>
+ <h4 id="1_1_1_requirements_by_device_type">
+ 1.1.1. Requirements by Device Type
+ </h4>
+ <p>
+ <a href="#2_device_types">Section 2</a> contains all of the requirements that apply to a specific device type. Each subsection of <a href="#2_device_types">Section 2</a> is dedicated to a specific device type.
+ </p>
+ <p>
+ All the other requirements, that universally apply to any Android device implementations, are listed in the sections after <a href="#2_device_types">Section 2</a>. These requirements are referenced as "Core Requirements" in this document.
+ </p>
+ <h4 id="1_1_2_requirement_id">
+ 1.1.2. Requirement ID
+ </h4>
+ <p>
+ Requirement ID is assigned for MUST requirements.
+ </p>
+ <ul>
+ <li>The ID is assigned for MUST requirements only.
+ </li>
+ <li>STRONGLY RECOMMENDED requirements are marked as [SR] but ID is not assigned.
+ </li>
+ <li>The ID consists of : Device Type ID - Condition ID - Requirement ID (e.g. C-0-1).
+ </li>
+ </ul>
+ <p>
+ Each ID is defined as below:
+ </p>
+ <ul>
+ <li>Device Type ID (see more in <a href="#2_device_types">2. Device Types</a>)
+ <ul>
+ <li>C: Core (Requirements that are applied to any Android device implementations)
+ </li>
+ <li>H: Android Handheld device
+ </li>
+ <li>T: Android Television device
+ </li>
+ <li>A: Android Automotive implementation
+ </li>
+ <li>Tab: Android Tablet implementation
+ </li>
+ </ul>
+ </li>
+ <li>Condition ID
+ <ul>
+ <li>When the requirement is unconditional, this ID is set as 0.
+ </li>
+ <li>When the requirement is conditional, 1 is assigned for the 1st condition and the number increments by 1 within the same section and the same device type.
+ </li>
+ </ul>
+ </li>
+ <li>Requirement ID
+ <ul>
+ <li>This ID starts from 1 and increments by 1 within the same section and the same condition.
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <h4 id="1_1_3_requirement_id_in_section_2">
+ 1.1.3. Requirement ID in Section 2
+ </h4>
+ <p>
+ The Requirement ID in <a href="#2_device_types">Section 2</a> starts with the corresponding section ID that is followed by the Requirement ID described above.
+ </p>
+ <ul>
+ <li>The ID in <a href="#2_device_types">Section 2</a> consists of : Section ID / Device Type ID - Condition ID - Requirement ID (e.g. 7.4.3/A-0-1).
+ </li>
+ </ul>
+ <h2 id="2_device_types">
+ 2. Device Types
+ </h2>
+ <p>
+ While the Android Open Source Project provides a software stack that can be used for a variety of device types and form factors, there are a few device types that have a relatively better established application distribution ecosystem.
+ </p>
+ <p>
+ This section describes those device types, and additional requirements and recommendations applicable for each device type.
+ </p>
+ <p>
+ All Android device implementations that do not fit into any of the described device types MUST still meet all requirements in the other sections of this Compatibility Definition.
+ </p>
+ <h3 id="2_1_device_configurations">
+ 2.1 Device Configurations
+ </h3>
+ <p>
+ For the major differences in hardware configuration by device type, see the device-specific requirements that follow in this section.
+ </p>
+ <h3 id="2_2_handheld_requirements">
+ 2.2. Handheld Requirements
+ </h3>
+ <p>
+ An <strong>Android Handheld device</strong> refers to an Android device implementation that is typically used by holding it in the hand, such as an mp3 player, phone, or tablet.
+ </p>
+ <p>
+ Android device implementations are classified as a Handheld if they meet all the following criteria:
+ </p>
+ <ul>
+ <li>Have a power source that provides mobility, such as a battery.
+ </li>
+ <li>Have a physical diagonal screen size in the range of 2.5 to 8 inches.
+ </li>
+ </ul>
+ <p>
+ The additional requirements in the rest of this section are specific to Android Handheld device implementations.
+ </p>
+ <div class="note">
+ <b>Note:</b> Requirements that do not apply to Android Tablet devices are marked with an *.
+ </div>
+ <h4 id="2_2_1_hardware">
+ 2.2.1. Hardware
+ </h4>
+ <p>
+ Handheld device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#7_1_display_and_graphics">7.1</a>.1.1/H-0-1] MUST have a screen at least 2.5 inches in physical diagonal size.
+ </li>
+ <li>[<a href="#7_1_display_and_graphics">7.1</a>.1.3/H-SR] Are STRONGLY RECOMMENDED to provide users an affordance to change the display size.(Screen Density)
+ </li>
+ </ul>
+ <p>
+ If Handheld device implementations claim support for high dynamic range displays through <a href="https://developer.android.com/reference/android/content/res/Configuration.html#isScreenHdr%28%29"><code>Configuration.isScreenHdr()</code></a> , they:
+ </p>
+ <ul>
+ <li>[<a href="#7_1_display-and-graphics">7.1</a>.4.5/H-1-1] MUST advertise support for the <code>EGL_EXT_gl_colorspace_bt2020_pq</code>, <code>EGL_EXT_surface_SMPTE2086_metadata</code>, <code>EGL_EXT_surface_CTA861_3_metadata</code>, <code>VK_EXT_swapchain_colorspace</code>, and <code>VK_EXT_hdr_metadata</code> extensions.
+ </li>
+ </ul>
+ <p>
+ Handheld device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#7_1_display_and_graphics">7.1</a>.5/H-0-1] MUST include support for legacy application compatibility mode as implemented by the upstream Android open source code. That is, device implementations MUST NOT alter the triggers or thresholds at which compatibility mode is activated, and MUST NOT alter the behavior of the compatibility mode itself.
+ </li>
+ <li>[<a href="#7_2_input_devices">7.2</a>.1/H-0-1] MUST include support for third-party Input Method Editor (IME) applications.
+ </li>
+ <li>[<a href="#7_2_input_devices">7.2</a>.3/H-0-1] MUST provide the Home, Recents, and Back functions.
+ </li>
+ <li>[<a href="#7_2_input_devices">7.2</a>.3/H-0-2] MUST send both the normal and long press event of the Back function (<a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_BACK"><code>KEYCODE_BACK</code></a>) to the foreground application. These events MUST NOT be consumed by the system and CAN be triggered by outside of the Android device (e.g. external hardware keyboard connected to the Android device).
+ </li>
+ <li>[<a href="#7_2_input_devices">7.2</a>.4/H-0-1] MUST support touchscreen input.
+ </li>
+ <li>[<a href="#7_2_input_devices">7.2</a>.4/H-SR] Are STRONGLY RECOMMENDED to launch the user-selected assist app, in other words the app that implements VoiceInteractionService, or an activity handling the <a href="https://developer.android.com/reference/android/content/Intent#ACTION_ASSIST"><code>ACTION_ASSIST</code></a> on long-press of <a href="https://developer.android.com/reference/android/view/KeyEvent#KEYCODE_MEDIA_PLAY_PAUSE"><code>KEYCODE_MEDIA_PLAY_PAUSE</code></a> or <a href="https://developer.android.com/reference/android/view/KeyEvent#KEYCODE_HEADSETHOOK"><code>KEYCODE_HEADSETHOOK</code></a> if the foreground activity does not handle those long-press events.
+ </li>
+ <li>[<a href="#7_3_sensors">7.3</a>.1/H-SR] Are STRONGLY RECOMMENDED to include a 3-axis accelerometer.
+ </li>
+ </ul>
+ <p>
+ If Handheld device implementations include a 3-axis accelerometer, they:
+ </p>
+ <ul>
+ <li>[<a href="#7_3_sensors">7.3</a>.1/H-1-1] MUST be able to report events up to a frequency of at least 100 Hz.
+ </li>
+ </ul>
+ <p>
+ If Handheld device implementations include a gyroscope, they:
+ </p>
+ <ul>
+ <li>[<a href="#7_3_sensors">7.3</a>.4/H-1-1] MUST be able to report events up to a frequency of at least 100 Hz.
+ </li>
+ </ul>
+ <p>
+ Handheld device implementations that can make a voice call and indicate any value other than <code>PHONE_TYPE_NONE</code> in <code>getPhoneType</code>:
+ </p>
+ <ul>
+ <li>[<a href="#7_3_sensors">7.3</a>.8/H] SHOULD include a proximity sensor.
+ </li>
+ </ul>
+ <p>
+ Handheld device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#7_3_sensors">7.3</a>.12/H-SR] Are RECOMMENDED to support pose sensor with 6 degrees of freedom.
+ </li>
+ <li>[<a href="#7_4_data_connectivity">7.4</a>.3/H] SHOULD include support for Bluetooth and Bluetooth LE.
+ </li>
+ </ul>
+ <p>
+ If Handheld device implementations include a metered connection, they:
+ </p>
+ <ul>
+ <li>[<a href="#7_4_data_connectivity">7.4</a>.7/H-1-1] MUST provide the data saver mode.
+ </li>
+ </ul>
+ <p>
+ Handheld device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#7_6_memory_and_storage">7.6</a>.1/H-0-1] MUST have at least 4 GB of non-volatile storage available for application private data (a.k.a. "/data" partition).
+ </li>
+ <li>[<a href="#7_6_memory_and_storage">7.6</a>.1/H-0-2] MUST return “true” for <code>ActivityManager.isLowRamDevice()</code> when there is less than 1GB of memory available to the kernel and userspace.
+ </li>
+ </ul>
+ <p>
+ If Handheld device implementations are 32-bit:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/H-1-1] The memory available to the kernel and userspace MUST be at least 512MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>280dpi or lower on small/normal screens<sup>*</sup>
+ </li>
+ <li>ldpi or lower on extra large screens
+ </li>
+ <li>mdpi or lower on large screens
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/H-2-1] The memory available to the kernel and userspace MUST be at least 608MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>xhdpi or higher on small/normal screens<sup>*</sup>
+ </li>
+ <li>hdpi or higher on large screens
+ </li>
+ <li>mdpi or higher on extra large screens
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/H-3-1] The memory available to the kernel and userspace MUST be at least 896MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>400dpi or higher on small/normal screens<sup>*</sup>
+ </li>
+ <li>xhdpi or higher on large screens
+ </li>
+ <li>tvdpi or higher on extra large screens
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/H-4-1] The memory available to the kernel and userspace MUST be at least 1344MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>560dpi or higher on small/normal screens<sup>*</sup>
+ </li>
+ <li>400dpi or higher on large screens
+ </li>
+ <li>xhdpi or higher on extra large screens
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <p>
+ If Handheld device implementations are 64-bit:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/H-5-1] The memory available to the kernel and userspace MUST be at least 816MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>280dpi or lower on small/normal screens<sup>*</sup>
+ </li>
+ <li>ldpi or lower on extra large screens
+ </li>
+ <li>mdpi or lower on large screens
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/H-6-1] The memory available to the kernel and userspace MUST be at least 944MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>xhdpi or higher on small/normal screens<sup>*</sup>
+ </li>
+ <li>hdpi or higher on large screens
+ </li>
+ <li>mdpi or higher on extra large screens
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/H-7-1] The memory available to the kernel and userspace MUST be at least 1280MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>400dpi or higher on small/normal screens<sup>*</sup>
+ </li>
+ <li>xhdpi or higher on large screens
+ </li>
+ <li>tvdpi or higher on extra large screens
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/H-8-1] The memory available to the kernel and userspace MUST be at least 1824MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>560dpi or higher on small/normal screens<sup>*</sup>
+ </li>
+ <li>400dpi or higher on large screens
+ </li>
+ <li>xhdpi or higher on extra large screens
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <p>
+ Note that the "memory available to the kernel and userspace" above refers to the memory space provided in addition to any memory already dedicated to hardware components such as radio, video, and so on that are not under the kernel’s control on device implementations.
+ </p>
+ <p>
+ Handheld device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#7_6_memory_and_storage">7.6</a>.2/H-0-1] MUST NOT provide an application shared storage smaller than 1 GiB.
+ </li>
+ <li>[<a href="#7_7_usb">7.7</a>.1/H] SHOULD include a USB port supporting peripheral mode.
+ </li>
+ </ul>
+ <p>
+ If handheld device implementations include a USB port supporting peripheral mode, they:
+ </p>
+ <ul>
+ <li>[<a href="#7_7_usb">7.7</a>.1/H-1-1] MUST implement the Android Open Accessory (AOA) API.
+ </li>
+ </ul>
+ <p>
+ Handheld device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#7_8_audio">7.8</a>.1/H-0-1] MUST include a microphone.
+ </li>
+ <li>[<a href="#7_8_audio">7.8</a>.2/H-0-1] MUST have an audio output and declare <code>android.hardware.audio.output</code>.
+ </li>
+ </ul>
+ <p>
+ If Handheld device implementations are capable of meeting all the performance requirements for supporting VR mode and include support for it, they:
+ </p>
+ <ul>
+ <li>[<a href="#7_9_virtual_reality">7.9</a>.1/H-1-1] MUST declare the <code>android.hardware.vr.high_performance</code> feature flag.
+ </li>
+ <li>[<a href="#7_9_virtual_reality">7.9</a>.1/H-1-2] MUST include an application implementing <code>android.service.vr.VrListenerService</code> that can be enabled by VR applications via <code>android.app.Activity#setVrModeEnabled</code>.
+ </li>
+ </ul>
+ <h4 id="2_2_2_multimedia">
+ 2.2.2. Multimedia
+ </h4>
+ <p>
+ Handheld device implementations MUST support the following audio encoding:
+ </p>
+ <ul>
+ <li>[<a href="#5_1_media_codecs">5.1</a>.1/H-0-1] AMR-NB
+ </li>
+ <li>[<a href="#5_1_media_codecs">5.1</a>.1/H-0-2] AMR-WB
+ </li>
+ <li>[<a href="#5_1_media_codecs">5.1</a>.1/H-0-3] MPEG-4 AAC Profile (AAC LC)
+ </li>
+ <li>[<a href="#5_1_media_codecs">5.1</a>.1/H-0-4] MPEG-4 HE AAC Profile (AAC+)
+ </li>
+ <li>[<a href="#5_1_media-codecs">5.1</a>.1/H-0-5] AAC ELD (enhanced low delay AAC)
+ </li>
+ </ul>
+ <p>
+ Handheld device implementations MUST support the following audio decoding:
+ </p>
+ <ul>
+ <li>[<a href="#5_1_media_codecs">5.1</a>.2/H-0-1] AMR-NB
+ </li>
+ <li>[<a href="#5_1_media_codecs">5.1</a>.2/H-0-2] AMR-WB
+ </li>
+ </ul>
+ <p>
+ Handheld device implementations MUST support the following video encoding and make it available to third-party applications:
+ </p>
+ <ul>
+ <li>[<a href="#5_2_video_encoding">5.2</a>/H-0-1] H.264 AVC
+ </li>
+ <li>[<a href="#5_2_video_encoding">5.2</a>/H-0-2] VP8
+ </li>
+ </ul>
+ <p>
+ Handheld device implementations MUST support the following video decoding:
+ </p>
+ <ul>
+ <li>[<a href="#5_3_video_decoding">5.3</a>/H-0-1] H.264 AVC
+ </li>
+ <li>[<a href="#5_3_video_decoding">5.3</a>/H-0-2] H.265 HEVC
+ </li>
+ <li>[<a href="#5_3_video_decoding">5.3</a>/H-0-3] MPEG-4 SP
+ </li>
+ <li>[<a href="#5_3_video_decoding">5.3</a>/H-0-4] VP8
+ </li>
+ <li>[<a href="#5_3_video_decoding">5.3</a>/H-0-5] VP9
+ </li>
+ </ul>
+ <h4 id="2_2_3_software">
+ 2.2.3. Software
+ </h4>
+ <p>
+ Handheld device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#3_2_3_1_core_application_intents">3.2.3.1</a>/H-0-1] MUST have an application that handles the <a href="https://developer.android.com/reference/android/content/Intent.html#ACTION_GET_CONTENT"><code>ACTION_GET_CONTENT</code></a>, <a href="https://developer.android.com/reference/android/content/Intent#ACTION_OPEN_DOCUMENT"><code>ACTION_OPEN_DOCUMENT</code></a>, <a href="https://developer.android.com/reference/android/content/Intent.html#ACTION_OPEN_DOCUMENT_TREE"><code>ACTION_OPEN_DOCUMENT_TREE</code></a>, and <a href="https://developer.android.com/reference/android/content/Intent.html#ACTION_CREATE_DOCUMENT"><code>ACTION_CREATE_DOCUMENT</code></a> intents as described in the SDK documents, and provide the user affordance to access the document provider data by using <a href="https://developer.android.com/reference/android/provider/DocumentsProvider"><code>DocumentsProvider</code></a> API.
+ </li>
+ <li>[<a href="#3_4_web_compatibility">3.4</a>.1/H-0-1] MUST provide a complete implementation of the <code>android.webkit.Webview</code> API.
+ </li>
+ <li>[<a href="#3_4_web_compatibility">3.4</a>.2/H-0-1] MUST include a standalone Browser application for general user web browsing.
+ </li>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.1/H-SR] Are STRONGLY RECOMMENDED to implement a default launcher that supports in-app pinning of shortcuts, widgets and <a href="https://developer.android.com/reference/android/appwidget/AppWidgetProviderInfo.html#widgetFeatures">widgetFeatures</a>.
+ </li>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.1/H-SR] Are STRONGLY RECOMMENDED to implement a default launcher that provides quick access to the additional shortcuts provided by third-party apps through the <a href="https://developer.android.com/reference/android/content/pm/ShortcutManager.html">ShortcutManager</a> API.
+ </li>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.1/H-SR] Are STRONGLY RECOMMENDED to include a default launcher app that shows badges for the app icons.
+ </li>
+ <li>[<a href="#3_8_user-interface_compatibility">3.8</a>.2/H-SR] Are STRONGLY RECOMMENDED to support third-party app widgets.
+ </li>
+ <li>[<a href="#3_8_user-interface_compatibility">3.8</a>.3/H-0-1] MUST allow third-party apps to notify users of notable events through the <a href="https://developer.android.com/reference/android/app/Notification.html"><code>Notification</code></a> and <a href="https://developer.android.com/reference/android/app/NotificationManager.html"><code>NotificationManager</code></a> API classes.
+ </li>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.3/H-0-2] MUST support rich notifications.
+ </li>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.3/H-0-3] MUST support heads-up notifications.
+ </li>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.3/H-0-4] MUST include a notification shade, providing the user the ability to directly control (e.g. reply, snooze, dismiss, block) the notifications through user affordance such as action buttons or the control panel as implemented in the AOSP.
+ </li>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.3/H-0-5] MUST display the choices provided through <a href="https://developer.android.com/reference/android/app/RemoteInput.Builder.html#setChoices%28java.lang.CharSequence[]%29"><code>RemoteInput.Builder setChoices()</code></a> in the notification shade.
+ </li>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.3/H-SR] Are STRONGLY RECOMMENDED to display the first choice provided through <a href="https://developer.android.com/reference/android/app/RemoteInput.Builder.html#setChoices%28java.lang.CharSequence[]%29"><code>RemoteInput.Builder setChoices()</code></a> in the notification shade without additional user interaction.
+ </li>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.3/H-SR] Are STRONGLY RECOMMENDED to display all the choices provided through <a href="https://developer.android.com/reference/android/app/RemoteInput.Builder.html#setChoices%28java.lang.CharSequence[]%29"><code>RemoteInput.Builder setChoices()</code></a> in the notification shade when the user expands all notifications in the notification shade.
+ </li>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.4/H-SR] Are STRONGLY RECOMMENDED to implement an assistant on the device to handle the <a href="http://developer.android.com/reference/android/content/Intent.html#ACTION_ASSIST">Assist action</a>.
+ </li>
+ </ul>
+ <p>
+ If Handheld device implementations support Assist action, they:
+ </p>
+ <ul>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.4/H-SR] Are STRONGLY RECOMMENDED to use long press on <code>HOME</code> key as the designated interaction to launch the assist app as described in <a href="#7_2_3_navigation_keys">section 7.2.3</a>. MUST launch the user-selected assist app, in other words the app that implements <a href="https://developer.android.com/reference/android/service/voice/VoiceInteractionService"><code>VoiceInteractionService</code></a> , or an activity handling the <code>ACTION_ASSIST</code> intent.
+ </li>
+ </ul>
+ <p>
+ If Android Handheld device implementations support a lock screen, they:
+ </p>
+ <ul>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.10/H-1-1] MUST display the Lock screen Notifications including the Media Notification Template.
+ </li>
+ </ul>
+ <p>
+ If Handheld device implementations support a secure lock screen, they:
+ </p>
+ <ul>
+ <li>[<a href="#3_9_device_administration">3.9</a>/H-1-1] MUST implement the full range of <a href="http://developer.android.com/guide/topics/admin/device-admin.html">device administration</a> policies defined in the Android SDK documentation.
+ </li>
+ <li>[<a href="#3_9_device_administration">3.9</a>/H-1-2] MUST declare the support of managed profiles via the <code>android.software.managed_users</code> feature flag, except when the device is configured so that it would <a href="http://developer.android.com/reference/android/app/ActivityManager.html#isLowRamDevice%28%29">report</a> itself as a low RAM device or so that it allocates internal (non-removable) storage as shared storage.
+ </li>
+ </ul>
+ <p>
+ Handheld device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#3_10_accessibility">3.10</a>/H-0-1] MUST support third-party accessibility services.
+ </li>
+ <li>[<a href="#3_10_accessibility">3.10</a>/H-SR] Are STRONGLY RECOMMENDED to preload accessibility services on the device comparable with or exceeding functionality of the Switch Access and TalkBack (for languages supported by the preloaded Text-to-speech engine) accessibility services as provided in the <a href="https://github.com/google/talkback">talkback open source project</a>.
+ </li>
+ <li>[<a href="#3_11_text_to_speech">3.11</a>/H-0-1] MUST support installation of third-party TTS engines.
+ </li>
+ <li>[<a href="#3_11_text_to_speech">3.11</a>/H-SR] Are STRONGLY RECOMMENDED to include a TTS engine supporting the languages available on the device.
+ </li>
+ <li>[<a href="#3_13_quick_settings">3.13</a>/H-SR] Are STRONGLY RECOMMENDED to include a Quick Settings UI component.
+ </li>
+ </ul>
+ <p>
+ If Android handheld device implementations declare <code>FEATURE_BLUETOOTH</code> or <code>FEATURE_WIFI</code> support, they:
+ </p>
+ <ul>
+ <li>[<a href="#3_15_instant_apps">3.15</a>/H-1-1] MUST support the companion device pairing feature.
+ </li>
+ </ul>
+ <h4 id="2_2_4_performance_and_power">
+ 2.2.4. Performance and Power
+ </h4>
+ <ul>
+ <li>[<a href="#8_1_user_experience_consistency">8.1</a>/H-0-1] <strong>Consistent frame latency</strong>. Inconsistent frame latency or a delay to render frames MUST NOT happen more often than 5 frames in a second, and SHOULD be below 1 frames in a second.
+ </li>
+ <li>[<a href="#8_1_user_experience_consistency">8.1</a>/H-0-2] <strong>User interface latency</strong>. Device implementations MUST ensure low latency user experience by scrolling a list of 10K list entries as defined by the Android Compatibility Test Suite (CTS) in less than 36 secs.
+ </li>
+ <li>[<a href="#8_1_user_experience_consistency">8.1</a>/H-0-3] <strong>Task switching</strong>. When multiple applications have been launched, re-launching an already-running application after it has been launched MUST take less than 1 second.
+ </li>
+ </ul>
+ <p>
+ Handheld device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#8_2_file_io_access_performance">8.2</a>/H-0-1] MUST ensure a sequential write performance of at least 5 MB/s.
+ </li>
+ <li>[<a href="#8_2_file_io_access_performance">8.2</a>/H-0-2] MUST ensure a random write performance of at least 0.5 MB/s.
+ </li>
+ <li>[<a href="#8_2_file_io_access_performance">8.2</a>/H-0-3] MUST ensure a sequential read performance of at least 15 MB/s.
+ </li>
+ <li>[<a href="#8_2_file_io_access_performance">8.2</a>/H-0-4] MUST ensure a random read performance of at least 3.5 MB/s.
+ </li>
+ </ul>
+ <p>
+ If Handheld device implementations include features to improve device power management that are included in AOSP or extend the features that are included in AOSP, they:
+ </p>
+ <ul>
+ <li>[<a href="#8_3_power_saving_modes">8.3</a>/H-1-1] MUST provide user affordance to enable and disable the battery saver feature.
+ </li>
+ <li>[<a href="#8_3_power_saving_modes">8.3</a>/H-1-2] MUST provide user affordance to display all apps that are exempted from App Standby and Doze power-saving modes.
+ </li>
+ </ul>
+ <p>
+ Handheld device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/H-0-1] MUST provide a per-component power profile that defines the <a href="http://source.android.com/devices/tech/power/values.html">current consumption value</a> for each hardware component and the approximate battery drain caused by the components over time as documented in the Android Open Source Project site.
+ </li>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/H-0-2] MUST report all power consumption values in milliampere hours (mAh).
+ </li>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/H-0-3] MUST report CPU power consumption per each process's UID. The Android Open Source Project meets the requirement through the <code>uid_cputime</code> kernel module implementation.
+ </li>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/H-0-4] MUST make this power usage available via the <a href="http://source.android.com/devices/tech/power/batterystats.html"><code>adb shell dumpsys batterystats</code></a> shell command to the app developer.
+ </li>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/H] SHOULD be attributed to the hardware component itself if unable to attribute hardware component power usage to an application.
+ </li>
+ </ul>
+ <p>
+ If Handheld device implementations include a screen or video output, they:
+ </p>
+ <ul>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/H-1-1] MUST honor the <a href="http://developer.android.com/reference/android/content/Intent.html#ACTION_POWER_USAGE_SUMMARY"><code>android.intent.action.POWER_USAGE_SUMMARY</code></a> intent and display a settings menu that shows this power usage.
+ </li>
+ </ul>
+ <h4 id="2_2_5_security_model">
+ 2.2.5. Security Model
+ </h4>
+ <p>
+ Handheld device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#9_1_permissions">9.1</a>/H-0-1] MUST allow third-party apps to access the usage statistics via the <code>android.permission.PACKAGE_USAGE_STATS</code> permission and provide a user-accessible mechanism to grant or revoke access to such apps in response to the <a href="https://developer.android.com/reference/android/provider/Settings.html#ACTION&lowbar;USAGE&lowbar;ACCESS&lowbar;SETTINGS"><code>android.settings.ACTION_USAGE_ACCESS_SETTINGS</code></a> intent.
+ </li>
+ </ul>
+ <p>
+ When Handheld device implementations support a secure lock screen, they:
+ </p>
+ <ul>
+ <li>[<a href="#9_11_permissions">9.11</a>/H-1-1] MUST allow the user to choose the shortest sleep timeout, that is a transition time from the unlocked to the locked state, as 15 seconds or less.
+ </li>
+ <li>[<a href="#9_11_permissions">9.11</a>/H-1-2] MUST provide user affordance to hide notifications and disable all forms of authentication except for the primary authentication described in <a href="#9_11_1_secure-lock-screen">9.11.1 Secure Lock Screen</a>. The AOSP meets the requirement as lockdown mode.
+ </li>
+ </ul>
+ <h3 id="2_3_television_requirements">
+ 2.3. Television Requirements
+ </h3>
+ <p>
+ An <strong>Android Television device</strong> refers to an Android device implementation that is an entertainment interface for consuming digital media, movies, games, apps, and/or live TV for users sitting about ten feet away (a “lean back” or “10-foot user interface”).
+ </p>
+ <p>
+ Android device implementations are classified as a Television if they meet all the following criteria:
+ </p>
+ <ul>
+ <li>Have provided a mechanism to remotely control the rendered user interface on the display that might sit ten feet away from the user.
+ </li>
+ <li>Have an embedded screen display with the diagonal length larger than 24 inches OR include a video output port, such as VGA, HDMI, DisplayPort, or a wireless port for display.
+ </li>
+ </ul>
+ <p>
+ The additional requirements in the rest of this section are specific to Android Television device implementations.
+ </p>
+ <h4 id="2_3_1_hardware">
+ 2.3.1. Hardware
+ </h4>
+ <p>
+ Television device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#7_2_input_devices">7.2</a>.2/T-0-1] MUST support <a href="https://developer.android.com/reference/android/content/res/Configuration.html#NAVIGATION_DPAD">D-pad</a>.
+ </li>
+ <li>[<a href="#7_2_input_devices">7.2</a>.3/T-0-1] MUST provide the Home and Back functions.
+ </li>
+ <li>[<a href="#7_2_input_devices">7.2</a>.3/T-0-2] MUST send both the normal and long press event of the Back function (<a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_BACK"><code>KEYCODE_BACK</code></a>) to the foreground application.
+ </li>
+ <li>[<a href="#7_2_input_devices">7.2</a>.6.1/T-0-1] MUST include support for game controllers and declare the <code>android.hardware.gamepad</code> feature flag.
+ </li>
+ <li>[<a href="#7_2_input_devices">7.2</a>.7/T] SHOULD provide a remote control from which users can access <a href="#7_2_2_non-touch_navigation">non-touch navigation</a> and <a href="#7_2_3_navigation_keys">core navigation keys</a> inputs.
+ </li>
+ </ul>
+ <p>
+ If Television device implementations include a gyroscope, they:
+ </p>
+ <ul>
+ <li>[<a href="#7_3_sensors">7.3</a>.4/T-1-1] MUST be able to report events up to a frequency of at least 100 Hz.
+ </li>
+ </ul>
+ <p>
+ Television device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#7_4_data_connectivity">7.4</a>.3/T-0-1] MUST support Bluetooth and Bluetooth LE.
+ </li>
+ <li>[<a href="#7_6_memory_and_storage">7.6</a>.1/T-0-1] MUST have at least 4 GB of non-volatile storage available for application private data (a.k.a. "/data" partition).
+ </li>
+ </ul>
+ <p>
+ If Television device implementations include a USB port that supports host mode, they:
+ </p>
+ <ul>
+ <li>[<a href="#7_5_camera">7.5</a>.3/T-1-1] MUST include support for an external camera that connects through this USB port but is not necessarily always connected.
+ </li>
+ </ul>
+ <p>
+ If TV device implementations are 32-bit:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/T-1-1] The memory available to the kernel and userspace MUST be at least 896MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>400dpi or higher on small/normal screens
+ </li>
+ <li>xhdpi or higher on large screens
+ </li>
+ <li>tvdpi or higher on extra large screens
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <p>
+ If TV device implementations are 64-bit:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/T-2-1] The memory available to the kernel and userspace MUST be at least 1280MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>400dpi or higher on small/normal screens
+ </li>
+ <li>xhdpi or higher on large screens
+ </li>
+ <li>tvdpi or higher on extra large screens
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <p>
+ Note that the "memory available to the kernel and userspace" above refers to the memory space provided in addition to any memory already dedicated to hardware components such as radio, video, and so on that are not under the kernel’s control on device implementations.
+ </p>
+ <p>
+ Television device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#7_8_audio">7.8</a>.1/T] SHOULD include a microphone.
+ </li>
+ <li>[<a href="#7_8_audio">7.8</a>.2/T-0-1] MUST have an audio output and declare <code>android.hardware.audio.output</code>.
+ </li>
+ </ul>
+ <h4 id="2_3_2_multimedia">
+ 2.3.2. Multimedia
+ </h4>
+ <p>
+ Television device implementations MUST support the following audio encoding formats:
+ </p>
+ <ul>
+ <li>[<a href="#5_1_media_codecs">5.1</a>/T-0-1] MPEG-4 AAC Profile (AAC LC)
+ </li>
+ <li>[<a href="#5_1_media_codecs">5.1</a>/T-0-2] MPEG-4 HE AAC Profile (AAC+)
+ </li>
+ <li>[<a href="#5_1_media_codecs">5.1</a>/T-0-3] AAC ELD (enhanced low delay AAC)
+ </li>
+ </ul>
+ <p>
+ Television device implementations MUST support the following video encoding formats:
+ </p>
+ <ul>
+ <li>[<a href="#5_2_video_encoding">5.2</a>/T-0-1] H.264
+ </li>
+ <li>[<a href="#5_2_video_encoding">5.2</a>/T-0-2] VP8
+ </li>
+ </ul>
+ <p>
+ Television device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#5_2_video_encoding">5.2</a>.2/T-SR] Are STRONGLY RECOMMENDED to support H.264 encoding of 720p and 1080p resolution videos at 30 frames per second.
+ </li>
+ </ul>
+ <p>
+ Television device implementations MUST support the following video decoding formats:
+ </p>
+ <ul>
+ <li>[<a href="#5_3_video_decoding">5.3.3</a>/T-0-1] MPEG-4 SP
+ </li>
+ <li>[<a href="#5_3_video_decoding">5.3.4</a>/T-0-2] H.264 AVC
+ </li>
+ <li>[<a href="#5_3_video_decoding">5.3.5</a>/T-0-3] H.265 HEVC
+ </li>
+ <li>[<a href="#5_3_video_decoding">5.3.6</a>/T-0-4] VP8
+ </li>
+ <li>[<a href="#5_3_video_decoding">5.3.7</a>/T-0-5] VP9
+ </li>
+ </ul>
+ <p>
+ Television device implementations are STRONGLY RECOMMENDED to support the following video decoding formats:
+ </p>
+ <ul>
+ <li>[<a href="#5_3_video_decoding">5.3.1</a>/T-SR] MPEG-2
+ </li>
+ </ul>
+ <p>
+ Television device implementations MUST support H.264 decoding, as detailed in Section 5.3.4, at standard video frame rates and resolutions up to and including:
+ </p>
+ <ul>
+ <li>[<a href="#5_3_video_decoding">5.3.4</a>.4/T-1-1] HD 1080p at 60 frames per second with Baseline Profile
+ </li>
+ <li>[<a href="#5_3_video_decoding">5.3.4</a>.4/T-1-2] HD 1080p at 60 frames per second with Main Profile
+ </li>
+ <li>[<a href="#5_3_video_decoding">5.3.4</a>.4/T-1-3] HD 1080p at 60 frames per second with High Profile Level 4.2
+ </li>
+ </ul>
+ <p>
+ Television device implementations with H.265 hardware decoders MUST support H.265 decoding, as detailed in Section 5.3.5, at standard video frame rates and resolutions up to and including:
+ </p>
+ <ul>
+ <li>[<a href="#5_3_video_decoding">5.3.5</a>.4/T-1-1] HD 1080p at 60 frames per second with Main Profile Level 4.1
+ </li>
+ </ul>
+ <p>
+ If Television device implementations with H.265 hardware decoders support H.265 decoding and the UHD decoding profile, they:
+ </p>
+ <ul>
+ <li>[<a href="#5_3_video_decoding">5.3.5</a>.5/T-2-1] MUST support UHD 3480p at 60 frames per second with Main10 Level 5 Main Tier profile.
+ </li>
+ </ul>
+ <p>
+ Television device implementations MUST support VP8 decoding, as detailed in Section 5.3.6, at standard video frame rates and resolutions up to and including:
+ </p>
+ <ul>
+ <li>[<a href="#5_3_video_decoding">5.3.6</a>.4/T-1-1] HD 1080p at 60 frames per second decoding profile
+ </li>
+ </ul>
+ <p>
+ Television device implementations with VP9 hardware decoders MUST support VP9 decoding, as detailed in Section 5.3.7, at standard video frame rates and resolutions up to and including:
+ </p>
+ <ul>
+ <li>[<a href="#5_3_video_decoding">5.3.7</a>.4/T-1-1] HD 1080p at 60 frames per second with profile 0 (8 bit colour depth)
+ </li>
+ </ul>
+ <p>
+ If Television device implementations with VP9 hardware decoders support VP9 decoding and the UHD decoding profile, they:
+ </p>
+ <ul>
+ <li>[<a href="#5_3_video_decoding">5.3.7</a>.5/T-2-1] MUST support UHD 3480p at 60 frames per second with profile 0 (8 bit colour depth).
+ </li>
+ <li>[<a href="#5_3_video_decoding">5.3.7</a>.5/T-2-1] Are STRONGLY RECOMMENDED to support UHD 3480p at 60 frames per second with profile 2 (10 bit colour depth).
+ </li>
+ </ul>
+ <p>
+ Television device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#5_5_audio_playback">5.5</a>.3/T-0-1] MUST include support for system Master Volume and digital audio output volume attenuation on supported outputs, except for compressed audio passthrough output (where no audio decoding is done on the device).
+ </li>
+ <li>[<a href="#5_8_secure_media">5.8</a>/T-0-1] MUST set the HDMI output mode to select the maximum resolution that can be supported with either 50Hz or 60Hz refresh rate for all wired displays.
+ </li>
+ <li>[<a href="#5_8_secure_media">5.8</a>/T-SR] Are STRONGLY RECOMMENDED to provide a user configurable HDMI refresh rate selector for all wired displays.
+ </li>
+ <li>[<a href="#5_8_secure_media">5.8</a>/T-SR] Are STRONGLY RECOMMENDED to support simultaneous decoding of secure streams. At minimum, simultaneous decoding of two steams is STRONGLY RECOMMENDED.
+ </li>
+ <li>[<a href="#5_8_secure_media">5.8</a>] SHOULD set the HDMI output mode refresh rate to either 50Hz or 60Hz, depending on the video refresh rate for the region the device is sold in for all wired displays.
+ </li>
+ </ul>
+ <p>
+ If Television device implementations support UHD decoding and have support for external displays, they:
+ </p>
+ <ul>
+ <li>[<a href="#5_8_secure_media">5.8</a>/T-1-1] MUST support HDCP 2.2.
+ </li>
+ </ul>
+ <p>
+ If Television device implementations do not support UHD decoding but have support for external displays, they:
+ </p>
+ <ul>
+ <li>[<a href="#5_8_secure_media">5.8</a>/T-2-1] MUST support HDCP 1.4
+ </li>
+ </ul>
+ <h4 id="2_3_3_software">
+ 2.3.3. Software
+ </h4>
+ <p>
+ Television device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#3_0_intro">3</a>/T-0-1] MUST declare the features <a href="http://developer.android.com/reference/android/content/pm/PackageManager.html#FEATURE_LEANBACK"><code>android.software.leanback</code></a> and <code>android.hardware.type.television</code>.
+ </li>
+ <li>[<a href="#3_4_web_compatibility">3.4</a>.1/T-0-1] MUST provide a complete implementation of the <code>android.webkit.Webview</code> API.
+ </li>
+ </ul>
+ <p>
+ If Android Television device implementations support a lock screen,they:
+ </p>
+ <ul>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.10/T-1-1] MUST display the Lock screen Notifications including the Media Notification Template.
+ </li>
+ </ul>
+ <p>
+ Television device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.14/T-SR] Are STRONGLY RECOMMENDED to support picture-in-picture (PIP) mode multi-window.
+ </li>
+ <li>[<a href="#3_10_accessibility">3.10</a>/T-0-1] MUST support third-party accessibility services.
+ </li>
+ <li>[<a href="#3_10_accessibility">3.10</a>/T-SR] Are STRONGLY RECOMMENDED to preload accessibility services on the device comparable with or exceeding functionality of the Switch Access and TalkBack (for languages supported by the preloaded Text-to-speech engine) accessibility services as provided in the <a href="https://github.com/google/talkback">talkback open source project</a>.
+ </li>
+ </ul>
+ <p>
+ If Television device implementations report the feature <code>android.hardware.audio.output</code>, they:
+ </p>
+ <ul>
+ <li>[<a href="#3_11_text_to_speech">3.11</a>/T-SR] Are STRONGLY RECOMMENDED to include a TTS engine supporting the languages available on the device.
+ </li>
+ <li>[<a href="#3_11_text_to_speech">3.11</a>/T-1-1] MUST support installation of third-party TTS engines.
+ </li>
+ </ul>
+ <p>
+ Television device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#3_12_tv_input_framework">3.12</a>/T-0-1] MUST support TV Input Framework.
+ </li>
+ </ul>
+ <h4 id="2_3_4_performance_and_power">
+ 2.3.4. Performance and Power
+ </h4>
+ <ul>
+ <li>[<a href="#8_1_user_experience_consistency">8.1</a>/T-0-1] <strong>Consistent frame latency</strong>. Inconsistent frame latency or a delay to render frames MUST NOT happen more often than 5 frames in a second, and SHOULD be below 1 frames in a second.
+ </li>
+ <li>[<a href="#8_2_file_io_access_performance">8.2</a>/T-0-1] MUST ensure a sequential write performance of at least 5MB/s.
+ </li>
+ <li>[<a href="#8_2_file_io_access_performance">8.2</a>/T-0-2] MUST ensure a random write performance of at least 0.5MB/s.
+ </li>
+ <li>[<a href="#8_2_file_io_access_performance">8.2</a>/T-0-3] MUST ensure a sequential read performance of at least 15MB/s.
+ </li>
+ <li>[<a href="#8_2_file_io_access_performance">8.2</a>/T-0-4] MUST ensure a random read performance of at least 3.5MB/s.
+ </li>
+ </ul>
+ <p>
+ If Television device implementations include features to improve device power management that are included in AOSP or extend the features that are included in AOSP, they:
+ </p>
+ <ul>
+ <li>[<a href="#8_3_power_saving_modes">8.3</a>/T-1-1] MUST provide user affordance to enable and disable the battery saver feature.
+ </li>
+ <li>[<a href="#8_3_power_saving_modes">8.3</a>/T-1-2] MUST provide user affordance to display all apps that are exempted from App Standby and Doze power-saving modes.
+ </li>
+ </ul>
+ <p>
+ Television device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/T-0-1] MUST provide a per-component power profile that defines the <a href="http://source.android.com/devices/tech/power/values.html">current consumption value</a> for each hardware component and the approximate battery drain caused by the components over time as documented in the Android Open Source Project site.
+ </li>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/T-0-2] MUST report all power consumption values in milliampere hours (mAh).
+ </li>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/T-0-3] MUST report CPU power consumption per each process's UID. The Android Open Source Project meets the requirement through the <code>uid_cputime</code> kernel module implementation.
+ </li>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/T] SHOULD be attributed to the hardware component itself if unable to attribute hardware component power usage to an application.
+ </li>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/T-0-4] MUST make this power usage available via the <a href="http://source.android.com/devices/tech/power/batterystats.html"><code>adb shell dumpsys batterystats</code></a> shell command to the app developer.
+ </li>
+ </ul>
+ <h3 id="2_4_watch_requirements">
+ 2.4. Watch Requirements
+ </h3>
+ <p>
+ An <strong>Android Watch device</strong> refers to an Android device implementation intended to be worn on the body, perhaps on the wrist.
+ </p>
+ <p>
+ Android device implementations are classified as a Watch if they meet all the following criteria:
+ </p>
+ <ul>
+ <li>Have a screen with the physical diagonal length in the range from 1.1 to 2.5 inches.
+ </li>
+ <li>Have a mechanism provided to be worn on the body.
+ </li>
+ </ul>
+ <p>
+ The additional requirements in the rest of this section are specific to Android Watch device implementations.
+ </p>
+ <h4 id="2_4_1_hardware">
+ 2.4.1. Hardware
+ </h4>
+ <p>
+ Watch device implementations:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [<a href="#7_1_display_and_graphics">7.1</a>.1.1/W-0-1] MUST have a screen with the physical diagonal size in the range from 1.1 to 2.5 inches.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_2_input_devices">7.2</a>.3/W-0-1] MUST have the Home function available to the user, and the Back function except for when it is in <code>UI_MODE_TYPE_WATCH</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_2_input_devices">7.2</a>.4/W-0-1] MUST support touchscreen input.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_3_sensors">7.3</a>.1/W-SR] Are STRONGLY RECOMMENDED to include a 3-axis accelerometer.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_4_data_connectivity">7.4</a>.3/W-0-1] MUST support Bluetooth.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/W-0-1] MUST have at least 1 GB of non-volatile storage available for application private data (a.k.a. "/data" partition).
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/W-0-2] MUST have at least 416 MB memory available to the kernel and userspace.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_8_audio">7.8</a>.1/W-0-1] MUST include a microphone.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_8_audio">7.8</a>.2/W] MAY but SHOULD NOT have audio output.
+ </p>
+ </li>
+ </ul>
+ <h4 id="2_4_2_multimedia">
+ 2.4.2. Multimedia
+ </h4>
+ <p>
+ No additional requirements.
+ </p>
+ <h4 id="2_4_3_software">
+ 2.4.3. Software
+ </h4>
+ <p>
+ Watch device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#3_0_intro">3</a>/W-0-1] MUST declare the feature <code>android.hardware.type.watch</code>.
+ </li>
+ <li>[<a href="#3_0_intro">3</a>/W-0-2] MUST support uiMode = <a href="http://developer.android.com/reference/android/content/res/Configuration.html#UI_MODE_TYPE_WATCH">UI_MODE_TYPE_WATCH</a>.
+ </li>
+ </ul>
+ <p>
+ Watch device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.4/W-SR] Are STRONGLY RECOMMENDED to implement an assistant on the device to handle the <a href="http://developer.android.com/reference/android/content/Intent.html#ACTION_ASSIST">Assist action</a>.
+ </li>
+ </ul>
+ <p>
+ Watch device implementations that declare the <code>android.hardware.audio.output</code> feature flag:
+ </p>
+ <ul>
+ <li>[<a href="#3_10_accessibility">3.10</a>/W-1-1] MUST support third-party accessibility services.
+ </li>
+ <li>[<a href="#3_10_accessibility">3.10</a>/W-SR] Are STRONGLY RECOMMENDED to preload accessibility services on the device comparable with or exceeding functionality of the Switch Access and TalkBack (for languages supported by the preloaded Text-to-speech engine) accessibility services as provided in the <a href="https://github.com/google/talkback">talkback open source project</a>.
+ </li>
+ </ul>
+ <p>
+ If Watch device implementations report the feature android.hardware.audio.output, they:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [<a href="#3_11_text_to_speech">3.11</a>/W-SR] Are STRONGLY RECOMMENDED to include a TTS engine supporting the languages available on the device.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#3_11_text_to_speech">3.11</a>/W-0-1] MUST support installation of third-party TTS engines.
+ </p>
+ </li>
+ </ul>
+ <h4 id="2_4_4_performance_and_power">
+ 2.4.4. Performance and Power
+ </h4>
+ <p>
+ If Watch device implementations include features to improve device power management that are included in AOSP or extend the features that are included in AOSP, they:
+ </p>
+ <ul>
+ <li>[<a href="#8_3_power_saving_modes">8.3</a>/W-SR] Are STRONGLY RECOMMENDED to provide user affordance to display all apps that are exempted from App Standby and Doze power-saving modes.
+ </li>
+ <li>[<a href="#8_3_power_saving_modes">8.3</a>/W-SR] Are STRONGLY RECOMMENDED to provide user affordance to enable and disable the battery saver feature.
+ </li>
+ </ul>
+ <p>
+ Watch device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/W-0-1] MUST provide a per-component power profile that defines the <a href="http://source.android.com/devices/tech/power/values.html">current consumption value</a> for each hardware component and the approximate battery drain caused by the components over time as documented in the Android Open Source Project site.
+ </li>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/W-0-2] MUST report all power consumption values in milliampere hours (mAh).
+ </li>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/W-0-3] MUST report CPU power consumption per each process's UID. The Android Open Source Project meets the requirement through the <code>uid_cputime</code> kernel module implementation.
+ </li>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/W-0-4] MUST make this power usage available via the <a href="http://source.android.com/devices/tech/power/batterystats.html"><code>adb shell dumpsys batterystats</code></a> shell command to the app developer.
+ </li>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/W] SHOULD be attributed to the hardware component itself if unable to attribute hardware component power usage to an application.
+ </li>
+ </ul>
+ <h3 id="2_5_automotive_requirements">
+ 2.5. Automotive Requirements
+ </h3>
+ <p>
+ <strong>Android Automotive implementation</strong> refers to a vehicle head unit running Android as an operating system for part or all of the system and/or infotainment functionality.
+ </p>
+ <p>
+ Android device implementations are classified as an Automotive if they declare the feature <code>android.hardware.type.automotive</code> or meet all the following criteria.
+ </p>
+ <ul>
+ <li>Are embedded as part of, or pluggable to, an automotive vehicle.
+ </li>
+ <li>Are using a screen in the driver's seat row as the primary display.
+ </li>
+ </ul>
+ <p>
+ The additional requirements in the rest of this section are specific to Android Automotive device implementations.
+ </p>
+ <h4 id="2_5_1_hardware">
+ 2.5.1. Hardware
+ </h4>
+ <p>
+ Automotive device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#7_1_display_and-graphics">7.1</a>.1.1/A-0-1] MUST have a screen at least 6 inches in physical diagonal size.
+ </li>
+ <li>
+ <p>
+ [<a href="#7_1_display_and_graphics">7.1</a>.1.1/A-0-2] MUST have a screen size layout of at least 750 dp x 480 dp.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_2_input_devices">7.2</a>.3/A-0-1] MUST provide the Home function and MAY provide Back and Recent functions.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_2_input_devices">7.2</a>.3/A-0-2] MUST send both the normal and long press event of the Back function (<a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_BACK"><code>KEYCODE_BACK</code></a>) to the foreground application.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_3_sensors">7.3</a>.1/A-SR] Are STRONGLY RECOMMENDED to include a 3-axis accelerometer.
+ </p>
+ </li>
+ </ul>
+ <p>
+ If Automotive device implementations include a 3-axis accelerometer, they:
+ </p>
+ <ul>
+ <li>[<a href="#7_3_sensors">7.3</a>.1/A-1-1] MUST be able to report events up to a frequency of at least 100 Hz.
+ </li>
+ <li>[<a href="#7_3_sensors">7.3</a>.1/A-1-2] MUST comply with the Android <a href="http://source.android.com/devices/sensors/sensor-types.html#auto_axes">car sensor coordinate system</a>.
+ </li>
+ </ul>
+ <p>
+ If Automotive device implementations include a GPS/GNSS receiver and report the capability to applications through the <code>android.hardware.location.gps</code> feature flag:
+ </p>
+ <ul>
+ <li>[<a href="#7_3_sensors">7.3</a>.3/A-1-1] GNSS technology generation MUST be the year "2017" or newer.
+ </li>
+ </ul>
+ <p>
+ If Automotive device implementations include a gyroscope, they:
+ </p>
+ <ul>
+ <li>[<a href="#7_3_sensors">7.3</a>.4/A-1-1] MUST be able to report events up to a frequency of at least 100 Hz.
+ </li>
+ </ul>
+ <p>
+ Automotive device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#7_3_sensors">7.3</a>.11/A-0-1] MUST provide current gear as <code>SENSOR_TYPE_GEAR</code>.
+ </li>
+ </ul>
+ <p>
+ Automotive device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#7_3_sensors">7.3</a>.11.2/A-0-1] MUST support day/night mode defined as <code>SENSOR_TYPE_NIGHT</code>.
+ </li>
+ <li>[<a href="#7_3_sensors">7.3</a>.11.2/A-0-2] The value of the <code>SENSOR_TYPE_NIGHT</code> flag MUST be consistent with dashboard day/night mode and SHOULD be based on ambient light sensor input.
+ </li>
+ <li>
+ <p>
+ The underlying ambient light sensor MAY be the same as <a href="#7_3_7_photometer">Photometer</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_3_sensors">7.3</a>.11.4/A-0-1] MUST provide vehicle speed as defined by <code>SENSOR_TYPE_CAR_SPEED</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_3_sensors">7.3</a>.11.5/A-0-1] MUST provide parking brake status as defined by <code>SENSOR_TYPE_PARKING_BRAKE</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_4_data_connectivity">7.4</a>.3/A-0-1] MUST support Bluetooth and SHOULD support Bluetooth LE.
+ </p>
+ </li>
+ <li>[<a href="#7_4_data_connectivity">7.4</a>.3/A-0-2] Android Automotive implementations MUST support the following Bluetooth profiles:
+ <ul>
+ <li>Phone calling over Hands-Free Profile (HFP).
+ </li>
+ <li>Media playback over Audio Distribution Profile (A2DP).
+ </li>
+ <li>Media playback control over Remote Control Profile (AVRCP).
+ </li>
+ <li>Contact sharing using the Phone Book Access Profile (PBAP).
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_4_data_connectivity">7.4</a>.3/A-SR] Are STRONGLY RECOMMENDED to support Message Access Profile (MAP).
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_4_data_connectivity">7.4</a>.5/A] SHOULD include support for cellular network-based data connectivity.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_4_data_connectivity">7.4</a>.5/A] MAY use the System API <code>NetworkCapabilities#NET_CAPABILITY_OEM_PAID</code> constant for networks that should be available to system apps.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/A-0-1] MUST have at least 4 GB of non-volatile storage available for application private data (a.k.a. "/data" partition).
+ </p>
+ </li>
+ </ul>
+ <p>
+ Automotive device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#7_6_memory_and_storage">7.6</a>.1/A] SHOULD format the data partition to offer improved performance and longevity on flash storage, for example using <code>f2fs</code> file-system.
+ </li>
+ </ul>
+ <p>
+ If Automotive device implementations provide shared external storage via a portion of the internal non-removable storage, they:
+ </p>
+ <ul>
+ <li>[<a href="#7_6_memory_and_storage">7.6</a>.1/A-SR] Are STRONGLY RECOMMENDED to reduce I/O overhead on operations performed on the external storage, for example by using <code>SDCardFS</code>.
+ </li>
+ </ul>
+ <p>
+ If Automotive device implementations are 32-bit:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/A-1-1] The memory available to the kernel and userspace MUST be at least 512MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>280dpi or lower on small/normal screens
+ </li>
+ <li>ldpi or lower on extra large screens
+ </li>
+ <li>mdpi or lower on large screens
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/A-1-2] The memory available to the kernel and userspace MUST be at least 608MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>xhdpi or higher on small/normal screens
+ </li>
+ <li>hdpi or higher on large screens
+ </li>
+ <li>mdpi or higher on extra large screens
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/A-1-3] The memory available to the kernel and userspace MUST be at least 896MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>400dpi or higher on small/normal screens
+ </li>
+ <li>xhdpi or higher on large screens
+ </li>
+ <li>tvdpi or higher on extra large screens
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/A-1-4] The memory available to the kernel and userspace MUST be at least 1344MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>560dpi or higher on small/normal screens
+ </li>
+ <li>400dpi or higher on large screens
+ </li>
+ <li>xhdpi or higher on extra large screens
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <p>
+ If Automotive device implementations are 64-bit:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/A-2-1] The memory available to the kernel and userspace MUST be at least 816MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>280dpi or lower on small/normal screens
+ </li>
+ <li>ldpi or lower on extra large screens
+ </li>
+ <li>mdpi or lower on large screens
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/A-2-2] The memory available to the kernel and userspace MUST be at least 944MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>xhdpi or higher on small/normal screens
+ </li>
+ <li>hdpi or higher on large screens
+ </li>
+ <li>mdpi or higher on extra large screens
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/A-2-3] The memory available to the kernel and userspace MUST be at least 1280MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>400dpi or higher on small/normal screens
+ </li>
+ <li>xhdpi or higher on large screens
+ </li>
+ <li>tvdpi or higher on extra large screens
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/A-2-4] The memory available to the kernel and userspace MUST be at least 1824MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>560dpi or higher on small/normal screens
+ </li>
+ <li>400dpi or higher on large screens
+ </li>
+ <li>xhdpi or higher on extra large screens
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <p>
+ Note that the "memory available to the kernel and userspace" above refers to the memory space provided in addition to any memory already dedicated to hardware components such as radio, video, and so on that are not under the kernel’s control on device implementations.
+ </p>
+ <p>
+ Automotive device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#7_7_usb">7.7</a>.1/A] SHOULD include a USB port supporting peripheral mode.
+ </li>
+ </ul>
+ <p>
+ Automotive device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#7_8_audio">7.8</a>.1/A-0-1] MUST include a microphone.
+ </li>
+ </ul>
+ <p>
+ Automotive device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#7_8_audio">7.8</a>.2/A-0-1] MUST have an audio output and declare <code>android.hardware.audio.output</code>.
+ </li>
+ </ul>
+ <h4 id="2_5_2_multimedia">
+ 2.5.2. Multimedia
+ </h4>
+ <p>
+ Automotive device implementations MUST support the following audio encoding:
+ </p>
+ <ul>
+ <li>[<a href="#5_1_media_codecs">5.1</a>/A-0-1] MPEG-4 AAC Profile (AAC LC)
+ </li>
+ <li>[<a href="#5_1_media_codecs">5.1</a>/A-0-2] MPEG-4 HE AAC Profile (AAC+)
+ </li>
+ <li>[<a href="#5_1_media_codecs">5.1</a>/A-0-3] AAC ELD (enhanced low delay AAC)
+ </li>
+ </ul>
+ <p>
+ Automotive device implementations MUST support the following video encoding:
+ </p>
+ <ul>
+ <li>[<a href="#5_2_video_encoding">5.2</a>/A-0-1] H.264 AVC
+ </li>
+ <li>[<a href="#5_2_video_encoding">5.2</a>/A-0-2] VP8
+ </li>
+ </ul>
+ <p>
+ Automotive device implementations MUST support the following video decoding:
+ </p>
+ <ul>
+ <li>[<a href="#5_3_video_decoding">5.3</a>/A-0-1] H.264 AVC
+ </li>
+ <li>[<a href="#5_3_video_decoding">5.3</a>/A-0-2] MPEG-4 SP
+ </li>
+ <li>[<a href="#5_3_video_decoding">5.3</a>/A-0-3] VP8
+ </li>
+ <li>[<a href="#5_3_video_decoding">5.3</a>/A-0-4] VP9
+ </li>
+ </ul>
+ <p>
+ Automotive device implementations are STRONGLY RECOMMENDED to support the following video decoding:
+ </p>
+ <ul>
+ <li>[<a href="#5_3_video_decoding">5.3</a>/A-SR] H.265 HEVC
+ </li>
+ </ul>
+ <h4 id="2_5_3_software">
+ 2.5.3. Software
+ </h4>
+ <p>
+ Automotive device implementations:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [<a href="#3_0_intro">3</a>/A-0-1] MUST declare the feature <code>android.hardware.type.automotive</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#3_0_intro">3</a>/A-0-2] MUST support uiMode = <a href="http://developer.android.com/reference/android/content/res/Configuration.html#UI_MODE_TYPE_CAR"><code>UI_MODE_TYPE_CAR</code></a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#3_0_intro">3</a>/A-0-3] MUST support all public APIs in the <a href="https://developer.android.com/reference/android/car/package-summary"><code>android.car.*</code></a> namespace.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#3_4_web_compatibility">3.4</a>.1/A-0-1] MUST provide a complete implementation of the <code>android.webkit.Webview</code> API.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#3_8_user_interface_compatibility">3.8</a>.3/A-0-1] MUST display notifications that use the <a href="https://developer.android.com/reference/android/app/Notification.CarExtender.html"><code>Notification.CarExtender</code></a> API when requested by third-party applications.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#3_8_user_interface_compatibility">3.8</a>.4/A-0-1] MUST implement an assistant on the device that provides a default implementation of the <a href="https://developer.android.com/reference/android/service/voice/VoiceInteractionSession"><code>VoiceInteractionSession</code></a> service.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#3_13_quick_settings">3.13</a>/A-SR] Are STRONGLY RECOMMENDED to include a Quick Settings UI component.
+ </p>
+ </li>
+ </ul>
+ <p>
+ If Automotive device implementations include a push-to-talk button, they:
+ </p>
+ <ul>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.4/A-1-1] MUST use a short press of the push-to-talk button as the designated interaction to launch the user-selected assist app, in other words the app that implements <a href="https://developer.android.com/reference/android/service/voice/VoiceInteractionService"><code>VoiceInteractionService</code></a>.
+ </li>
+ </ul>
+ <p>
+ Automotive device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#3_14_media_ui">3.14</a>/A-0-1] MUST include a UI framework to support third-party apps using the media APIs as described in section <a href="#3_14_media_ui">3.14</a>.
+ </li>
+ </ul>
+ <h4 id="2_5_4_performance_and_power">
+ 2.5.4. Performance and Power
+ </h4>
+ <p>
+ If Automotive device implementations include features to improve device power management that are included in AOSP or extend the features that are included in AOSP, they:
+ </p>
+ <ul>
+ <li>[<a href="#8_3_power_saving_modes">8.3</a>/A-1-1] MUST provide user affordance to enable and disable the battery saver feature.
+ </li>
+ <li>[<a href="#8_3_power_saving_modes">8.3</a>/A-1-2] MUST provide user affordance to display all apps that are exempted from App Standby and Doze power-saving modes.
+ </li>
+ </ul>
+ <p>
+ Automotive device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#8_2_file_i/o_access_performance">8.2</a>/A-0-1] MUST report the number of bytes read and written to non-volatile storage per each process's UID so the stats are available to developers through System API <code>android.car.storagemonitoring.CarStorageMonitoringManager</code>. The Android Open Source Project meets the requirement through the <code>uid_sys_stats</code> kernel module.
+ </li>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/A-0-1] MUST provide a per-component power profile that defines the <a href="http://source.android.com/devices/tech/power/values.html">current consumption value</a> for each hardware component and the approximate battery drain caused by the components over time as documented in the Android Open Source Project site.
+ </li>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/A-0-2] MUST report all power consumption values in milliampere hours (mAh).
+ </li>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/A-0-3] MUST report CPU power consumption per each process's UID. The Android Open Source Project meets the requirement through the <code>uid_cputime</code> kernel module implementation.
+ </li>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/A] SHOULD be attributed to the hardware component itself if unable to attribute hardware component power usage to an application.
+ </li>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/A-0-4] MUST make this power usage available via the <a href="http://source.android.com/devices/tech/power/batterystats.html"><code>adb shell dumpsys batterystats</code></a> shell command to the app developer.
+ </li>
+ </ul>
+ <h4 id="2_5_5_security_model">
+ 2.5.5. Security Model
+ </h4>
+ <p>
+ If Automotive device implementations support multiple users, they:
+ </p>
+ <ul>
+ <li>[<a href="#9_5_multi_user_support">9.5</a>/A-1-1] MUST include a guest account that allows all functions provided by the vehicle system without requiring a user to log in.
+ </li>
+ </ul>
+ <p>
+ If Automotive device implementations support a secure lock screen, they:
+ </p>
+ <ul>
+ <li>[<a href="#9_9_full_disk_encryption">9.9</a>.2/A-1-1] MUST support encryption per user-specific authentication keys. <a href="https://source.android.com/security/encryption/file-based">File-Based Encryption (FBE)</a> is one way to do it.
+ </li>
+ </ul>
+ <p>
+ Automotive device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#9_14_automotive_system_isolation">9.14</a>/A-0-1] MUST gatekeep messages from Android framework vehicle subsystems, e.g., whitelisting permitted message types and message sources.
+ </li>
+ <li>[<a href="#9_14_automotive_system_isolation">9.14</a>/A-0-2] MUST watchdog against denial of service attacks from the Android framework or third-party apps. This guards against malicious software flooding the vehicle network with traffic, which may lead to malfunctioning vehicle subsystems.
+ </li>
+ </ul>
+ <h3 id="2_6_tablet_requirements">
+ 2.6. Tablet Requirements
+ </h3>
+ <p>
+ An <strong>Android Tablet device</strong> refers to an Android device implementation that is typically used by holding in both hands and not in a clamshell form-factor.
+ </p>
+ <p>
+ Android device implementations are classified as a Tablet if they meet all the following criteria:
+ </p>
+ <ul>
+ <li>Have a power source that provides mobility, such as a battery.
+ </li>
+ <li>Have a physical diagonal screen size in the range of 7 to 18 inches.
+ </li>
+ </ul>
+ <p>
+ Tablet device implementations have similar requirements to handheld device implementations. The exceptions are in indicated by an * in that section and noted for reference in this section.
+ </p>
+ <h4 id="2_4_1_hardware">
+ 2.4.1. Hardware
+ </h4>
+ <p>
+ <strong>Screen Size</strong>
+ </p>
+ <ul>
+ <li>[<a href="#7_1_display_and_graphics">7.1</a>.1.1/Tab-0-1] MUST have a screen in the range of 7 to 18 inches.
+ </li>
+ </ul>
+ <p>
+ <strong>Minimum Memory and Storage (Section 7.6.1)</strong>
+ </p>
+ <p>
+ The screen densities listed for small/normal screens in the handheld requirements are not applicable to tablets.
+ </p>
+ <p>
+ <strong>USB peripheral mode (Section 7.7.1)</strong>
+ </p>
+ <p>
+ If tablet device implementations include a USB port supporting peripheral mode, they:
+ </p>
+ <ul>
+ <li>[<a href="#7_7_usb">7.7.1</a>/Tab] MAY implement the Android Open Accessory (AOA) API.
+ </li>
+ </ul>
+ <p>
+ <strong>Virtual Reality Mode (Section 7.9.1)</strong>
+ </p>
+ <p>
+ <strong>Virtual Reality High Performance (Section 7.9.2)</strong>
+ </p>
+ <p>
+ Virtual reality requirements are not applicable to tablets.
+ </p>
+ <h2 id="3_software">
+ 3. Software
+ </h2>
+ <h3 id="3_1_managed_api_compatibility">
+ 3.1. Managed API Compatibility
+ </h3>
+ <p>
+ The managed Dalvik bytecode execution environment is the primary vehicle for Android applications. The Android application programming interface (API) is the set of Android platform interfaces exposed to applications running in the managed runtime environment.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-0-1] MUST provide complete implementations, including all documented behaviors, of any documented API exposed by the <a href="http://developer.android.com/reference/packages.html">Android SDK</a> or any API decorated with the “@SystemApi” marker in the upstream Android source code.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-2] MUST support/preserve all classes, methods, and associated elements marked by the TestApi annotation (@TestApi).
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-3] MUST NOT omit any managed APIs, alter API interfaces or signatures, deviate from the documented behavior, or include no-ops, except where specifically allowed by this Compatibility Definition.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-4] MUST still keep the APIs present and behave in a reasonable way, even when some hardware features for which Android includes APIs are omitted. See <a href="#7_hardware_compatibility">section 7</a> for specific requirements for this scenario.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-5] MUST restrict the use of 3rd-party app usage of hidden APIs, defined as APIs in the android namespace decorated with the <code>@hidden</code> annotation but not with a <code>@SystemAPI</code> or <code>@TestApi</code>, as described in the <a href="https://developer.android.com/preview/restrictions-non-sdk-interfaces">SDK documents</a> and ship with each and every hidden API on the same restricted lists as provided via the light-greylist, dark-greylist, and blacklist files in the <code>prebuilts/runtime/appcompat/</code> path for the appropriate API level branch in the AOSP. However they:
+ </p>
+ <ul>
+ <li>MAY, if a hidden API is absent or implemented differently on the device implementation, move the hidden API into the blacklist or omit it from all restricted lists (i.e. light-grey, dark-grey, black).
+ </li>
+ <li>MAY, if a hidden API does not already exist in the AOSP, add the hidden API to any of the restricted lists (i.e. light-grey, dark-grey, black).
+ </li>
+ <li>MAY implement a dynamic update mechanism that moves a hidden API from a restricted list into a less restrictive list, except for the whitelist.
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <h3 id="3_1_1_android_extensions">
+ 3.1.1. Android Extensions
+ </h3>
+ <p>
+ Android includes the support of extending the managed APIs while keeping the same API level version.
+ </p>
+ <ul>
+ <li>[C-0-1] Android device implementations MUST preload the AOSP implementation of both the shared library <code>ExtShared</code> and services <code>ExtServices</code> with versions higher than or equal to the minimum versions allowed per each API level. For example, Android 7.0 device implementations, running API level 24 MUST include at least version 1.
+ </li>
+ </ul>
+ <h3 id="3_1_2_android_library">
+ 3.1.2. Android Library
+ </h3>
+ <p>
+ Due to <a href="https://developer.android.com/preview/behavior-changes#apache-p">Apache HTTP client deprecation</a>, device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST NOT place the <code>org.apache.http.legacy</code> library in the bootclasspath.
+ </li>
+ <li>[C-0-2] MUST add the <code>org.apache.http.legacy</code> library to the application classpath only when the app satisfies one of the following conditions:
+ <ul>
+ <li>Targets API level 28 or lower.
+ </li>
+ <li>Declares in its manifest that it needs the library by setting the <code>android:name</code> attribute of <code><uses-library></code> to <code>org.apache.http.legacy</code>.
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <p>
+ The AOSP implementation meets these requirements.
+ </p>
+ <h3 id="3_2_soft_api_compatibility">
+ 3.2. Soft API Compatibility
+ </h3>
+ <p>
+ In addition to the managed APIs from <a href="#3_1_managed_api_compatibility">section 3.1</a>, Android also includes a significant runtime-only “soft” API, in the form of such things as intents, permissions, and similar aspects of Android applications that cannot be enforced at application compile time.
+ </p>
+ <h4 id="3_2_1_permissions">
+ 3.2.1. Permissions
+ </h4>
+ <ul>
+ <li>[C-0-1] Device implementers MUST support and enforce all permission constants as documented by the <a href="http://developer.android.com/reference/android/Manifest.permission.html">Permission reference page</a>. Note that <a href="#9_security_model_compatibility">section 9</a> lists additional requirements related to the Android security model.
+ </li>
+ </ul>
+ <h4 id="3_2_2_build_parameters">
+ 3.2.2. Build Parameters
+ </h4>
+ <p>
+ The Android APIs include a number of constants on the <a href="http://developer.android.com/reference/android/os/Build.html">android.os.Build class</a> that are intended to describe the current device.
+ </p>
+ <ul>
+ <li>[C-0-1] To provide consistent, meaningful values across device implementations, the table below includes additional restrictions on the formats of these values to which device implementations MUST conform.
+ </li>
+ </ul>
+ <table>
+ <tr>
+ <th>
+ Parameter
+ </th>
+ <th>
+ Details
+ </th>
+ </tr>
+ <tr>
+ <td>
+ VERSION.RELEASE
+ </td>
+ <td>
+ The version of the currently-executing Android system, in human-readable format. This field MUST have one of the string values defined in <a href="http://source.android.com/compatibility/9/versions.html">9</a>.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ VERSION.SDK
+ </td>
+ <td>
+ The version of the currently-executing Android system, in a format accessible to third-party application code. For Android 9, this field MUST have the integer value 9_INT.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ VERSION.SDK_INT
+ </td>
+ <td>
+ The version of the currently-executing Android system, in a format accessible to third-party application code. For Android 9, this field MUST have the integer value 9_INT.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ VERSION.INCREMENTAL
+ </td>
+ <td>
+ A value chosen by the device implementer designating the specific build of the currently-executing Android system, in human-readable format. This value MUST NOT be reused for different builds made available to end users. A typical use of this field is to indicate which build number or source-control change identifier was used to generate the build. There are no requirements on the specific format of this field, except that it MUST NOT be null or the empty string ("").
+ </td>
+ </tr>
+ <tr>
+ <td>
+ BOARD
+ </td>
+ <td>
+ A value chosen by the device implementer identifying the specific internal hardware used by the device, in human-readable format. A possible use of this field is to indicate the specific revision of the board powering the device. The value of this field MUST be encodable as 7-bit ASCII and match the regular expression “^[a-zA-Z0-9_-]+$”.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ BRAND
+ </td>
+ <td>
+ A value reflecting the brand name associated with the device as known to the end users. MUST be in human-readable format and SHOULD represent the manufacturer of the device or the company brand under which the device is marketed. The value of this field MUST be encodable as 7-bit ASCII and match the regular expression “^[a-zA-Z0-9_-]+$”.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ SUPPORTED_ABIS
+ </td>
+ <td>
+ The name of the instruction set (CPU type + ABI convention) of native code. See <a href="#3_3_native_api_compatibility">section 3.3. Native API Compatibility</a>.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ SUPPORTED_32_BIT_ABIS
+ </td>
+ <td>
+ The name of the instruction set (CPU type + ABI convention) of native code. See <a href="#3_3_native_api_compatibility">section 3.3. Native API Compatibility</a>.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ SUPPORTED_64_BIT_ABIS
+ </td>
+ <td>
+ The name of the second instruction set (CPU type + ABI convention) of native code. See <a href="#3_3_native_api_compatibility">section 3.3. Native API Compatibility</a>.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ CPU_ABI
+ </td>
+ <td>
+ The name of the instruction set (CPU type + ABI convention) of native code. See <a href="#3_3_native_api_compatibility">section 3.3. Native API Compatibility</a>.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ CPU_ABI2
+ </td>
+ <td>
+ The name of the second instruction set (CPU type + ABI convention) of native code. See <a href="#3_3_native_api_compatibility">section 3.3. Native API Compatibility</a>.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ DEVICE
+ </td>
+ <td>
+ A value chosen by the device implementer containing the development name or code name identifying the configuration of the hardware features and industrial design of the device. The value of this field MUST be encodable as 7-bit ASCII and match the regular expression “^[a-zA-Z0-9_-]+$”. This device name MUST NOT change during the lifetime of the product.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ FINGERPRINT
+ </td>
+ <td>
+ A string that uniquely identifies this build. It SHOULD be reasonably human-readable. It MUST follow this template:
+ <p class="small">
+ $(BRAND)/$(PRODUCT)/<br>
+ $(DEVICE):$(VERSION.RELEASE)/$(ID)/$(VERSION.INCREMENTAL):$(TYPE)/$(TAGS)
+ </p>
+ <p>
+ For example:
+ </p>
+ <p class="small">
+ acme/myproduct/<br>
+ mydevice:9/LMYXX/3359:userdebug/test-keys
+ </p>
+ <p>
+ The fingerprint MUST NOT include whitespace characters. If other fields included in the template above have whitespace characters, they MUST be replaced in the build fingerprint with another character, such as the underscore ("_") character. The value of this field MUST be encodable as 7-bit ASCII.
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ HARDWARE
+ </td>
+ <td>
+ The name of the hardware (from the kernel command line or /proc). It SHOULD be reasonably human-readable. The value of this field MUST be encodable as 7-bit ASCII and match the regular expression “^[a-zA-Z0-9_-]+$”.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ HOST
+ </td>
+ <td>
+ A string that uniquely identifies the host the build was built on, in human-readable format. There are no requirements on the specific format of this field, except that it MUST NOT be null or the empty string ("").
+ </td>
+ </tr>
+ <tr>
+ <td>
+ ID
+ </td>
+ <td>
+ An identifier chosen by the device implementer to refer to a specific release, in human-readable format. This field can be the same as android.os.Build.VERSION.INCREMENTAL, but SHOULD be a value sufficiently meaningful for end users to distinguish between software builds. The value of this field MUST be encodable as 7-bit ASCII and match the regular expression “^[a-zA-Z0-9._-]+$”.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ MANUFACTURER
+ </td>
+ <td>
+ The trade name of the Original Equipment Manufacturer (OEM) of the product. There are no requirements on the specific format of this field, except that it MUST NOT be null or the empty string (""). This field MUST NOT change during the lifetime of the product.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ MODEL
+ </td>
+ <td>
+ A value chosen by the device implementer containing the name of the device as known to the end user. This SHOULD be the same name under which the device is marketed and sold to end users. There are no requirements on the specific format of this field, except that it MUST NOT be null or the empty string (""). This field MUST NOT change during the lifetime of the product.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ PRODUCT
+ </td>
+ <td>
+ A value chosen by the device implementer containing the development name or code name of the specific product (SKU) that MUST be unique within the same brand. MUST be human-readable, but is not necessarily intended for view by end users. The value of this field MUST be encodable as 7-bit ASCII and match the regular expression “^[a-zA-Z0-9_-]+$”. This product name MUST NOT change during the lifetime of the product.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ SERIAL
+ </td>
+ <td>
+ MUST return "UNKNOWN".
+ </td>
+ </tr>
+ <tr>
+ <td>
+ TAGS
+ </td>
+ <td>
+ A comma-separated list of tags chosen by the device implementer that further distinguishes the build. This field MUST have one of the values corresponding to the three typical Android platform signing configurations: release-keys, dev-keys, test-keys.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ TIME
+ </td>
+ <td>
+ A value representing the timestamp of when the build occurred.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ TYPE
+ </td>
+ <td>
+ A value chosen by the device implementer specifying the runtime configuration of the build. This field MUST have one of the values corresponding to the three typical Android runtime configurations: user, userdebug, or eng.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ USER
+ </td>
+ <td>
+ A name or user ID of the user (or automated user) that generated the build. There are no requirements on the specific format of this field, except that it MUST NOT be null or the empty string ("").
+ </td>
+ </tr>
+ <tr>
+ <td>
+ SECURITY_PATCH
+ </td>
+ <td>
+ A value indicating the security patch level of a build. It MUST signify that the build is not in any way vulnerable to any of the issues described up through the designated Android Public Security Bulletin. It MUST be in the format [YYYY-MM-DD], matching a defined string documented in the <a href="source.android.com/security/bulletin">Android Public Security Bulletin</a> or in the <a href="http://source.android.com/security/advisory">Android Security Advisory</a>, for example "2015-11-01".
+ </td>
+ </tr>
+ <tr>
+ <td>
+ BASE_OS
+ </td>
+ <td>
+ A value representing the FINGERPRINT parameter of the build that is otherwise identical to this build except for the patches provided in the Android Public Security Bulletin. It MUST report the correct value and if such a build does not exist, report an empty string ("").
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <a href="https://developer.android.com/reference/android/os/Build.html#BOOTLOADER">BOOTLOADER</a>
+ </td>
+ <td>
+ A value chosen by the device implementer identifying the specific internal bootloader version used in the device, in human-readable format. The value of this field MUST be encodable as 7-bit ASCII and match the regular expression “^[a-zA-Z0-9._-]+$”.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <a href="https://developer.android.com/reference/android/os/Build.html#getRadioVersion()">getRadioVersion()</a>
+ </td>
+ <td>
+ MUST (be or return) a value chosen by the device implementer identifying the specific internal radio/modem version used in the device, in human-readable format. If a device does not have any internal radio/modem it MUST return NULL. The value of this field MUST be encodable as 7-bit ASCII and match the regular expression “^[a-zA-Z0-9._-,]+$”.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <a href="https://developer.android.com/reference/android/os/Build.html#getSerial()">getSerial()</a>
+ </td>
+ <td>
+ MUST (be or return) a hardware serial number, which MUST be available and unique across devices with the same MODEL and MANUFACTURER. The value of this field MUST be encodable as 7-bit ASCII and match the regular expression “^[a-zA-Z0-9._-,]+$”.
+ </td>
+ </tr>
+ </table>
+ <h4 id="3_2_3_intent_compatibility">
+ 3.2.3. Intent Compatibility
+ </h4>
+ <h5 id="3_2_3_1_core_application_intents">
+ 3.2.3.1. Core Application Intents
+ </h5>
+ <p>
+ Android intents allow application components to request functionality from other Android components. The Android upstream project includes a list of applications considered core Android applications, which implements several intent patterns to perform common actions.
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-0-1] Device implementations MUST preload one or more applications or service components with an intent handler, for all the public intent filter patterns defined by the following core android applications in AOSP:
+ </p>
+ <ul>
+ <li>Desk Clock
+ </li>
+ <li>Browser
+ </li>
+ <li>Calendar
+ </li>
+ <li>Contacts
+ </li>
+ <li>Gallery
+ </li>
+ <li>GlobalSearch
+ </li>
+ <li>Launcher
+ </li>
+ <li>Music
+ </li>
+ <li>Settings
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <h5 id="3_2_3_2_intent_resolution">
+ 3.2.3.2. Intent Resolution
+ </h5>
+ <ul>
+ <li>
+ <p>
+ [C-0-1] As Android is an extensible platform, device implementations MUST allow each intent pattern referenced in <a href="#3_2_3_1_core_application_intents">section 3.2.3.1</a> , except for Settings, to be overridden by third-party applications. The upstream Android open source implementation allows this by default.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-2] Dvice implementers MUST NOT attach special privileges to system applications' use of these intent patterns, or prevent third-party applications from binding to and assuming control of these patterns. This prohibition specifically includes but is not limited to disabling the “Chooser” user interface that allows the user to select between multiple applications that all handle the same intent pattern.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-3] Device implementations MUST provide a user interface for users to modify the default activity for intents.
+ </p>
+ </li>
+ <li>
+ <p>
+ However, device implementations MAY provide default activities for specific URI patterns (e.g. http://play.google.com) when the default activity provides a more specific attribute for the data URI. For example, an intent filter pattern specifying the data URI “http://www.android.com” is more specific than the browser's core intent pattern for “http://”.
+ </p>
+ </li>
+ </ul>
+ <p>
+ Android also includes a mechanism for third-party apps to declare an authoritative default <a href="https://developer.android.com/training/app-links">app linking behavior</a> for certain types of web URI intents. When such authoritative declarations are defined in an app's intent filter patterns, device implementations:
+ </p>
+ <ul>
+ <li>[C-0-4] MUST attempt to validate any intent filters by performing the validation steps defined in the <a href="https://developers.google.com/digital-asset-links">Digital Asset Links specification</a> as implemented by the Package Manager in the upstream Android Open Source Project.
+ </li>
+ <li>[C-0-5] MUST attempt validation of the intent filters during the installation of the application and set all successfully validated URI intent filters as default app handlers for their URIs.
+ </li>
+ <li>MAY set specific URI intent filters as default app handlers for their URIs, if they are successfully verified but other candidate URI filters fail verification. If a device implementation does this, it MUST provide the user appropriate per-URI pattern overrides in the settings menu.
+ </li>
+ <li>MUST provide the user with per-app App Links controls in Settings as follows:
+ <ul>
+ <li>[C-0-6] The user MUST be able to override holistically the default app links behavior for an app to be: always open, always ask, or never open, which must apply to all candidate URI intent filters equally.
+ </li>
+ <li>[C-0-7] The user MUST be able to see a list of the candidate URI intent filters.
+ </li>
+ <li>The device implementation MAY provide the user with the ability to override specific candidate URI intent filters that were successfully verified, on a per-intent filter basis.
+ </li>
+ <li>[C-0-8] The device implementation MUST provide users with the ability to view and override specific candidate URI intent filters if the device implementation lets some candidate URI intent filters succeed verification while some others can fail.
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <h5 id="3_2_3_3_intent_namespaces">
+ 3.2.3.3. Intent Namespaces
+ </h5>
+ <ul>
+ <li>[C-0-1] Device implementations MUST NOT include any Android component that honors any new intent or broadcast intent patterns using an ACTION, CATEGORY, or other key string in the android. <em>or com.android.</em> namespace.
+ </li>
+ <li>[C-0-2] Device implementers MUST NOT include any Android components that honor any new intent or broadcast intent patterns using an ACTION, CATEGORY, or other key string in a package space belonging to another organization.
+ </li>
+ <li>[C-0-3] Device implementers MUST NOT alter or extend any of the intent patterns used by the core apps listed in <a href="#3_2_3_1_core_application_intents">section 3.2.3.1</a>.
+ </li>
+ <li>Device implementations MAY include intent patterns using namespaces clearly and obviously associated with their own organization. This prohibition is analogous to that specified for Java language classes in <a href="#3_6_api_namespaces">section 3.6</a>.
+ </li>
+ </ul>
+ <h5 id="3_2_3_4_broadcast_intents">
+ 3.2.3.4. Broadcast Intents
+ </h5>
+ <p>
+ Third-party applications rely on the platform to broadcast certain intents to notify them of changes in the hardware or software environment.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST broadcast the public broadcast intents in response to appropriate system events as described in the SDK documentation. Note that this requirement is not conflicting with section 3.5 as the limitation for background applications are also described in the SDK documentation.
+ </li>
+ </ul>
+ <h5 id="3_2_3_5_default_app_settings">
+ 3.2.3.5. Default App Settings
+ </h5>
+ <p>
+ Android includes settings that provide users an easy way to select their default applications, for example for Home screen or SMS.
+ </p>
+ <p>
+ Where it makes sense, device implementations MUST provide a similar settings menu and be compatible with the intent filter pattern and API methods described in the SDK documentation as below.
+ </p>
+ <p>
+ If device implementations report <code>android.software.home_screen</code>, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST honor the <a href="http://developer.android.com/reference/android/provider/Settings.html#ACTION_HOME_SETTINGS"><code>android.settings.HOME_SETTINGS</code></a> intent to show a default app settings menu for Home Screen.
+ </li>
+ </ul>
+ <p>
+ If device implementations report <code>android.hardware.telephony</code>, they:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-2-1] MUST provide a settings menu that will call the <a href="http://developer.android.com/reference/android/provider/Telephony.Sms.Intents.html#ACTION_CHANGE_DEFAULT"><code>android.provider.Telephony.ACTION_CHANGE_DEFAULT</code></a> intent to show a dialog to change the default SMS application.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-2-2] MUST honor the <a href="https://developer.android.com/reference/android/telecom/TelecomManager.html#ACTION_CHANGE_DEFAULT_DIALER"><code>android.telecom.action.CHANGE_DEFAULT_DIALER</code></a> intent to show a dialog to allow the user to change the default Phone application.
+ </p>
+ <ul>
+ <li>MUST use the user-selected default Phone app's UI for incoming and outgoing calls except for emergency calls, which would use the preloaded Phone app.
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [C-2-3] MUST honor the <a href="https://developer.android.com/reference/android/telecom/TelecomManager.html#ACTION_CHANGE_PHONE_ACCOUNTS">android.telecom.action.CHANGE_PHONE_ACCOUNTS</a> intent to provide user affordance to configure the <a href="https://developer.android.com/reference/android/telecom/ConnectionService.html"><code>ConnectionServices</code></a> associated with the <a href="https://developer.android.com/reference/android/telecom/PhoneAccount.html"><code>PhoneAccounts</code></a>, as well as a default PhoneAccount that the telecommunications service provider will use to place outgoing calls. The AOSP implementation meets this requirement by including a "Calling Accounts option" menu within the "Calls" settings menu.
+ </p>
+ </li>
+ </ul>
+ <p>
+ If device implementations report <code>android.hardware.nfc.hce</code>, they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST honor the <a href="http://developer.android.com/reference/android/provider/Settings.html#ACTION_NFC_PAYMENT_SETTINGS">android.settings.NFC_PAYMENT_SETTINGS</a> intent to show a default app settings menu for Tap and Pay.
+ </li>
+ </ul>
+ <p>
+ If device implementations support the <code>VoiceInteractionService</code> and have more than one application using this API installed at a time, they:
+ </p>
+ <ul>
+ <li>[C-4-1] MUST honor the <a href="https://developer.android.com/reference/android/provider/Settings.html#ACTION_VOICE_INPUT_SETTINGS"><code>android.settings.ACTION_VOICE_INPUT_SETTINGS</code></a> intent to show a default app settings menu for voice input and assist.
+ </li>
+ </ul>
+ <h4 id="3_2_4_activities_on_secondary_displays">
+ 3.2.4. Activities on secondary displays
+ </h4>
+ <p>
+ If device implementations allow launching normal <a href="https://developer.android.com/reference/android/app/Activity.html">Android Activities</a> on secondary displays, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST set the <code>android.software.activities_on_secondary_displays</code> feature flag.
+ </li>
+ <li>[C-1-2] MUST guarantee API compatibility similar to an activity running on the primary display.
+ </li>
+ <li>[C-1-3] MUST land the new activity on the same display as the activity that launched it, when the new activity is launched without specifying a target display via the <a href="https://developer.android.com/reference/android/app/ActivityOptions.html#setLaunchDisplayId%28int%29"><code>ActivityOptions.setLaunchDisplayId()</code></a> API.
+ </li>
+ <li>[C-1-4] MUST destroy all activities, when a display with the <a href="http://developer.android.com/reference/android/view/Display.html#FLAG_PRIVATE"><code>Display.FLAG_PRIVATE</code></a> flag is removed.
+ </li>
+ <li>[C-1-5] MUST resize accordingly all activities on a <a href="https://developer.android.com/reference/android/hardware/display/VirtualDisplay.html"><code>VirtualDisplay</code></a> if the display itself is resized.
+ </li>
+ <li>MAY show an IME (input method editor, a user control that enables users to enter text) on the primary display, when a text input field becomes focused on a secondary display.
+ </li>
+ <li>SHOULD implement the input focus on the secondary display independently of the primary display, when touch or key inputs are supported.
+ </li>
+ <li>SHOULD have <a href="https://developer.android.com/reference/android/content/res/Configuration.html"><code>android.content.res.Configuration</code></a> which corresponds to that display in order to be displayed, operate correctly, and maintain compatibility if an activity is launched on secondary display.
+ </li>
+ </ul>
+ <p>
+ If device implementations allow launching normal <a href="https://developer.android.com/reference/android/app/Activity.html">Android Activities</a> on secondary displays and primary and secondary displays have different <a href="https://developer.android.com/reference/android/util/DisplayMetrics.html">android.util.DisplayMetrics</a>:
+ </p>
+ <ul>
+ <li>[C-2-1] Non-resizeable activities (that have <code>resizeableActivity=false</code> in <code>AndroidManifest.xml</code>) and apps targeting API level 23 or lower MUST NOT be allowed on secondary displays.
+ </li>
+ </ul>
+ <p>
+ If device implementations allow launching normal <a href="https://developer.android.com/reference/android/app/Activity.html">Android Activities</a> on secondary displays and a secondary display has the <a href="https://developer.android.com/reference/android/view/Display.html#FLAG_PRIVATE">android.view.Display.FLAG_PRIVATE</a> flag:
+ </p>
+ <ul>
+ <li>[C-3-1] Only the owner of that display, system, and activities that are already on that display MUST be able to launch to it. Everyone can launch to a display that has <a href="https://developer.android.com/reference/android/view/Display.html#FLAG_PUBLIC">android.view.Display.FLAG_PUBLIC</a> flag.
+ </li>
+ </ul>
+ <h3 id="3_3_native_api_compatibility">
+ 3.3. Native API Compatibility
+ </h3>
+ <p>
+ Native code compatibility is challenging. For this reason, device implementers are:
+ </p>
+ <ul>
+ <li>[SR] STRONGLY RECOMMENDED to use the implementations of the libraries listed below from the upstream Android Open Source Project.
+ </li>
+ </ul>
+ <h4 id="3_3_1_application_binary_interfaces">
+ 3.3.1. Application Binary Interfaces
+ </h4>
+ <p>
+ Managed Dalvik bytecode can call into native code provided in the application <code>.apk</code> file as an ELF <code>.so</code> file compiled for the appropriate device hardware architecture. As native code is highly dependent on the underlying processor technology, Android defines a number of Application Binary Interfaces (ABIs) in the Android NDK.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST be compatible with one or more defined ABIs and implement compatibility with the Android NDK.
+ </li>
+ <li>[C-0-2] MUST include support for code running in the managed environment to call into native code, using the standard Java Native Interface (JNI) semantics.
+ </li>
+ <li>[C-0-3] MUST be source-compatible (i.e. header-compatible) and binary-compatible (for the ABI) with each required library in the list below.
+ </li>
+ <li>[C-0-5] MUST accurately report the native Application Binary Interface (ABI) supported by the device, via the <code>android.os.Build.SUPPORTED_ABIS</code>, <code>android.os.Build.SUPPORTED_32_BIT_ABIS</code>, and <code>android.os.Build.SUPPORTED_64_BIT_ABIS</code> parameters, each a comma separated list of ABIs ordered from the most to the least preferred one.
+ </li>
+ <li>
+ <p>
+ [C-0-6] MUST report, via the above parameters, a subset of the following list of ABIs and MUST NOT report any ABI not on the list.
+ </p>
+ <ul>
+ <li>
+ <code>armeabi</code>
+ </li>
+ <li>
+ <code>armeabi-v7a</code>
+ </li>
+ <li>
+ <code>arm64-v8a</code>
+ </li>
+ <li>
+ <code>x86</code>
+ </li>
+ <li>
+ <code>x86-64</code>
+ </li>
+ <li>
+ <p>
+ [C-0-7] MUST make all the following libraries, providing native APIs, available to apps that include native code:
+ </p>
+ </li>
+ <li>
+ <p>
+ libaaudio.so (AAudio native audio support)
+ </p>
+ </li>
+ <li>libandroid.so (native Android activity support)
+ </li>
+ <li>libc (C library)
+ </li>
+ <li>libcamera2ndk.so
+ </li>
+ <li>libdl (dynamic linker)
+ </li>
+ <li>libEGL.so (native OpenGL surface management)
+ </li>
+ <li>libGLESv1_CM.so (OpenGL ES 1.x)
+ </li>
+ <li>libGLESv2.so (OpenGL ES 2.0)
+ </li>
+ <li>libGLESv3.so (OpenGL ES 3.x)
+ </li>
+ <li>libicui18n.so
+ </li>
+ <li>libicuuc.so
+ </li>
+ <li>libjnigraphics.so
+ </li>
+ <li>liblog (Android logging)
+ </li>
+ <li>libmediandk.so (native media APIs support)
+ </li>
+ <li>libm (math library)
+ </li>
+ <li>libneuralnetworks.so (Neural Networks API)
+ </li>
+ <li>libOpenMAXAL.so (OpenMAX AL 1.0.1 support)
+ </li>
+ <li>libOpenSLES.so (OpenSL ES 1.0.1 audio support)
+ </li>
+ <li>libRS.so
+ </li>
+ <li>libstdc++ (Minimal support for C++)
+ </li>
+ <li>libvulkan.so (Vulkan)
+ </li>
+ <li>libz (Zlib compression)
+ </li>
+ <li>JNI interface
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [C-0-8] MUST NOT add or remove the public functions for the native libraries listed above.
+ </p>
+ </li>
+ <li>[C-0-9] MUST list additional non-AOSP libraries exposed directly to third-party apps in <code>/vendor/etc/public.libraries.txt</code>.
+ </li>
+ <li>[C-0-10] MUST NOT expose any other native libraries, implemented and provided in AOSP as system libraries, to third-party apps targeting API level 24 or higher as they are reserved.
+ </li>
+ <li>[C-0-11] MUST export all the OpenGL ES 3.1 and <a href="http://developer.android.com/guide/topics/graphics/opengl.html#aep">Android Extension Pack</a> function symbols, as defined in the NDK, through the <code>libGLESv3.so</code> library. Note that while all the symbols MUST be present, section 7.1.4.1 describes in more detail the requirements for when the full implementation of each corresponding functions are expected.
+ </li>
+ <li>[C-0-12] MUST export function symbols for the core Vulkan 1.0 function symbols, as well as the <code>VK_KHR_surface</code>, <code>VK_KHR_android_surface</code>, <code>VK_KHR_swapchain</code>, <code>VK_KHR_maintenance1</code>, and <code>VK_KHR_get_physical_device_properties2</code> extensions through the <code>libvulkan.so</code> library. Note that while all the symbols MUST be present, section 7.1.4.2 describes in more detail the requirements for when the full implementation of each corresponding functions are expected.
+ </li>
+ <li>SHOULD be built using the source code and header files available in the upstream Android Open Source Project
+ </li>
+ </ul>
+ <p>
+ Note that future releases of Android may introduce support for additional ABIs.
+ </p>
+ <h4 id="3_3_2_32-bit_arm_native_code_compatibility">
+ 3.3.2. 32-bit ARM Native Code Compatibility
+ </h4>
+ <p>
+ If device implementations report the support of the <code>armeabi</code> ABI, they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST also support <code>armeabi-v7a</code> and report its support, as <code>armeabi</code> is only for backwards compatibility with older apps.
+ </li>
+ </ul>
+ <p>
+ If device implementations report the support of the <code>armeabi-v7a</code> ABI, for apps using this ABI, they:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-2-1] MUST include the following lines in <code>/proc/cpuinfo</code>, and SHOULD NOT alter the values on the same device, even when they are read by other ABIs.
+ </p>
+ <ul>
+ <li>
+ <code>Features:</code>, followed by a list of any optional ARMv7 CPU features supported by the device.
+ </li>
+ <li>
+ <code>CPU architecture:</code>, followed by an integer describing the device's highest supported ARM architecture (e.g., "8" for ARMv8 devices).
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [C-2-2] MUST always keep the following operations available, even in the case where the ABI is implemented on an ARMv8 architecture, either through native CPU support or through software emulation:
+ </p>
+ <ul>
+ <li>SWP and SWPB instructions.
+ </li>
+ <li>SETEND instruction.
+ </li>
+ <li>CP15ISB, CP15DSB, and CP15DMB barrier operations.
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [C-2-3] MUST include support for the <a href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0388f/Beijfcja.html">Advanced SIMD</a> (a.k.a. NEON) extension.
+ </p>
+ </li>
+ </ul>
+ <h3 id="3_4_web_compatibility">
+ 3.4. Web Compatibility
+ </h3>
+ <h4 id="3_4_1_webview_compatibility">
+ 3.4.1. WebView Compatibility
+ </h4>
+ <p>
+ If device implementations provide a complete implementation of the <code>android.webkit.Webview</code> API, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST report <code>android.software.webview</code>.
+ </li>
+ <li>[C-1-2] MUST use the <a href="http://www.chromium.org/">Chromium</a> Project build from the upstream Android Open Source Project on the Android 9 branch for the implementation of the <a href="http://developer.android.com/reference/android/webkit/WebView.html"><code>android.webkit.WebView</code></a> API.
+ </li>
+ <li>
+ <p>
+ [C-1-3] The user agent string reported by the WebView MUST be in this format:
+ </p>
+ <p>
+ Mozilla/5.0 (Linux; Android $(VERSION); $(MODEL) Build/$(BUILD); wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 $(CHROMIUM_VER) Mobile Safari/537.36
+ </p>
+ <ul>
+ <li>The value of the $(VERSION) string MUST be the same as the value for android.os.Build.VERSION.RELEASE.
+ </li>
+ <li>The value of the $(MODEL) string MUST be the same as the value for android.os.Build.MODEL.
+ </li>
+ <li>The value of the $(BUILD) string MUST be the same as the value for android.os.Build.ID.
+ </li>
+ <li>The value of the $(CHROMIUM_VER) string MUST be the version of Chromium in the upstream Android Open Source Project.
+ </li>
+ <li>Device implementations MAY omit Mobile in the user agent string.
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ The WebView component SHOULD include support for as many HTML5 features as possible and if it supports the feature SHOULD conform to the <a href="http://html.spec.whatwg.org/multipage/">HTML5 specification</a>.
+ </p>
+ </li>
+ </ul>
+ <h4 id="3_4_2_browser_compatibility">
+ 3.4.2. Browser Compatibility
+ </h4>
+ <p>
+ If device implementations include a standalone Browser application for general web browsing, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support each of these APIs associated with HTML5:
+ <ul>
+ <li>
+ <a href="http://www.w3.org/html/wg/drafts/html/master/browsers.html#offline">application cache/offline operation</a>
+ </li>
+ <li>
+ <a href="http://www.w3.org/html/wg/drafts/html/master/semantics.html#video"><video> tag</a>
+ </li>
+ <li>
+ <a href="http://www.w3.org/TR/geolocation-API/">geolocation</a>
+ </li>
+ </ul>
+ </li>
+ <li>[C-1-2] MUST support the HTML5/W3C <a href="http://www.w3.org/TR/webstorage/">webstorage API</a> and SHOULD support the HTML5/W3C <a href="http://www.w3.org/TR/IndexedDB/">IndexedDB API</a>. Note that as the web development standards bodies are transitioning to favor IndexedDB over webstorage, IndexedDB is expected to become a required component in a future version of Android.
+ </li>
+ <li>MAY ship a custom user agent string in the standalone Browser application.
+ </li>
+ <li>SHOULD implement support for as much of <a href="http://html.spec.whatwg.org/multipage/">HTML5</a> as possible on the standalone Browser application (whether based on the upstream WebKit Browser application or a third-party replacement).
+ </li>
+ </ul>
+ <p>
+ However, If device implementations do not include a standalone Browser application, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST still support the public intent patterns as described in <a href="#3_2_3_1_core_application_intents">section 3.2.3.1</a>.
+ </li>
+ </ul>
+ <h3 id="3_5_api_behavioral_compatibility">
+ 3.5. API Behavioral Compatibility
+ </h3>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-9] MUST ensure that API behavioral compatibility is applied for all installed apps unless they are restricted as described in <a href="#3_5_1-background-restriction">Section 3.5.1</a>.
+ </li>
+ <li>[C-0-10] MUST NOT implement the whitelisting approach that ensures API behavioral compatibility only for apps that are selected by device implementers.
+ </li>
+ </ul>
+ <p>
+ The behaviors of each of the API types (managed, soft, native, and web) must be consistent with the preferred implementation of the upstream <a href="http://source.android.com/">Android Open Source Project</a>. Some specific areas of compatibility are:
+ </p>
+ <ul>
+ <li>[C-0-1] Devices MUST NOT change the behavior or semantics of a standard intent.
+ </li>
+ <li>[C-0-2] Devices MUST NOT alter the lifecycle or lifecycle semantics of a particular type of system component (such as Service, Activity, ContentProvider, etc.).
+ </li>
+ <li>[C-0-3] Devices MUST NOT change the semantics of a standard permission.
+ </li>
+ <li>Devices MUST NOT alter the limitations enforced on background applications. More specifically, for background apps:
+ <ul>
+ <li>[C-0-4] they MUST stop executing callbacks that are registered by the app to receive outputs from the <a href="https://developer.android.com/reference/android/location/GnssMeasurement.html"><code>GnssMeasurement</code></a> and <a href="https://developer.android.com/reference/android/location/GnssNavigationMessage.html"><code>GnssNavigationMessage</code></a>.
+ </li>
+ <li>[C-0-5] they MUST rate-limit the frequency of updates that are provided to the app through the <a href="https://developer.android.com/reference/android/location/LocationManager.html"><code>LocationManager</code></a> API class or the <a href="https://developer.android.com/reference/android/net/wifi/WifiManager.html#startScan%28%29"><code>WifiManager.startScan()</code></a> method.
+ </li>
+ <li>[C-0-6] if the app is targeting API level 25 or higher, they MUST NOT allow to register broadcast receivers for the implicit broadcasts of standard Android intents in the app's manifest, unless the broadcast intent requires a <code>"signature"</code> or <code>"signatureOrSystem"</code> <a href="https://developer.android.com/guide/topics/manifest/permission-element.html#plevel"><code>protectionLevel</code></a> permission or are on the <a href="https://developer.android.com/preview/features/background-broadcasts.html">exemption list</a> .
+ </li>
+ <li>[C-0-7] if the app is targeting API level 25 or higher, they MUST stop the app's background services, just as if the app had called the services'<a href="https://developer.android.com/reference/android/app/Service.html#stopSelf%28%29"><code>stopSelf()</code></a> method, unless the app is placed on a temporary whitelist to handle a task that's visible to the user.
+ </li>
+ <li>[C-0-8] if the app is targeting API level 25 or higher, they MUST release the wakelocks the app holds.
+ </li>
+ </ul>
+ </li>
+ <li>[C-0-9] Devices MUST return the following security providers as the first seven array values from the <a href="https://developer.android.com/reference/java/security/Security.html#getProviders%28%29"><code>Security.getProviders()</code></a> method, in the given order and with the given names (as returned by <a href="https://developer.android.com/reference/java/security/Provider.html#getName%28%29"><code>Provider.getName()</code></a>) and classes, unless the app has modified the list via <a href="https://developer.android.com/reference/java/security/Security.html#insertProviderAt%28java.security.Provider,%2520int%29"><code>insertProviderAt()</code></a> or <a href="https://developer.android.com/reference/java/security/Security.html#removeProvider%28java.lang.String%29"><code>removeProvider()</code></a>. Devices MAY return additional providers after the specified list of providers below.
+ <ol>
+ <li>
+ <strong>AndroidNSSP</strong> - <code>android.security.net.config.NetworkSecurityConfigProvider</code>
+ </li>
+ <li>
+ <strong>AndroidOpenSSL</strong> - <code>com.android.org.conscrypt.OpenSSLProvider</code>
+ </li>
+ <li>
+ <strong>CertPathProvider</strong> - <code>sun.security.provider.CertPathProvider</code>
+ </li>
+ <li>
+ <strong>AndroidKeyStoreBCWorkaround</strong> - <code>android.security.keystore.AndroidKeyStoreBCWorkaroundProvider</code>
+ </li>
+ <li>
+ <strong>BC</strong> - <code>com.android.org.bouncycastle.jce.provider.BouncyCastleProvider</code>
+ </li>
+ <li>
+ <strong>HarmonyJSSE</strong> - <code>com.android.org.conscrypt.JSSEProvider</code>
+ </li>
+ <li>
+ <strong>AndroidKeyStore</strong> - <code>android.security.keystore.AndroidKeyStoreProvider</code>
+ </li>
+ </ol>
+ </li>
+ </ul>
+ <p>
+ The above list is not comprehensive. The Compatibility Test Suite (CTS) tests significant portions of the platform for behavioral compatibility, but not all. It is the responsibility of the implementer to ensure behavioral compatibility with the Android Open Source Project. For this reason, device implementers SHOULD use the source code available via the Android Open Source Project where possible, rather than re-implement significant parts of the system.
+ </p>
+ <h3 id="3_5_1_background_restriction">
+ 3.5.1. Background Restriction
+ </h3>
+ <p>
+ If device implementations implement the app restrictions that are included in AOSP or extend the app restrictions, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST provide user affordance where the user can see the list of restricted apps.
+ </li>
+ <li>[C-1-2] MUST provide user affordance to turn on / off the restrictions on each app.
+ </li>
+ <li>[C-1-3] MUST not automatically apply restrictions without evidence of poor system health behaviour, but MAY apply the restrictions on apps upon detection of poor system health behaviour like stuck wakelocks, long running services, and other criteria. The criteria MAY be determined by device implementers but MUST be related to the app’s impact on the system health. Other criteria that is not purely related to the system health, such as the app’s lack of popularity in the market, MUST NOT be used as criteria.
+ </li>
+ <li>[C-1-4] MUST not automatically apply app restrictions for apps when a user has turned off app restrictions manually, and MAY suggest the user to apply app restrictions.
+ </li>
+ <li>[C-1-5] MUST inform users if app restrictions are applied to an app automatically.
+ </li>
+ <li>[C-1-6] MUST return <code>true</code> for <a href="https://developer.android.com/reference/android/app/ActivityManager.html#isBackgroundRestricted%28%29"><code>ActivityManager.isBackgroundRestricted()</code></a> when the restricted app calls this API.
+ </li>
+ <li>[C-1-7] MUST NOT restrict the top foreground app that is explicitly used by the user.
+ </li>
+ <li>[C-1-8] MUST suspend restrictions on an app that becomes the top foreground application when the user explicitly starts to use the app that used to be restricted.
+ </li>
+ <li>[C-1-9] MUST report all app restriction events via <a href="https://developer.android.com/reference/android/app/usage/UsageStats"><code>UsageStats</code></a>. If device implementations extend the app restrictions that are implemented in AOSP, MUST follow the implementation described in <a href="https://souce.android.com/devices/tech/power/app_mgmt.html">this document</a>.
+ </li>
+ </ul>
+ <h3 id="3_6_api_namespaces">
+ 3.6. API Namespaces
+ </h3>
+ <p>
+ Android follows the package and class namespace conventions defined by the Java programming language. To ensure compatibility with third-party applications, device implementers MUST NOT make any prohibited modifications (see below) to these package namespaces:
+ </p>
+ <ul>
+ <li>
+ <code>java.*</code>
+ </li>
+ <li>
+ <code>javax.*</code>
+ </li>
+ <li>
+ <code>sun.*</code>
+ </li>
+ <li>
+ <code>android.*</code>
+ </li>
+ <li>
+ <code>androidx.*</code>
+ </li>
+ <li>
+ <code>com.android.*</code>
+ </li>
+ </ul>
+ <p>
+ That is, they:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST NOT modify the publicly exposed APIs on the Android platform by changing any method or class signatures, or by removing classes or class fields.
+ </li>
+ <li>[C-0-2] MUST NOT add any publicly exposed elements (such as classes or interfaces, or fields or methods to existing classes or interfaces) or Test or System APIs to the APIs in the above namespaces. A “publicly exposed element” is any construct that is not decorated with the “@hide” marker as used in the upstream Android source code.
+ </li>
+ </ul>
+ <p>
+ Device implementers MAY modify the underlying implementation of the APIs, but such modifications:
+ </p>
+ <ul>
+ <li>[C-0-3] MUST NOT impact the stated behavior and Java-language signature of any publicly exposed APIs.
+ </li>
+ <li>[C-0-4] MUST NOT be advertised or otherwise exposed to developers.
+ </li>
+ </ul>
+ <p>
+ However, device implementers MAY add custom APIs outside the standard Android namespace, but the custom APIs:
+ </p>
+ <ul>
+ <li>[C-0-5] MUST NOT be in a namespace owned by or referring to another organization. For instance, device implementers MUST NOT add APIs to the <code>com.google.*</code> or similar namespace: only Google may do so. Similarly, Google MUST NOT add APIs to other companies' namespaces.
+ </li>
+ <li>[C-0-6] MUST be packaged in an Android shared library so that only apps that explicitly use them (via the <uses-library> mechanism) are affected by the increased memory usage of such APIs.
+ </li>
+ </ul>
+ <p>
+ If a device implementer proposes to improve one of the package namespaces above (such as by adding useful new functionality to an existing API, or adding a new API), the implementer SHOULD visit <a href="http://source.android.com/">source.android.com</a> and begin the process for contributing changes and code, according to the information on that site.
+ </p>
+ <p>
+ Note that the restrictions above correspond to standard conventions for naming APIs in the Java programming language; this section simply aims to reinforce those conventions and make them binding through inclusion in this Compatibility Definition.
+ </p>
+ <h3 id="3_7_runtime_compatibility">
+ 3.7. Runtime Compatibility
+ </h3>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-0-1] MUST support the full Dalvik Executable (DEX) format and <a href="https://android.googlesource.com/platform/dalvik/">Dalvik bytecode specification and semantics</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-2] MUST configure Dalvik runtimes to allocate memory in accordance with the upstream Android platform, and as specified by the following table. (See <a href="#7_1_1_screen_configuration">section 7.1.1</a> for screen size and screen density definitions.)
+ </p>
+ </li>
+ <li>
+ <p>
+ SHOULD use Android RunTime (ART), the reference upstream implementation of the Dalvik Executable Format, and the reference implementation’s package management system.
+ </p>
+ </li>
+ <li>
+ <p>
+ SHOULD run fuzz tests under various modes of execution and target architectures to assure the stability of the runtime. Refer to <a href="https://android.googlesource.com/platform/art/+/master/tools/dexfuzz/">JFuzz</a> and <a href="https://android.googlesource.com/platform/art/+/master/tools/dexfuzz/">DexFuzz</a> in the Android Open Source Project website.
+ </p>
+ </li>
+ </ul>
+ <p>
+ Note that memory values specified below are considered minimum values and device implementations MAY allocate more memory per application.
+ </p>
+ <table>
+ <tr>
+ <th>
+ Screen Layout
+ </th>
+ <th>
+ Screen Density
+ </th>
+ <th>
+ Minimum Application Memory
+ </th>
+ </tr>
+ <tr>
+ <td rowspan="12">
+ Android Watch
+ </td>
+ <td>
+ 120 dpi (ldpi)
+ </td>
+ <td rowspan="3">
+ 32MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 160 dpi (mdpi)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 213 dpi (tvdpi)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 240 dpi (hdpi)
+ </td>
+ <td rowspan="2">
+ 36MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 280 dpi (280dpi)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 320 dpi (xhdpi)
+ </td>
+ <td rowspan="2">
+ 48MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 360 dpi (360dpi)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 400 dpi (400dpi)
+ </td>
+ <td>
+ 56MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 420 dpi (420dpi)
+ </td>
+ <td>
+ 64MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 480 dpi (xxhdpi)
+ </td>
+ <td>
+ 88MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 560 dpi (560dpi)
+ </td>
+ <td>
+ 112MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 640 dpi (xxxhdpi)
+ </td>
+ <td>
+ 154MB
+ </td>
+ </tr>
+ <tr>
+ <td rowspan="12">
+ small/normal
+ </td>
+ <td>
+ 120 dpi (ldpi)
+ </td>
+ <td rowspan="2">
+ 32MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 160 dpi (mdpi)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 213 dpi (tvdpi)
+ </td>
+ <td rowspan="3">
+ 48MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 240 dpi (hdpi)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 280 dpi (280dpi)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 320 dpi (xhdpi)
+ </td>
+ <td rowspan="2">
+ 80MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 360 dpi (360dpi)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 400 dpi (400dpi)
+ </td>
+ <td>
+ 96MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 420 dpi (420dpi)
+ </td>
+ <td>
+ 112MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 480 dpi (xxhdpi)
+ </td>
+ <td>
+ 128MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 560 dpi (560dpi)
+ </td>
+ <td>
+ 192MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 640 dpi (xxxhdpi)
+ </td>
+ <td>
+ 256MB
+ </td>
+ </tr>
+ <tr>
+ <td rowspan="12">
+ large
+ </td>
+ <td>
+ 120 dpi (ldpi)
+ </td>
+ <td>
+ 32MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 160 dpi (mdpi)
+ </td>
+ <td>
+ 48MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 213 dpi (tvdpi)
+ </td>
+ <td rowspan="2">
+ 80MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 240 dpi (hdpi)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 280 dpi (280dpi)
+ </td>
+ <td>
+ 96MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 320 dpi (xhdpi)
+ </td>
+ <td>
+ 128MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 360 dpi (360dpi)
+ </td>
+ <td>
+ 160MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 400 dpi (400dpi)
+ </td>
+ <td>
+ 192MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 420 dpi (420dpi)
+ </td>
+ <td>
+ 228MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 480 dpi (xxhdpi)
+ </td>
+ <td>
+ 256MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 560 dpi (560dpi)
+ </td>
+ <td>
+ 384MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 640 dpi (xxxhdpi)
+ </td>
+ <td>
+ 512MB
+ </td>
+ </tr>
+ <tr>
+ <td rowspan="12">
+ xlarge
+ </td>
+ <td>
+ 120 dpi (ldpi)
+ </td>
+ <td>
+ 48MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 160 dpi (mdpi)
+ </td>
+ <td>
+ 80MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 213 dpi (tvdpi)
+ </td>
+ <td rowspan="2">
+ 96MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 240 dpi (hdpi)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 280 dpi (280dpi)
+ </td>
+ <td>
+ 144MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 320 dpi (xhdpi)
+ </td>
+ <td>
+ 192MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 360 dpi (360dpi)
+ </td>
+ <td>
+ 240MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 400 dpi (400dpi)
+ </td>
+ <td>
+ 288MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 420 dpi (420dpi)
+ </td>
+ <td>
+ 336MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 480 dpi (xxhdpi)
+ </td>
+ <td>
+ 384MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 560 dpi (560dpi)
+ </td>
+ <td>
+ 576MB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ 640 dpi (xxxhdpi)
+ </td>
+ <td>
+ 768MB
+ </td>
+ </tr>
+ </table>
+ <h3 id="3_8_user_interface_compatibility">
+ 3.8. User Interface Compatibility
+ </h3>
+ <h4 id="3_8_1_launcher_(home_screen)">
+ 3.8.1. Launcher (Home Screen)
+ </h4>
+ <p>
+ Android includes a launcher application (home screen) and support for third-party applications to replace the device launcher (home screen).
+ </p>
+ <p>
+ If device implementations allow third-party applications to replace the device home screen, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST declare the platform feature <code>android.software.home_screen</code>.
+ </li>
+ <li>[C-1-2] MUST return the <a href="https://developer.android.com/reference/android/graphics/drawable/AdaptiveIconDrawable.html"><code>AdaptiveIconDrawable</code></a> object when the third party application use <code><adaptive-icon></code> tag to provide their icon, and the <a href="https://developer.android.com/reference/android/content/pm/PackageManager.html"><code>PackageManager</code></a> methods to retrieve icons are called.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a default launcher that supports in-app pinning of shortcuts, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST report <code>true</code> for <a href="https://developer.android.com/reference/android/content/pm/ShortcutManager.html#isRequestPinShortcutSupported%28%29"><code>ShortcutManager.isRequestPinShortcutSupported()</code></a>.
+ </li>
+ <li>[C-2-2] MUST have user affordance asking the user before adding a shortcut requested by apps via the <a href="https://developer.android.com/reference/android/content/pm/ShortcutManager.html#requestPinShortcut%28android.content.pm.ShortcutInfo,%20android.content.IntentSender%29"><code>ShortcutManager.requestPinShortcut()</code></a> API method.
+ </li>
+ <li>[C-2-3] MUST support pinned shortcuts and dynamic and static shortcuts as documented on the <a href="https://developer.android.com/guide/topics/ui/shortcuts.html">App Shortcuts page</a>.
+ </li>
+ </ul>
+ <p>
+ Conversely, if device implementations do not support in-app pinning of shortcuts, they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST report <code>false</code> for <a href="https://developer.android.com/reference/android/content/pm/ShortcutManager.html#isRequestPinShortcutSupported%28%29"><code>ShortcutManager.isRequestPinShortcutSupported()</code></a>.
+ </li>
+ </ul>
+ <p>
+ If device implementations implement a default launcher that provides quick access to the additional shortcuts provided by third-party apps through the <a href="https://developer.android.com/reference/android/content/pm/ShortcutManager.html">ShortcutManager</a> API, they:
+ </p>
+ <ul>
+ <li>[C-4-1] MUST support all documented shortcut features (e.g. static and dynamic shortcuts, pinning shortcuts) and fully implement the APIs of the <a href="https://developer.android.com/reference/android/content/pm/ShortcutManager.html"><code>ShortcutManager</code></a> API class.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a default launcher app that shows badges for the app icons, they:
+ </p>
+ <ul>
+ <li>[C-5-1] MUST respect the <a href="https://developer.android.com/reference/android/app/NotificationChannel.html#setShowBadge%28boolean%29"><code>NotificationChannel.setShowBadge()</code></a> API method. In other words, show a visual affordance associated with the app icon if the value is set as <code>true</code>, and do not show any app icon badging scheme when all of the app's notification channels have set the value as <code>false</code>.
+ </li>
+ <li>MAY override the app icon badges with their proprietary badging scheme when third-party applications indicate support of the proprietary badging scheme through the use of proprietary APIs, but SHOULD use the resources and values provided through the notification badges APIs described in <a href="https://developer.android.com/preview/features/notification-badges.html">the SDK</a> , such as the <a href="http://developer.android.com/reference/android/app/Notification.Builder.html#setNumber%28int%29"><code>Notification.Builder.setNumber()</code></a> and the <a href="http://developer.android.com/reference/android/app/Notification.Builder.html#setBadgeIconType%28int%29"><code>Notification.Builder.setBadgeIconType()</code></a> API.
+ </li>
+ </ul>
+ <h4 id="3_8_2_widgets">
+ 3.8.2. Widgets
+ </h4>
+ <p>
+ Android supports third-party app widgets by defining a component type and corresponding API and lifecycle that allows applications to expose an <a href="http://developer.android.com/guide/practices/ui_guidelines/widget_design.html">“AppWidget”</a> to the end user.
+ </p>
+ <p>
+ If device implementations support third-party app widgets, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST declare support for platform feature <code>android.software.app_widgets</code>.
+ </li>
+ <li>[C-1-2] MUST include built-in support for AppWidgets and expose user interface affordances to add, configure, view, and remove AppWidgets directly within the Launcher.
+ </li>
+ <li>[C-1-3] MUST be capable of rendering widgets that are 4 x 4 in the standard grid size. See the <a href="http://developer.android.com/guide/practices/ui_guidelines/widget_design.html">App Widget DesignGuidelines</a> in the Android SDK documentation for details.
+ </li>
+ <li>MAY support application widgets on the lock screen.
+ </li>
+ </ul>
+ <p>
+ If device implementations support third-party app widgets and in-app pinning of shortcuts, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST report <code>true</code> for <a href="https://developer.android.com/reference/android/appwidget/AppWidgetManager.html#isRequestPinAppWidgetSupported%28%29"><code>AppWidgetManager.html.isRequestPinAppWidgetSupported()</code></a>.
+ </li>
+ <li>[C-2-2] MUST have user affordance asking the user before adding a shortcut requested by apps via the <a href="https://developer.android.com/reference/android/appwidget/AppWidgetManager.html#requestPinAppWidget%28android.content.ComponentName,android.os.Bundle,%20android.app.PendingIntent%29"><code>AppWidgetManager.requestPinAppWidget()</code></a> API method.
+ </li>
+ </ul>
+ <h4 id="3_8_3_notifications">
+ 3.8.3. Notifications
+ </h4>
+ <p>
+ Android includes <a href="https://developer.android.com/reference/android/app/Notification.html"><code>Notification</code></a> and <a href="https://developer.android.com/reference/android/app/NotificationManager.html"><code>NotificationManager</code></a> APIs that allow third-party app developers to notify users of notable events and attract users' attention using the hardware components (e.g. sound, vibration and light) and software features (e.g. notification shade, system bar) of the device.
+ </p>
+ <h5 id="3_8_3_1_presentation_of_notifications">
+ 3.8.3.1. Presentation of Notifications
+ </h5>
+ <p>
+ If device implementations allow third party apps to <a href="http://developer.android.com/guide/topics/ui/notifiers/notifications.html">notify users of notable events</a>, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support notifications that use hardware features, as described in the SDK documentation, and to the extent possible with the device implementation hardware. For instance, if a device implementation includes a vibrator, it MUST correctly implement the vibration APIs. If a device implementation lacks hardware, the corresponding APIs MUST be implemented as no-ops. This behavior is further detailed in <a href="#7_hardware_compatibility">section 7</a>.
+ </li>
+ <li>[C-1-2] MUST correctly render all <a href="https://developer.android.com/guide/topics/resources/available-resources.html">resources</a> (icons, animation files, etc.) provided for in the APIs, or in the Status/System Bar <a href="http://developer.android.com/design/style/iconography.html">icon style guide</a>, although they MAY provide an alternative user experience for notifications than that provided by the reference Android Open Source implementation.
+ </li>
+ <li>[C-1-3] MUST honor and implement properly the behaviors described for <a href="https://developer.android.com/guide/topics/ui/notifiers/notifications.html#Managing">the APIs</a> to update, remove and group notifications.
+ </li>
+ <li>[C-1-4] MUST provide the full behavior of the <a href="https://developer.android.com/reference/android/app/NotificationChannel.html">NotificationChannel</a> API documented in the SDK.
+ </li>
+ <li>[C-1-5] MUST provide a user affordance to block and modify a certain third-party app's notification per each channel and app package level.
+ </li>
+ <li>[C-1-6] MUST also provide a user affordance to display deleted notification channels.
+ </li>
+ <li>[C-1-7] MUST correctly render all resources (images, stickers, icons, etc.) provided through <a href="https://developer.android.com/reference/android/app/Notification.MessagingStyle">Notification.MessagingStyle</a> alongside the notification text without additional user interaction. For example, MUST show all resources including icons provided through <a href="https://developer.android.com/reference/android/app/Person">android.app.Person</a> in a group conversation that is set through <a href="https://developer.android.com/reference/android/app/Notification.MessagingStyle.html?hl=es-AR#setGroupConversation%28boolean%29">setGroupConversation</a>.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to automatically surface a user affordance to block a certain third-party app's notification per each channel and app package level after the user dismisses that notification multiple times.
+ </li>
+ <li>SHOULD support rich notifications.
+ </li>
+ <li>SHOULD present some higher priority notifications as heads-up notifications.
+ </li>
+ <li>SHOULD have a user affordance to snooze notifications.
+ </li>
+ <li>MAY only manage the visibility and timing of when third-party apps can notify users of notable events to mitigate safety issues such as driver distraction.
+ </li>
+ </ul>
+ <p>
+ If device implementations support rich notifications, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST use the exact resources as provided through the <a href="https://developer.android.com/reference/android/app/Notification.Style.html"><code>Notification.Style</code></a> API class and its subclasses for the presented resource elements.
+ </li>
+ <li>SHOULD present each and every resource element (e.g. icon, title and summary text) defined in the <a href="https://developer.android.com/reference/android/app/Notification.Style.html"><code>Notification.Style</code></a> API class and its subclasses.
+ </li>
+ </ul>
+ <p>
+ If device implementation support heads-up notifications: they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST use the heads-up notification view and resources as described in the <a href="https://developer.android.com/reference/android/app/Notification.Builder.html"><code>Notification.Builder</code></a> API class when heads-up notifications are presented.
+ </li>
+ <li>[C-3-2] MUST display the actions provided through <a href="https://developer.android.com/reference/android/app/Notification.Builder#addAction%28android.app.Notification.Action%29"><code>Notification.Builder.addAction()</code></a> together with the notification content without additional user interaction as described in <a href="https://developer.android.com/guide/topics/ui/notifiers/notifications.html#Heads-up">the SDK</a>.
+ </li>
+ </ul>
+ <h5 id="3_8_3_2_notification_listener_service">
+ 3.8.3.2. Notification Listener Service
+ </h5>
+ <p>
+ Android includes the <a href="https://developer.android.com/reference/android/service/notification/NotificationListenerService.html"><code>NotificationListenerService</code></a> APIs that allow apps (once explicitly enabled by the user) to receive a copy of all notifications as they are posted or updated.
+ </p>
+ <p>
+ If device implementations report the feature flag <a href="https://developer.android.com/reference/android/content/pm/PackageManager.html#FEATURE_RAM_NORMAL"><code>android.hardware.ram.normal</code></a>, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST correctly and promptly update notifications in their entirety to all such installed and user-enabled listener services, including any and all metadata attached to the Notification object.
+ </li>
+ <li>[C-1-2] MUST respect the <a href="https://developer.android.com/reference/android/service/notification/NotificationListenerService.html#snoozeNotification%28java.lang.String,%20long%29"><code>snoozeNotification()</code></a> API call, and dismiss the notification and make a callback after the snooze duration that is set in the API call.
+ </li>
+ </ul>
+ <p>
+ If device implementations have a user affordance to snooze notifications, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST reflect the snoozed notification status properly through the standard APIs such as <a href="https://developer.android.com/reference/android/service/notification/NotificationListenerService.html#getSnoozedNotifications%28%29"><code>NotificationListenerService.getSnoozedNotifications()</code></a>.
+ </li>
+ <li>[C-2-2] MUST make this user affordance available to snooze notifications from each installed third-party app's, unless they are from persistent/foreground services.
+ </li>
+ </ul>
+ <h5 id="3_8_3_3_dnd_(do_not_disturb)">
+ 3.8.3.3. DND (Do not Disturb)
+ </h5>
+ <p>
+ If device implementations support the DND feature, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST implement an activity that would respond to the intent <a href="https://developer.android.com/reference/android/provider/Settings.html#ACTION_NOTIFICATION_POLICY_ACCESS_SETTINGS">ACTION_NOTIFICATION_POLICY_ACCESS_SETTINGS</a>, which for implementations with UI_MODE_TYPE_NORMAL it MUST be an activity where the user can grant or deny the app access to DND policy configurations.
+ </li>
+ <li>[C-1-2] MUST, for when the device implementation has provided a means for the user to grant or deny third-party apps to access the DND policy configuration, display <a href="https://developer.android.com/reference/android/app/NotificationManager.html#addAutomaticZenRule%28android.app.AutomaticZenRule%29">Automatic DND rules</a> created by applications alongside the user-created and pre-defined rules.
+ </li>
+ <li>[C-1-3] MUST honor the <a href="https://developer.android.com/reference/android/app/NotificationManager.Policy.html#suppressedVisualEffects"><code>suppressedVisualEffects</code></a> values passed along the <a href="https://developer.android.com/reference/android/app/NotificationManager.Policy.html#NotificationManager.Policy%28int,%20int,%20int,%20int%29"><code>NotificationManager.Policy</code></a> and if an app has set any of the SUPPRESSED_EFFECT_SCREEN_OFF or SUPPRESSED_EFFECT_SCREEN_ON flags, it SHOULD indicate to the user that the visual effects are suppressed in the DND settings menu.
+ </li>
+ </ul>
+ <h4 id="3_8_4_search">
+ 3.8.4. Search
+ </h4>
+ <p>
+ Android includes APIs that allow developers to <a href="http://developer.android.com/reference/android/app/SearchManager.html">incorporate search</a> into their applications and expose their application’s data into the global system search. Generally speaking, this functionality consists of a single, system-wide user interface that allows users to enter queries, displays suggestions as users type, and displays results. The Android APIs allow developers to reuse this interface to provide search within their own apps and allow developers to supply results to the common global search user interface.
+ </p>
+ <ul>
+ <li>Android device implementations SHOULD include global search, a single, shared, system-wide search user interface capable of real-time suggestions in response to user input.
+ </li>
+ </ul>
+ <p>
+ If device implementations implement the global search interface, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST implement the APIs that allow third-party applications to add suggestions to the search box when it is run in global search mode.
+ </li>
+ </ul>
+ <p>
+ If no third-party applications are installed that make use of the global search:
+ </p>
+ <ul>
+ <li>The default behavior SHOULD be to display web search engine results and suggestions.
+ </li>
+ </ul>
+ <p>
+ Android also includes the <a href="https://developer.android.com/reference/android/app/assist/package-summary.html">Assist APIs</a> to allow applications to elect how much information of the current context is shared with the assistant on the device.
+ </p>
+ <p>
+ If device implementations support the Assist action, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST indicate clearly to the end user when the context is shared, by either:
+ <ul>
+ <li>Each time the assist app accesses the context, displaying a white light around the edges of the screen that meet or exceed the duration and brightness of the Android Open Source Project implementation.
+ </li>
+ <li>For the preinstalled assist app, providing a user affordance less than two navigations away from <a href="#3_2_3_5_default_app_settings">the default voice input and assistant app settings menu</a>, and only sharing the context when the assist app is explicitly invoked by the user through a hotword or assist navigation key input.
+ </li>
+ </ul>
+ </li>
+ <li>[C-2-2] The designated interaction to launch the assist app as described in <a href="#7_2_3_navigation_keys">section 7.2.3</a> MUST launch the user-selected assist app, in other words the app that implements <code>VoiceInteractionService</code>, or an activity handling the <code>ACTION_ASSIST</code> intent.
+ </li>
+ </ul>
+ <h4 id="3_8_5_alerts_and_toasts">
+ 3.8.5. Alerts and Toasts
+ </h4>
+ <p>
+ Applications can use the <a href="http://developer.android.com/reference/android/widget/Toast.html"><code>Toast</code></a> API to display short non-modal strings to the end user that disappear after a brief period of time, and use the <a href="http://developer.android.com/reference/android/view/WindowManager.LayoutParams.html#TYPE_APPLICATION_OVERLAY"><code>TYPE_APPLICATION_OVERLAY</code></a> window type API to display alert windows as an overlay over other apps.
+ </p>
+ <p>
+ If device implementations include a screen or video output, they:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-1-1] MUST provide a user affordance to block an app from displaying alert windows that use the <a href="http://developer.android.com/reference/android/view/WindowManager.LayoutParams.html#TYPE_APPLICATION_OVERLAY"><code>TYPE_APPLICATION_OVERLAY</code></a> . The AOSP implementation meets this requirement by having controls in the notification shade.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-2] MUST honor the Toast API and display Toasts from applications to end users in some highly visible manner.
+ </p>
+ </li>
+ </ul>
+ <h4 id="3_8_6_themes">
+ 3.8.6. Themes
+ </h4>
+ <p>
+ Android provides “themes” as a mechanism for applications to apply styles across an entire Activity or application.
+ </p>
+ <p>
+ Android includes a “Holo” and "Material" theme family as a set of defined styles for application developers to use if they want to match the <a href="http://developer.android.com/guide/topics/ui/themes.html">Holo theme look and feel</a> as defined by the Android SDK.
+ </p>
+ <p>
+ If device implementations include a screen or video output, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST NOT alter any of the <a href="http://developer.android.com/reference/android/R.style.html">Holo theme attributes</a> exposed to applications.
+ </li>
+ <li>[C-1-2] MUST support the “Material” theme family and MUST NOT alter any of the <a href="http://developer.android.com/reference/android/R.style.html#Theme_Material">Material theme attributes</a> or their assets exposed to applications.
+ </li>
+ </ul>
+ <p>
+ Android also includes a “Device Default” theme family as a set of defined styles for application developers to use if they want to match the look and feel of the device theme as defined by the device implementer.
+ </p>
+ <ul>
+ <li>Device implementations MAY modify the <a href="http://developer.android.com/reference/android/R.style.html">Device Default theme attributes</a> exposed to applications.
+ </li>
+ </ul>
+ <p>
+ Android supports a variant theme with translucent system bars, which allows application developers to fill the area behind the status and navigation bar with their app content. To enable a consistent developer experience in this configuration, it is important the status bar icon style is maintained across different device implementations.
+ </p>
+ <p>
+ If device implementations include a system status bar, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST use white for system status icons (such as signal strength and battery level) and notifications issued by the system, unless the icon is indicating a problematic status or an app requests a light status bar using the SYSTEM_UI_FLAG_LIGHT_STATUS_BAR flag.
+ </li>
+ <li>[C-2-2] Android device implementations MUST change the color of the system status icons to black (for details, refer to <a href="http://developer.android.com/reference/android/R.style.html">R.style</a>) when an app requests a light status bar.
+ </li>
+ </ul>
+ <h4 id="3_8_7_live_wallpapers">
+ 3.8.7. Live Wallpapers
+ </h4>
+ <p>
+ Android defines a component type and corresponding API and lifecycle that allows applications to expose one or more <a href="http://developer.android.com/reference/android/service/wallpaper/WallpaperService.html">“Live Wallpapers”</a> to the end user. Live wallpapers are animations, patterns, or similar images with limited input capabilities that display as a wallpaper, behind other applications.
+ </p>
+ <p>
+ Hardware is considered capable of reliably running live wallpapers if it can run all live wallpapers, with no limitations on functionality, at a reasonable frame rate with no adverse effects on other applications. If limitations in the hardware cause wallpapers and/or applications to crash, malfunction, consume excessive CPU or battery power, or run at unacceptably low frame rates, the hardware is considered incapable of running live wallpaper. As an example, some live wallpapers may use an OpenGL 2.0 or 3.x context to render their content. Live wallpaper will not run reliably on hardware that does not support multiple OpenGL contexts because the live wallpaper use of an OpenGL context may conflict with other applications that also use an OpenGL context.
+ </p>
+ <ul>
+ <li>Device implementations capable of running live wallpapers reliably as described above SHOULD implement live wallpapers.
+ </li>
+ </ul>
+ <p>
+ If device implementations implement live wallpapers, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST report the platform feature flag android.software.live_wallpaper.
+ </li>
+ </ul>
+ <h4 id="3_8_8_activity_switching">
+ 3.8.8. Activity Switching
+ </h4>
+ <p>
+ The upstream Android source code includes the <a href="https://developer.android.com/guide/components/activities/recents.html">overview screen</a>, a system-level user interface for task switching and displaying recently accessed activities and tasks using a thumbnail image of the application’s graphical state at the moment the user last left the application.
+ </p>
+ <p>
+ Device implementations including the recents function navigation key as detailed in <a href="#7_2_3_navigation_keys">section 7.2.3</a> MAY alter the interface.
+ </p>
+ <p>
+ If device implementations including the recents function navigation key as detailed in <a href="#7_2_3_navigation_keys">section 7.2.3</a> alter the interface, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support at least up to 7 displayed activities.
+ </li>
+ <li>SHOULD at least display the title of 4 activities at a time.
+ </li>
+ <li>[C-1-2] MUST implement the <a href="http://developer.android.com/about/versions/android-5.0.html#ScreenPinning">screen pinning behavior</a> and provide the user with a settings menu to toggle the feature.
+ </li>
+ <li>SHOULD display highlight color, icon, screen title in recents.
+ </li>
+ <li>SHOULD display a closing affordance ("x") but MAY delay this until user interacts with screens.
+ </li>
+ <li>SHOULD implement a shortcut to switch easily to the previous activity.
+ </li>
+ <li>SHOULD trigger the fast-switch action between the two most recently used apps, when the recents function key is tapped twice.
+ </li>
+ <li>SHOULD trigger the split-screen multiwindow-mode, if supported, when the recents functions key is long pressed.
+ </li>
+ <li>MAY display affiliated recents as a group that moves together.
+ </li>
+ <li>[SR] Are STRONGLY RECOMMENDED to use the upstream Android user interface (or a similar thumbnail-based interface) for the overview screen.
+ </li>
+ </ul>
+ <h4 id="3_8_9_input_management">
+ 3.8.9. Input Management
+ </h4>
+ <p>
+ Android includes support for <a href="http://developer.android.com/guide/topics/text/creating-input-method.html">Input Management</a> and support for third-party input method editors.
+ </p>
+ <p>
+ If device implementations allow users to use third-party input methods on the device, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST declare the platform feature android.software.input_methods and support IME APIs as defined in the Android SDK documentation.
+ </li>
+ <li>[C-1-2] MUST provide a user-accessible mechanism to add and configure third-party input methods in response to the android.settings.INPUT_METHOD_SETTINGS intent.
+ </li>
+ </ul>
+ <p>
+ If device implementations declare the <a href="https://developer.android.com/reference/android/content/pm/PackageManager.html#FEATURE_AUTOFILL"><code>android.software.autofill</code></a> feature flag, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST fully implement the <a href="https://developer.android.com/reference/android/service/autofill/AutofillService.html"><code>AutofillService</code></a> and <a href="https://developer.android.com/reference/android/view/autofill/AutofillManager.html"><code>AutofillManager</code></a> APIs and honor the <a href="https://developer.android.com/reference/android/provider/Settings.html#ACTION_REQUEST_SET_AUTOFILL_SERVICE"><code>android.settings.REQUEST_SET_AUTOFILL_SERVICE</code></a> intent to show a default app settings menu to enable and disable autofill and change the default autofill service for the user.
+ </li>
+ </ul>
+ <h4 id="3_8_10_lock_screen_media_control">
+ 3.8.10. Lock Screen Media Control
+ </h4>
+ <p>
+ The Remote Control Client API is deprecated from Android 5.0 in favor of the <a href="http://developer.android.com/reference/android/app/Notification.MediaStyle.html">Media Notification Template</a> that allows media applications to integrate with playback controls that are displayed on the lock screen.
+ </p>
+ <h4 id="3_8_11_screen_savers_(previously_dreams)">
+ 3.8.11. Screen savers (previously Dreams)
+ </h4>
+ <p>
+ Android includes support for <a href="http://developer.android.com/reference/android/service/dreams/DreamService.html">interactivescreensavers</a>, previously referred to as Dreams. Screen savers allow users to interact with applications when a device connected to a power source is idle or docked in a desk dock. Android Watch devices MAY implement screen savers, but other types of device implementations SHOULD include support for screen savers and provide a settings option for users to configure screen savers in response to the <code>android.settings.DREAM_SETTINGS</code> intent.
+ </p>
+ <h4 id="3_8_12_location">
+ 3.8.12. Location
+ </h4>
+ <p>
+ If device implementations include a hardware sensor (e.g. GPS) that is capable of providing the location coordinates, they
+ </p>
+ <ul>
+ <li>[C-1-2] MUST display the <a href="https://developer.android.com/reference/android/location/LocationManager.html#isLocationEnabled%28%29">current status of location</a> in the Location menu within Settings.
+ </li>
+ <li>[C-1-3] MUST NOT display <a href="https://developer.android.com/reference/android/provider/Settings.Secure.html#LOCATION_MODE">location modes</a> in the Location menu within Settings.
+ </li>
+ </ul>
+ <h4 id="3_8_13_unicode_and_font">
+ 3.8.13. Unicode and Font
+ </h4>
+ <p>
+ Android includes support for the emoji characters defined in <a href="http://www.unicode.org/versions/Unicode10.0.0/">Unicode 10.0</a>.
+ </p>
+ <p>
+ If device implementations include a screen or video output, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST be capable of rendering these emoji characters in color glyph.
+ </li>
+ <li>[C-1-2] MUST include support for:
+ <ul>
+ <li>Roboto 2 font with different weights—sans-serif-thin, sans-serif-light, sans-serif-medium, sans-serif-black, sans-serif-condensed, sans-serif-condensed-light for the languages available on the device.
+ </li>
+ <li>Full Unicode 7.0 coverage of Latin, Greek, and Cyrillic, including the Latin Extended A, B, C, and D ranges, and all glyphs in the currency symbols block of Unicode 7.0.
+ </li>
+ </ul>
+ </li>
+ <li>SHOULD support the skin tone and diverse family emojis as specified in the <a href="http://unicode.org/reports/tr51">Unicode Technical Report #51</a>.
+ </li>
+ </ul>
+ <p>
+ If device implementations include an IME, they:
+ </p>
+ <ul>
+ <li>SHOULD provide an input method to the user for these emoji characters.
+ </li>
+ </ul>
+ <h4 id="3_8_14_multi-windows">
+ 3.8.14. Multi-windows
+ </h4>
+ <p>
+ If device implementations have the capability to display multiple activities at the same time, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST implement such multi-window mode(s) in accordance with the application behaviors and APIs described in the Android SDK <a href="https://developer.android.com/guide/topics/ui/multi-window.html">multi-window mode support documentation</a> and meet the following requirements:
+ </li>
+ <li>[C-1-2] Applications can indicate whether they are capable of operating in multi-window mode in the <code>AndroidManifest.xml</code> file, either explicitly via setting the <a href="https://developer.android.com/reference/android/R.attr.html#resizeableActivity"><code>android:resizeableActivity</code></a> attribute to <code>true</code> or implicitly by having the targetSdkVersion > 24. Apps that explicitly set this attribute to <code>false</code> in their manifest MUST NOT be launched in multi-window mode. Older apps with targetSdkVersion < 24 that did not set this <code>android:resizeableActivity</code> attribute MAY be launched in multi-window mode, but the system MUST provide warning that the app may not work as expected in multi-window mode.
+ </li>
+ <li>[C-1-3] MUST NOT offer split-screen or freeform mode if the screen height < 440 dp and the screen width < 440 dp.
+ </li>
+ <li>Device implementations with screen size <code>xlarge</code> SHOULD support freeform mode.
+ </li>
+ </ul>
+ <p>
+ If device implementations support multi-window mode(s), and the split screen mode, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST preload a <a href="https://developer.android.com/guide/topics/ui/multi-window.html#configuring">resizeable</a> launcher as the default.
+ </li>
+ <li>[C-2-2] MUST crop the docked activity of a split-screen multi-window but SHOULD show some content of it, if the Launcher app is the focused window.
+ </li>
+ <li>[C-2-3] MUST honor the declared <a href="https://developer.android.com/reference/android/R.styleable.html#AndroidManifestLayout_minWidth"><code>AndroidManifestLayout_minWidth</code></a> and <a href="https://developer.android.com/reference/android/R.styleable.html#AndroidManifestLayout_minHeight"><code>AndroidManifestLayout_minHeight</code></a> values of the third-party launcher application and not override these values in the course of showing some content of the docked activity.
+ </li>
+ </ul>
+ <p>
+ If device implementations support multi-window mode(s) and Picture-in-Picture multi-window mode, they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST launch activities in picture-in-picture multi-window mode when the app is: * Targeting API level 26 or higher and declares <a href="https://developer.android.com/reference/android/R.attr.html#supportsPictureInPicture"><code>android:supportsPictureInPicture</code></a> * Targeting API level 25 or lower and declares both <a href="https://developer.android.com/reference/android/R.attr.html#resizeableActivity"><code>android:resizeableActivity</code></a> and <a href="https://developer.android.com/reference/android/R.attr.html#supportsPictureInPicture"><code>android:supportsPictureInPicture</code></a>.
+ </li>
+ <li>[C-3-2] MUST expose the actions in their SystemUI as specified by the current PIP activity through the <a href="https://developer.android.com/reference/android/app/PictureInPictureParams.Builder.html#setActions%28java.util.List%3Candroid.app.RemoteAction%3E%29"><code>setActions()</code></a> API.
+ </li>
+ <li>[C-3-3] MUST support aspect ratios greater than or equal to 1:2.39 and less than or equal to 2.39:1, as specified by the PIP activity through the <a href="https://developer.android.com/reference/android/app/PictureInPictureParams.Builder.html#setAspectRatio%28android.util.Rational%29"><code>setAspectRatio()</code></a> API.
+ </li>
+ <li>[C-3-4] MUST use <a href="https://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_WINDOW"><code>KeyEvent.KEYCODE_WINDOW</code></a> to control the PIP window; if PIP mode is not implemented, the key MUST be available to the foreground activity.
+ </li>
+ <li>[C-3-5] MUST provide a user affordance to block an app from displaying in PIP mode; the AOSP implementation meets this requirement by having controls in the notification shade.
+ </li>
+ <li>[C-3-6] MUST allocate minimum width and height of 108 dp for the PIP window and minimum width of 240 dp and height of 135 dp for the PIP window when the <code>Configuration.uiMode</code> is configured as <a href="https://developer.android.com/reference/android/content/res/Configuration.html#UI_MODE_TYPE_TELEVISION"><code>UI_MODE_TYPE_TELEVISION</code></a>.
+ </li>
+ </ul>
+ <h4 id="3_8_15_display_cutout">
+ 3.8.15. Display Cutout
+ </h4>
+ <p>
+ Android supports a Display Cutout as described in the SDK document. The <a href="https://developer.android.com/reference/android/view/DisplayCutout"><code>DisplayCutout</code></a> API defines an area on the edge of the display that is not functional for displaying content.
+ </p>
+ <p>
+ If device implementations include display cutout(s), they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST only have cutout(s) on the short edge(s) of the device. Conversely, if the device's aspect ratio is 1.0(1:1), they MUST NOT have cutout(s).
+ </li>
+ <li>[C-1-2] MUST NOT have more than one cutout per edge.
+ </li>
+ <li>[C-1-3] MUST honor the display cutout flags set by the app through the <a href="https://developer.android.com/reference/android/view/WindowManager.LayoutParams"><code>WindowManager.LayoutParams</code></a> API as described in the SDK.
+ </li>
+ <li>[C-1-4] MUST report correct values for all cutout metrics defined in the <a href="https://developer.android.com/reference/android/view/DisplayCutout"><code>DisplayCutout</code></a> API.
+ </li>
+ </ul>
+ <h3 id="3_9_device_administration">
+ 3.9. Device Administration
+ </h3>
+ <p>
+ Android includes features that allow security-aware applications to perform device administration functions at the system level, such as enforcing password policies or performing remote wipe, through the <a href="http://developer.android.com/guide/topics/admin/device-admin.html">Android Device Administration API</a>.
+ </p>
+ <p>
+ If device implementations implement the full range of <a href="http://developer.android.com/guide/topics/admin/device-admin.html">device administration</a> policies defined in the Android SDK documentation, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST declare <code>android.software.device_admin</code>.
+ </li>
+ <li>[C-1-2] MUST support device owner provisioning as described in <a href="#3_9_1_device_provisioning">section 3.9.1</a> and <a href="#3_9_1_1_device_owner_provisioning">section 3.9.1.1</a>.
+ </li>
+ </ul>
+ <h4 id="3_9_1_device_provisioning">
+ 3.9.1 Device Provisioning
+ </h4>
+ <h5 id="3_9_1_1_device_owner_provisioning">
+ 3.9.1.1 Device owner provisioning
+ </h5>
+ <p>
+ If device implementations declare <code>android.software.device_admin</code>, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support enrolling a Device Policy Client (DPC) as a <a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#isDeviceOwnerApp%28java.lang.String%29">Device Owner app</a> as described below:
+ <ul>
+ <li>When the device implementation has no user data is configured yet, it:
+ <ul>
+ <li>[C-1-3] MUST report <code>true</code> for <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#isProvisioningAllowed(java.lang.String)"><code>DevicePolicyManager.isProvisioningAllowed(ACTION_PROVISION_MANAGED_DEVICE)</code></a>.
+ </li>
+ <li>[C-1-4] MUST enroll the DPC application as the Device Owner app in response to the intent action <a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#ACTION_PROVISION_MANAGED_DEVICE"><code>android.app.action.PROVISION_MANAGED_DEVICE</code></a>.
+ </li>
+ <li>[C-1-5] MUST enroll the DPC application as the Device Owner app if the device declares Near-Field Communications (NFC) support via the feature flag <code>android.hardware.nfc</code> and receives an NFC message containing a record with MIME type <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#MIME_TYPE_PROVISIONING_NFC"><code>MIME_TYPE_PROVISIONING_NFC</code></a>.
+ </li>
+ </ul>
+ </li>
+ <li>When the device implementation has user data, it:
+ <ul>
+ <li>[C-1-6] MUST report <code>false</code> for the <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#isProvisioningAllowed(java.lang.String)"><code>DevicePolicyManager.isProvisioningAllowed(ACTION_PROVISION_MANAGED_DEVICE)</code></a>.
+ </li>
+ <li>[C-1-7] MUST not enroll any DPC application as the Device Owner App any more.
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>[C-1-2] MUST require some affirmative action during the provisioning process to consent to the app being set as Device Owner. Consent can be via user action or by some programmatic means during provisioning but it MUST NOT be hard coded or prevent the use of other Device Owner apps.
+ </li>
+ </ul>
+ <p>
+ If device implementations declare <code>android.software.device_admin</code>, but also include a proprietary Device Owner management solution and provide a mechanism to promote an application configured in their solution as a "Device Owner equivalent" to the standard "Device Owner" as recognized by the standard Android <a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html">DevicePolicyManager</a> APIs, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST have a process in place to verify that the specific app being promoted belongs to a legitimate enterprise device management solution and it has been already configured in the proprietary solution to have the rights equivalent as a "Device Owner".
+ </li>
+ <li>[C-2-2] MUST show the same AOSP Device Owner consent disclosure as the flow initiated by <a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#ACTION_PROVISION_MANAGED_DEVICE"><code>android.app.action.PROVISION_MANAGED_DEVICE</code></a> prior to enrolling the DPC application as "Device Owner".
+ </li>
+ <li>MAY have user data on the device prior to enrolling the DPC application as "Device Owner".
+ </li>
+ </ul>
+ <h5 id="3_9_1_2_managed_profile_provisioning">
+ 3.9.1.2 Managed profile provisioning
+ </h5>
+ <p>
+ If device implementations declare <code>android.software.managed_users</code>, they:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-1-1] MUST implement the <a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#ACTION_PROVISION_MANAGED_PROFILE">APIs</a> allowing a Device Policy Controller (DPC) application to become the <a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#isProfileOwnerApp%28java.lang.String%29">owner of a new Managed Profile</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-2] The managed profile provisioning process (the flow initiated by <a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#ACTION_PROVISION_MANAGED_PROFILE">android.app.action.PROVISION_MANAGED_PROFILE</a>) users experience MUST align with the AOSP implementation.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-3] MUST provide the following user affordances within the Settings to indicate to the user when a particular system function has been disabled by the Device Policy Controller (DPC):
+ </p>
+ <ul>
+ <li>A consistent icon or other user affordance (for example the upstream AOSP info icon) to represent when a particular setting is restricted by a Device Admin.
+ </li>
+ <li>A short explanation message, as provided by the Device Admin via the <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setShortSupportMessage%28android.content.ComponentName,%20java.lang.CharSequence%29"><code>setShortSupportMessage</code></a>.
+ </li>
+ <li>The DPC application’s icon.
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <h4 id="3_9_2_managed_profile_support">
+ 3.9.2 Managed Profile Support
+ </h4>
+ <p>
+ If device implementations declare <code>android.software.managed_users</code>, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support managed profiles via the <code>android.app.admin.DevicePolicyManager</code> APIs.
+ </li>
+ <li>[C-1-2] MUST allow one and only <a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#ACTION_PROVISION_MANAGED_PROFILE">one managed profile to be created</a>.
+ </li>
+ <li>[C-1-3] MUST use an icon badge (similar to the AOSP upstream work badge) to represent the managed applications and widgets and other badged UI elements like Recents & Notifications.
+ </li>
+ <li>[C-1-4] MUST display a notification icon (similar to the AOSP upstream work badge) to indicate when user is within a managed profile application.
+ </li>
+ <li>[C-1-5] MUST display a toast indicating that the user is in the managed profile if and when the device wakes up (ACTION_USER_PRESENT) and the foreground application is within the managed profile.
+ </li>
+ <li>[C-1-6] Where a managed profile exists, MUST show a visual affordance in the Intent 'Chooser' to allow the user to forward the intent from the managed profile to the primary user or vice versa, if enabled by the Device Policy Controller.
+ </li>
+ <li>[C-1-7] Where a managed profile exists, MUST expose the following user affordances for both the primary user and the managed profile:
+ <ul>
+ <li>Separate accounting for battery, location, mobile data and storage usage for the primary user and managed profile.
+ </li>
+ <li>Independent management of VPN Applications installed within the primary user or managed profile.
+ </li>
+ <li>Independent management of applications installed within the primary user or managed profile.
+ </li>
+ <li>Independent management of accounts within the primary user or managed profile.
+ </li>
+ </ul>
+ </li>
+ <li>[C-1-8] MUST ensure the preinstalled dialer, contacts and messaging applications can search for and look up caller information from the managed profile (if one exists) alongside those from the primary profile, if the Device Policy Controller permits it.
+ </li>
+ <li>[C-1-9] MUST ensure that it satisfies all the security requirements applicable for a device with multiple users enabled (see<a href="#9_5_multi-user_support">section 9.5</a>), even though the managed profile is not counted as another user in addition to the primary user.
+ </li>
+ <li>[C-1-10] MUST support the ability to specify a separate lock screen meeting the following requirements to grant access to apps running in a managed profile.
+ <ul>
+ <li>Device implementations MUST honor the <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#ACTION_SET_NEW_PASSWORD"><code>DevicePolicyManager.ACTION_SET_NEW_PASSWORD</code></a> intent and show an interface to configure a separate lock screen credential for the managed profile.
+ </li>
+ <li>The lock screen credentials of the managed profile MUST use the same credential storage and management mechanisms as the parent profile, as documented on the <a href="http://source.android.com/security/authentication/index.html">Android Open Source Project Site</a>.
+ </li>
+ <li>The DPC <a href="https://developer.android.com/guide/topics/admin/device-admin.html#pwd">password policies</a> MUST apply to only the managed profile's lock screen credentials unless called upon the <code>DevicePolicyManager</code> instance returned by <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#getParentProfileInstance%28android.content.ComponentName%29">getParentProfileInstance</a>.
+ </li>
+ </ul>
+ </li>
+ <li>When contacts from the managed profile are displayed in the preinstalled call log, in-call UI, in-progress and missed-call notifications, contacts and messaging apps they SHOULD be badged with the same badge used to indicate managed profile applications.
+ </li>
+ </ul>
+ <h3 id="3_9_3_managed_user_support">
+ 3.9.3 Managed User Support
+ </h3>
+ <p>
+ If device implementations declare <code>android.software.managed_users</code>, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST provide a user affordance to logout from the current user and switch back to the primary user in multiple-user session when <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#isLogoutEnabled%28%29"><code>isLogoutEnabled</code></a> returns <code>true</code>. The user affordance MUST be accessible from the lockscreen without unlocking the device.
+ </li>
+ </ul>
+ <h3 id="3_10_accessibility">
+ 3.10. Accessibility
+ </h3>
+ <p>
+ Android provides an accessibility layer that helps users with disabilities to navigate their devices more easily. In addition, Android provides platform APIs that enable accessibility service implementations to receive callbacks for user and system events and generate alternate feedback mechanisms, such as text-to-speech, haptic feedback, and trackball/d-pad navigation.
+ </p>
+ <p>
+ If device implementations support third-party accessibility services, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST provide an implementation of the Android accessibility framework as described in the <a href="http://developer.android.com/reference/android/view/accessibility/package-summary.html">accessibility APIs</a> SDK documentation.
+ </li>
+ <li>[C-1-2] MUST generate accessibility events and deliver the appropriate <code>AccessibilityEvent</code> to all registered <a href="http://developer.android.com/reference/android/accessibilityservice/AccessibilityService.html"><code>AccessibilityService</code></a> implementations as documented in the SDK.
+ </li>
+ <li>[C-1-3] MUST honor the <code>android.settings.ACCESSIBILITY_SETTINGS</code> intent to provide a user-accessible mechanism to enable and disable the third-party accessibility services alongside the preloaded accessibility services.
+ </li>
+ <li>[C-1-4] MUST add a button in the system's navigation bar allowing the user to control the accessibility service when the enabled accessibility services declare the <a href="https://developer.android.com/reference/android/accessibilityservice/AccessibilityServiceInfo.html#FLAG%5FREQUEST%5FACCESSIBILITY%5FBUTTON"><code>AccessibilityServiceInfo.FLAG_REQUEST_ACCESSIBILITY_BUTTON</code></a> . Note that for device implementations with no system navigation bar, this requirement is not applicable, but device implementations SHOULD provide a user affordance to control these accessibility services.
+ </li>
+ </ul>
+ <p>
+ If device implementations include preloaded accessibility services, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST implement these preloaded accessibility services as <a href="https://developer.android.com/reference/android/content/pm/ComponentInfo.html#directBootAware">Direct Boot Aware</a> apps when the data storage is encrypted with File Based Encryption (FBE).
+ </li>
+ <li>SHOULD provide a mechanism in the out-of-box setup flow for users to enable relevant accessibility services, as well as options to adjust the font size, display size and magnification gestures.
+ </li>
+ </ul>
+ <h3 id="3_11_text-to-speech">
+ 3.11. Text-to-Speech
+ </h3>
+ <p>
+ Android includes APIs that allow applications to make use of text-to-speech (TTS) services and allows service providers to provide implementations of TTS services.
+ </p>
+ <p>
+ If device implementations reporting the feature android.hardware.audio.output, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support the <a href="http://developer.android.com/reference/android/speech/tts/package-summary.html">Android TTS framework</a> APIs.
+ </li>
+ </ul>
+ <p>
+ If device implementations support installation of third-party TTS engines, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST provide user affordance to allow the user to select a TTS engine for use at system level.
+ </li>
+ </ul>
+ <h3 id="3_12_tv_input_framework">
+ 3.12. TV Input Framework
+ </h3>
+ <p>
+ The <a href="http://source.android.com/devices/tv/index.html">Android Television Input Framework (TIF)</a> simplifies the delivery of live content to Android Television devices. TIF provides a standard API to create input modules that control Android Television devices.
+ </p>
+ <p>
+ If device implementations support TIF, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST declare the platform feature <code>android.software.live_tv</code>.
+ </li>
+ <li>[C-1-2] MUST support all TIF APIs such that an application which uses these APIs and the <a href="https://source.android.com/devices/tv/index.html#third-party_input_example">third-party TIF-based inputs</a> service can be installed and used on the device.
+ </li>
+ </ul>
+ <h3 id="3_13_quick_settings">
+ 3.13. Quick Settings
+ </h3>
+ <p>
+ Android provides a Quick Settings UI component that allows quick access to frequently used or urgently needed actions.
+ </p>
+ <p>
+ If device implementations include a Quick Settings UI component, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST allow the user to add or remove the tiles provided through the <a href="https://developer.android.com/reference/android/service/quicksettings/package-summary.html"><code>quicksettings</code></a> APIs from a third-party app.
+ </li>
+ <li>[C-1-2] MUST NOT automatically add a tile from a third-party app directly to the Quick Settings.
+ </li>
+ <li>[C-1-3] MUST display all the user-added tiles from third-party apps alongside the system-provided quick setting tiles.
+ </li>
+ </ul>
+ <h3 id="3_14_media_ui">
+ 3.14. Media UI
+ </h3>
+ <p>
+ If device implementations include the UI framework that supports third-party apps that depend on <a href="http://developer.android.com/reference/android/media/browse/MediaBrowser.html"><code>MediaBrowser</code></a> and <a href="http://developer.android.com/reference/android/media/session/MediaSession.html"><code>MediaSession</code></a> , they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST display <a href="http://developer.android.com/reference/android/media/browse/MediaBrowser.MediaItem.html">MediaItem</a> icons and notification icons unaltered.
+ </li>
+ <li>[C-1-2] MUST display those items as described by MediaSession, e.g., metadata, icons, imagery.
+ </li>
+ <li>[C-1-3] MUST show app title.
+ </li>
+ <li>[C-1-4] MUST have a drawer or other mechanism to present <a href="http://developer.android.com/reference/android/media/browse/MediaBrowser.html">MediaBrowser</a> hierarchy and provide user affordance for the <a href="http://developer.android.com/reference/android/media/browse/MediaBrowser.html">MediaBrowser</a> hierarchy.
+ </li>
+ <li>[C-1-5] MUST consider double tap of <a href="https://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_HEADSETHOOK"><code>KEYCODE_HEADSETHOOK</code></a> or <a href="https://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_MEDIA_PLAY_PAUSE"><code>KEYCODE_MEDIA_PLAY_PAUSE</code></a> as <a href="https://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_MEDIA_NEXT"><code>KEYCODE_MEDIA_NEXT</code></a> for <a href="https://developer.android.com/reference/android/media/session/MediaSession.Callback.html#onMediaButtonEvent%28android.content.Intent%29"><code>MediaSession.Callback#onMediaButtonEvent</code></a>.
+ </li>
+ </ul>
+ <h3 id="3_15_instant_apps">
+ 3.15. Instant Apps
+ </h3>
+ <p>
+ Device implementations MUST satisfy the following requirements:
+ </p>
+ <ul>
+ <li>[C-0-1] Instant Apps MUST only be granted permissions that have the <a href="https://developer.android.com/reference/android/R.attr#protectionLevel"><code>android:protectionLevel</code></a> set to <code>"instant"</code>.
+ </li>
+ <li>[C-0-2] Instant Apps MUST NOT interact with installed apps via <a href="https://developer.android.com/reference/android/content/Intent.html">implicit intents</a> unless one of the following is true:
+ <ul>
+ <li>The component's intent pattern filter is exposed and has CATEGORY_BROWSABLE
+ </li>
+ <li>The action is one of ACTION_SEND, ACTION_SENDTO, ACTION_SEND_MULTIPLE
+ </li>
+ <li>The target is explicitly exposed with <a href="https://developer.android.com/reference/android/R.attr.html#visibleToInstantApps">android:visibleToInstantApps</a>
+ </li>
+ </ul>
+ </li>
+ <li>[C-0-3] Instant Apps MUST NOT interact explicitly with installed apps unless the component is exposed via android:visibleToInstantApps.
+ </li>
+ <li>[C-0-4] IInstalled Apps MUST NOT see details about Instant Apps on the device unless the Instant App explicitly connects to the installed application.
+ </li>
+ </ul>
+ <h3 id="3_16_companion_device_pairing">
+ 3.16. Companion Device Pairing
+ </h3>
+ <p>
+ Android includes support for companion device pairing to more effectively manage association with companion devices and provides the <a href="https://developer.android.com/reference/android/companion/CompanionDeviceManager.html"><code>CompanionDeviceManager</code></a> API for apps to access this feature.
+ </p>
+ <p>
+ If device implementations support the companion device pairing feature, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST declare the feature flag <a href="https://developer.android.com/reference/android/content/pm/PackageManager.html?#FEATURE_COMPANION_DEVICE_SETUP"><code>FEATURE_COMPANION_DEVICE_SETUP</code></a> .
+ </li>
+ <li>[C-1-2] MUST ensure the APIs in the <a href="https://developer.android.com/reference/android/companion/package-summary.html"><code>android.companion</code></a> package is fully implemented.
+ </li>
+ <li>[C-1-3] MUST provide user affordances for the user to select/confirm a companion device is present and operational.
+ </li>
+ </ul>
+ <h3 id="3_17_heavyweight_apps">
+ 3.17. Heavyweight Apps
+ </h3>
+ <p>
+ If device implementations declare the feature <a href="https://developer.android.com/reference/android/content/pm/PackageManager.html#FEATURE_CANT_SAVE_STATE"><code>FEATURE_CANT_SAVE_STATE</code></a>, then they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST have only one installed app that specifies <a href="https://developer.android.com/reference/android/R.attr#cantSaveState"><code>cantSaveState</code></a> running in the system at a time. If the user leaves such an app without explicitly exiting it (for example by pressing home while leaving an active activity the system, instead of pressing back with no remaining active activities in the system), then device implementations MUST prioritize that app in RAM as they do for other things that are expected to remain running, such as foreground services. While such an app is in the background, the system can still apply power management features to it, such as limiting CPU and network access.
+ </li>
+ <li>[C-1-2] MUST provide a UI affordance to chose the app that won't participate in the normal state save/restore mechanism once the user launches a second app declared with <a href="https://developer.android.com/reference/android/R.attr#cantSaveState"><code>cantSaveState</code></a> attribute.
+ </li>
+ <li>[C-1-3] MUST NOT apply other changes in policy to apps that specify <a href="https://developer.android.com/reference/android/R.attr#cantSaveState"><code>cantSaveState</code></a>, such as changing CPU performance or changing scheduling prioritization.
+ </li>
+ </ul>
+ <p>
+ If device implementations don't declare the feature <a href="https://developer.android.com/reference/android/content/pm/PackageManager.html#FEATURE_CANT_SAVE_STATE"><code>FEATURE_CANT_SAVE_STATE</code></a>, then they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST ignore the <a href="https://developer.android.com/reference/android/R.attr#cantSaveState"><code>cantSaveState</code></a> attribute set by apps and MUST NOT change the app behavior based on that attribute.
+ </li>
+ </ul>
+ <h2 id="4_application_packaging_compatibility">
+ 4. Application Packaging Compatibility
+ </h2>
+ <p>
+ Devices implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST be capable of installing and running Android “.apk” files as generated by the “aapt” tool included in the <a href="http://developer.android.com/tools/help/index.html">official Android SDK</a>.
+ </li>
+ <li>As the above requirement may be challenging, device implementations are RECOMMENDED to use the AOSP reference implementation's package management system.
+ </li>
+ </ul>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-2] MUST support verifying “.apk” files using the <a href="https://source.android.com/security/apksigning/v3.html">APK Signature Scheme v3</a> , <a href="https://source.android.com/security/apksigning/v2.html">APK Signature Scheme v2</a> and <a href="https://source.android.com/security/apksigning/v2.html#v1-verification">JAR signing</a>.
+ </li>
+ <li>[C-0-3] MUST NOT extend either the <a href="http://developer.android.com/guide/components/fundamentals.html">.apk</a>, <a href="http://developer.android.com/guide/topics/manifest/manifest-intro.html">Android Manifest</a>, <a href="https://android.googlesource.com/platform/dalvik/">Dalvik bytecode</a>, or RenderScript bytecode formats in such a way that would prevent those files from installing and running correctly on other compatible devices.
+ </li>
+ <li>
+ <p>
+ [C-0-4] MUST NOT allow apps other than the current "installer of record" for the package to silently uninstall the app without any user confirmation, as documented in the SDK for the <a href="https://developer.android.com/reference/android/Manifest.permission.html#DELETE_PACKAGES"><code>DELETE_PACKAGE</code></a> permission. The only exceptions are the system package verifier app handling <a href="https://developer.android.com/reference/android/content/Intent.html#ACTION_PACKAGE_NEEDS_VERIFICATION">PACKAGE_NEEDS_VERIFICATION</a> intent and the storage manager app handling <a href="https://developer.android.com/reference/android/os/storage/StorageManager.html#ACTION_MANAGE_STORAGE">ACTION_MANAGE_STORAGE</a> intent.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-5] MUST have an activity that handles the <a href="http://developer.android.com/reference/android/provider/Settings.html#ACTION_MANAGE_UNKNOWN_APP_SOURCES"><code>android.settings.MANAGE_UNKNOWN_APP_SOURCES</code></a> intent.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-6] MUST NOT install application packages from unknown sources, unless the app that <a href="https://developer.android.com/reference/android/content/Intent.html#ACTION_INSTALL_PACKAGE">requests the installation</a> meets all the following requirements:
+ </p>
+ <ul>
+ <li>It MUST declare the <a href="http://developer.android.com/reference/android/Manifest.permission.html#REQUEST_INSTALL_PACKAGES"><code>REQUEST_INSTALL_PACKAGES</code></a> permission or have the <code>android:targetSdkVersion</code> set at 24 or lower.
+ </li>
+ <li>It MUST have been granted permission by the user to install apps from unknown sources.
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ SHOULD provide a user affordance to grant/revoke the permission to install apps from unknown sources per application, but MAY choose to implement this as a no-op and return <code>RESULT_CANCELED</code> for <a href="http://developer.android.com/reference/android/app/Activity.html#startActivityForResult%28android.content.Intent,int%29"><code>startActivityForResult()</code></a>, if the device implementation does not want to allow users to have this choice. However, even in such cases, they SHOULD indicate to the user why there is no such choice presented.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-7] MUST display a warning dialog with the warning string that is provided through the system API <code>PackageManager.setHarmfulAppWarning</code> to the user before launching an activity in an application that has been marked by the same system API <code>PackageManager.setHarmfulAppWarning</code> as potentially harmful.
+ </p>
+ </li>
+ <li>SHOULD provide a user affordance to choose to uninstall or launch an application on the warning dialog.
+ </li>
+ </ul>
+ <h2 id="5_multimedia_compatibility">
+ 5. Multimedia Compatibility
+ </h2>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST support the media formats, encoders, decoders, file types, and container formats defined in <a href="#5_1_media-codecs.md">section 5.1</a> for each and every codec declared by <code>MediaCodecList</code>.
+ </li>
+ <li>[C-0-2] MUST declare and report support of the encoders, decoders available to third-party applications via <a href="http://developer.android.com/reference/android/media/MediaCodecList.html"><code>MediaCodecList</code></a>.
+ </li>
+ <li>[C-0-3] MUST be able to decode and make available to third-party apps all the formats it can encode. This includes all bitstreams that its encoders generate and the profiles reported in its <a href="http://developer.android.com/reference/android/media/CamcorderProfile.html"><code>CamcorderProfile</code></a>.
+ </li>
+ </ul>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>SHOULD aim for minimum codec latency, in other words, they:
+ <ul>
+ <li>SHOULD NOT consume and store input buffers and return input buffers only once processed.
+ </li>
+ <li>SHOULD NOT hold onto decoded buffers for longer than as specified by the standard (e.g. SPS).
+ </li>
+ <li>SHOULD NOT hold onto encoded buffers longer than required by the GOP structure.
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <p>
+ All of the codecs listed in the section below are provided as software implementations in the preferred Android implementation from the Android Open Source Project.
+ </p>
+ <p>
+ Please note that neither Google nor the Open Handset Alliance make any representation that these codecs are free from third-party patents. Those intending to use this source code in hardware or software products are advised that implementations of this code, including in open source software or shareware, may require patent licenses from the relevant patent holders.
+ </p>
+ <h3 id="5_1_media_codecs">
+ 5.1. Media Codecs
+ </h3>
+ <h4 id="5_1_1_audio_encoding">
+ 5.1.1. Audio Encoding
+ </h4>
+ <p>
+ See more details in <a href="#5_1_3_audio_codecs_details">5.1.3. Audio Codecs Details</a>.
+ </p>
+ <p>
+ If device implementations declare <code>android.hardware.microphone</code>, they MUST support the following audio encoding:
+ </p>
+ <ul>
+ <li>[C-1-1] PCM/WAVE
+ </li>
+ </ul>
+ <h4 id="5_1_2_audio_decoding">
+ 5.1.2. Audio Decoding
+ </h4>
+ <p>
+ See more details in <a href="#5_1_3_audio_codecs_details">5.1.3. Audio Codecs Details</a>.
+ </p>
+ <p>
+ If device implementations declare support for the <code>android.hardware.audio.output</code> feature, they must support decoding the following audio formats:
+ </p>
+ <ul>
+ <li>[C-1-1] MPEG-4 AAC Profile (AAC LC)
+ </li>
+ <li>[C-1-2] MPEG-4 HE AAC Profile (AAC+)
+ </li>
+ <li>[C-1-3] MPEG-4 HE AACv2 Profile (enhanced AAC+)
+ </li>
+ <li>[C-1-4] AAC ELD (enhanced low delay AAC)
+ </li>
+ <li>[C-1-11] xHE-AAC (ISO/IEC 23003-3 Extended HE AAC Profile, which includes the USAC Baseline Profile, and ISO/IEC 23003-4 Dynamic Range Control Profile)
+ </li>
+ <li>[C-1-5] FLAC
+ </li>
+ <li>[C-1-6] MP3
+ </li>
+ <li>[C-1-7] MIDI
+ </li>
+ <li>[C-1-8] Vorbis
+ </li>
+ <li>[C-1-9] PCM/WAVE
+ </li>
+ <li>[C-1-10] Opus
+ </li>
+ </ul>
+ <p>
+ If device implementations support the decoding of AAC input buffers of multichannel streams (i.e. more than two channels) to PCM through the default AAC audio decoder in the <code>android.media.MediaCodec</code> API, the following MUST be supported:
+ </p>
+ <ul>
+ <li>[C-2-1] Decoding MUST be performed without downmixing (e.g. a 5.0 AAC stream must be decoded to five channels of PCM, a 5.1 AAC stream must be decoded to six channels of PCM).
+ </li>
+ <li>[C-2-2] Dynamic range metadata MUST be as defined in "Dynamic Range Control (DRC)" in ISO/IEC 14496-3, and the <code>android.media.MediaFormat</code> DRC keys to configure the dynamic range-related behaviors of the audio decoder. The AAC DRC keys were introduced in API 21,and are: <code>KEY_AAC_DRC_ATTENUATION_FACTOR</code>, <code>KEY_AAC_DRC_BOOST_FACTOR</code>, <code>KEY_AAC_DRC_HEAVY_COMPRESSION</code>, <code>KEY_AAC_DRC_TARGET_REFERENCE_LEVEL</code> and <code>KEY_AAC_ENCODED_TARGET_LEVEL</code>.
+ </li>
+ </ul>
+ <p>
+ When decoding USAC audio, MPEG-D (ISO/IEC 23003-4):
+ </p>
+ <ul>
+ <li>[C-3-1] Loudness and DRC metadata MUST be interpreted and applied according to MPEG-D DRC Dynamic Range Control Profile Level 1.
+ </li>
+ <li>[C-3-2] The decoder MUST behave according to the configuration set with the following <code>android.media.MediaFormat</code> keys: <code>KEY_AAC_DRC_TARGET_REFERENCE_LEVEL</code> and <code>KEY_AAC_DRC_EFFECT_TYPE</code>.
+ </li>
+ </ul>
+ <p>
+ MPEG-4 AAC, HE AAC, and HE AACv2 profile decoders:
+ </p>
+ <ul>
+ <li>MAY support loudness and dynamic range control using ISO/IEC 23003-4 Dynamic Range Control Profile.
+ </li>
+ </ul>
+ <p>
+ If ISO/IEC 23003-4 is supported and if both ISO/IEC 23003-4 and ISO/IEC 14496-3 metadata are present in a decoded bitstream, then:
+ </p>
+ <ul>
+ <li>ISO/IEC 23003-4 metadata SHALL take precedence.
+ </li>
+ </ul>
+ <h4 id="5_1_3_audio_codecs_details">
+ 5.1.3. Audio Codecs Details
+ </h4>
+ <table>
+ <tr>
+ <th>
+ Format/Codec
+ </th>
+ <th>
+ Details
+ </th>
+ <th>
+ Supported File Types/Container Formats
+ </th>
+ </tr>
+ <tr>
+ <td>
+ MPEG-4 AAC Profile<br>
+ (AAC LC)
+ </td>
+ <td>
+ Support for mono/stereo/5.0/5.1 content with standard sampling rates from 8 to 48 kHz.
+ </td>
+ <td>
+ <ul>
+ <li class="table_list">3GPP (.3gp)
+ </li>
+ <li class="table_list">MPEG-4 (.mp4, .m4a)
+ </li>
+ <li class="table_list">ADTS raw AAC (.aac, ADIF not supported)
+ </li>
+ <li class="table_list">MPEG-TS (.ts, not seekable)
+ </li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ MPEG-4 HE AAC Profile (AAC+)
+ </td>
+ <td>
+ Support for mono/stereo/5.0/5.1 content with standard sampling rates from 16 to 48 kHz.
+ </td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>
+ MPEG-4 HE AACv2<br>
+ Profile (enhanced AAC+)
+ </td>
+ <td>
+ Support for mono/stereo/5.0/5.1 content with standard sampling rates from 16 to 48 kHz.
+ </td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>
+ AAC ELD (enhanced low delay AAC)
+ </td>
+ <td>
+ Support for mono/stereo content with standard sampling rates from 16 to 48 kHz.
+ </td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>
+ USAC
+ </td>
+ <td>
+ Support for mono/stereo content with standard sampling rates from 7.35 to 48 kHz.
+ </td>
+ <td>
+ <ul>
+ <li>MPEG-4 (.mp4, .m4a)
+ </li>
+ <li>LATM/LOAS (.loas, .xhe)
+ </li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ AMR-NB
+ </td>
+ <td>
+ 4.75 to 12.2 kbps sampled @ 8 kHz
+ </td>
+ <td>
+ 3GPP (.3gp)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ AMR-WB
+ </td>
+ <td>
+ 9 rates from 6.60 kbit/s to 23.85 kbit/s sampled @ 16 kHz
+ </td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>
+ FLAC
+ </td>
+ <td>
+ Mono/Stereo (no multichannel). Sample rates up to 48 kHz (but up to 44.1 kHz is RECOMMENDED on devices with 44.1 kHz output, as the 48 to 44.1 kHz downsampler does not include a low-pass filter). 16-bit RECOMMENDED; no dither applied for 24-bit.
+ </td>
+ <td>
+ FLAC (.flac) only
+ </td>
+ </tr>
+ <tr>
+ <td>
+ MP3
+ </td>
+ <td>
+ Mono/Stereo 8-320Kbps constant (CBR) or variable bitrate (VBR)
+ </td>
+ <td>
+ MP3 (.mp3)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ MIDI
+ </td>
+ <td>
+ MIDI Type 0 and 1. DLS Version 1 and 2. XMF and Mobile XMF. Support for ringtone formats RTTTL/RTX, OTA, and iMelody
+ </td>
+ <td>
+ <ul>
+ <li class="table_list">Type 0 and 1 (.mid, .xmf, .mxmf)
+ </li>
+ <li class="table_list">RTTTL/RTX (.rtttl, .rtx)
+ </li>
+ <li class="table_list">OTA (.ota)
+ </li>
+ <li class="table_list">iMelody (.imy)
+ </li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ Vorbis
+ </td>
+ <td></td>
+ <td>
+ <ul>
+ <li class="table_list">Ogg (.ogg)
+ </li>
+ <li class="table_list">Matroska (.mkv, Android 4.0+)
+ </li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ PCM/WAVE
+ </td>
+ <td>
+ 16-bit linear PCM (rates up to limit of hardware). Devices MUST support sampling rates for raw PCM recording at 8000, 11025, 16000, and 44100 Hz frequencies.
+ </td>
+ <td>
+ WAVE (.wav)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ Opus
+ </td>
+ <td></td>
+ <td>
+ Matroska (.mkv), Ogg(.ogg)
+ </td>
+ </tr>
+ </table>
+ <h4 id="5_1_4_image_encoding">
+ 5.1.4. Image Encoding
+ </h4>
+ <p>
+ See more details in <a href="#5_1_6_image_codecs_details">5.1.6. Image Codecs Details</a>.
+ </p>
+ <p>
+ Device implementations MUST support encoding the following image encoding:
+ </p>
+ <ul>
+ <li>[C-0-1] JPEG
+ </li>
+ <li>[C-0-2] PNG
+ </li>
+ <li>[C-0-3] WebP
+ </li>
+ </ul>
+ <h4 id="5_1_5_image_decoding">
+ 5.1.5. Image Decoding
+ </h4>
+ <p>
+ See more details in <a href="#5_1_6_image_codecs_details">5.1.6. Image Codecs Details</a>.
+ </p>
+ <p>
+ Device implementations MUST support decoding the following image encoding:
+ </p>
+ <ul>
+ <li>[C-0-1] JPEG
+ </li>
+ <li>[C-0-2] GIF
+ </li>
+ <li>[C-0-3] PNG
+ </li>
+ <li>[C-0-4] BMP
+ </li>
+ <li>[C-0-5] WebP
+ </li>
+ <li>[C-0-6] Raw
+ </li>
+ <li>[C-0-7] HEIF (HEIC)
+ </li>
+ </ul>
+ <h4 id="5_1_6_image_codecs_details">
+ 5.1.6. Image Codecs Details
+ </h4>
+ <table>
+ <tr>
+ <th>
+ Format/Codec
+ </th>
+ <th>
+ Details
+ </th>
+ <th>
+ Supported File Types/Container Formats
+ </th>
+ </tr>
+ <tr>
+ <td>
+ JPEG
+ </td>
+ <td>
+ Base+progressive
+ </td>
+ <td>
+ JPEG (.jpg)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ GIF
+ </td>
+ <td></td>
+ <td>
+ GIF (.gif)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ PNG
+ </td>
+ <td></td>
+ <td>
+ PNG (.png)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ BMP
+ </td>
+ <td></td>
+ <td>
+ BMP (.bmp)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ WebP
+ </td>
+ <td></td>
+ <td>
+ WebP (.webp)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ Raw
+ </td>
+ <td></td>
+ <td>
+ ARW (.arw), CR2 (.cr2), DNG (.dng), NEF (.nef), NRW (.nrw), ORF (.orf), PEF (.pef), RAF (.raf), RW2 (.rw2), SRW (.srw)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ HEIF
+ </td>
+ <td>
+ Image, Image collection, Image sequence
+ </td>
+ <td>
+ HEIF (.heif), HEIC (.heic)
+ </td>
+ </tr>
+ </table>
+ <h4 id="5_1_7_video_codecs">
+ 5.1.7. Video Codecs
+ </h4>
+ <ul>
+ <li>For acceptable quality of web video streaming and video-conference services, device implementations SHOULD use a hardware VP8 codec that meets the <a href="http://www.webmproject.org/hardware/rtc-coding-requirements/">requirements</a>.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a video decoder or encoder:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-1-1] Video codecs MUST support output and input bytebuffer sizes that accommodate the largest feasible compressed and uncompressed frame as dictated by the standard and configuration but also not overallocate.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-2] Video encoders and decoders MUST support YUV420 flexible color format (COLOR_FormatYUV420Flexible).
+ </p>
+ </li>
+ </ul>
+ <p>
+ If device implementations advertise HDR profile support through <a href="https://developer.android.com/reference/android/view/Display.HdrCapabilities.html"><code>Display.HdrCapabilities</code></a>, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST support HDR static metadata parsing and handling.
+ </li>
+ </ul>
+ <p>
+ If device implementations advertise intra refresh support through <code>FEATURE_IntraRefresh</code> in the <a href="https://developer.android.com/reference/android/media/MediaCodecInfo.CodecCapabilities.html#FEATURE_IntraRefresh"><code>MediaCodecInfo.CodecCapabilities</code></a> class, they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST support the refresh periods in the range of 10 - 60 frames and accurately operate within 20% of configured refresh period.
+ </li>
+ </ul>
+ <h4 id="5_1_8_video_codecs_list">
+ 5.1.8. Video Codecs List
+ </h4>
+ <table>
+ <tr>
+ <th>
+ Format/Codec
+ </th>
+ <th>
+ Details
+ </th>
+ <th>
+ Supported File Types/<br>
+ Container Formats
+ </th>
+ </tr>
+ <tr>
+ <td>
+ H.263
+ </td>
+ <td></td>
+ <td>
+ <ul>
+ <li class="table_list">3GPP (.3gp)
+ </li>
+ <li class="table_list">MPEG-4 (.mp4)
+ </li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ H.264 AVC
+ </td>
+ <td>
+ See <a href="#5_2_video_encoding">section 5.2</a> and <a href="#5_3_video_decoding">5.3</a> for details
+ </td>
+ <td>
+ <ul>
+ <li class="table_list">3GPP (.3gp)
+ </li>
+ <li class="table_list">MPEG-4 (.mp4)
+ </li>
+ <li class="table_list">MPEG-2 TS (.ts, AAC audio only, not seekable, Android 3.0+)
+ </li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ H.265 HEVC
+ </td>
+ <td>
+ See <a href="#5_3_video_decoding">section 5.3</a> for details
+ </td>
+ <td>
+ MPEG-4 (.mp4)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ MPEG-2
+ </td>
+ <td>
+ Main Profile
+ </td>
+ <td>
+ MPEG2-TS
+ </td>
+ </tr>
+ <tr>
+ <td>
+ MPEG-4 SP
+ </td>
+ <td></td>
+ <td>
+ 3GPP (.3gp)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ VP8
+ </td>
+ <td>
+ See <a href="#5_2_video_encoding">section 5.2</a> and <a href="#5_3_video_decoding">5.3</a> for details
+ </td>
+ <td>
+ <ul>
+ <li class="table_list">
+ <a href="http://www.webmproject.org/">WebM (.webm)</a>
+ </li>
+ <li class="table_list">Matroska (.mkv)
+ </li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ VP9
+ </td>
+ <td>
+ See <a href="#5_3_video_decoding">section 5.3</a> for details
+ </td>
+ <td>
+ <ul>
+ <li class="table_list">
+ <a href="http://www.webmproject.org/">WebM (.webm)</a>
+ </li>
+ <li class="table_list">Matroska (.mkv)
+ </li>
+ </ul>
+ </td>
+ </tr>
+ </table>
+ <h3 id="5_2_video_encoding">
+ 5.2. Video Encoding
+ </h3>
+ <p>
+ If device implementations support any video encoder and make it available to third-party apps, they:
+ </p>
+ <ul>
+ <li>SHOULD NOT be, over two sliding windows, more than ~15% over the bitrate between intraframe (I-frame) intervals.
+ </li>
+ <li>SHOULD NOT be more than ~100% over the bitrate over a sliding window of 1 second.
+ </li>
+ </ul>
+ <p>
+ If device implementations include an embedded screen display with the diagonal length of at least 2.5 inches or include a video output port or declare the support of a camera via the <code>android.hardware.camera.any</code> feature flag, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST include the support of at least one of the VP8 or H.264 video encoders, and make it available for third-party applications.
+ </li>
+ <li>SHOULD support both VP8 and H.264 video encoders, and make it available for third-party applications.
+ </li>
+ </ul>
+ <p>
+ If device implementations support any of the H.264, VP8, VP9 or HEVC video encoders and make it available to third-party applications, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST support dynamically configurable bitrates.
+ </li>
+ <li>SHOULD support variable frame rates, where video encoder SHOULD determine instantaneous frame duration based on the timestamps of input buffers, and allocate its bit bucket based on that frame duration.
+ </li>
+ </ul>
+ <p>
+ If device implementations support the MPEG-4 SP video encoder and make it available to third-party apps, they:
+ </p>
+ <ul>
+ <li>SHOULD support dynamically configurable bitrates for the supported encoder.
+ </li>
+ </ul>
+ <h4 id="5_2_1_h_263">
+ 5.2.1. H.263
+ </h4>
+ <p>
+ If device implementations support H.263 encoders and make it available to third-party apps, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support Baseline Profile Level 45.
+ </li>
+ <li>SHOULD support dynamically configurable bitrates for the supported encoder.
+ </li>
+ </ul>
+ <h4 id="5_2_2_h-264">
+ 5.2.2. H-264
+ </h4>
+ <p>
+ If device implementations support H.264 codec, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support Baseline Profile Level 3. However, support for ASO (Arbitrary Slice Ordering), FMO (Flexible Macroblock Ordering) and RS (Redundant Slices) is OPTIONAL. Moreover, to maintain compatibility with other Android devices, it is RECOMMENDED that ASO, FMO and RS are not used for Baseline Profile by encoders.
+ </li>
+ <li>[C-1-2] MUST support the SD (Standard Definition) video encoding profiles in the following table.
+ </li>
+ <li>SHOULD support Main Profile Level 4.
+ </li>
+ <li>SHOULD support the HD (High Definition) video encoding profiles as indicated in the following table.
+ </li>
+ </ul>
+ <p>
+ If device implementations report support of H.264 encoding for 720p or 1080p resolution videos through the media APIs, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST support the encoding profiles in the following table.
+ </li>
+ </ul>
+ <table>
+ <tr>
+ <th></th>
+ <th>
+ SD (Low quality)
+ </th>
+ <th>
+ SD (High quality)
+ </th>
+ <th>
+ HD 720p
+ </th>
+ <th>
+ HD 1080p
+ </th>
+ </tr>
+ <tr>
+ <th>
+ Video resolution
+ </th>
+ <td>
+ 320 x 240 px
+ </td>
+ <td>
+ 720 x 480 px
+ </td>
+ <td>
+ 1280 x 720 px
+ </td>
+ <td>
+ 1920 x 1080 px
+ </td>
+ </tr>
+ <tr>
+ <th>
+ Video frame rate
+ </th>
+ <td>
+ 20 fps
+ </td>
+ <td>
+ 30 fps
+ </td>
+ <td>
+ 30 fps
+ </td>
+ <td>
+ 30 fps
+ </td>
+ </tr>
+ <tr>
+ <th>
+ Video bitrate
+ </th>
+ <td>
+ 384 Kbps
+ </td>
+ <td>
+ 2 Mbps
+ </td>
+ <td>
+ 4 Mbps
+ </td>
+ <td>
+ 10 Mbps
+ </td>
+ </tr>
+ </table>
+ <h4 id="5_2_3_vp8">
+ 5.2.3. VP8
+ </h4>
+ <p>
+ If device implementations support VP8 codec, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support the SD video encoding profiles.
+ </li>
+ <li>SHOULD support the following HD (High Definition) video encoding profiles.
+ </li>
+ <li>SHOULD support writing Matroska WebM files.
+ </li>
+ <li>SHOULD use a hardware VP8 codec that meets the <a href="http://www.webmproject.org/hardware/rtc-coding-requirements">WebM project RTC hardware coding requirements</a>, to ensure acceptable quality of web video streaming and video-conference services.
+ </li>
+ </ul>
+ <p>
+ If device implementations report support of VP8 encoding for 720p or 1080p resolution videos through the media APIs, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST support the encoding profiles in the following table.
+ </li>
+ </ul>
+ <table>
+ <tr>
+ <th></th>
+ <th>
+ SD (Low quality)
+ </th>
+ <th>
+ SD (High quality)
+ </th>
+ <th>
+ HD 720p
+ </th>
+ <th>
+ HD 1080p
+ </th>
+ </tr>
+ <tr>
+ <th>
+ Video resolution
+ </th>
+ <td>
+ 320 x 180 px
+ </td>
+ <td>
+ 640 x 360 px
+ </td>
+ <td>
+ 1280 x 720 px
+ </td>
+ <td>
+ 1920 x 1080 px
+ </td>
+ </tr>
+ <tr>
+ <th>
+ Video frame rate
+ </th>
+ <td>
+ 30 fps
+ </td>
+ <td>
+ 30 fps
+ </td>
+ <td>
+ 30 fps
+ </td>
+ <td>
+ 30 fps
+ </td>
+ </tr>
+ <tr>
+ <th>
+ Video bitrate
+ </th>
+ <td>
+ 800 Kbps
+ </td>
+ <td>
+ 2 Mbps
+ </td>
+ <td>
+ 4 Mbps
+ </td>
+ <td>
+ 10 Mbps
+ </td>
+ </tr>
+ </table>
+ <h4 id="5_2_4_vp9">
+ 5.2.4. VP9
+ </h4>
+ <p>
+ If device implementations support VP9 codec, they:
+ </p>
+ <ul>
+ <li>SHOULD support writing Matroska WebM files.
+ </li>
+ </ul>
+ <h3 id="5_3_video_decoding">
+ 5.3. Video Decoding
+ </h3>
+ <p>
+ If device implementations support VP8, VP9, H.264, or H.265 codecs, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support dynamic video resolution and frame rate switching through the standard Android APIs within the same stream for all VP8, VP9, H.264, and H.265 codecs in real time and up to the maximum resolution supported by each codec on the device.
+ </li>
+ </ul>
+ <p>
+ If device implementations declare support for the Dolby Vision decoder through <a href="https://developer.android.com/reference/android/view/Display.HdrCapabilities.html#HDR_TYPE_DOLBY_VISION"><code>HDR_TYPE_DOLBY_VISION</code></a> , they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST provide a Dolby Vision-capable extractor.
+ </li>
+ <li>[C-2-2] MUST properly display Dolby Vision content on the device screen or on a standard video output port (e.g., HDMI).
+ </li>
+ <li>[C-2-3] MUST set the track index of backward-compatible base-layer(s) (if present) to be the same as the combined Dolby Vision layer's track index.
+ </li>
+ </ul>
+ <h4 id="5_3_1_mpeg-2">
+ 5.3.1. MPEG-2
+ </h4>
+ <p>
+ If device implementations support MPEG-2 decoders, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support the Main Profile High Level.
+ </li>
+ </ul>
+ <h4 id="5_3_2_h_263">
+ 5.3.2. H.263
+ </h4>
+ <p>
+ If device implementations support H.263 decoders, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support Baseline Profile Level 30 and Level 45.
+ </li>
+ </ul>
+ <h4 id="5_3_3_mpeg-4">
+ 5.3.3. MPEG-4
+ </h4>
+ <p>
+ If device implementations with MPEG-4 decoders, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support Simple Profile Level 3.
+ </li>
+ </ul>
+ <h4 id="5_3_4_h_264">
+ 5.3.4. H.264
+ </h4>
+ <p>
+ If device implementations support H.264 decoders, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support Main Profile Level 3.1 and Baseline Profile. Support for ASO (Arbitrary Slice Ordering), FMO (Flexible Macroblock Ordering) and RS (Redundant Slices) is OPTIONAL.
+ </li>
+ <li>[C-1-2] MUST be capable of decoding videos with the SD (Standard Definition) profiles listed in the following table and encoded with the Baseline Profile and Main Profile Level 3.1 (including 720p30).
+ </li>
+ <li>SHOULD be capable of decoding videos with the HD (High Definition) profiles as indicated in the following table.
+ </li>
+ </ul>
+ <p>
+ If the height that is reported by the <code>Display.getSupportedModes()</code> method is equal or greater than the video resolution, device implementations:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST support the HD 720p video decoding profiles in the following table.
+ </li>
+ <li>[C-2-2] MUST support the HD 1080p video decoding profiles in the following table.
+ </li>
+ </ul>
+ <table>
+ <tr>
+ <th></th>
+ <th>
+ SD (Low quality)
+ </th>
+ <th>
+ SD (High quality)
+ </th>
+ <th>
+ HD 720p
+ </th>
+ <th>
+ HD 1080p
+ </th>
+ </tr>
+ <tr>
+ <th>
+ Video resolution
+ </th>
+ <td>
+ 320 x 240 px
+ </td>
+ <td>
+ 720 x 480 px
+ </td>
+ <td>
+ 1280 x 720 px
+ </td>
+ <td>
+ 1920 x 1080 px
+ </td>
+ </tr>
+ <tr>
+ <th>
+ Video frame rate
+ </th>
+ <td>
+ 30 fps
+ </td>
+ <td>
+ 30 fps
+ </td>
+ <td>
+ 60 fps
+ </td>
+ <td>
+ 30 fps (60 fps<sup>Television</sup>)
+ </td>
+ </tr>
+ <tr>
+ <th>
+ Video bitrate
+ </th>
+ <td>
+ 800 Kbps
+ </td>
+ <td>
+ 2 Mbps
+ </td>
+ <td>
+ 8 Mbps
+ </td>
+ <td>
+ 20 Mbps
+ </td>
+ </tr>
+ </table>
+ <h4 id="5_3_5_h_265_(hevc)">
+ 5.3.5. H.265 (HEVC)
+ </h4>
+ <p>
+ If device implementations support H.265 codec, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support the Main Profile Level 3 Main tier and the SD video decoding profiles as indicated in the following table.
+ </li>
+ <li>SHOULD support the HD decoding profiles as indicated in the following table.
+ </li>
+ <li>[C-1-2] MUST support the HD decoding profiles as indicated in the following table if there is a hardware decoder.
+ </li>
+ </ul>
+ <p>
+ If the height that is reported by the <code>Display.getSupportedModes()</code> method is equal to or greater than the video resolution, then:
+ </p>
+ <ul>
+ <li>[C-2-1] Device implementations MUST support at least one of H.265 or VP9 decoding of 720, 1080 and UHD profiles.
+ </li>
+ </ul>
+ <table>
+ <tr>
+ <th></th>
+ <th>
+ SD (Low quality)
+ </th>
+ <th>
+ SD (High quality)
+ </th>
+ <th>
+ HD 720p
+ </th>
+ <th>
+ HD 1080p
+ </th>
+ <th>
+ UHD
+ </th>
+ </tr>
+ <tr>
+ <th>
+ Video resolution
+ </th>
+ <td>
+ 352 x 288 px
+ </td>
+ <td>
+ 720 x 480 px
+ </td>
+ <td>
+ 1280 x 720 px
+ </td>
+ <td>
+ 1920 x 1080 px
+ </td>
+ <td>
+ 3840 x 2160 px
+ </td>
+ </tr>
+ <tr>
+ <th>
+ Video frame rate
+ </th>
+ <td>
+ 30 fps
+ </td>
+ <td>
+ 30 fps
+ </td>
+ <td>
+ 30 fps
+ </td>
+ <td>
+ 30/60 fps (60 fps<sup>Television with H.265 hardware decoding</sup>)
+ </td>
+ <td>
+ 60 fps
+ </td>
+ </tr>
+ <tr>
+ <th>
+ Video bitrate
+ </th>
+ <td>
+ 600 Kbps
+ </td>
+ <td>
+ 1.6 Mbps
+ </td>
+ <td>
+ 4 Mbps
+ </td>
+ <td>
+ 5 Mbps
+ </td>
+ <td>
+ 20 Mbps
+ </td>
+ </tr>
+ </table>
+ <h4 id="5_3_6_vp8">
+ 5.3.6. VP8
+ </h4>
+ <p>
+ If device implementations support VP8 codec, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support the SD decoding profiles in the following table.
+ </li>
+ <li>SHOULD use a hardware VP8 codec that meets the <a href="" title="http://www.webmproject.org/hardware/rtc-coding-requirements/">requirements</a>.
+ </li>
+ <li>SHOULD support the HD decoding profiles in the following table.
+ </li>
+ </ul>
+ <p>
+ If the height as reported by the <code>Display.getSupportedModes()</code> method is equal or greater than the video resolution, then:
+ </p>
+ <ul>
+ <li>[C-2-1] Device implementations MUST support 720p profiles in the following table.
+ </li>
+ <li>[C-2-2] Device implementations MUST support 1080p profiles in the following table.
+ </li>
+ </ul>
+ <table>
+ <tr>
+ <th></th>
+ <th>
+ SD (Low quality)
+ </th>
+ <th>
+ SD (High quality)
+ </th>
+ <th>
+ HD 720p
+ </th>
+ <th>
+ HD 1080p
+ </th>
+ </tr>
+ <tr>
+ <th>
+ Video resolution
+ </th>
+ <td>
+ 320 x 180 px
+ </td>
+ <td>
+ 640 x 360 px
+ </td>
+ <td>
+ 1280 x 720 px
+ </td>
+ <td>
+ 1920 x 1080 px
+ </td>
+ </tr>
+ <tr>
+ <th>
+ Video frame rate
+ </th>
+ <td>
+ 30 fps
+ </td>
+ <td>
+ 30 fps
+ </td>
+ <td>
+ 30 fps (60 fps<sup>Television</sup>)
+ </td>
+ <td>
+ 30 (60 fps<sup>Television</sup>)
+ </td>
+ </tr>
+ <tr>
+ <th>
+ Video bitrate
+ </th>
+ <td>
+ 800 Kbps
+ </td>
+ <td>
+ 2 Mbps
+ </td>
+ <td>
+ 8 Mbps
+ </td>
+ <td>
+ 20 Mbps
+ </td>
+ </tr>
+ </table>
+ <h4 id="5_3_7_vp9">
+ 5.3.7. VP9
+ </h4>
+ <p>
+ If device implementations support VP9 codec, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support the SD video decoding profiles as indicated in the following table.
+ </li>
+ <li>SHOULD support the HD decoding profiles as indicated in the following table.
+ </li>
+ </ul>
+ <p>
+ If device implementations support VP9 codec and a hardware decoder:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST support the HD decoding profiles as indicated in the following table.
+ </li>
+ </ul>
+ <p>
+ If the height that is reported by the <code>Display.getSupportedModes()</code> method is equal to or greater than the video resolution, then:
+ </p>
+ <ul>
+ <li>[C-3-1] Device implementations MUST support at least one of VP9 or H.265 decoding of the 720, 1080 and UHD profiles.
+ </li>
+ </ul>
+ <table>
+ <tr>
+ <th></th>
+ <th>
+ SD (Low quality)
+ </th>
+ <th>
+ SD (High quality)
+ </th>
+ <th>
+ HD 720p
+ </th>
+ <th>
+ HD 1080p
+ </th>
+ <th>
+ UHD
+ </th>
+ </tr>
+ <tr>
+ <th>
+ Video resolution
+ </th>
+ <td>
+ 320 x 180 px
+ </td>
+ <td>
+ 640 x 360 px
+ </td>
+ <td>
+ 1280 x 720 px
+ </td>
+ <td>
+ 1920 x 1080 px
+ </td>
+ <td>
+ 3840 x 2160 px
+ </td>
+ </tr>
+ <tr>
+ <th>
+ Video frame rate
+ </th>
+ <td>
+ 30 fps
+ </td>
+ <td>
+ 30 fps
+ </td>
+ <td>
+ 30 fps
+ </td>
+ <td>
+ 30 fps (60 fps<sup>Television with VP9 hardware decoding</sup>)
+ </td>
+ <td>
+ 60 fps
+ </td>
+ </tr>
+ <tr>
+ <th>
+ Video bitrate
+ </th>
+ <td>
+ 600 Kbps
+ </td>
+ <td>
+ 1.6 Mbps
+ </td>
+ <td>
+ 4 Mbps
+ </td>
+ <td>
+ 5 Mbps
+ </td>
+ <td>
+ 20 Mbps
+ </td>
+ </tr>
+ </table>
+ <h3 id="5_4_audio_recording">
+ 5.4. Audio Recording
+ </h3>
+ <p>
+ While some of the requirements outlined in this section are listed as SHOULD since Android 4.3, the Compatibility Definition for future versions are planned to change these to MUST. Existing and new Android devices are <strong>STRONGLY RECOMMENDED</strong> to meet these requirements that are listed as SHOULD, or they will not be able to attain Android compatibility when upgraded to the future version.
+ </p>
+ <h4 id="5_4_1_raw_audio_capture">
+ 5.4.1. Raw Audio Capture
+ </h4>
+ <p>
+ If device implementations declare <code>android.hardware.microphone</code>, they:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-1-1] MUST allow capture of raw audio content with the following characteristics:
+ </p>
+ <ul>
+ <li>
+ <strong>Format</strong>: Linear PCM, 16-bit
+ </li>
+ <li>
+ <strong>Sampling rates</strong>: 8000, 11025, 16000, 44100 Hz
+ </li>
+ <li>
+ <strong>Channels</strong>: Mono
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [C-1-2] MUST capture at above sample rates without up-sampling.
+ </p>
+ </li>
+ <li>[C-1-3] MUST include an appropriate anti-aliasing filter when the sample rates given above are captured with down-sampling.
+ </li>
+ <li>
+ <p>
+ SHOULD allow AM radio and DVD quality capture of raw audio content, which means the following characteristics:
+ </p>
+ <ul>
+ <li>
+ <strong>Format</strong>: Linear PCM, 16-bit
+ </li>
+ <li>
+ <strong>Sampling rates</strong>: 22050, 48000 Hz
+ </li>
+ <li>
+ <strong>Channels</strong>: Stereo
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <p>
+ If device implementations allow AM radio and DVD quality capture of raw audio content, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST capture without up-sampling at any ratio higher than 16000:22050 or 44100:48000.
+ </li>
+ <li>[C-2-2] MUST include an appropriate anti-aliasing filter for any up-sampling or down-sampling.
+ </li>
+ </ul>
+ <h4 id="5_4_2_capture_for_voice_recognition">
+ 5.4.2. Capture for Voice Recognition
+ </h4>
+ <p>
+ If device implementations declare <code>android.hardware.microphone</code>, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST capture <code>android.media.MediaRecorder.AudioSource.VOICE_RECOGNITION</code> audio source at one of the sampling rates, 44100 and 48000.
+ </li>
+ <li>[C-1-2] MUST, by default, disable any noise reduction audio processing when recording an audio stream from the <code>AudioSource.VOICE_RECOGNITION</code> audio source.
+ </li>
+ <li>[C-1-3] MUST, by default, disable any automatic gain control when recording an audio stream from the <code>AudioSource.VOICE_RECOGNITION</code> audio source.
+ </li>
+ <li>SHOULD record the voice recognition audio stream with approximately flat amplitude versus frequency characteristics: specifically, ±3 dB, from 100 Hz to 4000 Hz.
+ </li>
+ <li>SHOULD record the voice recognition audio stream with input sensitivity set such that a 90 dB sound power level (SPL) source at 1000 Hz yields RMS of 2500 for 16-bit samples.
+ </li>
+ <li>SHOULD record the voice recognition audio stream so that the PCM amplitude levels linearly track input SPL changes over at least a 30 dB range from -18 dB to +12 dB re 90 dB SPL at the microphone.
+ </li>
+ <li>SHOULD record the voice recognition audio stream with total harmonic distortion (THD) less than 1% for 1 kHz at 90 dB SPL input level at the microphone.
+ </li>
+ </ul>
+ <p>
+ If device implementations declare <code>android.hardware.microphone</code> and noise suppression (reduction) technologies tuned for speech recognition, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST allow this audio effect to be controllable with the <code>android.media.audiofx.NoiseSuppressor</code> API.
+ </li>
+ <li>[C-2-2] MUST uniquely identify each noise suppression technology implementation via the <code>AudioEffect.Descriptor.uuid</code> field.
+ </li>
+ </ul>
+ <h4 id="5_4_3_capture_for_rerouting_of_playback">
+ 5.4.3. Capture for Rerouting of Playback
+ </h4>
+ <p>
+ The <code>android.media.MediaRecorder.AudioSource</code> class includes the <code>REMOTE_SUBMIX</code> audio source.
+ </p>
+ <p>
+ If device implementations declare both <code>android.hardware.audio.output</code> and <code>android.hardware.microphone</code>, they:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-1-1] MUST properly implement the <code>REMOTE_SUBMIX</code> audio source so that when an application uses the <code>android.media.AudioRecord</code> API to record from this audio source, it captures a mix of all audio streams except for the following:
+ </p>
+ <ul>
+ <li>
+ <code>AudioManager.STREAM_RING</code>
+ </li>
+ <li>
+ <code>AudioManager.STREAM_ALARM</code>
+ </li>
+ <li>
+ <code>AudioManager.STREAM_NOTIFICATION</code>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <h3 id="5_5_audio_playback">
+ 5.5. Audio Playback
+ </h3>
+ <p>
+ Android includes the support to allow apps to playback audio through the audio output peripheral as defined in section 7.8.2.
+ </p>
+ <h4 id="5_5_1_raw_audio_playback">
+ 5.5.1. Raw Audio Playback
+ </h4>
+ <p>
+ If device implementations declare <code>android.hardware.audio.output</code>, they:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-1-1] MUST allow playback of raw audio content with the following characteristics:
+ </p>
+ <ul>
+ <li>
+ <strong>Format</strong>: Linear PCM, 16-bit, 8-bit, float
+ </li>
+ <li>
+ <strong>Channels</strong>: Mono, Stereo, valid multichannel configurations with up to 8 channels
+ </li>
+ <li>
+ <strong>Sampling rates (in Hz)</strong>:
+ <ul>
+ <li>8000, 11025, 16000, 22050, 32000, 44100, 48000 at the channel configurations listed above
+ </li>
+ <li>96000 in mono and stereo
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ SHOULD allow playback of raw audio content with the following characteristics:
+ </p>
+ <ul>
+ <li>
+ <strong>Sampling rates</strong>: 24000, 48000
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <h4 id="5_5_2_audio_effects">
+ 5.5.2. Audio Effects
+ </h4>
+ <p>
+ Android provides an <a href="http://developer.android.com/reference/android/media/audiofx/AudioEffect.html">API for audio effects</a> for device implementations.
+ </p>
+ <p>
+ If device implementations declare the feature <code>android.hardware.audio.output</code>, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support the <code>EFFECT_TYPE_EQUALIZER</code> and <code>EFFECT_TYPE_LOUDNESS_ENHANCER</code> implementations controllable through the AudioEffect subclasses <code>Equalizer</code>, <code>LoudnessEnhancer</code>.
+ </li>
+ <li>[C-1-2] MUST support the visualizer API implementation, controllable through the <code>Visualizer</code> class.
+ </li>
+ <li>[C-1-3] MUST support the <code>EFFECT_TYPE_DYNAMICS_PROCESSING</code> implementation controllable through the AudioEffect subclass <a href="https://developer.android.com/reference/android/media/audiofx/DynamicsProcessing"><code>DynamicsProcessing</code></a>.
+ </li>
+ <li>SHOULD support the <code>EFFECT_TYPE_BASS_BOOST</code>, <code>EFFECT_TYPE_ENV_REVERB</code>, <code>EFFECT_TYPE_PRESET_REVERB</code>, and <code>EFFECT_TYPE_VIRTUALIZER</code> implementations controllable through the <code>AudioEffect</code> sub-classes <code>BassBoost</code>, <code>EnvironmentalReverb</code>, <code>PresetReverb</code>, and <code>Virtualizer</code>.
+ </li>
+ </ul>
+ <h4 id="5_5_3_audio_output_volume">
+ 5.5.3. Audio Output Volume
+ </h4>
+ <p>
+ Automotive device implementations:
+ </p>
+ <ul>
+ <li>SHOULD allow adjusting audio volume separately per each audio stream using the content type or usage as defined by <a href="" title="http://developer.android.com/reference/android/media/AudioAttributes.html">AudioAttributes</a> and car audio usage as publicly defined in <code>android.car.CarAudioManager</code>.
+ </li>
+ </ul>
+ <h3 id="5_6_audio_latency">
+ 5.6. Audio Latency
+ </h3>
+ <p>
+ Audio latency is the time delay as an audio signal passes through a system. Many classes of applications rely on short latencies, to achieve real-time sound effects.
+ </p>
+ <p>
+ For the purposes of this section, use the following definitions:
+ </p>
+ <ul>
+ <li>
+ <strong>output latency</strong>. The interval between when an application writes a frame of PCM-coded data and when the corresponding sound is presented to environment at an on-device transducer or signal leaves the device via a port and can be observed externally.
+ </li>
+ <li>
+ <strong>cold output latency</strong>. The output latency for the first frame, when the audio output system has been idle and powered down prior to the request.
+ </li>
+ <li>
+ <strong>continuous output latency</strong>. The output latency for subsequent frames, after the device is playing audio.
+ </li>
+ <li>
+ <strong>input latency</strong>. The interval between when a sound is presented by environment to device at an on-device transducer or signal enters the device via a port and when an application reads the corresponding frame of PCM-coded data.
+ </li>
+ <li>
+ <strong>lost input</strong>. The initial portion of an input signal that is unusable or unavailable.
+ </li>
+ <li>
+ <strong>cold input latency</strong>. The sum of lost input time and the input latency for the first frame, when the audio input system has been idle and powered down prior to the request.
+ </li>
+ <li>
+ <strong>continuous input latency</strong>. The input latency for subsequent frames, while the device is capturing audio.
+ </li>
+ <li>
+ <strong>cold output jitter</strong>. The variability among separate measurements of cold output latency values.
+ </li>
+ <li>
+ <strong>cold input jitter</strong>. The variability among separate measurements of cold input latency values.
+ </li>
+ <li>
+ <strong>continuous round-trip latency</strong>. The sum of continuous input latency plus continuous output latency plus one buffer period. The buffer period allows time for the app to process the signal and time for the app to mitigate phase difference between input and output streams.
+ </li>
+ <li>
+ <strong>OpenSL ES PCM buffer queue API</strong>. The set of PCM-related <a href="https://developer.android.com/ndk/guides/audio/opensl/index.html">OpenSL ES</a> APIs within <a href="https://developer.android.com/ndk/index.html">Android NDK</a>.
+ </li>
+ <li>
+ <strong>AAudio native audio API</strong>. The set of <a href="https://developer.android.com/ndk/guides/audio/aaudio/aaudio.html">AAudio</a> APIs within <a href="https://developer.android.com/ndk/index.html">Android NDK</a>.
+ </li>
+ <li>
+ <strong>Timestamp</strong>. A pair consisting of a relative frame position within a stream and the estimated time when that frame enters or leaves the audio processing pipeline on the associated endpoint. See also <a href="https://developer.android.com/reference/android/media/AudioTimestamp">AudioTimestamp</a>.
+ </li>
+ </ul>
+ <p>
+ If device implementations declare <code>android.hardware.audio.output</code> they are STRONGLY RECOMMENDED to meet or exceed the following requirements:
+ </p>
+ <ul>
+ <li>[C-SR] Cold output latency of 100 milliseconds or less
+ </li>
+ <li>[C-SR] Continuous output latency of 45 milliseconds or less
+ </li>
+ <li>[C-SR] Minimize the cold output jitter
+ </li>
+ <li>[C-SR] The output timestamp returned by <a href="https://developer.android.com/reference/android/media/AudioTrack.html#getTimestamp(android.media.AudioTimestamp)">AudioTrack.getTimestamp</a> and <code>AAudioStream_getTimestamp</code> is accurate to +/- 1 ms.
+ </li>
+ </ul>
+ <p>
+ If device implementations meet the above requirements, after any initial calibration, when using both the OpenSL ES PCM buffer queue and AAudio native audio APIs, for continuous output latency and cold output latency over at least one supported audio output device, they are:
+ </p>
+ <ul>
+ <li>[C-SR] STRONGLY RECOMMENDED to report low-latency audio by declaring <code>android.hardware.audio.low_latency</code> feature flag.
+ </li>
+ <li>[C-SR] STRONGLY RECOMMENDED to meet the requirements for low-latency audio via the AAudio API.
+ </li>
+ <li>[C-SR] STRONGLY RECOMMENDED to ensure that for streams that return <a href="https://developer.android.com/ndk/guides/audio/aaudio/aaudio#performance-mode"><code>AAUDIO_PERFORMANCE_MODE_LOW_LATENCY</code></a> from <a href="https://developer.android.com/ndk/reference/group/audio#aaudiostream_getperformancemode"><code>AAudioStream_getPerformanceMode()</code></a>, the value returned by <a href="https://developer.android.com/ndk/reference/group/audio#aaudiostream_getframesperburst"><code>AAudioStream_getFramesPerBurst()</code></a> is less than or equal to the value returned by <a href="https://developer.android.com/reference/android/media/AudioManager.html#getProperty%28java.lang.String%29"><code>android.media.AudioManager.getProperty(String)</code></a> for property key <a href="https://developer.android.com/reference/android/media/AudioManager.html#PROPERTY_OUTPUT_FRAMES_PER_BUFFER"><code>AudioManager.PROPERTY_OUTPUT_FRAMES_PER_BUFFER</code></a>.
+ </li>
+ </ul>
+ <p>
+ If device implementations do not meet the requirements for low-latency audio via both the OpenSL ES PCM buffer queue and AAudio native audio APIs, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST NOT report support for low-latency audio.
+ </li>
+ </ul>
+ <p>
+ If device implementations include <code>android.hardware.microphone</code>, they are STRONGLY RECOMMENDED to meet these input audio requirements:
+ </p>
+ <ul>
+ <li>[C-SR] Cold input latency of 100 milliseconds or less.
+ </li>
+ <li>[C-SR] Continuous input latency of 30 milliseconds or less.
+ </li>
+ <li>[C-SR] Continuous round-trip latency of 50 milliseconds or less.
+ </li>
+ <li>[C-SR] Minimize the cold input jitter.
+ </li>
+ <li>[C-SR] Limit the error in input timestamps, as returned by <a href="https://developer.android.com/reference/android/media/AudioRecord.html#getTimestamp(android.media.AudioTimestamp,%20int)">AudioRecord.getTimestamp</a> or <code>AAudioStream_getTimestamp</code>, to +/- 1 ms.
+ </li>
+ </ul>
+ <h3 id="5_7_network_protocols">
+ 5.7. Network Protocols
+ </h3>
+ <p>
+ Device implementations MUST support the <a href="http://developer.android.com/guide/appendix/media-formats.html">media network protocols</a> for audio and video playback as specified in the Android SDK documentation.
+ </p>
+ <p>
+ If device implementations include an audio or a video decoder, they:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-1-1] MUST support all required codecs and container formats in <a href="#5_1_media_codecs">section 5.1</a> over HTTP(S).
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-2] MUST support the media segment formats shown in the Media Segment Formats table below over <a href="http://tools.ietf.org/html/draft-pantos-http-live-streaming-07">HTTP Live Streaming draft protocol, Version 7</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-3] MUST support the following RTP audio video profile and related codecs in the RTSP table below. For exceptions please see the table footnotes in <a href="#5_1_media_codecs">section 5.1</a>.
+ </p>
+ </li>
+ </ul>
+ <p>
+ <strong>Media Segment Formats</strong>
+ </p>
+ <table>
+ <tr>
+ <th>
+ Segment formats
+ </th>
+ <th>
+ Reference(s)
+ </th>
+ <th>
+ Required codec support
+ </th>
+ </tr>
+ <tr id="mp2t">
+ <td>
+ MPEG-2 Transport Stream
+ </td>
+ <td>
+ <a href="http://www.iso.org/iso/catalogue_detail?csnumber=44169">ISO 13818</a>
+ </td>
+ <td>
+ Video codecs:
+ <ul>
+ <li class="table_list">H264 AVC
+ </li>
+ <li class="table_list">MPEG-4 SP
+ </li>
+ <li class="table_list">MPEG-2
+ </li>
+ </ul>See <a href="#5_1_3_video_codecs">section 5.1.3</a> for details on H264 AVC, MPEG2-4 SP,<br>
+ and MPEG-2.
+ <p>
+ Audio codecs:
+ </p>
+ <ul>
+ <li class="table_list">AAC
+ </li>
+ </ul>See <a href="#5_1_1_audio_codecs">section 5.1.1</a> for details on AAC and its variants.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ AAC with ADTS framing and ID3 tags
+ </td>
+ <td>
+ <a href="http://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=43345">ISO 13818-7</a>
+ </td>
+ <td>
+ See <a href="#5_1_1_audio_codecs">section 5.1.1</a> for details on AAC and its variants
+ </td>
+ </tr>
+ <tr>
+ <td>
+ WebVTT
+ </td>
+ <td>
+ <a href="http://dev.w3.org/html5/webvtt/">WebVTT</a>
+ </td>
+ <td></td>
+ </tr>
+ </table>
+ <p>
+ <strong>RTSP (RTP, SDP)</strong>
+ </p>
+ <table>
+ <tr>
+ <th>
+ Profile name
+ </th>
+ <th>
+ Reference(s)
+ </th>
+ <th>
+ Required codec support
+ </th>
+ </tr>
+ <tr>
+ <td>
+ H264 AVC
+ </td>
+ <td>
+ <a href="https://tools.ietf.org/html/rfc6184">RFC 6184</a>
+ </td>
+ <td>
+ See <a href="#5_1_3_video_codecs">section 5.1.3</a> for details on H264 AVC
+ </td>
+ </tr>
+ <tr>
+ <td>
+ MP4A-LATM
+ </td>
+ <td>
+ <a href="https://tools.ietf.org/html/rfc6416">RFC 6416</a>
+ </td>
+ <td>
+ See <a href="#5_1_1_audio_codecs">section 5.1.1</a> for details on AAC and its variants
+ </td>
+ </tr>
+ <tr>
+ <td>
+ H263-1998
+ </td>
+ <td>
+ <a href="https://tools.ietf.org/html/rfc3551">RFC 3551</a><br>
+ <a href="https://tools.ietf.org/html/rfc4629">RFC 4629</a><br>
+ <a href="https://tools.ietf.org/html/rfc2190">RFC 2190</a>
+ </td>
+ <td>
+ See <a href="#5_1_3_video_codecs">section 5.1.3</a> for details on H263
+ </td>
+ </tr>
+ <tr>
+ <td>
+ H263-2000
+ </td>
+ <td>
+ <a href="https://tools.ietf.org/html/rfc4629">RFC 4629</a>
+ </td>
+ <td>
+ See <a href="#5_1_3_video_codecs">section 5.1.3</a> for details on H263
+ </td>
+ </tr>
+ <tr>
+ <td>
+ AMR
+ </td>
+ <td>
+ <a href="https://tools.ietf.org/html/rfc4867">RFC 4867</a>
+ </td>
+ <td>
+ See <a href="#5_1_1_audio_codecs">section 5.1.1</a> for details on AMR-NB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ AMR-WB
+ </td>
+ <td>
+ <a href="https://tools.ietf.org/html/rfc4867">RFC 4867</a>
+ </td>
+ <td>
+ See <a href="#5_1_1_audio_codecs">section 5.1.1</a> for details on AMR-WB
+ </td>
+ </tr>
+ <tr>
+ <td>
+ MP4V-ES
+ </td>
+ <td>
+ <a href="https://tools.ietf.org/html/rfc6416">RFC 6416</a>
+ </td>
+ <td>
+ See <a href="#5_1_3_video_codecs">section 5.1.3</a> for details on MPEG-4 SP
+ </td>
+ </tr>
+ <tr>
+ <td>
+ mpeg4-generic
+ </td>
+ <td>
+ <a href="https://tools.ietf.org/html/rfc3640">RFC 3640</a>
+ </td>
+ <td>
+ See <a href="#5_1_1_audio_codecs">section 5.1.1</a> for details on AAC and its variants
+ </td>
+ </tr>
+ <tr>
+ <td>
+ MP2T
+ </td>
+ <td>
+ <a href="https://tools.ietf.org/html/rfc2250">RFC 2250</a>
+ </td>
+ <td>
+ See <a href="#mp2t">MPEG-2 Transport Stream</a> underneath HTTP Live Streaming for details
+ </td>
+ </tr>
+ </table>
+ <h3 id="5_8_secure_media">
+ 5.8. Secure Media
+ </h3>
+ <p>
+ If device implementations support secure video output and are capable of supporting secure surfaces, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST declare support for <code>Display.FLAG_SECURE</code>.
+ </li>
+ </ul>
+ <p>
+ If device implementations declare support for <code>Display.FLAG_SECURE</code> and support wireless display protocol, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST secure the link with a cryptographically strong mechanism such as HDCP 2.x or higher for the displays connected through wireless protocols such as Miracast.
+ </li>
+ </ul>
+ <p>
+ If device implementations declare support for <code>Display.FLAG_SECURE</code> and support wired external display, they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST support HDCP 1.2 or higher for all external displays connected via a user-accessible wired port.
+ </li>
+ </ul>
+ <h3 id="5_9_musical_instrument_digital_interface_(midi)">
+ 5.9. Musical Instrument Digital Interface (MIDI)
+ </h3>
+ <p>
+ If device implementations report support for feature <code>android.software.midi</code> via the <a href="http://developer.android.com/reference/android/content/pm/PackageManager.html"><code>android.content.pm.PackageManager</code></a> class, they:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-1-1] MUST support MIDI over <em>all</em> MIDI-capable hardware transports for which they provide generic non-MIDI connectivity, where such transports are:
+ </p>
+ <ul>
+ <li>USB host mode, <a href="#7_7_USB">section 7.7</a>
+ </li>
+ <li>USB peripheral mode, <a href="#7_7_USB">section 7.7</a>
+ </li>
+ <li>MIDI over Bluetooth LE acting in central role, <a href="#7_4_3_bluetooth">section 7.4.3</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [C-1-2] MUST support the inter-app MIDI software transport (virtual MIDI devices)
+ </p>
+ </li>
+ </ul>
+ <h3 id="5_10_professional_audio">
+ 5.10. Professional Audio
+ </h3>
+ <p>
+ If device implementations report support for feature <code>android.hardware.audio.pro</code> via the <a href="http://developer.android.com/reference/android/content/pm/PackageManager.html">android.content.pm.PackageManager</a> class, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST report support for feature <code>android.hardware.audio.low_latency</code>.
+ </li>
+ <li>[C-1-2] MUST have the continuous round-trip audio latency, as defined in <a href="#5_6_audio_latency">section 5.6 Audio Latency</a>, MUST be 20 milliseconds or less and SHOULD be 10 milliseconds or less over at least one supported path.
+ </li>
+ <li>[C-1-3] MUST include a USB port(s) supporting USB host mode and USB peripheral mode.
+ </li>
+ <li>[C-1-4] MUST report support for feature <code>android.software.midi</code>.
+ </li>
+ <li>[C-1-5] MUST meet latencies and USB audio requirements using both the <a href="https://developer.android.com/ndk/guides/audio/opensl-for-android.html">OpenSL ES</a> PCM buffer queue and <a href="https://developer.android.com/ndk/guides/audio/aaudio/aaudio.html">AAudio native audio</a> APIs.
+ </li>
+ <li>[SR] Are STRONGLY RECOMMENDED to provide a consistent level of CPU performance while audio is active and CPU load is varying. This should be tested using <a href="https://github.com/googlesamples/android-audio-high-performance/tree/master/SimpleSynth">SimpleSynth</a> commit <a href="https://github.com/googlesamples/android-audio-high-performance/commit/1bd6391f8ba9512f9f8798e979bc55b899f856d1">1bd6391</a>. The SimpleSynth app needs to be run with below parameters and achieve zero underruns after 10 minutes:
+ <ul>
+ <li>Work cycles: 200,000
+ </li>
+ <li>Variable load: ON (this will switch between 100% and 10% of the work cycles value every 2 seconds and is designed to test CPU governor behavior)
+ </li>
+ <li>Stabilized load: OFF
+ </li>
+ </ul>
+ </li>
+ <li>SHOULD minimize audio clock inaccuracy and drift relative to standard time.
+ </li>
+ <li>SHOULD minimize audio clock drift relative to the CPU <code>CLOCK_MONOTONIC</code> when both are active.
+ </li>
+ <li>SHOULD minimize audio latency over on-device transducers.
+ </li>
+ <li>SHOULD minimize audio latency over USB digital audio.
+ </li>
+ <li>SHOULD document audio latency measurements over all paths.
+ </li>
+ <li>SHOULD minimize jitter in audio buffer completion callback entry times, as this affects usable percentage of full CPU bandwidth by the callback.
+ </li>
+ <li>SHOULD provide zero audio underruns (output) or overruns (input) under normal use at reported latency.
+ </li>
+ <li>SHOULD provide zero inter-channel latency difference.
+ </li>
+ <li>SHOULD minimize MIDI mean latency over all transports.
+ </li>
+ <li>SHOULD minimize MIDI latency variability under load (jitter) over all transports.
+ </li>
+ <li>SHOULD provide accurate MIDI timestamps over all transports.
+ </li>
+ <li>SHOULD minimize audio signal noise over on-device transducers, including the period immediately after cold start.
+ </li>
+ <li>SHOULD provide zero audio clock difference between the input and output sides of corresponding end-points, when both are active. Examples of corresponding end-points include the on-device microphone and speaker, or the audio jack input and output.
+ </li>
+ <li>SHOULD handle audio buffer completion callbacks for the input and output sides of corresponding end-points on the same thread when both are active, and enter the output callback immediately after the return from the input callback. Or if it is not feasible to handle the callbacks on the same thread, then enter the output callback shortly after entering the input callback to permit the application to have a consistent timing of the input and output sides.
+ </li>
+ <li>SHOULD minimize the phase difference between HAL audio buffering for the input and output sides of corresponding end-points.
+ </li>
+ <li>SHOULD minimize touch latency.
+ </li>
+ <li>SHOULD minimize touch latency variability under load (jitter).
+ </li>
+ <li>SHOULD have a latency from touch input to audio output of less than or equal to 40 ms.
+ </li>
+ </ul>
+ <p>
+ If device implementations meet all of the above requirements, they:
+ </p>
+ <ul>
+ <li>[SR] STRONGLY RECOMMENDED to report support for feature <code>android.hardware.audio.pro</code> via the <a href="http://developer.android.com/reference/android/content/pm/PackageManager.html"><code>android.content.pm.PackageManager</code></a> class.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a 4 conductor 3.5mm audio jack, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST have the continuous round-trip audio latency to be 20 milliseconds or less over the audio jack path.
+ </li>
+ <li>[SR] STRONGLY RECOMMENDED to comply with section <a href="https://source.android.com/devices/accessories/headset/jack-headset-spec">Mobile device (jack) specifications</a> of the <a href="https://source.android.com/devices/accessories/headset/plug-headset-spec">Wired Audio Headset Specification (v1.1)</a>.
+ </li>
+ <li>The continuous round-trip audio latency SHOULD be 10 milliseconds or less over the audio jack path.
+ </li>
+ </ul>
+ <p>
+ If device implementations omit a 4 conductor 3.5mm audio jack and include a USB port(s) supporting USB host mode, they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST implement the USB audio class.
+ </li>
+ <li>[C-3-2] MUST have a continuous round-trip audio latency of 20 milliseconds or less over the USB host mode port using USB audio class.
+ </li>
+ <li>The continuous round-trip audio latency SHOULD be 10 milliseconds or less over the USB host mode port using USB audio class.
+ </li>
+ </ul>
+ <p>
+ If device implementations include an HDMI port, they:
+ </p>
+ <ul>
+ <li>[C-4-1] MUST support output in stereo and eight channels at 20-bit or 24-bit depth and 192 kHz without bit-depth loss or resampling, in at least one configuration.
+ </li>
+ </ul>
+ <h3 id="5_11_capture_for_unprocessed">
+ 5.11. Capture for Unprocessed
+ </h3>
+ <p>
+ Android includes support for recording of unprocessed audio via the <code>android.media.MediaRecorder.AudioSource.UNPROCESSED</code> audio source. In OpenSL ES, it can be accessed with the record preset <code>SL_ANDROID_RECORDING_PRESET_UNPROCESSED</code>.
+ </p>
+ <p>
+ If device implementations intent to support unprocessed audio source and make it available to third-party apps, they:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-1-1] MUST report the support through the <code>android.media.AudioManager</code> property <a href="http://developer.android.com/reference/android/media/AudioManager.html#PROPERTY_SUPPORT_AUDIO_SOURCE_UNPROCESSED">PROPERTY_SUPPORT_AUDIO_SOURCE_UNPROCESSED</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-2] MUST exhibit approximately flat amplitude-versus-frequency characteristics in the mid-frequency range: specifically ±10dB from 100 Hz to 7000 Hz for each and every microphone used to record the unprocessed audio source.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-3] MUST exhibit amplitude levels in the low frequency range: specifically from ±20 dB from 5 Hz to 100 Hz compared to the mid-frequency range for each and every microphone used to record the unprocessed audio source.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-4] MUST exhibit amplitude levels in the high frequency range: specifically from ±30 dB from 7000 Hz to 22 KHz compared to the mid-frequency range for each and every microphone used to record the unprocessed audio source.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-5] MUST set audio input sensitivity such that a 1000 Hz sinusoidal tone source played at 94 dB Sound Pressure Level (SPL) yields a response with RMS of 520 for 16 bit-samples (or -36 dB Full Scale for floating point/double precision samples) for each and every microphone used to record the unprocessed audio source.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-6] MUST have a signal-to-noise ratio (SNR) at 60 dB or higher for each and every microphone used to record the unprocessed audio source. (whereas the SNR is measured as the difference between 94 dB SPL and equivalent SPL of self noise, A-weighted).
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-7] MUST have a total harmonic distortion (THD) less than be less than 1% for 1 kHZ at 90 dB SPL input level at each and every microphone used to record the unprocessed audio source.
+ </p>
+ </li>
+ <li>
+ <p>
+ MUST not have any other signal processing (e.g. Automatic Gain Control, High Pass Filter, or Echo cancellation) in the path other than a level multiplier to bring the level to desired range. In other words:
+ </p>
+ </li>
+ <li>[C-1-8] If any signal processing is present in the architecture for any reason, it MUST be disabled and effectively introduce zero delay or extra latency to the signal path.
+ </li>
+ <li>[C-1-9] The level multiplier, while allowed to be on the path, MUST NOT introduce delay or latency to the signal path.
+ </li>
+ </ul>
+ <p>
+ All SPL measurements are made directly next to the microphone under test. For multiple microphone configurations, these requirements apply to each microphone.
+ </p>
+ <p>
+ If device implementations declare <code>android.hardware.microphone</code> but do not support unprocessed audio source, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST return <code>null</code> for the <code>AudioManager.getProperty(PROPERTY_SUPPORT_AUDIO_SOURCE_UNPROCESSED)</code> API method, to properly indicate the lack of support.
+ </li>
+ <li>[SR] are still STRONGLY RECOMMENDED to satisfy as many of the requirements for the signal path for the unprocessed recording source.
+ </li>
+ </ul>
+ <h2 id="6_developer_tools_and_options_compatibility">
+ 6. Developer Tools and Options Compatibility
+ </h2>
+ <h3 id="6_1_developer_tools">
+ 6.1. Developer Tools
+ </h3>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST support the Android Developer Tools provided in the Android SDK.
+ </li>
+ <li>
+ <p>
+ <a href="http://developer.android.com/tools/help/adb.html"><strong>Android Debug Bridge (adb)</strong></a>
+ </p>
+ <ul>
+ <li>[C-0-2] MUST support adb as documented in the Android SDK and the shell commands provided in the AOSP, which can be used by app developers, including <a href="https://source.android.com/devices/input/diagnostics.html"><code>dumpsys</code></a> and <code>cmd stats</code>.
+ </li>
+ <li>[C-0-3] MUST NOT alter the format or the contents of device system events (batterystats , diskstats, fingerprint, graphicsstats, netstats, notification, procstats) logged via the dumpsys command.
+ </li>
+ <li>[C-0-10] MUST record, without omission, and make the following events accessible and available to the <code>cmd stats</code> shell command and the <code>StatsManager</code> System API class.
+ <ul>
+ <li>ActivityForegroundStateChanged
+ </li>
+ <li>AnomalyDetected
+ </li>
+ <li>AppBreadcrumbReported
+ </li>
+ <li>AppCrashOccurred
+ </li>
+ <li>AppStartOccurred
+ </li>
+ <li>BatteryLevelChanged
+ </li>
+ <li>BatterySaverModeStateChanged
+ </li>
+ <li>BleScanResultReceived
+ </li>
+ <li>BleScanStateChanged
+ </li>
+ <li>ChargingStateChanged
+ </li>
+ <li>DeviceIdleModeStateChanged
+ </li>
+ <li>ForegroundServiceStateChanged
+ </li>
+ <li>GpsScanStateChanged
+ </li>
+ <li>JobStateChanged
+ </li>
+ <li>PluggedStateChanged
+ </li>
+ <li>ScheduledJobStateChanged
+ </li>
+ <li>ScreenStateChanged
+ </li>
+ <li>SyncStateChanged
+ </li>
+ <li>SystemElapsedRealtime
+ </li>
+ <li>UidProcessStateChanged
+ </li>
+ <li>WakelockStateChanged
+ </li>
+ <li>WakeupAlarmOccurred
+ </li>
+ <li>WifiLockStateChanged
+ </li>
+ <li>WifiMulticastLockStateChanged
+ </li>
+ <li>WifiScanStateChanged
+ </li>
+ </ul>
+ </li>
+ <li>[C-0-4] MUST have the device-side adb daemon be inactive by default and there MUST be a user-accessible mechanism to turn on the Android Debug Bridge.
+ </li>
+ <li>[C-0-5] MUST support secure adb. Android includes support for secure adb. Secure adb enables adb on known authenticated hosts.
+ </li>
+ <li>
+ <p>
+ [C-0-6] MUST provide a mechanism allowing adb to be connected from a host machine. For example:
+ </p>
+ <ul>
+ <li>Device implementations without a USB port supporting peripheral mode MUST implement adb via local-area network (such as Ethernet or Wi-Fi).
+ </li>
+ <li>MUST provide drivers for Windows 7, 9 and 10, allowing developers to connect to the device using the adb protocol.
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ <a href="http://developer.android.com/tools/debugging/ddms.html"><strong>Dalvik Debug Monitor Service (ddms)</strong></a>
+ </p>
+ <ul>
+ <li>[C-0-7] MUST support all ddms features as documented in the Android SDK. As ddms uses adb, support for ddms SHOULD be inactive by default, but MUST be supported whenever the user has activated the Android Debug Bridge, as above.
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="http://developer.android.com/tools/help/monkey.html"><strong>Monkey</strong></a>
+ <ul>
+ <li>[C-0-8] MUST include the Monkey framework and make it available for applications to use.
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="http://developer.android.com/tools/help/systrace.html"><strong>SysTrace</strong></a>
+ <ul>
+ <li>[C-0-9] MUST support the systrace tool as documented in the Android SDK. Systrace must be inactive by default and there MUST be a user-accessible mechanism to turn on Systrace.
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <p>
+ If device implementations report the support of Vulkan 1.0 or higher via the <code>android.hardware.vulkan.version</code> feature flags, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST provide an affordance for the app developer to enable/disable GPU debug layers.
+ </li>
+ <li>[C-1-2] MUST, when the GPU debug layers are enabled, enumerate layers in libraries provided by external tools (i.e. not part of the platform or application package) found in debuggable applications' base directory to support <a href="https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkEnumerateInstanceLayerProperties.html">vkEnumerateInstanceLayerProperties()</a> and <a href="https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkCreateInstance.html">vkCreateInstance()</a> API methods.
+ </li>
+ </ul>
+ <h3 id="6_2_developer_options">
+ 6.2. Developer Options
+ </h3>
+ <p>
+ Android includes support for developers to configure application development-related settings.
+ </p>
+ <p>
+ Device implementations MUST provide a consistent experience for Developer Options, they:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST honor the <a href="http://developer.android.com/reference/android/provider/Settings.html#ACTION_APPLICATION_DEVELOPMENT_SETTINGS">android.settings.APPLICATION_DEVELOPMENT_SETTINGS</a> intent to show application development-related settings. The upstream Android implementation hides the Developer Options menu by default and enables users to launch Developer Options after pressing seven (7) times on the <strong>Settings</strong> > <strong>About Device</strong> > <strong>Build Number</strong> menu item.
+ </li>
+ <li>[C-0-2] MUST hide Developer Options by default.
+ </li>
+ <li>[C-0-3] MUST provide a clear mechanism that does not give preferential treatment to one third-party app as opposed to another to enable Developer Options. MUST provide a public visible document or website that describes how to enable Developer Options. This document or website MUST be linkable from the Android SDK documents.
+ </li>
+ <li>SHOULD have an ongoing visual notification to the user when Developer Options is enabled and the safety of the user is of concern.
+ </li>
+ <li>MAY temporarily limit access to the Developer Options menu, by visually hiding or disabling the menu, to prevent distraction for scenarios where the safety of the user is of concern.
+ </li>
+ </ul>
+ <h2 id="7_hardware_compatibility">
+ 7. Hardware Compatibility
+ </h2>
+ <p>
+ If a device includes a particular hardware component that has a corresponding API for third-party developers:
+ </p>
+ <ul>
+ <li>[C-0-1] The device implementation MUST implement that API as described in the Android SDK documentation.
+ </li>
+ </ul>
+ <p>
+ If an API in the SDK interacts with a hardware component that is stated to be optional and the device implementation does not possess that component:
+ </p>
+ <ul>
+ <li>[C-0-2] Complete class definitions (as documented by the SDK) for the component APIs MUST still be presented.
+ </li>
+ <li>[C-0-3] The API’s behaviors MUST be implemented as no-ops in some reasonable fashion.
+ </li>
+ <li>[C-0-4] API methods MUST return null values where permitted by the SDK documentation.
+ </li>
+ <li>[C-0-5] API methods MUST return no-op implementations of classes where null values are not permitted by the SDK documentation.
+ </li>
+ <li>[C-0-6] API methods MUST NOT throw exceptions not documented by the SDK documentation.
+ </li>
+ <li>[C-0-7] Device implementations MUST consistently report accurate hardware configuration information via the <code>getSystemAvailableFeatures()</code> and <code>hasSystemFeature(String)</code> methods on the <a href="http://developer.android.com/reference/android/content/pm/PackageManager.html">android.content.pm.PackageManager</a> class for the same build fingerprint.
+ </li>
+ </ul>
+ <p>
+ A typical example of a scenario where these requirements apply is the telephony API: Even on non-phone devices, these APIs must be implemented as reasonable no-ops.
+ </p>
+ <h3 id="7_1_display_and_graphics">
+ 7.1. Display and Graphics
+ </h3>
+ <p>
+ Android includes facilities that automatically adjust application assets and UI layouts appropriately for the device to ensure that third-party applications run well on a <a href="http://developer.android.com/guide/practices/screens_support.html">variety of hardware configurations</a>. Devices MUST properly implement these APIs and behaviors, as detailed in this section.
+ </p>
+ <p>
+ The units referenced by the requirements in this section are defined as follows:
+ </p>
+ <ul>
+ <li>
+ <strong>physical diagonal size</strong>. The distance in inches between two opposing corners of the illuminated portion of the display.
+ </li>
+ <li>
+ <strong>dots per inch (dpi)</strong>. The number of pixels encompassed by a linear horizontal or vertical span of 1”. Where dpi values are listed, both horizontal and vertical dpi must fall within the range.
+ </li>
+ <li>
+ <strong>aspect ratio</strong>. The ratio of the pixels of the longer dimension to the shorter dimension of the screen. For example, a display of 480x854 pixels would be 854/480 = 1.779, or roughly “16:9”.
+ </li>
+ <li>
+ <strong>density-independent pixel (dp)</strong>. The virtual pixel unit normalized to a 160 dpi screen, calculated as: pixels = dps * (density/160).
+ </li>
+ </ul>
+ <h4 id="7_1_1_screen_configuration">
+ 7.1.1. Screen Configuration
+ </h4>
+ <h5 id="7_1_1_1_screen_size_and_shape">
+ 7.1.1.1. Screen Size and Shape
+ </h5>
+ <p>
+ The Android UI framework supports a variety of different logical screen layout sizes, and allows applications to query the current configuration's screen layout size via <code>Configuration.screenLayout</code> with the <code>SCREENLAYOUT_SIZE_MASK</code> and <code>Configuration.smallestScreenWidthDp</code>.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-0-1] MUST report the correct layout size for the <code>Configuration.screenLayout</code> as defined in the Android SDK documentation. Specifically, device implementations MUST report the correct logical density-independent pixel (dp) screen dimensions as below:
+ </p>
+ <ul>
+ <li>Devices with the <code>Configuration.uiMode</code> set as any value other than UI_MODE_TYPE_WATCH, and reporting a <code>small</code> size for the <code>Configuration.screenLayout</code>, MUST have at least 426 dp x 320 dp.
+ </li>
+ <li>Devices reporting a <code>normal</code> size for the <code>Configuration.screenLayout</code>, MUST have at least 480 dp x 320 dp.
+ </li>
+ <li>Devices reporting a <code>large</code> size for the <code>Configuration.screenLayout</code>, MUST have at least 640 dp x 480 dp.
+ </li>
+ <li>Devices reporting a <code>xlarge</code> size for the <code>Configuration.screenLayout</code>, MUST have at least 960 dp x 720 dp.
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [C-0-2] MUST correctly honor applications' stated support for screen sizes through the <a href="https://developer.android.com/guide/topics/manifest/supports-screens-element.html"><<code>supports-screens</code>></a> attribute in the AndroidManifest.xml, as described in the Android SDK documentation.
+ </p>
+ </li>
+ <li>
+ <p>
+ MAY have a display with rounded corners.
+ </p>
+ </li>
+ </ul>
+ <p>
+ If device implementations support <code>UI_MODE_TYPE_NORMAL</code> and include a display with rounded corners, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST ensure that the radius of the rounded corners is less than or equal to 32 dp.
+ </li>
+ <li>SHOULD include user affordance to switch to the display mode with the rectangular corners.
+ </li>
+ </ul>
+ <h5 id="7_1_1_2_screen_aspect_ratio">
+ 7.1.1.2. Screen Aspect Ratio
+ </h5>
+ <p>
+ While there is no restriction to the screen aspect ratio value of the physical screen display, the screen aspect ratio of the logical display that third-party apps are rendered within, as can be derived from the height and width values reported through the <a href="https://developer.android.com/reference/android/view/Display.html"><code>view.Display</code></a> APIs and <a href="https://developer.android.com/reference/android/content/res/Configuration.html">Configuration</a> API, MUST meet the following requirements:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-0-1] Device implementations with the <code>Configuration.uiMode</code> set as <code>UI_MODE_TYPE_NORMAL</code> MUST have an aspect ratio value between 1.3333 (4:3) and 1.86 (roughly 16:9), unless the app can be deemed as ready to be stretched longer by meeting one of the following conditions:
+ </p>
+ <ul>
+ <li>The app has declared that it supports a larger screen aspect ratio through the <a href="https://developer.android.com/guide/practices/screens&lowbar;support.html#MaxAspectRatio"><code>android.max_aspect</code></a> metadata value.
+ </li>
+ <li>The app declares it is resizeable via the <a href="https://developer.android.com/guide/topics/ui/multi-window.html#configuring">android:resizeableActivity</a> attribute.
+ </li>
+ <li>The app is targeting API level 24 or higher and does not declare a <a href="https://developer.android.com/reference/android/R.attr.html#maxAspectRatio"><code>android:MaxAspectRatio</code></a> that would restrict the allowed aspect ratio.
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [C-0-2] Device implementations with the <code>Configuration.uiMode</code> set as <code>UI_MODE_TYPE_WATCH</code> MUST have an aspect ratio value set as 1.0 (1:1).
+ </p>
+ </li>
+ </ul>
+ <h5 id="7_1_1_3_screen_density">
+ 7.1.1.3. Screen Density
+ </h5>
+ <p>
+ The Android UI framework defines a set of standard logical densities to help application developers target application resources.
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-0-1] By default, device implementations MUST report only one of the following logical Android framework densities through the <a href="https://developer.android.com/reference/android/util/DisplayMetrics.html#DENSITY_DEVICE_STABLE">DENSITY_DEVICE_STABLE</a> API and this value MUST NOT change at any time; however, the device MAY report a different arbitrary density according to the display configuration changes made by the user (for example, display size) set after initial boot.
+ </p>
+ <ul>
+ <li>120 dpi (ldpi)
+ </li>
+ <li>160 dpi (mdpi)
+ </li>
+ <li>213 dpi (tvdpi)
+ </li>
+ <li>240 dpi (hdpi)
+ </li>
+ <li>260 dpi (260dpi)
+ </li>
+ <li>280 dpi (280dpi)
+ </li>
+ <li>300 dpi (300dpi)
+ </li>
+ <li>320 dpi (xhdpi)
+ </li>
+ <li>340 dpi (340dpi)
+ </li>
+ <li>360 dpi (360dpi)
+ </li>
+ <li>400 dpi (400dpi)
+ </li>
+ <li>420 dpi (420dpi)
+ </li>
+ <li>480 dpi (xxhdpi)
+ </li>
+ <li>560 dpi (560dpi)
+ </li>
+ <li>640 dpi (xxxhdpi)
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ Device implementations SHOULD define the standard Android framework density that is numerically closest to the physical density of the screen, unless that logical density pushes the reported screen size below the minimum supported. If the standard Android framework density that is numerically closest to the physical density results in a screen size that is smaller than the smallest supported compatible screen size (320 dp width), device implementations SHOULD report the next lowest standard Android framework density.
+ </p>
+ </li>
+ </ul>
+ <p>
+ If there is an affordance to change the display size of the device:
+ </p>
+ <ul>
+ <li>[C-1-1] The display size MUST NOT be scaled any larger than 1.5 times the native density or produce an effective minimum screen dimension smaller than 320dp (equivalent to resource qualifier sw320dp), whichever comes first.
+ </li>
+ <li>[C-1-2] Display size MUST NOT be scaled any smaller than 0.85 times the native density.
+ </li>
+ <li>To ensure good usability and consistent font sizes, it is RECOMMENDED that the following scaling of Native Display options be provided (while complying with the limits specified above)
+ </li>
+ <li>Small: 0.85x
+ </li>
+ <li>Default: 1x (Native display scale)
+ </li>
+ <li>Large: 1.15x
+ </li>
+ <li>Larger: 1.3x
+ </li>
+ <li>Largest 1.45x
+ </li>
+ </ul>
+ <h4 id="7_1_2_display_metrics">
+ 7.1.2. Display Metrics
+ </h4>
+ <p>
+ If device implementations include a screen or video output, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST report correct values for all display metrics defined in the <a href="https://developer.android.com/reference/android/util/DisplayMetrics.html"><code>android.util.DisplayMetrics</code></a> API.
+ </li>
+ </ul>
+ <p>
+ If device implementations does not include an embedded screen or video output, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST report reasonable values for all display metrics defined in the <a href="https://developer.android.com/reference/android/util/DisplayMetrics.html"><code>android.util.DisplayMetrics</code></a> API for the emulated default <code>view.Display</code>.
+ </li>
+ </ul>
+ <h4 id="7_1_3_screen_orientation">
+ 7.1.3. Screen Orientation
+ </h4>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST report which screen orientations they support (<code>android.hardware.screen.portrait</code> and/or <code>android.hardware.screen.landscape</code>) and MUST report at least one supported orientation. For example, a device with a fixed orientation landscape screen, such as a television or laptop, SHOULD only report <code>android.hardware.screen.landscape</code>.
+ </li>
+ <li>[C-0-2] MUST report the correct value for the device’s current orientation, whenever queried via the <code>android.content.res.Configuration.orientation</code>, <code>android.view.Display.getOrientation()</code>, or other APIs.
+ </li>
+ </ul>
+ <p>
+ If device implementations support both screen orientations, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support dynamic orientation by applications to either portrait or landscape screen orientation. That is, the device must respect the application’s request for a specific screen orientation.
+ </li>
+ <li>[C-1-2] MUST NOT change the reported screen size or density when changing orientation.
+ </li>
+ <li>MAY select either portrait or landscape orientation as the default.
+ </li>
+ </ul>
+ <h4 id="7_1_4_2d_and_3d_graphics_acceleration">
+ 7.1.4. 2D and 3D Graphics Acceleration
+ </h4>
+ <h5 id="7_1_4_1_opengl_es">
+ 7.1.4.1 OpenGL ES
+ </h5>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST correctly identify the supported OpenGL ES versions (1.1, 2.0, 3.0, 3.1, 3.2) through the managed APIs (such as via the <code>GLES10.getString()</code> method) and the native APIs.
+ </li>
+ <li>[C-0-2] MUST include the support for all the corresponding managed APIs and native APIs for every OpenGL ES versions they identified to support.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a screen or video output, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support both OpenGL ES 1.1 and 2.0, as embodied and detailed in the <a href="https://developer.android.com/guide/topics/graphics/opengl.html">Android SDK documentation</a>.
+ </li>
+ <li>[SR] are STRONGLY RECOMMENDED to support OpenGL ES 3.1.
+ </li>
+ <li>SHOULD support OpenGL ES 3.2.
+ </li>
+ </ul>
+ <p>
+ If device implementations support any of the OpenGL ES versions, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST report via the OpenGL ES managed APIs and native APIs any other OpenGL ES extensions they have implemented, and conversely MUST NOT report extension strings that they do not support.
+ </li>
+ <li>[C-2-2] MUST support the <code>EGL_KHR_image</code>, <code>EGL_KHR_image_base</code>, <code>EGL_ANDROID_image_native_buffer</code>, <code>EGL_ANDROID_get_native_client_buffer</code>, <code>EGL_KHR_wait_sync</code>, <code>EGL_KHR_get_all_proc_addresses</code>, <code>EGL_ANDROID_presentation_time</code>, <code>EGL_KHR_swap_buffers_with_damage</code> and <code>EGL_ANDROID_recordable</code> extensions.
+ </li>
+ <li>[SR] are STRONGLY RECOMMENDED to support EGL_KHR_partial_update.
+ </li>
+ <li>SHOULD accurately report via the <code>getString()</code> method, any texture compression format that they support, which is typically vendor-specific.
+ </li>
+ </ul>
+ <p>
+ If device implementations declare support for OpenGL ES 3.0, 3.1, or 3.2, they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST export the corresponding function symbols for these versions in addition to the OpenGL ES 2.0 function symbols in the libGLESv2.so library.
+ </li>
+ </ul>
+ <p>
+ If device implementations support OpenGL ES 3.2, they:
+ </p>
+ <ul>
+ <li>[C-4-1] MUST support the OpenGL ES Android Extension Pack in its entirety.
+ </li>
+ </ul>
+ <p>
+ If device implementations support the OpenGL ES <a href="https://developer.android.com/reference/android/opengl/GLES31Ext.html">Android Extension Pack</a> in its entirety, they:
+ </p>
+ <ul>
+ <li>[C-5-1] MUST identify the support through the <code>android.hardware.opengles.aep</code> feature flag.
+ </li>
+ </ul>
+ <p>
+ If device implementations expose support for the <code>EGL_KHR_mutable_render_buffer</code> extension, they:
+ </p>
+ <ul>
+ <li>[C-6-1] MUST also support the <code>EGL_ANDROID_front_buffer_auto_refresh</code> extension.
+ </li>
+ </ul>
+ <h5 id="7_1_4_2_vulkan">
+ 7.1.4.2 Vulkan
+ </h5>
+ <p>
+ Android includes support for <a href="https://www.khronos.org/registry/vulkan/specs/1.0-wsi&lowbarextensions/xhtml/vkspec.html">Vulkan</a> , a low-overhead, cross-platform API for high-performance 3D graphics.
+ </p>
+ <p>
+ If device implementations support OpenGL ES 3.1, they:
+ </p>
+ <ul>
+ <li>[SR] Are STRONGLY RECOMMENDED to include support for Vulkan 1.1.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a screen or video output, they:
+ </p>
+ <ul>
+ <li>SHOULD include support for Vulkan 1.1.
+ </li>
+ </ul>
+ <p>
+ If device implementations include support for Vulkan 1.0, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST report the correct integer value with the <code>android.hardware.vulkan.level</code> and <code>android.hardware.vulkan.version</code> feature flags.
+ </li>
+ <li>[C-1-2] MUST enumerate, at least one <code>VkPhysicalDevice</code> for the Vulkan native API <a href="https://www.khronos.org/registry/vulkan/specs/1.0/man/html/vkEnumeratePhysicalDevices.html"><code>vkEnumeratePhysicalDevices()</code></a> .
+ </li>
+ <li>[C-1-3] MUST fully implement the Vulkan 1.0 APIs for each enumerated <code>VkPhysicalDevice</code>.
+ </li>
+ <li>[C-1-4] MUST enumerate layers, contained in native libraries named as <code>libVkLayer*.so</code> in the application package’s native library directory, through the Vulkan native APIs <a href="https://www.khronos.org/registry/vulkan/specs/1.0/man/html/vkEnumerateInstanceLayerProperties.html"><code>vkEnumerateInstanceLayerProperties()</code></a> and <a href="https://www.khronos.org/registry/vulkan/specs/1.0/man/html/vkEnumerateDeviceLayerProperties.html"><code>vkEnumerateDeviceLayerProperties()</code></a> .
+ </li>
+ <li>[C-1-5] MUST NOT enumerate layers provided by libraries outside of the application package, or provide other ways of tracing or intercepting the Vulkan API, unless the application has the <code>android:debuggable</code> attribute set as <code>true</code>.
+ </li>
+ <li>[C-1-6] MUST report all extension strings that they do support via the Vulkan native APIs , and conversely MUST NOT report extension strings that they do not correctly support.
+ </li>
+ <li>[C-1-7] MUST support the VK_KHR_surface, VK_KHR_android_surface, VK_KHR_swapchain, and VK_KHR_incremental_present extensions.
+ </li>
+ </ul>
+ <p>
+ If device implementations do not include support for Vulkan 1.0, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST NOT declare any of the Vulkan feature flags (e.g. <code>android.hardware.vulkan.level</code>, <code>android.hardware.vulkan.version</code>).
+ </li>
+ <li>[C-2-2] MUST NOT enumerate any <code>VkPhysicalDevice</code> for the Vulkan native API <code>vkEnumeratePhysicalDevices()</code>.
+ </li>
+ </ul>
+ <p>
+ If device implementations include support for Vulkan 1.1, they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST expose support for the <code>SYNC_FD</code> external semaphore and handle types.
+ </li>
+ <li>[SR] Are STRONGLY RECOMMENDED to support the <code>VK_ANDROID_external_memory_android_hardware_buffer</code> extension.
+ </li>
+ </ul>
+ <h5 id="7_1_4_3_renderscript">
+ 7.1.4.3 RenderScript
+ </h5>
+ <ul>
+ <li>[C-0-1] Device implementations MUST support <a href="http://developer.android.com/guide/topics/renderscript/">Android RenderScript</a>, as detailed in the Android SDK documentation.
+ </li>
+ </ul>
+ <h5 id="7_1_4_4_2d_graphics_acceleration">
+ 7.1.4.4 2D Graphics Acceleration
+ </h5>
+ <p>
+ Android includes a mechanism for applications to declare that they want to enable hardware acceleration for 2D graphics at the Application, Activity, Window, or View level through the use of a manifest tag <a href="http://developer.android.com/guide/topics/graphics/hardware-accel.html">android:hardwareAccelerated</a> or direct API calls.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST enable hardware acceleration by default, and MUST disable hardware acceleration if the developer so requests by setting android:hardwareAccelerated="false” or disabling hardware acceleration directly through the Android View APIs.
+ </li>
+ <li>[C-0-2] MUST exhibit behavior consistent with the Android SDK documentation on <a href="http://developer.android.com/guide/topics/graphics/hardware-accel.html">hardware acceleration</a>.
+ </li>
+ </ul>
+ <p>
+ Android includes a TextureView object that lets developers directly integrate hardware-accelerated OpenGL ES textures as rendering targets in a UI hierarchy.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-3] MUST support the TextureView API, and MUST exhibit consistent behavior with the upstream Android implementation.
+ </li>
+ </ul>
+ <h5 id="7_1_4_5_wide-gamut_displays">
+ 7.1.4.5 Wide-gamut Displays
+ </h5>
+ <p>
+ If device implementations claim support for wide-gamut displays through <a href="https://developer.android.com/reference/android/content/res/Configuration.html#isScreenWideColorGamut%28%29"><code>Configuration.isScreenWideColorGamut()</code></a> , they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST have a color-calibrated display.
+ </li>
+ <li>[C-1-2] MUST have a display whose gamut covers the sRGB color gamut entirely in CIE 1931 xyY space.
+ </li>
+ <li>[C-1-3] MUST have a display whose gamut has an area of at least 90% of DCI-P3 in CIE 1931 xyY space.
+ </li>
+ <li>[C-1-4] MUST support OpenGL ES 3.1 or 3.2 and report it properly.
+ </li>
+ <li>[C-1-5] MUST advertise support for the <code>EGL_KHR_no_config_context</code>, <code>EGL_EXT_pixel_format_float</code>, <code>EGL_KHR_gl_colorspace</code>, <code>EGL_EXT_gl_colorspace_scrgb</code>, <code>EGL_EXT_gl_colorspace_scrgb_linear</code>, <code>EGL_EXT_gl_colorspace_display_p3</code>, and <code>EGL_KHR_gl_colorspace_display_p3</code> extensions.
+ </li>
+ <li>[SR] Are STRONGLY RECOMMENDED to support <code>GL_EXT_sRGB</code>.
+ </li>
+ </ul>
+ <p>
+ Conversely, if device implementations do not support wide-gamut displays, they:
+ </p>
+ <ul>
+ <li>[C-2-1] SHOULD cover 100% or more of sRGB in CIE 1931 xyY space, although the screen color gamut is undefined.
+ </li>
+ </ul>
+ <h4 id="7_1_5_legacy_application_compatibility_mode">
+ 7.1.5. Legacy Application Compatibility Mode
+ </h4>
+ <p>
+ Android specifies a “compatibility mode” in which the framework operates in a 'normal' screen size equivalent (320dp width) mode for the benefit of legacy applications not developed for old versions of Android that pre-date screen-size independence.
+ </p>
+ <h4 id="7_1_6_screen_technology">
+ 7.1.6. Screen Technology
+ </h4>
+ <p>
+ The Android platform includes APIs that allow applications to render rich graphics to the display. Devices MUST support all of these APIs as defined by the Android SDK unless specifically allowed in this document.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST support displays capable of rendering 16-bit color graphics.
+ </li>
+ <li>SHOULD support displays capable of 24-bit color graphics.
+ </li>
+ <li>[C-0-2] MUST support displays capable of rendering animations.
+ </li>
+ <li>[C-0-3] MUST use the display technology that have a pixel aspect ratio (PAR) between 0.9 and 1.15. That is, the pixel aspect ratio MUST be near square (1.0) with a 10 ~ 15% tolerance.
+ </li>
+ </ul>
+ <h4 id="7_1_7_secondary_displays">
+ 7.1.7. Secondary Displays
+ </h4>
+ <p>
+ Android includes support for secondary display to enable media sharing capabilities and developer APIs for accessing external displays.
+ </p>
+ <p>
+ If device implementations support an external display either via a wired, wireless, or an embedded additional display connection, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST implement the <a href="https://developer.android.com/reference/android/hardware/display/DisplayManager.html"><code>DisplayManager</code></a> system service and API as described in the Android SDK documentation.
+ </li>
+ </ul>
+ <h3 id="7_2_input_devices">
+ 7.2. Input Devices
+ </h3>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST include an input mechanism, such as a <a href="#7_2_4_touchScreen_input">touchscreen</a> or <a href="#7_2_2_non-touch_navigation">non-touch navigation</a>, to navigate between the UI elements.
+ </li>
+ </ul>
+ <h4 id="7_2_1_keyboard">
+ 7.2.1. Keyboard
+ </h4>
+ <p>
+ If device implementations include support for third-party Input Method Editor (IME) applications, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST declare the <a href="https://developer.android.com/reference/android/content/pm/PackageManager.html#FEATURE_INPUT_METHODS"><code>android.software.input_methods</code></a> feature flag.
+ </li>
+ <li>[C-1-2] MUST implement fully <a href="https://developer.android.com/reference/android/view/inputmethod/InputMethodManager.html"><code>Input Management Framework</code></a>
+ </li>
+ <li>[C-1-3] MUST have a preloaded software keyboard.
+ </li>
+ </ul>
+ <p>
+ Device implementations: <em>[C-0-1] MUST NOT include a hardware keyboard that does not match one of the formats specified in <a href="http://developer.android.com/reference/android/content/res/Configuration.html">android.content.res.Configuration.keyboard</a> (QWERTY or 12-key).</em> SHOULD include additional soft keyboard implementations. * MAY include a hardware keyboard.
+ </p>
+ <h4 id="7_2_2_non-touch_navigation">
+ 7.2.2. Non-touch Navigation
+ </h4>
+ <p>
+ Android includes support for d-pad, trackball, and wheel as mechanisms for non-touch navigation.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST report the correct value for <a href="https://developer.android.com/reference/android/content/res/Configuration.html#navigation">android.content.res.Configuration.navigation</a>.
+ </li>
+ </ul>
+ <p>
+ If device implementations lack non-touch navigations, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST provide a reasonable alternative user interface mechanism for the selection and editing of text, compatible with Input Management Engines. The upstream Android open source implementation includes a selection mechanism suitable for use with devices that lack non-touch navigation inputs.
+ </li>
+ </ul>
+ <h4 id="7_2_3_navigation_keys">
+ 7.2.3. Navigation Keys
+ </h4>
+ <p>
+ The <a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_HOME">Home</a>, <a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_APP_SWITCH">Recents</a>, and <a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_BACK">Back</a> functions typically provided via an interaction with a dedicated physical button or a distinct portion of the touch screen, are essential to the Android navigation paradigm and therefore, device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST provide a user affordance to launch installed applications that have an activity with the <code><intent-filter></code> set with <code>ACTION=MAIN</code> and <code>CATEGORY=LAUNCHER</code> or <code>CATEGORY=LEANBACK_LAUNCHER</code> for Television device implementations. The Home function SHOULD be the mechanism for this user affordance.
+ </li>
+ <li>SHOULD provide buttons for the Recents and Back function.
+ </li>
+ </ul>
+ <p>
+ If the Home, Recents, or Back functions are provided, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST be accessible with a single action (e.g. tap, double-click or gesture) when any of them are accessible.
+ </li>
+ <li>[C-1-2] MUST provide a clear indication of which single action would trigger each function. Having a visible icon imprinted on the button, showing a software icon on the navigation bar portion of the screen, or walking the user through a guided step-by-step demo flow during the out-of-box setup experience are examples of such an indication.
+ </li>
+ </ul>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[SR] are STRONGLY RECOMMENDED to not provide the input mechanism for the <a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_BACK">Menu function</a> as it is deprecated in favor of action bar since Android 4.0.
+ </li>
+ </ul>
+ <p>
+ If device implementations provide the Menu function, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST display the action overflow button whenever the action overflow menu popup is not empty and the action bar is visible.
+ </li>
+ <li>[C-2-2] MUST NOT modify the position of the action overflow popup displayed by selecting the overflow button in the action bar, but MAY render the action overflow popup at a modified position on the screen when it is displayed by selecting the Menu function.
+ </li>
+ </ul>
+ <p>
+ If device implementations do not provide the Menu function, for backwards compatibility, they: * [C-3-1] MUST make the Menu function available to applications when <code>targetSdkVersion</code> is less than 10, either by a physical button, a software key, or gestures. This Menu function should be accessible unless hidden together with other navigation functions.
+ </p>
+ <p>
+ If device implementations provide the <a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_ASSIST">Assist function</a>, they: <em>[C-4-1] MUST make the Assist function accessible with a single action (e.g. tap, double-click or gesture) when other navigation keys are accessible.</em> [SR] STRONGLY RECOMMENDED to use long press on HOME function as this designated interaction.
+ </p>
+ <p>
+ If device implementations use a distinct portion of the screen to display the navigation keys, they:
+ </p>
+ <ul>
+ <li>[C-5-1] Navigation keys MUST use a distinct portion of the screen, not available to applications, and MUST NOT obscure or otherwise interfere with the portion of the screen available to applications.
+ </li>
+ <li>[C-5-2] MUST make available a portion of the display to applications that meets the requirements defined in <a href="#7_1_1_screen_configuration">section 7.1.1</a>.
+ </li>
+ <li>[C-5-3] MUST honor the flags set by the app through the <a href="https://developer.android.com/reference/android/view/View.html#setSystemUiVisibility%28int%29"><code>View.setSystemUiVisibility()</code></a> API method, so that this distinct portion of the screen (a.k.a. the navigation bar) is properly hidden away as documented in the SDK.
+ </li>
+ </ul>
+ <h4 id="7_2_4_touchscreen_input">
+ 7.2.4. Touchscreen Input
+ </h4>
+ <p>
+ Android includes support for a variety of pointer input systems, such as touchscreens, touch pads, and fake touch input devices. <a href="https://source.android.com/devices/input/touch-devices">Touchscreen-based device implementations</a> are associated with a display such that the user has the impression of directly manipulating items on screen. Since the user is directly touching the screen, the system does not require any additional affordances to indicate the objects being manipulated.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>SHOULD have a pointer input system of some kind (either mouse-like or touch).
+ </li>
+ <li>SHOULD support fully independently tracked pointers.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a touchscreen (single-touch or better), they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST report <code>TOUCHSCREEN_FINGER</code> for the <a href="https://developer.android.com/reference/android/content/res/Configuration.html#touchscreen"><code>Configuration.touchscreen</code></a> API field.
+ </li>
+ <li>[C-1-2] MUST report the <code>android.hardware.touchscreen</code> and <code>android.hardware.faketouch</code> feature flags.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a touchscreen that can track more than a single touch, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST report the appropriate feature flags <code>android.hardware.touchscreen.multitouch</code>, <code>android.hardware.touchscreen.multitouch.distinct</code>, <code>android.hardware.touchscreen.multitouch.jazzhand</code> corresponding to the type of the specific touchscreen on the device.
+ </li>
+ </ul>
+ <p>
+ If device implementations do not include a touchscreen (and rely on a pointer device only) and meet the fake touch requirements in <a href="#7_2_5_fake_touch_input">section 7.2.5</a>, they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST NOT report any feature flag starting with <code>android.hardware.touchscreen</code> and MUST report only <code>android.hardware.faketouch</code>.
+ </li>
+ </ul>
+ <h4 id="7_2_5_fake_touch_input">
+ 7.2.5. Fake Touch Input
+ </h4>
+ <p>
+ Fake touch interface provides a user input system that approximates a subset of touchscreen capabilities. For example, a mouse or remote control that drives an on-screen cursor approximates touch, but requires the user to first point or focus then click. Numerous input devices like the mouse, trackpad, gyro-based air mouse, gyro-pointer, joystick, and multi-touch trackpad can support fake touch interactions. Android includes the feature constant android.hardware.faketouch, which corresponds to a high-fidelity non-touch (pointer-based) input device such as a mouse or trackpad that can adequately emulate touch-based input (including basic gesture support), and indicates that the device supports an emulated subset of touchscreen functionality.
+ </p>
+ <p>
+ If device implementations do not include a touchscreen but include another pointer input system which they want to make available, they:
+ </p>
+ <ul>
+ <li>SHOULD declare support for the <code>android.hardware.faketouch</code> feature flag.
+ </li>
+ </ul>
+ <p>
+ If device implementations declare support for <code>android.hardware.faketouch</code>, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST report the <a href="http://developer.android.com/reference/android/view/MotionEvent.html">absolute X and Y screen positions</a> of the pointer location and display a visual pointer on the screen.
+ </li>
+ <li>[C-1-2] MUST report touch event with the action code that specifies the state change that occurs on the pointer <a href="http://developer.android.com/reference/android/view/MotionEvent.html">going down or up on the screen</a>.
+ </li>
+ <li>[C-1-3] MUST support pointer down and up on an object on the screen, which allows users to emulate tap on an object on the screen.
+ </li>
+ <li>[C-1-4] MUST support pointer down, pointer up, pointer down then pointer up in the same place on an object on the screen within a time threshold, which allows users to <a href="http://developer.android.com/reference/android/view/MotionEvent.html">emulate double tap</a> on an object on the screen.
+ </li>
+ <li>[C-1-5] MUST support pointer down on an arbitrary point on the screen, pointer move to any other arbitrary point on the screen, followed by a pointer up, which allows users to emulate a touch drag.
+ </li>
+ <li>[C-1-6] MUST support pointer down then allow users to quickly move the object to a different position on the screen and then pointer up on the screen, which allows users to fling an object on the screen.
+ </li>
+ <li>[C-1-7] MUST report <code>TOUCHSCREEN_NOTOUCH</code> for the <a href="https://developer.android.com/reference/android/content/res/Configuration.html#touchscreen"><code>Configuration.touchscreen</code></a> API field.
+ </li>
+ </ul>
+ <p>
+ If device implementations declare support for <code>android.hardware.faketouch.multitouch.distinct</code>, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST declare support for <code>android.hardware.faketouch</code>.
+ </li>
+ <li>[C-2-2] MUST support distinct tracking of two or more independent pointer inputs.
+ </li>
+ </ul>
+ <p>
+ If device implementations declare support for <code>android.hardware.faketouch.multitouch.jazzhand</code>, they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST declare support for <code>android.hardware.faketouch</code>.
+ </li>
+ <li>[C-3-2] MUST support distinct tracking of 5 (tracking a hand of fingers) or more pointer inputs fully independently.
+ </li>
+ </ul>
+ <h4 id="7_2_6_game_controller_support">
+ 7.2.6. Game Controller Support
+ </h4>
+ <h5 id="7_2_6_1_button_mappings">
+ 7.2.6.1. Button Mappings
+ </h5>
+ <p>
+ If device implementations declare the <code>android.hardware.gamepad</code> feature flag, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST have embed a controller or ship with a separate controller in the box, that would provide means to input all the events listed in the below tables.
+ </li>
+ <li>[C-1-2] MUST be capable to map HID events to it's associated Android <code>view.InputEvent</code> constants as listed in the below tables. The upstream Android implementation includes implementation for game controllers that satisfies this requirement.
+ </li>
+ </ul>
+ <table>
+ <tr>
+ <th>
+ Button
+ </th>
+ <th>
+ HID Usage<sup>2</sup>
+ </th>
+ <th>
+ Android Button
+ </th>
+ </tr>
+ <tr>
+ <td>
+ <a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_BUTTON_A">A</a><sup>1</sup>
+ </td>
+ <td>
+ 0x09 0x0001
+ </td>
+ <td>
+ KEYCODE_BUTTON_A (96)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_BUTTON_B">B</a><sup>1</sup>
+ </td>
+ <td>
+ 0x09 0x0002
+ </td>
+ <td>
+ KEYCODE_BUTTON_B (97)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_BUTTON_X">X</a><sup>1</sup>
+ </td>
+ <td>
+ 0x09 0x0004
+ </td>
+ <td>
+ KEYCODE_BUTTON_X (99)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_BUTTON_Y">Y</a><sup>1</sup>
+ </td>
+ <td>
+ 0x09 0x0005
+ </td>
+ <td>
+ KEYCODE_BUTTON_Y (100)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_DPAD_UP">D-pad up</a><sup>1</sup><br>
+ <a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_DPAD_DOWN">D-pad down</a><sup>1</sup>
+ </td>
+ <td>
+ 0x01 0x0039<sup>3</sup>
+ </td>
+ <td>
+ <a href="http://developer.android.com/reference/android/view/MotionEvent.html#AXIS_HAT_Y">AXIS_HAT_Y</a><sup>4</sup>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_DPAD_LEFT">D-pad left</a>1<br>
+ <a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_DPAD_RIGHT">D-pad right</a><sup>1</sup>
+ </td>
+ <td>
+ 0x01 0x0039<sup>3</sup>
+ </td>
+ <td>
+ <a href="http://developer.android.com/reference/android/view/MotionEvent.html#AXIS_HAT_X">AXIS_HAT_X</a><sup>4</sup>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_BUTTON_L1">Left shoulder button</a><sup>1</sup>
+ </td>
+ <td>
+ 0x09 0x0007
+ </td>
+ <td>
+ KEYCODE_BUTTON_L1 (102)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_BUTTON_R1">Right shoulder button</a><sup>1</sup>
+ </td>
+ <td>
+ 0x09 0x0008
+ </td>
+ <td>
+ KEYCODE_BUTTON_R1 (103)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_BUTTON_THUMBL">Left stick click</a><sup>1</sup>
+ </td>
+ <td>
+ 0x09 0x000E
+ </td>
+ <td>
+ KEYCODE_BUTTON_THUMBL (106)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_BUTTON_THUMBR">Right stick click</a><sup>1</sup>
+ </td>
+ <td>
+ 0x09 0x000F
+ </td>
+ <td>
+ KEYCODE_BUTTON_THUMBR (107)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_HOME">Home</a><sup>1</sup>
+ </td>
+ <td>
+ 0x0c 0x0223
+ </td>
+ <td>
+ KEYCODE_HOME (3)
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_BACK">Back</a><sup>1</sup>
+ </td>
+ <td>
+ 0x0c 0x0224
+ </td>
+ <td>
+ KEYCODE_BACK (4)
+ </td>
+ </tr>
+ </table>
+ <p class="table_footnote">
+ 1 <a href="http://developer.android.com/reference/android/view/KeyEvent.html">KeyEvent</a>
+ </p>
+ <p class="table_footnote">
+ 2 The above HID usages must be declared within a Game pad CA (0x01 0x0005).
+ </p>
+ <p class="table_footnote">
+ 3 This usage must have a Logical Minimum of 0, a Logical Maximum of 7, a Physical Minimum of 0, a Physical Maximum of 315, Units in Degrees, and a Report Size of 4. The logical value is defined to be the clockwise rotation away from the vertical axis; for example, a logical value of 0 represents no rotation and the up button being pressed, while a logical value of 1 represents a rotation of 45 degrees and both the up and left keys being pressed.
+ </p>
+ <p class="table_footnote">
+ 4 <a href="http://developer.android.com/reference/android/view/MotionEvent.html">MotionEvent</a>
+ </p>
+ <table>
+ <tr>
+ <th>
+ Analog Controls<sup>1</sup>
+ </th>
+ <th>
+ HID Usage
+ </th>
+ <th>
+ Android Button
+ </th>
+ </tr>
+ <tr>
+ <td>
+ <a href="http://developer.android.com/reference/android/view/MotionEvent.html#AXIS_LTRIGGER">Left Trigger</a>
+ </td>
+ <td>
+ 0x02 0x00C5
+ </td>
+ <td>
+ AXIS_LTRIGGER
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <a href="http://developer.android.com/reference/android/view/MotionEvent.html#AXIS_THROTTLE">Right Trigger</a>
+ </td>
+ <td>
+ 0x02 0x00C4
+ </td>
+ <td>
+ AXIS_RTRIGGER
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <a href="http://developer.android.com/reference/android/view/MotionEvent.html#AXIS_Y">Left Joystick</a>
+ </td>
+ <td>
+ 0x01 0x0030<br>
+ 0x01 0x0031
+ </td>
+ <td>
+ AXIS_X<br>
+ AXIS_Y
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <a href="http://developer.android.com/reference/android/view/MotionEvent.html#AXIS_Z">Right Joystick</a>
+ </td>
+ <td>
+ 0x01 0x0032<br>
+ 0x01 0x0035
+ </td>
+ <td>
+ AXIS_Z<br>
+ AXIS_RZ
+ </td>
+ </tr>
+ </table>
+ <p class="table_footnote">
+ 1 <a href="http://developer.android.com/reference/android/view/MotionEvent.html">MotionEvent</a>
+ </p>
+ <h4 id="7_2_7_remote_control">
+ 7.2.7. Remote Control
+ </h4>
+ <p>
+ See <a href="#2_3_1_hardware">Section 2.3.1</a> for device-specific requirements.
+ </p>
+ <h3 id="7_3_sensors">
+ 7.3. Sensors
+ </h3>
+ <p>
+ If device implementations include a particular sensor type that has a corresponding API for third-party developers, the device implementation MUST implement that API as described in the Android SDK documentation and the Android Open Source documentation on <a href="http://source.android.com/devices/sensors/">sensors</a>.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST accurately report the presence or absence of sensors per the <a href="http://developer.android.com/reference/android/content/pm/PackageManager.html"><code>android.content.pm.PackageManager</code></a> class.
+ </li>
+ <li>[C-0-2] MUST return an accurate list of supported sensors via the <code>SensorManager.getSensorList()</code> and similar methods.
+ </li>
+ <li>[C-0-3] MUST behave reasonably for all other sensor APIs (for example, by returning <code>true</code> or <code>false</code> as appropriate when applications attempt to register listeners, not calling sensor listeners when the corresponding sensors are not present; etc.).
+ </li>
+ </ul>
+ <p>
+ If device implementations include a particular sensor type that has a corresponding API for third-party developers, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST <a href="http://developer.android.com/reference/android/hardware/SensorEvent.html">report all sensor measurements</a> using the relevant International System of Units (metric) values for each sensor type as defined in the Android SDK documentation.
+ </li>
+ <li>[C-1-2] MUST report sensor data with a maximum latency of 100 milliseconds + 2 * sample_time for the case of a sensor streamed with a minimum required latency of 5 ms + 2 * sample_time when the application processor is active. This delay does not include any filtering delays.
+ </li>
+ <li>[C-1-3] MUST report the first sensor sample within 400 milliseconds + 2 * sample_time of the sensor being activated. It is acceptable for this sample to have an accuracy of 0.
+ </li>
+ <li>
+ <p>
+ [SR] SHOULD <a href="http://developer.android.com/reference/android/hardware/SensorEvent.html#timestamp">report the event time</a> in nanoseconds as defined in the Android SDK documentation, representing the time the event happened and synchronized with the SystemClock.elapsedRealtimeNano() clock. Existing and new Android devices are <strong>STRONGLY RECOMMENDED</strong> to meet these requirements so they will be able to upgrade to the future platform releases where this might become a REQUIRED component. The synchronization error SHOULD be below 100 milliseconds.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-4] For any API indicated by the Android SDK documentation to be a <a href="https://source.android.com/devices/sensors/report-modes.html#continuous">continuous sensor</a>, device implementations MUST continuously provide periodic data samples that SHOULD have a jitter below 3%, where jitter is defined as the standard deviation of the difference of the reported timestamp values between consecutive events.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-5] MUST ensure that the sensor event stream MUST NOT prevent the device CPU from entering a suspend state or waking up from a suspend state.
+ </p>
+ </li>
+ <li>When several sensors are activated, the power consumption SHOULD NOT exceed the sum of the individual sensor’s reported power consumption.
+ </li>
+ </ul>
+ <p>
+ The list above is not comprehensive; the documented behavior of the Android SDK and the Android Open Source Documentations on <a href="http://source.android.com/devices/sensors/">sensors</a> is to be considered authoritative.
+ </p>
+ <p>
+ Some sensor types are composite, meaning they can be derived from data provided by one or more other sensors. (Examples include the orientation sensor and the linear acceleration sensor.)
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>SHOULD implement these sensor types, when they include the prerequisite physical sensors as described in <a href="https://source.android.com/devices/sensors/sensor-types.html">sensor types</a>.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a composite sensor, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST implement the sensor as described in the Android Open Source documentation on <a href="https://source.android.com/devices/sensors/sensor-types.html#composite_sensor_type_summary">composite sensors</a>.
+ </li>
+ </ul>
+ <h4 id="7_3_1_accelerometer">
+ 7.3.1. Accelerometer
+ </h4>
+ <ul>
+ <li>Device implementations SHOULD include a 3-axis accelerometer.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a 3-axis accelerometer, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST be able to report events up to a frequency of at least 50 Hz.
+ </li>
+ <li>[C-1-2] MUST implement and report <a href="http://developer.android.com/reference/android/hardware/Sensor.html#TYPE_ACCELEROMETER"><code>TYPE_ACCELEROMETER</code></a> sensor.
+ </li>
+ <li>[C-1-3] MUST comply with the <a href="http://developer.android.com/reference/android/hardware/SensorEvent.html">Android sensor coordinate system</a> as detailed in the Android APIs.
+ </li>
+ <li>[C-1-4] MUST be capable of measuring from freefall up to four times the gravity(4g) or more on any axis.
+ </li>
+ <li>[C-1-5] MUST have a resolution of at least 12-bits.
+ </li>
+ <li>[C-1-6] MUST have a standard deviation no greater than 0.05 m/s^, where the standard deviation should be calculated on a per axis basis on samples collected over a period of at least 3 seconds at the fastest sampling rate.
+ </li>
+ <li>[SR] are <strong>STRONGLY RECOMMENDED</strong> to implement the <code>TYPE_SIGNIFICANT_MOTION</code> composite sensor.
+ </li>
+ <li>[SR] are STRONGLY RECOMMENDED to implement the <code>TYPE_ACCELEROMETER_UNCALIBRATED</code> sensor if online accelerometer calibration is available.
+ </li>
+ <li>SHOULD implement the <code>TYPE_SIGNIFICANT_MOTION</code>, <code>TYPE_TILT_DETECTOR</code>, <code>TYPE_STEP_DETECTOR</code>, <code>TYPE_STEP_COUNTER</code> composite sensors as described in the Android SDK document.
+ </li>
+ <li>SHOULD report events up to at least 200 Hz.
+ </li>
+ <li>SHOULD have a resolution of at least 16-bits.
+ </li>
+ <li>SHOULD be calibrated while in use if the characteristics changes over the life cycle and compensated, and preserve the compensation parameters between device reboots.
+ </li>
+ <li>SHOULD be temperature compensated.
+ </li>
+ <li>SHOULD also implement <a href="https://developer.android.com/reference/android/hardware/Sensor.html#STRING_TYPE_ACCELEROMETER_UNCALIBRATED"><code>TYPE_ACCELEROMETER_UNCALIBRATED</code></a> sensor.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a 3-axis accelerometer and any of the <code>TYPE_SIGNIFICANT_MOTION</code>, <code>TYPE_TILT_DETECTOR</code>, <code>TYPE_STEP_DETECTOR</code>, <code>TYPE_STEP_COUNTER</code> composite sensors are implemented:
+ </p>
+ <ul>
+ <li>[C-2-1] The sum of their power consumption MUST always be less than 4 mW.
+ </li>
+ <li>SHOULD each be below 2 mW and 0.5 mW for when the device is in a dynamic or static condition.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a 3-axis accelerometer and a gyroscope sensor, they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST implement the <code>TYPE_GRAVITY</code> and <code>TYPE_LINEAR_ACCELERATION</code> composite sensors.
+ </li>
+ <li>SHOULD implement the <code>TYPE_GAME_ROTATION_VECTOR</code> composite sensor.
+ </li>
+ <li>[SR] Existing and new Android devices are STRONGLY RECOMMENDED to implement the <code>TYPE_GAME_ROTATION_VECTOR</code> sensor.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a 3-axis accelerometer, a gyroscope sensor and a magnetometer sensor, they:
+ </p>
+ <ul>
+ <li>[C-4-1] MUST implement a <code>TYPE_ROTATION_VECTOR</code> composite sensor.
+ </li>
+ </ul>
+ <h4 id="7_3_2_magnetometer">
+ 7.3.2. Magnetometer
+ </h4>
+ <ul>
+ <li>Device implementations SHOULD include a 3-axis magnetometer (compass).
+ </li>
+ </ul>
+ <p>
+ If device implementations include a 3-axis magnetometer, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST implement the <code>TYPE_MAGNETIC_FIELD</code> sensor.
+ </li>
+ <li>[C-1-2] MUST be able to report events up to a frequency of at least 10 Hz and SHOULD report events up to at least 50 Hz.
+ </li>
+ <li>[C-1-3] MUST comply with the <a href="http://developer.android.com/reference/android/hardware/SensorEvent.html">Android sensor coordinate system</a> as detailed in the Android APIs.
+ </li>
+ <li>[C-1-4] MUST be capable of measuring between -900 µT and +900 µT on each axis before saturating.
+ </li>
+ <li>[C-1-5] MUST have a hard iron offset value less than 700 µT and SHOULD have a value below 200 µT, by placing the magnetometer far from dynamic (current-induced) and static (magnet-induced) magnetic fields.
+ </li>
+ <li>[C-1-6] MUST have a resolution equal or denser than 0.6 µT.
+ </li>
+ <li>[C-1-7] MUST support online calibration and compensation of the hard iron bias, and preserve the compensation parameters between device reboots.
+ </li>
+ <li>[C-1-8] MUST have the soft iron compensation applied—the calibration can be done either while in use or during the production of the device.
+ </li>
+ <li>[C-1-9] MUST have a standard deviation, calculated on a per axis basis on samples collected over a period of at least 3 seconds at the fastest sampling rate, no greater than 1.5 µT; SHOULD have a standard deviation no greater than 0.5 µT.
+ </li>
+ <li>SHOULD implement <code>TYPE_MAGNETIC_FIELD_UNCALIBRATED</code> sensor.
+ </li>
+ <li>[SR] Existing and new Android devices are STRONGLY RECOMMENDED to implement the <code>TYPE_MAGNETIC_FIELD_UNCALIBRATED</code> sensor.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a 3-axis magnetometer, an accelerometer sensor and a gyroscope sensor, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST implement a <code>TYPE_ROTATION_VECTOR</code> composite sensor.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a 3-axis magnetometer, an accelerometer, they:
+ </p>
+ <ul>
+ <li>MAY implement the <code>TYPE_GEOMAGNETIC_ROTATION_VECTOR</code> sensor.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a 3-axis magnetometer, an accelerometer and <code>TYPE_GEOMAGNETIC_ROTATION_VECTOR</code> sensor, they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST consume less than 10 mW.
+ </li>
+ <li>SHOULD consume less than 3 mW when the sensor is registered for batch mode at 10 Hz.
+ </li>
+ </ul>
+ <h4 id="7_3_3_gps">
+ 7.3.3. GPS
+ </h4>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>SHOULD include a GPS/GNSS receiver.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a GPS/GNSS receiver and report the capability to applications through the <code>android.hardware.location.gps</code> feature flag, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support location outputs at a rate of at least 1 Hz when requested via <code>LocationManager#requestLocationUpdate</code>.
+ </li>
+ <li>[C-1-2] MUST be able to determine the location in open-sky conditions (strong signals, negligible multipath, HDOP < 2) within 10 seconds (fast time to first fix), when connected to a 0.5 Mbps or faster data speed internet connection. This requirement is typically met by the use of some form of Assisted or Predicted GPS/GNSS technique to minimize GPS/GNSS lock-on time (Assistance data includes Reference Time, Reference Location and Satellite Ephemeris/Clock).
+ <ul>
+ <li>[C-1-6] After making such a location calculation, device implementations MUST determine its location, in open sky, within 5 seconds, when location requests are restarted, up to an hour after the initial location calculation, even when the subsequent request is made without a data connection, and/or after a power cycle.
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ In open sky conditions after determining the location, while stationary or moving with less than 1 meter per second squared of acceleration:
+ </p>
+ <ul>
+ <li>[C-1-3] MUST be able to determine location within 20 meters, and speed within 0.5 meters per second, at least 95% of the time.
+ </li>
+ <li>[C-1-4] MUST simultaneously track and report via <a href="https://developer.android.com/reference/android/location/GnssStatus.Callback.html#GnssStatus.Callback()'"><code>GnssStatus.Callback</code></a> at least 8 satellites from one constellation.
+ </li>
+ <li>SHOULD be able to simultaneously track at least 24 satellites, from multiple constellations (e.g. GPS + at least one of Glonass, Beidou, Galileo).
+ </li>
+ <li>[C-1-5] MUST report the GNSS technology generation through the test API ‘getGnssYearOfHardware’.
+ </li>
+ <li>[SR] Continue to deliver normal GPS/GNSS location outputs during an emergency phone call.
+ </li>
+ <li>[SR] Report GNSS measurements from all constellations tracked (as reported in GnssStatus messages), with the exception of SBAS.
+ </li>
+ <li>[SR] Report AGC, and Frequency of GNSS measurement.
+ </li>
+ <li>[SR] Report all accuracy estimates (including Bearing, Speed, and Vertical) as part of each GPS/GNSS location.
+ </li>
+ <li>[SR] are STRONGLY RECOMMENDED to meet as many as possible from the additional mandatory requirements for devices reporting the year "2016" or "2017" through the Test API <code>LocationManager.getGnssYearOfHardware()</code>.
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <p>
+ If device implementations include a GPS/GNSS receiver and report the capability to applications through the <code>android.hardware.location.gps</code> feature flag and the <code>LocationManager.getGnssYearOfHardware()</code> Test API reports the year "2016" or newer, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST report GNSS measurements, as soon as they are found, even if a location calculated from GPS/GNSS is not yet reported.
+ </li>
+ <li>[C-2-2] MUST report GNSS pseudoranges and pseudorange rates, that, in open-sky conditions after determining the location, while stationary or moving with less than 0.2 meter per second squared of acceleration, are sufficient to calculate position within 20 meters, and speed within 0.2 meters per second, at least 95% of the time.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a GPS/GNSS receiver and report the capability to applications through the <code>android.hardware.location.gps</code> feature flag and the <code>LocationManager.getGnssYearOfHardware()</code> Test API reports the year "2017" or newer, they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST continue to deliver normal GPS/GNSS location outputs during an emergency phone call.
+ </li>
+ <li>[C-3-2] MUST report GNSS measurements from all constellations tracked (as reported in GnssStatus messages), with the exception of SBAS.
+ </li>
+ <li>[C-3-3] MUST report AGC, and Frequency of GNSS measurement.
+ </li>
+ <li>[C-3-4] MUST report all accuracy estimates (including Bearing, Speed, and Vertical) as part of each GPS/GNSS location.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a GPS/GNSS receiver and report the capability to applications through the <code>android.hardware.location.gps</code> feature flag and the <code>LocationManager.getGnssYearOfHardware()</code> Test API reports the year "2018" or newer, they:
+ </p>
+ <ul>
+ <li>[C-4-1] MUST continue to deliver normal GPS/GNSS outputs to applications during a Mobile Station Based (MS-Based) Network Initiated emergency session call.
+ </li>
+ <li>[C-4-2] MUST report positions and measurements to the <a href="https://developer.android.com/reference/android/location/LocationProvider">GNSS Location Provider</a> APIs.
+ </li>
+ </ul>
+ <h4 id="7_3_4_gyroscope">
+ 7.3.4. Gyroscope
+ </h4>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>SHOULD include a gyroscope (angular change sensor).
+ </li>
+ <li>SHOULD NOT include a gyroscope sensor unless a 3-axis accelerometer is also included.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a gyroscope, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST be able to report events up to a frequency of at least 50 Hz.
+ </li>
+ <li>[C-1-2] MUST implement the <code>TYPE_GYROSCOPE</code> sensor and SHOULD also implement <code>TYPE_GYROSCOPE_UNCALIBRATED</code> sensor.
+ </li>
+ <li>[C-1-3] MUST be capable of measuring orientation changes up to 1,000 degrees per second.
+ </li>
+ <li>[C-1-4] MUST have a resolution of 12-bits or more and SHOULD have a resolution of 16-bits or more.
+ </li>
+ <li>[C-1-5] MUST be temperature compensated.
+ </li>
+ <li>[C-1-6] MUST be calibrated and compensated while in use, and preserve the compensation parameters between device reboots.
+ </li>
+ <li>[C-1-7] MUST have a variance no greater than 1e-7 rad^2 / s^2 per Hz (variance per Hz, or rad^2 / s). The variance is allowed to vary with the sampling rate, but MUST be constrained by this value. In other words, if you measure the variance of the gyro at 1 Hz sampling rate it SHOULD be no greater than 1e-7 rad^2/s^2.
+ </li>
+ <li>[SR] Existing and new Android devices are STRONGLY RECOMMENDED to implement the <code>SENSOR_TYPE_GYROSCOPE_UNCALIBRATED</code> sensor.
+ </li>
+ <li>[SR] Calibration error is STRONGLY RECOMMENDED to be less than 0.01 rad/s when device is stationary at room temperature.
+ </li>
+ <li>SHOULD report events up to at least 200 Hz.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a gyroscope, an accelerometer sensor and a magnetometer sensor, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST implement a <code>TYPE_ROTATION_VECTOR</code> composite sensor.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a gyroscope and an accelerometer sensor, they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST implement the <code>TYPE_GRAVITY</code> and <code>TYPE_LINEAR_ACCELERATION</code> composite sensors.
+ </li>
+ <li>[SR] Existing and new Android devices are STRONGLY RECOMMENDED to implement the <code>TYPE_GAME_ROTATION_VECTOR</code> sensor.
+ </li>
+ <li>SHOULD implement the <code>TYPE_GAME_ROTATION_VECTOR</code> composite sensor.
+ </li>
+ </ul>
+ <h4 id="7_3_5_barometer">
+ 7.3.5. Barometer
+ </h4>
+ <ul>
+ <li>Device implementations SHOULD include a barometer (ambient air pressure sensor).
+ </li>
+ </ul>
+ <p>
+ If device implementations include a barometer, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST implement and report <code>TYPE_PRESSURE</code> sensor.
+ </li>
+ <li>[C-1-2] MUST be able to deliver events at 5 Hz or greater.
+ </li>
+ <li>[C-1-3] MUST be temperature compensated.
+ </li>
+ <li>[SR] STRONGLY RECOMMENDED to be able to report pressure measurements in the range 300hPa to 1100hPa.
+ </li>
+ <li>SHOULD have an absolute accuracy of 1hPa.
+ </li>
+ <li>SHOULD have a relative accuracy of 0.12hPa over 20hPa range (equivalent to ~1m accuracy over ~200m change at sea level).
+ </li>
+ </ul>
+ <h4 id="7_3_6_thermometer">
+ 7.3.6. Thermometer
+ </h4>
+ <p>
+ Device implementations: <em>MAY include an ambient thermometer (temperature sensor).</em> MAY but SHOULD NOT include a CPU temperature sensor.
+ </p>
+ <p>
+ If device implementations include an ambient thermometer (temperature sensor), they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST be defined as <code>SENSOR_TYPE_AMBIENT_TEMPERATURE</code> and MUST measure the ambient (room/vehicle cabin) temperature from where the user is interacting with the device in degrees Celsius.
+ </li>
+ <li>[C-1-2] MUST be defined as <code>SENSOR_TYPE_TEMPERATURE</code>.
+ </li>
+ <li>[C-1-3] MUST measure the temperature of the device CPU.
+ </li>
+ <li>[C-1-4] MUST NOT measure any other temperature.
+ </li>
+ </ul>
+ <p>
+ Note the <code>SENSOR_TYPE_TEMPERATURE</code> sensor type was deprecated in Android 4.0.
+ </p>
+ <h4 id="7_3_7_photometer">
+ 7.3.7. Photometer
+ </h4>
+ <ul>
+ <li>Device implementations MAY include a photometer (ambient light sensor).
+ </li>
+ </ul>
+ <h4 id="7_3_8_proximity_sensor">
+ 7.3.8. Proximity Sensor
+ </h4>
+ <ul>
+ <li>Device implementations MAY include a proximity sensor.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a proximity sensor, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST measure the proximity of an object in the same direction as the screen. That is, the proximity sensor MUST be oriented to detect objects close to the screen, as the primary intent of this sensor type is to detect a phone in use by the user. If device implementations include a proximity sensor with any other orientation, it MUST NOT be accessible through this API.
+ </li>
+ <li>[C-1-2] MUST have 1-bit of accuracy or more.
+ </li>
+ </ul>
+ <h4 id="7_3_9_high_fidelity_sensors">
+ 7.3.9. High Fidelity Sensors
+ </h4>
+ <p>
+ If device implementations include a set of higher quality sensors as defined in this section, and make available them to third-party apps, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST identify the capability through the <code>android.hardware.sensor.hifi_sensors</code> feature flag.
+ </li>
+ </ul>
+ <p>
+ If device implementations declare <code>android.hardware.sensor.hifi_sensors</code>, they:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-2-1] MUST have a <code>TYPE_ACCELEROMETER</code> sensor which:
+ </p>
+ <ul>
+ <li>MUST have a measurement range between at least -8g and +8g, SHOULD have a measurement range between at least -16g and +16g.
+ </li>
+ <li>MUST have a measurement resolution of at least 2048 LSB/g.
+ </li>
+ <li>MUST have a minimum measurement frequency of 12.5 Hz or lower.
+ </li>
+ <li>MUST have a maximum measurement frequency of 400 Hz or higher; SHOULD support the SensorDirectChannel <a href="https://developer.android.com/reference/android/hardware/SensorDirectChannel.html#RATE_VERY_FAST"><code>RATE_VERY_FAST</code></a>.
+ </li>
+ <li>MUST have a measurement noise not above 400 μg/√Hz.
+ </li>
+ <li>MUST implement a non-wake-up form of this sensor with a buffering capability of at least 3000 sensor events.
+ </li>
+ <li>MUST have a batching power consumption not worse than 3 mW.
+ </li>
+ <li>[C-SR] Is STRONGLY RECOMMENDED to have 3dB measurement bandwidth of at least 80% of Nyquist frequency, and white noise spectrum within this bandwidth.
+ </li>
+ <li>SHOULD have an acceleration random walk less than 30 μg √Hz tested at room temperature.
+ </li>
+ <li>SHOULD have a bias change vs. temperature of ≤ +/- 1 mg/°C.
+ </li>
+ <li>SHOULD have a best-fit line non-linearity of ≤ 0.5%, and sensitivity change vs. temperature of ≤ 0.03%/C°.
+ </li>
+ <li>SHOULD have cross-axis sensitivity of < 2.5 % and variation of cross-axis sensitivity < 0.2% in device operation temperature range.
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [C-2-2] MUST have a <code>TYPE_ACCELEROMETER_UNCALIBRATED</code> with the same quality requirements as <code>TYPE_ACCELEROMETER</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-2-3] MUST have a <code>TYPE_GYROSCOPE</code> sensor which:
+ </p>
+ <ul>
+ <li>MUST have a measurement range between at least -1000 and +1000 dps.
+ </li>
+ <li>MUST have a measurement resolution of at least 16 LSB/dps.
+ </li>
+ <li>MUST have a minimum measurement frequency of 12.5 Hz or lower.
+ </li>
+ <li>MUST have a maximum measurement frequency of 400 Hz or higher; SHOULD support the SensorDirectChannel <a href="https://developer.android.com/reference/android/hardware/SensorDirectChannel.html#RATE_VERY_FAST"><code>RATE_VERY_FAST</code></a>.
+ </li>
+ <li>MUST have a measurement noise not above 0.014°/s/√Hz.
+ </li>
+ <li>[C-SR] Is STRONGLY RECOMMENDED to have 3dB measurement bandwidth of at least 80% of Nyquist frequency, and white noise spectrum within this bandwidth.
+ </li>
+ <li>SHOULD have a rate random walk less than 0.001 °/s √Hz tested at room temperature.
+ </li>
+ <li>SHOULD have a bias change vs. temperature of ≤ +/- 0.05 °/ s / °C.
+ </li>
+ <li>SHOULD have a sensitivity change vs. temperature of ≤ 0.02% / °C.
+ </li>
+ <li>SHOULD have a best-fit line non-linearity of ≤ 0.2%.
+ </li>
+ <li>SHOULD have a noise density of ≤ 0.007 °/s/√Hz.
+ </li>
+ <li>SHOULD have calibration error less than 0.002 rad/s in temperature range 10 ~ 40 ℃ when device is stationary.
+ </li>
+ <li>SHOULD have g-sensitivity less than 0.1°/s/g.
+ </li>
+ <li>SHOULD have cross-axis sensitivity of < 4.0 % and cross-axis sensitivity variation < 0.3% in device operation temperature range.
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [C-2-4] MUST have a <code>TYPE_GYROSCOPE_UNCALIBRATED</code> with the same quality requirements as <code>TYPE_GYROSCOPE</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-2-5] MUST have a <code>TYPE_GEOMAGNETIC_FIELD</code> sensor which:
+ </p>
+ <ul>
+ <li>MUST have a measurement range between at least -900 and +900 μT.
+ </li>
+ <li>MUST have a measurement resolution of at least 5 LSB/uT.
+ </li>
+ <li>MUST have a minimum measurement frequency of 5 Hz or lower.
+ </li>
+ <li>MUST have a maximum measurement frequency of 50 Hz or higher.
+ </li>
+ <li>MUST have a measurement noise not above 0.5 uT.
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [C-2-6] MUST have a <code>TYPE_MAGNETIC_FIELD_UNCALIBRATED</code> with the same quality requirements as <code>TYPE_GEOMAGNETIC_FIELD</code> and in addition:
+ </p>
+ <ul>
+ <li>MUST implement a non-wake-up form of this sensor with a buffering capability of at least 600 sensor events.
+ </li>
+ <li>[C-SR] Is STRONGLY RECOMMENDED to have white noise spectrum from 1 Hz to at least 10 Hz when the report rate is 50 Hz or higher.
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [C-2-7] MUST have a <code>TYPE_PRESSURE</code> sensor which:
+ </p>
+ <ul>
+ <li>MUST have a measurement range between at least 300 and 1100 hPa.
+ </li>
+ <li>MUST have a measurement resolution of at least 80 LSB/hPa.
+ </li>
+ <li>MUST have a minimum measurement frequency of 1 Hz or lower.
+ </li>
+ <li>MUST have a maximum measurement frequency of 10 Hz or higher.
+ </li>
+ <li>MUST have a measurement noise not above 2 Pa/√Hz.
+ </li>
+ <li>MUST implement a non-wake-up form of this sensor with a buffering capability of at least 300 sensor events.
+ </li>
+ <li>MUST have a batching power consumption not worse than 2 mW.
+ </li>
+ </ul>
+ </li>
+ <li>[C-2-8] MUST have a <code>TYPE_GAME_ROTATION_VECTOR</code> sensor which:
+ <ul>
+ <li>MUST implement a non-wake-up form of this sensor with a buffering capability of at least 300 sensor events.
+ </li>
+ <li>MUST have a batching power consumption not worse than 4 mW.
+ </li>
+ </ul>
+ </li>
+ <li>[C-2-9] MUST have a <code>TYPE_SIGNIFICANT_MOTION</code> sensor which:
+ <ul>
+ <li>MUST have a power consumption not worse than 0.5 mW when device is static and 1.5 mW when device is moving.
+ </li>
+ </ul>
+ </li>
+ <li>[C-2-10] MUST have a <code>TYPE_STEP_DETECTOR</code> sensor which:
+ <ul>
+ <li>MUST implement a non-wake-up form of this sensor with a buffering capability of at least 100 sensor events.
+ </li>
+ <li>MUST have a power consumption not worse than 0.5 mW when device is static and 1.5 mW when device is moving.
+ </li>
+ <li>MUST have a batching power consumption not worse than 4 mW.
+ </li>
+ </ul>
+ </li>
+ <li>[C-2-11] MUST have a <code>TYPE_STEP_COUNTER</code> sensor which:
+ <ul>
+ <li>MUST have a power consumption not worse than 0.5 mW when device is static and 1.5 mW when device is moving.
+ </li>
+ </ul>
+ </li>
+ <li>[C-2-12] MUST have a <code>TILT_DETECTOR</code> sensor which:
+ <ul>
+ <li>MUST have a power consumption not worse than 0.5 mW when device is static and 1.5 mW when device is moving.
+ </li>
+ </ul>
+ </li>
+ <li>[C-2-13] The event timestamp of the same physical event reported by the Accelerometer, Gyroscope, and Magnetometer MUST be within 2.5 milliseconds of each other. The event timestamp of the same physical event reported by the Accelerometer and Gyroscope SHOULD be within 0.25 milliseconds of each other.
+ </li>
+ <li>[C-2-14] MUST have Gyroscope sensor event timestamps on the same time base as the camera subsystem and within 1 milliseconds of error.
+ </li>
+ <li>[C-2-15] MUST deliver samples to applications within 5 milliseconds from the time when the data is available on any of the above physical sensors to the application.
+ </li>
+ <li>[C-2-16] MUST NOT have a power consumption higher than 0.5 mW when device is static and 2.0 mW when device is moving when any combination of the following sensors are enabled:
+ <ul>
+ <li>
+ <code>SENSOR_TYPE_SIGNIFICANT_MOTION</code>
+ </li>
+ <li>
+ <code>SENSOR_TYPE_STEP_DETECTOR</code>
+ </li>
+ <li>
+ <code>SENSOR_TYPE_STEP_COUNTER</code>
+ </li>
+ <li>
+ <code>SENSOR_TILT_DETECTORS</code>
+ </li>
+ </ul>
+ </li>
+ <li>[C-2-17] MAY have a <code>TYPE_PROXIMITY</code> sensor, but if present MUST have a minimum buffer capability of 100 sensor events.
+ </li>
+ </ul>
+ <p>
+ Note that all power consumption requirements in this section do not include the power consumption of the Application Processor. It is inclusive of the power drawn by the entire sensor chain—the sensor, any supporting circuitry, any dedicated sensor processing system, etc.
+ </p>
+ <p>
+ If device implementations include direct sensor support, they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST correctly declare support of direct channel types and direct report rates level through the <a href="https://developer.android.com/reference/android/hardware/Sensor.html#isDirectChannelTypeSupported%28int%29"><code>isDirectChannelTypeSupported</code></a> and <a href="https://developer.android.com/reference/android/hardware/Sensor.html#getHighestDirectReportRateLevel%28%29"><code>getHighestDirectReportRateLevel</code></a> API.
+ </li>
+ <li>[C-3-2] MUST support at least one of the two sensor direct channel types for all sensors that declare support for sensor direct channel.
+ <ul>
+ <li>
+ <a href="https://developer.android.com/reference/android/hardware/SensorDirectChannel.html#TYPE_HARDWARE_BUFFER"><code>TYPE_HARDWARE_BUFFER</code></a>
+ </li>
+ <li>
+ <a href="https://developer.android.com/reference/android/hardware/SensorDirectChannel.html#TYPE_MEMORY_FILE"><code>TYPE_MEMORY_FILE</code></a>
+ </li>
+ </ul>
+ </li>
+ <li>SHOULD support event reporting through sensor direct channel for primary sensor (non-wakeup variant) of the following types:
+ <ul>
+ <li>
+ <code>TYPE_ACCELEROMETER</code>
+ </li>
+ <li>
+ <code>TYPE_ACCELEROMETER_UNCALIBRATED</code>
+ </li>
+ <li>
+ <code>TYPE_GYROSCOPE</code>
+ </li>
+ <li>
+ <code>TYPE_GYROSCOPE_UNCALIBRATED</code>
+ </li>
+ <li>
+ <code>TYPE_MAGNETIC_FIELD</code>
+ </li>
+ <li>
+ <code>TYPE_MAGNETIC_FIELD_UNCALIBRATED</code>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <h4 id="7_3_10_biometric_sensors">
+ 7.3.10. Biometric Sensors
+ </h4>
+ <h5 id="7_3_10_1_fingerprint_sensors">
+ 7.3.10.1. Fingerprint Sensors
+ </h5>
+ <p>
+ If device implementations include a secure lock screen, they:
+ </p>
+ <ul>
+ <li>SHOULD include a fingerprint sensor.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a fingerprint sensor and make the sensor available to third-party apps, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST declare support for the <code>android.hardware.fingerprint</code> feature.
+ </li>
+ <li>[C-1-2] MUST fully implement the <a href="https://developer.android.com/reference/android/hardware/fingerprint/package-summary.html">corresponding API</a> as described in the Android SDK documentation.
+ </li>
+ <li>[C-1-3] MUST have a false acceptance rate not higher than 0.002%.
+ </li>
+ <li>[SR] Are STRONGLY RECOMMENDED to have a spoof and imposter acceptance rate not higher than 7%.
+ </li>
+ <li>[C-1-4] MUST disclose that this mode may be less secure than a strong PIN, pattern, or password and clearly enumerate the risks of enabling it, if the spoof and imposter acceptance rates are higher than 7%.
+ </li>
+ <li>[C-1-5] MUST rate limit attempts for at least 30 seconds after five false trials for fingerprint verification.
+ </li>
+ <li>[C-1-6] MUST have a hardware-backed keystore implementation, and perform the fingerprint matching in a Trusted Execution Environment (TEE) or on a chip with a secure channel to the TEE.
+ </li>
+ <li>[C-1-7] MUST have all identifiable fingerprint data encrypted and cryptographically authenticated such that they cannot be acquired, read or altered outside of the Trusted Execution Environment (TEE), or a chip with a secure channel to the TEE as documented in the <a href="https://source.android.com/devices/tech/security/authentication/fingerprint-hal.html">implementation guidelines</a> on the Android Open Source Project site.
+ </li>
+ <li>[C-1-8] MUST prevent adding a fingerprint without first establishing a chain of trust by having the user confirm existing or add a new device credential (PIN/pattern/password) that's secured by TEE; the Android Open Source Project implementation provides the mechanism in the framework to do so.
+ </li>
+ <li>[C-1-9] MUST NOT enable 3rd-party applications to distinguish between individual fingerprints.
+ </li>
+ <li>[C-1-10] MUST honor the DevicePolicyManager.KEYGUARD_DISABLE_FINGERPRINT flag.
+ </li>
+ <li>[C-1-11] MUST, when upgraded from a version earlier than Android 6.0, have the fingerprint data securely migrated to meet the above requirements or removed.
+ </li>
+ <li>[C-1-12] MUST completely remove all identifiable fingerprint data for a user when the user's account is removed (including via a factory reset).
+ </li>
+ <li>[C-1-13] MUST not allow unencrypted access to identifiable fingerprint data or any data derived from it (such as embeddings) to the Application Processor.
+ </li>
+ <li>[SR] Are STRONGLY RECOMMENDED to have a false rejection rate of less than 10%, as measured on the device.
+ </li>
+ <li>[SR] Are STRONGLY RECOMMENDED to have a latency below 1 second, measured from when the fingerprint sensor is touched until the screen is unlocked, for one enrolled finger.
+ </li>
+ <li>SHOULD use the Android Fingerprint icon provided in the Android Open Source Project.
+ </li>
+ </ul>
+ <h5 id="7_3_10_2_other_biometric_sensors">
+ 7.3.10.2. Other Biometric Sensors
+ </h5>
+ <p>
+ If device implementations include one or more non-fingerprint-based-biometric sensors and make them available to third-party apps they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST have a false acceptance rate not higher than 0.002%.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to have a spoof and imposter acceptance rate not higher than 7%.
+ </li>
+ <li>[C-1-2] MUST disclose that this mode may be less secure than a strong PIN, pattern, or password and clearly enumerate the risks of enabling it, if the spoof and imposter acceptance rates are higher than 7%.
+ </li>
+ <li>[C-1-3] MUST rate limit attempts for at least 30 seconds after five false trials for biometric verification - where a false trial is one with an adequate capture quality (ACQUIRED_GOOD) that does not match an enrolled biometric
+ </li>
+ <li>[C-1-4] MUST have a hardware-backed keystore implementation, and perform the biometric matching in a Trusted Execution Environment (TEE) or on a chip with a secure channel to the TEE.
+ </li>
+ <li>[C-1-5] MUST have all identifiable data encrypted and cryptographically authenticated such that they cannot be acquired, read or altered outside of the Trusted Execution Environment (TEE), or a chip with a secure channel to the TEE as documented in the <a href="https://source.android.com/devices/tech/security/authentication/fingerprint-hal.html">implementation guidelines</a> on the Android Open Source Project site.
+ </li>
+ <li>[C-1-6] MUST prevent adding new biometrics without first establishing a chain of trust by having the user confirm existing or add a new device credential (PIN/pattern/password) that's secured by TEE; the Android Open Source Project implementation provides the mechanism in the framework to do so.
+ </li>
+ <li>[C-1-7] MUST NOT enable third-party applications to distinguish between biometric enrollments.
+ </li>
+ <li>[C-1-8] MUST honor the individual flag for that biometric (ie: <code>DevicePolicyManager.KEYGUARD_DISABLE_FINGERPRINT</code>, <code>DevicePolicymanager.KEYGUARD_DISABLE_FACE</code>, or <code>DevicePolicymanager.KEYGUARD_DISABLE_IRIS</code>).
+ </li>
+ <li>[C-1-9] MUST completely remove all identifiable biometric data for a user when the user's account is removed (including via a factory reset).
+ </li>
+ <li>[C-1-10] MUST not allow unencrypted access to identifiable biometric data or any data derived from it (such as embeddings) to the Application Processor outside the context of the TEE.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to have a false rejection rate of less than 10%, as measured on the device.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to have a latency below 1 second, measured from when the biometric is detected, until the screen is unlocked, for each enrolled biometric.
+ </li>
+ </ul>
+ <h4 id="7_3_11_android_automotive-only_sensors">
+ 7.3.11. Android Automotive-only sensors
+ </h4>
+ <p>
+ Automotive-specific sensors are defined in the <code>android.car.CarSensorManager API</code>.
+ </p>
+ <h5 id="7_3_11_1_current_gear">
+ 7.3.11.1. Current Gear
+ </h5>
+ <p>
+ See <a href="#2_5_1_hardware">Section 2.5.1</a> for device-specific requirements.
+ </p>
+ <h5 id="7_3_11_2_day_night_mode">
+ 7.3.11.2. Day Night Mode
+ </h5>
+ <p>
+ See <a href="#2_5_1_hardware">Section 2.5.1</a> for device-specific requirements.
+ </p>
+ <h5 id="7_3_11_3_driving_status">
+ 7.3.11.3. Driving Status
+ </h5>
+ <p>
+ This requirement is deprecated.
+ </p>
+ <h5 id="7_3_11_4_wheel_speed">
+ 7.3.11.4. Wheel Speed
+ </h5>
+ <p>
+ See <a href="#2_5_1_hardware">Section 2.5.1</a> for device-specific requirements.
+ </p>
+ <h5 id="7_3_11_5_parking_brake">
+ 7.3.11.5. Parking Brake
+ </h5>
+ <p>
+ See <a href="#2_5_1_hardware">Section 2.5.1</a> for device-specific requirements.
+ </p>
+ <h3 id="7_3_12_pose_sensor">
+ 7.3.12. Pose Sensor
+ </h3>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>MAY support pose sensor with 6 degrees of freedom.
+ </li>
+ </ul>
+ <p>
+ If device implementations support pose sensor with 6 degrees of freedom, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST implement and report <a href="https://developer.android.com/reference/android/hardware/Sensor.html#TYPE_POSE_6DOF"><code>TYPE_POSE_6DOF</code></a> sensor.
+ </li>
+ <li>[C-1-2] MUST be more accurate than the rotation vector alone.
+ </li>
+ </ul>
+ <h3 id="7_4_data_connectivity">
+ 7.4. Data Connectivity
+ </h3>
+ <h4 id="7_4_1_telephony">
+ 7.4.1. Telephony
+ </h4>
+ <p>
+ “Telephony” as used by the Android APIs and this document refers specifically to hardware related to placing voice calls and sending SMS messages via a GSM or CDMA network. While these voice calls may or may not be packet-switched, they are for the purposes of Android considered independent of any data connectivity that may be implemented using the same network. In other words, the Android “telephony” functionality and APIs refer specifically to voice calls and SMS. For instance, device implementations that cannot place calls or send/receive SMS messages are not considered a telephony device, regardless of whether they use a cellular network for data connectivity.
+ </p>
+ <ul>
+ <li>Android MAY be used on devices that do not include telephony hardware. That is, Android is compatible with devices that are not phones.
+ </li>
+ </ul>
+ <p>
+ If device implementations include GSM or CDMA telephony, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST declare the <code>android.hardware.telephony</code> feature flag and other sub-feature flags according to the technology.
+ </li>
+ <li>[C-1-2] MUST implement full support for the API for that technology.
+ </li>
+ </ul>
+ <p>
+ If device implementations do not include telephony hardware, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST implement the full APIs as no-ops.
+ </li>
+ </ul>
+ <h5 id="7_4_1_1_number_blocking_compatibility">
+ 7.4.1.1. Number Blocking Compatibility
+ </h5>
+ <p>
+ If device implementations report the <code>android.hardware.telephony feature</code>, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST include number blocking support
+ </li>
+ <li>[C-1-2] MUST fully implement <a href="http://developer.android.com/reference/android/provider/BlockedNumberContract.html"><code>BlockedNumberContract</code></a> and the corresponding API as described in the SDK documentation.
+ </li>
+ <li>[C-1-3] MUST block all calls and messages from a phone number in 'BlockedNumberProvider' without any interaction with apps. The only exception is when number blocking is temporarily lifted as described in the SDK documentation.
+ </li>
+ <li>[C-1-4] MUST NOT write to the <a href="http://developer.android.com/reference/android/provider/CallLog.html">platform call log provider</a> for a blocked call.
+ </li>
+ <li>[C-1-5] MUST NOT write to the <a href="http://developer.android.com/reference/android/provider/Telephony.html">Telephony provider</a> for a blocked message.
+ </li>
+ <li>[C-1-6] MUST implement a blocked numbers management UI, which is opened with the intent returned by <code>TelecomManager.createManageBlockedNumbersIntent()</code> method.
+ </li>
+ <li>[C-1-7] MUST NOT allow secondary users to view or edit the blocked numbers on the device as the Android platform assumes the primary user to have full control of the telephony services, a single instance, on the device. All blocking related UI MUST be hidden for secondary users and the blocked list MUST still be respected.
+ </li>
+ <li>SHOULD migrate the blocked numbers into the provider when a device updates to Android 7.0.
+ </li>
+ </ul>
+ <h5 id="7_4_1_2_telecom_api">
+ 7.4.1.2. Telecom API
+ </h5>
+ <p>
+ If device implementations report <code>android.hardware.telephony</code>, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support the <code>ConnectionService</code> APIs described in the <a href="https://developer.android.com/guide/topics/connectivity/telecom/selfManaged.html">SDK</a>.
+ </li>
+ <li>[C-1-2] MUST display a new incoming call and provide user affordance to accept or reject the incoming call when the user is on an ongoing call that is made by a third-party app that does not support the hold feature specified via <a href="https://developer.android.com/reference/android/telecom/Connection.html#CAPABILITY_SUPPORT_HOLD"><code>CAPABILITY_SUPPORT_HOLD</code></a>.
+ </li>
+ <li>
+ <p>
+ [C-SR] Are STRONGLY RECOMMENDED to notify the user that answering an incoming call will drop an ongoing call.
+ </p>
+ <p>
+ The AOSP implementation meets these requirements by a heads-up notification which indicates to the user that answering an incoming call will cause the other call to be dropped.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-SR] Are STRONGLY RECOMMENDED to preload the default dialer app that shows a call log entry and the name of a third-party app in its call log when the third-party app sets the <a href="https://developer.android.com/reference/android/telecom/PhoneAccount.html#EXTRA_LOG_SELF_MANAGED_CALLS"><code>EXTRA_LOG_SELF_MANAGED_CALLS</code></a> extras key on its <code>PhoneAccount</code> to <code>true</code>.
+ </p>
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to handle the audio headset's <code>KEYCODE_MEDIA_PLAY_PAUSE</code> and <code>KEYCODE_HEADSETHOOK</code> events for the <a href="https://developer.android.com/reference/android/telecom/package-summary.html"><code>android.telecom</code></a> APIs as below:
+ <ul>
+ <li>Call <a href="https://developer.android.com/reference/android/telecom/Connection.html#onDisconnect%28%29"><code>Connection.onDisconnect()</code></a> when a short press of the key event is detected during an ongoing call.
+ </li>
+ <li>Call <a href="https://developer.android.com/reference/android/telecom/Connection.html#onAnswer%28%29"><code>Connection.onAnswer()</code></a> when a short press of the key event is detected during an incoming call.
+ </li>
+ <li>Call <a href="https://developer.android.com/reference/android/telecom/Connection.html#onReject%28%29"><code>Connection.onReject()</code></a> when a long press of the key event is detected during an incoming call.
+ </li>
+ <li>Toggle the mute status of the <a href="https://developer.android.com/reference/android/telecom/CallAudioState.html"><code>CallAudioState</code></a>.
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <h4 id="7_4_2_ieee_802_11_(wi-fi)">
+ 7.4.2. IEEE 802.11 (Wi-Fi)
+ </h4>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>SHOULD include support for one or more forms of 802.11.
+ </li>
+ </ul>
+ <p>
+ If device implementations include support for 802.11 and expose the functionality to a third-party application, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST implement the corresponding Android API.
+ </li>
+ <li>[C-1-2] MUST report the hardware feature flag <code>android.hardware.wifi</code>.
+ </li>
+ <li>[C-1-3] MUST implement the <a href="http://developer.android.com/reference/android/net/wifi/WifiManager.MulticastLock.html">multicast API</a> as described in the SDK documentation.
+ </li>
+ <li>[C-1-4] MUST support multicast DNS (mDNS) and MUST NOT filter mDNS packets (224.0.0.251) at any time of operation including:
+ <ul>
+ <li>Even when the screen is not in an active state.
+ </li>
+ <li>For Android Television device implementations, even when in standby power states.
+ </li>
+ </ul>
+ </li>
+ <li>[C-1-5] MUST NOT treat the <a href="https://developer.android.com/reference/android/net/wifi/WifiManager.html#enableNetwork%28int%2C%20boolean%29"><code>WifiManager.enableNetwork()</code></a> API method call as a sufficient indication to switch the currently active <code>Network</code> that is used by default for application traffic and is returned by <a href="https://developer.android.com/reference/android/net/ConnectivityManager"><code>ConnectivityManager</code></a> API methods such as <a href="https://developer.android.com/reference/android/net/ConnectivityManager#getActiveNetwork%28%29"><code>getActiveNetwork</code></a> and <a href="https://developer.android.com/reference/android/net/ConnectivityManager#registerDefaultNetworkCallback%28android.net.ConnectivityManager.NetworkCallback,%20android.os.Handler%29"><code>registerDefaultNetworkCallback</code></a>. In other words, they MAY only disable the Internet access provided by any other network provider (e.g. mobile data) if they successfully validate that the Wi-Fi network is providing Internet access.
+ </li>
+ <li>[C-1-6] MUST, when the <a href="https://developer.android.com/reference/android/net/ConnectivityManager.html#reportNetworkConnectivity%28android.net.Network%2C%20boolean%29"><code>ConnectivityManager.reportNetworkConnectivity()</code></a> API method is called, re-evaluate the Internet access on the <code>Network</code> and, once the evaluation determines that the current <code>Network</code> no longer provides Internet access, switch to any other available network (e.g. mobile data) that provides Internet access.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to randomize the source MAC address and sequence number of probe request frames, once at the beginning of each scan, while STA is disconnected.
+ <ul>
+ <li>Each group of probe request frames comprising one scan should use one consistent MAC address (SHOULD NOT randomize MAC address halfway through a scan).
+ </li>
+ <li>Probe request sequence number should iterate as normal (sequentially) between the probe requests in a scan.
+ </li>
+ <li>Probe request sequence number should randomize between the last probe request of a scan and the first probe request of the next scan.
+ </li>
+ </ul>
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED, while STA is disconnected, to allow only the following elements in probe request frames:
+ <ul>
+ <li>SSID Parameter Set (0)
+ </li>
+ <li>DS Parameter Set (3)
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <p>
+ If device implementations support Wi-Fi and use Wi-Fi for location scanning, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST provide a user affordance to enable/disable the value read through the <a href="https://developer.android.com/reference/android/net/wifi/WifiManager.html#isScanAlwaysAvailable%28%29"><code>WifiManager.isScanAlwaysAvailable</code></a> API method.
+ </li>
+ </ul>
+ <h5 id="7_4_2_1_wi-fi_direct">
+ 7.4.2.1. Wi-Fi Direct
+ </h5>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>SHOULD include support for Wi-Fi Direct (Wi-Fi peer-to-peer).
+ </li>
+ </ul>
+ <p>
+ If device implementations include support for Wi-Fi Direct, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST implement the <a href="http://developer.android.com/reference/android/net/wifi/p2p/WifiP2pManager.html">corresponding Android API</a> as described in the SDK documentation.
+ </li>
+ <li>[C-1-2] MUST report the hardware feature <code>android.hardware.wifi.direct</code>.
+ </li>
+ <li>[C-1-3] MUST support regular Wi-Fi operation.
+ </li>
+ <li>[C-1-4] MUST support Wi-Fi and Wi-Fi Direct operations concurrently.
+ </li>
+ </ul>
+ <h5 id="7_4_2_2_wi-fi_tunneled_direct_link_setup">
+ 7.4.2.2. Wi-Fi Tunneled Direct Link Setup
+ </h5>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>SHOULD include support for <a href="http://developer.android.com/reference/android/net/wifi/WifiManager.html">Wi-Fi Tunneled Direct Link Setup (TDLS)</a> as described in the Android SDK Documentation.
+ </li>
+ </ul>
+ <p>
+ If device implementations include support for TDLS and TDLS is enabled by the WiFiManager API, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST declare support for TDLS through [<code>WifiManager.isTdlsSupported</code>] (https://developer.android.com/reference/android/net/wifi/WifiManager.html#isTdlsSupported%28%29).
+ </li>
+ <li>SHOULD use TDLS only when it is possible AND beneficial.
+ </li>
+ <li>SHOULD have some heuristic and NOT use TDLS when its performance might be worse than going through the Wi-Fi access point.
+ </li>
+ </ul>
+ <h5 id="7_4_2_3_wi-fi_aware">
+ 7.4.2.3. Wi-Fi Aware
+ </h5>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>SHOULD include support for <a href="http://www.wi-fi.org/discover-wi-fi/wi-fi-aware">Wi-Fi Aware</a>.
+ </li>
+ </ul>
+ <p>
+ If device implementations include support for Wi-Fi Aware and expose the functionality to third-party apps, then they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST implement the <code>WifiAwareManager</code> APIs as described in the <a href="http://developer.android.com/reference/android/net/wifi/aware/WifiAwareManager.html">SDK documentation</a>.
+ </li>
+ <li>[C-1-2] MUST declare the <code>android.hardware.wifi.aware</code> feature flag.
+ </li>
+ <li>[C-1-3] MUST support Wi-Fi and Wi-Fi Aware operations concurrently.
+ </li>
+ <li>[C-1-4] MUST randomize the Wi-Fi Aware management interface address at intervals no longer than 30 minutes and whenever Wi-Fi Aware is enabled.
+ </li>
+ </ul>
+ <p>
+ If device implementations include support for Wi-Fi Aware and Wi-Fi Location as described in <a href="#7_4_2_5_Wi-Fi_Location">Section 7.4.2.5</a> and exposes these functionalities to third-party apps, then they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST implement the location-aware discovery APIs: <a href="https://developer.android.com/reference/android/net/wifi/aware/PublishConfig.Builder.html#setRangingEnabled%28boolean%29">setRangingEnabled</a>, <a href="https://developer.android.com/reference/android/net/wifi/aware/SubscribeConfig.Builder#setMinDistanceMm%28int%29">setMinDistanceMm</a>, <a href="https://developer.android.com/reference/android/net/wifi/aware/SubscribeConfig.Builder#setMaxDistanceMm%28int%29">setMaxDistanceMm</a> , and <a href="https://developer.android.com/reference/android/net/wifi/aware/DiscoverySessionCallback#onServiceDiscoveredWithinRange%28android.net.wifi.aware.PeerHandle,%20byte[],%20java.util.List%3Cbyte[]%3E,%20int%29">onServiceDiscoveredWithinRange</a>.
+ </li>
+ </ul>
+ <h5 id="7_4_2_4_wi-fi_passpoint">
+ 7.4.2.4. Wi-Fi Passpoint
+ </h5>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>SHOULD include support for <a href="http://www.wi-fi.org/discover-wi-fi/wi-fi-certified-passpoint">Wi-Fi Passpoint</a>.
+ </li>
+ </ul>
+ <p>
+ If device implementations include support for Wi-Fi Passpoint, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST implement the Passpoint related <code>WifiManager</code> APIs as described in the <a href="http://developer.android.com/reference/android/net/wifi/WifiManager.html">SDK documentation</a>.
+ </li>
+ <li>[C-1-2] MUST support IEEE 802.11u standard, specifically related to Network Discovery and Selection, such as Generic Advertisement Service (GAS) and Access Network Query Protocol (ANQP).
+ </li>
+ </ul>
+ <p>
+ Conversely if device implementations do not include support for Wi-Fi Passpoint:
+ </p>
+ <ul>
+ <li>[C-2-1] The implementation of the Passpoint related <code>WifiManager</code> APIs MUST throw an <code>UnsupportedOperationException</code>.
+ </li>
+ </ul>
+ <h5 id="7_4_2_5_wi-fi_location_(wi-fi_round_trip_time_-_rtt)">
+ 7.4.2.5. Wi-Fi Location (Wi-Fi Round Trip Time - RTT)
+ </h5>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>SHOULD include support for <a href="https://www.wi-fi.org/discover-wi-fi/wi-fi-location">Wi-Fi Location</a>.
+ </li>
+ </ul>
+ <p>
+ If device implementations include support for Wi-Fi Location and expose the functionality to third-party apps, then they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST implement the <code>WifiRttManager</code> APIs as described in the <a href="http://developer.android.com/reference/android/net/wifi/rtt/WifiRttManager.html">SDK documentation</a>.
+ </li>
+ <li>[C-1-2] MUST declare the <code>android.hardware.wifi.rtt</code> feature flag.
+ </li>
+ <li>[C-1-3] MUST randomize the source MAC address for each RTT burst which is executed while the Wi-Fi interface on which the RTT is being executed is not associated with an Access Point.
+ </li>
+ </ul>
+ <h4 id="7_4_3_bluetooth">
+ 7.4.3. Bluetooth
+ </h4>
+ <p>
+ If device implementations support Bluetooth Audio profile, they:
+ </p>
+ <ul>
+ <li>SHOULD support Advanced Audio Codecs and Bluetooth Audio Codecs (e.g. LDAC).
+ </li>
+ </ul>
+ <p>
+ If device implementations support HFP, A2DP and AVRCP, they:
+ </p>
+ <ul>
+ <li>SHOULD support at least 5 total connected devices.
+ </li>
+ </ul>
+ <p>
+ If device implementations declare <code>android.hardware.vr.high_performance</code> feature, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support Bluetooth 4.2 and Bluetooth LE Data Length Extension.
+ </li>
+ </ul>
+ <p>
+ Android includes support for <a href="http://developer.android.com/reference/android/bluetooth/package-summary.html">Bluetooth and Bluetooth Low Energy</a>.
+ </p>
+ <p>
+ If device implementations include support for Bluetooth and Bluetooth Low Energy, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST declare the relevant platform features (<code>android.hardware.bluetooth</code> and <code>android.hardware.bluetooth_le</code> respectively) and implement the platform APIs.
+ </li>
+ <li>SHOULD implement relevant Bluetooth profiles such as A2DP, AVRCP, OBEX, HFP, etc. as appropriate for the device.
+ </li>
+ </ul>
+ <p>
+ If device implementations include support for Bluetooth Low Energy, they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST declare the hardware feature <code>android.hardware.bluetooth_le</code>.
+ </li>
+ <li>[C-3-2] MUST enable the GATT (generic attribute profile) based Bluetooth APIs as described in the SDK documentation and <a href="http://developer.android.com/reference/android/bluetooth/package-summary.html">android.bluetooth</a>.
+ </li>
+ <li>[C-3-3] MUST report the correct value for <code>BluetoothAdapter.isOffloadedFilteringSupported()</code> to indicate whether the filtering logic for the <a href="https://developer.android.com/reference/android/bluetooth/le/ScanFilter.html">ScanFilter</a> API classes is implemented.
+ </li>
+ <li>[C-3-4] MUST report the correct value for <code>BluetoothAdapter.isMultipleAdvertisementSupported()</code> to indicate whether Low Energy Advertising is supported.
+ </li>
+ <li>SHOULD support offloading of the filtering logic to the bluetooth chipset when implementing the <a href="https://developer.android.com/reference/android/bluetooth/le/ScanFilter.html">ScanFilter API</a>.
+ </li>
+ <li>SHOULD support offloading of the batched scanning to the bluetooth chipset.
+ </li>
+ <li>
+ <p>
+ SHOULD support multi advertisement with at least 4 slots.
+ </p>
+ </li>
+ <li>
+ <p>
+ [SR] STRONGLY RECOMMENDED to implement a Resolvable Private Address (RPA) timeout no longer than 15 minutes and rotate the address at timeout to protect user privacy.
+ </p>
+ </li>
+ </ul>
+ <p>
+ If device implementations support Bluetooth LE and use Bluetooth LE for location scanning, they:
+ </p>
+ <ul>
+ <li>[C-4-1] MUST provide a user affordance to enable/disable the value read through the System API <code>BluetoothAdapter.isBleScanAlwaysAvailable()</code>.
+ </li>
+ </ul>
+ <h4 id="7_4_4_near-field_communications">
+ 7.4.4. Near-Field Communications
+ </h4>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>SHOULD include a transceiver and related hardware for Near-Field Communications (NFC).
+ </li>
+ <li>[C-0-1] MUST implement <code>android.nfc.NdefMessage</code> and <code>android.nfc.NdefRecord</code> APIs even if they do not include support for NFC or declare the <code>android.hardware.nfc</code> feature as the classes represent a protocol-independent data representation format.
+ </li>
+ </ul>
+ <p>
+ If device implementations include NFC hardware and plan to make it available to third-party apps, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST report the <code>android.hardware.nfc</code> feature from the <a href="http://developer.android.com/reference/android/content/pm/PackageManager.html"><code>android.content.pm.PackageManager.hasSystemFeature()</code> method</a>.
+ </li>
+ <li>MUST be capable of reading and writing NDEF messages via the following NFC standards as below:
+ </li>
+ <li>[C-1-2] MUST be capable of acting as an NFC Forum reader/writer (as defined by the NFC Forum technical specification NFCForum-TS-DigitalProtocol-1.0) via the following NFC standards:
+ <ul>
+ <li>NfcA (ISO14443-3A)
+ </li>
+ <li>NfcB (ISO14443-3B)
+ </li>
+ <li>NfcF (JIS X 6319-4)
+ </li>
+ <li>IsoDep (ISO 14443-4)
+ </li>
+ <li>NFC Forum Tag Types 1, 2, 3, 4, 5 (defined by the NFC Forum)
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [SR] STRONGLY RECOMMENDED to be capable of reading and writing NDEF messages as well as raw data via the following NFC standards. Note that while the NFC standards are stated as STRONGLY RECOMMENDED, the Compatibility Definition for a future version is planned to change these to MUST. These standards are optional in this version but will be required in future versions. Existing and new devices that run this version of Android are very strongly encouraged to meet these requirements now so they will be able to upgrade to the future platform releases.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-3] MUST be capable of transmitting and receiving data via the following peer-to-peer standards and protocols:
+ </p>
+ <ul>
+ <li>ISO 18092
+ </li>
+ <li>LLCP 1.2 (defined by the NFC Forum)
+ </li>
+ <li>SDP 1.0 (defined by the NFC Forum)
+ </li>
+ <li>
+ <a href="http://static.googleusercontent.com/media/source.android.com/en/us/compatibility/ndef-push-protocol.pdf">NDEF Push Protocol</a>
+ </li>
+ <li>SNEP 1.0 (defined by the NFC Forum)
+ </li>
+ </ul>
+ </li>
+ <li>[C-1-4] MUST include support for <a href="http://developer.android.com/guide/topics/connectivity/nfc/nfc.html">Android Beam</a> and SHOULD enable Android Beam by default.
+ </li>
+ <li>[C-1-5] MUST be able to send and receive using Android Beam, when Android Beam is enabled or another proprietary NFC P2p mode is turned on.
+ </li>
+ <li>[C-1-6] MUST implement the SNEP default server. Valid NDEF messages received by the default SNEP server MUST be dispatched to applications using the <code>android.nfc.ACTION_NDEF_DISCOVERED</code> intent. Disabling Android Beam in settings MUST NOT disable dispatch of incoming NDEF message.
+ </li>
+ <li>[C-1-7] MUST honor the <code>android.settings.NFCSHARING_SETTINGS</code> intent to show <a href="http://developer.android.com/reference/android/provider/Settings.html#ACTION_NFCSHARING_SETTINGS">NFC sharing settings</a>.
+ </li>
+ <li>[C-1-8] MUST implement the NPP server. Messages received by the NPP server MUST be processed the same way as the SNEP default server.
+ </li>
+ <li>[C-1-9] MUST implement a SNEP client and attempt to send outbound P2P NDEF to the default SNEP server when Android Beam is enabled. If no default SNEP server is found then the client MUST attempt to send to an NPP server.
+ </li>
+ <li>[C-1-10] MUST allow foreground activities to set the outbound P2P NDEF message using <code>android.nfc.NfcAdapter.setNdefPushMessage</code>, and <code>android.nfc.NfcAdapter.setNdefPushMessageCallback</code>, and <code>android.nfc.NfcAdapter.enableForegroundNdefPush</code>.
+ </li>
+ <li>SHOULD use a gesture or on-screen confirmation, such as 'Touch to Beam', before sending outbound P2P NDEF messages.
+ </li>
+ <li>[C-1-11] MUST support NFC Connection handover to Bluetooth when the device supports Bluetooth Object Push Profile.
+ </li>
+ <li>[C-1-12] MUST support connection handover to Bluetooth when using <code>android.nfc.NfcAdapter.setBeamPushUris</code>, by implementing the “<a href="http://members.nfc-forum.org/specs/spec_list/#conn_handover">Connection Handover version 1.2</a>” and “<a href="http://members.nfc-forum.org/apps/group_public/download.php/18688/NFCForum-AD-BTSSP_1_1.pdf">Bluetooth Secure Simple Pairing Using NFC version 1.0</a>” specs from the NFC Forum. Such an implementation MUST implement the handover LLCP service with service name “urn:nfc:sn:handover” for exchanging the handover request/select records over NFC, and it MUST use the Bluetooth Object Push Profile for the actual Bluetooth data transfer. For legacy reasons (to remain compatible with Android 4.1 devices), the implementation SHOULD still accept SNEP GET requests for exchanging the handover request/select records over NFC. However an implementation itself SHOULD NOT send SNEP GET requests for performing connection handover.
+ </li>
+ <li>[C-1-13] MUST poll for all supported technologies while in NFC discovery mode.
+ </li>
+ <li>SHOULD be in NFC discovery mode while the device is awake with the screen active and the lock-screen unlocked.
+ </li>
+ <li>SHOULD be capable of reading the barcode and URL (if encoded) of <a href="http://developer.android.com/reference/android/nfc/tech/NfcBarcode.html">Thinfilm NFC Barcode</a> products.
+ </li>
+ </ul>
+ <p>
+ Note that publicly available links are not available for the JIS, ISO, and NFC Forum specifications cited above.
+ </p>
+ <p>
+ Android includes support for NFC Host Card Emulation (HCE) mode.
+ </p>
+ <p>
+ If device implementations include an NFC controller chipset capable of HCE (for NfcA and/or NfcB) and support Application ID (AID) routing, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST report the <code>android.hardware.nfc.hce</code> feature constant.
+ </li>
+ <li>[C-2-2] MUST support <a href="http://developer.android.com/guide/topics/connectivity/nfc/hce.html">NFC HCE APIs</a> as defined in the Android SDK.
+ </li>
+ </ul>
+ <p>
+ If device implementations include an NFC controller chipset capable of HCE for NfcF, and implement the feature for third-party applications, they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST report the <code>android.hardware.nfc.hcef</code> feature constant.
+ </li>
+ <li>[C-3-2] MUST implement the <a href="https://developer.android.com/reference/android/nfc/cardemulation/NfcFCardEmulation.html">NfcF Card Emulation APIs</a> as defined in the Android SDK.
+ </li>
+ </ul>
+ <p>
+ If device implementations include general NFC support as described in this section and support MIFARE technologies (MIFARE Classic, MIFARE Ultralight, NDEF on MIFARE Classic) in the reader/writer role, they:
+ </p>
+ <ul>
+ <li>[C-4-1] MUST implement the corresponding Android APIs as documented by the Android SDK.
+ </li>
+ <li>[C-4-2] MUST report the feature <code>com.nxp.mifare</code> from the <a href="http://developer.android.com/reference/android/content/pm/PackageManager.html"><code>android.content.pm.PackageManager.hasSystemFeature</code>()</a> method. Note that this is not a standard Android feature and as such does not appear as a constant in the <code>android.content.pm.PackageManager</code> class.
+ </li>
+ </ul>
+ <h4 id="7_4_5_minimum_network_capability">
+ 7.4.5. Minimum Network Capability
+ </h4>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST include support for one or more forms of data networking. Specifically, device implementations MUST include support for at least one data standard capable of 200 Kbit/sec or greater. Examples of technologies that satisfy this requirement include EDGE, HSPA, EV-DO, 802.11g, Ethernet and Bluetooth PAN.
+ </li>
+ <li>SHOULD also include support for at least one common wireless data standard, such as 802.11 (Wi-Fi), when a physical networking standard (such as Ethernet) is the primary data connection.
+ </li>
+ <li>MAY implement more than one form of data connectivity.
+ </li>
+ <li>[C-0-2] MUST include an IPv6 networking stack and support IPv6 communication using the managed APIs, such as <code>java.net.Socket</code> and <code>java.net.URLConnection</code>, as well as the native APIs, such as <code>AF_INET6</code> sockets.
+ </li>
+ <li>[C-0-3] MUST enable IPv6 by default.
+ </li>
+ <li>MUST ensure that IPv6 communication is as reliable as IPv4, for example:
+ <ul>
+ <li>[C-0-4] MUST maintain IPv6 connectivity in doze mode.
+ </li>
+ <li>[C-0-5] Rate-limiting MUST NOT cause the device to lose IPv6 connectivity on any IPv6-compliant network that uses RA lifetimes of at least 180 seconds.
+ </li>
+ </ul>
+ </li>
+ <li>[C-0-6] MUST provide third-party applications with direct IPv6 connectivity to the network when connected to an IPv6 network, without any form of address or port translation happening locally on the device. Both managed APIs such as <a href="https://developer.android.com/reference/java/net/Socket.html#getLocalAddress%28%29"><code>Socket#getLocalAddress</code></a> or <a href="https://developer.android.com/reference/java/net/Socket.html#getLocalPort%28%29"><code>Socket#getLocalPort</code></a>) and NDK APIs such as <code>getsockname()</code> or <code>IPV6_PKTINFO</code> MUST return the IP address and port that is actually used to send and receive packets on the network.
+ </li>
+ </ul>
+ <p>
+ The required level of IPv6 support depends on the network type, as shown in the following requirements.
+ </p>
+ <p>
+ If device implementations support Wi-Fi, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support dual-stack and IPv6-only operation on Wi-Fi.
+ </li>
+ </ul>
+ <p>
+ If device implementations support Ethernet, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST support dual-stack operation on Ethernet.
+ </li>
+ </ul>
+ <p>
+ If device implementations support Cellular data, they:
+ </p>
+ <ul>
+ <li>SHOULD support IPv6 operation (IPv6-only and possibly dual-stack) on cellular.
+ </li>
+ </ul>
+ <p>
+ If device implementations support more than one network type (e.g., Wi-Fi and cellular data), they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST simultaneously meet the above requirements on each network when the device is simultaneously connected to more than one network type.
+ </li>
+ </ul>
+ <h4 id="7_4_6_sync_settings">
+ 7.4.6. Sync Settings
+ </h4>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST have the master auto-sync setting on by default so that the method <a href="http://developer.android.com/reference/android/content/ContentResolver.html"><code>getMasterSyncAutomatically()</code></a> returns “true”.
+ </li>
+ </ul>
+ <h4 id="7_4_7_data_saver">
+ 7.4.7. Data Saver
+ </h4>
+ <p>
+ If device implementations include a metered connection, they are:
+ </p>
+ <ul>
+ <li>[SR] STRONGLY RECOMMENDED to provide the data saver mode.
+ </li>
+ </ul>
+ <p>
+ If device implementations provide the data saver mode, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support all the APIs in the <code>ConnectivityManager</code> class as described in the <a href="https://developer.android.com/training/basics/network-ops/data-saver.html">SDK documentation</a>
+ </li>
+ <li>[C-1-2] MUST provide a user interface in the settings, that handles the <a href="https://developer.android.com/reference/android/provider/Settings.html#ACTION_IGNORE_BACKGROUND_DATA_RESTRICTIONS_SETTINGS"><code>Settings.ACTION_IGNORE_BACKGROUND_DATA_RESTRICTIONS_SETTINGS</code></a> intent, allowing users to add applications to or remove applications from the whitelist.
+ </li>
+ </ul>
+ <p>
+ If device implementations do not provide the data saver mode, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST return the value <code>RESTRICT_BACKGROUND_STATUS_DISABLED</code> for <a href="https://developer.android.com/reference/android/net/ConnectivityManager.html#getRestrictBackgroundStatus%28%29"><code>ConnectivityManager.getRestrictBackgroundStatus()</code></a>
+ </li>
+ <li>[C-2-2] MUST NOT broadcast <code>ConnectivityManager.ACTION_RESTRICT_BACKGROUND_CHANGED</code>.
+ </li>
+ <li>[C-2-3] MUST have an activity that handles the <code>Settings.ACTION_IGNORE_BACKGROUND_DATA_RESTRICTIONS_SETTINGS</code> intent but MAY implement it as a no-op.
+ </li>
+ </ul>
+ <h4 id="7_4_8_secure_elements">
+ 7.4.8. Secure Elements
+ </h4>
+ <p>
+ If device implementations support <a href="https://developer.android.com/reference/android/se/omapi/package-summary">Open Mobile API</a> capable secure elements and make them available to 3rd-party apps, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST enumerate the available Secure Elements readers when <a href="https://developer.android.com/reference/android/se/omapi/SEService#getReaders%28%29"><code>android.se.omapi.SEService.getReaders()</code></a> method is called.
+ </li>
+ </ul>
+ <h3 id="7_5_cameras">
+ 7.5. Cameras
+ </h3>
+ <p>
+ If device implementations include at least one camera, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST declare the <code>android.hardware.camera.any</code> feature flag.
+ </li>
+ <li>[C-1-2] MUST be possible for an application to simultaneously allocate 3 RGBA_8888 bitmaps equal to the size of the images produced by the largest-resolution camera sensor on the device, while camera is open for the purpose of basic preview and still capture.
+ </li>
+ </ul>
+ <h4 id="7_5_1_rear-facing_camera">
+ 7.5.1. Rear-Facing Camera
+ </h4>
+ <p>
+ A rear-facing camera is a camera located on the side of the device opposite the display; that is, it images scenes on the far side of the device, like a traditional camera.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>SHOULD include a rear-facing camera.
+ </li>
+ </ul>
+ <p>
+ If device implementations include at least one rear-facing camera, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST report the feature flag <code>android.hardware.camera</code> and <code>android.hardware.camera.any</code>.
+ </li>
+ <li>[C-1-2] MUST have a resolution of at least 2 megapixels.
+ </li>
+ <li>SHOULD have either hardware auto-focus or software auto-focus implemented in the camera driver (transparent to application software).
+ </li>
+ <li>MAY have fixed-focus or EDOF (extended depth of field) hardware.
+ </li>
+ <li>MAY include a flash.
+ </li>
+ </ul>
+ <p>
+ If the camera includes a flash:
+ </p>
+ <ul>
+ <li>[C-2-1] the flash lamp MUST NOT be lit while an <code>android.hardware.Camera.PreviewCallback</code> instance has been registered on a Camera preview surface, unless the application has explicitly enabled the flash by enabling the <code>FLASH_MODE_AUTO</code> or <code>FLASH_MODE_ON</code> attributes of a <code>Camera.Parameters</code> object. Note that this constraint does not apply to the device’s built-in system camera application, but only to third-party applications using <code>Camera.PreviewCallback</code>.
+ </li>
+ </ul>
+ <h4 id="7_5_2_front-facing_camera">
+ 7.5.2. Front-Facing Camera
+ </h4>
+ <p>
+ A front-facing camera is a camera located on the same side of the device as the display; that is, a camera typically used to image the user, such as for video conferencing and similar applications.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>MAY include a front-facing camera.
+ </li>
+ </ul>
+ <p>
+ If device implementations include at least one front-facing camera, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST report the feature flag <code>android.hardware.camera.any</code> and <code>android.hardware.camera.front</code>.
+ </li>
+ <li>[C-1-2] MUST have a resolution of at least VGA (640x480 pixels).
+ </li>
+ <li>[C-1-3] MUST NOT use a front-facing camera as the default for the Camera API and MUST NOT configure the API to treat a front-facing camera as the default rear-facing camera, even if it is the only camera on the device.
+ </li>
+ <li>[C-1-4] The camera preview MUST be mirrored horizontally relative to the orientation specified by the application when the current application has explicitly requested that the Camera display be rotated via a call to the <a href="http://developer.android.com/reference/android/hardware/Camera.html#setDisplayOrientation(int)"><code>android.hardware.Camera.setDisplayOrientation()</code></a> method. Conversely, the preview MUST be mirrored along the device’s default horizontal axis when the current application does not explicitly request that the Camera display be rotated via a call to the <a href="http://developer.android.com/reference/android/hardware/Camera.html#setDisplayOrientation(int)"><code>android.hardware.Camera.setDisplayOrientation()</code></a> method.
+ </li>
+ <li>[C-1-5] MUST NOT mirror the final captured still image or video streams returned to application callbacks or committed to media storage.
+ </li>
+ <li>[C-1-6] MUST mirror the image displayed by the postview in the same manner as the camera preview image stream.
+ </li>
+ <li>MAY include features (such as auto-focus, flash, etc.) available to rear-facing cameras as described in <a href="#7_5_1_rear-facing_camera">section 7.5.1</a>.
+ </li>
+ </ul>
+ <p>
+ If device implementations are capable of being rotated by user (such as automatically via an accelerometer or manually via user input):
+ </p>
+ <ul>
+ <li>[C-2-1] The camera preview MUST be mirrored horizontally relative to the device’s current orientation.
+ </li>
+ </ul>
+ <h4 id="7_5_3_external_camera">
+ 7.5.3. External Camera
+ </h4>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>MAY include support for an external camera that is not necessarily always connected.
+ </li>
+ </ul>
+ <p>
+ If device implementations include support for an external camera, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST declare the platform feature flag <code>android.hardware.camera.external</code> and <code>android.hardware camera.any</code>.
+ </li>
+ <li>[C-1-2] MUST support USB Video Class (UVC 1.0 or higher) if the external camera connects through the USB host port.
+ </li>
+ <li>[C-1-3] MUST pass camera CTS tests with a physical external camera device connected. Details of camera CTS testing are available at <a href="https://source.android.com/compatibility/cts/camera-hal">source.android.com</a>.
+ </li>
+ <li>SHOULD support video compressions such as MJPEG to enable transfer of high-quality unencoded streams (i.e. raw or independently compressed picture streams).
+ </li>
+ <li>MAY support multiple cameras.
+ </li>
+ <li>MAY support camera-based video encoding.
+ </li>
+ </ul>
+ <p>
+ If camera-based video encoding is supported:
+ </p>
+ <ul>
+ <li>[C-2-1] A simultaneous unencoded / MJPEG stream (QVGA or greater resolution) MUST be accessible to the device implementation.
+ </li>
+ </ul>
+ <h4 id="7_5_4_camera_api_behavior">
+ 7.5.4. Camera API Behavior
+ </h4>
+ <p>
+ Android includes two API packages to access the camera, the newer android.hardware.camera2 API expose lower-level camera control to the app, including efficient zero-copy burst/streaming flows and per-frame controls of exposure, gain, white balance gains, color conversion, denoising, sharpening, and more.
+ </p>
+ <p>
+ The older API package,<code>android.hardware.Camera</code>, is marked as deprecated in Android 5.0 but as it should still be available for apps to use. Android device implementations MUST ensure the continued support of the API as described in this section and in the Android SDK.
+ </p>
+ <p>
+ All features that are common between the deprecated android.hardware.Camera class and the newer android.hardware.camera2 package MUST have equivalent performance and quality in both APIs. For example, with equivalent settings, autofocus speed and accuracy must be identical, and the quality of captured images must be the same. Features that depend on the different semantics of the two APIs are not required to have matching speed or quality, but SHOULD match as closely as possible.
+ </p>
+ <p>
+ Device implementations MUST implement the following behaviors for the camera-related APIs, for all available cameras. Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST use <code>android.hardware.PixelFormat.YCbCr_420_SP</code> for preview data provided to application callbacks when an application has never called <code>android.hardware.Camera.Parameters.setPreviewFormat(int)</code>.
+ </li>
+ <li>[C-0-2] MUST further be in the NV21 encoding format when an application registers an <code>android.hardware.Camera.PreviewCallback</code> instance and the system calls the <code>onPreviewFrame()</code> method and the preview format is YCbCr_420_SP, the data in the byte[] passed into <code>onPreviewFrame()</code>. That is, NV21 MUST be the default.
+ </li>
+ <li>[C-0-3] MUST support the YV12 format (as denoted by the <code>android.graphics.ImageFormat.YV12</code> constant) for camera previews for both front- and rear-facing cameras for <code>android.hardware.Camera</code>. (The hardware video encoder and camera may use any native pixel format, but the device implementation MUST support conversion to YV12.)
+ </li>
+ <li>[C-0-4] MUST support the <code>android.hardware.ImageFormat.YUV_420_888</code> and <code>android.hardware.ImageFormat.JPEG</code> formats as outputs through the <code>android.media.ImageReader</code> API for <code>android.hardware.camera2</code> devices that advertise <a href="https://developer.android.com/reference/android/hardware/camera2/CameraMetadata.html#REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE"><code>REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE</code></a> capability in <a href="https://developer.android.com/reference/android/hardware/camera2/CameraCharacteristics.html#REQUEST_AVAILABLE_CAPABILITIES"><code>android.request.availableCapabilities</code></a>.
+ </li>
+ <li>[C-0-5] MUST still implement the full <a href="http://developer.android.com/reference/android/hardware/Camera.html">Camera API</a> included in the Android SDK documentation, regardless of whether the device includes hardware autofocus or other capabilities. For instance, cameras that lack autofocus MUST still call any registered <code>android.hardware.Camera.AutoFocusCallback</code> instances (even though this has no relevance to a non-autofocus camera.) Note that this does apply to front-facing cameras; for instance, even though most front-facing cameras do not support autofocus, the API callbacks must still be “faked” as described.
+ </li>
+ <li>[C-0-6] MUST recognize and honor each parameter name defined as a constant on the <a href="http://developer.android.com/reference/android/hardware/Camera.Parameters.html"><code>android.hardware.Camera.Parameters</code></a> class. Conversely, device implementations MUST NOT honor or recognize string constants passed to the <code>android.hardware.Camera.setParameters()</code> method other than those documented as constants on the <code>android.hardware.Camera.Parameters</code>. That is, device implementations MUST support all standard Camera parameters if the hardware allows, and MUST NOT support custom Camera parameter types. For instance, device implementations that support image capture using high dynamic range (HDR) imaging techniques MUST support camera parameter <code>Camera.SCENE_MODE_HDR</code>.
+ </li>
+ <li>[C-0-7] MUST report the proper level of support with the <a href="https://developer.android.com/reference/android/hardware/camera2/CameraCharacteristics.html#INFO_SUPPORTED_HARDWARE_LEVEL"><code>android.info.supportedHardwareLevel</code></a> property as described in the Android SDK and report the appropriate <a href="http://source.android.com/devices/camera/versioning.html">framework feature flags</a>.
+ </li>
+ <li>[C-0-8] MUST also declare its individual camera capabilities of <code>android.hardware.camera2</code> via the <code>android.request.availableCapabilities</code> property and declare the appropriate <a href="http://source.android.com/devices/camera/versioning.html">feature flags</a>; MUST define the feature flag if any of its attached camera devices supports the feature.
+ </li>
+ <li>[C-0-9] MUST broadcast the <code>Camera.ACTION_NEW_PICTURE</code> intent whenever a new picture is taken by the camera and the entry of the picture has been added to the media store.
+ </li>
+ <li>[C-0-10] MUST broadcast the <code>Camera.ACTION_NEW_VIDEO</code> intent whenever a new video is recorded by the camera and the entry of the picture has been added to the media store.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to support a logical camera device that lists capability <a href="https://developer.android.com/reference/android/hardware/camera2/CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA"><code>CameraMetadata.REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA</code></a>, for devices with multiple cameras facing the same direction, consisting of each physical camera facing that direction, as long as the physical camera type is supported by the framework and <a href="https://developer.android.com/reference/android/hardware/camera2/CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL"><code>CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL</code></a> for the physical cameras is either <code>LIMITED</code>, <code>FULL</code>, or <code>LEVEL_3</code>.
+ </li>
+ </ul>
+ <h4 id="7_5_5_camera_orientation">
+ 7.5.5. Camera Orientation
+ </h4>
+ <p>
+ If device implementations have a front- or a rear-facing camera, such camera(s):
+ </p>
+ <ul>
+ <li>[C-1-1] MUST be oriented so that the long dimension of the camera aligns with the screen’s long dimension. That is, when the device is held in the landscape orientation, cameras MUST capture images in the landscape orientation. This applies regardless of the device’s natural orientation; that is, it applies to landscape-primary devices as well as portrait-primary devices.
+ </li>
+ </ul>
+ <h3 id="7_6_memory_and_storage">
+ 7.6. Memory and Storage
+ </h3>
+ <h4 id="7_6_1_minimum_memory_and_storage">
+ 7.6.1. Minimum Memory and Storage
+ </h4>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST include a <a href="http://developer.android.com/reference/android/app/DownloadManager.html">Download Manager</a> that applications MAY use to download data files and they MUST be capable of downloading individual files of at least 100MB in size to the default “cache” location.
+ </li>
+ </ul>
+ <h4 id="7_6_2_application_shared_storage">
+ 7.6.2. Application Shared Storage
+ </h4>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST offer storage to be shared by applications, also often referred as “shared external storage”, "application shared storage" or by the Linux path "/sdcard" it is mounted on.
+ </li>
+ <li>[C-0-2] MUST be configured with shared storage mounted by default, in other words “out of the box”, regardless of whether the storage is implemented on an internal storage component or a removable storage medium (e.g. Secure Digital card slot).
+ </li>
+ <li>[C-0-3] MUST mount the application shared storage directly on the Linux path <code>sdcard</code> or include a Linux symbolic link from <code>sdcard</code> to the actual mount point.
+ </li>
+ <li>[C-0-4] MUST enforce the <code>android.permission.WRITE_EXTERNAL_STORAGE</code> permission on this shared storage as documented in the SDK. Shared storage MUST otherwise be writable by any application that obtains that permission.
+ </li>
+ </ul>
+ <p>
+ Device implementations MAY meet the above requirements using either of the following:
+ </p>
+ <ul>
+ <li>User-accessible removable storage, such as a Secure Digital (SD) card slot.
+ </li>
+ <li>A portion of the internal (non-removable) storage as implemented in the Android Open Source Project (AOSP).
+ </li>
+ </ul>
+ <p>
+ If device implementations use removable storage to satisfy the above requirements, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST implement a toast or pop-up user interface warning the user when there is no storage medium inserted in the slot.
+ </li>
+ <li>[C-1-2] MUST include a FAT-formatted storage medium (e.g. SD card) or show on the box and other material available at time of purchase that the storage medium has to be purchased separately.
+ </li>
+ </ul>
+ <p>
+ If device implementations use a portion of the non-removable storage to satisfy the above requirements, they:
+ </p>
+ <ul>
+ <li>SHOULD use the AOSP implementation of the internal application shared storage.
+ </li>
+ <li>MAY share the storage space with the application private data.
+ </li>
+ </ul>
+ <p>
+ If device implementations include multiple shared storage paths (such as both an SD card slot and shared internal storage), they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST allow only pre-installed and privileged Android applications with the <code>WRITE_EXTERNAL_STORAGE</code> permission to write to the secondary external storage, except when writing to their package-specific directories or within the <code>URI</code> returned by firing the <code>ACTION_OPEN_DOCUMENT_TREE</code> intent.
+ </li>
+ </ul>
+ <p>
+ If device implementations have a USB port with USB peripheral mode support, they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST provide a mechanism to access the data on the application shared storage from a host computer.
+ </li>
+ <li>SHOULD expose content from both storage paths transparently through Android’s media scanner service and <code>android.provider.MediaStore</code>.
+ </li>
+ <li>MAY use USB mass storage, but SHOULD use Media Transfer Protocol to satisfy this requirement.
+ </li>
+ </ul>
+ <p>
+ If device implementations have a USB port with USB peripheral mode and support Media Transfer Protocol, they:
+ </p>
+ <ul>
+ <li>SHOULD be compatible with the reference Android MTP host, <a href="http://www.android.com/filetransfer">Android File Transfer</a>.
+ </li>
+ <li>SHOULD report a USB device class of 0x00.
+ </li>
+ <li>SHOULD report a USB interface name of 'MTP'.
+ </li>
+ </ul>
+ <h4 id="7_6_3_adoptable_storage">
+ 7.6.3. Adoptable Storage
+ </h4>
+ <p>
+ If the device is expected to be mobile in nature unlike Television, device implementations are:
+ </p>
+ <ul>
+ <li>[SR] STRONGLY RECOMMENDED to implement the adoptable storage in a long-term stable location, since accidentally disconnecting them can cause data loss/corruption.
+ </li>
+ </ul>
+ <p>
+ If the removable storage device port is in a long-term stable location, such as within the battery compartment or other protective cover, device implementations are:
+ </p>
+ <ul>
+ <li>[SR] STRONGLY RECOMMENDED to implement <a href="http://source.android.com/devices/storage/adoptable.html">adoptable storage</a>.
+ </li>
+ </ul>
+ <h3 id="7_7_usb">
+ 7.7. USB
+ </h3>
+ <p>
+ If device implementations have a USB port, they:
+ </p>
+ <ul>
+ <li>SHOULD support USB peripheral mode and SHOULD support USB host mode.
+ </li>
+ </ul>
+ <h4 id="7_7_1_usb_peripheral_mode">
+ 7.7.1. USB peripheral mode
+ </h4>
+ <p>
+ If device implementations include a USB port supporting peripheral mode:
+ </p>
+ <ul>
+ <li>[C-1-1] The port MUST be connectable to a USB host that has a standard type-A or type-C USB port.
+ </li>
+ <li>[C-1-2] MUST report the correct value of <code>iSerialNumber</code> in USB standard device descriptor through <code>android.os.Build.SERIAL</code>.
+ </li>
+ <li>[C-1-3] MUST detect 1.5A and 3.0A chargers per the Type-C resistor standard and MUST detect changes in the advertisement if they support Type-C USB.
+ </li>
+ <li>[SR] The port SHOULD use micro-B, micro-AB or Type-C USB form factor. Existing and new Android devices are <strong>STRONGLY RECOMMENDED to meet these requirements</strong> so they will be able to upgrade to the future platform releases.
+ </li>
+ <li>[SR] The port SHOULD be located on the bottom of the device (according to natural orientation) or enable software screen rotation for all apps (including home screen), so that the display draws correctly when the device is oriented with the port at bottom. Existing and new Android devices are <strong>STRONGLY RECOMMENDED to meet these requirements</strong> so they will be able to upgrade to future platform releases.
+ </li>
+ <li>[SR] SHOULD implement support to draw 1.5 A current during HS chirp and traffic as specified in the <a href="http://www.usb.org/developers/docs/devclass_docs/BCv1.2_070312.zip">USB Battery Charging specification, revision 1.2</a>. Existing and new Android devices are <strong>STRONGLY RECOMMENDED to meet these requirements</strong> so they will be able to upgrade to the future platform releases.
+ </li>
+ <li>[SR] STRONGLY RECOMMENDED to not support proprietary charging methods that modify Vbus voltage beyond default levels, or alter sink/source roles as such may result in interoperability issues with the chargers or devices that support the standard USB Power Delivery methods. While this is called out as "STRONGLY RECOMMENDED", in future Android versions we might REQUIRE all type-C devices to support full interoperability with standard type-C chargers.
+ </li>
+ <li>[SR] STRONGLY RECOMMENDED to support Power Delivery for data and power role swapping when they support Type-C USB and USB host mode.
+ </li>
+ <li>SHOULD support Power Delivery for high-voltage charging and support for Alternate Modes such as display out.
+ </li>
+ <li>SHOULD implement the Android Open Accessory (AOA) API and specification as documented in the Android SDK documentation.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a USB port and implement the AOA specification, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST declare support for the hardware feature <a href="http://developer.android.com/guide/topics/connectivity/usb/accessory.html"><code>android.hardware.usb.accessory</code></a>.
+ </li>
+ <li>[C-2-2] The USB mass storage class MUST include the string "android" at the end of the interface description <code>iInterface</code> string of the USB mass storage
+ </li>
+ <li>SHOULD NOT implement <a href="https://source.android.com/devices/accessories/aoa2#audio-support">AOAv2 audio</a> documented in the Android Open Accessory Protocol 2.0 documentation. AOAv2 audio is deprecated as of Android version 8.0 (API level 26).
+ </li>
+ </ul>
+ <h4 id="7_7_2_usb_host_mode">
+ 7.7.2. USB host mode
+ </h4>
+ <p>
+ If device implementations include a USB port supporting host mode, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST implement the Android USB host API as documented in the Android SDK and MUST declare support for the hardware feature <a href="http://developer.android.com/guide/topics/connectivity/usb/host.html"><code>android.hardware.usb.host</code></a>.
+ </li>
+ <li>[C-1-2] MUST implement support to connect standard USB peripherals, in other words, they MUST either:
+ <ul>
+ <li>Have an on-device type C port or ship with cable(s) adapting an on-device proprietary port to a standard USB type-C port (USB Type-C device).
+ </li>
+ <li>Have an on-device type A or ship with cable(s) adapting an on-device proprietary port to a standard USB type-A port.
+ </li>
+ <li>Have an on-device micro-AB port, which SHOULD ship with a cable adapting to a standard type-A port.
+ </li>
+ </ul>
+ </li>
+ <li>[C-1-3] MUST NOT ship with an adapter converting from USB type A or micro-AB ports to a type-C port (receptacle).
+ </li>
+ <li>[SR] STRONGLY RECOMMENDED to implement the <a href="http://developer.android.com/reference/android/hardware/usb/UsbConstants.html#USB_CLASS_AUDIO">USB audio class</a> as documented in the Android SDK documentation.
+ </li>
+ <li>SHOULD support charging the connected USB peripheral device while in host mode; advertising a source current of at least 1.5A as specified in the Termination Parameters section of the <a href="http://www.usb.org/developers/docs/usb_31_021517.zip">USB Type-C Cable and Connector Specification Revision 1.2</a> for USB Type-C connectors or using Charging Downstream Port(CDP) output current range as specified in the <a href="http://www.usb.org/developers/docs/devclass_docs/BCv1.2_070312.zip">USB Battery Charging specifications, revision 1.2</a> for Micro-AB connectors.
+ </li>
+ <li>SHOULD implement and support USB Type-C standards.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a USB port supporting host mode and the USB audio class, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST support the <a href="https://developer.android.com/reference/android/hardware/usb/UsbConstants.html#USB_CLASS_HID">USB HID class</a>.
+ </li>
+ <li>[C-2-2] MUST support the detection and mapping of the following HID data fields specified in the <a href="http://www.usb.org/developers/hidpage/Hut1_12v2.pdf">USB HID Usage Tables</a> and the <a href="http://www.usb.org/developers/hidpage/Voice_Command_Usage.pdf">Voice Command Usage Request</a> to the <a href="https://developer.android.com/reference/android/view/KeyEvent.html"><code>KeyEvent</code></a> constants as below:
+ <ul>
+ <li>Usage Page (0xC) Usage ID (0x0CD): <code>KEYCODE_MEDIA_PLAY_PAUSE</code>
+ </li>
+ <li>Usage Page (0xC) Usage ID (0x0E9): <code>KEYCODE_VOLUME_UP</code>
+ </li>
+ <li>Usage Page (0xC) Usage ID (0x0EA): <code>KEYCODE_VOLUME_DOWN</code>
+ </li>
+ <li>Usage Page (0xC) Usage ID (0x0CF): <code>KEYCODE_VOICE_ASSIST</code>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <p>
+ If device implementations include a USB port supporting host mode and the Storage Access Framework (SAF), they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST recognize any remotely connected MTP (Media Transfer Protocol) devices and make their contents accessible through the <code>ACTION_GET_CONTENT</code>, <code>ACTION_OPEN_DOCUMENT</code>, and <code>ACTION_CREATE_DOCUMENT</code> intents. .
+ </li>
+ </ul>
+ <p>
+ If device implementations include a USB port supporting host mode and USB Type-C, they:
+ </p>
+ <ul>
+ <li>[C-4-1] MUST implement Dual Role Port functionality as defined by the USB Type-C specification (section 4.5.1.3.3).
+ </li>
+ <li>[SR] STRONGLY RECOMMENDED to support DisplayPort, SHOULD support USB SuperSpeed Data Rates, and are STRONGLY RECOMMENDED to support Power Delivery for data and power role swapping.
+ </li>
+ <li>[SR] STRONGLY RECOMMENDED to NOT support Audio Adapter Accessory Mode as described in the Appendix A of the <a href="http://www.usb.org/developers/docs/">USB Type-C Cable and Connector Specification Revision 1.2</a>.
+ </li>
+ <li>SHOULD implement the Try.* model that is most appropriate for the device form factor. For example a handheld device SHOULD implement the Try.SNK model.
+ </li>
+ </ul>
+ <h3 id="7_8_audio">
+ 7.8. Audio
+ </h3>
+ <h4 id="7_8_1_microphone">
+ 7.8.1. Microphone
+ </h4>
+ <p>
+ If device implementations include a microphone, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST report the <code>android.hardware.microphone</code> feature constant.
+ </li>
+ <li>[C-1-2] MUST meet the audio recording requirements in <a href="#5_4_audio_recording">section 5.4</a>.
+ </li>
+ <li>[C-1-3] MUST meet the audio latency requirements in <a href="#5_6_audio_latency">section 5.6</a>.
+ </li>
+ <li>[SR] Are STRONGLY RECOMMENDED to support near-ultrasound recording as described in <a href="#7_8_3_near_ultrasound">section 7.8.3</a>.
+ </li>
+ </ul>
+ <p>
+ If device implementations omit a microphone, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST NOT report the <code>android.hardware.microphone</code> feature constant.
+ </li>
+ <li>[C-2-2] MUST implement the audio recording API at least as no-ops, per <a href="#7_hardware_compatibility">section 7</a>.
+ </li>
+ </ul>
+ <h4 id="7_8_2_audio_output">
+ 7.8.2. Audio Output
+ </h4>
+ <p>
+ If device implementations include a speaker or an audio/multimedia output port for an audio output peripheral such as a 4 conductor 3.5mm audio jack or USB host mode port using <a href="https://source.android.com/devices/audio/usb#audioClass">USB audio class</a>, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST report the <code>android.hardware.audio.output</code> feature constant.
+ </li>
+ <li>[C-1-2] MUST meet the audio playback requirements in <a href="#5_5_audio_playback">section 5.5</a>.
+ </li>
+ <li>[C-1-3] MUST meet the audio latency requirements in <a href="#5_6_audio_latency">section 5.6</a>.
+ </li>
+ <li>[SR] STRONGLY RECOMMENDED to support near-ultrasound playback as described in <a href="#7_8_3_near_ultrasound">section 7.8.3</a>.
+ </li>
+ </ul>
+ <p>
+ If device implementations do not include a speaker or audio output port, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST NOT report the <code>android.hardware.audio.output</code> feature.
+ </li>
+ <li>[C-2-2] MUST implement the Audio Output related APIs as no-ops at least.
+ </li>
+ </ul>
+ <p>
+ For the purposes of this section, an "output port" is a <a href="https://en.wikipedia.org/wiki/Computer_port_%28hardware%29">physical interface</a> such as a 3.5mm audio jack, HDMI, or USB host mode port with USB audio class. Support for audio output over radio-based protocols such as Bluetooth, WiFi, or cellular network does not qualify as including an "output port".
+ </p>
+ <h5 id="7_8_2_1_analog_audio_ports">
+ 7.8.2.1. Analog Audio Ports
+ </h5>
+ <p>
+ In order to be compatible with the <a href="https://source.android.com/devices/accessories/headset/plug-headset-spec">headsets and other audio accessories</a> using the 3.5mm audio plug across the Android ecosystem, if device implementations include one or more analog audio ports, they:
+ </p>
+ <ul>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to include at least one of the audio port(s) to be a 4 conductor 3.5mm audio jack.
+ </li>
+ </ul>
+ <p>
+ If device implementations have a 4 conductor 3.5mm audio jack, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support audio playback to stereo headphones and stereo headsets with a microphone.
+ </li>
+ <li>[C-1-2] MUST support TRRS audio plugs with the CTIA pin-out order.
+ </li>
+ <li>[C-1-3] MUST support the detection and mapping to the keycodes for the following 3 ranges of equivalent impedance between the microphone and ground conductors on the audio plug:
+ <ul>
+ <li>
+ <strong>70 ohm or less</strong>: <code>KEYCODE_HEADSETHOOK</code>
+ </li>
+ <li>
+ <strong>210-290 ohm</strong>: <code>KEYCODE_VOLUME_UP</code>
+ </li>
+ <li>
+ <strong>360-680 ohm</strong>: <code>KEYCODE_VOLUME_DOWN</code>
+ </li>
+ </ul>
+ </li>
+ <li>[C-1-4] MUST trigger <code>ACTION_HEADSET_PLUG</code> upon a plug insert, but only after all contacts on plug are touching their relevant segments on the jack.
+ </li>
+ <li>[C-1-5] MUST be capable of driving at least 150mV ± 10% of output voltage on a 32 ohm speaker impedance.
+ </li>
+ <li>[C-1-6] MUST have a microphone bias voltage between 1.8V ~ 2.9V.
+ </li>
+ <li>[C-1-7] MUST detect and map to the keycode for the following range of equivalent impedance between the microphone and ground conductors on the audio plug:
+ <ul>
+ <li>
+ <strong>110-180 ohm:</strong> <code>KEYCODE_VOICE_ASSIST</code>
+ </li>
+ </ul>
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to support audio plugs with the OMTP pin-out order.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMEND to support audio recording from stereo headsets with a microphone.
+ </li>
+ </ul>
+ <p>
+ If device implementations have a 4 conductor 3.5mm audio jack and support a microphone, and broadcast the <code>android.intent.action.HEADSET_PLUG</code> with the extra value microphone set as 1, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST support the detection of microphone on the plugged in audio accessory.
+ </li>
+ </ul>
+ <h4 id="7_8_3_near-ultrasound">
+ 7.8.3. Near-Ultrasound
+ </h4>
+ <p>
+ Near-Ultrasound audio is the 18.5 kHz to 20 kHz band.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>MUST correctly report the support of near-ultrasound audio capability via the <a href="http://developer.android.com/reference/android/media/AudioManager.html#getProperty%28java.lang.String%29">AudioManager.getProperty</a> API as follows:
+ </li>
+ </ul>
+ <p>
+ If <a href="http://developer.android.com/reference/android/media/AudioManager.html#PROPERTY_SUPPORT_MIC_NEAR_ULTRASOUND"><code>PROPERTY_SUPPORT_MIC_NEAR_ULTRASOUND</code></a> is "true", the following requirements MUST be met by the <code>VOICE_RECOGNITION</code> and <code>UNPROCESSED</code> audio sources:
+ </p>
+ <ul>
+ <li>[C-1-1] The microphone's mean power response in the 18.5 kHz to 20 kHz band MUST be no more than 15 dB below the response at 2 kHz.
+ </li>
+ <li>[C-1-2] The microphone's unweighted signal to noise ratio over 18.5 kHz to 20 kHz for a 19 kHz tone at -26 dBFS MUST be no lower than 50 dB.
+ </li>
+ </ul>
+ <p>
+ If <a href="http://developer.android.com/reference/android/media/AudioManager.html#PROPERTY_SUPPORT_SPEAKER_NEAR_ULTRASOUND"><code>PROPERTY_SUPPORT_SPEAKER_NEAR_ULTRASOUND</code></a> is "true":
+ </p>
+ <ul>
+ <li>[C-2-1] The speaker's mean response in 18.5 kHz - 20 kHz MUST be no lower than 40 dB below the response at 2 kHz.
+ </li>
+ </ul>
+ <h3 id="7_9_virtual_reality">
+ 7.9. Virtual Reality
+ </h3>
+ <p>
+ Android includes APIs and facilities to build "Virtual Reality" (VR) applications including high quality mobile VR experiences. Device implementations MUST properly implement these APIs and behaviors, as detailed in this section.
+ </p>
+ <h4 id="7_9_1_virtual_reality_mode">
+ 7.9.1. Virtual Reality Mode
+ </h4>
+ <p>
+ Android includes support for <a href="https://developer.android.com/reference/android/app/Activity.html#setVrModeEnabled%28boolean,%20android.content.ComponentName%29">VR Mode</a>, a feature which handles stereoscopic rendering of notifications and disables monocular system UI components while a VR application has user focus.
+ </p>
+ <h4 id="7_9_2_virtual_reality_mode_-_high_performance">
+ 7.9.2. Virtual Reality Mode - High Performance
+ </h4>
+ <p>
+ If device implementations support VR mode, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST have at least 2 physical cores.
+ </li>
+ <li>[C-1-2] MUST declare the <code>android.hardware.vr.high_performance</code> feature.
+ </li>
+ <li>[C-1-3] MUST support sustained performance mode.
+ </li>
+ <li>[C-1-4] MUST support OpenGL ES 3.2.
+ </li>
+ <li>[C-1-5] MUST support <code>android.hardware.vulkan.level</code> 0.
+ </li>
+ <li>SHOULD support <code>android.hardware.vulkan.level</code> 1 or higher.
+ </li>
+ <li>[C-1-6] MUST implement <a href="https://www.khronos.org/registry/EGL/extensions/KHR/EGL_KHR_mutable_render_buffer.txt"><code>EGL_KHR_mutable_render_buffer</code></a>, <a href="https://www.khronos.org/registry/EGL/extensions/ANDROID/EGL_ANDROID_front_buffer_auto_refresh.txt"><code>EGL_ANDROID_front_buffer_auto_refresh</code></a>, <a href="https://www.khronos.org/registry/EGL/extensions/ANDROID/EGL_ANDROID_get_native_client_buffer.txt"><code>EGL_ANDROID_get_native_client_buffer</code></a>, <a href="https://www.khronos.org/registry/EGL/extensions/KHR/EGL_KHR_fence_sync.txt"><code>EGL_KHR_fence_sync</code></a>, <a href="https://www.khronos.org/registry/EGL/extensions/KHR/EGL_KHR_wait_sync.txt"><code>EGL_KHR_wait_sync</code></a>, <a href="https://www.khronos.org/registry/EGL/extensions/IMG/EGL_IMG_context_priority.txt"><code>EGL_IMG_context_priority</code></a>, <a href="https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_protected_content.txt"><code>EGL_EXT_protected_content</code></a>, <a href="https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_gl_colorspace.txt"><code>EGL_EXT_image_gl_colorspace</code></a>, and expose the extensions in the list of available EGL extensions.
+ </li>
+ <li>[C-1-8] MUST implement <a href="https://www.khronos.org/registry/OpenGL/extensions/EXT/EXT_multisampled_render_to_texture2.txt"><code>GL_EXT_multisampled_render_to_texture2</code></a>, <a href="https://www.khronos.org/registry/OpenGL/extensions/OVR/OVR_multiview.txt"><code>GL_OVR_multiview</code></a>, <a href="https://www.khronos.org/registry/OpenGL/extensions/OVR/OVR_multiview2.txt"><code>GL_OVR_multiview2</code></a>, <a href="https://www.khronos.org/registry/OpenGL/extensions/OVR/OVR_multiview_multisampled_render_to_texture.txt"><code>GL_OVR_multiview_multisampled_render_to_texture</code></a>, <a href="https://www.khronos.org/registry/OpenGL/extensions/EXT/EXT_protected_textures.txt"><code>GL_EXT_protected_textures</code></a>, <a href="https://www.khronos.org/registry/OpenGL/extensions/EXT/EXT_EGL_image_array.txt"><code>GL_EXT_EGL_image_array</code></a>, <a href="https://www.khronos.org/registry/OpenGL/extensions/EXT/EXT_external_buffer.txt"><code>GL_EXT_external_buffer</code></a>, and expose the extensions in the list of available GL extensions.
+ </li>
+ <li>[C-1-24] MUST implement <a href="https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#VK_KHR_shared_presentable_image"><code>VK_KHR_shared_presentable_image</code></a>, <a href="https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#VK_GOOGLE_display_timing"><code>VK_GOOGLE_display_timing</code></a> and expose the extensions in the list of available Vulkan extensions.
+ </li>
+ <li>[C-1-25] MUST expose at least one Vulkan queue family that where <code>flags</code> contain both <code>VK_QUEUE_GRAPHICS_BIT</code> and <code>VK_QUEUE_COMPUTE_BIT</code>, and <code>queueCount</code> is at least 2.
+ </li>
+ <li>[SR] Are STRONGLY RECOMMENDED to support Vulkan 1.1.
+ </li>
+ <li>[SR] Are STRONGLY RECOMMENDED to implement <a href="https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#VK_ANDROID_external_memory_android_hardware_buffer"><code>VK_ANDROID_external_memory_android_hardware_buffer</code></a> and expose it in the list of available Vulkan extensions.
+ </li>
+ <li>[C-1-7] The GPU and display MUST be able to synchronize access to the shared front buffer such that alternating-eye rendering of VR content at 60fps with two render contexts will be displayed with no visible tearing artifacts.
+ </li>
+ <li>[C-1-9] MUST implement support for <a href="https://developer.android.com/ndk/reference/hardware__buffer_8h.html"><code>AHardwareBuffer</code></a> flags <code>AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER</code>, <code>AHARDWAREBUFFER_USAGE_SENSOR_DIRECT_DATA</code> and <code>AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT</code> as described in the NDK.
+ </li>
+ <li>[C-1-10] MUST implement support for <code>AHardwareBuffers</code> with more than one layer and any combination of the usage flags <code>AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT</code>, <code>AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE</code>, <code>AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT</code> for at least the following formats: <code>AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM</code>, <code>AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM</code>, <code>AHARDWAREBUFFER_FORMAT_R10G10B10A2_UNORM</code>, <code>AHARDWAREBUFFER_FORMAT_R16G16B16A16_FLOAT</code>.
+ </li>
+ <li>[C-1-11] MUST support H.264 decoding at least 3840 x 2160 at 30fps, compressed to an average of 40Mbps (equivalent to 4 instances of 1920 x1080 at 30 fps-10 Mbps or 2 instances of 1920 x 1080 at 60 fps-20 Mbps).
+ </li>
+ <li>[C-1-12] MUST support HEVC and VP9, MUST be capable of decoding at least 1920 x 1080 at 30 fps compressed to an average of 10 Mbps and SHOULD be capable of decoding 3840 x 2160 at 30 fps-20 Mbps (equivalent to 4 instances of 1920 x 1080 at 30 fps-5 Mbps).
+ </li>
+ <li>[C-1-13] MUST support <code>HardwarePropertiesManager.getDeviceTemperatures</code> API and return accurate values for skin temperature.
+ </li>
+ <li>[C-1-14] MUST have an embedded screen, and its resolution MUST be at least 1920 x 1080.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to have a display resolution of at least 2560 x 1440.
+ </li>
+ <li>[C-1-15] The display MUST update at least 60 Hz while in VR Mode.
+ </li>
+ <li>[C-1-17] The display MUST support a low-persistence mode with ≤ 5 milliseconds persistence, persistence being defined as the amount of time for which a pixel is emitting light.
+ </li>
+ <li>[C-1-18] MUST support Bluetooth 4.2 and Bluetooth LE Data Length Extension <a href="#7_4_3_bluetooth">section 7.4.3</a>.
+ </li>
+ <li>[C-1-19] MUST support and properly report <a href="https://developer.android.com/reference/android/hardware/Sensor#isDirectChannelTypeSupported%28int%29">Direct Channel Type</a> for all of the following default sensor types:
+ <ul>
+ <li>
+ <code>TYPE_ACCELEROMETER</code>
+ </li>
+ <li>
+ <code>TYPE_ACCELEROMETER_UNCALIBRATED</code>
+ </li>
+ <li>
+ <code>TYPE_GYROSCOPE</code>
+ </li>
+ <li>
+ <code>TYPE_GYROSCOPE_UNCALIBRATED</code>
+ </li>
+ <li>
+ <code>TYPE_MAGNETIC_FIELD</code>
+ </li>
+ <li>
+ <code>TYPE_MAGNETIC_FIELD_UNCALIBRATED</code>
+ </li>
+ </ul>
+ </li>
+ <li>[C-1-20] MUST support the <a href="https://developer.android.com/reference/android/hardware/SensorDirectChannel.html#TYPE_HARDWARE_BUFFER"><code>TYPE_HARDWARE_BUFFER</code></a> direct channel type for all Direct Channel Types listed above.
+ </li>
+ <li>[C-1-21] MUST meet the gyroscope, accelerometer, and magnetometer related requirements for <code>android.hardware.hifi_sensors</code>, as specified in <a href="#7_3_9_high_fidelity_sensors">section 7.3.9</a>.
+ </li>
+ <li>[SR] Are STRONGLY RECOMMENDED to support the <code>android.hardware.sensor.hifi_sensors</code> feature.
+ </li>
+ <li>[C-1-22] MUST have end-to-end motion to photon latency not higher than 28 milliseconds.
+ </li>
+ <li>[SR] Are STRONGLY RECOMMENDED to have end-to-end motion to photon latency not higher than 20 milliseconds.
+ </li>
+ <li>[C-1-23] MUST have first-frame ratio, which is the ratio between the brightness of pixels on the first frame after a transition from black to white and the brightness of white pixels in steady state, of at least 85%.
+ </li>
+ <li>[SR] Are STRONGLY RECOMMENDED to have first-frame ratio of at least 90%.
+ </li>
+ <li>MAY provide an exclusive core to the foreground application and MAY support the <code>Process.getExclusiveCores</code> API to return the numbers of the cpu cores that are exclusive to the top foreground application.
+ </li>
+ </ul>
+ <p>
+ If exclusive core is supported, then the core:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST not allow any other userspace processes to run on it (except device drivers used by the application), but MAY allow some kernel processes to run as necessary.
+ </li>
+ </ul>
+ <h2 id="8_performance_and_power">
+ 8. Performance and Power
+ </h2>
+ <p>
+ Some minimum performance and power criteria are critical to the user experience and impact the baseline assumptions developers would have when developing an app.
+ </p>
+ <h3 id="8_1_user_experience_consistency">
+ 8.1. User Experience Consistency
+ </h3>
+ <p>
+ A smooth user interface can be provided to the end user if there are certain minimum requirements to ensure a consistent frame rate and response times for applications and games. Device implementations, depending on the device type, MAY have measurable requirements for the user interface latency and task switching as described in <a href="#2_device-types">section 2</a>.
+ </p>
+ <h3 id="8_2_file_i/o_access_performance">
+ 8.2. File I/O Access Performance
+ </h3>
+ <p>
+ Providing a common baseline for a consistent file access performance on the application private data storage (<code>/data</code> partition) allows app developers to set a proper expectation that would help their software design. Device implementations, depending on the device type, MAY have certain requirements described in <a href="#2_device-type">section 2</a> for the following read and write operations:
+ </p>
+ <ul>
+ <li>
+ <strong>Sequential write performance</strong>. Measured by writing a 256MB file using 10MB write buffer.
+ </li>
+ <li>
+ <strong>Random write performance</strong>. Measured by writing a 256MB file using 4KB write buffer.
+ </li>
+ <li>
+ <strong>Sequential read performance</strong>. Measured by reading a 256MB file using 10MB write buffer.
+ </li>
+ <li>
+ <strong>Random read performance</strong>. Measured by reading a 256MB file using 4KB write buffer.
+ </li>
+ </ul>
+ <h3 id="8_3_power-saving_modes">
+ 8.3. Power-Saving Modes
+ </h3>
+ <p>
+ If device implementations include features to improve device power management that are included in AOSP or extend the features that are included in AOSP, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST NOT deviate from the AOSP implementation for the triggering, maintenance, wakeup algorithms and the use of global system settings of App Standby and Doze power-saving modes.
+ </li>
+ <li>[C-1-2] MUST NOT deviate from the AOSP implementation for the use of global settings to manage the throttling of jobs, alarm and network for apps in each bucket for App standby.
+ </li>
+ <li>[C-1-3] MUST NOT deviate from the AOSP implementation for the number of the <a href="https://developer.android.com/topic/performance/appstandby">App Standby Buckets</a> used for App Standby.
+ </li>
+ <li>[C-1-4] MUST implement <a href="https://developer.android.com/topic/performance/appstandby">App Standby Buckets</a> and Doze as described in <a href="https://source.android.com/devices/tech/power/mgmt">Power Management</a>.
+ </li>
+ <li>[C-1-5] MUST return <code>true</code> for <a href="https://developer.android.com/reference/android/os/PowerManager#isPowerSaveMode%28%29"><code>PowerManager.isPowerSaveMode()</code></a> when the device is on power save mode.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to provide user affordance to enable and disable the battery saver feature.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to provide user affordance to display all Apps that are exempted from App Standby and Doze power-saving modes.
+ </li>
+ </ul>
+ <p>
+ In addition to the power-saving modes, Android device implementations MAY implement any or all of the 4 sleeping power states as defined by the Advanced Configuration and Power Interface (ACPI).
+ </p>
+ <p>
+ If device implementations implement S3 and S4 power states as defined by the ACPI, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST enter these states only after the user has taken an explicit action to put the device in an inactive state (e.g. by closing a lid that is physically part of the device or turning off a vehicle or television) and before the user re-activates the device (e.g. by opening the lid or turning the vehicle or television back on).
+ </li>
+ </ul>
+ <h3 id="8_4_power_consumption_accounting">
+ 8.4. Power Consumption Accounting
+ </h3>
+ <p>
+ A more accurate accounting and reporting of the power consumption provides the app developer both the incentives and the tools to optimize the power usage pattern of the application.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[SR] STRONGLY RECOMMENDED to provide a per-component power profile that defines the <a href="http://source.android.com/devices/tech/power/values.html">current consumption value</a> for each hardware component and the approximate battery drain caused by the components over time as documented in the Android Open Source Project site.
+ </li>
+ <li>[SR] STRONGLY RECOMMENDED to report all power consumption values in milliampere hours (mAh).
+ </li>
+ <li>[SR] STRONGLY RECOMMENDED to report CPU power consumption per each process's UID. The Android Open Source Project meets the requirement through the <code>uid_cputime</code> kernel module implementation.
+ </li>
+ <li>[SR] STRONGLY RECOMMENDED to make this power usage available via the <a href="http://source.android.com/devices/tech/power/batterystats.html"><code>adb shell dumpsys batterystats</code></a> shell command to the app developer.
+ </li>
+ <li>SHOULD be attributed to the hardware component itself if unable to attribute hardware component power usage to an application.
+ </li>
+ </ul>
+ <h3 id="8_5_consistent_performance">
+ 8.5. Consistent Performance
+ </h3>
+ <p>
+ Performance can fluctuate dramatically for high-performance long-running apps, either because of the other apps running in the background or the CPU throttling due to temperature limits. Android includes programmatic interfaces so that when the device is capable, the top foreground application can request that the system optimize the allocation of the resources to address such fluctuations.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-0-1] MUST report the support of Sustained Performance Mode accurately through the <a href="https://developer.android.com/reference/android/os/PowerManager.html#isSustainedPerformanceModeSupported%28%29"><code>PowerManager.isSustainedPerformanceModeSupported()</code></a> API method.
+ </p>
+ </li>
+ <li>
+ <p>
+ SHOULD support Sustained Performance Mode.
+ </p>
+ </li>
+ </ul>
+ <p>
+ If device implementations report support of Sustained Performance Mode, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST provide the top foreground application a consistent level of performance for at least 30 minutes, when the app requests it.
+ </li>
+ <li>[C-1-2] MUST honor the <a href="https://developer.android.com/reference/android/view/Window.html#setSustainedPerformanceMode%28boolean%29"><code>Window.setSustainedPerformanceMode()</code></a> API and other related APIs.
+ </li>
+ </ul>
+ <p>
+ If device implementations include two or more CPU cores, they:
+ </p>
+ <ul>
+ <li>SHOULD provide at least one exclusive core that can be reserved by the top foreground application.
+ </li>
+ </ul>
+ <p>
+ If device implementations support reserving one exclusive core for the top foreground application, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST report through the <a href="https://developer.android.com/reference/android/os/Process.html#getExclusiveCores%28%29"><code>Process.getExclusiveCores()</code></a> API method the ID numbers of the exclusive cores that can be reserved by the top foreground application.
+ </li>
+ <li>[C-2-2] MUST not allow any user space processes except the device drivers used by the application to run on the exclusive cores, but MAY allow some kernel processes to run as necessary.
+ </li>
+ </ul>
+ <p>
+ If device implementations do not support an exclusive core, they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST return an empty list through the <a href="https://developer.android.com/reference/android/os/Process.html#getExclusiveCores%28%29"><code>Process.getExclusiveCores()</code></a> API method.
+ </li>
+ </ul>
+ <h2 id="9_security_model_compatibility">
+ 9. Security Model Compatibility
+ </h2>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-0-1] MUST implement a security model consistent with the Android platform security model as defined in <a href="http://developer.android.com/guide/topics/security/permissions.html">Security and Permissions reference document</a> in the APIs in the Android developer documentation.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-2] MUST support installation of self-signed applications without requiring any additional permissions/certificates from any third parties/authorities. Specifically, compatible devices MUST support the security mechanisms described in the follow subsections.
+ </p>
+ </li>
+ </ul>
+ <h3 id="9_1_permissions">
+ 9.1. Permissions
+ </h3>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-0-1] MUST support the <a href="http://developer.android.com/guide/topics/security/permissions.html">Android permissions model</a> as defined in the Android developer documentation. Specifically, they MUST enforce each permission defined as described in the SDK documentation; no permissions may be omitted, altered, or ignored.
+ </p>
+ </li>
+ <li>
+ <p>
+ MAY add additional permissions, provided the new permission ID strings are not in the <code>android.\*</code> namespace.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-2] Permissions with a <code>protectionLevel</code> of <a href="https://developer.android.com/reference/android/content/pm/PermissionInfo.html#PROTECTION&lowbar;FLAG&lowbar;PRIVILEGED"><code>PROTECTION_FLAG_PRIVILEGED</code></a> MUST only be granted to apps preloaded in the privileged path(s) of the system image and within the subset of the explicitly whitelisted permissions for each app. The AOSP implementation meets this requirement by reading and honoring the whitelisted permissions for each app from the files in the <code>etc/permissions/</code> path and using the <code>system/priv-app</code> path as the privileged path.
+ </p>
+ </li>
+ </ul>
+ <p>
+ Permissions with a protection level of dangerous are runtime permissions. Applications with <code>targetSdkVersion</code> > 22 request them at runtime.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-3] MUST show a dedicated interface for the user to decide whether to grant the requested runtime permissions and also provide an interface for the user to manage runtime permissions.
+ </li>
+ <li>[C-0-4] MUST have one and only one implementation of both user interfaces.
+ </li>
+ <li>[C-0-5] MUST NOT grant any runtime permissions to preinstalled apps unless:
+ <ul>
+ <li>The user's consent can be obtained before the application uses it.
+ </li>
+ <li>The runtime permissions are associated with an intent pattern for which the preinstalled application is set as the default handler.
+ </li>
+ </ul>
+ </li>
+ <li>[C-0-6] MUST grant the <code>android.permission.RECOVER_KEYSTORE</code> permission only to system apps that register a properly secured Recovery Agent. A properly secured Recovery Agent is defined as an on-device software agent that synchronizes with an off-device remote storage, that is equipped with secure hardware with protection equivalent or stronger than what is described in <a href="https://developer.android.com/preview/features/security/ckv-whitepaper.html">Google Cloud Key Vault Service</a> to prevent brute-force attacks on the lockscreen knowledge factor.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a pre-installed app or wish to allow third-party apps to access the usage statistics, they:
+ </p>
+ <ul>
+ <li>[SR] are STRONGLY RECOMMENDED provide user-accessible mechanism to grant or revoke access to the usage stats in response to the <a href="https://developer.android.com/reference/android/provider/Settings.html#ACTION&lowbar;USAGE&lowbar;ACCESS&lowbar;SETTINGS"><code>android.settings.ACTION_USAGE_ACCESS_SETTINGS</code></a> intent for apps that declare the <code>android.permission.PACKAGE_USAGE_STATS</code> permission.
+ </li>
+ </ul>
+ <p>
+ If device implementations intend to disallow any apps, including pre-installed apps, from accessing the usage statistics, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST still have an activity that handles the <a href="https://developer.android.com/reference/android/provider/Settings.html#ACTION&lowbar;USAGE&lowbar;ACCESS&lowbar;SETTINGS"><code>android.settings.ACTION_USAGE_ACCESS_SETTINGS</code></a> intent pattern but MUST implement it as a no-op, that is to have an equivalent behavior as when the user is declined for access.
+ </li>
+ </ul>
+ <h3 id="9_2_uid_and_process_isolation">
+ 9.2. UID and Process Isolation
+ </h3>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST support the Android application sandbox model, in which each application runs as a unique Unixstyle UID and in a separate process.
+ </li>
+ <li>[C-0-2] MUST support running multiple applications as the same Linux user ID, provided that the applications are properly signed and constructed, as defined in the <a href="http://developer.android.com/guide/topics/security/permissions.html">Security and Permissions reference</a>.
+ </li>
+ </ul>
+ <h3 id="9_3_filesystem_permissions">
+ 9.3. Filesystem Permissions
+ </h3>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST support the Android file access permissions model as defined in the <a href="http://developer.android.com/guide/topics/security/permissions.html">Security and Permissions reference</a>.
+ </li>
+ </ul>
+ <h3 id="9_4_alternate_execution_environments">
+ 9.4. Alternate Execution Environments
+ </h3>
+ <p>
+ Device implementations MUST keep consistency of the Android security and permission model, even if they include runtime environments that execute applications using some other software or technology than the Dalvik Executable Format or native code. In other words:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-0-1] Alternate runtimes MUST themselves be Android applications, and abide by the standard Android security model, as described elsewhere in <a href="#9_security_model_compatibility">section 9</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-2] Alternate runtimes MUST NOT be granted access to resources protected by permissions not requested in the runtime’s <code>AndroidManifest.xml</code> file via the <<code>uses-permission</code>> mechanism.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-3] Alternate runtimes MUST NOT permit applications to make use of features protected by Android permissions restricted to system applications.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-4] Alternate runtimes MUST abide by the Android sandbox model and installed applications using an alternate runtime MUST NOT reuse the sandbox of any other app installed on the device, except through the standard Android mechanisms of shared user ID and signing certificate.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-5] Alternate runtimes MUST NOT launch with, grant, or be granted access to the sandboxes corresponding to other Android applications.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-6] Alternate runtimes MUST NOT be launched with, be granted, or grant to other applications any privileges of the superuser (root), or of any other user ID.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-7] When the <code>.apk</code> files of alternate runtimes are included in the system image of device implementations, it MUST be signed with a key distinct from the key used to sign other applications included with the device implementations.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-8] When installing applications, alternate runtimes MUST obtain user consent for the Android permissions used by the application.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-9] When an application needs to make use of a device resource for which there is a corresponding Android permission (such as Camera, GPS, etc.), the alternate runtime MUST inform the user that the application will be able to access that resource.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-10] When the runtime environment does not record application capabilities in this manner, the runtime environment MUST list all permissions held by the runtime itself when installing any application using that runtime.
+ </p>
+ </li>
+ <li>
+ <p>
+ Alternate runtimes SHOULD install apps via the <code>PackageManager</code> into separate Android sandboxes (Linux user IDs, etc.).
+ </p>
+ </li>
+ <li>
+ <p>
+ Alternate runtimes MAY provide a single Android sandbox shared by all applications using the alternate runtime.
+ </p>
+ </li>
+ </ul>
+ <h3 id="9_5_multi-user_support">
+ 9.5. Multi-User Support
+ </h3>
+ <p>
+ Android includes <a href="http://developer.android.com/reference/android/os/UserManager.html">support for multiple users</a> and provides support for full user isolation.
+ </p>
+ <ul>
+ <li>Device implementations MAY but SHOULD NOT enable multi-user if they use <a href="http://developer.android.com/reference/android/os/Environment.html">removable media</a> for primary external storage.
+ </li>
+ </ul>
+ <p>
+ If device implementations include multiple users, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST meet the following requirements related to <a href="http://source.android.com/devices/storage/traditional.html">multi-user support</a>.
+ </li>
+ <li>[C-1-2] MUST, for each user, implement a security model consistent with the Android platform security model as defined in <a href="http://developer.android.com/guide/topics/security/permissions.html">Security and Permissions reference document</a> in the APIs.
+ </li>
+ <li>[C-1-3] MUST have separate and isolated shared application storage (a.k.a. <code>/sdcard</code>) directories for each user instance.
+ </li>
+ <li>[C-1-4] MUST ensure that applications owned by and running on behalf of a given user cannot list, read, or write to the files owned by any other user, even if the data of both users are stored on the same volume or filesystem.
+ </li>
+ <li>[C-1-5] MUST encrypt the contents of the SD card when multiuser is enabled using a key stored only on non-removable media accessible only to the system if device implementations use removable media for the external storage APIs. As this will make the media unreadable by a host PC, device implementations will be required to switch to MTP or a similar system to provide host PCs with access to the current user’s data.
+ </li>
+ </ul>
+ <p>
+ If device implementations include multiple users and do not declare the <code>android.hardware.telephony</code> feature flag, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST support restricted profiles, a feature that allows device owners to manage additional users and their capabilities on the device. With restricted profiles, device owners can quickly set up separate environments for additional users to work in, with the ability to manage finer-grained restrictions in the apps that are available in those environments.
+ </li>
+ </ul>
+ <p>
+ If device implementations include multiple users and declare the <code>android.hardware.telephony</code> feature flag, they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST NOT support restricted profiles but MUST align with the AOSP implementation of controls to enable /disable other users from accessing the voice calls and SMS.
+ </li>
+ </ul>
+ <h3 id="9_6_premium_sms_warning">
+ 9.6. Premium SMS Warning
+ </h3>
+ <p>
+ Android includes support for warning users of any outgoing <a href="http://en.wikipedia.org/wiki/Short_code">premium SMS message</a>. Premium SMS messages are text messages sent to a service registered with a carrier that may incur a charge to the user.
+ </p>
+ <p>
+ If device implementations declare support for <code>android.hardware.telephony</code>, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST warn users before sending a SMS message to numbers identified by regular expressions defined in <code>/data/misc/sms/codes.xml</code> file in the device. The upstream Android Open Source Project provides an implementation that satisfies this requirement.
+ </li>
+ </ul>
+ <h3 id="9_7_security_features">
+ 9.7. Security Features
+ </h3>
+ <p>
+ Device implementations MUST ensure compliance with security features in both the kernel and platform as described below.
+ </p>
+ <p>
+ The Android Sandbox includes features that use the Security-Enhanced Linux (SELinux) mandatory access control (MAC) system, seccomp sandboxing, and other security features in the Linux kernel. Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST maintain compatibility with existing applications, even when SELinux or any other security features are implemented below the Android framework.
+ </li>
+ <li>[C-0-2] MUST NOT have a visible user interface when a security violation is detected and successfully blocked by the security feature implemented below the Android framework, but MAY have a visible user interface when an unblocked security violation occurs resulting in a successful exploit.
+ </li>
+ <li>[C-0-3] MUST NOT make SELinux or any other security features implemented below the Android framework configurable to the user or app developer.
+ </li>
+ <li>[C-0-4] MUST NOT allow an application that can affect another application through an API (such as a Device Administration API) to configure a policy that breaks compatibility.
+ </li>
+ <li>[C-0-5] MUST split the media framework into multiple processes so that it is possible to more narrowly grant access for each process as <a href="https://source.android.com/devices/media/framework-hardening.html#arch_changes">described</a> in the Android Open Source Project site.
+ </li>
+ <li>[C-0-6] MUST implement a kernel application sandboxing mechanism which allows filtering of system calls using a configurable policy from multithreaded programs. The upstream Android Open Source Project meets this requirement through enabling the seccomp-BPF with threadgroup synchronization (TSYNC) as described <a href="http://source.android.com/devices/tech/config/kernel.html#Seccomp-BPF-TSYNC">in the Kernel Configuration section of source.android.com</a>.
+ </li>
+ </ul>
+ <p>
+ Kernel integrity and self-protection features are integral to Android security. Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-7] MUST implement kernel stack buffer overflow protections (e.g. <code>CONFIG_CC_STACKPROTECTOR_STRONG</code>).
+ </li>
+ <li>[C-0-8] MUST implement strict kernel memory protections where executable code is read-only, read-only data is non-executable and non-writable, and writable data is non-executable (e.g. <code>CONFIG_DEBUG_RODATA</code> or <code>CONFIG_STRICT_KERNEL_RWX</code>).
+ </li>
+ <li>[C-0-9] MUST implement static and dynamic object size bounds checking of copies between user-space and kernel-space (e.g. <code>CONFIG_HARDENED_USERCOPY</code>) on devices originally shipping with API level 28 or higher.
+ </li>
+ <li>[C-0-10] MUST NOT execute user-space memory when executing in the kernel mode (e.g. hardware PXN, or emulated via <code>CONFIG_CPU_SW_DOMAIN_PAN</code> or <code>CONFIG_ARM64_SW_TTBR0_PAN</code>) on devices originally shipping with API level 28 or higher.
+ </li>
+ <li>[C-0-11] MUST NOT read or write user-space memory in the kernel outside of normal usercopy access APIs (e.g. hardware PAN, or emulated via <code>CONFIG_CPU_SW_DOMAIN_PAN</code> or <code>CONFIG_ARM64_SW_TTBR0_PAN</code>) on devices originally shipping with API level 28 or higher.
+ </li>
+ <li>[C-0-12] MUST implement kernel page table isolation on all devices originally shipping with API level 28 or higher (e.g. <code>CONFIG_PAGE_TABLE_ISOLATION</code> or `CONFIG_UNMAP_KERNEL_AT_EL0).
+ </li>
+ <li>[SR] STRONGLY RECOMMENDED to keep kernel data which is written only during initialization marked read-only after initialization (e.g. <code>__ro_after_init</code>).
+ </li>
+ <li>[SR] STRONGLY RECOMMENDED to randomize the layout of the kernel code and memory, and to avoid exposures that would compromise the randomization (e.g. <code>CONFIG_RANDOMIZE_BASE</code> with bootloader entropy via the <a href="https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/chosen.txt"><code>/chosen/kaslr-seed Device Tree node</code></a> or <a href="https://docs.microsoft.com/en-us/windows-hardware/drivers/bringup/efi-rng-protocol"><code>EFI_RNG_PROTOCOL</code></a>).
+ </li>
+ </ul>
+ <p>
+ If device implementations use a Linux kernel, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST implement SELinux.
+ </li>
+ <li>[C-1-2] MUST set SELinux to global enforcing mode.
+ </li>
+ <li>[C-1-3] MUST configure all domains in enforcing mode. No permissive mode domains are allowed, including domains specific to a device/vendor.
+ </li>
+ <li>[C-1-4] MUST NOT modify, omit, or replace the neverallow rules present within the system/sepolicy folder provided in the upstream Android Open Source Project (AOSP) and the policy MUST compile with all neverallow rules present, for both AOSP SELinux domains as well as device/vendor specific domains.
+ </li>
+ <li>[C-1-5] MUST run third-party applications targeting API level 28 or higher in per-application SELinux sandboxes with per-app SELinux restrictions on each application's private data directory.
+ </li>
+ <li>SHOULD retain the default SELinux policy provided in the system/sepolicy folder of the upstream Android Open Source Project and only further add to this policy for their own device-specific configuration.
+ </li>
+ </ul>
+ <p>
+ If device implementations use kernel other than Linux, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST use a mandatory access control system that is equivalent to SELinux.
+ </li>
+ </ul>
+ <p>
+ Android contains multiple defense-in-depth features that are integral to device security.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-SR] Are STRONGLY RECOMMENDED not to disable Control-Flow Integrity (CFI) or Integer Overflow Sanitization (IntSan) on components that have it enabled.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to enable both CFI and IntSan for any additional security-sensitive userspace components as explained in <a href="https://source.android.com/devices/tech/debug/cfi">CFI</a> and <a href="https://source.android.com/devices/tech/debug/intsan">IntSan</a>.
+ </li>
+ </ul>
+ <h3 id="9_8_privacy">
+ 9.8. Privacy
+ </h3>
+ <h4 id="9_8_1_usage_history">
+ 9.8.1. Usage History
+ </h4>
+ <p>
+ Android stores the history of the user's choices and manages such history by <a href="https://developer.android.com/reference/android/app/usage/UsageStatsManager.html">UsageStatsManager</a>.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST keep a reasonable retention period of such user history.
+ </li>
+ <li>[SR] Are STRONGLY RECOMMENDED to keep the 14 days retention period as configured by default in the AOSP implementation.
+ </li>
+ </ul>
+ <p>
+ Android stores the system events using the <a href="https://developer.android.com/reference/android/util/StatsLog.html"><code>StatsLog</code></a> identifiers, and manages such history via the <code>StatsManager</code> and the <code>IncidentManager</code> System API.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-2] MUST only include the fields marked with <code>DEST_AUTOMATIC</code> in the incident report created by the System API class <code>IncidentManager</code>.
+ </li>
+ <li>[C-0-3] MUST not use the system event identifiers to log any other event than what is described in the <a href="https://developer.android.com/reference/android/util/StatsLog.html"><code>StatsLog</code></a> SDK documents. If additional system events are logged, they MAY use a different atom identifier in the range between 100,000 and 200,000.
+ </li>
+ </ul>
+ <h4 id="9_8_2_recording">
+ 9.8.2. Recording
+ </h4>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST NOT preload or distribute software components out-of-box that send the user's private information (e.g. keystrokes, text displayed on the screen) off the device without the user's consent or clear ongoing notifications.
+ </li>
+ </ul>
+ <p>
+ If device implementations include functionality in the system that captures the contents displayed on the screen and/or records the audio stream played on the device, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST have an ongoing notification to the user whenever this functionality is enabled and actively capturing/recording.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a component enabled out-of-box, capable of recording ambient audio to infer useful information about user’s context, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST NOT store in persistent on-device storage or transmit off the device the recorded raw audio or any format that can be converted back into the original audio or a near facsimile, except with explicit user consent.
+ </li>
+ </ul>
+ <h4 id="9_8_3_connectivity">
+ 9.8.3. Connectivity
+ </h4>
+ <p>
+ If device implementations have a USB port with USB peripheral mode support, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST present a user interface asking for the user's consent before allowing access to the contents of the shared storage over the USB port.
+ </li>
+ </ul>
+ <h4 id="9_8_4_network_traffic">
+ 9.8.4. Network Traffic
+ </h4>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST preinstall the same root certificates for the system-trusted Certificate Authority (CA) store as <a href="https://source.android.com/security/overview/app-security.html#certificate-authorities">provided</a> in the upstream Android Open Source Project.
+ </li>
+ <li>[C-0-2] MUST ship with an empty user root CA store.
+ </li>
+ <li>[C-0-3] MUST display a warning to the user indicating the network traffic may be monitored, when a user root CA is added.
+ </li>
+ </ul>
+ <p>
+ If device traffic is routed through a VPN, device implementations:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST display a warning to the user indicating either:
+ <ul>
+ <li>That network traffic may be monitored.
+ </li>
+ <li>That network traffic is being routed through the specific VPN application providing the VPN.
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <p>
+ If device implementations have a mechanism, enabled out-of-box by default, that routes network data traffic through a proxy server or VPN gateway (for example, preloading a VPN service with <code>android.permission.CONTROL_VPN</code> granted), they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST ask for the user's consent before enabling that mechanism, unless that VPN is enabled by the Device Policy Controller via the <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setAlwaysOnVpnPackage%28android.content.ComponentName,%20java.lang.String,%20boolean%29"><code>DevicePolicyManager.setAlwaysOnVpnPackage()</code></a> , in which case the user does not need to provide a separate consent, but MUST only be notified.
+ </li>
+ </ul>
+ <p>
+ If device implementations implement a user affordance to toggle on the "always-on VPN" function of a 3rd-party VPN app, they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST disable this user affordance for apps that do not support always-on VPN service in the <code>AndroidManifest.xml</code> file via setting the <a href="https://developer.android.com/reference/android/net/VpnService.html#SERVICE_META_DATA_SUPPORTS_ALWAYS_ON"><code>SERVICE_META_DATA_SUPPORTS_ALWAYS_ON</code></a> attribute to <code>false</code>.
+ </li>
+ </ul>
+ <h3 id="9_9_data_storage_encryption">
+ 9.9. Data Storage Encryption
+ </h3>
+ <p>
+ If Advanced Encryption Standard (AES) crypto performance, measured with the most performant AES technology available on the device (e.g. the ARM Cryptography Extensions), is above 50 MiB/sec, device implementations:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support data storage encryption of the application private data (<code>/data</code> partition), as well as the application shared storage partition (<code>/sdcard</code> partition) if it is a permanent, non-removable part of the device, except for device implementations that are typically shared (e.g. Television).
+ </li>
+ <li>[C-1-2] MUST enable the data storage encryption by default at the time the user has completed the out-of-box setup experience, except for device implementations that are typically shared (e.g. Television).
+ </li>
+ </ul>
+ <p>
+ If device implementations are already launched on an earlier Android version and cannot meet the requirement through a system software update, they MAY be exempted from the above requirements.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>SHOULD meet the above data storage encryption requirement via implementing <a href="https://source.android.com/security/encryption/file-based.html">File Based Encryption</a> (FBE).
+ </li>
+ </ul>
+ <h4 id="9_9_1_direct_boot">
+ 9.9.1. Direct Boot
+ </h4>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-0-1] MUST implement the <a href="http://developer.android.com/preview/features/direct-boot.html">Direct Boot mode</a> APIs even if they do not support Storage Encryption.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-2] The <a href="https://developer.android.com/reference/android/content/Intent.html#ACTION_LOCKED_BOOT_COMPLETED"><code>ACTION_LOCKED_BOOT_COMPLETED</code></a> and <a href="https://developer.android.com/reference/android/content/Intent.html#ACTION_USER_UNLOCKED"><code>ACTION_USER_UNLOCKED</code></a> Intents MUST still be broadcast to signal Direct Boot aware applications that Device Encrypted (DE) and Credential Encrypted (CE) storage locations are available for user.
+ </p>
+ </li>
+ </ul>
+ <h4 id="9_9_2_file_based_encryption">
+ 9.9.2. File Based Encryption
+ </h4>
+ <p>
+ If device implementations support FBE, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST boot up without challenging the user for credentials and allow Direct Boot aware apps to access to the Device Encrypted (DE) storage after the <code>ACTION_LOCKED_BOOT_COMPLETED</code> message is broadcasted.
+ </li>
+ <li>[C-1-2] MUST only allow access to Credential Encrypted (CE) storage after the user has unlocked the device by supplying their credentials (eg. passcode, pin, pattern or fingerprint) and the <code>ACTION_USER_UNLOCKED</code> message is broadcasted.
+ </li>
+ <li>[C-1-3] MUST NOT offer any method to unlock the CE protected storage without either the user-supplied credentials or a registered escrow key.
+ </li>
+ <li>[C-1-4] MUST support Verified Boot and ensure that DE keys are cryptographically bound to the device's hardware root of trust.
+ </li>
+ <li>[C-1-5] MUST support encrypting file contents using AES-256-XTS. AES-256-XTS refers to the Advanced Encryption Standard with a 256-bit key length, operated in XTS mode. The full length of the XTS key is 512 bits.
+ </li>
+ <li>
+ <p>
+ [C-1-6] MUST support encrypting file names using AES-256 in CBC-CTS mode.
+ </p>
+ </li>
+ <li>
+ <p>
+ The keys protecting CE and DE storage areas:
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-7] MUST be cryptographically bound to a hardware-backed Keystore.
+ </p>
+ </li>
+ <li>[C-1-8] CE keys MUST be bound to a user's lock screen credentials.
+ </li>
+ <li>[C-1-9] CE keys MUST be bound to a default passcode when the user has not specified lock screen credentials.
+ </li>
+ <li>
+ <p>
+ [C-1-10] MUST be unique and distinct, in other words no user's CE or DE key matches any other user's CE or DE keys.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-11] MUST use the mandatorily supported ciphers, key lengths and modes by default.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-SR] Are STRONGLY RECOMMENDED to encrypt file system metadata, such as file sizes, ownership, modes, and Extended attributes (xattrs), with a key cryptographically bound to the device's hardware root of trust.
+ </p>
+ </li>
+ <li>
+ <p>
+ SHOULD make preloaded essential apps (e.g. Alarm, Phone, Messenger) Direct Boot aware.
+ </p>
+ </li>
+ <li>MAY support alternative ciphers, key lengths and modes for file content and file name encryption.
+ </li>
+ </ul>
+ <p>
+ The upstream Android Open Source project provides a preferred implementation of this feature based on the Linux kernel ext4 encryption feature.
+ </p>
+ <h4 id="9_9_3_full_disk_encryption">
+ 9.9.3. Full Disk Encryption
+ </h4>
+ <p>
+ If device implementations support <a href="http://source.android.com/devices/tech/security/encryption/index.html">full disk encryption</a> (FDE), they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST use AES in a mode designed for storage (for example, XTS or CBC-ESSIV), and with a cipher key length of 128 bits or greater.
+ </li>
+ <li>[C-1-2] MUST use a default passcode to wrap the encryption key and MUST NOT write the encryption key to storage at any time without being encrypted.
+ </li>
+ <li>[C-1-3] MUST AES encrypt the encryption key by default unless the user explicitly opts out, except when it is in active use, with the lock screen credentials stretched using a slow stretching algorithm (e.g. PBKDF2 or scrypt).
+ </li>
+ <li>[C-1-4] The above default password stretching algorithm MUST be cryptographically bound to that keystore when the user has not specified a lock screen credentials or has disabled use of the passcode for encryption and the device provides a hardware-backed keystore.
+ </li>
+ <li>[C-1-5] MUST NOT send encryption key off the device (even when wrapped with the user passcode and/or hardware bound key).
+ </li>
+ </ul>
+ <p>
+ The upstream Android Open Source project provides a preferred implementation of this feature, based on the Linux kernel feature dm-crypt.
+ </p>
+ <h3 id="9_10_device_integrity">
+ 9.10. Device Integrity
+ </h3>
+ <p>
+ The following requirements ensures there is transparency to the status of the device integrity. Device implementations:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-0-1] MUST correctly report through the System API method <code>PersistentDataBlockManager.getFlashLockState()</code> whether their bootloader state permits flashing of the system image. The <code>FLASH_LOCK_UNKNOWN</code> state is reserved for device implementations upgrading from an earlier version of Android where this new system API method did not exist.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-2] MUST support Verified Boot for device integrity.
+ </p>
+ </li>
+ </ul>
+ <p>
+ If device implementations are already launched without supporting Verified Boot on an earlier version of Android and can not add support for this feature with a system software update, they MAY be exempted from the requirement.
+ </p>
+ <p>
+ Verified Boot is a feature that guarantees the integrity of the device software. If device implementations support the feature, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST declare the platform feature flag <code>android.software.verified_boot</code>.
+ </li>
+ <li>[C-1-2] MUST perform verification on every boot sequence.
+ </li>
+ <li>[C-1-3] MUST start verification from an immutable hardware key that is the root of trust and go all the way up to the system partition.
+ </li>
+ <li>[C-1-4] MUST implement each stage of verification to check the integrity and authenticity of all the bytes in the next stage before executing the code in the next stage.
+ </li>
+ <li>[C-1-5] MUST use verification algorithms as strong as current recommendations from NIST for hashing algorithms (SHA-256) and public key sizes (RSA-2048).
+ </li>
+ <li>[C-1-6] MUST NOT allow boot to complete when system verification fails, unless the user consents to attempt booting anyway, in which case the data from any non-verified storage blocks MUST not be used.
+ </li>
+ <li>[C-1-7] MUST NOT allow verified partitions on the device to be modified unless the user has explicitly unlocked the bootloader.
+ </li>
+ <li>[C-SR] If there are multiple discrete chips in the device (e.g. radio, specialized image processor), the boot process of each of those chips is STRONGLY RECOMMENDED to verify every stage upon booting.
+ </li>
+ <li>[C-1-8] MUST use tamper-evident storage: for storing whether the bootloader is unlocked. Tamper-evident storage means that the bootloader can detect if the storage has been tampered with from inside Android.
+ </li>
+ <li>[C-1-9] MUST prompt the user, while using the device, and require physical confirmation before allowing a transition from bootloader locked mode to bootloader unlocked mode.
+ </li>
+ <li>[C-1-10] MUST implement rollback protection for partitions used by Android (e.g. boot, system partitions) and use tamper-evident storage for storing the metadata used for determining the minimum allowable OS version.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to verify all privileged app APK files with a chain of trust rooted in <code>/system</code>, which is protected by Verified Boot.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to verify any executable artifacts loaded by a privileged app from outside its APK file (such as dynamically loaded code or compiled code) before executing them or STRONGLY RECOMMENDED not to execute them at all.
+ </li>
+ <li>SHOULD implement rollback protection for any component with persistent firmware (e.g. modem, camera) and SHOULD use tamper-evident storage for storing the metadata used for determining the minimum allowable version.
+ </li>
+ </ul>
+ <p>
+ If device implementations are already launched without supporting C-1-8 through C-1-10 on an earlier version of Android and can not add support for these requirements with a system software update, they MAY be exempted from the requirements.
+ </p>
+ <p>
+ The upstream Android Open Source Project provides a preferred implementation of this feature in the <a href="http://android.googlesource.com/platform/external/avb/"><code>external/avb/</code></a> repository, which can be integrated into the bootloader used for loading Android.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-R] Are RECOMMENDED to support the <a href="https://developer.android.com/preview/features/security.html#user-confirmation">Android Protected Confirmation API</a>.
+ </li>
+ </ul>
+ <p>
+ If device implementations support the Android Protected Confirmation API they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST report <code>true</code> for the <a href="https://developer.android.com/reference/android/security/ConfirmationPrompt.html#isSupported%28android.content.Context%29"><code>ConfirmationPrompt.isSupported()</code></a> API.
+ </li>
+ <li>[C-3-2] MUST ensure that secure hardware takes full control of display in such a way that Android OS cannot block it without detection by the secure hardware.
+ </li>
+ <li>[C-3-3] MUST ensure that secure hardware takes full control of the touch screen.
+ </li>
+ </ul>
+ <h3 id="9_11_keys_and_credentials">
+ 9.11. Keys and Credentials
+ </h3>
+ <p>
+ The <a href="https://developer.android.com/training/articles/keystore.html">Android Keystore System</a> allows app developers to store cryptographic keys in a container and use them in cryptographic operations through the <a href="https://developer.android.com/reference/android/security/KeyChain.html">KeyChain API</a> or the <a href="https://developer.android.com/reference/java/security/KeyStore.html">Keystore API</a>. Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST allow at least 8,192 keys to be imported or generated.
+ </li>
+ <li>[C-0-2] The lock screen authentication MUST rate-limit attempts and MUST have an exponential backoff algorithm. Beyond 150 failed attempts, the delay MUST be at least 24 hours per attempt.
+ </li>
+ <li>SHOULD not limit the number of keys that can be generated
+ </li>
+ </ul>
+ <p>
+ When the device implementation supports a secure lock screen, it:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST back up the keystore implementation with an isolated execution environment.
+ </li>
+ <li>[C-1-2] MUST have implementations of RSA, AES, ECDSA and HMAC cryptographic algorithms and MD5, SHA1, and SHA-2 family hash functions to properly support the Android Keystore system's supported algorithms in an area that is securely isolated from the code running on the kernel and above. Secure isolation MUST block all potential mechanisms by which kernel or userspace code might access the internal state of the isolated environment, including DMA. The upstream Android Open Source Project (AOSP) meets this requirement by using the <a href="https://source.android.com/security/trusty/">Trusty</a> implementation, but another ARM TrustZone-based solution or a third-party reviewed secure implementation of a proper hypervisor-based isolation are alternative options.
+ </li>
+ <li>[C-1-3] MUST perform the lock screen authentication in the isolated execution environment and only when successful, allow the authentication-bound keys to be used. Lock screen credentials MUST be stored in a way that allows only the isolated execution environment to perform lock screen authentication. The upstream Android Open Source Project provides the <a href="http://source.android.com/devices/tech/security/authentication/gatekeeper.html">Gatekeeper Hardware Abstraction Layer (HAL)</a> and Trusty, which can be used to satisfy this requirement.
+ </li>
+ <li>[C-1-4] MUST support key attestation where the attestation signing key is protected by secure hardware and signing is performed in secure hardware. The attestation signing keys MUST be shared across large enough number of devices to prevent the keys from being used as device identifiers. One way of meeting this requirement is to share the same attestation key unless at least 100,000 units of a given SKU are produced. If more than 100,000 units of an SKU are produced, a different key MAY be used for each 100,000 units.
+ </li>
+ <li>[C-1-5] MUST allow the user to choose the Sleep timeout for transition from the unlocked to the locked state, with a minimum allowable timeout up to 15 seconds.
+ </li>
+ </ul>
+ <p>
+ Note that if a device implementation is already launched on an earlier Android version, such a device is exempted from the requirement to have a keystore backed by an isolated execution environment and support the key attestation, unless it declares the <code>android.hardware.fingerprint</code> feature which requires a keystore backed by an isolated execution environment.
+ </p>
+ <h4 id="9_11_1_secure_lock_screen">
+ 9.11.1. Secure Lock Screen
+ </h4>
+ <p>
+ The AOSP implementation follows a tiered authentication model where a knowledge-factory based primary authentication can be backed by either a secondary strong biometric, or by weaker tertiary modalities.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to set only one of the following as the primary authentication method:
+ <ul>
+ <li>A numerical PIN
+ </li>
+ <li>An alphanumeric password
+ </li>
+ <li>A swipe pattern on a grid of exactly 3x3 dots
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <p>
+ Note that the above authentication methods are referred as the recommended primary authentication methods in this document.
+ </p>
+ <p>
+ If device implementations add or modify the recommended primary authentication methods and use a new authentication method as a secure way to lock the screen, the new authentication method:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST be the user authentication method as described in <a href="https://developer.android.com/training/articles/keystore.html#UserAuthentication">Requiring User Authentication For Key Use</a>.
+ </li>
+ <li>[C-2-2] MUST unlock all keys for a third-party developer app to use when the user unlocks the secure lock screen. For example, all keys MUST be available for a third-party developer app through relevant APIs, such as <a href="https://developer.android.com/reference/android/app/KeyguardManager.html#createConfirmDeviceCredentialIntent%28java.lang.CharSequence,%20java.lang.CharSequence%29"><code>createConfirmDeviceCredentialIntent</code></a> and <a href="https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder.html#setUserAuthenticationRequired%28boolean%29"><code>setUserAuthenticationRequired</code></a>.
+ </li>
+ </ul>
+ <p>
+ If device implementations add or modify the authentication methods to unlock the lock screen if based on a known secret and use a new authentication method to be treated as a secure way to lock the screen:
+ </p>
+ <ul>
+ <li>[C-3-1] The entropy of the shortest allowed length of inputs MUST be greater than 10 bits.
+ </li>
+ <li>[C-3-2] The maximum entropy of all possible inputs MUST be greater than 18 bits.
+ </li>
+ <li>[C-3-3] The new authentication method MUST NOT replace any of the recommended primary authentication methods (i.e. PIN, pattern, password) implemented and provided in AOSP.
+ </li>
+ <li>[C-3-4] The new authentication method MUST be disabled when the Device Policy Controller (DPC) application has set the password quality policy via the <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordQuality%28android.content.ComponentName,%20int%29"><code>DevicePolicyManager.setPasswordQuality()</code></a> method with a more restrictive quality constant than <code>PASSWORD_QUALITY_SOMETHING</code>.
+ </li>
+ </ul>
+ <p>
+ If device implementations add or modify the recommended primary authentication methods to unlock the lock screen and use a new authentication method that is based on biometrics to be treated as a secure way to lock the screen, the new method:
+ </p>
+ <ul>
+ <li>[C-4-1] MUST meet all requirements described in <a href="#7_3_10_2_other_biometric_sensors">section 7.3.10.2</a>.
+ </li>
+ <li>[C-4-2] MUST have a fall-back mechanism to use one of the recommended primary authentication methods which is based on a known secret.
+ </li>
+ <li>[C-4-3] MUST be disabled and only allow the recommended primary authentication to unlock the screen when the Device Policy Controller (DPC) application has set the keguard feature policy by calling the method <a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setKeyguardDisabledFeatures%28android.content.ComponentName,%20int%29"><code>DevicePolicyManager.setKeyguardDisabledFeatures()</code></a> , with any of the associated biometric flags (i.e. <code>KEYGUARD_DISABLE_BIOMETRICS</code>, <code>KEYGUARD_DISABLE_FINGERPRINT</code>, <code>KEYGUARD_DISABLE_FACE</code>, or <code>KEYGUARD_DISABLE_IRIS</code>).
+ </li>
+ <li>[C-4-4] MUST challenge the user for the recommended primary authentication (e.g. PIN, pattern, password) at least once every 72 hours or less.
+ </li>
+ <li>[C-4-5] MUST have a false acceptance rate that is equal or stronger than what is required for a fingerprint sensor as described in section <a href="#7_3_10_biometric_sensors">section 7.3.10</a>, or otherwise MUST be disabled and only allow the recommended primary authentication to unlock the screen when the Device Policy Controller (DPC) application has set the password quality policy via the <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordQuality%28android.content.ComponentName,%20int%29"><code>DevicePolicyManager.setPasswordQuality()</code></a> method with a more restrictive quality constant than <code>PASSWORD_QUALITY_BIOMETRIC_WEAK</code>.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to have spoof and imposter acceptance rates that are equal to or stronger than what is required for a fingerprint sensor as described in <a href="#7_3_10_biometric_sensors">section 7.3.10</a>.
+ </li>
+ <li>[C-4-6] MUST have a secure processing pipeline such that an operating system or kernel compromise cannot allow data to be directly injected to falsely authenticate as the user.
+ </li>
+ <li>[C-4-7] MUST be paired with an explicit confirm action (eg: a button press) to allow access to keystore keys if the application sets <code>true</code> for <a href="https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder.html#setUserAuthenticationRequired%28boolean%29"><code>KeyGenParameterSpec.Built.setUserAuthenticationRequired()</code></a> and the biometric is passive (e.g. face or iris where no explicit signal of intent exists).
+ </li>
+ <li>[C-SR] The confirm action for passive biometrics is STRONGLY RECOMMENDED to be secured such that an operating system or kernel compromise cannot spoof it. For example, this means that the confirm action based on a physical button is routed through an input-only general-purpose input/output (GPIO) pin of a secure element (SE) that cannot be driven by any other means than a physical button press.
+ </li>
+ </ul>
+ <p>
+ If the biometric authentication methods do not meet the spoof and imposter acceptance rates as described in <a href="#7_3_10_biometric_sensors">section 7.3.10</a>:
+ </p>
+ <ul>
+ <li>[C-5-1] The methods MUST be disabled if the Device Policy Controller (DPC) application has set the password quality policy via the <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordQuality%28android.content.ComponentName,%20int%29"><code>DevicePolicyManager.setPasswordQuality()</code></a> method with a more restrictive quality constant than <code>PASSWORD_QUALITY_BIOMETRIC_WEAK</code>.
+ </li>
+ <li>[C-5-2] The user MUST be challenged for the recommended primary authentication (eg: PIN, pattern, password) after any 4-hour idle timeout period. The idle timeout period is reset after any successful confirmation of the device credentials.
+ </li>
+ <li>[C-5-3] The methods MUST NOT be treated as a secure lock screen, and MUST meet the requirements that start with C-8 in this section below.
+ </li>
+ </ul>
+ <p>
+ If device implementations add or modify the authentication methods to unlock the lock screen and a new authentication method is based on a physical token or the location:
+ </p>
+ <ul>
+ <li>[C-6-1] They MUST have a fall-back mechanism to use one of the recommended primary authentication methods which is based on a known secret and meet the requirements to be treated as a secure lock screen.
+ </li>
+ <li>[C-6-2] The new method MUST be disabled and only allow one of the recommended primary authentication methods to unlock the screen when the Device Policy Controller (DPC) application has set the policy with either the <a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setKeyguardDisabledFeatures%28android.content.ComponentName,%20int%29"><code>DevicePolicyManager.setKeyguardDisabledFeatures(KEYGUARD_DISABLE_TRUST_AGENTS)</code></a> method or the <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordQuality%28android.content.ComponentName,%20int%29"><code>DevicePolicyManager.setPasswordQuality()</code></a> method with a more restrictive quality constant than <code>PASSWORD_QUALITY_UNSPECIFIED</code>.
+ </li>
+ <li>[C-6-3] The user MUST be challenged for one of the recommended primary authentication methods (e.g.PIN, pattern, password) at least once every 72 hours or less.
+ </li>
+ <li>[C-6-4] The new method MUST NOT be treated as a secure lock screen and MUST follow the constraints listed in C-8 below.
+ </li>
+ </ul>
+ <p>
+ If device implementations have a secure lock screen and include one or more trust agent, which implements the <code>TrustAgentService</code> System API, they:
+ </p>
+ <ul>
+ <li>[C-7-1] MUST have clear indication in the settings menu and on the lock screen when device lock is deferred or can be unlocked by trust agent(s). For example, AOSP meets this requirement by showing a text description for the "Automatically lock setting" and "Power button instantly locks" in the settings menu and a distinguishable icon on the lock screen.
+ </li>
+ <li>[C-7-2] MUST respect and fully implement all trust agent APIs in the <code>DevicePolicyManager</code> class, such as the <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#KEYGUARD&lowbarDISABLE&lowbarTRUST&lowbarAGENTS"><code>KEYGUARD_DISABLE_TRUST_AGENTS</code></a> constant.
+ </li>
+ <li>[C-7-3] MUST NOT fully implement the <code>TrustAgentService.addEscrowToken()</code> function on a device that is used as a primary personal device (e.g. handheld) but MAY fully implement the function on device implementations that are typically shared (e.g. Android Television or Automotive device).
+ </li>
+ <li>[C-7-4] MUST encrypt all stored tokens added by <code>TrustAgentService.addEscrowToken()</code>.
+ </li>
+ <li>[C-7-5] MUST NOT store the encryption key on the same device where the key is used. For example, it is allowed for a key stored on a phone to unlock a user account on a TV.
+ </li>
+ <li>[C-7-6] MUST inform the user about the security implications before enabling the escrow token to decrypt the data storage.
+ </li>
+ <li>[C-7-7] MUST have a fall-back mechanism to use one of the recommended primary authentication methods.
+ </li>
+ <li>[C-7-8] The user MUST be challenged for one of the recommended primary authentication (eg: PIN, pattern, password) methods at least once every 72 hours or less.
+ </li>
+ <li>[C-7-9] The user MUST be challenged for one of the recommended primary authentication (eg: PIN, pattern, password) methods after any 4-hour idle timeout period. The idle timeout period is reset after any successful confirmation of the device credentials.
+ </li>
+ <li>[C-7-10] MUST NOT be treated as a secure lock screen and MUST follow the constraints listed in C-8 below.
+ </li>
+ </ul>
+ <p>
+ If device implementations add or modify the authentication methods to unlock the lock screen that is not a secure lock screen as described above, and use a new authentication method to unlock the keyguard:
+ </p>
+ <ul>
+ <li>[C-8-1] The new method MUST be disabled when the Device Policy Controller (DPC) application has set the password quality policy via the <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordQuality%28android.content.ComponentName,%20int%29"><code>DevicePolicyManager.setPasswordQuality()</code></a> method with a more restrictive quality constant than <code>PASSWORD_QUALITY_UNSPECIFIED</code>.
+ </li>
+ <li>[C-8-2] They MUST NOT reset the password expiration timers set by <a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordExpirationTimeout%28android.content.ComponentName,%20long%29"><code>DevicePolicyManager.setPasswordExpirationTimeout()</code></a>.
+ </li>
+ <li>[C-8-3] They MUST NOT authenticate access to keystores when the application sets <code>true</code> for <a href="https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder.html#setUserAuthenticationRequired%28boolean%29"><code>KeyGenParameterSpec.Builder.setUserAuthenticationRequired()</code></a>).
+ </li>
+ </ul>
+ <h4 id="9_11_2_strongbox">
+ 9.11.2. StrongBox
+ </h4>
+ <p>
+ The <a href="https://developer.android.com/training/articles/keystore.html">Android Keystore System</a> allows app developers to store cryptographic keys in a dedicated secure processor as well as the isolated execution environment described above.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to support StrongBox.
+ </li>
+ </ul>
+ <p>
+ If device implementations support StrongBox, they:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-1-1] MUST declare <a href="https://developer.android.com/reference/kotlin/android/content/pm/PackageManager#FEATURE_STRONGBOX_KEYSTORE%3Akotlin.String">FEATURE_STRONGBOX_KEYSTORE</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-2] MUST provide dedicated secure hardware that is used to back keystore and secure user authentication.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-3] MUST have a discrete CPU that shares no cache, DRAM, coprocessors or other core resources with the application processor (AP).
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-4] MUST ensure that any peripherals shared with the AP cannot alter StrongBox processing in any way, or obtain any information from the StrongBox. The AP MAY disable or block access to StrongBox.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-5] MUST have an internal clock with reasonable accuracy (+-10%) that is immune to manipulation by the AP.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-6] MUST have a true random number generator that produces uniformly-distributed and unpredictable output.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-7] MUST have tamper resistance, including resistance against physical penetration, and glitching.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-8] MUST have side-channel resistance, including resistance against leaking information via power, timing, electromagnetic radiation, and thermal radiation side channels.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-9] MUST have secure storage which ensures confidentiality, integrity, authenticity, consistency, and freshness of the contents. The storage MUST NOT be able to be read or altered, except as permitted by the StrongBox APIs.
+ </p>
+ </li>
+ <li>
+ <p>
+ To validate compliance with [C-1-3] through [C-1-9], device implementations:
+ </p>
+ <ul>
+ <li>[C-1-10] MUST include the hardware that is certified against the Secure IC Protection Profile <a href="https://www.commoncriteriaportal.org/files/ppfiles/pp0084b_pdf.pdf">BSI-CC-PP-0084-2014</a> or evaluated by a nationally accredited testing laboratory incorporating High attack potential vulnerability assessment according to the <a href="https://www.commoncriteriaportal.org/files/supdocs/CCDB-2013-05-002.pdf">Common Criteria Application of Attack Potential to Smartcards</a>.
+ </li>
+ <li>[C-1-11] MUST include the firmware that is evaluated by a nationally accredited testing laboratory incorporating High attack potential vulnerability assessment according to the <a href="https://www.commoncriteriaportal.org/files/supdocs/CCDB-2013-05-002.pdf">Common Criteria Application of Attack Potential to Smartcards</a>.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to include the hardware that is evaluated using a Security Target, Evaluation Assurance Level (EAL) 5, augmented by AVA_VAN.5. EAL 5 certification will likely become a requirement in a future release.
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [C-SR] are STRONGLY RECOMMENDED to provide insider attack resistance (IAR), which means that an insider with access to firmware signing keys cannot produce firmware that causes the StrongBox to leak secrets, to bypass functional security requirements or otherwise enable access to sensitive user data. The recommended way to implement IAR is to allow firmware updates only when the primary user password is provided via the IAuthSecret HAL. IAR will likely become a requirement in a future release.
+ </p>
+ </li>
+ </ul>
+ <h3 id="9_12_data_deletion">
+ 9.12. Data Deletion
+ </h3>
+ <p>
+ All device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST provide users a mechanism to perform a "Factory Data Reset".
+ </li>
+ <li>[C-0-2] MUST delete all user-generated data. That is, all data except for the following:
+ <ul>
+ <li>The system image
+ </li>
+ <li>Any operating system files required by the system image
+ </li>
+ </ul>
+ </li>
+ <li>[C-0-3] MUST delete the data in such a way that will satisfy relevant industry standards such as NIST SP800-88.
+ </li>
+ <li>[C-0-4] MUST trigger the above "Factory Data Reset" process when the <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#wipeData%28int%29"><code>DevicePolicyManager.wipeData()</code></a> API is called by the primary user's Device Policy Controller app.
+ </li>
+ <li>MAY provide a fast data wipe option that conducts only a logical data erase.
+ </li>
+ </ul>
+ <h3 id="9_13_safe_boot_mode">
+ 9.13. Safe Boot Mode
+ </h3>
+ <p>
+ Android provides Safe Boot Mode, which allows users to boot up into a mode where only preinstalled system apps are allowed to run and all third-party apps are disabled. This mode, known as "Safe Boot Mode", provides the user the capability to uninstall potentially harmful third-party apps.
+ </p>
+ <p>
+ Device implementations are:
+ </p>
+ <ul>
+ <li>[SR] STRONGLY RECOMMENDED to implement Safe Boot Mode.
+ </li>
+ </ul>
+ <p>
+ If device implementations implement Safe Boot Mode, they:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-1-1] MUST provide the user an option to enter Safe Boot Mode in such a way that is uninterruptible from third-party apps installed on the device, except when the third-party app is a Device Policy Controller and has set the <a href="https://developer.android.com/reference/android/os/UserManager.html#DISALLOW_SAFE_BOOT"><code>UserManager.DISALLOW_SAFE_BOOT</code></a> flag as true.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-2] MUST provide the user the capability to uninstall any third-party apps within Safe Mode.
+ </p>
+ </li>
+ <li>
+ <p>
+ SHOULD provide the user an option to enter Safe Boot Mode from the boot menu using a workflow that is different from that of a normal boot.
+ </p>
+ </li>
+ </ul>
+ <h3 id="9_14_automotive_vehicle_system_isolation">
+ 9.14. Automotive Vehicle System Isolation
+ </h3>
+ <p>
+ Android Automotive devices are expected to exchange data with critical vehicle subsystems by using the <a href="http://source.android.com/devices/automotive.html">vehicle HAL</a> to send and receive messages over vehicle networks such as CAN bus.
+ </p>
+ <p>
+ The data exchange can be secured by implementing security features below the Android framework layers to prevent malicious or unintentional interaction with these subsystems.
+ </p>
+ <h3 id="9_15_subscription_plans">
+ 9.15. Subscription Plans
+ </h3>
+ <p>
+ "Subscription plans" refer to the billing relationship plan details provided by a mobile carrier through <a href="https://developer.android.com/reference/android/telephony/SubscriptionManager.html#setSubscriptionPlans%28int,%20java.util.List%3Candroid.telephony.SubscriptionPlan%3E%29"><code>SubscriptionManager.setSubscriptionPlans()</code></a>.
+ </p>
+ <p>
+ All device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST return subscription plans only to the mobile carrier app that has originally provided them.
+ </li>
+ <li>[C-0-2] MUST NOT remotely back up or upload subscription plans.
+ </li>
+ <li>[C-0-3] MUST only allow overrides, such as <a href="https://developer.android.com/reference/android/telephony/SubscriptionManager.html#setSubscriptionOverrideCongested%28int,%20boolean,%20long%29"><code>SubscriptionManager.setSubscriptionOverrideCongested()</code></a>, from the mobile carrier app currently providing valid subscription plans.
+ </li>
+ </ul>
+ <h2 id="10_software_compatibility_testing">
+ 10. Software Compatibility Testing
+ </h2>
+ <p>
+ Device implementations MUST pass all tests described in this section. However, note that no software test package is fully comprehensive. For this reason, device implementers are <strong>STRONGLY RECOMMENDED</strong> to make the minimum number of changes as possible to the reference and preferred implementation of Android available from the Android Open Source Project. This will minimize the risk of introducing bugs that create incompatibilities requiring rework and potential device updates.
+ </p>
+ <h3 id="10_1_compatibility_test_suite">
+ 10.1. Compatibility Test Suite
+ </h3>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-0-1] MUST pass the <a href="http://source.android.com/compatibility/index.html">Android Compatibility Test Suite (CTS)</a> available from the Android Open Source Project, using the final shipping software on the device.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-2] MUST ensure compatibility in cases of ambiguity in CTS and for any reimplementations of parts of the reference source code.
+ </p>
+ </li>
+ </ul>
+ <p>
+ The CTS is designed to be run on an actual device. Like any software, the CTS may itself contain bugs. The CTS will be versioned independently of this Compatibility Definition, and multiple revisions of the CTS may be released for Android 9.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-0-3] MUST pass the latest CTS version available at the time the device software is completed.
+ </p>
+ </li>
+ <li>
+ <p>
+ SHOULD use the reference implementation in the Android Open Source tree as much as possible.
+ </p>
+ </li>
+ </ul>
+ <h3 id="10_2_cts_verifier">
+ 10.2. CTS Verifier
+ </h3>
+ <p>
+ The CTS Verifier is included with the Compatibility Test Suite, and is intended to be run by a human operator to test functionality that cannot be tested by an automated system, such as correct functioning of a camera and sensors.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST correctly execute all applicable cases in the CTS verifier.
+ </li>
+ </ul>
+ <p>
+ The CTS Verifier has tests for many kinds of hardware, including some hardware that is optional.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-2] MUST pass all tests for hardware that they possess; for instance, if a device possesses an accelerometer, it MUST correctly execute the Accelerometer test case in the CTS Verifier.
+ </li>
+ </ul>
+ <p>
+ Test cases for features noted as optional by this Compatibility Definition Document MAY be skipped or omitted.
+ </p>
+ <ul>
+ <li>[C-0-2] Every device and every build MUST correctly run the CTS Verifier, as noted above. However, since many builds are very similar, device implementers are not expected to explicitly run the CTS Verifier on builds that differ only in trivial ways. Specifically, device implementations that differ from an implementation that has passed the CTS Verifier only by the set of included locales, branding, etc. MAY omit the CTS Verifier test.
+ </li>
+ </ul>
+ <h2 id="11_updatable_software">
+ 11. Updatable Software
+ </h2>
+ <ul>
+ <li>
+ <p>
+ [C-0-1] Device implementations MUST include a mechanism to replace the entirety of the system software. The mechanism need not perform “live” upgrades—that is, a device restart MAY be required. Any method can be used, provided that it can replace the entirety of the software preinstalled on the device. For instance, any of the following approaches will satisfy this requirement:
+ </p>
+ <ul>
+ <li>“Over-the-air (OTA)” downloads with offline update via reboot.
+ </li>
+ <li>“Tethered” updates over USB from a host PC.
+ </li>
+ <li>“Offline” updates via a reboot and update from a file on removable storage.
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [C-0-2] The update mechanism used MUST support updates without wiping user data. That is, the update mechanism MUST preserve application private data and application shared data. Note that the upstream Android software includes an update mechanism that satisfies this requirement.
+ </p>
+ </li>
+ </ul>
+ <p>
+ If the device implementations include support for an unmetered data connection such as 802.11 or Bluetooth PAN (Personal Area Network) profile, then, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support OTA downloads with offline update via reboot.
+ </li>
+ </ul>
+ <p>
+ For device implementations that are launching with Android 6.0 and later, the update mechanism SHOULD support verifying that the system image is binary identical to expected result following an OTA. The block-based OTA implementation in the upstream Android Open Source Project, added since Android 5.1, satisfies this requirement.
+ </p>
+ <p>
+ Also, device implementations SHOULD support <a href="https://source.android.com/devices/tech/ota/ab_updates.html">A/B system updates</a>. The AOSP implements this feature using the boot control HAL.
+ </p>
+ <p>
+ If an error is found in a device implementation after it has been released but within its reasonable product lifetime that is determined in consultation with the Android Compatibility Team to affect the compatibility of third-party applications, then:
+ </p>
+ <ul>
+ <li>[C-2-1] The device implementer MUST correct the error via a software update available that can be applied per the mechanism just described.
+ </li>
+ </ul>
+ <p>
+ Android includes features that allow the Device Owner app (if present) to control the installation of system updates. If the system update subsystem for devices report android.software.device_admin then, they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST implement the behavior described in the <a href="http://developer.android.com/reference/android/app/admin/SystemUpdatePolicy.html">SystemUpdatePolicy</a> class.
+ </li>
+ </ul>
+ <h2 id="12_document_changelog">
+ 12. Document Changelog
+ </h2>
+ <p>
+ For a summary of changes to the Compatibility Definition in this release:
+ </p>
+ <ul>
+ <li>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/?pretty=full&no-merges">Document changelog</a>
+ </li>
+ </ul>
+ <p>
+ For a summary of changes to individuals sections:
+ </p>
+ <ol>
+ <li>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/1_introduction?pretty=full&no-merges">Introduction</a>
+ </li>
+ <li>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/2_device_types?pretty=full&no-merges">Device Types</a>
+ </li>
+ <li>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/3_software?pretty=full&no-merges">Software</a>
+ </li>
+ <li>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/4_application-packaging?pretty=full&no-merges">Application Packaging</a>
+ </li>
+ <li>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/5_multimedia?pretty=full&no-merges">Multimedia</a>
+ </li>
+ <li>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/6_dev-tools-and-options?pretty=full&no-merges">Developer Tools and Options</a>
+ </li>
+ <li>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/7_hardware-compatibility?pretty=full&no-merges">Hardware Compatibility</a>
+ </li>
+ <li>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/8_performance-and-power?pretty=full&no-merges">Performance and Power</a>
+ </li>
+ <li>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/9_security-model?pretty=full&no-merges">Security Model</a>
+ </li>
+ <li>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/10_software-compatibility-testing?pretty=full&no-merges">Software Compatibility Testing</a>
+ </li>
+ <li>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/11_updatable-software?pretty=full&no-merges">Updatable Software</a>
+ </li>
+ <li>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/12_document-changelog?pretty=full&no-merges">Document Changelog</a>
+ </li>
+ <li>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/13_contact-us?pretty=full&no-merges">Contact Us</a>
+ </li>
+ </ol>
+ <h3 id="12_1_changelog_viewing_tips">
+ 12.1. Changelog Viewing Tips
+ </h3>
+ <p>
+ Changes are marked as follows:
+ </p>
+ <ul>
+ <li>
+ <p>
+ <strong>CDD</strong><br>
+ Substantive changes to the compatibility requirements.
+ </p>
+ </li>
+ <li>
+ <p>
+ <strong>Docs</strong><br>
+ Cosmetic or build related changes.
+ </p>
+ </li>
+ </ul>
+ <p>
+ For best viewing, append the <code>pretty=full</code> and <code>no-merges</code> URL parameters to your changelog URLs.
+ </p>
+ <h2 id="13_contact_us">
+ 13. Contact Us
+ </h2>
+ <p>
+ You can join the <a href="https://groups.google.com/forum/#!forum/android-compatibility">android-compatibility forum</a> and ask for clarifications or bring up any issues that you think the document does not cover.
+ </p>
+ </body>
+</html>
diff --git a/en/compatibility/9.0/versions.html b/en/compatibility/9.0/versions.html
new file mode 100644
index 0000000..90babb7
--- /dev/null
+++ b/en/compatibility/9.0/versions.html
@@ -0,0 +1,43 @@
+<html devsite>
+ <head>
+ <title>Permitted Version Strings for Android 9</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>As described in Section 3.2.2 of the <a
+href="android-9.0-cdd.pdf">Android 9 Compatibility Definition</a>,
+only certain strings are allowable for the system property
+<code>android.os.Build.VERSION.RELEASE</code>. The reason for this is that
+applications and web sites may rely on predictable values for this string, and
+so that end users can easily and reliably identify the version of Android
+running on their devices.</p>
+<p>Because subsequent releases of the Android software may revise this string,
+but not change any API behavior, such releases may not be accompanied by a new
+Compatibility Definition Document. This page lists the versions that are
+allowable by an Android 9-based system. The only permitted values for
+<code>android.os.Build.VERSION.RELEASE</code> for Android 9 are:</p>
+<ul>
+<li>9.0</li>
+</ul>
+
+ </body>
+</html>
diff --git a/en/compatibility/_toc-architecture.yaml b/en/compatibility/_toc-architecture.yaml
new file mode 100644
index 0000000..c20f75a
--- /dev/null
+++ b/en/compatibility/_toc-architecture.yaml
@@ -0,0 +1,173 @@
+toc:
+- title: Overview
+ path: /devices/architecture/
+- title: Hardware Abstraction Layer (HAL)
+ section:
+ - title: HALs
+ path: /devices/architecture/hal
+ - title: HAL Types
+ path: /devices/architecture/hal-types
+ - title: Framework Testing
+ path: /devices/architecture/hal/framework-testing
+ - title: Dynamic Lifecycle
+ path: /devices/architecture/hal/dynamic-lifecycle
+- title: Kernel
+ section:
+ - title: Overview
+ path: /devices/architecture/kernel/
+ - title: Stable Releases & Updates
+ path: /devices/architecture/kernel/releases
+ - title: Android Common Kernels
+ path: /devices/architecture/kernel/android-common
+ - title: Modular Kernel Requirements
+ path: /devices/architecture/kernel/modular-kernels
+ - title: Interface Requirements
+ path: /devices/architecture/kernel/reqs-interfaces
+ - title: Configuration
+ path: /devices/architecture/kernel/config
+ - title: Kernel Hardening
+ path: /devices/architecture/kernel/hardening
+ - title: SquashFS
+ path: /devices/architecture/kernel/squashfs
+ - title: LLDB Debugging
+ path: /devices/architecture/kernel/lldb-debug
+ - title: Network Tests
+ path: /devices/architecture/kernel/network_tests
+- title: HIDL (General)
+ section:
+ - title: Overview
+ path: /devices/architecture/hidl/
+ - title: Interfaces & Packages
+ path: /devices/architecture/hidl/interfaces
+ - title: Interface Hashing
+ path: /devices/architecture/hidl/hashing
+ - title: Services & Data Transfer
+ path: /devices/architecture/hidl/services
+ - title: Fast Message Queue
+ path: /devices/architecture/hidl/fmq
+ - title: Using Binder IPC
+ path: /devices/architecture/hidl/binder-ipc
+ - title: Using MemoryBlock
+ path: /devices/architecture/hidl/memoryblock
+ - title: Network Stack Configuration Tools
+ path: /devices/architecture/hidl/network-stack
+ - title: Threading Models
+ path: /devices/architecture/hidl/threading
+ - title: Converting Modules
+ path: /devices/architecture/hidl/converting
+ - title: Data Types
+ path: /devices/architecture/hidl/types
+ - title: Versioning
+ path: /devices/architecture/hidl/versioning
+ - title: Code Style Guide
+ path: /devices/architecture/hidl/code-style
+- title: HIDL (C++)
+ section:
+ - title: Overview
+ path: /devices/architecture/hidl-cpp/
+ - title: Packages
+ path: /devices/architecture/hidl-cpp/packages
+ - title: Interfaces
+ path: /devices/architecture/hidl-cpp/interfaces
+ - title: Data Types
+ path: /devices/architecture/hidl-cpp/types
+ - title: Functions
+ path: /devices/architecture/hidl-cpp/functions
+- title: HIDL (Java)
+ section:
+ - title: Overview
+ path: /devices/architecture/hidl-java/
+ - title: Data Types
+ path: /devices/architecture/hidl-java/types
+ - title: Interface Errors & Methods
+ path: /devices/architecture/hidl-java/interfaces
+ - title: Exporting Constants
+ path: /devices/architecture/hidl-java/constants
+- title: ConfigStore HAL
+ section:
+ - title: Overview
+ path: /devices/architecture/configstore/
+ - title: Creating the HAL Interface
+ path: /devices/architecture/configstore/interface
+ - title: Implementing the Service
+ path: /devices/architecture/configstore/service
+ - title: Client-Side Usage
+ path: /devices/architecture/configstore/client
+ - title: Adding Classes & Items
+ path: /devices/architecture/configstore/add-class-item
+- title: Device Tree Overlays
+ section:
+ - title: Overview
+ path: /devices/architecture/dto/
+ - title: Implementing DTO
+ path: /devices/architecture/dto/implement
+ - title: DTO Syntax
+ path: /devices/architecture/dto/syntax
+ - title: Compiling & Verifying
+ path: /devices/architecture/dto/compile
+ - title: Using Multiple DTs
+ path: /devices/architecture/dto/multiple
+ - title: DTB/DTBO Partition Format
+ path: /devices/architecture/dto/partitions
+ - title: Optimizing DTO
+ path: /devices/architecture/dto/optimize
+- title: Vendor NDK
+ section:
+ - title: Overview
+ path: /devices/architecture/vndk/
+ - title: Enabling the VNDK
+ path: /devices/architecture/vndk/enabling
+ - title: VNDK Build System Support
+ path: /devices/architecture/vndk/build-system
+ - title: VNDK Extensions
+ path: /devices/architecture/vndk/extensions
+ - title: VNDK Definition Tool
+ path: /devices/architecture/vndk/deftool
+ - title: VNDK Snapshot Design
+ path: /devices/architecture/vndk/snapshot-design
+ - title: Generating VNDK Snapshots
+ path: /devices/architecture/vndk/snapshot-generate
+ - title: Linker Namespace
+ path: /devices/architecture/vndk/linker-namespace
+ - title: Directories, Rules, and sepolicy
+ path: /devices/architecture/vndk/dir-rules-sepolicy
+ - title: Renderscript
+ path: /devices/architecture/vndk/renderscript
+ - title: ABI Stability
+ path: /devices/architecture/vndk/abi-stability
+- title: Vendor Interface Object
+ section:
+ - title: Overview
+ path: /devices/architecture/vintf/
+ - title: Manifests
+ path: /devices/architecture/vintf/objects
+ - title: Compatibility Matrices
+ path: /devices/architecture/vintf/comp-matrices
+ - title: FCM Lifecycle
+ path: /devices/architecture/vintf/fcm
+ - title: DM Development
+ path: /devices/architecture/vintf/dm
+ - title: Matching Rules
+ path: /devices/architecture/vintf/match-rules
+ - title: Resources
+ path: /devices/architecture/vintf/resources
+- title: Bootloader
+ section:
+ - title: Overview
+ path: /devices/bootloader
+ - title: Boot Reason
+ path: /devices/bootloader/boot-reason
+ - title: Boot Image Header
+ path: /devices/bootloader/boot-image-header
+ - title: System as Root
+ path: /devices/bootloader/system-as-root
+ - title: Partitions and Images
+ path: /devices/bootloader/partitions-images
+ - title: Product Partitions
+ path: /devices/bootloader/product-partitions
+ - title: Recovery Image
+ path: /devices/bootloader/recovery-image
+ - title: Flashing and Updating
+ path: /devices/bootloader/flashing-updating
+ - title: Unlocking and Trusty
+ path: /devices/bootloader/unlock-trusty
diff --git a/en/compatibility/_toc-compatibility.yaml b/en/compatibility/_toc-compatibility.yaml
index d45a865..20f2abb 100644
--- a/en/compatibility/_toc-compatibility.yaml
+++ b/en/compatibility/_toc-compatibility.yaml
@@ -1,71 +1,9 @@
toc:
-- title: Introduction
- path: /compatibility/
-- title: Program Overview
+- title: Overview
path: /compatibility/overview
-- title: Compatibility Definition
- section:
- - title: Overview
- path: /compatibility/cdd/
- - title: CDD in HTML
- path: /compatibility/android-cdd
- - title: CDD in PDF
- path: /compatibility/android-cdd.pdf
-- title: Compatibility Test Suite
- section:
- - title: Overview
- path: /compatibility/cts/
- - title: Set up CTS
- path: /compatibility/cts/setup
- - title: Run CTS
- path: /compatibility/cts/run
- - title: Run CTS Verifier
- section:
- - title: Overview
- path: /compatibility/cts/verifier
- - title: Audio Framework
- path: /compatibility/cts/audio-framework
- - title: Near Ultrasound Tests
- path: /compatibility/cts/near-ultrasound
- - title: Rotation Vector Crosscheck
- path: /compatibility/cts/rotation-vector
- - title: USB Audio CTS Tests
- path: /compatibility/cts/usb-audio
- - title: Camera Testing
- section:
- - title: Camera HAL Testing
- path: /compatibility/cts/camera-hal
- - title: Camera ITS-in-a-Box
- path: /compatibility/cts/camera-its-box
- - title: Camera ITS-in-a-Box Assembly
- path: /compatibility/cts/camera-its-box-assembly
- - title: Interpret Results
- path: /compatibility/cts/interpret
- - title: Develop CTS
- path: /compatibility/cts/development
- - title: Downloads
- path: /compatibility/cts/downloads
-- title: Contact Us
- path: /compatibility/contact-us
-- title: Vendor Test Suite (VTS)
- section:
- - title: Overview
- path: /compatibility/vts/
- - title: Systems Testing with VTS
- path: /compatibility/vts/systems
- - title: Test Framework
- section:
- - title: Device Shell Commands
- path: /compatibility/vts/shell-commands
- - title: Test Templates
- path: /compatibility/vts/test-templates
- - title: Multi-Device Testing
- path: /compatibility/vts/multi-device-testing
- - title: VTS Dashboard Setup
- path: /compatibility/vts/setup
- - title: VTS Dashboard Database
- path: /compatibility/vts/database
- - title: VTS Dashboard UI
- path: /compatibility/vts/ui
- - title: Performance Testing
- path: /compatibility/vts/performance
\ No newline at end of file
+- title: Compatibility Definition Document
+ path: /compatibility/cdd/
+- title: CDD in HTML
+ path: /compatibility/android-cdd
+- title: CDD in PDF
+ path: /compatibility/android-cdd.pdf
diff --git a/en/compatibility/_toc-display.yaml b/en/compatibility/_toc-display.yaml
new file mode 100644
index 0000000..bcc5cf0
--- /dev/null
+++ b/en/compatibility/_toc-display.yaml
@@ -0,0 +1,35 @@
+toc:
+- title: Overview
+ path: /devices/tech/display/
+- title: Adaptive Icons
+ path: /devices/tech/display/adaptive-icons
+- title: App Shortcuts
+ path: /devices/tech/display/app-shortcuts
+- title: Circular Icons
+ path: /devices/tech/display/circular-icons
+- title: Color Management
+ path: /devices/tech/display/color-mgmt
+- title: Display Cutouts
+ path: /devices/tech/display/display-cutouts
+- title: Do Not Disturb
+ path: /devices/tech/display/dnd
+- title: HDR Video
+ path: /devices/tech/display/hdr
+- title: Multi-Window
+ path: /devices/tech/display/multi-window
+- title: Night Light
+ path: /devices/tech/display/night-light
+- title: Picture-in-picture
+ path: /devices/tech/display/pip
+- title: Retail Demo Mode
+ path: /devices/tech/display/retail-mode
+- title: Rotate Suggestions
+ path: /devices/tech/display/rotate-suggestions
+- title: Split-Screen Interactions
+ path: /devices/tech/display/split-screen
+- title: Synchronized App Transitions
+ path: /devices/tech/display/synched-app-transitions
+- title: Text Classification
+ path: /devices/tech/display/textclassifier
+- title: Widgets & Shortcuts
+ path: /devices/tech/display/widgets-shortcuts
diff --git a/en/compatibility/_toc-purpose.yaml b/en/compatibility/_toc-purpose.yaml
new file mode 100644
index 0000000..10af730
--- /dev/null
+++ b/en/compatibility/_toc-purpose.yaml
@@ -0,0 +1,3 @@
+toc:
+- title: Design an Android Device
+ path: /compatibility/
diff --git a/en/compatibility/_toc-settings.yaml b/en/compatibility/_toc-settings.yaml
new file mode 100644
index 0000000..7145959
--- /dev/null
+++ b/en/compatibility/_toc-settings.yaml
@@ -0,0 +1,11 @@
+toc:
+- title: Design Guidelines
+ path: /devices/tech/settings/settings-guidelines
+- title: Patterns and Components
+ path: /devices/tech/settings/patterns-components
+- title: Information Architecture
+ path: /devices/tech/settings/info-architecture
+- title: Personalized Settings
+ path: /devices/tech/settings/personalized
+- title: Universal Search
+ path: /devices/tech/settings/universal-search
diff --git a/en/compatibility/_toc-tests.yaml b/en/compatibility/_toc-tests.yaml
new file mode 100644
index 0000000..fd5d66f
--- /dev/null
+++ b/en/compatibility/_toc-tests.yaml
@@ -0,0 +1,127 @@
+toc:
+- title: Overview
+ path: /compatibility/tests
+- title: Compatibility Test Suite
+ section:
+ - title: Overview
+ path: /compatibility/cts/
+ - title: Set up CTS
+ path: /compatibility/cts/setup
+ - title: Run CTS
+ path: /compatibility/cts/run
+ - title: Run CTS Verifier
+ section:
+ - title: Overview
+ path: /compatibility/cts/verifier
+ - title: Audio Framework
+ path: /compatibility/cts/audio-framework
+ - title: Near Ultrasound Tests
+ path: /compatibility/cts/near-ultrasound
+ - title: Rotation Vector Crosscheck
+ path: /compatibility/cts/rotation-vector
+ - title: USB Audio CTS Tests
+ path: /compatibility/cts/usb-audio
+ - title: Camera Testing
+ section:
+ - title: Camera HAL Testing
+ path: /compatibility/cts/camera-hal
+ - title: Camera ITS-in-a-Box
+ path: /compatibility/cts/camera-its-box
+ - title: Camera ITS-in-a-Box Assembly
+ path: /compatibility/cts/camera-its-box-assembly
+ - title: Sensor Fusion Box Quick Start
+ path: /compatibility/cts/sensor-fusion-quick-start
+ - title: Sensor Fusion Box Assembly
+ path: /compatibility/cts/sensor-fusion-box-assembly
+ - title: Secure Element
+ path: /compatibility/cts/secure-element
+ - title: Interpret Results
+ path: /compatibility/cts/interpret
+ - title: Develop CTS
+ path: /compatibility/cts/development
+ - title: Downloads
+ path: /compatibility/cts/downloads
+- title: Vendor Test Suite (VTS)
+ section:
+ - title: Overview
+ path: /compatibility/vts/
+ - title: Systems Testing with VTS
+ path: /compatibility/vts/systems
+ - title: Test Framework
+ section:
+ - title: Device Shell Commands
+ path: /compatibility/vts/shell-commands
+ - title: Test Templates
+ path: /compatibility/vts/test-templates
+ - title: Service Name Aware HAL Testing
+ path: /compatibility/vts/sna-hal-testing
+ - title: HAL Testability Check
+ path: /compatibility/vts/hal-testability
+ - title: Multi-Device Testing
+ path: /compatibility/vts/multi-device-testing
+ - title: VTS Dashboard
+ section:
+ - title: Setup
+ path: /compatibility/vts/setup
+ - title: Database
+ path: /compatibility/vts/database
+ - title: User Interface
+ path: /compatibility/vts/ui
+ - title: Lab Infrastructure
+ section:
+ - title: Automated Testing Infrastructure
+ path: /compatibility/vts/automated-test-infra
+ - title: Host Controller Architecture
+ path: /compatibility/vts/host-controller
+ - title: Performance Testing
+ path: /compatibility/vts/performance
+- title: Testing Infrastructure
+ section:
+ - title: Overview
+ path: /devices/tech/test_infra/tradefed/
+ - title: Start Here
+ path: /devices/tech/test_infra/tradefed/fundamentals
+ - title: Machine Setup
+ path: /devices/tech/test_infra/tradefed/fundamentals/machine_setup
+ - title: Working with Devices
+ path: /devices/tech/test_infra/tradefed/fundamentals/devices
+ - title: Test Lifecycle
+ path: /devices/tech/test_infra/tradefed/fundamentals/lifecycle
+ - title: Option Handling
+ path: /devices/tech/test_infra/tradefed/fundamentals/options
+ - title: An End-to-End Example
+ path: /devices/tech/test_infra/tradefed/full_example
+ - title: Package Index
+ path: /reference/tradefed/
+- title: Debugging
+ section:
+ - title: Overview
+ path: /devices/tech/debug/
+ - title: Diagnosing Native Crashes
+ path: /devices/tech/debug/native-crash
+ - title: Evaluating Performance
+ section:
+ - title: Overview
+ path: /devices/tech/debug/eval_perf
+ - title: Understanding systrace
+ path: /devices/tech/debug/systrace
+ - title: Using ftrace
+ path: /devices/tech/debug/ftrace
+ - title: Identifying Capacity Jank
+ path: /devices/tech/debug/jank_capacity
+ - title: Identifying Jitter Jank
+ path: /devices/tech/debug/jank_jitter
+ - title: Using GDB
+ path: /devices/tech/debug/gdb
+ - title: Native Memory Use
+ path: /devices/tech/debug/native-memory
+ - title: Network Connectivity Tests
+ path: /devices/tech/connect/connect_tests
+ - title: Rescue Party
+ path: /devices/tech/debug/rescue-party
+ - title: Storaged
+ path: /devices/tech/debug/storaged
+ - title: Strace
+ path: /devices/tech/debug/strace
+ - title: Valgrind
+ path: /devices/tech/debug/valgrind
diff --git a/en/compatibility/android-cdd.html b/en/compatibility/android-cdd.html
index 52557f9..8f93b15 100644
--- a/en/compatibility/android-cdd.html
+++ b/en/compatibility/android-cdd.html
@@ -1,10 +1,10 @@
-<html devsite="" xmlns="http://www.w3.org/1999/xhtml">
+<html devsite="">
<head>
<title>
- Android 8.1 Compatibility Definition
+ Android 9 Compatibility Definition
</title>
- <meta name="project_path" value="/_project.yaml" />
- <meta name="book_path" value="/_book.yaml" />
+ <meta name="project_path" value="/_project.yaml">
+ <meta name="book_path" value="/_book.yaml">
</head>
<body>
<!--
@@ -26,19 +26,19 @@
1. Introduction
</h2>
<p>
- This document enumerates the requirements that must be met in order for devices to be compatible with Android 8.1.
+ This document enumerates the requirements that must be met in order for devices to be compatible with Android 9.
</p>
<p>
The use of “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” is per the IETF standard defined in <a href="http://www.ietf.org/rfc/rfc2119.txt">RFC2119</a>.
</p>
<p>
- As used in this document, a “device implementer” or “implementer” is a person or organization developing a hardware/software solution running Android 8.1. A “device implementation” or “implementation is the hardware/software solution so developed.
+ As used in this document, a “device implementer” or “implementer” is a person or organization developing a hardware/software solution running Android 9. A “device implementation” or “implementation" is the hardware/software solution so developed.
</p>
<p>
- To be considered compatible with Android 8.1, device implementations MUST meet the requirements presented in this Compatibility Definition, including any documents incorporated via reference.
+ To be considered compatible with Android 9, device implementations MUST meet the requirements presented in this Compatibility Definition, including any documents incorporated via reference.
</p>
<p>
- Where this definition or the software tests described in <a href="#10_software_compatibility_testing">section 10</a> is silent, ambiguous, or incomplete, it is the responsibility of the device implementer to ensure compatibility with existing implementations.
+ Where this definition or the software tests described in <a href="#10_software_compatibility_testing">section 10</a> are silent, ambiguous, or incomplete, it is the responsibility of the device implementer to ensure compatibility with existing implementations.
</p>
<p>
For this reason, the <a href="http://source.android.com/">Android Open Source Project</a> is both the reference and preferred implementation of Android. Device implementers are STRONGLY RECOMMENDED to base their implementations to the greatest extent possible on the “upstream” source code available from the Android Open Source Project. While some components can hypothetically be replaced with alternate implementations, it is STRONGLY RECOMMENDED to not follow this practice, as passing the software tests will become substantially more difficult. It is the implementer’s responsibility to ensure full behavioral compatibility with the standard Android implementation, including and beyond the Compatibility Test Suite. Finally, note that certain component substitutions and modifications are explicitly forbidden by this document.
@@ -53,7 +53,7 @@
1.1.1. Requirements by Device Type
</h4>
<p>
- <a href="#2_device_types">Section 2</a> contains all the MUST and STRONGLY RECOMMENDED requirements that apply to a specific device type. Each subsection of <a href="#2_device_types">Section 2</a> is dedicated to a specific device type.
+ <a href="#2_device_types">Section 2</a> contains all of the requirements that apply to a specific device type. Each subsection of <a href="#2_device_types">Section 2</a> is dedicated to a specific device type.
</p>
<p>
All the other requirements, that universally apply to any Android device implementations, are listed in the sections after <a href="#2_device_types">Section 2</a>. These requirements are referenced as "Core Requirements" in this document.
@@ -76,7 +76,7 @@
Each ID is defined as below:
</p>
<ul>
- <li>Device Type ID (see more on <a href="#2_device_types">2. Device Types</a>
+ <li>Device Type ID (see more in <a href="#2_device_types">2. Device Types</a>)
<ul>
<li>C: Core (Requirements that are applied to any Android device implementations)
</li>
@@ -86,13 +86,15 @@
</li>
<li>A: Android Automotive implementation
</li>
+ <li>Tab: Android Tablet implementation
+ </li>
</ul>
</li>
<li>Condition ID
<ul>
<li>When the requirement is unconditional, this ID is set as 0.
</li>
- <li>When the requirement is conditional, 1 is assinged for the 1st condition and the number increments by 1 within the same section and the same device type.
+ <li>When the requirement is conditional, 1 is assigned for the 1st condition and the number increments by 1 within the same section and the same device type.
</li>
</ul>
</li>
@@ -103,6 +105,16 @@
</ul>
</li>
</ul>
+ <h4 id="1_1_3_requirement_id_in_section_2">
+ 1.1.3. Requirement ID in Section 2
+ </h4>
+ <p>
+ The Requirement ID in <a href="#2_device_types">Section 2</a> starts with the corresponding section ID that is followed by the Requirement ID described above.
+ </p>
+ <ul>
+ <li>The ID in <a href="#2_device_types">Section 2</a> consists of : Section ID / Device Type ID - Condition ID - Requirement ID (e.g. 7.4.3/A-0-1).
+ </li>
+ </ul>
<h2 id="2_device_types">
2. Device Types
</h2>
@@ -146,590 +158,443 @@
2.2.1. Hardware
</h4>
<p>
- <strong>Screen Size (Section 7.1.1.1)</strong>
- </p>
- <p>
Handheld device implementations:
</p>
<ul>
- <li>[H-0-1] MUST have a screen at least 2.5 inches in physical diagonal size.<sup>*</sup>
+ <li>[<a href="#7_1_display_and_graphics">7.1</a>.1.1/H-0-1] MUST have a screen at least 2.5 inches in physical diagonal size.
+ </li>
+ <li>[<a href="#7_1_display_and_graphics">7.1</a>.1.3/H-SR] Are STRONGLY RECOMMENDED to provide users an affordance to change the display size.(Screen Density)
</li>
</ul>
<p>
- <strong>Screen Density (Section 7.1.1.3)</strong>
- </p>
- <p>
- Handheld device implementations:
+ If Handheld device implementations claim support for high dynamic range displays through <a href="https://developer.android.com/reference/android/content/res/Configuration.html#isScreenHdr%28%29"><code>Configuration.isScreenHdr()</code></a> , they:
</p>
<ul>
- <li>[H-SR] Are STRONGLY RECOMMENDED to provide users an affordance to change the display size.
+ <li>[<a href="#7_1_display-and-graphics">7.1</a>.4.5/H-1-1] MUST advertise support for the <code>EGL_EXT_gl_colorspace_bt2020_pq</code>, <code>EGL_EXT_surface_SMPTE2086_metadata</code>, <code>EGL_EXT_surface_CTA861_3_metadata</code>, <code>VK_EXT_swapchain_colorspace</code>, and <code>VK_EXT_hdr_metadata</code> extensions.
</li>
</ul>
<p>
- <strong>Legacy Application Compatibility Mode (Section 7.1.5)</strong>
- </p>
- <p>
Handheld device implementations:
</p>
<ul>
- <li>[H-0-1] MUST include support for legacy application compatibility mode as implemented by the upstream Android open source code. That is, device implementations MUST NOT alter the triggers or thresholds at which compatibility mode is activated, and MUST NOT alter the behavior of the compatibility mode itself.
+ <li>[<a href="#7_1_display_and_graphics">7.1</a>.5/H-0-1] MUST include support for legacy application compatibility mode as implemented by the upstream Android open source code. That is, device implementations MUST NOT alter the triggers or thresholds at which compatibility mode is activated, and MUST NOT alter the behavior of the compatibility mode itself.
</li>
- </ul>
- <p>
- <strong>Keyboard (Section 7.2.1)</strong>
- </p>
- <p>
- Handheld device implementations:
- </p>
- <ul>
- <li>[H-0-1] MUST include support for third-party Input Method Editor (IME) applications.
+ <li>[<a href="#7_2_input_devices">7.2</a>.1/H-0-1] MUST include support for third-party Input Method Editor (IME) applications.
</li>
- </ul>
- <p>
- <strong>Navigation Keys (Section 7.2.3)</strong>
- </p>
- <p>
- Handheld device implementations:
- </p>
- <ul>
- <li>
- <p>
- [H-0-1] MUST provide the Home, Recents, and Back functions.
- </p>
+ <li>[<a href="#7_2_input_devices">7.2</a>.3/H-0-1] MUST provide the Home, Recents, and Back functions.
</li>
- <li>
- <p>
- [H-0-2] MUST send both the normal and long press event of the the Back function (<a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_BACK"><code>KEYCODE_BACK</code></a>) to the foreground application.
- </p>
+ <li>[<a href="#7_2_input_devices">7.2</a>.3/H-0-2] MUST send both the normal and long press event of the Back function (<a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_BACK"><code>KEYCODE_BACK</code></a>) to the foreground application. These events MUST NOT be consumed by the system and CAN be triggered by outside of the Android device (e.g. external hardware keyboard connected to the Android device).
</li>
- </ul>
- <p>
- <strong>Touchscreen Input (Section 7.2.4)</strong>
- </p>
- <p>
- Handheld device implementations:
- </p>
- <ul>
- <li>[H-0-1] MUST support touchscreen input.
+ <li>[<a href="#7_2_input_devices">7.2</a>.4/H-0-1] MUST support touchscreen input.
</li>
- </ul>
- <p>
- <strong>Accelerometer (Section 7.3.1)</strong>
- </p>
- <p>
- Handheld device implementations:
- </p>
- <ul>
- <li>[H-SR] Are STRONGLY RECOMMENDED to include a 3-axis accelerometer.
+ <li>[<a href="#7_2_input_devices">7.2</a>.4/H-SR] Are STRONGLY RECOMMENDED to launch the user-selected assist app, in other words the app that implements VoiceInteractionService, or an activity handling the <a href="https://developer.android.com/reference/android/content/Intent#ACTION_ASSIST"><code>ACTION_ASSIST</code></a> on long-press of <a href="https://developer.android.com/reference/android/view/KeyEvent#KEYCODE_MEDIA_PLAY_PAUSE"><code>KEYCODE_MEDIA_PLAY_PAUSE</code></a> or <a href="https://developer.android.com/reference/android/view/KeyEvent#KEYCODE_HEADSETHOOK"><code>KEYCODE_HEADSETHOOK</code></a> if the foreground activity does not handle those long-press events.
+ </li>
+ <li>[<a href="#7_3_sensors">7.3</a>.1/H-SR] Are STRONGLY RECOMMENDED to include a 3-axis accelerometer.
</li>
</ul>
<p>
If Handheld device implementations include a 3-axis accelerometer, they:
</p>
<ul>
- <li>[H-1-1] MUST be able to report events up to a frequency of at least 100 Hz.
+ <li>[<a href="#7_3_sensors">7.3</a>.1/H-1-1] MUST be able to report events up to a frequency of at least 100 Hz.
</li>
</ul>
<p>
- <strong>Gyroscope (Section 7.3.4)</strong>
- </p>
- <p>
If Handheld device implementations include a gyroscope, they:
</p>
<ul>
- <li>[H-1-1] MUST be able to report events up to a frequency of at least 100 Hz.
+ <li>[<a href="#7_3_sensors">7.3</a>.4/H-1-1] MUST be able to report events up to a frequency of at least 100 Hz.
</li>
</ul>
<p>
- <strong>Proximity Sensor (Section 7.3.8 )</strong>
- </p>
- <p>
Handheld device implementations that can make a voice call and indicate any value other than <code>PHONE_TYPE_NONE</code> in <code>getPhoneType</code>:
</p>
<ul>
- <li>SHOULD include a proximity sensor.
+ <li>[<a href="#7_3_sensors">7.3</a>.8/H] SHOULD include a proximity sensor.
</li>
</ul>
<p>
- <strong>Pose Sensor (Section 7.3.12)</strong>
- </p>
- <p>
Handheld device implementations:
</p>
<ul>
- <li>Are RECOMMENDED to support pose sensor with 6 degrees of freedom.
+ <li>[<a href="#7_3_sensors">7.3</a>.12/H-SR] Are RECOMMENDED to support pose sensor with 6 degrees of freedom.
+ </li>
+ <li>[<a href="#7_4_data_connectivity">7.4</a>.3/H] SHOULD include support for Bluetooth and Bluetooth LE.
</li>
</ul>
<p>
- <strong>Bluetooth (Section 7.4.3)</strong>
- </p>
- <p>
- Handheld device implementations:
- </p>
- <ul>
- <li>SHOULD include support for Bluetooth and Bluetooth LE.
- </li>
- </ul>
- <p>
- <strong>Data Saver (Section 7.4.7)</strong>
- </p>
- <p>
If Handheld device implementations include a metered connection, they:
</p>
<ul>
- <li>[H-1-1] MUST provide the data saver mode.
+ <li>[<a href="#7_4_data_connectivity">7.4</a>.7/H-1-1] MUST provide the data saver mode.
</li>
</ul>
<p>
- <strong>Minimum Memory and Storage (Section 7.6.1)</strong>
+ Handheld device implementations:
</p>
+ <ul>
+ <li>[<a href="#7_6_memory_and_storage">7.6</a>.1/H-0-1] MUST have at least 4 GB of non-volatile storage available for application private data (a.k.a. "/data" partition).
+ </li>
+ <li>[<a href="#7_6_memory_and_storage">7.6</a>.1/H-0-2] MUST return “true” for <code>ActivityManager.isLowRamDevice()</code> when there is less than 1GB of memory available to the kernel and userspace.
+ </li>
+ </ul>
<p>
- If Handheld device implementations declare support of only a 32-bit ABI:
+ If Handheld device implementations are 32-bit:
</p>
<ul>
<li>
<p>
- [H-1-1] The memory available to the kernel and userspace MUST be at least 416MB if the default display uses framebuffer resolutions up to qHD (e.g. FWVGA).
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/H-1-1] The memory available to the kernel and userspace MUST be at least 512MB if any of the following densities are used:
</p>
+ <ul>
+ <li>280dpi or lower on small/normal screens<sup>*</sup>
+ </li>
+ <li>ldpi or lower on extra large screens
+ </li>
+ <li>mdpi or lower on large screens
+ </li>
+ </ul>
</li>
<li>
<p>
- [H-2-1] The memory available to the kernel and userspace MUST be at least 592MB if the default display uses framebuffer resolutions up to HD+ (e.g. HD, WSVGA).
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/H-2-1] The memory available to the kernel and userspace MUST be at least 608MB if any of the following densities are used:
</p>
+ <ul>
+ <li>xhdpi or higher on small/normal screens<sup>*</sup>
+ </li>
+ <li>hdpi or higher on large screens
+ </li>
+ <li>mdpi or higher on extra large screens
+ </li>
+ </ul>
</li>
<li>
<p>
- [H-3-1] The memory available to the kernel and userspace MUST be at least 896MB if the default display uses framebuffer resolutions up to FHD (e.g. WSXGA+).
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/H-3-1] The memory available to the kernel and userspace MUST be at least 896MB if any of the following densities are used:
</p>
+ <ul>
+ <li>400dpi or higher on small/normal screens<sup>*</sup>
+ </li>
+ <li>xhdpi or higher on large screens
+ </li>
+ <li>tvdpi or higher on extra large screens
+ </li>
+ </ul>
</li>
<li>
<p>
- [H-4-1] The memory available to the kernel and userspace MUST be at least 1344MB if the default display uses framebuffer resolutions up to QHD (e.g. QWXGA).
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/H-4-1] The memory available to the kernel and userspace MUST be at least 1344MB if any of the following densities are used:
</p>
+ <ul>
+ <li>560dpi or higher on small/normal screens<sup>*</sup>
+ </li>
+ <li>400dpi or higher on large screens
+ </li>
+ <li>xhdpi or higher on extra large screens
+ </li>
+ </ul>
</li>
</ul>
<p>
- If Handheld device implementations declare support of 32-bit and 64-bit ABIs:
+ If Handheld device implementations are 64-bit:
</p>
<ul>
<li>
<p>
- [H-5-1] The memory available to the kernel and userspace MUST be at least 816MB if the default display uses framebuffer resolutions up to qHD (e.g. FWVGA).
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/H-5-1] The memory available to the kernel and userspace MUST be at least 816MB if any of the following densities are used:
</p>
+ <ul>
+ <li>280dpi or lower on small/normal screens<sup>*</sup>
+ </li>
+ <li>ldpi or lower on extra large screens
+ </li>
+ <li>mdpi or lower on large screens
+ </li>
+ </ul>
</li>
<li>
<p>
- [H-6-1] The memory available to the kernel and userspace MUST be at least 944MB if the default display uses framebuffer resolutions up to HD+ (e.g. HD, WSVGA).
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/H-6-1] The memory available to the kernel and userspace MUST be at least 944MB if any of the following densities are used:
</p>
+ <ul>
+ <li>xhdpi or higher on small/normal screens<sup>*</sup>
+ </li>
+ <li>hdpi or higher on large screens
+ </li>
+ <li>mdpi or higher on extra large screens
+ </li>
+ </ul>
</li>
<li>
<p>
- [H-7-1] The memory available to the kernel and userspace MUST be at least 1280MB if the default display uses framebuffer resolutions up to FHD (e.g. WSXGA+).
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/H-7-1] The memory available to the kernel and userspace MUST be at least 1280MB if any of the following densities are used:
</p>
+ <ul>
+ <li>400dpi or higher on small/normal screens<sup>*</sup>
+ </li>
+ <li>xhdpi or higher on large screens
+ </li>
+ <li>tvdpi or higher on extra large screens
+ </li>
+ </ul>
</li>
<li>
<p>
- [H-8-1] The memory available to the kernel and userspace MUST be at least 1824MB if the default display uses framebuffer resolutions up to QHD (e.g. QWXGA).
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/H-8-1] The memory available to the kernel and userspace MUST be at least 1824MB if any of the following densities are used:
</p>
+ <ul>
+ <li>560dpi or higher on small/normal screens<sup>*</sup>
+ </li>
+ <li>400dpi or higher on large screens
+ </li>
+ <li>xhdpi or higher on extra large screens
+ </li>
+ </ul>
</li>
</ul>
<p>
Note that the "memory available to the kernel and userspace" above refers to the memory space provided in addition to any memory already dedicated to hardware components such as radio, video, and so on that are not under the kernel’s control on device implementations.
</p>
<p>
- If Handheld device implementations include less than or equal to 1GB of memory available to the kernel and userspace, they:
- </p>
- <ul>
- <li>[H-9-1] MUST declare the feature flag <a href="https://developer.android.com/reference/android/content/pm/PackageManager.html#FEATURE_RAM_LOW"><code>android.hardware.ram.low</code></a>.
- </li>
- <li>[H-9-2] MUST have at least 1.1 GB of non-volatile storage for application private data (a.k.a. "/data" partition).
- </li>
- </ul>
- <p>
- If Handheld device implementations include more than 1GB of memory available to the kernel and userspace, they:
- </p>
- <ul>
- <li>[H-10-1] MUST have at least 4GB of non-volatile storage available for application private data (a.k.a. "/data" partition).
- </li>
- <li>SHOULD declare the feature flag <a href="https://developer.android.com/reference/android/content/pm/PackageManager.html#FEATURE_RAM_NORMAL"><code>android.hardware.ram.normal</code></a>.
- </li>
- </ul>
- <p>
- <strong>Application Shared Storage (Section 7.6.2)</strong>
- </p>
- <p>
Handheld device implementations:
</p>
<ul>
- <li>[H-0-1] MUST NOT provide an application shared storage smaller than 1 GiB.
+ <li>[<a href="#7_6_memory_and_storage">7.6</a>.2/H-0-1] MUST NOT provide an application shared storage smaller than 1 GiB.
</li>
- </ul>
- <p>
- <strong>USB peripheral mode (Section 7.7.1)</strong>
- </p>
- <p>
- Handheld device implementations:
- </p>
- <ul>
- <li>SHOULD include a USB port supporting peripheral mode.
+ <li>[<a href="#7_7_usb">7.7</a>.1/H] SHOULD include a USB port supporting peripheral mode.
</li>
</ul>
<p>
If handheld device implementations include a USB port supporting peripheral mode, they:
</p>
<ul>
- <li>[H-1-1] MUST implement the Android Open Accessory (AOA) API.<sup>*</sup>
+ <li>[<a href="#7_7_usb">7.7</a>.1/H-1-1] MUST implement the Android Open Accessory (AOA) API.
</li>
</ul>
<p>
- <strong>Microphone (Section 7.8.1)</strong>
- </p>
- <p>
Handheld device implementations:
</p>
<ul>
- <li>[H-0-1] MUST include a microphone.
+ <li>[<a href="#7_8_audio">7.8</a>.1/H-0-1] MUST include a microphone.
+ </li>
+ <li>[<a href="#7_8_audio">7.8</a>.2/H-0-1] MUST have an audio output and declare <code>android.hardware.audio.output</code>.
</li>
</ul>
<p>
- <strong>Audio Output (Section 7.8.2)</strong>
- </p>
- <p>
- Handheld device implementations:
+ If Handheld device implementations are capable of meeting all the performance requirements for supporting VR mode and include support for it, they:
</p>
<ul>
- <li>[H-0-1] MUST have an audio output and declare <code>android.hardware.audio.output</code>.
+ <li>[<a href="#7_9_virtual_reality">7.9</a>.1/H-1-1] MUST declare the <code>android.hardware.vr.high_performance</code> feature flag.
</li>
- </ul>
- <p>
- <strong>Virtual Reality Mode (Section 7.9.1)</strong>
- </p>
- <p>
- If Handheld device implementations include support for the VR mode, they:
- </p>
- <ul>
- <li>[H-1-1] MUST declare the <code>android.software.vr.mode</code> feature.<sup>*</sup>
- </li>
- </ul>
- <p>
- If device implementations declare <code>android.software.vr.mode</code> feature, they:
- </p>
- <ul>
- <li>[H-2-1] MUST include an application implementing <code>android.service.vr.VrListenerService</code> that can be enabled by VR applications via <code>android.app.Activity#setVrModeEnabled</code>.<sup>*</sup>
- </li>
- </ul>
- <p>
- <strong>Virtual Reality High Performance (Section 7.9.2)</strong>
- </p>
- <p>
- If Handheld device implementations are capable of meeting all the requirements to declare the <code>android.hardware.vr.high_performance</code> feature flag, they:
- </p>
- <ul>
- <li>[H-1-1] MUST declare the <code>android.hardware.vr.high_performance</code> feature flag.<sup>*</sup>
+ <li>[<a href="#7_9_virtual_reality">7.9</a>.1/H-1-2] MUST include an application implementing <code>android.service.vr.VrListenerService</code> that can be enabled by VR applications via <code>android.app.Activity#setVrModeEnabled</code>.
</li>
</ul>
<h4 id="2_2_2_multimedia">
2.2.2. Multimedia
</h4>
<p>
- <strong>Audio Encoding (Section 5.1.1)</strong>
- </p>
- <p>
Handheld device implementations MUST support the following audio encoding:
</p>
<ul>
- <li>[H-0-1] AMR-NB
+ <li>[<a href="#5_1_media_codecs">5.1</a>.1/H-0-1] AMR-NB
</li>
- <li>[H-0-2] AMR-WB
+ <li>[<a href="#5_1_media_codecs">5.1</a>.1/H-0-2] AMR-WB
</li>
- <li>[H-0-3] MPEG-4 AAC Profile (AAC LC)
+ <li>[<a href="#5_1_media_codecs">5.1</a>.1/H-0-3] MPEG-4 AAC Profile (AAC LC)
</li>
- <li>[H-0-4] MPEG-4 HE AAC Profile (AAC+)
+ <li>[<a href="#5_1_media_codecs">5.1</a>.1/H-0-4] MPEG-4 HE AAC Profile (AAC+)
</li>
- <li>[H-0-5] AAC ELD (enhanced low delay AAC)
+ <li>[<a href="#5_1_media-codecs">5.1</a>.1/H-0-5] AAC ELD (enhanced low delay AAC)
</li>
</ul>
<p>
- <strong>Audio Decoding (Section 5.1.2)</strong>
- </p>
- <p>
Handheld device implementations MUST support the following audio decoding:
</p>
<ul>
- <li>[H-0-1] AMR-NB
+ <li>[<a href="#5_1_media_codecs">5.1</a>.2/H-0-1] AMR-NB
</li>
- <li>[H-0-2] AMR-WB
+ <li>[<a href="#5_1_media_codecs">5.1</a>.2/H-0-2] AMR-WB
</li>
</ul>
<p>
- <strong>Video Encoding (Section 5.2)</strong>
- </p>
- <p>
Handheld device implementations MUST support the following video encoding and make it available to third-party applications:
</p>
<ul>
- <li>[H-0-1] H.264 AVC
+ <li>[<a href="#5_2_video_encoding">5.2</a>/H-0-1] H.264 AVC
</li>
- <li>[H-0-2] VP8
+ <li>[<a href="#5_2_video_encoding">5.2</a>/H-0-2] VP8
</li>
</ul>
<p>
- <strong>Video Decoding (Section 5.3)</strong>
- </p>
- <p>
Handheld device implementations MUST support the following video decoding:
</p>
<ul>
- <li>[H-0-1] H.264 AVC.
+ <li>[<a href="#5_3_video_decoding">5.3</a>/H-0-1] H.264 AVC
</li>
- <li>[H-0-2] H.265 HEVC.
+ <li>[<a href="#5_3_video_decoding">5.3</a>/H-0-2] H.265 HEVC
</li>
- <li>[H-0-3] MPEG-4 SP.
+ <li>[<a href="#5_3_video_decoding">5.3</a>/H-0-3] MPEG-4 SP
</li>
- <li>[H-0-4] VP8.
+ <li>[<a href="#5_3_video_decoding">5.3</a>/H-0-4] VP8
</li>
- <li>[H-0-5] VP9.
+ <li>[<a href="#5_3_video_decoding">5.3</a>/H-0-5] VP9
</li>
</ul>
<h4 id="2_2_3_software">
2.2.3. Software
</h4>
<p>
- <strong>WebView Compatibility (Section 3.4.1)</strong>
- </p>
- <p>
Handheld device implementations:
</p>
<ul>
- <li>[H-0-1] MUST provide a complete implementation of the <code>android.webkit.Webview</code> API.
+ <li>[<a href="#3_2_3_1_core_application_intents">3.2.3.1</a>/H-0-1] MUST have an application that handles the <a href="https://developer.android.com/reference/android/content/Intent.html#ACTION_GET_CONTENT"><code>ACTION_GET_CONTENT</code></a>, <a href="https://developer.android.com/reference/android/content/Intent#ACTION_OPEN_DOCUMENT"><code>ACTION_OPEN_DOCUMENT</code></a>, <a href="https://developer.android.com/reference/android/content/Intent.html#ACTION_OPEN_DOCUMENT_TREE"><code>ACTION_OPEN_DOCUMENT_TREE</code></a>, and <a href="https://developer.android.com/reference/android/content/Intent.html#ACTION_CREATE_DOCUMENT"><code>ACTION_CREATE_DOCUMENT</code></a> intents as described in the SDK documents, and provide the user affordance to access the document provider data by using <a href="https://developer.android.com/reference/android/provider/DocumentsProvider"><code>DocumentsProvider</code></a> API.
+ </li>
+ <li>[<a href="#3_4_web_compatibility">3.4</a>.1/H-0-1] MUST provide a complete implementation of the <code>android.webkit.Webview</code> API.
+ </li>
+ <li>[<a href="#3_4_web_compatibility">3.4</a>.2/H-0-1] MUST include a standalone Browser application for general user web browsing.
+ </li>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.1/H-SR] Are STRONGLY RECOMMENDED to implement a default launcher that supports in-app pinning of shortcuts, widgets and <a href="https://developer.android.com/reference/android/appwidget/AppWidgetProviderInfo.html#widgetFeatures">widgetFeatures</a>.
+ </li>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.1/H-SR] Are STRONGLY RECOMMENDED to implement a default launcher that provides quick access to the additional shortcuts provided by third-party apps through the <a href="https://developer.android.com/reference/android/content/pm/ShortcutManager.html">ShortcutManager</a> API.
+ </li>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.1/H-SR] Are STRONGLY RECOMMENDED to include a default launcher app that shows badges for the app icons.
+ </li>
+ <li>[<a href="#3_8_user-interface_compatibility">3.8</a>.2/H-SR] Are STRONGLY RECOMMENDED to support third-party app widgets.
+ </li>
+ <li>[<a href="#3_8_user-interface_compatibility">3.8</a>.3/H-0-1] MUST allow third-party apps to notify users of notable events through the <a href="https://developer.android.com/reference/android/app/Notification.html"><code>Notification</code></a> and <a href="https://developer.android.com/reference/android/app/NotificationManager.html"><code>NotificationManager</code></a> API classes.
+ </li>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.3/H-0-2] MUST support rich notifications.
+ </li>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.3/H-0-3] MUST support heads-up notifications.
+ </li>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.3/H-0-4] MUST include a notification shade, providing the user the ability to directly control (e.g. reply, snooze, dismiss, block) the notifications through user affordance such as action buttons or the control panel as implemented in the AOSP.
+ </li>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.3/H-0-5] MUST display the choices provided through <a href="https://developer.android.com/reference/android/app/RemoteInput.Builder.html#setChoices%28java.lang.CharSequence[]%29"><code>RemoteInput.Builder setChoices()</code></a> in the notification shade.
+ </li>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.3/H-SR] Are STRONGLY RECOMMENDED to display the first choice provided through <a href="https://developer.android.com/reference/android/app/RemoteInput.Builder.html#setChoices%28java.lang.CharSequence[]%29"><code>RemoteInput.Builder setChoices()</code></a> in the notification shade without additional user interaction.
+ </li>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.3/H-SR] Are STRONGLY RECOMMENDED to display all the choices provided through <a href="https://developer.android.com/reference/android/app/RemoteInput.Builder.html#setChoices%28java.lang.CharSequence[]%29"><code>RemoteInput.Builder setChoices()</code></a> in the notification shade when the user expands all notifications in the notification shade.
+ </li>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.4/H-SR] Are STRONGLY RECOMMENDED to implement an assistant on the device to handle the <a href="http://developer.android.com/reference/android/content/Intent.html#ACTION_ASSIST">Assist action</a>.
</li>
</ul>
<p>
- <strong>Browser Compatibility (Section 3.4.2)</strong>
- </p>
- <p>
- Handheld device implementations:
+ If Handheld device implementations support Assist action, they:
</p>
<ul>
- <li>[H-0-1] MUST include a standalone Browser application for general user web browsing.
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.4/H-SR] Are STRONGLY RECOMMENDED to use long press on <code>HOME</code> key as the designated interaction to launch the assist app as described in <a href="#7_2_3_navigation_keys">section 7.2.3</a>. MUST launch the user-selected assist app, in other words the app that implements <a href="https://developer.android.com/reference/android/service/voice/VoiceInteractionService"><code>VoiceInteractionService</code></a> , or an activity handling the <code>ACTION_ASSIST</code> intent.
</li>
</ul>
<p>
- <strong>Launcher (Section 3.8.1)</strong>
- </p>
- <p>
- Handheld device implementations:
+ If Android Handheld device implementations support a lock screen, they:
</p>
<ul>
- <li>
- <p>
- [H-SR] Are STRONGLY RECOMMENDED to implement a default launcher that supports in-app pinning of shortcuts and widgets.
- </p>
- </li>
- <li>
- <p>
- [H-SR] Are STRONGLY RECOMMENDED to implement a default launcher that provides quick access to the additional shortcuts provided by third-party apps through the <a href="https://developer.android.com/reference/android/content/pm/ShortcutManager.html">ShortcutManager</a> API.
- </p>
- </li>
- <li>
- <p>
- [H-SR] Are STRONGLY RECOMMENDED to include a default launcher app that shows badges for the app icons.
- </p>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.10/H-1-1] MUST display the Lock screen Notifications including the Media Notification Template.
</li>
</ul>
<p>
- <strong>Widgets (Section 3.8.2)</strong>
- </p>
- <p>
- Handheld device implementations:
- </p>
- <ul>
- <li>[H-SR] Are STRONGLY RECOMMENDED to support third-party app widgets.
- </li>
- </ul>
- <p>
- <strong>Notifications (Section 3.8.3)</strong>
- </p>
- <p>
- Handheld device implementations:
- </p>
- <ul>
- <li>[H-0-1] MUST allow third-party apps to notify users of notable events through the <a href="https://developer.android.com/reference/android/app/Notification.html"><code>Notification</code></a> and <a href="https://developer.android.com/reference/android/app/NotificationManager.html"><code>NotificationManager</code></a> API classes.
- </li>
- <li>[H-0-2] MUST support rich notifications.
- </li>
- <li>[H-0-3] MUST support heads-up notifications.
- </li>
- <li>[H-0-4] MUST include a notification shade, providing the user the ability to directly control (e.g. reply, snooze, dismiss, block) the notifications through user affordance such as action buttons or the control panel as implemented in the AOSP.
- </li>
- </ul>
- <p>
- <strong>Search (Section 3.8.4)</strong>
- </p>
- <p>
- Handheld device implementations:
- </p>
- <ul>
- <li>[H-SR] Are STRONGLY RECOMMENDED to implement an assistant on the device to handle the <a href="http://developer.android.com/reference/android/content/Intent.html#ACTION_ASSIST">Assist action</a>.
- </li>
- </ul>
- <p>
- <strong>Lock Screen Media Control (Section 3.8.10)</strong>
- </p>
- <p>
- If Android Handheld device implementations support a lock screen,they:
- </p>
- <ul>
- <li>[H-1-1] MUST display the Lock screen Notifications including the Media Notification Template.
- </li>
- </ul>
- <p>
- <strong>Device administration (Section 3.9)</strong>
- </p>
- <p>
If Handheld device implementations support a secure lock screen, they:
</p>
<ul>
- <li>[H-1-1] MUST implement the full range of <a href="http://developer.android.com/guide/topics/admin/device-admin.html">device administration</a> policies defined in the Android SDK documentation.
+ <li>[<a href="#3_9_device_administration">3.9</a>/H-1-1] MUST implement the full range of <a href="http://developer.android.com/guide/topics/admin/device-admin.html">device administration</a> policies defined in the Android SDK documentation.
+ </li>
+ <li>[<a href="#3_9_device_administration">3.9</a>/H-1-2] MUST declare the support of managed profiles via the <code>android.software.managed_users</code> feature flag, except when the device is configured so that it would <a href="http://developer.android.com/reference/android/app/ActivityManager.html#isLowRamDevice%28%29">report</a> itself as a low RAM device or so that it allocates internal (non-removable) storage as shared storage.
</li>
</ul>
<p>
- <strong>Accessibility (Section 3.10)</strong>
- </p>
- <p>
Handheld device implementations:
</p>
<ul>
- <li>
- <p>
- [H-SR] MUST support third-party accessibility services.
- </p>
+ <li>[<a href="#3_10_accessibility">3.10</a>/H-0-1] MUST support third-party accessibility services.
</li>
- <li>
- <p>
- [H-SR] Are STRONGLY RECOMMENDED to preload accessibility services on the device comparable with or exceeding functionality of the Switch Access and TalkBack (for languages supported by the preloaded Text-to-speech engine) accessibility services as provided in the <a href="https://github.com/google/talkback">talkback open source project</a>.
- </p>
+ <li>[<a href="#3_10_accessibility">3.10</a>/H-SR] Are STRONGLY RECOMMENDED to preload accessibility services on the device comparable with or exceeding functionality of the Switch Access and TalkBack (for languages supported by the preloaded Text-to-speech engine) accessibility services as provided in the <a href="https://github.com/google/talkback">talkback open source project</a>.
+ </li>
+ <li>[<a href="#3_11_text_to_speech">3.11</a>/H-0-1] MUST support installation of third-party TTS engines.
+ </li>
+ <li>[<a href="#3_11_text_to_speech">3.11</a>/H-SR] Are STRONGLY RECOMMENDED to include a TTS engine supporting the languages available on the device.
+ </li>
+ <li>[<a href="#3_13_quick_settings">3.13</a>/H-SR] Are STRONGLY RECOMMENDED to include a Quick Settings UI component.
</li>
</ul>
<p>
- <strong>Text-to-Speech (Section 3.11)</strong>
- </p>
- <p>
- Handheld device implementations:
- </p>
- <ul>
- <li>
- <p>
- [H-0-1] MUST support installation of third-party TTS engines.
- </p>
- </li>
- <li>
- <p>
- [H-SR] Are STRONGLY RECOMMENDED to include a TTS engine supporting the languages available on the device.
- </p>
- </li>
- </ul>
- <p>
- <strong>Quick Settings (Section 3.13)</strong>
- </p>
- <p>
- Handheld device implementations:
- </p>
- <ul>
- <li>[H-SR] Are STRONGLY RECOMMENDED to include a Quick Settings UI component.
- </li>
- </ul>
- <p>
- <strong>Companion Device Pairing (Section 3.15)</strong>
- </p>
- <p>
If Android handheld device implementations declare <code>FEATURE_BLUETOOTH</code> or <code>FEATURE_WIFI</code> support, they:
</p>
<ul>
- <li>[H-1-1] MUST support the companion device pairing feature.
+ <li>[<a href="#3_15_instant_apps">3.15</a>/H-1-1] MUST support the companion device pairing feature.
</li>
</ul>
<h4 id="2_2_4_performance_and_power">
2.2.4. Performance and Power
</h4>
- <p>
- <strong>User Experience Consistency (Section 8.1)</strong>
- </p>
- <p>
- For handheld device implementations:
- </p>
<ul>
- <li>[H-0-1] <strong>Consistent frame latency</strong>. Inconsistent frame latency or a delay to render frames MUST NOT happen more often than 5 frames in a second, and SHOULD be below 1 frames in a second.
+ <li>[<a href="#8_1_user_experience_consistency">8.1</a>/H-0-1] <strong>Consistent frame latency</strong>. Inconsistent frame latency or a delay to render frames MUST NOT happen more often than 5 frames in a second, and SHOULD be below 1 frames in a second.
</li>
- <li>[H-0-2] <strong>User interface latency</strong>. Device implementations MUST ensure low latency user experience by scrolling a list of 10K list entries as defined by the Android Compatibility Test Suite (CTS) in less than 36 secs.
+ <li>[<a href="#8_1_user_experience_consistency">8.1</a>/H-0-2] <strong>User interface latency</strong>. Device implementations MUST ensure low latency user experience by scrolling a list of 10K list entries as defined by the Android Compatibility Test Suite (CTS) in less than 36 secs.
</li>
- <li>[H-0-3] <strong>Task switching</strong>. When multiple applications have been launched, re-launching an already-running application after it has been launched MUST take less than 1 second.
+ <li>[<a href="#8_1_user_experience_consistency">8.1</a>/H-0-3] <strong>Task switching</strong>. When multiple applications have been launched, re-launching an already-running application after it has been launched MUST take less than 1 second.
</li>
</ul>
<p>
- <strong>File I/O Access Performance (Section 8.2)</strong>
- </p>
- <p>
Handheld device implementations:
</p>
<ul>
- <li>[H-0-1] MUST ensure a sequential write performance of at least 5 MB/s.
+ <li>[<a href="#8_2_file_io_access_performance">8.2</a>/H-0-1] MUST ensure a sequential write performance of at least 5 MB/s.
</li>
- <li>[H-0-2] MUST ensure a random write performance of at least 0.5 MB/s.
+ <li>[<a href="#8_2_file_io_access_performance">8.2</a>/H-0-2] MUST ensure a random write performance of at least 0.5 MB/s.
</li>
- <li>[H-0-3] MUST ensure a sequential read performance of at least 15 MB/s.
+ <li>[<a href="#8_2_file_io_access_performance">8.2</a>/H-0-3] MUST ensure a sequential read performance of at least 15 MB/s.
</li>
- <li>[H-0-4] MUST ensure a random read performance of at least 3.5 MB/s.
+ <li>[<a href="#8_2_file_io_access_performance">8.2</a>/H-0-4] MUST ensure a random read performance of at least 3.5 MB/s.
</li>
</ul>
<p>
- <strong>Power-Saving Modes (Section 8.3)</strong>
- </p>
- <p>
- For handheld device implementations:
+ If Handheld device implementations include features to improve device power management that are included in AOSP or extend the features that are included in AOSP, they:
</p>
<ul>
- <li>[H-0-1] All Apps exempted from App Standby and Doze power-saving modes MUST be made visible to the end user.
+ <li>[<a href="#8_3_power_saving_modes">8.3</a>/H-1-1] MUST provide user affordance to enable and disable the battery saver feature.
</li>
- <li>[H-0-2] The triggering, maintenance, wakeup algorithms and the use of global system settings of App Standby and Doze power-saving modes MUST not deviate from the Android Open Source Project.
+ <li>[<a href="#8_3_power_saving_modes">8.3</a>/H-1-2] MUST provide user affordance to display all apps that are exempted from App Standby and Doze power-saving modes.
</li>
</ul>
<p>
- <strong>Power Consumption Accounting (Sections 8.4)</strong>
- </p>
- <p>
Handheld device implementations:
</p>
<ul>
- <li>[H-0-1] MUST provide a per-component power profile that defines the <a href="http://source.android.com/devices/tech/power/values.html">current consumption value</a> for each hardware component and the approximate battery drain caused by the components over time as documented in the Android Open Source Project site.
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/H-0-1] MUST provide a per-component power profile that defines the <a href="http://source.android.com/devices/tech/power/values.html">current consumption value</a> for each hardware component and the approximate battery drain caused by the components over time as documented in the Android Open Source Project site.
</li>
- <li>[H-0-2] MUST report all power consumption values in milliampere hours (mAh).
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/H-0-2] MUST report all power consumption values in milliampere hours (mAh).
</li>
- <li>[H-0-3] MUST report CPU power consumption per each process's UID. The Android Open Source Project meets the requirement through the <code>uid_cputime</code> kernel module implementation.
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/H-0-3] MUST report CPU power consumption per each process's UID. The Android Open Source Project meets the requirement through the <code>uid_cputime</code> kernel module implementation.
</li>
- <li>[H-0-4] MUST make this power usage available via the <a href="http://source.android.com/devices/tech/power/batterystats.html"><code>adb shell dumpsys batterystats</code></a> shell command to the app developer.
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/H-0-4] MUST make this power usage available via the <a href="http://source.android.com/devices/tech/power/batterystats.html"><code>adb shell dumpsys batterystats</code></a> shell command to the app developer.
</li>
- <li>SHOULD be attributed to the hardware component itself if unable to attribute hardware component power usage to an application.
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/H] SHOULD be attributed to the hardware component itself if unable to attribute hardware component power usage to an application.
</li>
</ul>
<p>
If Handheld device implementations include a screen or video output, they:
</p>
<ul>
- <li>[H-1-1] MUST honor the <a href="http://developer.android.com/reference/android/content/Intent.html#ACTION_POWER_USAGE_SUMMARY"><code>android.intent.action.POWER_USAGE_SUMMARY</code></a> intent and display a settings menu that shows this power usage.
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/H-1-1] MUST honor the <a href="http://developer.android.com/reference/android/content/Intent.html#ACTION_POWER_USAGE_SUMMARY"><code>android.intent.action.POWER_USAGE_SUMMARY</code></a> intent and display a settings menu that shows this power usage.
</li>
</ul>
<h4 id="2_2_5_security_model">
2.2.5. Security Model
</h4>
<p>
- <strong>Permissions (Sections 9.1)</strong>
- </p>
- <p>
Handheld device implementations:
</p>
<ul>
- <li>[H-0-1] MUST allow third-party apps to access the usage statistics via the <code>android.permission.PACKAGE_USAGE_STATS</code> permission and provide a user-accessible mechanism to grant or revoke access to such apps in response to the <a href="https://developer.android.com/reference/android/provider/Settings.html#ACTION&lowbar;USAGE&lowbar;ACCESS&lowbar;SETTINGS"><code>android.settings.ACTION_USAGE_ACCESS_SETTINGS</code></a> intent.
+ <li>[<a href="#9_1_permissions">9.1</a>/H-0-1] MUST allow third-party apps to access the usage statistics via the <code>android.permission.PACKAGE_USAGE_STATS</code> permission and provide a user-accessible mechanism to grant or revoke access to such apps in response to the <a href="https://developer.android.com/reference/android/provider/Settings.html#ACTION&lowbar;USAGE&lowbar;ACCESS&lowbar;SETTINGS"><code>android.settings.ACTION_USAGE_ACCESS_SETTINGS</code></a> intent.
+ </li>
+ </ul>
+ <p>
+ When Handheld device implementations support a secure lock screen, they:
+ </p>
+ <ul>
+ <li>[<a href="#9_11_permissions">9.11</a>/H-1-1] MUST allow the user to choose the shortest sleep timeout, that is a transition time from the unlocked to the locked state, as 15 seconds or less.
+ </li>
+ <li>[<a href="#9_11_permissions">9.11</a>/H-1-2] MUST provide user affordance to hide notifications and disable all forms of authentication except for the primary authentication described in <a href="#9_11_1_secure-lock-screen">9.11.1 Secure Lock Screen</a>. The AOSP meets the requirement as lockdown mode.
</li>
</ul>
<h3 id="2_3_television_requirements">
@@ -744,7 +609,7 @@
<ul>
<li>Have provided a mechanism to remotely control the rendered user interface on the display that might sit ten feet away from the user.
</li>
- <li>Have an embedded screen display with the diagonal length larger than 24 inches OR include a video output port, such as VGA, HDMI, DisplayPort or a wireless port for display.
+ <li>Have an embedded screen display with the diagonal length larger than 24 inches OR include a video output port, such as VGA, HDMI, DisplayPort, or a wireless port for display.
</li>
</ul>
<p>
@@ -754,262 +619,218 @@
2.3.1. Hardware
</h4>
<p>
- <strong>Non-touch Navigation (Section 7.2.2)</strong>
- </p>
- <p>
Television device implementations:
</p>
<ul>
- <li>[T-0-1] MUST support <a href="https://developer.android.com/reference/android/content/res/Configuration.html#NAVIGATION_DPAD">D-pad</a>.
+ <li>[<a href="#7_2_input_devices">7.2</a>.2/T-0-1] MUST support <a href="https://developer.android.com/reference/android/content/res/Configuration.html#NAVIGATION_DPAD">D-pad</a>.
+ </li>
+ <li>[<a href="#7_2_input_devices">7.2</a>.3/T-0-1] MUST provide the Home and Back functions.
+ </li>
+ <li>[<a href="#7_2_input_devices">7.2</a>.3/T-0-2] MUST send both the normal and long press event of the Back function (<a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_BACK"><code>KEYCODE_BACK</code></a>) to the foreground application.
+ </li>
+ <li>[<a href="#7_2_input_devices">7.2</a>.6.1/T-0-1] MUST include support for game controllers and declare the <code>android.hardware.gamepad</code> feature flag.
+ </li>
+ <li>[<a href="#7_2_input_devices">7.2</a>.7/T] SHOULD provide a remote control from which users can access <a href="#7_2_2_non-touch_navigation">non-touch navigation</a> and <a href="#7_2_3_navigation_keys">core navigation keys</a> inputs.
</li>
</ul>
<p>
- <strong>Navigation Keys (Section 7.2.3)</strong>
- </p>
- <p>
- Television device implementations:
- </p>
- <ul>
- <li>[T-0-1] MUST provide the Home and Back functions.
- </li>
- <li>[T-0-2] MUST send both the normal and long press event of the the Back function (<a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_BACK"><code>KEYCODE_BACK</code></a>) to the foreground application.
- </li>
- </ul>
- <p>
- <strong>Button Mappings (Section 7.2.6.1)</strong>
- </p>
- <p>
- Television device implementations:
- </p>
- <ul>
- <li>[T-0-1] MUST include support for game controllers and declare the <code>android.hardware.gamepad</code> feature flag.
- </li>
- </ul>
- <p>
- <strong>Remote Control (Section 7.2.7)</strong>
- </p>
- <p>
- Television device implementations:
- </p>
- <ul>
- <li>SHOULD provide a remote control from which users can access <a href="#7_2_2_non-touch_navigation">non-touch navigation</a> and <a href="#7_2_3_navigation_keys">core navigation keys</a> inputs.
- </li>
- </ul>
- <p>
- <strong>Gyroscope (Section 7.3.4)</strong>
- </p>
- <p>
If Television device implementations include a gyroscope, they:
</p>
<ul>
- <li>[T-1-1] MUST be able to report events up to a frequency of at least 100 Hz.
+ <li>[<a href="#7_3_sensors">7.3</a>.4/T-1-1] MUST be able to report events up to a frequency of at least 100 Hz.
</li>
</ul>
<p>
- <strong>Bluetooth (Section 7.4.3)</strong>
+ Television device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#7_4_data_connectivity">7.4</a>.3/T-0-1] MUST support Bluetooth and Bluetooth LE.
+ </li>
+ <li>[<a href="#7_6_memory_and_storage">7.6</a>.1/T-0-1] MUST have at least 4 GB of non-volatile storage available for application private data (a.k.a. "/data" partition).
+ </li>
+ </ul>
+ <p>
+ If Television device implementations include a USB port that supports host mode, they:
+ </p>
+ <ul>
+ <li>[<a href="#7_5_camera">7.5</a>.3/T-1-1] MUST include support for an external camera that connects through this USB port but is not necessarily always connected.
+ </li>
+ </ul>
+ <p>
+ If TV device implementations are 32-bit:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/T-1-1] The memory available to the kernel and userspace MUST be at least 896MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>400dpi or higher on small/normal screens
+ </li>
+ <li>xhdpi or higher on large screens
+ </li>
+ <li>tvdpi or higher on extra large screens
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <p>
+ If TV device implementations are 64-bit:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/T-2-1] The memory available to the kernel and userspace MUST be at least 1280MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>400dpi or higher on small/normal screens
+ </li>
+ <li>xhdpi or higher on large screens
+ </li>
+ <li>tvdpi or higher on extra large screens
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <p>
+ Note that the "memory available to the kernel and userspace" above refers to the memory space provided in addition to any memory already dedicated to hardware components such as radio, video, and so on that are not under the kernel’s control on device implementations.
</p>
<p>
Television device implementations:
</p>
<ul>
- <li>[T-0-1] MUST support Bluetooth and Bluetooth LE.
+ <li>[<a href="#7_8_audio">7.8</a>.1/T] SHOULD include a microphone.
</li>
- </ul>
- <p>
- <strong>Minimum Memory and Storage (Section 7.6.1)</strong>
- </p>
- <p>
- Television device implementations:
- </p>
- <ul>
- <li>[T-0-1] MUST have at least 4GB of non-volatile storage available for application private data (a.k.a. "/data" partition)
- </li>
- <li>[T-0-2] MUST return “true” for <code>ActivityManager.isLowRamDevice()</code> when there is less than 1GB of memory available to the kernel and userspace.
- </li>
- </ul>
- <p>
- <strong>Microphone (Section 7.8.1)</strong>
- </p>
- <p>
- Television device implementations:
- </p>
- <ul>
- <li>SHOULD include a microphone.
- </li>
- </ul>
- <p>
- <strong>Audio Output (Section 7.8.2)</strong>
- </p>
- <p>
- Television device implementations:
- </p>
- <ul>
- <li>[T-0-1] MUST have an audio output and declare <code>android.hardware.audio.output</code>.
+ <li>[<a href="#7_8_audio">7.8</a>.2/T-0-1] MUST have an audio output and declare <code>android.hardware.audio.output</code>.
</li>
</ul>
<h4 id="2_3_2_multimedia">
2.3.2. Multimedia
</h4>
<p>
- <strong>Audio Encoding (Section 5.1)</strong>
- </p>
- <p>
- Television device implementations MUST support the following audio encoding:
+ Television device implementations MUST support the following audio encoding formats:
</p>
<ul>
- <li>[T-0-1] MPEG-4 AAC Profile (AAC LC)
+ <li>[<a href="#5_1_media_codecs">5.1</a>/T-0-1] MPEG-4 AAC Profile (AAC LC)
</li>
- <li>[T-0-2] MPEG-4 HE AAC Profile (AAC+)
+ <li>[<a href="#5_1_media_codecs">5.1</a>/T-0-2] MPEG-4 HE AAC Profile (AAC+)
</li>
- <li>[T-0-3] AAC ELD (enhanced low delay AAC)
+ <li>[<a href="#5_1_media_codecs">5.1</a>/T-0-3] AAC ELD (enhanced low delay AAC)
</li>
</ul>
<p>
- <strong>Video Encoding (Section 5.2)</strong>
- </p>
- <p>
- Television device implementations MUST support the following video encoding:
+ Television device implementations MUST support the following video encoding formats:
</p>
<ul>
- <li>[T-0-1] H.264 AVC
+ <li>[<a href="#5_2_video_encoding">5.2</a>/T-0-1] H.264
</li>
- <li>[T-0-2] VP8
- </li>
- </ul>
- <p>
- <strong>H-264 (Section 5.2.2)</strong>
- </p>
- <p>
- Television device implementations are:
- </p>
- <ul>
- <li>[T-SR] STRONGLY RECOMMENDED to support H.264 encoding of 720p and 1080p resolution videos.
- </li>
- <li>[T-SR] STRONGLY RECOMMENDED to support H.264 encoding of 1080p resolution video at 30 frame-per-second (fps).
- </li>
- </ul>
- <p>
- <strong>Video Decoding (Section 5.3)</strong>
- </p>
- <p>
- Television device implementations MUST support the following video decoding:
- </p>
- <ul>
- <li>[T-0-1] H.264 AVC
- </li>
- <li>[T-0-2] H.265 HEVC
- </li>
- <li>[T-0-3] MPEG-4 SP
- </li>
- <li>[T-0-4] VP8
- </li>
- <li>[T-0-5] VP9
- </li>
- </ul>
- <p>
- Television device implementations are STRONGLY RECOMMENDED to support the following video decoding:
- </p>
- <ul>
- <li>[T-SR] MPEG-2
- </li>
- </ul>
- <p>
- <strong>H.264 (Section 5.3.4)</strong>
- </p>
- <p>
- If Television device implementations support H.264 decoders, they:
- </p>
- <ul>
- <li>[T-1-1] MUST support High Profile Level 4.2 and the HD 1080p (at 60 fps) decoding profile.
- </li>
- <li>[T-1-2] MUST be capable of decoding videos with both HD profiles as indicated in the following table and encoded with either the Baseline Profile, Main Profile, or the High Profile Level 4.2
- </li>
- </ul>
- <p>
- <strong>H.265 (HEVC) (Section 5.3.5)</strong>
- </p>
- <p>
- If Television device implementations support H.265 codec and the HD 1080p decoding profile, they:
- </p>
- <ul>
- <li>[T-1-1] MUST support the Main Profile Level 4.1 Main tier.
- </li>
- <li>[T-SR] Are STRONGLY RECOMMENDED to support 60 fps video frame rate for HD 1080p.
- </li>
- </ul>
- <p>
- If Television device implementations support H.265 codec and the UHD decoding profile, then:
- </p>
- <ul>
- <li>[T-2-1] The codec MUST support Main10 Level 5 Main Tier profile.
- </li>
- </ul>
- <p>
- <strong>VP8 (Section 5.3.6)</strong>
- </p>
- <p>
- If Television device implementations support VP8 codec, they:
- </p>
- <ul>
- <li>[T-1-1] MUST support the HD 1080p60 decoding profile.
- </li>
- </ul>
- <p>
- If Television device implementations support VP8 codec and support 720p, they:
- </p>
- <ul>
- <li>[T-2-1] MUST support the HD 720p60 decoding profile.
- </li>
- </ul>
- <p>
- <strong>VP9 (Section 5.3.7)</strong>
- </p>
- <p>
- If Television device implementations support VP9 codec and the UHD video decoding, they:
- </p>
- <ul>
- <li>[T-1-1] MUST support 8-bit color depth and SHOULD support VP9 Profile 2 (10-bit).
- </li>
- </ul>
- <p>
- If Television device implementations support VP9 codec, the 1080p profile and VP9 hardware decoding, they:
- </p>
- <ul>
- <li>[T-2-1] MUST support 60 fps for 1080p.
- </li>
- </ul>
- <p>
- <strong>Secure Media (Section 5.8)</strong>
- </p>
- <p>
- If device implementations are Android Television devices and support 4K resolution, they:
- </p>
- <ul>
- <li>[T-1-1] MUST support HDCP 2.2 for all wired external displays.
- </li>
- </ul>
- <p>
- If Television device implementations don't support 4K resolution, they:
- </p>
- <ul>
- <li>[T-2-1] MUST support HDCP 1.4 for all wired external displays.
+ <li>[<a href="#5_2_video_encoding">5.2</a>/T-0-2] VP8
</li>
</ul>
<p>
Television device implementations:
</p>
<ul>
- <li>[T-SR] Are STRONGLY RECOMMENDED to support simulataneous decoding of secure streams. At minimum, simultaneous decoding of two steams is STRONGLY RECOMMENDED.
+ <li>[<a href="#5_2_video_encoding">5.2</a>.2/T-SR] Are STRONGLY RECOMMENDED to support H.264 encoding of 720p and 1080p resolution videos at 30 frames per second.
</li>
</ul>
<p>
- <strong>Audio Output Volume (Section 5.5.3)</strong>
+ Television device implementations MUST support the following video decoding formats:
</p>
+ <ul>
+ <li>[<a href="#5_3_video_decoding">5.3.3</a>/T-0-1] MPEG-4 SP
+ </li>
+ <li>[<a href="#5_3_video_decoding">5.3.4</a>/T-0-2] H.264 AVC
+ </li>
+ <li>[<a href="#5_3_video_decoding">5.3.5</a>/T-0-3] H.265 HEVC
+ </li>
+ <li>[<a href="#5_3_video_decoding">5.3.6</a>/T-0-4] VP8
+ </li>
+ <li>[<a href="#5_3_video_decoding">5.3.7</a>/T-0-5] VP9
+ </li>
+ </ul>
+ <p>
+ Television device implementations are STRONGLY RECOMMENDED to support the following video decoding formats:
+ </p>
+ <ul>
+ <li>[<a href="#5_3_video_decoding">5.3.1</a>/T-SR] MPEG-2
+ </li>
+ </ul>
+ <p>
+ Television device implementations MUST support H.264 decoding, as detailed in Section 5.3.4, at standard video frame rates and resolutions up to and including:
+ </p>
+ <ul>
+ <li>[<a href="#5_3_video_decoding">5.3.4</a>.4/T-1-1] HD 1080p at 60 frames per second with Baseline Profile
+ </li>
+ <li>[<a href="#5_3_video_decoding">5.3.4</a>.4/T-1-2] HD 1080p at 60 frames per second with Main Profile
+ </li>
+ <li>[<a href="#5_3_video_decoding">5.3.4</a>.4/T-1-3] HD 1080p at 60 frames per second with High Profile Level 4.2
+ </li>
+ </ul>
+ <p>
+ Television device implementations with H.265 hardware decoders MUST support H.265 decoding, as detailed in Section 5.3.5, at standard video frame rates and resolutions up to and including:
+ </p>
+ <ul>
+ <li>[<a href="#5_3_video_decoding">5.3.5</a>.4/T-1-1] HD 1080p at 60 frames per second with Main Profile Level 4.1
+ </li>
+ </ul>
+ <p>
+ If Television device implementations with H.265 hardware decoders support H.265 decoding and the UHD decoding profile, they:
+ </p>
+ <ul>
+ <li>[<a href="#5_3_video_decoding">5.3.5</a>.5/T-2-1] MUST support UHD 3480p at 60 frames per second with Main10 Level 5 Main Tier profile.
+ </li>
+ </ul>
+ <p>
+ Television device implementations MUST support VP8 decoding, as detailed in Section 5.3.6, at standard video frame rates and resolutions up to and including:
+ </p>
+ <ul>
+ <li>[<a href="#5_3_video_decoding">5.3.6</a>.4/T-1-1] HD 1080p at 60 frames per second decoding profile
+ </li>
+ </ul>
+ <p>
+ Television device implementations with VP9 hardware decoders MUST support VP9 decoding, as detailed in Section 5.3.7, at standard video frame rates and resolutions up to and including:
+ </p>
+ <ul>
+ <li>[<a href="#5_3_video_decoding">5.3.7</a>.4/T-1-1] HD 1080p at 60 frames per second with profile 0 (8 bit colour depth)
+ </li>
+ </ul>
+ <p>
+ If Television device implementations with VP9 hardware decoders support VP9 decoding and the UHD decoding profile, they:
+ </p>
+ <ul>
+ <li>[<a href="#5_3_video_decoding">5.3.7</a>.5/T-2-1] MUST support UHD 3480p at 60 frames per second with profile 0 (8 bit colour depth).
+ </li>
+ <li>[<a href="#5_3_video_decoding">5.3.7</a>.5/T-2-1] Are STRONGLY RECOMMENDED to support UHD 3480p at 60 frames per second with profile 2 (10 bit colour depth).
+ </li>
+ </ul>
<p>
Television device implementations:
</p>
<ul>
- <li>[T-0-1] MUST include support for system Master Volume and digital audio output volume attenuation on supported outputs, except for compressed audio passthrough output (where no audio decoding is done on the device).
+ <li>[<a href="#5_5_audio_playback">5.5</a>.3/T-0-1] MUST include support for system Master Volume and digital audio output volume attenuation on supported outputs, except for compressed audio passthrough output (where no audio decoding is done on the device).
+ </li>
+ <li>[<a href="#5_8_secure_media">5.8</a>/T-0-1] MUST set the HDMI output mode to select the maximum resolution that can be supported with either 50Hz or 60Hz refresh rate for all wired displays.
+ </li>
+ <li>[<a href="#5_8_secure_media">5.8</a>/T-SR] Are STRONGLY RECOMMENDED to provide a user configurable HDMI refresh rate selector for all wired displays.
+ </li>
+ <li>[<a href="#5_8_secure_media">5.8</a>/T-SR] Are STRONGLY RECOMMENDED to support simultaneous decoding of secure streams. At minimum, simultaneous decoding of two steams is STRONGLY RECOMMENDED.
+ </li>
+ <li>[<a href="#5_8_secure_media">5.8</a>] SHOULD set the HDMI output mode refresh rate to either 50Hz or 60Hz, depending on the video refresh rate for the region the device is sold in for all wired displays.
+ </li>
+ </ul>
+ <p>
+ If Television device implementations support UHD decoding and have support for external displays, they:
+ </p>
+ <ul>
+ <li>[<a href="#5_8_secure_media">5.8</a>/T-1-1] MUST support HDCP 2.2.
+ </li>
+ </ul>
+ <p>
+ If Television device implementations do not support UHD decoding but have support for external displays, they:
+ </p>
+ <ul>
+ <li>[<a href="#5_8_secure_media">5.8</a>/T-2-1] MUST support HDCP 1.4
</li>
</ul>
<h4 id="2_3_3_software">
@@ -1019,142 +840,82 @@
Television device implementations:
</p>
<ul>
- <li>[T-0-1] MUST declare the features <a href="http://developer.android.com/reference/android/content/pm/PackageManager.html#FEATURE_LEANBACK"><code>android.software.leanback</code></a> and <code>android.hardware.type.television</code>.
+ <li>[<a href="#3_0_intro">3</a>/T-0-1] MUST declare the features <a href="http://developer.android.com/reference/android/content/pm/PackageManager.html#FEATURE_LEANBACK"><code>android.software.leanback</code></a> and <code>android.hardware.type.television</code>.
+ </li>
+ <li>[<a href="#3_4_web_compatibility">3.4</a>.1/T-0-1] MUST provide a complete implementation of the <code>android.webkit.Webview</code> API.
</li>
</ul>
<p>
- <strong>WebView compatibility (Section 3.4.1)</strong>
- </p>
- <p>
- Television device implementations:
- </p>
- <ul>
- <li>[T-0-1] MUST provide a complete implementation of the <code>android.webkit.Webview</code> API.
- </li>
- </ul>
- <p>
- <strong>Lock Screen Media Control (Section 3.8.10)</strong>
- </p>
- <p>
If Android Television device implementations support a lock screen,they:
</p>
<ul>
- <li>[T-1-1] MUST display the Lock screen Notifications including the Media Notification Template.
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.10/T-1-1] MUST display the Lock screen Notifications including the Media Notification Template.
</li>
</ul>
<p>
- <strong>Multi-windows (Section 3.8.14)</strong>
- </p>
- <p>
Television device implementations:
</p>
<ul>
- <li>[T-SR] Are STRONGLY RECOMMENDED to support picture-in-picture (PIP) mode multi-window.
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.14/T-SR] Are STRONGLY RECOMMENDED to support picture-in-picture (PIP) mode multi-window.
+ </li>
+ <li>[<a href="#3_10_accessibility">3.10</a>/T-0-1] MUST support third-party accessibility services.
+ </li>
+ <li>[<a href="#3_10_accessibility">3.10</a>/T-SR] Are STRONGLY RECOMMENDED to preload accessibility services on the device comparable with or exceeding functionality of the Switch Access and TalkBack (for languages supported by the preloaded Text-to-speech engine) accessibility services as provided in the <a href="https://github.com/google/talkback">talkback open source project</a>.
</li>
</ul>
<p>
- <strong>Accessibility (Section 3.10)</strong>
+ If Television device implementations report the feature <code>android.hardware.audio.output</code>, they:
</p>
+ <ul>
+ <li>[<a href="#3_11_text_to_speech">3.11</a>/T-SR] Are STRONGLY RECOMMENDED to include a TTS engine supporting the languages available on the device.
+ </li>
+ <li>[<a href="#3_11_text_to_speech">3.11</a>/T-1-1] MUST support installation of third-party TTS engines.
+ </li>
+ </ul>
<p>
Television device implementations:
</p>
<ul>
- <li>
- <p>
- [T-SR] MUST support third-party accessibility services.
- </p>
- </li>
- <li>
- <p>
- [T-SR] Android Television device implementations are STRONGLY RECOMMENDED to preload accessibility services on the device comparable with or exceeding functionality of the Switch Access and TalkBack (for languages supported by the preloaded Text-to-speech engine) accessibility services as provided in the <a href="https://github.com/google/talkback">talkback open source project</a>.
- </p>
+ <li>[<a href="#3_12_tv_input_framework">3.12</a>/T-0-1] MUST support TV Input Framework.
</li>
</ul>
- <p>
- <strong>Text-to-Speech (Section 3.11)</strong>
- </p>
- <p>
- If device implementations report the feature android.hardware.audio.output, they:
- </p>
- <ul>
- <li>
- <p>
- [T-SR] STRONGLY RECOMMENDED to include a TTS engine supporting the languages available on the device.
- </p>
- </li>
- <li>
- <p>
- [T-0-1] MUST support installation of third-party TTS engines.
- </p>
- </li>
- </ul>
- <p>
- <strong>TV Input Framework (Section 3.12)</strong>
- </p>
- <p>
- Television device implementations:
- </p>
- <ul>
- <li>[T-0-1] MUST support TV Input Framework.
- </li>
- </ul>
- <h4 id="2_2_4_performance_and_power">
- 2.2.4. Performance and Power
+ <h4 id="2_3_4_performance_and_power">
+ 2.3.4. Performance and Power
</h4>
- <p>
- <strong>User Experience Consistency (Section 8.1)</strong>
- </p>
- <p>
- For Television device implementations:
- </p>
<ul>
- <li>[T-0-1] <strong>Consistent frame latency</strong>. Inconsistent frame latency or a delay to render frames MUST NOT happen more often than 5 frames in a second, and SHOULD be below 1 frames in a second.
+ <li>[<a href="#8_1_user_experience_consistency">8.1</a>/T-0-1] <strong>Consistent frame latency</strong>. Inconsistent frame latency or a delay to render frames MUST NOT happen more often than 5 frames in a second, and SHOULD be below 1 frames in a second.
+ </li>
+ <li>[<a href="#8_2_file_io_access_performance">8.2</a>/T-0-1] MUST ensure a sequential write performance of at least 5MB/s.
+ </li>
+ <li>[<a href="#8_2_file_io_access_performance">8.2</a>/T-0-2] MUST ensure a random write performance of at least 0.5MB/s.
+ </li>
+ <li>[<a href="#8_2_file_io_access_performance">8.2</a>/T-0-3] MUST ensure a sequential read performance of at least 15MB/s.
+ </li>
+ <li>[<a href="#8_2_file_io_access_performance">8.2</a>/T-0-4] MUST ensure a random read performance of at least 3.5MB/s.
</li>
</ul>
<p>
- <strong>File I/O Access Performance (Section 8.2)</strong>
+ If Television device implementations include features to improve device power management that are included in AOSP or extend the features that are included in AOSP, they:
</p>
+ <ul>
+ <li>[<a href="#8_3_power_saving_modes">8.3</a>/T-1-1] MUST provide user affordance to enable and disable the battery saver feature.
+ </li>
+ <li>[<a href="#8_3_power_saving_modes">8.3</a>/T-1-2] MUST provide user affordance to display all apps that are exempted from App Standby and Doze power-saving modes.
+ </li>
+ </ul>
<p>
Television device implementations:
</p>
<ul>
- <li>[T-0-1] MUST ensure a sequential write performance of at least 5MB/s.
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/T-0-1] MUST provide a per-component power profile that defines the <a href="http://source.android.com/devices/tech/power/values.html">current consumption value</a> for each hardware component and the approximate battery drain caused by the components over time as documented in the Android Open Source Project site.
</li>
- <li>[T-0-2] MUST ensure a random write performance of at least 0.5MB/s.
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/T-0-2] MUST report all power consumption values in milliampere hours (mAh).
</li>
- <li>[T-0-3] MUST ensure a sequential read performance of at least 15MB/s.
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/T-0-3] MUST report CPU power consumption per each process's UID. The Android Open Source Project meets the requirement through the <code>uid_cputime</code> kernel module implementation.
</li>
- <li>[T-0-4] MUST ensure a random read performance of at least 3.5MB/s.
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/T] SHOULD be attributed to the hardware component itself if unable to attribute hardware component power usage to an application.
</li>
- </ul>
- <p>
- <strong>Power-Saving Modes (Section 8.3)</strong>
- </p>
- <p>
- For Television device implementations:
- </p>
- <ul>
- <li>[T-0-1] All Apps exempted from App Standby and Doze power-saving modes MUST be made visible to the end user.
- </li>
- <li>[T-0-2] The triggering, maintenance, wakeup algorithms and the use of global system settings of App Standby and Doze power-saving modes MUST not deviate from the Android Open Source Project.
- </li>
- </ul>
- <p>
- <strong>Power Consumption Accounting (Sections 8.4)</strong>
- </p>
- <p>
- Television device implementations:
- </p>
- <ul>
- <li>[T-0-1] MUST provide a per-component power profile that defines the <a href="http://source.android.com/devices/tech/power/values.html">current consumption value</a> for each hardware component and the approximate battery drain caused by the components over time as documented in the Android Open Source Project site.
- </li>
- <li>[T-0-2] MUST report all power consumption values in milliampere hours (mAh).
- </li>
- <li>[T-0-3] MUST report CPU power consumption per each process's UID. The Android Open Source Project meets the requirement through the <code>uid_cputime</code> kernel module implementation.
- </li>
- <li>SHOULD be attributed to the hardware component itself if unable to attribute hardware component power usage to an application.
- </li>
- <li>[T-0-4] MUST make this power usage available via the <a href="http://source.android.com/devices/tech/power/batterystats.html"><code>adb shell dumpsys batterystats</code></a> shell command to the app developer.
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/T-0-4] MUST make this power usage available via the <a href="http://source.android.com/devices/tech/power/batterystats.html"><code>adb shell dumpsys batterystats</code></a> shell command to the app developer.
</li>
</ul>
<h3 id="2_4_watch_requirements">
@@ -1179,85 +940,53 @@
2.4.1. Hardware
</h4>
<p>
- <strong>Screen Size (Section 7.1.1.1)</strong>
- </p>
- <p>
Watch device implementations:
</p>
<ul>
- <li>[W-0-1] MUST have a screen with the physical diagonal size in the range from 1.1 to 2.5 inches.
+ <li>
+ <p>
+ [<a href="#7_1_display_and_graphics">7.1</a>.1.1/W-0-1] MUST have a screen with the physical diagonal size in the range from 1.1 to 2.5 inches.
+ </p>
</li>
- </ul>
- <p>
- <strong>Navigation Keys (Section 7.2.3)</strong>
- </p>
- <p>
- Watch device implementations:
- </p>
- <ul>
- <li>[W-0-1] MUST have the Home function available to the user, and the Back function except for when it is in <code>UI_MODE_TYPE_WATCH</code>.
+ <li>
+ <p>
+ [<a href="#7_2_input_devices">7.2</a>.3/W-0-1] MUST have the Home function available to the user, and the Back function except for when it is in <code>UI_MODE_TYPE_WATCH</code>.
+ </p>
</li>
- </ul>
- <p>
- <strong>Touchscreen Input (Section 7.2.4)</strong>
- </p>
- <p>
- Watch device implementations:
- </p>
- <ul>
- <li>[W-0-2] MUST support touchscreen input.
+ <li>
+ <p>
+ [<a href="#7_2_input_devices">7.2</a>.4/W-0-1] MUST support touchscreen input.
+ </p>
</li>
- </ul>
- <p>
- <strong>Accelerometer (Section 7.3.1)</strong>
- </p>
- <p>
- Watch device implementations:
- </p>
- <ul>
- <li>[W-SR] Are STRONGLY RECOMMENDED to include a 3-axis accelerometer.
+ <li>
+ <p>
+ [<a href="#7_3_sensors">7.3</a>.1/W-SR] Are STRONGLY RECOMMENDED to include a 3-axis accelerometer.
+ </p>
</li>
- </ul>
- <p>
- <strong>Bluetooth (Section 7.4.3)</strong>
- </p>
- <p>
- Watch device implementations:
- </p>
- <ul>
- <li>[W-0-1] MUST support Bluetooth.
+ <li>
+ <p>
+ [<a href="#7_4_data_connectivity">7.4</a>.3/W-0-1] MUST support Bluetooth.
+ </p>
</li>
- </ul>
- <p>
- <strong>Minimum Memory and Storage (Section 7.6.1)</strong>
- </p>
- <p>
- Watch device implementations:
- </p>
- <ul>
- <li>[W-0-1] MUST have at least 1GB of non-volatile storage available for application private data (a.k.a. "/data" partition)
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/W-0-1] MUST have at least 1 GB of non-volatile storage available for application private data (a.k.a. "/data" partition).
+ </p>
</li>
- <li>[W-0-2] MUST have at least 416MB memory available to the kernel and userspace.
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/W-0-2] MUST have at least 416 MB memory available to the kernel and userspace.
+ </p>
</li>
- </ul>
- <p>
- <strong>Microphone (Section 7.8.1)</strong>
- </p>
- <p>
- Watch device implementations:
- </p>
- <ul>
- <li>[W-0-1] MUST include a microphone.
+ <li>
+ <p>
+ [<a href="#7_8_audio">7.8</a>.1/W-0-1] MUST include a microphone.
+ </p>
</li>
- </ul>
- <p>
- <strong>Audio Output (Section 7.8.1)</strong>
- </p>
- <p>
- Watch device implementations:
- </p>
- <ul>
- <li>MAY but SHOULD NOT have audio output.
+ <li>
+ <p>
+ [<a href="#7_8_audio">7.8</a>.2/W] MAY but SHOULD NOT have audio output.
+ </p>
</li>
</ul>
<h4 id="2_4_2_multimedia">
@@ -1273,57 +1002,69 @@
Watch device implementations:
</p>
<ul>
- <li>[W-0-1] MUST declare the feature android.hardware.type.watch.
+ <li>[<a href="#3_0_intro">3</a>/W-0-1] MUST declare the feature <code>android.hardware.type.watch</code>.
</li>
- <li>[W-0-2] MUST support uiMode = <a href="http://developer.android.com/reference/android/content/res/Configuration.html#UI_MODE_TYPE_WATCH">UI_MODE_TYPE_WATCH</a>.
+ <li>[<a href="#3_0_intro">3</a>/W-0-2] MUST support uiMode = <a href="http://developer.android.com/reference/android/content/res/Configuration.html#UI_MODE_TYPE_WATCH">UI_MODE_TYPE_WATCH</a>.
</li>
</ul>
<p>
- <strong>Search (Section 3.8.4)</strong>
- </p>
- <p>
Watch device implementations:
</p>
<ul>
- <li>[W-SR] Are STRONGLY RECOMMENDED to implement an assistant on the device to handle the <a href="http://developer.android.com/reference/android/content/Intent.html#ACTION_ASSIST">Assist action</a>.
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.4/W-SR] Are STRONGLY RECOMMENDED to implement an assistant on the device to handle the <a href="http://developer.android.com/reference/android/content/Intent.html#ACTION_ASSIST">Assist action</a>.
</li>
</ul>
<p>
- <strong>Accessibility (Section 3.10)</strong>
- </p>
- <p>
Watch device implementations that declare the <code>android.hardware.audio.output</code> feature flag:
</p>
<ul>
- <li>
- <p>
- [W-1-1] MUST support third-party accessibility services.
- </p>
+ <li>[<a href="#3_10_accessibility">3.10</a>/W-1-1] MUST support third-party accessibility services.
</li>
- <li>
- <p>
- [W-SR] Are STRONGLY RECOMMENDED to preload accessibility services on the device comparable with or exceeding functionality of the Switch Access and TalkBack (for languages supported by the preloaded Text-to-speech engine) accessibility services as provided in the <a href="https://github.com/google/talkback">talkback open source project</a>.
- </p>
+ <li>[<a href="#3_10_accessibility">3.10</a>/W-SR] Are STRONGLY RECOMMENDED to preload accessibility services on the device comparable with or exceeding functionality of the Switch Access and TalkBack (for languages supported by the preloaded Text-to-speech engine) accessibility services as provided in the <a href="https://github.com/google/talkback">talkback open source project</a>.
</li>
</ul>
<p>
- <strong>Text-to-Speech (Section 3.11)</strong>
- </p>
- <p>
If Watch device implementations report the feature android.hardware.audio.output, they:
</p>
<ul>
<li>
<p>
- [W-SR] Are STRONGLY RECOMMENDED to include a TTS engine supporting the languages available on the device.
+ [<a href="#3_11_text_to_speech">3.11</a>/W-SR] Are STRONGLY RECOMMENDED to include a TTS engine supporting the languages available on the device.
</p>
</li>
<li>
<p>
- [W-0-1] MUST support installation of third-party TTS engines.
+ [<a href="#3_11_text_to_speech">3.11</a>/W-0-1] MUST support installation of third-party TTS engines.
</p>
</li>
</ul>
+ <h4 id="2_4_4_performance_and_power">
+ 2.4.4. Performance and Power
+ </h4>
+ <p>
+ If Watch device implementations include features to improve device power management that are included in AOSP or extend the features that are included in AOSP, they:
+ </p>
+ <ul>
+ <li>[<a href="#8_3_power_saving_modes">8.3</a>/W-SR] Are STRONGLY RECOMMENDED to provide user affordance to display all apps that are exempted from App Standby and Doze power-saving modes.
+ </li>
+ <li>[<a href="#8_3_power_saving_modes">8.3</a>/W-SR] Are STRONGLY RECOMMENDED to provide user affordance to enable and disable the battery saver feature.
+ </li>
+ </ul>
+ <p>
+ Watch device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/W-0-1] MUST provide a per-component power profile that defines the <a href="http://source.android.com/devices/tech/power/values.html">current consumption value</a> for each hardware component and the approximate battery drain caused by the components over time as documented in the Android Open Source Project site.
+ </li>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/W-0-2] MUST report all power consumption values in milliampere hours (mAh).
+ </li>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/W-0-3] MUST report CPU power consumption per each process's UID. The Android Open Source Project meets the requirement through the <code>uid_cputime</code> kernel module implementation.
+ </li>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/W-0-4] MUST make this power usage available via the <a href="http://source.android.com/devices/tech/power/batterystats.html"><code>adb shell dumpsys batterystats</code></a> shell command to the app developer.
+ </li>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/W] SHOULD be attributed to the hardware component itself if unable to attribute hardware component power usage to an application.
+ </li>
+ </ul>
<h3 id="2_5_automotive_requirements">
2.5. Automotive Requirements
</h3>
@@ -1346,128 +1087,91 @@
2.5.1. Hardware
</h4>
<p>
- <strong>Screen Size (Section 7.1.1.1)</strong>
- </p>
- <p>
Automotive device implementations:
</p>
<ul>
- <li>[A-0-1] MUST have a screen at least 6 inches in physical diagonal size.
+ <li>[<a href="#7_1_display_and-graphics">7.1</a>.1.1/A-0-1] MUST have a screen at least 6 inches in physical diagonal size.
</li>
- <li>[A-0-2] MUST have a screen size layout of at least 750 dp x 480 dp.
+ <li>
+ <p>
+ [<a href="#7_1_display_and_graphics">7.1</a>.1.1/A-0-2] MUST have a screen size layout of at least 750 dp x 480 dp.
+ </p>
</li>
- </ul>
- <p>
- <strong>Navigation Keys (Section 7.2.3)</strong>
- </p>
- <p>
- Automotive device implementations:
- </p>
- <ul>
- <li>[A-0-1] MUST provide the Home function and MAY provide Back and Recent functions.
+ <li>
+ <p>
+ [<a href="#7_2_input_devices">7.2</a>.3/A-0-1] MUST provide the Home function and MAY provide Back and Recent functions.
+ </p>
</li>
- <li>[A-0-2] MUST send both the normal and long press event of the the Back function (<a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_BACK"><code>KEYCODE_BACK</code></a>) to the foreground application.
+ <li>
+ <p>
+ [<a href="#7_2_input_devices">7.2</a>.3/A-0-2] MUST send both the normal and long press event of the Back function (<a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_BACK"><code>KEYCODE_BACK</code></a>) to the foreground application.
+ </p>
</li>
- </ul>
- <p>
- <strong>Accelerometer (Section 7.3.1)</strong>
- </p>
- <p>
- Automotive device implementations:
- </p>
- <ul>
- <li>[A-SR] Are STRONGLY RECOMMENDED to include a 3-axis accelerometer.
+ <li>
+ <p>
+ [<a href="#7_3_sensors">7.3</a>.1/A-SR] Are STRONGLY RECOMMENDED to include a 3-axis accelerometer.
+ </p>
</li>
</ul>
<p>
If Automotive device implementations include a 3-axis accelerometer, they:
</p>
<ul>
- <li>[A-1-1] MUST be able to report events up to a frequency of at least 100 Hz.
+ <li>[<a href="#7_3_sensors">7.3</a>.1/A-1-1] MUST be able to report events up to a frequency of at least 100 Hz.
</li>
- <li>[A-1-2] MUST comply with the Android <a href="http://source.android.com/devices/sensors/sensor-types.html#auto_axes">car sensor coordinate system</a>.
+ <li>[<a href="#7_3_sensors">7.3</a>.1/A-1-2] MUST comply with the Android <a href="http://source.android.com/devices/sensors/sensor-types.html#auto_axes">car sensor coordinate system</a>.
</li>
</ul>
<p>
- <strong>GPS (Section 7.3.3)</strong>
- </p>
- <p>
If Automotive device implementations include a GPS/GNSS receiver and report the capability to applications through the <code>android.hardware.location.gps</code> feature flag:
</p>
<ul>
- <li>[A-1-1] GNSS technology generation MUST be the year "2017" or newer.
+ <li>[<a href="#7_3_sensors">7.3</a>.3/A-1-1] GNSS technology generation MUST be the year "2017" or newer.
</li>
</ul>
<p>
- <strong>Gyroscope (Section 7.3.4)</strong>
- </p>
- <p>
If Automotive device implementations include a gyroscope, they:
</p>
<ul>
- <li>[A-1-1] MUST be able to report events up to a frequency of at least 100 Hz.
+ <li>[<a href="#7_3_sensors">7.3</a>.4/A-1-1] MUST be able to report events up to a frequency of at least 100 Hz.
</li>
</ul>
<p>
- <strong>Android Automotive-only sensors (Section 7.3.11)</strong> <strong>Current Gear (Section 7.3.11.1)</strong>
- </p>
- <p>
Automotive device implementations:
</p>
<ul>
- <li>SHOULD provide current gear as <code>SENSOR_TYPE_GEAR</code>.
+ <li>[<a href="#7_3_sensors">7.3</a>.11/A-0-1] MUST provide current gear as <code>SENSOR_TYPE_GEAR</code>.
</li>
</ul>
<p>
- <strong>Day Night Mode (Section 7.3.11.2)</strong>
- </p>
- <p>
Automotive device implementations:
</p>
<ul>
- <li>[A-0-1] MUST support day/night mode defined as <code>SENSOR_TYPE_NIGHT</code>.
+ <li>[<a href="#7_3_sensors">7.3</a>.11.2/A-0-1] MUST support day/night mode defined as <code>SENSOR_TYPE_NIGHT</code>.
</li>
- <li>[A-0-2] The value of the <code>SENSOR_TYPE_NIGHT</code> flag MUST be consistent with dashboard day/night mode and SHOULD be based on ambient light sensor input.
+ <li>[<a href="#7_3_sensors">7.3</a>.11.2/A-0-2] The value of the <code>SENSOR_TYPE_NIGHT</code> flag MUST be consistent with dashboard day/night mode and SHOULD be based on ambient light sensor input.
</li>
- <li>The underlying ambient light sensor MAY be the same as <a href="#7_3_7_photometer">Photometer</a>.
- </li>
- </ul>
- <p>
- <strong>Driving Status (Section 7.3.11.3)</strong>
- </p>
- <p>
- Automotive device implementations:
- </p>
- <ul>
- <li>[A-0-1] MUST support driving status defined as <code>SENSOR_TYPE_DRIVING_STATUS</code>, with a default value of <code>DRIVE_STATUS_UNRESTRICTED</code> when the vehicle is fully stopped and parked. It is the responsibility of device manufacturers to configure <code>SENSOR_TYPE_DRIVING_STATUS</code> in compliance with all laws and regulations that apply to markets where the product is shipping.
- </li>
- </ul>
- <p>
- <strong>Wheel Speed (Section 7.3.11.4)</strong>
- </p>
- <p>
- Automotive device implementations:
- </p>
- <ul>
- <li>[A-0-1] MUST provide vehicle speed defined as <code>SENSOR_TYPE_CAR_SPEED</code>.
- </li>
- </ul>
- <p>
- <strong>Bluetooth (Section 7.4.3)</strong>
- </p>
- <p>
- Automotive device implementations:
- </p>
- <ul>
<li>
<p>
- [A-0-1] MUST support Bluetooth and SHOULD support Bluetooth LE.
+ The underlying ambient light sensor MAY be the same as <a href="#7_3_7_photometer">Photometer</a>.
</p>
</li>
<li>
<p>
- [A-0-2] Android Automotive implementations MUST support the following Bluetooth profiles:
+ [<a href="#7_3_sensors">7.3</a>.11.4/A-0-1] MUST provide vehicle speed as defined by <code>SENSOR_TYPE_CAR_SPEED</code>.
</p>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_3_sensors">7.3</a>.11.5/A-0-1] MUST provide parking brake status as defined by <code>SENSOR_TYPE_PARKING_BRAKE</code>.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_4_data_connectivity">7.4</a>.3/A-0-1] MUST support Bluetooth and SHOULD support Bluetooth LE.
+ </p>
+ </li>
+ <li>[<a href="#7_4_data_connectivity">7.4</a>.3/A-0-2] Android Automotive implementations MUST support the following Bluetooth profiles:
<ul>
<li>Phone calling over Hands-Free Profile (HFP).
</li>
@@ -1479,109 +1183,220 @@
</li>
</ul>
</li>
- <li>SHOULD support Message Access Profile (MAP).
+ <li>
+ <p>
+ [<a href="#7_4_data_connectivity">7.4</a>.3/A-SR] Are STRONGLY RECOMMENDED to support Message Access Profile (MAP).
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_4_data_connectivity">7.4</a>.5/A] SHOULD include support for cellular network-based data connectivity.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_4_data_connectivity">7.4</a>.5/A] MAY use the System API <code>NetworkCapabilities#NET_CAPABILITY_OEM_PAID</code> constant for networks that should be available to system apps.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/A-0-1] MUST have at least 4 GB of non-volatile storage available for application private data (a.k.a. "/data" partition).
+ </p>
</li>
</ul>
<p>
- <strong>Minimum Network Capability (Section 7.4.5)</strong>
+ Automotive device implementations:
+ </p>
+ <ul>
+ <li>[<a href="#7_6_memory_and_storage">7.6</a>.1/A] SHOULD format the data partition to offer improved performance and longevity on flash storage, for example using <code>f2fs</code> file-system.
+ </li>
+ </ul>
+ <p>
+ If Automotive device implementations provide shared external storage via a portion of the internal non-removable storage, they:
+ </p>
+ <ul>
+ <li>[<a href="#7_6_memory_and_storage">7.6</a>.1/A-SR] Are STRONGLY RECOMMENDED to reduce I/O overhead on operations performed on the external storage, for example by using <code>SDCardFS</code>.
+ </li>
+ </ul>
+ <p>
+ If Automotive device implementations are 32-bit:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/A-1-1] The memory available to the kernel and userspace MUST be at least 512MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>280dpi or lower on small/normal screens
+ </li>
+ <li>ldpi or lower on extra large screens
+ </li>
+ <li>mdpi or lower on large screens
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/A-1-2] The memory available to the kernel and userspace MUST be at least 608MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>xhdpi or higher on small/normal screens
+ </li>
+ <li>hdpi or higher on large screens
+ </li>
+ <li>mdpi or higher on extra large screens
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/A-1-3] The memory available to the kernel and userspace MUST be at least 896MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>400dpi or higher on small/normal screens
+ </li>
+ <li>xhdpi or higher on large screens
+ </li>
+ <li>tvdpi or higher on extra large screens
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/A-1-4] The memory available to the kernel and userspace MUST be at least 1344MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>560dpi or higher on small/normal screens
+ </li>
+ <li>400dpi or higher on large screens
+ </li>
+ <li>xhdpi or higher on extra large screens
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <p>
+ If Automotive device implementations are 64-bit:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/A-2-1] The memory available to the kernel and userspace MUST be at least 816MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>280dpi or lower on small/normal screens
+ </li>
+ <li>ldpi or lower on extra large screens
+ </li>
+ <li>mdpi or lower on large screens
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/A-2-2] The memory available to the kernel and userspace MUST be at least 944MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>xhdpi or higher on small/normal screens
+ </li>
+ <li>hdpi or higher on large screens
+ </li>
+ <li>mdpi or higher on extra large screens
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/A-2-3] The memory available to the kernel and userspace MUST be at least 1280MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>400dpi or higher on small/normal screens
+ </li>
+ <li>xhdpi or higher on large screens
+ </li>
+ <li>tvdpi or higher on extra large screens
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [<a href="#7_6_memory_and_storage">7.6</a>.1/A-2-4] The memory available to the kernel and userspace MUST be at least 1824MB if any of the following densities are used:
+ </p>
+ <ul>
+ <li>560dpi or higher on small/normal screens
+ </li>
+ <li>400dpi or higher on large screens
+ </li>
+ <li>xhdpi or higher on extra large screens
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <p>
+ Note that the "memory available to the kernel and userspace" above refers to the memory space provided in addition to any memory already dedicated to hardware components such as radio, video, and so on that are not under the kernel’s control on device implementations.
</p>
<p>
Automotive device implementations:
</p>
<ul>
- <li>SHOULD include support for cellular network based data connectivity.
+ <li>[<a href="#7_7_usb">7.7</a>.1/A] SHOULD include a USB port supporting peripheral mode.
</li>
</ul>
<p>
- <strong>Minimum Memory and Storage (Section 7.6.1)</strong>
- </p>
- <p>
Automotive device implementations:
</p>
<ul>
- <li>[A-0-1] MUST have at least 4GB of non-volatile storage available for application private data (a.k.a. "/data" partition)
+ <li>[<a href="#7_8_audio">7.8</a>.1/A-0-1] MUST include a microphone.
</li>
</ul>
<p>
- <strong>USB peripheral mode (Section 7.7.1)</strong>
- </p>
- <p>
Automotive device implementations:
</p>
<ul>
- <li>SHOULD include a USB port supporting peripheral mode.
- </li>
- </ul>
- <p>
- <strong>Microphone (Section 7.8.1)</strong>
- </p>
- <p>
- Automotive device implementations:
- </p>
- <ul>
- <li>[A-0-1] MUST include a microphone.
- </li>
- </ul>
- <p>
- <strong>Audio Output (Section 7.8.2)</strong>
- </p>
- <p>
- Automotive device implementations:
- </p>
- <ul>
- <li>[A-0-1] MUST have an audio output and declare <code>android.hardware.audio.output</code>.
+ <li>[<a href="#7_8_audio">7.8</a>.2/A-0-1] MUST have an audio output and declare <code>android.hardware.audio.output</code>.
</li>
</ul>
<h4 id="2_5_2_multimedia">
2.5.2. Multimedia
</h4>
<p>
- <strong>Audio Encoding (Section 5.1)</strong>
- </p>
- <p>
Automotive device implementations MUST support the following audio encoding:
</p>
<ul>
- <li>[A-1-1] MPEG-4 AAC Profile (AAC LC)
+ <li>[<a href="#5_1_media_codecs">5.1</a>/A-0-1] MPEG-4 AAC Profile (AAC LC)
</li>
- <li>[A-1-2] MPEG-4 HE AAC Profile (AAC+)
+ <li>[<a href="#5_1_media_codecs">5.1</a>/A-0-2] MPEG-4 HE AAC Profile (AAC+)
</li>
- <li>[A-1-3] AAC ELD (enhanced low delay AAC)
+ <li>[<a href="#5_1_media_codecs">5.1</a>/A-0-3] AAC ELD (enhanced low delay AAC)
</li>
</ul>
<p>
- <strong>Video Encoding (Section 5.2)</strong>
- </p>
- <p>
Automotive device implementations MUST support the following video encoding:
</p>
<ul>
- <li>[A-0-1] H.264 AVC
+ <li>[<a href="#5_2_video_encoding">5.2</a>/A-0-1] H.264 AVC
</li>
- <li>[A-0-2] VP8
+ <li>[<a href="#5_2_video_encoding">5.2</a>/A-0-2] VP8
</li>
</ul>
<p>
- <strong>Video Decoding (Section 5.3)</strong>
- </p>
- <p>
Automotive device implementations MUST support the following video decoding:
</p>
<ul>
- <li>[A-0-1] H.264 AVC
+ <li>[<a href="#5_3_video_decoding">5.3</a>/A-0-1] H.264 AVC
</li>
- <li>[A-0-2] MPEG-4 SP
+ <li>[<a href="#5_3_video_decoding">5.3</a>/A-0-2] MPEG-4 SP
</li>
- <li>[A-0-3] VP8
+ <li>[<a href="#5_3_video_decoding">5.3</a>/A-0-3] VP8
</li>
- <li>[A-0-4] VP9
+ <li>[<a href="#5_3_video_decoding">5.3</a>/A-0-4] VP9
</li>
</ul>
<p>
Automotive device implementations are STRONGLY RECOMMENDED to support the following video decoding:
</p>
<ul>
- <li>[A-SR] H.265 HEVC
+ <li>[<a href="#5_3_video_decoding">5.3</a>/A-SR] H.265 HEVC
</li>
</ul>
<h4 id="2_5_3_software">
@@ -1591,109 +1406,109 @@
Automotive device implementations:
</p>
<ul>
- <li>[A-0-1] MUST declare the feature android.hardware.type.automotive.
+ <li>
+ <p>
+ [<a href="#3_0_intro">3</a>/A-0-1] MUST declare the feature <code>android.hardware.type.automotive</code>.
+ </p>
</li>
- <li>[A-0-2] MUST support uiMode = <a href="http://developer.android.com/reference/android/content/res/Configuration.html#UI_MODE_TYPE_CAR">UI_MODE_TYPE_CAR</a>.
+ <li>
+ <p>
+ [<a href="#3_0_intro">3</a>/A-0-2] MUST support uiMode = <a href="http://developer.android.com/reference/android/content/res/Configuration.html#UI_MODE_TYPE_CAR"><code>UI_MODE_TYPE_CAR</code></a>.
+ </p>
</li>
- <li>[A-0-3] Android Automotive implementations MUST support all public APIs in the <code>android.car.*</code> namespace.
+ <li>
+ <p>
+ [<a href="#3_0_intro">3</a>/A-0-3] MUST support all public APIs in the <a href="https://developer.android.com/reference/android/car/package-summary"><code>android.car.*</code></a> namespace.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#3_4_web_compatibility">3.4</a>.1/A-0-1] MUST provide a complete implementation of the <code>android.webkit.Webview</code> API.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#3_8_user_interface_compatibility">3.8</a>.3/A-0-1] MUST display notifications that use the <a href="https://developer.android.com/reference/android/app/Notification.CarExtender.html"><code>Notification.CarExtender</code></a> API when requested by third-party applications.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#3_8_user_interface_compatibility">3.8</a>.4/A-0-1] MUST implement an assistant on the device that provides a default implementation of the <a href="https://developer.android.com/reference/android/service/voice/VoiceInteractionSession"><code>VoiceInteractionSession</code></a> service.
+ </p>
+ </li>
+ <li>
+ <p>
+ [<a href="#3_13_quick_settings">3.13</a>/A-SR] Are STRONGLY RECOMMENDED to include a Quick Settings UI component.
+ </p>
</li>
</ul>
<p>
- <strong>WebView Compatibility (Section 3.4.1)</strong>
+ If Automotive device implementations include a push-to-talk button, they:
</p>
+ <ul>
+ <li>[<a href="#3_8_user_interface_compatibility">3.8</a>.4/A-1-1] MUST use a short press of the push-to-talk button as the designated interaction to launch the user-selected assist app, in other words the app that implements <a href="https://developer.android.com/reference/android/service/voice/VoiceInteractionService"><code>VoiceInteractionService</code></a>.
+ </li>
+ </ul>
<p>
Automotive device implementations:
</p>
<ul>
- <li>[A-0-1] MUST provide a complete implementation of the <code>android.webkit.Webview API</code>.
+ <li>[<a href="#3_14_media_ui">3.14</a>/A-0-1] MUST include a UI framework to support third-party apps using the media APIs as described in section <a href="#3_14_media_ui">3.14</a>.
</li>
</ul>
- <p>
- <strong>Notifications (Section 3.8.3)</strong>
- </p>
- <p>
- Android Automotive device implementations:
- </p>
- <ul>
- <li>[A-0-1] MUST display notifications that use the <a href="https://developer.android.com/reference/android/app/Notification.CarExtender.html"><code>Notification.CarExtender</code></a> API when requested by third-party applications.
- </li>
- </ul>
- <p>
- <strong>Search (Section 3.8.4)</strong>
- </p>
- <p>
- Automotive device implementations:
- </p>
- <ul>
- <li>[A-0-1] MUST implement an assistant on the device to handle the <a href="http://developer.android.com/reference/android/content/Intent.html#ACTION_ASSIST">Assist action</a>.
- </li>
- </ul>
- <p>
- <strong>Media UI (Section 3.14)</strong>
- </p>
- <p>
- Automotive device implementations:
- </p>
- <ul>
- <li>[A-0-1] MUST include a UI framework to support third-party apps using the media APIs as described in section 3.14.
- </li>
- </ul>
- <h4 id="2_2_4_performance_and_power">
- 2.2.4. Performance and Power
+ <h4 id="2_5_4_performance_and_power">
+ 2.5.4. Performance and Power
</h4>
<p>
- <strong>Power-Saving Modes (Section 8.3)</strong>
- </p>
- <p>
- For Automotive device implementations:
+ If Automotive device implementations include features to improve device power management that are included in AOSP or extend the features that are included in AOSP, they:
</p>
<ul>
- <li>[A-0-1] All Apps exempted from App Standby and Doze power-saving modes MUST be made visible to the end user.
+ <li>[<a href="#8_3_power_saving_modes">8.3</a>/A-1-1] MUST provide user affordance to enable and disable the battery saver feature.
</li>
- <li>[A-0-2] The triggering, maintenance, wakeup algorithms and the use of global system settings of App Standby and Doze power-saving modes MUST not deviate from the Android Open Source Project.
+ <li>[<a href="#8_3_power_saving_modes">8.3</a>/A-1-2] MUST provide user affordance to display all apps that are exempted from App Standby and Doze power-saving modes.
</li>
</ul>
<p>
- <strong>Power Consumption Accounting (Sections 8.4)</strong>
- </p>
- <p>
Automotive device implementations:
</p>
<ul>
- <li>[A-0-1] MUST provide a per-component power profile that defines the <a href="http://source.android.com/devices/tech/power/values.html">current consumption value</a> for each hardware component and the approximate battery drain caused by the components over time as documented in the Android Open Source Project site.
+ <li>[<a href="#8_2_file_i/o_access_performance">8.2</a>/A-0-1] MUST report the number of bytes read and written to non-volatile storage per each process's UID so the stats are available to developers through System API <code>android.car.storagemonitoring.CarStorageMonitoringManager</code>. The Android Open Source Project meets the requirement through the <code>uid_sys_stats</code> kernel module.
</li>
- <li>[A-0-2] MUST report all power consumption values in milliampere hours (mAh).
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/A-0-1] MUST provide a per-component power profile that defines the <a href="http://source.android.com/devices/tech/power/values.html">current consumption value</a> for each hardware component and the approximate battery drain caused by the components over time as documented in the Android Open Source Project site.
</li>
- <li>[A-0-3] MUST report CPU power consumption per each process's UID. The Android Open Source Project meets the requirement through the <code>uid_cputime</code> kernel module implementation.
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/A-0-2] MUST report all power consumption values in milliampere hours (mAh).
</li>
- <li>SHOULD be attributed to the hardware component itself if unable to attribute hardware component power usage to an application.
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/A-0-3] MUST report CPU power consumption per each process's UID. The Android Open Source Project meets the requirement through the <code>uid_cputime</code> kernel module implementation.
</li>
- <li>[A-0-4] MUST make this power usage available via the <a href="http://source.android.com/devices/tech/power/batterystats.html"><code>adb shell dumpsys batterystats</code></a> shell command to the app developer.
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/A] SHOULD be attributed to the hardware component itself if unable to attribute hardware component power usage to an application.
+ </li>
+ <li>[<a href="#8_4_power_consumption_accounting">8.4</a>/A-0-4] MUST make this power usage available via the <a href="http://source.android.com/devices/tech/power/batterystats.html"><code>adb shell dumpsys batterystats</code></a> shell command to the app developer.
</li>
</ul>
- <h4 id="2_2_5_security_model">
- 2.2.5. Security Model
+ <h4 id="2_5_5_security_model">
+ 2.5.5. Security Model
</h4>
<p>
- <strong>Multi-User Support (Section 9.5)</strong>
- </p>
- <p>
- If Automotive device implementations include multiple users, they:
+ If Automotive device implementations support multiple users, they:
</p>
<ul>
- <li>[A-1-1] MUST include a guest account that allows all functions provided by the vehicle system without requiring a user to log in.
+ <li>[<a href="#9_5_multi_user_support">9.5</a>/A-1-1] MUST include a guest account that allows all functions provided by the vehicle system without requiring a user to log in.
</li>
</ul>
<p>
- <strong>Automotive Vehicle System Isolation (Section 9.14)</strong>
+ If Automotive device implementations support a secure lock screen, they:
</p>
+ <ul>
+ <li>[<a href="#9_9_full_disk_encryption">9.9</a>.2/A-1-1] MUST support encryption per user-specific authentication keys. <a href="https://source.android.com/security/encryption/file-based">File-Based Encryption (FBE)</a> is one way to do it.
+ </li>
+ </ul>
<p>
Automotive device implementations:
</p>
<ul>
- <li>[A-0-1] MUST gatekeep messages from Android framework vehicle subsystems, e.g., whitelisting permitted message types and message sources.
+ <li>[<a href="#9_14_automotive_system_isolation">9.14</a>/A-0-1] MUST gatekeep messages from Android framework vehicle subsystems, e.g., whitelisting permitted message types and message sources.
</li>
- <li>[A-0-2] MUST watchdog against denial of service attacks from the Android framework or third-party apps. This guards against malicious software flooding the vehicle network with traffic, which may lead to malfunctioning vehicle subsystems.
+ <li>[<a href="#9_14_automotive_system_isolation">9.14</a>/A-0-2] MUST watchdog against denial of service attacks from the Android framework or third-party apps. This guards against malicious software flooding the vehicle network with traffic, which may lead to malfunctioning vehicle subsystems.
</li>
</ul>
<h3 id="2_6_tablet_requirements">
@@ -1712,19 +1527,16 @@
</li>
</ul>
<p>
- Tablet device implementations have similar requirements to handheld device implementations. The exceptions are in indicated by and * in that section and noted for reference in this section.
+ Tablet device implementations have similar requirements to handheld device implementations. The exceptions are in indicated by an * in that section and noted for reference in this section.
</p>
<h4 id="2_4_1_hardware">
2.4.1. Hardware
</h4>
<p>
- <strong>Screen Size (Section 7.1.1.1)</strong>
- </p>
- <p>
- Tablet device implementations:
+ <strong>Screen Size</strong>
</p>
<ul>
- <li>[Ta-0-1] MUST have a screen in the range of 7 to 18 inches.
+ <li>[<a href="#7_1_display_and_graphics">7.1</a>.1.1/Tab-0-1] MUST have a screen in the range of 7 to 18 inches.
</li>
</ul>
<p>
@@ -1737,10 +1549,10 @@
<strong>USB peripheral mode (Section 7.7.1)</strong>
</p>
<p>
- If handheld device implementations include a USB port supporting peripheral mode, they:
+ If tablet device implementations include a USB port supporting peripheral mode, they:
</p>
<ul>
- <li>MAY implement the Android Open Accessory (AOA) API.
+ <li>[<a href="#7_7_usb">7.7.1</a>/Tab] MAY implement the Android Open Accessory (AOA) API.
</li>
</ul>
<p>
@@ -1761,27 +1573,43 @@
<p>
The managed Dalvik bytecode execution environment is the primary vehicle for Android applications. The Android application programming interface (API) is the set of Android platform interfaces exposed to applications running in the managed runtime environment.
</p>
+ <p>
+ Device implementations:
+ </p>
<ul>
<li>
<p>
- [C-0-1] Device implementations MUST provide complete implementations, including all documented behaviors, of any documented API exposed by the <a href="http://developer.android.com/reference/packages.html">Android SDK</a> or any API decorated with the “@SystemApi” marker in the upstream Android source code.
+ [C-0-1] MUST provide complete implementations, including all documented behaviors, of any documented API exposed by the <a href="http://developer.android.com/reference/packages.html">Android SDK</a> or any API decorated with the “@SystemApi” marker in the upstream Android source code.
</p>
</li>
<li>
<p>
- [C-0-2] Device implementations MUST support/preserve all classes, methods, and associated elements marked by the TestApi annotation (@TestApi).
+ [C-0-2] MUST support/preserve all classes, methods, and associated elements marked by the TestApi annotation (@TestApi).
</p>
</li>
<li>
<p>
- [C-0-3] Device implementations MUST NOT omit any managed APIs, alter API interfaces or signatures, deviate from the documented behavior, or include no-ops, except where specifically allowed by this Compatibility Definition.
+ [C-0-3] MUST NOT omit any managed APIs, alter API interfaces or signatures, deviate from the documented behavior, or include no-ops, except where specifically allowed by this Compatibility Definition.
</p>
</li>
<li>
<p>
- [C-0-4] Device implementations MUST still keep the APIs present and behave in a reasonable way, even when some hardware features for which Android includes APIs are omitted. See <a href="#7_hardware_compatibility">section 7</a> for specific requirements for this scenario.
+ [C-0-4] MUST still keep the APIs present and behave in a reasonable way, even when some hardware features for which Android includes APIs are omitted. See <a href="#7_hardware_compatibility">section 7</a> for specific requirements for this scenario.
</p>
</li>
+ <li>
+ <p>
+ [C-0-5] MUST restrict the use of 3rd-party app usage of hidden APIs, defined as APIs in the android namespace decorated with the <code>@hidden</code> annotation but not with a <code>@SystemAPI</code> or <code>@TestApi</code>, as described in the <a href="https://developer.android.com/preview/restrictions-non-sdk-interfaces">SDK documents</a> and ship with each and every hidden API on the same restricted lists as provided via the light-greylist, dark-greylist, and blacklist files in the <code>prebuilts/runtime/appcompat/</code> path for the appropriate API level branch in the AOSP. However they:
+ </p>
+ <ul>
+ <li>MAY, if a hidden API is absent or implemented differently on the device implementation, move the hidden API into the blacklist or omit it from all restricted lists (i.e. light-grey, dark-grey, black).
+ </li>
+ <li>MAY, if a hidden API does not already exist in the AOSP, add the hidden API to any of the restricted lists (i.e. light-grey, dark-grey, black).
+ </li>
+ <li>MAY implement a dynamic update mechanism that moves a hidden API from a restricted list into a less restrictive list, except for the whitelist.
+ </li>
+ </ul>
+ </li>
</ul>
<h3 id="3_1_1_android_extensions">
3.1.1. Android Extensions
@@ -1793,6 +1621,27 @@
<li>[C-0-1] Android device implementations MUST preload the AOSP implementation of both the shared library <code>ExtShared</code> and services <code>ExtServices</code> with versions higher than or equal to the minimum versions allowed per each API level. For example, Android 7.0 device implementations, running API level 24 MUST include at least version 1.
</li>
</ul>
+ <h3 id="3_1_2_android_library">
+ 3.1.2. Android Library
+ </h3>
+ <p>
+ Due to <a href="https://developer.android.com/preview/behavior-changes#apache-p">Apache HTTP client deprecation</a>, device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST NOT place the <code>org.apache.http.legacy</code> library in the bootclasspath.
+ </li>
+ <li>[C-0-2] MUST add the <code>org.apache.http.legacy</code> library to the application classpath only when the app satisfies one of the following conditions:
+ <ul>
+ <li>Targets API level 28 or lower.
+ </li>
+ <li>Declares in its manifest that it needs the library by setting the <code>android:name</code> attribute of <code><uses-library></code> to <code>org.apache.http.legacy</code>.
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <p>
+ The AOSP implementation meets these requirements.
+ </p>
<h3 id="3_2_soft_api_compatibility">
3.2. Soft API Compatibility
</h3>
@@ -1830,7 +1679,7 @@
VERSION.RELEASE
</td>
<td>
- The version of the currently-executing Android system, in human-readable format. This field MUST have one of the string values defined in <a href="http://source.android.com/compatibility/8.1/versions.html">8.1</a>.
+ The version of the currently-executing Android system, in human-readable format. This field MUST have one of the string values defined in <a href="http://source.android.com/compatibility/9/versions.html">9</a>.
</td>
</tr>
<tr>
@@ -1838,7 +1687,7 @@
VERSION.SDK
</td>
<td>
- The version of the currently-executing Android system, in a format accessible to third-party application code. For Android 8.1, this field MUST have the integer value 8.1_INT.
+ The version of the currently-executing Android system, in a format accessible to third-party application code. For Android 9, this field MUST have the integer value 9_INT.
</td>
</tr>
<tr>
@@ -1846,7 +1695,7 @@
VERSION.SDK_INT
</td>
<td>
- The version of the currently-executing Android system, in a format accessible to third-party application code. For Android 8.1, this field MUST have the integer value 8.1_INT.
+ The version of the currently-executing Android system, in a format accessible to third-party application code. For Android 9, this field MUST have the integer value 9_INT.
</td>
</tr>
<tr>
@@ -1928,15 +1777,15 @@
<td>
A string that uniquely identifies this build. It SHOULD be reasonably human-readable. It MUST follow this template:
<p class="small">
- $(BRAND)/$(PRODUCT)/<br />
+ $(BRAND)/$(PRODUCT)/<br>
$(DEVICE):$(VERSION.RELEASE)/$(ID)/$(VERSION.INCREMENTAL):$(TYPE)/$(TAGS)
</p>
<p>
For example:
</p>
<p class="small">
- acme/myproduct/<br />
- mydevice:8.1/LMYXX/3359:userdebug/test-keys
+ acme/myproduct/<br>
+ mydevice:9/LMYXX/3359:userdebug/test-keys
</p>
<p>
The fingerprint MUST NOT include whitespace characters. If other fields included in the template above have whitespace characters, they MUST be replaced in the build fingerprint with another character, such as the underscore ("_") character. The value of this field MUST be encodable as 7-bit ASCII.
@@ -1996,7 +1845,7 @@
SERIAL
</td>
<td>
- A hardware serial number, which MUST be available and unique across devices with the same MODEL and MANUFACTURER. The value of this field MUST be encodable as 7-bit ASCII and match the regular expression “^([a-zA-Z0-9]{6,20})$”.
+ MUST return "UNKNOWN".
</td>
</tr>
<tr>
@@ -2063,6 +1912,14 @@
MUST (be or return) a value chosen by the device implementer identifying the specific internal radio/modem version used in the device, in human-readable format. If a device does not have any internal radio/modem it MUST return NULL. The value of this field MUST be encodable as 7-bit ASCII and match the regular expression “^[a-zA-Z0-9._-,]+$”.
</td>
</tr>
+ <tr>
+ <td>
+ <a href="https://developer.android.com/reference/android/os/Build.html#getSerial()">getSerial()</a>
+ </td>
+ <td>
+ MUST (be or return) a hardware serial number, which MUST be available and unique across devices with the same MODEL and MANUFACTURER. The value of this field MUST be encodable as 7-bit ASCII and match the regular expression “^[a-zA-Z0-9._-,]+$”.
+ </td>
+ </tr>
</table>
<h4 id="3_2_3_intent_compatibility">
3.2.3. Intent Compatibility
@@ -2104,7 +1961,10 @@
3.2.3.2. Intent Resolution
</h5>
<ul>
- <li>[C-0-1] As Android is an extensible platform, device implementations MUST allow each intent pattern referenced in <a href="#3_2_3_1_core_application_intents">section 3.2.3.1</a> to be overridden by third-party applications. The upstream Android open source implementation allows this by default.
+ <li>
+ <p>
+ [C-0-1] As Android is an extensible platform, device implementations MUST allow each intent pattern referenced in <a href="#3_2_3_1_core_application_intents">section 3.2.3.1</a> , except for Settings, to be overridden by third-party applications. The upstream Android open source implementation allows this by default.
+ </p>
</li>
<li>
<p>
@@ -2128,7 +1988,7 @@
<ul>
<li>[C-0-4] MUST attempt to validate any intent filters by performing the validation steps defined in the <a href="https://developers.google.com/digital-asset-links">Digital Asset Links specification</a> as implemented by the Package Manager in the upstream Android Open Source Project.
</li>
- <li>[C-0-5] MUST attempt validation of the intent filters during the installation of the application and set all successfully validated UIR intent filters as default app handlers for their UIRs.
+ <li>[C-0-5] MUST attempt validation of the intent filters during the installation of the application and set all successfully validated URI intent filters as default app handlers for their URIs.
</li>
<li>MAY set specific URI intent filters as default app handlers for their URIs, if they are successfully verified but other candidate URI filters fail verification. If a device implementation does this, it MUST provide the user appropriate per-URI pattern overrides in the settings menu.
</li>
@@ -2193,13 +2053,17 @@
<ul>
<li>
<p>
- [C-2-1] MUST provide a settings menu that will call the <a href="http://developer.android.com/reference/android/provider/Telephony.Sms.Intents.html"><code>android.provider.Telephony.ACTION_CHANGE_DEFAULT</code></a> intent to show a dialog to change the default SMS application.
+ [C-2-1] MUST provide a settings menu that will call the <a href="http://developer.android.com/reference/android/provider/Telephony.Sms.Intents.html#ACTION_CHANGE_DEFAULT"><code>android.provider.Telephony.ACTION_CHANGE_DEFAULT</code></a> intent to show a dialog to change the default SMS application.
</p>
</li>
<li>
<p>
[C-2-2] MUST honor the <a href="https://developer.android.com/reference/android/telecom/TelecomManager.html#ACTION_CHANGE_DEFAULT_DIALER"><code>android.telecom.action.CHANGE_DEFAULT_DIALER</code></a> intent to show a dialog to allow the user to change the default Phone application.
</p>
+ <ul>
+ <li>MUST use the user-selected default Phone app's UI for incoming and outgoing calls except for emergency calls, which would use the preloaded Phone app.
+ </li>
+ </ul>
</li>
<li>
<p>
@@ -2234,7 +2098,7 @@
</li>
<li>[C-1-3] MUST land the new activity on the same display as the activity that launched it, when the new activity is launched without specifying a target display via the <a href="https://developer.android.com/reference/android/app/ActivityOptions.html#setLaunchDisplayId%28int%29"><code>ActivityOptions.setLaunchDisplayId()</code></a> API.
</li>
- <li>[C-1-4] MUST destory all activities, when a display with the <a href="http://developer.android.com/reference/android/view/Display.html#FLAG_PRIVATE"><code>Display.FLAG_PRIVATE</code></a> flag is removed.
+ <li>[C-1-4] MUST destroy all activities, when a display with the <a href="http://developer.android.com/reference/android/view/Display.html#FLAG_PRIVATE"><code>Display.FLAG_PRIVATE</code></a> flag is removed.
</li>
<li>[C-1-5] MUST resize accordingly all activities on a <a href="https://developer.android.com/reference/android/hardware/display/VirtualDisplay.html"><code>VirtualDisplay</code></a> if the display itself is resized.
</li>
@@ -2263,9 +2127,6 @@
3.3. Native API Compatibility
</h3>
<p>
- Device implementers are:
- </p>
- <p>
Native code compatibility is challenging. For this reason, device implementers are:
</p>
<ul>
@@ -2288,18 +2149,37 @@
</li>
<li>[C-0-3] MUST be source-compatible (i.e. header-compatible) and binary-compatible (for the ABI) with each required library in the list below.
</li>
- <li>[C-0-4] MUST support the equivalent 32-bit ABI if any 64-bit ABI is supported.
- </li>
<li>[C-0-5] MUST accurately report the native Application Binary Interface (ABI) supported by the device, via the <code>android.os.Build.SUPPORTED_ABIS</code>, <code>android.os.Build.SUPPORTED_32_BIT_ABIS</code>, and <code>android.os.Build.SUPPORTED_64_BIT_ABIS</code> parameters, each a comma separated list of ABIs ordered from the most to the least preferred one.
</li>
- <li>[C-0-6] MUST report, via the above parameters, only those ABIs documented and described in the latest version of the <a href="https://developer.android.com/ndk/guides/abis.html">Android NDK ABI Management documentation</a>, and MUST include support for the <a href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0388f/Beijfcja.html">Advanced SIMD</a> (a.k.a. NEON) extension.
- </li>
<li>
<p>
- [C-0-7] MUST make all the following libraries, providing native APIs, available to apps that include native code:
+ [C-0-6] MUST report, via the above parameters, a subset of the following list of ABIs and MUST NOT report any ABI not on the list.
</p>
<ul>
- <li>libaaudio.so (AAudio native audio support)
+ <li>
+ <code>armeabi</code>
+ </li>
+ <li>
+ <code>armeabi-v7a</code>
+ </li>
+ <li>
+ <code>arm64-v8a</code>
+ </li>
+ <li>
+ <code>x86</code>
+ </li>
+ <li>
+ <code>x86-64</code>
+ </li>
+ <li>
+ <p>
+ [C-0-7] MUST make all the following libraries, providing native APIs, available to apps that include native code:
+ </p>
+ </li>
+ <li>
+ <p>
+ libaaudio.so (AAudio native audio support)
+ </p>
</li>
<li>libandroid.so (native Android activity support)
</li>
@@ -2329,6 +2209,8 @@
</li>
<li>libm (math library)
</li>
+ <li>libneuralnetworks.so (Neural Networks API)
+ </li>
<li>libOpenMAXAL.so (OpenMAX AL 1.0.1 support)
</li>
<li>libOpenSLES.so (OpenSL ES 1.0.1 audio support)
@@ -2356,42 +2238,31 @@
</li>
<li>[C-0-11] MUST export all the OpenGL ES 3.1 and <a href="http://developer.android.com/guide/topics/graphics/opengl.html#aep">Android Extension Pack</a> function symbols, as defined in the NDK, through the <code>libGLESv3.so</code> library. Note that while all the symbols MUST be present, section 7.1.4.1 describes in more detail the requirements for when the full implementation of each corresponding functions are expected.
</li>
- <li>[C-0-12] MUST export function symbols for the core Vulkan 1.0 function symobls, as well as the <code>VK_KHR_surface</code>, <code>VK_KHR_android_surface</code>, <code>VK_KHR_swapchain</code>, <code>VK_KHR_maintenance1</code>, and <code>VK_KHR_get_physical_device_properties2</code> extensions through the <code>libvulkan.so</code> library. Note that while all the symbols MUST be present, section 7.1.4.2 describes in more detail the requirements for when the full implementation of each corresponding functions are expected.
+ <li>[C-0-12] MUST export function symbols for the core Vulkan 1.0 function symbols, as well as the <code>VK_KHR_surface</code>, <code>VK_KHR_android_surface</code>, <code>VK_KHR_swapchain</code>, <code>VK_KHR_maintenance1</code>, and <code>VK_KHR_get_physical_device_properties2</code> extensions through the <code>libvulkan.so</code> library. Note that while all the symbols MUST be present, section 7.1.4.2 describes in more detail the requirements for when the full implementation of each corresponding functions are expected.
</li>
<li>SHOULD be built using the source code and header files available in the upstream Android Open Source Project
</li>
</ul>
<p>
- Note that future releases of the Android NDK may introduce support for additional ABIs.
+ Note that future releases of Android may introduce support for additional ABIs.
</p>
<h4 id="3_3_2_32-bit_arm_native_code_compatibility">
3.3.2. 32-bit ARM Native Code Compatibility
</h4>
<p>
- If device implementations are 64-bit ARM devices, then:
+ If device implementations report the support of the <code>armeabi</code> ABI, they:
</p>
<ul>
- <li>
- <p>
- [C-1-1] Although the ARMv8 architecture deprecates several CPU operations, including some operations used in existing native code, the following deprecated operations MUST remain available to 32-bit native ARM code, either through native CPU support or through software emulation:
- </p>
- <ul>
- <li>SWP and SWPB instructions
- </li>
- <li>SETEND instruction
- </li>
- <li>CP15ISB, CP15DSB, and CP15DMB barrier operations
- </li>
- </ul>
+ <li>[C-3-1] MUST also support <code>armeabi-v7a</code> and report its support, as <code>armeabi</code> is only for backwards compatibility with older apps.
</li>
</ul>
<p>
- If device implementations include a 32-bit ARM ABI, they:
+ If device implementations report the support of the <code>armeabi-v7a</code> ABI, for apps using this ABI, they:
</p>
<ul>
<li>
<p>
- [C-2-1] MUST include the following lines in <code>/proc/cpuinfo</code> when it is read by 32-bit ARM applications to ensure compatibility with applications built using legacy versions of Android NDK.
+ [C-2-1] MUST include the following lines in <code>/proc/cpuinfo</code>, and SHOULD NOT alter the values on the same device, even when they are read by other ABIs.
</p>
<ul>
<li>
@@ -2404,7 +2275,20 @@
</li>
<li>
<p>
- SHOULD not alter <code>/proc/cpuinfo</code> when read by 64-bit ARM or non-ARM applications.
+ [C-2-2] MUST always keep the following operations available, even in the case where the ABI is implemented on an ARMv8 architecture, either through native CPU support or through software emulation:
+ </p>
+ <ul>
+ <li>SWP and SWPB instructions.
+ </li>
+ <li>SETEND instruction.
+ </li>
+ <li>CP15ISB, CP15DSB, and CP15DMB barrier operations.
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [C-2-3] MUST include support for the <a href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0388f/Beijfcja.html">Advanced SIMD</a> (a.k.a. NEON) extension.
</p>
</li>
</ul>
@@ -2420,7 +2304,7 @@
<ul>
<li>[C-1-1] MUST report <code>android.software.webview</code>.
</li>
- <li>[C-1-2] MUST use the <a href="http://www.chromium.org/">Chromium</a> Project build from the upstream Android Open Source Project on the Android 8.1 branch for the implementation of the <a href="http://developer.android.com/reference/android/webkit/WebView.html"><code>android.webkit.WebView</code></a> API.
+ <li>[C-1-2] MUST use the <a href="http://www.chromium.org/">Chromium</a> Project build from the upstream Android Open Source Project on the Android 9 branch for the implementation of the <a href="http://developer.android.com/reference/android/webkit/WebView.html"><code>android.webkit.WebView</code></a> API.
</li>
<li>
<p>
@@ -2486,6 +2370,15 @@
3.5. API Behavioral Compatibility
</h3>
<p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-9] MUST ensure that API behavioral compatibility is applied for all installed apps unless they are restricted as described in <a href="#3_5_1-background-restriction">Section 3.5.1</a>.
+ </li>
+ <li>[C-0-10] MUST NOT implement the whitelisting approach that ensures API behavioral compatibility only for apps that are selected by device implementers.
+ </li>
+ </ul>
+ <p>
The behaviors of each of the API types (managed, soft, native, and web) must be consistent with the preferred implementation of the upstream <a href="http://source.android.com/">Android Open Source Project</a>. Some specific areas of compatibility are:
</p>
<ul>
@@ -2509,10 +2402,61 @@
</li>
</ul>
</li>
+ <li>[C-0-9] Devices MUST return the following security providers as the first seven array values from the <a href="https://developer.android.com/reference/java/security/Security.html#getProviders%28%29"><code>Security.getProviders()</code></a> method, in the given order and with the given names (as returned by <a href="https://developer.android.com/reference/java/security/Provider.html#getName%28%29"><code>Provider.getName()</code></a>) and classes, unless the app has modified the list via <a href="https://developer.android.com/reference/java/security/Security.html#insertProviderAt%28java.security.Provider,%2520int%29"><code>insertProviderAt()</code></a> or <a href="https://developer.android.com/reference/java/security/Security.html#removeProvider%28java.lang.String%29"><code>removeProvider()</code></a>. Devices MAY return additional providers after the specified list of providers below.
+ <ol>
+ <li>
+ <strong>AndroidNSSP</strong> - <code>android.security.net.config.NetworkSecurityConfigProvider</code>
+ </li>
+ <li>
+ <strong>AndroidOpenSSL</strong> - <code>com.android.org.conscrypt.OpenSSLProvider</code>
+ </li>
+ <li>
+ <strong>CertPathProvider</strong> - <code>sun.security.provider.CertPathProvider</code>
+ </li>
+ <li>
+ <strong>AndroidKeyStoreBCWorkaround</strong> - <code>android.security.keystore.AndroidKeyStoreBCWorkaroundProvider</code>
+ </li>
+ <li>
+ <strong>BC</strong> - <code>com.android.org.bouncycastle.jce.provider.BouncyCastleProvider</code>
+ </li>
+ <li>
+ <strong>HarmonyJSSE</strong> - <code>com.android.org.conscrypt.JSSEProvider</code>
+ </li>
+ <li>
+ <strong>AndroidKeyStore</strong> - <code>android.security.keystore.AndroidKeyStoreProvider</code>
+ </li>
+ </ol>
+ </li>
</ul>
<p>
The above list is not comprehensive. The Compatibility Test Suite (CTS) tests significant portions of the platform for behavioral compatibility, but not all. It is the responsibility of the implementer to ensure behavioral compatibility with the Android Open Source Project. For this reason, device implementers SHOULD use the source code available via the Android Open Source Project where possible, rather than re-implement significant parts of the system.
</p>
+ <h3 id="3_5_1_background_restriction">
+ 3.5.1. Background Restriction
+ </h3>
+ <p>
+ If device implementations implement the app restrictions that are included in AOSP or extend the app restrictions, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST provide user affordance where the user can see the list of restricted apps.
+ </li>
+ <li>[C-1-2] MUST provide user affordance to turn on / off the restrictions on each app.
+ </li>
+ <li>[C-1-3] MUST not automatically apply restrictions without evidence of poor system health behaviour, but MAY apply the restrictions on apps upon detection of poor system health behaviour like stuck wakelocks, long running services, and other criteria. The criteria MAY be determined by device implementers but MUST be related to the app’s impact on the system health. Other criteria that is not purely related to the system health, such as the app’s lack of popularity in the market, MUST NOT be used as criteria.
+ </li>
+ <li>[C-1-4] MUST not automatically apply app restrictions for apps when a user has turned off app restrictions manually, and MAY suggest the user to apply app restrictions.
+ </li>
+ <li>[C-1-5] MUST inform users if app restrictions are applied to an app automatically.
+ </li>
+ <li>[C-1-6] MUST return <code>true</code> for <a href="https://developer.android.com/reference/android/app/ActivityManager.html#isBackgroundRestricted%28%29"><code>ActivityManager.isBackgroundRestricted()</code></a> when the restricted app calls this API.
+ </li>
+ <li>[C-1-7] MUST NOT restrict the top foreground app that is explicitly used by the user.
+ </li>
+ <li>[C-1-8] MUST suspend restrictions on an app that becomes the top foreground application when the user explicitly starts to use the app that used to be restricted.
+ </li>
+ <li>[C-1-9] MUST report all app restriction events via <a href="https://developer.android.com/reference/android/app/usage/UsageStats"><code>UsageStats</code></a>. If device implementations extend the app restrictions that are implemented in AOSP, MUST follow the implementation described in <a href="https://souce.android.com/devices/tech/power/app_mgmt.html">this document</a>.
+ </li>
+ </ul>
<h3 id="3_6_api_namespaces">
3.6. API Namespaces
</h3>
@@ -2533,6 +2477,9 @@
<code>android.*</code>
</li>
<li>
+ <code>androidx.*</code>
+ </li>
+ <li>
<code>com.android.*</code>
</li>
</ul>
@@ -3074,7 +3021,7 @@
<ul>
<li>[C-1-1] MUST support notifications that use hardware features, as described in the SDK documentation, and to the extent possible with the device implementation hardware. For instance, if a device implementation includes a vibrator, it MUST correctly implement the vibration APIs. If a device implementation lacks hardware, the corresponding APIs MUST be implemented as no-ops. This behavior is further detailed in <a href="#7_hardware_compatibility">section 7</a>.
</li>
- <li>[C-1-2] MUST correctly render all <a href="https://developer.android.com/guide/topics/resources/available-resources.html">resources</a> (icons, animation files etc.) provided for in the APIs, or in the Status/System Bar <a href="http://developer.android.com/design/style/iconography.html">icon style guide</a>, although they MAY provide an alternative user experience for notifications than that provided by the reference Android Open Source implementation.
+ <li>[C-1-2] MUST correctly render all <a href="https://developer.android.com/guide/topics/resources/available-resources.html">resources</a> (icons, animation files, etc.) provided for in the APIs, or in the Status/System Bar <a href="http://developer.android.com/design/style/iconography.html">icon style guide</a>, although they MAY provide an alternative user experience for notifications than that provided by the reference Android Open Source implementation.
</li>
<li>[C-1-3] MUST honor and implement properly the behaviors described for <a href="https://developer.android.com/guide/topics/ui/notifiers/notifications.html#Managing">the APIs</a> to update, remove and group notifications.
</li>
@@ -3084,6 +3031,10 @@
</li>
<li>[C-1-6] MUST also provide a user affordance to display deleted notification channels.
</li>
+ <li>[C-1-7] MUST correctly render all resources (images, stickers, icons, etc.) provided through <a href="https://developer.android.com/reference/android/app/Notification.MessagingStyle">Notification.MessagingStyle</a> alongside the notification text without additional user interaction. For example, MUST show all resources including icons provided through <a href="https://developer.android.com/reference/android/app/Person">android.app.Person</a> in a group conversation that is set through <a href="https://developer.android.com/reference/android/app/Notification.MessagingStyle.html?hl=es-AR#setGroupConversation%28boolean%29">setGroupConversation</a>.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to automatically surface a user affordance to block a certain third-party app's notification per each channel and app package level after the user dismisses that notification multiple times.
+ </li>
<li>SHOULD support rich notifications.
</li>
<li>SHOULD present some higher priority notifications as heads-up notifications.
@@ -3103,11 +3054,13 @@
</li>
</ul>
<p>
- If device impelementations support heads-up notifications: they:
+ If device implementation support heads-up notifications: they:
</p>
<ul>
<li>[C-3-1] MUST use the heads-up notification view and resources as described in the <a href="https://developer.android.com/reference/android/app/Notification.Builder.html"><code>Notification.Builder</code></a> API class when heads-up notifications are presented.
</li>
+ <li>[C-3-2] MUST display the actions provided through <a href="https://developer.android.com/reference/android/app/Notification.Builder#addAction%28android.app.Notification.Action%29"><code>Notification.Builder.addAction()</code></a> together with the notification content without additional user interaction as described in <a href="https://developer.android.com/guide/topics/ui/notifiers/notifications.html#Heads-up">the SDK</a>.
+ </li>
</ul>
<h5 id="3_8_3_2_notification_listener_service">
3.8.3.2. Notification Listener Service
@@ -3188,8 +3141,6 @@
</li>
<li>[C-2-2] The designated interaction to launch the assist app as described in <a href="#7_2_3_navigation_keys">section 7.2.3</a> MUST launch the user-selected assist app, in other words the app that implements <code>VoiceInteractionService</code>, or an activity handling the <code>ACTION_ASSIST</code> intent.
</li>
- <li>[SR] STRONGLY RECOMMENDED to use long press on <code>HOME</code> key as this designated interaction.
- </li>
</ul>
<h4 id="3_8_5_alerts_and_toasts">
3.8.5. Alerts and Toasts
@@ -3292,21 +3243,15 @@
</li>
<li>SHOULD display a closing affordance ("x") but MAY delay this until user interacts with screens.
</li>
- <li>SHOULD implement a shortcut to switch easily to the previous activity
+ <li>SHOULD implement a shortcut to switch easily to the previous activity.
</li>
<li>SHOULD trigger the fast-switch action between the two most recently used apps, when the recents function key is tapped twice.
</li>
<li>SHOULD trigger the split-screen multiwindow-mode, if supported, when the recents functions key is long pressed.
</li>
- <li>
- <p>
- MAY display affiliated recents as a group that moves together.
- </p>
+ <li>MAY display affiliated recents as a group that moves together.
</li>
- <li>
- <p>
- [SR] Are STRONGLY RECOMMENDED to use the upstream Android user interface (or a similar thumbnail-based interface) for the overview screen.
- </p>
+ <li>[SR] Are STRONGLY RECOMMENDED to use the upstream Android user interface (or a similar thumbnail-based interface) for the overview screen.
</li>
</ul>
<h4 id="3_8_9_input_management">
@@ -3341,16 +3286,18 @@
3.8.11. Screen savers (previously Dreams)
</h4>
<p>
- Android includes support for <a href="http://developer.android.com/reference/android/service/dreams/DreamService.html">interactivescreensavers</a>, previously referred to as Dreams. Screen savers allow users to interact with applications when a device connected to a power source is idle or docked in a desk dock. Android Watch devices MAY implement screen savers, but other types of device implementations SHOULD include support for screen savers and provide a settings option for users toconfigure screen savers in response to the <code>android.settings.DREAM_SETTINGS</code> intent.
+ Android includes support for <a href="http://developer.android.com/reference/android/service/dreams/DreamService.html">interactivescreensavers</a>, previously referred to as Dreams. Screen savers allow users to interact with applications when a device connected to a power source is idle or docked in a desk dock. Android Watch devices MAY implement screen savers, but other types of device implementations SHOULD include support for screen savers and provide a settings option for users to configure screen savers in response to the <code>android.settings.DREAM_SETTINGS</code> intent.
</p>
<h4 id="3_8_12_location">
3.8.12. Location
</h4>
<p>
- If device implementations include a hardware sensor (e.g. GPS) that is capable of providing the location coordinates:
+ If device implementations include a hardware sensor (e.g. GPS) that is capable of providing the location coordinates, they
</p>
<ul>
- <li>[C-1-1] <a href="http://developer.android.com/reference/android/provider/Settings.Secure.html#LOCATION_MODE">location modes</a> MUST be displayed in the Location menu within Settings.
+ <li>[C-1-2] MUST display the <a href="https://developer.android.com/reference/android/location/LocationManager.html#isLocationEnabled%28%29">current status of location</a> in the Location menu within Settings.
+ </li>
+ <li>[C-1-3] MUST NOT display <a href="https://developer.android.com/reference/android/provider/Settings.Secure.html#LOCATION_MODE">location modes</a> in the Location menu within Settings.
</li>
</ul>
<h4 id="3_8_13_unicode_and_font">
@@ -3366,10 +3313,12 @@
<li>[C-1-1] MUST be capable of rendering these emoji characters in color glyph.
</li>
<li>[C-1-2] MUST include support for:
- </li>
- <li>Roboto 2 font with different weights—sans-serif-thin, sans-serif-light, sans-serif-medium, sans-serif-black, sans-serif-condensed, sans-serif-condensed-light for the languages available on the device.
- </li>
- <li>Full Unicode 7.0 coverage of Latin, Greek, and Cyrillic, including the Latin Extended A, B, C, and D ranges, and all glyphs in the currency symbols block of Unicode 7.0.
+ <ul>
+ <li>Roboto 2 font with different weights—sans-serif-thin, sans-serif-light, sans-serif-medium, sans-serif-black, sans-serif-condensed, sans-serif-condensed-light for the languages available on the device.
+ </li>
+ <li>Full Unicode 7.0 coverage of Latin, Greek, and Cyrillic, including the Latin Extended A, B, C, and D ranges, and all glyphs in the currency symbols block of Unicode 7.0.
+ </li>
+ </ul>
</li>
<li>SHOULD support the skin tone and diverse family emojis as specified in the <a href="http://unicode.org/reports/tr51">Unicode Technical Report #51</a>.
</li>
@@ -3392,7 +3341,7 @@
</li>
<li>[C-1-2] Applications can indicate whether they are capable of operating in multi-window mode in the <code>AndroidManifest.xml</code> file, either explicitly via setting the <a href="https://developer.android.com/reference/android/R.attr.html#resizeableActivity"><code>android:resizeableActivity</code></a> attribute to <code>true</code> or implicitly by having the targetSdkVersion > 24. Apps that explicitly set this attribute to <code>false</code> in their manifest MUST NOT be launched in multi-window mode. Older apps with targetSdkVersion < 24 that did not set this <code>android:resizeableActivity</code> attribute MAY be launched in multi-window mode, but the system MUST provide warning that the app may not work as expected in multi-window mode.
</li>
- <li>[C-1-3] MUST NOT offer split-screen or freeform mode if the screen height < 440 dp and the the screen width < 440 dp.
+ <li>[C-1-3] MUST NOT offer split-screen or freeform mode if the screen height < 440 dp and the screen width < 440 dp.
</li>
<li>Device implementations with screen size <code>xlarge</code> SHOULD support freeform mode.
</li>
@@ -3422,14 +3371,33 @@
</li>
<li>[C-3-5] MUST provide a user affordance to block an app from displaying in PIP mode; the AOSP implementation meets this requirement by having controls in the notification shade.
</li>
- <li>[C-3-6] MUST allocate minimum width and height of 108 dp for the PIP window and minimum width of 240 dp and height of 135 dp for the PIP window when the <code>Configuration.uiMode</code> is configured as <a href="https://developer.android.com/reference/android/content/res/Configuration.html#UI_MODE_TYPE_TELEVISION"><code>UI_MODE_TYPE_TELEVISION</code></a>
+ <li>[C-3-6] MUST allocate minimum width and height of 108 dp for the PIP window and minimum width of 240 dp and height of 135 dp for the PIP window when the <code>Configuration.uiMode</code> is configured as <a href="https://developer.android.com/reference/android/content/res/Configuration.html#UI_MODE_TYPE_TELEVISION"><code>UI_MODE_TYPE_TELEVISION</code></a>.
+ </li>
+ </ul>
+ <h4 id="3_8_15_display_cutout">
+ 3.8.15. Display Cutout
+ </h4>
+ <p>
+ Android supports a Display Cutout as described in the SDK document. The <a href="https://developer.android.com/reference/android/view/DisplayCutout"><code>DisplayCutout</code></a> API defines an area on the edge of the display that is not functional for displaying content.
+ </p>
+ <p>
+ If device implementations include display cutout(s), they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST only have cutout(s) on the short edge(s) of the device. Conversely, if the device's aspect ratio is 1.0(1:1), they MUST NOT have cutout(s).
+ </li>
+ <li>[C-1-2] MUST NOT have more than one cutout per edge.
+ </li>
+ <li>[C-1-3] MUST honor the display cutout flags set by the app through the <a href="https://developer.android.com/reference/android/view/WindowManager.LayoutParams"><code>WindowManager.LayoutParams</code></a> API as described in the SDK.
+ </li>
+ <li>[C-1-4] MUST report correct values for all cutout metrics defined in the <a href="https://developer.android.com/reference/android/view/DisplayCutout"><code>DisplayCutout</code></a> API.
</li>
</ul>
<h3 id="3_9_device_administration">
3.9. Device Administration
</h3>
<p>
- Android includes features that allow security-aware applications to perform device administration functions at the system level, such as enforcing password policies or performing remote wipe, through the <a href="http://developer.android.com/guide/topics/admin/device-admin.html">Android Device Administration API</a>].
+ Android includes features that allow security-aware applications to perform device administration functions at the system level, such as enforcing password policies or performing remote wipe, through the <a href="http://developer.android.com/guide/topics/admin/device-admin.html">Android Device Administration API</a>.
</p>
<p>
If device implementations implement the full range of <a href="http://developer.android.com/guide/topics/admin/device-admin.html">device administration</a> policies defined in the Android SDK documentation, they:
@@ -3439,8 +3407,6 @@
</li>
<li>[C-1-2] MUST support device owner provisioning as described in <a href="#3_9_1_device_provisioning">section 3.9.1</a> and <a href="#3_9_1_1_device_owner_provisioning">section 3.9.1.1</a>.
</li>
- <li>[C-1-3] MUST declare the support of manged profiles via the <code>android.software.managed_users</code> feature flag, except for when the device is configured so that it would <a href="http://developer.android.com/reference/android/app/ActivityManager.html#isLowRamDevice%28%29">report</a> itself as a low RAM device or so that it allocate internal (non-removable) storage as shared storage.
- </li>
</ul>
<h4 id="3_9_1_device_provisioning">
3.9.1 Device Provisioning
@@ -3452,9 +3418,9 @@
If device implementations declare <code>android.software.device_admin</code>, they:
</p>
<ul>
- <li>[C-1-1] MUST support enrolling a Device Policy Client (DPC) as a <a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#isDeviceOwnerApp%28java.lang.String%29">Device Owner app</a> as described below:.
+ <li>[C-1-1] MUST support enrolling a Device Policy Client (DPC) as a <a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#isDeviceOwnerApp%28java.lang.String%29">Device Owner app</a> as described below:
<ul>
- <li>when the device implementation has no user data is configured yet, it:
+ <li>When the device implementation has no user data is configured yet, it:
<ul>
<li>[C-1-3] MUST report <code>true</code> for <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#isProvisioningAllowed(java.lang.String)"><code>DevicePolicyManager.isProvisioningAllowed(ACTION_PROVISION_MANAGED_DEVICE)</code></a>.
</li>
@@ -3474,7 +3440,7 @@
</li>
</ul>
</li>
- <li>[C-1-2] MUST NOT set an application (including pre-installed app) as the Device Owner app without explicit consent or action from the user or the administrator of the device.
+ <li>[C-1-2] MUST require some affirmative action during the provisioning process to consent to the app being set as Device Owner. Consent can be via user action or by some programmatic means during provisioning but it MUST NOT be hard coded or prevent the use of other Device Owner apps.
</li>
</ul>
<p>
@@ -3519,9 +3485,9 @@
</ul>
</li>
</ul>
- <h3 id="3_9_2_managed_profile_support">
+ <h4 id="3_9_2_managed_profile_support">
3.9.2 Managed Profile Support
- </h3>
+ </h4>
<p>
If device implementations declare <code>android.software.managed_users</code>, they:
</p>
@@ -3530,7 +3496,7 @@
</li>
<li>[C-1-2] MUST allow one and only <a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#ACTION_PROVISION_MANAGED_PROFILE">one managed profile to be created</a>.
</li>
- <li>[C-1-3] MUST use an icon badge (similar to the AOSP upstream work badge) to represent the managed applications and widgets and other badged UI elements like Recents & Notifications.
+ <li>[C-1-3] MUST use an icon badge (similar to the AOSP upstream work badge) to represent the managed applications and widgets and other badged UI elements like Recents & Notifications.
</li>
<li>[C-1-4] MUST display a notification icon (similar to the AOSP upstream work badge) to indicate when user is within a managed profile application.
</li>
@@ -3558,7 +3524,7 @@
<ul>
<li>Device implementations MUST honor the <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#ACTION_SET_NEW_PASSWORD"><code>DevicePolicyManager.ACTION_SET_NEW_PASSWORD</code></a> intent and show an interface to configure a separate lock screen credential for the managed profile.
</li>
- <li>The lock screen credentials of the managed profile MUST use the same credential storage and management mechanisms as the parent profile, as documented on the <a href="http://source.android.com/security/authentication/index.html">Android Open Source Project Site</a>
+ <li>The lock screen credentials of the managed profile MUST use the same credential storage and management mechanisms as the parent profile, as documented on the <a href="http://source.android.com/security/authentication/index.html">Android Open Source Project Site</a>.
</li>
<li>The DPC <a href="https://developer.android.com/guide/topics/admin/device-admin.html#pwd">password policies</a> MUST apply to only the managed profile's lock screen credentials unless called upon the <code>DevicePolicyManager</code> instance returned by <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#getParentProfileInstance%28android.content.ComponentName%29">getParentProfileInstance</a>.
</li>
@@ -3567,6 +3533,16 @@
<li>When contacts from the managed profile are displayed in the preinstalled call log, in-call UI, in-progress and missed-call notifications, contacts and messaging apps they SHOULD be badged with the same badge used to indicate managed profile applications.
</li>
</ul>
+ <h3 id="3_9_3_managed_user_support">
+ 3.9.3 Managed User Support
+ </h3>
+ <p>
+ If device implementations declare <code>android.software.managed_users</code>, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST provide a user affordance to logout from the current user and switch back to the primary user in multiple-user session when <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#isLogoutEnabled%28%29"><code>isLogoutEnabled</code></a> returns <code>true</code>. The user affordance MUST be accessible from the lockscreen without unlocking the device.
+ </li>
+ </ul>
<h3 id="3_10_accessibility">
3.10. Accessibility
</h3>
@@ -3590,7 +3566,7 @@
If device implementations include preloaded accessibility services, they:
</p>
<ul>
- <li>[C-2-1] MUST implement these preloaded accessibility services as [Direct Boot aware] (https://developer.android.com/reference/android/content/pm/ComponentInfo.html#directBootAware) apps when the data storage is encrypted with File Based Encryption (FBE).
+ <li>[C-2-1] MUST implement these preloaded accessibility services as <a href="https://developer.android.com/reference/android/content/pm/ComponentInfo.html#directBootAware">Direct Boot Aware</a> apps when the data storage is encrypted with File Based Encryption (FBE).
</li>
<li>SHOULD provide a mechanism in the out-of-box setup flow for users to enable relevant accessibility services, as well as options to adjust the font size, display size and magnification gestures.
</li>
@@ -3627,107 +3603,7 @@
<ul>
<li>[C-1-1] MUST declare the platform feature <code>android.software.live_tv</code>.
</li>
- <li>[C-1-2] MUST preload a TV application (TV App) and meet all requirements described in <a href="#3_12_tv-input-framework">section 3.12.1</a>.
- </li>
- </ul>
- <h4 id="3_12_1_tv_app">
- 3.12.1. TV App
- </h4>
- <p>
- If device implementations support TIF:
- </p>
- <ul>
- <li>[C-1-1] The TV App MUST provide facilities to install and use <a href="http://developer.android.com/reference/android/media/tv/TvContract.Channels.html">TV Channels</a> and meet the following requirements:
- </li>
- </ul>
- <p>
- The TV app that is required for Android device implementations declaring the <code>android.software.live_tv</code> feature flag, MUST meet the following requirements:
- </p>
- <ul>
- <li>Device implementations SHOULD allow third-party TIF-based inputs (<a href="https://source.android.com/devices/tv/index.html#third-party_input_example">third-party inputs</a>) to be installed and managed.
- </li>
- <li>Device implementations MAY provide visual separation between pre-installed <a href="https://source.android.com/devices/tv/index.html#tv_inputs">TIF-based inputs</a> (installed inputs) and third-party inputs.
- </li>
- <li>Device implementations SHOULD NOT display the third-party inputs more than a single navigation action away from the TV App (i.e. expanding a list of third-party inputs from the TV App).
- </li>
- </ul>
- <p>
- The Android Open Source Project provides an implementation of the TV App that meets the above requirements.
- </p>
- <h5 id="3_12_1_1_electronic_program_guide">
- 3.12.1.1. Electronic Program Guide
- </h5>
- <p>
- If device implementations support TIF, they:
- </p>
- <ul>
- <li>[C-1-1] MUST show an informational and interactive overlay, which MUST include an electronic program guide (EPG) generated from the values in the <a href="https://developer.android.com/reference/android/media/tv/TvContract.Programs.html">TvContract.Programs</a> fields.
- </li>
- <li>[C-1-2] On channel change, device implementations MUST display EPG data for the currently playing program.
- </li>
- <li>[SR] The EPG is STRONGLY RECOMMENDED to display installed inputs and third-party inputs with equal prominence. The EPG SHOULD NOT display the third-party inputs more than a single navigation action away from the installed inputs on the EPG.
- </li>
- <li>The EPG SHOULD display information from all installed inputs and third-party inputs.
- </li>
- <li>The EPG MAY provide visual separation between the installed inputs and third-party inputs.
- </li>
- </ul>
- <h5 id="3_12_1_2_navigation">
- 3.12.1.2. Navigation
- </h5>
- <p>
- If device implementations support TIF, they:
- </p>
- <ul>
- <li>
- <p>
- [C-1-1] MUST allow navigation for the following functions via the D-pad, Back, and Home keys on the Android Television device’s input device(s) (i.e. remote control, remote control application, or game controller):
- </p>
- <ul>
- <li>Changing TV channels
- </li>
- <li>Opening EPG
- </li>
- <li>Configuring and tuning to third-party TIF-based inputs (if those inputs are supported)
- </li>
- <li>Opening Settings menu
- </li>
- </ul>
- </li>
- <li>
- <p>
- SHOULD pass key events to HDMI inputs through CEC.
- </p>
- </li>
- </ul>
- <h5 id="3_12_1_3_tv_input_app_linking">
- 3.12.1.3. TV input app linking
- </h5>
- <p>
- Android Television device implementations SHOULD support <a href="http://developer.android.com/reference/android/media/tv/TvContract.Channels.html#COLUMN_APP_LINK_INTENT_URI">TV input app linking</a>, which allows all inputs to provide activity links from the current activity to another activity (i.e. a link from live programming to related content). The TV App SHOULD show TV input app linking when it is provided.
- </p>
- <h5 id="3_12_1_4_time_shifting">
- 3.12.1.4. Time shifting
- </h5>
- <p>
- If device implementations support TIF, they:
- </p>
- <ul>
- <li>[SR] STRONGLY RECOMMENDED to support time shifting, which allows the user to pause and resume live content.
- </li>
- <li>SHOULD provide the user a way to pause and resume the currently playing program, if time shifting for that program <a href="https://developer.android.com/reference/android/media/tv/TvInputManager.html#TIME_SHIFT_STATUS_AVAILABLE">is available</a>.
- </li>
- </ul>
- <h5 id="3_12_1_5_tv_recording">
- 3.12.1.5. TV recording
- </h5>
- <p>
- If device implementations support TIF, they:
- </p>
- <ul>
- <li>[SR] STRONGLY RECOMMENDED to support TV recording.
- </li>
- <li>If the TV input supports recording and the recording of a program is not <a href="https://developer.android.com/reference/android/media/tv/TvContract.Programs.html#COLUMN_RECORDING_PROHIBITED">prohibited</a>, the EPG MAY provide a way to <a href="https://developer.android.com/reference/android/media/tv/TvInputInfo.html#canRecord%28%29">record a program</a>.
+ <li>[C-1-2] MUST support all TIF APIs such that an application which uses these APIs and the <a href="https://source.android.com/devices/tv/index.html#third-party_input_example">third-party TIF-based inputs</a> service can be installed and used on the device.
</li>
</ul>
<h3 id="3_13_quick_settings">
@@ -3760,7 +3636,7 @@
</li>
<li>[C-1-3] MUST show app title.
</li>
- <li>[C-1-4] MUST have drawer to present <a href="http://developer.android.com/reference/android/media/browse/MediaBrowser.html">MediaBrowser</a> hierarchy.
+ <li>[C-1-4] MUST have a drawer or other mechanism to present <a href="http://developer.android.com/reference/android/media/browse/MediaBrowser.html">MediaBrowser</a> hierarchy and provide user affordance for the <a href="http://developer.android.com/reference/android/media/browse/MediaBrowser.html">MediaBrowser</a> hierarchy.
</li>
<li>[C-1-5] MUST consider double tap of <a href="https://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_HEADSETHOOK"><code>KEYCODE_HEADSETHOOK</code></a> or <a href="https://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_MEDIA_PLAY_PAUSE"><code>KEYCODE_MEDIA_PLAY_PAUSE</code></a> as <a href="https://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_MEDIA_NEXT"><code>KEYCODE_MEDIA_NEXT</code></a> for <a href="https://developer.android.com/reference/android/media/session/MediaSession.Callback.html#onMediaButtonEvent%28android.content.Intent%29"><code>MediaSession.Callback#onMediaButtonEvent</code></a>.
</li>
@@ -3772,7 +3648,7 @@
Device implementations MUST satisfy the following requirements:
</p>
<ul>
- <li>[C-0-1] Instant Apps MUST only be granted permissions that have the <a href="https://developer.android.com/guide/topics/manifest/permission-element.html#plevel"><code>android:protectionLevel</code></a> set to <code>"ephemeral"</code>.
+ <li>[C-0-1] Instant Apps MUST only be granted permissions that have the <a href="https://developer.android.com/reference/android/R.attr#protectionLevel"><code>android:protectionLevel</code></a> set to <code>"instant"</code>.
</li>
<li>[C-0-2] Instant Apps MUST NOT interact with installed apps via <a href="https://developer.android.com/reference/android/content/Intent.html">implicit intents</a> unless one of the following is true:
<ul>
@@ -3806,6 +3682,27 @@
<li>[C-1-3] MUST provide user affordances for the user to select/confirm a companion device is present and operational.
</li>
</ul>
+ <h3 id="3_17_heavyweight_apps">
+ 3.17. Heavyweight Apps
+ </h3>
+ <p>
+ If device implementations declare the feature <a href="https://developer.android.com/reference/android/content/pm/PackageManager.html#FEATURE_CANT_SAVE_STATE"><code>FEATURE_CANT_SAVE_STATE</code></a>, then they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST have only one installed app that specifies <a href="https://developer.android.com/reference/android/R.attr#cantSaveState"><code>cantSaveState</code></a> running in the system at a time. If the user leaves such an app without explicitly exiting it (for example by pressing home while leaving an active activity the system, instead of pressing back with no remaining active activities in the system), then device implementations MUST prioritize that app in RAM as they do for other things that are expected to remain running, such as foreground services. While such an app is in the background, the system can still apply power management features to it, such as limiting CPU and network access.
+ </li>
+ <li>[C-1-2] MUST provide a UI affordance to chose the app that won't participate in the normal state save/restore mechanism once the user launches a second app declared with <a href="https://developer.android.com/reference/android/R.attr#cantSaveState"><code>cantSaveState</code></a> attribute.
+ </li>
+ <li>[C-1-3] MUST NOT apply other changes in policy to apps that specify <a href="https://developer.android.com/reference/android/R.attr#cantSaveState"><code>cantSaveState</code></a>, such as changing CPU performance or changing scheduling prioritization.
+ </li>
+ </ul>
+ <p>
+ If device implementations don't declare the feature <a href="https://developer.android.com/reference/android/content/pm/PackageManager.html#FEATURE_CANT_SAVE_STATE"><code>FEATURE_CANT_SAVE_STATE</code></a>, then they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST ignore the <a href="https://developer.android.com/reference/android/R.attr#cantSaveState"><code>cantSaveState</code></a> attribute set by apps and MUST NOT change the app behavior based on that attribute.
+ </li>
+ </ul>
<h2 id="4_application_packaging_compatibility">
4. Application Packaging Compatibility
</h2>
@@ -3815,27 +3712,51 @@
<ul>
<li>[C-0-1] MUST be capable of installing and running Android “.apk” files as generated by the “aapt” tool included in the <a href="http://developer.android.com/tools/help/index.html">official Android SDK</a>.
</li>
- <li>As the above requirement may be challenging, device implementations are RECOMMENDED to use the AOSP reference implementation's package management systemDevice implementations.
+ <li>As the above requirement may be challenging, device implementations are RECOMMENDED to use the AOSP reference implementation's package management system.
</li>
- <li>[C-0-2] MUST support verifying “.apk” files using the <a href="https://source.android.com/security/apksigning/v2.html">APK Signature Scheme v2</a> and <a href="https://source.android.com/security/apksigning/v2.html#v1-verification">JAR signing</a>.
+ </ul>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-2] MUST support verifying “.apk” files using the <a href="https://source.android.com/security/apksigning/v3.html">APK Signature Scheme v3</a> , <a href="https://source.android.com/security/apksigning/v2.html">APK Signature Scheme v2</a> and <a href="https://source.android.com/security/apksigning/v2.html#v1-verification">JAR signing</a>.
</li>
<li>[C-0-3] MUST NOT extend either the <a href="http://developer.android.com/guide/components/fundamentals.html">.apk</a>, <a href="http://developer.android.com/guide/topics/manifest/manifest-intro.html">Android Manifest</a>, <a href="https://android.googlesource.com/platform/dalvik/">Dalvik bytecode</a>, or RenderScript bytecode formats in such a way that would prevent those files from installing and running correctly on other compatible devices.
</li>
- <li>[C-0-4] MUST NOT allow apps other than the current "installer of record" for the package to silently uninstall the app without any prompt, as documented in the SDK for the <a href="https://developer.android.com/reference/android/Manifest.permission.html#DELETE_PACKAGES"><code>DELETE_PACKAGE</code></a> permission. The only exceptions are the system package verifier app handling <a href="https://developer.android.com/reference/android/content/Intent.html#ACTION_PACKAGE_NEEDS_VERIFICATION">PACKAGE_NEEDS_VERIFICATION</a> intent and the storage manager app handling <a href="https://developer.android.com/reference/android/os/storage/StorageManager.html#ACTION_MANAGE_STORAGE">ACTION_MANAGE_STORAGE</a> intent.
+ <li>
+ <p>
+ [C-0-4] MUST NOT allow apps other than the current "installer of record" for the package to silently uninstall the app without any user confirmation, as documented in the SDK for the <a href="https://developer.android.com/reference/android/Manifest.permission.html#DELETE_PACKAGES"><code>DELETE_PACKAGE</code></a> permission. The only exceptions are the system package verifier app handling <a href="https://developer.android.com/reference/android/content/Intent.html#ACTION_PACKAGE_NEEDS_VERIFICATION">PACKAGE_NEEDS_VERIFICATION</a> intent and the storage manager app handling <a href="https://developer.android.com/reference/android/os/storage/StorageManager.html#ACTION_MANAGE_STORAGE">ACTION_MANAGE_STORAGE</a> intent.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-5] MUST have an activity that handles the <a href="http://developer.android.com/reference/android/provider/Settings.html#ACTION_MANAGE_UNKNOWN_APP_SOURCES"><code>android.settings.MANAGE_UNKNOWN_APP_SOURCES</code></a> intent.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-6] MUST NOT install application packages from unknown sources, unless the app that <a href="https://developer.android.com/reference/android/content/Intent.html#ACTION_INSTALL_PACKAGE">requests the installation</a> meets all the following requirements:
+ </p>
+ <ul>
+ <li>It MUST declare the <a href="http://developer.android.com/reference/android/Manifest.permission.html#REQUEST_INSTALL_PACKAGES"><code>REQUEST_INSTALL_PACKAGES</code></a> permission or have the <code>android:targetSdkVersion</code> set at 24 or lower.
+ </li>
+ <li>It MUST have been granted permission by the user to install apps from unknown sources.
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ SHOULD provide a user affordance to grant/revoke the permission to install apps from unknown sources per application, but MAY choose to implement this as a no-op and return <code>RESULT_CANCELED</code> for <a href="http://developer.android.com/reference/android/app/Activity.html#startActivityForResult%28android.content.Intent,int%29"><code>startActivityForResult()</code></a>, if the device implementation does not want to allow users to have this choice. However, even in such cases, they SHOULD indicate to the user why there is no such choice presented.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-7] MUST display a warning dialog with the warning string that is provided through the system API <code>PackageManager.setHarmfulAppWarning</code> to the user before launching an activity in an application that has been marked by the same system API <code>PackageManager.setHarmfulAppWarning</code> as potentially harmful.
+ </p>
+ </li>
+ <li>SHOULD provide a user affordance to choose to uninstall or launch an application on the warning dialog.
</li>
</ul>
- <p>
- Device implementations MUST NOT install application packages from unknown sources, unless the app that <a href="https://developer.android.com/reference/android/content/Intent.html#ACTION_INSTALL_PACKAGE">requests the installation</a> meets all the following requirements:
- </p>
- <ul>
- <li>It MUST declare the <a href="http://developer.android.com/reference/android/Manifest.permission.html#REQUEST_INSTALL_PACKAGES"><code>REQUEST_INSTALL_PACKAGES</code></a> permission or have the <code>android:targetSdkVersion</code> set at 24 or lower.
- </li>
- <li>It MUST have been granted permission by the user to install apps from unknown sources.
- </li>
- </ul>
- <p>
- Device implementations MUST have an activity that handles the <a href="http://developer.android.com/reference/android/provider/Settings.html#ACTION_MANAGE_UNKNOWN_APP_SOURCES"><code>android.settings.MANAGE_UNKNOWN_APP_SOURCES</code></a> intent. They SHOULD provide a user affordance to grant/revoke the permission to install apps from unknown sources per application, but MAY choose to implement this as a no-op and return <code>RESULT_CANCELED</code> for <a href="http://developer.android.com/reference/android/app/Activity.html#startActivityForResult%28android.content.Intent,%20int%29"><code>startActivityForResult()</code></a>, if the device implementation does not want to allow users to have this choice. However even in such cases, they SHOULD indicate to the user why there is no such choice presented.
- </p>
<h2 id="5_multimedia_compatibility">
5. Multimedia Compatibility
</h2>
@@ -3854,7 +3775,7 @@
Device implementations:
</p>
<ul>
- <li>SHOULD aim for minimum codec latency, in others words, they
+ <li>SHOULD aim for minimum codec latency, in other words, they:
<ul>
<li>SHOULD NOT consume and store input buffers and return input buffers only once processed.
</li>
@@ -3894,7 +3815,7 @@
See more details in <a href="#5_1_3_audio_codecs_details">5.1.3. Audio Codecs Details</a>.
</p>
<p>
- If device implementations declare support for the <code>android.hardware.audio.output</code> feature, they:
+ If device implementations declare support for the <code>android.hardware.audio.output</code> feature, they must support decoding the following audio formats:
</p>
<ul>
<li>[C-1-1] MPEG-4 AAC Profile (AAC LC)
@@ -3905,6 +3826,8 @@
</li>
<li>[C-1-4] AAC ELD (enhanced low delay AAC)
</li>
+ <li>[C-1-11] xHE-AAC (ISO/IEC 23003-3 Extended HE AAC Profile, which includes the USAC Baseline Profile, and ISO/IEC 23003-4 Dynamic Range Control Profile)
+ </li>
<li>[C-1-5] FLAC
</li>
<li>[C-1-6] MP3
@@ -3924,7 +3847,30 @@
<ul>
<li>[C-2-1] Decoding MUST be performed without downmixing (e.g. a 5.0 AAC stream must be decoded to five channels of PCM, a 5.1 AAC stream must be decoded to six channels of PCM).
</li>
- <li>[C-2-2] Dynamic range metadata MUST be as defined in "Dynamic Range Control (DRC)" in ISO/IEC 14496-3, and the <code>android.media.MediaFormat</code> DRC keys to configure the dynamic range-related behaviors of the audio decoder. The AAC DRC keys were introduced in API 21,and are: KEY_AAC_DRC_ATTENUATION_FACTOR, KEY_AAC_DRC_BOOST_FACTOR, KEY_AAC_DRC_HEAVY_COMPRESSION, KEY_AAC_DRC_TARGET_REFERENCE_LEVEL and KEY_AAC_ENCODED_TARGET_LEVEL
+ <li>[C-2-2] Dynamic range metadata MUST be as defined in "Dynamic Range Control (DRC)" in ISO/IEC 14496-3, and the <code>android.media.MediaFormat</code> DRC keys to configure the dynamic range-related behaviors of the audio decoder. The AAC DRC keys were introduced in API 21,and are: <code>KEY_AAC_DRC_ATTENUATION_FACTOR</code>, <code>KEY_AAC_DRC_BOOST_FACTOR</code>, <code>KEY_AAC_DRC_HEAVY_COMPRESSION</code>, <code>KEY_AAC_DRC_TARGET_REFERENCE_LEVEL</code> and <code>KEY_AAC_ENCODED_TARGET_LEVEL</code>.
+ </li>
+ </ul>
+ <p>
+ When decoding USAC audio, MPEG-D (ISO/IEC 23003-4):
+ </p>
+ <ul>
+ <li>[C-3-1] Loudness and DRC metadata MUST be interpreted and applied according to MPEG-D DRC Dynamic Range Control Profile Level 1.
+ </li>
+ <li>[C-3-2] The decoder MUST behave according to the configuration set with the following <code>android.media.MediaFormat</code> keys: <code>KEY_AAC_DRC_TARGET_REFERENCE_LEVEL</code> and <code>KEY_AAC_DRC_EFFECT_TYPE</code>.
+ </li>
+ </ul>
+ <p>
+ MPEG-4 AAC, HE AAC, and HE AACv2 profile decoders:
+ </p>
+ <ul>
+ <li>MAY support loudness and dynamic range control using ISO/IEC 23003-4 Dynamic Range Control Profile.
+ </li>
+ </ul>
+ <p>
+ If ISO/IEC 23003-4 is supported and if both ISO/IEC 23003-4 and ISO/IEC 14496-3 metadata are present in a decoded bitstream, then:
+ </p>
+ <ul>
+ <li>ISO/IEC 23003-4 metadata SHALL take precedence.
</li>
</ul>
<h4 id="5_1_3_audio_codecs_details">
@@ -3944,7 +3890,7 @@
</tr>
<tr>
<td>
- MPEG-4 AAC Profile<br />
+ MPEG-4 AAC Profile<br>
(AAC LC)
</td>
<td>
@@ -3974,7 +3920,7 @@
</tr>
<tr>
<td>
- MPEG-4 HE AACv2<br />
+ MPEG-4 HE AACv2<br>
Profile (enhanced AAC+)
</td>
<td>
@@ -3993,6 +3939,22 @@
</tr>
<tr>
<td>
+ USAC
+ </td>
+ <td>
+ Support for mono/stereo content with standard sampling rates from 7.35 to 48 kHz.
+ </td>
+ <td>
+ <ul>
+ <li>MPEG-4 (.mp4, .m4a)
+ </li>
+ <li>LATM/LOAS (.loas, .xhe)
+ </li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>
AMR-NB
</td>
<td>
@@ -4112,7 +4074,7 @@
See more details in <a href="#5_1_6_image_codecs_details">5.1.6. Image Codecs Details</a>.
</p>
<p>
- Device impelementations MUST support encoding the following image decoding:
+ Device implementations MUST support decoding the following image encoding:
</p>
<ul>
<li>[C-0-1] JPEG
@@ -4127,6 +4089,8 @@
</li>
<li>[C-0-6] Raw
</li>
+ <li>[C-0-7] HEIF (HEIC)
+ </li>
</ul>
<h4 id="5_1_6_image_codecs_details">
5.1.6. Image Codecs Details
@@ -4199,6 +4163,17 @@
ARW (.arw), CR2 (.cr2), DNG (.dng), NEF (.nef), NRW (.nrw), ORF (.orf), PEF (.pef), RAF (.raf), RW2 (.rw2), SRW (.srw)
</td>
</tr>
+ <tr>
+ <td>
+ HEIF
+ </td>
+ <td>
+ Image, Image collection, Image sequence
+ </td>
+ <td>
+ HEIF (.heif), HEIC (.heic)
+ </td>
+ </tr>
</table>
<h4 id="5_1_7_video_codecs">
5.1.7. Video Codecs
@@ -4233,7 +4208,7 @@
If device implementations advertise intra refresh support through <code>FEATURE_IntraRefresh</code> in the <a href="https://developer.android.com/reference/android/media/MediaCodecInfo.CodecCapabilities.html#FEATURE_IntraRefresh"><code>MediaCodecInfo.CodecCapabilities</code></a> class, they:
</p>
<ul>
- <li>[C-3-1]MUST support the refresh periods in the range of 10 - 60 frames and accurately operate within 20% of configured refresh period.
+ <li>[C-3-1] MUST support the refresh periods in the range of 10 - 60 frames and accurately operate within 20% of configured refresh period.
</li>
</ul>
<h4 id="5_1_8_video_codecs_list">
@@ -4248,7 +4223,7 @@
Details
</th>
<th>
- Supported File Types/<br />
+ Supported File Types/<br>
Container Formats
</th>
</tr>
@@ -4660,9 +4635,9 @@
If the height that is reported by the <code>Display.getSupportedModes()</code> method is equal or greater than the video resolution, device implementations:
</p>
<ul>
- <li>[C-2-1] MUST support the HD 720p video encoding profiles in the following table.
+ <li>[C-2-1] MUST support the HD 720p video decoding profiles in the following table.
</li>
- <li>[C-2-2] MUST support the HD 1080p video encoding profiles in the following table.
+ <li>[C-2-2] MUST support the HD 1080p video decoding profiles in the following table.
</li>
</ul>
<table>
@@ -4941,7 +4916,7 @@
If device implementations support VP9 codec and a hardware decoder:
</p>
<ul>
- <li>[C-2-2] MUST support the HD decoding profiles as indicated in the following table.
+ <li>[C-2-1] MUST support the HD decoding profiles as indicated in the following table.
</li>
</ul>
<p>
@@ -5048,19 +5023,17 @@
<p>
[C-1-1] MUST allow capture of raw audio content with the following characteristics:
</p>
- </li>
- <li>
- <p>
- <strong>Format</strong>: Linear PCM, 16-bit
- </p>
- </li>
- <li>
- <strong>Sampling rates</strong>: 8000, 11025, 16000, 44100 Hz
- </li>
- <li>
- <p>
- <strong>Channels</strong>: Mono
- </p>
+ <ul>
+ <li>
+ <strong>Format</strong>: Linear PCM, 16-bit
+ </li>
+ <li>
+ <strong>Sampling rates</strong>: 8000, 11025, 16000, 44100 Hz
+ </li>
+ <li>
+ <strong>Channels</strong>: Mono
+ </li>
+ </ul>
</li>
<li>
<p>
@@ -5073,17 +5046,17 @@
<p>
SHOULD allow AM radio and DVD quality capture of raw audio content, which means the following characteristics:
</p>
- </li>
- <li>
- <p>
- <strong>Format</strong>: Linear PCM, 16-bit
- </p>
- </li>
- <li>
- <strong>Sampling rates</strong>: 22050, 48000 Hz
- </li>
- <li>
- <strong>Channels</strong>: Stereo
+ <ul>
+ <li>
+ <strong>Format</strong>: Linear PCM, 16-bit
+ </li>
+ <li>
+ <strong>Sampling rates</strong>: 22050, 48000 Hz
+ </li>
+ <li>
+ <strong>Channels</strong>: Stereo
+ </li>
+ </ul>
</li>
</ul>
<p>
@@ -5118,12 +5091,12 @@
</li>
</ul>
<p>
- If device impelementations declare <code>android.hardware.microphone</code> and noise suppression (reduction) technologies tuned for speech recognition, they:
+ If device implementations declare <code>android.hardware.microphone</code> and noise suppression (reduction) technologies tuned for speech recognition, they:
</p>
<ul>
- <li>[C-2-1] MUST allow this audio affect to be controllable with the <code>android.media.audiofx.NoiseSuppressor</code> API.
+ <li>[C-2-1] MUST allow this audio effect to be controllable with the <code>android.media.audiofx.NoiseSuppressor</code> API.
</li>
- <li>[C-2-2] MUST uniquely identfiy each noise suppression technology implementation via the <code>AudioEffect.Descriptor.uuid</code> field.
+ <li>[C-2-2] MUST uniquely identify each noise suppression technology implementation via the <code>AudioEffect.Descriptor.uuid</code> field.
</li>
</ul>
<h4 id="5_4_3_capture_for_rerouting_of_playback">
@@ -5172,13 +5145,19 @@
</p>
<ul>
<li>
- <strong>Format</strong>: Linear PCM, 16-bit
+ <strong>Format</strong>: Linear PCM, 16-bit, 8-bit, float
</li>
<li>
- <strong>Sampling rates</strong>: 8000, 11025, 16000, 22050, 32000, 44100
+ <strong>Channels</strong>: Mono, Stereo, valid multichannel configurations with up to 8 channels
</li>
<li>
- <strong>Channels</strong>: Mono, Stereo
+ <strong>Sampling rates (in Hz)</strong>:
+ <ul>
+ <li>8000, 11025, 16000, 22050, 32000, 44100, 48000 at the channel configurations listed above
+ </li>
+ <li>96000 in mono and stereo
+ </li>
+ </ul>
</li>
</ul>
</li>
@@ -5207,6 +5186,8 @@
</li>
<li>[C-1-2] MUST support the visualizer API implementation, controllable through the <code>Visualizer</code> class.
</li>
+ <li>[C-1-3] MUST support the <code>EFFECT_TYPE_DYNAMICS_PROCESSING</code> implementation controllable through the AudioEffect subclass <a href="https://developer.android.com/reference/android/media/audiofx/DynamicsProcessing"><code>DynamicsProcessing</code></a>.
+ </li>
<li>SHOULD support the <code>EFFECT_TYPE_BASS_BOOST</code>, <code>EFFECT_TYPE_ENV_REVERB</code>, <code>EFFECT_TYPE_PRESET_REVERB</code>, and <code>EFFECT_TYPE_VIRTUALIZER</code> implementations controllable through the <code>AudioEffect</code> sub-classes <code>BassBoost</code>, <code>EnvironmentalReverb</code>, <code>PresetReverb</code>, and <code>Virtualizer</code>.
</li>
</ul>
@@ -5266,29 +5247,36 @@
<li>
<strong>AAudio native audio API</strong>. The set of <a href="https://developer.android.com/ndk/guides/audio/aaudio/aaudio.html">AAudio</a> APIs within <a href="https://developer.android.com/ndk/index.html">Android NDK</a>.
</li>
+ <li>
+ <strong>Timestamp</strong>. A pair consisting of a relative frame position within a stream and the estimated time when that frame enters or leaves the audio processing pipeline on the associated endpoint. See also <a href="https://developer.android.com/reference/android/media/AudioTimestamp">AudioTimestamp</a>.
+ </li>
</ul>
<p>
If device implementations declare <code>android.hardware.audio.output</code> they are STRONGLY RECOMMENDED to meet or exceed the following requirements:
</p>
<ul>
- <li>[SR] Cold output latency of 100 milliseconds or less
+ <li>[C-SR] Cold output latency of 100 milliseconds or less
</li>
- <li>[SR] Continuous output latency of 45 milliseconds or less
+ <li>[C-SR] Continuous output latency of 45 milliseconds or less
</li>
- <li>[SR] Minimize the cold output jitter
+ <li>[C-SR] Minimize the cold output jitter
+ </li>
+ <li>[C-SR] The output timestamp returned by <a href="https://developer.android.com/reference/android/media/AudioTrack.html#getTimestamp(android.media.AudioTimestamp)">AudioTrack.getTimestamp</a> and <code>AAudioStream_getTimestamp</code> is accurate to +/- 1 ms.
</li>
</ul>
<p>
- If device implementations meet the above requirements after any initial calibration when using the OpenSL ES PCM buffer queue API, for continuous output latency and cold output latency over at least one supported audio output device, they are:
+ If device implementations meet the above requirements, after any initial calibration, when using both the OpenSL ES PCM buffer queue and AAudio native audio APIs, for continuous output latency and cold output latency over at least one supported audio output device, they are:
</p>
<ul>
- <li>[SR] STRONGLY RECOMMENDED to report low latency audio by declaring <code>android.hardware.audio.low_latency</code> feature flag.
+ <li>[C-SR] STRONGLY RECOMMENDED to report low-latency audio by declaring <code>android.hardware.audio.low_latency</code> feature flag.
</li>
- <li>[SR] STRONGLY RECOMMENDED to also meet the requirements for low-latency audio via the AAudio API.
+ <li>[C-SR] STRONGLY RECOMMENDED to meet the requirements for low-latency audio via the AAudio API.
+ </li>
+ <li>[C-SR] STRONGLY RECOMMENDED to ensure that for streams that return <a href="https://developer.android.com/ndk/guides/audio/aaudio/aaudio#performance-mode"><code>AAUDIO_PERFORMANCE_MODE_LOW_LATENCY</code></a> from <a href="https://developer.android.com/ndk/reference/group/audio#aaudiostream_getperformancemode"><code>AAudioStream_getPerformanceMode()</code></a>, the value returned by <a href="https://developer.android.com/ndk/reference/group/audio#aaudiostream_getframesperburst"><code>AAudioStream_getFramesPerBurst()</code></a> is less than or equal to the value returned by <a href="https://developer.android.com/reference/android/media/AudioManager.html#getProperty%28java.lang.String%29"><code>android.media.AudioManager.getProperty(String)</code></a> for property key <a href="https://developer.android.com/reference/android/media/AudioManager.html#PROPERTY_OUTPUT_FRAMES_PER_BUFFER"><code>AudioManager.PROPERTY_OUTPUT_FRAMES_PER_BUFFER</code></a>.
</li>
</ul>
<p>
- If device implementations do not meet the requirements for low-latency audio via the OpenSL ES PCM buffer queue API, they:
+ If device implementations do not meet the requirements for low-latency audio via both the OpenSL ES PCM buffer queue and AAudio native audio APIs, they:
</p>
<ul>
<li>[C-1-1] MUST NOT report support for low-latency audio.
@@ -5298,13 +5286,15 @@
If device implementations include <code>android.hardware.microphone</code>, they are STRONGLY RECOMMENDED to meet these input audio requirements:
</p>
<ul>
- <li>[SR] Cold input latency of 100 milliseconds or less
+ <li>[C-SR] Cold input latency of 100 milliseconds or less.
</li>
- <li>[SR] Continuous input latency of 30 milliseconds or less
+ <li>[C-SR] Continuous input latency of 30 milliseconds or less.
</li>
- <li>[SR] Continuous round-trip latency of 50 milliseconds or less
+ <li>[C-SR] Continuous round-trip latency of 50 milliseconds or less.
</li>
- <li>[SR] Minimize the cold input jitter
+ <li>[C-SR] Minimize the cold input jitter.
+ </li>
+ <li>[C-SR] Limit the error in input timestamps, as returned by <a href="https://developer.android.com/reference/android/media/AudioRecord.html#getTimestamp(android.media.AudioTimestamp,%20int)">AudioRecord.getTimestamp</a> or <code>AAudioStream_getTimestamp</code>, to +/- 1 ms.
</li>
</ul>
<h3 id="5_7_network_protocols">
@@ -5324,7 +5314,7 @@
</li>
<li>
<p>
- [C-1-2] MUST support the media segment formats shown in the Media Segmant Formats table below over <a href="http://tools.ietf.org/html/draft-pantos-http-live-streaming-07">HTTP Live Streaming draft protocol, Version 7</a>.
+ [C-1-2] MUST support the media segment formats shown in the Media Segment Formats table below over <a href="http://tools.ietf.org/html/draft-pantos-http-live-streaming-07">HTTP Live Streaming draft protocol, Version 7</a>.
</p>
</li>
<li>
@@ -5334,7 +5324,7 @@
</li>
</ul>
<p>
- Media Segment Formats
+ <strong>Media Segment Formats</strong>
</p>
<table>
<tr>
@@ -5364,7 +5354,7 @@
</li>
<li class="table_list">MPEG-2
</li>
- </ul>See <a href="#5_1_3_video_codecs">section 5.1.3</a> for details on H264 AVC, MPEG2-4 SP,<br />
+ </ul>See <a href="#5_1_3_video_codecs">section 5.1.3</a> for details on H264 AVC, MPEG2-4 SP,<br>
and MPEG-2.
<p>
Audio codecs:
@@ -5397,7 +5387,7 @@
</tr>
</table>
<p>
- RTSP (RTP, SDP)
+ <strong>RTSP (RTP, SDP)</strong>
</p>
<table>
<tr>
@@ -5438,8 +5428,8 @@
H263-1998
</td>
<td>
- <a href="https://tools.ietf.org/html/rfc3551">RFC 3551</a><br />
- <a href="https://tools.ietf.org/html/rfc4629">RFC 4629</a><br />
+ <a href="https://tools.ietf.org/html/rfc3551">RFC 3551</a><br>
+ <a href="https://tools.ietf.org/html/rfc4629">RFC 4629</a><br>
<a href="https://tools.ietf.org/html/rfc2190">RFC 2190</a>
</td>
<td>
@@ -5534,7 +5524,7 @@
If device implementations declare support for <code>Display.FLAG_SECURE</code> and support wired external display, they:
</p>
<ul>
- <li>[C-3-1] MUST support HDCP 1.2 or higher for all wired external displays.
+ <li>[C-3-1] MUST support HDCP 1.2 or higher for all external displays connected via a user-accessible wired port.
</li>
</ul>
<h3 id="5_9_musical_instrument_digital_interface_(midi)">
@@ -5578,7 +5568,7 @@
</li>
<li>[C-1-4] MUST report support for feature <code>android.software.midi</code>.
</li>
- <li>[C-1-5] MUST meet latencies and USB audio requirements using the <a href="https://developer.android.com/ndk/guides/audio/opensl-for-android.html">OpenSL ES</a> PCM buffer queue API.
+ <li>[C-1-5] MUST meet latencies and USB audio requirements using both the <a href="https://developer.android.com/ndk/guides/audio/opensl-for-android.html">OpenSL ES</a> PCM buffer queue and <a href="https://developer.android.com/ndk/guides/audio/aaudio/aaudio.html">AAudio native audio</a> APIs.
</li>
<li>[SR] Are STRONGLY RECOMMENDED to provide a consistent level of CPU performance while audio is active and CPU load is varying. This should be tested using <a href="https://github.com/googlesamples/android-audio-high-performance/tree/master/SimpleSynth">SimpleSynth</a> commit <a href="https://github.com/googlesamples/android-audio-high-performance/commit/1bd6391f8ba9512f9f8798e979bc55b899f856d1">1bd6391</a>. The SimpleSynth app needs to be run with below parameters and achieve zero underruns after 10 minutes:
<ul>
@@ -5624,6 +5614,8 @@
</li>
<li>SHOULD minimize touch latency variability under load (jitter).
</li>
+ <li>SHOULD have a latency from touch input to audio output of less than or equal to 40 ms.
+ </li>
</ul>
<p>
If device implementations meet all of the above requirements, they:
@@ -5633,13 +5625,6 @@
</li>
</ul>
<p>
- If device implementations meet the requirements via the OpenSL ES PCM buffer queue API, they:
- </p>
- <ul>
- <li>[SR] STRONGLY RECOMMENDED to also meet the same requirements via the <a href="https://developer.android.com/ndk/guides/audio/aaudio/aaudio.html">AAudio</a> API.
- </li>
- </ul>
- <p>
If device implementations include a 4 conductor 3.5mm audio jack, they:
</p>
<ul>
@@ -5665,7 +5650,7 @@
If device implementations include an HDMI port, they:
</p>
<ul>
- <li>[C-4-1] MUST support output in stereo and eight channels at 20-bit or 24-bit depth and 192 kHz without bit-depth loss or resampling.
+ <li>[C-4-1] MUST support output in stereo and eight channels at 20-bit or 24-bit depth and 192 kHz without bit-depth loss or resampling, in at least one configuration.
</li>
</ul>
<h3 id="5_11_capture_for_unprocessed">
@@ -5752,9 +5737,63 @@
<a href="http://developer.android.com/tools/help/adb.html"><strong>Android Debug Bridge (adb)</strong></a>
</p>
<ul>
- <li>[C-0-2] MUST support all adb functions as documented in the Android SDK including <a href="https://source.android.com/devices/input/diagnostics.html">dumpsys</a>.
+ <li>[C-0-2] MUST support adb as documented in the Android SDK and the shell commands provided in the AOSP, which can be used by app developers, including <a href="https://source.android.com/devices/input/diagnostics.html"><code>dumpsys</code></a> and <code>cmd stats</code>.
</li>
- <li>[C-0-3] MUST NOT alter the format or the contents of device system events (batterystats , diskstats, fingerprint, graphicsstats, netstats, notification, procstats) logged via dumpsys.
+ <li>[C-0-3] MUST NOT alter the format or the contents of device system events (batterystats , diskstats, fingerprint, graphicsstats, netstats, notification, procstats) logged via the dumpsys command.
+ </li>
+ <li>[C-0-10] MUST record, without omission, and make the following events accessible and available to the <code>cmd stats</code> shell command and the <code>StatsManager</code> System API class.
+ <ul>
+ <li>ActivityForegroundStateChanged
+ </li>
+ <li>AnomalyDetected
+ </li>
+ <li>AppBreadcrumbReported
+ </li>
+ <li>AppCrashOccurred
+ </li>
+ <li>AppStartOccurred
+ </li>
+ <li>BatteryLevelChanged
+ </li>
+ <li>BatterySaverModeStateChanged
+ </li>
+ <li>BleScanResultReceived
+ </li>
+ <li>BleScanStateChanged
+ </li>
+ <li>ChargingStateChanged
+ </li>
+ <li>DeviceIdleModeStateChanged
+ </li>
+ <li>ForegroundServiceStateChanged
+ </li>
+ <li>GpsScanStateChanged
+ </li>
+ <li>JobStateChanged
+ </li>
+ <li>PluggedStateChanged
+ </li>
+ <li>ScheduledJobStateChanged
+ </li>
+ <li>ScreenStateChanged
+ </li>
+ <li>SyncStateChanged
+ </li>
+ <li>SystemElapsedRealtime
+ </li>
+ <li>UidProcessStateChanged
+ </li>
+ <li>WakelockStateChanged
+ </li>
+ <li>WakeupAlarmOccurred
+ </li>
+ <li>WifiLockStateChanged
+ </li>
+ <li>WifiMulticastLockStateChanged
+ </li>
+ <li>WifiScanStateChanged
+ </li>
+ </ul>
</li>
<li>[C-0-4] MUST have the device-side adb daemon be inactive by default and there MUST be a user-accessible mechanism to turn on the Android Debug Bridge.
</li>
@@ -5792,11 +5831,20 @@
<li>
<a href="http://developer.android.com/tools/help/systrace.html"><strong>SysTrace</strong></a>
<ul>
- <li>[C-0-9] MUST support systrace tool as documented in the Android SDK. Systrace must be inactive by default and there MUST be a user-accessible mechanism to turn on Systrace.
+ <li>[C-0-9] MUST support the systrace tool as documented in the Android SDK. Systrace must be inactive by default and there MUST be a user-accessible mechanism to turn on Systrace.
</li>
</ul>
</li>
</ul>
+ <p>
+ If device implementations report the support of Vulkan 1.0 or higher via the <code>android.hardware.vulkan.version</code> feature flags, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST provide an affordance for the app developer to enable/disable GPU debug layers.
+ </li>
+ <li>[C-1-2] MUST, when the GPU debug layers are enabled, enumerate layers in libraries provided by external tools (i.e. not part of the platform or application package) found in debuggable applications' base directory to support <a href="https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkEnumerateInstanceLayerProperties.html">vkEnumerateInstanceLayerProperties()</a> and <a href="https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkCreateInstance.html">vkCreateInstance()</a> API methods.
+ </li>
+ </ul>
<h3 id="6_2_developer_options">
6.2. Developer Options
</h3>
@@ -5809,7 +5857,11 @@
<ul>
<li>[C-0-1] MUST honor the <a href="http://developer.android.com/reference/android/provider/Settings.html#ACTION_APPLICATION_DEVELOPMENT_SETTINGS">android.settings.APPLICATION_DEVELOPMENT_SETTINGS</a> intent to show application development-related settings. The upstream Android implementation hides the Developer Options menu by default and enables users to launch Developer Options after pressing seven (7) times on the <strong>Settings</strong> > <strong>About Device</strong> > <strong>Build Number</strong> menu item.
</li>
- <li>[C-0-2] MUST hide Developer Options by default and MUST provide a mechanism to enable Developer Options without the need for any special whitelisting.
+ <li>[C-0-2] MUST hide Developer Options by default.
+ </li>
+ <li>[C-0-3] MUST provide a clear mechanism that does not give preferential treatment to one third-party app as opposed to another to enable Developer Options. MUST provide a public visible document or website that describes how to enable Developer Options. This document or website MUST be linkable from the Android SDK documents.
+ </li>
+ <li>SHOULD have an ongoing visual notification to the user when Developer Options is enabled and the safety of the user is of concern.
</li>
<li>MAY temporarily limit access to the Developer Options menu, by visually hiding or disabling the menu, to prevent distraction for scenarios where the safety of the user is of concern.
</li>
@@ -5870,16 +5922,19 @@
<h4 id="7_1_1_screen_configuration">
7.1.1. Screen Configuration
</h4>
- <h5 id="7_1_1_1_screen_size">
- 7.1.1.1. Screen Size
+ <h5 id="7_1_1_1_screen_size_and_shape">
+ 7.1.1.1. Screen Size and Shape
</h5>
<p>
The Android UI framework supports a variety of different logical screen layout sizes, and allows applications to query the current configuration's screen layout size via <code>Configuration.screenLayout</code> with the <code>SCREENLAYOUT_SIZE_MASK</code> and <code>Configuration.smallestScreenWidthDp</code>.
</p>
+ <p>
+ Device implementations:
+ </p>
<ul>
<li>
<p>
- [C-0-1] Device implementations MUST report the correct layout size for the <code>Configuration.screenLayout</code> as defined in the Android SDK documentation. Specifically, device implementations MUST report the correct logical density-independent pixel (dp) screen dimensions as below:
+ [C-0-1] MUST report the correct layout size for the <code>Configuration.screenLayout</code> as defined in the Android SDK documentation. Specifically, device implementations MUST report the correct logical density-independent pixel (dp) screen dimensions as below:
</p>
<ul>
<li>Devices with the <code>Configuration.uiMode</code> set as any value other than UI_MODE_TYPE_WATCH, and reporting a <code>small</code> size for the <code>Configuration.screenLayout</code>, MUST have at least 426 dp x 320 dp.
@@ -5894,9 +5949,23 @@
</li>
<li>
<p>
- [C-0-2] Device implementations MUST correctly honor applications' stated support for screen sizes through the <a href="https://developer.android.com/guide/topics/manifest/supports-screens-element.html"><<code>supports-screens</code>></a> attribute in the AndroidManifest.xml, as described in the Android SDK documentation.
+ [C-0-2] MUST correctly honor applications' stated support for screen sizes through the <a href="https://developer.android.com/guide/topics/manifest/supports-screens-element.html"><<code>supports-screens</code>></a> attribute in the AndroidManifest.xml, as described in the Android SDK documentation.
</p>
</li>
+ <li>
+ <p>
+ MAY have a display with rounded corners.
+ </p>
+ </li>
+ </ul>
+ <p>
+ If device implementations support <code>UI_MODE_TYPE_NORMAL</code> and include a display with rounded corners, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST ensure that the radius of the rounded corners is less than or equal to 32 dp.
+ </li>
+ <li>SHOULD include user affordance to switch to the display mode with the rectangular corners.
+ </li>
</ul>
<h5 id="7_1_1_2_screen_aspect_ratio">
7.1.1.2. Screen Aspect Ratio
@@ -5914,7 +5983,7 @@
</li>
<li>The app declares it is resizeable via the <a href="https://developer.android.com/guide/topics/ui/multi-window.html#configuring">android:resizeableActivity</a> attribute.
</li>
- <li>The app is targeting API level 26 or higher and does not declare a <a href="https://developer.android.com/reference/android/R.attr.html#maxAspectRatio"><code>android:MaxAspectRatio</code></a> that would restrict the allowed aspect ratio.
+ <li>The app is targeting API level 24 or higher and does not declare a <a href="https://developer.android.com/reference/android/R.attr.html#maxAspectRatio"><code>android:MaxAspectRatio</code></a> that would restrict the allowed aspect ratio.
</li>
</ul>
</li>
@@ -6054,11 +6123,11 @@
If device implementations include a screen or video output, they:
</p>
<ul>
- <li>[C-1-1] MUST support both OpenGL ES 1.0 and 2.0, as embodied and detailed in the <a href="https://developer.android.com/guide/topics/graphics/opengl.html">Android SDK documentation</a>.
+ <li>[C-1-1] MUST support both OpenGL ES 1.1 and 2.0, as embodied and detailed in the <a href="https://developer.android.com/guide/topics/graphics/opengl.html">Android SDK documentation</a>.
</li>
- <li>[SR] are STRONGLY RECOMMENDED to support OpenGL ES 3.0.
+ <li>[SR] are STRONGLY RECOMMENDED to support OpenGL ES 3.1.
</li>
- <li>SHOULD support OpenGL ES 3.1 or 3.2.
+ <li>SHOULD support OpenGL ES 3.2.
</li>
</ul>
<p>
@@ -6078,7 +6147,7 @@
If device implementations declare support for OpenGL ES 3.0, 3.1, or 3.2, they:
</p>
<ul>
- <li>[C-3-1] MUST export the corresponding function symbols for these version in addition to the OpenGL ES 2.0 function symbols in the libGLESv2.so library.
+ <li>[C-3-1] MUST export the corresponding function symbols for these versions in addition to the OpenGL ES 2.0 function symbols in the libGLESv2.so library.
</li>
</ul>
<p>
@@ -6109,26 +6178,26 @@
Android includes support for <a href="https://www.khronos.org/registry/vulkan/specs/1.0-wsi&lowbarextensions/xhtml/vkspec.html">Vulkan</a> , a low-overhead, cross-platform API for high-performance 3D graphics.
</p>
<p>
- If device implementations support OpenGL ES 3.0 or 3.1, they:
+ If device implementations support OpenGL ES 3.1, they:
</p>
<ul>
- <li>[SR] Are STRONGLY RECOMMENDED to include support for Vulkan 1.0 .
+ <li>[SR] Are STRONGLY RECOMMENDED to include support for Vulkan 1.1.
</li>
</ul>
<p>
If device implementations include a screen or video output, they:
</p>
<ul>
- <li>SHOULD include support for Vulkan 1.0.
+ <li>SHOULD include support for Vulkan 1.1.
</li>
</ul>
<p>
- Device implementations, if including support for Vulkan 1.0:
+ If device implementations include support for Vulkan 1.0, they:
</p>
<ul>
<li>[C-1-1] MUST report the correct integer value with the <code>android.hardware.vulkan.level</code> and <code>android.hardware.vulkan.version</code> feature flags.
</li>
- <li>[C-1-2] MUST enumarate, at least one <code>VkPhysicalDevice</code> for the Vulkan native API <a href="https://www.khronos.org/registry/vulkan/specs/1.0/man/html/vkEnumeratePhysicalDevices.html"><code>vkEnumeratePhysicalDevices()</code></a> .
+ <li>[C-1-2] MUST enumerate, at least one <code>VkPhysicalDevice</code> for the Vulkan native API <a href="https://www.khronos.org/registry/vulkan/specs/1.0/man/html/vkEnumeratePhysicalDevices.html"><code>vkEnumeratePhysicalDevices()</code></a> .
</li>
<li>[C-1-3] MUST fully implement the Vulkan 1.0 APIs for each enumerated <code>VkPhysicalDevice</code>.
</li>
@@ -6138,14 +6207,25 @@
</li>
<li>[C-1-6] MUST report all extension strings that they do support via the Vulkan native APIs , and conversely MUST NOT report extension strings that they do not correctly support.
</li>
+ <li>[C-1-7] MUST support the VK_KHR_surface, VK_KHR_android_surface, VK_KHR_swapchain, and VK_KHR_incremental_present extensions.
+ </li>
</ul>
<p>
- Device implementations, if not including support for Vulkan 1.0:
+ If device implementations do not include support for Vulkan 1.0, they:
</p>
<ul>
<li>[C-2-1] MUST NOT declare any of the Vulkan feature flags (e.g. <code>android.hardware.vulkan.level</code>, <code>android.hardware.vulkan.version</code>).
</li>
- <li>[C-2-2] MUST NOT enumarate any <code>VkPhysicalDevice</code> for the Vulkan native API <code>vkEnumeratePhysicalDevices()</code>.
+ <li>[C-2-2] MUST NOT enumerate any <code>VkPhysicalDevice</code> for the Vulkan native API <code>vkEnumeratePhysicalDevices()</code>.
+ </li>
+ </ul>
+ <p>
+ If device implementations include support for Vulkan 1.1, they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST expose support for the <code>SYNC_FD</code> external semaphore and handle types.
+ </li>
+ <li>[SR] Are STRONGLY RECOMMENDED to support the <code>VK_ANDROID_external_memory_android_hardware_buffer</code> extension.
</li>
</ul>
<h5 id="7_1_4_3_renderscript">
@@ -6173,6 +6253,9 @@
<p>
Android includes a TextureView object that lets developers directly integrate hardware-accelerated OpenGL ES textures as rendering targets in a UI hierarchy.
</p>
+ <p>
+ Device implementations:
+ </p>
<ul>
<li>[C-0-3] MUST support the TextureView API, and MUST exhibit consistent behavior with the upstream Android implementation.
</li>
@@ -6181,18 +6264,18 @@
7.1.4.5 Wide-gamut Displays
</h5>
<p>
- If device implementations claim support for wide-gamut displays through <a href="https://developer.android.com/reference/android/view/Display.html#isWideColorGamut%28%29"><code>Display.isWideColorGamut()</code></a> , they:
+ If device implementations claim support for wide-gamut displays through <a href="https://developer.android.com/reference/android/content/res/Configuration.html#isScreenWideColorGamut%28%29"><code>Configuration.isScreenWideColorGamut()</code></a> , they:
</p>
<ul>
<li>[C-1-1] MUST have a color-calibrated display.
</li>
<li>[C-1-2] MUST have a display whose gamut covers the sRGB color gamut entirely in CIE 1931 xyY space.
</li>
- <li>[C-1-3] MUST have a display whose gamut has an area of at least 90% of NTSC 1953 in CIE 1931 xyY space.
+ <li>[C-1-3] MUST have a display whose gamut has an area of at least 90% of DCI-P3 in CIE 1931 xyY space.
</li>
- <li>[C-1-4] MUST support OpenGL ES 3.0, 3.1, or 3.2 and report it properly.
+ <li>[C-1-4] MUST support OpenGL ES 3.1 or 3.2 and report it properly.
</li>
- <li>[C-1-5] MUST advertise support for the <code>EGL_KHR_no_config_context</code>, <code>EGL_EXT_pixel_format_float</code>,<code>EGL_KHR_gl_colorspace</code>, <code>EGL_EXT_colorspace_scrgb_linear</code>, and <code>EGL_GL_colorspace_display_p3</code> extensions.
+ <li>[C-1-5] MUST advertise support for the <code>EGL_KHR_no_config_context</code>, <code>EGL_EXT_pixel_format_float</code>, <code>EGL_KHR_gl_colorspace</code>, <code>EGL_EXT_gl_colorspace_scrgb</code>, <code>EGL_EXT_gl_colorspace_scrgb_linear</code>, <code>EGL_EXT_gl_colorspace_display_p3</code>, and <code>EGL_KHR_gl_colorspace_display_p3</code> extensions.
</li>
<li>[SR] Are STRONGLY RECOMMENDED to support <code>GL_EXT_sRGB</code>.
</li>
@@ -6327,21 +6410,11 @@
</li>
</ul>
<p>
- If device implementations do not provide the Menu function, for backwards compatibility, they:
+ If device implementations do not provide the Menu function, for backwards compatibility, they: * [C-3-1] MUST make the Menu function available to applications when <code>targetSdkVersion</code> is less than 10, either by a physical button, a software key, or gestures. This Menu function should be accessible unless hidden together with other navigation functions.
</p>
- <ul>
- <li>[C-3-1] MUST make the Menu function available to applications when <code>targetSdkVersion</code> is less than 10, either by a physical button, a software key, or gestures. This Menu function should be accessible unless hidden together with other navigation functions.
- </li>
- </ul>
<p>
- If device implementations provide the <a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_ASSIST">Assist function</a>, they:
+ If device implementations provide the <a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_ASSIST">Assist function</a>, they: <em>[C-4-1] MUST make the Assist function accessible with a single action (e.g. tap, double-click or gesture) when other navigation keys are accessible.</em> [SR] STRONGLY RECOMMENDED to use long press on HOME function as this designated interaction.
</p>
- <ul>
- <li>[C-4-1] MUST make the Assist function accessible with a single action (e.g. tap, double-click or gesture) when other navigation keys are accessible.
- </li>
- <li>[SR] STRONGLY RECOMMENDED to use long press on HOME function as this designated interaction.
- </li>
- </ul>
<p>
If device implementations use a distinct portion of the screen to display the navigation keys, they:
</p>
@@ -6357,7 +6430,7 @@
7.2.4. Touchscreen Input
</h4>
<p>
- Android includes support for a variety of pointer input systems, such as touchscreens, touch pads, and fake touch input devices. <a href="http://source.android.com/devices/tech/input/touch-devices.html">Touchscreen-based device implementations</a> are associated with a display such that the user has the impression of directly manipulating items on screen. Since the user is directly touching the screen, the system does not require any additional affordances to indicate the objects being manipulated.
+ Android includes support for a variety of pointer input systems, such as touchscreens, touch pads, and fake touch input devices. <a href="https://source.android.com/devices/input/touch-devices">Touchscreen-based device implementations</a> are associated with a display such that the user has the impression of directly manipulating items on screen. Since the user is directly touching the screen, the system does not require any additional affordances to indicate the objects being manipulated.
</p>
<p>
Device implementations:
@@ -6374,7 +6447,7 @@
<ul>
<li>[C-1-1] MUST report <code>TOUCHSCREEN_FINGER</code> for the <a href="https://developer.android.com/reference/android/content/res/Configuration.html#touchscreen"><code>Configuration.touchscreen</code></a> API field.
</li>
- <li>[C-1-2] MUST report the <code>android.hardware.touchscreen</code> and <code>android.hardware.faketouch</code> feature flags
+ <li>[C-1-2] MUST report the <code>android.hardware.touchscreen</code> and <code>android.hardware.faketouch</code> feature flags.
</li>
</ul>
<p>
@@ -6514,7 +6587,7 @@
</tr>
<tr>
<td>
- <a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_DPAD_UP">D-pad up</a><sup>1</sup><br />
+ <a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_DPAD_UP">D-pad up</a><sup>1</sup><br>
<a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_DPAD_DOWN">D-pad down</a><sup>1</sup>
</td>
<td>
@@ -6526,7 +6599,7 @@
</tr>
<tr>
<td>
- <a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_DPAD_LEFT">D-pad left</a>1<br />
+ <a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_DPAD_LEFT">D-pad left</a>1<br>
<a href="http://developer.android.com/reference/android/view/KeyEvent.html#KEYCODE_DPAD_RIGHT">D-pad right</a><sup>1</sup>
</td>
<td>
@@ -6654,11 +6727,11 @@
<a href="http://developer.android.com/reference/android/view/MotionEvent.html#AXIS_Y">Left Joystick</a>
</td>
<td>
- 0x01 0x0030<br />
+ 0x01 0x0030<br>
0x01 0x0031
</td>
<td>
- AXIS_X<br />
+ AXIS_X<br>
AXIS_Y
</td>
</tr>
@@ -6667,11 +6740,11 @@
<a href="http://developer.android.com/reference/android/view/MotionEvent.html#AXIS_Z">Right Joystick</a>
</td>
<td>
- 0x01 0x0032<br />
+ 0x01 0x0032<br>
0x01 0x0035
</td>
<td>
- AXIS_Z<br />
+ AXIS_Z<br>
AXIS_RZ
</td>
</tr>
@@ -6708,9 +6781,7 @@
<ul>
<li>[C-1-1] MUST <a href="http://developer.android.com/reference/android/hardware/SensorEvent.html">report all sensor measurements</a> using the relevant International System of Units (metric) values for each sensor type as defined in the Android SDK documentation.
</li>
- <li>[C-1-2] MUST report sensor data with a maximum latency of 100 milliseconds
- </li>
- <li>2 * sample_time for the case of a sensor streamed with a minimum required latency of 5 ms + 2 * sample_time when the application processor is active. This delay does not include any filtering delays.
+ <li>[C-1-2] MUST report sensor data with a maximum latency of 100 milliseconds + 2 * sample_time for the case of a sensor streamed with a minimum required latency of 5 ms + 2 * sample_time when the application processor is active. This delay does not include any filtering delays.
</li>
<li>[C-1-3] MUST report the first sensor sample within 400 milliseconds + 2 * sample_time of the sensor being activated. It is acceptable for this sample to have an accuracy of 0.
</li>
@@ -6721,12 +6792,12 @@
</li>
<li>
<p>
- [C-1-7] For any API indicated by the Android SDK documentation to be a <a href="https://source.android.com/devices/sensors/report-modes.html#continuous">continuous sensor</a>, device implementations MUST continuously provide periodic data samples that SHOULD have a jitter below 3%, where jitter is defined as the standard deviation of the difference of the reported timestamp values between consecutive events.
+ [C-1-4] For any API indicated by the Android SDK documentation to be a <a href="https://source.android.com/devices/sensors/report-modes.html#continuous">continuous sensor</a>, device implementations MUST continuously provide periodic data samples that SHOULD have a jitter below 3%, where jitter is defined as the standard deviation of the difference of the reported timestamp values between consecutive events.
</p>
</li>
<li>
<p>
- [C-1-8] MUST ensure that the sensor event stream MUST NOT prevent the device CPU from entering a suspend state or waking up from a suspend state.
+ [C-1-5] MUST ensure that the sensor event stream MUST NOT prevent the device CPU from entering a suspend state or waking up from a suspend state.
</p>
</li>
<li>When several sensors are activated, the power consumption SHOULD NOT exceed the sum of the individual sensor’s reported power consumption.
@@ -6827,7 +6898,7 @@
</li>
</ul>
<p>
- If device impelementations include a 3-axis magnetometer, they:
+ If device implementations include a 3-axis magnetometer, they:
</p>
<ul>
<li>[C-1-1] MUST implement the <code>TYPE_MAGNETIC_FIELD</code> sensor.
@@ -6854,21 +6925,21 @@
</li>
</ul>
<p>
- If device impelementations include a 3-axis magnetometer, an accelerometer sensor and a gyroscope sensor, they:
+ If device implementations include a 3-axis magnetometer, an accelerometer sensor and a gyroscope sensor, they:
</p>
<ul>
<li>[C-2-1] MUST implement a <code>TYPE_ROTATION_VECTOR</code> composite sensor.
</li>
</ul>
<p>
- If device impelementations include a 3-axis magnetometer, an accelerometer, they:
+ If device implementations include a 3-axis magnetometer, an accelerometer, they:
</p>
<ul>
<li>MAY implement the <code>TYPE_GEOMAGNETIC_ROTATION_VECTOR</code> sensor.
</li>
</ul>
<p>
- If device impelementations include a 3-axis magnetometer, an accelerometer and <code>TYPE_GEOMAGNETIC_ROTATION_VECTOR</code> sensor, they:
+ If device implementations include a 3-axis magnetometer, an accelerometer and <code>TYPE_GEOMAGNETIC_ROTATION_VECTOR</code> sensor, they:
</p>
<ul>
<li>[C-3-1] MUST consume less than 10 mW.
@@ -6894,7 +6965,7 @@
</li>
<li>[C-1-2] MUST be able to determine the location in open-sky conditions (strong signals, negligible multipath, HDOP < 2) within 10 seconds (fast time to first fix), when connected to a 0.5 Mbps or faster data speed internet connection. This requirement is typically met by the use of some form of Assisted or Predicted GPS/GNSS technique to minimize GPS/GNSS lock-on time (Assistance data includes Reference Time, Reference Location and Satellite Ephemeris/Clock).
<ul>
- <li>[SR] After making such a location calculation, it is STRONGLY RECOMMENDED for the device to be able to determine its location, in open sky, within 10 seconds, when location requests are restarted, up to an hour after the initial location calculation, even when the subsequent request is made without a data connection, and/or after a power cycle.
+ <li>[C-1-6] After making such a location calculation, device implementations MUST determine its location, in open sky, within 5 seconds, when location requests are restarted, up to an hour after the initial location calculation, even when the subsequent request is made without a data connection, and/or after a power cycle.
</li>
</ul>
</li>
@@ -6917,7 +6988,7 @@
</li>
<li>[SR] Report AGC, and Frequency of GNSS measurement.
</li>
- <li>[SR] Report all accuracy estimates (including Bearing, Speed, and Vertical) as part of each GPS Location.
+ <li>[SR] Report all accuracy estimates (including Bearing, Speed, and Vertical) as part of each GPS/GNSS location.
</li>
<li>[SR] are STRONGLY RECOMMENDED to meet as many as possible from the additional mandatory requirements for devices reporting the year "2016" or "2017" through the Test API <code>LocationManager.getGnssYearOfHardware()</code>.
</li>
@@ -6928,9 +6999,9 @@
If device implementations include a GPS/GNSS receiver and report the capability to applications through the <code>android.hardware.location.gps</code> feature flag and the <code>LocationManager.getGnssYearOfHardware()</code> Test API reports the year "2016" or newer, they:
</p>
<ul>
- <li>[C-2-1] MUST report GPS measurements, as soon as they are found, even if a location calculated from GPS/GNSS is not yet reported.
+ <li>[C-2-1] MUST report GNSS measurements, as soon as they are found, even if a location calculated from GPS/GNSS is not yet reported.
</li>
- <li>[C-2-2] MUST report GPS pseudoranges and pseudorange rates, that, in open-sky conditions after determining the location, while stationary or moving with less than 0.2 meter per second squared of acceleration, are sufficient to calculate position within 20 meters, and speed within 0.2 meters per second, at least 95% of the time.
+ <li>[C-2-2] MUST report GNSS pseudoranges and pseudorange rates, that, in open-sky conditions after determining the location, while stationary or moving with less than 0.2 meter per second squared of acceleration, are sufficient to calculate position within 20 meters, and speed within 0.2 meters per second, at least 95% of the time.
</li>
</ul>
<p>
@@ -6943,7 +7014,16 @@
</li>
<li>[C-3-3] MUST report AGC, and Frequency of GNSS measurement.
</li>
- <li>[C-3-4] MUST report all accuracy estimates (including Bearing, Speed, and Vertical) as part of each GPS Location.
+ <li>[C-3-4] MUST report all accuracy estimates (including Bearing, Speed, and Vertical) as part of each GPS/GNSS location.
+ </li>
+ </ul>
+ <p>
+ If device implementations include a GPS/GNSS receiver and report the capability to applications through the <code>android.hardware.location.gps</code> feature flag and the <code>LocationManager.getGnssYearOfHardware()</code> Test API reports the year "2018" or newer, they:
+ </p>
+ <ul>
+ <li>[C-4-1] MUST continue to deliver normal GPS/GNSS outputs to applications during a Mobile Station Based (MS-Based) Network Initiated emergency session call.
+ </li>
+ <li>[C-4-2] MUST report positions and measurements to the <a href="https://developer.android.com/reference/android/location/LocationProvider">GNSS Location Provider</a> APIs.
</li>
</ul>
<h4 id="7_3_4_gyroscope">
@@ -6991,7 +7071,7 @@
</li>
</ul>
<p>
- If device implementations include a gyroscope and a accelerometer sensor, they:
+ If device implementations include a gyroscope and an accelerometer sensor, they:
</p>
<ul>
<li>[C-3-1] MUST implement the <code>TYPE_GRAVITY</code> and <code>TYPE_LINEAR_ACCELERATION</code> composite sensors.
@@ -7089,27 +7169,29 @@
[C-2-1] MUST have a <code>TYPE_ACCELEROMETER</code> sensor which:
</p>
<ul>
- <li>MUST have a measurement range between at least -8g and +8g.
+ <li>MUST have a measurement range between at least -8g and +8g, SHOULD have a measurement range between at least -16g and +16g.
</li>
- <li>MUST have a measurement resolution of at least 1024 LSB/G.
+ <li>MUST have a measurement resolution of at least 2048 LSB/g.
</li>
<li>MUST have a minimum measurement frequency of 12.5 Hz or lower.
</li>
- <li>MUST have a maximum measurement frequency of 400 Hz or higher.
+ <li>MUST have a maximum measurement frequency of 400 Hz or higher; SHOULD support the SensorDirectChannel <a href="https://developer.android.com/reference/android/hardware/SensorDirectChannel.html#RATE_VERY_FAST"><code>RATE_VERY_FAST</code></a>.
</li>
- <li>MUST have a measurement noise not above 400 uG/√Hz.
+ <li>MUST have a measurement noise not above 400 μg/√Hz.
</li>
<li>MUST implement a non-wake-up form of this sensor with a buffering capability of at least 3000 sensor events.
</li>
<li>MUST have a batching power consumption not worse than 3 mW.
</li>
- <li>SHOULD have a stationary noise bias stability of \<15 μg √Hz from 24hr static dataset.
+ <li>[C-SR] Is STRONGLY RECOMMENDED to have 3dB measurement bandwidth of at least 80% of Nyquist frequency, and white noise spectrum within this bandwidth.
</li>
- <li>SHOULD have a bias change vs. temperature of ≤ +/- 1mg / °C.
+ <li>SHOULD have an acceleration random walk less than 30 μg √Hz tested at room temperature.
+ </li>
+ <li>SHOULD have a bias change vs. temperature of ≤ +/- 1 mg/°C.
</li>
<li>SHOULD have a best-fit line non-linearity of ≤ 0.5%, and sensitivity change vs. temperature of ≤ 0.03%/C°.
</li>
- <li>SHOULD have white noise spectrum to ensure adequate qualification of sensor’s noise integrity.
+ <li>SHOULD have cross-axis sensitivity of < 2.5 % and variation of cross-axis sensitivity < 0.2% in device operation temperature range.
</li>
</ul>
</li>
@@ -7129,11 +7211,13 @@
</li>
<li>MUST have a minimum measurement frequency of 12.5 Hz or lower.
</li>
- <li>MUST have a maximum measurement frequency of 400 Hz or higher.
+ <li>MUST have a maximum measurement frequency of 400 Hz or higher; SHOULD support the SensorDirectChannel <a href="https://developer.android.com/reference/android/hardware/SensorDirectChannel.html#RATE_VERY_FAST"><code>RATE_VERY_FAST</code></a>.
</li>
<li>MUST have a measurement noise not above 0.014°/s/√Hz.
</li>
- <li>SHOULD have a stationary bias stability of < 0.0002 °/s √Hz from 24-hour static dataset.
+ <li>[C-SR] Is STRONGLY RECOMMENDED to have 3dB measurement bandwidth of at least 80% of Nyquist frequency, and white noise spectrum within this bandwidth.
+ </li>
+ <li>SHOULD have a rate random walk less than 0.001 °/s √Hz tested at room temperature.
</li>
<li>SHOULD have a bias change vs. temperature of ≤ +/- 0.05 °/ s / °C.
</li>
@@ -7143,10 +7227,12 @@
</li>
<li>SHOULD have a noise density of ≤ 0.007 °/s/√Hz.
</li>
- <li>SHOULD have white noise spectrum to ensure adequate qualification of sensor’s noise integrity.
- </li>
<li>SHOULD have calibration error less than 0.002 rad/s in temperature range 10 ~ 40 ℃ when device is stationary.
</li>
+ <li>SHOULD have g-sensitivity less than 0.1°/s/g.
+ </li>
+ <li>SHOULD have cross-axis sensitivity of < 4.0 % and cross-axis sensitivity variation < 0.3% in device operation temperature range.
+ </li>
</ul>
</li>
<li>
@@ -7154,9 +7240,12 @@
[C-2-4] MUST have a <code>TYPE_GYROSCOPE_UNCALIBRATED</code> with the same quality requirements as <code>TYPE_GYROSCOPE</code>.
</p>
</li>
- <li>[C-2-5] MUST have a <code>TYPE_GEOMAGNETIC_FIELD</code> sensor which:
+ <li>
+ <p>
+ [C-2-5] MUST have a <code>TYPE_GEOMAGNETIC_FIELD</code> sensor which:
+ </p>
<ul>
- <li>MUST have a measurement range between at least -900 and +900 uT.
+ <li>MUST have a measurement range between at least -900 and +900 μT.
</li>
<li>MUST have a measurement resolution of at least 5 LSB/uT.
</li>
@@ -7168,15 +7257,21 @@
</li>
</ul>
</li>
- <li>[C-2-6] MUST have a <code>TYPE_MAGNETIC_FIELD_UNCALIBRATED</code> with the same quality requirements as <code>TYPE_GEOMAGNETIC_FIELD</code> and in addition:
+ <li>
+ <p>
+ [C-2-6] MUST have a <code>TYPE_MAGNETIC_FIELD_UNCALIBRATED</code> with the same quality requirements as <code>TYPE_GEOMAGNETIC_FIELD</code> and in addition:
+ </p>
<ul>
<li>MUST implement a non-wake-up form of this sensor with a buffering capability of at least 600 sensor events.
</li>
- <li>SHOULD have white noise spectrum to ensure adequate qualification of sensor’s noise integrity.
+ <li>[C-SR] Is STRONGLY RECOMMENDED to have white noise spectrum from 1 Hz to at least 10 Hz when the report rate is 50 Hz or higher.
</li>
</ul>
</li>
- <li>[C-2-7] MUST have a <code>TYPE_PRESSURE</code> sensor which:
+ <li>
+ <p>
+ [C-2-7] MUST have a <code>TYPE_PRESSURE</code> sensor which:
+ </p>
<ul>
<li>MUST have a measurement range between at least 300 and 1100 hPa.
</li>
@@ -7230,13 +7325,13 @@
</li>
</ul>
</li>
- <li>[C-2-13] The event timestamp of the same physical event reported by the Accelerometer, Gyroscope sensor and Magnetometer MUST be within 2.5 milliseconds of each other.
+ <li>[C-2-13] The event timestamp of the same physical event reported by the Accelerometer, Gyroscope, and Magnetometer MUST be within 2.5 milliseconds of each other. The event timestamp of the same physical event reported by the Accelerometer and Gyroscope SHOULD be within 0.25 milliseconds of each other.
</li>
<li>[C-2-14] MUST have Gyroscope sensor event timestamps on the same time base as the camera subsystem and within 1 milliseconds of error.
</li>
<li>[C-2-15] MUST deliver samples to applications within 5 milliseconds from the time when the data is available on any of the above physical sensors to the application.
</li>
- <li>[C-2-16] MUST not have a power consumption higher than 0.5 mW when device is static and 2.0 mW when device is moving when any combination of the following sensors are enabled:
+ <li>[C-2-16] MUST NOT have a power consumption higher than 0.5 mW when device is static and 2.0 mW when device is moving when any combination of the following sensors are enabled:
<ul>
<li>
<code>SENSOR_TYPE_SIGNIFICANT_MOTION</code>
@@ -7264,38 +7359,45 @@
<ul>
<li>[C-3-1] MUST correctly declare support of direct channel types and direct report rates level through the <a href="https://developer.android.com/reference/android/hardware/Sensor.html#isDirectChannelTypeSupported%28int%29"><code>isDirectChannelTypeSupported</code></a> and <a href="https://developer.android.com/reference/android/hardware/Sensor.html#getHighestDirectReportRateLevel%28%29"><code>getHighestDirectReportRateLevel</code></a> API.
</li>
- <li>[C-3-2] MUST support at least one of the two sensor direct channel types for all sensors that declare support for sensor direct channel
- </li>
- <li>
- <a href="https://developer.android.com/reference/android/hardware/SensorDirectChannel.html#TYPE_HARDWARE_BUFFER"><code>TYPE_HARDWARE_BUFFER</code></a>
- </li>
- <li>
- <a href="https://developer.android.com/reference/android/hardware/SensorDirectChannel.html#TYPE_MEMORY_FILE"><code>TYPE_MEMORY_FILE</code></a>
+ <li>[C-3-2] MUST support at least one of the two sensor direct channel types for all sensors that declare support for sensor direct channel.
+ <ul>
+ <li>
+ <a href="https://developer.android.com/reference/android/hardware/SensorDirectChannel.html#TYPE_HARDWARE_BUFFER"><code>TYPE_HARDWARE_BUFFER</code></a>
+ </li>
+ <li>
+ <a href="https://developer.android.com/reference/android/hardware/SensorDirectChannel.html#TYPE_MEMORY_FILE"><code>TYPE_MEMORY_FILE</code></a>
+ </li>
+ </ul>
</li>
<li>SHOULD support event reporting through sensor direct channel for primary sensor (non-wakeup variant) of the following types:
- </li>
- <li>
- <code>TYPE_ACCELEROMETER</code>
- </li>
- <li>
- <code>TYPE_ACCELEROMETER_UNCALIBRATED</code>
- </li>
- <li>
- <code>TYPE_GYROSCOPE</code>
- </li>
- <li>
- <code>TYPE_GYROSCOPE_UNCALIBRATED</code>
- </li>
- <li>
- <code>TYPE_MAGNETIC_FIELD</code>
- </li>
- <li>
- <code>TYPE_MAGNETIC_FIELD_UNCALIBRATED</code>
+ <ul>
+ <li>
+ <code>TYPE_ACCELEROMETER</code>
+ </li>
+ <li>
+ <code>TYPE_ACCELEROMETER_UNCALIBRATED</code>
+ </li>
+ <li>
+ <code>TYPE_GYROSCOPE</code>
+ </li>
+ <li>
+ <code>TYPE_GYROSCOPE_UNCALIBRATED</code>
+ </li>
+ <li>
+ <code>TYPE_MAGNETIC_FIELD</code>
+ </li>
+ <li>
+ <code>TYPE_MAGNETIC_FIELD_UNCALIBRATED</code>
+ </li>
+ </ul>
</li>
</ul>
- <h4 id="7_3_10_fingerprint_sensor">
- 7.3.10. Fingerprint Sensor
+ <h4 id="7_3_10_biometric_sensors">
+ 7.3.10. Biometric Sensors
</h4>
+ <h5 id="7_3_10_1_fingerprint_sensors">
+ 7.3.10.1. Fingerprint Sensors
+ </h5>
<p>
If device implementations include a secure lock screen, they:
</p>
@@ -7321,7 +7423,7 @@
</li>
<li>[C-1-6] MUST have a hardware-backed keystore implementation, and perform the fingerprint matching in a Trusted Execution Environment (TEE) or on a chip with a secure channel to the TEE.
</li>
- <li>[C-1-7] MUST have all identifiable fingerprint data encrypted and cryptographically authenticated such that they cannot be acquired, read or altered outside of the Trusted Execution Environment (TEE) as documented in the <a href="https://source.android.com/devices/tech/security/authentication/fingerprint-hal.html">implementation guidelines</a> on the Android Open Source Project site.
+ <li>[C-1-7] MUST have all identifiable fingerprint data encrypted and cryptographically authenticated such that they cannot be acquired, read or altered outside of the Trusted Execution Environment (TEE), or a chip with a secure channel to the TEE as documented in the <a href="https://source.android.com/devices/tech/security/authentication/fingerprint-hal.html">implementation guidelines</a> on the Android Open Source Project site.
</li>
<li>[C-1-8] MUST prevent adding a fingerprint without first establishing a chain of trust by having the user confirm existing or add a new device credential (PIN/pattern/password) that's secured by TEE; the Android Open Source Project implementation provides the mechanism in the framework to do so.
</li>
@@ -7331,6 +7433,10 @@
</li>
<li>[C-1-11] MUST, when upgraded from a version earlier than Android 6.0, have the fingerprint data securely migrated to meet the above requirements or removed.
</li>
+ <li>[C-1-12] MUST completely remove all identifiable fingerprint data for a user when the user's account is removed (including via a factory reset).
+ </li>
+ <li>[C-1-13] MUST not allow unencrypted access to identifiable fingerprint data or any data derived from it (such as embeddings) to the Application Processor.
+ </li>
<li>[SR] Are STRONGLY RECOMMENDED to have a false rejection rate of less than 10%, as measured on the device.
</li>
<li>[SR] Are STRONGLY RECOMMENDED to have a latency below 1 second, measured from when the fingerprint sensor is touched until the screen is unlocked, for one enrolled finger.
@@ -7338,6 +7444,40 @@
<li>SHOULD use the Android Fingerprint icon provided in the Android Open Source Project.
</li>
</ul>
+ <h5 id="7_3_10_2_other_biometric_sensors">
+ 7.3.10.2. Other Biometric Sensors
+ </h5>
+ <p>
+ If device implementations include one or more non-fingerprint-based-biometric sensors and make them available to third-party apps they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST have a false acceptance rate not higher than 0.002%.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to have a spoof and imposter acceptance rate not higher than 7%.
+ </li>
+ <li>[C-1-2] MUST disclose that this mode may be less secure than a strong PIN, pattern, or password and clearly enumerate the risks of enabling it, if the spoof and imposter acceptance rates are higher than 7%.
+ </li>
+ <li>[C-1-3] MUST rate limit attempts for at least 30 seconds after five false trials for biometric verification - where a false trial is one with an adequate capture quality (ACQUIRED_GOOD) that does not match an enrolled biometric
+ </li>
+ <li>[C-1-4] MUST have a hardware-backed keystore implementation, and perform the biometric matching in a Trusted Execution Environment (TEE) or on a chip with a secure channel to the TEE.
+ </li>
+ <li>[C-1-5] MUST have all identifiable data encrypted and cryptographically authenticated such that they cannot be acquired, read or altered outside of the Trusted Execution Environment (TEE), or a chip with a secure channel to the TEE as documented in the <a href="https://source.android.com/devices/tech/security/authentication/fingerprint-hal.html">implementation guidelines</a> on the Android Open Source Project site.
+ </li>
+ <li>[C-1-6] MUST prevent adding new biometrics without first establishing a chain of trust by having the user confirm existing or add a new device credential (PIN/pattern/password) that's secured by TEE; the Android Open Source Project implementation provides the mechanism in the framework to do so.
+ </li>
+ <li>[C-1-7] MUST NOT enable third-party applications to distinguish between biometric enrollments.
+ </li>
+ <li>[C-1-8] MUST honor the individual flag for that biometric (ie: <code>DevicePolicyManager.KEYGUARD_DISABLE_FINGERPRINT</code>, <code>DevicePolicymanager.KEYGUARD_DISABLE_FACE</code>, or <code>DevicePolicymanager.KEYGUARD_DISABLE_IRIS</code>).
+ </li>
+ <li>[C-1-9] MUST completely remove all identifiable biometric data for a user when the user's account is removed (including via a factory reset).
+ </li>
+ <li>[C-1-10] MUST not allow unencrypted access to identifiable biometric data or any data derived from it (such as embeddings) to the Application Processor outside the context of the TEE.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to have a false rejection rate of less than 10%, as measured on the device.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to have a latency below 1 second, measured from when the biometric is detected, until the screen is unlocked, for each enrolled biometric.
+ </li>
+ </ul>
<h4 id="7_3_11_android_automotive-only_sensors">
7.3.11. Android Automotive-only sensors
</h4>
@@ -7360,7 +7500,7 @@
7.3.11.3. Driving Status
</h5>
<p>
- See <a href="#2_5_1_hardware">Section 2.5.1</a> for device-specific requirements.
+ This requirement is deprecated.
</p>
<h5 id="7_3_11_4_wheel_speed">
7.3.11.4. Wheel Speed
@@ -7368,6 +7508,12 @@
<p>
See <a href="#2_5_1_hardware">Section 2.5.1</a> for device-specific requirements.
</p>
+ <h5 id="7_3_11_5_parking_brake">
+ 7.3.11.5. Parking Brake
+ </h5>
+ <p>
+ See <a href="#2_5_1_hardware">Section 2.5.1</a> for device-specific requirements.
+ </p>
<h3 id="7_3_12_pose_sensor">
7.3.12. Pose Sensor
</h3>
@@ -7447,7 +7593,24 @@
If device implementations report <code>android.hardware.telephony</code>, they:
</p>
<ul>
- <li>[C-SR] Are STRONGLY RECOMMENDED to handle the the audio headset's <code>KEYCODE_MEDIA_PLAY_PAUSE</code> and <code>KEYCODE_HEADSETHOOK</code> events for the <a href="https://developer.android.com/reference/android/telecom/package-summary.html"><code>android.telecom</code></a> APIs as below:
+ <li>[C-1-1] MUST support the <code>ConnectionService</code> APIs described in the <a href="https://developer.android.com/guide/topics/connectivity/telecom/selfManaged.html">SDK</a>.
+ </li>
+ <li>[C-1-2] MUST display a new incoming call and provide user affordance to accept or reject the incoming call when the user is on an ongoing call that is made by a third-party app that does not support the hold feature specified via <a href="https://developer.android.com/reference/android/telecom/Connection.html#CAPABILITY_SUPPORT_HOLD"><code>CAPABILITY_SUPPORT_HOLD</code></a>.
+ </li>
+ <li>
+ <p>
+ [C-SR] Are STRONGLY RECOMMENDED to notify the user that answering an incoming call will drop an ongoing call.
+ </p>
+ <p>
+ The AOSP implementation meets these requirements by a heads-up notification which indicates to the user that answering an incoming call will cause the other call to be dropped.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-SR] Are STRONGLY RECOMMENDED to preload the default dialer app that shows a call log entry and the name of a third-party app in its call log when the third-party app sets the <a href="https://developer.android.com/reference/android/telecom/PhoneAccount.html#EXTRA_LOG_SELF_MANAGED_CALLS"><code>EXTRA_LOG_SELF_MANAGED_CALLS</code></a> extras key on its <code>PhoneAccount</code> to <code>true</code>.
+ </p>
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to handle the audio headset's <code>KEYCODE_MEDIA_PLAY_PAUSE</code> and <code>KEYCODE_HEADSETHOOK</code> events for the <a href="https://developer.android.com/reference/android/telecom/package-summary.html"><code>android.telecom</code></a> APIs as below:
<ul>
<li>Call <a href="https://developer.android.com/reference/android/telecom/Connection.html#onDisconnect%28%29"><code>Connection.onDisconnect()</code></a> when a short press of the key event is detected during an ongoing call.
</li>
@@ -7455,7 +7618,7 @@
</li>
<li>Call <a href="https://developer.android.com/reference/android/telecom/Connection.html#onReject%28%29"><code>Connection.onReject()</code></a> when a long press of the key event is detected during an incoming call.
</li>
- <li>Toggle the mute status of the <a href="https://developer.android.com/reference/android/telecom/CallAudioState.html"><code>CallAudioState</code></a>
+ <li>Toggle the mute status of the <a href="https://developer.android.com/reference/android/telecom/CallAudioState.html"><code>CallAudioState</code></a>.
</li>
</ul>
</li>
@@ -7471,7 +7634,7 @@
</li>
</ul>
<p>
- If device implementations include support for 802.11 and expose the functionality to a third-party application, they
+ If device implementations include support for 802.11 and expose the functionality to a third-party application, they:
</p>
<ul>
<li>[C-1-1] MUST implement the corresponding Android API.
@@ -7488,17 +7651,21 @@
</li>
</ul>
</li>
- <li>SHOULD randomize the source MAC address and sequence number of probe request frames, once at the beginning of each scan, while STA is disconnected.
+ <li>[C-1-5] MUST NOT treat the <a href="https://developer.android.com/reference/android/net/wifi/WifiManager.html#enableNetwork%28int%2C%20boolean%29"><code>WifiManager.enableNetwork()</code></a> API method call as a sufficient indication to switch the currently active <code>Network</code> that is used by default for application traffic and is returned by <a href="https://developer.android.com/reference/android/net/ConnectivityManager"><code>ConnectivityManager</code></a> API methods such as <a href="https://developer.android.com/reference/android/net/ConnectivityManager#getActiveNetwork%28%29"><code>getActiveNetwork</code></a> and <a href="https://developer.android.com/reference/android/net/ConnectivityManager#registerDefaultNetworkCallback%28android.net.ConnectivityManager.NetworkCallback,%20android.os.Handler%29"><code>registerDefaultNetworkCallback</code></a>. In other words, they MAY only disable the Internet access provided by any other network provider (e.g. mobile data) if they successfully validate that the Wi-Fi network is providing Internet access.
+ </li>
+ <li>[C-1-6] MUST, when the <a href="https://developer.android.com/reference/android/net/ConnectivityManager.html#reportNetworkConnectivity%28android.net.Network%2C%20boolean%29"><code>ConnectivityManager.reportNetworkConnectivity()</code></a> API method is called, re-evaluate the Internet access on the <code>Network</code> and, once the evaluation determines that the current <code>Network</code> no longer provides Internet access, switch to any other available network (e.g. mobile data) that provides Internet access.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to randomize the source MAC address and sequence number of probe request frames, once at the beginning of each scan, while STA is disconnected.
<ul>
<li>Each group of probe request frames comprising one scan should use one consistent MAC address (SHOULD NOT randomize MAC address halfway through a scan).
</li>
- <li>Probe request sequence number should iterate as normal (sequentially) between the probe requests in a scan
+ <li>Probe request sequence number should iterate as normal (sequentially) between the probe requests in a scan.
</li>
- <li>Probe request sequence number should randomize between the last probe request of a scan and the first probe request of the next scan
+ <li>Probe request sequence number should randomize between the last probe request of a scan and the first probe request of the next scan.
</li>
</ul>
</li>
- <li>SHOULD only allow the following information elements in probe request frames, while STA is disconnected:
+ <li>[C-SR] Are STRONGLY RECOMMENDED, while STA is disconnected, to allow only the following elements in probe request frames:
<ul>
<li>SSID Parameter Set (0)
</li>
@@ -7507,6 +7674,13 @@
</ul>
</li>
</ul>
+ <p>
+ If device implementations support Wi-Fi and use Wi-Fi for location scanning, they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST provide a user affordance to enable/disable the value read through the <a href="https://developer.android.com/reference/android/net/wifi/WifiManager.html#isScanAlwaysAvailable%28%29"><code>WifiManager.isScanAlwaysAvailable</code></a> API method.
+ </li>
+ </ul>
<h5 id="7_4_2_1_wi-fi_direct">
7.4.2.1. Wi-Fi Direct
</h5>
@@ -7527,7 +7701,7 @@
</li>
<li>[C-1-3] MUST support regular Wi-Fi operation.
</li>
- <li>SHOULD support Wi-Fi and Wi-Fi Direct operations concurrently.
+ <li>[C-1-4] MUST support Wi-Fi and Wi-Fi Direct operations concurrently.
</li>
</ul>
<h5 id="7_4_2_2_wi-fi_tunneled_direct_link_setup">
@@ -7571,7 +7745,14 @@
</li>
<li>[C-1-3] MUST support Wi-Fi and Wi-Fi Aware operations concurrently.
</li>
- <li>[C-1-4] MUST randomize the Wi-Fi Aware management interface address at intervals no longer then 30 minutes and whenever Wi-Fi Aware is enabled.
+ <li>[C-1-4] MUST randomize the Wi-Fi Aware management interface address at intervals no longer than 30 minutes and whenever Wi-Fi Aware is enabled.
+ </li>
+ </ul>
+ <p>
+ If device implementations include support for Wi-Fi Aware and Wi-Fi Location as described in <a href="#7_4_2_5_Wi-Fi_Location">Section 7.4.2.5</a> and exposes these functionalities to third-party apps, then they:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST implement the location-aware discovery APIs: <a href="https://developer.android.com/reference/android/net/wifi/aware/PublishConfig.Builder.html#setRangingEnabled%28boolean%29">setRangingEnabled</a>, <a href="https://developer.android.com/reference/android/net/wifi/aware/SubscribeConfig.Builder#setMinDistanceMm%28int%29">setMinDistanceMm</a>, <a href="https://developer.android.com/reference/android/net/wifi/aware/SubscribeConfig.Builder#setMaxDistanceMm%28int%29">setMaxDistanceMm</a> , and <a href="https://developer.android.com/reference/android/net/wifi/aware/DiscoverySessionCallback#onServiceDiscoveredWithinRange%28android.net.wifi.aware.PeerHandle,%20byte[],%20java.util.List%3Cbyte[]%3E,%20int%29">onServiceDiscoveredWithinRange</a>.
</li>
</ul>
<h5 id="7_4_2_4_wi-fi_passpoint">
@@ -7600,6 +7781,27 @@
<li>[C-2-1] The implementation of the Passpoint related <code>WifiManager</code> APIs MUST throw an <code>UnsupportedOperationException</code>.
</li>
</ul>
+ <h5 id="7_4_2_5_wi-fi_location_(wi-fi_round_trip_time_-_rtt)">
+ 7.4.2.5. Wi-Fi Location (Wi-Fi Round Trip Time - RTT)
+ </h5>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>SHOULD include support for <a href="https://www.wi-fi.org/discover-wi-fi/wi-fi-location">Wi-Fi Location</a>.
+ </li>
+ </ul>
+ <p>
+ If device implementations include support for Wi-Fi Location and expose the functionality to third-party apps, then they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST implement the <code>WifiRttManager</code> APIs as described in the <a href="http://developer.android.com/reference/android/net/wifi/rtt/WifiRttManager.html">SDK documentation</a>.
+ </li>
+ <li>[C-1-2] MUST declare the <code>android.hardware.wifi.rtt</code> feature flag.
+ </li>
+ <li>[C-1-3] MUST randomize the source MAC address for each RTT burst which is executed while the Wi-Fi interface on which the RTT is being executed is not associated with an Access Point.
+ </li>
+ </ul>
<h4 id="7_4_3_bluetooth">
7.4.3. Bluetooth
</h4>
@@ -7611,6 +7813,13 @@
</li>
</ul>
<p>
+ If device implementations support HFP, A2DP and AVRCP, they:
+ </p>
+ <ul>
+ <li>SHOULD support at least 5 total connected devices.
+ </li>
+ </ul>
+ <p>
If device implementations declare <code>android.hardware.vr.high_performance</code> feature, they:
</p>
<ul>
@@ -7626,7 +7835,7 @@
<ul>
<li>[C-2-1] MUST declare the relevant platform features (<code>android.hardware.bluetooth</code> and <code>android.hardware.bluetooth_le</code> respectively) and implement the platform APIs.
</li>
- <li>SHOULD implement relevant Bluetooth profiles such as A2DP, AVCP, OBEX, etc. as appropriate for the device.
+ <li>SHOULD implement relevant Bluetooth profiles such as A2DP, AVRCP, OBEX, HFP, etc. as appropriate for the device.
</li>
</ul>
<p>
@@ -7656,6 +7865,13 @@
</p>
</li>
</ul>
+ <p>
+ If device implementations support Bluetooth LE and use Bluetooth LE for location scanning, they:
+ </p>
+ <ul>
+ <li>[C-4-1] MUST provide a user affordance to enable/disable the value read through the System API <code>BluetoothAdapter.isBleScanAlwaysAvailable()</code>.
+ </li>
+ </ul>
<h4 id="7_4_4_near-field_communications">
7.4.4. Near-Field Communications
</h4>
@@ -7677,16 +7893,18 @@
<li>MUST be capable of reading and writing NDEF messages via the following NFC standards as below:
</li>
<li>[C-1-2] MUST be capable of acting as an NFC Forum reader/writer (as defined by the NFC Forum technical specification NFCForum-TS-DigitalProtocol-1.0) via the following NFC standards:
- </li>
- <li>NfcA (ISO14443-3A)
- </li>
- <li>NfcB (ISO14443-3B)
- </li>
- <li>NfcF (JIS X 6319-4)
- </li>
- <li>IsoDep (ISO 14443-4)
- </li>
- <li>NFC Forum Tag Types 1, 2, 3, 4, 5 (defined by the NFC Forum)
+ <ul>
+ <li>NfcA (ISO14443-3A)
+ </li>
+ <li>NfcB (ISO14443-3B)
+ </li>
+ <li>NfcF (JIS X 6319-4)
+ </li>
+ <li>IsoDep (ISO 14443-4)
+ </li>
+ <li>NFC Forum Tag Types 1, 2, 3, 4, 5 (defined by the NFC Forum)
+ </li>
+ </ul>
</li>
<li>
<p>
@@ -7697,17 +7915,19 @@
<p>
[C-1-3] MUST be capable of transmitting and receiving data via the following peer-to-peer standards and protocols:
</p>
- </li>
- <li>ISO 18092
- </li>
- <li>LLCP 1.2 (defined by the NFC Forum)
- </li>
- <li>SDP 1.0 (defined by the NFC Forum)
- </li>
- <li>
- <a href="http://static.googleusercontent.com/media/source.android.com/en/us/compatibility/ndef-push-protocol.pdf">NDEF Push Protocol</a>
- </li>
- <li>SNEP 1.0 (defined by the NFC Forum)
+ <ul>
+ <li>ISO 18092
+ </li>
+ <li>LLCP 1.2 (defined by the NFC Forum)
+ </li>
+ <li>SDP 1.0 (defined by the NFC Forum)
+ </li>
+ <li>
+ <a href="http://static.googleusercontent.com/media/source.android.com/en/us/compatibility/ndef-push-protocol.pdf">NDEF Push Protocol</a>
+ </li>
+ <li>SNEP 1.0 (defined by the NFC Forum)
+ </li>
+ </ul>
</li>
<li>[C-1-4] MUST include support for <a href="http://developer.android.com/guide/topics/connectivity/nfc/nfc.html">Android Beam</a> and SHOULD enable Android Beam by default.
</li>
@@ -7737,7 +7957,7 @@
</li>
</ul>
<p>
- (Note that publicly available links are not available for the JIS, ISO, and NFC Forum specifications cited above.)
+ Note that publicly available links are not available for the JIS, ISO, and NFC Forum specifications cited above.
</p>
<p>
Android includes support for NFC Host Card Emulation (HCE) mode.
@@ -7757,7 +7977,7 @@
<ul>
<li>[C-3-1] MUST report the <code>android.hardware.nfc.hcef</code> feature constant.
</li>
- <li>[C-3-2] MUST implement the [NfcF Card Emulation APIs] (https://developer.android.com/reference/android/nfc/cardemulation/NfcFCardEmulation.html) as defined in the Android SDK.
+ <li>[C-3-2] MUST implement the <a href="https://developer.android.com/reference/android/nfc/cardemulation/NfcFCardEmulation.html">NfcF Card Emulation APIs</a> as defined in the Android SDK.
</li>
</ul>
<p>
@@ -7776,47 +7996,56 @@
Device implementations:
</p>
<ul>
- <li>[C-0-1] MUST include support for one or more forms of data networking. Specifically, device implementations MUST include support for at least one data standard capable of 200Kbit/sec or greater. Examples of technologies that satisfy this requirement include EDGE, HSPA, EV-DO, 802.11g, Ethernet, Bluetooth PAN, etc.
+ <li>[C-0-1] MUST include support for one or more forms of data networking. Specifically, device implementations MUST include support for at least one data standard capable of 200 Kbit/sec or greater. Examples of technologies that satisfy this requirement include EDGE, HSPA, EV-DO, 802.11g, Ethernet and Bluetooth PAN.
+ </li>
+ <li>SHOULD also include support for at least one common wireless data standard, such as 802.11 (Wi-Fi), when a physical networking standard (such as Ethernet) is the primary data connection.
+ </li>
+ <li>MAY implement more than one form of data connectivity.
</li>
<li>[C-0-2] MUST include an IPv6 networking stack and support IPv6 communication using the managed APIs, such as <code>java.net.Socket</code> and <code>java.net.URLConnection</code>, as well as the native APIs, such as <code>AF_INET6</code> sockets.
</li>
<li>[C-0-3] MUST enable IPv6 by default.
</li>
- <li>MUST ensure that IPv6 communication is as reliable as IPv4, for example.
+ <li>MUST ensure that IPv6 communication is as reliable as IPv4, for example:
+ <ul>
+ <li>[C-0-4] MUST maintain IPv6 connectivity in doze mode.
+ </li>
+ <li>[C-0-5] Rate-limiting MUST NOT cause the device to lose IPv6 connectivity on any IPv6-compliant network that uses RA lifetimes of at least 180 seconds.
+ </li>
+ </ul>
</li>
- <li>[C-0-4] MUST maintain IPv6 connectivity in doze mode.
- </li>
- <li>[C-0-5] Rate-limiting MUST NOT cause the device to lose IPv6 connectivity on any IPv6-compliant network that uses RA lifetimes of at least 180 seconds.
- </li>
- <li>SHOULD also include support for at least one common wireless data standard, such as 802.11 (Wi-Fi) when a physical networking standard (such as Ethernet) is the primary data connection
- </li>
- <li>MAY implement more than one form of data connectivity.
+ <li>[C-0-6] MUST provide third-party applications with direct IPv6 connectivity to the network when connected to an IPv6 network, without any form of address or port translation happening locally on the device. Both managed APIs such as <a href="https://developer.android.com/reference/java/net/Socket.html#getLocalAddress%28%29"><code>Socket#getLocalAddress</code></a> or <a href="https://developer.android.com/reference/java/net/Socket.html#getLocalPort%28%29"><code>Socket#getLocalPort</code></a>) and NDK APIs such as <code>getsockname()</code> or <code>IPV6_PKTINFO</code> MUST return the IP address and port that is actually used to send and receive packets on the network.
</li>
</ul>
<p>
- The required level of IPv6 support depends on the network type, as follows:
+ The required level of IPv6 support depends on the network type, as shown in the following requirements.
</p>
<p>
- If devices implementations support Wi-Fi networks, they:
+ If device implementations support Wi-Fi, they:
</p>
<ul>
<li>[C-1-1] MUST support dual-stack and IPv6-only operation on Wi-Fi.
</li>
</ul>
<p>
- If device impelementations support Ethernet networks, they:
+ If device implementations support Ethernet, they:
</p>
<ul>
<li>[C-2-1] MUST support dual-stack operation on Ethernet.
</li>
</ul>
<p>
- If device implementations support cellular data, they:
+ If device implementations support Cellular data, they:
</p>
<ul>
- <li>[C-3-1] MUST simultaneously meet these requirements on each network to which it is connected when a device is simultaneously connected to more than one network (e.g., Wi-Fi and cellular data), .
+ <li>SHOULD support IPv6 operation (IPv6-only and possibly dual-stack) on cellular.
</li>
- <li>SHOULD support IPv6 operation (IPv6-only and possibly dual-stack) on cellular data.
+ </ul>
+ <p>
+ If device implementations support more than one network type (e.g., Wi-Fi and cellular data), they:
+ </p>
+ <ul>
+ <li>[C-3-1] MUST simultaneously meet the above requirements on each network when the device is simultaneously connected to more than one network type.
</li>
</ul>
<h4 id="7_4_6_sync_settings">
@@ -7859,6 +8088,16 @@
<li>[C-2-3] MUST have an activity that handles the <code>Settings.ACTION_IGNORE_BACKGROUND_DATA_RESTRICTIONS_SETTINGS</code> intent but MAY implement it as a no-op.
</li>
</ul>
+ <h4 id="7_4_8_secure_elements">
+ 7.4.8. Secure Elements
+ </h4>
+ <p>
+ If device implementations support <a href="https://developer.android.com/reference/android/se/omapi/package-summary">Open Mobile API</a> capable secure elements and make them available to 3rd-party apps, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST enumerate the available Secure Elements readers when <a href="https://developer.android.com/reference/android/se/omapi/SEService#getReaders%28%29"><code>android.se.omapi.SEService.getReaders()</code></a> method is called.
+ </li>
+ </ul>
<h3 id="7_5_cameras">
7.5. Cameras
</h3>
@@ -7900,7 +8139,7 @@
</li>
</ul>
<p>
- If the Camera includes a flash:
+ If the camera includes a flash:
</p>
<ul>
<li>[C-2-1] the flash lamp MUST NOT be lit while an <code>android.hardware.Camera.PreviewCallback</code> instance has been registered on a Camera preview surface, unless the application has explicitly enabled the flash by enabling the <code>FLASH_MODE_AUTO</code> or <code>FLASH_MODE_ON</code> attributes of a <code>Camera.Parameters</code> object. Note that this constraint does not apply to the device’s built-in system camera application, but only to third-party applications using <code>Camera.PreviewCallback</code>.
@@ -7916,7 +8155,7 @@
Device implementations:
</p>
<ul>
- <li>MAY include a front-facing camera
+ <li>MAY include a front-facing camera.
</li>
</ul>
<p>
@@ -7929,11 +8168,11 @@
</li>
<li>[C-1-3] MUST NOT use a front-facing camera as the default for the Camera API and MUST NOT configure the API to treat a front-facing camera as the default rear-facing camera, even if it is the only camera on the device.
</li>
- <li>[C-1-5] The camera preview MUST be mirrored horizontally relative to the orientation specified by the application when the current application has explicitly requested that the Camera display be rotated via a call to the <a href="http://developer.android.com/reference/android/hardware/Camera.html#setDisplayOrientation(int)"><code>android.hardware.Camera.setDisplayOrientation()</code></a> method. Conversely, the preview MUST be mirrored along the device’s default horizontal axis when the the current application does not explicitly request that the Camera display be rotated via a call to the <a href="http://developer.android.com/reference/android/hardware/Camera.html#setDisplayOrientation(int)"><code>android.hardware.Camera.setDisplayOrientation()</code></a> method.
+ <li>[C-1-4] The camera preview MUST be mirrored horizontally relative to the orientation specified by the application when the current application has explicitly requested that the Camera display be rotated via a call to the <a href="http://developer.android.com/reference/android/hardware/Camera.html#setDisplayOrientation(int)"><code>android.hardware.Camera.setDisplayOrientation()</code></a> method. Conversely, the preview MUST be mirrored along the device’s default horizontal axis when the current application does not explicitly request that the Camera display be rotated via a call to the <a href="http://developer.android.com/reference/android/hardware/Camera.html#setDisplayOrientation(int)"><code>android.hardware.Camera.setDisplayOrientation()</code></a> method.
</li>
- <li>[C-1-6] MUST NOT mirror the final captured still image or video streams returned to application callbacks or committed to media storage.
+ <li>[C-1-5] MUST NOT mirror the final captured still image or video streams returned to application callbacks or committed to media storage.
</li>
- <li>[C-1-7] MUST mirror the image displayed by the postview in the same manner as the camera preview image stream.
+ <li>[C-1-6] MUST mirror the image displayed by the postview in the same manner as the camera preview image stream.
</li>
<li>MAY include features (such as auto-focus, flash, etc.) available to rear-facing cameras as described in <a href="#7_5_1_rear-facing_camera">section 7.5.1</a>.
</li>
@@ -7956,18 +8195,27 @@
</li>
</ul>
<p>
- If device impelmentations include support for an external camera, they:
+ If device implementations include support for an external camera, they:
</p>
<ul>
<li>[C-1-1] MUST declare the platform feature flag <code>android.hardware.camera.external</code> and <code>android.hardware camera.any</code>.
</li>
- <li>[C-1-2] MUST support USB Video Class (UVC 1.0 or higher) if the external camera connects through the USB port.
+ <li>[C-1-2] MUST support USB Video Class (UVC 1.0 or higher) if the external camera connects through the USB host port.
+ </li>
+ <li>[C-1-3] MUST pass camera CTS tests with a physical external camera device connected. Details of camera CTS testing are available at <a href="https://source.android.com/compatibility/cts/camera-hal">source.android.com</a>.
</li>
<li>SHOULD support video compressions such as MJPEG to enable transfer of high-quality unencoded streams (i.e. raw or independently compressed picture streams).
</li>
<li>MAY support multiple cameras.
</li>
- <li>MAY support camera-based video encoding. If supported, a simultaneous unencoded / MJPEG stream (QVGA or greater resolution) MUST be accessible to the device implementation.
+ <li>MAY support camera-based video encoding.
+ </li>
+ </ul>
+ <p>
+ If camera-based video encoding is supported:
+ </p>
+ <ul>
+ <li>[C-2-1] A simultaneous unencoded / MJPEG stream (QVGA or greater resolution) MUST be accessible to the device implementation.
</li>
</ul>
<h4 id="7_5_4_camera_api_behavior">
@@ -7977,7 +8225,10 @@
Android includes two API packages to access the camera, the newer android.hardware.camera2 API expose lower-level camera control to the app, including efficient zero-copy burst/streaming flows and per-frame controls of exposure, gain, white balance gains, color conversion, denoising, sharpening, and more.
</p>
<p>
- The older API package, <code>android.hardware.Camera</code>, is marked as deprecated in Android 5.0 but as it should still be available for apps to use. Android device implementations MUST ensure the continued support of the API as described in this section and in the Android SDK.
+ The older API package,<code>android.hardware.Camera</code>, is marked as deprecated in Android 5.0 but as it should still be available for apps to use. Android device implementations MUST ensure the continued support of the API as described in this section and in the Android SDK.
+ </p>
+ <p>
+ All features that are common between the deprecated android.hardware.Camera class and the newer android.hardware.camera2 package MUST have equivalent performance and quality in both APIs. For example, with equivalent settings, autofocus speed and accuracy must be identical, and the quality of captured images must be the same. Features that depend on the different semantics of the two APIs are not required to have matching speed or quality, but SHOULD match as closely as possible.
</p>
<p>
Device implementations MUST implement the following behaviors for the camera-related APIs, for all available cameras. Device implementations:
@@ -8003,6 +8254,8 @@
</li>
<li>[C-0-10] MUST broadcast the <code>Camera.ACTION_NEW_VIDEO</code> intent whenever a new video is recorded by the camera and the entry of the picture has been added to the media store.
</li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to support a logical camera device that lists capability <a href="https://developer.android.com/reference/android/hardware/camera2/CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA"><code>CameraMetadata.REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA</code></a>, for devices with multiple cameras facing the same direction, consisting of each physical camera facing that direction, as long as the physical camera type is supported by the framework and <a href="https://developer.android.com/reference/android/hardware/camera2/CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL"><code>CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL</code></a> for the physical cameras is either <code>LIMITED</code>, <code>FULL</code>, or <code>LEVEL_3</code>.
+ </li>
</ul>
<h4 id="7_5_5_camera_orientation">
7.5.5. Camera Orientation
@@ -8044,12 +8297,12 @@
</li>
</ul>
<p>
- Device implementations MAY meet the above requirements using either:
+ Device implementations MAY meet the above requirements using either of the following:
</p>
<ul>
- <li>a user-accessible removable storage, such as a Secure Digital (SD) card slot.
+ <li>User-accessible removable storage, such as a Secure Digital (SD) card slot.
</li>
- <li>a portion of the internal (non-removable) storage as implemented in the Android Open Source Project (AOSP).
+ <li>A portion of the internal (non-removable) storage as implemented in the Android Open Source Project (AOSP).
</li>
</ul>
<p>
@@ -8062,7 +8315,7 @@
</li>
</ul>
<p>
- If device implementations use a protion of the non-removable storage to satisfy the above requirements, they:
+ If device implementations use a portion of the non-removable storage to satisfy the above requirements, they:
</p>
<ul>
<li>SHOULD use the AOSP implementation of the internal application shared storage.
@@ -8074,7 +8327,7 @@
If device implementations include multiple shared storage paths (such as both an SD card slot and shared internal storage), they:
</p>
<ul>
- <li>[C-3-1] MUST allow only pre-installed and privileged Android applications with the <code>WRITE_EXTERNAL_STORAGE</code> permission to write to the secondary external storage, except when writing to their package-specific directories or within the <code>URI</code> returned by firing the <code>ACTION_OPEN_DOCUMENT_TREE</code> intent.
+ <li>[C-2-1] MUST allow only pre-installed and privileged Android applications with the <code>WRITE_EXTERNAL_STORAGE</code> permission to write to the secondary external storage, except when writing to their package-specific directories or within the <code>URI</code> returned by firing the <code>ACTION_OPEN_DOCUMENT_TREE</code> intent.
</li>
</ul>
<p>
@@ -8155,7 +8408,7 @@
</li>
</ul>
<p>
- If device implementations including a USB port, implement the AOA specification, they:
+ If device implementations include a USB port and implement the AOA specification, they:
</p>
<ul>
<li>[C-2-1] MUST declare support for the hardware feature <a href="http://developer.android.com/guide/topics/connectivity/usb/accessory.html"><code>android.hardware.usb.accessory</code></a>.
@@ -8197,7 +8450,7 @@
If device implementations include a USB port supporting host mode and the USB audio class, they:
</p>
<ul>
- <li>[C-2-1] MUST support the <a href="https://developer.android.com/reference/android/hardware/usb/UsbConstants.html#USB_CLASS_HID">USB HID class</a>
+ <li>[C-2-1] MUST support the <a href="https://developer.android.com/reference/android/hardware/usb/UsbConstants.html#USB_CLASS_HID">USB HID class</a>.
</li>
<li>[C-2-2] MUST support the detection and mapping of the following HID data fields specified in the <a href="http://www.usb.org/developers/hidpage/Hut1_12v2.pdf">USB HID Usage Tables</a> and the <a href="http://www.usb.org/developers/hidpage/Voice_Command_Usage.pdf">Voice Command Usage Request</a> to the <a href="https://developer.android.com/reference/android/view/KeyEvent.html"><code>KeyEvent</code></a> constants as below:
<ul>
@@ -8248,7 +8501,7 @@
</li>
<li>[C-1-3] MUST meet the audio latency requirements in <a href="#5_6_audio_latency">section 5.6</a>.
</li>
- <li>[SR] STRONGLY RECOMMENDED to support near-ultrasound recording as described in <a href="#7_8_3_near_ultrasound">section 7.8.3</a>.
+ <li>[SR] Are STRONGLY RECOMMENDED to support near-ultrasound recording as described in <a href="#7_8_3_near_ultrasound">section 7.8.3</a>.
</li>
</ul>
<p>
@@ -8292,8 +8545,12 @@
7.8.2.1. Analog Audio Ports
</h5>
<p>
- In order to be compatible with the <a href="http://source.android.com/accessories/headset-spec.html">headsets and other audio accessories</a> using the 3.5mm audio plug across the Android ecosystem, if a device implementation includes one or more analog audio ports, at least one of the audio port(s) SHOULD be a 4 conductor 3.5mm audio jack.
+ In order to be compatible with the <a href="https://source.android.com/devices/accessories/headset/plug-headset-spec">headsets and other audio accessories</a> using the 3.5mm audio plug across the Android ecosystem, if device implementations include one or more analog audio ports, they:
</p>
+ <ul>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to include at least one of the audio port(s) to be a 4 conductor 3.5mm audio jack.
+ </li>
+ </ul>
<p>
If device implementations have a 4 conductor 3.5mm audio jack, they:
</p>
@@ -8321,16 +8578,16 @@
</li>
<li>[C-1-6] MUST have a microphone bias voltage between 1.8V ~ 2.9V.
</li>
- <li>[SR] STRONGLY RECOMMENDED to detect and map to the keycode for the following range of equivalent impedance between the microphone and ground conductors on the audio plug:
+ <li>[C-1-7] MUST detect and map to the keycode for the following range of equivalent impedance between the microphone and ground conductors on the audio plug:
<ul>
<li>
<strong>110-180 ohm:</strong> <code>KEYCODE_VOICE_ASSIST</code>
</li>
</ul>
</li>
- <li>SHOULD support audio plugs with the OMTP pin-out order.
+ <li>[C-SR] Are STRONGLY RECOMMENDED to support audio plugs with the OMTP pin-out order.
</li>
- <li>SHOULD support audio recording from stereo headsets with a microphone.
+ <li>[C-SR] Are STRONGLY RECOMMEND to support audio recording from stereo headsets with a microphone.
</li>
</ul>
<p>
@@ -8381,50 +8638,60 @@
<p>
Android includes support for <a href="https://developer.android.com/reference/android/app/Activity.html#setVrModeEnabled%28boolean,%20android.content.ComponentName%29">VR Mode</a>, a feature which handles stereoscopic rendering of notifications and disables monocular system UI components while a VR application has user focus.
</p>
- <h4 id="7_9_2_virtual_reality_high_performance">
- 7.9.2. Virtual Reality High Performance
+ <h4 id="7_9_2_virtual_reality_mode_-_high_performance">
+ 7.9.2. Virtual Reality Mode - High Performance
</h4>
<p>
- If device implementations identify the support of high performance VR for longer user periods through the <code>android.hardware.vr.high_performance</code> feature flag, they:
+ If device implementations support VR mode, they:
</p>
<ul>
<li>[C-1-1] MUST have at least 2 physical cores.
</li>
- <li>[C-1-2] MUST declare <code>android.software.vr.mode feature</code>.
+ <li>[C-1-2] MUST declare the <code>android.hardware.vr.high_performance</code> feature.
</li>
<li>[C-1-3] MUST support sustained performance mode.
</li>
<li>[C-1-4] MUST support OpenGL ES 3.2.
</li>
- <li>[C-1-5] MUST support Vulkan Hardware Level 0 and SHOULD support Vulkan Hardware Level 1.
+ <li>[C-1-5] MUST support <code>android.hardware.vulkan.level</code> 0.
</li>
- <li>[C-1-6] MUST implement <a href="https://www.khronos.org/registry/EGL/extensions/KHR/EGL_KHR_mutable_render_buffer.txt"><code>EGL_KHR_mutable_render_buffer</code></a>, <a href="https://www.khronos.org/registry/EGL/extensions/ANDROID/EGL_ANDROID_front_buffer_auto_refresh.txt"><code>EGL_ANDROID_front_buffer_auto_refresh</code></a>, <a href="https://www.khronos.org/registry/EGL/extensions/ANDROID/EGL_ANDROID_get_native_client_buffer.txt"><code>EGL_ANDROID_get_native_client_buffer</code></a>, <a href="https://www.khronos.org/registry/EGL/extensions/KHR/EGL_KHR_fence_sync.txt"><code>EGL_KHR_fence_sync</code></a>, <a href="https://www.khronos.org/registry/EGL/extensions/KHR/EGL_KHR_wait_sync.txt"><code>EGL_KHR_wait_sync</code></a>, <a href="https://www.khronos.org/registry/EGL/extensions/IMG/EGL_IMG_context_priority.txt"><code>EGL_IMG_context_priority</code></a>, <a href="https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_protected_content.txt"><code>EGL_EXT_protected_content</code></a>, and expose the extensions in the list of available EGL extensions.
+ <li>SHOULD support <code>android.hardware.vulkan.level</code> 1 or higher.
+ </li>
+ <li>[C-1-6] MUST implement <a href="https://www.khronos.org/registry/EGL/extensions/KHR/EGL_KHR_mutable_render_buffer.txt"><code>EGL_KHR_mutable_render_buffer</code></a>, <a href="https://www.khronos.org/registry/EGL/extensions/ANDROID/EGL_ANDROID_front_buffer_auto_refresh.txt"><code>EGL_ANDROID_front_buffer_auto_refresh</code></a>, <a href="https://www.khronos.org/registry/EGL/extensions/ANDROID/EGL_ANDROID_get_native_client_buffer.txt"><code>EGL_ANDROID_get_native_client_buffer</code></a>, <a href="https://www.khronos.org/registry/EGL/extensions/KHR/EGL_KHR_fence_sync.txt"><code>EGL_KHR_fence_sync</code></a>, <a href="https://www.khronos.org/registry/EGL/extensions/KHR/EGL_KHR_wait_sync.txt"><code>EGL_KHR_wait_sync</code></a>, <a href="https://www.khronos.org/registry/EGL/extensions/IMG/EGL_IMG_context_priority.txt"><code>EGL_IMG_context_priority</code></a>, <a href="https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_protected_content.txt"><code>EGL_EXT_protected_content</code></a>, <a href="https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_gl_colorspace.txt"><code>EGL_EXT_image_gl_colorspace</code></a>, and expose the extensions in the list of available EGL extensions.
+ </li>
+ <li>[C-1-8] MUST implement <a href="https://www.khronos.org/registry/OpenGL/extensions/EXT/EXT_multisampled_render_to_texture2.txt"><code>GL_EXT_multisampled_render_to_texture2</code></a>, <a href="https://www.khronos.org/registry/OpenGL/extensions/OVR/OVR_multiview.txt"><code>GL_OVR_multiview</code></a>, <a href="https://www.khronos.org/registry/OpenGL/extensions/OVR/OVR_multiview2.txt"><code>GL_OVR_multiview2</code></a>, <a href="https://www.khronos.org/registry/OpenGL/extensions/OVR/OVR_multiview_multisampled_render_to_texture.txt"><code>GL_OVR_multiview_multisampled_render_to_texture</code></a>, <a href="https://www.khronos.org/registry/OpenGL/extensions/EXT/EXT_protected_textures.txt"><code>GL_EXT_protected_textures</code></a>, <a href="https://www.khronos.org/registry/OpenGL/extensions/EXT/EXT_EGL_image_array.txt"><code>GL_EXT_EGL_image_array</code></a>, <a href="https://www.khronos.org/registry/OpenGL/extensions/EXT/EXT_external_buffer.txt"><code>GL_EXT_external_buffer</code></a>, and expose the extensions in the list of available GL extensions.
+ </li>
+ <li>[C-1-24] MUST implement <a href="https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#VK_KHR_shared_presentable_image"><code>VK_KHR_shared_presentable_image</code></a>, <a href="https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#VK_GOOGLE_display_timing"><code>VK_GOOGLE_display_timing</code></a> and expose the extensions in the list of available Vulkan extensions.
+ </li>
+ <li>[C-1-25] MUST expose at least one Vulkan queue family that where <code>flags</code> contain both <code>VK_QUEUE_GRAPHICS_BIT</code> and <code>VK_QUEUE_COMPUTE_BIT</code>, and <code>queueCount</code> is at least 2.
+ </li>
+ <li>[SR] Are STRONGLY RECOMMENDED to support Vulkan 1.1.
+ </li>
+ <li>[SR] Are STRONGLY RECOMMENDED to implement <a href="https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#VK_ANDROID_external_memory_android_hardware_buffer"><code>VK_ANDROID_external_memory_android_hardware_buffer</code></a> and expose it in the list of available Vulkan extensions.
</li>
<li>[C-1-7] The GPU and display MUST be able to synchronize access to the shared front buffer such that alternating-eye rendering of VR content at 60fps with two render contexts will be displayed with no visible tearing artifacts.
</li>
- <li>[C-1-8] MUST implement <a href="https://www.khronos.org/registry/OpenGL/extensions/EXT/EXT_multisampled_render_to_texture.txt"><code>GL_EXT_multisampled_render_to_texture</code></a>, <a href="https://www.khronos.org/registry/OpenGL/extensions/OVR/OVR_multiview.txt"><code>GL_OVR_multiview</code></a>, <a href="https://www.khronos.org/registry/OpenGL/extensions/OVR/OVR_multiview2.txt"><code>GL_OVR_multiview2</code></a>, <a href="https://www.khronos.org/registry/OpenGL/extensions/OVR/OVR_multiview_multisampled_render_to_texture.txt"><code>GL_OVR_multiview_multisampled_render_to_texture</code></a>, <a href="https://www.khronos.org/registry/OpenGL/extensions/EXT/EXT_protected_textures.txt"><code>GL_EXT_protected_textures</code></a>, <a href="https://www.khronos.org/registry/OpenGL/extensions/EXT/EXT_EGL_image_array.txt"><code>GL_EXT_EGL_image_array</code></a>, <a href="https://www.khronos.org/registry/OpenGL/extensions/EXT/EXT_external_buffer.txt"><code>GL_EXT_external_buffer</code></a>, and expose the extensions in the list of available GL extensions.
+ <li>[C-1-9] MUST implement support for <a href="https://developer.android.com/ndk/reference/hardware__buffer_8h.html"><code>AHardwareBuffer</code></a> flags <code>AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER</code>, <code>AHARDWAREBUFFER_USAGE_SENSOR_DIRECT_DATA</code> and <code>AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT</code> as described in the NDK.
</li>
- <li>[C-1-9] MUST implement support for <a href="https://developer.android.com/ndk/reference/hardware__buffer_8h.html"><code>AHardwareBuffer</code></a> flags <code>AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER</code> and <code>AHARDWAREBUFFER_USAGE_SENSOR_DIRECT_DATA</code> as described in the NDK.
+ <li>[C-1-10] MUST implement support for <code>AHardwareBuffers</code> with more than one layer and any combination of the usage flags <code>AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT</code>, <code>AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE</code>, <code>AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT</code> for at least the following formats: <code>AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM</code>, <code>AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM</code>, <code>AHARDWAREBUFFER_FORMAT_R10G10B10A2_UNORM</code>, <code>AHARDWAREBUFFER_FORMAT_R16G16B16A16_FLOAT</code>.
</li>
- <li>[C-1-10] MUST implement support for <code>AHardwareBuffers</code> with more than one layer.
+ <li>[C-1-11] MUST support H.264 decoding at least 3840 x 2160 at 30fps, compressed to an average of 40Mbps (equivalent to 4 instances of 1920 x1080 at 30 fps-10 Mbps or 2 instances of 1920 x 1080 at 60 fps-20 Mbps).
</li>
- <li>[C-1-11] MUST support H.264 decoding at least 3840x2160@30fps-40Mbps (equivalent to 4 instances of 1920x1080@30fps-10Mbps or 2 instances of 1920x1080@60fps-20Mbps).
- </li>
- <li>[C-1-12] MUST support HEVC and VP9, MUST be capable to decode at least 1920x1080@30fps-10Mbps and SHOULD be capable to decode 3840x2160@30fps-20Mbps (equivalent to 4 instances of 1920x1080@30fps-5Mbps).
+ <li>[C-1-12] MUST support HEVC and VP9, MUST be capable of decoding at least 1920 x 1080 at 30 fps compressed to an average of 10 Mbps and SHOULD be capable of decoding 3840 x 2160 at 30 fps-20 Mbps (equivalent to 4 instances of 1920 x 1080 at 30 fps-5 Mbps).
</li>
<li>[C-1-13] MUST support <code>HardwarePropertiesManager.getDeviceTemperatures</code> API and return accurate values for skin temperature.
</li>
- <li>[C-1-14] MUST have an embedded screen, and its resolution MUST be at least be FullHD(1080p) and STRONGLY RECOMMENDED TO BE be QuadHD (1440p) or higher.
+ <li>[C-1-14] MUST have an embedded screen, and its resolution MUST be at least 1920 x 1080.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to have a display resolution of at least 2560 x 1440.
</li>
<li>[C-1-15] The display MUST update at least 60 Hz while in VR Mode.
</li>
- <li>[C-1-16] The display latency (as measured on Gray-to-Gray, White-to-Black, and Black-to-White switching time) MUST be ≤ 6 milliseconds.
- </li>
<li>[C-1-17] The display MUST support a low-persistence mode with ≤ 5 milliseconds persistence, persistence being defined as the amount of time for which a pixel is emitting light.
</li>
<li>[C-1-18] MUST support Bluetooth 4.2 and Bluetooth LE Data Length Extension <a href="#7_4_3_bluetooth">section 7.4.3</a>.
</li>
- <li>[C-1-19] MUST support and properly report <a href='https://developer.android.com/reference/android/hardware/Sensor.html#isDirectChannelTypeSupported%28int%29"'>Direct Channel Type</a> for all of the following default sensor types:
+ <li>[C-1-19] MUST support and properly report <a href="https://developer.android.com/reference/android/hardware/Sensor#isDirectChannelTypeSupported%28int%29">Direct Channel Type</a> for all of the following default sensor types:
<ul>
<li>
<code>TYPE_ACCELEROMETER</code>
@@ -8448,9 +8715,26 @@
</li>
<li>[C-1-20] MUST support the <a href="https://developer.android.com/reference/android/hardware/SensorDirectChannel.html#TYPE_HARDWARE_BUFFER"><code>TYPE_HARDWARE_BUFFER</code></a> direct channel type for all Direct Channel Types listed above.
</li>
- <li>[SR] Are STRONGLY RECOMMENDED to support <code>android.hardware.sensor.hifi_sensors</code> feature and MUST meet the gyroscope, accelerometer, and magnetometer related requirements for <code>android.hardware.hifi_sensors</code>.
+ <li>[C-1-21] MUST meet the gyroscope, accelerometer, and magnetometer related requirements for <code>android.hardware.hifi_sensors</code>, as specified in <a href="#7_3_9_high_fidelity_sensors">section 7.3.9</a>.
</li>
- <li>MAY provide an exclusive core to the foreground application and MAY support the <code>Process.getExclusiveCores</code> API to return the numbers of the cpu cores that are exclusive to the top foreground application. If exclusive core is supported then the core MUST not allow any other userspace processes to run on it (except device drivers used by the application), but MAY allow some kernel processes to run as necessary.
+ <li>[SR] Are STRONGLY RECOMMENDED to support the <code>android.hardware.sensor.hifi_sensors</code> feature.
+ </li>
+ <li>[C-1-22] MUST have end-to-end motion to photon latency not higher than 28 milliseconds.
+ </li>
+ <li>[SR] Are STRONGLY RECOMMENDED to have end-to-end motion to photon latency not higher than 20 milliseconds.
+ </li>
+ <li>[C-1-23] MUST have first-frame ratio, which is the ratio between the brightness of pixels on the first frame after a transition from black to white and the brightness of white pixels in steady state, of at least 85%.
+ </li>
+ <li>[SR] Are STRONGLY RECOMMENDED to have first-frame ratio of at least 90%.
+ </li>
+ <li>MAY provide an exclusive core to the foreground application and MAY support the <code>Process.getExclusiveCores</code> API to return the numbers of the cpu cores that are exclusive to the top foreground application.
+ </li>
+ </ul>
+ <p>
+ If exclusive core is supported, then the core:
+ </p>
+ <ul>
+ <li>[C-2-1] MUST not allow any other userspace processes to run on it (except device drivers used by the application), but MAY allow some kernel processes to run as necessary.
</li>
</ul>
<h2 id="8_performance_and_power">
@@ -8489,16 +8773,32 @@
8.3. Power-Saving Modes
</h3>
<p>
- Android includes App Standby and Doze power-saving modes to optimize battery usage. <em>[SR] All Apps exempted from these modes are STRONGLY RECOMMENDED to be made visible to the end user.</em> [SR] The triggering, maintenance, wakeup algorithms and the use of global system settings of these power-saving modes are STRONGLY RECOMMENDED NOT to deviate from the Android Open Source Project.
+ If device implementations include features to improve device power management that are included in AOSP or extend the features that are included in AOSP, they:
</p>
+ <ul>
+ <li>[C-1-1] MUST NOT deviate from the AOSP implementation for the triggering, maintenance, wakeup algorithms and the use of global system settings of App Standby and Doze power-saving modes.
+ </li>
+ <li>[C-1-2] MUST NOT deviate from the AOSP implementation for the use of global settings to manage the throttling of jobs, alarm and network for apps in each bucket for App standby.
+ </li>
+ <li>[C-1-3] MUST NOT deviate from the AOSP implementation for the number of the <a href="https://developer.android.com/topic/performance/appstandby">App Standby Buckets</a> used for App Standby.
+ </li>
+ <li>[C-1-4] MUST implement <a href="https://developer.android.com/topic/performance/appstandby">App Standby Buckets</a> and Doze as described in <a href="https://source.android.com/devices/tech/power/mgmt">Power Management</a>.
+ </li>
+ <li>[C-1-5] MUST return <code>true</code> for <a href="https://developer.android.com/reference/android/os/PowerManager#isPowerSaveMode%28%29"><code>PowerManager.isPowerSaveMode()</code></a> when the device is on power save mode.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to provide user affordance to enable and disable the battery saver feature.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to provide user affordance to display all Apps that are exempted from App Standby and Doze power-saving modes.
+ </li>
+ </ul>
<p>
In addition to the power-saving modes, Android device implementations MAY implement any or all of the 4 sleeping power states as defined by the Advanced Configuration and Power Interface (ACPI).
</p>
<p>
- If device implementations implements S3 and S4 power states as defined by the ACPI, they:
+ If device implementations implement S3 and S4 power states as defined by the ACPI, they:
</p>
<ul>
- <li>[C-1-1] MUST only enter these states when closing a lid that is physically part of the device.
+ <li>[C-1-1] MUST enter these states only after the user has taken an explicit action to put the device in an inactive state (e.g. by closing a lid that is physically part of the device or turning off a vehicle or television) and before the user re-activates the device (e.g. by opening the lid or turning the vehicle or television back on).
</li>
</ul>
<h3 id="8_4_power_consumption_accounting">
@@ -8628,24 +8928,28 @@
<li>[C-0-4] MUST have one and only one implementation of both user interfaces.
</li>
<li>[C-0-5] MUST NOT grant any runtime permissions to preinstalled apps unless:
+ <ul>
+ <li>The user's consent can be obtained before the application uses it.
+ </li>
+ <li>The runtime permissions are associated with an intent pattern for which the preinstalled application is set as the default handler.
+ </li>
+ </ul>
</li>
- <li>the user's consent can be obtained before the application uses it
- </li>
- <li>the runtime permissions are associated with an intent pattern for which the preinstalled application is set as the default handler
+ <li>[C-0-6] MUST grant the <code>android.permission.RECOVER_KEYSTORE</code> permission only to system apps that register a properly secured Recovery Agent. A properly secured Recovery Agent is defined as an on-device software agent that synchronizes with an off-device remote storage, that is equipped with secure hardware with protection equivalent or stronger than what is described in <a href="https://developer.android.com/preview/features/security/ckv-whitepaper.html">Google Cloud Key Vault Service</a> to prevent brute-force attacks on the lockscreen knowledge factor.
</li>
</ul>
<p>
If device implementations include a pre-installed app or wish to allow third-party apps to access the usage statistics, they:
</p>
<ul>
- <li>[C-1-1] are STRONGLY RECOMMENDED provide user-accessible mechanism to grant or revoke access to the usage stats in response to the <a href="https://developer.android.com/reference/android/provider/Settings.html#ACTION&lowbar;USAGE&lowbar;ACCESS&lowbar;SETTINGS"><code>android.settings.ACTION_USAGE_ACCESS_SETTINGS</code></a> intent for apps that declare the <code>android.permission.PACKAGE_USAGE_STATS</code> permission.
+ <li>[SR] are STRONGLY RECOMMENDED provide user-accessible mechanism to grant or revoke access to the usage stats in response to the <a href="https://developer.android.com/reference/android/provider/Settings.html#ACTION&lowbar;USAGE&lowbar;ACCESS&lowbar;SETTINGS"><code>android.settings.ACTION_USAGE_ACCESS_SETTINGS</code></a> intent for apps that declare the <code>android.permission.PACKAGE_USAGE_STATS</code> permission.
</li>
</ul>
<p>
If device implementations intend to disallow any apps, including pre-installed apps, from accessing the usage statistics, they:
</p>
<ul>
- <li>[C-2-1] MUST still have an activity that handles the <a href="https://developer.android.com/reference/android/provider/Settings.html#ACTION&lowbar;USAGE&lowbar;ACCESS&lowbar;SETTINGS"><code>android.settings.ACTION_USAGE_ACCESS_SETTINGS</code></a> intent pattern but MUST implement it as a no-op, that is to have an equivalent behavior as when the user is declined for access.
+ <li>[C-1-1] MUST still have an activity that handles the <a href="https://developer.android.com/reference/android/provider/Settings.html#ACTION&lowbar;USAGE&lowbar;ACCESS&lowbar;SETTINGS"><code>android.settings.ACTION_USAGE_ACCESS_SETTINGS</code></a> intent pattern but MUST implement it as a no-op, that is to have an equivalent behavior as when the user is declined for access.
</li>
</ul>
<h3 id="9_2_uid_and_process_isolation">
@@ -8758,7 +9062,7 @@
</li>
<li>[C-1-3] MUST have separate and isolated shared application storage (a.k.a. <code>/sdcard</code>) directories for each user instance.
</li>
- <li>[C-1-4] MUST ensure that applications owned by and running on behalf a given user cannot list, read, or write to the files owned by any other user, even if the data of both users are stored on the same volume or filesystem.
+ <li>[C-1-4] MUST ensure that applications owned by and running on behalf of a given user cannot list, read, or write to the files owned by any other user, even if the data of both users are stored on the same volume or filesystem.
</li>
<li>[C-1-5] MUST encrypt the contents of the SD card when multiuser is enabled using a key stored only on non-removable media accessible only to the system if device implementations use removable media for the external storage APIs. As this will make the media unreadable by a host PC, device implementations will be required to switch to MTP or a similar system to provide host PCs with access to the current user’s data.
</li>
@@ -8790,10 +9094,13 @@
<li>[C-1-1] MUST warn users before sending a SMS message to numbers identified by regular expressions defined in <code>/data/misc/sms/codes.xml</code> file in the device. The upstream Android Open Source Project provides an implementation that satisfies this requirement.
</li>
</ul>
- <h3 id="9_7_kernel_security_features">
- 9.7. Kernel Security Features
+ <h3 id="9_7_security_features">
+ 9.7. Security Features
</h3>
<p>
+ Device implementations MUST ensure compliance with security features in both the kernel and platform as described below.
+ </p>
+ <p>
The Android Sandbox includes features that use the Security-Enhanced Linux (SELinux) mandatory access control (MAC) system, seccomp sandboxing, and other security features in the Linux kernel. Device implementations:
</p>
<ul>
@@ -8818,14 +9125,16 @@
</li>
<li>[C-0-8] MUST implement strict kernel memory protections where executable code is read-only, read-only data is non-executable and non-writable, and writable data is non-executable (e.g. <code>CONFIG_DEBUG_RODATA</code> or <code>CONFIG_STRICT_KERNEL_RWX</code>).
</li>
+ <li>[C-0-9] MUST implement static and dynamic object size bounds checking of copies between user-space and kernel-space (e.g. <code>CONFIG_HARDENED_USERCOPY</code>) on devices originally shipping with API level 28 or higher.
+ </li>
+ <li>[C-0-10] MUST NOT execute user-space memory when executing in the kernel mode (e.g. hardware PXN, or emulated via <code>CONFIG_CPU_SW_DOMAIN_PAN</code> or <code>CONFIG_ARM64_SW_TTBR0_PAN</code>) on devices originally shipping with API level 28 or higher.
+ </li>
+ <li>[C-0-11] MUST NOT read or write user-space memory in the kernel outside of normal usercopy access APIs (e.g. hardware PAN, or emulated via <code>CONFIG_CPU_SW_DOMAIN_PAN</code> or <code>CONFIG_ARM64_SW_TTBR0_PAN</code>) on devices originally shipping with API level 28 or higher.
+ </li>
+ <li>[C-0-12] MUST implement kernel page table isolation on all devices originally shipping with API level 28 or higher (e.g. <code>CONFIG_PAGE_TABLE_ISOLATION</code> or `CONFIG_UNMAP_KERNEL_AT_EL0).
+ </li>
<li>[SR] STRONGLY RECOMMENDED to keep kernel data which is written only during initialization marked read-only after initialization (e.g. <code>__ro_after_init</code>).
</li>
- <li>[SR} STRONGLY RECOMMENDED to implement static and dynamic object size bounds checking of copies between user-space and kernel-space (e.g. <code>CONFIG_HARDENED_USERCOPY</code>).
- </li>
- <li>[SR] STRONGLY RECOMMENDED to never execute user-space memory when running in the kernel (e.g. hardware PXN, or emulated via <code>CONFIG_CPU_SW_DOMAIN_PAN</code> or <code>CONFIG_ARM64_SW_TTBR0_PAN</code>).
- </li>
- <li>[SR] STRONGLY RECOMMENDED to never read or write user-space memory in the kernel outside of normal usercopy access APIs (e.g. hardware PAN, or emulated via <code>CONFIG_CPU_SW_DOMAIN_PAN</code> or <code>CONFIG_ARM64_SW_TTBR0_PAN</code>).
- </li>
<li>[SR] STRONGLY RECOMMENDED to randomize the layout of the kernel code and memory, and to avoid exposures that would compromise the randomization (e.g. <code>CONFIG_RANDOMIZE_BASE</code> with bootloader entropy via the <a href="https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/chosen.txt"><code>/chosen/kaslr-seed Device Tree node</code></a> or <a href="https://docs.microsoft.com/en-us/windows-hardware/drivers/bringup/efi-rng-protocol"><code>EFI_RNG_PROTOCOL</code></a>).
</li>
</ul>
@@ -8841,6 +9150,8 @@
</li>
<li>[C-1-4] MUST NOT modify, omit, or replace the neverallow rules present within the system/sepolicy folder provided in the upstream Android Open Source Project (AOSP) and the policy MUST compile with all neverallow rules present, for both AOSP SELinux domains as well as device/vendor specific domains.
</li>
+ <li>[C-1-5] MUST run third-party applications targeting API level 28 or higher in per-application SELinux sandboxes with per-app SELinux restrictions on each application's private data directory.
+ </li>
<li>SHOULD retain the default SELinux policy provided in the system/sepolicy folder of the upstream Android Open Source Project and only further add to this policy for their own device-specific configuration.
</li>
</ul>
@@ -8848,7 +9159,19 @@
If device implementations use kernel other than Linux, they:
</p>
<ul>
- <li>[C-2-1] MUST use an mandatory access control system that is equivalent to SELinux.
+ <li>[C-2-1] MUST use a mandatory access control system that is equivalent to SELinux.
+ </li>
+ </ul>
+ <p>
+ Android contains multiple defense-in-depth features that are integral to device security.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-SR] Are STRONGLY RECOMMENDED not to disable Control-Flow Integrity (CFI) or Integer Overflow Sanitization (IntSan) on components that have it enabled.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to enable both CFI and IntSan for any additional security-sensitive userspace components as explained in <a href="https://source.android.com/devices/tech/debug/cfi">CFI</a> and <a href="https://source.android.com/devices/tech/debug/intsan">IntSan</a>.
</li>
</ul>
<h3 id="9_8_privacy">
@@ -8864,15 +9187,34 @@
Device implementations:
</p>
<ul>
- <li>[C-1-1] MUST keep a reasonable retention period of such user history.
+ <li>[C-0-1] MUST keep a reasonable retention period of such user history.
</li>
<li>[SR] Are STRONGLY RECOMMENDED to keep the 14 days retention period as configured by default in the AOSP implementation.
</li>
</ul>
+ <p>
+ Android stores the system events using the <a href="https://developer.android.com/reference/android/util/StatsLog.html"><code>StatsLog</code></a> identifiers, and manages such history via the <code>StatsManager</code> and the <code>IncidentManager</code> System API.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-2] MUST only include the fields marked with <code>DEST_AUTOMATIC</code> in the incident report created by the System API class <code>IncidentManager</code>.
+ </li>
+ <li>[C-0-3] MUST not use the system event identifiers to log any other event than what is described in the <a href="https://developer.android.com/reference/android/util/StatsLog.html"><code>StatsLog</code></a> SDK documents. If additional system events are logged, they MAY use a different atom identifier in the range between 100,000 and 200,000.
+ </li>
+ </ul>
<h4 id="9_8_2_recording">
9.8.2. Recording
</h4>
<p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST NOT preload or distribute software components out-of-box that send the user's private information (e.g. keystrokes, text displayed on the screen) off the device without the user's consent or clear ongoing notifications.
+ </li>
+ </ul>
+ <p>
If device implementations include functionality in the system that captures the contents displayed on the screen and/or records the audio stream played on the device, they:
</p>
<ul>
@@ -8941,25 +9283,22 @@
9.9. Data Storage Encryption
</h3>
<p>
- If device implementations support a secure lock screen as described in <a href="#9_11_1_secure_lock_screen">section 9.11.1</a>, they:
+ If Advanced Encryption Standard (AES) crypto performance, measured with the most performant AES technology available on the device (e.g. the ARM Cryptography Extensions), is above 50 MiB/sec, device implementations:
</p>
<ul>
- <li>[C-1-1] MUST support data storage encryption of the application private data (<code>/data partition</code>), as well as the application shared storage partition (<code>/sdcard partition</code>) if it is a permanent, non-removable part of the device.
+ <li>[C-1-1] MUST support data storage encryption of the application private data (<code>/data</code> partition), as well as the application shared storage partition (<code>/sdcard</code> partition) if it is a permanent, non-removable part of the device, except for device implementations that are typically shared (e.g. Television).
+ </li>
+ <li>[C-1-2] MUST enable the data storage encryption by default at the time the user has completed the out-of-box setup experience, except for device implementations that are typically shared (e.g. Television).
</li>
</ul>
<p>
- If device implementations support a secure lock screen as described in <a href="#9_11_1_secure_lock_screen">section 9.11.1</a> and support data storage encryption with Advanced Encryption Standard (AES) crypto performance above 50MiB/sec, they:
+ If device implementations are already launched on an earlier Android version and cannot meet the requirement through a system software update, they MAY be exempted from the above requirements.
+ </p>
+ <p>
+ Device implementations:
</p>
<ul>
- <li>
- <p>
- [C-2-1] MUST enable the data storage encryption by default at the time the user has completed the out-of-box setup experience. If device implementations are already launched on an earlier Android version with encryption disabled by default, such a device cannot meet the requirement through a system software update and thus MAY be exempted.
- </p>
- </li>
- <li>
- <p>
- SHOULD meet the above data storage encryption requirement via implementing <a href="https://source.android.com/security/encryption/file-based.html">File Based Encryption</a> (FBE).
- </p>
+ <li>SHOULD meet the above data storage encryption requirement via implementing <a href="https://source.android.com/security/encryption/file-based.html">File Based Encryption</a> (FBE).
</li>
</ul>
<h4 id="9_9_1_direct_boot">
@@ -8991,15 +9330,15 @@
</li>
<li>[C-1-2] MUST only allow access to Credential Encrypted (CE) storage after the user has unlocked the device by supplying their credentials (eg. passcode, pin, pattern or fingerprint) and the <code>ACTION_USER_UNLOCKED</code> message is broadcasted.
</li>
- <li>[C-1-3] MUST NOT offer any method to unlock the CE protected storage without the user-supplied credentials.
+ <li>[C-1-3] MUST NOT offer any method to unlock the CE protected storage without either the user-supplied credentials or a registered escrow key.
</li>
<li>[C-1-4] MUST support Verified Boot and ensure that DE keys are cryptographically bound to the device's hardware root of trust.
</li>
- <li>[C-1-5] MUST support encrypting file contents using AES with a key length of 256-bits in XTS mode.
+ <li>[C-1-5] MUST support encrypting file contents using AES-256-XTS. AES-256-XTS refers to the Advanced Encryption Standard with a 256-bit key length, operated in XTS mode. The full length of the XTS key is 512 bits.
</li>
<li>
<p>
- [C-1-6] MUST support encrypting file name using AES with a key length of 256-bits in CBC-CTS mode.
+ [C-1-6] MUST support encrypting file names using AES-256 in CBC-CTS mode.
</p>
</li>
<li>
@@ -9023,10 +9362,20 @@
</li>
<li>
<p>
+ [C-1-11] MUST use the mandatorily supported ciphers, key lengths and modes by default.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-SR] Are STRONGLY RECOMMENDED to encrypt file system metadata, such as file sizes, ownership, modes, and Extended attributes (xattrs), with a key cryptographically bound to the device's hardware root of trust.
+ </p>
+ </li>
+ <li>
+ <p>
SHOULD make preloaded essential apps (e.g. Alarm, Phone, Messenger) Direct Boot aware.
</p>
</li>
- <li>MAY support alternative ciphers, key lengths and modes for file content and file name encryption, but MUST use the mandatorily supported ciphers, key lengths and modes by default.
+ <li>MAY support alternative ciphers, key lengths and modes for file content and file name encryption.
</li>
</ul>
<p>
@@ -9039,7 +9388,7 @@
If device implementations support <a href="http://source.android.com/devices/tech/security/encryption/index.html">full disk encryption</a> (FDE), they:
</p>
<ul>
- <li>[C-1-1] MUST use AES with a key of 128-bits (or greater) and a mode designed for storage (for example, AES-XTS, AES-CBC-ESSIV).
+ <li>[C-1-1] MUST use AES in a mode designed for storage (for example, XTS or CBC-ESSIV), and with a cipher key length of 128 bits or greater.
</li>
<li>[C-1-2] MUST use a default passcode to wrap the encryption key and MUST NOT write the encryption key to storage at any time without being encrypted.
</li>
@@ -9047,7 +9396,7 @@
</li>
<li>[C-1-4] The above default password stretching algorithm MUST be cryptographically bound to that keystore when the user has not specified a lock screen credentials or has disabled use of the passcode for encryption and the device provides a hardware-backed keystore.
</li>
- <li>[C-1-5] MUST NOT send encryption key off the the device (even when wrapped with the user passcode and/or hardware bound key).
+ <li>[C-1-5] MUST NOT send encryption key off the device (even when wrapped with the user passcode and/or hardware bound key).
</li>
</ul>
<p>
@@ -9057,14 +9406,25 @@
9.10. Device Integrity
</h3>
<p>
- The following requirements ensures there is transparancy to the status of the device integrity. Device implementations:
+ The following requirements ensures there is transparency to the status of the device integrity. Device implementations:
</p>
<ul>
- <li>[C-0-1] MUST correctly report through the System API method <code>PersistentDataBlockManager.getFlashLockState()</code> whether their bootloader state permits flashing of the system image. The <code>FLASH_LOCK_UNKNOWN</code> state is reserved for device implementations upgrading from an earlier version of Android where this new system API method did not exist.
+ <li>
+ <p>
+ [C-0-1] MUST correctly report through the System API method <code>PersistentDataBlockManager.getFlashLockState()</code> whether their bootloader state permits flashing of the system image. The <code>FLASH_LOCK_UNKNOWN</code> state is reserved for device implementations upgrading from an earlier version of Android where this new system API method did not exist.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-2] MUST support Verified Boot for device integrity.
+ </p>
</li>
</ul>
<p>
- Verified boot is a feature that guarantees the integrity of the device software. If a device implementation supports the feature, it:
+ If device implementations are already launched without supporting Verified Boot on an earlier version of Android and can not add support for this feature with a system software update, they MAY be exempted from the requirement.
+ </p>
+ <p>
+ Verified Boot is a feature that guarantees the integrity of the device software. If device implementations support the feature, they:
</p>
<ul>
<li>[C-1-1] MUST declare the platform feature flag <code>android.software.verified_boot</code>.
@@ -9079,32 +9439,47 @@
</li>
<li>[C-1-6] MUST NOT allow boot to complete when system verification fails, unless the user consents to attempt booting anyway, in which case the data from any non-verified storage blocks MUST not be used.
</li>
- <li>[C-1-7] MUST NOT allow verified partitions on the device to be modified unless the user has explicitly unlocked the boot loader.
+ <li>[C-1-7] MUST NOT allow verified partitions on the device to be modified unless the user has explicitly unlocked the bootloader.
</li>
- <li>[SR] If there are multiple discrete chips in the device (e.g. radio, specialized image processor), the boot process of each of those chips is STRONGLY RECOMMENDED to verify every stage upon booting.
+ <li>[C-SR] If there are multiple discrete chips in the device (e.g. radio, specialized image processor), the boot process of each of those chips is STRONGLY RECOMMENDED to verify every stage upon booting.
</li>
- <li>[SR] STRONGLY RECOMMENDED to use tamper-evident storage: for when the bootloader is unlocked. Tamper-evident storage means that the boot loader can detect if the storage has been tampered with from inside the HLOS (High Level Operating System).
+ <li>[C-1-8] MUST use tamper-evident storage: for storing whether the bootloader is unlocked. Tamper-evident storage means that the bootloader can detect if the storage has been tampered with from inside Android.
</li>
- <li>[SR] STRONGLY RECOMMENDED to prompt the user, while using the device, and require physical confirmation before allowing a transition from boot loader locked mode to boot loader unlocked mode.
+ <li>[C-1-9] MUST prompt the user, while using the device, and require physical confirmation before allowing a transition from bootloader locked mode to bootloader unlocked mode.
</li>
- <li>[SR] STRONGLY RECOMMENDED to implement rollback protection for the HLOS (e.g. boot, system partitions) and to use tamper-evident storage for storing the metadata used for determining the minimum allowable OS version.
+ <li>[C-1-10] MUST implement rollback protection for partitions used by Android (e.g. boot, system partitions) and use tamper-evident storage for storing the metadata used for determining the minimum allowable OS version.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to verify all privileged app APK files with a chain of trust rooted in <code>/system</code>, which is protected by Verified Boot.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to verify any executable artifacts loaded by a privileged app from outside its APK file (such as dynamically loaded code or compiled code) before executing them or STRONGLY RECOMMENDED not to execute them at all.
</li>
<li>SHOULD implement rollback protection for any component with persistent firmware (e.g. modem, camera) and SHOULD use tamper-evident storage for storing the metadata used for determining the minimum allowable version.
</li>
</ul>
<p>
- The upstream Android Open Source Project provides a preferred implementation of this feature in the <a href="http://android.googlesource.com/platform/external/avb/"><code>external/avb/</code></a> repository, which can be integrated into the boot loader used for loading Android.
+ If device implementations are already launched without supporting C-1-8 through C-1-10 on an earlier version of Android and can not add support for these requirements with a system software update, they MAY be exempted from the requirements.
</p>
<p>
- If device implementations report the feature flag <a href="https://developer.android.com/reference/android/content/pm/PackageManager.html#FEATURE_RAM_NORMAL"><code>android.hardware.ram.normal</code></a> , they:
+ The upstream Android Open Source Project provides a preferred implementation of this feature in the <a href="http://android.googlesource.com/platform/external/avb/"><code>external/avb/</code></a> repository, which can be integrated into the bootloader used for loading Android.
+ </p>
+ <p>
+ Device implementations:
</p>
<ul>
- <li>[C-2-1] MUST support verified boot for device integrity.
+ <li>[C-R] Are RECOMMENDED to support the <a href="https://developer.android.com/preview/features/security.html#user-confirmation">Android Protected Confirmation API</a>.
</li>
</ul>
<p>
- If a device implementation is already launched without supporting verified boot on an earlier version of Android, such a device can not add support for this feature with a system software update and thus are exempted from the requirement.
+ If device implementations support the Android Protected Confirmation API they:
</p>
+ <ul>
+ <li>[C-3-1] MUST report <code>true</code> for the <a href="https://developer.android.com/reference/android/security/ConfirmationPrompt.html#isSupported%28android.content.Context%29"><code>ConfirmationPrompt.isSupported()</code></a> API.
+ </li>
+ <li>[C-3-2] MUST ensure that secure hardware takes full control of display in such a way that Android OS cannot block it without detection by the secure hardware.
+ </li>
+ <li>[C-3-3] MUST ensure that secure hardware takes full control of the touch screen.
+ </li>
+ </ul>
<h3 id="9_11_keys_and_credentials">
9.11. Keys and Credentials
</h3>
@@ -9112,7 +9487,7 @@
The <a href="https://developer.android.com/training/articles/keystore.html">Android Keystore System</a> allows app developers to store cryptographic keys in a container and use them in cryptographic operations through the <a href="https://developer.android.com/reference/android/security/KeyChain.html">KeyChain API</a> or the <a href="https://developer.android.com/reference/java/security/KeyStore.html">Keystore API</a>. Device implementations:
</p>
<ul>
- <li>[C-0-1] MUST at least allow more than 8,192 keys to be imported.
+ <li>[C-0-1] MUST allow at least 8,192 keys to be imported or generated.
</li>
<li>[C-0-2] The lock screen authentication MUST rate-limit attempts and MUST have an exponential backoff algorithm. Beyond 150 failed attempts, the delay MUST be at least 24 hours per attempt.
</li>
@@ -9123,7 +9498,7 @@
When the device implementation supports a secure lock screen, it:
</p>
<ul>
- <li>[C-1-1] MUST back up the keystore implementation with secure hardware.
+ <li>[C-1-1] MUST back up the keystore implementation with an isolated execution environment.
</li>
<li>[C-1-2] MUST have implementations of RSA, AES, ECDSA and HMAC cryptographic algorithms and MD5, SHA1, and SHA-2 family hash functions to properly support the Android Keystore system's supported algorithms in an area that is securely isolated from the code running on the kernel and above. Secure isolation MUST block all potential mechanisms by which kernel or userspace code might access the internal state of the isolated environment, including DMA. The upstream Android Open Source Project (AOSP) meets this requirement by using the <a href="https://source.android.com/security/trusty/">Trusty</a> implementation, but another ARM TrustZone-based solution or a third-party reviewed secure implementation of a proper hypervisor-based isolation are alternative options.
</li>
@@ -9131,32 +9506,38 @@
</li>
<li>[C-1-4] MUST support key attestation where the attestation signing key is protected by secure hardware and signing is performed in secure hardware. The attestation signing keys MUST be shared across large enough number of devices to prevent the keys from being used as device identifiers. One way of meeting this requirement is to share the same attestation key unless at least 100,000 units of a given SKU are produced. If more than 100,000 units of an SKU are produced, a different key MAY be used for each 100,000 units.
</li>
+ <li>[C-1-5] MUST allow the user to choose the Sleep timeout for transition from the unlocked to the locked state, with a minimum allowable timeout up to 15 seconds.
+ </li>
</ul>
<p>
- Note that if a device implementation is already launched on an earlier Android version, such a device is exempted from the requirement to have a hardware-backed keystore, unless it declares the <code>android.hardware.fingerprint</code> feature which requires a hardware-backed keystore.
+ Note that if a device implementation is already launched on an earlier Android version, such a device is exempted from the requirement to have a keystore backed by an isolated execution environment and support the key attestation, unless it declares the <code>android.hardware.fingerprint</code> feature which requires a keystore backed by an isolated execution environment.
</p>
<h4 id="9_11_1_secure_lock_screen">
9.11.1. Secure Lock Screen
</h4>
<p>
- If device implementations have a secure lock screen and include one or more trust agent, which implements the <code>TrustAgentService</code> System API, then they:
+ The AOSP implementation follows a tiered authentication model where a knowledge-factory based primary authentication can be backed by either a secondary strong biometric, or by weaker tertiary modalities.
+ </p>
+ <p>
+ Device implementations:
</p>
<ul>
- <li>[C-1-1] MUST indicate the user in the Settings and Lock screen user interface of situations where either the screen auto-lock is deferred or the screen lock can be unlocked by the trust agent. The AOSP meets the requirement by showing a text description for the "Automatically lock setting" and "Power button instantly locks setting" menus and a distinguishable icon on the lock screen.
- </li>
- <li>[C-1-2] MUST respect and fully implement all trust agent APIs in the <code>DevicePolicyManager</code> class, such as the <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#KEYGUARD&lowbarDISABLE&lowbarTRUST&lowbarAGENTS"><code>KEYGUARD_DISABLE_TRUST_AGENTS</code></a> constant.
- </li>
- <li>[C-1-3] MUST NOT fully implement the <code>TrustAgentService.addEscrowToken()</code> function on a device that is used as the primary personal device (e.g. handheld) but MAY fully implement the function on device implementations typically shared.
- </li>
- <li>[C-1-4] MUST encrypt the tokens added by <code>TrustAgentService.addEscrowToken()</code> before storing them on the device.
- </li>
- <li>[C-1-5] MUST NOT store the encryption key on the device.
- </li>
- <li>[C-1-6] MUST inform the user about the security implications before enabling the escrow token to decrypt the data storage.
+ <li>[C-SR] Are STRONGLY RECOMMENDED to set only one of the following as the primary authentication method:
+ <ul>
+ <li>A numerical PIN
+ </li>
+ <li>An alphanumeric password
+ </li>
+ <li>A swipe pattern on a grid of exactly 3x3 dots
+ </li>
+ </ul>
</li>
</ul>
<p>
- If device implementations add or modify the authentication methods to unlock the lock screen, then for such an authentication method to be treated as a secure way to lock the screen, they:
+ Note that the above authentication methods are referred as the recommended primary authentication methods in this document.
+ </p>
+ <p>
+ If device implementations add or modify the recommended primary authentication methods and use a new authentication method as a secure way to lock the screen, the new authentication method:
</p>
<ul>
<li>[C-2-1] MUST be the user authentication method as described in <a href="https://developer.android.com/training/articles/keystore.html#UserAuthentication">Requiring User Authentication For Key Use</a>.
@@ -9165,62 +9546,180 @@
</li>
</ul>
<p>
- If device implementations add or modify the authentication methods to unlock the lock screen if based on a known secret then for such an authentication method to be treated as a secure way to lock the screen, they:
+ If device implementations add or modify the authentication methods to unlock the lock screen if based on a known secret and use a new authentication method to be treated as a secure way to lock the screen:
</p>
<ul>
<li>[C-3-1] The entropy of the shortest allowed length of inputs MUST be greater than 10 bits.
</li>
<li>[C-3-2] The maximum entropy of all possible inputs MUST be greater than 18 bits.
</li>
- <li>[C-3-3] MUST not replace any of the existing authentication methods (PIN,pattern, password) implemented and provided in AOSP.
+ <li>[C-3-3] The new authentication method MUST NOT replace any of the recommended primary authentication methods (i.e. PIN, pattern, password) implemented and provided in AOSP.
</li>
- <li>[C-3-4] MUST be disabled when the Device Policy Controller (DPC) application has set the password quality policy via the <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordQuality%28android.content.ComponentName,%20int%29"><code>DevicePolicyManager.setPasswordQuality()</code></a> method with a more restrictive quality constant than <code>PASSWORD_QUALITY_SOMETHING</code>.
+ <li>[C-3-4] The new authentication method MUST be disabled when the Device Policy Controller (DPC) application has set the password quality policy via the <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordQuality%28android.content.ComponentName,%20int%29"><code>DevicePolicyManager.setPasswordQuality()</code></a> method with a more restrictive quality constant than <code>PASSWORD_QUALITY_SOMETHING</code>.
</li>
</ul>
<p>
- If device implementations add or modify the authentication methods to unlock the lock screen if based on a physical token or the location, then for such an authentication method to be treated as a secure way to lock the screen, they:
+ If device implementations add or modify the recommended primary authentication methods to unlock the lock screen and use a new authentication method that is based on biometrics to be treated as a secure way to lock the screen, the new method:
</p>
<ul>
- <li>[C-4-1] MUST have a fall-back mechanism to use one of the primary authentication methods which is based on a known secret and meets the requirements to be treated as a secure lock screen.
+ <li>[C-4-1] MUST meet all requirements described in <a href="#7_3_10_2_other_biometric_sensors">section 7.3.10.2</a>.
</li>
- <li>[C-4-2] MUST be disabled and only allow the primary authentication to unlock the screen when the Device Policy Controller (DPC) application has set the policy with either the <a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setKeyguardDisabledFeatures%28android.content.ComponentName,%20int%29"><code>DevicePolicyManager.setKeyguardDisabledFeatures(KEYGUARD_DISABLE_TRUST_AGENTS)</code></a> method or the <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordQuality%28android.content.ComponentName,%20int%29"><code>DevicePolicyManager.setPasswordQuality()</code></a> method with a more restrictive quality constant than <code>PASSWORD_QUALITY_UNSPECIFIED</code>.
+ <li>[C-4-2] MUST have a fall-back mechanism to use one of the recommended primary authentication methods which is based on a known secret.
</li>
- <li>[C-4-3] The user MUST be challenged for the primary authentication (e.g.PIN, pattern, password) at least once every 72 hours or less.
+ <li>[C-4-3] MUST be disabled and only allow the recommended primary authentication to unlock the screen when the Device Policy Controller (DPC) application has set the keguard feature policy by calling the method <a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setKeyguardDisabledFeatures%28android.content.ComponentName,%20int%29"><code>DevicePolicyManager.setKeyguardDisabledFeatures()</code></a> , with any of the associated biometric flags (i.e. <code>KEYGUARD_DISABLE_BIOMETRICS</code>, <code>KEYGUARD_DISABLE_FINGERPRINT</code>, <code>KEYGUARD_DISABLE_FACE</code>, or <code>KEYGUARD_DISABLE_IRIS</code>).
+ </li>
+ <li>[C-4-4] MUST challenge the user for the recommended primary authentication (e.g. PIN, pattern, password) at least once every 72 hours or less.
+ </li>
+ <li>[C-4-5] MUST have a false acceptance rate that is equal or stronger than what is required for a fingerprint sensor as described in section <a href="#7_3_10_biometric_sensors">section 7.3.10</a>, or otherwise MUST be disabled and only allow the recommended primary authentication to unlock the screen when the Device Policy Controller (DPC) application has set the password quality policy via the <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordQuality%28android.content.ComponentName,%20int%29"><code>DevicePolicyManager.setPasswordQuality()</code></a> method with a more restrictive quality constant than <code>PASSWORD_QUALITY_BIOMETRIC_WEAK</code>.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to have spoof and imposter acceptance rates that are equal to or stronger than what is required for a fingerprint sensor as described in <a href="#7_3_10_biometric_sensors">section 7.3.10</a>.
+ </li>
+ <li>[C-4-6] MUST have a secure processing pipeline such that an operating system or kernel compromise cannot allow data to be directly injected to falsely authenticate as the user.
+ </li>
+ <li>[C-4-7] MUST be paired with an explicit confirm action (eg: a button press) to allow access to keystore keys if the application sets <code>true</code> for <a href="https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder.html#setUserAuthenticationRequired%28boolean%29"><code>KeyGenParameterSpec.Built.setUserAuthenticationRequired()</code></a> and the biometric is passive (e.g. face or iris where no explicit signal of intent exists).
+ </li>
+ <li>[C-SR] The confirm action for passive biometrics is STRONGLY RECOMMENDED to be secured such that an operating system or kernel compromise cannot spoof it. For example, this means that the confirm action based on a physical button is routed through an input-only general-purpose input/output (GPIO) pin of a secure element (SE) that cannot be driven by any other means than a physical button press.
</li>
</ul>
<p>
- If device implementations add or modify the authentication methods to unlock the lock screen based on biometrics, then for such an authentication method to be treated as a secure way to lock the screen, they:
+ If the biometric authentication methods do not meet the spoof and imposter acceptance rates as described in <a href="#7_3_10_biometric_sensors">section 7.3.10</a>:
</p>
<ul>
- <li>[C-5-1] MUST have a fall-back mechanism to use one of the primary authentication methods which is based on a known secret and meets the requirements to be treated as a secure lock screen.
+ <li>[C-5-1] The methods MUST be disabled if the Device Policy Controller (DPC) application has set the password quality policy via the <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordQuality%28android.content.ComponentName,%20int%29"><code>DevicePolicyManager.setPasswordQuality()</code></a> method with a more restrictive quality constant than <code>PASSWORD_QUALITY_BIOMETRIC_WEAK</code>.
</li>
- <li>[C-5-2] MUST be disabled and only allow the primary authentication to unlock the screen when the Device Policy Controller (DPC) application has set the keguard feature policy by calling the method <a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setKeyguardDisabledFeatures%28android.content.ComponentName,%20int%29"><code>DevicePolicyManager.setKeyguardDisabledFeatures(KEYGUARD_DISABLE_FINGERPRINT)</code></a>.
+ <li>[C-5-2] The user MUST be challenged for the recommended primary authentication (eg: PIN, pattern, password) after any 4-hour idle timeout period. The idle timeout period is reset after any successful confirmation of the device credentials.
</li>
- <li>[C-5-3] MUST have a false acceptance rate that is equal or stronger than what is required for a fingerprint sensor as described in section 7.3.10, or otherwise MUST be disabled and only allow the primary authentication to unlock the screen when the Device Policy Controller (DPC) application has set the password quality policy via the <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordQuality%28android.content.ComponentName,%20int%29"><code>DevicePolicyManager.setPasswordQuality()</code></a> method with a more restrictive quality constant than <code>PASSWORD_QUALITY_BIOMETRIC_WEAK</code>.
- </li>
- <li>[SR] Are STRONGLY RECOMMENDED to have spoof and imposter acceptance rates that are equal to or stronger than what is required for a fingerprint sensor as described in section 7.3.10.
+ <li>[C-5-3] The methods MUST NOT be treated as a secure lock screen, and MUST meet the requirements that start with C-8 in this section below.
</li>
</ul>
<p>
- If the spoof and imposter acceptance rates are not equal to or stronger than what is required for a fingerprint sensor as described in <a href="#7_3_10_fingerprint_sensor">section 7.3.10</a> and the Device Policy Controller (DPC) application has set the password quality policy via the <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordQuality%28android.content.ComponentName,%20int%29"><code>DevicePolicyManager.setPasswordQuality()</code></a> method with a more restrictive quality constant than <code>PASSWORD_QUALITY_BIOMETRIC_WEAK</code>, then:
+ If device implementations add or modify the authentication methods to unlock the lock screen and a new authentication method is based on a physical token or the location:
</p>
<ul>
- <li>[C-6-1] MUST disable these biometric methods and allow only the primary authentication to unlock the screen.
+ <li>[C-6-1] They MUST have a fall-back mechanism to use one of the recommended primary authentication methods which is based on a known secret and meet the requirements to be treated as a secure lock screen.
</li>
- <li>[C-6-2] MUST challenge the user for the primary authentication (e.g.PIN, pattern, password) at least once every 72 hours or less.
+ <li>[C-6-2] The new method MUST be disabled and only allow one of the recommended primary authentication methods to unlock the screen when the Device Policy Controller (DPC) application has set the policy with either the <a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setKeyguardDisabledFeatures%28android.content.ComponentName,%20int%29"><code>DevicePolicyManager.setKeyguardDisabledFeatures(KEYGUARD_DISABLE_TRUST_AGENTS)</code></a> method or the <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordQuality%28android.content.ComponentName,%20int%29"><code>DevicePolicyManager.setPasswordQuality()</code></a> method with a more restrictive quality constant than <code>PASSWORD_QUALITY_UNSPECIFIED</code>.
+ </li>
+ <li>[C-6-3] The user MUST be challenged for one of the recommended primary authentication methods (e.g.PIN, pattern, password) at least once every 72 hours or less.
+ </li>
+ <li>[C-6-4] The new method MUST NOT be treated as a secure lock screen and MUST follow the constraints listed in C-8 below.
</li>
</ul>
<p>
- If device implementations add or modify the authentication methods to unlock the lock screen and if such an authentication method will be used to unlock the keyguard, but will not be treated as a secure lock screen, then they:
+ If device implementations have a secure lock screen and include one or more trust agent, which implements the <code>TrustAgentService</code> System API, they:
</p>
<ul>
- <li>[C-7-1] MUST return <code>false</code> for both the <a href="http://developer.android.com/reference/android/app/KeyguardManager.html#isKeyguardSecure%28%29"><code>KeyguardManager.isKeyguardSecure()</code></a> and the <a href="https://developer.android.com/reference/android/app/KeyguardManager.html#isDeviceSecure%28%29"><code>KeyguardManager.isDeviceSecure()</code></a> methods.
+ <li>[C-7-1] MUST have clear indication in the settings menu and on the lock screen when device lock is deferred or can be unlocked by trust agent(s). For example, AOSP meets this requirement by showing a text description for the "Automatically lock setting" and "Power button instantly locks" in the settings menu and a distinguishable icon on the lock screen.
</li>
- <li>[C-7-2] MUST be disabled when the Device Policy Controller (DPC) application has set the password quality policy via the <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordQuality%28android.content.ComponentName,%20int%29"><code>DevicePolicyManager.setPasswordQuality()</code></a> method with a more restrictive quality constant than <code>PASSWORD_QUALITY_UNSPECIFIED</code>.
+ <li>[C-7-2] MUST respect and fully implement all trust agent APIs in the <code>DevicePolicyManager</code> class, such as the <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#KEYGUARD&lowbarDISABLE&lowbarTRUST&lowbarAGENTS"><code>KEYGUARD_DISABLE_TRUST_AGENTS</code></a> constant.
</li>
- <li>[C-7-3] MUST NOT reset the password expiration timers set by <a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordExpirationTimeout%28android.content.ComponentName,%20long%29"><code>DevicePolicyManager.setPasswordExpirationTimeout()</code></a>.
+ <li>[C-7-3] MUST NOT fully implement the <code>TrustAgentService.addEscrowToken()</code> function on a device that is used as a primary personal device (e.g. handheld) but MAY fully implement the function on device implementations that are typically shared (e.g. Android Television or Automotive device).
</li>
- <li>[C-7-4] MUST NOT authenticate access to keystores if the application has called <a href="https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder.html#setUserAuthenticationRequired%28boolean%29"><code>KeyGenParameterSpec.Builder.setUserAuthenticationRequired(true)</code></a>).
+ <li>[C-7-4] MUST encrypt all stored tokens added by <code>TrustAgentService.addEscrowToken()</code>.
+ </li>
+ <li>[C-7-5] MUST NOT store the encryption key on the same device where the key is used. For example, it is allowed for a key stored on a phone to unlock a user account on a TV.
+ </li>
+ <li>[C-7-6] MUST inform the user about the security implications before enabling the escrow token to decrypt the data storage.
+ </li>
+ <li>[C-7-7] MUST have a fall-back mechanism to use one of the recommended primary authentication methods.
+ </li>
+ <li>[C-7-8] The user MUST be challenged for one of the recommended primary authentication (eg: PIN, pattern, password) methods at least once every 72 hours or less.
+ </li>
+ <li>[C-7-9] The user MUST be challenged for one of the recommended primary authentication (eg: PIN, pattern, password) methods after any 4-hour idle timeout period. The idle timeout period is reset after any successful confirmation of the device credentials.
+ </li>
+ <li>[C-7-10] MUST NOT be treated as a secure lock screen and MUST follow the constraints listed in C-8 below.
+ </li>
+ </ul>
+ <p>
+ If device implementations add or modify the authentication methods to unlock the lock screen that is not a secure lock screen as described above, and use a new authentication method to unlock the keyguard:
+ </p>
+ <ul>
+ <li>[C-8-1] The new method MUST be disabled when the Device Policy Controller (DPC) application has set the password quality policy via the <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordQuality%28android.content.ComponentName,%20int%29"><code>DevicePolicyManager.setPasswordQuality()</code></a> method with a more restrictive quality constant than <code>PASSWORD_QUALITY_UNSPECIFIED</code>.
+ </li>
+ <li>[C-8-2] They MUST NOT reset the password expiration timers set by <a href="http://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#setPasswordExpirationTimeout%28android.content.ComponentName,%20long%29"><code>DevicePolicyManager.setPasswordExpirationTimeout()</code></a>.
+ </li>
+ <li>[C-8-3] They MUST NOT authenticate access to keystores when the application sets <code>true</code> for <a href="https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder.html#setUserAuthenticationRequired%28boolean%29"><code>KeyGenParameterSpec.Builder.setUserAuthenticationRequired()</code></a>).
+ </li>
+ </ul>
+ <h4 id="9_11_2_strongbox">
+ 9.11.2. StrongBox
+ </h4>
+ <p>
+ The <a href="https://developer.android.com/training/articles/keystore.html">Android Keystore System</a> allows app developers to store cryptographic keys in a dedicated secure processor as well as the isolated execution environment described above.
+ </p>
+ <p>
+ Device implementations:
+ </p>
+ <ul>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to support StrongBox.
+ </li>
+ </ul>
+ <p>
+ If device implementations support StrongBox, they:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-1-1] MUST declare <a href="https://developer.android.com/reference/kotlin/android/content/pm/PackageManager#FEATURE_STRONGBOX_KEYSTORE%3Akotlin.String">FEATURE_STRONGBOX_KEYSTORE</a>.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-2] MUST provide dedicated secure hardware that is used to back keystore and secure user authentication.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-3] MUST have a discrete CPU that shares no cache, DRAM, coprocessors or other core resources with the application processor (AP).
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-4] MUST ensure that any peripherals shared with the AP cannot alter StrongBox processing in any way, or obtain any information from the StrongBox. The AP MAY disable or block access to StrongBox.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-5] MUST have an internal clock with reasonable accuracy (+-10%) that is immune to manipulation by the AP.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-6] MUST have a true random number generator that produces uniformly-distributed and unpredictable output.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-7] MUST have tamper resistance, including resistance against physical penetration, and glitching.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-8] MUST have side-channel resistance, including resistance against leaking information via power, timing, electromagnetic radiation, and thermal radiation side channels.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-1-9] MUST have secure storage which ensures confidentiality, integrity, authenticity, consistency, and freshness of the contents. The storage MUST NOT be able to be read or altered, except as permitted by the StrongBox APIs.
+ </p>
+ </li>
+ <li>
+ <p>
+ To validate compliance with [C-1-3] through [C-1-9], device implementations:
+ </p>
+ <ul>
+ <li>[C-1-10] MUST include the hardware that is certified against the Secure IC Protection Profile <a href="https://www.commoncriteriaportal.org/files/ppfiles/pp0084b_pdf.pdf">BSI-CC-PP-0084-2014</a> or evaluated by a nationally accredited testing laboratory incorporating High attack potential vulnerability assessment according to the <a href="https://www.commoncriteriaportal.org/files/supdocs/CCDB-2013-05-002.pdf">Common Criteria Application of Attack Potential to Smartcards</a>.
+ </li>
+ <li>[C-1-11] MUST include the firmware that is evaluated by a nationally accredited testing laboratory incorporating High attack potential vulnerability assessment according to the <a href="https://www.commoncriteriaportal.org/files/supdocs/CCDB-2013-05-002.pdf">Common Criteria Application of Attack Potential to Smartcards</a>.
+ </li>
+ <li>[C-SR] Are STRONGLY RECOMMENDED to include the hardware that is evaluated using a Security Target, Evaluation Assurance Level (EAL) 5, augmented by AVA_VAN.5. EAL 5 certification will likely become a requirement in a future release.
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [C-SR] are STRONGLY RECOMMENDED to provide insider attack resistance (IAR), which means that an insider with access to firmware signing keys cannot produce firmware that causes the StrongBox to leak secrets, to bypass functional security requirements or otherwise enable access to sensitive user data. The recommended way to implement IAR is to allow firmware updates only when the primary user password is provided via the IAuthSecret HAL. IAR will likely become a requirement in a future release.
+ </p>
</li>
</ul>
<h3 id="9_12_data_deletion">
@@ -9289,59 +9788,125 @@
<p>
The data exchange can be secured by implementing security features below the Android framework layers to prevent malicious or unintentional interaction with these subsystems.
</p>
+ <h3 id="9_15_subscription_plans">
+ 9.15. Subscription Plans
+ </h3>
+ <p>
+ "Subscription plans" refer to the billing relationship plan details provided by a mobile carrier through <a href="https://developer.android.com/reference/android/telephony/SubscriptionManager.html#setSubscriptionPlans%28int,%20java.util.List%3Candroid.telephony.SubscriptionPlan%3E%29"><code>SubscriptionManager.setSubscriptionPlans()</code></a>.
+ </p>
+ <p>
+ All device implementations:
+ </p>
+ <ul>
+ <li>[C-0-1] MUST return subscription plans only to the mobile carrier app that has originally provided them.
+ </li>
+ <li>[C-0-2] MUST NOT remotely back up or upload subscription plans.
+ </li>
+ <li>[C-0-3] MUST only allow overrides, such as <a href="https://developer.android.com/reference/android/telephony/SubscriptionManager.html#setSubscriptionOverrideCongested%28int,%20boolean,%20long%29"><code>SubscriptionManager.setSubscriptionOverrideCongested()</code></a>, from the mobile carrier app currently providing valid subscription plans.
+ </li>
+ </ul>
<h2 id="10_software_compatibility_testing">
10. Software Compatibility Testing
</h2>
<p>
- Device implementations MUST pass all tests described in this section.
- </p>
- <p>
- However, note that no software test package is fully comprehensive. For this reason, device implementers are <strong>STRONGLY RECOMMENDED</strong> to make the minimum number of changes as possible to the reference and preferred implementation of Android available from the Android Open Source Project. This will minimize the risk of introducing bugs that create incompatibilities requiring rework and potential device updates.
+ Device implementations MUST pass all tests described in this section. However, note that no software test package is fully comprehensive. For this reason, device implementers are <strong>STRONGLY RECOMMENDED</strong> to make the minimum number of changes as possible to the reference and preferred implementation of Android available from the Android Open Source Project. This will minimize the risk of introducing bugs that create incompatibilities requiring rework and potential device updates.
</p>
<h3 id="10_1_compatibility_test_suite">
10.1. Compatibility Test Suite
</h3>
<p>
- Device implementations MUST pass the <a href="http://source.android.com/compatibility/index.html">Android Compatibility Test Suite (CTS)</a> available from the Android Open Source Project, using the final shipping software on the device. Additionally, device implementers SHOULD use the reference implementation in the Android Open Source tree as much as possible, and MUST ensure compatibility in cases of ambiguity in CTS and for any reimplementations of parts of the reference source code.
+ Device implementations:
+ </p>
+ <ul>
+ <li>
+ <p>
+ [C-0-1] MUST pass the <a href="http://source.android.com/compatibility/index.html">Android Compatibility Test Suite (CTS)</a> available from the Android Open Source Project, using the final shipping software on the device.
+ </p>
+ </li>
+ <li>
+ <p>
+ [C-0-2] MUST ensure compatibility in cases of ambiguity in CTS and for any reimplementations of parts of the reference source code.
+ </p>
+ </li>
+ </ul>
+ <p>
+ The CTS is designed to be run on an actual device. Like any software, the CTS may itself contain bugs. The CTS will be versioned independently of this Compatibility Definition, and multiple revisions of the CTS may be released for Android 9.
</p>
<p>
- The CTS is designed to be run on an actual device. Like any software, the CTS may itself contain bugs. The CTS will be versioned independently of this Compatibility Definition, and multiple revisions of the CTS may be released for Android 8.1. Device implementations MUST pass the latest CTS version available at the time the device software is completed.
+ Device implementations:
</p>
+ <ul>
+ <li>
+ <p>
+ [C-0-3] MUST pass the latest CTS version available at the time the device software is completed.
+ </p>
+ </li>
+ <li>
+ <p>
+ SHOULD use the reference implementation in the Android Open Source tree as much as possible.
+ </p>
+ </li>
+ </ul>
<h3 id="10_2_cts_verifier">
10.2. CTS Verifier
</h3>
<p>
- Device implementations MUST correctly execute all applicable cases in the CTS Verifier. The CTS Verifier is included with the Compatibility Test Suite, and is intended to be run by a human operator to test functionality that cannot be tested by an automated system, such as correct functioning of a camera and sensors.
+ The CTS Verifier is included with the Compatibility Test Suite, and is intended to be run by a human operator to test functionality that cannot be tested by an automated system, such as correct functioning of a camera and sensors.
</p>
<p>
- The CTS Verifier has tests for many kinds of hardware, including some hardware that is optional. Device implementations MUST pass all tests for hardware that they possess; for instance, if a device possesses an accelerometer, it MUST correctly execute the Accelerometer test case in the CTS Verifier. Test cases for features noted as optional by this Compatibility Definition Document MAY be skipped or omitted.
- </p>
- <p>
- Every device and every build MUST correctly run the CTS Verifier, as noted above. However, since many builds are very similar, device implementers are not expected to explicitly run the CTS Verifier on builds that differ only in trivial ways. Specifically, device implementations that differ from an implementation that has passed the CTS Verifier only by the set of included locales, branding, etc. MAY omit the CTS Verifier test.
- </p>
- <h2 id="11_updatable_software">
- 11. Updatable Software
- </h2>
- <p>
- Device implementations MUST include a mechanism to replace the entirety of the system software. The mechanism need not perform “live” upgrades—that is, a device restart MAY be required.
- </p>
- <p>
- Any method can be used, provided that it can replace the entirety of the software preinstalled on the device. For instance, any of the following approaches will satisfy this requirement:
+ Device implementations:
</p>
<ul>
- <li>“Over-the-air (OTA)” downloads with offline update via reboot.
- </li>
- <li>“Tethered” updates over USB from a host PC.
- </li>
- <li>“Offline” updates via a reboot and update from a file on removable storage.
+ <li>[C-0-1] MUST correctly execute all applicable cases in the CTS verifier.
</li>
</ul>
<p>
- However, if the device implementation includes support for an unmetered data connection such as 802.11 or Bluetooth PAN (Personal Area Network) profile, it MUST support OTA downloads with offline update via reboot.
+ The CTS Verifier has tests for many kinds of hardware, including some hardware that is optional.
</p>
<p>
- The update mechanism used MUST support updates without wiping user data. That is, the update mechanism MUST preserve application private data and application shared data. Note that the upstream Android software includes an update mechanism that satisfies this requirement.
+ Device implementations:
</p>
+ <ul>
+ <li>[C-0-2] MUST pass all tests for hardware that they possess; for instance, if a device possesses an accelerometer, it MUST correctly execute the Accelerometer test case in the CTS Verifier.
+ </li>
+ </ul>
+ <p>
+ Test cases for features noted as optional by this Compatibility Definition Document MAY be skipped or omitted.
+ </p>
+ <ul>
+ <li>[C-0-2] Every device and every build MUST correctly run the CTS Verifier, as noted above. However, since many builds are very similar, device implementers are not expected to explicitly run the CTS Verifier on builds that differ only in trivial ways. Specifically, device implementations that differ from an implementation that has passed the CTS Verifier only by the set of included locales, branding, etc. MAY omit the CTS Verifier test.
+ </li>
+ </ul>
+ <h2 id="11_updatable_software">
+ 11. Updatable Software
+ </h2>
+ <ul>
+ <li>
+ <p>
+ [C-0-1] Device implementations MUST include a mechanism to replace the entirety of the system software. The mechanism need not perform “live” upgrades—that is, a device restart MAY be required. Any method can be used, provided that it can replace the entirety of the software preinstalled on the device. For instance, any of the following approaches will satisfy this requirement:
+ </p>
+ <ul>
+ <li>“Over-the-air (OTA)” downloads with offline update via reboot.
+ </li>
+ <li>“Tethered” updates over USB from a host PC.
+ </li>
+ <li>“Offline” updates via a reboot and update from a file on removable storage.
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ [C-0-2] The update mechanism used MUST support updates without wiping user data. That is, the update mechanism MUST preserve application private data and application shared data. Note that the upstream Android software includes an update mechanism that satisfies this requirement.
+ </p>
+ </li>
+ </ul>
+ <p>
+ If the device implementations include support for an unmetered data connection such as 802.11 or Bluetooth PAN (Personal Area Network) profile, then, they:
+ </p>
+ <ul>
+ <li>[C-1-1] MUST support OTA downloads with offline update via reboot.
+ </li>
+ </ul>
<p>
For device implementations that are launching with Android 6.0 and later, the update mechanism SHOULD support verifying that the system image is binary identical to expected result following an OTA. The block-based OTA implementation in the upstream Android Open Source Project, added since Android 5.1, satisfies this requirement.
</p>
@@ -9349,11 +9914,19 @@
Also, device implementations SHOULD support <a href="https://source.android.com/devices/tech/ota/ab_updates.html">A/B system updates</a>. The AOSP implements this feature using the boot control HAL.
</p>
<p>
- If an error is found in a device implementation after it has been released but within its reasonable product lifetime that is determined in consultation with the Android Compatibility Team to affect the compatibility of third-party applications, the device implementer MUST correct the error via a software update available that can be applied per the mechanism just described.
+ If an error is found in a device implementation after it has been released but within its reasonable product lifetime that is determined in consultation with the Android Compatibility Team to affect the compatibility of third-party applications, then:
</p>
+ <ul>
+ <li>[C-2-1] The device implementer MUST correct the error via a software update available that can be applied per the mechanism just described.
+ </li>
+ </ul>
<p>
- Android includes features that allow the Device Owner app (if present) to control the installation of system updates. To facilitate this, the system update subsystem for devices that report android.software.device_admin MUST implement the behavior described in the <a href="http://developer.android.com/reference/android/app/admin/SystemUpdatePolicy.html">SystemUpdatePolicy</a> class.
+ Android includes features that allow the Device Owner app (if present) to control the installation of system updates. If the system update subsystem for devices report android.software.device_admin then, they:
</p>
+ <ul>
+ <li>[C-3-1] MUST implement the behavior described in the <a href="http://developer.android.com/reference/android/app/admin/SystemUpdatePolicy.html">SystemUpdatePolicy</a> class.
+ </li>
+ </ul>
<h2 id="12_document_changelog">
12. Document Changelog
</h2>
@@ -9362,7 +9935,7 @@
</p>
<ul>
<li>
- <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/oreo-mr1-dev/?pretty=full&no-merges">Document changelog</a>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/?pretty=full&no-merges">Document changelog</a>
</li>
</ul>
<p>
@@ -9370,43 +9943,43 @@
</p>
<ol>
<li>
- <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/oreo-mr1-dev/1_introduction?pretty=full&no-merges">Introduction</a>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/1_introduction?pretty=full&no-merges">Introduction</a>
</li>
<li>
- <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/oreo-mr1-dev/2_device_types?pretty=full&no-merges">Device Types</a>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/2_device_types?pretty=full&no-merges">Device Types</a>
</li>
<li>
- <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/oreo-mr1-dev/3_software?pretty=full&no-merges">Software</a>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/3_software?pretty=full&no-merges">Software</a>
</li>
<li>
- <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/oreo-mr1-dev/4_application-packaging?pretty=full&no-merges">Application Packaging</a>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/4_application-packaging?pretty=full&no-merges">Application Packaging</a>
</li>
<li>
- <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/oreo-mr1-dev/5_multimedia?pretty=full&no-merges">Multimedia</a>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/5_multimedia?pretty=full&no-merges">Multimedia</a>
</li>
<li>
- <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/oreo-mr1-dev/6_dev-tools-and-options?pretty=full&no-merges">Developer Tools and Options</a>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/6_dev-tools-and-options?pretty=full&no-merges">Developer Tools and Options</a>
</li>
<li>
- <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/oreo-mr1-dev/7_hardware-compatibility?pretty=full&no-merges">Hardware Compatibility</a>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/7_hardware-compatibility?pretty=full&no-merges">Hardware Compatibility</a>
</li>
<li>
- <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/oreo-mr1-dev/8_performance-and-power?pretty=full&no-merges">Performance and Power</a>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/8_performance-and-power?pretty=full&no-merges">Performance and Power</a>
</li>
<li>
- <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/oreo-mr1-dev/9_security-model?pretty=full&no-merges">Security Model</a>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/9_security-model?pretty=full&no-merges">Security Model</a>
</li>
<li>
- <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/oreo-mr1-dev/10_software-compatibility-testing?pretty=full&no-merges">Software Compatibility Testing</a>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/10_software-compatibility-testing?pretty=full&no-merges">Software Compatibility Testing</a>
</li>
<li>
- <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/oreo-mr1-dev/11_updatable-software?pretty=full&no-merges">Updatable Software</a>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/11_updatable-software?pretty=full&no-merges">Updatable Software</a>
</li>
<li>
- <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/oreo-mr1-dev/12_document-changelog?pretty=full&no-merges">Document Changelog</a>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/12_document-changelog?pretty=full&no-merges">Document Changelog</a>
</li>
<li>
- <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/oreo-mr1-dev/13_contact-us?pretty=full&no-merges">Contact Us</a>
+ <a href="https://android.googlesource.com/platform/compatibility/cdd/+log/pi-dev/13_contact-us?pretty=full&no-merges">Contact Us</a>
</li>
</ol>
<h3 id="12_1_changelog_viewing_tips">
@@ -9418,13 +9991,13 @@
<ul>
<li>
<p>
- <strong>CDD</strong><br />
+ <strong>CDD</strong><br>
Substantive changes to the compatibility requirements.
</p>
</li>
<li>
<p>
- <strong>Docs</strong><br />
+ <strong>Docs</strong><br>
Cosmetic or build related changes.
</p>
</li>
diff --git a/en/compatibility/cdd.html b/en/compatibility/cdd.html
index c5dd731..00c0737 100644
--- a/en/compatibility/cdd.html
+++ b/en/compatibility/cdd.html
@@ -71,6 +71,12 @@
<th>Strings</th>
</tr>
<tr>
+ <td>9</td>
+ <td><a href="9.0/android-9.0-cdd.pdf">android-9.0-cdd.pdf</a></td>
+ <td><a href="9.0/android-9.0-cdd.html">android-9.0-cdd.html</a></td>
+ <td><a href="9.0/versions.html">Version 9.0</a></td>
+ </tr>
+ <tr>
<td>8.1</td>
<td><a href="8.1/android-8.1-cdd.pdf">android-8.1-cdd.pdf</a></td>
<td><a href="8.1/android-8.1-cdd.html">android-8.1-cdd.html</a></td>
diff --git a/en/compatibility/contact-us.html b/en/compatibility/contact-us.html
deleted file mode 100644
index 29d5852..0000000
--- a/en/compatibility/contact-us.html
+++ /dev/null
@@ -1,62 +0,0 @@
-<html devsite>
- <head>
- <title>Contact Us</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>This page describes the
-contact methods for inquiries regarding the Android compatibility program,
-including the Compatibility Definition Document (CDD) and Compatibility Test
-Suite (CTS). See the <a href="/setup/community.html">Community</a>
-page for communication channels regarding other topics.</p>
-
-<h2
-id="for-android-compatibility-definition-and-compatibility-test-suite-technical-questions">For
-CDD and CTS technical questions</h2>
-<p>If you have technical questions about Android compatibility that aren't covered in
-this site, you can seek help from your peers on the <a
-href="https://groups.google.com/forum/?fromgroups#!forum/android-compatibility">android-compatibility</a>
-list.</p>
-
-<ul>
-<li>Subscribe using Google Groups: <a
-href="https://groups.google.com/forum/?fromgroups#!forum/android-compatibility">android-compatibility</a></li>
-<li>Subscribe via email: <a
-href="mailto:android-compatibility+subscribe@googlegroups.com">android-compatibility</a></li>
-</ul>
-
-<p>To make best use of this list, please first read <a
-href="/setup/community.html#getting-the-most-from-our-lists">Getting
-the Most from Our Lists</a> on the Community page. Users looking for help with
-Android devices should contact their carrier or manufacturer for help.</p>
-
-<h2 id="for-business-inquiries">For licensing Google Mobile Services</h2>
-<p>Please send inquiries about licensing <a
-href="https://www.android.com/gms/">Google Mobile Services </a> through the <a
-href="https://www.android.com/gms/contact/">GMS contact</a> form. Other non-GMS
-partnership inquiries can be sent to <a
-href="mailto:android-partnerships@google.com">android-partnerships@google.com</a>.</p>
-
-<p>While we read every message received, we cannot respond to each of them. We
-promise to contact you if we can help!</p>
-
- </body>
-</html>
diff --git a/en/compatibility/cts/camera-hal.html b/en/compatibility/cts/camera-hal.html
index 0b42a34..f6db85a 100644
--- a/en/compatibility/cts/camera-hal.html
+++ b/en/compatibility/cts/camera-hal.html
@@ -30,14 +30,15 @@
Compatibility Test Suite (CTS), it greatly increases camera test coverage and
will certainly identify potential bugs.</p>
-<p>By passing these tests, original equipment manufacturers (OEM) validate whether
-they have properly integrated the latest Android camera hardware abstraction
-layer (HAL) 3.2 interfaces. When conforming with all items in the checklist, a
-device implementation may be considered <em>full</em> with respect to the new Android
-Camera HAL interfaces. This will in turn enable a device to properly support
-the new <code>android.hardware.camera2</code> package that camera apps build upon.</p>
+<p>By passing these tests, original equipment manufacturers (OEM) validate
+whether they have properly integrated the latest Android camera hardware
+abstraction layer (HAL) 3.2 interfaces. When conforming with all items in the
+checklist, a device implementation may be considered <em>full</em> with respect
+to the new Android Camera HAL interfaces. This will in turn enable a device to
+properly support the new <code>android.hardware.camera2</code> package that
+camera apps build upon.</p>
-<h2 id=camera_hal_3_2_specification>[ ] 1. Camera HAL 3.2 specification</h2>
+<h2 id=camera_hal_3_2_specification>Camera HAL 3.2 specification</h2>
<p>The Android Camera HAL 3.2 specification is the authoritative source of
information on what devices must satisfy; the document here provides a summary
@@ -59,28 +60,28 @@
href="https://android.googlesource.com/platform/system/core/+/master/include/system/graphics.h">system/core/include/system/graphics.h</a></code>
</ul>
-<h2 id=camera_test_types>[ ] 2. Camera test types</h2>
+<h2 id=camera_test_types>Camera test types</h2>
<p>Here are the primary types of tests available for the latest Android camera
along with references to associated instructions below:</p>
<ul>
- <li><em><a href="#native_tests">Native</a>:</em> Tests that directly test the camera HAL interface
- <li><em><a href="#cts_tests">Compatibility Test Suite (CTS)</a></em>: Standard, automated Android
-tests to ensure device compatibility - see the <a
-href="/compatibility/cts/index.html">CTS introduction</a> and the <a
-href="/devices/tech/test_infra/tradefed/index.html">Trade Federation
-Overview</a>
- <li><em><a href="#its_tests">Image Test Suite (ITS)</a>:</em> Manually run tests to ensure image
-correctness - see the top-level and
-test-specific <code>README</code> files and tutorial.py for setup instructions
- <li><em><a href="#manual_tests_with_aosp_camera_app">Manual tests with the
-Android Open Source Project (AOSP) Camera App</a>:</em> User-like testing of
-common camera functions
- <li><em><a href="#manual_testingcam_tests">Manual TestingCam tests</a>:</em>
-Run from the source in <code>pdk/apps/TestingCamera/</code>
+ <li><em><a href="#vendor_test_suite">Vendor Test Suite (VTS)</a>:</em> Tests that directly test the
+ camera HAL interface
+ <li><em><a href="#cts_tests">Compatibility Test Suite (CTS)</a></em>:
+ Standard, automated Android
+ tests to ensure device compatibility - see the
+ <a href="/compatibility/cts/index.html">CTS introduction</a> and the <a
+ href="/devices/tech/test_infra/tradefed/index.html">Trade Federation
+ Overview</a>
+ <li><em><a href="#its_tests">Image Test Suite (ITS)</a>:</em> Manually run
+ tests to ensure image correctness - see the top-level and test-specific
+ <code>README</code> files and <code>tutorial.py</code> for setup instructions
+ <li><em><a
+ href="#manual_testingcam_tests">Manual TestingCam tests</a>:</em>
+ Run from the source in <code>pdk/apps/TestingCamera/</code>
<li><em><a href="#manual_testingcam2_tests">Manual TestingCam2.1
-tests</a>:</em> Run from the source in <code>pdk/apps/TestingCamera2/</code>
+ tests</a>:</em> Run from the source in <code>pdk/apps/TestingCamera2/</code>
</ul>
<p>All of these test types are described in detail below. These tests are
@@ -93,81 +94,28 @@
addressing failures in each test type before proceeding to the next set of
tests.</p>
-<h2 id=native_tests>[ ] 3. Native tests</h2>
+<h2 id=vendor_test_suite>Vendor Test Suite (VTS) tests</h2>
-<p>These tests directly test the camera HAL interface.</p>
+<p>The Android Vendor Test Suite (VTS) is a testing suite that works on the
+HIDL interface level. For more information on using VTS, see
+<a href="/compatibility/vts/">Vendor Test Suite</a>.</p>
-<p>The starting path for Camera native tests is:
-<code>platform/hardware/libhardware</code></p>
-
-<p>To set up these tests:</p>
-
-<pre class="devsite-click-to-copy">
-<code class="devsite-terminal">cd hardware/libhardware/tests/camera*/</code>
-<code class="devsite-terminal">mm</code>
-<code class="devsite-terminal">adb remount; adb sync</code>
-</pre>
-
-<h3 id=hal_3_x_tests>[ ] 3.1. HAL 3.x tests</h3>
-
-<p>Find these camera tests under:
-<code>hardware/libhardware/tests/camera3/*</code></p>
-
-<p>To run all tests:</p>
-
-<pre class="devsite-terminal devsite-click-to-copy">
-adb shell /data/nativetest/camera3_test/camera3_test
-</pre>
-
-<p>You receive an <strong>OK</strong> for each passed test. Errors are logged
-at the end of output along with a summary of tests passed.</p>
-
-<h3 id=hal_2_3_tests>[ ] 3.2. HAL 2/3 tests</h3>
-
-<p>Find these camera tests under:
-<code>hardware/libhardware/tests/camera2/*</code></p>
-
-<p>To run all tests:</p>
-
-<pre class="devsite-terminal devsite-click-to-copy">
-adb shell /data/nativetest/camera3_test/camera3_test
-</pre>
-
-<p>To run a single test, pass the <code>--gtest_filter</code> argument and the
-test name, like so:</p>
-
-<pre class="devsite-terminal devsite-click-to-copy">
-adb shell /data/nativetest/camera2_test/camera2_test --gtest_filter=Camera2Test.OpenClose
-</pre>
-
-<p>To run a subset of tests, use a wildcard with the
-<code>--gtest_filter</code> argument, like so:</p>
-
-<pre class="devsite-terminal devsite-click-to-copy">
-adb shell /data/nativetest/camera2_test/camera2_test --gtest_filter=Camera2Test.*
-</pre>
-
-<h3 id=3_tests_that_interact_with_the_camera_service>[ ] 3.3. Tests that
-interact with the camera service</h3>
-
-<p>Find these camera tests under: <code>frameworks/av/camera/tests/*</code></p>
-
-<h3 id=camera_metadata_tests>[ ] 3.4. Camera metadata tests</h3>
-
-<p>Find these camera tests under: <code>system/media/camera/tests/*</code></p>
-
-<h2 id=cts_tests>[ ] 4. Compatibility Test Suite (CTS) tests</h2>
+<h2 id=cts_tests>Compatibility Test Suite (CTS) tests</h2>
<p>Camera Android Compatibility Test Suite (CTS) tests focus upon device
compatibility. They do not require a specific test environment (the field of
-view or FOV CTS Verifier test being the lone exception).</p>
+view or FOV CTS Verifier test being the lone exception). </p>
-<p>The starting path for Camera CTS tests is: <code>platform/cts</code></p>
+<p>The starting path for Camera CTS tests is: <code>platform/cts</code>.</p>
+
+<p>When running Camera CTS for devices that support external cameras (such as
+USB webcams), you must have a device plugged in when running CTS or the tests
+will automatically fail.</p>
<p>See the <a href="/compatibility/cts/index.html">CTS
introduction</a> and its subpages for general instructions on running CTS.</p>
-<h3 id=cts_tests_for_the_android_hardware_camera_api>[ ] 4.1. CTS tests for
+<h3 id=cts_tests_for_the_android_hardware_camera_api>CTS tests for
the <code>android.hardware.Camera</code> API</h3>
<p>Find these camera tests under <code>cts/tests/tests/</code>:</p>
@@ -179,7 +127,7 @@
<li><code>permission/src/android/permission/cts/CameraPermissionTest.java</code>
</ul>
-<h3 id=cts_tests_for_the_android_hardware_camera2_api>[ ] 4.2. CTS tests for
+<h3 id=cts_tests_for_the_android_hardware_camera2_api>CTS tests for
the <code>android.hardware.camera2</code> API</h3>
<p>Find these camera tests under <code>cts/tests/tests/</code>:</p>
@@ -189,12 +137,12 @@
<li><code>permission/src/android/permission/cts/Camera2PermissionTest.java</code>
</ul>
-<h3 id=cts_verifier_camera_tests>[ ] 4.3. CTS Verifier camera tests</h3>
+<h3 id=cts_verifier_camera_tests>CTS Verifier camera tests</h3>
<p>Find these camera tests under:
<code>cts/apps/CtsVerifier/src/com/android/cts/verifier/camera/*</code></p>
-<h2 id=its_tests>[ ] 5. Image Test Suite (ITS) tests</h2>
+<h2 id=its_tests>Image Test Suite (ITS) tests</h2>
<p>The CameraITS tests focus upon image correctness. These Python scripts are
manually run on a workstation with the Android device connected over USB. The
@@ -205,7 +153,8 @@
ITS subtest before running the python scripts so they have processes with which
to communicate.</p>
-<p>The CameraITS infrastructure and tests are located under: <code>cts/apps/CameraITS</code></p>
+<p>The CameraITS infrastructure and tests are located under:
+<code>cts/apps/CameraITS</code></p>
<p>See the latest <code>README</code> file in this top-level folder for
instructions on how to set up and run the tests. For setup: <code>make
@@ -219,11 +168,16 @@
</pre>
<p>See <code>tutorial.py</code> in the <code>tests</code> subdirectory for a
-walkthrough of the script's use. Each test resides in a corresponding
+walkthrough of the script's use. Each test resides in a corresponding
<code>tests/scene<#></code> subdirectory. See the <code>README</code> file in
each subdirectory for specific test instructions.</p>
-<p>You will need a simple physical environment with a specific, reusable target
+<p>To follow the recommended way of setting up and running the Camera Image Test
+Suite, see <a href="/compatibility/cts/camera-its-box">Camera
+ITS-in-a-Box</a>.</p>
+
+<p>To run ITS manually, you will need a simple physical environment with a
+specific, reusable target
such as a white wall, grey card, and desk lamp. The Android device is mounted
on a tripod and its camera functions are exercised by the scripts. Most tests
are pass or fail but some offer metrics, as well.</p>
@@ -233,98 +187,28 @@
do test scenarios that are not tested in CTS and are an important component of
the overall HAL 3.2 test plan.</p>
-<h3 id=its_tests_on_scene_0_plain>[ ] 5.1. ITS tests on scene 0 (plain)</h3>
+<h3 id=its_tests_on_scene_0_plain>ITS tests on scene 0 (plain)</h3>
<p>This test requires no specific setup. Pass all of the tests in the
<code>tests/scene0</code> folder, for all cameras (back + front + any
others).</p>
-<h3 id=its_tests_on_scene_1_grey_card>[ ] 5.2. ITS tests on scene 1 (grey card)</h3>
+<h3 id=its_tests_on_scene_1_grey_card>ITS tests on scene 1 (grey card)</h3>
<p>Pass all of the tests in the <code>tests/scene1</code> folder, for all
cameras (back + front + any others). The <code>tests/scene1/README</code> file
describes the scene setup.</p>
-<h3 id=its_tests_on_scene_2_camera_lab>[ ] 5.3. ITS tests on scene 2 (camera lab)</h3>
+<h3 id=its_tests_on_scene_2_camera_lab>ITS tests on scene 2 (camera lab)</h3>
<p>Pass all of the tests in the <code>tests/scene2</code> folder, for all
cameras (back + front + any others). The <code>tests/scene2/README</code> file
describes the scene setup.</p>
-<h2 id=manual_tests_with_aosp_camera_app>[ ] 6. Manual tests with the AOSP App</h2>
+<h2 id=media_framework_tests>Media Framework tests</h2>
-<h3 id=camera_mode_aosp_camera_app>[ ] 6.1. Camera mode</h3>
-
-<p>For all cameras on the device (front, back, and any others), verify:</p>
-
-<ol>
- <li>Images can be captured and reviewed on the device, and the images look good
-with no obvious problems.
- <li>Tap-to-focus, continuous autofocus, macro focus, infinity focus, AWB, and AEC
-are all reliable.
- <li>Tap-to-focus, continuous autofocus, AWB, and AEC are reliable when using
-digital zoom (during capture).
- <li>Flash settings (on/off/auto) are reliable and synchronize well with the 3As.
-</ol>
-
-<h3 id=video_mode_aosp_camera_app>[ ] 6.2. Video mode</h3>
-
-<p>For all cameras on the device (front, back, and any others), verify:</p>
-
-<ol>
- <li>Videos can be captured and reviewed on the device, and the videos look good
-with no obvious problems.
- <li>Capturing a snapshot while in the middle of recording a video works.
- <li>Tap-to-focus, continuous autofocus, macro focus, infinity focus, AWB, and AEC
-are all reliable.
- <li>Tap-to-focus, continuous autofocus, AWB, and AEC are reliable when using
-digital zoom (during capture).
- <li>Torch settings (on/off) are reliable and synchronize well with the 3As.
-</ol>
-
-<h3 id=camera_settings_resolution>[ ] 6.3. Camera settings: resolution</h3>
-
-<p>For all cameras on the device (front, back, and any others), and for all
-resolutions available in the menu, verify that correct resolution settings are
-returned and applied for:</p>
-
-<ul>
- <li>Camera mode
- <li>Video mode
- <li>LensBlur
- <li>PhotoSphere
- <li>Panorama
-</ul>
-
-<h3 id=camera_settings_exposure_compensation>[ ] 6.4. Camera settings:
-exposure compensation</h3>
-
-<p>Verify that exposure compensation is applied (at +2 and -2).</p>
-
-<h3 id=photosphere>[ ] 6.5. PhotoSphere</h3>
-
-<p>Capture full 360-degree PhotoSphere images shot with each of the front and
-rear cameras. Verify all of the individual frames are focused at infinity and the
-exposure and white balance match between shots.</p>
-
-<h3 id=panorama>[ ] 6.6. Panorama</h3>
-
-<p>Capture vertical, horizontal, and wide-angle panoramas (with both front and
-rear cameras), and verify all of the individual frames are focused at infinity
-and the exposure and white balance matches between shots.</p>
-
-<h3 id=lensblur>[ ] 6.7. LensBlur</h3>
-
-<p>Capture a LensBlur image with both front and rear cameras, and verify
-refocusing to different depths (while reviewing the captured shots) works.</p>
-
-<p>Also verify tap-to-focus, continuous autofocus, AWB, and AEC are reliable in
-this mode.</p>
-
-<h2 id=media_framework_tests>[ ] 7. Media Framework tests</h2>
-
-<p>Pass all of the camera-related media tests in MediaFrameworkTest. Please note,
-these tests require the mediaframeworktest.apk be installed on the Android
+<p>Pass all of the camera-related media tests in MediaFrameworkTest. Please
+note, these tests require the mediaframeworktest.apk be installed on the Android
device. You will need to <code>make mediaframeworktest</code> and then use adb
to install the resulting .apk. Example commands are included below.</p>
@@ -361,7 +245,7 @@
<li><code>unit/</code>
</ul>
-<h3 id=running_media_framework_tests>[ ] 7.1. Running Media Framework tests</h3>
+<h3 id=running_media_framework_tests>Running Media Framework tests</h3>
<p>To see all of the available tests::</p>
@@ -397,13 +281,16 @@
com.android.mediaframeworktest/.MediaFrameworkPowerTestRunner
</pre>
-<p>You may then pass each component to <code>adb shell am instrument</code> like so:</p>
+<p>You may then pass each component to <code>adb shell am instrument</code> like
+so:</p>
<pre class="devsite-terminal devsite-click-to-copy">
-adb shell am instrument -w <component.name>
+adb shell am instrument -w <var>component.name</var>
</pre>
-<p>Where the <component.name> equals the extracted value above. For example:</p>
+ <p>Where <code><var>component.name</var></code> equals the extracted value
+ above. For
+example:</p>
<pre class="devsite-terminal devsite-click-to-copy">
adb shell am instrument -w com.android.mediaframeworktest/.MediaFrameworkIntegrationTestRunner
@@ -428,7 +315,7 @@
adb shell am instrument -e class 'com.android.mediaframeworktest.integration.CameraBinderTest#testConnectPro' -w com.android.mediaframeworktest/.MediaFrameworkIntegrationTestRunner
</pre>
-<h3 id=media_settings_functional_tests>[ ] 7.2. Media settings functional tests</h3>
+<h3 id=media_settings_functional_tests>Media settings functional tests</h3>
<p>Here is an example run of a functional test. This test verifies the basic
functionality of different combinations of camera settings. (ie, Flash,
@@ -439,7 +326,7 @@
adb shell am instrument -w -r -e delay_msec 15 -e log true -e class com.android.mediaframeworktest.functional.camera.CameraPairwiseTest com.android.mediaframeworktest/com.android.mediaframeworktest.CameraStressTestRunner
</pre>
-<h3 id=media_integration_tests>[ ] 7.3. Media integration tests</h3>
+<h3 id=media_integration_tests>Media integration tests</h3>
<p>Here is an example run of an integration test, in this case
mediaframeworktest/integration/CameraBinderTest.java and
@@ -463,7 +350,7 @@
-----
</pre>
-<h3 id=media_performance_tests>[ ] 7.4. Media performance tests</h3>
+<h3 id=media_performance_tests>Media performance tests</h3>
<p>This preview memory test will open and release the camera preview for 200
times. In each 20 iterations, the snapshot of ps mediaserver will be recorded
@@ -478,7 +365,7 @@
<p>More detailed output can be found in:
<code>/sdcard/mediaMemOutput.txt</code></p>
-<h3 id=media_unit_tests>[ ] 7.5. Media unit tests</h3>
+<h3 id=media_unit_tests>Media unit tests</h3>
<p>The commands to run unit tests are all similar. For example, for
CameraMetadataTest.java, the command would be:</p>
@@ -487,7 +374,7 @@
adb shell am instrument -e class 'com.android.mediaframeworktest.unit.CameraMetadataTest' -w 'com.android.mediaframeworktest/.CameraStressTestRunner'
</pre>
-<h3 id=media_stress_tests>[ ] 7.6. Media stress tests</h3>
+<h3 id=media_stress_tests>Media stress tests</h3>
<p>This test is to stress out the camera image capture and video recording.</p>
@@ -499,12 +386,12 @@
<p>All tests should pass.</p>
-<h2 id=manual_testingcam_tests>[ ] 8. Manual TestingCam tests</h2>
+<h2 id=manual_testingcam_tests>Manual TestingCam tests</h2>
<p>The TestingCam app should be run manually with the following checks performed.
The source for TestingCam is here: <code>pdk/apps/TestingCamera/</code></p>
-<h3 id=infinity_focus_with_camera_tilt>[ ] 8.1. Infinity focus with camera tilt</h3>
+<h3 id=infinity_focus_with_camera_tilt>Infinity focus with camera tilt</h3>
<p>Start TestingCam, turn on preview, and ensure that autofocus mode is set to
infinity. Using the <strong>Take picture</strong> button, capture shots of
@@ -521,12 +408,12 @@
correction based on using accelerometer data to determine camera orientation.
Reliable factory calibration of the lens infinity position will also be needed.</p>
-<h2 id=manual_testingcam2_tests>[ ] 9. Manual TestingCam2 tests</h2>
+<h2 id=manual_testingcam2_tests>Manual TestingCam2 tests</h2>
<p>The TestingCam2 app should be run manually, with the following checks
performed. The source for TestingCam2 is here: <code>pdk/apps/TestingCamera2/</code></p>
-<h3 id=9_1_jpeg_capture>[ ] 9.1. JPEG capture</h3>
+<h3 id=9_1_jpeg_capture>JPEG capture</h3>
<p>Start TestingCam2, and press the <strong>JPEG</strong> button. The image
that appears to the right of the viewfinder image should appear the same as the
diff --git a/en/compatibility/cts/downloads.html b/en/compatibility/cts/downloads.html
index 9e79b90..df5e21c 100644
--- a/en/compatibility/cts/downloads.html
+++ b/en/compatibility/cts/downloads.html
@@ -28,6 +28,31 @@
updated, new versions are added to this page. CTS versions are denoted by
R<number> in the link name.</p>
+<h2 id="android-90">Android 9</h2>
+<p>Android 9 is the release of the development milestone code-named P.
+The source code for the following tests, including tests for instant apps, can be synced with the
+'android-cts-9.0_r1' tag in the open-source tree.</p>
+<ul>
+<li><a
+href="https://dl.google.com/dl/android/cts/android-cts-9.0_r1-linux_x86-arm.zip">Android
+9.0 R1 Compatibility Test Suite (CTS) - ARM</a></li>
+<li><a
+href="https://dl.google.com/dl/android/cts/android-cts-9.0_r1-linux_x86-x86.zip">Android
+9.0 R1 Compatibility Test Suite (CTS) - x86</a></li>
+<li><a
+href="https://dl.google.com/dl/android/cts/android-cts-verifier-9.0_r1-linux_x86-arm.zip">Android
+9.0 R1 CTS Verifier - ARM</a></li>
+<li><a
+href="https://dl.google.com/dl/android/cts/android-cts-verifier-9.0_r1-linux_x86-x86.zip">Android
+9.0 R1 CTS Verifier - x86</a></li>
+<li><a
+href="https://dl.google.com/dl/android/cts/android-cts_instant-9.0_r1-linux_x86-arm.zip">Android
+9.0 R1 CTS for Instant Apps - ARM</a></li>
+<li><a
+href="https://dl.google.com/dl/android/cts/android-cts_instant-9.0_r1-linux_x86-x86.zip">Android
+9.0 R1 CTS for Instant Apps - x86</a></li>
+</ul>
+
<h2 id="android-81">Android 8.1</h2>
<p>Android 8.1 is the release of the development milestone code-named Oreo-MR1.
The source code for the following tests can be synced with the
diff --git a/en/compatibility/cts/images/sensor_fusion_adjust.png b/en/compatibility/cts/images/sensor_fusion_adjust.png
new file mode 100644
index 0000000..17282ce
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_adjust.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_assembly_abs_pieces.png b/en/compatibility/cts/images/sensor_fusion_assembly_abs_pieces.png
new file mode 100644
index 0000000..f5687a0
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_assembly_abs_pieces.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_assembly_assembled_fixture.png b/en/compatibility/cts/images/sensor_fusion_assembly_assembled_fixture.png
new file mode 100644
index 0000000..bec5fc0
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_assembly_assembled_fixture.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_assembly_box_cad_drawing.png b/en/compatibility/cts/images/sensor_fusion_assembly_box_cad_drawing.png
new file mode 100644
index 0000000..1a31243
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_assembly_box_cad_drawing.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_assembly_checkerboard.png b/en/compatibility/cts/images/sensor_fusion_assembly_checkerboard.png
new file mode 100644
index 0000000..b08e378
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_assembly_checkerboard.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_assembly_clamp.png b/en/compatibility/cts/images/sensor_fusion_assembly_clamp.png
new file mode 100644
index 0000000..bfb213f
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_assembly_clamp.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_assembly_clamp_attachment_cad_drawing.png b/en/compatibility/cts/images/sensor_fusion_assembly_clamp_attachment_cad_drawing.png
new file mode 100644
index 0000000..1b84a6a
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_assembly_clamp_attachment_cad_drawing.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_assembly_complete_box_drawing.png b/en/compatibility/cts/images/sensor_fusion_assembly_complete_box_drawing.png
new file mode 100644
index 0000000..7bf163c
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_assembly_complete_box_drawing.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_assembly_exterior_bolts.png b/en/compatibility/cts/images/sensor_fusion_assembly_exterior_bolts.png
new file mode 100644
index 0000000..4564e86
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_assembly_exterior_bolts.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_assembly_fixed_rail.png b/en/compatibility/cts/images/sensor_fusion_assembly_fixed_rail.png
new file mode 100644
index 0000000..1cbcb97
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_assembly_fixed_rail.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_assembly_handle_pieces.png b/en/compatibility/cts/images/sensor_fusion_assembly_handle_pieces.png
new file mode 100644
index 0000000..c6a877a
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_assembly_handle_pieces.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_assembly_interior_wall_lights.png b/en/compatibility/cts/images/sensor_fusion_assembly_interior_wall_lights.png
new file mode 100644
index 0000000..b1f6d8e
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_assembly_interior_wall_lights.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_assembly_interior_wall_screws.png b/en/compatibility/cts/images/sensor_fusion_assembly_interior_wall_screws.png
new file mode 100644
index 0000000..f478d9e
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_assembly_interior_wall_screws.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_assembly_light_strips_diffusers.png b/en/compatibility/cts/images/sensor_fusion_assembly_light_strips_diffusers.png
new file mode 100644
index 0000000..24ff8bf
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_assembly_light_strips_diffusers.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_assembly_phone_fixture.png b/en/compatibility/cts/images/sensor_fusion_assembly_phone_fixture.png
new file mode 100644
index 0000000..a563ae0
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_assembly_phone_fixture.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_assembly_phone_fixture_holes1.png b/en/compatibility/cts/images/sensor_fusion_assembly_phone_fixture_holes1.png
new file mode 100644
index 0000000..9231eec
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_assembly_phone_fixture_holes1.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_assembly_phone_fixture_holes2.png b/en/compatibility/cts/images/sensor_fusion_assembly_phone_fixture_holes2.png
new file mode 100644
index 0000000..f23f61f
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_assembly_phone_fixture_holes2.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_assembly_servo_on_wall.png b/en/compatibility/cts/images/sensor_fusion_assembly_servo_on_wall.png
new file mode 100644
index 0000000..c2f0600
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_assembly_servo_on_wall.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_assembly_servo_screw.png b/en/compatibility/cts/images/sensor_fusion_assembly_servo_screw.png
new file mode 100644
index 0000000..74c1fcb
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_assembly_servo_screw.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_assembly_servo_servo_plate.png b/en/compatibility/cts/images/sensor_fusion_assembly_servo_servo_plate.png
new file mode 100644
index 0000000..277dbc1
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_assembly_servo_servo_plate.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_assembly_servo_shaft.png b/en/compatibility/cts/images/sensor_fusion_assembly_servo_shaft.png
new file mode 100644
index 0000000..7bca41f
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_assembly_servo_shaft.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_assembly_shaft.png b/en/compatibility/cts/images/sensor_fusion_assembly_shaft.png
new file mode 100644
index 0000000..0078599
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_assembly_shaft.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_assembly_shaft_screws.png b/en/compatibility/cts/images/sensor_fusion_assembly_shaft_screws.png
new file mode 100644
index 0000000..ffbd262
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_assembly_shaft_screws.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_assembly_strips_taped_back.png b/en/compatibility/cts/images/sensor_fusion_assembly_strips_taped_back.png
new file mode 100644
index 0000000..04ba3f1
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_assembly_strips_taped_back.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_assembly_taped_box.png b/en/compatibility/cts/images/sensor_fusion_assembly_taped_box.png
new file mode 100644
index 0000000..826b240
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_assembly_taped_box.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_connect_lights.png b/en/compatibility/cts/images/sensor_fusion_connect_lights.png
new file mode 100644
index 0000000..e77bab0
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_connect_lights.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_conversion_cable1.png b/en/compatibility/cts/images/sensor_fusion_conversion_cable1.png
new file mode 100644
index 0000000..acba9e3
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_conversion_cable1.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_conversion_cable2.png b/en/compatibility/cts/images/sensor_fusion_conversion_cable2.png
new file mode 100644
index 0000000..8496a72
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_conversion_cable2.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_fixture1.png b/en/compatibility/cts/images/sensor_fusion_fixture1.png
new file mode 100644
index 0000000..71a3e77
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_fixture1.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_fixture2.png b/en/compatibility/cts/images/sensor_fusion_fixture2.png
new file mode 100644
index 0000000..4a4c3e4
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_fixture2.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_servo_connector.png b/en/compatibility/cts/images/sensor_fusion_servo_connector.png
new file mode 100644
index 0000000..dc20d1b
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_servo_connector.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_servo_control1.png b/en/compatibility/cts/images/sensor_fusion_servo_control1.png
new file mode 100644
index 0000000..f531571
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_servo_control1.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_servo_control2.png b/en/compatibility/cts/images/sensor_fusion_servo_control2.png
new file mode 100644
index 0000000..38fb2f6
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_servo_control2.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_servo_control_box1.png b/en/compatibility/cts/images/sensor_fusion_servo_control_box1.png
new file mode 100644
index 0000000..c43522b
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_servo_control_box1.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_servo_control_box2.png b/en/compatibility/cts/images/sensor_fusion_servo_control_box2.png
new file mode 100644
index 0000000..7473968
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_servo_control_box2.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_test_components.png b/en/compatibility/cts/images/sensor_fusion_test_components.png
new file mode 100644
index 0000000..ae7a4f5
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_test_components.png
Binary files differ
diff --git a/en/compatibility/cts/images/sensor_fusion_zip_ties.png b/en/compatibility/cts/images/sensor_fusion_zip_ties.png
new file mode 100644
index 0000000..790766e
--- /dev/null
+++ b/en/compatibility/cts/images/sensor_fusion_zip_ties.png
Binary files differ
diff --git a/en/compatibility/cts/run.html b/en/compatibility/cts/run.html
index 4bc17a0..0bd66d9 100644
--- a/en/compatibility/cts/run.html
+++ b/en/compatibility/cts/run.html
@@ -198,6 +198,8 @@
<h2 id=using-cts-v2>Using the CTS v2 console</h2>
<p>For Android 7.0 or later, you'll use CTS v2.</p>
+
+
<h3 id=selecting_ctsv2_plans>Selecting plans</h3>
<p>Available test plans include the following:</p>
<ul>
@@ -266,6 +268,13 @@
<p>If more than one device is connected, the CTS host will choose a device automatically.</p></td>
</tr>
<tr>
+ <td><code>run retry</code></td>
+ <td><p><strong>For Android 9</strong>. Retry all tests that failed or were not executed from the
+ previous sessions. For example, <code>run retry --retry <session id> -s<device serial></code>,
+ or <code>run retry --retry <session id> --shard-count</code> with TF sharding.</p>
+ <p><code>run cts --retry</code> is not allowed for Android 9.</td>
+ </tr>
+ <tr>
<td><code>--plan <test_plan_name></code></td>
<td>Run the specified test plan.</td>
</tr>
@@ -292,8 +301,17 @@
Use <code>list results</code> to get the session id.</td>
</tr>
<tr>
+ <td><code>--retry-type not_executed</code></td>
+ <td>Retry only tests that were not executed from the previous sessions.
+ Use <code>list results</code> to get the session id.</td>
+ </tr>
+ <tr>
<td><code>--shards <number_of_shards></code></td>
- <td>Shard a CTS run into given number of independent chunks, to run on multiple devices in parallel.</td>
+ <td><strong>For Android 8.1 and earlier versions</strong>. Shard a CTS run into given number of independent chunks, to run on multiple devices in parallel.</td>
+ </tr>
+ <tr>
+ <td><code>--shard-count <number_of_shards></code></td>
+ <td><strong>For Android 9</strong>. Shard a CTS run into given number of independent chunks, to run on multiple devices in parallel.</td>
</tr>
<tr>
<td><code>--serial/-s <deviceID></code></td>
diff --git a/en/compatibility/cts/secure-element.md b/en/compatibility/cts/secure-element.md
new file mode 100644
index 0000000..e827c0a
--- /dev/null
+++ b/en/compatibility/cts/secure-element.md
@@ -0,0 +1,799 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# CTS Test for Secure Element
+
+To provide better security, some devices have an embedded Secure Element (SE),
+which is dedicated, separate tamper-resistant hardware to store cryptographic
+data. Open Mobile API is a
+[standard API](https://globalplatform.org/specs-library/open-mobile-api-specification-v3-2/){: .external}
+used to communicate with a device's Secure Element. Android
+{{ androidPVersionNumber }}
+introduces support for this API and provides a backend implementation including
+Secure Element Service and SE HAL.
+
+Secure Element Service checks support for Global platform-supported Secure
+Elements (essentially checks if devices have SE HAL implementation and if yes,
+how many). This is used as the basis to test the API and the
+underlying Secure Element implementation.
+
+## Terminology
+
+<table>
+<thead>
+<tr>
+<th>Term</th>
+<th>Definition</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>AID</td>
+<td>Application Identifier</td>
+</tr>
+<tr>
+<td>APDU</td>
+<td>Application Protocol Data Unit</td>
+</tr>
+<tr>
+<td>BER</td>
+<td>Basic Encoding Rules</td>
+</tr>
+<tr>
+<td>TLV</td>
+<td>Tag Length Value</td>
+</tr>
+<tr>
+<td>UICC </td>
+<td>UMTS Integrated Circuit Card</td>
+</tr>
+<tr>
+<td>ARA</td>
+<td>Access Rule Application Master</td>
+</tr>
+<tr>
+<td>ARF</td>
+<td>Access Rule File</td>
+</tr>
+<tr>
+<td>Applet</td>
+<td>Java Card application on Secure Element</td>
+</tr>
+</tbody>
+</table>
+
+## Open Mobile API test cases
+
+Open Mobile API test cases are used to enforce API guidelines and to confirm the
+underlying implementation of Secure Elements meets the Open Mobile API
+specification. These test cases require installation of a special applet that
+is used by the CTS application for communication. For installation, use the
+sample applet found in
+[CtsAndroidOmapiTestApplet.java](https://android.googlesource.com/platform/cts/+/master/tests/tests/secure_element/sample_applet/src/com/android/cts/omapi/test/CtsAndroidOmapiTestApplet.java){: .external} and [test.cap](https://android.googlesource.com/platform/cts/+/master/tests/tests/secure_element/sample_applet/test.cap){: .external}.
+
+To pass OMAPI test cases, the underlying Secure Element Service and the SE
+should be capable of the following:
+
+<ol>
+<li>All Secure Element Reader names should start with SIM or eSE or SD.</li>
+<li>Non-SIM based readers should be capable of opening basic channels.</li>
+<li><p><code>CtsOmapiTestCases.apk</code> should be capable of selecting an
+applet with the following AIDs:</p>
+ <ol>
+ <li><p>0xA000000476416E64726F696443545331</p>
+ <ol>
+ <li><p>The applet should throw a Security Exception when it receives the
+ following APDUs in android.se.omapi.Channel.Transmit (hereby referred to
+ as <em>Transmit</em>):</p>
+ <ol>
+ <li>0x00700000</li>
+ <li>0x00708000</li>
+ <li>0x00A40404104A535231373754657374657220312E30</li>
+ </ol>
+ </li>
+ <li><p>The applet should return no data when it receives the following
+ APDUs in<em> Transmit</em>:</p>
+ <ol>
+ <li>0x00060000</li>
+ <li>0x80060000</li>
+ <li>0xA0060000</li>
+ <li>0x94060000</li>
+ <li>0x000A000001AA</li>
+ <li>0x800A000001AA</li>
+ <li>0xA00A000001AA</li>
+ <li>0x940A000001AA</li>
+ </ol>
+ </li>
+ <li><p>The applet should return 256 byte data for the following
+ <em>Transmit</em> APDUs:</p>
+ <ol>
+ <li>0x0008000000</li>
+ <li>0x8008000000</li>
+ <li>0xA008000000</li>
+ <li>0x9408000000</li>
+ <li>0x000C000001AA00</li>
+ <li>0x800C000001AA00</li>
+ <li>0xA00C000001AA00</li>
+ <li>0x940C000001AA00</li>
+ </ol>
+ <li><p>The applet should return the following Status word responses for
+ the respective <em>Transmit</em> APDU:</p>
+ <table>
+ <thead>
+ <tr>
+ <th>Transmit APDU</th>
+ <th>Status Word</th>
+ <th>Data</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>0x00F30106</td>
+ <td>0x6200</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F30206</td>
+ <td>0x6281</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F30306</td>
+ <td>0x6282</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F30406</td>
+ <td>0x6283</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F30506</td>
+ <td>0x6285</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F30606</td>
+ <td>0x62F1</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F30706</td>
+ <td>0x62F2</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F30806</td>
+ <td>0x63F1</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F30906</td>
+ <td>0x63F2</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F30A06</td>
+ <td>0x63C2</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F30B06</td>
+ <td>0x6202</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F30C06</td>
+ <td>0x6280</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F30D06</td>
+ <td>0x6284</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F30E06</td>
+ <td>0x6282</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F30F06</td>
+ <td>0x6300</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F31006</td>
+ <td>0x6381</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F3010A01AA</td>
+ <td>0x6200</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F3020A01AA</td>
+ <td>0x6281</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F3030A01AA</td>
+ <td>0x6282</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F3040A01AA</td>
+ <td>0x6283</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F3050A01AA</td>
+ <td>0x6285</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F3060A01AA</td>
+ <td>0x62F1</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F3070A01AA</td>
+ <td>0x62F2</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F3080A01AA</td>
+ <td>0x63F1</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F3090A01AA</td>
+ <td>0x63F2</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F30A0A01AA</td>
+ <td>0x63C2</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F30B0A01AA</td>
+ <td>0x6202</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F30C0A01AA</td>
+ <td>0x6280</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F30D0A01AA</td>
+ <td>0x6284</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F30E0A01AA</td>
+ <td>0x6282</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F30F0A01AA</td>
+ <td>0x6300</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F3100A01AA</td>
+ <td>0x6381</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>0x00F3010800</td>
+ <td>0x6200</td>
+ <td>Yes</td>
+ </tr>
+ <tr>
+ <td>0x00F3020800</td>
+ <td>0x6281</td>
+ <td>Yes</td>
+ </tr>
+ <tr>
+ <td>0x00F3030800</td>
+ <td>0x6282</td>
+ <td>Yes</td>
+ </tr>
+ <tr>
+ <td>0x00F3040800</td>
+ <td>0x6283</td>
+ <td>Yes</td>
+ </tr>
+ <tr>
+ <td>0x00F3050800</td>
+ <td>0x6285</td>
+ <td>Yes</td>
+ </tr>
+ <tr>
+ <td>0x00F3060800</td>
+ <td>0x62F1</td>
+ <td>Yes</td>
+ </tr>
+ <tr>
+ <td>0x00F3070800</td>
+ <td>0x62F2</td>
+ <td>Yes</td>
+ </tr>
+ <tr>
+ <td>0x00F3080800</td>
+ <td>0x63F1</td>
+ <td>Yes</td>
+ </tr>
+ <tr>
+ <td>0x00F3090800</td>
+ <td>0x63F2</td>
+ <td>Yes</td>
+ </tr>
+ <tr>
+ <td>0x00F30A0800</td>
+ <td>0x63C2</td>
+ <td>Yes</td>
+ </tr>
+ <tr>
+ <td>0x00F30B0800</td>
+ <td>0x6202</td>
+ <td>Yes</td>
+ </tr>
+ <tr>
+ <td>0x00F30C0800</td>
+ <td>0x6280</td>
+ <td>Yes</td>
+ </tr>
+ <tr>
+ <td>0x00F30D0800</td>
+ <td>0x6284</td>
+ <td>Yes</td>
+ </tr>
+ <tr>
+ <td>0x00F30E0800</td>
+ <td>0x6282</td>
+ <td>Yes</td>
+ </tr>
+ <tr>
+ <td>0x00F30F0800</td>
+ <td>0x6300</td>
+ <td>Yes</td>
+ </tr>
+ <tr>
+ <td>0x00F3100800</td>
+ <td>0x6381</td>
+ <td>Yes</td>
+ </tr>
+ <tr>
+ <td>0x00F3010C01AA00</td>
+ <td>0x6200</td>
+ <td>Yes*</td>
+ </tr>
+ <tr>
+ <td>0x00F3020C01AA00</td>
+ <td>0x6281</td>
+ <td>Yes*</td>
+ </tr>
+ <tr>
+ <td>0x00F3030C01AA00</td>
+ <td>0x6282</td>
+ <td>Yes*</td>
+ </tr>
+ <tr>
+ <td>0x00F3040C01AA00</td>
+ <td>0x6283</td>
+ <td>Yes*</td>
+ </tr>
+ <tr>
+ <td>0x00F3050C01AA00</td>
+ <td>0x6285</td>
+ <td>Yes*</td>
+ </tr>
+ <tr>
+ <td>0x00F3060C01AA00</td>
+ <td>0x62F1</td>
+ <td>Yes*</td>
+ </tr>
+ <tr>
+ <td>0x00F3070C01AA00</td>
+ <td>0x62F2</td>
+ <td>Yes*</td>
+ </tr>
+ <tr>
+ <td>0x00F3080C01AA00</td>
+ <td>0x63F1</td>
+ <td>Yes*</td>
+ </tr>
+ <tr>
+ <td>0x00F3090C01AA00</td>
+ <td>0x63F2</td>
+ <td>Yes*</td>
+ </tr>
+ <tr>
+ <td>0x00F30A0C01AA00</td>
+ <td>0x63C2</td>
+ <td>Yes*</td>
+ </tr>
+ <tr>
+ <td>0x00F30B0C01AA00</td>
+ <td>0x6202</td>
+ <td>Yes*</td>
+ </tr>
+ <tr>
+ <td>0x00F30C0C01AA00</td>
+ <td>0x6280</td>
+ <td>Yes*</td>
+ </tr>
+ <tr>
+ <td>0x00F30D0C01AA00</td>
+ <td>0x6284</td>
+ <td>Yes*</td>
+ </tr>
+ <tr>
+ <td>0x00F30E0C01AA00</td>
+ <td>0x6282</td>
+ <td>Yes*</td>
+ </tr>
+ <tr>
+ <td>0x00F30F0C01AA00</td>
+ <td>0x6300</td>
+ <td>Yes*</td>
+ </tr>
+ <tr>
+ <td>0x00F3100C01AA00</td>
+ <td>0x6381</td>
+ <td>Yes*</td>
+ </tr>
+ </tbody>
+ </table>
+ <p class="note"><strong>Note:</strong> The response should contain data
+ that is the same as input APDU,
+ except the first byte is 0x01 instead of 0x00.</p>
+ </li>
+ <li><p>The applet should return Segmented responses of size 2048 bytes for
+ commands a,b,c,d, f and g whereas 32767 bytes for APDU(e), with last
+ data byte being 0xFF and success status word<0x9000> for the following
+ APDUs:</0x9000></p>
+ <ol>
+ <li>0x00C2080000</li>
+ <li>0x00C4080002123400</li>
+ <li>0x00C6080000</li>
+ <li>0x00C8080002123400</li>
+ <li>0x00C27FFF00</li>
+ <li>0x00CF080000</li>
+ <li>0x94C2080000</li>
+ </ol>
+ </li>
+ <li>The applet should return success status word <0x9000> for the given
+ APDU: 0x00F40000</li>
+ </ol>
+ <li><p>A000000476416E64726F696443545332</p>
+ <ol>
+ <li><p>This AID when selected should return a select response greater than
+ 2 bytes that are correctly BER TLV formatted.</p></li>
+ </ol>
+ </li>
+</ol>
+
+<li><p><code>CtsOmapiTestCases.apk</code> should not be capable of selecting the
+following AID:</p>
+ <ol>
+ <li>A000000476416E64726F6964435453FF</li>
+ </ol>
+</li>
+</ol>
+
+## Access Control test cases
+
+Access Control uses configured in the Secure Element ensure that only the
+application with access to an applet can communicate with it. Additionally,
+Android supports configuring rules for specific APDUs that can be exchanged by
+the APK. The following tests will require the device manufacturer to configure
+special Access Control Rules (either ARA or ARF) to pass.
+
+We recommend using the same applet that is used for OMAPI tests (see applet
+functional behavior described in Open Mobile API test cases section) as the same
+commands need to be supported to pass the Access Control tests.
+
+You must create an instance of the applet under each of the following AIDs:
+
+- 0xA000000476416E64726F696443545340
+- 0xA000000476416E64726F696443545341
+- 0xA000000476416E64726F696443545342
+- 0xA000000476416E64726F696443545344
+- 0xA000000476416E64726F696443545345
+- 0xA000000476416E64726F696443545347
+- 0xA000000476416E64726F696443545348
+- 0xA000000476416E64726F696443545349
+- 0xA000000476416E64726F69644354534A
+- 0xA000000476416E64726F69644354534B
+- 0xA000000476416E64726F69644354534C
+- 0xA000000476416E64726F69644354534D
+- 0xA000000476416E64726F69644354534E
+- 0xA000000476416E64726F69644354534F
+
+### 1. `CtsSecureElementAccessControlTestCases1`
+
+- Hash of the APK: 0x4bbe31beb2f753cfe71ec6bf112548687bb6c34e
+- Authorized AIDs
+
+ - 0xA000000476416E64726F696443545340
+
+ 1. Authorized APDU for above AID: 0x00060000A0060000
+ 1. Unauthorized APDUs for above AID:
+
+ 1. 0x0008000000
+ 1. 0x80060000
+ 1. 0xA008000000
+ 1. 0x9406000000
+
+ - 0xA000000476416E64726F696443545341
+
+ 1. Authorized APDUs for above AID:
+
+ 1. 0x94060000
+ 1. 0x9408000000
+ 1. 0x940C000001AA00
+ 1. 0x940A000001AA
+
+ 1. Unauthorized APDUs for above AID:
+
+ 1. 0x00060000
+ 1. 0x80060000
+ 1. 0xA0060000
+ 1. 0x0008000000
+ 1. 0x000A000001AA
+ 1. 0x800A000001AA
+ 1. 0xA00A000001AA
+ 1. 0x8008000000
+ 1. 0xA008000000
+ 1. 0x000C0000001AA00
+ 1. 0x800C000001AA00
+ 1. 0xA00C000001AA00
+
+ - 0xA000000476416E64726F696443545342
+
+ - 0xA000000476416E64726F696443545344
+
+ - 0xA000000476416E64726F696443545345
+
+ - 0xA000000476416E64726F696443545347
+
+ - 0xA000000476416E64726F696443545348
+
+ - 0xA000000476416E64726F696443545349
+
+ - 0xA000000476416E64726F69644354534A
+
+ - 0xA000000476416E64726F69644354534B
+
+ - 0xA000000476416E64726F69644354534C
+
+ - 0xA000000476416E64726F69644354534D
+
+ - 0xA000000476416E64726F69644354534E
+
+ - 0xA000000476416E64726F69644354534F
+
+- Unauthorized AID:
+
+ - 0xA000000476416E64726F696443545343
+ - 0xA000000476416E64726F696443545346
+
+### 2. `CtsSecureElementAccessControlTestCases2`
+
+- Hash of the APK: 0x93b0ff2260babd4c2a92c68aaa0039dc514d8a33
+- Authorized AIDs:
+
+ - 0xA000000476416E64726F696443545340
+
+ 1. Authorized APDU for the above AID:
+
+ 1. 0x00060000
+ 1. 0xA0060000
+
+ 1. Unauthorized APDU for the above AID:
+
+ 1. 0x0008000000
+ 1. 0x80060000
+ 1. 0xA008000000
+ 1. 0x9406000000
+
+ - 0xA000000476416E64726F696443545341
+
+ 1. Authorized APDU for the above AID:
+
+ 1. 0x94060000
+ 1. 0x9408000000
+ 1. 0x940C000001AA00
+ 1. 0x940A000001AA
+
+ 1. Unauthorized APDU for the above AID:
+
+ 1. 0x0006000
+ 1. 0x80060000
+ 1. 0xA0060000
+ 1. 0x0008000000
+ 1. 0x000A000001AA
+ 1. 0x800A000001AA
+ 1. 0xA00A000001AA
+ 1. 0x8008000000
+ 1. 0xA008000000
+ 1. 0x000C000001AA00
+ 1. 0x800C000001AA00
+ 1. 0xA00C000001AA00
+
+ - 0xA000000476416E64726F696443545343
+
+ - 0xA000000476416E64726F696443545345
+
+ - 0xA000000476416E64726F696443545346
+
+- Unauthorized AIDs:
+
+ - 0xA000000476416E64726F696443545342
+ - 0xA000000476416E64726F696443545344
+ - 0xA000000476416E64726F696443545347
+ - 0xA000000476416E64726F696443545348
+ - 0xA000000476416E64726F69644354534A
+ - 0xA000000476416E64726F69644354534B
+ - 0xA000000476416E64726F69644354534C
+ - 0xA000000476416E64726F69644354534D
+ - 0xA000000476416E64726F69644354534E
+ - 0xA000000476416E64726F69644354534F
+
+### 3. `CtsSecureElementAccessControlTestCases3`
+
+- Hash of the APK: 0x5528ca826da49d0d7329f8117481ccb27b8833aa
+- Authorized AIDs:
+
+ - 0xA000000476416E64726F696443545340
+
+ 1. Authorized APDU for the above AID:
+
+ 1. 0x00060000
+ 1. 0x80060000
+ 1. 0xA0060000
+ 1. 0x94060000
+ 1. 0x000A000001AA
+ 1. 0x800A000001AA
+ 1. 0xA00A000001AA
+ 1. 0x940A000001AA
+ 1. 0x0008000000
+ 1. 0x8008000000
+ 1. 0xA008000000
+ 1. 0x9408000000
+ 1. 0x000C000001AA00
+ 1. 0x800C000001AA00
+ 1. A00C000001AA00
+ 1. 940C000001AA00
+
+ - 0xA000000476416E64726F696443545341
+
+ 1. Authorized APDU for the above AID:
+
+ 1. 0x94060000
+ 1. 0x9408000000
+ 1. 0x940C000001AA00
+ 1. 0x940A00000aAA
+
+ 1. Unauthorized APDU for the above AID:
+
+ 1. 0x00060000
+ 1. 0x80060000
+ 1. 0xA0060000
+ 1. 0x0008000000
+ 1. 0x000A000001AA
+ 1. 0x800A000001AA
+ 1. 0xA00A000001AA
+ 1. 0x8008000000
+ 1. 0xA008000000
+ 1. 0x000C000001AA00
+ 1. 0x800C000001AA00
+ 1. 0xA00C000001AA00
+
+ - 0xA000000476416E64726F696443545345
+
+ - 0xA000000476416E64726F696443545346
+
+- Unauthorized AIDs:
+
+ - 0xA000000476416E64726F696443545342
+ - 0xA000000476416E64726F696443545343
+ - 0xA000000476416E64726F696443545344
+ - 0xA000000476416E64726F696443545347
+ - 0xA000000476416E64726F696443545348
+ - 0xA000000476416E64726F69644354534A
+ - 0xA000000476416E64726F69644354534B
+ - 0xA000000476416E64726F69644354534C
+ - 0xA000000476416E64726F69644354534D
+ - 0xA000000476416E64726F69644354534E
+ - 0xA000000476416E64726F69644354534F
+
+## Appendix
+
+### Sample applet and installation steps for UICC
+
+#### 1. Package specification
+
+File name: `google-cardlet.cap`
+
+Package AID: 6F 6D 61 70 69 63 61 72 64 6C 65 74
+Version: 1.0
+SHA1: 5F72E0A073BA9E61A7358F2FE3F031
+SHA256: ECC1217AA0BC687DD89D5BB233F743
+
+Module AIDs:
+6F 6D 61 70 69 4A 53 52 31 37 37 = SelectResponse module
+6F 6D 61 70 69 43 61 63 68 69 6E 67 = XXLResponse module
+
+Imports:
+javacard.framework v1.3 - A0000000620101
+java.lang v1.0 - A0000000620001
+
+Size on card: 4463
+
+#### 2. Installation steps
+
+Load the `google-cardlet.cap` file to the SIM card using the appropriate
+procedure (check with your SE manufacturers).
+
+Run installation command for each applet.
+
+##### OMAPI tests
+
+Command to install applet
+
+<code>80E60C00300C6F6D617069636172646C65740B<var>module_AID</var>10<var>AID</var>010002C90000</code><br>
+Module_AID => 6F 6D 61 70 69 4A 53 52 31 37 37
+AID: A000000476416E64726F696443545331
+<code>80E60C00310C6F6D617069636172646C65740B<var>module_AID</var>10<var>AID</var>010002C9000</code><br>
+Module_AID => 6F 6D 61 70 69 43 61 63 68 69 6E 67
+AID: A000000476416E64726F696443545332
+
+##### AccessControl tests (template using PKCS#15 structure)
+
+<code>80E60C003C0C6F6D617069636172646C65740B<var>module_AID</var>10<var>AID</var>01000EEF0AA008810101A5038201C0C90000</code><br>
+Module_AID => 6F 6D 61 70 69 4A 53 52 31 37 37
+
+AIDs:
+
++ 0xA000000476416E64726F696443545340
++ 0xA000000476416E64726F696443545341
++ 0xA000000476416E64726F696443545342
++ 0xA000000476416E64726F696443545344
++ 0xA000000476416E64726F696443545345
++ 0xA000000476416E64726F696443545347
++ 0xA000000476416E64726F696443545348
++ 0xA000000476416E64726F696443545349
++ 0xA000000476416E64726F69644354534A
++ 0xA000000476416E64726F69644354534B
++ 0xA000000476416E64726F69644354534C
++ 0xA000000476416E64726F69644354534D
++ 0xA000000476416E64726F69644354534E
++ 0xA000000476416E64726F69644354534F
+
+For step-by-step commands to set up the PKCS#15 structure matching the CTS
+tests, see
+[Commands for PKCS#15](/compatibility/cts/images/commands-for-pkcs15.pdf).
diff --git a/en/compatibility/cts/sensor-fusion-box-assembly.md b/en/compatibility/cts/sensor-fusion-box-assembly.md
new file mode 100644
index 0000000..adba778
--- /dev/null
+++ b/en/compatibility/cts/sensor-fusion-box-assembly.md
@@ -0,0 +1,218 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Sensor Fusion Box Assembly
+
+This page provides step-by-step instructions for assembling a Sensor Fusion
+Box. The Sensor Fusion Box is used in the CameraITS sensor_fusion test and
+multi-camera sync test. It provides a consistent test environment for measuring
+timestamp accuracy of camera and other sensors for Android phones. It consists
+of plastic box components that are laser cut from computer-aided design (CAD)
+drawings and a Servo Control Box.
+
+You can purchase a Sensor Fusion Box or build your own.
+
+## Purchasing a Sensor Fusion Box
+
+We recommend purchasing a Sensor Fusion Box from one of the following qualified
+vendors.
+
+* *Acu Spec, Inc.*
+ 990 Richard Ave, Ste 103, Santa Clara, CA 95050
+ fred@acuspecinc.com
+* *MYWAY DESIGN*
+ Website: http://www.myway.tw/
+ Fu-ming (Troy) Tsai, tsaifuming0205@gmail.com
+
+## Building a Sensor Fusion Box
+
+This section includes step-by-step instructions for assembling a Sensor Fusion
+Box from laser-cut plastic components (shown in Figure 1):
+
+<img src="images/sensor_fusion_assembly_box_cad_drawing.png" width="700" alt="CAD drawing of Sensor Fusion Box components">
+**Figure 1.** CAD drawing of Sensor Fusion Box components
+
+### Required tools
+
+Before starting, ensure you have downloaded the technical drawings for the
+Sensor Fusion Box (included in the [Sensor Fusion Box 1.3.zip
+file](sensor_fusion_box_1.3.zip)) and
+have the following tools available:
+
+* Phillips head screwdriver
+* Power drill set
+* Exacto knife
+* Tape
+
+### Step 1: Apply vinyl stickers
+
+After creating the plastic components with a laser cutter, you can apply vinyl
+stickers to the plastic box components:
+
+1. Apply vinyl on the smooth side of the ABS (acrylonitrile butadiene styrene)
+ as shown in **Figure 2**. For helpful tips on applying vinyl, refer to
+ [wikiHow](https://www.wikihow.com/Install-a-Vinyl-Graphic).
+1. Cut out the necessary holes on the vinyl.
+
+ <img src="images/sensor_fusion_assembly_abs_pieces.png" width="350" alt="BS pieces">
+ **Figure 2.** ABS pieces with vinyl applied on the smooth side (interior of
+ the box)
+
+### Step 2: Attach servo
+
+To attach the servo:
+
+1. Tap three holes on the phone fixture with ¼" - 20, and make countersink
+ holes on the back of the phone fixture:
+ <table class="columns">
+ <tr>
+ <td><img src="images/sensor_fusion_assembly_phone_fixture_holes1.png" width="250" alt="Phone fixture tap holes"></td>
+ <td><img src="images/sensor_fusion_assembly_phone_fixture_holes2.png" width="250" alt="Phone fixture countersink holes"></td>
+ </tr>
+ </table>
+ **Figure 3.** Phone fixture with tap and countersink holes shown
+
+1. With the large shaft that came with the servo, drill pilot holes with #43
+ drill bit (2.26 mm) into the last holes from each side so 4-40 screws could
+ grab onto them:
+
+ <img src="images/sensor_fusion_assembly_servo_shaft.png" width="350" alt="Servo shaft">
+ **Figure 4.** Servo shaft with pilot holes at each end
+
+1. Apply the flat-head 4-40 screws on the front of the phone fixture and
+ tighten the shaft:
+
+ <img src="images/sensor_fusion_assembly_shaft_screws.png" width="350" alt="Shaft and screws">
+ **Figure 5.** Phone fixture front with shaft and screws shown
+
+ <img src="images/sensor_fusion_assembly_shaft.png" width="350" alt="Shaft">
+ **Figure 6.** Shaft on the back of fixture, tightened by screws applied
+ from the front
+
+### Step 3: Attach clamp & rails
+
+To attach the clamp and rails:
+
+1. Apply nylon thumb screws, rubber adhesive, and wire to the aluminum clamp:
+
+ <img src="images/sensor_fusion_assembly_clamp.png" width="350" alt="Clamp with rubber adhesive">
+ **Figure 7.** Clamp with rubber adhesive, thumb screws and wire
+
+1. Screw the phone clamps' thumb screws into the tapped holes of the phone
+ fixture.
+
+ * CAD Drawing:
+
+ <img src="images/sensor_fusion_assembly_clamp_attachment_cad_drawing.png" width="450" alt="CAD drawing of clamp attachment">
+ **Figure 8.** CAD drawing of clamp attachment to phone fixture
+
+ * Actual clamp attachment to phone fixture:
+
+ <img src="images/sensor_fusion_assembly_assembled_fixture.png" width="350" alt="Assembled phone fixture">
+ **Figure 9.** Assembled phone fixture
+
+1. Fix rails on top and bottom of box towards the front. The figure below shows
+ 6-32 screws on pre-tapped holes, but you can use self-tapping screws instead
+ if desired.
+
+ <img src="images/sensor_fusion_assembly_fixed_rail.png" width="350" alt="Fixed rail">
+ **Figure 10.** Fixed rail on top and bottom of box
+
+### Step 4: Attach lighting
+
+To attach the light brackets and diffuser:
+
+1. Stack two handle pieces and connect using 6-32 screws (or use self-tapping
+ screws):
+
+ <img src="images/sensor_fusion_assembly_handle_pieces.png" width="450" alt="Handle pieces and assembly">
+ **Figure 11.** Sensor fusion box handle pieces and assembly
+
+1. Prepare four 4-40 screws and nuts to fix the mounting bracket from the
+ lighting kit to the wall of the box:
+
+ <img src="images/sensor_fusion_assembly_interior_wall_screws.png" width="350" alt="Screws and bracket on interior wall">
+ **Figure 12.** Screws and light bracket on the interior wall of the box
+ <img src="images/sensor_fusion_assembly_exterior_bolts.png" width="350" alt="Exterior with bolts applied">
+ **Figure 13.** Bolts applied to the screws from the exterior of the box
+
+1. Snap the lights into the brackets (can be a tight fit):
+
+ <img src="images/sensor_fusion_assembly_interior_wall_lights.png" width="450" alt="Lights on interior wall">
+ **Figure 14.** Lights fixed to the interior wall with brackets
+
+1. Cut the light diffuser to an appropriate size to wrap the light strips:
+
+ <img src="images/sensor_fusion_assembly_light_strips_diffusers.png" width="350" alt="Light strips and diffusers">
+ **Figure 15.** Light strips and light diffusers
+
+1. Wrap the light diffuser around the strip and tape it at the back:
+
+ <img src="images/sensor_fusion_assembly_strips_taped_back.png" width="350" alt="Strips and diffusers taped from back">
+ **Figure 16.** Light strips and light diffusers taped from the back
+
+### Step 5: Attach phone fixture to servo plate
+
+To attach the phone fixture to the servo plate:
+
+1. Prepare four 6-32 screws and servo plate to fix the servo onto the wall.
+ The screws go from inside and fix themselves onto the servo plate that is
+ on the exterior of the wall.
+
+ <img src="images/sensor_fusion_assembly_servo_servo_plate.png" width="450" alt="Servo and servo plate">
+ **Figure 17.** Servo and servo plate held in place with 6-32 screws
+
+1. Secure phone fixture onto the servo with nylocks (pushing the center of the
+ shaft into the servo's rotation center):
+
+ <img src="images/sensor_fusion_assembly_phone_fixture.png" width="450" alt="Phone fixture on servo">
+ **Figure 18.** Phone fixture on servo
+
+1. Screw the phone fixture onto the servo with its servo screw:
+
+ <img src="images/sensor_fusion_assembly_servo_screw.png" width="350" alt="Phone fixture on servo with screw">
+ **Figure 19.** Securing phone fixture onto servo with servo screw
+
+### Step 6: Final assembly
+
+To complete final assembly of the Sensor Fusion Box:
+
+1. Secure servo control box on the left of the servo with 4-40 screws from the
+ outside and fastened from the inside with nuts:
+
+ <img src="images/sensor_fusion_assembly_servo_on_wall.png" width="450" alt="Servo control box on wall">
+ **Figure 20.** Secure servo control box onto the wall
+
+1. Tape the box together, then screw the parts together (you might need to pre-drill some holes in some parts).
+
+ * CAD drawing:
+
+ <img src="images/sensor_fusion_assembly_complete_box_drawing.png" width="450" alt="Complete box CAD drawing">
+ **Figure 21.** CAD drawing of complete Sensor Box
+
+ * Actual Sensor Fusion Box:
+
+ <img src="images/sensor_fusion_assembly_taped_box.png" width="450" alt="Taped box">
+ **Figure 22.** Taped box with motor assembly and servo control box and screw detail
+
+1. Print out a colored copy of the checkerboard (included in the [Sensor Fusion Box 1.3.zip file](sensor_fusion_box_1.3.zip)) on A3 (or 11 x 17 inch paper), and tape it on the opposite wall of the phone fixture.
+
+ Make sure the red dot in the center of the checkerboard is directly facing
+ the camera when placed on the fixture, as shown below:
+
+ <img src="images/sensor_fusion_assembly_checkerboard.png" width="350" alt="Checkerboard">
+ **Figure 23.** Checkerboard printed and taped to the opposite wall of phone
+ fixture
diff --git a/en/compatibility/cts/sensor-fusion-quick-start.html b/en/compatibility/cts/sensor-fusion-quick-start.html
new file mode 100644
index 0000000..521e5be
--- /dev/null
+++ b/en/compatibility/cts/sensor-fusion-quick-start.html
@@ -0,0 +1,198 @@
+<html devsite>
+ <head>
+ <title>Sensor Fusion Box Quick Start Guide</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ <body>
+ <!--
+ Copyright 2018 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 sensor fusion test measures timestamp accuracy of camera and other
+ sensors for Android phones. This page provides step-by-step directions on
+ how to setup the Sensor Fusion test and Sensor Fusion Box for the first
+ time.
+ </p>
+ <h2 id="required-tools">Required tools</h2>
+ <p>
+ Before getting started, ensure you have the following cables and cords
+ available:</p>
+ <figure id="sensor-fusion-test-component">
+ <img src="images/sensor_fusion_test_components.png" width="700" alt="Sensor fusion test components">
+ <figcaption><b>Figure 1.</b> Components required for the sensor fusion test</figcaption>
+ </figure>
+ <ul>
+ <li>USB A to B cable</li>
+ <li>USB A to C cable (for test phone)</li>
+ <li>12V power cord (for servo control box)</li>
+ <li>12V power cord (for lighting, with switch)</li>
+ <li>Interconnected cable (for lighting)</li>
+ <li>Conversion cable (for lighting)</li>
+ </ul>
+ <h2 id="step-1-connect-lights">Step 1: Connect lights</h2>
+ <p>
+ To connect the lights:
+ </p>
+ <ol>
+ <li>Use the interconnected cable to connect the two lights.</li>
+ <li>Connect one light to the conversion cable.
+ <figure id="sensor-fusion-connect-lights">
+ <img src="images/sensor_fusion_connect_lights.png" width="300" alt="Connect lights">
+ <figcaption><b>Figure 2.</b> Connecting the lights to each other and one light to the conversion cable</figcaption>
+ </figure>
+ </li>
+ <li>Thread the unconnected end of the conversion cable through the round
+ hole that exits the box, then connect the end of that cable to the power
+ cable for lighting.
+ <table class="columns">
+ <tr>
+ <td><img src="images/sensor_fusion_conversion_cable1.png" width="" alt="Conversion cable and power cable"></td>
+ <td><img src="images/sensor_fusion_conversion_cable2.png" width="" alt="Power cable for lighting"></td>
+ </tr>
+ </table>
+ <b>Figure 3.</b> Lighting conversion cable exiting the box and connecting
+ to power cable</li>
+ </ol>
+ <h2 id="step-2-attach-servo">Step 2: Attach servo</h2>
+ <p>
+ To attach the servo:
+ </p>
+ <ol>
+ <li>Plug the servo connector into the servo control. Be sure to insert
+ the connector oriented to the corresponding colors as labeled (Y =
+ Yellow, R = Red, B = Black), as reversing the order could damage the
+ motor.
+ <figure id="sensor-fusion-servo-connector">
+ <img src="images/sensor_fusion_servo_connector.png" width="300" alt="Servo connecting to the servo control box">
+ <figcaption><b>Figure 4.</b> Servo connecting to the servo control box</figcaption>
+ </figure>
+ <li>Connect the servo control with its power cord (the lighting and
+ servo control have independent, dedicated power supplies).
+ <table class="columns">
+ <tr>
+ <td><img src="images/sensor_fusion_servo_control1.png" width="" alt="Servo control"></td>
+ <td><img src="images/sensor_fusion_servo_control2.png" width="" alt="Power to servo control"></td>
+ </tr>
+ </table>
+ <b>Figure 5.</b> Connecting the servo control to its dedicated power
+ cord
+ <li>Use the USB A to B cable to connect the servo control box to the
+ host (machine that is running the test).
+ <table class="columns">
+ <tr>
+ <td><img src="images/sensor_fusion_servo_control_box1.png" width="" alt="Connect servo control box"></td>
+ <td><img src="images/sensor_fusion_servo_control_box2.png" width="" alt="Connect servo control box to host"></td>
+ </tr>
+ </table>
+ <b>Figure 6.</b> Connecting the servo control box to the host machine</li>
+ </ol>
+ <h2 id="step-3-attach-phone">Step 3: Attach phone</h2>
+ <ol>
+ <li>Set the phone on the fixture and clamp it down.<br>
+ <table class="columns">
+ <tr>
+ <td><img src="images/sensor_fusion_fixture1.png" width="" alt="Phone on fixture"></td>
+ <td><img src="images/sensor_fusion_fixture2.png" width="" alt="Clamping phone on fixture"></td>
+ </tr>
+ </table>
+ <b>Figure 7.</b> Placing and clamping the phone on the fixture
+ <p> The upside-down thumb screw provides back support while the
+ other screw tightens the grip by turning right. For more help,
+ refer to the video on loading the phone (included in the <a
+ href="sensor_fusion_box_1.3.zip">Sensor Fusion Box zip file</a>).
+ </p>
+ </li>
+ <li>Use a zip tie to hold the phone USB cord to the fixture plate and
+ lead it outside the box through the exit hole. Plug the other end
+ of the cord to the host running the test.
+ <figure id="sensor-fusion-zip-ties">
+ <img src="images/sensor_fusion_zip_ties.png" width="300" alt="Phone USB cord with zip ties">
+ <figcaption><b>Figure 8.</b> Phone USB cord held to fixture with
+ zip ties</figcaption>
+ </figure>
+ </li>
+ </ol>
+ <h2 id="step-4-run-test-script">Step 4: Run test script</h2>
+ <p>
+ The main python executable for the test script is:
+ </p>
+ <pre class="prettyprint">python tools/run_all_tests.py device=ID camera=0 scenes=sensor_fusion rot_rig=default</pre>
+ <p>You can also enter the actual rotator address at the command line
+ using:</p>
+ <pre class="prettyprint">rot_rig=VID:PID:CH</pre>
+ <ul>
+ <li>To determine the Vendor ID (VID) and Product ID (PID), use the Linux
+ command <code>lsusb</code>.</li> <li>By default, the VID and PID are set
+ to <code>04d8</code> and <code>fc73</code> with channel "1".</li>
+ </ul>
+ <h3 id="multiple-runs-different-formats">Multiple runs, different formats</h3>
+ <p>To perform multiple runs with different formats, you can use a
+ different script (however, the results will not be uploaded to
+ <code>CtsVerifier.apk</code>). Sample test script: </p>
+ <pre class="prettyprint">python tools/run_sensor_fusion_box.py device=FA7831A00278 camera=0 rotator=default img_size=640,360 fps=30 test_length=7</pre>
+ <h3 id="permission-issues">Permission issues</h3>
+ <p>To resolve permission issues related to controlling the motor through the
+ USB port:</p>
+ <ol>
+ <li>Add the operator username to <code>dialout</code> group using:
+ <pre class="prettyprint">sudo adduser $username dialout</pre></li>
+ <li>Log out the operator.</li>
+ <li>Log in the operator.</li>
+ </ol>
+ <h2>Adjusting the motor</h2>
+ <p>
+ You can adjust the speed of the motor and the distance the phone' travels
+ using the resistance ports (labelled <strong>A</strong>,
+ <strong>B</strong>, and <strong>T</strong>) on the side of the controller
+ box.
+ </p>
+ <ol>
+ <li>Ensure the phone fixture travels a full 90 degrees (from 12
+ o'clock to 9 o'clock when looking at the phone) for each rotation.
+ <ul>
+ <li>To adjust the distance travelled, use the <strong>A</strong> and
+ <strong>B</strong> screws (where <strong>A</strong> is the starting
+ location
+ and <strong>B</strong> is the final location).</li>
+ <li>Upon first receiving the box, it is easiest to power up the box and
+ determine the initial position. If the initial position on power-up
+ is not close to 12 o'clock, unscrew the phone fixture (single Philips
+ head screw in mount hole) and rotate the phone fixture to 12
+ o'clock.</li>
+ </ul>
+ </li>
+ <li>Adjust the rotation speed to travel a full rotation in 1.5s. Turning
+ the resistor pot clockwise slows down the motion.
+ <table class="columns">
+ <tr>
+ <td>
+ <img src="images/sensor_fusion_adjust.png" width="" alt="Adjust position and speed of servo">
+ </td>
+ <td>
+ <ul>
+ <li>A is the start position of the fixture.</li>
+ <li>B is the end position of the fixture.</li>
+ <li>T is the speed motor rotates.</li>
+ </ul>
+ </td>
+ </tr>
+ </table>
+ <b>Figure 9.</b> How to adjust the position and speed of servo and phone
+ fixture
+ </li>
+ </ol>
+ <p>
+ For more help, refer to the video of the sensor fusion box running (included in the <a href=sensor_fusion_box_1.3.zip>Sensor Fusion Box zip file</a>).
+ </p>
+</body>
+</html>
diff --git a/en/compatibility/cts/sensor_fusion_box_1.3.zip b/en/compatibility/cts/sensor_fusion_box_1.3.zip
new file mode 100644
index 0000000..814f83e
--- /dev/null
+++ b/en/compatibility/cts/sensor_fusion_box_1.3.zip
Binary files differ
diff --git a/en/compatibility/cts/setup.html b/en/compatibility/cts/setup.html
index a09efbc..6efc82d 100644
--- a/en/compatibility/cts/setup.html
+++ b/en/compatibility/cts/setup.html
@@ -24,6 +24,7 @@
<h2 id=physical_environment>Physical environment</h2>
+
<h3 id=ble_beacons>Bluetooth LE beacons</h3>
<p>If the DUT supports the Bluetooth LE feature, then at least three
Bluetooth LE beacons should be placed within five meters of the DUT for Bluetooth
@@ -31,6 +32,16 @@
configured or emit anything specific, and can include iBeacon,
Eddystone, or even devices simulating BLE beacons.</p>
+<h3 id=camera>Cameras</h3>
+<p>When running camera CTS, you are recommended to use normal lighting
+conditions with a test pattern chart (such as a checkerboard pattern) that is
+not too close to the lens (the distance depends on the device's minimum focus
+distance).</p>
+
+<p>If the DUT supports external cameras, such as USB
+webcams, then an external camera must be plugged in when running CTS.
+Otherwise, the CTS tests will fail.</p>
+
<h3 id="gnss">GPS/GNSS</h3>
<p>If the DUT supports the Global Positioning System (GPS) Global Navigation
Satellite System (GNSS) feature, then a GPS/GNSS signal, with GPS portion
@@ -61,6 +72,18 @@
href="http://en.wikipedia.org/wiki/List_of_IPv6_tunnel_brokers">list of IPv6
tunnel brokers</a>.</p>
+<h3 id="rtt">Wi-Fi RTT (Round Trip Time)</h3>
+<p>Android 9 adds an API for a <a ref="/devices/tech/connect/wifi-rtt">Wi-Fi RTT</a> capability, which
+allows devices to measure their distance to access points with an accuracy of 1 to 2 meters,
+thus increasing indoor location accuracy significantly. Here are two recommended devices
+supporting Wi-Fi RTT: <a href="https://store.google.com/product/google_wifi">Google Wifi</a>
+and <a href="https://fit-iot.com/web/products/fitlet2/">Compulab's Filet2 Access Point</a> (set to 40MHz bandwidth at 5GHz).</p>
+
+<p>The access points should be powered up, but not required to be connected to any network.
+Access points do not need to be next to the testing device; however, they are recommended to be within a distance of 40 ft from the DUT.
+One access point is typically sufficient.</p>
+
+
<h2 id=desktop_setup>Desktop machine setup</h2>
<aside class="caution"><strong>Caution:</strong> CTS currently supports 64-bit
Linux and Mac OS host machines. CTS will not work on Windows OS.</aside>
@@ -182,6 +205,14 @@
preload the apps into the appropriate directories on the system image without
re-signing them.</p>
+ <h3 id=sample-applet>Sample Applet</h3>
+ <p>Android 9 introduced Open Mobile API Test cases, which are used to check if the
+underlying implementation of Secure Elements are implemented as per standard. These test
+cases would require the installation of a special applet which can be used by the
+CTS application to communicate with. One can use the <a href="https://android-review.googlesource.com/c/platform/cts/+/700517">sample applet</a> as provided.</p>
+ <p>This is applicable to devices, which have eSE(embedded Secure Element), SIM or SDs. See <a href="/compatibility/cts/secure-element">CTS Test for Secure Element</a> for more detailed information on Open Mobile
+API Test cases and Access Control Test cases.</p>
+
<h3 id=storage_requirements>Storage requirements</h3>
<p>The CTS media stress tests require video clips to be on external storage
(<code>/sdcard</code>). Most of the clips are from <a
@@ -208,8 +239,8 @@
one with at least speed class 10 or higher to ensure it can pass the CTS.</em>
<p class="warning"><strong>Warning:</strong> CTS may modify/erase data on the SD card plugged into the device.</p>
</li>
-<li>If the device has SIM card slots, plug in an activated SIM card to each slot. If the device supports SMS, each SIM card should have its own number field populated.</li>
-</li>
+<li>If the device has SIM card slots, plug in an activated SIM card to each slot. If the device
+ supports SMS, each SIM card should have its own number field populated.</li>
</ol>
<h3 id=developer_uicc>Developer UICC</h3>
@@ -222,7 +253,7 @@
<h2 id=config_device>Android device configuration</h2>
<ol>
<li>Factory data reset the device: <strong>Settings > Backup & reset > Factory data reset</strong>
- <p class="warning"><strong>Warning:</strong> This will erase all user data from the device.</em></p>
+ <p class="warning"><strong>Warning:</strong> This will erase all user data from the device.</p>
<li>Set your device's language to English (<strong>United States</strong>) from: <strong>Settings > Language
& input > Language</strong>
<li>Turn on the location setting if there is a GPS or Wi-Fi / Cellular network
diff --git a/en/compatibility/cts/verifier.html b/en/compatibility/cts/verifier.html
index 5483e0d..118087b 100644
--- a/en/compatibility/cts/verifier.html
+++ b/en/compatibility/cts/verifier.html
@@ -38,6 +38,8 @@
be through this port.</li>
<li>Second Android device with a known compatible Bluetooth, Wi-Fi direct, and
NFC Host Card Emulation (HCE) implementation.</li>
+<li>A Wi-Fi router configured with access point name and password. The router
+should have the ability to disconnect from the internet, but not powered off.</li>
</ul>
<h2 id=setup>Setting up</h2>
diff --git a/en/compatibility/index.html b/en/compatibility/index.html
deleted file mode 100644
index a905170..0000000
--- a/en/compatibility/index.html
+++ /dev/null
@@ -1,98 +0,0 @@
-<html devsite>
- <head>
- <title>Android Compatibility</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's purpose is to establish an open platform for developers to build
-innovative apps.</p>
-<ul>
-<li>The Android Compatibility program defines technical details of the
-Android platform and provides tools for OEMs to ensure developer applications
-run on a variety of devices.</li>
-<li>The Android SDK provides built-in tools for developers to clearly state the
-device features required by their applications.</li>
-<li>Google Play shows applications only to those devices that can properly run
-those applications.</li>
-</ul>
-
-<h2 id="why-build-compatible-android-devices">Why build compatible Android
-devices?</h2>
-
-<h3 id="users-want-a-customizable-device">Users want customizable devices</h3>
-
-<div class="attempt-right">
- <img src="images/compat-ecosystem.png" alt="Compatibility ecosystem" id="figure1" />
- <p class="img-caption">
- <strong>Figure 1.</strong> The Android ecosystem thrives with device compatibility
- </p>
-</div>
-
-<p>A mobile phone is a highly personal, always-on, always-present gateway to
-the Internet. We haven't met a user yet who didn't want to customize it by
-extending its functionality. That's why Android was designed as a robust
-platform for running aftermarket applications.</p>
-
-<h3 id="developers-outnumber-us-all">Developers outnumber us all</h3>
-<p>No device manufacturer can write all the software a user could conceivably
-need. We need third-party developers to write the apps users want, so the
-Android Open Source Project (AOSP) aims to make application development as easy
-and open as possible.</p>
-
-<h3 id="everyone-needs-a-common-ecosystem">Everyone needs a common ecosystem</h3>
-<p>Every line of code developers write to work around a bug is a line of code
-that didn't add a new feature. The more compatible mobile devices are, the more
-applications we'll have to run on those devices. By building a fully compatible
-Android device, you benefit from the huge pool of apps written for Android while
-increasing the incentive for developers to build more apps.</p>
-
-<h2 id="android-compatibility-is-free-and-its-easy">Android compatibility is
-free, and it's easy</h2>
-<p>To build an Android-compatible mobile device, follow this three-step
-process:</p>
-<ol>
-<li><em>Obtain the <a href="/setup/index.html">Android software source
-code</a></em>. This is the source code for the Android platform that you port
-to your hardware.</li>
-<li><em>Comply with the Android Compatibility Definition Document (CDD)</em>
-(<a href="/compatibility/android-cdd.pdf">PDF</a>, <a
-href="/compatibility/android-cdd.html">HTML</a>). The CDD enumerates
-the software and hardware requirements of a compatible Android device.</li>
-<li><em>Pass the <a href="/compatibility/cts/">Compatibility
-Test Suite (CTS)</a></em>. Use the CTS as an ongoing aid to evaluate
-compatibility during the development process.</li> </ol>
-
-<p>After complying with the CDD and passing the CTS, your device is Android
-compatible, meaning Android apps in the ecosystem provide a consistent
-experience when running on your device. For details about the Android
-compatibility program, see the <a href="overview.html">program overview</a>.</p>
-
-<h2 id="licensing-gms">Licensing Google Mobile Services (GMS)</h2>
-<p>After building an Android compatible device, consider licensing Google Mobile
-Services (GMS), Google’s proprietary suite of apps (Google Play, YouTube, Google
-Maps, Gmail, and more ) that run on top of Android. GMS is not part of the
-Android Open Source Project and is available only through a license with Google.
-For information on how to request a GMS license, see
-<a href="contact-us.html">Contact Us</a>.</p>
-
- </body>
-</html>
diff --git a/en/compatibility/index.md b/en/compatibility/index.md
new file mode 100644
index 0000000..83d9dc5
--- /dev/null
+++ b/en/compatibility/index.md
@@ -0,0 +1,50 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Design an Android Device
+
+Being open source, Android offers a near-infinite combination of hardware and
+software for you to develop devices undreamt by even the operating system's
+creators.
+
+Still, for your users to have a coherent experience as they adopt additional
+Android devices, consider following established standards while designing and
+customizing your implementation.
+
+1. Review the fundamental principles of Android platform development within
+ [Architecture](/devices/architecture/), particularly the
+ [HIDL](/devices/architecture/hidl/) format introduced in Android 8.0.
+
+1. Ensure your devices meet requirements to be deemed
+ [compatible](/compatibility/overview) with Android’s core specification, the
+ [Android Compatibility Definition Document](/compatibility/cdd).
+
+1. See the [Display](/devices/tech/display/) features and
+ [Settings](/devices/tech/settings/settings-guidelines) guidelines for
+ help with the user interface.
+
+1. Take advantage of all of the [tests](/compatibility/tests) available to debug
+ and improve your Android devices.
+
+1. Familiarize yourself with
+ [App Design](https://developer.android.com/design/){: .external} principles and
+ [Material Design](https://material.io/design/){: .external} techniques when
+ developing user-facing applications.
diff --git a/en/compatibility/overview.html b/en/compatibility/overview.html
index 962a5b7..85b7444 100644
--- a/en/compatibility/overview.html
+++ b/en/compatibility/overview.html
@@ -1,6 +1,6 @@
<html devsite>
<head>
- <title>Compatibility Program Overview</title>
+ <title>Android Compatibility Program Overview</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
@@ -23,8 +23,47 @@
-<p>The Android compatibility program makes it easy for mobile device
-manufacturers to develop compatible Android devices.</p>
+<p>Android's purpose is to establish an open platform for developers to build
+innovative apps.</p>
+<ul>
+<li>The Android Compatibility program defines technical details of the
+Android platform and provides tools for OEMs to ensure developer applications
+run on a variety of devices.</li>
+<li>The Android SDK provides built-in tools for developers to clearly state the
+device features required by their applications.</li>
+<li>Google Play shows applications only to those devices that can properly run
+those applications.</li>
+</ul>
+
+<h2 id="why-build-compatible-android-devices">Why build compatible Android
+devices?</h2>
+
+<h3 id="users-want-a-customizable-device">Users want customizable devices</h3>
+
+<div class="attempt-right">
+ <img src="images/compat-ecosystem.png" alt="Compatibility ecosystem" id="figure1" />
+ <p class="img-caption">
+ <strong>Figure 1.</strong> The Android ecosystem thrives with device compatibility
+ </p>
+</div>
+
+<p>A mobile phone is a highly personal, always-on, always-present gateway to
+the Internet. We haven't met a user yet who didn't want to customize it by
+extending its functionality. That's why Android was designed as a robust
+platform for running aftermarket applications.</p>
+
+<h3 id="developers-outnumber-us-all">Developers outnumber us all</h3>
+<p>No device manufacturer can write all the software a user could conceivably
+need. We need third-party developers to write the apps users want, so the
+Android Open Source Project (AOSP) aims to make application development as easy
+and open as possible.</p>
+
+<h3 id="everyone-needs-a-common-ecosystem">Everyone needs a common ecosystem</h3>
+<p>Every line of code developers write to work around a bug is a line of code
+that didn't add a new feature. The more compatible mobile devices are, the more
+applications we'll have to run on those devices. By building a fully compatible
+Android device, you benefit from the huge pool of apps written for Android while
+increasing the incentive for developers to build more apps.</p>
<h2 id="program-goals">Program goals</h2>
@@ -39,7 +78,7 @@
<ul>
<li>
<p><em>Provide a consistent application and hardware environment to application
-developers.</em>
+developers.</em>
Without a strong compatibility standard, devices can vary so
greatly that developers must design different versions of their applications
for different devices. The compatibility program provides a precise definition
@@ -87,10 +126,39 @@
<li>The <a href="cts/index.html">Compatibility Test Suite (CTS)</a>, representing the "mechanism" of compatibility</li>
</ul>
+<h2 id="android-compatibility-is-free-and-its-easy">Android compatibility is
+free, and it's easy</h2>
+<p>To build an Android-compatible mobile device, follow this three-step
+process:</p>
+<ol>
+<li><em>Obtain the <a href="/setup/index.html">Android software source
+code</a></em>. This is the source code for the Android platform that you port
+to your hardware.</li>
+<li><em>Comply with the Android Compatibility Definition Document (CDD)</em>
+(<a href="/compatibility/android-cdd.pdf">PDF</a>, <a
+href="/compatibility/android-cdd.html">HTML</a>). The CDD enumerates
+the software and hardware requirements of a compatible Android device.</li>
+<li><em>Pass the <a href="/compatibility/cts/">Compatibility
+Test Suite (CTS)</a></em>. Use the CTS as an ongoing aid to evaluate
+compatibility during the development process.</li> </ol>
+
+<p>After complying with the CDD and passing the CTS, your device is Android
+compatible, meaning Android apps in the ecosystem provide a consistent
+experience when running on your device. For details about the Android
+compatibility program, see the <a href="overview.html">program overview</a>.</p>
+
<p>Just as each version of the Android platform exists in a separate branch in
the source code tree, there is a separate CTS and CDD for each version as
-well. The CDD, CTS, and source code are -- along with your hardware and your
-software customizations -- everything you need to create a compatible device.</p>
+well. The CDD, CTS, and source code are — along with your hardware and your
+software customizations — everything you need to create a compatible device.</p>
+
+<h2 id="licensing-gms">Licensing Google Mobile Services (GMS)</h2>
+<p>After building an Android compatible device, consider licensing Google Mobile
+Services (GMS), Google’s proprietary suite of apps (Google Play, YouTube, Google
+Maps, Gmail, and more) that run on top of Android. GMS is not part of the
+Android Open Source Project and is available only through a license with Google.
+For information on how to request a GMS license, see our
+<a href="/setup/community#for-business-inquiries">Contact/Community</a> page.</p>
</body>
</html>
diff --git a/en/compatibility/tests.md b/en/compatibility/tests.md
new file mode 100644
index 0000000..9b22f0b
--- /dev/null
+++ b/en/compatibility/tests.md
@@ -0,0 +1,63 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Tests
+
+As an open source operating system, Android offers many testing and debugging
+tools. First, take a moment to understand the
+[basics](https://android.googlesource.com/platform/platform_testing/+/master/docs/basics/index.md){: .external}
+of testing and then explore the options below.
+
+## Atest
+
+[Atest](https://android.googlesource.com/platform/tools/tradefederation/+/master/atest/README.md){: .external}
+is a command line tool that allows users to build, install and run Android tests
+locally.
+
+## Compatibility Test Suite (CTS)
+
+The [Compatibility Test Suite](/compatibility/cts/) (CTS) is a free,
+commercial-grade test suite that runs on a desktop machine and executes test
+cases directly on attached devices or an emulator.
+
+## Vendor Test Suite (VTS)
+
+The [Vendor Test Suite](/compatibility/vts/) (VTS) automates HAL and OS kernel
+testing. To use VTS to test an Android native system implementation, set up a
+testing environment then test a patch using a VTS plan.
+
+## Trade Federation Testing Infrastructure
+
+[Trade Federation](/devices/tech/test_infra/tradefed/) (tradefed or TF for
+short) is a continuous test framework designed for running tests on Android
+devices. TF can run functional tests locally, at your desk, within your platform
+checkout. There are two required files to run a test in TF, a java test source
+and an XML config. See
+[RebootTest.java](https://android.googlesource.com/platform/tools/tradefederation/contrib/+/master/src/com/android/example/RebootTest.java){: .external}
+and
+[reboot.xml](https://android.googlesource.com/platform/tools/tradefederation/contrib/+/master/res/config/example/reboot.xml){: .external}
+for examples.
+
+## Debugging
+
+The [Debugging](/devices/tech/debug/) section summarizes useful tools and related
+commands for debugging, tracing, and profiling native Android platform code when
+developing platform-level features.
diff --git a/en/compatibility/vts/automated-test-infra.html b/en/compatibility/vts/automated-test-infra.html
new file mode 100644
index 0000000..8d6d30d
--- /dev/null
+++ b/en/compatibility/vts/automated-test-infra.html
@@ -0,0 +1,252 @@
+<html devsite>
+ <head>
+ <title>Automated Testing Infrastructure</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ <body>
+ {% include "_versions.html" %}
+ <!--
+ Copyright 2018 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 {{ androidPVersionNumber }} includes a Vendor Test Suite (VTS)
+ infrastructure for automated testing of VTS, CTS, or other tests on partner
+ devices running the AOSP generic system image (GSI). Previously, running these
+ tests was a highly manual operation; the new VTS test infrastructure is
+ designed to support automated testing multiple times a day on multiple
+ devices.
+</p>
+
+<h2 id=architecture>Architecture</h2>
+
+<p>
+ The VTS automated testing infrastructure uses the following architecture:
+ </p>
+
+<p>
+ <img src="images/vts-automated.png"
+ alt="Automated test architecture"
+ title="Automated test architecture"">
+</p>
+<figcaption>
+ <strong>Figure 1.</strong> VTS automated testing infrastructure architecture
+</figcaption>
+
+<p>
+ When a test is triggered, the VTS automated testing infrastructure performs
+ the following tasks:
+</p>
+
+<ol>
+ <li>Fetches build artifacts and test resources from different locations:
+ <ul>
+ <li><strong>Partner Android Build (PAB)</strong>. For the GSI, VTS
+ framework, and some other builds.</li>
+ <li><strong>Local filesystem, Google Cloud Storage, or other vendor-specific
+ build system</strong>. For partners who do not store builds in Google's
+ cloud.</li>
+ </ul>
+ </li>
+ <li>Flashes build artifacts (from the device) and the GSI (from AOSP) onto the
+ connected device(s).</li>
+ <li>Runs VTS tests using local TradeFed or a TradeFed in the cloud.</li>
+ <li>Reports test results to the VTS dashboard</li>
+</ol>
+
+<p>
+ The process is coordinated by the VTS host controller (HC), a machine in the
+ lab that directs the behavior of all connected devices under test. The HC is
+ responsible for fetching the latest builds, flashing them onto devices, and
+ invoking tests (either locally or through the commander). It also communicates
+ with a cloud scheduler and directs traffic between the scheduler and the
+ TradeFed instance (or some other harness) running on the HC. For details on
+ the host controller, see <a href="/compatibility/vts/host-controller">Host
+ Controller Architecture</a>.
+</p>
+
+<h2 id="resource-providers">Resource providers</h2>
+
+<p>
+ Automated testing requires resources such as system builds, test files, and
+ VTS artifacts. While it's possible to build these from source, it is easier to
+ build them from tip-of-tree regularly then post the artifacts for download.
+</p>
+
+<p>
+ Partners can access automation resources using the following locations:
+</p>
+
+<ul>
+ <li><strong>Partner Android Build</strong>. Programmatic access granted on a
+ per-account basis.</li>
+ <li><strong>Local filesystem</strong> (or similar). For partners who do not
+ use the Partner Android Build.</li>
+</ul>
+
+<p>
+ For use in flashing the devices later, resources include build providers for
+ both options, extending from a single <code>build_provider.py</code> that
+ stores the builds in local temporary directories.
+</p>
+
+<h3 id=partner-android-build>Partner Android Build</h3>
+
+<p>
+ In Android 8.1 and lower releases, Android partners were required to visit the
+ Partner Android Build website
+ (<a href="https://partner.android.com/build" class="external">https://partner.android.com/build</a>),
+ navigate to their account, and fetch the latest system images through the user
+ interface. To help partners avoid this slow and labor-intensive process,
+ Android {{ androidPVersionNumber }} includes support for automatically
+ downloading these resources from PAB when
+ the appropriate credentials are provided.
+</p>
+
+<h4 id="establishing-access">Establishing access</h4>
+
+<p>
+ Programmatic access uses OAuth2 on Google APIs to access the required RPCs.
+ Using the
+ <a href="https://developers.google.com/api-client-library/python/guide/aaa_oauth#flow_from_clientsecrets" class="external">standard
+ approach</a> for generating OAuth2 credentials, the partner must set up a
+ client id/secret pair with Google. When the
+ <code>PartnerAndroidBuildClient</code> is pointed to that secret for the first
+ time, it opens a browser window for the user to log in to their Google
+ account, which generates the OAuth2 credentials needed to move forward. The
+ credentials (access token and refresh token) are stored locally, meaning
+ partners should need to login only once.
+</p>
+
+<h4>POST request for URL</h4>
+
+<p>
+ Clicking a resource link in PAB sends a POST request that includes the
+ necessary data for that resource, including:
+</p>
+
+<ul>
+ <li>build id, build target</li>
+ <li>resource name</li>
+ <li>branch</li>
+ <li>release candidate name and whether or not the candidate is an internal
+ build</li>
+</ul>
+
+<p>
+ The POST request is received by the <code>downloadBuildArtifact</code> method
+ of the <code>buildsvc</code> RPC, which returns a URL that can be used to
+ access the resource.
+
+<ul>
+ <li>For Clockwork Companion APK resources, the URL is a readable URL hosted on
+ PAB (which is auth-protected and accessible with the appropriate OAuth2
+ credentials).</li>
+ <li>For other resources, the URL is long, non-protected URL from the internal
+ Android Build API (which expires after five minutes).</li>
+</ul>
+
+<h4 id="getting-url">Getting the URL </h4>
+
+<p>
+ To avoid cross-site request forgery, the <code>buildsvc</code> RPC requires an
+ XSRF token to be POSTed with the other parameters. While this token makes the
+ process more secure, it also makes programmatic access much harder since the
+ token (which is available only in the JavaScript of the PAB page) is now also
+ required for access.
+</p>
+
+<p>
+ To avoid this issue, Android {{ androidPVersionNumber }} redesigns the URL
+ naming scheme for all files (not just APKs) to use predictable URL names for
+ accessing artifact lists and artifact URLs. The PAB now uses a convenient URL
+ format that enables partners to download resources; HC scripts can download
+ those APKs easily, since the URL format is known, and HC can bypass the
+ XSRF/cookie issues because it does not need the <code>buildsvc</code> RPC.
+</p>
+
+<h3 id="local-filesystem">Local filesystem</h3>
+
+<p>
+ Given a directory with a list (or zip file) of artifacts, the build provider
+ sets the relevant images based on what's in the directory. You can use the
+ <a href="https://cloud.google.com/storage/docs/gsutil" class="external">gsutil</a>
+ tool to copy files from Google Cloud Storage to a local directory.
+</p>
+
+<h2 id="flashing-builds">Flashing builds</h2>
+
+<p>
+ After the most recent device images are downloaded to the host, those images
+ must be flashed onto the devices. This is done using the standard
+ <code>adb</code> and <code>fastboot</code> commands and Python subprocesses,
+ based on the temporary file paths stored by the build providers.
+</p>
+
+<p>
+ Supported actions:
+</p>
+
+<ul>
+ <li>Flashing only the GSI</li>
+ <li>Flashing individual images from the main system (e.g.,
+ <code>fastboot flash boot boot.img</code>)</li>
+ <li>Flashing all images from the main system. Example:
+ <ul>
+ <li><code>fastboot flashall</code> (using the built-in <code>flashall</code>
+ utility)</li>
+ <li><code>fastboot flash</code> (one at a time)</li>
+ </ul>
+ </li>
+</ul>
+
+<h2 id="running=tests">Running tests</h2>
+
+<p>
+ In Android {{ androidPVersionNumber }}, the VTS automated testing
+ infrastructure supports only the TradeFed test harness but could be extended
+ to support other harnesses in the future.
+</p>
+
+<p>
+ After the devices are prepared, you can invoke tests using one of the
+ following options:
+</p>
+
+<ul>
+ <li>When using TradeFed locally, use the <code>test</code> command in the host
+ controller, which takes the name of a VTS test plan (e.g.
+ <code>vts-selftest</code>) and runs the test.</li>
+ <li>When using a TradeFed Cluster (optionally connected to MTT), use the
+ <code>lease</code> command in the host controller console, which looks for
+ unfulfilled test runs.</li>
+</ul>
+
+<p>
+ If using TradeFedCluster, TradeFed runs
+ <a href="/compatibility/vts/host-controller">locally as a remote manager</a>.
+ If not, the tests are invoked using Python subprocesses.
+</p>
+
+<h2 id="reporting-results">Reporting results</h2>
+
+<p>
+ Test results are automatically reported to some VTS dashboard projects by
+ <code>VtsMultiDeviceTest</code>.
+</p>
+
+</body>
+</html>
diff --git a/en/compatibility/vts/hal-testability.html b/en/compatibility/vts/hal-testability.html
new file mode 100644
index 0000000..cf53457
--- /dev/null
+++ b/en/compatibility/vts/hal-testability.html
@@ -0,0 +1,252 @@
+<html devsite>
+<head>
+ <title>HAL Testability Check</title>
+ <meta name="project_path" value="/_project.yaml">
+ <meta name="book_path" value="/_book.yaml">
+</head>
+<body>
+ {% include "_versions.html" %}
+ <!--
+ Copyright 2018 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 Android {{ androidPVersionNumber }} Vendor Test Suite (VTS) supports a
+ runtime method for using the device configuration to identify which VTS tests
+ should be skipped for that device target.
+</p>
+
+<h3 id="vts-test-flexibility">VTS test flexibility</h3>
+
+<p>
+ As of Android 8.0, VTS tests are required for all devices launched with
+ Android 8.0 and higher. However, not all VTS tests apply to all device
+ targets. For example:
+</p>
+
+<ul>
+ <li>If a specific device does not support a testing HAL (e.g. IR), VTS does
+ not need to run tests for that HAL test against that device target.</li>
+ <li>If several devices share the same SoC and vendor image but have
+ different hardware functionalities, VTS must determine whether a test
+ should be run or be skipped for a specific device target.</li>
+</ul>
+
+<h3 id="vts-test-types">VTS test types</h3>
+
+<p>
+ VTS includes the following test types:
+</p>
+
+<ul>
+ <li><strong>Compliance</strong> tests ensure compatibility between framework
+ and vendor partitions. These tests are required to be run (and pass) on
+ devices launching with Android 8.0 or higher.</li>
+ <li><strong>Non-compliance</strong> tests help vendors to improve product
+ quality (performance/fuzzing etc.). These tests are optional for vendors.</li>
+</ul>
+
+<p>
+ Whether a test is a compliance test or not depends on which plan it belongs
+ to. Tests that run with
+ <a href="https://android.googlesource.com/platform/test/vts/+/master/tools/vts-tradefed/res/config/vts.xml" class="external">
+ VTS plan</a> are considered compliance tests.
+</p>
+
+<h2 id="determine-supported-hals">Determining supported HALs</h2>
+
+<p>
+ VTS can use the following files to determine if the device target supports a
+ specific HAL:
+</p>
+
+<ul>
+ <li><code>/system/compatibility_matrix.xml</code>. Claims the HAL instances
+ required by the framework. Example:
+<pre class="prettyprint">
+<hal format="hidl" optional="true">
+ <name>android.hardware.vibrator</name>
+ <version>1.0-1</version>
+ <interface>
+ <name>IVibrator</name>
+ <instance>default</instance>
+ </interface>
+</hal>
+</pre>
+ <ul>
+ <li>The <code>optional</code> attribute indicates if the HAL is strictly
+ required by the framework.</li>
+ <li>The file may contain multiple entries for the same HAL (with same name)
+ but with different version and interfaces.</li>
+ <li>The file may contain multiple <code>version</code> configurations for
+ the same entry, indicating the framework can work with different versions.
+ </li>
+ <li><code>version1.0-1</code> means the framework can work with the lowest
+ version 1.0, and does not require a version higher than 1.1.</li>
+ </ul>
+ </li>
+ <li>Device <code>manifest.xml</code>. Claims the HAL instances provided by the
+ vendor. Example:
+<pre class="prettyprint">
+<hal format="hidl">
+ <name>android.hardware.vibrator</name>
+ <transport>hwbinder</transport>
+ <version>1.2</version>
+ <interface>
+ <name>IVibrator</name>
+ <instance>default</instance>
+ </interface>
+</hal>
+</pre>
+ <ul>
+ <li>The file may contain multiple entries for the same HAL (with same name)
+ but with different version and interfaces.</li>
+ <li>If the file contains only a single <code>version</code> configuration
+ for an entry, <code>version1.2</code> means the vendor supports all versions
+ from 1.0~1.2.</li>
+ </ul>
+ </li>
+ <li><strong>lshal</strong>. A tool on device that shows runtime info about
+ the HAL services registered with the <code>hwservicemanager</code>. Example:
+<pre class="prettyprint">
+android.hardware.vibrator@1.0::IVibrator/default
+</pre>
+ <br><code>lshal</code> also shows all the HALs that with passthrough
+ implementations (i.e having the corresponding <code>-impl.so</code> file on
+ the device). Example:
+<pre class="prettyprint">
+android.hardware.nfc@1.0::I*/* (/vendor/lib/hw/)
+android.hardware.nfc@1.0::I*/* (/vendor/lib64/hw/)
+</pre>
+ </li>
+ </ul>
+
+<h2 id="compliance-tests">Compliance tests</h2>
+
+<p>
+ For compliance tests, VTS relies on the vendor manifest to determine (and
+ test) all HAL instances provided by the device. Decision flow:
+</p>
+
+<p>
+ <img src="images/testability-check-compliance.png"
+ alt="Testability check for compliance"
+ title="Testability check for compliance"">
+</p>
+<figcaption>
+ <strong>Figure 1.</strong> Testability check for VTS compliance tests
+</figcaption>
+
+<h2 id="non-compliance-tests">Non-compliance tests</h2>
+
+<p>
+ For non-compliance tests, VTS relies on the vendor manifest and
+ <code>lshal</code> outputs to determine (and test) the experimental HALs not
+ claimed in the <code>manifest.xml</code> file. Decision flow:
+</p>
+
+<p>
+ <img src="images/testability-check-non-compliance.png"
+ alt="Testability check for non-compliance"
+ title="Testability check for non-compliance">
+<figcaption>
+ <strong>Figure 2.</strong> Testability check for VTS non-compliance
+ tests
+</figcaption>
+
+<h2 id="locating-the-vendor-manifest">Locating the vendor manifest</h2>
+
+<p>
+ VTS checks for the vendor <code>manifest.xml</code> file in the following
+ places in the following order:
+</p>
+
+<ol>
+ <li><code>/vendor/etc/vintf/manifest.xml</code> + ODM manifest (If same HAL
+ is defined in both places, ODM manifest overrides the one in
+ <code>/vendor/etc/vintf/manifest.xml</code>)</li>
+ <li><code>/vendor/etc/vintf/manifest.xml</code></li>
+ <li>ODM <code>manifest.xml</code> file, loaded from the following files in
+ the following order:
+ <ol>
+ <li><code>/odm/etc/vintf/manifest_$(ro.boot.product.hardware.sku).xml</code>
+ </li>
+ <li><code>/odm/etc/vintf/manifest.xml</code></li>
+ <li><code>/odm/etc/manifest_$(ro.boot.product.hardware.sku).xml</code></li>
+ <li><code>/odm/etc/manifest.xml</code></li>
+ <li><code>/vendor/manifest.xml</code></li>
+ </ol>
+ </li>
+</ol>
+
+<h2 id="vts-testability-checker">VTS testability checker</h2>
+
+<p>
+ The
+ <code><a href="https://android.googlesource.com/platform/test/vts/+/master/utils/native/testability_checker/?q=vts_testability&g=0" class="external">
+ vts_testibility_checker</a></code> is a binary packaged with VTS and used by
+ VTS test framework at runtime to determine whether a given HAL test is
+ testable or not. It is based on
+ <code><a href="https://android.googlesource.com/platform/system/libvintf/+/master" class="external">libvintf</a></code>
+ to load and parse the vendor manifest file and implements the decision flow
+ described in the previous section.
+</p>
+
+<p>
+ To use <code>vts_testability_check</code>:
+</p>
+
+<ul>
+ <li>For a compliance test:
+<pre class="prettyprint">
+vts_testability_check -c -b <bitness> <hal@version>
+</pre>
+ </li>
+ <li>For a non-compliance test:
+<pre class="prettyprint">
+vts_testability_check -b <bitness> <hal@version>
+</pre>
+ </li>
+</ul>
+
+<p>
+ The output of <code>vts_testability_check</code> uses the following json
+ format:
+</p>
+
+<pre class="prettyprint">
+{testable: <True/False> Instances: <list of instance names of HAL service>}
+</pre>
+
+<h2 id="determining-accessed-hals">Determining accessed HALs</h2>
+
+<p>
+ To determine which HALs are accessed by VTS tests, ensure that each HAL test
+ uses the
+ <code><a href="https://android.googlesource.com/platform/test/vts/+/master/runners/target/vts_hal_hidl_target/VtsHalHidlTargetTestEnvBase.h" class="external">VtsHalHidlTargetTestEnvBase</a></code>
+ template to register the HAL(s) accessed in the test. The VTS testing
+ framework can then extract the registered HALs when pre-processing the test.
+</p>
+
+<p>
+ For compliance tests, you can also check
+ <code>/system/etc/vintf/manifest.xml</code>. If a HAL is defined here, VTS
+ should test it. (For the HAL services provided by the system (e.g.
+ <code>graphics.composer/vr</code>), the HALs are declared in
+ <code>/system/manifest.xml</code>.)
+</p>
+
+</body>
+</html>
diff --git a/en/compatibility/vts/host-controller.html b/en/compatibility/vts/host-controller.html
new file mode 100644
index 0000000..05ee402
--- /dev/null
+++ b/en/compatibility/vts/host-controller.html
@@ -0,0 +1,64 @@
+<html devsite="">
+<head>
+ <title>Host Controller Architecture</title>
+ <meta name="project_path" value="/_project.yaml">
+ <meta name="book_path" value="/_book.yaml">
+</head>
+
+<body>
+ {% include "_versions.html" %}
+ <!--
+ Copyright 2018 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 architecture of VTS test framework integrates with its cloud-based test
+ serving service. A VTS Host Controller runs on a host machine and controls a
+ test harness (e.g., TradeFed) instance as shown below:
+ </p>
+
+<p>
+ <img src="images/vts-host-controller.png" width="" alt="Host controller architecture"
+ title="Host controller architecture">
+</p>
+<figcaption>
+ <strong>Figure 1.</strong> VTS Host Controller architecture
+ </figcaption>
+
+ <p>
+ The controller pulls commands from a Cluster Commander running as a Google App
+ Engine (GAE) instance, then relays commands and responses between its cluster
+ commander and the test harness instance.
+</p>
+
+<p>This architecture includes the following advantages:
+</p>
+
+<ul>
+ <li>Because it is <strong>decoupled from any test harness instance</strong>,
+ it can control different types of test harnesses and is more robust. The
+ alternative design (embedding the host control logic in a test harness) does
+ not block errors from propagating.</li>
+ <li>Because it uses a <strong>pull-based command-and-control (C&C)
+ model</strong>, it can work with different types of cloud-side cluster
+ commanders as well as hosts that exist behind a firewall (for ingress
+ connections). The alternative design (push-based C&C model) may not allow
+ a cloud commander to access host controller instances that exist on host
+ computers in a private network.</li>
+</ul>
+
+</body>
+</html>
diff --git a/en/compatibility/vts/images/VTS-Host0.png b/en/compatibility/vts/images/VTS-Host0.png
new file mode 100644
index 0000000..fadd6b9
--- /dev/null
+++ b/en/compatibility/vts/images/VTS-Host0.png
Binary files differ
diff --git a/en/compatibility/vts/images/runtime-support-host.png b/en/compatibility/vts/images/runtime-support-host.png
new file mode 100644
index 0000000..3f6e0f7
--- /dev/null
+++ b/en/compatibility/vts/images/runtime-support-host.png
Binary files differ
diff --git a/en/compatibility/vts/images/runtime-support-target.png b/en/compatibility/vts/images/runtime-support-target.png
new file mode 100644
index 0000000..5c1188d
--- /dev/null
+++ b/en/compatibility/vts/images/runtime-support-target.png
Binary files differ
diff --git a/en/compatibility/vts/images/testability-check-compliance.png b/en/compatibility/vts/images/testability-check-compliance.png
new file mode 100644
index 0000000..7e37df8
--- /dev/null
+++ b/en/compatibility/vts/images/testability-check-compliance.png
Binary files differ
diff --git a/en/compatibility/vts/images/testability-check-non-compliance.png b/en/compatibility/vts/images/testability-check-non-compliance.png
new file mode 100644
index 0000000..c26c870
--- /dev/null
+++ b/en/compatibility/vts/images/testability-check-non-compliance.png
Binary files differ
diff --git a/en/compatibility/vts/images/vts-automated.png b/en/compatibility/vts/images/vts-automated.png
new file mode 100644
index 0000000..1226509
--- /dev/null
+++ b/en/compatibility/vts/images/vts-automated.png
Binary files differ
diff --git a/en/compatibility/vts/images/vts-host-controller.png b/en/compatibility/vts/images/vts-host-controller.png
new file mode 100644
index 0000000..fadd6b9
--- /dev/null
+++ b/en/compatibility/vts/images/vts-host-controller.png
Binary files differ
diff --git a/en/compatibility/vts/index.html b/en/compatibility/vts/index.html
index 67eacfc..12575b3 100644
--- a/en/compatibility/vts/index.html
+++ b/en/compatibility/vts/index.html
@@ -5,6 +5,7 @@
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
+ {% include "_versions.html" %}
<!--
Copyright 2017 The Android Open Source Project
@@ -23,38 +24,67 @@
<p>
-The Android Vendor Test Suite (VTS) provides extensive new functionality for
-Android testing and promotes a test-driven development process. To help the
-Android development community interact with test data, Android includes the
-following testing resources:
+ The Android Vendor Test Suite (VTS) provides extensive new functionality for
+ Android testing and promotes a test-driven development process. To help the
+ Android development community interact with test data, Android includes the
+ following testing resources:
</p>
+
<ul>
-<li><a href="systems.html">Systems
-Testing with VTS</a>. Describes how to use VTS to test an Android native system
-implementation, set up a testing environment, then test a patch using a VTS
-plan.</li>
-<li><strong>VTS Dashboard</strong>. Web-based user interface for viewing VTS
-results. Includes details on:
- <ul>
- <li><a href="database.html">Dashboard
- database</a>. A scalable back-end to support the continuous integration
- dashboard.</li>
- <li><a href="ui.html">Dashboard UI</a>. A
- cohesive user interface that uses material design to effectively display
- information about test results, profiling, and coverage.</li>
- <li><a href="setup.html">Dashboard setup</a>.
- Instructions for setting up and configuring the VTS Dashboard.</li>
- </ul>
-</li>
-<li><a href="performance.html">binder and hwbinder
-performance tests</a>. Tools for measuring throughput and latency.</li>
+ <li><a href="/compatibility/vts/systems">Systems Testing with VTS</a>.
+ Describes how to use VTS to test an Android native system implementation, set
+ up a testing environment, then test a patch using a VTS plan.</li>
+ <li><strong>Test Framework</strong>. Provides details on using the VTS test
+ framework. Includes:
+ <ul>
+ <li><a href="/compatibility/vts/shell-commands">Device shell commands</a>.
+ Instructions on how to use device shell commands to execute target-side test
+ binaries, to get/set properties, environment variables, and system
+ information, and to start/stop the Android framework.</li>
+ <li><a href="/compatibility/vts/test-templates">Test templates</a>.
+ Details on configuring and using test templates for test modules that are
+ not host-side Python subclass of VTS runner's BaseTest.</li>
+ <li><a href="/compatibility/vts/sna-hal-testing">Service name aware HAL
+ testing</a>. Details on Android {{ androidPVersionNumber }} support for
+ obtaining the service name of a given HAL instance based on the device on
+ VTS is running.</li>
+ <li><a href="/compatibility/vts/hal-testability">HAL testability check</a>.
+ Details on Android {{ androidPVersionNumber }} support for a runtime method
+ that uses the device configuration to identify which VTS tests should be
+ skipped for that device target.</li>
+ <li><a href="/compatibility/vts/multi-device-testing">Multi-device
+ testing</a>. Instructions for configuring tests that require interaction
+ between multiple Android devices.</li>
+ </ul>
+ </li>
+ <li><strong>VTS Dashboard</strong>. Web-based user interface for viewing VTS
+ results. Includes details on:
+ <ul>
+ <li><a href="setup.html">Setup</a>. Instructions for setting up and
+ configuring the VTS Dashboard.</li>
+ <li><a href="/compatibility/vts/database.html">Database</a>. A scalable
+ back-end to support the continuous integration dashboard.</li>
+ <li><a href="/compatibility/vts/ui.html">User Interface</a>. A cohesive user
+ interface that uses material design to effectively display information about
+ test results, profiling, and coverage.</li>
+ </ul>
+ </li>
+ <li><strong>Lab infrastructure</strong>. Describes the architecture of an
+ <a href="/compatibility/vts/automated-test-infra">automated testing
+ infrastructure</a> for running VTS, CTS, or other tests on partner devices
+ running the AOSP <a href="/setup/build/gsi">Generic System Image (GSI)</a>.
+ Requires a <a href="/compatibility/vts/host-controller">Host Controller</a>.
+ </li>
+ <li><a href="/compatibility/vts/performance.html">binder and hwbinder
+ performance tests</a>. Tools for measuring throughput and latency.</li>
</ul>
-<p>For additional details, refer to the
-<a href="https://codelabs.developers.google.com/codelabs/android-vts/#0"
-class="external">Android VTS Codelab</a> on developer.android.com and the
-<a href="https://www.youtube.com/watch?v=7BX7oSHc7nk&list=PLWz5rJ2EKKc9JOMtoWWMJHFHgvXDoThva"
-class="external">Android VTS Products video</a> produced by Google Developers.
+<p>
+ For additional details, refer to the
+ <a href="https://codelabs.developers.google.com/codelabs/android-vts/#0" class="external">Android
+ VTS Codelab</a> on developer.android.com and the
+ <a href="https://www.youtube.com/watch?v=7BX7oSHc7nk&list=PLWz5rJ2EKKc9JOMtoWWMJHFHgvXDoThva" class="external">Android
+ VTS Products video</a> produced by Google Developers.
</p>
</body>
diff --git a/en/compatibility/vts/sna-hal-testing.html b/en/compatibility/vts/sna-hal-testing.html
new file mode 100644
index 0000000..a818597
--- /dev/null
+++ b/en/compatibility/vts/sna-hal-testing.html
@@ -0,0 +1,252 @@
+<html devsite>
+ <head>
+ <title>Service Name Aware HAL Testing</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ <body>
+ {% include "_versions.html" %}
+ <!--
+ Copyright 2018 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 {{ androidPVersionNumber }} includes support for obtaining the service
+ name of a given HAL instance based on the device on which Vendor Test Suite
+ (VTS) tests are running. Running VTS HAL tests that are service name aware
+ enables developers to automate testing vendor extensions, multiple HALs, and
+ multiple HAL instances on both target- and host-side VTS test runs.
+</p>
+
+<h3 id="about-service-names">About service names</h3>
+
+<p>
+ Each instance of the running HAL service registers itself with a service name.
+</p>
+
+<p>
+ In previous versions of Android, developers running VTS HAL tests were
+ required to set the correct service name for the test client in
+ <code>getService()</code> or leave the name empty and fallback to the default
+ service name. Disadvantages to this approach included:
+</p>
+
+<ul>
+ <li>Reliance on the test developer's knowledge to set the correct service
+ name.</li>
+ <li>Limited to testing against a single service instance by default.</li>
+ <li>Manual maintenance of service names (i.e. because names are hard-coded,
+ they must be manually updated if the service name changes.</li>
+</ul>
+
+<p>
+ In Android {{ androidPVersionNumber }}, developers can automatically get the
+ service name for a given HAL instance based on the device under test.
+ Advantages to this approach include support for testing:
+</p>
+
+<ul>
+ <li><strong>Vendor HAL extensions</strong>. For example, when a vendor has an
+ implementation of camera.provider HAL that runs on vendor devices with a
+ customized service name, VTS can identify the vendor instance and run the test
+ against it.</li>
+ <li><strong>Multiple HAL instances</strong>. For example, when the
+ <code>graphics.composer</code> HAL has two instances (one with service name
+ "default" and one with service name "vr"), VTS can identify both instances and
+run the test against each of them.</li>
+ <li><strong>Multi-HAL testing</strong>. Used when testing multiple HALs with
+ multiple instances For example, when running the VTS test that verifies how
+ the keymaster and gatekeeper HAL work together, VTS can test all combinations
+ of service instances for those HALs.</li>
+</ul>
+
+<h2 id="target-side-tests">Target-side tests</h2>
+
+<p>
+ To enable service name awareness for target-side testing, Android
+ {{ androidPVersionNumber }} includes a customizable test environment
+ (<code><a href="https://android.googlesource.com/platform/test/vts/+/master/runners/target/vts_hal_hidl_target/VtsHalHidlTargetTestEnvBase.h" class="external">VtsHalHidlTargetTestEnvBase</a></code>)
+ that provides interfaces to:
+</p>
+
+<ul>
+ <li>Register targeting HAL(s) in the test.</li>
+ <li>List all the registered HAL(s).</li>
+ <li>Get service name(s) for registered HAL(s) provided by VTS framework.</li>
+</ul>
+
+<p>
+ In addition, the VTS framework provides runtime support for:
+</p>
+
+<ul>
+ <li>Pre-processing the test binary to get all registered test HAL(s).</li>
+ <li>Identifying all running service instances and getting the service name for
+ each instance (retrieved based on <code>vendor/manifest.xml</code>).</li>
+ <li>Calculating all instance combinations (to support multiple HAL
+ testing).</li>
+ <li>Generating a new test for each service instance (combination).</li>
+</ul>
+
+<p>
+ Example:
+</p>
+
+<p>
+ <img src="images/runtime-support-target.png"
+ alt="Runtime support for target-side testing"
+ title="Runtime support for target-side testing">
+</p>
+<figcaption>
+ <strong>Figure 1.</strong> VTS framework runtime support for target-side
+ testing
+</figcaption>
+
+<h3 id="setting-up">Setting up service name aware target-side tests</h3>
+
+<p>
+ To setup your test environment for target-side service name aware testing:
+</p>
+
+<ol>
+ <li>Define a <code>testEnvironment</code> based on
+ <code>VtsHalHidlTargetTestEnvBase</code> and register test HALs:
+
+<pre class="prettyprint">#include <VtsHalHidlTargetTestEnvBase.h>
+class testEnvironment : public::testing::VtsHalHidlTargetTestEnvBase {
+ virtual void registerTestServices() override {
+ registerTestService<IFoo>();
+ }
+};</pre>
+ </li>
+ <li>Use <code>getServiceName()</code> provided by the test environment to pass
+ service name:
+
+<pre
+class="prettyprint">::testing::VtsHalHidlTargetTestBase::getService<IFoo>(testEnv->getServiceName<IFoo>("default"));
+// "default" is the default service name you want to use.</pre>
+ </li>
+ <li>Register the test environment in <code>main()</code> and
+ <code>initTest</code>:
+<pre
+class="prettyprint">int main(int argc, char** argv) {
+ testEnv = new testEnvironment();
+ ::testing::AddGlobalTestEnvironment(testEnv);
+ ::testing::InitGoogleTest(&argc, argv);
+ testEnv->init(argc, argv);
+ return RUN_ALL_TESTS();
+}</pre>
+ </li>
+</ol>
+
+<p>
+ For additional examples, refer to
+ <code><a href="https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/provider/2.4/vts/functional/VtsHalCameraProviderV2_4TargetTest.cpp" class="external">VtsHalCameraProviderV2_4TargetTest.cpp</a></code>.
+
+<h2 id="host-side-tests">VTS host-side tests</h2>
+
+<p>
+ VTS host-side tests run test scripts on host side instead of test binaries on
+ the target device. To enable service name awareness for these tests, you can
+ use host side templates to run the same test script multiple times against
+ different parameters (similar to the gtest parameterized test).
+</p>
+
+<p>
+ <img src="images/runtime-support-host.png"
+ alt="Runtime support for host-side testing"
+ title="Runtime support for host-side testing">
+<p>
+<figcaption>
+ <strong>Figure 2.</strong> VTS framework runtime support for host-side
+ testing
+</figcaption>
+
+<ul>
+ <li>The <strong>hal test</strong> script specifies the targeting HAL
+ service(s) in the test.</li>
+ <li>The
+ <code><a href="https://android.googlesource.com/platform/test/vts/+/master/testcases/template/hal_hidl_host_test/hal_hidl_host_test.py" class="external">hal_hidl_host_test</a></code>
+ (subclass of <code>param_test</code>) takes the registered testing HAL(s) from
+ test script, identifies the corresponding service name(s) for the testing HAL,
+ then generates service name combinations (for multi-HAL testing) as test
+ parameters. It also provides a method <code>getHalServiceName()</code> which
+ returns the corresponding service name according to the parameter passed to
+ the current test case.</li>
+ <li>The
+ <a href="https://android.googlesource.com/platform/test/vts/+/master/testcases/template/param_test/param_test.py" class="external">param_test</a>
+ template supports logic to accept a list of parameters and run all the given
+ test cases against each parameter. I.e. for each test case it generates N new
+ parameterized test case (N = size of parameters), each with a given
+ parameter.</li>
+</ul>
+
+<h3 id="setting-up-host-side">Setting up service name aware host-side tests</h3>
+
+<p>
+ To setup your test environment for host-side service name aware testing:
+</p>
+
+<ol>
+ <li>Specify the target HAL service in the test script:
+<pre
+class="prettyprint">TEST_HAL_SERVICES = { "android.hardware.foo@1.0::IFoo" }
+</pre>
+ </li>
+ <li>Call <code>getHalServiceName()</code> and pass the name to init hal:
+
+<pre class="prettyprint">self.dut.hal.InitHidlHal(
+ target_type='foo',
+ target_basepaths=self.dut.libPaths,
+ target_version=1.0,
+ target_package='android.hardware.foo',
+ target_component_name='IFoo',
+ hw_binder_service_name
+ =self.getHalServiceName("android.hardware.foo@1.0::IFoo"),
+ bits=int(self.abi_bitness))
+</pre>
+ </li>
+</ol>
+
+<p>
+ For additional examples, refer to
+ <code><a href="https://android.googlesource.com/platform/test/vts-testcase/hal/+/master/media/omx/V1_0/host_omxstore/VtsHalMediaOmxStoreV1_0HostTest.py" class="external">VtsHalMediaOmxStoreV1_0HostTest.py</a></code>.
+</p>
+
+<h2 id="register-test-hals">Registering test HALs</h2>
+
+<p>
+ In previous versions of Android, VTS identified the testing HAL using the
+ <code><precondition-lshal></code> option configured in
+ <code>AndroidTest.xml</code>. This approach was difficult to maintain (as it
+ relied on developers to configure the test properly and update the
+ configuration accordingly) and inaccurate (as it contained only the package
+ and version info and not the interface info).
+</p>
+
+<p>
+ In Android {{ androidPVersionNumber }}, VTS identifies the testing HAL using
+ service name awareness. The registered testing HALs are also useful for:
+</p>
+
+<ul>
+ <li><strong>Precondition checks</strong>. Before running a HAL test, VTS can
+ confirm the testing HAL is available on the target device and skip the tests
+ if it is not (refer to <a href="/compatibility/vts/hal-testability">VTS
+ testability check</a>).</li>
+ <li><strong>Coverage measurement</strong>. VTS supports cross-process code
+ coverage measurement via the knowledge about the testing HAL services it wants
+ to measure (i.e. to flush the coverage for the hal service process).</li>
+</ul>
+
+ </body>
+</html>
diff --git a/en/devices/_toc-audio.yaml b/en/devices/_toc-audio.yaml
new file mode 100644
index 0000000..173f4fe
--- /dev/null
+++ b/en/devices/_toc-audio.yaml
@@ -0,0 +1,61 @@
+toc:
+- title: Overview
+ path: /devices/audio/
+- title: Terminology
+ path: /devices/audio/terminology
+- title: Implementation
+ section:
+ - title: Overview
+ path: /devices/audio/implement
+ - title: Policy Configuration
+ path: /devices/audio/implement-policy
+ - title: Shared Library
+ path: /devices/audio/implement-shared-library
+ - title: Pre-processing Effects
+ path: /devices/audio/implement-pre-processing
+- title: Data Formats
+ path: /devices/audio/data_formats
+- title: Attributes
+ path: /devices/audio/attributes
+- title: High-Resolution Effects
+ path: /devices/audio/highres-effects
+- title: AAudio and MMAP
+ path: /devices/audio/aaudio
+- title: Warmup
+ path: /devices/audio/warmup
+- title: Latency
+ section:
+ - title: Overview
+ path: /devices/audio/latency/latency
+ - title: Contributors
+ path: /devices/audio/latency/contrib
+ - title: Design
+ path: /devices/audio/latency/design
+ - title: Measure
+ path: /devices/audio/latency/measure
+ - title: Light Testing Circuit
+ path: /devices/audio/latency/testing_circuit
+ - title: Audio Loopback Dongle
+ path: /devices/audio/latency/loopback
+ - title: Measurements
+ path: /devices/audio/latency/measurements
+ - title: Applications
+ path: /devices/audio/latency/app
+- title: Priority Inversion
+ path: /devices/audio/avoiding_pi
+- title: Sample Rate Conversion
+ path: /devices/audio/src
+- title: Debugging
+ path: /devices/audio/debugging
+- title: MIDI
+ section:
+ - title: Overview
+ path: /devices/audio/midi
+ - title: MIDI Architecture
+ path: /devices/audio/midi_arch
+ - title: MIDI Test Procedure
+ path: /devices/audio/midi_test
+- title: USB Digital Audio
+ path: /devices/audio/usb
+- title: TV Audio
+ path: /devices/audio/tv
diff --git a/en/devices/_toc-camera.yaml b/en/devices/_toc-camera.yaml
new file mode 100644
index 0000000..0389733
--- /dev/null
+++ b/en/devices/_toc-camera.yaml
@@ -0,0 +1,29 @@
+toc:
+- title: Overview
+ path: /devices/camera/
+- title: Camera3
+ path: /devices/camera/camera3
+- title: HAL Subsystem
+ path: /devices/camera/camera3_requests_hal
+- title: Metadata and Controls
+ path: /devices/camera/camera3_metadata
+- title: 3A Modes and State
+ path: /devices/camera/camera3_3Amodes
+- title: Output and Cropping
+ path: /devices/camera/camera3_crop_reprocess
+- title: Errors and Streams
+ path: /devices/camera/camera3_error_stream
+- title: Request Creation
+ path: /devices/camera/camera3_requests_methods
+- title: External USB Cameras
+ path: /devices/camera/external-usb-cameras
+- title: Multi-Camera Support
+ path: /devices/camera/multi-camera
+- title: Motion Tracking
+ path: /devices/camera/motion-tracking
+- title: Session Parameters
+ path: /devices/camera/session-parameters
+- title: Single Producer, Multiple Consumer
+ path: /devices/camera/singleprod-multiconsum
+- title: Version Support
+ path: /devices/camera/versioning
diff --git a/en/devices/_toc-connectivity.yaml b/en/devices/_toc-connectivity.yaml
new file mode 100644
index 0000000..239f5bc
--- /dev/null
+++ b/en/devices/_toc-connectivity.yaml
@@ -0,0 +1,77 @@
+toc:
+- title: Overview
+ path: /devices/tech/connect/
+- title: Bluetooth and NFC
+ section:
+ - title: Overview
+ path: /devices/bluetooth
+ - title: Bluetooth Services
+ path: /devices/bluetooth/services
+ - title: Bluetooth Low Energy
+ path: /devices/bluetooth/ble
+ - title: BLE Advertising
+ path: /devices/bluetooth/ble_advertising
+ - title: Verifying and Debugging Bluetooth
+ path: /devices/bluetooth/verifying_debugging
+ - title: Bluetooth HCI Requirements
+ path: /devices/bluetooth/hci_requirements
+ - title: NFC Host Card Emulation of FeliCa
+ path: /devices/tech/connect/felica
+- title: Calling and Messaging
+ section:
+ - title: Block Phone Numbers
+ path: /devices/tech/connect/block-numbers
+ - title: Call Notifications
+ path: /devices/tech/connect/call-notification
+ - title: Emergency Affordance
+ path: /devices/tech/connect/emergency-affordance
+ - title: IP Multimedia Subsystem (IMS)
+ path: /devices/tech/connect/ims
+ - title: Real-Time Text (RTT)
+ path: /devices/tech/connect/rtt
+ - title: Third-Party Calling Apps
+ path: /devices/tech/connect/third-party-call-apps
+- title: Carrier
+ section:
+ - title: Overview
+ path: /devices/tech/config/carrier
+ - title: APN and CarrierConfig
+ path: /devices/tech/config/update
+ - title: Carrier Identification
+ path: /devices/tech/config/carrierid
+ - title: Data Plans
+ path: /devices/tech/connect/data-plans
+ - title: eSIM
+ section:
+ - title: Implementing eSIM
+ path: /devices/tech/connect/esim-overview
+ - title: Modem Requirements
+ path: /devices/tech/connect/esim-modem-requirements
+ - title: eUICC APIs
+ path: /devices/tech/connect/esim-euicc-api
+ - title: Out-of-Balance Users
+ path: /devices/tech/connect/oob-users
+ - title: Radio Interface Layer (RIL)
+ path: /devices/tech/connect/ril
+ - title: UICC
+ path: /devices/tech/config/uicc
+- title: Wi-Fi
+ section:
+ - title: Overview
+ path: /devices/tech/connect/wifi-overview
+ - title: Wi-Fi HAL
+ path: /devices/tech/connect/wifi-hal
+ - title: STA/AP Concurrency
+ path: /devices/tech/connect/wifi-sta-ap-concurrency
+ - title: MAC Randomization
+ path: /devices/tech/connect/wifi-mac-randomization
+ - title: Passpoint R1
+ path: /devices/tech/connect/wifi-passpoint
+ - title: Carrier Wi-Fi
+ path: /devices/tech/connect/carrier-wifi
+ - title: Wi-Fi Aware
+ path: /devices/tech/connect/wifi-aware
+ - title: Wi-Fi Round Trip Time (RTT)
+ path: /devices/tech/connect/wifi-rtt
+ - title: Testing and Debugging
+ path: /devices/tech/connect/wifi-debug
diff --git a/en/devices/_toc-data.yaml b/en/devices/_toc-data.yaml
new file mode 100644
index 0000000..af0157e
--- /dev/null
+++ b/en/devices/_toc-data.yaml
@@ -0,0 +1,21 @@
+toc:
+- title: Overview
+ path: /devices/tech/datausage/
+- title: Data Usage Tags Explained
+ path: /devices/tech/datausage/tags-explained
+- title: Data Saver Mode
+ path: /devices/tech/connect/data-saver
+- title: eBPF Traffic Monitoring
+ path: /devices/tech/datausage/ebpf-traffic-monitor
+- title: Exclude Network Types from Usage
+ path: /devices/tech/datausage/excluding-network-types
+- title: Network Interface Statistics Overview
+ path: /devices/tech/datausage/iface-overview
+- title: Tethering Data
+ path: /devices/tech/datausage/tethering-data
+- title: Usage Cycle Reset Dates
+ path: /devices/tech/datausage/usage-cycle-resets-dates
+- title: Kernel Overview
+ path: /devices/tech/datausage/kernel-overview
+- title: Kernel Changes
+ path: /devices/tech/datausage/kernel-changes
diff --git a/en/devices/_toc-enterprise.yaml b/en/devices/_toc-enterprise.yaml
new file mode 100644
index 0000000..c284e72
--- /dev/null
+++ b/en/devices/_toc-enterprise.yaml
@@ -0,0 +1,21 @@
+toc:
+- title: Overview
+ path: /devices/tech/admin/
+- title: Implementation
+ path: /devices/tech/admin/implement
+- title: Multiple Users
+ path: /devices/tech/admin/multi-user
+- title: Managed Profiles
+ path: /devices/tech/admin/managed-profiles
+- title: Provisioning
+ path: /devices/tech/admin/provision
+- title: Multiuser Apps
+ path: /devices/tech/admin/multiuser-apps
+- title: Enterprise Telephony
+ path: /devices/tech/admin/enterprise-telephony
+- title: Testing Device Provisioning
+ path: /devices/tech/admin/testing-provision
+- title: Testing Device Administration
+ path: /devices/tech/admin/testing-setup
+- title: Enterprise OTA Updates
+ path: /devices/tech/admin/ota-updates
diff --git a/en/devices/_toc-interfaces.yaml b/en/devices/_toc-frameworks.yaml
similarity index 96%
rename from en/devices/_toc-interfaces.yaml
rename to en/devices/_toc-frameworks.yaml
index 7fb6b5c..5f91e99 100644
--- a/en/devices/_toc-interfaces.yaml
+++ b/en/devices/_toc-frameworks.yaml
@@ -9,6 +9,8 @@
path: /devices/architecture/hal
- title: HAL Types
path: /devices/architecture/hal-types
+ - title: Treble
+ path: /devices/architecture/treble
- title: Kernel
section:
- title: Overview
@@ -164,21 +166,21 @@
- title: Latency
section:
- title: Overview
- path: /devices/audio/latency/latency
+ path: /devices/audio/latency
- title: Contributors
- path: /devices/audio/latency/contrib
+ path: /devices/audio/latency_contrib
- title: Design
- path: /devices/audio/latency/design
+ path: /devices/audio/latency_design
- title: Measure
- path: /devices/audio/latency/measure
+ path: /devices/audio/latency_measure
- title: Light Testing Circuit
- path: /devices/audio/latency/testing_circuit
+ path: /devices/audio/testing_circuit
- title: Audio Loopback Dongle
- path: /devices/audio/latency/loopback
+ path: /devices/audio/loopback
- title: Measurements
- path: /devices/audio/latency/measurements
+ path: /devices/audio/latency_measurements
- title: Applications
- path: /devices/audio/latency/app
+ path: /devices/audio/latency_app
- title: Priority Inversion
path: /devices/audio/avoiding_pi
- title: Sample Rate Conversion
diff --git a/en/devices/_toc-graphics.yaml b/en/devices/_toc-graphics.yaml
new file mode 100644
index 0000000..f249cfa
--- /dev/null
+++ b/en/devices/_toc-graphics.yaml
@@ -0,0 +1,55 @@
+toc:
+- title: Overview
+ path: /devices/graphics/
+- title: Architecture
+ section:
+ - title: Overview
+ path: /devices/graphics/architecture
+ - title: BufferQueue
+ path: /devices/graphics/arch-bq-gralloc
+ - title: SurfaceFlinger and HWC
+ path: /devices/graphics/arch-sf-hwc
+ - title: Surface and SurfaceHolder
+ path: /devices/graphics/arch-sh
+ - title: OpenGL ES
+ path: /devices/graphics/arch-egl-opengl
+ - title: OpenGLRenderer Configuration
+ path: /devices/graphics/renderer
+ - title: Vulkan
+ path: /devices/graphics/arch-vulkan
+ - title: SurfaceView
+ path: /devices/graphics/arch-sv-glsv
+ - title: SurfaceTexture
+ path: /devices/graphics/arch-st
+ - title: TextureView
+ path: /devices/graphics/arch-tv
+ - title: Game Loops
+ path: /devices/graphics/arch-gameloops
+- title: Implementation
+ section:
+ - title: Overview
+ path: /devices/graphics/implement
+ - title: Hardware Composer HAL
+ path: /devices/graphics/implement-hwc
+ - title: VSYNC
+ path: /devices/graphics/implement-vsync
+ - title: Vulkan
+ path: /devices/graphics/implement-vulkan
+ - title: Virtual Displays
+ path: /devices/graphics/implement-vdisplays
+- title: OpenGL ES Testing
+ section:
+ - title: Overview
+ path: /devices/graphics/testing
+ - title: Building Test Programs
+ path: /devices/graphics/build-tests
+ - title: Porting the Test Framework
+ path: /devices/graphics/port-tests
+ - title: Running the Tests
+ path: /devices/graphics/run-tests
+ - title: Automating the Tests
+ path: /devices/graphics/automate-tests
+ - title: Using Special Test Groups
+ path: /devices/graphics/test-groups
+ - title: Integrating with Android CTS
+ path: /devices/graphics/cts-integration
diff --git a/en/devices/_toc-interaction.yaml b/en/devices/_toc-interaction.yaml
new file mode 100644
index 0000000..252a7a3
--- /dev/null
+++ b/en/devices/_toc-interaction.yaml
@@ -0,0 +1,118 @@
+toc:
+- title: Input
+ section:
+ - title: Overview
+ path: /devices/input/
+ - title: Key Layout Files
+ path: /devices/input/key-layout-files
+ - title: Key Character Map Files
+ path: /devices/input/key-character-map-files
+ - title: Input Device Configuration Files
+ path: /devices/input/input-device-configuration-files
+ - title: Migration Guide
+ path: /devices/input/migration-guide
+ - title: Keyboard Devices
+ path: /devices/input/keyboard-devices
+ - title: Touch Devices
+ path: /devices/input/touch-devices
+ - title: Getevent
+ path: /devices/input/getevent
+ - title: Validate Keymaps
+ path: /devices/input/validate-keymaps
+- title: Automotive
+ section:
+ - title: Overview
+ path: /devices/automotive/
+ - title: Audio
+ section:
+ - title: Overview
+ path: /devices/automotive/audio/
+ - title: Audio HAL
+ path: /devices/automotive/audio/audio-hal
+ - title: AudioControl HAL
+ path: /devices/automotive/audio/audio-control
+ - title: Interaction Sequences
+ path: /devices/automotive/audio/interaction-sequences
+ - title: Multi-Zone
+ path: /devices/automotive/audio/multi-zone
+ - title: Camera HAL
+ path: /devices/automotive/camera-hal
+ - title: IVI Connectivity
+ path: /devices/automotive/ivi_connectivity
+ - title: Vehicle Properties
+ path: /devices/automotive/properties
+ - title: Flash Wear Management
+ path: /devices/tech/perf/flash-wear
+- title: Neural Networks
+ path: /devices/interaction/neural-networks
+- title: Peripherals
+ path: /devices/accessories
+ section:
+ - title: Audio Accessories
+ section:
+ - title: Overview
+ path: /devices/accessories/audio
+ - title: 3.5 mm Headset
+ section:
+ - title: Headset Spec
+ path: /devices/accessories/headset/plug-headset-spec
+ - title: Device Spec
+ path: /devices/accessories/headset/jack-headset-spec
+ - title: USB Headset
+ section:
+ - title: Headset Spec
+ path: /devices/accessories/headset/usb-headset-spec
+ - title: Adapter Spec
+ path: /devices/accessories/headset/usb-adapter
+ - title: Device Spec
+ path: /devices/accessories/headset/usb-device
+ - 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
+ path: /devices/sensors/
+ - title: Sensor Stack
+ path: /devices/sensors/sensor-stack
+ - title: Reporting Modes
+ path: /devices/sensors/report-modes
+ - title: Suspend Mode
+ path: /devices/sensors/suspend-mode
+ - title: Power Consumption
+ path: /devices/sensors/power-use
+ - title: Interaction
+ path: /devices/sensors/interaction
+ - title: HAL Interface
+ path: /devices/sensors/hal-interface
+ - title: Batching
+ path: /devices/sensors/batching
+ - title: Sensor Types
+ path: /devices/sensors/sensor-types
+ - title: Version Deprecation
+ path: /devices/sensors/versioning
+- title: TV
+ section:
+ - title: Overview
+ path: /devices/tv
+ - title: HDMI-CEC Control Service
+ path: /devices/tv/hdmi-cec
+ - title: Reference TV App
+ path: /devices/tv/reference-tv-app
+ - title: Customize the TV App
+ path: /devices/tv/customize-tv-app
diff --git a/en/devices/_toc-media.yaml b/en/devices/_toc-media.yaml
new file mode 100644
index 0000000..1bc99e4
--- /dev/null
+++ b/en/devices/_toc-media.yaml
@@ -0,0 +1,11 @@
+toc:
+- title: Overview
+ path: /devices/media/
+- title: Framework Hardening
+ path: /devices/media/framework-hardening
+- title: SoC Dependencies
+ path: /devices/media/soc
+- title: OEM Dependencies
+ path: /devices/media/oem
+- title: DRM
+ path: /devices/drm
diff --git a/en/devices/_toc-performance.yaml b/en/devices/_toc-performance.yaml
new file mode 100644
index 0000000..83f3140
--- /dev/null
+++ b/en/devices/_toc-performance.yaml
@@ -0,0 +1,21 @@
+toc:
+- title: Health
+ section:
+ - title: Overview
+ path: /devices/tech/health/
+ - title: Implementing Health
+ path: /devices/tech/health/implementation
+ - title: Deprecating health@1.0
+ path: /devices/tech/health/deprecation
+- title: APK Caching
+ path: /devices/tech/perf/apk-caching
+- title: Boot Times
+ path: /devices/tech/perf/boot-times
+- title: Low RAM
+ path: /devices/tech/perf/low-ram
+- title: Profile Guided Optimization (PGO)
+ path: /devices/tech/perf/pgo
+- title: Task Snapshots
+ path: /devices/tech/perf/task-snapshots
+- title: Write-Ahead Logging
+ path: /devices/tech/perf/compatibility-wal
diff --git a/en/devices/_toc-permissions.yaml b/en/devices/_toc-permissions.yaml
new file mode 100644
index 0000000..5857602
--- /dev/null
+++ b/en/devices/_toc-permissions.yaml
@@ -0,0 +1,17 @@
+toc:
+ - title: Privileged Permission Whitelist
+ path: /devices/tech/config/perms-whitelist
+ - title: Runtime Permissions
+ path: /devices/tech/config/runtime_perms
+ - title: Time Zone Rules
+ path: /devices/tech/config/timezone-rules
+ - title: Ambient Capabilities
+ path: /devices/tech/config/ambient
+ - title: Discretionary Access Control
+ path: /devices/tech/config/filesystem
+ - title: Library Namespaces
+ path: /devices/tech/config/namespaces_libraries
+ - title: USB HAL
+ path: /devices/tech/config/usb-hal
+ - title: Visual Voicemail
+ path: /devices/tech/config/voicemail
diff --git a/en/devices/_toc-power.yaml b/en/devices/_toc-power.yaml
new file mode 100644
index 0000000..f2a8d12
--- /dev/null
+++ b/en/devices/_toc-power.yaml
@@ -0,0 +1,19 @@
+toc:
+- title: Overview
+ path: /devices/tech/power/
+- title: Power Management
+ path: /devices/tech/power/mgmt
+- title: App Management
+ path: /devices/tech/power/app_mgmt
+- title: Platform Management
+ path: /devices/tech/power/platform_mgmt
+- title: Performance Management
+ path: /devices/tech/power/performance
+- title: Batteryless Devices
+ path: /devices/tech/power/batteryless
+- title: Component Power
+ path: /devices/tech/power/component
+- title: Device Power
+ path: /devices/tech/power/device
+- title: Power Values
+ path: /devices/tech/power/values
diff --git a/en/devices/_toc-runtime.yaml b/en/devices/_toc-runtime.yaml
new file mode 100644
index 0000000..6e95229
--- /dev/null
+++ b/en/devices/_toc-runtime.yaml
@@ -0,0 +1,19 @@
+toc:
+- title: Overview
+ path: /devices/tech/dalvik
+- title: Improvements
+ path: /devices/tech/dalvik/improvements
+- title: Bytecode Format
+ path: /devices/tech/dalvik/dalvik-bytecode
+- title: Dex Format
+ path: /devices/tech/dalvik/dex-format
+- title: Instruction Formats
+ path: /devices/tech/dalvik/instruction-formats
+- title: Constraints
+ path: /devices/tech/dalvik/constraints
+- title: Configuration
+ path: /devices/tech/dalvik/configure
+- title: Garbage Collection
+ path: /devices/tech/dalvik/gc-debug
+- title: JIT Compilation
+ path: /devices/tech/dalvik/jit-compiler
diff --git a/en/devices/_toc-storage.yaml b/en/devices/_toc-storage.yaml
new file mode 100644
index 0000000..9990cff
--- /dev/null
+++ b/en/devices/_toc-storage.yaml
@@ -0,0 +1,13 @@
+toc:
+- title: Overview
+ path: /devices/storage/
+- title: Traditional Storage
+ path: /devices/storage/traditional
+- title: Adoptable Storage
+ path: /devices/storage/adoptable
+- title: Device Configuration
+ path: /devices/storage/config
+- title: Configuration Examples
+ path: /devices/storage/config-example
+- title: Faster Statistics
+ path: /devices/storage/faster-stats
diff --git a/en/devices/_toc-interfaces.yaml b/en/devices/_toc-systems.yaml
similarity index 96%
copy from en/devices/_toc-interfaces.yaml
copy to en/devices/_toc-systems.yaml
index 7fb6b5c..5f91e99 100644
--- a/en/devices/_toc-interfaces.yaml
+++ b/en/devices/_toc-systems.yaml
@@ -9,6 +9,8 @@
path: /devices/architecture/hal
- title: HAL Types
path: /devices/architecture/hal-types
+ - title: Treble
+ path: /devices/architecture/treble
- title: Kernel
section:
- title: Overview
@@ -164,21 +166,21 @@
- title: Latency
section:
- title: Overview
- path: /devices/audio/latency/latency
+ path: /devices/audio/latency
- title: Contributors
- path: /devices/audio/latency/contrib
+ path: /devices/audio/latency_contrib
- title: Design
- path: /devices/audio/latency/design
+ path: /devices/audio/latency_design
- title: Measure
- path: /devices/audio/latency/measure
+ path: /devices/audio/latency_measure
- title: Light Testing Circuit
- path: /devices/audio/latency/testing_circuit
+ path: /devices/audio/testing_circuit
- title: Audio Loopback Dongle
- path: /devices/audio/latency/loopback
+ path: /devices/audio/loopback
- title: Measurements
- path: /devices/audio/latency/measurements
+ path: /devices/audio/latency_measurements
- title: Applications
- path: /devices/audio/latency/app
+ path: /devices/audio/latency_app
- title: Priority Inversion
path: /devices/audio/avoiding_pi
- title: Sample Rate Conversion
diff --git a/en/devices/_toc-update.yaml b/en/devices/_toc-update.yaml
new file mode 100644
index 0000000..e3b86dd
--- /dev/null
+++ b/en/devices/_toc-update.yaml
@@ -0,0 +1,27 @@
+toc:
+- title: Overview
+ path: /devices/tech/ota/
+- title: OTA Tools
+ path: /devices/tech/ota/tools
+- title: Signing Builds for Release
+ path: /devices/tech/ota/sign_builds
+- title: Reducing OTA Size
+ path: /devices/tech/ota/reduce_size
+- title: A/B System Updates
+ section:
+ - title: Overview
+ path: /devices/tech/ota/ab/
+ - title: Implementing A/B Updates
+ path: /devices/tech/ota/ab/ab_implement
+ - title: Frequently Asked Questions
+ path: /devices/tech/ota/ab/ab_faqs
+- title: Non-A/B System Updates
+ section:
+ - title: Overview
+ path: /devices/tech/ota/nonab/
+ - title: Block-Based OTA
+ path: /devices/tech/ota/nonab/block
+ - title: Inside OTA Packages
+ path: /devices/tech/ota/nonab/inside_packages
+ - title: Device-Specific Code
+ path: /devices/tech/ota/nonab/device_code
diff --git a/en/devices/architecture/dto/compile.html b/en/devices/architecture/dto/compile.html
index 65e3cbc..aea2f3b 100644
--- a/en/devices/architecture/dto/compile.html
+++ b/en/devices/architecture/dto/compile.html
@@ -1,10 +1,12 @@
-<html devsite>
- <head>
- <title>Compiling & Verifying</title>
- <meta name="project_path" value="/_project.yaml" />
- <meta name="book_path" value="/_book.yaml" />
- </head>
- <body>
+<html devsite="">
+<head>
+ <title>Compiling & Verifying</title>
+ <meta name="project_path" value="/_project.yaml">
+ <meta name="book_path" value="/_book.yaml">
+</head>
+
+<body>
+ {% include "_versions.html" %}
<!--
Copyright 2017 The Android Open Source Project
@@ -21,83 +23,408 @@
limitations under the License.
-->
-<p>You can use Device Tree Compiler (DTC) to compile the Device Tree Source
-files. However, before applying the overlay DT on the target main DT, you should
-also verify the result by simulating the behavior of DTO.</p>
-<h2 id=compile>Compiling with DTC</h2>
-<p>When using <code>dtc</code> to compile <code>.dts</code>, you must add option
-<code>-@</code> to add a <code>__symbols__</code> node in the resulting
-<code>.dtbo</code>. The <code>__symbols__</code> node contains a list of all
-nodes that are marked with a label, which the DTO library can use for
-references.</p>
+ <p>You can use Device Tree Compiler (DTC) to compile the Device Tree Source
+ files. However, before applying the overlay DT on the target main DT, you
+ should also verify the result by simulating the behavior of DTO.</p>
-<p>Sample command to build main DT <code>.dts</code>:</p>
-<pre class="devsite-terminal">
+ <h2 id="compile">Compiling with DTC</h2>
+
+
+ <p>When using <code>dtc</code> to compile <code>.dts</code>, you must add
+ option <code>-@</code> to add a <code>__symbols__</code> node in the
+ resulting <code>.dtbo</code>. The <code>__symbols__</code> node contains a
+ list of all nodes that are marked with a label, which the DTO library can use
+ for references.</p>
+
+
+ <p>Sample command to build main DT <code>.dts</code>:</p>
+
+ <pre class="devsite-terminal">
dtc -@ -O dtb -o my_main_dt.dtb my_main_dt.dts
</pre>
-<p>Sample command to build the overlay DT <code>.dts</code>:</p>
+ <p>Sample command to build the overlay DT <code>.dts</code>:</p>
-<pre class="devsite-terminal">
+ <pre class="devsite-terminal">
dtc -@ -O dtb -o my_overlay_dt.dtbo my_overlay_dt.dts
</pre>
-<p class="note"><strong>Note:</strong> If you encounter the DTC build error:
-<code>invalid option --'@'</code>, you might need to update your DTC version.
-Upstream of AOSP, the official DTC supports DTO as of
-<a href="https://github.com/dgibson/dtc/tree/v1.4.4" class="external">version
-1.4.4</a> and most patches are merged after December 2016. For DTO support, we
-recommend using the
-<code><a href="https://android.googlesource.com/platform/external/dtc/" class="external">external/dtc</code></a>
-in AOSP, which is synced with the latest DTC (with DTO patches merged as
-needed).</p>
+ <aside class="note"><strong>Note:</strong> If you encounter the DTC build error:
+ <code>invalid option --'@'</code>, you might need to update your DTC version.
+ Upstream of AOSP, the official DTC supports DTO as of <a href=
+ "https://github.com/dgibson/dtc/tree/v1.4.4" class="external">version
+ 1.4.4</a> and most patches are merged after December 2016. For DTO support,
+ we recommend using the <code><a href=
+ "https://android.googlesource.com/platform/external/dtc/" class=
+ "external">external/dtc</a></code> in AOSP, which is synced with the latest DTC
+ (with DTO patches merged as needed).</aside>
-<h2 id=verify>Verify DTO results on the host</h2>
-<p>Verification can help you identify errors that might occur when placing the
-overlay DT on the main DT. Before updating the target, you can verify the
-result of overlaying DT on the host by simulating the behavior of DTO using
-<code>/include/</code> in <code>.dts</code>.</p>
-<p class="note"><strong>Note:</strong> <code>/include/</code> does NOT support
-the use of <code>__overlay__</code> in overlay DT sources.</p>
+ <h2 id="verify">Verify DTO results on the host</h2>
-<p><img src="../images/treble_dto_simulate.png"></p>
-<p><strong>Figure 1.</strong> Use syntax <code>/include/</code> to simulate DTO
-on the host.</p>
-<ol>
-<li>Create a copy of the overlay <code>.dts</code>. In the copy, remove the
-first line header. Example:
-<pre>
+ <p>Verification can help you identify errors that might occur when placing
+ the overlay DT on the main DT. Before updating the target, you can verify the
+ result of overlaying DT on the host by simulating the behavior of DTO using
+ <code>/include/</code> in <code>.dts</code>.</p>
+
+
+ <aside class="note"><strong>Note:</strong> <code>/include/</code> does NOT
+ support the use of <code>__overlay__</code> in overlay DT sources.</aside>
+
+
+ <p><img src="../images/treble_dto_simulate.png">
+ </p>
+
+
+ <figcaption><strong>Figure 1.</strong> Use syntax <code>/include/</code> to simulate
+ DTO on the host</figcaption>
+
+
+ <ol>
+ <li>Create a copy of the overlay <code>.dts</code>. In the copy, remove the
+ first line header. Example:
+
+ <pre>
/dts-v1/;
/plugin/;
-</pre>
-Save the file as <code>my_overlay_dt_wo_header.dts</code> (or any filename you
-want).</li>
+</pre>Save the file as <code>my_overlay_dt_wo_header.dts</code> (or any
+filename you want).
+ </li>
-<li>Create a copy of the main <code>.dts</code>. In the copy, after the last
-line, append the include syntax for the file you created in step 1. For example:
-<pre>
+
+ <li>Create a copy of the main <code>.dts</code>. In the copy, after the
+ last line, append the include syntax for the file you created in step 1.
+ For example:
+
+ <pre>
/include/ "my_overlay_dt_wo_header.dts"
-</pre>
-Save the file as <code>my_main_dt_with_include.dts</code> (or any filename you
-want).</li>
+</pre>Save the file as <code>my_main_dt_with_include.dts</code> (or any
+filename you want).
+ </li>
-<li>Use <code>dtc</code> to compile <code>my_main_dt_with_include.dts</code> to
-get the merged DT, which should be the same result as DTO. For example:
-<pre class="devsite-terminal">
+
+ <li>Use <code>dtc</code> to compile
+ <code>my_main_dt_with_include.dts</code> to get the merged DT, which should
+ be the same result as DTO. For example:
+
+ <pre class="devsite-terminal">
dtc -@ -O dtb -o my_merged_dt.dtb my_main_dt_with_include.dts
</pre>
-</li>
+ </li>
-<li>Use <code>dtc</code> to dump <code>my_merged_dt.dto</code>.
-<pre class="devsite-terminal">
+
+ <li>Use <code>dtc</code> to dump <code>my_merged_dt.dto</code>.
+
+ <pre class="devsite-terminal">
dtc -O dts -o my_merged_dt.dts my_merged_dt.dtb
</pre>
-</li>
-</ol>
+ </li>
+ </ol>
- </body>
+
+ <h2 id="verifying-DTO-in-p">Verifying DTO in Android {{ androidPVersionNumber }}</h2>
+
+
+ <p>Android {{ androidPVersionNumber}} requires a Device Tree Blob Overlay
+ (DTBO) partition. To add nodes or make changes to the properties in the SoC
+ DT, the bootloader must dynamically overlay a device specific DT over
+ the SoC DT.</p>
+
+
+ <h3 id="indicating-applied-overlays">Indicating applied overlays</h3>
+
+
+ <p>To enable the <a href="/compatibility/vts/">
+ Vendor Test Suite (VTS)</a> to assess the correctness of overlay
+ application, vendors must add a new kernel command line parameter
+ <code>androidboot.dtbo_idx</code> that indicates the overlays selected from
+ the DTBO partition. For example, the parameter <code>androidboot.
+ dtbo_idx=x,y,z</code> reports <code>x</code>, <code>y</code> and
+ <code>z</code> as the zero-based indices of the Device Tree Overlays (DTOs)
+ from the DTBO partition applied (in that order) by the bootloader to the base
+ Device Tree (DT).</p>
+
+
+ <p>Overlays can apply to nodes from the main device tree or add new nodes,
+ but <strong>cannot</strong> refer to a node added in a previous overlay. This
+ restriction is necessary because the overlay application does not merge the
+ overlay symbol table with the main DT symbol table (not merging avoids
+ conflicts in symbol names and complication of dependencies between
+ overlays).</p>
+
+
+ <h4 id="example-invalid-overlays">Example: Invalid overlays</h4>
+
+
+ <p>In this example, <code>overlay_2.dts</code> refers to node
+ <strong><code>e</code></strong> , which was added by
+ <code>overlay_1.dts</code>. After <code>overlay_1</code> is applied to the
+ main DT, if an attempt is made to apply <code>overlay_2</code> to the
+ resultant DT, the overlay application will fail with an error that the symbol
+ <strong><code>e</code></strong> is not present in the symbol table for the
+ base DT.</p>
+
+
+ <table>
+ <tr>
+ <th width="33%">main.dts</th>
+
+ <th>overlay_1.dts</th>
+
+ <th>overlay_2.dts</th>
+
+ </tr>
+ <tr>
+ <td>
+ <pre>
+<strong>[main.dts]</strong>
+
+/dts-v1/;
+
+/ {
+ a: a {};
+ b: b {};
+ c: c {};
+};
+</pre>
+ </td>
+
+ <td>
+ <pre>
+<strong>[overlay_1.dts]</strong>
+
+/dts-v1/;
+/plugin/;
+
+&b { ref1 = <&a>;
+ e: e {
+ prop = <0x0a>;
+ phandle = <0x04>;
+ };
+};
+</pre>
+</td>
+
+ <td>
+<pre>
+<strong>[overlay_2.dts]</strong>
+
+/dts-v1/;
+/plugin/;
+
+/* invalid! */
+<font color="red">&e</font> {
+ prop = <0x0b>;
+};
+</pre>
+ </td>
+ </tr>
+ </table>
+
+
+ <h4 id="example-valid-overlays">Example: Valid overlays</h4>
+
+
+ <p>In this example, <code>overlay_2.dts</code> refers only to node
+ <strong><code>b</code></strong> from the main DTS. When
+ <code>overlay_1</code> is applied to the base DT, then followed by the
+ application of <code>overlay_2</code>, the value of property
+ <strong><code>prop</code></strong> in node <strong><code>e</code></strong>
+ (set by <code>overlay_1.dts</code>) is overwritten by the value set by
+ <code>overlay_2.dts</code>.</p>
+
+
+ <table>
+ <tr>
+ <th width="33%">main.dts</th>
+
+ <th>overlay_1.dts</th>
+
+ <th>overlay_2.dts</th>
+
+ </tr>
+
+
+ <tr>
+ <td>
+ <pre>
+<strong>[final.dts]</strong>
+
+/dts-v1/;
+
+/ {
+ a: a {};
+ b: b {};
+ c: c {};
+};
+</pre>
+ </td>
+
+ <td>
+ <pre>
+<strong>[overlay_1.dts]</strong>
+
+/dts-v1/;
+/plugin/;
+
+
+&b { ref1 = <&a>;
+ e {
+ prop = <0x0c>;
+ };
+};
+</pre>
+ </td>
+
+ <td>
+ <pre>
+<strong>[overlay_2.dts]</strong>
+
+/dts-v1/;
+/plugin/;
+
+/* valid */
+<font color="blue">&b</font> { ref1 = <&c>;
+ e {
+ prop = <0x0d>;
+ };
+};
+</pre>
+ </td>
+ </tr>
+ </table>
+
+
+ <h3 id="implementing-the-dtbo-partition">Implementing the DTBO partition</h3>
+
+
+ <p>To implement the required DTBO partition, ensure the bootloader can do the
+ following:</p>
+
+
+ <ol>
+ <li>Identify the board it is running on and select the corresponding
+ overlay(s) to be applied.</li>
+
+
+ <li>Append the <code>androidboot.dtbo_idx</code> parameter to the kernel
+ command line.
+
+ <ul>
+ <li>The parameter must indicate, the zero-based indices of the DTOs
+ from the DTBO partition image it applied to the base DT (in the same
+ order).</li>
+
+
+ <li>The indices must refer to the position of the overlay in the DTBO
+ partition.</li>
+ </ul>
+ </li>
+ </ol>
+
+
+ <p>For details on the structure of the DTBO partition, refer to <a href=
+ "https://source.android.com/devices/architecture/dto/">Device Tree
+ Overlays</a> on source.android.com.</p>
+
+
+ <h3 id="validating-the-dtbo-partition">Validating the DTBO partition</h3>
+
+
+ <p>You can use VTS to verify the following:</p>
+
+
+ <ul>
+ <li>Existence of the kernel command line parameter
+ <code>androidboot.dtbo_idx</code> (by checking that <code>Init</code> has
+ automatically set up the corresponding <code>ro.boot.dtbo_idx</code> system
+ property).</li>
+
+
+ <li>Validity of the <code>ro.boot.dtbo_idx</code> system property (by
+ checking that the property specifies at least one valid DTBO image
+ index).</li>
+
+
+ <li>Validity of the DTBO partition (also verifies the overlays in the DTBO
+ partition that are applied to the base DT).</li>
+
+
+ <li>Additional nodes or property changes in the resulting DT are presented
+ to the Linux kernel.</li>
+ </ul>
+
+
+ <p>For example, in the following overlays and final DT, adding
+ <code>androidboot.dtbo_idx=5,3</code> to the kernel command line passes
+ validation but adding <code>androidboot.dtbo_idx=3,5</code> to the kernel
+ command line does not pass validation.</p>
+
+
+ <table>
+ <tr>
+ <th width="50%">Overlay DT at index 3</th>
+
+
+ <th>Overlay DT at index 5</th>
+
+<tr>
+<td>
+<pre>
+<strong>[overlay_1.dts]</strong>
+
+/dts-v1/;
+/plugin/;
+
+&c <strong>{ prop = <0xfe>; }</strong>;
+</pre>
+ </td>
+
+ <td>
+ <pre>
+<strong>[overlay_2.dts]</strong>
+
+/dts-v1/;
+/plugin/;
+
+&c { prop = <0xff>; };
+</pre>
+ </td>
+ </tr>
+
+<table>
+ <tr>
+ <th>Final DT</th>
+
+ <tr>
+ <td>
+ <pre>
+/dts-v1/;
+/ {
+
+ a {
+ phandle = <0x1>;
+ };
+
+ b {
+ phandle = <0x2>;
+ };
+
+ c {
+ phandle = <0x3>;
+ <strong>prop = <0xfe></strong>;
+ };
+
+ __symbols__ {
+ a = "/a";
+ b = "/b";
+ c = "/c";
+ };
+};
+
+ </table>
+</body>
</html>
diff --git a/en/devices/architecture/dto/index.html b/en/devices/architecture/dto/index.html
index 3fdf3c2..8470b2a 100644
--- a/en/devices/architecture/dto/index.html
+++ b/en/devices/architecture/dto/index.html
@@ -5,8 +5,9 @@
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
+ {% include "_versions.html" %}
<!--
- Copyright 2017 The Android Open Source Project
+ Copyright 2018 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.
@@ -29,11 +30,11 @@
which Linux then compiles into the Device Tree Blob (DTB) file used by the
bootloader.</p>
-A <a href="https://lkml.org/lkml/2012/11/5/615" class="external">device tree
-overlay</a> (DTO) enables a central DTB to be overlaid on the device tree. A
-bootloader using DTO can maintain the system-on-chip (SoC) DT and dynamically
-overlay a device-specific DT, adding nodes to the tree and making changes to
-properties in the existing tree.</p>
+<p>A <a href="https://lkml.org/lkml/2012/11/5/615" class="external">device tree
+overlay</a> (DTO) enables a central device tree blob (DTB) to be overlaid on
+the device tree. A bootloader using DTO can maintain the system-on-chip (SoC)
+DT and dynamically overlay a device-specific DT, adding nodes to the tree and
+making changes to properties in the existing tree.</p>
<p>This page details a typical bootloader workflow for loading a DT and provides
a list of common DT terms. Other pages in this section describe how to
@@ -44,10 +45,15 @@
implementation</a>, and how to
<a href="/devices/architecture/dto/multiple.html">use multiple DTs</a>. You can
also get details on <a href="/devices/architecture/dto/syntax.html">DTO
-syntax</a> and recommended
-<a href="/devices/architecture/dto/partition.html">DTO/DTBO partition
+syntax</a> and required
+<a href="/devices/architecture/dto/partitions.html">DTO/DTBO partition
formatting</a>.</p>
+<h2 id="p-update">Updates in Android {{ androidPVersionNumber }} Release</h2>
+<p>In Android {{ androidPVersionNumber }}, the bootloader must not modify the
+properties defined in the device tree overlays before passing the unified
+device tree blob to the kernel.</p>
+
<h2 id=load-dt>Loading a device tree</h2>
<p>Loading a device tree in bootloader involves building, partitioning, and
running.</p>
diff --git a/en/devices/architecture/dto/optimize.html b/en/devices/architecture/dto/optimize.html
index 7502d7a..7624cc1 100644
--- a/en/devices/architecture/dto/optimize.html
+++ b/en/devices/architecture/dto/optimize.html
@@ -5,6 +5,7 @@
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
+ {% include "_versions.html" %}
<!--
Copyright 2017 The Android Open Source Project
@@ -21,14 +22,21 @@
limitations under the License.
-->
-<p>This page details optimizations you can make to your DTO implementation,
-describes restrictions against overlaying the root node, and provides sample
-implementation instructions and code.</p>
+<p>
+ This page discusses optimizations you can make to your DTO implementation,
+ describes restrictions against overlaying the root node, and details how to
+ configure compressed overlays in the DTBO image. It also provides sample
+ implementation instructions and code.
+</p>
<h2 id=kernel>Kernel command line</h2>
-<p>The original kernel command line in device tree is located in the
-<code>chosen/bootargs</code> node. The bootloader must concatenate this location
-with other sources of kernel command line:</p>
+
+<p>
+ The original kernel command line in device tree is located in the
+ <code>chosen/bootargs</code> node. The bootloader must concatenate this
+ location with other sources of kernel command line:
+</p>
+
<pre class="prettyprint">
/dts-v1/;
@@ -39,11 +47,13 @@
};
</pre>
-<p>DTO <strong>cannot</strong> concatenate values from main DT and overlay DT.
-We recommend putting the kernel command line of the main DT in
-<code>chosen/bootargs</code> and the kernel command line of the overlay DT in
-<code>chosen/bootargs_ext</code>. Bootloader can then concatenate these
-locations and pass the result to the kernel.</p>
+<p>
+ DTO <strong>cannot</strong> concatenate values from main DT and overlay DT, so
+ you must put the kernel command line of the main DT in
+ <code>chosen/bootargs</code> and the kernel command line of the overlay DT in
+ <code>chosen/bootargs_ext</code>. Bootloader can then concatenate these
+ locations and pass the result to the kernel.
+</p>
<table>
<tr>
@@ -77,47 +87,70 @@
</table>
<h2 id=libufdt>libufdt</h2>
-<p>While the latest
-<code><a href="https://github.com/dgibson/dtc/tree/master/libfdt" class="external">libfdt</code></a>
-supports DTO, we recommend using <code>libufdt</code> to implement DTO (source
-at
-<code><a href="https://android.googlesource.com/platform/system/libufdt/+/refs/heads/master" class="external">platform/system/libufdt</code></a>
-in AOSP). <code>libufdt</code> builds a real tree structure (un-flattened device
-tree, or <em>ufdt</em>) from the flattened device tree (FDT), so it can improve
-the merging of two <code>.dtb</code> files from O(N2) to O(N), where N is the
-number of nodes in the tree.</p>
+
+<p>
+ While the latest
+ <code><a href="https://github.com/dgibson/dtc/tree/master/libfdt" class="external">libfdt</code></a>
+ supports DTO, is it recommended to use <code>libufdt</code> to implement DTO
+ (AOSP source at
+ <code><a href="https://android.googlesource.com/platform/system/libufdt/+/refs/heads/master" class="external">platform/system/libufdt</code></a>).
+ <code>libufdt</code> builds a real tree structure (un-flattened device tree,
+ or <em>ufdt</em>) from the flattened device tree (FDT), so it can improve the
+ merging of two <code>.dtb</code> files from O(N2) to O(N), where N is the
+ number of nodes in the tree.
+</p>
<h3 id=performance>Performance testing</h3>
-<p>In Google's internal testing, using <code>libufdt</code> on 2405
-<code>.dtb</code> and 283 <code>.dtbo</code> DT nodes results in file sizes of
-70,618 and 8,566 bytes after compilation. Compared with a
-<a href="http://fxr.watson.org/fxr/source/boot/fdt/" class="external">DTO
-implementation</a> ported from FreeBSD (124ms runtime), <code>libufdt</code>
-DTO runtime is 10ms.</p>
-<p>In performance testing for Pixel devices, we compared <code>libufdt</code>
-and <code>libfdt</code>. The number of base nodes effect is similar, but
-includes the following differences:</p>
+<p>
+ In Google's internal testing, using <code>libufdt</code> on 2405
+ <code>.dtb</code> and 283 <code>.dtbo</code> DT nodes results in file sizes of
+ 70,618 and 8,566 bytes after compilation. Compared with a
+ <a href="http://fxr.watson.org/fxr/source/boot/fdt/" class="external">DTO
+ implementation</a> ported from FreeBSD (124 ms runtime), <code>libufdt</code>
+ DTO runtime is 10 ms.
+</p>
+
+<p>
+ Performance testing for Pixel devices compared <code>libufdt</code> and
+ <code>libfdt</code>. The number of base nodes effect is similar, but includes
+ the following differences:
+</p>
+
<ul>
-<li>500 overlay (append or override) operations have 6~8x time difference</li>
-<li>1000 overlay (append or override) operations have 8~10x time difference</li>
+ <li>500 overlay (append or override) operations have 6x to 8x time
+ difference</li>
+ <li>1000 overlay (append or override) operations have 8x to 10x time
+ difference</li>
</ul>
-<p>Example with appending count set to X:</p>
+<p>
+ Example with appending count set to X:
+</p>
+
<p><img src="../images/treble_dto_appending.png"></p>
-<figcaption><strong>Figure 1.</strong> Appending count is X.</figcaption>
+<figcaption><strong>Figure 1.</strong> Appending count is X</figcaption>
-<p>Example with overriding count set to X:</p>
+<p>
+ Example with overriding count set to X:
+</p>
+
<p><img src="../images/treble_dto_overriding.png"></p>
-<figcaption><strong>Figure 2.</strong> Overriding count is X.</figcaption>
+<figcaption><strong>Figure 2.</strong> Overriding count is X</figcaption>
-<p><code>libufdt</code> is developed with some <code>libfdt</code> APIs and data
-structures. When using <code>libufdt</code>, you must include and link
-<code>libfdt</code> (however in your code you can use <code>libfdt</code> API to
-operate DTB or DTBO).</p>
+<p>
+ <code>libufdt</code> is developed with some <code>libfdt</code> APIs and data
+ structures. When using <code>libufdt</code>, you must include and link
+ <code>libfdt</code> (however, in your code you can use the <code>libfdt</code>
+ API to operate DTB or DTBO).
+</p>
<h3 id=api>libufdt DTO API</h3>
-<p>The main API to DTO in <code>libufdt</code> is as follows:</p>
+
+<p>
+ The main API to DTO in <code>libufdt</code> is as follows:
+</p>
+
<pre class="prettyprint">
struct fdt_header *ufdt_apply_overlay(
struct fdt_header *main_fdt_header,
@@ -126,30 +159,39 @@
size_t overlay_size);
</pre>
-<p>The parameter <code>main_fdt_header</code> is the main DT and
-<code>overlay_fdt</code> is the buffer containing the contents of a
-<code>.dtbo</code> file. The return value is a new buffer containing the merged
-DT (or <code>null</code> in case of error). The merged DT is formated in FDT,
-which you can pass to the kernel when starting the kernel.</p>
+<p>
+ The parameter <code>main_fdt_header</code> is the main DT and
+ <code>overlay_fdt</code> is the buffer containing the contents of a
+ <code>.dtbo</code> file. The return value is a new buffer containing the
+ merged DT (or <code>null</code> in case of error). The merged DT is formated
+ in FDT, which you can pass to the kernel when starting the kernel.
+</p>
-<p>The new buffer from the return value is created by <code>dto_malloc()</code>,
-which you should implement when porting <code>libufdt</code> into bootloader.
-For reference implementations, refer to
-<code>sysdeps/libufdt_sysdeps_*.c</code>.</p>
+<p>
+ The new buffer from the return value is created by <code>dto_malloc()</code>,
+ which you should implement when porting <code>libufdt</code> into bootloader.
+ For reference implementations, refer to
+ <code>sysdeps/libufdt_sysdeps_*.c</code>.
+</p>
<h2 id=root>Root node restrictions</h2>
-<p>You cannot overlay a new node or property into the root node of main DT
-because overlay operations rely on labels. Because the main DT must define a
-label and the overlay DT assigns the nodes to be overlaid with labels, we
-cannot give a label for the root node (and therefore cannot overlay the root
-node).</p>
-<p>SoC vendors must define the overlaying ability of main DT; ODM/OEMs can only
-append or override nodes with labels defined by the SoC vendor. As a workaround,
-you can define a <strong><code>odm</code></strong> node under the root node in
-base DT, enabling all ODM nodes in overlay DT to add new nodes. Alternatively,
-you could put all SoC-related nodes in the base DT into a
-<strong><code>soc</code></strong> node under root node as described below:</p>
+<p>
+ You cannot overlay a new node or property into the root node of main DT
+ because overlay operations rely on labels. Because the main DT must define a
+ label and the overlay DT assigns the nodes to be overlaid with labels, you
+ cannot give a label for the root node (and therefore cannot overlay the root
+ node).
+</p>
+
+<p>
+ SoC vendors must define the overlaying ability of main DT; ODM/OEMs can only
+ append or override nodes with labels defined by the SoC vendor. As a
+ workaround, you can define an <strong><code>odm</code></strong> node under the
+ root node in base DT, enabling all ODM nodes in overlay DT to add new nodes.
+ Alternatively, you could put all SoC-related nodes in the base DT into an
+ <strong><code>soc</code></strong> node under root node as described below:
+</p>
<table>
<tr>
@@ -209,64 +251,103 @@
</tr>
</table>
+<h2 id="compressed-overlays">Using compressed overlays</h2>
+
+<p>
+ Android {{ androidPVersionNumber }} adds support for using compressed overlays
+ in the DTBO image when using version 1 of the device tree table header.
+ When using DTBO header v1, the four least significant bits of the flags field
+ in <em>dt_table_entry</em> indicate the compression format of the DT entry.
+</p>
+
+<pre class="prettyprint">struct dt_table_entry_v1 {
+ uint32_t dt_size;
+ uint32_t dt_offset; /* offset from head of dt_table_header */
+ uint32_t id; /* optional, must be zero if unused */
+ uint32_t rev; /* optional, must be zero if unused */
+ uint32_t flags; /* For version 1 of dt_table_header, the 4 least significant bits
+ of 'flags' will be used to indicate the compression
+ format of the DT entry as per the enum 'dt_compression_info' */
+ uint32_t custom[3]; /* optional, must be zero if unused */
+};
+</pre>
+
+<p>
+ Currently, <code>zlib</code> and <code>gzip</code> compressions are supported.
+</p>
+
+<pre class="prettyprint">enum dt_compression_info {
+ NO_COMPRESSION,
+ ZLIB_COMPRESSION,
+ GZIP_COMPRESSION
+};
+</pre>
+
+<p>
+ Android {{ androidPVersionNumber }} adds support for testing compressed
+ overlays to the <code>VtsFirmwareDtboVerification</code> test to help you
+ verify the correctness of overlay application.
+</p>
+
<h2 id=sample>Sample DTO implementation</h2>
-<p>The following instructions walk you through a sample implementation of DTO
-with <code>libufdt</code> (sample code below).</p>
+
+<p>
+ The following instructions walk you through a sample implementation of DTO
+ with <code>libufdt</code> (sample code below).
+</p>
<h3 id=sample-instructions>Sample DTO instructions</h3>
<ol>
-<li>Include libraries. To use <code>libufdt</code>, include <code>libfdt</code>
-for data structures and APIs:
+ <li>Include libraries. To use <code>libufdt</code>, include
+ <code>libfdt</code> for data structures and APIs:
<pre class="prettyprint">
#include <libfdt.h>
#include <ufdt_overlay.h>
</pre>
-</li>
-
-<li>Load main DT and overlay DT. Load <code>.dtb</code> and <code>.dtbo</code>
-from storage into memory (exact steps depend on your design). At this point, you
-should have the buffer and size of <code>.dtb</code>/<code>.dtbo</code>:
+ </li>
+ <li>Load main DT and overlay DT. Load <code>.dtb</code> and <code>.dtbo</code>
+ from storage into memory (exact steps depend on your design). At this point,
+ you should have the buffer and size of <code>.dtb</code>/<code>.dtbo</code>:
<pre class="prettyprint">
main_size = my_load_main_dtb(main_buf, main_buf_size)
</pre>
<pre class="prettyprint">
overlay_size = my_load_overlay_dtb(overlay_buf, overlay_buf_size);
</pre>
-</li>
-
-<li>Overlay the DTs:
-<ol>
-
-<li>Use <code>ufdt_install_blob()</code> to get the FDT header for main DT:
+ </li>
+ <li>Overlay the DTs:
+ <ol>
+ <li>Use <code>ufdt_install_blob()</code> to get the FDT header for main DT:
<pre class="prettyprint">
main_fdt_header = ufdt_install_blob(main_buf, main_size);
main_fdt_size = main_size;
</pre>
-</li>
-<li>Call <code>ufdt_apply_overlay()</code> to DTO to get a merged DT in FDT
-format:
+ </li>
+ <li>Call <code>ufdt_apply_overlay()</code> to DTO to get a merged DT in FDT
+ format:
<pre class="prettyprint">
merged_fdt = ufdt_apply_overlay(main_fdt_header, main_fdt_size,
overlay_buf, overlay_size);
</pre>
-</li>
-
-<li>To get the size of <code>merged_fdt</code>, use <code>dtc_totalsize()</code>:
+ </li>
+ <li>Use <code>merged_fdt</code> to get the size of
+ <code>dtc_totalsize()</code>:
<pre class="prettyprint">
merged_fdt_size = dtc_totalsize(merged_fdt);
</pre>
-</li>
-
-<li>Pass merged DT to start kernel. When you start the kernel, pass merged DT to
-kernel:
+ </li>
+ <li>Pass the merged DT to start the kernel:
<pre class="prettyprint">
my_kernel_entry(0, machine_type, merged_fdt);
</pre>
-</li>
-</ol></li></ol>
+ </li>
+ </ol>
+ </li>
+</ol>
<h3 id=sample-code>Sample DTO code</h3>
+
<pre class="prettyprint">
#include <libfdt.h>
#include <ufdt_overlay.h>
diff --git a/en/devices/architecture/dto/partitions.html b/en/devices/architecture/dto/partitions.html
index d18cda8..195f119 100644
--- a/en/devices/architecture/dto/partitions.html
+++ b/en/devices/architecture/dto/partitions.html
@@ -6,7 +6,7 @@
</head>
<body>
<!--
- Copyright 2017 The Android Open Source Project
+ Copyright 2018 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.
@@ -54,7 +54,9 @@
// from head of dt_table_header
uint32_t page_size; // flash page size we assume
- uint32_t reserved[1]; // must be zero
+ uint32_t version; // DTBO image version, the current version is 0.
+ // The version will be incremented when the
+ // dt_table_header struct is updated.
};
struct dt_table_entry {
@@ -288,7 +290,7 @@
dt_entry_count = 3
dt_entries_offset = 32
page_size = 2048
- reserved[0] = 00000000
+ version = 0
dt_table_entry[0]:
dt_size = 380
dt_offset = 128
diff --git a/en/devices/architecture/hal/dynamic-lifecycle.html b/en/devices/architecture/hal/dynamic-lifecycle.html
new file mode 100644
index 0000000..16563ca
--- /dev/null
+++ b/en/devices/architecture/hal/dynamic-lifecycle.html
@@ -0,0 +1,92 @@
+<html devsite="">
+<head>
+ <title>Dynamically Available HALs</title>
+ <meta name="project_path" value="/_project.yaml">
+ <meta name="book_path" value="/_book.yaml">
+</head>
+ {% include "_versions.html" %}
+<body>
+ <!--
+ Copyright 2018 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.
+ -->
+ Android {{ androidPVersionNumber }} supports the dynamic shutdown of Android hardware
+ subsystems when they are not in use or not needed. For example, when a user
+ is not using Wi-Fi, the Wi-Fi subsystems should not be taking up memory,
+ power, or other system resources. In earlier versions of Android, HALs/drivers
+ were kept open on Android devices for the entire duration an Android
+ phone was booted.
+
+ <p>Implementing dynamic shutdown involves wiring up data flows and executing
+ dynamic processes as detailed in the following sections.</p>
+
+
+ <h2 id="changes-HAL-definitions">Changes to HAL definitions</h2>
+
+
+ <p>Dynamic shutdown requires information on which processes serve what HAL
+ interfaces (this information may also be useful later in other contexts) as
+ well as not starting processes on boot and not restarting them (until
+ requested again) when they exit.</p>
+
+ <pre class="prettyprint"># some init.rc script associated with the HAL
+service vendor.some-service-name /vendor/bin/hw/some-binary-service
+ # init language extension, provides information of what service is served
+ # if multiple interfaces are served, they can be specified one on each line
+ interface android.hardware.light@2.0::ILight default
+ # restarted if hwservicemanager dies
+ # would also cause the hal to start early during boot if oneshot wasn't set
+ class hal
+ # will not be restarted if it exits until it is requested to be restarted
+ oneshot
+ # will only be started when requested
+ disabled
+ # ... other properties</pre>
+
+ <h2 id="changes-init-and-hwservicemanager">Changes to init and hwservicemanager</h2>
+
+
+ <p>Dynamic shutdown also requires the <code>hwservicemanager</code> to tell
+ <code>init</code> to start requested services. In Android {{ androidPVersionNumber }},
+ <code>init</code> includes three additional control messages (e.g.
+ <code>ctl.start</code>): <code>ctl.interface_start</code>,
+ <code>ctl.interface_stop</code>, and <code>ctl.interface_restart</code>.
+ These messages can be used to signal <code>init</code> to bring up and down
+ specific hardware interfaces. When a service is requested and it is not
+ registered, <code>hwservicemanager</code> will request the service to be
+ started.</p>
+
+
+ <h2 id="determining-HAL-exit">Determining HAL exit</h2>
+
+
+ <p>Dynamic shutdown requires multiple policies for deciding when to start a
+ HAL and when to shutdown a HAL. If a HAL decides to exit for any reason, it
+ will automatically be restarted when it is needed again using the information
+ provided in the HAL definition and the infrastructure provided by changes to
+ <code>init</code> and <code>hwservicemanager</code>. This could involve a
+ couple of different strategies, including:</p>
+
+
+ <ul>
+ <li>A HAL could choose to call exit on itself if someone calls a close or
+ similar API on it. This behavior must be specified in the corresponding HAL
+ interface.</li>
+
+
+ <li>HALs can shut down when their task is completed (documented in the HAL
+ file).</li>
+ </ul>
+</body>
+</html>
diff --git a/en/devices/architecture/hal/framework-testing.html b/en/devices/architecture/hal/framework-testing.html
new file mode 100644
index 0000000..8eb311a
--- /dev/null
+++ b/en/devices/architecture/hal/framework-testing.html
@@ -0,0 +1,191 @@
+<html devsite="">
+<head>
+ <title>HIDL Framework Backwards Compatibility Verification</title>
+ <meta name="project_path" value="/_project.yaml">
+ <meta name="book_path" value="/_book.yaml">
+</head>
+<body>
+ {% include "_versions.html" %}
+ <!--
+ Copyright 2018 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 href="/devices/architecture/#hidl">HIDL HALs</a>
+ guarantee the Android core system (aka system.img or the framework) is
+ backwards compatible. While <a href="/compatibility/vts">Vendor Test Suite (VTS)</a>
+ tests ensure that HALs work as expected (e.g. 1.1 HAL tests are run on all
+ 1.2 implementations), framework testing is needed to ensure that when a
+ supported HAL (1.0, 1.1, or 1.2) is provided, the framework works properly
+ with that HAL.</p>
+
+
+ <p>For details on HAL interface definition language (HIDL), refer to <a href=
+ "/devices/architecture/hidl">HIDL</a>, <a href=
+ "/devices/architecture/hidl/versioning">HIDL
+ versioning</a>, and <a href=
+ "/devices/architecture/vintf/fcm#hal-version-deprecation">HIDL HAL
+ Deprecation</a>.</p>
+
+
+ <h2 id="about-HAL-upgrades">About HAL upgrades</h2>
+
+ <p>There are two types of HAL upgrades: <em>major</em> and <em>minor</em>.
+ Most systems include only one HAL implementation, but multiple
+ implementations are supported. For example:</p>
+
+<pre>android.hardware.teleport@1.0 # initial interface
+android.hardware.teleport@1.1 # minor version upgrade
+android.hardware.teleport@1.2 # another minor version upgrade
+...
+android.hardware.teleport@2.0 # major version upgrade
+...</pre>
+
+ <p>The system partition typically includes a framework daemon (such as
+ <code>teleportd</code>) that manages communication with a specific group of
+ HAL implementations. Alternatively, systems might instead
+ include a system library (such as
+ <code>android.hardware.configstore-utils</code>) that implements convenient
+ client behavior. In the example above, <code>teleportd</code> must work no
+ matter what version of the HAL is installed on the device.</p>
+
+ <h2 id="google-maintained-versions">Google-maintained versions</h2>
+
+ <p>If major version upgrades (1.0, 2.0, 3.0, etc.) exist, at least one
+ Google-maintained device must maintain an implementation of each major
+ version until that version is deprecated. If no Google-maintained device
+ ships with a specific major version, Google continues to maintain an old
+ implementation of that major version.</p>
+
+ <p>Such maintenance adds minor additional overhead because the old
+ implementation (e.g. 1.2) can be kept and not used by default when a new
+ implementation (e.g. 2.0) is created.</p>
+
+ <h2 id="testing-minor-version-upgrades">Testing minor version upgrades</h2>
+
+ <p>Testing the backwards compatibility of minor versions in the framework
+ requires a way to automatically generate minor version implementations. Given
+ the restrictions around Google-maintained versions, <code>hidl-gen</code>
+ will only (and can only) generate adapters that take a 1.(x+n) implementation
+ and provide a 1.x implementation; it cannot generate a 1.0 implementation
+ from a 2.0 implementation (by definition of a major version).</p>
+
+
+ <p>For example, to run 1.1 tests on a 1.2 implementation, you must be able to
+ simulate having a 1.1 implementation. The 1.2 interfaces can automatically be
+ used as 1.1 implementation with some slight differences in behavior (such as
+ the framework manually checking what version something is or calling
+ <code>castFrom</code> on it).</p>
+ <p>The basic idea is this:</p>
+
+ <ol>
+ <li>Install an x.(y+n) interface on an Android mobile device.</li>
+
+
+ <li>Install and activate an x.y-target adapter.</li>
+
+
+ <li>Test the device to verify it works as expected when running an older
+ minor version.</li>
+ </ol>
+
+ <p>These adapters completely hide the fact that the implementation is
+ actually backed by a 1.2 interface and only provides the 1.1 interface (the
+ adapter takes a 1.2 interface and makes it look like a 1.1 interface).</p>
+
+
+ <h3 id="example-workflow">Example workflow</h3>
+
+
+ <p>In this example, the Android device runs
+ <code>android.hardware.foo@1.1::IFoo/default</code>. To ensure a client works
+ properly with <code>android.hardware.foo@1.0::IFoo/default</code>:</p>
+
+
+ <ol>
+ <li>In a terminal, run the following:
+
+<pre>$ PACKAGE=android.hidl.allocator@1.0-adapter
+$ INTERFACE=IAllocator
+$ INSTANCE=ashmem
+$ THREAD_COUNT=1 # can see current thread use on `lshal -i -e`
+$ m -j $PACKAGE
+$ /data/nativetest64/$PACKAGE/$PACKAGE $INTERFACE $INSTANCE $THREAD_COUNT
+Trying to adapt down android.hidl.allocator@1.0-adapter/default
+Press any key to disassociate adapter.</pre>
+ </li>
+
+ <li>Restart the client using <code>adb shell stop</code> (or
+ <code>start</code>) or simply kill the process.</li>
+
+ <li>After the test completes, disassociate the adapter.</li>
+
+ <li>Restore system state by restarting the device OR by restarting the
+ client.</li>
+ </ol>
+
+ <h3 id="additional-targets">Additional targets</h3>
+
+ <p><code>hidl-gen</code> automatically adds additional build targets for the
+ adapters for every interface specified with <code>hidl_interface</code> in
+ the build system. For package <code>a.b.c@x.y</code>, there is an additional
+ C++ target <code>a.b.c@x.y-adapter</code>.</p>
+
+ <aside class="note"><strong>Note:</strong> No java adapter needs to be made because a C++
+ adapter can always be used to wrap a Java service.</aside>
+
+ <p>An adapter for <code>a.b.c@x.y</code> takes as an input some
+ implementation, <code>a.b.c@x.(y+n)::ISomething/instance-name</code>, and
+ must register <code>a.b.c@x.y::ISomething/instance-name</code> which must
+ also unregister the <code>y+n</code> implementation.</p>
+
+ <p>Given the following sample interface:</p>
+
+<pre>// IFoo.hal
+package a.b.c@1.0;
+interface IFoo {
+ doFoo(int32_t a) generates (int64_t b);
+ doSubInterface() generates (IFoo a);
+};</pre>
+
+ <p>The code provided by <code>a.b.c@1.0-adapter</code> is similar to the
+ sample below:</p>
+
+ <pre>// autogenerated code
+// in namespace a::b::c::V1_0::IFoo
+struct MockFoo {
+ // takes some subclass of V1_0. May be V1_1, V1_2, etc...
+ MockFoo(V1_0::IFoo impl) mImpl(impl) {}
+
+ Return<int64_t> doFoo(int32_t a) {
+ return this->mImpl->doFoo(a);
+ }
+
+ Return<V1_0::ICallback> doSubInterface() {
+ // getMockForBinder returns MockCallback instance
+ // that corresponds to a particular binder object
+ // It can't return a new object every time or
+ // clients using interfacesSame will have
+ // divergent behavior when using the mock.
+ auto _hidl_out = this->mImpl->doSubInterface();
+ return getMockForBinder(_hidl_out);
+ }
+};</pre>
+
+ <p>Data values are forwarded exactly into and out of the auto-generated mock
+ class, except for sub interfaces, which are returned. These interfaces must
+ be wrapped in the corresponding most recent callback object.</p>
+
+</body>
+</html>
diff --git a/en/devices/architecture/hidl-cpp/index.html b/en/devices/architecture/hidl-cpp/index.html
index 1509817..340d576 100644
--- a/en/devices/architecture/hidl-cpp/index.html
+++ b/en/devices/architecture/hidl-cpp/index.html
@@ -92,7 +92,7 @@
<p>For the HAL to work in passthrough mode (for legacy devices), you must have
the function <em>HIDL_FETCH_IModuleName</em> residing in
-<code>/system/lib(64)?/hw/android.hardware.package@3.0-impl($OPTIONAL_IDENTIFIER).so</code>
+<code>/(system|vendor|...)/lib(64)?/hw/android.hardware.package@3.0-impl($OPTIONAL_IDENTIFIER).so</code>
where <code>$OPTIONAL_IDENTIFIER</code> is a string identifying the passthrough
implementation. The passthrough mode requirements are met automatically by the
above commands, which also create the <code>android.hardware.nfc@1.0-impl</code>
diff --git a/en/devices/architecture/hidl/memoryblock.md b/en/devices/architecture/hidl/memoryblock.md
new file mode 100644
index 0000000..de2b349
--- /dev/null
+++ b/en/devices/architecture/hidl/memoryblock.md
@@ -0,0 +1,302 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# HIDL Memory Block
+
+The HIDL MemoryBlock is an abstract layer built on `hidl_memory`, `HIDL
+@1.0::IAllocator`, and `HIDL @1.0::IMapper`. It is designed for HIDL services
+that have multiple memory blocks to share a single memory heap.
+
+
+## Performance improvements
+
+Using MemoryBlock in applications can significantly reduce the number of
+`mmap`/`munmap` and user space segmentation faults, thus improving performance.
+For example:
+
+* Using per `hidl_memory` for each buffer allocation averages 238 us/1 allocation.
+* Using `MemoryBlock` and sharing a single `hidl_memory` averages 2.82 us/1 allocation.
+
+
+## Architecture
+
+The HIDL MemoryBlock architecture includes HIDL services with multiple memory
+blocks sharing a single memory heap:
+
+
+
+**Figure 1.** HIDL MemoryBlock architecture
+
+
+## Normal usage
+
+This section provides an example of using MemoryBlock by first declaring the HAL
+then implementing the HAL.
+
+
+### Declaring the HAL
+
+For the following example IFoo HAL:
+
+```
+import android.hidl.memory.block@1.0::MemoryBlock;
+
+interface IFoo {
+ getSome() generates(MemoryBlock block);
+ giveBack(MemoryBlock block);
+};
+```
+
+The `Android.bp` is as follows:
+
+```
+hidl_interface {
+ ...
+ srcs: [
+ "IFoo.hal",
+ ],
+ interfaces: [
+ "android.hidl.memory.block@1.0",
+ ...
+};
+```
+
+### Implementing the HAL
+
+To implement the example HAL:
+
+1. Get the `hidl_memory` (for details, refer to [HIDL C++](/devices/architecture/hidl-cpp/)).
+
+
+ ```
+ #include <android/hidl/allocator/1.0/IAllocator.h>
+
+ using ::android::hidl::allocator::V1_0::IAllocator;
+ using ::android::hardware::hidl_memory;
+ ...
+ sp<IAllocator> allocator = IAllocator::getService("ashmem");
+ allocator->allocate(2048, [&](bool success, const hidl_memory& mem)
+ {
+ if (!success) { /* error */ }
+ // you can now use the hidl_memory object 'mem' or pass it
+ }));
+ ```
+
+1. Make a `HidlMemoryDealer` with the acquired `hidl_memory`:
+
+ ```
+ #include <hidlmemory/HidlMemoryDealer.h>
+
+ using ::android::hardware::HidlMemoryDealer
+ /* The mem argument is acquired in the Step1, returned by the ashmemAllocator->allocate */
+ sp<HidlMemoryDealer> memory_dealer = HidlMemoryDealer::getInstance(mem);
+ ```
+
+1. Allocate `MemoryBlock`, which is a struct defined with HIDL.
+
+ Example `MemoryBlock`:
+
+ ```
+ struct MemoryBlock {
+ IMemoryToken token;
+ uint64_t size;
+ uint64_t offset;
+ };
+ ```
+
+ Example using the `MemoryDealer` to allocate a `MemoryBlock`:
+
+
+ ```
+ #include <android/hidl/memory/block/1.0/types.h>
+
+ using ::android::hidl::memory::block::V1_0::MemoryBlock;
+
+ Return<void> Foo::getSome(getSome_cb _hidl_cb) {
+ MemoryBlock block = memory_dealer->allocate(1024);
+ if(HidlMemoryDealer::isOk(block)){
+ _hidl_cb(block);
+ ...
+ ```
+
+1. Deallocate `MemoryBlock`:
+
+ ```
+ Return<void> Foo::giveBack(const MemoryBlock& block) {
+ memory_dealer->deallocate(block.offset);
+ ...
+ ```
+
+1. Manipulate the data:
+
+ ```
+ #include <hidlmemory/mapping.h>
+ #include <android/hidl/memory/1.0/IMemory.h>
+
+ using ::android::hidl::memory::V1_0::IMemory;
+
+ sp<IMemory> memory = mapMemory(block);
+ uint8_t* data =
+
+ static_cast<uint8_t*>(static_cast<void*>(memory->getPointer()));
+ ```
+
+1. Config `Android.bp`:
+
+ ```
+ shared_libs: [
+ "android.hidl.memory@1.0",
+
+ "android.hidl.memory.block@1.0"
+
+ "android.hidl.memory.token@1.0",
+ "libhidlbase",
+ "libhidlmemory",
+ ```
+
+1. Review the flow to determine if you need to `lockMemory`.
+
+ Normally, the MemoryBlock uses reference count to maintain the shared
+ `hidl_memory` which is `mmap()`-ed the first time one of its `MemoryBlock`s gets
+ mapped and is `munmap()`-ed when nothing refers to it. To keep the `hidl_memory`
+ always mapped, you can use `lockMemory`, a RAII style object that keeps the
+ corresponding `hidl_memory` mapped throughout the lock life cycle. Example:
+
+ ```
+ #include <hidlmemory/mapping.h>
+
+ sp<RefBase> lockMemory(const sp<IMemoryToken> key);
+ ```
+
+## Extended usage
+
+This section provides details about the extended usage of `MemoryBlock`.
+
+
+### Using reference count to manage Memoryblock
+
+In most situations, the most efficient way to use MemoryBlock is to explicitly
+allocate/deallocate. However, in complicated applications using reference count
+for garbage collection might be a better idea. To have reference count on
+MemoryBlock, you can bind MemoryBlock with a binder object, which helps to count
+the references and deallocate the MemoryBlock when the count decreases to zero.
+
+
+### Declaring the HAL
+
+When declaring the HAL, describe a HIDL struct that contains a MemoryBlock and a
+IBase:
+
+
+```
+import android.hidl.memory.block@1.0::MemoryBlock;
+
+struct MemoryBlockAllocation {
+ MemoryBlock block;
+ IBase refcnt;
+};
+```
+
+Use the `MemoryBlockAllocation` to replace `MemoryBlock` and remove the method
+to give back the `MemoryBlock`. It will be deallocated by reference counting
+with the `MemoryBlockAllocation`. Example:
+
+
+```
+interface IFoo {
+ allocateSome() generates(MemoryBlockAllocation allocation);
+};
+```
+
+### Implementing the HAL
+
+Example of the service side implementation of the HAL:
+
+
+```
+class MemoryBlockRefCnt: public virtual IBase {
+ MemoryBlockRefCnt(uint64_t offset, sp<MemoryDealer> dealer)
+ : mOffset(offset), mDealer(dealer) {}
+ ~MemoryBlockRefCnt() {
+ mDealer->deallocate(mOffset);
+ }
+ private:
+ uint64_t mOffset;
+ sp<MemoryDealer> mDealer;
+};
+
+Return<void> Foo::allocateSome(allocateSome_cb _hidl_cb) {
+ MemoryBlockAllocation allocation;
+ allocation.block = memory_dealer->allocate(1024);
+ if(HidlMemoryDealer::isOk(block)){
+ allocation.refcnt= new MemoryBlockRefCnt(...);
+ _hidl_cb(allocation);
+```
+
+
+Example of the client side implementation of the HAL:
+
+
+```
+ifoo->allocateSome([&](const MemoryBlockAllocation& allocation){
+ ...
+);
+```
+
+### Attaching/retrieving metadata
+
+Some applications need additional data to bind with the allocated `MemoryBlock`.
+You can append/retrieve metadata using two methods:
+
+
+* If the application accesses the metadata as often as the block itself,
+ append the metadata and pass them all in a struct. Example:
+
+ ```
+ import android.hidl.memory.block@1.0::MemoryBlock;
+
+ struct MemoryBlockWithMetaData{
+ MemoryBlock block;
+ MetaDataStruct metaData;
+ };
+ ```
+
+* If the application accesses the metadata much less frequently than the
+ block, it is more efficient to pass the metadata passively with an
+ interface. Example:
+
+ ```
+ import android.hidl.memory.block@1.0::MemoryBlock;
+
+ struct MemoryBlockWithMetaData{
+ MemoryBlock block;
+ IMetaData metaData;
+ };
+ ```
+
+ Next, bind the metadata with the MemoryBlock using the Memory Dealer. Example:
+
+ ```
+ MemoryBlockWithMetaData memory_block;
+ memory_block.block = dealer->allocate(size);
+ if(HidlMemoryDealer::isOk(block)){
+ memory_block.metaData = new MetaData(...);
+ ```
diff --git a/en/devices/architecture/images/abi_check_abidiff.png b/en/devices/architecture/images/abi_check_abidiff.png
new file mode 100644
index 0000000..85ea934
--- /dev/null
+++ b/en/devices/architecture/images/abi_check_abidiff.png
Binary files differ
diff --git a/en/devices/architecture/images/abi_check_lsdump.png b/en/devices/architecture/images/abi_check_lsdump.png
new file mode 100644
index 0000000..0a1db9d
--- /dev/null
+++ b/en/devices/architecture/images/abi_check_lsdump.png
Binary files differ
diff --git a/en/devices/architecture/images/abi_check_sdump.png b/en/devices/architecture/images/abi_check_sdump.png
new file mode 100644
index 0000000..1b97560
--- /dev/null
+++ b/en/devices/architecture/images/abi_check_sdump.png
Binary files differ
diff --git a/en/devices/architecture/images/android-diffs.png b/en/devices/architecture/images/android-diffs.png
index 601b998..6f533b0 100644
--- a/en/devices/architecture/images/android-diffs.png
+++ b/en/devices/architecture/images/android-diffs.png
Binary files differ
diff --git a/en/devices/architecture/images/hidl_memoryblock_arch.png b/en/devices/architecture/images/hidl_memoryblock_arch.png
new file mode 100644
index 0000000..8e99d0c
--- /dev/null
+++ b/en/devices/architecture/images/hidl_memoryblock_arch.png
Binary files differ
diff --git a/en/devices/architecture/images/kernel_lts_diff.png b/en/devices/architecture/images/kernel_lts_diff.png
index b75fc5d..354832c 100644
--- a/en/devices/architecture/images/kernel_lts_diff.png
+++ b/en/devices/architecture/images/kernel_lts_diff.png
Binary files differ
diff --git a/en/devices/architecture/images/treble_vndk_design.png b/en/devices/architecture/images/treble_vndk_design.png
index 205a97e..a4d9642 100644
--- a/en/devices/architecture/images/treble_vndk_design.png
+++ b/en/devices/architecture/images/treble_vndk_design.png
Binary files differ
diff --git a/en/devices/architecture/images/treble_vndk_linker_namespace1.png b/en/devices/architecture/images/treble_vndk_linker_namespace1.png
index 533fab1..a3e895d 100644
--- a/en/devices/architecture/images/treble_vndk_linker_namespace1.png
+++ b/en/devices/architecture/images/treble_vndk_linker_namespace1.png
Binary files differ
diff --git a/en/devices/architecture/images/treble_vndk_linker_namespace2.png b/en/devices/architecture/images/treble_vndk_linker_namespace2.png
index 520ceb8..5dff03d 100644
--- a/en/devices/architecture/images/treble_vndk_linker_namespace2.png
+++ b/en/devices/architecture/images/treble_vndk_linker_namespace2.png
Binary files differ
diff --git a/en/devices/architecture/images/treble_vndk_linker_namespace3.png b/en/devices/architecture/images/treble_vndk_linker_namespace3.png
new file mode 100644
index 0000000..6679307
--- /dev/null
+++ b/en/devices/architecture/images/treble_vndk_linker_namespace3.png
Binary files differ
diff --git a/en/devices/architecture/images/vndk_snapshot_arch.png b/en/devices/architecture/images/vndk_snapshot_arch.png
new file mode 100644
index 0000000..97e0e22
--- /dev/null
+++ b/en/devices/architecture/images/vndk_snapshot_arch.png
Binary files differ
diff --git a/en/devices/architecture/images/vndk_snapshot_directory.png b/en/devices/architecture/images/vndk_snapshot_directory.png
new file mode 100644
index 0000000..b7c9f7a
--- /dev/null
+++ b/en/devices/architecture/images/vndk_snapshot_directory.png
Binary files differ
diff --git a/en/devices/architecture/images/vndk_snapshot_prebuilt.png b/en/devices/architecture/images/vndk_snapshot_prebuilt.png
new file mode 100644
index 0000000..e73ab23
--- /dev/null
+++ b/en/devices/architecture/images/vndk_snapshot_prebuilt.png
Binary files differ
diff --git a/en/devices/architecture/images/vndk_snapshot_system_only.png b/en/devices/architecture/images/vndk_snapshot_system_only.png
new file mode 100644
index 0000000..7fdbb31
--- /dev/null
+++ b/en/devices/architecture/images/vndk_snapshot_system_only.png
Binary files differ
diff --git a/en/devices/architecture/kernel/android-common.html b/en/devices/architecture/kernel/android-common.html
index 1317557..7348f6f 100644
--- a/en/devices/architecture/kernel/android-common.html
+++ b/en/devices/architecture/kernel/android-common.html
@@ -45,29 +45,29 @@
(shown below).</p>
<p><img src="../images/android-diffs.png"></p>
<p class="img-caption"><strong>Figure 1.</strong> List of Android common
-kernels.</p>
+kernels</p>
<h3 id="differences-lts">Differences from LTS</h3>
-<p>When compared to LTS (4.4.40), the Android common kernel has 679 changes,
-56172 insertions, and 3340 deletions (as of February 2017).</p>
+<p>When compared to LTS (4.14.0), the Android common kernel has 355 changes,
+32266 insertions, and 1546 deletions (as of February 2018).</p>
<p><img src="../images/kernel_lts_diff.png"></p>
<p class="img-caption"><strong>Figure 2.</strong> Android-specific code over
-time.</p>
+time</p>
<p>The largest features include:</p>
<ul>
-<li>13.8% SoC (arch/arm64, arch/x86)</li>
-<li>9.2% USB (drivers/usb)</li>
-<li>8.2% Energy Aware Scheduling (kernel/sched)</li>
-<li>8.2% Atomic Display Framework (drivers/video/adf)</li>
-<li>8.0% networking (net/netfilter)</li>
-<li>6.2% sdcardfs (fs/sdcardfs)</li>
-<li>5.0% Verity (drivers/md)</li>
-<li>3.7% Input (drivers/input/misc)</li>
-<li>3.3% FIQ Debugger (drivers/staging/android/fiq_debugger)</li>
-<li>2.4% Cpufreq (drivers/cpufreq)</li>
-<li>2.2% Goldfish Emulator (drivers/platform/goldfish)</li>
+<li>19.8% Energy Aware Scheduling (kernel/sched)</li>
+<li>13.8% Networking (net/netfilter)</li>
+<li>13.5% Sdcardfs (fs/sdcardfs)</li>
+<li>9.4% USB (drivers/usb)</li>
+<li>7.2% SoC (arch/arm64, arch/x86)</li>
+<li>6.2% f2fs (fs/f2fs -- backports from upstream)</li>
+<li>6.1% Input (drivers/input/misc)</li>
+<li>5.4% FIQ Debugger (drivers/staging/android/fiq_debugger)</li>
+<li>3.6% Goldfish Emulator (drivers/platform/goldfish)</li>
+<li>3.4% Verity (drivers/md)</li>
+<li>11.6% Other</li>
</ul>
<h2 id="requirements">Requirements</h2>
diff --git a/en/devices/architecture/kernel/config.html b/en/devices/architecture/kernel/config.html
index afc36f8..49ae7e1 100644
--- a/en/devices/architecture/kernel/config.html
+++ b/en/devices/architecture/kernel/config.html
@@ -41,7 +41,7 @@
</ul>
<p>These configuration files are located in the
-<code><a href="https://android.googlesource.com/kernel/configs/">kernel/configs</a></code>
+<code><a href="https://android.googlesource.com/kernel/configs/" class="external">kernel/configs</a></code>
repo. Use the set of configuration files that corresponds to the version of the
kernel you are using.</p>
@@ -87,45 +87,42 @@
<p>Ensure that <code>CONFIG_SECCOMP_FILTER=y</code> is enabled in the Kconfig
(verified as of the Android 5.0 CTS), then cherry-pick the following changes
-from the AOSP kernel/common:android-3.10 repository: <a href="https://android.
-googlesource.com/kernel/common/+log/9499cd23f9d05ba159
-fac6d55dc35a7f49f9ce76..a9ba4285aa5722a3b4d84888e78ba8adc0046b28">9499cd23f9d05ba159fac6d55dc35a7f49f9ce76..a9ba4285aa5722a3b4d84888e78ba8adc0046b28</a>
+from the AOSP kernel/common:android-3.10 repository:
+<a href="https://android.googlesource.com/kernel/common/+log/9499cd23f9d05ba159
+fac6d55dc35a7f49f9ce76..a9ba4285aa5722a3b4d84888e78ba8adc0046b28" class="external">9499cd23f9d05ba159fac6d55dc35a7f49f9ce76..a9ba4285aa5722a3b4d84888e78ba8adc0046b28</a>
</p>
<ul>
-<li><a href="https://android.googlesource.com/kernel/common/+/a03a2426ea9f1d9dada33cf4a824f63e8f916c9d">a03
+<li><a href="https://android.googlesource.com/kernel/common/+/a03a2426ea9f1d9dada33cf4a824f63e8f916c9d" class="external">a03
a242 arch: Introduce smp_load_acquire(), smp_store_release()</a> by Peter
Zijlstra</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/987a0f1102321853565c4bfecde6a5a58ac6db11">987a0f
-1 introduce for_each_thread() to replace the buggy while_each_thread()</a> by
- Oleg Nesterov</li>
- <li><a href="https://android.googlesource.com/kernel/common/+/2a30a4386e4a7e1283157c4cf4cfcc0306b22ac8">2a30a43
+<li><a href="https://android.googlesource.com/kernel/common/+/987a0f1102321853565c4bfecde6a5a58ac6db11" class="external">987a0f1
+introduce for_each_thread() to replace the buggy while_each_thread()</a> by
+Oleg Nesterov</li>
+<li><a href="https://android.googlesource.com/kernel/common/+/2a30a4386e4a7e1283157c4cf4cfcc0306b22ac8" class="external">2a30a43
seccomp: create internal mode-setting function</a> by Kees Cook</li>
-<li><a href="https://android.googlesource.com/kernel/common/+
-/b8a9cff6dbe9cfddbb4d17e2dea496e523544687">b8a9cff
+<li><a href="https://android.googlesource.com/kernel/common/+/b8a9cff6dbe9cfddbb4d17e2dea496e523544687" class="external">b8a9cff
seccomp: extract check/assign mode helpers</a> by Kees Cook</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/8908dde5a7fdca974374b0dbe6dfb10f69df7216">8908dde
+<li><a href="https://android.googlesource.com/kernel/common/+/8908dde5a7fdca974374b0dbe6dfb10f69df7216" class="external">8908dde
seccomp: split mode setting routines</a> by Kees Cook</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/e985fd474debedb269fba27006eda50d0b6f07ef">e985fd4 seccomp: add
-"seccomp" syscall</a> by Kees Cook</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/9d0ff
-694bc22fb458acb763811a677696c60725b">9d0ff69
+<li><a href="https://android.googlesource.com/kernel/common/+/e985fd474debedb269fba27006eda50d0b6f07ef" class="external">e985fd4
+seccomp: add "seccomp" syscall</a> by Kees Cook</li>
+<li><a href="https://android.googlesource.com/kernel/common/+/9d0ff694bc22fb458acb763811a677696c60725b" class="external">9d0ff69
sched: move no_new_privs into new atomic flags</a> by Kees Cook</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/b6a12bf4dd762236c7f637b19cfe10a268304b9b">b6a12bf
+<li><a href="https://android.googlesource.com/kernel/common/+/b6a12bf4dd762236c7f637b19cfe10a268304b9b" class="external">b6a12bf
seccomp: split filter prep from check and apply</a> by Kees Cook</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/61b6b882a0abfeb627d25a069cfa1d232b84c8eb">61b6b88
+<li><a href="https://android.googlesource.com/kernel/common/+/61b6b882a0abfeb627d25a069cfa1d232b84c8eb" class="external">61b6b88
seccomp: introduce writer locking</a> by Kees Cook</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/c852ef778224ecf5fe995d74ad96087038778bca">c852ef7
+<li><a href="https://android.googlesource.com/kernel/common/+/c852ef778224ecf5fe995d74ad96087038778bca" class="external">c852ef7
seccomp: allow mode setting across threads</a> by Kees Cook</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/f14a5db2398afed8f416d244e6da6b23940997c6">f14a5db
+<li><a href="https://android.googlesource.com/kernel/common/+/f14a5db2398afed8f416d244e6da6b23940997c6" class="external">f14a5db
seccomp: implement SECCOMP_FILTER_FLAG_TSYNC</a> by Kees Cook</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/9ac860041db
-860a59bfd6ac82b31d6b6f76ebb52">9ac8600
+<li><a href="https://android.googlesource.com/kernel/common/+/9ac860041db860a59bfd6ac82b31d6b6f76ebb52" class="external">9ac8600
seccomp: Replace BUG(!spin_is_locked()) with assert_spin_lock</a> by Guenter
Roeck</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/900e9fd0d5d15c596cacfb89ce007c933cea6e1c">900e9fd
+<li><a href="https://android.googlesource.com/kernel/common/+/900e9fd0d5d15c596cacfb89ce007c933cea6e1c" class="external">900e9fd
seccomp: fix syscall numbers for x86 and x86_64</a> by Lee Campbell</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/a9ba4285aa5722a3b4d84888e78ba8adc0046b28">a9ba428
+<li><a href="https://android.googlesource.com/kernel/common/+/a9ba4285aa5722a3b4d84888e78ba8adc0046b28" class="external">a9ba428
ARM: add seccomp syscall</a> by Kees Cook</li>
</ul>
@@ -134,56 +131,54 @@
(verified as of the Android 5.0 CTS), then cherry-pick the following changes
from the AOSP kernel/common:android-3.10 repository:</p>
<ul>
-<li><a href="https://android.googlesource.com/kernel/common/+/cfc7e99e9e3900056028a7d90072e9ea0d886f8d">cfc7e99e9
+<li><a href="https://android.googlesource.com/kernel/common/+/cfc7e99e9e3900056028a7d90072e9ea0d886f8d" class="external">cfc7e99e9
arm64: Add __NR_* definitions for compat syscalls</a> by JP Abgrall</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/bf11863d45eb3dac0d0cf1f818ded11ade6e28d3">bf11863
+<li><a href="https://android.googlesource.com/kernel/common/+/bf11863d45eb3dac0d0cf1f818ded11ade6e28d3" class="external">bf11863
arm64: Add audit support</a> by AKASHI Takahiro</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/3
-e21c0bb663a23436e0eb3f61860d4fedc233bab">3e21c0b
+<li><a href="https://android.googlesource.com/kernel/common/+/3e21c0bb663a23436e0eb3f61860d4fedc233bab" class="external">3e21c0b
arm64: audit: Add audit hook in syscall_trace_enter/exit()</a> by JP Abgrall</li>
-<li><a href="https://android.googlesource.com/kernel
-/common/+/9499cd23f9d05ba159fac6d55dc35a7f49f9ce76">9499cd2
+<li><a href="https://android.googlesource.com/kernel/common/+/9499cd23f9d05ba159fac6d55dc35a7f49f9ce76" class="external">9499cd2
syscall_get_arch: remove useless function arguments</a> by Eric Paris</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/2a30a4386e4a7e1283157c4cf4cfcc0306b22ac8">2a30a43
+<li><a href="https://android.googlesource.com/kernel/common/+/2a30a4386e4a7e1283157c4cf4cfcc0306b22ac8" class="external">2a30a43
seccomp: create internal mode-setting function</a> by Kees Cook</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/b8a9cff6dbe9cfddbb4d17e2dea496e523544687">b8a9
+<li><a href="https://android.googlesource.com/kernel/common/+/b8a9cff6dbe9cfddbb4d17e2dea496e523544687" class="external">b8a9
cff seccomp: extract check/assign mode helpers</a> by Kees Cook</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/8908dde5a7fdca974374b0dbe6dfb10f69df7216">8908dde
+<li><a href="https://android.googlesource.com/kernel/common/+/8908dde5a7fdca974374b0dbe6dfb10f69df7216" class="external">8908dde
seccomp: split mode setting routines</a> by Kees Cook</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/e985fd474debedb269fba27006eda50d0b6f07ef">e985fd4
+<li><a href="https://android.googlesource.com/kernel/common/+/e985fd474debedb269fba27006eda50d0b6f07ef" class="external">e985fd4
seccomp: add "seccomp" syscall</a> by Kees Cook</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/9d0ff694bc22fb458acb763811a677696c60725b">9d0ff69
+<li><a href="https://android.googlesource.com/kernel/common/+/9d0ff694bc22fb458acb763811a677696c60725b" class="external">9d0ff69
sched: move no_new_privs into new atomic flags</a> by Kees Cook</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/b6a12bf4dd762236c7f637b19cfe10a268304b9b">b6a12bf
+<li><a href="https://android.googlesource.com/kernel/common/+/b6a12bf4dd762236c7f637b19cfe10a268304b9b" class="external">b6a12bf
seccomp: split filter prep from check and apply</a> by Kees Cook</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/61b6b882a0abfeb627d25a069cfa1d232b84c8eb">61b6b88
+<li><a href="https://android.googlesource.com/kernel/common/+/61b6b882a0abfeb627d25a069cfa1d232b84c8eb" class="external">61b6b88
seccomp: introduce writer locking</a> by Kees Cook</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/c852ef778224ecf5fe995d74ad96087038778bca">c852ef7
+<li><a href="https://android.googlesource.com/kernel/common/+/c852ef778224ecf5fe995d74ad96087038778bca" class="external">c852ef7
seccomp: allow mode setting across threads</a> by Kees Cook</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/f14a5db2398afed8f416d244e6da6b23940997c6">f14a5db
+<li><a href="https://android.googlesource.com/kernel/common/+/f14a5db2398afed8f416d244e6da6b23940997c6" class="external">f14a5db
seccomp: implement SECCOMP_FILTER_FLAG_TSYNC</a> by Kees Cook</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/9ac860041db860a59bfd6ac82b31d6b6f76ebb52">9ac8600
+<li><a href="https://android.googlesource.com/kernel/common/+/9ac860041db860a59bfd6ac82b31d6b6f76ebb52" class="external">9ac8600
seccomp: Replace BUG(!spin_is_locked()) with assert_spin_lock</a> by Guenter
Roeck</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/900e9fd0d5d15c596cacfb89ce007c933cea6e1c">900e9fd
+<li><a href="https://android.googlesource.com/kernel/common/+/900e9fd0d5d15c596cacfb89ce007c933cea6e1c" class="external">900e9fd
seccomp: fix syscall numbers for x86 and x86_64</a> by Lee Campbell</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/a9ba4285aa5722a3b4d84888e78ba8adc0046b28">a9ba428
+<li><a href="https://android.googlesource.com/kernel/common/+/a9ba4285aa5722a3b4d84888e78ba8adc0046b28" class="external">a9ba428
ARM: add seccomp syscall</a> by Kees Cook</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/41900903483eb96602dd72e719a798c208118aad">4190090
+<li><a href="https://android.googlesource.com/kernel/common/+/41900903483eb96602dd72e719a798c208118aad" class="external">4190090
ARM: 8087/1: ptrace: reload syscall number after secure_computing() check</a> by
Will Deacon</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/abbfed9ed1a78701ef3db74f5287958feb897035">abbfed9
+<li><a href="https://android.googlesource.com/kernel/common/+/abbfed9ed1a78701ef3db74f5287958feb897035" class="external">abbfed9
arm64: ptrace: add PTRACE_SET_SYSCALL</a> by AKASHI Takahiro</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/feb28436457d33fef9f264635291432df4b74122">feb2843
+<li><a href="https://android.googlesource.com/kernel/common/+/feb28436457d33fef9f264635291432df4b74122" class="external">feb2843
arm64: ptrace: allow tracer to skip a system call</a> by AKASHI Takahiro</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/dab10731da65a0deba46402ca9fadf6974676cc8">dab1073
+<li><a href="https://android.googlesource.com/kernel/common/+/dab10731da65a0deba46402ca9fadf6974676cc8" class="external">dab1073
asm-generic: add generic seccomp.h for secure computing mode 1</a> by AKASHI
Takahiro</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/4f12b53f28a751406a27ef7501a22f9e32a9c30b">4f1
+<li><a href="https://android.googlesource.com/kernel/common/+/4f12b53f28a751406a27ef7501a22f9e32a9c30b" class="external">4f1
2b53 add seccomp syscall for compat task</a> by AKASHI Takahiro</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/77227239d20ac6381fb1aee7b7cc902f0d14cd85">7722723
+<li><a href="https://android.googlesource.com/kernel/common/+/77227239d20ac6381fb1aee7b7cc902f0d14cd85" class="external">7722723
arm64: add SIGSYS siginfo for compat task</a> by AKASHI Takahiro</li>
-<li><a href="https://android.googlesource.com/kernel/common/+/210957c2bb3b4d111963bb296e2c42beb8721929">210957c
+<li><a href="https://android.googlesource.com/kernel/common/+/210957c2bb3b4d111963bb296e2c42beb8721929" class="external">210957c
arm64: add seccomp support</a> by AKASHI Takahiro</li>
</ul>
diff --git a/en/devices/architecture/kernel/modular-kernels.html b/en/devices/architecture/kernel/modular-kernels.html
index fd1d870..c314a95 100644
--- a/en/devices/architecture/kernel/modular-kernels.html
+++ b/en/devices/architecture/kernel/modular-kernels.html
@@ -4,6 +4,7 @@
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
+ {% include "_versions.html" %}
<body>
<!--
Copyright 2017 The Android Open Source Project
@@ -21,7 +22,7 @@
limitations under the License.
-->
-<p>In Android 8.0, the device kernel splits into System-on-Chip (SoC), device,
+<p>In Android 8.0, the device kernel split into System-on-Chip (SoC), device,
and board-specific deliverables. This sets up the kernel and Android such that
Original Device Manufacturers (ODMs) and Original Equipment Manufacturers (OEMs)
can work in isolated board–specific trees for board–specific features, drivers,
@@ -32,8 +33,8 @@
<ul>
<li>Platform support for independent SoC and OEM/ODM kernel development. Android
-O recommends all board–specific code to be built and shipped as kernel modules
-in devices. As a result:
+{{ androidPVersionNumber }} recommends all board–specific code to be built and
+shipped as kernel modules in devices. As a result:
<ul>
<li>All platforms should support either
<a href="https://www.devicetree.org/" class="external">Device Tree</a> or
@@ -55,7 +56,7 @@
</ul>
<h2 id="loadable-kernel-modules">Loadable kernel modules</h2>
-<p>All SoC kernels should support loadable kernel modules. As a starting point,
+<p>All SoC kernels must support loadable kernel modules. As a starting point,
the following kernel-config options (or their kernel-version equivalent) have
been added to
<a href="https://android.googlesource.com/kernel/common/+/android-4.4-o/android/configs/android-base.cfg" class="external">android-base.cfg</a>
@@ -67,8 +68,7 @@
CONFIG_MODVERSIONS=y
</pre>
-<p>All kernel modules are subject to module load/unload testing to ensure the
-correctness of the driver/module.</p>
+<p>Kernel modules should support unloading and reloading whenever possible.</p>
<aside class="note"><strong>Note:</strong>
<code>CONFIG_MODULE_SRCVERSION_ALL</code> is optional and will not be tested
@@ -93,9 +93,10 @@
<h3 id="file-locations">File locations</h3>
<p>While Android 7.x and earlier versions do not mandate against kernel modules
(and include support for <code>insmod</code> and <code>rmmod</code>), Android
-8.0 recommends the use of kernel modules in the ecosystem. The following table
-shows potential board–specific peripheral support required across three Android
-boot modes:</p>
+8.x and higher recommends the use of kernel modules in the ecosystem. The
+following table shows potential board–specific peripheral support required
+across three Android boot modes:</p>
+
<table>
<tr>
<th>Boot Mode</th>
@@ -154,7 +155,7 @@
<ul>
<li>All kernels should have built-in support for booting and mounting partitions.
</li>
-<li>Kernel modules should be loaded from a read-only partition.</li>
+<li>Kernel modules must be loaded from a read-only partition.</li>
<li>For devices required to have verified boot, kernel modules should be loaded
from verified partitions.</li>
<li>Kernel modules should not be located in <code>/system</code>.</li>
@@ -178,8 +179,8 @@
</ul>
<p>In Android 7.x and earlier, <code>/vendor</code> and <code>/odm</code>
-partitions are <strong>not</strong> mounted early. In Android 8.0, to make
-module loading from these partitions possible, provisions have been made to
+partitions are <strong>not</strong> mounted early. In Android 8.x and higher, to
+make module loading from these partitions possible, provisions have been made to
mount partitions early for both
<a href="/devices/tech/ota/ab_updates">non-A/B and A/B devices</a>. This also
ensures the partitions are mounted in both Android and
@@ -279,11 +280,11 @@
loading of kernel modules as soon as possible after kernel boot).</p>
<aside class="note"><strong>Note:</strong> For details on SELinux in Android
-8.0, see <a href="/security/selinux/images/SELinux_Treble.pdf">SELinux for
+8.x, see <a href="/security/selinux/images/SELinux_Treble.pdf">SELinux for
Android 8.0</a>.</aside>
<p>Android must have access to the filesystem(s) on which the modules reside. To
-enable, Android 8.0 supports mounting <code>/system</code>,
+enable, Android 8.x and higher supports mounting <code>/system</code>,
<code>/vendor</code>, or <code>/odm</code> as early as <code>init</code>'s first
stage (i.e before selinux is initialized). Device makers can use
<a href="/devices/architecture/dto/index.html">device tree overlays</a> to
@@ -340,9 +341,9 @@
<h3 id="early-mounting-device-tree-vboot-1-0">Early mounting device tree, VBoot
1.0</h3>
-<p>In Android 8.0, <code>init</code> parses the device tree and creates
-<code>fstab</code> entries to mount the partition early during its first stage.
-An fstab entry takes the form:</p>
+<p>In Android 8.x and higher, <code>init</code> parses the device tree and
+creates <code>fstab</code> entries to mount the partition early during its first
+stage. An <code>fstab</code> entry takes the form:</p>
<pre class="prettyprint">src mnt_point type mnt_flags fs_mgr_flags</pre>
@@ -577,10 +578,16 @@
tree patching in the bootloader with the help of
<code>libfdt</code>/<code>libufdt</code>.</p>
-<p>In Android 7.x and earlier, Android did not require device tree support and
-did not provide recommendations regarding how vendors pass DT blobs to the
-kernel or where they store them. Android 8.0 recommends such support to keep the
-board–specific and SoC-only parts of the kernel separate.</p>
+<p>Support for DTOs in Android varies by Android release:</p>
+<ul>
+ <li>Android 7.x and earlier did not require device tree support and did not
+ provide recommendations regarding how vendors pass DT blobs to the kernel or
+ where they store them.</li>
+ <li>Android 8.x recommended such support to keep the board–specific and
+ SoC-only parts of the kernel separate.</li>
+ <li>Android {{ androidPVersionNumber }} requires a DTBO partition to be
+ present and at least one DTO to be applied.</li>
+</ul>
<h3 id="partitioning-requirements">Partitioning requirements</h3>
<p>Most Android devices today append the DT blob to the kernel at build time,
@@ -629,10 +636,11 @@
<a href="/devices/architecture/dto/index.html">Device Tree Overlays</a>.</p>
<h2 id="core-kernel-requirements">Core kernel requirements</h2>
-<p>Android 8.0 mandates a minimum kernel version and kernel configuration and
-checks them both in VTS as well as during an OTA. Android device kernels must
-enable the kernel <code>.config</code> support along with the option to read the
-kernel configuration at runtime through <code>procfs</code>.</p>
+<p>As of Android 8.0, Android mandates a minimum kernel version and kernel
+configuration and checks them both in VTS as well as during an OTA. Android
+device kernels must enable the kernel <code>.config</code> support along with
+the option to read the kernel configuration at runtime through
+<code>procfs</code>.</p>
<h3 id="kernel-config-support">Kernel .config support</h3>
<p>All device kernels must enable the entirety of
@@ -646,18 +654,29 @@
</pre>
<h3 id="kernel-version">Kernel version</h3>
-<p>Kernel version requirements:</p>
+<p>For Android {{ androidPVersionNumber }}, the minimum LTS kernel version
+requirements are 4.4.107, 4.9.84, and 4.14.42.</p>
+
<ul>
-<li>All SoCs productized in 2017 must launch with kernel 4.4 or newer.</li>
-<li>All other SoCs launching new Android devices running Android 8.0 must use
-kernel 3.18 or newer.</li>
-<li>Regardless of launch date, all SoCs with device launches on Android 8.0
-remain subject to kernel changes required to enable Treble.</li>
-<li>Older Android devices released prior to Android 8.0 but that will be
-upgraded to Android 8.0 can continue to use their original base kernel version
-if desired.</li>
+<li>All SoCs productized in 2018 must launch with kernel 4.9.84 or newer.</li>
+<li>All other SoCs launching new Android devices running Android 8.x must use
+kernel 3.18 or newer. All other SoCs launching new Android devices running
+Android {{ androidPVersionNumber }} must use kernel 4.4.107 or newer.</li>
+<li>Device kernels based on 4.14 must include the 4.14.42 or later LTS release.
+</li>
+<li>Regardless of launch date, all SoCs with device launches on Android 8.x
+and higher remain subject to the kernel changes required to enable Treble.</li>
+<li>Older Android devices that will be upgraded to Android 8.x or
+{{ androidPVersionNumber }} can continue to use their original base kernel
+version if desired.</li>
</ul>
+<p>For details on LTS kernels, refer to
+<a href="/devices/architecture/kernel/releases#long-term-stable-kernels">Long-term
+stable kernels</a> and
+<a href="https://source.android.com/devices/architecture/kernel/android-common">Android
+Common Kernels</a></p>
+
<h3 id="device-tree-support">Device tree support</h3>
<p>Device tree support in the kernel must be enabled and bootloaders must pass
the hardware description in the form of device tree to the kernel (unless the
@@ -686,12 +705,11 @@
<code>debugfs</code>. It may be enabled, but VTS testing may be done with
<code>debugfs</code> unmounted.</p>
-<h2 id="beyond-android-o">Beyond Android 8.0</h2>
-<p>Android 8.0 recommends any board–specific kernel functionality to be in the
-form of loadable kernel modules and device–tree overlays. The rest of the kernel
-is treated monolithically with respect to Android (whether or not is it is
-actually a monolithic kernel, or parts of it are compiled as kernel modules).
-</p>
+<h2 id="beyond-android-o">Future Android versions</h2>
+<p>The current Android release recommends that all board–specific code is built
+and shipped as kernel modules in devices. The rest of the kernel is treated
+monolithically with respect to Android (whether or not is it is actually a
+monolithic kernel, or parts of it are compiled as kernel modules).</p>
<p>This monolithic kernel is an SoC kernel that can boot on the SoC vendor's
reference hardware but nothing beyond that. Today, SoC kernels are treated
@@ -706,7 +724,7 @@
fragmented over time, across Android releases, and across ODMs.</p>
<img src="../images/treble_kernel_current.png">
-<figcaption><strong>Figure 1.</strong> Device kernel replication.</figcaption>
+<figcaption><strong>Figure 1.</strong> Device kernel replication</figcaption>
<p>Figure 1 shows the following:</p>
<ol>
@@ -723,14 +741,14 @@
unified–per–SoC–kernel scenario:</p>
<img src="../images/treble_kernel_treble.png">
-<figcaption><strong>Figure 2.</strong> Android 8.0 and higher device
-kernels.</figcaption>
+<figcaption><strong>Figure 2.</strong> Android 8.x and higher device
+kernels</figcaption>
<p>This is intended to solve the problem of fragmented kernel repos by
recommending and working with device manufacturers to stay up to date with the
-common SoC kernel. Android 8.0 provides all possible options to ODMs to help
-them avoid maintaining their own SoC kernels and instead rely on the common SoC
-kernel for LTS upgrades/bug fixes/security patches/etc.</p>
+common SoC kernel. Android 8.x and higher provides all possible options to ODMs
+to help them avoid maintaining their own SoC kernels and instead rely on the
+common SoC kernel for LTS upgrades/bug fixes/security patches/etc.</p>
<p>As a start, we want to facilitate all ODMs/vendors using a single kernel
source for an SoC. In the future, we want to move towards a single binary
diff --git a/en/devices/architecture/kernel/releases.html b/en/devices/architecture/kernel/releases.html
index 612922d..1d06b82 100644
--- a/en/devices/architecture/kernel/releases.html
+++ b/en/devices/architecture/kernel/releases.html
@@ -57,7 +57,7 @@
LTS kernel has been selected once a year and kernel community maintains that
kernel for a minimum of 2 years.
</p>
-<p>At the time of this writing, the LTS kernels are the 4.4.y and 4.9.y
+<p>At the time of this writing, the LTS kernels are the 4.4.y, 4.9.y, and 4.14.y
releases, and a new kernel is released weekly. Due to the needs of some users
and distributions, a few additional older kernels are maintained by kernel
developers at a slower release cycle. Information about all long-term stable
diff --git a/en/devices/architecture/kernel/reqs-interfaces.html b/en/devices/architecture/kernel/reqs-interfaces.html
index 82349f7..53fbf65 100644
--- a/en/devices/architecture/kernel/reqs-interfaces.html
+++ b/en/devices/architecture/kernel/reqs-interfaces.html
@@ -4,6 +4,7 @@
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
+ {% include "_versions.html" %}
<body>
<!--
Copyright 2017 The Android Open Source Project
@@ -28,46 +29,8 @@
Android kernel interfaces.</p>
<h2 id="system-calls">System calls</h2>
-<p>System calls are expected to provide the same signatures and semantics as in
-the upstream Linux kernel.</p>
-
-<p>ARM64 system calls required by bionic per
-<code>bionic/libc/SYSCALLS.txt</code>:</p>
-
-<table>
-<tr>
-<td class="devsite-click-to-copy">accept4, acct, adjtimex, bind, brk, capget, capset, chdir, chroot, clock_adjtime, clock_getres, clock_gettime, clock_nanosleep, clock_settime, close, connect, delete_module, dup3, dup, epoll_create1, epoll_ctl, epoll_pwait, eventfd2, execve, exit, exit_group, faccessat, fadvise64, fallocate, fchdir, fchmodat, fchmod, fchownat, fchown, fcntl, fdatasync, fgetxattr, flistxattr, flock, fremovexattr, fsetxattr, fstat, newfstatat, fstatfs, fsync, ftruncate, getcpu, getcwd, getdents64, getegid, geteuid, getgid, getgroups, getitimer, getpeername, getpgid, getpid, getppid, getpriority, getresgid, getresuid, getrlimit, getrusage, getsid, getsockname, getsockopt, gettimeofday, getuid, getxattr, init_module, inotify_add_watch, inotify_init1, inotify_rm_watch, ioctl, kill, syslog, lgetxattr, linkat, listen, listxattr, llistxattr, lremovexattr, lseek, lsetxattr, madvise, mincore, mkdirat, mknodat, mlockall, mlock, mmap, mount, mprotect, mremap, msync, munlockall, munlock, munmap, nanosleep, openat, personality, pipe2, ppoll, prctl, pread64, preadv, prlimit64, process_vm_readv, process_vm_writev, pselect6, ptrace, pwrite64, pwritev, quotactl, readahead, readlinkat, read, readv, reboot, recvfrom, recvmmsg, recvmsg, removexattr, renameat, rt_sigaction, rt_sigpending, rt_sigprocmask, rt_sigqueueinfo, rt_sigsuspend, rt_sigtimedwait, sched_getaffinity, sched_getparam, sched_get_priority_max, sched_get_priority_min, sched_getscheduler, sched_rr_get_interval, sched_setaffinity, sched_setparam, sched_setscheduler, sched_yield, sendfile, sendmmsg, sendmsg, sendto, setdomainname, setfsgid, setfsuid, setgid, setgroups, sethostname, setitimer, setns, setpgid, setpriority, setregid, setresgid, setresuid, setreuid, setrlimit, setsid, setsockopt, set_tid_address, settimeofday, setuid, setxattr, shutdown, sigaltstack, signalfd4, socketpair, socket, splice, statfs, swapoff, swapon, symlinkat, sync_file_range, sync, sysinfo, tee, tgkill, timer_create, timer_delete, timerfd_create, timerfd_gettime, timerfd_settime, timer_getoverrun, timer_gettime, timer_settime, times, truncate, umask, umount2, uname, unlinkat, unshare, utimensat, vmsplice, wait4, waitid, write, writev</td>
-</tr></table>
-
-<p>ARM32 system calls required by bionic per
-<code>bionic/libc/SYSCALLS.txt</code>:</p>
-
-<table>
-<tr>
-<td class="devsite-click-to-copy">accept4, acct, adjtimex, arm_fadvise64_64, bind, brk, cacheflush, capget, capset, chdir, chroot, clock_adjtime, clock_getres, clock_gettime, clock_nanosleep, clock_settime, close, connect, delete_module, dup3, dup, epoll_create1, epoll_ctl, epoll_pwait, eventfd2, execve, exit, exit_group, faccessat, fallocate, fchdir, fchmodat, fchmod, fchownat, fchown32, fcntl64, fdatasync, fgetxattr, flistxattr, flock, fremovexattr, fsetxattr, fstat64, fstatat64, fstatfs64, fsync, ftruncate64, getcpu, getcwd, getdents64, getegid32, geteuid32, getgid32, getgroups32, getitimer, getpeername, getpgid, getpid, getppid, getpriority, getresgid32, getresuid32, ugetrlimit, getrusage, getsid, getsockname, getsockopt, gettimeofday, getuid32, getxattr, init_module, inotify_add_watch, inotify_init1, inotify_rm_watch, ioctl, kill, syslog, lgetxattr, linkat, listen, listxattr, llistxattr, _llseek, lremovexattr, lseek, lsetxattr, madvise, mincore, mkdirat, mknodat, mlockall, mlock, mmap2, mount, mprotect, mremap, msync, munlockall, munlock, munmap, nanosleep, openat, personality, pipe2, ppoll, prctl, pread64, preadv, prlimit64, process_vm_readv, process_vm_writev, pselect6, ptrace, pwrite64, pwritev, quotactl, readahead, readlinkat, read, readv, reboot, recvfrom, recvmmsg, recvmsg, removexattr, renameat, rt_sigaction, rt_sigpending, rt_sigprocmask, rt_sigqueueinfo, rt_sigsuspend, rt_sigtimedwait, sched_getaffinity, sched_getparam, sched_get_priority_max, sched_get_priority_min, sched_getscheduler, sched_rr_get_interval, sched_setaffinity, sched_setparam, sched_setscheduler, sched_yield, sendfile64, sendfile, sendmmsg, sendmsg, sendto, setdomainname, setfsgid, setfsuid, setgid32, setgroups32, sethostname, setitimer, setns, setpgid, setpriority, setregid32, setresgid32, setresuid32, setreuid32, setrlimit, setsid, setsockopt, set_tid_address, settimeofday, set_tls, setuid32, setxattr, shutdown, sigaction, sigaltstack, signalfd4, socketpair, socket, splice, statfs64, swapoff, swapon, symlinkat, sync_file_range2, sync, sysinfo, tee, tgkill, timer_create, timer_delete, timerfd_create, timerfd_gettime, timerfd_settime, timer_getoverrun, timer_gettime, timer_settime, times, truncate64, truncate, umask, umount2, uname, unlinkat, unshare, utimensat, vmsplice, wait4, waitid, write, writev</td>
-</tr></table>
-
-<p>The system calls listed below are made by bypassing bionic:</p>
-
-<table>
- <tr>
- <th style="width:20%">All Architectures</th>
- <td>gettid, futex, clone, rt_sigreturn, rt_tgsigqueueinfo, restart_syscall,
-getrandom, perf_event_open, syncfs, tkill, seccomp</td>
- </tr>
- <tr>
- <th>arm</th>
- <td>vfork, sigreturn, pipe, access, stat64, lstat64, open, getdents, eventfd,
-epoll_wait, readlink, epoll_create, creat, unlink</td>
- </tr>
- <tr>
- <th>arm64</th>
- <td>pivot_root, ioprio_get, ioprio_set</td>
- </tr>
-</table>
-
-<aside class="note"><strong>Note:</strong> x86 and x86_64 system calls will be
-added in a future release.</aside>
+<p>All system calls are expected to provide the same signatures and semantics as
+in the upstream Linux kernel of the same version.</p>
<h3 id="prctl">prctl</h3>
<p>In addition to the upstream <code>prctl</code> operations for supported
@@ -89,102 +52,316 @@
<h3 id="procfs">procfs</h3>
<table>
<tr>
- <th>Path</th>
+ <th>Interface</th>
<th>Description</th>
</tr>
<tr>
- <td><code>/proc/cmdline</code></td>
+ <td>/proc/asound/</td>
+ <td>Read-only file showing the list of currently configured ALSA drivers.</td>
+ </tr>
+ <tr>
+ <td>/proc/cmdline</td>
<td>Read-only file containing command line arguments passed to the kernel.
</td>
</tr>
<tr>
- <td><code>/proc/config.gz</code></td>
+ <td>/proc/config.gz</td>
<td>Read-only file containing kernel build configuration.</td>
</tr>
<tr>
- <td><code>/proc/cpuinfo</code></td>
+ <td>/proc/cpuinfo</td>
<td>Read-only file containing architecture-specific CPU details.</td>
</tr>
<tr>
- <td><code>/proc/kmsg</code></td>
+ <td>/proc/diskstats</td>
+ <td>Read-only file showing I/O statistics of block devices.</td>
+ </tr>
+ <tr>
+ <td>/proc/filesystems</td>
+ <td>Read-only file listing filesystems currently supported by the
+ kernel.</td>
+ </tr>
+ <tr>
+ <tr>
+ <td>/proc/kmsg</td>
<td>Read-only file showing kernel messages in real time.</td>
</tr>
<tr>
- <td><code>/proc/meminfo</code></td>
+ <td>/proc/loadavg</td>
+ <td>Read-only file showing CPU and IO load average over time.</td>
+ </tr>
+ <tr>
+ <td>/proc/meminfo</td>
<td>Read-only file showing memory subsystem details.</td>
</tr>
<tr>
- <td><code>/proc/modules</code></td>
+ <td>/proc/misc</td>
+ <td>Read-only file listing miscellaneous drivers registered on the
+ miscellaneous major device.</td>
+ </tr>
+ <tr>
+ <td>/proc/modules</td>
<td>Read-only file containing information about loaded kernel modules.</td>
</tr>
<tr>
- <td><code>/proc/mounts</code></td>
+ <td>/proc/mounts</td>
<td>Symlink to <code>/proc/self/mounts</code>, which is a read-only file
listing information about the mounted filesystems.</td>
</tr>
<tr>
- <td><code>/proc/net/xt_qtaguid/ctrl</code></td>
+ <td>/proc/net</td>
+ <td>Directory containing a variety of network stack parameters.</td>
+ </tr>
+ <tr>
+ <td>/proc/net/xt_qtaguid/</td>
<td>Read-write file providing information about tagged sockets.</td>
</tr>
<tr>
- <td><code>/proc/self/maps</code></td>
- <td>Read-only file containing the currently mapped memory regions and
- permissions.</td>
+ <td>/proc/pagetypeinfo</td>
+ <td>Read-only file containing page allocator information.</td>
</tr>
<tr>
- <td><code>/proc/stat</code></td>
+ <td>/proc/stat</td>
<td>Read-only file containing various kernel and system statistics.</td>
</tr>
<tr>
- <td><code>/proc/sys/kernel/kptr_restrict</code></td>
+ <td>/proc/swaps</td>
+ <td>Read-only file showing swap space utilization. <strong>This file is
+ optional; its contents and permissions will be verified in VTS only if the
+ file is present</strong>.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/abi/swp</td>
+ <td>Read-write file which determines the behavior of the obsoleted ARM
+ instruction SWP.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/fs/pipe-max-size</td>
+ <td>Read-write file that reports the maximum size, in bytes, of an
+ individual pipe buffer.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/fs/protected_hardlinks</td>
+ <td>Read-write file that controls the behavior of creation of hard links.
+ </td>
+ </tr>
+ <tr>
+ <td>/proc/sys/fs/protected_symlinks</td>
+ <td>Read-write file that controls the behavior of creation of symbolic
+ links.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/fs/suid_dumpable</td>
+ <td>Read-write file that controls the core dump mode for setuid or otherwise
+ protected/tainted binaries.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/kernel/core_pattern</td>
+ <td>Read-write file that specifies the core dump filename pattern.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/kernel/core_pipe_limit</td>
+ <td>Read-write file that defines how many concurrent crashing processes may
+ be piped to user applications in parallel.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/kernel/dmesg_restrict</td>
+ <td>Read-write file that controls whether unprivileged users may access
+ dmesg.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/kernel/domainname</td>
+ <td>Read-write file that contains the YP/NIS domain name of the system.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/kernel/hostname</td>
+ <td>Read-write file that determines the host name of the system.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/kernel/hung_task_timeout_secs</td>
+ <td>Read-write file that controls the timeout used to determine when a task
+ has become non-responsive and should be considered hung. <strong>This file
+ is optional; its contents and permissions will be verified in VTS only if
+ the file is present</strong>.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/kernel/kptr_restrict</td>
<td>Read-write file that determines whether kernel pointers are printed in
<code>proc</code> files and other interfaces.</td>
</tr>
<tr>
- <td><code>/proc/sys/kernel/randomize_va_space</code></td>
+ <td>/proc/sys/kernel/modules_disabled</td>
+ <td>Read-write file that controls whether kernel modules may be loaded.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/kernel/panic_on_oops</td>
+ <td>Read-write file that controls the kernel's behavior on oops.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/kernel/perf_event_max_sample_rate</td>
+ <td>Read-write file that controls the maximum sample rate of performance
+ events.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/kernel/perf_event_paranoid</td>
+ <td>Read-write file that controls the usage of the performance events system
+ by unprivileged users.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/kernel/pid_max</td>
+ <td>Read-write file that contains the PID allocation wrap value.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/kernel/random/boot_id</td>
+ <td>Read-only file that contains a new random ID on each boot.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/kernel/randomize_va_space</td>
<td>Read-write file that determines the address layout randomization policy
for the system.</td>
</tr>
<tr>
- <td><code>/proc/sys/vm/mmap_min_addr</code></td>
+ <td>/proc/sys/kernel/sched_child_runs_first</td>
+ <td>Read-write file that controls whether newly forked tasks are favored in
+ scheduling over their parent tasks.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/kernel/sched_latency_ns</td>
+ <td>Read-write file that contains the maximum latency, in nanoseconds, a task
+ may incur prior to being scheduled.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/kernel/sched_rt_period_us</td>
+ <td>Read-write file that contains the period length used by the system-wide RT
+ execution limit in microseconds.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/kernel/sched_rt_runtime_us</td>
+ <td>Read-write file that contains the amount of time, relative to
+ sched_rt_period_us, that the system may execute RT tasks.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/kernel/sched_tunable_scaling</td>
+ <td>Read-write file that controls whether sched_latency_ns should be
+ automatically adjusted by the scheduler based on the number of CPUs.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/kernel/sched_wakeup_granularity_ns</td>
+ <td>Read-write file that contains how much more virtual runtime task A must
+ have than task B in nanoseconds for task B to preempt it.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/kernel/sysrq</td>
+ <td>Read-write file that controls the functions allowed to be invoked via the
+ sysrq key.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/net/*</td>
+ <td>Directory containing a variety of network stack parameters.</td>
+ </tr>
+ <tr>
+ <td>/proc/sysrq-trigger</td>
+ <td>Write-only file that can be used to initiate sysrq functions.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/vm/dirty_background_ratio</td>
+ <td>Read-write file that contains, as a percentage of total available memory
+ (free pages and reclaimable pages), the number of pages at which the
+ background kernel flusher threads will start writing out dirty data.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/vm/dirty_expire_centisecs</td>
+ <td>Read-write file that defines when dirty data is old enough to be eligible
+ for write out by the kernel flusher threads.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/vm/drop_caches</td>
+ <td>Read-write file that can be used to force the kernel to drop clean
+ caches.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/vm/extra_free_kbytes</td>
+ <td>Read-write file that can be used to keep extra free memory between the
+ threshold where background reclaim (kswapd) kicks in, and the threshold
+ where direct reclaim (by allocating processes) kicks in. <strong>This file
+ is optional; its contents and permissions will be verified in VTS only if
+ the file is present</strong>.</td>
+ </tr>
+ <tr>
+ <td>/proc/sys/vm/max_map_count</td>
+ <td>Read-write file that contains the maximum number of memory map areas a
+ process may have.</td>
+ </tr>
+
+ <tr>
+ <td>/proc/sys/vm/mmap_min_addr</td>
<td>Read-write file that determines the minimum address than can be
<code>mmap</code>'d.</td>
</tr>
<tr>
- <td><code>/proc/sys/vm/mmap_rnd_bits</code></td>
+ <td>/proc/sys/vm/mmap_rnd_bits</td>
<td>Read-write file that specifies the amount of randomness in
<code>mmap</code>'d addresses.</td>
</tr>
<tr>
- <td><code>/proc/sys/vm/mmap_rnd_compat_bits</code></td>
+ <td>/proc/sys/vm/mmap_rnd_compat_bits</td>
<td>Read-write file that specifies the amount of randomness in
<code>mmap</code>'d addresses.</td>
</tr>
<tr>
- <td><code>/proc/sys/vm/overcommit_memory</code></td>
+ <td>/proc/sys/vm/overcommit_memory</td>
<td>Read-write file that determines the kernel virtual memory accounting
mode.</td>
</tr>
<tr>
- <td><code>/proc/uid_cputime/remove_uid_range</code></td>
+ <td>/proc/sys/vm/page-cluster</td>
+ <td>Read-write file that controls the number of pages up to which
+ consecutive pages are read in from swap in a single attempt.</td>
+ </tr>
+ <tr>
+ <td>/proc/uid_cputime/remove_uid_range</td>
<td>Write-only file that, when written, removes UIDs from being shown in
<code>/proc/uid_cputime/show_uid_stat</code>.</td>
</tr>
<tr>
- <td><code>/proc/uid_cputime/show_uid_stat</code></td>
+ <td>/proc/uid_cputime/show_uid_stat</td>
<td>Read-only file containing the time a UID's processes spent in user and
kernel space.</td>
</tr>
<tr>
- <td><code>/proc/version</code></td>
+ <td>/proc/uid_io/stats</td>
+ <td>Read-only file containing a list of I/O stats for each UID in the
+ system</td>
+ </tr>
+ <tr>
+ <td>/proc/uid_procstat/set</td>
+ <td>Write-only file used to configure a UID as foreground or background.</td>
+ </tr>
+ <tr>
+ <td>/proc/uid_time_in_state</td>
+ <td>Read-only file containing the time each UID's processes spend executing at
+ each available frequency. <strong>This file is optional; its contents and
+ permissions will be verified in VTS only if the file is present</strong>.</td>
+ </tr>
+ <tr>
+ <td>/proc/uptime</td>
+ <td>Read-only file that shows how long the system has been running.</td>
+ </tr>
+ <tr>
+ <td>/proc/version</td>
<td>Read-only file containing a string describing the kernel version.</td>
</tr>
<tr>
- <td><code>/proc/vmallocinfo</code></td>
+ <td>/proc/vmallocinfo</td>
<td>Read-only file containing <code>vmalloc</code>'d ranges.</td>
</tr>
<tr>
- <td><code>/proc/zoneinfo</code></td>
+ <td>/proc/vmstat</td>
+ <td>Read-only file containing virtual memory statistics from the kernel.
+ </td>
+ </tr>
+ <tr>
+ <td>/proc/zoneinfo</td>
<td>Read-only file containing information about memory zones.</td>
</tr>
</table>
@@ -193,27 +370,27 @@
<table>
<tr>
- <th>Path</th>
+ <th>Interface</th>
<th>Description</th>
</tr>
<tr>
- <td><code>/dev/ashmem</code></td>
+ <td>/dev/ashmem</td>
<td>Anonymous shared memory device file.</td>
</tr>
<tr>
- <td><code>/dev/binder</code></td>
+ <td>/dev/binder</td>
<td>Binder device file.</td>
</tr>
<tr>
- <td><code>/dev/hwbinder</code></td>
+ <td>/dev/hwbinder</td>
<td>Hardware binder device file.</td>
</tr>
<tr>
- <td><code>/dev/tun</code></td>
+ <td>/dev/tun</td>
<td>Universal TUN/TAP device file.</td>
</tr>
<tr>
- <td><code>/dev/xt_qtaguid</code></td>
+ <td>/dev/xt_qtaguid</td>
<td>QTAGUID netfilter device file.</td>
</tr>
</table>
@@ -221,22 +398,49 @@
<h3 id="sysfs">sysfs</h3>
<table>
<tr>
- <th>Path</th>
+ <th>Interface</th>
<th>Description</th>
</tr>
<tr>
- <td><code>/sys/devices/system/cpu/online</code></td>
- <td>Read-only file showing ranges of CPUs that are currently online.</td>
+ <td>/sys/class/net/*/mtu</td>
+ <td>Read-write file containing the maximum transmission unit for each
+ interface.</td>
</tr>
<tr>
- <td><code>/sys/kernel/wakeup_reasons/last_resume_reason</code></td>
- <td>Read-only file showing a textual description of why the system exited the
- last instance of suspend.</td>
+ <td>/sys/class/rtc/*/hctosys</td>
+ <td>Read-only file showing whether a particular rtc supplies the system time
+ on boot and resume.</td>
</tr>
<tr>
- <td><code>/sys/devices/system/cpu/kernel_max</code></td>
- <td>Read-only file showing the maximum CPU index supported by the kernel.
- </td>
+ <td>/sys/devices/system/cpu/</td>
+ <td>Directory containing information about CPU configuration and
+ frequency.</td>
+ </tr>
+ <tr>
+ <td>/sys/kernel/ipv4</td>
+ <td>Directory of read-write files to configure TCP socket buffer sizes.</td>
+ </tr>
+ <tr>
+ <td>/sys/kernel/wakeup_reasons</td>
+ <td>Directory of read-only files containing the last suspend time and resume
+ reason.</td>
+ </tr>
+ <tr>
+ <td>/sys/power/state</td>
+ <td>Read-write file that controls the system sleep states.</td>
+ </tr>
+ <tr>
+ <td>/sys/power/wake_lock</td>
+ <td>Read-write file that contains the active wake locks.</td>
+ </tr>
+ <tr>
+ <td>/sys/power/wake_unlock</td>
+ <td>Read-write file that contains non-active wake locks.</td>
+ </tr>
+ <tr>
+ <td>/sys/power/wakeup_count</td>
+ <td>Read-write file that can be used to put the system into a sleep state
+ while taking into account the concurrent arrival of wakeup events.</td>
</tr>
</table>
@@ -250,17 +454,17 @@
<th>Description</th>
</tr>
<tr>
- <td><code>/sys/fs/selinux/checkreqprot</code></td>
+ <td>/sys/fs/selinux/checkreqprot</td>
<td>Read/write file containing a binary flag that determines how selinux
protections are checked on <code>mmap</code> and <code>mprotect</code> calls.
</td>
</tr>
<tr>
- <td><code>/sys/fs/selinux/null</code></td>
+ <td>/sys/fs/selinux/null</td>
<td>Read/write null device for use by selinux.</td>
</tr>
<tr>
- <td><code>/sys/fs/selinux/policy</code></td>
+ <td>/sys/fs/selinux/policy</td>
<td>Read-only file containing the selinux policy in binary form.</td>
</tr>
</table>
diff --git a/en/devices/architecture/vintf/comp-matrices.html b/en/devices/architecture/vintf/comp-matrices.html
index 74589ee..01ac349 100644
--- a/en/devices/architecture/vintf/comp-matrices.html
+++ b/en/devices/architecture/vintf/comp-matrices.html
@@ -26,19 +26,20 @@
match rules, see <a href="/devices/architecture/vintf/match-rules.html">Matching
Rules</a>.</p>
-<h2 id="framework-compatibility-matrix">Framework compatibility matrix</h2>
+<h2 id="framework-compatibility-matrix">Framework compatibility matrix
+(FCM)</h2>
<p>The framework compatibility matrix describes the requirements of the
framework on the device it runs on. The matrix file is associated with the
Android framework image (on <code>system.img</code>). It is expected the
-requirements of the framework's compatibility matrix will be satisfied by the
-device manifest (requirements enforced at launch and OTA time).</p>
+requirements of the FCM will be satisfied by the device manifest (requirements
+enforced at launch and OTA time).</p>
-<p>Example framework compatibility matrix file:</p>
+<p>Example FCM file:</p>
<pre class="prettyprint">
<?xml version="1.0" encoding="UTF-8"?>
<!-- Comments, Legal notices, etc. here -->
-<compatibility-matrix version="1.0" type="framework">
+<compatibility-matrix version="1.0" type="framework" level="3">
<hal>
<name>android.hardware.camera</name>
<version>1.0</version>
@@ -46,6 +47,7 @@
<interface>
<name>ICameraProvider</name>
<instance>default</instance>
+ <regex-instance>[a-z_]+/[0-9]+</regex-instance>
</interface>
</hal>
<hal>
@@ -70,6 +72,16 @@
<version>1.1</version>
</hal>
<kernel version="3.18.51">
+ <!-- common configs -->
+ </kernel>
+ <kernel version="3.18.51">
+ <!-- arm specific configs -->
+ <condition>
+ <config>
+ <key>CONFIG_ARM</key>
+ <value type="tristate">y</value>
+ </config>
+ <condition>
<config>
<key>CONFIG_A</key>
<value type="string"></value>
@@ -80,6 +92,7 @@
</config>
</kernel>
<kernel version="4.1.22">
+ <!-- common configs -->
<config>
<key>CONFIG_A</key>
<value type="string">foo</value>
@@ -105,11 +118,14 @@
</compatibility-matrix>
</pre>
-<h2 id="device-compatibility-matrix">Device compatibility matrix</h2>
+<p>For more details, see <a href="/devices/architecture/vintf/fcm">FCM
+Lifecycle</a>.</p>
+
+<h2 id="device-compatibility-matrix">Device compatibility matrix (DCM)</h2>
<p>The device compatibility matrix describes a set of requirements the device
expects from the framework (requirements enforced at launch and OTA time).
</p>
-<p>Example device compatibility matrix file:</p>
+<p>Example DCM file:</p>
<pre class="prettyprint">
<?xml version="1.0" encoding="UTF-8"?>
@@ -147,20 +163,28 @@
<instance>default</instance>
</interface>
</hal>
- <xmlfile format="dtd" optional="false">
- <name>sample_xml</name>
- <version>1.0</version>
- </xmlfile>
+ <vendor-ndk>
+ <version>27</version>
+ </vendor-ndk>
+ <system-sdk>
+ <version>27</version>
+ </system-sdk>
</compatibility-matrix>
</pre>
<h2 id="compatibility-matrix-schema">Compatibility matrix schema</h2>
+<p>This section describes the meaning of these XML tags. Some "required" tags
+can be missing from the source file in Android source tree and written by
+<code><a href="/devices/architecture/vintf/resources#assemble_vintf">assemble_vintf</a></code>
+at build time. "Required" tags must be present in the corresponding files on the
+device.</p>
+
<dl>
<dt><code>?xml</code></dt>
<dd>Optional. It only provides information to the XML parser.</dd>
<dt><code>compatibility-matrix.version</code></dt>
-<dd>Required. Version of this compatibility matrix. Describes the elements
-expected in the manifest. Unrelated to XML version.</dd>
+<dd>Required. Meta-version of this compatibility matrix. Describes the elements
+expected in the compatibility matrix. Unrelated to XML version.</dd>
<dt><code>compatibility-matrix.type</code></dt>
<dd>Required. Type of this compatibility matrix:
<ul>
@@ -168,6 +192,11 @@
<li><code>"framework"</code>: Framework compatibility matrix.</li>
</ul>
</dd>
+<dt><code>manifest.level</code></dt>
+<dd>Required for framework compatibility matrix. Specifies the Framework
+Compatibility Matrix Version (FCM Version) of this file. Should not be
+declared in device-specific framework compatibility matrix (i.e.
+<code>DEVICE_FRAMEWORK_COMPATIBILITY_MATRIX_FILE</code>).</dd>
<dt><code>compatibility-matrix.hal</code></dt>
<dd>Optional and can repeat. Lists a single HAL (HIDL or native) that is
required by owner of the compatibility matrix (framework or device) to be
@@ -184,7 +213,7 @@
<dt><code>compatibility-matrix.hal.optional</code></dt>
<dd>Attribute is optional and defaults to false. States whether this HAL is
optional to the owner of the compatibility matrix (framework or device). If a
-<code><p;hal></code> entry is marked as optional, it means the owner can
+<code><hal></code> entry is marked as optional, it means the owner can
work with this HAL, if present, but does not require it to be present.</dd>
<dt><code>compatibility-matrix.hal.name</code></dt>
<dd>Required. Full package name of this HAL. Examples:
@@ -204,11 +233,28 @@
<dd>Required. Name of the interface.</dd>
<dt><code>compatibility-matrix.hal.interface.instance</code></dt>
<dd>Optional, can repeat. A list of required instances of this interface.</dd>
+<dt><code>compatibility-matrix.hal.interface.regex-instance</code></dt>
+<dd>Optional, can repeat. A list of required instance name patterns on this
+interface. Use
+<a href="http://man7.org/linux/man-pages/man7/regex.7.html" class="external">Extended
+Regular Expression</a> format.</dd>
+<dt><code>compatibility-matrix.kernel</code></dt>
+<dd>Optional, can repeat. Specify a list of kernel configs that the framework
+requires on each kernel version.<br>
+Multiple <code><kernel></code> with the same <code><version></code> can
+exist to imply "and" relationship. Each <code><kernel></code> is a "fragment"
+of the requirements that are enabled only when <code><conditions></code> are
+met.</dd>
<dt><code>compatibility-matrix.kernel.version</code></dt>
<dd>Required. Kernel version. Format is
-<code>{version}.{major-revision}.{minor-revision}</code>. Version and major
-revision must match exactly, minor-revision defines the minimum LTS version of
-the kernel the framework expects.</dd>
+<code><var>VERSION</var>.<var>MAJOR_REVISION</var>.<var>MINOR_REVISION</var></code>.
+Version and major revision must match exactly. Minor revision defines the
+minimum LTS version of the kernel the framework expects.</dd>
+<dt><code>compatibility-matrix.kernel.condition</code></dt>
+<dd>Optional. Must not exist for the first <code><kernel></code> of each
+version. Specifies a list of conditions. Only when the conditions are met are
+the requirements stated in this <code><kernel></code> fragment is enabled.
+</dd>
<dt><code>compatibility-matrix.kernel.config</code></dt>
<dd>Optional, can repeat. Lists <code>CONFIG</code> items that must be
matched for this kernel version. Each <code>CONFIG</code> item is a key-value
@@ -257,7 +303,22 @@
<dd>Optional; used only by the framework compatibility matrix. Declares the
<a href="/devices/architecture/vintf/match-rules.html#avb-version">AVB
version</a> used to sign <code>system.img</code>.</dd>
+<dt><code>compatibility-matrix.vendor-ndk</code></dt>
+<dd>Optional; used only by the device compatibility matrix. Declares the
+requirement of the VNDK vendor snapshot. If missing, no VNDK requirement is made
+on the system image.</dd>
+<dt><code>compatibility-matrix.vendor-ndk.version</code></dt>
+<dd>Required. A positive integer that declares a VNDK version required by the
+vendor image.</dd>
+<dt><code>compatibility-matrix.vendor-ndk.library</code></dt>
+<dd>Optional, can repeat. Declares a set of VNDK libraries required by the
+vendor image. Same semantics as <code>manifest.vendor-ndk.library</code>.</dd>
+<dt><code>compatibility-matrix.system-sdk.version</code></dt>
+<dd>Optional, can repeat; used only by the device compatibility matrix. Declares
+the requirement by vendor apps on System SDK versions. If missing, no System SDK
+requirement is made on the system image.</dd>
</dl>
</body>
</html>
+
diff --git a/en/devices/architecture/vintf/dm.html b/en/devices/architecture/vintf/dm.html
new file mode 100644
index 0000000..091094d
--- /dev/null
+++ b/en/devices/architecture/vintf/dm.html
@@ -0,0 +1,160 @@
+<html devsite>
+ <head>
+ <title>Device Manifest Development</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ {% include "_versions.html" %}
+ <body>
+ <!--
+ Copyright 2018 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>When developing and releasing new devices, vendors can define and declare the
+Target FCM Version in the device manifest (DM). When upgrading the vendor image
+for old devices, vendors can choose to implement new HAL versions and increment
+the Target FCM Version.</p>
+
+<aside class="note"><strong>Note:</strong> For details on terms used in this
+page, see <a href="/devices/architecture/vintf/fcm#terminology">Terminology</a>.
+</aside>
+
+<h2 id=develop-new-devices>Developing new devices</h2>
+<p>When defining the device Target FCM Version for new devices:</p>
+
+<ol>
+<li>Leave <code>DEVICE_MANIFEST_FILE</code> and
+<code>PRODUCT_ENFORCE_VINTF_MANIFEST</code> undefined.</li>
+<li>Implement HALs for the Target FCM Version.</li>
+<li>Write the correct device manifest file.</li>
+<li>Write the Target FCM Version to device manifest file.</li>
+<li>Set <code>DEVICE_MANIFEST_FILE</code>.</li>
+<li>Set <code>PRODUCT_ENFORCE_VINTF_MANIFEST</code> to <code>true</code>.</li>
+</ol>
+
+<h2 id=release-new-devices>Releasing new devices</h2>
+<p>When a new device is released, its initial Target FCM Version needs to be
+determined and declared in the device manifest as the
+"<code>target-level</code>" attribute in the top-level
+<code><manifest></code> element.</p>
+
+<p>For example, devices launching with Android {{ androidPVersionNumber }} must
+have Target FCM Version equal to 3 (the higher version available at this time).
+To declare this in the device manifest:</p>
+
+<pre class="prettyprint">
+<manifest version="1.0" type="device" target-level="3">
+ <!-- ... -->
+</manifest>
+</pre>
+
+<h2 id=upgrade-vendor-image>Upgrading vendor image</h2>
+<p>When upgrading the vendor image for an old device, vendors can choose to
+implement new HAL versions and increment the Target FCM Version.</p>
+
+<h3 id=upgrade-hals>Upgrading HALs</h3>
+<p>During a vendor image upgrade, vendors can implement new HAL versions
+provided that HAL name, interface name, and instance name are the same. For
+example:</p>
+
+<ul>
+<li>Google Pixel 2 and Pixel 2 XL devices released with Target FCM Version
+2, which implemented the required audio 2.0 HAL
+<code>android.hardware.audio@2.0::IDeviceFactory/default</code>.</li>
+<li>For the audio 4.0 HAL that released with Android
+{{ androidPVersionNumber }}, Google Pixel 2 and Pixel 2 XL devices can use a
+full OTA to upgrade to the 4.0 HAL, which implements
+<code>android.hardware.audio@4.0::IDeviceFactory/default</code>.</li>
+<li>Even though the <code>compatibility_matrix.2.xml</code> specifies audio 2.0
+only, the requirement on a vendor image with Target FCM Version 2 has been
+loosened because the Android {{ androidPVersionNumber }} framework (FCM Version
+3) considers audio 4.0 a replacement of audio 2.0 HAL in terms of functionality.
+</li>
+</ul>
+
+<p>To summarize, given that <code>compatibility_matrix.2.xml</code> requires
+audio 2.0 and <code>compatibility_matrix.3.xml</code> requires audio 4.0, the
+requirements are as follows:</p>
+
+<table>
+<thead>
+<tr>
+<th>FCM Version (System)</th>
+<th>Target FCM Version (Vendor)</th>
+<th>Requirements</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>2 (8.1)</td>
+<td>2 (8.1)</td>
+<td>Audio 2.0</td>
+</tr>
+<tr>
+<td>3 ({{ androidPVersionNumber }})</td>
+<td>2 (8.1)</td>
+<td>Audio 2.0 or 4.0</td>
+</tr>
+<tr>
+<td>3 ({{ androidPVersionNumber }})</td>
+<td>3 ({{ androidPVersionNumber }})</td>
+<td>Audio 4.0</td>
+</tr>
+</tbody>
+</table>
+
+<h3 id=upgrade=target-fcm>Upgrading Target FCM Version</h3>
+
+<p>During a vendor image upgrade, vendors can also increment the Target FCM
+Version to specify the targeted FCM Version the upgraded vendor image can work
+with. To bump the Target FCM Version of a device, vendors need to:</p>
+
+<ol>
+<li>Implement all new required HAL Versions for the Target FCM Version.</li>
+<li>Modify HAL Versions in the device manifest file.</li>
+<li>Modify the Target FCM Version in the device manifest file.</li>
+<li>Remove deprecated HAL versions.</li>
+<li>For devices launched with {{ androidPVersionNumber }} or older, cherry-pick
+these CLs before generating OTA update packages:
+ <ul>
+ <li><a href="https://android-review.googlesource.com/722283">CL 722283</a></li>
+ <li><a href="https://android-review.googlesource.com/722284">CL 722284</a></li>
+ <li><a href="https://android-review.googlesource.com/722345">CL 722345</a></li>
+ </ul>
+</li>
+</ol>
+
+<p>For example, Google Pixel and Pixel XL devices launched with Android 7.0
+so their Target FCM Version must be at least legacy. However, the <a
+href="https://android.googlesource.com/device/google/marlin/+/0a276ad8b98fde395ed99a4b303434800c07049e/manifest.xml#1" class="external">device
+manifest</a> declares the Target FCM Version 2 because the vendor image has
+been updated to conform with <code>compatibility_matrix.2.xml</code>:</p>
+
+<pre class="prettyprint">
+<manifest version="1.0" type="device" target-level="2">
+</pre>
+
+<p>If vendors do not implement all required new HAL versions or do not remove
+deprecated HAL versions, the Target FCM Version cannot be upgraded.</p>
+
+<p>For example, Google Pixel 2 and Pixel 2 XL devices have Target FCM Version 2.
+While they do implement some HALs required by
+<code>compatibility_matrix.3.xml</code> (such as audio 4.0, health 2.0, etc.),
+they do not remove <code>android.hardware.radio.deprecated@1.0</code>, which is
+deprecated at FCM Version 3 (Android {{ androidPVersionNumber }}). Hence, these
+devices cannot upgrade the Target FCM Version to 3.</p>
+
+</body>
+</html>
diff --git a/en/devices/architecture/vintf/fcm.html b/en/devices/architecture/vintf/fcm.html
new file mode 100644
index 0000000..7087915
--- /dev/null
+++ b/en/devices/architecture/vintf/fcm.html
@@ -0,0 +1,446 @@
+<html devsite>
+ <head>
+ <title>FCM Lifecycle</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ {% include "_versions.html" %}
+ <body>
+ <!--
+ Copyright 2018 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>An Android framework release has multiple Framework Compatibility Matrices
+(FCMs)—one for each upgradable Target FCM Version—that define what
+the framework may use and Target FCM version requirements. As part of the FCM
+lifecycle, Android deprecates and removes HIDL HALs, then modifies FCM files to
+reflect the status of the <a href="#hal-version-status">HAL Version</a>.
+
+<p>To enable framework-only OTAs in their own ecosystems, partners who extend
+vendor interfaces should also deprecate and remove HIDL HALs using the same
+methods.</p>
+
+<aside class="note"><strong>Note:</strong> For more details on HIDL HALs, see
+<a href="/devices/architecture/vintf/comp-matrices">Compatibility Matrices</a>,
+<a href="/devices/architecture/vintf/match-rules">Matching Rules</a>, and
+<a href="/devices/architecture/hidl/versioning">HIDL HAL Versioning</a>.</aside>
+
+<h2 id=terminology>Terminology</h2>
+
+<table>
+<tr>
+<th>Framework Compatibility Matrix (FCM)</th>
+<td>An XML file that specifies framework requirements on conforming vendor
+implementations. The compatibility matrix is versioned, and a new version
+is frozen for each framework release. Each framework release contains
+multiple FCMs.</td>
+</tr>
+<tr>
+<th>Platform FCM Versions (S<sub>F</sub>)</th>
+<td>The set of all FCM versions in a framework release. The framework can work
+with any vendor implementation that satisfies one of these FCMs.</td>
+</tr>
+<tr>
+<th>FCM Version (F)</th>
+<td>The highest version among all FCMs in a framework release.</td>
+</tr>
+<tr>
+<th>Target FCM Version (V)</th>
+<td>The targeted FCM version (from S<sub>F</sub>), declared explicitly in the
+ device manifest, that a vendor implementation satisfies. A vendor
+ implementation must be generated against a published FCM, although it may
+declare newer HAL versions in its Device Manifest.</td>
+</tr>
+<tr>
+<th>HAL Version</th>
+<td>A HAL Version has the format <code>foo@x.y</code>, where <code>foo</code>
+is the HAL name and <code>x.y</code> is the specific version; e.g.
+<code>nfc@1.0</code>, <code>keymaster@3.0</code> (the root prefix, e.g.
+<code>android.hardware</code>, is omitted throughout this document.)</td>
+</tr>
+<tr>
+<th>Device Manifest</th>
+<td>An XML file that specifies what HAL versions the vendor image provides. The
+contents of a device manifest are constrained by the Target FCM version of
+the device but can list HALs that are strictly newer relative to the FCM
+corresponding to V.</td>
+</tr>
+</table>
+
+
+<h2 id=develop-new-fcm>Developing in a new FCM Version</h2>
+<p>Android increments the FCM Version for each framework release (such as
+Android 8, 8.1, etc). During development, the new
+<code>compatibility_matrix.current.xml</code> is created (<code>F</code>) and
+the existing <code>compatibility_matrix.f.xml</code> (where <code>f</code> <
+<code>F</code>) is no longer changed.</p>
+
+<p>To start developing in a new FCM Version <code>F</code>:</p>
+
+<ol>
+<li>Copy the latest <code>compatibility_matrix.<F-1>.xml</code> to
+<code>compatibility_matrix.current.xml</code>.</li>
+<li>Update the <code>level</code> attribute in the file to <code>F</code>.</li>
+<li>Add corresponding build rules to install this compatibility matrix to the
+device.</li>
+</ol>
+
+<h2 id=introduce-new-hal>Introducing a new HAL</h2>
+<p>During development, when introducing a new HAL (Wi-Fi, NFC, etc.) to Android
+on the current FCM Version <code>F</code>, add the HAL to
+<code>compatibility_matrix.current.xml</code> with the following
+<code>optional</code> settings:</p>
+
+<ul>
+<li><code>optional="false"</code> if devices that ship with <code>V = F</code>
+must launch with this HAL,<br>
+<br>
+OR
+<br>
+</li>
+<li><code>optional="true"</code> if devices that ship with <code>V = F</code>
+can launch without this HAL.</li>
+</ul>
+
+<p>For example, Android 8.1 introduced <code>cas@1.0</code> as an optional HAL.
+Devices launching with Android 8.1 are not required to implement this HAL, so
+the following entry was added to <code>compatibility_matrix.current.xml</code>
+(renamed to <code><a
+href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.2.xml#74" class="external">compatibility_matrix.2.xml</code></a>
+after Android 8.1 released):</p>
+
+<pre class="prettyprint">
+<hal format="hidl" optional="true">
+ <name>android.hardware.cas</name>
+ <version>1.0</version>
+ <interface>
+ <name>IMediaCasService</name>
+ <instance>default</instance>
+ </interface>
+</hal>
+</pre>
+
+<h2 id=upgrade-hal-minor>Upgrading a HAL (minor)</h2>
+<p>During development, when a HAL has a minor-version upgrade from
+<code>x.z</code> to <code>x.(z+1)</code> at current FCM Version <code>F</code>,
+if that version is:</p>
+
+<ul>
+<li>Required on devices launching with <code>V = F</code>, the
+<code>compatibility_matrix.current.xml</code> must state <code>x.(z+1)</code>and
+<code>optional="false"</code>.</li>
+<li>Not required on devices launching with <code>V = F</code>, the
+<code>compatibility_matrix.current.xml</code> must copy <code>x.y-z</code> and
+optionality from <code>compatibility_matrix.<F-1>.xml</code> and change
+the version to <code>x.w-(z+1)</code> (where <code>w >= y</code>).</li>
+</ul>
+
+<p>For example, Android 8.1 introduced <code>broadcastradio@1.1</code> as a
+minor version upgrade of 1.0 HAL. The older version,
+<code>broadcastradio@1.0</code>, is optional for devices launching with Android
+8.0 while the newer version, <code>broadcastradio@1.1</code>, is optional for
+devices launching with Android 8.1. In <code><a
+href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.1.xml#58" class="external">compatibility_matrix.1.xml</code></a>:</p>
+
+<pre class="prettyprint">
+<hal format="hidl" optional="true">
+ <name>android.hardware.broadcastradio</name>
+ <version>1.0</version>
+ <interface>
+ <name>IBroadcastRadioFactory</name>
+ <instance>default</instance>
+ </interface>
+</hal>
+</pre>
+
+<p>This entry was copied to <code>compatibility_matrix.current.xml</code>
+(renamed to <code><a
+href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.2.xml#58">compatibility_matrix.2.xml</code></a>
+after Android 8.1 released) and modified as follows:</p>
+
+<pre class="prettyprint">
+<hal format="hidl" optional="true">
+ <name>android.hardware.broadcastradio</name>
+ <version>1.0-1</version>
+ <interface>
+ <name>IBroadcastRadioFactory</name>
+ <instance>default</instance>
+ </interface>
+</hal>
+</pre>
+
+<h2 id=upgrade-hal-major>Upgrading a HAL (major)</h2>
+<p>During development, when a HAL has a major-version upgrade at current FCM
+Version <code>F</code>, the new major version <code>x.0</code> is added to
+<code>compatibility_matrix.current.xml</code> with the following
+<code>optional</code> settings:</p>
+
+<ul>
+<li><code>optional="false"</code> with only version <code>x.0</code>, if devices
+that ship with <code>V = F</code> must launch with <code>x.0</code>.</li>
+<li><code>optional="false"</code> but along with older major versions in the
+same <code><hal></code> tag, if devices that ship with <code>V = F</code>
+must launch with this HAL, but can launch with an older major version.</li>
+<li><code>optional="true"</code> if devices that ship with <code>V = F</code> do
+not have to launch the HAL.</li>
+</ul>
+
+<p>For example, Android {{ androidPVersionNumber }} introduces
+<code>health@2.0</code> as a major-version upgrade of the 1.0 HAL and deprecates
+the 1.0 HAL. The older version, <code>health@1.0</code>, is optional for devices
+launching with Android 8.0 and Android 8.1. Devices launching with Android
+{{ androidPVersionNumber }} must not provide the deprecated 1.0 HAL and must
+instead provide the new 2.0 version. In <code><a
+href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.legacy.xml#150" class="external">compatibility_matrix.legacy.xml</code></a>,
+<code><a
+href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.1.xml#150" class="external">compatibility_matrix.1.xml</code></a>,
+and <code><a
+href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.2.xml#158" class="external">compatibility_matrix.2.xml</code></a>:</p>
+
+<pre class="prettyprint">
+<hal format="hidl" optional="true">
+ <name>android.hardware.health</name>
+ <version>1.0</version>
+ <interface>
+ <name>IHealth</name>
+ <instance>default</instance>
+ </interface>
+</hal>
+</pre>
+
+<p>This entry is copied to <code>compatibility_matrix.current.xml</code>
+(renamed to <code>compatibility_matrix.3.xml</code> with the Android
+{{ androidPVersionNumber }} release) and modified as follows:</p>
+
+<pre class="prettyprint">
+<hal format="hidl" optional="false">
+ <name>android.hardware.health</name>
+ <version>2.0</version>
+ <interface>
+ <name>IHealth</name>
+ <instance>default</instance>
+ </interface>
+</hal>
+</pre>
+
+<p>Restrictions:</p>
+<ul>
+<li>Because the 2.0 HAL is in <code>compatibility_matrix.3.xml</code> with
+<code>optional="false"</code>, devices that launch with Android
+{{ androidPVersionNumber }} must ship with 2.0 HAL.</li>
+<li>Because the 1.0 HAL is not in <code>compatibility_matrix.3.xml</code>,
+devices that launch with Android {{ androidPVersionNumber }} must not provide
+the 1.0 HAL (as this HAL is considered deprecated).</li>
+<li>Because the 1.0 HAL is present in legacy/1/2.xml (older FCM Versions that
+Android {{ androidPVersionNumber }} can work with) as an optional HAL, the
+Android {{ androidPVersionNumber }} framework can still work with the 1.0 HAL
+(which is not considered a removed HAL Version).</li>
+</ul>
+
+<h2 id=new-fcm-versions>New FCM Versions</h2>
+<p>The process of releasing an FCM Version is done solely by Google as part of
+an AOSP release and includes the following steps:</p>
+
+<ol>
+<li>Rename <code>compatibility_matrix.current.xml</code> to
+<code>compatibility_matrix.F.xml</code>.</li>
+<li>Ensure the file has the attribute <code>level="F"</code>.</li>
+<li>Edit corresponding <a
+href="https://android.googlesource.com/platform/hardware/interfaces/+/2d8442c76270b2c32816d1dac56bbd536b0bf790/compatibility_matrices/Android.mk" class="external">build
+rules</a> to reflect the file name change.</li>
+<li>Ensure all devices build and boot.</li>
+<li><a
+href="https://android.googlesource.com/platform/test/vts-testcase/hal/+/95e09aca7711cace6184077debc556b05335a8b1/treble/vintf/vts_treble_vintf_test.cpp#87" class="external">Update
+VTS tests</a> to ensure devices launching with the latest framework (based
+on Shipping API level) have Target FCM Version <code>V >= F</code>.</li>
+<li>Publish file to AOSP.</li>
+</ol>
+
+<p>This file <strong>cannot</strong> be changed once renamed and published. For
+example, during Android {{ androidPVersionNumber }} development the following
+files are <a
+href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/Android.mk" class="external">built</a>
+for <code>hardware/interfaces/compatibility_matrices/</code>:</p>
+
+<ul>
+<li><code>compatibility_matrix.legacy.xml</code></li>
+<li><code>compatibility_matrix.1.xml</code></li>
+<li><code>compatibility_matrix.2.xml</code></li>
+<li><code>compatibility_matrix.current.xml</code></li>
+</ul>
+
+<p>When Android {{ androidPVersionNumber }} is released,
+<code>compatibility_matrix.current.xml</code> is renamed to
+<code>compatibility_matrix.3.xml</code> and the following files are
+built for <code>hardware/interfaces/compatibility_matrices/</code>:</p>
+
+<ul>
+<li><code>compatibility_matrix.legacy.xml</code></li>
+<li><code>compatibility_matrix.1.xml</code></li>
+<li><code>compatibility_matrix.2.xml</code></li>
+<li><code>compatibility_matrix.3.xml</code></li>
+</ul>
+
+<p>
+<a href="https://android.googlesource.com/platform/test/vts-testcase/hal/+/95e09aca7711cace6184077debc556b05335a8b1/treble/vintf/vts_treble_vintf_test.cpp#435" class="external">VTS
+tests</a> ensure that devices launching with Android {{ androidPVersionNumber }}
+have Target FCM Version >= 3.</p>
+
+<h2 id=hal-version-deprecation>HAL Version deprecation</h2>
+
+<p>Deprecating a HAL Version is a developer decision (i.e. for AOSP HALs, Google
+makes the decision). It could happen when a higher HAL version (whether minor or
+major) is released. When a given HAL <code>foo@x.y</code> is deprecated at FCM
+Version <code>F</code>, it means that any device launching with Target FCM
+Version <code>V = F</code> or later must not implement <code>foo</code> at
+version <code>x.y</code> or any version older than <code>x.y</code>. A
+deprecated HAL version is still supported by the framework for upgrading
+devices.</p>
+
+<p>When FCM Version <code>F</code> is released, a HAL Version
+<code>foo@x.y</code> is considered deprecated if the specific HAL Version is not
+explicitly stated in the latest FCM for Target FCM Version <code>V = F</code>.
+For devices launching with <code>V</code>, one of the following conditions is
+true:</p>
+
+<ul>
+<li>The framework requires a higher version (major or minor);</li>
+<li>The framework doesn't require the HAL anymore.</li>
+</ul>
+
+<p>For example, in Android {{ androidPVersionNumber }}, <code>health@2.0</code>
+is introduced as a major version upgrade of 1.0 HAL. <code>health@1.0</code> is
+removed from <code>compatibility_matrix.3.xml</code> but is present in <code><a
+href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.legacy.xml#150" class="external">compatibility_matrix.legacy.xml</code></a>,
+<code><a
+href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.1.xml#150" class="external">compatibility_matrix.1.xml</code></a>,
+and <code><a
+href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.2.xml#158" class="external">compatibility_matrix.2.xml</code></a>.
+Hence, <code>health@1.0</code> is considered deprecated.</p>
+
+<h2 id=removal-of-support>Removal of support for Target FCM Versions</h2>
+<p>When active devices of a certain Target FCM Version <code>V</code> drop below
+a certain threshold, the Target FCM Version is removed from the set
+S<sub>F</sub> of the next framework release. This is done by removing
+<code>compatibility_matrix.V.xml</code> from the build rules (so that it is no
+longer installed on the system image), and by deleting any code that implemented
+or depended on the removed functionality. Devices with a target FCM Version
+outside of S<sub>F</sub> for a given framework release cannot upgrade to that
+release.</p>
+
+<h2 id=hal-version-status>HAL Version status</h2>
+<p>The following sections describe (in chronological order) the possible states
+of a HAL Version.</p>
+
+<h3 id=hal-unreleased>Unreleased</h3>
+<p>If a HAL Version is not in any of the public and frozen compatibility
+matrices, it is considered unreleased and possibly in development. This includes
+HAL Versions that are only in <code>compatibility_matrix.current.xml</code>.
+Examples:</p>
+
+<ul>
+<li>During the development of Android {{ androidPVersionNumber }} (before
+<code>compatibiility_matrix.current.xml</code> is renamed to
+<code>compatibility_matrix.3.xml</code>), the <code>health@2.0</code> HAL was
+considered an unreleased HAL.</li>
+<li>The <code>teleportation@1.0</code> HAL is not in any released compatibility
+matrices, and is also considered an unreleased HAL.</li>
+</ul>
+
+<h3 id=hal-released-and-current>Released and Current</h3>
+<p>If a HAL Version is in any public and frozen compatibility matrix, it is
+released. For example, after FCM Version 3 is frozen (when
+<code>compatibiility_matrix.current.xml</code> is renamed to
+<code>compatibility_matrix.3.xml</code>) and published to AOSP, the
+<code>health@2.0</code> HAL is considered a released and current HAL Version.
+</p>
+
+<p>If a HAL Version is in a public and frozen compatibility matrix that has
+the highest FCM Version (excluding
+<code>compatibility_matrix.current.xml</code>), the HAL version is current (i.e.
+not deprecated). For example, existing HAL Versions (such as
+<code>nfc@1.0</code> introduced in <code><a
+href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.legacy.xml#198" class="external">compatibility_matrix.legacy.xml</code></a>)
+that continue to exist in <code>compatibility_matrix.3.xml</code> are also
+considered as released and current HAL Versions.</p>
+
+<h3 id=hal-released-but-deprecated>Released but Deprecated</h3>
+<p>A HAL Version is deprecated if and only if:</p>
+
+<ul>
+<li>It is released;</li>
+<li>It is not in the public and frozen compatibility matrix that has the highest
+FCM Version;</li>
+<li>It is in a public and frozen compatibility matrix that the framework still
+supports.</li>
+</ul>
+
+<p>Examples:</p>
+
+<ul>
+<li>The <code>health@1.0</code> HAL is in in <code><a
+href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.legacy.xml#150" class="external">compatibility_matrix.legacy.xml</code></a>,
+<code><a
+href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.1.xml#150" class="external">compatibility_matrix.1.xml</code></a>,
+and <code><a
+href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.2.xml#158" class="external">compatibility_matrix.2.xml</code></a>,
+but not in <code>compatibility_matrix.3.xml</code>. Hence it is considered
+deprecated in Android {{ androidPVersionNumber }}.</li>
+<li>The power HAL has a minor version upgrade in Android
+{{ androidPVersionNumber }}, but <code>power@1.0</code> is still in
+<code>compatibility_matrix.3.xml</code>.
+<ul>
+<li><code>power@1.0</code> is in <code><a
+href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.legacy.xml#206" class="external">compatibility_matrix.legacy.xml</code></a>,
+<code><a
+href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.1.xml#206" class="external">compatibility_matrix.1.xml</code></a>,
+and <code><a
+href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.2.xml#222" class="external">compatibility_matrix.2.xml</code></a>.</li>
+<li><code>compatibility_matrix.3.xml</code> has <code>power@1.0-1</code>.</li>
+</ul>
+</li>
+</ul>
+
+<p>Hence <code>power@1.0</code> is current, but <strong>NOT</strong> deprecated,
+in Android {{ androidPVersionNumber }}.</p>
+
+<h3 id=hal-removed>Removed</h3>
+<p>A HAL Version is removed if and only if:</p>
+
+<ul>
+<li>It was previously released;</li>
+<li>It is not in any public and frozen compatibility matrix that the framework
+supports. </li>
+</ul>
+
+<p>Compatibility matrices that are public, frozen, but not supported by the
+framework are kept in the code base to define the removed HAL Versions set so
+that VTS tests can be written to ensure removed HALs are not on new devices.
+</p>
+
+<h2>Legacy FCMs</h2>
+<p>Target FCM Version legacy is a special value for all non-Treble devices. The
+legacy FCM, <code>compatibility_matrix.legacy.xml</code>, lists the requirements
+of the framework on legacy devices (i.e. devices launched prior to Android 8.0).
+</p>
+
+<p>If this file exists for an FCM with version <code>F</code>, any non-Treble
+device can be upgraded to <code>F</code> provided its device manifest is
+compatible with this file. Its removal follows the same procedure as FCMs for
+other Target FCM Versions (removed after the number of active pre-8.0 devices
+drops below a certain threshold).</p>
+
+</body>
+</html>
diff --git a/en/devices/architecture/vintf/index.html b/en/devices/architecture/vintf/index.html
index fe1fc07..31c0056 100644
--- a/en/devices/architecture/vintf/index.html
+++ b/en/devices/architecture/vintf/index.html
@@ -33,7 +33,7 @@
<img src="../images/treble_vintf_mm.png">
<figcaption><strong>Figure 1.</strong> Manifests, compatibility matrices, and
-runtime-collectible information.</figcaption>
+runtime-collectible information</figcaption>
<p>VINTF object design provides the following for device and framework
components:</p>
@@ -76,9 +76,9 @@
<a href="/devices/architecture/vintf/resources.html#caveats">Caveats</a>).</p>
<h2 id=manifests-matrices>Manifests & matrices</h2>
-<p>Android O requires an API at runtime to query what is on the device and send
-that information to the <a href="/devices/tech/ota/index.html">Over-the-Air
-(OTA)</a> update server and other interested parties (such as CTS
+<p>As of Android 8.0, a runtime API queries what is on the device and sends that
+information to the <a href="/devices/tech/ota/index.html">Over-the-Air (OTA)</a>
+update server and other interested parties (such as CTS
<code>DeviceInfo</code>). Some information is retrieved at runtime and some of
it is statically-defined.</p>
@@ -101,13 +101,23 @@
capabilities. In general, a <em>manifest</em> describes what is provided and a
<em>compatibility matrix</em> describes what is required.</p>
-<p><a href="/devices/architecture/vintf/objects.html">VINTF Object Data</a>
-defines the schema for the manifest,
-<a href="/devices/architecture/vintf/comp-matrices.html">Compatibility
-Matrices</a> defines the schema for the compatibility matrix, and
-<a href="/devices/architecture/vintf/match-rules.html">Matching Rules</a>
-defines the rules for a successful match between a compatibility matrix
-and a manifest.</p>
+<p>This section includes the following details on manifests and matrices:</p>
+<ul>
+ <li><a href="/devices/architecture/vintf/objects.html">Manifests</a> defines
+ the device manifest, framework manifest, and manifest file schema.</li>
+ <li><a href="/devices/architecture/vintf/comp-matrices.html">Compatibility
+ Matrices</a> defines the schema for the compatibility matrix.</li>
+ <li><a href="/devices/architecture/vintf/fcm.html">FCM Lifecycle</a> details
+ how HIDL HALs are deprecated and removed and how FCM files are modifed to
+ reflect the status of the HAL Version.</li>
+ <li><a href="/devices/architecture/vintf/dm.html">DM Development</a> describes
+ how vendors can define and declare the Target FCM Version in the device
+ manifest for new devices or implement new HAL versions and increment the
+ Target FCM Version when upgrading the vendor image for old devices.</li>
+ <li><a href="/devices/architecture/vintf/match-rules.html">Matching Rules</a>
+ defines the rules for a successful match between a compatibility matrix and a
+ manifest.</li>
+</ul>
</body>
</html>
diff --git a/en/devices/architecture/vintf/match-rules.html b/en/devices/architecture/vintf/match-rules.html
index 61a5f1a..dd79254 100644
--- a/en/devices/architecture/vintf/match-rules.html
+++ b/en/devices/architecture/vintf/match-rules.html
@@ -29,15 +29,34 @@
compatibility matrix. The following sections detail matching rules used by
various components.</p>
+<h2 id="fcm-version">Framework compatibility matrix version matches</h2>
+<p>To match a device manifest with a framework compatibility matrix,
+the Shipping FCM version specified by <code>manifest.target-level</code>
+must exactly equal to the FCM version specified by
+<code>compatibility-matrix.level</code>. Otherwise there is no match.</p>
+
+<p>If the framework compatibility matrix is requested with
+<code>libvintf</code>, this match is always successful because
+<code>libvintf</code> opens the device manifest, retrieves the Shipping FCM
+Version, and returns the framework compatibility matrix at that Shipping FCM
+Version (plus some optional HALs from compatibility matrices at higher FCM
+Versions).</p>
+
<h2 id="hals">HAL matches</h2>
<p>The HAL-match rule identifies the versions of <code>hal</code> elements in a
manifest file that are considered supported by the owner of the corresponding
compatibility matrix.</p>
<ul>
-<li>Multiple <code>version</code> elements are concatenated with
-<strong>OR</strong> (see camera example below).</li>
-<li>Multiple <code><hal></code> elements with the same name are
-concatenated with <strong>AND</strong>.</li>
+<li>Multiple <code><hal></code> elements have <strong>AND</strong>
+relationship.</li>
+<li>Multiple <code><version></code> elements within the same
+<code><hal></code> have
+<strong>OR</strong> relationship. If two or more are specified, only
+one of the version needs to be implemented (see DRM example below).</li>
+<li>Multiple <code><instance></code> and
+<code><regex-instance></code> elements within the same
+<code><hal></code> have
+<strong>AND</strong> relationship (see DRM example below).</li>
</ul>
<h4><strong>Example</strong>: Successful HAL match for Camera module</h4>
@@ -92,28 +111,32 @@
<interface>
<name>ICryptoFactory</name>
<instance>default</instance>
+ <regex-instance>[a-z]+/[0-9]+</regex-instance>
</interface>
</hal>
</pre>
-<p>A vendor must implement ONE of the following HALs:</p>
+<p>A vendor must implement ONE of the following instances:</p>
<pre>
-android.hardware.drm@1.x::IDrmFactory/default //where x >= 0
-android.hardware.drm@1.x::IDrmFactory/specific //where x >= 0
+android.hardware.drm@1.x::IDrmFactory/default // where x >= 0
+android.hardware.drm@1.x::IDrmFactory/specific // where x >= 0
</pre>
OR
<pre>
-android.hardware.drm@3.y::IDrmFactory/default //where y >= 1
-android.hardware.drm@3.y::IDrmFactory/specific //where y >= 1
+android.hardware.drm@3.y::IDrmFactory/default // where y >= 1
+android.hardware.drm@3.y::IDrmFactory/specific // where y >= 1
</pre>
-<p>... AND must also implement this HAL:</p>
+<p>... AND must also implement all of these instances:</p>
<pre>
-android.hardware.drm@2.z::ICryptoFactory/default //where z >= 0
+android.hardware.drm@2.z::ICryptoFactory/default // where z >= 0
+android.hardware.drm@2.z::ICryptoFactory/${INSTANCE}
+ // where z >= 0 and ${INSTANCE} matches [a-z]+/[0-9]+
+ // e.g. legacy/0
</pre>
<h2 id="kernel">Kernel matches</h2>
@@ -257,7 +280,7 @@
higher or equal to the minimum version for the range. The maximum version is
purely informational.</li>
<li><code><kernel-sepolicy-version></code> i.e. policydb version. Must
-exactly match the <code>security_policyvers()</code> reported by the device.
+be less than the <code>security_policyvers()</code> reported by the device.
</li>
</ul>
@@ -266,17 +289,22 @@
</p>
<pre class="prettyprint">
- <sepolicy>
- <kernel-sepolicy-version>30</kernel-sepolicy-version>
- <sepolicy-version>25.0</sepolicy-version>
- <sepolicy-version>26.0-3</sepolicy-version>
- </sepolicy>
+<sepolicy>
+ <kernel-sepolicy-version>30</kernel-sepolicy-version>
+ <sepolicy-version>25.0</sepolicy-version>
+ <sepolicy-version>26.0-3</sepolicy-version>
+</sepolicy>
</pre>
<p>On the device:</p>
<ul>
-<li>The value returned by <code>security_policyvers()</code> must exactly equal
-30. Otherwise it is not a match.</li>
+<li>The value returned by <code>security_policyvers()</code> must be greater
+than or equal to 30. Otherwise it is not a match. For example:
+<ul>
+<li>If a device returns 29, it is not a match.</li>
+<li>If a device returns 31, it is a match.</li>
+</ul>
+</li>
<li>SE Policy version must be one of 25.0-∞ or 26.0-∞. Otherwise it is not a
match. (The "<code>-3</code>" after "<code>26.0</code>" is purely
informational.)</li>
@@ -362,5 +390,126 @@
ro.boot.vbmeta.avb_version == 2.1 <font style="font-family: Roboto, Arial, Helvetica, sans-serif; background-color: green; color: white"> match </font>
</pre>
+<h2 id="vndk">VNDK version matches</h2>
+<p>The device compatibility matrix declares the required VNDK version in
+<code>compatibility-matrix.vendor-ndk.version</code>. If the device
+compatibility matrix does not have a <code><vendor-ndk></code> tag, no
+requirements are imposed, and hence it is always considered a match.</p>
+<p>If the device compatibility matrix does have a <code><vendor-ndk></code>
+tag, an <code><vendor-ndk></code> entry with a matching
+<code><version></code> is looked up from the set of VNDK vendor snapshots
+provided by the framework in the framework manifest. If such an entry does not
+exist, there is no match.</p>
+<p>If such entry does exist, the set of libraries enumerated in the device
+compatibility matrix must be a subset of the set of libraries stated in the
+framework manifest; otherwise, the entry is not considered a match.</p>
+<ul>
+ <li>As a special case, if no libraries are enumerated in the device
+ compatibility matrix, the entry is always considered a match, because empty
+ set is a subset of any set.</li>
+</ul>
+
+<h4><strong>Example:</strong> Successful VNDK version match</h4>
+<p>If the device compatibility matrix states the following requirement on VNDK:
+</p>
+
+<pre class="prettyprint">
+<!-- Example Device Compatibility Matrix -->
+<vendor-ndk>
+ <version>27</version>
+ <library>libjpeg.so</library>
+ <library>libbase.so</library>
+</vendor-ndk>
+</pre>
+
+<p>In the framework manifest, only the entry with version 27 is considered.</p>
+
+<pre class="prettyprint">
+<!-- Framework Manifest Example A -->
+<vendor-ndk>
+ <version>27</version>
+ <library>libjpeg.so</library>
+ <library>libbase.so</library>
+ <library>libfoo.so</library>
+</vendor-ndk>
+</pre>
+
+<p>Example A is a match, because VNDK version 27 is in the framework manifest,
+and <code>{libjpeg.so, libbase.so, libfoo.so} ⊇ {libjpeg.so, libbase.so}</code>.
+</p>
+
+<pre class="prettyprint">
+<!-- Framework Manifest Example B -->
+<vendor-ndk>
+ <version>26</version>
+ <library>libjpeg.so</library>
+ <library>libbase.so</library>
+</vendor-ndk>
+<vendor-ndk>
+ <version>27</version>
+ <library>libbase.so</library>
+</vendor-ndk>
+</pre>
+
+<p>Example B is not a match. Even though VNDK version 27 is in the framework
+manifest, <code>libjpeg.so</code> is not supported by the framework in that
+snapshot. VNDK version 26 is ignored.</p>
+
+<h2 id="vsdk">System SDK version matches</h2>
+<p>The device compatibility matrix declares a set of required System SDK
+version in <code>compatibility-matrix.system-sdk.version</code>. There is a
+match only if the set is a subset of provided System SDK versions as declared
+in <code>manifest.system-sdk.version</code> in the framework manifest.</p>
+<ul>
+ <li>As a special case, if no System SDK versions are enumerated in the device
+ compatibility matrix, it is always considered a match, because empty
+ set is a subset of any set.</li>
+</ul>
+
+<h4><strong>Example:</strong> Successful System SDK version match</h4>
+<p>If the device compatibility matrix states the following requirement on System
+SDK:
+</p>
+
+<pre class="prettyprint">
+<!-- Example Device Compatibility Matrix -->
+<system-sdk>
+ <version>26</version>
+ <version>27</version>
+</system-sdk>
+</pre>
+
+<p>Then, the framework must provide System SDK version 26 and 27 to match.</p>
+
+<pre class="prettyprint">
+<!-- Framework Manifest Example A -->
+<system-sdk>
+ <version>26</version>
+ <version>27</version>
+</system-sdk>
+</pre>
+
+<p>Example A is a match.</p>
+
+<pre class="prettyprint">
+<!-- Framework Manifest Example B -->
+<system-sdk>
+ <version>26</version>
+ <version>27</version>
+ <version>28</version>
+</system-sdk>
+</pre>
+
+<p>Example B is a match.</p>
+
+<pre class="prettyprint">
+<!-- Framework Manifest Example C -->
+<system-sdk>
+ <version>26</version>
+</system-sdk>
+</pre>
+
+<p>Example C is not a match, because System SDK version 27 is not provided.</p>
+
</body>
</html>
diff --git a/en/devices/architecture/vintf/objects.html b/en/devices/architecture/vintf/objects.html
index c7ab09f..a5e34a2 100644
--- a/en/devices/architecture/vintf/objects.html
+++ b/en/devices/architecture/vintf/objects.html
@@ -1,6 +1,6 @@
<html devsite>
<head>
- <title>VINTF Object Data</title>
+ <title>Manifests</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
@@ -21,26 +21,39 @@
limitations under the License.
-->
-<p>A VINTF object aggregates data from
-<a href="#device-manifest-file">device manifest</a> and
-<a href="#framework-manifest-file">framework manifest</a> files (XML) and from
-the device itself at <a href="#runtime-data">runtime</a>. Both manifests share a
-format, although not all elements apply to both (for details on the schema, see
-<a href="#manifest-file-schema">Manifest file schema</a>).</p>
-
-<h2 id="device-manifest-file">Device manifest file</h2>
-<p>The Device manifest file is provided by the device. It lives in the Android
-source tree at <code>device/${VENDOR}/${DEVICE}/manifest.xml</code> and on the
-device at
-<code><a href="https://android.googlesource.com/platform/system/libhidl/+/master/vintfdata/manifest.xml" class="external">/vintfdata/manifest.xml</a></code>.
+<p>A VINTF object aggregates data from <a href="#device-manifest-file">device
+manifest</a> and <a href="#framework-manifest-file">framework manifest</a> files
+(XML) and from the device itself at <a href="#runtime-data">runtime</a>. Both
+manifests share a format, although not all elements apply to both (for details
+on the schema, see <a href="#manifest-file-schema">Manifest file schema</a>).
</p>
-<p>Example Device manifest:</p>
+<h2 id="device-manifest-file">Device manifest</h2>
+<p>The Device manifest (provided by the device) consists of the vendor manifest
+and the ODM manifest:</p>
+
+<ul>
+<li>The vendor manifest specifies HALs, VNDK versions, etc. common to an SoC. It
+is recommended to be placed in the Android source tree at
+<code>device/${VENDOR}/${DEVICE}/manifest.xml</code>, but multiple fragment
+files can be used. For details, see
+<a href="/devices/architecture/vintf/resources.html#manifest-fragments">Generate
+DM from fragments</a>.
+</li>
+<li>The ODM manifest overrides the vendor manifest and lists HALs specific to
+the product.</li>
+</ul>
+
+<p>This setup enables multiple products with the same board to share the same
+vendor image (which provides common HALs) yet have different ODM images (which
+specify product-specific HALs).</p>
+
+<p>Example vendor manifest:</p>
<pre class="prettyprint">
<?xml version="1.0" encoding="UTF-8"?>
<!-- Comments, Legal notices, etc. here -->
-<manifest version="1.0" type="device">
+<manifest version="1.0" type="device" target-level="1">
<hal>
<name>android.hardware.camera</name>
<transport>hwbinder</transport>
@@ -70,6 +83,21 @@
<instance>default</instance>
</interface>
</hal>
+ <hal>
+ <name>android.hardware.drm</name>
+ <transport>hwbinder</transport>
+ <version>1.0</version>
+ <interface>
+ <name>ICryptoFactory</name>
+ <instance>default</instance>
+ </interface>
+ <interface>
+ <name>IDrmFactory</name>
+ <instance>default</instance>
+ </interface>
+ <fqname>@1.1::ICryptoFactory/clearkey</fqname>
+ <fqname>@1.1::IDrmFactory/clearkey</fqname>
+ </hal>
<hal format="native">
<name>EGL</name>
<version>1.1</version>
@@ -86,12 +114,47 @@
</manifest>
</pre>
-<h2 id="framework-manifest-file">Framework manifest file</h2>
-<p>The Framework manifest file is provided by Google and is manually generated.
-It lives in the Android source tree at <code>system/libhidl/manifest.xml</code>
-and on the device under <code>/system/manifest.xml</code>.</p>
+<p>Example ODM manifest:</p>
-<p>Example Framework manifest (provided by Google):</p>
+<pre class="prettyprint">
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Comments, Legal notices, etc. here -->
+<manifest version="1.0" type="device">
+ <hal override="true">
+ <name>android.hardware.camera</name>
+ <transport>hwbinder</transport>
+ <version>3.5</version>
+ <interface>
+ <name>ICameraProvider</name>
+ <instance>legacy/0</instance>
+ </interface>
+ </hal>
+ <hal override="true">
+ <name>android.hardware.nfc</name>
+ <transport>hwbinder</transport>
+ </hal>
+ <hal>
+ <name>android.hardware.power</name>
+ <transport>hwbinder</transport>
+ <version>1.1</version>
+ <interface>
+ <name>IPower</name>
+ <instance>default</instance>
+ </interface>
+ </hal>
+</manifest>
+</pre>
+
+For more details, see <a href="/devices/architecture/vintf/dm">DM
+Development</a>.
+
+<h2 id="framework-manifest-file">Framework manifest</h2>
+<p>The Framework manifest file (provided by Google) is manually generated and
+lives in the Android source tree at
+<code><a href="https://android.googlesource.com/platform/system/libhidl/+/master/manifest.xml" class="external">/system/libhidl/manifest.xml</a></code>.
+</p>
+
+<p>Example Framework manifest:</p>
<pre class="prettyprint">
<?xml version="1.0" encoding="UTF-8"?>
@@ -133,20 +196,36 @@
<instance>default</instance>
</interface>
</hal>
+ <vendor-ndk>
+ <version>27</version>
+ </vendor-ndk>
+ <system-sdk>
+ <version>27</version>
+ </system-sdk>
</manifest>
</pre>
<h2 id="manifest-file-schema">Manifest file schema</h2>
+<p>This section describes the meaning of these XML tags. Some "required" tags
+can be missing from the source file in Android source tree and written by
+<code><a href="/devices/architecture/vintf/resources.html#assemble_vintf">assemble_vintf</a></code>
+at build time. "Required" tags must be present in the corresponding files on the
+device.</p>
+
<dl>
<dt><code>?xml</code></dt>
<dd>Optional. Only provides information to the XML parser.</dd>
<dt><code>manifest.version</code></dt>
-<dd>Required. Version of <strong>this</strong> manifest. Describes the elements
-expected in the manifest. Unrelated to XML version.</dd>
+<dd>Required. Meta-version of <strong>this</strong> manifest. Describes the
+elements expected in the manifest. Unrelated to XML version.</dd>
<dt><code>manifest.type</code></dt>
<dd>Required. Type of this manifest. It has value <code>device</code> for
device manifest file and <code>framework</code> for framework manifest
file.</dd>
+<dt><code>manifest.target-level</code></dt>
+<dd>Required for device manifest. Specifies the Framework Compatibility Matrix
+Version (FCM Version) that this device manifest is targeted to be compatible
+with. This is also called the Shipping FCM Version of the device.</dd>
<dt><code>manifest.hal</code></dt>
<dd>Optional, can repeat. A single HAL (HIDL or native, such as GL),
depending on the <code>format</code> attribute.</dd>
@@ -157,6 +236,17 @@
<li><code>native</code>: native HALs.</li>
</ul>
</dd>
+<dt><code>manifest.hal.override</code></dt>
+<dd>Optional. Value can be one of:
+ <ul>
+ <li><code>true</code>: override other <code><hal></code> elements with
+ the same <code><name></code> and major version. If no
+ <code><version></code> or <code><fqname></code> are in this
+ <code><hal></code> element, then this HAL is disabled.</li>
+ <li><code>false</code>: do not override other <code><hal></code> elements
+ with the same <code><name></code> and major version.</li>
+ </ul>
+</dd>
<dt><code>manifest.hal.name</code></dt>
<dd>Required. Fully-qualified package name of HAL. Multiple HAL entries can use
the same name. Examples:
@@ -185,7 +275,7 @@
</ul>
</dd>
<dt><code>manifest.hal.version</code></dt>
-<dd>Required, can repeat. A version for the <code>hal</code> tags in a
+<dd>Optional, can repeat. A version for the <code>hal</code> tags in a
manifest. Format is <code><var>MAJOR</var>.<var>MINOR</var></code>. For
examples, refer to <code>hardware/interfaces</code>,
<code>vendor/${VENDOR}/interfaces</code>,
@@ -195,7 +285,8 @@
HIDL and native HALs may use multiple version fields as long as they represent
<strong>distinct major versions</strong>, with only one minor version per major
version provided. For example, 3.1 and 3.2 cannot coexist, but 1.0 and 3.4 can.
-This applies for all <code>hal</code> elements with the same name.</dd>
+This applies for all <code>hal</code> elements with the same name, unless
+<code>override="true"</code>.</dd>
<dt><code>manifest.hal.interface</code></dt>
<dd>Required, can repeat without duplicates. State an interface in the
package that has an instance name. There can be multiple
@@ -207,56 +298,37 @@
<dd>Required, can repeat. Instance name of the interface. Can have multiple
instances for an interface but no duplicated <code><instance></code>
elements.</dd>
+<dt><code>manifest.hal.fqname</code></dt>
+<dd>Optional, can repeat. An alternative way to specify an instance for the HAL
+with name <code>manifest.hal.name</code>. Format is
+<code>@<var>MAJOR</var>.<var>MINOR</var>::<var>INTERFACE</var>/<var>INSTANCE</var></code>.
+For devices upgrading from Android 8.0, this cannot be used to declare
+instances required by the compatibility matrix.</dd>
<dt><code>manifest.sepolicy</code></dt>
<dd>Required. Contains all sepolicy-related entries.</dd>
<dt><code>manifest.sepolicy.version</code></dt>
-<dd>Required for device manifest. Declares sepolicy version. It has the
-format <var>SDK_INT</var>.<var>PLAT_INT</var>.</dd>
+<dd>Required for device manifest. Declares SELinux version. It has the
+format <code><var>SDK_INT</var>.<var>PLAT_INT</var></code>.</dd>
+<dt><code>manifest.vendor-ndk</code></dt>
+<dd>Required, can repeat; required for framework manifest. Must not be present
+in the device manifest. Multiple <code><vendor-ndk></code> entries must have
+different <code><version></code>’s. Describes a set of VNDK snapshots
+provided by the framework.</dd>
+<dt><code>manifest.vendor-ndk.version</code></dt>
+<dd>Required. It is a positive integer representing the version of the VNDK
+snapshot.</dd>
+<dt><code>manifest.vendor-ndk.library</code></dt>
+<dd>Optional, can repeat, without duplicates. Describes a set of VNDK libraries
+provided by the framework for this VNDK vendor snapshot. The value is the
+filename of a library, e.g. <code>libjpeg.so</code>, including the prefix
+<code>lib</code> and the suffix <code>.so</code>. No path components are
+allowed.</dd>
+<dt><code>manifest.system-sdk.version</code></dt>
+<dd>Optional, can repeat, without duplicates; used only by the framework
+manifest. Describes a set of System SDK versions provided by the framework to
+vendor apps.</dd>
</dl>
-<h2 id=runtime-data>Runtime data</h2>
-<p>Some information required for the device manifest can be collected only at
-runtime. Information is available via
-<code>::android::vintf::VintfObject::GetRuntimeInfo()</code> and includes the
-following:</p>
-
-<ul>
-<li>Kernel information, including:
- <ul>
- <li><code>/proc/config.gz</code>. Zipped full kernel configuration that needs
- to be read at runtime and converted to a queryable object.</li>
- <li><code>/proc/version</code>. Information available through
- <code>uname()</code> system call.</li>
- <li><code>/proc/cpuinfo</code>. Format may be different for 32-bit and 64-bit
- machine.</li>
- <li>policydb version
- <ul>
- <li><code>/sys/fs/selinux/policyvers</code> (assuming <code>selinuxfs</code>
- is mounted at <code>/sys/fs/selinux</code>).</li>
- <li><code>security_policyvers()</code> API from <code>libselinux</code> gives
- you the same.</li>
- </ul>
- </li>
- </ul>
-<li>static libavb version, including:
- <ul>
- <li>bootloader system property: <code>ro.boot.vbmeta.avb_version</code></li>
- <li>init/fs_mgr system property: <code>ro.boot.avb_version</code></li>
- </ul>
-</li>
-</ul>
-
-<h2 id="queryable-api">Queryable API</h2>
-<p>The VINTF object is a system API as the
-<code>hwservicemanager</code>, OTA update service, CTS <code>DeviceInfo</code>,
-and others need information from this API.</p>
-
-<ul>
-<li>C++ queryable API is in
-<a href="https://android.googlesource.com/platform/system/libvintf/+/master/include/vintf/VintfObject.h" class="external"><code>android::vintf::VintfObject</code></a></li>
-<li>Java queryable API is in
-<a href="https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/os/VintfObject.java" class="external"><code>android.os.VintfObject</code></a>
-</ul>
-
</body>
</html>
+
diff --git a/en/devices/architecture/vintf/resources.html b/en/devices/architecture/vintf/resources.html
index 0f408a8..7f70fff 100644
--- a/en/devices/architecture/vintf/resources.html
+++ b/en/devices/architecture/vintf/resources.html
@@ -22,7 +22,7 @@
-->
<p>The following resources provide details on code locations, tools, testing,
-licensing, and caveats.</p>
+and licensing.</p>
<h2 id=query-api-code>Queryable code location</h2>
<p>The code for the queryable vendor interface object goes to
@@ -51,9 +51,8 @@
<li>If a package is both registered to <code>hwservicemanager</code> and found
as a passthrough HAL, <code><transport></code> is set to
<code>hwbinder</code>.</li>
-<li>A dummy <code><sepolicy><version>0.0</version></sepolicy></code>
-element exists at the end of the manifest. It is suggested that the element is
-deleted and injected via <code>assemble_vintf</code> as explained below.</li>
+<li>No SELinux version is written into the manifest. It is suggested that the
+element is injected via <code>assemble_vintf</code> as explained below.</li>
<li>The generated HAL manifest file may be inaccurate. Human attention is
required to fix inconsistencies between the device manifest and what
<code>vendor.img</code> actually provides.</li>
@@ -74,32 +73,21 @@
matrix</strong> from a framework manifest file</h4>
<pre class="devsite-terminal">
-assemble_vintf -m \
+assemble_vintf -m --hals-only \
-i system/libhidl/manifest.xml \
-o device/manufacturer/device_name/compatibility_matrix.xml
</pre>
-<p>Note the following:</p>
-<ul>
-<li>Even though <code><vndk></code> entries are in the output
-compatibility matrix, they should be deleted and injected at build time.</li>
-<li>All HALs are set to <code>optional="true"</code>.</li>
-</ul>
+<p>Note that all HALs are set to <code>optional="true"</code>.</p>
<h4><strong>Example:</strong> Generate a skeleton framework compatibility
matrix from a device manifest file</h4>
<pre class="devsite-terminal">
-BOARD_SEPOLICY_VERS=10000.0 assemble_vintf -m \
- -i device/foo/bar/manifest.xml
+assemble_vintf -m --hals-only \
+ -i device/foo/bar/manifest.xml \
-o path/to/place/output/compatibility_matrix.xml
</pre>
-<p>Note the following:</p>
-<ul>
-<li>Even though <code><sepolicy></code> and <code><avb></code> are
-in the output compatibility matrix, they should be deleted and injected at
-build time.</li>
-<li>All HALs are set to <code>optional="true"</code>.</li>
-</ul>
+<p>Note that all HALs are set to <code>optional="true"</code>.</p>
<h4><strong>Example:</strong> Generate XML files from variables</h4>
@@ -113,37 +101,53 @@
device/manufacturer/device_name/compatibility_matrix.xml
</pre>
-<p>Then the following commands (modified to omit implementation details) are
-executed to generate all XML files:</p>
+<p>Then the following commands are executed (in the build system, modified to omit implementation
+details) to generate all XML files:</p>
<pre class="prettyprint">
# device manifest; only when DEVICE_MANIFEST_FILE is set
BOARD_SEPOLICY_VERS=10000.0 assemble_vintf \
- -i device/manufacturer/device_name/manifest.xml \
- -o $(TARGET_OUT_VENDOR)/manifest.xml
+ $(addprefix,-i ,$(DEVICE_MANIFEST_FILE)) \
+ -o $(TARGET_OUT_VENDOR)/etc/vintf/manifest.xml
# device compatibility matrix; only when DEVICE_MATRIX_FILE is set
assemble_vintf \
- -i device/manufacturer/device_name/compatibility_matrix.xml \
- -o $(TARGET_OUT_VENDOR)/compatibility_matrix.xml
+ -i $(DEVICE_MATRIX_FILE) \
+ -o $(TARGET_OUT_VENDOR)/etc/vintf/compatibility_matrix.xml
# framework manifest
assemble_vintf
- -i system/libhidl/manifest.xml \
+ $(addprefix,-i ,system/libhidl/manifest.xml $(DEVICE_FRAMEWORK_MANIFEST_FILE)) \
-o $(TARGET_OUT)/manifest.xml \
- -c $(TARGET_OUT_VENDOR)/compatibility_matrix.xml
+ -c $(TARGET_OUT_VENDOR)/etc/vintf/compatibility_matrix.xml
-# framework compatibility matrix
+# common framework compatibility matrix for each FCM version
BOARD_SEPOLICY_VERS=$(BOARD_SEPOLICY_VERS) \
POLICYVERS=$(POLICYVERS) \
BOARD_AVB_VBMETA_VERSION=$(BOARD_AVB_VBMETA_VERSION)
assemble_vintf \
- -i hardware/interfaces/compatibility_matrix.xml \
- -o $(TARGET_OUT)/compatibility_matrix.xml \
- -c $(TARGET_OUT_VENDOR)/manifest.xml \
+ $(addprefix,-i ,\
+ hardware/interfaces/compatibility_matrices/compatibility_matrix.empty.xml \
+ $(DEVICE_FRAMEWORK_COMPATIBILITY_MATRIX_FILE)) \
+ -o $(TARGET_OUT)/etc/vintf/compatibility_matrix.empty.xml
+
+# framework compatibility matrices at each FCM version
+assemble_vintf
+ -i hardware/interfaces/compatibility_matrices/compatibility_matrix.{level}.xml \
+ -o $(TARGET_OUT)/etc/vintf/compatibility_matrix.{level}.xml \
+ --kernel=...
+
+# Final framework compatibility matrix to check with device manifest.
+# Each input matrix should have a unique "level" attribute.
+PRODUCT_ENFORCE_VINTF_MANIFEST=$(PRODUCT_ENFORCE_VINTF_MANIFEST) \
+assemble_vintf
+ -i $(TARGET_OUT)/etc/vintf/compatibility_matrix.*.xml
+ -o /tmp/compatibility_matrix.xml
+ -c $(TARGET_OUT_VENDOR)/manifest.xml
</pre>
-<h4><strong>Example:</strong> Generate device manifest from fragments</h4>
+<h4 id=manifest-fragments><strong>Example:</strong>
+Generate device manifest from fragments</h4>
<p>Multiple device manifest fragments can be bundled at build time. For example:</p>
@@ -210,21 +214,5 @@
MODULE_LICENSE_APACHE2 and NOTICE files).</li>
</ul>
-<h2 id="caveats">Caveats</h2>
-<p>It is also possible to determine the HALs at runtime by querying
-<code>hwservicemanager</code> (as <code>lshal</code> does). However:</p>
-<ul>
-<li><code>hwservicemanager</code> does not list passthrough services.</li>
-<li>If a service has just crashed and is restarting, it may be missing from the
-query result.</li>
-<li>It doesn't work for hot pluggable services.</li>
-<li><code>hwservicemanager</code> is not available in recovery mode (see
-below).</li>
-</ul>
-
-<p>In recovery mode, the API to retrieve the vendor interface object must still
-be available to allow the device to check the vendor interface against the
-compatibility matrix again.</p>
-
</body>
</html>
diff --git a/en/devices/architecture/vndk/abi-stability.html b/en/devices/architecture/vndk/abi-stability.html
new file mode 100644
index 0000000..36c33cd
--- /dev/null
+++ b/en/devices/architecture/vndk/abi-stability.html
@@ -0,0 +1,937 @@
+<html devsite>
+ <head>
+ <title>ABI Stability</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ <body>
+ {% include "_versions.html" %}
+ <!--
+ Copyright 2018 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>
+ Application Binary Interface (ABI) stability is a prerequisite of
+ framework-only updates because vendor modules may depend on the Vendor Native
+ Development Kit (VNDK) shared libraries that reside in the system partition.
+ Newly-built VNDK shared libraries must be ABI-compatible to previously
+ released VNDK shared libraries so vendor modules can work with those libraries
+ without recompilation and without runtime errors.
+</p>
+
+<p>
+ To help ensure ABI compatibility, Android {{ androidPVersionNumber }} includes
+ a header ABI checker, as described in the following sections.
+
+
+<h2 id="about-vndk-abi-compliance">About VNDK and ABI compliance</h2>
+
+<p>
+ The VNDK is a restrictive set of libraries that vendor modules may link to and
+ which enable framework-only updates. <em>ABI compliance</em> refers to the
+ ability of a newer version of a shared library to work as expected with a
+ module that is dynamically linked to it (i.e. works as an older version of the
+ library would).
+</p>
+
+<h3 id="about-exported-symbols">About exported symbols</h3>
+
+<p>
+ An <em>exported symbol</em> (also known as a <em>global symbol</em>) refers to
+ a symbol that satisfies all of the following:
+</p>
+
+<ul>
+ <li>Exported by the <em>public headers</em> of a shared library.</li>
+ <li>Appears in the <code>.dynsym</code> table of the <code>.so</code> file
+ corresponding to the shared library.</li>
+ <li>Has WEAK or GLOBAL binding.</li>
+ <li>Visibility is DEFAULT or PROTECTED.</li>
+ <li>Section index is not UNDEFINED.</li>
+ <li>Type is either FUNC or OBJECT.</li>
+</ul>
+
+<p>
+ The <em>public headers</em> of a shared library are defined as the headers
+ available to other libraries/binaries through the
+ <code>export_include_dirs</code>, <code>export_header_lib_headers</code>,
+ <code>export_static_lib_headers</code>,
+ <code>export_shared_lib_headers</code>, and
+ <code>export_generated_headers</code> attributes in <code>Android.bp</code>
+ definitions of the module corresponding to the shared library.
+</p>
+
+<h3 id="about-reachable-types">About reachable types</h3>
+
+<p>
+ A <em>reachable type</em> is any C/C++ built-in or user-defined type that is
+ reachable directly or indirectly through an exported symbol AND exported
+ through public headers. For example, <code>libfoo.so</code> has function
+ <code>Foo</code>, which is an exported symbol found in the
+ <code>.dynsym</code> table. The <code>libfoo.so</code> library includes the
+ following:
+</p>
+
+<table>
+ <tr>
+ <th>foo_exported.h</th>
+ <th>foo.private.h</th>
+ </tr>
+ <tr>
+ <td>
+<pre class="prettyprint">
+typedef struct foo_private foo_private_t;
+
+typedef struct foo {
+ int m1;
+ int *m2;
+ foo_private_t *mPfoo;
+} foo_t;
+
+typedef struct bar {
+ foo_t mfoo;
+} bar_t;
+
+bool Foo(int id, bar_t *bar_ptr);
+</pre>
+</td>
+
+<td>
+<pre class="prettyprint">
+typedef struct foo_private {
+ int m1;
+ float mbar;
+} foo_private_t;
+</pre>
+ </td>
+ </tr>
+</table>
+
+<table>
+ <tr>
+ <th>Android.bp</th>
+ </tr>
+ <tr>
+ <td>
+<pre class="prettyprint">
+cc_library {
+ name : libfoo,
+ vendor_available: true,
+ vndk {
+ enabled : true,
+ }
+ srcs : ["src/*.cpp"],
+ export_include_dirs : [
+ "include"
+ ],
+}
+</pre>
+ </td>
+ </tr>
+</table>
+
+<table>
+ <tr>
+ <th colspan="8">.dynsym table</th>
+ </tr>
+ <tr>
+ <td><code>Num</code>
+ </td>
+ <td><code>Value</code>
+ </td>
+ <td><code>Size</code>
+ </td>
+ <td><code>Type</code>
+ </td>
+ <td><code>Bind</code>
+ </td>
+ <td><code>Vis</code>
+ </td>
+ <td><code>Ndx</code>
+ </td>
+ <td><code>Name</code>
+ </td>
+ </tr>
+ <tr>
+ <td><code>1</code>
+ </td>
+ <td><code>0</code>
+ </td>
+ <td><code>0</code>
+ </td>
+ <td><code>FUNC</code>
+ </td>
+ <td><code>GLOB</code>
+ </td>
+ <td><code>DEF</code>
+ </td>
+ <td><code>UND</code>
+ </td>
+ <td><code>dlerror@libc</code>
+ </td>
+ </tr>
+ <tr>
+ <td><code>2</code>
+ </td>
+ <td><code>1ce0</code>
+ </td>
+ <td><code>20</code>
+ </td>
+ <td><code>FUNC</code>
+ </td>
+ <td><code>GLOB</code>
+ </td>
+ <td><code>DEF</code>
+ </td>
+ <td><code>12</code>
+ </td>
+ <td><code>Foo</code>
+ </td>
+ </tr>
+</table>
+
+
+<p>
+ Looking at <code>Foo</code>, direct/indirect reachable types include:
+</p>
+
+<table>
+ <tr>
+ <th>Type</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><code>bool</code>
+ </td>
+ <td>Return type of <code>Foo</code>.
+ </td>
+ </tr>
+ <tr>
+ <td><code>int</code>
+ </td>
+ <td>Type of first <code>Foo</code> parameter.
+ </td>
+ </tr>
+ <tr>
+ <td><code>bar_t *</code>
+ </td>
+ <td>Type of second Foo parameter. By way of <code>bar_t *</code>,
+ <code>bar_t</code> is exported through <code>foo_exported.h</code>.
+ <br><br>
+ <code>bar_t</code> contains a member <code>mfoo</code>, of type
+ <code>foo_t</code>, which is exported through <code>foo_exported.h</code>,
+ which results in more types being exported:
+
+ <ul>
+ <li><code>int :</code> is the type of <code>m1</code>.</li>
+ <li><code>int * :</code> is the type of <code>m2</code>.</li>
+ <li><code>foo_private_t * : </code> is the type of <code>mPfoo</code>.</li>
+ </ul>
+ <br>
+ However, <code>foo_private_t</code> is NOT reachable because it is not
+ exported through <code>foo_exported.h</code>. (<code>foot_private_t *</code>
+ is opaque, therefore changes made to <code>foo_private_t</code> are allowed.)
+ </td>
+ </tr>
+</table>
+
+<p>
+ A similar explanation can be given for types reachable through base class
+ specifiers and template parameters as well.
+</p>
+
+<h2 id="ensuring-abi-compliance">Ensuring ABI compliance</h2>
+
+<p>
+ ABI compliance must be ensured for the libraries marked
+ <code>vendor_available: true</code> and <code>vndk.enabled: true</code> in the
+ corresponding <code>Android.bp</code> files. For example:
+</p>
+
+<pre class="prettyprint">
+cc_library {
+ name: "libvndk_example",
+ vendor_available: true,
+ vndk: {
+ enabled: true,
+ }
+}
+</pre>
+
+<p>
+ For data types reachable directly or indirectly by an exported function, the
+ following changes to a library are classified as ABI-breaking:
+</p>
+
+<table>
+ <tr>
+ <th>Data type</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>Structures and Classes</td>
+ <td>
+ <ul>
+ <li>Removing non-static data members.</li>
+ <li>Change resulting in the change of the size of the class/struct.</li>
+ <li>Change resulting in a change in the v-table layout.</li>
+ <li>Adding/removing base classes.</li>
+ <li>Changing the order of base classes.</li>
+ <li>Change in template arguments.</li>
+ <li>Change resulting in a change to memory offset of a data
+ member<sup>**</sup>.</li>
+ <li>Change in the const-volatile-restricted qualifiers of a
+ member<sup>*</sup>.</li>
+ <li>Downgrading the access specifier of a data member<sup>*</sup>.</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>Unions</td>
+ <td>
+ <ul>
+ <li>Adding/removing fields.</li>
+ <li>Change which results in the change in the size.</li>
+ <li>Changing the order of fields.</li>
+ <li>Changing field types.</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>Enumerations</td>
+ <td>
+ <ul>
+ <li>Changing the value of a member.</li>
+ <li>Changing the name of a member.</li>
+ <li>Changing the underlying type.</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>Global Symbols</td>
+ <td>
+ <ul>
+ <li>Removing symbols exported by public headers.</li>
+ <li>For global symbols of type FUNC
+ <ul>
+ <li>Adding/removing parameters.</li>
+ <li>Changing the type of any parameter in any way.</li>
+ <li>Changing the return type in any way.</li>
+ <li>Downgrading the access specifier<sup>*</sup>.</li>
+ </ul>
+ </li>
+ <li>For global symbols of type OBJECT
+ <ul>
+ <li>Changing the corresponding C/C++ type in any way.</li>
+ <li>Downgrading the access specifier<sup>*</sup>.</li>
+ </ul>
+ </li>
+ </ul>
+ </td>
+ </tr>
+</table>
+
+<p>
+ <strong><sup>**</sup></strong> Not restricted to changes in offsets of public
+ fields (as inline functions could use private fields internally).
+</p>
+
+<p>
+ <strong><sup>*</sup></strong> While these do not represent a change in the
+ memory layout of the type, they are semantic differences that could lead to
+ libraries not functioning as expected.
+</p>
+
+<h2 id="using-abi-compliance-tools">Using ABI compliance tools</h2>
+
+<p>
+ When a VNDK library is built, the library's ABI is compared with the
+ corresponding ABI reference for the version of the VNDK being built. Reference
+ ABI dumps are located in:
+</p>
+
+<pre class="prettyprint">
+${ANDROID_BUILD_TOP}/prebuilts/abi-dumps/(v)ndk/<${PLATFORM_VNDK_VERSION}>/<BINDER_BITNESS>/<ARCH_ARCH-VARIANT>/source-based
+</pre>
+
+<p>
+ For example, on building <code>libfoo</code> for API level 27 of the VNDK,
+ <code>libfoo</code>'s inferred ABI is compared with its reference at:
+</p>
+
+<pre class="prettyprint">
+${ANDROID_BUILD_TOP}/prebuilts/abi-dumps/(v)ndk/27/64/<ARCH_ARCH-VARIANT>/source-based/libfoo.so.lsdump
+</pre>
+
+<h3 id="abit-breakage-error">ABI breakage error</h3>
+
+<p>
+ On ABI breakages, the build log displays warnings with the warning type and a
+ path to the abi-diff report. For example, if <code>libbinder</code>'s ABI has
+ an incompatible change, the build system throws an error with a message
+ similar to the following:
+</p>
+
+<pre>
+*****************************************************
+error: VNDK library: libbinder.so's ABI has INCOMPATIBLE CHANGES
+Please check compatibility report at:
+out/soong/.intermediates/frameworks/native/libs/binder/libbinder/android_arm64_armv8-a_cortex-a73_vendor_shared/libbinder.so.abidiff
+******************************************************
+---- Please update abi references by running
+platform/development/vndk/tools/header-checker/utils/create_reference_dumps.py -l libbinder ----
+</pre>
+
+<h3 id="building-vndk-lib-abi-checks">Building VNDK library ABI checks</h3>
+
+<p>
+ When a VNDK library is built:
+</p>
+
+<ol>
+ <li><code>header-abi-dumper</code> processes the source files compiled to
+ build the VNDK library (the library's own source files as well as source files
+ inherited through static transitive dependencies), to produce
+ <code>.sdump</code> files that correspond to each source.
+ <br>
+ <img src="../images/abi_check_sdump.png" alt="sdump creation"
+ title="sdump creation">
+ <figcaption><strong>Figure 1.</strong> Creating the <code>.sdump</code>
+ files</figcaption>
+ </li>
+
+ <li><code>header-abi-linker</code> then processes the <code>.sdump</code>
+ files (using either a version script provided to it or the <code>.so</code>
+ file corresponding to the shared library) to produce a <code>.lsdump</code>
+ file that logs all of the ABI information corresponding to the shared library.
+ <br>
+ <img src="../images/abi_check_lsdump.png" alt="lsdump creation"
+ title="lsdump creation">
+ <figcaption><strong>Figure 2.</strong> Creating the <code>.lsdump</code>
+ file</figcaption>
+ </li>
+
+ <li><code>header-abi-diff</code> compares the <code>.lsdump</code>
+ file with a reference <code>.lsdump</code> file to produce a diff report
+ that outlines the differences in the ABIs of the two libraries.
+ <br>
+ <img src="../images/abi_check_abidiff.png" alt="abi diff creation"
+ title="abi diff creation">
+ <figcaption><strong>Figure 3.</strong> Creating the diff report</figcaption>
+ </li>
+</ol>
+
+<h3 id="header-abi-dumper">header-abi-dumper</h3>
+
+<p>
+ The <code>header-abi-dumper</code> tool parses a C/C++ source file and dumps
+ the ABI inferred from that source file into an intermediate file. The build
+ system runs <code>header-abi-dumper</code> on all compiled source files while
+ also building a library that includes the source files from transitive
+ dependencies.
+</p>
+
+<p>
+ Currently <code>.sdump</code> files are formatted as
+ <a href="https://developers.google.com/protocol-buffers/docs/reference/java/com/google/protobuf/TextFormat" class="external">Protobuf
+ TextFormatted</a>, which is not guaranteed to be stable across future
+ releases. As such, <code>.sdump</code> file formatting should be considered a
+ build system implementation detail.
+</p>
+
+<p>
+ For example, <code>libfoo.so</code> has the following source file
+ <strong><code>foo.cpp</code></strong>:
+</p>
+
+<pre class="prettyprint">
+#include <stdio.h>
+#include <foo_exported.h>
+
+bool Foo(int id, bar_t *bar_ptr) {
+ if (id > 0 && bar_ptr->mfoo.m1 > 0) {
+ return true;
+ }
+ return false;
+}</pre>
+
+
+<p>
+ You can use <code>header-abi-dumper</code> to generate an intermediate
+ <code>.sdump</code> file that represents the ABI presented by the source file
+ using:
+</p>
+
+<pre class="prettyprint">
+$ header-abi-dumper foo.cpp -I exported -o foo.sdump -- -x c++
+</pre>
+
+<p>
+ This command tells <code>header-abi-dumper</code> to parse
+ <code>foo.cpp</code> and emit the ABI information that is exposed in the
+ public headers in the <code>exported</code> directory. This is an excerpt
+ (not a complete representation) from <strong><code>foo.sdump</code></strong>
+ generated by <code>header-abi-dumper</code>:
+</p>
+
+<pre class="prettyprint">
+record_types {
+ type_info {
+ name: "foo"
+ size: 12
+ alignment: 4
+ referenced_type: "type-1"
+ source_file: "foo/include/foo_exported.h"
+ linker_set_key: "foo"
+ self_type: "type-1"
+ }
+ fields {
+ referenced_type: "type-2"
+ field_offset: 0
+ field_name: "m1"
+ access: public_access
+ }
+ fields {
+ referenced_type: "type-3"
+ field_offset: 32
+ field_name: "m2"
+ access: public_access
+ }
+ fields {
+ referenced_type: "type-5"
+ field_offset: 64
+ field_name: "mPfoo"
+ access: public_access
+ }
+ access: public_access
+ record_kind: struct_kind
+ tag_info {
+ unique_id: "_ZTS3foo"
+ }
+}
+record_types {
+ type_info {
+ name: "bar"
+ size: 12
+ alignment: 4
+ referenced_type: "type-6"
+…
+pointer_types {
+ type_info {
+ name: "bar *"
+ size: 4
+ alignment: 4
+ referenced_type: "type-6"
+ source_file: "foo/include/foo_exported.h"
+ linker_set_key: "bar *"
+ self_type: "type-8"
+ }
+}
+builtin_types {
+ type_info {
+ name: "int"
+ size: 4
+ alignment: 4
+ referenced_type: "type-2"
+ source_file: ""
+ linker_set_key: "int"
+ self_type: "type-2"
+ }
+ is_unsigned: false
+ is_integral: true
+}
+functions {
+ return_type: "type-7"
+ function_name: "Foo"
+ source_file: "foo/include/foo_exported.h"
+ parameters {
+ referenced_type: "type-2"
+ default_arg: false
+ }
+ parameters {
+ referenced_type: "type-8"
+ default_arg: false
+ }
+ linker_set_key: "_Z3FooiP3bar"
+ access: public_access
+}
+</pre>
+
+
+<p>
+ <code>foo.sdump</code> contains ABI information exposed by the source file
+ <code>foo.cpp</code>, e.g.:
+</p>
+
+<ul>
+ <li><code>record_types</code>. Refer to structs, unions, or classes exposed by
+ the public headers. Each record type has information about its fields, its
+ size, access specifier, the header file it was exposed in, etc.</li>
+ <li><code>pointer_types</code>. Refer to pointer types directly/indirectly
+ referenced by records/functions exposed by public headers, along with the type
+ the pointer points to (via the <code>referenced_type</code> field in
+ <code>type_info</code>). Similar information is logged in the
+ <code>.sdump</code> file for qualified types, built-in C/C++ types, array
+ types, and lvalue and rvalue reference types (such logging information about
+ types allows for recursive diffing).</li>
+ <li><code>functions</code>. Represent functions exposed by public headers.
+ They also have information about the function's mangled name, the return type,
+ the types of the parameters, the access specifier, etc.</li>
+</ul>
+
+<aside class="tip">
+ <strong>Tip:</strong> To get help with the <code>header-abi-dumper</code>
+ tool, run <code>header-abi-dumper --help</code>.
+</aside>
+
+<h3 id="header-abi-linker">header-abi-linker</h3>
+
+<p>
+ The <code>header-abi-linker</code> tool takes the intermediate files produced
+ by <code>header-abi-dumper</code> as input then links those files:
+</p>
+
+<table>
+ <tr>
+ <th>Inputs</th>
+ <td>
+ <ul>
+ <li>Intermediate files produced by <code>header-abi-dumper</code></li>
+ <li>Version script/Map file (optional)</li>
+ <li>.so file of the shared library</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <th>Output</th>
+ <td>A file that logs the ABI of a shared library (e.g.
+ <code>libfoo.so.lsdump </code>represents <code>libfoo</code>'s ABI).
+ </td>
+ </tr>
+</table>
+
+<p>
+ The tool merges the types graphs in all the intermediate files given to it,
+ taking into account one-definition (user-defined types in different
+ translation units with the same fully qualified name, might be semantically
+ different) differences across translation units. The tool then parses either
+ a version script or the <code>.dynsym</code> table of the shared library
+ (<code>.so</code> file) to make a list of the exported symbols.
+</p>
+
+<p>
+ For example, when <code>libfoo</code> adds the <code>bar.cpp</code> file
+ (which exposes a C function <code>bar</code>) to its compilation,
+ <code>header-abi-linker</code> could be invoked to create the complete
+ linked ABI dump of <code>libfoo</code> as follows:
+</p>
+
+<pre class="prettyprint">
+header-abi-linker -I exported foo.sdump bar.sdump \
+ -o libfoo.so.lsdump \
+ -so libfoo.so \
+ -arch arm64 -api current
+</pre>
+
+<p>
+ Example command output in <strong><code>libfoo.so.lsdump</code></strong>:
+</p>
+
+<pre class="prettyprint">
+record_types {
+ type_info {
+ name: "foo"
+ size: 24
+ alignment: 8
+ referenced_type: "type-1"
+ source_file: "foo/include/foo_exported.h"
+ linker_set_key: "foo"
+ self_type: "type-1"
+ }
+ fields {
+ referenced_type: "type-2"
+ field_offset: 0
+ field_name: "m1"
+ access: public_access
+ }
+ fields {
+ referenced_type: "type-3"
+ field_offset: 64
+ field_name: "m2"
+ access: public_access
+ }
+ fields {
+ referenced_type: "type-4"
+ field_offset: 128
+ field_name: "mPfoo"
+ access: public_access
+ }
+ access: public_access
+ record_kind: struct_kind
+ tag_info {
+ unique_id: "_ZTS3foo"
+ }
+}
+record_types {
+ type_info {
+ name: "bar"
+ size: 24
+ alignment: 8
+...
+builtin_types {
+ type_info {
+ name: "void"
+ size: 0
+ alignment: 0
+ referenced_type: "type-6"
+ source_file: ""
+ linker_set_key: "void"
+ self_type: "type-6"
+ }
+ is_unsigned: false
+ is_integral: false
+}
+functions {
+ return_type: "type-19"
+ function_name: "Foo"
+ source_file: "foo/include/foo_exported.h"
+ parameters {
+ referenced_type: "type-2"
+ default_arg: false
+ }
+ parameters {
+ referenced_type: "type-20"
+ default_arg: false
+ }
+ linker_set_key: "_Z3FooiP3bar"
+ access: public_access
+}
+functions {
+ return_type: "type-6"
+ function_name: "FooBad"
+ source_file: "foo/include/foo_exported_bad.h"
+ parameters {
+ referenced_type: "type-2"
+ default_arg: false
+ }
+parameters {
+ referenced_type: "type-7"
+ default_arg: false
+ }
+ linker_set_key: "_Z6FooBadiP3foo"
+ access: public_access
+}
+elf_functions {
+ name: "_Z3FooiP3bar"
+}
+elf_functions {
+ name: "_Z6FooBadiP3foo"
+}
+</pre>
+
+<p>
+ The <code>header-abi-linker</code> tool:
+</p>
+
+<ul>
+ <li>Links the <code>.sdump</code> files provided to it (<code>foo.sdump</code>
+ and <code>bar.sdump</code>), filtering out the ABI information not present in
+ the headers residing in the directory: <code>exported</code>.</li>
+ <li>Parses <code>libfoo.so</code>, and collects information about the symbols
+ exported by the library through its <code>.dynsym</code> table.</li>
+ <li>Adds <code>_Z3FooiP3bar</code> and <code>Bar</code>.</li>
+</ul>
+
+<p>
+ <code>libfoo.so.lsdump</code> is the final generated ABI dump of
+ <code>libfoo.so</code>.
+</p>
+
+<aside class="tip"><strong>Tip:</strong> To get help with the
+ <code>header-abi-linker</code> tool, run
+ <code>header-abi-linker --help</code>.
+</aside>
+
+<h3 id="header-abi-diff">header-abi-diff</h3>
+
+<p>
+ The <code>header-abi-diff</code> tool compares two <code>.lsdump</code> files
+ representing the ABI of two libraries and produces a diff report stating the
+ differences between the two ABIs.
+</p>
+
+<table>
+ <tr>
+ <th>Inputs</th>
+ <td>
+ <ul>
+ <li><code>.lsdump</code> file representing the ABI of an old shared
+ library.</li>
+ <li><code>.lsdump</code> file representing the ABI of a new shared library.
+ </li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <th>Output</th>
+ <td>A diff report stating the differences in the ABIs offered by the two
+ shared libraries compared.
+ </td>
+ </tr>
+</table>
+
+<p>
+ The ABI diff file is designed to be as verbose and readable as possible. The
+ format is subject to change in future releases. For example, you have two
+ versions of <code>libfoo</code>: <code>libfoo_old.so</code> and
+ <code>libfoo_new.so</code>. In <code>libfoo_new.so</code>, in
+ <code>bar_t</code>, you change the type of <code>mfoo</code> from
+ <code>foo_t</code> to <code>foo_t *</code>. Since <code>bar_t</code> is a
+ directly reachable type, this should be flagged as an ABI breaking change by
+ <code>header-abi-diff</code>.
+</p>
+
+<p>
+ To run <code>header-abi-diff</code>:
+</p>
+
+<pre class="prettyprint">
+header-abi-diff -old libfoo_old.so.lsdump \
+ -new libfoo_new.so.lsdump \
+ -arch arm64 \
+ -o libfoo.so.abidiff \
+ -lib libfoo
+</pre>
+
+<p>
+ Example command output in <strong><code>libfoo.so.abidiff</code></strong>:
+</p>
+
+<pre class="prettyprint">
+lib_name: "libfoo"
+arch: "arm64"
+record_type_diffs {
+ name: "bar"
+ type_stack: "Foo-> bar *->bar "
+ type_info_diff {
+ old_type_info {
+ size: 24
+ alignment: 8
+ }
+ new_type_info {
+ size: 8
+ alignment: 8
+ }
+ }
+ fields_diff {
+ old_field {
+ referenced_type: "foo"
+ field_offset: 0
+ field_name: "mfoo"
+ access: public_access
+ }
+ new_field {
+ referenced_type: "foo *"
+ field_offset: 0
+ field_name: "mfoo"
+ access: public_access
+ }
+ }
+}</pre>
+
+
+<p>
+ The <code>libfoo.so.abidiff</code> contains a report of all ABI breaking
+ changes in <code>libfoo</code>. The <code>record_type_diffs</code> message
+ indicates a record has changed and lists the incompatible changes, which
+ include:
+</p>
+
+<ul>
+ <li>The size of the record changing from <code>24</code> bytes to
+ <code>8</code> bytes.</li>
+ <li>The field type of <code>mfoo</code> changing from <code>foo</code> to
+ <code>foo *</code> (all typedefs are stripped off).</li>
+</ul>
+
+<p>
+ The <code>type_stack</code> field indicates how <code>header-abi-diff</code>
+ reached the type that changed (<code>bar</code>). This field may be
+ interpreted as <code>Foo</code> is an exported function that takes in
+ <code>bar *</code> as parameter, that points to <code>bar</code>, which was
+ exported and changed.
+</p>
+
+<aside class="tip">
+ <strong>Tip:</strong> To get help with the <code>header-abi-diff</code> tool,
+ run <code>header-abi-diff --help</code>. You can also refer to
+ <code>development/vndk/tools/header-checker/README.md</code>.
+</aside>
+
+<h2 id="enforcing-abi-api">Enforcing ABI/API</h2>
+
+<p>
+ To enforce the ABI/API of VNDK and LLNDK shared libraries, ABI references must
+ be checked into <code>${ANDROID_BUILD_TOP}/prebuilts/abi-dumps/(v)ndk/</code>.
+ To create these references, run the following command:
+</p>
+
+<pre class="prettyprint">
+${ANDROID_BUILD_TOP}/development/vndk/tools/header-checker/utils/create_reference_dumps.py
+</pre>
+
+<p>
+ After creating the references, any change made to the source code that results
+ in an incompatible ABI/API change in a VNDK or LLNDK library now results in a
+ build error.
+</p>
+
+<p>
+ To update ABI references for specific VNDK core libraries, run the following
+ command:
+</p>
+
+<pre class="prettyprint">
+${ANDROID_BUILD_TOP}/development/vndk/tools/header-checker/utils/create_reference_dumps.py -l <lib1> -l <lib2>
+</pre>
+
+<p>
+ For example, to update <code>libbinder</code> ABI references, run:
+</p>
+
+<pre class="prettyprint">
+${ANDROID_BUILD_TOP}/development/vndk/tools/header-checker/utils/create_reference_dumps.py -l libbinder
+</pre>
+
+<p>
+ To update ABI references for specific LLNDK libraries, run the following
+ command:
+</p>
+
+<pre class="prettyprint">
+${ANDROID_BUILD_TOP}/development/vndk/tools/header-checker/utils/create_reference_dumps.py -l <lib1> -l <lib2> --llndk
+</pre>
+
+<p>
+ For example, to update <code>libm</code> ABI references, run:
+</p>
+
+<pre class="prettyprint">
+${ANDROID_BUILD_TOP}/development/vndk/tools/header-checker/utils/create_reference_dumps.py -l libm --llndk
+</pre>
+
+
+</body>
+</html>
\ No newline at end of file
diff --git a/en/devices/architecture/vndk/build-system.html b/en/devices/architecture/vndk/build-system.html
index df019e6..6c4acf6 100644
--- a/en/devices/architecture/vndk/build-system.html
+++ b/en/devices/architecture/vndk/build-system.html
@@ -55,6 +55,9 @@
<a href="#module-definition">Module definition</a>.</p>
+
+
+
<h2 id="configuration">Configuration</h2>
<p>To enable full build system support for a product device, add
@@ -62,6 +65,8 @@
<pre class="prettyprint">BOARD_VNDK_VERSION := current</pre>
+
+
<h3 id="migration-notes">Migration notes</h3>
<p>Adding <code>BOARD_VNDK_VERSION</code> to <code>BoardConfig.mk</code> has a
@@ -97,6 +102,9 @@
<code>static_libs</code>, and/or <code>shared_libs</code>.</p>
+
+
+
<h2 id="module-definition">Module definition</h2>
<p>To build Android with <code>BOARD_VNDK_VERSION</code>, developers must
@@ -106,6 +114,7 @@
implemented in the build system.</p>
+
<h3 id="vendor-modules">Vendor modules</h3>
<p>Vendor modules are vendor-specific executables or shared libraries that
@@ -135,6 +144,7 @@
<code>LOCAL_SHARED_LIBRARIES</code> in <code>Android.mk</code>.</p>
+
<h3 id="ll-ndk">LL-NDK</h3>
<p>LL-NDK shared libraries are shared libraries with stable ABIs. Both
@@ -179,6 +189,8 @@
shared libraries because vendor modules won't be able to find them in
<em>Generic System Image (GSI)</em>.</aside>
+
+
<h3 id="vndk">VNDK</h3>
<p>In <code>Android.bp</code> files, <code>cc_library</code>,
@@ -207,14 +219,13 @@
<code>shared_libs</code>, must be either an <code>llndk_library</code> or a
module with <code>vendor_available</code> or <code>vndk.enabled</code>.</li>
- <li>If <code>vendor_available</code> is <code>true</code> (the only valid
- value for Android 8.1), the vendor variant is accessible to all
- vendor modules.</li>
+ <li>If <code>vendor_available</code> is <code>true</code>, the vendor variant
+ is accessible to all vendor modules.</li>
- <li>In AOSP master, if <code>vendor_available</code> is
- <code>false</code>, the vendor variant is accessible only to other
- VNDK or VNDK-SP modules (i.e., modules with <code>vendor:true</code>
- cannot link <code>vendor_available:false</code> modules).</li>
+ <li>If <code>vendor_available</code> is <code>false</code>, the vendor variant
+ is accessible only to other VNDK or VNDK-SP modules (i.e., modules with
+ <code>vendor:true</code> cannot link <code>vendor_available:false</code>
+ modules).</li>
</ul>
<p>The default installation path for <code>cc_library</code> or
@@ -242,12 +253,13 @@
<ul>
<li>
If <code>vndk.support_system_process</code> is <code>false</code>,
- the vendor variant is installed into <code>/system/lib[64]/vndk</code>.
+ the vendor variant is installed into
+ <code>/system/lib[64]/vndk-${VER}</code>.
</li>
<li>
Conversely, the vendor variant is installed to
- <code>/system/lib[64]/vndk-sp</code>.
+ <code>/system/lib[64]/vndk-sp-${VER}</code>.
</li>
</ul>
</li>
@@ -292,7 +304,7 @@
<td>
<p>The vendor variants are <em>VNDK</em>.</p>
<p>Shared libraries are installed to
- <code>/system/lib[64]/vndk</code>.</p>
+ <code>/system/lib[64]/vndk-${VER}</code>.</p>
</td>
</tr>
@@ -301,7 +313,7 @@
<td>
<p>The vendor variants are <em>VNDK-SP</em>.</p>
<p>Shared libraries are installed to
- <code>/system/lib[64]/vndk-sp</code>.</p>
+ <code>/system/lib[64]/vndk-sp-${VER}</code>.</p>
</td>
</tr>
@@ -321,21 +333,20 @@
<td rowspan="2"><p><code>true</code></p></td>
<td><p><code>false</code></p></td>
<td>
- <p>The vendor variants are <em>VNDK-Indirect</em>.</p>
- <p>Shared libraries are installed to <code>/system/lib[64]/vndk</code>.</p>
+ <p>The vendor variants are <em>VNDK-Private</em>.</p>
+ <p>Shared libraries are installed to
+ <code>/system/lib[64]/vndk-${VER}</code>.</p>
<p>These must not be directly used by vendor modules.</p>
- <p>New in AOSP master (not in Android 8.1).</p>
</td>
</tr>
<tr>
<td><p><code>true</code></p></td>
<td>
- <p>The vendor variants are <em>VNDK-SP-Indirect-Private</em>.</p>
+ <p>The vendor variants are <em>VNDK-SP-Private</em>.</p>
<p>Shared libraries are installed to
- <code>/system/lib[64]/vndk-sp</code>.</p>
+ <code>/system/lib[64]/vndk-sp-${VER}</code>.</p>
<p>These must not be directly used by vendor modules.</p>
- <p>New in AOSP master (not in Android 8.1).</p>
</td>
</tr>
</table>
@@ -346,38 +357,315 @@
vendor modules won't be able to find them in GSI.</aside>
+
+<h3 id="vndk-extensions">VNDK extensions</h3>
+
+<p>VNDK extensions are VNDK shared libraries with additional APIs. VNDK
+extensions are installed to <code>/vendor/lib[64]/vndk[-sp]</code> (without
+version suffix) and override the original VNDK shared libraries at runtime.</p>
+
+
+<h4 id="defining-vndk-extensions">Defining VNDK extensions</h4>
+
+<p>In Android P, <code>Android.bp</code> natively supports VNDK extensions. To
+build a VNDK extension, define another module with a <code>vendor:true</code>
+and an <code>extends</code> property:</p>
+
+<pre class="prettyprint">
+cc_library {
+ name: "libvndk",
+ vendor_available: true,
+ vndk: {
+ enabled: true,
+ },
+}
+
+cc_library {
+ name: "libvndk_ext",
+ vendor: true,
+ vndk: {
+ enabled: true,
+ extends: "libvndk",
+ },
+}
+</pre>
+
+<p>A module with <code>vendor:true</code>, <code>vndk.enabled:true</code>, and
+<code>extends</code> properties defines VNDK extension:</p>
+
+<ul>
+ <li>The <code>extends</code> property must specify a base VNDK shared library
+ name (or VNDK-SP shared library name).</li>
+
+ <li>VNDK extensions (or VNDK-SP extensions) are named after the base module
+ names from which they extend. For example, the output binary of <code>libvndk_ext</code>
+ is <code>libvndk.so</code> instead of <code>libvndk_ext.so</code>.</li>
+
+ <li>VNDK extensions are installed into <code>/vendor/lib[64]/vndk</code>.</li>
+
+ <li>VNDK-SP extensions are installed into
+ <code>/vendor/lib[64]/vndk-sp</code>.</li>
+
+ <li>The base shared libraries must have both <code>vndk.enabled:true</code> and
+ <code>vendor_available:true</code>.</li>
+</ul>
+
+<p>A VNDK-SP extension must extend from a VNDK-SP shared library. In other
+words, <code>vndk.support_system_process</code> must be equal:</p>
+
+<pre class="prettyprint">
+cc_library {
+ name: "libvndk_sp",
+ vendor_available: true,
+ vndk: {
+ enabled: true,
+ support_system_process: true,
+ },
+}
+
+cc_library {
+ name: "libvndk_sp_ext",
+ vendor: true,
+ vndk: {
+ enabled: true,
+ extends: "libvndk_sp",
+ support_system_process: true,
+ },
+}
+</pre>
+
+<p>VNDK extensions (or VNDK-SP extensions) may depend on other vendor shared
+libraries:</p>
+
+<pre class="prettyprint">
+cc_library {
+ name: "libvndk",
+ vendor_available: true,
+ vndk: {
+ enabled: true,
+ },
+}
+
+cc_library {
+ name: "libvndk_ext",
+ vendor: true,
+ vndk: {
+ enabled: true,
+ extends: "libvndk",
+ },
+ shared_libs: [
+ "libvendor",
+ ],
+}
+
+cc_library {
+ name: "libvendor",
+ vendor: true,
+}
+</pre>
+
+<aside class="note"><strong>Note:</strong> Similar to SP-HAL-Dep, VNDK-SP
+extensions and their dependencies (including vendor libraries) must be labeled
+as <code>same_process_hal_file</code> in sepolicy.</aside>
+
+
+<h4 id="using-vndk-extensions">Using VNDK extensions</h4>
+
+<p>If a vendor module depends on some additional APIs defined by VNDK
+extensions, it must specify the name of the VNDK extension in its
+<code>shared_libs</code> property:</p>
+
+<pre class="prettyprint">
+// A vendor shared library example
+cc_library {
+ name: "libvendor",
+ vendor: true,
+ shared_libs: [
+ "libvndk_ext",
+ ],
+}
+
+// A vendor executable example
+cc_binary {
+ name: "vendor-example",
+ vendor: true,
+ shared_libs: [
+ "libvndk_ext",
+ ],
+}
+</pre>
+
+<p>If a vendor module depends on some VNDK extensions, those VNDK extensions
+will be installed to <code>/vendor/lib[64]/vndk[-sp]</code> automatically.</p>
+
+<p>If a module no longer depends on a VNDK extension, add a clean step to
+<code>CleanSpec.mk</code> to remove the shared library. For example:</p>
+
+<pre class="prettyprint">
+$(call add-clean-step, rm -rf $(TARGET_OUT_VENDOR)/lib/libvndk.so)
+</pre>
+
+
+
<h3 id="conditional-compilation">Conditional compilation</h3>
-<p>If there are some subtle differences between the core variant and the vendor
-variant, you can use <code>target.vendor</code> to specify different
-options for conditional compilation. For example:</p>
+<p>This subsection describes how to deal with the <em>subtle differences</em>
+(e.g. adding or removing a feature from one of the variants) between three VNDK
+shared libraries: (1) the core variant (e.g.
+<code>/system/lib[64]/libexample.so</code>), (2) the vendor variant (e.g.
+<code>/system/lib[64]/vndk[-sp]-${VER}/libexample.so</code>), and (3) the VNDK
+extension (e.g. <code>/vendor/lib[64]/vndk[-sp]/libexample.so</code>).
+
+
+<h4 id="conditional-cflags">Conditional compiler flags</h4>
+
+<p>The Android build system defines <code>__ANDROID_VNDK__</code> for
+vendor variants (including VNDK extensions) by default. You may guard the code
+with the C preprocessor guards:</p>
+
+<pre class="prettyprint">
+void all() { }
+
+#if !defined(__ANDROID_VNDK__)
+void framework_only() { }
+#endif
+
+#if defined(__ANDROID_VNDK__)
+void vndk_only() { }
+#endif
+</pre>
+
+<p>In addition to <code>__ANDROID_VNDK__</code>, different <code>cflags</code>
+or <code>cppflags</code> may be specified in <code>Android.bp</code>. The
+<code>cflags</code> or <code>cppflags</code> specified in
+<code>target.vendor</code> is specific to the vendor variant. For example, the
+code below is the <code>Android.bp</code> module definition for
+<code>libexample</code> and <code>libexample_ext</code>:</p>
+
+<pre class="prettyprint">
+cc_library {
+ name: "libexample",
+ srcs: ["example.c"],
+ vendor_available: true,
+ vndk: {
+ enabled: true,
+ },
+ target: {
+ vendor: {
+ cflags: ["-DLIBEXAMPLE_ENABLE_VNDK=1"],
+ },
+ },
+}
+
+cc_library {
+ name: "libexample_ext",
+ srcs: ["example.c"],
+ vendor: true,
+ vndk: {
+ enabled: true,
+ extends: "libexample",
+ },
+ cflags: [
+ "-DLIBEXAMPLE_ENABLE_VNDK=1",
+ "-DLIBEXAMPLE_ENABLE_VNDK_EXT=1",
+ ],
+}
+</pre>
+
+<p>The code listing of <code>example.c</code>:</p>
+
+<pre class="prettyprint">
+void all() { }
+
+#if !defined(LIBEXAMPLE_ENABLE_VNDK)
+void framework_only() { }
+#endif
+
+#if defined(LIBEXAMPLE_ENABLE_VNDK)
+void vndk() { }
+#endif
+
+#if defined(LIBEXAMPLE_ENABLE_VNDK_EXT)
+void vndk_ext() { }
+#endif
+</pre>
+
+<p>And the exported symbols for each variant will be:</p>
+
+<table>
+ <tr>
+ <th>Installation path</th>
+ <th>Exported symbols</th>
+ </tr>
+
+ <tr>
+ <td><code>/system/lib[64]/libexample.so</code></td>
+ <td><code>all</code>, <code>framework_only</code></td>
+ </tr>
+
+ <tr>
+ <td><code>/system/lib[64]/vndk-${VER}/libexample.so</code></td>
+ <td><code>all</code>, <code>vndk</code></td>
+ </tr>
+
+ <tr>
+ <td><code>/vendor/lib[64]/vndk/libexample.so</code></td>
+ <td><code>all</code>, <code>vndk</code>, <code>vndk_ext</code></td>
+ </tr>
+</table>
+
+<!-- TODO: The paragraph below looks awkward. Refine this subsection to make
+this more fluent. -->
+
+<p>The VNDK ABI compliance checker compares the ABI of VNDK and VNDK
+extensions to the ABI dumps under <code>prebuilts/abi-dumps/vndk</code>:</p>
+
+<ul>
+ <li>Symbols exported by original VNDK shared libraries must be identical to
+ (not the supersets of) the symbols defined in ABI dumps.</li>
+
+ <li>Symbols exported by VNDK extensions must be supersets of the symbols
+ defined in ABI dumps.</li>
+</ul>
+
+
+<h4 id="exclude-source-files-or-shared-libs">Exclude source files or shared
+libs</h4>
+
+<p>To exclude source files from the vendor variant, add them to the
+<code>exclude_srcs</code> property. Similarly, to ensure specific shared
+libraries are not linked with the vendor variant, add them to the
+<code>exclude_shared_libs</code> property. For example:</p>
<pre class="prettyprint">cc_library {
- name: "libconditional_example",
+ name: "libcond_exclude_example",
srcs: ["fwk.c", "both.c"],
shared_libs: ["libfwk_only", "libboth"],
target: {
vendor: {
exclude_srcs: ["fwk.c"],
exclude_shared_libs: ["libfwk_only"],
- cflags: ["-DVENDOR_VARIANT=1"],
- cppflags: ["-DVENDOR_VARIANT=1"],
},
},
}</pre>
-<p>In this example, the core variant of <code>libconditional_example</code>
-includes the code from <code>fwk.c</code> and <code>both.c</code> and
-depends on the shared libraries <code>libfwk_only</code> and
-<code>libboth</code>.</p>
+<p>In this example, the core variant of <code>libcond_exclude_example</code>
+includes the code from <code>fwk.c</code> and <code>both.c</code> and depends
+on the shared libraries <code>libfwk_only</code> and <code>libboth</code>.</p>
-<p>On the other hand, the vendor variant of <code>libconditional_example</code>
-includes only the code from <code>both.c</code> because <code>fwk.c</code>
-is excluded by the <code>exclude_srcs</code> property. Similarly,
-<code>libconditional_example</code> depends only on the shared library
-<code>libboth</code> because <code>libfwk_only</code> is excluded by the
-<code>exclude_shared_libs</code> property. <code>cflags</code> and
-<code>cppflags</code> may specified vendor-specific options as well.</p>
+<p>On the other hand, the vendor variant of
+<code>libcond_exclude_example</code> includes only the code from
+<code>both.c</code> because <code>fwk.c</code> is excluded by the
+<code>exclude_srcs</code> property. Similarly,
+<code>libcond_exclude_example</code> depends only on the shared library
+<code>libboth</code> because <code>libfwk_only</code> is excluded by
+the</code><br/> <code>exclude_shared_libs</code> property.
+
+
+<!-- <h4 id="vndk-ext-header-guideline">VNDK extension header guidelines</h4> -->
+
+<!-- TODO: Add the guide line for VNDK extension headers. -->
+
<h3 id="product-packages">Product packages</h3>
diff --git a/en/devices/architecture/vndk/deftool.html b/en/devices/architecture/vndk/deftool.html
index fb5e69e..2949904 100644
--- a/en/devices/architecture/vndk/deftool.html
+++ b/en/devices/architecture/vndk/deftool.html
@@ -22,72 +22,74 @@
-->
-<p>
-The VNDK definition tool helps vendors migrate their source tree to an Android
-8.0 environment. This tool scans binary files in the system and vendor images
-then resolves dependencies. Based on the module dependency graph, the tool can
-also detect violations to VNDK concepts and provide insight/suggestions for
-moving modules between partitions. If an Generic System Image (GSI) is
-specified, the VNDK definition tool can compare your system image with the
-GSI and determine the extended libraries.
-</p>
-<p>
-This section covers three frequently used commands for the VNDK definition tool:
-</p>
+<p>The VNDK definition tool helps vendors migrate their source tree to an
+Android 8.0 environment. This tool scans binary files in the system and vendor
+images then resolves dependencies. Based on the module dependency graph, the
+tool can also detect violations to VNDK concepts and provide
+insight/suggestions for moving modules between partitions. If an Generic System
+Image (GSI) is specified, the VNDK definition tool can compare your system
+image with the GSI and determine the extended libraries.</p>
+
+<p>This section covers three frequently used commands for the VNDK definition
+tool:</p>
+
<ul>
-<li><code>vndk</code>. Compute VNDK_SP_LIBRARIES, VNDK_SP_EXT_LIBRARIES, and
-EXTRA_VENDOR_LIBRARIES for build system workaround in Android 8.0 and higher.
-</li>
-<li><code>check-dep</code>. Check the violating module dependencies from vendor
-modules to non-eligible framework shared libraries.</li>
-<li><code>deps</code>. Print the dependencies between the shared libraries and
-executables.</li>
+ <li><code>vndk</code>. Compute VNDK_SP_LIBRARIES, VNDK_SP_EXT_LIBRARIES, and
+ EXTRA_VENDOR_LIBRARIES for build system workaround in Android 8.0 and
+ higher.</li>
+
+ <li><code>check-dep</code>. Check the violating module dependencies from
+ vendor modules to non-eligible framework shared libraries.</li>
+
+ <li><code>deps</code>. Print the dependencies between the shared libraries and
+ executables.</li>
</ul>
<p>For more details on advanced command usage, refer to
<a href="https://android.googlesource.com/platform/development/+/master/vndk/tools/definition-tool/README.md" class="external">README.md</a>
file in the VNDK Definition Tool repository.</p>
+
+
+
+
<h2 id="vndk">vndk</h2>
+
<p>The <code>vndk</code> subcommand loads the shared libraries and executables
from the system partition and vendor partitions, then resolves module
dependencies to determine the libraries that must be copied to
-<code>/system/lib[64]/vndk-sp</code> and <code>/vendor/lib[64]</code>. Options
-for the <code>vndk</code> subcommand include:</p>
+<code>/system/lib[64]/vndk-sp-${VER}</code> and <code>/vendor/lib[64]</code>.
+Options for the <code>vndk</code> subcommand include:</p>
<table>
- <tr>
- <th>Option</th>
- <th>Description</th>
- </tr>
- <tr>
- <td><code>--system</code>
- </td>
- <td>Point to a directory containing the files that will reside in the system
-partition.
- </td>
- </tr>
- <tr>
- <td><code>--vendor</code>
- </td>
- <td>Point to a directory containing the files that will reside in a vendor
-partition.
- </td>
- </tr>
- <tr>
- <td><code>--aosp-system</code>
- </td>
- <td>Point to a directory containing the files that will reside in the Generic
-System Image (GSI).
- </td>
- </tr>
- <tr>
- <td><code>--load-extra-deps</code>
- </td>
- <td>Point to a file that describes the implicit dependencies, such as
-<code>dlopen()</code>.
- </td>
- </tr>
+ <tr>
+ <th>Option</th>
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td><code>--system</code></td>
+ <td>Point to a directory containing the files that will reside in the system
+ partition.</td>
+ </tr>
+
+ <tr>
+ <td><code>--vendor</code></td>
+ <td>Point to a directory containing the files that will reside in a vendor
+ partition.</td>
+ </tr>
+
+ <tr>
+ <td><code>--aosp-system</code></td>
+ <td>Point to a directory containing the files that will reside in the Generic
+ System Image (GSI).</td>
+ </tr>
+
+ <tr>
+ <td><code>--load-extra-deps</code></td>
+ <td>Point to a file that describes the implicit dependencies, such as
+ <code>dlopen()</code>.</td>
+ </tr>
</table>
<p>For example, to compute the VNDK library sets, run the following
@@ -108,39 +110,41 @@
<pre class="prettyprint">/system/lib/libart.so: /system/lib/libart-compiler.so</pre>
<p>This line lets the VNDK definition tool know that <code>libart.so</code>
-depends on <code>libart-compiler.so</code>.
-</p>
+depends on <code>libart-compiler.so</code>.</p>
+
+
<h3 id="installation-destination">Installation destination</h3>
+
<p>VNDK definition tool lists libraries and corresponding install directories
for the following categories:</p>
<table>
- <tr>
- <th>Category</th>
- <th>Directory</th>
- </tr>
- <tr>
- <td>vndk_sp
- </td>
- <td>Must install to <code>/system/lib[64]/vndk-sp</code>
- </td>
- </tr>
- <tr>
- <td>vndk_sp_ext
- </td>
- <td>Must install to <code>/vendor/lib[64]/vndk-sp</code>
- </td>
- </tr>
- <tr>
- <td>extra_vendor_libs
- </td>
- <td>Must install to <code>/vendor/lib[64]</code>
- </td>
- </tr>
+ <tr>
+ <th>Category</th>
+ <th>Directory</th>
+ </tr>
+
+ <tr>
+ <td>vndk_sp</td>
+ <td>Must install to <code>/system/lib[64]/vndk-sp-${VER}</code></td>
+ </tr>
+
+ <tr>
+ <td>vndk_sp_ext</td>
+ <td>Must install to <code>/vendor/lib[64]/vndk-sp</code></td>
+ </tr>
+
+ <tr>
+ <td>extra_vendor_libs</td>
+ <td>Must install to <code>/vendor/lib[64]</code></td>
+ </tr>
</table>
+
+
<h3 id="build-system-templates">Build system templates</h3>
+
<p>After gathering outputs from VNDK definition tool, a vendor can create an
<code>Android.mk</code> and fill in <code>VNDK_SP_LIBRARIES</code>,
<code>VNDK_SP_EXT_LIBRARIES</code> and <code>EXTRA_VENDOR_LIBRARIES</code> to
@@ -213,7 +217,12 @@
endif # ifneq ($(filter $(YOUR_DEVICE_NAME),$(TARGET_DEVICE)),)
</pre>
+
+
+
+
<h2 id="check-dep">check-dep</h2>
+
<p>The <code>check-dep</code> subcommand scans vendor modules and checks their
dependencies. If it detects violations, it prints the violating dependant
library and symbol usages:</p>
@@ -224,8 +233,8 @@
--vendor ${ANDROID_PRODUCT_OUT}/vendor \
--tag-file eligible-list.csv \
--module-info ${ANDROID_PRODUCT_OUT}/module-info.json \
- 1> check_dep.txt \
- 2> check_dep_err.txt
+ 1> check_dep.txt \
+ 2> check_dep_err.txt
</pre>
<p>For example, the following sample output shows a violating dependency from
@@ -245,101 +254,113 @@
<p>Options for the <code>check-dep</code> subcommand include:</p>
<table>
- <tr>
- <th style="width:25%">Option</th>
- <th>Description</th>
- </tr>
- <tr>
- <td><code>--tag-file</code>
- </td>
- <td>Must refer to an eligible library tag file (described below), which is a
-Google-provided spreadsheet that described categories of framework shared
-libraries.
- </td>
- </tr>
- <tr>
- <td><code>--module-info</code>
- </td>
- <td>Points to the <code>module-info.json</code> generated by Android build
-system. It helps the VNDK definition tool associate binary modules with source
-code.
- </td>
- </tr>
+ <tr>
+ <th style="width:25%">Option</th>
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td><code>--tag-file</code></td>
+ <td>Must refer to an eligible library tag file (described below), which is a
+ Google-provided spreadsheet that described categories of framework shared
+ libraries.</td>
+ </tr>
+
+ <tr>
+ <td><code>--module-info</code></td>
+ <td>Points to the <code>module-info.json</code> generated by Android build
+ system. It helps the VNDK definition tool associate binary modules with source
+ code.</td>
+ </tr>
</table>
+
+
<h3 id="eligible-library-tag-file">Eligible library tag file</h3>
+
<p>Google provides an eligible VNDK spreadsheet (e.g.
<code>eligible-list.csv</code>) that tags the framework shared libraries that
can be used by vendor modules:</p>
<table>
- <tr>
- <th style="width:25%">Tag</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>LL-NDK</td>
- <td>Shared libraries with stable ABIs/APIs that can be used by both
-framework and vendor modules.</td>
- </tr>
- <tr>
- <td>LL-NDK-Indirect</td>
- <td>Private dependencies of LL-NDK libraries. Vendor modules must not access
-these libraries directly.</td>
- </tr>
- <tr>
- <td>VNDK-SP</td>
- <td>SP-HAL framework shared libraries dependencies.</td>
- </tr>
- <tr>
- <td>VNDK-SP-Indirect</td>
- <td>VNDK-SP dependencies that are not directly accessible to SP-HAL, but can
-be accessed by other vendor modules (except SP-HAL and SP-HAL-Dep)</td>
- </tr>
- <tr>
- <td>VNDK-SP-Indirect-Private</td>
- <td>VNDK-SP dependencies that are not directly accessible to all vendor
-modules.</td>
- </tr>
- <tr>
- <td>VNDK</td>
- <td>Framework shared libraries that are available to vendor modules (except
-SP-HAL and SP-HAL-Dep).</td>
- </tr>
- <tr>
- <td>FWK-ONLY</td>
- <td>Framework-only shared libraries that must not be accessed by vendor
-modules (neither directly nor indirectly).</td>
- </tr>
- <tr>
- <td>FWK-ONLY-RS</td>
- <td>Framework-only shared libraries that must not be accessed by vendor
-modules (except for RS usages).</td>
- </tr>
+ <tr>
+ <th style="width:25%">Tag</th>
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td>LL-NDK</td>
+ <td>Shared libraries with stable ABIs/APIs that can be used by both
+ framework and vendor modules.</td>
+ </tr>
+
+ <tr>
+ <td>LL-NDK-Private</td>
+ <td>Private dependencies of LL-NDK libraries. Vendor modules must not access
+ these libraries directly.</td>
+ </tr>
+
+ <tr>
+ <td>VNDK-SP</td>
+ <td>SP-HAL framework shared libraries dependencies.</td>
+ </tr>
+
+ <tr>
+ <td>VNDK-SP-Private</td>
+ <td>VNDK-SP dependencies that are not directly accessible to all vendor
+ modules.</td>
+ </tr>
+
+ <tr>
+ <td>VNDK</td>
+ <td>Framework shared libraries that are available to vendor modules (except
+ SP-HAL and SP-HAL-Dep).</td>
+ </tr>
+
+ <tr>
+ <td>VNDK-Private</td>
+ <td>VNDK dependencies that are not directly accessible to all vendor
+ modules.</td>
+ </tr>
+
+ <tr>
+ <td>FWK-ONLY</td>
+ <td>Framework-only shared libraries that must not be accessed by vendor
+ modules (neither directly nor indirectly).</td>
+ </tr>
+
+ <tr>
+ <td>FWK-ONLY-RS</td>
+ <td>Framework-only shared libraries that must not be accessed by vendor
+ modules (except for RS usages).</td>
+ </tr>
</table>
<p>The following table describes tags used for vendor shared libraries:</p>
<table>
- <tr>
- <th style="width:25%">Tag</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>SP-HAL</td>
- <td>Same-process HAL implementation shared libraries.</td>
- </tr>
- <tr>
- <td>SP-HAL-Dep</td>
- <td>SP-HAL vendor shared libraries dependencies (a.k.a. SP-HAL dependencies
-excluding LL-NDK and VNDK-SP).</td>
- </tr>
- <tr>
- <td>VND-ONLY</td>
- <td>Framework-invisible shared libraries that must not be accessed by
-framework modules. The copied extended VNDK libraries will be tagged as VND-ONLY
-as well.</td>
- </tr>
+ <tr>
+ <th style="width:25%">Tag</th>
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td>SP-HAL</td>
+ <td>Same-process HAL implementation shared libraries.</td>
+ </tr>
+
+ <tr>
+ <td>SP-HAL-Dep</td>
+ <td>SP-HAL vendor shared libraries dependencies (a.k.a. SP-HAL dependencies
+ excluding LL-NDK and VNDK-SP).</td>
+ </tr>
+
+ <tr>
+ <td>VND-ONLY</td>
+ <td>Framework-invisible shared libraries that must not be accessed by
+ framework modules. The copied extended VNDK libraries will be tagged as
+ VND-ONLY as well.</td>
+ </tr>
</table>
<p>Relationships between tags:</p>
@@ -347,7 +368,12 @@
<img src="../images/treble_vndk_design.png">
<figcaption><strong>Figure 1.</strong> Relationships between tags.</figcaption>
+
+
+
+
<h2 id="deps">deps</h2>
+
<p>To debug the library dependencies, the <code>deps</code> subcommand prints
the module dependencies:</p>
diff --git a/en/devices/architecture/vndk/dir-rules-sepolicy.html b/en/devices/architecture/vndk/dir-rules-sepolicy.html
index 634d9d9..f04836c 100644
--- a/en/devices/architecture/vndk/dir-rules-sepolicy.html
+++ b/en/devices/architecture/vndk/dir-rules-sepolicy.html
@@ -30,7 +30,7 @@
<ul>
<li><code>/system/lib[64]</code> contains all framework shared libraries,
including LL-NDK, VNDK, and framework-only libraries (including
-LL-NDK-Indirect and some libraries with the same names as the
+LL-NDK-Private and some libraries with the same names as the
ones in VNDK-SP).</li>
<li><code>/system/lib[64]/vndk-sp</code> contains VNDK-SP libraries for
same-process HALs.</li>
@@ -107,19 +107,19 @@
<td>Y</td>
</tr>
<tr>
- <td>LL-NDK-Indirect</td>
+ <td>LL-NDK-Private</td>
<td>System</td>
<td>Y</td>
<td>Y</td>
</tr>
<tr>
- <td>VNDK-SP/VNDK-SP-Indirect/VNDK-SP-Indirect-Private</td>
+ <td>VNDK-SP/VNDK-SP-Private</td>
<td>System</td>
<td>Y</td>
<td>Y</td>
</tr>
<tr>
- <td>VNDK-SP-Ext/VNDK-SP-Indirect-Ext</td>
+ <td>VNDK-SP-Ext</td>
<td>Vendor</td>
<td>Y</td>
<td>Y</td>
@@ -168,7 +168,7 @@
</tr>
</table>
-<p>LL-NDK-Indirect, VNDK-SP-Indirect, and VNDK-SP-Indirect-Private must be
+<p>LL-NDK-Private and VNDK-SP-Private must be
accessible from both domains because non-<code>coredomain</code> will
indirectly access them. Similarly, SP-HAL-Dep must be accessible from
<code>coredomain</code> because SP-HAL relies on it.</p>
diff --git a/en/devices/architecture/vndk/extensions.html b/en/devices/architecture/vndk/extensions.html
index a4d45bf..7f0e2ab 100644
--- a/en/devices/architecture/vndk/extensions.html
+++ b/en/devices/architecture/vndk/extensions.html
@@ -27,124 +27,155 @@
functionalities to AOSP libraries. This section provides guidelines for
extending AOSP libraries in a way that does not break CTS/VTS.</p>
+
+
+
+
<h2 id="drop-in-replacement">Drop-in replacement</h2>
+
<p>All modified shared libraries must be <strong>binary-compatible</strong>,
<strong>drop-in replacements</strong> of their AOSP counterpart. All existing
AOSP users must be able to use the modified shared library without
recompilations. This requirement implies the following:</p>
+
<ul>
-<li>AOSP functions must not be removed.</li>
-<li>Structures must not be altered if such structures are exposed to their
-users.</li>
-<li>Pre-condition of functions must not be strengthened.</li>
-<li>Functions must provide equivalent functionalities.</li>
-<li>Post-condition of functions must not be weakened.</li>
+ <li>AOSP functions must not be removed.</li>
+ <li>Structures must not be altered if such structures are exposed to their
+ users.</li>
+ <li>Pre-condition of functions must not be strengthened.</li>
+ <li>Functions must provide equivalent functionalities.</li>
+ <li>Post-condition of functions must not be weakened.</li>
</ul>
+
+
+
+
<h2 id="extended-module-classifications">Extended module classifications</h2>
+
<p>Classify modules by the functionalities they <strong>define</strong> and
<strong>use</strong>.</p>
+
<p class="note"><strong>Note</strong>: <em>Functionalities</em> is used here
instead of API/ABI because it is possible to add functionality without changing
any API/ABI.</p>
<p>Depending on the functionalities defined in a module, modules can be
classified into <strong>DA-Module</strong> and <strong>DX-Module</strong>:</p>
+
<ul>
-<li><em>Defining-only-AOSP Modules (DA-Module)</em> do not define new
-functionalities which were not in the AOSP counterpart.
- <ul>
- <li><em>Example 1.</em> An intact unmodified AOSP library is a DA-Module.</li>
- <li><em>Example 2.</em> If a vendor rewrites the functions in
- <code>libcrypto.so</code> with SIMD instructions (without adding new
- functions), then the modified <code>libcrypto.so</code> will be a DA-Module.
+ <li>
+ <em>Defining-only-AOSP Modules (DA-Module)</em> do not define new
+ functionalities which were not in the AOSP counterpart.
+
+ <ul>
+ <li><em>Example 1.</em> An intact unmodified AOSP library is a
+ DA-Module.</li>
+
+ <li><em>Example 2.</em> If a vendor rewrites the functions in
+ <code>libcrypto.so</code> with SIMD instructions (without adding new
+ functions), then the modified <code>libcrypto.so</code> will be a DA-Module.
+ </li>
+ </ul>
</li>
- </ul>
-</li>
-<li><em>Defining-Extension Modules (DX-Module)</em> either define new
-functionalities or do not have an AOSP counterpart.
- <ul>
- <li><em>Example 1.</em> If a vendor adds a helper function to
- <code>libjpeg.so</code> to access some internal data, then the modified
- <code>libjpeg.so</code> will be a DX-Lib and the newly added function will be
- the extended portion of the library.</li>
- <li><em>Example 2.</em> If a vendor defines a non-AOSP library named
- <code>libfoo.so</code>, then <code>libfoo.so</code> will be a DX-Lib.</li>
- </ul>
-</li>
+
+ <li>
+ <em>Defining-Extension Modules (DX-Module)</em> either define new
+ functionalities or do not have an AOSP counterpart.
+
+ <ul>
+ <li><em>Example 1.</em> If a vendor adds a helper function to
+ <code>libjpeg.so</code> to access some internal data, then the modified
+ <code>libjpeg.so</code> will be a DX-Lib and the newly added function will be
+ the extended portion of the library.</li>
+
+ <li><em>Example 2.</em> If a vendor defines a non-AOSP library named
+ <code>libfoo.so</code>, then <code>libfoo.so</code> will be a DX-Lib.</li>
+ </ul>
+ </li>
</ul>
<p>Depending on the functionalities used by a module, modules can be classified
into <strong>UA-Module</strong> and <strong>UX-Module</strong>.</p>
+
<ul>
-<li><em>Using-only-AOSP Modules (UA-Module)</em> only use AOSP functionalities
-in their implementations. They do not rely on any non-AOSP extensions.
- <ul>
- <li><em>Example 1.</em> An intact unmodified AOSP library is an UA-Module.</li>
- <li><em>Example 2.</em> If a modified shared library <code>libjpeg.so</code>
- only relies on other AOSP APIs, then it will be an UA-Module.</li>
- </ul>
-</li>
-<li><em>Using-Extension Modules (UX-Module)</em> rely on some non-AOSP
-functionalities in their implementations.
- <ul>
- <li><em>Example 1.</em> If a modified <code>libjpeg.so</code> relies on another
- non-AOSP library named <code>libjpeg_turbo2.so</code>, then the modified
- <code>libjpeg.so</code> will be an UX-Module.</li>
- <li><em>Example 2.</em> If a vendor adds a new function to their modified
- <code>libexif.so</code> and their modified <code>libjpeg.so</code> uses the
- newly added function from <code>libexif.so</code>, then their modified
- <code>libjpeg.so</code> will be an UX-Module.</li>
- </ul>
-</li>
+ <li>
+ <em>Using-only-AOSP Modules (UA-Module)</em> only use AOSP functionalities
+ in their implementations. They do not rely on any non-AOSP extensions.
+
+ <ul>
+ <li><em>Example 1.</em> An intact unmodified AOSP library is an
+ UA-Module.</li>
+
+ <li><em>Example 2.</em> If a modified shared library <code>libjpeg.so</code>
+ only relies on other AOSP APIs, then it will be an UA-Module.</li>
+ </ul>
+ </li>
+
+ <li>
+ <em>Using-Extension Modules (UX-Module)</em> rely on some non-AOSP
+ functionalities in their implementations.
+
+ <ul>
+ <li><em>Example 1.</em> If a modified <code>libjpeg.so</code> relies on
+ another non-AOSP library named <code>libjpeg_turbo2.so</code>, then the
+ modified <code>libjpeg.so</code> will be an UX-Module.</li>
+
+ <li><em>Example 2.</em> If a vendor adds a new function to their modified
+ <code>libexif.so</code> and their modified <code>libjpeg.so</code> uses the
+ newly added function from <code>libexif.so</code>, then their modified
+ <code>libjpeg.so</code> will be an UX-Module.</li>
+ </ul>
+ </li>
</ul>
<p>Definitions and usages are independent from each other:</p>
+
<table>
- <tr>
- <td rowspan="2" colspan="2" class="columns"></td>
- <th colspan="2">Used Functionalities</th>
- </tr>
- <tr>
- <td>Only AOSP (UA)</td>
- <td>Extended (UX)</td>
- </tr>
- <tr>
- <th rowspan="2">Defined Functionalities</th>
- <td>Only AOSP (DA)</td>
- <td>DAUA</td>
- <td>DAUX</td>
- </tr>
- <tr>
- <td>Extended (DX)</td>
- <td>DXUA</td>
- <td>DXUX</td>
- </tr>
+ <tr>
+ <td rowspan="2" colspan="2" class="columns"></td>
+ <th colspan="2">Used Functionalities</th>
+ </tr>
+ <tr>
+ <td>Only AOSP (UA)</td>
+ <td>Extended (UX)</td>
+ </tr>
+ <tr>
+ <th rowspan="2">Defined Functionalities</th>
+ <td>Only AOSP (DA)</td>
+ <td>DAUA</td>
+ <td>DAUX</td>
+ </tr>
+ <tr>
+ <td>Extended (DX)</td>
+ <td>DXUA</td>
+ <td>DXUX</td>
+ </tr>
</table>
+
+
+
+
<h2 id="vndk-extension-mechanism">VNDK extension mechanism</h2>
-<p>
-Vendor modules that rely on extended functionalities won't work because the
+<p>Vendor modules that rely on extended functionalities won't work because the
AOSP library with the same name does not have the extended functionality. If
vendor modules directly or indirectly depend on extended functionalities,
vendors should copy DAUX, DXUA, and DXUX shared libraries to the vendor
partition (vendor processes always look for shared libraries in the vendor
partition first). However, LL-NDK libraries must not be copied, so vendor
modules must not rely on the extended functionalities defined by the modified
-LL-NDK libraries.
-</p>
-<p>
-DAUA shared libraries can remain on the system partition if the corresponding
-AOSP library can provide the same functionality and vendor modules continue to
-work when the system partition is overwritten by an Generic System Image (GSI).
-</p>
-<p>
-Drop-in replacement is important because the unmodified VNDK libraries in the
-GSI will link with the modified shared libraries on name
-collision. If the AOSP libraries are modified in an API/ABI incompatible
-manner, the AOSP libraries in the GSI might fail to link
-or result in undefined behaviors.
-</p>
+LL-NDK libraries.</p>
+
+<p>DAUA shared libraries can remain on the system partition if the
+corresponding AOSP library can provide the same functionality and vendor
+modules continue to work when the system partition is overwritten by an Generic
+System Image (GSI).</p>
+
+<p>Drop-in replacement is important because the unmodified VNDK libraries in
+the GSI will link with the modified shared libraries on name collision. If the
+AOSP libraries are modified in an API/ABI incompatible manner, the AOSP
+libraries in the GSI might fail to link or result in undefined behaviors.</p>
</body>
</html>
diff --git a/en/devices/architecture/vndk/index.html b/en/devices/architecture/vndk/index.html
index 2070927..02722a6 100644
--- a/en/devices/architecture/vndk/index.html
+++ b/en/devices/architecture/vndk/index.html
@@ -135,7 +135,8 @@
<code>libGLESv2.so</code>, <code>libGLESv3.so</code>,
<code>libandroid_net.so</code>, <code>libc.so</code>, <code>libdl.so</code>,
<code>liblog.so</code>, <code>libm.so</code>, <code>libnativewindow.so</code>,
-<code>libsync.so</code>, and <code>libvndksupport.so</code>,
+<code>libneuralnetworks.so</code>, <code>libsync.so</code>,
+<code>libvndksupport.so</code>, and <code>libvulkan.so</code>,
</li>
</ul>
</li>
@@ -193,7 +194,6 @@
</p>
<ul>
-<li><code>android.hardware.graphics.allocator@2.0.so</code></li>
<li><code>android.hardware.graphics.common@1.0.so</code></li>
<li><code>android.hardware.graphics.mapper@2.0.so</code></li>
<li><code>android.hardware.renderscript@1.0.so</code> (Renderscript)</li>
@@ -211,9 +211,11 @@
</ul>
<p>
-The following <em>VNDK-SP dependencies (VNDK-SP-Indirect)</em> are invisible to
+The following <em>VNDK-SP dependencies (VNDK-SP-Private)</em> are invisible to
<em>SP-HALs</em>:
-</p><ul>
+</p>
+
+<ul>
<li><code>libRSCpuRef.so</code> (Renderscript)</li>
<li><code>libRSDriver.so</code> (Renderscript)</li>
<li><code>libbacktrace.so</code></li>
@@ -223,13 +225,6 @@
<li><code>libunwind.so</code></li>
</ul>
-<p>The following <em>private VNDK-SP dependency (VNDK-SP-Indirect-Private)</em>
-is invisible to all vendor modules:</p>
-
-<ul>
-<li><code>libcompiler_rt.so</code> (Renderscript)</li>
-</ul>
-
<p>The following are <em>framework-only libraries with RS exceptions
(FWK-ONLY-RS)</em>:</p>
<ul>
@@ -276,10 +271,97 @@
generalizations) and released by Google.</aside>
+<h2 id="vndk-versioning">VNDK versioning</h2>
+
+<p>In Android P, VNDK shared libraries are versioned:</p>
+
+<ul>
+ <li>The <code>ro.vndk.version</code> system property is automatically added to
+ <code>/vendor/default.prop</code>.</li>
+
+ <li>VNDK shared libraries are installed to
+ <code>/system/lib[64]/vndk-${ro.vndk.version}</code>.</li>
+
+ <li>VNDK-SP shared libraries are installed to
+ <code>/system/lib[64]/vndk-sp-${ro.vndk.version}</code>.</li>
+
+ <li>The dynamic linker configuration file is installed to
+ <code>/system/etc/ld.config.${ro.vndk.version}.txt</code>.</li>
+</ul>
+
+<p>The value of <code>ro.vndk.version</code> is chosen by the algorithm
+below:</p>
+
+<ul>
+ <li>If <code>BOARD_VNDK_VERSION</code> is <em>not equal to</em>
+ <code>current</code>, use <code>BOARD_VNDK_VERSION</code>.</li>
+
+ <li>If <code>BOARD_VNDK_VERSION</code> is <em>equal to</em>
+ <code>current</code>:</li>
+
+ <ul>
+ <li>If <code>PLATFORM_VERSION_CODENAME</code> is <code>REL</code>, use
+ <code>PLATFORM_SDK_VERSION</code> (e.g. <code>28</code>).</li>
+
+ <li>Otherwise, use <code>PLATFORM_VERSION_CODENAME</code> (e.g.
+ <code>P</code>).</li>
+ </ul>
+</ul>
+
+<h3 id="upgrading-devices">Upgrading devices</h3>
+
+<p>If an Android 8.x device disabled VNDK run-time enforcement (i.e. either
+built without <code>BOARD_VNDK_VERSION</code> or built with
+<code>BOARD_VNDK_RUNTIME_DISABLE</code>), it may add
+<code>PRODUCT_USE_VNDK_OVERRIDE := false</code> to <code>BoardConfig.mk</code>
+while upgrading to Android P.</p>
+
+<p>If <code>PRODUCT_USE_VNDK_OVERRIDE</code> is <code>false</code>, the
+<code>ro.vndk.lite</code> property will be automatically added to
+<code>/vendor/default.prop</code> and its value will be <code>true</code>.
+Consequently, the dynamic linker will load the linker namespace configuration
+from <code>/system/etc/ld.config.vndk_lite.txt</code>, which isolates only
+SP-HAL and VNDK-SP.</p>
+
+<p>If an Android 7.0 (or earlier) device would like to upgrade to Android P,
+add <code>PRODUCT_TREBLE_LINKER_NAMESPACES_OVERRIDE := false</code> to
+<code>BoardConfig.mk</code>.</p>
+
+<h3 id="vendor-test-suite">Vendor Test Suite (VTS)</h3>
+
+<p>Android P Vendor Test Suite (VTS) mandates a non-empty
+<code>ro.vndk.version</code> property. Both newly-launched devices and
+upgrading devices must define <code>ro.vndk.version</code>. Some VNDK test
+cases (e.g. <code>VtsVndkFilesTest</code> and
+<code>VtsVndkDependencyTest</code>) rely on the <code>ro.vndk.version</code>
+property to load the matching eligible VNDK libraries data sets.</p>
+
+<p>If the <code>ro.product.first_api_level</code> property is greater than 27,
+the <code>ro.vndk.lite</code> property must not be defined.
+<code>VtsTreblePlatformVersionTest</code> will fail if
+<code>ro.vndk.lite</code> is defined in a newly-launched Android P device.</p>
+
+
<h2 id="document-history">Document history</h2>
<p>This section tracks changes to VNDK documentation.</p>
+<h3 id="changes-p">Android P changes</h3>
+
+<ul>
+ <li>Add VNDK versioning section.</li>
+
+ <li>Add VTS section.</li>
+
+ <li>Some VNDK categories have been renamed:</li>
+ <ul>
+ <li>LL-NDK-Indirect has been renamed to LL-NDK-Private.</li>
+ <li>VNDK-Indirect has been renamed to VNDK-Private.</li>
+ <li>VNDK-SP-Indirect-Private has been renamed to VNDK-SP-Private.</li>
+ <li>VNDK-SP-Indirect has been removed.</li>
+ </ul>
+</ul>
+
<h3 id="changes-81">Android 8.1 changes</h3>
<ul>
diff --git a/en/devices/architecture/vndk/linker-namespace.html b/en/devices/architecture/vndk/linker-namespace.html
index e017676..040d844 100644
--- a/en/devices/architecture/vndk/linker-namespace.html
+++ b/en/devices/architecture/vndk/linker-namespace.html
@@ -25,12 +25,12 @@
<ul>
<li>SP-HAL shared libraries and their dependencies, including VNDK-SP
-libraries, are loaded into framework processes. There should be some mechanisms
-to prevent symbol conflicts.</li>
+ libraries, are loaded into framework processes. There should be some
+ mechanisms to prevent symbol conflicts.</li>
<li><code>dlopen()</code> and <code>android_dlopen_ext()</code> may introduce
-some run-time dependencies that are not visible at build-time and can be
-difficult to detect using static analysis.</li>
+ some run-time dependencies that are not visible at build-time and can be
+ difficult to detect using static analysis.</li>
</ul>
<p>These two challenges can be resolved by the <em>linker namespace</em>
@@ -45,11 +45,11 @@
hiding their implementation details within their linker namespaces.</p>
<p>For example, <code>/system/lib[64]/libcutils.so</code> and
-<code>/system/lib[64]/vndk-sp/libutils.so</code> are two shared libraries.
-These two libraries may have different symbols. They will be loaded into
-different linker namespaces so that framework modules can depend on
+<code>/system/lib[64]/vndk-sp-${VER}/libutils.so</code> are two shared
+libraries. These two libraries may have different symbols. They will be loaded
+into different linker namespaces so that framework modules can depend on
<code>/system/lib[64]/libcutils.so</code> and SP-HAL shared libraries can
-depend on <code>/system/lib[64]/vndk-sp/libcutils.so</code>.</p>
+depend on <code>/system/lib[64]/vndk-sp-${VER}/libcutils.so</code>.</p>
<p>On the other hand, <code>/system/lib[64]/libc.so</code> is an example of
public libraries that is exported by a linker namespace and imported into
@@ -60,16 +60,24 @@
mechanism encapsulates the implementation details while providing the public
interfaces.</p>
+
+
+
+
<h2 id="how-does-it-work">How does it work?</h2>
<p>The dynamic linker is responsible for loading the shared libraries specified
in <code>DT_NEEDED</code> entries or the shared libraries specified by the
argument of <code>dlopen()</code> or <code>android_dlopen_ext()</code>. In both
-cases, the dynamic linker will find out the linker namespace in which the
-caller resides in and try to load the dependencies into the same linker
-namespace. If the dynamic linker cannot load the shared library into the
-specified linker namespace, it will ask the linked linker namespace for
-exported shared libraries.</p>
+cases, the dynamic linker will find the linker namespace where the caller
+resides and try to load the dependencies into the same linker namespace. If
+the dynamic linker cannot load the shared library into the specified linker
+namespace, it will ask the <em>linked linker namespace</em> for exported shared
+libraries.</p>
+
+
+
+
<h2 id="configuration-file-format">Configuration file format</h2>
@@ -100,7 +108,7 @@
namespace.default.permitted.paths = /vendor/${LIB}:/system/${LIB}
</pre>
-<p>First, there are several <code>dir.${section}</code> properties in the
+<p>First, there are several <code>dir.${section}</code> properties at the
beginning of <code>ld.config.txt</code>:</p>
<pre class="prettyprint">
@@ -108,10 +116,10 @@
</pre>
<p>These properties decide which set of rules will be applied to the process.
-For example, If the <em>main executable</em> is in <code>/system/bin</code>,
-the rules in the <code>[system]</code> are applied. Similarly, if the
-<em>main executable</em> is in <code>/vendor/bin</code>, the rules in
-<code>[vendor]</code> are applied.</p>
+For example, if a <em>main executable</em> resides in <code>/system/bin</code>,
+the rules in the <code>[system]</code> section are applied. Similarly, if a
+<em>main executable</em> resides in <code>/vendor/bin</code>, the rules in the
+<code>[vendor]</code> section are applied.</p>
<p>Second, for each section, in addition to the <code>default</code> linker
namespace, <code>addition.namespaces</code> specifies the extra linker
@@ -134,6 +142,7 @@
namespace.${name}.isolated = true|false
namespace.${name}.links = namespace1,namespace2
namespace.${name}.link.${other}.shared_libs = lib1.so:lib2.so
+namespace.${name}.link.${other}.allow_all_shared_libs = true
namespace.${name}.visible = true|false
</pre>
@@ -170,12 +179,12 @@
<code>sphal</code> linker namespace links to the <code>default</code> linker
namespace.</p>
-<p><code>namespace.${name}.link.${other}.shared_libs</code> links two linker
-namespaces and specifies the shared library names (separated by colons) that
-may utilize the fallback link. If a shared library can't be loaded into the
-<code>${name}</code> linker namespace and its name is in
-<code>namespace.${name}.link.${other}.shared_libs</code>, the dynamic
-linker will try to import the library from the <code>${other}</code> linker
+<p><code>namespace.${name}.link.${other}.shared_libs</code> specifies the
+shared library names (separated by colons) that may utilize the fallback link.
+If a shared library can't be loaded into the <code>${name}</code> linker
+namespace and its name is in
+<code>namespace.${name}.link.${other}.shared_libs</code>, the dynamic linker
+will try to import the library from the <code>${other}</code> linker
namespace.</p>
<p>In the example above, <code>namespace.sphal.link.default.shared_libs</code>
@@ -187,6 +196,12 @@
fallback link and find the <code>libc.so</code> exported by the
<code>default</code> linker namespace.</p>
+<p>If <code>namespace.${name}.link.${other}.allow_all_shared_libs</code> is
+<code>true</code>, all shared library names may utilize the fallback link. If
+a shared library can't be loaded into the <code>${name}</code> linker
+namespace, the dynamic linker will try to import the library from the
+<code>${other}</code> linker namespace.</p>
+
<p>If <code>namespace.${name}.visible</code> is <code>true</code>, the
program will be able to obtain a linker namespace handle, which can be passed
to <code>android_dlopen_ext()</code> later.</p>
@@ -196,51 +211,67 @@
explicitly ask the dynamic linker to load a shared library in the
<code>sphal</code> linker namespace.</p>
+
+
+
+
<h2 id="linker-namespace-isolation">Linker namespace isolation</h2>
<p>There are three configurations in
-<code>android-src/system/core/rootdir/etc</code>. Depending on the value of
-<code>PRODUCT_FULL_TREBLE</code>, <code>BOARD_VNDK_VERSION</code>, and
-<code>BOARD_VNDK_RUNTIME_DISABLE</code> in <code>BoardConfig.mk</code>,
+<code>${android-src}/system/core/rootdir/etc</code>. Depending on the value of
+<code>PRODUCT_TREBLE_LINKER_NAMESPACES</code>, <code>BOARD_VNDK_VERSION</code>,
+and <code>BOARD_VNDK_RUNTIME_DISABLE</code> in <code>BoardConfig.mk</code>,
different configurations will be selected:</p>
<table>
<tr>
- <th><code>PRODUCT_FULL_TREBLE</code></th>
- <th><code>BOARD_VNDK_VERSION</code> / <code>BOARD_VNDK_RUNTIME_DISABLE</code></th>
+ <th><code>PRODUCT_TREBLE_</code><br/><code>LINKER_NAMESPACES</code></th>
+ <th><code>BOARD_VNDK_</code><br/><code>VERSION</code></th>
+ <th><code>BOARD_VNDK_</code><br/><code>RUNTIME_DISABLE</code></th>
<th>Selected configuration</th>
+ <th>VTS Requirement</th>
+ </tr>
+
+ <tr>
+ <td rowspan="3"><code>true</code></td>
+ <td rowspan="2"><code>current</code></td>
+ <td><em>empty</em></td>
+ <td><code>ld.config.txt</code></td>
+ <td>Mandatory for devices launched with Android P.</td>
+ </tr>
+
+ <tr>
+ <td><code>true</code></td>
+ <td rowspan="2"><code>ld.config.vndk_lite.txt</code></td>
+ <td rowspan="2">Mandatory for devices launched with Android 8.x.</td>
+ </tr>
+
+ <tr>
+ <td><em>empty</em></td>
+ <td><em>any</em></td>
</tr>
<tr>
<td><code>false</code></td>
<td><em>any</em></td>
+ <td><em>any</em></td>
<td><code>ld.config.legacy.txt</code></td>
- </tr>
-
- <tr>
- <td rowspan="2"><code>true</code></td>
- <td><code>current</code> and <em>empty</em></td>
- <td><code>ld.config.txt.in</code></td>
- </tr>
-
- <tr>
- <td><em>empty</em> or <code>true</code></td>
- <td><code>ld.config.txt</code></td>
+ <td>For non-Treble devices</td>
</tr>
</table>
-<p><code>android-src/system/core/rootdir/etc/ld.config.txt</code> isolates
-SP-HAL and VNDK-SP shared libraries. In Android 8.0 and higher, this must be the
-dynamic linker configuration when <code>PRODUCT_FULL_TREBLE</code> is
-<code>true</code>.</p>
+<p><code>${android-src}/system/core/rootdir/etc/ld.config.vndk_lite.txt</code>
+isolates SP-HAL and VNDK-SP shared libraries. In Android 8.0 and higher, this
+must be the configuration file for dynamic linker when
+<code>PRODUCT_TREBLE_LINKER_NAMESPACES</code> is <code>true</code>.</p>
-<p><code>android-src/system/core/rootdir/etc/ld.config.txt.in</code> isolates
+<p><code>${android-src}/system/core/rootdir/etc/ld.config.txt</code> isolates
SP-HAL and VNDK-SP shared libraries as well. In addition,
-<code>ld.config.txt.in</code> also provides the full dynamic linker isolation.
+<code>ld.config.txt</code> also provides the full dynamic linker isolation.
It makes sure that modules in the system partition won't depend on the shared
libraries in the vendor partitions and vice versa.</p>
-<p>In Android 8.1, <code>ld.config.txt.in</code> is the default configuration
+<p>In Android 8.1, <code>ld.config.txt</code> is the default configuration file
and it is highly recommended to enable full dynamic linker isolation. However,
if there are too many dependencies to be cleaned up in Android 8.1, you may add
<code>BOARD_VNDK_RUNTIME_DISABLE</code> to <code>BoardConfig.mk</code>:</p>
@@ -250,308 +281,55 @@
</pre>
<p>If <code>BOARD_VNDK_RUNTIME_DISABLE</code> is <code>true</code>,
-<code>android-src/system/core/rootdir/etc/ld.config.txt</code> will be
-installed.</p>
+<code>${android-src}/system/core/rootdir/etc/ld.config.vndk_lite.txt</code>
+will be installed.</p>
+
<h3 id="ld.config.txt">ld.config.txt</h3>
-<p>As of Android 8.0, the dynamic linker is configured to isolate SP-HAL and
-VNDK-SP shared libraries such that their symbols do not conflict with other
-framework shared libraries. The relationship between the linker namespaces is
-shown below:</p>
-
-<img src="../images/treble_vndk_linker_namespace1.png" alt="Linker namespace
-graph described in ld.config.txt" />
- <figcaption><strong>Figure 2.</strong> Linker namespace isolation
- (<code>ld.config.txt</code>).</figcaption>
-
-<p><em>LL-NDK</em> and <em>VNDK-SP</em> stand for following shared libraries:
-</p>
-
-<ul>
- <li>
- <em>LL-NDK</em>
-
- <ul>
- <li><code>libEGL.so</code></li>
- <li><code>libGLESv1_CM.so</code></li>
- <li><code>libGLESv2.so</code></li>
- <li><code>libc.so</code></li>
- <li><code>libdl.so</code></li>
- <li><code>liblog.so</code></li>
- <li><code>libm.so</code></li>
- <li><code>libnativewindow.so</code></li>
- <li><code>libstdc++.so</code> (Not in <code>ld.config.txt.in</code>)</li>
- <li><code>libsync.so</code></li>
- <li><code>libvndksupport.so</code></li>
- <li><code>libz.so</code> (Moved to <em>VNDK-SP</em> in
- <code>ld.config.txt.in</code>)</li>
- </ul>
- </li>
-
- <li>
- <em>VNDK-SP</em>
-
- <ul>
- <li><code>android.hardware.graphics.common@1.0.so</code></li>
- <li><code>android.hardware.graphics.allocator@2.0.so</code></li>
- <li><code>android.hardware.graphics.mapper@2.0.so</code></li>
- <li><code>android.hardware.renderscript@1.0.so</code></li>
- <li><code>android.hidl.memory@1.0.so</code></li>
- <li><code>libbase.so</code></li>
- <li><code>libc++.so</code></li>
- <li><code>libcutils.so</code></li>
- <li><code>libhardware.so</code></li>
- <li><code>libhidlbase.so</code></li>
- <li><code>libhidlmemory.so</code></li>
- <li><code>libhidltransport.so</code></li>
- <li><code>libhwbinder.so</code></li>
- <li><code>libion.so</code></li>
- <li><code>libutils.so</code></li>
- </ul>
- </li>
-</ul>
-
-<p>The table below presents the namespaces configuration for framework
-processes, which is excerpted from the <code>[system]</code> section in
-<code>ld.config.txt</code>:</p>
-
-<table>
- <tr>
- <th>Namespace</th>
- <th>Property</th>
- <th>Value</th>
- </tr>
-
- <tr>
- <td rowspan="3"><code>default</code></td>
- <td><code>search.paths</code></td>
- <td>
- <code>/system/${LIB}</code><br/>
- <code>/vendor/${LIB}</code>
- </td>
- </tr>
-
- <tr>
- <td><code>permitted.paths</code></td>
- <td>
- <code>/system/${LIB}</code><br/>
- <code>/vendor/${LIB}</code>
- </td>
- </tr>
-
- <tr>
- <td><code>isolated</code></td>
- <td><code>false</code></td>
- </tr>
-
- <tr>
- <td rowspan="8"><code>sphal</code></td>
- <td><code>search.paths</code></td>
- <td>
- <code>/vendor/${LIB}/egl</code><br/>
- <code>/vendor/${LIB}/hw</code><br/>
- <code>/vendor/${LIB}</code>
- </td>
- </tr>
-
- <tr>
- <td><code>permitted.paths</code></td>
- <td>
- <code>/vendor/${LIB}</code><br/>
- <code>/system/${LIB}/vndk-sp/hw</code> (Android 8.1)
- </td>
- </tr>
-
- <tr>
- <td><code>isolated</code></td>
- <td><code>true</code></td>
- </tr>
-
- <tr>
- <td><code>visible</code></td>
- <td><code>true</code></td>
- </tr>
-
- <tr>
- <td><code>links</code></td>
- <td><code>default,vndk,rs</code></td>
- </tr>
- <tr>
- <td><code>link.default.shared_libs</code></td>
- <td><em>LL-NDK</em></td>
- </tr>
- <tr>
- <td><code>link.vndk.shared_libs</code></td>
- <td><em>VNDK-SP</em></td>
- </tr>
- <tr>
- <td><code>link.rs.shared_libs</code></td>
- <td><code>libRS_internal.so</code></td>
- </tr>
-
- <tr>
- <td rowspan="6"><code>vndk</code> (For VNDK-SP)</td>
- <td><code>search.paths</code></td>
- <td>
- <code>/vendor/${LIB}/vndk-sp</code><br/>
- <code>/system/${LIB}/vndk-sp</code><br/>
- <code>/vendor/${LIB}</code>
- </td>
- </tr>
-
- <tr>
- <td><code>permitted.paths</code></td>
- <td>
- <code>/vendor/${LIB}/egl</code><br/>
- <code>/vendor/${LIB}/hw</code>
- </td>
- </tr>
-
- <tr>
- <td><code>isolated</code></td>
- <td><code>true</code></td>
- </tr>
-
- <tr>
- <td><code>visible</code></td>
- <td><code>true</code></td>
- </tr>
-
- <tr>
- <td><code>links</code></td>
- <td><code>default</code></td>
- </tr>
-
- <tr>
- <td><code>link.default.shared_libs</code></td>
- <td><em>LL-NDK</em></td>
- </tr>
-
- <tr>
- <td rowspan="7"><code>rs</code> (For Renderscript)</td>
- <td><code>search.paths</code></td>
- <td>
- <code>/vendor/${LIB}/vndk-sp</code><br/>
- <code>/system/${LIB}/vndk-sp</code><br/>
- <code>/vendor/${LIB}</code>
- </td>
- </tr>
-
- <tr>
- <td><code>permitted.paths</code></td>
- <td>
- <code>/vendor/${LIB}</code><br/>
- <code>/data</code> (For compiled RS kernel)
- </td>
- </tr>
-
- <tr>
- <td><code>isolated</code></td>
- <td><code>true</code></td>
- </tr>
-
- <tr>
- <td><code>visible</code></td>
- <td><code>true</code></td>
- </tr>
-
- <tr>
- <td><code>links</code></td>
- <td><code>default,vndk</code></td>
- </tr>
-
- <tr>
- <td><code>link.default.shared_libs</code></td>
- <td>
- <em>LL-NDK</em><br/>
- <code>libmediandk.so</code><br/>
- <code>libft2.so</code>
- </td>
- </tr>
-
- <tr>
- <td><code>link.vndk.shared_libs</code></td>
- <td><em>VNDK-SP</em></td>
- </tr>
-</table>
-
-<p>The table below presents the namespaces configuration for vendor processes,
-which is excerpted from the <code>[vendor]</code> section in
-<code>ld.config.txt</code>:</p>
-
-<table>
- <tr>
- <th>Namespace</th>
- <th>Property</th>
- <th>Value</th>
- </tr>
-
- <tr>
- <td rowspan="2"><code>default</code></td>
- <td><code>search.paths</code></td>
- <td>
- <code>/vendor/${LIB}</code><br/>
- <code>/vendor/${LIB}/vndk-sp</code><br/>
- <code>/system/${LIB}/vndk-sp</code><br/>
- <code>/system/${LIB}</code> (Deprecated)
- </td>
- </tr>
-
- <tr>
- <td><code>isolated</code></td>
- <td><code>false</code></td>
- </tr>
-</table>
-
-<p>More details can be found in
-<code>android-src/system/core/rootdir/etc/ld.config.txt</code>.</p>
-
-
-<h3 id="ld.config.txt.in">ld.config.txt.in</h3>
-
-<p><code>ld.config.txt.in</code> isolates the shared library dependencies
+<p><code>ld.config.txt</code> isolates the shared library dependencies
between the system partition and vendor partitions. Compared to
<code>ld.config.txt</code> mentioned in previous subsection, the differences
are outlined as following items:</p>
<ul>
<li>
- Framework Processes
+ <p>Framework Processes</p>
<ul>
- <li>The <code>default</code> namespace is isolated. A shared library can be
- loaded into the <code>default</code> namespace only if it is in a directory
- specified in the search paths or under a directory specified in the
- permitted paths.</li>
+ <li>Four namespaces (<code>default</code>, <code>vndk</code>,
+ <code>sphal</code>, and <code>rs</code>) are created.</li>
- <li>The permitted paths of the <code>default</code> namespace have been
- changed to a limited set (<code>/vendor/lib[64]</code>,
- <code>/system/lib[64]/vndk</code>, and <code>/system/lib[64]/vndk-sp</code>
- have been excluded).</li>
+ <li>All namespaces are isolated.</li>
+
+ <li>System shared libraries are loaded into the <code>default</code>
+ namespace.</li>
+
+ <li>SP-HALs are loaded into the <code>sphal</code> namespace.</li>
+
+ <li>VNDK-SP shared libraries loaded into the <code>vndk</code>
+ namespace.</li>
</ul>
</li>
<li>
- Vendor Processes
+ <p>Vendor Processes</p>
<ul>
- <li>Two namespaces (<code>default</code> and <code>system</code>) are
- created.</li>
+ <li>Three namespaces (<code>default</code>, <code>vndk</code>, and
+ <code>system</code>) are created.</li>
- <li>The <code>default</code> namespace is isolated. A shared library can be
- loaded into the default namespace only if it is in a directory specified in
- the search paths or under a directory specified in the permitted
- paths.</li>
+ <li>The <code>default</code> namespace is isolated.</li>
- <li>The permitted paths of the <code>default</code> namespace are
- <code>/vendor</code>, <code>/system/lib[64]/vndk</code>, and
- <code>/system/lib[64]/vndk-sp</code>.</li>
+ <li>Vendor shared libraries are loaded into the <code>default</code>
+ namespace.</li>
- <li>The <code>default</code> namespace and <code>system</code> namespace are
- linked. The <code>default</code> namespace may link to LL-NDK libraries
- loaded in the <code>system</code> namespace.</li>
+ <li>VNDK and VNDK-SP shared libraries are loaded into the <code>vndk</code>
+ namespace.</li>
+
+ <li>LL-NDK and their dependencies are loaded into the <code>system</code>
+ namespace.</li>
</ul>
</li>
</ul>
@@ -559,9 +337,12 @@
<p>The relationship between the linker namespaces is depicted in the figure
below:</p>
-<img src="../images/treble_vndk_linker_namespace2.png" alt="Linker namespace graph described in ld.config.txt.in" />
- <figcaption><strong>Figure 2.</strong> Linker namespace isolation
- (<code>ld.config.txt.in</code>).</figcaption>
+<img src="../images/treble_vndk_linker_namespace3.png"
+ alt="Linker namespace graph described in ld.config.txt" />
+<figcaption>
+ <strong>Figure 1.</strong> Linker namespace isolation
+ (<code>ld.config.txt</code>)
+</figcaption>
<p>In the graph above, <em>LL-NDK</em> and <em>VNDK-SP</em> stand for following
@@ -582,8 +363,10 @@
<li><code>liblog.so</code></li>
<li><code>libm.so</code></li>
<li><code>libnativewindow.so</code></li>
+ <li><code>libneuralnetworks.so</code></li>
<li><code>libsync.so</code></li>
<li><code>libvndksupport.so</code></li>
+ <li><code>libvulkan.so</code></li>
</ul>
</li>
@@ -592,7 +375,6 @@
<ul>
<li><code>android.hardware.graphics.common@1.0.so</code></li>
- <li><code>android.hardware.graphics.allocator@2.0.so</code></li>
<li><code>android.hardware.graphics.mapper@2.0.so</code></li>
<li><code>android.hardware.renderscript@1.0.so</code></li>
<li><code>android.hidl.memory@1.0.so</code></li>
@@ -617,7 +399,7 @@
<p>The table below presents the namespaces configuration for framework
processes, which is excerpted from the <code>[system]</code> section in
-<code>ld.config.txt.in</code>:</p>
+<code>ld.config.txt</code>:</p>
<table>
<tr>
@@ -629,20 +411,30 @@
<tr>
<td rowspan="3"><code>default</code></td>
<td><code>search.paths</code></td>
- <td><code>/system/${LIB}</code></td>
+ <td>
+ <code>/system/${LIB}</code><br/>
+ <code>/product/${LIB}</code>
+ </td>
</tr>
<tr>
<td><code>permitted.paths</code></td>
<td>
<code>/system/${LIB}/drm</code><br/>
+ <code>/system/${LIB}/extractors</code><br/>
<code>/system/${LIB}/hw</code><br/>
+ <code>/product/${LIB}</code><br/>
<code>/system/framework</code><br/>
<code>/system/app</code><br/>
<code>/system/priv-app</code><br/>
<code>/vendor/app</code><br/>
- <code>/vendor/framework</code><br/>
+ <code>/vendor/priv-app</code><br/>
<code>/oem/app</code><br/>
+ <code>/odm/priv-app</code><br/>
+ <code>/oem/app</code><br/>
+ <code>/product/framework</code><br/>
+ <code>/product/app</code><br/>
+ <code>/product/priv-app</code><br/>
<code>/data</code><br/>
<code>/mnt/expand
</td>
@@ -657,8 +449,7 @@
<td rowspan="8"><code>sphal</code></td>
<td><code>search.paths</code></td>
<td>
- <code>/vendor/${LIB}/egl</code><br/>
- <code>/vendor/${LIB}/hw</code><br/>
+ <code>/odm/${LIB}</code><br/>
<code>/vendor/${LIB}</code>
</td>
</tr>
@@ -666,8 +457,8 @@
<tr>
<td><code>permitted.paths</code></td>
<td>
- <code>/vendor/${LIB}</code><br/>
- <code>/system/${LIB}/vndk-sp/hw</code>
+ <code>/odm/${LIB}</code><br/>
+ <code>/vendor/${LIB}</code>
</td>
</tr>
@@ -702,19 +493,23 @@
</tr>
<tr>
- <td rowspan="6"><code>vndk</code> (For VNDK-SP)</td>
+ <td rowspan="7"><code>vndk</code> (For VNDK-SP)</td>
<td><code>search.paths</code></td>
<td>
+ <code>/odm/${LIB}/vndk-sp</code><br/>
<code>/vendor/${LIB}/vndk-sp</code><br/>
- <code>/system/${LIB}/vndk-sp</code>
+ <code>/system/${LIB}/vndk-sp-${VER}</code>
</td>
</tr>
<tr>
<td><code>permitted.paths</code></td>
<td>
+ <code>/odm/${LIB}/hw</code><br/>
+ <code>/odm/${LIB}/egl</code><br/>
+ <code>/vendor/${LIB}/hw</code><br/>
<code>/vendor/${LIB}/egl</code><br/>
- <code>/vendor/${LIB}/hw</code>
+ <code>/system/${LIB}/vndk-sp-${VER}/hw</code>
</td>
</tr>
@@ -730,7 +525,7 @@
<tr>
<td><code>links</code></td>
- <td><code>default</code></td>
+ <td><code>default</code>, <code>sphal</code></td>
</tr>
<tr>
@@ -739,11 +534,18 @@
</tr>
<tr>
+ <td><code>link.default.allow_all_shared_libs</code></td>
+ <td><code>true</code></td>
+ </tr>
+
+ <tr>
<td rowspan="7"><code>rs</code> (For Renderscript)</td>
<td><code>search.paths</code></td>
<td>
+ <code>/odm/${LIB}/vndk-sp</code><br/>
<code>/vendor/${LIB}/vndk-sp</code><br/>
- <code>/system/${LIB}/vndk-sp</code><br/>
+ <code>/system/${LIB}/vndk-sp-${VER}</code><br/>
+ <code>/odm/${LIB}</code><br/>
<code>/vendor/${LIB}</code>
</td>
</tr>
@@ -751,6 +553,7 @@
<tr>
<td><code>permitted.paths</code></td>
<td>
+ <code>/odm/${LIB}</code><br/>
<code>/vendor/${LIB}</code><br/>
<code>/data</code> (For compiled RS kernel)
</td>
@@ -788,7 +591,7 @@
<p>The table below presents the namespaces configuration for vendor processes,
which is excerpted from the <code>[vendor]</code> section in
-<code>ld.config.txt.in</code>:</p>
+<code>ld.config.txt</code>:</p>
<table>
<tr>
@@ -798,25 +601,57 @@
</tr>
<tr>
- <td rowspan="5"><code>default</code></td>
+ <td rowspan="7"><code>default</code></td>
<td><code>search.paths</code></td>
<td>
- <code>/vendor/${LIB}/hw</code><br/>
- <code>/vendor/${LIB}/egl</code><br/>
- <code>/vendor/${LIB}</code><br/>
- <code>/vendor/${LIB}/vndk</code><br/>
- <code>/system/${LIB}/vndk</code><br/>
- <code>/vendor/${LIB}/vndk-sp</code><br/>
- <code>/system/${LIB}/vndk-sp</code>
+ <code>/odm/${LIB}</code><br/>
+ <code>/vendor/${LIB}</code>
</td>
</tr>
<tr>
<td><code>permitted.paths</code></td>
<td>
+ <code>/odm</code><br/>
<code>/vendor</code><br/>
- <code>/system/${LIB}/vndk</code><br/>
- <code>/system/${LIB}/vndk-sp</code>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code>isolated</code></td>
+ <td><code>true</code></td>
+ </tr>
+
+ <tr>
+ <td><code>visible</code></td>
+ <td><code>true</code></td>
+ </tr>
+
+ <tr>
+ <td><code>links</code></td>
+ <td><code>system</code>, <code>vndk</code></td>
+ </tr>
+
+ <tr>
+ <td><code>link.system.shared_libs</code></td>
+ <td><em>LL-NDK</em></td>
+ </tr>
+
+ <tr>
+ <td><code>link.vndk.shared_libs</code></td>
+ <td><em>VNDK</em>, <em>VNDK-SP</em> (vendor available)</td>
+ </tr>
+
+ <tr>
+ <td rowspan="5"><code>vndk</code></td>
+ <td><code>search.paths</code></td>
+ <td>
+ <code>/odm/${LIB}/vndk</code><br/>
+ <code>/odm/${LIB}/vndk-sp</code><br/>
+ <code>/vendor/${LIB}/vndk</code><br/>
+ <code>/vendor/${LIB}/vndk-sp</code><br/>
+ <code>/system/${LIB}/vndk-${VER}</code><br/>
+ <code>/system/${LIB}/vndk-sp-${VER}</code>
</td>
</tr>
@@ -827,7 +662,7 @@
<tr>
<td><code>links</code></td>
- <td><code>system</code></td>
+ <td><code>system</code>, <code>default</code></td>
</tr>
<tr>
@@ -836,20 +671,339 @@
</tr>
<tr>
+ <td><code>link.default.allow_all_shared_libs</code></td>
+ <td><code>true</code></td>
+ </tr>
+
+ <tr>
<td rowspan="2"><code>system</code></td>
<td><code>search.paths</code></td>
<td><code>/system/${LIB}</code></td>
</tr>
<tr>
- <td><code>permitted.paths</code></td>
- <td><code>/system/${LIB}</code></td>
+ <td><code>isolated</code></td>
+ <td><code>false</code></td>
</tr>
</table>
<p>More details can be found in
-<code>android-src/system/core/rootdir/etc/ld.config.txt.in</code>.</p>
+<code>${android-src}/system/core/rootdir/etc/ld.config.txt</code>.</p>
+
+
+
+<h3 id="ld.config.vndk_lite.txt">ld.config.vndk_lite.txt</h3>
+
+<p>As of Android 8.0, the dynamic linker is configured to isolate SP-HAL and
+VNDK-SP shared libraries such that their symbols do not conflict with other
+framework shared libraries. The relationship between the linker namespaces is
+shown below:</p>
+
+<img src="../images/treble_vndk_linker_namespace1.png"
+ alt="Linker namespace graph described in ld.config.vndk_lite.txt" />
+<figcaption>
+ <strong>Figure 2.</strong> Linker namespace isolation
+ (<code>ld.config.vndk_lite.txt</code>)
+</figcaption>
+
+<p><em>LL-NDK</em> and <em>VNDK-SP</em> stand for following shared libraries:
+</p>
+
+<ul>
+ <li>
+ <em>LL-NDK</em>
+
+ <ul>
+ <li><code>libEGL.so</code></li>
+ <li><code>libGLESv1_CM.so</code></li>
+ <li><code>libGLESv2.so</code></li>
+ <li><code>libc.so</code></li>
+ <li><code>libdl.so</code></li>
+ <li><code>liblog.so</code></li>
+ <li><code>libm.so</code></li>
+ <li><code>libnativewindow.so</code></li>
+ <li><code>libstdc++.so</code> (Not in <code>ld.config.txt</code>)</li>
+ <li><code>libsync.so</code></li>
+ <li><code>libvndksupport.so</code></li>
+ <li><code>libz.so</code> (Moved to <em>VNDK-SP</em> in
+ <code>ld.config.txt</code>)</li>
+ </ul>
+ </li>
+
+ <li>
+ <em>VNDK-SP</em>
+
+ <ul>
+ <li><code>android.hardware.graphics.common@1.0.so</code></li>
+ <li><code>android.hardware.graphics.mapper@2.0.so</code></li>
+ <li><code>android.hardware.renderscript@1.0.so</code></li>
+ <li><code>android.hidl.memory@1.0.so</code></li>
+ <li><code>libbase.so</code></li>
+ <li><code>libc++.so</code></li>
+ <li><code>libcutils.so</code></li>
+ <li><code>libhardware.so</code></li>
+ <li><code>libhidlbase.so</code></li>
+ <li><code>libhidlmemory.so</code></li>
+ <li><code>libhidltransport.so</code></li>
+ <li><code>libhwbinder.so</code></li>
+ <li><code>libion.so</code></li>
+ <li><code>libutils.so</code></li>
+ </ul>
+ </li>
+</ul>
+
+<p>The table below presents the namespaces configuration for framework
+processes, which is excerpted from the <code>[system]</code> section in
+<code>ld.config.vndk_lite.txt</code>:</p>
+
+<table>
+ <tr>
+ <th>Namespace</th>
+ <th>Property</th>
+ <th>Value</th>
+ </tr>
+
+ <tr>
+ <td rowspan="2"><code>default</code></td>
+ <td><code>search.paths</code></td>
+ <td>
+ <code>/system/${LIB}</code><br/>
+ <code>/odm/${LIB}</code><br/>
+ <code>/vendor/${LIB}</code><br/>
+ <code>/product/${LIB}</code>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code>isolated</code></td>
+ <td><code>false</code></td>
+ </tr>
+
+ <tr>
+ <td rowspan="8"><code>sphal</code></td>
+ <td><code>search.paths</code></td>
+ <td>
+ <code>/odm/${LIB}</code><br/>
+ <code>/vendor/${LIB}</code>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code>permitted.paths</code></td>
+ <td>
+ <code>/odm/${LIB}</code><br/>
+ <code>/vendor/${LIB}</code>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code>isolated</code></td>
+ <td><code>true</code></td>
+ </tr>
+
+ <tr>
+ <td><code>visible</code></td>
+ <td><code>true</code></td>
+ </tr>
+
+ <tr>
+ <td><code>links</code></td>
+ <td><code>default,vndk,rs</code></td>
+ </tr>
+ <tr>
+ <td><code>link.default.shared_libs</code></td>
+ <td><em>LL-NDK</em></td>
+ </tr>
+ <tr>
+ <td><code>link.vndk.shared_libs</code></td>
+ <td><em>VNDK-SP</em></td>
+ </tr>
+ <tr>
+ <td><code>link.rs.shared_libs</code></td>
+ <td><code>libRS_internal.so</code></td>
+ </tr>
+
+ <tr>
+ <td rowspan="6"><code>vndk</code> (For VNDK-SP)</td>
+ <td><code>search.paths</code></td>
+ <td>
+ <code>/odm/${LIB}/vndk-sp</code><br/>
+ <code>/vendor/${LIB}/vndk-sp</code><br/>
+ <code>/system/${LIB}/vndk-sp-${VER}</code>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code>permitted.paths</code></td>
+ <td>
+ <code>/odm/${LIB}/hw</code><br/>
+ <code>/odm/${LIB}/egl</code><br/>
+ <code>/vendor/${LIB}/hw</code><br/>
+ <code>/vendor/${LIB}/egl</code><br/>
+ <code>/system/${LIB}/vndk-sp-${VER}/hw</code><br/>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code>isolated</code></td>
+ <td><code>true</code></td>
+ </tr>
+
+ <tr>
+ <td><code>visible</code></td>
+ <td><code>true</code></td>
+ </tr>
+
+ <tr>
+ <td><code>links</code></td>
+ <td><code>default</code></td>
+ </tr>
+
+ <tr>
+ <td><code>link.default.shared_libs</code></td>
+ <td><em>LL-NDK</em></td>
+ </tr>
+
+ <tr>
+ <td rowspan="7"><code>rs</code> (For Renderscript)</td>
+ <td><code>search.paths</code></td>
+ <td>
+ <code>/odm/${LIB}/vndk-sp</code><br/>
+ <code>/vendor/${LIB}/vndk-sp</code><br/>
+ <code>/system/${LIB}/vndk-sp-${VER}</code><br/>
+ <code>/odm/${LIB}</code><br/>
+ <code>/vendor/${LIB}</code>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code>permitted.paths</code></td>
+ <td>
+ <code>/odm/${LIB}</code><br/>
+ <code>/vendor/${LIB}</code><br/>
+ <code>/data</code> (For compiled RS kernel)
+ </td>
+ </tr>
+
+ <tr>
+ <td><code>isolated</code></td>
+ <td><code>true</code></td>
+ </tr>
+
+ <tr>
+ <td><code>visible</code></td>
+ <td><code>true</code></td>
+ </tr>
+
+ <tr>
+ <td><code>links</code></td>
+ <td><code>default,vndk</code></td>
+ </tr>
+
+ <tr>
+ <td><code>link.default.shared_libs</code></td>
+ <td>
+ <em>LL-NDK</em><br/>
+ <code>libmediandk.so</code><br/>
+ <code>libft2.so</code>
+ </td>
+ </tr>
+
+ <tr>
+ <td><code>link.vndk.shared_libs</code></td>
+ <td><em>VNDK-SP</em></td>
+ </tr>
+</table>
+
+<p>The table below presents the namespaces configuration for vendor processes,
+which is excerpted from the <code>[vendor]</code> section in
+<code>ld.config.vndk_lite.txt</code>:</p>
+
+<table>
+ <tr>
+ <th>Namespace</th>
+ <th>Property</th>
+ <th>Value</th>
+ </tr>
+
+ <tr>
+ <td rowspan="2"><code>default</code></td>
+ <td><code>search.paths</code></td>
+ <td>
+ <code>/odm/${LIB}</code><br/>
+ <code>/odm/${LIB}/vndk</code><br/>
+ <code>/odm/${LIB}/vndk-sp</code><br/>
+ <code>/vendor/${LIB}</code><br/>
+ <code>/vendor/${LIB}/vndk</code><br/>
+ <code>/vendor/${LIB}/vndk-sp</code><br/>
+ <code>/system/${LIB}/vndk-${VER}</code><br/>
+ <code>/system/${LIB}/vndk-sp-${VER}</code><br/>
+ <code>/system/${LIB}</code> (Deprecated)<br/>
+ <code>/product/${LIB}</code> (Deprecated)
+ </td>
+ </tr>
+
+ <tr>
+ <td><code>isolated</code></td>
+ <td><code>false</code></td>
+ </tr>
+</table>
+
+<p>More details can be found in
+<code>${android-src}/system/core/rootdir/etc/ld.config.vndk_lite.txt</code>.</p>
+
+
+
+
+
+<h2 id="document-history">Document history</h2>
+
+<h3 id="changes-p">Android P changes</h3>
+
+<ul>
+ <li><p>In Android P, the <code>vndk</code> linker namespace is added to vendor
+ processes and VNDK shared libraries are isolated from the default linker
+ namespace.</p></li>
+
+ <li><p>Replace <code>PRODUCT_FULL_TREBLE</code> with more specific
+ <code>PRODUCT_TREBLE_LINKER_NAMESPACES</code>.</p></li>
+
+ <li>
+ <p>Android P changes the names of the following dynamic linker configuration
+ files:</p>
+
+ <table>
+ <tr>
+ <th>Android 8.x</th>
+ <th>Android P</th>
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td>ld.config.txt.in</td>
+ <td>ld.config.txt</td>
+ <td>For devices with runtime linker namespace isolation</td>
+ </tr>
+
+ <tr>
+ <td>ld.config.txt</td>
+ <td>ld.config.vndk_lite.txt</td>
+ <td>For devices with VNDK-SP linker namespace isolation</td>
+ </tr>
+
+ <tr>
+ <td>ld.config.legacy.txt</td>
+ <td>ld.config.legacy.txt</td>
+ <td>For legacy devices running Android 7.x and earlier</td>
+ </tr>
+ </table>
+ </li>
+
+ <li><p>Remove <code>android.hardware.graphics.allocator@2.0.so</code>.</p></li>
+
+ <li><p><code>product</code> and <code>odm</code> partitions are added.</p></li>
+</ul>
</body>
</html>
diff --git a/en/devices/architecture/vndk/snapshot-design.html b/en/devices/architecture/vndk/snapshot-design.html
new file mode 100644
index 0000000..1cee1f5
--- /dev/null
+++ b/en/devices/architecture/vndk/snapshot-design.html
@@ -0,0 +1,249 @@
+<html devsite>
+ <head>
+ <title>VNDK Snapshot Design</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ {% include "_versions.html" %}
+ <body>
+ <!--
+ Copyright 2018 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>
+ VNDK snapshots can be used by a system image to provide the correct VNDK
+ libraries to vendor images even when system and vendor images are built from
+ different versions of Android. Creating a VNDK snapshot requires capturing
+ VNDK libraries as a snapshot and marking them with a version number. The
+ vendor image may link with a specific VNDK version that provides required ABIs
+ for the modules in the vendor image. However, within the same VNDK version,
+ the VNDK libraries must be
+ <a href="/devices/architecture/hidl/hashing#abi-stability">ABI-stable</a>.
+</p>
+
+<p>
+ VNDK snapshot design includes methods for
+ <a href="/devices/architecture/vndk/snapshot-generate.html">generating the
+ pre-builds of a VNDK snapshot</a> from the current system image and
+ <a href="/devices/architecture/vndk/snapshot-generate.html#install-vndk-snapshot">installing
+ those pre-built libs</a> to the system partition of a newer Android version.
+</p>
+
+<h2 id=about-vndk-libs>About VNDK libraries</h2>
+
+<p>
+ <a href="/devices/architecture/index.html#hidl">HIDL-HALs</a>, introduced in
+ Android 8.0, enables separate upgrades for system and vendor partitions. VNDK
+ defines sets of libraries (VNDK-core, VNDK-SP and LL-NDK) that vendor code can
+ link with and blocks the vendors from using libraries that are not in a VNDK
+ set. As a result, the vendor image can be built and run if the proper VNDK
+ sets on the system image are provided to the vendor image.
+</p>
+
+<aside class="note"><strong>Note:</strong> For details on these libraries, refer
+ to <a href="/devices/architecture/vndk/index.html#concepts">VNDK concepts</a>.
+</aside>
+
+<h3 id="vndk-core">VNDK-core</h3>
+
+<p>
+ The VNDK-core set of libraries is installed in
+ <code>/system/lib[64]/vndk-${VER}</code> and is available
+ <strong>only</strong> for vendor processes with the API level equal to
+ <code>${VER}</code>. System processes may not use these libraries and must
+ instead use the libraries installed in <code>/system/lib[64]</code>. Because
+ of the strict namespace restriction for each process, the VNDK-core libraries
+ are safe from dual-loading.
+</p>
+
+<p>To include a library in VNDK-core, add the following to
+ <code>Android.bp</code>:
+</p>
+
+<pre class="prettyprint">
+vendor_available: true,
+vndk: {
+ enabled: true,
+},
+</pre>
+
+<aside class="note"><strong>Note:</strong> If a system process loads library
+ <code>foo.so</code> from <code>system/lib</code> and loads another
+ <code>foo.so</code> from <code>system/lib/vndk</code>, <code>foo.so</code> is
+ dual-loaded. Normally it is unsafe to load the same library twice in a
+ process.
+</aside>
+
+<h3 id="vndk-sp">VNDK-SP</h3>
+
+<p>
+ VNDK-SP libraries are installed in <code>/system/lib[64]/vndk-sp-${VER}</code>
+ and are available to vendor processes and system processes (through the SP-HAL
+ libraries installed in vendor partition). VNDK-SP libraries may be
+ dual-loaded.
+</p>
+
+<p>
+ To include a library in VNDK-SP, add the following to <code>Android.bp</code>:
+</p>
+
+<pre class="prettyprint">
+vendor_available: true,
+vndk: {
+ enabled: true,
+ support_system_process: true,
+},
+</pre>
+
+<h3 id="ll-ndk">LL-NDK</h3>
+
+<p>
+ LL-NDK libraries are installed in <code>/system/lib[64]</code>. Vendor modules
+ can use LL-NDK stub libraries to access pre-selected symbols of LL-NDK
+ libraries. LL-NDK libraries must be backward-compatible and ABI-stable to
+ enable old versions of vendor modules to use new versions of LL-NDK libraries.
+ Because of the ABI-stable characteristics of LL-NDK, the VNDK snapshot does
+ not need to include LL-NDK libraries for old vendor images.
+</p>
+
+<h2 id="about-vndk-snapshots">About VNDK snapshots</h2>
+
+<p>
+ Android 8.1 included <a href="/devices/architecture/vndk/build-system">VNDK
+ libraries built from the source code</a>. However, for later versions of
+ Android, each VNDK version must be captured as a snapshot and provided as a
+ pre-build to enabling linking to an older vendor image.
+</p>
+
+<p>
+ Starting in Android {{ androidPVersionNumber }}, new versions of Android will
+ include at least one snapshot of VNDK-core and VNDK-SP directories for older
+ versions in the Android source code. At build time, required snapshots will be
+ installed to <code>/system/lib[64]/vndk-${VER}</code> and
+ <code>/system/lib[64]/vndk-sp-${VER}</code> (directories that can be used by
+ the vendor partition), where <code>${VER}</code> is the string variable that
+ represents the version name of the VNDK snapshot.
+</p>
+
+<p>
+ As the VNDK snapshot libraries may differ for each VNDK version, the VNDK
+ snapshot also includes the linker namespace configurations, installed as
+ <code>etc/ld.config.${VER}.txt</code>,
+ <code>/etc/llndk.libraries.${VER}.txt</code>, and
+ <code>/etc/vndksp.libraries.${VER}.txt</code>.
+</p>
+
+<h3 id="example-upgrade-system-vendor">Example: Upgrading system and vendor
+images</h3>
+
+<p>
+ No snapshot required; build without additional configurations for VNDK
+ snapshots.
+</p>
+
+<h3 id="example-upgrade-system-only">Example: Upgrading system image only</h3>
+
+<p>
+ Must include the VNDK snapshot and linker namespace configuration files for
+ the vendor image in the system image. The linker namespace configuration files
+ are automatically configured to search for VNDK libraries in
+ <code>/system/lib[64]/vndk-${VER}</code> and
+ <code>/system/lib[64]/vndk-sp-${VER}</code>.
+</p>
+
+<img src="/devices/architecture/images/vndk_snapshot_system_only.png">
+<figcaption><strong>Figure 1.</strong> Upgrading system only</figcaption>
+
+<h3 id="example-upgrade-system-minor-vendor">Example: Upgrading system image,
+minor vendor image change</h3>
+
+<p>
+ Building a vendor image against a VNDK snapshot is not yet supported, so you
+ must build the vendor image separately with its original source code, then
+ upgrade the system image as described in the previous example.
+</p>
+
+<h2 id="vndk-snapshot-arch">VNDK snapshot architecture</h2>
+
+<p>
+ To make an Android {{ androidPVersionNumber }} system image compatible with an
+ Android 8.1 vendor image, the VNDK snapshot that matches the Android 8.1
+ vendor image must be provided with the Android {{ androidPVersionNumber }}
+ system image, as shown below:
+</p>
+
+<img src="/devices/architecture/images/vndk_snapshot_arch.png">
+<figcaption><strong>Figure 2.</strong> VNDK snapshot architecture</figcaption>
+
+<p>
+ The VNDK snapshot design includes the following methods:
+</p>
+
+<ul>
+ <li><strong>Generating a snapshot for VNDK-core and VNDK-SP
+ libraries</strong>. Android {{ androidPVersionNumber }} includes a script you
+ can use to make a snapshot of the current VNDK build. This script bundles all
+ libraries in <code>/system/lib[64]/vndk-28</code> and
+ <code>/system/lib[64]/vndk-sp-28</code> that were built with the current
+ source as a VNDK snapshot, where <code>28</code> is the VNDK version of
+ Android {{ androidPVersionNumber }}. The snapshot also includes the linker
+ namespace configuration files <code>/etc/ld.config.28.txt</code>,
+ <code>/etc/llndk.libraries.28.txt</code>, and
+ <code>/etc/vndksp.libraries.28.txt</code>. The generated snapshot will be used
+ with newer Android versions (higher than Android {{ androidPVersionNumber }}).
+ </li>
+ <li><strong>Installing pre-built VNDK-core and VNDK-SP libraries from a
+ snapshot</strong>. In Android {{ androidPVersionNumber }}, a VNDK snapshot has
+ a set of pre-built VNDK-core libraries and a set of VNDK-SP libraries, as well
+ as linker namespace configuration files. When you provide a list of VNDK
+ snapshot versions to be installed, at build time, the system image installs
+ the VNDK snapshot libraries to <code>/system/lib[64]/vndk-${VER}</code> and
+ the <code>/system/lib[64]/vndk-sp-${VER}</code> directories and linker
+ namespace configuration files for those VNDK snapshots to
+ <code>/etc</code> directory.</li>
+</ul>
+
+<h3 id="vndk-versioning">VNDK versioning</h3>
+
+<p>
+ Each Android release has only one VNDK snapshot and the SDK version is used as
+ a VNDK version (which means the VNDK version has an integer number, such as 27
+ for Android 8.1). The VNDK version is fixed when the Android version is
+ released. The VNDK version used by the vendor partition is stored
+ automatically in the <code>ro.vndk.version</code> property, which can be read
+ on runtime. This version is then used in identifying the vendor VNDK version
+ for some libraries and identifying the VNDK snapshot version for namespace
+ configuration.
+</p>
+
+<h3 id="build-vndk-libs">Building VNDK libraries</h3>
+
+<p>
+ The <code>make vndk</code> command builds libraries that have <code>vndk:
+ { enabled: true, … }</code>, including dependencies and namespace
+ configuration files. If <code>BOARD_VNDK_VERSION := current</code> is set,
+ these libraries are built with the <code>make</code> command.
+<p>
+
+<p>
+ Because this build does not install the VNDK libraries from the snapshot, the
+ installed VNDK libraries are not ABI-stable. However, when an Android version
+ is released, the ABI for the current VNDK version is fixed. At this point, any
+ ABI breakage is a build error, so patches to the Android version must not
+ change the ABI for VNDK libraries.
+</p>
+
+</body>
+</html>
diff --git a/en/devices/architecture/vndk/snapshot-generate.html b/en/devices/architecture/vndk/snapshot-generate.html
new file mode 100644
index 0000000..92b4d7d
--- /dev/null
+++ b/en/devices/architecture/vndk/snapshot-generate.html
@@ -0,0 +1,456 @@
+<html devsite>
+ <head>
+ <title>Generating VNDK Snapshots</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ {% include "_versions.html" %}
+ <body>
+ <!--
+ Copyright 2018 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 VNDK snapshot is a set of VNDK-core and VNDK-SP libs for an Android release.
+ You can upgrade only the system partition if the system.img includes the
+ corresponding VNDK snapshot needed by the vendor.img.
+</p>
+
+<aside class="note"><strong>Note:</strong> This page provides design details for
+ building and updating a VNDK snapshot. For details on the background,
+ definition, and use cases of VNDK snapshots, refer to
+ <a href="/devices/architecture/vndk/snapshot-design">VNDK Snapshot Design</a>.
+</aside>
+
+<p>
+ Official VNDK snapshots are built automatically on the Android build server
+ and checked into <code>/prebuilts/vndk</code> of the Android source tree. For
+ development purposes, you can build VNDK snapshots locally. VNDK snapshots are
+ supported for arm, arm64, x86, and x86_64 TARGET_ARCH flavors.
+</p>
+
+<h2 id="snapshot-build-artifacts">Snapshot build artifacts</h2>
+
+<p>
+ The Android build server generates build artifacts for VNDK snapshots using
+ the following build parameters and build commands.
+</p>
+
+<h3 id="build-parameters">Build parameters</h3>
+
+<p>
+ The build target name is <code>vndk</code> and the build target configuration
+ is as follows:
+</p>
+
+<ul>
+ <li>TARGET_PRODUCT=aosp_{TARGET_ARCH}_ab</li>
+ <li>TARGET_BUILD_VARIANT=user</li>
+ <li>TARGET_ARCH. Same as Generic System Image (GSI) target archs (arm, arm64,
+ x86, x86_64).</li>
+ <li>TARGET_ARCH_VARIANT. For snapshot v27 (Android 8.1), includes popular
+ configurations (listed below); future releases may include other arch/cpu
+ variants.</li>
+</ul>
+
+<table>
+<thead>
+<tr>
+<th>TARGET_PRODUCT</th>
+<th>TARGET_ARCH</th>
+<th>TARGET_ARCH_VARIANT</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>aosp_arm_ab</td>
+<td>arm</td>
+<td>armv7-a-neon</td>
+</tr>
+<tr>
+<td>aosp_arm64_ab</td>
+<td>arm64</td>
+<td>armv8-a</td>
+</tr>
+<tr>
+<td>aosp_x86_ab</td>
+<td>x86</td>
+<td>x86</td>
+</tr>
+<tr>
+<td>aosp_x86_64_ab</td>
+<td>x86_64</td>
+<td>x86_64</td>
+</tr>
+</tbody>
+</table>
+
+<h3 id="build-commands">Build commands</h3>
+
+<p>
+ For official snapshots, Android {{ androidPVersionNumber }} includes a new
+ dummy target (<code>vndk</code>) in
+ <a href="https://android.googlesource.com/platform/build/+/master/core/tasks/vndk.mk">vndk.mk</a>
+ that builds and outputs a VNDK snapshot to <code>$DIST_DIR</code>. The
+ snapshot zip file uses the format <code>android-vndk-{TARGET_ARCH}.zip</code>.
+ For example:
+</p>
+
+<pre class="prettyprint">
+$ lunch aosp_<ARCH>_ab-user
+$ make -j vndk dist [BOARD_VNDK_VERSION=current]
+</pre>
+
+<p>
+ The Android build server uses the
+ <a href="https://android.googlesource.com/platform/development/+/master/vndk/snapshot/build.sh">build.sh</a>
+ script to build all supported arch flavors with the following command:
+</p>
+
+<pre class="prettyprint">
+$ DIST_DIR=%dist_dir% development/vndk/snapshot/build.sh
+</pre>
+
+<p>
+ VNDK snapshots for an Android Version are generated from the
+ <code><Android Version>-release</code> branch.
+</p>
+
+<h3 id="build-locally">Building locally</h3>
+
+<p>
+ During development, you can build VNDK snapshots from a local source tree with
+ the following commands:
+</p>
+
+<ul>
+ <li>To build all supported archs at once, execute the build script
+ (<code>build.sh</code>):
+<pre class="prettyprint">
+$ cd $ANDROID_BUILD_TOP
+$ development/vndk/snapshot/build.sh
+</pre>
+ </li>
+ <li>To build one specific TARGET_ARCH:
+
+<pre class="prettyprint">
+$ lunch aosp_<ARCH>_ab-user
+$ m -j vndk dist
+</pre>
+ </li>
+</ul>
+
+<p>
+ The corresponding <code>android-vndk-<ARCH>.zip</code> file is created
+ under <code>$DIST_DIR</code>.
+</p>
+
+<h2 id="snapshot-files">Snapshot files</h2>
+
+<p>
+ A VNDK snapshot includes the following files:
+</p>
+
+<ul>
+ <li>Vendor variant of VNDK-core and VNDK-SP shared libraries.
+ <ul>
+ <li>LL-NDK shared libs are not needed as they are backward compatible.</li>
+ <li>For 64bit targets, both TARGET_ARCH and TARGET_2ND_ARCH libraries are
+ built and included.</li>
+ </ul>
+ </li>
+ <li>List of VNDK-core, VNDK-SP, LL-NDK, and VNDK-private libraries is at
+ <code>[vndkcore|vndksp|llndk|vndkprivate].libraries.txt</code>.</li>
+ <li>Linker config file is <code>ld.config.txt</code>.</li>
+ <li>License files. </li>
+ <li><code>module_paths.txt</code>. Records the module paths for all VNDK
+ libraries, which is needed for checking that GPL projects have sources
+ released in a given Android source tree.</li>
+</ul>
+
+<p>
+ For a given VNDK snapshot zip file,
+ <code>android-vndk-{TARGET_ARCH}.zip</code>, the VNDK prebuilt libraries are
+ grouped in separate directories named
+ <code>arch-{TARGET_ARCH}-{TARGET_ARCH_VARIANT}</code> according to ABI
+ bitness. For example, for <code>android-vndk-arm64.zip</code>, the 64-bit libs
+ are placed under <code>arch-arm64-armv8-a</code> and the 32-bit libs are
+ placed under <code>arch-arm-armv8-a</code>.
+</p>
+
+<h3 id="example-snapshot-dir-structure">Example: VNDK snapshot directory
+structure</h3>
+
+<p>
+ The example below shows the directory structure for an arm64
+ (<code>TARGET_ARCH=arm64</code>) VNDK snapshot zip file
+ (<code>android-vndk-arm64.zip</code>).
+</p>
+
+<img src="/devices/architecture/images/vndk_snapshot_directory.png">
+<figcaption><strong>Figure 1. </strong>VNDK snapshot directory structure
+(example)</figcaption>
+
+<h2 id='upload-vndk-snapshots'>Uploading VNDK snapshots</h2>
+
+<p>
+ VNDK snapshots are checked in the source tree under
+ <code>/prebuilts/vndk/v<VER></code>, where <code><VER></code> is
+ equal to the version of the VNDK snapshot (which follows the SDK version of
+ the corresponding Android release). For example, the O MR1 VNDK snapshot has
+ version 27.
+</p>
+
+<h3 id="using-update-py">Using the update.py script</h3>
+
+<p>
+ The <code>update.py</code> script
+ (<code>/development/vndk/snapshot/update.py)</code> automates the process of
+ adding a pre-built VNDK snapshot to the source tree. This script performs the
+ following tasks:
+</p>
+
+<ol>
+ <li>In <code>/prebuilts/vndk/v<VER></code>, uses <code>repo start</code>
+ to create new git branch.</li>
+ <li>Fetches and unzips VNDK snapshot build artifacts.</li>
+ <li>Runs <code>gen_buildfiles.py</code> to auto generate the build files
+ (<code>Android.mk</code>, <code>Android.bp</code>).</li>
+ <li>Runs <code>check_gpl_license.py</code> to verify the prebuilt libraries
+ licensed under the General Public License (GPL) have sources released in
+ current source tree.</li>
+ <li>Uses <code>git commit</code> to commit new changes.</li>
+</ol>
+
+<h3 id="using-local-snapshots">Using locally-built VNDK snapshots</h3>
+
+<p>
+ During development, you can use locally-built VNDK snapshots for testing. When
+ the <code>--local</code> option is specified, <code>update.py</code> fetches
+ VNDK snapshot build artifacts from local <code>$DIST_DIR</code> instead of the
+ Android build server. Usage:
+</p>
+
+<pre class="prettyprint">
+$ python update.py <VER> --local
+</pre>
+
+<p>
+ For example, to update the O MR1 VNDK snapshot with local build artifacts,
+ run:
+</p>
+
+<pre class="prettyprint">
+$ python update.py 27 --local
+</pre>
+
+<p>
+ Because local mode is designed for testing only, the script skips the GPL
+ license checking and git commit steps.
+</p>
+
+<h3 id="dir-structure-prebuilts">Directory structure for prebuilts/vndk</h3>
+
+<img src="/devices/architecture/images/vndk_snapshot_prebuilt.png">
+<figcaption><strong>Figure 2. </strong>Prebuilts/vndk directory
+structure</figcaption>
+
+<h2 id="install-vndk-snapshot">Installing VNDK snapshots</h2>
+
+<p>
+ The system image installs VNDK snapshot libraries at build time using the
+ information in <code>BOARD_VNDK_VERSION</code>,
+ <code>PRODUCT_EXTRA_VNDK_VERSIONS</code>, and <code>ro.vndk.version</code>.
+ You can control which VNDK snapshots get installed from
+ <code>/prebuilts/vndk/v<VER></code> using one of the following options:
+</p>
+
+<ul>
+ <li><strong>Option 1:</strong> <code>BOARD_VNDK_VERSION</code>. Use the
+ snapshot modules for building the current vendor modules and install only the
+ snapshot modules that are required for the vendor modules.</li>
+ <li><strong>Option 2:</strong> <code>PRODUCT_EXTRA_VNDK_VERSIONS</code>.
+ Install the VNDK snapshot modules regardless of the current vendor modules.
+ This installs the prebuilt VNDK snapshots listed in
+ <code>PRODUCT_EXTRA_VNDK_VERSIONS</code> without linking them to any other
+ modules at build time.</li>
+</ul>
+
+<h3 id="set-board-vndk">Setting BOARD_VNDK_VERSION</h3>
+
+<p>
+ <code>BOARD_VNDK_VERSION</code> shows the VNDK version that current vendor
+ modules are required to build. If <code>BOARD_VNDK_VERSION</code> has an
+ available VNDK snapshot version in <code>/prebuilts/vndk</code> directory, the
+ VNDK snapshot indicated in <code>BOARD_VNDK_VERSION</code> is installed. If
+ the VNDK snapshot is not available in the directory, a build error occurs.
+</p>
+
+<p>
+ Defining <code>BOARD_VNDK_VERSION</code> also enables the VNDK modules to be
+ installed. Vendor modules link with the VNDK snapshot version defined in
+ <code>BOARD_VNDK_VERSION</code> at build time (this does not build current
+ VNDK modules in the system source). When downloading the full source tree from
+ a repository, both system and vendor sources are based on the same Android
+ release.
+</p>
+
+<aside class="note"><strong>Note:</strong> Vendor modules use the current VNDK
+ version of the system source tree, so you must set
+ <code>BOARD_VNDK_VERSION</code> to <code>current</code>.
+</aside>
+
+<h3 id="set-product-extra">Setting PRODUCT_EXTRA_VNDK_VERSIONS</h3>
+
+<p>
+ <code>PRODUCT_EXTRA_VNDK_VERSIONS</code> lists the extra VNDK versions to be
+ installed. Normally it is enough to have one VNDK snapshot for the current
+ vendor partition. However, in some cases you might need to include multiple
+ snapshots in one system image. For example, Generic System Image (GSI) has
+ multiple snapshots to support multiple vendor versions with one system image.
+ By setting <code>PRODUCT_EXTRA_VNDK_VERSIONS</code>, you can install the VNDK
+ snapshot modules in addition to the VNDK version in
+ <code>BOARD_VNDK_VERSION</code>.
+</p>
+
+<p>
+ If <code>PRODUCT_EXTRA_VNDK_VERSIONS</code> has a specific list of versions,
+ the build system looks for pre-built snapshots of the version list in the
+ <code>prebuilts/vndk</code> directory. If the build system locates all listed
+ snapshots, it installs those snapshot files to each
+ <code>out/target/product/<board>/system/lib[64]/vndk[-sp]-${VER}</code>.
+ Missing versions generate a build error.
+</p>
+
+<p>
+ The VNDK modules will not link with the vendor modules at build time but may
+ be used at runtime if the vendor modules in vendor partition require one of
+ the installed VNDK versions. <code>PRODUCT_EXTRA_VNDK_VERSIONS</code> is valid
+ only if <code>BOARD_VNDK_VERSION</code> is defined. For example, to install
+ the O MR1 VNDK snapshot to system.img:
+</p>
+
+<pre class="prettyprint">
+$ m -j PRODUCT_EXTRA_VNDK_VERSIONS=27
+</pre>
+
+<h3 id="platform-vndk">PLATFORM_VNDK_VERSION</h3>
+
+<p>
+ <code>PLATFORM_VNDK_VERSION</code> defines the VNDK version for current VNDK
+ modules in the system source. The value is set automatically:
+</p>
+
+<ul>
+ <li>Prior to release, the <code>PLATFORM_VNDK_VERSION</code> is set as
+ <code>PLATFORM_VERSION_CODENAME</code>.</li>
+ <li>At release, <code>PLATFORM_SDK_VERSION</code> is copied to
+ <code>PLATFORM_VNDK_VERSION</code>.</li>
+</ul>
+
+<p>
+ After the Android version is released, the current VNDK libraries are
+ installed to <code>/system/lib[64]/vndk-$SDK_VER</code> and
+ <code>/system/lib[64]/vndk-sp-$SDK_VER</code>, where <code>$SDK_VER</code> is
+ the version stored in <code>PLATFORM_VNDK_VERSION</code>.
+</p>
+
+<h3 id="namespace-config">Namespace configuration</h3>
+
+<p>
+ The vendor modules search the required shared libraries using the namespace
+ configuration in <code>/etc/ld.config.${VER}.txt</code> (where
+ <code>${VER}</code> is obtained from the <code>ro.vndk.version</code>
+ property). The namespace configuration has a versioned VNDK directory that
+ uses the following syntax:
+</p>
+
+<ul>
+ <li><code>/system/${LIB}/vndk-%VNDK_VER%</code></li>
+ <li><code>/system/${LIB}/vndk-sp-%VNDK_VER%</code></li>
+</ul>
+
+<p>
+ <code>%VNDK_VER%</code> is replaced with <code>PLATFORM_VNDK_VERSION</code>
+ at build time, enabling a system image to provide multiple snapshots for each
+ VNDK version.
+</p>
+
+<p>
+ When <code>BOARD_VNDK_VERSION</code> is set to <code>current</code>, the
+ <code>PLATFORM_VNDK_VERSION</code> is stored in <code>ro.vndk.version</code>,
+ otherwise <code>BOARD_VNDK_VERSION </code>is stored in
+ <code>ro.vndk.version</code>. <code>PLATFORM_VNDK_VERSION</code> is set to the
+ SDK version when Android releases; prior to release, the alphanumeric Android
+ code name is used for <code>PLATFORM_VNDK_VERSION</code>.
+</p>
+
+<h3 id="summary-vndk-version-settings">Summary of VNDK version settings</h3>
+
+<p>
+ The table below summarizes the VNDK version settings.
+</p>
+
+<table>
+<thead>
+<tr>
+<th width="15%">Vendor<br>Build</th>
+<th>Board<br>Version</th>
+<th>SDK<br>Release</th>
+<th>Platform<br>Version</th>
+<th>Version<br>Property</th>
+<th>Install Directory</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td rowspan=2>Current VNDK modules</td>
+<td rowspan=2><code>current</code></td>
+<td>Before</td>
+<td><CODE_NAME></td>
+<td><CODE_NAME></td>
+<td>/system/lib[64]/vndk[-sp]-<CODE_NAME></td>
+</tr>
+<tr>
+<td>After</td>
+<td><SDK_ver></td>
+<td><SDK_ver></td>
+<td>/system/lib[64]/vndk[-sp]-<SDK_ver></td>
+</tr>
+<tr>
+<td>Prebuilt snapshot modules</td>
+<td><VNDK_ver><br>for snapshot</td>
+<td>Before or After</td>
+<td><CODE_NAME><br>or <SDK_ver></td>
+<td><VNDK_ver></td>
+<td>/system/lib[64]/vndk[-sp]-<VNDK_ver></td>
+</tr>
+</tbody>
+</table>
+
+<ul>
+ <li><strong>Board Version</strong> (<code>BOARD_VNDK_VERSION</code>). VNDK
+ version that vendor modules require to build. Set to <code>current</code> if
+ vendor modules can link with current system modules.</li>
+ <li><strong>Platform Version</strong> (<code>PLATFORM_VNDK_VERSION</code>).
+ VNDK version that current system modules are building. Built only when
+ <code>BOARD_VNDK_VERSION</code> equals current.</li>
+ <li><strong>Version Property</strong> (<code>ro.vndk.version</code>). Property
+ that specifies the VNDK version the binaries and libs in vendor.img require to
+ run. Stored in the vendor.img at<code> /vendor/default.prop</code>.</li>
+</ul>
+
+</body>
+</html>
\ No newline at end of file
diff --git a/en/devices/audio/attributes.html b/en/devices/audio/attributes.html
index 61825c0..9cf34e8 100644
--- a/en/devices/audio/attributes.html
+++ b/en/devices/audio/attributes.html
@@ -4,6 +4,7 @@
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
+ {% include "_versions.html" %}
<body>
<!--
Copyright 2017 The Android Open Source Project
@@ -22,84 +23,127 @@
-->
+<p>
+ Audio players support attributes that define how the audio system handles
+ routing, volume, and focus decisions for the specified source. Applications
+ can attach attributes to an audio playback (such as music played by a
+ streaming service or a notification for a new email) then pass the audio
+ source attributes to the framework, where the audio system uses the attributes
+ to make mixing decisions and to notify applications about the state of the
+ system.
+</p>
-<p>Audio players support attributes that define how the audio system handles routing, volume, and
-focus decisions for the specified source. Applications can attach attributes to an audio playback
-(such as music played by a streaming service or a notification for a new email) then pass the audio
-source attributes to the framework, where the audio system uses the attributes to make mixing
-decisions and to notify applications about the state of the system.</p>
+<aside class="note"><strong>Note:</strong> Applications can also attach
+ attributes to an audio recording (such as audio captured in a video
+ recording), but this functionality is not exposed in the public API.
+</aside>
-<p class="note"><strong>Note:</strong> Applications can also attach attributes to an audio
-recording (such as audio captured in a video recording), but this functionality is not exposed in
-the public API.</p>
+<p>
+ In Android 4.4 and earlier, the framework made mixing decisions using only
+ the audio stream type. However, basing such decisions on stream type was too
+ limiting to produce quality output across multiple applications and devices.
+ For example, on a mobile device, some applications (i.e. Google Maps) played
+ driving directions on the STREAM_MUSIC stream type; however, on mobile devices
+ in projection mode (i.e. Android Auto), applications cannot mix driving
+ directions with other media streams.
+</p>
-<p>In Android 4.4 and earlier, the framework made mixing decisions using only the audio stream type.
-However, basing such decisions on stream type was too limiting to produce quality output across
-multiple applications and devices. For example, on a mobile device, some applications (i.e.
-Google Maps) played driving directions on the STREAM_MUSIC stream type; however, on mobile
-devices in projection mode (i.e. Android Auto), applications cannot mix driving directions with
-other media streams.</p>
+<p>
+ Using the
+ <a href="http://developer.android.com/reference/android/media/AudioAttributes.html" class="external">Audio
+ Attribute API</a>, applications provide the audio system with detailed
+ information about a specific audio source, including usage (why the source is
+ playing), content type (what the source is playing), flags (how the source
+ should be played), and contexts (new in Android {{ androidPVersionNumber }}).
+ Syntax:
+</p>
-<p>Using the <a href="http://developer.android.com/reference/android/media/AudioAttributes.html">
-audio attribute API</a>, applications can now provide the audio system with detailed information
-about a specific audio source:</p>
+<pre class="prettyprint">
+AudioAttributes {
+ mUsage
+ mContentType
+ mSource
+ mFlags
+ mTags / mFormattedTags / mBundle (key value pairs)
+}
+</pre>
+
<ul>
-<li><b>Usage</b>. Specifies why the source is playing and controls routing, focus, and volume
-decisions.</li>
-<li><b>Content type</b>. Specifies what the source is playing (music, movie, speech,
-sonification, unknown).</li>
-<li><b>Flags</b>. Specifies how the source should be played. Includes support for audibility
-enforcement (camera shutter sounds required in some countries) and hardware audio/video
-synchronization.</li>
+ <li><strong>Usage</strong>. Specifies why the source is playing and controls
+ routing, focus, and volume decisions.</li>
+ <li><strong>Content type</strong>. Specifies what the source is playing
+ (music, movie, speech, sonification, unknown).</li>
+ <li><strong>Context</strong>. Usage values abstracted to the Audio HAL.
+ <li><strong>Flags</strong>. Specifies how the source should be played.
+ Includes support for audibility enforcement (camera shutter sounds required in
+ some countries) and hardware audio/video synchronization.</li>
</ul>
-<p>For dynamics processing, applications must distinguish between movie, music, and speech content.
-Information about the data itself may also matter, such as loudness and peak sample value.</p>
+<p>
+ For dynamics processing, applications must distinguish between movie, music,
+ and speech content. Information about the data itself may also matter, such as
+ loudness and peak sample value.
+</p>
<h2 id="using">Using attributes</h2>
-<p>Usage specifies the context in which the stream is used, providing information about why the
-sound is playing and what the sound is used for. Usage information is more expressive than a stream
-type and allows platforms or routing policies to refine volume or routing decisions.</p>
+<p>
+ Usage specifies the context in which the stream is used, providing
+ information about why the sound is playing and what the sound is used for.
+ Usage information is more expressive than a stream type and allows platforms
+ or routing policies to refine volume or routing decisions.
+</p>
-<p>Supply one of the following usage values for any instance:</p>
+<p>
+ Supply one of the following usage values for any instance:
+</p>
<ul>
-<li><code>USAGE_UNKNOWN</code></li>
-<li><code>USAGE_MEDIA</code></li>
-<li><code>USAGE_VOICE_COMMUNICATION</code></li>
-<li><code>USAGE_VOICE_COMMUNICATION_SIGNALLING</code></li>
-<li><code>USAGE_ALARM</code></li>
-<li><code>USAGE_NOTIFICATION</code></li>
-<li><code>USAGE_NOTIFICATION_RINGTONE</code></li>
-<li><code>USAGE_NOTIFICATION_COMMUNICATION_INSTANT</code></li>
-<li><code>USAGE_NOTIFICATION_COMMUNICATION_DELAYED</code></li>
-<li><code>USAGE_NOTIFICATION_EVENT</code></li>
-<li><code>USAGE_ASSISTANCE_ACCESSIBILITY</code></li>
-<li><code>USAGE_ASSISTANCE_NAVIGATION_GUIDANCE</code></li>
-<li><code>USAGE_ASSISTANCE_SONIFICATION</code></li>
-<li><code>USAGE_GAME</code></li>
+<li>USAGE_UNKNOWN</li>
+<li>USAGE_MEDIA</li>
+<li>USAGE_VOICE_COMMUNICATION</li>
+<li>USAGE_VOICE_COMMUNICATION_SIGNALLING</li>
+<li>USAGE_ALARM</li>
+<li>USAGE_NOTIFICATION</li>
+<li>USAGE_NOTIFICATION_TELEPHONY_RINGTONE</li>
+<li>USAGE_NOTIFICATION_COMMUNICATION_REQUEST</li>
+<li>USAGE_NOTIFICATION_COMMUNICATION_INSTANT</li>
+<li>USAGE_NOTIFICATION_COMMUNICATION_DELAYED</li>
+<li>USAGE_NOTIFICATION_EVENT</li>
+<li>USAGE_ASSISTANCE_ACCESSIBILITY</li>
+<li>USAGE_ASSISTANCE_NAVIGATION_GUIDANCE</li>
+<li>USAGE_ASSISTANCE_SONIFICATION</li>
+<li>USAGE_GAME</li>
+<li>USAGE_VIRTUAL_SOURCE</li>
+<li>USAGE_ASSISTANT</li>
</ul>
-<p>Audio attribute usage values are mutually exclusive. For examples, refer to <code>
-<a href="http://developer.android.com/reference/android/media/AudioAttributes.html#USAGE_MEDIA">
-USAGE_MEDIA</a></code> and <code>
-<a href="http://developer.android.com/reference/android/media/AudioAttributes.html#USAGE_ALARM">
-USAGE_ALARM</a></code> definitions; for exceptions, refer to the <code>
-<a href="http://developer.android.com/reference/android/media/AudioAttributes.Builder.html">
-AudioAttributes.Builder</a></code> definition.</p>
+<p>
+ Audio attribute usage values are mutually exclusive. For examples, refer to
+ <code><a href="http://developer.android.com/reference/android/media/AudioAttributes.html#USAGE_MEDIA" class="external">USAGE_MEDIA</a></code>
+ and
+ <code><a href="http://developer.android.com/reference/android/media/AudioAttributes.html#USAGE_ALARM" class="external">USAGE_ALARM</a></code>
+ definitions; for exceptions, refer to the
+ <code><a href="http://developer.android.com/reference/android/media/AudioAttributes.Builder.html" class="external">AudioAttributes.Builder</a></code>
+ definition.
+</p>
<h2 id="content-type">Content type</h2>
-<p>Content type defines what the sound is and expresses the general category of the content such as
-movie, speech, or beep/ringtone. The audio framework uses content type information to selectively
-configure audio post-processing blocks. While supplying the content type is optional, you should
-include type information whenever the content type is known, such as using
-<code>CONTENT_TYPE_MOVIE</code> for a movie streaming service or <code>CONTENT_TYPE_MUSIC</code>
-for a music playback application.</p>
+<p>
+ Content type defines what the sound is and expresses the general category of
+ the content such as movie, speech, or beep/ringtone. The audio framework uses
+ content type information to selectively configure audio post-processing
+ blocks. While supplying the content type is optional, you should include type
+ information whenever the content type is known, such as using
+ <code>CONTENT_TYPE_MOVIE</code> for a movie streaming service or
+ <code>CONTENT_TYPE_MUSIC</code> for a music playback application.
+</p>
-<p>Supply one of the following content type values for any instance:</p>
+<p>
+ Supply one of the following content type values for any instance:
+</p>
<ul>
<li><code>CONTENT_TYPE_UNKNOWN</code> (default)</li>
@@ -109,33 +153,121 @@
<li><code>CONTENT_TYPE_SPEECH</code></li>
</ul>
-<p>Audio attribute content type values are mutually exclusive. For details on content types,
-refer to the <a href="http://developer.android.com/reference/android/media/AudioAttributes.html">
-audio attribute API</a>.</p>
+<p>
+ Audio attribute content type values are mutually exclusive. For details on content types,
+ refer to the
+ <a href="http://developer.android.com/reference/android/media/AudioAttributes.html" class="external">audio
+ attribute API</a>.
+</p>
+
+<h2 id="contexts">Contexts</h2>
+
+<p>
+ Each sound in Android is identified by the responsible application and reason
+ for generating the sound; and Android device uses this information to
+ determine how to present the sound. In Android 8.x and lower, applications can
+ report the sound generation reason using legacy stream types (e.g.
+ <code>AudioSystem.STREAM_MUSIC</code>) or <code>AudioAttributes</code>. In
+ Android {{ androidPVersionNumber }}, <code>AudioAttributes.usage</code> values
+ are abstracted at the HAL level as <em>Contexts</em>.
+</p>
+
+<table>
+<thead>
+<tr>
+<th>HAL audio contexts</th>
+<th>AudioAttributes usage</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>MUSIC</td>
+<td>MEDIA</td>
+</tr>
+<tr>
+<td>VOICE_COMMAND</td>
+<td>USAGE_ASSISTANT</td>
+</tr>
+<tr>
+<td>NAVIGATION</td>
+<td>ASSISTANCE_NAVIGATION_GUIDANCE</td>
+</tr>
+<tr>
+<td>CALL</td>
+<td>VOICE_COMMUNICATION</td>
+</tr>
+<tr>
+<td>RINGTONE</td>
+<td>NOTIFICATION_RINGTONE</td>
+</tr>
+<tr>
+<td>NOTIFICATION</td>
+<td>NOTIFICATION</td>
+</tr>
+<tr>
+<td>ALARM</td>
+<td>ALARM</td>
+</tr>
+<tr>
+<td>SYSTEM_SOUND</td>
+<td>ASSISTANCE_SONIFICATION</td>
+</tr>
+<tr>
+<td>UNKNOWN</td>
+<td>UNKNOWN</td>
+</tr>
+</tbody>
+</table>
+
+<p>
+ You can supply one of the following <code>CONTEXT_NUMBER</code> values for any
+ instance:
+</p>
+
+<ul>
+<li>MUSIC_CONTEXT // Music playback</li>
+<li>NAVIGATION_CONTEXT // Navigation directions</li>
+<li>VOICE_COMMAND_CONTEXT // Voice command session</li>
+<li>CALL_RING_CONTEXT // Voice call ringing</li>
+<li>CALL_CONTEXT // Voice call</li>
+<li>ALARM_CONTEXT // Alarm sound from Android</li>
+<li>NOTIFICATION_CONTEXT // Notifications</li>
+<li>SYSTEM_SOUND_CONTEXT // User interaction sounds (button clicks, etc)</li>
+</ul>
+
<h2 id="flags">Flags</h2>
-<p>Flags specify how the audio framework applies effects to the audio playback. Supply one or more
-of the following flags for an instance:</p>
+<p>
+ Flags specify how the audio framework applies effects to the audio playback.
+ Supply one or more of the following flags for an instance:
+</p>
<ul>
-<li><code>FLAG_AUDIBILITY_ENFORCED</code>. Requests the system ensure the audibility of the
-sound. Use to address the needs of legacy <code>STREAM_SYSTEM_ENFORCED</code> (such as forcing
-camera shutter sounds).</li>
-<li><code>HW_AV_SYNC</code>. Requests the system select an output stream that supports hardware A/V
-synchronization.</li>
+ <li><code>FLAG_AUDIBILITY_ENFORCED</code>. Requests the system to ensure the
+ audibility of the sound. Use to address the needs of legacy
+ <code>STREAM_SYSTEM_ENFORCED</code> (such as forcing camera shutter sounds).
+ </li>
+ <li><code>HW_AV_SYNC</code>. Requests the system to select an output stream
+ that supports hardware A/V synchronization.</li>
</ul>
-<p>Audio attribute flags are non-exclusive (can be combined). For details on these flags,
-refer to the <a href="http://developer.android.com/reference/android/media/AudioAttributes.html">
-audio attribute API</a>.</p>
+<p>
+ Audio attribute flags are non-exclusive and can be combined. For details on
+ these flags, refer to the
+ <a href="http://developer.android.com/reference/android/media/AudioAttributes.html" class="external">audio
+ attribute API</a>.
+</p>
<h2 id="example">Example</h2>
-<p>In this example, AudioAttributes.Builder defines the AudioAttributes to be used by a new
-AudioTrack instance:</p>
+<p>
+ In this example, <code>AudioAttributes.Builder</code> defines the
+ <code>AudioAttributes</code> to be used by a new <code>AudioTrack</code>
+ instance:
+</p>
-<pre class="devsite-click-to-copy">
+<pre class="prettyprint">
AudioTrack myTrack = new AudioTrack(
new AudioAttributes.Builder()
.setUsage(AudioAttributes.USAGE_MEDIA)
@@ -146,21 +278,28 @@
<h2 id="compatibility">Compatibility</h2>
-<p>Application developers should use audio attributes when creating or updating applications for
-Android 5.0. However, applications are not required to take advantage of attributes; they can
-handle legacy stream types only or remain unaware of attributes (i.e. a generic media player that
-doesn't know anything about the content it's playing).</p>
+<p>
+ Application developers should use audio attributes when creating or updating
+ applications for Android 5.0 and higher. However, applications are not
+ required to take advantage of attributes; they can handle legacy stream types
+ only or remain unaware of attributes (i.e. a generic media player that doesn't
+ know anything about the content it's playing).
+</p>
-<p>In such cases, the framework maintains backwards compatibility with older devices and Android
-releases by automatically translating legacy audio stream types to audio attributes. However, the
-framework does not enforce or guarantee this mapping across devices, manufacturers, or Android
-releases.</p>
+<p>
+ In such cases, the framework maintains backwards compatibility with older
+ devices and Android releases by automatically translating legacy audio stream
+ types to audio attributes. However, the framework does not enforce or
+ guarantee this mapping across devices, manufacturers, or Android releases.
+</p>
-<p>Compatibility mappings:</p>
+<p>
+ Compatibility mappings:
+</p>
<table>
<tr>
- <th>Android 5.0</th>
+ <th>Android 5.0 and higher</th>
<th>Android 4.4 and earlier</th>
</tr>
<tr>
@@ -252,8 +391,35 @@
</tr>
</table>
-<p class="note"><strong>Note:</strong> @hide streams are used internally by the framework but are
-not part of the public API.</p>
+<aside class="note"><strong>Note:</strong> @hide streams are used internally by
+ the framework but are not part of the public API.
+</aside>
+
+<h2 id="deprecated">Deprecated stream types</h2>
+
+<p>
+ Android {{ androidPVersionNumber }} deprecates the following stream types for
+ automotive use:
+</p>
+
+<ul>
+<li>STREAM_DEFAULT</li>
+<li>STREAM_VOICE_CALL</li>
+<li>STREAM_SYSTEM</li>
+<li>STREAM_RING</li>
+<li>STREAM_MUSIC</li>
+<li>STREAM_ALARM</li>
+<li>STREAM_NOTIFICATION</li>
+<li>STREAM_BLUETOOTH_SCO</li>
+<li>STREAM_SYSTEM_ENFORCED</li>
+<li>STREAM_DTMF</li>
+<li>STREAM_TTS</li>
+<li>STREAM_ACCESSIBILITY</li>
+</ul>
+
+<p>For more details, see
+ <a href="/devices/automotive/audio">Automotive Audio</a>.
+</p>
</body>
</html>
diff --git a/en/devices/audio/highres-effects.html b/en/devices/audio/highres-effects.html
new file mode 100644
index 0000000..eb94a70
--- /dev/null
+++ b/en/devices/audio/highres-effects.html
@@ -0,0 +1,164 @@
+<html devsite="">
+<head>
+ <title>High-Resolution Audio Effects</title>
+ <meta name="project_path" value="/_project.yaml">
+ <meta name="book_path" value="/_book.yaml">
+</head>
+
+<body>
+ {% include "_versions.html" %}
+ <!--
+ Copyright 2018 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 Android {{ androidPVersionNumber }} release includes the following
+ improvements for high-resolution audio:</p>
+
+
+ <ul>
+ <li>Effect processing is converted from int16 to float format, one of the
+ few remaining int16 pipelines in AudioFlinger. This effect processing
+ change requires implementation work from vendors providing custom effects.
+ That work is described in the following sections.</li>
+
+
+ <li>The following improvements do not require any partner implementation:
+
+ <ul>
+ <li>The number of simultaneous client output tracks increases from 14
+ to 40, as limited client AudioTracks have been an issue for
+ applications in Android 8.x.</li>
+
+
+ <li>Maximum client/server memory increases from 4MB to 32MB (depending
+ on total device memory) to allow more simultaneous high-resolution
+ audio tracks.</li>
+
+
+ <li>Total mixed tracks increases from 32 to 256 to prevent resource
+ contention between applications and the System UI.</li>
+ </ul>
+ </li>
+ </ul>
+
+
+ <h2 id="output-effect-changes">Output effect changes</h2>
+
+
+ <p>Prior to the Android {{ androidPVersionNumber }} release, effect chain processing
+was implemented in stereo int16 sample format. This had several limitations:</p>
+
+
+ <ul>
+ <li>All output effects forced conversion from floating point audio data to
+ int16, causing loss of precision.</li>
+
+
+ <li>Output effects were rejected from output sinks with a channel count
+ greater than 2.</li>
+ </ul>
+
+
+ <p>In the Android {{ androidPVersionNumber }} release, the effect chain processing
+ pipeline is upgraded to support the multichannel float format. Key points:</p>
+
+
+ <ul>
+ <li>Android software effects are already migrated to stereo float.</li>
+
+
+ <li>Legacy effects are supported with format adapters, which convert float
+ to int16 as needed.</li>
+ </ul>
+
+
+ <h2 id="implementing-output-effects">Implementing output effects</h2>
+
+
+ <p>A reference implementation for output effects is available under
+ <code>frameworks/av/media/libeffects</code>.</p>
+
+
+ <p>Partners implementing their own custom output effects should do the
+ following for the Android {{ androidPVersionNumber }} release:</p>
+
+
+ <ul>
+ <li>Update output effects to support the multichannel float format:
+
+ <ul>
+ <li>Int16 processing support is no longer required.</li>
+
+
+ <li>Support output channel counts from 2 - 8 (for future compatibility
+ consider counts from 1 - 30).</li>
+
+
+ <li>Support input channel counts matching output channel count for
+ insert effects. Auxiliary effects will continue to see an input channel
+ count of 1 (mono).</li>
+
+
+ <li>Support both channel position masks (canonical) and channel index
+ masks of (1 << n) - 1.</li>
+ </ul>
+ </li>
+
+
+ <li>If you must continue to support legacy vendor output effects and cannot
+ update them, then verify legacy code as follows:
+
+ <ul>
+ <li>Legacy output (insert) effects <strong>must reject</strong>
+ unsupported configurations in <code>EFFECT_CMD_SET_CONFIG</code>.
+
+ <ul>
+ <li>Check that format is int16.</li>
+
+
+ <li>Check that the input and output channel masks are stereo.</li>
+
+
+ <li>If not, return <code>-EINVAL</code>.</li>
+ </ul>
+ </li>
+
+
+ <li>Legacy output (auxiliary) effects are configured by AudioFlinger
+ with a mono input channel mask and potentially multichannel output
+ channel masks, depending on whether the output sink is multichannel.
+ They <strong>must reject</strong> unsupported configurations in <code>
+ EFFECT_CMD_SET_CONFIG</code>.
+
+ <ul>
+ <li>Check that the format is int16.</li>
+
+
+ <li>Check that the input channel mask is mono and the output
+ channel mask is stereo.</li>
+
+
+ <li>If not, return <code>-EINVAL</code>.</li>
+ </ul>
+ </li>
+
+
+ <li>Verify legacy code. Please do not assume it will work!</li>
+ </ul>
+ </li>
+ </ul>
+</body>
+</html>
diff --git a/en/devices/audio/index.html b/en/devices/audio/index.html
index e016b92..d99d1dc 100644
--- a/en/devices/audio/index.html
+++ b/en/devices/audio/index.html
@@ -33,7 +33,6 @@
improving performance.
</p>
-<h2 id="Architecture">Audio Architecture</h2>
<p>
Android audio architecture defines how audio functionality is implemented and
points to the relevant source code involved in the implementation.
diff --git a/en/devices/automotive/audio/audio-control.html b/en/devices/automotive/audio/audio-control.html
new file mode 100644
index 0000000..bb0ecbb
--- /dev/null
+++ b/en/devices/automotive/audio/audio-control.html
@@ -0,0 +1,504 @@
+<html devsite>
+ <head>
+ <title>Implementing the AudioControl HAL</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ {% include "_versions.html" %}
+ <body>
+ <!--
+ Copyright 2018 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 {{ androidPVersionNumber }} deprecates the <code>AUDIO_*</code>
+ properties in previous iterations of the Vehicle HAL and replaces them with a
+ dedicated Audio Control HAL that includes explicit function calls and typed
+ parameter lists.
+</p>
+
+<p>
+ This new HAL exposes <code>IAudioControl</code> as the primary interface
+ object that provides entry points to interact with the vehicle's audio engine
+ for configuration and volume control. The system can contain exactly one
+ instance of this object, which is created by <code>CarAudioService</code> when
+ it starts up. This object is an automotive extension of the traditional
+ Android Audio HAL; in most implementations, the same process that publishes
+ the Audio HAL interfaces should also publish the
+ <code>IAudioControl interfaces</code>.
+</p>
+
+<h2 id="supported-interfaces">Supported interfaces</h2>
+
+<p>
+ The <code>AudioControl</code> HAL supports the following interfaces:
+</p>
+
+<ul>
+ <li><code><strong>getBusforContext</strong></code>. Called at startup once
+ per context to get the mapping from <code>ContextNumber</code> to
+ <code>busAddress</code>. Example usage:
+
+<pre class="prettyprint">
+getBusForContext(ContextNumber contextNumber)
+ generates (uint32_t busNumber);
+</pre>
+
+Enables the vehicle to tell the framework where to route the physical
+output stream for each context. For every context, a valid bus number (0 - num
+busses-1) must be returned. If an unrecognized <code>contextNumber</code> is
+encountered, -1 shall be returned. Any context for which an invalid
+<code>busNumber</code> is returned will be routed to bus 0.
+<br><br>
+Any concurrent sounds associated with the same <code>busNumber</code> via this
+mechanism will be mixed by the Android <code>AudioFlinger</code> before being
+delivered as a single stream to the Audio HAL. This supersedes the Vehicle HAL
+properties <code>AUDIO_HW_VARIANT</code> and <code>AUDIO_ROUTING_POLICY</code>.
+ </li>
+
+ <li><code><strong>setBalanceTowardRight</strong></code>. Control the
+ right/left balance setting of vehicle speakers. Example usage:
+
+<pre class="prettyprint">
+setBalanceTowardRight(float value);
+</pre>
+
+Shifts the speaker volume toward the right (+) or left (-) side of the
+car. 0.0 is centered, +1.0 is fully right, -1.0 is fully left, and a value
+outside the range -1 to 1 is an error.
+ </li>
+
+ <li><code><strong>setFadeTowardFront</strong></code>. Control the fore/aft
+ fade setting of vehicle speakers. Example usage:
+
+<pre class="prettyprint">
+setFadeTowardFront(float value);
+</pre>
+
+Shifts the speaker volume toward the front (+) or back (-) of the car.
+0.0 is centered, +1.0 is fully forward, -1.0 is fully rearward, and a value
+outside the range -1 to 1 is an error.
+ </li>
+</ul>
+
+<h2 id="configure-volume">Configuring volume</h2>
+
+<p>
+ Android automotive implementations should control volume using a hardware
+ amplifier instead of a software mixer. To avoid side effects, in
+ <code>device/generic/car/emulator/audio/overlay/frameworks/base/core/res/res/values/config.xml</code>,
+ set the <code>config_useFixedVolume</code> flag to <code>true</code> (overlay
+ as necessary):
+</p>
+
+<pre class="prettyprint">
+<resources>
+ <!-- Car uses hardware amplifier for volume. -->
+ <bool name="config_useFixedVolume">true</bool>
+</resources>
+</pre>
+
+<p>
+ When the <code>config_useFixedVolume</code> flag is not set (or set to
+ <code>false</code>), applications can call
+ <code>AudioManager.setStreamVolume()</code> and change the volume by stream
+ type in the software mixer. This may be undesirable because of the potential
+ effect on other applications and the fact that volume attenuation in the
+ software mixer results in fewer significant bits available in the signal when
+ received at the hardware amplifier.
+</p>
+
+<h2 id="configure-volume-groups">Configuring volume groups</h2>
+
+<p>
+ <code>CarAudioService</code> uses volume groups defined in
+ <code>packages/services/Car/service/res/xml/car_volume_group.xml</code>. You
+ can override this file to redefine volume groups as necessary. Groups are
+ identified at runtime by their order of definition in the XML file. IDs range
+ from 0 to N-1, where N is the number of volume groups. Example:
+</p>
+
+<pre class="prettyprint">
+<volumeGroups xmlns:car="http://schemas.android.com/apk/res-auto">
+ <group>
+ <context car:context="music"/>
+ <context car:context="call_ring"/>
+ <context car:context="notification"/>
+ <context car:context="system_sound"/>
+ </group>
+ <group>
+ <context car:context="navigation"/>
+ <context car:context="voice_command"/>
+ </group>
+ <group>
+ <context car:context="call"/>
+ </group>
+ <group>
+ <context car:context="alarm"/>
+ </group>
+</volumeGroups>
+</pre>
+
+<p>
+ The attributes used in this configuration are defined in
+ <code>packages/services/Car/service/res/values/attrs.xml</code>.
+</p>
+
+<h2 id="handle-volumn-key-events">Handling volume key events</h2>
+
+<p>
+ Android defines several keycodes for volume control, including
+ <code>KEYCODE_VOLUME_UP</code>, <code>KEYCODE_VOLUME_DOWN</code>, and
+ <code>KEYCODE_VOLUME_MUTE</code>. By default, Android routes the volume key
+ events to applications. Automotive implementations should force these key
+ events to <code>CarAudioService</code>, which can then call
+ <code>setGroupVolume</code> or <code>setMasterMute</code> as appropriate.
+</p>
+
+<p>
+ To force this behavior, in
+ <code>device/generic/car/emulator/car/overlay/frameworks/base/core/res/res/values/config.xml</code>,
+ set the <code>config_handleVolumeKeysInWindowManager</code> flag to
+ <code>true</code>:
+</p>
+
+<pre class="prettyprint">
+<resources>
+ <bool name="config_handleVolumeKeysInWindowManager">true</bool>
+</resources>
+</pre>
+
+<h2 id="caraudiomanager-api">CarAudioManager API</h2>
+
+<p>
+ The <code>CarAudioManager</code> uses <code>CarAudioService</code> to
+ configure and control vehicle audio systems. The manager is invisible to most
+ apps in the system, but vehicle-specific components, such as a volume
+ controller, can use the <code>CarAudioManager</code> API to interact with the
+ system.
+</p>
+
+<p>
+ The following sections describe Android {{ androidPVersionNumber }} changes to
+ the <code>CarAudioManager API</code>.
+</p>
+
+<h3 id="deprecated-apis">Deprecated APIs</h3>
+
+<p>
+ Android {{ androidPVersionNumber }} handles device enumeration through the
+ existing <code>AudioManager</code> <code>getDeviceList</code> API, so the
+ following vehicle-specific functions have been deprecated and removed:
+</p>
+
+<ul>
+ <li><code>String[] getSupportedExternalSourceTypes()</code></li>
+ <li><code>String[] getSupportedRadioTypes()</code></li>
+</ul>
+
+<p>
+ Android {{ androidPVersionNumber }} handles volume using
+ <code>AudioAttributes.AttributeUsage</code> or volume group-based entry
+ points, so the following APIs that rely on <code>streamType</code> have been
+ removed:
+</p>
+
+<ul>
+ <li><code>void setStreamVolume(int streamType, int index, int flags)</code>
+ </li>
+ <li><code>int getStreamMaxVolume(int streamType)</code></li>
+ <li><code>int getStreamMinVolume(int streamType)</code></li>
+ <li><code>void setVolumeController(IVolumeController controller)</code></li>
+</ul>
+
+<h3 id="new-apis">New APIs</h3>
+
+<p>
+ Android {{ androidPVersionNumber }} adds the following new APIs for
+ controlling amplifier hardware (explicitly based on volume groups):
+</p>
+
+<ul>
+ <li><code>int getVolumeGroupIdForUsage(@AudioAttributes.AttributeUsage int
+ usage)</code></li>
+ <li><code>int getVolumeGroupCount()</code></li>
+ <li><code>int getGroupVolume(int groupId)</code></li>
+ <li><code>int getGroupMaxVolume(int groupId)</code></li>
+ <li><code>int getGroupMinVolume(int groupId)</code></li>
+</ul>
+
+<p>
+ In addition, Android {{ androidPVersionNumber }} provides the following new
+ system APIs for use by System GUI:
+</p>
+
+<ul>
+ <li><code>void setGroupVolume(int groupId, int index, int flags)</code></li>
+ <li><code>void registerVolumeChangeObserver(@NonNull ContentObserver
+ observer)</code></li>
+ <li><code>void unregisterVolumeChangeObserver(@NonNull ContentObserver
+ observer)</code></li>
+ <li><code>void registerVolumeCallback(@NonNull IBinder binder)</code></li>
+ <li><code>void unregisterVolumeCallback(@NonNull IBinder binder)</code></li>
+ <li><code>void setFadeToFront(float value)</code></li>
+ <li><code>Void setBalanceToRight(float value)</code></li>
+</ul>
+
+<p>
+ Finally, Android {{ androidPVersionNumber }} adds new APIs for external
+ source management. These are intended primarily to support audio routing from
+ external sources to the output buses based on media type. They can also
+ potentially enable third-party application access to external devices.
+</p>
+
+<ul>
+ <li><code>String[] getExternalSources()</code>. Returns an array of
+ addresses identifying the available audio ports in the system of type
+ <code>AUX_LINE</code>, <code>FM_TUNER</code>, <code>TV_TUNER</code>, and
+ <code>BUS_INPUT</code>.</li>
+ <li><code>CarPatchHandle createAudioPatch(String sourceAddress, int
+ carUsage)</code>. Routes the source addresses to the output <code>BUS</code>
+ associated with the provided <code>carUsage</code>.</li>
+ <li><code>int releaseAudioPatch(CarPatchHandle patch)</code>. Removes the
+ provided patch. If the creator of the <code>CarPatchHandle</code> dies
+ unexpectedly, this is handled automatically by
+ <code>AudioPolicyService::removeNotificationClient()</code>.</li>
+</ul>
+
+<h2 id="create-audio-patches">Creating audio patches</h2>
+
+<p>
+ You can create an audio patch between two audio ports, either a mix port or a
+ device port. Typically, an audio patch from mix port to device port is for
+ playback while the reverse direction is for capture.</p>
+
+<p>
+ For example, an audio patch that routes audio samples from <code>FM_TUNER</code>
+ source directly to media sink bypasses the software mixer. You must then use a
+ hardware mixer to mix the audio samples from Android and <code>FM_TUNER</code>
+ for the sink. When creating an audio patch directly from <code>FM_TUNER</code>
+ source to the media sink:
+</p>
+
+<ul>
+ <li>Volume control applies to the media sink and should affect both the
+ Android and <code>FM_TUNER</code> audio.</li>
+ <li>Users should be able to switch between Android and <code>FM_TUNER</code>
+ audio via a simple app switch (no explicit media source choice should be
+ necessary).</li>
+</ul>
+
+<p>
+ Automotive implementations might also need to create an audio patch between
+ two device ports. To do so, you must first declare the device ports and
+ possible routes in <code>audio_policy_configuration.xml</code> and associate
+ mixports with these device ports.
+</p>
+
+<h3 id="example-config">Example configuration</h3>
+
+<p>
+ See also
+ <code>device/generic/car/emulator/audio/audio_policy_configuration.xml</code>.
+</p>
+
+<pre class="prettyprint">
+<audioPolicyConfiguration>
+ <modules>
+ <module name="primary" halVersion="3.0">
+ <attachedDevices>
+ <item>bus0_media_out</item>
+ <item>bus1_audio_patch_test_in</item>
+ </attachedDevices>
+ <mixPorts>
+ <mixPort name="mixport_bus0_media_out" role="source"
+ flags="AUDIO_OUTPUT_FLAG_PRIMARY">
+ <profile name="" format="AUDIO_FORMAT_PCM_16_BIT"
+ samplingRates="48000"
+ channelMasks="AUDIO_CHANNEL_OUT_STEREO"/>
+ </mixPort>
+ <mixPort name="mixport_audio_patch_in" role="sink">
+ <profile name="" format="AUDIO_FORMAT_PCM_16_BIT"
+ samplingRates="48000"
+ channelMasks="AUDIO_CHANNEL_IN_STEREO"/>
+ </mixPort>
+ </mixPorts>
+ <devicePorts>
+ <devicePort tagName="bus0_media_out" role="sink" type="AUDIO_DEVICE_OUT_BUS"
+ address="bus0_media_out">
+ <profile balance="" format="AUDIO_FORMAT_PCM_16_BIT"
+ samplingRates="48000" channelMasks="AUDIO_CHANNEL_OUT_STEREO"/>
+ <gains>
+ <gain name="" mode="AUDIO_GAIN_MODE_JOINT"
+ minValueMB="-8400" maxValueMB="4000" defaultValueMB="0" stepValueMB="100"/>
+ </gains>
+ </devicePort>
+ <devicePort tagName="bus1_audio_patch_test_in" type="AUDIO_DEVICE_IN_BUS" role="source"
+ address="bus1_audio_patch_test_in">
+ <profile name="" format="AUDIO_FORMAT_PCM_16_BIT"
+ samplingRates="48000" channelMasks="AUDIO_CHANNEL_IN_STEREO"/>
+ <gains>
+ <gain name="" mode="AUDIO_GAIN_MODE_JOINT"
+ minValueMB="-8400" maxValueMB="4000" defaultValueMB="0" stepValueMB="100"/>
+ </gains>
+ </devicePort>
+ </devicePorts>
+ <routes>
+ <route type="mix" sink="bus0_media_out" sources="mixport_bus0_media_out,bus1_audio_patch_test_in"/>
+ <route type="mix" sink="mixport_audio_patch_in" sources="bus1_audio_patch_test_in"/>
+ </routes>
+ </module>
+ </modules>
+</audioPolicyConfiguration>
+</pre>
+
+<h3 id=audio-driver-api>Audio driver API</h3>
+
+<p>
+ You can use <code>getExternalSources()</code> to retrieve a list of available
+ sources (identified by address), then create audio patches between these
+ sources and the sink ports by audio usages. The corresponding entry points on
+ the Audio HAL appear in <code>IDevice.hal</code>:
+</p>
+
+<pre class="prettyprint">
+Interface IDevice {
+...
+/**
+* Creates an audio patch between several source and sink ports. The handle
+* is allocated by the HAL and must be unique for this audio HAL module.
+*
+* @param sources patch sources.
+* @param sinks patch sinks.
+* @return retval operation completion status.
+* @return patch created patch handle.
+*/
+createAudioPatch(vec<AudioPortConfig> sources, vec<AudioPortConfig> sinks)
+ generates (Result retval, AudioPatchHandle patch);
+
+/**
+* Release an audio patch.
+*
+* @param patch patch handle.
+* @return retval operation completion status.
+*/
+releaseAudioPatch(AudioPatchHandle patch) generates (Result retval);
+...
+}
+</pre>
+
+<aside class="note"><strong>Note:</strong> These API hooks have been available
+since AUDIO_DEVICE_API_VERSION_3_0. For more details, refer to
+<code>device/generic/car/emulator/audio/driver/audio_hw.c</code>.</aside>
+
+<h2 id="configure-volume-settings-ui">Configuring the volume settings UI</h2>
+
+<p>
+ Android {{ androidPVersionNumber }} decouples the volume settings UI from
+ volume group configuration (which can be overlaid as described in Configuring
+ volume groups). This separation ensures that no changes are required if the
+ volume groups configuration changes in the future.
+</p>
+
+<p>
+ In car settings UI, the
+ <code>packages/apps/Car/Settings/res/xml/car_volume_items.xml</code> file
+ contains UI elements (title and icon resources) associated with each defined
+ <code>AudioAttributes.USAGE</code>. This file provides for a reasonable
+ rendering of the defined VolumeGroups by using resources associated with the
+ first recognized usage contained in each VolumeGroup.
+</p>
+
+<p>
+ For example, the following example defines a VolumeGroup as including both
+ <code>voice_communication</code> and
+ <code>voice_communication_signalling</code>. The default implementation of the
+ car settings UI renders the VolumeGroup using the resources associated with
+ <code>voice_communication</code> as that is the first match in the file.
+</p>
+
+<pre class="prettyprint">
+<carVolumeItems xmlns:car="http://schemas.android.com/apk/res-auto">
+ <item car:usage="voice_communication"
+ car:title="@*android:string/volume_call"
+ car:icon="@*android:drawable/ic_audio_ring_notif"/>
+ <item car:usage="voice_communication_signalling"
+ car:title="@*android:string/volume_call"
+ car:icon="@*android:drawable/ic_audio_ring_notif"/>
+ <item car:usage="media"
+ car:title="@*android:string/volume_music"
+ car:icon="@*android:drawable/ic_audio_media"/>
+ <item car:usage="game"
+ car:title="@*android:string/volume_music"
+ car:icon="@*android:drawable/ic_audio_media"/>
+ <item car:usage="alarm"
+ car:title="@*android:string/volume_alarm"
+ car:icon="@*android:drawable/ic_audio_alarm"/>
+ <item car:usage="assistance_navigation_guidance"
+ car:title="@string/navi_volume_title"
+ car:icon="@drawable/ic_audio_navi"/>
+ <item car:usage="notification_ringtone"
+ car:title="@*android:string/volume_ringtone"
+ car:icon="@*android:drawable/ic_audio_ring_notif"/>
+ <item car:usage="assistant"
+ car:title="@*android:string/volume_unknown"
+ car:icon="@*android:drawable/ic_audio_vol"/>
+ <item car:usage="notification"
+ car:title="@*android:string/volume_notification"
+ car:icon="@*android:drawable/ic_audio_ring_notif"/>
+ <item car:usage="notification_communication_request"
+ car:title="@*android:string/volume_notification"
+ car:icon="@*android:drawable/ic_audio_ring_notif"/>
+ <item car:usage="notification_communication_instant"
+ car:title="@*android:string/volume_notification"
+ car:icon="@*android:drawable/ic_audio_ring_notif"/>
+ <item car:usage="notification_communication_delayed"
+ car:title="@*android:string/volume_notification"
+ car:icon="@*android:drawable/ic_audio_ring_notif"/>
+ <item car:usage="notification_event"
+ car:title="@*android:string/volume_notification"
+ car:icon="@*android:drawable/ic_audio_ring_notif"/>
+ <item car:usage="assistance_accessibility"
+ car:title="@*android:string/volume_notification"
+ car:icon="@*android:drawable/ic_audio_ring_notif"/>
+ <item car:usage="assistance_sonification"
+ car:title="@*android:string/volume_unknown"
+ car:icon="@*android:drawable/ic_audio_vol"/>
+ <item car:usage="unknown"
+ car:title="@*android:string/volume_unknown"
+ car:icon="@*android:drawable/ic_audio_vol"/>
+</carVolumeItems>
+</pre>
+
+<p>
+ The attributes and values used in the above configuration are declared in
+ <code>packages/apps/Car/Settings/res/values/attrs.xml</code>. The volume
+ settings UI uses the following <code>VolumeGroup</code>-based
+ <code>CarAudioManager</code> APIs:
+</p>
+
+<ul>
+ <li><code>getVolumeGroupCount()</code> to know how many controls should be
+ drawn.</li>
+ <li><code>getGroupMinVolume()</code> and <code>getGroupMaxVolume()</code> to
+ get lower and upper bounds.</li>
+ <li><code>getGroupVolume()</code> to get the current volume.</li>
+ <li><code>registerVolumeChangeObserver()</code> to get notified on volume
+ changes.</li>
+</ul>
+
+</body>
+</html>
\ No newline at end of file
diff --git a/en/devices/automotive/audio/audio-hal.html b/en/devices/automotive/audio/audio-hal.html
new file mode 100644
index 0000000..f619f50
--- /dev/null
+++ b/en/devices/automotive/audio/audio-hal.html
@@ -0,0 +1,244 @@
+<html devsite>
+ <head>
+ <title>Implementing the Audio HAL</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ {% include "_versions.html" %}
+ <body>
+ <!--
+ Copyright 2018 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>
+ Automotive audio implementations rely on the standard
+ <a href="/devices/audio/implement"> Android Audio HAL</a>, which includes the
+ following:
+</p>
+
+<ul>
+ <li><code><strong>IDevice</code></strong>
+ (<code>hardware/interfaces/audio/2.0/IDevice.hal</code>). Creates input and
+ output streams, handles master volume and muting, and uses:
+ <ul>
+ <li><code>createAudioPatch</code> to create external-external patches
+ between devices.</li>
+ <li><code>IDevice.setAudioPortConfig()</code> to provide volume for each
+ physical stream.</li>
+ </ul>
+ <li><code><strong>IStream</code></strong>
+ (<code>hardware/interfaces/audio/2.0/IStream.hal</code>). Along with its In
+ and Out variants, manages the actual streaming of audio samples to and from
+ the hardware.</li>
+</ul>
+
+<h2 id="automotive-device-types">Automotive device types</h2>
+
+<p>
+The following device types are relevant for automotive platforms:
+</p>
+
+<table>
+<thead>
+<tr>
+<th>Device type</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>AUDIO_DEVICE_OUT_BUS</td>
+<td>Primary output from Android (this is how all audio from Android is
+delivered to the vehicle). Used as the address for disambiguating streams
+for each Context.</td>
+</tr>
+<tr>
+<td>AUDIO_DEVICE_OUT_TELEPHONY_TX</td>
+<td>Used for audio routed to the cellular radio for transmission.</td>
+</tr>
+<tr>
+<td>AUDIO_DEVICE_IN_BUS</td>
+<td>Used for inputs not otherwise classified.</td>
+</tr>
+<tr>
+<td>AUDIO_DEVICE_IN_FM_TUNER</td>
+<td>Used only for broadcast radio input.</td>
+</tr>
+<tr>
+<td>AUDIO_DEVICE_IN_TV_TUNER</td>
+<td>May be used for a TV device if present.</td>
+</tr>
+<tr>
+<td>AUDIO_DEVICE_IN_LINE</td>
+<td>Used for AUX input jack.</td>
+</tr>
+<tr>
+<td>AUDIO_DEVICE_IN_BLUETOOTH_A2DP</td>
+<td>Music received over Bluetooth.</td>
+</tr>
+<tr>
+<td>AUDIO_DEVICE_IN_TELEPHONY_RX</td>
+<td>Used for audio received from the cellular radio associated with a phone
+call.</td>
+</tr>
+</tbody>
+</table>
+
+<h2 id="route-audio-sources">Routing audio sources</h2>
+
+<p>
+ Most audio sources should be captured using <code>AudioRecord</code> or a
+ related Android mechanism. The data can then be assigned
+ <a href="/devices/audio/attributes">AudioAttributes</a> and played through
+ <code>AndroidTrack</code> either by relying on the default Android routing
+ logic or by explicitly calling <code>setPreferredDevice()</code> on the
+ <code>AudioRecord</code> and/or <code>AudioTrack</code> objects.
+<p>
+
+<p>
+ For sources with dedicated hardware connections to the external mixer or
+ with extremely tight latency requirements, you can use
+ <code>createAudioPatch()</code> and <code>releaseAudioPatch()</code> to
+ activate and deactivate routes between external devices (without involving
+ <code>AudioFlinger</code> in the transport of samples).
+</p>
+
+<h2 id="configure-audio-devices">Configuring audio devices</h2>
+
+<p>
+ Audio devices visible to Android must be defined in
+ <code>system/etc/audio_policy_configuration.xml</code>, which includes the
+ following components:
+</p>
+
+<ul>
+ <li><strong>module name</strong>. Supports "primary" (used for automotive
+ use cases), "A2DP", "remote_submix", and "USB". The module name and the
+ corresponding audio driver should be compiled to
+ <code>audio.primary.$(variant).so</code>.</li>
+ <li><strong>devicePorts</strong>. Contains a list of device descriptors for
+ all input and output devices (includes permanently attached devices and
+ removable devices) that are accessible from this module.
+ <ul>
+ <li>For each output device, you can define gain control that consists of
+ min/value/step/default values in millibel (1 millibel = 1/100 dB = 1/1000
+ bel).</li>
+ <li>The address attribute on a <code>devicePort</code> can be used to find
+ the device, even if there are multiple devices with the same device type
+ as <code>AUDIO_DEVICE_OUT_BUS</code>.</li>
+ </ul>
+ <li><strong>mixPorts</strong>. Contains a list of all output and input streams
+ exposed by the audio HAL. Each <code>mixPort</code> can be considered as a
+ physical stream to Android <code>AudioService</code>.</li>
+ <li><strong>routes</strong>. Defines a list of possible connections between
+ input and output devices or between stream and device.</li>
+</ul>
+
+<p>
+ The following example defines an output device <code>bus0_phone_out</code> in
+ which all Android audio streams are mixed by
+ <code>mixer_bus0_phone_out</code>. The route takes output stream of
+ <code>mixer_bus0_phone_out</code> to <code>device bus0_phone_out</code>.
+</p>
+
+<pre class="prettyprint">
+<audioPolicyConfiguration version="1.0" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <modules>
+ <module name="primary" halVersion="3.0">
+ <attachedDevices>
+ <item>bus0_phone_out</item>
+<defaultOutputDevice>bus0_phone_out</defaultOutputDevice>
+ <mixPorts>
+ <mixPort name="mixport_bus0_phone_out"
+ role="source"
+ flags="AUDIO_OUTPUT_FLAG_PRIMARY">
+ <profile name="" format="AUDIO_FORMAT_PCM_16_BIT"
+ samplingRates="48000"
+ channelMasks="AUDIO_CHANNEL_OUT_STEREO"/>
+ </mixPort>
+ </mixPorts>
+ <devicePorts>
+ <devicePort tagName="bus0_phone_out"
+ role="sink"
+ type="AUDIO_DEVICE_OUT_BUS"
+ address="BUS00_PHONE">
+ <profile name="" format="AUDIO_FORMAT_PCM_16_BIT"
+ samplingRates="48000"
+ channelMasks="AUDIO_CHANNEL_OUT_STEREO"/>
+ <gains>
+ <gain name="" mode="AUDIO_GAIN_MODE_JOINT"
+ minValueMB="-8400"
+ maxValueMB="4000"
+ defaultValueMB="0"
+ stepValueMB="100"/>
+ </gains>
+ </devicePort>
+ </devicePorts>
+ <routes>
+ <route type="mix" sink="bus0_phone_out"
+ sources="mixport_bus0_phone_out"/>
+ </routes>
+ </module>
+ </modules>
+</audioPolicyConfiguration>
+</pre>
+
+<h2 id="device-ports">Specifying devicePorts</h2>
+
+<p>
+ Automotive platforms should specify a <code>devicePort</code> for each
+ physical stream that is input to and output from Android. For output,
+ <code>devicePorts</code> should be of type <code>AUDIO_DEVICE_OUT_BUS</code>,
+ and addressed by integers (i.e., Bus 0, Bus 1, etc.). <code>mixPort</code>s
+ should be created in 1:1 relation to the <code>devicePorts</code> and should
+ allow specification of the data formats that can be routed to each bus.
+</p>
+
+<p>
+ Automotive implementations can use multiple input device types, including
+ <code>FM_TUNER</code> (reserved for broadcast radio input), <code>MIC</code>
+ device for handling microphone input, and <code>TYPE_AUX_LINE</code> for
+ representing analog line input. All other input streams are assigned to the
+ <code>AUDIO_DEVICE_IN_BUS</code> and discovered by enumerating the devices via
+ a <code>AudioManager.getDeviceList()</code> call. Individual sources can be
+ differentiated by their <code>AudioDeviceInfo.getProductName()</code>.
+ <p>
+
+<p>
+ You can also define external devices as ports, then use those ports to
+ interact with external hardware with the
+ <code>IDevice::createAudioPatch</code> method of the Audio HAL (exposed via a
+ new <code>CarAudioManager</code> entry point).
+</p>
+
+<p>
+ When the BUS-based audio driver is present, you must set the
+ <code>audioUseDynamicRouting</code> flag to <code>true</code>:
+</p>
+
+<pre class="prettyprint">
+<resources>
+ <bool name="audioUseDynamicRouting">true</bool>
+</resources>
+</pre>
+
+<p>
+ For details, refer to
+ <code>device/generic/car/emulator/audio/overlay/packages/services/Car/service/res/values/config.xml</code>.
+</p>
+
+</body>
+</html>
\ No newline at end of file
diff --git a/en/devices/automotive/audio/index.html b/en/devices/automotive/audio/index.html
new file mode 100644
index 0000000..3573724
--- /dev/null
+++ b/en/devices/automotive/audio/index.html
@@ -0,0 +1,365 @@
+<html devsite>
+ <head>
+ <title>Automotive Audio</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ {% include "_versions.html" %}
+ <body>
+ <!--
+ Copyright 2018 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>
+ This section details the audio architecture for automotive-related Android
+ implementations. OEMs and other Android developers implementing an automotive
+ audio system should review all content in this section thoroughly in addition
+ to content in the main <a href="/devices/audio/">Audio</a> section.
+</p>
+
+<h2 id="key-concepts">Key concepts</h2>
+
+<p>
+ Android is responsible for infotainment sounds (i.e. media, navigation, and
+ communications) but is not directly responsible for chimes and warnings that
+ have strict availability and timing requirements. External sources are
+ represented by applications, which are responsible for audio focus. However,
+ you cannot rely on focus for sound selection and mixing.
+</p>
+
+<p>
+ Android {{ androidPVersionNumber }} includes the following changes to
+ automotive-related audio support:
+</p>
+
+<ul>
+ <li>The Audio HAL Context maps to <code>AudioAttributes.usage</code> to
+ identify sounds; the Audio HAL implementation is responsible for
+ Context-specific mixing/routing.</li>
+ <li>Vehicles define a generic output device
+ (<code>AUDIO_DEVICE_OUT_BUS</code>) for use in vehicle audio systems; Android
+ supports one <code>AUDIO_DEVICE_OUT_BUS</code> per Context.</li>
+ <li><code>IAudioControl HAL</code> provides vehicle-specific extensions to the
+ Audio HAL; for an example implementation, refer to
+ <code>device/generic/car/emulator/audio</code>. Android
+ {{ androidPVersionNumber }} does not include <code>AUDIO_* VHAL</code>
+ properties.</li>
+</ul>
+
+<h2 id="android-sounds-streams">Android sounds and streams</h2>
+
+<p>
+ Automotive audio systems handle the following sounds and streams:
+</p>
+
+<img src="/devices/automotive/images/audio_streams_all.png">
+<figcaption><strong>Figure 1.</strong> Stream-centric architecture diagram
+</figcaption>
+
+<p>
+ Android is responsible for sounds coming from Android applications,
+ controlling those applications and routing their sounds to individual streams
+ at the HAL based on the type of sound:
+</p>
+
+<ul>
+ <li><strong>Logical</strong> streams, known as <em>sources</em> in core audio
+ nomenclature, are tagged with <a href="/devices/audio/attributes">Audio
+ Attributes</a>.</li>
+ <li><strong>Physical</strong> streams, known as <em>devices</em> in core audio
+ nomenclature, have no context information after mixing.</li>
+</ul>
+
+<p>
+ For reliability, external sounds (coming from independent sources such as seat
+ belt warning chimes) are managed outside Android, below the HAL or even in
+ separate hardware. System implementers must provide a mixer that accepts one
+ or more streams of sound input from Android and then combines those streams in
+ a suitable way with the external sound sources required by the vehicle.
+ External streams can be always on, or controlled via
+ <code>createAudioPatch</code> entry points in the HAL.
+</p>
+
+<p>
+ The HAL implementation and external mixer are responsible for ensuring the
+ safety-critical external sounds are heard and for mixing in the
+ Android-provided streams and routing them to suitable speakers.
+</p>
+
+<h3 id="android-sounds">Android sounds</h3>
+
+<p>
+ Applications may have one or more players that interact through the standard
+ Android APIs (e.g.
+ <a href="https://developer.android.com/reference/android/media/AudioManager.html" class="external">AudioManager</a>
+ for focus control or
+ <a href="https://developer.android.com/reference/android/media/MediaPlayer.html" class="external">MediaPlayer</a>
+ for streaming) to emit one or more logical streams of audio data. This data
+ could be single channel mono or 7.1 surround, but is routed and treated as a
+ single source. The application stream is associated with
+ <a href="/devices/audio/attributes">AudioAttributes</a> that give the system
+ hints about how the audio should be expressed.
+</p>
+
+<p>
+ The logical streams are sent through the <code>AudioService</code> and routed
+ to one (and only one) of the available physical output streams, each of which
+ is the output of a mixer within <code>AudioFlinger</code>. After
+ <code>AudioAttributes</code> have been mixed down to a physical stream, they
+ are no longer available.
+</p>
+
+<p>
+ Each physical stream is then delivered to the Audio HAL for rendering on the
+ hardware. In automotive applications, rendering hardware can be local codecs
+ (similar to mobile devices) or a remote processor across the vehicle's
+ physical network. Either way, it is the job of the Audio HAL implementation to
+ deliver the actual sample data and cause it to become audible.
+</p>
+
+<h3 id="external-streams">External streams</h3>
+
+<p>
+ Sound streams that should not be routed through Android (for certification or
+ timing reasons) may be sent directly to the external mixer. In many cases,
+ Android doesn't need to know these sounds exist as the external mixer can mix
+ them over Android sounds. If a sound needs to be ducked or routed to different
+ speakers, the external mixer can do that invisibly to Android.
+</p>
+
+<p>
+ If external streams are media sources that should interact with the sound
+ environment Android is generating (e.g. stop MP3 playback when an external
+ tuner is turned on), those external streams should be represented by an
+ Android app. Such an app would request audio focus and respond to focus
+ notifications by starting/stopping the external source as necessary to fit
+ into the Android focus policy. One suggested mechanism to control such
+ external devices is <code>AudioManager.createAudioPatch()</code>.
+</p>
+
+<h3 id="audio-focus">Audio focus</h3>
+
+<p>
+ Before starting a logical stream, an application should request audio focus
+ using the same <code>AudioAttributes</code> as it will use for its logical
+ stream. While sending such a focus request is recommended, it is not enforced
+ by the system. Some applications may explicitly skip sending the request to
+ achieve specific behaviors (e.g. to intentionally play sound during a phone
+ call).
+</p>
+
+<p>
+ For this reason, you should consider focus as a way to indirectly control
+ and deconflict media playback and not as a primary audio control
+ mechanism—the vehicle should not depend on the focus system for operation of
+ the audio subsystem. Focus awareness is <strong>not part of the HAL</strong>
+ and should <strong>not be used to influence audio routing</strong>.
+</p>
+
+<h3 id="output-bus">Output BUS</h3>
+
+<p>
+ At the Audio HAL level, the device type <code>AUDIO_DEVICE_OUT_BUS</code>
+ provides a generic output device for use in vehicle audio systems. The BUS
+ device supports addressable ports (where each port is the end point for a
+ physical stream) and is expected to be the only supported output device type
+ in a vehicle.
+</p>
+
+<p>
+ A system implementation can use one BUS port for all Android sounds, in which
+ case Android mixes everything together and delivers it as one stream.
+ Alternatively, the HAL can provide one BUS port for each Context to allow
+ concurrent delivery of any sound type. This makes it possible for the HAL
+ implementation to mix or duck the different sounds as desired.</p>
+
+<p>
+ The assignment of Contexts to BUS ports is done through the Audio Control
+ HAL and creates a many:one relationship between Contexts and BUS ports.
+</p>
+
+<h2 id="mic-input">Microphone input</h2>
+
+<p>
+ When capturing audio, the Audio HAL receives an <code>openInputStream</code>
+ call that includes an <code>AudioSource</code> argument indicating how the
+ microphone input should be processed.</p>
+
+<p>
+ <code>VOICE_RECOGNITION</code> (specifically the Google Assistant) expects a
+ stereo microphone stream that has an echo cancellation effect (if available)
+ but no other processing applied to it. Beamforming is expected to be done by
+ the Assistant itself.
+</p>
+
+<h3 id="multi-channel-mic-input">Multi-channel microphone input</h3>
+
+<p>
+ To capture audio from a device with more than two channels (stereo), use a
+ channel index mask instead of positional index mask (such as
+ <code>CHANNEL_IN_LEFT</code>). Example:
+</p>
+
+<pre class="prettyprint">
+final AudioFormat audioFormat = new AudioFormat.Builder()
+ .setEncoding(AudioFormat.ENCODING_PCM_16BIT)
+ .setSampleRate(44100)
+ .setChannelIndexMask(0xf /* 4 channels, 0..3 */)
+ .build();
+final AudioRecord audioRecord = new AudioRecord.Builder()
+ .setAudioFormat(audioFormat)
+ .build();
+audioRecord.setPreferredDevice(someAudioDeviceInfo);
+</pre>
+
+<p>
+ When both <code>setChannelMask</code> and <code>setChannelIndexMask</code>
+ are set, <code>AudioRecord</code> uses only the value set by
+ <code>setChannelMask</code> (maximum of two channels).
+</p>
+
+<h3 id="concurrent-capture">Concurrent capture</h3>
+
+<p>
+ The Android framework does not allow concurrent capture for most input audio
+ device types but makes exceptions for <code>AUDIO_DEVICE_IN_BUS</code> and
+ <code>AUDIO_DEVICE_IN_FM_TUNER</code> by handling them as virtual devices.
+ Doing so means the framework assumes no competition for resources exists
+ between/among these devices and thus any/all of them are allowed to be
+ captured concurrently along with one regular input device (such as the
+ microphone). If hardware constraints on concurrent capture do exist
+ between/among these devices, such constraints must be handled by custom
+ application logic in the first party applications designed to use these input
+ devices.
+</p>
+
+<p>
+ Applications designed to work with <code>AUDIO_DEVICE_IN_BUS</code> devices or
+ with secondary <code>AUDIO_DEVICE_IN_FM_TUNER</code> devices must rely on
+ explicitly identifying those devices and using
+ <code>AudioRecord.setPreferredDevice()</code> to bypass the Android default
+ source selection logic.
+</p>
+
+<h2 id="volume-and-groups">Volume and volume groups</h2>
+
+<p>
+ Android 8.x and lower supports three volume groups (ring, media, and alarm)
+ along with a hidden group for phone in-call. Each group can be set to a
+ different volume level based on the output device, such as higher volumes for
+ speakers and lower volumes for headsets).
+</p>
+
+<p>
+ Android {{ androidPVersionNumber }} adds a <em>speech</em> volume group and
+ the automotive-related contexts as shown below:
+</p>
+
+<table>
+<thead>
+<tr>
+<th>Volume group</th>
+<th>Audio contexts</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Ring</td>
+<td>CALL_RING_CONTEXT</td>
+<td>Voice call ringing</td>
+</tr>
+<tr>
+<td></td>
+<td>NOTIFICATION_CONTEXT</td>
+<td>Notifications</td>
+</tr>
+<tr>
+<td></td>
+<td>ALARM_CONTEXT</td>
+<td>Alarm sound from Android</td>
+</tr>
+<tr>
+<td></td>
+<td>SYSTEM_SOUND_CONTEXT</td>
+<td>System sound from Android</td>
+</tr>
+<tr>
+<td>Media</td>
+<td>MUSIC_CONTEXT</td>
+<td>Music playback</td>
+</tr>
+<tr>
+<td>Phone</td>
+<td>CALL_CONTEXT</td>
+<td>Voice call</td>
+</tr>
+<tr>
+<td>Speech</td>
+<td>NAVIGATION_CONTEXT</td>
+<td>Navigation directions</td>
+</tr>
+<tr>
+<td></td>
+<td>VOICE_COMMAND_CONTEXT</td>
+<td>Voice command session</td>
+</tr>
+</tbody>
+</table>
+
+<p>
+ When the value for a volume group is updated, the framework's
+ <code>CarAudioService</code> handles setting the affected physical stream
+ gains. Physical stream volume in a vehicle is based on volume group (rather
+ than stream_type) and each volume group consists of one or more Audio
+ Contexts. Each <code>AudioAttributes.USAGE</code> maps to an Audio Context in
+ a <code>CarAudioService</code> and can be configured to be routed to an output
+ bus (see
+ <a href="/devices/automotive/audio/audio-control.html#configure-volume">Configuring
+ volume</a> and
+ <a href="/devices/automotive/audio/audio-control.html#configure-volume-groups">Configuring
+ volume groups</a>).
+</p>
+
+<p>
+ Android {{ androidPVersionNumber }} simplifies controlling the hardware volume
+in the amplifier:
+</p>
+
+<ul>
+ <li>Each volume group is routed to one or more output buses. The volume for a
+ specific group can be changed using the Car Settings UI or via an
+ externally-generated
+ <code>KEYCODE_VOLUME_DOWN</code> or <code>KEYCODE_VOLUME_UP</code> key event.
+ </li>
+ <li>In response, <code>CarAudioService</code> calls
+ <code>AudioManager.setAudioPortGain()</code> with the audio device port(s)
+ bound to targeted volume group. At the HAL, this appears as a series of one or
+ more calls to <code>IDevice.setAudioPortConfig()</code> with the volume gain
+ value for each physical output stream associated with the targeted volume
+ group.</li>
+</ul>
+
+<p>
+ You can configure the maximum, minimum, and step gain value for each audio
+ device port in <code>audio_policy_configuration.xml</code>. For a sample
+ configuration and details on overriding the default set of volume groups, see
+ <a href="/devices/automotive/audio/audio-hal.html#configure-audio-devices">Configuring
+ audio devices.
+</p>
+
+</body>
+</html>
\ No newline at end of file
diff --git a/en/devices/automotive/audio/interaction-sequences.html b/en/devices/automotive/audio/interaction-sequences.html
new file mode 100644
index 0000000..c0fb3b6
--- /dev/null
+++ b/en/devices/automotive/audio/interaction-sequences.html
@@ -0,0 +1,188 @@
+<html devsite>
+ <head>
+ <title>Example Interaction Sequences</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ {% include "_versions.html" %}
+ <body>
+ <!--
+ Copyright 2018 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>
+ In the following automotive audio examples, the vehicle head unit runs
+ Android {{ androidPVersionNumber }} and includes a radio application and a
+ navigation application. In addition, the vehicle tuner is externally routed
+ and plays over the speakers. In real-world use cases, it may be advantageous
+ to handle the tuner as an input to Android and have the Radio app read from
+ the tuner and write to an <code>AudioTrack</code> object.
+</p>
+
+<h2 id="user-starts-radio">User starts radio</h2>
+
+<p>
+ In this interaction sequence, no media is playing in the vehicle when the user
+ presses <strong>Play</strong> for a preset frequency in the radio application.
+ The radio application must gain focus for the tuner to play sound over the
+ speakers.
+</p>
+
+<p><img src="/devices/automotive/images/audio_auto_focus_radio.png"></p>
+<figcaption><strong>Figure 1.</strong> Radio gains focus and tuner play over
+speakers</figcaption>
+
+<ol>
+ <li>Radio: "Tune to FM 96.5."</li>
+ <li>Radio: Request focus GAIN.</li>
+ <li>AudioManager: GAIN granted.</li>
+ <li>Radio: <code>createAudioPatch()</code></li>
+ <li>Radio: "Play tuner output."</li>
+ <li>Externally-routed tuner: Mixer enables Tuner audio route to amplifier.
+ </li>
+</ol>
+
+<h2 id="radio-ducks-nav-prompt">Radio ducks navigation prompt</h2>
+
+<p>
+ In this interaction sequence, the radio is playing when the navigation
+ application generates a navigation prompt for a next turn announcement. The
+ navigation application must obtain transient focus from the
+ <code>AudioManager</code> to play the navigation prompt.
+</p>
+
+<p><img src="/devices/automotive/images/audio_auto_radio_ducks.png"></p>
+<figcaption><strong>Figure 2.</strong> Radio playback ducks navigation
+prompt</figcaption>
+
+<ol>
+ <li value="5">Radio: "Play tuner output."</li>
+ <li>Externally-routed tuner: Mixer enables Tuner audio route to amplifier.
+ </li>
+ <li>Navigation: Request focus GAIN TRANSIENT from <code>AudioManager</code>.
+ </li>
+ <li>AudioManager: GAIN TRANSIENT to Navigation.</li>
+ <li>Navigation: Open stream, send packets.
+ <ol>
+ <li>Navigation: Context GUIDANCE routed on bus1.</li>
+ <li>Mixer: Ducks Tuner to play bus1 GUIDANCE on Speakers.</li>
+ </ol>
+ </li>
+ <li>Navigation: Announcement over, close stream.</li>
+ <li>Navigation: Abandon focus.</li>
+</ol>
+
+<p>
+ The <code>AudioManager</code> recognizes the radio playback can duck and would
+ normally apply a ducking factor to the music stream without notifying the
+ radio application. However, the framework ducking is bypassed by overlaying
+ <code>framework/base/core/res/res/values/config.xml</code> and setting
+ <code>config_applyInternalDucking</code> to <code>false</code>, so the
+ external tuner continues to provide sound and the radio application remains
+ unaware of any changes. The mixer (below the HAL) is responsible for combining
+ the two inputs and can choose to duck radio playback or move radio playback to
+ the rear speakers.
+</p>
+
+<p>
+ When the navigation prompt is complete, the navigation application releases
+ focus and radio playback resumes.
+</p>
+
+<h2 id="user-launches-audio-book">User launches audio book application</h2>
+
+<p>
+ In this interaction sequence, the user launches an audio book application,
+ causing radio playback to stop (pressing play in a streaming music app would
+ be a similar trigger).
+</p>
+
+<p><img src="/devices/automotive/images/audio_auto_focus_book.png"></p>
+<figcaption><strong>Figure 3.</strong> Audio book takes focus from radio
+playback</figcaption>
+
+<ol>
+ <li value="12">Audio Book: Request GAIN context MEDIA from
+ <code>AudioManager</code>.</li>
+ <li>Radio loses focus:
+ <ol>
+ <li>AudioManager: LOSS.</li>
+ <li>Radio: <code>releaseAudioPatch()</code></li>
+ </ol>
+ </li>
+ <li>Audio Book gains focus:
+ <ol>
+ <li>GAIN granted, Context MEDIA routed on bus0</li>
+ <li>Open stream, send MEDIA packets.</li>
+ </ol>
+ </li>
+</ol>
+
+<p>
+ The request for focus by the audio book application is not transient, and so
+ the previous focus holder (the radio application), receives a permanent focus
+ loss, to which the radio application responds by tearing down the patch to the
+ tuner. The mixer stops listening to the tuner and starts processing the audio
+ delivered via the Audio HAL (it may also optionally perform a cross fade as
+ part of the radio-to-audiobook transition).
+</p>
+
+<h2 id="nav-prompt-takes-focus">Navigation prompt takes focus</h2>
+
+<p>
+ In this interaction sequence, the audio book is playing when the navigation
+ application generates a navigation prompt.
+</p>
+
+<p><img src="/devices/automotive/images/audio_auto_focus_nav.png"></p>
+<figcaption><strong>Figure 4.</strong> Navigation prompt takes focus from audio
+book playback</figcaption>
+
+<ol>
+ <li value="15">Audio Book: Streaming MEDIA packets, focus no-concurrent.</li>
+ <li>Navigation: Request GAIN TRANSIENT.</li>
+ <li>AudioManager: LOSS TRANSIENT.</li>
+ <li>Audio Book: Stops.</li>
+ <li>Audio Manager: GAIN TRANSIENT granted.</li>
+ <li>Navigation: Open stream, send packets.
+ <ol>
+ <li>Navigation: Context GUIDANCE routed on bus1.</li>
+ <li>Mixer: Plays bus1 (GUIDANCE).</li>
+ </ol>
+ </li>
+ <li>Navigation: Announcement over, close stream.</li>
+ <li>Navigation: Abandon focus.</li>
+ <li>Audio Book: GAIN.</li>
+ <li>Audio Book: Restarts.</li>
+</ol>
+
+<p>
+ Because the original audio book application <code>AudioFocusRequest</code>
+ (sent when starting the <code>AudioTrack</code>) included the
+ <code>AUDIOFOCUS_FLAG_PAUSES_ON_DUCKABLE_LOSS</code> flag, the
+ <code>AudioManager</code> determines it cannot handle ducking for the audio
+ book app. Instead, <code>AudioManager</code> sends an
+ <code>AUDIOFOCUS_LOSS_TRANSIENT</code> message to the audio book app, which is
+ expected to respond by suspending its playback.
+</p>
+
+<p>
+ The navigation application can now play the navigation prompt without
+ interruption. When the navigation prompt is complete, the audio book regains
+ focus and resumes playback.
+</p>
+
+</body>
+</html>
\ No newline at end of file
diff --git a/en/devices/automotive/audio/multi-zone.html b/en/devices/automotive/audio/multi-zone.html
new file mode 100644
index 0000000..7e3e4ff
--- /dev/null
+++ b/en/devices/automotive/audio/multi-zone.html
@@ -0,0 +1,120 @@
+<html devsite>
+ <head>
+ <title>Multi-Zone Audio</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ {% include "_versions.html" %}
+ <body>
+ <!--
+ Copyright 2018 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>
+ While Android {{ androidPVersionNumber }} does not support multi-zone audio,
+ the Android audio teams have explored several possible approaches to
+ multi-zone audio. This section provides details on some of these approaches
+ that might be helpful to system implementers setting out to build rear-seat
+ entertainment (RSE) solutions.
+</p>
+
+<h2 id=user-cases>Use cases</h2>
+
+<ul>
+ <li>Radio in rear seats plays simultaneously with different media sources in
+ front seats.</li>
+ <li>Front seat passenger hears a different media source than the driver (e.g.
+ passenger plays a game on their own screen while driver views navigation on
+ the main screen).</li>
+ <li>Four different, independent audio zones: Driver, front seat passenger,
+ rear seat 1, rear-seat 2.</li>
+</ul>
+
+<h2 id="limitations">Limitations</h2>
+
+<p>
+ Android {{ androidPVersionNumber }} doesn't support multiple audio stacks
+ (zones) or different priorities natively due to the following limitations:
+</p>
+
+<ul>
+ <li>Android {{ androidPVersionNumber }} does not provide APIs that enable
+ applications to target a specific zone. Instead, applications must target the
+ audio type (media, announcement, etc.), which is selected from a pre-defined
+ set provided by Android. For example, Android does not currently support
+ defining the audio type as <strong>media</strong> for target <strong>zone
+ 2</strong>.</li>
+ <li>Physical Streams (provided by the AudioFlinger/internal mixer) do not
+ transport Context information (e.g. tagging within Logical Streams) after the
+ mixing; preventing the Audio HAL from routing specific Logical Streams to
+ different zones.</li>
+</ul>
+
+<h2 id="scenario-multiple-instances">Scenario: Use multiple instances</h2>
+
+<p>
+ This scenario uses multiple instances of Android automotive to effect
+ multi-zone audio.
+</p>
+
+<ul>
+ <li>Each zone has its own Android automotive instance that independently
+ manages zone content. Hardware below the HAL combines and coordinates the
+ output of multiple instances.</li>
+ <li>Instances exist on distinct hardware (i.e. tablets in the rear seat) or
+ share physical hardware via a hypervisor.</li>
+ <li>Output is statically assigned to vehicle speakers using a single primary
+ zone or dynamic assignments are made below the HAL.</li>
+ <li>First-party party apps (installed in every instance) collaborate via a
+ proprietary protocol to coordinate and route sounds to specific zones.
+ Alternatively, use ChromeCast functionality to communicate across different
+ instances and even devices.</li>
+</ul>
+
+<h2 id="scenario-target-secondary-zones">Scenario: Target secondary zones</h2>
+
+<p>
+ This scenario uses first-party applications to explicitly target secondary
+ zones (which are ignored by Android).
+</p>
+
+<ul>
+ <li>OEM defines additional output audio device ports in
+ <code>audio_policy_configuration.xml</code>.</li>
+ <li>First-party applications that implicitly know the vehicle configuration
+ can enumerate the available output ports and explicitly target any one of them
+ using the <code>AudioTrack.setPrefereceDevice()</code> API.</li>
+</ul>
+
+<h2 id="scenario-audio-policy-rules">Scenario: Use audio policy rules</h2>
+
+<p>
+ This scenario uses audio policy rules to dynamically add route-specific UIDs
+ to additional audio devices.
+</p>
+
+<ul>
+ <li>The audio routing engine defines routing rules based on the UID of the
+ requesting application.</li>
+ <li>A system-level service or launcher adds rules to send the output of a
+ specific application (UID) to a specific device associated with a secondary
+ zone.</li>
+ <li>These specific devices are defined in addition to those provided for
+ routing of the predefined audio contexts.</li>
+</ul>
+
+</body>
+</html>
\ No newline at end of file
diff --git a/en/devices/automotive/images/audio_auto_focus_book.png b/en/devices/automotive/images/audio_auto_focus_book.png
new file mode 100644
index 0000000..2331891
--- /dev/null
+++ b/en/devices/automotive/images/audio_auto_focus_book.png
Binary files differ
diff --git a/en/devices/automotive/images/audio_auto_focus_nav.png b/en/devices/automotive/images/audio_auto_focus_nav.png
new file mode 100644
index 0000000..e33282d
--- /dev/null
+++ b/en/devices/automotive/images/audio_auto_focus_nav.png
Binary files differ
diff --git a/en/devices/automotive/images/audio_auto_focus_radio.png b/en/devices/automotive/images/audio_auto_focus_radio.png
new file mode 100644
index 0000000..1337561
--- /dev/null
+++ b/en/devices/automotive/images/audio_auto_focus_radio.png
Binary files differ
diff --git a/en/devices/automotive/images/audio_auto_radio_ducks.png b/en/devices/automotive/images/audio_auto_radio_ducks.png
new file mode 100644
index 0000000..3c05eb2
--- /dev/null
+++ b/en/devices/automotive/images/audio_auto_radio_ducks.png
Binary files differ
diff --git a/en/devices/automotive/images/audio_streams_all.png b/en/devices/automotive/images/audio_streams_all.png
new file mode 100644
index 0000000..856392b
--- /dev/null
+++ b/en/devices/automotive/images/audio_streams_all.png
Binary files differ
diff --git a/en/devices/automotive/properties.html b/en/devices/automotive/properties.html
index 55baea9..4f50b86 100644
--- a/en/devices/automotive/properties.html
+++ b/en/devices/automotive/properties.html
@@ -75,53 +75,105 @@
(<code>value_type</code>):</p>
<ul>
-<li><code>INT32</code> (and array), <code>INT64</code>, <code>BOOLEAN</code>,
-<code>FLOAT</code> (and array), string, bytes.</li>
-<li>Zoned type has zone in addition to value.</li>
+<li><code>BYTES</code></li>
+<li><code>BOOLEAN</code></li>
+<li><code>FLOAT</code></li>
+<li><code>FLOAT[]</code></li>
+<li><code>INT32</code></li>
+<li><code>INT32[]</code></li>
+<li><code>INT64</code></li>
+<li><code>INT64[]</code></li>
+<li><code>STRING</code></li>
+</ul>
+<p>A zoned property may have more than one value, based on the number of zones
+supported by the property.</p>
+
+<h2 id=area_type>Area types</h2>
+<p>The vehicle HAL defines multiple area types:</p>
+<ul>
+<li><code>GLOBAL</code>
+<br>This property is a singleton and does not have multiple areas.</li>
+<li><code>WINDOW</code>
+<br>Area based on windows, uses <code>VehicleAreaWindow</code> enum.</li>
+<li><code>MIRROR</code>
+<br>Area based on mirrors, uses <code>VehicleAreaMirror</code> enum.</li>
+<li><code>SEAT</code>
+<br>Area based on seats, uses <code>VehicleAreaSeat</code> enum.</li>
+<li><code>DOOR</code>
+<br>Area based on doors, uses <code>VehicleAreaDoor</code> enum.</li>
+<li><code>WHEEL</code>
+<br>Area based on wheels, uses <code>VehicleAreaWheel</code> enum.</li>
+</ul>
+<p>Each zoned property must use pre-defined area type. Each area type has a
+set of bit flags defined in an enum for the area type. For example, the SEAT
+area defines VehicleAreaSeat enums:</p>
+<ul>
+<li><code>ROW_1_LEFT = 0x0001</code></li>
+<li><code>ROW_1_CENTER = 0x0002</code></li>
+<li><code>ROW_1_RIGHT = 0x0004</code></li>
+<li><code>ROW_2_LEFT = 0x0010</code></li>
+<li><code>ROW_2_CENTER = 0x0020</code></li>
+<li><code>ROW_2_RIGHT = 0x0040</code></li>
+<li><code>ROW_3_LEFT = 0x0100</code></li>
+<li>...</li>
</ul>
-<h2 id-=zone_type>Zone types</h2>
-<p>The vehicle HAL defines three zone types:</p>
+<h2 id=area_id>Area IDs</h2>
+<p>Zoned properties are addressed via Area IDs. Each zoned property may
+support one or more Area IDs. An Area ID is composed of one or more flags
+from its respective enum. For example, a property using
+<code>VehicleAreaSeat</code> might use the following Area IDs:</p>
<ul>
-<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>
+<li><code>ROW_1_LEFT | ROW_1_RIGHT</code>
+<br>The Area ID applies to both front seats.</li>
+<li><code>ROW_2_LEFT</code>
+<br>Only applies to rear left seat.</li>
+<li><code>ROW_2_RIGHT</code>
+<br>Only applies to rear right seat.</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>
+
+<h2 id=status>Property Status</h2>
+<p>Every property value comes with a <code>VehiclePropertyStatus</code> value.
+This indicates the current status for the property:
+<ul>
+<li><code>AVAILABLE</code>
+<br>Property is available and the value is valid.</li>
+<li><code>UNAVAILABLE</code>
+<br>Property value is currently unavailable. This is used for transiently
+disabled features for a supported property.</li>
+<li><code>ERROR</code>
+<br>Something is wrong with this property.</li>
+</ul>
+<aside class="note"><strong>Note:</strong> If a property is not supported by the
+vehicle, it should not be included in the VHAL. It is not acceptable to set the
+property status to <code>UNAVAILABLE</code> permanently to denote an unsupported
+property.</aside>
<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>
<li><code>access</code> (r, w, rw)</li>
-<li><code>change_mode</code> (represents how property is monitored: on change vs
+<li><code>changeMode</code> (represents how property is monitored: on change vs
continuous)</li>
-<li><code>min_value</code> (int32, float, int64), <code>max_value</code> (int32,
-float, int64)</li>
-<li><code>min_sample_rate</code>, <code>max_sample_rate</code></li>
-<li><code>permission_model</code></li>
+<li><code>areaConfigs</code> (areaId, min, and max values)</li>
+<li><code>configArray</code> (additional configuration parameters)</li>
+<li><code>configString</code> (additional information passed as a string)</li>
+<li><code>minSampleRate</code>, <code>max_sample_rate</code></li>
<li><code>prop</code> (Property ID, int)</li>
-<li><code>value_type</code></li>
-<li><code>zone_flags</code> (represents supported zones as bit flags)</li>
</ul>
-<p>In addition, some properties have specific configuration flags to represent
-capability.</p>
<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>
+each sub property is accessible by specified Area ID value.</p>
<ul>
-<li><code>get</code> call for zoned property always includes zone in request, so
-only the current value for the requested zone should be returned.</li>
-<li><code>set</code> call for zoned property always includes zone in request, so
-only the requested zone should be changed.</li>
-<li><code>subscribe</code> call includes flags of all zones subscribed. Events
-from un-subscribed zones should not be reported.</li>
+<li><code>get</code> call for zoned property always includes the Area ID in
+the request, so only the current value for the requested Area ID is returned.
+If the property is a global, then Area ID is 0.</li>
+<li><code>set</code> call for zoned property always includes the Area ID in the
+request, so only the requested Area ID is changed.</li>
+<li><code>subscribe</code> call will generate events for all Area IDs for the
+property.</li>
</ul>
<h3 id=get>Get calls</h3>
@@ -129,16 +181,8 @@
the matching vehicle network message has not yet been received. In such cases,
the <code>get</code> call should return <code>-EAGAIN</code>. Some properties
(such as HVAC) have separate on/off power property. Calling <code>get</code> for
-such a property (when powered off) should return a special value
-<code>(VEHICLE_INT_OUT_OF_RANGE_OFF/VEHICLE_FLOAT_OUT_OF_RANGE_OFF)</code>
-rather than returning an error.</p>
-<p>In addition, some properties (such as HVAC temperature) can have a value to
-indicate it is in max power mode rather than in specific temperature value. In
-such cases, use special values to represent such state.</p>
-<ul>
-<li>VEHICLE_INT_OUT_OF_RANGE_MAX/MIN</li>
-<li>VEHICLE_FLOAT_OUT_OF_RANGE_MAX/MIN</li>
-</ul>
+such a property (when powered off) should return a <code>UNAVAILABLE</code>
+status rather than returning an error.</p>
<p>Example: get HVAC Temperature</p>
<img src="../images/vehicle_hvac_get.png" alt="Vehicle HAL get HVAC example">
@@ -158,10 +202,7 @@
separate power on /off should return <code>-ESHUTDOWN</code> when the property
is powered off and set cannot be done.</p>
<p>Until <code>set</code> is made effective, <code>get</code> does not
-necessarily return the same value as what is set. The exception is a property
-with change mode of <code>VEHICLE_PROP_CHANGE_MODE_ON_SET.</code> This property
-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>
+necessarily return the same value as what is set.</p>
<p>Example: set HVAC Temperature</p>
<img src="../images/vehicle_hvac_set.png" alt="Vehicle HAL set HVAC example">
@@ -173,86 +214,152 @@
that are restricted to system apps. Use the following guidelines when working
with custom properties:</p>
<ul>
-<li>Key should be in [<code>VEHICLE_PROPERTY_CUSTOM_START,
-VEHICLE_PROPERTY_CUSTOM_END</code>] range. Other ranges are reserved for future
-extension; using such ranges can cause conflicts in future Android releases.</li>
-<li>Use only defined <code>value_type</code>. BYTES type allows passing raw
-data, so this is enough in most cases. Sending big data frequently through
-custom properties can slow down the whole vehicle network access, so be careful
-when you add a big payload.</li>
-<li>Add access policy into <code>vendor_vns_policy.xml</code> (otherwise, all
-access will be rejected).</li>
-<li>Access via <code>VendorExtensionManager</code> (for Java components) or
+<li>Property ID should be generated using the following fields:
+ <ul>
+ <li><code>VehiclePropertyGroup:VENDOR</code>
+ <br>The <code>VENDOR</code> group is used only for custom properties.</li>
+ <li><code>VehicleArea</code>
+ <br>Select an appropriate Area Type.</li>
+ <li><code>VehiclePropertyType</code>
+ <br>Select the proper data type. BYTES type allows passing raw
+ data, so this is enough in most cases. Sending big data frequently
+ through custom properties can slow down the whole vehicle network
+ access, so be careful when you add a big payload.</li>
+ <li>Property ID
+ <br>Choose a four nibble ID for the custom property.</li>
+ </ul></li>
+<li>Access via <code>CarPropertyManager</code> (for Java components) or
via Vehicle Network Service API (for native). Do not modify other car APIs as it
can lead to compatibility issues in the future.</li>
</ul>
<h2 id=prop_hvac>Handling HVAC properties</h2>
-<p>You can use the vehicle HAL to control HVAC by setting HVAC-related
-properties. Most HVAC properties are zoned properties, but a few are non-zoned
-(global) properties. Example properties defined include:</p>
+<p>
+ You can use the vehicle HAL to control HVAC by setting HVAC-related
+ 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>
-<br>Set temperature per zone.</li>
-<li><code>VEHICLE_PROPERTY_HVAC_RECIRC_ON</code>
-<br>Control recirculation per 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>
+
+<p>
+ For a full list of HVAC properties, search for
+ <code>VEHICLE_PROPERTY_HVAC_*</code> in <code>types.hal</code>.
+</p>
+
+<p>
+ There are additional rules for mapping a zoned HVAC property to Area IDs when
+ the HVAC property uses <code>VehicleAreaSeat</code>. Every available seat in
+ the car must be part of an Area ID in the Area ID array.
+</p>
+
+<p>
+ Example 1: A car has two front seats <code>(ROW_1_LEFT, ROW_1_RIGHT)</code>
+ and three back seats <code>(ROW_2_LEFT, ROW_2_CENTER, ROW_2_RIGHT)</code>.
+ There are two temperature control units: driver side and passenger side.
+</p>
+
+<ul>
+ <li>A valid mapping set of Area IDs for <code>HVAC_TEMPERATURE SET</code> is:
+ <ul>
+ <li><code>ROW_1_LEFT | ROW_2_LEFT</code></li>
+ <li><code>ROW_1_RIGHT | ROW_2_CENTER | ROW_2_RIGHT</code></li>
+ </ul>
+ </li>
+ <li>An alternative mapping for the same hardware configuration is:
+ <ul>
+ <li><code>ROW_1_LEFT | ROW_2_LEFT | ROW_2_CENTER</code></li>
+ <li><code>ROW_1_RIGHT | ROW_2_RIGHT</code></li>
+ </ul>
+ </li>
+</ul>
+
+<p>
+ Example 2: A car has three seat rows with two seats in the front row
+ <code>(ROW_1_LEFT, ROW_1_RIGHT)</code> and three seats in the second
+ <code>(ROW_2_LEFT, ROW_2_CENTER, ROW_2_RIGHT)</code> and third rows
+ <code>(ROW_3_LEFT, ROW_3_CENTER, ROW_3_RIGHT)</code>. There are three
+ temperature control units: driver side, passenger side, and rear. A
+ reasonable way to map <code>HVAC_TEMPERATURE_SET</code> to Area IDs is a
+ three element array:
+</p>
+
+<ul>
+ <li><code>ROW_1_LEFT</code></li>
+ <li><code>ROW_1_RIGHT</code></li>
+ <li><code>ROW_2_LEFT | ROW_2_CENTER | ROW_2_RIGHT | ROW_3_LEFT | ROW_3_CENTER
+ | ROW_3_RIGHT</code></li>
+</ul>
<h2 id=prop_sensor>Handling sensor properties</h2>
-<p>Vehicle HAL sensor properties represent real sensor data or policy
-information such as driving status. Some sensor information (such as driving
-status and day/night mode) is accessible by any app without restriction as the
-data is mandatory to build a safe vehicle application. Other sensor information
-(such as vehicle speed) is more sensitive and requires specific permissions that
-users can manage.</p>
-<p>Supported sensor properties include:</p>
+
+<p>
+ Vehicle HAL sensor properties represent real sensor data or policy information
+ such as driving status. Some sensor information (such as driving status and
+ day/night mode) is accessible by any app without restriction as the data is
+ mandatory to build a safe vehicle application. Other sensor information (such
+ as vehicle speed) is more sensitive and requires specific permissions that
+ users can manage.
+</p>
+
+<p>
+ Supported sensor properties include:
+</p>
+
<ul>
-<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>
-<br>Current fuel level in %.</li>
-<li><code>FUEL_LEVEL_LOW</code>
-<br>Fuel level is low or not (boolean).</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>
+ <br>Current fuel level in %.</li>
+ <li><code>FUEL_LEVEL_LOW</code>
+ <br>Fuel level is low or not (boolean).</li>
</ul>
<h2 id=vms>Vehicle Mapping Service (VMS)</h2>
-<p>Android 8.1 introduces support for the Vehicle Mapping Service (VMS), a new
-vehicle property intended for use only in Android Automotive implementations.
-VMS can be used for in-vehicle mapping services that support common vehicle
-features such as advanced driver assistance
-(<a href="https://en.wikipedia.org/wiki/Advanced_driver-assistance_systems" class="external">ADAS</a>).
+<p>
+ The Vehicle Map Service (VMS) provides a mechanism to exchange map data
+ between clients through a pub/sub interface to support common vehicle features
+ such as advanced driver assistance
+ (<a href="https://en.wikipedia.org/wiki/Advanced_driver-assistance_systems" class="external">ADAS</a>).
+ Clients may include vehicle systems interfacing through the VMS property in
+ the Vehicle HAL or privileged Android applications. Data shared on VMS are
+ intended to be limited to map data for use by vehicle systems and supporting
+ apps.
+</p>
-<aside class="note"><strong>Note:</strong> For details on compatibility
-requirements for Automotive, see
-<a href="https://source.android.com/compatibility/android-cdd#2_5_automotive_requirements">Automotive
-Requirements</a>.</aside>
+<p>VMS is intended for use only in Android Automotive implementations; AOSP does
+ not contain default clients that publish or subscribe to VMS.
+</p>
-<p>The VMS property is a complex data type that expresses map data exchanged
-between an Android Automotive implementation and the underlying vehicle hardware
-responsible for managing onboard mapping data.</p>
+<p>
+ For the VMS property in the Vehicle HAL, the message types and data structures
+ are described in
+ <a href="https://android.googlesource.com/platform/hardware/interfaces/+/master/automotive/vehicle/2.0/types.hal" class="external">Vehicle
+ HAL 2.0</a> in the
+ <a href="https://android.googlesource.com/platform/hardware/interfaces/+/master/automotive/vehicle/2.0/types.hal#3216" class="external">VmsMessageType</a>
+ enum, which lists the types of supported VMS messages. This enum is used as
+ the first integer in the vehicle property integers array and determines how
+ the rest of the message is decoded.
+</p>
-<p>AOSP does not contain a default implementation of VMS, which currently
-exists only as the property and related enumeration. Message types and data
-structures are described in
-<a href="https://android.googlesource.com/platform/hardware/interfaces/+/master/automotive/vehicle/2.0/types.hal">Vehicle
-HAL 2.0</a> in the
-<a href="https://android.googlesource.com/platform/hardware/interfaces/+/master/automotive/vehicle/2.0/types.hal#3216">VmsMessageType</a>
-enum, which lists the types of supported VMS messages. This enum is used as the
-first integer in the vehicle property integers array and determines how the rest
-of the message is decoded.</p>
+<aside class="note">
+ <strong>Note:</strong> For details on compatibility requirements for
+ Automotive, see
+ <a href="/compatibility/android-cdd#2_5_automotive_requirements">Automotive
+ Requirements</a>.
+</aside>
</body>
</html>
diff --git a/en/devices/bootloader/boot-image-header.html b/en/devices/bootloader/boot-image-header.html
new file mode 100644
index 0000000..af099fe
--- /dev/null
+++ b/en/devices/bootloader/boot-image-header.html
@@ -0,0 +1,169 @@
+<html devsite>
+<head>
+ <title>Boot Image Header Versioning</title>
+ <meta name="project_path" value="/_project.yaml">
+ <meta name="book_path" value="/_book.yaml">
+</head>
+{% include "_versions.html" %}
+<body>
+ <!--
+ Copyright 2018 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.
+ -->
+
+
+ <h2>Boot Image Header Versioning</h2>
+
+
+ <p>Starting in Android {{ androidPVersionNumber }}, the boot image header contains
+ a field to indicate the header version. The bootloader must check this header
+ version field and parse the header accordingly. Versioning the boot image header
+ allows future modifications to the header while maintaining backward compatibility.</p>
+
+
+ <p>All devices launching with Android {{ androidPVersionNumber }} must use a boot header
+ version of 1.</p>
+
+
+ <h2 id="boot-image-header-changes">Boot image header changes</h2>
+
+
+ <p>In the legacy boot image header (shown below), the <code>unused</code>
+ field will be converted to a header version field for devices launching with
+ Android {{ androidPVersionNumber }}.</p>
+
+ <pre class="prettyprint">struct boot_img_hdr
+{
+ uint8_t magic[BOOT_MAGIC_SIZE];
+ uint32_t kernel_size; /* size in bytes */
+ uint32_t kernel_addr; /* physical load addr */
+
+ uint32_t ramdisk_size; /* size in bytes */
+ uint32_t ramdisk_addr; /* physical load addr */
+
+ uint32_t second_size; /* size in bytes */
+ uint32_t second_addr; /* physical load addr */
+
+ uint32_t tags_addr; /* physical addr for kernel tags */
+ uint32_t page_size; /* flash page size we assume */
+ uint32_t unused;
+ uint32_t os_version;
+ uint8_t name[BOOT_NAME_SIZE]; /* asciiz product name */
+ uint8_t cmdline[BOOT_ARGS_SIZE];
+ uint32_t id[8]; /* timestamp / checksum / sha1 / etc */
+ uint8_t extra_cmdline[BOOT_EXTRA_ARGS_SIZE];
+};</pre>
+
+ <p>Devices launched before Android {{ androidPVersionNumber }} using the legacy boot
+ image header are considered as using a boot image header version of 0. All devices
+ launching with Android {{ androidPVersionNumber }} must use the following structure
+ for the boot image header with the header version set to 1:</p>
+
+ <pre class="prettyprint">struct boot_img_hdr
+{
+ uint8_t magic[BOOT_MAGIC_SIZE];
+ uint32_t kernel_size; /* size in bytes */
+ uint32_t kernel_addr; /* physical load addr */
+
+ uint32_t ramdisk_size; /* size in bytes */
+ uint32_t ramdisk_addr; /* physical load addr */
+
+ uint32_t second_size; /* size in bytes */
+ uint32_t second_addr; /* physical load addr */
+
+ uint32_t tags_addr; /* physical addr for kernel tags */
+ uint32_t page_size; /* flash page size we assume */
+ uint32_t header_version;
+ uint32_t os_version;
+ uint8_t name[BOOT_NAME_SIZE]; /* asciiz product name */
+ uint8_t cmdline[BOOT_ARGS_SIZE];
+ uint32_t id[8]; /* timestamp / checksum / sha1 / etc */
+ uint8_t extra_cmdline[BOOT_EXTRA_ARGS_SIZE];
+ uint32_t recovery_dtbo_size; /* size of recovery dtbo image */
+ uint64_t recovery_dtbo_offset; /* offset in boot image */
+ uint32_t header_size; /* size of boot image header in bytes */
+};</pre>
+
+ <p>The <code>header_size</code> field contains the size of the boot image
+ header. If the boot image header version is set to 1, the id field contains
+ the SHA1 digest for the <code>recovery_dtbo</code> section of the boot image
+ in addition to the kernel, ramdisk. and second sections. For details on the
+ <code>recovery_dtbo_size</code> and <code>recovery_dtbo_offset</code> fields,
+ refer to <em><a href="/devices/bootloader/recovery-image">Including
+ DTBO in Recovery for Non-A/B Devices</a></em>.</p>
+
+
+ <h2 id="implementation">Implementation</h2>
+
+
+ <p>The <code>mkbootimg</code> tool that creates boot images adds the
+ following arguments to support the new boot image header:</p>
+
+
+ <table>
+ <tr>
+ <td><strong>Argument</strong>
+ </td>
+
+ <td><strong>Description</strong>
+ </td>
+ </tr>
+
+
+ <tr>
+ <td><code>header_version</code>
+ </td>
+
+ <td>Sets the boot image header version.</td>
+ </tr>
+
+
+ <tr>
+ <td><code>recovery_dtbo</code>
+ </td>
+
+ <td>Path to the recovery DTBO image to be included in the recovery
+ image.</td>
+ </tr>
+ </table>
+
+
+ <p>The device <code>BoardConfig.mk</code> uses the config
+ <code>BOARD_MKBOOTIMG_ARGS</code> to add <code>header version</code> to the
+ other board-specific arguments of <code>mkbootimg</code>. For example:</p>
+
+ <pre class="prettyprint">
+ BOARD_MKBOOTIMG_ARGS := --ramdisk_offset $(BOARD_RAMDISK_OFFSET) --tags_offset $(BOARD_KERNEL_TAGS_OFFSET) --header_version $(BOARD_BOOTIMG_HEADER_VERSION)</pre>
+
+ <p>The Android build system uses the BoardConfig variable
+ <code>BOARD_PREBUILT_DTBOIMAGE</code> to set the argument
+ <code>recovery_dtbo</code> of <code>mkbootimg</code> tool during the creation
+ of recovery image.</p>
+
+
+ <p>For details on the Android Open Source Project (AOSP) changes, review the
+ <a href=
+ "https://android-review.googlesource.com/q/topic:%22recovery_dtbo%22+(status:open%20OR%20status:merged)">
+ associated changelists for boot image header versioning</a>.</p>
+
+
+ <h2 id="validation">Validation</h2>
+
+
+ <p>For all devices launching with Android {{ androidPVersionNumber }}, the <a href=
+ "/compatibility/vts/">Vendor Test Suite (VTS)</a>
+ checks the format of the boot/recovery image to ensure the boot image header
+ uses version 1.</p>
+</body>
+</html>
diff --git a/en/devices/bootloader/boot-reason.html b/en/devices/bootloader/boot-reason.html
new file mode 100644
index 0000000..4071e32
--- /dev/null
+++ b/en/devices/bootloader/boot-reason.html
@@ -0,0 +1,319 @@
+<html devsite>
+ <head>
+ <title>Canonical Boot Reason</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ <body>
+ {% include "_versions.html" %}
+ <!--
+ Copyright 2018 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 {{ androidPVersionNumber }} includes the following changes to the
+ bootloader boot reason specification.
+</p>
+
+<h2 id="about-boot-reasons">About boot reasons</h2>
+
+<p>
+ A bootloader uses uniquely-available hardware and memory resources to
+ determine why a device rebooted, then communicates that determination by
+ adding <code>androidboot.bootreason=<reason></code> to the Android
+ kernel command line for its launch. <code>init</code> then translates this
+ command line to propagate to the Android property
+ <code>bootloader_boot_reason_prop</code> (<code>ro.boot.bootreason</code>).
+</p>
+
+<h2 id="about-boot-reason-specifications">About boot reason specifications</h2>
+
+<p>
+ Previous releases of Android specified a boot reason format that used no
+ spaces, was all lowercase, included few requirements (such as for reporting
+ <code>kernel_panic</code>, <code>watchdog</code>,
+ <code>cold</code>/<code>warm</code>/<code>hard</code>), and which made
+ allowances for other unique reasons. This loose specification resulted in the
+ proliferation of hundreds of custom (and sometimes meaningless) boot reason
+ strings, which in turn led to an unmanageable situation. As of the current
+ Android release, the sheer momentum of near unparseable or meaningless content
+ filed by the bootloader has created compliance issues for
+ <code>bootloader_boot_reason_prop</code>.
+</p>
+
+<p>
+ With the Android {{ androidPVersionNumber }} release, the Android team
+ recognizes that the legacy <code>bootloader_boot_reason_prop</code> has
+ substantial momentum and cannot be re-written at runtime. Any improvements to
+ the boot reason specification must therefore come from interactions with
+ bootloader developers and tweaks to the existing system. To that end the
+ Android team is:
+</p>
+
+<ul>
+ <li>Engaging with bootloader developers to encourage them to:
+ <ul>
+ <li>Provide canonical, parseable, and recognizable reasons to
+ <code>bootloader_boot_reason_prop</code>.</li>
+ <li>Participate in the <code>system/core/bootstat/bootstat.cpp</code>
+ <code>kBootReasonMap</code> list.</li>
+ </ul>
+ </li>
+ <li>Adding a controlled and runtime-rewritable source of the
+ <code>system_boot_reason_prop</code> (<code>sys.boot.reason</code>). A
+ limited set of system applications (such as <code>bootstat</code> and
+ <code>init</code>) can rewrite this property, but all applications can be
+ granted sepolicy rights to read it.</li>
+ <li>Informing users of the boot reason to wait until after userdata is mounted
+ before trusting the content in the system boot reason property
+ <code>system_boot_reason_prop</code>.</li>
+</ul>
+
+<p>
+ Why so late? While <code>bootloader_boot_reason_prop</code> is available early
+ on in boot, it is blocked by the Android security policy on an as-need basis
+ because it represents inaccurate, unparseable, and noncanonical information.
+ In most situations, only developers with deep knowledge of the boot system
+ should need to access this information. A refined, parseable, and canonical
+ API for boot reason via <code>system_boot_reason_prop</code> can be reliably
+ and accurately picked up only <strong>after</strong> userdata has mounted.
+ Specifically:
+</p>
+
+ <ul>
+ <li><strong>Before</strong> userdata has mounted,
+ <code>system_boot_reason_prop</code> will contain the value from
+ <code>bootloader_boot_reasoon_prop</code>.</li>
+ <li><strong>After</strong> userdata has mounted,
+ <code>system_boot_reason_prop</code> may be updated to be compliant or to
+ report more accurate information.</li>
+ </ul>
+
+<p>
+ For this reason, Android {{ androidPVersionNumber }} extends the period of
+ time before the boot reason can be officially acquired, changing it from being
+ immediately accurate in boot (with <code>bootloader_boot_reason_prop</code>)
+ to being available only after userdata has mounted (with
+ <code>system_boot_reason_prop</code>).
+</p>
+
+<p>
+ Bootstat logic depends on a more informative and compliant
+ <code>bootloader_boot_reason_prop</code>. When that property uses a
+ predictable format, it improves the accuracy of all controlled reboot and
+ shutdown scenarios, which in turn refines and expands the accuracy and meaning
+ of <code>system_boot_reason_prop</code>.
+</p>
+
+<h2 id="canonical-boot-reason-format">Canonical boot reason format</h2>
+
+<p>
+ The canonical boot reason format for <code>bootloader_boot_reason_prop</code>
+ in Android {{ androidPVersionNumber }} uses the following syntax:
+</p>
+
+<pre class="prettyprint"><reason>,<subreason>,<detail>…</pre>
+
+<p>
+ Formatting rules:
+</p>
+
+<ul>
+ <li>Lower case</li>
+ <li>No blanks (use underline)</li>
+ <li>All printable characters</li>
+ <li>Comma-separated <code>reason</code>, <code>subreason</code>, and one or
+ more <code>detail</code>(s).
+ <ul>
+ <li>A required <code>reason</code> that represents the highest priority
+ reason why the device had to reboot or shutdown.</li>
+ <li>An optional <code>subreason</code> that represents a short summary of
+ why the device had to reboot or shutdown (or who rebooted or shutdown the
+ device).</li>
+ <li>One or more optional <code>detail</code> values. A <code>detail</code>
+ may point to a subsystem to aid in determining which specific system
+ resulted in the <code>subreason</code>. You can specify multiple
+ <code>detail</code> values, which should generally follow a hierarchy of
+ importance. However, it is also acceptable to report multiple
+ <code>detail</code> values of equal importance.</li>
+ </ul>
+ </li>
+</ul>
+
+<p>
+ An empty value for <code>bootloader_boot_reason_prop</code> is considered
+ illegal (as this allows other agents to inject a boot reason after the fact).
+</p>
+
+<h3 id="reason-requirements">Reason requirements</h3>
+
+<p>
+ The value given for <code>reason</code> (first span, prior to termination or
+ comma) must be of the following set divided into kernel, strong, and blunt
+ reasons:
+</p>
+
+<ul>
+ <li>kernel set:
+ <ul>
+ <li>"<code>watchdog"</code></li>
+ <li><code>"kernel_panic"</code></li>
+ </ul>
+ </li>
+ <li>strong set:
+ <ul>
+ <li><code>"recovery"</code></li>
+ <li><code>"bootloader"</code></li>
+ </ul>
+ </li>
+ <li>blunt set:
+ <ul>
+ <li><code>"cold"</code>. Generally indicates a full reset of all devices,
+ including memory.</li>
+ <li><code>"hard"</code>. Generally indicates the hardware has its state
+ reset and <code>ramoops</code> should retain persistent content.</li>
+ <li><code>"warm"</code>. Generally indicates the memory and the devices
+ retain some state, and the <code>ramoops</code> (see <code>pstore</code>
+ driver in kernel) backing store contains persistent content.</li>
+ <li><code>"shutdown"</code></li>
+ <li><code>"reboot"</code>. Generally means the <code>ramoops</code> state is
+ unknown and the hardware state is unknown. This value is a catchall as the
+ <code>cold</code>, <code>hard</code>, and <code>warm</code> values provide
+ clues as to the depth of the reset for the device.</li>
+ </ul>
+ </li>
+</ul>
+
+<p>
+ Bootloaders must provide a kernel set or a blunt set <code>reason</code>, and
+ are strongly encouraged to provide a <code>subreason</code> if it can be
+ determined. For example, a power key long press that may or may not have
+ <code>ramoops</code> backup would have the boot reason
+ <code>"reboot,longkey"</code>.
+</p>
+
+<p>
+ No first-span <code>reason</code> can be part of any <code>subreason</code> or
+ <code>detail</code>. However, because kernel set reasons cannot be produced by
+ user space, <code>"watchdog"</code> may be reused after a blunt set reason,
+ along with a detail of the source (e.g.
+ <code>"reboot,watchdog,service_manager_unresponsive"</code>, or
+ <code>"reboot,software,watchdog"</code>).
+</p>
+
+<p>
+ Boot reasons should not require expert internal knowledge to decipher and/or
+ should be human readable with an intuitive report. Examples:
+ <code>"shutdown,vbxd"</code> (bad), <code>"shutdown,uv"</code> (better),
+ <code>"shutdown,undervoltage"</code> (preferred).
+</p>
+
+<h3 id="reason-subreason-combinations">Reason-Subreason combinations</h3>
+
+<p>
+ Android reserves a set of <code>reason</code>-<code>subreason</code>
+ combinations that should not be overloaded in normal usage but can be used on
+ a case-by-case basis if the combination accurately reflects the associated
+ condition. Examples of reserved combinations include:
+</p>
+
+<ul>
+ <li><code>"reboot,userrequested"</code></li>
+ <li><code>"shutdown,userrequested"</code></li>
+ <li><code>"Shutdown,thermal"</code> (from <code>thermald</code>)</li>
+ <li><code>"shutdown,battery"</code></li>
+ <li><code>"Shutdown,battery,thermal"</code> (from
+ <code>BatteryStatsService</code>)</li>
+ <li><code>"reboot,adb"</code></li>
+ <li><code>"reboot,shell"</code></li>
+ <li><code>"reboot,bootloader"</code></li>
+ <li><code>"reboot,recovery"</code></li>
+</ul>
+
+<p>
+ For more details, refer to <code>kBootReasonMap</code> in
+ <code>system/core/bootstat/bootstat.cpp</code> and the associated git
+ changelog history in the Android source repository.
+</p>
+
+<h2 id="reporting-boot-reasons">Reporting boot reasons</h2>
+
+<p>
+ All boot reasons, either from the bootloader or recorded in the canonical boot
+ reason, must be recorded in the <code>kBootReasonMap</code> section of
+ <code>system/core/bootstat/bootstat.cpp</code>. The
+ <code>kBootReasonMap</code> list is a mix of compliant and legacy
+ non-compliant reasons. Bootloader developers should register only new
+ compliant reasons here (and should not register non-compliant reasons unless
+ the product has already shipped and cannot be changed).
+</p>
+
+<aside class="note">
+ <strong>Note:</strong> While <code>system/core/bootstat/bootstat.cpp</code>
+ contains a <code>kBootReasonMap</code> section that lists a considerable
+ number of legacy reasons, the presence of these reasons does not mean the
+ <code>reason</code> string is approved for use. A subset of the list
+ represents compliant reasons; we expect this subset to grow as bootloader
+ authors register and explain additional compliant reasons.
+</aside>
+
+<p>
+ We strongly recommend using existing, compliant entries in
+ <code>system/core/bootstat/bootstat.cpp</code> and exercising restraint before
+ using a non-compliant string. As a guideline, it is:
+</p>
+
+<ul>
+ <li><strong>OK</strong> to report <code>"kernel_panic"</code> from the
+ bootloader, as <code>bootstat</code> may be able to inspect
+ <code>ramoops</code> for <code>kernel_panic signatures</code> to refine the
+ subreasons into the canonical <code>system_boot_reason_prop</code>.</li>
+ <li><strong>Not OK</strong> to report a non-compliant string in
+ <code>kBootReasonMap</code> (such as <code>"panic")</code> from the
+ bootloader, as this will ultimately break the ability to refine the
+ <code>reason</code>.</li>
+</ul>
+
+<p>
+ For example, if <code>kBootReasonMap</code> contains <code>"wdog_bark"</code>,
+ a bootloader developer should:
+</p>
+
+<ul>
+ <li>Change to <code>"watchdog,bark"</code> and add to the list in
+ <code>kBootReasonMap</code>.</li>
+ <li>Consider what <code>"bark"</code> means for those unfamiliar with the
+ technology and determine if a more meaningful <code>subreason</code> is
+ available.</li>
+</ul>
+
+<h2 id="verifying-boot-reason-compliance">Verifying boot reason compliance</h2>
+
+<p>
+ At this time, Android does not provide an active CTS test that can accurately
+ trigger or inspect all possible boot reasons a bootloader could provide;
+ partners can still attempt to run a passive test to determine compatibility.
+</p>
+
+<p>
+ As a result, bootloader compliance requires bootloader developers to
+ voluntarily adhere to the spirit of the rules and guidelines described above.
+ We urge such developers to contribute to AOSP (specifically to
+ <code>system/core/bootstat/bootstat.cpp</code>) and use this opportunity as a
+ forum for discussions about boot reason issues.
+</p>
+
+</body>
+</html>
\ No newline at end of file
diff --git a/en/devices/bootloader/images/maintain_abi_partitions.png b/en/devices/bootloader/images/maintain_abi_partitions.png
new file mode 100644
index 0000000..868d6a0
--- /dev/null
+++ b/en/devices/bootloader/images/maintain_abi_partitions.png
Binary files differ
diff --git a/en/devices/bootloader/product-partitions.html b/en/devices/bootloader/product-partitions.html
new file mode 100644
index 0000000..55f7df4
--- /dev/null
+++ b/en/devices/bootloader/product-partitions.html
@@ -0,0 +1,201 @@
+<html devsite>
+<head>
+ <title>Building Product Partitions</title>
+ <meta name="project_path" value="/_project.yaml">
+ <meta name="book_path" value="/_book.yaml">
+</head>
+{% include "_versions.html" %}
+<body>
+ <!--
+ Copyright 2018 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 {{ androidPVersionNumber }} includes support for building
+ <code>/product</code> partitions using the Android build system. Previously,
+ Android 8.x enforced the separation of System-on-Chip (SoC)-specific
+ components from the <code>/system</code> partition to the <code>/vendor</code>
+ partition without dedicating space for OEM-specific components built from
+ Android build system.
+</p>
+
+<h2 id="product-partitions">About product partitions</h2>
+
+<p>
+ Many OEMs customize the AOSP system image to implement their own features
+ and requirements from carriers. However, such customizations make it
+ impossible to use a single system image for multiple software SKUs as each
+ image must be different to support a different locale, carrier, etc. Using a
+ separate <code>/product</code> partition to contain customizations makes it
+ possible to use a single system image for multiple software SKUs (the
+ <code>/system</code> partition hosts generic code that can be shared among
+ many software SKUs). The <code>/vendor</code> partition continues to host
+ SoC-specific Board-Specific (BSP) code that can be shared among multiple
+ devices based on the given SoC.
+</p>
+
+<p>
+ Using separate partitions has some disadvantages, such as difficulties in
+ managing disk space (a limited amount of space should be reserved for future
+ growth) and in <a href="/devices/architecture/vndk/abi-stability">maintaining
+ stable Application Binary Interface (ABI)</a> between partitions. Before
+ deciding to use <code>/product</code> partitions, take time to consider your
+ unique AOSP implementation and possible mitigation tactics (such as
+ repartitioning a device during an <a href="/devices/tech/ota/">Over-the-Air
+ (OTA) update</a>, which is not done by Google but is done by some OEMs).
+</p>
+
+<h3 id="legacy-oem">Legacy /oem vs /product</h3>
+
+<p>
+ The new <code>/product</code> partition is incompatible with the legacy
+ <code>/oem</code> partition:
+</p>
+
+<table>
+ <tr>
+ <th>Partition</th>
+ <th>Attributes</th>
+ </tr>
+ <tr>
+ <td><code>/oem</code></td>
+ <td>
+ <ul>
+ <li>Not updateable; usually flashed once at factory.</li>
+ <li>Built per small variations such as branding and color. Different
+ <code>/oem</code> partition contents do not make them different product
+ software.</li>
+ <li>System partition does not depend on <code>/oem</code> (it uses the
+ partition only when a specific file is found there).</li>
+ <li>Does not use API on system other than public API.</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td><code>/product</code></td>
+ <td>
+ <ul>
+ <li>Updateable</li>
+ <li>Coupled with the system image (they update together)</li>
+ <li>Built per product or product families.</li>
+ <li>System partition can depend on <code>/product</code> partition.</li>
+ <li>Can use non-public APIs since they are updated simultaneously.</li>
+ </ul>
+ </td>
+ </tr>
+ </table>
+
+<p>
+ For these reasons, Android {{ androidPVersionNumber }} supports the new
+ <code>/product</code> partition and also retains support for the legacy
+ <code>/oem</code> partition for devices that depend on it.
+</p>
+
+<h3 id="product-components">/product components</h3>
+
+<p>
+ The <code>/product</code> partition contains the following components:
+</p>
+
+<ul>
+ <li>Product-specific system properties (<code>/product/build.prop</code>)</li>
+ <li>Product-specific RROs (<code>/product/overlay/*.apk</code>)</li>
+ <li>Product-specific apps (<code>/product/app/*.apk</code>)</li>
+ <li>Product-specific priv-apps (<code>/product/priv-app/*.apk</code>)</li>
+ <li>Product-specific libraries (<code>/product/lib/*</code>)</li>
+ <li>Product-specific java libraries (<code>/product/framework/*.jar</code>)
+ </li>
+ <li>Product-specific Android Framework system configs
+ (<code>/product/etc/sysconfig/*</code> and
+ <code>/product/etc/permissions/*</code>)</li>
+ <li>Product-specific media files (<code>/product/media/audio/*</code>)</li>
+ <li>Product-specific <code>bootanimation</code> files</li>
+</ul>
+
+<h3 id="custom-images">No custom_images</h3>
+
+<p>
+ You cannot use <code>custom_images</code> as they lack support for the
+ following:
+</p>
+
+<ul>
+ <li><strong>Installing modules into a specific target</strong>.
+ <code>custom_images</code> support copying artifacts into an image but
+ cannot install a module into a specific partition by specifying its target
+ partition as a part of a build rule.</li>
+ <li><strong>Soong support</strong>. <code>custom_images</code> cannot be
+ built using the Soong build system.</li>
+ <li>OTA update support</a>. <code>custom_images</code> are used as factory ROM
+ images that cannot be OTA-ed.</li>
+</ul>
+
+<h3 id="maintaining-abis">Maintaining ABIs between partitions</h3>
+
+<p>
+ The <code>/product</code> partition in Android {{ androidPVersionNumber }}
+ is an extension of the <code>/system</code> partition. As there is weak ABI
+ between <code>/product</code> and <code>/system</code> partitions, both must
+ be upgraded at the same time and the ABI should be System SDK-based. If the
+ System SDK doesn't cover all API surfaces between <code>/product</code> and
+ <code>/system</code>, it is up to the OEM to maintain their own ABI between
+ the two partitions.
+</p>
+
+<p>The <code>/product</code> and <code>/system</code> partitions can have
+ dependency on each other. However, tests with the
+ <a href="/setup/build/gsi">Generic System Image (GSI)</a> must work properly
+ without the <code>/product</code> partition.
+</p>
+
+<p>The <code>/product</code> partition must not have any dependency on
+ <code>/vendor</code> partition and no direct interaction between the
+ <code>/product</code> partition and the <code>/vendor</code> is permitted
+ (enforced by SEpolicy).
+</p>
+
+<h2 id="implementing-product-partitions">Implementing product partitions</h2>
+
+<p>
+ Before implementing a new product partition, review the
+ <a href="https://android-review.googlesource.com/q/topic:product_partition+(status:open+OR+status:merged)" class="external">related
+ product partition changes in AOSP</a>. Then, to set up <code>/product</code>,
+ include the following board or product build flags.
+</p>
+
+<ul>
+ <li><code>BOARD_USES_PRODUCTIMAGE</code></li>
+ <li><code>BOARD_PRODUCTIMAGE_PARTITION_SIZE</code></li>
+ <li><code>BOARD_PRODUCTIMAGE_FILE_SYSTEM_TYPE</code></li>
+ <li><code>PRODUCT_PRODUCT_PROPERTIES for /product/build.prop</code>.
+ Should be within a <code>$(call inherit-product path/to/device.mk)</code>,
+ e.g., <code>PRODUCT_PRODUCT_PROPERTIES += product.abc=ok</code>.
+ </li>
+ </ul>
+
+<h3 id="enabling-verified-boot">Enabling verified boot</h3>
+
+<p>
+ To prevent the <code>/product</code> partition from being tampered with by
+ malicious software, you should enable
+ <a href="https://android.googlesource.com/platform/external/avb/" class="external">Android
+ Verified Boot (AVB)</a> for that partition (just as you do for
+ <code>/vendor</code> and <code>/system</code> partitions). To enable AVB,
+ include the following build flags:
+ <code>BOARD_AVB_PRODUCT_ADD_HASHTREE_FOOTER_ARGS</code>
+</p>
+
+</body>
+</html>
diff --git a/en/devices/bootloader/recovery-image.html b/en/devices/bootloader/recovery-image.html
new file mode 100644
index 0000000..cc1057a
--- /dev/null
+++ b/en/devices/bootloader/recovery-image.html
@@ -0,0 +1,167 @@
+<html devsite>
+<head>
+ <title>Including DTBO in Recovery for Non-A/B Devices</title>
+ <meta name="project_path" value="/_project.yaml">
+ <meta name="book_path" value="/_book.yaml">
+</head>
+
+<body>
+ {% include "_versions.html" %} <!--
+ Copyright 2018 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.
+ -->
+ To prevent OTA failures on non-A/B devices, the recovery partition must be
+ self-sufficient and cannot depend on other partitions.
+
+ <p>While booting into recovery, the bootloader must load the DTBO image that
+ is compatible with the recovery image. During an OTA, if a problem occurs
+ after the DTBO image has been updated (but prior to completing the full
+ update), the device will try to boot into recovery mode to complete the OTA.
+ However, because the DTBO partition has already been updated, a mismatch
+ could occur with the recovery image (which has not yet been updated).</p>
+
+
+ <p>To prevent this situation, in Android {{ androidPVersionNumber }} the recovery
+ image must also contain information from the DTBO image. The recovery image for a
+ non-A/B device must also contain the device's DTB appended to kernel so as to not
+ depend on the DTB partition during an update.</p>
+
+
+ <h2 id="boot-image-changes">Boot image changes</h2>
+
+
+ <p>To allow the recovery image to contain the recovery DTBO, the format of
+ boot image in Android {{ androidPVersionNumber }} is:</p>
+
+
+ <table>
+ <tr>
+ <td>Boot header (1 page)</td>
+ </tr>
+
+
+ <tr>
+ <td>Kernel (<em>l</em> pages)</td>
+ </tr>
+
+
+ <tr>
+ <td>Ramdisk (<em>m</em> pages)</td>
+ </tr>
+
+
+ <tr>
+ <td>Second stage (<em>n</em> pages)</td>
+ </tr>
+
+
+ <tr>
+ <td>Recovery DTBO (<em>o</em> pages)</td>
+ </tr>
+ </table>
+
+
+ <p>In addition, the <code>mkbootimg</code> tool that creates boot images
+ includes the following new arguments:</p>
+
+
+ <table>
+ <tr>
+ <th><strong>Argument</strong>
+ </th>
+
+ <th><strong>Description</strong>
+ </th>
+ </tr>
+
+
+ <tr>
+ <td><code>header_version</code>
+ </td>
+
+ <td>Sets the boot image header version. A boot image with a header
+ version greater than or equal to 1 supports the recovery DTBO
+ section.</td>
+ </tr>
+
+
+ <tr>
+ <td><code>recovery_dtbo</code>
+ </td>
+
+ <td>Path to the recovery DTBO image.</td>
+ </tr>
+ </table>
+
+
+ <p>For details on modifications to the legacy boot image header, refer to
+ <em><a href="/devices/bootloader/boot-image-header">Boot Image Header
+ Versioning in Android {{ androidPVersionNumber }}</a></em>.</p>
+
+
+ <h2 id="implementation">Implementation</h2>
+
+
+ <p>Although all devices launching with Android {{ androidPVersionNumber }}
+ must use the new boot image header (version 1), only non-A/B devices are
+ required to populate the <code>recovery_dtbo</code> section of the recovery
+ image. To include the <code>recovery_dtbo</code> image in <code>recovery.img</code>,
+ in the device <code>BoardConfig.mk</code>:</p>
+
+
+ <ul>
+ <li>Set the config <code>BOARD_INCLUDE_RECOVERY_DTBO</code> to
+ <code>true</code>:
+
+ <pre class="prettyprint">BOARD_INCLUDE_RECOVERY_DTBO := true</pre>
+ </li>
+ </ul>
+
+
+ <ul>
+ <li>Extend the <code>BOARD_MKBOOTIMG_ARGS</code> variable to specify the
+ boot image header version:
+
+ <pre class="prettyprint">
+ BOARD_MKBOOTIMG_ARGS := --ramdisk_offset $(BOARD_RAMDISK_OFFSET) --tags_offset $(BOARD_KERNEL_TAGS_OFFSET) --header_version $(BOARD_BOOTIMG_HEADER_VERSION)</pre>
+ </li>
+ </ul>
+
+
+ <ul>
+ <li>Ensure the <code>BOARD_PREBUILT_DTBOIMAGE</code> variable is set to the
+ path of the DTBO image. The Android build system uses the variable to set
+ the argument <code>recovery_dtbo</code> of mkbootimg tool during the
+ creation of recovery image.</li>
+ </ul>
+
+
+ <ul>
+ <li>If the variables <code>BOARD_INCLUDE_RECOVERY_DTBO</code>,
+ <code>BOARD_MKBOOTIMG_ARGS</code>, and
+ <code>BOARD_PREBUILT_DTBOIMAGE</code> are set correctly, the Android build
+ system uses the DTBO specified by the variable
+ <code>BOARD_PREBUILT_DTBOIMAGE</code> to include in
+ <code>recovery.img</code>.</li>
+ </ul>
+
+
+ <h2 id="validation">Validation</h2>
+
+
+ <p>For all devices launching with Android {{ androidPVersionNumber }}, the <a href=
+ "/compatibility/vts/">Vendor Test Suite (VTS)</a> checks the format of the
+ boot/recovery image to ensure the boot image header uses version 1.</p>
+</body>
+</html>
diff --git a/en/devices/bootloader/system-as-root.html b/en/devices/bootloader/system-as-root.html
new file mode 100644
index 0000000..fd4620c
--- /dev/null
+++ b/en/devices/bootloader/system-as-root.html
@@ -0,0 +1,399 @@
+<html devsite>
+<head>
+ <title>System-as-root</title>
+ <meta name="project_path" value="/_project.yaml">
+ <meta name="book_path" value="/_book.yaml">
+</head>
+{% include "_versions.html" %}
+<body>
+ <!--
+ Copyright 2018 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>All new devices launching with Android {{ androidPVersionNumber }} must use system-as-root
+ (<code>BOARD_BUILD_SYSTEM_ROOT_IMAGE</code> must be <code>true</code>), which
+ merges <code>ramdisk.img</code> into <code>system.img</code>, which in turn
+ is mounted as rootfs. For devices upgrading to Android {{ androidPVersionNumber }}, system-as-root is
+ not mandatory. This document describes system-as-root, lists kernel
+ requirements for dm-verity support (including dependent kernel patches), and
+ provides setup examples.</p>
+
+
+ <h2 id="about-system-only-otas">About system-only OTAs</h2>
+
+
+ <p>The current Android ecosystem supports <a href=
+ "/devices/tech/ota/ab/ab_faqs#how-did-ab-affect-the-2016-pixel-partition-sizes">
+ two types of partition layout</a>:</p>
+
+
+ <ul>
+ <li>In an A/B partitioning scheme, the <code>system</code> partition is
+ mounted as rootfs.</li>
+
+
+ <li>In a non-A/B partitioning scheme, the <code>ramdisk.img</code> in the
+ <code>/boot</code> partition is loaded into memory (which in turn is
+ mounted as rootfs) while the <code>system</code> partition is mounted at
+ <code>/system</code>.</li>
+ </ul>
+
+
+ <p>System-only OTAs, in which a <code>system.img</code> can be updated across
+ major Android releases without changing other partitions, are supported by
+ the architectural changes made in Android 8.0 as part of
+ <a href="/devices/architecture/#hidl">Project Treble.</a>
+ However, for non-A/B devices, as <code>ramdisk.img</code> is in
+ <code>/boot</code> partition, it cannot be updated via a system-only OTA
+ using the Android 8.x architecture. As a result, an old
+ <code>ramdisk.img</code> might not work with a new <code>system.img</code>
+ for the following reasons:</p>
+
+
+ <ul>
+ <li>The older <code>/init</code> in <code>ramdisk.img</code> might not be
+ able to parse the *.rc files on <code>/system</code>.</li>
+
+
+ <li>The ramdisk contains <code>/init.rc</code>, which also may be out of
+ date compared to what is required for the new <code>/system</code>.</li>
+ </ul>
+
+
+ <p>To ensure system-only OTAs work as expected, system-as-root is
+ <strong>mandatory</strong> in Android {{ androidPVersionNumber }}. Non-A/B devices must switch from
+ ramdisk partition layout to system-as-root partition layout; A/B devices do
+ not need to change as they already must use system-as-root.</p>
+
+
+ <h2 id="about-ab-nonab-devices">About A/B and non-A/B devices</h2>
+
+
+ <p>A/B devices and non-A/B devices have the following partition details:</p>
+
+
+ <table>
+ <tr>
+ <th>A/B Devices</th>
+
+ <th>Non-A/B Devices</th>
+ </tr>
+ <tr>
+ <td>
+ Each partition (except userdata) has two copies (slots):
+
+ <ul>
+ <li>/boot_a</li>
+
+
+ <li>/boot_b</li>
+
+
+ <li>/system_a</li>
+
+
+ <li>/system_b</li>
+
+
+ <li>/vendor_a</li>
+
+
+ <li>/vendor_b</li>
+
+
+ <li>...</li>
+ </ul>
+ </td>
+
+ <td>
+ Each partition has one copy, no other backup partitions.
+
+ <ul>
+ <li>/boot</li>
+
+
+ <li>/system</li>
+
+
+ <li>/vendor</li>
+
+
+ <li>...</li>
+ </ul>
+ </td>
+ </tr>
+ </table>
+
+
+ <p>For details on A/B and non-A/B devices, refer to <a href=
+ "/devices/tech/ota/ab_updates">A/B (Seamless)
+ System Updates.</a></p>
+
+
+ <h2 id="about-system-as-root">About system-as-root</h2>
+
+
+ <p>In Android {{ androidPVersionNumber }}, non-A/B devices should adopt system-as-root so they can be
+ updated via a system-only OTA.</p>
+
+
+<aside class="note"><strong>Note</strong>: For devices using an A/B partitioning scheme,
+ no changes are required.</aside>
+
+
+ <p>Unlike A/B devices that re-purpose <code>/boot</code> as the <a href=
+ "/devices/tech/ota/ab_implement#recovery">recovery</a>
+ partition, <strong>non-A/B devices must keep the <code>/recovery</code>
+ partition separate as they do not have the fallback slot partition</strong>
+ (e.g., from <code>boot_a</code> → <code>boot_b</code>). If
+ <code>/recovery</code> is removed on non-A/B device and made similar to the
+ A/B scheme, recovery mode could break during a failed update to
+ <code>/boot</code> partition. For this reason, the <code>/recovery</code>
+ partition <strong>must</strong> be a separate partition than
+ <code>/boot</code> for non-A/B devices, which implies the recovery image will
+ continue to be updated in a deferred manner (i.e. the same as in <a href=
+ "/devices/tech/ota/nonab/#life-ota-update">pre-{{ androidPVersionNumber }}</a>
+ devices).</p>
+
+
+ <p>Partition layout differences for non-A/B devices before and after Android
+ {{ androidPVersionNumber }}:</p>
+
+
+ <table>
+ <tr>
+ <th>Component
+ </th>
+
+ <th>Image
+ </th>
+
+ <th>ramdisk (before {{ androidPVersionNumber }})
+ </th>
+
+ <th>system-as-root (after {{ androidPVersionNumber }})
+ </th>
+ </tr>
+
+
+ <tr>
+ <td rowspan="3"><strong>Image Content</strong>
+ </td>
+
+ <td>boot.img</td>
+
+ <td>
+ Contains a kernel and a ramdisk.img:
+
+ <pre class="prettyprint">ramdisk.img
+ -/
+ - init.rc
+ - init
+ - etc -> /system/etc
+ - system/ (mount point)
+ - vendor/ (mount point)
+ - odm/ (mount point)
+ ...</pre>
+ </td>
+
+ <td>Contains a normal boot kernel only.</td>
+ </tr>
+
+
+ <tr>
+ <td>recovery.img</td>
+
+ <td colspan="2">Contains a recovery kernel and a
+ recovery-ramdisk.img.</td>
+ </tr>
+
+
+ <tr>
+ <td>system.img</td>
+
+ <td>
+ Contains the following:
+
+ <pre class="prettyprint">system.img
+ -/
+ - bin/
+ - etc
+ - vendor -> /vendor
+ - ...</pre>
+ </td>
+
+ <td>
+ Contains the merged content of original system.img and ramdisk.img:
+
+ <pre class="prettyprint">system.img
+ -/
+ - init.rc
+ - init
+ - etc -> /system/etc
+ - system/
+ - bin/
+ - etc/
+ - vendor -> /vendor
+ - ...
+ - vendor/ (mount point)
+ - odm/ (mount point)
+ ...</pre>
+ </td>
+ </tr>
+
+
+ <tr>
+ <td><strong>Partition Layout</strong>
+ </td>
+
+ <td>N/A</td>
+
+ <td>
+ <ol>
+ <li>/boot</li>
+
+
+ <li>/system</li>
+
+
+ <li>/recovery</li>
+
+
+ <li>/vendor, … etc</li>
+ </ol>
+ </td>
+
+ <td>
+ <ol>
+ <li>/boot</li>
+
+
+ <li>/system</li>
+
+
+ <li>/recovery</li>
+
+
+ <li>/vendor, … etc</li>
+ </ol>
+ </td>
+ </tr>
+ </table>
+
+
+ <h2 id="setting-up-dm-verity">Setting up dm-verity</h2>
+
+
+ <p>In system-as-root, the kernel must mount <code>system.img</code> under
+ <strong><code>/</code></strong> (mount point) with <a href=
+ "https://www.kernel.org/doc/Documentation/device-mapper/verity.txt"class="external">dm-verity</a>.
+ AOSP supports the following dm-verity implementations for
+ <code>system.img</code>:</p>
+
+
+ <ol>
+ <li>For <a href="/security/verifiedboot/">vboot
+ 1.0</a>, the kernel must parse android-specific <a href=
+ "/security/verifiedboot/dm-verity#metadata">metadata</a>
+ on <code>/system</code>, then convert to <a href=
+ "https://www.kernel.org/doc/Documentation/device-mapper/verity.txt"class="external">dm-verity
+ params</a> to set up dm-verity. Requires these <a href=
+ "/devices/tech/ota/ab_implement#kernel">kernel-patches</a>.</li>
+
+
+ <li>For vboot 2.0 (<a href=
+ "https://android.googlesource.com/platform/external/avb/"class="external">AVB</a>), the
+ bootloader must integrate <a href=
+ "https://android.googlesource.com/platform/external/avb/+/master/libavb/"class="external">
+ external/avb/libavb</a>, which then parses the <a href=
+ "https://android.googlesource.com/platform/external/avb/+/master/libavb/avb_hashtree_descriptor.h"class="external">
+ hashtree descriptor</a> for <code>/system</code>, converts it to <a href=
+ "https://www.kernel.org/doc/Documentation/device-mapper/verity.txt"class="external">dm-verity
+ params</a>, and finally passes the params to the kernel via kernel
+ command line. (Hashtree descriptors of <code>/system</code> might be on
+ <code>/vbmeta</code> or on <code>/system</code> itself.)<br>
+ <br>
+ Requires the following kernel-patches:
+
+ <ul>
+ <li><a href=
+ "https://android-review.googlesource.com/#/c/kernel/common/+/158491/"class="external">https://android-review.googlesource.com/#/c/kernel/common/+/158491/</a>
+ </li>
+
+
+ <li><a href="https://android-review.googlesource.com/q/hashtag:avb-kernel-patch-4.4"class="external">kernel 4.4 patches</a>,
+ <a href="https://android-review.googlesource.com/q/hashtag:avb-kernel-patch-4.9"class="external">kernel 4.9 patches</a>, etc.
+<aside class="note"><strong>Note</strong>: The above AVB-specific kernel patch files are also available on
+ <a href="https://android.googlesource.com/platform/external/avb/+/master/contrib/linux/"class="external">external/avb/contrib/linux/</a>
+ {4.4,4.9,etc.}/*.
+</aside>
+ </li>
+ </ul>
+ </li>
+ </ol>
+
+
+ <p>Examples from real devices showing dm-verity related settings for
+ system-as-root in kernel command line:</p>
+
+
+ <p><strong><em>vboot 1.0</em></strong>
+ </p>
+
+ <pre class="prettyprint">ro root=/dev/dm-0 rootwait skip_initramfs init=/init
+dm="system none ro,0 1 android-verity /dev/sda34"
+veritykeyid=id:7e4333f9bba00adfe0ede979e28ed1920492b40f</pre>
+
+ <p><strong><em>vboot 2.0 (AVB)</em></strong>
+ </p>
+
+ <pre class="prettyprint">
+ro root=/dev/dm-0 rootwait skip_initramfs init=/init
+
+dm="1 vroot none ro 1,0 5159992 verity 1
+PARTUUID=00000016-0000-0000-0000-000000000000
+PARTUUID=00000016-0000-0000-0000-000000000000 4096 4096 644999 644999
+sha1 d80b4a8be3b58a8ab86fad1b498640892d4843a2
+8d08feed2f55c418fb63447fec0d32b1b107e42c 10 restart_on_corruption
+ignore_zero_blocks use_fec_from_device
+PARTUUID=00000016-0000-0000-0000-000000000000 fec_roots 2 fec_blocks
+650080 fec_start 650080"
+ </pre>
+
+ <h2 id="device-specific-folders">Device-specific root folders</h2>
+
+
+<p>With system-as-root, after the <a href="/setup/build/gsi">Generic System Image (GSI)</a>
+ is flashed on the device (and before running <a href="/compatibility/vts/">Vendor Test Suite</a>
+ tests), any device-specific root folders added via
+ <code>BOARD_ROOT_EXTRA_FOLDERS</code> will be gone because the entire root
+ directory content has been replaced by the system-as-root GSI. The removal of
+ these folders might cause the device to become unbootable if a dependency on
+ the device-specific root folders exists (e.g., they are used as mount
+ points).</p>
+
+
+ <p>To avoid this issue, do not use <code>BOARD_ROOT_EXTRA_FOLDERS</code> to
+ add device-specific root folders (it will likely be deprecated in the
+ future). If you need to specify device-specific mount points, use
+ <code>/mnt/vendor/<mount point></code> (added in these <a href=
+ "https://android-review.googlesource.com/q/topic:vmount"class="external">changelists</a>).
+ These vendor-specific mount points can be directly specified in both the
+ <code>fstab</code> device tree (for first-stage mount) and the
+ <code>/vendor/etc/fstab.{ro.hardware}</code> file without additional setup
+ (as <code>fs_mgr</code> will create them under <code>/mnt/vendor/*</code>
+ automatically).</p>
+</body>
+</html>
diff --git a/en/devices/camera/external-usb-cameras.md b/en/devices/camera/external-usb-cameras.md
new file mode 100644
index 0000000..b9e9325
--- /dev/null
+++ b/en/devices/camera/external-usb-cameras.md
@@ -0,0 +1,197 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+<!--
+ Copyright 2018 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.
+-->
+
+# External USB Cameras
+
+The Android platform supports the use of plug-and-play USB cameras (i.e.
+webcams) using the standard
+[Android Camera2 API](https://developer.android.com/reference/android/hardware/camera2/package-summary.html)
+and the camera
+[HIDL](/reference/hidl/android/hardware/camera/provider/2.4/ICameraProvider)
+interface. Webcams generally support
+[USB video class (UVC)](https://en.wikipedia.org/wiki/USB_video_device_class)
+drivers and on Linux the standard
+[Video4Linux (V4L)](https://en.wikipedia.org/wiki/Video4Linux)
+driver is used to control UVC cameras.
+
+With support for webcams, devices can be used in lightweight use cases such as
+video chatting and photo kiosks. This feature does not serve as a replacement
+for typical internal camera HALs on Android phones and is not designed to
+support performance-intensive, complex tasks involving high-resolution and
+high-speed streaming, AR, and manual ISP/sensor/lens control.
+
+The new USB camera HAL process is part of the external camera provider that
+listens to USB device availability and enumerates external camera devices
+accordingly. The process has permissions and an SE policy similar to the
+built-in camera HAL process. Third party webcam applications that communicate
+directly with USB devices require the same camera permissions to access UVC
+devices as with any regular camera application.
+
+## Examples and sources
+
+For more information on how to implement USB cameras, see an external camera
+provider reference implementation at
+[`ExternalCameraProvider`](https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/provider/2.4/default/CameraProvider.cpp).
+The external camera device and session implementations are included in
+[`ExternalCameraDevice`](https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/device/3.4/default/ExternalCameraDevice.cpp)
+and
+[`ExternalCameraDeviceSession`](https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/device/3.4/default/ExternalCameraDeviceSession.cpp).
+The Java client API includes a new
+[`EXTERNAL`](https://developer.android.com/reference/android/hardware/camera2/CameraMetadata?authuser=3#INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL)
+hardware level.
+
+## Implementation
+
+The implementation must support the
+[`android.hardware.usb.host`](https://developer.android.com/guide/topics/connectivity/usb/host)
+system feature.
+
+Kernel support for UVC devices must also be enabled. You can enable this by
+adding the following to the respective kernel `deconfig` files.
+
+```
++CONFIG_USB_VIDEO_CLASS=y
++CONFIG_MEDIA_USB_SUPPORT=y
+```
+
+Note: Make sure you also have this
+[patch](https://patchwork.kernel.org/patch/6874491/) for uvcvideo.
+
+To enable the external camera provider in the respective device build, which
+adds the necessary SELinux permissions, external camera configuration, and
+external camera provider dependency, complete the following steps:
+
++ Add external camera config file and external camera library to `device.mk`
+
+ ```
+ +PRODUCT_PACKAGES += android.hardware.camera.provider@2.4-impl
+ +PRODUCT_PACKAGES += android.hardware.camera.provider@2.4-external-service
+
+ +PRODUCT_COPY_FILES += \
+ +device/manufacturerX/productY/external_camera_config.xml:$(TARGET_COPY_OUT_VENDOR)/etc/external_camera_config.xml
+ ```
+
++ Add external camera provider name to device Treble HAL manifest
+
+ ```
+ <hal format="hidl">
+ <name>android.hardware.camera.provider</name>
+ <transport arch="32+64">passthrough</transport>
+ <impl level="generic"></impl>
+ <version>2.4</version>
+ <interface>
+ <name>ICameraProvider</name>
+ <instance>legacy/0</instance>
+ + <instance>external/0</instance>
+ </interface>
+ </hal>
+ ```
+
++ (Optional) If the device runs in Treble passthrough mode, update `sepolicy`
+ so `cameraserver` can access UVC camera
+
+ ```
+ +# for external camera
+ +allow cameraserver device:dir r_dir_perms;
+ +allow cameraserver video_device:dir r_dir_perms;
+ +allow cameraserver video_device:chr_file rw_file_perms;
+ ```
+
+Here is an example of `external_camera_config.xml` (copyright lines omitted)
+
+```
+<ExternalCamera>
+ <Provider>
+ <ignore> <!-- Internal video devices to be ignored by external camera HAL -->
+ <id>0</id> <!-- No leading/trailing spaces -->
+ <id>1</id>
+ </ignore>
+ </Provider>
+ <!-- See ExternalCameraUtils.cpp for default values of Device configurations below -->
+ <Device>
+ <!-- Max JPEG buffer size in bytes-->
+ <MaxJpegBufferSize bytes="3145728"/> <!-- 3MB (~= 1080p YUV420) -->
+ <!-- Size of v4l2 buffer queue when streaming >= 30fps -->
+ <!-- Larger value: more request can be cached pipeline (less janky) -->
+ <!-- Smaller value: use less memory -->
+ <NumVideoBuffers count="4"/>
+ <!-- Size of v4l2 buffer queue when streaming < 30fps -->
+ <NumStillBuffers count="2"/>
+
+ <!-- List of maximum fps for various output sizes -->
+ <!-- Any image size smaller than the size listed in Limit row will report
+ fps (as minimum frame duration) up to the fpsBound value. -->
+ <FpsList>
+ <!-- width/height must be increasing, fpsBound must be decreasing-->
+ <Limit width="640" height="480" fpsBound="30.0"/>
+ <Limit width="1280" height="720" fpsBound="15.0"/>
+ <Limit width="1920" height="1080" fpsBound="10.0"/>
+ <!-- image size larger than the last entry will not be supported-->
+ </FpsList>
+ </Device>
+</ExternalCamera>
+```
+
+## Customization
+
+You can enhance the Android camera either through general customization options
+or device-specific optimizations.
+
+### General customizations
+
+You can customize the external camera provider by modifying the
+`external_camera_config.xml` file. Specifically, clients can customize the
+following parameters:
+
++ Excluding video nodes of internal camera(s)
++ Supported image size and frame rate upper bound
++ Number of inflight buffers (jank vs memory tradeoff)
+
+In addition to these parameters, you can add your own parameters or develop your
+own configurations.
+
+### Device-specific optimizations
+
+You can also improve performance by adding device-specific optimizations.
+
+#### Buffer copy/scaling and JPEG decode/encode
+
+Generic implementations use CPU (libyuv/libjpeg) but you can replace this with
+device-specific optimizations.
+
+#### HAL output format
+
+Generic implementations use the following output formats:
+
++ YUV_420_888 for video IMPLEMENTATION_DEFINED buffers.
++ YV12 for all other IMPLEMENTATION_DEFINED buffers.
+
+To improve performance, you can replace output formats with device-specific
+efficient formats. You can also support additional formats in a customized
+implementation
+
+## Validation
+
+Devices with external camera support must pass camera CTS. The external USB
+webcam must remain plugged in the specific device during the entire test run,
+otherwise some test cases will fail.
+
+Note: `media_profiles` entries are not available for external USB webcams, so
+[camcorder profiles](https://developer.android.com/reference/android/media/CamcorderProfile)
+are absent.
diff --git a/en/devices/camera/images/buffer-sharing.png b/en/devices/camera/images/buffer-sharing.png
new file mode 100644
index 0000000..c6a0c03
--- /dev/null
+++ b/en/devices/camera/images/buffer-sharing.png
Binary files differ
diff --git a/en/devices/camera/images/multi-camera.png b/en/devices/camera/images/multi-camera.png
new file mode 100644
index 0000000..9c7723b
--- /dev/null
+++ b/en/devices/camera/images/multi-camera.png
Binary files differ
diff --git a/en/devices/camera/motion-tracking.md b/en/devices/camera/motion-tracking.md
new file mode 100644
index 0000000..f227518
--- /dev/null
+++ b/en/devices/camera/motion-tracking.md
@@ -0,0 +1,62 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Motion Tracking
+
+In Android {{ androidPVersionNumber }}, camera devices can advertise
+[motion tracking capability](https://developer.android.com/reference/android/hardware/camera2/CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_MOTION_TRACKING).
+Cameras that support this feature do not produce motion tracking data itself,
+but instead are used by ARCore or an image-stabilization algorithm along with
+other sensors for scene analysis. To support this feature, devices must support
+[`CONTROL_CAPTURE_INTENT_MOTION_TRACKING`](https://developer.android.com/reference/android/hardware/camera2/CameraMetadata#CONTROL_CAPTURE_INTENT_MOTION_TRACKING).
+If this intent is part of the capture request, the camera must limit the
+exposure time to a maximum of 20 milliseconds to reduce motion blur.
+
+## Examples and source
+
+A reference motion tracking implementation on the HAL side is available as part
+of the
+[Camera HAL](https://android.googlesource.com/platform/hardware/qcom/camera/+/master/msm8998/QCamera2/HAL3/QCamera3HWI.cpp).
+
+## Implementation
+
+To enable motion tracking on a camera device, make sure:
+
++ The
+ [`ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MOTION_TRACKING`](https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/metadata/3.3/types.hal#231)
+ capability is enabled.
++ The
+ [`ANDROID_CONTROL_CAPTURE_INTENT_MOTION_TRACKING`](https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/metadata/3.3/types.hal#207)
+ intent is supported and when included in a capture request limits the camera
+ exposure time to a maximum of 20 milliseconds.
++ Lens calibration data from the following list is accurately reported in the
+ static information and dynamic metadata fields:
+
+ + [`ANDROID_LENS_POSE_ROTATION`](https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/metadata/3.2/types.hal#747)
+ + [`ANDROID_LENS_POSE_TRANSLATION`](https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/metadata/3.2/types.hal#753)
+ + [`ANDROID_LENS_INTRINSIC_CALIBRATION`](https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/metadata/3.2/types.hal#773)
+ + [`ANDROID_LENS_RADIAL_DISTORTION`](https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/metadata/3.2/types.hal#780)
+ + [`ANDROID_LENS_POSE_REFERENCE`](https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/metadata/3.3/types.hal#79)
+
+## Validation
+
+Camera devices supporting the motion tracking feature must pass the
+[camera CTS tests](/compatibility/cts/camera-hal#cts_tests).
diff --git a/en/devices/camera/multi-camera.md b/en/devices/camera/multi-camera.md
new file mode 100644
index 0000000..e2c79e1
--- /dev/null
+++ b/en/devices/camera/multi-camera.md
@@ -0,0 +1,210 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Multi-Camera Support
+
+Android {{ androidPVersionNumber }} introduces API support for multi-camera
+devices via a new logical camera device composed of two or more physical camera
+devices pointing in the same direction. The logical camera device is exposed as
+a single CameraDevice/CaptureSession to an application allowing for interaction
+with HAL-integrated multi-camera features. Applications can optionally access
+and control underlying physical camera streams, metadata, and controls.
+
+
+
+**Figure 1**. Multi-camera support
+
+In this diagram, different camera IDs are color coded. The application can
+stream raw buffers from each physical camera at the same time. It is also
+possible to set separate controls and receive separate metadata from different
+physical cameras.
+
+## Examples and sources
+
+Multi-camera devices must be advertised via the
+[logical multi-camera capability](https://developer.android.com/reference/android/hardware/camera2/CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA).
+
+Camera clients can query the camera ID of the physical devices a particular
+logical camera is made of by calling
+[`getPhysicalCameraIds()`](https://developer.android.com/reference/android/hardware/camera2/CameraCharacteristics.html#getPhysicalCameraIds\(\)).
+The IDs returned as part of the result are then used to control physical devices
+individually via
+[`setPhysicalCameraId()`](https://developer.android.com/reference/android/hardware/camera2/params/OutputConfiguration.html#setPhysicalCameraId\(java.lang.String\)).
+The results from such individual requests can be queried from the complete
+result by invoking
+[`getPhysicalCameraResults()`](https://developer.android.com/reference/android/hardware/camera2/TotalCaptureResult.html#getPhysicalCameraResults\(\)).
+
+Individual physical camera requests may support only a limited subset of
+parameters. To receive a list of the supported parameters, developers can call
+[`getAvailablePhysicalCameraRequestKeys()`](https://developer.android.com/reference/android/hardware/camera2/CameraCharacteristics.html#getAvailablePhysicalCameraRequestKeys\(\)).
+
+Physical camera streams are supported only for non-reprocessing requests and
+only for monochrome and bayer sensors.
+
+## Implementation
+
+### Support checklist
+
+To add logical multi-camera devices on the HAL side:
+
++ Add a
+ [`ANDROID_REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA`](https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/metadata/3.3/types.hal#232)
+ capability for any logical camera device backed by two or more physical
+ cameras that are also exposed to an application.
++ Populate the static
+ [`ANDROID_LOGICAL_MULTI_CAMERA_PHYSICAL_IDS`](https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/metadata/3.3/types.hal#161)
+ metadata field with a list of physical camera IDs.
++ Populate the depth-related static metadata required to correlate between
+ physical camera streams' pixels:
+ [`ANDROID_LENS_POSE_ROTATION`](https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/metadata/3.2/types.hal#747),
+ [`ANDROID_LENS_POSE_TRANSLATION`](https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/metadata/3.2/types.hal#753),
+ [`ANDROID_LENS_INTRINSIC_CALIBRATION`](https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/metadata/3.2/types.hal#773),
+ [`ANDROID_LENS_RADIAL_DISTORTION`](https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/metadata/3.2/types.hal#780),
+ [`ANDROID_LENS_POSE_REFERENCE`](https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/metadata/3.3/types.hal#79)`
++ Set the static
+ [`ANDROID_LOGICAL_MULTI_CAMERA_SENSOR_SYNC_TYPE`](https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/metadata/3.3/types.hal#167)
+ metadata field to:
+
+ + [`ANDROID_LOGICAL_MULTI_CAMERA_SENSOR_SYNC_TYPE_APPROXIMATE`](https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/metadata/3.3/types.hal#256):
+ For sensors in master-master mode, no hardware shutter/exposure sync.
+ + [`ANDROID_LOGICAL_MULTI_CAMERA_SENSOR_SYNC_TYPE_CALIBRATED`](https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/metadata/3.3/types.hal#257):
+ For sensors in master-slave mode, hardware shutter/exposure sync.
+
++ Populate
+ [`ANDROID_REQUEST_AVAILABLE_PHYSICAL_CAMERA_REQUEST_KEYS`](https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/metadata/3.3/types.hal#106)
+ with a list of supported parameters for individual physical cameras. The
+ list can be empty if the logical device doesn't support individual requests.
+
++ If individual requests are supported, process and apply the individual
+ [`physicalCameraSettings`](https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/device/3.4/types.hal#226)
+ that can arrive as part of capture requests and append the individual
+ [`physicalCameraMetadata`](https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/device/3.4/types.hal#289)
+ accordingly.
+
+The camera device must support replacing one logical YUV/RAW stream with
+physical streams of the same size (RAW size is an exception) and format from two
+physical cameras.
+
+### Stream configuration map
+
+For a logical camera, the mandatory stream combinations for the camera device of
+a certain hardware level is the same as what's required in
+[`CameraDevice.createCaptureSession`](https://developer.android.com/reference/android/hardware/camera2/CameraDevice.html#createCaptureSession\(java.util.List<android.view.Surface>, android.hardware.camera2.CameraCaptureSession.StateCallback, android.os.Handler\)).
+All the streams in the stream configuration map should be fused/logical frames.
+
+If certain stream combinations cannot be fused, they should not be included in
+the logical camera's stream configuration map. Instead the application can look
+up the stream configuration map of the individual physical camera and configure
+the stream using the physical camera ID.
+
+This means that the logical camera's hardware level may be lower than that of
+individual cameras. One such example is when the two physical cameras have
+different raw sizes. The logical camera does not have RAW capability, so it
+cannot be a LEVEL_3 device, but the individual physical cameras can be LEVEL_3
+devices.
+
+For both the logical camera and the underlying physical cameras, the directly
+configured processed streams, RAW streams, and stall streams should not exceed
+the predefined `android.request.maxNumOutputStreams`.
+
+### Guaranteed stream combination
+
+Both the logical camera and its underlying physical cameras must guarantee the
+[mandatory stream combinations](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#createcapturesession_4)
+required for their device levels.
+
+A logical camera device should operate in the same way as a physical camera
+device based on its hardware level and capabilities. It's recommended that its
+feature set is a superset of that of individual physical cameras.
+
+Additionally, for each guaranteed stream combination, the logical camera must
+support:
+
++ Replacing one logical YUV_420_888 or raw stream with two physical streams of
+ the same size and format, each from a separate physical camera, given that
+ the size and format are supported by the physical cameras.
+
++ Adding two raw streams, one from each physical camera, if the logical camera
+ doesn't advertise RAW capability, but the underlying physical cameras do.
+ This usually occurs when the physical cameras have different sensor sizes.
+
+Using physical streams in place of a logical stream of the same size and format
+must not slow down the frame rate of the capture, as long as the minimum frame
+duration of the physical and logical streams are the same.
+
+### Performance and power considerations
+
++ Performance:
+
+ + Without attaching physical camera settings, physical streams should not
+ slow down capture rate.
+ + Applying physical camera settings may slow down the capture rate if the
+ underlying cameras are put into different frame rates.
+
++ Power:
+
+ + HAL's power optimization continues to work in the default case.
+ + Configuring or requesting physical streams may override HAL's internal
+ power optimization and incur more power use.
+
+## Customization
+
+You can customize your device implementation in the following ways.
+
++ The fused output of the logical camera device depends entirely on the HAL
+ implementation. The decision on how fused logical streams are derived from
+ the physical cameras is transparent to the application and Android camera
+ framework.
++ Individual physical requests and results can be optionally supported. The
+ set of available parameters in such requests is also entirely dependent on
+ the specific HAL implementation.
+
+## Validation
+
+Logical multi-camera devices must pass Camera CTS like any other regular camera.
+The test cases that target this type of device can be found in the
+[`LogicalCameraDeviceTest`](https://android.googlesource.com/platform/cts/+/master/tests/camera/src/android/hardware/camera2/cts/)
+module.
+
+These three ITS tests target multi-camera systems to facilitate the proper
+fusing of images:
+
++ [`scene1/test_multi_camera_match.py`](https://android.googlesource.com/platform/cts/+/master/apps/CameraITS/tests/scene1/)
++ [`scene4/test_multi_camera_alignment.py`](https://android.googlesource.com/platform/cts/+/master/apps/CameraITS/tests/scene4/)
++ [`sensor_fusion/test_multi_camera_frame_sync.py`](https://android.googlesource.com/platform/cts/+/master/apps/CameraITS/tests/sensor_fusion/)
+
+The scene1 and scene4 tests run with the
+[ITS-in-a-box](/compatibility/cts/camera-its-box) test
+rig. The `test_multi_camera_match` test asserts that the brightness of the
+center of the images match when the two cameras are both enabled. The
+`test_multi_camera_alignment` test asserts that camera spacings, orientations,
+and distortion parameters are properly loaded. If the multi-camera system
+includes a Wide FoV camera (>90o), the rev2 version of the ITS box is required.
+
+`Sensor_fusion` is a second test rig that enables repeated, prescribed phone
+motion and asserts that the gyroscope and image sensor timestamps match and that
+the multi-camera frames are in sync.
+
+All boxes are available through AcuSpec, Inc.
+([www.acuspecinc.com](http://www.acuspecinc.com), fred@acuspecinc.com) and MYWAY
+Manufacturing ([www.myway.tw](http://www.myway.tw), sales@myway.tw).
+Additionally, the rev1 ITS box can be purchased through West-Mark
+([www.west-mark.com](http://www.west-mark.com), dgoodman@west-mark.com).
diff --git a/en/devices/camera/session-parameters.md b/en/devices/camera/session-parameters.md
new file mode 100644
index 0000000..881f9db
--- /dev/null
+++ b/en/devices/camera/session-parameters.md
@@ -0,0 +1,88 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Session Parameters
+
+The session parameters feature reduces delays by enabling camera clients to
+actively configure the subset of costly request parameters, i.e. session
+parameters, as part of the capture session initialization phase. With this
+feature, your HAL implementations receive the client parameters during the
+stream configuration phase instead of the first capture request and can,
+depending on their values, prepare and build the internal pipeline more
+efficiently.
+
+## Examples and source
+
+A reference session parameter implementation is already part of the
+[CameraHal](https://android.googlesource.com/platform/hardware/qcom/camera/+/master/msm8998/QCamera2/HAL3/QCamera3HWI.cpp).
+This HAL uses the legacy Hal API.
+The [binderized](https://source.android.com/devices/architecture/hal-types)
+CameraHal that implements the camera HIDL API must use the respective HIDL
+[sessionParams](https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/device/3.4/types.hal#111)
+entry to access any new incoming session parameters during stream configuration.
+
+Camera clients can query the keys of all supported session parameters by calling
+[`getAvailableSessionKeys()`](https://developer.android.com/reference/android/hardware/camera2/CameraCharacteristics#getAvailableSessionKeys())
+and eventually set their initial values via
+[`setSessionParameters()`](https://developer.android.com/reference/android/hardware/camera2/params/SessionConfiguration#setSessionParameters\(android.hardware.camera2.CaptureRequest\)).
+
+## Implementation
+
+Your CameraHal implementation must populate the
+[`ANDROID_REQUEST_AVAILABLE_SESSION_KEYS`](https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/metadata/3.3/types.hal#99)
+within the respective static camera metadata and provide a subset of
+[`ANDROID_REQUEST_AVAILABLE_REQUEST_KEYS`](https://android.googlesource.com/platform/hardware/interfaces/+/master/camera/metadata/3.2/types.hal#1016),
+which contains a list of keys that are difficult to apply per-frame and can
+result in unexpected delays when modified during the capture session lifetime.
+
+Typical examples include parameters that require a time-consuming hardware
+reconfiguration or an internal camera pipeline change. Control over session
+parameters can still be exerted in capture requests but clients should be aware
+of and expect delays in their application.
+
+The framework monitors all incoming requests and if it detects a change in the
+value of a session parameter, it internally reconfigures the camera. The new
+stream configuration passed to CameraHal then includes the updated session
+parameter values, which are used to configure the camera pipeline more
+efficiently.
+
+## Customization
+
+You can define tags in the available session parameter list that is populated on
+the CameraHal side. This feature is not active if CameraHal leaves the
+available session parameter list empty.
+
+## Validation
+
+CTS includes the following new cases for testing session parameters:
+
++ [`CameraDeviceTest#testSessionConfiguration`](https://android.googlesource.com/platform/cts/+/master/tests/camera/src/android/hardware/camera2/cts/CameraDeviceTest.java#795)
++ [`CameraDeviceTest#testCreateSessionWithParameters`](https://android.googlesource.com/platform/cts/+/master/tests/camera/src/android/hardware/camera2/cts/CameraDeviceTest.java#1038)
++ [`CameraDeviceTest#testSessionParametersStateLeak`](https://android.googlesource.com/platform/cts/+/master/tests/camera/src/android/hardware/camera2/cts/CameraDeviceTest.java#870)
++ [`NativeCameraDeviceTest#testCameraDevicePreviewWithSessionParameters`](https://android.googlesource.com/platform/cts/+/master/tests/camera/libctscamera2jni/native-camera-jni.cpp#2140)
+
+In general, once a certain parameter is part of the session key list, its
+current value is included as part of the session parameters passed during stream
+configuration at the HAL layer.
+
+Session parameters must be carefully selected. The values should not change
+frequently, if at all, between stream configurations. Parameters that change
+frequently, such as capture intent, are ill-suited and adding them to the
+session parameter list could cause CTS failures due to excessive internal
+re-configuration.
diff --git a/en/devices/camera/singleprod-multiconsum.md b/en/devices/camera/singleprod-multiconsum.md
new file mode 100644
index 0000000..9191525
--- /dev/null
+++ b/en/devices/camera/singleprod-multiconsum.md
@@ -0,0 +1,66 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Single Producer Multiple Consumer Camera Buffer Transport
+
+This feature introduces a set of methods that allows camera clients to add and
+remove output surfaces dynamically while the capture session is active and
+camera streaming is ongoing. A new output can map to a specific, user-selected
+[shared camera](https://developer.android.com/reference/android/hardware/camera2/params/OutputConfiguration#enableSurfaceSharing\(\))
+stream. After a surface is added, it can be removed at any time.
+
+The general idea is to share the buffers associated with a particular camera
+stream within several output surfaces. An internal reference counter keeps track
+of the buffers as they become ready for further processing on the consumer side.
+When all consumers complete their respective tasks the buffer gets dequeued and
+is available for the camera.
+
+
+
+**Figure 1.** Buffer sharing
+
+Figure 1 depicts one example scenario where the buffers processed by camera
+stream 2 are dynamically attached and detached, reference counted, and managed
+by the stream splitter component inside a dedicated shared output stream within
+the camera service.
+
+## Examples and source
+
+The core implementation of this feature can be found in the
+[`Camera3StreamSplitter`](https://android.googlesource.com/platform/frameworks/av/+/master/services/camera/libcameraservice/device3/Camera3StreamSplitter.cpp)
+module. Documentation on this feature can be found in the developer reference:
+
++ [`updateOutputConfiguration()`](https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#updateOutputConfiguration\(android.hardware.camera2.params.OutputConfiguration\))
++ [`addSurface()`](https://developer.android.com/reference/android/hardware/camera2/params/OutputConfiguration#addSurface\(android.view.Surface\))
++ [`removeSurface()`](https://developer.android.com/reference/android/hardware/camera2/params/OutputConfiguration#removeSurface\(android.view.Surface\))
+
+## Implementation
+
+No implementation is required on the Camera HAL side as this feature is
+implemented on the framework side.
+
+## Validation
+
+Your implementation must pass CTS cases that cover this feature from the
+[MultiViewTest](https://android.googlesource.com/platform/cts/+/master/tests/camera/src/android/hardware/camera2/cts/MultiViewTest.java)
+module and the
+[native JNI library](https://android.googlesource.com/platform/cts/+/master/tests/camera/libctscamera2jni/native-camera-jni.cpp)
+for the native API.
diff --git a/en/devices/graphics/arch-vulkan.html b/en/devices/graphics/arch-vulkan.html
index d87c4c6..75baa7a 100644
--- a/en/devices/graphics/arch-vulkan.html
+++ b/en/devices/graphics/arch-vulkan.html
@@ -51,7 +51,7 @@
<h2 id=vulkan_components>Vulkan components</h2>
<p>Vulkan support includes the following components:</p>
<p><img src="/devices/graphics/images/ape_graphics_vulkan.png"></p>
-<p class=img-caption>Figure 1: Vulkan components</p>
+<p class=img-caption><strong>Figure 1.</strong> Vulkan components</p>
<ul>
<li><strong>Vulkan Validation Layers</strong> (<em>provided in the Android
diff --git a/en/devices/graphics/implement-vulkan.html b/en/devices/graphics/implement-vulkan.html
index 7b71c3d..c40ec85 100644
--- a/en/devices/graphics/implement-vulkan.html
+++ b/en/devices/graphics/implement-vulkan.html
@@ -5,6 +5,7 @@
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
+ {% include "_versions.html" %}
<!--
Copyright 2017 The Android Open Source Project
@@ -155,6 +156,54 @@
<a href="https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers/tree/android_layers">KhronosGroup/Vulkan-LoaderAndValidationLayers</a>
project on GitHub.</p>
+
+<h2 id="versions">Vulkan API Versions and Capabilities</h2>
+<p>This section describes the supported Vulkan API versions.</p>
+
+<h3 id="v1_0">Vulkan API version 1.0</h3>
+<p>The Android 7.0 release added support for Vulkan API version 1.0.</p>
+
+<h3 id="v1_1">Vulkan API version 1.1</h3>
+<p>The Android {{ androidPVersionNumber }} release introduces support for the Vulkan 1.1 graphics
+API. For more information about the Vulkan 1.1 API, see the
+<a href="https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html">
+Vulkan 1.1 API spec</a>.</p>
+
+<h4>Vulkan 1.1 support overview</h4>
+<p>Vulkan 1.1 support includes support for Vulkan 1.1 and memory/synchronization interop.
+This enables OEMs to support Vulkan 1.1 on devices, and developers to determine whether Vulkan 1.1
+is supported on a device, and use it effectively when it is. Vulkan 1.1 does not have new hardware
+requirements beyond Vulkan 1.0, but most of the implementation is in the SOC-specific graphics
+driver, not in the framework.</p>
+<p>The most important Vulkan 1.1 features for Android are:</p>
+<ul>
+<li>Support for importing and exporting memory buffers and synchronization objects from outside
+Vulkan (for interop with camera, codecs, and GLES)</li>
+<li>Support for YCbCr formats</li>
+</ul>
+<p>Vulkan 1.1 also includes several smaller features and API usability enhancements.</p>
+
+<h4>Implementing Vulkan 1.1</h4>
+<p>Vulkan 1.1 is optional in the Android {{ androidPVersionNumber }} release. To use it, a device
+must have a GPU that meets the minimum Vulkan 1.1 capabilities.</p>
+<p>To implement Vulkan 1.1:</p>
+<ol>
+<li>Add a Vulkan driver that supports Vulkan 1.1 plus the additional Android 1.1 requirements
+(make sure to view the {{ androidPVersionNumber }} API level documentation), or update the existing Vulkan 1.0 driver.</li>
+<li>You might need to update the kernel GPU driver, depending on your implementation.</li>
+<li>Ensure <code>PackageManager#hasSystemFeature(PackageManager.FEATURE_VULKAN_HARDWARE_VERSION, 0x401000)</code>
+returns <code>true</code> by adding a rule like the following to an appropriate <code>device.mk</code> file:
+<p><code>
+PRODUCT_COPY_FILES += frameworks/native/data/etc/android.hardware.vulkan.version-1_1.xml:
+$(TARGET_COPY_OUT_VENDOR)/etc/permissions/android.hardware.vulkan.version.xml
+</code></p></li>
+</ol>
+
+<h4>Customizing Vulkan 1.1</h4>
+<p>Applications that depend on Vulkan 1.1 are not compatible with devices that don’t provide Vulkan
+1.1 support. Some applications might not require Vulkan 1.1 but will provide additional features or
+performance when it is present.</p>
+
<h2 id=wsi>Window System Integration (WSI)</h2>
<p>The Window System Integration (WSI) extensions <code>VK_KHR_surface</code>,
<code>VK_KHR_android_surface</code>, and <code>VK_KHR_swapchain</code> are
@@ -351,9 +400,14 @@
without intervening calls to <code>vkAcquireImageANDROID</code>.
<h2 id=validation>Validation</h2>
-<p>OEMs can test their Vulkan implementation using CTS, which includes
-<a href="/devices/graphics/cts-integration.html">drawElements
-Quality Program (dEQP)</a> tests that exercise the Vulkan Runtime.</p>
+<p>OEMs can test their Vulkan implementation using CTS, which includes:</p>
+<ul>
+<li><a href="/devices/graphics/cts-integration.html">drawElements
+Quality Program (dEQP)</a> tests in the <code>CtsDeqpTestCases</code> module, which include
+functional API tests for Vulkan 1.0 and 1.1.</li>
+<li>The <code>CtsGraphicsTestCases</code> module, which tests that the device is configured
+correctly for Vulkan capabilities it supports.</li>
+</ul>
- </body>
+</body>
</html>
diff --git a/en/devices/images/ebpf-net-monitor.png b/en/devices/images/ebpf-net-monitor.png
new file mode 100644
index 0000000..bb9e437
--- /dev/null
+++ b/en/devices/images/ebpf-net-monitor.png
Binary files differ
diff --git a/en/devices/index.html b/en/devices/index.html
index e6d7b15..d20a3e0 100644
--- a/en/devices/index.html
+++ b/en/devices/index.html
@@ -1,12 +1,12 @@
<html devsite>
<head>
- <title>Android Interfaces and Architecture</title>
+ <title>Develop Android Devices</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
- Copyright 2017 The Android Open Source Project
+ Copyright 2018 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.
@@ -21,27 +21,10 @@
limitations under the License.
-->
-<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>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>
+<p>Welcome to the development documentation for the Android platform. Here you
+will find instructions for implementing particular Android interfaces. Use the
+horizontal menu above to delve into specific subtabs and sections.</p>
</body>
</html>
diff --git a/en/devices/interaction/images/neural_networks_interface.png b/en/devices/interaction/images/neural_networks_interface.png
new file mode 100644
index 0000000..64b435a
--- /dev/null
+++ b/en/devices/interaction/images/neural_networks_interface.png
Binary files differ
diff --git a/en/devices/interaction/neural-networks.md b/en/devices/interaction/neural-networks.md
new file mode 100644
index 0000000..0a3d081
--- /dev/null
+++ b/en/devices/interaction/neural-networks.md
@@ -0,0 +1,215 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Neural Networks API Drivers
+
+This document provides an overview on how to implement a Neural Networks API
+driver for Android {{ androidPVersionNumber }}. For full details, consult the
+documentation found in the HAL definition files in
+`hardware/interfaces/neuralnetworks. `You will find useful code, including a
+sample driver, in `frameworks/ml/nn/driver.`
+
+We suggest you familiarize yourself with the
+[Neural Networks API guide](https://developer.android.com/ndk/guides/neuralnetworks/){: .external}
+before reading this document.
+
+
+## Changes introduced in Android {{ androidPVersionNumber }}
+
+The 1.1 HAL is very similar to the 1.0 HAL introduced in Android 8.1. It contains
+three notable changes:
+
+
+* `IDevice::prepareModel_1_1 `includes an `ExecutionPreference` parameter. A
+ driver can use this to adjust its preparation, knowing that the application
+ prefers to conserve battery or will be executing the model in quick
+ successive calls.
+* Nine new operations have been added: `BATCH_TO_SPACE_ND`, `DIV`, `MEAN`,
+ `PAD`, `SPACE_TO_BATCH_ND`, `SQUEEZE`, `STRIDED_SLICE`, `SUB`, `TRANSPOSE`.
+* An application can specify that 32 bit float computations can be run using
+ 16 bit float range and/or precision by setting
+ `Model.relaxComputationFloat32toFloat16` to `true`. The `Capabilities`
+ struct has the additional field `relaxedFloat32toFloat16Performance` so that
+ the driver can report its relaxed performance to the Framework.
+
+
+## Overview
+
+The Neural Networks (NN) HAL defines an abstraction of the various accelerators.
+The drivers for these accelerators must conform to this HAL. Like all drivers
+implemented since the Android 8.0 release, the interface is specified in HIDL
+files.
+
+The general flow of the interface between the framework and a driver is depicted below:
+
+
+
+**Figure 1**: Neural Networks flow
+
+## Initialization
+
+At initialization, the Framework queries the driver for its capabilities. How
+fast can the accelerator process floating point and quantized tensors? How much
+power does the accelerator use doing so? The Framework uses this information to
+determine where a model will be executed. See `IDevice::getCapabilities `in
+`IDevice.hal`.
+
+
+## Request compilation
+
+For a given application request, the Framework needs to figure out which
+accelerators to use.
+
+At model compilation time, the framework sends the model to each driver by
+calling `IDevice::getSupportedOperations`. Each driver returns an array of
+booleans indicating which operations of the model are supported. The driver may
+decide that it can't support a given operation for many reasons, for example:
+
+
+* It does not support the data type or the operation,
+* It supports only operations with specific input parameters, e.g. it can do
+ convolve 3x3 and 5x5 but not 7x7, or
+* Memory constraints prevent it from handling large graphs or inputs.
+
+The Framework chooses which parts of the model to run on the available
+processors. It bases its decision on the performance characteristics of the
+processor and on the preference stated by the application, e.g., whether it
+prefers speed or energy efficiency. See the Performance Characteristics section
+below.
+
+The Framework instructs each selected driver to prepare to execute a subset of
+the model by calling `IDevice::prepareModel.` This instructs the driver to
+compile the request. A driver may for example generate code, create a re-ordered
+copy of the weights, etc. There may be a substantial time between the
+compilation of the model and the execution of requests, so precious resources
+like large chunks of device memory should not be assigned at this time.
+
+If any driver returns a failure code during the preparation, the Framework runs
+the entire model on the CPU. On success, an `IPreparedModel `handle is returned.
+
+A driver may want to cache to persistent storage the results of its compilation.
+This avoids a perhaps lengthy compilation step each time the application is
+started. The directory `frameworks/ml/nn/driver/cache` contains sample caching
+code. The `nnCache `subdirectory contains persistent storage code. A driver is
+free to use this implementation or any other. A driver is responsible for
+freeing cached artefacts when they are no longer useful.
+
+
+## Request execution
+
+When the application asks the Framework to execute a request, the Framework
+calls `IPreparedModel::execute` for each selected driver. The `Request
+`parameter passed to this function lists the input and output buffers used for
+the execution. Both input and output buffers use a standard format; see the
+Tensors section.
+
+The driver notifies the framework when the work has been completed via the
+`IExecutionCallback`.
+
+For user requests that span multiple processors, the Framework is responsible
+for reserving the intermediate memory and for sequencing the calls to each
+driver.
+
+Multiple requests can be initiated in parallel on the same `IPreparedModel. `A
+driver is free to execute them in parallel or to serialize their executions.
+
+A driver may also be asked to keep around more than one prepared model. E.g.
+prepare m1, prepare m2, run r1 on m1, run r2 on m2, run r3 on m1, run r4 on m2,
+… delete m1, delete m2.
+
+To avoid a slow first execution that could result in a poor user experience
+(e.g., a first frame stutter), we recommend that the driver perform most
+initializations in the compilation phase. Initialization on first execution
+should be limited to actions that would negatively affect system health if done
+very early, like reserving large temporary buffers or increasing the clock rate
+of the accelerator. Drivers that can only prepare a very limited number of
+concurrent models may also have to do their initialization at first execution.
+
+To give good performance on quick successive executions, a driver may want to
+hold on to temporary buffers or increased clock rates. We recommend that a
+watchdog thread be created to release these resources if no new requests have
+been created after a fixed period of time.
+
+When an application is finished using a prepared model, the Framework releases
+its reference to the `IPreparedModel` object. Shortly after, the
+`IPreparedModel` object will be destroyed in the driver service that created it.
+Model-specific resources can be reclaimed at this time in the implementation of
+the destructor.
+
+
+## Performance characteristics
+
+To determine how to allocate the computations to the available accelerators, the
+Framework must understand the efficiency of each accelerator: how fast it can
+execute a query and how energy efficient it is.
+
+While the performance could be simply measured by running a sample workload on
+device, battery drain is harder to measure. For this reason, at initialization
+time, the driver will provide standardized numbers on how fast and how
+efficiently it can execute a few reference workloads.
+
+This is an imperfect method. A lot of factors affect the actual runtime
+performance: type of data, size of the tensors, operator types, etc.
+
+In Android {{ androidPVersionNumber }}, we recommend that you use MobileNets
+quantized and MobileNets floats as reference workloads when determining the
+values that the driver must return in response to the `getCapabilities `call`.
+`The MobileNets floats model should be used to measure both the full 32 bit
+float performance and the relaxed 16 bit float performance.
+
+A driver does not benefit from misrepresenting these numbers. Doing so will lead
+the Framework to doing suboptimal work assignment. In future releases, these
+numbers could be subject to verification by VTS.
+
+
+## CPU usage
+
+Drivers will use the CPU to set up the computations. They should not use the CPU
+to perform graph computations, as this will interfere with the ability of the
+Framework to allocate the work correctly. A driver should simply report to the
+Framework the parts it can't handle, and let the Framework handle the rest.
+
+There is no driver for the CPU. The Framework provides a CPU based
+implementation of all operations except for OEM operations.
+
+
+## Testing
+
+Google provides a complete set of VTS tests. These tests exercise each API. They
+also verify that all operators supported by a driver work correctly, and give
+results of sufficient precision.
+
+For Android {{ androidPVersionNumber }}, we've selected the following ad-hoc
+precision requirements: 1e-5 for float, off-by-one for quantized. In the future,
+we hope to establish more rigorous precision requirements based on tests on a
+wide range of models and implementations.
+
+
+## Security
+
+Because application processes communicate directly to a driver's process, the
+driver code must validate the arguments of the calls it receives. This
+validation is verified by VTS. See `frameworks/ml/nn/include/ValidateHal.h` for
+validation code.
+
+Additionally, drivers should ensure that applications can't interfere with each
+other even when they use the same accelerator.
+
diff --git a/en/devices/storage/adoptable.html b/en/devices/storage/adoptable.html
index 7d16762..85e8b10 100644
--- a/en/devices/storage/adoptable.html
+++ b/en/devices/storage/adoptable.html
@@ -27,16 +27,20 @@
<p>Android has always supported external storage accessories (such as SD cards), but
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>.
+<a href="/devices/storage/traditional">traditional external storage</a>.
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>
+<a href="http://developer.android.com/about/versions/marshmallow/android-6.0.html#adoptable-storage"
+ class="external">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>
+<aside class="caution">
+ <p><strong>Caution</strong>: On devices running Android 7.0-8.1,
+ <a href="/security/encryption/file-based">file-based encryption</a>
+ (FBE) can't be used together with adoptable storage. On devices
+ using FBE, new storage media (such as an SD card) must be used as
+ <a href="/devices/storage/traditional">traditional storage</a>.</p>
+ <p>Devices running Android 9 and higher can use adoptable storage and FBE.</p>
+</aside>
<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
@@ -47,11 +51,13 @@
location, Android asks them how they want to use the media. They can choose to
adopt the media, which formats and encrypts it, or they can continue using it
as-is for simple file storage. If they choose to adopt, the platform offers to
-migrate the primary shared storage contents (typically mounted at <code>/sdcard</code>)
-to the newly adopted media, freeing up valuable space on internal storage.
-Unlike traditional storage, which is limited to 2TB due to its use of
-<a href="https://en.wikipedia.org/wiki/Master_boot_record">MBR</a>, adoptable
-storage uses <a href="https://en.wikipedia.org/wiki/GUID_Partition_Table">GPT</a>
+migrate the primary shared storage contents (typically mounted at
+<code>/sdcard</code>) to the newly adopted media, freeing up valuable space on
+internal storage. Unlike traditional storage, which is limited to 2TB due to its
+use of
+<a href="https://en.wikipedia.org/wiki/Master_boot_record" class="external">MBR</a>,
+adoptable storage uses
+<a href="https://en.wikipedia.org/wiki/GUID_Partition_Table" class="external">GPT</a>
and therefore has file storage limit of ~9ZB.</p>
<p>Apps can be placed on adopted storage media only when the developer has
@@ -62,7 +68,7 @@
media are remembered while the media is ejected,
and return when the media is reinserted.</p>
-<h2 id=security>Security</h2>
+<h2 id="security">Security</h2>
<p>The platform randomly generates an encryption key for each adopted device,
@@ -70,8 +76,9 @@
effectively makes the adopted media as secure as internal storage. Keys are
associated with adopted devices based on the adopted partition GUID. The
adopted device is encrypted using <code>dm-crypt</code> configured with the
-<code>aes-cbc-essiv:sha256</code> algorithm and a 128-bit key size.</p>
-
+<code>aes-cbc-essiv:sha256</code> algorithm
+and a 128-bit key size.
+</p>
<p>The on-disk layout of the adopted device closely mirrors the internal data
partition, including SELinux labels, etc. When multi-user is supported on the
Android device, the adopted storage device also supports multi-user with the
@@ -79,9 +86,27 @@
<p>Because the contents of an adopted storage device are strongly tied to the
Android device that adopted it, the encryption keys should not be extractable
-from the parent device, and therefore the storage device can't be mounted elsewhere.</p>
+from the parent device, and therefore the storage device can't be mounted
+elsewhere.</p>
-<h2 id=performance_and_stability>Performance and stability</h2>
+<p>
+The default encryption algorithm for contents mode is <code>aes-256-xts</code>
+and for filenames is <code>aes-256-heh</code>. You can change these by changing
+the values of the properties <code>ro.crypto.volume.contents_mode</code> and
+<code>ro.crypto.volume.filenames_mode</code> respectively, by setting
+<code>PRODUCT_PROPERTY_OVERRIDES</code> in <code>device.mk</code>.
+</p>
+<p>
+If your kernel does not support HEH filename encryption, you can use CTS mode
+instead by adding the following to device.mk:
+</p>
+
+
+<pre
+class="prettyprint">PRODUCT_PROPERTY_OVERRIDES += \
+ro.crypto.volume.filenames_mode=aes-256-cts</pre>
+
+<h2 id="performance_and_stability">Performance and stability</h2>
<p>Only external storage media in stable locations, such as a slot inside a
@@ -100,15 +125,63 @@
further, such as rejecting adoption completely if the card is extremely slow.</p>
<p>Adopted devices must be formatted with a filesystem that supports POSIX
-permissions and extended attributes, such as <code>ext4</code> or <code>f2fs</code>.
-For optimal performance, the <code>f2fs</code> filesystem is recommended for
-flash-based storage devices.</p>
+permissions and extended attributes, such as <code>ext4</code> or
+<code>f2fs</code>. For optimal performance, the <code>f2fs</code> filesystem is
+recommended for flash-based storage devices.</p>
-<p>When performing periodic idle maintenance, the platform issues <code>FI_TRIM</code>
-to adopted media just like it does for internal storage. The current SD card
-specification does not support the <code>DISCARD</code> command; but the kernel
-instead falls back to the <code>ERASE</code> command, which SD card firmware
-may choose to use for optimization purposes.</p>
+<p>When performing periodic idle maintenance, the platform issues
+<code>FI_TRIM</code> to adopted media just like it does for internal storage.
+The current SD card specification does not support the <code>DISCARD</code>
+command; but the kernel instead falls back to the <code>ERASE</code> command,
+which SD card firmware may choose to use for optimization purposes.</p>
+
+<h3 id="fixing-double-encryption">Fixing double encryption</h3>
+
+<p>In Android 8.x and lower, adoptable storage didn't work with FBE. All
+existing devices that have adoptable storage used
+<a href="/security/encryption/full-disk">full-disk encryption</a> (FDE).
+In Android 9, adoptable storage works with FBE and is encrypted using
+<a href="/security/encryption/metadata">metadata encryption</a>. However, by
+default, file contents are double-encrypted because adoptable storage has an
+FDE and FBE layer. By default, both layers encrypt file contents, which can
+slow device performance. To fix the problem of double encryption and speed up
+device performance:
+</p>
+<ol>
+ <li>Add <a href="https://android-review.googlesource.com/q/REQ_NOENCRYPT"
+ class="external">these patches</a> to your kernel.</li>
+ <li>To communicate this change with <code>vold</code>, add the following to
+ <code>device.mk</code>:
+ <pre class="prettyprint">PRODUCT_PROPERTY_OVERRIDES += ro.crypto.allow_encrypt_override=true</pre></li>
+</ol>
+<p>
+If you set this, but the kernel patches aren't present, adoptable storage won't
+work, and the <code>vold</code> logs will contain an error that it was unable
+to create the dm device.
+</p>
+<aside class="caution">
+ <strong>Caution:</strong> Don't change this flag with an OTA update because
+ it changes the on-disk format of adoptable storage.
+</aside>
+
+<h2 id="testing">Testing</h2>
+<p>
+To test that adoptable storage is working, run this CTS test:
+</p>
+
+
+<pre
+class="devsite-terminal devsite-click-to-copy">cts-tradefed run commandAndExit cts-dev \
+ -m CtsAppSecurityHostTestCases \
+ -t android.appsecurity.cts.AdoptableHostTest</pre>
+<p>
+To verify behavior of USB drives and SD cards when a device doesn't have a
+built-in slot or when the USB connector is being used for an active adb
+connection, use:
+</p>
+<pre class="prettyprint">
+adb shell sm set-virtual-disk true
+</pre>
</body>
</html>
diff --git a/en/devices/tech/admin/images/Work-profile0.png b/en/devices/tech/admin/images/Work-profile0.png
new file mode 100755
index 0000000..9095c70
--- /dev/null
+++ b/en/devices/tech/admin/images/Work-profile0.png
Binary files differ
diff --git a/en/devices/tech/admin/images/Work-profile1.png b/en/devices/tech/admin/images/Work-profile1.png
new file mode 100755
index 0000000..5487568
--- /dev/null
+++ b/en/devices/tech/admin/images/Work-profile1.png
Binary files differ
diff --git a/en/devices/tech/admin/images/Work-profile2.png b/en/devices/tech/admin/images/Work-profile2.png
new file mode 100755
index 0000000..cff8e03
--- /dev/null
+++ b/en/devices/tech/admin/images/Work-profile2.png
Binary files differ
diff --git a/en/devices/tech/admin/images/Work-profile3.png b/en/devices/tech/admin/images/Work-profile3.png
new file mode 100755
index 0000000..c0d3061
--- /dev/null
+++ b/en/devices/tech/admin/images/Work-profile3.png
Binary files differ
diff --git a/en/devices/tech/admin/images/Work-profile4.png b/en/devices/tech/admin/images/Work-profile4.png
new file mode 100755
index 0000000..c8f77b1
--- /dev/null
+++ b/en/devices/tech/admin/images/Work-profile4.png
Binary files differ
diff --git a/en/devices/tech/admin/images/Work-profile5.png b/en/devices/tech/admin/images/Work-profile5.png
new file mode 100755
index 0000000..ba56faa
--- /dev/null
+++ b/en/devices/tech/admin/images/Work-profile5.png
Binary files differ
diff --git a/en/devices/tech/admin/images/Work-profile6.png b/en/devices/tech/admin/images/Work-profile6.png
new file mode 100755
index 0000000..5487568
--- /dev/null
+++ b/en/devices/tech/admin/images/Work-profile6.png
Binary files differ
diff --git a/en/devices/tech/admin/images/Work-profile7.png b/en/devices/tech/admin/images/Work-profile7.png
new file mode 100755
index 0000000..5969204
--- /dev/null
+++ b/en/devices/tech/admin/images/Work-profile7.png
Binary files differ
diff --git a/en/devices/tech/admin/managed-profiles.html b/en/devices/tech/admin/managed-profiles.html
index 3a37c76..17df9a6 100644
--- a/en/devices/tech/admin/managed-profiles.html
+++ b/en/devices/tech/admin/managed-profiles.html
@@ -21,11 +21,11 @@
limitations under the License.
-->
-
+ {% include "_versions.html" %}
<p>A <em>managed profile</em> or <em>work profile</em> is an Android <a
-href="multi-user.html">user</a> with additional special properties around
-management and visual aesthetic.</p>
+href="/devices/tech/admin/multi-user.html">user</a> with additional special
+properties around management and visual aesthetic.</p>
<p>The primary goal of a managed profile is to create a segregated and secure
space for managed data (such as corporate data) to reside. The administrator of
@@ -50,29 +50,31 @@
available inline with user interface (UI) elements from the primary user.</li>
</ul>
-<h2 id=data_segregation>Data segregation</h2>
+<h2 id="data_segregation">Data segregation</h2>
<p>Managed profiles use the following data segregation rules.</p>
-<h3 id=applications>Applications</h3>
+<h3 id="applications">Applications</h3>
<p>Applications are scoped with their own segregated data when the same app
exists in the primary user and managed profile. Generally, applications act
independently of one another and cannot communicate directly with one another
across the profile-user boundary.</p>
-<h3 id=accounts>Accounts</h3>
+<h3 id="accounts">Accounts</h3>
-<p>Accounts in the managed profile are distinctly unique from the primary user.
+<p>
+Accounts in the managed profile are distinctly unique from the primary user.
There is no way to access credentials across the profile-user boundary. Only
-apps in their respective context are able to access their respective accounts.</p>
+apps in their respective context are able to access their respective accounts.
+</p>
-<h3 id=intents>Intents</h3>
+<h3 id="intents">Intents</h3>
<p>The administrator controls whether intents are resolved in/out of managed
profile or not. Applications from the managed profile are default scoped to
stay within the managed profile exception of the Device Policy API.</p>
-<h3 id=settings>Settings</h3>
+<h3 id="settings">Settings</h3>
<p>Enforcement of settings is generally scoped to the managed profile, with
exceptions for lockscreen and encryption settings that are still scoped
@@ -80,7 +82,9 @@
Otherwise, a profile owner does not have any device administrator privileges
outside the managed profile.</p>
-<p>Managed profiles are implemented as a new kind of secondary user, such that:</p>
+<p>
+Managed profiles are implemented as a new kind of secondary user, such that:
+</p>
<pre class="devsite-click-to-copy">
uid = 100000 * userid + appid
@@ -115,7 +119,7 @@
switching users.</li>
</ul>
-<h2 id=device_administration>Device administration</h2>
+<h2 id="device_administration">Device administration</h2>
<p>Android device administration includes the following types of device
administrators for enterprises:</p>
@@ -131,7 +135,7 @@
remain but are applicable to the simpler consumer-only case (e.g., find my
device).</p>
-<h3 id=profile_owners>Profile owners</h3>
+<h3 id="profile_owners">Profile owners</h3>
<p>A Device Policy Client (DPC) app typically functions as the profile owner.
The DPC app is typically provided by an enterprise mobility management (EMM)
@@ -146,7 +150,7 @@
<p>The EMM has control only over the managed profile (not personal space) with
some exceptions, such as enforcing the lock screen.</p>
-<h3 id=device_owners>Device owners</h3>
+<h3 id="device_owners">Device owners</h3>
<p>The device owner can be set only in an unprovisioned device:</p>
@@ -168,7 +172,7 @@
cannot be mounted.</li>
</ul>
-<h3 id=dpm_api>DevicePolicyManager APIs</h3>
+<h3 id="dpm_api">DevicePolicyManager APIs</h3>
<p>Android 5.0 and higher offers a greatly improved DevicePolicyManager with
dozens of new APIs to support both corporate-owned and bring your own device
@@ -182,5 +186,228 @@
class="external">Building
a Work Policy Controller</a>.</p>
+<h2 id="user-experience">Managed profile user experience</h2>
+
+ <p>
+ Android {{ androidPVersionNumber }} creates a tighter integration between
+ managed profiles and the platform, making it easier for users to keep their
+ work and personal information separate on their devices. These managed
+ profile user experience changes appear in the Launcher. Implementing the UX
+ managed profile changes creates a consistent user experience across managed
+ devices.
+ </p>
+
+ <h3 id="ux-changes-app-try">UX changes for devices with an app try</h3>
+
+ <p>
+ The managed profile UX changes for Launcher 3 in Android
+ {{ androidPVersionNumber }} help users maintain separate personal and
+ managed profiles. The apps drawer provides a tabbed view to distinguish
+ between personal profile apps. When users first view the managed profile
+ tab, they are presented with an educational view to help them navigate
+ the managed profile. Users can also turn the managed profile on and off
+ by using a toggle in the Launcher's work tab.
+ </p>
+
+ <h4 id="tabbed-profile-views">Tabbed profile views</h4>
+
+ <p>
+ In Android {{ androidPVersionNumber }}, the managed profile lets users
+ switch between personal and managed app lists in the apps drawer. When
+ the managed profile is enabled, the app views are separated into two
+ distinct
+ <a
+ href="https://developer.android.com/reference/android/support/v7/widget/RecyclerView.html"
+ class="external"><code>RecyclerViews</code></a>, managed by a
+ <a
+ href="https://developer.android.com/reference/android/support/v4/view/ViewPager.html"
+ class="external"><code>ViewPager</code></a>. Users can switch between
+ the different profiles' views by using profile tabs at the top of the
+ app drawer. The <code>PersonalWorkSlidingTabStrip</code> class
+ provides a reference implementation of the tabbed profile indicator.
+ The tabbed view is implemented as part of the Launcher3 class
+ <a
+ href="https://android.googlesource.com/platform/packages/apps/Launcher3/+/master/src/com/android/launcher3/allapps/AllAppsContainerView.java"
+ class="external"><code>AllAppsContainerView</code></a>.
+ </p>
+
+ <table>
+ <tr>
+ <td width="50%">
+ <img src="/devices/tech/admin/images/Work-profile0.png" width=""
+ alt="Personal tab view" title="image_tooltip">
+ </td>
+ <td width="50%">
+ <img src="/devices/tech/admin/images/Work-profile1.png" width=""
+ alt="Managed profile toggle" title="image_tooltip">
+ </td>
+ </tr>
+ <tr>
+ <td><strong>Figure 1.</strong> Personal tab view</td>
+ <td><strong>Figure 2.</strong> Work tab view with the managed profile
+ toggle at the bottom of the screen
+ </td>
+ </tr>
+ </table>
+
+ <h4 id="educational-view">Educational view</h4>
+
+ <p>
+ Launcher3 also has the option of presenting an educational view at the
+ bottom of the screen when users first open the work tab, as seen in
+ <strong>Figure 3</strong>. Use the educational view to inform users of
+ the purpose of the work tab and how to make work apps easier to access.
+ </p>
+
+ <p>
+ The educational view is defined in Android {{ androidPVersionNumber }}
+ and higher by the class
+ <code>BottomUserEducationView</code> with the layout controlled by
+ <code>work_tab_tottom_user_education_view.xml</code>. Within
+ <code>BottomUserEducationView</code>, the
+ <code>KEY_SHOWED_BOTTOM_USER_EDUCATION</code> boolean is set to
+ <code>false</code> by default. When the user dismisses the educational
+ view, the boolean is set to <code>true</code>.
+ </p>
+
+ <p>
+ <img src="/devices/tech/admin/images/Work-profile2.png" width="50%"
+ alt="Educational view" title="image_tooltip">
+ <p class="img-caption">
+ <strong>Figure 3.</strong> Educational view in work tab
+ </p>
+ </p>
+
+ <h4 id="toggle-to-enable-disable">
+ Toggle to enable/disable managed profiles
+ </h4>
+
+ <p>
+ Within the work tab, managed device administrators can present a toggle
+ in the footer view for users to enable or disable the managed profile as
+ seen in <strong>Figure 2</strong> above. The source for the toggle can be
+ found in <code>WorkFooterContainer</code>, starting in Android
+ {{ androidPVersionNumber }}. Enabling and disabling the managed profile
+ is done asynchronously and applied to all valid user profiles. This
+ process is controlled by the<code>WorkModeSwitch</code> class in Android
+ {{ androidPVersionNumber }}.
+ </p>
+
+ <h3 id="ux-changes-without-an-app-tray">
+ UX changes for devices without an app tray
+ </h3>
+
+ <p>
+ For launchers without an app tray, it is recommended to continue placing
+ shortcuts to the managed profile apps in the work folder.
+ </p>
+
+ <p>
+ If the work folder fails to populate correctly, and newly installed apps
+ are not added to the folder, apply the following change in the
+ <code>onAllAppsLoaded</code> method in the
+ <a
+ href="https://android.googlesource.com/platform/packages/apps/Launcher3/+/master/src/com/android/launcher3/util/ManagedProfileHeuristic.java"
+ class="external"><code>ManagedProfileHeuristic</code></a> class:
+ </p>
+
+<pre class="prettyprint">for (LauncherActivityInfo app : apps) {
+ // Queue all items which should go in the work folder.
+ if (app.getFirstInstallTime() < Long.MAX_VALUE) {
+ InstallShortcutReceiver.queueActivityInfo(app, context);
+ }
+}</pre>
+
+
+ <h3 id="validating-ux-changes">Validating UX changes</h3>
+
+ <p>
+ Test the managed profile UX implementation using the TestDPC app.
+ </p>
+
+ <ol>
+ <li>Install the
+ <a
+ href="https://play.google.com/store/apps/details?id=com.afwsamples.testdpc"
+ class="external">TestDPC</a> app from the Google Play Store.
+ </li>
+ <li>
+ Open the launcher or app drawer and select the <strong>Set up
+ TestDPC</strong> icon.
+ </li>
+ <li>Follow the on-screen instructions to set up a managed profile.</li>
+ <li>
+ Open the launcher or app drawer and verify that there is a work tab
+ there.
+ </li>
+ <li>
+ Verify that there is a managed profile footer under the work tab.
+ </li>
+ <li>
+ Verify that you can toggle the managed profile switch on and off. The
+ managed profile should be enabled and disabled accordingly.
+ </li>
+ </ol>
+
+ <table>
+ <tr>
+ <td width="33%">
+ <img src="/devices/tech/admin/images/Work-profile3.png" width=""
+ alt="TestDPC profile setup" title="image_tooltip">
+ </td>
+ <td width="33%">
+ <img src="/devices/tech/admin/images/Work-profile4.png" width=""
+ alt="TestDPC add accounts" title="image_tooltip">
+ </td>
+ <td width="33%">
+ <img src="/devices/tech/admin/images/Work-profile5.png" width=""
+ alt="TestDPC setup complete" title="image_tooltip">
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <strong>Figure 4.</strong> Setting up a managed profile in <strong>Set up TestDPC</strong>
+ </td>
+ <td>
+ <strong>Figure 5.</strong> Add accounts in <strong>Set up TestDPC</strong>
+ </td>
+ <td>
+ <strong>Figure 6.</strong> Set up complete
+ </td>
+ </tr>
+ </table>
+
+ <table>
+ <tr>
+ <td width="50%">
+ <img src="/devices/tech/admin/images/Work-profile6.png" width=""
+ alt="App drawer work tab toggle on" title="image_tooltip">
+ </td>
+ <td width="50%">
+ <img src="/devices/tech/admin/images/Work-profile7.png" width=""
+ alt="App drawer work tab toggle off" title="image_tooltip">
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <strong>Figure 7.</strong> App drawer with a work tab. The managed
+ profile footer switch is <strong>ON</strong>, and the managed profile
+ is enabled.
+ </td>
+ <td>
+ <strong>Figure 8.</strong> App drawer with a work tab. The managed
+ profile footer switch is <strong>OFF</strong>, and the managed
+ profile is disabled.
+ </td>
+ </tr>
+ </table>
+
+ <h3 id="managed-profile-app-badge">Managed profile app badge</h3>
+
+ <p>
+ For accessibility reasons, the color of the work badge changes from
+ orange to blue (#1A73E8) in Android {{ androidPVersionNumber}}.
+ </p>
+
</body>
</html>
diff --git a/en/devices/tech/admin/ota-updates.html b/en/devices/tech/admin/ota-updates.html
new file mode 100644
index 0000000..62f07bd
--- /dev/null
+++ b/en/devices/tech/admin/ota-updates.html
@@ -0,0 +1,184 @@
+<html devsite>
+ <head>
+ <title>Enterprise OTA Updates</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ <body>
+ <!--
+ Copyright 2018 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.
+ -->
+
+ {% include "_versions.html" %}
+
+ <p>
+ The
+ <a href="https://source.android.com/compatibility/android-cdd#11_updatable_software">Android
+ Compatibility Definition Document (CDD) Updatable Software</a>
+ requires devices to implement the
+ <a
+ href="https://developer.android.com/reference/android/app/admin/SystemUpdatePolicy.html"
+ class="external"><code>SystemUpdatePolicy</code></a>
+ class. <code>SystemUpdatePolicy</code> lets the Device Owner (DO) app, if
+ present, control the installation of system updates.
+ </p>
+
+ <p>
+ Android {{ androidPVersionNumber }} enhances the ability for device
+ owners to control updates by allowing device owners to postpone
+ over-the-air (OTA) updates for up to 90 days. Focusing on
+ corporate-owned, single-use (COSU) solutions, this feature lets owners
+ pause the OS version running on devices over critical periods, such as
+ holidays.
+ </p>
+
+ <h2 id="system-update-policy">System update policy</h2>
+
+ <p>
+ To comply with the CDD, the OTA client must implement behavioral
+ policies. The DO can set the following policies, which must be
+ respected by the device system update subsystems:
+ </p>
+
+ <ul>
+ <li>
+ <a
+ href="https://developer.android.com/reference/android/app/admin/SystemUpdatePolicy.html#TYPE_INSTALL_AUTOMATIC"
+ class="external"><code>TYPE_INSTALL_AUTOMATIC</code></a>
+ </li>
+ <li>
+ <a
+ href="https://developer.android.com/reference/android/app/admin/SystemUpdatePolicy.html#TYPE_INSTALL_WINDOWED"
+ class="external"><code>TYPE_INSTALL_WINDOWED</code></a>
+ </li>
+ <li>
+ <a
+ href="https://developer.android.com/reference/android/app/admin/SystemUpdatePolicy.html#TYPE_POSTPONE"
+ class="external"><code>TYPE_POSTPONE</code></a>
+ </li>
+ </ul>
+
+ <h2 id="implementing-installation-options">
+ Implementing installation options
+ </h2>
+
+ <p>
+ Android {{ androidPVersionNumber }} introduces an @SystemApi,
+ <code>SystemUpdatePolicy.InstallationOption</code>, that is designed
+ for the system update clients.
+ <code>SystemUpdatePolicy.InstallationOption</code> serves as a wrapper
+ class for the policies. An installation option tells clients how to act
+ on incoming system updates and how long that action is valid for, given
+ the current system update policy. An installation option can be one of
+ the following:
+ </p>
+
+ <ul>
+ <li>
+ <code>TYPE_INSTALL_AUTOMATIC</code> - Incoming system updates install
+ immediately and without user intervention as soon as they become
+ available. The device reboots automatically.
+ </li>
+ <li>
+ <code>TYPE_POSTPONE</code> - Incoming system updates can be delayed
+ for a maximum of 30 days. Users cannot install an update manually.
+ Device manufacturers can choose whether or not to block security
+ patches.
+ </li>
+ <li>
+ <code>TYPE_PAUSE</code> - Incoming system updates can be delayed
+ indefinitely until further notice. Users cannot install an update
+ manually. <code>TYPE_PAUSE</code> delays all updates, including
+ security patches.
+ </li>
+ </ul>
+
+ <p>
+ System update clients can query
+ <code>SystemUpdatePolicy.InstallationOption</code> using
+ <code>SystemUpdatePolicy.getInstallationOptionAt(long <var>when</var>)</code>,
+ where <var>when</var> represents the time the installation option is
+ being queried in number of milliseconds since Epoch. Using the
+ <code>SystemUpdatePolicy.getInstallationOptionAt(long <var>when</var>)</code>
+ method, system update clients can act on the returned option until the
+ effective time lapses. After the returned option lapses, the client can
+ make another query, using a new timestamp, for the most recent option.
+ </p>
+
+ <p>
+ The system update client must listen for
+ <code>DevicePolicyManager.ACTION_SYSTEM_UPDATE_POLICY_CHANGED</code>
+ broadcasts in case the whole policy is updated.
+ </p>
+
+ <h2 id="validating-the-type_pause-policy">
+ Validating the <code>TYPE_PAUSE</code> policy
+ </h2>
+
+ <p>
+ You can manually validate the <code>TYPE_PAUSE</code> option works
+ on an OTA system.
+ </p>
+
+ <h3 id="policy-type_pause-in-effect">
+ Policy <code>TYPE_PAUSE</code> is in effect
+ </h3>
+
+ <p>
+ To validate a <code>TYPE_PAUSE</code> policy is working:
+ </p>
+
+ <ol>
+ <li>
+ Set an automatic policy and specify <code>TYPE_PAUSE</code>.
+ </li>
+ <li>
+ While the system clock is in the pause period, push an OTA update.
+ </li>
+ <li>
+ Verify the device does not take the OTA update and the user
+ cannot manually install the update.
+ </li>
+ <li>
+ If the device is an A/B device, reboot the device and verify the
+ reboot did not trigger an auto-install of the update.
+ </li>
+ </ol>
+
+ <h3 id="policy-type_pause-is-expired">
+ Policy <code>TYPE_PAUSE</code> is expired
+ </h3>
+
+ <p>
+ To validate an expired <code>TYPE_PAUSE</code> policy is working:
+ </p>
+
+ <ol>
+ <li>
+ Set an automatic policy and specify <code>TYPE_PAUSE</code>.
+ </li>
+ <li>
+ While the system clock is in the pause period, push an OTA update.
+ </li>
+ <li>
+ Wait for the pause to period to expire.
+ </li>
+ <li>
+ Verify the device automatically reboots and the OTA update is
+ taken after the reboot.
+ </li>
+ </ol>
+ </body>
+</html>
diff --git a/en/devices/tech/config/carrierid.html b/en/devices/tech/config/carrierid.html
new file mode 100644
index 0000000..58be2e0
--- /dev/null
+++ b/en/devices/tech/config/carrierid.html
@@ -0,0 +1,78 @@
+<html devsite>
+ <head>
+ <title>Carrier Identification</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ <body>
+ <!--
+ Copyright 2018 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.
+ -->
+
+ {% include "_versions.html" %}
+
+ <p>
+ Devices running Android {{ androidPVersionNumber }} and higher can
+ recognize subscription carrier information to provide an ID and a
+ carrier name. Android maintains a carrier ID database with matching
+ rules for each carrier and its unique carrier ID. AOSP includes the
+ content of the carrier ID database, in the file
+ <a
+ href="https://android.googlesource.com/platform/packages/providers/TelephonyProvider/+/master/assets/carrier_list.textpb"
+ class="external"><code>android/packages/providers/TelephonyProvider/assets/carrier_list.textpb</code></a>.
+ The unified database minimizes duplicate logic in apps that need to
+ identify carriers and limits the exposure of carrier-identifying
+ attributes.
+ </p>
+
+ <p>
+ To improve the coverage and accuracy of carrier identification, Android
+ supports out-of-band carrier ID table updates. Each update comes with
+ a version number and is published to AOSP.
+ </p>
+
+ <h2 id="implementation">Implementation</h2>
+
+ <p>
+ Users who want to implement out-of-band updates can download the
+ <a
+ href="https://android.googlesource.com/platform/packages/providers/TelephonyProvider/+/master/assets/carrier_list.pb"
+ class="external"><code>carrier_list.pb</code></a>
+ binary from AOSP. To view the readable format of the table, see
+ <a
+ href="https://android.googlesource.com/platform/packages/providers/TelephonyProvider/+/master/assets/carrier_list.textpb"
+ class="external"><code>carrier_list.txtpb</code></a>.
+ </p>
+
+ <p>
+ Place the updated carrier ID table in the
+ <code>/data/misc/carrierid/</code> data partition. If the updated
+ version is newer than the installed version, the device will persist
+ the table to the
+ <a
+ href="https://developer.android.com/reference/android/provider/Telephony.CarrierId"
+ class="external">carrier ID database</a>. The most recent
+ information from the carrier ID database will be picked up by the
+ public APIs
+ <a
+ href="https://developer.android.com/reference/android/telephony/TelephonyManager#getSimCarrierId()"
+ class="external"><code>getSimCarrierId()</code></a> and
+ <a
+ href="https://developer.android.com/reference/android/telephony/TelephonyManager#getSimCarrierIdName()"
+ class="external"><code>getSimCarrierIdName()</code></a>.
+ </p>
+
+ </body>
+</html>
diff --git a/en/devices/tech/config/filesystem.html b/en/devices/tech/config/filesystem.html
index d6569c3..2487645 100644
--- a/en/devices/tech/config/filesystem.html
+++ b/en/devices/tech/config/filesystem.html
@@ -1,10 +1,11 @@
<html devsite>
<head>
- <title>File DAC Configuration</title>
+ <title>Configuring Discretionary Access Control (DAC)</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
+ {% include "_versions.html" %}
<!--
Copyright 2017 The Android Open Source Project
@@ -21,117 +22,152 @@
limitations under the License.
-->
-<p>When adding file system objects and services to the build, such items
-frequently need separate unique IDs, known as Android IDs (AIDs). Currently,
-many resources such as files and services use core, Android-defined AIDs
-unnecessarily; in many cases you can use OEM-defined AIDs instead.</p>
+<p>
+ Filesystem objects and services added to the build frequently need separate,
+ unique IDs, known as Android IDs (AIDs). Currently, many resources such as
+ files and services use core (Android-defined) AIDs unnecessarily; in many
+ cases you can use OEM (OEM-defined) AIDs instead.
+</p>
-<p>In earlier versions of Android, extending the AIDs mechanism used a
-device-specific <code>android_filesystem_config.h</code> file to specify the
-filesystem capabilities and/or custom OEM AIDs. However, this system was
-unintuitive as it did not support using nice names for OEM AIDs, requiring you
-to specify the raw numeric for user and group fields without a way to associate
-a friendly name with the numeric AID.</p>
+<p>
+ Earlier versions of Android (Android 7.x and lower) extended the AIDs
+ mechanism using a device-specific <code>android_filesystem_config.h</code>
+ file to specify filesystem capabilities and/or custom OEM AIDs. However, this
+ system was unintuitive as it did not support using nice names for OEM AIDs,
+ requiring you to specify the raw numeric for user and group fields without a
+ way to associate a friendly name with the numeric AID.
+</p>
-<p>Android 8.0 and higher includes a new AIDs mechanism for extending filesystem
-capabilities. This new method has support for the following:</p>
+<p>
+ Newer versions of Android (Android 8.0 and higher) support a new method for
+ extending filesystem capabilities, This new method has support for the
+ following:
+</p>
+
<ul>
-<li>Multiple source locations for configuration files (enables extensible build
-configurations).</li>
-<li>Build-time sanity checking of OEM AID values.</li>
-<li>Generation of a custom OEM AID header that can be used in source files as
-needed.</li>
-<li>Association of a friendly name with the actual OEM AID value. Supports
-non-numeric string arguments for user and group, i.e. "foo" instead of
-"2901".</li>
+ <li>Multiple source locations for configuration files (enables extensible
+ build configurations).</li>
+ <li>Build-time sanity checking of OEM AID values.</li>
+ <li>Generation of a custom OEM AID header that can be used in source files as
+ needed.</li>
+ <li>Association of a friendly name with the actual OEM AID value. Supports
+ non-numeric string arguments for user and group, i.e. "foo" instead of
+ "2901".</li>
</ul>
-<p>Additional improvements include the removal of the <code>android_ids[]</code>
-array from <code>system/core/include/private/android_filesystem_config.h</code>.
-This array now exists in Bionic as a fully private generated array, with
-accessors via <code>getpwnam()</code> and <code>getgrnam()</code>. (This has the
-side effect of producing stable binaries as core AIDs are modified.) For tooling
-and a README file with more details, refer to
-<code>build/make/tools/fs_config</code>.</p>
+<p>
+ Additional improvements include the removal of the <code>android_ids[]</code>
+ array from
+ <code>system/core/include/private/android_filesystem_config.h</code>. This
+ array now exists in Bionic as a fully private generated array, with
+ accessors via <code>getpwnam()</code> and <code>getgrnam()</code>. (This has
+ the side effect of producing stable binaries as core AIDs are modified.) For
+ tooling and a README file with more details, refer to
+ <code>build/make/tools/fs_config</code>.
+</p>
-<aside class="note"><strong>Note:</strong> While you can still use the
-<a href="#older">filesystem override method from previous Android releases</a>,
-you cannot use it simultaneously with the new AIDs mechanism. Using the new
-mechanism whenever possible is recommended.</aside>
+<aside class="note">
+ <strong>Note:</strong> While you can still use the <a href="#older">filesystem
+ override method from previous Android releases</a>, you cannot use it
+ simultaneously with the new AIDs mechanism. Using the new mechanism whenever
+ possible is recommended.
+</aside>
-<h2 id="adding-android-ids-aids">Adding Android IDs (AIDs)</h2>
-<p>Android 8.0 removes the <code>android_ids[]</code> array from the Android
-Open Source Project (AOSP). All AID-friendly names are instead generated from
-the <code>system/core/include/private/android_filesystem_config.h</code> header
-file when generating the Bionic <code>android_ids[]</code> array. Any
-<code>define</code> matching <code>AID_*</code> is picked up by the tooling and
-<strong>*</strong> becomes the lowercase name.</p>
+<h2 id="adding-android-aids">Adding Android IDs (AIDs)</h2>
-<p>For example, in <code>private/android_filesystem_config.h</code>:</p>
+<p>
+ Android 8.0 removed the <code>android_ids[]</code> array from the Android
+ Open Source Project (AOSP). All AID-friendly names are instead generated from
+ the <code>system/core/include/private/android_filesystem_config.h</code>
+ header file when generating the Bionic <code>android_ids[]</code> array. Any
+ <code>define</code> matching <code>AID_*</code> is picked up by the tooling
+ and <strong>*</strong> becomes the lowercase name.
+</p>
+
+<p>
+ For example, in <code>private/android_filesystem_config.h</code>:
+</p>
<pre class="prettyprint">#define AID_SYSTEM 1000</pre>
-<p>Becomes:</p>
+<p>
+ Becomes:
+</p>
+
<ul>
-<li>Friendly name: system</li>
-<li>uid: 1000</li>
-<li>gid: 1000</li>
+ <li>Friendly name: system</li>
+ <li>uid: 1000</li>
+ <li>gid: 1000</li>
</ul>
-<p>To add a new AOSP core AID, simply add the <code>#define</code> to the
-<code>android_filesystem_config.h</code> header file. The AID will be generated
-at build and made available to interfaces that use user and group arguments. The
-tooling validates the new AID is not within the APP or OEM ranges; it also
-respects changes to those ranges and should automatically reconfigure on changes
-or new OEM-reserved ranges.</p>
+<p>
+ To add a new AOSP core AID, simply add the <code>#define</code> to the
+ <code>android_filesystem_config.h</code> header file. The AID will be
+ generated at build and made available to interfaces that use user and group
+ arguments. The tooling validates the new AID is not within the APP or OEM
+ ranges; it also respects changes to those ranges and should automatically
+ reconfigure on changes or new OEM-reserved ranges.
+</p>
<h2 id="configuring-aids">Configuring AIDs</h2>
+
<p>
-To enable the new AIDs mechanism, set <code>TARGET_FS_CONFIG_GEN</code> in the
-<code>BoardConfig.mk</code> file. This variable holds a list of configuration
-files, enabling you to append files as needed.</p>
+ To enable the new AIDs mechanism, set <code>TARGET_FS_CONFIG_GEN</code> in the
+ <code>BoardConfig.mk</code> file. This variable holds a list of configuration
+ files, enabling you to append files as needed.
+</p>
-<aside class="caution"><strong>Caution:</strong> Don't use
-<code>TARGET_FS_CONFIG_GEN</code> with the
-older <code>TARGET_ANDROID_FILESYSTEM_CONFIG_H</code> method from older Android
-releases! You will get an error.</aside>
+<aside class="caution">
+ <strong>Caution:</strong> Don't use <code>TARGET_FS_CONFIG_GEN</code> with the
+ older <code>TARGET_ANDROID_FILESYSTEM_CONFIG_H</code> method from older
+ Android releases! You will get an error.
+</aside>
-<p>By convention, configuration files use the name <code>config.fs</code>, but
-in practice you can use any name. <code>config.fs</code> files are in the
-<a href="https://docs.python.org/2/library/configparser.html" class="external">Python
-ConfigParser ini format</a> and include a caps section (for configuring file
-system capabilities) and an AIDs section (for configuring OEM-specific AIDs).
+<p>
+ By convention, configuration files use the name <code>config.fs</code>, but in
+ practice you can use any name. <code>config.fs</code> files are in the
+ <a href="https://docs.python.org/2/library/configparser.html" class="external">Python
+ ConfigParser ini format</a> and include a caps section (for configuring file
+ system capabilities) and an AIDs section (for configuring OEM AIDs).
</p>
<h3 id="configuring-the-caps-section">Configuring the caps section</h3>
-<aside class="note"><strong>Note:</strong>
-<a href="/devices/tech/config/ambient">Ambient capabilities</a> are the preferred
-mechanism for setting capabilities for services launched by init (this method
-keeps all aspects for the service configuration in a single <code>.rc</code>
-file). We recommend using ambient capabilities for these services instead of
-configuring file system capabilities using the caps section in
-<code>config.fs</code> files. When setting capabilities for services
-<strong>not launched by init</strong>, continue to configure file system
-capabilities using <code>fs_config.c</code>.</aside>
+<aside class="note">
+ <strong>Note:</strong> <a href="/devices/tech/config/ambient">Ambient
+ capabilities</a> are the preferred mechanism for setting capabilities for
+ services launched by <code>init</code> (this method keeps all aspects for the
+ service configuration in a single <code>.rc</code> file). We recommend using
+ ambient capabilities for these services instead of configuring file system
+ capabilities using the caps section in <code>config.fs</code> files. When
+ setting capabilities for services <strong>not launched by
+ <code>init</code></strong>, continue to configure file system capabilities
+ using <code>fs_config.c</code>.
+</aside>
+<p>
+ The caps section supports setting
+ <a href="http://man7.org/linux/man-pages/man7/capabilities.7.html" class="external">file
+ system capabilities</a> on filesystem objects within the build (the filesystem
+ itself must also support this functionality).
+</p>
-<p>The caps section supports setting
-<a href="http://man7.org/linux/man-pages/man7/capabilities.7.html" class="external">file
-system capabilities</a> on filesystem objects within the build (the filesystem
-itself must also support this functionality).</p>
+<p>
+ Because running a stable service as root in Android causes a
+ <a href="/compatibility/cts/index.html">Compatibility Test Suite (CTS)</a>
+ failure, previous requirements for retaining a capability while running a
+ process or service involved setting up capabilities then using
+ <code>setuid</code>/<code>setgid</code> to a proper AID to run. With caps, you
+ can skip these requirements and have the kernel do it for you. When control is
+ handed to <code>main()</code>, your process already has the capabilities it
+ needs so your service can use a non-root user and group (this is the preferred
+ way for starting privileged services).
+</p>
-<p>Because running a stable service as root in Android causes a
-<a href="/compatibility/cts/index.html">Compatibility Test Suite (CTS)</a>
-failure, previous requirements for retaining a capability while running a
-process or service involved setting up capabilities then using
-<code>setuid</code>/<code>setgid</code> to a proper AID to run. With caps, you
-can skip these requirements and have the kernel do it for you. When control is
-handed to <code>main()</code>, your process already has the capabilities it
-needs so your service can use a non-root user and group (this is the preferred
-way for starting privileged services).</p>
+<p>
+ The caps section uses the following syntax:
+</p>
-<p>The caps section uses the following syntax:</p>
<table>
<tr>
<th>Section</th>
@@ -144,9 +180,9 @@
<td>The filesystem path to configure. A path ending in / is considered a dir,
else it's a file.
<br><br>It is an error to specify multiple sections with the same
- <code>[path]</code> in different files. In Python versions <= 3.2, the same
- file may contain sections that override the previous section; in Python 3.2,
- it's set to strict mode.</td>
+ <code>[path]</code> in different files. In Python versions <= 3.2, the
+ same file may contain sections that override the previous section; in Python
+ 3.2, it's set to strict mode.</td>
</tr>
<tr>
<td><code>mode</code></td>
@@ -184,11 +220,16 @@
</tr>
</table>
-<p>For a usage example, see <a href="#using-file-system-capabilities">Using file
-system capabilities</a>.</p>
+<p>
+ For a usage example, see <a href="#using-file-system-capabilities">Using file
+ system capabilities</a>.
+</p>
<h3 id="configuring-the-aid-section">Configuring the AID section</h3>
-<p>The AID section contains OEM-specific AIDs and uses the following syntax:</p>
+
+<p>
+ The AID section contains OEM AIDs and uses the following syntax:
+</p>
<table>
<tr>
@@ -223,115 +264,178 @@
</tr>
</table>
-<p>For usage examples, see <a href="#defining-an-oem-specific-aid">Defining an
-OEM-specific AID</a> and <a href="#using-an-oem-specific-aid">Using an
-OEM-specific AID</a>.</p>
+<p>
+ For usage examples, see <a href="#defining-oem-aid-name">Defining an OEM
+ AID</a> and <a href="#using-oem-aids">Using an OEM AID</a>.
+</p>
<h2 id="usage-examples">Usage examples</h2>
-<p>The following examples detail how to define and use an OEM-specific AID and
-how to enable filesystem capabilities.</p>
-<h3 id="defining-an-oem-specific-aid">Defining an OEM-specific AID</h3>
-<p>To define an OEM-specific AID, create a <code>config.fs</code> file and set
-the AID value. For example, in <code>device/x/y/config.fs</code>, set the
-following:</p>
+<p>
+ The following examples detail how to define and use an OEM AID and how to
+ enable filesystem capabilities. OEM AID names
+ (<strong>[AID_</strong><em>name<strong></em>]</strong>) must begin with the
+ value "<strong>vendor_</strong>" to ensure they do not conflict with future
+ AOSP names.
+</p>
-<pre class="prettyprint">
-[AID_FOO]
+<h3 id="defining-oem-aid-name">Defining OEM AID names</h2>
+
+<p>
+ To define an OEM AID, create a <code>config.fs</code> file and set
+ the AID value. For example, in <code>device/x/y/config.fs</code>, set the
+ following:
+</p>
+
+<pre>
+[AID_VENDOR_FOO]
value: 2900
</pre>
-<p>After creating the file, set the <code>TARGET_FS_CONFIG_GEN</code> variable
-and point to it in <code>BoardConfig.mk</code>. For example, in
-<code>device/x/y/BoardConfig.mk</code>, set the following:</p>
+<p>
+ After creating the file, set the <code>TARGET_FS_CONFIG_GEN</code> variable
+ and point to it in <code>BoardConfig.mk</code>. For example, in
+ <code>device/x/y/BoardConfig.mk</code>, set the following:
+</p>
<pre class="prettyprint">TARGET_FS_CONFIG_GEN += device/x/y/config.fs</pre>
-<p>Your custom AID can now be consumed by the system at large on a new build.
+<p>
+ Your custom AID can now be consumed by the system at large on a new build.
</p>
-<h3 id="using-an-oem-specific-aid">Using an OEM-specific AID</h3>
-<p>To access the <code>#define</code> value of your AID via C or C++ code, use
-the autogenerated header file by adding to your module's <code>Android.mk</code>
-and including the empty faux library. For example, in <code>Android.mk</code>,
-add the following:</p>
+<h2 id="using-oem-aids">Using OEM AIDs</h2>
-<pre class="prettyprint">LOCAL_HEADER_LIBRARIES := oemaids_headers</pre>
+<p>
+ To use an OEM AID, in your C code, add <code>#include
+ "generated_oem_aid.h"</code> and start using the declared identifiers. For
+ example, in <code>my_file.c</code>, add the following:
+</p>
-<p>In your C code, <code>#include "generated_oem_aid.h"</code> and start using
-the declared identifiers. For example, in <code>my_file.c</code>, add the
-following: </p>
-
-<pre class="prettyprint">
+<pre>
#include "generated_oem_aid.h"
-
…
-If (ipc->uid == AID_FOO) {
+If (ipc->uid == AID_VENDOR_FOO) {
// Do something
...
</pre>
-<p>In Android 8.0, you must continue to use <code>oem_####</code> with
-<code>getpwnam</code> and similar functions, as well in places that handle
-lookups via <code>getpwnam</code> (such as init scripts). For example, in
-<code>some/init.rc</code>, use the following:</p>
+<h3 id="using-friendly-names">Using friendly names</h3>
-<pre class="prettyprint">
-service foo /vendor/bin/foo_service
- user: oem_2900
- group: oem_2900
+<p>
+ In Android {{ androidPVersionNumber }}, you can use the friendly name for any
+ interface that supports AID names. For example:
+</p>
+
+<ul>
+ <li>In a <code>chown</code> command in <code>some/init.rc</code>:
+<pre>
+chown vendor_foo /vendor/some/vendor_foo/file
</pre>
+ </li>
+ <li>In a <code>service</code> in <code>some/init.rc</code>:
+
+<pre>
+service vendor_foo /vendor/bin/foo_service
+ user vendor_foo
+ group vendor_foo
+</pre>
+ </li>
+</ul>
+
+<p>
+ Because the internal mapping from friendly name to uid is performed by
+ <code>/vendor/etc/passwd</code> and <code>/vendor/etc/group</code>, the vendor
+ partition must be mounted.
+</p>
+
+<h2 id="associating-friendly-names">Associating friendly names</h2>
+
+<p>
+ Android {{ androidPVersionNumber }} includes support for associating a
+ friendly name with the actual OEM AID value. You can use non-numeric string
+ arguments for user and group, i.e. "<strong>vendor_</strong>foo" instead of
+ "2901".
+</p>
+
+<h2 id="converting-aid-to-friendly">Converting from AID to friendly names</h2>
+
+<p>
+ For
+ <a href="#using-oem-aid">OEM AIDs</a>, Android 8.x required the use of
+ <code>oem_####</code> with <code>getpwnam</code> and similar functions, as
+ well in places that handle lookups via <code>getpwnam</code> (such as
+ <code>init</code> scripts). In Android {{ androidPVersionNumber }}, you can
+ use the <code>getpwnam</code> and <code>getgrnam</code> friends in Bionic for
+ converting from Android IDs (AIDs) to friendly names and vice versa.
+</p>
<h3 id="using-file-system-capabilities">Using file system capabilities</h3>
-<p>To enable filesystem capabilities, create a caps section in the
-<code>config.fs</code> file. For example, in <code>device/x/y/config.fs</code>,
-add the following section:</p>
-<pre class="prettyprint">
+<p>
+ To enable filesystem capabilities, create a caps section in the
+ <code>config.fs</code> file. For example, in
+ <code>device/x/y/config.fs</code>, add the following section:
+</p>
+
+<pre>
[system/bin/foo_service]
mode: 0555
-user: AID_FOO
+user: AID_VENDOR_FOO
group: AID_SYSTEM
caps: SYS_ADMIN | SYS_NICE
</pre>
-<aside class="note"><strong>Note:</strong> The nice names <code>foo</code> and
-<code>system</code> could be used here as well.</aside>
+<aside class="note">
+ <strong>Note:</strong> The nice names <code><strong>vendor_</strong>foo</code>
+ and <code>system</code> could be used here as well.
+</aside>
-<p>After creating the file, set the <code>TARGET_FS_CONFIG_GEN</code> to point
-to it in <code>BoardConfig.mk</code>. For example, in
-<code>device/x/y/BoardConfig.mk</code>, set the following:</p>
+<p>
+ After creating the file, set the <code>TARGET_FS_CONFIG_GEN</code> to point to
+ that file in <code>BoardConfig.mk</code>. For example, in
+ <code>device/x/y/BoardConfig.mk</code>, set the following:
+</p>
-<pre class="prettyprint">TARGET_FS_CONFIG_GEN += device/x/y/config.fs</pre>
+<pre>
+TARGET_FS_CONFIG_GEN += device/x/y/config.fs
+</pre>
-<p>When service <code>foo</code> is executed, it starts with capabilities
-<code>CAP_SYS_ADMIN</code> and <code>CAP_SYS_NICE</code> without
-<code>setuid</code> and <code>setgid</code> calls. In addition, the
-<code>foo</code> service's SELinux policy no longer needs <code>setuid</code>
-and <code>setgid</code>, so these capabilities can be removed from the SELinux
-policy for <code>foo</code>.</p>
+<p>
+ When service <code><strong>vendor_</strong>foo</code> is executed, it starts
+ with capabilities <code>CAP_SYS_ADMIN</code> and <code>CAP_SYS_NICE</code>
+ without <code>setuid</code> and <code>setgid</code> calls. In addition, the
+ <code><strong>vendor_</strong>foo</code> service's SELinux policy no longer
+ needs capability <code>setuid</code> and <code>setgid</code> and can be
+ deleted.
+</p>
<h2 id="older">Configuring overrides (Android 6.x-7.x)</h2>
-<p>Android 6.0 relocated <code>fs_config</code> and associated structure
-definitions
-(<code>system/core/include/private/android_filesystem_config.h</code>) to
-<code>system/core/libcutils/fs_config.c</code> where they could be updated or
-overridden by binary files installed in <code>/system/etc/fs_config_dirs</code>
-and <code>/system/etc/fs_config_files</code>. Using separate matching and
-parsing rules for directories and files (which could use additional glob
-expressions) enabled Android to handle directories and files in two different
-tables. Structure definitions in <code>system/core/libcutils/fs_config.c</code>
-not only allowed runtime reading of directories and files, but the host could
-use the same files during build time to construct filesystem images as
-<code>${OUT}/system/etc/fs_config_dirs</code> and
-<code>${OUT}/system/etc/fs_config_files</code>.</p>
+<p>
+ Android 6.0 relocated <code>fs_config</code> and associated structure
+ definitions
+ (<code>system/core/include/private/android_filesystem_config.h</code>) to
+ <code>system/core/libcutils/fs_config.c</code> where they could be updated or
+ overridden by binary files installed in
+ <code>/system/etc/fs_config_dirs</code> and
+ <code>/system/etc/fs_config_files</code>. Using separate matching and parsing
+ rules for directories and files (which could use additional glob expressions)
+ enabled Android to handle directories and files in two different tables.
+ Structure definitions in <code>system/core/libcutils/fs_config.c</code> not
+ only allowed runtime reading of directories and files, but the host could use
+ the same files during build time to construct filesystem images as
+ <code>${OUT}/system/etc/fs_config_dirs</code> and
+ <code>${OUT}/system/etc/fs_config_files</code>.
+</p>
-<p>While the override method of extending the filesystem has been superseded by
-the modular config system introduced in Android 8.0, you can still use the old
-method if desired. The following sections detail how to generate and include
-override files and configure the filesystem.</p>
+<p>
+ While the override method of extending the filesystem has been superseded by
+ the modular config system introduced in Android 8.0, you can still use the old
+ method if desired. The following sections detail how to generate and include
+ override files and configure the filesystem.
+</p>
<h3 id=older-generate>Generating override files</h3>
@@ -354,52 +458,64 @@
<li>For files, use <code>android<strong>_device</strong>_files[]</code>.</li>
</ul>
-<p>When not using <code>android_device_dirs[]</code> and
-<code>android_device_files[]</code>, you can define
-<code>NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_DIRS</code> and <code>NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_FILES</code> (see the
-<a href="#older-example">example</a> below). You can also specify the override file
-using <code>TARGET_ANDROID_FILESYSTEM_CONFIG_H</code> in the board
-configuration, with an enforced basename of
-<code>android_filesystem_config.h</code>.</p>
+<p>
+ When not using <code>android_device_dirs[]</code> and
+ <code>android_device_files[]</code>, you can define
+ <code>NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_DIRS</code> and
+ <code>NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_FILES</code> (see the
+ <a href="#older-example">example</a> below). You can also specify the override
+ file using <code>TARGET_ANDROID_FILESYSTEM_CONFIG_H</code> in the board
+ configuration, with an enforced basename of
+ <code>android_filesystem_config.h</code>.
+</p>
<h3 id=older-include>Including override files</h3>
-<p>To include files, ensure that <code>PRODUCT_PACKAGES</code> includes
-<code>fs_config_dirs</code> and/or <code>fs_config_files</code> so it can
-install them to <code>/system/etc/fs_config_dirs</code> and
-<code>/system/etc/fs_config_files</code>, respectively. The build system
-searches for custom <code>android_filesystem_config.h</code> in
-<code>$(TARGET_DEVICE_DIR)</code>, where <code>BoardConfig.mk</code> exists.
-If this file exists elsewhere, set board config variable
-<code>TARGET_ANDROID_FILESYSTEM_CONFIG_H</code> to point to that location.</p>
+
+<p>
+ To include files, ensure that <code>PRODUCT_PACKAGES</code> includes
+ <code>fs_config_dirs</code> and/or <code>fs_config_files</code> so it can
+ install them to <code>/system/etc/fs_config_dirs</code> and
+ <code>/system/etc/fs_config_files</code>, respectively. The build system
+ searches for custom <code>android_filesystem_config.h</code> in
+ <code>$(TARGET_DEVICE_DIR)</code>, where <code>BoardConfig.mk</code> exists.
+ If this file exists elsewhere, set board config variable
+ <code>TARGET_ANDROID_FILESYSTEM_CONFIG_H</code> to point to that location.
+</p>
<h3 id=older-configure>Configuring the filesystem</h3>
-<p>To configure the filesystem in Android 6.0 and higher:</p>
+
+<p>
+ To configure the filesystem in Android 6.0 and higher:
+</p>
<ol>
-<li>Create the <code>$(TARGET_DEVICE_DIR)/android_filesystem_config.h</code>
-file.</li>
-<li>Add the <code>fs_config_dirs</code> and/or <code>fs_config_files</code> to
-<code>PRODUCT_PACKAGES </code>in the board configuration file (e.g.,
-<code>$(TARGET_DEVICE_DIR)/device.mk</code>).</li>
+ <li>Create the <code>$(TARGET_DEVICE_DIR)/android_filesystem_config.h</code>
+ file.</li>
+ <li>Add the <code>fs_config_dirs</code> and/or <code>fs_config_files</code> to
+ <code>PRODUCT_PACKAGES </code>in the board configuration file (e.g.,
+ <code>$(TARGET_DEVICE_DIR)/device.mk</code>).</li>
</ol>
<h3 id=older-example>Override example</h3>
-<p>This example shows a patch for overriding the <code>system/bin/glgps</code>
-daemon to add wake lock support in the
-<code>device/<em>vendor</em>/<em>device</em></code> directory. Keep the
-following in mind:</p>
+<p>
+ This example shows a patch for overriding the <code>system/bin/glgps</code>
+ daemon to add wake lock support in the
+ <code>device/<em>vendor</em>/<em>device</em></code> directory. Keep the
+ following in mind:
+</p>
<ul>
-<li>Each structure entry is the mode, uid, gid, capabilities, and the name.
-<code>system/core/include/private/android_filesystem_config.h</code> is included
-automatically to provide the manifest #defines (<code>AID_ROOT</code>,
- <code>AID_SHELL</code>, <code>CAP_BLOCK_SUSPEND</code>).</li>
-<li>The <code>android_device_files[]</code> section includes an action to
-suppress access to <code>system/etc/fs_config_dirs</code> when unspecified,
-which serves as an additional DAC protection for lack of content for directory
-overrides. However, this is weak protection; if someone has control over
-<code>/system</code>, they can typically do anything they want.</li>
+ <li>Each structure entry is the mode, uid, gid, capabilities, and the name.
+ <code>system/core/include/private/android_filesystem_config.h</code> is
+ included automatically to provide the manifest #defines
+ (<code>AID_ROOT</code>, <code>AID_SHELL</code>,
+ <code>CAP_BLOCK_SUSPEND</code>).</li>
+ <li>The <code>android_device_files[]</code> section includes an action to
+ suppress access to <code>system/etc/fs_config_dirs</code> when unspecified,
+ which serves as an additional DAC protection for lack of content for directory
+ overrides. However, this is weak protection; if someone has control over
+ <code>/system</code>, they can typically do anything they want.</li>
</ul>
<pre class="devsite-click-to-copy">
@@ -465,25 +581,28 @@
</pre>
<h3 id=older-migration>Migrating filesystems from earlier releases</h3>
-<p>When migrating filesystems from Android 5.x and earlier, keep in mind that
-Android 6.x:</p>
+
+<p>
+ When migrating filesystems from Android 5.x and earlier, keep in mind that
+ Android 6.x:
+</p>
+
<ul>
-<li>Removes some includes, structures, and inline definitions.</li>
-<li>Requires a reference to <code>libcutils</code> instead of running directly
-from <code>system/core/include/private/android_filesystem_config.h</code>.
-Device manufacturer private executables that depend on
-<code>system/code/include/private_filesystem_config.h</code> for the file or
-directory structures or <code>fs_config</code> must add <code>libcutils</code>
-library dependencies.</li>
-<li>Requires device manufacturer private branch copies of the
-<code>system/core/include/private/android_filesystem_config.h</code> with extra
-content on existing targets to move to
-<code>device/<em>vendor</em>/<em>device</em>/android_filesystem_config.h</code>.
-</li>
-<li>As Android reserves the right to apply SELinux Mandatory Access Controls
-(MAC) to configuration files on the target system, implementations that include
-custom target executables using <code>fs_config()</code> must ensure access.
-</li>
+ <li>Removes some includes, structures, and inline definitions.</li>
+ <li>Requires a reference to <code>libcutils</code> instead of running directly
+ from <code>system/core/include/private/android_filesystem_config.h</code>.
+ Device manufacturer private executables that depend on
+ <code>system/code/include/private_filesystem_config.h</code> for the file or
+ directory structures or <code>fs_config</code> must add <code>libcutils</code>
+ library dependencies.</li>
+ <li>Requires device manufacturer private branch copies of the
+ <code>system/core/include/private/android_filesystem_config.h</code> with
+ extra content on existing targets to move to
+ <code>device/<em>vendor</em>/<em>device</em>/android_filesystem_config.h</code>.
+ </li>
+ <li>Reserves the right to apply SELinux Mandatory Access Controls (MAC) to
+ configuration files on the target system, implementations that include custom
+ target executables using <code>fs_config()</code> must ensure access.</li>
</ul>
</body>
diff --git a/en/devices/tech/connect/carrier-wifi.md b/en/devices/tech/connect/carrier-wifi.md
new file mode 100644
index 0000000..eabe25e
--- /dev/null
+++ b/en/devices/tech/connect/carrier-wifi.md
@@ -0,0 +1,106 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Carrier Wi-Fi
+
+Carrier Wi-Fi is a feature introduced in Android {{ androidPVersionNumber }}
+that allows devices to automatically connect to carrier-implemented Wi-Fi
+networks. In areas of high congestion or with minimal cell coverage such as a
+stadium or an underground train station, Carrier Wi-Fi can be used to improve
+users' connectivity experience and to offload traffic.
+
+## Implementation
+
+Device manufacturers and carriers must do the following to implement Carrier
+Wi-Fi.
+
+### Manufacturers
+
+In the carrier config manager, configure the following parameters for each
+carrier:
+
++ [KEY_CARRIER_WIFI_STRING_ARRAY](https://android.googlesource.com/platform/frameworks/base/+/master/telephony/java/android/telephony/CarrierConfigManager.java#1599):
+ Base64-encoded Wi-Fi SSID.
++ [IMSI_KEY_AVAILABILITY_INT](https://android.googlesource.com/platform/frameworks/base/+/master/telephony/java/android/telephony/CarrierConfigManager.java#1830):
+ Identifies whether the key used for IMSI encryption is available for WLAN or
+ EPDG, or both.
++ [IMSI_KEY_DOWNLOAD_URL_STRING](https://android.googlesource.com/platform/frameworks/base/+/master/telephony/java/android/telephony/CarrierConfigManager.java#1823):
+ URL from which the proto containing the public key of the carrier used for
+ IMSI encryption is downloaded.
+
+### Carriers
+
+To implement Carrier Wi-Fi, the carrier must support encrypted IMSI and provide
+a public key.
+
+#### Support encrypted IMSI
+
+Change the Wi-Fi network configuration to ensure that encrypted IMSI can be
+handled. The format for the identity used in EAP-SIM is:
+
+`Prefix | [IMSI || Encrypted IMSI] | @realm | {, Key Identifier AVP}`
+
+where "|" (single bar) denotes concatenation, "||" (double bar) denotes
+exclusive value, "{}" (curly brackets) denotes optional value, and realm is the
+3GPP network domain name derived from the given MNC/MCC according to the 3GGP
+spec (TS23.003).
+
+`Prefix` values include:
+
++ "`\0`": Encrypted Identity
++ "`0`": EAP-AKA Identity
++ "`1`": EAP-SIM Identity
++ "`6`": EAP-AKA' Identity
+
+The format for an `Encrypted IMSI` is:
+
+`Base64{RSA_Public_Key_Encryption{eapPrefix | IMSI}}`
+
+where "|" denotes concatenation.
+
+`eapPrefix` values include:
+
++ "`0`" - EAP-AKA Identity
++ "`1`" - EAP-SIM Identity
++ "`6`" - EAP-AKA' Identity
+
+#### Provide public key
+
+Provide a public URL that hosts the certificate of the carrier where:
+
+1. The public key (and expiration) can be extracted from the certificate
+1. The information is in JSON with the following format:
+
+```
+{
+"carrier-keys" : [ {
+ "key-identifier" : "CertificateSerialNumber=5xxe06d4",
+ "certificate" : "-----BEGIN CERTIFICATE-----\r\nTIIDRTCCAi2gAwIBAgIEVR4G1DANBgkqhkiG9w0BAQsFADBTMQswCQYDVQQGEwJVUzELMAkGA1UE\r\nCBMCTkExCzAJBgNVBAcTAk5BMQswCQYDVQQKEwJOQTELMAkGA1UECxMCTkExEDAOBgNVBAMTB1Rl\r\nc3RiT6N1/w==\r\n-----END CERTIFICATE-----",
+ "key-type" : "WLAN"
+} ]
+}
+```
+
+## Customization
+
+Carrier Wi-Fi is off by default unless configured in the carrier config manager
+for each carrier. If the feature is on, the device attempts to connect to a
+network automatically. A notification is sent on the first attempt.
diff --git a/en/devices/tech/connect/data-plans.md b/en/devices/tech/connect/data-plans.md
new file mode 100644
index 0000000..f61af73
--- /dev/null
+++ b/en/devices/tech/connect/data-plans.md
@@ -0,0 +1,116 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Implementing Data Plans
+
+Android {{ androidPVersionNumber }} lets carriers directly provide authoritative
+plan details to users in the Settings app to reduce user confusion and support
+calls. On devices running Android 4.0 and higher, users are able to manually
+configure their carrier-specific data plan details in the Settings app, for
+example, setting warnings and limits to manage their data usage.
+
+## Configuration by Carrier
+
+To configure data plans, carriers can add functionality to their existing
+Android apps using the
+[`SubscriptionPlan` APIs](https://developer.android.com/reference/android/telephony/SubscriptionPlan.Builder).
+The APIs are designed to support a wide range of data plan types, including both
+recurring and non-recurring plans, and plans that change over time.
+
+Here's an example of how to configure a common type of data plan that recurs
+monthly:
+
+```
+SubscriptionManager sm =
+ context.getSystemService(SubscriptionManager.class);
+sm.setSubscriptionPlans(subId, Lists.newArrayList(
+ SubscriptionPlan.Builder.createRecurringMonthly(
+ ZonedDateTime.parse("2016-12-03T10:00:00Z"))
+ .setTitle("G-Mobile")
+ .setDataLimit(4_000_000_000L,
+ SubscriptionPlan.LIMIT_BEHAVIOR_BILLED)
+ .setDataUsage(200_493_293L, dataUsageTimestamp)
+ .build()));
+```
+
+The device only lets an app configure data plans under one of these conditions:
+
++ The SIM card has explicitly defined an app that can manage it, as defined by
+ [`SubscriptionManager.canManageSubscription()`](https://developer.android.com/reference/android/telephony/SubscriptionManager.html#canManageSubscription\(android.telephony.SubscriptionInfo\)).
++ The carrier has pushed the
+ [`KEY_CONFIG_PLANS_PACKAGE_OVERRIDE_STRING`](https://developer.android.com/reference/android/telephony/CarrierConfigManager#KEY_CONFIG_PLANS_PACKAGE_OVERRIDE_STRING)
+ value via `CarrierConfigManager` to indicate which app can manage the
+ carrier's data plans.
++ The device has an app built into the system image that has the
+ `MANAGE_SUBSCRIPTION_PLANS` permission.
+
+The first two conditions enable the carrier app to be installed by the user,
+without requiring that it be pre-installed into the system image at the factory.
+The OS enforces (and the CDD requires) that all configured data plan details are
+protected and are only made available to the carrier app that originally
+provided the details to the OS.
+
+One suggested design is for a carrier app to use an idle maintenance service to
+update data plan details on a daily basis, but carriers are free to use a wide
+range of mechanisms, such as receiving data plan details via carrier-internal
+SMS messages. Idle maintenance services are best implemented with a
+`JobScheduler` job that uses
+[`setRequiresDeviceIdle()`](https://developer.android.com/reference/android/app/job/JobInfo.Builder#setRequiresDeviceIdle\(boolean\))
+and
+[`setRequiresCharging()`](https://developer.android.com/reference/android/app/job/JobInfo.Builder.html#setRequiresCharging\(boolean\)).
+
+## Usage by OS
+
+The OS uses the data plan details provided by the SubscriptionPlan APIs in the
+following ways:
+
++ The plan details are surfaced via the Settings app to display accurate data
+ usage to users and to provide
+ [direct deep links into the carrier app](https://developer.android.com/reference/android/telephony/SubscriptionManager.html#ACTION_MANAGE_SUBSCRIPTION_PLANS)
+ for upgrade/upsell opportunities.
++ The data usage warning and limit notification thresholds are automatically
+ configured based on the plan details; the warning is set to 90% of the
+ limit.
++ If the carrier temporarily indicates the network is
+ ["congested"](https://developer.android.com/reference/android/telephony/SubscriptionManager.html#setSubscriptionOverrideCongested\(int,%20boolean,%20long\)),
+ the OS delays JobScheduler jobs that can be time-shifted, reducing the load
+ on the carrier network.
++ If the carrier temporarily indicates the network is
+ ["unmetered"](https://developer.android.com/reference/android/telephony/SubscriptionManager#setSubscriptionOverrideUnmetered\(int,%20boolean,%20long\)),
+ the OS can report the cellular connection as "unmetered" until the carrier
+ clears the override, or until the timeout value (if provided) is reached.
++ By comparing the user's current data usage with the overall data limit, the
+ OS estimates the user's normal data usage at the end of the billing cycle
+ and conservatively allocates 10% of any surplus data to improve the user
+ experience, for example, by letting apps use multi-path data.
+
+## Customization and validation
+
+The Android Settings app displays all carrier-configured data plan details,
+ensuring that users see the most accurate status of their carrier relationship,
+and offering users a path into the carrier app to upgrade their plan. Device
+manufacturers choosing to customize the Settings app are recommended to continue
+surfacing these details.
+
+The `SubscriptionManager` APIs described above are tested by
+`android.telephony.cts.SubscriptionManagerTest`, which ensures that data plan
+details can be configured by carrier apps and that changes are propagated within
+the OS.
diff --git a/en/devices/tech/connect/esim-euicc-api.md b/en/devices/tech/connect/esim-euicc-api.md
new file mode 100644
index 0000000..607fef8
--- /dev/null
+++ b/en/devices/tech/connect/esim-euicc-api.md
@@ -0,0 +1,249 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# eUICC APIs
+
+In Android {{ androidPVersionNumber }}, profile management APIs (public and
+@SystemApi) are available through the class `EuiccManager`. eUICC communication
+APIs (@SystemApi only) are available through the class `EuiccCardManager`.
+
+## About eUICC
+
+Carriers can make carrier apps using EuiccManager to manage profiles, as shown
+in Figure 1. Carrier apps don't need to be system apps but need to have carrier
+privileges granted by eUICC profiles. An
+[LPA app](/devices/tech/connect/esim-overview#making_an_lpa_app) (LUI and LPA
+backend) needs to be a system app (i.e., included in the system image) to call
+the @SystemApi.
+
+
+
+**Figure 1.** Android phones with carrier app and OEM LPA
+
+Besides the logic of calling `EuiccCardManager` and talking to eUICC, LPA apps
+must implement the following:
+
++ SM-DP+ client talking to SM-DP+ server to authenticate and
+ download profiles
++ [Optional] SM-DS to get more potential downloadable profiles
++ Notification handling to send notifications to the server to
+ update the profile state
++ [Optional] Slots management including switching between eSIM and pSIM logic.
+ This is optional if the phone only has an eSIM chip.
++ eSIM OTA
+
+Although more than one LPA app can be present in an Android phone, only one LPA
+can be selected to be the actual working LPA based on the priority defined in
+the `AndroidManifest.xml` file of each app.
+
+## Using EuiccManager
+
+The LPA APIs are public through `EuiccManager` (under package
+`android.telephony.euicc`). A carrier app can get the instance of `EuiccManager`,
+and call the methods in `EuiccManager` to get the eUICC information and manage
+subscriptions (referred to as profiles in GSMA RSP documents) as
+SubscriptionInfo instances.
+
+To call public APIs including download, switch, and delete subscription
+operations, the carrier app must have the required privileges. Carrier
+privileges are added by the mobile carrier in the profile metadata. The eUICC
+API enforces the carrier privilege rules accordingly.
+
+The Android platform does not handle the profile policy rules. If a policy rule
+is declared in the profile metadata, the LPA can choose how to handle the
+profile download and installation procedure. For example, it is possible for a
+third-party OEM LPA to handle policy rules using a special error code (the error
+code is passed from the OEM LPA to the platform, then the platform passes the
+code to the OEM LUI).
+
+### APIs
+
+The following APIs can be found in the
+[`EuiccManager` reference documentation](https://developer.android.com/reference/android/telephony/euicc/EuiccManager)
+and
+[`EuiccManager.java`](https://android.googlesource.com/platform/frameworks/base/+/master/telephony/java/android/telephony/euicc/EuiccManager.java).
+
+#### Get instance (public)
+
+Gets the instance of `EuiccManager` through `Context#getSystemService`.
+
+```
+EuiccManager mgr = context.getSystemService(Context.EUICC_SERVICE);
+```
+
+#### Check enabled (public)
+
+Checks whether the embedded subscription is enabled. This should be checked
+before accessing LPA APIs.
+
+```
+boolean isEnabled = mgr.isEnabled();
+if (!isEnabled) {
+ return;
+}
+```
+
+#### Get EID (public)
+
+Gets the EID identifying the eUICC hardware. This may be null if the eUICC is
+not ready. The caller must have carrier privilege or the
+`READ_PRIVILEGED_PHONE_STATE` permission.
+
+```
+String eid = mgr.getEid();
+if (eid == null) {
+ // Handle null case.
+}
+```
+
+#### Get EuiccInfo (public)
+
+Gets information about the eUICC. This contains the OS version.
+
+```
+EuiccInfo info = mgr.getEuiccInfo();
+String osVer = info.getOsVersion();
+```
+
+#### Download subscription (public)
+
+Downloads the given subscription (referred to as "profile" in GSMA RSP
+documents). The subscription can be created from an activation code. For
+example, an activation code can be parsed from a QR code. Downloading a
+subscription is an asynchronous operation.
+
+The caller must either have the `WRITE_EMBEDDED_SUBSCRIPTIONS` permission or
+have carrier privileges for the target subscription.
+
+```
+// Register receiver.
+String action = "download_subscription";
+BroadcastReceiver receiver =
+ new BroadcastReceiver() {
+ @Override
+ public void onReceive(Context context, Intent intent) {
+ if (!action.equals(intent.getAction())) {
+ return;
+ }
+ resultCode = getResultCode();
+ detailedCode = intent.getIntExtra(
+ EuiccManager.EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE,
+ 0 /* defaultValue*/);
+ resultIntent = intent;
+ }
+ };
+context.registerReceiver(
+ receiver,
+ new IntentFilter(action),
+ "example.broadcast.permission" /* broadcastPermission*/, null /* handler */);
+
+// Download subscription asynchronously.
+DownloadableSubscription sub =
+ DownloadableSubscription.forActivationCode(code /* encodedActivationCode*/);
+Intent intent = new Intent(action);
+PendingIntent callbackIntent = PendingIntent.getBroadcast(
+ getContext(), 0 /* requestCode */, intent, PendingIntent.FLAG_UPDATE_CURRENT);
+mgr.downloadSubscription(sub, true /* switchAfterDownload */, callbackIntent);
+```
+
+#### Switch subscription (public)
+
+Switches to (enables) the given subscription. The caller must either have
+`WRITE_EMBEDDED_SUBSCRIPTIONS` or have carrier privileges for the current
+enabled subscription and the target subscription.
+
+```
+// Register receiver.
+String action = "switch_to_subscription";
+BroadcastReceiver receiver =
+ new BroadcastReceiver() {
+ @Override
+ public void onReceive(Context context, Intent intent) {
+ if (!action.equals(intent.getAction())) {
+ return;
+ }
+ resultCode = getResultCode();
+ detailedCode = intent.getIntExtra(
+ EuiccManager.EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE, 0 /* defaultValue*/);
+ resultIntent = intent;
+ }
+ };
+context.registerReceiver(receiver, new IntentFilter(action),
+ "example.broadcast.permission" /* broadcastPermission*/, null /* handler */);
+
+// Switch to a subscription asynchronously.
+Intent intent = new Intent(action);
+PendingIntent callbackIntent = PendingIntent.getBroadcast(
+ getContext(), 0 /* requestCode */, intent, PendingIntent.FLAG_UPDATE_CURRENT);
+mgr.switchToSubscription(1 /* subscriptionId */, callbackIntent);
+```
+
+#### Delete subscription (public)
+
+Deletes a subscription with a subscription ID. If the subscription is currently
+active, it is first disabled. The caller must have either
+`WRITE_EMBEDDED_SUBSCRIPTIONS` or carrier privileges for the target
+subscription.
+
+```
+// Register receiver.
+String action = "delete_subscription";
+BroadcastReceiver receiver =
+ new BroadcastReceiver() {
+ @Override
+ public void onReceive(Context context, Intent intent) {
+ if (!action.equals(intent.getAction())) {
+ return;
+ }
+ resultCode = getResultCode();
+ detailedCode = intent.getIntExtra(
+ EuiccManager.EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE,
+ 0 /* defaultValue*/);
+ resultIntent = intent;
+ }
+ };
+context.registerReceiver(receiver, new IntentFilter(action),
+ "example.broadcast.permission" /* broadcastPermission*/,
+ null /* handler */);
+
+// Delete a subscription asynchronously.
+Intent intent = new Intent(action);
+PendingIntent callbackIntent = PendingIntent.getBroadcast(
+ getContext(), 0 /* requestCode */, intent, PendingIntent.FLAG_UPDATE_CURRENT);
+mgr.deleteSubscription(1 /* subscriptionId */, callbackIntent);
+```
+
+#### Start resolution activity (public)
+
+Starts an activity to resolve a user-resolvable error. If an operation returns
+`EuiccManager#EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR`, this method can be
+called to prompt the user to resolve the issue. This method can only be called
+once for a particular error.
+
+```
+...
+mgr.startResolutionActivity(getActivity(), 0 /* requestCode */, resultIntent, callbackIntent);
+```
+
+### Constants
+
+To see a list of the the `public` constants in `EuiccManager`, see
+[Constants](https://developer.android.com/reference/android/telephony/euicc/EuiccManager#constants).
diff --git a/en/devices/tech/connect/esim-modem-requirements.md b/en/devices/tech/connect/esim-modem-requirements.md
new file mode 100644
index 0000000..cd9f7d7
--- /dev/null
+++ b/en/devices/tech/connect/esim-modem-requirements.md
@@ -0,0 +1,103 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Modem Requirements for eSIM Support
+
+This page summarizes the required modem features for supporting an eSIM chip or
+removable eSIM 4FF card.
+
+## General requirements
+
+These are the modem requirements for general eSIM support. The LPA needs the
+modem to support all of these requirements to function properly.
+
+### Handle the default boot profile correctly
+
+When there is no operational or test profile enabled on eSIM, the default boot
+profile is enabled. The modem shall recognize the eSIM with the default boot
+profile enabled as a valid SIM. The modem shall report card as valid to upper
+layers and shall not turn off the SIM power.
+
+### Send terminal capabilities correctly
+
+When opening a logical channel to ISD-R, the modem shall send correct terminal
+capabilities to the eSIM. The terminal capability must encode support for eUICC
+capabilities: "Local Profile Management" and "Profile Download" per ETSI TS 102
+221.
+
+### Implement setSimPower API in Radio HAL v1.1
+
+The modem shall support the
+[setSimPower](https://source.android.com/reference/hidl/android/hardware/radio/1.1/IRadio#setsimcardpower_1_1)
+API.
+
+### Implement getSimSlotsStatus API in IRadioConfig HAL v1.0
+
+The modem shall support the
+[getSimSlotsStatus](https://android.googlesource.com/platform/hardware/interfaces/+/master/radio/config/1.0/IRadioConfig.hal#51)
+API, which indicates whether a slot contains an eSIM.
+
+### Implement getIccCardStatus API in IRadio HAL v1.2
+
+The modem shall provide the ATR and slot ID of the card status as specified in
+the
+[getIccCardStatus](https://source.android.com/reference/hidl/android/hardware/radio/1.0/IRadio#getIccCardStatus)
+API. This API was first introduced in v1.0 and, in v1.2,
+[CardStatus](https://android.googlesource.com/platform/hardware/interfaces/+/master/radio/1.2/types.hal#341)
+was changed to include
+[ATR](https://android.googlesource.com/platform/hardware/interfaces/+/master/radio/1.2/types.hal#351).
+
+### (Optional) Support eSIM OS OTA
+
+As the eSIM OS OTA is not standardized, this depends on the vendor providing
+eSIM OS. The modem shall support all requirements for eSIM OS OTA, for example
+switching to passthrough mode and keeping the eSIM powered on during the OTA
+procedure.
+
+## Logging requirements
+
+These are general modem logging requirements to properly debug eSIM issues.
+
+### Provide PC based tools to capture detailed modem logs
+
+Logging shall capture all the OTA packets for Cellular RATs (4G, 3G, 2G) and IMS
+(SIP, RTP, RTCP, XCAP). ESP protected SIP packets shall be logged without ESP.
+OTA parser shall be compliant to 3GPP specs.
+
+Logging shall support capture IP packets on all network interfaces.
+
+Logging shall support capturing debug logs and protocol layer information
+including protocol layer states, radio power measurements, network cell
+information, packet TX/RX statistics, inter-layer messaging, inter-processor
+communication, SIM functionality & APDU logging, and RIL logging.
+
+### On-device logging
+
+Device software shall support an on-device modem log capturing mechanism.
+
+### Log config support
+
+Device software shall support different modem logging configurations (level,
+modules). These configurations shall be supported for both on-device logging and
+PC-tool-based logging.
+
+### Android bug report
+
+Bug reports shall contain modem logs, vendor RIL logs, panic signature logs, and
+Android logs.
diff --git a/en/devices/tech/connect/esim-overview.md b/en/devices/tech/connect/esim-overview.md
new file mode 100644
index 0000000..fb9f745
--- /dev/null
+++ b/en/devices/tech/connect/esim-overview.md
@@ -0,0 +1,511 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Implementing eSIM
+
+Embedded SIM (eSIM, or eUICC) is the latest technology to allow mobile users to
+download a carrier profile and activate a carrier's service without having a
+physical SIM card. It is a global specification driven by the GSMA that enables
+remote SIM provisioning of any mobile device. Starting with Android
+{{ androidPVersionNumber }}, the Android framework provides standard APIs for
+accessing eSIM and managing subscription profiles on the eSIM. These _eUICC
+APIs_ enable third parties to develop their own carrier apps and Local Profile
+Assistants (LPAs) on eSIM-enabled Android devices.
+
+The LPA is a standalone, system application that should be included in the
+Android build image. Management of the profiles on the eSIM is generally done by
+the LPA, as it serves as a bridge between the SM-DP+ (remote service that
+prepares, stores, and delivers profile packages to devices) and the eUICC chip.
+The LPA APK can optionally include a UI component, called the LPA UI or LUI, to
+provide a central place for the end user to manage all embedded subscription
+profiles. The Android framework automatically discovers and connects to the best
+available LPA, and routes all the eUICC operations through an LPA instance.
+
+
+
+**Figure 1.** Simplified Remote SIM Provisioning (RSP) architecture
+
+Mobile network operators interested in creating a _carrier app_ should look at
+the APIs in
+[EuiccManager](https://android.googlesource.com/platform/frameworks/base/+/master/telephony/java/android/telephony/euicc/EuiccManager.java),
+which provides high-level profile management operations such as
+`downloadSubscription()`, `switchToSubscription()`, and
+`deleteSubscription()`.
+
+If you are a device OEM interested in creating your own LPA system app, you must
+extend
+[EuiccService](https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/service/euicc/EuiccService.java)
+for the Android framework to connect to your LPA services. In addition, you
+should use the APIs in
+[EuiccCardManager](https://android.googlesource.com/platform/frameworks/base/+/master/telephony/java/android/telephony/euicc/EuiccCardManager.java),
+which provides ES10x functions based on GSMA Remote SIM Provisioning (RSP) v2.0.
+These functions are used to issue commands to the eUICC chip, such as
+`prepareDownload()`, `loadBoundProfilePackage()`, `retrieveNotificationList()`,
+and `resetMemory()`.
+
+The APIs in
+[EuiccManager](https://android.googlesource.com/platform/frameworks/base/+/master/telephony/java/android/telephony/euicc/EuiccManager.java)
+require a properly implemented LPA app to function and the caller of
+[EuiccCardManager](https://android.googlesource.com/platform/frameworks/base/+/master/telephony/java/android/telephony/euicc/EuiccCardManager.java)
+APIs must be an LPA. This is enforced by the Android framework.
+
+## Making a carrier app
+
+The eUICC APIs in Android {{ androidPVersionNumber }} make it possible for
+mobile network operators to create carrier-branded applications to manage their
+profiles directly. This includes downloading and deleting subscription profiles
+owned by the carrier, as well as switching to a profile owned by a carrier.
+
+### EuiccManager
+
+`EuiccManager` is the main entry point for applications to interact with the
+LPA. This includes carrier apps that download, delete, and switch to
+subscriptions owned by the carrier. This also includes the LUI system app, which
+provides a central location/UI for managing _all_ embedded subscriptions, and
+can be a separate app from the one that provides the `EuiccService`.
+
+To use the public APIs, a carrier app must first obtain the instance of
+`EuiccManager` through `Context#getSystemService`:
+
+```
+EuiccManager mgr = context.getSystemService(Context.EUICC_SERVICE);
+```
+
+You should check whether eSIM is supported on the device before performing any
+eSIM operations. `EuiccManager#isEnabled()` generally returns true if the
+android.hardware.telephony.euicc feature is defined and an LPA package is
+present.
+
+```
+boolean isEnabled = mgr.isEnabled();
+if (!isEnabled) {
+ return;
+}
+```
+
+To get information about the eUICC hardware and the eSIM OS version:
+
+```
+EuiccInfo info = mgr.getEuiccInfo();
+String osVer = info.getOsVersion();
+```
+
+Many APIs, such as `downloadSubscription()` and `switchToSubscription()`, use
+`PendingIntent` callbacks as they may take seconds or even minutes to complete.
+The `PendingIntent` is sent with a result code in the
+`EuiccManager#EMBEDDED_SUBSCRIPTION_RESULT_` space, which provides
+framework-defined error codes, as well as an arbitrary detailed result code
+propagated from the LPA as `EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE`, allowing
+the carrier app to track for logging/debugging purposes. The `PendingIntent`
+must be a `BroadcastReceiver`.
+
+To download a given `DownloadableSubscription` (created from an
+_activation code_ or a QR code):
+
+```
+// Register receiver.
+static final String ACTION_DOWNLOAD_SUBSCRIPTION = "download_subscription";
+static final String LPA_DECLARED_PERMISSION
+ = "com.your.company.lpa.permission.BROADCAST";
+BroadcastReceiver receiver =
+ new BroadcastReceiver() {
+ @Override
+ public void onReceive(Context context, Intent intent) {
+ if (!action.equals(intent.getAction())) {
+ return;
+ }
+ resultCode = getResultCode();
+ detailedCode = intent.getIntExtra(
+ EuiccManager.EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE,
+ 0 /* defaultValue*/);
+ resultIntent = intent;
+ }
+ };
+context.registerReceiver(receiver,
+ new IntentFilter(ACTION_DOWNLOAD_SUBSCRIPTION),
+ LPA_DECLARED_PERMISSION /* broadcastPermission*/,
+ null /* handler */);
+
+// Download subscription asynchronously.
+DownloadableSubscription sub = DownloadableSubscription
+ .forActivationCode(code /* encodedActivationCode*/);
+Intent intent = new Intent(action);
+PendingIntent callbackIntent = PendingIntent.getBroadcast(
+ getContext(), 0 /* requestCode */, intent,
+ PendingIntent.FLAG_UPDATE_CURRENT);
+mgr.downloadSubscription(sub, true /* switchAfterDownload */,
+ callbackIntent);
+```
+
+To switch to a subscription given the subscription ID:
+
+```
+// Register receiver.
+static final String ACTION_SWITCH_TO_SUBSCRIPTION = "switch_to_subscription";
+static final String LPA_DECLARED_PERMISSION
+ = "com.your.company.lpa.permission.BROADCAST";
+BroadcastReceiver receiver =
+ new BroadcastReceiver() {
+ @Override
+ public void onReceive(Context context, Intent intent) {
+ if (!action.equals(intent.getAction())) {
+ return;
+ }
+ resultCode = getResultCode();
+ detailedCode = intent.getIntExtra(
+ EuiccManager.EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE,
+ 0 /* defaultValue*/);
+ resultIntent = intent;
+ }
+ };
+context.registerReceiver(receiver,
+ new IntentFilter(ACTION_SWITCH_TO_SUBSCRIPTION),
+ LPA_DECLARED_PERMISSION /* broadcastPermission*/,
+ null /* handler */);
+
+// Switch to a subscription asynchronously.
+Intent intent = new Intent(action);
+PendingIntent callbackIntent = PendingIntent.getBroadcast(
+ getContext(), 0 /* requestCode */, intent,
+ PendingIntent.FLAG_UPDATE_CURRENT);
+mgr.switchToSubscription(1 /* subscriptionId */, callbackIntent);
+```
+
+For a complete list of `EuiccManager` APIs and code examples, see
+[eUICC APIs](/devices/tech/connect/esim-euicc-api).
+
+### Resolvable errors
+
+There are some cases where the system is unable to complete the eSIM operation
+but the error can be resolved by the user. For example, `downloadSubscription`
+may fail if the profile metadata indicates that a *carrier confirmation code*
+is required. Or `switchToSubscription` may fail if the carrier app has carrier
+privileges over the destination profile (i.e. carrier owns the profile) but
+doesn't have carrier privileges over the currently enabled profile, and hence
+user consent is required.
+
+For these cases, the caller's callback is called with
+`EuiccManager#EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR`. The callback
+`Intent` will contain internal extras such that when the caller passes it to
+[`EuiccManager#startResolutionActivity`](https://developer.android.com/reference/android/telephony/euicc/EuiccManager.html#startResolutionActivity(android.app.Activity,%20int,%20android.content.Intent,%20android.app.PendingIntent)),
+resolution can be requested through the LUI. Using the confirmation code for
+example again,
+[`EuiccManager#startResolutionActivity`](https://developer.android.com/reference/android/telephony/euicc/EuiccManager.html#startResolutionActivity(android.app.Activity,%20int,%20android.content.Intent,%20android.app.PendingIntent))
+triggers an LUI screen that allows the user to enter a confirmation code;
+after the code is entered, the download operation is resumed. This approach
+provides the carrier app with full control over when the UI is shown, but gives
+the LPA/LUI an extensible method for adding new handling of user-recoverable
+issues in the future without needing client apps to change.
+
+Android {{ androidPVersionNumber }} defines these resolvable errors in
+[`EuiccService`](https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/service/euicc/EuiccService.java),
+which the LUI should handle:
+
+```
+/**
+ * Alert the user that this action will result in an active SIM being
+ * deactivated. To implement the LUI triggered by the system, you need to define
+ * this in AndroidManifest.xml.
+ */
+public static final String ACTION_RESOLVE_DEACTIVATE_SIM =
+ "android.service.euicc.action.RESOLVE_DEACTIVATE_SIM";
+/**
+ * Alert the user about a download/switch being done for an app that doesn't
+ * currently have carrier privileges.
+ */
+public static final String ACTION_RESOLVE_NO_PRIVILEGES =
+ "android.service.euicc.action.RESOLVE_NO_PRIVILEGES";
+
+/** Ask the user to input carrier confirmation code. */
+public static final String ACTION_RESOLVE_CONFIRMATION_CODE =
+ "android.service.euicc.action.RESOLVE_CONFIRMATION_CODE";
+```
+
+### Carrier privileges
+
+If you are a carrier developing your own carrier app that calls `EuiccManager`
+to download profiles onto a device, your profile should include carrier
+privilege rules corresponding to your carrier app in the metadata. This is
+because subscription profiles belonging to different carriers can co-exist in
+the eUICC of a device, and each carrier app should only be allowed to access the
+profiles owned by that carrier. For example, carrier A should not be able to
+download, enable, or disable a profile owned by carrier B.
+
+To ensure a profile is only accessible to its owner, Android uses a mechanism to
+grant special privileges to the profile owner's app (i.e. carrier app). The
+Android platform loads certificates stored in the profile's Access Rule File
+(ARF) and grants permission to apps signed by these certificates to make calls
+to `EuiccManager` APIs. The high-level process is described below:
+
+1. Operator signs the carrier app APK; the
+ [apksigner](https://developer.android.com/studio/command-line/apksigner)
+ tool attaches the public-key certificate to the APK.
+1. Operator/SM-DP+ prepares a profile and its metadata, which include an ARF
+ that contains:
+
+ 1. Signature (SHA-1 or SHA-256) of the carrier app's public-key certificate
+ (required)
+ 1. Package name of the carrier app (optional)
+
+1. Carrier app tries to perform an eUICC operation via `EuiccManager` API.
+
+1. Android platform verifies SHA-1 or SHA-256 hash of the caller app's
+ certificate matches the signature of the certificate obtained from the
+ target profile's ARF. If the package name of the carrier app is included in
+ the ARF, it must also match the package name of the caller app.
+
+1. After the signature and the package name (if included) are verified, the
+ carrier privilege is granted to the caller app over the target profile.
+
+Because profile metadata can be available outside of the profile itself (so that
+LPA can retrieve the profile metadata from SM-DP+ before the profile is
+downloaded, or from ISD-R when the profile is disabled), it should contain the
+same carrier privilege rules as in the profile.
+
+The eUICC OS and SM-DP+ must support a proprietary tag **BF76** in the profile
+metadata. The tag content should be the same carrier privilege rules as returned
+by the ARA (Access Rule Applet) defined in
+[UICC Carrier Privileges](/devices/tech/config/uicc):
+
+```
+RefArDo ::= [PRIVATE 2] SEQUENCE { -- Tag E2
+ refDo [PRIVATE 1] SEQUENCE { -- Tag E1
+ deviceAppIdRefDo [PRIVATE 1] OCTET STRING (SIZE(20|32)), -- Tag C1
+ pkgRefDo [PRIVATE 10] OCTET STRING (SIZE(0..127)) OPTIONAL -- Tag CA
+ },
+ arDo [PRIVATE 3] SEQUENCE { -- Tag E3
+ permArDo [PRIVATE 27] BIT STRING (SIZE(8)) -- Tag DB
+ }
+}
+```
+
+For more details on app signing, see
+[Sign your app](https://developer.android.com/studio/publish/app-signing). For
+details on carrier privileges, see
+[UICC Carrier Privileges](/devices/tech/config/uicc).
+
+## Making an LPA app
+
+You can implement your own LPA, which must be hooked up with Android Euicc
+APIs. The following sections give a brief overview of making an LPA app and
+integrating it with the Android system.
+
+### Hardware/modem requirements
+
+The LPA and the eSIM OS on the eUICC chip must support at least GSMA RSP (Remote
+SIM Provisioning) v2.0 or v2.2. You should also plan to use SM-DP+ and SM-DS
+servers that have a matching RSP version. For detailed RSP architecture, see
+[GSMA SGP.21 RSP Architecture Specification](https://www.gsma.com/newsroom/all-documents/sgp-21-rsp-architecture-v2-2/).
+
+In addition, to integrate with the eUICC APIs in Android
+{{ androidPVersionNumber }}, the device modem should send terminal capabilities
+with the support for eUICC capabilities encoded (Local Profile Management and
+Profile Download). It also needs to implement the following APIs:
+
++ IRadio HAL v1.1: setSimPower
++ IRadio HAL v1.2: getIccCardStatus
++ IRadioConfig HAL v1.0: getSimSlotsStatus
+
+The modem should recognize the eSIM with the default boot profile enabled as a
+valid SIM and keep the SIM power on.
+
+For a complete list of modem requirements, see
+[Modem Requirements for eSIM Support](/devices/tech/connect/esim-modem-requirements).
+
+### EuiccService
+
+An LPA consists of two separate components (may both be implemented in the same
+APK): the LPA backend, and the LPA UI or LUI.
+
+To implement the LPA backend, you must extend
+[`EuiccService`](https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/service/euicc/EuiccService.java)
+and declare this service in your manifest file. The service must require the
+`android.permission.BIND_EUICC_SERVICE` system permission to ensure that only
+the system can bind to it. The service must also include an intent filter with
+the `android.service.euicc.EuiccService` action. The priority of the intent
+filter should be set to a non-zero value in case multiple implementations are
+present on the device. For example:
+
+```
+<service
+ android:name=".EuiccServiceImpl"
+ android:permission="android.permission.BIND_EUICC_SERVICE">
+ <intent-filter android:priority="100">
+ <action android:name="android.service.euicc.EuiccService" />
+ </intent-filter>
+</service>
+```
+
+Internally, the Android framework determines the active LPA and interacts with
+it as needed to support the Android eUICC APIs. `PackageManager` is queried for
+all apps with the `android.permission.WRITE_EMBEDDED_SUBSCRIPTIONS` permission,
+which specifies a service for the `android.service.euicc.EuiccService` action.
+The service with the highest priority is selected. If no service is found, LPA
+support is disabled.
+
+To implement the LUI, you must provide an activity for the following actions:
+
++ `android.telephony.euicc.action.MANAGE_EMBEDDED_SUBSCRIPTIONS`
++ `android.telephony.euicc.action.PROVISION_EMBEDDED_SUBSCRIPTION`
+
+As with the service, each activity must require the
+`android.permission.BIND_EUICC_SERVICE` system permission. Each should have an
+intent filter with the appropriate action, the
+`android.service.euicc.category.EUICC_UI` category, and a non-zero priority.
+Similar logic is used to pick the implementations for these activities as
+with picking the implementation of
+[`EuiccService`](https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/service/euicc/EuiccService.java).
+For example:
+
+```
+<activity android:name=".MyLuiActivity"
+ android:exported="true"
+ android:permission="android.permission.BIND_EUICC_SERVICE">
+ <intent-filter android:priority="100">
+ <action android:name=
+ "android.telephony.euicc.action.MANAGE_EMBEDDED_SUBSCRIPTIONS" />
+ <action android:name=
+ "android.telephony.euicc.action.PROVISION_EMBEDDED_SUBSCRIPTION" />
+ <category android:name="android.intent.category.DEFAULT" />
+ <category android:name="android.service.euicc.category.EUICC_UI" />
+ </intent-filter>
+</activity>
+```
+
+This implies that the UI implementing these screens can come from a different
+APK from the one that implements
+[`EuiccService`](https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/service/euicc/EuiccService.java).
+Whether to have a single APK or multiple APKs (e.g. one that implements
+[`EuiccService`](https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/service/euicc/EuiccService.java)
+and one that provides LUI activities) is a design choice.
+
+### EuiccCardManager
+
+`EuiccCardManager` is the interface for communicating with the eSIM chip. It
+provides ES10 functions (as described in the GSMA RSP spec) and handles the
+low-level APDU request/response commands as well as ASN.1 parsing.
+`EuiccCardManager` is a system API and can be called only by system-privileged
+applications.
+
+
+
+**Figure 2.** Both carrier app and LPA use Euicc APIs
+
+The profile operation APIs through `EuiccCardManager` require the caller to be
+an LPA. This is enforced by the Android framework. This means the caller must
+extend the `EuiccService` and be declared in your manifest file, as described in
+the previous sections.
+
+Similar to the `EuiccManager`, to use the `EuiccCardManager` APIs, your LPA must
+first obtain the instance of `EuiccCardManager` through
+`Context#getSystemService`:
+
+```
+EuiccCardManager cardMgr = context.getSystemService(Context.EUICC_CARD_SERVICE);
+```
+
+Then, to get all the profiles on the eUICC:
+
+```
+ResultCallback<EuiccProfileInfo[]> callback =
+ new ResultCallback<EuiccProfileInfo[]>() {
+ @Override
+ public void onComplete(int resultCode,
+ EuiccProfileInfo[] result) {
+ if (resultCode == EuiccCardManagerReflector.RESULT_OK) {
+ // handle result
+ } else {
+ // handle error
+ }
+ }
+ };
+
+cardMgr.requestAllProfiles(eid, AsyncTask.THREAD_POOL_EXECUTOR, callback);
+```
+
+Internally, `EuiccCardManager` binds to `EuiccCardController` (which runs in the
+phone process) through an AIDL interface, and each `EuiccCardManager` method
+receives its callback from the phone process through a different, dedicated AIDL
+interface. When using `EuiccCardManager` APIs, the caller (LPA) must provide an
+[`Executor`](https://developer.android.com/reference/java/util/concurrent/Executor)
+through which the callback is invoked. This `Executor` may run on a single
+thread or on a thread pool of your choice.
+
+Most `EuiccCardManager` APIs have the same usage pattern. For example, to load a
+bound profile package onto the eUICC:
+
+```
+...
+cardMgr.loadBoundProfilePackage(eid, boundProfilePackage,
+ AsyncTask.THREAD_POOL_EXECUTOR, callback);
+```
+
+To switch to a different profile with a given ICCID:
+
+```
+...
+cardMgr.switchToProfile(eid, iccid, true /* refresh */,
+ AsyncTask.THREAD_POOL_EXECUTOR, callback);
+```
+
+To get the default SM-DP+ address from the eUICC chip:
+
+```
+...
+cardMgr.requestDefaultSmdpAddress(eid, AsyncTask.THREAD_POOL_EXECUTOR,
+ callback);
+```
+
+To retrieve a list of notifications of the given notification events:
+
+```
+...
+cardMgr.listNotifications(eid,
+ EuiccNotification.Event.INSTALL
+ | EuiccNotification.Event.DELETE /* events */,
+ AsyncTask.THREAD_POOL_EXECUTOR, callback);
+```
+
+## Validation
+
+AOSP does not come with an LPA implementation and you are not expected to
+have an LPA available on all Android builds (not every phone supports eSIM). For
+this reason, there are no end-to-end CTS test cases. However, basic test cases are available in AOSP to ensure the exposed eUICC APIs
+are valid in Android builds.
+
+You should make sure the builds pass the following CTS test cases (for public
+APIs):
+
+[https://android.googlesource.com/platform/cts/+/master/tests/tests/telephony/src/android/telephony/](https://android.googlesource.com/platform/cts/+/master/tests/tests/telephony/src/android/telephony/euicc/cts)
+
+Carriers implementing a carrier app should go through their normal in-house
+quality assurance
+cycles to ensure all implemented features are working as expected. At the
+minimum, the carrier app should be able to list all the subscription profiles
+owned by the same operator, download and install a profile, activate service on
+the profile, switch between profiles, and delete profiles.
+
+If you are making your own LPA, you should go through much more rigorous
+testing. You should work with your modem vendor, eUICC chip or eSIM OS vendor,
+SM-DP+ vendors, and carriers to resolve issues and ensure interoperability of
+your LPA within the RSP architecture. A good amount of manual testing is
+inevitable. For best test coverage, you should follow the
+[GSMA SGP.23 RSP Test Plan](https://www.gsma.com/newsroom/all-documents/sgp-23-v1-2-rsp-test-specification/).
diff --git a/en/devices/tech/connect/images/call-log-entry-3p.png b/en/devices/tech/connect/images/call-log-entry-3p.png
new file mode 100644
index 0000000..e3ec9c7
--- /dev/null
+++ b/en/devices/tech/connect/images/call-log-entry-3p.png
Binary files differ
diff --git a/en/devices/tech/connect/images/carrier-app-euicc-apis.png b/en/devices/tech/connect/images/carrier-app-euicc-apis.png
new file mode 100644
index 0000000..4fba5ab
--- /dev/null
+++ b/en/devices/tech/connect/images/carrier-app-euicc-apis.png
Binary files differ
diff --git a/en/devices/tech/connect/images/carrier-oem-lpa.png b/en/devices/tech/connect/images/carrier-oem-lpa.png
new file mode 100644
index 0000000..4fba5ab
--- /dev/null
+++ b/en/devices/tech/connect/images/carrier-oem-lpa.png
Binary files differ
diff --git a/en/devices/tech/connect/images/imsservice-sequence.png b/en/devices/tech/connect/images/imsservice-sequence.png
new file mode 100644
index 0000000..3654945
--- /dev/null
+++ b/en/devices/tech/connect/images/imsservice-sequence.png
Binary files differ
diff --git a/en/devices/tech/connect/images/imsservice.png b/en/devices/tech/connect/images/imsservice.png
new file mode 100644
index 0000000..b1f96d8
--- /dev/null
+++ b/en/devices/tech/connect/images/imsservice.png
Binary files differ
diff --git a/en/devices/tech/connect/images/incoming-call-3p-call-app.png b/en/devices/tech/connect/images/incoming-call-3p-call-app.png
new file mode 100644
index 0000000..cab4e28
--- /dev/null
+++ b/en/devices/tech/connect/images/incoming-call-3p-call-app.png
Binary files differ
diff --git a/en/devices/tech/connect/images/rsp-architecture.png b/en/devices/tech/connect/images/rsp-architecture.png
new file mode 100644
index 0000000..671763c
--- /dev/null
+++ b/en/devices/tech/connect/images/rsp-architecture.png
Binary files differ
diff --git a/en/devices/tech/connect/images/rtt-accessibility.png b/en/devices/tech/connect/images/rtt-accessibility.png
new file mode 100644
index 0000000..495320f
--- /dev/null
+++ b/en/devices/tech/connect/images/rtt-accessibility.png
Binary files differ
diff --git a/en/devices/tech/connect/images/rtt-banner.png b/en/devices/tech/connect/images/rtt-banner.png
new file mode 100644
index 0000000..4460cf0
--- /dev/null
+++ b/en/devices/tech/connect/images/rtt-banner.png
Binary files differ
diff --git a/en/devices/tech/connect/images/rtt-call-details.png b/en/devices/tech/connect/images/rtt-call-details.png
new file mode 100644
index 0000000..a29d9e0
--- /dev/null
+++ b/en/devices/tech/connect/images/rtt-call-details.png
Binary files differ
diff --git a/en/devices/tech/connect/images/rtt-in-call-ui-options.png b/en/devices/tech/connect/images/rtt-in-call-ui-options.png
new file mode 100644
index 0000000..d5fd116
--- /dev/null
+++ b/en/devices/tech/connect/images/rtt-in-call-ui-options.png
Binary files differ
diff --git a/en/devices/tech/connect/images/rtt-in-call-ui.png b/en/devices/tech/connect/images/rtt-in-call-ui.png
new file mode 100644
index 0000000..057ab40
--- /dev/null
+++ b/en/devices/tech/connect/images/rtt-in-call-ui.png
Binary files differ
diff --git a/en/devices/tech/connect/images/rtt-mode-view.png b/en/devices/tech/connect/images/rtt-mode-view.png
new file mode 100644
index 0000000..f5022cf
--- /dev/null
+++ b/en/devices/tech/connect/images/rtt-mode-view.png
Binary files differ
diff --git a/en/devices/tech/connect/images/rtt-standard-call-ui.png b/en/devices/tech/connect/images/rtt-standard-call-ui.png
new file mode 100644
index 0000000..4ed05cb
--- /dev/null
+++ b/en/devices/tech/connect/images/rtt-standard-call-ui.png
Binary files differ
diff --git a/en/devices/tech/connect/images/test-app-3p-call.png b/en/devices/tech/connect/images/test-app-3p-call.png
new file mode 100644
index 0000000..fa9ba54
--- /dev/null
+++ b/en/devices/tech/connect/images/test-app-3p-call.png
Binary files differ
diff --git a/en/devices/tech/connect/images/wifi-arch.png b/en/devices/tech/connect/images/wifi-arch.png
new file mode 100644
index 0000000..72e744f
--- /dev/null
+++ b/en/devices/tech/connect/images/wifi-arch.png
Binary files differ
diff --git a/en/devices/tech/connect/ims.md b/en/devices/tech/connect/ims.md
new file mode 100644
index 0000000..0a93f39
--- /dev/null
+++ b/en/devices/tech/connect/ims.md
@@ -0,0 +1,298 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Implementing IMS
+
+Android {{ androidPVersionNumber }} introduces a new SystemApi interface called
+[ImsService](https://android.googlesource.com/platform/frameworks/base/+/master/telephony/java/android/telephony/ims/)
+to help you implement IP Multimedia Subsystem (IMS). The ImsService API is a
+well-defined interface between the Android platform and a vendor or
+carrier-provided IMS implementation.
+
+<img src="/devices/tech/connect/images/imsservice.png" alt="ImsService overview" width="">
+
+**Figure 1.** ImsService overview
+
+By using the ImsService interface, the IMS implementer can provide important
+signaling information to the platform, such as IMS registration information, SMS
+over IMS integration, and MmTel feature integration to provide voice and video
+calling. The ImsService API is an Android System API as well, meaning it can be
+built against the Android SDK directly instead of against the source. An IMS
+application that has been pre-installed on the device can also be configured to
+be Play Store updatable.
+
+## Examples and source
+
+Android provides an application on AOSP that implements portions of the
+ImsService API for testing and development purposes. You can find the
+application at
+[/testapps/ImsTestService](https://android.googlesource.com/platform/packages/services/Telephony/+/master/testapps/ImsTestService/).
+
+You can find the documentation for the ImsService API in
+[ImsService](https://android.googlesource.com/platform/frameworks/base/+/master/telephony/java/android/telephony/ims/ImsService.java)
+and in the other classes in the API.
+
+## Implementation
+
+The ImsService API is a high level API that lets you implement IMS in many ways,
+depending on the hardware available. For example, the implementation changes
+depending on whether the IMS implementation is fully on the application
+processor or if it is partially or fully offloaded to the modem. Android does
+not provide a public HAL for offloading to the baseband processor, so any
+offloading must occur using your HAL extension to the modem.
+
+### Compatibility with older IMS implementations
+
+Although Android {{ androidPVersionNumber }} includes the ImsService API,
+devices using an older implementation for IMS are not able to support the API.
+For these devices, the older AIDL interfaces and wrapper classes have been moved
+to the `android.telephony.ims.compat` namespace. When upgrading to Android
+{{ androidPVersionNumber }}, older devices must do the following to continue
+the support of the older API.
+
++ Change the namespace of the ImsService implementation to extend from the
+ `android.telephony.ims.compat` namespace API.
++ Modify the ImsService service definition in AndroidManifest.xml to use the
+ `android.telephony.ims.compat.ImsService` intent-filter action, instead of
+ the `android.telephony.ims.ImsService` action.
+
+The framework will then bind to the ImsService using the compatibility layer
+provided in Android {{ androidPVersionNumber }} to work with the legacy
+`ImsService` implementation.
+
+### ImsService registration with the framework
+
+The ImsService API is implemented as a service, which the Android framework
+binds to in order to communicate with the IMS implementation. Three steps are
+necessary to register an application that implements an ImsService with the
+framework. First, the ImsService implementation must register itself with the
+platform using the `AndroidManifest.xml` of the application; second, it must
+define which IMS features the implementation supports (MmTel or RCS); and third,
+it must be verified as the trusted IMS implementation either in the carrier
+configuration or device overlay.
+
+#### Service definition
+
+The IMS application registers an ImsService with the framework by adding a
+`service` entry into the manifest using the following format:
+
+```
+<service
+ android:name="com.egcorp.ims.EgImsService"
+ android:directBootAware="true"
+ Android:persistent="true"
+ ...
+ android:permission="android.permission.BIND_IMS_SERVICE" >
+ ...
+ <intent-filter>
+ <action android:name="android.telephony.ims.ImsService" />
+ </intent-filter>
+</service>
+```
+
+The `service` definition in `AndroidManifest.xml` defines the following
+attributes, which are necessary for correct operation:
+
++ `directBootAware="true"`: Allows the `service` to be found and bound before
+ the file system has been decrypted. This means that the ImsService must not
+ do any file system access with encrypted files. For more information about
+ File-Based Encryption (FBE), see
+ [File-Based Encryption](/security/encryption/file-based).
++ `persistent="true"`: Allows this service to be run persistently and not be
+ killed by the system to reclaim memory. This attribute ONLY works if the
+ application is built as a system application.
++ `permission="android.permission.BIND_IMS_SERVICE"`: Ensures that only a
+ process that has had the `BIND_IMS_SERVICE` permission granted to it can
+ bind to the application. This prevents a rogue app from binding to the
+ service, since only system applications can be granted the permission by the
+ framework.
+
+The service must also specify the `intent-filter` element with the action
+`android.telephony.ims.ImsService`. This allows the framework to find the
+`ImsService`.
+
+### IMS feature specification
+
+After the ImsService has been defined as an Android service in
+AndroidManifest.xml, the ImsService must define which IMS features it supports.
+Android currently supports the MmTel and RCS features, however only MmTel is
+integrated into the framework. Although there are no RCS APIs integrated into
+the framework, there are still advantages to declaring it as a feature of the
+ImsService.
+
+Below are the valid features defined in `android.telephony.ims.ImsFeature` that
+an ImsService can provide and an explanation and example as to why an IMS
+application would want to implement one or all of these features. After each
+feature is defined, this page outlines how the `ImsService` declares the set of
+features that it defines for each SIM slot.
+
+#### FEATURE_MMTEL
+
+The `ImsService` implements the IMS MMTEL feature, which contains support for
+all IMS media (IR.92 and IR.94 specifications) except emergency attach to the
+IMS PDN for emergency calling. Any implementation of `ImsService` that wishes to
+support the MMTEL features should extend the
+`android.telephony.ims.MmTelFeature` base class and return a custom
+`MmTelFeature` implementation in
+[`ImsService#createMmTelFeature`](https://android.googlesource.com/platform/frameworks/base/+/master/telephony/java/android/telephony/ims/ImsService.java#335).
+
+#### FEATURE_EMERGENCY_MMTEL
+
+Declaring this feature only signals to the platform that emergency attach to the
+IMS PDN for emergency services is possible. If this feature is not declared for
+your `ImsService`, the platform will always default to Circuit Switch Fallback
+for emergency services. The `FEATURE_MMTEL` feature must be defined for this
+feature to be defined.
+
+#### FEATURE_RCS
+
+The ImsService API does not implement any IMS RCS features, but the
+`android.telephony.ims.RcsFeature` base class can still be useful. The framework
+automatically binds to the ImsService and calls `ImsService#createRcsFeature`
+when it detects that the package should provide RCS. If the SIM card associated
+with the RCS service is removed, the framework automatically calls
+`RcsFeature#onFeatureRemoved` and then cleans up the `ImsService` associated
+with the RCS feature. This functionality can remove some of the custom
+detection/binding logic that an RCS feature would otherwise have to provide.
+
+#### Registration of supported features
+
+The telephony framework first binds to the ImsService to query the features that
+it supports using the `ImsService#querySupportedImsFeatures` API. After the
+framework calculates which features the ImsService will support, it will call
+`ImsService#create[...]Feature` for each feature that the ImsService will be
+responsible for. If the features that the IMS application supports changes, you
+can use `ImsService#onUpdateSupportedImsFeatures` to signal the framework to
+recalculate supported features. See the diagram below for more information on
+the initialization and binding of the ImsService.
+
+
+
+**Figure 2:** ImsService initialization and binding
+
+### Framework detection and verification of ImsServices
+
+Once the ImsService has been defined correctly in AndroidManifest.xml, the
+platform must be configured to (securely) bind to the ImsService when
+appropriate. There are two types of ImsServices that the framework binds to:
+
+1. Carrier "override" ImsService: These ImsServices are preloaded onto the
+ device but are attached to one or more cellular carriers and will only be
+ bound when a matching SIM card is inserted. This is configured using the
+ [`key_config_ims_package_override`](https://android.googlesource.com/platform/frameworks/base/+/master/telephony/java/android/telephony/CarrierConfigManager.java#309)
+ CarrierConfig key.
+1. Device "default" ImsService: This is the default ImsService that is loaded
+ onto the device by an OEM and should be designed to provide IMS services in
+ all situations when a carrier ImsService is not available and is useful in
+ situations where the device has no SIM card inserted or the SIM card
+ inserted does not have a carrier ImsService installed with it. This is
+ defined in the device overlay
+ [`config_ims_package`](https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml#2705)
+ key.
+
+Both of these ImsService implementations are required to be System applications,
+or to reside in the /system/priv-app/ folder to grant the appropriate
+user-granted permissions (namely phone, microphone, location, camera, and
+contacts permissions). By verifying whether the package name of the IMS
+implementation matches the CarrierConfig or device overlay values defined above,
+only trusted applications are bound.
+
+## Customization
+
+The ImsService allows the IMS features that it supports (MMTEL and RCS) to be
+enabled or disabled dynamically via updates using the
+`ImsService#onUpdateSupportedImsFeatures` method. This triggers the framework to
+recalculate which ImsServices are bound and which features they support. If the
+IMS application updates the framework with no features supported, the ImsService
+will be unbound until the phone is rebooted or a new SIM card is inserted that
+matches the IMS application.
+
+### Binding priority for multiple ImsService
+
+The framework cannot support binding to all of the possible ImsServices that are
+preloaded onto the device and will bind to up to two ImsServices per SIM slot
+(one ImsService for each feature) in the following order:
+
+1. The ImsService package name defined by the CarrierConfig value
+ `key_config_ims_package_override` when there is a SIM card inserted.
+1. The ImsService package name defined in the device overlay value for
+ `config_ims_package`including the case where there is no SIM card inserted.
+ This ImsService MUST support the Emergency MmTel feature.
+
+You must either have the package name of your ImsService defined in the
+CarrierConfig for each of the carriers that will use that package or in the
+device overlay if your ImsService will be the default, as defined above.
+
+Let's break this down for each feature. For a single SIM device, two IMS
+features are possible: MMTel and RCS. The framework will try to bind in the
+order defined above for each feature and if the feature is not available for the
+ImsService defined in the Carrier Configuration override, the framework will
+fallback to your default ImsService. So, for example, the table below describes
+which IMS feature the framework will use given three IMS applications
+implementing ImsServices installed on a system with the following features:
+
++ Carrier A ImsService supports RCS
++ Carrier B ImsService supports RCS and MMTel
++ OEM ImsService supports RCS, MMTel, and Emergency MMTel
+
+<table>
+<thead>
+<tr>
+<th><strong>SIM Card Inserted</strong></th>
+<th><strong>RCS Feature</strong></th>
+<th><strong>MMTel Feature</strong></th>
+<th><strong>Emergency MMTel Feature</strong></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Carrier A</td>
+<td>Carrier A</td>
+<td>OEM</td>
+<td>OEM</td>
+</tr>
+<tr>
+<td>Carrier B</td>
+<td>Carrier B</td>
+<td>Carrier B</td>
+<td>OEM</td>
+</tr>
+<tr>
+<td>No SIM</td>
+<td>OEM</td>
+<td>OEM</td>
+<td>OEM</td>
+</tr>
+</tbody>
+</table>
+
+## Validation
+
+The ImsService APIs include a GTS test suite that verifies the functionality of
+the ImsService API in the framework as well as the IMS application Service
+binding logic. The `GtsImsServiceTestCases` GTS APK can be run as part of the
+GTS test suite to ensure that the API surface functions consistently across all
+Android {{ androidPVersionNumber }} implementations.
+
+Tools for verifying the IMS implementation itself are not included since the IMS
+specifications are extremely large and use special verification equipment. The
+tests can only verify that the telephony framework properly responds to the
+ImsService API.
diff --git a/en/devices/tech/connect/index.html b/en/devices/tech/connect/index.html
index 16c6173..92eb6f7 100644
--- a/en/devices/tech/connect/index.html
+++ b/en/devices/tech/connect/index.html
@@ -1,6 +1,6 @@
<html devsite>
<head>
- <title>Ensuring Network Connectivity</title>
+ <title>Connectivity</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
@@ -23,6 +23,10 @@
+<p>This section describes implementation of standard Android connectivity
+protocols and describes use of related features, including Bluetooth, NFC,
+Wi-Fi, Telephony, and more.</p>
+
<p>Follow the instructions in this section to ensure your Android devices are
connected properly.</p>
diff --git a/en/devices/tech/connect/rtt.md b/en/devices/tech/connect/rtt.md
new file mode 100644
index 0000000..cf13c98
--- /dev/null
+++ b/en/devices/tech/connect/rtt.md
@@ -0,0 +1,197 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Implementing Real-Time Text
+
+This page describes how to implement Real-Time Text (RTT) in Android
+{{ androidPVersionNumber }}. RTT is a feature for deaf or hard of hearing users
+that replaces Text Telephone (TTY) technology. With this feature, devices can
+use the same phone number for voice and RTT calls, simultaneously transmit text
+as it is being typed on a character-by-character basis, support 911
+communications, and provide backward capability with TTY.
+
+In an RTT call, both the caller and receiver have indications that they are in
+an RTT call. When connected, both sides enter the RTT call where the text input
+and keyboard is activated. When typing, the text appears and is sent as it is
+typed, character by character.
+
+## Examples and source
+
+Framework components are available in AOSP at
+[Call.RttCall](https://developer.android.com/reference/android/telecom/Call.RttCall)
+and
+[Connection.RttTextStream](https://developer.android.com/reference/android/telecom/Connection.RttTextStream).
+IMS/modem components are proprietary and should be supplied by the IMS/modem
+vendor. Dialer RTT reference implementation is also available.
+
+AOSP Dialer code for RTT:
+
++ InCall:
+ [/java/com/android/incallui/rtt](https://android.googlesource.com/platform/packages/apps/Dialer/+/master/java/com/android/incallui/rtt)
++ Call log:
+ [/java/com/android/dialer/rtt](https://android.googlesource.com/platform/packages/apps/Dialer/+/master/java/com/android/dialer/rtt)
+
+## Implementation
+
+To implement RTT, you should work with a modem/SoC provider because a modem that
+supports RTT is required. You can upgrade to Android
+{{ androidPVersionNumber }} or backport a list of telephony framework patches
+into Android 8.0. APIs added in Android 8.0 AOSP will not work.
+
+This feature uses public APIs in AOSP in `android.telecom` and @SystemApis in
+`android.telephony.ims`. All UI lies within `com.android.phone` and the AOSP
+dialer.
+
+To implement RTT, import the AOSP code and supply an IMS stack that implements
+the IMS-side @SystemApis for RTT. This requires:
+
++ Turning RTT on/off via `ImsConfig#setProvisionedValue(RTT_SETTING_ENABLED)`
++ Indicating RTT status of a call via `ImsStreamMediaProfile#mRttMode`
++ Support for the following methods in `ImsCallSession`:
+
+ + `sendRttMessage`
+ + `sendRttModifyRequest`
+ + `sendRttModifyResponse`
+
++ Support for calling the following methods in `ImsCallSessionListener`:
+
+ + `callSessionRttModifyRequestReceived`
+ + `callSessionRttModifyResponseReceived`
+ + `callSessionRttMessageReceived`
+
+## Customization
+
+You can enable or disable this feature using the device config,
+`config_support_rtt`, in the device config overlay for
+`packages/services/Telephony`, and the carrier config flag,
+`CarrierConfigManager.RTT_SUPPORTED_BOOL`, in the carrier config files.
+Depending on the configuration, the feature is either available via the
+Accessibility settings or not. Use the device config to change the default
+settings. By default, the feature is set to Off.
+
+## Validation
+
+To validate your implementation of RTT, run CTS tests, and perform dialer RTT testing.
+
+### CTS testing
+
+The CTS tests (`android.cts.telecom.RttOperationsTest`) cover the AOSP portion
+of the implementation. You must provide your own tests for the IMS stack portion
+of the implementation.
+
+### Dialer RTT testing
+
+<table>
+<thead>
+<tr>
+<th><strong>Scenario description</strong></th>
+<th><strong>UI mock</strong></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><p>If RTT is disabled on the device, a banner about RTT
+is displayed. A "Learn more" option that directs to the Google Help Center
+article page with more information on RTT is displayed.</p>
+<p>Banner call is displayed.</p></td>
+<td><p><img src="/devices/tech/connect/images/rtt-banner.png" width="250px" alt="RTT banner"></p>
+
+</td>
+</tr>
+<tr>
+<td>In Dialer settings, a "Real-Time Text" screen is
+available under Settings > Accessibility that provides an option to enable
+"RTT mode". Descriptive text is displayed to explain the mode: "Send and
+receive text messages instead of speaking and listening during a call".</td>
+<td><p><img src="/devices/tech/connect/images/rtt-accessibility.png" width="250px" alt="RTT accessibility"></p>
+
+</td>
+</tr>
+<tr>
+<td>When RTT is enabled by default,<br>
+<ul>
+<li>While the call is placed, the standard in-call dialing UI is
+displayed.</li>
+<li>Upon call connection, the RTT mode view is displayed. If the receiving
+user does not default into RTT mode, a banner indicating that RTT mode has
+been requested is displayed while waiting for a response. </li>
+</ul>
+</td>
+<td><p><img src="/devices/tech/connect/images/rtt-in-call-ui.png" width="250px" alt="RTT in-call UI"></p>
+
+</td>
+</tr>
+<tr>
+<td>If RTT is disabled on the device:<br>
+<ul>
+<li>Incoming call screen displays standard answering puck and standard
+call labels.</li>
+</ul>
+</td>
+<td><p><img src="/devices/tech/connect/images/rtt-standard-call-ui.png" width="250px" alt="RTT standard call UI"></p>
+
+</td>
+</tr>
+<tr>
+<td>If RTT is enabled on the device and has the default
+set to answer all calls as RTT:<br>
+<ul>
+<li>Incoming call screen displays RTT puck and associated call labels.</li>
+<li>Answering the call loads the RTT mode view with keyboard enabled.</li>
+</ul>
+</td>
+<td><p><img src="/devices/tech/connect/images/rtt-mode-view.png" width="250px" alt="RTT mode view"></p>
+
+</td>
+</tr>
+<tr>
+<td>In the in-call UI for RTT, options are provided to
+allow users to control the state of the voice call and get general help on
+using RTT.<br>
+<ul>
+<li>Toggle microphone on and off.</li>
+<li>Toggle speaker on and off.</li>
+<li>Route audio to external audio devices if available.</li>
+</ul>
+</td>
+<td><p><img src="/devices/tech/connect/images/rtt-in-call-ui-options.png" width="250px" alt="RTT in-call UI options"></p>
+
+</td>
+</tr>
+<tr>
+<td>In the "Call details" screen, a snippet of the RTT
+conversation history is displayed.<br>
+<ul>
+<li>Snippet does not exceed one line in length. If the RTT session did
+not include any conversation content, a notice is displayed indicating no
+content was stored.</li>
+<li>Snippet includes RTT icon to indicate an RTT call.</li>
+<li>Selecting the "See all" link displays a full conversation view with the
+full text of the RTT session. Timestamps are displayed. The user can return
+to the Call details screen using the Back button.</li>
+</ul>
+</td>
+<td><p><img src="/devices/tech/connect/images/rtt-call-details.png" width="250px" alt="RTT call details"></p>
+
+</td>
+</tr>
+</tbody>
+</table>
diff --git a/en/devices/tech/connect/third-party-call-apps.md b/en/devices/tech/connect/third-party-call-apps.md
new file mode 100644
index 0000000..3e1b236
--- /dev/null
+++ b/en/devices/tech/connect/third-party-call-apps.md
@@ -0,0 +1,177 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Supporting Third-Party Calling Apps
+
+Android {{ androidPVersionNumber }} provides APIs to better support third-party
+(3P) calling apps. 3P calling apps typically rely on Telephony APIs such as the
+`PHONE_STATE` broadcast to co-exist alongside carrier phone calls. As a
+consequence, 3P calling apps must give carrier calls priority and often resort
+to silently rejecting incoming calls in the app, or terminating an ongoing call
+to make way for a carrier call.
+
+The APIs in Android {{ androidPVersionNumber }} support concurrent calling
+scenarios between 3P apps and carrier calls. This makes it possible, for
+example, to receive an incoming 3P call while engaged in a carrier call. The
+framework assumes responsibility for ensuring the carrier call is held when the
+user engages in the 3P call.
+
+In Android {{ androidPVersionNumber }}, 3P calling apps are encouraged to
+implement the self-managed `ConnectionService` API. For more information on how
+to build a calling app using this API, see
+[Build a calling app](https://developer.android.com/guide/topics/connectivity/telecom/selfManaged).
+
+The self-managed `ConnectionService` API also gives developers the opportunity
+to opt-in to having calls in their app logged in the system call log (see
+[`EXTRA_LOG_SELF_MANAGED_CALLS`](https://developer.android.com/reference/android/telecom/PhoneAccount#EXTRA_LOG_SELF_MANAGED_CALLS)).
+Per the requirements in the
+[Android Compatibility Definition Document (CDD)](/compatibility/android-cdd#7_4_data_connectivity)
+(section 7.4.1.2), you should ensure your dialer/phone app displays these
+call log entries and shows the name of the 3P calling app where the call
+originated (for an example of how the AOSP dialer app meets this requirement,
+see
+[Call log entries from 3P calling apps](#call_log_entries_from_3p_calling_apps)).
+
+Apps are responsible for setting
+[`CAPABILITY_SUPPORT_HOLD`](https://developer.android.com/reference/android/telecom/Connection.html#CAPABILITY_SUPPORT_HOLD)
+and
+[`CAPABILITY_HOLD`](https://developer.android.com/reference/android/telecom/Connection.html#CAPABILITY_HOLD)
+on their apps' connections. However, it is possible that an app cannot hold a
+call in some circumstances. The framework includes provisions for resolving
+these types of cases.
+
+## Scenarios
+
+You should modify your dialer app to handle the following scenarios.
+
+### Handling incoming calls which disconnect an ongoing call
+
+In a scenario where there is an ongoing 3P call (e.g. in a SuperCaller call)
+that does not support hold, and the user receives a mobile call (e.g. via their
+carrier FooCom), your Dialer/Phone app should indicate to the user that
+answering the mobile network call will end the ongoing 3P call.
+
+This user experience is important as a 3P calling app may have an ongoing call
+that cannot be held by the framework. Answering a new mobile call causes the
+ongoing 3P call to be disconnected.
+
+See the user interface below for an example:
+
+<figure id="incoming-call-3p-call-app">
+ <img src="/devices/tech/connect/images/incoming-call-3p-call-app.png"
+ width="250" class="screenshot"
+ alt="Incoming call disconnecting an ongoing 3P call">
+ <figcaption><strong>Figure 1.</strong> Incoming call which disconnects an
+ ongoing 3P call</figcaption>
+</figure>
+
+Your dialer app can check if an incoming call causes another call to be
+disconnected by checking the
+[call extras](https://developer.android.com/reference/android/telecom/Call.Details.html#getExtras\(\)).
+Make sure that
+[`EXTRA_ANSWERING_DROPS_FG_CALL`](https://developer.android.com/reference/android/telecom/Connection.html#EXTRA_ANSWERING_DROPS_FG_CALL)
+is set to `TRUE`, and
+[`EXTRA_ANSWERING_DROPS_FG_CALL_APP_NAME`](https://developer.android.com/reference/android/telecom/Connection.html#EXTRA_ANSWERING_DROPS_FG_CALL_APP_NAME)
+is set to the name of the app whose call is disconnected upon answering the
+incoming mobile call.
+
+### Call log entries from 3P calling apps
+
+Developers of 3P calling apps can opt-in to having calls in their app logged in
+the system call log (see
+[`EXTRA_LOG_SELF_MANAGED_CALLS`](https://developer.android.com/reference/android/telecom/PhoneAccount#EXTRA_LOG_SELF_MANAGED_CALLS)).
+This means that it is possible to have entries in the call log that are not for
+mobile network calls.
+
+When the AOSP dialer app displays call log entries related to a 3P calling app,
+the name of the app where the call took place is displayed in the call log, as
+illustrated below:
+
+<figure id="call-log-entry-3p">
+ <img src="/devices/tech/connect/images/call-log-entry-3p.png"
+ width="400" class="screenshot"
+ alt="Call log entry with 3P calling app">
+ <figcaption><strong>Figure 2.</strong> Call log entry with name of 3P calling
+ app on dialer app</figcaption>
+</figure>
+
+To determine the name of an app associated with a call log entry, use the
+[`PHONE_ACCOUNT_COMPONENT_NAME`](https://developer.android.com/reference/android/provider/CallLog.Calls.html#PHONE_ACCOUNT_COMPONENT_NAME)
+and
+[`PHONE_ACCOUNT_ID`](https://developer.android.com/reference/android/provider/CallLog.Calls.html#PHONE_ACCOUNT_ID)
+columns in the call log provider to create an instance of
+[`PhoneAccountHandle`](https://developer.android.com/reference/android/telecom/PhoneAccountHandle.html#PhoneAccountHandle\(android.content.ComponentName,%20java.lang.String\)),
+which identifies the source of a call log entry. Query
+[`TelecomManager`](https://developer.android.com/reference/android/telecom/TelecomManager.html#getPhoneAccount\(android.telecom.PhoneAccountHandle\))
+to get the details for the PhoneAccount. \
+To determine if a call log entry is from a 3P calling app, check
+[`PhoneAccount` capabilities ](https://developer.android.com/reference/android/telecom/PhoneAccount.html#getCapabilities\(\))
+to see if
+[`CAPABILITY_SELF_MANAGED`](https://developer.android.com/reference/android/telecom/PhoneAccount.html#CAPABILITY_SELF_MANAGED)
+is set.
+
+The
+[`getLabel`](https://developer.android.com/reference/android/telecom/PhoneAccount.html#getLabel\(\))
+method of the returned `PhoneAccount` returns the name of the app associated
+with a call log entry from the 3P calling app.
+
+## Validation
+
+To test that your device supports 3P calling apps, use the Telecomm test
+application, which implements the self-managed ConnectionService API. The
+application is located in
+[`/packages/services/Telecomm/testapps/`](https://android.googlesource.com/platform/packages/services/Telecomm/+/master/testapps/).
+
+1. Build the test app from the root of your Android source repository using:
+
+ `mmma packages/services/Telecomm/testapps/`
+
+1. Install the build apk using `adb install -g -r <apk path>`. A Self-Managed
+ Sample icon is then added to your launcher.
+
+1. Tap the icon to open the test application.
+
+### Handling incoming calls which disconnect an ongoing call
+
+Follow these steps to verify that an incoming call disconnects an ongoing 3P
+call.
+
+<figure id="test-app-3p-call">
+ <img src="/devices/tech/connect/images/test-app-3p-call.png"
+ width="250" class="screenshot"
+ alt="Test application for 3P calling apps">
+ <figcaption><strong>Figure 3.</strong> Test application with sample
+ implementations of the self-managed ConnectionService API</figcaption>
+</figure>
+
+1. Uncheck the **Holdable** option.
+1. Tap **OUTGOING** to start a new sample outgoing call.
+1. Tap the **ACTIVE** button to make the call go active.
+1. Call the phone number of the device under test with another phone. This
+ invokes the scenario where your dialer is provided with the name of an app,
+ which will have its call disconnected.
+1. When you are finished, tap the **DISCONNECT** button in the test app.
+
+### Call log entries from 3P calling apps
+
+After completing the steps above, the test app should have logged a call to the
+system call log. To confirm the device logs calls from 3P calling apps,
+open your dialer app and confirm the call appears in the system call log.
diff --git a/en/devices/tech/connect/wifi-aware.html b/en/devices/tech/connect/wifi-aware.html
deleted file mode 100644
index 7244abb..0000000
--- a/en/devices/tech/connect/wifi-aware.html
+++ /dev/null
@@ -1,122 +0,0 @@
-<html devsite>
- <head>
- <title>Wi-Fi Aware</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 <a
-href="https://developer.android.com/guide/topics/connectivity/wifi-aware.html">Wi-Fi
-Aware</a> feature in the Android 8.1 (O MR1) release enables supporting devices to
-connect to one another directly over Wi-Fi without internet or cellular network
-access. This feature, built upon the <a href="https://www.wi-fi.org/">Wi-Fi
-Alliance</a> <a href="https://www.wi-fi.org/discover-wi-fi/wi-fi-aware">Wi-Fi
-Aware specification</a> (version 2.0), allows easy sharing of high-throughput
-data among trusted devices and apps that are otherwise off network.
-</p>
-
-<h2 id="examples-and-source">Examples and source</h2>
-
-<p>
-To use this feature, device manufacturers should implement the Wi-Fi Hardware
-Interface Design Language (HIDL) provided in the Android Open Source Project
-(AOSP). In the Android 8.0 (O) release, HIDL replaces the previous Hardware
-Abstraction Layer (HAL) structure used in order to streamline implementations by
-specifying types and method calls collected into interfaces and packages.
-</p>
-
-<p>
-Follow the Wi-Fi HIDL to employ the Wi-Fi aware feature:
-hardware/interfaces/wifi/1.0. The Wi-Fi Aware HAL surface is very large; the
-<a href
- ="https://android.googlesource.com/platform/hardware/interfaces/+/master/wifi/1.0/README-NAN.md">hardware/interfaces/wifi/1.0/README-NAN.md</a>
-file describes the subset which is currently in use.
-</p>
-
-<p>
-You may reference the legacy Wi-Fi HAL to see how it correlates with the new
-HIDL interface:
-<a
-href="https://android.googlesource.com/platform/hardware/libhardware_legacy/+/master/include/hardware_legacy/wifi_nan.h">hardware/libhardware_legacy/+/master/include/hardware_legacy/wifi_nan.h</a>.
-</p>
-
-<h2 id="implementation">Implementation</h2>
-
-<p>
-Device manufacturers need to provide both framework and HAL/firmware support:
-</p>
-<ul>
- <li>Framework:
- <ul>
- <li>AOSP code</li>
- <li>Enable Aware: requires both a feature flag and an HIDL build flag</li>
- </ul>
- <li>Wi-Fi Aware (NAN) HAL support (which implies firmware support)</li>
- </li>
-</ul>
-
-<p>
-To implement this feature, device manufacturers implement the Wi-Fi HIDL and
-also enable two feature flags:
-</p>
-
-<p>
-In <code>BoardConfig.mk</code>, add this flag to tell the Wi-Fi HIDL to include
-the Wi-Fi Aware feature:
-<code>WIFI_HIDL_FEATURE_AWARE := true</code>
-</p>
-
-<p>
-And in <code>device.mk</code>, modify the <code>PRODUCT_COPY_FILES</code>
-environment variable to include support for the Wi-Fi Aware feature:
-<code>PRODUCT_COPY_FILES +=
-frameworks/native/data/etc/android.hardware.wifi.aware.xml:system/etc/permissions/android.hardware.wifi.aware.xml</code>
-</p>
-
-<p>
-Otherwise, everything required for this feature is included in AOSP.
-</p>
-
-<h2 id="validation">Validation</h2>
-
-<p>
-Android Compatibility Test Suite (CTS) tests exist for this feature. CTS detects
-when the feature is enabled and automatically includes the associated tests.
-</p>
-
-<p>
-This feature can also be tested using the <a
-href="/devices/tech/test_infra/tradefed/fundamentals/vts">Vendor
-Test Suite (VTS)</a> and <a
-href="https://android.googlesource.com/platform/tools/test/connectivity/+/master/acts/tests/google/wifi/">acts/sl4a</a>,
-a test suite that conducts extensive integration testing.
-</p>
-
-<p>
-The acts/sl4a test suite, described in
-<a
-href="https://android.googlesource.com/platform/tools/test/connectivity/+/master/acts/tests/google/wifi/aware/README.md">tools/test/connectivity/acts/tests/google/wifi/aware/README.md</a>,
-provides functional, performance, and stress tests.
-</p>
-
-</body>
-</html>
diff --git a/en/devices/tech/connect/wifi-aware.md b/en/devices/tech/connect/wifi-aware.md
new file mode 100644
index 0000000..10477e4
--- /dev/null
+++ b/en/devices/tech/connect/wifi-aware.md
@@ -0,0 +1,148 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Wi-Fi Aware
+
+The
+[Wi-Fi Aware](https://developer.android.com/guide/topics/connectivity/wifi-aware.html)
+feature added in Android 8.0 enables supporting devices to discover, connect,
+and range (added in Android {{ androidPVersionNumber }}) to one another directly
+using the Wi-Fi Aware protocol without internet or cellular network access. This
+feature, built upon the [Wi-Fi Alliance](https://www.wi-fi.org/) (WFA) [Wi-Fi
+Aware specification](https://www.wi-fi.org/discover-wi-fi/wi-fi-aware) (version
+2.0), allows easy sharing of high-throughput data among trusted devices and apps
+that are otherwise off-network.
+
+## Examples and source
+
+To use this feature, device manufacturers should implement the Wi-Fi
+[Hardware Interface Design Language (HIDL)](/devices/architecture/hidl)
+provided in the Android Open Source Project (AOSP). HIDL replaces the previous
+[Hardware Abstraction Layer (HAL)](/devices/architecture/hal) structure used to
+streamline implementations by specifying types and method calls collected into
+interfaces and packages.
+
+Follow the Wi-Fi HIDL to employ the Wi-Fi Aware feature:
+hardware/interfaces/wifi/1.2. The Wi-Fi Aware HAL surface is very large; the
+[hardware/interfaces/wifi/1.2/README-NAN.md]https://android.googlesource.com/platform/hardware/interfaces/+/master/wifi/1.2/README-NAN.md)
+file describes the subset that is currently in use by the framework.
+
+You can reference the legacy Wi-Fi HAL to see how it correlates with the new
+HIDL interface:
+[hardware/libhardware_legacy/+/master/include/hardware_legacy/wifi_nan.h](https://android.googlesource.com/platform/hardware/libhardware_legacy/+/master/include/hardware_legacy/wifi_nan.h).
+
+## Implementation
+
+Device manufacturers need to provide both framework and HAL/firmware support:
+
++ Framework:
+ + AOSP code
+ + Enable Aware: Requires both a feature flag and an HIDL build flag
++ Wi-Fi Aware (NAN) HAL support (which implies firmware support)
+
+To implement this feature, device manufacturers implement the Wi-Fi HIDL and
+enable two feature flags:
+
++ In `BoardConfig.mk` or BoardConfig-common.mk located in
+ `device/<oem>/<device>`, add the following flag:
+
+ ```
+ WIFI_HIDL_FEATURE_AWARE := true
+ ```
+
++ In `device.mk` located in `device/<oem>/<device>`, modify the
+ `PRODUCT_COPY_FILES` environment variable to include support for the Wi-Fi
+ Aware feature:
+
+ ```
+ PRODUCT_COPY_FILES +=
+ frameworks/native/data/etc/android.hardware.wifi.aware.xml:$(TARGET_COPY_OUT_VENDOR)/etc/permissions/android.hardware.wifi.aware.xml
+ ```
+
+Wi-Fi Aware includes ranging to peer devices using the IEEE 802.11mc protocol,
+also known as Round Trip Time (RTT). This sub-feature of Wi-Fi Aware is
+conditional on the device supporting the Wi-Fi RTT feature, i.e. it requires the
+device to support both Wi-Fi Aware and Wi-Fi RTT. For more details, see
+[Wi-Fi RTT](/devices/tech/connect/wifi/rtt).
+
+Otherwise, everything required for this feature is included in AOSP.
+
+## MAC Randomization
+
+Android requires the MAC address of the Wi-Fi Aware discovery (NMI) and data
+interfaces (NDPs) to be randomized and not be identical to the true MAC address
+of the device. The MAC addresses must be:
+
++ Randomized whenever Wi-Fi Aware is enabled or re-enabled.
++ When Wi-Fi Aware is enabled, the MAC address must be randomized at a
+ regular interval configured by the
+ `NanConfigRequest.macAddressRandomizationIntervalSec` HIDL parameter. This
+ is configured by the framework by default to be 30 minutes.
+
+ Note: Per the Wi-Fi Aware spec, randomization may be suspended while an NDP
+ is configured.
+
+## Validation
+
+Android provides a set of unit tests, integration tests (ACTS), [Compatibility Test Suite (CTS)](/compatibility/cts) tests, and [CTS Verifier](/compatibility/cts/verifier)
+tests to validate the Wi-Fi Aware feature. Wi-Fi Aware can also be tested using
+the
+[Vendor Test Suite (VTS)](/devices/tech/test_infra/tradefed/fundamentals/vts).
+
+### Unit tests
+
+The Wi-Fi Aware package tests are executed using:
+
+Service tests:
+
+```
+% ./frameworks/opt/net/wifi/tests/wifitests/runtests.sh -e package
+com.android.server.wifi.aware
+```
+
+Manager tests:
+
+```
+% ./frameworks/base/wifi/tests/runtests.sh -e package android.net.wifi.aware
+```
+
+### Integration tests (ACTS)
+
+The `acts/sl4a` test suite, described in
+`tools/test/connectivity/acts/tests/google/wifi/aware/README.md`, provides
+functional, performance, and stress tests.
+
+### Compatibility Test Suite (CTS)
+
+Use CTS tests to validate the Wi-Fi Aware feature. CTS detects when the feature
+is enabled and automatically includes the associated tests.
+
+The CTS tests can be triggered using:
+
+```
+% atest SingleDeviceTest
+```
+
+### CTS Verifier tests
+
+CTS Verifier tests validate Wi-Fi Aware behavior using two devices: a test
+device and a *known good* device. To run the tests, open CTS Verifier and
+navigate to the section titled Wi-Fi Aware Tests.
diff --git a/en/devices/tech/connect/wifi-debug.md b/en/devices/tech/connect/wifi-debug.md
new file mode 100644
index 0000000..87e7ed7
--- /dev/null
+++ b/en/devices/tech/connect/wifi-debug.md
@@ -0,0 +1,112 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Testing and Debugging
+
+This page describes how to test and debug the Wi-Fi implementation using the
+tools provided in AOSP.
+
+## Testing
+
+To test the Wi-Fi framework, AOSP provides a mix of unit tests, integration
+tests (ACTS), and CTS tests.
+
+### Unit tests
+
+AOSP includes functional and unit tests for the default Wi-Fi framework: both
+for the Wi-Fi Manager (app-side code) and the Wi-Fi Service.
+
+Wi-Fi Manager tests:
+
++ Located in `frameworks/base/wifi/tests`
++ Run using the following shell executable (read the file for more execution
+ options):
+
+ ```
+ % ./frameworks/base/wifi/tests/runtest.sh
+ ```
+
+Wi-Fi Service tests:
+
++ Located in `frameworks/opt/net/wifi/tests/wifitest`
++ Run using the following shell executable (read the file for more execution
+ options):
+
+ ```
+ % ./frameworks/opt/net/wifi/tests/wifitests/runtest.sh
+ ```
+
+### Android Comms Test Suite
+
+The Android Comms Test Suite (ACTS) performs automated testing of connectivity
+stacks, such as Wi-Fi, Bluetooth, and cellular services. The testing tool
+requires adb and Python, and it can be found in `tools/test/connectivity/acts`.
+
+The ACTS tests for Wi-FI are found in
+`tools/test/connectivity/acts/tests/google/wifi`, with an example test
+configuration in the same directory: `example_config.json`.
+
+### CTS Tests
+
+The [Compatibility Test Suite](/compatibility/cts/) (CTS) includes tests for the
+Wi-Fi framework. These are located in
+`cts/tests/tests/net/src/android/net/wifi`. The Wi-Fi CTS tests require the
+device-under-test to be associated with an Access Point at the start of the test
+run.
+
+## Enhanced logging options
+
+Android {{ androidPVersionNumber }} improves Wi-Fi logging to make it easier to
+debug Wi-Fi issues. In Android {{ androidPVersionNumber }}, driver/firmware ring
+buffers can always be on. Bug reports may automatically be triggered when a bad
+state is detected (only in userdebug and eng builds). When the latest Wi-Fi HAL
+(version 1.2) is used, firmware debug buffers are stored in the HAL instead of
+the framework to save IPC costs.
+
+### Implementation
+
+For a reference implementation, see the
+[default implementation](https://android.googlesource.com/platform/hardware/interfaces/+/master/wifi/1.2/default/wifi_chip.cpp#1388)
+in the vendor HAL.
+
+You can disable firmware logging by setting the resource,
+`config_wifi_enable_wifi_firmware_debugging`, to false.
+
+### Integration test (ACTS)
+
+The integration test can be found at
+`/tools/test/connectivity/acts/tests/google/wifi/WifiDiagnosticsTest.py`.
+
+Verified firmware dumps are persisted in the appropriate tombstone directory in
+flash for userdebug builds. Dumpstate collects from this directory when creating
+a bug report.
+
+### Manual test
+
+Run this manual test to verify that old files in the [tombstone directory](/devices/tech/debug/#debuggerd) are
+being deleted.
+
+1. Turn on Wi-Fi.
+1. Connect to a network.
+1. Generate a [bug report](/setup/contribute/read-bug-reports).
+1. Inspect the bugreport zip file and verify that
+ `/lshal-debug/android.hardware.wifi@1.2__IWifi_default.txt` holds the
+ archived firmware logs.
diff --git a/en/devices/tech/connect/wifi-hal.md b/en/devices/tech/connect/wifi-hal.md
new file mode 100644
index 0000000..cd89344
--- /dev/null
+++ b/en/devices/tech/connect/wifi-hal.md
@@ -0,0 +1,83 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Wi-Fi HAL
+
+The Wi-Fi framework has three Wi-Fi HAL surfaces represented by three different
+HIDL packages:
+
++ Vendor HAL: A HAL surface for Android-specific commands. The HIDL files are
+ in `hardware/interfaces/wifi/1.x`.
++ Supplicant HAL: A HAL surface for **wpa_supplicant**. The HIDL files are in
+ `hardware/interfaces/supplicant/1.x`.
++ Hostapd HAL: A HAL surface for **hostapd**. The HIDL files are in
+ `hardware/interfaces/hostapd/1.x`.
+
+## Vendor HAL
+
+The Vendor HAL provides Android-specific commands. It is optional (not required)
+for infrastructure Station (STA) and Soft AP (SAP) modes to function. However,
+it is mandatory for [Wi-Fi Aware](/devices/tech/connect/wifi-aware) and for
+[Wi-Fi RTT](/devices/tech/connect/wifi-rtt) services.
+
+Pre-HIDL (i.e. pre-Android 8.0) Android used a HAL mechanism now called _legacy
+HAL_. The Android source code currently provides a default implementation of
+HIDL using a shim running on top of the legacy HAL.
+
+The legacy HAL headers are located in
+`hardware/libhardware_legacy/include/hardware_legacy/`. The legacy HAL based
+implementation is located in `hardware/interfaces/wifi/1.2/default`.
+
+## Supplicant HAL
+
+The Supplicant HAL provides a HIDL interface for the **wpa_supplicant** daemon.
+
+The wpa_supplicant source code is located in
+`external/wpa_supplicant_8/wpa_supplicant`. The wpa_supplicant code providing
+the HIDL interface is located in the `hidl` sub-directory.
+
+## Hostapd HAL
+
+The Hostapd HAL provides a HIDL interface for the **hostapd** daemon.
+
+The hostapd source code is located in `external/wpa_supplicant_8/hostapd`. The
+hostapd code providing the HIDL interface is located in the `hidl`
+sub-directory.
+
+## Wi-Fi multi-interface concurrency
+
+Different Android devices can support different combinations of Wi-Fi interfaces
+concurrently. The supported combinations are defined in the HAL and are exposed
+to the framework. The specification format is defined in
+`android/hardware/interfaces/wifi/1.0/IWifiChip.hal`. For example, a device may
+support one STA and one interface of either NAN
+([Wi-Fi Aware](https://developer.android.com/guide/topics/connectivity/wifi-aware))
+or P2P
+([Wi-Fi Direct](https://developer.android.com/guide/topics/connectivity/wifip2p))
+type (but not both). This would be expressed as:
+
+`[{STA} <= 1, {NAN,P2P} <= 1]`
+
+The concurrency specification format is flexible and generic. It can express
+combinations that are not yet supported by the framework. The reference HAL has
+configurations for several combinations which may be activated with build flags.
+For configuration instructions, see:
+
++ [Wi-Fi STA/AP Concurrency](/devices/tech/connect/wifi-sta-ap-concurrency)
++ [Wi-Fi Aware](/devices/tech/connect/wifi-aware)
diff --git a/en/devices/tech/connect/wifi-mac-randomization.md b/en/devices/tech/connect/wifi-mac-randomization.md
new file mode 100644
index 0000000..d1f4220
--- /dev/null
+++ b/en/devices/tech/connect/wifi-mac-randomization.md
@@ -0,0 +1,105 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Privacy: MAC Randomization
+
+Starting in Android 8.0, Android devices use random MAC addresses when probing
+for new networks while not currently associated to a network.
+
+In Android {{ androidPVersionNumber }}, a developer option can be enabled (it is
+**disabled** by default) to cause the device to use a randomized MAC address
+when connecting to a Wi-Fi network. A different randomized MAC address is used
+per SSID.
+
+MAC randomization prevents listeners from using MAC addresses to build a history
+of device activity, thus increasing user privacy.
+
+Additionally, MAC addresses are randomized as part of
+[Wi-Fi Aware](/devices/tech/connect/wifi-aware) and
+[Wi-Fi RTT](/devices/tech/connect/wifi-rtt) operations.
+
+## Implementation
+
+To implement MAC randomization on your device:
+
+1. Work with a Wi-Fi chip vendor to implement the
+ `IWifiStaIface.setMacAddress()` HAL method.
+
+ + The AOSP reference implementation brings the interface down, changes the
+ MAC address, and brings the interface back up. This reference
+ implementation behavior may not work with certain chip vendors.
+
+1. Set
+ [`config_wifi_support_connected_mac_randomization`](https://android.googlesource.com/platform/packages/apps/Settings/+/master/res/values/config.xml#46)
+ to **true** in the Settings `config.xml` (this can be done in a device
+ custom overlay).
+
+ + This flag is used to control whether the *Connected MAC Randomization*
+ toggle is shown in the developer option of the reference Settings
+ implementation. If **true**, the toggle is shown; if **false**, the
+ toggle is not shown.
+
+1. Test your implementation using the methods described in
+ [Validation](#validation).
+
+The System UI must:
+
++ Have a setting in the developer menu to enable or disable the feature.
++ Show the random MAC address generated by the system when displaying the
+ Wi-Fi interface MAC address if the MAC randomization feature is enabled.
+
+Use the
+[reference implementation](https://android.googlesource.com/platform/packages/apps/Settings/+/master/src/com/android/settings/development/WifiConnectedMacRandomizationPreferenceController.java)
+of Settings UI to implement new prompts.
+
+## Validation
+
+To validate that the feature is working as intended, run both an integration
+test (ACTS) and a manual test.
+
+To run an integration test, use the ACTS file,
+`WifiConnectedMacRandomizationTest.py`, located in
+`tools/test/connectivity/acts/tests/google/wifi`, to verify if the device uses
+the randomized MAC address and correctly stores the randomized MAC address for
+each network.
+
+To run a manual test:
+
+1. Turn on the feature and verify that the device is able to connect to Wi-Fi
+ networks.
+1. Verify that the MAC address displayed in Wi-Fi settings matches the one that
+ the device is using (from ifconfig).
+1. Verify that the device is using a randomized MAC address (not a factory MAC)
+ by doing packet captures.
+1. Verify that the device stores network-based randomized MAC addresses by
+ checking that it uses the same MAC address whenever connecting to the same
+ network.
+1. Verify that forgetting a network and re-associating to the same SSID
+ generates a new random MAC address.
+
+You may experience up to a three-second delay when connecting to networks since
+scan results are cleared whenever a new MAC address is set. Other delays may
+also occur when connecting to networks and validating internet connectivity.
+
+If the Wi-Fi driver or firmware does not properly synchronize the MAC address
+state with the host kernel, internet connectivity checks will fail. If this
+happens, check with your silicon partners to ensure that the driver or firmware
+has been correctly updated with the new MAC address.
diff --git a/en/devices/tech/connect/wifi-overview.md b/en/devices/tech/connect/wifi-overview.md
new file mode 100644
index 0000000..702fdab
--- /dev/null
+++ b/en/devices/tech/connect/wifi-overview.md
@@ -0,0 +1,73 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Overview
+
+Android provides a default Android framework implementation that includes
+support for various Wi-Fi protocols and modes, including:
+
++ Wi-Fi infrastructure (STA)
++ Wi-Fi hotspot (Soft AP) in either tethered or local-only modes
++ Wi-Fi Direct (p2p)
++ Wi-Fi Aware (NAN)
++ Wi-Fi RTT (IEEE 802.11mc FTM)
+
+An application using Wi-Fi services directly communicates with the various Wi-Fi
+services through Binder. The Wi-Fi services run in the System Service and
+communicate with the HAL over HIDL. This diagram shows the general structure of
+the Android Wi-Fi stack.
+
+
+
+**Figure 1.** Android Wi-Fi architecture
+
+## Application framework
+
+At the application framework level is application code, which uses the various
+[android.net.wifi](https://developer.android.com/reference/android/net/wifi/package-summary)
+APIs to interact with the Wi-Fi framework and hardware. Internally, this code
+calls the Wi-Fi process through the Binder IPC mechanism.
+
+## Wi-Fi services
+
+The Wi-Fi services run in the System Service, and are located in
+`frameworks/opt/net/wifi`. The Wi-Fi service communicates with the Wi-Fi HAL
+over HIDL.
+
+There are various Wi-Fi services:
+
++ Wi-Fi Service: Primary mechanism for controlling Wi-Fi infrastructure modes
+ (both STA and AP).
++ Wi-Fi P2P Service: Manages the Wi-Fi Direct mode.
++ Wi-Fi Aware Service: Manages the Wi-Fi Aware mode.
++ Wi-Fi RTT Service: Manages the IEEE 802.11mc FTM functionality.
+
+The Wi-Fi framework also includes a stand-alone process, **wificond**, located
+at `system/connectivity/wificond`. The **wificond** process communicates with
+the Wi-Fi driver over standard `nl80211` commands.
+
+## Wi-Fi HALs
+
+The Wi-Fi framework has three Wi-Fi HAL surfaces represented by three different
+HIDL packages: Vendor HAL, Supplicant HAL, and Hostapd HAL.
+
+For details about implementations of the various HALs, see
+[Wi-Fi HAL](/devices/tech/connect/wifi-hal).
diff --git a/en/devices/tech/connect/wifi-passpoint.md b/en/devices/tech/connect/wifi-passpoint.md
new file mode 100644
index 0000000..f75a5ad
--- /dev/null
+++ b/en/devices/tech/connect/wifi-passpoint.md
@@ -0,0 +1,216 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Passpoint R1
+
+Android has supported Passpoint R1 since Android 6.0 allowing the provisioning
+of Passpoint R1 (release 1) credentials through web-based downloading of a
+special file that contains profile and credential information. The client
+automatically launches a special installer for the Wi-Fi information and allows
+the user to view parts of the information before accepting or declining the
+content.
+
+The profile information contained in the file is used for matching against data
+retrieved from Passpoint R1 enabled access points, and the credentials are
+automatically applied for any matched network.
+
+The Android reference implementation supports EAP-TTLS, EAP-TLS, EAP-SIM,
+EAP-AKA, and EAP-AKA'.
+
+## Download mechanism
+
+The wifi-config file must be hosted on a web-server and should be protected with
+TLS (HTTPS) since it may contain clear text password or private key data. The
+content is made up of wrapped multi-part MIME text represented in UTF-8 and
+encoded in base64 encoding per RFC-2045 section 6.8.
+
+The following HTTP header fields are used by the client to automatically launch
+a Wi-Fi installer on the device:
+
++ `Content-Type` must be set to `application/x-wifi-config`
++ `Content-Transfer-Encoding` must be set to `base64`
++ `Content-Disposition` must not be set
+
+The HTTP method used to retrieve the file must be GET. Any time an HTTP GET from
+the browser receives a response with these MIME headers, the installation app is
+started. The download must be triggered by tapping on an HTML element such as a
+button (automatic redirects to a download URL are not supported). This behavior
+is specific to Google Chrome; other web browsers may or may not provide similar
+functionality.
+
+## File composition
+
+The base64-encoded content must consist of MIME multipart content with a
+`Content-Type` of `multipart/mixed`. The following parts make up the individual
+parts of the multi-part content:
+
+<table>
+<thead>
+<tr>
+<th><strong>Part</strong></th>
+<th><strong>Content-Type (less quotes)</strong></th>
+<th><strong>Required</strong></th>
+<th><strong>Description</strong></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Profile</td>
+<td><code>
+application/x-passpoint-profile
+</code>
+
+</td>
+<td>Always</td>
+<td>OMA-DM SyncML formatted payload containing the Passpoint R1
+<code>PerProviderSubscription</code> formatted MO for <code>HomeSP</code>
+and <code>Credential</code>.</td>
+</tr>
+<tr>
+<td>Trust certificate</td>
+<td><code>
+application/x-x509-ca-cert
+</code>
+
+</td>
+<td>Optional for EAP-TLS and EAP-TTLS</td>
+<td>A single X.509v3 base64-encoded certificate payload.</td>
+</tr>
+<tr>
+<td>EAP-TLS key</td>
+<td><code>
+application/x-pkcs12
+</code>
+
+</td>
+<td>Required for EAP-TLS</td>
+<td>A base64-encoded PKCS #12 ASN.1 structure containing a client certificate
+chain with at least the client certificate and the associated private key.
+The PKCS 12 container as well as the private key and the certificates must
+all be in clear text with no password.</td>
+</tr>
+</tbody>
+</table>
+
+The Profile section must be transferred as base64-encoded, UTF-8-encoded XML
+text that specifies parts of the `HomeSP` and `Credential` sub-trees in the
+Passpoint R2 Technical Specification Version 1.0.0, section 9.1.
+
+Note: The profile XML format used in Android for Passpoint R1 borrows the
+Passpoint R2 format but isn't necessarily R2 compliant. That is a design choice
+and not a requirement of Passpoint R1.
+
+The top-level node must be `MgmtTree` and the immediate sub-node must be
+`PerProviderSubscription`. An example XML file appears in the Appendix below.
+
+The following sub-tree nodes are used under `HomeSP`:
+
++ `FriendlyName`: Must be set; used as display text
++ `FQDN`: Required
++ `RoamingConsortiumOI`
+
+The following sub-tree nodes are used under `Credential`:
+
++ `Realm`: Must be a non-empty string
++ `UsernamePassword`: Required for EAP-TTLS with the following nodes set:
+
+ + `Username`
+ + `Password`
+ + `EAPMethod/EAPType`: Must be set to `21`
+ + `EAPMethod/InnerMethod`: Must be set to one of `PAP`, `CHAP`, `MS-CHAP`,
+ or `MS-CHAP-V2`
+
++ `DigitalCertificate`: Required for EAP-TLS. The following nodes must be set:
+
+ + `CertificateType` set to `x509v3`
+ + `CertSHA256Fingerprint` set to the correct SHA-256 digest of the client
+ certificate in the EAP-TLS key MIME section.
+
++ `SIM`: Required for EAP-SIM, EAP-AKA and EAP-AKA'. The `EAPType` field must
+ be set to the appropriate EAP type and `IMSI` must match an IMSI of one of
+ the SIM cards installed in the device at the time of provisioning. The IMSI
+ string can either consist entirely of decimal digits to force full equality
+ match, or of zero or more decimal digits followed by an asterisk (\*) to
+ relax the IMSI matching to prefix only. For example, the IMSI string 123\*
+ matches any SIM card with an IMSI starting with 123.
+
+# Example Profile OMA-DM XML
+
+```xml
+<MgmtTree xmlns="syncml:dmddf1.2">
+ <VerDTD>1.2</VerDTD>
+ <Node>
+ <NodeName>PerProviderSubscription</NodeName>
+ <RTProperties>
+ <Type>
+ <DDFName>urn:wfa:mo:hotspot2dot0-perprovidersubscription:1.0</DDFName>
+ </Type>
+ </RTProperties>
+ <Node>
+ <NodeName>i001</NodeName>
+ <Node>
+ <NodeName>HomeSP</NodeName>
+ <Node>
+ <NodeName>FriendlyName</NodeName>
+ <Value>Century House</Value>
+ </Node>
+ <Node>
+ <NodeName>FQDN</NodeName>
+ <Value>mi6.co.uk</Value>
+ </Node>
+ <Node>
+ <NodeName>RoamingConsortiumOI</NodeName>
+ <Value>112233,445566</Value>
+ </Node>
+ </Node>
+ <Node>
+ <NodeName>Credential</NodeName>
+ <Node>
+ <NodeName>Realm</NodeName>
+ <Value>shaken.stirred.com</Value>
+ </Node>
+ <Node>
+ <NodeName>UsernamePassword</NodeName>
+ <Node>
+ <NodeName>Username</NodeName>
+ <Value>james</Value>
+ </Node>
+ <Node>
+ <NodeName>Password</NodeName>
+ <Value>Ym9uZDAwNw==</Value>
+ </Node>
+ <Node>
+ <NodeName>EAPMethod</NodeName>
+ <Node>
+ <NodeName>EAPType</NodeName>
+ <Value>21</Value>
+ </Node>
+ <Node>
+ <NodeName>InnerMethod</NodeName>
+ <Value>MS-CHAP-V2</Value>
+ </Node>
+ </Node>
+ </Node>
+ </Node>
+ </Node>
+ </Node>
+</MgmtTree>
+```
diff --git a/en/devices/tech/connect/wifi-rtt.md b/en/devices/tech/connect/wifi-rtt.md
new file mode 100644
index 0000000..be44df7
--- /dev/null
+++ b/en/devices/tech/connect/wifi-rtt.md
@@ -0,0 +1,158 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Wi-Fi RTT (IEEE 802.11mc)
+
+The [Wi-Fi Round Trip Time (RTT)](https://developer.android.com/guide/topics/connectivity/wifi-rtt) feature in Android
+{{ androidPVersionNumber }} enables supporting devices to measure a
+distance to other supporting devices: whether they are Access Points (APs) or
+Wi-Fi Aware peers (if [Wi-Fi Aware](/devices/tech/connect/wifi-aware) is
+supported on the device). This feature, built upon the IEEE 802.11mc protocol,
+enables apps to use enhanced location accuracy and awareness.
+
+## Examples and source
+
+To use this feature, implement the Wi-Fi Hardware Interface Design Language
+(HIDL) provided in the Android Open Source Project (AOSP). In Android 8.0, HIDL
+replaces the previous Hardware Abstraction Layer (HAL) structure used to
+streamline implementations by specifying types and method calls collected into
+interfaces and packages.
+
+Follow the Wi-Fi HIDL to employ the Wi-Fi RTT feature:
+`hardware/interfaces/wifi/1.0` or later.
+
+You can refer to the legacy Wi-Fi HAL to see how it correlates with the new HIDL
+interface:
+[hardware/libhardware_legacy/+/master/include/hardware_legacy/rtt.h](https://android.googlesource.com/platform/hardware/libhardware_legacy/+/master/include/hardware_legacy/rtt.h).
+
+## Implementation
+
+To implement Wi-Fi RTT, you must provide both framework and HAL/firmware
+support:
+
++ Framework:
+
+ + AOSP code
+ + Enable Wi-Fi RTT: requires a feature flag
+
++ Wi-Fi RTT (IEEE 802.11mc) HAL support (which implies firmware support)
+
+To implement this feature, implement the Wi-Fi HIDL and enable the feature flag:
+
++ In `device.mk` located in `device/<oem>/<device>`, modify the
+ `PRODUCT_COPY_FILES` environment variable to include support for the Wi-Fi
+ RTT feature:
+
+ ```
+ PRODUCT_COPY_FILES += frameworks/native/data/etc/android.hardware.wifi.rtt.xml:$(TARGET_COPY_OUT_VENDOR)/etc/permissions/android.hardware.wifi.rtt.xml
+ ```
+
+Otherwise, everything required for this feature is included in AOSP.
+
+## MAC randomization
+
+To enhance privacy, the MAC address used during Wi-Fi RTT transactions must be randomized, i.e., it must not match the native MAC address of the Wi-Fi interface. However, as an exception, when a device is associated with an AP, it may use the MAC address with which it is associated for any RTT transactions with that AP or with other APs.
+
+## Validation
+
+Android Compatibility Test Suite (CTS) tests exist for this feature. CTS detects
+when the feature is enabled and automatically includes the associated tests. This feature can also be tested using the
+[Vendor Test Suite (VTS)](/devices/tech/test_infra/tradefed/fundamentals/vts)
+and
+[acts/sl4a](https://android.googlesource.com/platform/tools/test/connectivity/+/master/acts/tests/google/wifi/),
+a test suite that conducts extensive integration testing.
+
+### Unit tests
+
+The Wi-Fi RTT package tests are executed using:
+
+Service tests:
+
+```
+% ./frameworks/opt/net/wifi/tests/wifitests/runtests.sh -e package
+com.android.server.wifi.rtt
+```
+
+Manager tests:
+
+```
+% ./frameworks/base/wifi/tests/runtests.sh -e package android.net.wifi.rtt
+```
+
+### Integration (ACTS) tests
+
+The acts/sl4a test suite, described in
+`/tools/test/connectivity/acts/tests/google/wifi/rtt/README.md`, provides
+functional, performance, and stress tests.
+
+### CTS
+
+Android Compatibility Test Suite (CTS) tests exist for this feature. CTS detects
+when the feature is enabled and automatically includes the associated tests. An
+Access Point which supports Wi-Fi RTT (IEEE 802.11mc) must be within range of
+the device-under-test.
+
+The CTS tests can be triggered using:
+
+```
+% atest WifiRttTest
+```
+
+## Calibration
+
+For Wi-Fi RTT to perform well, the ranges returned in the 802.11mc protocol are
+ideally accurate within the Key Performance Indicator (KPI). For the 90% CDF
+error, at the bandwidths listed, the recommended KPI for a range estimate is
+expected to have the following tolerances:
+
++ 80MHz: 2 meter
++ 40MHz: 4 meters
++ 20MHz: 8 meters
+
+To ensure the implementation of the feature is working correctly, calibration
+testing is necessary.
+
+This can be achieved by comparing a ground truth range against the RTT estimated
+range at increasing distances. For basic conformance, you should validate your
+solution against a device known to be RTT calibrated. Range calibration should
+be tested under the following conditions:
+
+1. A large open laboratory, or a corridor that does not have a lot of metal
+ objects that may result in unusually high occurrences of multi-path.
+1. At least a Line-Of-Sight (LOS) track/path extending for 25m.
+1. Markers of 0.5 meter increments from one end of the track to the other.
+1. A place to secure an RTT capable access point at one end of the track
+ mounted 20cm above the floor, and a movable mount for an Android phone (or
+ other Android mobile device under test) that can be moved along the track,
+ and aligned with the 0.5m markers, also at 20cm above the floor. Note: This
+ repetitive task can be performed by a small robot, but a human operator is
+ also fine.
+1. 50 ranging results should be recorded at each marker, along with the distance
+ from the access point. Statistics, such as range mean and variance should be
+ calculated for each marker position.
+
+From the results in step 5, a chart can be drawn for ground truth (x-axis)
+against estimated range (y-axis) and a best fit regression line estimated. Ideal
+device calibration will result in a line of gradient 1.0, with offset 0.0m on
+the y-axis. Deviations from these values are acceptable if they are within the
+KPI for the corresponding bandwidth. If the results are outside of the KPI, the
+device feature should be recalibrated to bring the results within the KPI
+specification.
diff --git a/en/devices/tech/connect/wifi-sta-ap-concurrency.md b/en/devices/tech/connect/wifi-sta-ap-concurrency.md
new file mode 100644
index 0000000..cdf09cd
--- /dev/null
+++ b/en/devices/tech/connect/wifi-sta-ap-concurrency.md
@@ -0,0 +1,76 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Wi-Fi STA/AP concurrency
+
+Android {{ androidPVersionNumber }} introduces the ability for devices to
+operate in STA and AP mode concurrently. For devices supporting Dual Band
+Simultaneous (DBS), this feature opens up new capabilities such as not
+disrupting STA Wi-Fi when a user wants to enable hotspot (softAP).
+
+## Examples and source
+
+Wi-Fi STA/AP concurrency is supported in the default AOSP Android framework
+code. It is also supported by the reference HAL implementation described in
+[Wi-Fi HAL](/devices/tech/connect/wifi-hal). The
+`WIFI_HIDL_FEATURE_DUAL_INTERFACE` build-time flag described in the
+Implementation section below enables an interface concurrency specification
+indicating concurrent support for STA and AP.
+
+## Implementation
+
+To implement Wi-Fi STA/AP concurrency on your device:
+
+1. Turn on a build-time flag to enable support for two interfaces in the HAL.
+ The flag is located in `device/<oem>/<device>/BoardConfig-common.mk`.
+
+ + **WIFI_HIDL_FEATURE_DUAL_INTERFACE := true**
+
+1. Expose two network interfaces:
+
+ + **wlan0** and **wlan1**
+
+Note: To avoid performance issues, only use this feature on devices with a Wi-Fi
+chip that supports multiple independent hardware MACs (radio chains).
+
+## Validation
+
+To validate that the feature is working as intended, run both an integration
+test (ACTS) and a manual test.
+
+The ACTS file, `WifiStaApConcurrencyTest.py`, located in
+`tools/test/connectivity/acts/tests/google/wifi`, contains a set of tests which
+bring up different combinations of STAs and APs.
+
+To manually validate this feature, turn the STA and AP interfaces on and off
+independently from UI.
+
+If both AP and STA are on the same subnet, routing issues on the
+device-under-test (DUT) may occur. To avoid collisions, try moving the AP to a
+different subnet.
+
+Some Wi-Fi chip vendors place the radio in time-sharing mode if STA and AP are
+on the same band but on different channels. This leads to a severe drop in
+performance. To address this issue, the chip can use Channel Switch Avoidance
+(CSA) to either:
+
+* Move the AP to the same channel as the STA
+* Move the AP to a different band from the STA
diff --git a/en/devices/tech/datausage/ebpf-traffic-monitor.md b/en/devices/tech/datausage/ebpf-traffic-monitor.md
new file mode 100644
index 0000000..6d3f613
--- /dev/null
+++ b/en/devices/tech/datausage/ebpf-traffic-monitor.md
@@ -0,0 +1,203 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+<!--
+ Copyright 2018 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.
+-->
+
+{% include "_versions.html" %}
+
+# eBPF Traffic Monitoring
+
+## Introduction {:#introduction}
+
+The eBPF network traffic tool uses a combination of kernel and user space
+implementation to monitor network usage on the device since the last device
+boot. It provides additional functionality such as socket tagging, separating
+foreground/background traffic and per-UID firewall to block apps from network
+access depending on phone state. The statistics gathered from the tool are
+stored in a kernel data structure called `eBPF maps` and the result is used by
+services like `NetworkStatsService` to provide persistent traffic statistics
+since the last boot.
+
+## Examples and source {:#examples-and-source}
+
+The userspace changes are mainly in the `system/netd` and `framework/base`
+projects. Development is being done in AOSP, so AOSP code will always be up to
+date. The source is mainly located at
+[`system/netd/server/TrafficController*`](https://android.googlesource.com/platform/system/netd/+/master/server/TrafficController.cpp){: .external},
+[`system/netd/bpfloader`](https://android.googlesource.com/platform/system/netd/+/master/bpfloader/){: .external}
+and
+[`system/netd/libbpf/`](https://android.googlesource.com/platform/system/netd/+/master/libbpf/){: .external}.
+Some necessary framework changes are in `framework/base/` and `system/core` as
+well.
+
+## Implementation {:#implementation}
+
+Starting with Android {{ androidPVersionNumber }}, Android devices running on
+kernel 4.9 or above and originally shipped with the P release MUST use
+eBPF-based network traffic monitoring accounting instead of `xt_qtaguid`. The
+new infrastructure is more flexible and more maintainable and does not require
+any out-of-tree kernel code.
+
+The major design differences between legacy and eBPF traffic monitoring are
+illustrated in Figure 1.
+
+
+
+**Figure 1.** Legacy (left) and eBPF (right) traffic monitoring design
+differences
+
+The new `trafficController` design is based on per-`cgroup` eBPF filter as well
+as `xt_bpf` netfilter module inside the kernel. These eBPF filters are applied
+on the packet tx/rx when they pass through the filter. The `cgroup` eBPF filter
+is located at the transport layer and is responsible for counting the traffic
+against the right UID depending on the socket UID as well as userspace setting.
+The `xt_bpf` netfilter is hooked at the`bw_raw_PREROUTING` and
+`bw_mangle_POSTROUTING` chain and is responsible for counting traffic against
+the correct interface.
+
+At boot time, the userspace process `trafficController` creates the eBPF maps
+used for data collection and pins all maps as a virtual file at `sys/fs/bpf`.
+Then the privileged process `bpfloader` loads the precompiled eBPF program into
+the kernel and attaches it to the correct `cgroup`. There is a single root
+`cgroup` for all traffic so all the process should be included in that `cgroup`
+by default.
+
+At run time, the `trafficController` can tag/untag a socket by writing to the
+`traffic_cookie_tag_map` and `traffic_uid_counterSet_map`. The
+`NetworkStatsService` can read the traffic stats data from
+`traffic_tag_stats_map`, `traffic_uid_stats_map` and `traffic_iface_stats_map`.
+Besides the traffic stats collection function, the `trafficController` and
+`cgroup` eBPF filter are also responsible for blocking traffic from certain UIDs
+depending on the phone settings. The UID-based networking traffic blocking
+feature is a replacement of the `xt_owner` module inside the kernel and the
+detail mode can be configured by writing to`traffic_powersave_uid_map`,
+`traffic_standby_uid_map` and `traffic_dozable_uid_map`.
+
+The new implementation follows the legacy `xt_qtaguid` module implementation so
+`TrafficController` and `NetworkStatsService` will run with either the legacy or
+new implementation. If the app uses public APIs, it should not experience any
+difference whether `xt_qtaguid` or eBPF tools are used in the background.
+
+If the device kernel is based on the Android common kernel 4.9 (SHA
+39c856663dcc81739e52b02b77d6af259eb838f6 or above), then no modifications to
+HALs, drivers, or kernel code are required to implement the new eBPF tool.
+
+## Requirements {:#requirements}
+
+1. The kernel config MUST have these following configs turned on:
+
+ 1. `CONFIG_CGROUP_BPF=y`
+ 1. `CONFIG_BPF=y`
+ 1. `CONFIG_BPF_SYSCALL=y`
+ 1. `CONFIG_NETFILTER_XT_MATCH_BPF=y`
+
+ The
+ [VTS kernel config test](https://android.googlesource.com/platform/test/vts-testcase/kernel/+/master/config/VtsKernelConfigTest.py){: .external}
+ is helpful when verifying the correct config is turned on.
+
+1. The device `MEM_LOCK` rlimit MUST be set to 8 MB or more.
+
+## Legacy xt_qtaguid deprecation process {:#legacy-xt_qtaguid-deprecation-process}
+
+The new eBPF tool is replacing the`xt_qtaguid` module and the `xt_owner` module
+it is based on. We will start to remove the `xt_qtaguid` module from the Android
+kernel and disable its unnecessary configs.
+
+In the Android {{ androidPVersionNumber }} release, the `xt_qtaguid` module is
+turned on in all devices, but all the public APIs that directly read the
+`xt_qtaguid` module proc file are moved into the `NetworkManagement` Service.
+Depending on the device kernel version and first API level, the
+`NetworkManagement` Service knows whether eBPF tools is turned on and chooses
+the right module to get for each app network usage stat. Apps with SDK level 28
+and higher are blocked from accessing `xt_qtaguid` proc files by sepolicy.
+
+In the next Android release after {{ androidPVersionNumber }}, app access to
+those `xt_qtaguid` proc files will be completely blocked we will start to remove
+the `xt_qtaguid` module from the new Android common kernels. After it is
+removed, we will update the Android base config for that kernel version to
+explicitly turn the `xt_qtaguid` module off. The `xt_qtaguid` module will be
+completely deprecated when the minimum kernel version requirement for an Android
+release is 4.9 or above.
+
+In the Android {{ androidPVersionNumber }} release, only devices that launch
+with the Android {{ androidPVersionNumber }} release are required to have the
+new eBPF feature. For devices that shipped with a kernel that can support eBPF
+tools, we recommend updating it to the new eBPF feature when upgrading to the
+Android {{ androidPVersionNumber }} release. There is no CTS test to enforce
+that update.
+
+## Validation {:#validation}
+
+You should regularly take patches from Android common kernels and Android AOSP
+master. Ensure your implementation passes the applicable VTS and CTS tests, the
+`netd_unit_test`, and the `libbpf_test`.
+
+### Testing {:#testing}
+
+There are
+[kernel net_tests](https://android.googlesource.com/kernel/tests/+/master/net/test/bpf_test.py){: .external}
+to ensure you have the required features turned on and required kernel patches
+backported. The tests are integrated as part of Android {{ androidPVersionNumber }}
+release VTS tests. There are some unit tests in `system/netd/`
+([`netd_unit_test`](https://android.googlesource.com/platform/system/netd/+/master/server/TrafficControllerTest.cpp){: .external}
+and
+[`libbpf_test`](https://android.googlesource.com/platform/system/netd/+/master/libbpf/BpfNetworkStatsTest.cpp){: .external}).
+There are some tests in `netd_integration_test` to validate the overall behavior
+of the new tool.
+
+#### CTS and CTS verifier {:#cts-and-cts-verifier}
+
+Because both traffic monitoring modules are supported in the Android
+{{ androidPVersionNumber }} release, there is no CTS test to force implementing the
+new module on all devices. But for devices with kernel version higher then 4.9
+that originally ship with the Android {{ androidPVersionNumber }} release (i.e.
+the first API level >= 28), there are CTS tests on GSI to validate the new
+module is correctly configured. Old CTS tests such as `TrafficStatsTest`,
+`NetworkUsageStatsTest` and `CtsNativeNetTestCases` can be used to verify the
+behavior to be consistent with old UID module.
+
+#### Manual testing {:#manual-testing}
+
+There are some unit tests in `system/netd/`
+([`netd_unit_test`](https://android.googlesource.com/platform/system/netd/+/master/server/TrafficControllerTest.cpp){: .external},
+[`netd_integration_test`](https://android.googlesource.com/platform/system/netd/+/master/tests/bpf_base_test.cpp){: .external}
+and
+[`libbpf_test`](https://android.googlesource.com/platform/system/netd/+/master/libbpf/BpfNetworkStatsTest.cpp){: .external}).
+There is dumpsys support for manually checking the status. The command
+**`dumpsys netd`** shows the basic status of the `trafficController` module and
+whether eBPF is correctly turned on. If eBPF is turned on, the command
+**`dumpsys netd trafficcontroller`** shows the detailed content of each eBPF
+map, including tagged socket information, stats per tag, UID and iface, and
+owner UID match.
+
+### Test locations {:#test-locations}
+
+CTS tests are located at:
+
+* [https://android.googlesource.com/platform/cts/+/master/tests/tests/net/src/android/net/cts/TrafficStatsTest.java](https://android.googlesource.com/platform/cts/+/master/tests/tests/net/src/android/net/cts/TrafficStatsTest.java)
+ {: .external}
+* [https://android.googlesource.com/platform/cts/+/master/tests/tests/app.usage/src/android/app/usage/cts/NetworkUsageStatsTest.java](https://android.googlesource.com/platform/cts/+/master/tests/tests/app.usage/src/android/app/usage/cts/NetworkUsageStatsTest.java)
+ {: .external}
+* [https://android.googlesource.com/platform/system/netd/+/master/tests/bpf_base_test.cpp](https://android.googlesource.com/platform/system/netd/+/master/tests/bpf_base_test.cpp)
+ {: .external}
+
+VTS tests are located at
+[https://android.googlesource.com/kernel/tests/+/master/net/test/bpf_test.py](https://android.googlesource.com/kernel/tests/+/master/net/test/bpf_test.py){: .external}.
+
+Unit tests are located at:
+
+* [https://android.googlesource.com/platform/system/netd/+/master/libbpf/BpfNetworkStatsTest.cpp](https://android.googlesource.com/platform/system/netd/+/master/libbpf/BpfNetworkStatsTest.cpp)
+ {: .external}
+* [https://android.googlesource.com/platform/system/netd/+/master/server/TrafficControllerTest.cpp](https://android.googlesource.com/platform/system/netd/+/master/server/TrafficControllerTest.cpp)
+ {: .external}
diff --git a/en/devices/tech/datausage/index.html b/en/devices/tech/datausage/index.html
index 2a30853..b33ad8e 100644
--- a/en/devices/tech/datausage/index.html
+++ b/en/devices/tech/datausage/index.html
@@ -22,17 +22,17 @@
-->
-<p>Android 4.0 introduces new features that help
-users understand and control how their device uses network data. It
-monitors overall data usage, and supports warning or limit thresholds
-which will trigger notifications or disable mobile data when usage
+<p>Android helps users understand and control how their devices use network data.
+It monitors overall data usage and supports warning or limit thresholds
+that trigger notifications or disable mobile data when usage
exceeds a specific quota.</p>
<p>Data usage is also tracked on a per-application basis, enabling users
-to visually explore historical usage in the Settings app. Users can
+to visually explore historical usage in the <a
+href="/devices/tech/settings/settings-guidelines">Settings</a> app. Users can
also restrict how specific applications are allowed to use data when
running in the background.</p>
<p>The documentation in this section is intended for systems integrators
-and mobile operators, to help explain technical details they should be
+and mobile operators to help explain technical details they should be
aware of when porting Android to specific devices. These details are
summarized below, and the
<a href="mailto:android-porting+subscribe@googlegroups.com">android-porting</a>
diff --git a/en/devices/tech/datausage/kernel-changes.html b/en/devices/tech/datausage/kernel-changes.html
index 7a32b72..dd14d83 100644
--- a/en/devices/tech/datausage/kernel-changes.html
+++ b/en/devices/tech/datausage/kernel-changes.html
@@ -5,6 +5,7 @@
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
+ {% include "_versions.html" %}
<!--
Copyright 2017 The Android Open Source Project
@@ -33,6 +34,8 @@
<p>A few comments on the kernel configuration:</p>
<ul>
<li>xt_qtaguid masquerades as xt_owner and relies on xt_socket and itself relies on the connection tracker.</li>
+<li>Support for xt_qtaguid will be phased out starting in the Android {{ androidPVersionNumber }}
+release. See <a href="ebpf-traffic-monitor">eBPF Traffic Monitoring</a> for more information.
<li>The connection tracker can't handle large SIP packets, it must be disabled.</li>
<li>The modified xt_quota2 uses the NFLOG support to notify userspace.</li>
</ul>
diff --git a/en/devices/tech/datausage/kernel-overview.html b/en/devices/tech/datausage/kernel-overview.html
index 8856b74..3a5027d 100644
--- a/en/devices/tech/datausage/kernel-overview.html
+++ b/en/devices/tech/datausage/kernel-overview.html
@@ -5,6 +5,7 @@
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
+ {% include "_versions.html" %}
<!--
Copyright 2017 The Android Open Source Project
@@ -28,6 +29,11 @@
functionality in the framework (<code>system/core/libcutils/qtaguid.c</code>)
relies mainly on the existence of <code>/proc/net/xt_qtaguid/ctrl</code>
interface exported by the <code>xt_qtaguid</code> kernel module.</p>
+
+<aside class="note"><b>Note:</b> Support for <code>xt_qtaguid</code> will be phased out starting in
+the Android {{ androidPVersionNumber }} release. See <a href="ebpf-traffic-monitor">eBPF Traffic
+Monitoring</a> for more information.</aside>
+
<p>The <code>quota2</code> netfilter module (originally part of <code>xtables-addons</code>)
allows the functionality to set named quota limits and was extended to
support notifying userspace when certain limits are reached. Once the
diff --git a/en/devices/tech/debug/cfi.html b/en/devices/tech/debug/cfi.html
new file mode 100644
index 0000000..7fd4825
--- /dev/null
+++ b/en/devices/tech/debug/cfi.html
@@ -0,0 +1,195 @@
+<html devsite>
+ <head>
+ <title>Control Flow Integrity</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ <body>
+ <!--
+ Copyright 2018 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
+
+ //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>
+As of 2016, about 86% of all vulnerabilities on Android are memory safety
+related. Most vulnerabilities are exploited by attackers changing the normal
+control flow of an application to perform arbitrary malicious activities with
+all the privileges of the exploited application.
+<a href="https://clang.llvm.org/docs/ControlFlowIntegrity.html">Control flow
+integrity</a> (CFI) is a security mechanism that disallows changes to the
+original control flow graph of a compiled binary, making it significantly harder
+to perform such attacks.
+</p>
+<p>
+In Android 8.1, we enabled LLVM's implementation of CFI in the media stack. In
+Android 9, we enabled CFI in more components and also the kernel. System CFI is
+on by default but you need to enable kernel CFI.
+</p>
+<p>
+LLVM's CFI requires compiling with
+<a href="https://llvm.org/docs/LinkTimeOptimization.html">Link-Time Optimization
+(LTO)</a>. LTO preserves the LLVM bitcode representation of object files until
+link-time, which allows the compiler to better reason about what optimizations
+can be performed. Enabling LTO reduces the size of the final binary and improves
+performance, but increases compile time. In testing on Android, the combination
+of LTO and CFI results in negligible overhead to code size and performance; in a
+few cases both improved.
+</p>
+<p>
+For more technical details about CFI and how other forward-control checks are
+handled, see the <a
+href="https://clang.llvm.org/docs/ControlFlowIntegrityDesign.html">LLVM design
+documentation</a>.
+</p>
+
+<h2 id="examples">Examples and source</h2>
+<p>
+CFI is provided by the compiler and adds instrumentation into the binary during
+compile time. We support CFI in the Clang toolchain and the Android build system
+in AOSP.
+</p>
+<p>
+CFI is enabled by default for Arm64 devices for the set of components in
+<code><a
+href="https://android.googlesource.com/platform/build/+/master/target/product/cfi-common.mk">/platform/build/target/product/cfi-common.mk</a></code>.
+It's also directly enabled in a set of media components' makefiles/blueprint
+files, such as <code><a
+href="https://android.googlesource.com/platform/frameworks/av/+/master/media/libmedia/Android.bp#117">/platform/frameworks/av/media/libmedia/Android.bp</a></code>
+and <code><a
+href="https://android.googlesource.com/platform/frameworks/av/+/master/cmds/stagefright/Android.mk#188">/platform/frameworks/av/cmds/stagefright/Android.mk</a></code>.
+
+<h2 id="system-cfi">Implementing system CFI</h2>
+<p>
+CFI is enabled by default if you use Clang and the Android build system.
+Because CFI helps keep Android users safe, you should not disable it.
+</p>
+<p>
+In fact, we strongly encourage you to enable CFI for additional components.
+Ideal candidates are privileged native code, or native code that processes
+untrusted user input. If you're using clang and the Android build system, you
+can enable CFI in new components by adding a few lines to your makefiles or
+blueprint files.
+</p>
+
+<h3 id="cf-in-mk">Supporting CFI in makefiles</h3>
+<p>
+To enable CFI in a make file, such as <code><a
+href="https://android.googlesource.com/platform/frameworks/av/+/master/cmds/stagefright/Android.mk#188">/platform/frameworks/av/cmds/stagefright/Android.mk</a></code>,
+add:
+
+
+
+<pre
+class="prettyprint">LOCAL_SANITIZE := cfi
+# Optional features
+LOCAL_SANITIZE_DIAG := cfi
+LOCAL_SANITIZE_BLACKLIST := cfi_blacklist.txt</pre>
+<ul>
+ <li><code>LOCAL_SANITIZE</code> specifies CFI as the sanitizer during the
+ build.</li>
+ <li><code>LOCAL_SANITIZE_DIAG</code> turns on diagnostic mode for CFI.
+ Diagnostic mode prints out additional debug information in logcat during
+ crashes, which is useful while developing and testing your builds. Make
+ sure to remove diagnostic mode on productions builds, though.</li>
+ <li><code>LOCAL_SANITIZE_BLACKLIST</code> allows components to selectively
+ disable CFI instrumentation for individual functions or source files. You
+ can use a blacklist as a last resort to fix any user-facing issues that
+ might otherwise exist. For more details, see
+ <a href="#disabling-cfi">Disabling CFI</a>.</li>
+</ul>
+<h3 id="cfi-in-bp">Supporting CFI in blueprint files</h3>
+<p>
+To enable CFI in a blueprint file, such as <code><a
+href="https://android.googlesource.com/platform/frameworks/av/+/master/media/libmedia/Android.bp#117">/platform/frameworks/av/media/libmedia/Android.bp</a></code>,
+add:</p>
+
+
+
+<pre class="prettyprint"> sanitize: {
+ cfi: true,
+ diag: {
+ cfi: true,
+ },
+ blacklist: "cfi_blacklist.txt",
+ },</pre>
+
+<h3 id="troubleshooting">Troubleshooting</h3>
+<p>
+If you're enabling CFI in new components, you may run into a few issues with
+<em>function type mismatch errors</em> and <em>assembly code type mismatch
+errors</em>.
+</p>
+<p>
+Function type mismatch errors occur because CFI restricts indirect calls to only
+jump to functions that have the same dynamic type as the static type used in the
+call. CFI restricts virtual and non-virtual member function calls to only jump
+to objects that are a derived class of the static type of the object used to
+make the call. This means, when you have code that violates either of these
+assumptions, the instrumentation that CFI adds will abort. For example, the
+stack trace shows a SIGABRT and logcat contains a line about control flow
+integrity finding a mismatch.
+</p>
+<p>
+To fix this, ensure that the called function has the same type that was
+statically declared. Here are two example CLs:
+</p>
+<ul>
+<li><strong>Bluetooth</strong>:
+<a href="https://android-review.googlesource.com/c/platform/system/bt/+/532377">/c/platform/system/bt/+/532377</a></li>
+<li><strong>NFC</strong>:
+<a href="https://android-review.googlesource.com/c/platform/system/nfc/+/527858">/c/platform/system/nfc/+/527858</a></li>
+</ul>
+<p>
+Another possible issue is trying to enable CFI in code that contains indirect
+calls to assembly. Because assembly code is not typed, this results in a type
+mismatch.
+</p>
+<p>
+To fix this, create native code wrappers for each assembly call, and give the
+wrappers the same function signature as the calling poiner. The wrapper can then
+directly call the assembly code. Because direct branches are not instrumented by
+CFI (they cannot be repointed at runtime and so do not pose a security risk),
+this will fix the issue.
+</p>
+<p>
+If there are too many assembly functions and they cannot all be fixed, you can
+also blacklist all functions that contain indirect calls to assembly. This is
+not recommended as it disables CFI checks on these functions, thereby opening
+attack surface.
+</p>
+<h3 id="disabling-cfi">Disabling CFI</h3>
+<p>
+We didn't observe any performance overhead, so you shouldn't need to disable
+CFI. However, if there is a user-facing impact, you can selectively disable CFI
+for individual functions or source files by supplying a sanitizer blacklist file
+at compile time. The blacklist instructs the compiler to disable CFI
+instrumentation in specified locations.
+</p>
+<p>
+The Android build system provides support for per-component blacklists (allowing
+you to choose source files or individual functions that will not receive CFI
+instrumentation) for both Make and Soong. For more details on the format of a
+blacklist file, see the <a
+href="https://clang.llvm.org/docs/ControlFlowIntegrity.html#blacklist">upstream
+Clang docs</a>.
+</p>
+
+<h2 id="validation">Validation</h2>
+<p>
+Currently, there are no CTS test specifically for CFI. Instead, make sure that
+CTS tests pass with or without CFI enabled to verify that CFI isn't impacting
+the device.
+</p>
+</body>
+</html>
diff --git a/en/devices/tech/debug/fuzz-sanitize.html b/en/devices/tech/debug/fuzz-sanitize.html
index d1076e7..55c517d 100644
--- a/en/devices/tech/debug/fuzz-sanitize.html
+++ b/en/devices/tech/debug/fuzz-sanitize.html
@@ -1,6 +1,6 @@
<html devsite>
<head>
- <title>Fuzzing and sanitizers</title>
+ <title>Dynamic Analysis</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
@@ -20,24 +20,15 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<p>
-Fuzzing, which is simply providing potentially invalid, unexpected, or random
-data as an input to a program, is an extremely effective way of finding bugs in
-large software systems, and is an important part of the software development
-lifecycle.
-</p>
-<p>
-LLVM, the compiler infrastructure used to build Android, contains multiple
-components that perform static and dynamic analysis. Of these components, the
-sanitizers can be used to push out bugs and make Android better.
-</p>
+
+ <p>This section summarizes useful tools for dynamic analysis and debugging
+ from a security perspective. It covers some tools for fuzzing, sanitizing,
+ and preemptively mitigating exploits. For general debugging, see
+ <a href="/devices/tech/debug/">the debugging section</a>.</p>
+
<p>
While Android has supported fuzzing tools for many releases, Android 8.0
-includes more fuzzing support, tighter fuzzing tool integration in the Android
-build system, and greater dynamic analysis support on the Android kernels.
-</p>
-<p>
-This section includes information on how to set up and use various fuzzing and
-sanitizing tools.
+and later include more fuzzing support, tighter fuzzing tool integration in the
+Android build system, and greater dynamic analysis support on the Android kernels.
</p>
</body></html>
diff --git a/en/devices/tech/debug/intsan.html b/en/devices/tech/debug/intsan.html
new file mode 100644
index 0000000..98bc653
--- /dev/null
+++ b/en/devices/tech/debug/intsan.html
@@ -0,0 +1,255 @@
+<html devsite>
+ <head>
+ <title>Integer Overflow Sanitization</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ <body>
+ <!--
+ Copyright 2018 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
+
+ //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>
+Unintended integer overflows can cause memory corruption or information
+disclosure vulnerabilities in variables associated with memory accesses or
+memory allocations. To combat this, we added Clang's
+<a href="https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html">UndefinedBehaviorSanitizer</a>
+(UBSan) signed and unsigned integer overflow sanitizers to
+<a href="https://android-developers.googleblog.com/2016/05/hardening-media-stack.html">harden
+the media framework</a> in Android 7.0. In Android 9, we
+<a href="https://android-developers.googleblog.com/2018/06/compiler-based-security-mitigations-in.html">expanded
+UBSan to cover more components</a> and improved build system support for it.
+</p>
+<p>
+If a signed or unsigned integer overflows, overflow sanitization is designed to
+safely abort process execution by instrumenting arithmetic instructions which
+may overflow. These sanitizers can mitigate an entire class of memory corruption
+and information disclosure vulnerabilities where the root cause is an integer
+overflow, such as the original Stagefright vulnerability.
+</p>
+<h2 id="examples-and-source">Examples and source</h2>
+<p>
+Integer Overflow Sanitization (IntSan) is provided by the compiler and adds
+instrumentation into the binary during compile time to detect arithmetic
+overflows. It is enabled by default in various components throughout the
+platform, for example
+<a href="https://android.googlesource.com/platform/external/libnl/+/master/Android.bp#64"><code>/platform/external/libnl/Android.bp</code></a>.
+</p>
+
+<h2 id="implementation">Implementation</h2>
+<p>
+IntSan uses UBSan's signed and unsigned integer overflow sanitizers. This
+mitigation is enabled on a per-module level. It helps keep critical components
+of Android secure and should not be disabled.
+</p>
+<p>
+We strongly encourage you to enable Integer Overflow Sanitization for additional
+components. Ideal candidates are privileged native code or native code that
+parses untrusted user input. There is a small performance overhead associated
+with the sanitizer that is dependent on code's usage and the prevalence of
+arithmetic operations. Expect a small overhead percentage and test if
+performance is a concern.
+</p>
+<h3 id="intsan-in-makefiles">Supporting IntSan in makefiles</h3>
+<p>
+To enable IntSan in a makefile, add:
+</p>
+
+<pre class="prettyprint">LOCAL_SANITIZE := integer_overflow
+# Optional features
+LOCAL_SANITIZE_DIAG := integer_overflow
+LOCAL_SANITIZE_BLACKLIST := modulename_blacklist.txt</pre>
+<ul>
+ <li><code>LOCAL_SANITIZE</code> takes a comma separated list of sanitizers,
+ with <code>integer_overflow</code> being a pre-packaged set of options for
+ the individual signed and unsigned integer overflow sanitizers with a
+ <a href="https://android.googlesource.com/platform/build/soong/+/master/cc/config/integer_overflow_blacklist.txt">default
+ blacklist</a>.</li>
+ <li><code>LOCAL_SANITIZE_DIAG</code> turns on diagnostics mode for the
+ sanitizers. Use diagnostics mode only during testing because this will not
+ abort on overflows, completely negating the security advantage of the
+ mitigation. See <a href="#troubleshooting">Troubleshooting</a>
+ for additional details.</li>
+ <li><code>LOCAL_SANITIZE_BLACKLIST</code> allows you to specify a blacklist
+ file to prevent functions and source files from being sanitized. See
+ <a href="#troubleshooting">Troubleshooting</a> for additional
+ details.</li>
+</ul>
+<p>
+If you want more granular control, enable the sanitizers individually using one
+or both flags:
+</p>
+
+<pre class="prettyprint">LOCAL_SANITIZE := signed-integer-overflow, unsigned-integer-overflow
+LOCAL_SANITIZE_DIAG := signed-integer-overflow, unsigned-integer-overflow</pre>
+
+<aside class="caution"><strong>Caution</strong>: The individual sanitizers <strong>must</strong>
+be specified as above for static binaries/libraries; the
+<code>integer_overflow</code> flag does not support static binaries/libraries.
+Use both signed and unsigned sanitizers when specifying individually.</aside>
+
+<h3 id="intsan-in-bp">Supporting IntSan in blueprint files</h3>
+<p>
+To enable integer overflow sanitization in a blueprint file, such as
+<a href="https://android.googlesource.com/platform/external/libnl/+/master/Android.bp#64"><code>/platform/external/libnl/Android.bp</code></a>,
+add:
+</p>
+
+
+<pre class="prettyprint"> sanitize: {
+ integer_overflow: true,
+ diag: {
+ integer_overflow: true,
+ },
+ blacklist: "modulename_blacklist.txt",
+ },</pre>
+<p>
+As with make files, the <code>integer_overflow</code> property is a pre-packaged
+set of options for the individual signed and unsigned integer overflow
+sanitizers with a <a
+href="https://android.googlesource.com/platform/build/soong/+/master/cc/config/integer_overflow_blacklist.txt">default
+blacklist</a>.
+</p>
+<p>
+The <code>diag</code> set of properties enables diagnostics mode for the
+sanitizers. Use diagnostics mode only during testing. Diagnostics mode doesn't
+abort on overflows, which completely negates the security advantage of the
+mitigation in user builds. See <a
+href="#troubleshooting">Troubleshooting</a> for additional details.
+</p>
+<p>
+The <code>blacklist</code> property allows specification of a blacklist file
+that allows developers to prevent functions and source files from being
+sanitized. See <a href="#troubleshooting">Troubleshooting</a> for
+additional details.
+</p>
+<p>
+To enable the sanitizers individually, use:
+</p>
+
+<pre class="prettyprint"> sanitize: {
+ misc_undefined: ["signed-integer-overflow", "unsigned-integer-overflow"],
+ diag: {
+ misc_undefined: ["signed-integer-overflow",
+ "unsigned-integer-overflow",],
+ },
+ blacklist: "modulename_blacklist.txt",
+ },</pre>
+<aside class="caution"><strong>Caution</strong>: The individual sanitizers <strong>must</strong>
+be specified as above for static binaries/libraries in Android 9; the
+<code>integer_overflow</code> flag does not support static binaries/libraries.
+Use both signed and unsigned sanitizers when specifying individually.</aside>
+
+<h3 id="troubleshooting">Troubleshooting</h3>
+<p>
+If you are enabling integer overflow sanitization in new components, or rely on
+platform libraries that have had integer overflow sanitization, you may run into
+a few issues with benign integer overflows causing aborts. You should test
+components with sanitization enabled to ensure benign overflows can be surfaced.
+</p>
+<p>
+To find, aborts caused by sanitization in user builds, search for
+<code>SIGABRT</code> crashes with Abort messages indicating an overflow caught
+by UBSan, such as:
+</p>
+
+
+<pre
+class="prettyprint">pid: ###, tid: ###, name: Binder:### >>> /system/bin/surfaceflinger <<<
+signal 6 (SIGABRT), code -6 (SI_TKILL), fault addr --------
+Abort message: 'ubsan: sub-overflow'</pre>
+
+<p>
+The stack trace should include the function causing the abort, however,
+overflows that occur in inline functions may not be evident in the stack trace.
+</p>
+<p>
+To more easily determine the root cause, enable diagnostics in the library
+triggering the abort and attempt to reproduce the error. <strong>With
+diagnostics enabled, the process will not abort</strong> and will instead
+continue to run. Not aborting helps maximize the number of benign overflows in a
+particular execution path without having to recompile after fixing each bug.
+Diagnostics produces an error message which includes the line number and source
+file causing the abort:
+</p>
+
+
+<pre
+class="prettyprint">frameworks/native/services/surfaceflinger/SurfaceFlinger.cpp:2188:32: runtime error: unsigned integer overflow: 0 - 1 cannot be represented in type 'size_t' (aka 'unsigned long')</pre>
+<p>
+Once the problematic arithmetic operation is located, ensure that the overflow
+is benign and intended (e.g. has no security implications). You can address the
+sanitizer abort by:
+</p>
+<ul>
+<li>Refactoring the code to avoid the overflow (<a
+href="https://android-review.googlesource.com/c/platform/frameworks/av/+/572808">example</a>)
+<li>Overflow explicitly via Clang's <a
+href="https://clang.llvm.org/docs/LanguageExtensions.html#checked-arithmetic-builtins">__builtin_*_overflow</a>
+functions (<a
+href="https://android-review.googlesource.com/c/platform/frameworks/av/+/588160">example</a>)
+<li>Disabling sanitization the function via an attribute (<a
+href="https://android-review.googlesource.com/c/platform/frameworks/base/+/531720">example</a>)
+<li>Disabling sanitization of a function or source file via a blacklist file (<a
+href="https://android-review.googlesource.com/c/platform/frameworks/base/+/574222">example</a>)</li></ul>
+<p>
+You should use the most granular solution possible. For example, a large
+function with many arithmetic operations and a single overflowing operation
+should have the single operation refactored rather than the entire function
+blacklisted.
+</p>
+<p>
+Common patterns that may result in benign overflows include:
+</p><ul>
+<li>Implicit casts where an unsigned overflow occurs before being cast to a
+signed type (<a
+href="https://android-review.googlesource.com/c/platform/frameworks/av/+/574011">example</a>)
+<li>Linked list deletions which decrements the loop index on deletion (<a
+href="https://android-review.googlesource.com/c/platform/frameworks/base/+/588158">example</a>)
+<li>Assigning an unsigned type to -1 as shorthand for the max value (<a
+href="https://android-review.googlesource.com/c/platform/frameworks/native/+/574088/1/services/surfaceflinger/Layer.cpp">example</a>)
+<li>Loops which decrement an unsigned integer in the condition (<a
+href="https://android-review.googlesource.com/c/platform/frameworks/native/+/573763/1/services/inputflinger/InputReader.cpp">example</a>,
+<a
+href="https://android-review.googlesource.com/c/platform/frameworks/rs/+/572756">example</a>)</li></ul>
+<p>
+It is recommended that developers assure that cases where the sanitizer detects
+an overflow that it is indeed benign with no unintended side-effects or security
+implications before disabling sanitization.
+</p>
+<h3 id="disabling-intsan">Disabling IntSan</h3>
+<p>
+You can disable IntSan with blacklists or function attributes. Disable sparingly
+and only when refactoring the code is otherwise unreasonable or if there is
+problematic performance overhead.
+</p>
+<p>
+See the upstream Clang documentation for more information on disabling IntSan
+with <a
+href="https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html#disabling-instrumentation-with-attribute-no-sanitize-undefined">function
+attributes</a> and <a
+href="https://clang.llvm.org/docs/SanitizerSpecialCaseList.html">blacklist file
+formatting</a>. Blacklisting should be scoped to the particular sanitizer by
+using section names specifying the target sanitizer to avoid impacting other
+sanitizers.
+</p>
+<h2 id="validation">Validation</h2>
+<p>
+Currently, there are no CTS test specifically for Integer Overflow Sanitization.
+Instead, make sure that CTS tests pass with or without IntSan enabled to verify
+that it is not impacting the device.
+</p>
+</body>
+</html>
diff --git a/en/devices/tech/debug/kcfi.html b/en/devices/tech/debug/kcfi.html
new file mode 100644
index 0000000..0fe7cf0
--- /dev/null
+++ b/en/devices/tech/debug/kcfi.html
@@ -0,0 +1,106 @@
+<html devsite>
+ <head>
+ <title>Kernel Control Flow Integrity</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ <body>
+ <!--
+ Copyright 2018 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
+
+ //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 href="https://clang.llvm.org/docs/ControlFlowIntegrity.html">Control flow
+integrity</a> (CFI) is a security mechanism that disallows changes to the
+original control flow graph of a compiled binary, making it significantly harder
+to perform such attacks.
+</p>
+<p>
+In Android 9, we enabled LLVM's implementation of CFI in more components and
+also in the kernel. <a href="/devices/tech/debug/cfi">System CFI</a> is on by
+default, but you need to enable kernel CFI.
+</p>
+<p>
+LLVM's CFI requires compiling with <a
+href="https://llvm.org/docs/LinkTimeOptimization.html">Link-Time Optimization
+(LTO)</a>. LTO preserves the LLVM bitcode representation of object files until
+link-time, which allows the compiler to better reason about what optimizations
+can be performed. Enabling LTO reduces the size of the final binary and improves
+performance, but increases compile time. In testing on Android, the combination
+of LTO and CFI results in negligible overhead to code size and performance; in a
+few cases both improved.
+</p>
+<p>
+For more technical details about CFI and how other forward-control checks are
+handled, see the <a
+href="https://clang.llvm.org/docs/ControlFlowIntegrityDesign.html">LLVM design
+documentation</a>.
+</p>
+<h2 id="implementation">Implementation</h2>
+<p>
+Support for kernel CFI exists in Android common kernel versions 4.9 and 4.14. If
+your kernel is based on version 4.9 or 4.14 and you build with Clang, then you
+can enable it. To enable kCFI, you need to copy over the relevant patches and
+update your kernel config file.
+</p>
+<h3 id="copy-kcfi-patches">Copy kCFI patches</h3>
+<p>
+Add these changes to your kernel:
+</p>
+<ul>
+<li><a
+href="https://android-review.googlesource.com/q/topic:android-4.9-cfi">Version
+4.9</a></li>
+<li><a
+href="https://android-review.googlesource.com/q/topic:android-4.14-cfi">Version
+4.14</a></li>
+</ul>
+
+<h3 id="enable-kcfi">Enable kCFI</h3>
+<p>
+After you've copied over the relevant changes, you need to enable the kCFI in
+your kernel config file, such as
+<code>/kernel/<var>PROJECT</var>/+/<var>BRANCH</var>/arch/arm64/configs/<var>PROJECT</var>_defconfig</code>.
+</p>
+<p>
+To enable kCFI, add these lines:
+</p>
+
+<pre class="prettyprint">CONFIG_LTO_CLANG=y
+CONFIG_CFI_CLANG=y</pre>
+
+
+<h3 id="troubleshooting">Troubleshooting</h3>
+<p>
+After enabling, work through any type mismatch errors that may exist with their
+drivers. An indirect function call through an incompatible function pointer
+trips CFI. When a CFI failure is detected, the kernel prints out a warning that
+includes both the function that was called and the stacktrace that led to the
+failure. Correct this by ensuring function pointers always have the same type as
+the function that's called.
+</p>
+<p>
+To assist in debugging CFI failures, enable <code>CONFIG_CFI_PERMISSIVE</code>,
+which prints out a warning instead of causing a kernel panic. Permissive mode
+must not be used in production.
+</p>
+
+<h2 id="validation">Validation</h2>
+<p>
+Currently, there are no CTS test specifically for CFI. Instead, make sure that
+CTS tests pass with or without CFI enabled to verify that CFI isn't impacting
+the device.
+</p>
+</body>
+</html>
diff --git a/en/devices/tech/debug/native-crash.html b/en/devices/tech/debug/native-crash.html
index fbebb93..32725ba 100644
--- a/en/devices/tech/debug/native-crash.html
+++ b/en/devices/tech/debug/native-crash.html
@@ -21,56 +21,58 @@
limitations under the License.
-->
-
-
<p>
-If you've never seen a native crash before, start with
-<a href="/devices/tech/debug/index.html">Debugging Native Android
-Platform Code</a>.
+ The following sections include common types of native crash, an analysis of a
+ sample crash dump, and a discussion of tombstones. Each crash type includes
+ example <code>debuggerd</code> output with key evidence highlighted to help
+ you distinguish the specific kind of crash.
</p>
-<h2 id=crashtypes>Types of native crash</h2>
-<p>
-The sections below detail the most common kinds of native crash. Each includes
-an example chunk of <code>debuggerd</code> output, with the key evidence that helps you
-distinguish that specific kind of crash highlighted in orange italic text.
-</p>
-<h3 id=abort>Abort</h3>
-<p>
-Aborts are interesting because they're deliberate. There are many different ways
-to abort (including calling <code><a
-href="http://man7.org/linux/man-pages/man3/abort.3.html">abort(3)</a></code>,
-failing an <code><a
-href="http://man7.org/linux/man-pages/man3/assert.3.html">assert(3)</a></code>,
-using one of the Android-specific fatal logging types), but they all involve
-calling <code>abort</code>. A call to <code>abort</code> basically signals the
-calling thread with SIGABRT, so a frame showing "abort" in <code>libc.so</code>
-plus SIGABRT are the things to look for in the <code>debuggerd</code> output to
-recognize this case.</p>
+<aside class=tip>
+ <strong>Tip:</strong> If you've never seen a native crash before, start with
+ <a href="/devices/tech/debug/index.html">Debugging Native Android Platform
+ Code</a>.
+</aside>
+
+<h2 id=abort>Abort</h2>
<p>
-As mentioned above, there may be an explicit "abort message" line. You
-should also look in the <code>logcat</code> output to see what this thread logged before
-deliberately killing itself, because unlike assert(3) or high level fatal logging
-facilities, abort(3) doesn't accept a message.
+ Aborts are interesting because they are deliberate. There are many different
+ ways to abort (including calling
+ <code><a href="http://man7.org/linux/man-pages/man3/abort.3.html" class="external">abort(3)</a></code>,
+ failing an
+ <code><a href="http://man7.org/linux/man-pages/man3/assert.3.html" class="external">assert(3)</a></code>,
+ using one of the Android-specific fatal logging types), but all involve
+ calling <code>abort</code>. A call to <code>abort</code> signals the calling
+ thread with SIGABRT, so a frame showing "abort" in <code>libc.so</code> plus
+ SIGABRT are the things to look for in the <code>debuggerd</code> output to
+ recognize this case.
</p>
<p>
-Current versions of Android inline the <code><a
-href="http://man7.org/linux/man-pages/man2/tgkill.2.html">tgkill(2)</a></code>
-system call, so their stacks are the easiest to read, with the call to abort(3)
-at the very top:
+ There may be an explicit "abort message" line. You should also look in the
+ <code>logcat</code> output to see what this thread logged before deliberately
+ killing itself, because unlike <code>assert(3)</code> or high level fatal
+ logging facilities, <code>abort(3)</code> doesn't accept a message.
</p>
+
+<p>
+ Current versions of Android inline the
+ <code><a href="http://man7.org/linux/man-pages/man2/tgkill.2.html" class="external">tgkill(2)</a></code>
+ system call, so their stacks are the easiest to read, with the call to
+ abort(3) at the very top:
+</p>
+
<pre class="devsite-click-to-copy">
pid: 4637, tid: 4637, name: crasher >>> crasher <<<
-signal 6 (<i style="color:Orange">SIGABRT</i>), code -6 (SI_TKILL), fault addr --------
-<i style="color:Orange">Abort message</i>: 'some_file.c:123: some_function: assertion "false" failed'
+signal 6 (<em style="color:Orange">SIGABRT</em>), code -6 (SI_TKILL), fault addr --------
+<em style="color:Orange">Abort message</em>: 'some_file.c:123: some_function: assertion "false" failed'
r0 00000000 r1 0000121d r2 00000006 r3 00000008
r4 0000121d r5 0000121d r6 ffb44a1c r7 0000010c
r8 00000000 r9 00000000 r10 00000000 r11 00000000
ip ffb44c20 sp ffb44a08 lr eace2b0b pc eace2b16
backtrace:
- #00 pc 0001cb16 /system/lib/<i style="color:Orange">libc.so</i> (<i style="color:Orange">abort</i>+57)
+ #00 pc 0001cb16 /system/lib/<em style="color:Orange">libc.so</em> (<em style="color:Orange">abort</em>+57)
#01 pc 0001cd8f /system/lib/libc.so (__assert2+22)
#02 pc 00001531 /system/bin/crasher (do_action+764)
#03 pc 00002301 /system/bin/crasher (main+68)
@@ -79,15 +81,17 @@
</pre>
<p>
-Older versions of Android followed a convoluted path between the original abort call (frame 4 here)
-and the actual sending of the signal (frame 0 here). This was especially true on 32-bit ARM,
-which added <code>__libc_android_abort</code> (frame 3 here) to the other platforms' sequence of
-<code>raise</code>/<code>pthread_kill</code>/<code>tgkill</code>:
+ Older versions of Android followed a convoluted path between the original
+ abort call (frame 4 here) and the actual sending of the signal (frame 0 here).
+ This was especially true on 32-bit ARM, which added
+ <code>__libc_android_abort</code> (frame 3 here) to the other platforms'
+ sequence of <code>raise</code>/<code>pthread_kill</code>/<code>tgkill</code>:
</p>
+
<pre class="devsite-click-to-copy">
pid: 1656, tid: 1656, name: crasher >>> crasher <<<
-signal 6 (<i style="color:Orange">SIGABRT</i>), code -6 (SI_TKILL), fault addr --------
-<i style="color:Orange">Abort message</i>: 'some_file.c:123: some_function: assertion "false" failed'
+signal 6 (<em style="color:Orange">SIGABRT</em>), code -6 (SI_TKILL), fault addr --------
+<em style="color:Orange">Abort message</em>: 'some_file.c:123: some_function: assertion "false" failed'
r0 00000000 r1 00000678 r2 00000006 r3 f70b6dc8
r4 f70b6dd0 r5 f70b6d80 r6 00000002 r7 0000010c
r8 ffffffed r9 00000000 sl 00000000 fp ff96ae1c
@@ -97,35 +101,39 @@
#01 pc 00041ed1 /system/lib/libc.so (pthread_kill+32)
#02 pc 0001bb87 /system/lib/libc.so (raise+10)
#03 pc 00018cad /system/lib/libc.so (__libc_android_abort+34)
- #04 pc 000168e8 /system/lib/<i style="color:Orange">libc.so</i> (<i style="color:Orange">abort</i>+4)
+ #04 pc 000168e8 /system/lib/<em style="color:Orange">libc.so</em> (<em style="color:Orange">abort</em>+4)
#05 pc 0001a78f /system/lib/libc.so (__libc_fatal+16)
#06 pc 00018d35 /system/lib/libc.so (__assert2+20)
#07 pc 00000f21 /system/xbin/crasher
#08 pc 00016795 /system/lib/libc.so (__libc_init+44)
#09 pc 00000abc /system/xbin/crasher
</pre>
+
<p>
-You can reproduce an instance of this type of crash using <code>crasher
-abort</code>.
+ You can reproduce an instance of this type of crash using <code>crasher
+ abort</code>.
</p>
-<h3 id=nullpointer>Pure null pointer dereference</h3>
+
+<h2 id=nullpointer>Pure null pointer dereference</h2>
+
<p>
-This is the classic native crash, and although it's just a special case of the
-next crash type, it's worth mentioning separately because it usually requires
-the least thought.
+ This is the classic native crash, and although it's just a special case of the
+ next crash type, it's worth mentioning separately because it usually requires
+ the least thought.
</p>
+
<p>
-In the example below, even though the crashing function is in
-<code>libc.so</code>, because the string functions just operate on the pointers
-they're given, you can infer that <code><a
-href="http://man7.org/linux/man-pages/man3/strlen.3.html">strlen(3)</a></code>
-was called with a null pointer; and this crash should go straight to the author
-of the calling code. In this case, frame #01 is the bad caller.
+ In the example below, even though the crashing function is in
+ <code>libc.so</code>, because the string functions just operate on the
+ pointers they're given, you can infer that
+ <code><a href="http://man7.org/linux/man-pages/man3/strlen.3.html" class="external">strlen(3)</a></code>
+ was called with a null pointer; and this crash should go straight to the
+ author of the calling code. In this case, frame #01 is the bad caller.
</p>
<pre class="devsite-click-to-copy">
pid: 25326, tid: 25326, name: crasher >>> crasher <<<
-signal 11 (<i style="color:Orange">SIGSEGV</i>), code 1 (SEGV_MAPERR), <i style="color:Orange">fault addr 0x0</i>
+signal 11 (<em style="color:Orange">SIGSEGV</em>), code 1 (SEGV_MAPERR), <em style="color:Orange">fault addr 0x0</em>
r0 00000000 r1 00000000 r2 00004c00 r3 00000000
r4 ab088071 r5 fff92b34 r6 00000002 r7 fff92b40
r8 00000000 r9 00000000 sl 00000000 fp fff92b2c
@@ -139,34 +147,37 @@
#04 pc 000177a1 /system/lib/libc.so (__libc_init+48)
#05 pc 000010e4 /system/xbin/crasher (_start+96)
</pre>
+
<p>
-You can reproduce an instance of this type of crash using <code>crasher
-strlen-NULL</code>.
+ You can reproduce an instance of this type of crash using <code>crasher
+ strlen-NULL</code>.
</p>
-<h3 id=lowaddress>Low-address null pointer dereference</h3>
+
+<h2 id=lowaddress>Low-address null pointer dereference</h2>
+
<p>
-In many cases the fault address won't be 0, but some other low number. Two- or
-three-digit addresses in particular are very common, whereas a six-digit address
-is almost certainly not a null pointer dereference—that would require a 1MiB
-offset. This usually occurs when you have code that dereferences a null pointer
-as if it was a valid struct. Common functions are <code><a
-href="http://man7.org/linux/man-pages/man3/fprintf.3.html">fprintf(3)</a></code>
-(or any other function taking a FILE*) and <code><a
-href="http://man7.org/linux/man-pages/man3/readdir.3.html">readdir(3)</a></code>,
-because code often fails to check that the <code><a
-href="http://man7.org/linux/man-pages/man3/fopen.3.html">fopen(3)</a></code> or
-<code><a
-href="http://man7.org/linux/man-pages/man3/opendir.3.html">opendir(3)</a></code>
-call actually succeeded first.
+ In many cases the fault address won't be 0, but some other low number. Two- or
+ three-digit addresses in particular are very common, whereas a six-digit
+ address is almost certainly not a null pointer dereference—that would
+ require a 1MiB offset. This usually occurs when you have code that
+ dereferences a null pointer as if it was a valid struct. Common functions are
+ <code><a href="http://man7.org/linux/man-pages/man3/fprintf.3.html" class="external">fprintf(3)</a></code>
+ (or any other function taking a FILE*) and
+ <code><a href="http://man7.org/linux/man-pages/man3/readdir.3.html" class="external">readdir(3)</a></code>,
+ because code often fails to check that the
+ <code><a href="http://man7.org/linux/man-pages/man3/fopen.3.html" class="external">fopen(3)</a></code>
+ or
+ <code><a href="http://man7.org/linux/man-pages/man3/opendir.3.html" class="external">opendir(3)</a></code>
+ call actually succeeded first.
</p>
<p>
-Here's an example of <code>readdir</code>:
+ Here's an example of <code>readdir</code>:
</p>
<pre class="devsite-click-to-copy">
pid: 25405, tid: 25405, name: crasher >>> crasher <<<
-signal 11 (<i style="color:Orange">SIGSEGV</i>), code 1 (SEGV_MAPERR), <i style="color:Orange">fault addr 0xc</i>
+signal 11 (<em style="color:Orange">SIGSEGV</em>), code 1 (SEGV_MAPERR), <em style="color:Orange">fault addr 0xc</em>
r0 0000000c r1 00000000 r2 00000000 r3 3d5f0000
r4 00000000 r5 0000000c r6 00000002 r7 ff8618f0
r8 00000000 r9 00000000 sl 00000000 fp ff8618dc
@@ -181,22 +192,24 @@
#05 pc 000177a1 /system/lib/libc.so (__libc_init+48)
#06 pc 00001110 /system/xbin/crasher (_start+96)
</pre>
+
<p>
-Here the direct cause of the crash is that <code><a
-href="http://man7.org/linux/man-pages/man3/pthread_mutex_lock.3p.html">pthread_mutex_lock(3)</a></code>
-has tried to access address 0xc (frame 0). But the first thing
-<code>pthread_mutex_lock</code> does is dereference the <code>state</code>
-element of the <code>pthread_mutex_t*</code> it was given. If you look at the
-source, you can see that element is at offset 0 in the struct, which tells you
-that <code>pthread_mutex_lock</code> was given the invalid pointer 0xc. From the
-frame 1 you can see that it was given that pointer by <code>readdir</code>,
-which extracts the <code>mutex_</code> field from the <code>DIR*</code> it's
-given. Looking at that structure, you can see that <code>mutex_</code> is at
-offset <code>sizeof(int) + sizeof(size_t) + sizeof(dirent*)</code> into
-<code>struct DIR</code>, which on a 32-bit device is 4 + 4 + 4 = 12 = 0xc, so
-you found the bug: <code>readdir</code> was passed a null pointer by the caller.
-At this point you can paste the stack into the stack tool to find out
-<em>where</em> in logcat this happened.</p>
+ Here the direct cause of the crash is that
+ <code><a href="http://man7.org/linux/man-pages/man3/pthread_mutex_lock.3p.html" class="external">pthread_mutex_lock(3)</a></code>
+ has tried to access address 0xc (frame 0). But the first thing
+ <code>pthread_mutex_lock</code> does is dereference the <code>state</code>
+ element of the <code>pthread_mutex_t*</code> it was given. If you look at the
+ source, you can see that element is at offset 0 in the struct, which tells you
+ that <code>pthread_mutex_lock</code> was given the invalid pointer 0xc. From
+ frame 1 you can see that it was given that pointer by <code>readdir</code>,
+ which extracts the <code>mutex_</code> field from the <code>DIR*</code> it's
+ given. Looking at that structure, you can see that <code>mutex_</code> is at
+ offset <code>sizeof(int) + sizeof(size_t) + sizeof(dirent*)</code> into
+ <code>struct DIR</code>, which on a 32-bit device is 4 + 4 + 4 = 12 = 0xc, so
+ you found the bug: <code>readdir</code> was passed a null pointer by the
+ caller. At this point you can paste the stack into the stack tool to find out
+ <em>where</em> in logcat this happened.
+</p>
<pre class="prettyprint">
struct DIR {
@@ -208,30 +221,35 @@
long current_pos_;
};
</pre>
+
<p>
-In most cases you can actually skip this analysis. A sufficiently low fault
-address usually means you can just skip any <code>libc.so</code> frames in the
-stack and directly accuse the calling code. But not always, and this is how you
-would present a compelling case.
+ In most cases you can actually skip this analysis. A sufficiently low fault
+ address usually means you can just skip any <code>libc.so</code> frames in the
+ stack and directly accuse the calling code. But not always, and this is how
+ you would present a compelling case.
</p>
+
<p>
-You can reproduce instances of this kind of crash using <code>crasher
-fprintf-NULL</code> or <code>crasher readdir-NULL</code>.
+ You can reproduce instances of this kind of crash using <code>crasher
+ fprintf-NULL</code> or <code>crasher readdir-NULL</code>.
</p>
-<h3 id=fortify>FORTIFY failure</h3>
+
+<h2 id=fortify>FORTIFY failure</h2>
+
<p>
-A FORTIFY failure is a special case of an abort that occurs when the C library
-detects a problem that might lead to a security vulnerability. Many C library
-functions are <em>fortified</em>; they take an extra argument that tells them how large
-a buffer actually is and check at run time whether the operation you're trying
-to perform actually fits. Here's an example where the code tries to
-<code>read(fd, buf, 32)</code> into a buffer that's actually only 10 bytes
-long...
+ A FORTIFY failure is a special case of an abort that occurs when the C library
+ detects a problem that might lead to a security vulnerability. Many C library
+ functions are <em>fortified</em>; they take an extra argument that tells them
+ how large a buffer actually is and check at run time whether the operation
+ you're trying to perform actually fits. Here's an example where the code tries
+ to <code>read(fd, buf, 32)</code> into a buffer that's actually only 10 bytes
+ long...
</p>
+
<pre class="devsite-click-to-copy">
pid: 25579, tid: 25579, name: crasher >>> crasher <<<
signal 6 (SIGABRT), code -6 (SI_TKILL), fault addr --------
-Abort message: '<i style="color:Orange">FORTIFY: read: prevented 32-byte write into 10-byte buffer'</i>
+Abort message: '<em style="color:Orange">FORTIFY: read: prevented 32-byte write into 10-byte buffer</em>'
r0 00000000 r1 000063eb r2 00000006 r3 00000008
r4 ff96f350 r5 000063eb r6 000063eb r7 0000010c
r8 00000000 r9 00000000 sl 00000000 fp ff96f49c
@@ -240,33 +258,37 @@
backtrace:
#00 pc 00049f0c /system/lib/libc.so (tgkill+12)
#01 pc 00019cdf /system/lib/libc.so (abort+50)
- #02 pc 0001e197 /system/lib/libc.so (<i style="color:Orange">__fortify_fatal</i>+30)
+ #02 pc 0001e197 /system/lib/libc.so (<em style="color:Orange">__fortify_fatal</em>+30)
#03 pc 0001baf9 /system/lib/libc.so (__read_chk+48)
#04 pc 0000165b /system/xbin/crasher (do_action+534)
#05 pc 000021e5 /system/xbin/crasher (main+100)
#06 pc 000177a1 /system/lib/libc.so (__libc_init+48)
#07 pc 00001110 /system/xbin/crasher (_start+96)
</pre>
+
<p>
-You can reproduce an instance of this type of crash using <code>crasher
-fortify</code>.
+ You can reproduce an instance of this type of crash using <code>crasher
+ fortify</code>.
</p>
-<h3 id=stackcorruption>Stack corruption detected by -fstack-protector</h3>
+
+<h2 id=stackcorruption>Stack corruption detected by -fstack-protector</h2>
+
<p>
-The compiler's <code>-fstack-protector</code> option inserts checks into
-functions with on-stack buffers to guard against buffer overruns. This option is
-on by default for platform code but not for apps. When this option is enabled,
-the compiler adds instructions to the <a
-href="https://en.wikipedia.org/wiki/Function_prologue">function prologue</a> to
-write a random value just past the last local on the stack and to the function
-epilogue to read it back and check that it's not changed. If that value changed,
-it was overwritten by a buffer overrun, so the epilogue calls
-<code>__stack_chk_fail</code> to log a message and abort.
+ The compiler's <code>-fstack-protector</code> option inserts checks into
+ functions with on-stack buffers to guard against buffer overruns. This option
+ is on by default for platform code but not for apps. When this option is
+ enabled, the compiler adds instructions to the
+ <a href="https://en.wikipedia.org/wiki/Function_prologue" class="external">function
+ prologue</a> to write a random value just past the last local on the stack and
+ to the function epilogue to read it back and check that it's not changed. If
+ that value changed, it was overwritten by a buffer overrun, so the epilogue
+ calls <code>__stack_chk_fail</code> to log a message and abort.
</p>
+
<pre class="devsite-click-to-copy">
pid: 26717, tid: 26717, name: crasher >>> crasher <<<
signal 6 (SIGABRT), code -6 (SI_TKILL), fault addr --------
-<i style="color:Orange">Abort message: 'stack corruption detected'</i>
+<em style="color:Orange">Abort message: 'stack corruption detected'</em>
r0 00000000 r1 0000685d r2 00000006 r3 00000008
r4 ffd516d8 r5 0000685d r6 0000685d r7 0000010c
r8 00000000 r9 00000000 sl 00000000 fp ffd518bc
@@ -276,39 +298,46 @@
#00 pc 00049f0c /system/lib/libc.so (tgkill+12)
#01 pc 00019cdf /system/lib/libc.so (abort+50)
#02 pc 0001e07d /system/lib/libc.so (__libc_fatal+24)
- #03 pc 0004863f /system/lib/libc.so (<i style="color:Orange">__stack_chk_fail</i>+6)
+ #03 pc 0004863f /system/lib/libc.so (<em style="color:Orange">__stack_chk_fail</em>+6)
#04 pc 000013ed /system/xbin/crasher (smash_stack+76)
#05 pc 00001591 /system/xbin/crasher (do_action+280)
#06 pc 00002219 /system/xbin/crasher (main+100)
#07 pc 000177a1 /system/lib/libc.so (__libc_init+48)
#08 pc 00001144 /system/xbin/crasher (_start+96)
</pre>
+
<p>
-You can distinguish this from other kinds of abort by the presence of
-<code>__stack_chk_fail</code> in the backtrace and the specific abort message.
+ You can distinguish this from other kinds of abort by the presence of
+ <code>__stack_chk_fail</code> in the backtrace and the specific abort message.
</p>
+
<p>
-You can reproduce an instance of this type of crash using <code>crasher
-smash-stack</code>.
+ You can reproduce an instance of this type of crash using <code>crasher
+ smash-stack</code>.
</p>
-<h3 id="seccomp">Seccomp SIGSYS from a disallowed system call</h3>
+
+<h2 id="seccomp">Seccomp SIGSYS from a disallowed system call</h2>
+
<p>
-The <a href="https://en.wikipedia.org/wiki/Seccomp">seccomp</a> system (specifically seccomp-bpf)
-restricts access to system calls. For more information about seccomp for platform developers, see
-the blog post
-<a href="https://android-developers.googleblog.com/2017/07/seccomp-filter-in-android-o.html">Seccomp filter in Android O</a>.
-A thread that calls a restricted system call
-will receive a SIGSYS signal with code SYS_SECCOMP. The system call number will be shown in the
-cause line, along with the architecture. It is important to note that system call numbers vary
-between architectures. For example, the readlinkat(2) system call is number 305 on x86
-but 267 on x86-64. The call number is different again on both arm and arm64. Because system call
-numbers vary between architectures, it's usually easier to use the stack trace to find out which
-system call was disallowed rather than looking for the system call number in the headers.
+ The <a href="https://en.wikipedia.org/wiki/Seccomp" class="external">seccomp</a>
+ system (specifically seccomp-bpf) restricts access to system calls. For more
+ information about seccomp for platform developers, see the blog post
+ <a href="https://android-developers.googleblog.com/2017/07/seccomp-filter-in-android-o.html" class="external">Seccomp
+ filter in Android O</a>. A thread that calls a restricted system call will
+ receive a SIGSYS signal with code SYS_SECCOMP. The system call number will be
+ shown in the cause line, along with the architecture. It is important to note
+ that system call numbers vary between architectures. For example, the
+ <code>readlinkat(2)</code> system call is number 305 on x86 but 267 on x86-64.
+ The call number is different again on both arm and arm64. Because system call
+ numbers vary between architectures, it's usually easier to use the stack trace
+ to find out which system call was disallowed rather than looking for the
+ system call number in the headers.
</p>
+
<pre class="devsite-click-to-copy">
pid: 11046, tid: 11046, name: crasher >>> crasher <<<
-signal 31 (SIGSYS), code 1 (<i style="color:Orange">SYS_SECCOMP</i>), fault addr --------
-<i style="color:Orange">Cause: seccomp prevented call to disallowed arm system call 99999</a>
+signal 31 (SIGSYS), code 1 (<em style="color:Orange">SYS_SECCOMP</em>), fault addr --------
+<em style="color:Orange">Cause: seccomp prevented call to disallowed arm system call 99999</em>
r0 cfda0444 r1 00000014 r2 40000000 r3 00000000
r4 00000000 r5 00000000 r6 00000000 r7 0001869f
r8 00000000 r9 00000000 sl 00000000 fp fffefa58
@@ -321,8 +350,9 @@
#03 pc 0007c60d /system/lib/libc.so (__libc_init+48)
#04 pc 000011b0 /system/bin/crasher (_start_main+72)
</pre>
+
<p>
-You can distinguish disallowed system calls from other crashes by the presence of
+ You can distinguish disallowed system calls from other crashes by the presence of
<code>SYS_SECCOMP</code> on the signal line and the description on the cause line.
</p>
<p>
@@ -330,18 +360,22 @@
seccomp</code>.
</p>
+<h2 id=crashdump>Investigating crash dumps</h2>
-<h2 id=crashdump>Crash dumps</h2>
+<p>
+ If you don't have a specific crash that you're investigating right now, the
+ platform source includes a tool for testing <code>debuggerd</code> called
+ crasher. If you <code>mm</code> in <code>system/core/debuggerd/</code> you'll
+ get both a <code>crasher</code> and a <code>crasher64</code> on your path (the
+ latter allowing you to test 64-bit crashes). Crasher can crash in a large
+ number of interesting ways based on the command line arguments you provide.
+ Use <code>crasher --help</code> to see the currently supported selection.
+</p>
-<p>If you don't have a specific crash that you're investigating right now,
-the platform source includes a tool for testing <code>debuggerd</code> called crasher. If
-you <code>mm</code> in <code>system/core/debuggerd/</code> you'll get both a <code>crasher</code>
-and a <code>crasher64</code> on your path (the latter allowing you to test
-64-bit crashes). Crasher can crash in a large number of interesting ways based
-on the command line arguments you provide. Use <code>crasher --help</code>
-to see the currently supported selection.</p>
-
-<p>To introduce the different pieces in a crash dump, let's work through this example crash dump:</p>
+<p>
+ To introduce the different pieces in a crash dump, let's work through this
+ example crash dump:
+</p>
<pre class="devsite-click-to-copy">
*** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
@@ -370,65 +404,79 @@
*** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
</pre>
-<p>The line of asterisks with spaces is helpful if you're searching a log
-for native crashes. The string "*** ***" rarely shows up in logs other than
-at the beginning of a native crash.</p>
+<p>
+ The line of asterisks with spaces is helpful if you're searching a log
+ for native crashes. The string "*** ***" rarely shows up in logs other than
+ at the beginning of a native crash.
+</p>
<pre class="devsite-click-to-copy">
Build fingerprint:
'Android/aosp_flounder/flounder:5.1.51/AOSP/enh08201009:eng/test-keys'
</pre>
-<p>The fingerprint lets you identify exactly which build the crash occurred
-on. This is exactly the same as the <code>ro.build.fingerprint</code> system property.</p>
+<p>
+ The fingerprint lets you identify exactly which build the crash occurred on.
+ This is exactly the same as the <code>ro.build.fingerprint</code> system
+ property.
+</p>
<pre class="devsite-click-to-copy">
Revision: '0'
</pre>
-<p>The revision refers to the hardware rather than the software. This is
-usually unused but can be useful to help you automatically ignore bugs known
-to be caused by bad hardware. This is exactly the same as the <code>ro.revision</code>
-system property.</p>
+<p>
+ The revision refers to the hardware rather than the software. This is usually
+ unused but can be useful to help you automatically ignore bugs known to be
+ caused by bad hardware. This is exactly the same as the
+ <code>ro.revision</code> system property.
+</p>
<pre class="devsite-click-to-copy">
ABI: 'arm'
</pre>
-<p>The ABI is one of arm, arm64, mips, mips64, x86, or x86-64. This is
-mostly useful for the <code>stack</code> script mentioned above, so that it knows
-what toolchain to use.</p>
+<p>
+ The ABI is one of arm, arm64, mips, mips64, x86, or x86-64. This is mostly
+ useful for the <code>stack</code> script mentioned above, so that it knows
+ what toolchain to use.
+</p>
<pre class="devsite-click-to-copy">
pid: 1656, tid: 1656, name: crasher >>> crasher <<<
</pre>
-<p>This line identifies the specific thread in the process that crashed. In
-this case, it was the process' main thread, so the process ID and thread
-ID match. The first name is the thread name, and the name surrounded by
->>> and <<< is the process name. For an app, the process name
-is typically the fully-qualified package name (such as com.facebook.katana),
-which is useful when filing bugs or trying to find the app in Google Play. The
-pid and tid can also be useful in finding the relevant log lines preceding
-the crash.</p>
+<p>
+ This line identifies the specific thread in the process that crashed. In this
+ case, it was the process' main thread, so the process ID and thread ID match.
+ The first name is the thread name, and the name surrounded by >>> and
+ <<< is the process name. For an app, the process name is typically
+ the fully-qualified package name (such as com.facebook.katana), which is
+ useful when filing bugs or trying to find the app in Google Play. The pid and
+tid can also be useful in finding the relevant log lines preceding the crash.
+</p>
<pre class="devsite-click-to-copy">
signal 6 (SIGABRT), code -6 (SI_TKILL), fault addr --------
</pre>
-<p>This line tells you which signal (SIGABRT) was received, and more about
-how it was received (SI_TKILL). The signals reported by <code>debuggerd</code> are SIGABRT,
-SIGBUS, SIGFPE, SIGILL, SIGSEGV, and SIGTRAP. The signal-specific codes vary
-based on the specific signal.</p>
+<p>
+ This line tells you which signal (SIGABRT) was received, and more about how it
+ was received (SI_TKILL). The signals reported by <code>debuggerd</code> are
+ SIGABRT, SIGBUS, SIGFPE, SIGILL, SIGSEGV, and SIGTRAP. The signal-specific
+codes vary based on the specific signal.
+</p>
<pre class="devsite-click-to-copy">
Abort message: 'some_file.c:123: some_function: assertion "false" failed'
</pre>
-<p>Not all crashes will have an abort message line, but aborts will. This
-is automatically gathered from the last line of fatal logcat output for
-this pid/tid, and in the case of a deliberate abort is likely to give an
-explanation of why the program killed itself.</p>
+<p>
+ Not all crashes will have an abort message line, but aborts will. This is
+ automatically gathered from the last line of fatal logcat output for this
+ pid/tid, and in the case of a deliberate abort is likely to give an
+ explanation of why the program killed itself.
+</p>
<pre class="devsite-click-to-copy">
r0 00000000 r1 00000678 r2 00000006 r3 f70b6dc8
@@ -437,9 +485,11 @@
ip 00000006 sp ff96ad18 lr f700ced5 pc f700dc98 cpsr 400b0010
</pre>
-<p>The register dump shows the content of the CPU registers at the time the
-signal was received. (This section varies wildly between ABIs.) How useful
-these are will depend on the exact crash.</p>
+<p>
+ The register dump shows the content of the CPU registers at the time the
+ signal was received. (This section varies wildly between ABIs.) How useful
+ these are will depend on the exact crash.
+</p>
<pre class="devsite-click-to-copy">
backtrace:
@@ -455,32 +505,38 @@
#09 pc 00000abc /system/xbin/crasher
</pre>
-<p>The backtrace shows you where in the code we were at the time of
-crash. The first column is the frame number (matching gdb's style where
-the deepest frame is 0). The PC values are relative to the location of the
-shared library rather than absolute addresses. The next column is the name
-of the mapped region (which is usually a shared library or executable, but
-might not be for, say, JIT-compiled code). Finally, if symbols are available,
-the symbol that the PC value corresponds to is shown, along with the offset
-into that symbol in bytes. You can use this in conjunction with <code>objdump(1)</code>
-to find the corresponding assembler instruction.</p>
+<p>
+ The backtrace shows you where in the code we were at the time of crash. The
+ first column is the frame number (matching gdb's style where the deepest frame
+ is 0). The PC values are relative to the location of the shared library rather
+ than absolute addresses. The next column is the name of the mapped region
+ (which is usually a shared library or executable, but might not be for, say,
+ JIT-compiled code). Finally, if symbols are available, the symbol that the PC
+ value corresponds to is shown, along with the offset into that symbol in
+ bytes. You can use this in conjunction with <code>objdump(1)</code> to find
+ the corresponding assembler instruction.
+</p>
-<h2 id=tombstones>Tombstones</h2>
+<h2 id=tombstones>Reading tombstones</h2>
<pre class="devsite-click-to-copy">
Tombstone written to: /data/tombstones/tombstone_06
</pre>
-<p>This tells you where <code>debuggerd</code> wrote extra information.
-<code>debuggerd</code> will keep up to 10 tombstones, cycling through
-the numbers 00 to 09 and overwriting existing tombstones as necessary.</p>
+<p>
+ This tells you where <code>debuggerd</code> wrote extra information.
+ <code>debuggerd</code> will keep up to 10 tombstones, cycling through the
+ numbers 00 to 09 and overwriting existing tombstones as necessary.
+</p>
-<p>The tombstone contains the same information as the crash dump, plus a
-few extras. For example, it includes backtraces for <i>all</i> threads (not
-just the crashing thread), the floating point registers, raw stack dumps,
-and memory dumps around the addresses in registers. Most usefully it also
-includes a full memory map (similar to <code>/proc/<i>pid</i>/maps</code>). Here's an
-annotated example from a 32-bit ARM process crash:</p>
+<p>
+ The tombstone contains the same information as the crash dump, plus a few
+ extras. For example, it includes backtraces for <em>all</em> threads (not
+ just the crashing thread), the floating point registers, raw stack dumps,
+ and memory dumps around the addresses in registers. Most usefully it also
+ includes a full memory map (similar to <code>/proc/<var>pid</var>/maps</code>).
+ Here's an annotated example from a 32-bit ARM process crash:
+</p>
<pre class="devsite-click-to-copy">
memory map: (fault address prefixed with --->)
@@ -488,12 +544,14 @@
b9527db01b5cf8f5402f899f64b9b121)
</pre>
-<p>There are two things to note here. The first is that this line is prefixed
-with "--->". The maps are most useful when your crash isn't just a null
-pointer dereference. If the fault address is small, it's probably some variant
-of a null pointer dereference. Otherwise looking at the maps around the fault
-address can often give you a clue as to what happened. Some possible issues
-that can be recognized by looking at the maps include:</p>
+<p>
+ There are two things to note here. The first is that this line is prefixed
+ with "--->". The maps are most useful when your crash isn't just a null
+ pointer dereference. If the fault address is small, it's probably some variant
+ of a null pointer dereference. Otherwise looking at the maps around the fault
+ address can often give you a clue as to what happened. Some possible issues
+ that can be recognized by looking at the maps include:
+</p>
<ul>
<li>Reads/writes past the end of a block of memory.</li>
@@ -503,11 +561,13 @@
<li>Attempts to write to code (as in the example above).</li>
</ul>
-<p>The second thing to note is that executables and shared libraries files
-will show the BuildId (if present) in Android M and later, so you can see
-exactly which version of your code crashed. (Platform binaries include a
-BuildId by default since Android M. NDK r12 and later automatically pass
-<code>-Wl,--build-id</code> to the linker too.)</p>
+<p>
+ The second thing to note is that executables and shared libraries files will
+ show the BuildId (if present) in Android 6.0 and higher, so you can see exactly
+ which version of your code crashed. Platform binaries include a BuildId by
+ default since Android 6.0; NDK r12 and higher automatically pass
+ <code>-Wl,--build-id</code> to the linker too.
+</p>
<pre class="devsite-click-to-copy">
ab163000-ab163fff r-- 3000 1000 /system/xbin/crasher
@@ -515,8 +575,10 @@
f6c80000-f6d7ffff rw- 0 100000 [anon:libc_malloc]
</pre>
-<p>On Android the heap isn't necessarily a single region. Heap regions will
-be labeled <code>[anon:libc_malloc]</code>.</p>
+<p>
+ On Android the heap isn't necessarily a single region. Heap regions will
+ be labeled <code>[anon:libc_malloc]</code>.
+</p>
<pre class="devsite-click-to-copy">
f6d82000-f6da1fff r-- 0 20000 /dev/__properties__/u:object_r:logd_prop:s0
@@ -544,13 +606,14 @@
f6f33000-f6f33fff rw- e000 1000 /system/lib/liblog.so
</pre>
-<p>Typically a shared library will have three adjacent entries. One will be
-readable and executable (code), one will be read-only (read-only
-data), and one will be read-write (mutable data). The first column
-shows the address ranges for the mapping, the second column the permissions
-(in the usual Unix <code>ls(1)</code> style), the third column the offset into the file
-(in hex), the fourth column the size of the region (in hex), and the fifth
-column the file (or other region name).</p>
+<p>
+ Typically, a shared library has three adjacent entries. One is readable and
+ executable (code), one is read-only (read-only data), and one is read-write
+ (mutable data). The first column shows the address ranges for the mapping, the
+ second column the permissions (in the usual Unix <code>ls(1)</code> style),
+ the third column the offset into the file (in hex), the fourth column the size
+ of the region (in hex), and the fifth column the file (or other region name).
+</p>
<pre class="devsite-click-to-copy">
f6f34000-f6f53fff r-x 0 20000 /system/lib/libm.so (BuildId: 76ba45dcd9247e60227200976a02c69b)
@@ -581,8 +644,8 @@
</pre>
<p>
-Note that since Android 5.0 (Lollipop), the C library names most of its anonymous mapped
-regions so there are fewer mystery regions.
+ As of Android 5.0, the C library names most of its anonymous mapped regions so
+ there are fewer mystery regions.
</p>
<pre class="devsite-click-to-copy">
@@ -590,7 +653,8 @@
</pre>
<p>
-Regions named <code>[stack:<i>tid</i>]</code> are the stacks for the given threads.
+ Regions named <code>[stack:<var>tid</var>]</code> are the stacks for the given
+ threads.
</p>
<pre class="devsite-click-to-copy">
@@ -604,6 +668,11 @@
ffff0000-ffff0fff r-x 0 1000 [vectors]
</pre>
-<p>Whether you see <code>[vector]</code> or <code>[vdso]</code> depends on the architecture. ARM uses [vector], while all other architectures use <a href="http://man7.org/linux/man-pages/man7/vdso.7.html">[vdso].</a></p>
+<p>
+ Whether you see <code>[vector]</code> or <code>[vdso]</code> depends on the
+ architecture. ARM uses <code>[vector]</code>, while all other architectures use
+ <a href="http://man7.org/linux/man-pages/man7/vdso.7.html" class="external"><code>[vdso]</code></a>.
+</p>
+
</body>
</html>
diff --git a/en/devices/tech/display/display-cutouts.md b/en/devices/tech/display/display-cutouts.md
new file mode 100644
index 0000000..a99987a
--- /dev/null
+++ b/en/devices/tech/display/display-cutouts.md
@@ -0,0 +1,279 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Display Cutouts
+
+Android {{ androidPVersionNumber }} adds support for implementing different
+types of display cutouts on devices. Display cutouts allow you to create
+immersive, edge-to-edge experiences while still allowing space for important
+sensors on the front of devices.
+
+<img src="/devices/tech/display/images/top-center-cutout.png" alt="Top center display cutout" width="250px">
+
+**Figure 1.** Top center display cutout
+
+Android {{ androidPVersionNumber }} supports the following types of cutouts:
+
++ Top center: Cutout at the center of the top edge
++ Top uncentered: Cutout may be in the corner or slightly off-center
++ Bottom: Cutout at the bottom
++ Dual: One cutout on top and one on the bottom
+
+## Examples and source
+
+The following window manager code at
+[frameworks/base/services/core/java/com/android/server/policy/PhoneWindowManager.java](https://android.googlesource.com/platform/frameworks/base/+/master/services/core/java/com/android/server/policy/PhoneWindowManager.java)
+shows how display frames are inset to the safe area when
+`LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS` is not set.
+
+```java
+// Ensure that windows with a DEFAULT or NEVER display cutout mode are laid out in
+// the cutout safe zone.
+if (cutoutMode != LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS) {
+ final Rect displayCutoutSafeExceptMaybeBars = mTmpDisplayCutoutSafeExceptMaybeBarsRect;
+ displayCutoutSafeExceptMaybeBars.set(displayFrames.mDisplayCutoutSafe);
+ if (layoutInScreen && layoutInsetDecor && !requestedFullscreen
+ && cutoutMode == LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT) {
+ // At the top we have the status bar, so apps that are
+ // LAYOUT_IN_SCREEN | LAYOUT_INSET_DECOR but not FULLSCREEN
+ // already expect that there's an inset there and we don't need to exclude
+ // the window from that area.
+ displayCutoutSafeExceptMaybeBars.top = Integer.MIN_VALUE;
+ }
+ if (layoutInScreen && layoutInsetDecor && !requestedHideNavigation
+ && cutoutMode == LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT) {
+ // Same for the navigation bar.
+ switch (mNavigationBarPosition) {
+ case NAV_BAR_BOTTOM:
+ displayCutoutSafeExceptMaybeBars.bottom = Integer.MAX_VALUE;
+ break;
+ case NAV_BAR_RIGHT:
+ displayCutoutSafeExceptMaybeBars.right = Integer.MAX_VALUE;
+ break;
+ case NAV_BAR_LEFT:
+ displayCutoutSafeExceptMaybeBars.left = Integer.MIN_VALUE;
+ break;
+ }
+ }
+ if (type == TYPE_INPUT_METHOD && mNavigationBarPosition == NAV_BAR_BOTTOM) {
+ // The IME can always extend under the bottom cutout if the navbar is there.
+ displayCutoutSafeExceptMaybeBars.bottom = Integer.MAX_VALUE;
+ }
+ // Windows that are attached to a parent and laid out in said parent already avoid
+ // the cutout according to that parent and don't need to be further constrained.
+ // Floating IN_SCREEN windows get what they ask for and lay out in the full screen.
+ // They will later be cropped or shifted using the displayFrame in WindowState,
+ // which prevents overlap with the DisplayCutout.
+ if (!attachedInParent && !floatingInScreenWindow) {
+ mTmpRect.set(pf);
+ pf.intersectUnchecked(displayCutoutSafeExceptMaybeBars);
+ parentFrameWasClippedByDisplayCutout |= !mTmpRect.equals(pf);
+ }
+ // Make sure that NO_LIMITS windows clipped to the display don't extend under the
+ // cutout.
+ df.intersectUnchecked(displayCutoutSafeExceptMaybeBars);
+}
+```
+
+SystemUI renders in the cutout area, and needs to determine where it can draw.
+[frameworks/base/packages/SystemUI/src/com/android/systemui/statusbar/phone/PhoneStatusBarView.java](https://android.googlesource.com/platform/frameworks/base/+/master/packages/SystemUI/src/com/android/systemui/statusbar/phone/PhoneStatusBarView.java)
+provides an example of a view that determines where the display cutout is, how
+big it is, and whether or not the inset from the nav bar avoids the cutout area.
+
+By overriding `onApplyWindowInsets()`, a view can determine where the cutout is
+and update its layout accordingly.
+
+```java
+@Override
+ public WindowInsets onApplyWindowInsets(WindowInsets insets) {
+ if (updateOrientationAndCutout(mLastOrientation)) {
+ updateLayoutForCutout();
+ requestLayout();
+ }
+ return super.onApplyWindowInsets(insets);
+ }
+```
+
+These methods outline how cutouts are handled in the status bar in all cases
+(i.e. top center, top uncentered, bottom, and dual-cutouts in all rotations).
+
+## Requirements
+
+To ensure that apps are not negatively impacted by cutouts, you must ensure
+that:
+
++ The status bar extends to at least the height of the cutout in portrait mode
++ The cutout area must be letterboxed in fullscreen and landscape modes
+
+Your device can have up to one cutout on each short edge (top and bottom).
+
+For more information, see the [CDD](/compatibility/android-cdd#3_8_15_display_cutout).
+
+Note: For apps targeting Android 8.0 or lower, you can provide users with an
+option to extend a fullscreen or landscape app into the cutout area (e.g. toggle
+in the navigation bar). As this may lead to content getting cut off, the
+`layoutInDisplayCutoutMode` activity theme attribute has been backported to
+Android 8.1 to allow apps to opt out. If the attribute is set, you may not show
+a special mode toggle.
+
+## Implementation
+
+To implement display cutouts on your device, you must configure the following
+values for System UI.
+
+<table>
+<thead>
+<tr>
+<th>Value</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>
+quick_qs_offset_height
+</code>
+</td>
+<td><p>Defines the top margin for the quick settings panel. The clock and battery
+are displayed in the space above the panel.</p>
+<p>In values-land, set to <code>status_bar_height_landscape</code>, and in
+portrait set to either the default of 48dp, or the height of the cutout,
+whichever is larger. Can optionally be taller than the cutout if
+desired.</p></td>
+</tr>
+<tr>
+<td><code>
+quick_qs_total_height
+</code>
+</td>
+<td><p>Total height of the quick-quick settings panel (collapsed quick settings
+panel) when the notification shade is expanded, including the space above
+the panel containing the clock.</p>
+<p>
+Because of the way quick settings is laid out, the total height of the
+quick-quick settings panel (including the offset) must be known statically,
+so this value must be adjusted by the same delta
+<code>quick_qs_offset_height</code>. Values-land defaults this to 152dp,
+while the portrait default is 176dp.</p></td>
+</tr>
+<tr>
+<td><code>
+status_bar_height_portrait
+</code>
+</td>
+<td><p>The default height of the status bar from the framework's perspective.</p>
+<p>In most devices, this defaults to 24dp. When there is a cutout, set this
+value to the height of the cutout. Can optionally be taller than the cutout
+if desired.</p></td>
+</tr>
+<tr>
+<td><code>
+status_bar_height_landscape
+</code>
+</td>
+<td><p>The height of the status bar in landscape. Cutouts are only supported on
+the short edges of the device, so this will always be an unaltered status
+bar height.</p>
+<p>In a device with no cutout, this is equivalent to
+<code>status_bar_height_portrait</code>. When a cutout is present, keep
+this value at the default status bar height.</p></td>
+</tr>
+<tr>
+<td><code>
+config_mainBuiltInDisplayCutout
+</code>
+</td>
+<td><p>The path defining the shape of the cutout. This is a string parsable by
+<code>android.util.PathParser</code>, and is how the size and shape of the
+cutout is defined to the system.</p>
+<p><code>@dp</code> can be specified on the path to emulate a shape targeting
+different devices. Because physical cutouts have an exact pixel size, do
+not use the <code>@dp</code> specifier when defining the path for a
+hardware notch.</p></td>
+</tr>
+<tr>
+<td><code>
+config_fillMainBuiltinDisplayCutout
+</code>
+</td>
+<td><p>A boolean value that determines whether to draw the cutout path (defined
+above) in software. Can be used to emulate a cutout, or to fill in a
+physical cutout to achieve anti-aliasing.</p>
+<p>If true, <code>config_mainBuiltInDisplayCutout</code> is filled in
+black.</p></td>
+</tr>
+</tbody>
+</table>
+
+See these `dimens` files for the default definitions:
+
++ [`core/res/res/values-land/dimens.xml`](https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values-land/dimens.xml)
++ [`core/res/res/values/dimens.xml`](https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/dimens.xml)
+
+Example overlay for an emulated cutout:
+
+```
+<resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2">
+
+ <!-- The bounding path of the cutout region of the main built-in display.
+ Must either be empty if there is no cutout region, or a string that is parsable by
+ {@link android.util.PathParser}.
+
+ The path is assumed to be specified in display coordinates with pixel units and in
+ the display's native orientation, with the origin of the coordinate system at the
+ center top of the display.
+
+ To facilitate writing device-independent emulation overlays, the marker `@dp` can be
+ appended after the path string to interpret coordinates in dp instead of px units.
+ Note that a physical cutout should be configured in pixels for the best results.
+ -->
+ <string translatable="false" name="config_mainBuiltInDisplayCutout">
+ M 0,0
+ L -48, 0
+ L -44.3940446283, 36.0595537175
+ C -43.5582133885, 44.4178661152 -39.6, 48.0 -31.2, 48.0
+ L 31.2, 48.0
+ C 39.6, 48.0 43.5582133885, 44.4178661152 44.3940446283, 36.0595537175
+ L 48, 0
+ Z
+ @dp
+ </string>
+
+ <!-- Whether the display cutout region of the main built-in display should be forced to
+ black in software (to avoid aliasing or emulate a cutout that is not physically existent).
+ -->
+ <bool name="config_fillMainBuiltInDisplayCutout">true</bool>
+
+ <!-- Height of the status bar -->
+ <dimen name="status_bar_height_portrait">48dp</dimen>
+ <dimen name="status_bar_height_landscape">28dp</dimen>
+ <!-- Height of area above QQS where battery/time go (equal to status bar height if > 48dp) -->
+ <dimen name="quick_qs_offset_height">48dp</dimen>
+ <!-- Total height of QQS (quick_qs_offset_height + 128) -->
+ <dimen name="quick_qs_total_height">176dp</dimen>
+
+</resources>
+```
+
+## Validation
+
+To validate your implementation of display cutouts, run the CTS tests at
+[tests/framework/base/windowmanager/src/android/server/wm](https://android.googlesource.com/platform/cts/+/master/tests/framework/base/windowmanager/src/android/server/wm).
diff --git a/en/devices/tech/display/images/app-launch-animation.mp4 b/en/devices/tech/display/images/app-launch-animation.mp4
new file mode 100644
index 0000000..1f24468
--- /dev/null
+++ b/en/devices/tech/display/images/app-launch-animation.mp4
Binary files differ
diff --git a/en/devices/tech/display/images/notification-launch-animation.mp4 b/en/devices/tech/display/images/notification-launch-animation.mp4
new file mode 100644
index 0000000..5446372
--- /dev/null
+++ b/en/devices/tech/display/images/notification-launch-animation.mp4
Binary files differ
diff --git a/en/devices/tech/display/images/rotate-btn-quickstep.gif b/en/devices/tech/display/images/rotate-btn-quickstep.gif
new file mode 100644
index 0000000..f2f5aa9
--- /dev/null
+++ b/en/devices/tech/display/images/rotate-btn-quickstep.gif
Binary files differ
diff --git a/en/devices/tech/display/images/top-center-cutout.png b/en/devices/tech/display/images/top-center-cutout.png
new file mode 100644
index 0000000..eab4abd
--- /dev/null
+++ b/en/devices/tech/display/images/top-center-cutout.png
Binary files differ
diff --git a/en/devices/tech/display/rotate-suggestions.html b/en/devices/tech/display/rotate-suggestions.html
new file mode 100644
index 0000000..3024ce5
--- /dev/null
+++ b/en/devices/tech/display/rotate-suggestions.html
@@ -0,0 +1,225 @@
+<html devsite>
+ <head>
+ <title>Rotate Suggestions</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ {% include "_versions.html" %}
+ <body>
+ <!--
+ Copyright 2018 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
+
+ //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>
+In Android 8.0, users could toggle between auto-rotate and portrait rotation
+modes using a Quicksettings tile or Display settings. In Android P, we updated
+portrait rotation mode to eliminate unintentional rotations by pinning the
+current screen rotation even if the device position changes. Users can trigger
+rotation manually when needed by pressing a new button in the navigation bar.
+We renamed the portrait mode to rotation lock and it activates when auto-rotate
+is off. There are no changes to auto-rotate mode.
+</p>
+<p>
+When the device is in rotation lock mode, users can lock their screen to any
+rotation supported by the top, visible Activity (given current system
+constraints). If the top Activity can be rendered in multiple rotations in
+auto-rotate mode, the same options should be available in rotation locked mode,
+with some exceptions based on the Activity's <code>screenOrientation</code>
+setting.
+</p>
+<p>
+Rotation lock mode works by showing a button in the navbar on device rotation
+changes. To accomplish this, the device's orientation sensor must remain active
+even when auto-rotate is off. Tapping this button effectively sets user rotation
+preference (<code>Settings.System.USER_ROTATION</code>). WindowManager uses this
+preference, along with other details about the top Activity and system status,
+to change the system's rotation. WindowManager continues to use user rotation
+preference when deciding what rotation to render the system in when moving to
+another Activity.
+</p>
+
+<figure>
+ <img src="images/rotate-btn-quickstep.gif"
+ alt="This gif shows a phone in landscape orientation with the screen in
+ portrait orientation. An icon appears to ask the user if they want to
+ change their screen orientation to landscape.">
+ <figcaption><strong>Figure 1</strong>. Rotate suggestion button with "Swipe
+ up on Home button" gesture enabled</figcaption>
+</figure>
+
+
+<p>
+User rotation preference should be maintained when moving between Activities.
+However, because most phone users only want to be in landscape for a short,
+temporary period of time, we added natural orientation bias. User rotation
+preference is <em>reset</em> to the device's natural orientation whenever the
+system rotation changes to the device's natural orientation. For most phones,
+the device's natural orientation is portrait (0º). Resetting user rotation
+preference often happens when using a portrait-only app, locking the phone or
+returning to launcher workspace.
+</p>
+<p>
+Rotation interactions for users haven't changed much in the last decade. Users
+may find this feature hard to discover given their prior history with rotation
+and button positioning in the navigation bar. For this reason, we've added an
+introduction mode to the rotate button that highlights it when it appears. Intro
+mode behavior only happens for the first few button interactions after which
+introduction mode is disabled.
+</p>
+<h2 id="source">Source</h2>
+<p>
+Support for rotation suggestions has been added to Android P. Most changes are
+contained within the following files.
+</p>
+<ul>
+ <li><code>services/.../server/policy/PhoneWindowManager.java</code>:
+ <ul>
+ <li>Hooks consuming the output of <code>WindowOrientationListener</code>
+ (<code>MyOrientationListener</code>, responsible for monitoring
+ sensors to determine if the device has been rotated)</li>
+ <li>Keeps the <code>WindowOrientationListener</code> active even when
+ auto-rotate is disabled (see <code>needSensorRunningLp()</code>)</li>
+ <li>Computes the system rotation given user rotation preference, top
+ Activity <code>screenOrientation</code> settings and system status
+ (see <code>rotationForOrientationLw()</code>)</li>
+ <li>Determine if the top Activity can rotate to a given rotation (see
+ <code>isRotationChoicePossible()</code>)</li>
+ </ul>
+ </li>
+ <li><code>SystemUI/.../statusbar/phone/NavigationBarFragment</code>:
+ <ul>
+ <li>Determines if the navbar button should be shown on rotation
+ suggestion callbacks from <code>PhoneWindowManager</code>
+ (see <code>onRotationProposal()</code>)</li>
+ <li>Handles when to hide the rotate navbar button (see calls to
+ <code>setRotateSuggestionButtonState(false)</code>)</li>
+ <li>Handles button timeouts, including the special case when the
+ navbar is hidden (commonly in full screen)</li>
+ <li>Resets user preference on return to the device's natural
+ orientation (<code>mRotationWatcher</code>)</li>
+ <li>Picks the appropriate style for the navbar button animation,
+ applied in <code>NavigationBarView</code>
+ (see <code>onRotationProposal()</code>)</li>
+ <li>Adds introduction mode logic, including specialized animation
+ (see references to
+ <code>Settings.Secure.NUM_ROTATION_SUGGESTIONS_ACCEPTED</code>)</li>
+ <li>Implements the disable2 rotation flag (see <code>disable()</code>)</li>
+ </ul>
+ </li>
+ <li><code>SystemUI/.../statusbar/phone/NavigationBarView.java</code>:
+ <ul>
+ <li>Styles button icon animation to match pending rotation (see
+ <code>updateRotateSuggestionButtonStyle()</code>)</li>
+ <li>Handles button visibility changes (see
+ <code>setRotateButtonVisibility()</code>), including logic to hide
+ the rotate button if certain Accessibility services are active
+ (accounting for the right-most navbar button stack ranking)</li>
+ </ul>
+ </li>
+ <li><code>SystemUI/res/layout/menu_ime.xml</code>:
+ <ul>
+ <li>Includes a new <code>KeyButtonView</code> for the rotate button,
+ stacked above the menu and IME/keyboard chooser but below the
+ Accessibility button</li>
+ </ul>
+ </li>
+ <li><code>SystemUI/res/drawable/ic_sysbar_rotate_button.xml</code>:
+ <ul>
+ <li>Complex <code>AnimatedVectorDrawable</code> used to animate the
+ rotate navbar button</li>
+ <li>Styling (in <code>SystemUI/res/values/styles.xml</code>) is used to
+ set the start and end angles of rotation so the same drawable can be
+ used to animate various starting and ending rotations</li>
+ <li>Icon tinting is set via <code>TintedKeyButtonDrawable</code></li>
+ </ul>
+ </li>
+</ul>
+
+
+<h2 id="implementation">Implementation</h2>
+<p>
+Android P includes all necessary changes to get rotation suggestions working for
+devices that use software navigation keys (back, home, etc).
+</p>
+<p>
+Device manufacturers who create devices with hardware navigation keys that wish
+to implement this feature will need to design and implement their own System UI
+affordance or disable the feature. It is recommended that any introduced surface
+be easy to use when the device is held at 90º or 180º to the current system
+rotation and is rapidly accessible. For these reasons, the use of notifications
+(as is done for the IME/keyboard picker) is not recommended.
+</p>
+<p>
+The hardware requirements to use this feature are the same as the requirements
+to use auto-rotate.
+</p>
+<p>
+It is necessary for implementation consistency that user rotation preference
+(<code>Settings.System.USER_ROTATION</code>) is reset to the device's natural
+rotation when the system changes to the device's natural rotation for any reason
+when auto-rotate is off. The provided implementation does this (see
+<code>NavigationBarFragment.mRotationWatcher</code>).
+</p>
+<p>
+There is a new flag in <code>StatusBarManager.disable2</code> to temporarily
+prevent rotation suggestions from appearing. See
+<code>StatusBarManager.DISABLE2_ROTATE_SUGGESTIONS</code>. This flag must be
+respected in all implementations as it's used by critical system apps, including
+Setup Wizard. The provided implementation supports this (see
+<code>NavigationBarFragment.disable()</code>).
+</p>
+<p>
+We strongly recommend enabling the feature and following the AOSP
+implementation, if possible. We aim to keep the rotation experience similar
+between devices, mirroring the uniformity in experience on most phones today
+between auto-rotate and portrait lock.
+</p>
+
+<h2 id="customization">Customization</h2>
+<p>
+As rotation suggestions appear only in rotation locked mode (auto-rotate off),
+it is possible to choose if the feature is default on for new installs by
+choosing to have auto-rotate off by default. See
+<code>def_accelerometer_rotation</code> in
+<code>SettingsProvider/res/values/defaults.xml</code> to make default changes.
+</p>
+<p>
+Users can easily change if auto-rotate is active or not (regardless of default)
+via the rotate tile in Quicksettings or Display settings.
+</p>
+
+<h2 id="validation">Validation</h2>
+<p>
+For testing, the feature can be turned off and on by altering a gating
+<code>Settings.Secure</code> value. This accomplished easiest by running the
+following command from a privileged adb instance:
+</p>
+
+
+<pre
+class="prettyprint">adb shell settings put secure show_rotation_suggestions <x>
+</pre>
+<p>
+Set x to <code>0</code> for off and <code>1</code> for on.
+
+<p>
+For testing, introduction mode can be reset by altering the associated
+<code>Settings.Secure</code> value. This accomplished easiest by running the
+following command from a privileged adb instance:
+</p>
+
+
+<pre class="prettyprint">adb shell settings put secure num_rotation_suggestions_accepted 0</pre>
+</body>
+</html>
diff --git a/en/devices/tech/display/synched-app-transitions.md b/en/devices/tech/display/synched-app-transitions.md
new file mode 100644
index 0000000..6247b29
--- /dev/null
+++ b/en/devices/tech/display/synched-app-transitions.md
@@ -0,0 +1,68 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Implementing Synchronized App Transitions
+
+Synchronized App Transitions is a feature in Android {{ androidPVersionNumber }}
+that enhances the existing app transition architecture. When a user opens,
+closes, or switches between apps, the SystemUI or Launcher (homescreen) process
+sends a request to control the animation frame-by-frame with guaranteed
+synchronization between view animations and window animations. When the SystemUI
+or Launcher draws a new frame as part of an animation, it requests a different
+transform on the animating app surface that determines how the app is composed
+on the screen, and marks the request, a surface transaction, to be synchronized
+with the frame it's currently drawing.
+
+This allows for new app transition animations that are not possible on Android
+8.x and lower. For example, the
+[app launch animation](/devices/tech/display/images/app-launch-animation.mp4)
+can transform homescreen icons seamlessly into the app surface and the
+[notification launch animation](/devices/tech/display/images/notification-launch-animation.mp4)
+can transform notifications into the app surface.
+
+## Examples and source
+
+See the following references for this feature.
+
++ [`ActivityOptions.makeRemoteAnimation`](https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/app/ActivityOptions.java#844)
+
++ [`RemoteAnimationAdapter`](https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/view/RemoteAnimationAdapter.java)
+
++ [`RemoteAnimationRunner`](https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/view/IRemoteAnimationRunner.aidl)
+
++ [`Activity.registerRemoteAnimations`](https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/app/Activity.java#7869)
+
+For a reference implementation for the notification launch animation, see
+[`ActivityLaunchAnimator.java`](https://android.googlesource.com/platform/frameworks/base/+/master/packages/SystemUI/src/com/android/systemui/statusbar/notification/ActivityLaunchAnimator.java).
+
+## Implementation
+
+You can implement this feature on Launcher/System UI as required or you can use
+the AOSP implementation in SystemUI/Launcher3.
+
+Note: This feature increases the load on the GPU and CPU during animations.
+
+## Validation
+
+To validate the performance of the animations, measure the performance of the
+controlling app, i.e. SystemUI or Launcher, during the animations as described
+in
+[Test UI performance](https://developer.android.com/training/testing/performance).
diff --git a/en/devices/tech/display/textclassifier.html b/en/devices/tech/display/textclassifier.html
index 81ed87f..9cb3a25 100644
--- a/en/devices/tech/display/textclassifier.html
+++ b/en/devices/tech/display/textclassifier.html
@@ -1,10 +1,11 @@
<html devsite>
<head>
- <title>Implementing TEXTCLASSIFIER</title>
+ <title>Implementing Text Classification</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
+{% include "_versions.html" %}
<!--
Copyright 2017 The Android Open Source Project
@@ -21,13 +22,126 @@
limitations under the License.
-->
-<h2 id="overview">Overview</h2>
-<p>
-Android 8.1 introduces the TextClassfier API that uses machine learning
-techniques to help developers classify text:
+<p>Text classification uses machine learning techniques to help developers classify text.</p>
+
+<h2>Android {{ androidPVersionNumber }} release text classification enhancements</h2>
+
+<p>Android {{ androidPVersionNumber }} extended the <a
+href="#8_1release">text
+classification framework introduced in Android 8.1</a> with the new Text
+Classifier service. The Text Classifier service is the recommended way for OEMs
+to provide text classification system support. The Text Classifier service may
+be part of any system APK and may be updated when necessary.</p>
+
+<p>Android {{ androidPVersionNumber }} includes a default Text Classifier service implementation (<a
+href="https://android.googlesource.com/platform/frameworks/base/+/refs/heads/master/core/java/android/view/textclassifier/TextClassifierImpl.java">
+<code>TextClassifierImpl</code></a>) that is used unless you replace it with a custom Text Classifier service
+implementation.</p>
+
+<h3>Implementing a custom Text Classifier service</h3>
+<p>The following sections describe how to implement a custom Text Classifier
+service that you develop.</p>
+
+<h4>Extend android.service.textclassifier.TextClassifierService</h4>
+<p><pre class="prettyprint">
+public final class TextClassifierServiceImpl
+ extends TextClassifierService {
+
+ // Returns TextClassifierImpl.
+ private final TextClassifier tc = getLocalTextClassifier();
+
+ @Override
+ public void onSuggestSelection(
+ @Nullable TextClassificationSessionId sessionId,
+ @NonNull TextSelection.Request request,
+ @NonNull CancellationSignal cancellationSignal,
+ @NonNull Callback<TextSelection> callback) {
+ CompletableFuture.supplyAsync(
+ () -> tc.suggestSelection(request))
+ .thenAccept(r -> callback.onSuccess(r));
+ }
+
+ @Override
+ public void onClassifyText(
+ @Nullable TextClassificationSessionId sessionId,
+ @NonNull TextClassification.Request request,
+ @NonNull CancellationSignal cancellationSignal,
+ @NonNull Callback<TextClassification> callback) {
+ ...
+ }
+
+ @Override
+ public void onGenerateLinks(
+ @Nullable TextClassificationSessionId sessionId,
+ @NonNull TextLinks.Request request,
+ @NonNull CancellationSignal cancellationSignal,
+ @NonNull Callback<TextLinks> callback) {
+ ...
+ }
+ ...
+}
+</pre>
</p>
+<h4>Define the service in the Android manifest</h4>
+
+<p><em>[AndroidManifest.xml]</p></em>
+<p><pre class="prettyprint">
+<service android:name=".TextClassifierServiceImpl"
+ android:permission="android.permission.BIND_TEXTCLASSIFIER_SERVICE">
+ <intent-filter>
+ <action android:name=
+ "android.service.textclassifier.TextClassifierService"/>
+ </intent-filter>
+</service>
+</pre></p>
+
+<p>
+Note that the service must require the
+<code>android.permission.BIND_TEXTCLASSIFIER_SERVICE</code> permission and must
+also specify the
+<code>android.service.textclassifier.TextClassifierService</code> Intent
+action.</p>
+
+<h4>Set a system default Text Classifier service in the config overlay</h4>
+<p>[<em>config.xml</em>]</p>
+<p><pre class="prettyprint">
+<string name="config_defaultTextClassifierPackage" translatable="false">com.example.textclassifierservice</string></pre></p>
+
+<h4>Build the Text Classifier service into the system image</h4>
+<p>Your custom Text Classifier service can be a standalone APK that is built into the system image
+or a part of another system APK. The system uses <code>PackageManager.MATCH_SYSTEM_ONLY</code>
+to resolve the service.
+</p>
+
+<h3>Testing</h3>
+
+<p>Run Tests in <code>android.view.textclassifier.cts</code></p>
+
+<h3>Other text classification changes in Android {{ androidPVersionNumber }}</h3>
+
+<p>Refer to <a
+href="https://source.android.com/devices/tech/display/textclassifier#inspecting-installed-language-modules">
+Inspecting installed language modules</a>.</p>
+<p>Android {{ androidPVersionNumber }} model files are incompatible with
+Android 8.x model files.</p>
+<p>Android {{ androidPVersionNumber }} model files have the naming pattern:
+<code>texclassifier.[language-code].model</code> (e.g.
+<code>textclassifier.en.model</code>)
+instead of <code>textclassifier.smartselection.en.model</code> in Android 8.x.</p>
+
+<h3>Obtaining the latest text classification model files</h3>
+<p>To obtain the most up-to-date models the following script can be run, which
+updates the TextClassifier models in the source tree:</p>
+
+<p><pre class="devsite-terminal devsite-click-to-copy">
+<a href="https://android.googlesource.com/platform/external/libtextclassifier/+/master/models/">external/libtextclassifier/models/</a>update.sh</pre></p>
+
+
+<h2 id="8_1release">Android release 8.1 text classification</h2>
+
+<p>Android 8.1 introduced the TextClassfier API to implement text classification</p>
<pre
class="prettyprint">TextClassificationManager tcm =
@@ -59,7 +173,7 @@
<b>Figure 1.</b> TEXTCLASSIFIER usage.
</p>
-<h2 id="textclassifier-neural-net-models">TextClassifier neural-net models</h2>
+<h3 id="textclassifier-neural-net-models">TextClassifier neural-net models</h3>
<p>
The Android Open Source Project (AOSP) features a number of neural network
models for classifying text. Each model file is trained for a single language.
@@ -69,8 +183,8 @@
<code>external/libtextclassifier/Android.mk</code>
</p>
-<h2 id="pre-installing-language-models-on-devices">Pre-installing language
-models on devices</h2>
+<h3 id="pre-installing-language-models-on-devices">Pre-installing language
+models on devices</h3>
<p>
You may specify a bundle of language models and install them on a device:
</p>
@@ -101,8 +215,8 @@
textclassifier.smartselection.bundle1
</pre>
-<h2 id="inspecting-installed-language-modules">Inspecting installed language
-modules</h2>
+<h3 id="inspecting-installed-language-modules">Inspecting installed language
+modules</h3>
<p>
Use ADB to list the files in the directory:
</p>
@@ -116,7 +230,7 @@
-rw-r--r-- 1 root root ... textclassifier.smartselection.fr.model
</pre>
-<h2 id="gservices-model-updates">Model updates</h2>
+<h3 id="gservices-model-updates">Model updates</h3>
<p>
Models can be updated either by having a new model included as part of a system image update,
@@ -132,7 +246,7 @@
If no model file is found for the specified language, text classification will return no-op values.
</p>
-<h2 id="compatibility-test-suite-tests">Compatibility Test Suite tests</h2>
+<h3 id="compatibility-test-suite-tests">Compatibility Test Suite tests</h3>
<p>
The associated Android Compatibility Test Suite (CTS) tests can be found in:
</p>
diff --git a/en/devices/tech/health/deprecation.md b/en/devices/tech/health/deprecation.md
new file mode 100644
index 0000000..4e92e7e
--- /dev/null
+++ b/en/devices/tech/health/deprecation.md
@@ -0,0 +1,80 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Deprecating health@1.0
+
+The framework will continue to work with health@1.0 until it is fully deprecated
+according to the standard
+[HAL deprecation schedule](/devices/architecture/vintf/fcm#hal-version-deprecation).
+When health@1.0 is deprecated (entry removed from
+[framework compatibility matrix](https://source.android.com/devices/architecture/vintf/comp-matrices)),
+`healthd` and `libbatterymonitor` must also be removed from system to avoid
+unknown behaviors for healthd. As health@1.0 is an optional HAL and all
+`healthd` dependencies to health@1.0 are guarded by NULL checks, nothing should
+break on deprecation.
+
+When Android removes the legacy code path (healthd, health@1.0), Health@1.0 HAL
+is deprecated according to deprecation schedule. In addition, Android also
+removes the following:
+
+1. healthd dependency in framework
+1. healthd
+1. health@1.0 HAL definition library from system
+1. health@1.0 entry in framework compatibility matrix
+
+## Removing healthd
+
+For devices launching with Android {{ androidPVersionNumber }} and devices
+upgrading to Android {{ androidPVersionNumber }} that provide the Health 2.0 HAL
+in the new vendor image, we recommend removing `healthd` from the system image
+to save disk space and speed boot time.
+
+To do so:
+
+1. Remove `healthd` and `healthd.rc` from the system image by adding the
+ following line to the device-specific implementation in Soong:
+
+ ```
+ cc_binary {
+ name: "android.hardware.health@2.0-service.device_name"
+ overrides: ["healthd"],
+ // ...
+ }
+ ```
+
+ Or, if the module is in Make:
+
+ ```yaml
+ LOCAL_MODULE_NAME := \
+ android.hardware.health@2.0-service.device_name
+ LOCAL_OVERRIDES_MODULES := healthd
+ ```
+
+ If the default implementation `android.hardware.health@2.0-service` is
+ installed, implement a device-specific
+ `android.hardware.health@2.0-service.device_name` instead. For more
+ information, see [Implementing Health](/devices/tech/health/implementation).
+
+1. Add the following lines to `BoardConfig.mk` to remove the backup instance
+ from framework manifest. This ensures the framework manifest correctly
+ reflects the HALs on the device and allows the relevant VTS tests to pass.
+
+ ```make
+ DEVICE_FRAMEWORK_MANIFEST_FILE += \
+ system/libhidl/vintfdata/manifest_healthd_exclude.xml
+ ```
diff --git a/en/devices/tech/health/images/health-1-charging-recovery.png b/en/devices/tech/health/images/health-1-charging-recovery.png
new file mode 100644
index 0000000..d3488db
--- /dev/null
+++ b/en/devices/tech/health/images/health-1-charging-recovery.png
Binary files differ
diff --git a/en/devices/tech/health/images/health-2-charging-recovery.png b/en/devices/tech/health/images/health-2-charging-recovery.png
new file mode 100644
index 0000000..a5b2418
--- /dev/null
+++ b/en/devices/tech/health/images/health-2-charging-recovery.png
Binary files differ
diff --git a/en/devices/tech/health/images/health-component-1.png b/en/devices/tech/health/images/health-component-1.png
new file mode 100644
index 0000000..9c7a718
--- /dev/null
+++ b/en/devices/tech/health/images/health-component-1.png
Binary files differ
diff --git a/en/devices/tech/health/images/health-component-2.png b/en/devices/tech/health/images/health-component-2.png
new file mode 100644
index 0000000..b85b5a5
--- /dev/null
+++ b/en/devices/tech/health/images/health-component-2.png
Binary files differ
diff --git a/en/devices/tech/health/implementation.md b/en/devices/tech/health/implementation.md
new file mode 100644
index 0000000..156c9e0
--- /dev/null
+++ b/en/devices/tech/health/implementation.md
@@ -0,0 +1,208 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Implementing Health
+
+All `healthd` code has been refactored into health@2.0-impl and
+`libhealthservice`, then modified to implement health@2.0 HAL. These two
+libraries are linked statically by health@2.0-service, enabling it to do the
+work previously done by `healthd` (i.e. run the `healthd_mainloop` and do
+polling). In init, the health@2.0-service registers an implementation of the
+interface `IHealth` to `hwservicemanager`. When upgrading devices with an
+Android 8.x vendor image and an Android {{ androidPVersionNumber }} framework,
+health@2.0 service might not be provided by the vendor image. This is enforced
+by the
+[deprecation schedule](/devices/architecture/vintf/fcm#hal-version-deprecation).
+
+To resolve this issue:
+
+1. `healthd` registers `IHealth` to `hwservicemanager` (despite being a system
+ daemon). `IHealth` is added to the system manifest, with instance name
+ "backup".
+1. Framework and `storaged` communicate with `healthd` via `hwbinder` instead
+ of `binder`.
+1. Code for framework and `storaged` are changed to fetch the instance
+ "default" if available, then "backup".
+ * C++ client code uses the logic defined in `libhealthhalutils`.
+ * Java client code uses the logic defined in `HealthServiceWrapper`.
+1. After IHealth/default is widely available and Android 8.1 vendor images are
+ deprecated, IHealth/backup and `healthd` can be deprecated. For more
+ details, see [Deprecating health@1.0](/devices/tech/health/deprecation).
+
+## Board-specific build variables for healthd
+
+`BOARD_PERIODIC_CHORES_INTERVAL_*` are board-specific variables used to build
+`healthd`. As part of system/vendor build split, board-specific values
+**cannot** be defined for system modules. In health@2.0, vendors can override
+these two values in `healthd_mode_ops->init` (by dropping `libhealthservice`
+dependency in `health@2.0-service.<device>` and re-implementing this function).
+
+## Static implementation library
+
+Unlike other HAL implementation libraries, the implementation library
+health@2.0-impl is a **static** library to which health@2.0-service, charger,
+recovery, and legacy healthd link.
+
+health@2.0.impl implements `IHealth` as described above and is meant to wrap
+around `libbatterymonitor` and <code>libhealthd.<var>BOARD</var></code>. These
+users of health@2.0-impl must not use `BatteryMonitor` or the functions in
+`libhealthd` directly; instead, these calls should be replaced with calls into
+the `Health` class, an implementation of the`IHealth` interface. To generalize
+further, `healthd_common` code is also included in health@2.0-impl. The new
+`healthd_common` contains the rest of common code between health@2.0-service,
+charger, and `healthd` and calls into IHealth methods instead of BatteryMonitor.
+
+## Implementing Health 2.0 service
+
+When implementing health@2.0 service for a device, if the default implementation
+is:
+
+* Sufficient for the device, use `android.hardware.health@2.0-service`
+ directly.
+* Not sufficient for the device, create the
+ `android.hardware.health@2.0-service.(device)` executable and include:
+
+ ```
+ #include <health2/service.h>
+ int main() { return health_service_main(); }
+ ```
+
+Then:
+
++ If board-specific `libhealthd:`
+
+ + Does exist, link to it.
+ + Does not exist, provide empty implementations for `healthd_board_init`
+ and `healthd_board_battery_update` functions.
+
++ If board-specific `BOARD_PERIODIC_CHORES_INTERVAL_*` variables:
+
+ + Are defined, create a device-specific `HealthServiceCommon.cpp` (copied
+ from `hardware/interfaces/health/2.0/utils/libhealthservice`) and
+ customize it in `healthd_mode_service_2_0_init`.
+ + Are not defined, link to `libhealthservice` statically.
+
++ If device:
+
+ + Should implement `getStorageInfo` and `getDiskStats` APIs, provide the
+ implementation in `get_storage_info` and `get_disk_stats` functions.
+ + Should not implement those APIs, link to `libstoragehealthdefault`
+ statically.
+
+* Update necessary SELinux permissions.
+
+For details, refer to
+[hardware/interfaces/health/2.0/README.md](https://android.googlesource.com/platform/hardware/interfaces/+/master/health/2.0/README.md).
+
+## Health clients
+
+health@2.0 has the following clients:
+
++ **charger**. The usage of `libbatterymonitor` and `healthd_common` code is
+ wrapped in health@2.0-impl.
++ **recovery**. The linkage to `libbatterymonitor` is wrapped in
+ health@2.0-impl. All calls to `BatteryMonitor` are replaced by calls into
+ `Health` implementation class.
++ **BatteryManager**. `BatteryManager.queryProperty(int id)` was the only
+ client of `IBatteryPropertiesRegistrar.getProperty` which was provided by
+ `healthd` and directly reads `/sys/class/power_supply`.
+
+ As a security consideration, apps are not allowed to call into health HAL
+ directly. In Android {{ androidPVersionNumber }}, the binder service
+ `IBatteryPropertiesRegistrar` is provided by `BatteryService` instead of
+ `healthd` and `BatteryService` delegates the call to health HAL to retrieve
+ the requested information.
+
++ **BatteryService**. In Android {{ androidPVersionNumber }}, `BatteryService`
+ uses `HealthServiceWrapper` to determine the health service instance to use
+ ("default" instance from vendor or "backup" instance from healthd). It then
+ listens for health events via `IHealth.registerCallback`.
+
++ **Storaged**. In Android {{ androidPVersionNumber }}, `storaged` uses
+ `libhealthhalutils` to determine the health service instance to use
+ ("default" instance from vendor or "backup" instance from healthd). It then
+ listens for health events via `IHealth.registerCallback` and retrieves
+ storage information.
+
+## SELinux changes
+
+The new health@2.0 HAL includes the following SELinux changes:
+
++ Adds health@2.0-service to `file_contexts`.
++ Allows `system_server` and `storaged` to use `hal_health`.
++ Allows `system_server` (`BatteryService`) to register
+ `batteryproperties_service` (`IBatteryPropertiesRegistrar`).
++ Allows `healthd` to provide `hal_health`.
++ Removes rules that allow `system_server` / `storaged` to call into `healthd`
+ via binder.
++ Removes rules that allow `healthd` to register `batteryproperties_service`
+ (`IBatteryPropertiesRegistrar`).
+
+For devices with their own implementation, some vendor SELinux changes may be
+necessary. Example:
+
+```
+# device/<manufacturer>/<device>/sepolicy/vendor/file_contexts
+/vendor/bin/hw/android\.hardware\.health@2\.0-service.<device> u:object_r:hal_health_default_exec:s0
+
+# device/<manufacturer>/<device>/sepolicy/vendor/hal_health_default.te
+# Add device specific permissions to hal_health_default domain, especially
+# if it links to board-specific libhealthd or implements storage APIs.
+```
+
+## Kernel interfaces
+
+The `healthd` daemon and the default implementation
+`android.hardware.health@2.0-service` access the following kernel interfaces to
+retrieve battery information:
+
++ `/sys/class/power_supply/*/capacity`
++ `/sys/class/power_supply/*/charge_counter`
++ `/sys/class/power_supply/*/charge_full`
++ `/sys/class/power_supply/*/current_avg`
++ `/sys/class/power_supply/*/current_max`
++ `/sys/class/power_supply/*/current_now`
++ `/sys/class/power_supply/*/cycle_count`
++ `/sys/class/power_supply/*/health`
++ `/sys/class/power_supply/*/online`
++ `/sys/class/power_supply/*/present`
++ `/sys/class/power_supply/*/status`
++ `/sys/class/power_supply/*/technology`
++ `/sys/class/power_supply/*/temp`
++ `/sys/class/power_supply/*/type`
++ `/sys/class/power_supply/*/voltage_max`
++ `/sys/class/power_supply/*/voltage_now`
+
+Any device-specific health HAL implementation that uses `libbatterymonitor`
+accesses these kernel interfaces by default, unless overridden in
+`healthd_board_init(struct healthd_config*)`.
+
+If these files are missing or are inaccessible from `healthd` or from the
+default service (e.g. the file is a symlink to a vendor-specific folder that
+denies access because of misconfigured SELinux policy), they may not function
+correctly. Hence, additional vendor-specific SELinux changes may be necessary
+even though the default implementation is used.
+
+## Testing
+
+Android {{ androidPVersionNumber }} includes new [VTS tests](/compatibility/vts)
+written specifically for the health@2.0 HAL. If a device declares to provide
+health@2.0 HAL in the device manifest, it must pass the corresponding VTS tests.
+Tests are written for both the default instance (to ensure that the device
+implements the HAL correctly) and the backup instance (to ensure that `healthd`
+continues to function correctly before it is removed).
diff --git a/en/devices/tech/health/index.md b/en/devices/tech/health/index.md
new file mode 100644
index 0000000..1379090
--- /dev/null
+++ b/en/devices/tech/health/index.md
@@ -0,0 +1,156 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Health
+
+Android {{ androidPVersionNumber }} includes `android.hardware.health` HAL 2.0,
+a major version upgrade from health@1.0 HAL. This new HAL has the following
+advantages:
+
+* Cleaner separation between framework and vendor code.
+* Deprecates the unnecessary `healthd` daemon.
+* Greater degrees of freedom for vendor customization in health information
+ reports.
+* More device health information than just battery.
+
+## Requirements
+
+Devices launching with Android {{ androidPVersionNumber }} must provide the 2.0
+HAL (and must not provide the 1.0 HAL). Devices not launching with Android
+{{ androidPVersionNumber }} but planning to update the vendor image to Target
+Framework Compatibility Matrix Version 3 (released in Android
+{{ androidPVersionNumber }}) must remove existing 1.0 HAL implementations and
+provide the 2.0 HAL.
+
+AOSP includes multiple helper libraries designed to help you implement the 2.0
+HAL and the transition from the old 1.0 HAL.
+
+## Terminology
+
+* **health@1.0**: abbreviation of `android.hardware.health@1.0`. Refers to
+ health HIDL HAL version 1.0 released in Android 8.0.
+* **health@2.0**: abbreviation of `android.hardware.health@2.0`. Refers to
+ health HIDL HAL version 2.0 released in Android {{ androidPVersionNumber }}.
+* **charger**: executable running in off-mode charging that displays the
+ phone-charging animation.
+* **recovery**: executable running in recovery mode that must retrieve battery
+ information.
+* **healthd**: legacy daemon running in Android that retrieves health-related
+ information and provides it to framework.
+* **storaged**: daemon running in Android that retrieves storage information
+ and provides it to framework.
+
+## Health in Android 8.x
+
+In Android 8.x, the health component works as detailed in the following diagram:
+
+<img src="images/health-component-1.png" width="512" alt="Health in Android 8.x">
+
+**Figure 1**. Health in Android 8.x
+
+In this diagram:
+
+* One (1) binder call and one (1) hwbinder call are used by the framework to
+ communicate with hardware.
+* `healthd` statically links to `libhealthd_android`, `libbatterymonitor`, and
+ `libbatteryservice`.
+* health@1.0-impl statically links to
+ <code>libhealthd.<var>BOARD</var></code>.
+
+Each board can customize a different <code>libhealthd.<var>BOARD</var></code>;
+it is determined at build time what charger, health@1.0-impl, and recovery link
+to.
+
+For other modes:
+
+<img src="images/health-1-charging-recovery.png" width="" alt="Off-mode charing and recovery mode in Android 8.x">
+
+**Figure 2.** Health in Android 8.x, off-mode charging and recovery mode
+
+* charger statically links to <code>libhealthd.<var>BOARD</var></code>,
+ `libhealthd_charger` and `libbatterymonitor`.
+* recovery statically links to <code>libhealthd.<var>BOARD</var></code> and
+ `libbatterymonitor`.
+
+## Health in Android {{ androidPVersionNumber }}
+
+In Android {{ androidPVersionNumber }}, the health component works as detailed
+in the following diagram:
+<img src="images/health-component-2.png" width="553" alt="Health in Android {{ androidPVersionNumber }}">
+
+**Figure 3**. Health in Android {{ androidPVersionNumber }}
+
+The framework attempts to retrieve health@2.0 service from `hwservicemanager`.
+If it fails, it calls into health@1.0 (in Android 8.x). The legacy code path is
+kept so the Android {{ androidPVersionNumber }} system image is compatible with
+the Android 8.x vendor image. The framework does not retrieve information from
+both HALs because only one service version (1.0 or 2.0) can exist on the device.
+
+Note: For the legacy code path, the processes/libraries will be kept until
+health@1.0 is
+[deprecated](/devices/architecture/vintf/fcm#hal-version-deprecation).
+
+For other modes:
+
+<img src="images/health-2-charging-recovery.png" width="397" alt="Off-mode charing and recovery in Android {{ androidPVersionNumber }}">
+
+**Figure 4.** Health in Android {{ androidPVersionNumber }}, off-mode charging
+and recovery mode
+
+## HAL interface
+
+The health@2.0 HAL provides the same functionality to the framework as the old
+healthd daemon. It also provides APIs that are similar to what healthd
+previously provided as a binder service (i.e.
+[IBatteryPropertiesRegistrar](https://android.googlesource.com/platform/frameworks/base/+/2392cbd888212f61a242058f749bcc39d495bf4b/core/java/android/os/IBatteryPropertiesRegistrar.aidl)).
+
+The main interface,
+[IHealth](https://android.googlesource.com/platform/hardware/interfaces/+/de542acbbf46812cfb53d231ecb50048baf8780e/health/2.0/IHealth.hal)
+, provides the following functions:
+
+* `registerCallback`, to replace
+ `IBatteryPropertiesRegistrar.registerListener`
+* `unregisterCallback`, to replace
+ `IBatteryPropertiesRegistrar.unregisterListener`
+* `update`, to replace `IBatteryPropertiesRegistrar.scheduleUpdate`
+* `IBatteryPropertiesRegistrar.getProperties` are replaced by the following:
+ * `getChargeCounter`
+ * `getCurrentNow`
+ * `getCurrentAverage`
+ * `getCapacity`
+ * `getEnergyCounter`
+ * `getChargeStatus`
+ * `getHealthInfo`
+
+In addition, `IHealth` provides the following new APIs for `storaged` to
+retrieve vendor-specific storage related information:
+
+* `getStorageInfo`
+* `getDiskStats`
+
+A new struct, `@2.0::HealthInfo`, is returned via callbacks and `getHealthInfo`.
+This struct contains all device health information available through health@2.0
+HAL, including:
+
+* Charging information (AC/USB/wireless, current, voltage, etc.)
+* Battery information (presence, battery level, current, voltage, charge,
+ technology, etc.)
+* Storage information (storage device information, disk statistics)
+
+For information on implementing the Health service, see
+[Implementing Health](/devices/tech/health/implementation).
diff --git a/en/devices/tech/index.html b/en/devices/tech/index.html
index aafb7e0..fa523b4 100644
--- a/en/devices/tech/index.html
+++ b/en/devices/tech/index.html
@@ -1,12 +1,12 @@
<html devsite>
<head>
- <title>Android Core Technologies</title>
+ <title>Configure Android Devices</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
- Copyright 2017 The Android Open Source Project
+ Copyright 2018 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.
@@ -22,116 +22,11 @@
-->
+<p>Welcome to the Android platform configuration documentation. Here you can
+find instructions for optimizing services and customizing features.</p>
-
-<p>Welcome to the Android core technologies section of the site. Here you
-can find information on common features useful to people and organizations who
-are looking to modify, contribute to, or port the Android software. This is
-"under the hood" information intended for engineers.</p>
-
-<h2 id="art-technical-information">ART and Dalvik</h2>
-<p>The Android runtime (ART) is the heart of Android. It's a fast, ahead-of-time
-compiled runtime with modern garbage collection designed to scale.
-Android applications are compiled to Dalvik bytecode and run with ART. This
-section includes detailed information such as the Dalvik Executable format
-specification, and design information on the runtime itself.</p>
-<p><a href="/devices/tech/dalvik/index.html">» ART and Dalvik
-Information</a></p>
-
-<h2 id="config">Configuration</h2>
-<p>Getting the most out of Android requires tuning of the <a
-href="/devices/tech/config/kernel.html">kernel</a>, <a
-href="/devices/tech/config/renderer.html">OpenGLRenderer</a>, and
-more. See the subpages of this section for details.
-<p><a href="/devices/tech/config/index.html">» Configuration
-Information</a></p>
-
-<h2 id="connect">Connectivity</h2>
-<p>This section covers Android support for NFC standards (such as Felica),
-provides details on the Radio Interface Layer (RIL), describes call notification
-behavior, and gives implementation instructions for user-facing features such as
-Data Saver and phone number blocking.</p>
-<p><a href="/devices/tech/connect/index.html">» Connectivity
-Information</a></p>
-
-<h2 id="data-usage-technical-information">Data Usage</h2>
-<p>Android's data usage features allow users to understand and control how
-their device uses network data. This section is designed for systems
-integrators and mobile operators to help explain technical details they
-should be aware of when porting Android to specific devices.</p>
-<p><a href="/devices/tech/datausage/index.html">» Data Usage
-Information</a></p>
-
-<h2 id="debugging">Debugging</h2>
-<p>Android is a large and complex system. This section includes tips and tricks
-for debugging at the platform level.</p>
-<p><a href="/devices/tech/debug/index.html">» Debugging
-Information</a></p>
-
-<h2 id="admin-information">Device Administration</h2>
-<p>Since Android 5.0, the platform supports use cases in a corporate
-environment under the auspices of each company’s information technology (IT)
-department.</p>
-<p><a href="/devices/tech/admin/index.html">» Device
-administration information</a></p>
-
-<h2 id="display">Display Settings</h2>
-<p>This section covers AOSP implementation of various Android display
-settings, including app shortcuts, circular launcher icons, do not disturb
-(DND), multi-window (split-screen, free-form, and picture-in-picture), high
-dynamic range (HDR) video, night light, and retail demo mode.</p>
-<p><a href="/devices/tech/display/index.html">» Display settings
-information</a></p>
-
-<h2 id="ota-technical-information">OTA Updates</h2>
-<p>Android devices in the field can receive and install over-the-air (OTA)
-updates to the system and application software. This section describes the
-structure of update packages and the tools to build them. It is intended for
-developers building OTA updates for new and released Android devices.</p>
-<p><a href="/devices/tech/ota/index.html">» OTA Information</a>
-</p>
-
-<h2 id="performance">Performance</h2>
-<p>This section provides guidance for ensuring your Android devices minimize
-resource use and optimize performance. It includes details on optimizing boot
-times, managing flash wear, configuring for low ram devices, and more.</p>
-<p><a href="/devices/tech/perf/index.html">» Performance Information</a>
-</p>
-
-<h2 id="power-technical-information">Power</h2>
-<p>The framework provides battery usage statistics, keeping track of time spent
-by different device components in different states. This section covers power
-management features (such as Doze), gives instructions for accurately measuring
-device and component power (and how to determine power values), and details the
-<code>batterystats</code> command and output.</p>
-<p><a href="/devices/tech/power/index.html">» Power
-Information</a></p>
-
-<h2 id="settings">Settings</h2>
-<p>This section provides guidance on implementing features in Android Settings
-menu. It includes details on the patterns, components, and architecture of the
-Settings app, how to customize personalized settings, and how to add a setting
-to universal search.</p>
-<p><a href="/devices/tech/settings/index.html">» Settings Information</a>
-</p>
-
-<h2 id="tradefed-test-infrastructure">Trade Federation Testing Infrastructure
-</h2>
-<p>Trade Federation is a continuous test framework for running tests on
-Android devices. Trade Federation's modularity makes it straightforward to
-slot into environments with existing build, test, and reporting
-infrastructures.</p>
-<p><a href="/devices/tech/test_infra/tradefed/index.html">
-» Trade Federation Testing Infrastructure Overview</a></p>
-
-
-<h2 id="vts">Vendor Test Suite (VTS)</h2>
-<p>The Android Vendor Test Suite (VTS) provides extensive new functionality for
-Android testing and promotes a test-driven development process. This section
-describes the testing tools and resources available to help the Android
-development community interact with test data.</p>
-<p><a href="/devices/tech/vts/index.html">» VTS Information</a>
-</p>
+<p>Use the horizontal menu above to delve into specific subtabs and
+sections.</p>
</body>
</html>
diff --git a/en/devices/tech/ota/index.html b/en/devices/tech/ota/index.html
index 7b2f0dd..946a6f4 100644
--- a/en/devices/tech/ota/index.html
+++ b/en/devices/tech/ota/index.html
@@ -35,6 +35,17 @@
applications installed by the user from Google Play.
</p>
+ <p>
+ The Android Open Source Project (AOSP) includes a
+ <a href="https://android.googlesource.com/platform/bootable/recovery/+/master/updater_sample/"
+ class="external">SystemUpdaterSample</a> app that gives examples on
+ how to use Android system update APIs to install OTA updates. The sample
+ app is an example on how to use <code>update_engine</code> for A/B
+ updates.
+ For more information, see <a href="https://android.googlesource.com/platform/bootable/recovery/+/master/updater_sample/README.md"
+ class="external"><code>updater_sample/README.md</code></a>.
+ </p>
+
<h2 id="ab_updates">A/B (seamless) system updates</h2>
<p>
diff --git a/en/devices/tech/perf/apk-caching.html b/en/devices/tech/perf/apk-caching.html
new file mode 100644
index 0000000..4523afa
--- /dev/null
+++ b/en/devices/tech/perf/apk-caching.html
@@ -0,0 +1,284 @@
+<html devsite>
+ <head>
+ <title>APK Caching</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>
+This document describes design of an APK caching solution for rapid installation
+of preloaded apps on a device that supports A/B partitions.
+</p>
+
+<p>
+OEMs can place preloads and popular apps in the APK cache stored in the mostly
+empty B partition on new <a
+href="/devices/tech/ota/ab_updates">A/B-partitioned</a> devices without impacting
+any user-facing data space. By having an APK cache available on the device, new or
+recently factory reset devices are ready for use almost immediately, without
+needing to download APK files from Google Play.
+</p>
+
+<h2 id="use-cases">Use cases</h2>
+
+<ul>
+<li>Store preloaded apps in B partition for faster setup
+<li>Store popular apps in B partition for faster restoration
+</ul>
+
+<h2 id="prerequisites">Prerequisites</h2>
+
+<p>
+To use this feature, the device needs:
+</p>
+
+<ul>
+<li>Android 8.1 (O MR1) release installed
+<li>A/B partition implemented</li>
+</ul>
+
+<p>
+Preloaded content can be copied only during first boot. This is because on
+devices supporting A/B system updates, the B partition doesn't actually store
+system image files, but instead preloaded content like retail demo resources,
+OAT files and the APK cache. After resources have been copied to the /data
+partition (this happens on first boot), the B partition will be used by <a
+href="/devices/tech/ota/">over-the-air (OTA)
+updates</a> for downloading updated versions of the system image.
+</p>
+
+<p>
+Therefore, the APK cache cannot be updated through OTA; it can be preloaded only
+at a factory. Factory reset affects only the /data partition. The system B
+partition still has the preloaded content until the OTA image is downloaded.
+After factory reset, the system will go through first boot again. This means APK
+caching is not available if the OTA image is downloaded to the B partition, and
+then the device is factory reset.
+</p>
+
+<h2 id="implementation">Implementation</h2>
+
+<h3 id="approach-1-content-on-system_other-partition">Approach 1. Content on
+system_other partition</h3>
+
+<p>
+<strong>Pro</strong>: Preloaded content is not lost after factory reset - it
+will be copied from the B partition after a reboot.
+</p>
+
+<p>
+<strong>Con</strong>: Requires space on B partition. Boot after factory reset
+requires additional time to copy preloaded content.
+</p>
+
+<p>
+In order for preloads to be copied during first boot, the system calls a script
+in <code>/system/bin/preloads_copy.sh</code>. The script is called with a single
+argument (path to the read-only mount point for <code>system_b</code>
+partition):
+</p>
+
+<p>
+To implement this feature, make these device-specific changes. Here is an
+example from Marlin:
+</p>
+
+<ol>
+ <li>Add the script that does the copying to the <code>device-common.mk</code>
+file (in this case, <code>device/google/marlin/device-common.mk</code>), like so:
+
+<pre class="devsite-click-to-copy">
+# Script that copies preloads directory from system_other to data partition
+PRODUCT_COPY_FILES += \
+ device/google/marlin/preloads_copy.sh:system/bin/preloads_copy.sh
+</pre>
+
+Find example script source at: <a
+href="https://android.googlesource.com/device/google/marlin/+/master/preloads_copy.sh">device/google/marlin/preloads_copy.sh</a>
+</li>
+
+<li> Edit the <code>init.common.rc</code> file to have it create the
+necessary<code> /data/preloads</code> directory and subdirectories:
+
+<pre class="devsite-click-to-copy">
+<code class="devsite-terminal">mkdir /data/preloads 0775 system system</code>
+<code class="devsite-terminal">mkdir /data/preloads/media 0775 system system</code>
+<code class="devsite-terminal">mkdir /data/preloads/demo 0775 system system</code>
+</pre>
+
+Find example <code>init</code> file source at: <a
+href="https://android.googlesource.com/device/google/marlin/+/master/init.common.rc">device/google/marlin/init.common.rc</a>
+</li>
+
+<li>Define a new SELinux domain in the file <code>preloads_copy.te</code>:
+
+<pre class="devsite-click-to-copy">
+type preloads_copy, domain, coredomain;
+type preloads_copy_exec, exec_type, vendor_file_type, file_type;
+
+init_daemon_domain(preloads_copy)
+
+allow preloads_copy shell_exec:file rx_file_perms;
+allow preloads_copy toolbox_exec:file rx_file_perms;
+allow preloads_copy preloads_data_file:dir create_dir_perms;
+allow preloads_copy preloads_data_file:file create_file_perms;
+allow preloads_copy preloads_media_file:dir create_dir_perms;
+allow preloads_copy preloads_media_file:file create_file_perms;
+
+# Allow to copy from /postinstall
+allow preloads_copy system_file:dir r_dir_perms;
+</pre>
+
+Find an example SELinux domain file at: <a
+href="https://android.googlesource.com/device/google/marlin/+/master/sepolicy/preloads_copy.te">/device/google/marlin/+/master/sepolicy/preloads_copy.te</a>
+</li>
+
+<li>Register the domain in a new <code><device>/sepolicy/file_contexts</code>
+file:
+
+<pre class="devsite-click-to-copy">
+/system/bin/preloads_copy\.sh u:object_r:preloads_copy_exec:s0
+</pre>
+
+Find an example SELinux contexts file at: <a
+href="https://android.googlesource.com/device/google/marlin/+/master/sepolicy/preloads_copy.te">device/google/marlin/sepolicy/preloads_copy.te</a>
+</li>
+
+<li>At build time, the directory with preloaded content must be copied to the
+<code>system_other</code> partition:
+
+<pre class="devsite-click-to-copy">
+# Copy contents of preloads directory to system_other partition
+PRODUCT_COPY_FILES += \
+ $(call find-copy-subdir-files,*,vendor/google_devices/marlin/preloads,system_other/preloads)
+</pre>
+
+This is an example of a change in a Makefile that allows copying APK cache
+resources from vendor's Git repository (in our case it was
+vendor/google_devices/marlin/preloads) to the location on system_other partition
+that will later be copied to /data/preloads when device boots for the first
+time. This script runs at build time to prepare system_other image. It expects
+preloaded content to be available in vendor/google_devices/marlin/preloads. OEM
+is free to choose the actual repository name/path.
+</li>
+
+<li>The APK cache is located in <code>/data/preloads/file_cache</code> and has
+the following layout:
+
+<pre>
+/data/preloads/file_cache/
+ app.package.name.1/
+ file1
+ fileN
+ app.package.name.N/
+</pre>
+
+This is the final directory structure on the devices. OEMs are free to choose
+any implementation approach as long as the final file structure replicates the
+one described above.
+</li>
+</ol>
+
+<h3 id="approach-2-content-on-user-data-image">Approach 2. Content on user data
+image flashed at factory</h3>
+
+<p>
+This alternative approach assumes that preloaded content is already included in
+the <code>/data/preloads</code> directory on the <code>/data</code> partition.
+</p>
+
+<p>
+<strong>Pro</strong>: Works out of the box - no need to make device
+customizations to copy files on first boot. Content is already on the
+<code>/data</code> partition.
+</p>
+
+<p>
+<strong>Con</strong>: Preloaded content is lost after a factory reset. While
+this may be acceptable for some, it may not always work for OEMs who factory
+reset devices after doing quality control inspections.
+</p>
+
+<p>
+A new @SystemApi method, <code>getPreloadsFileCache()</code>, was added to
+<code>android.content.Context</code>. It returns an absolute path to an
+application-specific directory in the preloaded cache.
+</p>
+
+<p>
+A new method, <code>IPackageManager.deletePreloadsFileCache</code>, was added
+that allows deleting the preloads directory to reclaim all space. The method can
+be called only by apps with SYSTEM_UID, i.e. system server or Settings.
+</p>
+
+<h2 id="app-preparation">App preparation</h2>
+
+<p>
+Only privileged applications can access the preloads cache directory. For that
+access, apps must be installed in the<code> /system/priv-app</code> directory.
+</p>
+
+<h2 id="validation">Validation</h2>
+
+<ul>
+<li>After first boot, the device should have content in the
+<code>/data/preloads/file_cache</code> directory.
+<li>The content in the <code>file_cache/</code> directory must be deleted if the
+device runs low on storage.</li>
+</ul>
+
+<p>Use the example <a
+href="https://android.googlesource.com/platform/development/+/master/samples/apkcachetest/">ApkCacheTest</a>
+ app for testing APK cache.</p>
+
+<ol>
+<li>Build the app by running this command from the root directory:
+<pre class="devsite-click-to-copy">
+<code class="devsite-terminal">make ApkCacheTest</code>
+</pre>
+</li>
+
+<li>Install the app as a privileged application. (Remember, only privileged apps can access the APK cache.) This requires a rooted device:
+<pre class="devsite-click-to-copy">
+<code class="devsite-terminal">adb root && adb remount</code>
+<code class="devsite-terminal">adb shell mkdir /system/priv-app/ApkCacheTest</code>
+<code class="devsite-terminal">adb push $ANDROID_PRODUCT_OUT/data/app/ApkCacheTest/ApkCacheTest.apk /system/priv-app/ApkCacheTest/</code>
+<code class="devsite-terminal">adb shell stop && adb shell start</code>
+</pre>
+</li>
+
+<li>Simulate the file cache directory and its content if neeeded (also requiring root privileges):
+<pre class="devsite-click-to-copy">
+<code class="devsite-terminal">adb shell mkdir -p /data/preloads/file_cache/com.android.apkcachetest</code>
+<code class="devsite-terminal">adb shell restorecon -r /data/preloads</code>
+<code class="devsite-terminal">adb shell "echo "Test File" > /data/preloads/file_cache/com.android.apkcachetest/test.txt"</code>
+</pre>
+</li>
+
+<li>Test the app. After installing the app and creating test <code>file_cache</code> directory, open the ApkCacheTest app. It should show one file <code>test.txt</code> and its contents. See this screenshot to see how these results appear in the user interface.
+
+<p><img src="/devices/tech/perf/images/apk_cache_test_results.png"></p>
+<figcaption><strong>Figure 1.</strong> ApkCacheTest results</figcaption>
+</li>
+</ol>
+
+</body>
+</html>
diff --git a/en/devices/tech/perf/boot-times.html b/en/devices/tech/perf/boot-times.html
index fb6ad44..197b7ff 100644
--- a/en/devices/tech/perf/boot-times.html
+++ b/en/devices/tech/perf/boot-times.html
@@ -385,11 +385,11 @@
Use the following scripts to help with analyzing boot performance.
</p>
<ul>
-<li><code>packages/services/Car/tools/bootanalyze/bootanalyze.py</code>
+<li><code>system/extras/boottime_tools/bootanalyze/bootanalyze.py</code>
Measures boot time with a breakdown of important steps in the boot process.
-<li><code>packages/services/Car/tools/io_analysis/check_file_read.py
+<li><code>system/extras/boottime_tools/io_analysis/check_file_read.py
boot_trace</code> Provides access information per each file.
-<li><code>packages/services/Car/tools/io_analysis/check_io_trace_all.py
+<li><code>system/extras/boottime_tools/io_analysis/check_io_trace_all.py
boot_trace</code> Gives system-level breakdown.</li>
</ul>
diff --git a/en/devices/tech/perf/compatibility-wal.md b/en/devices/tech/perf/compatibility-wal.md
new file mode 100644
index 0000000..20d7f85
--- /dev/null
+++ b/en/devices/tech/perf/compatibility-wal.md
@@ -0,0 +1,80 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Compatibility WAL (Write-Ahead Logging) for Apps
+
+Android {{ androidPVersionNumber }} introduces a special mode of
+[SQLiteDatabase](https://developer.android.com/reference/android/database/sqlite/SQLiteDatabase.html){: .external}
+called Compatibility WAL (write-ahead logging) that allows a database to use
+`journal_mode=WAL` while preserving the behavior of keeping a maximum of one
+connection per database.
+
+Compatibility WAL is enabled for an application's database by default unless the
+application has either:
+
+1. Opted-in or out of write-ahead logging by calling
+ [`SQLiteDatabase.enableWriteAheadLogging`](https://developer.android.com/reference/android/database/sqlite/SQLiteDatabase.html#enableWriteAheadLogging\(\)){: .external}
+ or
+ [`disableWriteAheadLogging`](https://developer.android.com/reference/android/database/sqlite/SQLiteDatabase.html#disableWriteAheadLogging\(\)){: .external}
+1. Explicitly requested journal mode by calling
+ `SQLiteDatabase.OpenParams.setJournalMode(String mode)`
+
+Enabling the WAL journal mode can lead to a significant improvement in
+performance and reduction in the amount of writes. For example, on an ext4
+filesystem, WAL can lead to a 4x improvement in write speed.
+
+Compatibility WAL is enabled by default and doesn't require any additional
+implementation.
+
+Note: For applications using
+[Room](https://developer.android.com/topic/libraries/architecture/room),
+full write-ahead logging mode (not Compatibility WAL) is enabled by
+default. This applies to devices running API 16 and higher and are not
+categorized as a
+[low memory device](https://developer.android.com/reference/android/app/ActivityManager.html#isLowRamDevice()). For more information, see
+[`RoomDatabase.JournalMode AUTOMATIC`](https://developer.android.com/reference/androidx/room/RoomDatabase.JournalMode#AUTOMATIC).
+
+## Disabling Compatibility WAL
+
+To disable the Compatibility WAL mode, overlay the
+[`db_compatibility_wal_supported`](https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml#1844){: .external}
+config resource.
+
+For example:
+
+```
+<bool name="db_compatibility_wal_supported">false</bool>
+```
+
+You may want to disable Compatibility WAL for configurations where the WAL
+journal mode does not provide a performance advantage over traditional rollback
+journal modes. For example, on a F2FS filesystem, although SQLite supports
+atomic writes and the DELETE journal performance is similar to WAL, WAL can
+increase the amount of writes by 10% to 15%.
+
+## Validation
+
+To validate the Compatibility WAL mode, run
+[CTS tests](https://android.googlesource.com/platform/cts/+/master/tests/tests/database){: .external}
+from the CtsDatabaseTestCases module. CTS tests will verify the expected
+behavior when Compatibility WAL is enabled.
+
+Note: CTS tests pass when the Compatibility WAL mode is disabled.
diff --git a/en/devices/tech/perf/images/apk_cache_test_results.png b/en/devices/tech/perf/images/apk_cache_test_results.png
new file mode 100644
index 0000000..9a27b43
--- /dev/null
+++ b/en/devices/tech/perf/images/apk_cache_test_results.png
Binary files differ
diff --git a/en/devices/tech/perf/pgo.html b/en/devices/tech/perf/pgo.html
new file mode 100644
index 0000000..36bff93
--- /dev/null
+++ b/en/devices/tech/perf/pgo.html
@@ -0,0 +1,539 @@
+<html devsite>
+<head>
+ <title>Using Profile-Guided Optimization (PGO)</title>
+ <meta name="project_path" value="/_project.yaml">
+ <meta name="book_path" value="/_book.yaml">
+</head>
+
+<body>
+ <!--
+ Copyright 2018 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 Android build system supports using Clang's <a href=
+ "https://clang.llvm.org/docs/UsersManual.html#profile-guided-optimization">profile-guided
+ optimization (PGO)</a> on native Android modules that have <a href=
+ "https://android.googlesource.com/platform/build/soong/">blueprint</a> build
+ rules. This page describes Clang PGO, how to continually generate and update
+ profiles used for PGO, and how to integrate PGO with the build system (with
+ use case).</p>
+
+
+ <h2 id="about-clang-pgo">About Clang PGO</h2>
+
+
+ <p>Clang can perform profile-guided optimization using two types of
+ profiles:</p>
+
+
+ <ul>
+ <li><strong>Instrumentation-based profiles</strong> are generated from an
+ instrumented target program. These profiles are detailed and impose a high
+ runtime overhead.</li>
+
+
+ <li><strong>Sampling-based profiles</strong> are typically produced by
+ sampling hardware counters. They impose a low runtime overhead, and can be
+ collected without any instrumentation or modification to the binary. They
+ are less detailed than instrumentation-based profiles.</li>
+ </ul>
+
+
+ <p>All profiles should be generated from a representative workload that
+ exercises the typical behavior of the application. While Clang supports both
+ AST-based (<code>-fprofile-instr-generate</code>) and LLVM IR-based
+ (<code>-fprofile-generate)</code>, Android supports only LLVM IR-based for
+ instrumentation-based PGO.</p>
+
+
+ <p>The following flags are needed to build for profile collection:</p>
+
+
+ <ul>
+ <li><code>-fprofile-generate</code> for IR-based instrumentation. With this
+ option, the backend uses a weighted minimal spanning tree approach to
+ reduce the number of instrumentation points and optimize their placement to
+ low-weight edges (use this option for the link step as well). The Clang
+ driver automatically passes the profiling runtime
+ (<code>libclang_rt.profile-<em>arch</em>-android.a</code>) to the linker.
+ This library contains routines to write the profiles to disk upon program
+ exit.</li>
+
+
+ <li><code>-gline-tables-only</code> for sampling-based profile collection
+ to generate minimal debug information.</li>
+ </ul>
+
+
+ <p>A profile can be used for PGO using
+ <code>-fprofile-instr-use=<em>pathname</em></code> or
+ <code>-fprofile-sample-use=<em>pathname</em></code> for instrumentation-based
+ and sampling-based profiles respectively.</p>
+
+
+ <p><strong>Note:</strong> As changes are made to the code, if Clang can no
+ longer use the profile data it generates a
+ <code>-Wprofile-instr-out-of-date</code> warning.</p>
+
+
+ <h2 id="using-pgo">Using PGO</h2>
+
+
+ <p>Using PGO involves the following steps:</p>
+
+
+ <ol>
+ <li>Build the library/executable with instrumentation by passing
+ <code>-fprofile-generate</code> to the compiler and linker.</li>
+
+
+ <li>Collect profiles by running a representative workload on the
+ instrumented binary.</li>
+
+
+ <li>Post-process the profiles using the <code>llvm-profdata</code> utility
+ (for details, see <a href="#handling-llvm-profile-files">Handling LLVM
+ profile files</a>).</li>
+
+
+ <li>Use the profiles to apply PGO by passing
+ <code>-fprofile-use=<>.profdata</code> to the compiler and
+ linker.</li>
+ </ol>
+
+
+ <p>For PGO in Android, profiles should be collected offline and checked in
+ alongside the code to ensure reproducible builds. The profiles can be used as
+ code evolves, but must be regenerated periodically (or whenever Clang warns
+ that the profiles are stale).</p>
+
+
+ <h3 id="collecting-profiles">Collecting profiles</h3>
+
+
+ <p>Clang can use profiles collected by running benchmarks using an
+ instrumented build of the library or by sampling hardware counters when the
+ benchmark is run. At this time, Android does not support using sampling-based
+ profile collection, so you must collect profiles using an instrumented
+ build:</p>
+
+
+ <ol>
+ <li>Identify a benchmark and the set of libraries collectively exercised by
+ that benchmark.</li>
+
+
+ <li>Add <code>pgo</code> properties to the benchmark and libraries (details
+ below).</li>
+
+
+ <li>Produce an Android build with an instrumented copy of these libraries
+ using:
+
+ <pre class="prettyprint">make ANDROID_PGO_INSTRUMENT=benchmark</pre>
+ </li>
+ </ol>
+
+
+ <p><code><em>benchmark</em></code> is a placeholder that identifies the
+ collection of libraries instrumented during build. The actual representative
+ inputs (and possibly another executable that links against a library being
+ benchmarked) are not specific to PGO and are beyond the scope of this
+ document.</p>
+
+
+ <ol>
+ <li>Flash or sync the instrumented build on a device.</li>
+
+
+ <li>Run the benchmark to collect profiles.</li>
+
+
+ <li>Use the <code>llvm-profdata</code> tool (discussed below) to
+ post-process the profiles and make them ready to be checked into the source
+ tree.</li>
+ </ol>
+
+
+ <h3 id="using-profiles-during-build">Using profiles during build</h3>
+
+
+ <p>Check the profiles into <code>toolchain/pgo-profiles</code> in an Android
+ tree. The name should match what is specified in the
+ <code>profile_file</code> sub-property of the <code>pgo</code> property for
+ the library. The build system automatically passes the profile file to Clang
+ when building the library. The <code>ANDROID_PGO_DISABLE_PROFILE_USE</code>
+ environment variable can be set to <strong><code>true</code></strong> to
+ temporarily disable PGO and measure its performance benefit.</p>
+
+
+ <p>To specify additional product-specific profile directories, append them to
+ the <code>PGO_ADDITIONAL_PROFILE_DIRECTORIES</code> make variable in a
+ <code>BoardConfig.mk</code>. If additional paths are specified, profiles in
+ these paths override those in <code>toolchain/pgo-profiles</code>.</p>
+
+
+ <p>When generating a release image using the <code>dist</code> target to
+ <code>make</code>, the build system writes the names of missing profile files
+ to <code>$DIST_DIR/pgo_profile_file_missing.txt</code>. You can check this
+ file to see what profile files were accidentally dropped (which silently
+ disables PGO).</p>
+
+
+ <h2 id="enabling-pgo-in-android-bp-files">Enabling PGO in Android.bp
+ files</h2>
+
+
+ <p>To enable PGO in <code>Android.bp</code> files for native modules, simply
+ specify the <code>pgo</code> property. This property has the following
+ sub-properties:</p>
+
+
+ <table>
+ <tr>
+ <th><strong>Property</strong>
+ </th>
+
+ <th><strong>Description</strong>
+ </th>
+ </tr>
+
+
+ <tr>
+ <td><code>instrumentation</code>
+ </td>
+
+ <td>Set to <code>true</code> for PGO using instrumentation. Default is
+ <code>false</code>.</td>
+ </tr>
+
+
+ <tr>
+ <td><code>sampling</code>
+ </td>
+
+ <td><strong>Currently unsupported.</strong> Set to <code>true</code> for
+ PGO using sampling. Default is <code>false</code>.</td>
+ </tr>
+
+
+ <tr>
+ <td><code>benchmarks</code>
+ </td>
+
+ <td>List of strings. This module is built for profiling if any benchmark
+ in the list is specified in the <code>ANDROID_PGO_INSTRUMENT</code> build
+ option.</td>
+ </tr>
+
+
+ <tr>
+ <td><code>profile_file</code>
+ </td>
+
+ <td>Profile file (relative to <code>toolchain/pgo-profile</code>) to use
+ with PGO. The build warns that this file doesn't exist by adding this
+ file to <code>$DIST_DIR/pgo_profile_file_missing.txt</code>
+ <em>unless</em> the <code>enable_profile_use</code> property is set to
+ <code>false</code> <strong>OR</strong> the
+ <code>ANDROID_PGO_NO_PROFILE_USE</code> build variable is set to
+ <code>true</code>.</td>
+ </tr>
+
+
+ <tr>
+ <td><code>enable_profile_use</code>
+ </td>
+
+ <td>Set to <code>false</code> if profiles should not be used during
+ build. Can be used during bootstrap to enable profile collection or to
+ temporarily disable PGO. Default is <code>true</code>.</td>
+ </tr>
+
+
+ <tr>
+ <td><code>cflags</code>
+ </td>
+
+ <td>List of additional flags to use during an instrumented build.</td>
+ </tr>
+ </table>
+
+
+ <p>Example of a module with PGO:</p>
+
+<pre class="prettyprint">cc_library {
+ name: "libexample",
+ srcs: [
+ "src1.cpp",
+ "src2.cpp",
+ ],
+ static: [
+ "libstatic1",
+ "libstatic2",
+ ],
+ shared: [
+ "libshared1",
+ ]
+ pgo: {
+ instrumentation: true,
+ benchmarks: [
+ "benchmark1",
+ "benchmark2",
+ ],
+ profile_file: "example.profdata",
+ }
+}
+</pre>
+
+
+
+ <p>If the benchmarks <code>benchmark1</code> and <code>benchmark2</code>
+ exercise representative behavior for libraries <code>libstatic1</code>,
+ <code>libstatic2</code>, or <code>libshared1</code>, the <code>pgo</code>
+ property of these libraries can also include the benchmarks. The
+ <code>defaults</code> module in <code>Android.bp</code> can include a common
+ <code>pgo</code> specification for a set of libraries to avoid repeating the
+ same build rules for several modules.</p>
+
+
+ <p>To select different profile files or selectively disable PGO for an
+ architecture, specify the <code>profile_file</code>,
+ <code>enable_profile_use</code>, and <code>cflags</code> properties per
+ architecture. Example (with architecture target in
+ <strong>bold</strong>):</p>
+
+<pre class="prettyprint">cc_library {
+ name: "libexample",
+ srcs: [
+ "src1.cpp",
+ "src2.cpp",
+ ],
+ static: [
+ "libstatic1",
+ "libstatic2",
+ ],
+ shared: [
+ "libshared1",
+ ],
+ pgo: {
+ instrumentation: true,
+ benchmarks: [
+ "benchmark1",
+ "benchmark2",
+ ],
+ }
+
+ <strong>target: {
+ android_arm: {
+ pgo: {
+ profile_file: "example_arm.profdata",
+ }
+ },
+ android_arm64: {
+ pgo: {
+ profile_file: "example_arm64.profdata",
+ }
+ }
+ }
+}</strong>
+</pre>
+
+
+ <p>To resolve references to the profiling runtime library during
+ instrumentation-based profiling, pass the build flag
+ <code>-fprofile-generate</code> to the linker. Static libraries instrumented
+ with PGO, all shared libraries, and any binary that directly depends on the
+ static library must also be instrumented for PGO. However, such shared
+ libraries or executables don't need to use PGO profiles, and their
+ <code>enable_profile_use</code> property can be set to <code>false</code>.
+ Outside of this restriction, you can apply PGO to any static library, shared
+ library, or executable.</p>
+
+
+ <h2 id="handling-llvm-profile-files">Handling LLVM profile files</h2>
+
+
+ <p>Executing an instrumented library or executable produces a profile file
+ named <code>default_<em>unique_id</em>_0.profraw</code> in
+ <code>/data/local/tmp</code> (where <code><em>unique_id</em></code> is a
+ numeric hash that is unique to this library). If this file already exists,
+ the profiling runtime merges the new profile with the old one while writing
+ the profiles. To change the location of the profile file, set the
+ <code>LLVM_PROFILE_FILE</code> environment variable at runtime.</p>
+
+
+ <p>The <code><a href=
+ "https://llvm.org/docs/CommandGuide/llvm-profdata.html">llvm-profdata</a></code>
+ utility is then used to convert the <code>.profraw</code> file (and possibly
+ merge multiple <code>.profraw</code> files) to a <code>.profdata</code>
+ file:</p>
+
+ <pre class="prettyprint">
+ llvm-profdata merge -output=profile.profdata <.profraw and/or .profdata files></pre>
+
+ <p><code><em>profile.profdata</em></code> can then be checked into the source
+ tree for use during build.</p>
+
+
+ <p>If multiple instrumented binaries/libraries are loaded during a benchmark,
+ each library generates a separate <code>.profraw</code> file with a separate
+ unique ID. Typically, all of these files can be merged to a single
+ <code>.profdata</code> file and used for PGO build. In cases where a library
+ is exercised by another benchmark, that library must be optimized using
+ profiles from both the benchmarks. In this situation, the <code>show</code>
+ option of <code>llvm-profdata</code> is useful:</p>
+
+ <pre class="prettyprint">
+ llvm-profdata merge -output=default_unique_id.profdata default_unique_id_0.profraw
+llvm-profdata show -all-functions default_unique_id.profdata</pre>
+
+ <p>To map <em>unique_id</em>s to individual libraries, search the
+ <code>show</code> output for each <em>unique_id</em> for a function name that
+ is unique to the library.</p>
+
+
+ <h2 id="case-study-pgo-for-art">Case Study: PGO for ART</h2>
+
+
+ <p><em>The case study presents ART as a relatable example; however, it is not
+ an accurate description of the actual set of libraries profiled for ART or
+ their interdependencies.</em>
+ </p>
+
+
+ <p>The <code>dex2oat</code> ahead-of-time compiler in ART depends on
+ <code>libart-compiler.so</code>, which in turn depends on
+ <code>libart.so</code>. The ART runtime is implemented mainly in
+ <code>libart.so</code>. Benchmarks for the compiler and the runtime will be
+ different:</p>
+
+
+ <table>
+ <tr>
+ <th><strong>Benchmark</strong>
+ </th>
+
+ <th><strong>Profiled libraries</strong>
+ </th>
+ </tr>
+
+
+ <tr>
+ <td><code>dex2oat</code>
+ </td>
+
+ <td><code>dex2oat</code> (executable), <code>libart-compiler.so</code>,
+ <code>libart.so</code></td>
+ </tr>
+
+
+ <tr>
+ <td><code>art_runtime</code>
+ </td>
+
+ <td><code>libart.so</code>
+ </td>
+ </tr>
+ </table>
+
+
+ <ol>
+ <li>Add the following <code>pgo</code> property to <code>dex2oat</code>,
+ <code>libart-compiler.so</code>:
+
+ <pre class="prettyprint"> pgo: {
+ instrumentation: true,
+ benchmarks: ["dex2oat",],
+ profile_file: "dex2oat.profdata",
+ }</pre>
+ </li>
+
+ <li>Add the following <code>pgo</code> property to <code>libart.so</code>:
+
+ <pre class="prettyprint"> pgo: {
+ instrumentation: true,
+ benchmarks: ["art_runtime", "dex2oat",],
+ profile_file: "libart.profdata",
+ }</pre>
+ </li>
+
+ <li>Create instrumented builds for the <code>dex2oat</code> and
+ <code>art_runtime</code> benchmarks using:
+
+ <pre class="prettyprint"> make ANDROID_PGO_INSTRUMENT=dex2oat
+ make ANDROID_PGO_INSTRUMENT=art_runtime</pre>
+ </li>
+
+
+ <p>Alternatively, create a single instrumented build with all libraries
+ instrumented using:</p>
+
+ <pre class="prettyprint"> make ANDROID_PGO_INSTRUMENT=dex2oat,art_runtime
+ (or)
+ make ANDROID_PGO_INSTRUMENT=ALL</pre>
+
+ <p>The second command builds <strong>all</strong> PGO-enabled modules for
+ profiling.</p>
+
+ <li>Run the benchmarks exercising <code>dex2oat</code> and
+ <code>art_runtime</code> to obtain:
+
+ <ul>
+
+ <li>Three <code>.profraw</code> files from <code>dex2oat</code>
+ (<code>dex2oat_exe.profdata</code>,
+ <code>dex2oat_libart-compiler.profdata</code>, and
+ <code>dexeoat_libart.profdata</code>), identified using the method
+ described in <a href="#handling-llvm-profile-files">Handling LLVM profile
+ files</a>.</li>
+
+ <li>A single <code>art_runtime_libart.profdata</code>.</li>
+ </ul>
+ </li>
+
+ <li>Produce a common profdata file for <code>dex2oat</code> executable and
+ <code>libart-compiler.so</code> using:
+
+ <pre class="prettyprint">llvm-profdata merge -output=dex2oat.profdata \
+ dex2oat_exe.profdata dex2oat_libart-compiler.profdata</pre>
+ </li>
+
+ <li>Obtain the profile for <code>libart.so</code> by merging the profiles
+ from the two benchmarks:
+
+ <pre class="prettyprint">llvm-profdata merge -output=libart.profdata \
+ dex2oat_libart.profdata art_runtime_libart.profdata</pre>
+
+ <p>The raw counts for <code>libart.so</code> from the two profiles might be
+ disparate because the benchmarks differ in the number of test cases and the
+ duration for which they run. In this case, you can use a weighted merge:</p>
+
+ <pre class="prettyprint">llvm-profdata merge -output=libart.profdata \
+ -weighted-input=2,dex2oat_libart.profdata \
+ -weighted-input=1,art_runtime_libart.profdata</pre>
+
+ <p>The above command assigns twice the weight to the profile from
+ <code>dex2oat</code>. The actual weight should be determined based on domain
+ knowledge or experimentation.</p>
+ </li>
+
+ <li>Check the profile files <code>dex2oat.profdata</code> and
+ <code>libart.profdata</code> into <code>toolchain/pgo-profiles</code> for
+ use during build.</li>
+ </ol>
+</body>
+</html>
diff --git a/en/devices/tech/power/app_mgmt.html b/en/devices/tech/power/app_mgmt.html
new file mode 100644
index 0000000..7d4e871
--- /dev/null
+++ b/en/devices/tech/power/app_mgmt.html
@@ -0,0 +1,361 @@
+<html devsite>
+ <head>
+ <title>Application Power Management</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ <body>
+ <!--
+ Copyright 2018 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>
+ In Android 9 and later, the platform can monitor apps for behavior that
+ negatively affects the battery life of devices. The platform uses and
+ evaluates setup rules to provide a UX flow that gives users the option to
+ restrict apps that violate the rules.
+ </p>
+
+ <p>
+ In Android 8.0 and earlier, there were restrictions via features
+ such as Doze, App Standby, background limits, and background location
+ limits. However, some apps continued to exhibit bad behaviors, some of
+ which are described in <a
+ href="https://developer.android.com/topic/performance/vitals/" class="external">Android vitals</a>.
+ Android 9 introduces an OS infrastructure that can detect and restrict
+ apps based on setup rules that can be updated over time.
+ </p>
+
+ <h2 id="app-restrictions">Background Restrictions</h2>
+
+ <p>
+ Users can choose to restrict apps, or the system may suggest apps that it
+ detects are negatively impacting the health of the device.
+ </p>
+
+ <p>
+ Restricted apps:
+ </p>
+
+ <ul>
+ <li>Can still be launched by the user.</li>
+ <li>Cannot run jobs/alarms or use network in the background.</li>
+ <li>Cannot run foreground services.</li>
+ <li>Can be changed to an unrestricted app by the user.</li>
+ </ul>
+
+ <p>
+ Device implementers can add additional restrictions to apps to:
+ </p>
+
+ <ul>
+ <li>Restrict the app from self restarts.</li>
+ <li>Restrict services from being bound (highly risky).</li>
+ </ul>
+
+ <p>
+ Restricted apps are not expected to consume any device resources, such as
+ memory, CPU, and battery, when they are in the background. Background
+ restricted apps should not impact the device health when the user is not
+ actively using those apps. However, the same apps are expected to be
+ fully functional when the user launches the apps.
+ </p>
+
+
+ <h3 id="using-customg-restrictions">Using custom implementations</h3>
+
+ <p>
+ Device implementers can continue to use their custom methods to apply
+ restrictions on the apps.
+ </p>
+
+ <aside class="caution"><strong>Caution:</strong> Future releases may break
+ device implementers' customizations. We recommend adopting the Android
+ 9 App Restrictions architecture in AOSP.
+ </aside>
+
+ <h3 id="integrating-app-restrictions">Integrating App Restrictions</h3>
+
+ <p>
+ The following sections outline how to define and integrate app
+ restrictions on your device. If you are using app restriction methods
+ from Android 8.x or earlier, review the following sections closely for
+ changes in Android 9.
+ </p>
+
+ <h4 id="set-appopsmanager-flag">Set the AppOpsManager flag</h4>
+
+ <p>
+ When an app is restricted, set the appropriate flag in
+ <code>AppOpsManager</code>. An example code snippet from
+ <code>packages/apps/Settings/src/com/android/settings/fuelgauge/BatteryUtils.java</code>:
+ </p>
+
+<pre class="prettyprint"> public void setForceAppStandby(int uid, String packageName,
+ int mode) {
+ final boolean isPreOApp = isPreOApp(packageName);
+ if (isPreOApp) {
+ // Control whether app could run in the background if it is pre O app
+ mAppOpsManager.setMode(AppOpsManager.OP_RUN_IN_BACKGROUND, uid, packageName, mode);
+ }
+ // Control whether app could run jobs in the background
+ mAppOpsManager.setMode(AppOpsManager.OP_RUN_ANY_IN_BACKGROUND, uid, packageName, mode);
+ }
+</pre>
+
+ <h4 id="ensure-isbackgroundrestricted-returns-true">
+ Ensure <code>isBackgroundRestricted</code> returns <code>true</code>
+ </h4>
+
+ <p>
+ When an app is restricted, ensure that
+ <code>ActivityManager.isBackgroundRestricted()</code> returns
+ <code>true</code>.
+ </p>
+
+ <h4>Log the reason for restriction</h4>
+
+ <p>
+ When an app is restricted, log the reasons for the restriction. An
+ example code snippet of logging from
+ <code>packages/apps/Settings/src/com/android/settings/fuelgauge/batterytip/actions/RestrictAppAction.java</code>:
+ </p>
+
+
+
+<pre class="prettyprint">mBatteryUtils.setForceAppStandby(mBatteryUtils.getPackageUid(packageName), packageName,AppOpsManager.MODE_IGNORED);
+if (CollectionUtils.isEmpty(appInfo.anomalyTypes)) {
+ // Only log context if there is no anomaly type
+ mMetricsFeatureProvider.action(mContext,
+ MetricsProto.MetricsEvent.ACTION_TIP_RESTRICT_APP, packageName,
+ Pair.create(MetricsProto.MetricsEvent.FIELD_CONTEXT,metricsKey));
+ } else {
+ // Log ALL the anomaly types
+ for (int type : appInfo.anomalyTypes) {
+ mMetricsFeatureProvider.action(mContext,
+ MetricsProto.MetricsEvent.ACTION_TIP_RESTRICT_APP, packageName,
+ Pair.create(MetricsProto.MetricsEvent.FIELD_CONTEXT, metricsKey),
+ Pair.create(MetricsProto.MetricsEvent.FIELD_ANOMALY_TYPE, type));
+ }
+</pre>
+
+ <p>
+ The <code>type</code> should be replaced with the value from
+ <code>AnomalyType</code>.
+ </p>
+
+ <p>
+ Device implementers can use the constants defined in
+ <code>src/com/android/settings/fuelgauge/batterytip/StatsManagerConfig.java</code>:
+ </p>
+
+<pre class="prettyprint">public @interface AnomalyType {
+ // This represents an error condition in the anomaly detection.
+ int NULL = -1;
+ // The anomaly type does not match any other defined type.
+ int UNKNOWN_REASON = 0;
+ // The application held a partial (screen off) wake lock for a period of time that
+ // exceeded the threshold with the screen off when not charging.
+ int EXCESSIVE_WAKELOCK_ALL_SCREEN_OFF = 1;
+ // The application exceeded the maximum number of wakeups while in the background
+ // when not charging.
+ int EXCESSIVE_WAKEUPS_IN_BACKGROUND = 2;
+ // The application did unoptimized Bluetooth scans too frequently when not charging.
+ int EXCESSIVE_UNOPTIMIZED_BLE_SCAN = 3;
+ // The application ran in the background for a period of time that exceeded the
+ // threshold.
+ int EXCESSIVE_BACKGROUND_SERVICE = 4;
+ // The application exceeded the maximum number of wifi scans when not charging.
+ int EXCESSIVE_WIFI_SCAN = 5;
+ // The application exceed the maximum number of flash writes
+ int EXCESSIVE_FLASH_WRITES = 6;
+ // The application used more than the maximum memory, while not spending any time
+ // in the foreground.
+ int EXCESSIVE_MEMORY_IN_BACKGROUND = 7;
+ // The application exceeded the maximum percentage of frames with a render rate of
+ // greater than 700ms.
+ int EXCESSIVE_DAVEY_RATE = 8;
+ // The application exceeded the maximum percentage of frames with a render rate
+ // greater than 16ms.
+ int EXCESSIVE_JANKY_FRAMES = 9;
+ // The application exceeded the maximum cold start time - the app has not been
+ // launched since last system start, died or was killed.
+ int SLOW_COLD_START_TIME = 10;
+ // The application exceeded the maximum hot start time - the app and activity are
+ // already in memory.
+ int SLOW_HOT_START_TIME = 11;
+ // The application exceeded the maximum warm start time - the app was already in
+ // memory but the activity wasn't created yet or was removed from memory.
+ int SLOW_WARM_START_TIME = 12;
+ // The application exceeded the maximum number of syncs while in the background.
+ int EXCESSIVE_BACKGROUND_SYNCS = 13;
+ // The application exceeded the maximum number of gps scans while in the background.
+ int EXCESSIVE_GPS_SCANS_IN_BACKGROUND = 14;
+ // The application scheduled more than the maximum number of jobs while not charging.
+ int EXCESSIVE_JOB_SCHEDULING = 15;
+ // The application exceeded the maximum amount of mobile network traffic while in
+ // the background.
+ int EXCESSIVE_MOBILE_NETWORK_IN_BACKGROUND = 16;
+ // The application held the WiFi lock for more than the maximum amount of time while
+ // not charging.
+ int EXCESSIVE_WIFI_LOCK_TIME = 17;
+ // The application scheduled a job that ran longer than the maximum amount of time.
+ int JOB_TIMED_OUT = 18;
+ // The application did an unoptimized Bluetooth scan that exceeded the maximum
+ // time while in the background.
+ int LONG_UNOPTIMIZED_BLE_SCAN = 19;
+ // The application exceeded the maximum ANR rate while in the background.
+ int BACKGROUND_ANR = 20;
+ // The application exceeded the maximum crash rate while in the background.
+ int BACKGROUND_CRASH_RATE = 21;
+ // The application exceeded the maximum ANR-looping rate.
+ int EXCESSIVE_ANR_LOOPING = 22;
+ // The application exceeded the maximum ANR rate.
+ int EXCESSIVE_ANRS = 23;
+ // The application exceeded the maximum crash rate.
+ int EXCESSIVE_CRASH_RATE = 24;
+ // The application exceeded the maximum crash-looping rate.
+ int EXCESSIVE_CRASH_LOOPING = 25;
+ // The application crashed because no more file descriptors were available.
+ int NUMBER_OF_OPEN_FILES = 26;
+ }
+</pre>
+
+ <p>
+ When the user or the system removes an app's restrictions, you must
+ log the reasons for removing the restrictions. An example code
+ snippet of logging from
+ <code>packages/apps/Settings/src/com/android/settings/fuelgauge/batterytip/actions/UnrestrictAppAction.java</code>:
+ </p>
+
+<pre class="prettyprint"> public void handlePositiveAction(int metricsKey) {
+ final AppInfo appInfo = mUnRestrictAppTip.getUnrestrictAppInfo();
+ // Clear force app standby, then app can run in the background
+ mBatteryUtils.setForceAppStandby(appInfo.uid, appInfo.packageName,
+ AppOpsManager.MODE_ALLOWED);
+ mMetricsFeatureProvider.action(mContext,
+ MetricsProto.MetricsEvent.ACTION_TIP_UNRESTRICT_APP, appInfo.packageName,
+ Pair.create(MetricsProto.MetricsEvent.FIELD_CONTEXT, metricsKey));
+ }
+</pre>
+
+ <h3 id="testing-app-restrictions">Testing App Restrictions</h3>
+
+ <p>
+ To test the behavior of App Restrictions in Android 9.x and later,
+ use one of the following commands:
+ </p>
+
+ <ul>
+ <li>To put an app into App Restriction:
+ <pre class="devsite-terminal devsite-click-to-copy">appops set <var>package-name</var> RUN_ANY_IN_BACKGROUND ignore</pre>
+ </li>
+ <li>To take it out and restore the default behaviour:
+ <pre class="devsite-terminal devsite-click-to-copy">appops set <var>package-name</var> RUN_ANY_IN_BACKGROUND allow</pre>
+ </li>
+ <li>Make an app in the background go idle immediately:
+ <pre class="devsite-terminal devsite-click-to-copy">am make-uid-idle [--user <var>user-id</var> | all | current] <var>package-name</var></pre>
+ </li>
+ <li>Add a package to the <code>tempwhitelist</code> for a short duration:
+ <pre class="devsite-terminal devsite-click-to-copy">cmd deviceidle tempwhitelist [-u <var>user</var>] [-d <var>duration</var>] [package <var>package-name</var>]</pre>
+ </li>
+ <li>Add/Remove a package from the user whitelist:
+ <pre class="devsite-terminal devsite-click-to-copy">cmd deviceidle whitelist [+/-]<var>package-name</var></pre>
+ </li>
+ <li>To check internal state of jobscheduler and alarm manager:
+ <pre class="devsite-click-to-copy"><code class="devsite-terminal">dumpsys jobscheduler</code>
+<code class="devsite-terminal">dumpsys alarm</code></pre>
+ </li>
+ </ul>
+
+
+ <h2 id="app-standby">App Standby</h2>
+
+ <p>
+ App Standby extends battery life by deferring background network
+ activity and jobs for applications the user is not actively using.
+ </p>
+
+ <h3 id="app-standby-life">App Standby lifecycle</h3>
+
+ <p>
+ The platform detects inactive applications and places them in App
+ Standby until the user begins actively engaging with the application.
+ </p>
+
+<table>
+ <tbody>
+ <tr>
+ <th width=46%>Detection</th>
+ <th width=23%>During App Standby</th>
+ <th width=31%>Exit</th>
+ </tr>
+ <tr>
+ <td>
+ <p>
+ The platform detects an application is inactive when the device is not
+ charging <strong>and</strong> the user has not launched the application
+ directly or indirectly for a specific amount of clock time as well as a
+ specific amount of screen-on time. (Indirect launches occur when a
+ foreground app accesses a service in a second app.)
+ </p>
+ </td>
+ <td>
+ <p>
+ The platform prevents applications from accessing the network more than
+ once a day, deferring application syncs and other jobs.
+ </p>
+ </td>
+ <td>
+ <p>The platform exits the app from App Standby when:</p>
+ <ul>
+ <li>Application becomes active.</li>
+ <li>Device is plugged in and charging.</li>
+ </ul>
+ </td>
+ </tr>
+ </tbody>
+</table>
+
+<p>Active applications are unaffected by App Standby. An application is active
+when it has:</p>
+<ul>
+ <li>A process currently in the foreground (either as an activity or
+ foreground service, or in use by another activity or foreground service),
+ such as notification listener, accessibility services, live wallpaper, etc.
+ </li>
+ <li>A notification viewed by the user, such as in the lock screen or
+ notification tray.
+ </li>
+ <li>Explicitly been launched by the user.</li>
+</ul>
+
+<p>An application is inactive if none of the above activities has occurred for
+a period of time.
+</p>
+
+<h3 id=testing_app_standby>Testing App Standby</h3>
+<p>You can manually test App Standby using the following <code>adb</code>
+commands:</p>
+
+<pre class="devsite-click-to-copy">
+<code class="devsite-terminal">adb shell dumpsys battery unplug</code>
+<code class="devsite-terminal">adb shell am set-idle <var>package-name</var> true</code>
+<code class="devsite-terminal">adb shell am set-idle <var>package-name</var> false</code>
+<code class="devsite-terminal">adb shell am get-idle <var>package-name</var></code>
+</pre>
+
+ </body>
+</html>
diff --git a/en/devices/tech/power/batteryless.md b/en/devices/tech/power/batteryless.md
new file mode 100644
index 0000000..90bdbc0
--- /dev/null
+++ b/en/devices/tech/power/batteryless.md
@@ -0,0 +1,155 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+ Copyright 2018 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.
+-->
+
+# Supporting Batteryless Devices
+
+This page describes how Android handles products that have either removable
+batteries or no internal batteries. The latter devices are instead connected to
+an external power source, such as an AC power outlet or USB port on another
+device.
+
+
+## Is a battery present?
+
+The following code may be used by applications to detect whether the device has
+a battery currently present:
+
+ ```
+ final Intent batteryInfo = registerReceiver(null, new
+ IntentFilter(Intent.ACTION_BATTERY_CHANGED));
+
+ return batteryInfo.getBooleanExtra(BatteryManager.EXTRA_PRESENT, true);
+ ```
+
+## Batteryless device behavior
+
+If Android does not detect a battery device for your product, then the following
+battery-related default values are used. Note the defaults have changed in the
+Android {{ androidPVersionNumber }} release. This table shows the differences.
+
+<table>
+ <tr>
+ <th>Battery state
+ </th>
+ <th>Android {{ androidPVersionNumber }} and higher
+ </th>
+ <th>Android 8.1 and lower
+ </th>
+ </tr>
+ <tr>
+ <td><em>Present</em>
+ </td>
+ <td>false
+ </td>
+ <td>true
+ </td>
+ </tr>
+ <tr>
+ <td><em>Status</em>
+ </td>
+ <td>unknown
+ </td>
+ <td>charging
+ </td>
+ </tr>
+ <tr>
+ <td><em>Remaining capacity</em>
+ </td>
+ <td>0
+ </td>
+ <td>100%
+ </td>
+ </tr>
+ <tr>
+ <td><em>Health</em>
+ </td>
+ <td>unknown
+ </td>
+ <td>good
+ </td>
+ </tr>
+ <tr>
+ <td><em>AC charger online status</em>
+ </td>
+ <td>not modified
+ </td>
+ <td>forced to true
+ </td>
+ </tr>
+</table>
+
+
+Manufacturers may alter the default settings using a kernel
+[power_supply](https://www.kernel.org/doc/Documentation/power/power_supply_class.txt){: .external}
+driver or [Health HAL](/devices/tech/health/).
+
+### Android {{ androidPVersionNumber }} and higher
+
+Android {{ androidPVersionNumber }} removes some previous code for batteryless
+devices that by default pretended a battery was present, was being charged at
+100%, and was in good health with a normal temperature reading on its
+thermistor.
+
+Most framework APIs that deal with this information continue to handle common
+situations the same as previously: the system will be considered to be
+_charging_ (that is, not running on battery power), and will not be considered
+to have a low battery. If the user interface draws the battery icon, it will
+appear with an exclamation point, and battery percentage will be shown as 0%.
+But the device will not shut down due to low battery, and jobs that require
+charging or good battery will be scheduled.
+
+
+### Android 8.1 and lower
+
+Because the battery status is unknown, the Android framework APIs will consider
+the system to be _charging_ (or, not running on battery power) and will not be
+considered to have a low battery. If the user interface renders the battery
+icon, it will appear with an exclamation point, and battery percentage will be
+shown as 0%. But the device will not shut down due to low battery, and jobs that
+require charging or good battery will be scheduled.
+
+
+## Implementation
+
+The Android {{ androidPVersionNumber }} default code may work properly for your
+device, but it is recommended to make either a kernel or a HAL change to
+accurately reflect the power and battery state for your product, as described
+above. If Android {{ androidPVersionNumber }} and higher does not detect a [Linux power supply
+class](https://www.kernel.org/doc/Documentation/power/power_supply_class.txt){: .external}
+charger device, then by default all charger types (AC, USB, Wireless) will have
+status _offline_. If all chargers are offline but there is no battery device
+detected, the system will still be considered to be charging in the sense that
+it is running on external, not battery power, as described previously.
+
+If your product does not have a battery and is always connected to a power
+source, it's best to implement a Linux kernel power_supply class _charger_
+driver for the AC or USB power source that sets its _online_ `sysfs` attribute
+to `true`. Or you can configure the AC charger online property in a Health HAL
+for your device. To do this implement a Health HAL as described in [Implementing
+Health 2.0](/devices/tech/health/implementation).
+
+This custom Health HAL implements a custom version of `Health::getHealthInfo()`
+that modifies the value of `BatteryProperties.chargerAcOnline = true`.
+
+To get started, copy file
+<code>[hardware/interfaces/health/2.0/default/Health.cpp](https://android.googlesource.com/platform/hardware/interfaces/+/master/health/2.0/default/Health.cpp)</code>
+to your own Health HAL implementation and modify it according to the [Health 2.0
+README](https://android.googlesource.com/platform/hardware/interfaces/+/master/health/2.0/README).
diff --git a/en/devices/tech/power/mgmt.html b/en/devices/tech/power/mgmt.html
index dc44142..44e1778 100644
--- a/en/devices/tech/power/mgmt.html
+++ b/en/devices/tech/power/mgmt.html
@@ -24,299 +24,46 @@
<p>Battery life is a perennial user concern. To extend battery life, Android
-continually adds new features and optimizations to help the platform optimize
-the off-charger behavior of applications and devices.</p>
+continually adds new features to help the platform optimize the off-charger
+behavior of applications and devices.</p>
<p>Android includes the following battery life enhancements:</p>
<ul>
-<li><a href="#app-standby">App Standby</a>. The platform can
-place unused applications in App Standby mode, temporarily restricting network
-access and deferring syncs and jobs for those applications.</li>
-<li><a href="#doze">Doze</a>. The platform can enter a state of
-deep sleep (periodically resuming normal operations) if users have not actively
-used their device (screen off and stationary) for extended periods of time.
-Android 7.0 and higher also enables Doze to trigger a lighter set of
-optimizations when users turn off the device screen yet continue to move around.
-</li>
-<li><a href="#exempt-apps">Exemptions</a>. System apps and
-cloud messaging services preloaded on a device are typically exempted from App
-Standby and Doze by default (although app developers can intent their
-applications into this setting). Users can exempt applications via the Settings
-menu.</li>
+ <li>
+ <a href="/devices/tech/power/app_mgmt#app-restrictions">App Restrictions</a>.
+ The platform can suggest apps that negatively affect battery life, so
+ that users can choose to restrict those apps from consuming resources. Apps
+ are not background restricted by default.
+ </li>
+ <li><a href="/devices/tech/power/app_mgmt#app-standby">App Standby</a>. The
+ platform can place unused applications in App Standby mode, temporarily
+ restricting network access and deferring syncs and jobs for those
+ applications.
+ </li>
+ <li>
+ <a href="/devices/tech/power/platform_mgmt#doze">Doze</a>. The platform can
+ enter a state of deep sleep (periodically resuming normal operations) if
+ users have not actively used their device (screen off and stationary) for
+ extended periods of time. Android 7.0 and later also enables Doze to
+ trigger a lighter set of optimizations when users turn off the device
+ screen yet continue to move around.
+ </li>
+ <li>
+ <a href="#exempt-apps">Exemptions</a>. Preloaded system apps and cloud
+ messaging services are typically exempted from App Standby and Doze by
+ default. App developers can use Intents to apply these settings to their
+ apps. Users can exempt apps from App Standby and Doze power-saving modes
+ in the Settings menu.
+ </li>
</ul>
-<p>The following sections describe these enhancements.</p>
-
-<h2 id="app-standby">App Standby</h2>
-<p>App Standby extends battery life by deferring background network activity
-and jobs for applications the user is not actively using.</p>
-
-<h3 id="app-standby-life">App Standby lifecycle</h3>
-<p>The platform detects inactive applications and places them in App Standby
-until the user begins actively engaging with the application.</p>
-
-<table>
-<tbody>
-<tr>
-<th width=46%>Detection</th>
-<th width=23%>During App Standby</th>
-<th width=31%>Exit</th>
-</tr>
-
-<tr>
-<td><p>The platform detects an application is inactive when the device is not
-charging <strong>and</strong> the user has not launched the application directly
-or indirectly for a specific amount of clock time as well as a specific amount
-of screen-on time. (Indirect launches occur when a foreground app accesses a
-service in a second app.)</p></td>
-<td><p>The platform prevents applications from accessing the network more than
-once a day, deferring application syncs and other jobs.</p></td>
-<td><p>The platform exits the app from App Standby when:</p>
-<ul>
-<li>Application becomes active.</li>
-<li>Device is plugged in and charging.</li>
-</ul>
-</td>
-</tr>
-</tbody>
-</table>
-
-<p>Active applications are unaffected by App Standby. An application is active
-when it has:</p>
-<ul>
-<li>A process currently in the foreground (either as an activity or foreground
-service, or in use by another activity or foreground service), such as
-notification listener, accessibility services, live wallpaper, etc.</li>
-<li>A notification viewed by the user, such as in the lock screen or
-notification tray.</li>
-<li>Explicitly been launched by the user.</li>
-</ul>
-<p>An application is inactive if none of the above activities has occurred for
-a period of time.
-</p>
-
-<h3 id=testing_app_standby>Testing App Standby</h3>
-<p>You can manually test App Standby using the following <code>adb</code>
-commands:</p>
-
-<pre class="devsite-click-to-copy">
-<code class="devsite-terminal">adb shell dumpsys battery unplug</code>
-<code class="devsite-terminal">adb shell am set-idle packageName true</code>
-<code class="devsite-terminal">adb shell am set-idle packageName false</code>
-<code class="devsite-terminal">adb shell am get-idle packageName</code>
-</pre>
-
-<h2 id="doze">Doze</h2>
-
-<p>Doze extends battery life by deferring application background CPU and
-network activity when a device is unused for long periods.</p>
-
-<p>Idle devices in Doze periodically enter a maintenance window, during which
-apps can complete pending activities (syncs, jobs, etc.). Doze then resumes
-sleep for a longer period of time, followed by another maintenance window. The
-platform continues the Doze sleep/maintenance sequence, increasing the length of
-idle each time, until a maximum of a few hours of sleep time is reached. At all
-times, a device in Doze remains aware of motion and immediately leaves Doze
-if motion is detected.</p>
-
-<p>Android 7.0 and higher extends Doze to trigger a lighter set of optimizations
-every time a user turns off the device screen, even when the user continues to
-move around, enabling longer lasting battery life.</p>
-
-<p>System services (such as telephony) may be preloaded and exempted from Doze
-by default. Users can also exempt specific applications from Doze in the
-Settings menu. By default, Doze is <strong>disabled</strong> in AOSP; for
-details on enabling Doze, see <a href="#integrate-doze">Integrating Doze</a>.
-</p>
-
-<h3 id="doze-reqs">Doze requirements</h3>
-<p>Doze support requires the device has a cloud messaging service, such as
-<a href="https://firebase.google.com/docs/cloud-messaging/">Firebase Cloud
-Messaging (FCM)</a>. This enables the device to know when to wake from Doze.</p>
-
-<p>Full Doze support also requires a
-<a href="/devices/sensors/sensor-types.html#significant_motion">Significant
-Motion Detector (SMD)</a> on the device; however, the lightweight Doze mode in
-Android 7.0 and higher does not require an SMD. If Doze is enabled on a device
-that:</p>
-<ul>
-<li>Has an SMD, full Doze optimizations occur (includes lightweight
-optimizations).</li>
-<li>Does not have an SMD, only the lightweight Doze optimizations occur.</li>
-</ul>
-
-<h3 id="doze-life">Doze lifecycle</h3>
-
-<p>Doze begins when the platform detects the device is idle and
-ends when one or more exit criteria activities occur.</p>
-
-<table>
-<tbody>
-<tr>
-<th width=20%>Detection</th>
-<th width=60%>During Doze</th>
-<th width=20%>Exit</th>
-</tr>
-<tr>
-<td><p>The platform detects a device is idle when:</p>
-<ul>
-<li>Device is stationary (using significant motion detector).</li>
-<li>Device screen is off for some amount of time.</li>
-</ul>
-<p>Doze mode does not engage when the device is plugged into a power charger.
-</p>
-</td>
-<td><p>The platform attempts to keep the system in a sleep state, periodically
-resuming normal operations during a maintenance window then returning the device
-to sleep for longer repeating periods. During sleep, the following
-restrictions are active:</p>
-<ul>
-<li>Apps not allowed network access.</li>
-<li>App wakelocks ignored.</li>
-<li>Alarms deferred. Excludes alarm clock alarms and alarms set using
-<code>setAndAllowWhileIdle()</code> (limited to 1 per 15 minutes per app while
-in Doze). This exemption is intended for apps (such as Calendar) that must show
-event reminder notifications.</li>
-<li>Wi-Fi scans not performed.</li>
-<li>SyncAdapter syncs and JobScheduler jobs deferred until the next maintenance
-window.</li>
-<li>Apps receiving SMS and MMS messages are put on a temporary whitelist so
-they can complete their processing.</li>
-</ul>
-</td>
-<td><p>The platform exits the device from Doze when it detects:</p>
-<ul>
-<li>User interaction with device.</li>
-<li>Device movement.</li>
-<li>Device screen turns on.</li>
-<li>Imminent AlarmClock alarm.</li>
-</ul>
-<p>Notifications do not cause the device to exit from Doze.</p>
-</td>
-</tr>
-</tbody>
-</table>
-
-<p>Android 7.0 and higher extends Doze by enabling a lightweight sleep mode
-during screen off, before the device is idle.</p>
-
-<p><img src="/devices/tech/images/doze_lightweight.png"></p>
-<figcaption><strong>Figure 1.</strong> Doze modes for non-stationary and
-stationary devices.</figcaption>
-
-<table>
-<tbody>
-<tr>
-<th>Action</th>
-<th>Doze</th>
-<th>Lightweight Doze</th>
-</tr>
-<tr>
-<td>Trigger</td>
-<td>Screen off, on battery, stationary</td>
-<td>Screen off, on battery (unplugged)</td>
-</tr>
-<tr>
-<td>Timing</td>
-<td>Successively increasing periods with maintenance</td>
-<td>Repeated N-minute periods with maintenance windows</td>
-</tr>
-<tr>
-<td>Restrictions</td>
-<td>No network access, wake lock, or GPS/Wi-FI scan. Alarms and jobs/syncs
-deferred.</td>
-<td>No network access. Jobs/syncs deferred except during maintenance windows.
-</td>
-</tr>
-<tr>
-<td>Behavior</td>
-<td>Only high-priority push notification messages received.</td>
-<td>All real-time messages (instant messages, calls, etc.) received.
-High-priority push notification message enables temporary network access.</td>
-</tr>
-<tr>
-<td>Exit</td>
-<td>Motion, screen on, or alarm clock alarm.</td>
-<td>Screen on.</td>
-</tr>
-</tbody>
-</table>
-
-<h3 id="doze-interactions">Interaction with App Standby</h3>
-<ul>
-<li>Time spent in Doze does not count towards App Standby.</li>
-<li>While the device is in Doze, idle applications are allowed to perform normal
-operations at least once a day.</li>
-</ul>
-
-<h3 id="integrate-doze">Integrating Doze</h3>
-
-<p>When Doze is enabled, devices that support
-<a href="/devices/sensors/sensor-types.html#significant_motion">SENSOR_TYPE_SIGNIFICANT_MOTION</a>
-will perform full Doze optimizations (includes lightweight optimizations);
-devices without an SMD will perform only lightweight Doze optimizations. Android
-automatically selects the appropriate Doze optimizations and no vendor
-configuration is necessary.</p>
-
-<p>To enable Doze for a device, perform the following tasks:</p>
-
-<ol>
-<li>Confirm the device has a cloud messaging service installed.</li>
-<li>In the device overlay config file
-<code>overlay/frameworks/base/core/res/res/values/config.xml</code>, set
-<code>config_enableAutoPowerModes</code> to <strong>true</strong>:
-<pre class="devsite-click-to-copy">
-<bool name="config_enableAutoPowerModes">true</bool>
-</pre>
-In AOSP, this parameter is set to false (Doze disabled) by default.<br>
-</li>
-<li>Confirm that preloaded apps and services:
-<ul>
-<li>Use the
-<a href="https://developer.android.com/training/monitoring-device-state/doze-standby.html">power-saving
-optimization guidelines</a>. For details, see <a href="#test-apps">Testing and
-optimizing applications</a>.
-<p><strong>OR</strong></p>
-<li>Are exempted from Doze and App Standby. For details, see
-<a href="#exempt-apps">Exempting applications</a>.</li>
-</ul>
-</li>
-<li>Confirm the necessary services are exempted from Doze.</li>
-</ol>
-
-<h4 id="doze-tips">Tips</h4>
-<ul>
-<li>If possible, use FCM for
-<a href="https://firebase.google.com/docs/cloud-messaging/http-server-ref#send-downstream">downstream
-messaging</a>.</li>
-<li>If your users must see a notification right away, use a
-<a href="https://firebase.google.com/docs/cloud-messaging/concept-options#setting-the-priority-of-a-message">FCM
-high priority message</a>.</li>
-<li>Provide sufficient information within the initial
-<a href="https://firebase.google.com/docs/cloud-messaging/concept-options#notifications_and_data_messages">message
-payload</a> (to avoid unnecessary subsequent network access).</li>
-<li>Set critical alarms with
-<a href="http://developer.android.com/reference/android/app/AlarmManager.html#setAndAllowWhileIdle(int,%20long,%20android.app.PendingIntent)">setAndAllowWhileIdle()</a>
-and
-<a href="http://developer.android.com/reference/android/app/AlarmManager.html#setExactAndAllowWhileIdle(int,%20long,%20android.app.PendingIntent)">setExactAndAllowWhileIdle()</a>.
-</li>
-</ul>
-
-<h4 id="test-apps">Testing and optimizing applications</h4>
-<p>Test all applications (especially preloaded applications) in Doze mode. For
-details, refer to
-<a href="https://developer.android.com/training/monitoring-device-state/doze-standby.html#testing_doze_and_app_standby">Testing
-Doze and App Standby</a>.</p>
-
-<aside class="note"><strong>Note</strong>: MMS/SMS/Telephony services function
-independently of Doze and will always wake client apps even while the device
-remains in Doze mode.</aside>
-
<h2 id="exempt-apps">Exempting applications</h2>
<p>You can exempt applications from being subject to Doze or App Standby.
Exemptions may be needed in the following use cases:</p>
<ul>
-<li>OEM using non-FCM Cloud Messaging platform</li>
+<li>Device manufacturers using a Cloud Messaging platform other than
+<a href="https://firebase.google.com/docs/cloud-messaging/" class="external">Firebase
+Cloud Messaging</a> (FCM).</li>
<li>Carrier using non-FCM Cloud Messaging platform</li>
<li>Third-party application using non-FCM Cloud Messaging platform</li>
</ul>
@@ -327,15 +74,15 @@
minimizing such exemptions as they allow applications to defeat beneficial
controls the platform has over power use. If users become unhappy about the
power consumption of these apps, it can lead to frustration, bad experiences
-(and negative user reviews for the app), and customer support questions. For
-these reasons, we strongly recommend that you do not exempt third-party
-applications and instead exempt only cloud messaging services or apps with
-similar functions.</p>
+(and negative reviews for the app), and customer support questions. For these
+reasons, we strongly recommend that you do not exempt third-party applications
+and instead exempt only cloud messaging services or apps with similar
+functions.</p>
-<p>Apps exempted by default are listed in a single view in <em>Settings > App
-& Notifications > Special app access > Battery Optimization</em>. This list
-is used for exempting the app from both Doze and App Standby modes. To provide
-transparency to the user, the Settings menu <strong>MUST</strong> show all
+<p>Apps exempted by default are listed in <em>Settings > App &
+ Notifications > Special app access > Battery Optimization</em>. This list is
+ used for exempting the app from both Doze and App Standby modes. To provide
+ transparency to the user, the Settings menu <strong>MUST</strong> show all
exempted applications.</p>
<p>Users can manually exempt apps via <em>Settings > App & Notifications >
diff --git a/en/devices/tech/power/platform_mgmt.html b/en/devices/tech/power/platform_mgmt.html
new file mode 100644
index 0000000..97ddd57
--- /dev/null
+++ b/en/devices/tech/power/platform_mgmt.html
@@ -0,0 +1,239 @@
+<html devsite>
+ <head>
+ <title>Platform Power Management</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ <body>
+ <!--
+ Copyright 2018 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>
+ To improve device battery life, Android can affect the device state by
+ monitoring device use and wakefulness. The platform can enter a state of
+ sleep to pause activities from running while the device is unused.
+ </p>
+
+ <h2 id="doze">Doze</h2>
+
+<p>Doze extends battery life by deferring application background CPU and
+network activity when a device is unused for long periods.</p>
+
+<p>Idle devices in Doze periodically enter a maintenance window, during which
+apps can complete pending work (syncs, jobs, etc.). Doze then resumes
+sleep for a longer period of time, followed by another maintenance window. The
+platform continues the Doze sleep/maintenance sequence, increasing the length of
+idle each time, until a maximum of a few hours of sleep time is reached. At all
+times, a device in Doze remains aware of motion and immediately leaves Doze
+if motion is detected.</p>
+
+<p>Android 7.0 and higher extends Doze to trigger a lighter set of optimizations
+every time a user turns off the device screen, even when the user continues to
+move around, enabling longer lasting battery life.</p>
+
+<p>Critical system services are genereally set up by device manufacturers to be
+ exempt from Doze. Users can also exempt specific apps from Doze via the
+Settings menu. However, exempting apps may cause battery drain on the device.
+ By default, Doze is <strong>disabled</strong> in AOSP; for
+details on enabling Doze, see <a href="#integrate-doze">Integrating Doze</a>.
+</p>
+
+<h3 id="doze-reqs">Doze requirements</h3>
+<p>Doze support requires the device has a cloud messaging service, such as
+<a href="https://firebase.google.com/docs/cloud-messaging/" class="external">Firebase
+Cloud Messaging (FCM)</a>. External triggers events, such as cloud messages,
+ can temporarily wake apps to do work while the device remains in Doze mode.</p>
+
+<p>Full Doze support also requires a
+<a href="/devices/sensors/sensor-types.html#significant_motion">Significant
+Motion Detector (SMD)</a> on the device; however, the lightweight Doze mode in
+Android 7.0 and higher does not require an SMD. If Doze is enabled on a device
+that:</p>
+<ul>
+<li>Has an SMD, full Doze optimizations occur (includes lightweight
+optimizations).</li>
+<li>Does not have an SMD, only the lightweight Doze optimizations occur.</li>
+</ul>
+
+<h3 id="doze-life">Doze lifecycle</h3>
+
+<p>Doze begins when the platform detects the device is idle and
+ends when one or more exit criteria activities occur.</p>
+
+<table>
+<tbody>
+<tr>
+<th width=20%>Detection</th>
+<th width=60%>During Doze</th>
+<th width=20%>Exit</th>
+</tr>
+<tr>
+<td><p>The platform detects a device is idle when:</p>
+<ul>
+<li>Device is stationary (using significant motion detector).</li>
+<li>Device screen is off for some amount of time.</li>
+</ul>
+<p>Doze mode does not engage when the device is plugged into a power charger.
+</p>
+</td>
+<td><p>The platform attempts to keep the system in a sleep state, periodically
+resuming normal operations during a maintenance window then returning the device
+to sleep for longer repeating periods. During sleep, the following
+restrictions are active:</p>
+<ul>
+<li>Apps not allowed network access.</li>
+<li>App wakelocks ignored.</li>
+<li>Alarms deferred. Excludes alarm clock alarms and alarms set using
+<code>setAndAllowWhileIdle()</code> (limited to 1 per 15 minutes per app while
+in Doze). This exemption is intended for apps (such as Calendar) that must show
+event reminder notifications.</li>
+<li>Wi-Fi scans not performed.</li>
+<li><code>SyncAdapter</code> syncs and <code>JobScheduler</code> jobs deferred
+until the next maintenance window.</li>
+<li>Apps receiving SMS and MMS messages are put on a temporary whitelist so
+they can complete their processing.</li>
+</ul>
+</td>
+<td><p>The platform exits the device from Doze when it detects:</p>
+<ul>
+<li>User interaction with device.</li>
+<li>Device movement.</li>
+<li>Device screen turns on.</li>
+<li>Imminent AlarmClock alarm.</li>
+</ul>
+<p>Notifications do not cause the device to exit from Doze.</p>
+</td>
+</tr>
+</tbody>
+</table>
+
+<p>Android 7.0 and higher extends Doze by enabling a lightweight sleep mode
+during screen off, before the device is idle.</p>
+
+<p><img src="/devices/tech/images/doze_lightweight.png"></p>
+<figcaption><strong>Figure 1.</strong> Doze modes for non-stationary and
+stationary devices.</figcaption>
+
+<table>
+<tbody>
+<tr>
+<th>Action</th>
+<th>Doze</th>
+<th>Lightweight Doze</th>
+</tr>
+<tr>
+<td>Trigger</td>
+<td>Screen off, on battery, stationary</td>
+<td>Screen off, on battery (unplugged)</td>
+</tr>
+<tr>
+<td>Timing</td>
+<td>Successively increasing periods with maintenance</td>
+<td>Repeated N-minute periods with maintenance windows</td>
+</tr>
+<tr>
+<td>Restrictions</td>
+<td>No network access, wake lock, or GPS/Wi-Fi scan. Alarms and jobs/syncs
+deferred.</td>
+<td>No network access. Jobs/syncs deferred except during maintenance windows.
+</td>
+</tr>
+<tr>
+<td>Behavior</td>
+<td>Only high-priority push notification messages received.</td>
+<td>All real-time messages (instant messages, calls, etc.) received.
+High-priority push notification message enables temporary network access.</td>
+</tr>
+<tr>
+<td>Exit</td>
+<td>Motion, screen on, or alarm clock alarm.</td>
+<td>Screen on.</td>
+</tr>
+</tbody>
+</table>
+
+<h3 id="doze-interactions">Interaction with App Standby</h3>
+<ul>
+<li>Time spent in Doze does not count towards App Standby.</li>
+<li>While the device is in Doze, idle applications are allowed to perform normal
+operations at least once a day.</li>
+</ul>
+
+<h3 id="integrate-doze">Integrating Doze</h3>
+
+<p>When Doze is enabled, devices that support
+<a href="/devices/sensors/sensor-types.html#significant_motion"><code>SENSOR_TYPE_SIGNIFICANT_MOTION</code>code></a>
+perform full Doze optimizations (including lightweight optimizations);
+devices without an SMD perform only lightweight Doze optimizations. Android
+automatically selects the appropriate Doze optimizations and no vendor
+configuration is necessary.</p>
+
+<p>To enable Doze for a device:</p>
+
+<ol>
+<li>Confirm the device has a cloud messaging service installed.</li>
+<li>In the device overlay config file
+<code>overlay/frameworks/base/core/res/res/values/config.xml</code>, set
+<code>config_enableAutoPowerModes</code> to <strong>true</strong>:
+<pre class="devsite-click-to-copy">
+<bool name="config_enableAutoPowerModes">true</bool>
+</pre>
+In AOSP, this parameter is set to false (Doze disabled) by default.<br>
+</li>
+<li>Confirm that preloaded apps and services:
+<ul>
+<li>Use the
+<a href="https://developer.android.com/training/monitoring-device-state/doze-standby.html" class="external">power-saving
+optimization guidelines</a>. For details, see <a href="#test-apps">Testing and
+optimizing applications</a>.
+<p><strong>OR</strong></p>
+<li>Are exempted from Doze and App Standby. For details, see
+<a href="#exempt-apps">Exempting applications</a>.</li>
+</ul>
+</li>
+<li>Confirm the necessary services are exempted from Doze.</li>
+</ol>
+
+<h4 id="doze-tips">Tips</h4>
+<ul>
+<li>If possible, use FCM for
+<a href="https://firebase.google.com/docs/cloud-messaging/http-server-ref#send-downstream" class="external">downstream
+messaging</a>.</li>
+<li>If your users must see a notification right away, use a
+<a href="https://firebase.google.com/docs/cloud-messaging/concept-options#setting-the-priority-of-a-message" class="external">FCM
+high priority message</a>.</li>
+<li>Provide sufficient information within the initial
+<a href="https://firebase.google.com/docs/cloud-messaging/concept-options#notifications_and_data_messages" class="external">message
+payload</a> (to avoid unnecessary subsequent network access).</li>
+<li>Set critical alarms with
+<a href="http://developer.android.com/reference/android/app/AlarmManager.html#setAndAllowWhileIdle(int,%20long,%20android.app.PendingIntent)" class="external"><code>setAndAllowWhileIdle()</code></a>
+and
+<a href="http://developer.android.com/reference/android/app/AlarmManager.html#setExactAndAllowWhileIdle(int,%20long,%20android.app.PendingIntent)" class="external"><code>setExactAndAllowWhileIdle()</code></a>.
+</li>
+</ul>
+
+<h4 id="test-apps">Testing and optimizing applications</h4>
+<p>Test all applications (especially preloaded applications) in Doze mode. For
+details, refer to
+<a href="https://developer.android.com/training/monitoring-device-state/doze-standby.html#testing_doze_and_app_standby">Testing
+Doze and App Standby</a>.</p>
+
+<aside class="note"><strong>Note:</strong> MMS/SMS/Telephony services function
+independently of Doze and will always wake client apps even while the device
+remains in Doze mode.</aside>
+
+ </body>
+</html>
diff --git a/en/devices/tech/settings/index.html b/en/devices/tech/settings/index.html
index 0b3066d..4f1ad73 100644
--- a/en/devices/tech/settings/index.html
+++ b/en/devices/tech/settings/index.html
@@ -1,6 +1,6 @@
<html devsite>
<head>
- <title>Settings Menu</title>
+ <title>Design Android Settings</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
@@ -23,8 +23,9 @@
-<p>The pages in this section explain how to employ the latest features
-available in the Android Settings menu.</p>
+<p>The pages in this section explain how to design consistent settings
+interface. Use the horitonzal menu at the top to delve into specific subtabs and
+sections.</p>
</body>
</html>
diff --git a/en/devices/tech/settings/info-architecture.html b/en/devices/tech/settings/info-architecture.html
index d74ff5f..d0f027d 100644
--- a/en/devices/tech/settings/info-architecture.html
+++ b/en/devices/tech/settings/info-architecture.html
@@ -1,10 +1,12 @@
<html devsite>
<head>
- <title>Updated Information Architecture</title>
+ <title>Information Architecture</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
+ {% include "_versions.html" %}
+
<!--
Copyright 2017 The Android Open Source Project
@@ -22,10 +24,12 @@
-->
<p>
-Android 8.0 introduces a new information architecture for the Settings app. The
-goal of the new information architecture is to simplify the way settings are
-organized and make it easier for users to quickly find the settings needed to
-customize their Android devices.
+Android 8.0 introduced a new information architecture for the Settings app to
+simplify the way settings are organized and make it easier for users to
+quickly find settings to customize their Android devices.
+
+Android {{ androidPVersionNumber }} introduced some improvements to provide more
+Settings functionality and easier implementation.
</p>
<h2 id="examples-and-source">Examples and source</h2>
@@ -40,23 +44,19 @@
Files paths for important components are listed below:
</p>
-<h3 id="categorykey">CategoryKey</h3>
-
-<code>packages/SettingsLib/src/com/android/settingslib/drawer/CategoryKey.java</code>
-
-<h3 id="dashboardfragmentregistry">DashboardFragmentRegistry</h3>
-
-<code>packages/apps/Settings/src/com/android/settings/dashboard/DashboardFragmentRegistry.java</code>
-
-<h3 id="dashboardfragment">DashboardFragment</h3>
-
-<code>packages/apps/Settings/src/com/android/settings/dashboard/DashboardFragment.java</code>
-
-<h3 id="preferencecontrollers">AbstractPreferenceController and PreferenceController</h3>
-
-<code>frameworks/base/packages/SettingsLib/src/com/android/settingslib/core/AbstractPreferenceController.java</code>
-
-<code>packages/apps/Settings/src/com/android/settings/core/PreferenceController.java</code>
+<ul>
+<li><strong>CategoryKey</strong>:
+<code>packages/SettingsLib/src/com/android/settingslib/drawer/CategoryKey.java</code></li>
+<li><strong>DashboardFragmentRegistry</strong>:
+<code>packages/apps/Settings/src/com/android/settings/dashboard/DashboardFragmentRegistry.java</code></li>
+<li><strong>DashboardFragment</strong>:
+<code>packages/apps/Settings/src/com/android/settings/dashboard/DashboardFragment.java</code></li>
+<li><strong>AbstractPreferenceController</strong>:
+<code>frameworks/base/packages/SettingsLib/src/com/android/settingslib/core/AbstractPreferenceController.java
+</code></li>
+<li><strong>BasePreferenceController</strong> (introduced in Android {{ androidPVersionNumber }}):
+<code>packages/apps/Settings/src/com/android/settings/core/BasePreferenceController.java</code></li>
+</ul>
<h2 id="implementation">Implementation</h2>
@@ -64,21 +64,24 @@
Device manufacturers are encouraged to adapt the existing Settings information
architecture and insert additional settings pages as needed to accommodate
partner-specific features. Moving preferences from legacy page (implemented as
-SettingsPreferencePage) to a new page (implemented using DashboardFragment) can
-be complicated. The preference from the legacy page is likely not implemented
-with a PreferenceController.
+<code>SettingsPreferencePage</code>) to a new page (implemented using
+<code>DashboardFragment</code>) can be complicated. The preference from the
+legacy page is likely not implemented with a <code>PreferenceController</code>.
</p>
<p>
-So when moving it into a DashboardFragment, partners will need to create a
-PreferenceController and move the code into the controller before instantiating
-it in the new DashboardFragment. The refactor process is fairly straightforward
-since most of it is just moving existing code.
+So when moving a preferences from a legacy page to a new page, you need to create a
+<code>PreferenceController</code> and move the code into the controller before
+instantiating it in the new <code>DashboardFragment</code>. The APIs that
+<code>PreferenceController</code> requires are described in their name and
+documented in Javadoc.
</p>
<p>
-Once done with refactoring, OEMs should submit patch CLs with tests to have
-their changes merged upstream.
+It is highly recommended to add a unit test for each <code>PreferenceController</code>.
+If the change is submitted to AOSP, then a unit test is required.
+To get more information about how to write Robolectric based tests, see the
+readme file <code>packages/apps/Settings/tests/robotests/README.md</code>.
</p>
<h3 id="plugin">Plugin-style information architecture</h3>
@@ -89,8 +92,8 @@
</p>
<p>
-To make it easier for multiple settings to be moved around, Android O introduces
-a plugin style host fragment that contains settings items. Settings items are
+To make it easier for multiple settings to be moved around, Android 8.0 introduced
+a plugin-style host fragment that contains settings items. Settings items are
modeled as plugin-style controllers. Hence, a settings page is constructed by a
single host fragment and multiple setting controllers.
</p>
@@ -98,17 +101,18 @@
<h3 id="dashboard-fragment">DashboardFragment</h3>
<p>
-This is the host of plugin-style preference controllers. The fragment inherits
-from PreferenceFragment and has hooks to inflate and update both static
-preference lists and dynamic preference lists.
+<code>DashboardFragment</code> is the host of plugin-style preference controllers.
+The fragment inherits from <code>PreferenceFragment</code> and has hooks to
+inflate and update both static preference lists and dynamic preference lists.
</p>
<h3 id="static-preferences">Static preferences</h3>
<p>
-A static preference list is defined in XML using the <Preference> tag. A
-DashboardFragment implementation uses the getPreferenceScreenResId() method to
-define which XML file contains the static list of preferences to display.
+A static preference list is defined in XML using the <code><Preference></code> tag. A
+<code>DashboardFragment</code> implementation uses the
+<code>getPreferenceScreenResId()</code> method to define which XML file contains
+the static list of preferences to display.
</p>
<h3 id="dynamic-preferences">Dynamic preferences</h3>
@@ -117,12 +121,13 @@
A dynamic item represents a tile with intent, leading to an external or internal
Activity. Usually, the intent leads to a different setting page. For example,
the "Google" setting item in the Settings homepage is a dynamic item. Dynamic
-items are defined in AndroidManifest (discussed below) and loaded through a
-FeatureProvider (defined as DashboardFeatureProvider).
+items are defined in <code>AndroidManifest</code> (discussed below) and loaded
+through a <code>FeatureProvider</code> (defined as <code>
+DashboardFeatureProvider</code>).
</p>
<p>
-Note that dynamic settings are more heavyweight than statically configured
+Dynamic settings are more heavyweight than statically configured
settings, so normally developers should implement the setting as a static one.
However the dynamic setting can be useful when any of the following is true:
</p>
@@ -131,24 +136,24 @@
<li>The setting is not directly implemented in the Settings app (such as
injecting a setting implemented by OEM/Carrier apps).</li>
<li>The setting should appear on the Settings homepage.</li>
-<li>You already have an Activity for the setting and don't want to implement the
+<li>You already have an Activity for the setting and do not want to implement the
extra static config.</li>
</ul>
<p>
-To configure an Activity as a dynamic setting, you need to do a few things:
+To configure an Activity as a dynamic setting, do the following:
</p>
<ul>
-<li>Mark the activity as a dynamic setting. This is done by simply adding an
-intent-filter to the activity.</li>
-<li>Tell Settings app which category it belongs to. The category is a constant,
-defined in <strong>CategoryKey</strong>.</li>
-<li>Optional: Add a summary text when the setting is displayed.</li>
+<li>Mark the activity as a dynamic setting by adding an intent-filter to the
+activity.</li>
+<li>Tell the Settings app which category it belongs to. The category is a constant,
+defined in <code>CategoryKey</code>.</li>
+<li>Optional: Add summary text when the setting is displayed.</li>
</ul>
<p>
-Here is an example taken from Settings app for DisplaySettings.
+Here is an example taken from Settings app for <code>DisplaySettings</code>.
</p>
<pre
@@ -171,72 +176,157 @@
<p>
At render time, the fragment will ask for a list of Preferences from both static
-XML and dynamic settings defined in AndroidManifest. Regardless in which source
-a setting is loaded, DashboardFragment manages the handling logic of each
-setting through PreferenceController<strong> </strong>(discussed below). Then
-they will be displayed onto the UI as a mixed list.
+XML and dynamic settings defined in <code>AndroidManifest</code>. Whether the
+<code>PreferenceController</code>s are defined in Java code or in XML,
+<code>DashboardFragment</code> manages the handling logic of each setting
+through <code>PreferenceController</code> (discussed below). Then they are
+displayed in the UI as a mixed list.
</p>
<h3 id="preference-controller">PreferenceController</h3>
+<p>There are differences between implementing <code>PreferenceController</code>
+in Android {{ androidPVersionNumber }} and Android 8.x, as described in this
+section.</p>
+
+<h4>PreferenceController in Android {{ androidPVersionNumber }} release</h4>
+
+<p>A <code>PreferenceController</code> contains all logic to interact with the
+preference, including displaying, updating, search indexing, etc.</p>
+
+<p>The interface of <code>PreferenceController</code> is defined as
+<code>BasePreferenceController</code>. For example, see code in
+<code>packages/apps/Settings/src/com/android/settings/core/
+BasePreferenceController.java</code></p>
+
+<p>There are several subclasses of <code>BasePreferenceController</code>, each
+mapping to a specific UI style that the Settings app supports by default. For
+example, <code>TogglePreferenceController</code> has an API that directly maps
+to how the user should interact with a toggle-based preference UI.</p>
+
+<p><code>BasePreferenceController</code> has APIs like
+<code>getAvailabilityStatus()</code>, <code>displayPreference()</code>,
+<code>handlePreferenceTreeClicked(),</code> etc. Detailed documentation for each
+API is in the interface class.</p>
+
+<p>A restriction on implementing <code>BasePreferenceController</code> (and
+its subclasses such as <code>TogglePreferenceController</code>) is that the
+constructor signature must match either of the following:</p>
+
+<ul>
+<li><code>public MyController(Context context, String key) {}</code></li>
+<li><code>public MyController(Context context) {}</code></li>
+</ul>
+
+<p>While installing a preference to the fragment, dashboard provides a method to
+attach a <code>PreferenceController</code> before display time. At install time,
+the controller is wired up to the fragment so all future relevant events are
+sent to the controller.</p>
+
+<code>DashboardFragment</code> keeps a list of
+<code>PreferenceController</code>s in the screen. At the fragment's
+<code>onCreate()</code>, all controllers are invoked for the
+<code>getAvailabilityStatus()</code> method, and if it returns true,
+<code>displayPreference()</code> is invoked to process display logic.
+<code>getAvailabilityStatus()</code> is also important to tell the Settings
+framework which items are available during search.</p>
+
+<h4>PreferenceController in Android 8.x releases</h4>
+
<p>
-A PreferenceController contains all logic to interact with the preference,
-including displaying/updating/search indexing and so on.
+A <code>PreferenceController</code> contains all logic to interact with the
+preference, including displaying, updating, search indexing. etc.
</p>
<p>
-Correspondingly, the interface of PreferenceController has API of isAvailable(),
-displayPreference(), handlePreferenceTreeClicked() etc. Detailed documentation
-on each API can be found in the interface class.
+Corresponding to the preference interactions, the interface of <code>
+PreferenceController</code> has APIs <code>isAvailable()</code>, <code>
+displayPreference()</code>, <code>handlePreferenceTreeClicked()</code> etc.
+Detailed documentation on each API can be found in the interface class.
</p>
<p>
While installing a preference to the fragment, dashboard provides a method to
-attach a PreferenceController before display time. At install time, the
-controller will be wired up to the fragment so all future relevant events are
+attach a <code>PreferenceController</code> before display time. At install time,
+the controller is wired up to the fragment so all future relevant events are
sent to the controller.
</p>
<p>
-DashboardFragment will keep a list of PreferenceControllers in the screen. At
-fragment's onCreate(), all controllers will be invoked for the isAvailable()
-method, and if it returns true, displayPreference() will be invoked to process
-display logic.
+<code>DashboardFragment</code> keeps a list of <code>PreferenceControllers
+</code> in the screen. At the fragment's <code>onCreate()</code>, all
+controllers are invoked for the <code>isAvailable()</code> method, and if it
+returns true, <code>displayPreference()</code> is invoked to process display
+logic.
</p>
<h2 id="using-dashboardfragment">Using DashboardFragment</h2>
-<h3 id="moving-preference">Moving preference from page A to B</h3>
+<h3 id="moving-preference">Moving a preference from page A to B</h3>
<p>
If the preference is statically listed in the original page's preference XML
-file, follow the <strong>static </strong>path below. Otherwise, follow the
-<strong>dynamic</strong> path.
+file, follow the <strong>Static</strong> move procedure for your Android
+release below. Otherwise, follow the <strong>Dynamic</strong> move procedure
+for your Android release.
</p>
-<h4 id="static-move">Static</h4>
+<h4 id="static-move-p">Static move in Android {{ androidPVersionNumber }}</h4>
+
+<ol>
+<li>Find the preference XML files for the original page and destination
+page. You can find this information from the page's
+<code>getPreferenceScreenResId()</code> method.</li>
+<li>Remove the preference from the original page's XML.</li>
+<li>Add the preference to the destination page's XML.</li>
+<li>Remove the <code>PreferenceController</code> for this preference from the
+original page's Java implementation. Usually it is in
+<code>createPreferenceControllers()</code>. The controller might be declared in
+XML directly.
+<p><strong>Note</strong>: The preference might not have a
+<code>PreferenceController</code>.</p></li>
+<li>Instantiate the <code>PreferenceController</code> in the destination page's
+<code>createPreferenceControllers()</code>. If the
+<code>PreferenceController</code> is defined in XML in the old page, define it
+in XML for the new page also.</li>
+</ol>
+
+<h4 id="dynamic-move">Dynamic move in Android {{ androidPVersionNumber }}</h4>
+
+<ol>
+<li>Find which category the original and destination page hosts. You can
+find this information in <code>DashboardFragmentRegistry</code>.</li>
+<li>Open the <code>AndroidManifest.xml</code> file that contains the setting you
+need to move and find the Activity entry representing this setting.</li>
+<li>Set the activity's metadata value for
+<code>com.android.settings.category</code> to the new page's category key.</li>
+</ol>
+
+<h4 id="static-move-8">Static move in Android 8.x releases</h4>
<ol>
<li>Find the preference XML files for the original page and destination page.</li>
-You can find this information from the page's getPreferenceScreenResId() method.</li>
+You can find this information from the page's <code>getPreferenceScreenResId()
+</code> method.</li>
<li>Remove the preference in the original page's XML.</li>
<li>Add the preference to destination page's XML.</li>
-<li>Remove the PreferenceController for this preference in the original page's
-Java implementation. Usually it's in getPreferenceControllers().</li>
-<strong>Note</strong>: It is possible the preference does not have a
-PreferenceController.</li>
-<li>Instantiate the PreferenceController in the destination page's
-getPreferenceControllers().</li>
+<li>Remove the <code>PreferenceController</code> for this preference in the
+original page's Java implementation. Usually it's in
+<code>getPreferenceControllers()</code>.</li>
+<p><strong>Note</strong>: It is possible the preference does not have a
+<code>PreferenceController</code>.</p></li>
+<li>Instantiate the <code>PreferenceController</code> in the destination page's
+<code>getPreferenceControllers()</code>.</li>
</ol>
-<h4 id="dynamic-move">Dynamic</h4>
+<h4 id="dynamic-move">Dynamic move in Android 8.x releases</h4>
<ol>
<li>Find which category the original and destination page hosts. You can find
this information in <code>DashboardFragmentRegistry</code>.</li>
<li>Open the <code>AndroidManifest.xml</code> file that contains the setting you
need to move and find the Activity entry representing this setting.</li>
-<li>Change the activity's metadata value for "com.android.settings.category",
+<li>Change the activity's metadata value for <code>com.android.settings.category</code>,
set the value point to the new page's category key.</li>
</ol>
@@ -244,49 +334,70 @@
<p>
If the preference is statically listed in the original page's preference XML
-file, follow the <strong>static </strong>path below. Otherwise follow the
-<strong>dynamic</strong> path.
+file, follow the <strong>static</strong> procedure below. Otherwise follow the
+<strong>dynamic</strong> procedure.
</p>
-<h4 id="static-create">Static</h4>
+<h4 id="static-create">Creating a static preference</h4>
<ol>
<li>Find the preference XML files for the page. You can find this information
from the page's getPreferenceScreenResId() method.</li>
-<li>Add a new Preference item in the XML. Make sure it has a unique android:key.</li>
-<li>Instantiate a PreferenceController for this preference in the page's
-getPreferenceControllers() method.</li>
-If this preference already existed in other
-places, it's possible there is already a PreferenceController for it. You can
-reuse the PreferenceController without building a new one.</li>
+<li>Add a new Preference item in the XML. Make sure it has a unique <code>android:key</code>.</li>
+<li>
+Define a <code>PreferenceController</code> for this preference in the page's
+<code>getPreferenceControllers()</code> method.
+<ul>
+<li>In Android 8.x and optionally in Android {{ androidPVersionNumber }},
+instantiate a <code>PreferenceController</code> for this preference in the
+page’s <code>createPreferenceControllers()</code> method.
+
+<p>If this preference already existed in other places, it’s possible there is
+already a <code>PreferenceController</code> for it. You can reuse the
+<code>PreferenceController</code> without building a new one.</p>
+</li>
+<li>
+Starting in Android {{ androidPVersionNumber }}, you can choose to declare the
+<code>PreferenceController</code> in XML next to the preference. For example:
+<pre class="prettyprint">
+<Preference
+ android:key="reset_dashboard"
+ android:title="@string/reset_dashboard_title"
+ <b>settings:controller="com.android.settings.system.ResetPreferenceController"/></b>
+</pre>
+</li>
+</ul>
+</li>
</ol>
-<h4 id="dynamic-create">Dynamic</h4>
+<h4 id="dynamic-create">Creating a dynamic preference</h4>
<ol>
<li>Find which category the original and destination page hosts. You can find
this information in <code>DashboardFragmentRegistry</code>.</li>
-<li>Create a new Activity in AndroidManifest, and add necessary metadata to
-define the setting. Make the metadata value for "com.android.settings.category"
-to be the same value defined in step 1.</li>
+<li>Create a new Activity in <code>AndroidManifest</code></li>
+<li>Add necessary metadata to the new Activity to define the setting. Set the
+metadata value for <code>com.android.settings.category</code> to the same value
+defined in step 1.</li>
</ol>
<h3 id="create-new-page">Create a new page</h3>
<ol>
-<li>Create a new fragment, inheriting from DashboardFragment.</li>
+<li>Create a new fragment, inheriting from <code>DashboardFragment</code>.</li>
<li>Define its category in <code>DashboardFragmentRegistry</code>.
<p class="note"><strong>Note:</strong> This step is optional. If you do not need
any dynamic preferences in this page, you don't need to provide a category key.</p></li>
-<li>Follow the steps for adding the settings needed for this page.</li>
+<li>Follow the steps for adding the settings needed for this page. For more
+information, see the <a href="#implementation">Implementation</a> section.</li>
</ol>
<h2 id="validation">Validation</h2>
<ul>
-<li>Run the robolectric tests in Settings, all existing and new tests should
+<li>Run the robolectric tests in Settings. All existing and new tests should
pass.
-<li>Build and install Settings, manually open the page being modified; the page
-should update immediately.</li>
+<li>Build and install Settings, then manually open the page being modified.
+The page should update immediately.</li>
</ul>
</body>
</html>
diff --git a/en/devices/tech/settings/patterns-components.html b/en/devices/tech/settings/patterns-components.html
index 90c730f..463937c 100644
--- a/en/devices/tech/settings/patterns-components.html
+++ b/en/devices/tech/settings/patterns-components.html
@@ -96,7 +96,7 @@
<code>packages/apps/Settings/src/com/android/settings/dashboard/ProgressiveDisclosureMixin.java</code>
<p class="note"><strong>Note:</strong> This component must be used together with
DashboardFragment. (See more details about DashboardFragment in <a
-href="information-architecture.html">Updated Information Architecture</a>.)</p>
+href="info-architecture.html">Updated Information Architecture</a>.)</p>
</li>
</ul>
<li>Default app picker
diff --git a/en/devices/tech/settings/settings-guidelines.md b/en/devices/tech/settings/settings-guidelines.md
index be948b6..2d29aa8 100644
--- a/en/devices/tech/settings/settings-guidelines.md
+++ b/en/devices/tech/settings/settings-guidelines.md
@@ -32,7 +32,7 @@
<img src="images/settings-guidelines01.png" width="250" class="screenshot">
-**Figure 1:** Settings and their current values are presented on the top-level
+**Figure 1.** Settings and their current values are presented on the top-level
screen
### Organize items intuitively
@@ -43,7 +43,7 @@
<img src="images/settings-guidelines02.png" width="250" class="screenshot">
-**Figure 2:** Common settings are at the top of the screen
+**Figure 2.** Common settings are at the top of the screen
### Make settings easy to find
@@ -61,7 +61,7 @@
</tr>
</table>
-**Figure 3 & 4:** "Default notification sound" appears on both the
+**Figure 3 & 4.** "Default notification sound" appears on both the
"Notification" and "Sound" screens
### Use a clear title and status
@@ -99,7 +99,7 @@
<img src="images/settings-guidelines05.png" width="250" class="screenshot">
-**Figure 5**: Example of settings list
+**Figure 5.** Example of settings list
### List view
@@ -108,7 +108,7 @@
<img src="images/settings-guidelines06.png" width="250" class="screenshot">
-**Figure 6**: Example of List view
+**Figure 6.** Example of List view
### Entity screen
@@ -120,11 +120,11 @@
<img src="images/settings-guidelines07.png" width="250" class="screenshot">
-**Figure 7**: Example of Entity screen used in App info
+**Figure 7.** Example of Entity screen used in App info
<img src="images/settings-guidelines08.png" width="250" class="screenshot">
-**Figure 8**: Example of Entity screen used in Storage
+**Figure 8.** Example of Entity screen used in Storage
### Master setting
@@ -142,12 +142,12 @@
<img src="images/settings-guidelines09.png" width="250" class="screenshot">
-**Figure 9**: Example of master setting used in App notifications screen;
+**Figure 9.** Example of master setting used in App notifications screen;
turning off the master toggle will turn of the entire feature for this app
<img src="images/settings-guidelines10.png" width="250" class="screenshot">
-**Figure 10**: Example of master setting used in App notifications screen with
+**Figure 10.** Example of master setting used in App notifications screen with
master toggle turned off
### Radio button selection screen
@@ -161,11 +161,11 @@
<img src="images/settings-guidelines11.png" width="250" class="screenshot">
-**Figure 11:** Radio buttons should not be used in settings list
+**Figure 11.** Radio buttons should not be used in settings list
<img src="images/settings-guidelines12.png" width="250" class="screenshot">
-**Figure 12:** This is how to use radio buttons correctly in settings
+**Figure 12.** This is how to use radio buttons correctly in settings
## Components
@@ -175,17 +175,17 @@
other related actions. Overflow menus are discouraged as users may not discover
actions hidden in these menus.
-**For toolbars with no screen-specific actions**: Show search and help actions.
+**For toolbars with no screen-specific actions.** Show search and help actions.
<img src="images/settings-guidelines13.png" width="250" class="screenshot">
-**Figure 13:** Toolbar with search and help actions
+**Figure 13.** Toolbar with search and help actions
**For toolbars with one action**: Present the action before search.
<img src="images/settings-guidelines14.png" width="250" class="screenshot">
-**Figure 14:** Toolbar with one action before the search and help actions
+**Figure 14.** Toolbar with one action before the search and help actions
**For toolbars with more than 1 action**: Consider placing the primary action
before search, while putting advanced actions in the overflow menu.
@@ -195,7 +195,7 @@
<img src="images/settings-guidelines15.png" width="250" class="screenshot">
-**Figure 15:** Toolbar with an overflow menu for actions
+**Figure 15.** Toolbar with an overflow menu for actions
### Entity header
@@ -205,13 +205,13 @@
<img src="images/settings-guidelines16.png" width="250" class="screenshot">
-**Figure 16:** Entity header
+**Figure 16.** Entity header
The icon and heading (App1) part will scroll under the header (App info).
<img src="images/settings-guidelines17.png" width="250" class="screenshot">
-**Figure 17:** App info title here is part of the toolbar, while the rest of the
+**Figure 17.** App info title here is part of the toolbar, while the rest of the
screen will scroll under it
### Menu link
@@ -227,15 +227,15 @@
<img src="images/settings-guidelines18.png" width="250" class="screenshot">
-**Figure 18:** Menu link with icon, title, and subtext
+**Figure 18.** Menu link with icon, title, and subtext
<img src="images/settings-guidelines19.png" width="250" class="screenshot">
-**Figure 19:** Menu link with title and subtext
+**Figure 19.** Menu link with title and subtext
<img src="images/settings-guidelines20.png" width="250" class="screenshot">
-**Figure 20:** Menu link with title only
+**Figure 20.** Menu link with title only
**Menu link with icon, title, subtext and a separate hit target on the right**
@@ -243,7 +243,7 @@
<img src="images/settings-guidelines21.png" width="250" class="screenshot">
-**Figure 21:** Example of two-tap target menu
+**Figure 21.** Example of two-tap target menu
**Menu link with icon, title, subtext and stats/number/alert icon**
@@ -255,7 +255,7 @@
<img src="images/settings-guidelines22.png" width="250" class="screenshot">
-**Figure 22:** Example of menu with icon, title, stat and graph
+**Figure 22.** Example of menu with icon, title, stat and graph
### Grouping & dividers
@@ -268,7 +268,7 @@
<img src="images/settings-guidelines23.png" width="250" class="screenshot">
-**Figure 23:** Settings grouped with dividers
+**Figure 23.** Settings grouped with dividers
### Switch
@@ -276,13 +276,13 @@
<img src="images/settings-guidelines24.png" width="250" class="screenshot">
-**Figure 24:** Switch with icon, title, and subtext
+**Figure 24.** Switch with icon, title, and subtext
**Switch with title and subtext**
<img src="images/settings-guidelines25.png" width="250" class="screenshot">
-**Figure 25:** Switch with title and subtext
+**Figure 25.** Switch with title and subtext
**Switch with title only**
@@ -290,7 +290,7 @@
<img src="images/settings-guidelines26.png" width="250" class="screenshot">
-**Figure 26:** Switch with title only
+**Figure 26.** Switch with title only
### List item + switch
@@ -303,7 +303,7 @@
<img src="images/settings-guidelines27.png" width="250" class="screenshot">
-**Figure 27:** List item and a switch
+**Figure 27.** List item and a switch
### Slider
@@ -311,7 +311,7 @@
<img src="images/settings-guidelines28.png" width="250" class="screenshot">
-**Figure 28:** Slider
+**Figure 28.** Slider
### On-screen button
@@ -322,11 +322,11 @@
<img src="images/settings-guidelines29.png" width="250" class="screenshot">
-**Figure 29:** Gray buttons for "Uninstall" and "Force stop"
+**Figure 29.** Gray buttons for "Uninstall" and "Force stop"
<img src="images/settings-guidelines30.png" width="250" class="screenshot">
-**Figure 30:** Blue button for "Turn on now"
+**Figure 30.** Blue button for "Turn on now"
### Progressive disclosure (Advanced)
@@ -338,7 +338,7 @@
<img src="images/settings-guidelines31.png" width="250" class="screenshot">
-**Figure 31:** Advanced used on the "Display'" screen
+**Figure 31.** Advanced used on the "Display'" screen
### Drop-down menu
@@ -351,7 +351,7 @@
<img src="images/settings-guidelines32.png" width="250" class="screenshot">
-**Figure 32:** Drop-down menu
+**Figure 32.** Drop-down menu
### Checkbox
@@ -364,7 +364,7 @@
<img src="images/settings-guidelines33.png" width="250" class="screenshot">
-**Figure 33**: Checkboxes are used to reduce the number of switches on this
+**Figure 33.** Checkboxes are used to reduce the number of switches on this
screen
### Links
@@ -374,7 +374,7 @@
<img src="images/settings-guidelines34.png" width="250" class="screenshot">
-**Figure 34:** Link used in settings
+**Figure 34.** Link used in settings
### Footer
@@ -384,7 +384,7 @@
<img src="images/settings-guidelines35.png" width="250" class="screenshot">
-**Figure 35:** Footer text
+**Figure 35.** Footer text
## Patterns
@@ -397,11 +397,11 @@
<img src="images/settings-guidelines36.png" width="250" class="screenshot">
-**Figure 36:** Example showing Storage
+**Figure 36.** Example showing Storage
<img src="images/settings-guidelines37.png" width="250" class="screenshot">
-**Figure 37:** Example showing Network
+**Figure 37.** Example showing Network
### User education
@@ -412,7 +412,7 @@
<img src="images/settings-guidelines38.png" width="250" class="screenshot">
-**Figure 38:** Setting using animation and footer text
+**Figure 38.** Setting using animation and footer text
### Forms
@@ -424,7 +424,7 @@
<img src="images/settings-guidelines39.png" width="250" class="screenshot">
-**Figure 39:** Form with a normal dialog
+**Figure 39.** Form with a normal dialog
### Search results
@@ -433,4 +433,4 @@
<img src="images/settings-guidelines40.png" width="250" class="screenshot">
-**Figure 40:** Search result
+**Figure 40.** Search result
diff --git a/en/security/_toc-bulletins.yaml b/en/security/_toc-bulletins.yaml
new file mode 100644
index 0000000..b3b62c1
--- /dev/null
+++ b/en/security/_toc-bulletins.yaml
@@ -0,0 +1,135 @@
+toc:
+- title: Overview
+ path: /security/bulletin/
+- title: Advisories
+ section:
+ - title: Overview
+ path: /security/advisory/
+ - title: March 2016
+ path: /security/advisory/2016-03-18
+- title: Android Bulletins
+ section:
+ - title: 2018 Bulletins
+ section:
+ - title: August
+ path: /security/bulletin/2018-08-01
+ - title: July
+ path: /security/bulletin/2018-07-01
+ - title: June
+ path: /security/bulletin/2018-06-01
+ - title: May
+ path: /security/bulletin/2018-05-01
+ - title: April
+ path: /security/bulletin/2018-04-01
+ - title: March
+ path: /security/bulletin/2018-03-01
+ - title: February
+ path: /security/bulletin/2018-02-01
+ - title: January
+ path: /security/bulletin/2018-01-01
+ - title: Index
+ path: /security/bulletin/2018
+ - title: 2017 Bulletins
+ section:
+ - title: December
+ path: /security/bulletin/2017-12-01
+ - title: November
+ path: /security/bulletin/2017-11-01
+ - title: October
+ path: /security/bulletin/2017-10-01
+ - title: September
+ path: /security/bulletin/2017-09-01
+ - title: August
+ path: /security/bulletin/2017-08-01
+ - title: July
+ path: /security/bulletin/2017-07-01
+ - title: June
+ path: /security/bulletin/2017-06-01
+ - title: May
+ path: /security/bulletin/2017-05-01
+ - title: April
+ path: /security/bulletin/2017-04-01
+ - title: March
+ path: /security/bulletin/2017-03-01
+ - title: February
+ path: /security/bulletin/2017-02-01
+ - title: January
+ path: /security/bulletin/2017-01-01
+ - title: Index
+ path: /security/bulletin/2017
+ - title: 2016 Bulletins
+ section:
+ - title: December
+ path: /security/bulletin/2016-12-01
+ - title: November
+ path: /security/bulletin/2016-11-01
+ - title: October
+ path: /security/bulletin/2016-10-01
+ - title: September
+ path: /security/bulletin/2016-09-01
+ - title: August
+ path: /security/bulletin/2016-08-01
+ - title: July
+ path: /security/bulletin/2016-07-01
+ - title: June
+ path: /security/bulletin/2016-06-01
+ - title: May
+ path: /security/bulletin/2016-05-01
+ - title: April
+ path: /security/bulletin/2016-04-02
+ - title: March
+ path: /security/bulletin/2016-03-01
+ - title: February
+ path: /security/bulletin/2016-02-01
+ - title: January
+ path: /security/bulletin/2016-01-01
+ - title: Index
+ path: /security/bulletin/2016
+ - title: 2015 Bulletins
+ section:
+ - title: December
+ path: /security/bulletin/2015-12-01
+ - title: November
+ path: /security/bulletin/2015-11-01
+ - title: October
+ path: /security/bulletin/2015-10-01
+ - title: September
+ path: /security/bulletin/2015-09-01
+ - title: August
+ path: /security/bulletin/2015-08-01
+ - title: Index
+ path: /security/bulletin/2015
+- title: Pixel/Nexus Bulletins
+ section:
+ - title: Overview
+ path: /security/bulletin/pixel/index
+ - title: 2018 Bulletins
+ section:
+ - title: August
+ path: /security/bulletin/pixel/2018-08-01
+ - title: July
+ path: /security/bulletin/pixel/2018-07-01
+ - title: June
+ path: /security/bulletin/pixel/2018-06-01
+ - title: May
+ path: /security/bulletin/pixel/2018-05-01
+ - title: April
+ path: /security/bulletin/pixel/2018-04-01
+ - title: March
+ path: /security/bulletin/pixel/2018-03-01
+ - title: February
+ path: /security/bulletin/pixel/2018-02-01
+ - title: January
+ path: /security/bulletin/pixel/2018-01-01
+ - title: Index
+ path: /security/bulletin/pixel/2018
+ - title: 2017 Bulletins
+ section:
+ - title: December
+ path: /security/bulletin/pixel/2017-12-01
+ - title: November
+ path: /security/bulletin/pixel/2017-11-01
+ - title: October
+ path: /security/bulletin/pixel/2017-10-01
+ - title: Index
+ path: /security/bulletin/pixel/2017
diff --git a/en/security/_toc-features.yaml b/en/security/_toc-features.yaml
new file mode 100644
index 0000000..eb4a908
--- /dev/null
+++ b/en/security/_toc-features.yaml
@@ -0,0 +1,89 @@
+toc:
+- title: Application Sandbox
+ path: /security/app-sandbox
+- title: Application Signing
+ section:
+ - title: Overview
+ path: /security/apksigning/
+ - title: APK Signature Scheme v2
+ path: /security/apksigning/v2
+ - title: APK Signature Scheme v3
+ path: /security/apksigning/v3
+- title: Authentication
+ section:
+ - title: Overview
+ path: /security/authentication/
+ - title: Fingerprint HAL
+ path: /security/authentication/fingerprint-hal
+ - title: Gatekeeper
+ path: /security/authentication/gatekeeper
+- title: Biometric Unlock
+ section:
+ - title: Overview
+ path: /security/biometric/
+ - title: Measuring Biometric Security
+ path: /security/biometric/measure
+- title: Keystore
+ section:
+ - title: Overview
+ path: /security/keystore/
+ - title: Features
+ path: /security/keystore/features
+ - title: Key Attestation
+ path: /security/keystore/attestation
+ - title: Version Binding
+ path: /security/keystore/version-binding
+ - title: Authorization Tags
+ path: /security/keystore/tags
+ - title: Functions
+ path: /security/keystore/implementer-ref
+- title: Trusty TEE
+ section:
+ - title: Overview
+ path: /security/trusty/
+ - title: Trusty API Reference
+ path: /security/trusty/trusty-ref
+- title: Encryption
+ section:
+ - title: Overview
+ path: /security/encryption/
+ - title: File-Based Encryption
+ path: /security/encryption/file-based
+ - title: Full-Disk Encryption
+ path: /security/encryption/full-disk
+ - title: Metadata Encryption
+ path: /security/encryption/metadata
+- title: SELinux
+ section:
+ - title: Overview
+ path: /security/selinux/
+ - title: Concepts
+ path: /security/selinux/concepts
+ - title: Implementation
+ path: /security/selinux/implement
+ - title: Customization
+ path: /security/selinux/customize
+ - title: Building sepolicy
+ path: /security/selinux/build
+ - title: Compatibility
+ path: /security/selinux/compatibility
+ - title: Validation
+ path: /security/selinux/validate
+ - title: Writing Policy
+ path: /security/selinux/device-policy
+ - title: Vendor init
+ path: /security/selinux/vendor-init
+- title: Verified Boot
+ section:
+ - title: Overview
+ path: /security/verifiedboot/
+ - title: Device State
+ path: /security/verifiedboot/device-state
+ - title: Verifying Boot
+ path: /security/verifiedboot/verified-boot
+ - title: Boot Flow
+ path: /security/verifiedboot/boot-flow
+ - title: Implementing dm-verity
+ path: /security/verifiedboot/dm-verity
+ - title: Reference Implementation
+ path: /security/verifiedboot/avb
diff --git a/en/security/_toc-fuzz.yaml b/en/security/_toc-fuzz.yaml
new file mode 100644
index 0000000..2e51dff
--- /dev/null
+++ b/en/security/_toc-fuzz.yaml
@@ -0,0 +1,17 @@
+toc:
+- title: Overview
+ path: /devices/tech/debug/fuzz-sanitize
+- title: AddressSanitizer
+ path: /devices/tech/debug/asan
+- title: LLVM Sanitizers
+ path: /devices/tech/debug/sanitizers
+- title: Build kernel with KASAN+KCOV
+ path: /devices/tech/debug/kasan-kcov
+- title: Fuzzing with libFuzzer
+ path: /devices/tech/debug/libfuzzer
+- title: Control Flow Integrity (CFI)
+ path: /devices/tech/debug/cfi
+- title: Kernel CFI
+ path: /devices/tech/debug/kcfi
+- title: Integer Overflow Sanitization
+ path: /devices/tech/debug/intsan
diff --git a/en/security/_toc-overview.yaml b/en/security/_toc-overview.yaml
new file mode 100644
index 0000000..9833bed
--- /dev/null
+++ b/en/security/_toc-overview.yaml
@@ -0,0 +1,37 @@
+toc:
+- title: Overview
+ path: /security/
+- title: Kernel Security
+ path: /security/overview/kernel-security
+- title: App Security
+ path: /security/overview/app-security
+- title: Implementing Security
+ path: /security/overview/implement
+- title: Updates and Resources
+ path: /security/overview/updates-resources
+- title: Reports
+ path: /security/overview/reports
+- title: Enhancements
+ section:
+ - title: Overview
+ path: /security/enhancements/
+ - title: Android 9
+ path: /security/enhancements/enhancements9
+ - title: Android 8.0
+ path: /security/enhancements/enhancements80
+ - title: Android 7.0
+ path: /security/enhancements/enhancements70
+ - title: Android 6.0
+ path: /security/enhancements/enhancements60
+ - title: Android 5.0
+ path: /security/enhancements/enhancements50
+ - title: Android 4.4
+ path: /security/enhancements/enhancements44
+ - title: Android 4.3
+ path: /security/enhancements/enhancements43
+ - title: Android 4.2
+ path: /security/enhancements/enhancements42
+ - title: Android 4.1
+ path: /security/enhancements/enhancements41
+- title: Acknowledgements
+ path: /security/overview/acknowledgements
diff --git a/en/security/_toc.yaml b/en/security/_toc.yaml
deleted file mode 100644
index f21fb73..0000000
--- a/en/security/_toc.yaml
+++ /dev/null
@@ -1,233 +0,0 @@
-toc:
-- title: Overview
- path: /security/
-- title: Kernel Security
- path: /security/overview/kernel-security
-- title: App Security
- path: /security/overview/app-security
-- title: Implementing Security
- path: /security/overview/implement
-- title: Updates and Resources
- path: /security/overview/updates-resources
-- title: Reports
- path: /security/overview/reports
-- title: Enhancements
- section:
- - title: Overview
- path: /security/enhancements/
- - title: Android 8.0
- path: /security/enhancements/enhancements80
- - title: Android 7.0
- path: /security/enhancements/enhancements70
- - title: Android 6.0
- path: /security/enhancements/enhancements60
- - title: Android 5.0
- path: /security/enhancements/enhancements50
- - title: Android 4.4
- path: /security/enhancements/enhancements44
- - title: Android 4.3
- path: /security/enhancements/enhancements43
- - title: Android 4.2
- path: /security/enhancements/enhancements42
- - title: Android 4.1
- path: /security/enhancements/enhancements41
-- title: Acknowledgements
- path: /security/overview/acknowledgements
-- title: Bulletins
- section:
- - title: Overview
- path: /security/bulletin/
- - title: Advisories
- section:
- - title: Overview
- path: /security/advisory/
- - title: March 2016
- path: /security/advisory/2016-03-18
- - title: Android Bulletins
- section:
- - title: 2018 Bulletins
- section:
- - title: July
- path: /security/bulletin/2018-07-01
- - title: June
- path: /security/bulletin/2018-06-01
- - title: May
- path: /security/bulletin/2018-05-01
- - title: April
- path: /security/bulletin/2018-04-01
- - title: March
- path: /security/bulletin/2018-03-01
- - title: February
- path: /security/bulletin/2018-02-01
- - title: January
- path: /security/bulletin/2018-01-01
- - title: Index
- path: /security/bulletin/2018
- - title: 2017 Bulletins
- section:
- - title: December
- path: /security/bulletin/2017-12-01
- - title: November
- path: /security/bulletin/2017-11-01
- - title: October
- path: /security/bulletin/2017-10-01
- - title: September
- path: /security/bulletin/2017-09-01
- - title: August
- path: /security/bulletin/2017-08-01
- - title: July
- path: /security/bulletin/2017-07-01
- - title: June
- path: /security/bulletin/2017-06-01
- - title: May
- path: /security/bulletin/2017-05-01
- - title: April
- path: /security/bulletin/2017-04-01
- - title: March
- path: /security/bulletin/2017-03-01
- - title: February
- path: /security/bulletin/2017-02-01
- - title: January
- path: /security/bulletin/2017-01-01
- - title: Index
- path: /security/bulletin/2017
- - title: 2016 Bulletins
- section:
- - title: December
- path: /security/bulletin/2016-12-01
- - title: November
- path: /security/bulletin/2016-11-01
- - title: October
- path: /security/bulletin/2016-10-01
- - title: September
- path: /security/bulletin/2016-09-01
- - title: August
- path: /security/bulletin/2016-08-01
- - title: July
- path: /security/bulletin/2016-07-01
- - title: June
- path: /security/bulletin/2016-06-01
- - title: May
- path: /security/bulletin/2016-05-01
- - title: April
- path: /security/bulletin/2016-04-02
- - title: March
- path: /security/bulletin/2016-03-01
- - title: February
- path: /security/bulletin/2016-02-01
- - title: January
- path: /security/bulletin/2016-01-01
- - title: Index
- path: /security/bulletin/2016
- - title: 2015 Bulletins
- section:
- - title: December
- path: /security/bulletin/2015-12-01
- - title: November
- path: /security/bulletin/2015-11-01
- - title: October
- path: /security/bulletin/2015-10-01
- - title: September
- path: /security/bulletin/2015-09-01
- - title: August
- path: /security/bulletin/2015-08-01
- - title: Index
- path: /security/bulletin/2015
- - title: Pixel/Nexus Bulletins
- section:
- - title: Overview
- path: /security/bulletin/pixel/index
- - title: 2018 Bulletins
- section:
- - title: July
- path: /security/bulletin/pixel/2018-07-01
- - title: June
- path: /security/bulletin/pixel/2018-06-01
- - title: May
- path: /security/bulletin/pixel/2018-05-01
- - title: April
- path: /security/bulletin/pixel/2018-04-01
- - title: March
- path: /security/bulletin/pixel/2018-03-01
- - title: February
- path: /security/bulletin/pixel/2018-02-01
- - title: January
- path: /security/bulletin/pixel/2018-01-01
- - title: Index
- path: /security/bulletin/pixel/2018
- - title: 2017 Bulletins
- section:
- - title: December
- path: /security/bulletin/pixel/2017-12-01
- - title: November
- path: /security/bulletin/pixel/2017-11-01
- - title: October
- path: /security/bulletin/pixel/2017-10-01
- - title: Index
- path: /security/bulletin/pixel/2017
-- title: Application Signing
- section:
- - title: Overview
- path: /security/apksigning/
- - title: APK Signature Scheme v2
- path: /security/apksigning/v2
-- title: Authentication
- section:
- - title: Overview
- path: /security/authentication/
- - title: Fingerprint HAL
- path: /security/authentication/fingerprint-hal
- - title: Gatekeeper
- path: /security/authentication/gatekeeper
-- title: Biometric Unlock
- path: /security/biometric/
-- title: Keystore
- section:
- - title: Overview
- path: /security/keystore/
- - title: Features
- path: /security/keystore/features
- - title: Key Attestation
- path: /security/keystore/attestation
- - title: Version Binding
- path: /security/keystore/version-binding
- - title: Authorization Tags
- path: /security/keystore/tags
- - title: Functions
- path: /security/keystore/implementer-ref
-- title: Trusty TEE
- section:
- - title: Overview
- path: /security/trusty/
- - title: Trusty API Reference
- path: /security/trusty/trusty-ref
-- title: Encryption
- section:
- - title: Overview
- path: /security/encryption/
- - title: File-Based Encryption
- path: /security/encryption/file-based
- - title: Full-Disk Encryption
- path: /security/encryption/full-disk
-- title: SELinux
- section:
- - title: Overview
- path: /security/selinux/
- - title: Concepts
- path: /security/selinux/concepts
- - title: Implementation
- path: /security/selinux/implement
- - title: Customization
- path: /security/selinux/customize
- - title: Validation
- path: /security/selinux/validate
- - title: Writing Policy
- path: /security/selinux/device-policy
-- title: Verified Boot
- section:
- - title: Overview
- path: /security/verifiedboot/
- - title: Verifying Boot
- path: /security/verifiedboot/verified-boot
- - title: Implementing dm-verity
- path: /security/verifiedboot/dm-verity
diff --git a/en/security/apksigning/index.html b/en/security/apksigning/index.html
index 6d89be2..53130c7 100644
--- a/en/security/apksigning/index.html
+++ b/en/security/apksigning/index.html
@@ -69,17 +69,23 @@
UID feature</a> where two or more applications signed with same developer key
can declare a shared UID in their manifest.
</p>
-<h2>APK signing schemes</h2>
+<h2 id="schemes">APK signing schemes</h2>
<p>
-Android supports two application signing schemes, one based on JAR signing (v1
-scheme) and <a href="v2.html">APK Signature Scheme v2 (v2 scheme)</a>, which
-was introduced in Android Nougat (Android 7.0).
-</p>
+Android supports three application signing schemes:</p>
+<ul>
+ <li>v1 scheme: based on JAR signing</li>
+ <li>v2 scheme: <a href="/security/apksigning/v2.html">APK Signature Scheme v2</a>,
+ which was introduced in Android 7.0.</li>
+ <li>v3 scheme: <a href="/security/apksigning/v3.html">APK Signature Scheme v3</a>,
+ which was introduced in Android 9.</li>
+</ul>
+
<p>
-For maximum compatibility, applications should be signed both with v1 and v2
-schemes. Android Nougat and newer devices install apps signed with v2 scheme
-more quickly than those signed only with v1 scheme. Older Android platforms
-ignore v2 signatures and thus need apps to contain v1 signatures.
+For maximum compatibility, sign applications with all
+schemes, first with v1, then v2, and then v3. Android 7.0+ and newer devices
+install apps signed with v2+ schemes more quickly than those signed only with
+v1 scheme. Older Android platforms ignore v2+ signatures and thus need apps to
+contain v1 signatures.
</p>
<h3 id="v1">JAR signing (v1 scheme)</h3>
<p>
@@ -97,16 +103,18 @@
compressed entries, consuming more time and memory. To address these issues,
Android 7.0 introduced APK Signature Scheme v2.
</p>
-<h3 id="v2">APK Signature Scheme v2 (v2 scheme)</h3>
+<h3 id="v2">APK Signature Scheme v2 & v3 (v2+ scheme)</h3>
<p>
-Android 7.0 introduces APK signature scheme v2 (v2 scheme). The contents of the
-APK are hashed and signed, then the resulting APK Signing Block is inserted
-into the APK. For details on applying the v2 scheme to an application, refer to
+Devices running Android 7.0 and later support APK signature scheme v2 (v2
+scheme) and later. (v2 scheme was updated to v3 in Android P to include
+additional information in the signing block, but otherwise works the same.) The
+contents of the APK are hashed and signed, then the resulting APK Signing Block
+is inserted into the APK. For details on applying the v2+ scheme to an app, see
<a href="https://developer.android.com/about/versions/nougat/android-7.0.html#apk_signature_v2">APK
-Signature Scheme v2</a> in the Android N Developer Preview.
+Signature Scheme v2</a>.
</p>
<p>
-During validation, v2 scheme treats the APK file as a blob and performs signature
+During validation, v2+ scheme treats the APK file as a blob and performs signature
checking across the entire file. Any modification to the APK, including ZIP metadata
modifications, invalidates the APK signature. This form of APK verification is
substantially faster and enables detection of more classes of unauthorized
@@ -121,15 +129,15 @@
<img src="../images/apk-validation-process.png" alt="APK signature verification process" id="figure1" />
</p>
<p class="img-caption"><strong>Figure 1.</strong> APK signature verification
-process (new steps in red)</p>
+process</p>
<p>
-Whole-file hash of the APK is verified against the v2 signature stored in the
+Whole-file hash of the APK is verified against the v2+ signature stored in the
APK Signing Block. The hash covers everything except the APK Signing Block,
-which contains the v2 signature. Any modification to the APK outside of the APK
-Signing Block invalidates the APK's v2 signature. APKs with stripped v2
+which contains the v2+ signature. Any modification to the APK outside of the APK
+Signing Block invalidates the APK's v2+ signature. APKs with stripped v2+
signature are rejected as well, because their v1 signature specifies that the
-APK was v2-signed, which makes Android Nougat and newer refuse to verify APKs
+APK was v2-signed, which makes Android 7.0 and newer refuse to verify APKs
using their v1 signatures.
</p>
diff --git a/en/security/apksigning/v2.html b/en/security/apksigning/v2.html
index 4497d63..4e801c5 100644
--- a/en/security/apksigning/v2.html
+++ b/en/security/apksigning/v2.html
@@ -53,7 +53,7 @@
<h2 id="apk-signing-block">APK Signing Block</h2>
<p>
-To maintain backward-compatibility with the current APK format, v2 and newer APK
+To maintain backward-compatibility with the v1 APK format, v2 and newer APK
signatures are stored inside an APK Signing Block, a new container introduced to
support APK Signature Scheme v2. In an APK file, the APK Signing Block is located
immediately before the ZIP Central Directory, which is located at the end of the file.
@@ -280,13 +280,13 @@
<h2 id="verification">Verification</h2>
-<p>In Android 7.0, APKs can be verified according to the APK Signature Scheme v2
-(v2 scheme) or JAR signing (v1 scheme). Older platforms ignore v2 signatures
+<p>In Android 7.0 and later, APKs can be verified according to the APK
+Signature Scheme v2+ or JAR signing (v1 scheme). Older platforms ignore v2 signatures
and only verify v1 signatures.
</p>
<p>
- <img src="../images/apk-validation-process.png" alt="APK signature verification process" id="figure4" />
+ <img src="../images/apk-v2-validation.png" alt="APK signature verification process" id="figure4" />
</p>
<p class="img-caption"><strong>Figure 4.</strong> APK signature verification
process (new steps in red)</p>
@@ -361,8 +361,8 @@
</ol>
<p>
-The protection chain is thus <signer>.(RSA|DSA|EC) -> <signer>.SF -> MANIFEST.MF
--> contents of each integrity-protected JAR entry.
+The protection chain is thus <signer>.(RSA|DSA|EC) -> <signer>.SF -> MANIFEST.MF
+-> contents of each integrity-protected JAR entry.
</p>
diff --git a/en/security/apksigning/v3.html b/en/security/apksigning/v3.html
new file mode 100644
index 0000000..e5b8594
--- /dev/null
+++ b/en/security/apksigning/v3.html
@@ -0,0 +1,306 @@
+<html devsite>
+ <head>
+ <title>APK Signature Scheme v3</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ <body>
+ <!--
+ Copyright 2018 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
+
+ //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 9 supports <a
+href="https://developer.android.com/preview/features/security#apk-key-rotation">APK
+key rotation</a>, which gives apps the ability to change their signing key as
+part of an APK update. To make rotation practical, APKs must indicate levels of
+trust between the new and old signing key. To support key rotation, we updated
+the <a href="/security/apksigning/v2">APK signature
+scheme</a> from v2 to v3 to allow the new and old keys to be used. V3 adds
+information about the supported SDK versions and a proof-of-rotation struct to
+the APK signing block.
+</p>
+<h2 id="apk-signing-block">APK Signing Block</h2>
+<p>
+To maintain backward-compatibility with the v1 APK format, v2 and v3 APK
+signatures are stored inside an APK Signing Block, located immediately before
+the ZIP Central Directory.
+</p>
+<p>
+The v3 APK Signing Block format is the <a
+href="/security/apksigning/v2#apk-signing-block-format">same
+as v2</a>. The v3 signature of the APK is stored as an ID-value pair with ID
+0xf05368c0.
+</p>
+<h2 id="apk-signature-scheme-v3-block">APK Signature Scheme v3 Block</h2>
+<p>
+The v3 scheme is designed to be very similar to the <a
+href="/security/apksigning/v2#apk-signature-scheme-v2-block">v2
+scheme</a>. It has the same general format and supports the same <a
+href="/security/apksigning/v2#signature-algorithm-ids">signature
+algorithm IDs</a>, key sizes, and EC curves.
+</p>
+<p>
+However, the v3 scheme adds information about the supported SDK versions and the
+proof-of-rotation struct.
+</p>
+<h3 id="format">Format</h3>
+<p>
+APK Signature Scheme v3 Block is stored inside the APK Signing Block under ID
+<code>0xf05368c0</code>.
+</p>
+<p>
+The format of the APK Signature Scheme v3 Block follows that of v2:
+</p>
+
+<ul>
+ <li>length-prefixed sequence of length-prefixed <code>signer</code>:
+ <ul>
+ <li>length-prefixed <code>signed data</code>:
+ <ul>
+ <li>length-prefixed sequence of length-prefixed <code>digests</code>:
+ <ul>
+ <li><code>signature algorithm ID</code> (4 bytes)</li>
+ <li><code>digest</code> (length-prefixed)</li>
+ </ul>
+ </li>
+ <li>length-prefixed sequence of X.509 <code>certificates</code>:
+ <ul>
+ <li>length-prefixed X.509 <code>certificate</code> (ASN.1 DER form)</li>
+ </ul>
+ </li>
+ <li><code>minSDK</code> (uint32) - this signer should be ignored if
+ platform version is below this number.</li>
+ <li><code>maxSDK</code> (uint32) - this signer should be ignored if
+ platform version is above this number.</li>
+ <li>length-prefixed sequence of length-prefixed <code>additional
+ attributes</code>:
+ <ul>
+ <li><code>ID</code> (uint32)</li>
+ <li><code>value</code> (variable-length: length of the additional
+ attribute - 4 bytes)</li>
+ <li><code>ID -<strong> 0x3ba06f8c</strong></code></li>
+ <li><code>value -</code> Proof-of-rotation struct</li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li><code>minSDK</code> (uint32) - duplicate of minSDK value in signed data
+ section - used to skip verification of this signature if the current platform is
+ not in range. Must match signed data value.</li>
+ <li><code>maxSDK</code> (uint32) - duplicate of the maxSDK value in the signed
+ data section - used to skip verification of this signature if the current
+ platform is not in range. Must match signed data value.</li>
+ <li>length-prefixed sequence of length-prefixed <code>signatures</code>:
+ <ul>
+ <li><code>signature algorithm ID</code> (uint32)</li>
+ <li>length-prefixed <code>signature</code> over <code>signed data</code></li>
+ </ul>
+ </li>
+ <li>length-prefixed <code>public key</code> (SubjectPublicKeyInfo, ASN.1 DER
+ form)</li>
+ </ul>
+ </li>
+</ul>
+
+<h2 id="proof-of-rotation-and-self-trusted-old-certs-structs">Proof-of-rotation
+and self-trusted-old-certs structs</h2>
+<p>
+The proof-of rotation struct allows apps to rotate their signing cert without
+being blocked on other apps with which they communicate. To accomplish this, app
+signatures contain two new pieces of data:
+</p>
+<ul>
+ <li>assertion for third parties that the app's signing cert can be trusted
+ wherever its predecessors are trusted</li>
+ <li>app's older signing certs which the app itself still trusts</li>
+</ul>
+<p>
+The proof-of-rotation attribute in the signed-data section consists of a
+singly-linked list, with each node containing a signing certificate used to sign
+previous versions of the app. This attribute is meant to contain the conceptual
+proof-of-rotation and self-trusted-old-certs data structures. The list is
+ordered by version with the oldest signing cert corresponding to the root node.
+The proof-of-rotation data structure is built by having the cert in each node
+sign the next in the list, and thus imbuing each new key with evidence that it
+should be as trusted as the older key(s).
+</p>
+<p>
+The self-trusted-old-certs data structure is constructed by adding flags to each
+node indicating its membership, and properties, in the set. For example, a flag
+may be present indicating that the signing certificate at a given node is
+trusted for obtaining Android signature permissions, so that other apps which
+are signed by it still may be granted that permission, even though they are now
+behind the defining app. Because the whole proof-of-rotation attribute resides
+in the signed data section of the v3 <code>signer</code> field, it is protected
+by the key used to sign the containing apk.
+</p>
+<p>
+This format precludes <a href="#multiple-certificates">multiple signing keys</a>
+and convergence of <a
+href="#multiple-ancestors">different ancestor
+signing certificates</a> to one (multiple starting nodes to a common sink).
+</p>
+
+<h3 id="proof-of-rotation-format">Format</h3>
+<p>
+The proof-of-rotation is stored inside the APK Signature Scheme v3 Block under
+ID <code>0x3ba06f8c</code>. Its format is:
+</p>
+
+<ul>
+ <li>length-prefixed sequence of length-prefixed <code>levels</code>:
+ <ul>
+ <li>length-prefixed <code>signed data</code> (by previous cert - if exists)
+ <ul>
+ <li>length-prefixed X.509 <code>certificate</code> (ASN.1 DER form)</li>
+ <li><code>signature algorithm ID</code> (uint32) - algorithm used by cert in
+ previous level</li>
+ </ul>
+ </li>
+ <li><code>flags</code> (uint32) - flags indicating whether or not this cert
+ should be in the self-trusted-old-certs struct, and for which operations.</li>
+ <li><code>signature algorithm ID</code> (uint32) - must match the one from the
+ signed data section in the next level.</li>
+ <li>length-prefixed <code>signature</code> over the above <code>signed
+ data</code></li>
+ </ul>
+ </li>
+</ul>
+
+<h3 id="multiple-certificates">Multiple certificates</h3>
+<p>
+Android currently treats an APK signed with multiple certificates as having a
+unique signing identity separate from the comprising certs. Thus, the
+proof-of-rotation attribute in the signed-data section forms a directed acyclic
+graph, that could better be viewed as a singly-linked list, with each set of
+signers for a given version representing one node. This adds extra complexity to
+the proof-of-rotation struct (multi-signer version below). In particular,
+ordering becomes a concern. What's more, it is no longer possible to sign APKs
+independently, because the proof-of-rotation structure must have the old signing
+certs signing the new set of certs, rather than signing them one-by-one. For
+example, an APK signed by key A that wishes to be signed by two new keys B and C
+could not have the B signer just include a signature by A of B, because that is
+a different signing identity than B and C. This would mean that the signers must
+coordinate before building up such a struct.
+</p>
+<h4 id="multiple-signers-proof-of-rotation-attribute">Multiple signers
+proof-of-rotation attribute</h4>
+<ul>
+ <li>length-prefixed sequence of length-prefixed <code>sets</code>:
+ <ul>
+ <li><code>signed data</code> (by previous set - if exists)
+ <ul>
+ <li>length-prefixed sequence of <code>certificates</code>
+ <ul>
+ <li>length-prefixed X.509 <code>certificate</code> (ASN.1 DER form)</li>
+ </ul>
+ </li>
+ <li>Sequence of <code>signature algorithm IDs </code>(uint32) - one for each
+ certificate from the previous set, in the same order.</li>
+ </ul>
+ </li>
+ <li><code>flags </code>(uint32) - flags indicating whether or not this set of
+ certs should be in the self-trusted-old-certs struct, and for which
+ operations.</li>
+ <li>length-prefixed sequence of length-prefixed <code>signatures</code>:
+ <ul>
+ <li><code>signature algorithm ID</code> (uint32) - must match the one from the
+ signed data section</li>
+ <li>length-prefixed <code>signature</code> over the above
+ <code>signed data</code></li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+</ul>
+
+<h3 id="multiple-ancestors">Multiple ancestors in proof-of-rotation struct</h3>
+<p>
+v3 scheme also doesn't handle two different keys rotating to the same signing
+key for the same app. This differs from the case of an acquisition, where the
+acquiring company would like to move the acquired app to use its signing key to
+share permissions. The acquisition is viewed as a supported use-case because the
+new app would be distinguished by its package name and could contain its own
+proof-of-rotation struct. The unsupported case, of the same app having two
+different paths to get to the same cert, breaks a lot of the assumptions made in
+the key rotation design.
+</p>
+<h2 id="verification">Verification</h2>
+<p>In Android 9 and higher, APKs can be verified according to the APK Signature
+Scheme v3, v2 scheme, or v1 scheme. Older platforms ignore v3 signatures and try
+to verify v2 signatures, then v1.
+<p>
+ <img src="../images/apk-validation-process.png" alt="APK signature verification process" id="figure1" />
+</p>
+<p class="img-caption"><strong>Figure 1.</strong> APK signature verification
+process</p>
+
+<h3 id="v3-verification">APK Signature Scheme v3 verification</h3>
+<ol>
+ <li>Locate the APK Signing Block and verify that:
+ <ol>
+ <li>Two size fields of APK Signing Block contain the same value.</li>
+ <li>ZIP Central Directory is immediately followed by ZIP End of Central
+ Directory record.</li>
+ <li>ZIP End of Central Directory is not followed by more data.</li>
+ </ol>
+ </li>
+ <li>Locate the first APK Signature Scheme v3 Block inside the APK Signing Block.
+ If the v3 Block is present, proceed to step 3. Otherwise, fall back to verifying
+ the APK <a href="/security/apksigning/v2#v2-verification">using v2 scheme</a>.</li>
+ <li>For each <code>signer</code> in the APK Signature Scheme v3 Block with a min
+ and max SDK version that is in range of the current platform:
+ <ol>
+ <li>Choose the strongest supported <code>signature algorithm ID</code> from
+ <code>signatures</code>. The strength ordering is up to each
+ implementation/platform version.</li>
+ <li>Verify the corresponding <code>signature</code> from
+ <code>signatures</code> against <code>signed data</code> using <code>public
+ key</code>. (It is now safe to parse <code>signed data</code>.)</li>
+ <li>Verify the min and max SDK versions in the signed data match those
+ specified for the <code>signer</code>.</li>
+ <li>Verify that the ordered list of signature algorithm IDs in
+ <code>digests</code> and <code>signatures</code> is identical. (This is
+ to prevent signature stripping/addition.)</li>
+ <li><a href="/security/apksigning/v2#integrity-protected-contents">Compute
+ the digest of APK contents</a> using the same digest algorithm as the digest
+ algorithm used by the signature algorithm.</li>
+ <li>Verify that the computed digest is identical to the corresponding
+ <code>digest</code> from <code>digests</code>.</li>
+ <li>Verify that SubjectPublicKeyInfo of the first <code>certificate</code> of
+ <code>certificates</code> is identical to <code>public key</code>.</li>
+ <li>If the proof-of-rotation attribute exists for the <code>signer</code> verify
+ that the struct is valid and this <code>signer</code> is the last
+ certificate in the list.</li>
+ </ol>
+ </li>
+ <li>Verification succeeds if exactly one <code>signer</code> was found in range
+ of the current platform and step 3 succeeded for that <code>signer</code>.</li>
+</ol>
+
+<aside class="caution">
+<strong>Caution</strong>: APK must not be verified using the v1 or v2 scheme if a
+failure occurs in step 3 or 4.
+</aside>
+
+<h2 id="validation">Validation</h2>
+<p>
+To test that your device supports v3 properly, run the
+<code>PkgInstallSignatureVerificationTest.java</code> CTS tests in
+<code>cts/hostsidetests/appsecurity/src/android/appsecurity/cts/</code>.
+</p>
+</body>
+</html>
diff --git a/en/security/app-sandbox.html b/en/security/app-sandbox.html
new file mode 100644
index 0000000..1360161
--- /dev/null
+++ b/en/security/app-sandbox.html
@@ -0,0 +1,121 @@
+<html devsite>
+ <head>
+ <title>Application Sandbox</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ <body>
+ <!--
+ Copyright 2018 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
+
+ //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 Android platform takes advantage of the Linux user-based protection to
+identify and isolate app resources. This isolates apps from each other and
+protects apps and the system from malicious apps. To do this, Android assigns a
+unique user ID (UID) to each Android application and runs it in its own
+process.
+</p>
+<p>
+Android uses this UID to set up a kernel-level Application Sandbox. The kernel
+enforces security between apps and the system at the process level through
+standard Linux facilities, such as user and group IDs that are assigned to apps.
+By default, apps can't interact with each other and have limited access to the
+operating system. For example, if application A tries to do something
+malicious, such as read application B's data or dial the phone without
+permission (which is a separate application), then the operating system protects
+against this behavior because application A does not have the appropriate user
+privileges. The sandbox is simple, auditable, and based on decades-old
+UNIX-style user separation of processes and file permissions.
+</p>
+<p>
+Because the Application Sandbox is in the kernel, this security model extends to
+native code and to operating system applications. All of the software above the
+kernel, such as operating system libraries, application framework, application
+runtime, and all applications, run within the Application Sandbox. On some
+platforms, developers are constrained to a specific development framework, set
+of APIs, or language in order to enforce security. On Android, there are no
+restrictions on how an application can be written that are required to enforce
+security; in this respect, native code is as sandboxed as interpreted code.
+</p>
+
+<h2 id="protections">Protections</h2>
+<p>
+Generally, to break out of the Application Sandbox in a properly configured
+device, one must compromise the security of the Linux kernel. However, similar
+to other security features, individual protections enforcing the application
+sandbox are not invulnerable, so defense-in-depth is important to prevent single
+vulnerabilities from leading to compromise of the OS or other apps.
+</p>
+<p>
+Android relies on a number of protections to enforce the application sandbox.
+These enforcements have been introduced over time and have significantly
+strengthened the original UID-based discretionary access control (DAC) sandbox.
+Previous Android releases included the following protections:
+</p>
+
+<ul>
+ <li>In Android 5.0, SELinux provided mandatory access control (MAC)
+ separation between the system and apps. However, all third-party apps ran
+ within the same SELinux context so inter-app isolation was primarily
+ enforced by UID DAC.</li>
+ <li>In Android 6.0, the SELinux sandbox was extended to isolate apps across
+ the per-physical-user boundary. In addition, Android also set safer defaults
+ for application data: For apps with <code>targetSdkVersion >= 24</code>,
+ default DAC permissions on an app's home dir changed from 751 to 700. This
+ provided safer default for private app data (although apps may override
+ these defaults).</li>
+ <li>In Android 8.0, all apps were set to run with a <code>seccomp-bpf</code>
+ filter that limited the syscalls that apps were allowed to use, thus
+ strengthening the app/kernel boundary.</li>
+ <li>In Android 9 all non-privileged apps with <code>targetSdkVersion >=
+ 28</code> must run in individual SELinux sandboxes, providing MAC on a
+ per-app basis. This protection improves app separation, prevents overriding
+ safe defaults, and (most significantly) prevents apps from making their
+ data world accessible.</li>
+</ul>
+
+<h2 id="guidelines-for-sharing-files">Guidelines for sharing files</h2>
+<p>
+Setting app data as world accessible is a poor security practice as access is
+granted to everyone and there is no way to limit access to only the intended
+recipient(s). This practice has led to information disclosure leaks, confused
+deputy vulnerabilities, and is a favorite target for malware that targets apps
+with sensitive data (such as email clients). In Android 9 and higher, sharing
+files this way is explicitly disallowed for apps with
+<code>targetSdkVersion>=28</code>.
+</p>
+<p>
+Instead of making app data world-accessible, use the following guidelines when
+sharing files:
+</p>
+<ul>
+ <li>If your app needs to share files with another app, use a <a
+ href="https://developer.android.com/guide/topics/providers/content-provider-basics.html">content
+ provider</a> or shared location on <a
+ href="https://developer.android.com/guide/topics/data/data-storage.html#filesExternal">external
+ storage</a>. Content providers share data with the proper granularity and
+ without the many downsides of world-accessible UNIX permissions (for
+ details, refer to <a
+ href="https://developer.android.com/guide/topics/providers/content-provider-basics.html">Content
+ provider basics</a>).</li>
+ <li>If your app has files that genuinely should be accessible to the world
+ (such as photos), use <a
+ href="https://developer.android.com/guide/topics/data/data-storage.html#filesExternal">external
+ storage</a>. For help, refer to <a
+ href="https://developer.android.com/training/data-storage/files.html#PublicFiles">Save
+ file to public directory</a>.</li>
+</ul>
+ </body>
+</html>
diff --git a/en/security/authentication/fingerprint-hal.html b/en/security/authentication/fingerprint-hal.html
index 02ee3e4..a3a656f 100644
--- a/en/security/authentication/fingerprint-hal.html
+++ b/en/security/authentication/fingerprint-hal.html
@@ -65,9 +65,13 @@
<figcaption><strong>Figure 1.</strong> High-level data flow for fingerprint
authentication.</figcaption>
<ul>
- <li><code>FingerprintManager</code> API. Interacts directly with an app in
- an app process. Each app has an instance of <code>FingerprintManager</code>,
- a wrapper that communicates with <code>FingerprintService</code>.</li>
+ <li>Biometric API. For devices that launcher with Android 8.1 and lower,
+ <code>FingerprintManager</code> interacts directly with an app in an app
+ process. Each app has an instance of <code>FingerprintManager</code>,
+ a wrapper that communicates with <code>FingerprintService</code>.<br>
+ Devices that ship with Android 9 and higher, should use the
+ <code>BiometricPrompt</code> API instead of <code>FingerprintManager</code>.
+ </li>
<li><code>FingerprintService</code>. Singleton service that operates in
the system process, which handles communication with
<code>fingerprintd</code>.
diff --git a/en/security/authentication/index.html b/en/security/authentication/index.html
index 33c141d..77e35d9 100644
--- a/en/security/authentication/index.html
+++ b/en/security/authentication/index.html
@@ -30,23 +30,26 @@
Android supports a <a href="/security/keystore/index.html">hardware-backed
Keystore</a> and Keymaster for cryptographic services, including hardware-backed
cryptography for key storage that might include a Trusted Execution Environment
-(TEE).</li>
+(TEE) or Secure Element (SE), such as Strongbox.</li>
<li><strong>User authenticators</strong>. Attest to the user's presence and/or
successful authentication. Android supports
<a href="gatekeeper.html">Gatekeeper</a> for PIN/pattern/password authentication
and <a href="fingerprint-hal.html">Fingerprint</a> for fingerprint
-authentication. These components communicate their authentication state with the
-keystore service via an authenticated channel. (The
-<a href="https://developer.android.com/training/articles/keystore.html" class="external">Android
-Keystore system</a> at the framework level is also backed by the keystore
-service.)</li>
+authentication. Devices that ship with Android 9 and higher can use <a
+href="https://developer.android.com/reference/android/hardware/biometrics/BiometricPrompt"
+class="external">BiometricPrompt</a> as a single integration point for
+fingerprint and additional biometrics. These components communicate their
+authentication state with the keystore service via an authenticated channel.
+(The <a href="https://developer.android.com/training/articles/keystore.html"
+class="external">Android Keystore system</a> at the framework level is also
+backed by the keystore service.)</li>
</ul>
-<p>Gatekeeper and Fingerprint components work with Keystore and other components
-to support the use of hardware-backed <a href="#authtoken_format">authentication
-tokens</a> (AuthTokens).</p>
+<p>Gatekeeper, Fingerprint, and Biometric components work with Keystore and other
+components to support the use of hardware-backed
+<a href="#authtoken_format">authentication tokens</a> (AuthTokens).</p>
-<h2 id=enrollment>Enrollment</h2>
+<h2 id="enrollment">Enrollment</h2>
<p>On first boot of the device after a factory reset, all authenticators are
prepared to receive credential enrollments from the user. A user must initially
@@ -70,7 +73,7 @@
password resets, either by a device administrator or an attacker, may
cause this to occur.</p>
-<h2 id=authentication>Authentication</h2>
+<h2 id="authentication">Authentication</h2>
<p>After a user has set up a credential and received a User SID, they may
proceed to start authentication, which begins when a user provides a PIN,
@@ -78,15 +81,27 @@
they use to authenticate each other's messages.</p>
<img src="../images/authentication-flow.png" alt="Authentication flow"
-id="figure1" />
+id="Authentication flow" />
<figcaption><strong>Figure 1.</strong> Authentication flow.</figcaption>
<ol>
- <li>A user provides a PIN, pattern, password, or fingerprint. The
- <code>LockSettingsService</code> or <code>FingerprintService</code> makes a
- request via Binder to appropriate daemon (<code>gatekeeperd</code> or
- <code>fingerprintd</code>); fingerprint authentication occurs asynchronously
- after the fingerprint request is sent.</li>
+ <li>A user provides an authentication method and the associated service
+ makes a request to the the associated daemon.
+ <ul>
+ <li>For PIN, pattern, or password, the <code>LockSettingsService</code>
+ makes a request to <code>gatekeeperd</code>.</li>
+ <li>Biometrics-based authentication flows depend on the Android version.
+ On devices running Android 8.x and lower, <code>FingerprintService</code>
+ makes a request to <code>fingerprintd</code>). On devices
+ running Android 9 and higher, <code>BiometricPrompt</code> makes a
+ request to the appropriate biometric daemon (for example,
+ <code>fingerprintd</code> for fingerprints or <code>faced</code> for
+ face) using the appropriate <code><var>Biometric</var>Manager</code>
+ class, such as <code>FingerprintManager</code> or
+ <code>FaceManager</code>. Regardless of version, biometric
+ authentication occurs asynchronously after the request is sent.</li>
+ </ul>
+ </li>
<li>The daemon sends data to its counterpart, which generates an AuthToken:
<ul>
<li>For PIN/pattern/password authentication, <code>gatekeeperd</code> sends
@@ -99,22 +114,26 @@
authentication in the TEE is successful, Fingerprint in the TEE sends an
AuthToken (signed with the AuthToken HMAC key) to its counterpart in the
Android OS.</li>
+ <li>For other biometric authentication, the appropriate biometric daemon
+ listens for the biometric event and sends it to the appropriate biometric
+ TEE component.</li>
</ul>
</li>
<li>The daemon receives a signed AuthToken and passes it to the keystore
service via an extension to the keystore service's Binder interface.
(<code>gatekeeperd</code> also notifies the keystore service when the device
is re-locked and when the device password changes.)
- <li>The keystore service passes the AuthTokens to Keymaster, verifying them
- using the key shared with the Gatekeeper and Fingerprint trustlets. Keymaster
- trusts the timestamp in the token as the last authentication time and bases a
- key release decision (to allow an app to use the key) on the timestamp.</li>
+ <li>The keystore service passes the AuthTokens to Keymaster and verifies them
+ using the key shared with the Gatekeeper and supported biometric TEE
+ component. Keymaster trusts the timestamp in the token as the last
+ authentication time and bases a key release decision (to allow an app to use
+ the key) on the timestamp.</li>
</ol>
<aside class="note"><strong>Note:</strong> AuthTokens are invalidated when a
device reboots.</aside>
-<h2 id=authtoken_format>AuthToken format</h2>
+<h2 id="authtoken_format">AuthToken format</h2>
<p>To ensure token sharing and compatibility across languages and components,
the AuthToken format is described in
@@ -183,12 +202,12 @@
</tr>
</table>
-<h2 id=device_boot_flow>Device boot flow</h2>
+<h2 id="device_boot_flow">Device boot flow</h2>
<p>On every boot of a device, the AuthToken HMAC key must be generated and
-shared with all TEE components (Gatekeeper, Fingerprint, and Keymaster). Thus,
-for added protection against replay attacks, the HMAC key must be randomly
-generated every time the device reboots.</p>
+shared with all TEE components (Gatekeeper, Keymaster, and supported biometrics
+trustlets). Thus, for added protection against replay attacks, the HMAC key
+must be randomly generated every time the device reboots.</p>
<p>The protocol for sharing this HMAC key with all components is a
platform-dependent implementation feature. The key must <strong>never</strong>
@@ -199,9 +218,9 @@
<p>The <a href="/security/trusty/index.html">Trusty</a> operating system,
which runs next to Android, is an example of a TEE, but other TEEs can be used
instead. Trusty uses an internal IPC system to communicate directly between
-Keymaster and Fingerprint or Gatekeeper. The HMAC key is kept solely in
-Keymaster; Fingerprint and Gatekeeper request the key from Keymaster for each
-use and do not persist or cache the value.</p>
+Keymaster and Gatekeeper or the appropriate biometric trustlet. The HMAC key is
+kept solely in Keymaster; Fingerprint and Gatekeeper request the key from
+Keymaster for each use and do not persist or cache the value.</p>
<p>As some TEEs lack an IPC infrastructure, no communication occurs between
applets in the TEE. This also permits the keystore service to quickly deny
diff --git a/en/security/biometric/index.html b/en/security/biometric/index.html
index 6961e58..5189547 100644
--- a/en/security/biometric/index.html
+++ b/en/security/biometric/index.html
@@ -1,18 +1,18 @@
<html devsite>
<head>
- <title>Measuring Biometric Unlock Security</title>
+ <title>Biometrics</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
- Copyright 2017 The Android Open Source Project
+ Copyright 2018 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
+ //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,
@@ -20,268 +20,113 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-
-
-
<p>
-Today, biometric-based unlock modalities are evaluated almost solely on the
-basis of <em>False Accept Rate (FAR)</em>, a metric that defines how often a
-model mistakenly accepts a randomly chosen incorrect input. While this is a
-useful measure, it does not provide sufficient information to evaluate how well
-the model stands up to targeted attacks.
+Android 9 and higher includes a <a
+href="https://developer.android.com/reference/android/hardware/biometrics/BiometricPrompt"
+class="external">BiometricPrompt API</a> that app developers can use to
+integrate biometric authentication into their applications in a device- and
+modality-agnostic fashion. Only strong biometrics can integrate with
+<code>BiometricPrompt</code>. For more details, see <a
+href="/security/biometric/measure#strong-weak-unlocks">Measuring Biometric
+Unlock Security</a>.
</p>
-<h2 id="metrics">Metrics</h2>
-
+<h2 id="source">Source</h2>
<p>
-Android 8.1 introduces two new metrics associated with biometric unlocks that
-are intended to help device manufacturers evaluate their security more
-accurately:
+Android 9 only includes fingerprint integration for <a
+href="https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/hardware/biometrics"
+class="external">BiometricPrompt</a>. However, integrated support for other
+biometric modalities are forthcoming.
+</p>
+<p>
+In Android 9 and higher, the <a
+href="https://developer.android.com/reference/android/hardware/fingerprint/FingerprintManager"
+class="external">FingerprintManager</a> API is deprecated. If your bundled and
+system apps use this API, update them to use <code>BiometricPrompt</code>
+instead.
</p>
-<ul>
-<li><em>Imposter Accept Rate (IAR)</em>: The chance that a biometric model
-accepts input that is meant to mimic a known good sample. For example, in the <a
-href="https://support.google.com/nexus/answer/6093922">Smart Lock</a> trusted
-voice (voice unlock) mechanism, this would measure how often someone trying to
-mimic a user's voice (using similar tone, accent, etc) can unlock their device.
-We call such attacks <em>Imposter Attacks</em>.</li>
-<li><em>Spoof Accept Rate (SAR)<strong>:</strong></em> The chance that a
-biometric model accepts a previously recorded, known good sample. For example,
-with voice unlock this would measure the chances of unlocking a user's phone
-using a recorded sample of them saying: "Ok, Google" We call such attacks
-<em>Spoof Attacks<strong>.</strong></em></li>
-</ul>
-
+<h2 id="implementation">Implementation</h2>
<p>
-Of these, IAR measurements are not universally useful for all biometric
-modalities. Consider fingerprint for example. An attacker could create a mold of
-a user's fingerprint and attempt to use that to bypass the fingerprint sensor,
-which would count as a spoof attack. However, there isn't a way to mimic a
-fingerprint that would be accepted as the user's - and so there's not a clear
-notion of an imposter attack against fingerprint sensors.
+To ensure that users and developers have a seamless biometric experience,
+integrate your biometric stack with <code>BiometricPrompt</code>. Devices that
+enable <code>BiometricPrompt</code> API for any modality, including face,
+fingerprint, and iris, must adhere to these <a
+href="/security/biometric/measure#strong-weak-unlocks">strength
+requirements</a>. If they do not meet the strength requirements, then they
+cannot implement this API.
+</p>
+<p>
+To integrate your biometric stack with <code>BiometricPrompt</code>:
+</p>
+<ol>
+ <li>Add an instance of your <code><var>Biometric</var>Manager</code> class in <code><a
+ href="https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/hardware/biometrics/BiometricPrompt.java"
+ class="external">/frameworks/base/core/java/android/hardware/biometrics/BiometricPrompt.java</a></code></li>
+ <li>Make sure your instance hooks the <code><a
+ href="https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/hardware/biometrics/BiometricPrompt.java#467"
+ class="external">authenticate()</a></code>
+ method that <code>BiometricPrompt</code> exposes.</li>
+ <li>Update the framework to honor
+ <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager#KEYGUARD_DISABLE_FACE"
+ class="external"><code>KEYGUARD_DISABLE_*</code></a> flags for the added
+ biometrics.</li>
+</ol>
+<figure>
+ <img src="/security/images/biometricprompt-architecture.png"
+ alt="BiometricPrompt architecture">
+ <figcaption>
+ <strong>Figure 1</strong>. <code>BiometricPrompt</code>
+ architecture.</figcaption>
+</figure>
+
+<h2 id="hal-implementation">HAL implementation guidelines</h2>
+<p>
+Follow these biometric HAL guidelines to ensure that biometric data is
+<strong>not leaked</strong> and is <strong>removed</strong> when a user
+is removed from a device:
+</p>
+<ol>
+ <li>Make sure raw biometric data or derivatives (such as templates) are never
+ accessible from outside the sensor driver or secure isolated environment
+ (such as the TEE or Secure Element).</li>
+ <li>If the hardware supports it, limit hardware access to the secure isolated
+ environment and protect it with an SELinux policy. Make the communication
+ channel (e.g. SPI, I2C, etc.) accessible only to the secure isolated
+ environment with an explicit SELinux policy on all device files.</li>
+ <li>To prevent accidental data breach an immunity to attacks, fingerprint
+ acquisition, enrollment, and recognition must occur inside the secure
+ isolated environment.</li>
+ <li>Store only the encrypted form of biometric data or derivatives on the file
+ system, even if the file system itself is encrypted.</li>
+ <li>To protect against replay attacks, sign biometric templates with a private,
+ device-specific key. For Advanced Encryption Standard (AES), at a minimum
+ sign a template with the absolute file-system path, group, and biometric ID
+ such that template files are inoperable on another device or for anyone other
+ than the user that enrolled them on the same device. For example, prevent
+ copying biometric data from a different user on the same device or from
+ another device.</li>
+ <li>Use the file system path provided by the
+ <code>set_active_group()</code>function or provide another way to erase all
+ user template data when the user is removed. It is strongly recommended that
+ biometric template files be stored as encrypted in the path provided. If this
+ is infeasible due to the storage requirements of the secure isolated
+ environment, add hooks to ensure removal of the data when the user is removed
+ or the device is wiped.</li>
+</ol>
+
+<h2 id="customization">Customization</h2>
+<p>
+If your device supports multiple biometrics, you can specify a default. However,
+you must allow users to change their preferred biometric in Settings.
</p>
+<h2 id="validation">Validation</h2>
<p>
-SAR, however, works for every biometric modality.
-</p>
-
-<h3 id="example-attacks">Example attacks</h3>
-
-<p>
-The table below lists examples of imposter and spoof attacks for four
-modalities.
-</p>
-
-<table>
- <tr>
- <th>Modality</th>
- <th>Imposter Attack</th>
- <th>Spoof Attack</th>
- </tr>
- <tr>
- <td>Fingerprint
- </td>
- <td>N/A
- </td>
- <td>Fingerprint + Fingerprint mold
- </td>
- </tr>
- <tr>
- <td>Face
- </td>
- <td>Trying to look like the user
- </td>
- <td>High-res photo, Latex (or other high quality) face masks
- </td>
- </tr>
- <tr>
- <td>Voice
- </td>
- <td>Trying to sound like the user
- </td>
- <td>Recording
- </td>
- </tr>
- <tr>
- <td>Iris
- </td>
- <td>N/A
- </td>
- <td>High-res photo + contact lens
- </td>
- </tr>
-</table>
-
-<p>
-<strong>Table 1. Example attacks</strong>
-</p>
-
-<p>
-See <a href="#test-methods">Test methodology</a> for advice and more details on
-methodologies to measure SAR and IAR for different biometrics.
-</p>
-
-<h3 id="strong-weak-unlocks">Strong vs. weak unlocks</h3>
-
-<p>
-The bar for an unlock to be considered strong is a combination of the three
-accept rates - FAR, IAR, and SAR. In cases where an imposter attack does not
-exist, we consider only the FAR and SAR.
-</p>
-
-<p>
-See the <a href="https://source.android.com/compatibility/android-cdd">Android
-Compatibility Definition Document</a> (CDD) for the measures to be taken for
-weak unlock modalities<strong>.</strong>
-</p>
-
-<h2 id="test-methods">Test methodology</h2>
-
-<p>
-Here we explain considerations and offer advice regarding test setups to measure
-spoof (SAR) and imposter acceptance rates (IAR) for biometric unlock modalities.
-See <a href="#metrics">Metrics</a> for more information on what these metrics mean
-and why they're useful.
-</p>
-
-<h3 id="common-considerations">Common considerations</h3>
-
-<p>
-While each modality requires a different test setup, there are a few common
-aspects that apply to all of them.
-</p>
-
-<h4 id="test-hw">Test the actual hardware</h4>
-
-<p>
-Collected SAR/IAR metrics can be inaccurate when biometric models are tested
-under idealized conditions and on different hardware than it would actually
-appear on in a mobile device. For example, voice unlock models that are
-calibrated in an anechoic chamber using a multi-microphone setup behave very
-differently when used on a single microphone device in a noisy environment. In
-order to capture accurate metrics, tests should be carried out on an actual
-device with the hardware installed, and failing that with the hardware as it
-would appear on the device.
-</p>
-
-<h4 id="known-attacks">Use known attacks</h4>
-
-<p>
-Most biometric modalities in use today have been successfully spoofed, and
-public documentation of the attack methodology exists. Below we provide a brief
-high-level overview of test setups for modalities with known attacks. We
-recommend using the setup outlined here wherever possible.
-</p>
-
-<h4 id="anticipate-attacks">Anticipate new attacks</h4>
-
-<p>
-For modalities where significant new improvements have been made, the test setup
-document may not contain a suitable setup, and no known public attack may exist.
-Existing modalities may also need their test setup tuned in the wake of a newly
-discovered attack. In both cases you will need to come up with a reasonable test
-setup. Please use the <a
-href="https://issuetracker.google.com/issues/new?component=191476">Site
-Feedback</a> link at the bottom of this page to let us know if you have set up a
-reasonable mechanism that can be added.
-</p>
-
-<h3 id="setups-for-different-modalities">Setups for different modalities</h3>
-
-<h4 id="fingerprint">Fingerprint</h4>
-
-<table>
- <tr>
- <td><strong>IAR</strong>
- </td>
- <td>Not needed.
- </td>
- </tr>
- <tr>
- <td><strong>SAR</strong>
- </td>
- <td>
- <ul>
-<li>Create fake fingerprints using a mold of the target fingerprint.</li>
-<li>Measurement accuracy is sensitive to the quality of the fingerprint mold.
-Dental silicon is a good choice.</li>
-<li>The test setup should measure how often a fake fingerprint created with the
-mold is able to unlock the device.</li>
- </ul>
- </td>
- </tr>
-</table>
-
-<h4 id="face-and-iris">Face and Iris</h4>
-
-<table>
- <tr>
- <td><strong>IAR</strong>
- </td>
- <td>Lower bound will be captured by SAR so separately measuring this is not
-needed.
- </td>
- </tr>
- <tr>
- <td><strong>SAR</strong>
- </td>
- <td>
- <ul>
-<li>Test with photos of the target's face. For iris, the face will need to be
-zoomed in to mimic the distance a user would normally use the feature.</li>
-<li>Photos should be high resolution, otherwise results are misleading.</li>
-<li>Photos should not be presented in a way that reveals they are images. For
-example:
- <ul>
- <li>image borders should not be included</li>
- <li>if the photo is on a phone, the phone screen/bezels should not be visible</li>
- <li>if someone is holding the photo, their hands should not be seen</li>
- </ul>
- </li>
-<li>For straight angles, the photo should fill the sensor so nothing else
-outside can be seen.</li>
-<li>Face and iris models are typically more permissive when the sample
-(face/iris/photo) is at an acute angle w.r.t to the camera (to mimic the use
-case of a user holding the phone straight in front of them and pointing up at
-their face). Testing at this angle will help determine if your model is
-susceptible to spoofing.</li>
-<li>The test setup should measure how often an image of the face or iris is able
-to unlock the device.</li>
-</ul>
-</li>
-</ul>
- </td>
- </tr>
-</table>
-
-<h4 id="voice">Voice</h4>
-
-<table>
- <tr>
- <td><strong>IAR</strong>
- </td>
- <td>
- <ul>
-<li>Test using a setup where participants hear a positive sample and then try to
-mimic it.</li>
-<li>Test the model with participants across genders and with different accents
-to ensure coverage of edge cases where some intonations/accents have a higher
-FAR.</li>
-</ul>
- </td>
- </tr>
- <tr>
- <td><strong>SAR</strong>
- </td>
- <td>
- <ul>
-<li>Test with recordings of the target's voice.</li>
-<li>The recording needs to be of a reasonably high quality, or the results will
-be misleading.</li>
-</ul>
- </td>
- </tr>
-</table>
+Android 9 updated the <code>FingerprintManager</code> CTS verifier tests to
+test <code>BiometricPrompt</code> via <code><a
+href="https://android.googlesource.com/platform/cts/+/master/apps/CtsVerifier/src/com/android/cts/verifier/security/BiometricPromptBoundKeysTest.java">BiometricPromptBoundKeysTest</a></code>.
+For other biometrics, there are no formal CTS or CTS verifier tests yet.</p>
</body>
</html>
+
diff --git a/en/security/biometric/measure.html b/en/security/biometric/measure.html
new file mode 100644
index 0000000..399548b
--- /dev/null
+++ b/en/security/biometric/measure.html
@@ -0,0 +1,286 @@
+<html devsite>
+ <head>
+ <title>Measuring Biometric Unlock Security</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>
+Today, biometric-based unlock modalities are evaluated almost solely on the
+basis of <em>False Accept Rate (FAR)</em>, a metric that defines how often a
+model mistakenly accepts a randomly chosen incorrect input. While this is a
+useful measure, it does not provide sufficient information to evaluate how well
+the model stands up to targeted attacks.
+</p>
+
+<h2 id="metrics">Metrics</h2>
+
+<p>
+Android 8.1 introduces two new metrics associated with biometric unlocks that
+are intended to help device manufacturers evaluate their security more
+accurately:
+</p>
+
+<ul>
+<li><em>Imposter Accept Rate (IAR)</em>: The chance that a biometric model
+accepts input that is meant to mimic a known good sample. For example, in the
+<a href="https://support.google.com/nexus/answer/6093922" class="external">Smart
+Lock</a> trusted voice (voice unlock) mechanism, this would measure how often
+someone trying to mimic a user's voice (using similar tone, accent, etc) can
+unlock their device. We call such attacks <em>Imposter Attacks</em>.</li>
+<li><em>Spoof Accept Rate (SAR)<strong>:</strong></em> The chance that a
+biometric model accepts a previously recorded, known good sample. For example,
+with voice unlock this would measure the chances of unlocking a user's phone
+using a recorded sample of them saying: "Ok, Google" We call such attacks
+<em>Spoof Attacks<strong>.</strong></em></li>
+</ul>
+
+<p>
+Of these, IAR measurements are not universally useful for all biometric
+modalities. Consider fingerprint for example. An attacker could create a mold of
+a user's fingerprint and attempt to use that to bypass the fingerprint sensor,
+which would count as a spoof attack. However, there isn't a way to mimic a
+fingerprint that would be accepted as the user's - and so there's not a clear
+notion of an imposter attack against fingerprint sensors.
+</p>
+
+<p>
+SAR, however, works for every biometric modality.
+</p>
+
+<h3 id="example-attacks">Example attacks</h3>
+
+<p>
+The table below lists examples of imposter and spoof attacks for four
+modalities.
+</p>
+
+<table>
+ <tr>
+ <th>Modality</th>
+ <th>Imposter Attack</th>
+ <th>Spoof Attack</th>
+ </tr>
+ <tr>
+ <td>Fingerprint
+ </td>
+ <td>N/A
+ </td>
+ <td>Fingerprint + Fingerprint mold
+ </td>
+ </tr>
+ <tr>
+ <td>Face
+ </td>
+ <td>Trying to look like the user
+ </td>
+ <td>High-res photo, Latex (or other high quality) face masks
+ </td>
+ </tr>
+ <tr>
+ <td>Voice
+ </td>
+ <td>Trying to sound like the user
+ </td>
+ <td>Recording
+ </td>
+ </tr>
+ <tr>
+ <td>Iris
+ </td>
+ <td>N/A
+ </td>
+ <td>High-res photo + contact lens
+ </td>
+ </tr>
+</table>
+
+<p>
+<strong>Table 1. Example attacks</strong>
+</p>
+
+<p>
+See <a href="#test-methods">Test methodology</a> for advice and more details on
+methodologies to measure SAR and IAR for different biometrics.
+</p>
+
+<h3 id="strong-weak-unlocks">Strong vs. weak unlocks</h3>
+
+<p>
+The bar for an unlock to be considered strong is a combination of the three
+accept rates - FAR, IAR, and SAR. In cases where an imposter attack does not
+exist, we consider only the FAR and SAR.
+</p>
+
+<p>
+See the <a href="/compatibility/android-cdd">Android Compatibility Definition
+Document</a> (CDD) for the measures to be taken for weak unlock modalities.
+</p>
+
+<h2 id="test-methods">Test methodology</h2>
+
+<p>
+Here we explain considerations and offer advice regarding test setups to measure
+spoof (SAR) and imposter acceptance rates (IAR) for biometric unlock modalities.
+See <a href="#metrics">Metrics</a> for more information on what these metrics mean
+and why they're useful.
+</p>
+
+<h3 id="common-considerations">Common considerations</h3>
+
+<p>
+While each modality requires a different test setup, there are a few common
+aspects that apply to all of them.
+</p>
+
+<h4 id="test-hw">Test the actual hardware</h4>
+
+<p>
+Collected SAR/IAR metrics can be inaccurate when biometric models are tested
+under idealized conditions and on different hardware than it would actually
+appear on in a mobile device. For example, voice unlock models that are
+calibrated in an anechoic chamber using a multi-microphone setup behave very
+differently when used on a single microphone device in a noisy environment. In
+order to capture accurate metrics, tests should be carried out on an actual
+device with the hardware installed, and failing that with the hardware as it
+would appear on the device.
+</p>
+
+<h4 id="known-attacks">Use known attacks</h4>
+
+<p>
+Most biometric modalities in use today have been successfully spoofed, and
+public documentation of the attack methodology exists. Below we provide a brief
+high-level overview of test setups for modalities with known attacks. We
+recommend using the setup outlined here wherever possible.
+</p>
+
+<h4 id="anticipate-attacks">Anticipate new attacks</h4>
+
+<p>
+For modalities where significant new improvements have been made, the test setup
+document may not contain a suitable setup, and no known public attack may exist.
+Existing modalities may also need their test setup tuned in the wake of a newly
+discovered attack. In both cases you will need to come up with a reasonable test
+setup. Please use the <a
+href="https://issuetracker.google.com/issues/new?component=191476"
+class="external">Site Feedback</a> link at the bottom of this page to let us
+know if you have set up a reasonable mechanism that can be added.
+</p>
+
+<h3 id="setups-for-different-modalities">Setups for different modalities</h3>
+
+<h4 id="fingerprint">Fingerprint</h4>
+
+<table>
+ <tr>
+ <td><strong>IAR</strong>
+ </td>
+ <td>Not needed.
+ </td>
+ </tr>
+ <tr>
+ <td><strong>SAR</strong>
+ </td>
+ <td>
+ <ul>
+<li>Create fake fingerprints using a mold of the target fingerprint.</li>
+<li>Measurement accuracy is sensitive to the quality of the fingerprint mold.
+Dental silicon is a good choice.</li>
+<li>The test setup should measure how often a fake fingerprint created with the
+mold is able to unlock the device.</li>
+ </ul>
+ </td>
+ </tr>
+</table>
+
+<h4 id="face-and-iris">Face and Iris</h4>
+
+<table>
+ <tr>
+ <td><strong>IAR</strong>
+ </td>
+ <td>Lower bound will be captured by SAR so separately measuring this is not
+needed.
+ </td>
+ </tr>
+ <tr>
+ <td><strong>SAR</strong>
+ </td>
+ <td>
+ <ul>
+<li>Test with photos of the target's face. For iris, the face will need to be
+zoomed in to mimic the distance a user would normally use the feature.</li>
+<li>Photos should be high resolution, otherwise results are misleading.</li>
+<li>Photos should not be presented in a way that reveals they are images. For
+example:
+ <ul>
+ <li>image borders should not be included</li>
+ <li>if the photo is on a phone, the phone screen/bezels should not be visible</li>
+ <li>if someone is holding the photo, their hands should not be seen</li>
+ </ul>
+ </li>
+<li>For straight angles, the photo should fill the sensor so nothing else
+outside can be seen.</li>
+<li>Face and iris models are typically more permissive when the sample
+(face/iris/photo) is at an acute angle w.r.t to the camera (to mimic the use
+case of a user holding the phone straight in front of them and pointing up at
+their face). Testing at this angle will help determine if your model is
+susceptible to spoofing.</li>
+<li>The test setup should measure how often an image of the face or iris is able
+to unlock the device.</li>
+</ul>
+</li>
+</ul>
+ </td>
+ </tr>
+</table>
+
+<h4 id="voice">Voice</h4>
+
+<table>
+ <tr>
+ <td><strong>IAR</strong>
+ </td>
+ <td>
+ <ul>
+<li>Test using a setup where participants hear a positive sample and then try to
+mimic it.</li>
+<li>Test the model with participants across genders and with different accents
+to ensure coverage of edge cases where some intonations/accents have a higher
+FAR.</li>
+</ul>
+ </td>
+ </tr>
+ <tr>
+ <td><strong>SAR</strong>
+ </td>
+ <td>
+ <ul>
+<li>Test with recordings of the target's voice.</li>
+<li>The recording needs to be of a reasonably high quality, or the results will
+be misleading.</li>
+</ul>
+ </td>
+ </tr>
+</table>
+</body>
+</html>
diff --git a/en/security/bulletin/2018-08-01.html b/en/security/bulletin/2018-08-01.html
new file mode 100644
index 0000000..5cb95de
--- /dev/null
+++ b/en/security/bulletin/2018-08-01.html
@@ -0,0 +1,752 @@
+<html devsite>
+ <head>
+ <title>Android Security Bulletin—August 2018</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ <body>
+ <!--
+ Copyright 2018 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
+
+ //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><em>Published August 6, 2018</em></p>
+
+<p>
+The Android Security Bulletin contains details of security vulnerabilities
+affecting Android devices. Security patch levels of 2018-08-05 or later address
+all of these issues. To learn how to check a device's security patch level, see
+<a href="https://support.google.com/pixelphone/answer/4457705"
+ class="external">Check and update your Android version</a>.
+</p>
+<p>
+Android partners are notified of all issues at least a month before
+publication. Source code patches for these issues have been released to the
+Android Open Source Project (AOSP) repository and linked from this bulletin.
+This bulletin also includes links to patches outside of AOSP.
+</p>
+<p>
+The most severe of these issues is a critical vulnerability that could enable
+a remote attacker using a specially crafted file to execute arbitrary code
+within the context of a privileged process. The
+<a href="/security/overview/updates-resources.html#severity">severity
+assessment</a> is based on the effect that exploiting the vulnerability would
+possibly have on an affected device, assuming the platform and service
+mitigations are turned off for development purposes or if successfully bypassed.
+</p>
+<p>
+We have had no reports of active customer exploitation or abuse of these newly
+reported issues. Refer to the
+<a href="#mitigations">Android and Google Play Protect mitigations</a>
+section for details on the
+<a href="/security/enhancements/index.html">Android security platform protections</a>
+and Google Play Protect, which improve the security of the Android platform.
+</p>
+<p class="note">
+<strong>Note:</strong> Information on the latest over-the-air update (OTA) and
+firmware images for Google devices is available in the
+<a href="/security/bulletin/pixel/2018-08-01.html">August 2018
+Pixel / Nexus Security Bulletin</a>.
+</p>
+
+<h2 id="mitigations">Android and Google service mitigations</h2>
+<p>
+This is a summary of the mitigations provided by the
+<a href="/security/enhancements/index.html">Android security platform</a>
+and service protections such as
+<a href="https://www.android.com/play-protect">Google Play Protect</a>.
+These capabilities reduce the likelihood that security vulnerabilities
+could be successfully exploited on Android.
+</p>
+<ul>
+<li>Exploitation for many issues on Android is made more difficult by
+enhancements in newer versions of the Android platform. We encourage all users
+to update to the latest version of Android where possible.</li>
+<li>The Android security team actively monitors for abuse through
+<a href="https://www.android.com/play-protect" class="external">Google Play
+Protect</a> and warns users about
+<a href="/security/reports/Google_Android_Security_PHA_classifications.pdf">Potentially
+Harmful Applications</a>. Google Play Protect is enabled by default on devices
+with <a href="http://www.android.com/gms" class="external">Google Mobile
+Services</a>, and is especially important for users who install apps from
+outside of Google Play.</li>
+</ul>
+<h2 id="2018-08-01-details">2018-08-01 security patch level vulnerability
+details</h2>
+<p>
+In the sections below, we provide details for each of the security
+vulnerabilities that apply to the 2018-08-01 patch level. Vulnerabilities are
+grouped under the component that they affect. There is a description of the
+issue and a table with the CVE, associated references,
+<a href="#type">type of vulnerability</a>,
+<a href="/security/overview/updates-resources.html#severity">severity</a>,
+and updated AOSP versions (where applicable). When available, we link the public
+change that addressed the issue to the bug ID, like the AOSP change list. When
+multiple changes relate to a single bug, additional references are linked to
+numbers following the bug ID.
+</p>
+
+<h3 id="framework">Framework</h3>
+<p>The most severe vulnerability in this section could enable a local malicious
+application to bypass user interaction requirements in order to gain access to
+additional permissions.</p>
+
+<table>
+ <col width="21%">
+ <col width="21%">
+ <col width="14%">
+ <col width="14%">
+ <col width="30%">
+
+ <tr>
+ <th>CVE</th>
+ <th>References</th>
+ <th>Type</th>
+ <th>Severity</th>
+ <th>Updated AOSP versions</th>
+ </tr>
+ <tr>
+ <td>CVE-2018-9445</td>
+ <td>
+ <a href="https://android.googlesource.com/platform/external/e2fsprogs/+/9a2d95e4ed9ec5ab76998654b1c2fba9cc139e50">A-80436257</a>
+ [<a href="https://android.googlesource.com/platform/system/vold/+/940a1ff70cfc5f2e4de83da9ad84cd9734faadf6">2</a>]
+ </td>
+ <td>EoP</td>
+ <td>High</td>
+ <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-9438</td>
+ <td>
+<a href="https://android.googlesource.com/platform/packages/providers/DownloadProvider/+/b552ebf70913cc79085bcc4212235ea45e036d3b">A-78644887</a>
+[<a href="https://android.googlesource.com/platform/frameworks/base/+/e3854655e75d97552140d77cca5d20c121a17ef9">2</a>]
+[<a href="https://android.googlesource.com/platform/frameworks/opt/telephony/+/d1ce32b059bed774b41f11413c1d83a1bc412964">3</a>]
+[<a href="https://android.googlesource.com/platform/frameworks/base/+/97e1cd61d3040dd366ac9e25cdb6f134c7490846">4</a>]
+</td>
+ <td>DoS</td>
+ <td>High</td>
+ <td>8.1</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-9458</td>
+ <td>
+<a href="https://android.googlesource.com/platform/frameworks/base/+/c4f66f4f607654611b2227827123e016c57a5729">A-71786287</a>
+</td>
+ <td>EoP</td>
+ <td>High</td>
+ <td>8.0, 8.1</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-9451</td>
+ <td>
+<a href="https://android.googlesource.com/platform/frameworks/base/+/a409aa1214d6483efe129a4966f09aa4fdc097ad">A-79488511</a>
+[<a href="https://android.googlesource.com/platform/frameworks/base/+/1de25074adb5d9ed572d6a85e77d3df5ac3a7e9e">2</a>]
+</td>
+ <td>ID</td>
+ <td>High</td>
+ <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
+ </tr>
+</table>
+
+
+<h3 id="media-framework">Media framework</h3>
+<p>The most severe vulnerability in this section could enable a remote attacker
+using a specially crafted file to execute arbitrary code within the context of
+a privileged process.</p>
+
+<table>
+ <col width="21%">
+ <col width="21%">
+ <col width="14%">
+ <col width="14%">
+ <col width="30%">
+
+ <tr>
+ <th>CVE</th>
+ <th>References</th>
+ <th>Type</th>
+ <th>Severity</th>
+ <th>Updated AOSP versions</th>
+ </tr>
+ <tr>
+ <td>CVE-2018-9427</td>
+ <td>
+<a href="https://android.googlesource.com/platform/frameworks/av/+/08d392085c095e227c029f64644bc08ef5a544de">A-77486542</a>
+[<a href="https://android.googlesource.com/platform/frameworks/av/+/c9909e5a980f941a5b72477755e09fb4dc57c478">2</a>]
+</td>
+ <td>RCE</td>
+ <td>Critical</td>
+ <td>8.0, 8.1</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-9444</td>
+ <td>A-63521984<a href="#asterisk">*</a></td>
+ <td>DoS</td>
+ <td>High</td>
+ <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-9437</td>
+ <td>
+<a href="https://android.googlesource.com/platform/frameworks/av/+/017ff33fd419c50734f775d5054e2cbea719700b">A-78656554</a>
+ </td>
+ <td>DoS</td>
+ <td>High</td>
+ <td>6.0, 6.0.1</td>
+ </tr>
+</table>
+
+
+<h3 id="system">System</h3>
+<p>The most severe vulnerability in this section could enable a remote attacker
+using a specially crafted file to execute arbitrary code within the context of
+a privileged process.</p>
+
+<table>
+ <col width="21%">
+ <col width="21%">
+ <col width="14%">
+ <col width="14%">
+ <col width="30%">
+ <tr>
+ <th>CVE</th>
+ <th>References</th>
+ <th>Type</th>
+ <th>Severity</th>
+ <th>Updated AOSP versions</th>
+ </tr>
+ <tr>
+ <td>CVE-2018-9446</td>
+ <td>
+ <a href="https://android.googlesource.com/platform/system/bt/+/49acada519d088d8edf37e48640c76ea5c70e010">A-80145946</a>
+ </td>
+ <td>RCE</td>
+ <td>Critical</td>
+ <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-9450</td>
+ <td>
+<a href="https://android.googlesource.com/platform/system/bt/+/bc259b4926a6f9b33b9ee2c917cd83a55f360cbf">A-79541338</a>
+ </td>
+ <td>RCE</td>
+ <td>Critical</td>
+ <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-9459</td>
+ <td>
+<a href="https://android.googlesource.com/platform/packages/apps/UnifiedEmail/+/76c5261a03c8402e893999196651afc5791ca0fd">A-66230183</a>
+ </td>
+ <td>EoP</td>
+ <td>High</td>
+ <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-9455</td>
+ <td>
+<a href="https://android.googlesource.com/platform/system/bt/+/d56c7ec9e2ecfa8a8ceeb82f37187e5ea21f2101">A-78136677</a>
+ </td>
+ <td>DoS</td>
+ <td>High</td>
+ <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-9436</td>
+ <td>
+<a href="https://android.googlesource.com/platform/system/bt/+/289a49814aef7f0f0bb98aac8246080abdfeac01">A-79164722</a>
+ </td>
+ <td>ID</td>
+ <td>High</td>
+ <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-9454</td>
+ <td>
+<a href="https://android.googlesource.com/platform/system/bt/+/289a49814aef7f0f0bb98aac8246080abdfeac01">A-78286118</a>
+ </td>
+ <td>ID</td>
+ <td>High</td>
+ <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-9448</td>
+ <td>
+<a href="https://android.googlesource.com/platform/system/bt/+/13294c70a66347c9e5d05b9f92f8ceb6fe38d7f6">A-79944113</a>
+[<a href="https://android.googlesource.com/platform/system/bt/+/f1f1c3e00f8d1baad0215b057e6d894517eeaddb">2</a>]
+ </td>
+ <td>ID</td>
+ <td>High</td>
+ <td>8.0, 8.1</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-9453</td>
+ <td>
+<a href="https://android.googlesource.com/platform/system/bt/+/cb6a56b1d8cdab7c495ea8f53dcbdb3cfc9477d2">A-78288378</a>
+ </td>
+ <td>ID</td>
+ <td>High</td>
+ <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
+ </tr>
+</table>
+
+
+<h2 id="2018-08-05-details">2018-08-05 security patch level vulnerability details</h2>
+<p>
+In the sections below, we provide details for each of the security
+vulnerabilities that apply to the 2018-08-05 patch level. Vulnerabilities are
+grouped under the component that they affect and include details such as the
+CVE, associated references, <a href="#type">type of vulnerability</a>,
+<a href="/security/overview/updates-resources.html#severity">severity</a>,
+component (where applicable), and updated AOSP versions (where applicable). When
+available, we link the public change that addressed the issue to the bug ID,
+like the AOSP change list. When multiple changes relate to a single bug,
+additional references are linked to numbers following the bug ID.
+</p>
+
+<h3 id="kernel-components">Kernel components</h3>
+<p>The most severe vulnerability in this section could enable a local malicious
+application to execute arbitrary code within the context of a privileged
+process.</p>
+
+<table>
+ <col width="21%">
+ <col width="21%">
+ <col width="14%">
+ <col width="14%">
+ <col width="30%">
+ <tr>
+ <th>CVE</th>
+ <th>References</th>
+ <th>Type</th>
+ <th>Severity</th>
+ <th>Component</th>
+ </tr>
+ <tr>
+ <td>CVE-2017-18249</td>
+ <td>A-78283212<br />
+ <a
+href="http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=30a61ddf8117c26ac5b295e1233eaa9629a94ca3">
+Upstream kernel</a></td>
+ <td>EoP</td>
+ <td>High</td>
+ <td>F2FS</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-9465</td>
+ <td>A-69164715<br />
+ <a href="https://patchwork.kernel.org/patch/10058587/">Upstream
+kernel</a></td>
+ <td>EoP</td>
+ <td>High</td>
+ <td>binder</td>
+ </tr>
+</table>
+
+
+<h3 id="qualcomm-components">Qualcomm components</h3>
+<p>The most severe vulnerability in this section could lead to remote
+information disclosure with no additional execution privileges needed.</p>
+
+<table>
+ <col width="21%">
+ <col width="21%">
+ <col width="14%">
+ <col width="14%">
+ <col width="30%">
+ <tr>
+ <th>CVE</th>
+ <th>References</th>
+ <th>Type</th>
+ <th>Severity</th>
+ <th>Component</th>
+ </tr>
+ <tr>
+ <td>CVE-2018-5383</td>
+ <td>A-79421580<a href="#asterisk">*</a><br />
+ QC-CR#2209635</td>
+ <td>ID</td>
+ <td>High</td>
+ <td>Bluetooth</td>
+ </tr>
+ <tr>
+ <td>CVE-2017-13077</td>
+ <td>A-78284758<br />
+ <a
+href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-2.0/commit/?id=edb507885fc47cf3cdf061bfba1dc77451a6a332">
+QC-CR#2133033</a></td>
+ <td>ID</td>
+ <td>High</td>
+ <td>WLAN</td>
+ </tr>
+ <tr>
+ <td>CVE-2017-18281</td>
+ <td>A-78242172<br />
+ <a
+href="https://source.codeaurora.org/quic/la/kernel/msm-3.18/commit/?id=69f0a80b8cc1333647397d7bc4f267bd3fe22be9">
+QC-CR#856388</a></td>
+ <td>ID</td>
+ <td>High</td>
+ <td>Video</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-11260</td>
+ <td>A-72997254<br />
+ <a
+href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=9fd239116d9cb19a18b3892b8a1f428636ca1453">
+QC-CR#2204872</a></td>
+ <td>EoP</td>
+ <td>High</td>
+ <td>WLAN</td>
+ </tr>
+</table>
+
+
+<h3 id="qualcomm-closed-source-components">Qualcomm closed-source
+components</h3>
+<p>These vulnerabilities affect Qualcomm components and are described in
+further detail in the appropriate Qualcomm AMSS security bulletin or security
+alert. The severity assessment of these issues is provided directly by
+Qualcomm.</p>
+
+<table>
+ <col width="21%">
+ <col width="21%">
+ <col width="14%">
+ <col width="14%">
+ <col width="30%">
+ <tr>
+ <th>CVE</th>
+ <th>References</th>
+ <th>Type</th>
+ <th>Severity</th>
+ <th>Component</th>
+ </tr>
+ <tr>
+ <td>CVE-2017-18296</td>
+ <td>A-78240731<a href="#asterisk">*</a></td>
+ <td>N/A</td>
+ <td>Critical</td>
+ <td>Closed-source component</td>
+ </tr>
+ <tr>
+ <td>CVE-2017-18305</td>
+ <td>A-78239838<a href="#asterisk">*</a></td>
+ <td>N/A</td>
+ <td>Critical</td>
+ <td>Closed-source component</td>
+ </tr>
+ <tr>
+ <td>CVE-2017-18310</td>
+ <td>A-62211308<a href="#asterisk">*</a></td>
+ <td>N/A</td>
+ <td>Critical</td>
+ <td>Closed-source component</td>
+ </tr>
+ <tr>
+ <td>CVE-2017-18295</td>
+ <td>A-78240386<a href="#asterisk">*</a></td>
+ <td>N/A</td>
+ <td>High</td>
+ <td>Closed-source component</td>
+ </tr>
+ <tr>
+ <td>CVE-2017-18283</td>
+ <td>A-78240411<a href="#asterisk">*</a></td>
+ <td>N/A</td>
+ <td>High</td>
+ <td>Closed-source component</td>
+ </tr>
+ <tr>
+ <td>CVE-2017-18294</td>
+ <td>A-78240247<a href="#asterisk">*</a></td>
+ <td>N/A</td>
+ <td>High</td>
+ <td>Closed-source component</td>
+ </tr>
+ <tr>
+ <td>CVE-2017-18293</td>
+ <td>A-78240316<a href="#asterisk">*</a></td>
+ <td>N/A</td>
+ <td>High</td>
+ <td>Closed-source component</td>
+ </tr>
+ <tr>
+ <td>CVE-2017-18292</td>
+ <td>A-78241027<a href="#asterisk">*</a></td>
+ <td>N/A</td>
+ <td>High</td>
+ <td>Closed-source component</td>
+ </tr>
+ <tr>
+ <td>CVE-2017-18298</td>
+ <td>A-78239976<a href="#asterisk">*</a></td>
+ <td>N/A</td>
+ <td>High</td>
+ <td>Closed-source component</td>
+ </tr>
+ <tr>
+ <td>CVE-2017-18299</td>
+ <td>A-78240418<a href="#asterisk">*</a></td>
+ <td>N/A</td>
+ <td>High</td>
+ <td>Closed-source component</td>
+ </tr>
+ <tr>
+ <td>CVE-2017-18304</td>
+ <td>A-78239975<a href="#asterisk">*</a></td>
+ <td>N/A</td>
+ <td>High</td>
+ <td>Closed-source component</td>
+ </tr>
+ <tr>
+ <td>CVE-2017-18303</td>
+ <td>A-78240396<a href="#asterisk">*</a></td>
+ <td>N/A</td>
+ <td>High</td>
+ <td>Closed-source component</td>
+ </tr>
+ <tr>
+ <td>CVE-2017-18301</td>
+ <td>A-78238455<a href="#asterisk">*</a></td>
+ <td>N/A</td>
+ <td>High</td>
+ <td>Closed-source component</td>
+ </tr>
+ <tr>
+ <td>CVE-2017-18302</td>
+ <td>A-78239233<a href="#asterisk">*</a></td>
+ <td>N/A</td>
+ <td>High</td>
+ <td>Closed-source component</td>
+ </tr>
+ <tr>
+ <td>CVE-2017-18300</td>
+ <td>A-78239508<a href="#asterisk">*</a></td>
+ <td>N/A</td>
+ <td>High</td>
+ <td>Closed-source component</td>
+ </tr>
+ <tr>
+ <td>CVE-2017-18297</td>
+ <td>A-78240275<a href="#asterisk">*</a></td>
+ <td>N/A</td>
+ <td>High</td>
+ <td>Closed-source component</td>
+ </tr>
+ <tr>
+ <td>CVE-2017-18280</td>
+ <td>A-78285512<a href="#asterisk">*</a></td>
+ <td>N/A</td>
+ <td>High</td>
+ <td>Closed-source component</td>
+ </tr>
+ <tr>
+ <td>CVE-2017-18282</td>
+ <td>A-78241591<a href="#asterisk">*</a></td>
+ <td>N/A</td>
+ <td>High</td>
+ <td>Closed-source component</td>
+ </tr>
+ <tr>
+ <td>CVE-2017-18309</td>
+ <td>A-73539064<a href="#asterisk">*</a></td>
+ <td>N/A</td>
+ <td>High</td>
+ <td>Closed-source component</td>
+ </tr>
+ <tr>
+ <td>CVE-2017-18308</td>
+ <td>A-73539310<a href="#asterisk">*</a></td>
+ <td>N/A</td>
+ <td>High</td>
+ <td>Closed-source component</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-11305</td>
+ <td>A-72951032<a href="#asterisk">*</a></td>
+ <td>N/A</td>
+ <td>High</td>
+ <td>Closed-source component</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-11258</td>
+ <td>A-72951054<a href="#asterisk">*</a></td>
+ <td>N/A</td>
+ <td>High</td>
+ <td>Closed-source component</td>
+ </tr>
+</table>
+
+
+
+<h2 id="common-questions-and-answers">Common questions and answers</h2>
+<p>This section answers common questions that may occur after reading this
+bulletin.</p>
+<p><strong>1. How do I determine if my device is updated to address these
+issues?</strong></p>
+<p>To learn how to check a device's security patch level, see
+<a href="https://support.google.com/pixelphone/answer/4457705#pixel_phones&nexus_devices"
+ class="external">Check and update your Android version</a>.</p>
+<ul>
+<li>Security patch levels of 2018-08-01 or later address all issues associated
+with the 2018-08-01 security patch level.</li>
+<li>Security patch levels of 2018-08-05 or later address all issues associated
+with the 2018-08-05 security patch level and all previous patch levels.</li>
+</ul>
+<p>Device manufacturers that include these updates should set the patch string
+level to:</p>
+<ul>
+ <li>[ro.build.version.security_patch]:[2018-08-01]</li>
+ <li>[ro.build.version.security_patch]:[2018-08-05]</li>
+</ul>
+<p><strong>2. Why does this bulletin have two security patch levels?</strong></p>
+<p>
+This bulletin has two security patch levels so that Android partners have the
+flexibility to fix a subset of vulnerabilities that are similar across all
+Android devices more quickly. Android partners are encouraged to fix all issues
+in this bulletin and use the latest security patch level.
+</p>
+<ul>
+<li>Devices that use the 2018-08-01 security patch level must include all
+issues associated with that security patch level, as well as fixes for all
+issues reported in previous security bulletins.</li>
+<li>Devices that use the security patch level of 2018-08-05 or newer must
+include all applicable patches in this (and previous) security
+bulletins.</li>
+</ul>
+<p>
+Partners are encouraged to bundle the fixes for all issues they are addressing
+in a single update.
+</p>
+<p id="type">
+<strong>3. What do the entries in the <em>Type</em> column mean?</strong>
+</p>
+<p>
+Entries in the <em>Type</em> column of the vulnerability details table
+reference the classification of the security vulnerability.
+</p>
+<table>
+ <col width="25%">
+ <col width="75%">
+ <tr>
+ <th>Abbreviation</th>
+ <th>Definition</th>
+ </tr>
+ <tr>
+ <td>RCE</td>
+ <td>Remote code execution</td>
+ </tr>
+ <tr>
+ <td>EoP</td>
+ <td>Elevation of privilege</td>
+ </tr>
+ <tr>
+ <td>ID</td>
+ <td>Information disclosure</td>
+ </tr>
+ <tr>
+ <td>DoS</td>
+ <td>Denial of service</td>
+ </tr>
+ <tr>
+ <td>N/A</td>
+ <td>Classification not available</td>
+ </tr>
+</table>
+<p>
+<strong>4. What do the entries in the <em>References</em> column mean?</strong>
+</p>
+<p>
+Entries under the <em>References</em> column of the vulnerability details table
+may contain a prefix identifying the organization to which the reference value
+belongs.
+</p>
+<table>
+ <col width="25%">
+ <col width="75%">
+ <tr>
+ <th>Prefix</th>
+ <th>Reference</th>
+ </tr>
+ <tr>
+ <td>A-</td>
+ <td>Android bug ID</td>
+ </tr>
+ <tr>
+ <td>QC-</td>
+ <td>Qualcomm reference number</td>
+ </tr>
+ <tr>
+ <td>M-</td>
+ <td>MediaTek reference number</td>
+ </tr>
+ <tr>
+ <td>N-</td>
+ <td>NVIDIA reference number</td>
+ </tr>
+ <tr>
+ <td>B-</td>
+ <td>Broadcom reference number</td>
+ </tr>
+</table>
+<p id="asterisk">
+<strong>5. What does a * next to the Android bug ID in the <em>References</em>
+column mean?</strong>
+</p>
+<p>
+Issues that are not publicly available have a * next to the Android bug ID in
+the <em>References</em> column. The update for that issue is generally
+contained in the latest binary drivers for Pixel / Nexus devices
+available from the
+<a href="https://developers.google.com/android/drivers" class="external">Google
+Developer site</a>.
+</p>
+<p>
+<strong>6. Why are security vulnerabilities split between this bulletin and
+device/partner security bulletins, such as the Pixel / Nexus
+bulletin?</strong>
+</p>
+<p>
+Security vulnerabilities that are documented in this security bulletin are
+required in order to declare the latest security patch level on Android
+devices. Additional security vulnerabilities that are documented in the
+device / partner security bulletins are not required for
+declaring a security patch level. Android device and chipset manufacturers are
+encouraged to document the presence of other fixes on their devices through
+their own security websites, such as the
+<a href="https://security.samsungmobile.com/securityUpdate.smsb"
+ class="external">Samsung</a>,
+<a href="https://lgsecurity.lge.com/security_updates.html"
+ class="external">LGE</a>, or
+<a href="/security/bulletin/pixel/"
+ class="external">Pixel / Nexus</a> security bulletins.
+</p>
+
+<h2 id="versions">Versions</h2>
+<table>
+ <col width="25%">
+ <col width="25%">
+ <col width="50%">
+ <tr>
+ <th>Version</th>
+ <th>Date</th>
+ <th>Notes</th>
+ </tr>
+ <tr>
+ <td>1.0</td>
+ <td>August 6, 2018</td>
+ <td>Bulletin published.</td>
+ </tr>
+</table>
+</body></html>
diff --git a/en/security/bulletin/2018.html b/en/security/bulletin/2018.html
index 54044c7..6b1d0b7 100644
--- a/en/security/bulletin/2018.html
+++ b/en/security/bulletin/2018.html
@@ -37,6 +37,23 @@
<th>Security patch level</th>
</tr>
<tr>
+ <td><a href="/security/bulletin/2018-08-01.html">August 2018</a></td>
+ <td>Coming soon
+ <!--
+ <a href="/security/bulletin/2018-08-01.html">English</a> /
+ <a href="/security/bulletin/2018-08-01.html?hl=ja">日本語</a> /
+ <a href="/security/bulletin/2018-08-01.html?hl=ko">한국어</a> /
+ <a href="/security/bulletin/2018-08-01.html?hl=ru">ру́сский</a> /
+ <a href="/security/bulletin/2018-08-01.html?hl=zh-cn">中文 (中国)</a> /
+ <a href="/security/bulletin/2018-08-01.html?hl=zh-tw">中文 (台灣)</a>
+ -->
+ </td>
+ <td>August 6, 2018</td>
+ <td>2018-08-01<br>
+ 2018-08-05</td>
+ </tr>
+
+ <tr>
<td><a href="/security/bulletin/2018-07-01.html">July 2018</a></td>
<td>
<a href="/security/bulletin/2018-07-01.html">English</a> /
diff --git a/en/security/bulletin/index.html b/en/security/bulletin/index.html
index a2bae04..ba3b35e 100644
--- a/en/security/bulletin/index.html
+++ b/en/security/bulletin/index.html
@@ -69,6 +69,22 @@
<th>Security patch level</th>
</tr>
<tr>
+ <td><a href="/security/bulletin/2018-08-01.html">August 2018</a></td>
+ <td>Coming soon
+ <!--
+ <a href="/security/bulletin/2018-08-01.html">English</a> /
+ <a href="/security/bulletin/2018-08-01.html?hl=ja">日本語</a> /
+ <a href="/security/bulletin/2018-08-01.html?hl=ko">한국어</a> /
+ <a href="/security/bulletin/2018-08-01.html?hl=ru">ру́сский</a> /
+ <a href="/security/bulletin/2018-08-01.html?hl=zh-cn">中文 (中国)</a> /
+ <a href="/security/bulletin/2018-08-01.html?hl=zh-tw">中文 (台灣)</a>
+ -->
+ </td>
+ <td>August 6, 2018</td>
+ <td>2018-08-01<br>
+ 2018-08-05</td>
+ </tr>
+ <tr>
<td><a href="/security/bulletin/2018-07-01.html">July 2018</a></td>
<td>
<a href="/security/bulletin/2018-07-01.html">English</a> /
diff --git a/en/security/bulletin/pixel/2018-08-01.html b/en/security/bulletin/pixel/2018-08-01.html
new file mode 100644
index 0000000..af51a8b
--- /dev/null
+++ b/en/security/bulletin/pixel/2018-08-01.html
@@ -0,0 +1,571 @@
+<html devsite>
+ <head>
+ <title>Pixel / Nexus Security Bulletin—August 2018</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ <body>
+ <!--
+ Copyright 2018 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
+
+ //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><em>Published August 6, 2018</em></p>
+
+<p>
+The Pixel / Nexus Security Bulletin contains details of security
+vulnerabilities and functional improvements affecting <a
+href="https://support.google.com/pixelphone/answer/4457705#pixel_phones&nexus_devices"
+class="external">supported Google Pixel and Nexus devices</a> (Google devices).
+For Google devices, security patch levels of 2018-08-05 or later address all
+issues in this bulletin and all issues in the August 2018 Android Security
+Bulletin. To learn how to check a device's security patch level, see <a
+href="https://support.google.com/pixelphone/answer/4457705"
+class="external">Check & update your Android version</a>.
+</p>
+<p>
+All supported Google devices will receive an update to the 2018-08-05 patch
+level. We encourage all customers to accept these updates to their devices.
+</p>
+<p class="note">
+<strong>Note:</strong> The Google device firmware images are available on the
+<a href="https://developers.google.com/android/images" class="external">Google
+Developer site</a>.
+</p>
+
+<h2 id="announcements">Announcements</h2>
+<p>In addition to the security vulnerabilities described in the August 2018
+Android Security Bulletin, Google devices also contain patches for the
+security vulnerabilities described below. Partners were notified of these
+issues at least a month ago and may choose to incorporate them as part of their
+device updates.</p>
+
+<h2 id="security-patches">Security patches</h2>
+<p>
+Vulnerabilities are grouped under the component that they affect. There is a
+description of the issue and a table with the CVE, associated references,
+<a href="#type">type of vulnerability</a>,
+<a href="/security/overview/updates-resources.html#severity">severity</a>,
+and updated Android Open Source Project (AOSP) versions (where applicable).
+When available, we link the public change that addressed the issue to the bug
+ID, such as the AOSP change list. When multiple changes relate to a single bug,
+additional references are linked to numbers following the bug ID.
+</p>
+
+<h3 id="framework">Framework</h3>
+
+<table>
+ <col width="21%">
+ <col width="21%">
+ <col width="14%">
+ <col width="14%">
+ <col width="30%">
+ <tr>
+ <th>CVE</th>
+ <th>References</th>
+ <th>Type</th>
+ <th>Severity</th>
+ <th>Updated AOSP versions</th>
+ </tr>
+ <tr>
+ <td>CVE-2017-1000100</td>
+ <td>
+<a href="https://android.googlesource.com/platform/external/curl/+/1506c0316973bd95d7832891b1aa2258b52a793d">A-64610131</a>
+</td>
+ <td>ID</td>
+ <td>Moderate</td>
+ <td>7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
+ </tr>
+</table>
+
+
+<h3 id="system">System</h3>
+
+<table>
+ <col width="21%">
+ <col width="21%">
+ <col width="14%">
+ <col width="14%">
+ <col width="30%">
+ <tr>
+ <th>CVE</th>
+ <th>References</th>
+ <th>Type</th>
+ <th>Severity</th>
+ <th>Updated AOSP versions</th>
+ </tr>
+ <tr>
+ <td>CVE-2018-9435</td>
+ <td>
+<a href="https://android.googlesource.com/platform/system/bt/+/51b05b715024adff4fa59ab2e18c0b56c5d3af5e">A-79591688</a>
+</td>
+ <td>ID</td>
+ <td>Moderate</td>
+ <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-9461</td>
+ <td>
+<a href="https://android.googlesource.com/platform/packages/apps/Messaging/+/17a2579a0aa603a3a7d94e5dc64afeb96e430e8f">A-37629504</a>
+</td>
+ <td>ID</td>
+ <td>Moderate</td>
+ <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-9449</td>
+ <td>
+<a href="https://android.googlesource.com/platform/system/bt/+/27b90f4f6fe3811335e9bb4fac4656bc1df49204">A-79884292</a>
+</td>
+ <td>ID</td>
+ <td>Moderate</td>
+ <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-9457</td>
+ <td>
+<a href="https://android.googlesource.com/platform/packages/apps/Settings/+/a3e94449c8fe0a377b61747b6129fafc930da086">A-72872376</a>
+</td>
+ <td>ID</td>
+ <td>Moderate</td>
+ <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-9441</td>
+ <td>
+<a href="https://android.googlesource.com/platform/system/bt/+/c3c69bed0f76178c640dd8e726967b9cdea5dece">A-74075873</a>
+[<a href="https://android.googlesource.com/platform/system/bt/+/3a2799939b2da543ed3a62f29db658cb05f8ad3b">2</a>]
+</td>
+ <td>ID</td>
+ <td>Moderate</td>
+ <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
+ </tr>
+ <tr>
+ <td>CVE-2017-13322</td>
+ <td>
+<a href="https://android.googlesource.com/platform/packages/services/Telephony/+/c25745addd19b1549b7ec5bdc46d8bf1a1de37ed">A-67862398</a>
+</td>
+ <td>DoS</td>
+ <td>Moderate</td>
+ <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-9447</td>
+ <td>
+<a href="https://android.googlesource.com/platform/packages/services/Telephony/+/19c48992b79df89c730f3619eb69baf03d449e95">A-79995313</a>
+</td>
+ <td>DoS</td>
+ <td>Moderate</td>
+ <td>6.0, 6.0.1, 8.0, 8.1</td>
+ </tr>
+</table>
+
+
+<h3 id="kernel-components">Kernel components</h3>
+
+<table>
+ <col width="21%">
+ <col width="21%">
+ <col width="14%">
+ <col width="14%">
+ <col width="30%">
+ <tr>
+ <th>CVE</th>
+ <th>References</th>
+ <th>Type</th>
+ <th>Severity</th>
+ <th>Component</th>
+ </tr>
+ <tr>
+ <td>CVE-2018-9462</td>
+ <td>A-78364203<a href="#asterisk">*</a></td>
+ <td>EoP</td>
+ <td>Moderate</td>
+ <td>Touchscreen</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-9439</td>
+ <td>A-79377438<a href="#asterisk">*</a></td>
+ <td>EoP</td>
+ <td>Moderate</td>
+ <td>Network stack</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-9463</td>
+ <td>A-78362414<a href="#asterisk">*</a></td>
+ <td>EoP</td>
+ <td>Moderate</td>
+ <td>Touchscreen</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-1068</td>
+ <td>A-77902350<br />
+ <a
+href="https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=b71812168571fa55e44cdd0254471331b9c4c4c6">
+Upstream kernel</a></td>
+ <td>EoP</td>
+ <td>Moderate</td>
+ <td>Netfilter</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-9464</td>
+ <td>A-68993267<a href="#asterisk">*</a></td>
+ <td>EoP</td>
+ <td>Moderate</td>
+ <td>Taimen bootloader</td>
+ </tr>
+</table>
+
+
+<h3 id="qualcomm-components">Qualcomm components</h3>
+
+<table>
+ <col width="21%">
+ <col width="21%">
+ <col width="14%">
+ <col width="14%">
+ <col width="30%">
+ <tr>
+ <th>CVE</th>
+ <th>References</th>
+ <th>Type</th>
+ <th>Severity</th>
+ <th>Component</th>
+ </tr>
+ <tr>
+ <td>CVE-2018-11263</td>
+ <td>A-79422278<a href="#asterisk">*</a><br />
+ QC-CR#2209106</td>
+ <td>EoP</td>
+ <td>Moderate</td>
+ <td>WLAN</td>
+ </tr>
+ <tr>
+ <td>CVE-2017-8261</td>
+ <td>A-35139833<a href="#asterisk">*</a><br />
+ QC-CR#2013631</td>
+ <td>EoP</td>
+ <td>Moderate</td>
+ <td>Camera driver</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-5910</td>
+ <td>A-79422277<br />
+<a href="https://source.codeaurora.org/quic/la/kernel/msm-3.18/commit/?id=b67e04e3696f05411b7434c8b194895d273b00c5">
+QC-CR#2175499</a>
+[<a href="https://source.codeaurora.org/quic/la/kernel/msm-4.4/commit/?id=d9344c2f4b60cf5d4c747c11f3cb0b6f1558db78">2</a>]
+</td>
+ <td>EoP</td>
+ <td>Moderate</td>
+ <td>MDSS</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-5909</td>
+ <td>A-79421262<br />
+ <a
+href="https://source.codeaurora.org/quic/la/kernel/msm-4.4/commit/?id=2c1716c5afd660651724b6088f2e6301272f4926">
+QC-CR#2174716</a></td>
+ <td>EoP</td>
+ <td>Moderate</td>
+ <td>Rotator</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-5908</td>
+ <td>A-79422409<br />
+<a href="https://source.codeaurora.org/quic/la/kernel/msm-3.18/commit/?id=28e5918c60b832091c6b3618747258803cbd3302">
+QC-CR#2171758</a>
+[<a href="https://source.codeaurora.org/quic/la/kernel/msm-4.4/commit/?id=4689d03e5db548d263232c274bf307956207da27">2</a>]
+</td>
+ <td>EoP</td>
+ <td>Moderate</td>
+ <td>MDSS</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-5905</td>
+ <td>A-79421261<br />
+ <a
+href="https://source.codeaurora.org/quic/la/kernel/msm-4.4/commit/?id=6eb2f4f6fde1b210712d6ac66b40b9e7684d77db">
+QC-CR#2169715</a></td>
+ <td>EoP</td>
+ <td>Moderate</td>
+ <td>Diag driver</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-5904</td>
+ <td>A-79421260<br />
+ <a href="https://source.codeaurora.org/quic/la/kernel/msm-4.4/commit/?id=88b838c8952ec6414c72449ae15768d15d2606dd">
+QC-CR#2184702</a>
+[<a href="https://source.codeaurora.org/quic/la/kernel/msm-4.9/commit/?id=8e82c0d84ccee87309fd22f8208915f0ba502b26">2</a>]
+</td>
+ <td>EoP</td>
+ <td>Moderate</td>
+ <td>Power driver</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-5903</td>
+ <td>A-79421737<br />
+ <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=20365fa599f42f6e1f175d9d5d60d964927c2160">
+QC-CR#2185477</a></td>
+ <td>EoP</td>
+ <td>Moderate</td>
+ <td>qcacld 3.0</td>
+ </tr>
+ <tr>
+ <td>CVE-2017-18306</td>
+ <td>A-73889358<a href="#asterisk">*</a><br />
+ QC-CR#2216399</td>
+ <td>ID</td>
+ <td>Moderate</td>
+ <td>v4l2</td>
+ </tr>
+ <tr>
+ <td>CVE-2017-18307</td>
+ <td>A-73888283<a href="#asterisk">*</a><br />
+ QC-CR#2026045</td>
+ <td>ID</td>
+ <td>Moderate</td>
+ <td>qcacld-3.0</td>
+ </tr>
+ <tr>
+ <td>CVE-2017-9711</td>
+ <td>A-36367253<a href="#asterisk">*</a><br />
+ QC-CR#2046006</td>
+ <td>EoP</td>
+ <td>Moderate</td>
+ <td>IPA</td>
+ </tr>
+ <tr>
+ <td>CVE-2018-3587</td>
+ <td>A-65542521<a href="#asterisk">*</a><br />
+ QC-CR#2120605</td>
+ <td>EoP</td>
+ <td>Moderate</td>
+ <td>qcacld-2.0</td>
+ </tr>
+</table>
+
+
+<h3 id="update:-framework">Update: Framework</h3>
+
+<table>
+ <col width="21%">
+ <col width="21%">
+ <col width="14%">
+ <col width="14%">
+ <col width="30%">
+ <tr>
+ <th>CVE</th>
+ <th>References</th>
+ <th>Type</th>
+ <th>Severity</th>
+ <th>Updated AOSP versions</th>
+ </tr>
+ <tr>
+ <td>CVE-2017-13295</td>
+ <td>
+<a href="https://android.googlesource.com/platform/frameworks/base/+/da24aa45a8b65a7b9adbe12ff94bf891bdd38825">A-62537081</a>
+[<a href="https://android.googlesource.com/platform/packages/apps/PackageInstaller/+/3af01bd93513d902dbb5382b10109fdf3ab29d2d">2</a>]
+</td>
+ <td>DoS</td>
+ <td>Moderate</td>
+ <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
+ </tr>
+</table>
+
+
+<h3 id="update:-system">Update: System</h3>
+
+<table>
+ <col width="21%">
+ <col width="21%">
+ <col width="14%">
+ <col width="14%">
+ <col width="30%">
+ <tr>
+ <th>CVE</th>
+ <th>References</th>
+ <th>Type</th>
+ <th>Severity</th>
+ <th>Updated AOSP versions</th>
+ </tr>
+ <tr>
+ <td>CVE-2017-13242</td>
+ <td>
+<a href="https://android.googlesource.com/platform/packages/apps/Settings/+/f973e707f50adc0c21599e719be06714f808a333">A-62672248</a>
+</td>
+ <td>ID</td>
+ <td>Moderate</td>
+ <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
+ </tr>
+</table>
+
+
+<h3 id="update:-qualcomm-components">Update: Qualcomm components</h3>
+
+<table>
+ <col width="21%">
+ <col width="21%">
+ <col width="14%">
+ <col width="14%">
+ <col width="30%">
+ <tr>
+ <th>CVE</th>
+ <th>References</th>
+ <th>Type</th>
+ <th>Severity</th>
+ <th>Component</th>
+ </tr>
+ <tr>
+ <td>CVE-2017-15817</td>
+ <td>A-68992394<br />
+ <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/prima/commit/?id=fe43c2b64ac81199de17efc258e95546cb0546f1">QC-CR#2076603</a>
+[<a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/prima/commit/?id=8ba78e506e5002cdae525dd544dbf1df0ccce1ef">2</a>]
+<br>
+<a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=343a3f28338788c5c91289f53171c1f71f293cd7">QC-CR#2084599</a>
+<br>
+<a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=0c21aaa2fefa6c5919813fdd287436dddda54227">QC-CR#2096512</a>
+</td>
+ <td>RCE</td>
+ <td>Critical</td>
+ <td>WLAN</td>
+ </tr>
+</table>
+
+
+<h2 id="common-questions-and-answers">Common questions and answers</h2>
+<p>
+This section answers common questions that may occur after reading this
+bulletin.
+</p>
+<p>
+<strong>1. How do I determine if my device is updated to address these issues?
+</strong>
+</p>
+<p>
+Security patch levels of 2018-08-05 or later address all issues associated with
+the 2018-08-05 security patch level and all previous patch levels. To learn how
+to check a device's security patch level, read the instructions on the <a
+href="https://support.google.com/pixelphone/answer/4457705#pixel_phones&nexus_devices"
+class="external">Pixel and Nexus update schedule</a>.
+</p>
+<p id="type">
+<strong>2. What do the entries in the <em>Type</em> column mean?</strong>
+</p>
+<p>
+Entries in the <em>Type</em> column of the vulnerability details table reference
+the classification of the security vulnerability.
+</p>
+<table>
+ <col width="25%">
+ <col width="75%">
+ <tr>
+ <th>Abbreviation</th>
+ <th>Definition</th>
+ </tr>
+ <tr>
+ <td>RCE</td>
+ <td>Remote code execution</td>
+ </tr>
+ <tr>
+ <td>EoP</td>
+ <td>Elevation of privilege</td>
+ </tr>
+ <tr>
+ <td>ID</td>
+ <td>Information disclosure</td>
+ </tr>
+ <tr>
+ <td>DoS</td>
+ <td>Denial of service</td>
+ </tr>
+ <tr>
+ <td>N/A</td>
+ <td>Classification not available</td>
+ </tr>
+</table>
+<p>
+<strong>3. What do the entries in the <em>References</em> column mean?</strong>
+</p>
+<p>
+Entries under the <em>References</em> column of the vulnerability details table
+may contain a prefix identifying the organization to which the reference value
+belongs.
+</p>
+<table>
+ <col width="25%">
+ <col width="75%">
+ <tr>
+ <th>Prefix</th>
+ <th>Reference</th>
+ </tr>
+ <tr>
+ <td>A-</td>
+ <td>Android bug ID</td>
+ </tr>
+ <tr>
+ <td>QC-</td>
+ <td>Qualcomm reference number</td>
+ </tr>
+ <tr>
+ <td>M-</td>
+ <td>MediaTek reference number</td>
+ </tr>
+ <tr>
+ <td>N-</td>
+ <td>NVIDIA reference number</td>
+ </tr>
+ <tr>
+ <td>B-</td>
+ <td>Broadcom reference number</td>
+ </tr>
+</table>
+<p id="asterisk">
+<strong>4. What does a * next to the Android bug ID in the <em>References</em>
+column mean?</strong>
+</p>
+<p>
+Issues that are not publicly available have a * next to the Android bug ID in
+the <em>References</em> column. The update for that issue is generally contained
+in the latest binary drivers for Pixel / Nexus devices available
+from the <a href="https://developers.google.com/android/nexus/drivers"
+class="external">Google Developer site</a>.
+</p>
+<p>
+<strong>5. Why are security vulnerabilities split between this bulletin and the
+Android Security Bulletins?</strong>
+</p>
+<p>
+Security vulnerabilities that are documented in the Android Security Bulletins
+are required in order to declare the latest security patch level on Android
+devices. Additional security vulnerabilities, such as those documented in this
+bulletin are not required for declaring a security patch level.
+</p>
+<h2 id="versions">Versions</h2>
+<table>
+ <col width="25%">
+ <col width="25%">
+ <col width="50%">
+ <tr>
+ <th>Version</th>
+ <th>Date</th>
+ <th>Notes</th>
+ </tr>
+ <tr>
+ <td>1.0</td>
+ <td>August 6, 2018</td>
+ <td>Bulletin published.</td>
+ </tr>
+</table>
+ </body>
+</html>
\ No newline at end of file
diff --git a/en/security/bulletin/pixel/2018.html b/en/security/bulletin/pixel/2018.html
index 769a6b1..665c7d0 100644
--- a/en/security/bulletin/pixel/2018.html
+++ b/en/security/bulletin/pixel/2018.html
@@ -39,6 +39,21 @@
<th>Security patch level</th>
</tr>
<tr>
+ <td><a href="/security/bulletin/pixel/2018-08-01.html">August 2018</a></td>
+ <td>Coming soon
+ <!--
+ <a href="/security/bulletin/pixel/2018-08-01.html">English</a> /
+ <a href="/security/bulletin/pixel/2018-08-01.html?hl=ja">日本語</a> /
+ <a href="/security/bulletin/pixel/2018-08-01.html?hl=ko">한국어</a> /
+ <a href="/security/bulletin/pixel/2018-08-01.html?hl=ru">ру́сский</a> /
+ <a href="/security/bulletin/pixel/2018-08-01.html?hl=zh-cn">中文 (中国)</a> /
+ <a href="/security/bulletin/pixel/2018-08-01.html?hl=zh-tw">中文 (台灣)</a>
+ -->
+ </td>
+ <td>August 6, 2018</td>
+ <td>2018-08-05</td>
+ </tr>
+ <tr>
<td><a href="/security/bulletin/pixel/2018-07-01.html">July 2018</a></td>
<td>
<a href="/security/bulletin/pixel/2018-07-01.html">English</a> /
diff --git a/en/security/bulletin/pixel/index.html b/en/security/bulletin/pixel/index.html
index c5ba5e6..0732810 100644
--- a/en/security/bulletin/pixel/index.html
+++ b/en/security/bulletin/pixel/index.html
@@ -59,6 +59,21 @@
<th>Security patch level</th>
</tr>
<tr>
+ <td><a href="/security/bulletin/pixel/2018-08-01.html">August 2018</a></td>
+ <td>Coming soon
+ <!--
+ <a href="/security/bulletin/pixel/2018-08-01.html">English</a> /
+ <a href="/security/bulletin/pixel/2018-08-01.html?hl=ja">日本語</a> /
+ <a href="/security/bulletin/pixel/2018-08-01.html?hl=ko">한국어</a> /
+ <a href="/security/bulletin/pixel/2018-08-01.html?hl=ru">ру́сский</a> /
+ <a href="/security/bulletin/pixel/2018-08-01.html?hl=zh-cn">中文 (中国)</a> /
+ <a href="/security/bulletin/pixel/2018-08-01.html?hl=zh-tw">中文 (台灣)</a>
+ -->
+ </td>
+ <td>August 6, 2018</td>
+ <td>2018-08-05</td>
+ </tr>
+ <tr>
<td><a href="/security/bulletin/pixel/2018-07-01.html">July 2018</a></td>
<td>
<a href="/security/bulletin/pixel/2018-07-01.html">English</a> /
diff --git a/en/security/encryption/file-based.html b/en/security/encryption/file-based.html
index 806d822..6695b46 100644
--- a/en/security/encryption/file-based.html
+++ b/en/security/encryption/file-based.html
@@ -34,11 +34,14 @@
Direct Boot APIs and offer users the best, most secure experience possible.
</p>
-<p class="warning"><strong>Warning:</strong> File-based encryption cannot
-currently be used together with <a
-href="/devices/storage/adoptable.html">adoptable storage</a>. 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>
+<aside class="caution">
+ <p><strong>Caution</strong>: On devices running Android 7.0-8.1,
+ file-based encryption can't be used together with
+ <a href="/devices/storage/adoptable.html">adoptable storage</a>. On devices
+ using FBE, new storage media (such as an SD card) must be used as
+ <a href="/devices/storage/traditional.html">traditional storage</a>.</p>
+ <p>Devices running Android 9 and higher can use adoptable storage and FBE.</p>
+</aside>
<h2 id="direct-boot">Direct Boot</h2>
<p>
@@ -252,28 +255,8 @@
<code>filenames_encryption_mode</code> has two possible values: <code>aes-256-cts</code>
and <code>aes-256-heh</code>. If <code>filenames_encryption_mode</code> is not specified
then <code>aes-256-cts</code> value is used.
-<p>
-Whilst testing the FBE implementation on a device, it is possible to specify the
-following flag:
-<code>forcefdeorfbe="<path/to/metadata/partition>"</code>
</p>
-<p>
-This sets the device up with FDE but allows conversion to FBE for developers. By
-default, this behaves like <code>forceencrypt</code>, putting the device into
-FDE mode. However, it will expose a debug option allowing a device to be put
-into FBE mode as is the case in the developer preview. It is also possible to
-enable FBE from fastboot using this command:
-</p>
-<p>
-<pre class="devsite-terminal devsite-click-to-copy">
-fastboot --wipe-and-use-fbe
-</pre>
-</p>
-<p>
-This is intended solely for development purposes as a platform for demonstrating
-the feature before actual FBE devices are released. This flag may be deprecated
-in the future.
-</p>
+
<h3 id="integrating-with-keymaster">Integrating with Keymaster</h3>
<p>
The generation of keys and management of the kernel keyring is handled by
@@ -421,7 +404,8 @@
<h2 id="validation">Validation</h2>
<p>
To ensure the implemented version of the feature works as intended, employ the
-many <a href="https://android.googlesource.com/platform/cts/+/nougat-cts-release/hostsidetests/appsecurity/src/android/appsecurity/cts/DirectBootHostTest.java">
+many
+<a href="https://android.googlesource.com/platform/cts/+/master/hostsidetests/appsecurity/src/android/appsecurity/cts/DirectBootHostTest.java">
CTS encryption tests</a>.
</p>
<p>
@@ -463,12 +447,16 @@
file-based encryption works. It should not be necessary for device manufacturers
to make any changes here to use FBE and Direct Boot on their devices.
</p>
-<h3 id="ext4-encryption">ext4 encryption</h3>
+<h3 id="fscrypt-encryption">fscrypt encryption</h3>
<p>
-The AOSP implementation uses ext4 encryption in kernel and is configured to:
-</p><ul>
-<li>Encrypt file contents with AES-256 in XTS mode
-<li>Encrypt file names with AES-256 in CBC-CTS mode</li></ul>
+The AOSP implementation uses "fscrypt" encryption (supported by ext4 and f2fs)
+in kernel and is configured to:
+</p>
+<ul>
+ <li>Encrypt file contents with AES-256 in XTS mode</li>
+ <li>Encrypt file names with AES-256 in CBC-CTS mode</li>
+</ul>
+
<h3 id="key-derivation">Key derivation</h3>
<p>
Disk encryption keys, which are 512-bit AES-XTS keys, are stored encrypted
@@ -502,9 +490,7 @@
in a new way; this added protection ensures an attacker must recover every bit
of this securely deleted file to recover the key. This is cryptographically
bound to the key in the TEE with all the guarantees that apply to
-<code>KM_TAG_APPLICATION_ID</code>. See the <a
-href="/security/keystore/implementer-ref.html">Keystore
-Implementer's Reference</a>.
+<code><a href="/security/keystore/tags#application_id">KM_TAG_APPLICATION_ID</a></code>.
</body>
</html>
diff --git a/en/security/encryption/index.html b/en/security/encryption/index.html
index 43aaebf..6ed3047 100644
--- a/en/security/encryption/index.html
+++ b/en/security/encryption/index.html
@@ -32,12 +32,45 @@
read it.
</p>
<p>
-Android has two methods for device encryption: full-disk encryption and
-file-based encryption.
+Android has two methods for device encryption: file-based encryption and
+full-disk encryption.
</p>
-<h2 id=full-disk>Full-disk encryption</h2>
+<h2 id=file-based>File-based encryption</h2>
<p>
-Android 5.0 and above supports <a href="full-disk.html">full-disk encryption</a>.
+Android 7.0 and later supports
+<a href="/security/encryption/file-based.html">file-based encryption</a>.
+File-based encryption allows different files to be encrypted with different
+keys that can be unlocked independently. Devices that support file-based
+encryption can also support
+<a href="https://developer.android.com/training/articles/direct-boot">Direct
+Boot</a>, which allows encrypted devices to boot straight to the lock screen,
+thus enabling quick access to important device features like accessibility
+services and alarms.
+</p>
+<p>
+With file-based encryption and APIs that make apps aware of encryption, apps
+can operate within a limited context. This can happen before users have
+provided their credentials while still protecting private user information.
+</p>
+<h3 id="metadata">Metadata encryption</h3>
+<p>
+Android P introduces support for
+<a href="/security/encryption/metadata">metadata encryption</a>, where hardware
+support is present. With metadata encryption, a single key present at boot time
+encrypts whatever content is not encrypted by FBE, such as directory layouts,
+file sizes, permissions, and creation/modification times. This key is protected
+by Keymaster, which in turn is protected by verified boot.
+</p>
+
+
+<h2 id=full-disk>Full-disk encryption</h2>
+<aside class="caution">
+ Caution: Support for full-disk encryption is going away. If you're creating a
+ new device, you should use file-based encryption.
+</aside>
+<p>
+Android 5.0 and above supports
+<a href="/security/encryption/full-disk.html">full-disk encryption</a>.
Full-disk encryption uses a single key—protected with the user’s device password—to
protect the whole of a device’s userdata partition. Upon boot, the user must
provide their credentials before any part of the disk is accessible.
@@ -49,24 +82,5 @@
features like alarms could not operate, accessibility services were unavailable,
and phones could not receive calls.
</p>
-<h2 id=file-based>File-based encryption</h2>
-<p>
-Android 7.0 and above supports <a href="file-based.html">file-based encryption</a>.
-File-based encryption
-allows different files to be encrypted with different keys that can be unlocked
-independently. Devices that support file-based encryption can also support a new
-feature called <a
-href="https://developer.android.com/training/articles/direct-boot">Direct
-Boot</a> that allows encrypted devices to boot straight to the lock screen, thus
-enabling quick access to important device features like accessibility services
-and alarms.
-</p>
-<p>
-With the introduction of file-based encryption and new APIs to make
-applications aware of encryption, it is possible for these apps to operate
-within a limited context. This can happen before users have provided their
-credentials while still protecting private user information.
-</p>
-
</body>
</html>
diff --git a/en/security/encryption/metadata.html b/en/security/encryption/metadata.html
new file mode 100644
index 0000000..472ed1a
--- /dev/null
+++ b/en/security/encryption/metadata.html
@@ -0,0 +1,312 @@
+<html devsite>
+ <head>
+ <title>Metadata Encryption</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ <body>
+ <!--
+ Copyright 2018 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 7.0 and later supports
+<a href="/security/encryption/file-based">file-based encryption</a> (FBE). FBE
+allows different files to be encrypted with different keys that can be unlocked
+independently. These keys are used to encrypt both file contents and file names.
+When FBE is used, other information, such as directory layouts, file sizes,
+permissions, and creation/modification times, is not encrypted. Collectively,
+this is known as filesystem metadata.
+</p>
+<p>
+Android 9 introduces support for metadata encryption where hardware support is
+present. With metadata encryption, a single key present at boot time encrypts
+whatever content is not encrypted by FBE. This key is protected by Keymaster,
+which in turn is protected by verified boot.
+</p>
+<h2 id="implementation">Implementation</h2>
+<p>
+You can set up metadata encryption on new devices running Android 9 by setting
+up the metadata filesystem, changing the init sequence, and turning on metadata
+encryption in the device's fstab file.
+</p>
+<h3 id="hardware-requirements">Hardware requirements</h3>
+<p>
+Metadata encryption can only be set up when the data partition is first
+formatted. As a result, this feature is only for new devices; this is not
+something an OTA should change.
+</p>
+<p>
+To support metadata encryption currently, your hardware needs to support an <a
+href="https://blog.google/topics/connected-workspaces/pixel-security-better-faster-stronger/">inline
+crypto engine</a> to use for file-based encryption. This is indicated by a
+<code>fileencryption=ice</code> directive for the userdata partition in
+<code>fstab.hardware</code>.
+</p>
+<p>
+Additionally, the <code>dm-default-key</code> module must be present and enabled
+in the kernel.
+</p>
+<h3 id="set-up-metadata-filesystem">Set up metadata filesystem</h3>
+<p>
+Because nothing in the userdata partition can be read until the metadata
+encryption key is present, the partition table must set aside a separate
+partition called the "metadata partition" for storing the keymaster blobs that
+protect this key. The metadata partition should be 16MB.
+</p>
+<p>
+<code>fstab.hardware</code> must include an entry for the metadata filesystem
+that lives on that partition mounting it at <code>/metadata</code>, including
+the <code>formattable</code> flag to ensure it is formatted at boot time. The
+f2fs filesystem does not work on smaller partitions; we recommend using ext4
+instead. For example:
+</p>
+
+<pre
+class="prettyprint">/dev/block/bootdevice/by-name/metadata /metadata ext4 noatime,nosuid,nodev,discard wait,check,formattable</pre>
+<p>
+To ensure the <code>/metadata</code> mount point exists, add the following line
+to <code>BoardConfig-common.mk</code>:
+</p>
+
+<pre
+class="prettyprint">BOARD_USES_METADATA_PARTITION := true</pre>
+
+<h3 id="changes-to-the-init-sequence">Changes to the init sequence</h3>
+<p>
+When metadata encryption is used, <code>vold</code> must be running before
+<code>/data</code> is mounted. To ensure that it is started early enough, add
+the following stanza to <code>init.hardware.rc</code>:
+</p>
+
+
+<pre
+class="prettyprint"># We need vold early for metadata encryption
+on early-fs
+ start vold</pre>
+<p>
+Keymaster must be running and ready before init attempts to mount
+<code>/data</code>.
+</p>
+<p>
+ <code>init.hardware.rc</code> should already contain a <code>mount_all</code>
+instruction which mounts <code>/data</code> itself in the <code>on
+late-fs</code> stanza. Before this line, add the directive to exec the
+<code>wait_for_keymaster</code> service:
+</p>
+
+
+<pre
+class="prettyprint">on late-fs
+ …
+ # Wait for keymaster
+ exec_start wait_for_keymaster
+
+ # Mount RW partitions which need run fsck
+ mount_all /vendor/etc/fstab.${ro.boot.hardware.platform} --late</pre>
+
+<h3 id="switching-on-metadata-encryption">Switching on metadata encryption</h3>
+<p>
+Finally add <code>keydirectory=/metadata/vold/metadata_encryption</code> to the
+<code>fstab.hardware</code> entry for userdata:
+</p>
+
+
+<pre
+class="prettyprint">/dev/block/bootdevice/by-name/userdata /data f2fs noatime,nosuid,nodev,discard latemount,wait,check,fileencryption=ice,keydirectory=/metadata/vold/metadata_encryption,quota,formattable</pre>
+
+<h2 id="validation">Validation</h2>
+<p>While implementing metadata encryption, be mindful of these common issues
+and test your implementation.
+</p>
+
+<h3 id="common-issues">Common issues</h3>
+<p>
+During the call to <code>mount_all</code>, which mounts the metadata-encrypted
+<code>/data</code> partition, <code>init</code> executes the vdc tool. The vdc
+tool connects to <code>vold</code> over <code>binder</code> to set up the
+metadata-encrypted device and mount the partition. For the duration of this
+call, <code>init</code> is blocked, and attempts to either read or set
+<code>init</code> properties will block until <code>mount_all</code> finishes.
+If, at this stage, any part of <code>vold</code>'s work is directly or
+indirectly blocked on reading or setting a property, deadlock will result. It is
+important to ensure that <code>vold</code> can complete the work of reading the
+keys, interacting with Keymaster, and mounting the data directory without
+interacting further with <code>init</code>.
+</p>
+<p>
+If Keymaster is not fully started when <code>mount_all</code> runs, it will not
+respond to <code>vold</code> until it has read certain properties from
+<code>init</code>, resulting in exactly the deadlock described. Placing
+<code>exec_start wait_for_keymaster</code> above the relevant
+<code>mount_all</code> invocation as set out ensures that Keymaster is fully
+running in advance and so avoids this deadlock.
+</p>
+
+<h3 id="metadata-encryption-test">Metadata encryption test</h3>
+<p>
+We're upstreaming these tests, but in the meantime, add a few lines to
+<code>Android.bp</code> and add <code>check_encryption.cpp</code> to <code><a
+href="https://android.googlesource.com/platform/system/vold/+/master">platform/system/vold</a></code>
+to test your implementation.</p>
+
+<h4 id="changes-to-android-bp">Changes to <code>Android.bp</code></h4>
+<p>
+Changes to <code>Android.bp</code> called out below.
+</p>
+
+
+<pre class="prettyprint">...
+}
+
+cc_binary {
+ name: "vold",
+ defaults: [
+ "vold_default_flags",
+ "vold_default_libs",
+ ],
+
+ srcs: ["main.cpp"],
+ static_libs: ["libvold"],
+ product_variables: {
+ arc: {
+ static_libs: [
+ "arc_services_aidl",
+ "libarcobbvolume",
+ ],
+ },
+ },
+ init_rc: [
+ "vold.rc",
+ "wait_for_keymaster.rc",
+ ],
+
+ required: [
+ <strong>"check_encryption",</strong>
+ "mke2fs",
+ "vold_prepare_subdirs",
+ "wait_for_keymaster",
+ ],
+}
+...
+<strong>
+}
+
+cc_binary {
+ name: "check_encryption",
+ defaults: ["vold_default_flags"],
+ srcs: [
+ "FileDeviceUtils.cpp",
+ "check_encryption.cpp",
+ ],
+ shared_libs: [
+ "libbase",
+ ],
+}</strong></pre>
+
+<h4 id="add-check_encryption-cpp">Add check_encryption.cpp</h4>
+
+<p>Add <code>check_encryption.cpp</code> to <code><a
+href="https://android.googlesource.com/platform/system/vold/+/master">platform/system/vold</a></code>.</p>
+
+<pre class="prettyprint">/*
+ * Copyright (C) 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.
+ */
+#include "FileDeviceUtils.h"
+
+#include <cmath>
+#include <string>
+
+#include <assert.h>
+#include <stdio.h>
+
+#include <android-base/file.h>
+#include <android-base/logging.h>
+#include <android-base/unique_fd.h>
+using android::base::unique_fd;
+using android::base::ReadFileToString;
+using android::base::WriteStringToFile;
+
+namespace android {
+namespace vold {
+const size_t sectorsize = 1 << 12;
+const int sectorcount = 1024;
+static double randomness_score(const std::string& checkme) {
+ unsigned int freq[256] = {0};
+ unsigned int sum = 256;
+ double loglaplace = 0;
+ for (auto b : checkme) {
+ loglaplace -= 8 + log2(static_cast<double>(++freq[static_cast<uint8_t>(b)]) / (sum++));
+ }
+ return loglaplace;
+ LOG(INFO) << "Score: " << loglaplace; // if negative, not random
+ return loglaplace < 0;
+}
+static bool run_test(const std::string& device) {
+ unique_fd device_fd(open(device.c_str(), O_RDONLY | O_CLOEXEC));
+ if (device_fd.get() == -1) {
+ PLOG(ERROR) << "Failed to open " << device;
+ return false;
+ }
+ int randompassed = 0;
+ auto buf = std::string(sectorsize, '\0');
+ for (int i = 0; i < sectorcount; i++) {
+ auto l = read(device_fd.get(), &buf[0], buf.size());
+ if (l < 1) {
+ PLOG(ERROR) << "Failed read on sector " << i;
+ return false;
+ }
+ if (((size_t)l) != buf.size()) {
+ LOG(ERROR) << "Short read on sector " << i;
+ return false;
+ }
+ auto score = randomness_score(buf);
+ if (score >= 0) {
+ randompassed++;
+ LOG(INFO) << "Passed randomness check on sector " << i << " with score " << score;
+ } else {
+ LOG(ERROR) << "Failed randomness check on sector " << i << " with score " << score;
+ }
+ }
+ LOG(INFO) << "Passed randomness check on " << randompassed << "/" << sectorcount << " sectors";
+ return randompassed == sectorcount;
+}
+} // namespace vold
+} // namespace android
+int main(int argc, const char* const argv[]) {
+ setenv("ANDROID_LOG_TAGS", "*:v", 1);
+ android::base::InitLogging(const_cast<char**>(argv), android::base::StderrLogger);
+ if (argc != 2) {
+ LOG(ERROR) << "Usage: " << argv[0] << " <device>";
+ LOG(ERROR) << "example: " << argv[0] << " /dev/block/bootdevice/by-name/userdata";
+ return -1;
+ }
+ android::vold::run_test(std::string(argv[1]));
+ return 0;
+}</pre>
+ </body>
+</html>
diff --git a/en/security/enhancements/enhancements9.html b/en/security/enhancements/enhancements9.html
new file mode 100644
index 0000000..22febd1
--- /dev/null
+++ b/en/security/enhancements/enhancements9.html
@@ -0,0 +1,34 @@
+<html devsite>
+ <head>
+ <title>Security Enhancements in Anroid 9</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ <body>
+ <!--
+ Copyright 2018 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>Every Android release includes dozens of security enhancements to protect
+users. For a list of some of the major security enhancements available in
+Android 9, see the
+<a href="/setup/start/p-release-notes#security_features">Android Release
+ Notes<a>.
+</p>
+
+ </body>
+</html>
diff --git a/en/security/images/apk-v2-validation.png b/en/security/images/apk-v2-validation.png
new file mode 100644
index 0000000..58c0a06
--- /dev/null
+++ b/en/security/images/apk-v2-validation.png
Binary files differ
diff --git a/en/security/images/apk-validation-process.png b/en/security/images/apk-validation-process.png
index 58c0a06..d7307e3 100644
--- a/en/security/images/apk-validation-process.png
+++ b/en/security/images/apk-validation-process.png
Binary files differ
diff --git a/en/security/images/biometricprompt-architecture.png b/en/security/images/biometricprompt-architecture.png
new file mode 100644
index 0000000..edf3b79
--- /dev/null
+++ b/en/security/images/biometricprompt-architecture.png
Binary files differ
diff --git a/en/security/images/boot_orange.png b/en/security/images/boot_orange.png
index e77edda..ea3dd83 100644
--- a/en/security/images/boot_orange.png
+++ b/en/security/images/boot_orange.png
Binary files differ
diff --git a/en/security/images/boot_red1.png b/en/security/images/boot_red1.png
index 831251c..720ac8d 100644
--- a/en/security/images/boot_red1.png
+++ b/en/security/images/boot_red1.png
Binary files differ
diff --git a/en/security/images/boot_red2.png b/en/security/images/boot_red2.png
index cfdcac1..a3f33d8 100644
--- a/en/security/images/boot_red2.png
+++ b/en/security/images/boot_red2.png
Binary files differ
diff --git a/en/security/images/boot_yellow1.png b/en/security/images/boot_yellow1.png
index d929da9..2789b56 100644
--- a/en/security/images/boot_yellow1.png
+++ b/en/security/images/boot_yellow1.png
Binary files differ
diff --git a/en/security/images/lock-confirmation.png b/en/security/images/lock-confirmation.png
new file mode 100644
index 0000000..5fde224
--- /dev/null
+++ b/en/security/images/lock-confirmation.png
Binary files differ
diff --git a/en/security/images/unlock-confirmation.png b/en/security/images/unlock-confirmation.png
new file mode 100644
index 0000000..de9b71b
--- /dev/null
+++ b/en/security/images/unlock-confirmation.png
Binary files differ
diff --git a/en/security/images/verified-boot-flow.png b/en/security/images/verified-boot-flow.png
new file mode 100644
index 0000000..976146a
--- /dev/null
+++ b/en/security/images/verified-boot-flow.png
Binary files differ
diff --git a/en/security/keystore/index.html b/en/security/keystore/index.html
index 155027e..e7d71e0 100644
--- a/en/security/keystore/index.html
+++ b/en/security/keystore/index.html
@@ -28,7 +28,8 @@
security services to the Android OS, to platform services, and even to
third-party apps. Developers seeking the Android-specific extensions should go
to <a
-href="https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.html">android.security.keystore</a>.</p>
+href="https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.html"
+class="external">android.security.keystore</a>.</p>
<p>Before Android 6.0, Android already had a simple, hardware-backed crypto
services API, provided by versions 0.2 and 0.3 of the Keymaster Hardware
@@ -38,13 +39,25 @@
cannot easily be achieved with only a signature API. Keystore in Android 6.0
extends the Keystore API to provide a broader range of capabilities.</p>
-<p>In Android 6.0, Keystore added <a href="/security/keystore/features.html">symmetric cryptographic
-primitives</a>, AES and HMAC, and an access control system for hardware-backed
-keys. Access controls are specified during key generation and enforced for the
-lifetime of the key. Keys can be restricted to be usable only after the user has
+<p>In Android 6.0, Keystore added
+<a href="/security/keystore/features">symmetric cryptographic primitives</a>,
+AES and HMAC, and an access control system for hardware-backed keys. Access
+controls are specified during key generation and enforced for the lifetime of
+the key. Keys can be restricted to be usable only after the user has
authenticated, and only for specified purposes or with specified cryptographic
-parameters. For more information, see the <a href="/security/keystore/tags">Authorization
-Tags</a> and <a href="/security/keystore/implementer-ref">Functions</a> pages.</p>
+parameters. For more information, see the
+<a href="/security/keystore/tags">Authorization Tags</a> and
+<a href="/security/keystore/implementer-ref">Functions</a> pages.</p>
+
+<p>In addition to expanding the range of cryptographic primitives, Keystore in
+Android 6.0 adds the following:</p>
+
+<ul>
+ <li>A usage control scheme to allow key usage to be limited, to mitigate the risk
+of security compromise due to misuse of keys</li>
+ <li>An access control scheme to enable restriction of keys to specified users,
+clients, and a defined time range</li>
+</ul>
<p>
In Android 7.0, Keymaster 2 added support for key attestation and version binding.
@@ -85,25 +98,79 @@
way to retrieve the relevant data items, as well as to define a mechanism for
securely and permanently disabling the feature.
</p>
+<p>
+In Android 9, updates include:
+</p>
+<ul>
+ <li>Update to
+ <a href="https://android.googlesource.com/platform/hardware/interfaces/+/master/keymaster/4.0/"
+ class="external">Keymaster 4</a></li>
+ <li>Support for embedded Secure Elements</li>
+ <li>Support for secure key import</li>
+ <li>Support for 3DES encryption</li>
+ <li>Changes to version binding so that boot.img and system.img have
+ separately set versions to allow for independent updates</li>
+</ul>
+<h2 id="glossary">Glossary</h2>
+<p>
+Here is a quick overview of Keystore components and their relationships.
+</p>
+<p>
+<strong>AndroidKeystore</strong> is the Android Framework API and component used
+by apps to access Keystore functionality. It is implemented as an extension to
+the standard Java Cryptography Architecture APIs, and consists of Java code that
+runs in the app's own process space. <code>AndroidKeystore</code> fulfills app
+requests for Keystore behavior by forwarding them to the keystore daemon.
+</p>
+<p>
+The <strong>keystore daemon</strong> is an Android system daemon that provides
+access to all Keystore functionality via a <a
+href="https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/security/IKeystoreService.aidl"
+class="external">Binder API</a>. It's responsible for storing "key blobs", which
+contain the actual secret key material, encrypted so Keystore can store it but
+not use it or reveal it.
+</p>
+<p>
+<strong>keymasterd</strong> is a HIDL server that provides access to the
+Keymaster TA. (This name is not standarized and is for conceptual purposes.)
+</p>
+<p>
+<strong>Keymaster TA</strong> (trusted application) is the software running in a
+secure context, most often in TrustZone on an ARM SoC, that provides all of the
+secure Keystore operations, has access to the raw key material, validates all of
+the access control conditions on keys, etc.
+</p>
+<p>
+<strong>LockSettingsService</strong> is the Android system component responsible
+for user authentication, both password and fingerprint. It's not part of
+Keystore, but relevant because many Keystore key operations require user
+authentication. <code>LockSettingsService</code> interacts with the Gatekeeper
+TA and Fingerprint TA to obtain authentication tokens, which it provides to the
+keystore daemon, and which are ultimately consumed by the Keymaster TA
+application.
+</p>
+<p>
+<strong>Gatekeeper TA</strong> (trusted application) is another component
+running in the secure context, which is responsible for authenticating user
+passwords and generating authentication tokens used to prove to the Keymaster TA
+that an authentication was done for a particular user at a particular point in
+time.
+</p>
+<p>
+<strong>Fingerprint TA </strong>(trusted application) is another component
+running in the secure context which is responsible for authenticating user
+fingerprints and generating authentication tokens used to prove to the Keymaster
+TA that an authentication was done for a particular user at a particular point
+in time.
+</p>
-<h2 id="goals">Goals</h2>
+
+<h2 id="architecture">Architecture</h2>
<p>The Android Keystore API and the underlying Keymaster HAL
provides a basic but adequate set of cryptographic primitives to allow the
implementation of protocols using access-controlled, hardware-backed keys.</p>
-<p>In addition to expanding the range of cryptographic primitives, Keystore in
-Android 6.0 adds the following:</p>
-
-<ul>
- <li>A usage control scheme to allow key usage to be limited, to mitigate the risk
-of security compromise due to misuse of keys</li>
- <li>An access control scheme to enable restriction of keys to specified users,
-clients, and a defined time range</li>
-</ul>
-
-<h2 id="architecture">Architecture</h2>
-
<p>The Keymaster HAL is an OEM-provided, dynamically-loadable library used by the
Keystore service to provide hardware-backed cryptographic services. To keep
things secure, HAL implementations don't perform any sensitive operations in
@@ -120,9 +187,9 @@
multiple layers (e.g. app, framework, Keystore daemon), but that can be ignored
for the purposes of this document. This means that the described Keymaster HAL
API is low-level, used by platform-internal components, and not exposed to app
-developers. The higher-level API, for API level 23, is described on the <a
-href="https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.html">Android
-Developer site</a>.</p>
+developers. The higher-level API is described on the <a
+href="https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.html"
+class="external">Android Developer site</a>.</p>
<p>The purpose of the Keymaster HAL is not to implement the security-sensitive
algorithms but only to marshal and unmarshal requests to the secure world. The
diff --git a/en/security/keystore/tags.html b/en/security/keystore/tags.html
index 8253b7e..0273fe0 100644
--- a/en/security/keystore/tags.html
+++ b/en/security/keystore/tags.html
@@ -27,11 +27,15 @@
in, and whether the tag is repeatable. Except as noted in the tag descriptions,
all of the tags below are used during key generation to specify key
characteristics.</p>
-<p>For Keymaster 3, tags are defined in
-<code>platform/hardware/interfaces/keymaster/3.0/types.hal</code>. For
-Keymaster 2 and below, tags are defined in
-<code><a href="https://android.googlesource.com/platform/hardware/libhardware/+/master/include/hardware">
-hardware/libhardware/include/hardware/keymaster_defs.h</a></code>.</p>
+<p>For Keymaster 4, tags are defined in
+<code>platform/hardware/interfaces/keymaster/<var>keymaster-version</var>/types.hal</code>,
+such as
+<a href="https://android.googlesource.com/platform/hardware/interfaces/+/master/keymaster/3.0/types.hal" class="external">
+3.0/types.hal</a> for Keymaster 3 and
+<a href="https://android.googlesource.com/platform/hardware/interfaces/+/master/keymaster/4.0/types.hal" class="external">
+4.0/types.hal</a> for Keymaster 4. For Keymaster 2 and below, tags are defined in
+<code><a href="https://android.googlesource.com/platform/hardware/libhardware/+/master/include/hardware" class="external">
+platform/hardware/libhardware/include/hardware/keymaster_defs.h</a></code>.</p>
<p>For functions, see the
<a href="/security/keystore/implementer-ref">Keymaster Functions</a> page.</p>
@@ -45,7 +49,7 @@
<h2 id="active_datetime">Tag::ACTIVE_DATETIME</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Specifies the date and time at which the key becomes active. Prior to this
@@ -58,7 +62,7 @@
<h2 id="algorithm">Tag::ALGORITHM</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Specifies the cryptographic algorithm with which the key is used.</p>
@@ -88,7 +92,7 @@
<h2 id="all_applications">Tag::ALL_APPLICATIONS</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Reserved for future use.</p>
@@ -96,7 +100,7 @@
<h2 id="allow_while_on_body">Tag::ALLOW_WHILE_ON_BODY</h2>
-<p><strong>Version</strong>: 2, 3</p>
+<p><strong>Version</strong>: 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>This tag is applicable only for Android Wear devices with on-body sensors. At
@@ -106,14 +110,14 @@
<h2 id="all_users">Tag::ALL_USERS</h2>
-<p><strong>Version</strong>: 3</p>
+<p><strong>Version</strong>: 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Reserved for future use.</p>
<h2 id="application_data">Tag::APPLICATION_DATA</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>When provided to
@@ -140,7 +144,7 @@
<h2 id="application_id">Tag::APPLICATION_ID</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>When provided to
@@ -166,7 +170,7 @@
<h2 id="associated_data">Tag::ASSOCIATED_DATA</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Provides "associated data" for AES-GCM encryption or decryption. This tag is
@@ -177,7 +181,7 @@
<p>The value is a blob, an arbitrary-length array of bytes.</p>
<h2 id="attestation_application_id">Tag::ATTESTATION_APPLICATION_ID</h2>
-<p><strong>Version</strong>: 3</p>
+<p><strong>Version</strong>: 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Used to identify the set of possible applications of which one
@@ -186,14 +190,14 @@
<p>The value is a blob, an arbitrary-length array of bytes.</p>
<h2 id="attestation_challenge">Tag::ATTESTATION_CHALLENGE</h2>
-<p><strong>Version</strong>: 3</p>
+<p><strong>Version</strong>: 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Used to provide challenge in attestation.</p>
<p>The value is a blob, an arbitrary-length array of bytes.</p>
<h2 id="attestation_id_brand">Tag::ATTESTATION_ID_BRAND</h2>
-<p><strong>Version</strong>: 3</p>
+<p><strong>Version</strong>: 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Provides the device's brand name, as returned by <code>Build.BRAND</code>
@@ -206,7 +210,7 @@
<p>The value is a blob, an arbitrary-length array of bytes.</p>
<h2 id="attestation_id_device">Tag::ATTESTATION_ID_DEVICE</h2>
-<p><strong>Version</strong>: 3</p>
+<p><strong>Version</strong>: 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Provides the device's device name, as returned by <code>Build.DEVICE</code>
@@ -219,7 +223,7 @@
<p>The value is a blob, an arbitrary-length array of bytes.</p>
<h2 id="attestation_id_imei">Tag::ATTESTATION_ID_IMEI</h2>
-<p><strong>Version</strong>: 3</p>
+<p><strong>Version</strong>: 3, 4</p>
<p><strong>Repeatable</strong>? Yes</p>
<p>Provides the IMEIs for all radios on the device. This field is set only
@@ -231,7 +235,7 @@
<p>The value is a blob, an arbitrary-length array of bytes.</p>
<h2 id="attestation_id_manufacturer">Tag::ATTESTATION_ID_MANUFACTURER</h2>
-<p><strong>Version</strong>: 3</p>
+<p><strong>Version</strong>: 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Provides the device's manufacturer name, as returned by
@@ -244,7 +248,7 @@
<p>The value is a blob, an arbitrary-length array of bytes.</p>
<h2 id="attestation_id_meid">Tag::ATTESTATION_ID_MEID</h2>
-<p><strong>Version</strong>: 3</p>
+<p><strong>Version</strong>: 3, 4</p>
<p><strong>Repeatable</strong>? Yes</p>
<p>Provides the MEIDs for all radios on the device. This field will only be set
@@ -256,7 +260,7 @@
<p>The value is a blob, an arbitrary-length array of bytes.</p>
<h2 id="attestation_id_model">Tag::ATTESTATION_ID_MODEL</h2>
-<p><strong>Version</strong>: 3</p>
+<p><strong>Version</strong>: 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Provides the device's model name, as returned by
@@ -271,7 +275,7 @@
<h2 id="attestation_id_product">Tag::ATTESTATION_ID_PRODUCT</h2>
-<p><strong>Version</strong>: 3</p>
+<p><strong>Version</strong>: 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Provides the device's product name, as returned by
@@ -284,7 +288,7 @@
<p>The value is a blob, an arbitrary-length array of bytes.</p>
<h2 id="attestation_id_serial">Tag::ATTESTATION_ID_SERIAL</h2>
-<p><strong>Version</strong>: 3</p>
+<p><strong>Version</strong>: 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Provides the device's serial number. This field is set only when
@@ -297,7 +301,7 @@
<h2 id="auth_timeout">Tag::AUTH_TIMEOUT</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Specifies the time in seconds for which the key is authorized for use, after
@@ -315,7 +319,7 @@
<h2 id="auth_token">Tag::AUTH_TOKEN</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Provides an
@@ -331,7 +335,7 @@
<h2 id="blob_usage_requirements">Tag::BLOB_USAGE_REQUIREMENTS</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Specifies the necessary system environment conditions for the generated
@@ -369,7 +373,7 @@
<h2 id="block_mode">Tag::BLOCK_MODE</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? Yes</p>
<p>Specifies the block cipher mode(s) with which the key may be used.
@@ -403,10 +407,35 @@
If the specifiedmode is not in the modes associated with the key, the
operation fails with <code>ErrorCode::INCOMPATIBLE_BLOCK_MODE</code>.</p>
+<h2 id=boot_patchlevel">Tag::BOOT_PATCHLEVEL</h2>
+<p><strong>Version</strong>: 4</p>
+<p>Tag::BOOT_PATCHLEVEL specifies the boot image (kernel) security patch level
+with which the key may be used. This tag is never sent to the keymaster TA, but
+is added to the hardware-enforced authorization list by the TA. Any attempt to
+use a key with a <code>Tag::BOOT_PATCHLEVEL</code> value different from the
+currently-running system patchlevel causes <code>begin()</code>,
+<code>getKeyCharacteristics()</code> or <code>exportKey()</code> to return
+<code>ErrorCode::KEY_REQUIRES_UPGRADE</code>. See <code>upgradeKey()</code>
+for details.
+</p>
+<p>
+The value of the tag is an integer of the form YYYYMMDD, where YYYY is the
+four-digit year of the last update, MM is the two-digit month and DD is the
+two-digit day of the last update. For example, for a key generated on an
+Android device last updated on June 5, 2018, the value would be 20180605.
+If the day is not known, 00 may be substituted.
+</p>
+<p>
+During each boot, the bootloader must provide the patch level of the boot image
+to the secure envirionment (mechanism is implementation-defined).
+</p>
+<p>
+Must be hardware-enforced.
+</p>
<h2 id="bootloader_only">Tag::BOOTLOADER_ONLY</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Specifies only the bootloader can use the key.</p>
@@ -420,7 +449,7 @@
<h2 id="caller_nonce">Tag::CALLER_NONCE</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Specifies that the caller can provide a nonce for nonce-requiring operations.</p>
@@ -437,7 +466,7 @@
<h2 id="creation_datetime">Tag::CREATION_DATETIME</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Specifies the date and time the key was created, in milliseconds since January
@@ -446,7 +475,7 @@
<h2 id="digest">Tag::DIGEST</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? Yes</p>
<p>Specifies the digest algorithms that may be used with the key to perform
@@ -490,7 +519,7 @@
<h2 id="ec_curve">Tag::EC_CURVE</h2>
-<p><strong>Version</strong>: 2, 3</p>
+<p><strong>Version</strong>: 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>In Keymaster 1, the curve used for EC keys was guessed from the specified key
@@ -536,7 +565,7 @@
<h2 id="include_unique_id">Tag::INCLUDE_UNIQUE_ID</h2>
-<p><strong>Version</strong>: 2, 3</p>
+<p><strong>Version</strong>: 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>This tag is specified during key generation to indicate that an attestation
@@ -549,7 +578,7 @@
<h2 id="key_size">Tag::KEY_SIZE</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Specifies the size, in bits, of the key, measuring in the normal way for the
@@ -564,7 +593,7 @@
<h2 id="mac_length">Tag::MAC_LENGTH</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Provides the requested length of a MAC or GCM authentication tag, in bits.</p>
@@ -576,7 +605,7 @@
<h2 id="max_uses_per_boot">Tag::MAX_USES_PER_BOOT</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Specifies the maximum number of times that a key may be used between system
@@ -599,7 +628,7 @@
<h2 id="min_mac_length">Tag::MIN_MAC_LENGTH</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>This tag specifies the minimum length of MAC that can be requested or
@@ -612,7 +641,7 @@
<h2 id="min_seconds_between_ops">Tag::MIN_SECONDS_BETWEEN_OPS</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Specifies the minimum amount of time that elapses between allowed
@@ -639,7 +668,7 @@
<h2 id="no_auth_required">Tag::NO_AUTH_REQUIRED</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Specifies that no authentication is required to use this key. This tag is
@@ -651,7 +680,7 @@
<h2 id="nonce">Tag::NONCE</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Provides or returns a nonce or Initialization Vector (IV) for AES GCM, CBC, or
@@ -670,7 +699,7 @@
<h2 id="origin">Tag::ORIGIN</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Specifies where the key was created, if known. This tag may not be specified
@@ -727,7 +756,7 @@
<h2 id="origination_expire_datetime">Tag::ORIGINATION_EXPIRE_DATETIME</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Specifies the date and time at which the key expires for signing and encryption
@@ -742,7 +771,7 @@
<h2 id="os_patchlevel">Tag::OS_PATCHLEVEL</h2>
-<p><strong>Version</strong>: 2, 3</p>
+<p><strong>Version</strong>: 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>This tag is never sent to the keymaster TA, but is added to the
@@ -764,7 +793,7 @@
<h2 id="os_version">Tag::OS_VERSION</h2>
-<p><strong>Version</strong>: 2, 3</p>
+<p><strong>Version</strong>: 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>This tag is never sent to the keymaster TA, but is added to the
@@ -778,7 +807,7 @@
<h2 id="padding">Tag::PADDING</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? Yes</p>
<p>Specifies the padding modes that may be used with the key. This tag is
@@ -839,7 +868,7 @@
<h2 id="purpose">Tag::PURPOSE</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? Yes</p>
<p>Specifies the set of purposes for which the key may be used.</p>
@@ -878,7 +907,7 @@
<h2 id="reset_since_id_rotation">Tag::RESET_SINCE_ID_ROTATION</h2>
-<p><strong>Version</strong>: 3</p>
+<p><strong>Version</strong>: 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Specifies whether the device has beeen factory reset
since the last unique ID rotation. Used for key attestation.</p>
@@ -889,7 +918,7 @@
<h2 id="rollback_resistant">Tag::ROLLBACK_RESISTANT</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Indicates that the key is rollback-resistant, meaning that when deleted
@@ -904,7 +933,7 @@
<h2 id="root_of_trust">Tag::ROOT_OF_TRUST</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
@@ -914,7 +943,7 @@
<h2 id="rsa_public_exponent">Tag::RSA_PUBLIC_EXPONENT</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Specifies the value of the public exponent for an RSA key pair. This tag is
@@ -929,7 +958,7 @@
<h2 id="unique_id">Tag::UNIQUE_ID</h2>
-<p><strong>Version</strong>: 3</p>
+<p><strong>Version</strong>: 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Used to provide unique ID in attestation.</p>
@@ -938,7 +967,7 @@
<h2 id="usage_expire_datetime">Tag::USAGE_EXPIRE_DATETIME</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Specifies the date and time at which the key expires for verification and
@@ -952,7 +981,7 @@
<h2 id="user_auth_type">Tag::USER_AUTH_TYPE</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Specifies the types of user authenticators that may be used to authorize this
@@ -990,7 +1019,7 @@
<h2 id="user_secure_id">Tag::USER_SECURE_ID</h2>
-<p><strong>Version</strong>: 1, 2, 3</p>
+<p><strong>Version</strong>: 1, 2, 3, 4</p>
<p><strong>Repeatable</strong>? No</p>
<p>Specifies that a key may only be used under a particular secure user
@@ -1010,5 +1039,32 @@
value in the authentication token, the key is authorized for use. Otherwise the operation
fails with <code>ErrorCode::KEY_USER_NOT_AUTHENTICATED</code>.</p>
+<h2 id="vendor_patchlevel">Tag::VENDOR_PATCHLEVEL</h2>
+<p><strong>Version</strong>: 4</p>
+<p>This tag specifies the vendor image security patch level with which the key
+may be used. This tag is never sent to the keymaster TA, but is added to the
+hardware-enforced authorization list by the TA. Any attempt to use a key with a
+<code>Tag::VENDOR_PATCHLEVEL</code> value different from the currently-running
+system patchlevel must cause <code>begin()</code>,
+<code>getKeyCharacteristics()</code> or <code>exportKey()</code> to return
+<code>ErrorCode::KEY_REQUIRES_UPGRADE</code>. See <code>upgradeKey()</code>
+for details.
+</p>
+<p>
+The value of the tag is an integer of the form YYYYMMDD, where YYYY is the
+four-digit year of the last update, MM is the two-digit month and DD is the
+two-digit day of the last update. For example, for a key generated on an
+Android device last updated on June 5, 2018, the value would be 20180605.</p>
+<p>
+The IKeymasterDevice HAL must read the current vendor patchlevel from the system
+property <code>ro.vendor.build.security_patch</code> and deliver it to the
+secure environment when the HAL is first loaded (mechanism is
+implementation-defined). The secure environment must not accept another
+patchlevel until after the next boot.
+</p>
+<p>
+Must be hardware-enforced.
+</p>
+
</body>
</html>
diff --git a/en/security/keystore/version-binding.html b/en/security/keystore/version-binding.html
index 17059d5..73473ff 100644
--- a/en/security/keystore/version-binding.html
+++ b/en/security/keystore/version-binding.html
@@ -20,10 +20,10 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-
+
<p>
In Keymaster 1, all keymaster keys were cryptographically bound to the device
-<em>Root of Trust</em>, or the verified boot key. In Keymaster 2 and above, all
+<em>Root of Trust</em>, or the Verified Boot key. In Keymaster 2 and 3, all
keys are also bound to the operating system and patch level of the system image.
This ensures that an attacker who discovers a weakness in an old
version of system or TEE software cannot roll a device back to the vulnerable
@@ -35,6 +35,55 @@
reversion of the device to a previous release will cause the keys to be
unusable.
</p>
+<p>
+To support Treble's modular structure and break the binding of system.img to
+boot.img, Keymaster 4 changed the key version binding model to have separate
+patch levels for each partition. This allows each partition to be updated
+independently, while still providing rollback protection.
+</p>
+<p>
+In Android 9 the <code>boot</code>, <code>system</code> and <code>vendor</code>
+partitions each have their own patch level.
+<ul>
+ <li>Devices with Android Verified Boot
+(AVB) can put all of the patch levels and the system version in vbmeta, so the
+bootloader can provide them to Keymaster. For chained partitions, the version
+info for the partition will be in the chained vbmeta. In general, version
+information should be in the vbmeta struct that contains the verification data
+(hash or hashtree) for a given partition.
+</li>
+<li>On devices without AVB:
+ <ul>
+ <li>Verified Boot implementations need to provide a hash of the version
+ metadata to bootloader, so that bootloader can provide them to Keymaster.
+ </li>
+ <li>boot.img can continue storing patch level in the header</li>
+ <li>system.img can continue storing patch level and OS version in read-only
+ properties</li>
+ <li>vendor.img stores the patch level in the read-only property
+ <code>ro.vendor.build.version.security_patch</code>.</li>
+ <li>The bootloader can provide a hash of all data validated by verified boot
+ to keymaster.</li>
+ </ul>
+</li>
+<li>In Android 9, use the following tags to supply version information for
+ the following partitions:
+ <ul>
+ <li><code>VENDOR_PATCH_LEVEL</code>: <code>vendor</code> partition</li>
+ <li><code>BOOT_PATCH_LEVEL</code>: <code>boot</code> partition</li>
+ <li><code>OS_PATCH_LEVEL</code> and <code>OS_VERSION</code>:
+ <code>system</code> partition. (<code>OS_VERSION</code> is removed from
+ the boot.img header.</li>
+ </ul>
+</li>
+<li>
+Keymaster implementations should treat all patch levels independently. Keys are
+usable if all version info matches the values associated with a key, and
+<code>IKeymaster::upgradeDevice()</code> rolls to a higher patch level if
+needed.</li>
+</ul>
+
+
<h2 id="hal-changes">HAL Changes</h2>
<p>
diff --git a/en/security/overview/acknowledgements.html b/en/security/overview/acknowledgements.html
index 5db2794..7071cb7 100644
--- a/en/security/overview/acknowledgements.html
+++ b/en/security/overview/acknowledgements.html
@@ -37,6 +37,84 @@
<p>In 2018, the security acknowledgements are listed by month. In prior years,
acknowledgements were listed together.</p>
+<h4 id="aug-2018">August</h4>
+
+<table>
+ <col width="70%">
+ <col width="30%">
+ <tr>
+ <th>Researchers</th>
+ <th>CVEs</th>
+ </tr>
+ <tr>
+ <td>Chao Dai @ L.O. Team</td>
+ <td>CVE-2018-9437</td>
+ </tr>
+ <tr>
+ <td><a href="weibo.com/csddl" class="external">Chong Wang</a> of Chengdu
+ Security Response Center, Qihoo 360 Technology Co. Ltd.</td>
+ <td>CVE-2018-9436, CVE-2018-9448, CVE-2018-9454, CVE-2018-9455</td>
+ </tr>
+ <tr>
+ <td>Dinesh Venkatesan (<a
+href="https://twitter.com/malwareresearch" class="external">@malwareresearch</a>)
+of Symantec</td>
+ <td>CVE-2017-13295</td>
+ </tr>
+ <tr>
+ <td><a href="https://www.linkedin.com/in/dzima" class="external">Dzmitry
+ Lukyanenka</a></td>
+ <td>CVE-2018-9459, CVE-2018-9461</td>
+ </tr>
+ <tr>
+ <td>En He
+ (<a href="https://twitter.com/heeeeen4x" class="external">@heeeeen4x</a>)
+ and Bo Liu of
+ <a href="http://www.ms509.com" class="external">MS509Team</a></td>
+ <td>CVE-2017-13242, CVE-2018-9457</td>
+ </tr>
+ <tr>
+ <td><a href="mailto:pinci.francesco@gmail.com" class="external">Francesco
+ Pinci</a></td>
+ <td>CVE-2018-9447</td>
+ </tr>
+ <tr>
+ <tr>
+ <td>Jann Horn of Google Project Zero</td>
+ <td>CVE-2018-9445</td>
+ </tr>
+ <tr>
+ <td>Joshua Steiner of Introne Apps</td>
+ <td>CVE-2017-13322</td>
+ </tr>
+ <tr>
+ <td>Tencent Blade Team</td>
+ <td>CVE-2017-18306, CVE-2017-18307</td>
+ </tr>
+ <tr>
+ <td>Tong Lin (<a
+href="mailto:segfault5514@gmail.com" class="external">segfault5514@gmail.com</a>)
+and Mingjian Zhou (周明建)
+(<a href="https://twitter.com/Mingjian_Zhou" class="external">@Mingjian_Zhou</a>)
+of <a href="http://c0reteam.org" class="external">C0RE Team</a></td>
+ <td>CVE-2018-9439</td>
+ </tr>
+ <tr>
+ <td>V.E.O (<a href="https://twitter.com/vysea" class="external">@VYSEa</a>)
+ of <a
+href="http://blog.trendmicro.com/trendlabs-security-intelligence/category/mobile/"
+class="external">Mobile Security Research Team</a>,
+<a href="http://www.trendmicro.com" class="external">Trend Micro</a></td>
+ <td>CVE-2018-9444</td>
+ </tr>
+ <tr>
+ <td><a href="weibo.com/ele7enxxh" class="external">Zinuo Han</a> of Chengdu
+ Security Response Center, Qihoo 360 Technology Co. Ltd.</td>
+ <td>CVE-2018-9435, CVE-2018-9446, CVE-2018-9449, CVE-2018-9450,
+ CVE-2018-9451, CVE-2018-9453</td>
+ </tr>
+</table>
+
<h4 id="july-2018">July</h4>
<table>
<col width="70%">
diff --git a/en/security/overview/app-security.html b/en/security/overview/app-security.html
index 5aa2a1e..317b57b 100644
--- a/en/security/overview/app-security.html
+++ b/en/security/overview/app-security.html
@@ -73,7 +73,7 @@
<h2 id="the-android-permission-model-accessing-protected-apis">
The Android Permission Model: Accessing Protected APIs</h2>
<p>All applications on Android run in an <a
-href="/security/overview/kernel-security#the-application-sandbox">Application Sandbox</a>.
+href="/security/app-sandbox">Application Sandbox</a>.
By default, an Android application can only access a limited range of system
resources. The system manages Android application access to resources that, if
used incorrectly or maliciously, could adversely impact the user experience,
diff --git a/en/security/overview/kernel-security.html b/en/security/overview/kernel-security.html
index 1eaaeb3..9800d91 100644
--- a/en/security/overview/kernel-security.html
+++ b/en/security/overview/kernel-security.html
@@ -62,41 +62,10 @@
Bluetooth)</li>
</ul>
<h2 id="the-application-sandbox">The Application Sandbox</h2>
-<p>The Android platform takes advantage of the Linux user-based protection as a
- means of identifying and isolating application resources. The Android system
- assigns a unique user ID (UID) to each Android application and runs it as that user
- in a separate process. This approach is different from other operating systems
- (including the traditional Linux configuration), where multiple applications
- run with the same user permissions.</p>
-<p>This sets up a kernel-level Application Sandbox. The kernel enforces security
- between applications and the system at the process level through standard Linux
- facilities, such as user and group IDs that are assigned to applications. By
- default, applications cannot interact with each other and applications have
- limited access to the operating system. If application A tries to do something
- malicious like read application B's data or dial the phone without permission
- (which is a separate application), then the operating system protects against
- this because application A does not have the appropriate user privileges. The
- sandbox is simple, auditable, and based on decades-old UNIX-style user
- separation of processes and file permissions.</p>
-<p>Because the Application Sandbox is in the kernel, this security model extends to
- native code and to operating system applications. All of the software above the
- kernel, such as operating system libraries, application
- framework, application runtime, and all applications, run within the Application
- Sandbox. On some platforms, developers are constrained to a specific
- development framework, set of APIs, or language in order to enforce security.
- On Android, there are no restrictions on how an application can be written that
- are required to enforce security; in this respect, native code is just as
- secure as interpreted code.</p>
-<p>In some operating systems, memory corruption errors in one application may
- lead to corruption in other applications housed in the same memory space,
- resulting in a complete compromise of the security of the device. Because all
- applications and their resources are sandboxed at the OS level, a memory
- corruption error will allow arbitrary code execution only in
- the context of that particular application, with the permissions established by
- the operating system.</p>
-<p>Like all security features, the Application Sandbox is not unbreakable.
- However, to break out of the Application Sandbox in a properly configured
- device, one must compromise the security of the Linux kernel.</p>
+<p>Android’s application security is enforced by the application sandbox, which
+ isolates apps from each other and protects apps and the system from malicious
+ apps. For more details, see <a href="/security/app-sandbox">Application
+ Sandbox</a>.</p>
<h2 id="system-partition-and-safe-mode">System Partition and Safe Mode</h2>
<p>The system partition contains Android's kernel as well as the operating system
libraries, application runtime, application framework, and applications. This
diff --git a/en/security/selinux/build.html b/en/security/selinux/build.html
new file mode 100644
index 0000000..62b23aa
--- /dev/null
+++ b/en/security/selinux/build.html
@@ -0,0 +1,302 @@
+<html devsite>
+ <head>
+ <title>Building SELinux Policy</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ <body>
+ <!--
+ Copyright 2018 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
+
+ //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>
+This article covers how SELinux policy is built. SELinux policy is built from
+the combination of core AOSP policy (platform) and device-specific policy
+(vendor). The SELinux policy build flow for Android 4.4 through Android
+7.0 merged all sepolicy fragments then generated monolithic files in the root
+directory. This meant that SoC vendors and ODM manufacturers modified boot.img
+(for non-A/B devices) or system.img (for A/B devices) every time policy was
+modified.
+</p>
+<p>
+In Android 8.0 and higher, platform and vendor policy is built separately.
+SOCs and OEMs can update their parts of the policy, build their images
+(vendor.img, boot.img, etc.), then update those images independent of platform
+updates.
+</p>
+<p>
+However, as modularized SELinux policy files are stored on <code>/vendor</code>
+partitions, the <code>init</code> process must mount the system and vendor
+partitions earlier so it can read SELinux files from those partitions and merge
+them with core SELinux files in the system directory (before loading them into
+the kernel).
+</p>
+
+<h2 id="files">Source files</h2>
+<p>
+The logic for building SELinux is in these files:
+</p>
+<ul>
+ <li><a href="https://android.googlesource.com/platform/external/selinux/" class="external">
+ <code>external/selinux</code></a>: External SELinux project, used to
+ build HOST command line utilities to compile SELinux policy and labels.
+ <ul>
+ <li><a href="https://android.googlesource.com/platform/external/selinux/libselinux" class="external">
+ <code>external/selinux/libselinux</code></a>: Android uses only a subset
+ of the external <code>libselinux</code> project along with some
+ Android-specific customizations. For details, see
+ <a href="https://android.googlesource.com/platform/external/selinux/+/master/README.android" class="external">
+ <code>external/selinux/README.android</code></a>.</li>
+ <li><a href="https://android.googlesource.com/platform/external/selinux/+/master/libsepol/" class="external">
+ <code>external/selinux/libsepol</code></a>:
+ <ul>
+ <li><a href="http://man7.org/linux/man-pages/man8/chkcon.8.html"i class="external">
+ <code>chkcon</code></a>: Determine if a security context is valid
+ for a given binary policy (host executable).</li>
+ <li><a href="https://android.googlesource.com/platform/external/selinux/+/master/libsepol/" class="external">
+ <code>libsepol</code></a>: SELinux library for manipulating binary
+ security policies (host static/shared library, target static library).</li>
+ </ul>
+ </li>
+ <li><a href="https://android.googlesource.com/platform/external/selinux/+/master/checkpolicy/" class="external">
+ <code>external/selinux/checkpolicy</code></a>: SELinux policy compiler
+ (host executables: <code>checkpolicy</code>, <code>checkmodule</code>,
+ and <code>dispol</code>). Depends on <code>libsepol</code>.</li>
+ </ul>
+ </li>
+ <li><a href="https://android.googlesource.com/platform/system/sepolicy/+/master" class="external">
+ <code>system/sepolicy</code></a>: Core Android SELinux policy
+ configurations, including contexts and policy files. Major sepolicy build
+ logic is also here (<code>system/sepolicy/Android.mk</code>).</li>
+</ul>
+<p>
+For more details on the files in <code>system/sepolicy</code>
+<a href="/security/selinux/implement#key_files">Implementing SELinux</a>.
+</p>
+
+<h2 id="android-7">Android 7.0 and earlier</h2>
+
+<p>This section covers how SELinux policy is built in Android 7.x and earlier.</p>
+
+<h3 id="android-7-building">Building SELinux policy</h3>
+<p>
+SELinux policy is created by combining the core AOSP policy with device-specific
+customizations. The combined policy is then passed to the policy compiler and
+various checkers. Device-specific customization is done through the
+<code>BOARD_SEPOLICY_DIRS</code> variable defined in device-specific
+<code>Boardconfig.mk</code> file. This global build variable contains a list of
+directories that specify the order in which to search for additional policy files.
+</p>
+<p>
+For example, a SoC vendor and an ODM might each add a directory, one for the
+SoC-specific settings and another for device-specific settings, to generate the
+final SELinux configurations for a given device:
+</p>
+<ul>
+ <li><code>BOARD_SEPOLICY_DIRS += device/<var>SOC</var>/common/sepolicy</code></li>
+ <li><code>BOARD_SEPOLICY_DIRS += device/<var>SoC</var>/<var>DEVICE</var>/sepolicy</code></li>
+</ul>
+<p>
+The content of file_contexts files in <code>system/sepolicy</code> and
+<code>BOARD_SEPOLICY_DIRS</code> are concatenated to generate the
+<code>file_contexts.bin</code> on the device:
+</p>
+
+<figure>
+ <img src="images/n-selinux-build-logic.png"
+ alt="This image shows the SELinux build logic for Android 7.x.">
+ <figcaption><strong>Figure 1</strong>. SELinux build logic</figcaption>
+</figure>
+<p>
+The <code>sepolicy</code> file consists of multiple source files:
+</p>
+<ul>
+ <li>The plain text <code>policy.conf</code> is generated by concatenating
+ <code>security_classes</code>, <code>initial_sids</code>,
+ <code>*.te</code> files, <code>genfs_contexts</code>, and
+ <code>port_contexts</code> in that order.</li>
+ <li>For each file (such as <code>security_classes</code>), its content is the
+ concatenation of the files with the same name under
+ <code>system/sepolicy/</code> and <code>BOARDS_SEPOLICY_DIRS</code>.</li>
+ <li>The <code>policy.conf</code> is sent to SELinux compiler for syntax
+ checking and compiled into binary format as <code>sepolicy</code> on the
+ device.
+ <figure>
+ <img src="images/n-selinux-policy-file.png"
+ alt="This image shows the files that generate the SELinux policy file
+ for Android 7.x.">
+ <figcaption><strong>Figure 2</strong>. SELinux policy file</figcaption>
+ </figure></li>
+</ul>
+
+<h3 id="selinux-files">SELinux files</h3>
+<p>
+After compiling, Android devices running 7.x and earlier typically contain the
+following SELinux-related files:
+</p>
+<ul>
+ <li><code>selinux_version</code></li>
+ <li><code>sepolicy: binary output after combining policy files (security_classes,
+ initial_sids, *.te, etc.)</code></li>
+ <li><code>file_contexts</code></li>
+ <li><code>property_contexts</code></li>
+ <li><code>seapp_contexts</code></li>
+ <li><code>service_contexts</code></li>
+ <li><code>system/etc/mac_permissions.xml</code></li>
+</ul>
+<p>
+For more details, see <a href="/security/selinux/implement">Implementing SELinux</a>.
+</p>
+<h3 id="android-n-init">SELinux initialization</h3>
+<p>
+When the system boots up, SELinux is in permissive mode (and not in enforcing
+mode). The init process performs the following tasks:
+</p>
+<ul>
+ <li>Loads <code>sepolicy</code> files from ramdisk into the kernel through
+ <code>/sys/fs/selinux/load</code>.</li>
+ <li>Switches SELinux to enforcing mode.</li>
+ <li>Re-exec()s itself to apply the SELinux domain rule to itself.</li>
+</ul>
+<p>
+To shorten the boot time, perform the <code>re-exec()</code> on the
+<code>init</code> process as soon as possible.
+</p>
+
+<h2 id="android-o">Android 8.0 and higher</h2>
+<p>
+In Android 8.0, SELinux policy is split into platform and vendor
+components to allow independent platform/vendor policy updates while
+maintaining compatibility.
+</p>
+<p>
+The platform sepolicy is further split into platform private and platform public
+parts to export specific types and attributes to vendor policy writers.
+The platform public types/attributes are guaranteed to be maintained as stable
+APIs for a given platform version. Compatibility with previous platform public
+types/attributes can be guaranteed for several versions using platform mapping
+files.
+</p>
+<h3 id="platform-public">Platform public sepolicy</h3>
+<p>
+The platform public sepolicy includes everything defined under
+<a href="https://android.googlesource.com/platform/system/sepolicy/+/master/public/" class="external">
+<code>system/sepolicy/public</code></a>. The platform can assume the types and
+attributes defined under public policy are stable APIs for a given platform
+version. This forms the part of the sepolicy that is exported by platform on
+which vendor (i.e. device) policy developers may write additional
+device-specific policy.
+</p>
+<p>
+Types are versioned according to the version of the policy that vendor
+files are written against, defined by the <code>PLATFORM_SEPOLICY_VERSION</code>
+build variable. The versioned public policy is then included with the
+vendor policy and (in its original form) in the platform policy. Thus,
+the final policy includes the private platform policy, the current platform's
+public sepolicy, the device-specific policy, and the versioned public policy
+corresponding to the platform version against which the device policy was
+written.
+</p>
+<h3 id="platform-private">Platform private sepolicy</h3>
+<p>
+The platform private sepolicy includes everything defined under
+<a href="https://android.googlesource.com/platform/system/sepolicy/+/master/private" class="external">
+<code>/system/sepolicy/private</code></a>. This part of the policy forms
+platform-only types, permissions, and attributes required for platform
+functionality. These are not exported to the <code>vendor/device</code> policy
+writers. Non-platform policy writers must not write their policy extensions
+based on types/attributes/rules defined in platform private sepolicy. Moreover,
+these rules are allowed to be modified or may disappear as part of a
+framework-only update.
+</p>
+<h3 id="platform-private-mapping">Platform private mapping</h3>
+<p>
+The platform private mapping includes policy statements that map the attributes
+exposed in platform public policy of the previous platform versions to the
+concrete types used in current platform public sepolicy. This ensures
+vendor policy that was written based on platform public attributes from
+the previous platform public sepolicy version(s) continues to work. The
+versioning is based on the <code>PLATFORM_SEPOLICY_VERSION</code> build variable
+set in AOSP for a given platform version. A separate mapping file exists for
+each previous platform version from which this platform is expected to accept
+vendor policy. For more details, see
+<a href="/security/selinux/compatibility">Compatibility</a>.
+</p>
+<h2 id="android-o-build">Building SELinux policy</h2>
+<p>
+SELinux policy in Android 8.0 is made by combining pieces from
+<code>/system</code> and <code>/vendor</code>. Logic for setting this up
+appropriately is in
+<a href="https://android.googlesource.com/platform/system/sepolicy/+/master/Android.mk" class="external">
+ <code>/platform/system/sepolicy/Android.mk</code></a>.
+</p>
+<p>
+Policy exists in the following locations:
+</p>
+<table>
+ <tr>
+ <th>Location</th>
+ <th>Contains</th>
+ </tr>
+ <tr>
+ <td><code>system/sepolicy/public</code></td>
+ <td>The platform's sepolicy API</td>
+ </tr>
+ <tr>
+ <td><code>system/sepolicy/private</code></td>
+ <td>Platform implementation details (vendors can ignore)</td>
+ </tr>
+ <tr>
+ <td><code>system/sepolicy/vendor</code></td>
+ <td>Policy and context files that vendors can use (vendors can ignore if desired)</td>
+ </tr>
+ <tr>
+ <td><code>BOARD_SEPOLICY_DIRS</code></td>
+ <td>Vendor sepolicy</td>
+ </tr>
+</table>
+
+<p>
+The build system takes this policy and produces platform and vendor
+policy components on the system partition and vendor partition, respectively.
+Steps include:
+</p>
+<ol>
+ <li>Converting policies to the SELinux Common Intermediate Language (CIL)
+ format, specifically:
+ <ol>
+ <li>public platform policy</li>
+ <li>combined private + public policy</li>
+ <li>public + vendor and <code>BOARD_SEPOLICY_DIRS</code> policy</li>
+ </ol>
+ </li>
+ <li>Versioning the policy provided by public as part of the vendor policy.
+ Done by using the produced public CIL policy to inform the combined public +
+ vendor + <code>BOARD_SEPOLICY_DIRS</code> policy as to which parts must be
+ turned into attributes that will be linked to the platform policy.</li>
+ <li>Creating a mapping file linking the platform and vendor parts.
+ Initially, this just links the types from the public policy with the
+ corresponding attributes in the vendor policy; later it will also provide
+ the basis for the file maintained in future platform versions, enabling
+ compatibility with vendor policy targeting this platform version.</li>
+ <li>Combining policy files (describe both on-device and precompiled solutions).
+ <ol>
+ <li>Combine mapping, platform and vendor policy.</li>
+ <li>Compile output binary policy file.</li>
+ </ol>
+ </li>
+</ol>
+
+ </body>
+</html>
diff --git a/en/security/selinux/compatibility.html b/en/security/selinux/compatibility.html
new file mode 100644
index 0000000..8461e7c
--- /dev/null
+++ b/en/security/selinux/compatibility.html
@@ -0,0 +1,1072 @@
+<html devsite>
+ <head>
+ <title>Policy Compatibility</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ <body>
+ <!--
+ Copyright 2018 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
+
+ //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>
+This article describes how Android handles the policy compatibility issues
+with platform OTAs, where new platform SELinux settings may differ from old vendor
+SELinux settings.
+</p>
+<p>
+Treble-based SELinux policy design considers a binary distinction
+between <em>platform</em> and <em>vendor</em> policy; the scheme becomes
+more complicated if vendor partitions generate dependencies, such as
+<code>platform</code> < <code>vendor</code> < <code>oem</code>.
+</p>
+<p>
+In Android 8.0 and higher, SELinux global policy is divided into private and
+public components. Public components consist of the policy and associated
+infrastructure, which are guaranteed to be available for a platform version.
+This policy will be exposed to vendor policy writers to enable vendors to build
+a vendor policy file, which when combined with the platform-provided policy,
+results in a fully-functional policy for a device.
+</p>
+
+<ul>
+ <li>For versioning, the exported platform-public policy will be written as
+ <em>attributes</em>.</li>
+ <li>For ease of policy writing, exported types will be transformed into
+ <em>versioned attributes</em> as part of the policy build process. Public
+ types may also be used directly in labeling decisions provided by vendor
+ contexts files.</li>
+</ul>
+<p>
+<strong>Android maintains a mapping between exported concrete types in platform
+policy and the corresponding versioned attributes for each platform
+version</strong>. This ensures that when objects are labeled with a type, it
+does not break behavior guaranteed by the platform-public policy in a previous
+version. This mapping is maintained by keeping a mapping file up-to-date for
+<a href="https://android.googlesource.com/platform/system/sepolicy/+/master/prebuilts/api" class="external">
+each platform version</a>, which keeps attribute membership information for each
+type exported in public policy.
+</p>
+
+<h2 id="object-ownership-and-labeling">Object ownership and labeling</h2>
+<p>
+When customizing policy in Android 8.0 and higher, ownership must be clearly defined
+for each object to keep platform and vendor policy separate. For example, if
+the vendor labels <code>/dev/foo</code> and the platform then labels
+<code>/dev/foo</code> in a subsequent OTA, there will be undefined behavior. For
+SELinux, this manifests as a labeling collision. The device node can have only a
+single label which resolves to whichever label is applied last. As a result:
+</p>
+<ul>
+ <li>Processes that <em>need access</em> to the unsuccessfully applied label will
+ lose access to the resource.</li>
+ <li>Processes that <em>gain access</em> to the file may break because the wrong
+ device node was created.</li>
+</ul>
+<p>
+System properties also have potential for naming collisions that could result in
+undefined behavior on the system (as well as for SELinux labeling). Collisions
+between platform and vendor labels can occur for any object that has an SELinux
+label, including properties, services, processes, files, and sockets. To avoid
+these issues, clearly define ownership of these objects.
+</p>
+<p>
+In addition to label collisions, SELinux type/attribute names may also collide.
+A type/attribute name collision will always result in a policy compiler error.
+</p>
+<h3 id="type-attribute-namespacing">Type/attribute namespacing</h3>
+<p>
+SELinux does not allow multiple declarations of the same type/attribute. Policy
+with duplicate declarations will fail to compilation. To avoid type and
+attribute name collisions, all vendor declarations should be namespaced
+starting with <code>np_</code>.
+</p>
+
+
+<pre
+class="prettyprint">type foo, domain; → type np_foo, domain;</pre>
+
+<h3 id="system-property-and-process-labeling-ownership">System property and
+process labeling ownership</h3>
+<p>
+Avoiding labeling collisions is best solved using property namespaces. To
+easily identify platform properties and avoid name conflicts when renaming or
+adding exported-platform properties, ensure all vendor properties have their
+own prefixes:
+</p>
+<table>
+ <tr>
+ <th>Property type</th>
+ <th>Acceptable prefixes</th>
+ </tr>
+ <tr>
+ <td>read-writable</td>
+ <td><code>vendor.</code></td>
+ </tr>
+ <tr>
+ <td>read-only</td>
+ <td><code>ro.vendor.</code><br>
+ <code>ro.boot.</code><br>
+ <code>ro.hardware.</code>
+ </td>
+ </tr>
+ <tr>
+ <td>persistent</td>
+ <td><code>persist.vendor.</code></td>
+ </tr>
+</table>
+<p>
+Vendors can continue to use <code>ro.boot.*</code> (which comes from the kernel
+cmdline) and <code>ro.hardware.*</code> (an obvious hardware-related property).
+</p>
+<p>
+All the vendor services in init rc files should have <code>vendor.</code>
+for services in init rc files of non-system partitions. Similar rules are
+applied to the SELinux labels for the vendor properties (<code>vendor_</code>
+for the vendor properties).
+</p>
+<h3 id="file-ownership">File ownership</h3>
+<p>
+Preventing collisions for files is challenging because platform and vendor
+policy both commonly provide labels for all filesystems. Unlike type naming,
+namespacing of files is not practical since many of them are created by the
+kernel. To prevent these collisions, follow the naming guidance for filesystems
+in this section. For Android 8.0, these are recommendations without technical
+enforcement. In the future, these recommendations will be enforced by the
+<a href="/compatibility/vts/">Vendor Test Suite</a> (VTS).
+</p>
+<h4 id="system">System (/system)</h4>
+<p>
+Only the system image must provide labels for <code>/system</code> components
+through <code>file_contexts</code>, <code>service_contexts</code>, etc. If labels
+for <code>/system</code> components are added in <code>/vendor</code> policy, a
+framework-only OTA update may not be possible.
+</p>
+<h4 id="vendor">Vendor (/vendor)</h4>
+<p>
+The AOSP SELinux policy already labels parts of <code>vendor</code> partition
+the platform interacts with, which enables writing SELinux rules for platform
+processes to be able to talk and/or access parts of <code>vendor</code>
+partition. Examples:
+</p>
+<table>
+ <tr>
+ <th><code>/vendor</code> path</th>
+ <th>Platform-provided label</th>
+ <th>Platform processes depending on the label</th>
+ </tr>
+ <tr>
+ <td><code>/vendor(/.<strong>*</strong>)?</code>
+ </td>
+ <td><code>vendor_file</code>
+ </td>
+ <td>All HAL clients in framework, <code>ueventd</code>, etc.
+ </td>
+ </tr>
+ <tr>
+ <td><code>/vendor/framework(/.<strong>*</strong>)?</code>
+ </td>
+ <td><code>vendor_framework_file</code>
+ </td>
+ <td><code>dex2oat</code>, <code>appdomain</code>, etc.
+ </td>
+ </tr>
+ <tr>
+ <td><code>/vendor/app(/.<strong>*</strong>)?</code>
+ </td>
+ <td><code>vendor_app_file</code>
+ </td>
+ <td><code>dex2oat</code>, <code>installd</code>, <code>idmap</code>, etc.
+ </td>
+ </tr>
+ <tr>
+ <td><code>/vendor/overlay(/.<strong>*</strong>)</code>
+ </td>
+ <td><code>vendor_overlay_file</code>
+ </td>
+ <td><code>system_server</code>, <code>zygote</code>, <code>idmap</code>, etc.
+ </td>
+ </tr>
+</table>
+<aside class="note">
+ <strong>*</strong> For more examples, see
+<a href="https://android.googlesource.com/platform/system/sepolicy/+/master/private/file_contexts" class="external">
+ <code>system/sepolicy/private/file_contexts</code></a>.</aside>
+
+<p>
+As a result, specific rules must be followed (enforced through
+<code>neverallows</code>) when labelling additional files in <code>vendor</code>
+partition:
+</p>
+<ul>
+<li><code>vendor_file </code>must be the default label for all files in
+<code>vendor</code> partition. The platform policy requires this to access
+passthrough HAL implementations.</li>
+<li>All new <code>exec_types</code> added in <code>vendor</code> partition
+through vendor SEPolicy must have <code>vendor_file_type</code> attribute. This
+is enforced through neverallows.</li>
+<li>To avoid conflicts with future platform/framework updates, avoid labelling
+ files other than <code>exec_types</code> in <code>vendor</code> partition.</li>
+<li>All library dependencies for AOSP-identified same process HALs must be
+labelled as <code>same_process_hal_file.</code></li></ul>
+
+<h4 id="procfs">Procfs (/proc)</h4>
+<p>
+Files in <code>/proc</code> may be labeled using only the <code>genfscon</code>
+label. In Android 7.0, both the
+<a href="https://android.googlesource.com/platform/system/sepolicy/+/nougat-dr1-release/genfs_contexts" class="external">platform</a>
+and <a
+href="https://android.googlesource.com/device/google/marlin/+/nougat-dr1-release/sepolicy/genfs_contexts" class="external">vendor</a>
+policy used <code>genfscon</code> to label files in <code>procfs</code>.
+</p>
+<p>
+<strong>Recommendation:</strong> Only platform policy labels <code>/proc</code>.
+If <code>vendor</code> processes need access to files in <code>/proc</code> that
+are currently labeled with the default label (<code>proc</code>), vendor policy
+should not explicitly label them and should instead use the generic
+<code>proc</code> type to add rules for vendor domains. This allows the platform
+updates to accommodate future kernel interfaces exposed through
+<code>procfs</code> and label them explicitly as needed.
+</p>
+<h4 id="debugfs">Debugfs (/sys/kernel/debug)</h4>
+<p>
+<code>Debugfs</code> can be labeled in both <code>file_contexts</code> and
+<code>genfscon</code>. In Android 7.0, both platform and vendor label
+<code>debugfs</code>.
+</p>
+<p>
+<strong>Recommendation:</strong> In the short term, only vendor policy may label
+<code>debugfs</code>. In the long term, remove <code>debugfs</code>.
+</p>
+<h4 id="tracefs">Tracefs
+(/sys/kernel/debug/tracing)</h4>
+<p>
+<code>Tracefs</code> can be labeled in both <code>file_contexts</code> and
+<code>genfscon</code>. In Android 7.0, only the platform labels
+<code>tracefs</code>.
+</p>
+<p>
+<strong>Recommendation:</strong> Only platform may label <code>tracefs</code>.
+</p>
+<h4 id="sysfs">Sysfs (/sys)</h4>
+<p>
+Files in <code>/sys</code> may be labeled using both <code>file_contexts</code>
+and <code>genfscon</code>. In Android 7.0, both platform and vendor use
+<code>file_contexts</code> and <code>genfscon</code> to label files in
+<code>sysfs</code>.
+</p>
+<p>
+<strong>Recommendation:</strong> The platform may label <code>sysfs</code>
+nodes that are not device-specific. Otherwise, only vendor may label files.
+</p>
+<h4 id="tmpfs">tmpfs (/dev)</h4>
+<p>
+Files in <code>/dev</code> may be labeled in <code>file_contexts</code>. In
+Android 7.0, both platform and vendor label files here.
+</p>
+<p>
+<strong>Recommendation:</strong> Vendor may label only files in
+<code>/dev/vendor</code> (e.g., <code>/dev/vendor/foo</code>,
+<code>/dev/vendor/socket/bar</code>).
+</p>
+<h4 id="rootfs">Rootfs (/)</h4>
+<p>
+Files in <code>/</code> may be labeled in <code>file_contexts</code>. In Android
+7.0, both platform and vendor label files here.
+</p>
+<p>
+<strong>Recommendation:</strong> Only system may label files in <code>/</code>.
+</p>
+<h4 id="data-data">Data (/data)</h4>
+<p>
+Data is labeled through a combination of <code>file_contexts</code> and
+<code>seapp_contexts</code>.
+</p>
+<p>
+<strong>Recommendation:</strong> Disallow vendor labeling outside
+<code>/data/vendor</code>. Only platform may label other parts of
+<code>/data</code>.
+</p>
+
+<h2 id="compatibility-attributes">Compatibility attributes</h2>
+<p>
+SELinux policy is an interaction between source and target types for specific
+object classes and permissions. Every object (processes, files, etc.) affected
+by SELinux policy may have only one type, but that type may have multiple
+attributes.
+</p>
+<p>
+Policy is written mostly in terms of existing types:
+</p>
+
+
+<pre
+class="prettyprint">allow source_type target_type:target_class permission(s);</pre>
+<p>
+This works because the policy was written with knowledge of all types. However,
+if the vendor policy and platform policy use specific types, and the label of a
+specific object changes in only one of those policies, the other may contain
+policy that gained or lost access previously relied upon. For example:
+</p>
+
+
+<pre class="prettyprint">File_contexts:
+/sys/A u:object_r:sysfs:s0
+Platform: allow p_domain sysfs:class perm;
+Vendor: allow v_domain sysfs:class perm;</pre>
+<p>
+Could be changed to:
+</p>
+
+
+<pre class="prettyprint">File_contexts:
+/sys/A u:object_r:sysfs_A:s0</pre>
+<p>
+Although the vendor policy would remain the same, the <code>v_domain</code>
+would lose access due to the lack of policy for the new <code>sysfs_A</code>
+type.
+</p>
+<p>
+By defining a policy in terms of attributes, we can give the underlying object a
+type that has an attribute corresponding to policy for both the platform and
+vendor code. This can be done for all types to effectively create an
+<em>attribute-policy</em> wherein concrete types are never used. In practice,
+this is required only for the portions of policy that overlap between platform
+and vendor, which are defined and provided as <em>platform public policy</em>
+that gets built as part of the vendor policy.
+</p>
+<p>
+Defining public policy as versioned attributes satisfies two policy
+compatibility goals:
+</p>
+<ul>
+ <li><strong>Ensure vendor code continues to work after platform update</strong>.
+ Achieved by adding attributes to concrete types for objects corresponding to
+ those on which vendor code relied, preserving access.</li>
+ <li><strong>Ability to deprecate policy</strong>. Achieved by clearly
+ delineating policy sets into attributes that can be removed as soon as the
+ version to which they correspond no longer is supported. Development can
+ continue in the platform, knowing the old policy is still present in the
+ vendor policy and will be automatically removed when/if it upgrades.</li>
+</ul>
+
+<h3 id="policy-writability">Policy writability</h3>
+<p>
+To meet the goal of not requiring knowledge of specific version changes for
+policy development, Android 8.0 includes a mapping between platform-public
+policy types and their attributes. Type <code>foo</code> is mapped
+to attribute <code>foo_v<em>N</em></code>, where <code><em>N</em></code> is the
+version targeted. <code>vN</code> corresponds to the
+<code>PLATFORM_SEPOLICY_VERSION</code> build variable and is of the form
+<code>MM.NN</code>, where <code>MM</code> corresponds to the platform SDK number
+and <code>NN</code> is a platform sepolicy specific version.
+</p>
+<p>
+Attributes in public policy are not versioned, but rather exist as an API on
+which platform and vendor policy can build to keep the interface between the two
+partitions stable. Both platform and vendor policy writers can continue to write
+policy as it is written today.
+</p>
+<p>
+Platform-public policy exported as <code>allow source_foo target_bar:<em>class
+perm</em>;</code>is included as part of the vendor policy. During
+<a href="/security/selinux/build">compilation</a> (which includes the
+corresponding version) it is transformed into the policy that will go to the
+vendor portion of the device (shown in the transformed Common Intermediate
+Language (CIL)):
+</p>
+<pre
+class="prettyprint"> (allow source_foo_vN target_bar_vN (class (perm)))</pre>
+<p>
+As vendor policy is never ahead of the platform, it should not be concerned with
+prior versions. However, platform policy will need to know how far back vendor
+policy is, include attributes to its types, and set policy corresponding to
+versioned attributes.
+</p>
+
+<h3 id="policy-diffs">Policy diffs</h3>
+<p>
+Automatically creating attributes by adding <code>_v<em>N</em></code> to the end
+of each type does nothing without mapping of attributes to types across version
+diffs. Android maintains a mapping between versions for attributes and a
+mapping of types to those attributes. This is done in the aforementioned mapping
+files with statements, such as (CIL):
+</p>
+
+<pre class="prettyprint">(typeattributeset foo_vN (foo))</pre>
+
+<h4 id="platform-upgrades">Platform upgrades</h4>
+<p>
+The following section details scenarios for platform upgrades.
+</p>
+
+<h5 id="same-types">Same types</h5>
+<p>
+This scenario occurs when an object does not change labels in policy versions.
+This is the same for source and target types and can be seen with
+<code>/dev/binder</code>, which is labeled <code>binder_device</code> across all
+releases. It is represented in transformed policy as:
+</p>
+
+
+<pre class="prettyprint">binder_device_v1 … binder_device_vN</pre>
+<p>
+When upgrading from <code>v1</code> → <code>v2</code>, the platform policy must
+contain:
+</p>
+
+
+<pre
+class="prettyprint">type binder_device; -> (type binder_device) (in CIL)</pre>
+<p>
+In the v1 mapping file (CIL):
+</p>
+
+
+<pre
+class="prettyprint">(typeattributeset binder_device_v1 (binder_device))</pre>
+<p>
+In the v2 mapping file (CIL):
+</p>
+
+
+<pre
+class="prettyprint">(typeattributeset binder_device_v2 (binder_device))</pre>
+<p>
+In the v1 vendor policy (CIL):
+</p>
+
+
+<pre class="prettyprint">(typeattribute binder_device_v1)
+(allow binder_device_v1 …)</pre>
+<p>
+In the v2 vendor policy (CIL):
+</p>
+
+
+<pre class="prettyprint">(typeattribute binder_device_v2)
+(allow binder_device_v2 …)</pre>
+<h5 id="new-types">New types</h5>
+<p>
+This scenario occurs when the platform has added a new type, which can happen
+when adding new features or during policy hardening.
+</p>
+<ul>
+<li><strong>New feature</strong>. When the type is labeling an object that was
+previously non-existent (such as a new service process), the vendor code did not
+previously interact with it directly so no corresponding policy exists. The new
+attribute corresponding to the type does not have an attribute in the previous
+version, and so would not need an entry in the mapping file targeting that
+version.</li>
+<li><strong>Policy hardening</strong>. When the type represents policy
+hardening, the new type attribute must link back to a chain of attributes
+corresponding to the previous one (similar to the previous example changing
+<code>/sys/A</code> from <code>sysfs</code> to <code>sysfs_A</code>). Vendor
+code relies on a rule enabling access to <code>sysfs</code>, and needs
+to include that rule as an attribute of the new type.</li>
+</ul>
+
+<p>
+When upgrading from <code>v1</code> → <code>v2</code>, the platform policy must
+contain:
+</p>
+
+
+<pre
+class="prettyprint">type sysfs_A; -> (type sysfs_A) (in CIL)
+type sysfs; (type sysfs) (in CIL)</pre>
+<p>
+In the v1 mapping file (CIL):
+</p>
+
+
+<pre
+class="prettyprint">(typeattributeset sysfs_v1 (sysfs sysfs_A))</pre>
+<p>
+In the v2 mapping file (CIL):
+</p>
+
+
+<pre class="prettyprint">(typeattributeset sysfs_v2 (sysfs))
+(typeattributeset sysfs_A_v2 (sysfs_A))</pre>
+<p>
+In the v1 vendor policy (CIL):
+</p>
+
+
+<pre class="prettyprint">(typeattribute sysfs_v1)
+(allow … sysfs_v1 …)</pre>
+<p>
+In the v2 vendor policy (CIL):
+</p>
+
+
+<pre class="prettyprint">(typeattribute sysfs_A_v2)
+(allow … sysfs_A_v2 …)
+(typeattribute sysfs_v2)
+(allow … sysfs_v2 …)</pre>
+</li></ul>
+<h5 id="removed-types">Removed types</h5>
+<p>
+This (rare) scenario occurs when a type is removed, which can happen when the
+underlying object:
+</p>
+<ul>
+<li>Remains but gets a different label.</li>
+<li>Is removed by the platform.</li>
+</ul>
+<p>
+During policy loosening, a type is removed and the object labeled with that type
+is given a different, already-existing label. This represents a merging of
+attribute mappings: The vendor code must still be able to access the underlying
+object by the attribute it used to possess, but the rest of the system must now
+be able to access it with its new attribute.
+</p>
+<p>
+If the attribute to which it has been switched is new, then relabeling is the
+same as in the new type case, except that when an existing label is used, the
+addition of the old attribute new type would cause other objects also labeled
+with this type to be newly accessible. This is essentially what is done by the
+platform and is deemed to be an acceptable tradeoff to maintain
+compatibility.
+</p>
+
+
+<pre class="prettyprint">(typeattribute sysfs_v1)
+(allow … sysfs_v1 …)</pre>
+<p>
+<strong>Example Version 1: Collapsing types (removing sysfs_A)</strong>
+</p>
+<p>
+When upgrading from <code>v1</code> → <code>v2</code>, the platform policy must
+contain:
+</p>
+
+
+<pre
+class="prettyprint">type sysfs; (type sysfs) (in CIL)</pre>
+<p>
+In the v1 mapping file (CIL):
+</p>
+
+
+<pre class="prettyprint">(typeattributeset sysfs_v1 (sysfs))
+(type sysfs_A) # in case vendors used the sysfs_A label on objects
+(typeattributeset sysfs_A_v1 (sysfs sysfs_A))</pre>
+<p>
+In the v2 mapping file (CIL):
+</p>
+
+
+<pre class="prettyprint">(typeattributeset sysfs_v2 (sysfs))</pre>
+<p>
+In the v1 vendor policy (CIL):
+</p>
+
+
+<pre class="prettyprint">(typeattribute sysfs_A_v1)
+(allow … sysfs_A_v1 …)
+(typeattribute sysfs_v1)
+(allow … sysfs_v1 …)</pre>
+<p>
+In the v2 vendor policy (CIL):
+</p>
+
+
+<pre class="prettyprint">(typeattribute sysfs_v2)
+(allow … sysfs_v2 …)</pre>
+<p>
+<strong>Example Version 2: Removing completely (foo type)</strong>
+</p>
+<p>
+When upgrading from <code>v1</code> → <code>v2</code>, the platform policy must
+contain:
+</p>
+
+
+<pre
+class="prettyprint"># nothing - we got rid of the type</pre>
+<p>
+In the v1 mapping file (CIL):
+</p>
+
+
+<pre
+class="prettyprint">(type foo) #needed in case vendors used the foo label on objects
+(typeattributeset foo_v1 (foo))</pre>
+<p>
+In the v2 mapping file (CIL):
+</p>
+
+
+<pre
+class="prettyprint"># nothing - get rid of it</pre>
+<p>
+In the v1 vendor policy (CIL):
+</p>
+
+
+<pre class="prettyprint">(typeattribute foo_v1)
+(allow foo …)
+(typeattribute sysfs_v1)
+(allow sysfs_v1 …)</pre>
+<p>
+In the v2 vendor policy (CIL):
+</p>
+
+
+<pre class="prettyprint">(typeattribute sysfs_v2)
+(allow sysfs_v2 …)</pre>
+
+<h5 id="new-class-permissions">New class/permissions</h5>
+<p>
+This scenario occurs when a platform upgrade introduces new policy components
+that do not exist in previous versions. For example, when Android added the
+<code>servicemanager</code> object manager that created the add, find, and list
+permissions, vendor daemons wanting to register with the
+<code>servicemanager</code> needed permissions that were not
+available. In Android 8.0, only the platform policy may add new classes and
+permissions.
+</p>
+<p>
+To allow all domains that could have been created or extended by vendor policy
+to use the new class without obstruction, the platform policy needs to include a
+rule similar to:
+</p>
+
+
+<pre
+class="prettyprint">allow {domain -coredomain} *:new_class perm;</pre>
+<p>
+This may even require policy allowing access for all interface (public policy)
+types, to be sure vendor image gains access. If this results in unacceptable
+security policy (as it may have with the servicemanager changes), a vendor
+upgrade could potentially be forced.
+</p>
+<h5 id="removed-class-permissions">Removed class/permissions</h5>
+<p>
+This scenario occurs when an object manager is removed (such as the
+<code>ZygoteConnection</code> object manager) and should not cause issues. The
+object manager class and permissions could remain defined in policy until the
+vendor version no longer uses it. This is done by adding the definitions
+to the corresponding mapping file.
+</p>
+<h4 id="vendor-customization-for-new-relabeled-types">Vendor customization for
+new/relabeled types</h4>
+<p>
+New vendor types are at the core of vendor policy development as they are needed
+to describe new processes, binaries, devices, subsystems, and stored data. As
+such, it is imperative to allow the creation of vendor-defined types.
+</p>
+<p>
+As vendor policy is always the oldest on the device, there is no need to
+automatically convert all vendor types to attributes in policy. The platform
+does not rely on anything labeled in vendor policy because the platform has no
+knowledge of it; however, the platform will provide the attributes and public
+types it uses to interact with objects labeled with these types (such as
+<code>domain</code>, <code>sysfs_type</code>, etc.). For the platform to
+continue to interact correctly with these objects, the attributes and types
+must be appropriately applied and specific rules may need to be added to the
+customizable domains (such as <code>init</code>).
+</p>
+
+<h2 id="attributes-p">Attribute changes for Android 9</h2>
+<p>
+Devices upgrading to Android 9 can use the following attributes, but devices
+launching with Android 9 must not.
+</p>
+<h3 id="violator-attributes">Violator attributes</h3>
+<p>
+Android 9 includes these domain-related attributes:
+</p>
+<ul>
+<li><strong><code>data_between_core_and_vendor_violators</code></strong>.
+Attribute for all domains that violate the requirement of not sharing files by
+path between <code>vendor</code> and <code>coredomains</code>. Platform and
+vendor processes shouldn't use on-disk files to communicate (unstable ABI).
+Recommendation:
+<ul>
+ <li>Vendor code should use <code>/data/vendor</code>.</li>
+ <li>System should not use <code>/data/vendor</code>.</li>
+ </ul
+</li>
+<li><strong><code>system_executes_vendor_violators</code></strong>. Attribute
+for all system domains (except <code>init</code> and <code>shell domains</code>)
+that violate the requirement of not executing vendor binaries. Execution of
+vendor binaries has unstable API. Platform shouldn't execute vendor binaries
+directly. Recommendation:
+<ul>
+ <li>Such platform dependencies on vendor binaries must be behind HIDL HALs.
+ <p> <strong><em>OR</em></strong></p></li>
+ <li><code>coredomains</code> that need access to vendor binaries should be
+moved to the vendor partition and thus, stop being <code>coredomain</code>.</li>
+</ul>
+</li>
+</ul>
+
+<h3 id="untrusted-attributes">Untrusted attributes</h3>
+<p>
+Untrusted apps that host arbitrary code shouldn't have access to HwBinder
+services, except those considered sufficiently safe for access from such apps
+(see safe services below). The two main reasons for this are:
+</p>
+<ol>
+<li>HwBinder servers do not perform client authentication because HIDL currently
+does not expose caller UID information. Even if HIDL did expose such data, many
+HwBinder services either operate at a level below that of apps (such as, HALs) or
+must not rely on app identity for authorization. Thus, to be safe, the default
+assumption is that every HwBinder service treats all its clients as equally
+authorized to perform operations offered by the service.</li>
+<li>HAL servers (a subset of HwBinder services) contain code with higher
+incidence rate of security issues than <code>system/core</code> components and
+have access to the lower layers of the stack (all the way down to hardware) thus
+increasing opportunities for bypassing the Android security model.</li></ol>
+
+<h4 id="safe-services">Safe services</h4>
+<p>
+Safe services include:
+</p>
+<ul>
+<li><code>same_process_hwservice</code>. These services (by definition) run in
+the process of the client and thus have the same access as the client domain in
+which the process runs.</li>
+<li><code>coredomain_hwservice</code>. These services do not pose risks
+ associated with reason #2.</li>
+<li><code>hal_configstore_ISurfaceFlingerConfigs</code>. This service is
+ specifically designed for use by any domain.</li>
+<li><code>hal_graphics_allocator_hwservice</code>. These operations are also
+offered by <code>surfaceflinger</code> Binder service, which apps are permitted
+to access.</li>
+<li><code>hal_omx_hwservice</code>. This is a HwBinder version of the
+ <code>mediacodec</code> Binder service, which apps are permitted to access.</li>
+<li><code>hal_codec2_hwservice</code>. This is a newer version of
+<code>hal_omx_hwservice</code>.</li>
+</ul>
+
+<h4 id="useable-attributes">Useable attributes</h4>
+<p>
+All <code>hwservices</code> not considered safe have the attribute
+<code>untrusted_app_visible_hwservice</code>. The corresponding HAL servers have
+the attribute <code>untrusted_app_visible_halserver</code>. Devices launching
+with Android P MUST NOT use either <code>untrusted</code> attribute.
+</p>
+<p>
+Recommendation:
+</p>
+<ul>
+<li>Untrusted apps should instead talk to a system service that talks to the
+vendor HIDL HAL. For example, apps can talk to <code><a
+href="https://android.googlesource.com/platform/system/sepolicy/+/master/public/app.te#209"
+class="external">binderservicedomain</a></code>, then <code>mediaserver</code>
+(which is a <code>binderservicedomain</code>) in turn talks to the <code><a
+href="https://android.googlesource.com/platform/system/sepolicy/+/master/private/mediaserver.te#6"
+class="external">hal_graphics_allocator</a></code>.
+
+<p><strong><em>OR</em></strong></p></li>
+<li>Apps that need direct access to <code>vendor</code> HALs should have their
+own vendor-defined sepolicy domain.</li>
+</ul>
+
+<h3 id="file-attribute-tests">File attribute tests</h3>
+<p>
+Android 9 includes <a
+href="https://android.googlesource.com/platform/system/sepolicy/+/master/tests/sepolicy_tests.py"
+class="external">build time tests</a> that ensure all files in specific
+locations have the appropriate attributes (such as, all files in
+<code>sysfs</code> have the required <code>sysfs_type</code> attribute).
+</p>
+
+
+<h2 id="platform-public-policy">Platform-public policy</h2>
+<p>
+The platform-public policy is the core of conforming to the Android 8.0
+architecture model without simply maintaining the union of platform policies
+from v1 and v2. Vendors are exposed to a subset of platform policy that
+contains useable types and attributes and rules on those types and attributes
+which then becomes part of vendor policy (i.e.
+<code>vendor_sepolicy.cil</code>).
+</p>
+<p>
+Types and rules are automatically translated in the vendor-generated policy
+into <code>attribute_v<em>N</em></code> such that all platform-provided types
+are versioned attributes (however attributes are not versioned). The platform is
+responsible for mapping the concrete types it provides into the appropriate
+attributes to ensure that vendor policy continues to function and that the rules
+provided for a particular version are included. The combination of
+platform-public policy and vendor policy satisfies the Android 8.0 architecture
+model goal of allowing independent platform and vendor builds.
+</p>
+
+<h3 id="mapping-to-attribute-chains">Mapping to attribute chains</h3>
+<p>
+When using attributes to map to policy versions, a type maps to an attribute or
+multiple attributes, ensuring objects labeled with the type are accessible via
+attributes corresponding to their previous types.
+</p>
+<p>
+Maintaining a goal to hide version information from the policy writer means
+automatically generating the versioned attributes and assigning them to the
+appropriate types. In the common case of static types, this is straightforward:
+<code>type_foo</code> maps to <code>type_foo_v1</code>.
+</p>
+<p>
+For an object label change such as <code>sysfs</code> → <code>sysfs_A</code> or
+<code>mediaserver</code> → <code>audioserver</code>, creating this mapping is
+non-trivial (and is described in the examples above). Platform policy maintainers
+must determine how to create the mapping at transition points for objects, which
+requires understanding the relationship between objects and their assigned
+labels and determining when this occurs. For backwards compatibility, this
+complexity needs to be managed on the platform side, which is the only partition
+that may uprev.
+</p>
+<h3 id="version-uprevs">Version uprevs</h3>
+<p>
+For simplicity, the Android platform releases an sepolicy version when a new
+release branch is cut. As described above, the version number is contained in
+<code>PLATFORM_SEPOLICY_VERSION</code> and is of the form <code>MM.nn</code>,
+where <code>MM</code> corresponds to the SDK value and <code>nn</code> is a
+private value maintained in<code> /platform/system/sepolicy.</code> For
+example, <code>19.0</code> for Kitkat, <code>21.0</code> for Lollipop,
+<code>22.0</code> for Lollipop-MR1 <code>23.0</code> for Marshmallow,
+<code>24.0</code> for Nougat, <code>25.0</code> for Nougat-MR1,
+<code>26.0</code> for Oreo, <code>27.0</code> for Oreo-MR1, and
+<code>28.0</code> for Android P. Uprevs aren't always whole numbers. For
+example, if an MR bump to a versions necessitates an incompatible change in
+<code>system/sepolicy/public</code> but not an API bump, then that sepolicy
+version could be: <code>vN.1</code>. The version present in a development
+branch is a never-to-be-used-in-shipping-devices <code>10000.0</code>.
+</p>
+<p>
+Android may deprecate oldest version when upreving. For input on when to
+deprecate a version, Android may collect the number of devices with vendor
+policies running that Android version and still receiving major platform
+updates. If the number is less than a certain threshold, that version is
+deprecated.
+</p>
+<h3 id="performance-impact-of-multiple-attributes">Performance impact of
+multiple attributes</h3>
+<p>
+As described in <a
+href="https://github.com/SELinuxProject/cil/issues/9" class="external">https://github.com/SELinuxProject/cil/issues/9</a>,
+a large number of attributes assigned to a type result in performance issues in
+the event of a policy cache miss.
+</p>
+<p>
+This was confirmed to be an issue in Android, so <a
+href="http://marc.info/?l=selinux&m=149202161421482&w=2" class="external">changes
+were made</a> to Android 8.0 to remove attributes added to the policy by the
+policy compiler, as well as to remove unused attributes. These changes resolved
+performance regressions.
+</p>
+
+
+<h2 id="selinux-contexts-labeling">SELinux contexts labeling</h2>
+<p>To support the distinction between platform and vendor sepolicy,
+the system builds SELinux context files differently to keep them separate.
+</p>
+
+<h3 id="file-contexts">File contexts</h3>
+<p>
+Android 8.0 introduced the following changes for <code>file_contexts</code>:
+</p>
+<ul>
+ <li>To avoid additional compilation overhead on device during boot,
+ <code>file_contexts</code> cease to exist in the binary form. Instead, they
+ are readable, regular expression text file such as <code>{property,
+ service}_contexts</code> (as they were pre-7.0).</li>
+ <li>The <code>file_contexts</code> are split between two files:
+ <ul>
+ <li><code>plat_file_contexts</code>
+ <ul>
+ <li>Android platform <code>file_context</code> that has no
+ device-specific labels, except for labeling parts of
+ <code>/vendor</code> partition that must be labeled precisely to
+ ensure proper functioning of the sepolicy files.</li>
+ <li>Must reside in <code>system</code> partition at
+ <code>/system/etc/selinux/plat_file_contexts</code> on device and
+ be loaded by <code>init</code> at the start along with the
+ vendor <code>file_context</code>.</li>
+ </ul>
+ </li>
+ <li><code>vendor_file_contexts</code>
+ <ul>
+ <li>Device-specific <code>file_context</code> built by combining
+ <code>file_contexts</code> found in the directories pointed to by
+ <code>BOARD_SEPOLICY_DIRS</code> in the device's
+ <code>Boardconfig.mk</code> files.</li>
+ <li>Must be installed at
+ <code>/vendor/etc/selinux/vendor_file_contexts</code> in
+ <code>vendor</code> partition and be loaded by <code>init</code> at
+ the start along with the platform <code>file_context</code>.</li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+</ul>
+
+<h3 id="property-contexts">Property contexts</h3>
+<p>
+In Android 8.0, the <code>property_contexts</code> is split between two files:
+</p>
+<ul>
+ <li><code>plat_property_contexts</code>
+ <ul>
+ <li>Android platform <code>property_context</code> that has no
+ device-specific labels.</li>
+ <li>Must reside in <code>system</code> partition at
+ <code>/system/etc/selinux/plat_property_contexts</code> and be loaded
+ by <code>init</code> at the start along with the vendor
+ <code>property_contexts</code>.</li>
+ </ul>
+ </li>
+ <li><code>vendor_property_contexts</code>
+ <ul>
+ <li>Device-specific <code>property_context</code> built by combining
+ <code>property_contexts</code> found in the directories pointed to by
+ <code>BOARD_SEPOLICY_DIRS</code> in device's
+ <code>Boardconfig.mk</code> files.</li>
+ <li>Must reside in <code>vendor</code> partition at
+ <code>/vendor/etc/selinux/vendor_property_contexts</code> and be
+ loaded by <code>init</code> at the start along with the platform
+ <code>property_context</code></li>
+ </ul>
+ </li>
+</ul>
+
+<h3 id="service-contexts">Service contexts</h3>
+<p>
+In Android 8.0, the <code>service_contexts</code> is split between the following
+files:
+</p>
+<ul>
+ <li><code>plat_service_contexts</code>
+ <ul>
+ <li>Android platform-specific <code>service_context</code> for the
+ <code>servicemanager</code>. The <code>service_context</code> has no
+ device-specific labels.</li>
+ <li>Must reside in <code>system</code> partition at
+ <code>/system/etc/selinux/plat_service_contexts</code> and be loaded by
+ <code>servicemanager</code> at the start along with the vendor
+ <code>service_contexts</code>.</li>
+ </ul>
+ </li>
+ <li><code>vendor_service_contexts</code>
+ <ul>
+ <li>Device-specific <code>service_context</code> built by combining
+ <code>service_contexts</code> found in the directories pointed to by
+ <code>BOARD_SEPOLICY_DIRS</code> in the device's
+ <code>Boardconfig.mk</code> files.</li>
+ <li>Must reside in <code>vendor</code> partition at
+ <code>/vendor/etc/selinux/vendor_service_contexts</code> and be loaded
+ by <code>servicemanager</code> at the start along with the platform
+ <code>service_contexts</code>.</li>
+ <li>Although <code>servicemanager</code> looks for this file at boot time,
+ for a fully compliant <code>TREBLE</code> device, the
+ <code>vendor_service_contexts</code> MUST NOT exist. This is because
+ all interaction between <code>vendor</code> and <code>system</code>
+ processes MUST go through
+ <code>hwservicemanager</code>/<code>hwbinder</code>.</li>
+ </ul>
+ </li>
+ <li><code>plat_hwservice_contexts</code>
+ <ul>
+ <li>Android platform <code>hwservice_context</code> for
+ <code>hwservicemanager</code> that has no device-specific labels.</li>
+ <li>Must reside in <code>system</code> partition at
+ <code>/system/etc/selinux/plat_hwservice_contexts</code> and be loaded by
+ <code>hwservicemanager</code> at the start along with the
+ <code>vendor_hwservice_contexts</code>.</li>
+ </ul>
+ </li>
+ <li><code>vendor_hwservice_contexts</code>
+ <ul>
+ <li>Device-specific <code>hwservice_context</code> built by combining
+ <code>hwservice_contexts</code> found in the directories pointed to by
+ <code>BOARD_SEPOLICY_DIRS</code> in the device's
+ <code>Boardconfig.mk</code> files.</li>
+ <li>Must reside in <code>vendor</code> partition at
+ <code>/vendor/etc/selinux/vendor_hwservice_contexts</code> and be
+ loaded by <code>hwservicemanager</code> at the start along with the
+ <code>plat_service_contexts</code>.</li>
+ </ul>
+ </li>
+ <li><code>vndservice_contexts</code>
+ <ul>
+ <li>Device-specific <code>service_context</code> for the
+ <code>vndservicemanager</code> built by combining
+ <code>vndservice_contexts</code> found in the directories pointed to by
+ <code>BOARD_SEPOLICY_DIRS</code> in the device's
+ <code>Boardconfig.mk</code>.</li>
+ <li>This file must reside in <code>vendor</code> partition at
+ <code>/vendor/etc/selinux/vndservice_contexts</code> and be loaded by
+ <code>vndservicemanager</code> at the start.</li>
+ </ul>
+ </li>
+</ul>
+
+<h3 id="seapp-contexts">Seapp contexts</h3>
+<p>
+In Android 8.0, the <code>seapp_contexts</code> is split between two files:
+</p>
+<ul>
+ <li><code>plat_seapp_contexts</code>
+ <ul>
+ <li>Android platform <code>seapp_context</code> that has no device-specific
+ changes.</li>
+ <li>Must reside in <code>system</code> partition at
+ <code>/system/etc/selinux/plat_seapp_contexts.</code></li>
+ </ul>
+ </li>
+ <li><code>vendor_seapp_contexts</code>
+ <ul>
+ <li>Device-specific extension to platform <code>seapp_context</code> built
+ by combining <code>seapp_contexts</code> found in the directories
+ pointed to by <code>BOARD_SEPOLICY_DIRS</code> in the device's
+ <code>Boardconfig.mk</code> files.</li>
+ <li>Must reside in <code>vendor</code> partition at
+ <code>/vendor/etc/selinux/vendor_seapp_contexts</code>.</li>
+ </ul>
+ </li>
+</ul>
+
+<h3 id="mac-permissions">MAC permissions</h3>
+<p>
+In Android 8.0, the <code>mac_permissions.xml</code> is split between two files:
+</p>
+<ul>
+ <li>Platform <code>mac_permissions.xml</code>
+ <ul>
+ <li>Android platform <code>mac_permissions.xml</code> that has no
+ device-specific changes.</li>
+ <li>Must reside in <code>system</code> partition at
+ <code>/system/etc/selinux/.</code></li>
+ </ul>
+ </li>
+ <li>Non-Platform <code>mac_permissions.xml</code>
+ <ul>
+ <li>Device-specific extension to platform
+ <code>mac_permissions.xml</code> built from
+ <code>mac_permissions.xml</code> found in the directories pointed to by
+ <code>BOARD_SEPOLICY_DIRS</code> in the device's
+ <code>Boardconfig.mk</code> files.</li>
+ <li>Must reside in <code>vendor</code> partition at
+ <code>/vendor/etc/selinux/.</code></li>
+ </ul>
+ </li>
+</ul>
+
+
+ </body>
+</html>
diff --git a/en/security/selinux/concepts.html b/en/security/selinux/concepts.html
index 227a3c5..fc63220 100644
--- a/en/security/selinux/concepts.html
+++ b/en/security/selinux/concepts.html
@@ -23,35 +23,35 @@
-<p>Review this page to become familar with the concepts at play within SELinux.</p>
+<p>Review this page to become familiar with SELinux concepts.</p>
-<h2 id=mandatory_access_control>Mandatory access control</h2>
+<h2 id="mandatory_access_control">Mandatory access control</h2>
<p>Security Enhanced Linux (SELinux), is a mandatory access control (MAC) system
-for the Linux operating system. As a MAC system, it differs from Linux’s
-familiar discretionary access control (DAC) system. In a DAC system, a concept
+for the Linux operating system. As a MAC system, it differs from Linux’s
+familiar discretionary access control (DAC) system. In a DAC system, a concept
of ownership exists, whereby an owner of a particular resource controls access
-permissions associated with it. This is generally coarse-grained and subject
-to unintended privilege escalation. A MAC system, however, consults a central
+permissions associated with it. This is generally coarse-grained and subject
+to unintended privilege escalation. A MAC system, however, consults a central
authority for a decision on all access attempts.</p>
<p>SELinux has been implemented as part of the Linux Security Module (LSM)
framework, which recognizes various kernel objects, and sensitive actions
-performed on them. At the point at which each of these actions would be
+performed on them. At the point at which each of these actions would be
performed, an LSM hook function is called to determine whether or not the
action should be allowed based on the information for it stored in an opaque
security object. SELinux provides an implementation for these hooks and
management of these security objects, which combine with its own policy, to
determine the access decisions.</p>
-<p>In conjunction with other Android security measures, Android's access control
+<p>Along with other Android security measures, Android's access control
policy greatly limits the potential damage of compromised machines and
accounts. Using tools like Android's discretionary and mandatory access
controls gives you a structure to ensure your software runs only at the minimum
privilege level. This mitigates the effects of attacks and reduces the
likelihood of errant processes overwriting or even transmitting data.</p>
-<p>Starting in Android 4.3, SELinux provides a mandatory access control (MAC)
+<p>In Android 4.3 and higher, SELinux provides a mandatory access control (MAC)
umbrella over traditional discretionary access control (DAC) environments. For
instance, software must typically run as the root user account to write to raw
block devices. In a traditional DAC-based Linux environment, if the root user
@@ -61,55 +61,43 @@
way, the process cannot overwrite data and system settings outside of the
specific raw block device.</p>
-<p>See <a href="implement.html#use_cases">Use Cases</a> for more examples of threats and ways to address them with SELinux.</p>
+<p>See <a href="/security/selinux/implement.html#use_cases">Use Cases</a>
+for more examples of threats and ways to address them with SELinux.</p>
-<h2 id=enforcement_levels>Enforcement levels</h2>
+<h2 id="enforcement_levels">Enforcement levels</h2>
-<p>Become familiar with the following terms to understand how SELinux can be
-implemented to varying strengths.</p>
+<p>SELinux can be implemented in varying modes:</p>
<ul>
<li><em>Permissive</em> - SELinux security policy is not enforced, only logged.
- <li><em>Enforcing</em> - Security policy is enforced and logged. Failures appear as EPERM errors.
+ <li><em>Enforcing</em> - Security policy is enforced and logged. Failures
+ appear as EPERM errors.
</ul>
<p>This choice is binary and determines whether your policy takes action or merely
allows you to gather potential failures. Permissive is especially useful during
implementation.</p>
-<ul>
- <li><em>Unconfined</em> - A very light policy that prohibits certain tasks and provides a temporary
-stop-gap during development. Should not be used for anything outside of the
-Android Open Source Project (AOSP).
- <li><em>Confined</em> - A custom-written policy designed for the service. That policy should define
-precisely what is allowed.
-</ul>
+<h2 id="labels_rules_and_domains">Labels, rules, and domains</h2>
-<p>Unconfined policies are available to help implement SELinux in Android quickly.
-They are suitable for most root-level applications. But they should be
-converted to confined policies wherever possible over time to restrict each
-application to precisely the resources it needs.</p>
+<p>SELinux depends upon <em>labels</em> to match actions and policies. Labels
+determine what is allowed. Sockets, files, and processes all have labels in
+SELinux. SELinux decisions are based on labels assigned to these objects and
+the policy defining how they may interact.</p>
-<p>Ideally, your policy is both in enforcing mode and confined. Unconfined
-policies in enforcement mode can mask potential violations that would have been
-logged in permissive mode with a confined policy. Therefore, we strongly
-recommend that device implementers implement true confined policies.</p>
+<p>In SELinux, a label takes the form:
+<code>user:role:type:mls_level</code>, where the type is the primary component
+of the access decisions, which may be modified by the other sections components
+that make up the label. The objects are mapped to classes and the different
+types of access for each class are represented by permissions. </p>
-<h2 id=labels_rules_and_domains>Labels, rules and domains</h2>
-
-<p>SELinux depends upon <em>labels</em> to match actions and policies. Labels determine what is allowed. Sockets,
-files, and processes all have labels in SELinux. SELinux decisions are based
-fundamentally on labels assigned to these objects and the policy defining how
-they may interact. In SELinux, a label takes the form:
-user:role:type:mls_level, where the type is the primary component of the access
-decisions, which may be modified by the other sections components which make up
-the label. The objects are mapped to classes and the different types of access
-for each class are represented by permissions. </p>
-
-<p>The policy rules come in the form: allow <em>domains</em> <em>types</em>:<em>classes</em> <em>permissions</em>;, where:</p>
+<p>The policy rules come in the form:
+<code>allow <em>domains</em> <em>types</em>:<em>classes</em> <em>permissions</em>;</code>,
+where:</p>
<ul>
- <li><em>Domain</em> - A label for the process or set of processes. Also called a domain type as it is just a type for a process.
+ <li><em>Domain</em> - A label for the process or set of processes. Also
+ called a domain type as it is just a type for a process.
<li><em>Type</em> - A label for the object (e.g. file, socket) or set of objects.
<li><em>Class</em> - The kind of object (e.g. file, socket) being accessed.
<li><em>Permission</em> - The operation (e.g. read, write) being performed.
@@ -120,22 +108,37 @@
allow appdomain app_data_file:file rw_file_perms;
</pre>
-<p>This says that all application domains are allowed to read and write files labeled
-app_data_file. Note that this rule relies upon macros defined in the
-global_macros file, and other helpful macros can also be found in the te_macros
-file, both of which can be found in the <a href="https://android.googlesource.com/platform/system/sepolicy/">system/sepolicy</a> directory in the AOSP source tree. Macros are provided for common groupings of classes, permissions and
-rules, and should be used whenever possible to help reduce the likelihood of
-failures due to denials on related permissions.</p>
+<p>This says that all application domains are allowed to read and write files
+labeled <code>app_data_file</code>. Note that this rule relies upon macros
+defined in the <code>global_macros</code> file, and other helpful macros can
+also be found in the <code>te_macros</code> file. Macros are provided for
+common groupings of classes, permissions and rules, and should be used whenever
+possible to help reduce the likelihood of failures due to denials on related
+permissions. These macros files are located in the
+<a href="https://android.googlesource.com/platform/system/sepolicy/">system/sepolicy</a>
+directory. In Android 8.0 and higher, they are in the <code>public</code>
+subdirectory with other supported public sepolicy.</p>
-<p>In addition to individually listing domains or types in a rule, one can also refer to a set of domains or types via an <em>attribute</em>. An attribute is simply a name for a set of domains or types. Each domain or type can be associated with any number of attributes. When a rule is written that specifies an attribute name, that name is automatically expanded to the list of domains or types associated with the attribute. For example, the <em>domain</em> attribute is associated with all process domains, and the <em>file_type</em> attribute is associated with all file types.</p>
+<p>In addition to individually listing domains or types in a rule, one can also
+refer to a set of domains or types via an <em>attribute</em>. An attribute is
+simply a name for a set of domains or types. Each domain or type can be
+associated with any number of attributes. When a rule is written that specifies
+an attribute name, that name is automatically expanded to the list of domains or
+types associated with the attribute. For example, the <em>domain</em> attribute
+is associated with all process domains, and the <em>file_type</em> attribute is
+associated with all file types.</p>
<p>Use the syntax above to create avc rules that comprise the essence of an
-SELinux policy. A rule takes the form:
+SELinux policy. A rule takes the form:
<pre class="devsite-click-to-copy">
<var>RULE_VARIANT SOURCE_TYPES TARGET_TYPES</var> : <var>CLASSES PERMISSIONS</var>
</pre>
-<p>The rule indicates what should happen when a subject labeled with any of the <em>source_types</em> attempts an action corresponding to any of the <em>permissions</em> on an object with any of the class <em>classes</em> which has any of the <em>target_types</em> label. The most common example of one of these rules is an allow rule, e.g.:</p>
+<p>The rule indicates what should happen when a subject labeled with any of the
+<em>source_types</em> attempts an action corresponding to any of the
+<em>permissions</em> on an object with any of the class <em>classes</em> that
+has any of the <em>target_types</em> label. The most common example of one of
+these rules is an allow rule, such as:</p>
<pre class="devsite-click-to-copy">
allow domain null_device:chr_file { open };
@@ -143,35 +146,44 @@
<p>
-This rule allows a process with any <em>domain</em> associated with the ‘domain’ attribute to take the action described by the <em>permission</em> ‘open’ on an object of <em>class</em> ‘chr_file’ (character device file) that has the <em>target_type</em> label of ‘null_device.’ In practice, this rule may be extended to include other permissions: </p>
+This rule allows a process with any <em>domain</em> associated with the
+<code>domain</code> attribute to take the action described by the
+<em>permission</em> <code>open</code> on an object of <em>class</em>
+<code>chr_file</code> (character device file) that has the <em>target_type</em>
+label of <code>null_device</code>. In practice, this rule may be extended to
+include other permissions:</p>
<pre class="devsite-click-to-copy">
allow domain null_device:chr_file { getattr open read ioctl lock append write};
</pre>
-<p>When combined with the knowledge that ‘domain’ is an attribute assigned to
-all process domains and
-that null_device is the label for the character device /dev/null, this rule basically
-permits reading and writing to <code>/dev/null</code>.</p>
+<p>When combined with the knowledge that <code>domain</code> is an attribute
+assigned to all process domains and that <code>null_device</code> is the label
+for the character device <code>/dev/null</code>, this rule basically permits
+reading and writing to <code>/dev/null</code>.</p>
-<p>A <em>domain</em> generally corresponds to a process and will have a label associated with it.</p>
+<p>A <em>domain</em> generally corresponds to a process and has a label
+associated with it.</p>
<p>For example, a typical Android app is running in its own process and has the
-label of untrusted_app that grants it certain restricted permissions.</p>
+label of <code>untrusted_app</code> that grants it certain restricted permissions.</p>
<p>Platform apps built into the system run under a separate label and are granted
a distinct set of permissions. System UID apps that are part of the core Android
-system run under the system_app label for yet another set of privileges.</p>
+system run under the <code>system_app</code> label for yet another set of
+privileges.</p>
-<p>Access to the following generic labels should never be directly allowed to domains; instead, a more specific type should be created for the object or objects:</p>
+<p>Access to the following generic labels should never be directly allowed to
+domains; instead, a more specific type should be created for the object or
+objects:</p>
<ul>
- <li> socket_device
- <li> device
- <li> block_device
- <li> default_service
- <li> system_data_file
- <li> tmpfs
+ <li><code>socket_device</code></li>
+ <li><code>device</code></li>
+ <li><code>block_device</code></li>
+ <li><code>default_service</code></li>
+ <li><code>system_data_file</code></li>
+ <li><code>tmpfs</code></li>
</ul>
</body>
diff --git a/en/security/selinux/customize.html b/en/security/selinux/customize.html
index 47f287a..52f4b30 100644
--- a/en/security/selinux/customize.html
+++ b/en/security/selinux/customize.html
@@ -21,89 +21,100 @@
limitations under the License.
-->
-<p>After you've integrated this base level of functionality and thoroughly
-analyzed the results, you may add your own policy settings to cover your
-customizations to the Android operating system. Of course, these policies must
-still meet the <a href="/compatibility/index.html">Android Compatibility
-program</a> requirements and not remove the default SELinux settings.</p>
+<p>After you've integrated the base level of SELinux functionality and
+thoroughly analyzed the results, you may add your own policy settings to cover
+your customizations to the Android operating system. These policies must still
+meet the <a href="/compatibility/index.html">Android Compatibility program</a>
+requirements and must not remove the default SELinux settings.</p>
-<aside class="note"><strong>Note:</strong> For details on customizing SELinux
-in Android 8.0, see
-<a href="/security/selinux/images/SELinux_Treble.pdf">SELinux for Android
-8.0</a>.</aside>
-
-<p>Manufacturers should not remove existing security settings. Otherwise, they
+<p>Manufacturers should not remove existing SELinux policy. Otherwise, they
risk breaking the Android SELinux implementation and the applications it
governs. This includes third-party applications that will likely need to be
improved to be compliant and operational. Applications must require no
modification to continue functioning on SELinux-enabled devices.</p>
-<p>When embarking upon customizing SELinux, manufacturers should remember to:</p>
+<p>When embarking upon customizing SELinux, remember to:</p>
<ul>
- <li>Write SELinux policy for all new daemons
- <li>Use predefined domains whenever appropriate
- <li>Assign a domain to any process spawned as an <code>init</code> service
- <li>Become familiar with the macros before writing policy
- <li>Submit changes to core policy to AOSP
+ <li>Write SELinux policy for all new daemons</li>
+ <li>Use predefined domains whenever appropriate</li>
+ <li>Assign a domain to any process spawned as an <code>init</code> service</li>
+ <li>Become familiar with the macros before writing policy</li>
+ <li>Submit changes to core policy to AOSP</li>
</ul>
-<p>And not to:</p>
+<p>And remember not to:</p>
<ul>
- <li>Create incompatible policy
- <li>Allow end user policy customization
- <li>Allow MDM policy customizations
- <li>Scare users with policy violations
- <li>Add backdoors
+ <li>Create incompatible policy</li>
+ <li>Allow end user policy customization</li>
+ <li>Allow MDM policy customizations</li>
+ <li>Scare users with policy violations</li>
+ <li>Add backdoors</li>
</ul>
-<p>See the <em>Kernel Security Features</em> section of the <a href="/compatibility/android-cdd.pdf">Android Compatibility Definition document</a> for specific requirements.</p>
+<p>See the <em>Kernel Security Features</em> section of the
+<a href="/compatibility/android-cdd#9_7_kernel_security_features">Android
+Compatibility Definition document</a> for specific requirements.</p>
<p>SELinux uses a whitelist approach, meaning all access must be explicitly
allowed in policy in order to be granted. Since Android's default SELinux
-policy already supports the Android Open Source Project, OEMs are not required
-to modify SELinux settings in any way. If they do customize SELinux settings,
-they should take great care not to break existing applications. Here is how we
-recommend proceeding:</p>
+policy already supports the Android Open Source Project, you are not required
+to modify SELinux settings in any way. If you do customize SELinux settings,
+take great care not to break existing applications. To get started:</p>
<ol>
- <li>Use the <a href="https://android.googlesource.com/kernel/common/">latest Android kernel</a>.
- <li>Adopt the <a href="http://en.wikipedia.org/wiki/Principle_of_least_privilege">principle of least privilege</a>.
- <li>Address only your own additions to Android. The default policy works with the <a href="https://android.googlesource.com/">Android Open Source Project</a> codebase automatically.
- <li>Compartmentalize software components into modules that conduct singular tasks.
- <li>Create SELinux policies that isolate those tasks from unrelated functions.
- <li>Put those policies in *.te files (the extension for SELinux policy source
-files) within the <code>/device/manufacturer/device-name/sepolicy</code> directory and use
-<code>BOARD_SEPOLICY</code> variables to include them in your build.
- <li>Make new domains permissive initially. This is done by
-using a permissive declaration in the domain's .te file.
- <li>Analyze results and refine your domain definitions.
+ <li>Use the
+ <a href="https://android.googlesource.com/kernel/common/">latest Android
+ kernel</a>.</li>
+ <li>Adopt the
+ <a href="http://en.wikipedia.org/wiki/Principle_of_least_privilege">principle
+ of least privilege</a>.</li>
+ <li>Address only your own additions to Android. The default policy works with
+ the <a href="https://android.googlesource.com/">Android Open Source
+ Project</a> codebase automatically.</li>
+ <li>Compartmentalize software components into modules that conduct singular
+ tasks.</li>
+ <li>Create SELinux policies that isolate those tasks from unrelated
+ functions.</li>
+ <li>Put those policies in <code>*.te</code> files (the extension for SELinux
+ policy source files) within the
+ <code>/device/<var>manufacturer</var>/<var>device-name</var>/sepolicy</code>
+ directory and use <code>BOARD_SEPOLICY</code> variables to include them in
+ your build.</li>
+ <li>Make new domains permissive initially. This is done by using a permissive
+ declaration in the domain's <code>.te</code> file.</li>
+ <li>Analyze results and refine your domain definitions.</li>
<li>Remove the permissive declaration when no further denials appear in userdebug
-builds.
+ builds.</li>
</ol>
-<p>Once integrated, OEM Android development should include a step to ensure
-SELinux compatibility going forward. In an ideal software development process,
-SELinux policy changes only when the software model changes and not the actual
-implementation.</p>
+<p>After you've integrated your SELinux policy change, add a step to your
+development workflow to ensure SELinux compatibility going forward. In an ideal
+software development process, SELinux policy changes only when the software
+model changes and not the actual implementation.</p>
-<p>As device manufacturers begin to customize SELinux, they should first audit
-their additions to Android. If they've added a component that conducts a new
-function, the manufacturers will need to ensure the component meets the
-security policy applied by Android, as well as any associated policy crafted by
+<p>As you start customizing SELinux, first audit your additions to Android. If
+you've added a component that conducts a new function, ensure the component
+meets Android's security policy, as well as any associated policy crafted by
the OEM, before turning on enforcing mode.</p>
-<p>To prevent unnecessary issues, it is better to be overbroad and over-compatible
-than too restrictive and incompatible, which results in broken device
-functions. Conversely, if a manufacturer's changes will benefit others, it
-should supply the modifications to the default SELinux policy as a <a href="/setup/submit-patches.html">patch</a>. If the patch is applied to the default security policy, the manufacturer will no longer need to make this change with each new Android release.</p>
+<p>To prevent unnecessary issues, it is better to be overbroad and
+over-compatible than too restrictive and incompatible, which results in broken
+device functions. Conversely, if your changes will benefit others, you should
+submit the modifications to the default SELinux policy as a
+<a href="/setup/contribute/submit-patches.html">patch</a>. If the patch is
+applied to the default security policy, you won't need to make this change with
+each new Android release.</p>
-<h2 id=example_policy_statements>Example policy statements</h2>
+<h2 id="example_policy_statements">Example policy statements</h2>
-<p>First, note SELinux is based upon the <a href="https://www.gnu.org/software/m4/manual/index.html">M4</a> computer language and therefore supports a variety of macros to save time.</p>
+<p>SELinux is based upon the
+<a href="https://www.gnu.org/software/m4/manual/index.html" class="external">M4</a>
+computer language and therefore supports a variety of macros to save time.</p>
-<p>In the following example, all domains are granted access to read from or write to <code>/dev/null</code> and read from <code>/dev/zero</code>.</p>
+<p>In the following example, all domains are granted access to read from or
+write to <code>/dev/null</code> and read from <code>/dev/zero</code>.</p>
<pre class="devsite-click-to-copy">
# Allow read / write access to /dev/null
@@ -114,7 +125,8 @@
</pre>
-<p>This same statement can be written with SELinux <code>*_file_perms</code> macros (shorthand):</p>
+<p>This same statement can be written with SELinux <code>*_file_perms</code>
+macros (shorthand):</p>
<pre class="devsite-click-to-copy">
# Allow read / write access to /dev/null
@@ -124,7 +136,7 @@
allow domain zero_device:chr_file r_file_perms;
</pre>
-<h2 id=example_policy>Example policy</h2>
+<h2 id="example_policy">Example policy</h2>
<p>Here is a complete example policy for DHCP, which we examine below:</p>
@@ -161,39 +173,41 @@
<p>Let’s dissect the example:</p>
-<p>In the first line, the type declaration, the DHCP daemon inherits from the base
-security policy (<code>domain</code>). From the previous statement examples, we know DHCP can read from and write
-to <code>/dev/null</code>.</p>
+<p>In the first line, the type declaration, the DHCP daemon inherits from the
+base security policy (<code>domain</code>). From the previous statement
+examples, DHCP can read from and write to <code>/dev/null</code>.</p>
<p>In the second line, DHCP is identified as a permissive domain.</p>
-<p>In the <code>init_daemon_domain(dhcp)</code> line, the policy states DHCP is spawned from <code>init</code> and is allowed to communicate with it.</p>
+<p>In the <code>init_daemon_domain(dhcp)</code> line, the policy states DHCP is
+spawned from <code>init</code> and is allowed to communicate with it.</p>
-<p>In the <code>net_domain(dhcp)</code> line, the policy allows DHCP to use common network functionality from the <code>net</code> domain such as reading and writing TCP packets, communicating over sockets, and conducting DNS requests.</p>
+<p>In the <code>net_domain(dhcp)</code> line, the policy allows DHCP to use
+common network functionality from the <code>net</code> domain such as reading
+and writing TCP packets, communicating over sockets, and conducting DNS
+requests.</p>
-<p>In the line <code>allow dhcp proc_net:file write;</code>, the policy states DHCP can write to specific files in <code>/proc</code>. This line demonstrates SELinux’s fine-grained file labeling. It uses the <code>proc_net</code> label to limit write access to only the files under <code>/proc/sys/net</code>.</p>
+<p>In the line <code>allow dhcp proc_net:file write;</code>, the policy states
+DHCP can write to specific files in <code>/proc</code>. This line demonstrates
+SELinux’s fine-grained file labeling. It uses the <code>proc_net</code> label
+to limit write access to only the files under <code>/proc/sys/net</code>.</p>
-<p>The final block of the example starting with <code>allow dhcp netd:fd use;</code> depicts how applications may be allowed to interact with one another. The
-policy says DHCP and netd may communicate with one another via file
-descriptors, FIFO files, datagram sockets, and UNIX stream sockets. DHCP may
-only read to and write from the datagram sockets and UNIX stream sockets and
-not create or open them.</p>
+<p>The final block of the example starting with
+<code>allow dhcp netd:fd use;</code> depicts how applications may be allowed to
+interact with one another. The policy says DHCP and netd may communicate with
+one another via file descriptors, FIFO files, datagram sockets, and UNIX stream
+sockets. DHCP may only read to and write from the datagram sockets and UNIX
+stream sockets and not create or open them.</p>
-<h2 id=available_controls>Available controls</h2>
+<h2 id="available_controls">Available controls</h2>
<table>
<tr>
- <td>
-<p><strong>Class</strong></p>
-</td>
- <td>
-<p><strong>Permission</strong></p>
-</td>
+ <th>Class</th>
+ <th>Permission</th>
</tr>
<tr>
- <td>
-<p>file</p>
-</td>
+ <td>file</td>
<td>
<pre>
ioctl read write create getattr setattr lock relabelfrom relabelto append
@@ -201,18 +215,14 @@
</td>
</tr>
<tr>
- <td>
-<p>directory</p>
-</td>
+ <td>directory</td>
<td>
<pre>
add_name remove_name reparent search rmdir open audit_access execmod</pre>
</td>
</tr>
<tr>
- <td>
-<p>socket</p>
-</td>
+ <td>socket</td>
<td>
<pre>
ioctl read write create getattr setattr lock relabelfrom relabelto append bind
@@ -221,9 +231,7 @@
</td>
</tr>
<tr>
- <td>
-<p>filesystem</p>
-</td>
+ <td>filesystem</td>
<td>
<pre>
mount remount unmount getattr relabelfrom relabelto transition associate
@@ -231,9 +239,7 @@
</td>
</tr>
<tr>
- <td>
-<p>process</p>
- </td>
+ <td>process</td>
<td>
<pre>
fork transition sigchld sigkill sigstop signull signal ptrace getsched setsched
@@ -243,9 +249,7 @@
</td>
</tr>
<tr>
- <td>
-<p>security</p>
-</td>
+ <td>security</td>
<td>
<pre>
compute_av compute_create compute_member check_context load_policy
@@ -254,9 +258,7 @@
</td>
</tr>
<tr>
- <td>
-<p>capability</p>
-</td>
+ <td>capability</td>
<td>
<pre>
chown dac_override dac_read_search fowner fsetid kill setgid setuid setpcap
@@ -279,8 +281,8 @@
<h2 id=neverallow>neverallow rules</h2>
<p>SELinux <code>neverallow</code> rules prohibit behavior that should never occur.
-With <a href="/compatibility/index.html">compatibility</a> testing,
-SELinux <code>neverallow</code> rules are now enforced across partner devices.</p>
+With <a href="/compatibility/cts/">compatibility</a> testing,
+SELinux <code>neverallow</code> rules are now enforced across devices.</p>
<p>The following guidelines are intended to help manufacturers avoid errors
related to <code>neverallow</code> rules during customization. The rule numbers
@@ -303,5 +305,221 @@
<code>neverallow</code> rule is to move the offending code to the
<code>/system</code> partition.</p>
+<h2 id="android-o">Customizing SEPolicy in Android 8.0+</h2>
+<p>
+This section provides guidelines for vendor SELinux policy in Android 8.0 and
+higher, including details on Android Open Source Project (AOSP) SEPolicy and
+SEPolicy extensions. For more information about how SELinux policy is kept
+compatible across partitions and Android versions, see
+<a href="/security/selinux/compatibility">Compatibility</a>.
+</p>
+<h3 id="policy-placement">Policy placement</h3>
+<p>
+In Android 7.0 and earlier, device manufacturers could add policy to
+<code>BOARD_SEPOLICY_DIRS</code>, including policy meant to augment AOSP policy
+across different device types. In Android 8.0 and higher, adding a policy to
+<code>BOARD_SEPOLICY_DIRS</code> places the policy only in the vendor
+image.
+</p>
+<p>
+In Android 8.0 and higher, policy exists in the following locations in AOSP:
+</p>
+<ul>
+ <li><strong>system/sepolicy/public</strong>. Includes policy exported for use
+ in vendor-specific policy. Everything goes into the Android 8.0
+ <a href="/security/selinux/compatibility">compatibility infrastructure</a>.
+ Public policy is meant to persist across releases so you can include
+ anything <code>/public</code> in your customized policy. Because of this,
+ the type of policy that can be placed in <code>/public</code> is more
+ restricted. Consider this the platform's exported policy API: Anything that
+ deals with the interface between <code>/system</code> and
+ <code>/vendor</code> belongs here.</li>
+ <li><strong>system/sepolicy/private</strong>. Includes policy necessary for
+ the functioning of the system image, but of which vendor image policy should
+ have no knowledge.</li>
+ <li><strong>system/sepolicy/vendor</strong>. Includes policy for components that
+ go in <code>/vendor</code> but exist in the core platform tree (not
+ device-specific directories). This is an artifact of build system's
+ distinction between devices and global components; conceptually this is a
+ part of the device-specific policy described below.</li>
+ <li><strong>device/<var>manufacturer</var>/<var>device-name</var>/sepolicy</strong>.
+ Includes device-specific policy. Also includes device customizations to
+ policy, which in Android 8.0 and higher corresponds to policy for components
+ on the vendor image.</li>
+</ul>
+<h3 id="supported-policy-scenarios">Supported policy scenarios</h3>
+<p>
+On devices launching with Android 8.0 and higher, the vendor image must work
+with the OEM system image and the reference AOSP system image provided by Google
+(and pass CTS on this reference image). These requirements ensure a clean
+separation between the framework and the vendor code. Such devices support the
+following scenarios.
+</p>
+<h4 id="vendor-image-only-extensions">vendor-image-only extensions</h4>
+<p>
+<strong>Example</strong>: Adding a new service to <code>vndservicemanager</code>
+from the vendor image that supports processes from the vendor image.
+</p>
+<p>
+As with devices launching with previous Android versions, add device-specific
+customization in
+<code>device/<var>manufacturer</var>/<var>device-name</var>/sepolicy</code>.
+New policy governing how vendor components interact with (only) other vendor
+components <strong>should involve types present only in
+<code>device/<var>manufacturer</var>/<var>device-name</var>/sepolicy</code></strong>.
+Policy written here allows code on vendor to work, will not be updated as part
+of a framework-only OTA, and will be present in the combined policy on a device
+with the reference AOSP system image.
+
+<h4 id="vendor-image-support-to-work-with-aosp">vendor-image support to work
+with AOSP</h4>
+<p>
+<strong>Example</strong>: Adding a new process (registered with
+<code>hwservicemanager</code> from the vendor image) that implements an
+AOSP-defined HAL.
+</p>
+<p>
+As with devices launching with previous Android versions, perform
+device-specific customization in
+<code>device/<var>manufacturer</var>/<var>device-name</var>/sepolicy</code>.
+The policy exported as part of <code>system/sepolicy/public/</code> is available
+for use, and is shipped as part of the vendor policy. Types and attributes from
+the public policy may be used in new rules dictating interactions with the new
+vendor-specific bits, subject to the provided <code>neverallow</code>
+restrictions. As with the vendor-only case, new policy here will not be updated
+as part of a framework-only OTA and will be present in the combined policy on a
+device with the reference AOSP system image.
+</p>
+<h4 id="system-image-only-extensions">system-image-only extensions</h4>
+<p>
+<strong>Example</strong>: Adding a new service (registered with servicemanager)
+that is accessed only by other processes from the system image.
+</p>
+<p>
+Add this policy to <code>system/sepolicy/private</code>. You can add extra
+processes or objects to enable functionality in a partner system image, provided
+those new bits don't need to interact with new components on the vendor image
+(specifically, such processes or objects must fully function without policy from
+the vendor image). The policy exported by <code>system/sepolicy/public</code> is
+available here just as it is for vendor-image-only extensions. This policy is
+part of the system image and could be updated in a framework-only OTA, but will
+not be present when using the reference AOSP system image.
+</p>
+<h4
+id="vendor-image-extensions-that-serve-extended-aosp-components">vendor-image
+extensions that serve extended AOSP components</h4>
+<p>
+<strong>Example:</strong> A new, non-AOSP HAL for use by extended clients that
+also exist in the AOSP system image (such as an extended system_server).
+</p>
+<p>
+Policy for interaction between system and vendor must be included in the
+<code>device/<var>manufacturer</var>/<var>device-name</var>/sepolicy</code>
+directory shipped on the vendor partition.
+This is similar to the above scenario of adding vendor-image support to work
+with the reference AOSP image, except the modified AOSP components may also
+require additional policy to properly operate with the rest of the system
+partition (which is fine as long as they still have the public AOSP type
+labels).
+</p>
+<p>
+Policy for interaction of public AOSP components with system-image-only
+extensions should be in <code>system/sepolicy/private</code>.
+</p>
+
+<h4 id="system-image-extensions-that-access-only-AOSP-interfaces">system-image
+extensions that access only AOSP interfaces</h4>
+<p>
+<strong>Example:</strong> A new, non-AOSP system process must access a HAL on
+which AOSP relies.
+</p>
+<p>
+This is similar to the <a href="#system-image-only-extensions">system-image-only
+extension example</a>, except new system components may interact across the
+<code>system/vendor</code> interface. Policy for the new system component must
+go in <code>system/sepolicy/private</code>, which is acceptable provided it is
+through an interface already established by AOSP in
+<code>system/sepolicy/public</code> (i.e. the types and attributes required for
+functionality are there). While policy could be included in the device-specific
+policy, it would be unable to use other <code>system/sepolicy/private</code>
+types or change (in any policy-affecting way) as a result of a framework-only
+update. The policy may be changed in a framework-only OTA, but will not be
+present when using an AOSP system image (which won't have the new system
+component either).
+</p>
+<h4 id="vendor-image-extensions-that-serve-new-system-components">vendor-image
+extensions that serve new system components</h4>
+<p>
+<strong>Example:</strong> Adding a new, non-AOSP HAL for use by a client process
+without an AOSP analogue (and thus requires its own domain).
+</p>
+<p>
+Similar to the <a
+href="#vendor-image-extensions-that-serve-extended-aosp-components">AOSP-extensions
+example</a>, policy for interactions between system and vendor must go in the
+<code>device/<var>manufacturer</var>/<var>device-name</var>/sepolicy</code>
+directory shipped on the vendor partition
+(to ensure the system policy has no knowledge of vendor-specific details). You
+can add new public types that extend the policy in
+<code>system/sepolicy/public</code>; this should be done only in addition to the
+existing AOSP policy, i.e. do not remove AOSP public policy. The new public
+types can then be used for policy in <code>system/sepolicy/private</code> and in
+<code>device/<var>manufacturer</var>/<var>device-name</var>/sepolicy</code>.
+</p>
+<p>
+Keep in mind that every addition to <code>system/sepolicy/public</code> adds
+complexity by exposing a new compatibility guarantee that must be tracked in a
+mapping file and which is subject to other restrictions. Only new types and
+corresponding allow rules may be added in <code>system/sepolicy/public</code>;
+attributes and other policy statements are not supported. In addition, new
+public types cannot be used to directly label objects in the
+<code>/vendor</code> policy.
+</p>
+<h3 id="unsupported-policy-scenarios">Unsupported policy scenarios</h3>
+<p>
+Devices launching with Android 8.0 and higher do not support the following
+policy scenario and examples.
+</p>
+<h4
+id="additional-extensions-to-system-image-that-need-permission-to-new-vendor-image-components-after-a-framework-only-ota">Additional
+extensions to system-image that need permission
+to new vendor-image components
+after a framework-only OTA</h4>
+<p>
+<strong>Example: </strong>A new non-AOSP system process, requiring its own
+domain, is added in the next Android release and needs access to a new,
+non-AOSP HAL.
+</p>
+<p>
+Similar to
+<a href="#vendor-image-extensions-that-serve-extended-aosp-components">new
+(non-AOSP) system and vendor components</a> interaction, except the new system
+type is introduced in a
+framework-only OTA. Although the new type could be added to the policy in
+<code>system/sepolicy/public</code>, the existing vendor policy has no knowledge
+of the new type as it is tracking only the Android 8.0 system public policy.
+AOSP handles this by exposing vendor-provided resources via an attribute (e.g.
+<code>hal_foo</code> attribute) but as attribute partner extensions are not
+supported in <code>system/sepolicy/public</code>, this method is unavailable to
+vendor policy. Access must be provided by a previously-existing public type.
+</p>
+<p>
+<strong>Example: </strong>A change to a system process (AOSP or non-AOSP) must
+change how it interacts with new, non-AOSP vendor component.
+</p>
+<p>
+The policy on the system image must be written without knowledge of specific
+vendor customizations. Policy concerning specific interfaces in AOSP is thus
+exposed via attributes in system/sepolicy/public so that vendor policy can
+opt-in to future system policy which uses these attributes. However,
+<strong>attribute extensions in <code>system/sepolicy/public</code> are not
+supported</strong>, so all policy dictating how the system components interact
+with new vendor components (and which is not handled by attributes already
+present in AOSP <code>system/sepolicy/public</code>) must be in
+<code>device/<var>manufacturer</var>/<var>device-name</var>/sepolicy</code>.
+This means that system types cannot change
+the access allowed to vendor types as part of a framework-only OTA.</p>
+
+
</body>
</html>
diff --git a/en/security/selinux/device-policy.html b/en/security/selinux/device-policy.html
index adfd629..0d8088e 100644
--- a/en/security/selinux/device-policy.html
+++ b/en/security/selinux/device-policy.html
@@ -29,35 +29,30 @@
these device-specific customizations, how to write device-specific policy, and
some of the pitfalls to avoid along the way.</p>
-<aside class="note"><strong>Note:</strong> For details on writing SELinux policy
-in Android 8.0, see
-<a href="/security/selinux/images/SELinux_Treble.pdf">SELinux for Android
-8.0</a>.</aside>
+<h2 id="device_bringup">Device bringup</h2>
-<h2 id=device_bringup>Device bringup</h2>
+<p>While writing device-specific policy, follow these steps.</p>
-<p>While writing device-specific policy, progress through the following steps in
-order.</p>
-
-<h3 id=run_in_permissive_mode>Run in permissive mode</h3>
+<h3 id="run_in_permissive_mode">Run in permissive mode</h3>
-<p>When a device is in <a href="index.html#background">permissive mode</a>,
+<p>When a device is in
+<a href="/security/selinux/concepts#enforcement_levels">permissive mode</a>,
denials are logged but not enforced. Permissive mode is important for two
reasons:</p>
-<ol>
- <li> Permissive mode ensures that policy bringup does not delay other early device
- bringup tasks.
- <li> An enforced denial may mask other denials. For example, file access
- typically entails a directory search, file open, then file read. In
- enforcing mode, only the directory search denial would occur. Permissive
- mode ensures all denials are seen.
-</ol>
+<ul>
+ <li>Permissive mode ensures that policy bringup does not delay other early
+ device bringup tasks.</li>
+ <li>An enforced denial may mask other denials. For example, file access
+ typically entails a directory search, file open, then file read. In
+ enforcing mode, only the directory search denial would occur. Permissive
+ mode ensures all denials are seen.</li>
+</ul>
-<p>The simplest way to put a device into permissive mode is via the
-<a href="validate.html#switching_to_permissive">kernel command line</a>. This
-can be added to the device’s BoardConfig.mk file:
+<p>The simplest way to put a device into permissive mode is using the
+<a href="/security/selinux/validate.html#switching_to_permissive">kernel command
+line</a>. This can be added to the device’s <code>BoardConfig.mk</code> file:
<code>platform/device/<vendor>/<target>/BoardConfig.mk</code>.
After modifying the command line, perform <code>make clean</code>, then
<code>make bootimage</code>, and flash the new boot image.</p>
@@ -69,27 +64,27 @@
</pre>
-<p>Two weeks is a reasonable amount of time to be in global permissive mode. After
-addressing the majority of denials, move back into enforcing mode and address
-bugs as they come in. Domains still producing denials or services still under
-heavy development can be temporarily put into permissive mode, but move them
-back to enforcing mode as soon as possible.</p>
+<p>Two weeks is a reasonable amount of time to be in global permissive mode.
+After addressing the majority of denials, move back into enforcing mode and
+address bugs as they come in. Domains still producing denials or services still
+under heavy development can be temporarily put into permissive mode, but move
+them back to enforcing mode as soon as possible.</p>
-<h3 id=enforce_early>Enforce early</h3>
+<h3 id="enforce_early">Enforce early</h3>
-<p>In enforcing mode, denials are both logged and enforced. It is a best practice
-to get your device into enforcing mode as early as possible. Waiting to create
-and enforce device-specific policy often results in a buggy product and a bad
-user experience. Start early enough to participate in
-<a href="https://en.wikipedia.org/wiki/Eating_your_own_dog_food">dogfooding</a>
+<p>In enforcing mode, denials are both logged and enforced. It is a best
+practice to get your device into enforcing mode as early as possible. Waiting to
+create and enforce device-specific policy often results in a buggy product and a
+bad user experience. Start early enough to participate in
+<a href="https://en.wikipedia.org/wiki/Eating_your_own_dog_food" class="external">dogfooding</a>
and ensure full test coverage of functionality in real world usage. Starting
early ensures security concerns inform design decisions. Conversely, granting
permissions based solely on observed denials is an unsafe approach. Use this
time to perform a security audit of the device and file bugs against behavior
that should not be allowed.</p>
-<h3 id=remove_or_delete_existing_policy>Remove or delete existing policy</h3>
+<h3 id="remove_or_delete_existing_policy">Remove or delete existing policy</h3>
<p>There are a number of good reasons to create device-specific policy from
@@ -102,7 +97,7 @@
<li> Dead policy
</ul>
-<h3 id=address_denials_of_core_services>Address denials of core services</h3>
+<h3 id="address_denials_of_core_services">Address denials of core services</h3>
<p>Denials generated by core services are typically addressed by file labeling.
@@ -121,10 +116,11 @@
<p>is completely addressed by properly labeling <code>/dev/kgsl-3d0</code>. In
this example, <code>tcontext</code> is <code>device</code>. This represents a
default context where everything in <code>/dev</code> receives the
-“<a href="https://android.googlesource.com/platform/external/sepolicy/+/marshmallow-dev/file_contexts#31">
+“<a href="https://android.googlesource.com/platform/external/sepolicy/+/marshmallow-dev/file_contexts#31" class="external">
device</a>” label unless a more specific label is assigned. Simply accepting
-the output from <a href="validate.html#using_audit2allow">audit2allow</a> here
-would result in an incorrect and overly permissive rule.</p>
+the output from
+<a href="/security/selinux/validate.html#using_audit2allow">audit2allow</a>
+here would result in an incorrect and overly permissive rule.</p>
<p>To solve this kind of problem, give the file a more specific label, which in
this case is
@@ -137,36 +133,39 @@
<p>Other device-specific files that should be labeled with types predefined in
core policy:</p>
-<ol>
- <li> <a href="https://android.googlesource.com/device/lge/hammerhead/+/marshmallow-dev/sepolicy/file_contexts#31">
- block devices</a>
- <li> <a href="https://android.googlesource.com/device/lge/hammerhead/+/marshmallow-dev/sepolicy/file_contexts#80">
- audio devices</a>
- <li> <a href="https://android.googlesource.com/device/lge/hammerhead/+/marshmallow-dev/sepolicy/file_contexts#21">
- video devices</a>
- <li> <a href="https://android.googlesource.com/device/lge/hammerhead/+/marshmallow-dev/sepolicy/file_contexts#89">
- sensors</a>
- <li> <a href="https://android.googlesource.com/device/lge/hammerhead/+/marshmallow-dev/sepolicy/file_contexts#8">
- nfc</a>
- <li> gps_device
- <li> <a href="https://android.googlesource.com/device/lge/hammerhead/+/marshmallow-dev/sepolicy/file_contexts#139">
- files in /sys</a>
- <li> files in /proc
-</ol>
+<ul>
+ <li><a href="https://android.googlesource.com/device/lge/hammerhead/+/marshmallow-dev/sepolicy/file_contexts#31" class="external">
+ block devices</a></li>
+ <li><a href="https://android.googlesource.com/device/lge/hammerhead/+/marshmallow-dev/sepolicy/file_contexts#80" class="external">
+ audio devices</a></li>
+ <li><a href="https://android.googlesource.com/device/lge/hammerhead/+/marshmallow-dev/sepolicy/file_contexts#21" class="external">
+ video devices</a></li>
+ <li><a href="https://android.googlesource.com/device/lge/hammerhead/+/marshmallow-dev/sepolicy/file_contexts#89" class="external">
+ sensors</a></li>
+ <li><a href="https://android.googlesource.com/device/lge/hammerhead/+/marshmallow-dev/sepolicy/file_contexts#8" class="external">
+ nfc</a></li>
+ <li>gps_device</li>
+ <li><a href="https://android.googlesource.com/device/lge/hammerhead/+/marshmallow-dev/sepolicy/file_contexts#139" class="external">
+ files in /sys</a></li>
+ <li>files in /proc</li>
+</ul>
<p>In general, granting permissions to default labels is wrong. Many of these
-permissions are disallowed by <a href="customize.html#neverallow">neverallow</a>
-rules, but even when not explicitly disallowed, best practice is to provide a
-specific label.</p>
+permissions are disallowed by
+<a href="/security/selinux/customize.html#neverallow">neverallow</a> rules, but
+even when not explicitly disallowed, best practice is to provide a specific
+label.</p>
-<h3 id=label_new_services_and_address_denials>Label new services and address denials</h3>
+<h3 id="label_new_services_and_address_denials">Label new services and address
+denials</h3>
<p>Init-launched services are required to run in their own SELinux domains. The
following example puts service “foo” into its own SELinux domain and grants it
permissions.</p>
-<p>The service is launched in our device’s <code>init.<target>.rc</code> file as:</p>
+<p>The service is launched in our device’s
+<code>init.<var>device</var>.rc</code> file as:</p>
<pre class="devsite-click-to-copy">
service foo /system/bin/foo
@@ -176,7 +175,8 @@
<ol>
<li>Create a new domain "foo"<br />
- <p>Create the file <code>device/<oem>/<target>/sepolicy/foo.te</code>
+ <p>Create the file
+ <code>device/<var>manufacturer</var>/<var>device-name</var>/sepolicy/foo.te</code>
with the following contents:</p>
<pre class="devsite-click-to-copy">
@@ -187,15 +187,14 @@
init_daemon_domain(foo)
</pre>
-
<p>This is the initial template for the foo SELinux domain, to which you
can add rules based on the specific operations performed by that executable.</p>
</li>
<li>Label <code>/system/bin/foo</code><br />
- <p>Add the following to <code>device/<oem>/<target>/sepolicy/
- file_contexts</code>:</p>
+ <p>Add the following to
+ <code>device/<var>manufacturer</var>/<var>device-name</var>/sepolicy/file_contexts</code>:</p>
<pre class="devsite-click-to-copy">
/system/bin/foo u:object_r:foo_exec:s0
@@ -211,25 +210,25 @@
<li>Refine the SELinux rules for the domain.<br />
<p>Use denials to determine the required permissions. The
- <a href="validate.html#using_audit2allow">audit2allow</a> tool provides
- good guidelines, but only use it to inform policy writing. Do
- not just copy the output.</p>
+ <a href="/security/selinux/validate.html#using_audit2allow">audit2allow</a>
+ tool provides good guidelines, but only use it to inform policy
+ writing. Do not just copy the output.</p>
</li>
</ol>
-<h3 id=enforcing_mode>Switch back to enforcing mode</h3>
+<h3 id="enforcing_mode">Switch back to enforcing mode</h3>
<p>It’s fine to troubleshoot in permissive mode, but switch back to enforcing
mode as early as possible and try to remain there.</p>
-<h2 id=common_mistakes>Common mistakes</h2>
+<h2 id="common_mistakes">Common mistakes</h2>
<p>Here are a few solutions for common mistakes that happen when writing
device-specific policies.</p>
-<h3 id=overuse_of_negation>Overuse of negation</h3>
+<h3 id="overuse_of_negation">Overuse of negation</h3>
<p>The following example rule is like locking the front door but leaving the
@@ -238,7 +237,7 @@
<pre>allow { domain -untrusted_app } scary_debug_device:chr_file rw_file_perms</pre>
<p>The intent is clear: everyone but third-party apps may have access to the debug
-device. </p>
+device.</p>
<p>The rule is flawed in a few ways. The exclusion of <code>untrusted_app</code>
is trivial to work around because all apps may optionally run services in the
@@ -248,7 +247,7 @@
access to this debugging tool. The rule should have been written to allow only
the domains that require access. </p>
-<h3 id=debugging_features_in_production>Debugging features in production</h3>
+<h3 id="debugging_features_in_production">Debugging features in production</h3>
<p>Debug features should not be present on production builds nor should their
@@ -262,7 +261,7 @@
<a href="https://android.googlesource.com/device/lge/hammerhead/+/marshmallow-dev/sepolicy/platform_app.te#3">
userdebug_or_eng</a> statement.</p>
-<h3 id=policy_size_explosion>Policy size explosion</h3>
+<h3 id="policy_size_explosion">Policy size explosion</h3>
<p><a href="http://arxiv.org/abs/1510.05497">Characterizing SEAndroid Policies in the Wild</a>
@@ -274,16 +273,16 @@
<p>Unnecessarily large policy:</p>
<ul>
- <li> Takes a double hit on memory as the policy sits in the ramdisk and is also
- loaded into kernel memory.
- <li> Wastes disk space by necessitating a larger bootimage.
- <li> Affects runtime policy lookup times.
+ <li>Takes a double hit on memory as the policy sits in the ramdisk and is
+ also loaded into kernel memory.</li>
+ <li>Wastes disk space by necessitating a larger bootimage.</li>
+ <li>Affects runtime policy lookup times.</li>
</ul>
-<p> The following example shows two devices where the manufacturer-specific policy
-comprised 50% and 40% of the on-device policy. A rewrite of the policy yielded
-substantial security improvements with no loss in functionality, as shown
-below. (AOSP devices Shamu and Flounder are included for comparison.)</p>
+<p> The following example shows two devices where the manufacturer-specific
+policy comprised 50% and 40% of the on-device policy. A rewrite of the policy
+yielded substantial security improvements with no loss in functionality, as
+shown below. (AOSP devices Shamu and Flounder are included for comparison.)</p>
<p><img alt="Figure 1: Comparison of device-specific policy size after security audit."
@@ -293,11 +292,11 @@
<p>In both cases, the policy was dramatically reduced both in size and in number
of permissions. The decrease in policy size is almost entirely due to removing
-unnecessary permissions, many of which were likely rules generated by
-audit2allow that were indiscriminately added to the policy. Dead domains were
-also an issue for both devices.</p>
+unnecessary permissions, many of which were likely rules generated by
+<code>audit2allow</code> that were indiscriminately added to the policy. Dead
+domains were also an issue for both devices.</p>
-<h3 id=granting_the_dac_override_capability>Granting the dac_override capability</h3>
+<h3 id="granting_the_dac_override_capability">Granting the dac_override capability</h3>
<p>A<code> dac_override</code> denial means that the offending process is
@@ -305,9 +304,9 @@
The proper solution is almost never to grant the <code>dac_override</code> permission.
Instead <a href="https://android-review.googlesource.com/#/c/174530/5/update_engine.te@11">
change the unix permissions on the file or process</a>. A few domains such as
-init, vold, and installd genuinely need the ability to override unix file
-permissions to access other processes’ files. See
-<a href="http://danwalsh.livejournal.com/69478.html">Dan Walsh’s blog</a>
+<code>init</code>, <code>vold</code>, and <code>installd</code> genuinely need
+the ability to override unix file permissions to access other processes’ files.
+See <a href="http://danwalsh.livejournal.com/69478.html">Dan Walsh’s blog</a>
for a more in-depth explanation.</p>
</body>
diff --git a/en/security/selinux/images/n-selinux-build-logic.png b/en/security/selinux/images/n-selinux-build-logic.png
new file mode 100644
index 0000000..89c933c
--- /dev/null
+++ b/en/security/selinux/images/n-selinux-build-logic.png
Binary files differ
diff --git a/en/security/selinux/images/n-selinux-policy-file.png b/en/security/selinux/images/n-selinux-policy-file.png
new file mode 100644
index 0000000..68112f9
--- /dev/null
+++ b/en/security/selinux/images/n-selinux-policy-file.png
Binary files differ
diff --git a/en/security/selinux/implement.html b/en/security/selinux/implement.html
index 5a855ce..79846c2 100644
--- a/en/security/selinux/implement.html
+++ b/en/security/selinux/implement.html
@@ -31,107 +31,82 @@
href="/security/selinux#supporting_documentation">Supporting
documentation</a> for suggested resources.</p>
-<aside class="note"><strong>Note:</strong> For details on implementing SELinux
-in Android 8.0, see
-<a href="/security/selinux/images/SELinux_Treble.pdf">SELinux for Android
-8.0</a>.</aside>
+<h2 id="key_files">Key files</h2>
-<h2 id=summary_of_steps>Summary of steps</h2>
+<p>To enable SELinux, integrate the
+<a href="https://android.googlesource.com/kernel/common/" class="external">latest
+Android kernel</a> and then incorporate the files found in the
+<a href="https://android.googlesource.com/platform/system/sepolicy/" class="external">system/sepolicy</a>
+directory. When compiled, those files comprise the SELinux kernel security
+policy and cover the upstream Android operating system.</p>
+<p>In general, you should not modify the <code>system/sepolicy</code> files
+directly. Instead, add or edit your own device-specific policy files in the
+<code>/device/<var>manufacturer</var>/<var>device-name</var>/sepolicy</code>
+directory. In Android 8.0 and higher, the changes you make to these files should
+only affect policy in your vendor directory. For more details on separation of
+public sepolicy in Android 8.0 and higher, see
+<a href="/security/selinux/customize#android-o">Customizing SEPolicy in Android
+8.0+</a>. Regardless of Android version, you're still modifying these files:</p>
-<p>Here is a brief summary of the steps needed to implement SELinux on your
-Android device:</p>
-<ol>
- <li>Add SELinux support in the kernel and configuration.
- <li>Grant each service (process or daemon) started from <code>init</code> its own domain.
- <li>Identify these services by:
+<h3 id="policy-files">Policy files</h3>
+
+<p>Files that end with <code>*.te</code> are SELinux policy source files, which
+define domains and their labels. You may need to create new policy files in
+<code>/device/<var>manufacturer</var>/<var>device-name</var>/sepolicy</code>,
+but you should try to update existing files where possible.</p>
+
+<h3 id="context-files">Context files</h3>
+<p>Context files are where you specify labels for your objects.</p>
<ul>
- <li>Reviewing the init.<device>.rc file and finding all services.
- <li>Examining warnings of the form <em>init: Warning! Service name needs a SELinux domain defined; please fix!</em> in <code>dmesg</code> output.
- <li>Checking <code>ps -Z | grep init</code> output to see which services are running in the init domain.
- </ul>
- <li>Label all new processes, drivers, sockets, etc.
-All objects need to be labeled
-properly to ensure they interact properly with the policies you apply. See the
-labels used in AOSP for examples to follow in label name creation.
- <li>Institute security policies that fully cover all labels and restrict
-permissions to their absolute minimum.
-</ol>
-
-<p>Ideally, OEMs start with the policies in the AOSP and then build upon them for
-their own customizations.</p>
-
-<h2 id=key_files>Key files</h2>
-
-<p>SELinux for Android is accompanied by everything you need to enable SELinux
-now. You merely need to integrate the <a href="https://android.googlesource.com/kernel/common/">latest Android kernel</a> and then incorporate the files found in the <a href="https://android.googlesource.com/platform/system/sepolicy/">system/sepolicy</a> directory:</p>
-
-<p><a href="https://android.googlesource.com/kernel/common/">https://android.googlesource.com/kernel/common/ </a></p>
-
-<p><a href="https://android.googlesource.com/platform/system/sepolicy/">https://android.googlesource.com/platform/system/sepolicy/</a></p>
-
-<p>Those files when compiled comprise the SELinux kernel security policy and cover
-the upstream Android operating system. You should not need to modify the
-system/sepolicy files directly. Instead, add your own device-specific policy
-files within the /device/manufacturer/device-name/sepolicy directory.</p>
-
-<p>Here are the files you must create or edit in order to implement SELinux:</p>
-
-<ul>
- <li><em>New SELinux policy source (*.te) files</em> - Located in the
-<root>/device/manufacturer/device-name/sepolicy directory. These files define
-domains and their labels. The new policy files get
-concatenated with the existing policy files during compilation into a single
-SELinux kernel policy file.
-<p class="caution"><strong>Important:</strong> Do not alter the app.te file
-provided by the Android Open Source Project.
-Doing so risks breaking all third-party applications.</p>
- <li><em>Updated BoardConfig.mk makefile</em> - Located in the <device-name>
-directory containing the sepolicy subdirectory. It must be updated to reference
-the sepolicy subdirectory once created if it
-wasn’t in initial implementation.
- <li><em>file_contexts</em> - Located in the sepolicy subdirectory. This file
-assigns labels to files and is used by various userspace components. As you
-create new policies, create or update this file to
-assign new labels to files. In order to apply new file_contexts, you must
-rebuild the filesystem image or run <code>restorecon</code> on the file to be
-relabeled. On upgrades, changes to file_contexts are automatically applied to
-the system and userdata partitions as part of the upgrade. Changes can also be
-automatically applied on upgrade to other partitions by adding
-restorecon_recursive calls to your init.<em>board</em>.rc file after the
-partition has been mounted read-write.
- <li><em>genfs_contexts</em> - Located in the sepolicy subdirectory. This file
-assigns labels to filesystems such as proc or vfat that do not support extended
-attributes. This configuration is loaded as part of the kernel policy but
-changes may not take effect for in-core inodes, requiring a reboot or
-unmounting and re-mounting the filesystem to fully apply the change. Specific
-labels may also be assigned to specific mounts such as vfat using the context=
-mount option.
- <li><em>property_contexts</em> - Located in the sepolicy subdirectory. This
-file assigns labels to Android system properties to control what processes can
-set them. This configuration is read by the init process during startup.
- <li><em>service_contexts</em> - Located in the sepolicy subdirectory. This
-file assigns labels to Android binder services to control what processes can
-add (register) and find (lookup) a binder reference for the service. This
-configuration is read by the servicemanager process during startup.
- <li><em>seapp_contexts</em> - Located in the sepolicy subdirectory. This file
-assigns labels to app processes and /data/data directories. This configuration
-is read by the zygote process on each app launch and by installd during startup.
- <li><em>mac_permissions.xml</em> - Located in the sepolicy subdirectory. This
-file assigns a seinfo tag to apps based on their signature and optionally their
-package name. The seinfo tag can then be used as a key in the seapp_contexts
-file to assign a specific label to all apps with that seinfo tag. This
-configuration is read by system_server during startup.
+ <li><code>file_contexts</code> assigns labels to files and is used by various
+ userspace components. As you create new policies, create or update this file
+ to assign new labels to files. To apply new <code>file_contexts</code>,
+ rebuild the filesystem image or run <code>restorecon</code> on the file to
+ be relabeled. On upgrades, changes to <code>file_contexts</code> are
+ automatically applied to the system and userdata partitions as part of the
+ upgrade. Changes can also be automatically applied on upgrade to other
+ partitions by adding <code>restorecon_recursive</code> calls to your
+ init.<var>board</var>.rc file after the partition has been mounted
+ read-write.</li>
+ <li><code>genfs_contexts</code> assigns labels to filesystems, such as
+ <code>proc</code> or <code>vfat</code> that do not support extended
+ attributes. This configuration is loaded as part of the kernel policy but
+ changes may not take effect for in-core inodes, requiring a reboot or
+ unmounting and re-mounting the filesystem to fully apply the change.
+ Specific labels may also be assigned to specific mounts, such as
+ <code>vfat</code> using the <code>context=mount</code> option.</li>
+ <li><code>property_contexts</code> assigns labels to Android system properties to
+ control what processes can set them. This configuration is read by the
+ <code>init</code> process during startup.</li>
+ <li><code>service_contexts</code> assigns labels to Android binder services to
+ control what processes can add (register) and find (lookup) a binder
+ reference for the service. This configuration is read by the
+ <code>servicemanager</code> process during startup.</li>
+ <li><code>seapp_contexts</code> assigns labels to app processes and
+ <code>/data/data</code> directories. This configuration is read by the
+ <code>zygote</code> process on each app launch and by <code>installd</code>
+ during startup.</li>
+ <li><code>mac_permissions.xml</code> assigns a <code>seinfo</code> tag to apps
+ based on their signature and optionally their package name. The
+ <code>seinfo</code> tag can then be used as a key in the
+ <code>seapp_contexts</code> file to assign a specific label to all apps with
+ that <code>seinfo</code> tag. This configuration is read by
+ <code>system_server</code> during startup.</li>
</ul>
-<p>Then just update your BoardConfig.mk makefile - located in the directory
-containing the sepolicy subdirectory - to reference the sepolicy subdirectory
-and each policy file once created, as shown below. The BOARD_SEPOLICY variables
-and their meaning is documented in the system/sepolicy/README file.</p>
+<h3 id="boardconfig">BoardConfig.mk makefile</h3>
+
+<p>After editing or adding policy and context files, update your
+<code>/device/<var>manufacturer</var>/<var>device-name</var>/BoardConfig.mk</code>
+makefile to reference the <code>sepolicy</code> subdirectory and each new policy file.
+For more information about the <code>BOARD_SEPOLICY</code> variables, see
+<a href="https://android.googlesource.com/platform/system/sepolicy/+/master/README" class="external">
+<code>system/sepolicy/README</code> file</a>.</p>
<pre class="devsite-click-to-copy">
BOARD_SEPOLICY_DIRS += \
- <root>/device/manufacturer/device-name/sepolicy
+ <root>/device/<var>manufacturer</var>/<var>device-name</var>/sepolicy
BOARD_SEPOLICY_UNION += \
genfs_contexts \
@@ -139,108 +114,124 @@
sepolicy.te
</pre>
-<p class="note"><strong>Note:</strong> As of the M release,
-BOARD_SEPOLICY_UNION is no longer required as all policy files found within any
-directory included in the BOARD_SEPOLICY_DIRS variable are joined with the
-base policy automatically.</p>
-
-<p>After rebuilding your device, it is enabled with SELinux. You can now either
+<p>After rebuilding, your device is enabled with SELinux. You can now either
customize your SELinux policies to accommodate your own additions to the
-Android operating system as described in <a
-href="customize.html">Customization</a> or verify your existing setup as
-covered in <a href="validate.html">Validation</a>.</p>
+Android operating system as described in
+<a href="/security/selinux/customize.html">Customization</a> or verify your
+existing setup as covered in
+<a href="/security/selinux/validate.html">Validation</a>.</p>
-<p>Once the new policy files and BoardConfig.mk updates are in place, the new
-policy settings are automatically built into the final kernel policy file.</p>
+<p>When the new policy files and BoardConfig.mk updates are in place, the new
+policy settings are automatically built into the final kernel policy file.
+For more information about how sepolicy is built on the device, see
+<a href="security/selinux/building">Building sepolicy</a>.</p>
-<h2 id=use_cases>Use cases</h2>
+<h2 id="steps">Implementation</h2>
+
+<p>To get started with SELinux:</p>
+
+<ol>
+ <li>Enable SELinux in the kernel:
+ <code>CONFIG_SECURITY_SELINUX=y</code></li>
+ <li>Change the kernel_cmdline parameter so that:
+ <pre class="devsite-click-to-copy">
+BOARD_KERNEL_CMDLINE := androidboot.selinux=permissive</pre>
+ This is only for initial development of policy for the device. After you
+ have an initial bootstrap policy, remove this parameter so your
+ device is enforcing or it will fail CTS.</li>
+ <li>Boot up the system in permissive and see what denials are encountered on boot:<br/>
+ On Ubuntu 14.04 or newer:
+<pre class="devsite-terminal devsite-click-to-copy">
+adb shell su -c dmesg | grep denied | audit2allow -p out/target/product/<var>BOARD</var>/root/sepolicy
+</pre>
+ On Ubuntu 12.04:
+<pre class="devsite-terminal devsite-click-to-copy">
+adb pull /sys/fs/selinux/policy
+adb logcat -b all | audit2allow -p policy
+</pre></li>
+ <li>Evaluate the output for warnings that resemble <code>init: Warning!
+ Service name needs a SELinux domain defined; please fix!</code> See
+ <a href="/security/selinux/validate">Validation</a> for instructions
+ and tools.</li>
+ <li>Identify devices, and other new files that need labeling.</li>
+ <li>Use existing or new labels for your objects. Look at the
+ <code>*_contexts</code> files to see how things were previously labeled
+ and use knowledge of the label meanings to assign a new one. Ideally,
+ this will be an existing label which will fit into policy, but sometimes
+ a new label will be needed, and rules for access to that label will be
+ needed. Add your labels to the appropriate context files.</li>
+ <li>Identify domains/processes that should have their own security domains.
+ You will likely need to write a completely new policy for each. All
+ services spawned from <code>init</code>, for instance, should have their
+ own. The following commands help reveal those that remain running (but ALL
+ services need such a treatment):<br/>
+<pre class="devsite-terminal devsite-click-to-copy">
+adb shell su -c ps -Z | grep init
+</pre>
+<pre class="devsite-terminal devsite-click-to-copy">
+adb shell su -c dmesg | grep 'avc: '
+</pre></li>
+ <li>Review <code>init.<var>device</var>.rc</code> to identify any domains that
+ don't have a domain type. Give them a domain <em>early</em> in your
+ development process to avoid adding rules to <code>init</code> or
+ otherwise confusing <code>init</code> accesses with ones that are in their
+ own policy.</li>
+ <li>Set up <code>BOARD_CONFIG.mk</code> to use <code>BOARD_SEPOLICY_*</code>
+ variables. See the
+ <a href="https://android.googlesource.com/platform/system/sepolicy/+/master/README" class="external">README</a>
+ in <code>system/sepolicy</code> for details on setting this up.</li>
+ <li>Examine the init.<var>device</var>.rc and fstab.<var>device</var> file and
+ make sure every use of <code>mount</code> corresponds to a properly
+ labeled filesystem or that a <code>context= mount</code> option is
+ specified.</li>
+ <li>Go through each denial and create SELinux policy to properly handle each. See
+ the examples in <a href="/security/selinux/customize">Customization</a>.
+</ol>
+
+<p>You should start with the policies in the AOSP and then build upon them for
+your own customizations. For more information about policy strategy and a
+closer look at some of these steps, see
+<a href="/security/selinux/device-policy">Writing SELinux Policy</a>.</p>
+
+
+<h2 id="use_cases">Use cases</h2>
<p>Here are specific examples of exploits to consider when crafting your own
software and associated SELinux policies:</p>
-<p><strong>Symlinks</strong> - Because symlinks appear as files, they are often read just as that. This can
-lead to exploits. For instance, some privileged components such as init change
-the permissions of certain files, sometimes to be excessively open.</p>
+<p><strong>Symlinks</strong> - Because symlinks appear as files, they are often
+read as files, which can lead to exploits. For instance, some privileged
+components, such as <code>init</code>, change the permissions of certain files,
+sometimes to be excessively open.</p>
<p>Attackers might then replace those files with symlinks to code they control,
allowing the attacker to overwrite arbitrary files. But if you know your
application will never traverse a symlink, you can prohibit it from doing so
with SELinux.</p>
-<p><strong>System files</strong> - Consider the class of system files that should only be modified by the
-system server. Still, since netd, init, and vold run as root, they can access
-those system files. So if netd became compromised, it could compromise those
-files and potentially the system server itself.</p>
+<p><strong>System files</strong> - Consider the class of system files that
+should be modified only by the system server. Still, since <code>netd</code>,
+<code>init</code>, and <code>vold</code> run as root, they can access
+those system files. So if <code>netd</code> became compromised, it could
+compromise those files and potentially the system server itself.</p>
<p>With SELinux, you can identify those files as system server data files.
Therefore, the only domain that has read/write access to them is system server.
-Even if netd became compromised, it could not switch domains to the system
-server domain and access those system files although it runs as root.</p>
+Even if <code>netd</code> became compromised, it could not switch domains to the
+system server domain and access those system files although it runs as root.</p>
-<p><strong>App data</strong> - Another example is the class of functions that must run as root but should
-not get to access app data. This is incredibly useful as wide-ranging
-assertions can be made, such as certain domains unrelated to application data
-being prohibited from accessing the internet.</p>
+<p><strong>App data</strong> - Another example is the class of functions that
+must run as root but should not get to access app data. This is incredibly
+useful as wide-ranging assertions can be made, such as certain domains unrelated
+to application data being prohibited from accessing the internet.</p>
-<p><strong>setattr</strong> - For commands such as chmod and chown, you could identify the set of files
-where the associated domain can conduct setattr. Anything outside of that could
-be prohibited from these changes, even by root. So an application might run
-chmod and chown against those labeled app_data_files but not shell_data_files
-or system_data_files.</p>
-
-<h2 id=steps_in_detail>Steps in detail</h2>
-
-<p>Here is a detailed view of how Android recommends you employ and customize
-SELinux to protect your devices:</p>
-
-<ol>
- <li>Enable SELinux in the kernel:
-<code>CONFIG_SECURITY_SELINUX=y</code>
- <li>Change the kernel_cmdline parameter so that:<br/>
-<pre class="devsite-click-to-copy">
-BOARD_KERNEL_CMDLINE := androidboot.selinux=permissive
-</pre>
-<br/>
-This is only for initial development of policy for the device. Once you have
-an initial bootstrap policy, remove this parameter so that your device is
-enforcing or it will fail CTS.
- <li>Boot up the system in permissive and see what denials are encountered on boot:<br/>
-On Ubuntu 14.04 or newer:
-<br/>
-<pre class="devsite-terminal devsite-click-to-copy">
-adb shell su -c dmesg | grep denied | audit2allow -p out/target/product/<var>BOARD</var>/root/sepolicy
-</pre>
-<br/>
-On Ubuntu 12.04:<br/>
-<pre class="devsite-terminal devsite-click-to-copy">
-adb shell su -c dmesg | grep denied | audit2allow
-</pre>
- <li>Evaluate the output. See <a href="validate.html">Validation</a> for instructions and tools.
- <li>Identify devices, and other new files that need labeling.
- <li>Use existing or new labels for your objects.
-Look at the *_contexts files to
-see how things were previously labeled and use knowledge of the label meanings
-to assign a new one. Ideally, this will be an existing label which will fit
-into policy, but sometimes a new label will be needed, and rules for access to
-that label will be needed, as well.
- <li>Identify domains/processes that should have their own security domains. A policy will likely need to be written for each of these from scratch. All services spawned from <code>init</code>, for instance, should have their own. The following commands help reveal those that remain running (but ALL services need such a treatment):<br/>
-<pre class="devsite-terminal devsite-click-to-copy">
-adb shell su -c ps -Z | grep init
-</pre>
-<pre class="devsite-terminal devsite-click-to-copy">
-adb shell su -c dmesg | grep 'avc: '
-</pre>
- <li>Review init.<device>.rc to identify any which are without a type.
-These should
-be given domains EARLY in order to avoid adding rules to init or otherwise
-confusing <code>init</code> accesses with ones that are in their own policy.
- <li>Set up <code>BOARD_CONFIG.mk</code> to use <code>BOARD_SEPOLICY_*</code> variables. See
-the README in system/sepolicy for details on setting this up.
- <li> Examine the init.<device>.rc and fstab.<device> file and make sure every use of “mount”
-corresponds to a properly labeled filesystem or that a context= mount option is specified.
- <li> Go through each denial and create SELinux policy to properly handle each. See
-the examples within <a href="customize.html">Customization</a>.
-</ol>
+<p><strong>setattr</strong> - For commands such as <code>chmod</code> and
+<code>chown</code>, you could identify the set of files where the associated
+domain can conduct <code>setattr</code>. Anything outside of that could be
+prohibited from these changes, even by root. So an application might run
+<code>chmod</code> and <code>chown</code> against those labeled
+<code>app_data_files</code> but not <code>shell_data_files</code>
+or <code>system_data_files</code>.</p>
</body>
</html>
diff --git a/en/security/selinux/index.html b/en/security/selinux/index.html
index e5ad9a1..a0ce8f3 100644
--- a/en/security/selinux/index.html
+++ b/en/security/selinux/index.html
@@ -21,42 +21,19 @@
limitations under the License.
-->
-
-<p>The Android security model is based in part on the concept of application
-sandboxes. Each application runs in its own sandbox. Prior to Android 4.3,
-these sandboxes were defined by the creation of a unique Linux UID for each
-application at time of installation. Starting with Android 4.3,
-Security-Enhanced Linux (SELinux) is used to further define the boundaries of
-the Android application sandbox.</p>
-
-<aside class="note"><strong>Note:</strong> For details on Android 8.0 SELinux,
-see <a href="/security/selinux/images/SELinux_Treble.pdf">SELinux for Android
-8.0</a>.</aside>
-
<p>As part of the Android <a href="/security/index.html">
-security model</a>, Android uses SELinux to enforce mandatory access control
-(MAC) over all processes, even processes running with root/superuser privileges
-(a.k.a. Linux capabilities). SELinux enhances Android security by confining
-privileged processes and automating security policy creation.</p>
+security model</a>, Android uses Security-Enhanced Linux (SELinux) to enforce
+mandatory access control (MAC) over all processes, even processes running with
+root/superuser privileges (Linux capabilities). Many companies and organizations
+have contributed to Android's
+<a href="https://android.googlesource.com/platform/external/selinux/" class="external">SELinux
+implementation</a>. With SELinux, Android can better protect and confine system
+services, control access to application data and system logs, reduce the effects
+of malicious software, and protect users from potential flaws in code on mobile
+devices.</p>
-<p>Many companies and organizations have contributed to SELinux; their
-contributions are publicly available for review on
-<a href="https://android.googlesource.com/" class="external">android.googlesource.com</a>,
-aka the Android Open Source Project (AOSP). With SELinux, Android can better
-protect and confine system services, control access to application data and
-system logs, reduce the effects of malicious software, and protect users from
-potential flaws in code on mobile devices.</p>
-
-<p>Android includes SELinux in enforcing mode and a corresponding security
-policy that works by default across AOSP. In enforcing mode, illegitimate
-actions are prevented and all attempted violations are logged by the kernel to
-<code>dmesg</code> and <code>logcat</code>. Android device manufacturers should
-gather information about errors so they may refine their software and SELinux
-policies before enforcing them.</p>
-
-<h2 id=background>Background</h2>
-<p>SELinux operates on the ethos of default denial: Anything not explicitly
-allowed is denied. SELinux can operate in one of two global modes:</p>
+<p>SELinux operates on the principle of default denial: Anything not explicitly
+allowed is denied. SELinux can operate in two global modes:</p>
<ul>
<li><em>Permissive</em> mode, in which permission denials are logged but not
enforced.</li>
@@ -64,6 +41,14 @@
<strong>and</strong> enforced.</li>
</ul>
+<p>Android includes SELinux in enforcing mode and a corresponding security
+policy that works by default across AOSP. In enforcing mode, disallowed
+actions are prevented and all attempted violations are logged by the kernel to
+<code>dmesg</code> and <code>logcat</code>. When developing, you should
+use these errors to refine your software and SELinux policies before enforcing
+them. For more details, see <a href="/security/selinux/implement">Implementing
+SELinux</a>.</p>
+
<p>SELinux also supports a <em>per-domain permissive</em> mode in which specific
domains (processes) can be made permissive while placing the rest of the system
in global enforcing mode. A domain is simply a label identifying a process or set
@@ -73,7 +58,16 @@
the system and policy development for new services (while keeping the rest of
the system enforcing).</p>
-<p>The Android 5.0 release moved to full enforcement of SELinux, building on the
+<h2 id="background">Background</h2>
+
+<p>The Android security model is based in part on the concept of
+<a href="/security/app-sandbox">application sandboxes</a>. Each application
+runs in its own sandbox. Prior to Android 4.3, these sandboxes were defined by
+the creation of a unique Linux UID for each application at time of installation.
+Android 4.3 and later uses SELinux to further define the boundaries of the
+Android application sandbox.</p>
+
+<p>In Android 5.0 and later, SELinux is fully enforced, building on the
permissive release of Android 4.3 and the partial enforcement of Android 4.4.
With this change, Android shifted from enforcement on a limited set of crucial
domains (<code>installd</code>, <code>netd</code>, <code>vold</code> and
@@ -87,8 +81,41 @@
<code>socket_device</code>, <code>default_service</code>, etc.) indicates that
device needs a special domain.</li>
</ul>
-<p>As a result, manufacturers need to better understand and scale their SELinux
-implementations to provide compatible devices.</p>
+
+<p>Android 6.0 hardened the system by reducing the permissiveness of our
+policy to include better isolation between users, IOCTL filtering, reduced
+threat of exposed services, further tightening of SELinux domains, and
+extremely limited <code>/proc</code> access.
+</p>
+<p>
+Android 7.0 updated SELinux configuration to further lock down the
+application sandbox and reduce attack surface. This release also broke up the
+monolithic mediaserver stack into smaller processes to reduce the scope of
+their permissions. For more details, see
+<a href="https://android-developers.googleblog.com/2016/07/protecting-android-with-more-linux.html" class="external">Protecting
+Android with more Linux kernel defenses</a> and
+<a href="https://android-developers.googleblog.com/2016/05/hardening-media-stack.html" class="external">Hardening
+the media stack</a>.
+</p>
+</p>
+<p>
+Android 8.0 updated SELinux to work with <a
+href="/devices/architecture/#hidl">Treble</a>, which separates the lower-level
+vendor code from the Android system framework. This release updated SELinux
+policy to allow device manufacturers and SOC vendors to update their parts of
+the policy, build their images (<code>vendor.img</code>, <code>boot.img</code>,
+etc.), then update those images independent of the platform or vice versa.
+</p>
+<p>
+While it is possible to have higher/newer platform (framework) version running
+on the device, the opposite case is not supported; the vendor images
+(<code>vendor.img/odm.img</code>) cannot have a newer version than the platform
+(<code>system.img</code>). So, a newer platform version might introduce SELinux
+compatibility issues because the platform SELinux policy is at a newer version
+than vendor SELinux parts of the policy. The Android 8.0 model provides a method
+to <a href="/security/selinux/compatibility">retain compatibility</a> to prevent
+unnecessary simultaneous OTAs.
+</p>
<h2 id=supporting_documentation>Additional resources</h2>
@@ -115,6 +142,9 @@
<li><a href="https://www.gnu.org/software/m4/manual/index.html" class="external">
GNU M4 - GNU Macro Processor Manual</a></li>
+
+<li><a href="https://opensource.com/business/13/11/selinux-policy-guide" class="external">
+Your visual how-to guide for SELinux policy enforcement</a></li>
</ul>
</body>
diff --git a/en/security/selinux/validate.html b/en/security/selinux/validate.html
index c2e0e41..3f7ef80 100644
--- a/en/security/selinux/validate.html
+++ b/en/security/selinux/validate.html
@@ -27,24 +27,26 @@
thoroughly. As manufacturers implement SELinux, they should apply the new
policy to a test pool of devices first.</p>
-<p>Once applied, make sure SELinux is running in the correct mode on the device by
-issuing the command:getenforce</p>
+<p>After applying a new policy, make sure SELinux is running in the correct
+mode on the device by issuing the command <code>getenforce</code>.</p>
-<p>This will print the global SELinux mode: either Enforcing or
-Permissive. Please note, this command shows only the global SELinux mode. To
+<p>This prints the global SELinux mode: either Enforcing or Permissive. To
determine the SELinux mode for each domain, you must examine the corresponding
files or run the latest version of <code>sepolicy-analyze</code> with the
-appropriate (-p) flag, present in /platform/system/sepolicy/tools/.</p>
+appropriate (<code>-p</code>) flag, present in
+<a href="https://android.googlesource.com/platform/system/sepolicy/+/master/tools/" class="external">
+<code>/platform/system/sepolicy/tools/</code></a>.</p>
-<h2 id=reading_denials>Reading denials</h2>
+<h2 id="reading_denials">Reading denials</h2>
-<p>Then check for errors. Errors are routed as event logs to dmesg and
-<code>logcat</code> and are viewable locally on the device. Manufacturers
-should examine the SELinux output to dmesg on these devices and refine settings prior to public
-release in permissive mode and eventual switch to enforcing mode. SELinux log
-messages contain "avc:" and so may easily be found with <code>grep</code>. It is
-possible to capture the ongoing denial logs by running <code>cat /proc/kmsg</code>
-or to capture denial logs from the previous boot by running
+<p>Check for errors, which are routed as event logs to <code>dmesg</code>
+and <code>logcat</code> and are viewable locally on the device. Manufacturers
+should examine the SELinux output to <code>dmesg</code> on these devices and
+refine settings prior to public release in permissive mode and eventual switch
+to enforcing mode. SELinux log messages contain <code>avc:</code> and so may
+easily be found with <code>grep</code>. It is possible to capture the ongoing
+denial logs by running <code>cat /proc/kmsg</code> or to capture denial logs
+from the previous boot by running
<code>cat /sys/fs/pstore/console-ramoops</code>.</p>
<p>With this output, manufacturers can readily identify when system users or
@@ -73,7 +75,7 @@
run at the time the denial was generated. In this case, it’s a pretty good hint.
</ul>
-<p>And here is another example:</p>
+<p>Another example:</p>
<pre class="devsite-terminal devsite-click-to-copy">adb shell su root dmesg | grep 'avc: '</pre>
<p>Output:</p>
<pre>
diff --git a/en/security/selinux/vendor-init.html b/en/security/selinux/vendor-init.html
new file mode 100644
index 0000000..bc51333
--- /dev/null
+++ b/en/security/selinux/vendor-init.html
@@ -0,0 +1,125 @@
+<html devsite>
+ <head>
+ <title>Vendor Init</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ <body>
+ <!--
+ Copyright 2018 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
+
+ //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 init process has nearly unrestricted permissions and uses input scripts from
+both the system and vendor partitions to initialize the system during the boot
+process. This access causes a huge hole in the Treble system/vendor split, as
+vendor scripts may instruct init to access files, properties, etc. that do not
+form part of the stable system-vendor application binary interface (ABI).
+</p>
+<p>
+<em>Vendor init</em> is designed to close this hole by using a separate
+security-enhanced Linux (SELinux) domain <code>vendor_init</code> to run
+commands found in <code>/vendor</code> with vendor-specific permissions.
+</p>
+<h2 id="mechanism">Mechanism</h2>
+<p>
+Vendor init forks a subprocess of init early in the boot process with the
+SELinux context <code>u:r:vendor_init:s0</code>. This SELinux context has
+considerably fewer permissions than the default init context and its access is
+confined to files, properties, etc. that are either vendor-specific or part of
+the stable system-vendor ABI.
+</p>
+<p>
+Init checks each script it loads to see if its path starts with
+<code>/vendor</code> and if so, tags it with an indication that its commands
+must be run in the vendor init context. Each init builtin is annotated with a
+boolean that specifies whether or not the command must be run in the vendor init
+subprocess:
+</p>
+<ul>
+<li>Most commands that access the file system are annotated to run in the vendor
+ init subprocess and are therefore subjected to the vendor init SEPolicy.</li>
+<li>Most commands that impact internal init state (e.g., starting and stopping
+ services) are run within the normal init process. These commands are made
+ aware that a vendor script is calling them to do their own non-SELinux
+ permissions handling.</li>
+</ul>
+<p>
+The main processing loop of init contains a check that if a command is annotated
+to run in the vendor subprocess and originates from a vendor script, that
+command is sent via inter-process communication (IPC) to the vendor init
+subprocess, which runs the command and sends the result back to init.
+</p>
+<h2 id="using-vendor-init">Using Vendor Init</h2>
+<p>
+Vendor init is enabled by default and its restrictions apply to all init scripts
+present in the <code>/vendor</code> partition. Vendor init should be transparent
+to vendors whose scripts are already not accessing system only files,
+properties, etc.
+</p>
+<p>
+However, if commands in a given vendor script violate the vendor init
+restrictions, the commands will fail. Failing commands have a line in the kernel
+log (visible with dmesg) from init indicating failure. An SELinux audit
+accompanies any failing command that failed due to the SELinux policy. Example
+of a failure including an SELinux audit:
+</p>
+
+
+<pre class="devsite-disable-click-to-copy">type=1400 audit(1511821362.996:9): avc: denied { search } for pid=540 comm="init" name="nfc" dev="sda45" ino=1310721 scontext=u:r:vendor_init:s0 tcontext=u:object_r:nfc_data_file:s0 tclass=dir permissive=0
+init: Command 'write /data/nfc/bad_file_access 1234' action=boot (/vendor/etc/init/hw/init.walleye.rc:422) took 2ms and failed: Unable to write to file '/data/nfc/bad_file_access': open() failed: Permission denied</pre>
+<p>
+If a command fails, there are two options:
+</p>
+<ul>
+<li>If the command is failing due to an intended restriction (such as if the
+command is accessing a system file or property), the command must be
+re-implemented in a Treble-friendly way, going through only stable interfaces.
+Neverallow rules prevent adding permissions to access system files that are not
+part of the stable system-vendor ABI.</li>
+<li>If the SELinux label is new and is not already granted permissions in the
+system <code>vendor_init.te</code> nor excluded permissions via the neverallow
+rules, the new label may be granted permissions in the device-specific
+<code>vendor_init.te</code>.</li>
+</ul>
+<p>
+For devices launching before Android 9, the neverallows rules may be bypassed by
+adding the <code>data_between_core_and_vendor_violators</code> typeattribute to
+the device-specific <code>vendor_init.te</code> file.
+</p>
+<p>
+For devices launching with Android 9, a GTS check prevents the usage of
+<code>data_between_core_and_vendor_violators</code>.
+</p>
+<h2 id="code-locations">Code Locations</h2>
+<p>
+The bulk of the logic for the vendor init IPC is in <a
+href="https://android.googlesource.com/platform/system/core/+/master/init/subcontext.cpp">system/core/init/subcontext.cpp</a>.
+</p>
+<p>
+The table of commands is in the <code>BuiltinFunctionMap</code> class in <a
+href="https://android.googlesource.com/platform/system/core/+/master/init/builtins.cpp">system/core/init/builtins.cpp</a>
+and includes annotations that indicate if the command must run in the vendor
+init subprocess.
+</p>
+<p>
+The SEPolicy for vendor init is split across the private (<a
+href="https://android.googlesource.com/platform/system/sepolicy/+/master/private/vendor_init.te">system/sepolicy/private/vendor_init.te</a>)
+and public (<a
+href="https://android.googlesource.com/platform/system/sepolicy/+/master/public/vendor_init.te">system/sepolicy/public/vendor_init.te</a>)
+directories in system/sepolicy.
+</p>
+ </body>
+</html>
diff --git a/en/security/verifiedboot/avb.html b/en/security/verifiedboot/avb.html
new file mode 100644
index 0000000..f6a8e42
--- /dev/null
+++ b/en/security/verifiedboot/avb.html
@@ -0,0 +1,54 @@
+<html devsite>
+ <head>
+ <title>Android Verified Boot</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ <body>
+ <!--
+ Copyright 2018 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
+
+ //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 8.0 and higher includes a reference implementation of Verified Boot
+called Android Verified Boot (AVB) or Verified Boot 2.0. AVB in a version of
+Verified Boot that works with <a
+href="/devices/architecture/#hidl">Project Treble</a>
+architecture, which separates the Android framework from the underlying vendor
+implementation.
+</p>
+<p>
+AVB is integrated with the Android Build System and enabled by
+a single line, which takes care of generating and signing all necessary dm-verity
+metadata. For more information, see <a
+href="https://android.googlesource.com/platform/external/avb/+/master/README.md#Build-System-Integration"
+class="external">Build System Integration</a>.
+</p>
+<p>AVB provides libavb, which is a C library to be used at boot time for
+verifying Android. You can integrate libavb with your bootloader by implementing a
+<a href="https://android.googlesource.com/platform/external/avb/+/master/libavb/avb_ops.h"
+class="external">platform-specific functionality</a> for I/O, providing the root
+of trust, and getting/setting rollback protection metadata.
+</p>
+<p>
+AVB's key features include delegating updates for different
+partitions, a common footer format for signing partitions, and protection from
+attackers rolling back to a vulnerable version of Android.
+</p>
+For more implementation details, see <code><a
+href="https://android.googlesource.com/platform/external/avb/+/master/README.md"
+class="external">/platform/external/avb/README.md</a></code>.
+
+</body>
+</html>
diff --git a/en/security/verifiedboot/boot-flow.html b/en/security/verifiedboot/boot-flow.html
new file mode 100644
index 0000000..212233f
--- /dev/null
+++ b/en/security/verifiedboot/boot-flow.html
@@ -0,0 +1,361 @@
+<html devsite>
+ <head>
+ <title>Boot Flow</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ <body>
+ <!--
+ Copyright 2018 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
+
+ //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 recommended boot flow for a device is as follows:
+</p>
+<figure>
+ <img src="/security/images/verified-boot-flow.png"
+ alt="Verified boot flow">
+ <figcaption><b>Figure 1</b>. Verified boot flow</figcaption>
+</figure>
+
+<h2 id="flow-for-a-b-devices">Flow for A/B devices</h2>
+<p>
+If the device is using A/B, the boot flow is slightly different. The slot to
+boot must first be marked as <code>SUCCESSFUL</code> using the <a
+href="https://android.googlesource.com/platform/hardware/interfaces/+/master/boot/1.0/IBootControl.hal"
+class="external">Boot Control HAL</a> <strong>before</strong> updating the
+Rollback Protection metadata.
+</p>
+<p>
+If there's a platform update that fails (is not marked
+<code>SUCCESSFUL</code>), the A/B stack falls back to the other slot,
+which still has the previous version of Android in it. However, if
+the Rollback Protection-metadata had been set, the previous version can't
+boot because of Rollback Protection.
+</p>
+
+<h2 id="communicating-verified-boot-state-to-users">Communicating Verified Boot
+ state to users</h2>
+<p>
+After determining the boot state of a device, you need to communicate that
+state to the user. If the device doesn't have any issues, then proceed without
+displaying anything. Verified Boot issues fall into these categories:
+</p>
+<ul>
+ <li>YELLOW: Warning screen for LOCKED devices with custom root of trust set</li>
+ <li>ORANGE: Warning screen for UNLOCKED devices</li>
+ <li>RED (eio): Warning screen for dm-verity corruption</li>
+ <li>RED (no os found): No valid OS found</li>
+</ul>
+<table class="columns">
+ <col width="50%">
+ <col width="50%">
+ <tr>
+ <td>
+<h3 id="locked-devices-with-custom-root-of-trust">LOCKED devices with custom
+root of trust</h3>
+
+<p>
+Show a YELLOW screen on every boot if the device is LOCKED, a custom root of
+trust has been set, and the image was signed with this custom root of trust.
+The YELLOW screen is dismissed after ten seconds and the device continues
+booting. If the user presses the power button, "Press power button to pause"
+text changes to "Press power button to continue" and the screen is never
+dismissed, though the device may dim or turn off the screen to protect against
+burn-in). If pressed again, the screen is dismissed and the phone continues
+booting.
+</p>
+<p>
+For the <var>hex-number</var>, use the first 8 digits of the sha256 of
+the libavb representation of the public key used for verification, for example
+<code>f7a24de1</code>.
+</p>
+<p>
+<strong>Suggested text:</strong>
+</p>
+<p>
+Your device has loaded a different operating system.
+</p>
+<p>
+Visit this link on another device to learn more:
+</p>
+<p>
+g.co/ABH
+</p>
+<p>
+ID: <var>hex-number</var>
+</p>
+<p>
+<span class="material-icons">power_settings_new</span> Press power button to pause
+</p>
+<p> </p>
+ </td>
+ <td>
+
+<figure>
+ <p><strong>Example YELLOW screen:</strong></p>
+ <img src="/security/images/boot_yellow1.png"
+ alt="Yellow device warning screen">
+</figure>
+ </td>
+ </tr>
+ <tr>
+ <td>
+<h3 id="unlocked-devices">UNLOCKED devices</h3>
+<p>
+Show an ORANGE screen on every boot if the device is UNLOCKED. The ORANGE screen
+is dismissed after ten seconds and the device continues booting. If the user
+presses the power button, "Press power button to pause" text changes to "Press
+power button to continue" and the screen is never dismissed (the device may dim
+and/or turn off the screen if needed to protect against burn-in or similar). If
+pressed again, the screen is dismissed and the phone continues booting.
+</p>
+<p>
+For the <var>hex-number</var>, use the first 8 digits of the sha256 of the libavb
+representation of the public key used for verification, for example
+<code>f7a24de1</code>.
+</p>
+<p>
+<strong>Suggested text:</strong>
+</p>
+<p>
+The boot loader is unlocked and software integrity cannot be guaranteed. Any
+data stored on the device may be available to attackers. Do not store any
+sensitive data on the device.
+</p>
+<p>
+Visit this link on another device to learn more:
+</p>
+<p>
+g.co/ABH
+</p>
+<p>
+ID: <var>hex-number</var>
+</p>
+<p>
+<span class="material-icons">power_settings_new</span> Press power button to pause.
+</p>
+<p> </p>
+ </td>
+ <td>
+
+<figure>
+ <p><strong>Example ORANGE screen:</strong></p>
+ <img src="/security/images/boot_orange.png"
+ alt="Orange device warning screen">
+</figure>
+ </td>
+ </tr>
+ <tr>
+ <td>
+
+<h3 id="dm-verity-corruption">dm-verity corruption</h3>
+<p>
+Show a RED <code>eio</code> screen if a valid version of Android is found and
+the device is currently in the <code>eio</code> dm-verity mode. The user needs
+to click the power button to continue. If the user hasn't acknowledged the
+warning screen within 30 seconds, the device powers off (to protect the screen
+against burn-in and save power).
+</p>
+
+<aside class="note">
+<strong>Note:</strong> Other warning screens may follow this screen. For example, if the
+device is <code>UNLOCKED</code> the ORANGE screen shows after.
+</aside>
+
+<p>
+<strong>Suggested text:</strong>
+</p>
+<p>
+Your device is corrupt. It can't be trusted and may not work properly.
+</p>
+<p>
+Visit this link on another device to learn more:
+</p>
+<p>
+g.co/ABH
+</p>
+<p>
+<span class="material-icons">power_settings_new</span> Press power button to continue.
+</p>
+<p> </p>
+ </td>
+ <td>
+<figure>
+ <p><strong>Example RED eio screen:</strong></p>
+ <img src="/security/images/boot_red1.png"
+ alt="Red eio device warning screen">
+</figure>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <h3 id="no-valid-os-found">No valid OS found</h3>
+<p>
+Show a RED screen is shown if no valid version of Android can be found. The
+device cannot continue booting. If the user hasn't acknowledged the warning
+screen within 30 seconds, the device powers off to protect the screen against
+burn-in and save power).
+</p>
+<p>
+For the <var>hex-number</var>, use the first 8 digits of the sha256 of
+the libavb representation of the public key used for verification, for example
+<code>f7a24de1</code>.
+</p>
+<p>
+<strong>Suggested text:</strong>
+</p>
+<p>
+No valid operating system could be found. The device will not boot.
+</p>
+<p>
+Visit this link on another device to learn more:
+</p>
+<p>
+g.co/ABH
+</p>
+<p>
+ID: <var>hex-number</var>
+</p>
+<p>
+<span class="material-icons">power_settings_new</span> Press power button to power off.
+</p>
+<p> </p>
+ </td>
+ <td>
+<figure>
+ <p><strong>Example RED screen:</strong></p>
+ <img src="/security/images/boot_red2.png"
+ alt="Red corrupt device warning screen">
+</figure>
+ </td>
+ </tr>
+ <tr>
+ <td>
+<h3 id="unlock-confirmation">Unlock confirmation</h3>
+<p>
+Show an unlock confirmation screen in response to the
+<code>fastboot flashing unlock</code> command being executed via the fastboot
+interface. Focus is initially on <em>Don't unlock</em>. If the user hasn't
+interacted with the warning screen within 30 seconds, the screen disappears and
+the command fails.
+</p>
+<p>
+<strong>Suggested text:</strong>
+</p>
+<p>
+If you unlock the bootloader, you will be able to install custom operating
+system software on this phone. A custom OS is not subject to the same level of
+testing as the original OS, and can cause your phone and installed applications
+to stop working properly. Software integrity cannot be guaranteed with a custom
+OS so any data stored on the phone while the bootloader is unlocked may be at
+risk.
+</p>
+<p>
+To prevent unauthorized access to your personal data, unlocking the bootloader
+will also delete all personal data on your phone.
+</p>
+<p>
+Press the Volume Up/Volume Down to select whether to unlock the bootloader, then
+the power button to continue.
+</p>
+<p>
+Unlock
+</p>
+<p>
+Unlock bootloader.
+</p>
+<p>
+Don't unlock
+</p>
+<p>
+Do not unlock bootloader and restart phone.
+</p>
+<p> </p>
+ </td>
+ <td>
+<figure>
+ <p><strong>Example screen:</strong></p>
+ <img src="/security/images/unlock-confirmation.png"
+ alt="UNLOCK device warning screen">
+</figure>
+ </td>
+ </tr>
+ <tr>
+ <td>
+<h3 id="lock-confirmation">Lock confirmation</h3>
+<p>
+Show a lock confirmation screen in response to the <code>fastboot flashing
+lock</code> command being executed via the fastboot interface. Focus is
+initially on <em>Don't lock</em>. If the user hasn't interacted with the
+warning screen within 30 seconds, the screen disappears and the command fails.
+</p>
+<p>
+<strong>Text:</strong>
+</p>
+<p>
+If you lock the bootloader, you will not be able to install custom operating
+system software on this phone. To prevent unauthorized access to your personal
+data, locking the bootloader will also delete all personal data on your phone.
+</p>
+<p>
+Press the Volume Up/Volume Down to select whether to lock the bootloader, then
+the power button to continue.
+</p>
+<p>
+Lock
+</p>
+<p>
+Lock bootloader.
+</p>
+<p>
+Don't lock
+</p>
+<p>
+Do not lock bootloader and restart phone.
+</p>
+<p> </p>
+ </td>
+ <td>
+<figure>
+ <p><strong>Example screen:</strong></p>
+ <img src="/security/images/lock-confirmation.png"
+ alt="LOCK confirmation device warning screen">
+</figure>
+ </td>
+ </tr>
+</table>
+<h2 id="communicating-verified-boot-state-to-android">Communicating Verified
+Boot state to Android</h2>
+<p>
+The bootloader communicates Verified Boot state to Android through
+kernel-command options. It sets the <code>androidboot.verifiedstate</code>
+option to one of the following values:
+</p>
+<ul>
+ <li><code>green</code>: if device is <code>LOCKED</code> and user-settable
+ root of trust is not used</li>
+ <li><code>yellow</code>: if device is <code>LOCKED</code> and user-settable
+ root of trust is used</li>
+ <li><code>orange</code>: if device is <code>UNLOCKED</code></li>
+</ul>
+<p>
+The <code>androidboot.veritymode</code> option is set to <code>eio</code> or
+<code>restart</code> depending on which state the boot loader is in with respect
+to handling dm-verity errors. For more details, see <a
+href="/security/verifiedboot/verified-boot#handling-verification-errors">Handling
+verification errors</a>.
+</p>
+</body>
+</html>
diff --git a/en/security/verifiedboot/device-state.html b/en/security/verifiedboot/device-state.html
new file mode 100644
index 0000000..3c8bb9d
--- /dev/null
+++ b/en/security/verifiedboot/device-state.html
@@ -0,0 +1,129 @@
+<html devsite>
+ <head>
+ <title>Device State</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ <body>
+ <!--
+ Copyright 2018 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
+
+ //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 device state indicates how freely software can be flashed to a device and
+whether verification is enforced. Device states are <code>LOCKED</code> and
+<code>UNLOCKED</code>. <code>LOCKED</code> devices prevent you from flashing new
+software to the device, whereas <code>UNLOCKED</code> devices allow
+modification.
+</p>
+<p>
+When a device powers on, the bootloader first checks if a device is
+<code>LOCKED</code> or <code>UNLOCKED</code>. If a device is
+<code>UNLOCKED</code>, the bootloader shows the user a warning and then proceeds
+to boot even if the loaded OS isn't signed by the root of trust.
+</p>
+<p>
+If the device is <code>LOCKED</code>, the bootloader goes through the steps in
+<a href="/security/verifiedboot/verified-boot">Verifying Boot</a> to verify
+the device's software. <code>LOCKED</code> devices boot <em>only</em> if the
+loaded OS is properly signed by the root of trust. For more details, see
+<a href="/security/verifiedboot/boot-flow">The boot flow</a>.
+</p>
+
+<h2 id="changing-device-state">Changing device state</h2>
+<p>
+To <a href="/devices/bootloader/unlock-trusty">change a device's state</a>, use
+the <code>fastboot flashing [unlock | lock]</code> command. To protect user
+data, <em>all</em> state transitions wipe the data partitions and ask for user
+confirmation before data is deleted.
+</p>
+<p>
+The <code>UNLOCKED</code> to <code>LOCKED</code> transition is anticipated when
+a user buys a used development device. As a result of locking the device, the
+user should have confidence that it is in a state produced by the device
+manufacturer, as long as there is no warning. The <code>LOCKED</code> to
+<code>UNLOCKED</code> transition is expected when a developer wishes to disable
+verification on the device for development purposes.
+</p>
+
+<h2 id="root-of-trust">Root of Trust</h2>
+<p>
+<em>Root of trust</em> is the cryptographic key used to sign the copy of Android
+stored on the device. The private part of the root of trust is known only to the
+device manufacturer and is used to sign every version of Android intended for
+distribution. The public part of the root of trust is embedded in the device and
+is stored in a place so it cannot be tampered with (typically read-only
+storage).
+</p>
+<p>
+When it loads Android, the bootloader uses the root of trust to verify
+authenticity. For more details on this process, see
+<a href="/security/verifiedboot/verified-boot">Verifying Boot</a>. Devices may have
+multiple boot loaders and as such multiple cryptographic keys may be in play.
+</p>
+<h3 id="user-settable-root-of-trust">User-settable root of trust</h3>
+<p>
+Devices can optionally allow the user to configure the root of trust (for
+example, a public key). Devices can use this user-settable root of trust for
+Verified Boot instead of the built-in root of trust. This allows the user to
+install and use custom versions of Android without sacrificing the security
+improvements of Verified Boot.
+</p>
+<p>
+If user-settable root of trust is implemented, it should be done in a way such
+that:
+</p>
+<ul>
+ <li>Physical confirmation is required to set/clear the user-settable root of
+ trust.</li>
+ <li>The user-settable root of trust can only be set by the end user. It cannot
+ be set at the factory or any intermediate point before the end user gets the
+ device.</li>
+ <li>The user-settable root of trust is stored in tamper-evident storage.
+ <em>Tamper-evident</em> means that it's possible to detect if Android has
+ tampered with the data, for example, if it has been overwritten or changed.
+ </li>
+ <li>If an user-settable root of trust is set, the device should allow a version
+ of Android signed with either the built-in root of trust or the user-settable
+ root of trust to boot.</li>
+ <li>Every time the device boots using the user-settable root of trust, the user
+ should be notified that the device is loading a custom version of Android. For
+ example waring screens, see
+ <a href="/security/verifiedboot/boot-flow#locked-devices-with-custom-key-set"><code>LOCKED</code>
+ devices with custom key set</a>.</li>
+</ul>
+<p>
+One way of implementing user-settable root of trust is to have a virtual
+partition that can only be flashed or cleared when the device is in the
+<code>UNLOCKED</code> state. The Google Pixel 2 devices use this approach and
+the virtual partition is called <code>avb_custom_key</code>. The format of the
+data in this partition is the output of the
+<code>avbtool extract_public_key</code> command. Here's an example of how to set
+the user-settable root of trust:
+</p>
+
+
+<pre
+class="prettyprint"><code class="devsite-terminal">avbtool extract_public_key --key key.pem --output pkmd.bin</code>
+<code class="devsite-terminal">fastboot flash avb_custom_key pkmd.bin</code>
+</pre>
+<p>
+The user-settable root of trust can be cleared by issuing:
+</p>
+
+<pre
+class="devsite-terminal devsite-click-to-copy">fastboot erase avb_custom_key
+</pre>
+</body>
+</html>
diff --git a/en/security/verifiedboot/dm-verity.html b/en/security/verifiedboot/dm-verity.html
index 07e7821..cc8e445 100644
--- a/en/security/verifiedboot/dm-verity.html
+++ b/en/security/verifiedboot/dm-verity.html
@@ -21,6 +21,36 @@
limitations under the License.
-->
+<p>Android 4.4 and higher supports Verified Boot through the optional
+device-mapper-verity (dm-verity) kernel feature, which provides transparent
+integrity checking of block devices. dm-verity helps prevent persistent rootkits
+that can hold onto root privileges and compromise devices. This
+feature helps Android users be sure when booting a device it is in the same
+state as when it was last used.</p>
+<p>Potentially Harmful Applications (PHAs) with root privileges can hide from
+detection programs and otherwise mask themselves. The rooting software can do
+this because it is often more privileged than the detectors, enabling the
+software to "lie" to the detection programs.</p>
+
+<p>The dm-verity feature lets you look at a block device, the underlying storage
+layer of the file system, and determine if it matches its expected
+configuration. It does this using a cryptographic hash tree. For every block
+(typically 4k), there is a SHA256 hash.</p>
+
+<p>Because the hash values are stored in a tree of pages, only the top-level
+"root" hash must be trusted to verify the rest of the tree. The ability to
+modify any of the blocks would be equivalent to breaking the cryptographic hash.
+See the following diagram for a depiction of this structure.</p>
+
+<img src="../images/dm-verity-hash-table.png" alt="dm-verity-hash-table" id="figure1"/>
+<p class="img-caption">
+ <strong>Figure 1.</strong> dm-verity hash table
+</p>
+
+<p>A public key is included on the boot partition, which must be verified
+externally by the device manufacturer. That key is used to verify the signature
+for that hash and confirm the device's system partition is protected and
+unchanged.</p>
<h2 id="operation">Operation</h2>
@@ -33,9 +63,10 @@
<p>Manufacturers use that key to verify the signature on the first-level
bootloader, which in turn verifies the signature on subsequent levels, the
application bootloader and eventually the kernel. Each manufacturer wishing to
-take advantage of <a href="verified-boot.html">verified boot</a> should have a
-method for verifying the integrity of the kernel. Assuming the kernel has been
-verified, the kernel can look at a block device and verify it as it is mounted.</p>
+take advantage of <a href="/security/verifiedboot/verified-boot.html">verified
+boot</a> should have a method for verifying the integrity of the kernel.
+Assuming the kernel has been verified, the kernel can look at a block device
+and verify it as it is mounted.</p>
<p>One way of verifying a block device is to directly hash its contents and compare
them to a stored value. However, attempting to verify an entire block device can
@@ -56,6 +87,17 @@
those results are not required to the application's primary function. However,
if the application cannot continue without the data, it will fail.</p>
+<h2 id="fec">Forward error correction</h2>
+
+Android 7.0 and higher improves dm-verity robustness with forward error
+correction (FEC). The AOSP implementation starts with the the common
+<a href="https://en.wikipedia.org/wiki/Reed%E2%80%93Solomon_error_correction"
+ class="external">Reed-Solomon</a> error-correcting code and applies a
+technique called interleaving to reduce space overhead and increase the
+number of corrupted blocks that can be recovered. For more details on FEC, see
+<a href="https://android-developers.googleblog.com/2016/07/strictly-enforced-verified-boot-with.html"
+ class="external">Strictly Enforced Verified Boot with Error Correction</a>.
+
<h2 id="implementation">Implementation</h2>
<h3 id="summary">Summary</h3>
@@ -71,15 +113,16 @@
<li>Concatenate the system image, the verity metadata, and the hash tree.</li>
</ol>
-<p>See the <a href="http://www.chromium.org/chromium-os/chromiumos-design-docs/verified-boot">The Chromium Projects - Verified
-Boot</a>
+<p>See the <a
+href="http://www.chromium.org/chromium-os/chromiumos-design-docs/verified-boot"
+class="external">The Chromium Projects - Verified Boot</a>
for a detailed description of the hash tree and dm-verity table.</p>
<h3 id="hash-tree">Generating the hash tree</h3>
-<p>As described in the <a href="#introduction">Introduction</a>, the hash tree is
-integral to dm-verity. The
-<a href="https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity">cryptsetup</a> tool will
+<p>As described in the introduction, the hash tree is integral to dm-verity. The
+<a href="https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity"
+ class="external">cryptsetup</a> tool will
generate a hash tree for you. Alternatively, a compatible one is defined here:</p>
<pre class="devsite-click-to-copy">
@@ -131,7 +174,8 @@
the size of the blocks and the hash_start, the start location of the hash tree
(specifically, its block number from the beginning of the image).</p>
-<p>See <a href="https://code.google.com/p/cryptsetup/wiki/DMVerity">cryptsetup</a> for a
+<p>See <a href="https://code.google.com/p/cryptsetup/wiki/DMVerity"
+class="external">cryptsetup</a> for a
detailed description of the verity target mapping table fields.</p>
<h3 id="signing">Signing the dm-verity table</h3>
diff --git a/en/security/verifiedboot/index.html b/en/security/verifiedboot/index.html
index 6c9a428..f83178f 100644
--- a/en/security/verifiedboot/index.html
+++ b/en/security/verifiedboot/index.html
@@ -20,71 +20,47 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-
-
-
-<p>Android 4.4 and later supports verified boot through the optional
-device-mapper-verity (dm-verity) kernel feature, which provides transparent
-integrity checking of block devices. dm-verity helps prevent persistent rootkits
-that can hold onto root privileges and compromise devices. This
-feature helps Android users be sure when booting a device it is in the same
-state as when it was last used.</p>
-
-<p>Clever malware with root privileges can hide from detection programs and
-otherwise mask themselves. The rooting software can do this because it is often
-more privileged than the detectors, enabling the software to "lie" to the
-detection programs.</p>
-
-<p>The dm-verity feature lets you look at a block device, the underlying storage
-layer of the file system, and determine if it matches its expected
-configuration. It does this using a cryptographic hash tree. For every block
-(typically 4k), there is a SHA256 hash.</p>
-
-<p>Because the hash values are stored in a tree of pages, only the top-level
-"root" hash must be trusted to verify the rest of the tree. The ability to
-modify any of the blocks would be equivalent to breaking the cryptographic hash.
-See the following diagram for a depiction of this structure.</p>
-
-<img src="../images/dm-verity-hash-table.png" alt="dm-verity-hash-table" id="figure1"/>
-<p class="img-caption">
- <strong>Figure 1.</strong> dm-verity hash table
+<p>
+Verified Boot strives to ensure all executed code comes from a trusted source
+(usually device OEMs), rather than from an attacker or corruption. It
+establishes a full chain of trust, starting from a hardware-protected root of
+trust to the bootloader, to the boot partition and other verified partitions
+including <code>system</code>, <code>vendor</code>, and optionally
+<code>oem</code> partitions. During device boot up, each stage verifies the
+integrity and authenticity of the next stage before handing over execution.
</p>
-
-<p>A public key is included on the boot partition, which must be verified
-externally by the OEM. That key is used to verify the signature for that hash
-and confirm the device's system partition is protected and unchanged.</p>
-
-<h2 id="prerequisites">Prerequisites</h2>
-
-<h3 id="verified-boot">Establishing a verified boot flow</h3>
-<p>To greatly reduce the risk of compromise, verify the kernel using a key
-burned into the device. For details, see <a href="verified-boot.html">Verifying
-boot</a>.</p>
-
-<h3 id="block-otas">Switching to block-oriented OTAs</h3>
-<p>To enable dm-verity for a device, you must use block-based over-the-air
-(OTA) updates to ensure all devices use the same system partition. For details,
-see <a href="/devices/tech/ota/block.html">Block-Based OTAs</a>.</p>
-
-<h3 id="config-dm-verity">Configuring dm-verity</h3>
-
-<p>After switching to block-oriented OTAs, incorporate the latest Android kernel
-or use a stock upstream kernel and enable dm-verity support by including the
-relevant configuration option <code>CONFIG_DM_VERITY</code>.</p>
-
-<p>When using the Android kernel, dm-verity is turned on when the kernel is
-built. For details, see <a href="dm-verity.html">Implementing dm-verity</a>.</p>
-
-<h2 id="supporting-docs">Supporting documentation</h2>
-<p><a href="verified-boot.html">Verifying Boot</a><br/>
-<a href="/devices/tech/ota/block.html">Block-Based OTA</a><br/>
-<a href="dm-verity.html">Implementing dm-verity</a><br/>
-<a href="https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity">cryptsetup -
-dm-verity: device-mapper block integrity checking target</a><br/>
-<a href="http://www.chromium.org/chromium-os/chromiumos-design-docs/verified-boot">The
-Chromium Projects - Verified Boot</a><br/>
-<a
-href="http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob;f=Documentation/device-mapper/verity.txt">Linux Kernel Documentation: verity.txt</a></p>
+<p>
+In addition to ensuring that devices are running a safe version of Android,
+Verified Boot check for the correct version of Android with
+<a href="/security/verifiedboot/verified-boot#rollback-protection">rollback
+protection</a>. Rollback protection helps to prevent a possible
+exploit from becoming persistent by ensuring devices only update to newer
+versions of Android.
+</p>
+<p>
+In addition to verifying the OS, Verified Boot also allows Android devices to
+communicate their state of integrity to the user.
+</p>
+<h2 id="background">Background</h2>
+<p>
+Android 4.4 added support for Verified Boot and the
+<a href="/security/verifiedboot/dm-verity">dm-verity</a> kernel feature. This
+combination of verifying features served as Verified Boot 1.
+</p>
+<p>
+Where previous versions of Android warned users about device corruption, but
+still allowed them to boot their devices, Android 7.0 started strictly enforcing
+Verified Boot to prevent compromised devices from booting. Android 7.0 also
+added support for forward error correction to improve reliability against
+non-malicious data corruption.
+</p>
+<p>
+Android 8.0 and higher includes
+<a href="/security/verifiedboot/avb">Android Verified Boot</a> (AVB), a
+reference implementation of Verified Boot that works with Project Treble. In
+addition to working with Treble, AVB standardized partition footer format and
+added rollback protection features.
+</p>
</body>
</html>
diff --git a/en/security/verifiedboot/verified-boot.html b/en/security/verifiedboot/verified-boot.html
index dada3c4..c373bf4 100644
--- a/en/security/verifiedboot/verified-boot.html
+++ b/en/security/verifiedboot/verified-boot.html
@@ -6,13 +6,13 @@
</head>
<body>
<!--
- Copyright 2017 The Android Open Source Project
+ Copyright 2018 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
+ //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,
@@ -22,522 +22,92 @@
-->
-
-<p>Verified boot guarantees the integrity of the device software starting from a
-hardware root of trust up to the system partition. During boot, each stage
-verifies the integrity and authenticity of the next stage before executing it.</p>
-
-<p>This capability can be used to warn users of unexpected changes to the
-software when they acquire a used device, for example. It will also provide an
-additional signal of device integrity for remote attestation, and together with
-encryption and Trusted Execution Environment (TEE) root of trust binding, adds
-another layer of protection for user data against malicious system software.</p>
-
-<p>If verification fails at any stage, the user is visibly
-notified.</p>
-
-<h2 id=glossary>Glossary</h2>
-
-<table>
- <col width="15%">
- <col width="85%">
- <tr>
- <th>Term</th>
- <th>Definition</th>
- </tr>
- <tr>
- <td>Boot state</td>
- <td>The boot state of the device describes the level of protection provided
- to the end user if the device boots. Boot states are GREEN, YELLOW,
- ORANGE, and RED.</td>
- </tr>
- <tr>
- <td>Device state</td>
- <td>The device state indicates how freely software can be flashed to the device.
- Device states are LOCKED and UNLOCKED.</td>
- </tr>
- <tr>
- <td>dm-verity</td>
- <td>Linux kernel driver for verifying the integrity of a partition at runtime using
- a hash tree and signed metadata.</td>
- </tr>
- <tr>
- <td>OEM key</td>
- <td>The OEM key is a fixed, tamper-protected key available to the bootloader that
- must be used to verify the boot image.</td>
- </tr>
-</table>
-
-<h2 id=overview>Overview</h2>
-
-<p>In addition to device state—which already exists in devices and controls
-whether the bootloader allows new software to be flashed—verified boot introduces
-the concept of boot state that indicates the state of device integrity.</p>
-
-<h3 id=classes>Classes</h3>
-
-<p>Two implementation classes exist for verified boot. Depending on how
-fully the device implements this specification, they are defined as follows:</p>
-
-<p><strong>Class A</strong> implements verified boot with full chain of trust
-up to verified partitions. In other words, the implementation supports the
-LOCKED device state, and GREEN and RED boot states.</p>
-
-<p><strong>Class B</strong> implements Class A, and additionally supports the
-UNLOCKED device state and the ORANGE boot state.</p>
-
-<h3 id=verification_keys>Verification keys</h3>
-
-<p>Bootloader integrity is always verified using a hardware root of trust. For
-verifying boot and recovery partitions, the bootloader has a fixed OEM key
-available to it. It always attempts to verify the boot partition using the OEM
-key first and try other possible keys only if this verification fails.</p>
-
-<p>In Class B implementations, it is possible for the user to flash
-software signed with other keys when the device is UNLOCKED. If the device is
-then LOCKED and verification using the OEM key fails, the bootloader tries
-verification using the certificate embedded in the partition signature.
-However, using a partition signed with anything other than the OEM key
-results in a notification or a warning, as described below.</p>
-
-<h3 id=boot_state>Boot state</h3>
-
-<p>A verified device will ultimately boot into one of the four states during
-each boot attempt:</p>
-
-<ul>
- <li>GREEN, indicating a full chain of trust extending from the bootloader to
-verified partitions, including the bootloader, boot partition, and all verified
-partitions.
-
- <li>YELLOW, indicating the boot partition has been verified using the
-embedded certificate, and the signature is valid. The bootloader
-displays a warning and the fingerprint of the public key before allowing
-the boot process to continue.
-
- <li>ORANGE, indicating a device may be freely modified. Device integrity is
-left to the user to verify out-of-band. The bootloader displays a warning
-to the user before allowing the boot process to continue.
-
- <li>RED, indicating the device has failed verification. The bootloader
-displays a warning and stops the boot process.
-</ul>
-
-<p>The recovery partition is verified in the exact same way, as well.</p>
-
-<h3 id=device_state>Device state</h3>
-
-<p>The possible device states and their relationship with the four verified
-boot states are:</p>
-<ol>
- <li>LOCKED, indicating the device cannot be flashed. A LOCKED device
-boots into the GREEN, YELLOW, or RED states during any attempted boot.
-
- <li>UNLOCKED, indicating the device may be flashed freely and is not intended
-to be verified. An UNLOCKED device always boots to the ORANGE boot state.
-</ol>
-
-<img src="../images/verified_boot.png" alt="Verified boot flow" id="figure1" />
-<p class="img-caption"><strong>Figure 1.</strong> Verified boot flow</p>
-
-<h2 id=detailed_design>Detailed design</h2>
-
-<p>Achieving full chain of trust requires support from both the bootloader and the
-software on the boot partition, which is responsible for mounting further
-partitions. Verification metadata is also appended to the system partition
-and any additional partitions whose integrity should be verified.</p>
-
-<h3 id=bootloader_requirements>Bootloader requirements</h3>
-
-<p>The bootloader is the guardian of the device state and is responsible for
-initializing the TEE and binding its root of trust.</p>
-
-<p>Most importantly, the bootloader verifies the integrity of the boot and/or
-recovery partition before moving execution to the kernel and display the
-warnings specified in the section <a href="#boot_state">Boot state</a>.</p>
-
-<h4 id=changing_device_state>Changing device state</h4>
-
-<p>State changes are performed using the <code>fastboot flashing [unlock |
-lock]</code> command. And to protect user data, <strong>all</strong>
-state transitions wipe the data partitions and ask the user for
-confirmation before data is deleted.</p>
-
-<ol>
- <li>The UNLOCKED to LOCKED transition is anticipated when a user buys a used
-development device. As a result of locking the device, the user should have
-confidence that it is in a state produced by the device manufacturer, as long
-as there is no warning.
-
- <li>The LOCKED to UNLOCKED transition is expected in the case where a developer
-wishes to disable verification on the device.
-</ol>
-
-
-<p><code>fastboot</code> commands that alter device state are listed in the table below:</p>
-
-<table>
- <col width="25%">
- <col width="75%">
- <tr>
- <th><code>fastboot</code> command</th>
- <th>Description</th>
- </tr>
- <tr>
- <td><code>flashing lock</code></td>
- <td>
- <ul>
- <li>Wipes data after asking the user for confirmation.
- <li>Clears a write-protected bit to lock the device.
- Because the bit is write-protected, only the
- bootloader can change it.
- </ul>
- </td>
- </tr>
- <tr>
- <td><code>flashing unlock</code></td>
- <td>
- <ul>
- <li>If the unlock device setting has not been enabled by the user,
- aborts unlocking
- <li>Wipes data after asking the user for confirmation
- <li>Sets a write-protected bit to unlock the device.
- Because the bit is write-protected, only the
- bootloader can change it.
- </ul>
- </td>
- </tr>
-</table>
-
-<p>When altering partition contents, the bootloader checks the bits set by
-the above commands as described in the following table:</p>
-
-<table>
- <col width="25%">
- <col width="75%">
- <tr>
- <th><code>fastboot</code> command</th>
- <th>Description</th>
- </tr>
- <tr>
- <td><code>flash <partition></code></td>
- <td>If the bit set by <code>flashing unlock</code> is set, flash the
- partition. Otherwise, do not allow flashing.
- </td>
- </tr>
-</table>
-
-<p>The same checks should be performed for any <code>fastboot</code> command
-that can be used to change the contents of partitions.</p>
-
-<p class="note"><strong>Note</strong>: Class B implementations support
-changing device state.</p>
-
-<h4 id=binding_tee_root_of_trust>Binding TEE root of trust</h4>
-
-<p>If TEE is available, the bootloader passes the following information to
-the TEE after boot/recovery partition verification and TEE initialization
-to bind the Keymaster root of trust:</p>
-
-<ol>
- <li>the public key that was used to sign the boot partition
- <li>the current device state (LOCKED or UNLOCKED)
-</ol>
-
-<p>This changes the keys derived by the TEE. Taking disk encryption as an example,
-this prevents user data from being decrypted when the device state changes.</p>
-
-<p class="note"><strong>Note:</strong> This means if the system software or the
-device state changes, encrypted user data will no longer be accessible as the
-TEE will attempt to use a different key to decrypt the data.</p>
-
-<h4 id="initializing-attestation">Initializing attestation</h4>
<p>
-Similar to root of trust binding, if TEE is available, the bootloader passes it
-the following information to initialize attestation:
-</p>
-<ol>
-<li>the current boot state (GREEN, YELLOW, ORANGE)
-<li>the operating system version
-<li>the operating system security patch level
-</ol>
-<h4 id=booting_into_recovery>Booting into recovery</h4>
-
-<p>The recovery partition should be verified in exactly the same manner as the
-boot partition.</p>
-
-<h4 id=comm_boot_state>Communicating boot state</h4>
-
-<p>System software needs to be able to determine the verification status of
-previous stages. The bootloader specifies the current boot state as a
-parameter on the kernel command line (or through the device tree under
-<code>firmware/android/verifiedbootstate</code>) as described in the table
-below:</p>
-
-<table>
- <tr>
- <th>Kernel command line parameter</th>
- <th>Description</th>
- </tr>
- <tr>
- <td><code>androidboot.verifiedbootstate=green</code></td>
- <td>Device has booted into GREEN boot state.<br>
- Boot partition has been verified using the OEM key and it’s valid.</td>
- </tr>
- <tr>
- <td><code>androidboot.verifiedbootstate=yellow</code></td>
- <td>Device has booted into YELLOW boot state.<br>
- Boot partition has been verified using the certificate embedded into
- the signature and it’s valid.</td>
- </tr>
- <tr>
- <td><code>androidboot.verifiedbootstate=orange</code></td>
- <td>Device has booted into ORANGE boot state.<br>
- The device is unlocked and no verification has been performed.</td>
- </tr>
-</table>
-<p class="note"><strong>Note</strong>: The device cannot boot into kernel when
-in the RED boot state, and therefore the kernel command line never includes the
-parameter <code>androidboot.verifiedbootstate=red</code>.</p>
-
-<h3 id=boot_partition>Boot partition</h3>
-
-<p>Once execution has moved to the boot partition, the software there is responsible
-for setting up verification of further partitions. Due to its large size, the
-system partition typically cannot be verified similarly to previous parts but is
-verified as it’s being accessed instead using the dm-verity kernel driver or a
-similar solution.</p>
-
-<p>If dm-verity is used to verify large partitions, the signature of the verity
-metadata appended to each verified partition is verified before the
-partition is mounted and dm-verity is set up for it.</p>
-
-<h4 id=managing_dm-verity>Managing dm-verity</h4>
-
-<p>Implemented as a device mapper target in kernel, dm-verity adds a layer
-on top of a partition and verifies each read block against a hash tree passed to
-it during setup. If it comes across a block that fails to verify, it makes the
-block inaccessible to user space.</p>
-
-<p>When mounting partitions during boot, fs_mgr sets up dm-verity for a
-partition if the <code>verify</code> fs_mgr flag is specified for it in the
-device’s fstab. Verity metadata signature is verified against the public key
-in <code>/verity_key</code>.</p>
-
-<h4 id=recovering_from_dm-verity_errors>Recovering from dm-verity errors</h4>
-
-<p>Because the system partition is by far larger than the boot partition, the
-probability of verification errors is also higher. Specifically, there is a
-larger probability of unintentional disk corruption, which will cause a
-verification failure and can potentially make an otherwise functional device
-unusable if a critical block in the partition can no longer be accessed.
-Forward error correction can be used with dm-verity to mitigate this risk.
-Providing this alternative recovery path is recommended, though it comes at the
-expense of increasing metadata size.</p>
-
-<p>
-By default, dm-verity is configured to function in a “restart” mode where it
-immediately restarts the device when a corrupted block is detected. This makes
-it possible to safely warn the user when the device is corrupted, or to fall
-back to device specific recovery, if available.
+Verified boot requires cryptographically verifying all executable code and data
+that is part of the Android version being booted before it is used. This includes
+the kernel (loaded from the <code>boot</code> partition), the device tree (loaded
+from the <code>dtbo</code> partition), <code>system</code> partition,
+<code>vendor</code> partition, and so on.
</p>
<p>
-To make it possible for users to still access their data, dm-verity switches
-to I/O Error (EIO) mode if the device boots with known corruption. When in EIO mode,
-dm-verity returns I/O errors for any reads that access corrupted blocks but
-allows the device to keep running. Keeping track of the current mode requires
-persistently storing dm-verity state. The state can be managed either by fs_mgr
-or the bootloader:
+Small partitions, such as <code>boot</code> and <code>dtbo</code>, that are read
+only once are typically verified by loading the entire contents into memory and
+then calculating its hash. This calculated hash value is then compared to the
+<em>expected hash value</em>. If the value doesn't match, Android won't load.
+For more details, see <a href="/security/verifiedboot/boot-flow">Boot Flow</a>.
</p>
-
-<ol>
- <li>To manage dm-verity state in fs_mgr, an additional argument is specified to
- the <code>verify</code> flag to inform fs_mgr where to store dm-verity state.
- For example, to store the state on the metadata partition, specify
- <code>verify=/path/to/metadata</code>.
- <p class="note"><strong>Note:</strong> fs_mgr switches dm-verity to EIO
- mode after the first corruption has been detected and resets the mode
- back to “restart” after the metadata signature of any verified partition
- has changed.</p>
- </li>
- <li>Alternatively, to manage dm-verity state in the bootloader, pass the current
- mode to the kernel in the <code>androidboot.veritymode</code> command line
- parameter as follows:
-
- <table>
- <tr>
- <th>Kernel command line parameter</th>
- <th>Description</th>
- </tr>
- <tr>
- <td><code>androidboot.veritymode=enforcing</code></td>
- <td>Set up dm-verity in the default “restart” mode.</td>
- </tr>
- <tr>
- <td><code>androidboot.veritymode=eio</code></td>
- <td>Set up dm-verity in EIO mode.</td>
- </tr>
- </table>
-
- <p class="note">
- <strong>Note:</strong> Managing state in the bootloader also requires the kernel
- to set the restart reason correctly when the device restarts due to dm-verity.
- After corruption has been detected, the bootloader should switch back to
- “restart” mode when any of the verified partitions have changed.</p>
- </li>
-</ol>
-
<p>
-If dm-verity is not started in the “restart” mode for any reason, or verity
-metadata cannot be verified, a warning displays to the user if the device is
-allowed to boot, similar to the one shown before booting into the RED boot
-state. The user must consent to the device to continue booting in EIO mode. If
-user consent is not received in 30 seconds, the device powers off.
+Larger partitions that won't fit into memory (such as, file systems) may use
+a hash tree where verification is a continuous process happening as data is
+loaded into memory. In this case, the root hash of the hash tree is calculated
+during run time and is checked against the <em>expected root hash value</em>.
+Android includes the <a href="/security/verifiedboot/dm-verity">dm-verity
+driver</a> to verify larger partitions. If at some point the calculated root
+hash doesn't match the <em>expected root hash value</em>, the data is not used
+and Android enters an error state. For more details, see
+<a href="/security/verifiedboot/boot-flow#dm-verity-corruption">dm-verity
+corruption</a>.
+</p>
+<p>
+The <em>expected hashes</em> are typically stored at either the end or beginning
+of each verified partition, in a dedicated partition, or both. Crucially, these
+hashes are signed (either directly or indirectly) by the root of trust. As an
+example, the AVB implementation supports both approaches, see
+<a href="/security/verifiedboot/avb">Android Verified Boot</a> for details.
</p>
-<p class="note">
-<strong>Note:</strong> dm-verity never starts in logging mode to prevent
-unverified data from leaking into userspace.
+<h2 id="rollback-protection">Rollback protection</h2>
+<p>
+Even with a completely secure update process, it's possible for a non-persistent
+Android kernel exploit to manually install an older, more vulnerable version of
+Android, reboot into the vulnerable version, and then use that Android version to
+install a persistent exploit. From there the attacker permanently owns the device
+and can do anything, including disabling updates.
+</p>
+<p>
+The protection against this class of attacks is called <em>Rollback
+Protection</em>. Rollback protection is typically implemented by using
+tamper-evident storage to record the most recent version of the Android and
+refusing to boot Android if it's lower than the recorded version. Versions
+are typically tracked on a per-partition basis.
+</p>
+<p>
+For more details on how AVB handles rollback protections, see the AVB
+<a href="https://android.googlesource.com/platform/external/avb/+/master/README.md#Rollback-Protection"
+class="external">README</a>.
</p>
-
-
-<h3 id=verified_partition>Verified partition</h3>
-
-<p>In a verified device, the system partition is always verified. But any
-other read-only partition should also be set to be verified, as well. Any
-read-only partition that contains executable code is verified on a
-verified device. This includes vendor and OEM partitions, if they exist, for example.</p>
-
-<p>To verify a partition, signed verity metadata is
-appended to it. The metadata consists of a hash tree of the partition contents
-and a verity table containing signed parameters and the root of the hash tree.
-If this information is missing or invalid when dm-verity is set up for the
-partition, the device doesn't boot.</p>
-
-<h2 id=implementation_details>Implementation details</h2>
-
-<h3 id=key_types_and_sizes>Key types and sizes</h3>
-
-<p>The OEM key used in AOSP is an RSA key with a modulus of 2048 bits or
-higher and a public exponent of 65537 (F4), meeting the CDD requirements of
-equivalent or greater strength than such a key.</p>
-
-<p>Note that the OEM key typically cannot be rotated if it's compromised, so
-protecting it is important, preferably using a Hardware Security Module (HSM)
-or a similar solution. It's also recommended to use a different key for each
-type of device.</p>
-
-<h3 id=signature_format>Signature format</h3>
-
-<p>The signature on an Android verifiable boot image is an ASN.1 DER-encoded
-message, which can be parsed with a decoder similar to the one found at: <a
-href="https://android.googlesource.com/platform/bootable/recovery/+/master/asn1_decoder.cpp"
-class="external"><code>platform/bootable/recovery/asn1_decoder.cpp</code></a><br/>
-The message format itself is as follows:</p>
-
-<pre class="devsite-click-to-copy">
-AndroidVerifiedBootSignature DEFINITIONS ::=
- BEGIN
- FormatVersion ::= INTEGER
- Certificate ::= Certificate
- AlgorithmIdentifier ::= SEQUENCE {
- algorithm OBJECT IDENTIFIER,
- parameters ANY DEFINED BY algorithm OPTIONAL
- }
- AuthenticatedAttributes ::= SEQUENCE {
- target CHARACTER STRING,
- length INTEGER
- }
-
- Signature ::= OCTET STRING
- END
-</pre>
-
-<p>The <code>Certificate</code> field is the full X.509 certificate containing
-the public key used for signing, as defined by <a
-href="http://tools.ietf.org/html/rfc5280#section-4.1.1.2">RFC5280</a> section
-4.1. When LOCKED, the bootloader uses the OEM key for verification
-first, and only boot to YELLOW or RED states if the embedded certificate is
-used for verification instead.</p>
-
-<p>The remaining structure is similar to that defined by <a
-href="http://tools.ietf.org/html/rfc5280#section-4.1.1.2">RFC5280</a> sections
-4.1.1.2 and 4.1.1.3 with the exception of the
-<code>AuthenticatedAttributes</code> field. This field contains the length of
-the image to be verified as an integer and the partition where the image can
-be found (boot, recovery, etc.).</p>
-
-<h3 id=signing_and_verifying_an_image>Signing and verifying an image</h3>
-
-<p><strong>To produce a signed image:</strong></p>
-<ol>
- <li>Generate the unsigned image.
- <li>0-pad the image to the next page size boundary (omit this step if already
-aligned).
- <li>Populate the fields of the <code>AuthenticatedAttributes</code> section
- above based on the padded image and desired target partition.
- <li>Append the <code>AuthenticatedAttributes</code> structure above to the image.
- <li>Sign the image.
-</ol>
-
-<p><strong>To verify the image:</strong></p>
-<ol>
- <li>Determine the size of the image to be loaded including padding (e.g. by reading
-a header).
- <li>Read the signature located at the offset above.
- <li>Validate the contents of the <code>AuthenticatedAttributes</code> field.
- If these values do not validate, treat it as a signature validation error.
- <li>Verify the image and <code>AuthenticatedAttributes</code> sections.
-</ol>
-
-<h3 id=user_experience>User experience</h3>
-
-<p>A user in the GREEN boot state should see no additional user interaction besides that
-required by normal device boot. In ORANGE and YELLOW boot states, the user sees a
-warning for at least five seconds. Should the user interact with the device during
-this time, the warning remains visible at least 30 seconds longer, or until
-the user dismisses the warning. In the RED boot state, the warning is shown for
-at least 30 seconds, after which the device powers off.</p>
-
-<p>Sample user interaction screens for other states are shown in the following table:</p>
-
-<table>
- <tr>
- <th>Device state</th>
- <th>Sample UX</th>
- <th> </th>
- </tr>
- <tr>
- <td>YELLOW</td>
- <td><img src="../images/boot_yellow1.png" alt="Yellow device state 1" id="figure2" />
- <p class="img-caption"><strong>Figure 2.</strong> Before user interaction</p>
- </td>
- <td><img src="../images/boot_yellow2.png" alt="Yellow device state 2" id="figure3" />
- <p class="img-caption"><strong>Figure 3.</strong> After user interaction</p>
- </td>
- </tr>
- <tr>
- <td>ORANGE</td>
- <td><img src="../images/boot_orange.png" alt="Orange device state" id="figure4" />
- <p class="img-caption"><strong>Figure 4.</strong> Warning that device is
- unlocked and can’t be verified.</p>
- </td>
- <td> </td>
- </tr>
- <tr>
- <td>RED</td>
- <td><img src="../images/boot_red1.png" alt="Red device state" id="figure5" />
- <p class="img-caption"><strong>Figure 5.</strong> Verified boot failure
- warning</p>
- </td>
- <td><img src="../images/boot_red2.png" alt="Red device state" id="figure6" />
- <p class="img-caption"><strong>Figure 6.</strong> Booting into EIO mode
- warning</p>
- </td>
- </tr>
-</table>
-
- </body>
+<h2 id="handling-verification-errors">Handling verification errors</h2>
+<p>
+Verification can fail either at boot time (such as, if the calculated hash on
+<code>boot</code> partition doesn't match the expected hash) or at run time
+(such as, if dm-verity encounters a verification error on the
+<code>system</code> partition). If verification fails at boot time, the device
+cannot boot and the end user needs to go through steps to recover the device.
+</p>
+<p>
+If verification fails at run-time the flow is a bit more complicated. If the
+device uses dm-verity, it should be configured in <code>restart</code> mode. In
+<code>restart</code> mode, if a verification error is encountered, the device is
+immediately restarts with a specific flag set to indicate the reason. The boot
+loader should notice this flag and switch dm-verity over to use I/O Error
+(<code>eio</code>) mode and stay in this mode until a new update has been
+installed.
+</p>
+<p>
+When booting in <code>eio</code> mode, the device shows an error screen
+informing the user that corruption has been detected and the device may not
+function correctly. The screen shows until the user dismisses it. In
+<code>eio</code> mode the dm-verity driver will not restart the device if a
+verification error is encountered, instead an EIO error is returned and the
+application needs to deal with the error.
+</p>
+<p>
+The intent is that either the system updater will run (so a new OS without
+corruption errors can be installed) or the user can get as much of their data
+off the device as possible. Once the new OS has been installed, the boot loader
+notices the newly installed OS and switches back to <code>restart</code> mode.
+</p>
+</body>
</html>
diff --git a/en/setup/_toc-build.yaml b/en/setup/_toc-build.yaml
new file mode 100644
index 0000000..b5fae85
--- /dev/null
+++ b/en/setup/_toc-build.yaml
@@ -0,0 +1,13 @@
+toc:
+- title: Use Reference Boards
+ path: /setup/build/devices
+- title: Find Generic System Images
+ path: /setup/build/gsi
+- title: Compile with Jack
+ path: /setup/build/jack
+- title: Run Builds
+ path: /setup/build/running
+- title: Build Kernels
+ path: /setup/build/building-kernels
+- title: See Known Issues
+ path: /setup/build/known-issues
diff --git a/en/setup/_toc-contact.yaml b/en/setup/_toc-contact.yaml
new file mode 100644
index 0000000..821687c
--- /dev/null
+++ b/en/setup/_toc-contact.yaml
@@ -0,0 +1,3 @@
+toc:
+- title: Community
+ path: /setup/community
diff --git a/en/setup/_toc-contribute.yaml b/en/setup/_toc-contribute.yaml
new file mode 100644
index 0000000..3d15116
--- /dev/null
+++ b/en/setup/_toc-contribute.yaml
@@ -0,0 +1,17 @@
+toc:
+- title: Overview
+ path: /setup/contribute/
+- title: Life of a Patch
+ path: /setup/contribute/life-of-a-patch
+- title: Submitting Patches
+ path: /setup/contribute/submit-patches
+- title: View Patches
+ path: /setup/contribute/view-patches
+- title: Life of a Bug
+ path: /setup/contribute/life-of-a-bug
+- title: Reporting Bugs
+ path: /setup/contribute/report-bugs
+- title: Reading Bug Reports
+ path: /setup/contribute/read-bug-reports
+- title: Java Code Style Rules
+ path: /setup/contribute/code-style
diff --git a/en/setup/_toc-create.yaml b/en/setup/_toc-create.yaml
new file mode 100644
index 0000000..893d743
--- /dev/null
+++ b/en/setup/_toc-create.yaml
@@ -0,0 +1,9 @@
+toc:
+- title: Overview
+ path: /setup/develop/
+- title: Using Repo
+ path: /setup/develop/repo
+- title: Adding a New Device
+ path: /setup/develop/new-device
+- title: Understanding 64-bit Builds
+ path: /setup/develop/64-bit-builds
diff --git a/en/setup/_toc-download.yaml b/en/setup/_toc-download.yaml
new file mode 100644
index 0000000..d339677
--- /dev/null
+++ b/en/setup/_toc-download.yaml
@@ -0,0 +1,9 @@
+toc:
+- title: Requirements
+ path: /setup/build/requirements
+- title: Establishing a Build Environment
+ path: /setup/build/initializing
+- title: Downloading the Source
+ path: /setup/build/downloading
+- title: Preparing to Build
+ path: /setup/build/building
diff --git a/en/setup/_toc-start.yaml b/en/setup/_toc-start.yaml
new file mode 100644
index 0000000..d38f52d
--- /dev/null
+++ b/en/setup/_toc-start.yaml
@@ -0,0 +1,17 @@
+toc:
+- title: Codelines, Branches, and Releases
+ path: /setup/start/codelines
+- title: Codenames, Tags, and Build Numbers
+ path: /setup/start/build-numbers
+- title: Project Roles
+ path: /setup/start/roles
+- title: Brand Guidelines
+ path: /setup/start/brands
+- title: Licenses
+ path: /setup/start/licenses
+- title: FAQ
+ path: /setup/start/faqs
+- title: Android 9 Release Notes
+ path: /setup/start/p-release-notes
+- title: Site Updates
+ path: /setup/start/site-updates
diff --git a/en/setup/_toc.yaml b/en/setup/_toc.yaml
deleted file mode 100644
index b82fb73..0000000
--- a/en/setup/_toc.yaml
+++ /dev/null
@@ -1,69 +0,0 @@
-toc:
-- title: Overview
- path: /setup/
-- title: Getting Started
- section:
- - title: Codelines, Branches, and Releases
- path: /setup/start/codelines
- - title: Codenames, Tags, and Build Numbers
- path: /setup/start/build-numbers
- - title: Project Roles
- path: /setup/start/roles
- - title: Brand Guidelines
- path: /setup/start/brands
- - title: Licenses
- path: /setup/start/licenses
- - title: FAQ
- path: /setup/start/faqs
- - title: Site Updates
- path: /setup/start/site-updates
-- title: Downloading and Building
- section:
- - title: Requirements
- path: /setup/build/requirements
- - title: Establishing a Build Environment
- path: /setup/build/initializing
- - title: Downloading the Source
- path: /setup/build/downloading
- - title: Preparing to Build
- path: /setup/build/building
- - title: Compiling with Jack
- path: /setup/build/jack
- - title: Using Reference Boards
- path: /setup/build/devices
- - title: Running Builds
- path: /setup/build/running
- - title: Building Kernels
- path: /setup/build/building-kernels
- - title: Known Issues
- path: /setup/build/known-issues
-- title: Developing
- section:
- - title: Overview
- path: /setup/develop/
- - title: Using Repo
- path: /setup/develop/repo
- - title: Adding a New Device
- path: /setup/develop/new-device
- - title: Understanding 64-bit Builds
- path: /setup/develop/64-bit-builds
-- title: Contributing
- section:
- - title: Overview
- path: /setup/contribute/
- - title: Life of a Patch
- path: /setup/contribute/life-of-a-patch
- - title: Submitting Patches
- path: /setup/contribute/submit-patches
- - title: View Patches
- path: /setup/contribute/view-patches
- - title: Life of a Bug
- path: /setup/contribute/life-of-a-bug
- - title: Reporting Bugs
- path: /setup/contribute/report-bugs
- - title: Reading Bug Reports
- path: /setup/contribute/read-bug-reports
- - title: Java Code Style Rules
- path: /setup/contribute/code-style
-- title: Community
- path: /setup/community
diff --git a/en/setup/build/devices.html b/en/setup/build/devices.html
index ad24391..b3a7520 100644
--- a/en/setup/build/devices.html
+++ b/en/setup/build/devices.html
@@ -56,23 +56,14 @@
<figcaption><strong>Figure 1.</strong> HiKey960 board by Lenovator</figcaption>
<h3 id="additional-resources">Additional resources</h3>
-<ul>
-<li>
-<a href="https://github.com/96boards/documentation/blob/master/consumer/hikey960/hardware-docs/HiKey960_Schematics.pdf" class="external">HiKey960
-schematics</a></li>
-<li>
-<a href="https://github.com/96boards/documentation/blob/master/consumer/hikey960/hardware-docs/hardware-user-manual.md" class="external">HiKey960
-user guide</a></li>
-<li>
-<a href="https://github.com/96boards/documentation/tree/master/consumer/hikey960/hardware-docs" class="external">HiKey960 Hardware Docs directory</a></li>
-<li>
-<a href="https://github.com/96boards/documentation/wiki/" class="external">96boards wiki</a></li>
-</ul>
+
+<a href="https://github.com/96boards/documentation/wiki/" class="external">96boards wiki</a>
+
+<h3 id="960userspace">Compiling userspace</h3>
<p>Use the following commands to download, build, and run Android on the
HiKey960 board.</p>
-<h3 id="960userspace">Compiling userspace</h3>
<ol>
<li>Download the Android source tree:
<pre class="devsite-click-to-copy">
@@ -173,21 +164,15 @@
<figcaption><strong>Figure 2.</strong> HiKey board by Lenovator</figcaption>
<p>Additional resources:</p>
-<ul>
-<li>
-<a href="https://github.com/96boards/documentation/blob/master/ConsumerEdition/HiKey/HardwareDocs/HiKey_schematics_LeMaker_version_Rev_A1.pdf" class="external">HiKey
-schematics</a></li>
-<li>
-<a href="https://www.96boards.org/wp-content/uploads/2015/02/HiKey_User_Guide_Rev0.2.pdf" class="external">HiKey
-user guide</a></li>
-<li><a href="https://github.com/96boards/documentation/wiki/" class="external">96boards
-wiki</a></li>
-</ul>
+
+<a href="https://github.com/96boards/documentation/wiki/" class="external">96boards
+wiki</a>
+
+<h3 id="620userspace">Compiling userspace</h3>
<p>Use the following commands to download, build, and run Android on the HiKey
board.</p>
-<h3 id="620userspace">Compiling userspace</h3>
<ol>
<li>Download the Android source tree:
<pre class="devsite-click-to-copy">
@@ -214,10 +199,7 @@
<h3 id="620fastboot">Installing initial fastboot and ptable</h3>
<ol>
- <li>Select special bootloader mode by linking J15 1-2 and 3-4 pins (for details,
-refer to the
-<a href="https://github.com/96boards/documentation/blob/master/consumer/hikey/hardware-docs/HiKey_Hardware_User_Manual_Rev0.2.pdf" class="external">HiKey
-user guide</a>).</li>
+ <li>Select special bootloader mode by linking J15 1-2 and 3-4 pins.</li>
<li>Connect USB to PC to get ttyUSB device (ex: <code>/dev/ttyUSB1</code>).</li>
<li>Power the board:
<pre class="devsite-click-to-copy">
@@ -274,10 +256,7 @@
Example setting for a 24" monitor: <code>video=HDMI-A-1:1280x800@60</code>.</p>
<h3 id="620serial">Configuring kernel serial output (uart3)</h3>
-<p>Set the J2 low speed expansion connector to 1 - Gnd, 11 - Rx, 13 - Tx. For
-details, refer to the
-<a href="https://www.96boards.org/wp-content/uploads/2015/02/HiKey_User_Guide_Rev0.2.pdf" class="external">HiKey
-user guide</a>.</p>
+<p>Set the J2 low speed expansion connector to 1 - Gnd, 11 - Rx, 13 - Tx.</p>
<h2 id="neonkey">Neonkey SensorHub</h2>
<p>To develop new ContextHub features that use new sensors or LEDs, you can use
diff --git a/en/setup/build/gsi.html b/en/setup/build/gsi.html
new file mode 100644
index 0000000..5dcafdf
--- /dev/null
+++ b/en/setup/build/gsi.html
@@ -0,0 +1,676 @@
+<html devsite>
+ <head>
+ <title>Generic System Image (GSI)</title>
+ <meta name="project_path" value="/_project.yaml" />
+ <meta name="book_path" value="/_book.yaml" />
+ </head>
+ <body>
+ <!--
+ Copyright 2018 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.
+ -->
+
+<h2 id="overview">Overview</h2>
+<p>
+This document describes the Generic System Image (GSI) for Android 9, including
+details on the differences between GSIs for devices launching with Android 9 and
+devices upgrading to Android 9.
+</p>
+<h2 id="gsi-types">GSI types</h2>
+<p>
+Android 9 supports the following GSIs:
+</p>
+<table>
+ <tr>
+ <th><strong>GSI Name</strong>
+ </th>
+ <th><strong>Description</strong>
+ </th>
+ <th><strong>Product Name</strong>
+ </th>
+ </tr>
+ <tr>
+ <td>P GSI
+ </td>
+ <td>For devices launching with Android 9
+ </td>
+ <td><code>aosp_$arch</code>
+ </td>
+ </tr>
+ <tr>
+ <td>Legacy GSI
+ </td>
+ <td>For devices upgrading to Android 9
+ </td>
+ <td><code>aosp_$arch_a(b)</code>
+ </td>
+ </tr>
+</table>
+<p>
+All GSIs are built from the Android 9 codebase.
+</p>
+<h3 id="changes-in-p-gsis">Changes in GSIs for Android 9</h3>
+<p>
+Devices launching with Android 9 must use P GSIs, which include the following
+major changes from earlier GSIs:
+</p><ul>
+<li><strong>Merges GSI and emulator. </strong>GSIs are built from the system
+images of emulator products, e.g. <code>aosp_arm64</code>,
+<code>aosp_x86</code>, etc.
+<li><strong>System-as-root</strong>. In previous versions of Android, devices
+that did not support A/B updates could mount the system image under
+<code>/system</code> directory.<strong> </strong>In Android 9, the root of the
+system image is mounted as the root of the device.
+<li><strong>64-bit binder interface</strong>. In Android 8.x, 32-bit GSIs used
+the 32-bit binder interface. Android 9 does not support 32-bit binder interface,
+so both 32-bit GSIs and 64-bit GSIs use the 64-bit binder interface.
+<li><strong>VNDK enforcement</strong>. In Android 8.1, VNDK was optional. In
+Android 9, VNDK is mandatory, meaning the
+<code>BOARD_VNDK_RUNTIME_DISABLE</code> must <strong>not</strong> be set:
+<code>BOARD_VNDK_RUNTIME_DISABLE := # must not be set</code>
+<li><strong>Compatible system property</strong>. Android 9 enables the access
+check for compatible system property:<code>
+PRODUCT_COMPATIBLE_PROPERTY_OVERRIDE := true</code>.</li></ul>
+<p>
+To test devices launching with Android 9 with cts-on-gsi, use the <a
+href="#p-gsi-build-targets">build targets for P GSI</a>.
+</p>
+<h3 id="changes-in-legacy-gsis">Changes in Legacy GSIs</h3>
+<p>
+Devices upgrading to Android 9 can use Legacy GSI product named with suffix
+<code>_ab</code> or <code>_a</code> (e.g. <code>aosp_arm64_ab</code>,
+<code>aosp_x86_a</code> ). This GSI supports the following upgrade use cases:
+</p><ul>
+<li>For devices with an Android 8.1 vendor interface implementation
+<li>For devices updated to the Android 9 vendor interface
+implementation</li></ul>
+<p>
+Legacy GSIs are build from the Android 9 source tree but contain the following
+backward compatible configurations for upgraded devices:
+</p><ul>
+<li><strong>Non system-as-root</strong>. Devices that do not support
+system-as-root can continue to use <code>_a</code> products (e.g.,
+<code>aosp_arm_a</code>).
+<li><strong>32-bit userspace + 32-bit binder interface. </strong>32-bit GSIs can
+continue to use the 32-bit binder interface.
+<li><strong>8.1 VNDK</strong>. Devices can use the included 8.1 VNDK.
+<li><strong>Mount directories</strong>. Some legacy devices use directories as
+mount-pointers (e.g. <code>/bluetooth</code>, <code>/firmware/radio</code>,
+<code>/persist</code>, etc.).</li></ul>
+<p>
+To test devices upgrading to Android 9 with cts-on-gsi, use the <a
+href="#legacy-gsi-build-targets">build targets for Legacy GSI</a>.
+</p>
+<p>
+<strong>Note:</strong> If a pre-Android 9 device implements the Android 9 vendor
+interface and meets all requirements introduced in Android 9, don't use the
+Legacy GSIs; instead use P GSIs for VTS and cts-on-gsi.
+</p>
+<h2 id="changes-to-keymaster-behavior">Changes to Keymaster behavior</h2>
+<p>
+In earlier versions of Android, devices implementing Keymaster 3 or earlier were
+required to verify the version info (<code>ro.build.version.release</code> and
+<code>ro.build.version.security_patch</code>) reported by the running system
+matched the version info reported by bootloader. Such information was typically
+obtained from the boot image header.
+</p>
+<p>
+In Android 9, this requirement has changed for vendors to boot GSI: The
+Keymaster should not perform verification since the version info reported by the
+GSI may not match the version info reported by vendor's bootloader. For devices
+implementing Keymaster 3 or earlier, vendors must modify the Keymaster
+implementation to skip verification (or upgrade to Keymaster 4).
+</p>
+<p>
+For details on Keymaster, refer to <a
+href="https://source.android.com/security/keystore/">Hardware-backed
+Keystore</a> on source.android.com.
+</p>
+<h2 id="vendor-binaries-and-vndk-dependencies">Vendor binaries and VNDK
+dependencies</h2>
+<p>
+Devices upgrading to Android 9 have different upgrade paths depending on the
+version of vendor binaries in use on the device and the VNDK-related
+configurations used to build the device.
+</p>
+<p>
+The following table summarizes the Legacy GSI support for upgraded devices:
+</p>
+<table>
+ <tr>
+ <th><strong>Use Case</strong>
+ </th>
+ <th><strong>Device
+Vendor Binaries</strong>
+ </th>
+ <th><strong><code>BOARD_VNDK
+_VERSION</code></strong>
+ </th>
+ <th><strong><code>BOARD_VNDK
+_RUNTIME_DISABLE</code></strong>
+ </th>
+ <th><strong>Legacy GSI
+System Binaries</strong>
+ </th>
+ <th><strong>Support</strong>
+ </th>
+ </tr>
+ <tr>
+ <td>1.a
+ </td>
+ <td>8.1
+ </td>
+ <td>(empty)
+ </td>
+ <td>(any)
+ </td>
+ <td>P
+ </td>
+ <td>No
+ </td>
+ </tr>
+ <tr>
+ <td>1.b
+ </td>
+ <td>8.1
+ </td>
+ <td><code>current</code>
+ </td>
+ <td><code>true</code>
+ </td>
+ <td>P
+ </td>
+ <td>No
+ </td>
+ </tr>
+ <tr>
+ <td>2
+ </td>
+ <td>8.1
+ </td>
+ <td><code>current</code>
+ </td>
+ <td>(empty)
+ </td>
+ <td>P
+ </td>
+ <td>Yes
+ </td>
+ </tr>
+ <tr>
+ <td>3
+ </td>
+ <td>P
+ </td>
+ <td><code>current</code>
+ </td>
+ <td><code>true</code>
+ </td>
+ <td>P
+ </td>
+ <td>Yes
+ </td>
+ </tr>
+ <tr>
+ <td>4
+ </td>
+ <td>P
+ </td>
+ <td><code>current</code>
+ </td>
+ <td>(empty)
+ </td>
+ <td>P
+ </td>
+ <td>Yes
+ </td>
+ </tr>
+</table>
+<p>
+The most common supported use case is #2, where the Legacy GSI supports devices
+running 8.1 that were built with <code>BOARD_VNDK_VERSION</code> but built
+without <code>BOARD_VNDK_RUNTIME_DISABLE</code> (i.e., runtime enforcement was
+NOT disabled).
+</p>
+<p>
+The two unsupported use cases are #1.a and #1.b, where the Legacy GSI does NOT
+support devices running 8.1 that were not built with
+<code>BOARD_VNDK_VERSION</code> or built with
+<code>BOARD_VNDK_RUNTIME_DISABLE</code> (i.e. runtime enforcement WAS disabled).
+These devices are not supported because their vendor binaries depend on 8.1
+non-VNDK shared libraries, which are not included in Legacy GSI.
+</p>
+<p>
+To make these devices compatible with the Legacy GSI, vendors must do one of the
+following:
+</p><ul>
+<li>Enable <code>BOARD_VNDK_VERSION</code> without
+<code>BOARD_VNDK_RUNTIME_DISABLE</code> (use case #2)
+
+OR
+<li>Port/upgrade the vendor binaries to depend on the shared libraries from
+Android 9 (use case #3 and use case #4).</li></ul>
+
+<h2 id="build-targets">Build targets</h2>
+<p>
+Use the following build target tables to determine the correct GSI version for
+your device.
+</p>
+<h3 id="p-gsi-build-targets">P GSI build targets</h3>
+<p>
+The following P GSI build targets are for devices launching with Android 9. (Due
+to a reduction in variances between architectures, Android 9 includes only four
+GSI products).
+</p>
+<table>
+ <tr>
+ <th><strong>GSI name</strong>
+ </th>
+ <th><strong>CPU arch</strong>
+ </th>
+ <th><strong>Binder interface bitness</strong>
+ </th>
+ <th><strong>System-as-root</strong>
+ </th>
+ <th><strong>Product name</strong>
+ </th>
+ </tr>
+ <tr>
+ <td><strong><code>aosp_arm</code></strong>
+ </td>
+ <td><code>ARM</code>
+ </td>
+ <td><code>64</code>
+ </td>
+ <td><code>Y</code>
+ </td>
+ <td><code>aosp_arm-userdebug</code>
+ </td>
+ </tr>
+ <tr>
+ <td><strong><code>aosp_arm64</code></strong>
+ </td>
+ <td><code>ARM64</code>
+ </td>
+ <td><code>64</code>
+ </td>
+ <td><code>Y</code>
+ </td>
+ <td><code>aosp_arm64-userdebug</code>
+ </td>
+ </tr>
+ <tr>
+ <td><strong><code>aosp_x86</code></strong>
+ </td>
+ <td><code>x86</code>
+ </td>
+ <td><code>64</code>
+ </td>
+ <td><code>Y</code>
+ </td>
+ <td><code>aosp_x86-userdebug</code>
+ </td>
+ </tr>
+ <tr>
+ <td><strong><code>aosp_x86_64</code></strong>
+ </td>
+ <td><code>x86-64</code>
+ </td>
+ <td><code>64</code>
+ </td>
+ <td><code>Y</code>
+ </td>
+ <td><code>aosp_x86_64-userdebug</code>
+ </td>
+ </tr>
+</table>
+<h3 id="legacy-gsi-build-targets">Legacy GSI build targets</h3>
+<p>
+The following Legacy GSI build targets are for devices upgrading to Android 9.
+Legacy GSI names include the suffix <code>_ab</code> or <code>_a</code> to
+distinguish them from P GSI names.
+</p>
+<table>
+ <tr>
+ <th><strong>GSI name</strong>
+ </th>
+ <th><strong>CPU arch</strong>
+ </th>
+ <th><strong>Binder interface bitness</strong>
+ </th>
+ <th><strong>System-as-root</strong>
+ </th>
+ <th><strong>Product name</strong>
+ </th>
+ </tr>
+ <tr>
+ <td><strong><code>aosp_arm_a</code></strong>
+ </td>
+ <td><code>ARM</code>
+ </td>
+ <td><code>32</code>
+ </td>
+ <td><code>N</code>
+ </td>
+ <td><code>aosp_arm_a-userdebug</code>
+ </td>
+ </tr>
+ <tr>
+ <td><strong><code>aosp_arm_ab</code></strong>
+ </td>
+ <td><code>ARM</code>
+ </td>
+ <td><code>32</code>
+ </td>
+ <td><code>Y</code>
+ </td>
+ <td><code>aosp_arm_ab-userdebug</code>
+ </td>
+ </tr>
+ <tr>
+ <td><code>**NA</code>
+ </td>
+ <td><code>ARM</code>
+ </td>
+ <td><code>64</code>
+ </td>
+ <td><code>N</code>
+ </td>
+ <td>
+ </td>
+ </tr>
+ <tr>
+ <td><code>aosp_arm_64b_ab</code>
+ </td>
+ <td><code>ARM</code>
+ </td>
+ <td><code>64</code>
+ </td>
+ <td><code>Y</code>
+ </td>
+ <td><code>aosp_arm_64b_ab-userdebug</code>
+ </td>
+ </tr>
+ <tr>
+ <td><strong><code>aosp_arm64_a</code></strong>
+ </td>
+ <td><code>ARM64</code>
+ </td>
+ <td><code>64</code>
+ </td>
+ <td><code>N</code>
+ </td>
+ <td><code>aosp_arm64_a-userdebug</code>
+ </td>
+ </tr>
+ <tr>
+ <td><strong><code>aosp_arm64_ab</code></strong>
+ </td>
+ <td><code>ARM64</code>
+ </td>
+ <td><code>64</code>
+ </td>
+ <td><code>Y</code>
+ </td>
+ <td><code>aosp_arm64_ab-userdebug</code>
+ </td>
+ </tr>
+ <tr>
+ <td><strong><code>aosp_x86_a</code></strong>
+ </td>
+ <td><code>x86</code>
+ </td>
+ <td><code>32</code>
+ </td>
+ <td><code>N</code>
+ </td>
+ <td><code>aosp_x86_a-userdebug</code>
+ </td>
+ </tr>
+ <tr>
+ <td><strong><code>aosp_x86_ab</code></strong>
+ </td>
+ <td><code>x86</code>
+ </td>
+ <td><code>32</code>
+ </td>
+ <td><code>Y</code>
+ </td>
+ <td><code>aosp_x86_ab-userdebug</code>
+ </td>
+ </tr>
+ <tr>
+ <td><code>**NA</code>
+ </td>
+ <td><code>x86</code>
+ </td>
+ <td><code>64</code>
+ </td>
+ <td><code>N</code>
+ </td>
+ <td>
+ </td>
+ </tr>
+ <tr>
+ <td><code>**NA</code>
+ </td>
+ <td><code>x86</code>
+ </td>
+ <td><code>64</code>
+ </td>
+ <td><code>Y</code>
+ </td>
+ <td>
+ </td>
+ </tr>
+ <tr>
+ <td><strong><code>aosp_x86_64_a</code></strong>
+ </td>
+ <td><code>x86-64</code>
+ </td>
+ <td><code>64</code>
+ </td>
+ <td><code>N</code>
+ </td>
+ <td><code>aosp_x86_64_a-userdebug</code>
+ </td>
+ </tr>
+ <tr>
+ <td><strong><code>aosp_x86_64_ab</code></strong>
+ </td>
+ <td><code>x86-64</code>
+ </td>
+ <td><code>64</code>
+ </td>
+ <td><code>Y</code>
+ </td>
+ <td><code>aosp_x86_64_ab-userdebug</code>
+ </td>
+ </tr>
+</table>
+<p>
+<em>** Could be added by request</em>
+</p>
+<p>
+<strong>Note: </strong>These build targets will likely be removed in a future
+version of Android.
+</p>
+<h3 id="gsi-8-1-build-targets">GSI 8.1 build targets</h3>
+<p>
+Android 8.1 GSIs support eight normal products (<strong>bolded</strong> in the
+table) and one special product built from Android 8.1 source tree.
+</p>
+<table>
+ <tr>
+ <th><strong>GSI name</strong>
+ </th>
+ <th><strong>CPU arch</strong>
+ </th>
+ <th><strong>Binder interface bitness</strong>
+ </th>
+ <th><strong>System-as-root</strong>
+ </th>
+ <th><strong>Product name</strong>
+ </th>
+ </tr>
+ <tr>
+ <td><strong><code>aosp_arm_a</code></strong>
+ </td>
+ <td><code>ARM</code>
+ </td>
+ <td><code>32</code>
+ </td>
+ <td><code>N</code>
+ </td>
+ <td><code>aosp_arm_a-userdebug</code>
+ </td>
+ </tr>
+ <tr>
+ <td><strong><code>aosp_arm_ab</code></strong>
+ </td>
+ <td><code>ARM</code>
+ </td>
+ <td><code>32</code>
+ </td>
+ <td><code>Y</code>
+ </td>
+ <td><code>aosp_arm_ab-userdebug</code>
+ </td>
+ </tr>
+ <tr>
+ <td><code>aosp_arm_64b_a</code>
+ </td>
+ <td><code>ARM</code>
+ </td>
+ <td><code>64</code>
+ </td>
+ <td><code>N</code>
+ </td>
+ <td><code>aosp_arm_64b_a-userdebug</code>
+ </td>
+ </tr>
+ <tr>
+ <td><code>**NA</code>
+ </td>
+ <td><code>ARM</code>
+ </td>
+ <td><code>64</code>
+ </td>
+ <td><code>Y</code>
+ </td>
+ <td>
+ </td>
+ </tr>
+ <tr>
+ <td><strong><code>aosp_arm64_a</code></strong>
+ </td>
+ <td><code>ARM64</code>
+ </td>
+ <td><code>64</code>
+ </td>
+ <td><code>N</code>
+ </td>
+ <td><code>aosp_arm64_a-userdebug</code>
+ </td>
+ </tr>
+ <tr>
+ <td><strong><code>aosp_arm64_ab</code></strong>
+ </td>
+ <td><code>ARM64</code>
+ </td>
+ <td><code>64</code>
+ </td>
+ <td><code>Y</code>
+ </td>
+ <td><code>aosp_arm64_ab-userdebug</code>
+ </td>
+ </tr>
+ <tr>
+ <td><strong><code>aosp_x86_a</code></strong>
+ </td>
+ <td><code>x86</code>
+ </td>
+ <td><code>32</code>
+ </td>
+ <td><code>N</code>
+ </td>
+ <td><code>aosp_x86_a-userdebug</code>
+ </td>
+ </tr>
+ <tr>
+ <td><strong><code>aosp_x86_ab</code></strong>
+ </td>
+ <td><code>x86</code>
+ </td>
+ <td><code>32</code>
+ </td>
+ <td><code>Y</code>
+ </td>
+ <td><code>aosp_x86_ab-userdebug</code>
+ </td>
+ </tr>
+ <tr>
+ <td><code>**NA</code>
+ </td>
+ <td><code>x86</code>
+ </td>
+ <td><code>64</code>
+ </td>
+ <td><code>N</code>
+ </td>
+ <td>
+ </td>
+ </tr>
+ <tr>
+ <td><code>**NA</code>
+ </td>
+ <td><code>x86</code>
+ </td>
+ <td><code>64</code>
+ </td>
+ <td><code>Y</code>
+ </td>
+ <td>
+ </td>
+ </tr>
+ <tr>
+ <td><strong><code>aosp_x86_64_a</code></strong>
+ </td>
+ <td><code>x86-64</code>
+ </td>
+ <td><code>64</code>
+ </td>
+ <td><code>N</code>
+ </td>
+ <td><code>aosp_x86_64_a-userdebug</code>
+ </td>
+ </tr>
+ <tr>
+ <td><strong><code>aosp_x86_64_ab</code></strong>
+ </td>
+ <td><code>x86-64</code>
+ </td>
+ <td><code>64</code>
+ </td>
+ <td><code>Y</code>
+ </td>
+ <td><code>aosp_x86_64_ab-userdebug</code>
+ </td>
+ </tr>
+</table>
+<p>
+<em>** Could be added by request</em>
+</p>
+ </body>
+</html>
diff --git a/en/setup/community.html b/en/setup/community.html
index 7cd5355..7b67d80 100644
--- a/en/setup/community.html
+++ b/en/setup/community.html
@@ -214,6 +214,18 @@
<a href="mailto:android-ota+subscribe@googlegroups.com">android-ota</a></li>
</ul>
</li>
+<li>
+<p><em>android-compatibility</em>:
+If you have technical questions about Android compatibility that aren't covered
+in this site, you can seek help from your peers on this list.</p>
+<ul>
+<li>Subscribe using Google Groups:
+<a href="https://groups.google.com/forum/?fromgroups#!forum/android-compatibility">
+android-compatibility</a></li>
+<li>Subscribe via email:
+<a href="mailto:android-compatibility+subscribe@googlegroups.com">android-compatibility</a></li>
+</ul>
+</li>
</ul>
<h3 id="audience">Audience</h3>
@@ -362,5 +374,15 @@
</li>
</ul>
+<h2 id="for-business-inquiries">For licensing Google Mobile Services</h2>
+<p>Please send inquiries about licensing <a
+href="https://www.android.com/gms/">Google Mobile Services </a> through the <a
+href="https://www.android.com/gms/contact/">GMS contact</a> form. Other non-GMS
+partnership inquiries can be sent to <a
+href="mailto:android-partnerships@google.com">android-partnerships@google.com</a>.</p>
+
+<p>While we read every message received, we cannot respond to each of them. We
+promise to contact you if we can help!</p>
+
</body>
</html>
diff --git a/en/setup/start/build-numbers.html b/en/setup/start/build-numbers.html
index 13536d4..4abb4d6 100644
--- a/en/setup/start/build-numbers.html
+++ b/en/setup/start/build-numbers.html
@@ -40,6 +40,11 @@
</thead>
<tbody>
<tr>
+<td>Pie</td>
+<td>9</td>
+<td>API level 28</td>
+</tr>
+<tr>
<td>Oreo</td>
<td>8.1.0</td>
<td>API level 27</td>
@@ -235,6 +240,36 @@
</thead>
<tbody>
<tr>
+ <td>PPR1.180610.011</td>
+ <td>android-9.0.0_r3</td>
+ <td>Pie</td>
+ <td>Pixel 2 XL, Pixel 2</td>
+ </tr>
+ <tr>
+ <td>PPR1.180610.010</td>
+ <td>android-9.0.0_r2</td>
+ <td>Pie</td>
+ <td>Pixel XL, Pixel</td>
+ </tr>
+ <tr>
+ <td>PPR1.180610.009</td>
+ <td>android-9.0.0_r1</td>
+ <td>Pie</td>
+ <td>Pixel 2 XL, Pixel 2, Pixel XL, Pixel</td>
+ </tr>
+ <tr>
+ <td>OPM6.171019.030.H1</td>
+ <td>android-8.1.0_r43</td>
+ <td>Oreo</td>
+ <td>Nexus 5X and Nexus 6P</td>
+ </tr>
+ <tr>
+ <td>OPM4.171019.021.Y1</td>
+ <td>android-8.1.0_r42</td>
+ <td>Oreo</td>
+ <td>Pixel C</td>
+ </tr>
+ <tr>
<td>OPM6.171019.030.E1</td>
<td>android-8.1.0_r41</td>
<td>Oreo</td>
diff --git a/en/setup/start/p-release-notes.md b/en/setup/start/p-release-notes.md
new file mode 100644
index 0000000..dcfedad
--- /dev/null
+++ b/en/setup/start/p-release-notes.md
@@ -0,0 +1,863 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+<!--
+ Copyright 2018 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.
+-->
+
+{% include "_versions.html" %}
+
+# Android {{ androidPVersionNumber }} Release Notes
+
+Android {{ androidPVersionNumber }} has released! This page summarizes the
+major features in this release, and provides links to additional information
+when available. These feature summaries are organized according to the feature's
+documentation location on this site. See the
+[August 2018 Site Updates](/setup/start/site-updates#Aug-2018) for a guide to
+section moves and
+renaming.
+
+## Build
+
+### Generic System Image (GSI)
+
+[Generic System Image (GSI)](/setup/build/gsi) describes the Generic System
+Image (GSI) for Android {{ androidPVersionNumber }}, including details on
+differences between GSIs for devices launching with Android
+{{ androidPVersionNumber }} and devices upgrading to Android
+{{ androidPVersionNumber }}.
+
+## Architecture
+
+### Hardware Abstraction Layer
+
+#### HIDL Framework Backwards Compatibility
+
+[HIDL Framework Backwards Compatibility Verification](/devices/architecture/hal/framework-testing)
+is a method for verifying the backwards compatibility of the framework.
+
+#### Dynamically Available HALs
+
+[Dynamically Available HALs](/devices/architecture/hal/dynamic-lifecycle)
+support the dynamic shutdown of Android hardware subsystems when they are not in
+use or not needed.
+
+### HIDL
+
+#### HIDL Memory Block
+
+[HIDL MemoryBlock](/devices/architecture/hidl/memoryblock) is an abstract layer
+built on `hidl_memory`, `HIDL @1.0::IAllocator`, and `HIDL @1.0::IMapper`. It is
+designed for HIDL services that have multiple memory blocks to share a single
+memory heap.
+
+### Device Tree Overlays
+
+#### Compressed Overlays
+
+This release adds support for using
+[compressed overlays](/devices/architecture/dto/optimize#compressed-overlays) in
+the Device Tree Blob Overlay (DTBO) image when using version 1 of the device
+tree table header.
+
+#### DTO Updates
+
+This release requires that the bootloader must not modify the properties defined
+in the [device tree overlays](/devices/architecture/dto/#p-update) before
+passing the unified device tree blob to the kernel.
+
+#### DTO Image Header Versioning
+
+This release inroduces a
+[new version field](/devices/architecture/dto/partitions) in the DTBO image header.
+
+#### DTBO Verification
+
+This release requires a DTBO partition. To add nodes
+or make changes to the properties in the SoC DT, the bootloader must dynamically
+overlay a device specific DT over the SoC DT. For more information see
+[Compiling & Verifying](/devices/architecture/dto/compile).
+
+#### Kernel compliance
+
+This release includes changes to requirements that affect the kernel, its
+interfaces, and the use of DTBOs. For more information, see these pages:
+
+* [Stable Kernel Releases & Updates](/devices/architecture/kernel/releases)
+* [Android Common Kernels](/devices/architecture/kernel/android-common)
+* [Modular Kernel Requirements](/devices/architecture/kernel/modular-kernels)
+* [Interface Requirements](/devices/architecture/kernel/reqs-interfaces)
+* [Device Tree Overlays](/devices/architecture/dto/)
+
+### Vendor NDK
+
+#### VNDK: Design
+
+For information about VNDK design changes in this release, see these pages:
+
+* [Vendor Native Development Kit (VNDK)](/devices/architecture/vndk/index)
+* [VNDK Build System Support](/devices/architecture/vndk/build-system)
+* [VNDK Definition Tool](/devices/architecture/vndk/deftool)
+* [Directories, Rules, and sepolicy](/devices/architecture/vndk/dir-rules-sepolicy)
+* [VNDK Extensions](/devices/architecture/vndk/extensions)
+* [Linker Namespace](/devices/architecture/vndk/linker-namespace)
+
+#### VNDK: ABI Checker
+
+[ABI Stability](/devices/architecture/vndk/abi-stability) describes the process
+for ensuring changes made to libraries in the Vendor Native Development Kit
+(VNDK) maintain Application Binary Interface (ABI) compliance.
+
+#### VNDK Snapshots
+
+[VNDK Snapshots](/devices/architecture/vndk/snapshot-design) can be used by a
+system image to provide the correct VNDK libraries to vendor images even when
+system and vendor images are built from different versions of Android.
+
+### Vendor Interface Object
+
+The following pages in the [Vendor Interface Object](/devices/architecture/vintf/)
+section describe vendor interface object updates in this release:
+
+* [Manifests](/devices/architecture/vintf/objects)
+* [FCM Lifecycle](/devices/architecture/vintf/fcm)
+* [Device Manifest Development](/devices/architecture/vintf/dm)
+
+#### HIDL Deprecation Schedule
+
+The following pages describe how Android deprecates and removes HIDL HALs:
+
+* [FCM Lifecycle](/devices/architecture/vintf/fcm)
+* [Device Manifest Development](/devices/architecture/vintf/dm)
+
+### Bootloader
+
+#### Product Partitions
+
+This release supports building
+[`/product` partitions](/devices/bootloader/product-partitions) using the
+Android build system. Previously, Android 8.x enforced the separation of
+System-on-Chip (SoC)-specific components from the `/system` partition to the
+`/vendor` partition without dedicating space for OEM-specific components built
+from Android build system.
+
+#### Canonical boot reason compliance
+
+[Canonical Boot Reason](/devices/bootloader/boot-reason) describes changes to
+the bootloader boot reason specification in this release.
+
+#### System as Root
+
+All devices launching with this release must use
+[system-as-root](/devices/bootloader/system-as-root), which merges `ramdisk.img`
+into `system.img` (this is also known as no-ramdisk), which in turn is mounted
+as `rootfs`.
+
+#### Boot Image Header Versioning
+
+Starting in this release, the boot image header contains a
+[field to indicate the header version](/devices/bootloader/boot-image-header).
+The bootloader must check this header version field and parse the header
+accordingly.
+
+#### DTBO in Recovery
+
+To prevent OTA failures due to mismatches between the recovery image and the
+DTBO partition on non-A/B devices, the recovery image must contain
+[information from the DTBO image](/devices/bootloader/recovery-image).
+
+### Display
+
+#### Display Cutouts
+
+[Display Cutouts](/devices/tech/display/display-cutouts) allow app developers to
+create immersive, edge-to-edge experiences while still allowing space for
+important sensors on the front of devices.
+
+#### Rotate Suggestions
+
+Updates to [screen rotation behavior](/devices/tech/display/rotate-suggestions)
+in this release include support for a user-facing control to pin screen rotation
+in either landscape or portrait.
+
+#### Synchronized App Transitions
+
+[Synchronized App Transitions](/devices/tech/display/synched-app-transitions)
+allow for new app transition animations.
+
+#### Text Classification (formerly TEXTCLASSIFIER)
+
+This release introduces a
+[Text Classifier service](/devices/tech/display/textclassifier), which is now
+the recommended way to implement text classification, and a default service
+implementation.
+
+#### Wide gamut color
+
+This release introduces support for wide gamut color, including:
+
+* High dynamic range (HDR)
+* Processing content in the BT2020 color space, but not as an end-target
+ dataspace
+
+To use wide gamut color, a device’s full display stack (screen, hardware
+composer, GPU, etc.) must support wide-gamut colors or buffer formats. Devices
+are not required to claim support for wide gamut content even if the hardware
+supports it. However, wide gamut color should be enabled to take full advantage
+of the hardware. To avoid an inconsistent visual experience, wide gamut color
+should not be turned off during runtime.
+
+## Compatibility
+
+### Android Compatibility Definition Document (CDD)
+
+The [Android 9 Compatibility Definition Document](/compatibility/android-cdd)
+iterates upon [previous versions](/compatibility/cdd) with updates for new
+features and changes to requirements for previously released functionality.
+
+## Settings
+
+### Device State Change Notifications to Package Installers
+
+A protected system broadcast can now be sent to apps that hold the
+`INSTALL_PACKAGES` permission whenever a change to properties like locale or
+display density happens. Receivers can be registered in the manifest, and a
+process will be awakened to receive the broadcast. This is useful for package
+installers that wish to install additional components of apps upon such changes,
+which will happen rarely, because the configuration changes eligible to trigger
+this broadcast are rare.
+
+Device state change notification source code is located at the following
+locations under `platform/frameworks/base`:
+
+* `api/system-current.txt`
+* `core/java/android/content/Intent.java`
+* `core/res/AndroidManifest.xml`
+* `services/core/java/com/android/server/am/ActivityManagerService.java`
+
+### Information Architecture
+
+Changes to the
+[Settings app information architecture](/devices/tech/settings/info-architecture)
+provide more Settings functionality and easier implementation.
+
+## Tests
+
+### Atest
+
+[Atest](https://android.googlesource.com/platform/tools/tradefederation/+/master/atest/README.md){: .external}
+is a new command line tool that allows users to build, install and run Android
+tests locally.
+
+### Compatibility Test Suite (CTS)
+
+#### CTS Downloads
+
+New CTS packages supporting Android 9 have been uploaded to the
+[CTS Downloads](/compatibility/cts/downloads) page. The source code for the
+included tests can be synced with the `android-cts-9.0_r1` tag in the
+open-source tree.
+
+#### CTS Options
+
+For Android 9, CTS v2 gains the following
+[command and argument](/compatibility/cts/run#ctsv2_reference):
+
+* `run retry` - Retry all tests that failed or were not executed from the
+ previous sessions.
+* `‘--shard-count` - Shard a CTS run into given number of independent chunks,
+ to run on multiple devices in parallel.
+
+In addition, the previously undocumented commands ‘--retry-type’ has been added
+to the same
+[CTS v2 console command reference](/compatibility/cts/run#ctsv2_reference).
+
+
+#### Secure Element
+
+[Secure Element Service](/compatibility/cts/secure-element) checks for
+Global platform-supported secure elements (essentially checks for
+Global platform-supported secure elements, by seeing if devices have an SE
+HAL implementation and if yes, how many. This is used as the
+basis to test the API and the underlying secure element implementation.
+
+#### Sensor Fusion Box
+
+The Sensor Fusion Box is used in the CameraITS sensor_fusion test and
+multi-camera sync test and provides a consistent test environment for measuring
+timestamp accuracy of camera and other sensors for Android phones. See these
+pages for more information:
+
+* [Sensor Fusion Box Quick Start Guide](/compatibility/cts/sensor-fusion-quick-start)
+ provides step-by-step directions on how to set up the Sensor Fusion test and
+ Sensor Fusion Box for the first time.
+* [Sensor Fusion Box Assembly](/compatibility/cts/sensor-fusion-box-assembly)
+ provides step-by-step instructions for assembling a Sensor Fusion Box.
+
+### Vendor Test Suite
+
+#### Host Controller Architecture
+
+[VTS Host Controller Architecture](/compatibility/vts/host-controller) describes
+the architecture of VTS test framework integrated with its cloud-based test
+serving service.
+
+#### Service Name Aware HAL Testing
+
+[VTS Service Name Aware HAL Testing](/compatibility/vts/sna-hal-testing)
+supports obtaining the service name of a given HAL instance based on the device
+on which Vendor Test Suite (VTS) tests are running.
+
+#### HAL Testability Check
+
+[VTS HAL Testability Check](/compatibility/vts/hal-testability) includes a
+runtime method for using the device configuration to identify which VTS tests
+should be skipped for that device target.
+
+#### Automated Testing Infrastructure
+
+The [Automated Testing Infrastructure](/compatibility/vts/automated-test-infra)
+page describes a new Vendor Test Suite (VTS) infrastructure for automated
+testing of VTS, CTS, or other tests on partner devices running the AOSP generic
+system image (GSI).
+
+### Debugging
+
+#### Advanced Telemetry
+
+
+In Android, telemetry is the process of automatically collecting usage and
+diagnostics information about the device, the Android system, and apps. In
+previous versions of Android, the telemetry stack was limited and did not
+capture the information needed to identify and resolve system reliability
+and device or app issues. This made identifying root causes of issues difficult,
+if not impossible.
+
+Android 9 includes a new telemetry feature, `statsd`, which solves this
+deficiency by collecting better data faster. `statsd` collects
+app usage, battery and process statistics, and crashes. The data is analyzed and
+used to improve products, hardware, and services.
+
+For more details, see `frameworks/base/cmds/statsd/`.
+
+
+## Security Features
+
+### Application Signing
+
+[APK Signature Scheme v3](/security/apksigning/v3) is the new APK signature
+scheme, which supports APK key rotation.
+
+
+### Biometric Support
+
+Android 9 includes a
+[BiometricPrompt API](https://developer.android.com/preview/features/security#fingerprint-auth){: .external}
+that apps can use to integrate biometric authentication support in a device- and
+modality-agnostic fashion. For more information about integrating your
+biometrics stack to include `BiometricPrompt`, see
+[Biometrics](/security/biometric).
+
+### Dynamic Analysis
+
+Android 9 includes support for more
+[exploit mitigation and analysis
+tools](/devices/tech/debug/fuzz-sanitize).
+
+#### Control Flow Integrity (CFI)
+
+[Control Flow Integrity (CFI)](/devices/tech/debug/cfi) is a security mechanism
+that disallows changes to the original control flow graph of a compiled binary,
+making it significantly harder to perform such attacks.
+
+#### Kernel CFI
+
+In addition to system CFI, which is enabled by default, this release also
+includes support for [Kernel Control Flow Integrity](/devices/tech/debug/kcfi).
+
+### Encryption
+
+#### File-Based Encryption
+
+[File-based encryption](/security/encryption/file-based) is updated to work with
+[adoptable storage](/devices/storage/adoptable). For new devices, we recommend
+using file-based encryption over full-disk encryption.
+
+#### Metadata encryption
+
+This release introduces support for
+[metadata encryption](/security/encryption/metadata) where hardware support is
+present. With metadata encryption, a single key present at boot time encrypts
+whatever content is not encrypted by file-based-encryption.
+
+### Keystore
+
+Android 9 includes
+[Keymaster 4](https://android.googlesource.com/platform/hardware/interfaces/+/master/keymaster/4.0/){: .external},
+which has these features:
+
+#### StrongBox
+
+Android 9 includes support for Android Keystore keys that are
+stored and used in a physically separate CPU purpose-built for
+high-security applications, such as an embedded
+[Secure Element](/compatibility/cts/secure-element) (SE).
+StrongBox Keymaster is an implementation of the Keymaster HAL in discrete
+secure hardware. A StrongBox has:
+
+ * Discrete CPU
+ * Integral secure storage
+ * High-quality True Random Number Generator
+ * Tamper-resistant packaging
+ * Side-channel resistance
+
+#### Secure key import
+
+To securely import a key into Keymaster 4, a key created off-device is encrypted
+with a specification of the authorizations that define how the key may be used.
+
+##### 3DES support
+
+Keymaster 4 includes 3DES for compatibility with legacy systems that use 3DES.
+
+#### Version binding
+
+To support Treble's modular structure and break the binding of `system.img`
+to `boot.img`, Keymaster 4 changed the [key version binding](/security/keystore/version-binding)
+model to have separate patch levels for each partition. This allows each partition to be
+updated independently while still providing rollback protection.
+
+#### Android Protected Confirmation
+
+Supported devices that launch with Android 9 installed give developers the
+ability to use the
+[Android Protected Confirmation API](https://developer.android.com/preview/features/security#android-protected-confirmation){: .external}.
+By using this new API, apps can use an instance of
+<code>[ConfirmationPrompt](https://developer.android.com/reference/android/security/ConfirmationPrompt.html)</code>
+to display a prompt to the user, asking them to approve a short statement. This
+statement allows an app to reaffirm that the user would like to complete a
+sensitive transaction, such as making a payment.
+
+
+### SELinux
+
+#### Per-App SELinux Sandbox
+
+The [Application Sandbox](/security/app-sandbox) has new protections and test
+cases to ensure that all non-privileged apps tageting Android 9 and higher run
+individual SELinux sandboxes.
+
+#### Treble SELinux changes
+
+Updates to Treble SELinux in this release are documented in several pages in the
+[SELinux section](/security/selinux).
+
+#### Vendor_init
+
+[Vendor Init](/security/selinux/vendor-init) describes updates to close the init
+process access hole in the Treble system/vendor split by using a separate
+SELinux domain to run `/vendor` commands with vendor-specific permissions.
+
+#### System Properties
+
+Android 9 restricts [system properties](/security/selinux/compatibility#system-property-and-process-labeling-ownership)
+from being shared between `system` and `vendor` partitions unnecessarily and
+provides a method for ensuring consistency between shared system properties.
+
+##### SELinux attribute tests
+
+Android 9 includes new
+[build-time tests](https://android.googlesource.com/platform/system/sepolicy/+/master/tests/sepolicy_tests.py){: .external}
+that ensure all files in specific locations have the
+[appropriate attributes](/security/selinux/compatibility#compatibility-attributes).
+For example, all files in `sysfs` have the required `sysfs_type` attribute.
+
+
+## Audio
+
+### High-Resolution Audio Effects
+
+Updates to [High-Resolution Audio Effects](/devices/audio/highres-effects)
+include converting effect processing from int16 to float format and increases in
+simultaneous client output tracks, maximum client/server memory, and total mixed
+tracks.
+
+## Camera
+
+### External USB Cameras
+
+This release supports using
+[plug-and-play USB cameras](/devices/camera/external-usb-cameras) (i.e. webcams)
+using the standard Android Camera2 API and the camera HIDL interface.
+
+### Motion Tracking
+
+Camera devices can
+[advertise motion tracking capability](/devices/camera/motion-tracking).
+
+### Multi-Camera Support
+
+[Multi-Camera Support](/devices/camera/multi-camera) includes API support for
+multi-camera devices via a new logical camera device composed of two or more
+physical camera devices pointing in the same direction.
+
+### Session Parameters
+
+[Implementing session parameters](/devices/camera/session-parameters) can reduce
+delays by enabling camera clients to actively configure a subset of costly
+request parameters as part of the capture session initialization phase.
+
+### Single Producer, Multiple Consumer Buffer
+
+[Single Producer Multiple Consumer Camera Buffer Transport](/devices/camera/singleprod-multiconsum)
+is a new set of methods that allows camera clients to add and remove output
+surfaces dynamically while the capture session is active and camera streaming is
+ongoing.
+
+## Connectivity
+
+### Calling and Messaging
+
+#### Implementing data plans
+
+This release provides improved support for carriers
+[implementing data plans](/devices/tech/connect/data-plans) using the
+`SubcriptionPlan` APIs.
+
+#### Third-party calling apps
+
+This release provides APIs that allow
+[third-party calling apps](/devices/tech/connect/third-party-call-apps) to
+handle concurrent incoming carrier calls and to have calls logged in the system
+call log.
+
+### Carrier
+
+#### Carrier identification
+
+In Android {{ androidPVersionNumber }}, AOSP adds a carrier ID database to help
+with [carrier identification](/devices/tech/config/carrierid). The database
+minimizes duplicate logic and fragmented app experiences by providing a common
+way to identify carriers.
+
+#### eSIM
+
+Embedded SIM (eSIM or eUICC) is the latest technology to allow mobile users to
+download a carrier profile and activate a carrier's service without having a
+physical SIM card. In this release, the Android framework provides standard APIs
+for accessing eSIM and managing subscription profiles on the eSIM. For more
+information, see:
+
+* [Implementing eSIM](/devices/tech/connect/esim-overview)
+* [Modem Requirements](/devices/tech/connect/esim-modem-requirements)
+* [eUICC APIs](/devices/tech/connect/esim-euicc-api)
+
+#### Multi-SIM support for IMS settings
+
+This release provides improvements to the user settings for
+[IMS](/devices/tech/connect/ims). Users can set up Voice over LTE (VoLTE), video
+calling, and Wi-Fi calling on a per-subscription basis instead of sharing these
+settings across all subscriptions.
+
+#### SIM state broadcasts
+
+In this release, `Intent.ACTION_SIM_STATE_CHANGED` has been deprecated, and two
+separate broadcasts for card state and card application state have been added:
+`TelephonyManager.ACTION_SIM_CARD_STATE_CHANGED` and
+`TelephonyManager.ACTION_SIM_APPLICATION_STATE_CHANGED`.
+
+With this change, receivers that only need to know whether a card is present are
+no longer required to listen to application state changes, and receivers that
+only need to know whether card applications are ready are not required to listen
+to changes in card state.
+
+The two new broadcasts are @SystemApis and are not sticky. Only receivers with
+the `READ_PRIVILEGED_PHONE_STATE` permission can receive the broadcasts.
+
+The intents are not rebroadcast when the user unlocks the device. Receivers that
+depend on broadcasts sent before user unlock must either be `directBootAware`,
+or they must query the state after user unlock. The states can be queried using
+the corresponding APIs in TelephonyManager: `getSimCardState()`
+and`getSimApplicationState()`.
+
+### Wi-Fi
+
+#### Carrier Wi-Fi
+
+[Carrier Wi-Fi](/devices/tech/connect/carrier-wifi) allows devices to
+automatically connect to carrier-implemented Wi-Fi networks. In areas of high
+congestion or with minimal cell coverage such as a stadium or an underground
+train station, Carrier Wi-Fi can be used to improve users' connectivity
+experience and to offload traffic.
+
+#### MAC randomization
+
+[MAC Randomization](/devices/tech/connect/wifi-mac-randomization) allows devices
+to use random MAC addresses when probing for new networks while not currently
+associated to a network. In this release, a developer option can be enabled to
+cause a device to use a randomized MAC address when connecting to a Wi-Fi
+network.
+
+#### Wi-Fi Round Trip Time (RTT)
+
+[Wi-Fi Round Trip Time (RTT)](/devices/tech/connect/wifi-rtt) allows devices to
+measure the distance to other supporting devices: whether they are Access Points
+(APs) or Wi-Fi Aware peers (if Wi-Fi Aware is supported on the device). This
+feature, built upon the IEEE 802.11mc protocol, enables apps to use enhanced
+location accuracy and awareness.
+
+#### Wi-Fi Scoring improvements
+
+Improved Wi-Fi scoring models quickly and accurately determine when a device
+should exit a connected Wi-Fi network or enter a new Wi-Fi network. These models
+provide a reliable and seamless experience for users by avoiding gaps in
+connectivity.
+
+You should review and tune the RSSI values in the config.xml resources,
+especially the following:
+
+- `config_wifi_framework_wifi_score_bad_rssi_threshold_5GHz`
+- `config_wifi_framework_wifi_score_entry_rssi_threshold_5GHz`
+- `config_wifi_framework_wifi_score_bad_rssi_threshold_24GHz`
+- `config_wifi_framework_wifi_score_entry_rssi_threshold_24GHz`
+
+Note: The "entry" values were introduced in Android 8.1, and the defaults were
+chosen to match the defaults for the "bad" thresholds for compatibility.
+Ideally, the entry threshold should be 3 dB or more above the corresponding exit
+("bad") threshold.
+
+#### Wi-Fi STA/AP concurrency
+
+[Wi-Fi STA/AP concurrency](/devices/tech/connect/wifi-sta-ap-concurrency) is the
+ability for devices to operate in Station (STA) and Access Point (AP) modes
+concurrently. For devices supporting Dual Band Simultaneous (DBS), this feature
+opens up new capabilities such as not disrupting STA Wi-Fi when a user wants to
+enable a hotspot (softAP).
+
+#### WiFiStateMachine improvements
+
+`WifiStateMachine` is the main class used to control Wi-Fi activity, coordinate
+user input (operating mode: hotspot, scan, connect or off), and control Wi-Fi
+network actions (e.g., scanning, connecting).
+
+In this release, the Wi-Fi framework code and implementation of
+`WifiStateMachine`has been re-architected leading to reduced code size,
+easier-to-follow Wi-Fi control logic, improved control granularity, and
+increased coverage and quality of unit tests.
+
+At a high level,`WifiStateMachine` allows Wi-Fi to be in one of four states:
+
+1. Client mode (can connect and scan)
+1. Scan Only mode
+1. SoftAP mode (Wi-Fi hotspot)
+1. Disabled (Wi-Fi fully off)
+
+Each Wi-Fi mode has different requirements for running services and should be
+set up in a consistent manner, handling only the events relevant to its
+operation. The new implementation restricts the code to events related to that
+mode, reducing debugging time and the risk of introducing new bugs due to
+complexity. In addition to explicit handling for mode functionality, thread
+management is handled in a consistent manner and the use of asynchronous
+channels is eliminated as a mechanism for synchronization.
+
+#### Wi-Fi permission updates
+
+From this release, the `CHANGE_WIFI_STATE` app permission is dynamically checked
+and can be turned off by the user. The user can disable the permission for any
+app through the special settings page in **Settings > Apps & notifications >
+Special app access > Wi-Fi control**.
+
+Apps must be able to handle cases where the `CHANGE_WIFI_STATE` permission is
+not granted.
+
+To validate this behavior, run the roboelectric and manual tests.
+
+Run the roboelectric tests at:
+[/packages/apps/Settings/tests/robotests/src/com/android/settings/wifi/AppStateChangeWifiStateBridgeTest.java](https://android.googlesource.com/platform/packages/apps/Settings/+/master/tests/robotests/src/com/android/settings/wifi/){: .external}
+
+For manual testing:
+
+1. Go to Settings > Apps & notifications > Special app access > Wi-Fi control.
+1. Select and turn off the permission for your app.
+1. Verify that your app can handle the scenario where the `CHANGE_WIFI_STATE`
+ permission is not granted.
+
+#### WPS deprecation
+
+Due to security issues, Wi-Fi Protected Setup (WPS) in `WiFiManager` has been
+deprecated and disabled from this release. However, `WiFiDirect` still uses WPS
+in the WPA supplicant.
+
+## Graphics
+
+### Implementation
+
+#### Vulkan 1.1 API
+
+This release supports implementing the
+[Vulkan 1.1 graphics API](/devices/graphics/implement-vulkan).
+
+#### WinScope tool for window transition tracing
+
+This release introduces the WinScope tool for tracing window transitions.
+WinScope provides infrastructure and tools to record and analyze Window Manager
+state during and after transitions. It allows recording and stepping through
+window transitions, while recording all pertinent window manager state to a
+trace file. You can use this data to replay and step through the transition.
+
+The WinScope tool source code is located at
+`platform/development/tools/winscope`.
+
+## Interaction
+
+### Automotive Audio
+
+The section [Automotive Audio](/devices/automotive/audio) describes the audio
+architecture for automotive-related Android implementations.
+
+The [Neural Networks](/devices/interaction/neural-networks) (NN) HAL defines an
+abstraction of the various accelerators. The drivers for these accelerators must
+conform to this HAL.
+
+### Vehicle HAL
+
+[Vehicle Properties](/devices/automotive/properties) describes changes to the
+vehicle HAL interface.
+
+### GNSS hardware model
+
+In Android {{ androidPVersionNumber }}, the GNSS HAL version 1.1 or higher can
+pass information about the hardware API to the platform. The platform needs to
+implement the `IGnssCallback` interface and pass a handle to the HAL. The GNSS
+HAL passes the hardware model information through the
+[`LocationManager#getGnssHardwareModelName()`](https://developer.android.com/reference/android/location/LocationManager#getGnssHardwareModelName()){: .external}
+API. Device manufacturers should work with their GNSS HAL providers to provide
+this information where possible.
+
+## Permissions
+
+### Configuring Discretionary Access Control (DAC) Updates
+
+[Configuring Discretionary Access Control (DAC)](/devices/tech/config/filesystem)
+contains updates to the Android IDs (AIDs) mechanism for extending filesystem
+capabilities.
+
+### Update on the privileged apps permissions whitelisting
+
+Starting in Android 9, if there are permissions that should be denied, edit the
+XML to use a `deny-permission` tag instead of a `permission` tag as was used in
+prior releases.
+
+## Data
+
+### Bandwidth Estimation Improvements
+
+Android {{ androidPVersionNumber }} provides improved support for bandwidth
+estimation. Android applications can make better decisions on the resolution to
+use for video calls and video streaming if they are aware of the data bandwidth
+available to them.
+
+On devices running Android 6.0 and higher, a caller wanting a bandwidth estimate
+for a cellular network calls
+[`ConnectivityManager.requestBandwidthUpdate()`](https://developer.android.com/reference/android/net/ConnectivityManager.html#requestBandwidthUpdate\(android.net.Network\)){: .external},
+and the framework *may* provide an estimated downlink bandwidth.
+
+But on devices running {{ androidPVersionNumber }} or higher, the
+[`onNetworkCapabilitiesChanged()`](https://developer.android.com/reference/android/net/ConnectivityManager.NetworkCallback.html#onCapabilitiesChanged\(android.net.Network,%20android.net.NetworkCapabilities\)){: .external}
+callback automatically fires when there is a significant change in the estimated
+bandwidth, and calling `requestBandwidthUpdate()` is a no-op; the associated
+[`getLinkDownstreamBandwidthKbps()`](https://developer.android.com/reference/android/net/NetworkCapabilities#getlinkdownstreambandwidthkbps){: .external}
+and
+[`getLinkUpstreamBandwidthKbps()`](https://developer.android.com/reference/android/net/NetworkCapabilities#getlinkupstreambandwidthkbps){: .external}
+is populated with updated information provided by the physical layer.
+
+In addition, devices can check the LTE cell bandwidths via
+[`ServiceState.getCellBandwidths()`](https://developer.android.com/reference/android/telephony/ServiceState#getcellbandwidths){: .external}.
+This lets applications know exactly how much bandwidth (frequency) is available
+on a given cell. Cell bandwidth information is available via a hidden menu so
+that field testers can check the most current information.
+
+### eBPF Traffic Monitoring
+
+The [eBPF network traffic tool](/devices/tech/datausage/ebpf-traffic-monitor)
+uses a combination of kernel and user space implementation to monitor network
+usage on the device since the last device boot. It provides additional
+functionality such as socket tagging, separating foreground/background traffic
+and per-UID firewall to block apps from network access depending on device state.
+
+## Enterprise
+
+### Managed Profile Improvements
+
+[Managed Profile](/devices/tech/admin/managed-profiles) UX changes make it
+easier for users to identify, access, and control the managed profile.
+
+### Pause OTAs
+
+A new @SystemApi lets device owners
+[indefinitely pause OTA updates](/devices/tech/admin/ota-updates), including
+security updates.
+
+## Performance
+
+### Health 2.0
+
+This release introduces includes android.hardware.health HAL 2.0, a major
+version upgrade from health@1.0 HAL. For more information see these pages:
+
+* [Health](/devices/tech/health/)
+* [Implementing Health](/devices/tech/health/implementation)
+* [Deprecating health@1.0](/devices/tech/health/deprecation)
+
+### APK Caching
+
+Android 9 includes an [APK caching](/devices/tech/perf/apk-caching) solution for
+rapid installation of preloaded apps on a device that supports
+A/B partitions. OEMs can place preloads and
+popular apps in the APK cache stored in the mostly empty B partition on new
+A/B-partitioned devices without impacting any user-facing data space.
+
+### Profile Guided Optimization (PGO)
+
+This release supports using
+[Clang's profile-guided optimization](/devices/tech/perf/pgo) (PGO) on native
+Android modules that have blueprint build rules.
+
+### Write-Ahead Logging
+
+[Compatibility WAL (Write-Ahead Logging) for Apps](/devices/tech/perf/compatibility-wal)
+is a new special mode of SQLiteDatabase called Compatibility WAL (write-ahead
+logging) that allows a database to use `journal_mode=WAL` while preserving the
+behavior of keeping a maximum of one connection per database.
+
+### Boot Times
+
+[Optimizing Boot Times](/devices/tech/perf/boot-times) describes changes to boot
+time optimization.
+
+## Power
+
+### Background Restrictions
+
+Android {{ androidPVersionNumber }}
+introduces [Background Restrictions](/devices/tech/power/app_mgmt),
+which allow users to restrict apps that may be draining device battery power.
+The system may also suggest disabling apps that it detects are negatively
+affecting a device's health.
+
+### Batteryless Devices
+
+Android 9 more elegantly handles
+[batteryless devices](/devices/tech/power/batteryless) than previous releases.
+Android 9 removes some previous code for batteryless devices that by default
+pretended a battery was present, was being charged at 100%, and was in good
+health with a normal temperature reading on its thermistor.
diff --git a/en/setup/start/site-updates.html b/en/setup/start/site-updates.html
index b6eba9a..78dab3a 100644
--- a/en/setup/start/site-updates.html
+++ b/en/setup/start/site-updates.html
@@ -30,6 +30,98 @@
log</a>.
</p>
+<h2 id="Aug-2018">August 2018</h2>
+
+<p>Hello and welcome to the revised Android Open Source Project (AOSP) website.
+As our site has grown, we’ve reorganized the platform documentation navigation
+to better accommodate new and updated information.</p>
+
+<p>Please see the subsections below for a guide to major changes. See the <a
+ href="/setup/start/p-release-notes">Release Notes</a> for feature summaries,
+ updates, and additions. Send us your feedback via bugs filed at <a
+ href="https://g.co/androidsourceissue"
+ class="external">g.co/androidsourceissue</a> or by clicking the <a
+ href="https://issuetracker.google.com/issues/new?component=191476">Site
+ Feedback</a> link in the footer of every page on the site.</p>
+
+<h3 id="second-menu">Second horizontal menu</h3>
+
+<p>The most sweeping change is the introduction of a second horizontal menu of
+tabs within the site’s navigation to better expose deeper pages.
+Now, instead of left navigation menus containing dozens of entries, each subtab
+contains a small list of sections and pages directly relevant to the associated
+topic identified in the subtab.</p>
+
+<p>Note we have not yet updated directory paths and URLs for existing
+documentation to avoid breaking bookmarks and external links… yet. In
+time, we will make these changes and institute redirects accordingly. So
+revisit the site for new locations and update bookmarks as you find
+changes.</p>
+
+<h3 id="set-up">Setup to Set up</h3>
+
+<p>The main <strong>Set up</strong> tab has been renamed slightly from
+<em>Setup</em> to match the verbs used for subsequent primary tabs.
+<strong>Download</strong> and <strong>Build</strong> contents have been split
+into distinct subtabs to ease access to the pages they contain. The
+<em>Develop</em> subsection has been renamed as a <strong>Create</strong>
+subtab to avoid confusion with the new top-level <strong>Develop</strong> tab
+of the same name.</p>
+
+<p>The information previously found on the <em>Compatibility > Contact
+Us</em> page has been merged into the main <strong>Set up > Contact
+(Community)</strong> list.
+</p>
+
+<h3 id="design">Compatibility to Design</h3>
+
+<p>The information formerly found on the <em>Compatibility</em> top-level tab
+can now be found under <strong>Design</strong>. See the
+<strong>Compatibility</strong> subtab for an overview of that program and links
+to the new <em>Android Compatibility Definition Document (CDD)</em>.</p>
+
+<p>In a related change, instructions for the <em>Android Compatibility Test
+Suite (CTS)</em> and general debugging information have been moved to a
+new <strong>Tests</strong> subtab. <strong>Display</strong> and
+<strong>Settings</strong> menu guidelines have been shifted to dedicated
+subtabs.</p>
+
+<h3 id="develop">Porting to Develop</h3>
+
+<p>The <em>Porting</em> tab has been renamed <strong>Develop</strong> to better
+convey the instructions this tab contains. Largely focused upon implementing
+individual interfaces, this documentation helps you write the drivers necessary
+to connect your device to the Android operating system.</p>
+
+<p>As a result, the <strong>Architecture</strong> section describing the
+overarching <em>HIDL</em> format has been moved to the <strong>Design</strong>
+tab for consideration during the planning phase, earlier in the development
+cycle. The <strong>Bootloader</strong> contents now live under
+<strong>Design > Architecture,</strong> while an
+<strong>Interaction</strong> subtab has been introduced to contain
+<em>Input</em>, <em>Sensors</em>, and related information.</p>
+
+<p>The <strong>Connectivity</strong> section has been reorganized to include
+<strong>Bluetooth and NFC</strong>, <strong>Calling and Messaging</strong>,
+<strong>Carrier</strong>, and <strong>Wi-Fi</strong> subsections. In addition,
+the Wi-Fi section includes the following new articles:</p>
+
+<ul>
+ <li><a href="/devices/tech/connect/wifi-overview">Overview</a></li>
+ <li><a href="/devices/tech/connect/wifi-hal">Wi-Fi HAL</a></li>
+ <li><a href="/devices/tech/connect/wifi-passpoint">Passpoint R1</a></li>
+ <li><a href="/devices/tech/connect/wifi-debug">Testing and Debugging</a></li>
+</ul>
+
+<h3 id="configure">Tuning to Configure</h3>
+
+<p>The <em>Tuning</em> tab has been renamed <strong>Configure</strong> to encapsulate more than
+customization and optimization steps. The former <em>Device Administration</em>
+subsection is now found under <strong>Enterprise</strong>. The <em>ART and
+Dalvik</em> contents reside under <strong>ART</strong>, and
+<em>Over-the-air (OTA) update</em> information lives under
+<strong>Updates</strong>.</p>
+
<h2 id="Dec-2017">December 2017</h2>
<p>
Android 8.1 has been released! See the entries below for the major platform
diff --git a/ja/security/bulletin/2018-06-01.html b/ja/security/bulletin/2018-06-01.html
index 4d0983b..007d793 100644
--- a/ja/security/bulletin/2018-06-01.html
+++ b/ja/security/bulletin/2018-06-01.html
@@ -29,7 +29,7 @@
下記の問題のうち最も重大度の高いものは、メディア フレームワークに重大なセキュリティの脆弱性があるため、リモートの攻撃者が特別に細工したファイルを使用して、特権プロセス内で任意のコードを実行するおそれがあることです。<a href="/security/overview/updates-resources.html#severity">重大度の評価</a>は、攻撃対象の端末でその脆弱性が悪用された場合の影響に基づくもので、プラットフォームやサービスでのリスク軽減策が開発目的または不正な回避により無効となっていることを前提としています。
</p>
<p>
-この新たに報告された問題によって実際のユーザー端末が不正使用された報告はありません。<a href="#mitigations">Android セキュリティ プラットフォームの保護</a>や Google Play プロテクトについて詳しくは、<a href="/security/enhancements/index.html">Android と Google サービスでのリスク軽減策</a>をご覧ください。こうした保護により、Android プラットフォームのセキュリティが改善されます。
+この新たに報告された問題によって実際のユーザー端末が不正使用された報告はありません。<a href="/security/enhancements/index.html">Android セキュリティ プラットフォームの保護</a>や Google Play プロテクトについて詳しくは、<a href="#mitigations">Android と Google サービスでのリスク軽減策</a>をご覧ください。こうした保護により、Android プラットフォームのセキュリティが改善されます。
</p>
<p class="note">
<strong>注:</strong> 最新の無線（OTA）アップデートと Google 端末のファームウェア イメージについての情報は、<a href="/security/bulletin/pixel/2018-06-01.html">2018 年 6 月の Pixel / Nexus のセキュリティに関する公開情報</a>でご覧いただけます。
diff --git a/ja/security/bulletin/2018.html b/ja/security/bulletin/2018.html
index 6972bd8..17f5aa8 100644
--- a/ja/security/bulletin/2018.html
+++ b/ja/security/bulletin/2018.html
@@ -33,6 +33,20 @@
<th>公開日</th>
<th>セキュリティ パッチレベル</th>
</tr>
+ <tr>
+ <td><a href="/security/bulletin/2018-07-01.html">2018 年 7 月</a></td>
+ <td>
+ <a href="/security/bulletin/2018-07-01.html">English</a> /
+ <a href="/security/bulletin/2018-07-01.html?hl=ja">日本語</a> /
+ <a href="/security/bulletin/2018-07-01.html?hl=ko">한국어</a> /
+ <a href="/security/bulletin/2018-07-01.html?hl=ru">ру́сский</a> /
+ <a href="/security/bulletin/2018-07-01.html?hl=zh-cn">中文（中国）</a>/
+ <a href="/security/bulletin/2018-07-01.html?hl=zh-tw">中文（台灣）</a>
+ </td>
+ <td>2018 年 7 月 4 日</td>
+ <td>2018-07-01<br />
+ 2018-07-05</td>
+ </tr>
<tr>
<td><a href="/security/bulletin/2018-06-01.html">2018 年 6 月</a></td>
<td>
@@ -119,4 +133,4 @@
</tr>
</tbody></table>
-</body></html>
\ No newline at end of file
+</body></html>
diff --git a/ja/security/bulletin/index.html b/ja/security/bulletin/index.html
index 1f04001..f0eed84 100644
--- a/ja/security/bulletin/index.html
+++ b/ja/security/bulletin/index.html
@@ -55,6 +55,20 @@
<th>公開日</th>
<th>セキュリティ パッチレベル</th>
</tr>
+ <tr>
+ <td><a href="/security/bulletin/2018-07-01.html">2018 年 7 月</a></td>
+ <td>
+ <a href="/security/bulletin/2018-07-01.html">English</a> /
+ <a href="/security/bulletin/2018-07-01.html?hl=ja">日本語</a> /
+ <a href="/security/bulletin/2018-07-01.html?hl=ko">한국어</a> /
+ <a href="/security/bulletin/2018-07-01.html?hl=ru">ру́сский</a> /
+ <a href="/security/bulletin/2018-07-01.html?hl=zh-cn">中文（中国）</a>/
+ <a href="/security/bulletin/2018-07-01.html?hl=zh-tw">中文（台灣）</a>
+ </td>
+ <td>2018 年 7 月 4 日</td>
+ <td>2018-07-01<br />
+ 2018-07-05</td>
+ </tr>
<tr>
<td><a href="/security/bulletin/2018-06-01.html">2018 年 6 月</a></td>
<td>
@@ -68,7 +82,8 @@
<td>2018 年 6 月 4 日</td>
<td>2018-06-01<br />
2018-06-05</td>
- </tr><tr>
+ </tr>
+ <tr>
<td><a href="/security/bulletin/2018-05-01.html">2018 年 5 月</a></td>
<td>
<a href="/security/bulletin/2018-05-01.html">English</a> /
@@ -534,4 +549,4 @@
</tr>
</tbody></table>
-</body></html>
\ No newline at end of file
+</body></html>
diff --git a/ja/security/bulletin/pixel/2018.html b/ja/security/bulletin/pixel/2018.html
index 7006e61..ccd99e3 100644
--- a/ja/security/bulletin/pixel/2018.html
+++ b/ja/security/bulletin/pixel/2018.html
@@ -33,6 +33,19 @@
<th>公開日</th>
<th>セキュリティ パッチレベル</th>
</tr>
+ <tr>
+ <td><a href="/security/bulletin/pixel/2018-07-01.html">2018 年 7 月</a></td>
+ <td>
+ <a href="/security/bulletin/pixel/2018-07-01.html">English</a> /
+ <a href="/security/bulletin/pixel/2018-07-01.html?hl=ja">日本語</a> /
+ <a href="/security/bulletin/pixel/2018-07-01.html?hl=ko">한국어</a> /
+ <a href="/security/bulletin/pixel/2018-07-01.html?hl=ru">ру́сский</a> /
+ <a href="/security/bulletin/pixel/2018-07-01.html?hl=zh-cn">中文（中国）</a>/
+ <a href="/security/bulletin/pixel/2018-07-01.html?hl=zh-tw">中文（台灣）</a>
+ </td>
+ <td>2018 年 7 月 4 日</td>
+ <td>2018-07-05</td>
+ </tr>
<tr>
<td><a href="/security/bulletin/pixel/2018-06-01.html">2018 年 6 月</a></td>
<td>
@@ -115,4 +128,4 @@
</tr>
</tbody></table>
-</body></html>
\ No newline at end of file
+</body></html>
diff --git a/ja/security/bulletin/pixel/index.html b/ja/security/bulletin/pixel/index.html
index 6b3f561..a563eb2 100644
--- a/ja/security/bulletin/pixel/index.html
+++ b/ja/security/bulletin/pixel/index.html
@@ -42,6 +42,19 @@
<th>公開日</th>
<th>セキュリティ パッチレベル</th>
</tr>
+ <tr>
+ <td><a href="/security/bulletin/pixel/2018-07-01.html">2018 年 7 月</a></td>
+ <td>
+ <a href="/security/bulletin/pixel/2018-07-01.html">English</a> /
+ <a href="/security/bulletin/pixel/2018-07-01.html?hl=ja">日本語</a> /
+ <a href="/security/bulletin/pixel/2018-07-01.html?hl=ko">한국어</a> /
+ <a href="/security/bulletin/pixel/2018-07-01.html?hl=ru">ру́сский</a> /
+ <a href="/security/bulletin/pixel/2018-07-01.html?hl=zh-cn">中文（中国）</a>/
+ <a href="/security/bulletin/pixel/2018-07-01.html?hl=zh-tw">中文（台灣）</a>
+ </td>
+ <td>2018 年 7 月 4 日</td>
+ <td>2018-07-05</td>
+ </tr>
<tr>
<td><a href="/security/bulletin/pixel/2018-06-01.html">2018 年 6 月</a></td>
<td>
@@ -161,4 +174,4 @@
</tr>
</tbody></table>
-</body></html>
\ No newline at end of file
+</body></html>
diff --git a/ko/security/bulletin/2018-06-01.html b/ko/security/bulletin/2018-06-01.html
index fb75389..02479e3 100644
--- a/ko/security/bulletin/2018-06-01.html
+++ b/ko/security/bulletin/2018-06-01.html
@@ -47,8 +47,8 @@
실제 고객이 새로 보고된 이러한 문제로 인해 악용당했다는 신고는
접수되지 않았습니다. Android 플랫폼의 보안을 개선하는
<a href="/security/enhancements/index.html">Android 보안 플랫폼 보호</a>
-및 Google Play Protect 관련 세부정보를 보려면
-<a href="#mitigations">Android 및 Google Play Protect 완화</a>
+및 Google Play 프로텍트 관련 세부정보를 보려면
+<a href="#mitigations">Android 및 Google Play 프로텍트 완화</a>
섹션을 참조하세요.
</p>
<p class="note">
@@ -62,7 +62,7 @@
<h2 id="mitigations">Android 및 Google 서비스 완화</h2>
<p>
다음은
-<a href="https://www.android.com/play-protect">Google Play Protect</a>와 같은
+<a href="https://www.android.com/play-protect">Google Play 프로텍트</a>와 같은
<a href="/security/enhancements/index.html">Android 보안 플랫폼</a> 및 서비스 보호 기능에서
제공하는 완화에 관한 요약입니다.
이러한 기능을 통해 Android에서
@@ -72,7 +72,7 @@
<li>Android 플랫폼 최신 버전의 향상된 기능으로 Android의 여러 문제를
악용하기가 더욱 어려워졌습니다. 가능하다면 모든 사용자는 최신 버전의 Android로
업데이트하는 것이 좋습니다.</li>
-<li>Android 보안팀에서는 <a href="https://www.android.com/play-protect">Google Play Protect</a>를 통해 악용사례를 모니터링하고 <a href="/security/reports/Google_Android_Security_PHA_classifications.pdf">잠재적으로 위험한 애플리케이션</a>에 관해 사용자에게 경고를 보냅니다. Google Play Protect는 <a href="http://www.android.com/gms">Google 모바일 서비스</a>가 적용된 기기에 기본적으로 사용 설정되어 있으며 Google Play 외부에서 가져온 앱을 설치하는 사용자에게 특히 중요합니다.</li>
+<li>Android 보안팀에서는 <a href="https://www.android.com/play-protect">Google Play 프로텍트</a>를 통해 악용사례를 모니터링하고 <a href="/security/reports/Google_Android_Security_PHA_classifications.pdf">잠재적으로 위험한 애플리케이션</a>에 관해 사용자에게 경고를 보냅니다. Google Play Protect는 <a href="http://www.android.com/gms">Google 모바일 서비스</a>가 적용된 기기에 기본적으로 사용 설정되어 있으며 Google Play 외부에서 가져온 앱을 설치하는 사용자에게 특히 중요합니다.</li>
</ul>
<h2 id="2018-06-01-details">2018-06-01 보안 패치 수준 취약성 세부정보</h2>
<p>
diff --git a/ko/security/bulletin/pixel/2018-06-01.html b/ko/security/bulletin/pixel/2018-06-01.html
index e082e83..d1a0a48 100644
--- a/ko/security/bulletin/pixel/2018-06-01.html
+++ b/ko/security/bulletin/pixel/2018-06-01.html
@@ -47,16 +47,16 @@
패치도 포함되어 있습니다. 파트너에게는 적어도 1개월 전에 이러한 문제와 관련해 알림이 전송되었으며
이러한 패치를 기기 업데이트의 일부로 포함하도록 선택할 수
있습니다.</p>
-<h2 id="security-patches">보안 업데이트</h2>
+<h2 id="security-patches">보안 패치</h2>
<p>
취약성은 영향을 받는 구성요소 아래에 분류되어 있습니다. 여기에는
문제 설명 및 CVE, 관련 참조,
<a href="#type">취약성 유형</a>,
<a href="https://source.android.com/security/overview/updates-resources.html#severity">심각도</a>,
-업데이트된 Android 오픈소스 프로젝트(AOSP) 버전(해당하는 경우)이 포함된 표가 제시됩니다. 가능한 경우
-AOSP 변경사항 목록과 같이 문제를 해결한 공개 변경사항을 버그 ID에
-연결합니다. 하나의 버그와 관련된 변경사항이 여러 개인 경우 추가 참조가
-버그 ID 다음에 오는 번호에 연결됩니다.
+업데이트된 Android 오픈소스 프로젝트(AOSP) 버전(해당하는 경우)이 포함된 표가 제시됩니다. 가능한
+경우 AOSP 변경사항 목록과 같이 문제를 해결한 공개 변경사항을 버그 ID에
+연결합니다. 하나의 버그와 관련된 변경사항이 여러 개인 경우
+추가 참조가 버그 ID 다음에 오는 번호에 연결됩니다.
</p>
<h3 id="framework">프레임워크</h3>
@@ -77,21 +77,21 @@
<tr>
<td>CVE-2018-9374</td>
<td><a href="https://android.googlesource.com/platform/frameworks/base/+/62b500f99595e99e1db8f0c068f719e68c73551e">A-72710897</a></td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
</tr>
<tr>
<td>CVE-2018-9375</td>
<td><a href="https://android.googlesource.com/platform/packages/providers/UserDictionaryProvider/+/cccf7d5c98fc81ff4483f921fb4ebfa974add9c6">A-75298708</a></td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
</tr>
<tr>
<td>CVE-2018-9377</td>
<td>A-64752751<a href="#asterisk">*</a></td>
- <td>ID</td>
+ <td>ID </td>
<td>보통</td>
<td>6.0, 6.0.1</td>
</tr>
@@ -115,7 +115,7 @@
<tr>
<td>CVE-2018-9378</td>
<td><a href="https://android.googlesource.com/platform/frameworks/av/+/e0c09e4dd62e033aa9688634844d19136c0d34bc">A-73126106</a></td>
- <td>ID</td>
+ <td>ID </td>
<td>보통</td>
<td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
</tr>
@@ -123,16 +123,16 @@
<td>CVE-2018-9379</td>
<td><a href="https://android.googlesource.com/platform/frameworks/base/+/42e5aed1d106bef1f8913ffe87aa1f9df6aae90c">A-63766886</a>
[<a href="https://android.googlesource.com/platform/packages/providers/MediaProvider/+/76ffd8258c483b7170af49a8a67702426df07f2f">2</a>]</td>
- <td>ID</td>
+ <td>ID </td>
<td>보통</td>
<td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
</tr>
<tr>
<td rowspan="2">CVE-2018-9349</td>
<td rowspan="2"><a href="https://android.googlesource.com/platform/external/libvpx/+/69ddad629d1db85d8531af694c910626a1e80a9f">A-72510002</a></td>
- <td>ID</td>
+ <td>ID </td>
<td>보통</td>
- <td>7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
+ <td>7.0, 7.1.1, 7.1.2, 8.0, 8.1 </td>
</tr>
<tr>
<td>DoS</td>
@@ -142,9 +142,9 @@
<tr>
<td rowspan="2">CVE-2018-9350</td>
<td rowspan="2"><a href="https://android.googlesource.com/platform/external/libavc/+/fde8eda71e8f7bc9c973fe6fbdd3846951b340ed">A-73552574</a></td>
- <td>ID</td>
+ <td>ID </td>
<td>보통</td>
- <td>7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
+ <td>7.0, 7.1.1, 7.1.2, 8.0, 8.1 </td>
</tr>
<tr>
<td>DoS</td>
@@ -154,9 +154,9 @@
<tr>
<td rowspan="2">CVE-2018-9351</td>
<td rowspan="2"><a href="https://android.googlesource.com/platform/external/libavc/+/27c639d897fb0f1f0acf6a58b5c013d65c63bd04">A-73625898</a></td>
- <td>ID</td>
+ <td>ID </td>
<td>보통</td>
- <td>7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
+ <td>7.0, 7.1.1, 7.1.2, 8.0, 8.1 </td>
</tr>
<tr>
<td>DoS</td>
@@ -167,9 +167,9 @@
<td rowspan="2">CVE-2018-9352</td>
<td rowspan="2"><a href="https://android.googlesource.com/platform/external/libhevc/+/a7303e887a40ab164b19b310068e13ac4f123edc">A-73965867</a>
[<a href="https://android.googlesource.com/platform/external/libhevc/+/9434d4d8846241f0575aaf48ee7d4342e926ae77">2</a>]</td>
- <td>ID</td>
+ <td>ID </td>
<td>보통</td>
- <td>7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
+ <td>7.0, 7.1.1, 7.1.2, 8.0, 8.1 </td>
</tr>
<tr>
<td>DoS</td>
@@ -179,9 +179,9 @@
<tr>
<td rowspan="2">CVE-2018-9353</td>
<td rowspan="2"><a href="https://android.googlesource.com/platform/external/libhevc/+/7ea8a36d5de35d71ace260a695199093fcc1f08f">A-73965890</a></td>
- <td>ID</td>
+ <td>ID </td>
<td>보통</td>
- <td>7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
+ <td>7.0, 7.1.1, 7.1.2, 8.0, 8.1 </td>
</tr>
<tr>
<td>DoS</td>
@@ -193,7 +193,7 @@
<td rowspan="2"><a href="https://android.googlesource.com/platform/frameworks/av/+/f5d61ac18c72c9abdbbd971bfae7ce8b073eb08a">A-74067957</a></td>
<td>NSI</td>
<td>NSI</td>
- <td>7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
+ <td>7.0, 7.1.1, 7.1.2, 8.0, 8.1 </td>
</tr>
<tr>
<td>DoS</td>
@@ -220,21 +220,21 @@
<tr>
<td>CVE-2018-9380</td>
<td><a href="https://android.googlesource.com/platform/system/bt/+/85677abe2cc90bcd8b9df127088a97657d17c986">A-75298652</a></td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
- <td>7.0, 7.1.1, 7.1.2, 8.0, 8.1</td>
+ <td>7.0, 7.1.1, 7.1.2, 8.0, 8.1 </td>
</tr>
<tr>
<td>CVE-2018-9381</td>
<td><a href="https://android.googlesource.com/platform/system/bt/+/0519f6aa5345be0917ad52188479230148adf8bd">A-73125709</a></td>
- <td>ID</td>
+ <td>ID </td>
<td>보통</td>
<td>8.1</td>
</tr>
<tr>
<td>CVE-2018-9382</td>
<td>A-35765136<a href="#asterisk">*</a></td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2</td>
</tr>
@@ -258,51 +258,51 @@
<tr>
<td>CVE-2018-9383</td>
<td>A-73827422<a href="#asterisk">*</a></td>
- <td>ID</td>
+ <td>ID </td>
<td>보통</td>
<td>asn1_decoder</td>
</tr>
<tr>
<td>CVE-2018-9384</td>
<td>A-74356909<br />
- <a href="https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=c02433dd6de32f042cf3ffe476746b1115b8c096">업스트림 커널</a></td>
- <td>ID</td>
+ <a href="https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=c02433dd6de32f042cf3ffe476746b1115b8c096">Upstream kernel</a></td>
+ <td>ID </td>
<td>보통</td>
<td>커널</td>
</tr>
<tr>
<td>CVE-2018-9385</td>
<td>A-74128061<br />
- <a href="https://patchwork.kernel.org/patch/10175611/">업스트림 커널</a></td>
- <td>EoP</td>
+ <a href="https://patchwork.kernel.org/patch/10175611/">Upstream kernel</a></td>
+ <td>EoP </td>
<td>보통</td>
<td>amba</td>
</tr>
<tr>
<td>CVE-2018-9386</td>
<td>A-71363680<a href="#asterisk">*</a></td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>HTC reboot_block 드라이버</td>
</tr>
<tr>
<td>CVE-2018-9387</td>
<td>A-69006385<a href="#asterisk">*</a></td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>mnh_sm 드라이버</td>
</tr>
<tr>
<td>CVE-2018-9388</td>
<td>A-68343441<a href="#asterisk">*</a></td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>ftm4_touch</td>
</tr>
<tr>
<td>CVE-2018-9389</td>
<td>A-65023306<a href="#asterisk">*</a></td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>ipv4/ipv6</td>
</tr>
@@ -310,8 +310,8 @@
<td>CVE-2018-7480</td>
<td>A-76106168<br />
<a href="http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=9b54d816e00425c3a517514e0d677bb3cec49258">
-업스트림 커널</a></td>
- <td>EoP</td>
+Upstream kernel</a></td>
+ <td>EoP </td>
<td>보통</td>
<td>블록 처리 프로그램</td>
</tr>
@@ -319,8 +319,8 @@
<td>CVE-2017-18075</td>
<td>A-73237057<br />
<a href="http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=d76c68109f37cb85b243a1cf0f40313afd2bae68">
-업스트림 커널</a></td>
- <td>EoP</td>
+Upstream kernel</a></td>
+ <td>EoP </td>
<td>보통</td>
<td>pcrypt</td>
</tr>
@@ -345,7 +345,7 @@
<td>CVE-2018-9390</td>
<td>A-76100614<a href="#asterisk">*</a><br />
M-ALPS03849277</td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>wlanThermo procfs 항목</td>
</tr>
@@ -353,7 +353,7 @@
<td>CVE-2018-9391</td>
<td>A-72313579<a href="#asterisk">*</a><br />
M-ALPS03762614</td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>GPS HAL</td>
</tr>
@@ -361,7 +361,7 @@
<td>CVE-2018-9392</td>
<td>A-72312594<a href="#asterisk">*</a><br />
M-ALPS03762614</td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>GPS HAL</td>
</tr>
@@ -369,7 +369,7 @@
<td>CVE-2018-9393</td>
<td>A-72312577<a href="#asterisk">*</a><br />
M-ALPS03753748</td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>MTK wlan</td>
</tr>
@@ -377,7 +377,7 @@
<td>CVE-2018-9394</td>
<td>A-72312468<a href="#asterisk">*</a><br />
M-ALPS03753652</td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>MTK P2P 드라이버</td>
</tr>
@@ -385,7 +385,7 @@
<td>CVE-2018-9395</td>
<td>A-72312071<a href="#asterisk">*</a><br />
M-ALPS03753735</td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>MTK cfg80211</td>
</tr>
@@ -393,7 +393,7 @@
<td>CVE-2018-9396</td>
<td>A-71867113<a href="#asterisk">*</a><br />
M-ALPS03740353</td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>Mediatek CCCI</td>
</tr>
@@ -402,7 +402,7 @@
<td>A-71866634<a href="#asterisk">*</a><br />
M-ALPS03532675<br />
M-ALPS03479586</td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>Mediatek WMT 기기</td>
</tr>
@@ -410,7 +410,7 @@
<td>CVE-2018-9398</td>
<td>A-71866289<a href="#asterisk">*</a><br />
M-ALPS03740468</td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>FM 라디오 드라이버</td>
</tr>
@@ -418,7 +418,7 @@
<td>CVE-2018-9399</td>
<td>A-71866200<a href="#asterisk">*</a><br />
M-ALPS03740489</td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>/proc/driver/wmt_dbg 드라이버</td>
</tr>
@@ -426,15 +426,15 @@
<td>CVE-2018-9400</td>
<td>A-71865884<a href="#asterisk">*</a><br />
M-ALPS03753678</td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
- <td>Goodix Touchscreen Driver</td>
+ <td>Goodix 터치스크린 드라이버</td>
</tr>
<tr>
<td>CVE-2017-13308</td>
<td>A-70728757<a href="#asterisk">*</a><br />
M-ALPS03751855</td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>thermal</td>
</tr>
@@ -442,7 +442,7 @@
<td>CVE-2018-9401</td>
<td>A-70511226<a href="#asterisk">*</a><br />
M-ALPS03693409</td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>cameraisp</td>
</tr>
@@ -450,7 +450,7 @@
<td>CVE-2018-9402</td>
<td>A-70728072<a href="#asterisk">*</a><br />
M-ALPS03684171</td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>WLAN 드라이버</td>
</tr>
@@ -458,7 +458,7 @@
<td>CVE-2018-9403</td>
<td>A-72313700<a href="#asterisk">*</a><br />
M-ALPS03762413</td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>HAL</td>
</tr>
@@ -466,7 +466,7 @@
<td>CVE-2018-9404</td>
<td>A-72314374<a href="#asterisk">*</a><br />
M-ALPS03773299</td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>무선 인터페이스 레이어</td>
</tr>
@@ -474,7 +474,7 @@
<td>CVE-2018-9405</td>
<td>A-72314804<a href="#asterisk">*</a><br />
M-ALPS03762818</td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>DmAgent</td>
</tr>
@@ -482,7 +482,7 @@
<td>CVE-2018-9406</td>
<td>A-70726950<a href="#asterisk">*</a><br />
M-ALPS03684231</td>
- <td>ID</td>
+ <td>ID </td>
<td>보통</td>
<td>NlpService</td>
</tr>
@@ -490,7 +490,7 @@
<td>CVE-2018-9407</td>
<td>A-70728406<a href="#asterisk">*</a><br />
M-ALPS03902529</td>
- <td>ID</td>
+ <td>ID </td>
<td>보통</td>
<td>emmc</td>
</tr>
@@ -498,7 +498,7 @@
<td>CVE-2018-9408</td>
<td>A-70729980<a href="#asterisk">*</a><br />
M-ALPS03693684</td>
- <td>ID</td>
+ <td>ID </td>
<td>보통</td>
<td>GPS</td>
</tr>
@@ -523,7 +523,7 @@
<td>CVE-2017-15824</td>
<td>A-68163089<a href="#asterisk">*</a><br />
QC-CR#2107596</td>
- <td>ID</td>
+ <td>ID </td>
<td>보통</td>
<td>EDK2 부트로더</td>
</tr>
@@ -531,7 +531,7 @@
<td>CVE-2018-5897</td>
<td>A-70528036<a href="#asterisk">*</a><br />
QC-CR#2172685</td>
- <td>ID</td>
+ <td>ID </td>
<td>보통</td>
<td>diag</td>
</tr>
@@ -539,7 +539,7 @@
<td>CVE-2018-5895</td>
<td>A-70293535<a href="#asterisk">*</a><br />
QC-CR#2161027</td>
- <td>ID</td>
+ <td>ID </td>
<td>보통</td>
<td>qcacld</td>
</tr>
@@ -547,7 +547,7 @@
<td>CVE-2018-5836</td>
<td>A-74237168<br />
<a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=12a789c2e0e9fd2df40ac13ac27fe99487263887">QC-CR#2160375</a></td>
- <td>ID</td>
+ <td>ID </td>
<td>보통</td>
<td>WLAN</td>
</tr>
@@ -556,7 +556,7 @@
<td>A-72957387<br />
<a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-2.0/commit/?id=cf1c43ce8840021d2907afaa6c514e6971d7ebac">
QC-CR#2129566</a></td>
- <td>ID</td>
+ <td>ID </td>
<td>보통</td>
<td>WLAN</td>
</tr>
@@ -565,7 +565,7 @@
<td>A-68992463<br />
<a href="https://source.codeaurora.org/quic/la/abl/tianocore/edk2/commit/?id=6ad7ccfee4f78d23b4b8f5ebda0eef54dced32e3">
QC-CR#2107596</a></td>
- <td>ID</td>
+ <td>ID </td>
<td>보통</td>
<td>부트로더</td>
</tr>
@@ -574,7 +574,7 @@
<td>A-68992461<br />
<a href="https://source.codeaurora.org/quic/la/abl/tianocore/edk2/commit/?id=c8dc3bf07ee909e6e57ad7887f9d3c0ffa5df795">
QC-CR#2104835</a></td>
- <td>ID</td>
+ <td>ID </td>
<td>보통</td>
<td>부트로더</td>
</tr>
@@ -583,7 +583,7 @@
<td>A-68992457<br />
<a href="https://source.codeaurora.org/quic/la/abl/tianocore/edk2/commit/?id=1daa83baa41d1e6291e89f69e6487695b6890c01">
QC-CR#2073366</a></td>
- <td>ID</td>
+ <td>ID </td>
<td>보통</td>
<td>부트로더</td>
</tr>
@@ -592,7 +592,7 @@
<td>A-74237664<br />
<a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=4cc54a30958d2a8d989364aa45a27fde3dd17352">
QC-CR#2146949</a></td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>WLAN</td>
</tr>
@@ -600,7 +600,7 @@
<td>CVE-2016-5342, CVE-2016-5080</td>
<td>A-72232294<a href="#asterisk">*</a><br />
QC-CR#1032174</td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>WLAN 드라이버</td>
</tr>
@@ -608,7 +608,7 @@
<td>CVE-2018-5899</td>
<td>A-71638332<a href="#asterisk">*</a><br />
QC-CR#1040612</td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>WLAN 드라이버</td>
</tr>
@@ -617,7 +617,7 @@
<td>A-71501675<br />
<a href="https://source.codeaurora.org/quic/la/abl/tianocore/edk2/commit/?id=c9c8de8000ff32f8d1e24e697d861d92d8ed0b7a">
QC-CR#2127348</a></td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>부트로더</td>
</tr>
@@ -626,7 +626,7 @@
<td>A-71501674<br />
<a href="https://source.codeaurora.org/quic/la/abl/tianocore/edk2/commit/?id=a95ca8e2eeb8a030e977f033cff122cad408158c">
QC-CR#2127341</a></td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>부트로더</td>
</tr>
@@ -635,7 +635,7 @@
<td>A-71501672<br />
<a href="https://source.codeaurora.org/quic/la/abl/tianocore/edk2/commit/?id=5388803fa6d004382f4a857056ce06d963698d9c">
QC-CR#2127312</a></td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>부트로더</td>
</tr>
@@ -644,7 +644,7 @@
<td>A-71501669<br />
<a href="https://source.codeaurora.org/quic/la/abl/tianocore/edk2/commit/?id=c8415f6f2271008aef5056689950236df627d9b1">
QC-CR#2127305</a></td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>부트로더</td>
</tr>
@@ -652,7 +652,7 @@
<td>CVE-2018-5898</td>
<td>A-71363804<a href="#asterisk">*</a><br />
QC-CR#2173850</td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>QC 오디오 드라이버</td>
</tr>
@@ -660,7 +660,7 @@
<td>CVE-2018-5832</td>
<td>A-69065862<a href="#asterisk">*</a><br />
QC-CR#2149998</td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>Camerav2</td>
</tr>
@@ -668,7 +668,7 @@
<td>CVE-2018-5857</td>
<td>A-62536960<a href="#asterisk">*</a><br />
QC-CR#2169403</td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>wcd_cpe_core</td>
</tr>
@@ -677,7 +677,7 @@
<td>A-74237782<br />
<a href="https://source.codeaurora.org/quic/la/kernel/msm-4.4/commit/?id=e569b915a246627d0449016408a9c0d388ee4ab4">
QC-CR#2143070</a></td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>DSP_Services</td>
</tr>
@@ -686,7 +686,7 @@
<td>A-72957546<br />
<a href="https://source.codeaurora.org/quic/la/kernel/msm-4.4/commit/?id=782cd411398e3cf2aca1615ab2649df0c46920ee">
QC-CR#2062648</a></td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>DSP_Services</td>
</tr>
@@ -694,7 +694,7 @@
<td>CVE-2017-15856</td>
<td>A-72957506<br />
<a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-2.0/commit/?id=ed02c0ccd6f7461a69d64903738372eaf21babcd">QC-CR#2111922</a></td>
- <td>EoP</td>
+ <td>EoP </td>
<td>보통</td>
<td>power_stats debugfs 노드</td>
</tr>
@@ -755,11 +755,11 @@
<td>A-74413120</td>
<td>블루투스</td>
<td>BLE 성능 개선</td>
- <td>모두</td>
+ <td>전체</td>
</tr>
<tr>
<td>A-76022834</td>
- <td>실적</td>
+ <td>성능</td>
<td>연결 상태가 좋지 않은 지역에 있는 경우 안테나 전환 동작 개선</td>
<td>Pixel 2, Pixel 2 XL</td>
</tr>
@@ -802,9 +802,10 @@
</p>
<p>
2018-06-05 보안 패치 수준 및 그 이전의 모든 패치 수준과 관련된
-모든 문제는 2018-06-05 보안 패치 수준 이상에서 해결됩니다. 기기의 보안 패치 수준을 확인하는 방법을
-알아보려면 <a href="https://support.google.com/pixelphone/answer/4457705#pixel_phones&nexus_devices">Pixel 및 Nexus 업데이트 일정</a>의
-안내를 참조하세요.
+모든 문제는 2018-06-05 보안 패치 수준 이상에서 해결됩니다. 기기의
+보안 패치 수준을 확인하는 방법을 알아보려면 <a href="https://support.google.com/pixelphone/answer/4457705#pixel_phones&nexus_devices">Pixel
+및 Nexus 업데이트 일정</a>의 안내를 참조하세요.
+
</p>
<p id="type">
<strong>2. <em>유형</em> 열의 항목은 무엇을 의미하나요?</strong>
@@ -825,11 +826,11 @@
<td>원격 코드 실행</td>
</tr>
<tr>
- <td>EoP</td>
+ <td>EoP </td>
<td>권한 승격</td>
</tr>
<tr>
- <td>ID</td>
+ <td>ID </td>
<td>정보 공개</td>
</tr>
<tr>
@@ -883,9 +884,10 @@
</p>
<p>
공개되지 않은 문제는 <em>참조</em> 열의 Android 버그 ID 옆에 * 표시가
-있습니다. 일반적으로 이러한 문제에 관한 업데이트는
-<a href="https://developers.google.com/android/nexus/drivers">Google 개발자 사이트</a>에서 제공하는 Pixel&hairsp;/&hairsp;Nexus 기기용
-최신 바이너리 드라이버에 포함되어 있습니다.
+있습니다. 일반적으로 이러한 문제에 관한 업데이트는 <a href="https://developers.google.com/android/nexus/drivers">Google
+개발자 사이트</a>에서 제공되는 Pixel / Nexus 기기용 최신 바이너리
+드라이버에 포함되어
+있습니다.
</p>
<p>
<strong>5. 보안 취약성이 이 게시판과 Android 보안 게시판에 나뉘어져 있는 이유가
diff --git a/ru/security/bulletin/2018-03-01.html b/ru/security/bulletin/2018-03-01.html
index 42e1021..6369f31 100644
--- a/ru/security/bulletin/2018-03-01.html
+++ b/ru/security/bulletin/2018-03-01.html
@@ -32,7 +32,7 @@
Самая серьезная из проблем – критическая уязвимость в Media Framework, которая позволяет злоумышленнику выполнять произвольный код в контексте привилегированного процесса с помощью специально созданного файла. <a href="/security/overview/updates-resources.html#severity">Уровень серьезности</a> зависит от того, какой ущерб будет нанесен устройству при атаке с использованием уязвимости, если средства защиты будут отключены разработчиком или взломаны.
</p>
<p>
-У нас нет информации о том, что обнаруженные уязвимости эксплуатировались. В разделе <a href="#mitigations">Предотвращение атак</a> рассказано, как <a href="/security/enhancements/index.html">платформа безопасности</a> и Google Play Защита помогают снизить вероятность атак на Android.
+У нас нет информации о том, что обнаруженные уязвимости эксплуатировались. В разделе <a href="#mitigations">Предотвращение атак</a> рассказывается, как <a href="/security/enhancements/index.html">платформа безопасности</a> и Google Play Защита помогают снизить вероятность атак на Android.
</p>
<p class="note">
<strong>Примечание.</strong> Информация о последних автоматических обновлениях (OTA) и образах встроенного ПО для устройств Google содержится в <a href="/security/bulletin/pixel/2018-03-01.html">бюллетене по безопасности Pixel и Nexus</a> за март 2018 года.
@@ -40,7 +40,7 @@
<h2 id="mitigations">Предотвращение атак</h2>
<p>
-Ниже рассказано, как <a href="/security/enhancements/index.html">платформа безопасности</a> и средства защиты сервисов, например <a href="https://www.android.com/play-protect">Google Play Защита</a>,
+Ниже рассказывается, как <a href="/security/enhancements/index.html">платформа безопасности</a> и средства защиты сервисов, например <a href="https://www.android.com/play-protect">Google Play Защита</a>,
позволяют снизить вероятность атак на Android.
</p>
<ul>
diff --git a/ru/security/bulletin/2018-06-01.html b/ru/security/bulletin/2018-06-01.html
index 4bc79cd..9355df6 100644
--- a/ru/security/bulletin/2018-06-01.html
+++ b/ru/security/bulletin/2018-06-01.html
@@ -32,7 +32,7 @@
Самая серьезная из проблем – критическая уязвимость в Media Framework, которая позволяет злоумышленнику выполнять произвольный код в контексте привилегированного процесса с помощью специально созданного файла. <a href="/security/overview/updates-resources.html#severity">Уровень серьезности</a> зависит от того, какой ущерб будет нанесен устройству при атаке с использованием уязвимости, если средства защиты будут отключены разработчиком или взломаны.
</p>
<p>
-У нас нет информации о том, что обнаруженные уязвимости эксплуатировались. В разделе <a href="#mitigations">Предотвращение атак</a> рассказано о том, как <a href="/security/enhancements/index.html">платформа безопасности</a> и Google Play Защита помогают снизить вероятность атак на Android.
+У нас нет информации о том, что обнаруженные уязвимости эксплуатировались. В разделе <a href="#mitigations">Предотвращение атак</a> рассказывается, как <a href="/security/enhancements/index.html">платформа безопасности</a> и Google Play Защита помогают снизить вероятность атак на Android.
</p>
<p class="note">
<strong>Примечание.</strong> Информация о последних автоматических обновлениях (OTA) и образах встроенного ПО для устройств Google приведена в <a href="/security/bulletin/pixel/2018-06-01.html">бюллетене по безопасности Pixel и Nexus</a> за июнь 2018 года.
@@ -40,7 +40,7 @@
<h2 id="mitigations">Предотвращение атак</h2>
<p>
-Ниже рассказано о том, как <a href="/security/enhancements/index.html">платформа безопасности</a> и средства защиты сервисов, например <a href="https://www.android.com/play-protect">Google Play Защита</a>,
+Ниже рассказывается, как <a href="/security/enhancements/index.html">платформа безопасности</a> и средства защиты сервисов, например <a href="https://www.android.com/play-protect">Google Play Защита</a>,
позволяют снизить вероятность атак на Android.
</p>
<ul>
diff --git a/ru/security/bulletin/pixel/2018-06-01.html b/ru/security/bulletin/pixel/2018-06-01.html
index 8bd4372..b9d87dc 100644
--- a/ru/security/bulletin/pixel/2018-06-01.html
+++ b/ru/security/bulletin/pixel/2018-06-01.html
@@ -23,20 +23,20 @@
<p><em>Опубликовано 4 июня 2018 г. | Обновлено 6 июня 2018 г.</em></p>
<p>
-В этом бюллетене содержится информация об уязвимостях в защите и об улучшениях функциональных возможностей <a href="https://support.google.com/pixelphone/answer/4457705#pixel_phones&nexus_devices">поддерживаемых устройств Pixel и Nexus</a> (устройства Google).
+В этом бюллетене содержится информация об уязвимостях в защите и улучшениях функциональных возможностей <a href="https://support.google.com/pixelphone/answer/4457705#pixel_phones&nexus_devices">поддерживаемых устройств Pixel и Nexus</a> (устройства Google).
Все проблемы, перечисленные здесь и в бюллетене по безопасности Android за июнь 2018 года, устранены в исправлении от 5 июня 2018 года или более новом. Информацию о том, как проверить обновления системы безопасности, можно найти в <a href="https://support.google.com/pixelphone/answer/4457705">Справочном центре</a>.
</p>
<p>
-Поддерживаемые устройства Google получат обновление системы безопасности 2018-06-05. Мы рекомендуем всем пользователям установить перечисленные здесь обновления.
+Обновление системы безопасности 2018-06-05 получат все поддерживаемые устройства Google. Мы настоятельно рекомендуем пользователям установить это обновление.
</p>
<p class="note">
-<strong>Примечание.</strong> Образы встроенного ПО для устройств Google находятся на <a href="https://developers.google.com/android/images">сайте для разработчиков</a>.
+<strong>Примечание.</strong> Образы встроенного ПО для устройств Google можно найти на <a href="https://developers.google.com/android/images">сайте для разработчиков</a>.
</p>
<h2 id="announcements">Объявления</h2>
-<p>Помимо исправлений уязвимостей, описанных в бюллетене по безопасности Android за июнь 2018 года, обновления для устройств Pixel и Nexus содержат также исправления проблем, перечисленных ниже. Мы сообщили партнерам об этих проблемах по крайней мере месяц назад. Они могут включить их исправления в свои обновления безопасности.</p>
+<p>Помимо исправлений уязвимостей, описанных в бюллетене по безопасности Android за июнь 2018 года, обновления для устройств Pixel и Nexus содержат также исправления проблем, перечисленных ниже. Мы сообщили партнерам об этих проблемах не менее месяца назад. Они могут включить эти исправления в свои обновления безопасности.</p>
<h2 id="security-patches">Обновления системы безопасности</h2>
<p>
-Уязвимости сгруппированы по компонентам, которые они затрагивают. Для каждого приведены описание и таблица с CVE, ссылками, <a href="#type">типом</a>, <a href="https://source.android.com/security/overview/updates-resources.html#severity">уровнем серьезности</a>, а также версиями AOSP (при наличии). Где возможно, мы приводим основную ссылку на опубликованное изменение, связанное с идентификатором ошибки (например, список AOSP), и дополнительные ссылки в квадратных скобках.
+Уязвимости сгруппированы по компонентам, которые они затрагивают. Для каждого приведены описание и таблица с CVE, ссылками, <a href="#type">типом</a>, <a href="https://source.android.com/security/overview/updates-resources.html#severity">уровнем серьезности</a>, а также версиями AOSP (при наличии). Где возможно, идентификаторы ошибки содержат ссылку на опубликованное изменение (например, список AOSP). Если опубликованных изменений несколько, дополнительные ссылки указаны в квадратных скобках.
</p>
<h3 id="framework">Framework</h3>
@@ -681,7 +681,7 @@
<h3 id="qualcomm-closed-source-components">Компоненты Qualcomm с закрытым исходным кодом</h3>
<p>
-Эти уязвимости затрагивают компоненты Qualcomm и описаны в бюллетенях по безопасности Qualcomm AMSS или оповещениях системы безопасности.
+Эти уязвимости затрагивают компоненты Qualcomm. Они описаны в бюллетенях по безопасности Qualcomm AMSS или оповещениях системы безопасности.
Уровень серьезности этих уязвимостей определяется непосредственно компанией Qualcomm.
</p>
@@ -735,7 +735,7 @@
<tr>
<td>A-76022834</td>
<td>Производительность</td>
- <td>Улучшено переключение между антеннами в зонах со слабым покрытием.</td>
+ <td>Улучшено переключение между антеннами в зонах со слабым покрытием сети.</td>
<td>Pixel 2, Pixel 2 XL</td>
</tr>
<tr>
@@ -755,7 +755,7 @@
A-74058011</td>
<td>Экран</td>
- <td>Повышена стабильность показа информации на заблокированном экране.</td>
+ <td>Повышена стабильность работы функции "Информация на заблокированном экране".</td>
<td>Pixel 2 XL</td>
</tr>
<tr>
@@ -812,7 +812,7 @@
</tr>
</tbody></table>
<p>
-<strong>3. На что указывают записи в столбце <em>Ссылки</em>?</strong>
+<strong>3. Что означает информация в столбце <em>Ссылки</em>?</strong>
</p>
<p>
В таблицах с описанием уязвимостей есть столбец <em>Ссылки</em>. Каждая запись в нем может содержать префикс, указывающий на источник ссылки, а именно:
@@ -855,7 +855,7 @@
<strong>5. Почему теперь одни уязвимости описываются в этом бюллетене, а другие – в бюллетенях по безопасности Android?</strong>
</p>
<p>
-В бюллетене по безопасности Android описаны уязвимости, которые необходимо устранить в последнем обновлении системы безопасности для устройств Android. Решать дополнительные проблемы, перечисленные здесь, для этого не требуется.
+В бюллетене по безопасности Android описаны уязвимости, которые необходимо устранить в последнем обновлении системы безопасности для устройств Android. Исправление дополнительных проблем, перечисленных здесь, для выпуска этого обновления не требуется.
</p>
<h2 id="versions">Версии</h2>
<table>
diff --git a/zh-cn/_book.yaml b/zh-cn/_book.yaml
index 6fe11a7..4c604ac 100644
--- a/zh-cn/_book.yaml
+++ b/zh-cn/_book.yaml
@@ -769,7 +769,13 @@
title: 概览
- path: /devices/tech/config/ambient
title: Ambient 权能
- - path: /devices/tech/config/carrier
+ - section:
+ - path: /devices/tech/config/carrier
+ title: 运营商配置
+ - path: /devices/tech/config/update
+ title: APN 和 CarrierConfig
+ - path: /devices/tech/config/uicc
+ title: UICC
title: 运营商定制
- path: /devices/tech/config/filesystem
title: 文件 DAC 配置
@@ -781,8 +787,6 @@
title: 运行时权限
- path: /devices/tech/config/timezone-rules
title: 时区规则
- - path: /devices/tech/config/uicc
- title: UICC
- path: /devices/tech/config/usb-hal
title: USB HAL
- path: /devices/tech/config/voicemail
diff --git a/zh-cn/compatibility/cts/camera-hal.html b/zh-cn/compatibility/cts/camera-hal.html
index 9a03b9d..77aba12 100644
--- a/zh-cn/compatibility/cts/camera-hal.html
+++ b/zh-cn/compatibility/cts/camera-hal.html
@@ -22,9 +22,9 @@
<p>本文档列出了可用于评估 Android 相机硬件抽象层 (HAL) 的所有测试，它面向的是原始设备制造商 (OEM) 和应用处理器 (AP) 供应商，旨在帮助他们确保正确实现相机 HAL，并最大限度减少缺陷。尽管这是 Android 兼容性测试套件 (CTS) 的自愿性补充测试，但它显著扩大了相机测试覆盖范围，并且确实能够发现一些潜在错误。</p>
-<p>通过执行这些测试，原始设备制造商 (OEM) 可验证其是否正确集成了最新的 Android 相机硬件抽象层 (HAL) 3.2 接口。当符合核对清单中的所有规范时，设备实施可被视为<em></em>完全符合新的 Android 相机 HAL 接口规范。这反过来又使得设备能够正确支持构建相机应用所依据的全新 <code>android.hardware.camera2</code> 文件包。</p>
+<p>通过执行这些测试，原始设备制造商 (OEM) 可验证其是否正确集成了最新的 Android 相机硬件抽象层 (HAL) 3.2 接口。当符合核对清单中的所有规范时，设备实现可被视为<em></em>完全符合新的 Android 相机 HAL 接口规范。这反过来又使得设备能够正确支持构建相机应用所依据的全新 <code>android.hardware.camera2</code> 文件包。</p>
-<h2 id="camera_hal_3_2_specification">[ ] 1. 相机 HAL 3.2 规范</h2>
+<h2 id="camera_hal_3_2_specification">相机 HAL 3.2 规范</h2>
<p>Android 相机 HAL 3.2 规范是有关设备必须满足哪些要求的权威信息来源；本文档提供了所有测试的摘要，可将其用作核对清单。相机 HAL 实现方（例如 AP 供应商）应逐条检查 HAL 3.2 规范，并确保其设备符合该规范。</p>
@@ -36,85 +36,37 @@
</li><li><em></em>HAL 像素格式接口和规范：<code><a href="https://android.googlesource.com/platform/system/core/+/master/include/system/graphics.h">system/core/include/system/graphics.h</a></code>
</li></ul>
-<h2 id="camera_test_types">[ ] 2. 相机测试类型</h2>
+<h2 id="camera_test_types">相机测试类型</h2>
<p>以下是适用于最新 Android 相机的主要测试类型以及相关说明：</p>
<ul>
- <li><em><a href="#native_tests">原生</a></em>：直接针对相机 HAL 接口的测试</li><li><em><a href="#cts_tests">兼容性测试套件 (CTS)</a></em>：自动运行的标准 Android 测试，可确保设备兼容性；有关详情，请参阅 <a href="/compatibility/cts/index.html">CTS 简介</a>和<a href="/devices/tech/test_infra/tradefed/index.html">贸易联盟概述</a>
- </li><li><em><a href="#its_tests">图像测试套件 (ITS)</a></em>：手动运行的测试，可确保图像正确性；有关设置说明，请参阅顶级和测试专用的 <code>README</code> 文件以及 tutorial.py</li><li><em><a href="#manual_tests_with_aosp_camera_app">针对 Android 开放源代码项目 (AOSP) 相机应用的手动测试</a></em>：对常见相机功能进行用户体验之类的测试</li><li><em><a href="#manual_testingcam_tests">手动 TestingCam 测试</a></em>：从源中的 <code>pdk/apps/TestingCamera/</code> 运行
- </li><li><em><a href="#manual_testingcam2_tests">手动 TestingCam2.1 测试</a></em>：从源中的 <code>pdk/apps/TestingCamera2/</code> 运行
+ <li><em><a href="#vendor_test_suite">供应商测试套件 (VTS)</a>：</em>直接针对相机 HAL 接口的测试
+ </li><li><em><a href="#cts_tests">兼容性测试套件 (CTS)</a></em>：自动运行的标准 Android 测试，可确保设备兼容性；有关详情，请参阅 <a href="/compatibility/cts/index.html">CTS 简介</a>和<a href="/devices/tech/test_infra/tradefed/index.html">贸易联盟概述</a>
+ </li><li><em><a href="#its_tests">图像测试套件 (ITS)</a>：</em>手动运行的测试，可确保图像正确性；有关设置说明，请参阅顶级和测试专用的 <code>README</code> 文件以及 <code>tutorial.py</code>
+ </li><li><em><a href="#manual_testingcam_tests">手动 TestingCam 测试</a>：</em>从源中的 <code>pdk/apps/TestingCamera/</code> 运行
+ </li><li><em><a href="#manual_testingcam2_tests">手动 TestingCam2.1 测试</a>：从源中的 <code>pdk/apps/TestingCamera2/</code></em> 运行
</li></ul>
<p>下面详细介绍了所有这些测试类型。我们按照 OEM 应执行这些测试的时间先后顺序对它们进行了介绍。</p>
<p>例如，如果设备未通过原生测试，那么肯定无法通过随后的兼容性测试套件 (CTS) 测试。如果设备未能通过 CTS，则没必要继续进行图像测试套件 (ITS) 测试。我们建议先解决每种测试类型中发现的问题，然后再进行下一组测试。</p>
-<h2 id="native_tests">[ ] 3. 原生测试</h2>
+<h2 id="vendor_test_suite">供应商测试套件 (VTS) 测试</h2>
-<p>这类测试会直接测试相机 HAL 接口。</p>
+<p>Android 供应商测试套件 (VTS) 是在 HIDL 接口一级运行的测试套件。要详细了解如何使用 VTS，请参阅<a href="/compatibility/vts/">供应商测试套件</a>。</p>
-<p>相机原生测试的起始路径为：<code>platform/hardware/libhardware</code></p>
-
-<p>设置这类测试的命令如下：</p>
-
-<pre class="devsite-click-to-copy">
-<code class="devsite-terminal">cd hardware/libhardware/tests/camera*/</code>
-<code class="devsite-terminal">mm</code>
-<code class="devsite-terminal">adb remount; adb sync</code>
-</pre>
-
-<h3 id="hal_3_x_tests">[ ] 3.1. HAL 3.x 测试</h3>
-
-<p>这类相机测试位于以下路径：<code>hardware/libhardware/tests/camera3/*</code></p>
-
-<p>运行所有测试的命令如下：</p>
-
-<pre class="devsite-terminal devsite-click-to-copy">
-adb shell /data/nativetest/camera3_test/camera3_test
-</pre>
-
-<p>对于每项通过的测试，您会收到 <strong>OK</strong>。在输出信息末尾处会提供错误日志，以及有关所有已通过测试的摘要。</p>
-
-<h3 id="hal_2_3_tests">[ ] 3.2. HAL 2/3 测试</h3>
-
-<p>这类相机测试位于以下路径：<code>hardware/libhardware/tests/camera2/*</code></p>
-
-<p>运行所有测试的命令如下：</p>
-
-<pre class="devsite-terminal devsite-click-to-copy">
-adb shell /data/nativetest/camera3_test/camera3_test
-</pre>
-
-<p>要运行单个测试，请传递 <code>--gtest_filter</code> 参数和相应测试名称，命令如下：</p>
-
-<pre class="devsite-terminal devsite-click-to-copy">
-adb shell /data/nativetest/camera2_test/camera2_test --gtest_filter=Camera2Test.OpenClose
-</pre>
-
-<p>要运行一小组测试，请使用带有 <code>--gtest_filter</code> 参数的通配符，命令如下：</p>
-
-<pre class="devsite-terminal devsite-click-to-copy">
-adb shell /data/nativetest/camera2_test/camera2_test --gtest_filter=Camera2Test.*
-</pre>
-
-<h3 id="3_tests_that_interact_with_the_camera_service">[ ] 3.3. 与相机服务交互的测试</h3>
-
-<p>这类相机测试位于以下路径：<code>frameworks/av/camera/tests/*</code></p>
-
-<h3 id="camera_metadata_tests">[ ] 3.4. 相机元数据测试</h3>
-
-<p>这类相机测试位于以下路径：<code>system/media/camera/tests/*</code></p>
-
-<h2 id="cts_tests">[ ] 4. 兼容性测试套件 (CTS) 测试</h2>
+<h2 id="cts_tests">兼容性测试套件 (CTS) 测试</h2>
<p>相机 Android 兼容性测试套件 (CTS) 测试重点测试设备兼容性。这类测试不需要特定的测试环境（唯一的例外是视野范围/FOV CTS 验证程序测试）。</p>
-<p>相机 CTS 测试的起始路径为：<code>platform/cts</code></p>
+<p>相机 CTS 测试的起始路径为：<code>platform/cts</code>。</p>
+
+<p>在针对支持外部相机（如 USB 网络摄像头）的设备运行相机 CTS 时，您必须在运行 CTS 时将设备连接到充电器，否则测试将自动失败。</p>
<p>有关运行 CTS 的常规说明，请参阅 <a href="/compatibility/cts/index.html">CTS 简介</a>及其子页面。</p>
-<h3 id="cts_tests_for_the_android_hardware_camera_api">[ ] 4.1. 针对 <code>android.hardware.Camera</code> API 的 CTS 测试</h3>
+<h3 id="cts_tests_for_the_android_hardware_camera_api">针对 <code>android.hardware.Camera</code> API 的 CTS 测试</h3>
<p>这类相机测试位于 <code>cts/tests/tests/</code> 路径下的下列位置：</p>
@@ -125,7 +77,7 @@
</li><li><code>permission/src/android/permission/cts/CameraPermissionTest.java</code>
</li></ul>
-<h3 id="cts_tests_for_the_android_hardware_camera2_api">[ ] 4.2. 针对 <code>android.hardware.camera2</code> API 的 CTS 测试</h3>
+<h3 id="cts_tests_for_the_android_hardware_camera2_api">针对 <code>android.hardware.camera2</code> API 的 CTS 测试</h3>
<p>这类相机测试位于 <code>cts/tests/tests/</code> 路径下的下列位置：</p>
@@ -134,11 +86,11 @@
</li><li><code>permission/src/android/permission/cts/Camera2PermissionTest.java</code>
</li></ul>
-<h3 id="cts_verifier_camera_tests">[ ] 4.3. CTS 验证程序相机测试</h3>
+<h3 id="cts_verifier_camera_tests">CTS 验证程序相机测试</h3>
<p>这类相机测试位于以下路径：<code>cts/apps/CtsVerifier/src/com/android/cts/verifier/camera/*</code></p>
-<h2 id="its_tests">[ ] 5. 图像测试套件 (ITS) 测试</h2>
+<h2 id="its_tests">图像测试套件 (ITS) 测试</h2>
<p>CameraITS 测试重点测试图像的正确性。这些 Python 脚本在通过 USB 连接 Android 设备的工作站上手动运行。该工作站可以运行具备必需的 Python 2.7 环境的任何操作系统。</p>
@@ -158,73 +110,25 @@
<p>有关脚本使用方法的演示，请参阅 <code>tests</code> 子目录中的 <code>tutorial.py</code>。每项测试都归属于相应的 <code>tests/scene<#></code> 子目录。有关具体的测试说明，请参阅每个子目录中的 <code>README</code> 文件。</p>
-<p>您将需要使用由可重复使用的特定目标（如白色墙面、灰色卡片和台灯）构建的简单物理环境。Android 设备安装在三脚架上，而设备的相机功能通过脚本运行。大多数测试的结果要么是通过，要么是失败，不过有些测试还会提供一些指标。</p>
+<p>要按照推荐的方法设置和运行相机图像测试套件，请参阅<a href="/compatibility/cts/camera-its-box">相机盒装 ITS</a>。</p>
+
+<p>要手动运行 ITS，您将需要使用由可重复使用的特定目标（如白色墙面、灰色卡片和台灯）构建的简单物理环境。Android 设备安装在三脚架上，而设备的相机功能通过脚本运行。大多数测试的结果要么是通过，要么是失败，不过有些测试还会提供一些指标。</p>
<p>这些测试仍在不断开发改进，还不够全面，无法对相机 HAL 进行完全自动化的通过/失败验证。但是，这些脚本确实可以测试未在 CTS 中测试的情景，而且还是整个 HAL 3.2 测试计划的重要组成部分。</p>
-<h3 id="its_tests_on_scene_0_plain">[ ] 5.1. 对场景 0（纯色）的 ITS 测试</h3>
+<h3 id="its_tests_on_scene_0_plain">对场景 0（纯色）的 ITS 测试</h3>
<p>此测试不需要特定设置。所有相机（背面 + 正面 + 任何其他相机）都必须通过 <code>tests/scene0</code> 文件夹中的所有测试。</p>
-<h3 id="its_tests_on_scene_1_grey_card">[ ] 5.2. 对场景 1（灰色卡片）的 ITS 测试</h3>
+<h3 id="its_tests_on_scene_1_grey_card">对场景 1（灰色卡片）的 ITS 测试</h3>
<p>所有相机（背面 + 正面 + 任何其他相机）都必须通过 <code>tests/scene1</code> 文件夹中的所有测试。<code>tests/scene1/README</code> 文件对场景设置进行了说明。</p>
-<h3 id="its_tests_on_scene_2_camera_lab">[ ] 5.3. 对场景 2（相机实验室）的 ITS 测试</h3>
+<h3 id="its_tests_on_scene_2_camera_lab">对场景 2（相机实验室）的 ITS 测试</h3>
<p>所有相机（背面 + 正面 + 任何其他相机）都必须通过 <code>tests/scene2</code> 文件夹中的所有测试。<code>tests/scene2/README</code> 文件对场景设置进行了说明。</p>
-<h2 id="manual_tests_with_aosp_camera_app">[ ] 6. 针对 AOSP 应用的手动测试</h2>
-
-<h3 id="camera_mode_aosp_camera_app">[ ] 6.1. 相机模式</h3>
-
-<p>对于设备上的所有相机（正面、背面和任何其他相机），您需要验证以下内容：</p>
-
-<ol>
- <li>可以在设备上拍照和查看图像，并且图像效果良好，没有明显的问题。
- </li><li>点按对焦、连续自动对焦、微距对焦、无限远对焦、自动白平衡和自动曝光控制均可正常使用。
- </li><li>使用数码变焦时（拍摄期间），点按对焦、连续自动对焦、自动白平衡和自动曝光控制均可正常使用。
- </li><li>闪光灯设置（开启/关闭/自动）可正常使用，并且能与 3A 有效同步。
-</li></ol>
-
-<h3 id="video_mode_aosp_camera_app">[ ] 6.2. 视频模式</h3>
-
-<p>对于设备上的所有相机（正面、背面和任何其他相机），您需要验证以下内容：</p>
-
-<ol>
- <li>可以在设备上拍摄和查看视频，并且视频效果良好，没有明显的问题。
- </li><li>在录制视频的过程中能够正常拍摄快照。
- </li><li>点按对焦、连续自动对焦、微距对焦、无限远对焦、自动白平衡和自动曝光控制均可正常使用。
- </li><li>使用数码变焦时（拍摄期间），点按对焦、连续自动对焦、自动白平衡和自动曝光控制均可正常使用。
- </li><li>手电筒设置（开启/关闭）可正常使用，并且能与 3A 有效同步。
-</li></ol>
-
-<h3 id="camera_settings_resolution">[ ] 6.3. 相机设置：分辨率</h3>
-
-<p>对于设备上的所有相机（正面、背面和任何其他相机）以及菜单中可用的所有分辨率，您需要验证是否返回并应用了正确的分辨率设置：</p>
-
-<ul>
- <li>相机模式</li><li>视频模式</li><li>镜头模糊</li><li>PhotoSphere</li><li>全景</li></ul>
-
-<h3 id="camera_settings_exposure_compensation">[ ] 6.4. 相机设置：曝光补偿</h3>
-
-<p>验证是否应用了曝光补偿（+2 和 -2）。</p>
-
-<h3 id="photosphere">[ ] 6.5. PhotoSphere</h3>
-
-<p>分别通过前置和后置摄像头拍摄 360 度全景 PhotoSphere 图像。确认每一帧都对焦在无限远处，并且各个拍摄画面之间的曝光和白平衡是一致的。</p>
-
-<h3 id="panorama">[ ] 6.6. 全景</h3>
-
-<p>拍摄纵向、横向和广角全景（分别使用前置和后置摄像头），然后确认每一帧都对焦在无限远处，并且各个拍摄画面之间的曝光和白平衡是一致的。</p>
-
-<h3 id="lensblur">[ ] 6.7. 镜头模糊</h3>
-
-<p>分别使用前置和后置摄像头拍摄一张镜头模糊图像，然后确认（在查看拍摄的照片时）重新对焦于不同景深的功能能够正常运行。</p>
-
-<p>此外，在此模式下验证点按对焦、连续自动对焦、自动白平衡和自动曝光控制是否能正常使用。</p>
-
-<h2 id="media_framework_tests">[ ] 7. 媒体框架测试</h2>
+<h2 id="media_framework_tests">媒体框架测试</h2>
<p>通过 MediaFrameworkTest 中与相机相关的所有媒体测试。请注意，运行这些测试需要在 Android 设备上安装 mediaframeworktest.apk。您将需要 <code>make mediaframeworktest</code>，然后使用 adb 来安装生成的 .apk。下面提供了命令示例。</p>
@@ -258,7 +162,7 @@
</li><li><code>unit/</code>
</li></ul>
-<h3 id="running_media_framework_tests">[ ] 7.1. 运行媒体框架测试</h3>
+<h3 id="running_media_framework_tests">运行媒体框架测试</h3>
<p>查看所有可用测试的命令如下：</p>
@@ -279,7 +183,8 @@
(target=com.android.mediaframeworktest)
</pre>
-<p>从每个测试行中识别并提取组件（位于 <code>instrumentation:</code> 和 <code>(target=com.android.mediaframeworktest) </code>之间）。该组件包含目标文件包名称 (<code>com.android.mediaframeworktest</code>) 和测试运行器名称 (<code>MediaFramework<type>TestRunner</type></code>)。</p>
+<p>从每个测试行中识别并提取组件（位于 <code>instrumentation:</code> 和 <code>(target=com.android.mediaframeworktest) </code>之间）。
+该组件包含目标软件包名称 (<code>com.android.mediaframeworktest</code>) 和测试运行器名称 (<code>MediaFramework<type>TestRunner</type></code>)。</p>
<p>例如：</p>
@@ -293,10 +198,10 @@
<p>然后，您可以将每个组件传递到 <code>adb shell am instrument</code>，如下所示：</p>
<pre class="devsite-terminal devsite-click-to-copy">
-adb shell am instrument -w <component.name>
+adb shell am instrument -w <var>component.name</var>
</pre>
-<p>其中 <component.name> 等同于上面提取的值。例如：</p>
+ <p>其中 <code><var>component.name</var></code> 等同于上面提取的值。例如：</p>
<pre class="devsite-terminal devsite-click-to-copy">
adb shell am instrument -w com.android.mediaframeworktest/.MediaFrameworkIntegrationTestRunner
@@ -316,7 +221,7 @@
adb shell am instrument -e class 'com.android.mediaframeworktest.integration.CameraBinderTest#testConnectPro' -w com.android.mediaframeworktest/.MediaFrameworkIntegrationTestRunner
</pre>
-<h3 id="media_settings_functional_tests">[ ] 7.2. 媒体设置功能测试</h3>
+<h3 id="media_settings_functional_tests">媒体设置功能测试</h3>
<p>下面是一个运行功能测试的示例。该测试用于验证不同相机设置（即闪光灯、曝光、白平衡、场景、照片大小和地理标记）组合的基本功能。</p>
@@ -325,7 +230,7 @@
adb shell am instrument -w -r -e delay_msec 15 -e log true -e class com.android.mediaframeworktest.functional.camera.CameraPairwiseTest com.android.mediaframeworktest/com.android.mediaframeworktest.CameraStressTestRunner
</pre>
-<h3 id="media_integration_tests">[ ] 7.3. 媒体集成测试</h3>
+<h3 id="media_integration_tests">媒体集成测试</h3>
<p>下面是一个运行集成测试的示例，此例中包括 mediaframeworktest/integration/CameraBinderTest.java 和 mediaframeworktest/CameraStressTestRunner.java：</p>
@@ -347,7 +252,7 @@
-----
</pre>
-<h3 id="media_performance_tests">[ ] 7.4. 媒体性能测试</h3>
+<h3 id="media_performance_tests">媒体性能测试</h3>
<p>此预览存储空间测试将打开并释放 200 次相机预览。系统每隔 20 次迭代会记录一次 ps mediaserver 的快照，并且在 200 次迭代后比较存储空间使用量的差异。如果差异大于 150kM，则表明未通过测试。</p>
@@ -358,7 +263,7 @@
<p>更详细的输出信息位于以下路径：<code>/sdcard/mediaMemOutput.txt</code></p>
-<h3 id="media_unit_tests">[ ] 7.5. 媒体单元测试</h3>
+<h3 id="media_unit_tests">媒体单元测试</h3>
<p>用于执行单元测试的命令很相似。例如，对于 CameraMetadataTest.java，测试命令如下：</p>
@@ -366,7 +271,7 @@
adb shell am instrument -e class 'com.android.mediaframeworktest.unit.CameraMetadataTest' -w 'com.android.mediaframeworktest/.CameraStressTestRunner'
</pre>
-<h3 id="media_stress_tests">[ ] 7.6. 媒体压力测试</h3>
+<h3 id="media_stress_tests">媒体压力测试</h3>
<p>该测试用于对相机进行拍照压力测试和视频录制压力测试。</p>
@@ -378,21 +283,21 @@
<p>您必须确保通过所有测试。</p>
-<h2 id="manual_testingcam_tests">[ ] 8. 手动 TestingCam 测试</h2>
+<h2 id="manual_testingcam_tests">手动 TestingCam 测试</h2>
<p>您必须手动运行 TestingCam 应用并执行以下检查。TestingCam 的来源位于以下位置：<code>pdk/apps/TestingCamera/</code></p>
-<h3 id="infinity_focus_with_camera_tilt">[ ] 8.1. 利用相机倾斜度进行无限远聚焦</h3>
+<h3 id="infinity_focus_with_camera_tilt">利用相机倾斜度进行无限远聚焦</h3>
<p>启动 TestingCam，打开预览，并确保将自动对焦模式设置为无限远。使用<strong>拍照</strong>按钮，给距离较远（至少 10 米距离）的对象拍摄照片，且相机方向为水平、向上（接近垂直）和向下（接近垂直）；例如，向上拍摄可以是从下面拍摄大树高处的树叶/分枝，而向下拍摄则可以是从建筑物的顶部俯拍下面的街道。在所有情况下，距离较远的拍摄对象都必须成像清晰且对焦准确。保存并查看图库视图中的照片，以便您可以放大并且更轻松地检查锐度。</p>
<p>请注意，对于具有 VCM 执行器的相机，要通过此测试，则需要使用闭环自动对焦控制系统，或者需要使用加速度计数据来确定相机方向，并据此进行一些 SW 校正。此外，还需要对镜头无限远位置进行可靠的工厂校准。</p>
-<h2 id="manual_testingcam2_tests">[ ] 9. 手动 TestingCam2 测试</h2>
+<h2 id="manual_testingcam2_tests">手动 TestingCam2 测试</h2>
<p>您必须手动运行 TestingCam2 应用并执行以下检查。TestingCam2 的来源位于以下位置：<code>pdk/apps/TestingCamera2/</code></p>
-<h3 id="9_1_jpeg_capture">[ ] 9.1. JPEG 拍照</h3>
+<h3 id="9_1_jpeg_capture">JPEG 拍照</h3>
<p>启动 TestingCam2，然后按 <strong>JPEG</strong> 按钮。显示在取景器图像右侧的图像应与取景器相同，包括具有一致的方向。</p>
diff --git a/zh-cn/devices/tech/debug/index.html b/zh-cn/devices/tech/debug/index.html
index be66afc..d1079db 100644
--- a/zh-cn/devices/tech/debug/index.html
+++ b/zh-cn/devices/tech/debug/index.html
@@ -22,10 +22,9 @@
<p>本部分总结了开发平台级功能时，可用于调试、跟踪和分析原生 Android 平台代码的实用工具和相关命令。</p>
-<p class="note"><strong>注意</strong>：本部分和本网站其他部分的页面建议您使用 <code>adb</code> 和 <code>setprop</code> 参数一起调试 Android 的某些方面。请注意，在 Android 操作系统的 O 版本之前，属性名称的长度上限为 32 个字符。也就是说，要创建一个包含应用名称的 wrap 属性，您需要截断该名称以使其符合字符数限制。在 Android O 及更高版本中，此字符数上限值要大得多，应该不需要截断。</p>
+<p class="note"><strong>注意</strong>：本部分和本网站其他部分的页面建议您使用 <code>adb</code> 和 <code>setprop</code> 参数一起调试 Android 的特定领域。请注意，在 Android 操作系统的 O 版本之前，属性名称的长度上限为 32 个字符。也就是说，要创建一个包含应用名称的 wrap 属性，您需要截断该名称以使其符合字符数限制。在 Android O 及更高版本中，此字符数上限值要大得多，应该不需要截断。</p>
-<p>本页面介绍了与崩溃转储有关的基本信息（可以在 logcat 输出中找到）。
-其他页面更详细地介绍了如何<a href="/devices/tech/debug/native-crash.html">诊断原生代码崩溃问题</a>，通过 <a href="https://developer.android.com/studio/command-line/dumpsys.html"><code>dumpsys</code></a> 了解系统服务状况，查看<a href="/devices/tech/debug/native-memory.html">本机内存</a>、<a href="https://developer.android.com/studio/command-line/dumpsys.html#network">网络</a>和 <a href="https://developer.android.com/studio/command-line/dumpsys.html#procstats">RAM</a> 使用情况，使用 <a href="/devices/tech/debug/asan.html">AddressSanitizer</a> 检测原生代码中的内存错误，评估<a href="/devices/tech/debug/eval_perf.html">性能问题</a>（包括 <a href="/devices/tech/debug/systrace">systrace</a>），以及使用 <a href="/devices/tech/debug/gdb.html">GNU 调试程序 (GDB)</a> 和其他调试工具。</p>
+<p>本页面介绍了与崩溃转储有关的基本信息（可以在 logcat 输出中找到）。其他页面更详细地介绍了如何<a href="/devices/tech/debug/native-crash.html">诊断原生代码崩溃问题</a>，通过 <a href="https://developer.android.com/studio/command-line/dumpsys.html"><code>dumpsys</code></a> 了解系统服务状况，查看<a href="/devices/tech/debug/native-memory.html">本机内存</a>、<a href="https://developer.android.com/studio/command-line/dumpsys.html#network">网络</a>和 <a href="https://developer.android.com/studio/command-line/dumpsys.html#procstats">RAM</a> 使用情况，使用 <a href="/devices/tech/debug/asan.html">AddressSanitizer</a> 检测原生代码中的内存错误，评估<a href="/devices/tech/debug/eval_perf.html">性能问题</a>（包括 <a href="/devices/tech/debug/systrace">systrace</a>），以及使用 <a href="/devices/tech/debug/gdb.html">GNU 调试程序 (GDB)</a> 和其他调试工具。</p>
<h2 id="debuggerd">崩溃转储</h2>
@@ -116,7 +115,7 @@
0001a7e5 __start_thread+34 bionic/libc/bionic/clone.cpp:46 (discriminator 1)
</pre>
-<p class="note"><strong>注意</strong>：某些系统库是使用 <code>LOCAL_STRIP_MODULE := keep_symbols</code> 编译的，可直接提供可用的回溯，而不会像未剥离版本那样占用较大的空间。</p>
+<p class="note"><strong>注意</strong>：有些系统库是使用 <code>LOCAL_STRIP_MODULE := keep_symbols</code> 编译的，可直接提供可用的回溯，而不会像未剥离版本那样占用较大的空间。</p>
<p>您也可以 <code>stack</code> 整个 tombstone。示例：</p>
<pre class="devsite-terminal devsite-click-to-copy">
diff --git a/zh-cn/devices/tech/ota/index.html b/zh-cn/devices/tech/ota/index.html
index 0ed9dc3..c7f9627 100644
--- a/zh-cn/devices/tech/ota/index.html
+++ b/zh-cn/devices/tech/ota/index.html
@@ -24,6 +24,9 @@
正常使用的 Android 设备可以接收和安装系统和应用软件的无线 (OTA) 更新。本部分介绍了更新包的结构以及构建更新包时所用的工具。它适用于希望将 OTA 更新系统用于新的 Android 设备以及正在编译更新软件包以用于已发布设备的开发者。<em></em>OTA 更新旨在升级基础操作系统和系统分区上安装的只读应用；这些更新不会影响用户从 Google Play 安装的应用。
</p>
+ <p>Android 开源项目 (AOSP) 包含 <a href="https://android.googlesource.com/platform/bootable/recovery/+/master/updater_sample/" class="external">SystemUpdaterSample</a> 应用，该应用可提供关于如何使用 Android 系统更新 API 来安装 OTA 更新的示例。示例应用提供了关于如何使用 <code>update_engine</code> 进行 A/B 更新的示例。有关详情，请参阅 <a href="https://android.googlesource.com/platform/bootable/recovery/+/master/updater_sample/README.md" class="external"><code>updater_sample/README.md</code></a>。
+ </p>
+
<h2 id="ab_updates">A/B（无缝）系统更新</h2>
<p>
diff --git a/zh-cn/devices/tech/perf/boot-times.html b/zh-cn/devices/tech/perf/boot-times.html
index 0a25c23..30531be 100644
--- a/zh-cn/devices/tech/perf/boot-times.html
+++ b/zh-cn/devices/tech/perf/boot-times.html
@@ -320,10 +320,10 @@
使用以下脚本来帮助分析启动性能。
</p>
<ul>
-<li><code>packages/services/Car/tools/bootanalyze/bootanalyze.py</code>：负责衡量启动时间，并详细分析启动过程中的重要步骤。
-</li><li><code>packages/services/Car/tools/io_analysis/check_file_read.py
+<li><code>system/extras/boottime_tools/bootanalyze/bootanalyze.py</code>：负责衡量启动时间，并详细分析启动过程中的重要步骤。
+</li><li><code>system/extras/boottime_tools/io_analysis/check_file_read.py
boot_trace</code>：提供每个文件的访问信息。
-</li><li><code>packages/services/Car/tools/io_analysis/check_io_trace_all.py
+</li><li><code>system/extras/boottime_tools/io_analysis/check_io_trace_all.py
boot_trace</code>：提供系统级细分信息。</li>
</ul>
@@ -565,4 +565,4 @@
<strong>注意</strong>：Chrome 无法处理过大的文件。请考虑使用 <code>tail</code>、<code>head</code> 或 <code>grep</code> 分割 <code>boot_trace</code> 文件，以获得必要的部分。由于事件过多，I/O 分析通常需要直接分析获取的 <code>boot_trace</code>。
</p>
-</body></html>
\ No newline at end of file
+</body></html>
diff --git a/zh-cn/security/advisory/2016-03-18.html b/zh-cn/security/advisory/2016-03-18.html
index d7bd996..45ab14e 100644
--- a/zh-cn/security/advisory/2016-03-18.html
+++ b/zh-cn/security/advisory/2016-03-18.html
@@ -54,7 +54,7 @@
<h3 id="acknowledgements">致谢</h3>
-<p>Android 衷心感谢 <a href="http://c0reteam.org/">C0RE 团队</a>和 <a href="https://www.zimperium.com/">Zimperium</a> 对该安全建议做出的贡献。</p>
+<p>Android 衷心感谢 <a href="http://c0reteam.org/">C0RE 团队</a>和 <a href="https://www.zimperium.com/">Zimperium</a> 对这份安全建议做出的贡献。</p>
<h3 id="suggested_actions">建议操作</h3>
diff --git a/zh-cn/security/bulletin/2018-01-01.html b/zh-cn/security/bulletin/2018-01-01.html
index e6c8795..efd0ae4 100644
--- a/zh-cn/security/bulletin/2018-01-01.html
+++ b/zh-cn/security/bulletin/2018-01-01.html
@@ -33,7 +33,7 @@
尚未有人向我们举报过有用户主动利用或滥用这些新报告的问题。请参阅 <a href="#mitigations">Android 和 Google Play 保护机制提供的缓解措施</a>部分，详细了解有助于提高 Android 平台安全性的 <a href="/security/enhancements/index.html">Android 安全平台防护功能</a>和 Google Play 保护机制。
</p>
<p>
-<strong>注意</strong>：如需了解适用于 Google 设备的最新无线下载更新 (OTA) 和固件映像，请参阅 2018 年 1 月 Pixel/Nexus 安全公告。
+<strong>注意</strong>：如需了解适用于 Google 设备的最新无线下载更新 (OTA) 和固件映像，请参阅 2018 年 1 月的 Pixel/Nexus 安全公告。
</p>
<h2 id="announcements">通告</h2>
<aside class="note">
@@ -231,10 +231,7 @@
</tr>
<tr>
<td>CVE-2017-13209</td>
- <td><a href="https://android.googlesource.com/platform/system/libhidl/+/a4d0252ab5b6f6cc52a221538e1536c5b55c1fa7">
- A-68217907</a>
-[<a href="https://android.googlesource.com/platform/system/tools/hidl/+/8539fc8ac94d5c92ef9df33675844ab294f68d61">2</a>]
-[<a href="https://android.googlesource.com/platform/system/hwservicemanager/+/e1b4a889e8b84f5c13b76333d4de90dbe102a0de">3</a>]</td>
+ <td><a href="https://android.googlesource.com/platform/system/libhidl/+/a4d0252ab5b6f6cc52a221538e1536c5b55c1fa7">A-68217907</a> [<a href="https://android.googlesource.com/platform/system/tools/hidl/+/8539fc8ac94d5c92ef9df33675844ab294f68d61">2</a>] [<a href="https://android.googlesource.com/platform/system/hwservicemanager/+/e1b4a889e8b84f5c13b76333d4de90dbe102a0de">3</a>]</td>
<td>EoP</td>
<td>高</td>
<td>8.0、8.1</td>
diff --git a/zh-cn/security/bulletin/2018-04-01.html b/zh-cn/security/bulletin/2018-04-01.html
index b7141de..b00f979 100644
--- a/zh-cn/security/bulletin/2018-04-01.html
+++ b/zh-cn/security/bulletin/2018-04-01.html
@@ -281,8 +281,7 @@
</tr>
<tr>
<td>CVE-2017-13292</td>
- <td>A-70722061<a href="#asterisk">*</a><br />
- B-V2018010201</td>
+ <td>A-70722061<a href="#asterisk">*</a><br />B-V2018010201</td>
<td>RCE</td>
<td>严重</td>
<td>Bcmdhd 驱动程序</td>
@@ -315,8 +314,7 @@
<tr>
<td>CVE-2017-16534</td>
<td>A-69052594<br />
- <a href="https://github.com/torvalds/linux/commit/2e1c42391ff2556387b3cb6308b24f6f65619feb">
-上游内核</a></td>
+ <a href="https://github.com/torvalds/linux/commit/2e1c42391ff2556387b3cb6308b24f6f65619feb">上游内核</a></td>
<td>ID</td>
<td>高</td>
<td>USB</td>
@@ -342,8 +340,7 @@
<tr>
<td>CVE-2017-15822</td>
<td>A-71501534<br />
- <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=dba4c106922d637ff5965b023b451f6273348eb6">
-QC-CR#2123807</a></td>
+ <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=dba4c106922d637ff5965b023b451f6273348eb6">QC-CR#2123807</a></td>
<td>RCE</td>
<td>严重</td>
<td>WLAN</td>
@@ -351,8 +348,7 @@
<tr>
<td>CVE-2017-17770</td>
<td>A-70237684<br />
- <a href="https://source.codeaurora.org/quic/la/kernel/msm-3.18/commit/?id=284f963af0accf7f921ec10e23acafd71c3a724b">QC-CR#2103199</a>
- [<a href="https://source.codeaurora.org/quic/la/kernel/msm-4.4/commit/?id=3b0c1463e4a6b37d4413a4ba02f1727eeb8693be">2</a>]</td>
+ <a href="https://source.codeaurora.org/quic/la/kernel/msm-3.18/commit/?id=284f963af0accf7f921ec10e23acafd71c3a724b">QC-CR#2103199</a> [<a href="https://source.codeaurora.org/quic/la/kernel/msm-4.4/commit/?id=3b0c1463e4a6b37d4413a4ba02f1727eeb8693be">2</a>]</td>
<td>EoP</td>
<td>高</td>
<td>Binder</td>
@@ -360,8 +356,7 @@
<tr>
<td>CVE-2018-3566</td>
<td>A-72957177<br />
- <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-2.0/commit/?id=11868230d4fe79f76eae30c742b4c68c2899caea">
-QC-CR#2143847</a></td>
+ <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-2.0/commit/?id=11868230d4fe79f76eae30c742b4c68c2899caea">QC-CR#2143847</a></td>
<td>EoP</td>
<td>高</td>
<td>WLAN</td>
@@ -369,9 +364,7 @@
<tr>
<td>CVE-2018-3563</td>
<td>A-72956842<br />
- <a href="https://source.codeaurora.org/quic/la/kernel/msm-4.4/commit/?id=c643a15d73b3fb6329b002662e72dfa96acfdb8a">QC-CR#2143207</a>
- [<a href="https://source.codeaurora.org/quic/la/kernel/msm-3.18/commit/?id=0b8320cd49255177f0c0c8589708e983116ac420">2</a>]
- [<a href="https://source.codeaurora.org/quic/la/platform/vendor/opensource/audio-kernel/commit/?id=d5231fa166521a32621c32fb749b80fc37c13c6a">3</a>]</td>
+ <a href="https://source.codeaurora.org/quic/la/kernel/msm-4.4/commit/?id=c643a15d73b3fb6329b002662e72dfa96acfdb8a">QC-CR#2143207</a> [<a href="https://source.codeaurora.org/quic/la/kernel/msm-3.18/commit/?id=0b8320cd49255177f0c0c8589708e983116ac420">2</a>] [<a href="https://source.codeaurora.org/quic/la/platform/vendor/opensource/audio-kernel/commit/?id=d5231fa166521a32621c32fb749b80fc37c13c6a">3</a>]</td>
<td>EoP</td>
<td>高</td>
<td>音频驱动程序</td>
@@ -379,8 +372,7 @@
<tr>
<td>CVE-2017-13077</td>
<td>A-72957017<br />
- <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=776f17c87599fae3202e69bb5718ac9062f14695">
-QC-CR#2129237</a></td>
+ <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=776f17c87599fae3202e69bb5718ac9062f14695">QC-CR#2129237</a></td>
<td>ID</td>
<td>高</td>
<td>WLAN</td>
@@ -2549,8 +2541,7 @@
<strong>6. 为什么要将安全漏洞拆分到本公告和设备 / 合作伙伴安全公告（如 Pixel/Nexus 公告）中？</strong>
</p>
<p>
-要在 Android 设备上声明最新的安全补丁程序级别，必须修复本安全公告中记录的安全漏洞。但在声明安全补丁程序级别时，并不是必须要修复设备/合作伙伴安全公告中记录的其他安全漏洞。
-我们建议 Android 设备和芯片组制造商通过自己的安全网站（例如 <a href="https://security.samsungmobile.com/securityUpdate.smsb">Samsung</a>、<a href="https://lgsecurity.lge.com/security_updates.html">LGE</a> 或 <a href="/security/bulletin/pixel/">Pixel/Nexus</a> 安全公告）记录其设备上存在的其他修复程序。
+要在 Android 设备上声明最新的安全补丁程序级别，必须修复本安全公告中记录的安全漏洞。但在声明安全补丁程序级别时，并不是必须要修复设备/合作伙伴安全公告中记录的其他安全漏洞。我们建议 Android 设备和芯片组制造商通过自己的安全网站（例如 <a href="https://security.samsungmobile.com/securityUpdate.smsb">Samsung</a>、<a href="https://lgsecurity.lge.com/security_updates.html">LGE</a> 或 <a href="/security/bulletin/pixel/">Pixel/Nexus</a> 安全公告）记录其设备上存在的其他修复程序。
</p>
<h2 id="versions">版本</h2>
<table>
diff --git a/zh-cn/security/bulletin/2018-05-01.html b/zh-cn/security/bulletin/2018-05-01.html
index 4e9471b..8dd2c47 100644
--- a/zh-cn/security/bulletin/2018-05-01.html
+++ b/zh-cn/security/bulletin/2018-05-01.html
@@ -20,7 +20,7 @@
limitations under the License.
-->
-<p><em>发布时间：2018 年 5 月 7 日 | 更新时间：2018 年 5 月 9 日</em></p>
+<p><em>发布时间：2018 年 5 月 7 日 | 更新时间：2018 年 7 月 11 日</em></p>
<p>
本 Android 安全公告详细介绍了会影响 Android 设备的安全漏洞。安全补丁程序级别为 2018-05-05 或更新的 Android 系统都已解决本公告中所述的问题。要了解如何查看设备的安全补丁程序级别，请参阅<a href="https://support.google.com/pixelphone/answer/4457705">查看并更新 Android 版本</a>。
@@ -204,13 +204,6 @@
<td>高</td>
<td>USB 驱动程序</td>
</tr>
- <tr>
- <td>CVE-2017-5754</td>
- <td>A-69856074<a href="#asterisk">*</a></td>
- <td>ID</td>
- <td>高</td>
- <td>内存映射</td>
- </tr>
</tbody></table>
<h3 id="nvidia-components">NVIDIA 组件</h3>
@@ -487,6 +480,11 @@
<td>2018 年 5 月 9 日</td>
<td>在本公告中添加了 AOSP 链接。</td>
</tr>
+ <tr>
+ <td>1.2</td>
+ <td>2018 年 7 月 11 日</td>
+ <td>从 2018-05-05 SPL 中移除了 CVE-2017-5754。</td>
+ </tr>
</tbody></table>
</body></html>
\ No newline at end of file
diff --git a/zh-cn/security/bulletin/pixel/2018-04-01.html b/zh-cn/security/bulletin/pixel/2018-04-01.html
index 5023bb2..8a2460c 100644
--- a/zh-cn/security/bulletin/pixel/2018-04-01.html
+++ b/zh-cn/security/bulletin/pixel/2018-04-01.html
@@ -56,8 +56,7 @@
</tr>
<tr>
<td>CVE-2017-13294</td>
- <td><a href="https://android.googlesource.com/platform/packages/apps/Email/+/c3e0aba2a604ce7c3807d65df1e6a2b848287019">A-71814449</a>
- [<a href="https://android.googlesource.com/platform/packages/apps/UnifiedEmail/+/e00598532bbfc8618b7c051cbf6bd15491f61f27">2</a>]</td>
+ <td><a href="https://android.googlesource.com/platform/packages/apps/Email/+/c3e0aba2a604ce7c3807d65df1e6a2b848287019">A-71814449</a> [<a href="https://android.googlesource.com/platform/packages/apps/UnifiedEmail/+/e00598532bbfc8618b7c051cbf6bd15491f61f27">2</a>]</td>
<td>ID</td>
<td>中</td>
<td>6.0、6.0.1、7.0、7.1.1、7.1.2、8.0、8.1</td>
@@ -160,8 +159,7 @@
</tr>
<tr>
<td>CVE-2017-13301</td>
- <td><a href="https://android.googlesource.com/platform/frameworks/base/+/384689934d293acf532e3fea3e72ef78df4f2d1e">A-66498711</a>
- [<a href="https://android.googlesource.com/platform/frameworks/base/+/d52b215f82e464705373d794748325298f0a1f9a">2</a>]</td>
+ <td><a href="https://android.googlesource.com/platform/frameworks/base/+/384689934d293acf532e3fea3e72ef78df4f2d1e">A-66498711</a> [<a href="https://android.googlesource.com/platform/frameworks/base/+/d52b215f82e464705373d794748325298f0a1f9a">2</a>]</td>
<td>DoS</td>
<td>中</td>
<td>8.0</td>
@@ -192,8 +190,7 @@
</tr>
<tr>
<td>CVE-2017-13303</td>
- <td>A-71359108<a href="#asterisk">*</a><br />
- B-V2018010501</td>
+ <td>A-71359108<a href="#asterisk">*</a><br />B-V2018010501</td>
<td>ID</td>
<td>中</td>
<td>Bcmdhd 驱动程序</td>
@@ -254,8 +251,7 @@
<tr>
<td>CVE-2017-17712</td>
<td>A-71500434<br />
- <a href="http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=8f659a03a0ba9289b9aeb9b4470e6fb263d6f483">
-上游内核</a></td>
+ <a href="http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=8f659a03a0ba9289b9aeb9b4470e6fb263d6f483">上游内核</a></td>
<td>EoP</td>
<td>中</td>
<td>net ipv4</td>
@@ -263,8 +259,7 @@
<tr>
<td>CVE-2017-15115</td>
<td>A-70217214<br />
- <a href="http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=df80cd9b28b9ebaa284a41df611dbf3a2d05ca74">
-上游内核</a></td>
+ <a href="http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=df80cd9b28b9ebaa284a41df611dbf3a2d05ca74">上游内核</a></td>
<td>EoP</td>
<td>中</td>
<td>SCTP</td>
@@ -289,50 +284,42 @@
<tr>
<td>CVE-2018-3598</td>
<td>A-71501698<br />
- <a href="https://source.codeaurora.org/quic/la/kernel/msm-3.18/commit/?id=bfd8ffc65e6e82de2adceba58bd67137fb3b2024">
-QC-CR#1097390</a></td>
+ <a href="https://source.codeaurora.org/quic/la/kernel/msm-3.18/commit/?id=bfd8ffc65e6e82de2adceba58bd67137fb3b2024">QC-CR#1097390</a></td>
<td>ID</td>
<td>中</td>
<td>camera_v2 驱动程序</td>
</tr>
<tr>
<td>CVE-2018-5826</td>
- <td>A-69128800<a href="#asterisk">*</a><br />
- QC-CR#2157283</td>
+ <td>A-69128800<a href="#asterisk">*</a><br />QC-CR#2157283</td>
<td>ID</td>
<td>中</td>
<td>qcacld-3.0 硬盘驱动器</td>
</tr>
<tr>
<td>CVE-2017-15853</td>
- <td>A-65853393<a href="#asterisk">*</a><br />
- QC-CR#2116517<br />
- QC-CR#2125577</td>
+ <td>A-65853393<a href="#asterisk">*</a><br />QC-CR#2116517<br />QC-CR#2125577</td>
<td>ID</td>
<td>中</td>
<td>WLAN</td>
</tr>
<tr>
<td>CVE-2018-3584</td>
- <td>A-64610600<a href="#asterisk">*</a><br />
- QC-CR#2142046</td>
+ <td>A-64610600<a href="#asterisk">*</a><br />QC-CR#2142046</td>
<td>ID</td>
<td>中</td>
<td>rmnet_usb</td>
</tr>
<tr>
<td>CVE-2017-8269</td>
- <td>A-33967002<a href="#asterisk">*</a><br />
- QC-CR#2013145<br />
- QC-CR#2114278</td>
+ <td>A-33967002<a href="#asterisk">*</a><br />QC-CR#2013145<br />QC-CR#2114278</td>
<td>ID</td>
<td>中</td>
<td>IPA 驱动程序</td>
</tr>
<tr>
<td>CVE-2017-15837</td>
- <td>A-64403015<a href="#asterisk">*</a><br />
- QC-CR#2116387</td>
+ <td>A-64403015<a href="#asterisk">*</a><br />QC-CR#2116387</td>
<td>ID</td>
<td>中</td>
<td>NL80211 驱动程序</td>
@@ -340,8 +327,7 @@
<tr>
<td>CVE-2018-5823</td>
<td>A-72957335<br />
- <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=fc5bbedd4ab9fd5239be8618afe714d39dd8de49">
-QC-CR#2139436</a></td>
+ <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=fc5bbedd4ab9fd5239be8618afe714d39dd8de49">QC-CR#2139436</a></td>
<td>EoP</td>
<td>中</td>
<td>WLAN</td>
@@ -349,9 +335,7 @@
<tr>
<td>CVE-2018-5825</td>
<td>A-72957269<br />
- <a href="https://source.codeaurora.org/quic/la/kernel/msm-3.10/commit/?id=5ae227670444cf8ea7b8a8d98eab41404a03332f">QC-CR#2151146</a>
- [<a href="https://source.codeaurora.org/quic/la/kernel/msm-3.18/commit/?id=cf0f031ffbb6a8e08e517f653045c3f81d7f2663">2</a>]
- [<a href="https://source.codeaurora.org/quic/la/kernel/msm-3.18/commit/?id=09a34b7878a732187f9138900667d8abb2b1c39c">3</a>]</td>
+ <a href="https://source.codeaurora.org/quic/la/kernel/msm-3.10/commit/?id=5ae227670444cf8ea7b8a8d98eab41404a03332f">QC-CR#2151146</a> [<a href="https://source.codeaurora.org/quic/la/kernel/msm-3.18/commit/?id=cf0f031ffbb6a8e08e517f653045c3f81d7f2663">2</a>] [<a href="https://source.codeaurora.org/quic/la/kernel/msm-3.18/commit/?id=09a34b7878a732187f9138900667d8abb2b1c39c">3</a>]</td>
<td>EoP</td>
<td>中</td>
<td>IPA 驱动程序</td>
@@ -359,8 +343,7 @@
<tr>
<td>CVE-2018-5824</td>
<td>A-72957235<br />
- <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-2.0/commit/?id=b34f6f3afe229e32a32418f75889279f6e00d157">QC-CR#2149399</a>
- [<a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=d3a92a1656a3ee2fc44d4ff98614a4f5b70f1893">2</a>]</td>
+ <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-2.0/commit/?id=b34f6f3afe229e32a32418f75889279f6e00d157">QC-CR#2149399</a> [<a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=d3a92a1656a3ee2fc44d4ff98614a4f5b70f1893">2</a>]</td>
<td>EoP</td>
<td>中</td>
<td>WLAN</td>
@@ -368,8 +351,7 @@
<tr>
<td>CVE-2018-5827</td>
<td>A-72956920<br />
- <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=53e6d889ac29336ba212a0d4a987455a85736fa8">
-QC-CR#2161977</a></td>
+ <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=53e6d889ac29336ba212a0d4a987455a85736fa8">QC-CR#2161977</a></td>
<td>EoP</td>
<td>中</td>
<td>WLAN</td>
@@ -377,8 +359,7 @@
<tr>
<td>CVE-2018-5822</td>
<td>A-71501692<br />
- <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-2.0/commit/?id=edc42ce371b6831dc55a15bc2624175bd538aa37">
-QC-CR#2115221</a></td>
+ <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-2.0/commit/?id=edc42ce371b6831dc55a15bc2624175bd538aa37">QC-CR#2115221</a></td>
<td>EoP</td>
<td>中</td>
<td>QC WLAN</td>
@@ -386,8 +367,7 @@
<tr>
<td>CVE-2018-5821</td>
<td>A-71501687<br />
- <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-2.0/commit/?id=08ab943766abe845a8fae21689bae18dd74e9b20">
-QC-CR#2114363</a></td>
+ <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-2.0/commit/?id=08ab943766abe845a8fae21689bae18dd74e9b20">QC-CR#2114363</a></td>
<td>EoP</td>
<td>中</td>
<td>调制解调器驱动程序</td>
@@ -395,8 +375,7 @@
<tr>
<td>CVE-2018-5820</td>
<td>A-71501686<br />
- <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-2.0/commit/?id=a4a8475ea650c16705a3eaa011524820dc5ffd44">
-QC-CR#2114336</a></td>
+ <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-2.0/commit/?id=a4a8475ea650c16705a3eaa011524820dc5ffd44">QC-CR#2114336</a></td>
<td>EoP</td>
<td>中</td>
<td>调制解调器驱动程序</td>
@@ -404,16 +383,14 @@
<tr>
<td>CVE-2018-3599</td>
<td>A-71501666<br />
- <a href="https://source.codeaurora.org/quic/la/kernel/msm-3.18/commit/?id=cf2702c1a77d2a164a3be03597eff7e6fe5f967e">
-QC-CR#2047235</a></td>
+ <a href="https://source.codeaurora.org/quic/la/kernel/msm-3.18/commit/?id=cf2702c1a77d2a164a3be03597eff7e6fe5f967e">QC-CR#2047235</a></td>
<td>EoP</td>
<td>中</td>
<td>Qualcomm 核心服务</td>
</tr>
<tr>
<td>CVE-2018-3596</td>
- <td>A-35263529<a href="#asterisk">*</a><br />
- QC-CR#640898</td>
+ <td>A-35263529<a href="#asterisk">*</a><br />QC-CR#640898</td>
<td>EoP</td>
<td>中</td>
<td>WLAN</td>
@@ -421,8 +398,7 @@
<tr>
<td>CVE-2018-3568</td>
<td>A-72957136<br />
- <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=70cd30a5c1fdd02af19cf0e34c41842cce89a82d">
-QC-CR#2152824</a></td>
+ <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=70cd30a5c1fdd02af19cf0e34c41842cce89a82d">QC-CR#2152824</a></td>
<td>EoP</td>
<td>中</td>
<td>WLAN</td>
@@ -430,8 +406,7 @@
<tr>
<td>CVE-2018-3567</td>
<td>A-72956997<br />
- <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-2.0/commit/?id=f2627fca43bc4403a445c2b84481383ac0249364">QC-CR#2147119</a>
- [<a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=25c131e8a807894e04f95bdeb1cbd0376eda3bea">2</a>]</td>
+ <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-2.0/commit/?id=f2627fca43bc4403a445c2b84481383ac0249364">QC-CR#2147119</a> [<a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=25c131e8a807894e04f95bdeb1cbd0376eda3bea">2</a>]</td>
<td>EoP</td>
<td>中</td>
<td>WLAN</td>
@@ -439,8 +414,7 @@
<tr>
<td>CVE-2017-15855</td>
<td>A-72957336<br />
- <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=75c0ea8622bb07716d2a82247e6dd1597980f223">
-QC-CR#2149501</a></td>
+ <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=75c0ea8622bb07716d2a82247e6dd1597980f223">QC-CR#2149501</a></td>
<td>EoP</td>
<td>中</td>
<td>WLAN</td>
@@ -448,8 +422,7 @@
<tr>
<td>CVE-2018-5828</td>
<td>A-71501691<br />
- <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-2.0/commit/?id=6299a6bf166a60a47e9108ae2119027e787432d0">
-QC-CR#2115207</a></td>
+ <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-2.0/commit/?id=6299a6bf166a60a47e9108ae2119027e787432d0">QC-CR#2115207</a></td>
<td>EoP</td>
<td>中</td>
<td>QC WLAN</td>
@@ -457,8 +430,7 @@
<tr>
<td>CVE-2017-15836</td>
<td>A-71501693<br />
- <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=058e1eef2b1422bc0dd70f73832f1ac8a3dbe806">
-QC-CR#2119887</a></td>
+ <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=058e1eef2b1422bc0dd70f73832f1ac8a3dbe806">QC-CR#2119887</a></td>
<td>EoP</td>
<td>中</td>
<td>QC WLAN</td>
@@ -466,8 +438,7 @@
<tr>
<td>CVE-2017-14890</td>
<td>A-71501695<br />
- <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=234e14add09a1ba4a1b1d81d474ac3978dc94fd6">
-QC-CR#2120751</a></td>
+ <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=234e14add09a1ba4a1b1d81d474ac3978dc94fd6">QC-CR#2120751</a></td>
<td>EoP</td>
<td>中</td>
<td>QC WLAN</td>
@@ -475,8 +446,7 @@
<tr>
<td>CVE-2017-14894</td>
<td>A-71501694<br />
- <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=dfca3d8173c1548a97e558cb8abd1ffd2483f8b7">
-QC-CR#2120424</a></td>
+ <a href="https://source.codeaurora.org/quic/la/platform/vendor/qcom-opensource/wlan/qcacld-3.0/commit/?id=dfca3d8173c1548a97e558cb8abd1ffd2483f8b7">QC-CR#2120424</a></td>
<td>EoP</td>
<td>中</td>
<td>QC WLAN</td>
@@ -484,9 +454,7 @@
<tr>
<td>CVE-2017-14880</td>
<td>A-68992477<br />
- <a href="https://source.codeaurora.org/quic/la/kernel/msm-3.18/commit/?id=cbf3702ae1c5e2cacd6f15a5eb7a799e2f1ed96f">
-QC-CR#2078734</a>
- [<a href="https://source.codeaurora.org/quic/la/kernel/msm-3.10/commit/?id=d72e444dce0b9d20fdcdc4daeb6227e3536eebf7">2</a>]</td>
+ <a href="https://source.codeaurora.org/quic/la/kernel/msm-3.18/commit/?id=cbf3702ae1c5e2cacd6f15a5eb7a799e2f1ed96f">QC-CR#2078734</a> [<a href="https://source.codeaurora.org/quic/la/kernel/msm-3.10/commit/?id=d72e444dce0b9d20fdcdc4daeb6227e3536eebf7">2</a>]</td>
<td>EoP</td>
<td>中</td>
<td>IPA WAN 驱动程序</td>
@@ -494,8 +462,7 @@
<tr>
<td>CVE-2017-11075</td>
<td>A-70237705<br />
- <a href="https://source.codeaurora.org/quic/la/kernel/msm-4.4/commit/?id=7a07165c62926e899b710e1fed31532f31797dd5">
-QC-CR#2098332</a></td>
+ <a href="https://source.codeaurora.org/quic/la/kernel/msm-4.4/commit/?id=7a07165c62926e899b710e1fed31532f31797dd5">QC-CR#2098332</a></td>
<td>EoP</td>
<td>中</td>
<td>音频 DSP 驱动程序</td>
@@ -521,8 +488,7 @@
<td>Pixel 2、Pixel 2 XL</td>
</tr>
<tr>
- <td>A-37681923<br />
- A-68215016</td>
+ <td>A-37681923<br />A-68215016</td>
<td>日志记录</td>
<td>改进异常检测指标</td>
<td>所有</td>
@@ -636,11 +602,8 @@
<td>Pixel、Pixel XL</td>
</tr>
<tr>
- <td>A-68150449<br />
- A-68059359<br />
- A-69797741<br />
- A-69378640<br />
- A-68824279</td>
+ <td>A-68150449<br />A-68059359<br />A-69797741<br />
+ A-69378640<br />A-68824279</td>
<td>稳定性</td>
<td>改进 Pixel 2 手机的 WLAN 稳定性</td>
<td>Pixel 2、Pixel 2 XL</td>
@@ -676,9 +639,7 @@
<td>所有</td>
</tr>
<tr>
- <td>A-68923696<br />
- A-68922470<br />
- A-68940490</td>
+ <td>A-68923696<br />A-68922470<br />A-68940490</td>
<td>认证</td>
<td>升级证书以确保持续为您提供服务。</td>
<td>Nexus 5X、Pixel、Pixel XL、Pixel 2、Pixel 2 XL</td>
@@ -702,13 +663,7 @@
<td>Pixel 2、Pixel 2 XL</td>
</tr>
<tr>
- <td>A-69017578<br />
- A-68138080<br />
- A-68205105<br />
- A-70731000<br />
- A-69574837<br />
- A-68474108<br />
- A-70406781</td>
+ <td>A-69017578<br />A-68138080<br />A-68205105<br />A-70731000<br />A-69574837<br />A-68474108<br />A-70406781</td>
<td>连接、性能</td>
<td>改进部分运营商网络的连接性和性能</td>
<td>Pixel、Pixel XL、Pixel 2、Pixel 2 XL</td>
@@ -732,16 +687,13 @@
<td>Pixel 2</td>
</tr>
<tr>
- <td>A-69238007<br />
- A-68202289<br />
- A-69334308</td>
+ <td>A-69238007<br />A-68202289<br />A-69334308</td>
<td>连接</td>
<td>调整 APN 设置</td>
<td>Nexus 5X、Pixel、Pixel XL、Pixel 2、Pixel 2 XL</td>
</tr>
<tr>
- <td>A-69261367<br />
- A-70512352</td>
+ <td>A-69261367<br />A-70512352</td>
<td>短信</td>
<td>改进部分运营商的彩信性能</td>
<td>Nexus 5X、Pixel、Pixel XL、Pixel 2、Pixel 2 XL</td>
@@ -771,8 +723,7 @@
<td>Pixel 2、Pixel 2 XL</td>
</tr>
<tr>
- <td>A-69848394<br />
- A-68275646</td>
+ <td>A-69848394<br />A-68275646</td>
<td>性能</td>
<td>改进免安装应用的性能</td>
<td>所有</td>
@@ -790,8 +741,7 @@
<td>Pixel 2、Pixel 2 XL</td>
</tr>
<tr>
- <td>A-70094083<br />
- A-70094701</td>
+ <td>A-70094083<br />A-70094701</td>
<td>电池</td>
<td>改进 Pixel 2 和 Pixel 2 XL 的电池性能</td>
<td>Pixel 2、Pixel 2 XL</td>
@@ -821,9 +771,7 @@
<td>Nexus 5X、Pixel、Pixel XL、Pixel 2、Pixel 2 XL</td>
</tr>
<tr>
- <td>A-70580873<br />
- A-70912923<br />
- A-71497259</td>
+ <td>A-70580873<br />A-70912923<br />A-71497259</td>
<td>连接</td>
<td>改进部分运营商的通话性能</td>
<td>Pixel、Pixel XL、Pixel 2、Pixel 2 XL</td>
@@ -859,8 +807,7 @@
<td>所有</td>
</tr>
<tr>
- <td>A-72797728<br />
- A-71599119</td>
+ <td>A-72797728<br />A-71599119</td>
<td>日志记录</td>
<td>改进内部问题排查工具</td>
<td>所有</td>
diff --git a/zh-cn/security/bulletin/pixel/2018-05-01.html b/zh-cn/security/bulletin/pixel/2018-05-01.html
index 903047f..87703d9 100644
--- a/zh-cn/security/bulletin/pixel/2018-05-01.html
+++ b/zh-cn/security/bulletin/pixel/2018-05-01.html
@@ -31,7 +31,7 @@
<p class="note">
<strong>注意</strong>：可在 <a href="https://developers.google.com/android/nexus/images">Google Developers 网站</a>上找到 Google 设备固件映像。
</p>
-<h2 id="announcements">通知</h2>
+<h2 id="announcements">通告</h2>
<p>除了 2018 年 5 月的 Android 安全公告中所述的安全漏洞外，Pixel 和 Nexus 设备中还包含针对下述安全漏洞的补丁程序。合作伙伴在至少一个月前就已收到关于这些问题的通知，并可以选择将针对这些问题的补丁程序纳入到其设备更新中。</p>
<h2 id="security-patches">安全补丁程序</h2>
<p>
diff --git a/zh-cn/security/overview/app-security.html b/zh-cn/security/overview/app-security.html
index e82025b..0c47655 100644
--- a/zh-cn/security/overview/app-security.html
+++ b/zh-cn/security/overview/app-security.html
@@ -25,16 +25,16 @@
<p>Android 应用的主要构造块包括：</p>
<ul>
<li>
- <p><strong>AndroidManifest.xml</strong>：<a href="https://developer.android.com/guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a> 文件是一个控制文件，用于告知系统如何处理应用中的所有顶层组件（具体来说就是下面介绍的 Activity、服务、广播接收器和内容提供程序）。该文件还用于指定需要哪些权限。</p>
+ <p><strong>AndroidManifest.xml</strong>：<a href="https://developer.android.com/guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a> 文件是一个控制文件，用于告知系统如何处理应用中的所有顶层组件（具体来说就是下面介绍的活动、服务、广播接收器和内容提供程序）。该文件还用于指定需要哪些权限。</p>
</li>
<li>
- <p><strong>Activity</strong>：<a href="https://developer.android.com/guide/topics/fundamentals/activities.html">Activity</a> 通常是指适用于面向用户的单个任务的代码。活动通常包括向用户显示界面，但并不一定会这样，有些活动就从不显示界面。通常情况下，应用的入口点是应用的其中一项活动。</p>
+ <p><strong>活动</strong>：<a href="https://developer.android.com/guide/topics/fundamentals/activities.html">活动</a>通常是指适用于面向用户的单个任务的代码。活动通常包括向用户显示界面，但并不一定会这样，有些活动就从不显示界面。通常情况下，应用的入口点是应用的其中一项活动。</p>
</li>
<li>
<p><strong>服务</strong>：<a href="https://developer.android.com/guide/topics/fundamentals/services.html">服务</a>是指在后台运行的一段代码。服务可以在自己的进程中运行，也可以在其他应用的进程中运行。其他组件会“绑定”到某项服务，并通过远程过程调用来调用该服务的方法。比如媒体播放器就是一项服务：即使用户退出媒体选择界面，也可能仍然希望音乐继续播放。即使界面已关闭，服务也可使音乐继续播放。</p>
</li>
<li>
- <p><strong>广播接收器</strong>：<a href="https://developer.android.com/reference/android/content/BroadcastReceiver.html">BroadcastReceiver</a> 是一种对象，该对象会在操作系统或其他应用发出称为 <a href="https://developer.android.com/reference/android/content/Intent.html">Intent</a> 的 IPC 机制时进行实例化。例如，应用可以注册一个接收器来接收电量不足的消息，并可以根据该信息改变自己的行为。</p>
+ <p><strong>广播接收器</strong>：<a href="https://developer.android.com/reference/android/content/BroadcastReceiver.html">广播接收器</a>是一种对象，该对象会在操作系统或其他应用发出称为 <a href="https://developer.android.com/reference/android/content/Intent.html">Intent</a> 的 IPC 机制时进行实例化。例如，应用可以注册一个接收器来接收电量不足的消息，并可以根据该信息改变自己的行为。</p>
</li>
</ul>
<h2 id="the-android-permission-model-accessing-protected-apis">Android 权限模式：访问受保护的 API</h2>
diff --git a/zh-cn/security/selinux/device-policy.html b/zh-cn/security/selinux/device-policy.html
index 9452db9..3ea8fde 100644
--- a/zh-cn/security/selinux/device-policy.html
+++ b/zh-cn/security/selinux/device-policy.html
@@ -20,7 +20,7 @@
limitations under the License.
-->
-<p>Android 开放源代码项目 (AOSP) 针对所有 Android 设备中常用的应用和服务提供了一个可靠实用的基本政策。AOSP 的贡献者会定期完善该政策。该核心政策应占设备上最终政策的 90-95%，而剩下的 5-10% 则为设备专用自定义政策。本文重点介绍了这些设备专用自定义政策、如何编写设备专用政策，以及在编写此类政策时要避免的一些陷阱。</p>
+<p>Android 开放源代码项目 (AOSP) 针对所有 Android 设备中常用的应用和服务提供了一个可靠实用的基本政策。AOSP 的贡献者会定期完善该政策。核心政策应占设备上最终政策的 90-95%，而剩下的 5-10% 则为设备专用自定义政策。本文重点介绍这些设备专用自定义政策、编写设备专用政策的方法，以及在编写此类政策时要避免的一些陷阱。</p>
<aside class="note"><strong>注意</strong>：要详细了解如何在 Android 8.0 中编写 SELinux 政策，请参阅 <a href="/security/selinux/images/SELinux_Treble.pdf">SELinux for Android 8.0</a>。</aside>
@@ -49,7 +49,7 @@
<h3 id="enforce_early">提早采用强制模式</h3>
-<p>在强制模式下，拒绝事件会被记录下来，并且会被强制执行。最佳做法是尽早使您的设备进入强制模式。如果花时间等待创建和强制执行设备专用政策，通常会导致有问题的产品和糟糕的用户体验。在实际使用过程中，要提前足够长的时间开始参与 <a href="https://en.wikipedia.org/wiki/Eating_your_own_dog_food">dogfooding</a>，确保对功能进行全面测试。提早开始有助于确保安全问题能够在相关人员做出设计决策时被考虑在内。相反，仅根据观察到的拒绝事件来授予权限是一种不安全的做法。可以利用这段时间对设备进行安全审核，并针对不应被允许的行为提出错误。</p>
+<p>在强制模式下，拒绝事件会被记录下来，并且会被强制执行。最佳做法是尽早使您的设备进入强制模式。如果花时间等待创建和强制执行设备专用政策，通常会导致有问题的产品和糟糕的用户体验。要提前足够长的时间开始参与 <a href="https://en.wikipedia.org/wiki/Eating_your_own_dog_food">dogfooding</a>，确保对实际使用中涉及的功能进行全面测试。提早开始有助于确保安全问题能够在相关人员做出设计决策时被考虑在内。相反，仅根据观察到的拒绝事件来授予权限是一种不安全的做法。可以利用这段时间对设备进行安全审核，并针对不应被允许的行为提出错误。</p>
<h3 id="remove_or_delete_existing_policy">移除或删除现有政策</h3>
@@ -165,7 +165,7 @@
<h3 id="policy_size_explosion">政策规模扩张</h3>
-<p><a href="http://arxiv.org/abs/1510.05497">在 Wild 中描述 SEAndroid 政策</a>中介绍了一个令人关注的设备政策自定义发展趋势。设备专用政策应占设备上运行的总体政策的 5-10%。如果自定义政策所占的比例超过 20%，则几乎肯定会包含超特权域和 Dead 政策。</p>
+<p><a href="http://arxiv.org/abs/1510.05497">在 Wild 中描述 SEAndroid 政策</a>中介绍了一个令人关注的设备政策自定义发展趋势。设备专用政策应占设备上运行的所有政策的 5-10%。如果自定义政策所占的比例超过 20%，则几乎肯定会包含超特权域和 Dead 政策。</p>
<p>过大的政策：</p>
diff --git a/zh-tw/security/bulletin/pixel/2018-06-01.html b/zh-tw/security/bulletin/pixel/2018-06-01.html
index 2735ff0..1d14c04 100644
--- a/zh-tw/security/bulletin/pixel/2018-06-01.html
+++ b/zh-tw/security/bulletin/pixel/2018-06-01.html
@@ -746,7 +746,7 @@
<tr>
<td>A-77458860</td>
<td>UI</td>
- <td>IMEI SV 格式正確顯示為數字 </td>
+ <td>IMEI SV 格式正確顯示為數字</td>
<td>Pixel、Pixel XL、Pixel 2、Pixel 2 XL</td>
</tr>
<tr>
@@ -848,7 +848,7 @@
<strong>4.「參考資料」<em></em>欄中 Android 錯誤 ID 旁邊的星號 (*) 代表什麼意義？</strong>
</p>
<p>
-在「參考資料」<em></em>欄中 Android 錯誤 ID 旁邊標上星號 (*) 代表該問題並未公開，相關的更新通常是直接整合在最新的 Pixel/Nexus 裝置專用驅動程式的安裝檔中。您可以前往 <a href="https://developers.google.com/android/nexus/drivers">Google Developers 網站</a>下載這些驅動程式。
+在「參考資料」<em></em>欄中的 Android 錯誤 ID 旁邊標上星號 (*) 代表該問題並未公開，相關的更新通常是直接整合在最新的 Pixel/Nexus 裝置專用驅動程式的安裝檔中。您可以前往 <a href="https://developers.google.com/android/nexus/drivers">Google Developers 網站</a>下載這些驅動程式。
</p>
<p>
<strong>5. 為什麼安全性漏洞會分別刊載在這份安全性公告和 Android 安全性公告？</strong>
