LLVM tools: Updated README.md to include new scripts

Also added more examples for each script.

BUG=None
TEST=None

Change-Id: Ic41217574a4a430d6869679ddc8e8c920795269b
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/third_party/toolchain-utils/+/1783103
Reviewed-by: Manoj Gupta <manojgupta@chromium.org>
Reviewed-by: George Burgess <gbiv@chromium.org>
Tested-by: Salud Lemus <saludlemus@google.com>

1 files changed, 267 insertions, 11 deletions

diff --git a/llvm_tools/README.md b/llvm_tools/README.md
index d0b76fe6..68106a05 100644
--- a/llvm_tools/README.md
+++ b/llvm_tools/README.md
@@ -28,17 +28,40 @@ to be tested with the updated `LLVM_NEXT_HASH`.
 For example:
 
 ```
-python update_packages_and_run_tryjobs.py --llvm_version tot --options
-nochromesdk --builders kevin-release-tryjob nocturne-release-tryjob
+$ ./update_packages_and_run_tryjobs.py \
+  --llvm_version tot \
+  --options nochromesdk latest-toolchain \
+  --builders kevin-release-tryjob nocturne-release-tryjob
 ```
 
 The above example would update the packages' `LLVM_NEXT_HASH` to the top of
-trunk's git hash and would submit tryjobs for kevin and nocturne boards.
+trunk's git hash and would submit tryjobs for kevin and nocturne boards, passing
+in 'nochromesdk' and 'latest-toolchain' for each tryjob.
 
 For help with the command line arguments of the script, run:
 
 ```
-python update_packages_and_run_tryjobs.py --help
+$ ./update_packages_and_run_tryjobs.py --help
+```
+
+Similarly as the previous example, but for updating `LLVM_NEXT_HASH` to
+google3:
+
+```
+$ ./update_packages_and_run_tryjobs.py \
+  --llvm_version google3 \
+  --options nochromesdk latest-toolchain \
+  --builders kevin-release-tryjob nocturne-release-tryjob
+```
+
+Similarly as the previous example, but for updating `LLVM_NEXT_HASH` to
+the git hash of revision 367622:
+
+```
+$ ./update_packages_and_run_tryjobs.py \
+  --llvm_version 367622 \
+  --options nochromesdk latest-toolchain \
+  --builders kevin-release-tryjob nocturne-release-tryjob
 ```
 
 ## `update_chromeos_llvm_next_hash.py`
@@ -58,8 +81,10 @@ have their `LLVM_NEXT_HASH` updated.
 For example:
 
 ```
-python update_chromeos_llvm_next_hash.py --update_packages sys-devel/llvm
-sys-libs/compiler-rt --llvm_version google3 --failure_mode disable_patches
+$ ./update_chromeos_llvm_next_hash.py \
+  --update_packages sys-devel/llvm sys-libs/compiler-rt \
+  --llvm_version google3 \
+  --failure_mode disable_patches
 ```
 
 The example above would update sys-devel/llvm and sys-libs/compiler-rt
@@ -70,7 +95,25 @@ sys-libs/compiler-rt.
 For help with the command line arguments of the script, run:
 
 ```
-python update_chromeos_llvm_next.py --help
+$ ./update_chromeos_llvm_next.py --help
+```
+
+For example, to update `LLVM_NEXT_HASH` to top of trunk of LLVM:
+
+```
+$ ./update_chromeos_llvm_next_hash.py \
+  --update_packages sys-devel/llvm sys-libs/compiler-rt \
+  --llvm_version tot \
+  --failure_mode disable_patches
+```
+
+For example, to update `LLVM_NEXT_HASH` to the git hash of revision 367622:
+
+```
+$ ./update_chromeos_llvm_next_hash.py \
+  --update_packages sys-devel/llvm sys-libs/compiler-rt \
+  --llvm_version 367622 \
+  --failure_mode disable_patches
 ```
 
 ## `llvm_patch_management.py`
@@ -88,8 +131,9 @@ tested when a new patch was added to their patch metadata file.
 For example:
 
 ```
-python llvm_patch_management.py --packages sys-devel/llvm sys-libs/compiler-rt
---failure_mode continue
+$ ./llvm_patch_management.py \
+  --packages sys-devel/llvm sys-libs/compiler-rt \
+  --failure_mode continue
 ```
 
 The above example tests sys-devel/llvm and sys-libs/compiler-rt patch metadata
@@ -98,7 +142,7 @@ file with the failure mode `continue`.
 For help with the command line arguments of the script, run:
 
 ```
-python llvm_patch_management.py --help
+$ ./llvm_patch_management.py --help
 ```
 
 ## `patch_manager.py`
