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