Merge "Docs: Changes to source.android.com"

6 files changed, 192 insertions, 8 deletions

diff --git a/en/devices/architecture/dto/partitions.html b/en/devices/architecture/dto/partitions.html
index bcbea204..d18cda84 100644
--- a/en/devices/architecture/dto/partitions.html
+++ b/en/devices/architecture/dto/partitions.html
@@ -150,8 +150,8 @@ several commands, including <code>create</code>, <code>cfg_create</code>, and
 <h3 id=create>create</h3>
 <p>Use the <code>create</code> command to create a
 <code>dtb</code>/<code>dtbo</code> image:</p>
-<pre class="prettyprint">
-$mkdtimg create &lt;image_filename&gt; (&lt;global-option&gt;...) \
+<pre class="devsite-click-to-copy">
+<code class="devsite-terminal">mkdtimg create &lt;image_filename&gt; (&lt;global-option&gt;...) \</code>
     &lt;ftb1_filename&gt; (&lt;entry1_option&gt;...) \
     &lt;ftb2_filename&gt; (&lt;entry2_option&gt;...) \
     ...
@@ -184,7 +184,7 @@ value of <code>page_size</code> in <code>dt_table_header</code> is 2048; use
 value.</p>
 
 <p>Example:</p>
-<pre class="prettyprint">
+<pre class="devsite-click-to-copy">
 [board1.dts]
 /dts-v1/;
 /plugin/;
@@ -203,7 +203,7 @@ value.</p>
 };
 
 
-$mkdtimg create dtbo.img --id=/:board_id --custom0=0xabc \
+<code class="devsite-terminal">mkdtimg create dtbo.img --id=/:board_id --custom0=0xabc \</code>
   board1.dtbo \
   board2.dtbo --id=0x6800 \
   board3.dtbo --id=0x6801 --custom0=0x123
