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