1# Pin Tool 2 3This tool is currently used mainly for: 4 51) Inspecting resident memory and locality 62) Generating and inspecting pinlist.meta used by Android's PinnerService 7 8For memory inspection, it allows probing live memory and providing the memory 9locations that are resident which can be used for diagnosis or as part of PGO 10optimizations. 11 12## Build and Install the tool 13 14To build and push the binary to device 15``` 16mm pintool 17and push $ANDROID_REPO/out/target/product/<lunchtarget>/system/bin/pintool /data/local/tmp/pintool 18adb shell 19cd /data/local/tmp/pintool 20``` 21 22 23## How to use the tool to generate pinner files 24 25Here are some sample use cases for this tool. 26 27### Sample Use Case 1: Probe Resident Memory for a mapped file or library and dump to console 28 29Executing the following command and providing the path to a library mapped by a process 30it will dump the resident memory ranges. 31 32``` 33./pintool file <path_to_your_library> --gen-probe --dump 34``` 35 36Note: you can use any kind of mapped file such as .so, .apk, etc. 37 38### Sample Use Case 2: Probe per-file Resident Memory for a mapped apk file and dump to console 39 40Executing this command will inspect resident memory for a zip file and dump 41per-file breakdowns. 42 43``` 44./pintool file <path_to_myfile.apk> --zip --gen-probe --dump 45``` 46 47### Sample Use Case 3: Probe per-file resident memory for a mapped apk, dump and generate pinlist.meta 48``` 49./pintool file <path_to_myfile.apk> --zip --gen-probe --dump -o pinlist.meta 50``` 51 52### Sample Use Case 4: Probe per-file resident memory and filter it with a provided pinconfig 53``` 54./pintool file <path_to_myfile.apk> --zip --gen-probe --pinconfig pinconfig.txt --dump -o pinlist.meta 55``` 56 57### Sample Use Case 5: Dump contents of a provided pinlist.meta file 58``` 59./pintool pinlist pinlist.meta --dump -v 60``` 61 62### Sample Use Case 6: Read a zip and filter based on a pinconfig file and generate pinlist.meta without probing 63 64This will skip doing any probing and it will just apply filtering based on the pinconfig.txt, this is helpful 65in cases where you do not intend to do any kind of PGO probing and know exactly what ranges you want to pin within your file 66 67``` 68./pintool file <path_to_myfile.apk> --zip --pinconfig pinconfig.txt --dump -o pinlist.meta 69``` 70 71### Sample Use Case 7: Load an existing zip probe and inspect its per-file contents 72 73``` 74./pintool file /data/app/~~tmTrs5_XINwbpYWroRu5rA==/org.chromium.trichromelibrary_602300034-EFoOwMgVNBbwkMnp9zcWbg==/base.apk --zip --use-probe pinlist.meta --dump 75``` 76 77 78## Pinconfig File Structure 79 80Pinconfig files specify a custom filter to be applied on top of a generated or provided memory probe 81it should specify a subset of files and optionally ranges within those files to be matched against 82and subsequently kept in case a pinlist.meta is generated. 83 84A `pinconfig.txt` is just a list of files with a key value pair separated by a newline. 85 86`pinconfig.txt` structure pattern: 87``` 88(file <file> 89[offset <value> 90length <value>])* 91``` 92where: 93<file> 94 Filename as a string, the parser will do a contains like operation (e.g. GLOB(*<file>*)) to match against files 95 within the zip file and stop on first match. 96<value> 97 Unsigned integer value 98 99Note: `offset` and `length` tokens are optional and if ommited, the whole file will be considered desired. 100 101 102Example `pinconfig.txt`: 103``` 104file lib/arm64-v8a/libcrashpad_handler_trampoline.so 105file libmonochrome_64.so 106offset 1000 107len 50000 108file libarcore_sdk_c.so 109``` 110 111## Pinlist.meta files 112 113"pinlist.meta" files are consumed by PinnerService. 114 115These files specify a list of memory ranges to be pinned (mlocked). 116If Android's PinnerService allows your app pinning, it will read the pinlist.meta 117file from inside your apk's assets folder (assets/pinlist.meta) and pin based 118on the specified ranges. 119 120Note: The PinnerService will need to support pinning your apk in order for the 121pinlist.meta file to be used. 122 123A pinlist.meta file is a binary file with a set of tuples of OFFSET and LENGTH 124stored in Big Endian format. 125 1264 byte: OFFSET 1274 byte: LEN 128 129pinlist.meta 130``` 131OFFSET LEN* 132``` 133 134So to read those files, it is usually helpful to use the `pintool`. 135 136## Other potential uses 137 138Outside of pinner service, the tool can be used to inspect resident memory for 139any file in memory. 140 141## Extra information 142 143the pinlist.meta depends on the apk contents and needs to be regenrated if 144you are pushing a new version of your apk. 145 146## Tips for better pinning 147 148Take the steps listed below before generating your pinlist to improve its quality. 149 150### Disable disk read-ahead before generating the pinlist 151 152Disk read-ahead will add pages to your pinlist that are not actually accessed. 153Disable disk read-ahead to reduce the size of your pinned memory by dropping 154unnecessary regions from the pinlist. 155 156Before invoking `pintool --gen-probe`, disable disk read-ahead: 157``` 158echo 1 > /sys/block/<block_device>/queue/read_ahead_kb 159``` 160Replace <block_device> with the filesystem where the path to your `.apk` or library is hosted. You can find this information in the output of `df`. 161 162If you are unsure if read ahead is currently enabled, you can just query the value instead: 163``` 164cat /sys/block/<block_device>/queue/read_ahead_kb 165``` 166 167This setting is reverted to the default after a reboot. 168 169### Drop the page cache before generating the pinlist 170 171Before taking a probe, it is a good idea to drop the page cache to reduce the amount of pages that 172are unrelated to your CUJ and start fresh loading new memory. 173 174In order to drop the page cache you can run this command: 175``` 176echo 3 > /proc/sys/vm/drop_caches 177```