Add documentation about ART Service.
Bug: 264794495
Bug: 269082327
Test: N/A
Ignore-AOSP-First: ART Services
(cherry picked from https://googleplex-android-review.googlesource.com/q/commit:e231149f388b71181dfc6d65c0a531fc36e65aac)
Merged-In: Ia8ab6703b906d3c5232dc6c4acea458de84d2f9c
Change-Id: Ia8ab6703b906d3c5232dc6c4acea458de84d2f9c
diff --git a/libartservice/service/README.md b/libartservice/service/README.md
new file mode 100644
index 0000000..b5fa24e
--- /dev/null
+++ b/libartservice/service/README.md
@@ -0,0 +1,103 @@
+## ART Service
+
+Warning: The contents in this doc can become stale while the code evolves.
+
+ART Service manages dexopt artifacts of apps. With ART Service, you can dexopt
+apps, query their dexopt status (the compiler filter, the compilation reason,
+whether the dexopt artifacts are up-to-date, etc.), and delete dexopt artifacts.
+
+Note: ART Service is introduced since Android U. Prior to ART Service, dexopt
+artifacts were managed by Package Manager with a legacy implementation. ART
+Service is the default on Android U, while partners are allowed to opt-out and
+use the legacy implementation instead. The legacy implementation will be removed
+since Android V. This doc only describes ART Service, not the legacy
+implementation.
+
+### Primary dex vs. secondary dex
+
+ART Service dexopts both primary dex files and secondary dex files of an app.
+
+A primary dex file refers to the base APK or a split APK of an app. It's
+installed by Package Manager or shipped as a part of the system image, and it's
+loaded by Framework on app startup.
+
+A secondary dex file refers to an APK or JAR file that an app adds to its own
+data directory and loads dynamically.
+
+Note: Strictly speaking, an APK/JAR file is not a DEX file. It is a ZIP file
+that contain one or more DEX files. However, it is called a *dex file*
+conventionally.
+
+### Compiler filters
+
+See
+[Compilation options](https://source.android.com/docs/core/runtime/configure#compilation_options).
+
+### Dexopt scenarios
+
+At a high level, ART Service dexopts apps in the following senarios:
+
+- the device is on the very first boot
+- the device is on the first boot after an OTA update
+- the device is on the first boot after a mainline update
+- an app is being installed
+- the device is idle and charging
+
+Tip: The compilation reason, stored in the header of the OAT file, shows the
+senario, in which the app is dexopted.
+
+The sections below describe the default behavior in each senario. Note that the
+list of apps to dexopt and the compiler filter, as well as other options, can be
+customized by partners through a callback.
+
+#### On the very first boot / the first boot after an OTA update
+
+On the very first boot / the first boot after an OTA update, ART Service only
+dexopts primary dex files of all apps with the "verify" compiler filter.
+
+Note: It doesn't dexopt secondary dex files or use the "speed-profile" filter
+because doing so may block the boot for too long.
+
+Note: In practice, ART Service does nothing for most of the apps because the
+apps on the system partitions have dexopt artifacts generated by dexpreopt, and
+the apps on the data partition still have VDEX files usable even though their
+dependencies (bootclasspath and class loader context) have probably changed. In
+this senario, ART Service mostly dexopt apps in APEXes because they are not
+supported by dexpreopt.
+
+#### On the first boot after a mainline update
+
+On the first boot after a mainline update, ART Service dexopts the primary dex
+files of the system UI and the launcher. It uses the "speed" compiler filter for
+the system UI, and uses the "speed-profile" compiler filter for the launcher.
+
+Note: It only dexopts those two apps because they are important to user
+experience.
+
+Note: ART Service cannot use the "speed-profile" compiler filter for the system
+UI because the system UI is dexpreopted using the "speed" compiler filter and
+therefore it's never JITed and as a result there is no profile collected on the
+device to use. This may change in the future.
+
+#### During app installation
+
+During app installation, ART Service dexopts the primary dex files of the app.
+If the app is installed along with a DM file that contains a profile (known as a
+*cloud profile*), it uses the "speed-profile" compiler filter. Otherwise, it
+uses the "verify" compiler filter.
+
+Note: If the app is installed along with a DM file that only contains a VDEX
+file (but not a profile), no dexopt will be performed because the compiler
+filter will be "verify" and the VDEX file is satisfactory.
+
+Note: There is no secondary dex file present during installation.
+
+#### When the device is idle and charging
+
+ART Service has a job called *background dexopt job* managed by Job Scheduler.
+It is triggered when the device is idle and charging. During the job execution,
+it dexopts primary dex files and secondary dex files of all apps with the
+"speed-profile" compiler filter.
+
+The job is cancellable. When the device is no longer idle or charging, Job
+Scheduler cancels the job.