am d62bf8fb: Reconcile with jb-release
* commit 'd62bf8fb254b3f27c0170c5d96424ae93afce5ad':
diff --git a/src/compatibility/4.0/versions.md b/src/compatibility/4.0/versions.md
index 1b70297..895b820 100644
--- a/src/compatibility/4.0/versions.md
+++ b/src/compatibility/4.0/versions.md
@@ -34,3 +34,5 @@
- 4.0.1
- 4.0.3
+
+- 4.0.4
diff --git a/src/compatibility/downloads.md b/src/compatibility/downloads.md
index 7072e65..fb7c7a8 100644
--- a/src/compatibility/downloads.md
+++ b/src/compatibility/downloads.md
@@ -26,8 +26,8 @@
Android 4.0.3 is found in the 'android-4.0.3_r1' branch in the open-source tree.
- [Android 4.0 Compatibility Definition Document (CDD)](4.0/android-4.0-cdd.pdf)
-- [Android 4.0.3 R2 Compatibility Test Suite (CTS)](https://dl.google.com/dl/android/cts/android-cts-4.0.3_r2-linux_x86-arm.zip)
-- [Android 4.0.3 R1 CTS Verifier](https://dl.google.com/dl/android/cts/android-cts-verifier-4.0.3_r1-linux_x86-arm.zip)
+- [Android 4.0.3 R3 Compatibility Test Suite (CTS)](https://dl.google.com/dl/android/cts/android-cts-4.0.3_r3-linux_x86-arm.zip)
+- [Android 4.0.3 R2 CTS Verifier](https://dl.google.com/dl/android/cts/android-cts-verifier-4.0.3_r2-linux_x86-arm.zip)
## Android 2.3 ##
@@ -36,8 +36,8 @@
the open-source tree.
- [Android 2.3 Compatibility Definition Document (CDD)](2.3/android-2.3.3-cdd.pdf)
-- [Android 2.3 R12 Compatibility Test Suite (CTS)](https://dl.google.com/dl/android/cts/android-cts-2.3_r12-linux_x86-arm.zip)
-- [Android 2.3 R2 CTS Verifier](https://dl.google.com/dl/android/cts/android-cts-verifier-2.3_r2-linux_x86-armv5.zip)
+- [Android 2.3 R13 Compatibility Test Suite (CTS)](https://dl.google.com/dl/android/cts/android-cts-2.3_r13-linux_x86-arm.zip)
+- [Android 2.3 R3 CTS Verifier](https://dl.google.com/dl/android/cts/android-cts-verifier-2.3_r3-linux_x86-armv5.zip)
## Android 2.2 ##
diff --git a/src/index.md b/src/index.md
index 54319bf..0ebaad9 100644
--- a/src/index.md
+++ b/src/index.md
@@ -28,14 +28,12 @@
and researchers to develop custom builds. For information on how to obtain the
software, visit our [Getting the Source](source/downloading.html) page.
-### Compatibility Definition for Android 2.3 ###
+### Compatibility Definition for Android 4.0 ###
-The Compatibility Definition Document for Android 2.3.3 has been published.
-Android 2.3 allows device manufacturers to use the Android source code to ship
-a significantly wider variety of devices, including devices with extra-large
-screens, such as tablets. Android 2.3.3 adds enhanced Near-Field
-Communications support to the Android APIs. For more information, visit the
-[Compatibility](compatibility/index.html) page.
+The Compatibility Definition Document for Android 4.0 has been published.
+Android 4.0 allows device manufacturers to use the Android source code to ship
+a significantly wider variety of devices including phones and tablets.
+For more information, visit the [Compatibility](compatibility/index.html) page.
</div>
diff --git a/src/source/build-numbers.md b/src/source/build-numbers.md
index b0d581b..06a9559 100644
--- a/src/source/build-numbers.md
+++ b/src/source/build-numbers.md
@@ -112,7 +112,9 @@
IML77 | android-4.0.3_r1.1 |
IMM76 | android-4.0.4_r1 |
IMM76D | android-4.0.4_r1.1 | Nexus S, Nexus S 4G, Galaxy Nexus
-IMM76I | android-4.0.4_r1.2 | Galaxy Nexus, latest IceCreamSandwich version
+IMM76I | android-4.0.4_r1.2 | Galaxy Nexus
+IMM76K | android-4.0.4_r2 | Galaxy Nexus
+IMM76L | android-4.0.4_r2.1 | latest IceCreamSandwich version
The branches froyo, gingerbread, ics-mr0, ics-mr1, represent development
branches that do not exactly match configurations that were tested
diff --git a/src/source/building-devices.md b/src/source/building-devices.md
index bf3132a..1de1e61 100644
--- a/src/source/building-devices.md
+++ b/src/source/building-devices.md
@@ -145,10 +145,10 @@
Device | Branch | Build configuration
---------|------------------------------|------------------------
-maguro | android-4.0.4_r1.2 or master | full_maguro-userdebug
+maguro | android-4.0.4_r2.1 or master | full_maguro-userdebug
panda | master | full_panda-userdebug
-wingray | android-4.0.4_r1.2 or master | full_wingray-userdebug
-crespo | android-4.0.4_r1.2 or master | full_crespo-userdebug
+wingray | android-4.0.4_r2.1 or master | full_wingray-userdebug
+crespo | android-4.0.4_r2.1 or master | full_crespo-userdebug
passion | android-2.3.7_r1 | full_passion-userdebug
sapphire | android-2.2.3_r1 | full_sapphire-userdebug
dream | android-2.2.3_r1 | full_dream-userdebug
@@ -205,6 +205,8 @@
4.0.3 (IML74K) | I9020XXKL1 | I9020XXKI1 | All previous versions
4.0.4 (IMM76D) | I9020XXKL1 | I9020XXKI1
4.0.4 (IMM76I) | I9020XXKL1 | I9020XXKI1
+4.0.4 (IMM76K) | I9020XXKL1 | I9020XXKI1
+4.0.4 (IMM76L) | I9020XXKL1 | I9020XXKI1
Nexus S (850MHz version "UC", i9020a):
@@ -218,6 +220,8 @@
4.0.3 (IML74K) | I9020XXKL1 | I9020UCKF1 | All previous versions
4.0.4 (IMM76D) | I9020XXKL1 | I9020UCKJ1
4.0.4 (IMM76I) | I9020XXKL1 | I9020UCKJ1
+4.0.4 (IMM76K) | I9020XXKL1 | I9020UCKJ1
+4.0.4 (IMM76L) | I9020XXKL1 | I9020UCKJ1
Nexus S (Korea version "KR", m200):
@@ -228,8 +232,10 @@
2.3.5 (GRJ90) | I9020XXKA3 | M200KRKC1 | All previous versions
2.3.6 (GRK39F) | I9020XXKA3 | M200KRKC1 | All previous versions
4.0.3 (IML74K) | I9020XXKL1 | M200KRKC1 | All previous versions
-4.0.4 (IMM76D) | I9020XXKL1 | M200KRKC1 | Versions from 2.3.6
-4.0.4 (IMM76I) | I9020XXKL1 | M200KRKC1 | Versions from 2.3.6
+4.0.4 (IMM76D) | I9020XXKL1 | M200KRKC1
+4.0.4 (IMM76I) | I9020XXKL1 | M200KRKC1
+4.0.4 (IMM76K) | I9020XXKL1 | M200KRKC1
+4.0.4 (IMM76L) | I9020XXKL1 | M200KRKC1
Galaxy Nexus (GSM/HSPA+):
@@ -238,8 +244,10 @@
4.0.1 (ITL41D) | PRIMEKJ10 | I9250XXKK1
4.0.2 (ICL53F) | PRIMEKK15 | I9250XXKK6 | All previous versions
4.0.3 (IML74K) | PRIMEKL01 | I9250XXKK6 | All previous versions
-4.0.4 (IMM76D) | PRIMEKL03 | I9250XXLA02
-4.0.4 (IMM76I) | PRIMEKL03 | I9250XXLA02
+4.0.4 (IMM76D) | PRIMELA03 | I9250XXLA02
+4.0.4 (IMM76I) | PRIMELA03 | I9250XXLA02
+4.0.4 (IMM76K) | PRIMELA03 | I9250XXLA02
+4.0.4 (IMM76L) | PRIMELA03 | I9250XXLA02
If you're building a new version of Android, if your Nexus S or
Galaxy Nexus has
diff --git a/src/source/building-kernels.md b/src/source/building-kernels.md
index 4987654..144a2f4 100644
--- a/src/source/building-kernels.md
+++ b/src/source/building-kernels.md
@@ -52,10 +52,18 @@
$ git clone https://android.googlesource.com/kernel/samsung.git
$ git clone https://android.googlesource.com/kernel/tegra.git
-The goldfish project contains the kernel sources for the emulated
-platforms. The msm project has the sources for ADP1, ADP2 and
-Nexus One. The omap project is used for PandaBoard and Galaxy Nexus,
-the samsung project for Nexus S, and the tegra project for Xoom.
+ - The `goldfish` project contains the kernel sources for the emulated
+platforms.
+ - The `msm` project has the sources for ADP1, ADP2, Nexus One, and
+can be used as a starting point for work on Qualcomm MSM chipsets.
+ - The `omap` project is used for PandaBoard and Galaxy Nexus, and
+can be used as a starting point for work on TI OMAP chipsets.
+ - The `samsung` project is used for Nexus S and can be used as a
+starting point for work on Samsung Hummingbird chipsets.
+ - The `tegra` project is for Xoom, and can be used as a starting
+point for work on NVIDIA Tegra chipsets.
+ - The `exynos` project can be used as a starting point for work
+on Samsung Exynos chipsets.
## Downloading a prebuilt gcc ##
@@ -80,6 +88,10 @@
To build the tuna kernel, you may run the previous commands replacing all
instances of "panda" with "tuna".
-The image is output as arch/arm/boot/zImage. You may copy it as
-device/<vendor>/<name>/kernel or device/ti/panda/kernel in the case of this
+ - The kernel for maguro and toro is `device/samsung/tuna/kernel`
+ - The kernel for crespo and crespo4g is `device/samsung/crespo/kernel`
+ - The kernel for stingray and wingray is `device/moto/wingray/kernel`
+
+The image is output as `arch/arm/boot/zImage`. You may copy it as
+`device/<vendor>/<name>/kernel` or `device/ti/panda/kernel` in the case of this
example.
diff --git a/src/source/downloading.md b/src/source/downloading.md
index 40e881b..7fabab5 100644
--- a/src/source/downloading.md
+++ b/src/source/downloading.md
@@ -32,8 +32,8 @@
$ curl https://dl-ssl.google.com/dl/googlesource/git-repo/repo > ~/bin/repo
$ chmod a+x ~/bin/repo
- - For version 1.16, the SHA-1 checksum for repo is
- 19ba8290344752da23e00cfb2b26afb43b463fe6
+ - For version 1.17, the SHA-1 checksum for repo is
+ ddd79b6d5a7807e911b524cb223bc3544b661c28
## Initializing a Repo client ##
diff --git a/src/tech/test_infra/index.md b/src/tech/test_infra/index.md
new file mode 100644
index 0000000..39ed155
--- /dev/null
+++ b/src/tech/test_infra/index.md
@@ -0,0 +1,20 @@
+<!--
+ Copyright 2012 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.
+-->
+
+# Test Infrastructure Technical Information #
+
+We make tests go vroom.
+
diff --git a/src/tech/test_infra/sidebar2.md b/src/tech/test_infra/sidebar2.md
new file mode 100644
index 0000000..1ddf988
--- /dev/null
+++ b/src/tech/test_infra/sidebar2.md
@@ -0,0 +1,5 @@
+# Infrastructure Components #
+
+- [Trade Federation](/tech/test_infra/tradefed/index.html)
+- [Notifilter](/tech/test_infra/notifilter.html)
+
diff --git a/src/tech/test_infra/tradefed/commandfile_format.md b/src/tech/test_infra/tradefed/commandfile_format.md
new file mode 100644
index 0000000..88c0a74
--- /dev/null
+++ b/src/tech/test_infra/tradefed/commandfile_format.md
@@ -0,0 +1,133 @@
+<!--
+ Copyright 2012 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.
+-->
+
+# Command File Format
+
+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.
+
+
+## Lines
+
+The format is line-based.
+
+* Each output line will be considered as the arguments for a single Configuration for Trade
+ Federation to run.
+* Each input line will turn into one or more output lines.
+
+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.
+
+
+## Macros
+
+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
+
+* The name of a macro must begin with an alpha character. Each subsequent character may be any
+ alphanumeric, an underscore, or a hyphen.
+* A macro with name "macro_name" is invoked by adding macro_name() as an argument on some subsequent
+ line.
+* The macro format does not support passing arguments to macros. It allows only concatenation.
+* 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.
+* The parser currently has a hard limit of 10 iterations of expansion. This will be made
+ configurable at some point.
+* During a single iteration of expansion:
+ * 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
+ * Only one long macro invocation on a line will be expanded. This will be the left-most long
+ macro invocation.
+
+
+## Short Macros
+
+A short macro can be defined with the syntax:
+
+ MACRO macro_name = this is the macro expansion
+
+The macro expansion terminates at the end of the line. For multi-line expansion, see Long Macros
+below.
+
+### Short Macro Expansion
+
+* `a macro_name() invocation`<br />
+ will be replaced by<br />
+ `a this is the macro expansion invocation`
+* `three macro_name() A macro_name() B macro_name()`<br />
+ will be replaced by (all during the first iteration)<br />
+ `three this is the macro expansion A this is the macro expansion B this is the macro expansion`
+
+
+## Long Macros
+
+A long macro can be defined with the syntax:
+
+ LONG MACRO macro_name
+ expansion line 1
+ expansion line 2
+ expansion line 3
+ END MACRO
+
+The macro is then invoked with th enormal `macro_name()` syntax. Leading whitespace/indentation
+will be ignored.
+
+### Long Macro Expansion
+
+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:
+
+* 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.
+* 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.
+
+* Example 1:
+
+ a macro_name() invocation
+
+ will be replaced by (in a single iteration)
+
+ a expansion line 1 invocation
+ a expansion line 2 invocation
+ a expansion line 3 invocation
+
+* Example 2:
+
+ alpha macro_name() beta macro_name()
+
+ will be replaced by (during the first iteration)
+
+ alpha expansion line 1 beta macro_name()
+ alpha expansion line 2 beta macro_name()
+ alpha expansion line 3 beta macro_name()
+
+ which will be replaced by (during the second iteration)
+
+ 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
+
diff --git a/src/tech/test_infra/tradefed/getting_started.md b/src/tech/test_infra/tradefed/getting_started.md
new file mode 100644
index 0000000..4735aa5
--- /dev/null
+++ b/src/tech/test_infra/tradefed/getting_started.md
@@ -0,0 +1,249 @@
+<!--
+ Copyright 2012 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.
+-->
+
+# Getting Started
+
+## Using the console
+
+TF is based around an interactive console. You can fire up the console by going to the
+`tools/tradefederation/` directory and running
+
+ $ ./tradefed.sh
+
+You should end up at a `tf >` prompt.
+
+The console is self-documenting. Try entering "help"
+
+ 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
+ [...]
+
+As the help text suggests, the help menus are organized hierarchically
+
+ tf >help list
+ l(?:ist)? help:
+ i[nvocations] List all invocation threads
+ d[evices] List all detected or known devices
+ [...]
+
+The majority of commands have a convenient short form, which the help text displays. The
+`l(?:ist)?` is a regular expression. As an example, here are the four equivalent ways to list
+invocations:
+* `list invocations`
+* `list i`
+* `l invocations`
+* `l i`
+
+
+## Running a config/command
+
+This is documented by the `help run` command in the console.
+
+As a reminder, a command is a config along with all of its command-line arguments. A command *must*
+begin with the name of the respective config.
+
+As a quick example, you could run the calculator unit tests like so:
+
+ $./tradefed.sh
+ tf >run instrument --package com.android.calculator2.tests
+
+As a shortcut, if you specify any arguments to `tradefed.sh`, it will attempt to execute them as if
+they were typed on the commandline. So the short version of the above would be
+
+ $./tradefed.sh run instrument --package com.android.calculator2.tests
+
+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".
+
+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 `list configs` 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 `dump config <configname>` console
+command.
+
+### So, let's say you want to run the calculator instrumentation tests, but don't know where to start.
+
+You could try something like this sequence of steps. First, look for a config that looks like it
+might do what you want:
+
+ 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
+ [...]
+
+Now that you've found something reasonable-looking, see what options it takes. The `list configs` output suggests trying `run command instrument --help`
+
+ 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.
+
+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 `runtest`, or reading testdefs.xml directly. We use `runtest -n` to simply show what would be run without actually running it:
+
+ $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
+
+The argument to `am instrument` that comes before the slash is the manifest package. `android.test.InstrumentationTestRunner` 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
+
+ tf >run instrument --package com.android.calculator2.tests
+
+
+## Interacting with a device
+
+### Generic device behavior in TF
+
+The running version of a command is called in `invocation`. 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").
+
+The primary console command to figure out what devices are up to is `list devices`:
+
+ $./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
+
+As far as the invocations are concerned, there are three device states: available, unavailable, and
+allocated. An `Available` device is ready to be allocated for an invocation. An `Unavailable`
+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 `Allocated` device is a device that is already being used by an invocation.
+
+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.
+
+Finally, once invocations are already underway, you can see what's going on with the `list
+invocations` command
+
+ 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
+
+
+### Running invocations on specific devices
+
+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:
+
+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
+[...]
+
+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:
+
+ tf >run instrument --package com.android.calculator2.tests --product-type tuna:toro
+
+As another example, to run on a GSM device with a SIM, you could do the following:
+
+ tf >run instrument --package com.android.calculator2.tests --property gsm.sim.state=READY
+
+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 *are* 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.
+
+
+## Logging
+
+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:
+
+ 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));
+
+You can now accomplish the same thing with the shim like this:
+
+ class ClassName {
+ [...]
+ CLog.v("This is a simple verbose log message");
+ CLog.w("This warning message brought to you by the number %d", 17);
+
+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.
+
+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.
+
+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.
+
+<!--
+FIXME: discuss test result reporting, retrieving builds, doing things continuously, target prep and
+FIXME: flashing builds, extending tradefed (like CTS).
+-->
+
diff --git a/src/tech/test_infra/tradefed/index.md b/src/tech/test_infra/tradefed/index.md
new file mode 100644
index 0000000..ef7ab7f
--- /dev/null
+++ b/src/tech/test_infra/tradefed/index.md
@@ -0,0 +1,55 @@
+<!--
+ Copyright 2011 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.
+-->
+
+# Trade Federation Overview #
+
+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
+more Android devices using ddmlib (the library behind DDMS) over adb.
+
+## Features
+
+- modular, flexible design
+- has built in support for running many different types of Android tests: instrumentation, native/gtest, host-based JUnit, etc
+- provides reliability and recovery mechanism on top of adb
+- supports scheduling and running tests on multiple devices in parallel
+
+## Fundamentals
+The lifecycle of a test executed using TradeFederation is composed of four separate stages, designed
+around formally defined interfaces.
+
+- [Build provider](bp.html): Provides a build to test, downloading appropriate files if necessary
+- [Target preparer](tp.html): Prepares the test environment, e.g. software installation and setup
+- [Test](test.html): Executes test(s) and gathers test results
+- [Result reporter](result.html): Listens for test results, usually for the purpose of forwarding
+ test results to a repository
+
+The fundamental entity in TradeFederation is a Configuration. A Configuration is an XML file that
+declares the lifecycle components of a test.
+
+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.
+
+### Additional components of a configuration
+
+- [Device recovery](recovery.html): mechanism to recover device communication if lost
+- [Logger](logger.html): collects tradefed logging data
+
+A complete TradeFederation test execution, across its entire lifecycle, is referred to as an
+Invocation.
diff --git a/src/tech/test_infra/tradefed/sidebar3.md b/src/tech/test_infra/tradefed/sidebar3.md
new file mode 100644
index 0000000..2aa2b1d
--- /dev/null
+++ b/src/tech/test_infra/tradefed/sidebar3.md
@@ -0,0 +1,5 @@
+# Trade Federation Docs #
+
+- [Getting Started](getting_started.html)
+- [Tutorial](tutorial.html)
+- [Command Files](commandfile_format.html)
diff --git a/src/tech/test_infra/tradefed/tutorial.md b/src/tech/test_infra/tradefed/tutorial.md
new file mode 100644
index 0000000..e9b5e5f
--- /dev/null
+++ b/src/tech/test_infra/tradefed/tutorial.md
@@ -0,0 +1,424 @@
+<!--
+ Copyright 2012 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.
+-->
+
+# Tutorial
+
+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.
+
+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.
+
+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.
+
+
+## Set up TradeFederation development environment
+
+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.
+
+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.
+
+
+## Creating a test class
+
+Lets create a hello world test that just dumps a message to stdout. A TradeFederation test must
+implement the (FIXME: link) IRemoteTest interface.
+
+Here's an implementation for the HelloWorldTest:
+
+ 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!");
+ }
+ }
+
+FIXME: prod-tests
+Save this sample code to
+`<git home>/tools/tradefederation/prod-tests/src/com/android/tradefed/example/HelloWorldTest.java`
+and rebuild tradefed from your shell:
+
+ m -j6
+
+If the build does not succeed, please consult the (FIXME: link)Development Environment page to
+ensure you did not miss any steps.
+
+
+## Creating a configuration
+
+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.
+
+Lets create a new Configuration for our HelloWorldTest.
+
+ <configuration description="Runs the hello world test">
+ <test class="com.android.tradefed.example.HelloWorldTest" />
+ </configuration>
+
+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.
+
+Note that we've specified the full class name of the HelloWorldTest. Save this data to a
+`helloworld.xml` file anywhere on your local filesystem (eg `/tmp/helloworld.xml`).
+
+
+## Running the configuration
+
+From your shell, launch the tradefed console
+
+ $ ./tradefed.sh
+
+Ensure a device is connected to the host machine that is visible to tradefed
+
+ tf> list devices
+
+Configurations can be run using the `run <config>` console command. Try this now
+
+FIXME: redo this
+
+ 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!
+
+You should see "Hello, TF World!" outputted on the terminal.
+
+
+## Adding the configuration to the classpath
+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.
+
+Lets illustrate this now by moving the helloworld.xml into the tradefed core library.
+
+Move the `helloworld.xml` file into
+`<git root>/tools/tradefederation/prod-tests/res/config/example/helloworld.xml`.
+
+Rebuild tradefed, and restart the tradefed console.
+
+Ask tradefed to display the list of configurations on the classpath:
+
+ tf> list configs
+ […]
+ example/helloworld: Runs the hello world test
+
+You can now run the helloworld config via the following command
+
+ 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!
+
+
+## Interacting with a device
+
+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.
+
+Tests can get a reference to an Android device by implementing the IDeviceTest interface.
+
+Here's a sample implementation of what this looks like:
+
+ public class HelloWorldTest implements IRemoteTest, IDeviceTest {
+ private ITestDevice mDevice;
+ @Override
+ public void setDevice(ITestDevice device) {
+ mDevice = device;
+ }
+
+ @Override
+ public ITestDevice getDevice() {
+ return mDevice;
+ }
+ …
+ }
+
+The TradeFederation framework will inject the ITestDevice reference into your test via the
+IDeviceTest#setDevice method, before the IRemoteTest#run method is called.
+
+Lets add an additional print message to the HelloWorldTest displaying the serial number of the
+device.
+
+ @Override
+ public void run(ITestInvocationListener listener) throws DeviceNotAvailableException {
+ System.out.println("Hello, TF World! I have a device " + getDevice().getSerialNumber());
+ }
+
+Now rebuild tradefed, and do (FIXME: update)
+
+ $ tradefed.sh
+ tf> list devices
+ Available devices: [30315E38655500EC]
+ …
+
+Take note of the serial number listed in Available devices above. That is the device that should be allocated to HelloWorld.
+
+ 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
+
+You should see the new print message displaying the serial number of the device.
+
+
+## Sending test results
+
+IRemoteTests report results by calling methods on the ITestInvocationListener instance provided to
+their `#run` method.
+
+The TradeFederation framework is responsible for reporting the start and end of an Invocation (via
+the ITestInvocationListener#invocationStarted and ITestInvocationListener#invocationEnded methods
+respectively).
+
+A `test run` 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.
+
+Here's what the HelloWorldTest implementation looks like with a single failed test result.
+
+ @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);
+ }
+
+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.
+
+
+## Storing test results
+
+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:
+
+ $ ./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
+
+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.
+
+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.
+
+Lets specify the result_reporter in the configuration now. Edit the
+`tools/tradefederation/res/config/example/helloworld.xml` like this:
+
+ <configuration description="Runs the hello world test">
+ <test class="com.android.tradefed.example.HelloWorldTest" />
+ <result_reporter class="com.android.tradefed.result.XmlResultReporter" />
+ </configuration>
+
+Now rebuild tradefed and re-run the hello world sample:
+FIXME: paths
+
+ 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
+
+Notice the log message stating an XML file has been generated. The generated file should look like this:
+
+ <?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>
+
+Note that you can write your own custom result_reporter. It just needs to implement the
+ITestInvocationListener interface.
+
+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.
+
+
+## Logging
+
+TradeFederation includes two logging facilities:
+
+1. ability to capture logs from the device (aka device logcat)
+2. ability to record logs from the TradeFederation framework running on the host machine (aka the
+ host log)
+
+Lets focus on 2 for now. Trade Federation's host logs are reported using the CLog wrapper for the
+ddmlib Log class.
+
+Lets convert the previous System.out.println call in HelloWorldTest to a CLog call:
+
+ @Override
+ public void run(ITestInvocationListener listener) throws DeviceNotAvailableException {
+ CLog.i("Hello world, TF! I have a device " + getDevice().getSerialNumber());
+
+Now rebuild and rerun. You should see the log message on stdout.
+
+ tf> run example/helloworld
+ …
+ 05-16 21:30:46 I/HelloWorldTest: Hello world, TF! I have a device 30315E38655500EC
+ …
+
+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.
+
+ <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>
+
+Now rebuild and run the helloworld example again.
+
+ 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
+ …
+
+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
+
+ $ more /tmp/0/inv_6390011618174565918/host_log_4255420317120216614.txt
+ …
+ 05-16 21:38:21 I/HelloWorldTest: Hello world, TF! I have a device 30315E38655500EC
+
+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.
+
+
+## Command line options
+Objects loaded from a TradeFederation Configuration (aka "Configuration objects") also have the
+ability to receive data from command line arguments.
+
+This is accomplished via the `@Option` annotation. To participate, a Configuration object class
+would apply the `@Option` 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).
+
+Lets add an Option to the HelloWorldTest.
+
+ @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";
+
+And lets add a log message to display the value of the option in HelloWorldTest, so we can
+demonstrate that it was received correctly.
+
+ @SuppressWarnings("unchecked")
+ @Override
+ public void run(ITestInvocationListener listener) throws DeviceNotAvailableException {
+ …
+ Log.logAndDisplay(LogLevel.INFO, "HelloWorldTest", "I received this option " + mMyOption);
+
+Rebuild TF and run helloworld: you should see a log message with the my_option's default value.
+
+ tf> run example/helloworld
+ …
+ 05-24 18:30:05 I/HelloWorldTest: I received this option thisisthedefault
+
+Now pass in a value for my_option: you should see my_option getting populated with that value
+
+ tf> run example/helloworld --my_option foo
+ …
+ 05-24 18:33:44 I/HelloWorldTest: I received this option foo
+
+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':
+
+ 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.
+FIXME: redo with enum help
+
+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.
+
+You can also specify an Option's value within the configuration xml by adding a
+`<option name="" value="">` element. Lets see how this looks in the helloworld.xml:
+
+ <test class="com.android.tradefed.example.HelloWorldTest" >
+ <option name="my_option" value="fromxml" />
+ </test>
+
+Re-building and running helloworld should now produce this output:
+
+ 05-24 20:38:25 I/HelloWorldTest: I received this option fromxml
+
+The configuration help should also be updated to indicate my_option's new default value:
+
+ tf> run --help example/helloworld
+ test options:
+ -m, --my_option this is the option's help text Default: fromxml.
+
+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.
+
+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.
+
+ tf >run --log-level-display info example/helloworld
+ …
+ 05-24 18:53:50 I/HelloWorldTest: Hello world, TF! I have a device XXXXXX
+
+<!-- To make future debugging in this tutorial easier, edit the helloworld.xml to default log-level-display to debug:
+
+ <logger class="com.android.tradefed.log.FileLogger" >
+ <option name="log-level-display" value="debug" />
+ </logger>
+-->