@@ -243,7 +243,7 @@ with one or more space characters (these options are the same as
 lines beginning with <code>#</code> are ignored.</p>
 
 <p>Example:</p>
-<pre class="prettyprint">
+<pre class="devsite-click-to-copy">
 [dtboimg.cfg]
 # global options
   id=/:board_id
@@ -260,7 +260,7 @@ board2.dtbo
   custom0=0x123   # override the value of custom0 in global options
 
 
-$mkdtimg cfg_create dtbo.img dtboimg.cfg
+<code class="devsite-terminal">mkdtimg cfg_create dtbo.img dtboimg.cfg</code>
 </pre>
 
 <p><code>mkdtimg</code> does not handle alignment for
@@ -278,8 +278,8 @@ useful when using different hardware with identical DTs.</p>
 <h3 id=dump>dump</h3>
 <p>For <code>dtb</code>/<code>dtbo</code> images, use the <code>dump</code>
 command to print the information in the image. Example:</p>
-<pre class="prettyprint">
-$mkdtimg dump dtbo.img
+<pre class="devsite-click-to-copy">
+<code class="devsite-terminal">mkdtimg dump dtbo.img</code>
 dt_table_header:
                magic = d7b7ab1e
           total_size = 1300
diff --git a/en/devices/architecture/hidl/services.html b/en/devices/architecture/hidl/services.html
index 647555b7..75933ec9 100644
--- a/en/devices/architecture/hidl/services.html
+++ b/en/devices/architecture/hidl/services.html
@@ -51,8 +51,12 @@ into the server.</p>
 version, calling <code>getService</code> on the desired HAL class:</p>
 
 <pre class="prettyprint">
+// C++
 sp&lt;V1_1::IFooService&gt; service = V1_1::IFooService::getService();
 sp&lt;V1_1::IFooService&gt; alternateService = 1_1::IFooService::getService("another_foo_service");
+// Java
+V1_1.IFooService; service = V1_1.IFooService.getService(true /* retry */);
+V1_1.IFooService; alternateService = 1_1.IFooService.getService("another", true /* retry */);
 </pre>
 
 <p>Each version of a HIDL interface is treated as a separate interface. Thus,
@@ -69,6 +73,16 @@ returned interface. For an interface <code>IFoo</code> in package
 <code>android.hardware.foo</code> in the device manifest if the entry exists;
 and if the transport method is not available, nullptr is returned.</p>
 
+<p> In some cases, it may be necessary to continue immediately even without
+getting the service. This can happen (for instance) when a client wants to
+manage service notifications itself or in a diagnostic program (such as
+<code>atrace</code>) which needs to get all hwservices and retrieve them. In
+this case, additional APIs are provided such as <code>tryGetService</code> in C++ or
+<code>getService("instance-name", false)</code> in Java. The legacy API
+<code>getService</code> provided in Java also must be used with service
+notifications. Using this API does not avoid the race condition where a server
+registers itself after the client requests it with one of these no-retry APIs.</p>
+
 <h2 id=death>Service death notifications</h2>
 <p>Clients who want to be notified when a service dies can receive death
 notifications delivered by the framework. To receive notifications, the client
diff --git a/en/devices/architecture/images/android-diffs.png b/en/devices/architecture/images/android-diffs.png
new file mode 100644
index 00000000..312718cb
--- /dev/null
+++ b/en/devices/architecture/images/android-diffs.png
diff --git a/en/devices/architecture/images/kernel_branch_hierarchy_44.png b/en/devices/architecture/images/kernel_branch_hierarchy_44.png
new file mode 100644
index 00000000..ab749e87
--- /dev/null
+++ b/en/devices/architecture/images/kernel_branch_hierarchy_44.png
diff --git a/en/devices/architecture/images/kernel_lts_diff.png b/en/devices/architecture/images/kernel_lts_diff.png
new file mode 100644
index 00000000..cbd9fafa
--- /dev/null
+++ b/en/devices/architecture/images/kernel_lts_diff.png
diff --git a/en/devices/architecture/kernel/android-common.html b/en/devices/architecture/kernel/android-common.html
new file mode 100644
index 00000000..13175576
--- /dev/null
+++ b/en/devices/architecture/kernel/android-common.html
@@ -0,0 +1,170 @@
+<html devsite>
+  <head>
+    <title>Android Common Kernels</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://android.googlesource.com/kernel/common/" class="external">AOSP
+common kernels</a> are downstream of Long Term Supported (LTS) kernels and
+include patches of interest to the Android community that have not been merged
+into LTS. These patches can include:</p>
+
+<ul>
+<li>Features tailored for Android needs (e.g. interactive <code>cpufreq</code>
+governor).</li>
+<li>Features rejected by upstream due to implementation concerns (e.g. MTP/PTP,
+paranoid networking).</li>
+<li>Features ready for Android devices but still under development upstream
+(e.g. Energy Aware Scheduling/EAS).</li>
+<li>Vendor/OEM features that are useful for others (e.g. <code>sdcardfs</code>).
+</li>
+</ul>
+
+<h2 id="list-of-kernels">List of common kernels</h2>
+<p>To view a list of Android common kernels, refer to
+<a href="https://android.googlesource.com/kernel/common/" class=external>https://android.googlesource.com/kernel/common/</a>
+(shown below).</p>
+<p><img src="../images/android-diffs.png"></p>
+<p class="img-caption"><strong>Figure 1.</strong> List of Android common
+kernels.</p>
+
+<h3 id="differences-lts">Differences from LTS</h3>
+<p>When compared to LTS (4.4.40), the Android common kernel has 679 changes,
+56172 insertions, and 3340 deletions (as of February 2017).</p>
+
+<p><img src="../images/kernel_lts_diff.png"></p>
+<p class="img-caption"><strong>Figure 2.</strong> Android-specific code over
+time.</p>
+
+<p>The largest features include:</p>
+<ul>
+<li>13.8% SoC (arch/arm64, arch/x86)</li>
+<li>9.2% USB (drivers/usb)</li>
+<li>8.2% Energy Aware Scheduling (kernel/sched)</li>
+<li>8.2% Atomic Display Framework (drivers/video/adf)</li>
+<li>8.0% networking (net/netfilter)</li>
+<li>6.2% sdcardfs (fs/sdcardfs)</li>
+<li>5.0% Verity (drivers/md)</li>
+<li>3.7% Input (drivers/input/misc)</li>
+<li>3.3% FIQ Debugger (drivers/staging/android/fiq_debugger)</li>
+<li>2.4% Cpufreq (drivers/cpufreq)</li>
+<li>2.2% Goldfish Emulator (drivers/platform/goldfish)</li>
+</ul>
+
+<h2 id="requirements">Requirements</h2>
+<p>All AOSP common kernels must provide the following:</p>
+<ul>
+<li>Method for downstream partners to get timely updates that include all
+LTS patches.</li>
+<li>Mechanism to guarantee that new feature development does not interfere with
+merging from AOSP common (even for previous Android releases).</li>
+<li>Method for downstream partners to easily identify security patches that are
+part of an <a href="/security/bulletin/">Android Security Bulletin (ASB)</a>.
+This satisfies carriers who require a full requalification if OEMs attempt to
+include patches beyond those listed in the bulletin.</li>
+</ul>
+<p>In addition, regular testing must be performed on AOSP common kernels and
+branches must be tagged when passing.</p>
+
+<h3 id="lts-merges">LTS merges</h3>
+<p>To ensure downstream partners can get timely updates that include all LTS
+patches, android-<var>X</var>.<var>Y</var> gets regular merges from LTS and is
+validated via automated VTS, CTS, and build/boot tests.</p>
+
+<h3 id="android-dessert-branches">Android-dessert branches</h3>
+<p>To guarantee that new feature development does not interfere with merging
+from the AOSP common kernel (even for previous Android releases),
+android-<var>X</var>.<var>Y</var>-<var>androidRel</var> is cloned from
+android-<var>X</var>.<var>Y</var> prior to the initial dessert release, gets regular
+merges from LTS, and is tested against the associated Android release. For
+example, the android-4.4-n branch gets merges from the LTS 4.4.y branch. </p>
+
+<h3 id="android-release-branches">Android-release branches</h3>
+<p>To ensure downstream partners can easily identify security patches that are
+part of an ASB,
+android-<var>X</var>.<var>Y</var>-<var>androidRel</var>-<var>type</var> is
+cloned from android-<var>X</var>.<var>Y</var>-<var>androidRel</var> at the time
+of the Android release and gets only the patches listed in the bulletin.</p>
+
+<p>After the patches associated with a bulletin are confirmed to be merged
+into a release branch, the branch is tagged with the ASB level. For example, the
+tag <strong>ASB-2017-10-05</strong> indicates the release branch contains
+patches from the Android Security Bulletin for October 5th, 2017. Parent
+branches contain those security patches, so if the android-4.4-o-release branch
+is tagged with <strong>ASB-2017-10-01</strong>, android-4.4-o and android-4.4
+are also up-to-date with that bulletin. Example:</p>
+<ul>
+<li>Before releasing Android N MR1, <strong>android-4.4-n-mr1</strong> is cloned
+from <strong>android-4.4-n</strong>.</li>
+<li>Only patches listed in ASBs are merged, allowing OEMs (who have strict
+requirements from carriers to avoid full qualification on security updates) to
+find the patches listed in the bulletin.</li>
+<li><strong>android-4.4-n-mr2</strong> will be
+<strong>android-4.4-n-mr1</strong> plus LTS patches that were merged between the
+releases.</li>
+<li>Each month when the ASB is released publicly, the release branches are
+updated with any patches cited in the bulletin that are upstream
+(device-specific patches cited in the bulletin are not applied to the common
+kernels).</li>
+</ul>
+
+<h3 id="regular-testing">Regular testing</h3>
+<p>Regular testing is performed on all on AOSP common kernels and test results
+are available to the public. Specifically:</p>
+<ul>
+<li>After LTS updates or other patches are merged, VTS and a subset of CTS
+is run and results are made available at
+<a href="https://qa-reports.linaro.org/lkft" class="external">https://qa-reports.linaro.org/lkft</a>.
+</li>
+<li>To continually test for build/boot breaks in a variety of architectures and
+builds, <code>kernelci</code> is run and results are made available at
+<a href="https://kernelci.org/job/android/" class="external">https://kernelci.org/job/android</a>.
+</li>
+</ul>
+
+<h3 id="branch-hierarchy">Branch hierarchy (android-4.4)</h3>
+<p>The branch hierarchy for the android-4.4 kernel uses the following structure:
+</p>
+
+<p><img src="../images/kernel_branch_hierarchy_44.png"></p>
+<p class="img-caption"><strong>Figure 3.</strong> Branch hierarchy for the
+android-4.4 kernel.</p>
+
+<h2 id="guidelines">Guidelines</h2>
+<p>Android implementations should use the following kernel guidelines:</p>
+<ul>
+<li>Use the new AOSP common kernels as upstream merge sources.<ul>
+<li>To get patches from LTS, merge from android-<var>X</var>.<var>Y</var>.<ul>
+<li>Merge regularly during development phase.</li>
+<li>When updating device to a new Android release, merge either from the
+android-<var>X</var>.<var>Y</var> branch or the release branch for the target
+release (e.g. for an update to Nougat MR2, merge from the android-4.4-n-mr2
+branch).</li>
+</ul>
+<li>When constrained by the carrier for a security release, merge from release
+branches for security updates.</li>
+</ul>
+<li>Send fixes upstream to mainline, LTS, or AOSP common.</li>
+</ul>
+
+  </body>
+</html>