Docs: Changes to source.android.com

  - 175558266 Add left nav to advisory by Danielle Roberts <daroberts@google.com>
  - 175554955 Fix malformed reference to AOSP by Clay Murphy <claym@google.com>
  - 175550240 Devsite localized content from translation request 7a0693... by Android Partner Docs <noreply@android.com>
  - 175549114 Typo fix (ASOP -> AOSP) by Christina Nguyen <cqn@google.com>
  - 175293154 Devsite localized content from translation request 372f6d... by Android Partner Docs <noreply@android.com>
  - 175248838 Devsite localized content from translation request 29d8af... by Android Partner Docs <noreply@android.com>
  - 175218477 Clarify information about update_verifier and care_map.txt. by Christina Nguyen <cqn@google.com>
  - 175207560 Adding android common kernel details by Heidi von Markham <hvm@google.com>
  - 175185286 Add November Security bulletins to home page by Danielle Roberts <daroberts@google.com>
  - 175055180 Add AOSP links to Android and Pixel security bulletins by Danielle Roberts <daroberts@google.com>
  - 175042468 updated researcher acknowledgments by Android Partner Docs <noreply@android.com>
  - 175015511 Devsite localized content from translation request 9104ad... by Android Partner Docs <noreply@android.com>
  - 175015506 Devsite localized content from translation request bd87ac... by Android Partner Docs <noreply@android.com>
  - 174885954 Update build numbers for Nov 2017 EMR releases by Android Partner Docs <noreply@android.com>
  - 174874043 Devsite localized content from translation request 76c64c... by Android Partner Docs <noreply@android.com>
  - 174773244 Update build numbers for Nov 2017 releases by Android Partner Docs <noreply@android.com>
  - 174726959 Add FunctionFS support to Architecture section of Site Up... by Clay Murphy <claym@google.com>
  - 174724840 November Pixel/ Nexus & Android security bulletins by Danielle Roberts <daroberts@google.com>
  - 174719013 Updating link for reporting security vulns on Android by Android Partner Docs <noreply@android.com>
  - 174704161 Devsite localized content from translation request 937e48... by Android Partner Docs <noreply@android.com>
  - 174704153 Devsite localized content from translation request 9112c5... by Android Partner Docs <noreply@android.com>
  - 174528053 Devsite localized content from translation request 6e449c... by Android Partner Docs <noreply@android.com>
  - 174487952 Add outstanding updates to home page and Site Updates by Clay Murphy <claym@google.com>
  - 174475927 Add description how to build userspace HAL for neonkey by Android Partner Docs <noreply@android.com>
  - 174380489 Devsite localized content from translation request 841fb1... by Android Partner Docs <noreply@android.com>
  - 174380480 Devsite localized content from translation request 9eb492... by Android Partner Docs <noreply@android.com>
  - 174380476 Devsite localized content from translation request 04daa4... by Android Partner Docs <noreply@android.com>
  - 174248031 Update documentation to talk about retry vs. no-retry APIs. by Android Partner Docs <noreply@android.com>
  - 174202686 Update CTS/CTS-Verifier download links for CTS-Nov-2017 R... by Android Partner Docs <noreply@android.com>
  - 174116481 Devsite localized content from translation request 9299f0... by Android Partner Docs <noreply@android.com>
  - 174116372 Devsite localized content from translation request 6491d8... by Android Partner Docs <noreply@android.com>
  - 174099937 Include Nougat MR1 and Oreo branch information in release... by Android Partner Docs <noreply@android.com>
  - 174083954 Fixed some formatting and grammatical issues. by Christina Nguyen <cqn@google.com>
  - 174079046 Add devsite-click-to-copy and devsite-terminal classes by Christina Nguyen <cqn@google.com>
  - 174066120 Fix some terminal and click-to-copy classes by Christina Nguyen <cqn@google.com>
  - 173967954 Remove optional "function" keyword as discussed in b/6788... by Christina Nguyen <cqn@google.com>
  - 173952142 Escape a character so that Gerrit reads HTML properly. by Christina Nguyen <cqn@google.com>
  - 173951380 Update overview page and separated out non-a/b device upd... by Christina Nguyen <cqn@google.com>

PiperOrigin-RevId: 175558266
Change-Id: I413bc55681f23979b36d84ded9b012486988421b

1 files changed, 170 insertions, 0 deletions

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>