s.a.c. redesign, first checkin
Change-Id: I4dead2f18bc5e4a38f204c92198a267c286e775d
diff --git a/src/devices/overview.jd b/src/devices/overview.jd
new file mode 100644
index 0000000..ddb34b9
--- /dev/null
+++ b/src/devices/overview.jd
@@ -0,0 +1,198 @@
+page.title=Overview
+@jd:body
+
+<!--
+ Copyright 2010 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>
+ </ol>
+ </div>
+</div>
+
+<p>Welcome to the Android Platform Development Kit (PDK) Guide! The Android PDK allows partners to port
+ their drivers as well as develop, optimize, and test against an upcoming Android platform release.
+ The Android PDK includes a set of interfaces for the Android hardware abstraction layer (HAL),
+ platform sources for integration, a binary system image, and HAL and integration documentation.
+ In addition, the PDK also ships with the Android Compatibility Test Suite (CTS).
+</p>
+
+<h2 id="arch">Android Low-Level System Architecture</h2>
+<p>Before you begin porting Android to your hardware, it is important to have an
+understanding of how Android works at a high level. Because your drivers and HAL code interact
+with many layers of Android code, this understanding can help you find
+your way through the many layers of code that are available to you through the AOSP
+(Android Open Source Project) source tree as well as the PDK.
+The following diagram shows a system level view of how Android works:
+</p>
+
+<img src="images/system-architecture.png">
+
+<p class="img-caption"><strong>Figure 1.</strong> Android System Architecture</p>
+
+ <h4>Application framework</h4>
+ <p>This is the level that most application developers concern themselves with. You should be
+ aware of the APIs available to developers as many of them map 1:1 to the underlying HAL
+ interfaces and can provide information as to how to implement your driver.
+ </p>
+
+ <h4>Binder IPC</h4>
+ <p>
+ The Binder Inter-Process Communication mechanism allows the application framework to
+ cross process boundaries and call into the Android system services code. This basically allows
+ high level framework APIs to interact with Android's system services. At the application framework level, all
+ of this communication is hidden from the developer and things appear to "just work."
+ </p>
+
+ <h4>System services</h4>
+ <p>Most of the functionality exposed through the application framework APIs must
+ communicate with some sort of system service to access the underlying hardware. Services
+ are divided into modular components with focused functionality
+ such as the Window Manager, Search Service, or Notification Manager. System services are grouped
+ into two buckets: system and media. The system services include things such as the Window or
+ Notification Manager. The media services include all the services involved in playing and
+ recording media.
+ </p>
+
+<h4>Hardware abstraction layer (HAL)</h4>
+<p>The HAL serves as a standard interface that allows the Android system to call into the device
+ driver layer while being agnostic about the lower-level implementations of your drivers and hardware.
+ You must implement the corresponding HAL (and driver) for the particular piece of hardware that your product
+ provides. Android does not mandate a standard interaction between your HAL implementation and your device drivers, so
+ you have free reign to do what is best for your situation. However, you must abide by the contract
+ defined in each hardware-specific HAL interface for the Android system to be able
+ to correctly interact with your hardware. HAL implementations are typically built into
+ shared library modules (<code>.so</code> files).
+</p>
+<h4>Linux Kernel</h4>
+<p>For the most part, developing your device drivers is the same as developing a typical Linux device driver.
+ Android uses a specialized version of the Linux kernel with a few special additions such as
+ wakelocks, a memory management system that is more agressive in preserving memory,
+ the Binder IPC driver, and other features that are important for a mobile embedded platform like Android.
+ These additions have less to do with driver development than with the system's functionality. The PDK
+ does not provide kernel sources, so you must provide your own. You can use any version of the kernel that
+ you want as long as it supports the required features, such as the binder driver. However, we recommend
+ using the latest version of the Android kernel. For the latest Android kernel, see
+ <a href="http://source.android.com/source/building-kernels.html" >Building Kernels</a>.
+</p>
+
+
+<h2 id="pdk">PDK Components</h2>
+<p>Now that you have a high-level overview of the Android system, we'll go over the PDK and what it provides
+ to port Android to your product. The PDK provides source files needed to implement
+ your product and a platform binary that lets you build a runnable system image. You can then install
+ this barebones image to test your product with the latest builds of Android. The most important source files
+ included in the PDK are located in the:</p>
+
+ <ul>
+ <li><code>frameworks/native</code> directory</li>
+ <li><code>frameworks/av</code> directory for media, camera, DRM, and the audio framework stack</code></li>
+ <li><code>hardware/libhardware/include/hardware</code> directory for the HAL interfaces </li>
+ <li><code>vendor/pdk/data/cts</code> directory for the CTS binaries</li>
+ </ul>
+</p>
+<p>In addition, the Android PDK includes the following source directories:</p>
+<ul>
+ <li>abi</li>
+ <li>bionic</li>
+ <li>bootable</li>
+ <li>build</li>
+ <li>device</li>
+ <li>external (Chromium and Webkit are not included)</li>
+ <li>hardware</li>
+ <li>libnativehelper</li>
+ <li>pdk</li>
+ <li>prebuilt</li>
+ <li>prebuilts</li>
+ <li>system</li>
+</ul>
+
+ <p>The PDK also contains documentation that is split into three different sections:</p>
+ <ul>
+ <li><a href="{@docRoot}guide/getting_started.html">Getting Started</a> - Explains how to download the PDK source, how the Android build system works, and how to configure a build for your specific product.</li>
+ <li><a href="{@docRoot}guide/hal.html">The Hardware Abstraction Layer</a> - Explains the various HALs provided by Android and the interfaces (C header files) that define them. </li>
+ <li><a href="{@docRoot}guide/reference/files.html">HAL reference</a> - A quick reference for the various HAL interfaces.</li>
+ </ul>
+
+<h3 id="cts">Compatibility Test Suite</h3>
+<p>CTS binaries for ARM, MIPS, and x86 are provided in the corresponding directories in <code>vendor/pdk/data/cts</code>. Only the ARM
+ variant is Google-verified as there is no Nexus device running on any other architecture. Not all of the CTS tests since the
+ complete Android platform is not present. The following CTS tests should work:</p>
+
+<ul>
+ <li>android.bluetooth</li>
+ <li>android.graphics</li>
+ <li>android.graphics2</li>
+ <li>android.hardware</li>
+ <li>android.location</li>
+ <li>android.opengl</li>
+ <li>android.openglperf</li>
+ <li>android.media</li>
+ <li>android.mediastress</li>
+ <li>android.nativemedia.sl</li>
+ <li>android.nativemedia.xa</li>
+ <li>android.net</li>
+ <li>android.renderscript</li>
+ </ul>
+ <p>You can run individual packages such as <code>android.media</code> with:</p>
+ <pre>cts-tradefed run singleCommand cts --skip-device-info --package android.media</pre>
+</ul>
+
+ <p>Because the PDK is missing many components compared to a full Android source tree,
+ there is a PDK test plan that is provided with CTS that limits the tests that are ran when using the PDK. You can run
+ this special test plan with the following command:</p>
+
+ <pre>run cts --plan PDK</pre>
+
+<p>CTS is always actively under development, so we expect some tests to fail. CTS results
+ for the Galaxy Nexus are provided for you in the
+ the <code>vendor/pdk/data/cts/</code> directory and will show which tests fail on that
+ device. You can safely ignore the failed tests for your devices as well.</p>
+
+ <p>See the <a href="http://source.android.com/compatibility/cts-intro.html">CTS manual</a> for more information on CTS.</p>
+
+<h2 id="inc-ex">PDK Inclusions and Exclusions</h2>
+<p>The PDK is a subset of the complete Android source tree and might be missing things that you might need. Here is a list of what the PDK supports
+ and does not support:</p>
+<ul>
+ <li>Supports building Android apps using the publicly available, standard SDK. Builds with non-public platform APIs are not supported. The JNI build is supported.</li>
+ <li>Supports only <code>en_US</code> locale.</li>
+ <li>Supports only phone layouts. Tablet layouts are not included.</li>
+ <li>Enables support for software navigation buttons by default, which you can disable by setting <code>qemu.jw.mainkeys=1</code>.</li>
+ <li>Builds all binaries with SMP (symmetric multiprocessing) features enabled. This might have a small performance impact on non-SMP CPUs.</li>
+ <li>Includes a minimal amount of Java libraries. Obtain any additional Java libraries from the publicly released Android source tree.</li>
+ <li>Contains a minimum number of applications. Build and install necessary applications as needed.</li>
+ <li>Does not support media streaming.</li>
+ <li>Does not include non-Latin fonts. (set by <code>MINIMAL_FONT_FOOTPRINT</code> variable in <code>BoardConfig.mk</code>).
+ An app might crash if it requires such fonts. </li>
+ <li>Does not support replacing framework resources by using the overlay mechanism.
+ This means all configurations controlled by framework resources are fixed.</li>
+ <li>Does not support NFC</li>
+ <li>Does not support DRM</li>
+</ul>
+
+<h2 id="knownissues">Support and Known Issues</h2>
+<p>
+For questions or to report issues related with the PDK, send a message to the <a href="https://groups.google.com/a/google.com/forum/?fromgroups#!forum/android-pdk-feedback">android-pdk@google.com</a> mailing list.</p>
+
+<p>The following list describes the known issues with the PDK:</p>
+<ul>
+ <li>After running the CTS (Compatibility Test Suite), <code>android.process.acore</code> crashes. This is caused by
+some missing components in PDK and does not affect the operation of CTS tests.</li>
+</p>