diff options
| author | Android Partner Docs <noreply@android.com> | 2017-08-14 19:56:10 +0000 |
|---|---|---|
| committer | android-build-merger <android-build-merger@google.com> | 2017-08-14 19:56:10 +0000 |
| commit | 04426e67ca3ee557a0083f9b3c6ba789021bd7a0 (patch) | |
| tree | 91c9ebee2d9b6c14b0ec5dd8b0dc2afa2f1afe8a | |
| parent | 8b3ca300c359ba2124c2794b0be9e938f22adc19 (diff) | |
| parent | 1d024fdd31c0f58ba53886a60b1c4219d7ab13e7 (diff) | |
| download | source.android.com-04426e67ca3ee557a0083f9b3c6ba789021bd7a0.tar.gz | |
Merge "Docs: Changes to source.android.com"
am: 1d024fdd31
Change-Id: Ibb2838482bff71b5bb761d4f28c211313c1b101a
63 files changed, 6625 insertions, 171 deletions
diff --git a/en/_index.yaml b/en/_index.yaml index d9ff3100..61e8df7c 100644 --- a/en/_index.yaml +++ b/en/_index.yaml @@ -60,6 +60,14 @@ landing_page: image_path: /images/android_stack.png - heading: News items: + - heading: August Android Security Bulletin + description: > + The August 2017 Android Security Bulletin has been published along with + links to associated fixes and new build numbers to support the August + Android security release. + buttons: + - label: August 8th, 2017 + path: /security/bulletin/2017-08-01 - heading: A/B Update Enhancements description: > A/B updates have been improved to stream updates in order to minimize @@ -74,13 +82,6 @@ landing_page: buttons: - label: August 1st, 2017 path: /devices/tv/customize-tv-app - - heading: Neonkey SensorHub - description: > - To develop ContextHub features that use new sensors or LEDs, you can use - Neonkey SensorHub connected to a HiKey or HiKey960 development board. - buttons: - - label: July 27th, 2017 - path: /source/devices#neonkey - classname: devsite-landing-row-100 tf-row-centered items: - buttons: diff --git a/en/compatibility/cts/downloads.html b/en/compatibility/cts/downloads.html index 466bb6ce..ac3b661f 100644 --- a/en/compatibility/cts/downloads.html +++ b/en/compatibility/cts/downloads.html @@ -31,77 +31,77 @@ R<number> in the link name.</p> <h2 id="android-71">Android 7.1</h2> <p>Android 7.1 is the release of the development milestone code-named Nougat-MR1. The source code for the following tests can be synced with the -'android-cts-7.1_r7' tag in the open-source tree.</p> +'android-cts-7.1_r8' tag in the open-source tree.</p> <ul> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-7.1_r7-linux_x86-arm.zip">Android -7.1 R7 Compatibility Test Suite (CTS) - ARM</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-7.1_r8-linux_x86-arm.zip">Android +7.1 R8 Compatibility Test Suite (CTS) - ARM</a></li> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-7.1_r7-linux_x86-x86.zip">Android -7.1 R7 Compatibility Test Suite (CTS) - x86</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-7.1_r8-linux_x86-x86.zip">Android +7.1 R8 Compatibility Test Suite (CTS) - x86</a></li> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-verifier-7.1_r7-linux_x86-arm.zip">Android -7.1 R7 CTS Verifier - ARM</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-verifier-7.1_r8-linux_x86-arm.zip">Android +7.1 R8 CTS Verifier - ARM</a></li> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-verifier-7.1_r7-linux_x86-x86.zip">Android -7.1 R7 CTS Verifier - x86</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-verifier-7.1_r8-linux_x86-x86.zip">Android +7.1 R8 CTS Verifier - x86</a></li> </ul> <h2 id="android-70">Android 7.0</h2> <p>Android 7.0 is the release of the development milestone code-named Nougat. The source code for the following tests can be synced with the -'android-cts-7.0_r11' tag in the open-source tree.</p> +'android-cts-7.0_r12' tag in the open-source tree.</p> <ul> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-7.0_r11-linux_x86-arm.zip">Android -7.0 R11 Compatibility Test Suite (CTS) - ARM</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-7.0_r12-linux_x86-arm.zip">Android +7.0 R12 Compatibility Test Suite (CTS) - ARM</a></li> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-7.0_r11-linux_x86-x86.zip">Android -7.0 R11 Compatibility Test Suite (CTS) - x86</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-7.0_r12-linux_x86-x86.zip">Android +7.0 R12 Compatibility Test Suite (CTS) - x86</a></li> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-verifier-7.0_r11-linux_x86-arm.zip">Android -7.0 R11 CTS Verifier - ARM</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-verifier-7.0_r12-linux_x86-arm.zip">Android +7.0 R12 CTS Verifier - ARM</a></li> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-verifier-7.0_r11-linux_x86-x86.zip">Android -7.0 R11 CTS Verifier - x86</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-verifier-7.0_r12-linux_x86-x86.zip">Android +7.0 R12 CTS Verifier - x86</a></li> </ul> <h2 id="android-60">Android 6.0</h2> <p>Android 6.0 is the release of the development milestone code-named Marshmallow. The source code for the following tests can be synced with the -'android-cts-6.0_r20' tag in the open-source tree.</p> +'android-cts-6.0_r21' tag in the open-source tree.</p> <ul> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-6.0_r20-linux_x86-arm.zip">Android -6.0 R20 Compatibility Test Suite (CTS) - ARM</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-6.0_r21-linux_x86-arm.zip">Android +6.0 R21 Compatibility Test Suite (CTS) - ARM</a></li> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-6.0_r20-linux_x86-x86.zip">Android -6.0 R20 Compatibility Test Suite (CTS) - x86</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-6.0_r21-linux_x86-x86.zip">Android +6.0 R21 Compatibility Test Suite (CTS) - x86</a></li> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-verifier-6.0_r20-linux_x86-arm.zip">Android -6.0 R20 CTS Verifier - ARM</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-verifier-6.0_r21-linux_x86-arm.zip">Android +6.0 R21 CTS Verifier - ARM</a></li> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-verifier-6.0_r20-linux_x86-x86.zip">Android -6.0 R20 CTS Verifier - x86</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-verifier-6.0_r21-linux_x86-x86.zip">Android +6.0 R21 CTS Verifier - x86</a></li> </ul> <h2 id="android-51">Android 5.1</h2> <p>Android 5.1 is the release of the development milestone code-named Lollipop-MR1. The source code for the following tests can be synced with the -'android-cts-5.1_r21' tag in the open source tree.</p> +'android-cts-5.1_r22' tag in the open source tree.</p> <ul> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-5.1_r21-linux_x86-arm.zip">Android -5.1 R21 Compatibility Test Suite (CTS) - ARM</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-5.1_r22-linux_x86-arm.zip">Android +5.1 R22 Compatibility Test Suite (CTS) - ARM</a></li> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-5.1_r21-linux_x86-x86.zip">Android -5.1 R21 Compatibility Test Suite (CTS) - x86</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-5.1_r22-linux_x86-x86.zip">Android +5.1 R22 Compatibility Test Suite (CTS) - x86</a></li> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-verifier-5.1_r21-linux_x86-arm.zip">Android -5.1 R21 CTS Verifier - ARM</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-verifier-5.1_r22-linux_x86-arm.zip">Android +5.1 R22 CTS Verifier - ARM</a></li> <li><a -href="https://dl.google.com/dl/android/cts/android-cts-verifier-5.1_r21-linux_x86-x86.zip">Android -5.1 R21 CTS Verifier - x86</a></li> +href="https://dl.google.com/dl/android/cts/android-cts-verifier-5.1_r22-linux_x86-x86.zip">Android +5.1 R22 CTS Verifier - x86</a></li> </ul> <h2 id="android-50">Android 5.0</h2> diff --git a/en/devices/_toc-interfaces.yaml b/en/devices/_toc-interfaces.yaml index 388219bc..fc1d43a6 100644 --- a/en/devices/_toc-interfaces.yaml +++ b/en/devices/_toc-interfaces.yaml @@ -12,9 +12,9 @@ toc: - title: Kernel section: - title: Configuration - path: /devices/tech/config/kernel + path: /devices/architecture/kernel/config - title: Network Tests - path: /devices/tech/config/kernel_network_tests + path: /devices/architecture/kernel/network_tests - title: Audio section: - title: Overview @@ -119,6 +119,8 @@ toc: 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 diff --git a/en/devices/_toc-tech.yaml b/en/devices/_toc-tech.yaml index f2e27d7a..da603b20 100644 --- a/en/devices/_toc-tech.yaml +++ b/en/devices/_toc-tech.yaml @@ -25,16 +25,10 @@ toc: path: /devices/tech/config/ - title: Carrier Customization path: /devices/tech/config/carrier - - title: Connectivity Tests - path: /devices/tech/config/connect_tests - title: File DAC Configuration path: /devices/tech/config/filesystem - - title: Low RAM - path: /devices/tech/config/low-ram - title: Namespaces for Libraries path: /devices/tech/config/namespaces_libraries - - title: OpenGLRenderer - path: /devices/tech/config/renderer - title: Runtime Permissions path: /devices/tech/config/runtime_perms - title: UICC @@ -55,6 +49,8 @@ toc: path: /devices/tech/connect/emergency-affordance - title: Host Card Emulation of FeliCa path: /devices/tech/connect/felica + - title: Network Connectivity Tests + path: /devices/tech/connect/connect_tests - title: Radio Interface Layer (RIL) path: /devices/tech/connect/ril - title: Data Usage @@ -95,16 +91,10 @@ toc: path: /devices/tech/debug/jank_jitter - title: AddressSanitizer path: /devices/tech/debug/asan - - title: Dumpsys - path: /devices/tech/debug/dumpsys - title: Using GDB path: /devices/tech/debug/gdb - title: Native Memory Use path: /devices/tech/debug/native-memory - - title: Network Use - path: /devices/tech/debug/netstats - - title: RAM Use - path: /devices/tech/debug/procstats - title: Strace path: /devices/tech/debug/strace - title: Valgrind @@ -129,7 +119,7 @@ toc: path: /devices/tech/admin/testing-provision - title: Testing Device Administration path: /devices/tech/admin/testing-setup -- title: Display Settings +- title: Display section: - title: Overview path: /devices/tech/display/ @@ -167,6 +157,12 @@ toc: path: /devices/tech/ota/sign_builds - title: A/B System Updates path: /devices/tech/ota/ab_updates +- title: Performance + section: + - title: Overview + path: /devices/tech/perf/ + - title: Low RAM + path: /devices/tech/perf/low-ram - title: Power section: - title: Overview @@ -183,6 +179,10 @@ toc: path: /devices/tech/power/values - title: Battery Use path: /devices/tech/power/batterystats +- title: Settings Menu + section: + - title: Overview + path: /devices/tech/settings/ - title: Testing Infrastructure section: - title: Overview diff --git a/en/devices/tech/config/kernel.html b/en/devices/architecture/kernel/config.html index 14d2ee17..14d2ee17 100644 --- a/en/devices/tech/config/kernel.html +++ b/en/devices/architecture/kernel/config.html diff --git a/en/devices/tech/config/kernel_network_tests.html b/en/devices/architecture/kernel/network_tests.html index bc437ad2..bc437ad2 100644 --- a/en/devices/tech/config/kernel_network_tests.html +++ b/en/devices/architecture/kernel/network_tests.html diff --git a/en/devices/tech/config/renderer.html b/en/devices/graphics/renderer.html index 7ee28f10..7ee28f10 100644 --- a/en/devices/tech/config/renderer.html +++ b/en/devices/graphics/renderer.html diff --git a/en/devices/tech/config/connect_tests.html b/en/devices/tech/connect/connect_tests.html index a7c06a83..a7c06a83 100644 --- a/en/devices/tech/config/connect_tests.html +++ b/en/devices/tech/connect/connect_tests.html diff --git a/en/devices/tech/ota/ab_updates.html b/en/devices/tech/ota/ab_updates.html index fee00bc2..871d8f63 100644 --- a/en/devices/tech/ota/ab_updates.html +++ b/en/devices/tech/ota/ab_updates.html @@ -31,10 +31,20 @@ repair and warranty centers. This approach is already explored successfully by other commercial-grade operating systems, such as <a href="https://www.chromium.org/chromium-os">ChromeOS</a>, and Android 8.0 - comes with the necessary platform changes to conduct streaming updates. Android - 7.0 and later support streaming updates with the correct version of <a - href="https://www.android.com/gms/">Google Mobile Services (GMS)</a> - installed.</p> + comes with the necessary platform changes to conduct streaming updates.</p> + +<p class="note"><strong>Note:</strong> Android 7.1, in which A/B updates were +introduced, requires the following patches to be cherrypicked before streaming +updates can be enabled. This is true whether using <a +href="https://www.android.com/gms/">Google Mobile Services (GMS)</a> or any +other update client.</p> + +<ul> + <li><a href="https://android-review.googlesource.com/333624">Allow to cancel a proxy resolution request</a></li> + <li><a href="https://android-review.googlesource.com/333625">Fix terminating a transfer while resolving proxies</a></li> + <li><a href="https://android-review.googlesource.com/333626">Add unittest for TerminateTrasnfer between ranges</a></li> + <li><a href="https://android-review.googlesource.com/333627">Cleanup the RetryTimeoutCallback()</a></li> +</ul> <p> Users don't always have enough space on <code>/data</code> to download the @@ -620,7 +630,7 @@ depended on what updates you wanted to apply. The worst case would be a cache partition as large as the system image. With A/B updates there's no need to stash blocks (because you're always writing to a partition that isn't currently used) and with streaming A/B there's no need to download the whole OTA package -before applying it (see "How do streaming A/B updates work?").</p> +before applying it.</p> <h3 id="fstab">Fstab</h3> diff --git a/en/devices/tech/perf/index.html b/en/devices/tech/perf/index.html new file mode 100644 index 00000000..6af0626c --- /dev/null +++ b/en/devices/tech/perf/index.html @@ -0,0 +1,30 @@ +<html devsite> + <head> + <title>Performance</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>Follow the instructions in this section to ensure your Android devices +minimize resource use and optimize performance.</p> + + </body> +</html> diff --git a/en/devices/tech/config/low-ram.html b/en/devices/tech/perf/low-ram.html index d1ca5b5e..d1ca5b5e 100644 --- a/en/devices/tech/config/low-ram.html +++ b/en/devices/tech/perf/low-ram.html diff --git a/en/devices/tech/settings/index.html b/en/devices/tech/settings/index.html new file mode 100644 index 00000000..0b3066d8 --- /dev/null +++ b/en/devices/tech/settings/index.html @@ -0,0 +1,30 @@ +<html devsite> + <head> + <title>Settings Menu</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 pages in this section explain how to employ the latest features +available in the Android Settings menu.</p> + + </body> +</html> diff --git a/en/security/bulletin/2017-05-01.html b/en/security/bulletin/2017-05-01.html index b3e9a684..1e5ce812 100644 --- a/en/security/bulletin/2017-05-01.html +++ b/en/security/bulletin/2017-05-01.html @@ -20,9 +20,9 @@ See the License for the specific language governing permissions and limitations under the License. --> - -<p><em>Published May 01, 2017 | Updated May 02, 2017</em></p> + +<p><em>Published May 01, 2017 | Updated August 10, 2017</em></p> <p>The Android Security Bulletin contains details of security vulnerabilities affecting Android devices. Alongside the bulletin, we have released a security @@ -512,7 +512,8 @@ lock screen.</p> <tr> <td>CVE-2017-0493</td> <td><a href="https://android.googlesource.com/platform/frameworks/base/+/e4cefbf4fce458489b5f1bebc79dfaf566bcc5d5">A-32793550</a> - [<a href="https://android.googlesource.com/platform/frameworks/base/+/f806d65e615b942c268a5f68d44bde9d55634972">2</a>]</td> + [<a href="https://android.googlesource.com/platform/frameworks/base/+/f806d65e615b942c268a5f68d44bde9d55634972">2</a>] + [<a href="https://android.googlesource.com/platform/frameworks/base/+/58552f814a03d978b4a6507f3c16f71964f9b28f">3</a>]</td> <td>Moderate</td> <td>All</td> <td>7.0, 7.1.1</td> @@ -3079,6 +3080,8 @@ belongs. These prefixes map as follows:</p> <ul> <li>May 01, 2017: Bulletin published.</li> <li>May 02, 2017: Bulletin revised to include AOSP links.</li> +<li>August 10, 2017: Bulletin revised to include additional AOSP link for +CVE-2017-0493.</li> </ul> </body> </html> diff --git a/en/security/bulletin/2017-08-01.html b/en/security/bulletin/2017-08-01.html index 51299a7c..2c4139d2 100644 --- a/en/security/bulletin/2017-08-01.html +++ b/en/security/bulletin/2017-08-01.html @@ -20,7 +20,7 @@ See the License for the specific language governing permissions and limitations under the License. --> -<p><em>Published August 7, 2017</em></p> +<p><em>Published August 7, 2017 | Updated August 8, 2017</em></p> <p>The Android Security Bulletin contains details of security vulnerabilities affecting Android devices. Security patch levels of August 05, 2017 or later @@ -30,9 +30,8 @@ and Nexus update schedule</a> to learn how to check a device's security patch level.</p> <p>Partners were notified of the issues described in the bulletin at least a month -ago. Source code patches for these issues will be released to the Android Open -Source Project (AOSP) repository in the next 48 hours. We will revise this -bulletin with the AOSP links when they are available. This bulletin also +ago. 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 security vulnerability in media @@ -129,7 +128,7 @@ context of a privileged process.</p> </tr> <tr> <td>CVE-2017-0712</td> - <td>A-37207928</td> + <td><a href="https://android.googlesource.com/platform/frameworks/opt/net/wifi/+/e8beda2579d277fb6b27f1792c4ed45c136ee15a">A-37207928</a></td> <td>EoP</td> <td>Moderate</td> <td>5.0.2, 5.1.1, 6.0, 6.0.1, 7.0, 7.1.1, 7.1.2</td> @@ -155,7 +154,8 @@ an unprivileged process.</p> </tr> <tr> <td>CVE-2017-0713</td> - <td>A-32096780</td> + <td><a href="https://android.googlesource.com/platform/external/sfntly/+/a642e3543a4ffdaaf1456768968ae05a205ed4f4">A-32096780</a> + [<a href="https://android.googlesource.com/platform/external/sfntly/+/fa6053736808e999483ca0a21fbe16a3075cf2c8">2</a>]</td> <td>RCE</td> <td>High</td> <td>4.4.4, 5.0.2, 5.1.1, 6.0, 6.0.1, 7.0, 7.1.1, 7.1.2</td> @@ -182,182 +182,184 @@ privileged process.</p> </tr> <tr> <td>CVE-2017-0714</td> - <td>A-36492637</td> + <td><a href="https://android.googlesource.com/platform/frameworks/av/+/26557d832fde349721500b47d51467c046794ae9">A-36492637</a></td> <td>RCE</td> <td>Critical</td> <td>4.4.4, 5.0.2, 5.1.1, 6.0, 6.0.1, 7.0, 7.1.1, 7.1.2</td> </tr> <tr> <td>CVE-2017-0715</td> - <td>A-36998372</td> + <td><a href="https://android.googlesource.com/platform/external/libavc/+/676c26e6a2ab3b75ab6e8fdd984547219fc1ceb5">A-36998372</a></td> <td>RCE</td> <td>Critical</td> <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2</td> </tr> <tr> <td>CVE-2017-0716</td> - <td>A-37203196</td> + <td><a href="https://android.googlesource.com/platform/external/libmpeg2/+/d5f52646974c29e6b7d51230b8ddae0c0a9430dc">A-37203196</a></td> <td>RCE</td> <td>Critical</td> <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2</td> </tr> <tr> <td>CVE-2017-0718</td> - <td>A-37273547</td> + <td><a href="https://android.googlesource.com/platform/external/libmpeg2/+/327496c59fb280273e23353061980dd72b07de1f">A-37273547</a></td> <td>RCE</td> <td>Critical</td> <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2</td> </tr> <tr> <td>CVE-2017-0719</td> - <td>A-37273673</td> + <td><a href="https://android.googlesource.com/platform/external/libmpeg2/+/f0afcf1943a1844e2a82ac3c5ab4d49427102cd1">A-37273673</a></td> <td>RCE</td> <td>Critical</td> <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2</td> </tr> <tr> <td>CVE-2017-0720</td> - <td>A-37430213</td> + <td><a href="https://android.googlesource.com/platform/external/libhevc/+/84732aaa4255955b8fefc39efee9b369181a6861">A-37430213</a></td> <td>RCE</td> <td>Critical</td> <td>5.0.2, 5.1.1, 6.0, 6.0.1, 7.0, 7.1.1, 7.1.2</td> </tr> <tr> <td>CVE-2017-0721</td> - <td>A-37561455</td> + <td><a href="https://android.googlesource.com/platform/external/libmpeg2/+/08a0d1ab6277770babbedab6ce7e7e2481869ad0">A-37561455</a></td> <td>RCE</td> <td>Critical</td> <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2</td> </tr> <tr> <td>CVE-2017-0722</td> - <td>A-37660827</td> + <td><a href="https://android.googlesource.com/platform/frameworks/av/+/26557d832fde349721500b47d51467c046794ae9">A-37660827</a></td> <td>RCE</td> <td>Critical</td> <td>4.4.4, 5.0.2, 5.1.1, 6.0, 6.0.1, 7.0, 7.1.1, 7.1.2</td> </tr> <tr> <td>CVE-2017-0723</td> - <td>A-37968755</td> + <td><a href="https://android.googlesource.com/platform/external/libavc/+/fe5ade4c86e2f5a86eab6c6593981d02f4c1710b">A-37968755</a></td> <td>RCE</td> <td>Critical</td> <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2</td> </tr> <tr> <td>CVE-2017-0745</td> - <td>A-37079296</td> + <td><a href="https://android.googlesource.com/platform/frameworks/av/+/b6ec3bbba36a3816a936f1e31984529b875b3618">A-37079296</a></td> <td>RCE</td> <td>Critical</td> <td>4.4.4, 5.0.2, 5.1.1, 6.0, 6.0.1, 7.0, 7.1.1, 7.1.2</td> </tr> <tr> <td>CVE-2017-0724</td> - <td>A-36819262</td> + <td><a href="https://android.googlesource.com/platform/external/libmpeg2/+/08a0d1ab6277770babbedab6ce7e7e2481869ad0">A-36819262</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-2017-0725</td> - <td>A-37627194</td> + <td><a href="https://android.googlesource.com/platform/external/skia/+/59372f5412036ce87285e91fd2dd53e37ff990e4">A-37627194</a></td> <td>DoS</td> <td>High</td> <td>7.0, 7.1.1, 7.1.2</td> </tr> <tr> <td>CVE-2017-0726</td> - <td>A-36389123</td> + <td><a href="https://android.googlesource.com/platform/frameworks/av/+/8995285da14e1303ae7357bf8162cbec13e65b68">A-36389123</a></td> <td>DoS</td> <td>High</td> <td>4.4.4, 5.0.2, 5.1.1, 6.0, 6.0.1, 7.0, 7.1.1, 7.1.2</td> </tr> <tr> <td>CVE-2017-0727</td> - <td>A-33004354</td> + <td><a href="https://android.googlesource.com/platform/frameworks/native/+/39dfabd43cbe57f92b771c0110a5c2d976b6c44f">A-33004354</a></td> <td>EoP</td> <td>High</td> <td>7.0, 7.1.1, 7.1.2</td> </tr> <tr> <td>CVE-2017-0728</td> - <td>A-37469795</td> + <td><a href="https://android.googlesource.com/platform/external/libhevc/+/314a0d038e6ae24bef80fff0b542965aed78ae96">A-37469795</a></td> <td>DoS</td> <td>High</td> <td>5.0.2, 5.1.1, 6.0, 6.0.1, 7.0, 7.1.1, 7.1.2</td> </tr> <tr> <td>CVE-2017-0729</td> - <td>A-37710346</td> + <td><a href="https://android.googlesource.com/platform/frameworks/av/+/96974782cd914120272a026ebc263dd38098f392">A-37710346</a></td> <td>EoP</td> <td>High</td> <td>5.0.2, 5.1.1, 6.0, 6.0.1, 7.0, 7.1.1, 7.1.2</td> </tr> <tr> <td>CVE-2017-0730</td> - <td>A-36279112</td> + <td><a href="https://android.googlesource.com/platform/external/libavc/+/efd28f6c36d40d0a8dd92f344e1d9a992b315c36">A-36279112</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-2017-0731</td> - <td>A-36075363</td> + <td><a href="https://android.googlesource.com/platform/frameworks/av/+/c10183960909f074a265c134cd4087785e7d26bf">A-36075363</a></td> <td>EoP</td> <td>High</td> <td>4.4.4, 5.0.2, 5.1.1, 6.0, 6.0.1, 7.0, 7.1.1, 7.1.2</td> </tr> <tr> <td>CVE-2017-0732</td> - <td>A-37504237</td> + <td><a href="https://android.googlesource.com/platform/frameworks/av/+/bf153fbedc2333b14e90826d22f08d10e832db29">A-37504237</a></td> <td>EoP</td> <td>High</td> <td>6.0, 6.0.1, 7.0, 7.1.1, 7.1.2</td> </tr> <tr> <td>CVE-2017-0733</td> - <td>A-38391487</td> + <td><a href="https://android.googlesource.com/platform/frameworks/base/+/6f357fd589e115a74aae25b1ac325af6121cdadf">A-38391487</a></td> <td>DoS</td> <td>High</td> <td>5.0.2, 5.1.1, 6.0, 6.0.1, 7.0, 7.1.1, 7.1.2</td> </tr> <tr> <td>CVE-2017-0734</td> - <td>A-38014992</td> + <td><a href="https://android.googlesource.com/platform/external/libavc/+/f6650b34ef27d6da8cdccd42e0f76fe756a9375b">A-38014992</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-2017-0735</td> - <td>A-38239864</td> + <td><a href="https://android.googlesource.com/platform/external/libavc/+/fe5ade4c86e2f5a86eab6c6593981d02f4c1710b">A-38239864</a> + [<a href="https://android.googlesource.com/platform/external/libavc/+/490bed0e7dce49296d50bb519348c6a87de8a8ef">2</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-2017-0736</td> - <td>A-38487564</td> + <td><a href="https://android.googlesource.com/platform/external/libavc/+/dfbbb54f14f83d45ad06a91aa76ed8260eb795d5">A-38487564</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-2017-0737</td> - <td>A-37563942</td> + <td><a href="https://android.googlesource.com/platform/frameworks/av/+/77e075ddd6d8cae33832add5225ee8f8c77908f0">A-37563942</a></td> <td>EoP</td> <td>High</td> <td>4.4.4, 5.0.2, 5.1.1, 6.0, 6.0.1, 7.0, 7.1.1, 7.1.2</td> </tr> <tr> <td>CVE-2017-0738</td> - <td>A-37563371</td> + <td><a href="https://android.googlesource.com/platform/frameworks/av/+/1d919d737b374b98b900c08c9d0c82fe250feb08">A-37563371</a> + [<a href="https://android.googlesource.com/platform/hardware/qcom/audio/+/234848dd6756c5d636f5a103e51636d60932983c">2</a>]</td> <td>ID</td> <td>Moderate</td> <td>4.4.4, 5.0.2, 5.1.1, 6.0, 6.0.1, 7.0, 7.1.1, 7.1.2</td> </tr> <tr> <td>CVE-2017-0739</td> - <td>A-37712181</td> + <td><a href="https://android.googlesource.com/platform/external/libhevc/+/e6e353a231f746743866d360b88ef8ced367bcb1">A-37712181</a></td> <td>ID</td> <td>Moderate</td> <td>5.0.2, 5.1.1, 6.0, 6.0.1, 7.0, 7.1.1, 7.1.2</td> @@ -818,14 +820,7 @@ Lab</a></td> </tr> <tr> <td>CVE-2017-0714, CVE-2017-0719, CVE-2017-0718, CVE-2017-0722, - CVE-2017-0725, CVE-2017-0720</td> - <td><a href="http://weibo.com/ele7enxxh">Zinuo Han</a> of Chengdu Security -Response Center, Qihoo 360 Technology Co. Ltd. and Ao Wang (<a -href="http://twitter.com/ArayzSegment">@ArayzSegment</a>) of <a -href="http://www.pwnzen.com/">Pangu Team</a></td> - </tr> - <tr> - <td>CVE-2017-0745</td> + CVE-2017-0725, CVE-2017-0720, CVE-2017-0745</td> <td><a href="http://weibo.com/ele7enxxh">Zinuo Han</a> of Chengdu Security Response Center, Qihoo 360 Technology Co. Ltd.</td> </tr> @@ -962,6 +957,11 @@ site</a>.</p> <td>August 7, 2017</td> <td>Bulletin published.</td> </tr> + <tr> + <td>1.1</td> + <td>August 8, 2017</td> + <td>Bulletin revised to include AOSP links and acknowledgements.</td> + </tr> </table> </body> </html> diff --git a/en/source/initializing.html b/en/source/initializing.html index 430bb4b0..eb8dce3d 100644 --- a/en/source/initializing.html +++ b/en/source/initializing.html @@ -57,10 +57,14 @@ OS below.</p> <h3 id="installing-the-jdk">Installing the JDK</h3> <p>The <code>master</code> branch of Android in the <a href="https://android.googlesource.com/">Android Open Source Project (AOSP)</a> -requires Java 8. On Ubuntu, use <a -href="http://openjdk.java.net/install/">OpenJDK</a>.</p> -<p>See <a href="requirements.html#jdk">JDK Requirements</a> for older -versions.</p> +comes with a prebuilt version of OpenJDK in +<code>platform/prebuilts/jdk/jdk8</code>. So no additional installation is +required.</p> + +<p>Older versions of Android require a separate installation of the JDK. On +Ubuntu, use <a href="http://openjdk.java.net/install/">OpenJDK</a>. See <a +href="requirements.html#jdk">JDK Requirements</a> for precise versions and the +sections below for instructions.</p> <h4 id="for-ubuntu-15-04">For Ubuntu >= 15.04</h4> <p>Run the following:</p> diff --git a/en/source/requirements.html b/en/source/requirements.html index e47d3e66..c2d8ba8c 100644 --- a/en/source/requirements.html +++ b/en/source/requirements.html @@ -92,11 +92,13 @@ <h3 id=jdk>Java Development Kit (JDK)</h3> -<p>Please note, since there are no available supported OpenJDK 8 packages for - Ubuntu 14.04, the Ubuntu 15.04 packages must be installed manually. See <a - href="initializing.html#for-ubuntu-14-04">JDK for Ubuntu LTS 14.04</a> for precise instructions.</p> +<p>Please note, the <code>master</code> branch of Android in AOSP comes with a +prebuilt version of OpenJDK, so no additional installation is required. Older +versions require a separate install. See <a +href="initializing.html#installing-the-jdk">Installing the JDK</a> for the +prebuilt path and installation instructions for older versions.</p> <ul> - <li>The master branch of Android in AOSP: Ubuntu - <a + <li>Android 7.0 (Nougat) - Android 8.0 (O release): Ubuntu - <a href="http://openjdk.java.net/install/">OpenJDK 8</a>, Mac OS - <a href="http://www.oracle.com/technetwork/java/javase/downloads/java-archive-javase8-2177648.html#jdk-8u45-oth-JPR">jdk 8u45 or newer</a></li> diff --git a/ja/security/bulletin/2017-07-01.html b/ja/security/bulletin/2017-07-01.html index 1a4cfe15..cba1123d 100644 --- a/ja/security/bulletin/2017-07-01.html +++ b/ja/security/bulletin/2017-07-01.html @@ -80,7 +80,7 @@ </tr> </tbody></table> <h3 id="framework">フレームワーク</h3> -<p>フレームワークに重大な脆弱性があるため、悪意のあるローカルアプリが特別に細工したファイルを使用して、ライブラリを使用するアプリの任意のコードを実行するおそれがあります。</p> +<p>フレームワークに重大な脆弱性があるため、悪意のあるローカルアプリが特別に細工したファイルを使用して、ライブラリを使用するアプリ内で任意のコードを実行するおそれがあります。</p> <table> <colgroup><col width="17%" /> @@ -1415,6 +1415,10 @@ <th>研究者</th> </tr> <tr> + <td>CVE-2017-8263</td> + <td>Google の Billy Lau</td> + </tr> + <tr> <td>CVE-2017-0711</td> <td>Alibaba Mobile Security Group の Chengming Yang、Baozeng Ding、Yang Song</td> </tr> @@ -1475,7 +1479,7 @@ <td>CSS Inc. の Timothy Becker</td> </tr> <tr> - <td>CVE-2017-0642、CVE-2017-0682、CVE-2017-0683、CVE-2017-0676、 + <td>CVE-2017-0682、CVE-2017-0683、CVE-2017-0676、 CVE-2017-0696、CVE-2017-0675、CVE-2017-0701、CVE-2017-0702、CVE-2017-0699</td> <td>Vasily Vasiliev</td> </tr> @@ -1483,7 +1487,7 @@ CVE-2017-0696、CVE-2017-0675、CVE-2017-0701、CVE-2017-0702、CVE-2017-0699</t <td>CVE-2017-0695、CVE-2017-0689、CVE-2017-0540、CVE-2017-0680、 CVE-2017-0679、CVE-2017-0685、CVE-2017-0686、CVE-2017-0693、CVE-2017-0674、 CVE-2017-0677</td> - <td><a href="//twitter.com/vysea">Trend Micro</a>、<a href="//blog.trendmicro.com/trendlabs-security-intelligence/category/mobile/">Mobile Threat Response Team</a> の V.E.O（<a href="//www.trendmicro.com">@VYSEa</a>）</td> + <td><a href="//www.trendmicro.com">Trend Micro</a>、<a href="//blog.trendmicro.com/trendlabs-security-intelligence/category/mobile/">Mobile Threat Response Team</a> の V.E.O（<a href="//twitter.com/vysea">@VYSEa</a>）</td> </tr> <tr> <td>CVE-2017-0708</td> @@ -1499,7 +1503,7 @@ CVE-2017-0677</td> </tr> <tr> <td>CVE-2017-8264、CVE-2017-0326、CVE-2017-0709</td> - <td><a href="mailto:computernik@gmail.com">C0RE Team</a> の Yuan-Tsung Lo（<a href="//c0reteam.org">computernik@gmail.com</a>）、Xuxian Jiang</td> + <td><a href="//c0reteam.org">C0RE Team</a> の Yuan-Tsung Lo（<a href="mailto:computernik@gmail.com">computernik@gmail.com</a>）、Xuxian Jiang</td> </tr> <tr> <td>CVE-2017-0704、CVE-2017-0669</td> @@ -1572,7 +1576,7 @@ CVE-2017-0677</td> </tr> </tbody></table> -<p><strong>4. 「参照」の列の項目はどういう意味ですか？<em></em></strong></p> +<p><strong>4. 「参照」列の項目はどういう意味ですか？<em></em></strong></p> <p>脆弱性の詳細の表で「参照」列に記載した項目には、その参照番号が属す組織を示す接頭辞を含めている場合があります。<em></em></p> @@ -1629,6 +1633,11 @@ CVE-2017-0677</td> <td>2017 年 7 月 6 日</td> <td>公開情報を改訂し AOSP リンクを追加</td> </tr> + <tr> + <td>1.2</td> + <td>2017 年 7 月 11 日</td> + <td>公開情報を改訂し、謝辞を更新</td> + </tr> </tbody></table> </body></html>
\ No newline at end of file diff --git a/ko/security/bulletin/2017-07-01.html b/ko/security/bulletin/2017-07-01.html index 2719b845..3e16d29d 100644 --- a/ko/security/bulletin/2017-07-01.html +++ b/ko/security/bulletin/2017-07-01.html @@ -40,21 +40,21 @@ <p>실제 고객이 새로 보고된 이러한 문제로 인해 악용당했다는 신고는 접수되지 않았습니다. Android 플랫폼의 보안을 개선하는 -<a href="/security/enhancements/index.html">Android 보안 플랫폼 보호</a> 및 -Google Play Protect 관련 세부정보를 -보려면 <a href="#mitigations">Android 및 Google Play Protect 완화</a> +<a href="#mitigations">Android 보안 플랫폼 보호</a> 및 Google Play Protect 관련 세부정보를 +보려면 <a href="/security/enhancements/index.html">Android 및 Google Play Protect 완화</a> 섹션을 참조하세요.</p> <p>모든 고객은 기기에서 이 업데이트를 수락하는 것이 좋습니다.</p> -<p class="note"><strong>참고:</strong> Google 기기의 최신 무선 업데이트(OTA) 및 펌웨어 이미지 관련 정보는 <a href="#google-device-updates">Google 기기 업데이트</a> 섹션을 참조하세요.</p> +<p class="note"><strong>참고:</strong> Google 기기의 최신 무선 업데이트(OTA) +및 펌웨어 이미지 관련 정보는 <a href="#google-device-updates">Google 기기 업데이트</a> 섹션을 +참조하세요.</p> <h2 id="announcements">공지사항</h2> <ul> <li>이 게시판에는 Android 파트너가 모든 Android 기기에서 유사하게 발생하는 취약성 문제의 일부를 더욱 빠르고 유연하게 해결하기 위한 - 두 가지 보안 패치 수준 문자열이 포함되어 있습니다. - 자세한 내용은 <a href="#common-questions-and-answers">일반적인 질문 및 답변</a>을 + 두 가지 보안 패치 수준 문자열이 포함되어 있습니다. 자세한 내용은 <a href="#common-questions-and-answers">일반적인 질문 및 답변</a>을 참조하세요. <ul> <li><strong>2017-07-01</strong>: 부분 보안 패치 수준 문자열입니다. 이 보안 패치 수준 문자열은 @@ -69,9 +69,7 @@ Google Play Protect 관련 세부정보를 </ul> <h2 id="mitigations">Android 및 Google Play Protect 완화</h2> -<p>다음은 <a href="//www.android.com/play-protect">Google Play Protect</a>와 같은 <a href="/security/enhancements/index.html">Android 보안 플랫폼</a> -및 서비스 보호 기능에서 제공하는 완화에 관한 -요약입니다. 이러한 기능을 통해 Android에서 보안 취약성이 +<p>다음은 <a href="/security/enhancements/index.html">Android 보안 플랫폼</a> 및 <a href="//www.android.com/play-protect">Google Play Protect</a>와 같은 서비스 보호 기능에서 제공하는 완화에 관한 요약입니다. 이러한 기능을 통해 Android에서 보안 취약성이 악용될 가능성을 줄입니다.</p> <ul> <li>Android 플랫폼 최신 버전의 향상된 기능으로 Android의 여러 문제를 @@ -1487,6 +1485,10 @@ AOSP 변경사항 목록과 같이 문제를 해결한 공개 변경사항을 <th>연구원</th> </tr> <tr> + <td>CVE-2017-8263</td> + <td>Google의 Billy Lau</td> + </tr> + <tr> <td>CVE-2017-0711</td> <td>Alibaba Mobile Security Group의 Chengming Yang, Baozeng Ding, Yang Song</td> @@ -1503,7 +1505,8 @@ Bauer</td> </tr> <tr> <td>CVE-2017-8265</td> - <td>Tencent KeenLab(<a href="//twitter.com/keen_lab?lang=en">@keen_lab</a>)의 + <td>Tencent +KeenLab(<a href="//twitter.com/keen_lab?lang=en">@keen_lab</a>)의 Di Shen(<a href="//twitter.com/returnsme?lang=en">@returnsme</a>)</td> </tr> <tr> @@ -1522,8 +1525,8 @@ Gengjia Chen(<a href="//twitter.com/chengjia4574">@chengjia4574</a>), <a href="/ </tr> <tr> <td>CVE-2017-0665, CVE-2017-0681</td> - <td><a href="//c0reteam.org">C0RE Team</a>의 -<a href="mailto:arnow117@gmail.com">Hanxiang Wen</a>, Mingjian Zhou(<a href="//twitter.com/Mingjian_Zhou">@Mingjian_Zhou</a>), Xuxian Jiang</td> + <td><a href="mailto:arnow117@gmail.com">C0RE Team</a>의 +<a href="//twitter.com/Mingjian_Zhou">Hanxiang Wen</a>, Mingjian Zhou(<a href="//c0reteam.org">@Mingjian_Zhou</a>), Xuxian Jiang</td> </tr> <tr> <td>CVE-2017-8268, CVE-2017-8261</td> @@ -1535,7 +1538,7 @@ Gengjia Chen(<a href="//twitter.com/chengjia4574">@chengjia4574</a>), <a href="/ </tr> <tr> <td>CVE-2017-0666, CVE-2017-0684</td> - <td><a href="//c0reteam.org">C0RE Team</a>의 Mingjian Zhou(<a href="//twitter.com/Mingjian_Zhou">@Mingjian_Zhou</a>), <a href="mailto:zc1991@mail.ustc.edu.cn">Chi Zhang</a>, Xuxian Jiang</td> + <td><a href="//twitter.com/Mingjian_Zhou">C0RE Team</a>의 Mingjian Zhou(<a href="mailto:zc1991@mail.ustc.edu.cn">@Mingjian_Zhou</a>), <a href="//c0reteam.org">Chi Zhang</a>, Xuxian Jiang</td> </tr> <tr> <td>CVE-2017-0697, CVE-2017-0670</td> @@ -1554,13 +1557,13 @@ Gengjia Chen(<a href="//twitter.com/chengjia4574">@chengjia4574</a>), <a href="/ <td>CSS Inc.의 Timothy Becker</td> </tr> <tr> - <td>CVE-2017-0642, CVE-2017-0682, CVE-2017-0683, CVE-2017-0676, -CVE-2017-0696,CVE-2017-0675, CVE-2017-0701, CVE-2017-0702, CVE-2017-0699</td> + <td>CVE-2017-0682, CVE-2017-0683, CVE-2017-0676, +CVE-2017-0696, CVE-2017-0675, CVE-2017-0701, CVE-2017-0702, CVE-2017-0699</td> <td>Vasily Vasiliev</td> </tr> <tr> <td>CVE-2017-0695, CVE-2017-0689, CVE-2017-0540, CVE-2017-0680, -CVE-2017-0679, CVE-2017-0685, CVE-2017-0686, CVE-2017-0693,CVE-2017-0674, +CVE-2017-0679, CVE-2017-0685, CVE-2017-0686, CVE-2017-0693, CVE-2017-0674, CVE-2017-0677</td> <td><a href="//twitter.com/vysea">Trend Micro</a> <a href="//blog.trendmicro.com/trendlabs-security-intelligence/category/mobile/">Mobile Threat Response Team</a>의 V.E.O(<a href="//www.trendmicro.com">@VYSEa</a>)</td> @@ -1598,7 +1601,7 @@ Chengdu Security Response Center의 <a href="//weibo.com/ele7enxxh">Zinuo Han</a <td>CVE-2017-0691, CVE-2017-0700</td> <td>Qihoo 360 Technology Co. Ltd., Chengdu Security Response Center의 <a href="//weibo.com/ele7enxxh">Zinuo Han</a> 및 -<a href="//www.pwnzen.com/">Pangu Team</a>의 Ao Wang(<a href="//twitter.com/ArayzSegment">@ArayzSegment</a>)</td> +<a href="//twitter.com/ArayzSegment">Pangu Team</a>의 Ao Wang(<a href="//www.pwnzen.com/">@ArayzSegment</a>)</td> </tr> </tbody></table> <h2 id="common-questions-and-answers">일반적인 질문 및 답변</h2> @@ -1731,6 +1734,11 @@ Chengdu Security Response Center의 <a href="//weibo.com/ele7enxxh">Zinuo Han</a <td>2017년 7월 6일</td> <td>게시판이 수정되어 AOSP 링크 포함됨</td> </tr> + <tr> + <td>1.2</td> + <td>2017년 7월 11일</td> + <td>게시판이 수정되어 감사의 말씀이 업데이트됨</td> + </tr> </tbody></table> </body></html>
\ No newline at end of file diff --git a/ru/security/bulletin/2017-07-01.html b/ru/security/bulletin/2017-07-01.html index 748ee719..5df832c2 100644 --- a/ru/security/bulletin/2017-07-01.html +++ b/ru/security/bulletin/2017-07-01.html @@ -31,7 +31,7 @@ <p>Мы рекомендуем всем пользователям установить перечисленные здесь обновления.</p> -<p class="note"><strong>Примечание.</strong> Информация о последних автоматических обновлениях (OTA) и об образах прошивок для устройств Google находится в разделе <a href="#google-device-updates">Обновления устройств Google</a>.</p> +<p class="note"><strong>Примечание.</strong> Информация о последних автоматических обновлениях (OTA) и образах прошивок для устройств Google находится в разделе <a href="#google-device-updates">Обновления устройств Google</a>.</p> <h2 id="announcements">Объявления</h2> <ul> @@ -44,7 +44,7 @@ </ul> <h2 id="mitigations">Предотвращение атак</h2> -<p>Ниже рассказывается, как <a href="/security/enhancements/index.html">платформа безопасности</a> и средства защиты сервисов, например <a href="//www.android.com/play-protect">Google Play Защита</a> позволяют снизить вероятность атак на Android.</p> +<p>Ниже рассказывается, как <a href="/security/enhancements/index.html">платформа безопасности</a> и средства защиты сервисов, например <a href="//www.android.com/play-protect">Google Play Защита</a>, позволяют снизить вероятность атак на Android.</p> <ul> <li>Использование многих уязвимостей затрудняется в новых версиях Android, поэтому мы рекомендуем всем пользователям своевременно обновлять систему.</li> <li>Команда, отвечающая за безопасность Android, активно отслеживает злоупотребления с помощью <a href="//www.android.com/play-protect">Google Play Защиты</a> и предупреждает пользователей об установке <a href="/security/reports/Google_Android_Security_PHA_classifications.pdf">потенциально опасных приложений</a>. Google Play Защита включена по умолчанию на всех устройствах с <a href="//www.android.com/gms">сервисами Google для мобильных устройств</a>. Она особенно важна, если пользователь устанавливает ПО из сторонних источников. @@ -234,7 +234,7 @@ </tr> <tr> <td>CVE-2017-0675</td> - <td><a href="https://android.googlesource.com/platform/external/libhevc/+/726108468dcfdabb833b8d55333de53cf6350aaa">A-34779227</a> + <td><a href="https://android.googlesource.com/platform/external/libhevc/+/726108468dcfdabb833b8d55333de53cf6350aaa"> A-34779227</a> [<a href="https://android.googlesource.com/platform/external/libhevc/+/4395fc2288e3f692765c73fce416e831fdaa5463">2</a>]</td> <td>УВК</td> <td>Критический</td> @@ -449,7 +449,7 @@ </tr> <tr> <td>CVE-2017-0701</td> - <td><a href="https://android.googlesource.com/platform/external/libgdx/+/85e94f5b67c1beb9402c4de82bd481a5202470de">A-36385715</a> + <td><a href="https://android.googlesource.com/platform/external/libgdx/+/85e94f5b67c1beb9402c4de82bd481a5202470de"> A-36385715</a> [<a href="https://android.googlesource.com/platform/external/libgdx/+/bd4c825d8fc5dd48f5c602e673ae210909b31fd0">2</a>]</td> <td>УВК</td> <td>Высокий</td> @@ -1416,6 +1416,10 @@ kernel</a></td> <th>Специалисты</th> </tr> <tr> + <td>CVE-2017-8263</td> + <td>Билли Лау из Google</td> + </tr> + <tr> <td>CVE-2017-0711</td> <td>Чэнмин Ян, Баоцзэн Дин и Ян Сун из Alibaba Mobile Security Group</td> </tr> @@ -1476,14 +1480,11 @@ kernel</a></td> <td>Тимоти Беккер из CSS Inc.</td> </tr> <tr> - <td>CVE-2017-0642, CVE-2017-0682, CVE-2017-0683, CVE-2017-0676, -CVE-2017-0696,CVE-2017-0675, CVE-2017-0701, CVE-2017-0702, CVE-2017-0699</td> + <td>CVE-2017-0682, CVE-2017-0683, CVE-2017-0676, CVE-2017-0696, CVE-2017-0675, CVE-2017-0701, CVE-2017-0702, CVE-2017-0699</td> <td>Василий Васильев</td> </tr> <tr> - <td>CVE-2017-0695, CVE-2017-0689, CVE-2017-0540, CVE-2017-0680, -CVE-2017-0679, CVE-2017-0685, CVE-2017-0686, CVE-2017-0693,CVE-2017-0674, -CVE-2017-0677</td> + <td>CVE-2017-0695, CVE-2017-0689, CVE-2017-0540, CVE-2017-0680, CVE-2017-0679, CVE-2017-0685, CVE-2017-0686, CVE-2017-0693, CVE-2017-0674, CVE-2017-0677</td> <td>V.E.O (<a href="//twitter.com/vysea">@VYSEa</a>) из <a href="//blog.trendmicro.com/trendlabs-security-intelligence/category/mobile/">команды по изучению угроз для мобильных устройств</a>, <a href="//www.trendmicro.com">Trend Micro</a></td> </tr> <tr> @@ -1631,6 +1632,11 @@ CVE-2017-0677</td> <td>6 июля 2017 г.</td> <td>Добавлены ссылки на AOSP.</td> </tr> + <tr> + <td>1.2</td> + <td>11 июля 2017 г.</td> + <td>Обновлен раздел благодарностей.</td> + </tr> </tbody></table> </body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/admin/implement.html b/zh-cn/devices/tech/admin/implement.html new file mode 100644 index 00000000..c04559b3 --- /dev/null +++ b/zh-cn/devices/tech/admin/implement.html @@ -0,0 +1,156 @@ +<html devsite><head> + <title>实现设备管理功能</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>本部分介绍如何启用和验证设备管理功能（为托管资料准备设备时所需）。同时，本部分还介绍了在企业环境中至关重要的设备所有者用户情境。</p> + +<p>除了 AOSP 代码之外，设备还需要以下组件来与托管资料配合使用。</p> + +<h2 id="requirements">常规要求</h2> +<p>要支持设备管理，设备必须符合以下常规要求。</p> + +<h3 id="HAL_values">热 HAL 值</h3> +<p>Android 7.0 及更高版本提供对 HardwarePropertiesManager API 的支持，该 API 是用于设备监控和运行状况报告的 API，可让应用查询设备硬件的状态。该 API 通过 <code>android.os.HardwarePropertiesManager</code> 提供，并通过 <code>HardwarePropertiesManagerService</code> 对硬件热 HAL (<code>hardware/libhardware/include/hardware/thermal.h</code>) 进行调用。该 API 是受保护的 API，也就是说，只有设备/资料所有者（即设备策略控制器 (DPC) 应用）和现有的 <code>VrListenerService</code> 可以调用它。</p> + +<p>要支持 HardwarePropertiesManager API，设备热 HAL 实现必须能够报告以下值：</p> + +<table> +<tbody><tr> +<th width="32%">值</th> +<th>报告范围</th> +<th>启用</th> +</tr> + +<tr> + <td>[CPU|GPU|电池|设备表面] 的温度</td> + <td>组件温度（以摄氏度为单位）</td> + <td>应用可以查看设备温度和组件限制/关闭温度</td> +</tr> + +<tr> + <td>CPU 处于活动状态的时间/总启用时间</td> + <td>时间（以毫秒为单位）</td> + <td>应用可以查看每个核心的 CPU 使用率</td> +</tr> + +<tr> + <td>风扇转速</td> + <td>每分钟转数 (RPM)</td> + <td>应用可以查看风扇转速</td> +</tr> + +</tbody></table> + +<p>当核心（或 GPU、电池、风扇）进入离线状态或接通/断开电源时，实现应正确处理报告值对应的情况。</p> + +<h3 id="low_ram">不允许低 RAM</h3> +<p>设备不得是低 RAM 设备，这意味着不得定义 <code>ro.config.low_ram</code>。当定义了 <code>low_ram</code> 标记时，框架会自动将用户数限制为 1。</p> + +<h3 id="uses-feature">Uses-feature</h3> +<p>设备必须定义以下 <code>uses-feature</code>：</p> + +<pre> +android.software.managed_users +android.software.device_admin +</pre> + +<p>要确认这些 <code>uses-feature</code> 值已在设备上进行了定义，请运行：<code>adb shell pm list features</code>。</p> + +<h3 id="required_apps">仅限基本应用</h3> +<p>默认情况下，在配置托管设备时，只能启用资料正确运行所必需的应用。原始设备制造商 (OEM) 必须通过修改以下文件确保托管资料或设备具有所有必需的应用：</p> + +<pre>vendor_required_apps_managed_profile.xml +vendor_required_apps_managed_device.xml +</pre> + +<p>Nexus 设备的示例：</p> + +<p><code>packages/apps/ManagedProvisioning/res/values/vendor_required_apps_managed_device.xml</code></p> + +<pre><resources> + <!-- A list of apps to be retained on the managed device --> + <string-array name="vendor_required_apps_managed_device"> + <item>com.android.vending</item> <!--Google Play --> + <item>com.google.android.gms</item> <!--Required by Play --> + <item>com.google.android.contacts</item> <!--Google or OEM Contacts--> + <item>com.google.android.googlequicksearchbox</item> <!--Google Launcher --> + <item>com.google.android.launcher</item> <!--Google Launcher or OEM Launcher --> + <item>com.google.android.dialer</item> <!--Google or OEM dialer to enable making phone calls --> + </string-array> +</resources> +</pre> + +<p><code> +packages/apps/ManagedProvisioning/res/values/vendor_required_apps_managed_profile.xml +</code></p> + +<pre> +<resources> + <!-- A list of apps to be retained in the managed profile. This includes any Google experience apps required. --> + <string-array name="vendor_required_apps_managed_profile"> + <item>com.android.vending</item> <!-- Google Play --> + <item>com.google.android.gms</item> <!-- Required by Play --> + <item>com.google.android.contacts</item> <!-- Google or OEM Contacts --> + </string-array> +</resources> +</pre> + +<h2 id="launcher">启动器要求</h2> + +<p>您必须更新启动器，以支持用来标记应用的图标徽章（在 AOSP 中提供，代表托管应用）以及其他徽章界面元素（如近期活动和通知）。如果您在 AOSP 中使用未经修改的 <a href="https://android.googlesource.com/platform/packages/apps/Launcher3/">launcher3</a>，那么您可能已经支持此徽章功能。</p> + +<h2 id="nfc">NFC 要求</h2> + +<p>NFC 设备必须在“开箱即用”的过程（即安装向导）中启用 NFC，并配置为接受托管配置 Intent：</p> + +<p><code>packages/apps/Nfc/res/values/provisioning.xml</code></p> +<pre><bool name="enable_nfc_provisioning">true</bool> +<item>application/com.android.managedprovisioning</item> +</pre> + +<h2 id="setup_wizard">设置要求</h2> + +<p>支持“开箱即用”过程（即安装向导）的设备应实现设备所有者配置功能。当“开箱即用”过程开始时，应检查其他进程（如设备所有者配置）是否已经完成用户设置，如果已完成，则应触发返回主屏幕的 Intent 完成设置。配置应用会捕获此 Intent，然后将控制权交给新设置的设备所有者。</p> + +<p>要满足设置要求，请将以下代码添加到设备设置的主要活动中：</p> + +<pre>@Override + protected void onStart() { + super.onStart(); + + // When returning to a setup wizard activity, check to see if another setup process + // has intervened and, if so, complete an orderly exit + boolean completed = Settings.Secure.getInt(getContentResolver(), + Settings.Secure.USER_SETUP_COMPLETE, 0) != 0; + if (completed) { + startActivity(new Intent(Intent.ACTION_MAIN, null) + .addCategory(Intent.CATEGORY_HOME) + .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK + | Intent.FLAG_ACTIVITY_CLEAR_TASK + | Intent.FLAG_ACTIVITY_RESET_TASK_IF_NEEDED)); + finish(); + } + + ... + } +</pre> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/admin/index.html b/zh-cn/devices/tech/admin/index.html new file mode 100644 index 00000000..d6862398 --- /dev/null +++ b/zh-cn/devices/tech/admin/index.html @@ -0,0 +1,43 @@ +<html devsite><head> + <title>设备管理</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 5.0 及更高版本且声明了 managed_users 功能的设备可在各公司信息技术 (IT) 部门的支持下用于<a href="http://www.android.com/work/">企业环境</a>中。只需引入<a href="multi-user.html">多用户</a>、<a href="managed-profiles.html">托管资料</a>和企业移动管理 (EMM) 应用，并完善默认<a href="/security/encryption/index.html">加密</a>、<a href="/security/verifiedboot/index.html">验证启动</a>和 <a href="/security/selinux/index.html">SELinux</a>，即可实现这一点。</p> + +<p>借助这些增强功能，用户或其 IT 部门便能创建可将公司雇主数据与个人用户信息分开的托管资料。请按照本网站该部分中的文档操作，以正确实施企业设备管理。</p> + +<h2 id="summary">摘要</h2> + +<p>请按照下述流程实施设备管理：</p> + +<ol> + <li>了解关键概念，例如<a href="multi-user.html">多用户</a>和<a href="managed-profiles.html">托管资料</a>。 + </li><li>通过自定义叠加文件<a href="implement.html">实施设备管理</a>。 + </li><li>借助 EMM 提供商和应用<a href="testing-setup.html">测试</a>和验证您的设备。 +</li></ol> + +<h2 id="supporting_documentation">支持文档</h2> + +<p><a href="http://developer.android.com/guide/topics/admin/device-admin.html">Device Administration API</a></p> + +<p><a href="https://developer.android.com/training/enterprise/index.html">构建 Apps for Work</a></p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/admin/multiuser-apps.html b/zh-cn/devices/tech/admin/multiuser-apps.html new file mode 100644 index 00000000..81e95cd1 --- /dev/null +++ b/zh-cn/devices/tech/admin/multiuser-apps.html @@ -0,0 +1,87 @@ +<html devsite><head> + <title>构建可感知多用户的应用</title> + <meta name="project_path" value="/_project.yaml"/> + <meta name="book_path" value="/_book.yaml"/> + </head> + <body> + <!-- + Copyright 2017 The Android Open Source Project + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + --> + +<p>对于支持<a href="multi-user.html">多用户</a>的设备，设备上的应用应能够感知不同的用户。</p> + +<p>某些应用需要将一些组件作为单例运行，并且可接受来自任意用户的请求。目前只有系统应用可以使用此功能。</p> + +<p>这类设备具有以下优势：</p> + +<ul> + <li>节约资源</li><li>判定各个用户之间的一个或多个共享资源</li><li>通过使用单个服务器连接减少网络开销</li></ul> + +<p>有关多用户权限流程的描述，请参见下图。</p> + +<p><img src="images/multi-user-perms.png" alt="Multiple users permissions flow"/> +</p><p class="img-caption"><strong>图 1</strong> 多用户权限</p> + +<h2 id="enabling_a_singleton_component">启用单例组件</h2> + +<p>要将应用识别为单例，请将 <code>android:singleUser=”true”</code> 添加至 Android 清单中的服务或提供程序。</p> + +<p>在仅以用户 0 的身份运行的进程中，系统会将该组件实例化。所有连接到该提供程序或服务的用户请求都将按指定路径发送到用户 0 的进程中。如果该组件是应用中的唯一组件，则只运行一个应用实例。</p> + +<p>软件包中的活动仍将在每个用户各自的进程中启动，并且 UID 处于相应用户的 UID 范围内（例如 1010034）。</p> + +<h2 id="interacting_with_users">与用户互动</h2> + +<h3 id="perms_required">设置权限</h3> + +<p>需要下列权限：</p> + +<pre> +INTERACT_ACROSS_USERS (signature|system) +INTERACT_ACROSS_USERS_FULL (signature) +</pre> + +<h3 id="apis">使用 API</h3> + +<p>使用下列 API，确保应用能够感知多个用户。</p> + +<ol> + <li>从传入的 Binder 调用中提取用户句柄：<ul> + <li> <code>int userHandle = UserHandle.getCallingUserId()</code> + </li></ul> + </li><li>使用受保护的全新 API 启动特定用户的服务、活动和广播：<ul> + <li><code>Context.startActivityAsUser(Intent, UserHandle)</code> + </li><li><code>Context.bindServiceAsUser(Intent, …, UserHandle)</code> + </li><li><code>Context.sendBroadcastAsUser(Intent, … , UserHandle)</code> + </li><li><code>Context.startServiceAsUser(Intent, …, UserHandle) +UserHandle</code> 可能是显式用户或是特殊句柄之一：<code>UserHandle.CURRENT</code> 或 <code>UserHandle.ALL</code>。<code>CURRENT</code> 表示当前处于前台的用户。如果您想向所有用户发送广播，则可以使用 <code>ALL</code>。 + </li></ul> + </li><li>要与您自己应用中的组件通信，请使用： +<code>(INTERACT_ACROSS_USERS)</code> +要与其他应用中的组件通信，请使用： +<code>(INTERACT_ACROSS_USERS_FULL)</code> + </li><li>您可能需要创建代理组件，这些代理组件在用户进程中运行，之后会访问用户 0 中的 <code>singleUser</code> 组件。 + </li><li>采用新的 <code>UserManager</code> 系统服务查询用户及其句柄：<ul> + <li><code>UserManager.getUsers()</code> + </li><li><code>UserManager.getUserInfo()</code> + </li><li><code>UserManager.supportsMultipleUsers()</code> + </li><li><code>UserManager.getUserSerialNumber(int userHandle)</code> - 与用户句柄对应的不可再循环数字。 + </li><li><code>UserManager.getUserHandle(int serialNumber)</code> + </li><li><code>UserManager.getUserProfiles() </code>- 返回用户本人个人资料和托管个人资料的集合（如有）。 + </li></ul> + </li><li>注册即可借助 ContentObserver、PackageMonitor 和 BroadcastReceiver 上的新 API 侦听特定或所有用户以及回调（可提供与回调发起用户相关的其他信息）。 +</li></ol> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/admin/testing-provision.html b/zh-cn/devices/tech/admin/testing-provision.html new file mode 100644 index 00000000..e7ac5b8c --- /dev/null +++ b/zh-cn/devices/tech/admin/testing-provision.html @@ -0,0 +1,211 @@ +<html devsite><head> + <title>测试设备配置</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 for Work (AfW) 自动化测试框架是一个用于验证 Android 设备的 AfW 兼容性的测试套件。该套件包括支持应用、测试用例、配置文件和一个基于 <code>cts-tradefed</code> 的测试运行程序 (<code>afw-test-tradefed</code>)。您应在完成<a href="/devices/tech/admin/provision.html">设备管理配置</a>后再设置并运行 AfW 自动化测试框架。</p> + +<p class="note"><strong>注意</strong>：AfW 自动化测试框架的编译和运行类似于 Android <a href="http://source.android.com/compatibility/cts/index.html">兼容性测试套件 (CTS)</a> 的编译和运行。</p> + +<h2 id="setup_env">设置开发环境</h2> +<p>AfW 自动化测试框架的开发环境类似于 Android 操作系统的开发环境。请按照<a href="/source/requirements.html">要求</a>中的步骤设置开发设备。</p> + +<h2 id="download_source">下载源代码</h2> +<p>按照<a href="/source/downloading.html">下载源代码</a>中的步骤下载 AfW 自动化测试框架源代码。AfW 自动化测试框架源代码位于 <code>./test/AfwTestHarness</code> 项目中。要下载的 AfW 自动化测试框架版本取决于分支名称（每个 Android 平台都有其单独的 AfW 自动化测试框架版本）。Android 7.0 的分支名称为 <code>afw-test-harness-nougat-dev</code>。要初始化该分支的 Repo 并下载源代码，请使用：</p> + +<pre> +$ mkdir WORKING_DIRECTORY +$ cd WORKING_DIRECTORY +$ git config --global user.name "Your Name" +$ git config --global user.email "you@example.com" +$ repo init -u https://android.googlesource.com/platform/manifest -b afw-test-harness-nougat-dev +$ repo sync -j24 +</pre> + +<p>要查看不同版本的源代码，请用相应标签指定分支。可用的分支包括：</p> + +<table> +<tbody><tr> +<th>分支名称</th><th>支持的 Android 平台</th></tr> +<tr> +<td>afw-test-harness-nougat-dev</td> +<td>Android 7.0</td> +</tr> +<tr> +<td>afw-test-harness-2.1</td> +<td>Android 7.0</td> +</tr> +<tr> +<td>afw-test-harness-marshmallow-dev</td> +<td>Android 6.0</td> +</tr> +<tr> +<td>afw-test-harness-1.5</td> +<td>Android 6.0</td> +</tr> +</tbody></table> + +<p>编译自动化测试框架所需的其他依赖项目也会随源代码一并下载。</p> + +<h3 id="view_studio">在 Android Studio 中查看</h3> +<p>要在 Android Studio 中查看和修改 AfW 源代码，请执行以下操作：</p> +<ol> +<li>运行以下命令：<pre> +$ make idegen +$ development/tools/idegen/idegen.sh +</pre> +</li> +<li>在 Android Studio 中打开 <code>android.ipr</code>。</li> +</ol> + +<p>AfW 自动化测试框架源代码位于 <code>test/AfwTestHarness</code> 中。</p> + +<h2 id="config_harness">配置 AfW 自动化测试框架</h2> +<p>通过配置 <code>test/AfwTestHarness/afw-test.props</code>，您可以自定义自动化测试框架。要成功运行自动化测试框架，请按照以下步骤操作：</p> +<ol> +<li>使用以下属性在 <code>afw-test.props</code> 中配置 WLAN 网络：<pre>wifi_ssid +wifi_password (optional) +wifi_security_type (optional, available options are: NONE, WEP or WPA) +</pre> +</li> +<li>从与 Test DPC（充当设备策略控制器）绑定的一个域中获取至少一个帐号。使用以下属性在 <code>afw-test.props</code> 中指定详细信息：<pre> +work_account_username +work_account_password +</pre> +<p>AfW 自动化测试框架使用 Test DPC 来测试配置流程。因此，帐号<strong>必须</strong>与 Test DPC 绑定才能运行自动化测试框架。</p> +</li> +</ol> + +<h2 id="build_harness">编译 AfW 自动化测试框架</h2> +<p>使用以下命令初始化编译配置：</p> +<pre> +$ source build/envsetup.sh +$ lunch +</pre> + +<p>选择设备类型，然后按 <strong>Enter</strong> 键。</p> + +<p>使用以下命令编译自动化测试框架：</p> +<pre>$ make afw-test-harness -j32</pre> +<p>该操作将创建一个目录 (<code>out/host/linux-x86/afw-th/android-cts</code>)，该目录包含运行自动化测试框架所需的全部二进制文件、配置文件和工具。该目录还会被压缩在一个文件 (<code>out/host/linux-x86/afw-th/android-afw-test-harness.zip</code>) 中以供分发。</p> + +<h2 id="run_harness">运行 AfW 自动化测试框架</h2> +<p>请按照以下步骤运行 AfW 自动化测试框架：</p> +<ol> +<li>使用以下命令，在您的编译环境中启动测试运行程序：<pre>$ afw-test-tradefed</pre> +该操作将启动 <code>cts-tf</code> 控制台，并从 <code>out/host/linux-x86/afw-th/android-cts</code> 中加载测试计划、测试用例和 <code>afw-test.props</code>。</li> +<li>使用以下命令，从 <code>android-afw-test-harness.zip</code> 的解压缩文件夹中启动测试运行程序：<pre>$ cts-tf > ./android‐cts/tools/afw-test‐tradefed</pre> +该操作将从 <code>android-cts</code> 目录中加载测试计划、测试用例和 <code>afw-test.props</code>。 +请确保 <code>./android‐cts/repository/testcases/afw-test.props</code> 拥有工作帐号和 WLAN 配置。</li> + +<li>运行测试计划。每个测试计划都是一个 XML 文件，其中包含从 <code>AfwTestHarness/tests</code> 测试包目录中获取的一组测试包。常见计划包括：<ul> +<li><code><strong>afw-userdebug-build</strong></code>。它包含需要使用 userdebug 版本的所有测试包。</li> +<li><code><strong>afw-user-build</strong></code>。该计划在 user 版本中运行，但要求对测试设备进行正确设置，其中包括完成初始设置以及启用 USB 调试。</li> +</ul> + +<br />要运行测试计划 <code>afw-userdebug-build</code>，请使用：<pre>$ cts-tf > run cts --plan afw-userdebug-build</pre>要查看所有测试计划，请使用命令 <code>list plans</code>。要查看计划定义，请参阅 <code>out/host/linux-x86/afw-th/android-cts/repository/plans</code>。 +<br /> +</li> +<li>运行测试包。要运行单个测试包，请使用：<pre>$ cts-tf > run cts --package com.android.afwtest.NfcProvisioning +</pre>要查看所有测试包，请使用命令 <code>list packages</code>。要查看更多选项，请使用命令 <code>run cts --help</code>。</li> +</ol> + +<h2 id="debug_harness">调试 AfW 自动化测试框架</h2> +<p>您可以通过运行 <code>afw-test-tradefed</code> 来启动 afw-test-tradefed 控制台 (<code>cts-tf</code>)，从而在该控制台中运行所有命令。</p> +<ul> + +<li>使用 <code>-l INFO</code> 或 <code>-l +DEBUG</code> 标记显示更多信息。示例：<pre>$ cts-tf > run cts ‐‐plan afw-userdebug-build -l DEBUG</pre></li> + +<li>在具有 <code>-s</code> 标记的设备上运行自动化测试框架。示例：<pre>$ cts-tf > run cts ‐‐plan afw-userdebug-build -l DEBUG -s device_sn</pre> +</li> + +<li>在具有 <code>--all-devices</code> 标记的所有连接设备上运行自动化测试框架。示例：<pre>$ cts-tf > run cts ‐‐plan afw-userdebug-build -l DEBUG --all-devices</pre> +</li> + +<li>使用 <code>list invocations</code> 或 <code>l i</code> 查看当前正在运行的执行程序。</li> + +<li>使用 <code>list results</code> 或 <code>l r</code> 查看过往测试执行程序的摘要。</li> + +<li>使用 <code>help list</code> 查看其他 <code>list</code> 命令。</li> + +<li>使用 <code>afwtest</code>，借助过滤器监控实时 logcat，然后打开另一个终端，并使用 <code>adb logcat | grep afwtest</code> 启动 logcat。测试完成后，请执行以下操作：<ul> +<li>在 <code>out/host/linux-x86/afw-th/android-cts/repository/logs/<em>start-time</em></code> 中查看日志。完整的设备 logcat 和主机日志（<code>afw-test-tradefed</code> 日志）会保存在单独的 ZIP 文件中。</li> + +<li>通过搜索设备 logcat，查看与 <strong>afwtest</strong> 相关的信息。示例：<code>zless +out/host/linux-x86/afw-th/android-cts/repository/logs/<em>start-time</em>/device_logcat_<em>random-number</em>.zip +| grep afwtest</code></li> + +<li>使用以下命令查看完整的 afw-test-tradefed 日志：<code>zless +out/host/linux-x86/afw-th/android-cts/repository/logs/<em>start-time</em>/host_log_<em>random-number</em>.zip</code> +</li> +</ul> +</li> +<li>测试包通过以下方式将 AfW 的配置流程自动化：访问界面页面，并将导航日志记录在每个页面的设备 logcat 文件中。示例：<code>afwtest.AutomationDriver: +Navigating:com.android.afwtest.uiautomator.pages.gms.AddAccountPage</code> +<br />用于测试包 <code>com.android.afwtest.NfcProvisioning</code> 的界面页面包括：<ul> +<li> +<code>com.android.afwtest.uiautomator.pages.managedprovisioning.NfcProvisioningPage</code> +</li> +<li><code>com.android.afwtest.uiautomator.pages.PageSkipper</code></li> +<li><code>com.android.afwtest.uiautomator.pages.LandingPage</code></li> +</ul> +</li> +<li>如果测试在配置过程中失败，logcat 将包含类似于以下内容的错误消息：<pre>TestRunner: java.lang.RuntimeException: Failed to load page: com.android.afwtest.uiautomator.pages.packageinstaller.DeviceAccessPage +</pre>这类错误通常是由之前的界面网页或加载失败的网页中的错误所导致，因此，请尝试在 logcat 中找到出现该错误之前的其他错误消息，然后按照配置流程手动重现该错误。</li> +<li>如果测试包运行失败：<ul> +<li>系统会使用以下语法将屏幕截图保存到 <code>out/host/linux-x86/afw-th/android-cts/repository/logs/<em>start-time</em></code>：<code>screenshot-test_<em>test_class_full_name</em>_<em>test_case_name</em>-<em>random_number</em>.png</code>。该信息也会记录在主机日志中。</li> +<li>错误报告会以 <code>bug-<em>test_class_full_name</em>_<em>test_case_name</em>-<em>random_number</em>.zip</code> 的形式保存到 <code>out/host/linux-x86/afw-th/android-cts/repository/logs/<em>start-time</em></code>。 +</li> +</ul> +</li> +<li>执行完所有测试包后，系统会进行屏幕截图，并以 <code>screenshot-<em>random_number</em>.png</code> 的形式将其保存到 <code>out/host/linux-x86/afw-th/android-cts/repository/logs/<em>start-time</em></code>。该信息也会记录在主机日志中。</li> +</ul> + +<h2 id="faq">常见问题解答</h2> +<p>要针对未在下面解答的问题获取帮助，请通过 <a href="mailto:afw-testharness-support@google.com">afw-testharness-support@google.com</a> 联系我们。 +</p> + +<p><strong>我是否可以在使用 user 版本刷机的设备上运行测试计划 <code>afw-userdebug-build</code>？</strong></p> +<p><em>不可以。在运行实际测试流程前，<code>afw-userdebug-build</code> 计划工厂中的测试包会重置测试设备，并要求自动启用 <code>adb</code> 调试。在 user 版本中，用户只能通过手动更改开发者选项中的设置来启用 <code>adb</code> 调试。</em></p> + +<p><strong>我是否可以在使用 userdebug 版本刷机的设备上运行测试计划 <code>afw-user-build</code>？</strong></p> +<p><em>可以，但我们建议您在 user 版本中运行该测试计划。</em></p> + +<p><strong>有时候我的测试会因为界面加载时间过长而失败。该怎么解决这个问题？</strong></p><em>在 <code>./android-cts/repository/testcases/afw-test.props</code> 中配置 <code>timeout_size</code> 设置。有效设置为：S、M、L、XL 和 XXL。</em><p></p> + +<p><strong>测试包 <code>com.android.afwtest.NfcProvisioning</code>（或 <code>SuwDoProvisioning</code>）无法在我的设备上成功运行，因为安装的初始设置（即设置向导）会在配置完成后显示自定义界面（例如“条款及条件”）。如何才能跳过该自定义界面？</strong></p> +<p><em>在配置过程结束后，系统应显示最小化界面。如果界面所包含的按钮包含有意义的文本或内容描述，且文本或内容描述含有以下任何字词，则自动化测试框架将自动跳过此类界面：“跳过”、“结束”、“完成”、“接受”、“同意”、“下一步”、“继续”、“前进”。或者，您可以在 <code>afw-test.props</code> 中定义一个按钮，以便将自动化测试框架配置为跳过您的界面。示例：</em></p> +<pre> +oem_widgets=your_btn +your_btn.text=your_customized_text +your_btn.package=your_package +your_btn.action=click +</pre> +<em></em><p><em>要定义多个微件，请使用逗号分隔。</em></p> + +<p><strong>测试包 <code>com.android.afwtest.NfcProvisioning</code>（或 <code>SuwDoProvisioning</code>）运行失败，最后的界面屏幕显示“验证您的帐号”。为什么会发生这种情况？怎样才能恢复测试设备？ +</strong></p> +<p><em>出现该问题的原因是：之前的测试包未能在测试结束后停用恢复出厂设置保护功能。您必须手动输入帐号才能解锁设备。</em></p> + +<p><strong>我的设备需要较长时间才能恢复出厂设置。我是否可以延长恢复出厂设置超时？</strong></p> +<p><em>可以。您可以在 <code>afw-test.props</code> 中配置 <code>factory_reset_timeout_min</code> 设置。有效时间设置以分钟为单位；您可以设置适合您设备的任意分钟数。</em></p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/config/carrier.html b/zh-cn/devices/tech/config/carrier.html new file mode 100644 index 00000000..e690a845 --- /dev/null +++ b/zh-cn/devices/tech/config/carrier.html @@ -0,0 +1,181 @@ +<html devsite><head> + <title>运营商配置</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 6.0 Marshmallow 版本为特权应用推出了一项功能，可以为相应平台提供运营商专属配置。此功能是以 Android 5.1 (Lollipop MR1) 中推出的 <a href="uicc.html">UICC 运营商授权功能</a>为基础，使运营商配置得以弃用静态配置叠加层，并使运营商和原始设备制造商 (OEM) 能够通过指定接口向相应平台动态提供运营商配置。</p> + +<p>经过正确签名的运营商应用可以预先加载到系统映像中，也可以自动安装，或者通过应用商店手动安装。平台会征询应用并提供以下配置信息以便于设置应用：</p> + +<ul> + <li>漫游/非漫游网络 + </li><li>可视语音信箱 + </li><li>短信/彩信网络设置 + </li><li>VoLTE/即时通讯配置 +</li></ul> + +<p class="note"><strong>注意</strong>：此应用必须使用证书进行签名，且所用证书的签名要与 SIM 卡上的签名一致。有关详情，请参阅<a href="#how_privilege_is_granted_to_a_carrier_app">如何向运营商应用授予权限</a>一节。</p> + +<p>返回值的选择完全取决于运营商应用，并且可以根据通过平台传递给应用的详细信息做出动态抉择。</p> + +<p>这种方法的主要优点包括：</p> + +<ul> + <li><strong>动态配置</strong> - 支持非 MCCMNC 衍生的配置等概念，例如：移动虚拟网络运营商 (MVNO) 或客户选择使用的额外服务 + </li><li><strong>支持通过任何渠道销售的设备</strong> - 例如，开放市场手机可以通过从应用商店下载应用，自动配置正确的设置。 + </li><li><strong>安全性</strong> - 仅向运营商签名的应用授予提供此配置的权限 + </li><li><strong>定义的 API</strong> - 过去，此配置主要存储在框架内的内部 XML 覆盖层中，而不是通过公共 API 进行配置。Android 6.0 中的运营商配置 API 是公共的且进行了严格定义。 +</li></ul> + +<h2 id="how_it_works">工作原理</h2> + +<h3 id="loading_the_config">加载配置</h3> + +<p>此功能提供的运营商配置是一组可以改变平台中各种电话相关行为的键值对。</p> + +<p>适用于特定设备的那组值是通过依序征询以下组件来确定：</p> + +<ol> + <li>运营商应用（虽然从技术上来看这不是必需的，但对于 Android 开源项目 (AOSP) 之外的其他配置来说，建议进行征询） + </li><li>与系统映像捆绑在一起的平台配置应用 + </li><li>硬编码到框架中（相当于 M 之前的行为）的默认值 +</li></ol> + +<p class="caution"><strong>重要提示</strong>：如果特定键的值在任何阶段都会予以返回，则发现的第一个值优先于其他阶段返回的值。</p> + +<h4 id="the_platform_config_app">平台配置应用</h4> + +<p>通用的平台配置应用会与系统映像捆绑在一起，而且该系统映像能够提供常规运营商应用不会提供的变量的值。平台配置应用可在 <code>packages/apps/CarrierConfig</code> 中找到（M 中）。</p> + +<p>此应用的目的是在未安装运营商应用的情况下提供一些基于运营商网络的配置，运营商/OEM 应在他们自己的映像中对配置只做很小的改动。不过，运营商应该提供单独的运营商应用以实现运营商定制，从而使更新可以通过诸如应用商店之类的渠道分发给用户。</p> + +<h4 id="how_privilege_is_granted_to_a_carrier_app">如何向运营商应用授予权限</h4> + +<p>根据 <a href="uicc.html">UICC 运营商授权</a>中的记录，相关的运营商应用必须使用在 SIM 卡上发现的同一证书进行签名。</p> + +<h4 id="what_information_is_passed_to_the_carrier_app">向运营商应用传递的信息</h4> + +<p>对运营商应用提供以下值，以使运营商应用能够对要返回的值做出动态抉择：</p> + +<ul> + <li>MCC + </li><li>MNC + </li><li>SPN + </li><li>IMSI + </li><li>GID1 + </li><li>GID2 +</li></ul> + +<h4 id="when_loading_the_carrier_config_occurs">在加载运营商配置时发生</h4> + +<p>在以下情况下，将构建键值对列表：</p> + +<ul> + <li>加载 SIM 卡（启动或 SIM 卡热插拔）时 + </li><li>运营商应用手动触发重新加载时 + </li><li>运营商应用更新时 +</li></ul> + +<p>如需了解更多详情，请参阅以下参考资料：<a href="http://developer.android.com/reference/android/service/carrier/CarrierService.html#onLoadConfig(android.service.carrier.CarrierIdentifier)">android.service.carrier.CarrierService#onLoadConfig()</a>。</p> + +<p class="note"><strong>注意</strong>：平台会缓存运营商配置捆绑包，并在 SIM 状态发生改变时从缓存中加载内容。缓存目的在于加速启动和 SIM 卡热插拔。假定软件包没有更新或没有明确的 <code>notifyConfigChangedForSubId</code>，配置捆绑包尚未被修改。</p> + +<h3 id="using_the_config">使用配置</h3> + +<p>一旦构建了配置，配置中包含的值将用于设置系统配置中的各种值，其中包括：</p> + +<ul> + <li>内部框架电话设置 + </li><li>SDK 返回的配置值，例如：在 SmsManager 中 + </li><li>应用设置，例如：拨号器中的 VVM 连接值 +</li></ul> + +<h3 id="configuration_keys">配置密钥</h3> + +<p>密钥列表被定义为 <code><a href="http://developer.android.com/reference/android/telephony/CarrierConfigManager.html">android.telephony.CarrierConfigManager</a></code> 中公共 SDK 的一部分，并且不能在相同的 API 级别中更改。有关密钥的摘要，请参见下表。</p> + +<h2 id="how_to_build_your_application">如何构建应用</h2> + +<h3 id="create_your_application">打造您的应用</h3> + +<p>您的应用必须定位到 Android 6.0 API 级别 (23)。</p> + +<h3 id="declare_a_class_that_overrides_android_service_carrier_carrierservice">声明一个替换 android.service.CarrierCarrierService 的类</h3> + +<ol> + <li>替换 <code>onLoadConfig</code> 以根据传递的 <code>service.carrier.CarrierIdentifier</code> 对象返回您希望提供的值 + </li><li>添加逻辑以在运营商配置可能随时间发生改变的情况下调用 <code>notifyConfigChangedForSubId</code>（例如，当用户向其帐号添加额外服务时） +</li></ol> + +<p>请参阅以下示例：</p> + +<pre> +public class SampleCarrierConfigService extends CarrierService { + + private static final String TAG = "SampleCarrierConfigService"; + + public SampleCarrierConfigService() { + Log.d(TAG, "Service created"); + } + + @Override + public PersistableBundle onLoadConfig(CarrierIdentifier id) { + Log.d(TAG, "Config being fetched"); + PersistableBundle config = new PersistableBundle(); + config.putBoolean( + CarrierConfigManager.KEY_CARRIER_VOLTE_AVAILABLE_BOOL, true); + config.putBoolean( + CarrierConfigManager.KEY_CARRIER_VOLTE_TTY_SUPPORTED_BOOL, false); + config.putInt(CarrierConfigManager.KEY_VOLTE_REPLACEMENT_RAT_INT, 6); + // Check CarrierIdentifier and add more config if needed… + return config; + } +} +</pre> + +<p>如需了解更多详情，请参阅 developer.android.com 网站上的 <a href="https://developer.android.com/reference/android/service/carrier/CarrierService.html">android.service.carrier.CarrierService</a> 参考资料。</p> + +<h3 id="name_the_class_in_your_manifest">命名清单中的类</h3> + +<p>请参阅以下示例：</p> + +<pre> +<service android:name=".SampleCarrierConfigService" +android:label="@string/service_name" +android:permission="android.permission.BIND_CARRIER_SERVICES"> + <intent-filter> + <action android:name="android.service.carrier.ConfigService"/></intent-filter> +</service> +</pre> + +<h3 id="sign_app_with_same_certificate_on_sim">使用 SIM 卡上的同一证书对应用进行签名</h3> + +<p>有关签名要求，请参阅 <a href="uicc.html">UICC 运营商授权</a>。</p> + +<h2 id="testing_your_application">测试您的应用</h2> + +<p>构建配置应用后，您可以使用以下工具来测试代码：</p> + +<ul> + <li>包含有效证书签名的 SIM 卡 + </li><li>运行 Android 6.0 或更高版本的设备（例如：Nexus 设备） +</li></ul> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/config/filesystem.html b/zh-cn/devices/tech/config/filesystem.html new file mode 100644 index 00000000..c47a4b08 --- /dev/null +++ b/zh-cn/devices/tech/config/filesystem.html @@ -0,0 +1,136 @@ +<html devsite><head> + <title>文件 DAC 配置</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 使用不可扩展的系统配置文件，导致设备制造商无法通过添加具名二进制文件来指定所有权、访问模式或可执行权限的自主访问控制 (DAC)。设置这种限制的原因是为了支持 Linux 内核 3.14 及更高版本，这些版本通过 <code>CAP_SUSPEND_BLOCK</code> 功能启用唤醒锁定；要保持此唤醒锁定（从而在文件系统中设置此功能），需要合作伙伴提供的 GPS 守护进程。</p> + +<p>从 Android 6.0 开始，<code>fs_config</code> 和相关结构定义 (<code>system/core/include/private/android_filesystem_config.h</code>) 位于 <code>system/core/libcutils/fs_config.c</code> 中，可以由安装在 <code>/system/etc/fs_config_dirs</code> 和 <code>/system/etc/fs_config_files</code> 中的二进制文件进行更新或替换。为明确起见，Android 针对目录和文件采用单独的匹配和解析规则（可以使用其它全局表达式），并在两个不同的表格中处理目录和文件。<code>system/core/libcutils/fs_config.c</code> 中的结构定义不仅允许运行时读取目录和文件，而且主机在构建时也可以使用相同的文件来构建文件系统映像，比方说 <code>${OUT}/system/etc/fs_config_dirs</code> 和 <code>${OUT}/system/etc/fs_config_files</code>。</p> + +<h2 id="gen-files">生成替换文件</h2> + +<p>您可以使用 <code>build/tools/fs_config</code> 中的 <code>fs_config_generate</code> 工具生成相应的二进制文件 <code>/system/etc/fs_config_dirs</code> 和 <code>/system/etc/fs_config_files</code>。该工具使用 <code>libcutils</code> 库函数 (<code>fs_config_generate()</code>) 管理放入缓冲区内的 DAC 需求，并为头文件定义规则来规定 DAC 规则的用法。</p> + +<p>要使用此工具，请在 <code>device/<em>vendor</em>/<em>device</em>/android_filesystem_config.h</code> 中创建头文件作为替换。该文件必须使用 <code>system/core/include/private/android_filesystem_config.h</code> 中定义的 <code>structure fs_path_config</code> 格式，并对目录和文件符号进行以下结构初始化：</p> +<ul> +<li>对于目录，请使用 <code>android<strong>_device</strong>_dirs[]</code>。</li> +<li>对于文件，请使用 <code>android<strong>_device</strong>_files[]</code>。</li> +</ul> + +<p>在不使用 <code>android_device_dirs[]</code> 和 <code>android_device_files[]</code> 时，您可以定义 <code>NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_DIRS</code> 和 <code>NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_FILES</code>（请参见下面的<a href="#example">示例</a>）。</p> + +<p>您还可以使用单板配置中的 <code>TARGET_ANDROID_FILESYSTEM_CONFIG_H</code> 指定强制基本名称为 <code>android_filesystem_config.h</code> 的替换文件。 + +</p><h2 id="include-files">包含的文件</h2> + +<p><code>PRODUCT_PACKAGES</code> 必须包含 <code>fs_config_dirs</code> 和/或 <code>fs_config_files</code>，才能分别将它们安装到 <code>/system/etc/fs_config_dirs</code> 和 <code>/system/etc/fs_config_files</code>。</p> + +<p>构建系统会在 <code>BoardConfig.mk</code> 所在的 <code>$(TARGET_DEVICE_DIR)</code> 中搜索自定义 <code>android_filesystem_config.h</code>。如果此文件位于其他位置，请设置单板配置变量 <code>TARGET_ANDROID_FILESYSTEM_CONFIG_H</code> 来指向该位置。</p> + +<h2 id="configuring">配置</h2> +<p>要在 Android 6.0 及更高版本中配置文件系统，请按以下步骤操作：</p> + +<ol> +<li>创建 <code>$(TARGET_DEVICE_DIR)/android_filesystem_config.h</code> 文件。</li> +<li>将 <code>fs_config_dirs</code> 和/或 <code>fs_config_files</code> 添加到单板配置文件（例如 <code>$(TARGET_DEVICE_DIR)/device.mk</code>）中的 <code>PRODUCT_PACKAGES </code>。</li> +</ol> + +<h2 id="migration-concerns">迁移问题</h2> +<p>将系统配置从 Android 5.0 及更早版本中迁出会造成干扰。在规划此类迁移时，请注意以下事项：</p> +<ul> +<li>Android 6.0 会移除部分头文件、结构和内嵌定义。</li> +<li>Android 6.0 需要引用 <code>libcutils</code>，而不是直接从 <code>system/core/include/private/android_filesystem_config.h</code> 运行。依赖于 <code>system/code/include/private_filesystem_config.h</code> 的文件/目录结构或者 <code>fs_config</code> 的设备制造商私有可执行文件必须添加 <code>libcutils</code> 库依赖关系。</li> +<li>Android 6.0 需要使用 <code>system/core/include/private/android_filesystem_config.h</code> 的设备制造商私有分支副本，该副本应包含有关现有目标的附加内容，以便移至 <code>device/<em>vendor</em>/<em>device</em>/android_filesystem_config.h</code>。 +</li> +<li>由于 Android 保留将 SELinux 强制访问控制 (MAC) 应用于目标系统中配置文件的权利，因此包含使用 <code>fs_config()</code> 的自定义目标可执行文件的实现必须确保具有访问权限。</li> +</ul> + +<h2 id="example">示例</h2> + +<p>此示例展示了用于替换 <code>system/bin/glgps</code> 守护进程以在 <code>device/<em>vendor</em>/<em>device</em></code> 目录中添加唤醒锁定支持的补丁。请注意以下几点：</p> + +<ul> +<li>每个结构条目都包含模式、uid、gid、功能和名称。 +已自动包含 <code>system/core/include/private/android_filesystem_config.h</code> 来提供清单 #defines（<code>AID_ROOT</code>、<code>AID_SHELL</code>、<code>CAP_BLOCK_SUSPEND</code>）。</li> +<li><code>android_device_files[]</code> 区段包含在未指定时禁止访问 <code>system/etc/fs_config_dirs</code> 的操作，其作用是在缺少目录替换内容时提供额外 DAC 保护。但此保护的强度较弱；如果有人拥有超过 <code>/system</code> 的控制权，那么他通常可以执行任何操作。</li> +</ul> + +<pre> +diff --git a/android_filesystem_config.h b/android_filesystem_config.h +new file mode 100644 +index 0000000..874195f +--- /dev/null ++++ b/android_filesystem_config.h +@@ -0,0 +1,36 @@ ++/* ++ * Copyright (C) 2015 The Android Open Source Project ++ * ++ * Licensed under the Apache License, Version 2.0 (the "License"); ++ * you may not use this file except in compliance with the License. ++ * You may obtain a copy of the License at ++ * ++ * http://www.apache.org/licenses/LICENSE-2.0 ++ * ++ * Unless required by applicable law or agreed to in writing, software ++ * distributed under the License is distributed on an "AS IS" BASIS, ++ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or ++ * implied. See the License for the specific language governing ++ * permissions and limitations under the License. ++ */ ++ ++/* This file is used to define the properties of the filesystem ++** images generated by build tools (eg: mkbootfs) and ++** by the device side of adb. ++*/ ++ ++#define NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_DIRS ++/* static const struct fs_path_config android_device_dirs[] = { }; */ ++ ++/* Rules for files. ++** These rules are applied based on "first match", so they ++** should start with the most specific path and work their ++** way up to the root. Prefixes ending in * denotes wildcard ++** and will allow partial matches. ++*/ ++static const struct fs_path_config android_device_files[] = { ++ { 00755, AID_ROOT, AID_SHELL, (1ULL << CAP_BLOCK_SUSPEND), +"system/bin/glgps" }, ++#ifdef NO_ANDROID_FILESYSTEM_CONFIG_DEVICE_DIRS ++ { 00000, AID_ROOT, AID_ROOT, 0, "system/etc/fs_config_dirs" }, ++#endif ++}; + +diff --git a/device.mk b/device.mk +index 0c71d21..235c1a7 100644 +--- a/device.mk ++++ b/device.mk +@@ -18,7 +18,8 @@ PRODUCT_PACKAGES := \ + libwpa_client \ + hostapd \ + wpa_supplicant \ +- wpa_supplicant.conf ++ wpa_supplicant.conf \ ++ fs_config_files + + ifeq ($(TARGET_PREBUILT_KERNEL),) + ifeq ($(USE_SVELTE_KERNEL), true) +</pre> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/config/low-ram.html b/zh-cn/devices/tech/config/low-ram.html new file mode 100644 index 00000000..f0abcc06 --- /dev/null +++ b/zh-cn/devices/tech/config/low-ram.html @@ -0,0 +1,271 @@ +<html devsite><head> + <title>低内存配置</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="intro">简介</h2> + +<p>Android 现支持内存为 512MB 的设备。本文档旨在帮助 OEM 优化和配置 Android 4.4，使其能够在低内存设备上运行。在下文所述的优化措施中，有几项非常通用，甚至也可应用于以前的版本。</p> + +<h2 id="optimizations">Android 4.4 平台优化</h2> + +<h3 id="opt-mgmt">改善了内存管理</h3> +<ul> +<li>验证了可节省内存的内核配置：内核同页合并 (KSM) 和交换到 ZRAM。</li> +<li>终止那些即将被取消缓存且过大的缓存进程。</li> +<li>不允许大型服务自行返回至 A 服务（以免导致启动器终止）。</li> +<li>终止那些处于空闲维护状态中的过大进程（甚至终止当前 IME 等通常不可终止的进程）。</li> +<li>对后台服务的启动进行序列化。</li> +<li>微调了低内存设备的内存使用情况：采用更严格的内存不足 (OOM) 调整级别、缩减图形缓存大小，等等。</li> +</ul> + +<h3 id="opt-mem">减少了系统内存</h3> +<ul> +<li>删减了 system_server 和 SystemUI 进程（节省了几兆的内存）。</li> +<li>在 Dalvik 中预加载 dex 缓存（节省了几兆的内存）。</li> +<li>验证了 JIT-off 选项（每个进程最多可节省 1.5MB 的内存）。</li> +<li>减少了各进程的字体缓存开销。</li> +<li>引入了占用内存更小的 ArrayMap/ArraySet，并在框架中广泛地使用其来替代 HashMap/HashSet。</li> +</ul> + +<h3 id="opt-proc">Procstats</h3> +<p> +新增了一个开发者选项，以显示内存状态和应用内存使用情况（按照运行频率和所耗内存量排序）。 +</p> + +<h3 id="opt-api">API</h3> +<p> +新增了 ActivityManager.isLowRamDevice()，使应用不仅能够检测是否是在低内存设备上运行，还能选择停用那些占用内存较大的功能。 +</p> + +<h3 id="opt-track">内存跟踪</h3> +<p> +使用新的 memtrack HAL 跟踪图形内存分配情况、dumpsys meminfo 中的其他信息以及 meminfo 中的阐明性总结（例如，所报告的空闲内存包括缓存进程的内存，以免 OEM 费力去优化错误的对象）。 +</p> + +<h2 id="build-time">编译时配置</h2> +<h3 id="flag">启用低内存设备标志</h3> +<p>我们引入了一个名为 <code>ActivityManager.isLowRamDevice()</code> 的新 API，以便应用能够确定是否应关闭那些在低内存设备上运行不良的内存密集型功能。</p> +<p>对于内存为 512MB 的设备，该 API 预计会返回“true”。若要启用该 API，请在设备 makefile 中使用下面这项系统属性： +<br /> +<code>PRODUCT_PROPERTY_OVERRIDES += ro.config.low_ram=true</code></p> + +<h3 id="jit">停用 JIT</h3> + + <p>系统级的 JIT 内存使用情况取决于正在运行的应用的数量以及这些应用的代码所占用的空间。JIT 会为编译后代码的缓存设定大小上限，并会根据需要处理其中的页面。在典型的运行系统中，JIT 会占用 3M 到 6M 的内存。<br /> + <br /> +大型应用往往很快就会达到代码缓存大小上限（默认情况下向来都是 1M）。平均来说，每个应用的 JIT 缓存使用量会介于 100K 和 200K 字节之间。减小缓存的大小上限在某种程度上有助于改进内存使用情况，但如果将这一上限设得过低，则会将 JIT 置于颠簸模式。对于内存确实很低的设备，我们建议完全停用 JIT。</p> + +<p>若要完全停用 JIT，请在产品 makefile 中添加下面这行内容：<br /> +<code>PRODUCT_PROPERTY_OVERRIDES += dalvik.vm.jit.codecachesize=0</code></p> +<h3 id="launcher">启动器配置</h3> + + <p>请务必确保启动器上的默认壁纸设置<strong>未</strong>使用动态壁纸。低内存设备不应预安装任何动态壁纸。</p> + +<h2 id="kernel">内核配置</h2> +<h3 id="kernel-tuning">微调内核/ActivityManager 以减少直接回收</h3> + + <p>当进程或内核尝试分配（直接分配或因新页面中存在故障而分配）内存页面并且内核已用尽所有可用内存时，就会发生直接回收。在这种情况下，内核便需要阻止分配并释放一个页面，而这通常又需要磁盘 I/O 清理一个有文件支持的脏页或等待 <code>lowmemorykiller</code> 终止一个进程。最终可能会导致任意线程（包括界面线程）中出现额外 I/O。</p> + + <p>为避免出现直接回收，内核已配有可触发 <code>kswapd</code> 或后台回收的水印。此线程会尝试释放页面，以便下次分配的真实线程能够快速顺利启动。</p> + + <p>用于触发后台回收的默认阈值相当低 - 在 2GB 设备上约为 2MB，在 512MB 设备上约为 636KB。而且，内核通过后台回收仅能回收几兆的内存。这即意味着，任何快速分配超过几兆字节的内容的进程都会快速导致直接回收。</p> + +<p>在 android-3.4 内核分支中，我们以补丁程序 92189d47f66c67e5fd92eafaa287e153197a454f（“添加额外的可调可用千字节”）的形式添加了对可调新内核的支持。选择将该补丁程序添加到设备内核中，会让 ActivityManager 告知内核尝试保留能容纳 3 个全屏 32 bpp 缓冲区的可用内存空间。</p> + +<p>这些阈值可通过框架 config.xml 进行配置</p> + +<pre> +<!-- Device configuration setting the /proc/sys/vm/extra_free_kbytes tunable +in the kernel (if it exists). A high value will increase the amount of memory +that the kernel tries to keep free, reducing allocation time and causing the +lowmemorykiller to kill earlier. A low value allows more memory to be used by +processes but may cause more allocations to block waiting on disk I/O or +lowmemorykiller. Overrides the default value chosen by ActivityManager based +on screen size. 0 prevents keeping any extra memory over what the kernel keeps +by default. -1 keeps the default. --> +<integer name="config_extraFreeKbytesAbsolute">-1</integer> +</pre> + +<pre> +<!-- Device configuration adjusting the /proc/sys/vm/extra_free_kbytes +tunable in the kernel (if it exists). 0 uses the default value chosen by +ActivityManager. A positive value will increase the amount of memory that the +kernel tries to keep free, reducing allocation time and causing the +lowmemorykiller to kill earlier. A negative value allows more memory to be +used by processes but may cause more allocations to block waiting on disk I/O +or lowmemorykiller. Directly added to the default value chosen by +ActivityManager based on screen size. --> +<integer name="config_extraFreeKbytesAdjust">0</integer> +</pre> + +<h3 id="lowmem">微调 LowMemoryKiller</h3> + +<p>ActivityManager 可配置 LowMemoryKiller 的阈值，以匹配它对在每个优先级存储分区中运行进程时所需的文件支持页面（缓存页面）工作集的预期。如果设备对工作集有很高的要求（例如：如果供应商界面需要更多内存，或者如果添加了更多服务），则可增大阈值。</p> + +<p>如果为文件支持页面预留了太多内存，则可减小阈值，以便系统能够早在因缓存变得过小而导致磁盘颠簸之前就终止后台进程。</p> + +<pre> +<!-- Device configuration setting the minfree tunable in the lowmemorykiller +in the kernel. A high value will cause the lowmemorykiller to fire earlier, +keeping more memory in the file cache and preventing I/O thrashing, but +allowing fewer processes to stay in memory. A low value will keep more +processes in memory but may cause thrashing if set too low. Overrides the +default value chosen by ActivityManager based on screen size and total memory +for the largest lowmemorykiller bucket, and scaled proportionally to the +smaller buckets. -1 keeps the default. --> +<integer name="config_lowMemoryKillerMinFreeKbytesAbsolute">-1</integer> +</pre> + +<pre> +<!-- Device configuration adjusting the minfree tunable in the +lowmemorykiller in the kernel. A high value will cause the lowmemorykiller to +fire earlier, keeping more memory in the file cache and preventing I/O +thrashing, but allowing fewer processes to stay in memory. A low value will +keep more processes in memory but may cause thrashing if set too low. Directly +added to the default value chosen by ActivityManager based on screen +size and total memory for the largest lowmemorykiller bucket, and scaled +proportionally to the smaller buckets. 0 keeps the default. --> +<integer name="config_lowMemoryKillerMinFreeKbytesAdjust">0</integer> +</pre> + +<h3 id="ksm">KSM（内核同页合并）</h3> + +<p>KSM 是一个在后台运行的内核线程，可对内存中已由用户空间标为 <code>MADV_MERGEABLE</code> 的页面进行比较。如果发现两个页面相同，KSM 线程即会将它们合并为内存的单个写入时复制页面。</p> + +<p>从长远来看，KSM 会为所运行的系统节省内存，但它是以 CPU 功耗为代价来获得重复的内存，这可能会对电池寿命产生不良影响。功耗损失与通过启用 KSM 而节省的内存到底孰重孰轻？您应认真地权衡一下。</p> + +<p>为便于测试 KSM，我们建议您查看长时间运行（运行数小时）的设备，并观察 KSM 是否对启动时间和渲染时间起到了明显的改善作用。</p> + +<p>要启用 KSM，请先启用内核中的 <code>CONFIG_KSM</code>，然后将下列各行内容添加到 <code>init.<device>.rc</code> 文件中：<br /> + +</p><pre> +write /sys/kernel/mm/ksm/pages_to_scan 100 +write /sys/kernel/mm/ksm/sleep_millisecs 500 +write /sys/kernel/mm/ksm/run 1 +</pre> + +<p>启用后，有几种实用工具可帮助进行调试，这几种工具分别是：procrank、librank 和 ksminfo。借助这些实用工具，您可以查看 KSM 内存与进程之间的映射关系以及占用 KSM 内存最多的进程。一旦发现一块看起来值得探索的内存，您便可以使用 hat 实用工具来探索该内存（如果它是 dalvik 堆上的重复对象）。</p> + +<h3 id="zram">交换到 zRAM</h3> + +<p>zRAM 交换可通过压缩内存页面并将其放入动态分配的内存交换区来增加系统中的可用内存量。</p> + +<p>由于这是以牺牲 CPU 时间为代价来增加少量内存，因此您应仔细权衡 zRAM 交换会对您系统的性能造成的负面影响。</p> + +<p>Android 会在多个层面上处理 zRAM 交换：</p> + +<ul> + <li>首先，必须启用以下内核选项，才能有效地使用 zRAM 交换：<ul> + <li><code>CONFIG_SWAP</code></li> + <li><code>CONFIG_CGROUP_MEM_RES_CTLR</code></li> + <li><code>CONFIG_CGROUP_MEM_RES_CTLR_SWAP</code></li> + <li><code>CONFIG_ZRAM</code></li> + </ul> + </li> + <li>然后，您应将一行与下例类似的内容添加到您的 fstab 中：<br /> + <code>/dev/block/zram0 none swap defaults zramsize=<size in bytes>,swapprio=<swap partition priority></code><br /> + <code><br /> + zramsize</code> 是必要内容，表示您希望 zram 区域占用多少未压缩内存。压缩比通常为 30-50％。<br /> + <br /> + <code>swapprio</code> 是可选内容；如果您没有多个交换区，则无需使用此项。<br /> + <br /> +您还应确保在特定于设备的 <a href="/security/selinux/implement.html">sepolicy/file_contexts</a> 中将关联的块设备标为 swap_block_device，以便 SELinux 适当地处理它。<br /> + <code>/dev/block/zram0 u:object_r:swap_block_device:s0</code><br /> + <br /> + </li> + <li>默认情况下，Linux 内核每次会换入 8 页内存。当使用 ZRAM 时，由每次读取 1 页而产生的增量成本微乎其微，且可能有助于防止设备承受极端的内存压力。要想每次只读取 1 页，请将以下内容添加到您的 <code>init.rc</code>：<br /> + <code>write /proc/sys/vm/page-cluster 0</code></li> + <li>在您的 <code>init.rc</code> 中的 <code>mount_all /fstab. X</code> 行后面，添加以下内容：<br /> + <code>swapon_all /fstab.X</code></li> + <li>如果在内核中启用了此功能，系统便会在启动时自动配置内存 cgroup。</li> + <li>如果内存 cgroup 可用，ActivityManager 就会将优先级较低的线程标为比其他线程更易于交换。如果需要内存，Android 内核则会开始将内存页面迁移到 zRAM 交换区，并会优先处理那些已被 ActivityManager 标记的内存页面。</li> +</ul> + +<h3 id="carveouts">Carveout、Ion 和连续内存分配 (CMA)</h3> + +<p>对于低内存设备，需要特别注意 carveout，尤其是未必会一直被充分利用的 carveout，例如用于安全地播放视频的 carveout。有几种解决方案可最大限度地减小 carveout 区域的影响，具体取决于硬件的确切要求。</p> + +<p>如果硬件允许不连续的内存分配，则 Ion 系统堆可从系统内存中分配内存，这样便无需使用 carveout。它还会尝试进行大量分配以消除外围设备上的 TLB 压力。如果内存区域必须连续或必须限定在某个特定地址范围内，则可以使用连续内存分配器 (CMA)。</p> + +<p>以这种方式创建的 carveout 也可供系统用于处理可移动页面。当需要该区域时，可移动页面就会被从中移出，以便系统将一个处于空闲状态的大型 carveout 用于其他目的。您可以直接使用 CMA，也可以借助 Ion（通过使用离子 CMA 堆）更轻松地使用 CMA。</p> + +<h2 id="app-opts">应用优化提示</h2> +<ul> + <li>查看<a href="http://developer.android.com/training/articles/memory.html">管理您的应用内存</a>和与同一主题相关的以往博文：<ul> + <li><a href="http://android-developers.blogspot.com/2009/01/avoiding-memory-leaks.html">http://android-developers.blogspot.com/2009/01/avoiding-memory-leaks.html</a></li> + <li><a href="http://android-developers.blogspot.com/2011/03/memory-analysis-for-android.html">http://android-developers.blogspot.com/2011/03/memory-analysis-for-android.html</a></li> + <li><a href="http://android-developers.blogspot.com/2009/02/track-memory-allocations.html">http://android-developers.blogspot.com/2009/02/track-memory-allocations.html</a></li> + <li> <a href="http://tools.android.com/recent/lintperformancechecks">http://tools.android.com/recent/lintperformancechecks</a></li> + </ul> +</li> + <li>从预安装应用中检查/移除所有未使用的资源 - development/tools/findunused（应该会有助于减小应用所占用的空间）。</li> +<li>对资源（特别是具有透明区域的资源）使用 PNG 格式</li> +<li>如果要编写本机代码，请使用 calloc() 而非 malloc/memset</li> +<li>不要启用会将 Parcel 数据写入磁盘并会在日后读取此数据的代码。</li> +<li>不要订阅已安装的所有软件包，而应使用 ssp 过滤。请添加如下所示的过滤条件：<br /> + <code><data android:scheme="package" android:ssp="com.android.pkg1" /><br /> + <data android:scheme="package" android:ssp="com.myapp.act1" /></code></li> +</ul> + +<h3 id="process-states">了解 Android 中的各种进程状态</h3> + + <ul> + <li><p>SERVICE - SERVICE_RESTARTING<br /> +因自身原因自动在后台运行的应用。这是频繁在后台运行的应用最常出现的问题。%duration * pss 很可能是一个绝佳的“不良”指标，但该组合的目标过于明确，也许只执行 %duration 就能更好地筛选出我们完全不希望运行的应用。</p></li> + <li><p>IMPORTANT_FOREGROUND - RECEIVER<br /> +因任何原因在后台运行的应用（不直接与用户交互）。这些应用都会增加系统的内存负载。在这种情况下，使用 (%duration * pss) 不良值很可能是对这些进程进行排序的最佳方式：许多此类进程都会因合理原因而需要一直运行，因此它们的 pss 大小将会是它们的内存负载的重要组成部分。</p></li> + <li><p>PERSISTENT<br /> +持续的系统进程。跟踪 pss 可监视这些进程是否会变得过大。</p></li> + <li><p>TOP<br /> +正与用户交互的进程。pss 在此又成为了重要指标，可显示应用在被使用的过程中产生的内存负载。</p></li> + <li><p>HOME - CACHED_EMPTY<br /> +所有此类底部进程均是系统保留的备用进程；此类进程可随时终止，并可根据需要重建。这些进程是我们计算内存状态时参照的依据 -“正常”、“中等”、“低”、“严重”均是基于系统可以保留多少个此类进程而定的。pss 亦是这些进程的关键指标；当这些进程处于该状态时，它们应尽量减少自身的内存占用空间，以便系统能够保留尽可能多的进程。一般来说，与在 TOP 状态下相比，运行状况良好的应用在该状态下的 pss 占用空间明显更小。</p></li> + <li> + <p>比较 TOP 与 CACHED_ACTIVITY-CACHED_ACTIVITY_CLIENT<em><br /> + </em>对于同一进程而言，当它处于 TOP 状态时的 pss 和当它处于上述任一种缓存状态时的 pss 之间会存在差异，而这种差异恰恰是可表明该进程在进入后台运行时的内存释放能力的最佳数据。排除 CACHED_EMPTY 状态可以改善该数据，因为这项操作会排除因某些原因（不仅仅是为了呈现界面）而启动进程的情况，因此无需在与用户交互时处理所有的界面开销。</p></li> + </ul> + +<h2 id="analysis">分析</h2> + +<h3 id="app-startup">分析应用启动时间</h3> + +<p>使用带有 <code>-P</code> 或 <code>--start-profiler</code> 选项的 <code>$ adb shell am start</code> 在应用启动时运行分析器。这样一来，当您的进程从 zygote 分岔之后，分析器就会立即启动，虽然此时您的任何代码都还未加载到其中。</p> + +<h3 id="bug-reports">使用错误报告进行分析</h3> + +<p>现已包含可用于进行调试的各种信息。这些服务包括 <code>batterystats</code>、<code>netstats</code>、<code>procstats</code> 和 <code>usagestats</code>。您可以使用如下所示的各行内容找到它们：</p> + +<pre> +------ CHECKIN BATTERYSTATS (dumpsys batterystats --checkin) ------ +7,0,h,-2558644,97,1946288161,3,2,0,340,4183 +7,0,h,-2553041,97,1946288161,3,2,0,340,4183 +</pre> + +<h3 id="persistent">检查是否存在任何持续进程</h3> + +<p>重新启动设备并检查进程。<br /> +运行几个小时，然后再次检查进程。不应存在任何长时间运行的进程。</p> + +<h3 id="longevity">长时测试</h3> + +<p>运行较长时间，并跟踪进程的内存。内存是增加了，还是保持不变？创建规范的使用案例并针对这些情形运行长时测试</p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/config/runtime_perms.html b/zh-cn/devices/tech/config/runtime_perms.html new file mode 100644 index 00000000..1eb5a8e1 --- /dev/null +++ b/zh-cn/devices/tech/config/runtime_perms.html @@ -0,0 +1,103 @@ +<html devsite><head> + <title>运行时权限</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 6.0 及更高版本中的 Android 应用权限模式旨在使权限更易于用户理解、更实用、更安全。该模式将需要危险权限（请参阅<a href="#affected-permissions">受影响的权限</a>）的 Android 应用从安装时权限模式转移至运行时权限模式：<em></em><em></em></p> + +<ul> +<li><strong>安装时权限</strong>（Android 5.1 及更低版本）。<em></em>用户在安装或更新应用时，向应用授予危险权限。OEM/运营商可以在不通知用户的情况下，预先安装具有预授权的应用。</li> +<li><strong>运行时权限</strong>（Android 6.0 及更高版本）。<em></em>用户在应用运行时向应用授予危险权限。应用决定何时申请权限（例如，在应用启动或用户访问特定功能时申请权限），但必须允许用户授予/拒绝授予应用访问特定权限组的权限。OEM/运营商可以预安装应用，但不得预先授予权限（请参阅<a href="#creating-exceptions">创建例外情况</a>）。</li> +</ul> + +<p>运行时权限可以为用户提供应用正在寻求或已被授予的权限的额外上下文和可视性。运行时模式还鼓励开发者帮助用户了解应用请求权限的原因，并向用户透明展示授予或拒绝权限的好处和危害。</p> +<p>用户可使用“设置”中的“应用”菜单撤消应用权限。</p> + +<h2 id="affected-permissions">受影响的权限</h2> + +<p>Android 6.0 及更高版本要求危险权限必须使用运行时权限模式。危险权限是具有更高风险的权限（例如 <code>READ_CALENDAR</code>），此类权限允许寻求授权的应用访问用户私人数据或获取可对用户造成不利影响的设备控制权。要查看危险权限列表，请运行以下命令：</p> +<pre> +adb shell pm list permissions -g -d +</pre> + +<p>Android 6.0 及更高版本不会更改常规权限的行为（包括常规权限、系统权限和签名权限在内的所有非危险权限）。常规权限是具有较低风险的权限（例如 <code>SET_WALLPAPER</code>），它允许请求授权的应用访问隔离的应用级功能，对其他应用、系统或用户的风险非常小。在 Android 5.1 及更低版本中，系统在安装应用时，自动向请求授权的应用授予常规权限，并且无需提示用户进行批准。有关权限的详细信息，请参阅<a href="http://developer.android.com/guide/topics/manifest/permission-element.html"><权限>元件文档</a>。</p> + +<h2 id="requirements">要求</h2> + +<p>运行时权限模式适用于所有应用，包括预安装应用和在设置过程中提供给设备的应用。应用的软件要求如下：</p> +<ul> +<li>所有在 Android 6.0 及更高版本上运行的设备，其运行时权限模式必须一致。而此一致性可通过 Android 兼容性测试套件 (CTS) 测试来保证。</li> +<li>应用必须提示用户在应用运行时授予权限。有关详情，请参阅<a href="#updating-apps">更新应用</a>。在少数例外情况下，可向默认应用和处理程序授予权限。这些默认应用和处理程序将提供设备预期操作所必需的基本设备功能（例如，设备中用于处理 <code>ACTION_CALL</code> 的默认拨号程序应用，可以获得访问电话的权限）。有关详情，请参阅<a href="#creating-exceptions">创建例外情况</a>。</li> +<li>具有“危险权限”的预加载应用必须面向 API 23 级别，并保持运行时权限模式（即：应用安装期间的界面流程不应偏离 PackageInstaller 的 AOSP，且用户可以撤消预安装应用的危险权限授权等）。</li> +<li>无头应用必须使用操作组件来请求权限，或与其他拥有必要权限的应用共享 UID。有关详情，请参阅<a href="#headless-apps">无头应用</a>。</li> +</ul> + +<h2 id="permissions-migration">权限迁移</h2> + +<p>更新到 Android 6.0 或更高版本后，授予 Android 5.x 应用的权限仍然有效，但用户可以随时撤消此类权限。</p> + +<h2 id="integration">集成</h2> + +<p>在向 Android 6.0 及更高版本集成应用运行时权限模式时，必须先更新预安装应用，然后才能使用新模式。您也可以为核心功能的默认处理程序/提供程序定义例外情况，定义自定义权限，以及自定义 PackageInstaller 中使用的主题背景。</p> + +<h3 id="updating-apps">更新应用</h3> + +<p>系统映像上的应用和预安装应用不会自动被预先授予权限。我们建议您与预安装应用的开发者（OEM、运营商和第三方）合作，根据<a href="https://developer.android.com/training/permissions/index.html">开发者指南</a>对应用进行必要的修改。具体来说，您必须保证对预安装应用进行修改，以避免用户在撤消权限时造成应用的崩溃或其他问题。</p> + +<h4 id="preloaded-apps">预加载应用</h4> +<p>使用危险权限的预加载应用必须采用 API 23 级或更高级别，并保持 Android 6.0 及更高版本的 AOSP 权限模式（即：应用安装期间界面流程不应偏离 PackageInstaller 的 AOSP 实现，且用户可以撤消预安装应用的危险权限等）。</p> + +<h4 id="headless-apps">无头应用</h4> +<p>仅 Activity 可以请求权限；服务不能直接请求权限。</p> +<ul> +<li>在 Android 5.1 及更低版本中，无头应用无需使用 Activity 即可在安装或预安装时请求权限。</li> +<li>在 Android 6.0 及更高版本中，无头应用必须使用以下方法之一请求权限：<ul> +<li>添加 Activity 以请求权限（推荐使用）。</li> +<li>与具有必要权限的其他应用共享 UID。仅当您需要将多个 APK 视作单个应用进行处理时，才推荐使用此方法。</li> +</ul></li> +</ul> +<p>这样做是为了避免突兀的权限请求让用户迷惑。</p> + +<h3 id="customizing-package-install">自定义 PackageInstaller</h3> +<p>如有需要，您可以更新 PackageInstaller 所用的默认设备主题背景，以此自定义权限界面<strong>主题背景</strong>（<code>Theme.DeviceDefault.Settings</code> 和 <code>Theme.DeviceDefault.Light.Dialog.NoActionBar</code>）。但是，由于一致性对应用开发者来说至关重要，您不可以自定义权限界面出现时的位置、定位和规则。</p> +<p>要包含其他语言的<strong>字符串</strong>，请将此类字符串提交给 AOSP。</p> + +<h3 id="creating-exceptions">创建例外情况</h3> +<p>通过使用 PackageManager 中的 <code>DefaultPermissionGrantPolicy.java</code>，您可以向核心操作系统功能的默认处理程序或提供程序进行预授权。例如：</p> + +<p><code>ACTION_CALL (Dialer) Default</code><br /> +<code>Phone, Contacts, SMS, Microphone</code></p> +<p><code>SMS_DELIVER_ACTION (SMS/MMS) Default</code><br /> +<code>Phone, Contacts, SMS</code></p> + +<h3 id="defining-custom-perms">自定义权限</h3> +<p>您可以将自定义权限和组定义为常规或危险级别，并将 OEM/运营商特有的权限添加到现有权限组中，该功能与 Android 5.x 和更低版本中的功能相同。<em></em><em></em></p> + +<p>在 Android 6.0 及更高版本中，如果您添加了新的危险权限，该权限的处理方式必须与其他危险权限的处理方式相同（在应用运行时请求权限，且用户可以撤消权限）。具体而言：</p> + +<ul> +<li>您可以向当前组添加新权限，但不可以修改危险权限和危险权限组的 AOSP 映射（例如，您不能从组中删除权限再将该权限分配给其他组）。</li> +<li>您可以向安装在设备上的应用添加新的权限组，但不能向 Android 平台清单中添加新的权限组。</li> +</ul> + +<h2 id="testing-perms">测试权限</h2> +<p>Android 含有兼容性测试套件 (CTS) 测试，可验证各个权限是否映射到正确的组中。Android 6.0 及更高版本中的 CTS 兼容性要求必须通过此类测试。</p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/config/uicc.html b/zh-cn/devices/tech/config/uicc.html new file mode 100644 index 00000000..7e882dc5 --- /dev/null +++ b/zh-cn/devices/tech/config/uicc.html @@ -0,0 +1,228 @@ +<html devsite><head> + <title>UICC 运营商权限</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 5.1 引入了一种机制，即如果 API 与通用集成电路卡 (UICC) 所有者的应用相关，则可以向 API 授予特殊权限。Android 平台会加载存储在 UICC 上的证书，并向由这些证书签名的应用授予权限，允许其调用一些特殊的 API。</p> +<p>Android 7.0 针对 UICC 运营商权限规则，对该功能进行了扩展，以支持其他存储源（例如访问规则文件 (ARF)），从而大幅增加了可以使用此类 API 的运营商数量。有关 API 参考，请参阅 <a href="#carrierconfigmanager">CarrierConfigManager</a>；有关说明，请参阅<a href="/devices/tech/config/carrier.html">运营商配置</a>。</p> + +<p>由于运营商拥有对 UICC 的完全控制权，该机制不仅提供了一种安全而灵活的方式来管理移动网络运营商 (MNO) 在通用应用分发渠道（如 Google Play）上托管的应用，同时运营商还保留对设备的特殊权限，无需使用针对单个设备的平台证书对应用进行签名，也无需作为系统应用进行预安装。</p> + +<h2 id="rules_on_uicc">UICC 规则</h2> + +<p>UICC 上的存储空间需兼容 <a href="http://www.globalplatform.org/specificationsdevice.asp">GlobalPlatform 安全元件访问控制规范</a>。卡上的应用标识符 (AID) 为 <code>A00000015141434C00</code>，并使用标准 GET DATA 命令来获取存储在卡上的规则。您可以通过无线 (OTA) 更新来更新这些规则。</p> + +<h3 id="data_hierarchy">数据层次结构</h3> +<p>UICC 规则使用以下数据层次结构（括号中由字母和数字组成的二个字符组合是对象标记）。每个规则均为 REF-AR-DO (E2)，并包含 REF-DO 与 AR-DO 的连接：</p> + +<ul> + <li>REF-DO (E1) 包含一个 DeviceAppID-REF-DO 或 DeviceAppID-REF-DO 与 PKG-REF-DO 的连接。<ul> + <li>DeviceAppID-REF-DO (C1) 存储 SHA-1（20 字节）或 SHA-256（32 字节）证书签名。 + </li><li>PKG-REF-DO (CA) 是在清单中定义的完整文件包名称字符串，为 ASCII 编码，最大长度是 127 字节。 + </li></ul></li> + <li>AR-DO (E3) 已扩展为包含 PERM-AR-DO (DB)。PERM-AR-DO (DB) 是一个 8 字节的位掩码，表示 64 个独立的权限。</li> +</ul> + +<p>如果 PKG-REF-DO 不存在，则由相关证书签名的任何应用均获得访问权限；否则，证书和文件包名称需相匹配。</p> + +<h3 id="rule_example">规则示例</h3> +<p>应用名称为 <code>com.google.android.apps.myapp</code>，并且 SHA-1 证书的十六进制字符串形式为：</p> +<pre>AB:CD:92:CB:B1:56:B2:80:FA:4E:14:29:A6:EC:EE:B6:E5:C1:BF:E4</pre> + +<p>UICC 上规则的十六进制字符串形式为：</p> +<pre> +E243 <= 43 is value length in hex + E135 + C114 ABCD92CBB156B280FA4E1429A6ECEEB6E5C1BFE4 + CA1D 636F6D2E676F6F676C652E616E64726F69642E617070732E6D79617070 + E30A + DB08 0000000000000001 +</pre> + +<h2 id="arf">访问规则文件 (ARF) 支持</h2> +<p>Android 7.0 增加了对从访问规则文件 (ARF) 中读取运营商授权规则的支持。</p> +<p>Android 平台会首先尝试选择访问规则小程序 (ARA) 应用标识符 (AID) <code>A00000015141434C00</code>。如果在通用集成电路卡 (UICC) 上找不到 AID，则 Android 会通过选择 PKCS15 AID <code>A000000063504B43532D3135</code> 回退到 ARF。然后，Android 会读取 <code>0x4300</code> 处的访问控制规则文件 (ACRF)，并查找具有 AID <code>FFFFFFFFFFFF</code> 的条目。具有不同 AID 的条目将被忽略，从而确保其他用例的规则可以同时存在。</p> +<p>十六进制字符串形式的 ACRF 内容示例：</p> +<pre>30 10 A0 08 04 06 FF FF FF FF FF FF 30 04 04 02 43 10</pre> + +<p>访问控制条件文件 (ACCF) 内容示例：</p> +<pre>30 16 04 14 61 ED 37 7E 85 D3 86 A8 DF EE 6B 86 4B D8 5B 0B FA A5 AF 81 +</pre> + +<p>在上述示例中，<code>0x4310</code> 是 ACCF 的地址，该地址包含证书哈希值 <code>61:ED:37:7E:85:D3:86:A8:DF:EE:6B:86:4B:D8:5B:0B:FA:A5:AF:81</code>。由此证书签名的应用获得了运营商权限。</p> + +<h2 id="enabled_apis">已启用的 API</h2> + +<p>Android 支持以下 API。</p> + +<h3 id="telephonymanager">TelephonyManager</h3> + +<ul> +<li>允许运营商应用向 UICC 请求挑战/响应的 API：<a href="https://developer.android.com/reference/android/telephony/TelephonyManager.html#getIccAuthentication(int,%20int,%20java.lang.String)"><code>getIccAuthentication</code></a>。 +</li> + +<li>用于检查发起呼叫的应用是否获得运营商权限的 API：<a href="http://developer.android.com/reference/android/telephony/TelephonyManager.html#hasCarrierPrivileges()"><code>hasCarrierPrivileges</code></a>。 +</li> + +<li>用于覆盖品牌和号码的 API：<ul> + <li><code>setOperatorBrandOverride</code></li> + <li><code>setLine1NumberForDisplay</code></li> + <li><code>setVoiceMailNumber</code></li> +</ul></li> + +<li>用于进行直接 UICC 通信的 API：<ul> + <li><code>iccOpenLogicalChannel</code></li> + <li><code>iccCloseLogicalChannel</code></li> + <li><code>iccExchangeSimIO</code></li> + <li><code>iccTransmitApduLogicalChannel</code></li> + <li><code>iccTransmitApduBasicChannel</code></li> + <li><code>sendEnvelopeWithStatus</code></li> +</ul></li> + +<li>将设备模式设置为全局的 API：<code>setPreferredNetworkTypeToGlobal</code>。</li> +</ul> + +<h3 id="smsmanager">SmsManager</h3> + +<p>允许调用的应用创建新的传入短信的 API：<code>injectSmsPdu</code>。</p> + +<h3 id="carrierconfigmanager">CarrierConfigManager</h3> + +<p>用于通知配置已更改的 API：<code>notifyConfigChangedForSubId</code>。有关说明，请参阅<a href="/devices/tech/config/carrier.html">运营商配置</a>。 +</p> + +<h3 id="carriermessagingservice">CarrierMessagingService</h3> + +<p>当用户发送或接收新的短信和彩信时接收系统调用的服务。要扩展此类，请在您的清单文件中通过 <code>android.Manifest.permission#BIND_CARRIER_MESSAGING_SERVICE</code> 权限声明该服务，并附带一个包含 <code>#SERVICE_INTERFACE</code> 操作的 Intent 过滤器。API 包括：</p> +<ul> + <li><code>onFilterSms</code></li> + <li><code>onSendTextSms</code></li> + <li><code>onSendDataSms</code></li> + <li><code>onSendMultipartTextSms</code></li> + <li><code>onSendMms</code></li> + <li><code>onDownloadMms</code></li> +</ul> + +<h3 id="telephonyprovider">TelephonyProvider</h3> + +<p>允许对电话数据库进行修改（插入、删除、更新和查询）的内容提供程序 API。字段值在 <a href="https://developer.android.com/reference/android/provider/Telephony.Carriers.html"><code>Telephony.Carriers</code></a> 中进行定义；要了解更多详情，请参阅 developer.android.com 上的 <a href="https://developer.android.com/reference/android/provider/Telephony.html">Telephony</a> API 参考资料。</p> + +<h2 id="android_platform">Android 平台 </h2> + +<p>Android 平台会在检测到的 UICC 上构建内部 UICC 对象，该对象将运营商权限规则作为 UICC 的一部分包含在内。<a href="https://android.googlesource.com/platform/frameworks/opt/telephony/+/master/src/java/com/android/internal/telephony/uicc/UiccCarrierPrivilegeRules.java"><code>UiccCarrierPrivilegeRules.java</code></a> 会加载规则、在 UICC 卡上对规则进行解析，并将它们缓存在内存中。如果需要进行权限检查，<code>UiccCarrierPrivilegeRules</code> 会将来电者证书与其自身的规则逐一对比。如果 UICC 被移除，规则会连同 UICC 对象一起被销毁。</p> + +<h2 id="validation">验证</h2> +<p>Android 7.0 CTS 包括针对 <code>CtsCarrierApiTestCases.apk</code> 中的运营商 API 的测试。由于此功能取决于 UICC 上的证书，因此您必须准备 UICC 以通过这些测试。</p> + +<h3 id="prepare_uicc">准备 UICC</h3> +<p>默认情况下，<code>CtsCarrierApiTestCases.apk</code> 由 Android 开发者密钥进行签名，其哈希值为 <code>61:ED:37:7E:85:D3:86:A8:DF:EE:6B:86:4B:D8:5B:0B:FA:A5:AF:81</code>。如果 UICC 上的证书不匹配，那么测试也会输出预期的证书哈希值。</p> +<p>输出示例：</p> +<pre> +junit.framework.AssertionFailedError: This test requires a SIM card with carrier privilege rule on it. +Cert hash: 61ed377e85d386a8dfee6b864bd85b0bfaa5af81 +</pre> + +<p>要使用 <code>CtsCarrierApiTestCases.apk</code> 验证借助 CTS 的实现，您必须先获得一个开发者 UICC，且该 UICC 应具备正确的 UICC 规则或 ARF 支持。您可以要求您选择的 SIM 卡供应商为您准备一个开发者 UICC，且该 UICC 具有如本节所述的正确 ARF，然后使用该 UICC 运行测试。UICC 不需要有效移动网络服务来通过 CTS 测试。</p> + +<h3 id="run_tests">运行测试</h3> +<p>为方便起见，Android 7.0 CTS 支持用来限制测试仅在配置了相同令牌的设备上运行的设备令牌。运营商 API CTS 测试支持设备令牌 <code>sim-card-with-certs</code>。例如，下面的设备令牌限制运营商 API 测试仅在 <code>abcd1234</code> 设备上运行：</p> +<pre>cts-tradefed run cts --device-token abcd1234:sim-card-with-certs</pre> + +<p>如果在不使用设备令牌的情况下运行测试，则测试将在所有设备上运行。</p> + +<h2 id="faq">常见问题解答</h2> + +<p><strong>如何在 UICC 上更新证书？</strong></p> + +<p><em>答：使用现有的卡 OTA 更新机制。</em></p> + +<p><strong>该规则是否可以与其他规则共存？</strong></p> + +<p><em>答：在 UICC 上可以出现具有相同 AID 的其他安全规则；Android 平台会自动过滤掉这些规则。</em></p> + +<p><strong>对于依赖 UICC 上的证书的应用，移除 UICC 会发生什么情况？</strong></p> + +<p><em>答：该应用将失去其权限，因为与 UICC 关联的规则会随 UICC 的移除而被销毁。</em></p> + +<p><strong>UICC 上的证书数量是否有限制？</strong> +</p> + +<p><em>答：Android 平台不限制证书数量，但是由于检查过程是线性的，因此规则太多可能会造成检查延迟。</em></p> + +<p><strong>我们通过该方法可以支持的 API 数量是否有限制？ +</strong></p> + +<p><em>答：没有限制，但我们规定 API 必须与运营商相关。</em></p> + +<p><strong>有些 API 是否被禁止使用该方法？如果是，你们是如何执行禁用规则的？（例如，是否有测试可以验证哪些 API 适用该方法？）</strong></p> + +<p><em>答：请参阅 <a href="/compatibility/cdd.html">Android 兼容性定义文档 (CDD)</a> 的“API 行为兼容性”部分。我们有一些 CTS 测试可以确保 API 的权限模式保持不变。</em></p> + +<p><strong>UICC 如何使用多 SIM 卡功能？</strong></p> + +<p><em>答：它会使用用户设置的默认 SIM 卡。</em></p> + +<p><strong>UICC 是否会与其他 SE 访问技术（例如 SEEK）交互或重叠？</strong></p> +<p><em>答：举例来说，SEEK 使用 UICC 上的同一 AID。因此，规则可以共存，并由 SEEK 或 UiccCarrierPrivileges 进行过滤。</em></p> + +<p><strong>何时适合检查运营商权限？</strong></p> +<p><em>答：在 SIM 卡状态加载广播后。</em></p> + +<p><strong>OEM 能否禁用部分运营商 API？</strong></p> + +<p><em>答：不能。我们认为目前的 API 集合已是最小的集合，未来，我们计划使用位掩码来实现更精细的粒度控制。</em></p> + +<p><strong>setOperatorBrandOverride 是否会覆盖所有其他形式的运营商名称字符串？例如 SE13、UICC SPN 和基于网络的 NITZ 等。</strong> +</p> + +<p><em>答：请参阅 <a href="http://developer.android.com/reference/android/telephony/TelephonyManager.html">TelephonyManager</a> 中的 SPN 条目 +</em></p> + +<p><strong>injectSmsPdu 方法调用的作用是什么？</strong></p> + +<p><em>答：该方法调用有助于将短信备份到云端或从云端恢复短信。injectSmsPdu 调用会启用恢复功能。</em></p> + +<p><strong>对于短信过滤，onFilterSms 调用是否基于短信 UDH 端口过滤？或者，运营商应用是否有权访问所有的传入短信？</strong></p> + +<p><em>答：运营商有权访问所有短信数据。</em></p> + +<p><strong>DeviceAppID-REF-DO 经扩展可支持 32 字节，这似乎与当前的 GP 规范（仅允许 0 或 20 字节）不兼容，你们为什么要做出这一更改？你们是否认为 SHA-1 不足以避免冲突？你们是否已向 GP 提出此更改建议，因为该规则可能无法向后兼容现有的 ARA-M/ARF？</strong></p> + +<p><em>答：为了提供能够满足未来需求的安全性，除了 SHA-1 之外，此项扩展还针对 DeviceAppID-REF-DO 引入 SHA-256，而目前 SHA-1 是 GP SEAC 标准中的唯一选项。因此我们强烈推荐使用 SHA-256。</em></p> + +<p><strong>如果 DeviceAppID 为 0（空），你们是否会真的将该规则应用于特定规则未涵盖的所有设备应用？</strong></p> + +<p><em>答：运营商 API 要求 deviceappid-ref-do 不为空。为空仅供满足测试用途，因此我们不建议在操作部署时留空。 +</em></p> + +<p><strong>根据你们的技术规范，在没有 DeviceAppID-REF-DO 的情况下，不得单独使用 PKG-REF-DO。但是在表 6-4 中，你们仍然扩展了 REF-DO 的定义。你们是否有意这样描述？如果在 REF-DO 中仅使用 PKG-REF-DO，代码会出现什么样的行为？</strong></p> + +<p><em>答：在最新版本中，我们移除了在 REF-DO 中将 PKG-REF-DO 作为单个值项的选项。PKG-REF-DO 只能与 DeviceAppID-REF-DO 一起使用。</em></p> + +<p><strong>假设我们可以授予所有基于运营商的权限，或者可以进行更精细的控制。那么可以用什么来定义位掩码和实际权限之间的映射？每个类一个权限？具体到每种方法一个权限？从长远来看，64 个独立权限是否足够？ +</strong></p> + +<p><em>答：这是留作将来使用。此外，欢迎向我们提出建议。</em></p> + +<p><strong>你们能否进一步具体地定义 DeviceAppID（Android 版）？由于这是发布者证书的 SHA-1（20 字节）哈希值，而发布者证书是用来为给定应用签名，因此该名称是否应该反映其用途？（该名称可能会让许多读者感到困惑，因为该规则将适用于使用这一发布者证书签名的所有应用。）</strong></p> + +<p><em>答：deviceAppID 存储证书已获得现有规范的支持。我们会尽量减少对规范的更改，以降低采用规范存在的障碍。有关详情，请参阅 <a href="#rules_on_uicc">UICC 规则</a>。</em></p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/config/voicemail.html b/zh-cn/devices/tech/config/voicemail.html new file mode 100644 index 00000000..6d97c2f2 --- /dev/null +++ b/zh-cn/devices/tech/config/voicemail.html @@ -0,0 +1,144 @@ +<html devsite><head> + <title>可视化语音信箱</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 6.0 (Marshmallow) 实现了集成到拨号器的可视化语音信箱 (VVM) 支持，从而使兼容的运营商 VVM 服务能够通过最少的配置接入拨号器。通过可视化语音信箱，用户无需拨号便可轻松查收语音邮件。用户可以在类似于收件箱的界面中查看邮件列表，按任何顺序收听邮件，并可根据需要删除邮件。</p> + +<p>Android 7.0 已将下列配置参数添加到可视化语音信箱： +</p><ul> + <li>通过 <code>KEY_VVM_PREFETCH_BOOLEAN</code> 来控制语音邮件的预取 + </li><li>通过 <code>KEY_VVM_CELLULAR_DATA_REQUIRED_BOOLEAN</code> 来控制是否需要移动数据网络连接 + </li><li>语音邮件转录内容的提取 + </li><li>语音信箱配额的提取 +</li></ul> + +<p>本文概述了可视化语音信箱的功能、运营商与之进行集成的方式，以及实现方面的一些相关细节。</p> + +<h2 id="visual_voicemail_vvm_client">可视化语音信箱 (VVM) 客户端</h2> + +<p>Android 6.0 及更高版本中包含一个 OMTP VVM 客户端。如果配置正确的话，该客户端将连接到运营商的 VVM 服务器，并在 Android 开放源代码项目 (AOSP) 拨号器中填入可视化语音邮件。VVM 客户端会执行以下操作：</p> + +<ul> + <li>处理用于激活/停用/查询服务状态的短信，以及处理用于将订阅者邮箱中的事件通知设备的短信 + </li><li>将信箱与 IMAP 服务器同步 + </li><li>当用户选择收听语音邮件时下载这类邮件 + </li><li>提取语音邮件转录内容 + </li><li>提取语音信箱配额的详细信息（信箱总容量和占用容量） + </li><li>集成到拨号器以实现用户功能（例如：回拨、查看未读邮件、删除邮件等） +</li></ul> + +<h2 id="integrate_with_the_vvm_client">与 VVM 客户端进行集成</h2> + +<h3 id="implementation">实现</h3> + +<p>运营商必须提供实施 <a href="http://www.gsma.com/newsroom/wp-content/uploads/2012/07/OMTP_VVM_Specification_1_3.pdf">OMTP VVM 规范</a>的可视化语音信箱服务器。AOSP VVM 客户端当前的实现支持核心功能（读取/删除语音邮件、下载/同步/收听语音邮件），但没有实现其他的 TUI 功能（密码更改、语音邮件问候语、语言）。目前，我们仅支持 OMTP 版本 1.1，并且没有对 IMAP 身份验证使用加密。</p> + +<p>为了支持转录，运营商必须支持 OMTP 1.3 规范第 2.1.3 项所规定的转录附件格式（MIME 类型 plain/text）。</p> + +<p class="note"><strong>注意</strong>：服务器发送到设备的短信（例如：STATUS 或 SYNC）必须为数据短信。</p> + +<h3 id="configuration">配置</h3> + +<p>为了让运营商能与 VVM 服务进行集成，运营商必须向 OMTP 客户端可以使用的平台提供配置详情。这些参数包括：</p> + +<ul> + <li>短信的目标号码和端口号 + </li><li>运营商提供的可视化语音信箱应用的软件包名称（如有提供），以便在安装该软件包后，可以停用平台实现 +</li></ul> + +<p>这些值通过 <a href="https://developer.android.com/reference/android/telephony/CarrierConfigManager.html">Carrier Config API</a> 提供。利用在 Android 6.0 中推出的这项功能，应用可以动态地将与电话相关的配置提供给需要该配置的各种平台组件。尤其需要注意的是，以下密钥必须定义值：</p> + +<ul> + <li><code>KEY_VVM_DESTINATION_NUMBER_STRING</code> + </li><li><code>KEY_VVM_PORT_NUMBER_INT</code> + </li><li><code>KEY_VVM_TYPE_STRING</code> + </li><li><code>KEY_CARRIER_VVM_PACKAGE_NAME_STRING</code> + </li><li><code>KEY_VVM_PREFETCH_BOOLEAN</code> + </li><li><code>KEY_VVM_CELLULAR_DATA_REQUIRED_BOOLEAN</code> +</li></ul> + +<p>有关详细信息，请参阅<a href="/devices/tech/config/carrier.html">运营商配置</a>一文。</p> + +<h2 id="implementation">实现</h2> + +<p>OMTP VVM 客户端是在 <code>packages/services/Telephony</code> 中实现，尤其是 <code>src/com/android/phone/vvm/</code> 内</p> + +<h3 id="setup">设置</h3> + +<ol> + <li>VVM 客户端监听 <code>TelephonyIntents#ACTION_SIM_STATE_CHANGED</code> 或 <code>CarrierConfigManager#ACTION_CARRIER_CONFIG_CHANGED</code>。 + </li><li>当添加了具有合适的运营商配置值（<code>KEY_VVM_TYPE_STRING</code> 设置为 <code>TelephonyManager.VVM_TYPE_OMTP</code> 或 <code>TelephonyManager.VVM_TYPE_CVVM</code>）的 SIM 卡后，VVM 客户端向 <code>KEY_VVM_DESTINATION_NUMBER_STRING</code> 中指定的值发送 ACTIVATE 短信。 + </li><li>服务器激活可视化语音信箱服务，并通过 STATUS 短信发送 OMTP 凭据。当 VVM 客户端收到 STATUS 短信后，就会注册语音邮件来源，并在设备上显示语音信箱标签。 + </li><li>OMTP 凭据保存到本地，并且设备开始进行完全同步（如下所述）。 +</li></ol> + +<h3 id="syncing">同步</h3> + +<p>VVM 客户端可以通过多种方式与运营商服务器进行同步，反之亦然。</p> + +<ul> + <li>初次下载时会触发<strong>完全同步</strong>。VVM 客户端提取语音信箱的元数据，例如日期和时间、发件号码、时长、语音邮件转录内容（如果有）以及音频数据（如果 <code>KEY_VVM_PREFETCH_BOOLEAN</code> 为 True）。完全同步可由以下操作触发： + <ul> + <li>插入新的 SIM 卡 + </li><li>重启设备 + </li><li>重新使用服务 + </li><li>接收 <code>VoicemailContract.ACTION_SYNC_VOICEMAIL</code> 广播 + </li></ul> + </li><li>当用户与语音邮箱进行互动以读取或删除语音邮件时，就会触发<strong>上传同步</strong>。上传同步会导致服务器更改其数据来匹配设备上的数据。例如，如果用户查看语音邮件，则相应邮件会在服务器中标为已读；如果用户删除语音邮件，则相应邮件会从服务器中删除。 + </li><li>当 VVM 客户端收到来自运营商的“MBU”（信箱更新）SYNC 短信时，就会触发<strong>下载同步</strong>。SYNC 短信包含新邮件的元数据，以便该邮件可以存储在语音信箱内容提供程序中。 +</li></ul> + +<p class="note"><strong>注意</strong>：每次同步时，系统都会对语音信箱收件箱配额值进行检索。</p> + +<h3 id="voicemail_download">语音邮件下载</h3> + +<p>当用户按下“播放”来收听语音邮件时，相应的音频文件便会被下载下来。如果用户选择收听语音邮件，拨号器便可以广播语音信箱客户端将会收到的 <code>VoicemailContract.ACTION_FETCH_VOICEMAIL</code>、开始下载内容并更新平台语音信箱内容提供程序中录制的内容。</p> + +<h3 id="disabling_vvm">停用 VVM</h3> + +<p>用户互动、取出有效 SIM 卡或者被运营商 VVM 应用所取代都会导致 VVM 服务遭到停用或禁用。<em></em>“停用”表示本地设备不再显示可视化语音邮件。<em></em>“禁用”则意味着为订阅者关闭该服务。用户互动会禁用服务，取出 SIM 卡会暂时停用服务（因为该服务已不再存在），而被运营商 VVM 所取代则会停用 AOSP VVM 客户端。</p> + +<h4 id="user_interaction">用户互动</h4> + +<p>用户可以手动启用或停用可视化语音信箱。如果用户停用可视化语音信箱，会同时禁用相应服务。当用户停用可视化语音信箱时，系统会发送 DEACTIVATE 短信，在本地取消注册语音信箱来源，并且语音信箱标签将会消失。如果用户重新启用可视化语音信箱，相应的服务也将重新激活。</p> + +<h4 id="sim_removal">取出 SIM 卡</h4> + +<p>如果设备的 SIM 卡状态 (<code>ACTION_SIM_STATE_CHANGED</code>) 或运营商配置值 (<code>ACTION_CARRIER_CONFIG_CHANGED</code>) 发生变化，并且给定 SIM 卡的有效配置不再存在，那么语音邮箱来源会在本地取消注册，而且语音信箱标签也会消失。如果更换 SIM 卡，VVM 将被重新启用。</p> + +<h4 id="replaced_by_carrier_vvm">被运营商 VVM 所取代</h4> + +<p>运营商可视化语音信箱应用（如果已安装在设备上）可以停用 AOSP VVM 客户端。这可通过检查是否安装了名称与 <code>KEY_CARRIER_VVM_PACKAGE_NAME_STRING</code> 参数相符的软件包来实现。</p> + +<p>VVM 客户端仍可通过用户互动来启用。</p> + +<h2 id="testing">测试</h2> + +<p>自 Android 4.0 以来，就有一组现有的 CTS 测试用于 VoicemailProvider API。借助 VoicemailProvider API，应用可以在平台中插入/查询/删除语音邮件。这些 API 与 VVM 用来添加/删除语音邮件的 API 相同，这样一来，任何拨号器应用都可以在界面中显示这些语音邮件。</p> + +<p>要测试您的配置应用是否在正确地传递 OMTP 配置，您可以使用以下工具来测试代码：</p> + +<ul> + <li>包含有效证书签名的 SIM 卡 + </li><li>运行 Android 6.0 且具备未修改版 AOSP 手机框架的设备 +</li></ul> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/connect/block-numbers.html b/zh-cn/devices/tech/connect/block-numbers.html new file mode 100644 index 00000000..991cbb0a --- /dev/null +++ b/zh-cn/devices/tech/connect/block-numbers.html @@ -0,0 +1,184 @@ +<html devsite><head> + <title>实现电话号码屏蔽功能</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 用户需要能够轻松屏蔽骚扰电话和短信。 +</p> + +<p> +在 Android N 推出之前，Android 用户只能依靠下载的应用来限制来自骚扰电话号码的来电和短信。但是，由于没有适当的 API 来屏蔽来电和短信，这些应用大部分要么达不到预期效果，要么用户体验不佳。 +</p> + +<p> +一些制造商可能会提供他们自己的开箱即用型屏蔽解决方案，但是如果用户更换设备，由于缺乏互用性，他们的屏蔽列表可能会完全丢失。最后，即便用户采用了提供此类功能的拨号应用和短信客户端，他们可能仍需在每个应用中执行屏蔽操作，才能有效屏蔽来电和短信。 +</p> + +<h2 id="features">功能</h2> + +<p> +Android 7.0 版本引入了 <code>BlockedNumberProvider</code> 内容提供程序，该程序可以存储用户指定的无法通过电话通讯（通话、短信、彩信）与他们联系的电话号码列表。系统会参考屏蔽列表中的号码，限制来自这些号码的来电和短信。Android 7.0 不仅会显示屏蔽号码列表，还可让用户添加和删除号码。 +</p> + +<p> +此外，借助号码屏蔽功能，系统能够与平台上的相关应用协同工作，有助于保护用户并为用户提供便捷体验。默认拨号器、默认短信客户端、UICC 授权应用以及与系统具有相同签名的应用都可以直接对屏蔽列表执行读写操作。由于屏蔽号码存储在系统中，无论用户使用哪种拨号或短信应用，这些号码始终会被屏蔽。最后，用户可在任何制造商的任何新设备中恢复屏蔽号码列表。 +</p> + +<ul> +<li>确保用户可以使用开箱即用的屏蔽功能，并且在切换应用或更换新手机时不会丢失屏蔽列表。系统中所有相关应用均可共享同一个列表，为用户提供最流畅的体验。 +</li><li>应用开发者无需自行开发功能来管理屏蔽列表、来电和短信。他们只需使用平台提供的功能即可。 +</li><li>用户选择的默认拨号器/短信应用可以直接对提供程序执行读写操作。其他应用可以使用 <code>createManageBlockedNumbersIntent()</code> 启动屏蔽列表管理界面。 +</li><li>原始设备制造商 (OEM) 可以利用平台提供的功能来实现开箱即用型屏蔽功能。OEM 可以放心，当用户从其他 OEM 的设备切换到当前设备时，他们将拥有更好的入门体验，因为屏蔽列表也将转移到当前设备。 +</li><li>如果运营商有自己的拨号器或即时通讯应用，他们可以重复使用平台功能，从而让用户继续使用屏蔽列表。他们可以放心，即使用户使用新设备，在新设备中仍可使用屏蔽列表。最后，所有运营商授权应用都可以读取该屏蔽列表，因此，如果运营商希望基于该屏蔽列表向用户提供更强大的额外屏蔽功能，那么现在他们可以基于此功能来实现。</li></ul> + +<h2 id="data-flow">数据流</h2> + +<img src="images/block-numbers-flow.png" alt="屏蔽号码数据流" id="block-numbers-flow"/> +<p class="img-caption"> + <strong>图 1.</strong> 屏蔽电话号码数据流</p> + +<h2 id="examples-and-source">示例和源代码</h2> + +<p> +以下是使用号码屏蔽新功能的调用示例： +</p> + +<h3 id="launch-from-app">从应用启动屏蔽号码管理程序</h3> + +<pre> +Context.startActivity(telecomManager.createManageBlockedNumbersIntent(), null); +</pre> + +<h3 id="query-blocked-numbers">查询屏蔽号码</h3> + +<pre> +Cursor c = getContentResolver().query(BlockedNumbers.CONTENT_URI, + new String[]{BlockedNumbers.COLUMN_ID, + BlockedNumbers.COLUMN_ORIGINAL_NUMBER, + BlockedNumbers.COLUMN_E164_NUMBER}, null, null, null); +</pre> + +<h3 id="put-blocked-number">添加屏蔽号码</h3> + +<pre> +ContentValues values = new ContentValues(); +values.put(BlockedNumbers.COLUMN_ORIGINAL_NUMBER, "1234567890"); +Uri uri = getContentResolver().insert(BlockedNumbers.CONTENT_URI, values); +</pre> + +<h3 id="delete-blocked-number">删除屏蔽号码</h3> + +<pre> +ContentValues values = new ContentValues(); +values.put(BlockedNumbers.COLUMN_ORIGINAL_NUMBER, "1234567890"); +Uri uri = getContentResolver().insert(BlockedNumbers.CONTENT_URI, values); +getContentResolver().delete(uri, null, null); +</pre> + +<h2 id="implementation">实现</h2> + +<p> +以下是使用号码屏蔽功能前必须完成的高级任务： +</p> + +<ul> +<li>OEM 通过使用 <code>BlockedNumberProvider</code> 在其设备上实现呼叫/短信限制功能 +</li><li>如果运营商有拨号器或即时通讯应用，请使用 <code>BlockedNumberProvider</code> 实现呼叫/短信限制功能 +</li><li>第三方拨号器和即时通讯应用供应商使用 <code>BlockedNumberProvider</code> 实现屏蔽功能</li> +</ul> + +<h3 id="recommendations-for-oems">面向 OEM 的建议</h3> + +<p> +如果设备之前从未配备任何其他呼叫/短信限制功能，请在所有此类设备上使用 Android 开源项目 (AOSP) 中的号码屏蔽功能。建议支持合理的屏蔽入口点，如从通话记录中或短信会话中屏蔽号码。 +</p> + +<p> +如果设备之前配备了呼叫/短信限制功能，请调整该功能，以便所有严格匹配的屏蔽电话号码都存储在 <code>BlockedNumberProvider,</code> 中，并且围绕提供程序的行为满足 Android 兼容性定义文档 (CDD) 中针对此功能的要求。<em></em> +</p> + +<p> +只要满足 CDD 中有关屏蔽严格匹配的电话号码的要求，便可以通过自定义提供程序和自定义界面/控件来实现其他高级功能。建议将其他功能标记为“高级”功能，以避免与基本号码屏蔽功能相混淆。 +</p> + +<h3 id="apis">API</h3> + +<p>以下是使用的 API：</p> +<ul> +<li><code><a href="http://developer.android.com/reference/android/telecom/TelecomManager.html">TelecomManager</a> +API</code> + <ul> + <li><code>Intent createManageBlockedNumbersIntent()</code> + </li></ul> +</li> +<li><code><a href="http://developer.android.com/reference/android/telephony/CarrierConfigManager.html">Carrier +Config</a></code> + <ul> + <li><code>KEY_DURATION_BLOCKING_DISABLED_AFTER_EMERGENCY_INT</code> + </li></ul> +</li> +<li>请参考 <code>BlockedNumberContract</code> + <ul> + <li>由 <code><a href="https://developer.android.com/reference/android/provider/BlockedNumberContract.html">BlockedNumberContract</a></code> 提供的 API</li> + <li><code>boolean isBlocked(Context context, String phoneNumber)</code></li> + <li><code>int unblock(Context context, String phoneNumber)</code></li> + <li><code>boolean canCurrentUserBlockNumbers(Context context)</code></li> + </ul> + </li> +</ul> + +<h3 id="user-interface">界面</h3> +<p> +AOSP 中提供的 BlockedNumbersActivity.java 界面可以按原样使用。只要符合相关 CDD 要求，设备实现人员也可以实现自己的界面版本。 +</p> + +<p> +请注意，要使用 <code>BlockedNumberProvider</code> 来实现屏蔽列表恢复功能，可能需要合作伙伴的 PC 备份和恢复应用。有关 AOSP 中提供的屏蔽号码界面，请参见下图。 +</p> + +<img src="images/block-numbers-ui.png" alt="屏蔽号码界面" width="665" id="block-numbers-ui"/> +<p class="img-caption"> + <strong>图 2.</strong> 屏蔽电话号码界面</p> + +<h2 id="validation">验证</h2> + +<p> +实现人员可以通过运行以下 CTS 测试来确保其功能版本能够按预期运转： +</p> + +<pre> +android.provider.cts.BlockedNumberContractTest +com.android.cts.numberblocking.hostside.NumberBlockingTest +android.telecom.cts.ExtendedInCallServiceTest#testIncomingCallFromBlockedNumber_IsRejected +android.telephony.cts.SmsManagerTest#testSmsBlocking +</pre> + +<p> +在运行 <code>$ adb root</code> 之后，可以使用 <code>adb</code> 命令来操作 <code>BlockedNumberProvider</code>。例如： +</p> +<pre> +$ adb root +$ adb shell content query --uri content://com.android.blockednumber/blocked +$ adb shell content insert --uri / content://com.android.blockednumber/blocked --bind / original_number:s:'6501002000' +$ adb shell content delete --uri / content://com.android.blockednumber/blocked/1 +</pre> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/connect/data-saver.html b/zh-cn/devices/tech/connect/data-saver.html new file mode 100644 index 00000000..9ae8253c --- /dev/null +++ b/zh-cn/devices/tech/connect/data-saver.html @@ -0,0 +1,107 @@ +<html devsite><head> + <title>流量节省程序模式</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 用户迫切希望能够降低应用的数据使用量，或完全阻止应用使用数据流量。Android 7.0 版本中的流量节省程序为用户提供了这项功能。 +</p> + +<p> +<a href="https://developer.android.com/preview/features/data-saver.html">流量节省程序</a>功能可由用户开启或关闭。应用开发者应使用新的 API 来检查流量节省程序模式是否已开启。如果已开启，则应用开发者可以微调其应用以实现低数据或无数据访问，从而妥善应对这种情况。 +</p> + +<p> +这项功能为最终用户带来极大的好处，因为他们将能够决定哪些应用可以在后台访问数据，而哪些应用只能在前台访问数据。这样就可以确保在流量节省程序处于开启状态时（根据用户设置），实现所需的后台数据交换。 +</p> + +<h2 id="implementation">实现</h2> + +<p> +由于流量节省程序是平台中的一项功能，因此在默认情况下，设备制造商可在 N 版本中获得相关功能。 +</p> + +<h3 id="settings-interface">设置界面</h3> + +<p>Android 开放源代码项目 (AOSP) 中提供了默认的“流量节省程序设置”用户界面。有关示例，请查看以下屏幕截图。 +</p> + +<p>这些屏幕截图显示了使用中的流量节省程序模式。 +</p> + +<img src="images/data-saver-use.png" width="397" alt="关闭/开启流量节省程序"/> +<p class="img-caption"> + <strong>图 1.</strong> 关闭/打开流量节省程序</p> + +<img src="images/data-battery-saver.png" width="641" alt="省电模式和流量节省程序同时开启"/> +<p class="img-caption"> + <strong>图 2.</strong> 省电模式和流量节省程序同时开启</p> + +<img src="images/data-saver-app.png" width="376" alt="特定应用流量使用情况屏幕"/> +<p class="img-caption"> + <strong>图 3.</strong> 特定应用流量使用情况屏幕：“设置”>“应用”>“流量使用情况”</p> + +<img src="images/data-saver-quick-settings.png" width="446" alt="“快捷设置”中的流量节省程序"/> +<p class="img-caption"> + <strong>图 4.</strong> “快捷设置”菜单中的流量节省程序状态</p> + +<h3 id="apps">应用</h3> + +<p class="caution"><strong>重要提示</strong>：设备实现人员不得将应用列入白名单。即使他们这样做，用户也可以移除这类应用。如果在设备中加入了其他应用，则可能会迫使用户决定针对这些应用使用流量节省程序。</p> + +<p>所有应用开发者（包括使用预加载应用的原始设备制造商 (OEM) 和运营商）都必须采取相应措施来实现流量节省程序。请参阅 <a href="https://developer.android.com/preview/features/data-saver.html">developer.android.com 上的流量节省程序</a>，了解有关检测和监控流量节省程序状态的应用开发者说明。合作伙伴可参阅下文以获得更多实用信息。</p> + +<p> +要优化流量节省程序模式，应用需要满足以下几点： +</p> + +<ul> + <li>移除不必要的图片 + </li><li>针对剩余图片使用低分辨率 + </li><li>使用低比特率视频 + </li><li>触发现有的“精简”体验 + </li><li>压缩数据 + </li><li>留意按流量计费/不按流量计费网络的状态（即使流量节省程序已关闭）。</li></ul> + +<p>另外，要实现与流量节省程序之间的完美协作，应用不得：</p> + +<ul> + <li>自动播放视频 + </li><li>预提取内容/附件 + </li><li>下载更新/代码 + </li><li>要求列入白名单（除非实现核心功能需要使用后台数据） + </li><li>将列入白名单作为使用更多带宽的许可条件</li></ul> + +<h2 id="validation">验证</h2> + +<p>实现人员可以运行以下 CTS 测试，从而确保其功能版本能够按预期运行。</p> + +<pre> +com.android.cts.net.HostsideRestrictBackgroundNetworkTests +</pre> + +<p>此外，还可以先运行以下命令来查看所有可用选项，从而使用 <code>adb</code> 命令手动执行测试：<br /> +<code>$ adb shell cmd netpolicy</code> +</p> + +<p>例如，执行此命令可返回白名单应用的 UID：<br /> +<code>$ adb shell cmd netpolicy list restrict-background-whitelist</code> +</p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/connect/index.html b/zh-cn/devices/tech/connect/index.html new file mode 100644 index 00000000..7f7bb921 --- /dev/null +++ b/zh-cn/devices/tech/connect/index.html @@ -0,0 +1,25 @@ +<html devsite><head> + <title>确保网络连接正常</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 设备正确联网。</p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/dalvik/gc-debug.html b/zh-cn/devices/tech/dalvik/gc-debug.html new file mode 100644 index 00000000..2827db75 --- /dev/null +++ b/zh-cn/devices/tech/dalvik/gc-debug.html @@ -0,0 +1,262 @@ +<html devsite><head> + <title>调试 ART 垃圾回收</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 运行时 (ART) 垃圾回收 (GC) 的正确性和性能问题。本文档解释了如何使用 GC 验证选项、确定 GC 验证失败的解决方案，以及测量并解决 GC 性能问题。</p> + +<p>有关处理 ART 的说明，请参阅 <a href="index.html">ART 和 Dalvik</a>、<a href="dex-format.html">Dalvik 可执行格式</a>以及 <a href="index.html">ART 和 Dalvik</a> 部分的其他页面。有关验证应用行为的其他帮助信息，请参阅<a href="http://developer.android.com/guide/practices/verifying-apps-art.html">在 Android 运行时 (ART) 上验证应用行为</a>。</p> + +<h2 id="art_gc_overview">ART GC 概述</h2> + +<p>ART 是在 Android 4.4 中引入的一个开发者选项，也是 Android 5.0 及更高版本的默认 Android 运行时。我们已不再继续维护和提供 Dalvik 运行时，现在 ART 采用了其字节码格式。请注意，本节仅总结 ART 的 GC。有关其他信息，请观看在 Google I/O 2014 上进行的 <a href="https://www.google.com/events/io/io14videos/b750c8da-aebe-e311-b297-00155d5066d7">Android 运行时</a>演示。</p> + +<p>ART 有多个不同的 GC 方案，这些方案包括运行不同垃圾回收器。默认方案是 CMS（并发标记清除）方案，主要使用粘性 CMS 和部分 CMS。粘性 CMS 是 ART 的不移动分代垃圾回收器。它仅扫描堆中自上次 GC 后修改的部分，并且只能回收自上次 GC 后分配的对象。除 CMS 方案外，当应用将进程状态更改为察觉不到卡顿的进程状态（例如，后台或缓存）时，ART 将执行堆压缩。</p> + +<p>除了新的垃圾回收器之外，ART 还引入了一种基于位图的新内存分配程序，称为 RosAlloc（插槽运行分配器）。此新分配器具有分片锁，当分配规模较小时可添加线程的本地缓冲区，因而性能优于 DlMalloc。</p> + +<p>与 Dalvik 相比，ART CMS 垃圾回收计划在很多方面都有一定的改善：</p> + +<ul> + <li>与 Dalvik 相比，暂停次数从 2 次减少到 1 次。Dalvik 的第一次暂停主要是为了进行根标记，即在 ART 中进行并发标记，让线程标记自己的根，然后马上恢复运行。 + </li><li>与 Dalvik 类似，ART GC 在清除过程开始之前也会暂停 1 次。两者在这方面的主要差异在于：在此暂停期间，某些 Dalvik 阶段在 ART 中并发进行。这些阶段包括 <code>java.lang.ref.Reference</code> 处理、系统弱清除（例如，jni 弱全局等）、重新标记非线程根和卡片预清理。在 ART 暂停期间仍进行的阶段包括扫描脏卡片以及重新标记线程根，这些操作有助于缩短暂停时间。 + </li><li>相对于 Dalvik，ART GC 改进的最后一个方面是粘性 CMS 回收器增加了 GC 吞吐量。不同于普通的分代 GC，粘性 CMS 不移动。年轻对象被保存在一个分配堆栈（基本上是 <code>java.lang. Object</code> 数组）中，而非为其设置一个专用区域。这样可以避免移动所需的对象以维持低暂停次数，但缺点是容易在堆栈中加入大量复杂对象图像而使堆栈变长。 +</li></ul> + +<p>ART GC 与 Dalvik 的另一个主要区别在于 ART GC 引入了移动垃圾回收器。使用移动 GC 的目的在于通过堆压缩来减少后台应用使用的内存。目前，触发堆压缩的事件是 ActivityManager 进程状态的改变。当应用转到后台运行时，它会通知 ART 已进入不再“感知”卡顿的进程状态。此时 ART 会进行一些操作（例如，压缩和监视器压缩），从而导致应用线程长时间暂停。目前正在使用的两个移动 GC 是同构空间压缩和半空间压缩。</p> + +<ul> + <li>半空间压缩将对象在两个紧密排列的碰撞指针空间之间进行移动。这种移动 GC 适用于小内存设备，因为它可以比同构空间压缩稍微多节省一点内存。额外节省出的空间主要来自紧密排列的对象，这样可以避免 RosAlloc/DlMalloc 分配器占用开销。由于 CMS 仍在前台使用，且不能从碰撞指针空间中进行收集，因此当应用在前台使用时，半空间还要再进行一次转换。这种情况并不理想，因为它可能引起较长时间的暂停。 + </li><li>同构空间压缩通过将对象从一个 RosAlloc 空间复制到另一个 RosAlloc 空间来实现。这有助于通过减少堆碎片来减少内存使用量。这是目前非低内存设备的默认压缩模式。相比半空间压缩，同构空间压缩的主要优势在于应用从后台切换到前台时无需进行堆转换。 +</li></ul> + +<h2 id="gc_verification_and_performance_options">GC 验证和性能选项</h2> + +<p>如果您是原始设备制造商 (OEM)，就可以更改 GC 类型。要执行该操作，您需要通过 adb 修改系统属性。请记住，这些属性只能在非用户版本或 root 版本上修改。</p> + +<h3 id="changing_the_gc_type">更改 GC 类型</h3> + +<p>您可以采用多种方法来更改 ART 使用的 GC 计划。更改前台 GC 计划的主要方法是更改 <code>dalvik.vm.gctype</code> 属性或传递 <code>-Xgc:</code> 选项。您可以通过以逗号分隔的格式传递多个 GC 选项。</p> + +<p>为了导出可用 <code>-Xgc</code> 设置的完整列表，可以键入 <code>adb shell dalvikvm -help</code> 来输出各种运行时命令行选项。</p> + +<p>以下是将 GC 更改为半空间并打开 GC 前堆验证的一个示例： <code>adb shell setprop dalvik.vm.gctype SS,preverify</code></p> + +<ul> + <li><code>CMS</code> 也是默认值，指定并发标记清除 GC 计划。该计划包括运行粘性分代 CMS、部分 CMS 和完整 CMS。该计划的分配器是适用于可移动对象的 RosAlloc 和适用于不可移动对象的 DlMalloc。 + </li><li><code>SS</code> 指定半空间 GC 计划。该计划有两个适用于可移动对象的半空间和一个适用于不可移动对象的 DlMalloc 空间。可移动对象分配器默认设置为使用原子操作的共享碰撞指针分配器。但是，如果 <code>-XX:UseTLAB</code> 标记也被传入，则分配器使用线程局部碰撞指针分配。 + </li><li><code>GSS</code> 指定分代半空间计划。该计划与半空间计划非常相似，但区别在于其会将存留期较长的对象提升到大型 RosAlloc 空间中。这样就可明显减少典型用例中需复制的对象。 +</li></ul> + +<h3 id="verifying_the_heap">验证堆</h3> + +<p>堆验证可能是调试 GC 相关错误或堆损坏的最有用的 GC 选项。启用堆验证会使 GC 在垃圾回收过程中在几个点检查堆的正确性。堆验证与更改 GC 类型的选项相同。启用堆验证后，堆验证会验证根，并确保可访问对象仅引用其他可访问对象。通过传入以下 -<code>Xgc</code> 值可以启用 GC 验证：</p> + +<ul> + <li>如果启用 GC 验证，<code>[no]preverify</code> 将在 GC 启动之前执行堆验证。</li><li>如果启用 GC 验证，<code>[no]presweepingverify</code> 将在启动垃圾回收器清除过程之前执行堆验证。 + </li><li>如果启用 GC 验证，<code>[no]postverify</code> 将在 GC 完成清除后执行堆验证。 + </li><li><code>[no]preverify_rosalloc</code>、<code>[no]postsweepingverify_rosalloc</code> 和 <code>[no]postverify_rosalloc</code> 也是附加 GC 选项，仅验证 RosAlloc 内部计算的状态。验证的主要内容是，魔数值是否与预期常量匹配，以及可用内存块是否已在 <code>free_page_runs_</code> 映射中注册。 +</li></ul> + +<h3 id="using_the_tlab_allocator_option">使用 TLAB 分配器选项</h3> + +<p>目前，只有 TLAB 选项可以更改分配器而不影响活动 GC 类型。此选项不可通过系统属性使用，但可以通过将 - <code>XX:UseTLAB</code> 传递给 <code>dalvikvm</code> 来启用。该选项的分配代码路径更短，因此分配速度更快。由于此选项需要使用暂停时间相当长的 SS 或 GSS GC 类型，因此默认情况下不启用。</p> + +<h2 id="performance">性能</h2> + +<p>评测 GC 性能主要使用两种工具：GC 时间转储和 systrace。评测 GC 性能问题的最直观方法是使用 systrace 确定哪些 GC 会导致长时间暂停或抢占应用线程。尽管 ART GC 效率相对较高，但是过度分配或错误的变异器行为等都能造成性能问题。</p> + +<h3 id="ergonomics">人机工程学</h3> + +<p>与 Dalvik 相比，ART 在 GC 人机工程学方面存在一些重要差异。与 Dalvik 相比，其中一项重要改进是在我们延后启用并行 GC 时不再分配 GC。但是，此操作存在一个缺点：在某些情况下，不阻止 GC 会导致堆的增长速度比 Dalvik 快。好在 ART 具有堆压缩功能，可在进程变为后台进程状态时对堆进行碎片整理来缓解此问题。</p> + +<p>CMS GC 人机工程学有两种定期运行的 GC。理想情况下，GC 人机工程学更多时间运行的是分代粘性 CMS，而非部分 CMS。GC 将一直运行粘性 CMS，直到最后一个 GC 的吞吐量（通过释放的字节数/GC 持续秒数计算得出）小于部分 CMS 的平均吞吐量。发生此情况时，人机工程学将下一个并发 GC 计划为部分 CMS，而非粘性 CMS。部分 CMS 完成后，人机工程学将下一个 GC 更改回粘性 CMS。粘性 CMS 在完成后不会调整堆占用空间限制，这是促使人机工程学发挥作用的一个关键因素。这样，粘性 CMS 的发生频率更高，直到吞吐量低于部分 CMS，最终导致堆增大。</p> + +<h3 id="using_sigquit_to_obtain_gc_performance_info">使用 SIGQUIT 获取 GC 性能信息</h3> + +<p>通过将 SIGQUIT 发送到已运行的应用，或在启动命令行程序时通过将 -<code>XX:DumpGCPerformanceOnShutdown</code> 传递给 <code>dalvikvm</code>，可以获得应用的 GC 性能时序。当应用获得 ANR 请求信号 (SIGQUIT) 时，它将转储与锁定、线程堆栈和 GC 性能相关的信息。</p> + +<p>获取 GC 时序转储的方法是使用以下命令：<br /> +<code>$ adb shell kill -S QUIT <pid></pid></code></p> + +<p>该操作将在 <code>/data/anr/</code> 中创建一个 <code>traces.txt</code> 文件。此文件包含一些 ANR 转储信息以及 GC 时序。您可以通过搜索“转储累计 GC 时序”来确定 GC 时序。这些时序会显示一些相关内容。它会显示各 GC 类型的阶段和暂停的直方图信息。暂停信息通常比较重要。例如：</p> + +<pre> +sticky concurrent mark sweep paused: Sum: 5.491ms 99% C.I. 1.464ms-2.133ms Avg: 1.830ms Max: 2.133ms +</pre> + +<p><code>This</code> 显示暂停的平均时间为 1.83 ms。该值足够低，在大多数应用中不会导致丢帧，因此无需担心。</p> + +<p>需要关注的另一个问题是挂起时间。挂起时间测量在 GC 要求某个线程挂起后，线程到达挂起点所需的时间。该时间包含在 GC 暂停中，所以可用于确定长时间暂停是否是由 GC 缓慢或线程挂起缓慢造成。以下是 Nexus 5 上的正常挂起时间示例：</p> + +<pre> +suspend all histogram: Sum: 1.513ms 99% C.I. 3us-546.560us Avg: 47.281us Max: 601us +</pre> + +<p>还有一些其他要关注的方面，例如总耗时、GC 吞吐量等。示例如下：</p> + +<pre> +Total time spent in GC: 502.251ms +Mean GC size throughput: 92MB/s +Mean GC object throughput: 1.54702e+06 objects/s +</pre> + +<p>转储已运行应用的 GC 时序的示例如下：</p><pre> +$ adb shell kill -s QUIT <pid> +$ adb pull /data/anr/traces.txt +</pre> + +<p>此时，GC 时序包含在 trace.txt 中。Google 地图的输出示例如下：</p> + +<pre> +Start Dumping histograms for 34 iterations for sticky concurrent mark sweep +ScanGrayAllocSpaceObjects: Sum: 196.174ms 99% C.I. 0.011ms-11.615ms Avg: 1.442ms Max: 14.091ms +FreeList: Sum: 140.457ms 99% C.I. 6us-1676.749us Avg: 128.505us Max: 9886us +MarkRootsCheckpoint: Sum: 110.687ms 99% C.I. 0.056ms-9.515ms Avg: 1.627ms Max: 10.280ms +SweepArray: Sum: 78.727ms 99% C.I. 0.121ms-11.780ms Avg: 2.315ms Max: 12.744ms +ProcessMarkStack: Sum: 77.825ms 99% C.I. 1.323us-9120us Avg: 576.481us Max: 10185us +(Paused)ScanGrayObjects: Sum: 32.538ms 99% C.I. 286us-3235.500us Avg: 986us Max: 3434us +AllocSpaceClearCards: Sum: 30.592ms 99% C.I. 10us-2249.999us Avg: 224.941us Max: 4765us +MarkConcurrentRoots: Sum: 30.245ms 99% C.I. 3us-3017.999us Avg: 444.779us Max: 3774us +ReMarkRoots: Sum: 13.144ms 99% C.I. 66us-712us Avg: 386.588us Max: 712us +ScanGrayImageSpaceObjects: Sum: 13.075ms 99% C.I. 29us-2538.999us Avg: 192.279us Max: 3080us +MarkingPhase: Sum: 9.743ms 99% C.I. 170us-518us Avg: 286.558us Max: 518us +SweepSystemWeaks: Sum: 8.046ms 99% C.I. 28us-479us Avg: 236.647us Max: 479us +MarkNonThreadRoots: Sum: 5.215ms 99% C.I. 31us-698.999us Avg: 76.691us Max: 703us +ImageModUnionClearCards: Sum: 2.708ms 99% C.I. 26us-92us Avg: 39.823us Max: 92us +ScanGrayZygoteSpaceObjects: Sum: 2.488ms 99% C.I. 19us-250.499us Avg: 37.696us Max: 295us +ResetStack: Sum: 2.226ms 99% C.I. 24us-449us Avg: 65.470us Max: 452us +ZygoteModUnionClearCards: Sum: 2.124ms 99% C.I. 18us-233.999us Avg: 32.181us Max: 291us +FinishPhase: Sum: 1.881ms 99% C.I. 31us-431.999us Avg: 55.323us Max: 466us +RevokeAllThreadLocalAllocationStacks: Sum: 1.749ms 99% C.I. 8us-349us Avg: 51.441us Max: 377us +EnqueueFinalizerReferences: Sum: 1.513ms 99% C.I. 3us-201us Avg: 44.500us Max: 201us +ProcessReferences: Sum: 438us 99% C.I. 3us-212us Avg: 12.882us Max: 212us +ProcessCards: Sum: 381us 99% C.I. 4us-17us Avg: 5.602us Max: 17us +PreCleanCards: Sum: 363us 99% C.I. 8us-17us Avg: 10.676us Max: 17us +ReclaimPhase: Sum: 357us 99% C.I. 7us-91.500us Avg: 10.500us Max: 93us +(Paused)PausePhase: Sum: 312us 99% C.I. 7us-15us Avg: 9.176us Max: 15us +SwapBitmaps: Sum: 166us 99% C.I. 4us-8us Avg: 4.882us Max: 8us +(Paused)ScanGrayAllocSpaceObjects: Sum: 126us 99% C.I. 14us-112us Avg: 63us Max: 112us +MarkRoots: Sum: 121us 99% C.I. 2us-7us Avg: 3.558us Max: 7us +(Paused)ScanGrayImageSpaceObjects: Sum: 68us 99% C.I. 68us-68us Avg: 68us Max: 68us +BindBitmaps: Sum: 50us 99% C.I. 1us-3us Avg: 1.470us Max: 3us +UnBindBitmaps: Sum: 49us 99% C.I. 1us-3us Avg: 1.441us Max: 3us +SwapStacks: Sum: 47us 99% C.I. 1us-3us Avg: 1.382us Max: 3us +RecordFree: Sum: 42us 99% C.I. 1us-3us Avg: 1.235us Max: 3us +ForwardSoftReferences: Sum: 37us 99% C.I. 1us-2us Avg: 1.121us Max: 2us +InitializePhase: Sum: 36us 99% C.I. 1us-2us Avg: 1.058us Max: 2us +FindDefaultSpaceBitmap: Sum: 32us 99% C.I. 250ns-1000ns Avg: 941ns Max: 1000ns +(Paused)ProcessMarkStack: Sum: 5us 99% C.I. 250ns-3000ns Avg: 147ns Max: 3000ns +PreSweepingGcVerification: Sum: 0 99% C.I. 0ns-0ns Avg: 0ns Max: 0ns +Done Dumping histograms +sticky concurrent mark sweep paused: Sum: 63.268ms 99% C.I. 0.308ms-8.405ms +Avg: 1.860ms Max: 8.883ms +sticky concurrent mark sweep total time: 763.787ms mean time: 22.464ms +sticky concurrent mark sweep freed: 1072342 objects with total size 75MB +sticky concurrent mark sweep throughput: 1.40543e+06/s / 98MB/s +Total time spent in GC: 4.805s +Mean GC size throughput: 18MB/s +Mean GC object throughput: 330899 objects/s +Total number of allocations 2015049 +Total bytes allocated 177MB +Free memory 4MB +Free memory until GC 4MB +Free memory until OOME 425MB +Total memory 90MB +Max memory 512MB +Zygote space size 4MB +Total mutator paused time: 229.566ms +Total time waiting for GC to complete: 187.655us +</pre> + +<h2 id="tools_for_analyzing_gc_correctness_problems">分析 GC 正确性问题的工具</h2> + +<p>造成 ART 内部崩溃的原因多种多样。读取或写入对象字段时出现崩溃可能表示存在堆损坏。如果 GC 在运行时崩溃，也可能是由堆损坏造成的。造成堆损坏的原因多种多样，最常见的原因可能是应用代码错误。好在可以使用相关工具调试与 GC 和堆相关的崩溃问题。此类工具包括上面指定的堆验证选项、valgrind 和 CheckJNI。</p> + +<h3 id="checkjni">CheckJNI</h3> + +<p>验证应用行为的另一种方法是使用 CheckJNI。CheckJNI 是一种添加额外 JNI 检查的模式；出于性能考虑，这些选项在默认情况下并不会启用。此类检查将捕获一些可能导致堆损坏的错误，例如使用无效/过时的局部和全局引用。启用 CheckJNI 的方法如下：</p> + +<pre> +$ adb shell setprop dalvik.vm.checkjni true +</pre> + +<p>Forcecopy 模式是 CheckJNI 的另一部分，对检测超出数组区域末端的写入非常有用。启用后，forcecopy 会促使数组访问 JNI 函数时始终返回带有红色区域的副本。<em></em>红色区域是返回指针结束/开始处的一个区域，该区域具有特殊值，并在数组释放时得到验证。如果红色区域中的值与预期值不匹配，则通常意味着发生缓冲区溢出或欠载。这将导致 CheckJNI 中止。启用 forcecopy 模式的方法如下：</p> + +<pre> +$ adb shell setprop dalvik.vm.jniopts forcecopy +</pre> + +<p>CheckJNI 应捕获错误的一个示例是超出从 <code>GetPrimitiveArrayCritical</code> 获取的数组末端的写入。该操作很可能会破坏 Java 堆。如果写入位于 CheckJNI 红色区域内，则在调用相应 <code>ReleasePrimitiveArrayCritical</code> 时，CheckJNI 将会捕获该问题。否则，写入将最终损坏 Java 堆中的一些随机对象，并可能会导致之后出现 GC 崩溃。如果崩溃的内存是引用字段，则 GC 可能会捕获错误并输出“Tried to mark not contained by any spaces<em></em><ptr></ptr>”的错误消息。</p> + +<p>当 GC 尝试标记无法找到空间的对象时，就会发生此错误。在此检查失败后，GC 会遍历根，并尝试查看无效对象是否为根。结果共有两个选项：对象为根或非根。</p> + +<h3 id="valgrind">Valgrind</h3> + +<p>ART 堆支持可选的 valgrind 工具，这款工具提供了一种方法来检测对无效堆地址的读取和写入操作。ART 可检测应用何时在 valgrind 下运行，并在每个对象分配前后插入红色区域。如果对这些红色区域有任何读取或写入错误，valgrind 将输出错误消息。例如，如果您在通过 JNI 直接访问数组时，越过数组元素末端进行读取或写入，就会出现此类错误。由于 AOT 编译器使用隐式 null 检查，因此建议使用 eng 版本运行 valgrind。另外值得一提的是，valgrind 比正常执行速度慢一个数量级。</p> + +<p>以下是一个使用示例：</p> + +<pre> +# build and install +$ mmm external/valgrind +$ adb remount && adb sync +# disable selinux +$ adb shell setenforce 0 +$ adb shell setprop wrap.com.android.calculator2 +"TMPDIR=/data/data/com.android.calculator2 logwrapper valgrind" +# push symbols +$ adb shell mkdir /data/local/symbols +$ adb push $OUT/symbols /data/local/symbols +$ adb logcat +</pre> + +<h3 id="invalid_root_example">无效的根示例</h3> + +<p>如果对象实际上为无效根，则会输出一些有用信息： +<code>art E 5955 5955 art/runtime/gc/collector/mark_sweep.cc:383] Tried to mark 0x2 +not contained by any spaces</code></p> + +<pre> +art E 5955 5955 art/runtime/gc/collector/mark_sweep.cc:384] Attempting see if +it's a bad root +art E 5955 5955 art/runtime/gc/collector/mark_sweep.cc:485] Found invalid +root: 0x2 +art E 5955 5955 art/runtime/gc/collector/mark_sweep.cc:486] +Type=RootJavaFrame thread_id=1 location=Visiting method 'java.lang.Object +com.google.gwt.corp.collections.JavaReadableJsArray.get(int)' at dex PC 0x0002 +(native PC 0xf19609d9) vreg=1 +</pre> + +<p>在这种情况下，<code>vreg 1</code>（在 <code>com.google.gwt.corp.collections.JavaReadableJsArray.get</code> 内）应该包含一个堆引用，但实际上包含地址 <code>0x2</code> 的一个无效指针。这显然是一个无效根。要调试此问题，下一步是在 oat 文件中使用 <code>oatdump</code>，并查看具有无效根的方法。在这种情况下，结果证明错误在于 x86 后端的编译器错误。修正该错误的更改列表如下：<a href="https://android-review.googlesource.com/#/c/133932/">https://android-review.googlesource.com/#/c/133932/</a></p> + +<h3 id="corrupted_object_example">损坏的对象示例</h3> + +<p>如果对象不是根，则会输出类似于以下打印内容的消息：</p> + +<pre> +01-15 12:38:00.196 1217 1238 E art : Attempting see if it's a bad root +01-15 12:38:00.196 1217 1238 F art : +art/runtime/gc/collector/mark_sweep.cc:381] Can't mark invalid object +</pre> + +<p>当堆损坏不是无效根时，将很难进行调试。此错误消息表示堆中至少含有一个指向无效对象的对象。</p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/dalvik/instruction-formats.html b/zh-cn/devices/tech/dalvik/instruction-formats.html new file mode 100644 index 00000000..014adf51 --- /dev/null +++ b/zh-cn/devices/tech/dalvik/instruction-formats.html @@ -0,0 +1,400 @@ +<html devsite><head> + <title>Dalvik 可执行指令格式</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>本页面列出了 Dalvik 可执行格式和 Dalvik 字节码使用的指令格式。本页面需要结合<a href="dalvik-bytecode.html">字节码参考文档</a>使用。</p> + +<h2 id="bitwise">按位描述</h2> + +<p>格式表的第一列列出了格式的按位布局。它由一个或多个空格分隔的“单词”组成，每个单词描述一个 16 位代码单元。单词中的每个字符代表四位，从高位往低位读取，并使用竖线 (“<code>|</code>”) 分隔以方便阅读。从“<code>A</code>”开始的大写字母用于表示格式中的字段，这些字段随后由语法列做进一步定义。“<code>op</code>”一词用于表示格式内八位操作码的位置。带斜划的零（“<code>Ø</code>”）用于表示所有在指示位置的位必须为零。</p> + +<p>一般而言，在一个代码单元内，字母的顺序为，较早的代码单元对应的字母在前，后期的代码单元对应的字母在后，按照从低阶到高阶排序。但是，这种一般规则存在一些例外情况，主要是为了让含义相似的部分在不同的指令格式中使用相同的命名。格式说明中对这些情况进行了明确的描述。</p> + +<p>例如，“<code>B|A|<i>op</i> CCCC</code>”格式表示其包含两个 16 位代码单元。第一个单词包括低 8 位中的操作码和高 8 位中的两个四位值；第二个单词由单个 16 位值组成。</p> + +<h2 id="format-ids">格式 ID</h2> + +<p>格式表中的第二列表示格式的短标识符，用于在其他文档和代码中识别该格式。</p> + +<p>大多数格式 ID 包含三个字符：前两个是十进制数，最后一个是字母。第一个十进制数表示格式中 16 位代码单元的数量。第二个十进制数表示格式包含的最大寄存器数量（使用最大值是因为某些格式可容纳的寄存器数量为可变值），特殊标识“<code>r</code>”表示已对寄存器的数量范围进行编码。最后一个字母以半助记符的形式表示该格式编码的任何其他数据类型。例如，“<code>21t</code>”格式的长度为 2，包含一个寄存器引用，另外还有一个分支目标。</p> + +<p>建议使用的静态链接格式有一个额外的“<code>s</code>”后缀，因此加上后缀一共是四个字符。同样，建议使用的“内联”链接格式也有一个额外的“<code>i</code>”后缀。（在这种情况下，内联链接与静态链接类似，但它与机器实现具有更直接的联系。）最后，几个建议使用的奇怪格式（例如，“<code>20bc</code>”）包含两个数据块，它们均体现在格式 ID 中。</p> + +<p>类型代码字母的完整列表如下。请注意，由于格式上的差异，部分形式的大小可能有所不同：</p> + +<table class="letters"> +<thead> +<tr> + <th>助记符</th> + <th>位数</th> + <th>含义</th> +</tr> +</thead> +<tbody> +<tr> + <td>b</td> + <td>8</td> + <td>有符号立即数（<b>字节</b>）</td> +</tr> +<tr> + <td>c</td> + <td>16、32</td> + <td><b>常量</b>池索引</td> +</tr> +<tr> + <td>f</td> + <td>16</td> + <td><b>接口</b>常量（仅对静态链接格式有效）</td> +</tr> +<tr> + <td>h</td> + <td>16</td> + <td>有符号立即数<b></b>（32 位或 64 位数的高值位，低值位为 <code>0</code>） + </td> +</tr> +<tr> + <td>i</td> + <td>32</td> + <td>有符号立即数（<b>整型</b>）或 32 位浮点数</td> +</tr> +<tr> + <td>l</td> + <td>64</td> + <td>有符号立即数（<b>长整型</b>）或 64 位双精度浮点数</td> +</tr> +<tr> + <td>m</td> + <td>16</td> + <td><b>方法</b>常量（仅对静态链接格式有效）</td> +</tr> +<tr> + <td>n</td> + <td>4</td> + <td>有符号立即数（<b>半字节</b>）</td> +</tr> +<tr> + <td>s</td> + <td>16</td> + <td>有符号立即数（<b>短整型</b>）</td> +</tr> +<tr> + <td>t</td> + <td>8、16、32</td> + <td>分支<b>目标</b></td> +</tr> +<tr> + <td>x</td> + <td>0</td> + <td>无额外数据</td> +</tr> +</tbody> +</table> + +<h2 id="syntax">语法</h2> + +<p>格式表的第三列指出了指令中所使用的人类可识别的语法。每个指令以命名的操作码开始，后面可选择使用一个或多个参数，并且参数之间用逗号分隔。</p> + +<p>当参数指第一列中的某个字段时，该字段的字母将在语法中出现，并在字段中每四位重复一次。例如，第一列中标记为“<code>BB</code>”的八位字段在语法列中也将标记为“<code>BB</code>”。</p> + +<p>命名寄存器的参数形式为“<code>v<i>X</i></code>”。选择“<code>v</code>”而不是更常用的“<code>r</code>”作为前缀，这样可避免与实现 Dalvik 可执行格式的（非虚拟）架构（其寄存器使用“<code>r</code>”作为前缀）出现冲突。（也就是说，我们可以直截了当地同时讨论虚拟和实际寄存器。）</p> + +<p>表示字面值的参数的形式为“<code>#+<i>X</i></code>”。有些格式在表示字面量时，仅具有字面量的高位（无 0 位）；对于这种类型的量，仅在语法表示时会明确写出后面的 0，但是在按位描述中这些 0 会被省略。</p> + +<p>表明相对指令地址偏移量的参数形式为“<code>+<i>X</i></code>”。</p> + +<p>表示字面量常量池索引的参数形式为“<code><i>kind</i>@<i>X</i></code>”，其中“<code><i>kind</i></code>”表示正在引用的常量池。每个使用此类格式的操作码明确地表示只允许使用一种常量；请查看操作码参考，找出对应关系。常量池的种类包括“<code>string</code>”（字符串池索引）、“<code>type</code>”（类型池索引）、“<code>field</code>”（字段池索引）、“<code>meth</code>”（方法池索引）和“<code>site</code>”（调用点索引）。</p> + +<p>此外还可使用一些建议的可选形式，它们与常量池索引的表示类似，表示预链接的偏移量或索引。可以使用两种类型的建议的预链接值：vtable 偏移（表示为“<code>vtaboff</code>”）和字段偏移（表示为“<code>fieldoff</code>”）。</p> + +<p>如果格式值并非明确地包含在语法中，而是选择使用某种变体，则每个变体都以“<code>[<i>X</i>=<i>N</i>]</code>”（例如，“<code>[A=2]</code>”）为前缀来表示对应关系。</p> + +<h2 id="formats">格式</h2> + +<table class="format"> +<thead> +<tr> + <th>格式</th> + <th>ID</th> + <th>语法</th> + <th>包含的重要操作码</th> +</tr> +</thead> +<tbody> +<tr> + <td><i>无</i></td> + <td>00x</td> + <td><i><code>N/A</code></i></td> + <td><i>用于未使用操作码的伪格式；建议用作断点操作码的标称格式</i></td> +</tr> +<tr> + <td>ØØ|<i>op</i></td> + <td>10x</td> + <td><i><code>op</code></i></td> + <td> </td> +</tr> +<tr> + <td rowspan="2">B|A|<i>op</i></td> + <td>12x</td> + <td><i><code>op</code></i> vA, vB</td> + <td> </td> +</tr> +<tr> + <td>11n</td> + <td><i><code>op</code></i> vA, #+B</td> + <td> </td> +</tr> +<tr> + <td rowspan="2">AA|<i>op</i></td> + <td>11x</td> + <td><i><code>op</code></i> vAA</td> + <td> </td> +</tr> +<tr> + <td>10t</td> + <td><i><code>op</code></i> +AA</td> + <td>goto</td> +</tr> +<tr> + <td>ØØ|<i>op</i> AAAA</td> + <td>20t</td> + <td><i><code>op</code></i> +AAAA</td> + <td>goto/16</td> +</tr> +<tr> + <td>AA|<i>op</i> BBBB</td> + <td>20bc</td> + <td><i><code>op</code></i> AA, kind@BBBB</td> + <td><i>静态确定验证错误的建议格式；其中，A 表示错误类型，B 表示适当类型的表索引（例如，出现“不存在这种方法”错误时的方法引用）</i></td> +</tr> +<tr> + <td rowspan="5">AA|<i>op</i> BBBB</td> + <td>22x</td> + <td><i><code>op</code></i> vAA, vBBBB</td> + <td> </td> +</tr> +<tr> + <td>21t</td> + <td><i><code>op</code></i> vAA, +BBBB</td> + <td> </td> +</tr> +<tr> + <td>21s</td> + <td><i><code>op</code></i> vAA, #+BBBB</td> + <td> </td> +</tr> +<tr> + <td>21h</td> + <td><i><code>op</code></i> vAA, #+BBBB0000<br /> + <i><code>op</code></i> vAA, #+BBBB000000000000 + </td> + <td> </td> +</tr> +<tr> + <td>21c</td> + <td><i><code>op</code></i> vAA, type@BBBB<br /> + <i><code>op</code></i> vAA, field@BBBB<br /> + <i><code>op</code></i> vAA, string@BBBB + </td> + <td>check-cast<br /> + const-class<br /> + const-string + </td> +</tr> +<tr> + <td rowspan="2">AA|<i>op</i> CC|BB</td> + <td>23x</td> + <td><i><code>op</code></i> vAA, vBB, vCC</td> + <td> </td> +</tr> +<tr> + <td>22b</td> + <td><i><code>op</code></i> vAA, vBB, #+CC</td> + <td> </td> +</tr> +<tr> + <td rowspan="4">B|A|<i>op</i> CCCC</td> + <td>22t</td> + <td><i><code>op</code></i> vA, vB, +CCCC</td> + <td> </td> +</tr> +<tr> + <td>22s</td> + <td><i><code>op</code></i> vA, vB, #+CCCC</td> + <td> </td> +</tr> +<tr> + <td>22c</td> + <td><i><code>op</code></i> vA, vB, type@CCCC<br /> + <i><code>op</code></i> vA, vB, field@CCCC + </td> + <td>instance-of</td> +</tr> +<tr> + <td>22cs</td> + <td><i><code>op</code></i> vA, vB, fieldoff@CCCC</td> + <td><i>22c 格式的静态链接字段访问指令的建议格式</i> + </td> +</tr> +<tr> + <td>ØØ|<i>op</i> AAAA<sub>lo</sub> AAAA<sub>hi</sub></td> + <td>30t</td> + <td><i><code>op</code></i> +AAAAAAAA</td> + <td>goto/32</td> +</tr> +<tr> + <td>ØØ|<i>op</i> AAAA BBBB</td> + <td>32x</td> + <td><i><code>op</code></i> vAAAA, vBBBB</td> + <td> </td> +</tr> +<tr> + <td rowspan="3">AA|<i>op</i> BBBB<sub>lo</sub> BBBB<sub>hi</sub></td> + <td>31i</td> + <td><i><code>op</code></i> vAA, #+BBBBBBBB</td> + <td> </td> +</tr> +<tr> + <td>31t</td> + <td><i><code>op</code></i> vAA, +BBBBBBBB</td> + <td> </td> +</tr> +<tr> + <td>31c</td> + <td><i><code>op</code></i> vAA, string@BBBBBBBB</td> + <td>const-string/jumbo</td> +</tr> +<tr> + <td rowspan="3">A|G|<i>op</i> BBBB F|E|D|C</td> + <td>35c</td> + <td><i>[<code>A=5</code>] <code>op</code></i> {vC, vD, vE, vF, vG}, + meth@BBBB<br /> + <i>[<code>A=5</code>] <code>op</code></i> {vC, vD, vE, vF, vG}, + site@BBBB<br /> + <i>[<code>A=5</code>] <code>op</code></i> {vC, vD, vE, vF, vG}, + type@BBBB<br /> + <i>[<code>A=4</code>] <code>op</code></i> {vC, vD, vE, vF}, + <i><code>kind</code></i>@BBBB<br /> + <i>[<code>A=3</code>] <code>op</code></i> {vC, vD, vE}, + <i><code>kind</code></i>@BBBB<br /> + <i>[<code>A=2</code>] <code>op</code></i> {vC, vD}, + <i><code>kind</code></i>@BBBB<br /> + <i>[<code>A=1</code>] <code>op</code></i> {vC}, + <i><code>kind</code></i>@BBBB<br /> + <i>[<code>A=0</code>] <code>op</code></i> {}, + <i><code>kind</code></i>@BBBB<br /> + <p><i>此处的特殊字母选择反映出其目的在于使计数和引用索引的标签与 3rc 格式中的标签一样。</i></p> + </td> + <td> </td> +</tr> +<tr> + <td>35ms</td> + <td><i>[<code>A=5</code>] <code>op</code></i> {vC, vD, vE, vF, vG}, + vtaboff@BBBB<br /> + <i>[<code>A=4</code>] <code>op</code></i> {vC, vD, vE, vF}, + vtaboff@BBBB<br /> + <i>[<code>A=3</code>] <code>op</code></i> {vC, vD, vE}, + vtaboff@BBBB<br /> + <i>[<code>A=2</code>] <code>op</code></i> {vC, vD}, + vtaboff@BBBB<br /> + <i>[<code>A=1</code>] <code>op</code></i> {vC}, + vtaboff@BBBB<br /> + <p><i>此处的特殊字母选择反映出其目的在于使计数和引用索引的的标签与 3rms 格式中的标签一样。</i></p> + </td> + <td><i>35c 格式的静态链接 <code>invoke-virtual</code> 和 <code>invoke-super</code> 指令的建议格式</i> + </td> +</tr> +<tr> + <td>35mi</td> + <td><i>[<code>A=5</code>] <code>op</code></i> {vC, vD, vE, vF, vG}, + inline@BBBB<br /> + <i>[<code>A=4</code>] <code>op</code></i> {vC, vD, vE, vF}, + inline@BBBB<br /> + <i>[<code>A=3</code>] <code>op</code></i> {vC, vD, vE}, + inline@BBBB<br /> + <i>[<code>A=2</code>] <code>op</code></i> {vC, vD}, + inline@BBBB<br /> + <i>[<code>A=1</code>] <code>op</code></i> {vC}, + inline@BBBB<br /> + <p><i>此处的特殊字母选择反映出其目的在于使计数和引用索引的标签与 3rmi 格式中的标签一样。</i></p> + </td> + <td><i>35c 格式内联链接 <code>invoke-static</code> 和 <code>invoke-virtual</code> 指令的建议格式</i> + </td> +</tr> +<tr> + <td rowspan="3">AA|<i>op</i> BBBB CCCC</td> + <td>3rc</td> + <td><i><code>op</code></i> {vCCCC .. vNNNN}, meth@BBBB<br /> + <i><code>op</code></i> {vCCCC .. vNNNN}, site@BBBB<br /> + <i><code>op</code></i> {vCCCC .. vNNNN}, type@BBBB<br /> + <p><i>其中 <code>NNNN = CCCC+AA-1</code>，即 <code>A</code> 确定计数 <code>0..255</code>，<code>C</code> 确定第一个寄存器</i></p> + </td> + <td> </td> +</tr> +<tr> + <td>3rms</td> + <td><i><code>op</code></i> {vCCCC .. vNNNN}, vtaboff@BBBB<br /> + <p><i>其中 <code>NNNN = CCCC+AA-1</code>，即 <code>A</code> 确定计数 <code>0..255</code>，<code>C</code> 确定第一个寄存器</i></p> + </td> + <td><i><code>3rc</code> 格式的静态链接 <code>invoke-virtual</code> 和 <code>invoke-super</code> 指令的建议格式 +</i> + </td> +</tr> +<tr> + <td>3rmi</td> + <td><i><code>op</code></i> {vCCCC .. vNNNN}, inline@BBBB<br /> + <p><i>其中 <code>NNNN = CCCC+AA-1</code>，即 <code>A</code> 确定计数 <code>0..255</code>，<code>C</code> 确定第一个寄存器</i></p> + </td> + <td><i>3rc 格式的内联链接 <code>invoke-static</code> 和 <code>invoke-virtual</code> 指令的建议格式</i> + </td> +</tr> +<tr> + <td>A|G|<i>op</i> BBBB F|E|D|C HHHH + </td><td>45cc</td> + <td> + <i>[<code>A=5</code>] <code>op</code></i> {vC, vD, vE, vF, vG}, meth@BBBB, proto@HHHH<br /> + <i>[<code>A=4</code>] <code>op</code></i> {vC, vD, vE, vF}, meth@BBBB, proto@HHHH<br /> + <i>[<code>A=3</code>] <code>op</code></i> {vC, vD, vE}, meth@BBBB, proto@HHHH<br /> + <i>[<code>A=2</code>] <code>op</code></i> {vC, vD}, meth@BBBB, proto@HHHH<br /> + <i>[<code>A=1</code>] <code>op</code></i> {vC}, meth@BBBB, proto@HHHH + </td> + <td>invoke-polymorphic + </td> +</tr> +<tr> + <td>AA|<i>op</i> BBBB CCCC HHHH + </td><td>4rcc</td> + <td> + <code>op></code> {vCCCC .. vNNNN}, meth@BBBB, proto@HHHH + <p><i>其中 <code>NNNN = CCCC+AA-1</code>，即 <code>A</code> 确定计数 <code>0..255</code>，<code>C</code> 确定第一个寄存器</i></p> + </td> + <td>invoke-polymorphic/range + </td> +</tr> +<tr> + <td>AA|<i>op</i> BBBB<sub>lo</sub> BBBB BBBB BBBB<sub>hi</sub></td> + <td>51l</td> + <td><i><code>op</code></i> vAA, #+BBBBBBBBBBBBBBBB</td> + <td>const-wide</td> +</tr> +</tbody> +</table> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/dalvik/jit-compiler.html b/zh-cn/devices/tech/dalvik/jit-compiler.html new file mode 100644 index 00000000..b4de2cbe --- /dev/null +++ b/zh-cn/devices/tech/dalvik/jit-compiler.html @@ -0,0 +1,302 @@ +<html devsite><head> + <title>实现 ART 即时 (JIT) 编译器</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 7.0 中，我们为 Android 运行时 (ART) 添加了一个具备代码归类功能的即时 (JIT) 编译器。ART 可以在 Android 应用运行时持续提高其性能。JIT 编译器补充了 ART 当前的预先 (AOT) 编译器的功能，有助于提高运行时性能、节省存储空间和加快应用更新及系统更新速度。 +</p> + +<p> +相较于 AOT 编译器，JIT 编译器的表现也更为出色，因为它不会在应用自动更新期间或 OTA 时重新编译应用期间拖慢系统速度。因此，该功能对制造商在设备集成方面的要求也最低。 +</p> + +<p> +JIT 和 AOT 使用相同的编译器，它们所进行的一系列优化几乎完全相同。根据实际情况生成的代码可能会有所不同。JIT 会利用运行时类型信息，并且可以更高效地进行内联。此外，我们有时会通过 JIT 进行 OSR 编译（即栈上替换）。这种编译会再次生成略有差异的代码。 +</p> + +<p> +要了解更全面的信息，请参阅 developer.android.com 网站上的<a href="https://developer.android.com/preview/api-overview.html#jit_aot">配置文件引导的 JIT/AOT 编译</a>。 +</p> + +<h2 id="architectural-overview">架构概览</h2> + +<img src="images/jit-arch.png" alt="JIT 架构" width="633" id="JIT-architecture"/> +<p class="img-caption"> + <strong>图 1.</strong> JIT 架构 - 工作原理 +</p> + +<h2 id="flow">流程</h2> + +<p> +JIT 编译采用以下方式运作： +</p> + +<ol> +<li>用户运行应用，而这随后就会触发 ART 加载 .dex 文件。 +</li><li>如果有 .oat 文件（即 .dex 文件的 AOT 二进制文件），ART 会直接使用该文件。请注意，虽然 .oat 文件会定期生成，但这并不意味着文件中会包含经过编译的代码（即 AOT 二进制文件）。 +</li><li>如果没有 .oat 文件，ART 会通过 JIT 或解释器执行 .dex 文件。如果有 .oat 文件，ART 将始终使用该文件。否则，它将在内存中解压 APK 文件并得到 .dex 文件，但是这会导致消耗大量内存（相当于 dex 文件的大小）。 +</li><li>对任何不是根据“加速”编译过滤器编译的应用启用 JIT（也就是说，要尽可能多地在应用中进行编译）。 +</li><li>将 JIT 配置文件数据转存到系统目录内的文件中。只有应用能访问这个目录。 +</li><li>AOT 编译 (dex2oat) 守护进程通过解析该文件来促进编译。</li> +</ol> + +<img src="images/jit-profile-comp.png" alt="配置文件引导的编译" width="452" id="JIT-profile-comp"/> +<p class="img-caption"> + <strong>图 2.</strong> 配置文件引导的编译 +</p> + +<img src="images/jit-daemon.png" alt="JIT 守护进程" width="718" id="JIT-daemon"/> +<p class="img-caption"> + <strong>图 3.</strong> 守护进程工作原理 +</p> + +<p> +举例来说，Google Play 就是一种由其他应用使用的服务。这些应用往往表现更像是共享库。 +</p> + +<h2 id="jit-workflow">JIT 工作流程</h2> +<p> +请从在接下来的示意图中查看下文介绍的 JIT 工作原理简要概览。 +</p> + +<img src="images/jit-workflow.png" alt="JIT 架构" width="707" id="JIT-workflow"/> +<p class="img-caption"> + <strong>图 4.</strong> JIT 数据流 +</p> + +<p> +这表示： +</p> + +<ul> +<li>归类信息存储在代码缓存中，并且会在内存紧张时进行垃圾回收。 +</li><li>因此，无法保证在应用处于后台时所捕获的快照能够包含完整的数据（即 JIT 编译的所有内容）。 +</li><li>不会尝试确保记录所有内容，因为这将影响运行时的性能。 +</li><li>方法可能有三种不同的状态：<ul> + <li>已经过解释（dex 代码） + </li><li>已经过 JIT 编译 + </li><li>已经过 AOT 编译 +</li><li>如果同时存在 JIT 和 AOT 代码（例如，由于反复进行逆优化），经过 JIT 编译的代码将是首选代码。 +</li><li>在不影响前台应用性能的情况下运行 JIT 所需的内存取决于相关应用。大型应用比小型应用需要更多内存。一般来说，大型应用所需的内存稳定维持在 4 MB 左右。</li></ul> +</li> +</ul> + +<h2 id="system-properties">系统属性</h2> + +<p> +以下系统属性用于控制 JIT 行为： +</p><ul> +<li><code>dalvik.vm.usejit <true|false></true|false></code>- 是否启用 JIT。 +</li><li><code>dalvik.vm.jitinitialsize</code>（默认 64K）- 代码缓存的初始容量。代码缓存将定期进行垃圾回收 (GC) 并且可以视情况增加缓存。您或许可以使用以下属性查看您应用的代码缓存大小：<br /> +<code> $ adb shell dumpsys meminfo -d &LT;pid&GT;</code> +</li><li><code>dalvik.vm.jitmaxsize</code>（默认 64M）- 代码缓存的最大容量。 +</li><li><code>dalvik.vm.jitthreshold &LT;integer&GT;</code>（默认 10000）- 此项属性是 JIT 编译方法时需要的“热度”计数器传递的阈值。“热度”计数器是运行时的内部度量标准。它包括调用次数、后向分支及其他因素。 +</li><li><code>dalvik.vm.usejitprofiles &LT;true|false&GT;</code> - 是否启用 JIT 配置文件；当 usejit 为 False 时也可以使用此属性。 +</li><li><code>dalvik.vm.jitprithreadweight &LT;integer&GT;</code>（默认为 <code>dalvik.vm.jitthreshold</code> / 20）- 应用界面线程的 JIT“示例”（参见 jitthreshold）的权重。用于加速方法的编译。在与应用交互时，这些方法会直接影响用户体验。 +</li><li><code>dalvik.vm.jittransitionweight &LT;integer&GT;</code> (<code>dalvik.vm.jitthreshold</code> / 10) - 在编译代码和解释器转换之间选择调用的方法的权重。这有助于确保所涉及的方法在编译时尽可能减少转换的量（转换需要很大开销）。 +</li> +</ul> + +<h2 id="tuning">调整</h2> + +<p> +如果需要，设备制造商可能会预先编译（某些）系统应用。使用 JIT 初始化的性能与预编译的性能差异取决于应用，但通常情况下两者会非常接近。可能值得注意的是，预编译的应用不会被归类，因此这会占用更多空间，并可能错过其他优化。 +</p> + +<p> +在 Android 7.0 中，有种基于不同的用例来指定编译/验证级别的通用方式。例如，安装时间的默认选项是仅进行验证（并将编译推迟到后期）。编译级别可通过系统属性进行配置，默认值为： +</p> + +<pre> +pm.dexopt.install=interpret-only +pm.dexopt.bg-dexopt=speed-profile +pm.dexopt.ab-ota=speed-profile +pm.dexopt.nsys-library=speed +pm.dexopt.shared-apk=speed +pm.dexopt.forced-dexopt=speed +pm.dexopt.core-app=speed +pm.dexopt.first-boot=interpret-only +pm.dexopt.boot=verify-profile +</pre> + +<p> +如需了解如何使用，请参阅<a href="#recommendation">建议</a>一节。 +</p> + +<p> +请注意，此处引用了 A/B 无线下载 (OTA) 更新。 +</p> + +<p> +检查 <code>$ adb shell cmd package compile</code> 以了解使用情况。请注意，本文档中的所有命令前面都有一个美元 ($) 符号，在复制粘贴命令时应去掉该符号。下面是几个常见用例： +</p> + +<h3 id="turn-on-jit-logging">打开 JIT 日志记录</h3> + +<pre> +$ adb root +$ adb shell stop +$ adb shell setprop dalvik.vm.extra-opts -verbose:jit +$ adb shell start +</pre> + +<h3 id="disable-jit-and-run-applications-in-interpreter">禁用 JIT</h3> + +<pre> +$ adb root +$ adb shell stop +$ adb shell setprop dalvik.vm.usejit false +$ adb shell start +</pre> + +<h3 id="force-compilation-of-a-specific-package">强制编译特定软件包</h3> + +<ul> +<li>基于配置文件： +<code>$ adb shell cmd package compile -m speed-profile -f +my-package</code> +</li><li>全部： +<code>$ adb shell cmd package compile -m speed -f +my-package</code></li> +</ul> + +<h3 id="force-compilation-of-all-packages">强制编译所有软件包</h3> + +<ul> +<li>基于配置文件： +<code>$ adb shell cmd package compile -m speed-profile -f +-a</code> +</li><li>全部： +<code>$ adb shell cmd package compile -m speed -f -a</code></li></ul> + +<h3 id="clear-profile-data-and-remove-compiled-code">清除配置文件数据并删除经过编译的代码</h3> + +<ul> +<li>一个软件包： +<code>$ adb shell cmd package compile --reset my-package</code> +</li><li>所有软件包： +<code>$ adb shell cmd package compile --reset +-a</code></li> +</ul> + +<h2 id="recommendation">建议</h2> + +<h3 id="runtime_compilation_level">编译/验证级别</h3> + +<p> +请注意，我们强烈建议您使用以下 <code>pm.dexopt</code> 默认设置，因为它是经过我们测试而且我们将提供支持的唯一路径。 +</p> + +<pre> +pm.dexopt.install=interpret-only +pm.dexopt.bg-dexopt=speed-profile +pm.dexopt.boot=verify-profile (or interpret-only) +</pre> + +<p> +以下是有关 <code>pm.dexopt</code> 选项的详细说明，以及我们提出这些建议的原因： +</p> + +<pre> +pm.dexopt.install +</pre> + +<p> +这是通过 Play 商店安装应用时所使用的编译过滤器。为了加快安装速度，我们建议 <code>interpret-only</code>。 +</p> + +<pre> +pm.dexopt.bg-dexopt +</pre> + +<p> +这是当设备处于空闲状态和在充电以及充满电时所使用的编译过滤器。我们建议您使用 <code>speed-profile</code>，以利用配置文件引导的编译并节省存储空间。 +</p> + +<pre> +pm.dexopt.ab-ota +</pre> + +<p> +这是在进行 A/B 无线下载 (OTA) 更新时使用的编译过滤器。如果设备支持 A/B OTA，我们建议使用 <code>speed-profile</code>，以利用配置文件引导的编译并节省存储空间。 +</p> + +<pre> +pm.dexopt.nsys-library +pm.dexopt.shared-apk +pm.dexopt.core-app +</pre> + +<p> +您可以使用这些不同的选项来控制如何从根本上编译被其他应用使用的应用。对于此类应用，我们建议使用 <code>speed</code> 过滤器，因为相应平台不支持对其进行有效归类。 +</p> + +<pre> +pm.dexopt.first-boot +</pre> + +<p> +在设备初次启动时使用的编译过滤器。此时使用的过滤器只会影响出厂后的启动时间。对于这种情况，我们建议使用 <code>interpret-only</code> 过滤器，以免用户在首次使用时需要很长时间才能开始使用手机。请注意，如果 /system 中的所有应用都已进行了速度编译，<code>pm.dexopt.first-boot</code> 将不会产生任何影响。 +</p> + +<pre> +pm.dexopt.boot +</pre> + +<p> +无线下载更新后使用的编译过滤器。对于此选项，我们<strong>强烈</strong>建议使用 <code>verify-profile</code>，以免更新时间过久。 +</p> + +<h3 id="system_image_compilation_level">系统映像</h3> + +<p> +本节为您提供有关如何最大限度地减小系统映像大小，同时尽可能维持最高性能水平的建议。请注意，本节内容是对上述关于<a href="#runtime_compilation_level">编译/验证级别</a>的指导原则的补充。 +</p> + +<p> +为预构建版本选择较低级别的编译可以减小系统映像大小。为了达到应用性能和映像大小之间的最佳折中状态，我们强烈建议您使用 <code>interpret-only</code> 过滤器来编译预构建版本。为此，请修改以下文件来添加这些条目。 +</p> + +<p>请将以下条目添加到 <code>BoardConfig.mk</code>：</p> + +<pre>WITH_DEXPREOPT := true</pre> + +<p>请将以下条目添加到 <code>device.mk</code>：</p> + +<pre> +PRODUCT_DEX_PREOPT_DEFAULT_FLAGS := --compiler-filter=interpret-only +</pre> + +<p> +与 <code>speed</code> 过滤器相比，使用 <code>interpret-only</code> 过滤器可将预构建版本已优化代码的大小缩小几乎一半（具体取决于应用）。借助此过滤器，运行时还可以归类预构建版本并执行配置文件引导的编译，以进一步节省数据分区存储空间。 +</p> + +<p> +我们建议您不要为了进一步节省系统映像上的空间，而使用较低的编译/验证级别（例如：<code>verify-none</code>）或禁用预构建版本的优化功能。因为这会导致减缓应用的启动速度并会增加内存的消耗。 +</p> + +<h2 id="validation">验证</h2> + +<p> +为了确保其功能版本能按预期运行，设备实现程序应该在 <code>android/art/test</code> 中运行 ART 测试。另请参阅 CTS 测试 <code>hostsidetests/compilation</code>，了解有关 userdebug 版本的信息。 +</p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/datausage/kernel-changes.html b/zh-cn/devices/tech/datausage/kernel-changes.html new file mode 100644 index 00000000..fcf47b49 --- /dev/null +++ b/zh-cn/devices/tech/datausage/kernel-changes.html @@ -0,0 +1,38 @@ +<html devsite><head> + <title>内核变化</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>以下内容简要介绍了从主线内核中分离出的内核分支的主要变化。</p> +<ul> +<li>新增了 net/netfilter/xt_qtaguid*</li> +<li>从 xtables-addons 项目导入了 net/netfilter/xt_quota2.c，且随后对其进行了修改</li> +<li>修正了 net/netfilter/ip6_tables.c 的相关错误</li> +<li>对 ip*t_REJECT.c 进行了修改</li> +<li>对 net/netfilter/xt_socket.c 进行了修改</li> +</ul> +<p>关于内核配置的几条注释：</p> +<ul> +<li>xt_qtaguid 伪装成 xt_owner 并依赖于 xt_socket，而它本身则依赖于连接跟踪器。</li> +<li>连接跟踪器无法处理大型 SIP 数据包，因此必须禁用。</li> +<li>经过修改的 xt_quota2 使用 NFLOG 支持来通知用户空间。</li> +</ul> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/datausage/kernel-overview.html b/zh-cn/devices/tech/datausage/kernel-overview.html new file mode 100644 index 00000000..66acf377 --- /dev/null +++ b/zh-cn/devices/tech/datausage/kernel-overview.html @@ -0,0 +1,29 @@ +<html devsite><head> + <title>概览</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 3.0 的 Linux 内核 (<code>kernel/net/netfilter/xt_qtaguid</code>) 中的 xt_qtaguid 模块来实现。框架 (<code>system/core/libcutils/qtaguid.c</code>) 中的套接字标记功能的实现主要依赖于从内核模块 <code>xt_qtaguid</code> 中导出到 <code>/proc/net/xt_qtaguid/ctrl</code> 接口的存在。</p> +<p><code>quota2</code> netfilter 模块（最初是属于 <code>xtables-addons</code>）可支持设置指定的配额限制的功能；此外，经过扩展后，该模块还可支持在达到特定配额限制时通知用户空间。一旦达到配额限制，<code>quota2</code> 模块将丢弃所有的后续网络流量。该框架还可以指定额外的规则来限制应用的后台数据流量（请参阅 <code>com.android.server.NetworkManagementSocketTagger.setKernelCounterSet</code> 和 <code>android.net.NetworkPolicyManager.POLICY_REJECT_METERED_BACKGROUND</code>）。</p> +<h1 id="how-does-it-work">工作原理</h1> +<p><code>qtaguid</code> netfilter 模块使用隶属于应用的专属 UID，基于单个套接字对每款应用的网络流量进行跟踪。系统中有两个标签组件与套接字相关联。第一个是 UID，用来唯一标识进行数据传输的应用（Linux 允许将每个网络套接字的所有权与调用应用的 UID 相关联）。第二个标签组件用于支持附加于流量上的开发者指定的类别描述。应用可使用这些应用级别标签，将流量归类到若干子类别。</p> +<p>当应用以服务（如下载管理器、媒体流式传输服务等）的方式提供网络数据传输时，可通过调用 <code>TrafficStats.setThreadStatsUid()</code> 函数将网络数据传输的所有权与发出请求的应用的 UID 相关联。发出调用的应用必须具备“<code>android.permission.MODIFY_NETWORK_ACCOUNTING</code>”权限才能重新分配网络流量的所有权。</p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/datausage/tethering-data.html b/zh-cn/devices/tech/datausage/tethering-data.html new file mode 100644 index 00000000..ff9a8964 --- /dev/null +++ b/zh-cn/devices/tech/datausage/tethering-data.html @@ -0,0 +1,25 @@ +<html devsite><head> + <title>网络共享流量</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>网络共享涉及使用 <code>iptables</code> 转发规则将流量从一个网络接口转发到另一个网络接口。该框架会定期记录由 <code>ConnectivityService.getTetheredIfacePairs()</code> 返回的任何接口对之间的网络共享统计信息。</p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/debug/jank_jitter.html b/zh-cn/devices/tech/debug/jank_jitter.html new file mode 100644 index 00000000..e3874146 --- /dev/null +++ b/zh-cn/devices/tech/debug/jank_jitter.html @@ -0,0 +1,180 @@ +<html devsite><head> + <title>识别与抖动相关的卡顿</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>抖动是一种随机的系统行为，可阻止可察觉任务运行。本文将介绍如何识别和解决抖动引起的卡顿问题。</p> + +<h2 id="application">应用线程调度程序延迟</h2> +<p>调度程序延迟是最明显的抖动征兆，具体表现为：尽管本应运行的进程处于就绪状态，但在相当长的一段时间内并未运行。根据情况的不同，延迟所造成的影响也不尽相同。例如：</p> +<ul> +<li>某个应用中的某个随机帮助程序线程可能会延迟若干毫秒，而不引起任何问题。</li> +<li>某个应用的界面线程可能可以容忍 1 至 2 毫秒的抖动。</li> +<li>作为 SCHED_FIFO 运行的驱动程序 kthread，如果在进入就绪状态 500 微秒还未开始运行，则可能会引发问题。</li> +</ul> +<p>就绪状态时间可以在 systrace 中确定，具体是通过线程运行分段前面的蓝色条进行确定。还有一种方法可以确定就绪状态时间，即通过某个线程的 <code>sched_wakeup</code> 事件与表示线程开始执行的 <code>sched_switch</code> 事件之间的时间长度来确定。</p> + +<h3 id="long_threads">线程运行时间过长</h3> +<p>应用界面线程如果处于就绪状态的时间过长，可能会引起问题。不同的低级线程长时间处于就绪状态的原因通常是不同的，不过，如果您想尝试将界面线程的就绪状态时间降至零，可能需要修复导致低级线程长时间处于就绪状态的一些相同问题。要降低延迟，可以尝试以下方法：</p> +<ol> +<li>使用<a href="/devices/tech/debug/jank_capacity.html#thermal-throttling">温控调频</a>中描述的 cpuset。</li> +<li>增加 CONFIG_HZ 的值。<ul> +<li>过去，在 arm 和 arm64 平台上，该值曾设为 100。不过，这只是一个巧合，该值其实并不适合交互式设备。如果 CONFIG_HZ = 100，则表示 jiffy 的长度为 10 毫秒，即 CPU 之间的负载平衡可能需要 20 毫秒的时间（两个 jiffy）。这极大增加了负载系统发生卡顿的几率。</li> +<li>近期推出的设备（如 Nexus 5X、Nexus 6P、Pixel、Pixel XL 等），出厂设置为 CONFIG_HZ = 300。该设置不仅可以显著改善就绪状态时间的问题，同时造成的功耗可以忽略不计。如果在更改 CONFIG_HZ 之后，出现功耗明显增加或性能问题，很可能是因为您的某一个驱动程序使用的是以原始 jiffy（而非毫秒）为单位的定时器，并会转换为 jiffy。通常情况下，要修复这个问题并不难（请参阅<a href="https://android.googlesource.com/kernel/msm.git/+/daf0cdf29244ce4098cff186d16df23cfa782993%5E!/">补丁程序</a>，该补丁程序可修复转换至 CONFIG_HZ = 300 时，Nexus 5X 和 6P 上出现的 kgsl 定时器问题）。</li> +<li>最后，我们在 Nexus/Pixel 上尝试设置 CONFIG_HZ = 1000，发现由于 RCU 开销的降低，该设置可显著提升性能并降低功耗。</li> +</ul> +</li> +</ol> +<p>您只需完成以上两项更改，便可改善设备在负载情况下的界面线程就绪状态时间问题。</p> + +<h3 id="sys.use_fifo_ui">使用 sys.use_fifo_ui</h3> +<p>您可以尝试将 <code>sys.use_fifo_ui</code> 属性设置为 1，从而将界面线程处于就绪状态的时间降至零。</p> + +<p class="warning"><strong>警告</strong>：除非您有容量感知型 RT 调度程序，否则不能在异构 CPU 配置上使用此选项。而且，<strong>目前市面上的 RT 调度程序均不具备容量感知功能</strong>。我们正在努力针对 EAS 开发这种类型的调度程序，但尚未推出。默认的 RT 调度程序完全基于两个因素：RT 优先级，以及 CPU 是否已经具有相同或更高优先级的 RT 线程。 + +<br /><br />因此，如果在同一个大核心上有较高优先级的 FIFO kthread 被唤醒，则默认的 RT 调度程序会将运行时间相对较长的界面线程从高频大核心上移到在最低频率运行的小核心上。<strong>这会使得性能明显降低</strong>。鉴于目前市面上的 Android 设备尚未使用上述功能，如果您想要使用该功能，请与 Android 性能团队联系，让他们帮助您验证此功能。</p> + +<p>启用 <code>sys.use_fifo_ui</code> 后，ActivityManager 会跟踪首要应用的界面线程和 RenderThread（对界面最为关键的两个线程），并将这些线程设为 SCHED_FIFO 而非 SCHED_OTHER。这种方法可以有效地消除界面线程和 RenderThread 造成的抖动；在启用该选项的情况下，我们收集的跟踪记录显示微秒级（而非毫秒级）就绪状态时间。</p> + +<p>不过，由于 RT 负载平衡程序不具备容量感知能力，应用的启动性能降低了 30％。这是因为负责启动应用的界面线程会从 2.1 Ghz 金级 Kryo 核心移至 1.5 GHz 银级 Kryo 核心。我们发现，在许多界面基准测试中，通过采用容量感知型 RT 负载平衡程序，在批量操作中取得了相同的性能，并且第 95 和第 99 个百分位的帧时间缩短了 10-15％。</p> + +<h2 id="interrupt">中断流量</h2> +<p>由于 ARM 平台仅在默认情况下才会对 CPU 0 造成中断，因此，我们建议使用 IRQ 平衡程序（在高通平台上，使用 irqbalance 或 msm_irqbalance）。</p> +<p>在 Pixel 开发期间，我们发现，导致卡顿的直接原因是 CPU 0 负载过重而出现中断。例如，如果在 CPU 0 上调度了 <code>mdss_fb0</code> 线程，那么在扫描输出之前，显示屏几乎会立即触发中断，从而大大增加了发生卡顿的概率。<code>mdss_fb0</code> 将处于工作进程中，且截止时间非常紧迫，而它又会因为 MDSS 中断处理程序损失部分时间。为了解决这个问题，我们最初试图将 mdss_fb0 线程的 CPU 亲和性设置为 CPU 1-3，以此来避免因中断而出现争用，但后来我们意识到，我们还未启用 msm_irqbalance。启用 msm_irqbalance 后，由于其他中断引起的争用减少，因此，即使 mdss_fb0 和 MDSS 中断出现在同一个 CPU 上，卡顿问题依然得到了明显的改善。</p> +<p>这可以通过查看 systrace 中的 sched 和 irq 区段来确定。sched 区段显示的是已调度的内容，但 irq 区段中的重叠区域表示在该时间段内正在运行中断，而不是正常调度的进程。如果您发现某个中断占用了大量时间，您有以下选择：</p> +<ul> +<li>提高中断处理程序的速度。</li> +<li>在第一时间阻止中断发生。</li> +<li>如果是常规中断，则将中断频率更改为与可能受中断干扰的其他常规工作不同步。</li> +<li>直接设置中断的 CPU 亲和性，并防止进行负载平衡。</li> +<li>设置受中断干扰的线程的 CPU 亲和性，以避开中断。</li> +<li>借助中断平衡程序，将中断移至负载较少的 CPU。</li> +</ul> +<p>通常我们不建议设置 CPU 亲和性，但在特定情况下，该操作可能会有所帮助。一般来说，我们很难预测系统在大多数常见中断下的状态，但是，对于某些会使系统受到超过正常水平限制（例如 VR）的中断，如果您掌握一套非常具体的触发条件，那么指定 CPU 亲和性可能会是一个很好的解决方案。</p> + +<h2>长 softirq</h2> +<p>当 softirq 运行时，它会停用抢占。softirq 也可以从内核中的多个位置触发，而且可以在用户进程内运行。如果 softirq 活动充分，则用户进程会停止运行 softirq，同时 ksoftirqd 会被唤醒，以运行 softirq 并进行负载平衡。通常情况下，该过程不会出现问题。但是，单个的超长 softirq 可能会对系统造成严重破坏。</p> + +<section class="expandable"> +<h4 class="showalways">显示问题：通过 WLAN 进行数据流式传输时，头部追踪会发生卡顿</h4> + +<p>我们发现，对于这个问题，在特定网络条件 (WLAN) 下，VR 性能不一致。通过跟踪，我们发现单个 NET_RX softirq 可以运行超过 30 毫秒。我们最后发现，该问题是由接收数据包转向（一种高通 WLAN 功能）造成的，该功能将多个 NET_RX softirq 合并成一个 softirq。所生成的 softirq 在合适的条件下，可能会拥有超长（有可能为无限长）的运行时间。</p> +<p>尽管此功能可能会减少花费在联网上的总 CPU 周期，但是它会使系统无法在正确的时间运行正确的内容。停用该功能不仅不会对网络吞吐量或电池续航造成影响，而且可以使 ksoftirqd 对 softirq 进行负载平衡（而非绕过 softirq），从而可以解决 VR 的头部追踪卡顿问题。</p> +</section> +<hr /> + +<p>softirq 会在跟踪记录的 irq 区段内显示，因此，如果能够在跟踪过程中重现该问题，就可以轻松找到 softirq。由于 softirq 可以在用户进程内运行，因此一个不良 softirq 也可能在没有明显原因的情况下，在用户进程内表现为额外的运行时。如果发生这种情况，请查看 irq 区段，确认该问题是否是由 softirq 引起的。</p> + +<h2 id="drivers">驱动程序停用抢占或 IRQ 的时间过长</h2> +<p>如果停用抢占或中断的时间过长（达到数十毫秒），就会导致卡顿。通常情况下，卡顿表现为某个进入就绪状态却不在特定 CPU 上运行的线程，即使处于就绪状态的线程的优先级（即 SCHED_FIFO）远高于另一线程。</p> + +<p>一些准则如下：</p> +<ul> +<li>如果处于就绪状态的线程是 SCHED_FIFO，而正在运行的线程是 SCHED_OTHER，则正在运行的线程已停用抢占或中断。</li> +<li>如果处于就绪状态的线程的优先级 (100) 远高于正在运行的线程 (120)，且处于就绪状态的线程没有在两个 jiffy 的时间内运行，则正在运行的线程很可能已停用抢占或中断。</li> +<li>如果处于就绪状态的线程与正在运行的线程具有相同的优先级，且处于就绪状态的线程没有在 20 毫秒内运行，则正在运行的线程可能已停用抢占或中断。</li> +</ul> +<p>请注意，运行中断处理程序时，您无法为其他中断提供服务，因为中断处理程序也会停用抢占。</p> + +<section class="expandable"> +<h4 class="showalways">显示问题：CONFIG_BUS_AUTO_SUSPEND 造成严重卡顿</h4> + +<p>在这个问题中，我们发现了在 Pixel 启动时造成卡顿的一个主要原因。要按照示例操作，请<a href="perf_traces.zip">下载跟踪记录的 ZIP 文件</a>（包含本节中提及的其他跟踪记录），将文件解压缩，然后在浏览器中打开 trace_30293222.html 文件。</p> + +<p>在跟踪记录中，找到从 2235.195 毫秒开始的 SurfaceFlinger EventThread。在进行弹力球调整时，当 SurfaceFlinger 或界面关键线程在进入就绪状态 6.6 毫秒（两个 jiffy，CONFIG_HZ = 300）后运行时，我们经常会看到丢失一帧的现象。此时，关键 SurfaceFlinger 线程和应用的界面线程为 SCHED_FIFO。</p> +<p>根据跟踪记录，该线程会在特定 CPU 上被唤醒并进入就绪状态，然后在等待两个 jiffy 后被负载平衡到其他 CPU 上开始运行。在界面线程和 SurfaceFlinger 处于就绪状态时正在运行的线程在 pm_runtime_work 中的优先级始终保持为 120 kworker。</p> +<p>通过查看内核了解 pm_runtime_work 的实际运作，我们发现，WLAN 驱动程序中的电源管理是通过 pm_runtime_work 进行的。于是我们停用了 WLAN，然后再获取其他跟踪记录，这时我们发现卡顿消失了。为进一步确认，我们停用了内核中的 WLAN 驱动程序的电源管理功能，并在连接 WLAN 的情况下获取更多跟踪记录，结果发现卡顿同样不见了。高通因此能找到停用抢占的问题区域，并对此进行修复，我们也能在发布时重新启用该选项。</p> +</section> +<hr /> + +<p>识别问题区域的另一个方式是使用 preemptirqsoff 跟踪程序（请参阅<a href="/devices/tech/debug/ftrace.html#dftrace">使用动态 ftrace</a>）。通过此跟踪程序可以更深入地了解无法中断的区域的根本原因（例如函数名称），但要实现这一点需要进行更多激进的工作。虽然这可能会对性能造成更大影响，但绝对值得一试。</p> + +<h2 id="workqueues">错误使用工作队列</h2> +<p>中断处理程序通常需要执行可在中断上下文环境之外进行的工作，从而将工作分包给内核中的不同线程。驱动程序开发人员可能会注意到，内核有一个非常方便的全系统异步任务功能（称为<em></em>工作队列），可用于执行与中断相关的任务。</p> + +<p>然而，工作队列几乎从来不是这类问题的解决方法，因为工作队列都是 SCHED_OTHER。而许多硬件中断都是出现在影响性能的关键路径上，因此必须能够立即运行。但工作队列无法保证其运行时间。无论对于何种设备，只要在影响性能的关键路径上发现有工作队列存在，便可断定它就是造成不时出现卡顿的原因。我们发现，在采用旗舰处理器的 Pixel 上，如果设备处于负载状态（负载由调度程序行为和系统上运行的其他进程决定），则单个工作队列的延迟可达 7 毫秒。</p> + +<p>如果不是工作队列，而是驱动程序需要在单独的线程中处理类似中断的工作，则驱动程序应该创建自己的 SCHED_FIFO kthread。如需获得关于如何通过 kthread_work 函数实现此操作的帮助信息，请参阅此<a href="https://android.googlesource.com/kernel/msm/+/1a7a93bd33f48a369de29f6f2b56251127bf6ab4%5E!/">补丁程序</a>。</p> + +<h2 id="framework-lock">框架锁争用</h2> +<p>框架锁争用可能造成卡顿或其他性能问题。框架锁争用通常是由 ActivityManagerService 锁引起的，但也可能出现在其他锁中。例如，PowerManagerService 锁可能会影响屏幕开启性能。如果您在设备上遇到这个问题，目前还没有什么有效的解决办法，因为该问题只能通过改进框架的架构来加以改善。但是，如果您正在修改在 system_server 内部运行的代码，切记要避免长时间持有锁（尤其是 ActivityManagerService 锁），这非常重要。</p> + +<h2 id="binder-lock">Binder 锁争用</h2> +<p>过去，binder 有一个单独的全局锁。如果运行 binder 事务的线程在持有锁时被抢占，则在该原始线程释放该锁之前，其他线程都无法执行 binder 事务。这是非常糟糕的情况，因为 binder 争用会阻止系统中的所有活动，包括向显示屏发送界面更新（界面线程通过 binder 与 SurfaceFlinger 通信）。</p> +<p>Android 6.0 包含了几个补丁程序，可以在持有 binder 锁时停用抢占，从而改善此问题。这样做之所以是安全的，只是因为应该在实际运行时的几微秒内持有 binder 锁。这可以极大地提高在无争用情况下的性能，而且还可以在 binder 锁被持有期间阻止大多数调度程序切换，从而防止发生争用。但是，由于无法在持有 binder 锁的整个运行时内停用抢占，因此对于那些可以进入睡眠状态的函数（例如 copy_from_user）而言，抢占仍为启用状态，而这可能会导致和初始情况一样的抢占。当我们向上游部门提交补丁程序时，他们很快就告诉我们这是最不明智的做法。（我们同意他们的观点，但我们也不能否认这些补丁程序可以有效地预防卡顿。）</p> + +<h2 id="fd-contention">进程内的 fd 争用</h2> +<p>这种情况很罕见。通常情况下不会因此造成卡顿。</p> +<p>也就是说，如果您在一个进程中有多个线程在写入相同的 fd，就有可能在此 fd 上出现争用。但是，在 Pixel 启动期间，我们只在一个测试中看到过这个问题，在该测试中，低优先级线程尝试占用所有 CPU 时间，而此时单个高优先级线程正在同一进程中运行。所有线程都在写入跟踪标记 fd，如果一个低优先级线程正持有 fd 锁，然后被抢占，则高优先级线程就可能在跟踪标记 fd 上受到阻止。如果低优先级线程被停用跟踪，则不会出现性能问题。</p> +<p>我们在其他任何情况下都没能重现此问题，但该问题依然值得一提，因为这也是跟踪期间可能造成性能问题的一个潜在原因。</p> + +<h2 id="cpu-idle">不必要的 CPU 空闲转换</h2> +<p>在处理 IPC 时，尤其是处理多进程通路时，经常可以看到以下运行时行为的变化：</p> +<ol> +<li>线程 A 在 CPU 1 上运行。</li> +<li>线程 A 唤醒线程 B。</li> +<li>线程 B 开始在 CPU 2 上运行。</li> +<li>线程 A 立即进入睡眠状态，待线程 B 完成其当前工作后，由线程 B 将线程 A 唤醒。</li> +</ol> + +<p>开销通常在步骤 2 和步骤 3 之间产生。如果 CPU 2 空闲，它必须回到活动状态，然后线程 B 才可以运行。根据 SOC 和空闲的深度，线程 B 可能需要等待几十微秒才能开始运行。如果 IPC 每一侧的实际运行时与开销足够接近，CPU 空闲转换将会大幅度降低该通路的整体性能。Android 最常发生上述情况的位置是 binder 事务周围，而许多使用 binder 的服务最后都与上述情况相似。</p> + +<p>首先，请在内核驱动程序中使用 <code>wake_up_interruptible_sync()</code> 函数，并在所有自定义调度程序中支持此函数。请将此作为一项要求，而不是一个提示。目前 binder 使用该函数，这可以避免不必要的 CPU 空闲转换，对同步 binder 事务很有帮助。</p> +<p>第二，请确保您的 CPU 空闲转换时间是可行的，并且 CPU 空闲调节器能正确地将这些因素纳入考虑范畴。如果您的 SOC 出现最深空闲状态的颠簸状态，则无法通过进入最深空闲状态来实现节能。</p> + +<h2 id="logging">日志记录</h2> +<p>日志记录并非不会占用 CPU 周期或内存，因此，请勿滥用日志缓冲区。日志记录会消耗应用（直接）和日志守护进程的周期。在设备出库之前，请删除全部调试日志。</p> + +<h2 id="io-issues">I/O 问题</h2> +<p>I/O 操作是造成抖动的常见原因。如果某个线程去访问内存映射文件，而该页面不在页面缓存中，则会发生故障，并且该线程会从磁盘读取该页面。这会造成该线程被阻塞（通常会阻塞 10 毫秒以上），并且如果问题发生在界面渲染的关键路径中，则可能会导致卡顿。造成 I/O 操作的原因多种多样，在这里我们就不一一讨论了，但在尝试改进 I/O 行为时，请注意检查以下位置：</p> +<ul> +<li><strong>PinnerService</strong>：PinnerService 是 Android 7.0 中新增的一项功能，可以让框架锁定页面缓存中的某些文件。这会清除这部分内存，以供任何其他进程使用。但是，如果事先已知会定期使用某些文件，则可以有效地 mlock（内存锁定）这些文件。<br /><br /> +在运行 Android 7.0 的 Pixel 和 Nexus 6P 设备上，我们 mlock 了以下四个文件：<ul> +<li>/system/framework/arm64/boot-framework.oat</li> +<li>/system/framework/oat/arm64/services.odex</li> +<li>/system/framework/arm64/boot.oat</li> +<li>/system/framework/arm64/boot-core-libart.oat</li> +</ul> +这些文件会被大多数应用和 system_server 持续使用，因此不应该被移出页面。并且我们发现，如果上述任何一个文件被移出页面，当从重型应用切换时，它们会被重新移回页面，从而引起卡顿。 +</li> +<li><strong>加密</strong>：这是造成 I/O 问题的另一个可能原因。我们发现，与基于 CPU 的加密或使用可通过 DMA 访问的硬件块相比，内嵌加密可提供最佳的性能。最重要的是，内嵌加密可以减少与 I/O 相关的抖动，尤其是跟基于 CPU 的加密相比。由于提取页面缓存通常发生在界面渲染的关键路径中，而基于 CPU 的加密会在关键路径中引入额外的 CPU 负载，因此会比 I/O 提取造成更多的抖动。 +<br /><br />基于 DMA 的硬件加密引擎也有类似问题，因为即使其他关键工作可以运行，内核仍然需要花费时间来管理此类工作。我们强烈建议所有 SOC 供应商在构建新硬件时，都应支持内嵌加密功能。</li> +</ul> + +<h2 id="small-task">激进式小任务打包</h2> +<p>一些调度程序支持将小任务打包到单个 CPU 内核上，从而让更多 CPU 在更长时间内保持空闲，以此降低功耗。虽然这样可以有效改善吞吐量和功耗，但却会造成严重的延迟。<em></em>如果界面渲染的关键路径中存在多个短时间运行的线程，可以将其视为小任务；但如果这些线程在缓慢迁移至其他 CPU 的过程中出现延迟，则<strong>会</strong>导致卡顿。我们建议谨慎使用小任务打包。</p> + +<h2 id="page-cache">页面缓存颠簸</h2> +<p>如果一个设备没有足够的可用内存，当它执行长时间运行的操作（例如，打开一个新应用）时，就可能会突然变得非常缓慢。应用的跟踪记录可能显示，在执行特定运行操作期间，它在 I/O 中始终处于被阻止状态，尽管一般情况下它不会在 I/O 中被阻止。这通常可视为页面缓存颠簸的标志，尤其是在内存较少的设备上。</p> + +<p>识别此问题的方法之一，就是使用 pagecache 标记来执行 systrace，并将跟踪记录提供给位于 <code>system/extras/pagecache/pagecache.py</code> 的脚本。pagecache.py 会使将文件映射到页面缓存的单个请求转换成汇总的每个文件的统计信息。如果您发现某个文件被读取的字节数超过了磁盘上该文件的总大小，毫无疑问，您遇到了页面缓存颠簸问题。</p> + +<p>这意味着：您的工作负载（通常是单个应用与 system_server 之和）所要求的工作集超出了您的设备上可供页面缓存使用的内存容量。因此，当工作负载的一部分在页面缓存中取得其需要的数据时，将在不久之后使用的另一部分工作负载则会被逐出，并不得不再次被提取，这将导致问题再次发生，直到工作负载完成。当设备上没有足够的可用内存时，这将是导致性能问题的根本原因。</p> + +<p>对于解决页面缓存颠簸问题，目前尚没有万全之策，但可以尝试通过以下方法在给定的设备上改善此问题。</p> +<ul> +<li>在持续性进程中使用较少内存。持续性进程所占用的内存越少，应用和页面缓存可使用的内存就越多。</li> +<li>审核您设备的 carveout，确保您没有从操作系统中删除不必要的内存。我们看到过这种情况，用于调试的 carveout 被无意中遗留在出库设备的内核配置中，结果占用了上百兆字节的内存。这决定了是否会出现页面缓存颠簸问题，尤其是在内存较少的设备上。</li> +<li>如果您发现 system_server 的关键文件上存在页面缓存颠簸问题，请考虑固定此类文件。尽管这样做会增加其他地方的内存压力，但是可以修改行为以达到避免颠簸的目的。</li> +<li>重新调试 lowmemorykiller，让更多内存保持可用。lowmemorykiller 的阈值由绝对可用内存和页面缓存决定，因此，提高给定 oom_adj 水平下的进程受到终止的阈值，可以改善行为，但代价是会提高后台应用被终止的数量。</li> +<li>尝试使用 ZRAM。尽管 Pixel 有 4 GB 内存，但我们仍在 Pixel 上使用 ZRAM，因为这有助于处理极少使用的脏页。</li> +</ul> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/debug/native-memory.html b/zh-cn/devices/tech/debug/native-memory.html new file mode 100644 index 00000000..d41b86a0 --- /dev/null +++ b/zh-cn/devices/tech/debug/native-memory.html @@ -0,0 +1,44 @@ +<html devsite><head> + <title>调试本地内存使用</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="malloc_debug">Malloc 调试</h2> + +<p>有关本地内存问题可用调试选项的完整说明，请参阅 <a href="https://android.googlesource.com/platform/bionic/+/master/libc/malloc_debug/README.md">Malloc 调试</a>和<a href="https://android.googlesource.com/platform/bionic/+/master/libc/malloc_debug/README_api.md">使用 libc 回调追踪本地内存</a>。</p> + +<h2 id="malloc-stats">Malloc 统计信息</h2> + +<p>Android 支持调用 <a href="http://man7.org/linux/man-pages/man3/mallinfo.3.html"><code>mallinfo(3)</code></a> 和 <a href="http://man7.org/linux/man-pages/man3/malloc_info.3.html"><code>malloc_info(3)</code></a> 以及 <code><malloc.h></code>。<code>malloc_info</code> 函数可在 Android 6.0 及更高版本中使用，其 XML 架构记录在 Bionic 的 <a href="https://android.googlesource.com/platform/bionic/+/master/libc/include/malloc.h"><code><malloc.h></code></a> 中。 +</p> + +<h2 id="ddms">Dalvik 调试监控服务器</h2> + +<p>您还可以使用 <a href="https://developer.android.com/studio/profile/ddms.html">Dalvik 调试监控服务器</a> (DDMS) 获取“Malloc 调试”输出的图形视图。</p> + +<p>要使用 DDMS，请先打开其本机内存界面：</p> +<ol> +<li>打开 <code>~/.android/ddms.cfg</code></li> +<li>添加命令行：<code>native=true</code></li> +</ol> + +<p>重新启动 DDMS 并选择一个进程后，您可以切换到新的本地分配选项卡，并使用分配列表进行填充。这对于调试内存泄漏尤为有用。</p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/debug/procstats.html b/zh-cn/devices/tech/debug/procstats.html new file mode 100644 index 00000000..eae905f8 --- /dev/null +++ b/zh-cn/devices/tech/debug/procstats.html @@ -0,0 +1,357 @@ +<html devsite><head> + <title>查看 RAM 使用情况数据 (procstats)</title> + <meta name="project_path" value="/_project.yaml"/> + <meta name="book_path" value="/_book.yaml"/> + </head> + <body> + <!-- + Copyright 2017 The Android Open Source Project + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + --> + +<p><code>procstats</code> 工具用于分析应用内存在一段时间内的使用情况（而不像 <code>meminfo</code> 一样在特定时间点捕获快照）。其状态转储会显示每个应用的运行时间、比例集合大小 (PSS) 和唯一集合大小 (USS) 的统计信息。</p> + +<h2 id="input">输入</h2> + +<p>要了解过去三小时内的应用内存使用情况（以人类可读的形式显示），请运行以下命令：</p> + +<pre class="prettyprint"> +$ adb shell dumpsys procstats --hours 3 +</pre> + +<h2 id="output">输出</h2> + +<p>从下面的示例中可以看出，百分比表示应用运行时间的百分比，后面的数字代表样本的 PSS 和 USS 值，显示为：PSS 最小值-PSS 平均值-PSS 最大值/USS 最小值-USS 平均值-USS 最大值 over 样本数。</p> + +<pre class="no-pretty-print"> +AGGREGATED OVER LAST 3 HOURS: + * com.android.systemui / u0a20 / v22: + TOTAL: 100% (109MB-126MB-159MB/108MB-125MB-157MB over 18) + Persistent: 100% (109MB-126MB-159MB/108MB-125MB-157MB over 18) + * com.android.nfc / 1027 / v22: + TOTAL: 100% (17MB-17MB-17MB/16MB-16MB-16MB over 18) + Persistent: 100% (17MB-17MB-17MB/16MB-16MB-16MB over 18) + * android.process.acore / u0a4 / v22: + TOTAL: 100% (14MB-15MB-15MB/14MB-14MB-14MB over 20) + Imp Fg: 100% (14MB-15MB-15MB/14MB-14MB-14MB over 20) + * com.google.android.inputmethod.latin / u0a56 / v21483: + TOTAL: 100% (57MB-59MB-59MB/56MB-58MB-58MB over 19) + Imp Fg: 100% (57MB-59MB-59MB/56MB-58MB-58MB over 19) + * com.redbend.vdmc / 1001 / v1: + TOTAL: 100% (9.5MB-9.6MB-9.7MB/8.8MB-8.9MB-9.0MB over 18) + Persistent: 100% (9.5MB-9.6MB-9.7MB/8.8MB-8.9MB-9.0MB over 18) + * com.android.phone / 1001 / v22: + TOTAL: 100% (19MB-22MB-27MB/18MB-21MB-26MB over 18) + Persistent: 100% (19MB-22MB-27MB/18MB-21MB-26MB over 18) + * com.google.android.gms.persistent / u0a8 / v7319438: + TOTAL: 100% (32MB-35MB-40MB/30MB-33MB-37MB over 19) + Imp Fg: 100% (32MB-35MB-40MB/30MB-33MB-37MB over 19) + * com.android.bluetooth / 1002 / v22: + TOTAL: 100% (9.3MB-9.7MB-10MB/8.5MB-8.9MB-9.2MB over 19) + Imp Fg: 100% (9.3MB-9.7MB-10MB/8.5MB-8.9MB-9.2MB over 19) + * com.google.android.googlequicksearchbox:interactor / u0a22 / v300404573: + TOTAL: 100% (3.4MB-3.5MB-3.6MB/2.8MB-2.8MB-2.8MB over 19) + Imp Fg: 100% (3.4MB-3.5MB-3.6MB/2.8MB-2.8MB-2.8MB over 19) + * com.google.process.gapps / u0a8 / v7306438: + TOTAL: 100% (23MB-24MB-28MB/21MB-22MB-26MB over 19) + Imp Fg: 100% (23MB-24MB-28MB/21MB-22MB-26MB over 19) + * com.vito.lux / u0a84 / v237: + TOTAL: 100% (32MB-48MB-83MB/31MB-47MB-82MB over 134) + Imp Fg: 100% (32MB-48MB-83MB/31MB-47MB-82MB over 134) + Service: 0.05% + * system / 1000 / v22: + TOTAL: 100% (79MB-85MB-102MB/78MB-83MB-100MB over 18) + Persistent: 100% (79MB-85MB-102MB/78MB-83MB-100MB over 18) + * com.rhapsody / u0a83 / v125: + TOTAL: 100% (7.9MB-12MB-19MB/6.9MB-11MB-17MB over 15) + Service: 100% (7.9MB-12MB-19MB/6.9MB-11MB-17MB over 15) + Service Rs: 0.04% + * com.qualcomm.qcrilmsgtunnel / 1001 / v22: + TOTAL: 100% (2.5MB-2.6MB-2.7MB/1.7MB-1.8MB-1.9MB over 15) + Service: 100% (2.5MB-2.6MB-2.7MB/1.7MB-1.8MB-1.9MB over 15) + Service Rs: 0.13% + * com.amazon.kindle / u0a82 / v1143472216: + TOTAL: 100% (44MB-54MB-77MB/43MB-52MB-74MB over 17) + Service: 100% (44MB-54MB-77MB/43MB-52MB-74MB over 17) + Service Rs: 0.04% + * com.outplaylab.VideoDiet2 / u0a93 / v21: + TOTAL: 100% (2.8MB-3.1MB-4.0MB/2.0MB-2.2MB-3.0MB over 15) + Service: 100% (2.8MB-3.1MB-4.0MB/2.0MB-2.2MB-3.0MB over 15) + Service Rs: 0.03% + * android.process.media / u0a6 / v800: + TOTAL: 99% (4.6MB-5.9MB-8.1MB/3.4MB-4.7MB-6.7MB over 25) + Imp Fg: 0.02% + Service: 99% (4.6MB-5.9MB-8.1MB/3.4MB-4.7MB-6.7MB over 25) + Service Rs: 0.02% + (Cached): 0.94% + * kr.sira.sound / u0a108 / v41: + TOTAL: 77% (117MB-191MB-219MB/111MB-187MB-213MB over 68) + Top: 77% (117MB-191MB-219MB/111MB-187MB-213MB over 68) + (Last Act): 18% (58MB-127MB-161MB/53MB-123MB-158MB over 3) + (Cached): 0.06% + * com.google.android.gms / u0a8 / v7319438: + TOTAL: 37% (41MB-45MB-57MB/38MB-42MB-53MB over 23) + Top: 13% (41MB-46MB-57MB/39MB-42MB-53MB over 16) + Imp Fg: 13% (41MB-44MB-47MB/39MB-41MB-44MB over 5) + Imp Bg: 0.38% + Service: 11% (42MB-42MB-42MB/38MB-38MB-38MB over 2) + Receiver: 0.03% + (Last Act): 2.0% (38MB-38MB-38MB/36MB-36MB-36MB over 1) + (Cached): 61% (39MB-40MB-43MB/37MB-37MB-40MB over 28) + * com.google.android.googlequicksearchbox / u0a22 / v300404573: + TOTAL: 22% (129MB-153MB-162MB/125MB-149MB-156MB over 20) + Top: 22% (129MB-153MB-162MB/125MB-149MB-156MB over 20) + Imp Bg: 0.04% + Receiver: 0.01% + (Home): 78% (75MB-84MB-122MB/74MB-82MB-117MB over 12) + * com.google.android.apps.thehub / u0a102 / v12: + TOTAL: 21% (6.4MB-7.6MB-8.7MB/4.8MB-6.0MB-7.2MB over 2) + Service: 21% (6.4MB-7.6MB-8.7MB/4.8MB-6.0MB-7.2MB over 2) + * com.google.android.talk / u0a54 / v22314462: + TOTAL: 9.3% + Top: 0.04% + Service: 9.3% + Receiver: 0.01% + (Last Act): 3.9% (69MB-70MB-71MB/67MB-68MB-69MB over 6) + (Cached): 87% (42MB-53MB-77MB/40MB-51MB-74MB over 137) + * com.google.android.apps.plus / u0a67 / v413836278: + TOTAL: 8.2% (9.6MB-12MB-18MB/8.1MB-11MB-16MB over 3) + Imp Bg: 0.10% + Service: 8.0% (9.6MB-12MB-18MB/8.1MB-11MB-16MB over 3) + Receiver: 0.05% + (Cached): 59% (7.8MB-19MB-33MB/6.8MB-18MB-31MB over 22) + * com.android.providers.calendar / u0a2 / v22: + TOTAL: 3.5% (7.3MB-7.7MB-8.0MB/5.9MB-6.5MB-6.9MB over 10) + Imp Bg: 0.32% + Service: 3.2% (7.3MB-7.7MB-8.0MB/5.9MB-6.5MB-6.9MB over 10) + Receiver: 0.01% + (Cached): 69% (4.7MB-6.6MB-7.8MB/3.5MB-5.5MB-6.7MB over 23) + * com.amazon.mShop.android / u0a104 / v5030102: + TOTAL: 2.7% (25MB-40MB-47MB/24MB-37MB-43MB over 6) + Service: 2.6% (25MB-40MB-47MB/24MB-37MB-43MB over 6) + Receiver: 0.15% + (Cached): 97% (25MB-33MB-48MB/24MB-31MB-44MB over 46) + * com.google.android.gm / u0a70 / v51001620: + TOTAL: 2.2% (209MB-209MB-209MB/203MB-203MB-203MB over 1) + Top: 0.48% (209MB-209MB-209MB/203MB-203MB-203MB over 1) + Imp Bg: 0.70% + Service: 1.0% + Receiver: 0.01% + (Last Act): 0.02% + (Cached): 94% (25MB-67MB-116MB/23MB-63MB-109MB over 61) + * com.google.android.googlequicksearchbox:search / u0a22 / v300404573: + TOTAL: 2.1% (66MB-66MB-66MB/63MB-63MB-63MB over 1) + Top: 1.4% (66MB-66MB-66MB/63MB-63MB-63MB over 1) + Imp Fg: 0.01% + Service: 0.66% + Receiver: 0.02% + (Cached): 98% (52MB-59MB-79MB/50MB-56MB-77MB over 56) + * com.google.android.calendar / u0a31 / v2015030452: + TOTAL: 1.4% + Imp Bg: 0.33% + Service: 1.1% + Receiver: 0.02% + (Cached): 80% (7.4MB-12MB-17MB/5.8MB-9.8MB-14MB over 18) + * com.android.vending / u0a16 / v80341100: + TOTAL: 1.3% (88MB-154MB-220MB/85MB-151MB-217MB over 2) + Top: 1.3% (88MB-154MB-220MB/85MB-151MB-217MB over 2) + Service: 0.06% + Receiver: 0.02% + (Last Act): 4.4% (46MB-68MB-89MB/45MB-66MB-87MB over 2) + (Cached): 11% (15MB-74MB-133MB/13MB-72MB-131MB over 2) + * com.google.android.apps.photos / u0a65 / v5616: + TOTAL: 0.94% + Service: 0.90% + Receiver: 0.04% + (Cached): 80% (9.2MB-12MB-17MB/7.5MB-11MB-15MB over 20) + * com.amazon.avod.thirdpartyclient / u0a107 / v451210: + TOTAL: 0.52% + Service: 0.49% + Receiver: 0.03% + (Cached): 97% (14MB-24MB-34MB/13MB-22MB-31MB over 40) + * com.google.android.gms.wearable / u0a8 / v7319438: + TOTAL: 0.51% + Imp Fg: 0.47% + Service: 0.04% + (Cached): 65% (4.7MB-6.5MB-8.2MB/3.6MB-4.2MB-5.4MB over 10) + * com.amazon.mShop.android.shopping / u0a103 / v5040011: + TOTAL: 0.50% + Service: 0.37% + Receiver: 0.13% + (Cached): 77% (13MB-17MB-21MB/11MB-15MB-19MB over 15) + * com.google.android.gms:car / u0a8 / v7319438: + TOTAL: 0.49% (7.1MB-7.1MB-7.1MB/4.3MB-4.3MB-4.3MB over 1) + Top: 0.05% + Imp Fg: 0.39% (7.1MB-7.1MB-7.1MB/4.3MB-4.3MB-4.3MB over 1) + Service: 0.05% + (Cached): 0.60% (6.6MB-6.6MB-6.6MB/3.6MB-3.6MB-3.6MB over 1) + * com.amazon.mp3 / u0a92 / v4033010: + TOTAL: 0.46% + Service: 0.43% + Receiver: 0.03% + (Cached): 84% (12MB-16MB-23MB/9.7MB-14MB-21MB over 25) + * com.android.chrome:privileged_process1 / u0a34 / v2272096: + TOTAL: 0.43% + Service: 0.04% + Service Rs: 0.39% + (Cached): 100% (2.9MB-4.0MB-4.9MB/1.7MB-2.9MB-3.9MB over 18) + * com.google.android.dialer / u0a10 / v20100: + TOTAL: 0.39% (93MB-93MB-93MB/89MB-89MB-89MB over 1) + Top: 0.23% (93MB-93MB-93MB/89MB-89MB-89MB over 1) + Imp Fg: 0.16% + (Cached): 16% (5.0MB-31MB-57MB/4.1MB-29MB-54MB over 2) + * com.google.android.apps.maps / u0a58 / v906101124: + TOTAL: 0.38% + Service: 0.33% + Receiver: 0.05% + (Cached): 69% (8.7MB-15MB-18MB/7.2MB-14MB-17MB over 8) + * com.google.android.youtube / u0a80 / v101451214: + TOTAL: 0.26% + Service: 0.26% + (Cached): 36% (15MB-22MB-29MB/13MB-19MB-27MB over 5) + * com.google.android.apps.fitness / u0a45 / v2015109100: + TOTAL: 0.26% + Service: 0.23% + Receiver: 0.02% + (Cached): 82% (3.9MB-6.4MB-9.2MB/2.8MB-5.3MB-7.9MB over 19) + * com.google.android.apps.enterprise.dmagent / u0a37 / v630: + TOTAL: 0.06% + Service: 0.06% + Receiver: 0.01% + (Cached): 2.2% (6.5MB-7.4MB-8.2MB/4.8MB-5.8MB-6.8MB over 2) + * com.audible.application / u0a95 / v3068: + TOTAL: 0.06% + Receiver: 0.06% + (Cached): 34% (14MB-16MB-19MB/11MB-14MB-17MB over 7) + * com.android.defcontainer / u0a5 / v22: + TOTAL: 0.06% + Imp Fg: 0.06% + (Cached): 0.12% + * com.google.android.music:main / u0a60 / v1847: + TOTAL: 0.04% + Top: 0.01% + Service: 0.02% + Receiver: 0.01% + (Cached): 9.8% (10MB-12MB-14MB/8.3MB-9.6MB-11MB over 2) + * com.google.android.apps.magazines / u0a61 / v2015040100: + TOTAL: 0.03% + Top: 0.02% + Receiver: 0.01% + (Cached): 8.7% (12MB-14MB-16MB/9.7MB-11MB-13MB over 2) + * com.google.android.videos / u0a77 / v37191: + TOTAL: 0.03% + Imp Fg: 0.01% + Service: 0.02% + (Cached): 1.3% (11MB-12MB-13MB/9.1MB-10MB-12MB over 2) + * com.google.android.apps.books / u0a28 / v30336: + TOTAL: 0.03% + Imp Fg: 0.01% + Service: 0.02% + (Cached): 1.3% (7.9MB-9.6MB-11MB/6.3MB-8.0MB-9.7MB over 2) + * com.google.android.keep / u0a71 / v3115: + TOTAL: 0.02% + Service: 0.01% + Receiver: 0.01% + (Cached): 11% (6.3MB-8.7MB-9.6MB/5.1MB-7.4MB-8.3MB over 4) + * com.android.chrome / u0a34 / v2272096: + TOTAL: 0.02% + Service: 0.01% + Receiver: 0.02% + (Cached): 90% (5.1MB-70MB-96MB/3.4MB-66MB-92MB over 15) + * com.google.android.apps.gcs / u0a94 / v14: + TOTAL: 0.02% + Service: 0.02% + (Cached): 17% (5.8MB-5.9MB-6.0MB/4.6MB-4.7MB-4.8MB over 2) + * com.android.chrome:privileged_process0 / u0a34 / v2272096: + TOTAL: 0.02% + Service: 0.01% + Receiver: 0.01% + (Cached): 73% (162MB-163MB-164MB/157MB-157MB-157MB over 13) + * com.android.chrome:sandboxed_process12 / u0a34 / v2272096: + TOTAL: 0.02% + Service: 0.01% + Receiver: 0.01% + (Cached): 73% (48MB-49MB-51MB/46MB-47MB-50MB over 13) + * com.google.android.apps.docs / u0a40 / v51410735: + TOTAL: 0.01% + Receiver: 0.01% + (Cached): 0.45% (10MB-10MB-10MB/9.3MB-9.3MB-9.3MB over 1) + * com.google.android.deskclock / u0a38 / v303: + TOTAL: 0.01% + Receiver: 0.01% + (Cached): 82% (2.5MB-3.3MB-4.3MB/1.7MB-2.3MB-3.2MB over 13) + * com.google.android.gm.exchange / u0a69 / v500065: + TOTAL: 0.01% + Imp Bg: 0.01% + (Cached): 27% (3.3MB-3.7MB-3.9MB/2.2MB-2.7MB-2.9MB over 6) + * com.android.cellbroadcastreceiver / u0a3 / v22: + TOTAL: 0.01% + Service: 0.01% + (Cached): 1.1% (3.5MB-3.5MB-3.5MB/2.5MB-2.5MB-2.5MB over 1) + * com.coulombtech / u0a106 / v26: + TOTAL: 0.01% + Receiver: 0.01% + (Cached): 21% (4.9MB-5.0MB-5.2MB/3.8MB-3.9MB-4.1MB over 2) + * com.softcoil.mms / u0a86 / v32: + TOTAL: 0.01% + (Cached): 0.25% + * com.udemy.android / u0a91 / v38: + TOTAL: 0.01% + Receiver: 0.01% + (Cached): 0.75% (9.8MB-9.8MB-9.8MB/8.5MB-8.5MB-8.5MB over 1) + * com.qualcomm.timeservice / u0a76 / v22: + (Cached): 16% (2.3MB-2.4MB-2.4MB/1.6MB-1.6MB-1.6MB over 4) + * com.lge.SprintHiddenMenu / 1000 / v22: + (Cached): 0.16% + * com.android.chrome:sandboxed_process13 / u0a34 / v2272096: + (Cached): 0.01% + * com.google.android.partnersetup / u0a13 / v22: + (Cached): 0.14% + * com.android.musicfx / u0a15 / v10400: + (Cached): 0.41% (2.5MB-2.5MB-2.5MB/1.6MB-1.6MB-1.6MB over 1) + * com.android.chrome:sandboxed_process9 / u0a34 / v2272096: + (Cached): 30% (34MB-34MB-34MB/32MB-32MB-32MB over 9) + * com.android.chrome:sandboxed_process11 / u0a34 / v2272096: + (Cached): 7.2% (56MB-56MB-56MB/54MB-54MB-54MB over 3) + +Run time Stats: + SOff/Norm: +32m52s226ms + SOn /Norm: +2h10m8s364ms + Mod : +17s930ms + TOTAL: +2h43m18s520ms + +Memory usage: + Kernel : 265MB (38 samples) + Native : 73MB (38 samples) + Persist: 262MB (90 samples) + Top : 190MB (325 samples) + ImpFg : 204MB (569 samples) + ImpBg : 754KB (345 samples) + Service: 93MB (1912 samples) + Receivr: 227KB (1169 samples) + Home : 66MB (12 samples) + LastAct: 30MB (255 samples) + CchAct : 220MB (450 samples) + CchCAct: 193MB (71 samples) + CchEmty: 182MB (652 samples) + Cached : 58MB (38 samples) + Free : 60MB (38 samples) + TOTAL : 1.9GB + ServRst: 50KB (278 samples) + + Start time: 2015-04-08 13:44:18 + Total elapsed time: +2h43m18s521ms (partial) libart.so +</pre> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/debug/valgrind.html b/zh-cn/devices/tech/debug/valgrind.html new file mode 100644 index 00000000..94ac00e4 --- /dev/null +++ b/zh-cn/devices/tech/debug/valgrind.html @@ -0,0 +1,65 @@ +<html devsite><head> + <title>使用 Valgrind</title> + <meta name="project_path" value="/_project.yaml"/> + <meta name="book_path" value="/_book.yaml"/> + </head> + <body> + <!-- + Copyright 2017 The Android Open Source Project + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + --> + +<p><a href="http://valgrind.org/">Valgrind</a> 工具套件包括 Memcheck（用于检测 C 和 C ++ 中与内存相关的错误）、Cachegrind（缓存分析器）、Massif（堆分析器）和其他几种工具。</p> + +<p class="note"><strong>注意</strong>：尽管您可以使用 Valgrind 对 Android 进行调试，但大多数 Android 平台开发人员都会使用 <a href="/devices/tech/debug/asan.html">AddressSanitizer</a>。</p> + +<h2 id="build-valgrind">构建 Valgrind</h2> +<p>要构建 Valgrind，请运行以下命令：</p> +<pre class="no-pretty-print"> +$ mmma -j6 external/valgrind +</pre> + +<h2 id="app-valgrind">在应用上使用</h2> +<p>要在某个应用上使用 Valgrind，请运行以下命令：</p> + +<pre class="no-pretty-print"> +$ adb shell setprop wrap.<em>app_name</em> "logwrapper valgrind" +$ adb shell am start -a android.intent.action.MAIN -n <em>app_name</em>/.MainActivity +</pre> + +<code><em>app_name</em></code> 必须是一个完全符合要求的名称，例如 <strong>com.google.example_app</strong>。 + +<h2 id="server-valgrind">在系统服务器上使用</h2> +<p>要使用 Valgrind 运行系统服务器，请运行以下命令：</p> + +<pre class="no-pretty-print"> +$ adb shell setprop wrap.system_server "logwrapper valgrind" +$ adb shell stop && adb shell start +</pre> + +<h2 id="symbols-valgrind">获取调试符号</h2> +<p>要获取调试符号，请将未剥离的库推送到 <code>/data/local/symbols</code>：</p> +<pre class="no-pretty-print"> +$ adb shell mkdir /data/local/symbols +$ adb push $OUT/symbols /data/local/symbols +</pre> + +<h2 id="boot-valgrind">在启动过程中使用</h2> +<p>要在启动过程中使用 Valgrind，请修改 <code>out/target/product/XXXX/root/init.rc</code>，具体方法是将</p> +<p><code>service example /system/bin/foo --arg1 --arg2</code></p> +<p>更改为：</p> +<p><code>service example /system/bin/logwrapper /system/bin/valgrind /system/bin/foo --arg1 --arg2</code></p> +<p>要查看效果，请创建一个 <code>boot.img</code> 并重新刷入设备。</p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/display/app-shortcuts.html b/zh-cn/devices/tech/display/app-shortcuts.html new file mode 100644 index 00000000..4e51a52d --- /dev/null +++ b/zh-cn/devices/tech/display/app-shortcuts.html @@ -0,0 +1,133 @@ +<html devsite><head> + <title>应用快捷方式</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 7.1.1 版本允许开发人员定义应用内特定操作的快捷方式，这些快捷方式可以显示在启动器中。这些<a href="https://developer.android.com/guide/topics/ui/shortcuts.html">应用快捷方式</a>可让用户在应用中快速启动常用或推荐的任务。 +</p> + +<h2 id="overview">概览</h2> + +<p> +每个快捷方式都会引用一个 intent，这些 intent 在用户选择相应快捷方式时会在应用中启动特定操作。可作为应用快捷方式的操作示例包括：</p> + +<ul> + <li>在地图应用中将用户导航到特定位置 + </li><li>在通讯应用中向朋友发送消息 + </li><li>在媒体应用中播放下一集电视节目 + </li><li>在游戏应用中加载上一个存档点</li></ul> + +<h2 id="examples-and-source">示例和源代码</h2> + +<p>您可以在以下文件中找到此功能的主要实现方式：</p> + +<pre>frameworks/base/services/core/java/com/android/server/policy/ShortcutManager.java +frameworks/base/services/core/java/com/android/server/pm/ShortcutPackage.java +frameworks/base/services/core/java/com/android/server/pm/ShortcutUser.java +frameworks/base/services/core/java/com/android/server/pm/ShortcutPackageInfo.java +frameworks/base/services/core/java/com/android/server/pm/ShortcutLauncher.java +frameworks/base/services/core/java/com/android/server/pm/ShortcutParser.java +frameworks/base/services/core/java/com/android/server/pm/ShortcutService.java +frameworks/base/services/core/java/com/android/server/pm/LauncherAppsService.java +frameworks/base/services/core/java/com/android/server/pm/ShortcutPackageItem.java +frameworks/base/core/java/com/android/server/backup/ShortcutBackupHelper.java +frameworks/base/core/java/android/content/pm/ShortcutManager.java +frameworks/base/core/java/android/content/pm/ShortcutServiceInternal.java +frameworks/base/core/java/android/content/pm/ShortcutInfo.java +frameworks/base/core/java/android/content/pm/LauncherApps.java +</pre> + +<p> +以下文件可提供支持功能（在 <code>ShortcutManager.java</code> 中称为隐藏 API）：</p> + +<pre> +packages/apps/Settings/src/com/android/settings/DevelopmentSettings.java +frameworks/base/packages/SystemUI/src/com/android/systemui/statusbar/policy/RemoteInputView.java +</pre> + +<p> +另外，Android 开放源代码项目启动器版本 3 支持以下快捷方式： +</p> + +<pre> +packages/apps/Launcher3/ +</pre> + +<p> +最后，有关公共 Javadoc，请查看以下文件： +</p> + +<pre>frameworks/base/core/java/android/content/pm/ShortcutManager.java +frameworks/base/core/java/android/content/pm/ShortcutInfo.java +frameworks/base/core/java/android/content/pm/LauncherApps.java +</pre> + +<h2 id="implementation">实现</h2> + +<p> +AOSP Launcher3 已经支持使用快捷方式。如果合作伙伴有自己的启动器，该启动器也应该支持使用快捷方式。 +</p> + +<ul> + <li>当用户在应用图标上执行某个手势（例如长按）时，启动器应显示与每个启动器活动图标相关联的动态和静态快捷方式。<br /> +快捷方式排序顺序在“快捷方式显示顺序”部分的 ShorctutManager Javadoc 中进行定义。例如，首先显示静态快捷方式，然后显示动态快捷方式。各组内的快捷方式按升序排列。 + </li><li>用户应能够拖动每个动态/静态快捷方式，并将其“固定”到主屏幕。 + </li><li>应备份和还原已经固定的快捷方式。（有关详细信息，请参阅 ShortcutManager 的 javadoc）</li><li>在通知中进行“内嵌回复”应在内部调用 ShortcutManager.onApplicationActive。 +</li></ul> + +<p> +另外，一些 Google 移动服务 (GMS) 应用也有快捷方式。OEM 启动器应该显示这些应用的快捷方式，最好还能支持“<a href="https://support.google.com/nexus/answer/6118421">固定</a>”功能（或创建快捷方式图标）。 +</p> + +<p> +要详细了解如何通过与框架交互以执行上述操作，请参阅 Launcher3 源代码。 +</p> + +<h2 id="validation">验证</h2> + +<p> +使用以下 Android 兼容性测试套件 (CTS) 测试来确保您的功能（ShortcutManager 和 LauncherApps）版本可以正常运行：</p> + +<pre> +cts/tests/tests/shortcutmanager/ +cts/hostsidetests/shortcuts/ +</pre> + +<p> +请在以下位置查找用于实现 AOSP 的单元测试：</p> + +<pre>frameworks/base/services/tests/servicestests/ +</pre> + +<p> +其中包括：</p> + +<pre>src/com/android/server/pm/ShortcutManagerTest*.java +</pre> +<p> +您还可以针对快捷方式管理器采用 CTS Verifier 测试： +</p> + +<pre> +cts/apps/CtsVerifier/src/com/android/cts/verifier/notifications/ShortcutThrottlingResetActivity.java +</pre> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/display/circular-icons.html b/zh-cn/devices/tech/display/circular-icons.html new file mode 100644 index 00000000..05d9fb6f --- /dev/null +++ b/zh-cn/devices/tech/display/circular-icons.html @@ -0,0 +1,34 @@ +<html devsite><head> + <title>实现圆形图标</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 7.1.1 及更高版本支持使用圆形<a href="https://developer.android.com/guide/practices/ui_guidelines/icon_design_launcher.html">启动器图标</a>。默认情况下，系统不会启用圆形启动器图标。要在设备实现中使用圆形图标，您必须修改设备上的<a href="/source/add-device.html#use-resource-overlays">资源覆盖层</a>才能予以启用。</p> + +<p>您正在使用的覆盖层所处的资源文件位于 <code><a href="https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml">frameworks/base/core/res/res/values/config.xml</a></code> + +</p><p>要启用圆形图标，请将覆盖层文件中的 <code>config_useRoundIcon</code> 设置从 <code>false</code> 更改为 <code>true</code>：</p> + +<pre> +<!-- Flag indicating whether round icons should be parsed from the application manifest. --> +<bool name="config_useRoundIcon">true</bool> +</pre> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/display/hdr.html b/zh-cn/devices/tech/display/hdr.html new file mode 100644 index 00000000..edddca9a --- /dev/null +++ b/zh-cn/devices/tech/display/hdr.html @@ -0,0 +1,497 @@ +<html devsite><head> + <title>HDR 视频播放</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>高动态范围 (HDR) 视频是高品质视频解码领域的又一项前沿技术产物，它能够提供无与伦比的场景再现品质。它可以通过显著扩大亮度分量的动态范围（从当前的 100 cd/m2 到 1000 cd/m2）以及使用更宽的色彩空间 (BT 2020) 来达到这种效果。<sup></sup><sup></sup>如今，在电视领域中，HDR 是发展 4K 超高清显示技术的一项核心元素。</p> + +<p>Android 7.0 中已新增对 HDR 技术的初步支持，其中包括创建适当的常量以便发现和设置 HDR 视频通道。这意味着需要定义编解码器类型和显示模式，以及指定以何种方式将 HDR 数据传递至 MediaCodec 并将其提供给 HDR 解码器。HDR 技术仅在隧道视频播放模式下受支持。</p> + +<p>本文档的目的在于帮助应用开发者提供对 HDR 流播放技术的支持，并帮助原始设备制造商 (OEM) 和 SoC 供应商在 Android 7.0 上启用 HDR 功能。</p> + +<h2 id="technologies">支持的 HDR 技术</h2> + +<p>自 Android 7.0 版本开始，支持以下 HDR 技术。 + +<table> +<tbody> +<tr> +<th>技术</th> +<th>杜比视界</th> +<th>HDR 10</th> +<th>VP9-HLG</th> +<th>VP9-PQ</th> +</tr> +<tr> +<th>编解码器</th> +<td>AVC/HEVC +</td> +<td>HEVC +</td> +<td>VP9 +</td> +<td>VP9 +</td> +</tr> +<tr> +<th>传递函数</th> +<td>ST-2084 +</td> +<td>ST-2084 +</td> +<td>HLG</td> +<td>ST-2084 +</td> +</tr> +<tr> +<th>HDR 元数据类型 +</th> +<td>动态 +</td> +<td>静态 +</td> +<td>无 +</td> +<td>静态 +</td> +</tr> +</tbody> +</table> + +</p><p>在 Android 7.0 中，<b>仅定义了隧道模式下的 HDR 播放</b>，但设备可以新增相应的支持，以便使用不透明的视频缓冲区在 SurfaceView 上播放 HDR 视频。换而言之：</p> +<ul> +<li>尚无标准的 Android API 可用于检查设备是否可使用非隧道解码器来支持 HDR 播放。</li> +<li>播发具有 HDR 播放功能的隧道视频解码器必须在连接到具有 HDR 功能的显示屏时支持 HDR 播放功能。</li> +<li>AOSP Android 7.0 版本不支持 HDR 内容的 GL 合成。</li> +</ul> + +<h2 id="discovery">发现</h2> + +<p>要使用 HDR 播放功能，您需要具备支持 HDR 功能的解码器，并需连接到支持 HDR 功能的显示屏。有时，某些技术需要用到特定的提取器。</p> + +<h3 id="display">显示屏</h3> + +<p>应用应使用全新 <code>Display.getHdrCapabilities</code> API 来查询特定显示屏支持的 HDR 技术。这基本上就是 CTA-861.3 中定义的 EDID 静态元数据块中的信息：</p> + +<ul> + +<li><code>public Display.HdrCapabilities getHdrCapabilities()</code><br />返回显示屏的 HDR 功能。</li> + +<li><code>Display.HdrCapabilities</code><br /> +封装特定显示屏的 HDR 功能。例如，该显示屏支持哪些 HDR 类型以及有关所需亮度数据的详细信息。</li> +</ul> + +<p><b>常量：</b></p> + +<ul> +<li><code>int HDR_TYPE_DOLBY_VISION</code><br />支持杜比视界。</li> + +<li><code>int HDR_TYPE_HDR10</code><br />支持 HDR10/PQ。</li> + +<li><code>int HDR_TYPE_HLG</code><br />支持混合 Log-Gamma (HLG)。</li> + +<li><code>float INVALID_LUMINANCE</code><br />无效亮度值。</li> +</ul> + +<p><b>公开方法：</b></p> + +<ul> +<li><code>float getDesiredMaxAverageLuminance()</code><br /> +为此显示屏返回所需的内容最大帧平均亮度数据（以 cd/cd/m2 为单位）<sup></sup>。</li> + +<li><code>float getDesiredMaxLuminance()</code><br /> +为此显示屏返回所需的内容最大亮度数据（以 cd/cd/m2 为单位）<sup></sup>。</li> + +<li><code>float getDesiredMinLuminance()</code><br /> +为此显示屏返回所需的内容最小亮度数据（以 cd/cd/m2 为单位）<sup></sup>。</li> + +<li><code>int[] getSupportedHdrTypes()</code><br /> +获取此显示屏的受支持 HDR 类型（请参阅“常量”）。如果此显示屏不支持 HDR，则返回空数组。</li> +</ul> + +<h3 id="decoder">解码器</h3> + +<p>应用应使用现有的 <a href="https://developer.android.com/reference/android/media/MediaCodecInfo.CodecCapabilities.html#profileLevels"><code>CodecCapabilities.profileLevels</code></a> API 来验证是否支持新的具有 HDR 功能的配置文件：</p> + +<h4>杜比视界</h4> + +<p><code>MediaFormat</code> mime 常量： +</p><blockquote><pre> +String MIMETYPE_VIDEO_DOLBY_VISION +</pre></blockquote><p></p> + +<p><code>MediaCodecInfo.CodecProfileLevel</code> 配置文件常量：</p> +<blockquote><pre> +int DolbyVisionProfileDvavPen +int DolbyVisionProfileDvavPer +int DolbyVisionProfileDvheDen +int DolbyVisionProfileDvheDer +int DolbyVisionProfileDvheDtb +int DolbyVisionProfileDvheDth +int DolbyVisionProfileDvheDtr +int DolbyVisionProfileDvheStn +</pre></blockquote> + +<p>杜比视界视频层和元数据必须通过视频应用逐帧连接到单个缓冲区。此过程可通过具有杜比视界功能的 MediaExtractor 自动完成。</p> + +<h4>HEVC HDR 10</h4> + +<p><code>MediaCodecInfo.CodecProfileLevel</code> 配置文件常量：</p><p> +</p><blockquote><pre> +int HEVCProfileMain10HDR10 +</pre></blockquote> + +<h4>VP9 HLG 与 VP9 PQ</h4> + +<p><code>MediaCodecInfo.CodecProfileLevel</code> 配置文件常量：</p> +<blockquote><pre> +int VP9Profile2HDR +int VP9Profile3HDR +</pre></blockquote> + +<p>如果某个平台支持具备 HDR 功能的解码器，则该平台还应该支持具备 HDR 功能的提取器。</p> + +<p>只有隧道解码器才能确保播放 HDR 内容。通过非隧道解码器播放可能会导致 HDR 信息丢失，且内容会被压缩为 SDR 色域。</p> + +<h3 id="extractor">提取器</h3> + +<p>Android 7.0 支持实现各项 HDR 技术的以下容器：</p> + +<table> +<tbody> +<tr> +<th>技术</th> +<th>杜比视界</th> +<th>HDR 10</th> +<th>VP9-HLG</th> +<th>VP9-PQ</th> +</tr> +<tr> +<th>容器</th> +<td>MP4 +</td> +<td>MP4 +</td> +<td>WebM</td> +<td>WebM</td> +</tr> +</tbody> +</table> + +<p>该平台不支持探索（文件的）轨道是否需要 HDR 支持。应用可以解析编解码器专用数据，以确定轨道是否需要特定的 HDR 配置文件。</p> + +<h3 id="summary">摘要</h3> + +<p>各项 HDR 技术的组件要求如下表所示：</p> + +<div style="overflow:auto"> +<table> +<tbody> +<tr> +<th>技术 +</th> +<th>杜比视界</th> +<th>HDR 10</th> +<th>VP9-HLG</th> +<th>VP9-PQ</th> +</tr> +<tr> +<th>支持的 HDR 类型（显示屏）</th> +<td>HDR_TYPE_DOLBY_VISION +</td> +<td>HDR_TYPE_HDR10 +</td> +<td>HDR_TYPE_HLG +</td> +<td>HDR_TYPE_HDR10 +</td> +</tr> +<tr> +<th>容器（提取器） +</th> +<td>MP4 +</td> +<td>MP4 +</td> +<td>WebM</td> +<td>WebM</td> +</tr> +<tr> +<th>解码器 +</th> +<td>MIMETYPE_VIDEO_DOLBY_VISION +</td> +<td>MIMETYPE_VIDEO_HEVC +</td> +<td>MIMETYPE_VIDEO_VP9 +</td> +<td>MIMETYPE_VIDEO_VP9 +</td> +</tr> +<tr> +<th>配置文件（解码器） +</th> +<td>其中一个杜比配置文件</td> +<td>HEVCProfileMain10HDR10 +</td> +<td>VP9Profile2HDR 或 +VP9Profile3HDR +</td> +<td>VP9Profile2HDR 或 +VP9Profile3HDR +</td> +</tr> +</tbody> +</table> +</div> +<br /> + +<p>注意：</p> +<ul> +<li>杜比视界比特流以杜比实验室定义的方式打包到 MP4 容器中。只要应用将访问单元从相应的层打包到用于杜比实验室所定义的解码器的单个访问单元，应用就可以实施它们自己的具有杜比功能的提取器。</li> +<li>某个平台可能会支持具有 HDR 功能的提取器，但不支持具有 HDR 功能的相应解码器。</li> +</ul> + +<h2 id="playback">播放</h2> + +<p>当应用确认支持 HDR 播放后，它可以通过几乎与播放非 HDR 内容相同的方式播放 HDR 内容，但需注意以下方面：</p> + +<ul> +<li>对于杜比视界，无论特定的媒体文件/轨道是否需要具有 HDR 功能的解码器，都不可立即播放。应用必须提前获取此信息，或能够通过解析 MediaFormat 的编解码器专用数据区段来获取此信息。</li> +<li><code>CodecCapabilities.isFormatSupported</code> 不考虑是否需要隧道解码器功能来支持此类配置文件。</li> +</ul> + +<h2 id="enablinghdr">启用 HDR 平台支持</h2> + +<p>SoC 供应商和原始设备制造商(OEM) 必须采取进一步措施，才能让某款设备支持 HDR 平台。</p> + +<h3 id="platformchanges">Android 7.0 版本中针对 HDR 所做的平台更改</h3> + +<p>以下是原始设备制造商 (OEM) 和 SoC 供应商需知悉的平台（应用层/本地层）中的一些重要更改。</p> + +<h3 id="display">显示屏</h3> + +<h4>硬件合成器</h4> + +<p>具有 HDR 功能的平台必须支持将 HDR 内容与非 HDR 内容合成在一起。从 7.0 版开始，Android 不再对实际的合成特性和操作进行定义，但完成相应流程一般应遵循以下步骤：</p> +<ol> +<li>根据各层的颜色、母带和潜在的动态元数据，确定包含要合成的所有层的线性色彩空间/色域。 +<br />如果直接合成到显示屏，则可能需要与显示屏的色域相匹配的线性空间。</li> +<li>将所有层转换为普通色彩空间。</li> +<li>进行合成。</li> +<li>如果是通过 HDMI 显示，则需要：<ol style="list-style-type: lower-alpha"> +<li>确定合成场景的颜色、母带和潜在的动态元数据。</li> +<li>将产生的合成场景转换为导出的色彩空间/色域。</li></ol></li> +<li>如果直接在显示屏中显示，则将产生的合成场景转换为所需的显示信号，以生成该场景。 +</li></ol> + +<h4>Display Discovery</h4> + +<p>HDR Display Discovery 功能只能通过 HWC2 受支持。设备实施者必须选择性地启用随 Android 7.0 一起发布的 HWC2 适配器，以确保此功能正常发挥作用。因此，平台必须添加对 HWC2 的支持，或扩展 AOSP 框架以允许通过某种方式提供此信息。HWC2 首次采用一种全新的 API，可以向框架和应用传播 HDR 静态数据。</p> + +<h4>HDMI</h4> + +<ul> +<li>根据 <a href="https://standards.cta.tech/kwspub/published_docs/CTA-861.3-Preview.pdf">CTA-861.3</a> 第 4.2 节中定义的内容，连接的 HDMI 显示屏通过 HDMI EDID 播发其 HDR 功能。</li> +<li>以下是应使用的 EOTF 映射：<ul> +<li>ET_0 传统灰度系数 - SDR 亮度范围：未映射到任何 HDR 类型</li> +<li>ET_1 传统灰度系数 - HDR 亮度范围：未映射到任何 HDR 类型</li> +<li>ET_2 SMPTE ST 2084 - 映射到 HDR 类型 HDR10</li></ul></li> +<li>通过 HDMI 实现杜比视界或 HLG 的信号支持（根据其相关机构的定义）。</li> +<li>请注意，HWC2 API 会使用浮点期望亮度值，因此 8 位 EDID 值必须以合适的方式进行转换。</li></ul> + +<h3 id="decoders">解码器</h3> + +<p>平台必须添加具有 HDR 功能的隧道解码器，并播发其 HDR 支持。通常，具有 HDR 功能的解码器必须：</p> +<ul> +<li>支持隧道解码 (<code>FEATURE_TunneledPlayback</code>)。</li> +<li>支持 HDR 静态元数据 (<code>OMX.google.android.index.describeHDRColorInfo</code>) 以及向显示屏/硬件合成器传播这类数据。对于 HLG，必须将适当的元数据提交至显示屏。</li> +<li>支持色彩描述 (<code>OMX.google.android.index.describeColorAspects</code>) 以及向显示屏/硬件合成器传播这类描述。</li> +<li>支持根据相关标准定义的 HDR 内嵌元数据。</li> +</ul> + +<h4>杜比视界解码器支持</h4> + +<p>要支持杜比视界，平台必须添加具有杜比视界功能的 HDR OMX 解码器。基于杜比视界的特性，这通常是由一个或多个 AVC 和/或 HEVC 解码器以及合成器封装的解码器。此类解码器必须：</p> +<ul> +<li>支持 mime 类型的“视频/杜比视界”。</li> +<li>播发支持的杜比视界配置文件/级别。</li> +<li>接受包含杜比实验室定义的所有层的子访问单元的访问单元。</li> +<li>接受由杜比实验室定义的编解码器专用数据。例如，包括杜比视界配置文件/级别的数据，也有可能是针对内部解码器的编解码器专用数据。</li> +<li>根据杜比实验室的要求，支持在杜比视界配置文件/级别之间进行自适应切换。</li> +</ul> + +<p>在配置解码器时，实际的杜比配置文件不会被传送到编解码器。只有在解码器启动后，配置文件才能通过编解码器专用数据完成传送。一个平台可选择支持多个杜比视界解码器：一个用于 AVC 配置文件，另一个用于 HEVC 配置文件，以便能够在配置时间内初始化底层编解码器。如果单个杜比视界解码器同时支持两种类型的配置文件，那么它还必须支持以自适应方式在这两种类型之间进行动态切换。</p> +<p>如果一个平台不仅支持一般的 HDR 解码器，而且还提供具有杜比视界功能的解码器，那么它必须：</p> + +<ul> +<li>提供杜比视界感知提取器（即使该平台不支持 HDR 播放）。</li> +<li>提供至少支持杜比视界配置文件 X/级别 Y 的解码器。</li> +</ul> + +<h4>HDR10 解码器支持</h4> + +<p>要支持 HDR10，平台必须添加一个支持 HDR10 的 OMX 解码器。上述解码器通常是采用隧道技术且支持解析和处理 HDMI 相关元数据的 HEVC 解码器。此类解码器（除了支持一般的 HDR 解码器之外）必须：</p> +<ul> +<li>支持 mime 类型“video/hevc”。</li> +<li>播发支持的 HEVCMain10HDR10。要支持 HEVCMain10HRD10 配置文件，解码器还需要支持 HEVCMain10 配置文件，而该 HEVCMain10 配置文件需要支持相同级别的 HEVCMain 配置文件。</li> +<li>支持解析母带元数据序列参数集 (SEI) 块，以及补充增强信息 (SPS) 中包含的与 HDR 相关的其他信息。</li> +</ul> + +<h4>VP9 解码器支持</h4> + +<p>要支持 VP9 HDR，平台必须添加一个支持 VP9 Profile2 的 HDR OMX 解码器。上述解码器通常是采用隧道技术且支持处理 HDMI 相关元数据的 VP9 解码器。此类解码器（除了支持一般的 HDR 解码器之外）必须：</p> +<ul> +<li>支持 mime 类型“video/x-vnd.on2.vp9”。</li> +<li>播发支持的 VP9Profile2HDR。要支持 VP9Profile2HDR 配置文件，解码器还需要支持相同级别的 VP9Profile2 配置文件。</li> +</ul> + +<h3 id="extractors">提取器</h3> + +<h4>杜比视界提取器支持</h4> + +<p>支持杜比视界解码器的平台必须支持用于提取杜比视频内容的杜比提取器（也称 Dolby Extractor）。</p> +<ul> +<li>常规的 MP4 提取器只能从文件中提取基本层，而无法提取增强层或元数据层。因此，需要使用特殊的杜比提取器来从文件中提取数据。</li> +<li>杜比提取器必须为每个杜比视频轨道（组）公开显示 1 到 2 个轨道：<ul> +<li>用于组合的 2/3 层杜比流的具有“视频/杜比视界”类型的杜比视界 HDR 轨道。杜比实验室将定义 HDR 轨道的访问单元格式，该格式定义了如何将访问单元从基本层/增强层/元数据层打包到将被解码为单个 HDR 帧的单个缓冲区。</li> +<li>如果杜比视界视频轨道包含单独的（向后兼容的）基本层 (BL)，则提取器还必须将其显示为单独的“video/avc”或“video/hevc”轨道。提取器必须为此轨道提供常规的 AVC/HEVC 访问单元。</li> +<li>BL 轨道必须与 HDR 轨道具有相同的轨道唯一 ID（“轨道 ID”），以便应用了解它们是同一视频的两种编码形式。</li> +<li>应用可以根据平台的能力决定选择哪个轨道。</li> +</ul> +</li> +<li>杜比视界配置文件/级别必须以 HDR 轨道的轨道格式显示。</li> +<li>如果平台提供了具有杜比视界功能的解码器，那么即使它不支持 HDR 播放，也必须提供杜比视界感知提取器。</li> +</ul> + +<h4>HDR10 和 VP9 HDR 提取器支持</h4> + +<p>要支持 HDR10 或 VP9 HLG，对于提取器并没有额外的要求。平台必须提供 MP4 提取器以支持 MP4 中的 VP9 PQ。HDR 静态元数据必须传播到 VP9 PQ 比特流中，以便将此元数据传递到 VP9 PQ 解码器，并通过正常的 MediaExtractor => MediaCodec 通道传递到显示屏。</p> + +<h3 id="stagefright">扩展 Stagefright 以支持杜比视界</h3> + +<p>平台必须为 Stagefright 添加杜比视界格式支持：</p> +<ul> +<li>支持压缩端口的端口定义查询。</li> +<li>支持 DV 解码器的配置文件/级别枚举。</li> +<li>支持显示对应 DV HDR 轨道的 DV 配置文件/级别。</li> +</ul> + +<h2 id="implementationnotes">技术方面的具体实施细节</h2> + +<h3 id="hdr10decoder">HDR10 解码器通道</h3> + +<p><img src="../images/hdr10_decoder_pipeline.png"/></p> + +<p class="img-caption"><strong>图 1.</strong> HDR10 通道</p> + +<p>HDR10 比特流会打包到 MP4 容器中。应用会使用常规的 MP4 提取器来提取帧数据，并将其发送到解码器。</p> + +<ul> +<li><b>MPEG4 提取器</b><br /> +MPEG4Extractor 会将 HDR10 比特流识别为正常的 HEVC 流，系统将提取具有类型“video/HEVC”的 HDR 轨道。该框架会选择支持 Main10HDR10 配置文件的 HEVC 视频解码器来解码该轨道。</li> + +<li><b>HEVC 解码器</b><br /> +HDR 信息位于 SEI 或 SPS 中。HEVC 解码器会首先接收包含 HDR 信息的帧。随后，解码器会将 HDR 信息提取出来，并通知应用它正在解码 HDR 视频。HDR 信息会以解码器输出格式进行捆绑，这些信息稍后会传播到表层。</li> +</ul> + +<h4>供应商操作</h4> +<ol> +<li>播发支持的 HDR 解码器配置文件和级别 OMX 类型。例如：<br /> +<code>OMX_VIDEO_HEVCProfileMain10HDR10</code>（和 <code>Main10</code>）</li> +<li>实现对以下索引的支持： +'<code>OMX.google.android.index.describeHDRColorInfo</code>'</li> +<li>实现对以下索引的支持： +'<code>OMX.google.android.index.describeColorAspects</code>'</li> +<li>实现对 SEI 解析母带元数据的支持。</li> +</ol> + +<h3 id="dvdecoder">杜比视界解码器通道</h3> + +<p><img src="../images/dolby_vision_decoder_pipleline.png"/></p> + +<p class="img-caption"><strong>图 2.</strong> 杜比视界通道</p> + +<p>将杜比比特流打包到由杜比实验室定义的 MP4 容器中。在理论上，应用可以使用常规 MP4 提取器独立提取基本层、增强层和元数据层；然而，这不符合当前的 Android MediaExtractor/MediaCodec 模式。</p> + +<ul> +<li>杜比提取器： +<ul> +<li>杜比提取器可识别杜比比特流，并会针对每个杜比视频轨道（组）将不同的层显示为 1 到 2 个轨道： +<ul> +<li>用于组合的 2/3 层杜比流的具有“视频/杜比视界”类型的 HDR 轨道。杜比实验室将定义 HDR 轨道的访问单元格式，该格式定义了如何将访问单元从基本层/增强层/元数据层打包到单个缓冲区（将被解码为单个 HDR 帧）。</li> +<li>（只有当 BL 是向后兼容时才可选）BL 轨道只包含必须通过常规 MediaCodec 解码器（例如：AVC/HEVC 解码器）才能解码的基本层。提取器应为此轨道提供常规的 AVC/HEVC 访问单元。此 BL 轨道必须与杜比轨道具有相同的轨道唯一 ID（“轨道 ID”），以便应用了解它们是同一视频的两种编码形式。</li> +</ul> +</li><li>应用可以根据平台的能力决定选择哪个轨道。</li> +<li>由于 HDR 轨道具有特定的 HDR 类型，因此，框架将选择杜比视频解码器来解码该轨道。BL 轨道将由常规 AVC/HEVC 视频解码器来解码。</li> +</ul> + +</li><li>杜比解码器：<ul> +<li>杜比解码器会接收包含所有层（EL+BL+MD 或 BL+MD）所需访问单元的访问单元。</li> +<li>单个层的 CSD（编解码器专用数据，例如 SPS+PPS+VPS）信息可以打包成 1 个杜比所定义的 CSD 帧。前提是，需要有一个单个的 CSD 帧。</li> +</ul> +</li></ul> + +<h4>杜比操作</h4> +<ol> +<li>对抽象杜比解码器（即 HDR 解码器预期的缓冲格式）的各种杜比容器方案（例如：BL+EL+MD）的访问单元的打包进行定义。</li> +<li>定义抽象杜比解码器的 CSD 打包。</li> +</ol> + +<h4>供应商操作</h4> +<ol> +<li>实施杜比提取器。此任务也可以由杜比实验室来完成。</li> +<li>将杜比提取器集成到框架中。入口点是 <code>frameworks/av/media/libstagefright/MediaExtractor.cpp</code>。</li> +<li>声明 HDR 解码器配置文件和级别 OMX 类型。例如：<code>OMX_VIDEO_DOLBYPROFILETYPE</code> 和 <code>OMX_VIDEO_DOLBYLEVELTYP</code>。</li> +<li>实现对以下索引的支持： +<code>'OMX.google.android.index.describeColorAspects</code>'</li> +<li>将动态 HDR 元数据传播到每个帧中的应用和表层。通常，这种信息必须打包成杜比实验室定义的解码帧，因为 HDMI 标准不提供将其传递给显示屏的途径。</li> +</ol> + +<h3 id="v9decoder">VP9 解码器通道</h3> + +<p><img src="../images/vp9-pq_decoder_pipleline.png"/></p> + +<p class="img-caption"><strong>图 3.</strong> VP9-PQ 通道</p> + +<p>VP9 比特流将按照 WebM 团队定义的方式打包到 WebM 容器中。在将帧发送到解码器之前，应用需要使用 WebM 提取器将 HDR 元数据从比特流中提取出来。</p> + +<ul> +<li>WebM 提取器：<ul> +<li>WebM 提取器从<a href="http://www.webmproject.org/docs/container/#location-of-the-colour-element-in-an-mkv-file">容器</a>中提取 HDR <a href="http://www.webmproject.org/docs/container/#colour">元数据</a>和帧。</li> +</ul> + +</li><li>VP9 解码器：<ul> +<li>解码器接收 Profile2 比特流，并将其解码为普通 VP9 流。</li> +<li>解码器接收任何来自框架的 HDR 静态元数据。</li> +<li>解码器通过 VP9 PQ 流的比特流访问单元接收静态元数据。</li> +<li>VP9 解码器必须能够将 HDR 静态/动态元数据传播到显示屏。</li> +</ul> +</li></ul> + +<h4>供应商操作</h4> + +<ol> +<li>实现对以下索引的支持：<code>OMX.google.android.index.describeHDRColorInfo</code></li> +<li>实现对以下索引的支持：<code>OMX.google.android.index.describeColorAspects</code></li> +<li>传播 HDR 静态元数据</li> +</ol> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/display/multi-window.html b/zh-cn/devices/tech/display/multi-window.html new file mode 100644 index 00000000..421527f0 --- /dev/null +++ b/zh-cn/devices/tech/display/multi-window.html @@ -0,0 +1,82 @@ +<html devsite><head> + <title>支持多窗口模式</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 7.0 及更高版本中，用户可以借助新的平台功能（多窗口模式）在设备屏幕上同时显示多个应用。除了默认实施的多窗口模式外，Android 还支持几个多窗口模式的变体：</p> + +<ul> +<li><strong>分屏</strong>是多窗口模式的基本实现方式，可为用户提供两个活动窗格来放置应用。 +</li><li><strong>自由窗口</strong>允许用户动态调整活动窗格大小，并在屏幕上显示两个以上的应用。 +</li><li><strong>画中画 (PIP) </strong>允许用户在与其他 Android 设备应用交互的同时，继续在小窗口中播放视频内容。</li> +</ul> + +<p> +为了实现多窗口模式功能，设备制造商在其设备的配置文件中设置了一个标记，用于启用或禁用多窗口模式支持。 +</p> + +<h2 id="implementation">实现</h2> +<p> +Android 7.0 及更高版本中默认启用多窗口模式支持要禁用此功能，请在 <a href="https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml">config.xml</a> 文件中将 <code>config_supportsMultiWindow</code> 标记设置为 false。 +</p> +<p> +对于声明 <code>ActivityManager.isLowRam()</code> 的设备，不论 <code>config_supportsMultiWindow</code> 标记为何值，都会禁用多窗口模式。 +</p> +<h3 id="split-screen">分屏</h3> +<p> +默认的多窗口模式体验是分屏模式，其中系统界面会从设备中间直接划分成两个横向或纵向屏幕。用户可以根据设备的屏幕方向左右或上下拖动分界线来调整窗口大小。 +</p> +<p> +然后，设备制造商可以选择是否要启用“自由窗口”或“画中画”模式。 +</p> +<h3 id="freeform">自由窗口</h3> +<p> +通过标记 <code>config_supportsMultiWindow</code> 启用标准多窗口模式后，设备制造商可以选择性允许启用自由窗口。此模式对于较大设备（如平板电脑）的制造商最为有用。 +</p> +<p> +要支持自由窗口模式，请启用 <a href="https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/content/pm/PackageManager.java">/android/frameworks/base/core/java/android/content/pm/PackageManager.java</a> 中的 +PackageManager#FEATURE_FREEFORM_WINDOW_MANAGEMENT 系统功能，并在 <a href="https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml">config.xml</a> 中将 <code>config_freeformWindowManagement</code> 设置为 true。 +</p> + +<pre> +<bool name="config_freeformWindowManagement">true</bool> +</pre> + +<h3 id="picture-in-picture">画中画</h3> +<p> +通过 <code>config_supportsMultiWindow</code> 标记启用标准多窗口模式后，设备制造商可以选择支持<a href="https://developer.android.com/training/tv/playback/picture-in-picture.html">画中画</a>功能，以允许用户在浏览其他活动时继续观看视频。虽然此功能主要针对 Android 电视设备，但其他设备类型也可能支持此功能。 +</p> +<p> +要支持画中画功能，请启用 <a href="https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/content/pm/PackageManager.java">/android/frameworks/base/core/java/android/content/pm/PackageManager.java</a> 中的 PackageManager#FEATURE_PICTURE_IN_PICTURE 系统功能。 +</p> +<h3 id="system-ui">系统界面</h3> +<p>如 <a href="https://developer.android.com/guide/topics/ui/multi-window.html#testing">https://developer.android.com/guide/topics/ui/multi-window.html#testing</a> 中所述，该功能支持所有标准系统界面。 +</p> +<h3 id="applications">应用</h3> +<p> +要在预加载应用中提供多窗口模式支持，请参阅 <a href="https://developer.android.com/guide/topics/ui/multi-window.html">Android 开发人员文档</a>。 +</p> +<h2 id="validation">验证</h2> +<p> +要验证多窗口模式的实现情况，设备制造商应运行 <a href="https://android.googlesource.com/platform/cts/+/master/hostsidetests/services/activitymanager/src/android/server/cts">CTS 测试</a>，并按照<a href="https://developer.android.com/guide/topics/ui/multi-window.html#testing">多窗口模式测试说明</a>进行操作。 +</p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/display/night-light.html b/zh-cn/devices/tech/display/night-light.html new file mode 100644 index 00000000..44d221a5 --- /dev/null +++ b/zh-cn/devices/tech/display/night-light.html @@ -0,0 +1,111 @@ +<html devsite><head> + <title>实现夜间模式</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 7.1.1 具备一种称为“夜间模式”的功能，可减少设备显示屏发出的蓝光量，以便达到更接近用户当前时间和地点的自然光效果。 +</p> +<p>夜间模式需要使用 <a href="/devices/graphics/implement-hwc.html">Hardware Composer HAL 2.0</a> (HWC 2) 来实现，它可应用传递到 <code>setColorTransform</code> 的矩阵以执行着色，而不会影响耗电量、性能和应用兼容性。 +</p> +<h2 id="implementation">实现</h2> +<p>设备制造商可以使用以下路径中定义的下列标记启用该功能的默认实现： +<code><a href="https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml"> +/android/frameworks/base/core/res/res/values/config.xml</a></code> + +</p><pre><!-- Control whether Night display is available. This should only be enabled + on devices with HWC 2 color transform support. --> + <bool name="config_nightDisplayAvailable">false</bool> + <!-- Default mode to control how Night display is automatically activated. + One of the following values (see NightDisplayController.java): + 0 - AUTO_MODE_DISABLED + 1 - AUTO_MODE_CUSTOM + 2 - AUTO_MODE_TWILIGHT + --> + <integer name="config_defaultNightDisplayAutoMode">0</integer> + <!-- Default time when Night display is automatically activated. + Represented as milliseconds from midnight (e.g. 79200000 == 10pm). --> + <integer name="config_defaultNightDisplayCustomStartTime">79200000</integer> + <!-- Default time when Night display is automatically deactivated. + Represented as milliseconds from midnight (e.g. 21600000 == 6am). --> + <integer name="config_defaultNightDisplayCustomEndTime">21600000</integer> +</pre> +<p> +这段代码包含用于框架、系统服务、SystemUI 和设置的代码： +</p> +<pre>platform/frameworks/base/core +├ java/android/provider/Settings.java +├ java/com/android/internal/app/NightDisplayController.java +└ res/res/values/config.xml + +platform/frameworks/base/proto/src/metrics_constants.proto + +platform/frameworks/base/services +├ core/java/com/android/server/display/DisplayManagerService.java +├ core/java/com/android/server/display/DisplayTransformManager.java +├ core/java/com/android/server/display/NightDisplayService.java +└ java/com/android/server/SystemServer.java + +platform/frameworks/base/packages/SystemUI +├ res/drawable/ic_qs_night_display_off.xml +├ res/drawable/ic_qs_night_display_on.xml +├ res/values/strings.xml +└ src/com/android/systemui/qs/tiles/NightDisplayTile.java + +platform/packages/apps/Settings +├ AndroidManifest.xml +├ res/drawable/ic_settings_night_display.xml +├ res/values/strings.xml +├ res/xml/display_settings.xml +├ res/xml/night_display_settings.xml +├ src/com/android/settings/Settings.java +├ src/com/android/settings/dashboard/conditional/NightDisplayCondition.java +├ src/com/android/settings/display/NightDisplayPreference.java +└ src/com/android/settings/display/NightDisplaySettings.java +</pre> + +<h2 id="ui-features">界面功能</h2> +<p> +由于夜间模式是面向用户的功能，因此用户需要能够掌控这项功能。 + Android 开放源代码项目 (AOSP) <a href="https://android.googlesource.com/platform/packages/apps/Settings/">packages/apps/Settings</a> 项目中提供了全面的设置实现方法，以供设备制造商在实现其设置时参考。 +</p> +<h3 id="settings">设置</h3> +<p>用户可以在“设置”>“显示”>“夜间模式”中设置夜间模式。<em></em>在设置页面中，用户可以了解夜间模式，设置其时间安排以及开启或关闭夜间模式。 +</p> +<ul> + <li><strong>自动开启</strong> + <ul> + <li><strong>永不</strong>：夜间模式一律不自动开启，且必须通过手动切换<strong>开启/关闭</strong>开关来启用。</li> + <li><strong>自定义时间安排</strong>：夜间模式在指定的<strong>开始时间</strong>（默认为晚上 10:30）开启，并在指定的<strong>结束时间</strong>（默认为早上 6:30）关闭。</li> + <li><strong>日落到日出</strong>：在日落时开启夜间模式，在日出时关闭夜间模式。日出和日落的时间取决于设备所处的位置和当地的时节。</li> + </ul> + </li> + <li><strong>开启/关闭</strong>：用于控制夜间模式当前状态的切换开关。此状态遵循现有的自动规则。例如，如果用户在下午 5:30 开启夜间模式（早于自动规则的开启时间，即晚上 10:30），则系统依然会在早上 6:30 关闭夜间模式。如果用户在早上 5:30 关闭夜间模式（早于自动规则的关闭时间，即早上 6:30），则系统依然会在晚上 10:30 开启夜间模式。</li> + <li><strong>信息性文本</strong>：向用户介绍夜间模式的功能和原理。</li> +</ul> +<h3 id="settings-conditional">设置条件语句</h3> +<p> +当夜间模式处于开启状态时，用户可以在“设置”顶部看到。 +</p> +<h3 id="quick-settings-tile">“快捷设置”图块</h3> +<p> +您可以通过“快捷设置”图块执行相应操作，也可以通过“设置”>“显示”>“夜间模式”中的<strong>开启/关闭</strong>切换开关执行相应操作，两者效果是一样的。<em></em> +</p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/ota/index.html b/zh-cn/devices/tech/ota/index.html new file mode 100644 index 00000000..0568cd4f --- /dev/null +++ b/zh-cn/devices/tech/ota/index.html @@ -0,0 +1,108 @@ +<html devsite><head> + <title>OTA 更新</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 设备可以接收和安装系统和应用软件的无线 (OTA) 更新。设备可在特殊的恢复分区中使用软件解压缩下载的更新包并将其应用于系统的其余部分。</p> +<p>本节介绍这些软件包的结构，并提供用于构建软件包的工具。它适用于希望将 OTA 更新系统用于新的 Android 设备以及正在构建更新软件包以用于已发布设备的开发人员。OTA 更新旨在升级基础操作系统和系统分区上安装的只读应用；这些更新不会影响用户从 Google Play 安装的应用。<i></i> +</p> +<p>本节介绍 Android 5.x 版本中的 OTA 系统。有关从旧版本移植 OTA 相关代码的帮助信息，请参阅<a href="#migrating">从以往版本中迁移</a>。 +</p> + +<h2 id="android-device-layout">Android 设备布局</h2> +<p>Android 设备上的闪存空间通常包含以下分区。</p> + +<dl> +<dt>引导</dt> +<dd>包含 Linux 内核和最小的根文件系统（加载到 RAM 磁盘）。它装载了系统和其它分区，并启动位于系统分区上的运行时。</dd> +<dt>系统</dt> +<dd>包含在 Android 开源项目 (AOSP) 上提供源代码的系统应用和库。在正常操作期间，此分区被装载为只读分区；其内容仅在 OTA 更新期间更改。</dd> +<dt>供应商</dt> +<dd>包含在 Android 开源项目 (AOSP) 上未提供源代码的系统应用和库。<em></em>在正常操作期间，此分区被装载为只读分区；其内容仅在 OTA 更新期间更改。</dd> +<dt>用户数据</dt> +<dd>存储由用户安装的应用所保存的数据等。OTA 更新过程通常不会触及该分区。</dd> +<dt>缓存</dt> +<dd>几个应用使用的临时保留区域（访问此分区需要使用特殊的应用权限），用于存储下载的 OTA 更新包。其他程序也可使用该空间，但是此类文件可能会随时消失。安装某些 OTA 更新包可能会导致此分区被完全擦除。</dd> +<dt>恢复</dt> +<dd>包含第二个完整的 Linux 系统，其中包括一个内核和特殊的恢复二进制文件（该文件可读取一个软件包并使用其内容来更新其他分区。）</dd> +<dt>其他</dt> +<dd>执行恢复操作时使用的微小分区，可在应用 OTA 更新包并重新启动设备时，隐藏某些进程的信息。</dd></dl> + +<h2 id="life-ota-update">OTA 更新过程</h2> +<p>典型 OTA 更新包含以下步骤：</p> +<ol> +<li>设备会与 OTA 服务器进行定期确认，并被告知是否有更新可用，包括更新软件包的 URL 和向用户显示的描述字符串。</li> +<li>将更新下载到缓存或数据分区，并根据 <code>/system/etc/security/otacerts.zip</code> 中的证书验证加密签名。系统提示用户安装更新。</li> +<li>设备重新启动进入恢复模式，引导恢复分区中的内核和系统启动，而非引导分区中的内核。</li> +<li>恢复分区的二进制文件由 init 启动。它会在 <code>/cache/recovery/command</code> 中寻找将其指向下载软件包的命令行参数。 +</li> +<li>恢复操作会根据 <code>/res/keys</code> （包含在恢复分区中的 RAM 磁盘的一部分）中的公钥来验证软件包的加密签名。</li> +<li>从软件包中提取数据，并根据需要使用该数据更新引导、系统和/或供应商分区。系统分区上其中一个新文件包含新恢复分区内容。</li> +<li>设备正常重启。<ol style="list-style-type:lower-alpha"> +<li>加载最新更新的引导分区，在最新更新的系统分区中装载并开始执行二进制文件。</li> +<li>作为正常启动的一部分，系统会根据所需内容（预先存储为 <code>/system</code> 中的一个文件）检查恢复分区的内容。二者内容不同，所以恢复分区会被所需内容重新刷写。（在后续引导中，恢复分区已经包含新内容，因此无需重新刷写。）</li> +</ol></li> +</ol> +<p>系统更新完成！</p> + +<h2 id="migrating">从更早版本迁移</h2> + +<p>当从 Android 2.3/3.0/4.0 版本进行迁移时，主要变化是将设备专属的功能从一组具有预定义名称的 C 函数转换为 C++ 对象。下表列出了用途大致相同的旧函数和新方法：</p> + +<table> +<tbody> +<tr> +<th>C 函数</th> +<th>C ++ 方法</th> +</tr> +<tr> +<td>device_recovery_start()</td> +<td>Device::RecoveryStart()</td> +</tr> +<tr> +<td>device_toggle_display()<br /> +device_reboot_now()<br /> +</td> +<td>RecoveryUI::CheckKey()<br /> +(also RecoveryUI::IsKeyPressed())<br /> +</td> +</tr> +<tr> +<td>device_handle_key()</td> +<td>Device::HandleMenuKey()</td> +</tr> +<tr> +<td>device_perform_action()</td> +<td>Device::InvokeMenuItem()</td> +</tr> +<tr> +<td>device_wipe_data()</td> +<td>Device::WipeData()</td> +</tr> +<tr> +<td>device_ui_init()</td> +<td>ScreenRecoveryUI::Init()</td> +</tr> +</tbody> +</table> + +<p>将旧函数转化为新方法应尽量简单直观。不要忘记添加新的 <code>make_device()</code> 函数来创建并返回新设备子类的实例。</p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/ota/inside_packages.html b/zh-cn/devices/tech/ota/inside_packages.html new file mode 100644 index 00000000..8d58080b --- /dev/null +++ b/zh-cn/devices/tech/ota/inside_packages.html @@ -0,0 +1,175 @@ +<html devsite><head> + <title>OTA 软件包内部</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>系统从 <code>bootable/recovery/updater +</code> 构建更新程序二进制文件并将其用于 OTA 更新包。</p>更新包本身是包含可执行二进制文件 <code>META-INF/com/google/android/update-binary +</code> 的 .zip 文件（<code>ota_update.zip</code>、<code>incremental_ota_update.zip</code>）。 + +<p>更新程序包含多个内建函数和一个可扩展脚本语言 (<b>Edify</b>) 解释器，该脚本语言支持用于执行更新相关的典型任务的命令。更新程序从 .zip 压缩包文件中查找 <code>META-INF/com/google/android/updater-script</code> 文件中的脚本。</p> + +<p class="note"><strong>注意</strong>：Edify 脚本和/或内建函数并不常用，但当您需要调试更新文件时，这会很有帮助。</p> + +<h2 id="edify-syntax">Edify 语法</h2> +<p>Edify 脚本是一个单一的表达式，其中的所有值都是字符串。在布尔上下文中，空字符串为 False，其他所有字符串均为 True。<i></i><i></i>Edify 支持以下运算符（具有常规含义）：</p> + +<pre> +(<i>expr</i> ) + <i>expr</i> <b>+</b> <i>expr</i> # string concatenation, not integer addition + <i>expr</i> <b>==</b> <i>expr</i> + <i>expr</i> <b>!=</b> <i>expr</i> + <i>expr</i> <b>&&</b> <i>expr</i> + <i>expr</i> <b>||</b> <i>expr</i> + ! <i>expr</i> + if <i>expr</i> <b>then</b> <i>expr</i> <b>endif</b> + if <i>expr</i> <b>then</b> <i>expr</i> <b>else</b> <i>expr</i> <b>endif</b> + <i>function_name</i><b>(</b><i>expr</i><b>,</b> <i>expr</i><b>,</b><i>...</i><b>)</b> + <i>expr</i><b>;</b> <i>expr</i> +</pre> + +<p><i></i>由非保留字符 az、AZ、0-9 _、:、/、. 组成的任何字符串均视为字符串字面量。（保留字为 <b>if else</b>、then <b>endif</b>。）字符串字面量也可以用双引号括起来；通过这种方法可以使用空格和上述集合之外的其他字符来创建值。\n、\t、\“ 和 \\ 充当带引号的字符串中的转义字符，\x## 亦如此。<i></i></p> +<p>&& 和 || 为短路运算符；如果逻辑结果由左侧确定，则不评估右侧。下面两个表达式是对等的：</p> +<pre> +<i>e1</i> <b>&&</b> <i>e2</i> +<b>if</b> <i>e1</i> <b>then</b> <i>e2</i> <b>endif</b></pre> +<p>分号“;”运算符是序列点；表示要先评估左侧，再评估右侧。它的值是右侧表达式的值。分号也可以出现在表达式之后，其效果与 C 风格语句相仿：</p> + +<pre> +<b>prepare(); +do_other_thing("argument"); +finish_up();</b> +</pre> + +<h2 id="builtin-functions">内建函数</h2> +<p>大部分更新功能都包含在可供脚本执行的函数中。（严格来说，这些是“宏”，而不是 Lisp 意义上的函数，因为它们不需要评估所有参数。）<i></i><i></i>除非另有说明，函数在成功时返回 <b>True</b>，出错时返回 <b>False</b>。如果您希望在出错时中止脚本执行，请使用 <code>abort()</code> 和/或 <code>assert()</code> 函数。也可以扩展更新程序中的可用函数集，以提供<a href="/devices/tech/ota/device_code.html">特定于设备的功能</a>。 + +</p><dl> +<dt><code>abort([<i>msg</i>])</code></dt> +<dd>使用可选的 msg 立即中止脚本执行。<i></i>如果用户打开了文本显示功能，msg 将出现在恢复日志和屏幕上。<i></i></dd> +<dt><code>assert(<i>expr</i>[, <i>expr</i>, ...])</code></dt> +<dd>依序评估每个 expr。<i></i>如果出现 false，则立即中止执行并显示“assert failed”和失败的表达式的源文本。</dd> +<dt><code>apply_patch(<i>src_file</i>, <i>tgt_file</i>, <i>tgt_sha1</i>, <i> +tgt_size</i>, <i>patch1_sha1</i>, <i>patch1_blob</i>, [...])</code></dt> +<dd>将二进制补丁程序应用于 src_file 以生成 tgt_file。<i></i><i></i>如果所需的目标文件与源文件相同，则传递“-”作为 tgt_file。tgt_sha1 和 tgt_size 分别是目标文件的预期最终 SHA1 哈希值和文件大小。<i></i><i></i><i></i>其余参数必须成对出现：一个 SHA1 哈希值（40 个字符的十六进制字符串）和一个 Blob。如果源文件当前的内容含有给定的 SHA1，该 Blob 即为要应用的补丁程序。 +<p>打补丁以一种安全的方式完成，该方式可保证目标文件要么具有所需的 SHA1 哈希值和大小，要么不发生变化，而不会处于不可恢复的中间状态。如果在打补丁过程中进程中断，目标文件可能会处于中间状态；这时缓存分区中会存在一个副本，重新启动更新便可成功更新文件。</p> +<p>支持特殊语法将内存技术设备 (MTD) 分区的内容作为文件处理，以便为引导分区这样的原始分区打补丁。由于 MTD 分区没有文件结束标记，因此要读取该分区，您必须知道您要读取的数据量。您可以使用字符串“MTD:partition:size_1:sha1_1:size_2:sha1_2”作为文件名来读取给定的分区。<i></i><i></i><i></i><i></i><i></i>您必须至少指定一个（size，sha-1）对；如果您希望读取的内容有多种可能，则可以指定多个对。<i></i></p></dd> +<dt><code>apply_patch_check(<i>filename</i>, <i>sha1</i>[, <i>sha1</i>, ...]) +</code></dt> +<dd>如果 filename 的内容或缓存分区中的临时副本（如果存在）中的内容具有与给定的 sha1 值之一相等的 SHA1 校验和，则返回 True。sha1 值指定为 40 位十六进制数字。<i></i><i></i><i></i>此函数与 <code>sha1_check(read_file(<i>filename</i>), +<i>sha1</i> [, ...])</code> 的不同之处在于，它知道检查缓存分区副本。因此，即使文件被中断的 <code>apply_patch() update</code> 损坏，<code>apply_patch_check()</code> 仍会成功执行。</dd> +<dt><code>apply_patch_space(<i>bytes</i>)</code></dt> +<dd>如果至少有 bytes 字节暂存空间可用于应用二进制补丁程序，则返回 True。<i></i></dd> +<dt><code>concat(<i>expr</i>[, <i>expr</i>, ...])</code></dt> +<dd>评估每个表达式并将它们连接起来。在只有两个参数的特殊情况下，+ 运算符就是该函数的语法糖（但该函数形式可以包含任意数量的表达式）。表达式必须为字符串；该函数不能连接 Blob。</dd> +<dt><code>delete([<i>filename</i>, ...])</code></dt> +<dd>删除列出的所有 filename。<i></i>返回成功删除的文件数。</dd> +<dt><code>delete_recursive([<i>dirname</i>, ...])</code></dt> +<dd><i></i>递归删除 dirname 及目录中的所有内容。返回成功删除的目录数。</dd> +<dt><code>file_getprop(<i>filename</i>, <i>key</i>)</code></dt> +<dd><i></i><i></i><i></i>读取给定的 filename，将其解释为属性文件（例如：<code>/system/build.prop</code>），并返回给定 key 的值，如果 key 不存在，则返回空字符串。</dd> +<dt><code>format(<i>fs_type</i>, <i>partition_type</i>, <i>location</i>, <i> +fs_size</i>, <i>mount_point</i>)</code></dt> +<dd>重新格式化给定的分区。支持的分区类型如下： +<ul> +<li>fs_type =“yaffs2”和 partition_type =“MTD”。Location 必须为 MTD 分区的名称；将在该位置构建一个空的 yaffs2 文件系统。其余参数未使用。</li> +<li>fs_type =“ext4”和 partition_type =“EMMC”。Location 必须为该分区的设备文件。将在该位置构建一个空的 ext4 文件系统。<i></i>如果 fs_size 为零，则文件系统将占用整个分区。<i></i>如果 fs_size 为正数，则文件系统将占用分区的前 fs_size 个字节。<i></i>如果 fs_size 为负数，则文件系统将占用分区中除最后 |fs_size| 个字节以外的所有字节。<i></i><i></i></li> +<li>fs_type =“f2fs” 和 partition_type =“EMMC”。Location 必须为该分区的设备文件。fs_size<i></i> 必须为非负数。<i></i>如果 fs_size 为零，则文件系统将占用整个分区。如果 fs_size 为正数，则文件系统将占用分区的前 fs_size 个字节。<i></i><i></i></li> +<li>mount_point 应为文件系统的未来挂载点。</li></ul> +</dd> +<dt><code>getprop(<i>key</i>)</code></dt> +<dd>返回系统属性 key 的值（或者，如果未定义，则为空字符串）。<i></i>由恢复分区定义的系统属性值未必与主系统属性值相同。此函数返回恢复分区中的值。</dd> +<dt><code>greater_than_int(<i>a</i>, <i>b</i>)</code></dt> +<dd>当且仅当 (iff) a（解析为整数）大于 b（解析为整数）时，才返回 True。<i></i><i></i></dd> +<dt><code>ifelse(<i>cond</i>, <i>e1</i>[, <i>e2</i>])</code></dt> +<dd>评估 cond，如果为 True，则评估并返回 e1 的值，否则评估并返回 e2（如果存在）。<i></i><i></i><i></i>“if ... else ... then ... endif”结构就是此函数的语法糖。</dd> +<dt><code>is_mounted(<i>mount_point</i>)</code></dt> +<dd>当且仅当 mount_point 挂载文件系统时，才返回 True。<i></i></dd> +<dt><code>is_substring(<i>needle</i>, <i>haystack</i>)</code></dt> +<dd>当且仅当 needle 是 haystack 的子字符串时，才返回 True。<i></i><i></i></dd> +<dt><code>less_than_int(<i>a</i>, <i>b</i>)</code></dt> +<dd>当且仅当 a（解析为整数）小于 b（解析为整数）时，才返回 True。<i></i><i></i></dd> +<dt><code>mount(<i>fs_type</i>, <i>partition_type</i>, <i>name</i>, +<i>mount_point</i>)</code></dt> +<dd>在 mount_point 挂载 fs_type 的文件系统。<i></i><i></i> +partition_type<i></i> 必须为以下类型之一：<ul> +<li><b>MTD</b>。Name 是 MTD 分区的名称（例如：system、userdata；有关完整列表，请参见设备上的 <code>/proc/mtd</code>）。</li> +<li><b>EMMC。</b></li> +</ul> +<p>默认情况下，恢复分区不挂载任何文件系统（如果用户正在手动从 SD 卡安装软件包，则 SD 卡除外）；您的脚本必须挂载需要修改的所有分区。</p></dd> +<dt><code>package_extract_dir(<i>package_dir</i>, <i>dest_dir</i>)</code></dt> +<dd>从 package_dir 下的文件包中提取所有文件，并将它们写入 dest_dir 下相应的树形结构中。<i></i><i></i>所有现有文件都将被覆盖。</dd> +<dt><code>package_extract_file(<i>package_file</i>[, <i>dest_file</i>])</code> +</dt> +<dd>从更新包中提取单个 package_file 并将其写入 dest_file，如有必要，覆盖现有文件。<i></i><i></i>在没有 dest_file 参数的情况下，将更新包文件的内容作为二进制 blob 返回。<i></i></dd> +<dt><code>read_file(<i>filename</i>)</code></dt> +<dd>读取 filename 并将其内容作为二进制 Blob 返回。<i></i></dd> +<dt><code>rename(<i>src_filename</i>, <i>tgt_filename</i>)</code></dt> +<dd>将 src_filename 重命名为 tgt_filename。<i></i><i></i>系统会自动为 tgt_filename 创建必要的目录。<i></i>例如：<code> +rename("system/app/Hangouts/Hangouts.apk", +"system/priv-app/Hangouts/Hangouts.apk")</code>。</dd> +<dt><code>run_program(<i>path</i>[, <i>arg</i>, ...])</code></dt> +<dd>在 path 上执行二进制文件，以传递 arg。<i></i><i></i>返回程序的退出状态。</dd> +<dt><code>set_metadata(<i>filename</i>, <i>key1</i>, <i>value1</i>[, <i>key2 +</i>, <i>value2</i>, ...])</code></dt> +<dd>将给定 filename 的 key 设置为 value。<i></i><i></i>例如： +<code>set_metadata("/system/bin/netcfg", "uid", 0, "gid", 3003, "mode", 02750, +"selabel", "u:object_r:system_file:s0", "capabilities", 0x0)</code>。</dd> +<dt><code>set_metadata_recursive(<i>dirname</i>, <i>key1</i>, <i>value1</i>[, +<i>key2</i>, <i>value2</i>, ...])</code></dt> +<dd>递归地将给定 dirname 及其所有子项的 key 设置为 value。<i></i><i></i>例如：<code>set_metadata_recursive("/system", "uid", +0, "gid", 0, "fmode", 0644, "dmode", 0755, "selabel", +"u:object_r:system_file:s0", "capabilities", 0x0)</code>。</dd> +<dt><code>set_progress(<i>frac</i>)</code></dt> +<dd>在最新的 <code>show_progress()</code> 调用所定义的块内设置进度条的位置。frac 必须介于 [0.0，1.0] 的范围内。<i></i>进度条从不向后移动；向后移动的尝试会被忽略。</dd> +<dt><code>sha1_check(<i>blob</i>[, <i>sha1</i>])</code></dt> +<dd>该 blob 参数是 <code> +read_file()</code> 返回类型的 Blob 或 <code>package_extract_file() +</code> 的单参数形式的 Blob。<i></i>在没有 sha1 参数的情况下，此函数返回 Blob 的 SHA1 哈希值（作为 40 位十六进制字符串）。<i></i>在使用一个或多个 sha1 参数的情况下，如果 SHA1 哈希值等于其中一个参数，则该函数返回 SHA1 哈希值；如果与其中的任何一个参数都不相等，则返回空字符串。<i></i></dd> +<dt><code>show_progress(<i>frac</i>, <i>secs</i>)</code></dt> +<dd>在 secs 秒（必须为整数）内推动进度条向前移动下一个 frac 的长度。secs 可能为 0，在这种情况下，进度条不会自动向前移动，而是通过使用上面所定义的 <code> +set_progress()</code> 函数实现进度递增。<i></i><i></i><i></i></dd> +<dt><code>sleep(<i>secs</i>)</code></dt> +<dd>休眠 secs 秒（必须为整数）。<i></i></dd> +<dt><code>stdout(<i>expr</i>[, <i>expr</i>, ...])</code></dt> +<dd>评估每个表达式并将其值转储到 stdout。这在调试时很有用。</dd> +<dt><code>symlink(<i>target</i>[, <i>source</i>, ...])</code></dt> +<dd>将所有 source 创建为 target 的符号链接。<i></i><i></i></dd> +<dt><code>tune2fs(<i>device</i>[, <i>arg</i>, …])</code></dt> +<dd>调整 device 上的可调参数 arg。<i></i><i></i></dd> +<dt><code>ui_print([<i>text</i>, ...])</code></dt> +<dd>连接所有 text 参数并将结果输出到界面（如果用户已打开文本显示功能，界面上将显示该结果）。<i></i></dd> +<dt><code>unmount(<i>mount_point</i>)</code></dt> +<dd>卸载挂载在 mount_point 上的文件系统。<i></i></dd> +<dt><code>wipe_block_device(<i>block_dev</i>, <i>len</i>)</code></dt> +<dd>擦除给定块设备 block_dev 的 len 字节。<i></i><i></i></dd> +<dt><code>wipe_cache()</code></dt> +<dd>可实现在安装过程成功结束时擦除缓存分区。</dd> +<dt><code>write_raw_image(<i>filename_or_blob</i>, <i>partition</i>)</code> +</dt> +<dd>将 filename_or_blob 中的映像写入 MTD 分区。<i></i><i></i> +filename_or_blob 可以是一个命名本地文件的字符串或一个包含要写入的数据的 blob 值参数。<i></i>要将文件从 OTA 包复制到分区，请使用：<code>write_raw_image(package_extract_file("zip_filename"), "partition_name"); +</code> +</dd> +</dl> + +<p class="note"><strong>注意</strong>：对于 Android 4.1 之前的版本，仅接受 filename。因此要完成该操作，必须先将数据解压到临时本地文件中。</p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/ota/sign_builds.html b/zh-cn/devices/tech/ota/sign_builds.html new file mode 100644 index 00000000..148a280e --- /dev/null +++ b/zh-cn/devices/tech/ota/sign_builds.html @@ -0,0 +1,229 @@ +<html devsite><head> + <title>对要发布的版本进行签名</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 OS 映像在两个地方使用加密签名：</p> +<ol> +<li>映像中的所有 .apk 文件都必须经过签名。Android 软件包管理器通过下列两种方式使用 .apk 签名：<ul> +<li>更换应用时，必须使用与旧应用相同的密钥对其签名，才能存取旧应用的数据。无论是通过覆盖 .apk 来更新用户应用，还是使用安装在 <code>/data</code> 下的新版本应用来覆盖系统应用，这一点都适用。</li> +<li>如果两个或多个应用想要共享同一个用户 ID（方便共享数据等），则必须使用相同的密钥对它们进行签名。</li></ul></li> +<li>必须使用符合系统预期的密钥对 OTA 更新包进行签名，否则在安装过程中 OTA 更新包将被拒绝。</li> +</ol> + +<h2 id="release-keys">发布密钥</h2> + +<p>Android 树的 <code>build/target/product/security</code> 目录中提供了“测试密钥”<i></i>。使用 <code>make</code> 构建 Android OS 映像便可使用这些测试密钥对所有 .apk 文件进行签名。由于这些测试密钥是公开的，任何人都可以使用相同的密钥对他们自己的 .apk 文件签名，这样他们就能够替换或盗用您的操作系统映像中构建的系统应用。因此，您必须使用只有您自己才能访问的特殊“发布密钥”<i></i>集对公开发布或部署的 Android OS 映像进行签名。</p> + +<p>要生成您自己的唯一发布密钥集，请在 Android 树的根目录下运行以下命令：</p> + +<pre class="no-pretty-print"> +subject='/C=US/ST=California/L=Mountain View/O=Android/OU=Android/CN=Android/emailAddress=android@android.com' +mkdir ~/.android-certs +for x in releasekey platform shared media; do \ + ./development/tools/make_key ~/.android-certs/$x "$subject"; \ +done +</pre> + +<p>您需要对 <code>$subject</code> 进行更改以反映贵组织的信息。您可以使用任何目录，但要注意选择一个已备份且安全的位置。部分供应商会使用强密码加密私钥，并将其存储在源代码控制系统中；其他供应商则将他们的发布密钥完全存储在其他地方，如气隙阻隔的计算机上。</p> + +<p>要生成发布映像，请使用以下命令：</p> + +<pre class="no-pretty-print"> +make dist +./build/tools/releasetools/sign_target_files_apks \ + -o \ # explained in the next section + -d ~/.android-certs out/dist/*-target_files-*.zip \ + signed-target_files.zip +</pre> + +<p><code>sign_target_files_apks</code> 脚本将目标文件 .zip 作为输入文件，并生成一个新的目标文件 .zip，其中所有的 .apk 都已使用新密钥签名。您可以在 <code>signed-target_files.zip</code> 中的 <code>IMAGES/</code> 目录下找到新签名的映像。</p> + +<h2 id="sign-ota-packages">对 OTA 更新包进行签名</h2> + +您可以按照以下步骤将已签名的目标文件 zip 转换为已签名的 OTA 更新 zip： + +<pre class="no-pretty-print"> +./build/tools/releasetools/ota_from_target_files \ + -k ~/.android-certs/releasekey \ + signed-target_files.zip \ + signed-ota_update.zip +</pre> + +<h3 id="signatures-sideloading">签名和旁加载</h3> +<p>旁加载不会绕过 Recovery 流程中的正常软件包签名验证机制。在安装一个软件包之前，Recovery 会验证该软件包是否由与 Recovery 分区中存储的公钥相匹配的私钥进行签名，这与利用无线方式传输的软件包的处理方式一样。 +</p> + +<p>从主系统接收的更新包通常要接受两次验证：一次是由主系统使用 Android API 中的 <code><a href="http://developer.android.com/reference/android/os/RecoverySystem.html#verifyPackage">RecoverySystem.verifyPackage()</a></code> 方法进行验证，第二次则是通过 Recovery 进行验证。RecoverySystem API 对照存储在主系统 <code>/system/etc/security/otacerts.zip +</code> 文件（默认情况下）中的公钥对签名进行检查。Recovery 对照存储在 Recovery 分区 RAM 磁盘中的 <code>/res/keys</code> 文件中的公钥对签名进行检查。</p> + +<p>默认情况下，由此版本生成的目标文件 .zip 会将 OTA 证书设置为与测试密钥相匹配。在发布的映像上，必须使用不同的证书，这样设备才能验证更新包的真实性。如前面一部分所示，将 <code>-o</code> 标志传递到 <code>sign_target_files_apks</code> 即可将测试密钥证书替换成您的证书目录中的发布密钥证书。</p> + +<p>通常情况下，系统映像和 Recovery 映像存储的是相同的 OTA 公钥集。通过将密钥仅<i></i>添加至 Recovery 密钥集，可对只能通过旁加载安装的 apk 包（假设主系统的更新下载机制正确地对照 otacerts.zip 进行验证）签名。您可以通过在产品定义中设置 PRODUCT_EXTRA_RECOVERY_KEYS 变量来指定其他仅可纳入 Recovery 中的密钥：</p> + +<p><code>vendor/yoyodyne/tardis/products/tardis.mk</code></p> +<pre class="no-pretty-print"> + [...] + +PRODUCT_EXTRA_RECOVERY_KEYS := vendor/yoyodyne/security/tardis/sideload +</pre> + +<p>其中包括 Recovery 密钥文件中的公钥 <code>vendor/yoyodyne/security/tardis/sideload.x509.pem</code>，因此它可以安装用此公钥签名的 apk 包。但 otacerts.zip 中不<i></i>包含额外的密钥，因此正确验证下载包的系统不会针对用此密钥签名的 apk 包调用 Recovery。</p> + +<h2 id="certificates-keys">证书和私钥</h2> +<p>每个密钥都包含两个文件：一个是扩展名为 .x509.pem 的证书<i></i>，另一个是扩展名为 .pk8 的私钥<i></i>。私钥需要加以保密，并用于对 apk 包进行签名。密钥本身也可能受密码保护。相比之下，证书只包含公开的一半密钥，因此可以大范围地分发。证书被用于验证某个 apk 包是否由相应的私钥进行签名。</p> +<p>标准 Android 版本使用四个密钥，所有这些密钥都位于 <code> +build/target/product/security</code> 中：</p> + +<dl> +<dt>testkey</dt> +<dd>适用于未另外指定密钥的 apk 包的通用默认密钥。</dd> +<dt>平台</dt> +<dd>适用于核心平台所包含的 apk 包的测试密钥。</dd> +<dt>共享</dt> +<dd>适用于家庭/联系人进程中的共享内容的测试密钥。</dd> +<dt>媒体</dt> +<dd>适用于媒体/下载系统所包含的 apk 包的测试密钥。</dd></dl> + +<p>单个 apk 包通过在其 Android.mk 文件中设置 LOCAL_CERTIFICATE 来指定其中一个密钥。（如果未设置此变量，则使用 testkey。）您还可以通过路径名指定完全不同的密钥，例如：</p> + +<p><code>device/yoyodyne/apps/SpecialApp/Android.mk</code></p> +<pre class="no-pretty-print"> + [...] + +LOCAL_CERTIFICATE := device/yoyodyne/security/special +</pre> + +<p>现在，此版本使用 <code>device/yoyodyne/security/special.{x509.pem,pk8} +</code> 密钥来对 SpecialApp.apk 进行签名。此版本仅可使用不受<i></i>密码保护的私钥。</p> + +<h2 id="advanced-signing-options">高级签名选项</h2> +<p>当您运行 <code>sign_target_files_apks</code> 脚本时，您必须在命令行中指定此版本中每个密钥的替换密钥。 +<code>-k <i>src_key</i>=<i> +dest_key</i></code> 标志每次指定一个密钥替换。<code>-d <i>dir</i></code> 标志可指定一个含有四个密钥的目录来替换所有位于 <code>build/target/product/security</code> 中的密钥；这相当于使用 <code>-k</code> 四次来指定映射：</p> + +<pre class="no-pretty-print"> +build/target/product/security/testkey = dir/releasekey +build/target/product/security/platform = dir/platform +build/target/product/security/shared = dir/shared +build/target/product/security/media = dir/media +</pre> + +<p>对于假定的 tardis 产品，您需要五个受密码保护的密钥：四个用于替换 <code>build/target/product/security</code> 中的四个密钥，其余一个则用于替换在上述示例中提到的 SpecialApp 所需的额外的 <code>keydevice/yoyodyne/security/special</code>。如果密钥位于以下文件中：</p> + +<pre class="no-pretty-print"> +vendor/yoyodyne/security/tardis/releasekey.x509.pem +vendor/yoyodyne/security/tardis/releasekey.pk8 +vendor/yoyodyne/security/tardis/platform.x509.pem +vendor/yoyodyne/security/tardis/platform.pk8 +vendor/yoyodyne/security/tardis/shared.x509.pem +vendor/yoyodyne/security/tardis/shared.pk8 +vendor/yoyodyne/security/tardis/media.x509.pem +vendor/yoyodyne/security/tardis/media.pk8 +vendor/yoyodyne/security/special.x509.pem +vendor/yoyodyne/security/special.pk8 # NOT password protected +vendor/yoyodyne/security/special-release.x509.pem +vendor/yoyodyne/security/special-release.pk8 # password protected +</pre> + +<p>那么您将对所有应用签名，如下所示：</p> + +<pre class="no-pretty-print"> +% <b>./build/tools/releasetools/sign_target_files_apks \ + -d vendor/yoyodyne/security/tardis \ + -k vendor/yoyodyne/special=vendor/yoyodyne/special-release \ + -o \ + tardis-target_files.zip signed-tardis-target_files.zip</b> +Enter password for vendor/yoyodyne/security/special-release key> +Enter password for vendor/yoyodyne/security/tardis/media key> +Enter password for vendor/yoyodyne/security/tardis/platform key> +Enter password for vendor/yoyodyne/security/tardis/releasekey key> +Enter password for vendor/yoyodyne/security/tardis/shared key> + signing: Phone.apk (vendor/yoyodyne/security/tardis/platform) + signing: Camera.apk (vendor/yoyodyne/security/tardis/media) + signing: Special.apk (vendor/yoyodyne/security/special-release) + signing: Email.apk (vendor/yoyodyne/security/tardis/releasekey) + [...] + signing: ContactsProvider.apk (vendor/yoyodyne/security/tardis/shared) + signing: Launcher.apk (vendor/yoyodyne/security/tardis/shared) +rewriting SYSTEM/build.prop: + replace: ro.build.description=tardis-user Eclair ERC91 15449 test-keys + with: ro.build.description=tardis-user Eclair ERC91 15449 release-keys + replace: ro.build.fingerprint=generic/tardis/tardis/tardis:Eclair/ERC91/15449:user/test-keys + with: ro.build.fingerprint=generic/tardis/tardis/tardis:Eclair/ERC91/15449:user/release-keys + signing: framework-res.apk (vendor/yoyodyne/security/tardis/platform) +rewriting RECOVERY/RAMDISK/default.prop: + replace: ro.build.description=tardis-user Eclair ERC91 15449 test-keys + with: ro.build.description=tardis-user Eclair ERC91 15449 release-keys + replace: ro.build.fingerprint=generic/tardis/tardis/tardis:Eclair/ERC91/15449:user/test-keys + with: ro.build.fingerprint=generic/tardis/tardis/tardis:Eclair/ERC91/15449:user/release-keys +using: + vendor/yoyodyne/security/tardis/releasekey.x509.pem +for OTA package verification +done. +</pre> + +<p>在提示用户所有受密码保护的密钥的密码后，脚本会使用发布密钥对输入目标 .zip 中的 .apk 文件重新签名。在运行该命令之前，您还可以将 ANDROID_PW_FILE 环境变量设置为临时文件名；然后脚本会调用您的编辑器，允许您输入所有密钥的密码（采用该方式输入密码可能较为简便）。</p><p> +</p><p><code>sign_target_files_apks</code> 还会在版本属性文件中重写版本描述和指纹，表明这是一个已签名的版本。<code>-t</code> 标志可以控制对指纹所做的编辑。使用 <code>-h</code> 运行脚本来查看所有标志上的文档。</p> + +<h2 id="manually-generating-keys">手动生成密钥</h2> +<p>Android 使用公开指数为 3 的 2048 位 RSA 密钥。您可以使用 <a href="https://www.openssl.org/">openssl.org</a> 提供的 openssl 工具来生成证书/私钥对：</p> + +<pre class="no-pretty-print"> +# generate RSA key +% <b>openssl genrsa -3 -out temp.pem 2048</b> +Generating RSA private key, 2048 bit long modulus +....+++ +.....................+++ +e is 3 (0x3) + +# create a certificate with the public part of the key +% <b>openssl req -new -x509 -key temp.pem -out releasekey.x509.pem \ + -days 10000 \ + -subj '/C=US/ST=California/L=San Narciso/O=Yoyodyne, Inc./OU=Yoyodyne Mobility/CN=Yoyodyne/emailAddress=yoyodyne@example.com'</b> + +# create a PKCS#8-formatted version of the private key +% <b>openssl pkcs8 -in temp.pem -topk8 -outform DER -out releasekey.pk8 -nocrypt</b> + +# securely delete the temp.pem file +% <b>shred --remove temp.pem</b> +</pre> + +<p>上述 openssl pkcs8 命令可创建一个适用于该版本系统的 .pk8 文件，该文件未<i></i>设置密码。要创建一个带有密码保护的 .pk8 文件（您应当为所有实际的发布密钥执行此步骤），请将 <code>-nocrypt</code> 参数替换为 <code>-passout stdin</code>；这样 openssl 将使用从标准输入中读取的密码来加密私钥。该过程中不会输出任何提示。因此，当系统确实只是在等待您输入密码时，如果 stdin 是终端，程序将会处于挂起状态。可以对 Passout 参数使用其他值，以便从其他位置读取密码；有关详情，请参阅 <a href="http://www.openssl.org/docs/man1.0.1/apps/openssl.html#PASS-PHRASE-ARGUMENTS">openssl 文档</a>。</p> +<p>temp.pem 中间文件包含不受任何类型的密码保护的私钥，因此在生成发布密钥时应谨慎处理该文件。需要特别指出的是，GNUshred 实用程序可能对网络或日志文件系统无效。在生成密钥时，您可以使用位于 RAM 磁盘（如 tmpfs 分区）中的工作目录以确保中间文件不会无意间被暴露。</p> + +<h2 id="creating-image-files">创建映像文件</h2> + +<p> +一旦您签署了目标文件 .zip，您便需要创建映像，以便将其存放到设备上。要从目标文件中创建已签名的映像，请在 Android 树形结构的根目录下运行以下命令：</p> + +<pre> +./build/tools/releasetools/img_from_target_files signed-target-files.zip signed-img.zip +</pre> + +生成的文件 <code>signed-img.zip</code> 中包含所有 .img 文件。 +要将映像加载到设备上，请使用 fastboot，如下 +所示： + +<pre> +fastboot update signed-img.zip +</pre> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/power/component.html b/zh-cn/devices/tech/power/component.html new file mode 100644 index 00000000..8ae1344a --- /dev/null +++ b/zh-cn/devices/tech/power/component.html @@ -0,0 +1,154 @@ +<html devsite><head> + <title>测量组件功率</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>您可以通过比较当组件处于期望状态（开启活跃、运行和扫描等）和关闭状态时设备消耗的电流来确定单个组件的功耗。在额定电压下使用外部电源监控器（如台式电源或 Monsoon Solution Inc. 的电源监控器和电源工具软件等专用电池监控工具）测量设备消耗的平均瞬时电流。</p> + +<p>制造商通常都会提供有关单个组件所耗电流的信息。如果这些信息准确地反映了实际操作时设备电池消耗的电流，您便可以利用这些信息。不过，在采用制造商提供的设备电源配置文件中的值之前，请先对它们进行验证。</p> + +<h2 id="control-consumption">控制功耗</h2> + +<p>进行测量时，请确保设备未连接到外部电源，例如运行 Android 调试桥 (adb) 时与开发主机之间通过 USB 连接。因为被测设备可能会使用来自主机的电流，从而导致电池的测量值偏低。避免使用 USB On-The-Go (OTG) 连接，因为 OTG 设备可能消耗被测设备的电流。</p> + +<p>除被测量的组件外，系统应以恒定的功耗水平运行，以避免由于其他组件的功耗变化而影响测量的准确性。以下系统活动可能会给功率测量带来不必要的更改：</p> + +<ul> +<li><strong>通过移动网络、Wi-Fi 和蓝牙进行的接收、传输或扫描活动</strong>。当未测量手机无线装置功率时，请将设备设置为飞行模式，并根据实际情况启用 Wi-Fi 或蓝牙。</li> +<li><strong>屏幕开启/关闭</strong>。屏幕开启时屏幕上显示的色彩可能会影响某些屏幕技术的功耗。测量非屏幕组件的功耗值时请关闭屏幕。</li> +<li><strong>系统挂起/恢复</strong>。当屏幕处于关闭状态时会触发系统进入挂起状态，使部分设备部件处于低功耗运行或关闭状态。这可能会影响被测量组件的功耗，并引起较大的差异，因为系统会定期恢复以发送报警等。有关详细信息，请参阅<a href="#control-suspend">控制系统挂起</a>。</li> +<li><strong>CPU 变速以及进入/退出低功耗调度程序空闲状态</strong>。在正常运行期间，系统会频繁地调整 CPU 速率、在线 CPU 内核数量以及其他系统内核状态，例如内存总线速率以及与 CPU 和内存关联的电源轨电压。在测试期间，这些调整会影响功率测量：<ul> +<li>CPU 速率调节操作可能会减少内存总线和其他系统核心组件的时钟和电压缩放量。</li> +<li>调度活动可能会影响 CPU 保持在低功耗空闲状态的时间所占的百分比。有关防止测试期间发生此类调整的详细信息，请参阅<a href="#control-cpu">控制 CPU 速率</a>。</li> +</ul> + +</li> +</ul> + +<p>例如，Joe Droid 想要计算某个设备的 <code>screen.on</code> 值。他在设备上启用飞行模式，在恒定电流状态下运行设备，保持 CPU 速率恒定，并使用部分唤醒锁来防止系统进入挂起状态。随后，Joe 关闭设备屏幕并测量电流 (200mA)。接着他开启设备屏幕，将亮度调到最低，然后再次进行测量 (300mA)。<code>screen.on</code> 值为 100mA (300 - 200)。</p> + +<p class="note"> +<strong>注意</strong>：如果组件在活跃状态（如移动无线装置或 Wi-Fi）下测得的消耗电流波形不平，请使用功率监控工具测量一段时间内的平均电流。</p> + +<p>当使用外部电源代替设备电池时，系统可能会因为电池热敏电阻或集成的电量计引脚未连接而出现问题（即当电池温度或电池剩余电量读数无效时，内核或 Android 系统可能会关闭）。假冒电池可以提供模仿正常系统温度和充电读数状态的热敏电阻或电量计引脚信号，并且还可以提供外部电源引线以方便连接。或者您也可以修改系统，以便忽略由于缺失电池产生的无效数据。</p> + +<h2 id="control-suspend">控制系统挂起</h2> + +<p>本节介绍了当您不希望系统挂起状态干扰其他测量时应如何避免系统进入挂起状态，以及当您希望测量系统在挂起状态下的功耗时该如何操作。</p> + +<h3 id="prevent-suspend">防止系统挂起</h3> + +<p>系统挂起可能会给功率测量造成不必要的误差，并使系统组件处于低功耗状态，而在这种状态下不适合测量活跃状态的功耗。要防止系统在屏幕关闭时进入挂起状态，请暂时使用部分唤醒锁。使用 USB 电缆将设备连接到开发主机，然后发出以下命令：</p> + +<pre> +$ adb shell "echo temporary > /sys/power/wake_lock" +</pre> + +<p>当使用 <code>wake_lock</code> 时，屏幕进入关闭状态不会触发系统挂起。（请记得在测量功耗之前先断开 USB 电缆与设备的连接。）</p> + +<p>要移除唤醒锁，请使用以下命令：</p> + +<pre> +$ adb shell "echo temporary > /sys/power/wake_unlock" +</pre> + +<h3 id="measure-suspend">测量系统挂起状态下的功耗</h3> + +<p>要测量系统挂起状态下的功耗，您可以测量电源配置文件中 <code>cpu.idle</code> 的值。测量前，请进行以下操作：</p><ul> +<li>移除现有的唤醒锁（如上所述）。</li> +<li>将设备设置成飞行模式，以避免移动网络无线装置的并发活动。移动网络无线装置可能在独立于 SoC 部分（受系统挂起状态控制）的处理器上运行。</li> +<li>通过执行以下操作确保系统处于挂起状态：<ul> +<li>确认电流读数稳定保持在某个值。读数应在预期范围内，即 SoC 挂起状态的功耗加上保持供电的系统组件（如 USB PHY）功耗之和。</li> +<li>检查系统控制台输出。</li> +<li>观察可指示系统状态的外部标示（如系统未挂起时 LED 关闭）。</li> +</ul> +</li> +</ul> + +<h2 id="control-cpu">控制 CPU 速率</h2> + +<p>活跃的 CPU 可以处于联机或脱机状态，改变其时钟速率和相关电压（也可能影响内存总线速率和其他系统内核的电源状态），并在内核空闲循环时进入较低功耗的空闲状态。在测量不同 CPU 的功耗状态来验证电源配置文件中的值时，请避免在测量其他参数时导致功耗发生变化。电源配置文件假设所有 CPU 的可用速率和功率特性都相同。</p> + +<p>在测量 CPU 功率或者在保持恒定 CPU 功率以进行其他测量时，请保持在线 CPU 的数量恒定（例如一个 CPU 在线，其余处于离线状态/以热插拔方式拔出）。留下一个 CPU，并将其余的所有 CPU 处于调度空闲状态，这样可能有助于获得令人信服的结果。使用 <code>adb shell stop</code> 停止 Android 框架可以减少系统调度活动。</p> + +<p>您必须在电源配置文件的 <code>cpu.speeds</code> 条目中指定设备的可用 CPU 速率。要获取可用 CPU 速率列表，请运行以下命令：</p> + +<pre> +adb shell cat /sys/devices/system/cpu/cpu0/cpufreq/stats/time_in_state +</pre> + +<p>这些速率与 <code>cpu.active</code> 值中对应的功率测量值相匹配。</p> + +<p>如果某个平台的在线内核数量对功耗有很大的影响，您可能需要修改该平台的 cpufreq 驱动程序或调节器。大多数平台支持使用用户空间 cpufreq 调节器控制 CPU 速率以及使用 sysfs 接口来设置速率。例如，要在只有 1 个 CPU 的系统上或者所有 CPU 共享一个公共 cpufreq 策略的系统上将速率设为 200MHz，请使用系统控制台或 adb shell 运行以下命令：</p> + +<pre> +echo userspace > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor +echo 200000 > /sys/devices/system/cpu/cpu0/cpufreq/scaling_max_freq +echo 200000 > /sys/devices/system/cpu/cpu0/cpufreq/scaling_min_freq +echo 200000 > /sys/devices/system/cpu/cpu0/cpufreq/scaling_setspeed +cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq +</pre> + +<p class="note"> +<strong>注意</strong>：确切的命令可能因平台实施的 cpufreq 不同而有所差异。 +</p> + +<p>这些命令可确保新的速率不超出允许的范围，并设置新的速率，然后输出 CPU 实际运行的速率（用于验证）。如果执行前的当前最小速率高于 200000，则可能需要交换前两行的顺序，或者再次执行第一行，以在设置最大速率之前降低最小速率。</p> + +<p>要测量 CPU 在不同速率下运行时所消耗的电流，请使用以下命令通过系统控制台将 CPU 置于 CPU 限制循环中：</p> +<pre> +# while true; do true; done +</pre> + +<p>请在执行循环时进行测量。</p> + +<p>如果某些设备因测量温度值过高（即持续高速运行 CPU 一段时间后）需执行温控调频，则可能会限制最大 CPU 速率。您可以通过两种方式观察是否存在此类限制：一是在测量时使用系统控制台输出，二是在测量后检查内核日志。</p> + +<p>对于 <code>cpu.awake</code> 值，您可以测量系统未挂起且不执行任务时的功耗。CPU 应处于低功耗调度程序空闲循环<em></em>中（可能是正在执行 ARM 等待事件指令）或特定的 SoC 低功耗状态（适用于空闲状态下使用的快速退出延迟）。</p> + +<p>对于 <code>cpu.active</code> 值，您可以测量系统未处于挂起模式且不执行任务时的功率。一个 CPU（通常是主 CPU）应运行任务，而所有其他 CPU 都应处于空闲状态。</p> + +<h2 id="screen-power">测量屏幕功率</h2> + +<p>当测量屏幕功率时，请确保在启用屏幕时通常会一并开启的其他设备也处于开启状态。例如，如果触摸屏和显示屏背光通常在屏幕打开时亮起，请确保在测量时这些设备也处于打开状态，以获得屏幕功耗的实际示例。</p> + +<p>一些显示屏技术因所显示颜色的不同而造成功耗上的差异，从而导致功率测量值随测量时屏幕上显示的内容而出现很大差异。测量时，请确保屏幕显示的是具有真实屏幕功率特性的内容。尽量确保屏幕处于全黑屏幕（某些技术在此状态下功耗最低）和全白屏幕两个极限状态之间。通常的做法是使用日历应用中的日程表视图，因为它混合了白色背景和非白色元素。</p> + +<p>测量显示屏/背光亮度最低<em></em>和最高<em></em>时的屏幕功率。设置最低亮度的方法：</p> + +<ul> +<li><strong>使用 Android UI</strong>（不推荐）。依次转到“设置”>“显示屏亮度”，将相应滑块设为最低显示亮度。然而，Android UI 支持的最低亮度为面板/背光亮度的 10-20％，并且不支持将亮度设置到难以看清屏幕的程度。</li> +<li><strong>使用 sysfs 文件</strong>（推荐）。如果有可用的 sysfs 文件，请使用该文件来控制面板亮度，最低可降至硬件支持的最低亮度。</li> +</ul> + +<p>此外，如果平台 sysfs 文件可以开启和关闭 LCD 面板、背光和触摸屏，请使用该文件在屏幕开启和关闭的状态下进行测量。或者您可以设置部分唤醒锁防止系统进入挂起状态，然后使用电源按钮开启和关闭屏幕。</p> + +<h2 id="wifi-power">测量 Wi-Fi 功率</h2> + +<p>在活动较少的网络上执行 Wi-Fi 测量。避免引入与被测活动无关的其他工作（处理大量广播流量）。</p> + +<p><code>wifi.on</code> 值测量 Wi-Fi 在启用但未主动发送或接收数据的状态下的功耗。该值通常是测量系统挂起（休眠）状态下启用/禁用 Wi-Fi 之间产生的电流增量。</p> + +<p><code>wifi.scan</code> 值测量接入点 Wi-Fi 扫描时的功耗。应用可以使用 WifiManager 类 <a href="http://developer.android.com/reference/android/net/wifi/WifiManager.html"><code>startScan()</code> API</a> 来触发 Wi-Fi 扫描。您也可以依次打开“设置”>“Wi-Fi”，这样 Wi-Fi 每隔几秒执行一次接入点扫描，扫描时功耗会明显上升，但必须从这些测量值中减去屏幕功率。</p> + +<p class="note"> +<strong>注意</strong>：请使用受控设置（如 <a href="http://en.wikipedia.org/wiki/Iperf">iperf</a>）来生成网络收发流量。</p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/power/device.html b/zh-cn/devices/tech/power/device.html new file mode 100644 index 00000000..3f96b798 --- /dev/null +++ b/zh-cn/devices/tech/power/device.html @@ -0,0 +1,210 @@ +<html devsite><head> + <title>测量设备电量</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>对于配有 Summit SMB347 或 Maxim MAX17050（许多 Nexus 设备均有提供）等电池电量计的 Android 设备，您可以确定设备耗电量。如果没有外部测量设备，或将外部测量设备连接到设备较麻烦（如在移动使用中），可使用系统内置电量计。</p> + +<p>测量结果可包括瞬时电流、剩余电量、测试开始和结束时的电量，以及其他测量结果（取决于设备支持的属性，见下文）。为获得最佳效果，请在长时间运行的 A/B 测试中进行设备电量测量，且该测试应使用具有相同电量计和相同电流感应电阻的同类型设备。确保每台设备的起始电量相同，以避免电量计在电池放电曲线的不同点出现不同的行为。</p> + +<p>即使处在相同的测试环境下，也不能保证测量结果具有绝对的高精确度。然而，在各次测试运行中，特定于电量计和感应电阻的大部分误差都会保持一致，这样使得相同设备之间的比较变得有意义。我们建议采用不同的配置进行多次测试，以确定各配置间的显著差异和相对耗电量。</p> + +<h2 id="power-consumption">读取耗电量</h2> + +<p>要读取耗电量数据，请在测试代码中插入对 API 的调用。</p> + +<pre> +import android.os.BatteryManager; +import android.content.Context; +BatteryManager mBatteryManager = +(BatteryManager)Context.getSystemService(Context.BATTERY_SERVICE); +Long energy = +mBatteryManager.getLongProperty(BatteryManager.BATTERY_PROPERTY_ENERGY_COUNTER); +Slog.i(TAG, "Remaining energy = " + energy + "nWh"); +</pre> + +<h2 id="avail-props">可用属性</h2> + +<p>Android 支持以下电池电量计属性：</p> + +<pre> +BATTERY_PROPERTY_CHARGE_COUNTER Remaining battery capacity in microampere-hours +BATTERY_PROPERTY_CURRENT_NOW Instantaneous battery current in microamperes +BATTERY_PROPERTY_CURRENT_AVERAGE Average battery current in microamperes +BATTERY_PROPERTY_CAPACITY Remaining battery capacity as an integer percentage +BATTERY_PROPERTY_ENERGY_COUNTER Remaining energy in nanowatt-hours +</pre> + +<p>大多数属性都是从内核中类似于 power_supply 名称的子系统属性中读取。但是，特定设备的确切属性、属性值解析和更新频率取决于：</p> + +<ul> +<li>电量计硬件，如 Summit SMB347 或 Maxim MAX17050。</li> +<li>电量计与系统的连接，如外部电流感应电阻的值。</li> +<li>电量计芯片的软件配置，如为内核驱动程序中的平均电流计算间隔所选的值。</li> +</ul> + +<p>有关详情，请参阅 <a href="#nexus-devices">Nexus 设备</a>的可用属性。</p> + +<h2 id="maxim-fuel">Maxim 电量计</h2> + +<p>在确定电池在长时间内的荷电状态时，Maxim 电量计（MAX17050，BC15）可校正库仑计数器的偏移测量结果。对于在短时间内进行的测量（如耗电量计量测试），该电量计不会进行校正，使得当电流测量值过小时偏移成为主要误差源（尽管任何时长都无法完全消除偏移误差）。</p> + +<p>对于典型的 10 毫欧感应电阻设计，电流偏移量应小于 1.5 毫安，这意味着任何测量结果误差均为 +/- 1.5 毫安（电路板布局也会对该误差产生影响）。例如，当测量强电流（200 毫安）时，您将会获得以下结果：</p> + +<ul> +<li>2 毫安（200 毫安的 1% 增益误差，由电量计增益误差导致）</li> +<li>+2 毫安（200 毫安的 1% 增益误差，由感应电阻误差导致）</li> +<li>+1.5 毫安（电流感应偏移误差，由电量计导致）</li> +</ul> + +<p>总误差为 5.5 毫安 (2.75%)。将该误差与中等电流（50 毫安）进行比较（相同误差百分比得出的总误差为 7％），或与小电流（15 毫安）进行比较（+/-1.5 毫安误差得出的总误差为 10％）。</p> + +<p>为获得最佳效果，我们建议测量大于 20 毫安的电流。增益测量误差是可重复的系统误差，使您能够在多种模式下测试设备，并获得纯粹的相对测量结果（1.5 毫安偏移量除外）。</p> + +<p>对于 +/-100 微安的相对测量结果，所需测量时间取决于：</p> + +<ul> +<li><b>ADC 采样噪声</b>。具有正常出厂配置的 MAX17050 由于噪声而产生 +/-1.5 毫安的样本变差，每 175.8 毫秒输出一个样本。对于 1 分钟的测试间隙，您将会获得大约 +/-100 微安的噪声，对于 6 分钟的测试间隙，您将会获得小于 100 微安、3-sigma 的纯粹噪声（或 33 微安、1-sigma 的噪声）。</li> +<li><b>由负载变化引起的样本混叠</b>。差异会放大误差，因此对于具有负载固有差异的样本，请考虑采用较长的测试间隙。</li> +</ul> + +<h2 id="nexus-devices">支持的 Nexus 设备</h2> + +<h5 id="nexus-5">Nexus 5</h5> + +<table> +<tbody> +<tr> +<th>型号</th> +<td>Nexus 5</td> +</tr> +<tr> +<th>电量计</th> +<td>Maxim MAX17048 电量计（ModelGauge™，无库仑计数器）</td> +</tr> +<tr> +<th>属性</th> +<td>BATTERY_PROPERTY_CAPACITY</td> +</tr> +<tr> +<th>测量结果</th> +<td>电量计不支持除电池荷电状态达到 ％/256（占满格电池电量的百分之一的 256 分之一）解析度之外的任何测量结果。</td> +</tr> +</tbody> +</table> + +<h5 id="nexus-6">Nexus 6</h5> + +<table> +<tbody> +<tr> +<th>型号</th> +<td>Nexus 6</td> +</tr> +<tr> +<th>电量计</th> +<td>Maxim MAX17050 电量计（带有 Maxim ModelGauge™ 调节功能的库仑计数器）和 10 毫欧电流感应电阻。</td> +</tr> +<tr> +<th>属性</th> +<td>BATTERY_PROPERTY_CAPACITY<br /> +BATTERY_PROPERTY_CURRENT_NOW<br /> +BATTERY_PROPERTY_CURRENT_AVERAGE<br /> +BATTERY_PROPERTY_CHARGE_COUNTER<br /> +BATTERY_PROPERTY_ENERGY_COUNTER</td> +</tr> +<tr> +<th>测量结果</th> +<td>CURRENT_NOW 解析度为 156.25 微安，更新周期为 175.8 毫秒。<br /> +CURRENT_AVERAGE 解析度为 156.25 微安，更新周期可在 0.7 秒到 6.4 小时范围内配置，默认为 11.25 秒。<br /> +CHARGE_COUNTER（累计电流，不可扩展精度）解析度为 500 微安时（未经电量计针对库仑计数器偏移量进行调整的原始库仑计数器读数，加上来自 ModelGauge m3 算法的输入值，其中包括空值补偿）。<br /> +CHARGE_COUNTER_EXT（内核扩展精度）解析度为 8 纳安时。<br /> +当额定电压为 3.7 伏时，ENERGY_COUNTER 为 CHARGE_COUNTER_EXT。</td> +</tr> +</tbody> +</table> + +<h5 id="nexus-9">Nexus 9</h5> + +<table> +<tbody> +<tr> +<th>型号</th> +<td>Nexus 9</td> +</tr> +<tr> +<th>电量计</th> +<td>Maxim MAX17050 电量计（带有 Maxim ModelGauge™ 调节功能的库仑计数器）和 10 毫欧电流感应电阻。</td> +</tr> +<tr> +<th>属性</th> +<td>BATTERY_PROPERTY_CAPACITY<br /> +BATTERY_PROPERTY_CURRENT_NOW<br /> +BATTERY_PROPERTY_CURRENT_AVERAGE<br /> +BATTERY_PROPERTY_CHARGE_COUNTER<br /> +BATTERY_PROPERTY_ENERGY_COUNTER</td> +</tr> +<tr> +<th>测量结果</th> +<td>CURRENT_NOW 解析度为 156.25 微安，更新周期为 175.8 毫秒。<br /> +CURRENT_AVERAGE 解析度为 156.25 微安，更新周期可在 0.7 秒到 6.4 小时范围内配置，默认为 11.25 秒。<br /> +CHARGE_COUNTER（累计电流，不可扩展精度）解析度为 500 微安时。<br /> +CHARGE_COUNTER_EXT（内核扩展精度）解析度为 8 纳安时。<br /> +当额定电压为 3.7 伏时，ENERGY_COUNTER 为 CHARGE_COUNTER_EXT。<br /> +累计电流更新周期为 175.8 毫秒。<br /> +当经过 175 毫秒的量化时进行 ADC 采样，采样周期为 4 毫秒。可以调整占空比。</td> +</tr> +</tbody> +</table> + +<h5 id="nexus-10">Nexus 10</h5> + +<table> +<tbody> +<tr> +<th>型号</th> +<td>Nexus 10</td> +</tr> +<tr> +<th>电量计</th> +<td>Dallas Semiconductor DS2784 电量计（库仑计数器），带 10 毫欧电流感应电阻。</td> +</tr> +<tr> +<th>属性</th> +<td>BATTERY_PROPERTY_CAPACITY<br /> +BATTERY_PROPERTY_CURRENT_NOW<br /> +BATTERY_PROPERTY_CURRENT_AVERAGE<br /> +BATTERY_PROPERTY_CHARGE_COUNTER<br /> +BATTERY_PROPERTY_ENERGY_COUNTER</td> +</tr> +<tr> +<th>测量结果</th> +<td>电流测量（瞬时电流和平均电流）解析度为 156.3 微安。<br /> +CURRENT_NOW 瞬时电流更新周期为 3.5 秒。<br /> +CURRENT_AVERAGE 更新周期为 28 秒（不可配置）。<br /> +CHARGE_COUNTER（累计电流，不可扩展精度）解析度为 625 微安时。<br /> +CHARGE_COUNTER_EXT（内核扩展精度）解析度为 144 纳安时。<br /> +当额定电压为 3.7 伏时，ENERGY_COUNTER 为 CHARGE_COUNTER_EXT。<br /> +全部更新周期为 3.5 秒。</td> +</tr> +</tbody> +</table> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/power/index.html b/zh-cn/devices/tech/power/index.html new file mode 100644 index 00000000..1fea242c --- /dev/null +++ b/zh-cn/devices/tech/power/index.html @@ -0,0 +1,52 @@ +<html devsite><head> + <title>Android 电源配置文件</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>电池使用信息来自电池使用统计信息和电源配置文件中的值。</p> + +<h2 id="usage-statistics">电池使用统计信息</h2> + +<p>框架可通过跟踪设备组件在不同状态下维持的时间来自动确定电池使用统计信息。当组件（WLAN 芯片组、手机无线装置、蓝牙、GPS、显示屏和 CPU）状态发生改变（开/关、空闲/全功耗、低/高亮度等）时，控制服务会向框架中的 BatteryStats 服务报告状态改变信息。BatteryStats 会不断地收集信息，并存储这些信息以便在重新启动后继续使用。该服务不会直接跟踪电池中消耗的电流，而是通过收集计时信息来估算不同组件所消耗的电量。</p> + +<p>该框架使用以下方法收集统计信息：</p> + +<ul> +<li><strong>推送</strong>。服务察觉到组件状态发生变化后，会将状态变化推送到 BatteryStats 服务中。</li> +<li><strong>拉取</strong>。对于应用使用的 CPU 等组件，框架会在转换点（例如启动活动或停止活动）自动拉取数据以截取快照。</li> +</ul> + +<p>资源消耗与使用资源的应用相关。当多个应用同时使用某项资源（例如防止系统挂起的唤醒锁）时，框架会将资源消耗量分摊到这些应用上，但不一定会均分。</p> + +<p>为了避免由于系统关闭事件而丢失电池使用统计信息（这些统计信息可能表明存在电池功耗问题，比如由于电池电量耗尽而关闭），框架会大约每 30 分钟发送一次统计信息。</p> + +<p>电池使用统计信息完全由框架处理，不需要原始设备制造商 (OEM) 修改。</p> + +<h2 id="profile-values">电源配置文件中的值</h2> + +<p class="caution"><strong>注意</strong>：设备制造商必须提供组件的电源配置文件，该配置文件定义了组件的电流消耗值以及该组件在一段时间内大概消耗的电量。有关此配置文件的定义，请查看 <a href="https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/xml/power_profile.xml">platform/frameworks/base/core/res/res/xml/power_profile.xml</a>。要获得与这些设置相关的指导，请参阅<a href="/devices/tech/power/values.html">电源值</a>。</p> + +<p>在电源配置文件中，功耗表示额定电压下的电流消耗量，单位为毫安 (mA)，也可用微安 (uA) 表示（分数值）。该值应代表电池上消耗的电流，而非与电池消耗的电流不对应的相应电源轨的值。</p> + +<p>例如，显示屏电源配置文件列出了当显示屏开启状态下保持最低亮度和最高亮度时需消耗的电流量 (mA)。为了确定显示屏常亮时所需的电源成本（即由显示屏组件所消耗的电池量），框架会跟踪在各个亮度级别下维持的时间，然后将这些时间间隔乘以通过插值算法计算的显示亮度成本。</p> + +<p>该框架还会将每个应用的 CPU 时间乘以在特定速度运行 CPU 所需的毫安量。通过该计算方法可以创建一个应用电池消耗量（通过执行 CPU 代码）的相对排名（应用在前台的时间和包括后台活动在内的总时间将分别进行报告）。</p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/power/performance.html b/zh-cn/devices/tech/power/performance.html new file mode 100644 index 00000000..0f7e1f3b --- /dev/null +++ b/zh-cn/devices/tech/power/performance.html @@ -0,0 +1,71 @@ +<html devsite><head> + <title>性能管理</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 设备的电量和性能进行管理有助于确保应用能够在各类硬件上稳定、顺畅地运行。在 Android 7.0 及更高版本中，OEM 可支持提供持续性能提示以便应用能够维持稳定的设备性能，并可指定专属核心以便提高 CPU 密集型前台应用的性能。</p> + +<h2 id="sustained_performance">持续性能</h2> +<p>对于长时间运行的应用（例如，游戏、相机、RenderScript 和音频处理应用）来说，当设备达到极限温度且系统芯片 (SoC) 引擎受到限制时，性能便可能会出现急剧变化。当设备开始升温时，底层平台的功能会变得飘忽不定，这会限制应用开发者打造可长时间运行的高性能应用。</p> + +<p>为解决此类限制，Android 7.0 引入了对持续性能的支持，让 OEM 能够为长时间运行的应用提供设备性能提示。应用开发者可根据这些提示来调整应用，以使设备能在长时间内保持可预测且稳定的性能水平。</p> + +<h3 id="architecture">架构</h3> +<p>Android 应用可以请求平台进入持续性能模式，以使 Android 设备能在长时间内保持稳定的性能水平。</p> + +<p><img src="../images/power_sustained_perf.png"/></p> +<p class="img-caption"><strong>图 1.</strong> 持续性能模式架构</p> + +<h3 id="implementation">实现</h3> +<p>为支持 Android 7.0 及更高版本实现持续性能，OEM 必须：</p> +<ul> +<li>针对具体设备更改 HAL 的电量文件，以锁定最大 CPU/GPU 频率<strong>或</strong>执行其他优化来防止出现过热保护。</li> +<li>在 HAL 的电量文件中实现新提示 <code>POWER_HINT_SUSTAINED_PERFORMANCE</code>。</li> +<li>通过使用 <code>isSustainedPerformanceModeSupported()</code> API 返回 TRUE 来声明支持。</li> +<li>实现 <code>Window.setSustainedPerformanceMode</code>。</li> +</ul> + +<p>在 Nexus 参考实现中，电量提示将 CPU 和 GPU 的最大频率设定为最高可持续水平的频率。请注意，降低 CPU/GPU 频率的上限会降低帧速率，但由于此种较低的速率具有可持续性，因此在该模式下它依然是首选。例如，某部使用正常最大时钟频率的设备或许能以 60 FPS 的速度渲染几分钟，但当该设备持续升温，则可能会在渲染 30 分钟后调节到 30 FPS。而当使用持续模式时，该设备就可能会以 45 FPS 的速度持续渲染整整 30 分钟。这样做的目的是：通过使用该模式，获得一个与不使用该模式时相同（或更高）的帧速率，而且该速率能在长时间内维持稳定水平，使开发者不必费心追逐一个飘忽不定的目标。</p> +<p>我们强烈建议您采用持续模式，以使设备能够达到最高可持续性能，而非仅仅达到为通过测试而需采用的最小值（例如，选择不会导致设备长时间运行后进入过热保护的最高频率上限）。</p> + +<p class="note"><strong>注意</strong>：实现持续模式不需要设定时钟频率的最大速率上限。</p> + +<h3 id="validation">验证</h3> +<p>OEM 可以使用 CTS 测试（适用于 Android 7.0 及更高版本）来验证持续性能 API 的实现情况。这项测试会运行工作负载大约 30 分钟，并会分别在启用和不启用持续模式的情况下对性能进行基准测试：</p> +<ul> +<li>启用持续模式后，帧速率必须保持相对恒定（这项测试会测量帧速率在一段时间内的变化幅度百分比，且会要求该比例 <5%）。</li> +<li>启用持续模式后，帧速率不得低于在不启用持续模式的情况下 30 分钟结束时的帧速率。</li> +</ul> +<p>此外，您可以对 CPU 和 GPU 进行多个高负荷工作来手动测试你的设备的实现情况，以确保设备在被使用 30 分钟后不会进入过热保护。在内部测试中，我们会使用游戏和基准测试应用（例如 <a href="https://gfxbench.com/result.jsp">gfxbench</a>）等示例工作负载。</p> + +<h2 id="exclusive_core">专属核心</h2> +<p>对于 CPU 密集型、时间敏感型工作负载，被另一个线程抢占可能会影响到能否按各个帧的预定截止时间完成渲染。 +Cc：烦请帮忙确认making frame deadlines or not的译文对于具有严格的延迟时间要求和帧速率要求的应用（如音频应用或虚拟实境应用），具有专属 CPU 核心能够保证实现可接受的性能水平。</p> +<p>运行 Android 7.0 或更高版本的设备现可为最主要前台应用明确保留一个核心，这不仅能提高所有前台应用的性能，还能让运行高强度工作负载的应用更好地控制其任务在各 CPU 核心上的分配方式。</p> +<p>要想支持在设备上使用专属核心，请执行以下操作：</p> +<ul> +<li>启用 <code>cpusets</code> 并配置仅包含最主要前台应用的 <code>cpuset</code>。</li> +<li>确保为来自 <code>cpuset</code> 的线程保留一个核心（即专属核心）。</li> +<li>实现 getExclusiveCores API 以返回这个专属核心的核心编号。</li> +</ul> +<p>要想确定哪些进程被安排在哪些核心上，请在运行任意工作负载时使用 <code>systrace</code>，并验证是否只有来自最主要前台应用的用户空间线程被安排在专属核心上。</p> +<p>要查看 Nexus 6P 的参考实现，请参阅 <code>android//device/huawei/angler/power/power.c</code>。</p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/power/values.html b/zh-cn/devices/tech/power/values.html new file mode 100644 index 00000000..9e1385c7 --- /dev/null +++ b/zh-cn/devices/tech/power/values.html @@ -0,0 +1,304 @@ +<html devsite><head> + <title>测量电量值</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>设备制造商必须在 <code>/frameworks/base/core/res/res/xml/power_profile.xml</code> 中提供组件的电源配置文件。</p> + +<p>要确定电源配置文件的有关数值，请使用测量设备耗电量的硬件，并执行需要信息的各种操作。测量执行这些操作时的电量使用情况并计算各项值（在适当情况下与其他基准操作的电量消耗做对比所得的差异值）。 +</p> + +<p>电源配置文件的目的在于适当地估算电量消耗情况，电源配置文件的有关数值以电流（安培）表示。Android 框架用电流乘以子系统处于激活状态的时间，并计算毫安时值，然后将此值用于评估应用/子系统消耗的电池电量。</p> + +<p>运行 Android 7.0 及更高版本且配备蓝牙、调制解调器和 WLAN 控制器的设备可以提供从芯片组数据获得的其他电量值。</p> + +<h2 id="multiple-cpus">采用异构 CPU 的设备</h2> + +<p>设备电源配置文件（针对具备异构架构 CPU 核心的设备）必须包含以下额外字段： +</p><ul> +<li>每个集群的 CPU 总数（以 cpu.clusters.cores 表示）。</li> +<li>每个集群支持的 CPU 速率。</li> +<li>每个集群中处于激活状态的 CPU 耗电情况。</li> +</ul> + +<p>为了区分集群中激活的 CPU 耗电量和所支持的 CPU 速率耗电量，需要将集群编号附加到数组名称上。集群编号按照 CPU 核心在内核设备树中的顺序分配。例如，在具备两 (2) 个集群，拥有四 (4) 个核心的异构架构中：</p> +<ul> +<li>cluster0 由 cpu0-3 组成</li> +<li>cluster1 由 cpu4-7 组成</li> +</ul> +<p>当 Android 框架从位于 <code>/sys/devices/system/cpu/cpu<number>/cpufreq/stats</code> 中的 <code>sysfs</code> 文件中读取统计信息时，将使用以上 CPU 核心编号。 + +</p><p>集群中激活的 CPU 以及速率示例：</p> + +<pre> +<array name="cpu.active.cluster0"> +<value>200</value> +<value>300</value> +<value>400</value> +</array> +<array name="cpu.speeds.cluster0"> +<value>600000</value> +<value>800000</value> +<value>1200000</value> +</array> + +<array name="cpu.active.cluster1"> +<value>400</value> +<value>500</value> +<value>600</value> +</array> +<array name="cpu.speeds.cluster1"> +<value>800000</value> +<value>1200000</value> +<value>1400000</value> +</array> +</pre> + +<h2 id="values">电量值</h2> +<p>下表列出可供使用的电量值设置。要查看 AOSP 中的示例文件，请参阅 <a href="https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/xml/power_profile.xml">power_profile.xml</a>。</p> + +<table> +<tbody><tr> + <th>名称</th> + <th>说明</th> + <th>示例值</th> + <th>备注</th> +</tr> +<tr> + <td>none</td> + <td>无</td> + <td>0</td> + <td></td> +</tr> + +<tr> + <td>screen.on</td> + <td>屏幕以最低亮度打开时消耗的额外电量。</td> + <td>200 毫安</td> + <td>包括触摸控制器和显示屏背光。Android 的最低亮度并非是 0，而是倾向于设为 10% 或 20%。</td> +</tr> + +<tr> + <td>screen.full</td> + <td>与处于最低亮度的屏幕相比，当屏幕处于最高亮度时消耗的额外电量。</td> + <td>100-300 毫安</td> + <td>将此值的分数（基于屏幕亮度）添加到 screen.on 值，用来计算屏幕耗电量。</td> +</tr> + +<tr> + <td>wifi.on</td> + <td>当 WLAN 打开，但未接收、发送信号或执行扫描时消耗的额外电量。</td> + <td>2 毫安</td> + <td></td> +</tr> + +<tr> + <td>wifi.active</td> + <td>通过 WLAN 发送或接收信号时消耗的额外电量。</td> + <td>31 毫安</td> + <td></td> +</tr> + +<tr> + <td>wifi.scan</td> + <td>WLAN 正在扫描无线接入点时消耗的额外电量。</td> + <td>100 毫安</td> + <td></td> +</tr> + +<tr> + <td>dsp.audio</td> + <td>当通过 DSP 进行音频解码/编码时消耗的额外电量。</td> + <td>14.1 毫安</td> + <td>预留以供日后使用。</td> +</tr> + +<tr> + <td>dsp.video</td> + <td>当通过 DSP 进行视频解码时消耗的额外电量。</td> + <td>54 毫安</td> + <td>预留以供日后使用。</td> +</tr> + +<tr> + <td>camera.avg</td> + <td>用于典型相机应用的相机子系统的平均电量消耗。</td> + <td>600 毫安</td> + <td>预期将此值作为当应用运行预览且每分钟捕获大约 10 张全分辨率照片时的粗略估算值。</td> +</tr> + +<tr> + <td>camera.flashlight</td> + <td>当摄像头闪光模块开启时消耗的平均电量。</td> + <td>200 毫安</td> + <td></td> +</tr> + +<tr> + <td>gps.on</td> + <td>GPS 获取信号时消耗的额外电量。</td> + <td>50 毫安</td> + <td></td> +</tr> + +<tr> + <td>radio.active</td> + <td>蜂窝无线电发送/接收信号时消耗的额外电量。</td> + <td>100-300 毫安</td> + <td></td> +</tr> + +<tr> + <td>radio.scanning</td> + <td>当移动网络无线装置寻呼发射塔时消耗的额外电量。</td> + <td>1.2 毫安</td> + <td></td> +</tr> + +<tr> + <td>radio.on</td> + <td>当蜂窝无线电开启时消耗的额外电量。多值条目，每个信号强度（无信号、弱、良好、强）各有一个值。</td> + <td>1.2 mA</td> + <td>某些无线装置在搜索手机信号塔但未能检测到信号时会增加耗电量。随着信号强度的增加，这些值可能保持不变或变小。如果您只提供一个值，则所有强度都使用同一个值。如果您提供两个值，则第一个值在无信号时使用，第二个值用于所有其他信号强度，以此类推。</td> +</tr> + +<tr> + <td>bluetooth.controller.idle</td> + <td>蓝牙控制器在空闲时的平均电流消耗量（毫安）。</td> + <td> - </td> + <td rowspan="4">这些值并不是通过预估获得的，而是从控制器的数据表中提取出来的。如果有多种接收或发送状态，则采用这些状态的平均值。此外，系统将即时收集数据以用于<a href="#le-bt-scans">低功耗 (LE) 和蓝牙扫描</a>。<br /><br />Android N 及更高版本不再将蓝牙电量值用于 bluetooth.active（通过蓝牙 A2DP 播放音频时使用）和 bluetooth.on（在蓝牙打开但处于空闲状态时使用）。</td> +</tr> + +<tr> + <td>bluetooth.controller.rx</td> + <td>蓝牙控制器在接收信号时的平均电流消耗量（毫安）。</td> + <td> - </td> +</tr> + +<tr> + <td>bluetooth.controller.tx</td> + <td>蓝牙控制器在发送信号时的平均电流消耗量（毫安）。</td> + <td> - </td> +</tr> + +<tr> + <td>bluetooth.controller.voltage</td> + <td>蓝牙控制器的平均工作电压（毫伏）。</td> + <td> - </td> +</tr> + +<tr> + <td>modem.controller.idle</td> + <td>调制解调控制器在空闲时的平均电流消耗量（毫安）。</td> + <td> - </td> + <td rowspan="4">这些值并不是通过预估获得的，而是从控制器的数据表中提取出来的。如果有多种接收或发送状态，则采用这些状态的平均值。</td> +</tr> + +<tr> + <td>modem.controller.rx</td> + <td>调制解调控制器在接收信号时的平均电流消耗量（毫安）。</td> + <td> - </td> +</tr> + +<tr> + <td>modem.controller.tx</td> + <td>调制解调控制器在发送信号时的平均电流消耗量（毫安）。</td> + <td> - </td> +</tr> + +<tr> + <td>modem.controller.voltage</td> + <td>调制解调控制器的平均工作电压（毫伏）。</td> + <td> - </td> +</tr> + +<tr> + <td>wifi.controller.idle</td> + <td>WLAN 控制器在空闲时的平均电流消耗量（毫安）。</td> + <td> - </td> + <td rowspan="4">这些值并不是通过预估获得的，而是从控制器的数据表中提取出来的。如果有多种接收或发送状态，则采用这些状态的平均值。</td> +</tr> + +<tr> + <td>wifi.controller.rx</td> + <td>WLAN 控制器在接收信号时的平均电流消耗量（毫安）。</td> + <td> - </td> +</tr> + +<tr> + <td>wifi.controller.tx</td> + <td>WLAN 控制器在发送信号时的平均电流消耗量（毫安）。</td> + <td> - </td> +</tr> + +<tr> + <td>wifi.controller.voltage</td> + <td>WLAN 控制器的平均工作电压（毫伏）。</td> + <td> - </td> +</tr> + +<tr> + <td>cpu.speeds</td> + <td>多值条目，以千赫 (KHz) 为单位列出每个 CPU 可能支持的速率。</td> + <td>125000 千赫、250000 千赫、500000 千赫、1000000 千赫、1500000 千赫</td> + <td>条目的数量和顺序必须与 cpu.active 中的毫安条目相一致。</td> +</tr> + +<tr> + <td>cpu.idle</td> + <td>当 CPU（和 SoC）处于系统挂起状态时，系统消耗的总电量。</td> + <td>3 毫安</td> + <td></td> +</tr> + +<tr> + <td>cpu.awake</td> + <td>当 CPU 处于调度空闲状态（内核空闲循环）时消耗的额外电量；系统没有处于系统挂起状态。</td> + <td>50 毫安</td> + <td>您的平台可能在不同的耗电水平上存在多种空闲状态；针对时间较长的调度空闲（几毫秒）可以选择一种有代表性的空闲状态。检查您的测量设备上的电量图，并选择 CPU 耗电量最低时的样本，丢弃当 CPU 退出空闲状态时的较高耗电量样本。</td> +</tr> + +<tr> + <td>cpu.active</td> + <td>CPU 以不同速度运行时消耗的额外电量。</td> + <td>100 毫安、120 毫安、140 毫安、160 毫安、200 毫安</td> + <td>此值代表 CPU 供电通道以不同速率运行时消耗的电量。在内核中设定每个耗电量所允许的最大速率并限制 CPU 以该速率运行。条目的数量和顺序应与 cpu.speeds 中的条目的数量和顺序相一致。</td> +</tr> + +<tr> + <td>cpu.clusters.cores</td> + <td>每个 CPU 集群所包含的核心数。</td> + <td>4、2</td> + <td>仅适用于具有<a href="#multiple-cpus">异构 CPU 架构</a>的设备。条目的数量和顺序应与适用于 cpu.active 和 cpu.speeds 的集群的条目的数量相一致。第一个条目表示 cluster0 中的 CPU 核心数，第二个条目表示 cluster1 中的 CPU 核心数，依此类推。</td> +</tr> + +<tr> + <td>电池容量</td> + <td>总电池容量 （以毫安时为单位）。</td> + <td>3000 毫安时</td> + <td></td> +</tr> + +</tbody></table> + +<h2 id="le-bt-scans">低功耗 (LE) 和蓝牙扫描</h2> +<p>对于运行 Android 7.0 的设备，系统为低功耗 (LE) 扫描和蓝牙网络流量（例如：RFCOMM 和 L2CAP）收集数据并将这些活动与初始化应用相关联。蓝牙扫描与初始化扫描的应用有关，但批量扫描与后者无关（而是与蓝牙应用有关）。对于扫描 N 毫秒的应用，扫描耗时为 N 毫秒接收时间和 N 毫秒发射时间；所有剩余的控制器时间被分配至网络流量或蓝牙应用。</p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/test_infra/tradefed/full_example.html b/zh-cn/devices/tech/test_infra/tradefed/full_example.html new file mode 100644 index 00000000..91696568 --- /dev/null +++ b/zh-cn/devices/tech/test_infra/tradefed/full_example.html @@ -0,0 +1,342 @@ +<html devsite><head> + <title>端到端测试示例</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>本教程将指导您创建“hello world”Trade Federation (TF) 测试配置，并通过实际操作向您介绍 TF 框架的相关内容。您将从开发环境着手，创建一个简单的配置并添加功能。</p> + +<p>本教程以一组练习的形式讲述测试开发过程，其中每个练习都包含几个步骤，为您演示如何构建配置并使其逐渐完善。我们为您提供了完成测试配置所需的所有示例代码，并在每个练习的标题中添加字母标注，表示该步骤涉及的人员：</p> +<ul> +<li><strong>D</strong> 代表开发者</li> +<li><strong>I</strong> 代表集成者</li> +<li><strong>R</strong> 代表测试运行者</li> +</ul> + +<p>学完本教程之后，您不仅会获得一个可正常运行的 TF 配置，还可以了解 TF 框架中的许多重要概念。</p> + +<h2 id="setup">搭建 Trade Federation 开发环境</h2> +<p>要详细了解如何搭建 TF 开发环境，请参阅<a href="/devices/tech/test_infra/tradefed/fundamentals/machine_setup.html">机器设置</a>。本教程的其余部分假设您已打开一个已初始化为 TF 环境的 shell。</p> + +<p>为简单起见，本教程将举例说明如何向 TF 框架核心库添加配置及其类。这可以通过编译 tradefed JAR 文件，然后根据该 JAR 文件编译模块来扩展到源代码树之外的开发模块。</p> + +<h2 id="testclass">创建测试类 (D)</h2> +<p>我们来创建一个仅将消息转储到 stdout 的 hello world 测试。Tradefed 测试通常会实现 <a href="/reference/com/android/tradefed/testtype/IRemoteTest.html">IRemoteTest</a> 接口。以下为 HelloWorldTest 的实现过程：</p> +<pre><code>package com.android.tradefed.example; + +import com.android.tradefed.device.DeviceNotAvailableException; +import com.android.tradefed.result.ITestInvocationListener; +import com.android.tradefed.testtype.IRemoteTest; + +public class HelloWorldTest implements IRemoteTest { + @Override + public void run(ITestInvocationListener listener) throws DeviceNotAvailableException { + System.out.println("Hello, TF World!"); + } +} +</code></pre> + +<p>请将此示例代码保存到 <code><tree>/tools/tradefederation/core/prod-tests/src/com/android/tradefed/example/HelloWorldTest.java</code> 并从您的 shell 中重建 tradefed：</p> +<pre><code>m -jN</code></pre> + +<p>请注意，在实际操作中，上述示例中的 <code>System.out</code> 可能并不直接将输出导向至控制台。虽然这对于此测试示例而言是可接受的，但您应按照<a href="#logging">日志记录（D、I、R）</a>这一部分所述，在 Trade Federation 中建立日志记录。</p> + +<p>如果测试创建失败，请参阅<a href="/devices/tech/test_infra/tradefed/fundamentals/machine_setup.html">机器设置</a>，并确保您没有漏掉任何步骤。</p> + +<h2 id="createconfig">创建配置 (I)</h2> +<p>Trade Federation 测试可通过创建<strong>配置</strong>来执行。此配置为 XML 文件，告诉 tradefed 在哪个（或哪些）测试上运行以及要执行哪些其他模块并按何种顺序执行。</p> + +<p>我们来为 HelloWorldTest 创建一个新的配置（请注意 HelloWorldTest 的完整类名）：</p> +<pre><code><configuration description="Runs the hello world test"> + <test class="com.android.tradefed.example.HelloWorldTest" /> +</configuration></code></pre> + +<p>请将此数据保存到位于本地文件系统任意位置的 <code>helloworld.xml</code> 文件上（例如：<code>/tmp/helloworld.xml</code>）。TF 将解析配置 XML 文件（也称为 <b>config</b> 文件）、使用反射加载指定的类、使其实例化、将其转型为 <code>IRemoteTest</code>，并调用其 <code>run</code> 方法。</p> + +<h2 id="runconfig">运行配置文件 (R)</h2> +<p>从您的 shell 中启动 tradefed 控制台：</p> +<pre><code>$ tradefed.sh +</code></pre> + +<p>确保设备已连接至主机，而且对 tradefed 可见：</p> +<pre><code>tf >list devices +Serial State Product Variant Build Battery +004ad9880810a548 Available mako mako JDQ39 100 +</code></pre> + +<p>您可以使用 <code>run <config></code> 控制台命令执行配置。请尝试输入：</p> +<pre><code>tf> run /tmp/helloworld.xml +05-12 13:19:36 I/TestInvocation: Starting invocation for target stub on build 0 on device 004ad9880810a548 +Hello, TF World! +</code></pre> +<p>您应该可以在终端看到“Hello, TF World！”输出内容。</p> + +<h2 id="addconfig">将配置文件添加到类路径（D、I、R）</h2> +<p>为了方便部署，您还可以将配置文件捆绑到 tradefed JAR 文件自身中。Tradefed 将自动识别类路径下的“config”文件夹中存放的所有配置。<em></em></p> + +<p>为进行详细说明，我们将 <code>helloworld.xml</code> 文件移到 tradefed 核心库 (<code><tree>/tools/tradefederation/core/prod-tests/res/config/example/helloworld.xml</code>) 中。重建 tradefed，重启 tradefed 控制台，然后请求 tradefed 显示类路径中的配置列表：</p> +<pre><code>tf> list configs +[…] +example/helloworld: Runs the hello world test +</code></pre> + +<p>您现在可以使用以下命令运行 helloworld 配置文件：</p> +<pre><code>tf >run example/helloworld +05-12 13:21:21 I/TestInvocation: Starting invocation for target stub on build 0 on device 004ad9880810a548 +Hello, TF World! +</code></pre> + +<h2 id="deviceinteract">与设备交互（D、R）</h2> +<p>到目前为止，我们的 HelloWorldTest 还没有执行任何有趣的操作。Tradefed 专门用于使用 Android 设备运行测试，所以我们向测试中添加一个 Android 设备吧。</p> + +<p>测试可以通过实现 <a href="/reference/com/android/tradefed/testtype/IDeviceTest.html">IDeviceTest</a> 接口来获得 Android 设备引用。以下为展示此步骤的实现示例：</p> +<pre><code>public class HelloWorldTest implements IRemoteTest, IDeviceTest { + private ITestDevice mDevice; + @Override + public void setDevice(ITestDevice device) { + mDevice = device; + } + + @Override + public ITestDevice getDevice() { + return mDevice; + } +… +} +</code></pre> + +<p>在调用 <code>IRemoteTest#run</code> 方法之前，Trade Federation 框架将通过 <code>IDeviceTest#setDevice</code> 方法将 <code>ITestDevice</code> 引用注入到测试中。</p> + +<p>我们来修改下 HelloWorldTest 输出消息，以显示设备的序列号：</p> +<pre><code>@Override +public void run(ITestInvocationListener listener) throws DeviceNotAvailableException { + System.out.println("Hello, TF World! I have device " + getDevice().getSerialNumber()); +} +</code></pre> + +<p>现在重建 tradefed 并检查设备列表：</p> +<pre><code>$ tradefed.sh +tf >list devices +Serial State Product Variant Build Battery +004ad9880810a548 Available mako mako JDQ39 100 +</code></pre> + +<p>记下列为 <strong>Available</strong> 的序列号；表示应分配到 HelloWorld 的设备：</p> +<pre><code>tf >run example/helloworld +05-12 13:26:18 I/TestInvocation: Starting invocation for target stub on build 0 on device 004ad9880810a548 +Hello, TF World! I have device 004ad9880810a548 +</code></pre> + +<p>您应该可以看到显示设备序列号的新输出消息。</p> + +<h2 id="sendresults">发送测试结果 (D)</h2> +<p><code>IRemoteTest</code> 通过对提供给 <code>#run</code> 方法的 <a href="/reference/com/android/tradefed/result/ITestInvocationListener.html">ITestInvocationListener</a> 实例调用方法来报告结果。TF 框架本身负责报告每个调用的开始之处（通过 <a href="/reference/com/android/tradefed/result/ITestInvocationListener.html#invocationStarted(com.android.tradefed.build.IBuildInfo)">ITestInvocationListener#invocationStarted</a>）和结束之处（通过 <a href="/reference/com/android/tradefed/result/ITestInvocationListener.html#invocationEnded(long)">ITestInvocationListener#invocationEnded</a>）。</p> + +<p><b>测试运行</b>是测试的逻辑集合。要报告测试结果，<code>IRemoteTest</code> 负责报告测试运行的开始之处，每个测试的开始和结束之处以及测试运行的结束之处。</p> + +<p>单次测试结果为失败的 HelloWorldTest 实现可能如下所示。</p> +<pre><code>@Override +public void run(ITestInvocationListener listener) throws DeviceNotAvailableException { + System.out.println("Hello, TF World! I have device " + getDevice().getSerialNumber()); + + TestIdentifier testId = new TestIdentifier("com.example.TestClassName", "sampleTest"); + listener.testRunStarted("helloworldrun", 1); + listener.testStarted(testId); + listener.testFailed(testId, "oh noes, test failed"); + listener.testEnded(testId, Collections.emptyMap()); + listener.testRunEnded(0, Collections.emptyMap()); +}</code></pre> + +<p>TF 包括几个可以重复使用的 <code>IRemoteTest</code> 实现，因而您无需从头开始编写您自己的实现。例如，<a href="/reference/com/android/tradefed/testtype/InstrumentationTest.html">InstrumentationTest</a> 可在 Android 设备上远程运行 Android 应用测试、解析结果，并将这些结果转发到 <code>ITestInvocationListener</code>。有关详情，请参阅<a href="/reference/com/android/tradefed/testtype/package-summary.html">测试类型</a>。</p> + +<h2 id="storeresults">存储测试结果 (I)</h2> +<p>TF 配置的默认测试监听器实现为 <a href="/reference/com/android/tradefed/result/TextResultReporter.html">TextResultReporter</a>，它会将调用结果转储到 stdout。请运行上一节中的 HelloWorldTest 配置文件，以进行详细说明：</p> +<pre><code>$ ./tradefed.sh +tf >run example/helloworld +05-16 20:03:15 I/TestInvocation: Starting invocation for target stub on build 0 on device 004ad9880810a548 +Hello, TF World! I have device 004ad9880810a548 +05-16 20:03:15 I/InvocationToJUnitResultForwarder: run helloworldrun started: 1 tests +Test FAILURE: com.example.TestClassName#sampleTest + stack: oh noes, test failed +05-16 20:03:15 I/InvocationToJUnitResultForwarder: run ended 0 ms +</code></pre> + +<p>要将调用结果存储在其他位置（如某个文件中），请使用配置中的 <code>result_reporter</code> 标签来指定自定义 <code>ITestInvocationListener</code> 实现。</p> + +<p>TF 还包括 <a href="/reference/com/android/tradefed/result/XmlResultReporter.html">XmlResultReporter</a> 监听器，它采用与 ant JUnit XML writer 所使用的格式类似的格式将测试结果写入 XML 文件。<em></em>要在配置中指定 result_reporter，请修改 <code>…/res/config/example/helloworld.xml</code> 配置：</p> +<pre><code><configuration description="Runs the hello world test"> + <test class="com.android.tradefed.example.HelloWorldTest" /> + <result_reporter class="com.android.tradefed.result.XmlResultReporter" /> +</configuration> +</code></pre> + +<p>现在重建 tradefed 并重新运行 hello world 示例：</p> +<pre><code>tf >run example/helloworld +05-16 21:07:07 I/TestInvocation: Starting invocation for target stub on build 0 on device 004ad9880810a548 +Hello, TF World! I have device 004ad9880810a548 +05-16 21:07:07 I/XmlResultReporter: Saved device_logcat log to /tmp/0/inv_2991649128735283633/device_logcat_6999997036887173857.txt +05-16 21:07:07 I/XmlResultReporter: Saved host_log log to /tmp/0/inv_2991649128735283633/host_log_6307746032218561704.txt +05-16 21:07:07 I/XmlResultReporter: XML test result file generated at /tmp/0/inv_2991649128735283633/test_result_536358148261684076.xml. Total tests 1, Failed 1, Error 0 +</code></pre> + +<p>请留意表明已生成 XML 文件的日志消息；所生成的文件应如下所示：</p> +<pre><code><?xml version='1.0' encoding='UTF-8' ?> +<testsuite name="stub" tests="1" failures="1" errors="0" time="9" timestamp="2011-05-17T04:07:07" hostname="localhost"> + <properties /> + <testcase name="sampleTest" classname="com.example.TestClassName" time="0"> + <failure>oh noes, test failed + </failure> + </testcase> +</testsuite> +</code></pre> + +<p>您还可以编写您自己的自定义调用监听器 - 它们只需要实现 <a href="/reference/com/android/tradefed/result/ITestInvocationListener.html">ITestInvocationListener</a> 接口。</p> + +<p>Tradefed 支持多个调用监听器，因此您可以将测试结果发送到多个独立的目的地。只需在配置文件中指定多个 <code><result_reporter></code> 标签，即可完成此步骤。</p> + +<h2 id="logging">日志记录（D、I、R）</h2> +<p>TF 的日志记录设备具有以下功能：</p> +<ol> +<li>从设备捕获日志（也称为设备 logcat）</li> +<li>记录在主机上运行的 TradeFederation 框架中的日志（也称为主机日志）</li> +</ol> + +<p>TF 框架自动从分配的设备中捕获 logcat，并将其发送到调用监听器以进行处理。 +然后 <code>XmlResultReporter</code> 将捕获的设备 logcat 保存为文件。 +</p> + +<p>系统使用 ddmlib 日志类的 <a href="/reference/com/android/tradefed/log/LogUtil.CLog.html">CLog 封装容器</a>报告主机日志。让我们将 HelloWorldTest 中之前的 <code>System.out.println</code> 调用转换为 <code>CLog</code> 调用：</p> +<pre><code>@Override +public void run(ITestInvocationListener listener) throws DeviceNotAvailableException { + CLog.i("Hello, TF World! I have device %s", getDevice().getSerialNumber()); +</code></pre> + +<p><code>CLog</code> 直接处理字符串插入，类似于 <code>String.format</code>。当您在重建和重新运行 TF 时，您应该可以在 stdout 上看到此日志消息：</p> +<pre><code>tf> run example/helloworld +… +05-16 21:30:46 I/HelloWorldTest: Hello, TF World! I have device 004ad9880810a548 +… +</code></pre> + +<p>默认情况下，tradefed <a =""="" android com hre="=" tradefed>会将主机日志消息输出到 stdout</a>。TF 还包括将消息写入文件的日志实现：<a href="/reference/com/android/tradefed/log/FileLogger.html">FileLogger</a>。要添加文件日志记录，请将 <code>logger</code> 标签添加到配置文件中，指定 <code>FileLogger</code> 的完整类名：</p> +<pre><code><configuration description="Runs the hello world test"> + <test class="com.android.tradefed.example.HelloWorldTest" /> + <result_reporter class="com.android.tradefed.result.XmlResultReporter" /> + <logger class="com.android.tradefed.log.FileLogger" /> +</configuration> +</code></pre> + +<p>现在，再次重建并运行 helloworld 示例：</p> +<pre><code>tf >run example/helloworld +… +05-16 21:38:21 I/XmlResultReporter: Saved device_logcat log to /tmp/0/inv_6390011618174565918/device_logcat_1302097394309452308.txt +05-16 21:38:21 I/XmlResultReporter: Saved host_log log to /tmp/0/inv_6390011618174565918/host_log_4255420317120216614.txt +… +</code></pre> +<p>该日志消息指出了主机日志的路径，当您查看该日志时，其中应当包含您的 HelloWorldTest 日志消息：</p> +<pre><code>$ more /tmp/0/inv_6390011618174565918/host_log_4255420317120216614.txt +… +05-16 21:38:21 I/HelloWorldTest: Hello, TF World! I have device 004ad9880810a548 +</code></pre> + +<h2 id="optionhandling">处理选项（D、I、R）</h2> +<p>从 TF 配置中加载的对象（也称为<b>配置对象</b>）亦可通过使用 <code>@Option</code> 注释从命令行参数中接收数据。</p><p> + +</p><p>要参与其中，配置对象类会将 <code>@Option</code> 注释应用于相关成员字段，并为其指定一个唯一的名称。这样您便可以通过命令行选项填充该成员字段值（并自动将该选项添加到配置帮助系统）。</p> + +<p class="note"><strong>注意</strong>：部分字段类型可能不受支持。要了解受支持的字段类型，请参阅 <a href="/reference/com/android/tradefed/config/OptionSetter.html">OptionSetter</a>。 +</p> + +<p>我们将 <code>@Option</code> 添加到 HelloWorldTest 中：</p> +<pre><code>@Option(name="my_option", + shortName='m', + description="this is the option's help text", + // always display this option in the default help text + importance=Importance.ALWAYS) +private String mMyOption = "thisisthedefault"; +</code></pre> + +<p>接下来，我们添加一条日志消息来显示 HelloWorldTest 中的选项的值，以便证明已正确接收该值：</p> +<pre><code>@Override +public void run(ITestInvocationListener listener) throws DeviceNotAvailableException { + … + CLog.logAndDisplay(LogLevel.INFO, "I received option '%s'", mMyOption); +</code></pre> + +<p>最后，重建 TF 并运行 helloworld；您应该会看到一条带有 <code>my_option</code> 默认值的日志消息：</p> +<pre><code>tf> run example/helloworld +… +05-24 18:30:05 I/HelloWorldTest: I received option 'thisisthedefault' +</code></pre> + +<h3 id="passclivalues">从命令行传递值</h3> +<p>为 <code>my_option</code> 传入值；您应该可以看到使用此值填充的 <code>my_option</code>：</p> +<pre><code>tf> run example/helloworld --my_option foo +… +05-24 18:33:44 I/HelloWorldTest: I received option 'foo' +</code></pre> + +<p>TF 配置还包括帮助系统，该系统会自动显示 <code>@Option</code> 字段的帮助文本。现在试试看吧，您应该可以看到 <code>my_option</code> 的帮助文本：</p> +<pre><code>tf> run example/helloworld --help +Printing help for only the important options. To see help for all options, use the --help-all flag + + cmd_options options: + --[no-]help display the help text for the most important/critical options. Default: false. + --[no-]help-all display the full help text for all options. Default: false. + --[no-]loop keep running continuously. Default: false. + + test options: + -m, --my_option this is the option's help text Default: thisisthedefault. + + 'file' logger options: + --log-level-display the minimum log level to display on stdout. Must be one of verbose, debug, info, warn, error, assert. Default: error. +</code></pre> + +<p>请注意有关“仅输出重要选项的帮助文本”的消息。为了减少选项帮助的混乱情况，TF 使用 <code>Option#importance</code> 属性来确定是否在指定 <code>--help</code> 时显示特定的 <code>@Option</code> 字段帮助文本。无论字段重要与否，<code>--help-all</code> 始终显示针对所有 <code>@Option</code> 字段的帮助。有关详情，请参阅 <a href="/reference/com/android/tradefed/config/Option.Importance.html">Option.Importance</a>。 +</p> + +<h3 id="passconfvalues">从配置传递值</h3> +<p>您还可以通过添加 <code><option name="" value=""></code> 元素在配置文件中指定“选项”值。使用 <code>helloworld.xml</code> 进行测试：</p> +<pre><code><test class="com.android.tradefed.example.HelloWorldTest" > + <option name="my_option" value="fromxml" /> +</test> +</code></pre> + +<p>重建和运行 helloworld 后现在应产生以下输出内容：</p> +<pre><code>05-24 20:38:25 I/HelloWorldTest: I received option 'fromxml' +</code></pre> + +<p>配置帮助也应经过更新以显示 <code>my_option</code> 的默认值：</p> +<pre><code>tf> run example/helloworld --help + test options: + -m, --my_option this is the option's help text Default: fromxml. +</code></pre> + +<p>helloworld 配置中包含的其他配置对象（如 <code>FileLogger</code>）也接受选项。选项 <code>--log-level-display</code> 比较有意思，因为它会过滤在 stdout 上显示的日志。在本教程前面的部分中，您可能已经注意到：当我们改用 <code>FileLogger</code> 后，stdout 上不再显示“Hello, TF World！ I have device ...”这一日志消息。您可以通过传入 <code>--log-level-display</code> 参数提高 stdout 上日志记录的详细程度。</p> + +<p>请立即尝试，您应该可以看到“I have device”这一日志消息再次出现在 stdout 上，并被记录到某个文件中：</p> +<pre><code>tf >run example/helloworld --log-level-display info +… +05-24 18:53:50 I/HelloWorldTest: Hello, TF World! I have device 004ad9880810a548 +</code></pre> + +<h2 id="conclusion">讲解完毕，谢谢大家！</h2> +<p>在此提醒您，如果您遇到任何问题，可在 <a href="https://android.googlesource.com/platform/tools/tradefederation/+/master">Trade Federation 源代码</a>中找到并未在本文档中公开的大量实用信息。如果所有其他尝试均以失败告终，请尝试在 <a href="/source/community.html">Android 平台</a> Google 网上论坛中咨询（在消息主题中提及“Trade Federation”）。</p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/test_infra/tradefed/fundamentals/index.html b/zh-cn/devices/tech/test_infra/tradefed/fundamentals/index.html new file mode 100644 index 00000000..da602624 --- /dev/null +++ b/zh-cn/devices/tech/test_infra/tradefed/fundamentals/index.html @@ -0,0 +1,44 @@ +<html devsite><head> + <title>开始使用 TF</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>Trade Federation 是一个大型测试架构，可通过调整来适应各种不同的用途，大多数人可能只需要使用它的部分功能。首先，我们设想 TF 用户主要担任三种角色：开发者、集成者和测试运行者。某个特定人员可能担任其中一种或全部三种角色，但我们认为，按照三种不同角色的区分来浏览文档可能会更轻松。</p> + +<h2>开发者</h2> +<p>开发者的主要工作是创建使用 Java 语言编写的 TF 模块。他们还会编写配置并执行测试，但这样做通常是为了验证他们的模块是否可以正确调用并按预期效果运行。</p> + +<h2>集成者</h2> +<p>集成者的主要工作是创建 XML 测试配置或命令文件（使用类似 shell 的简单语言编写）。他们将开发者编写的 TF 模块与特定测试要求和目标所需的特定配置相结合。</p> + +<h2>测试运行者</h2> +<p>测试运行者的主要工作是执行测试，确保生成测试结果，并且生成的测试结果具有相关性、可重现性，而且是准确无误的。他们把大部分时间用于与 tradefed 的命令行界面进行交互，并且还将验证结果是否合理。</p> + +<p>为了充分利用 Trade Federation，三种角色都需要有人担任，缺一不可。开发者和集成者共同协作，来实现 TF 与架构的其他部分（如构建系统和测试结果存储库）的交互。集成者和测试运行者共同协作，确保 TF 能实际运行所需的测试，并产生所需的测试结果。测试运行者则需要识别出无意义的结果，并与开发者和集成者协作来找出存在错误的地方，并将其修复。</p> + +<h2>后续说明</h2> +<p>我们建议担任这三种角色的人员至少完整浏览一遍本文档的其余内容。 +<a href="/devices/tech/test_infra/tradefed/fundamentals/machine_setup.html">机器设置</a>将简要说明运行 TF 的系统要求。<a href="/devices/tech/test_infra/tradefed/fundamentals/devices.html">使用设备</a>将介绍如何使用物理设备、仿真器或不借助设备来运行测试。<a href="/devices/tech/test_infra/tradefed/fundamentals/lifecycle.html">测试生命周期</a>页面将从理论上说明开发者、集成者和测试运行者如何互动。<a href="/devices/tech/test_infra/tradefed/fundamentals/options.html">选项处理</a>则演示如何将该理论付诸实践。</p> + +<p>最后，<a href="/devices/tech/test_infra/tradefed/full_example.html">端到端示例</a>会逐步介绍样本测试的开发、集成和部署过程。它涵盖了每个角色的各个方面，并提供了一些提示，指导您处理文档中未直接讨论的更复杂事项。</p> + +<p>如果您已经阅读了本文档的所有内容，但仍有疑问，请先查阅 <a href="https://android.googlesource.com/platform/tools/tradefederation/+/master">Trade Federation 源代码</a>。此外，您还可以随时在 <a href="/source/community.html">Android 平台</a> Google 网上论坛中提问。为获得最有用的解答，请务必在消息主题中提及“Trade Federation”（或“tradefed”或“TF”）。</p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/test_infra/tradefed/fundamentals/lifecycle.html b/zh-cn/devices/tech/test_infra/tradefed/fundamentals/lifecycle.html new file mode 100644 index 00000000..df075029 --- /dev/null +++ b/zh-cn/devices/tech/test_infra/tradefed/fundamentals/lifecycle.html @@ -0,0 +1,43 @@ +<html devsite><head> + <title>测试生命周期</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>使用 TradeFederation 执行的测试，其生命周期包括四个独立阶段，并且围绕正式定义的接口而设计。</p> +<ul> +<li><a href="/reference/tradefed/com/android/tradefed/build/IBuildProvider.html">版本提供者</a>：提供一个测试版本，必要时可下载适当的文件。</li> +<li><a href="/reference/tradefed/com/android/tradefed/targetprep/ITargetPreparer.html">目标准备器</a>：准备测试环境，其中可能包括软件安装和设备配置。</li> +<li><a href="/reference/tradefed/com/android/tradefed/testtype/IRemoteTest.html">测试</a>：执行测试并收集测试结果。虽然我们的 <a href="/reference/tradefed/com/android/tradefed/testtype/IRemoteTest.html">IRemoteTest</a> 接口专为在 Trade Federation 环境中实现出色性能而设计，但这里执行的测试可以是任何 JUnit 测试。</li> +<li><a href="/reference/tradefed/com/android/tradefed/result/ITestInvocationListener.html">测试调用监听器</a>：监听测试结果，通常用于将测试结果转发到存储区或将其显示给测试运行者。</li> +</ul> + +<p>TF 中的基本测试实体是一项<b>配置</b> (config)。config 是一个 XML 文件，用于声明测试的生命周期组件。</p> + +<p>对测试生命周期进行独立分段的目的是方便重复使用。使用该设计，开发者可以创建一次测试，然后集成者可以创建不同的配置，以便在不同环境中运行该测试。例如，他们可以创建一项配置，该配置可以在本地计算机上运行测试并将测试结果转储到 stdout。然后，他们可以创建执行相同测试的第二个配置，但使用不同的测试调用监听器将测试结果存储在数据库中。他们还可能设计第三个配置，用于从某处的测试实验室进行连续测试。</p> + +<p>这里顺便说明一下，一个配置加上相关命令行参数（由测试运行者提供）一起称为<b>命令</b>。当 TF 将 <code>ITestDevice</code> 与命令配对并执行该命令时，后续对象称为<b>调用</b>。简而言之，调用包含贯穿整个生命周期的完整 TF 测试执行过程。</p> + +<h3>配置的附加组件</h3> +<ul> +<li><a href="/reference/tradefed/com/android/tradefed/device/IDeviceRecovery.html">设备恢复</a>：设备丢失时的设备通信恢复机制。</li> +<li><a href="/reference/tradefed/com/android/tradefed/log/package-summary.html">日志记录器</a>：收集 tradefed 日志数据。</li> +</ul> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/test_infra/tradefed/fundamentals/machine_setup.html b/zh-cn/devices/tech/test_infra/tradefed/fundamentals/machine_setup.html new file mode 100644 index 00000000..780ee221 --- /dev/null +++ b/zh-cn/devices/tech/test_infra/tradefed/fundamentals/machine_setup.html @@ -0,0 +1,49 @@ +<html devsite><head> + <title>开发环境</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>Trade Federation 通过 AOSP 进行分发，并使用 Android 编译系统来创建二进制文件。请先<a href="/source/initializing.html">搭建一个编译环境</a>，以便使用 Android 源代码树来编译和运行软件包。 +</p> + +<h2>创建 TradeFed</h2> + +<p>在 Android 源代码树的根目录处：</p> +<pre> +<code class="devsite-terminal">source ./build/make/envsetup.sh</code> +<code class="devsite-terminal">lunch <device-target></code> +<code class="devsite-terminal">make tradefed-all -j8</code> +</pre> + +<h2>使用命令行运行</h2> + +<p>TradeFed 要求使用 <code>$PATH</code> 中的实用工具 <code>adb</code>：</p> +<pre class="devsite-terminal"> +export PATH=$PATH:<path/to/adb> +</pre> + +<p>创建 TradeFed 后，<code>tradefed.sh</code> 启动器脚本便可供从您的路径进行访问。要启动 Trade Federation 控制台：</p> +<pre class="devsite-terminal"> +tradefed.sh +</pre> +<p>现在，您的 Trade Federation 环境即已搭建完毕。 +</p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/test_infra/tradefed/fundamentals/vts.html b/zh-cn/devices/tech/test_infra/tradefed/fundamentals/vts.html new file mode 100644 index 00000000..ef2a501c --- /dev/null +++ b/zh-cn/devices/tech/test_infra/tradefed/fundamentals/vts.html @@ -0,0 +1,82 @@ +<html devsite><head> + <title>使用 VTS 进行系统测试</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>供应商测试套件 (VTS) 会自动执行 HAL 和 OS 内核测试。要使用 VTS 测试 Android 原生系统的实现情况，请设置一个测试环境，然后使用 VTS 计划测试相应补丁。</p> + +<h2 id="establish">建立测试环境</h2> +<p>要设置测试环境，请按以下步骤操作：</p> +<ol> +<li>安装 Python 开发工具包： +<pre><code>$ sudo apt-get install python-dev</code></pre></li> +<li>安装协议缓冲区工具（适用于 Python）： +<pre><code>$ sudo apt-get install python-protobuf<br /> +$ sudo apt-get install protobuf-compiler +</code></pre></li> +<li>安装 Python 虚拟环境相关工具： +<pre><code>$ sudo apt-get install python-virtualenv<br /> +$ sudo apt-get install python-pip +</code></pre></li></ol> + +<h2 id="test">测试补丁</h2> +<p>要测试补丁，请按以下步骤操作：</p> +<ol> +<li>构建 VTS 主机端软件包： +<pre><code>$ . build/envsetup.sh +$ lunch aosp_arm64-userdebug +$ make vts -j</code></pre></li> +<li>运行默认的 VTS 测试： +<pre><code>$ vts-tradefed<br /> +> run vts // where vts is the test plan name +</code></pre></li></ol> + +<h2 id="plans">VTS 计划</h2> +<p>可用的 VTS 测试计划包括：</p> + +<table> +<thead> +<tr> +<th>命令</th> +<th>说明</th> +</tr> +</thead> +<tbody> +<tr> +<td>> run vts</td> +<td>适用于默认的 VTS 测试</td> +</tr> +<tr> +<td>> run vts-hal</td> +<td>适用于默认的 VTS HAL（硬件抽象层）测试</td> +</tr> +<tr> +<td>> run vts-kernel</td> +<td>适用于默认的 VTS 内核测试</td> +</tr> +</tbody> +</table> + +<p>要查看所有计划的列表，请参阅 <code><a href="https://android.googlesource.com/platform/test/vts/+/master/tools/vts-tradefed/res/config/plans.md">/test/vts/tools/vts-tradefed/res/config.md</a></code>。</p> + +<h2 id="support">支持</h2> +<p>您可以在 <code><a href=" https://android.googlesource.com/platform/test/vts/+/master/README.md">/test/vts/doc</a></code> 中查看用户手册。有关 VTS 的问题，请加入 <a href="https://groups.google.com/forum/#!forum/android-vts">android-vts@googlegroups.com</a> 网上论坛。</p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/test_infra/tradefed/template.html b/zh-cn/devices/tech/test_infra/tradefed/template.html new file mode 100644 index 00000000..a299ee9a --- /dev/null +++ b/zh-cn/devices/tech/test_infra/tradefed/template.html @@ -0,0 +1,28 @@ +<html devsite><head> + <title>模板</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>写一些内容吧</p> + +<h2>嘿，这是标题！</h2> +<p>再写一些内容吧</p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/security/bulletin/2017-07-01.html b/zh-cn/security/bulletin/2017-07-01.html index 847b89b9..76304a36 100644 --- a/zh-cn/security/bulletin/2017-07-01.html +++ b/zh-cn/security/bulletin/2017-07-01.html @@ -31,7 +31,7 @@ <p>我们建议所有用户都在自己的设备上接受这些更新。</p> -<p class="note"><strong>注意</strong>：如需了解与最新的无线更新 (OTA) 和适用于 Google 设备的固件映像有关的信息，请参阅 <a href="#google-device-updates">Google 设备更新</a>部分。</p> +<p class="note"><strong>注意</strong>：如需了解与最新的无线下载更新 (OTA) 和适用于 Google 设备的固件映像有关的信息，请参阅 <a href="#google-device-updates">Google 设备更新</a>部分。</p> <h2 id="announcements">公告</h2> <ul> @@ -1298,6 +1298,10 @@ <th>研究人员</th> </tr> <tr> + <td>CVE-2017-8263</td> + <td>Google 的 Billy Lau</td> + </tr> + <tr> <td>CVE-2017-0711</td> <td>阿里巴巴移动安全团队的 Chengming Yang、Baozeng Ding 和 Yang Song</td> </tr> @@ -1358,7 +1362,7 @@ <td>CSS Inc. 的 Timothy Becker</td> </tr> <tr> - <td>CVE-2017-0642、CVE-2017-0682、CVE-2017-0683、CVE-2017-0676、CVE-2017-0696、CVE-2017-0675、CVE-2017-0701、CVE-2017-0702、CVE-2017-0699</td> + <td>CVE-2017-0682、CVE-2017-0683、CVE-2017-0676、CVE-2017-0696、CVE-2017-0675、CVE-2017-0701、CVE-2017-0702、CVE-2017-0699</td> <td>Vasily Vasiliev</td> </tr> <tr> @@ -1509,6 +1513,11 @@ <td>2017 年 7 月 6 日</td> <td>修订了本公告，添加了 AOSP 链接。</td> </tr> + <tr> + <td>1.2</td> + <td>2017 年 7 月 11 日</td> + <td>修订了本公告，更新了致谢信息。</td> + </tr> </tbody></table> </body></html>
\ No newline at end of file diff --git a/zh-tw/security/bulletin/2017-07-01.html b/zh-tw/security/bulletin/2017-07-01.html index 188958eb..e3a489d4 100644 --- a/zh-tw/security/bulletin/2017-07-01.html +++ b/zh-tw/security/bulletin/2017-07-01.html @@ -21,13 +21,13 @@ --> <p><em>2017 年 7 月 5 日發佈 | 2017 年 7 月 6 日更新</em></p> -<p>Android 安全性公告羅列了會對 Android 裝置造成影響的安全性漏洞，並說明各項相關細節。2017 年 7 月 5 日之後的安全修補等級已解決了這些問題。請參閱 <a href="//support.google.com/pixelphone/answer/4457705#pixel_phones&nexus_devices">Pixel 與 Nexus 更新時間表</a>，瞭解如何查看裝置的安全修補等級。</p> +<p>Android 安全性公告羅列了會對 Android 裝置造成影響的安全性漏洞，並說明各項相關細節。2017 年 7 月 5 日之後的安全性修補程式等級已解決了這些問題。請參閱 <a href="//support.google.com/pixelphone/answer/4457705#pixel_phones&nexus_devices">Pixel 與 Nexus 更新時間表</a>，瞭解如何查看裝置的安全性修補程式等級。</p> <p>我們的合作夥伴在至少一個月之前已收到公告中所述問題的相關通知。這些問題的原始碼修補程式已發佈到 Android 開放原始碼計劃 (AOSP) 存放區中，且公告中亦提供相關連結。此外，本公告也提供 AOSP 以外的修補程式連結。</p> <p>在這些問題中，最嚴重的就是媒體架構中「最高」等級的安全性漏洞。遠端攻擊者可利用這類漏洞，在獲得授權的程序環境內透過特製檔案執行任何指令。<a href="/security/overview/updates-resources.html#severity">嚴重程度評定標準</a>是假設平台與服務的因應防護措施基於開發作業的需求而被關閉，或是遭到有心人士破解，然後推算當有人惡意運用漏洞時，使用者的裝置會受到多大的影響，據此評定漏洞的嚴重程度。</p> -<p>針對這些新發現的漏洞，我們目前尚未收到任何客戶回報相關的漏洞濫用案例。如果想進一步瞭解 <a href="/security/enhancements/index.html">Android 安全性平台防護措施</a>和 Google Play 安全防護如何加強 Android 平台的安全性，請參閱 <a href="#mitigations">Android 和 Google Play 安全防護機制所提供的因應措施</a>。</p> +<p>針對這些新發現的漏洞，我們目前尚未收到任何客戶回報相關的漏洞濫用案例。如果想進一步瞭解 <a href="/security/enhancements/index.html">Android 安全性平台防護措施</a>和 Google Play 安全防護機制如何加強 Android 平台的安全性，請參閱 <a href="#mitigations">Android 和 Google Play 安全防護因應措施</a>。</p> <p>我們建議所有客戶接受這些裝置更新。</p> @@ -35,9 +35,9 @@ <h2 id="announcements">公告</h2> <ul> - <li>本公告有兩個安全修補等級字串，讓 Android 合作夥伴能夠靈活運用，以快速修正某些發生在所有 Android 裝置上的類似漏洞。如需查詢其他相關資訊，請參閱<a href="#common-questions-and-answers">常見問題與解答</a>：<ul> - <li><strong>2017-07-01</strong>：部分安全修補等級字串。這個安全修補等級字串表示所有與 2017-07-01 相關的問題 (以及所有先前的安全修補等級字串) 都已獲得解決。</li> - <li><strong>2017-07-05</strong>：完整安全修補等級字串。這個安全修補等級字串表示所有與 2017-07-01 和 2017-07-05 相關的問題 (以及所有先前的安全修補等級字串) 都已獲得解決。</li> + <li>本公告有兩個安全性修補程式等級字串，讓 Android 合作夥伴能夠靈活運用，以快速修正某些發生在所有 Android 裝置上的類似漏洞。如需查詢其他相關資訊，請參閱<a href="#common-questions-and-answers">常見問題與解答</a>：<ul> + <li><strong>2017-07-01</strong>：部分安全性修補程式等級字串。這個安全性修補程式等級字串表示所有與 2017-07-01 相關的問題 (以及所有先前的安全性修補程式等級字串) 都已獲得解決。</li> + <li><strong>2017-07-05</strong>：完整安全性修補程式等級字串。這個安全性修補程式等級字串表示所有與 2017-07-01 和 2017-07-05 相關的問題 (以及所有先前的安全性修補程式等級字串) 都已獲得解決。</li> </ul> </li> </ul> @@ -50,8 +50,8 @@ </li> </ul> -<h2 id="2017-07-01-details">2017-07-01 安全修補等級 — 資安漏洞詳情</h2> -<p>下列各節針對 2017-07-01 安全修補等級適用的各項安全性漏洞提供了詳細資訊。資安漏洞是依照受它們影響的元件分門別類。包括問題說明和一份漏洞資訊表、相關參照、<a href="#common-questions-and-answers">漏洞類型</a>、<a href="/security/overview/updates-resources.html#severity">嚴重程度</a>，以及更新的 AOSP 版本 (在適用情況下)。假如相關錯誤有公開變更，該錯誤 ID 會連結到相對應的變更 (例如 AOSP 變更清單)。如果單一錯誤有多項相關變更，您可以透過該錯誤 ID 後面的編號連結開啟額外的參考資料。</p> +<h2 id="2017-07-01-details">2017-07-01 安全性修補程式等級 — 資安漏洞詳情</h2> +<p>下列各節針對 2017-07-01 安全性修補程式等級適用的各項安全性漏洞提供了詳細資訊。資安漏洞是依照受它們影響的元件分門別類。包括問題說明和一份 CVE 資訊表、相關參考資料、<a href="#common-questions-and-answers">漏洞類型</a>、<a href="/security/overview/updates-resources.html#severity">嚴重程度</a>，以及更新的 AOSP 版本 (在適用情況下)。假如相關錯誤有公開變更，該錯誤 ID 會連結到相對應的變更 (例如 AOSP 變更清單)。如果單一錯誤有多項相關變更，您可以透過該錯誤 ID 後面的編號連結開啟額外的參考資料。</p> <h3 id="runtime">執行階段</h3> <p>本節中最嚴重的漏洞可能會讓遠端攻擊者得以利用特製檔案在未獲授權的程序環境內執行任何指令。</p> @@ -482,8 +482,8 @@ </tr> </tbody></table> -<h2 id="2017-07-05-details">2017-07-05 安全修補等級 — 資安漏洞詳情</h2> -<p>下列各節針對 2017-07-05 安全修補等級適用的各項安全性漏洞提供了詳細資訊，資安漏洞是依照受它們影響的元件分門別類，並且包含一些詳細資料，例如 CVE、相關參考資料、<a href="#common-questions-and-answers">漏洞類型</a>、<a href="/security/overview/updates-resources.html#severity">嚴重程度</a>、元件 (在適用情況下)，和更新的 AOSP 版本 (在適用情況下)。假如相關錯誤有公開變更，該錯誤 ID 會連結到相對應的變更 (例如 AOSP 變更清單)。如果單一錯誤有多項相關變更，您可以透過該錯誤 ID 後面的編號連結開啟額外的參考資料。</p> +<h2 id="2017-07-05-details">2017-07-05 安全性修補程式等級 — 資安漏洞詳情</h2> +<p>下列各節針對 2017-07-05 安全性修補程式等級適用的各項安全性漏洞提供了詳細資訊，資安漏洞是依照受它們影響的元件分門別類，並且包含一些詳細資料，例如 CVE、相關參考資料、<a href="#common-questions-and-answers">漏洞類型</a>、<a href="/security/overview/updates-resources.html#severity">嚴重程度</a>、元件 (在適用情況下)，和更新的 AOSP 版本 (在適用情況下)。假如相關錯誤有公開變更，該錯誤 ID 會連結到相對應的變更 (例如 AOSP 變更清單)。如果單一錯誤有多項相關變更，您可以透過該錯誤 ID 後面的編號連結開啟額外的參考資料。</p> <h3 id="broadcom-components">Broadcom 元件</h3> <p>本節中最嚴重的漏洞可能會讓鄰近的攻擊者在核心環境內執行任何指令。</p> @@ -615,7 +615,9 @@ <tr> <td>CVE-2017-7308</td> <td>A-36725304<br /> -<a href="//git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=2b6867c2ce76c596676bec7d2d525af525fdc6e2">上游程式庫核心</a> [<a href="//git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=8f8d28e4d6d815a391285e121c3a53a0b6cb9e7b">2</a>] [<a href="//git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=bcc5364bdcfe131e6379363f089e7b4108d35b70">3</a>]</td> +<a href="//git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=2b6867c2ce76c596676bec7d2d525af525fdc6e2">上游程式庫核心</a> +[<a href="//git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=8f8d28e4d6d815a391285e121c3a53a0b6cb9e7b">2</a>] +[<a href="//git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=bcc5364bdcfe131e6379363f089e7b4108d35b70">3</a>]</td> <td>EoP</td> <td>中</td> <td>網路驅動程式</td> @@ -906,7 +908,7 @@ </tr> </tbody></table> <h3 id="qualcomm-closed-source-components">Qualcomm 封閉原始碼元件</h3> -<p>以下列出會影響 Qualcomm 元件的安全性漏洞，詳情請參考 2014 至 2016 年之間發佈的 Qualcomm AMSS 安全性公告。我們在這個 Android 安全性公告中列出這些漏洞，方便使用者確認漏洞修正程式及其相對應的 Android 安全修補等級。Qualcomm 公司親自提供了這些漏洞的修正程式。</p> +<p>以下列出會影響 Qualcomm 元件的安全性漏洞，詳情請參考 2014 至 2016 年之間發佈的 Qualcomm AMSS 安全性公告。我們在這個 Android 安全性公告中列出這些漏洞，方便使用者確認漏洞修正程式及其相對應的 Android 安全性修補程式等級。Qualcomm 公司親自提供了這些漏洞的修正程式。</p> <table> <colgroup><col width="17%" /> @@ -1363,14 +1365,14 @@ </tr> </tbody></table> <h2 id="google-device-updates">Google 裝置更新</h2> -<p>此表格包含最新無線下載更新 (OTA) 中的安全修補等級和 Google 裝置的韌體映像檔。您可以前往 <a href="//developers.google.com/android/nexus/images">Google Developer 網站</a>取得 Google 裝置韌體映像檔。</p> +<p>此表格包含最新無線下載更新 (OTA) 中的安全性修補程式等級和 Google 裝置的韌體映像檔。您可以前往 <a href="//developers.google.com/android/nexus/images">Google Developer 網站</a>取得 Google 裝置韌體映像檔。</p> <table> <colgroup><col width="25%" /> <col width="75%" /> </colgroup><tbody><tr> <th>Google 裝置</th> - <th>安全修補等級</th> + <th>安全性修補程式等級</th> </tr> <tr> <td>Pixel/Pixel XL</td> @@ -1412,6 +1414,10 @@ <th>研究人員</th> </tr> <tr> + <td>CVE-2017-8263</td> + <td>Google 的 Billy Lau</td> + </tr> + <tr> <td>CVE-2017-0711</td> <td>阿里巴巴行動安全小組成員 Chengming Yang、Baozeng Ding 和 Yang Song</td> </tr> @@ -1457,7 +1463,7 @@ </tr> <tr> <td>CVE-2017-0697、CVE-2017-0670</td> - <td><a href="mailto:jiych.guru@gmail.com">Niky1235</a> (<a href="//twitter.com/jiych_guru">@jiych_guru</a>)</td> + <td><a href="mailto:jiych.guru@gmail.com">Niky1235</a> (<a href="//twitter.com/jiych_guru">@jiych_guru)</a></td> </tr> <tr> <td>CVE-2017-9417</td> @@ -1472,11 +1478,14 @@ <td>CSS Inc. 的 Timothy Becker</td> </tr> <tr> - <td>CVE-2017-0642、CVE-2017-0682、CVE-2017-0683、CVE-2017-0676、CVE-2017-0696、CVE-2017-0675、CVE-2017-0701、CVE-2017-0702、CVE-2017-0699</td> + <td>CVE-2017-0682、CVE-2017-0683、CVE-2017-0676、 +CVE-2017-0696、CVE-2017-0675、CVE-2017-0701、CVE-2017-0702、CVE-2017-0699</td> <td>Vasily Vasiliev</td> </tr> <tr> - <td>CVE-2017-0695、CVE-2017-0689、CVE-2017-0540、CVE-2017-0680、CVE-2017-0679、CVE-2017-0685、CVE-2017-0686、CVE-2017-0693、CVE-2017-0674、CVE-2017-0677</td> + <td>CVE-2017-0695、CVE-2017-0689、CVE-2017-0540、CVE-2017-0680、 +CVE-2017-0679、CVE-2017-0685、CVE-2017-0686、CVE-2017-0693、CVE-2017-0674、 +CVE-2017-0677</td> <td><a href="//www.trendmicro.com">趨勢科技</a><a href="//blog.trendmicro.com/trendlabs-security-intelligence/category/mobile/">行動威脅研究小組</a>成員 V.E.O (<a href="//twitter.com/vysea">@VYSEa</a>)</td> </tr> <tr> @@ -1514,22 +1523,22 @@ <p><strong>1. 如何判斷我目前的裝置軟體版本是否已修正這些問題？ </strong></p> -<p>要瞭解如何查看裝置的安全修補等級，請詳讀 <a href="//support.google.com/pixelphone/answer/4457705#pixel_phones&nexus_devices">Pixel 和 Nexus 更新時間表</a>中的操作說明。</p> +<p>如要瞭解如何查看裝置的安全性修補程式等級，請詳讀 <a href="//support.google.com/pixelphone/answer/4457705#pixel_phones&nexus_devices">Pixel 和 Nexus 更新時間表</a>中的操作說明。</p> <ul> - <li>2017 年 7 月 1 日之後的安全修補等級已解決了所有與 2017-07-01 安全修補等級相關的問題。</li> - <li>2017 年 7 月 5 日之後的安全修補等級完全解決了與 2017-07-05 安全修補等級及所有先前修補等級相關的問題。</li> + <li>2017 年 7 月 1 日之後的安全性修補程式等級已解決了所有與 2017-07-01 安全性修補程式等級相關的問題。</li> + <li>2017 年 7 月 5 日之後的安全性修補程式等級完全解決了與 2017-07-05 安全性修補程式等級及所有先前修補程式等級相關的問題。</li> </ul> <p>提供這些更新的裝置製造商應將修補程式字串等級設定為：</p> <ul> <li>[ro.build.version.security_patch]:[2017-07-01]</li> <li>[ro.build.version.security_patch]:[2017-07-05]</li> </ul> -<p><strong>2. 為什麼這篇公告有兩種安全修補等級？</strong></p> +<p><strong>2. 為什麼這篇公告有兩種安全性修補程式等級？</strong></p> -<p>本公告有兩種安全修補等級，讓 Android 合作夥伴能夠靈活運用，以快速修正某些發生在所有 Android 裝置上的類似漏洞。我們建議 Android 合作夥伴修正本公告所列的所有問題，並使用最新的安全修補等級。</p> +<p>本公告有兩種安全性修補程式等級，讓 Android 合作夥伴能夠靈活運用，以快速修正某些發生在所有 Android 裝置上的類似漏洞。我們建議 Android 合作夥伴修正本公告所列的所有問題，並使用最新的安全性修補程式等級。</p> <ul> - <li>使用 2017 年 7 月 1 日安全修補等級的裝置必須納入所有與該安全修補等級相關的問題，以及在之前安全性公告中回報的所有問題適用的修正程式。</li> - <li>如果裝置是使用 2017 年 7 月 5 日之後的安全修補等級，就必須加入本安全性公告 (以及之前公告) 中的所有適用修補程式。</li> + <li>使用 2017 年 7 月 1 日安全性修補程式等級的裝置必須納入所有與該安全性修補程式等級相關的問題，以及在之前安全性公告中回報的所有問題適用的修正程式。</li> + <li>如果裝置是使用 2017 年 7 月 5 日之後的安全性修補程式等級，就必須加入本安全性公告 (以及之前公告) 中的所有適用修補程式。</li> </ul> <p>我們建議合作夥伴將所要解決的所有問題適用修補程式彙整在單一更新中。</p> @@ -1621,7 +1630,12 @@ <tr> <td>1.1</td> <td>2017 年 7 月 6 日</td> - <td>修訂公告，加入 AOSP 連結。</td> + <td>修訂公告內容 (加入 AOSP 連結)。</td> + </tr> + <tr> + <td>1.2</td> + <td>2017 年 7 月 11 日</td> + <td>修訂公告內容 (更新特別銘謝名單)。</td> </tr> </tbody></table> |