1Android Order Files Scripts
2============================
3
4For the latest version of this doc, please make sure to visit:
5[Android Order Files Scripts](https://android.googlesource.com/toolchain/llvm_android/+/refs/heads/main/orderfiles/scripts/README.md)
6
7Getting started with Order files
8----------------------------------
9Order files are text files containing symbols representing functions names.
10Linker (lld) uses order files to layout functions in a specific order.
11These ordered binaries in Android will reduce page faults and improve a program's launch time due to the efficient loading of symbols during program’s cold-start.
12
13The scripts described here are used to create and validate order files. You can learn how and when they are used by looking at [Android Order Files](https://android.googlesource.com/toolchain/llvm_android/+/refs/heads/main/orderfiles/README.md).
14
15File/CSV Format
16----------------------------------
17Some arguments in the script allows three formats (File, CSV, or Folder) based on the first character.
18All formats represent a list of values, which is symbols or files in our case.
19- File format: The file will have one value per line.
20               Add @ before the filename to show it is a file.
21               If the values are files, the format is (file, weight).
22               Example: @example.txt
23- CSV format: Use “” (Quotation) around the comma-separated values.
24              Example: “main,foo,bar”
25- Folder format: Add ^ before the path to the folder.
26              We assume every file in the folder ends with ".orderfile".
27              Example: ^path/to/folder
28
29Orderfile scripts
30----------------------------------
31Following scripts are provided:
32- [create_orderfile](create_orderfile.py)
33- [validate_orderfile](validate_orderfile.py)
34- [merge_orderfile](merge_orderfile.py)
35
36In order to run the scripts you may need to install the following python3 dependencies:
37- bitarray
38- graphviz
39
40Create Order file
41----------------------------------
42You can create an orderfile from a mapping file and profile file.
43
44```
45python3 create_orderfile [-h] --profile-file PROFILE_FILE --mapping-file MAPPING_FILE [--output OUTPUT] [--denylist DENYLIST] [--last-symbol LAST_SYMBOL] [--leftover]
46```
47
48Flags:
49- Profile file (--profile-file):
50    - Description: The profile file generated by running a binary compiled with forder-file-instrumentation
51    - Type: String
52    - Required
53- Mapping file (--mapping-file):
54    - Description: The mapping file generated during compilation that maps MD5 hashes to symbol names
55    - Type: String
56    - Required
57- Output file (--output):
58    - Description: The output file name for the order file. Default Name: default.orderfile
59    - Type: String
60- Deny List (--denylist):
61    - Description: Symbols that you want to exclude from the order file
62    - Type: String (File/CSV)
63- Last symbol (--last-symbol):
64    - Description: The order file will end at the passed last symbol and ignore the symbols after it.
65                   If you want an order file only for startup, you should pass the last startup symbol.
66                   Last-symbol has priority over leftover so we will output until the last symbol and ignore the leftover flag.
67    - Type: String
68- Leftover symbols (--leftover):
69    - Description: Some symbols (functions) might not have executed so they will not appear in the profile file.
70                   If you want these symbols in your orderfile, you can use this flag and it will add them at the end.
71    - Type: Bool
72
73Validate Order file
74----------------------------------
75Once we get an order file for a library or binary, we need to check if it is valid based on each team’s criteria.
76To automate this process, we wrote a python script to check the criteria.
77The current criteria that we allow:
78- Defining an order priority that needs to be in the orderfile
79- Symbols that have to be present in orderfile
80- Symbols that should not be present in orderfile
81- Minimum number of symbols to make an orderfile good for page layout purposes
82
83```
84python3 validate_orderfile [-h] --order-file ORDER_FILE [--partial PARTIAL] [--allowlist ALLOWLIST] [--denylist DENYLIST] [--min MIN]
85```
86
87Flags:
88- Order file (--order-file):
89    - Description: The order file that is being validated on the below criteria
90    - Type: String
91    - Required
92- Partial Order (--partial):
93    - Description: A partial order of symbols that must be correct in the order file.
94    - Type: String (File/CSV)
95- Allow List (--allowlist):
96    - Description: Symbols that have to be present in orderfile
97    - Type: String (File/CSV)
98- Deny List (--denylist):
99    - Description: Symbols that should not be present in orderfile. Denylist flag has priority over allowlist.
100    - Type: String (File/CSV)
101- Minimum Number of Entries (--min):
102    - Description: Minimum number of symbols to make an orderfile good for page layout purposes
103    - Type: Int
104
105Merge Order File
106----------------------------------
107Any executable running on different devices might not create the same order file due to threads, OS, side effects, etc.
108As a result, our script will take all the order files and merge them into one order file while trying to maintain locality.
109As lower end device require better layout for performance boost, you can assign weights to order files and provide lower
110end device order files with higher weight. You can only assign weights if you use File format and an example can be found
111in test/merge-test/merge.txt.
112
113```
114python3 merge_orderfile [-h] --order-files ORDER_FILES [--output OUTPUT] [--graph-image GRAPH_IMAGE]
115```
116
117Flags:
118- Files (--order-files):
119    - Description: A collection of order files that need to be merged together
120    - Type: String (File/CSV/Folder)
121    - Required
122- Output (--output):
123    - Description: Provide the output file name for the order file. Default Name: default.orderfile
124    - Type: String
125- Graph Image (--graph-image):
126    - Description: Provide the output image name for the graph representation of the order files
127    - Type: String
128