@@ -111,7 +155,219 @@ testing a specific metadata file or a specific source tree.
 For help with the command line arguments of the script, run:
 
 ```
-python patch_manager.py --help
+$ ./patch_manager.py --help
+```
+
+For example, to see all the failed (if any) patches:
+
+```
+$ ./patch_manager.py \
+  --svn_version 367622 \
+  --patch_metadata_file /abs/path/to/patch/file \
+  --filesdir_path /abs/path/to/$FILESDIR \
+  --src_path /abs/path/to/src/tree \
+  --failure_mode continue
+```
+
+For example, to disable all patches that failed to apply:
+
+```
+$ ./patch_manager.py \
+  --svn_version 367622 \
+  --patch_metadata_file /abs/path/to/patch/file \
+  --filesdir_path /abs/path/to/$FILESDIR \
+  --src_path /abs/path/to/src/tree \
+  --failure_mode disable_patches
+```
+
+For example, to remove all patches that no longer apply:
+
+```
+$ ./patch_manager.py \
+  --svn_version 367622 \
+  --patch_metadata_file /abs/path/to/patch/file \
+  --filesdir_path /abs/path/to/$FILESDIR \
+  --src_path /abs/path/to/src/tree \
+  --failure_mode remove_patches
+```
+
+For example, to bisect a failing patch and stop at the first bisected patch:
+
+```
+$ ./patch_manager.py \
+  --svn_version 367622 \
+  --patch_metadata_file /abs/path/to/patch/file \
+  --filesdir_path /abs/path/to/$FILESDIR \
+  --src_path /abs/path/to/src/tree \
+  --failure_mode bisect_patches \
+  --good_svn_version 365631
+```
+
+For example, to bisect a failing patch and then continue bisecting the rest of
+the failed patches:
+
+```
+$ ./patch_manager.py \
+  --svn_version 367622 \
+  --patch_metadata_file /abs/path/to/patch/file \
+  --filesdir_path /abs/path/to/$FILESDIR \
+  --src_path /abs/path/to/src/tree \
+  --failure_mode bisect_patches \
+  --good_svn_version 365631 \
+  --continue_bisection True
+```
+
+## LLVM Bisection
+
+### `llvm_bisection.py`
+
+#### Usage
+
+This script is used to bisect a bad revision of LLVM. After the script finishes,
+the user requires to run the script again to continue the bisection. Intially,
+the script creates a JSON file that does not exist which then continues
+bisection (after invoking the script again) based off of the JSON file.
+
+For example, assuming the revision 369420 is the bad revision:
+
+```
+$ ./llvm_bisection.py \
+  --parallel 3 \
+  --start_rev 369410 \
+  --end_rev 369420 \
+  --last_tested /abs/path/to/tryjob/file/ \
+  --extra_change_lists 513590 \
+  --builder eve-release-tryjob \
+  --options latest-toolchain
+```
+
+The above example bisects the bad revision (369420), starting from the good
+revision 369410 and launching 3 tryjobs in between if possible (`--parallel`).
+Here, the `--last_tested` path is a path to a JSON file that does not exist. The
+tryjobs are tested on the eve board. `--extra_change_lists` and `--options`
+indicate what parameters to pass into launching a tryjob.
+
+For help with the command line arguments of the script, run:
+
+```
+$ ./llvm_bisection.py --help
+```
+
+### `update_tryjob_status.py`
+
+#### Usage
+
+This script updates a tryjob's 'status' value when bisecting LLVM. This script
+can use the file that was created by `llvm_bisection.py`.
+
+An example when this script would be used is when the result of tryjob that was
+launched was 'fail' (due to flaky infra) but it should really have been
+'success'.
+
+For example, to update a tryjob's 'status' to 'good':
+
+```
+$ ./update_tryjob_status.py \
+  --set_status good \
+  --revision 369412 \
+  --status_file /abs/path/to/tryjob/file
+```
+
+The above example uses the file in `--status_file` to update a tryjob in that
+file that tested the revision 369412 and sets its 'status' value to 'good'.
+
+For help with the command line arguments of the script, run:
+
+```
+$ ./update_tryjob_status.py --help
+```
+
+For example, to update a tryjob's 'status' to 'bad':
+
+```
+$ ./update_tryjob_status.py \
+  --set_status bad \
+  --revision 369412 \
+  --status_file /abs/path/to/tryjob/file
+```
+
+For example, to update a tryjob's 'status' to 'pending':
+
+```
+$ ./update_tryjob_status.py \
+  --set_status pending \
+  --revision 369412 \
+  --status_file /abs/path/to/tryjob/file
+```
+
+For example, to update a tryjob's 'status' to 'skip':
+
+```
+$ ./update_tryjob_status.py \
+  --set_status skip \
+  --revision 369412 \
+  --status_file /abs/path/to/tryjob/file
+```
+
+For example, to update a tryjob's 'status' based off a custom script exit code:
+
+```
+$ ./update_tryjob_status.py \
+  --set_status custom_script \
+  --revision 369412 \
+  --status_file /abs/path/to/tryjob/file \
+  --custom_script /abs/path/to/script.py
+```
+
+### `modify_a_tryjob.py`
+
+#### Usage
+
+This script modifies a tryjob directly given an already created tryjob file when
+bisecting LLVM. The file created by `llvm_bisection.py` can be used in this
+script.
+
+An example when this script would be used is when a tryjob needs to be manually
+added.
+
+For example:
+
+```
+$ ./modify_a_tryjob.py \
+  --modify_a_tryjob add \
+  --revision 369416 \
+  --extra_change_lists 513590 \
+  --options latest-toolchain \
+  --builder eve-release-tryjob \
+  --status_file /abs/path/to/tryjob/file
+```
+
+The above example creates a tryjob that tests revision 369416 on the eve board,
+passing in the extra arguments (`--extra_change_lists` and `--options`). The
+tryjob is then inserted into the file passed in via `--status_file`.
+
+For help with the command line arguments of the script, run:
+
+```
+$ ./modify_a_tryjob.py --help
+```
+
+For example, to remove a tryjob that tested revision 369412:
+
+```
+$ ./modify_a_tryjob.py \
+  --modify_a_tryjob remove \
+  --revision 369412 \
+  --status_file /abs/path/to/tryjob/file
+```
+
+For example, to relaunch a tryjob that tested revision 369418:
+
+```
+$ ./modify_a_tryjob.py \
+  --modify_a_tryjob relaunch \
+  --revision 369418 \
+  --status_file /abs/path/to/tryjob/file
 ```
 
 ## Other Helpful Scripts