diff options
| author | Android Partner Docs <noreply@android.com> | 2017-12-05 15:57:15 -0800 |
|---|---|---|
| committer | Clay Murphy <claym@google.com> | 2017-12-05 21:16:56 -0800 |
| commit | a63d28d20492979243f7cac739a506d308334a86 (patch) | |
| tree | ae2e203f4bf4eb3072e9a06ba2e512dc9230d8da /en/devices | |
| parent | 54024816e734bc99e432f281baabcf4718b9197a (diff) | |
| download | source.android.com-a63d28d20492979243f7cac739a506d308334a86.tar.gz | |
Docs: Changes to source.android.com
- 178024672 CDD updates for Android 8.1 (O MR1). by Gina Dimino <gdimino@google.com>
- 178024315 Document tags pushed to AOSP for December Security Releas... by Android Partner Docs <noreply@android.com>
- 178019963 Add TextClassifier feature to Site Updates. by Mark Hecomovich <mheco@google.com>
- 177986632 Add CTS/CTS-Verifier downloads for CTS-8.1R1 Release by Android Partner Docs <noreply@android.com>
- 177981307 Update December Pixel bulletin to note that firmware imag... by Android Partner Docs <noreply@android.com>
- 177977792 Note Source->Setup rename in site updates. by Billy Lamberta <blamb@google.com>
- 177972113 Add O MR1 doc changes to Site Updates by Clay Murphy <claym@google.com>
- 177970750 Integrate O MR1 branch into mainline by Clay Murphy <claym@google.com>
- 177966804 Fix typo: Digital Stream Digital > Direct Stream Digital by Christina Nguyen <cqn@google.com>
- 177966781 Exclude Android 8.1 compatibility directory from localiza... by Danielle Roberts <daroberts@google.com>
- 177857487 Specify additional ABI breaking changes. by Android Partner Docs <noreply@android.com>
- 177855089 Add attribution for William Roberts by Danielle Roberts <daroberts@google.com>
- 177844366 Devsite localized content from translation request 63bb47... by Android Partner Docs <noreply@android.com>
- 177840956 Devsite localized content from translation request 3a9204... by Android Partner Docs <noreply@android.com>
- 177840933 Devsite localized content from translation request 526dee... by Android Partner Docs <noreply@android.com>
- 177840699 Devsite localized content from translation request f000cb... by Android Partner Docs <noreply@android.com>
- 177833559 Fix table in Dec pixel bulletin by Danielle Roberts <daroberts@google.com>
- 177832645 Fix broken link in Security bulletin by Danielle Roberts <daroberts@google.com>
- 177830793 Fix index files for security bulletins by Danielle Roberts <daroberts@google.com>
- 177829204 December 2017 Android and Pixel security bulletins by Danielle Roberts <daroberts@google.com>
- 177619977 Add links to most recently localized files by Clay Murphy <claym@google.com>
- 177553556 Devsite localized content from translation request df5038... by Android Partner Docs <noreply@android.com>
- 177553553 Devsite localized content from translation request 3feff8... by Android Partner Docs <noreply@android.com>
- 177553549 Devsite localized content from translation request 57c74f... by Android Partner Docs <noreply@android.com>
- 177530761 Devsite localized content from translation request 52ae7a... by Android Partner Docs <noreply@android.com>
- 177530750 Devsite localized content from translation request f48e7b... by Android Partner Docs <noreply@android.com>
- 177402074 Make CVE-2017-0639 optional by Android Partner Docs <noreply@android.com>
- 177220538 Devsite localized content from translation request eaaf1d... by Android Partner Docs <noreply@android.com>
- 177208086 Fixing bad link. by Heidi von Markham <hvm@google.com>
- 177091447 updated CVEs by Android Partner Docs <noreply@android.com>
- 177091159 Devsite localized content from translation request dcaa09... by Android Partner Docs <noreply@android.com>
- 177091156 Devsite localized content from translation request 23af27... by Android Partner Docs <noreply@android.com>
- 177087486 Update HIDL documentation to reflect actual passthrough i... by Android Partner Docs <noreply@android.com>
PiperOrigin-RevId: 178024672
Change-Id: I593c61d26aac1fdcebb184ac048dbca7696161b1
Diffstat (limited to 'en/devices')
28 files changed, 1719 insertions, 43 deletions
diff --git a/en/devices/_toc-interfaces.yaml b/en/devices/_toc-interfaces.yaml index a7958fc3..0a5ce26f 100644 --- a/en/devices/_toc-interfaces.yaml +++ b/en/devices/_toc-interfaces.yaml @@ -155,6 +155,8 @@ toc: path: /devices/audio/data_formats - title: Attributes path: /devices/audio/attributes + - title: AAudio and MMAP + path: /devices/audio/aaudio - title: Warmup path: /devices/audio/warmup - title: Latency diff --git a/en/devices/_toc-tech.yaml b/en/devices/_toc-tech.yaml index dd7e48a2..9daad091 100644 --- a/en/devices/_toc-tech.yaml +++ b/en/devices/_toc-tech.yaml @@ -37,6 +37,8 @@ toc: path: /devices/tech/config/perms-whitelist - title: Runtime Permissions path: /devices/tech/config/runtime_perms + - title: Time Zone Rules + path: /devices/tech/config/timezone-rules - title: UICC path: /devices/tech/config/uicc - title: USB HAL @@ -63,6 +65,8 @@ toc: path: /devices/tech/connect/connect_tests - title: Radio Interface Layer (RIL) path: /devices/tech/connect/ril + - title: Wi-Fi Aware + path: /devices/tech/connect/wifi-aware - title: Data Usage section: - title: Overview @@ -147,6 +151,8 @@ toc: path: /devices/tech/display/app-shortcuts - title: Circular Icons path: /devices/tech/display/circular-icons + - title: Color Management + path: /devices/tech/display/color-mgmt - title: Do Not Disturb path: /devices/tech/display/dnd - title: HDR Video @@ -161,6 +167,8 @@ toc: path: /devices/tech/display/retail-mode - title: Split-Screen Interactions path: /devices/tech/display/split-screen + - title: TEXTCLASSIFIER + path: /devices/tech/display/textclassifier - title: Widgets & Shortcuts path: /devices/tech/display/widgets-shortcuts - title: OTA Updates diff --git a/en/devices/architecture/hidl-cpp/index.html b/en/devices/architecture/hidl-cpp/index.html index f42d8f8a..7d8466cb 100644 --- a/en/devices/architecture/hidl-cpp/index.html +++ b/en/devices/architecture/hidl-cpp/index.html @@ -92,11 +92,13 @@ hidl-gen -o $LOC -Landroidbp-impl -randroid.hardware:hardware/interfaces \ <p>For the HAL to work in passthrough mode (for legacy devices), you must have the function <em>HIDL_FETCH_IModuleName</em> residing in -<code>/system/lib(64)?/hw/android.hardware.package@3.0-impl(-$OPTIONAL_IDENTIFIER).so</code> +<code>/system/lib(64)?/hw/android.hardware.package@3.0-impl($OPTIONAL_IDENTIFIER).so</code> where <code>$OPTIONAL_IDENTIFIER</code> is a string identifying the passthrough implementation. The passthrough mode requirements are met automatically by the above commands, which also create the <code>android.hardware.nfc@1.0-impl</code> -target.</p> +target, but any extension can be used. For instance +<code>android.hardware.nfc@1.0-impl-foo</code> uses <code>-foo</code> to +differentiate itself.</p> <p>Next, fill out the stubs with functionality and setup a daemon. Example daemon code (supporting passthrough):</p> diff --git a/en/devices/architecture/hidl/hashing.html b/en/devices/architecture/hidl/hashing.html index e083fd4c..3debea85 100644 --- a/en/devices/architecture/hidl/hashing.html +++ b/en/devices/architecture/hidl/hashing.html @@ -151,6 +151,8 @@ interfaces which maintain ABI stability. Review the following types of changes: <td> <ul> <li>Reordering arguments, methods, etc…</li> +<li>Renaming an interface or moving it to a new package.</li> +<li>Renaming a package.</li> <li>Adding a method/struct field/etc… anywhere in the interface.</li> <li>Anything that would break a C++ vtable.</li> <li>etc..</li> diff --git a/en/devices/architecture/images/treble_latency_bubble.png b/en/devices/architecture/images/treble_latency_bubble.png Binary files differnew file mode 100644 index 00000000..72a83c05 --- /dev/null +++ b/en/devices/architecture/images/treble_latency_bubble.png diff --git a/en/devices/architecture/images/treble_priority_inv_rta.png b/en/devices/architecture/images/treble_priority_inv_rta.png Binary files differnew file mode 100644 index 00000000..5ece38be --- /dev/null +++ b/en/devices/architecture/images/treble_priority_inv_rta.png diff --git a/en/devices/architecture/images/treble_priority_inv_rta_blocked.png b/en/devices/architecture/images/treble_priority_inv_rta_blocked.png Binary files differnew file mode 100644 index 00000000..fe218529 --- /dev/null +++ b/en/devices/architecture/images/treble_priority_inv_rta_blocked.png diff --git a/en/devices/architecture/images/treble_systrace_binder_processes.png b/en/devices/architecture/images/treble_systrace_binder_processes.png Binary files differnew file mode 100644 index 00000000..425dcd07 --- /dev/null +++ b/en/devices/architecture/images/treble_systrace_binder_processes.png diff --git a/en/devices/audio/aaudio.html b/en/devices/audio/aaudio.html new file mode 100644 index 00000000..fb62ab87 --- /dev/null +++ b/en/devices/audio/aaudio.html @@ -0,0 +1,359 @@ +<html devsite> + <head> + <title>AAudio and MMAP</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> +AAudio is an audio API introduced in the Android 8.0 release. The Android 8.1 +release has enhancements to reduce latency when used in conjunction with a HAL +and driver that support MMAP. This document describes the hardware abstraction +layer (HAL) and driver changes needed to support AAudio's MMAP feature in +Android. +</p> + +<p> +Support for AAudio MMAP requires: +</p> + +<ul> +<li>reporting the MMAP capabilities of the HAL +<li>implementing new functions in the HAL +<li>optionally implementing a custom ioctl() for the EXCLUSIVE mode buffer +<li>providing an additional hardware data path</li> +<li>setting system properties that enable MMAP feature</li> +</ul> + +<aside class="note"><strong>Note:</strong> Enable the MMAP feature +only on Android O MR1 or higher.</aside> + +<h2 id="aaudio-architecture">AAudio architecture</h2> + +<p> +<a +href="https://developer.android.com/ndk/guides/audio/aaudio/aaudio.html">AAudio</a> +is a new native C API that provides an alternative to Open SL ES. It uses a +Builder design pattern to create audio streams. +</p> + +<p> +AAudio provides a low-latency data path. In EXCLUSIVE mode, the feature +allows client application code to write directly into a memory mapped buffer +that is shared with the ALSA driver. In SHARED mode, the MMAP buffer is used by +a mixer running in the AudioServer. In EXCLUSIVE mode, the latency is +significantly less because the data bypasses the mixer. +</p> + +<p> +In EXCLUSIVE mode, the service requests the MMAP buffer from the HAL and manages +the resources. The MMAP buffer is running in NOIRQ mode, so there are no shared +read/write counters to manage access to the buffer. Instead, the client +maintains a timing model of the hardware and predicts when the buffer will be +read. +</p> + +<p> +In the diagram below, we can see the Pulse-code modulation (PCM) data flowing +down through the MMAP FIFO into the ALSA driver. Timestamps are periodically +requested by the AAudio service and then passed up to the client's timing model +through an atomic message queue. +</p> + +<figure id="pcm-data-flow"> + <img src="/devices/audio/images/pcm_data_flow.png" + width="630" + alt="PCM data flow diagram."> + <figcaption><b>Figure 1.</b> PCM data flow through FIFO to ALSA</figcaption> +</figure> + +<p> +In SHARED mode, a timing model is also used, but it lives in the AAudioService. +</p> + +<p> +For audio capture, a similar model is used, but the PCM data flows in the +opposite direction. +</p> + +<h2 id="hal-changes">HAL changes</h2> +<p> +For tinyALSA see: +</p> + +<pre +class="prettyprint"> +external/tinyalsa/include/tinyalsa/asoundlib.h +external/tinyalsa/include/tinyalsa/pcm.c +</pre> + +<pre +class="prettyprint"> +int pcm_start(struct pcm *pcm); +int pcm_stop(struct pcm *pcm); +int pcm_mmap_begin(struct pcm *pcm, void **areas, + unsigned int *offset, + unsigned int *frames); +int pcm_get_poll_fd(struct pcm *pcm); +int pcm_mmap_commit(struct pcm *pcm, unsigned int offset, + unsigned int frames); +int pcm_mmap_get_hw_ptr(struct pcm* pcm, unsigned int *hw_ptr, + struct timespec *tstamp); +</pre> + +<p> +For the legacy HAL, see: +</p> + +<pre +class="prettyprint"> +hardware/libhardware/include/hardware/audio.h +hardware/qcom/audio/hal/audio_hw.c +</pre> + +<pre +class="prettyprint"> +int start(const struct audio_stream_out* stream); +int stop(const struct audio_stream_out* stream); +int create_mmap_buffer(const struct audio_stream_out *stream, + int32_t min_size_frames, + struct audio_mmap_buffer_info *info); +int get_mmap_position(const struct audio_stream_out *stream, + struct audio_mmap_position *position); +</pre> + +<p> +For HIDL audio HAL: +</p> + +<pre +class="prettyprint"> +hardware/interfaces/audio/2.0/IStream.hal +hardware/interfaces/audio/2.0/types.hal +hardware/interfaces/audio/2.0/default/Stream.h +</pre> + +<pre +class="prettyprint"> +start() generates (Result retval); +stop() generates (Result retval) ; +createMmapBuffer(int32_t minSizeFrames) + generates (Result retval, MmapBufferInfo info); +getMmapPosition() + generates (Result retval, MmapPosition position); +</pre> + +<h3 id="reporting-mmap-support">Reporting MMAP support</h3> + +<p> +System property "aaudio.mmap_policy" should be set to 2 (AAUDIO_POLICY_AUTO) so +the audio framework knows that MMAP mode is supported by the audio HAL. (see +"Enabling AAudio MMAP Data Path" below.) +</p> + +<p> +audio_policy_configuration.xml file must also contain an output and input +profile specific to MMAP/NO IRQ mode so that the Audio Policy Manager knows +which stream to open when MMAP clients are created: +</p> + +<pre +class="prettyprint"> +<mixPort name="mmap_no_irq_out" role="source" + flags="AUDIO_OUTPUT_FLAG_DIRECT|AUDIO_OUTPUT_FLAG_MMAP_NOIRQ"> + <profile name="" format="AUDIO_FORMAT_PCM_16_BIT" + samplingRates="48000" + channelMasks="AUDIO_CHANNEL_OUT_STEREO"/> +</mixPort> + +<mixPort name="mmap_no_irq_in" role="sink" flags="AUDIO_INPUT_FLAG_MMAP_NOIRQ"> + <profile name="" format="AUDIO_FORMAT_PCM_16_BIT" + samplingRates="48000" + channelMasks="AUDIO_CHANNEL_IN_STEREO"/> +</mixPort> +</pre> + +<h3 id="opening-and-closing-an-mmap-stream">Opening and closing an MMAP +stream</h3> + +<pre +class="prettyprint"> +createMmapBuffer(int32_t minSizeFrames) + generates (Result retval, MmapBufferInfo info); +</pre> + +<p> +The MMAP stream can be opened and closed by calling Tinyalsa functions. +</p> + +<h3 id="querying-mmap-position">Querying MMAP position</h3> + +<p> +The timestamp passed back to the Timing Model contains a frame position and a +MONOTONIC time in nanoseconds: +</p> + +<pre +class="prettyprint"> +getMmapPosition() + generates (Result retval, MmapPosition position); +</pre> + +<p> +The HAL can obtain this information from the ALSA driver by calling a new +Tinyalsa function: +</p> + +<pre +class="prettyprint"> +int pcm_mmap_get_hw_ptr(struct pcm* pcm, + unsigned int *hw_ptr, + struct timespec *tstamp); +</pre> + +<h2 id="kernel-changes">Kernel changes</h2> + +<p> +Enable MMAP/NOIRQ mode in the driver. +</p> + +<p> +The shared memory is referenced using a file descriptor that is generated by the +ALSA driver. If the file descriptor is directly associated with a +<code>/dev/snd/</code> driver file, then it can be used by the AAudio service in +SHARED mode. But the descriptor cannot be passed to the client code for +EXCLUSIVE mode. The <code>/dev/snd/</code> file descriptor would provide too +broad of access to the client, so it is blocked by SELinux. +</p> + +<p> +In order to support EXCLUSIVE mode, it is necessary to convert the +<code>/dev/snd/</code> descriptor to an <code>anon_inode:dmabuffer</code> file +descriptor. SELinux allows that file descriptor to be passed to the client. It +can also be used by the AAudioService. +</p> + +<p> +An <code>anon_inode:dmabuffer</code> file descriptor can be generated using the +Android Ion memory library. +</p> + +<p> +For additional information, see these external resources: +</p> + +<ol> +<li>"The Android ION memory allocator" <a +href="https://lwn.net/Articles/480055/">https://lwn.net/Articles/480055/</a> +<li>"Android ION overview" <a +href="https://wiki.linaro.org/BenjaminGaignard/ion">https://wiki.linaro.org/BenjaminGaignard/ion</a> +<li>"Integrating the ION memory allocator" <a +href="https://lwn.net/Articles/565469/">https://lwn.net/Articles/565469/</a></li> +</ol> + +<p> +The AAudio service needs to know if this <code>anon_inode:dmabuffer</code> is +supported. Currently, the only way to do that is to pass the size of the MMAP +buffer as a negative number, eg. -2048 instead of 2048, if supported. A better +way of reporting this without having to open the stream is planned. +</p> + +<h2 id="audio-subsystem-changes">Audio subsystem changes</h2> + +<p> +AAudio requires an additional data path at the audio front end of the audio +subsystem so it can operate in parallel with the original AudioFlinger path. +That legacy path is used for all other system sounds and application sounds. +This functionality could be provided by a software mixer in a DSP or a hardware +mixer in the SOC. +</p> + +<h2 id="enabling-aaudio-mmap-data-path">Enabling AAudio MMAP Data Path</h2> + +<p> +AAudio will use the legacy AudioFlinger data path if MMAP is not supported or +fails to open a stream. So AAudio will work with an audio device that does not +support MMAP/NOIRQ path. +</p> + +<p> +When testing MMAP support for AAudio, it is important to know whether you are +actually testing the MMAP data path or merely testing the legacy data path. The +following describes how to enable or force specific data paths, and how to query +the path used by a stream. +</p> + +<h3 id="system-properties">System properties</h3> + +<p> +You can set the MMAP policy through system properties: +</p> + +<ul> +<li>1 = AAUDIO_POLICY_NEVER - Only use legacy path. Do not even try to use MMAP. +<li>2 = AAUDIO_POLICY_AUTO - Try to use MMAP. If that fails or is not available, +then use legacy path. +<li>3 = AAUDIO_POLICY_ALWAYS - Only use MMAP path. Do not fall back to legacy +path.</li> +</ul> + +<p> +These may be set in the devices Makefile, like so: +</p> + +<pre +class="prettyprint"> +# Enable AAudio MMAP/NOIRQ data path. +# 2 is AAUDIO_POLICY_AUTO so it will try MMAP then fallback to Legacy path. +PRODUCT_PROPERTY_OVERRIDES += aaudio.mmap_policy=2 +# Allow EXCLUSIVE then fall back to SHARED. +PRODUCT_PROPERTY_OVERRIDES += aaudio.mmap_exclusive_policy=2 +</pre> + +<p> +You can also override these values after the device has booted. For example, to +enable AUTO mode for MMAP: +</p> + +<pre class="devsite-terminal devsite-click-to-copy"> +adb root +</pre> +<pre class="devsite-terminal devsite-click-to-copy"> +adb shell setprop aaudio.mmap_policy 2 +</pre> + +<p> +There are functions provided in +<code>ndk/sysroot/usr/include/aaudio/AAudioTesting.h</code> that allow you to +override the policy for using MMAP path: +</p> + +<pre +class="prettyprint">aaudio_result_t AAudio_setMMapPolicy(aaudio_policy_t policy); +</pre> + +<p> +To find out whether a stream is using MMAP path, call: +</p> + +<pre +class="prettyprint">bool AAudioStream_isMMapUsed(AAudioStream* stream); +</pre> +</body> +</html> diff --git a/en/devices/audio/images/pcm_data_flow.png b/en/devices/audio/images/pcm_data_flow.png Binary files differnew file mode 100644 index 00000000..2279e422 --- /dev/null +++ b/en/devices/audio/images/pcm_data_flow.png diff --git a/en/devices/audio/latency.html b/en/devices/audio/latency.html index 58b3024b..03dabb64 100644 --- a/en/devices/audio/latency.html +++ b/en/devices/audio/latency.html @@ -34,7 +34,8 @@ </tr> <tr> <td>Description of audio latency for purposes of Android compatibility</td> - <td><a href="/compatibility/android-cdd#5_6_audio_latency">Android CDD</a><br /><em>section 5.6 Audio Latency</em></td> + <td><a href="/compatibility/android-cdd#5_6_audio_latency">Android Compatibility Definition Document (CDD)</a><br /> + <em>section 5.6 Audio Latency</em></td> </tr> <tr> <td>Common causes of audio latency</td> @@ -60,6 +61,9 @@ <td>Applications</td> <td><a href="latency_app.html">Audio Latency for App Developers</a></td> </tr> +<tr> + <td>AAudio and MMAP</td> + <td><a href="aaudio.html">AAudio for OEMs and SoC Vendors</a></td> </table> </body> diff --git a/en/devices/audio/terminology.html b/en/devices/audio/terminology.html index 277b25e4..e691e285 100644 --- a/en/devices/audio/terminology.html +++ b/en/devices/audio/terminology.html @@ -94,7 +94,7 @@ Both PCM and DSD represent multiple channels by independent sequences. DSD is better suited to content distribution than as an internal representation for processing as it can be difficult to apply traditional digital signal processing (DSP) algorithms to DSD. DSD is used in <a href="http://en.wikipedia.org/wiki/Super_Audio_CD">Super Audio CD (SACD)</a> and in DSD over PCM (DoP) for USB. For details, refer -to <a href="http://en.wikipedia.org/wiki/Direct_Stream_Digital">Digital Stream +to <a href="http://en.wikipedia.org/wiki/Direct_Stream_Digital">Direct Stream Digital</a>. </dd> diff --git a/en/devices/graphics/arch-sh.html b/en/devices/graphics/arch-sh.html index 3b597abb..d581234e 100644 --- a/en/devices/graphics/arch-sh.html +++ b/en/devices/graphics/arch-sh.html @@ -83,8 +83,8 @@ will be handled by SurfaceFlinger or HWC; but since we need to only read from it, there's no need to wait for exclusive access.</p> <p>The main non-Canvas way for an application to draw directly on a Surface is -through OpenGL ES. That's described in the <a href="#eglsurface">EGLSurface and -OpenGL ES</a> section.</p> +through OpenGL ES (as described in the <a href="/devices/graphics/arch-egl-opengl">EGLSurface +and OpenGL ES</a> section).</p> <h2 id="surfaceholder">SurfaceHolder</h2> diff --git a/en/devices/graphics/renderer.html b/en/devices/graphics/renderer.html index 7ee28f10..fe0a0e79 100644 --- a/en/devices/graphics/renderer.html +++ b/en/devices/graphics/renderer.html @@ -25,6 +25,10 @@ <p>This document describes performance tuning that you can do to get the most out of your hardware.</p> +<p class="note"><strong>Note:</strong> In Android 8.1 and later, only the +<code>ro.zygote.disable_gl_preload</code> property still applies. All other +properties have been removed.</p> + <h2>OpenGLRenderer (libhwui) Properties</h2> <p>This document lists all the properties that you can use to control Android’s 2D hardware accelerated rendering pipeline. Set these properties diff --git a/en/devices/tech/config/images/tz_call_rulesmanagerservice.png b/en/devices/tech/config/images/tz_call_rulesmanagerservice.png Binary files differnew file mode 100644 index 00000000..65a1b2a9 --- /dev/null +++ b/en/devices/tech/config/images/tz_call_rulesmanagerservice.png diff --git a/en/devices/tech/config/images/tz_check_complete.png b/en/devices/tech/config/images/tz_check_complete.png Binary files differnew file mode 100644 index 00000000..efc8876a --- /dev/null +++ b/en/devices/tech/config/images/tz_check_complete.png diff --git a/en/devices/tech/config/images/tz_data_app_updates.png b/en/devices/tech/config/images/tz_data_app_updates.png Binary files differnew file mode 100644 index 00000000..108e4ec1 --- /dev/null +++ b/en/devices/tech/config/images/tz_data_app_updates.png diff --git a/en/devices/tech/config/images/tz_get_info_distro.png b/en/devices/tech/config/images/tz_get_info_distro.png Binary files differnew file mode 100644 index 00000000..70498a42 --- /dev/null +++ b/en/devices/tech/config/images/tz_get_info_distro.png diff --git a/en/devices/tech/config/images/tz_trigger_update.png b/en/devices/tech/config/images/tz_trigger_update.png Binary files differnew file mode 100644 index 00000000..cb9cb0a5 --- /dev/null +++ b/en/devices/tech/config/images/tz_trigger_update.png diff --git a/en/devices/tech/config/images/tz_version_check.png b/en/devices/tech/config/images/tz_version_check.png Binary files differnew file mode 100644 index 00000000..dd26a30e --- /dev/null +++ b/en/devices/tech/config/images/tz_version_check.png diff --git a/en/devices/tech/config/timezone-rules.html b/en/devices/tech/config/timezone-rules.html new file mode 100644 index 00000000..6a3f81ef --- /dev/null +++ b/en/devices/tech/config/timezone-rules.html @@ -0,0 +1,724 @@ +<html devsite> + <head> + <title>Time Zone Rules</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 8.1 provides a new mechanism for OEMs to push updated time zone rules +data to devices without requiring a system update. This mechanism enables users +to receive timely updates (thus extending the useful lifetime of an Android +device) and enables OEMs to test time zone updates independently of system image +updates.</p> + +<p>The Android core libraries team will provide the necessary data files for +updating time zone rules on a stock Android device. OEMs can choose to use these +data files when creating time zone updates for their devices or can create their +own data files if preferred. In all cases, OEMs retain control over the quality +assurance/testing, timing, and launch of time zone rule updates for their +supported devices.</p> + +<h2 id="source-code">Android time zone source code and data</h2> +<p>All stock Android devices, even those not using this feature, need time zone +rules data and must ship with a default set of time zone rules data in the +<code>/system</code> partition. This data is then used by code from the +following libraries in the Android source tree: </p> + +<ul> +<li>Managed code from <code>libcore/</code> (e.g. +<code>java.util.TimeZone</code>) uses <code>tzdata</code> and +<code>tzlookup.xml</code> files.</li> +<li>Native library code in <code>bionic/</code> (e.g. for <code>mktime</code>, +localtime system calls) uses the <code>tzdata</code> file.</li> +<li>ICU4J/ICU4C library code in <code>external/icu/</code> uses the icu .dat +file.</li> +</ul> + +<p>These libraries are configured to be aware of overlay files that may be +present in the <code>/data/misc/zoneinfo/current</code> directory. Overlay files +are expected to contain improved time zone rules data thereby enabling devices +to be updated without changing <code>/system</code>.</p> + +<p>Android system components that need time zone rule data check the following +locations first:</p> + +<ul> +<li><code>libcore/</code> and <code>bionic/</code> code use the +<code>/data</code> copy of the <code>tzdata</code> and <code>tzlookup.xml</code> +files.</li> +<li>ICU4J/ICU4C code use the files in <code>/data</code> and fallback to +<code>/system</code> files for data that isn't present (for formats, localized +strings, etc.).</li> +</ul> + +<h2 id="distro-files">Distro files</h2> +<p>Distro .zip files contain the data files needed to populate the +<code>/data/misc/zoneinfo/current</code> directory. The distro file also +contains metadata that allows devices to detect versioning issues.</p> +<p>The distro file format is Android-release dependent because the contents +change with the ICU version, Android platform requirements, +etc. Android provides distro files for supported Android releases for every IANA +update (in addition to updating the platform system files). To keep their +devices up to date, OEMs can choose to take this distro file or create their own +distro file using the Android source tree (which contains the scripts and other +files needed to generate distro files).</p> + +<h2>Time zone update components</h2> +<p>A time zone rules update involves the transmission of a distro file to a +device and the safe installation of the files contained within. Transfer and +installation requires the following:</p> + +<ul> +<li>Platform service functionality +(<a href="https://android.googlesource.com/platform/frameworks/base/+/master/services/core/java/com/android/server/timezone/RulesManagerService.java">timezone.RulesManagerService</a>), +which is disabled by default. OEMs must enable the functionality via +configuration. The RulesManagerService runs in the system server process and +stages time zone update operations by writing to +<code>/data/misc/zoneinfo/staged</code>. It can also replace or delete already +staged operations.</li> +<li> +<a href="https://android.googlesource.com/platform/packages/apps/TimeZoneUpdater/">Time +Zone Updater</a>, a non-updateable system application (aka the <em>Updater +App</em>). OEMs must include this application in the system image of devices +using the feature.</li> +<li>OEM +<a href="https://android.googlesource.com/platform/packages/apps/TimeZoneData/">Time +Zone Data</a>, an updateable system application (aka the <em>Data App</em>) +that carries the distro file to the device and makes it available to the Updater +App. OEMs must include this application in the system image of devices using the +feature.</li> +<li> +<a href="https://android.googlesource.com/platform/system/timezone/+/master/tzdatacheck/">tzdatacheck</a>, +a boot-time binary required for the correct and safe operation of time zone +updates.</li> +</ul> + +<p>The Android source tree contains generic source code for the above +components, which the OEM can choose to use without modification. +<a href="https://android.googlesource.com/platform/packages/apps/TimeZoneData/+/master/testing/">Test +code</a> is provided to enable OEMs to automatically check that they have +enabled the feature correctly.</p> + +<h3 id="distro-install">Distro installation</h3> +<p>The distro installation process includes the following steps:</p> + +<ol> +<li><strong>Data App is updated</strong> via an app store download or +sideload. The system server process (via +<code>timezone.RulesManagerServer/timezone.PackageTracker</code> classes) +watches for changes to the configured, OEM-specific, Data App package +name. +<figure> +<img src="images/tz_data_app_updates.png" alt="Data app updates" +id="data-app-updates" /> +<figcaption><strong>Figure 1.</strong> Data App updates.</figcaption></figure> +</li> +<li><strong>System server process triggers an update check</strong> by +broadcasting a targeted intent with a unique, single-use token to the Updater +App. The system server keeps track of the most recent token it generated so it +can later tell when the most recent check it triggered has completed; any other +tokens are ignored. +<figure> +<img src="images/tz_trigger_update.png" alt="Trigger update" +id="trigger-update" /> +<figcaption><strong>Figure 2.</strong> Trigger update check.</figcaption> +</figure> +</li> +<li><strong>Update check</strong>, in which the Updater App performs the +following tasks: +<ul> +<li>Queries the current device state by calling the RulesManagerService. +<figure> +<img src="images/tz_call_rulesmanagerservice.png" alt="Call RulesManagerService" +id="call-rulesmanagerservice" /> +<figcaption><strong>Figure 3.</strong> Data App updates, calling +RulesManagerService.</figcaption></figure> +</li> +<li>Queries the Data App by querying a well-defined ContentProvider URL and +column specs to get information about the distro: +<figure> +<img src="images/tz_get_info_distro.png" alt="Get distro information" +id="get-distro-info" /> +<figcaption><strong>Figure 4.</strong> Data App updates, get info about distro. +</figcaption></figure> +</li> +</ul> +<li><strong>Updater App takes the appropriate action</strong> based on the +information it has. Available actions include: +<ul> +<li><em>Request an installation</em>. Distro data is read from the Data App +and is passed to the RulesManagerService in the system server. The +RulesManagerService re-confirms the distro format version and content is +appropriate for the device and stages the install.</li> +<li><em>Request an uninstall</em> (this is rare). For example, if the updated +.apk in <code>/data</code> is being disabled or uninstalled and the device is +returning to the version present in <code>/system</code>.</li> +<li><em>Do nothing</em>. Occurs when the Data App distro is found to be invalid. +</li> +</ul> +In all cases, the Updated App calls the RulesManagerService with the check token +so the system server knows the check is complete and successful. +<figure> +<img src="images/tz_check_complete.png" alt="Check complete" +id="check-complete" /> +<figcaption><strong>Figure 5.</strong> Check complete.</figcaption></figure> +</li> +<li><strong>Reboot and tzdatacheck</strong>. When the device next boots, +the tzdatacheck binary executes any staged operation. The tzdatacheck binary can +perform the following tasks: +<ul> +<li>Execute the staged operation by handling the creation, replacement, +and/or deletion of the <code>/data/misc/zoneinfo/current</code> files before +other system components have opened and started to use the files.</li> +<li>Check the files in <code>/data</code> are correct for the current platform +version, which might not be the case if the device has just received a system update +and the distro format version has changed.</li> +<li>Ensure the IANA rules version is the same or newer than the version in +<code>/system</code>. This protects against a system update leaving a device +with older time zone rules data than is present in the <code>/system</code> +image. +</li> +</ul> +</li> +</ol> + +<h3 id="reliability">Reliability</h3> +<p>The end-to-end installation process is asynchronous and split across three OS +processes. At any point during the installation, the device may lose power, run +out of disk space, etc., causing the installation check to not complete +successfully. In the best unsuccessful case, the Updater App is able to inform +the system server it was unsuccessful; in the worst unsuccessful case, the +RulesManagerService receives no call at all.</p> +<p>To handle this, the system server code keeps track of whether a triggered +update check has completed and what the last checked version code of the Data +App is. When the device is idle and charging, the system server code can check +the current state. If it discovers an incomplete update check or unexpected Data +App version, it spontaneously triggers an update check.</p> + +<h3 id="security">Security</h3> +<p>When enabled, the RulesManagerService code in the system server performs +several checks to ensure the system is safe to use.</p> +<ul> +<li>Problems that indicate a badly configured system image will prevent a +device booting; examples include a bad Updater or Data App configuration or the +Updater or Data App not being in <code>/system/priv-app</code>.</li> +<li>Problems that indicate a bad Data App has been installed will not prevent a +device booting but will prevent an update check being triggered; examples +include a lack of required system permissions or the Data App doesn't expose a +ContentProvider on the expected URI.</li> +</ul> + +<p>File permissions for the <code>/data/misc/zoneinfo</code> directories are +enforced via SELinux rules. As with any APK, the Data App must be signed by the +same key used to sign the <code>/system/priv-app</code> version. The Data App is +expected to have a dedicated, OEM-specific package name and key.</p> + +<h2 id="integrating">Integrating time zone updates</h2> +<p>To enable the time zone update feature, OEMs typically:</p> +<ul> +<li>Create their own Data App.</li> +<li>Include the Updater and Data Apps in the system image build.</li> +<li>Configure the system server to enable the RulesManagerService.</li> +</ul> + +<h3 id="preparing">Preparing</h3> +<p>Before starting, review the following policy, quality assurance, and security +considerations:</p> +<ul> +<li>OEMs should create a dedicated app-specific signing key for their Data +App.</li> +<li>OEMs should create a release and versioning strategy for time zone updates +to understand which devices are going to be updated and how they will ensure +updates are only installed on devices that need them. For example, OEMs may want +to have a single Data App for all their devices or may choose to have different +Data Apps for different devices. The decision impacts the choice of package +name, possibly the version codes used, and the QA strategy.</li> +<li>OEMs should understand whether they want to use stock Android timezone data +from AOSP or create their own.</li> +</ul> + +<h3 id="creating-data-app">Creating a Data App</h3> +<p>AOSP includes all source code and build rules needed to create a Data App in +<code>packages/apps/TimeZoneData</code>, with instructions and example templates +for <code>AndroidManifest.xml</code> and other files located in +<code>packages/apps/TimeZoneData/oem_template</code>. Example templates include +both a build target for the real Data App .apk file and extra targets for +creating test versions of the Data App.</p> +<p>OEMs can customize the Data App with their own icon, name, translations, +etc. However, as the Data App cannot be launched, the icon appears only in the +<em>Settings > Apps</em> screen.</p> +<p>The Data App is intended to be built with a <strong>tapas</strong> build +that produces .apks suitable to be added to the system image (for the initial +release) and signed and distributed via an app store (for subsequent updates). +For details on using tapas, see <a href="#building-tapas">Building the Data app +using tapas</a>.</p> + +<aside class="note"><strong>Note:</strong> Securely signing APKs and key +management is outside of the scope of this article.</aside> + +<p>OEMs must install the Data App prebuilt in the system image of a device in +<code>/system/priv-app</code>. To include prebuilt .apks (generated by the tapas +build process) in the system image, OEMs can copy the example files in +<code>packages/apps/TimeZoneData/oem_template/data_app_prebuilt</code>. The +example templates also include build targets for including test versions of the +Data App in test suites.</p> + +<h3 id="including">Including the Updater and Data Apps in the system image</h3> +<p>OEMs must place the Updater and Data App .apk files in the +<code>/system/priv-app</code> directory of the system image. To do this, the +system image build must explicitly include the Updater App and Data App prebuilt +targets.</p> +<p>The Updater App should be signed with the platform key and included as any +other system app. The target is defined in +<code>packages/apps/TimeZoneUpdater</code> as <code>TimeZoneUpdater</code>. The +Data App inclusion is OEM-specific and depends on the target name chosen for the +prebuild.</p> + +<h3 id="configuring-system-server">Configuring the system server</h3> +<p>To enable time zone updates, OEMs can configure the system server by +overriding configuration properties defined in +<code>frameworks/base/core/res/res/values/config.xml</code>.</p> + +<table> +<thead> +<tr> +<th>Property</th> +<th width="20%">Override Required?</th> +</tr> +</thead> +<tbody> +<tr> +<td> +<pre class="prettyprint">config_enableUpdateableTimeZoneRules</pre> +Must be set to true to enable the RulesManagerService.</td> +<td>Yes</td> +</tr> +<tr> +<td><pre class="prettyprint">config_timeZoneRulesUpdateTrackingEnabled</pre> +Must be set to true to have the system listen for changes to the Data App.</td> +<td>Yes</td> +</tr> +<tr> +<td><pre class="prettyprint">config_timeZoneRulesDataPackage</pre> +Package name of the OEM-specific Data App.</td> +<td>Yes</td> +</tr> +<tr> +<td><pre class="prettyprint">config_timeZoneRulesUpdaterPackage</pre> +Configured for the default Updater App. Change only when providing a different +Updater App implementation.</td> +<td>No</td> +</tr> +<tr> +<td><pre class="prettyprint">config_timeZoneRulesCheckTimeMillisAllowed</pre> +Time allowed between an update check being triggered by the RulesManagerService +and an install, uninstall, or do nothing response. After this point, a +spontaneous reliability trigger may be generated.</td> +<td>No</td> +</tr> +<tr> +<td><pre class="prettyprint">config_timeZoneRulesCheckRetryCount</pre> +The number of sequential unsuccessful update checks allowed before the +RulesManagerService stops generating more.</td> +<td>No</td> +</tr> +</tbody> +</table> + +<p>Configuration overrides should be in the system image (not vendor or other) +as a misconfigured device can refuse to boot. If the configuration overrides +were in <code>/vendor</code>, updating to a system image without a Data App (or +with different Data App/Updater App package names) would be considered a +misconfiguration.</p> + +<h3 id="xts-testing">xTS testing</h3> +<p>xTS refers to any OEM-specific test suite that is similar to standard Android +test suites using Tradefed (such as CTS and VTS). OEMs that have such test +suites can add the Android time zone update tests provided in the following +locations:</p> + +<ul> +<li><code>packages/apps/TimeZoneData/testing/xts</code>. Includes the code +needed for basic automated functional testing.</li> +<li><code>packages/apps/TimeZoneData/oem_template/xts</code>. Contains a sample +directory structure for including tests in a Tradefed-like xTS suite. As with +other template directories, OEMs are expected to copy and customize to their +needs.</li> +<li><code>packages/apps/TimeZoneData/oem_template/data_app_prebuilt</code>. +Contains build-time configuration for including the pre-built test .apk files +required by the test.</li> +</ul> + +<aside class="note"><strong>Note:</strong> Setting up an OEM-specific test suite +is outside of the scope of this article.</aside> + +<h2 id="creating-updates">Creating time zone updates</h2> +<p>When IANA releases a new set of time zone rules, the Android core libraries +team generates patches to update releases in AOSP. OEMs using the stock Android +system and distro files can pick up these commits, use them to create a new +version of their Data App, then release the new version to update their devices +in production.</p> + +<aside class="note"><strong>Note:</strong> The following steps do not describe +how to update the base data files in the <code>/system</code> image, which is +required when preparing the factory image or system updates. That process also +generates the distro file for inclusion in the Data app. For instructions on +updating the platform files, refer to +<code>/system/timezone/README.android</code>.</aside> + +<p>Because Data Apps contain distro files closely tied to Android versions, +OEMs must create a new version of the Data App for <em>every</em> supported +Android release an OEM wants to update. For example, if an OEM wants to provide +updates for O-MR1, P, and Q devices, they must complete the process three +times.</p> + +<h3 id="step1">Step 1: Updating system/timezone and external/icu data files</h3> +<p>In this step, OEMs take stock Android commits for +<code>system/timezone</code> and <code>external/icu</code> from the +<em>release</em>-dev branches in AOSP and apply those commits to their copy of +the Android source code.</p> +<p>The system/timezone AOSP patch contains updated files in +<code>system/timezone/input_data</code> and +<code>system/timezone/output_data</code>. OEMs who need to make additional local +fixes can modify the input files then use the files in +<code>system/timezone/input_data</code> and <code>external/icu</code> to +generate files in <code>output_data</code>.</p> +<p>The most important file is +<code>system/timezone/output_data/distro/distro.zip</code>, which is +automatically included when the Data App .apk is built.</p> + +<h3 id="step2">Step 2: Updating the version code of the Data App</h3> +<p>In this step, OEMs update the version code of the Data App. The build +automatically picks up the <code>distro.zip</code>, but the new version of the +Data App must have a new version code so it is recognized as new and is used to +replace a pre-loaded Data App or a Data App installed on a device by a previous +update.</p> +<p>When building the Data App using files copied from +<code>package/apps/TimeZoneData/oem_template/data_app</code>, you can find the +version code/version name applied to the .apk in the <code>Android.mk</code>: +</p> + +<pre class="prettyprint"> +TIME_ZONE_DATA_APP_VERSION_CODE := +TIME_ZONE_DATA_APP_VERSION_NAME := +</pre> + +<p>Similar entries can be found in <code>testing/Android.mk</code> (however, the +test version codes must be higher than the system image version). For details, +see the <a href="#example-version-code-strategy">example version code strategy +scheme</a>; if the example scheme or a similar scheme is used, the test +version codes do not need to be updated because they are guaranteed to be higher +than the real version codes.</p> + +<h3 id="step3">Step 3: Rebuild, sign, test, and release</h3> +<p>In this step, OEMs rebuild the .apk files using tapas, sign the generated +.apk files, then test and release the .apks:</p> +<ul> +<li>For unreleased devices (or when preparing a system update for a +released device), submit the new .apk files in the Data App prebuilt directory +to ensure the system image and xTS tests have the latest .apks. OEMs should test +the new file works correctly (i.e. it passes CTS and any OEM-specific automated +and manual tests).</li> +<li>For released devices that no longer receive system updates, the signed .apk +might only be released via an app store.</li> +</ul> +<p>OEMs are entirely responsible for quality assurance and testing the updated +Data App on their devices before release.</p> + +<h2 id="version-code-strategy">Data App version code strategy</h2> +<p>The Data App must have a +<a href="https://developer.android.com/google/play/publishing/multiple-apks.html#VersionCodes">suitable +versioning strategy</a> to ensure that devices receive the correct .apk +files. For example, if a system update is received that contains an older .apk +than one downloaded from the app store, the app store version should be +retained.</p> +<p>The .apk version code should include the following information:</p> +<ul> +<li>Distro format version (major + minor)</li> +<li>An incrementing (opaque) version number</li> +</ul> +<p>Currently, platform API level is strongly correlated to distro format version +because each API level is usually associated with a new version of ICU (which +makes the distro files incompatible). In the future, Android may change this so +that a distro file can work across multiple Android platform releases (and API +level is not used in the Data App version code scheme).</p> + +<h3 id="example-version-code-strategy">Example version code strategy</h3> +<p>This example versioning number scheme ensures that higher distro format +versions beat lower distro format versions. The <code>AndroidManifest.xml</code> +uses <code>android:minSdkVersion</code> to ensure old devices don't receive +versions with a higher distro format version than they can handle.</p> + +<figure> +<img src="images/tz_version_check.png" alt="Version check" +id="version-check" /> +<figcaption><strong>Figure 6.</strong> Example version code strategy. +</figcaption></figure> + +<table> +<thead> +<tr> +<th>Example</th> +<th width="20%">Value</th> +<th>Purpose</th> +</tr> +</thead> +<tbody> +<tr> +<td><strong>Y</strong></td> +<td>Reserved</td> +<td>Allows for future alternative schemes and/or test APKs. It will initially +be (implicitly) 0. Because the underlying type is a signed 32-bit int type, +this scheme supports up to two future numbering scheme revisions.</td> +</tr> +<tr> +<td><strong>01</strong></td> +<td>Major format version</td> +<td>Tracks the 3 decimal digit major format version. The distro format supports +3 decimal digits but only 2 digits are used here. It is unlikely 100 will +be reached given the expected major increment per API level. Major version +1 == API level 27.</td> +</tr> +<tr> +<td><strong>1</strong></td> +<td>Minor format version</td> +<td>Tracks the 3 decimal digit minor format version. The distro format supports +3 decimal digits but only 1 digit is used here. It is unlikely 10 will be +reached.</td> +</tr> +<tr> +<td><strong>X</strong></td> +<td>Reserved</td> +<td>Is 0 for production releases (and may be different for test APKs).</td> +</tr> +<tr> +<td><strong>ZZZZZ</strong></td> +<td>Opaque version number</td> +<td>Decimal number allocated on demand. Includes gaps to allow interstitial +updates to be made if required.</td> +</tr> +</tbody> +</table> + +<p>The scheme could be packed better if binary were used instead of decimal, but +this scheme has the advantage of being human-readable. If the full number range +is exhausted, future releases could change the Data App package name and start +again.</p> + +<p>Version name will be a human-readable representation of the details, e.g.: +<code>major=001,minor=001,iana=2017a, revision=1,respin=2</code>. Examples:</p> + +<table> +<thead> +<tr> +<th>#</th> +<th>Version code</th> +<th>minSdkVersion</th> +<th>{Major format version}.{Minor format version}.{IANA rules +version}.{Revision}</th> +</tr> +</thead> +<tbody> +<tr> +<td>1</td> +<td>11000010</td> +<td>O-MR1</td> +<td>major=001,minor=001,iana=2017a,revision=1</td> +</tr> +<tr> +<td>2</td> +<td>21000010</td> +<td>P</td> +<td>major=002,minor=001,iana=2017a,revision=1</td> +</tr> +<tr> +<td>3</td> +<td>11000020</td> +<td>O-MR1</td> +<td>major=001,minor=001,iana=2017a,revision=2</td> +</tr> +<tr> +<td>4</td> +<td>11000030</td> +<td>O-MR1</td> +<td>major=001,minor=001,iana=2017b,revision=1</td> +</tr> +<tr> +<td>5</td> +<td>21000020</td> +<td>P</td> +<td>major=002,minor=001,iana=2017b,revision=1</td> +</tr> +<tr> +<td>6</td> +<td>11000040</td> +<td>O-MR1</td> +<td>major=001,minor=001,iana=2018a,revision=1</td> +</tr> +<tr> +<td>7</td> +<td>21000030</td> +<td>P</td> +<td>major=002,minor=001,iana=2018a,revision=1</td> +</tr> +<tr> +<td>8</td> +<td>1123456789</td> +<td>-</td> +<td>-</td> +</tr> +<tr> +<td>9</td> +<td>11000021</td> +<td>O-MR1</td> +<td>major=001,minor=001,iana=2017a,revision=2,respin=2</td> +</tr> +</tbody> +</table> + +<ul> +<li>Examples 1 and 2 show two .apk versions for the same 2017a IANA release +with different major format versions. 2 is numerically higher than 1, which is +needed to ensure that newer devices receive the higher format versions. The +minSdkVersion ensures the P version will not be supplied to O devices.</li> +<li>Example 3 is an example revision/fix for 1 and is numerically higher than 1. +</li> +<li>Examples 4 and 5 show the 2017b releases for O-MR1 and P. Being numerically +higher, they replace prior IANA releases/Android revisions of their respective +predecessors.</li> +<li>Examples 6 and 7 show the 2018a releases for O-MR1 and P.</li> +<li>Example 8 demonstrates the use of Y to completely replace the Y=0 scheme. +</li> +<li>Example 9 demonstrates the use of the gap left between 3 and 4 to re-spin +the apk.</li> +</ul> + +<p>As each device will ship with a default, appropriately versioned .apk in the +system image, there is no risk of an O-MR1 version being installed on a P device +because it will have a lower version number than a P system image version. A +device with an O-MR1 version installed in <code>/data</code> that then receives +a system update to P will use the <code>/system</code> version in preference to +the O-MR1 version in<code> /data</code> because the P version will always be +higher than any app intended for O-MR1.</p> + +<h2 id="building-tapas">Building the Data App using tapas</h2> +<p>OEMs are responsible for managing most aspects of the time zone Data App and +configuring the system image correctly. The Data App is intended to be built +with a <strong>tapas</strong> build that produces .apks suitable to be added to +the system image (for the initial release) and signed and distributed via an app +store (for subsequent updates).<p> +<p><strong>Tapas</strong> is a slimmed-down version of the Android build +system that uses a reduced source tree to produce distributable versions of +apps. OEMs familiar with the normal Android build system will recognize the +build files from the normal Android platform build.</p> + +<h3 id="creating-manifest">Creating the manifest</h3> +<p>A reduced source tree is usually achieved with a custom manifest file that +refers only to the Git projects needed by the build system and for building the +app. After following the instructions in +<a href="#creating-data-app">Creating a Data App</a>, OEMs should have at +least two OEM-specific git projects created by using the template files under +<code>packages/apps/TimeZoneData/oem_template</code>:</p> + +<ul> +<li>One git project contains application files such as the manifest and the +build files required to create the application .apk file (e.g. +<code>vendor/<em>oem</em>/apps/TimeZoneData</code>). This project also contains +build rules for test APKs that can be used by xTS tests.</li> +<li>One git project contains the signed .apk files produced by the app build for +inclusion in the system image build and xTS tests.</li> +</ul> + +<p>The app build leverages several other git projects that are shared with the +platform build or contain OEM-independent code libraries.</p> +<p>The following manifest snippet contains the minimal set of git projects +needed to support an O-MR1 build of the time zone Data App (future versions of +Android will have different lists or may even change the build system). OEMs +must add their OEM-specific git projects (which typically include a project that +contains the signing certificate) to this manifest, and may configure different +branches accordingly.</p> + +<pre class="prettyprint"> + <!-- Tapas Build --> + <project + path="build" + name="platform/build"> + <copyfile src="core/root.mk" dest="Makefile" /> + </project> + <project + path="prebuilts/build-tools" + name="platform/prebuilts/build-tools" + clone-depth="1" /> + <project + path="prebuilts/go/linux-x86" + name="platform/prebuilts/go/linux-x86" + clone-depth="1" /> + <project + path="build/blueprint" + name="platform/build/blueprint" /> + <project + path="build/kati" + name="platform/build/kati" /> + <project + path="build/soong" + name="platform/build/soong"> + <linkfile src="root.bp" dest="Android.bp" /> + <linkfile src="bootstrap.bash" dest="bootstrap.bash" /> + </project> + + <!-- SDK for system / public API stubs --> + <project + path="prebuilts/sdk" + name="platform/prebuilts/sdk" + clone-depth="1" /> + <!-- App source --> + <project + path="system/timezone" + name="platform/system/timezone" /> + <project + path="packages/apps/TimeZoneData" + name="platform/packages/apps/TimeZoneData" /> + <!-- Enable repohooks --> + <project + path="tools/repohooks" + name="platform/tools/repohooks" + revision="master" + clone_depth="1" /> + <repo-hooks + in-project="platform/tools/repohooks" + enabled-list="pre-upload" /> +</pre> + +<h3 id="running-tapas">Running the tapas build</h3> +<p>After the source tree is established, invoke the <strong>tapas</strong> build +using the following commands:</p> + +<pre class="devsite-click-to-copy"> +<code class="devsite-terminal">source build/envsetup.sh</code> +<code class="devsite-terminal">tapas</code> +<code class="devsite-terminal">make -j30 showcommands dist TARGET_BUILD_APPS='TimeZoneData TimeZoneData_test1 TimeZoneData_test2' TARGET_BUILD_VARIANT=userdebug</code> +</pre> + +<p>A successful build generates files in the <code>out/dist</code> directory for +testing. These files can be placed into the prebuilts directory for inclusion in +the system image and/or distributed via an app store for compatible +devices.</p> + +</body> +</html> diff --git a/en/devices/tech/connect/wifi-aware.html b/en/devices/tech/connect/wifi-aware.html new file mode 100644 index 00000000..7244abb2 --- /dev/null +++ b/en/devices/tech/connect/wifi-aware.html @@ -0,0 +1,122 @@ +<html devsite> + <head> + <title>Wi-Fi Aware</title> + <meta name="project_path" value="/_project.yaml" /> + <meta name="book_path" value="/_book.yaml" /> + </head> + <body> + <!-- + Copyright 2017 The Android Open Source Project + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + --> + + + +<p> +The <a +href="https://developer.android.com/guide/topics/connectivity/wifi-aware.html">Wi-Fi +Aware</a> feature in the Android 8.1 (O MR1) release enables supporting devices to +connect to one another directly over Wi-Fi without internet or cellular network +access. This feature, built upon the <a href="https://www.wi-fi.org/">Wi-Fi +Alliance</a> <a href="https://www.wi-fi.org/discover-wi-fi/wi-fi-aware">Wi-Fi +Aware specification</a> (version 2.0), allows easy sharing of high-throughput +data among trusted devices and apps that are otherwise off network. +</p> + +<h2 id="examples-and-source">Examples and source</h2> + +<p> +To use this feature, device manufacturers should implement the Wi-Fi Hardware +Interface Design Language (HIDL) provided in the Android Open Source Project +(AOSP). In the Android 8.0 (O) release, HIDL replaces the previous Hardware +Abstraction Layer (HAL) structure used in order to streamline implementations by +specifying types and method calls collected into interfaces and packages. +</p> + +<p> +Follow the Wi-Fi HIDL to employ the Wi-Fi aware feature: +hardware/interfaces/wifi/1.0. The Wi-Fi Aware HAL surface is very large; the +<a href + ="https://android.googlesource.com/platform/hardware/interfaces/+/master/wifi/1.0/README-NAN.md">hardware/interfaces/wifi/1.0/README-NAN.md</a> +file describes the subset which is currently in use. +</p> + +<p> +You may reference the legacy Wi-Fi HAL to see how it correlates with the new +HIDL interface: +<a +href="https://android.googlesource.com/platform/hardware/libhardware_legacy/+/master/include/hardware_legacy/wifi_nan.h">hardware/libhardware_legacy/+/master/include/hardware_legacy/wifi_nan.h</a>. +</p> + +<h2 id="implementation">Implementation</h2> + +<p> +Device manufacturers need to provide both framework and HAL/firmware support: +</p> +<ul> + <li>Framework: + <ul> + <li>AOSP code</li> + <li>Enable Aware: requires both a feature flag and an HIDL build flag</li> + </ul> + <li>Wi-Fi Aware (NAN) HAL support (which implies firmware support)</li> + </li> +</ul> + +<p> +To implement this feature, device manufacturers implement the Wi-Fi HIDL and +also enable two feature flags: +</p> + +<p> +In <code>BoardConfig.mk</code>, add this flag to tell the Wi-Fi HIDL to include +the Wi-Fi Aware feature: +<code>WIFI_HIDL_FEATURE_AWARE := true</code> +</p> + +<p> +And in <code>device.mk</code>, modify the <code>PRODUCT_COPY_FILES</code> +environment variable to include support for the Wi-Fi Aware feature: +<code>PRODUCT_COPY_FILES += +frameworks/native/data/etc/android.hardware.wifi.aware.xml:system/etc/permissions/android.hardware.wifi.aware.xml</code> +</p> + +<p> +Otherwise, everything required for this feature is included in AOSP. +</p> + +<h2 id="validation">Validation</h2> + +<p> +Android Compatibility Test Suite (CTS) tests exist for this feature. CTS detects +when the feature is enabled and automatically includes the associated tests. +</p> + +<p> +This feature can also be tested using the <a +href="/devices/tech/test_infra/tradefed/fundamentals/vts">Vendor +Test Suite (VTS)</a> and <a +href="https://android.googlesource.com/platform/tools/test/connectivity/+/master/acts/tests/google/wifi/">acts/sl4a</a>, +a test suite that conducts extensive integration testing. +</p> + +<p> +The acts/sl4a test suite, described in +<a +href="https://android.googlesource.com/platform/tools/test/connectivity/+/master/acts/tests/google/wifi/aware/README.md">tools/test/connectivity/acts/tests/google/wifi/aware/README.md</a>, +provides functional, performance, and stress tests. +</p> + +</body> +</html> diff --git a/en/devices/tech/dalvik/configure.html b/en/devices/tech/dalvik/configure.html index 6a5fa86e..4809c2fe 100644 --- a/en/devices/tech/dalvik/configure.html +++ b/en/devices/tech/dalvik/configure.html @@ -129,10 +129,10 @@ pre-optimization of prebuilt apps that are likely to be updated via Google Play saves <code>/system</code> space but does add to first boot time. </p> -<li><code>WITH_DEXPREOPT_BOOT_IMG_ONLY</code></li> +<li><code>WITH_DEXPREOPT_BOOT_IMG_AND_SYSTEM_SERVER_ONLY</code> (new in Android O MR1)</li> -<p>Enabling <code>WITH_DEXPREOPT_BOOT_IMG_ONLY</code> pre-optimizes only the -boot classpath. +<p>Enabling <code>WITH_DEXPREOPT_BOOT_IMG_AND_SYSTEM_SERVER_ONLY</code> pre-optimizes only the +boot classpath and system server jars.</p> <li><code>LOCAL_DEX_PREOPT</code></li> @@ -212,6 +212,12 @@ should enable PIC compilation.</p> <p>In Android 7.0, PIC compilation was enabled by default.</p> +<li><code>WITH_DEXPREOPT_BOOT_IMG_ONLY</code> (removed in Android O MR1)</li> +<p> +This option was replaced with WITH_DEXPREOPT_BOOT_IMG_AND_SYSTEM_SERVER_ONLY +that also preopts the system server jars. +</p> + </ul> diff --git a/en/devices/tech/display/color-mgmt.html b/en/devices/tech/display/color-mgmt.html new file mode 100644 index 00000000..d73f091d --- /dev/null +++ b/en/devices/tech/display/color-mgmt.html @@ -0,0 +1,149 @@ +<html devsite> + <head> + <title>Color Management</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 8.1 adds support for color management that can be used to provide a +consistent experience across display technologies. Applications running on +Android 8.1 can access the full capabilities of a wide gamut display to get the +most out of a display device.</p> + +<p>Previous Android releases did not include color management support and +instead relied on content and displays being compatible (a goal often aided by +the TV industry). However, recent display technologies allow for much larger +gamut displays that do not display existing content as expected. With Android +8.1, devices that use a wide-gamut display (e.g. active-matrix organic +light-emitting diode or AMOLED, some LCDs) will be able to see wide-gamut +content from applications.</p> + +<h2>Determining device support</h2> +<p>Devices with wide-color displays running Android 8.1 should support color +management (wide-color). Before enabling this feature, ensure the device meets +the following requirements:</p> +<ul> +<li>Device display meets the hardware requirements, which include a +well-characterized display that supports the Display-P3 colorspace. If the +display does not meet this requirement, do not enable color management. To +reduce CPU and GPU impact, support for extended sRGB and HDR10 in the display +pipeline is desirable.</li> +<li>Device supports a factory calibration process that generates calibration +data (stored on the device) to adjust for manufacturing variance in display +behavior. At a minimum, calibration data should allow the display to accurately +display sRGB content and D65 and D73 white points (future versions of Android +may support full ICC profiles for each device).</li> +</ul> +<p>If the above requirements are met, you can enable the color management +feature for the device.</p> + +<h2>Implementing color management</h2> +<p>To implement color management, you must first update the +<a href="/devices/graphics/implement-hwc">Hardware Composer 2 (HWC2)</a> driver +to understand color modes and to apply those modes to the hardware. +Specifically, the HWC2 composer must report the Display-P3 and sRGB +color modes using <code>HWCDisplay::GetColorModes</code>.</p> + +<aside class="key-term"><strong>Key Term:</strong> Display-P3 uses Digital +Cinema Initiatives primaries and sRGB transfer function.</aside> + +<p>Next, enable the necessary OpenGL extensions and library support to +translate OpenGL color spaces to HAL data spaces. Required OpenGL extensions +include:</p> +<ul> +<li> +<a href="https://www.khronos.org/registry/egl/extensions/EXT/EGL_EXT_pixel_format_float.txt" class="external">EGL_EXT_pixel_format_float</a>. +Allows applications to create presentable EGLSurface(s) with 16-bit float color +components. Priority: high (expect this is the default pixel format for +wide-color aware applications). Requires driver support.</li> +<li> +<a href="https://www.khronos.org/registry/egl/extensions/KHR/EGL_KHR_gl_colorspace.txt" class="external">EGL_KHR_gl_colorspace</a>. +For applications that want to use sRGB format default framebuffers to more +easily achieve sRGB rendering to display devices, this extension allows creating +EGLSurfaces that will be rendered to in sRGB by OpenGL contexts supporting that +capability. Requires driver support for sRGB behavior.</li> +</ul> +<p>Android also provides the following optional extensions:</p> +<ul> +<li> +<a href="https://www.khronos.org/registry/egl/extensions/EXT/EGL_EXT_gl_colorspace_scrgb_linear.txt" class="external">EGL_EXT_colorspace_scrgb_linear</a>. +This extension provides a new color space option, scRGB, for applications to +choose when creating an EGLSurface. The scRGB color space defines a linear +display referred space with the same white point and color primaries as sRGB +(and thus is backward-compatible with sRGB). This should not require driver +support and can be implemented in the Android EGL wrapper. To be useful, this +extension requires support for 16-bit floating point (FP16).</li> +<li> +<a href="https://github.com/KhronosGroup/EGL-Registry/pull/10/files" class="external">EGL_KHR_gl_colorspace_display_p3 +and EGL_EXT_gl_colorspace_display_p3_linear</a>. For applications that want +to use Display-P3 format default framebuffers to more easily achieve sRGB +rendering to display devices, this extension allows creating EGLSurfaces that +will be rendered to in Display-P3 by OpenGL contexts supporting that capability. +This can be implemented in EGL driver wrapper.</li> +<li> +<a href="https://www.khronos.org/registry/vulkan/specs/1.0-extensions/html/vkspec.html#VK_EXT_swapchain_colorspace" class="external">VK_EXT_swapchain_colorspace</a> +(Vulkan). Enables applications to tag swap chains with the color space they are +using. Includes a number of common color spaces such as DCI-P3, Display-P3, +AdobeRGB, BT2020, etc.</li> +</ul> + +<h2>Customizing</h2> +<p>You can customize the color management feature by including support for a +variety of color standards such as DCI-P3, AdobeRGB, Rec709, Rec2020. Other +customizations include:</p> +<ul> +<li><strong>Hardware support for color conversion in the display +pipeline</strong>. Enables support for multiple color transforms in hardware. +</li> +<li><strong>Support for independent color transform on multiple layers</strong> +(e.g. some layers could be sRGB and others extended-sRGB, each with their own +color pipeline). When there is more than one color space visible, some color +spaces will need to be converted to the color space of the display. Ideally, +this transform is best provided by the display engine (otherwise Android must +perform GPU composition).</li> +</ul> + +<h2>Testing</h2> +<p>To test color management, use the following resources in +<code>opengl/tests</code>:</p> +<ul> +<li><code>gl2_basic</code>. Simple OpenGL demo that requests a Display-P3 +colorspace.</li> +<li><code> +<a href="https://android.googlesource.com/platform/frameworks/native/+/master/opengl/tests/EGLTest/EGL_test.cpp">EGL_test</code></a>. +Tests for necessary extension and config support (10:10:10:2 and FP16).</li> +<li><code>test_wide_color</code>. Creates surface in same manner as +SurfaceFlinger (e.g. config, color space, pixel format).</li> +</ul> + +<h2>Reference implementation</h2> +<p>For a reference implementation, refer to <code>frameworks/native</code>. For +headers, refer to:</p> +<ul> +<li> +<code><a href="https://android.googlesource.com/platform/system/core/+/master/libsystem/include/system/graphics.h">system/core/include/system/graphics.h</code></a></li> +<li> +<code><a href="https://android.googlesource.com/platform/system/core/+/master/libsystem/include/system/graphics-base.h">system/core/include/system/graphics-base.h</code></a><ul> +<li><code>HAL_DATASPACE_*</code></li> +<li><code>HAL_COLOR_MODE_*</code></li> +</ul> +</li> +</ul> + +</body> +</html> diff --git a/en/devices/tech/display/images/textclassifier.png b/en/devices/tech/display/images/textclassifier.png Binary files differnew file mode 100644 index 00000000..adbeb0b8 --- /dev/null +++ b/en/devices/tech/display/images/textclassifier.png diff --git a/en/devices/tech/display/retail-mode.html b/en/devices/tech/display/retail-mode.html index b694e616..2928b88a 100644 --- a/en/devices/tech/display/retail-mode.html +++ b/en/devices/tech/display/retail-mode.html @@ -21,34 +21,131 @@ limitations under the License. --> +<p> +Android 7.1.1 and later offer system-level support for retail mode so +users may readily examine the devices in action. Android 8.1 revises +this support to create demo users via Device Policy Manager. This +allows much greater OEM customization to the standard retail mode. +</p> +<h2 id=android-8-1-and-later>Android 8.1 and later</h2> <p> -Android 7.1.1 and later offer system-level support for retail mode so -users may readily examine the devices in action. This feature enables anyone in -a retail environment to get a quick, safe, and consistent demonstration of an -Android device and significantly reduce the cost and complexity of a retail mode -for OEMs so that demonstration units are commonplace. +Through Device Policy Manager, Android 8.1 supports demonstrating +device functionality to users in retail stores. While Device Policy Manager's +APIs can be used on versions prior to 8.1, demo-type users cannot be created +with <a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html#createAndManageUser(android.content.ComponentName, java.lang.String, android.content.ComponentName, android.os.PersistableBundle, int)"> +createAndManageUser</a> prior to 8.1. </p> -<h2 id="key-use-cases">Key use cases</h2> +<h3 id="implementation">Implementation</h3> + +<h4 id="provisioning">Provisioning</h4> +<p> +Set <code>Settings.Global.DEVICE_DEMO_MODE</code> to 1 prior to +provisioning to indicate that the device should enter retail mode. System +Server will use this flag to manage aspects of retail mode, such as power +profile. In addition, retail employees must grant device ownership to the +demo application. Once a consumer setup is complete, device owners cannot +be set. +</p> +<h4 id="create-demo-app">Creating the demo application</h4> +<p> +Device owner apps do not need elevated privileges or pre-installation on the +system image. They are mostly implmented like traditional apps, with the +following differences: +</p> <ul> -<li>Any off-the-shelf Android device can be set to retail mode by adding a -single demo video to the build. -<li>All devices have a video highlighting the unique features of the device. -<li>Devices work in both online and offline environments. -<li>Device are self maintaining, requiring minimal interaction by -employees.</li></ul> + <li>All device owner apps must extend the <code>DeviceAdminReceiver</code> +component, which serves as the authorization token for all Device Policy +Manager APIs. The component must hold the <code>android.permission.BIND_DEVICE_ADMIN</code> +permission, include the requested special policies as metadata, and filter the +<code>android.app.action.PROFILE_PROVISIONING_COMPLETE</code> and + <code>android.app.action.DEVICE_ADMIN_ENABLED</code> intents.</li> + <li>The <code>DevicePolicyManager#MAKE_USER_DEMO</code> flag, which is set +to create special demo-type users, is a hidden API. This flag is a constant 0x4.</li> + <li>Device ownership can be assigned only via Managed Provisioning.</li> +</ul> + +<h4 id="device-policy-manager">Device Policy Manager</h4> +<p> +Device Policy Manager APIs grant all Device Owner (DO) and Profile Owner (PO) +rights, except for installing packages, which is automatically allowed. A PO +affiliated with a DO can use an AIDL interface to access rights that are only +granted to the DO. Functionality available includes: +</p> +<ul> + <li>Create users. Users created through the DevicePolicyManager are +automatically set as PO.</li> + <li>Switch users.</li> + <li>Set the permission policy to <code>PERMISSION_POLICY_AUTO_GRANT</code> +which will automatically grant all runtime permissions. Permissions can also be +granted more narrowly: a single permission to a single app. This does not +apply to Appops permissions, which users must still grant on a per-user, +per-app basis.</li> + <li>Add user restrictions. Restrictions relevant to retail mode may include, +but are not limited to: + <ul> + <li><code>DISALLOW_MODIFY_ACCOUNTS</code></li> + <li><code>DISALLOW_USB_FILE_TRANSFER</code></li> + <li><code>DISALLOW_DEBUGGING_FEATURES</code></li> + <li><code>DISALLOW_CONFIG_WIFI</code></li> + <li><code>DISALLOW_CONFIG_BLUETOOTH</code></li> + <li><code>DISALLOW_INSTALL_UNKNOWN_SOURCES</code></li> + <li><code>DISALLOW_CONFIG_MOBILE_NETWORKS</code></li> + </ul> + </li> + <li>Enable automatic system updates. Devices will automatically download and apply +OTA updates.</li> + <li>Set LockTask allowed packages.</li> + <li>Factory reset the device.</li> + <li>Disable the keyguard.</li> + <li>Prevent setting passwords / fingerprints.</li> + <li>Control Wi-fi network changes. When used with the <code>DISALLOW_CONFIG_WIFI</code> +user restriction, device owner apps can control access to the wifi network selection +setting.</li> + <li>Reboot the device.</li> + <li>Install packages through <a href="https://developer.android.com/reference/android/content/pm/PackageInstaller.html"> +PackageInstaller</a>.</li> + <li>Set a whitelisted set of <a href="https://developer.android.com/reference/android/provider/Settings.Global.html"> +Settings.Global</a>, <a href="https://developer.android.com/reference/android/provider/Settings.Secure.html"> +Settings.Secure</a>, and <a href="https://developer.android.com/reference/android/provider/Settings.System.html"> +Settings.System</a> settings.</li> + <li>Block packages from being uninstalled.</li> +</ul> + +<h3 id="examples-additional-resources">Examples and additional resources</h3> +<ul> + <li><a href="/devices/tech/admin/multi-user"> +Android Developer definitions</a> of users, profiles, and accounts</li> + <li><a href="https://developer.android.com/reference/android/app/admin/DevicePolicyManager.html"> +Device Policy Manager API documentation</a></li> + <li><a href="https://developer.android.com/samples/DeviceOwner/index.html"> +Sample Device Owner app</a></li> +</ul> + +<h3 id="validation">Validation</h3> +<p> +CTS does not cover Retail Demo Mode because it is an optional feature. Testing +should be conducted manually or with unit tests for the demo application. +</p> + +<h2 id="retail-demo-mode-8-and-earlier">Android 8.0 and earlier</h2> + +<p> +Android 7.1.1 introduced retail demo mode and provided a simple API to play a +demonstration video. This implementation was removed in Android 8.1. +</p> -<h2 id="lifecycle">Lifecycle</h2> +<h3 id="lifecycle">Lifecycle</h3> <img src="/devices/tech/display/images/retail-demo-flow.png" alt="retail demo mode flow" width="XXX" id="retail-demo-flow" /> <p class="img-caption"> <strong>Figure 1.</strong> Retail demonstration mode option in Language selection </p> -<h3 id="setup-wizard-suw">Setup Wizard (SUW)</h3> +<h4 id="setup-wizard-suw">Setup Wizard (SUW)</h4> <p> Retail employees can enable retail mode directly from the first screen of any setup @@ -64,7 +161,7 @@ available. Once selected, the device finishes SUW with an abbreviated flow. selection </p> -<h3 id="guest-session">Guest session</h3> +<h4 id="guest-session">Guest session</h4> <p> When the device enters retail mode, it switches to a new demo user and @@ -125,14 +222,14 @@ settings, including: <li>Language <li>Accessibility</li></ul> -<h3 id="exiting-retail-mode">Exiting retail mode</h3> +<h4 id="exiting-retail-mode">Exiting retail mode</h4> <p> In order to exit retail mode, retail employees must factory reset the device from the boot loader. </p> -<h2 id="examples-and-source">Examples and source</h2> +<h3 id="examples-and-source">Examples and source</h3> <p> Find the custom launcher that plays a video in a loop within:</p> @@ -140,9 +237,9 @@ Find the custom launcher that plays a video in a loop within:</p> /packages/apps/RetailDemo </pre> -<h2 id="implementation">Implementation</h2> +<h3 id="implementation">Implementation</h3> -<h3 id="enabling-retaildemomodeservice">Enabling RetailDemoModeService</h3> +<h4 id="enabling-retaildemomodeservice">Enabling RetailDemoModeService</h4> <p> Setup wizard sets a Global setting <code>Global.DEVICE_DEMO_MODE=true</code> to @@ -153,8 +250,8 @@ disables SUW. System Server and SystemUI also use this flag to manage aspects of retail mode. </p> -<h3 id="setting-custom-launcher-or-video-player">Setting custom launcher or -video player</h3> +<h4 id="setting-custom-launcher-or-video-player">Setting custom launcher or +video player</h4> <p> An OEM specifies a custom launcher by overriding the framework resource @@ -207,7 +304,7 @@ To set retail mode-specific settings, use: timeout default but is configurable. </p> -<h3 id="finding-sample-images">Finding sample images</h3> +<h4 id="finding-sample-images">Finding sample images</h4> <p> This feature places sample photos in a special folder that is visible to any @@ -215,7 +312,7 @@ gallery app. The photos are available only in demo mode and cannot be modified by the demo user as they are in a protected directory. </p> -<h3 id="preventing-google-accounts">Preventing Google accounts</h3> +<h4 id="preventing-google-accounts">Preventing Google accounts</h4> <p> Certain restrictions are set in the guest user, similar to managed @@ -232,14 +329,14 @@ general problem not unique to retail mode. It is likely already solved for enterprise use cases. </p> -<h3 id="customizing-the-system-launcher">Customizing the system launcher</h3> +<h4 id="customizing-the-system-launcher">Customizing the system launcher</h4> <p> OEMs are free to choose their layout but should include apps that function well on the home screen and hotseat. </p> -<h3 id="Customizing-built-in-apps">Customizing built-in apps for retail demo mode</h3> +<h4 id="Customizing-built-in-apps">Customizing built-in apps for retail demo mode</h4> <p> Built-in apps may have their experience for retail demo mode customized by @@ -247,7 +344,7 @@ calling the API <code>UserManager.isDemoUser()</code> to see if the app is launched in a demo environment. </p> -<h3 id="following-demo-video-guidelines">Following demo video guidelines</h3> +<h4 id="following-demo-video-guidelines">Following demo video guidelines</h4> <p> Demonstration videos should be in portrait layout (or natural orientation of the @@ -255,16 +352,16 @@ device, if tablet) and can be any length greater than five seconds. Content should not result in burn-in, since it will be played 24/7 when on display. </p> -<h2 id="maintenance">Maintenance</h2> +<h3 id="maintenance">Maintenance</h3> -<h3 id="bringing-the-device-out-of-retail-mode">Bringing the device out of -retail mode</h3> +<h4 id="bringing-the-device-out-of-retail-mode">Bringing the device out of +retail mode</h4> <p> This can be done only by factory resetting from the boot loader. </p> -<h3 id="auto-ota-of-system-software">Auto-OTA of system software</h3> +<h4 id="auto-ota-of-system-software">Auto-OTA of system software</h4> <p> By default, when retail mode is enabled, device policy is set to over-the-air @@ -280,7 +377,7 @@ subsequent factory reset will result in an inability to go back into retail mode. </p> -<h3 id="updating-demo-video-via-the-web">Updating demo video via the web</h3> +<h4 id="updating-demo-video-via-the-web">Updating demo video via the web</h4> <p> The RetailDemo app in <code>/packages/apps/RetailDemo</code> has the ability to diff --git a/en/devices/tech/display/textclassifier.html b/en/devices/tech/display/textclassifier.html new file mode 100644 index 00000000..81ed87f3 --- /dev/null +++ b/en/devices/tech/display/textclassifier.html @@ -0,0 +1,153 @@ +<html devsite> + <head> + <title>Implementing TEXTCLASSIFIER</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="overview">Overview</h2> + +<p> +Android 8.1 introduces the TextClassfier API that uses machine learning +techniques to help developers classify text: +</p> + + +<pre +class="prettyprint">TextClassificationManager tcm = + context.getSystemService(TextClassificationManager.class); +TextClassifier classifier = tcm.getTextClassifier(); +TextSelection selection = classifier.suggestSelection(...); +TextClassification classification = classifier.classifyText(...); +</pre> +<p> +Developers may choose to set a custom text classifier: +</p> +<p> + <code>tcm.setTextClassifier(customTextClassifier);</code> +</p> +<p> +But if an app developer sets the text classifier to null, a system default text +classifier is returned for <code>getTextClassifier()</code>. +</p> +<p> +See: <code>android.view.textclassifier.TextClassifierImpl</code> +</p> +<p> +TextView and WebView use the TextClassifier for smart selection and smart text +share features: +</p> + +<img src="/devices/tech/display/images/textclassifier.png"> +<p class="img-caption"> + <b>Figure 1.</b> TEXTCLASSIFIER usage. +</p> + +<h2 id="textclassifier-neural-net-models">TextClassifier neural-net models</h2> +<p> +The Android Open Source Project (AOSP) features a number of neural network +models for classifying text. Each model file is trained for a single language. +You may choose to install any combination of models. The models are defined in: +</p> +<p> +<code>external/libtextclassifier/Android.mk</code> +</p> + +<h2 id="pre-installing-language-models-on-devices">Pre-installing language +models on devices</h2> +<p> +You may specify a bundle of language models and install them on a device: +</p> + + +<pre +class="prettyprint"># ----------------------- +# Smart Selection bundles +# ----------------------- + +include $(CLEAR_VARS) +LOCAL_MODULE := textclassifier.smartselection.bundle1 +LOCAL_REQUIRED_MODULES := textclassifier.smartselection.en.model +LOCAL_REQUIRED_MODULES += textclassifier.smartselection.es.model +LOCAL_REQUIRED_MODULES += textclassifier.smartselection.de.model +LOCAL_REQUIRED_MODULES += textclassifier.smartselection.fr.model +include $(BUILD_STATIC_LIBRARY) +</pre> + +<p> +For example, in <code>device/google/marlin/device-common.mk</code> +</p> + + +<pre +class="prettyprint"># TextClassifier smart selection model files +PRODUCT_PACKAGES += \ + textclassifier.smartselection.bundle1 +</pre> + +<h2 id="inspecting-installed-language-modules">Inspecting installed language +modules</h2> +<p> +Use ADB to list the files in the directory: +</p> + + +<pre +class="prettyprint">$ adb shell ls -l /etc/textclassifier +-rw-r--r-- 1 root root ... textclassifier.smartselection.de.model +-rw-r--r-- 1 root root ... textclassifier.smartselection.en.model +-rw-r--r-- 1 root root ... textclassifier.smartselection.es.model +-rw-r--r-- 1 root root ... textclassifier.smartselection.fr.model +</pre> + +<h2 id="gservices-model-updates">Model updates</h2> + +<p> +Models can be updated either by having a new model included as part of a system image update, +or dynamically via having a system component that would trigger an update through the +System <code>API ACTION_UPDATE_SMART_SELECTION</code> intent. By broadcasting this System API +intent, the framework is able to update the language model of the currently set language. +The models themselves contain the supported +language and a version number so the latest appropriate model is used. +</p> + +<p> +So you don't need to preload models for all languages because they can be added later. +If no model file is found for the specified language, text classification will return no-op values. +</p> + +<h2 id="compatibility-test-suite-tests">Compatibility Test Suite tests</h2> +<p> +The associated Android Compatibility Test Suite (CTS) tests can be found in: +</p> +<p> +<code>cts/tests/tests/view/src/android/view/textclassifier/cts/TextClassificationManagerTest.java</code> +</p> +<p> +<code>cts/tests/tests/widget/src/android/widget/cts/TextViewTest.java</code> +</p> + +<ul> +<li><code>testSmartSelection</code></li> +<li><code>testSmartSelection_dragSelection</code></li> +<li><code>testSmartSelection_resetSelection</code></li> +</ul> + +</body> +</html> diff --git a/en/devices/tech/perf/boot-times.html b/en/devices/tech/perf/boot-times.html index 4712cce0..e74ef1fc 100644 --- a/en/devices/tech/perf/boot-times.html +++ b/en/devices/tech/perf/boot-times.html @@ -254,9 +254,10 @@ us uncover many meaningful bugs in some Android device drivers). <p> Many processes launch during boot, but only components in critical path (bootloader > kernel > init > file system mount > zygote > system server) -directly affect boot time. Use the early kernel log to identify -peripheral/components that are not critical to the start init process, then -delay those peripherals/components until later in the boot process. +directly affect boot time. Profile <strong>initcall</strong> during kernel +booting to identify peripheral/components that are not critical to the +start init process, then delay those peripherals/components until later +in the boot process. </p> <h2 id="optimizing-i-o-efficiency">Optimizing I/O efficiency</h2> @@ -456,6 +457,49 @@ zygote-start). When doing this, make sure to allow zygote to run in all CPUs (as the wrong cpuset setting may force zygote to run in specific CPUs). </p> +<h3 id="disable-power-saving">Disable power saving</h3> + +<p> +During device booting, power saving setting for components like UFS and/or CPU +governor can be disabled. +</p> +<p class="aside"><strong>Caution:</strong> Power saving should be enabled in +charger mode for efficiency.</p> + +<pre +class="prettyprint"> +on init + # Disable UFS powersaving + write /sys/devices/soc/${ro.boot.bootdevice}/clkscale_enable 0 + write /sys/devices/soc/${ro.boot.bootdevice}/clkgate_enable 0 + write /sys/devices/soc/${ro.boot.bootdevice}/hibern8_on_idle_enable 0 + write /sys/module/lpm_levels/parameters/sleep_disabled Y +on property:sys.boot_completed=1 + # Enable UFS powersaving + write /sys/devices/soc/${ro.boot.bootdevice}/clkscale_enable 1 + write /sys/devices/soc/${ro.boot.bootdevice}/clkgate_enable 1 + write /sys/devices/soc/${ro.boot.bootdevice}/hibern8_on_idle_enable 1 + write /sys/module/lpm_levels/parameters/sleep_disabled N +on charger + # Enable UFS powersaving + write /sys/devices/soc/${ro.boot.bootdevice}/clkscale_enable 1 + write /sys/devices/soc/${ro.boot.bootdevice}/clkgate_enable 1 + write /sys/devices/soc/${ro.boot.bootdevice}/hibern8_on_idle_enable 1 + write /sys/class/typec/port0/port_type sink + write /sys/module/lpm_levels/parameters/sleep_disabled N</pre> + +<h3 id="defer-non-critical-initialization">Defer non-critical initialization</h3> + +<p> +Non-critical initialization such as ZRAM can be deferred to boot_complete. +</p> + +<pre +class="prettyprint"> +on property:sys.boot_completed=1 + # Enable ZRAM on boot_complete + swapon_all /vendor/etc/fstab.${ro.hardware}</pre> + <h2 id="optimizing-boot-animation">Optimizing boot animation</h2> <p> |
