Merge "Docs: Link to latest docs and update version history for N release" into nyc-dev
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index 6c95564..6aa6188 100644
--- a/src/devices/devices_toc.cs
+++ b/src/devices/devices_toc.cs
@@ -391,6 +391,7 @@
</div>
<ul>
<li><a href="<?cs var:toroot ?>devices/tech/display/dnd.html">Do Not Disturb</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/display/multi-window.html">Multi-Window</a></li>
</ul>
</li>
diff --git a/src/devices/graphics/implement-hwc.jd b/src/devices/graphics/implement-hwc.jd
index 63387d9..ecf6cfb 100644
--- a/src/devices/graphics/implement-hwc.jd
+++ b/src/devices/graphics/implement-hwc.jd
@@ -152,7 +152,8 @@
returned when the enumerated value <code>HWC2_FUNCTION_CREATE_LAYER</code> is
passed into <code>getFunction</code>.</p>
<p>For detailed documentation on functions (including functions required for
-every HWC2 implementation), refer to the HWC2 header.</p>
+every HWC2 implementation), refer to the
+<a href="{@docRoot}devices/halref/hwcomposer2_8h.html">HWC2 header</a>.</p>
<h3 id="layer_display_handles">Layer and display handles</h3>
<p>Layers and displays are manipulated by opaque handles.</p>
@@ -315,4 +316,5 @@
for frame N has now replaced the previous content." This is non-speculative,
since this fence should signal shortly after <code>presentDisplay</code> is
called as soon as the hardware presents this frame's content.</p>
-<p>For implementation details, refer to the HWC2 header.</p>
+<p>For implementation details, refer to the
+<a href="{@docRoot}devices/halref/hwcomposer2_8h.html">HWC2 header</a>.</p>
diff --git a/src/devices/tech/display/dnd.jd b/src/devices/tech/display/dnd.jd
index 9bf6b53..2e1a80b 100644
--- a/src/devices/tech/display/dnd.jd
+++ b/src/devices/tech/display/dnd.jd
@@ -1,4 +1,4 @@
-lpage.title=Configuring DND
+page.title=Configuring DND
@jd:body
<!--
diff --git a/src/devices/tech/display/multi-window.jd b/src/devices/tech/display/multi-window.jd
new file mode 100644
index 0000000..78a1976
--- /dev/null
+++ b/src/devices/tech/display/multi-window.jd
@@ -0,0 +1,123 @@
+page.title=Supporting Multi-Window
+@jd:body
+
+<!--
+ Copyright 2016 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>
+In Android 7.0, users can have multiple apps simultaneously displayed on their
+device screen with the new platform feature, multi-window. In addition to the
+default implementation of multi-window, Android Nougat supports a few varieties
+of multi-window: split-screen, free-form, and picture-in-picture.
+</p>
+
+<ul>
+<li><strong>Split-screen</strong> is the base implementation of multi-window and
+provides two activity panes for users to place apps.
+<li><strong>Freeform</strong> allows users to dynamically resize the activity
+panes and have more than two apps visible on their screen.
+<li><strong>Picture-in-picture (PIP)</strong> allows Android devices to continue
+playing video content in a small window while the user interacts with other
+applications.</li>
+</ul>
+
+<p>
+To implement the multi-window feature, device manufacturers set a flag in the
+config file on their devices to enable or disable multi-window support.
+</p>
+
+<h2 id="implementation">Implementation</h2>
+<p>
+Multi-window support is enabled by default in Android N. To disable it, set
+the <code>config_supportsMultiWindow</code> flag to false in the <a
+href="https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml">config.xml</a>
+file.
+</p>
+<p>
+For devices that declare <code>ActivityManager.isLowRam()</code>, multi-window
+is disabled regardless of the value of <code>config_supportsMultiWindow</code>
+flag.
+</p>
+<h3 id="split-screen">Split-screen</h3>
+<p>
+The default multi-window experience is split-screen mode, where the System UI is
+divided directly down the middle of the device in portrait or landscape. Users
+can resize the window by dragging the dividing line side-to-side or
+top-to-bottom, depending on the device orientation.
+</p>
+<p>
+Then device manufacturers can choose if they want to enable freeform or PIP.
+</p>
+<h3 id="freeform">Freeform</h3>
+<p>
+After enabling standard multi-window mode with the flag
+<code>config_supportsMultiWindow</code>, device manufacturers can optionally
+allow freeform windowing. This mode is most useful for manufacturers of larger
+devices, like tablets.
+</p>
+<p>
+To support freeform mode, enable the
+PackageManager#FEATURE_FREEFORM_WINDOW_MANAGEMENT system feature in <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>
+and set <code>config_freeformWindowManagement</code> to true in <a
+href="https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml">config.xml</a>.
+</p>
+
+<pre>
+<bool name="config_freeformWindowManagement">true</bool>
+</pre>
+
+<h3 id="picture-in-picture">Picture-in-picture</h3>
+<p>
+After enabling standard multi-window mode with the flag
+<code>config_supportsMultiWindow</code>, device manufacturers can support <a
+href="http://developer.android.com/preview/features/picture-in-picture.html">picture-in-picture</a>
+to allow users to continue watching video while browsing other activities.
+While this features is primarily targeted at Android Television devices, other
+device form factors may support this feature.
+</p>
+<p>
+To support PIP, enable the PackageManager#FEATURE_PICTURE_IN_PICTURE system
+feature in <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>.
+</p>
+<h3 id="system-ui">System UI</h3>
+<p>
+Support all standard System UIs according to <a
+href="http://developer.android.com/preview/features/multi-window.html#testing">http://developer.android.com/preview/features/multi-window.html#testing</a>
+</p>
+<h3 id="applications">Applications</h3>
+<p>
+To support multi-window mode for preloaded apps, consult the <a
+href="http://developer.android.com/preview/features/multi-window.html">developer
+preview documentation</a>.
+</p>
+<h2 id="validation">Validation</h2>
+<p>
+To validate their implementation of multi-window, device manufacturers should
+run <a
+href="https://android.googlesource.com/platform/cts/+/master/hostsidetests/services/activitymanager/src/android/server/cts">CTS
+tests</a> and follow the <a
+href="http://developer.android.com/preview/features/multi-window.html#testing">testing
+instructions for multi-window</a>.
+</p>
diff --git a/src/devices/tech/images/power_sustained_perf.png b/src/devices/tech/images/power_sustained_perf.png
new file mode 100644
index 0000000..5ed7810
--- /dev/null
+++ b/src/devices/tech/images/power_sustained_perf.png
Binary files differ
diff --git a/src/devices/tech/power/mgmt.jd b/src/devices/tech/power/mgmt.jd
index 481e056..16aed9d 100644
--- a/src/devices/tech/power/mgmt.jd
+++ b/src/devices/tech/power/mgmt.jd
@@ -29,19 +29,25 @@
<p>Android includes the following battery life enhancements:</p>
<ul>
-<li><b><a href="#app-standby">App Standby</b></a>. The platform can place
-unused applications in App Standby mode, temporarily restricting network access
-and deferring syncs and jobs for those applications.</li>
-<li><b><a href="#doze">Doze</b></a>. The platform can enter a state of deep
-sleep (periodically resuming normal operations) if users have not actively used
-their device (screen off and stationary) for extended periods of time. Android N
-also enables Doze to trigger a lighter set of optimizations when users turn
-off the device screen yet continue to move around.</li>
-<li><b><a href="#exempt-apps">Exemptions</b></a>. System apps and cloud
-messaging services preloaded on a device are typically exempted from App Standby
-and Doze by default (although app developers can intent their applications into
-this setting). Users can exempt applications via the Settings menu.</li>
+<li><strong><a href="#app-standby">App Standby</strong></a>. The platform can
+place unused applications in App Standby mode, temporarily restricting network
+access and deferring syncs and jobs for those applications.</li>
+<li><strong><a href="#doze">Doze</strong></a>. The platform can enter a state of
+deep sleep (periodically resuming normal operations) if users have not actively
+used their device (screen off and stationary) for extended periods of time.
+Android 7.0 also enables Doze to trigger a lighter set of optimizations when
+users turn off the device screen yet continue to move around.</li>
+<li><strong><a href="#exempt-apps">Exemptions</strong></a>. System apps and
+cloud messaging services preloaded on a device are typically exempted from App
+Standby and Doze by default (although app developers can intent their
+applications into this setting). Users can exempt applications via the Settings
+menu.</li>
+<li><strong><a href="#sustained_performance">Sustained Performance</a></strong>.
+To address performance variations during high device temperatures, Android 7.0
+includes support for sustained performance, enabling OEMs to provide hints on
+device performance capabilities for long-running applications.</li>
</ul>
+
<p>The following sections describe these enhancements.</p>
<h2 id="app-standby">App Standby</h2>
@@ -92,7 +98,7 @@
a period of time.
</p>
-<h3>Testing App Standby</h3>
+<h3 id=testing_app_standby>Testing App Standby</h3>
<p>You can manually test App Standby using the following ADB commands:</p>
<pre>
@@ -115,14 +121,14 @@
times, a device in Doze remains aware of motion and immediately leaves Doze
if motion is detected.</p>
-<p>Android N extends Doze to trigger a lighter set of optimizations every time
+<p>Android 7.0 extends Doze to trigger a lighter set of optimizations every time
a user turns off the device screen, even when the user continues to move around,
enabling longer lasting battery life.</p>
<p>System services (such as telephony) may be preloaded and exempted from Doze
by default. Users can also exempt specific applications from Doze in the
-Settings menu. By default, Doze is <b>disabled</b> in the Android Open Source
-Project (AOSP). For details on enabling Doze, see
+Settings menu. By default, Doze is <strong>disabled</strong> in the Android Open
+Source Project (AOSP). For details on enabling Doze, see
<a href="#integrate-doze">Integrating Doze</a>.</p>
<h3 id="doze-reqs">Doze requirements</h3>
@@ -132,7 +138,7 @@
<p>Full Doze support also requires a
<a href="{@docRoot}devices/sensors/sensor-types.html#significant_motion">Significant
Motion Detector (SMD)</a> on the device; however, the lightweight Doze mode in
-Android N does not require an SMD. If Doze is enabled on a device that:</p>
+Android 7.0 does not require an SMD. If Doze is enabled on a device that:</p>
<ul>
<li>Has an SMD, full Doze optimizations occur (includes lightweight
optimizations).</li>
@@ -192,7 +198,7 @@
</tbody>
</table>
-<p>Android N extends Doze by enabling a lightweight sleep mode during screen
+<p>Android 7.0 extends Doze by enabling a lightweight sleep mode during screen
off, before the device is idle.</p>
<p><img src="../images/doze_lightweight.png"></p>
<p class="img-caption">Figure 1. Doze modes for non-stationary and stationary
@@ -255,7 +261,7 @@
<li>Confirm the device has a cloud messaging service installed.</li>
<li>In the device overlay config file
<code>overlay/frameworks/base/core/res/res/values/config.xml</code>, set
-<code>config_enableAutoPowerModes</code> to <b>true</b>:
+<code>config_enableAutoPowerModes</code> to <strong>true</strong>:
<pre>
bool name="config_enableAutoPowerModes">true</bool>
</pre>
@@ -267,7 +273,7 @@
<a href="https://developer.android.com/preview/behavior-changes.html#behavior-power">power-saving
optimization guidelines</a>. For details, see <a href="#test-apps">Testing and
optimizing applications</a>.
-<p><b>OR</b></p>
+<p><strong>OR</strong></p>
<li>Are exempted from Doze and App Standby. For details, see
<a href="#exempt-apps">Exempting applications</a>.</li>
</ul>
@@ -300,7 +306,7 @@
<a href="https://developer.android.com/preview/testing/guide.html#doze-standby">Testing
Doze and App Standby</a>.</p>
-<p class="note"><b>Note</b>: MMS/SMS/Telephony services function independently
+<p class="note"><strong>Note</strong>: MMS/SMS/Telephony services function independently
of Doze and will always wake client apps even while the device remains in Doze
mode.</p>
@@ -313,8 +319,8 @@
<li>Third-party application using non-GCM Cloud Messaging platform</li>
</ul>
-<p class="warning"><b>Warning</b>: Do not exempt apps to avoid testing and
-optimizing. Unnecessary exemptions undermine the benefits of Doze and App
+<p class="warning"><strong>Warning</strong>: Do not exempt apps to avoid testing
+and optimizing. Unnecessary exemptions undermine the benefits of Doze and App
Standby and can compromise the user experience, so we strongly suggest
minimizing such exemptions as they allow applications to defeat beneficial
controls the platform has over power use. If users become unhappy about the
@@ -327,9 +333,81 @@
<p>Apps exempted by default are listed in a single view within the Settings >
Battery menu. This list is used for exempting the app from both Doze and App
Standby modes. To provide transparency to the user, the Settings menu
-<b>MUST</b> show all exempted applications.</p>
+<strong>MUST</strong> show all exempted applications.</p>
<p>Users can manually exempt apps via Settings > Battery > Battery optimization
> All apps and then selecting the app to turn off (or back on) optimization.
However, users cannot unexempt any application or service that is exempted by
default in the system image.</p>
+
+<h2 id=sustained_performance>Sustained performance</h2>
+<p>For long-running applications (games, camera, RenderScript, audio
+processing), performance can vary dramatically as device temperature limits are
+reached and system on chip (SoC) engines are throttled. App developers creating
+high-performance, long-running apps are limited because the capabilities of the
+underlying platform are a moving target when the device begins to heat up.</p>
+
+<p>To address these limitations, Android 7.0 includes support for sustained
+performance, enabling OEMs to provide hints on device performance capabilities
+for long-running applications. App developers can use these hints to tune
+applications for a predictable, consistent level of device performance over long
+periods of time.</p>
+
+<h3 id=architecture>Architecture</h3>
+<p>An Android application can request the platform to enter a sustained
+performance mode where the Android device can keep a consistent level of
+performance for prolonged periods of time.</p>
+
+<p><img src="../images/power_sustained_perf.png"></p>
+<p class="img-caption"><strong>Figure 1.</strong> Sustained performance mode
+architecture</p>
+
+<h3 id=implementation>Implementation</h3>
+<p>To support sustained performance in Android 7.0, OEMs must:</p>
+<ul>
+<li>Make device-specific changes to the power HAL to either lock the maximum
+CPU/GPU frequencies <strong>or</strong> perform other optimizations to prevent
+thermal throttling.</li>
+<li>Implement the new hint <code>POWER_HINT_SUSTAINED_PERFORMANCE</code> in
+power HAL.</li>
+<li>Declare support by returning TRUE through the
+<code>isSustainedPerformanceModeSupported()</code> API.</li>
+<li>Implement <code>Window.setSustainedPerformanceMode</code>.</li>
+</ul>
+
+<p>In the Nexus reference implementation, the power hint caps the
+maximum frequencies of the CPU and GPU at the highest sustainable levels. Keep
+in mind that lowering the MAX bar in CPU/GPU frequency will lower the frame
+rate, but this lower rate is preferred in this mode due to its sustainability.
+For example, a device using normal max clocks might be able to render at 60
+FPS for a few minutes, but after the device heats up, it may throttle to 30 FPS
+by the end of 30 minutes. When using sustained mode, the device can, for
+example, render consistently at 45 FPS for the entire 30 minutes. The goal is a
+frame rate when using the mode that is as high (or higher) than the frame rate
+when not using the mode, and consistent over time so that developers don't have
+to chase a moving target.</p>
+<p>We strongly recommend implementing sustained mode such that the device
+achieves the highest possible sustained performance—not just the minimum values
+required to pass the test (e.g. choose the highest possible MAX frequency caps
+that do not cause the device to thermally throttle over time).</p>
+
+<p class="note"><strong>Note</strong>: Capping MAX clock rates is not required
+to implement sustained mode.</p>
+
+
+<h3 id=validation>Validation</h3>
+<p>OEMs can use a new Android 7.0 CTS test to verify their implementation of the
+sustained performance API. The test runs a workload for approximately 30 minutes
+and benchmarks the performance with and without sustained mode enabled:</p>
+<ul>
+<li>With sustained mode enabled, the frame rate must remain relatively constant
+(test measures the percentage of change in frame rate over time and requires a
+<5% change).</li>
+<li>With sustained mode enabled, the frame rate must not be lower than the frame
+rate at the end of 30 minutes with the mode disabled.</li>
+</ul>
+<p>In addition, you can manually test your implementation with several CPU- and
+GPU-intensive workloads to ensure the device does not thermally throttle after
+30 minutes of use. In internal testing, we used sample workloads including
+games and benchmarking apps (e.g.
+<a href="https://gfxbench.com/result.jsp">gfxbench</a>).</p>
