Add documentation for using emulator CIPD packages.

Bug: 922145
Change-Id: Ic21bfc796baa5d8b8f55a5dedef7b9eaa35aa5b1
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2135340Reviewed-by: Haiyang Pan <hypan@google.com>
Commit-Queue: John Budorick <jbudorick@chromium.org>
Cr-Commit-Position: refs/heads/master@{#756460}

docs/android_emulator.md

@@ -10,7 +10,112 @@ You need to target the correct architecture via GN args:
 target_cpu = "x86"  # or "x64" if you have an x86_64 emulator
 ```
 
-## Creating an Emulator Image
+## Running an Emulator
+
+### Using Prebuilt CIPD packages
+
+Chromium has a set of prebuilt images stored as CIPD packages. These are used
+by various builders to run tests on the emulator. Their configurations are
+currently stored in `//tools/android/avd/proto`.
+
+| File | Builder |
+|:----:|:-------:|
+| `tools/android/avd/proto/generic_android28.textpb` | [android-pie-x86-rel][android-pie-x86-rel] |
+
+You can use these configuration files to run the same emulator images locally.
+
+[android-pie-x86-rel]: https://ci.chromium.org/p/chromium/builders/ci/android-pie-x86-rel
+
+#### Running via the test runner
+
+The android test runner can run emulator instances on its own. In doing so, it
+starts the emulator instances, runs tests against them, and then shuts them
+down. This is how builders run the emulator.
+
+##### Options
+
+ * `--avd-config`
+
+    To have the test runner run an emulator instance, use `--avd-config`:
+
+    ```
+      $ out/Debug/bin/run_base_unittests \
+          --avd-config tools/android/avd/proto/generic_android28.textpb
+    ```
+
+ * `--emulator-count`
+
+    The test runner will launch one instance by default. To have it run multiple
+    instances, use `--emulator-count`:
+
+    ```
+      $ out/Debug/bin/run_base_unittests \
+          --avd-config tools/android/avd/proto/generic_android28.textpb \
+          --emulator-count 4
+    ```
+
+ * `--emulator-window`
+
+    The test runner runs the emulator in headless mode by default. To have it run
+    with a window, use `--emulator-window`:
+
+    ```
+      $ out/Debug/bin/run_base_unittests \
+          --avd-config tools/android/avd/proto/generic_android28.textpb \
+          --emulator-window
+    ```
+
+#### Running standalone
+
+The test runner will set up and tear down the emulator on each invocation.
+To manage emulator lifetime independently, use `tools/android/avd/avd.py`.
+
+**NOTE**: You'll first need to install the emulator configuration you intend to
+use:
+
+  ```
+    $ tools/android/avd/avd.py install \
+        --avd-config tools/android/avd/proto/generic_android28.textpb
+  ```
+
+##### Options
+
+ * `--avd-config`
+
+    This behaves the same as it does for the test runner.
+
+    ```
+      $ tools/android/avd/avd.py start \
+          --avd-config tools/android/avd/proto/generic_android28.textpb
+    ```
+
+    > Note: `avd.py start` will start an emulator instance and then terminate.
+    > To shut down the emulator, use `adb emu stop`.
+
+ * `--emulator-window`
+
+    Like the test runner, `avd.py` runs the emulator in headless mode by default.
+    To have it run with a window, use `--emulator-window`:
+
+    ```
+      $ tools/android/avd/avd.py start \
+          --avd-config tools/android/avd/proto/generic_android28.textpb \
+          --emulator-window
+    ```
+
+ * `--no-read-only`
+
+    `avd.py` runs the emulator in read-only mode by default. To run a modifiable
+    emulator, use `--no-read-only`:
+
+    ```
+      $ tools/android/avd/avd.py start \
+          --avd-config tools/android/avd/proto/generic_android28.textpb \
+          --no-read-only
+    ```
+
+### Using Your Own Emulator Image
+
 By far the easiest way to set up emulator images is to use Android Studio.
 If you don't have an [Android Studio project](android_studio.md) already, you
 can create a blank one to be able to reach the Virtual Device Manager screen.
@@ -22,11 +127,15 @@ Where files live:
  * Emulator configs and data partition images are stored within
    `~/.android/avd/`.
 
-### Choosing a Skin
+#### Creating an Image
+
+##### Choosing a Skin
+
 Choose a skin with a small screen for better performance (unless you care about
 testing large screens).
 
-### Choosing an Image
+##### Choosing an Image
+
 Android Studio's image labels roughly translate to the following:
 
 | AVD "Target" | Virtual Device Configuration tab | GMS? | Build Properties |
@@ -40,12 +149,14 @@ Android Studio's image labels roughly translate to the following:
 Images** tab in the Virtual Device Configuration wizard.
 ***
 
-### Configuration
+##### Configuration
+
 "Show Advanced Settings" > scroll down:
 * Set internal storage to 4000MB (component builds are really big).
 * Set SD card to 1000MB (our tests push a lot of files to /sdcard).
 
-### Known Issues
+##### Known Issues
+
  * Our test & installer scripts do not work with pre-MR1 Jelly Bean.
  * Component builds do not work on pre-KitKat (due to the OS having a max
    number of shared libraries).
@@ -55,7 +166,9 @@ Images** tab in the Virtual Device Configuration wizard.
    * Can often be fixed by editing `~/.android/avd/YOUR_DEVICE/config.ini`.
      * Look for `hw.sdCard=no` and set it to `yes`
 
-## Starting an Emulator from the Command Line
+
+#### Starting an Emulator from the Command Line
+
 Refer to: https://developer.android.com/studio/run/emulator-commandline.html.
 
 *** promo
@@ -67,7 +180,8 @@ Ctrl-C will gracefully close an emulator.
 provide tab completion for the `emulator` command line tool.
 ***
 
-### Basic Command Line Use
+#### Basic Command Line Use
+
 ```shell
 $ # List virtual devices that you've created:
 $ ~/Android/Sdk/emulator/emulator -list-avds
@@ -75,7 +189,8 @@ $ # Start a named device:
 $ ~/Android/Sdk/emulator/emulator @EMULATOR_ID
 ```
 
-### Running a Headless Emulator
+#### Running a Headless Emulator
+
 You can run an emulator without creating a window on your desktop (useful for
 `ssh`):
 ```shell
@@ -84,7 +199,8 @@ $ # This also works for new enough emulator builds:
 $ ~/Android/Sdk/emulator/emulator-headless @EMULATOR_ID
 ```
 
-### Running Multiple Emulators
+#### Running Multiple Emulators
+
 Tests are automatically sharded amongst available devices. If you run multiple
 emulators, then running test suites becomes much faster. Refer to the
 "Multiple AVD instances" section of these [emulator release notes](
@@ -97,7 +213,8 @@ $ # Start 12 emulators. More than 10 requires disabling audio on some OS's. Redu
 $ ( for i in $(seq 12); do ~/Android/Sdk/emulator/emulator @EMULATOR_ID -read-only -no-audio -cores 2 & done; wait )
 ```
 
-### Writable system partition
+#### Writable system partition
+
 Unlike physical devices, an emulator's `/system` partition cannot be modified by
 default (even on rooted devices). If you need to do so (such as to remove a
 system app), you can start your emulator like so: