Merge "Update the Tech Storage doc for JB-MR2." into jb-mr2-dev
diff --git a/Android.mk b/Android.mk
index 481de01..df4cad8 100644
--- a/Android.mk
+++ b/Android.mk
@@ -6,8 +6,9 @@
LOCAL_DROIDDOC_HTML_DIR:=src
# Droiddoc needs java source to run. Just pointing to a dummy location
# and deleting output later in delete-ref target
-LOCAL_ADDITIONAL_JAVA_DIR:=frameworks/base/core/java/android/annotation
-LOCAL_DROIDDOC_CUSTOM_TEMPLATE_DIR:=build/tools/droiddoc/templates-sac
+LOCAL_ADDITIONAL_JAVA_DIR := frameworks/base/core/java/android/annotation
+# FIXME FIXME FIXME LOCAL_ADDITIONAL_DEPENDENCIES := tradefed-docs
+LOCAL_DROIDDOC_CUSTOM_TEMPLATE_DIR := build/tools/droiddoc/templates-sac
LOCAL_MODULE := online-sac
LOCAL_DROIDDOC_OPTIONS:= \
-toroot / \
@@ -31,3 +32,4 @@
$(hide) rm -rf $(OUT_DOCS)/online-sac/reference
$(hide) cp -R ../tradefed/out/target/common/docs/tradefed/reference $(OUT_DOCS)/online-sac
$(hide) cp ../tradefed/out/target/common/docs/tradefed/navtree_data.js $(OUT_DOCS)/online-sac/navtree_data.js
+
diff --git a/scripts/micro-httpd.py b/scripts/micro-httpd.py
index 1cffa08..2292abc 100755
--- a/scripts/micro-httpd.py
+++ b/scripts/micro-httpd.py
@@ -19,7 +19,7 @@
import os
-outdir = os.path.join(os.path.dirname(__file__), '..', 'out')
+outdir = os.environ.get('OUTDIR', os.path.join(os.path.dirname(__file__), '..', 'out'))
os.chdir(outdir)
PORT = int(os.environ.get('HTTP_PORT', 8080))
Handler = SimpleHTTPServer.SimpleHTTPRequestHandler
diff --git a/src/compatibility/contact-us.jd b/src/compatibility/contact-us.jd
index 3c9418c..72999e6 100644
--- a/src/compatibility/contact-us.jd
+++ b/src/compatibility/contact-us.jd
@@ -21,19 +21,20 @@
<p>If you have questions about Android compatibility that aren't covered in
this site, you can reach us in one of a few different ways. To get the most
out of any of these options, please first read "Getting the Most from Our
-Lists" on the <a href="index.html">Community page</a></p>
-<h2 id="for-general-discussion">For General Discussion</h2>
-<p>The preferred way to reach us is via the <a href="mailto:compatibility@android.com">compatibility@android.com</a> address.</p>
-<h2 id="for-cts-technical-questions">For CTS Technical Questions</h2>
-<p>If you have specific issues with the Compatibility Test Suite that require
-you to disclose information you'd prefer not to be public, you can contact an
-email address we've set up specifically this purpose: <a href="mailto:cts@android.com">cts@android.com</a>. This email address is for
-cases that require disclosure of confidential information only, so general
-questions will be directed back to the public android-compatibility
-list. Note also that this list is for specific technical questions; general
-inquiries will also be directed back to the <a href="https://groups.google.com/forum/?fromgroups#!forum/android-compatibility">android-compatibility list.</a></p>
+Lists" on the <a href="{/community/index.html">Community page</a></p>
+<h2 id="for-android-compatibility-definition-and-compatibility-test-suite-technical-questions">For Android Compatibility Definition and Compatibility Test Suite Technical Questions</h2>
+<p>If you have questions about Android compatibility that aren't covered in this site, you can reach
+us in one of a few different ways. To get the most out of any of these options, please first read "Getting the Most from Our
+Lists" on the <a href="/community/index.html">Community page</a>. If you have specific issues with the Compatibility Test Suite or the Compatibility Definition
+<a href="https://groups.google.com/forum/?fromgroups#!forum/android-compatibility">android-compatibility list.</a> is the discussion forum for you.</p>
+<ul>
+<li>Subscribe using Google Groups: <a href="https://groups.google.com/forum/?fromgroups#!forum/android-compatibility">android-compatibility</a></li>
+<li>Subscribe via email: <a href="mailto:android-compatibility+subscribe@googlegroups.com">android-compatibility</a></li>
+</ul>
+<p>Note that if you're a user looking for help with your Android device, this page probably isn't for you;
+you should contact your carrier or manufacturer for help with your Android device.</p>
<h2 id="for-business-inquiries">For Business Inquiries</h2>
<p>Finally, business inquiries about the compatibility program, including
requests to use branding elements and so on, can be sent to the address <a href="mailto:android-partnerships@google.com">android-partnerships@google.com</a>. Like
the CTS address, this address is for specific, private inquiries; general
-questions will be directed back to the android-compatibility list.</p>
+questions will be directed back to the android-compatibility list.</p>
\ No newline at end of file
diff --git a/src/compatibility/downloads.jd b/src/compatibility/downloads.jd
index 1e5c3e6..7cbf466 100644
--- a/src/compatibility/downloads.jd
+++ b/src/compatibility/downloads.jd
@@ -19,14 +19,17 @@
<p>Thanks for your interest in Android Compatibility! The links below allow
you to access the key documents and information.</p>
+<p>Thanks for your interest in Android Compatibility! The links below allow
+you to access the key documents and information.</p>
+
<h2 id="android-42">Android 4.2</h2>
<p>Android 4.2 is the release of the development milestone code-named
Jelly Bean-MR1. Android 4.2 is the current version of Android. Source code for
-Android 4.2 is found in the 'android-4.2_r1' branch in the open-source tree.</p>
+Android 4.2 is found in the 'android-4.2.2_r1' branch in the open-source tree.</p>
<ul>
<li><a href="4.2/android-4.2-cdd.pdf">Android 4.2 Compatibility Definition Document (CDD)</a></li>
-<li><a href="https://dl.google.com/dl/android/cts/android-cts-4.2_r1-linux_x86-arm.zip">Android 4.2 R1 Compatibility Test Suite (CTS)</a></li>
-<li><a href="https://dl.google.com/dl/android/cts/android-cts-verifier-4.2_r1-linux_x86-arm.zip">Android 4.2 R1 CTS Verifier</a></li>
+<li><a href="https://dl.google.com/dl/android/cts/android-cts-4.2_r4-linux_x86-arm.zip">Android 4.2 R4 Compatibility Test Suite (CTS)</a></li>
+<li><a href="https://dl.google.com/dl/android/cts/android-cts-verifier-4.2_r5-linux_x86-arm.zip">Android 4.2 R5 CTS Verifier</a></li>
</ul>
<h2 id="android-41">Android 4.1</h2>
<p>Android 4.1.1 is the release of the development milestone code-named
@@ -34,8 +37,8 @@
Android 4.1.1 is found in the 'android-4.1.1_r1' branch in the open-source tree.</p>
<ul>
<li><a href="4.1/android-4.1-cdd.pdf">Android 4.1 Compatibility Definition Document (CDD)</a></li>
-<li><a href="https://dl.google.com/dl/android/cts/android-cts-4.1_r1-linux_x86-arm.zip">Android 4.1 R1 Compatibility Test Suite (CTS)</a></li>
-<li><a href="https://dl.google.com/dl/android/cts/android-cts-verifier-4.1_r2-linux_x86-arm.zip">Android 4.1 R2 CTS Verifier</a></li>
+<li><a href="https://dl.google.com/dl/android/cts/android-cts-4.1_r3-linux_x86-arm.zip">Android 4.1 R3 Compatibility Test Suite (CTS)</a></li>
+<li><a href="https://dl.google.com/dl/android/cts/android-cts-verifier-4.1_r6-linux_x86-arm.zip">Android 4.1 R6 CTS Verifier</a></li>
</ul>
<h2 id="android-403">Android 4.0.3</h2>
<p>Android 4.0.3 is the release of the development milestone code-named
@@ -94,4 +97,4 @@
<h2 id="older-android-versions">Older Android Versions</h2>
<p>There is no Compatibility Program for older versions of Android, such as Android
1.5 (known in development as Cupcake). New devices intended to be Android
-compatible must ship with Android 1.6 or later.</p>
+compatible must ship with Android 1.6 or later.</p>
\ No newline at end of file
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index 7138177..c66d891 100644
--- a/src/devices/devices_toc.cs
+++ b/src/devices/devices_toc.cs
@@ -143,13 +143,20 @@
<span class="en">Power</span>
</a>
</li>
-
- <li>
- <a href="<?cs var:toroot ?>devices/tech/security/index.html">
- <span class="en">Security</span>
- </a>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>devices/tech/security/index.html">
+ <span class="en">Input</span>
+ </a>
+ </div>
+ <ul>
+ <li>
+ <a href="<?cs var:toroot ?>devices/tech/security/enhancements.html">
+ <span class="en">Security Enhancements in Android 4.2</span>
+ </a>
+ </li>
+ </ul>
</li>
-
<li class="nav-section">
@@ -159,9 +166,19 @@
</a>
</div>
<ul>
- <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/tutorial.html">Tutorial</a></li>
- <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/commandfile_format.html">Command File Format</a></li>
- <li id="tradefed-tree-list" class="nav-section">
+ <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/index.html"
+ >Start Here</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/machine_setup.html"
+ >Machine Setup</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/devices.html"
+ >Working with Devices</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/lifecycle.html"
+ >Test Lifecycle</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/fundamentals/options.html"
+ >Option Handling</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/test_infra/tradefed/full_example.html"
+ >An End-to-End Example</a></li>
+ <li id="tradefed-tree-list" class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>reference/packages.html">
<span class="en">Reference</span>
@@ -174,4 +191,4 @@
</ul>
</li>
-</ul>
\ No newline at end of file
+</ul>
diff --git a/src/devices/tech/input/key-layout-files.jd b/src/devices/tech/input/key-layout-files.jd
index be5936e..e925881 100644
--- a/src/devices/tech/input/key-layout-files.jd
+++ b/src/devices/tech/input/key-layout-files.jd
@@ -52,10 +52,16 @@
and flags.</p>
<h3 id="key-declarations">Key Declarations</h3>
<p>Key declarations each consist of the keyword <code>key</code> followed by a Linux key code
-number, an Android key code name, and optional set of whitespace delimited policy flags.</p>
-<pre><code>key 1 ESCAPE
+number and an Android key code name, or the keyword `usage` followed by a HID
+usage and an Android key code name. The HID usage is represented as a 32-bit
+integer, where the high 16-bits represent the HID usage page and the low
+16-bits represent the HID usage ID. Either of these declarations can then be
+followed by an optional set of whitespace delimited policy flags.</p>
+<pre><code>
+key 1 ESCAPE
key 114 VOLUME_DOWN WAKE
key 16 Q VIRTUAL WAKE
+key usage 0x0c006F BRIGHTNESS_UP
</code></pre>
<p>The following policy flags are recognized:</p>
<ul>
diff --git a/src/devices/tech/security/enhancements.jd b/src/devices/tech/security/enhancements.jd
new file mode 100644
index 0000000..4044a1e
--- /dev/null
+++ b/src/devices/tech/security/enhancements.jd
@@ -0,0 +1,60 @@
+page.title=Security Enhancements in Android 4.2
+@jd:body
+
+<p>
+Android provides a multi-layered security model described in the <a href="{@docRoot}devices/tech/security/index.html">Android
+Security Overview</a>. Each update to Android includes dozens of
+security enhancements to protect users. The following are some of the security
+enhancements introduced in Android 4.2:</p>
+
+<ul>
+<li><strong>Application verification</strong> - Users can choose to enable “Verify Apps" and
+have applications screened by an application verifier, prior to installation.
+App verification can alert the user if they try to install an app that might be
+harmful; if an application is especially bad, it can block installation.</li>
+<li><strong>More control of premium SMS</strong> - Android will provide a notification if an
+application attempts to send SMS to a short code that uses premium services
+which might cause additional charges. The user can choose whether to allow the
+application to send the message or block it.</li>
+
+<li><strong>Always-on VPN</strong> - VPN can be configured so that applications will not have
+access to the network until a VPN connection is established. This prevents
+applications from sending data across other networks.</li>
+
+<li><strong>Certificate Pinning</strong> - The Android core libraries now support
+<a href="https://developer.android.com/reference/android/net/http/X509TrustManagerExtensions.html">certificate pinning</a>.
+Pinned domains will receive a certificate validation
+failure if the certificate does not chain to a set of expected certificates.
+This protects against possible compromise of Certificate Authorities.</li>
+
+<li><strong>Improved display of Android permissions</strong> - Permissions have been organized
+into groups that are more easily understood by users. During review of the
+permissions, the user can click on the permission to see more detailed
+information about the permission.</li>
+
+<li><strong>installd hardening</strong> - The <code>installd</code> daemon does not run as the root user,
+reducing potential attack surface for root privilege escalation.</li>
+
+<li><strong>init script hardening</strong> - init scripts now apply <code>O_NOFOLLOW</code> semantics to
+prevent symlink related attacks.</li>
+
+<li><strong>FORTIFY_SOURCE</strong> - Android now implements <code>FORTIFY_SOURCE</code>. This is used by
+system libraries and applications to prevent memory corruption.</li>
+
+<li><strong>ContentProvider default configuration</strong> - Applications which target API
+level 17 will have "export" set to "false" by default for each
+<a href="https://developer.android.com/reference/android/content/ContentProvider.html">Content
+Provider</a>, reducing default attack surface for applications.</li>
+
+<li><strong>Cryptography</strong> - Modified the default implementations of SecureRandom and
+Cipher.RSA to use OpenSSL. Added SSL Socket support for TLSv1.1 and TLSv1.2
+using OpenSSL 1.0.1</li>
+
+<li><strong>Security Fixes</strong> - Upgraded open source libraries with security fixes include
+WebKit, libpng, OpenSSL, and LibXML. Android 4.2 also includes fixes for
+Android-specific vulnerabilities. Information about these vulnerabilities has
+been provided to Open Handset Alliance members and fixes are available in
+Android Open Source Project. To improve security, some devices with earlier
+versions of Android may also include these fixes.</li>
+
+</ul>
\ No newline at end of file
diff --git a/src/devices/tech/security/index.jd b/src/devices/tech/security/index.jd
index 8c5a864..5a79598 100644
--- a/src/devices/tech/security/index.jd
+++ b/src/devices/tech/security/index.jd
@@ -16,6 +16,7 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
+
<h2 id="introduction">Introduction</h2>
<p>Android is a modern mobile platform that was designed to be truly open. Android
applications make use of advanced hardware and software, as well as local and
@@ -23,14 +24,17 @@
consumers. To protect that value, the platform must offer an application
environment that ensures the security of users, data, applications, the device,
and the network.</p>
+
<p>Securing an open platform requires a robust security architecture and rigorous
security programs. Android was designed with multi-layered security that
provides the flexibility required for an open platform, while providing
protection for all users of the platform.</p>
+
<p>Android was designed with developers in mind. Security controls were designed
to reduce the burden on developers. Security-savvy developers can easily work
with and rely on flexible security controls. Developers less familiar with
security will be protected by safe defaults.</p>
+
<p>Android was designed with device users in mind. Users are provided visibility
into how applications work, and control over those applications. This design
includes the expectation that attackers would attempt to perform common
@@ -38,6 +42,7 @@
malware, and attacks on third-party applications on Android. Android was
designed to both reduce the probability of these attacks and greatly limit the
impact of the attack in the event it was successful.</p>
+
<p>This document outlines the goals of the Android security program, describes the
fundamentals of the Android security architecture, and answers the most
pertinent questions for system architects and security analysts. This document
@@ -46,6 +51,7 @@
related to the browser or SMS application. Recommended best practices for
building Android devices, deploying Android devices, or developing applications
for Android are not the goal of this document and are provided elsewhere.</p>
+
<h1 id="background">Background</h1>
<p>Android provides an open source platform and application environment for mobile
devices.</p>
@@ -99,8 +105,7 @@
device or the web. Google Play makes it easy for developers to reach Android
users and potential customers. Google Play also provides community review,
application <a href="https://developer.android.com/guide/publishing/licensing.html">license
-verification</a>,
-and other security services.</p>
+verification</a>, application security scanning, and other security services.</p>
</li>
<li>
<p><strong>Android Updates</strong>: The Android update service delivers new capabilities and
@@ -218,6 +223,7 @@
<li>Ensures that user A does not exhaust user B's devices (e.g. telephony, GPS,
bluetooth)</li>
</ul>
+
<h2 id="the-application-sandbox">The Application Sandbox</h2>
<p>The Android platform takes advantage of the Linux user-based protection as a
means of identifying and isolating application resources. The Android system
@@ -259,18 +265,131 @@
partition is set to read-only. When a user boots the device into Safe Mode,
only core Android applications are available. This ensures that the user can
boot their phone into an environment that is free of third-party software.</p>
+
<h2 id="filesystem-permissions">Filesystem Permissions</h2>
<p>In a UNIX-style environment, filesystem permissions ensure that one user cannot
alter or read another user's files. In the case of Android, each application
runs as its own user. Unless the developer explicitly exposes files to other
applications, files created by one application cannot be read or altered by
another application.</p>
-<h2 id="filesystem-encryption">Filesystem Encryption</h2>
+
+
+<h2 id="crypto">Cryptography</h2>
+
+<p>
+Android provides a set of cryptographic APIs for use by applications. These
+include implementations of standard and commonly used cryptographic primitives
+such as AES, RSA, DSA, and SHA. Additionally, APIs are provided for higher level
+protocols such as SSL and HTTPS.
+</p>
+
+<p>
+Android 4.0 introduced the
+<a href="http://developer.android.com/reference/android/security/KeyChain.html">KeyChain</a>
+class to allow applications to use the system credential storage for private
+keys and certificate chains.
+</p>
+
+<h2>Memory Management Security Enhancements</h2>
+
+Android includes many features that make common security issues harder to
+exploit. The Android SDK, compilers, and OS use tools to make common memory
+corruption issues significantly harder to exploit, including:
+
+<dl>
+<dt><strong>Android 1.5</strong></dt>
+<dd><ul>
+<li>ProPolice to prevent stack buffer overruns (-fstack-protector)</li>
+<li>safe_iop to reduce integer overflows</li>
+<li>Extensions to OpenBSD dlmalloc to prevent double free() vulnerabilities and
+to prevent chunk consolidation attacks. Chunk consolidation attacks are a
+common way to exploit heap corruption.</li>
+<li>OpenBSD calloc to prevent integer overflows during memory allocation</li>
+</ul>
+</dd>
+
+<dt><strong>Android 2.3</strong></dt>
+<dd><ul>
+<li>Format string vulnerability protections (-Wformat-security -Werror=format-security)</li>
+<li>Hardware-based No eXecute (NX) to prevent code execution on the stack and heap</li>
+<li>Linux mmap_min_addr to mitigate null pointer dereference privilege
+escalation (further enhanced in Android 4.1)</li>
+</ul>
+</dd>
+
+<dt><strong>Android 4.0</strong></dt>
+<dd>Address Space Layout Randomization (ASLR) to randomize key locations in memory
+</dd>
+
+<dt><strong>Android 4.1</strong></dt>
+<dd><ul>
+<li>PIE (Position Independent Executable) support</li>
+<li>Read-only relocations / immediate binding (-Wl,-z,relro -Wl,-z,now)</li>
+<li>dmesg_restrict enabled (avoid leaking kernel addresses)</li>
+<li>kptr_restrict enabled (avoid leaking kernel addresses)</li>
+</ul>
+</dd>
+
+<dt><strong>Android 4.2</strong></dt>
+<dd><code>FORTIFY_SOURCE</code> for system code</dd>
+
+</dl>
+
+<h2>Rooting of Devices</h2>
+<p>
+By default, on Android only the kernel and a small subset of the core
+applications run with root permissions. Android does not prevent a user or
+application with root permissions from modifying the operating system, kernel,
+and any other application. In general, root has full access to all
+applications and all application data. Users that change the permissions on an
+Android device to grant root access to applications increase the security
+exposure to malicious applications and potential application flaws.
+</p>
+<p>
+The ability to modify an Android device they own is important to developers
+working with the Android platform. On many Android devices users have the
+ability to unlock the bootloader in order to allow installation of an alternate
+operating system. These alternate operating systems may allow an owner to gain
+root access for purposes of debugging applications and system components or to
+access features not presented to applications by Android APIs.
+</p>
+<p>
+On some devices, a person with physical control of a device and a USB cable is
+able to install a new operating system that provides root privileges to the
+user. To protect any existing user data from compromise the bootloader unlock
+mechanism requires that the bootloader erase any existing user data as part of
+the unlock step. Root access gained via exploiting a kernel bug or security
+hole can bypass this protection.
+</p>
+<p>
+Encrypting data with a key stored on-device does not protect the application
+data from root users. Applications can add a layer of data protection using
+encryption with a key stored off-device, such as on a server or a user
+password. This approach can provide temporary protection while the key is not
+present, but at some point the key must be provided to the application and it
+then becomes accessible to root users.
+</p>
+<p>
+A more robust approach to protecting data from root users is through the use of
+hardware solutions. OEMs may choose to implement hardware solutions that limit
+access to specific types of content such as DRM for video playback, or the
+NFC-related trusted storage for Google wallet.
+</p>
+<p>
+In the case of a lost or stolen device, full filesystem encryption on Android
+devices uses the device password to protect the encryption key, so modifying
+the bootloader or operating system is not sufficient to access user data
+without the user’s device password.
+</p>
+<h2>User Security Features</h2>
+
+<h3 id="filesystem-encryption">Filesystem Encryption</h3>
+
<p>Android 3.0 and later provides full filesystem encryption, so all user data can
be encrypted in the kernel using the dmcrypt implementation of AES128 with CBC
-and ESSIV:SHA256. The encryption key is protected by AES128 using a key
+and ESSIV:SHA256. The encryption key is protected by AES128 using a key
derived from the user password, preventing unauthorized access to stored data
-without the user device password. To provide resistance against systematic
+without the user device password. To provide resistance against systematic
password guessing attacks (e.g. “rainbow tables” or brute force), the
password is combined with a random salt and hashed repeatedly with SHA1 using
the standard PBKDF2 algorithm prior to being used to decrypt the filesystem
@@ -279,14 +398,15 @@
administrator and enforced by the operating system. Filesystem encryption
requires the use of a user password, pattern-based screen lock is not supported.</p>
<p>More details on implementation of filesystem encryption are available at
-<a href="/
-tech/encryption/android_crypto_implementation.html">https://source.android.com/tech/encryption/android_crypto_implementation.html</a></p>
+<a href="/tech/encryption/android_crypto_implementation.html">https://source.android.com/tech/encryption/android_crypto_implementation.html</a></p>
+
<h2 id="password-protection">Password Protection</h2>
<p>Android can be configured to verify a user-supplied password prior to providing
access to a device. In addition to preventing unauthorized use of the device,
this password protects the cryptographic key for full filesystem encryption.</p>
<p>Use of a password and/or password complexity rules can be required by a device
administrator.</p>
+
<h2 id="device-administration">Device Administration</h2>
<p>Android 2.2 and later provide the Android Device Administration API, which
provides device administration features at the system level. For example, the
@@ -300,71 +420,7 @@
on the API are provided here:
<a href="https://devel
oper.android.com/guide/topics/admin/device-admin.html">https://developer.android.com/guide/topics/admin/device-admin.html</a>.</p>
-<h2 id="memory-management-security-enhancements">Memory Management Security Enhancements</h2>
-<p>Android includes many features that make common security issues harder to
-exploit. The Android SDK, compilers, and OS use tools to make common memory
-corruption issues significantly harder to exploit, including:</p>
-<p><strong>Android 1.5+</strong></p>
-<ul>
-<li>ProPolice to prevent stack buffer overruns (-fstack-protector)</li>
-<li>safe_iop to reduce integer overflows</li>
-<li>Extensions to OpenBSD dlmalloc to prevent double free() vulnerabilities and
-to prevent chunk consolidation attacks. Chunk consolidation attacks are a
-common way to exploit heap corruption.</li>
-<li>OpenBSD calloc to prevent integer overflows during memory allocation</li>
-</ul>
-<p><strong>Android 2.3+</strong></p>
-<ul>
-<li>Format string vulnerability protections (-Wformat-security -Werror=format-security)</li>
-<li>Hardware-based No eXecute (NX) to prevent code execution on the stack and heap</li>
-<li>Linux mmap_min_addr to mitigate null pointer dereference privilege
-escalation (further enhanced in Android 4.1)</li>
-</ul>
-<p><strong>Android 4.0+</strong></p>
-<ul>
-<li>Address Space Layout Randomization (ASLR) to randomize key locations in memory</li>
-</ul>
-<p><strong>Android 4.1+</strong></p>
-<ul>
-<li>PIE (Position Independent Executable) support</li>
-<li>Read-only relocations / immediate binding (-Wl,-z,relro -Wl,-z,now)</li>
-<li>dmesg_restrict enabled (avoid leaking kernel addresses)</li>
-<li>kptr_restrict enabled (avoid leaking kernel addresses)</li>
-</ul>
-<h2 id="rooting-of-devices">Rooting of Devices</h2>
-<p>By default, on Android only the kernel and a small subset of the core
-applications run with root permissions. Android does not prevent a user or
-application with root permissions from modifying the operating system, kernel,
-and any other application. In general, root has full access to all
-applications and all application data. Users that change the permissions on an
-Android device to grant root access to applications increase the security
-exposure to malicious applications and potential application flaws.</p>
-<p>The ability to modify an Android device they own is important to developers
-working with the Android platform. On many Android devices users have the
-ability to unlock the bootloader in order to allow installation of an alternate
-operating system. These alternate operating systems may allow an owner to gain
-root access for purposes of debugging applications and system components or to
-access features not presented to applications by Android APIs.</p>
-<p>On some devices, a person with physical control of a device and a USB cable is
-able to install a new operating system that provides root privileges to the
-user. To protect any existing user data from compromise the bootloader unlock
-mechanism requires that the bootloader erase any existing user data as part of
-the unlock step. Root access gained via exploiting a kernel bug or security
-hole can bypass this protection.</p>
-<p>Encrypting data with a key stored on-device does not protect the application
-data from root users. Applications can add a layer of data protection using
-encryption with a key stored off-device, such as on a server or a user
-password. This approach can provide temporary protection while the key is not
-present, but at some point the key must be provided to the application and it
-then becomes accessible to root users.</p>
-<p>A more robust approach to protecting data from root users is through the use of
-hardware solutions. OEMs may choose to implement hardware solutions that limit
-access to specific types of content such as DRM for video playback, or the
-NFC-related trusted storage for Google wallet.</p>
-<p>In the case of a lost or stolen device, full filesystem encryption on Android
-devices uses the device password to protect the encryption key, so modifying
-the bootloader or operating system is not sufficient to access user data
-without the user’s device password.</p>
+
<h1 id="android-application-security">Android Application Security</h1>
<h2 id="elements-of-applications">Elements of Applications</h2>
<p>Android provides an open source platform and application environment for mobile
@@ -412,8 +468,10 @@
behavior based on that information.</p>
</li>
</ul>
+
<h2 id="the-android-permission-model-accessing-protected-apis">The Android Permission Model: Accessing Protected APIs</h2>
-<p>By default, an Android application can only access a limited range of system
+<p>All applications on Android run in an Application Sandbox, described earlier in this document.
+By default, an Android application can only access a limited range of system
resources. The system manages Android application access to resources that, if
used incorrectly or maliciously, could adversely impact the user experience,
the network, or data on the device.</p>
@@ -578,6 +636,13 @@
<li>In-App Billing</li>
<li>NFC Access</li>
</ul>
+
+<p> Android 4.2 adds further control on the use of SMS. Android will provide a
+notification if an application attempts to send SMS to a short code that uses
+premium services which might cause additional charges. The user can choose
+whether to allow the application to send the message or block it.
+</p>
+
<h2 id="sim-card-access">SIM Card Access</h2>
<p>Low level access to the SIM card is not available to third-party apps. The OS
handles all communications with the SIM card including access to personal
@@ -661,10 +726,20 @@
<p>Applications are also able to declare security permissions at the Signature
protection level, restricting access only to applications signed with the same
key while maintaining distinct UIDs and Application Sandboxes. A closer
-relationship with a shared Application Sandbox is allowed via the <a href="https://developer.android.com/guide/topics/manifest/manifest-element.html#uid">shared UID
-feature</a>
-where two or more applications signed with same developer key can
+relationship with a shared Application Sandbox is allowed via the
+<a href="https://developer.android.com/guide/topics/manifest/manifest-element.html#uid">shared UID
+feature</a> where two or more applications signed with same developer key can
declare a shared UID in their manifest.</p>
+
+<h2 id="app-verification">Application Verification</h2>
+<p>
+Android 4.2 and later support application verification. Users can choose to
+enable “Verify Apps" and have applications evaluated by an application verifier
+prior to installation. App verification can alert the user if they try to
+install an app that might be harmful; if an application is especially bad, it
+can block installation.
+</p>
+
<h2 id="digital-rights-management">Digital Rights Management</h2>
<p>The Android platform provides an extensible DRM framework that lets
applications manage rights-protected content according to the license
diff --git a/src/devices/tech/test_infra/tradefed/commandfile_format.jd b/src/devices/tech/test_infra/tradefed/commandfile_format.jd
deleted file mode 100644
index cd5102a..0000000
--- a/src/devices/tech/test_infra/tradefed/commandfile_format.jd
+++ /dev/null
@@ -1,121 +0,0 @@
-page.title=Command File Format
-@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.
--->
-<p>A command file allows one to specify sets of TF commands (that is, configurations with their
-associated arguments) to be specified all at once. Further, the format used in the command file
-supports simple macro expansions, which makes it very useful without being unwieldy. You can see a
-relatively involved example at the bottom of the page, as well as more gradual documentation
-immediately below.</p>
-<h2 id="lines">Lines</h2>
-<p>The format is line-based.</p>
-<ul>
-<li>Each output line will be considered as the arguments for a single Configuration for Trade
- Federation to run.</li>
-<li>Each input line will turn into one or more output lines.</li>
-</ul>
-<p>In essence, the command file format combinatorially creates a sequence of Configuration specifications that it passes to Trade Federation to run. Blank lines are ignored. Comments are delimited by the "#" character and may only be preceded by whitespace.</p>
-<h2 id="macros">Macros</h2>
-<p>The specific syntax for defining a macro is discussed below in the Short Macro and Long Macro sections. The following rules apply to all macros</p>
-<ul>
-<li>The name of a macro must begin with an alpha character. Each subsequent character may be any
- alphanumeric, an underscore, or a hyphen.</li>
-<li>A macro with name "macro_name" is invoked by adding macro_name() as an argument on some subsequent
- line.</li>
-<li>The macro format does not support passing arguments to macros. It allows only concatenation.</li>
-<li>A macro's expansion may contain invocations of other macros. Technically, a macro's expansion may
- contain invocations of itself, but in that case, the macro will never fully expand.</li>
-<li>The parser currently has a hard limit of 10 iterations of expansion. This will be made
- configurable at some point.</li>
-<li>During a single iteration of expansion:<ul>
-<li>All short macro invocations on a line will be expanded a single level — macro invocations
- embedded within the first-level expansions will not be expanded yet</li>
-<li>Only one long macro invocation on a line will be expanded. This will be the left-most long
- macro invocation.</li>
-</ul>
-</li>
-</ul>
-<h2 id="short-macros">Short Macros</h2>
-<p>A short macro can be defined with the syntax:</p>
-<pre><code>MACRO macro_name = this is the macro expansion
-</code></pre>
-<p>The macro expansion terminates at the end of the line. For multi-line expansion, see Long Macros
-below.</p>
-<h3 id="short-macro-expansion">Short Macro Expansion</h3>
-<ul>
-<li><code>a macro_name() invocation</code><br />
- will be replaced by<br />
- <code>a this is the macro expansion invocation</code></li>
-<li><code>three macro_name() A macro_name() B macro_name()</code><br />
- will be replaced by (all during the first iteration)<br />
- <code>three this is the macro expansion A this is the macro expansion B this is the macro expansion</code></li>
-</ul>
-<h2 id="long-macros">Long Macros</h2>
-<p>A long macro can be defined with the syntax:</p>
-<pre><code>LONG MACRO macro_name
- expansion line 1
- expansion line 2
- expansion line 3
-END MACRO
-</code></pre>
-<p>The macro is then invoked with th enormal <code>macro_name()</code> syntax. Leading whitespace/indentation
-will be ignored.</p>
-<h3 id="long-macro-expansion">Long Macro Expansion</h3>
-<p>The output of a single input line will include one line for each combination of macro expansions on
-that line. That is, the number of output lines is multiplicatively related to the number of macro
-expansions on that line:</p>
-<ul>
-<li>Only a single long macro invocation per line will be expanded during a single iteration. This
- means that a line may only contain 10 long macro invocations to stay under the iteration count
- limit.</li>
-<li>
-<p>A single invocation of a long macro on a single line will cause that line to expand to the number
- of lines of the long macro's expansion. On each expanded line, the invocation will be replaced
- by the corresponding line of the macro's expansion.</p>
-</li>
-<li>
-<p>Example 1:</p>
-<pre><code>a macro_name() invocation
-</code></pre>
-<p>will be replaced by (in a single iteration)</p>
-<pre><code>a expansion line 1 invocation
-a expansion line 2 invocation
-a expansion line 3 invocation
-</code></pre>
-</li>
-<li>
-<p>Example 2:</p>
-<pre><code>alpha macro_name() beta macro_name()
-</code></pre>
-<p>will be replaced by (during the first iteration)</p>
-<pre><code>alpha expansion line 1 beta macro_name()
-alpha expansion line 2 beta macro_name()
-alpha expansion line 3 beta macro_name()
-</code></pre>
-<p>which will be replaced by (during the second iteration)</p>
-<pre><code>alpha expansion line 1 beta expansion line 1
-alpha expansion line 1 beta expansion line 2
-alpha expansion line 1 beta expansion line 3
-alpha expansion line 2 beta expansion line 1
-alpha expansion line 2 beta expansion line 2
-alpha expansion line 2 beta expansion line 3
-alpha expansion line 3 beta expansion line 1
-alpha expansion line 3 beta expansion line 2
-alpha expansion line 3 beta expansion line 3
-</code></pre>
-</li>
-</ul>
diff --git a/src/devices/tech/test_infra/tradefed/full_example.jd b/src/devices/tech/test_infra/tradefed/full_example.jd
new file mode 100644
index 0000000..9733d77
--- /dev/null
+++ b/src/devices/tech/test_infra/tradefed/full_example.jd
@@ -0,0 +1,440 @@
+page.title=End-to-End Test Example
+@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.
+-->
+
+<p>This tutorial guides you through the construction of a "hello world" Trade Federation test
+configuration, and gives you a hands-on introduction to the Trade Federation framework. Starting
+from the TF development environment, it guides you through the process of creating a simple Trade
+Federation config and gradually adding more features to it.</p>
+
+<p>The tutorial presents the TF test development process as a set of exercises, each consisting of
+several steps. The exercises demonstrate how to gradually build and refine your configuration, and
+provide all the sample code you need to complete the test configuration. The title of each
+exercise is annotated with a letter describing which roles are involved in that step: <b>D</b> for
+Developer, <b>I</b> for Integrator, and/or <b>R</b> for Test Runner.</p>
+
+<p>When you are finished with the tutorial, you will have created a functioning TF configuration and
+will have learned many of the most important concepts in the TF framework.</p>
+
+<h2>Set up TradeFederation development environment</h2>
+<p>See the <a href="/devices/tech/test_infra/tradefed/fundamentals/machine_setup.html"
+>Machine Setup</a> page for how to setup the development environment. The rest of this tutorial
+assumes you have a shell open that has been initialized to the Trade Federation environment.</p>
+
+<p>For simplicity, this tutorial will illustrate adding a configuration and its classes to the
+Trade Federation framework core library. This can be extended to developing modules outside the
+source tree by simply compiling the tradefed JAR, and compiling your modules against that JAR.</p>
+
+<h2>Creating a test class (D)</h2>
+<p>Lets create a hello world test that just dumps a message to stdout. A tradefed test will
+generally implement the <a href="/reference/com/android/tradefed/testtype/IRemoteTest.html"
+>IRemoteTest</a> interface.</p>
+
+<p>Here's an implementation for the HelloWorldTest:</p>
+<pre><code>package com.android.tradefed.example;
+
+import com.android.tradefed.device.DeviceNotAvailableException;
+import com.android.tradefed.result.ITestInvocationListener;
+import com.android.tradefed.testtype.IRemoteTest;
+
+public class HelloWorldTest implements IRemoteTest {
+ @Override
+ public void run(ITestInvocationListener listener) throws DeviceNotAvailableException {
+ System.out.println("Hello, TF World!");
+ }
+}
+</code></pre>
+
+<p>Save this sample code to
+<code><tree>/tools/tradefederation/prod-tests/src/com/android/tradefed/example/HelloWorldTest.java</code>
+and rebuild tradefed from your shell:</p>
+<pre><code>m -jN</code></pre>
+
+<p>If the build does not succeed, consult the
+<a href="/devices/tech/test_infra/tradefed/fundamentals/machine_setup.html">Machine Setup</a> page
+to ensure that you didn't miss any steps.</p>
+
+<h2>Creating a Configuration (I)</h2>
+<p>Trade Federation tests are made executable by creating a <b>Configuration</b>, which is an XML file
+that instructs tradefed on which test (or tests) to run, as well as which other modules to
+execute, and in what order.</p>
+
+<p>Lets create a new Configuration for our HelloWorldTest:</p>
+<pre><code><configuration description="Runs the hello world test">
+ <test class="com.android.tradefed.example.HelloWorldTest" />
+</configuration></code></pre>
+
+<p>TF will parse the Configuration XML file (aka <b>config</b>), load the specified class using
+reflection, instantiate it, cast it to a <code>IRemoteTest</code>, and call its <code>run</code>
+method.</p>
+
+<p>Note that we've specified the full class name of the HelloWorldTest. Save this data to a
+<code>helloworld.xml</code> file anywhere on your local filesystem (eg <code>/tmp/helloworld.xml</code>).</p>
+
+<h2>Running the config (R)</h2>
+<p>From your shell, launch the tradefed console</p>
+<pre><code>$ tradefed.sh
+</code></pre>
+
+<p>Ensure that a device is connected to the host machine and is visible to tradefed</p>
+<pre><code>tf >list devices
+Serial State Product Variant Build Battery
+004ad9880810a548 Available mako mako JDQ39 100
+</code></pre>
+
+<p>Configurations can be executed using the <code>run <config></code> console command. Try this:</p>
+<p>FIXME: redo this</p>
+<pre><code>tf> run /tmp/helloworld.xml
+05-12 13:19:36 I/TestInvocation: Starting invocation for target stub on build 0 on device 004ad9880810a548
+Hello, TF World!
+</code></pre>
+<p>You should see "Hello, TF World!" outputted on the terminal.</p>
+
+<h2>Adding the config to the Classpath (D, I, R)</h2>
+<p>For convenience of deployment, you can also bundle configs into the tradefed jars
+themselves. Tradefed will automatically recognize all configurations placed in 'config' folders on
+the classpath.</p>
+
+<p>Lets illustrate this now by moving the helloworld.xml into the tradefed core library.</p>
+<p>Move the <code>helloworld.xml</code> file into
+<code><tree>/tools/tradefederation/prod-tests/res/config/example/helloworld.xml</code>.</p>
+<p>Rebuild tradefed, and restart the tradefed console. </p>
+<p>Ask tradefed to display the list of configurations from the classpath:</p>
+<pre><code>tf> list configs
+[…]
+example/helloworld: Runs the hello world test
+</code></pre>
+
+<p>You can now run the helloworld config via the following command</p>
+<pre><code>tf >run example/helloworld
+05-12 13:21:21 I/TestInvocation: Starting invocation for target stub on build 0 on device 004ad9880810a548
+Hello, TF World!
+</code></pre>
+
+<h2>Interacting with a Device (D, R)</h2>
+<p>So far our hello world test isn't doing anything interesting. Tradefed's specialty is running
+tests using Android devices, so lets add an Android device to the test.</p>
+
+<p>Tests can get a reference to an Android device by implementing the
+<a href="/reference/com/android/tradefed/testtype/IDeviceTest.html">IDeviceTest</a> interface.</p>
+
+<p>Here's a sample implementation of what this looks like:</p>
+<pre><code>public class HelloWorldTest implements IRemoteTest, IDeviceTest {
+ private ITestDevice mDevice;
+ @Override
+ public void setDevice(ITestDevice device) {
+ mDevice = device;
+ }
+
+ @Override
+ public ITestDevice getDevice() {
+ return mDevice;
+ }
+…
+}
+</code></pre>
+
+<p>The Trade Federation framework will inject the <code>ITestDevice</code> reference into your
+test via the <code>IDeviceTest#setDevice</code> method, before the <code>IRemoteTest#run</code>
+method is called.</p>
+
+<p>Let's modify the HelloWorldTest print message to display the serial number of the device.</p>
+<pre><code>@Override
+public void run(ITestInvocationListener listener) throws DeviceNotAvailableException {
+ System.out.println("Hello, TF World! I have device " + getDevice().getSerialNumber());
+}
+</code></pre>
+
+<p>Now rebuild tradefed, and check the list of devices:</p>
+<pre><code>$ tradefed.sh
+tf >list devices
+Serial State Product Variant Build Battery
+004ad9880810a548 Available mako mako JDQ39 100
+</code></pre>
+
+<p>Take note of the serial number listed as Available above. That is the device that should be
+allocated to HelloWorld.</p>
+<pre><code>tf >run example/helloworld
+05-12 13:26:18 I/TestInvocation: Starting invocation for target stub on build 0 on device 004ad9880810a548
+Hello, TF World! I have device 004ad9880810a548
+</code></pre>
+
+<p>You should see the new print message displaying the serial number of the device.</p>
+
+<h2>Sending Test Results (D)</h2>
+<p><code>IRemoteTest</code>s report results by calling methods on the
+<a href="/reference/com/android/tradefed/result/ITestInvocationListener.html"
+>ITestInvocationListener</a> instance provided to their <code>#run</code> method. Note that the
+TF framework itself is responsible for reporting the start and end of each Invocation, (via
+the <a href="/reference/com/android/tradefed/result/ITestInvocationListener.html#invocationStarted(com.android.tradefed.build.IBuildInfo)"
+>ITestInvocationListener#invocationStarted</a> and
+<a href="/reference/com/android/tradefed/result/ITestInvocationListener.html#invocationEnded(long)"
+>ITestInvocationListener#invocationEnded</a> methods, respectively).</p>
+
+<p>A <b>test run</b> is a logical collection of tests. To report test results,
+<code>IRemoteTest</code>s are responsible
+for reporting the start of a test run, the start and end of each test, and the end of the test run.</p>
+
+<p>Here's what the HelloWorldTest implementation might look like with a single failed test result.</p>
+<pre><code>@Override
+public void run(ITestInvocationListener listener) throws DeviceNotAvailableException {
+ System.out.println("Hello, TF World! I have device " + getDevice().getSerialNumber());
+
+ TestIdentifier testId = new TestIdentifier("com.example.TestClassName", "sampleTest");
+ listener.testRunStarted("helloworldrun", 1);
+ listener.testStarted(testId);
+ listener.testFailed(TestFailure.FAILURE, testId, "oh noes, test failed");
+ listener.testEnded(testId, Collections.emptyMap());
+ listener.testRunEnded(0, Collections.emptyMap());
+}</code></pre>
+
+<p>Note that Trade Federation also includes several <code>IRemoteTest</code> implementations that
+you can reuse instead of writing your own from scratch. These include, for instance,
+<a href="/reference/com/android/tradefed/testtype/InstrumentationTest.html"
+>InstrumentationTest</a>, which can run an Android application's tests remotely on an Android
+device, parse the results, and forward them to the <code>ITestInvocationListener</code>). See the
+<a href="/reference/com/android/tradefed/testtype/package-summary.html">Test Types
+documentation</a> for more details.</p>
+
+<h2>Storing Test Results (I)</h2>
+<p>By default, a TF config will use the
+<a href="/reference/com/android/tradefed/result/TextResultReporter.html">TextResultReporter</a> as
+the test listener implementation. <code>TextResultReporter</code> will dump the results of an
+invocation to stdout. To illustrate, try running the hello-world config from the previous
+section:</p>
+<pre><code>$ ./tradefed.sh
+tf >run example/helloworld
+05-16 20:03:15 I/TestInvocation: Starting invocation for target stub on build 0 on device 004ad9880810a548
+Hello, TF World! I have device 004ad9880810a548
+05-16 20:03:15 I/InvocationToJUnitResultForwarder: run helloworldrun started: 1 tests
+Test FAILURE: com.example.TestClassName#sampleTest
+ stack: oh noes, test failed
+05-16 20:03:15 I/InvocationToJUnitResultForwarder: run ended 0 ms
+</code></pre>
+
+<p>If you want to store the results of an invocation elsewhere, such as in a file, you need to
+specify a custom <code>ITestInvocationListener</code> implementation by using the
+<code>result_reporter</code> tag in your configuration.</p>
+
+<p>Trade Federation includes the
+<a href="/reference/com/android/tradefed/result/XmlResultReporter.html">XmlResultReporter</a>
+listener, which will write test results to an XML file, in a format similar to that used by the
+<em>ant</em> JUnit XML writer.</p>
+
+<p>Let's specify the result_reporter in the configuration now. Edit the
+<code>…/res/config/example/helloworld.xml</code> config like this:</p>
+<pre><code><configuration description="Runs the hello world test">
+ <test class="com.android.tradefed.example.HelloWorldTest" />
+ <result_reporter class="com.android.tradefed.result.XmlResultReporter" />
+</configuration>
+</code></pre>
+
+<p>Now rebuild tradefed and re-run the hello world sample:</p>
+<pre><code>tf >run example/helloworld
+05-16 21:07:07 I/TestInvocation: Starting invocation for target stub on build 0 on device 004ad9880810a548
+Hello, TF World! I have device 004ad9880810a548
+05-16 21:07:07 I/XmlResultReporter: Saved device_logcat log to /tmp/0/inv_2991649128735283633/device_logcat_6999997036887173857.txt
+05-16 21:07:07 I/XmlResultReporter: Saved host_log log to /tmp/0/inv_2991649128735283633/host_log_6307746032218561704.txt
+05-16 21:07:07 I/XmlResultReporter: XML test result file generated at /tmp/0/inv_2991649128735283633/test_result_536358148261684076.xml. Total tests 1, Failed 1, Error 0
+</code></pre>
+
+<p>Notice the log message stating that an XML file has been generated. The generated file should look like this:</p>
+<pre><code><?xml version='1.0' encoding='UTF-8' ?>
+<testsuite name="stub" tests="1" failures="1" errors="0" time="9" timestamp="2011-05-17T04:07:07" hostname="localhost">
+ <properties />
+ <testcase name="sampleTest" classname="com.example.TestClassName" time="0">
+ <failure>oh noes, test failed
+ </failure>
+ </testcase>
+</testsuite>
+</code></pre>
+
+<p>You can also write your own custom invocation listeners. It just needs to implement the
+<a href="/reference/com/android/tradefed/result/ITestInvocationListener.html"
+>ITestInvocationListener</a> interface.</p>
+
+<p>Also note that tradefed supports multiple invocation listeners, meaning that you can send test
+results to multiple independent destinations. Just specify multiple
+<code><result_reporter></code> tags in your config to do this.</p>
+
+<h2>Logging (D, I, R)</h2>
+<p>TradeFederation includes two logging facilities:</p>
+<ol>
+<li>ability to capture logs from the device (aka device logcat)</li>
+<li>ability to record logs from the TradeFederation framework running on the host machine (aka the
+ host log)</li>
+</ol>
+<p>Lets focus on #2 for now. Trade Federation's host logs are reported using the
+<a href="/reference/com/android/tradefed/log/LogUtil.CLog.html">CLog wrapper</a> for the
+ddmlib Log class.</p>
+
+<p>Let's convert the previous <code>System.out.println</code> call in HelloWorldTest to a
+<code>CLog</code> call:</p>
+<pre><code>@Override
+public void run(ITestInvocationListener listener) throws DeviceNotAvailableException {
+ CLog.i("Hello, TF World! I have device %s", getDevice().getSerialNumber());
+</code></pre>
+
+<p>Note that <code>CLog</code> handles string interpolation directly, akin to
+<code>String.format</code>. At this point, when you rebuild and rerun TF, you should see the
+log message on stdout.</p>
+<pre><code>tf> run example/helloworld
+…
+05-16 21:30:46 I/HelloWorldTest: Hello, TF World! I have device 004ad9880810a548
+…
+</code></pre>
+
+<p>By default, tradefed will
+<a href"/reference/com/android/tradefed/log/StdoutLogger.html">output host log messages to
+stdout</a>. TF also includes a log implementation that will write messages to a file:
+<a href="/reference/com/android/tradefed/log/FileLogger.html">FileLogger</a>. To add file logging,
+add a <code>logger</code> tag to the config, specifying the full class name of
+<code>FileLogger</code>.</p>
+<pre><code><configuration description="Runs the hello world test">
+ <test class="com.android.tradefed.example.HelloWorldTest" />
+ <result_reporter class="com.android.tradefed.result.XmlResultReporter" />
+ <logger class="com.android.tradefed.log.FileLogger" />
+</configuration>
+</code></pre>
+
+<p>Now rebuild and run the helloworld example again.</p>
+<pre><code>tf >run example/helloworld
+…
+05-16 21:38:21 I/XmlResultReporter: Saved device_logcat log to /tmp/0/inv_6390011618174565918/device_logcat_1302097394309452308.txt
+05-16 21:38:21 I/XmlResultReporter: Saved host_log log to /tmp/0/inv_6390011618174565918/host_log_4255420317120216614.txt
+…
+</code></pre>
+<p>Note the log message indicating the path of the host log. View the contents of that file, and you
+should see your HelloWorldTest log message</p>
+<pre><code>$ more /tmp/0/inv_6390011618174565918/host_log_4255420317120216614.txt
+…
+05-16 21:38:21 I/HelloWorldTest: Hello, TF World! I have device 004ad9880810a548
+</code></pre>
+
+<p>The TradeFederation framework will also automatically capture the logcat from the allocated device,
+and send it the invocation listener for processing. <code>XmlResultReporter</code> will save the
+captured device logcat as a file.</p>
+
+<h2>Option Handling (D, I, R)</h2>
+<p>Objects loaded from a Trade Federation Configuration (aka <b>Configuration objects</b>) also have the
+ability to receive data from command line arguments.</p>
+<p>This is accomplished via the <code>@Option</code> annotation. To participate, a Configuration object class
+would apply the <code>@Option</code> annotation to a member field, and provide it a unique name. This would
+allow that member field's value to be populated via a command line option, and would also
+automatically add that option to the configuration help system (Note: not all field types are
+supported: see the
+<a href="/reference/com/android/tradefed/config/OptionSetter.html">OptionSetter javadoc</a> for a
+description of supported types).</p>
+
+<p>Let's add an <code>@Option</code> to the HelloWorldTest:</p>
+<pre><code>@Option(name="my_option",
+ shortName='m',
+ description="this is the option's help text",
+ // always display this option in the default help text
+ importance=Importance.ALWAYS)
+private String mMyOption = "thisisthedefault";
+</code></pre>
+
+<p>And let's add a log message to display the value of the option in HelloWorldTest, so we can
+demonstrate that it was received correctly.</p>
+<pre><code>@Override
+public void run(ITestInvocationListener listener) throws DeviceNotAvailableException {
+ …
+ CLog.logAndDisplay(LogLevel.INFO, "I received option '%s'", mMyOption);
+</code></pre>
+
+<p>Rebuild TF and run helloworld; you should see a log message with <code>my_option</code>'s
+default value.</p>
+<pre><code>tf> run example/helloworld
+…
+05-24 18:30:05 I/HelloWorldTest: I received option 'thisisthedefault'
+</code></pre>
+
+<h3>Passing Values from the Command Line</h3>
+<p>Now pass in a value for my_option: you should see my_option getting populated with that value</p>
+<pre><code>tf> run example/helloworld --my_option foo
+…
+05-24 18:33:44 I/HelloWorldTest: I received option 'foo'
+</code></pre>
+
+<p>TF configurations also include a help system, which automatically displays help text for
+<code>@Option</code> fields. Try it now, and you should see the help text for
+<code>my_option</code>:</p>
+<pre><code>tf> run --help example/helloworld
+Printing help for only the important options. To see help for all options, use the --help-all flag
+
+ cmd_options options:
+ --[no-]help display the help text for the most important/critical options. Default: false.
+ --[no-]help-all display the full help text for all options. Default: false.
+ --[no-]loop keep running continuously. Default: false.
+
+ test options:
+ -m, --my_option this is the option's help text Default: thisisthedefault.
+
+ 'file' logger options:
+ --log-level-display the minimum log level to display on stdout. Must be one of verbose, debug, info, warn, error, assert. Default: error.
+</code></pre>
+
+<p>Note the message at the top about "printing only the important options." To reduce option help
+clutter, TF uses the <code>Option#importance</code> attribute to determine whether to show a
+particular <code>@Option</code> field's help text
+when <code>--help</code> is specified. <code>--help-all</code> will always show help for all
+<code>@Option</code> fields, regardless of importance. See the
+<a href="/reference/com/android/tradefed/config/Option.Importance.html"
+>Option.Importance javadoc</a> for details.</p>
+
+<h3>Passing Values from a Configuration</h3>
+<p>You can also specify an Option's value within the config by adding a
+<code><option name="" value=""></code> element. Let's see how this looks in
+<code>helloworld.xml</code>:</p>
+<pre><code><test class="com.android.tradefed.example.HelloWorldTest" >
+ <option name="my_option" value="fromxml" />
+</test>
+</code></pre>
+
+<p>Re-building and running helloworld should now produce this output:</p>
+<pre><code>05-24 20:38:25 I/HelloWorldTest: I received option 'fromxml'
+</code></pre>
+
+<p>The configuration help should also be updated to indicate my_option's new default value:</p>
+<pre><code>tf> run --help example/helloworld
+ test options:
+ -m, --my_option this is the option's help text Default: fromxml.
+</code></pre>
+<p>Also note that other configuration objects included in the helloworld config, such as
+<code>FileLogger</code>, also accept options. The option <code>--log-level-display</code> is
+interesting because it filters the logs that show up on stdout. You may have noticed from earlier
+in the tutorial that the "Hello, TF World! I have device …' log message stopped being displayed
+on stdout once we switched to using <code>FileLogger</code>. You can increase the verbosity of
+logging to stdout by passing in the <code>--log-level-display</code> arg.</p>
+
+<p>Try this now, and you should see the 'I have device' log message reappear on stdout, in
+addition to being logged to a file.</p>
+<pre><code>tf >run --log-level-display info example/helloworld
+…
+05-24 18:53:50 I/HelloWorldTest: Hello, TF World! I have device 004ad9880810a548
+</code></pre>
+
+<h2>That's All, Folks!</h2>
+<p>As a reminder, if you're stuck on something, the
+<a href="https://android.googlesource.com/platform/tools/tradefederation/+/master"
+>Trade Federation source code</a> has a lot of useful information that isn't
+exposed in the documentation. And if all else fails, try asking on the
+<a href="/source/community/index.html">android-platform</a> Google Group, with "Trade Federation"
+in the message subject.</p>
+
diff --git a/src/devices/tech/test_infra/tradefed/fundamentals/devices.jd b/src/devices/tech/test_infra/tradefed/fundamentals/devices.jd
new file mode 100644
index 0000000..c7d3da8
--- /dev/null
+++ b/src/devices/tech/test_infra/tradefed/fundamentals/devices.jd
@@ -0,0 +1,58 @@
+page.title=Working with Devices
+@jd:body
+
+<!--
+ Copyright 2013 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>Trade Federation uses an abstraction called
+<code><a href="/reference/com/android/tradefed/device/ITestDevice.html">ITestDevice</a></code> to
+run tests. This abstraction objectifies the lowest-common-denominator Android device:</p>
+<ul>
+<li>It has a serial number</li>
+<li>It has a state: Online, Available, Recovery, or Not Available</li>
+<li>It has some notion of reliability. For instance, if we run a command, we can differentiate
+ between the case where the command hasn't finished yet, the case where the device doesn't support
+ running commands, and the case where the device has become unresponsive while running the
+ command.</li>
+</ul>
+
+<h2>Different Classes of Devices</h2>
+<p>The three primary implementations of <code>ITestDevice</code> represent three common
+usecases.</p>
+
+<h3>Physical Device</h3>
+<p>This is an actual piece of hardware, connected to the TF host machine either by USB, or by using
+adb's TCP feature. The <a href="/reference/com/android/tradefed/device/TestDevice.html"
+>TestDevice</a> class sits atop the ddmlib library, which is a Java interface to adb. So any
+physical device listed in <code>adb devices</code> can be instantiated and used as a
+<code>TestDevice</code>.
+</p>
+
+<h3>Emulator</h3>
+<p>Emulators are handled specially by TF because they live in another process. To interact with an
+Emulator, specify the <code>--emulator</code> argument for the command. See
+<a href="/reference/com/android/tradefed/build/LocalSdkBuildProvider.html"
+>LocalSdkBuildProvider</a> and
+<a href="/reference/com/android/tradefed/targetprep/SdkAvdPreparer.html"
+>SdkAvdPreparer</a> for more info.</p>
+
+<h3>No Device</h3>
+<p>Suppose you have a test that doesn't interact with a device at all. For instance, it might just
+download a file from some service and verify that the file itself is valid. The
+<a href="/reference/com/android/tradefed/device/NullDevice.html"
+>NullDevice</a> is an <code>ITestDevice</code> that is just a stub. It has a serial number like
+<code>null-device-N</code>, and most attempted operations either no-op silently or throw.
+</p>
diff --git a/src/devices/tech/test_infra/tradefed/fundamentals/index.jd b/src/devices/tech/test_infra/tradefed/fundamentals/index.jd
new file mode 100644
index 0000000..98ab260
--- /dev/null
+++ b/src/devices/tech/test_infra/tradefed/fundamentals/index.jd
@@ -0,0 +1,75 @@
+page.title=Getting Started with TF
+@jd:body
+
+<!--
+ Copyright 2013 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>Trade Federation is a large test infrastructure that can be adapted to a great variety of
+different usecases, and most people will probably only need some subset of its functionality. First
+off, we envision that TF users will fulfill any of three primary roles: Developer, Integrator, and
+Test Runner. A particular individual might wear any (or all) of those three hats, but we feel the
+distinction will help make it easier to navigate the documentation.</p>
+
+<h2>Developers</h2>
+<p>Developers spend the majority of their time creating TF modules that are written in Java.
+They may write configurations and execute tests, but will typically only do so to verify that their
+modules are being invoked properly and are functioning as expected.</p>
+
+<h2>Integrators</h2>
+<p>Integrators spend the majority of their time creating XML test configurations, or command
+files (which are written in a simple shell-like language). They tie together TF modules written
+by the Developer with specific configurations that are required for particular test requirements and
+goals.</p>
+
+<h2>Test Runners</h2>
+<p>Test Runners spend the majority of their time executing tests and generally making sure
+that test results are being generated, and that the generated test results are relevant,
+reproducible, and accurate. They spend the majority of their time interacting with tradefed's
+command line interface, and will also verify that the results make sense.</p>
+
+
+<p>In order to get the most out of Trade Federation, all three roles will need to be represented.
+It will take Developers and Integrators to make TF interoperate with other pieces of infrastructure,
+like build systems and test result repositories. It will take Integrators and Test Runners to get
+TF to actually run the desired tests and produce the desired test results. It will take Test
+Runners to identify results that don't make sense, and to work with the Developers and
+Integrators to figure out where the bugs may lie and get them fixed.</p>
+
+<h2>What's Next</h2>
+<p>People in all three roles should at least glance through all the rest of the docs.
+<a href="/devices/tech/test_infra/tradefed/fundamentals/machine_setup.html"
+>Machine Setup</a> will get you to the point where you can run TF.
+<a href="/devices/tech/test_infra/tradefed/fundamentals/devices.html"
+>Working with Devices</a> will explain how to run tests with a physical device, with an emulator, or
+with no device at all. The
+<a href="/devices/tech/test_infra/tradefed/fundamentals/lifecycle.html"
+>Test Lifecycle</a> page will explain from a theoretical perspective how the roles of the
+Developer, Integrator, and Test Runner interact, and then
+<a href="/devices/tech/test_infra/tradefed/fundamentals/options.html"
+>Option Handling</a> will demonstrate how to put that theory into practice.</p>
+
+
+<p>Finally, the <a href="/devices/tech/test_infra/tradefed/full_example.html"
+>End-to-End Example</a> takes you through the development, integration, and deployment of a sample
+test. It involves aspects of each role, and should offer hints at how to do more complicated
+things that aren't directly discussed in the documentation.</p>
+
+<p>If you've gotten through everything here and still have unanswered questions, first try taking
+a look at the <a href="https://android.googlesource.com/platform/tools/tradefederation/+/master"
+>Trade Federation source code.</a>. Beyond that, feel free to try asking on the
+<a href="/source/community/index.html">android-platform</a> Google Group. For best results, make
+sure to mention "Trade Federation" (or "tradefed", or "TF") in the message subject.</p>
+
diff --git a/src/devices/tech/test_infra/tradefed/fundamentals/lifecycle.jd b/src/devices/tech/test_infra/tradefed/fundamentals/lifecycle.jd
new file mode 100644
index 0000000..2b8664d
--- /dev/null
+++ b/src/devices/tech/test_infra/tradefed/fundamentals/lifecycle.jd
@@ -0,0 +1,60 @@
+page.title=Test Lifecycle
+@jd:body
+
+<!--
+ Copyright 2013 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 lifecycle of a test executed using TradeFederation is composed of four separate stages, designed
+around formally defined interfaces.</p>
+<ul>
+<li><a href="/reference/com/android/tradefed/build/IBuildProvider.html"
+ >Build Provider</a>: Provides a build to test, downloading appropriate files if necessary</li>
+<li><a href="/reference/com/android/tradefed/targetprep/ITargetPreparer.html"
+ >Target Preparer</a>: Prepares the test environment, possibly including software installation and
+ device configuration</li>
+<li><a href="/reference/com/android/tradefed/testtype/IRemoteTest.html"
+ >Test</a>: Executes test(s) and gathers test results. This may be any JUnit Test, although our
+ <a href="/reference/com/android/tradefed/testtype/IRemoteTest.html"
+ >IRemoteTest</a> interface is specifically designed to work well in the Trade Federation
+ environment.</li>
+<li><a href="/reference/com/android/tradefed/result/ITestInvocationListener.html"
+ >Test Invocation Listener</a>: Listens for test results, usually for the purpose of forwarding the
+ test results to a repository or displaying them to the Test Runner</li>
+</ul>
+
+<p>The fundamental testing entity in TF is a <b>Configuration</b> (config). A config is an XML file
+that declares the lifecycle components of a test.</p>
+
+<p>This separation of the test's lifecycle is intended to allow for reuse. Using this design, the
+Developer can create a Test once, and then the Integrator can create different Configurations to
+run that Test in different environments. For example,
+they could create a Configuration that will run a test on a local machine and dump the result to
+stdout. They could then create a second Configuration that would execute that same test, but use a
+different Test Invocation Listener to store the test results in a database. A third Configuration
+might be designed run that test continuously from a test lab somewhere.</p>
+
+<p>It's convenient to note here that a Configuration along with its command-line arguments (as
+provided by the Test Runner) is known as a <b>Command</b>. When TF takes pairs a Command with an
+<code>ITestDevice</code> and executes it, the subsequent object is known as an <b>Invocation</b>.
+In short, an Invocation encompasses a complete TF test execution, across its entire lifecycle.</p>
+
+<h3>Additional Components of a Configuration</h3>
+<ul>
+<li><a href="/reference/com/android/tradefed/device/IDeviceRecovery.html"
+ >Device Recovery</a>: mechanism to recover device communication if lost</li>
+<li><a href="/reference/com/android/tradefed/log/package-summary.html">Logger</a>: collects tradefed logging data</li>
+</ul>
+
diff --git a/src/devices/tech/test_infra/tradefed/fundamentals/machine_setup.jd b/src/devices/tech/test_infra/tradefed/fundamentals/machine_setup.jd
new file mode 100644
index 0000000..112d359
--- /dev/null
+++ b/src/devices/tech/test_infra/tradefed/fundamentals/machine_setup.jd
@@ -0,0 +1,55 @@
+page.title=Development Environment
+@jd:body
+
+<!--
+ Copyright 2013 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 Trade Federation source is stored in git along with the rest of the Android platform, and
+uses the Android platform build system to create its binary. First and foremost,
+<a href="/source/initializing.html">follow these instructions</a> to set up your machine to be
+able to compile and run things from the Android tree.</p>
+
+<h2>Getting the Source</h2>
+<p>The TF source lives in the Android codebase, but you need to specify an extra option to get at it.
+<a href="/source/downloading.html">Follow these instructions</a> to download the source, but use
+the branch <code>tradefed</code> to actually pull down the Trade Federation source. The actual
+command you run should look something like</p>
+<pre><code>$ repo init -u https://…/manifest -b tradefed</code></pre>
+
+<h3>Building</h3>
+<p>Trade Federation is set up in a lightweight "unbundled" branch that uses slightly different build
+commands from the platform source. In particular, unbundled branches use the <code>tapas</code>
+command to set up the build environment, rather than the <code>lunch</code> command. So starting
+from the root directory of the source tree you checked out, try:</p>
+<pre><code>$ . build/envsetup.sh
+$ tapas tradefed-all
+$ m -j8
+</pre></code>
+
+Note that once the <code>$ . build/envsetup.sh</code> step is done, the other two commands will run
+equally well from anywhere in the tree.
+
+<h2>Running from Command Line</h2>
+<p>First and foremost, tradefed requires the <code>adb</code> utility to be in your current
+<code>$PATH</code>.</p>
+<pre><code>$ export PATH=$PATH:<path to adb></pre></code>
+
+<p>Building TF using the steps mentioned above will add the <code>tradefed.sh</code> launcher script
+to your path. So to launch the TF console, run</p>
+<pre><code>$ tradefed.sh</pre></code>
+
+<p>At this point, your environment is set up for Trade Federation.</p>
+
diff --git a/src/devices/tech/test_infra/tradefed/fundamentals/options.jd b/src/devices/tech/test_infra/tradefed/fundamentals/options.jd
new file mode 100644
index 0000000..930be9e
--- /dev/null
+++ b/src/devices/tech/test_infra/tradefed/fundamentals/options.jd
@@ -0,0 +1,100 @@
+page.title=Option Handling
+@jd:body
+
+<!--
+ Copyright 2013 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>Option handling lies at the heart of Trade Federation's modular approach. In particular, options
+are the mechanism by which the Developer, Integrator, and Test Runner can work together without
+having to duplicate each-other's work. Put simply, our implementation of option handling allows the
+Developer to mark a Java class member as being configurable, at which point the value of that member
+may be augmented or overridden by the Integrator, and may be subsequently augmented or overridden by
+the Test Runner. This mechanism works for all Java intrinsic types, as well as for any
+<code>Map</code>s or <code>Collection</code>s of intrinsic types.</p>
+
+<p><em>Note:</em> the option-handling mechanism only works for classes implementing one of the
+interfaces included in the <a href="lifecycle.html">Test Lifecycle</a>, and only when that class is
+<em>instantiated</em> by the lifecycle machinery.</p>
+
+<h2>Developer</h2>
+<p>To start off, the developer marks a member with the
+<code><a href="https://android.googlesource.com/platform/tools/tradefederation/+/master/src/com/android/tradefed/config/Option.java"
+>@Option</a></code> annotation. <!-- note: javadoc for the Option class is broken -->
+They specify (at a minimum) the <code>name</code> and <code>description</code> values, which
+specify the argument name associated with that Option, and the description that will be displayed on
+the TF console when the command is run with <code>--help</code> or <code>--help-all</code>.</p>
+
+<p>As an example, let's say we want to build a functional phone test which will dial a variety of
+phone numbers, and will expect to receive a sequence of DTMF tones from each number after it
+connects.</p>
+<code><pre>public class PhoneCallFuncTest extends IRemoteTest {
+ @Option(name = "timeout", description = "How long to wait for connection, in millis")
+ private long mWaitTime = 30 * 1000; // 30 seconds
+
+ @Option(name = "call", description = "Key: Phone number to attempt. " +
+ "Value: DTMF to expect. May be repeated.")
+ private Map<String, String> mCalls = new HashMap<String, String>;
+
+ public PhoneCallFuncTest() {
+ mCalls.add("123-456-7890", "01134"); // default
+ }</pre></code>
+
+<p>That's all that's required for the Developer to set up two points of configuration for that
+test. They could then go off and use <code>mWaitTime</code> and <code>mCalls</code> as normal,
+without paying much attention to the fact that they're configurable. Because the
+<code>@Option</code> fields are set after the class is instantiated, but before the
+<code>run</code> method is called, that provides an easy way for implementors to set up defaults for
+or perform some kind of filtering on <code>Map</code> and <code>Collection</code> fields, which are
+otherwise append-only.</p>
+
+<h2>Integrator</h2>
+<p>The Integrator works in the world of Configurations, which are written in XML. The config format
+allows the Integrator to set (or append) a value for any <code>@Option</code> field. For instance,
+suppose the Integrator wanted to define a lower-latency test that calls the default number, as well
+as a long-running test that calls a variety of numbers. They could create a pair of configurations
+that might look like the following:</p>
+
+<code><pre><?xml version="1.0" encoding="utf-8"?>
+<configuration description="low-latency default test; low-latency.xml">
+ <test class="com.example.PhoneCallFuncTest">
+ <option name="timeout" value="5000" />
+ </test>
+</configuration></pre></code>
+
+<code><pre><?xml version="1.0" encoding="utf-8"?>
+<configuration description="call a bunch of numbers; many-numbers.xml">
+ <test class="com.example.PhoneCallFuncTest">
+ <option name="call" key="111-111-1111" value="#*#*TEST1*#*#" />
+ <option name="call" key="222-222-2222" value="#*#*TEST2*#*#" />
+ <!-- ... -->
+ </test>
+</configuration></pre></code>
+
+<h2>Test Runner</h2>
+<p>The Test Runner also has access to these configuration points via the Trade Federation console.
+First and foremost, they will run a Command (that is, a config and all of its arguments) with the
+<code>run command <name></code> instruction (or <code>run <name></code> for short).
+Beyond that, they can specify any list of arguments are part of the command, which may replace or
+append to fields specified by Lifecycle Objects within each config.</p>
+
+<p>To run the low-latency test with the <code>many-numbers</code> phone numbers, the Test Runner
+could execute:</p>
+<code><pre>tf >run low-latency.xml --call 111-111-1111 #*#*TEST1*#*# --call 222-222-2222 #*#*TEST2*#*#</pre></code>
+
+<p>Or, to get a similar effect from the opposite direction, the Test Runner could reduce the wait time
+for the <code>many-numbers</code> test:</p>
+<code><pre>tf >run many-numbers.xml --timeout 5000</code></pre>
+
diff --git a/src/devices/tech/test_infra/tradefed/getting_started.jd b/src/devices/tech/test_infra/tradefed/getting_started.jd
deleted file mode 100644
index 8219ee7..0000000
--- a/src/devices/tech/test_infra/tradefed/getting_started.jd
+++ /dev/null
@@ -1,203 +0,0 @@
-page.title=Getting Started
-@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.
--->
-<h2 id="using-the-console">Using the console</h2>
-<p>TF is based around an interactive console. You can fire up the console by going to the
-<code>tools/tradefederation/</code> directory and running</p>
-<pre><code>$ ./tradefed.sh
-</code></pre>
-<p>You should end up at a <code>tf ></code> prompt.</p>
-<p>The console is self-documenting. Try entering "help"</p>
-<pre><code>tf >help
-Enter 'q' or 'exit' to exit
-Enter 'kill' to attempt to forcibly exit, by shutting down adb
-
-Enter 'help list' for help with 'list' commands
-[...]
-</code></pre>
-<p>As the help text suggests, the help menus are organized hierarchically</p>
-<pre><code>tf >help list
-l(?:ist)? help:
- i[nvocations] List all invocation threads
- d[evices] List all detected or known devices
-[...]
-</code></pre>
-<p>The majority of commands have a convenient short form, which the help text displays. The
-<code>l(?:ist)?</code> is a regular expression. As an example, here are the four equivalent ways to list
-invocations:
-<em> <code>list invocations</code>
-</em> <code>list i</code>
-<em> <code>l invocations</code>
-</em> <code>l i</code></p>
-<h2 id="running-a-configcommand">Running a config/command</h2>
-<p>This is documented by the <code>help run</code> command in the console.</p>
-<p>As a reminder, a command is a config along with all of its command-line arguments. A command <em>must</em>
-begin with the name of the respective config.</p>
-<p>As a quick example, you could run the calculator unit tests like so:</p>
-<pre><code>$./tradefed.sh
-tf >run instrument --package com.android.calculator2.tests
-</code></pre>
-<p>As a shortcut, if you specify any arguments to <code>tradefed.sh</code>, it will attempt to execute them as if
-they were typed on the commandline. So the short version of the above would be</p>
-<pre><code>$./tradefed.sh run instrument --package com.android.calculator2.tests
-</code></pre>
-<p>In both of these cases, the name of the config is "instrument", and
-"--class com.android.calculator2.tests" is a command-line argument. The command that is being run
-is "instrument --class com.android.calculator2.tests".</p>
-<p>TF can run both configs that are compiled in (such as the "instrument" config above), as well as
-configs that exist as xml files on the local filesystem. You can see a list of compiled-in configs
-with the <code>list configs</code> console command. Furthermore, you can investigate any config (compiled-in
-or local) by passing the "--help" or "--help-all" command-line arguments. The "--help" argument
-will only show "important" arguments, and "--help-all" will show all arguments, regardless of
-whether they've been marked as "important" or not. To take the final step, you can tell TF to print
-the contents of any config (compiled-in or local) with the <code>dump config <configname></code> console
-command.</p>
-<h3 id="so-lets-say-you-want-to-run-the-calculator-instrumentation-tests-but-dont-know-where-to-start">So, let's say you want to run the calculator instrumentation tests, but don't know where to start.</h3>
-<p>You could try something like this sequence of steps. First, look for a config that looks like it
-might do what you want:</p>
-<pre><code>tf >list configs
-Use 'run command --help <configuration_name>' to get list of options for a configuration
-Use 'dump config <configuration_name>' to display the configuration's XML content.
-
-Available configurations include:
-[...]
- instrument: Runs a single Android instrumentation test on an existing device
-[...]
-</code></pre>
-<p>Now that you've found something reasonable-looking, see what options it takes. The <code>list configs</code> output suggests trying <code>run command instrument --help</code></p>
-<pre><code>tf >run command --help instrument
-'instrument' configuration: Runs a single Android instrumentation test on an existing device
-
-Printing help for only the important options. To see help for all options, use the --help-all flag
-[...]
- 'instrumentation' test options:
- -p, --package The manifest package name of the Android test application to run.
-</code></pre>
-<p>As the message suggests, if you need more options, use the "--help-all" flag instead of "--help". In this case, we've got all we need. You could figure out the package by checking with <code>runtest</code>, or reading testdefs.xml directly. We use <code>runtest -n</code> to simply show what would be run without actually running it:</p>
-<pre><code>$runtest -n calculator
-adb root
-ONE_SHOT_MAKEFILE="packages/apps/Calculator/Android.mk" make -j4 -C "/srv/xsdg/master2" files
-adb sync
-adb shell am instrument -w com.android.calculator2.tests/android.test.InstrumentationTestRunner
-</code></pre>
-<p>The argument to <code>am instrument</code> that comes before the slash is the manifest package. <code>android.test.InstrumentationTestRunner</code> is the default runner, so no need to set it if that's the
-right one. Otherwise, using "--help-all" will tell you about the "--runner" argument, which you can
-use to specify an alternate runner. Ok, so at this point, we've got the following command, which
-you'll recognize from above</p>
-<pre><code>tf >run instrument --package com.android.calculator2.tests
-</code></pre>
-<h2 id="interacting-with-a-device">Interacting with a device</h2>
-<h3 id="generic-device-behavior-in-tf">Generic device behavior in TF</h3>
-<p>The running version of a command is called in <code>invocation</code>. First and foremost, every invocation
-requires a device before it can run. In addition to physical Android devices, TF can run tests with
-a mock device (by specifying the "-n" argument for the command), or with the Android emulator (by
-specifying the "-e" argument").</p>
-<p>The primary console command to figure out what devices are up to is <code>list devices</code>:</p>
-<pre><code>$./tradefed.sh
-06-07 17:03:22 I/: Detected new device 016B756E03018007
-06-07 17:03:22 I/: Detected new device 1700614743c14397
-06-07 17:03:22 I/: Detected new device 3531C342606300EC
-tf >l d
-Serial State Product Variant Build Battery
-016B756E03018007 Available tuna toro MASTER 100
-1700614743c14397 Available stingray stingray MASTER 100
-3531C342606300EC Available herring crespo4g MASTER 92
-</code></pre>
-<p>As far as the invocations are concerned, there are three device states: available, unavailable, and
-allocated. An <code>Available</code> device is ready to be allocated for an invocation. An <code>Unavailable</code>
-device is not ready for allocation, for any of a variety of reasons — TF may have deemed to the
-device as unstable, the device may be critically low on storage, or something else may be amiss.
-Finally, an <code>Allocated</code> device is a device that is already being used by an invocation.</p>
-<p>When you start TF, all detected physical devices will be checked for responsiveness with a simple
-shell command. If the command completes successfully, the device will be listed as Available. If
-the command fails, the device state will be shown as Unavailable. Thereafter, a device will typically bounce between the Available and Allocated states as invocation requirements dictate.</p>
-<p>Finally, once invocations are already underway, you can see what's going on with the <code>list
-invocations</code> command</p>
-<pre><code>tf >run instrument --package com.android.calculator2.tests
-06-07 17:18:31 I/TestInvocation: Starting invocation for 'stub' on build '0' on device 1700614743c14397
-[...]
-tf >l d
-Serial State Product Variant Build Battery
-1700614743c14397 Allocated stingray stingray MASTER 100
-3531C342606300EC Available herring crespo4g JRN11 93
-016B756E03018007 Available tuna toro MASTER 100
-
-tf >l i
-Command Id Exec Time Device State
-1 0m:02 1700614743c14397 running stub on build 0
-</code></pre>
-<h3 id="running-invocations-on-specific-devices">Running invocations on specific devices</h3>
-<p>TF supports a number of filtering mechanisms for specifying which device or devices to use for a
-particular invocation. Since the filtering mechanisms are run before a command turns into an
-invocation, you can find all of the filtering options in the help for any config:</p>
-<p>tf >run instrument --help-all
-[...]
- device_requirements options:
- -s, --serial run this test on a specific device with given serial number(s).
- --exclude-serial run this test on any device except those with this serial number(s).
- --product-type run this test on device with this product type(s). May also filter by variant using product:variant.
- --property run this test on device with this property value. Expected format <propertyname>=<propertyvalue>.
- -e, --[no-]emulator force this test to run on emulator. Default: false.
- -d, --[no-]device force this test to run on a physical device, not an emulator. Default: false.
- --[no-]new-emulator allocate a placeholder emulator. Should be used when config intends to launch an emulator Default: false.
- -n, --[no-]null-device
- do not allocate a device for this test. Default: false.
- --min-battery only run this test on a device whose battery level is at least the given amount. Scale: 0-100
- --max-battery only run this test on a device whose battery level is strictly less than the given amount. Scale: 0-100
-[...]</p>
-<p>The built-in help should be pretty self-explanatory. All of the filtering options excluding "-n",
-"-e", and "-d" may be specified as many times as needed. So, for instance, to run an invocation
-using any Verizon Galaxy Nexus, you could do the following:</p>
-<pre><code>tf >run instrument --package com.android.calculator2.tests --product-type tuna:toro
-</code></pre>
-<p>As another example, to run on a GSM device with a SIM, you could do the following:</p>
-<pre><code>tf >run instrument --package com.android.calculator2.tests --property gsm.sim.state=READY
-</code></pre>
-<p>The filtering works by exclusion from the pool of Available devices, so the "--serial" option simply
-excludes devices that aren't in the list of required serials, and --exclude-serial excludes devices
-that <em>are</em> in its list. As such, an argument like --exclude-serial XXX --serial XXX will simply
-make the respective command un-runnable — it will never match any device, since all devices are
-excluded.</p>
-<h2 id="logging">Logging</h2>
-<p>There are a few different aspects to logging in TF. First and foremost, TF has a built-in logging
-infrastructure that's based on DDMLib's Log class. For the common case, where the log tag is just
-the classname of the current class, you can use our CLog convenience shim. In short, if you might
-have originally done this:</p>
-<pre><code>class ClassName {
-private static final LOG_TAG = "ClassName";
-[...]
-Log.v(LOG_TAG, "This is a simple verbose log message");
-Log.w(LOG_TAG, String.format("This warning message brought to you by the number %d", 17));
-</code></pre>
-<p>You can now accomplish the same thing with the shim like this:</p>
-<pre><code>class ClassName {
-[...]
-CLog.v("This is a simple verbose log message");
-CLog.w("This warning message brought to you by the number %d", 17);
-</code></pre>
-<p>Each Invocation has its own ThreadGroup. Any host-side logging that happens inside of that thread
-group is associated with the Invocation, and will be reported as that invocation's "host_log" after
-the Invocation completes.</p>
-<p>Device logging is performed as part of TradeFed's device wrapper. We keep a buffer of up to 20 MB
-that captures log data as the device churns it out. In particular, we are not limited by the size
-of the on-device logcat buffer.</p>
-<p>The next important piece is the ITestInvocationListener. This is one of the components of an
-Invocation that handles results reporting. Each reporter has the option to implement the #testLog
-method, which will be used to pass logfiles to that result reporter. Among the files that are
-passed by TF itself will be the aforementioned host_log, as well as the device logcat for the device
-associated with the Invocation.</p>
diff --git a/src/devices/tech/test_infra/tradefed/index.jd b/src/devices/tech/test_infra/tradefed/index.jd
index 9331369..ad7367a 100644
--- a/src/devices/tech/test_infra/tradefed/index.jd
+++ b/src/devices/tech/test_infra/tradefed/index.jd
@@ -16,37 +16,92 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<p>TradeFederation (tradefed or TF for short) is a continuous test framework designed for running tests
-on Android devices. Its a Java application which runs on a host computer, and communicates to one or
+<p>Trade Federation (tradefed or TF for short) is a continuous test framework designed for running tests
+on Android devices. It's a Java application which runs on a host computer, and communicates to one or
more Android devices using ddmlib (the library behind DDMS) over adb.</p>
-<h2 id="features">Features</h2>
+
+<p>We've listed some of TF's main features below, along with a couple sample usecases. That said,
+if you want to jump right in and get started, you can head straight for the
+<a href="/devices/tech/test_infra/tradefed/fundamentals/index.html">Start Here</a> page.</p>
+
+<h2>Features</h2>
<ul>
-<li>modular, flexible design</li>
-<li>has built in support for running many different types of Android tests: instrumentation, native/gtest, host-based JUnit, etc</li>
-<li>provides reliability and recovery mechanism on top of adb</li>
+<li>modular, flexible, scalable design</li>
+<li>has built in support for running many different types of Android tests:
+ <a href="http://developer.android.com/tools/testing/testing_android.html#Instrumentation">instrumentation</a>,
+ <a href="http://developer.android.com/tools/testing/testing_ui.html">uiautomator</a>,
+ native/gtest, host-based JUnit, etc</li>
+<li>provides reliability and recovery mechanisms on top of adb</li>
<li>supports scheduling and running tests on multiple devices in parallel</li>
</ul>
-<h2 id="fundamentals">Fundamentals</h2>
-<p>The lifecycle of a test executed using TradeFederation is composed of four separate stages, designed
-around formally defined interfaces.</p>
-<ul>
-<li><a href="bp.html">Build provider</a>: Provides a build to test, downloading appropriate files if necessary</li>
-<li><a href="tp.html">Target preparer</a>: Prepares the test environment, e.g. software installation and setup</li>
-<li><a href="test.html">Test</a>: Executes test(s) and gathers test results</li>
-<li><a href="result.html">Result reporter</a>: Listens for test results, usually for the purpose of forwarding
- test results to a repository</li>
-</ul>
-<p>The fundamental entity in TradeFederation is a Configuration. A Configuration is an XML file that
-declares the lifecycle components of a test.</p>
-<p>This separation of the test's lifecycle is intended to allow for reuse. Using this design, you can
-create a Test, and then different Configurations to run it in different environments. For example,
-you could create a Configuration that will run a test on your local machine, and dump the result to
-stdout. You could then create a second Configuration that would execute that same test, but use a
-different Result reporter to store the test results in a database.</p>
-<h3 id="additional-components-of-a-configuration">Additional components of a configuration</h3>
-<ul>
-<li><a href="recovery.html">Device recovery</a>: mechanism to recover device communication if lost</li>
-<li><a href="logger.html">Logger</a>: collects tradefed logging data</li>
-</ul>
-<p>A complete TradeFederation test execution, across its entire lifecycle, is referred to as an
-Invocation.</p>
\ No newline at end of file
+
+<h2>Sample Trade Federation Usecases</h2>
+<p>Trade Federation's modularity makes it straightforward to slot into environments with existing
+build, test, and reporting infrastructures. We list below a few demonstrative
+usecases where tradefed could enable efficient, scalable test practices.</p>
+
+<p>First, it is useful to consider the landscape of potential usecases in terms of the question
+"which parts are modifiable, and what parts are static?" For instance, a Device OEM can modify the
+framework, the system, and the hardware, but has little or no influence over existing applications.
+An application developer, on the other hand, can modify the app, but has little control over most
+aspects of the system or the framework.</p>
+
+<p>As a result, an entity in each usecase will have different testing goals, and will have different
+options in the case of a set of test failures. Despite these differences, Trade Federation can
+help make each of their test processes efficient, flexible, and scalable.</p>
+
+<h3>Device OEM</h3>
+<p>A Device OEM builds hardware, and will often tweak the Android system and frameworks to run well
+on that hardware. The OEM might strive to accomplish those goals while retaining stability
+and performance at the hardware and system levels, and making sure the framework changes don't break
+compatibility with existing applications.</p>
+
+<p>The OEM could implement a device flashing module that will execute during the Target Setup stage
+of the <a href="/devices/tech/test_infra/tradefed/fundamentals/lifecycle.html">lifecycle</a>. That
+module would have complete control over the device during its execution period, which would allow
+it to potentially force the device into the bootloader, flash, and then force the device to reboot
+back into userspace mode. Combined with a module to tie into a continuous build system, this would
+allow the OEM to run tests on their device as they make changes to the system-level firmware and
+Java-level frameworks.</p>
+
+<p>Once the device is fully booted, the OEM would be able to leverage existing JUnit-based tests,
+or write new ones, to verify the functionality of interest. Finally, they could write one or more
+result reporting modules to tie into existing test-result repositories, or to report results
+directly (for instance,
+<a href="/reference/com/android/tradefed/result/EmailResultReporter.html">by email</a>).</p>
+
+<h3>App Developer</h3>
+<p>An Application Developer builds an app which needs to run well across a variety of platform
+versions and a variety of devices. If an issue comes up on a particular platform version and/or
+device, the only remedy is to add a workaround and move on. For larger developers, the test
+process might be incorporated into a continuous build sequence. For smaller developers, it
+might be kicked off periodically or by hand.</p>
+
+<p>Most app developers would use the apk test installation modules that already exist in TF.
+There's a version that <a href="/reference/com/android/tradefed/targetprep/InstallApkSetup.html"
+>installs from the local filesystem</a>, as well as a version that can
+<a href="/reference/com/android/tradefed/targetprep/InstallBuildEnvApkSetup.html">install
+apks downloaded from a build service</a>. It is important to note that the latter version would
+continue to work properly with arbitrarily many TF instances running on the same host machine.</p>
+
+<p>Because of TF's proficiency at dealing with multiple devices, it would be straightforward to
+classify each test result by the type of device that was used for that test. Thus, TF could
+potentially generate a 2-dimensional (or multi-dimensional) compatibility matrix for every
+build of the application.</p>
+
+<h3>Testing Service</h3>
+<p>A Test Service might, for instance, allow app developers to submit apps and run tests on devices
+instrumented with power-measurement tools to determine power usage for the app. This differs from
+the prior two usecases in that the service builder does not control the devices or the applications
+that are being run</p>
+
+<p>Because Trade Federation can run any Java class that implements the simple
+<a href="/reference/com/android/tradefed/testtype/IRemoteTest.html">IRemoteTest</a> interface, it's
+trivial to write drivers that can coordinate some external piece of hardware with the test case
+that's being run on the device. The driver itself can spawn Threads, send requests to other
+servers, or do anything else that it might need. Moreover, the simplicity and versatility of the
+result reporting interface,
+<a href="/reference/com/android/tradefed/result/ITestInvocationListener.html"
+>ITestInvocationListener</a>, means that it is likewise straightforward to
+represent arbitrary test results (including, for instance, numerical power metrics) into the
+standard result reporting pipeline.</p>
diff --git a/src/devices/tech/test_infra/tradefed/template.jd b/src/devices/tech/test_infra/tradefed/template.jd
new file mode 100644
index 0000000..3d6677f
--- /dev/null
+++ b/src/devices/tech/test_infra/tradefed/template.jd
@@ -0,0 +1,24 @@
+page.title=Template
+@jd:body
+
+<!--
+ Copyright 2013 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>Write some stuff</p>
+
+<h2>Hey, it's a header!</h2>
+<p>Write some more stuff</p>
+
diff --git a/src/devices/tech/test_infra/tradefed/tutorial.jd b/src/devices/tech/test_infra/tradefed/tutorial.jd
deleted file mode 100644
index eb42aa0..0000000
--- a/src/devices/tech/test_infra/tradefed/tutorial.jd
+++ /dev/null
@@ -1,334 +0,0 @@
-page.title=Tutorial
-@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.
--->
-<p>This tutorial guides you through the construction of a "hello world" Trade Federation test
-configuration, and gives you a hands-on introduction to the Trade Federation framework. Starting
-from the Tf development environment, it guides you through the process of creating a simple Trade
-Federation config and gradually adding more features to it.</p>
-<p>The tutorial presents the TF test development process as a set of exercises, each consisting of
-several steps. The exercises demonstrate how to gradually build and refine your configuration, and
-provide all the sample code you need to complete the test configuration.</p>
-<p>When you are finished with the tutorial, you will have created a functioning TF configuration and
-will have learned many of the most important concepts in the TF framework.</p>
-<h2 id="set-up-tradefederation-development-environment">Set up TradeFederation development environment</h2>
-<p>See (FIXME: link) for how to setup the development environment. The rest of this tutorial assumes you have a shell open that has been initialized to the TradeFederation environment. </p>
-<p>For simplicity, this tutorial will illustrate adding a configuration and its classes to the TradeFederation framework core library. Later tutorials/documentation will show how to create your own library that extends TradeFederation.</p>
-<h2 id="creating-a-test-class">Creating a test class</h2>
-<p>Lets create a hello world test that just dumps a message to stdout. A TradeFederation test must
-implement the (FIXME: link) IRemoteTest interface.</p>
-<p>Here's an implementation for the HelloWorldTest:</p>
-<pre><code>package com.android.tradefed.example;
-
-import com.android.tradefed.device.DeviceNotAvailableException;
-import com.android.tradefed.result.ITestInvocationListener;
-import com.android.tradefed.testtype.IRemoteTest;
-
-public class HelloWorldTest implements IRemoteTest {
- @Override
- public void run(ITestInvocationListener listener) throws DeviceNotAvailableException {
- System.out.println("Hello, TF World!");
- }
-}
-</code></pre>
-<p>FIXME: prod-tests
-Save this sample code to
-<code><git home>/tools/tradefederation/prod-tests/src/com/android/tradefed/example/HelloWorldTest.java</code>
-and rebuild tradefed from your shell:</p>
-<pre><code>m -j6
-</code></pre>
-<p>If the build does not succeed, please consult the (FIXME: link)Development Environment page to
-ensure you did not miss any steps.</p>
-<h2 id="creating-a-configuration">Creating a configuration</h2>
-<p>Trade Federation tests are defined in a "Configuration". A Configuration is an XML file that
-instructs tradefed which test (or set of tests) to run.</p>
-<p>Lets create a new Configuration for our HelloWorldTest.</p>
-<pre><code><configuration description="Runs the hello world test">
- <test class="com.android.tradefed.example.HelloWorldTest" />
-</configuration>
-</code></pre>
-<p>TF will parse the Configuration XML file, load the specified class using reflection, instantiate it,
-cast it to a IRemoteTest, and call its 'run' method.</p>
-<p>Note that we've specified the full class name of the HelloWorldTest. Save this data to a
-<code>helloworld.xml</code> file anywhere on your local filesystem (eg <code>/tmp/helloworld.xml</code>).</p>
-<h2 id="running-the-configuration">Running the configuration</h2>
-<p>From your shell, launch the tradefed console</p>
-<pre><code>$ ./tradefed.sh
-</code></pre>
-<p>Ensure a device is connected to the host machine that is visible to tradefed</p>
-<pre><code>tf> list devices
-</code></pre>
-<p>Configurations can be run using the <code>run <config></code> console command. Try this now</p>
-<p>FIXME: redo this</p>
-<pre><code>tf> run /tmp/helloworld.xml
-05-12 13:19:36 I/TestInvocation: Starting invocation for target stub on build 0 on device 30315E38655500EC
-Hello, TF World!
-</code></pre>
-<p>You should see "Hello, TF World!" outputted on the terminal.</p>
-<h2 id="adding-the-configuration-to-the-classpath">Adding the configuration to the classpath</h2>
-<p>FIXME: prod-tests
-For convenience of deployment, you can also bundle configuration files into the TradeFederation jars
-themselves. Tradefed will automatically recognize all configurations placed in 'config' folders on
-the classpath.</p>
-<p>Lets illustrate this now by moving the helloworld.xml into the tradefed core library.</p>
-<p>Move the <code>helloworld.xml</code> file into
-<code><git root>/tools/tradefederation/prod-tests/res/config/example/helloworld.xml</code>.</p>
-<p>Rebuild tradefed, and restart the tradefed console. </p>
-<p>Ask tradefed to display the list of configurations on the classpath:</p>
-<pre><code>tf> list configs
-[…]
-example/helloworld: Runs the hello world test
-</code></pre>
-<p>You can now run the helloworld config via the following command</p>
-<pre><code>tf >run example/helloworld
-05-12 13:21:21 I/TestInvocation: Starting invocation for target stub on build 0 on device 30315E38655500EC
-Hello, TF World!
-</code></pre>
-<h2 id="interacting-with-a-device">Interacting with a device</h2>
-<p>So far our hello world test isn't doing anything interesting. Tradefed is intended to run tests using Android devices, so lets add an Android device to the test.</p>
-<p>Tests can get a reference to an Android device by implementing the IDeviceTest interface. </p>
-<p>Here's a sample implementation of what this looks like:</p>
-<pre><code>public class HelloWorldTest implements IRemoteTest, IDeviceTest {
- private ITestDevice mDevice;
- @Override
- public void setDevice(ITestDevice device) {
- mDevice = device;
- }
-
- @Override
- public ITestDevice getDevice() {
- return mDevice;
- }
-…
-}
-</code></pre>
-<p>The TradeFederation framework will inject the ITestDevice reference into your test via the
-IDeviceTest#setDevice method, before the IRemoteTest#run method is called.</p>
-<p>Lets add an additional print message to the HelloWorldTest displaying the serial number of the
-device.</p>
-<pre><code>@Override
-public void run(ITestInvocationListener listener) throws DeviceNotAvailableException {
- System.out.println("Hello, TF World! I have a device " + getDevice().getSerialNumber());
-}
-</code></pre>
-<p>Now rebuild tradefed, and do (FIXME: update)</p>
-<pre><code>$ tradefed.sh
-tf> list devices
-Available devices: [30315E38655500EC]
-…
-</code></pre>
-<p>Take note of the serial number listed in Available devices above. That is the device that should be allocated to HelloWorld.</p>
-<pre><code>tf >run example/helloworld
-05-12 13:26:18 I/TestInvocation: Starting invocation for target stub on build 0 on device 30315E38655500EC
-Hello world, TF! I have a device 30315E38655500EC
-</code></pre>
-<p>You should see the new print message displaying the serial number of the device.</p>
-<h2 id="sending-test-results">Sending test results</h2>
-<p>IRemoteTests report results by calling methods on the ITestInvocationListener instance provided to
-their <code>#run</code> method.</p>
-<p>The TradeFederation framework is responsible for reporting the start and end of an Invocation (via
-the ITestInvocationListener#invocationStarted and ITestInvocationListener#invocationEnded methods
-respectively).</p>
-<p>A <code>test run</code> is a logical collection of tests. To report test results, IRemoteTests are responsible
-for reporting the start of a test run, the start and end of each test, and the end of the test run.</p>
-<p>Here's what the HelloWorldTest implementation looks like with a single failed test result.</p>
-<pre><code>@SuppressWarnings("unchecked")
-@Override
-public void run(ITestInvocationListener listener) throws DeviceNotAvailableException {
- System.out.println("Hello, TF World! I have a device " + getDevice().getSerialNumber());
-
- TestIdentifier testId = new TestIdentifier("com.example.MyTestClassName", "sampleTest");
- listener.testRunStarted("helloworldrun", 1);
- listener.testStarted(testId);
- listener.testFailed(TestFailure.FAILURE, testId, "oh noes, test failed");
- listener.testEnded(testId, Collections.EMPTY_MAP);
- listener.testRunEnded(0, Collections.EMPTY_MAP);
-}
-</code></pre>
-<p>Note that TradeFederation also includes several IRemoteTest implementations that you can reuse
-instead of writing your own from scratch. (such as InstrumentationTest, which can run an Android
-application's tests remotely on an Android device, parse the results, and forward them to the
-ITestInvocationListener). See the Test Types documentation for more details.</p>
-<h2 id="storing-test-results">Storing test results</h2>
-<p>By default, a TradeFederation configuration will use the TextResultReporter as the test listener
-implementation for the configuration. TextResultReporter will dump the results of an invocation to
-stdout. To illustrate, try running the hello-world config from previous section now:</p>
-<pre><code>$ ./tradefed.sh
-tf >run example/helloworld
-05-16 20:03:15 I/TestInvocation: Starting invocation for target stub on build 0 on device 30315E38655500EC
-Hello world, TF! I have a device 30315E38655500EC
-05-16 20:03:15 I/InvocationToJUnitResultForwarder: run helloworldrun started: 1 tests
-Test FAILURE: com.example.MyTestClassName#sampleTest
- stack: oh noes, test failed
-05-16 20:03:15 I/InvocationToJUnitResultForwarder: run ended 0 ms
-</code></pre>
-<p>If you want to store the results of an invocation elsewhere, say to a file, you would need to
-specify a custom "result_reporter" in your configuration, that specifies the custom
-ITestInvocationListener class you want to use.</p>
-<p>The TradeFederation framework includes a result_reporter (XmlResultReporter) that will write test
-results to an XML file, in a format similar to the ant JUnit XML writer. </p>
-<p>Lets specify the result_reporter in the configuration now. Edit the
-<code>tools/tradefederation/res/config/example/helloworld.xml</code> like this:</p>
-<pre><code><configuration description="Runs the hello world test">
- <test class="com.android.tradefed.example.HelloWorldTest" />
- <result_reporter class="com.android.tradefed.result.XmlResultReporter" />
-</configuration>
-</code></pre>
-<p>Now rebuild tradefed and re-run the hello world sample:
-FIXME: paths</p>
-<pre><code>tf >run example/helloworld
-05-16 21:07:07 I/TestInvocation: Starting invocation for target stub on build 0 on device 30315E38655500EC
-Hello world, TF! I have a device 30315E38655500EC
-05-16 21:07:07 I/XmlResultReporter: Saved device_logcat log to /var/folders/++/++2Pz+++6+0++4RjPqRgNE+-4zk/-Tmp-/0/inv_2991649128735283633/device_logcat_6999997036887173857.txt
-05-16 21:07:07 I/XmlResultReporter: Saved host_log log to /var/folders/++/++2Pz+++6+0++4RjPqRgNE+-4zk/-Tmp-/0/inv_2991649128735283633/host_log_6307746032218561704.txt
-05-16 21:07:07 I/XmlResultReporter: XML test result file generated at /var/folders/++/++2Pz+++6+0++4RjPqRgNE+-4zk/-Tmp-/0/inv_2991649128735283633/test_result_536358148261684076.xml. Total tests 1, Failed 1, Error 0
-</code></pre>
-<p>Notice the log message stating an XML file has been generated. The generated file should look like this:</p>
-<pre><code><?xml version='1.0' encoding='UTF-8' ?>
-<testsuite name="stub" tests="1" failures="1" errors="0" time="9" timestamp="2011-05-17T04:07:07" hostname="localhost">
- <properties />
- <testcase name="sampleTest" classname="com.example.MyTestClassName" time="0">
- <failure>oh noes, test failed
- </failure>
- </testcase>
-</testsuite>
-</code></pre>
-<p>Note that you can write your own custom result_reporter. It just needs to implement the
-ITestInvocationListener interface. </p>
-<p>Also note that Tradefed supports multiple result_reporters, meaning that you can send test results
-to multiple independent destinations. Just specify multiple <result_reporter> tags in your config to
-do this.</p>
-<h2 id="logging">Logging</h2>
-<p>TradeFederation includes two logging facilities:</p>
-<ol>
-<li>ability to capture logs from the device (aka device logcat)</li>
-<li>ability to record logs from the TradeFederation framework running on the host machine (aka the
- host log)</li>
-</ol>
-<p>Lets focus on 2 for now. Trade Federation's host logs are reported using the CLog wrapper for the
-ddmlib Log class. </p>
-<p>Lets convert the previous System.out.println call in HelloWorldTest to a CLog call:</p>
-<pre><code>@Override
-public void run(ITestInvocationListener listener) throws DeviceNotAvailableException {
- CLog.i("Hello world, TF! I have a device " + getDevice().getSerialNumber());
-</code></pre>
-<p>Now rebuild and rerun. You should see the log message on stdout. </p>
-<pre><code>tf> run example/helloworld
-…
-05-16 21:30:46 I/HelloWorldTest: Hello world, TF! I have a device 30315E38655500EC
-…
-</code></pre>
-<p>By default, TradeFederation will output host log messages to stdout. TradeFederation also includes a
-log implementation that will write messages to a file: FileLogger. To add file logging, add a
-'logger' tag to the configuration xml, specifying the full class name of FileLogger.</p>
-<pre><code><configuration description="Runs the hello world test">
- <test class="com.android.tradefed.example.HelloWorldTest" />
- <result_reporter class="com.android.tradefed.result.XmlResultReporter" />
- <logger class="com.android.tradefed.log.FileLogger" />
-</configuration>
-</code></pre>
-<p>Now rebuild and run the helloworld example again.</p>
-<pre><code>tf >run example/helloworld
-…
-05-16 21:38:21 I/XmlResultReporter: Saved device_logcat log to /var/folders/++/++2Pz+++6+0++4RjPqRgNE+-4zk/-Tmp-/0/inv_6390011618174565918/device_logcat_1302097394309452308.txt
-05-16 21:38:21 I/XmlResultReporter: Saved host_log log to /tmp/0/inv_6390011618174565918/host_log_4255420317120216614.txt
-…
-</code></pre>
-<p>Note the log message indicating the path of the host log. View the contents of that file, and you
-should see your HelloWorldTest log message</p>
-<pre><code>$ more /tmp/0/inv_6390011618174565918/host_log_4255420317120216614.txt
-…
-05-16 21:38:21 I/HelloWorldTest: Hello world, TF! I have a device 30315E38655500EC
-</code></pre>
-<p>The TradeFederation framework will also automatically capture the logcat from the allocated device,
-and send it the the result_reporter for processing. XmlResultReporter will save the captured device
-logcat as a file.</p>
-<h2 id="command-line-options">Command line options</h2>
-<p>Objects loaded from a TradeFederation Configuration (aka "Configuration objects") also have the
-ability to receive data from command line arguments.</p>
-<p>This is accomplished via the <code>@Option</code> annotation. To participate, a Configuration object class
-would apply the <code>@Option</code> annotation to a member field, and provide it a unique name. This would
-allow that member field's value to be populated via a command line option, and would also
-automatically add that option to the configuration help system (Note: not all field types are
-supported: see the OptionSetter javadoc for a description of supported types).</p>
-<p>Lets add an Option to the HelloWorldTest.</p>
-<pre><code>@Option(name="my_option",
- shortName='m',
- description="this is the option's help text",
- // always display this option in the default help text
- importance=Importance.ALWAYS)
-private String mMyOption = "thisisthedefault";
-</code></pre>
-<p>And lets add a log message to display the value of the option in HelloWorldTest, so we can
-demonstrate that it was received correctly.</p>
-<pre><code>@SuppressWarnings("unchecked")
-@Override
-public void run(ITestInvocationListener listener) throws DeviceNotAvailableException {
- …
- Log.logAndDisplay(LogLevel.INFO, "HelloWorldTest", "I received this option " + mMyOption);
-</code></pre>
-<p>Rebuild TF and run helloworld: you should see a log message with the my_option's default value.</p>
-<pre><code>tf> run example/helloworld
-…
-05-24 18:30:05 I/HelloWorldTest: I received this option thisisthedefault
-</code></pre>
-<p>Now pass in a value for my_option: you should see my_option getting populated with that value</p>
-<pre><code>tf> run example/helloworld --my_option foo
-…
-05-24 18:33:44 I/HelloWorldTest: I received this option foo
-</code></pre>
-<p>TF configurations also include a help system, which automatically displays help text for @Option
-fields. Try it now, and you should see the help text for 'my_option':</p>
-<pre><code>tf> run --help example/helloworld
-Printing help for only the important options. To see help for all options, use the --help-all flag
-
- cmd_options options:
- --[no-]help display the help text for the most important/critical options. Default: false.
- --[no-]help-all display the full help text for all options. Default: false.
- --[no-]loop keep running continuously. Default: false.
-
- test options:
- -m, --my_option this is the option's help text Default: thisisthedefault.
-
- 'file' logger options:
- --log-level-display the minimum log level to display on stdout. Must be one of verbose, debug, info, warn, error, assert. Default: error.
-</code></pre>
-<p>FIXME: redo with enum help</p>
-<p>Note the message at the top about 'printing only the important options'. To reduce option help
-clutter, TF uses the Option#importance attribute to determine whether to show an Option's help text
-when '--help' is specified. '--help-all' will always show all options' help regardless of
-importance. See Option.Importance javadoc for details.</p>
-<p>You can also specify an Option's value within the configuration xml by adding a
-<code><option name="" value=""></code> element. Lets see how this looks in the helloworld.xml:</p>
-<pre><code><test class="com.android.tradefed.example.HelloWorldTest" >
- <option name="my_option" value="fromxml" />
-</test>
-</code></pre>
-<p>Re-building and running helloworld should now produce this output:</p>
-<pre><code>05-24 20:38:25 I/HelloWorldTest: I received this option fromxml
-</code></pre>
-<p>The configuration help should also be updated to indicate my_option's new default value:</p>
-<pre><code>tf> run --help example/helloworld
- test options:
- -m, --my_option this is the option's help text Default: fromxml.
-</code></pre>
-<p>Also note that other configuration objects included in the helloworld config, like FileLogger, also have options. '--log-level-display' is of interest because it filters the logs that show up on stdout. You may have noticed from earlier in the tutorial the 'Hello world, TF! I have a device ..' log message stopped getting displayed on stdout once we switched to using FileLogger. You can increase the verbosity of logging to stdout by passing in log-level-display arg.</p>
-<p>Try this now, and you should see the 'I have a device' log message reappear on stdout, in addition to getting logged to a file.</p>
-<pre><code>tf >run --log-level-display info example/helloworld
-…
-05-24 18:53:50 I/HelloWorldTest: Hello world, TF! I have a device XXXXXX
-</code></pre>
diff --git a/src/source/build-numbers.jd b/src/source/build-numbers.jd
index c9b6607..cf33d51 100644
--- a/src/source/build-numbers.jd
+++ b/src/source/build-numbers.jd
@@ -421,15 +421,35 @@
<td>android-4.2_r1</td>
<td>Galaxy Nexus, Nexus 7, Nexus 4, Nexus 10</td>
</tr>
+
<tr>
<td>JOP40D</td>
<td>android-4.2.1_r1</td>
+<td>Galaxy Nexus, Nexus 7, Nexus 4, Nexus 10</td>
+</tr>
+
+<tr>
+<td>JOP40F</td>
+<td>android-4.2.1_r1.1</td>
+<td>Nexus 10</td>
+</tr>
+
+<tr>
+<td>JOP40G</td>
+<td>android-4.2.1_r1.2</td>
+<td>Nexus 4</td>
+</tr>
+
+<tr>
+<td>JDQ39</td>
+<td>android-4.2.2_r1</td>
<td>latest Jelly Bean version, Galaxy Nexus, Nexus 7, Nexus 4, Nexus 10</td>
</tr>
+
</tbody>
</table>
<p>The branches froyo, gingerbread, ics-mr0, ics-mr1, jb-dev,
-jb-mr1-dev,
+jb-mr1-dev, jb-mr1.1-dev
represent development
branches that do not exactly match configurations that were tested
by Google. They might contain a variety of changes in addition to
@@ -465,7 +485,7 @@
<td></td>
</tr>
<tr>
-<td>HRI93</td>
+<td>HRI83</td>
<td>android-3.0_r1.3</td>
<td></td>
</tr>
diff --git a/src/source/building-devices.jd b/src/source/building-devices.jd
index 077d448..bbf49ba 100644
--- a/src/source/building-devices.jd
+++ b/src/source/building-devices.jd
@@ -27,41 +27,37 @@
<p>This page complements the main page about
<a href="building-running.html">Building and Running</a> with
information that is specific to individual devices.</p>
+
<p>With the current release, it is possible to build for
-Nexus 10, for Nexus 7 (Wi-Fi), and for some variants of Galaxy Nexus.
+Nexus 4, Nexus 10, Nexus 7, and for some variants of Galaxy Nexus.
The exact level of functionality for each device depends on the availability
of the relevant proprietary hardware-specific binaries.</p>
-<p>All configurations of Nexus 10 can be used. On those devices, graphics, audio,
+<p>For Nexus 4 "mako" and on Nexus 7 "grouper" (Wi-Fi) and "tilapia" (Mobile),
+all configurations can be used,
+and all the hardware is functional.
+Due to hardware differences, do not use 4.1.1 on a Nexus 7 that
+was originally sold with 4.1.2 or newer.</p>
+<p>All configurations of Nexus 10 "manta" can be used. On those devices, graphics, audio,
Wi-Fi, Bluetooth, camera, NFC, GPS and orientation sensors are functional.</p>
-<p>Nexus 4 cannot be used at the moment.</p>
-<p>The Wi-Fi variants of Nexus 7 can be used. On Nexus 7, graphics and audio are
-functional, as well as Wi-Fi and Bluetooth. Due to hardware differences, do
-not use 4.1.1 on a Nexus 7 that was originally sold with 4.1.2 or newer.
-The Mobile variant is not supported.</p>
<p>The variants of Galaxy Nexus that can be used are the GSM/HSPA+ configuration
"maguro" (only if it was originally sold with a "yakju" or "takju" operating
system) and the VZW CDMA/LTE configuration "toro". On those devices, graphics
and audio are functional, as well as Wi-Fi, Bluetooth, and access to the
respective cellular networks. NFC and the orientation sensors are functional.</p>
<p>The Sprint CDMA/LTE configuration "toroplus" of Galaxy Nexus is supported
-experimentally. On that configuration, the cellular network is not functional,
+experimentally, in the jb-mr1-dev-plus-aosp branch. On that configuration,
+the cellular network is not functional,
and the other peripherals work like they do on "toro".</p>
<p>The Motorola Xoom can be used in the Wi-Fi configuration "wingray"
sold in the USA, with Android 4.1.2. Graphics and audio are functional
as well as Wi-Fi and Bluetooth and the orientation sensors.</p>
<p>All configurations of Nexus S and Nexus S 4G can be used with Android 4.1.2.
-On those devices all the peripherals are functional: graphics, audio, Wi-Fi,
-Bluetooth, cell networks, sensors, camera, hardware codecs, NFC, GPS.</p>
+On those devices all the hardware is functional.</p>
<p>In addition, <a href="http://pandaboard.org">PandaBoard</a> a.k.a. "panda" can be used
-in the master branch, but is considered experimental.
+in the jb-mr1-dev-plus-aosp branch, but is considered experimental.
The specific details to use a PandaBoard with the Android Open-Source Project
are in the file <code>device/ti/panda/README</code> in the source tree.</p>
-<p>Nexus One a.k.a. "passion" is obsolete, was experimental in gingerbread,
-and can't be used with newer versions of the Android Open-Source
-Project.</p>
-<p>Android Developer Phones (ADP1 and ADP2, a.k.a. "dream" and "sapphire") are
-obsolete, were experimental in froyo, and can't be used with
-newer versions of the Android Open-Source Project.</p>
+
<h2 id="building-fastboot-and-adb">Building fastboot and adb</h2>
<p>If you don't already have those tools, fastboot and adb can be built with
the regular build system. Follow the instructions on the page about
@@ -156,14 +152,12 @@
<p>The Android Open-Source Project can't be used
from pure source code only, and requires additional hardware-related proprietary
libraries to run, specifically for hardware graphics acceleration.</p>
-<p>Official binaries for Nexus S, Nexus S 4G, Galaxy Nexus, Nexus 7, Nexus 4,
-Nexus 10 and PandaBoard
-can be downloaded from
+<p>Official binaries for the supported devices can be downloaded from
<a href="https://developers.google.com/android/nexus/drivers">Google's Nexus driver page</a>,
which add access to additional hardware capabilities with non-Open-Source code.</p>
-<p>When using the master branch for a device, the binaries for the most
-recent numbered release are the ones that should be used in the master
-branch.</p>
+<p>When building the master branch for a device, the binaries for the most
+recent numbered release or with the most recent date
+are the ones that should be used.</p>
<h3 id="extracting-the-proprietary-binaries">Extracting the proprietary binaries</h3>
<p>Each set of binaries comes as a self-extracting script in a compressed archive.
After uncompressing each archive, run the included self-extracting script
@@ -178,7 +172,7 @@
</code></pre>
<h2 id="picking-and-building-the-configuration-that-matches-a-device">Picking and building the configuration that matches a device</h2>
<p>The steps to configure and build the Android Open-Source Project
-are described in the page about <a href="building-running.html">Building and Running</a>.</p>
+are described in the page about <a href="building.html">Building</a>.</p>
<p>The recommended builds for the various devices are available through
the lunch menu, accessed when running the <code>lunch</code> command with no arguments:</p>
<table>
@@ -192,27 +186,32 @@
<tbody>
<tr>
<td>manta</td>
-<td>android-4.2.1_r1 or master</td>
+<td>android-4.2.2_r1 or master</td>
<td>full_manta-userdebug</td>
</tr>
<tr>
+<td>mako</td>
+<td>android-4.2.2_r1 or master</td>
+<td>full_mako-userdebug</td>
+</tr>
+<tr>
<td>grouper</td>
-<td>android-4.2.1_r1 or master</td>
+<td>android-4.2.2_r1 or master</td>
<td>full_grouper-userdebug</td>
</tr>
<tr>
-<td>tipalia</td>
-<td>android-4.2.1_r1 or master</td>
-<td>full_tilapia-userdebug</td>
+<td>tilapia</td>
+<td>android-4.2.2_r1 or master</td>
+<td>full_grouper-userdebug</td>
</tr>
<tr>
<td>maguro</td>
-<td>android-4.2.1_r1 or master</td>
+<td>android-4.2.2_r1 or master</td>
<td>full_maguro-userdebug</td>
</tr>
<tr>
<td>toro</td>
-<td>android-4.2.1_r1 or master</td>
+<td>android-4.2.2_r1 or master</td>
<td>full_toro-userdebug</td>
</tr>
<tr>
@@ -264,11 +263,11 @@
for Nexus 10,
for Nexus 4,
for Nexus Q,
-for Nexus 7 (all variants),
+for Nexus 7,
for Galaxy Nexus (GSM/HSPA+ "yakju" and "takju",
and CDMA/LTE "mysid" and "mysidspr"),
and
-for Nexus S and Nexus S 4G (all variants)
+for Nexus S and Nexus S 4G
are available from
<a href="https://developers.google.com/android/nexus/images">Google's factory image page</a>.</p>
<p>Factory images for the Motorola Xoom are distributed directly by Motorola.</p>
\ No newline at end of file
diff --git a/src/source/building-kernels.jd b/src/source/building-kernels.jd
index 0b20a50..3cc6c1e 100644
--- a/src/source/building-kernels.jd
+++ b/src/source/building-kernels.jd
@@ -31,16 +31,98 @@
clone steps other than the step to download the actual kernel sources.</p>
<p>We will use the Pandaboard kernel in all the following examples.</p>
<h2 id="figuring-out-which-kernel-to-build">Figuring out which kernel to build</h2>
-<p>You will want to look at the git log for the kernel in the device project that
-you are interested in.
+<p>This table lists the name and locations of the kernel sources and binaries:
+<table>
+ <tr>
+ <th>Device</th>
+ <th>Binary location</th>
+ <th>Source location</th>
+ <th>Build configuration</th>
+ </tr>
+ <tr>
+ <td>manta</td>
+ <td>device/samsung/manta/kernel</td>
+ <td>kernel/exynos</td>
+ <td>manta_defconfig</td>
+ </tr>
+ <tr>
+ <td>mako</td>
+ <td>device/lge/mako-kernel/kernel</td>
+ <td>kernel/msm</td>
+ <td>mako_defconfig</td>
+ </tr>
+ <tr>
+ <td>grouper</td>
+ <td>device/asus/grouper/kernel</td>
+ <td>kernel/tegra</td>
+ <td>tegra3_android_defconfig</td>
+ </tr>
+ <tr>
+ <td>tilapia</td>
+ <td>device/asus/grouper/kernel</td>
+ <td>kernel/tegra</td>
+ <td>tegra3_android_defconfig</td>
+ </tr>
+ <tr>
+ <td>maguro</td>
+ <td>device/samsung/tuna/kernel</td>
+ <td>kernel/omap</td>
+ <td>tuna_defconfig</td>
+ </tr>
+ <tr>
+ <td>toro</td>
+ <td>device/samsung/tuna/kernel</td>
+ <td>kernel/omap</td>
+ <td>tuna_defconfig</td>
+ </tr>
+ <tr>
+ <td>panda</td>
+ <td>device/ti/panda/kernel</td>
+ <td>kernel/omap</td>
+ <td>panda_defconfig</td>
+ </tr>
+ <tr>
+ <td>stingray</td>
+ <td>device/moto/wingray/kernel</td>
+ <td>kernel/tegra</td>
+ <td>stingray_defconfig</td>
+ </tr>
+ <tr>
+ <td>wingray</td>
+ <td>device/moto/wingray/kernel </td>
+ <td>kernel/tegra</td>
+ <td>stingray_defconfig</td>
+ </tr>
+ <tr>
+ <td>crespo</td>
+ <td>device/samsung/crespo/kernel</td>
+ <td>kernel/samsung</td>
+ <td>herring_defconfig</td>
+ </tr>
+ <tr>
+ <td>crespo4g</td>
+ <td>device/samsung/crespo/kernel</td>
+ <td>kernel/samsung</td>
+ <td>herring_defconfig</td>
+ </tr>
+</table>
+
+<p>You will want to look at the git log for the kernel binary in the device
+project that you are interested in.</p>
+
+
+
Device projects are of the form device/<vendor>/<name>.</p>
<pre><code>$ git clone https://android.googlesource.com/device/ti/panda
$ cd panda
-$ git log kernel
+$ git log --max-count=1 kernel
</code></pre>
-<p>The log should contain notes of the commit SHA1 for the appropriate
-kernel project. Keep this value at hand so that you can use it in
-a later step.</p>
+
+<p>The commit message for the kernel binary contains a partial git log
+of the kernel sources that were used to build the binary in question.
+The first entry in the log is the most recent, i.e. the one used to
+build that kernel. You will need it at a later step.</p>
+
<h2 id="downloading-sources">Downloading sources</h2>
<p>Depending on which kernel you want,</p>
<pre><code>$ git clone https://android.googlesource.com/kernel/common.git
@@ -67,9 +149,15 @@
</ul>
<h2 id="downloading-a-prebuilt-gcc">Downloading a prebuilt gcc</h2>
<p>Ensure that the prebuilt toolchain is in your path.</p>
-<pre><code>$ git clone https://android.googlesource.com/platform/prebuilt
-$ export PATH=$(pwd)/prebuilt/linux-x86/toolchain/arm-eabi-4.4.3/bin:$PATH
-</code></pre>
+<pre>$ export PATH=$(pwd)/prebuilts/gcc/linux-x86/arm/arm-eabi-4.6/bin:$PATH</pre>
+
+or
+<pre>$ export PATH=$(pwd)/prebuilts/gcc/darwin-x86/arm/arm-eabi-4.6/bin:$PATH</pre>
+
+<p>On a linux host, if you don't have an Android source tree, you can download
+the prebuilt toolchain from:
+<pre>$ git clone https://android.googlesource.com/platform/prebuilts/gcc/linux-x86/arm/arm-eabi-4.6</pre>
+
<h2 id="building">Building</h2>
<p>As an example, we would build the panda kernel using the following commands:</p>
<pre><code>$ export ARCH=arm
@@ -82,14 +170,7 @@
</code></pre>
<p>To build the tuna kernel, you may run the previous commands replacing all
instances of "panda" with "tuna".</p>
-<ul>
-<li>The kernel for mantaray is <code>device/samsung/manta/kernel</code></li>
-<li>The kernel for mako is <code>device/lge/mako-kernel/kernel</code></li>
-<li>The kernel for grouper and tilapia is <code>device/asus/grouper/kernel</code></li>
-<li>The kernel for maguro and toro is <code>device/samsung/tuna/kernel</code></li>
-<li>The kernel for crespo and crespo4g is <code>device/samsung/crespo/kernel</code></li>
-<li>The kernel for stingray and wingray is <code>device/moto/wingray/kernel</code></li>
-</ul>
-<p>The image is output as <code>arch/arm/boot/zImage</code>. You may copy it as
-<code>device/<vendor>/<name>/kernel</code> or <code>device/ti/panda/kernel</code> in the case of this
-example.</p>
+<p>
+The kernel binary is output as `arch/arm/boot/zImage`, and needs to be copied
+into the Android source tree in order to build the matching boot image.
+</p>
\ No newline at end of file
diff --git a/src/source/downloading.jd b/src/source/downloading.jd
index 7376d41..6d4212e 100644
--- a/src/source/downloading.jd
+++ b/src/source/downloading.jd
@@ -63,6 +63,9 @@
<p>
For version 1.17, the SHA-1 checksum for repo is ddd79b6d5a7807e911b524cb223bc3544b661c28
</p>
+<p>
+ For version 1.19, the SHA-1 checksum for repo is 92cbad8c880f697b58ed83e348d06619f8098e6c
+</p>
<h2 id="initializing-a-repo-client">
Initializing a Repo client
</h2>
diff --git a/src/source/initializing.jd b/src/source/initializing.jd
index 029f308..f53e6fb 100644
--- a/src/source/initializing.jd
+++ b/src/source/initializing.jd
@@ -24,11 +24,50 @@
</div>
</div>
-<p>Before you begin, ensure that your system meets the <a href="{@docRoot}source/building.html">minimum requirements</a>.
-
-<h2 id="setup-linux">Setting up a Linux Build Environment</h2>
-
-<h3 id="installing-the-jdk">Installing the JDK</h3>
+<h1 id="initializing-a-build-environment">Initializing a Build Environment</h1>
+<p>The "Getting Started" section describes how to set up your local work environment, how to use Repo to get the Android files, and how to build the files on your machine. To build the Android source files, you will need to use Linux or Mac OS. Building under Windows is not currently supported.</p>
+<p><em>Note: The source download is approximately 8.5GB in size.
+You will need over 30GB free to complete a single build, and
+up to 100GB (or more) for a full set of builds.</em></p>
+<p>For an overview of the entire code-review and code-update process, see <a href="life-of-a-patch.html">Life of a Patch</a>.</p>
+<h1 id="choosing-a-branch">Choosing a Branch</h1>
+<p>Some of the requirements for your build environment are determined by which
+version of the source code you plan to compile. See
+<a href="build-numbers.html">Build Numbers</a> for a full listing of branches you may
+choose from. You may also choose to download and build the latest source code
+(called "master"), in which case you will simply omit the branch specification
+when you initialize the repository.</p>
+<p>Once you have selected a branch, follow the appropriate instructions below to
+set up your build environment.</p>
+<h1 id="setting-up-a-linux-build-environment">Setting up a Linux build environment</h1>
+<p>These instructions apply to all branches, including master.</p>
+<p>The Android build is routinely tested in house on recent versions of
+Ubuntu LTS (10.04), but most distributions should have the required
+build tools available. Reports of successes or failures on other
+distributions are welcome.</p>
+<p>For Gingerbread (2.3.x) and newer versions, including the master
+branch, a 64-bit environment is required. Older versions can be
+compiled on 32-bit systems.</p>
+<p><em>Note: It is also possible to build Android in a virtual machine.
+If you are running Linux in a virtual machine, you will need at
+least 16GB of RAM/swap and 30GB or more of disk space in order to
+build the Android tree.</em></p>
+<p>Detailed instructions for Ubuntu and MacOS follow. In general you will need:</p>
+<ul>
+<li>
+<p>Python 2.6 -- 2.7, which you can download from <a href="http://www.python.org/download/">python.org</a>.</p>
+</li>
+<li>
+<p>GNU Make 3.81 -- 3.82, which you can download from <a href="http://ftp.gnu.org/gnu/make/">gnu.org</a>,</p>
+</li>
+<li>
+<p>JDK 6 if you wish to build Gingerbread or newer; JDK 5 for Froyo or older. You can download both from <a href="http://java.sun.com/javase/downloads/">java.sun.com</a>.</p>
+</li>
+<li>
+<p>Git 1.7 or newer. You can find it at <a href="http://git-scm.com/download">git-scm.com</a>.</p>
+</li>
+</ul>
+<h2 id="installing-the-jdk">Installing the JDK</h2>
<p>The Sun JDK is no longer in Ubuntu's main package repository. In order to download it, you need to add the appropriate repository and indicate to the system which JDK should be used.</p>
<p>Java 6: for Gingerbread and newer</p>
<pre><code>$ sudo add-apt-repository "deb http://archive.canonical.com/ lucid partner"
@@ -43,7 +82,7 @@
</code></pre>
<p><em>Note: The <code>lunch</code> command in the build step will ensure that the Sun JDK is
used instead of any previously installed JDK.</em></p>
-<h3 id="installing-required-packages-ubuntu-1004-1110">Installing required packages (Ubuntu 10.04 -- 11.10)</h3>
+<h2 id="installing-required-packages-ubuntu-1004-1110">Installing required packages (Ubuntu 10.04 -- 11.10)</h2>
<p>You will need a 64-bit version of Ubuntu. Ubuntu 10.04 is recommended.
Building using a newer version of Ubuntu is currently only experimentally
supported and is not guaranteed to work on branches other than master.</p>
@@ -59,17 +98,17 @@
<p>On Ubuntu 11.10:</p>
<pre><code>$ sudo apt-get install libx11-dev:i386
</code></pre>
-<h3 id="installing-required-packages-ubuntu-1204">Installing required packages (Ubuntu 12.04)</h3>
+<h2 id="installing-required-packages-ubuntu-1204">Installing required packages (Ubuntu 12.04)</h2>
<p>Building on Ubuntu 12.04 is currently only experimentally supported and is not
guaranteed to work on branches other than master.</p>
<pre><code>$ sudo apt-get install git gnupg flex bison gperf build-essential \
zip curl libc6-dev libncurses5-dev:i386 x11proto-core-dev \
libx11-dev:i386 libreadline6-dev:i386 libgl1-mesa-glx:i386 \
- libgl1-mesa-dev g++-multilib mingw32 openjdk-6-jdk tofrodos \
+ libgl1-mesa-dev g++-multilib mingw32 tofrodos \
python-markdown libxml2-utils xsltproc zlib1g-dev:i386
$ sudo ln -s /usr/lib/i386-linux-gnu/mesa/libGL.so.1 /usr/lib/i386-linux-gnu/libGL.so
</code></pre>
-<h3 id="configuring-usb-access">Configuring USB Access</h3>
+<h2 id="configuring-usb-access">Configuring USB Access</h2>
<p>Under GNU/linux systems (and specifically under Ubuntu systems),
regular users can't directly access USB devices by default. The
system needs to be configured to allow such access.</p>
@@ -106,9 +145,9 @@
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e42", MODE="0600", OWNER="<username>"
# fastboot protocol on grouper/tilapia (Nexus 7)
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e40", MODE="0600", OWNER="<username>"
-# adb protocol on mako/manta (Nexus 4, Nexus 10)
+# adb protocol on manta (Nexus 10)
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4ee2", MODE="0600", OWNER="<username>"
-# fastboot protocol on mako/manta (Nexus 4, Nexus 10)
+# fastboot protocol on manta (Nexus 10)
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4ee0", MODE="0600", OWNER="<username>"
</code></pre>
<p>Those new rules take effect the next time a device is plugged in.
@@ -118,7 +157,7 @@
Lucid Lynx (10.04.x LTS). Other versions of Ubuntu or other
variants of GNU/linux might require different configurations.</p>
<p><a name="ccache"></a></p>
-<h3 id="setting-up-ccache">Setting up ccache</h3>
+<h2 id="setting-up-ccache">Setting up ccache</h2>
<p>You can optionally tell the build to use the ccache compilation tool.
Ccache acts as a compiler cache that can be used to speed-up rebuilds.
This works very well if you do "make clean" often, or if you frequently
@@ -141,7 +180,7 @@
<pre><code>prebuilt/linux-x86/ccache/ccache -M 50G
</code></pre>
<p>This setting is stored in the CCACHE_DIR and is persistent.</p>
-<h3 id="using-a-separate-output-directory">Using a separate output directory</h3>
+<h2 id="using-a-separate-output-directory">Using a separate output directory</h2>
<p>By default, the output of each build is stored in the out/
subdirectory of the matching source tree.</p>
<p>On some machines with multiple storage devices, builds are
@@ -167,7 +206,7 @@
unpredictable results.</p>
<p>This is only supported on Jelly Bean (4.1) and newer,
including the master branch.</p>
-<h2 id="setting-up-a-mac-os-x-build-environment">Setting up a Mac OS X build environment</h2>
+<h1 id="setting-up-a-mac-os-x-build-environment">Setting up a Mac OS X build environment</h1>
<p>In a default installation, OS X runs on a case-preserving but case-insensitive
filesystem. This type of filesystem is not supported by git and will cause some
git commands (such as "git status") to behave abnormally. Because of this, we
@@ -191,14 +230,14 @@
function mountAndroid { hdiutil attach ~/android.dmg -mountpoint /Volumes/android; }
</code></pre>
<p>Once mounted, you'll do all your work in the "android" volume. You can eject it (unmount it) just like you would with an external drive.</p>
-<h3 id="master-branch">Master branch</h3>
+<h2 id="master-branch">Master branch</h2>
<p>To build the latest source in a Mac OS environment, you will need an Intel/x86
machine running MacOS 10.6 (Snow Leopard) or MacOS 10.7 (Lion), along with Xcode
4.2 (Apple's Developer Tools). Although Lion does not come with a JDK, it should
install automatically when you attempt to build the source.</p>
<p>The remaining sections for Mac OS X only apply to those who wish to build
earlier branches.</p>
-<h3 id="branch-40x-and-all-earlier-branches">Branch 4.0.x and all earlier branches</h3>
+<h2 id="branch-40x-and-all-earlier-branches">Branch 4.0.x and all earlier branches</h2>
<p>To build android-4.0.x and earlier branches in a Mac OS environment, you need an
Intel/x86 machine running MacOS 10.5 (Leopard) or MacOS 10.6 (Snow Leopard). You
will need the MacOS 10.5 SDK.</p>
@@ -255,8 +294,11 @@
</li>
</ul>
<h3 id="setting-a-file-descriptor-limit">Setting a file descriptor limit</h3>
-<p>On MacOS the default limit on the number of simultaneous file descriptors open is too low and a highly parallel build process may exceed this limit. </p>
+<p>On MacOS the default limit on the number of simultaneous file descriptors open is too low and a highly parallel build process may exceed this limit.<br />
+</p>
<p>To increase the cap, add the following lines to your <code>~/.bash_profile</code>: </p>
<pre><code># set the number of open files to be 1024
ulimit -S -n 1024
</code></pre>
+<h1 id="next-download-the-source">Next: Download the source</h1>
+<p>Your build environment is good to go! Proceed to <a href="downloading.html">downloading the source</a>....</p>
\ No newline at end of file
diff --git a/src/source/known-issues.jd b/src/source/known-issues.jd
index 33ceb16..a68dde6 100644
--- a/src/source/known-issues.jd
+++ b/src/source/known-issues.jd
@@ -26,6 +26,15 @@
<p>Even with our best care, small problems sometimes slip in. This page keeps
track of the known issues around using the Android source code.</p>
+
+<h2 id="missing-cellbroadcastreceiver">Missing CellBroadcastReceiver in toro builds</h2>
+<p><strong>Symptom</strong></p>On AOSP builds for toro (up to Jelly Bean 4.2.1),
+CellBroadcastReceiver doesn't get included in the system.</p>
+
+<p><strong>Cause:</strong></p> There's a typo in <code>vendor/samsung/toro/device-partial.mk</code>,
+where <code>PRODUCT_PACKAGES</code> has the K replaced by an H.
+<p><strong>Fix</strong>: Use the latest packages for 4.2.2, or manually fix the typo.</p>
+
<h2 id="missing-cts-native-xml-generator">Missing CTS Native XML Generator</h2>
<p><strong>Symptom</strong>: On some builds of IceCreamSandwich and later, the following
warning is printed early during the build:
diff --git a/src/source/submit-patches.jd b/src/source/submit-patches.jd
index 6d555c5..11fecca 100644
--- a/src/source/submit-patches.jd
+++ b/src/source/submit-patches.jd
@@ -185,6 +185,17 @@
<p>All changes to the ICU4C project at <code>external/icu4c</code> should be made upstream at
<a href="http://site.icu-project.org/">icu-project.org/</a>.
See <a href="http://site.icu-project.org/bugs">Submitting ICU Bugs and Feature Requests</a> for more.</p>
+
+<h2 id="llvmclangcompiler-rt">LLVM/Clang/Compiler-rt</h2>
+<p>All changes to LLVM-related projects (<code>external/clang</code>, <code>external/compiler-rt</code>,
+<code>external/llvm</code>) should be made upstream at
+<a href="http://llvm.org/">llvm.org/</a>.</p>
+
+<h2 id="mksh">
+<p>All changes to the MirBSD Korn Shell project at <code>external/mksh</code> should be made upstream
+either by sending an email to miros-mksh on the mirbsd.o®g domain (no subscription
+required to submit there) or (optionally) at <a href="https://launchpad.net/mksh">Launchpad</a>.
+</p>
<h2 id="openssl">OpenSSL</h2>
<p>All changes to the OpenSSL project at <code>external/openssl</code> should be made upstream at
<a href="http://www.openssl.org">openssl.org</a>.</p>