AFDO-Bisect: Add user documentation
This CL adds a README containing some information about what the script
does, what the arguments are, and how to invoke it, for user benefit.
BUG=None
TEST=None
Change-Id: I909c75e35545c7049b030fde2d080f6466addabe
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/third_party/toolchain-utils/+/1718885
Reviewed-by: Caroline Tice <cmtice@chromium.org>
Tested-by: Emma Vukelj <emmavukelj@google.com>
diff --git a/afdo_tools/bisection/README.md b/afdo_tools/bisection/README.md
new file mode 100644
index 0000000..558b2ef
--- /dev/null
+++ b/afdo_tools/bisection/README.md
@@ -0,0 +1,71 @@
+# `afdo_prof_analysis.py`
+
+`afdo_prof_analysis.py` is the main script and entrypoint for this AFDO profile
+analysis tool. This tool attempts to determine which part of a "bad" profile is
+bad. It does this using several analysis techniques which iterate over provided
+good and bad profiles to isolate the problematic portion of the bad profile.
+Goodness and badness are determined by the user, by passing a user-provided
+bash script. If the program runs successfully to completion, results will be
+output to the path specified by `analysis_output_file` as a JSON with the
+following keys:
+
+* `seed`: Float, the seed to randomness for this analysis
+* `bisect_results`: a sub-JSON with the following keys:
+ + `ranges`: 2d list, where each element is a list of functions that are
+ problematic in conjunction with one another.
+ + `individuals`: individual functions with a bad profile
+* `good_only_functions`: Boolean: is the bad profile just missing some
+ function profiles (that only the good profile has?)
+* `bad_only_functions`: Boolean: does the bad profile have extra function
+ profiles (i.e. the good profile doesn't have these functions) causing
+ bad-ness?
+
+## Resuming
+
+`afdo_prof_analysis.py` offers the ability to resume profile analysis in case
+it was interrupted and the user does not want to restart analysis from the
+beginning. On every iteration of the analysis, it saves state to disk (as
+specified by the `state_file` flag). By default the tool will resume from this
+state file, and this behavior can be disabled by providing the `no_resume` flag
+when running the script.
+
+## Usage
+
+### Example Invocation
+ `python afdo_prof_analysis.py --good_prof good.txt --bad_prof bad.txt
+ --external_decider profile_test.sh --analysis_output_file afdo_results.json`
+
+### Required flags:
+
+ * `good_prof`: A "good" text-based AFDO profile as outputted by
+ bin/llvm-profdata (within an LLVM build).
+ * `bad_prof`: A "bad" text-based AFDO profile as outputted by
+ bin/llvm-profdata (within an LLVM build).
+ * `external_decider`: A user-provided bash script that, given a text-based
+ AFDO profile as above, has one of the following exit codes:
+ + 0: The given profile is GOOD.
+ + 1: The given profile is BAD.
+ + 125: The goodness of the given profile cannot be accurately determined by
+ the benchmarking script.
+ + 127: Something went wrong while running the benchmarking script, no
+ information about the profile (and this result will cause analysis to abort).
+ * `analysis_output_file`: The path of a file to which to write the output.
+ analysis results.
+
+### Optional flags:
+
+Note that these are all related to the state-saving feature which is
+described above in "Resuming", so feel free to return to this later.
+ * `state_file`: An explicit path for saving/restoring intermediate state.
+ Defaults to `$(pwd)/afdo_analysis_state.json`.
+ * `no_resume`: If enabled, the analysis will not attempt to resume from
+ previous state; instead, it will start from the beginning. Defaults to
+ False, i.e. by default will always try to resume from previous state if
+ possible.
+ * `remove_state_on_completion`: If enabled, the state file will be removed
+ upon the completion of profile analysis. If disabled, the state file will
+ be renamed to `<state_file_name>.completed.<date>` to prevent reusing this
+ as intermediate state. Defaults to False.
+ * `seed`: A float specifying the seed for randomness. Defaults to seconds
+ since epoch. Note that this can only be passed when --no_resume is True,
+ since otherwise there is ambiguity in which seed to use.
