1# How to update dirty-image-objects (from ATP top 100 run) 2 3## 1. Collect dirty objects from most used apps using ATP top100 test run (use specific branch/Android release) 4 5**IMPORTANT**: Make sure that pinned build for `GIT_TRUNK_RELEASE` branch is up-to-date. Update in `BUILD_IDS` here: 6<https://source.corp.google.com/piper///depot/google3/configs/wireless/android/testing/atp/prod/mainline-engprod/common.gcl;l=28-44> 7 8 9**NOTE**: New branches can be added in `master-art_imgdiag_tests` definition here: 10<https://source.corp.google.com/piper///depot/google3/configs/wireless/android/testing/atp/prod/mainline-engprod/config.gcl;l=1384-1395> 11 12 13Go to <http://go/abtd> and create a test run with the following parameters: 14 15* Branch name: `git_main` 16 17* Test type: `ATP` 18 19* Test name: select one of the supported imgdiag ATP configurations, see the list here: 20<https://atp.googleplex.com/test_configs?testName=%25imgdiag_top_100%25> 21 22 23This will generate a profile based on the following: 24 25* ART module – latest version from `git_main`. 26 27* Top 100 apps – up-to-date list of app versions. 28 29* Platform – pinned version from <https://source.corp.google.com/piper///depot/google3/configs/wireless/android/testing/atp/prod/mainline-engprod/common.gcl;l=28-44> 30 31 32## 2. Create two CLs with new dirty-image-objects files (one for ART, one for frameworks) 33 34 35Download new dirty-image-objects files from the run, either manually from the 36website or using the script. Example: 37``` 38ati_download_artifacts.py --invocation-id I70700010348949160 39``` 40 41 42**NOTE**: Use `ati_download_artifacts.py -h` to see all command line flags. 43 44 45There should be two files named like this: 46``` 47subprocess-dirty-image-objects-art_9607835265532903390.txt.gz 48subprocess-dirty-image-objects-framework_10599183892981195850.txt.gz 49``` 50 51dirty-image-objects-art goes into platform/art repo: <https://cs.android.com/android/platform/superproject/main/+/main:art/build/apex/dirty-image-objects> 52 53 54dirty-image-objects-framework goes into platform/frameworks/base repo: <https://cs.android.com/android/platform/superproject/main/+/main:frameworks/base/config/dirty-image-objects> 55 56 57Upload the two CLs and put them in the same topic. 58 59## 3. Start an ABTD build from the same branch with dirty-image-objects CLs on top 60 61Create a build for the same branch and target that was used in step 1, apply CLs with new dirty-image-objects. 62For `v2/mainline-engprod/apct/mainline/art/GIT_TRUNK_RELEASE/panther/imgdiag_top_100`: 63 64* Branch: `git_trunk-release` 65 66* Target: `panther-userdebug` 67 68## 4. Run ATP test again, this time with custom build-id from step 3 and with CLs from step 2 69 70Rerun the test from step 1 with the following additions: 71* Add the CLs with new dirty-image-objects (this will force ABTD to rebuild ART module with the change) 72* Select "Configure this test in **Advanced mode**". Scroll down to "**Extra Arguments**" and add **build-id**, set it to the build id from step 3. 73 74## 5. Download ATP results from step 1 and step 4 and compare them 75 76Use the script to download both ATP run results, example: 77``` 78ati_download_artifacts.py --invocation-id I79100010355578895 --invocation-id I84900010357346481 79``` 80 81Compare the results: 82``` 83~/compare_imgdiag_runs.py I79100010355578895 I84900010357346481 84 85# Example comparison output: 86 87Comparing: ['I79100010355578895', 'I84900010357346481'] 88Common proc count (used in the comparison): 233 89Mismatching proc count (not present in all runs): 10 90Total dirty pages: 91[17066, 14799] 92 93Mean dirty pages: 94[73.24463519313305, 63.51502145922747] 95 96Median dirty pages: 97[69, 60] 98``` 99 100Note the number of common processes, it should be at least 200 (approx 100 from top100 apps + another 100+ system processes). If it is lower than that, it might indicate missing processes in one or both runs, which would invalidate the comparison. 101The lower the number of mismatching processes the better. Typically less than 40 is fine. 102 103 104In there is a significant difference between the mean and median dirty page counts, it may be useful to check page count diffs for specific processess. Use `--verbose` flag with comparison script to show such info. 105 106The key number to look at for comparison is "mean dirty pages". In this example new profile saves about 10 pages per process (a mean reduction of 40 KiB memory per process). 107 108## 6. Submit new dirty-image-objects CLs if the result is better/good enough 109 110Typical measurement noise for mean dirty pages is less than 2. A new profile with dirty page reduction greater than this threshold is considered an improvement. 111 112 113# How to update dirty-image-objects (manually) 114 115## 1. Install imgdiag ART APEX on a device with AOSP build, e.g.: 116 117``` 118. ./build/envsetup.sh 119banchan test_imgdiag_com.android.art module_arm64 120m apps_only dist 121adb install out/dist/test_imgdiag_com.android.art.apex 122adb reboot 123``` 124 125## 2. Collect imgdiag output. 126 127``` 128# To see all options check: art/imgdiag/run_imgdiag.py -h 129 130art/imgdiag/run_imgdiag.py 131``` 132 133## 3. Create new dirty-image-objects files. 134 135``` 136# To see all options check: art/imgdiag/create_dirty_image_objects.py -h 137 138# Using all imgdiag files: 139art/imgdiag/create_dirty_image_objects.py ./imgdiag_* 140 141# Or using only specified files: 142art/imgdiag/create_dirty_image_objects.py \ 143 ./imgdiag_system_server.txt \ 144 ./imgdiag_com.android.systemui.txt \ 145 ./imgdiag_com.google.android.gms.txt \ 146 ./imgdiag_com.google.android.gms.persistent.txt \ 147 ./imgdiag_com.google.android.gms.ui.txt \ 148 ./imgdiag_com.google.android.gms.unstable.txt 149``` 150 151This will generate 3 files: 152* dirty-image-objects.txt -- contains all dirty objects + info about the jar they are defined in. 153* art\_dirty-image-objects.txt -- dirty objects defined in the ART module, these objects are defined in art/build/apex/dirty-image-objects 154* framework\_dirty\_image\_objects.txt -- dirty objects defined in frameworks, these objects are defined in frameworks/base/config/dirty-image-objects 155 156 157The resulting art/framework files will contain lists of dirty objects with 158optional (enabled by default) sort keys in the following format: 159``` 160<class_descriptor>[.<reference_field_name>:<reference_field_type>]* [<sort_key>] 161``` 162Classes are specified using a descriptor and objects are specified by 163a reference chain starting from a class. Example: 164``` 165# Mark FileUtils class as dirty: 166Landroid/os/FileUtils; 4 167# Mark instance of Property class as dirty: 168Landroid/view/View;.SCALE_X:Landroid/util/Property; 4 169``` 170If present, sort keys are used to specify the ordering between dirty entries. 171All dirty objects will be placed in the dirty bin of the boot image and sorted 172by the sort\_key values. I.e., dirty entries with sort\_key==N will have lower 173address than entries with sort\_key==N+1. 174 175## 4. Push new frameworks dirty-image-objects to the device. 176 177``` 178adb push framework_dirty-image-objects.txt /etc/dirty-image-objects 179``` 180 181## 5. Install ART module with new dirty-image-objects 182 183``` 184cp ./art_dirty-image-objects.txt $ANDROID_BUILD_TOP/art/build/apex/dirty-image-objects 185m apps_only dist 186adb install out/dist/com.android.art.apex 187adb reboot 188``` 189 190At this point the device should have new `boot.art` with optimized dirty object layout. 191This can be checked by collecting imgdiag output again and comparing dirty page counts to the previous run. 192