README.md
1# `afdo_prof_analysis.py`
2
3`afdo_prof_analysis.py` is the main script and entrypoint for this AFDO profile
4analysis tool. This tool attempts to determine which part of a "bad" profile is
5bad. It does this using several analysis techniques which iterate over provided
6good and bad profiles to isolate the problematic portion of the bad profile.
7Goodness and badness are determined by the user, by passing a user-provided
8bash script. If the program runs successfully to completion, results will be
9output to the path specified by `analysis_output_file` as a JSON with the
10following keys:
11
12* `seed`: Float, the seed to randomness for this analysis
13* `bisect_results`: a sub-JSON with the following keys:
14 + `ranges`: 2d list, where each element is a list of functions that are
15 problematic in conjunction with one another.
16 + `individuals`: individual functions with a bad profile
17* `good_only_functions`: Boolean: is the bad profile just missing some
18 function profiles (that only the good profile has?)
19* `bad_only_functions`: Boolean: does the bad profile have extra function
20 profiles (i.e. the good profile doesn't have these functions) causing
21 bad-ness?
22
23## Resuming
24
25`afdo_prof_analysis.py` offers the ability to resume profile analysis in case
26it was interrupted and the user does not want to restart analysis from the
27beginning. On every iteration of the analysis, it saves state to disk (as
28specified by the `state_file` flag). By default the tool will resume from this
29state file, and this behavior can be disabled by providing the `no_resume` flag
30when running the script.
31
32## Usage
33
34### Example Invocation
35 `python afdo_prof_analysis.py --good_prof good.txt --bad_prof bad.txt
36 --external_decider profile_test.sh --analysis_output_file afdo_results.json`
37
38### Required flags:
39
40 * `good_prof`: A "good" text-based AFDO profile as outputted by
41 bin/llvm-profdata (within an LLVM build).
42 * `bad_prof`: A "bad" text-based AFDO profile as outputted by
43 bin/llvm-profdata (within an LLVM build).
44 * `external_decider`: A user-provided bash script that, given a text-based
45 AFDO profile as above, has one of the following exit codes:
46 + 0: The given profile is GOOD.
47 + 1: The given profile is BAD.
48 + 125: The goodness of the given profile cannot be accurately determined by
49 the benchmarking script.
50 + 127: Something went wrong while running the benchmarking script, no
51 information about the profile (and this result will cause analysis to abort).
52 * `analysis_output_file`: The path of a file to which to write the output.
53 analysis results.
54
55### Optional flags:
56
57Note that these are all related to the state-saving feature which is
58described above in "Resuming", so feel free to return to this later.
59 * `state_file`: An explicit path for saving/restoring intermediate state.
60 Defaults to `$(pwd)/afdo_analysis_state.json`.
61 * `no_resume`: If enabled, the analysis will not attempt to resume from
62 previous state; instead, it will start from the beginning. Defaults to
63 False, i.e. by default will always try to resume from previous state if
64 possible.
65 * `remove_state_on_completion`: If enabled, the state file will be removed
66 upon the completion of profile analysis. If disabled, the state file will
67 be renamed to `<state_file_name>.completed.<date>` to prevent reusing this
68 as intermediate state. Defaults to False.
69 * `seed`: A float specifying the seed for randomness. Defaults to seconds
70 since epoch. Note that this can only be passed when --no_resume is True,
71 since otherwise there is ambiguity in which seed to use.
72