1# How to update dirty-image-objects
2
31. Add `imgdiag` to ART APEX.
4
5The easiest way is to modify `art/build/apex/Android.bp` like this:
6```
7 art_runtime_binaries_both = [
8     "dalvikvm",
9     "dex2oat",
10+    "imgdiag",
11 ]
12```
13
142. Install ART APEX and reboot, e.g.:
15
16```
17m apps_only dist
18adb install out/dist/com.android.art.apex
19adb reboot
20```
21
223. Collect imgdiag output.
23
24```
25# To see all options check: art/imgdiag/run_imgdiag.py -h
26
27art/imgdiag/run_imgdiag.py
28```
29
304. Create new dirty-image-objects.
31
32```
33# To see all options check: art/imgdiag/create_dirty_image_objects.py -h
34
35# Using all imgdiag files:
36art/imgdiag/create_dirty_image_objects.py ./imgdiag_*
37
38# Or using only specified files:
39art/imgdiag/create_dirty_image_objects.py \
40  ./imgdiag_system_server.txt \
41  ./imgdiag_com.android.systemui.txt \
42  ./imgdiag_com.google.android.gms.txt \
43  ./imgdiag_com.google.android.gms.persistent.txt \
44  ./imgdiag_com.google.android.gms.ui.txt \
45  ./imgdiag_com.google.android.gms.unstable.txt
46```
47
48The resulting file will contain a list of dirty objects with optional
49(enabled by default) sort keys in the following format:
50```
51<class_descriptor>[.<reference_field_name>:<reference_field_type>]* [<sort_key>]
52```
53Classes are specified using a descriptor and objects are specified by
54a reference chain starting from a class. Example:
55```
56# Mark FileUtils class as dirty:
57Landroid/os/FileUtils; 4
58# Mark instance of Property class as dirty:
59Landroid/view/View;.SCALE_X:Landroid/util/Property; 4
60```
61If present, sort keys are used to specify the ordering between dirty entries.
62All dirty objects will be placed in the dirty bin of the boot image and sorted
63by the sort\_key values. I.e., dirty entries with sort\_key==N will have lower
64address than entries with sort\_key==N+1.
65
665. Push new dirty-image-objects to the device.
67
68```
69adb push dirty-image-objects.txt /etc/dirty-image-objects
70```
71
726. Reinstall ART APEX to update the boot image.
73
74```
75adb install out/dist/com.android.art.apex
76adb reboot
77```
78
79At this point the device should have new `boot.art` with optimized dirty object layout.
80This can be checked by collecting imgdiag output again and comparing dirty page counts to the previous run.
81