Swap READMEs to markdown
Suggested by vapier@ in I7daf1cbe93f8809e469698d7772a6c68baf9e194
This ignores README.chromium, since I'm unsure if that's a special name
that some tool somewhere relies on.
I skimmed over all of these in gitiles (as you can probably tell by the
35 patch sets :) ) and fixed the issues that jumped out at me. I'm sure
that some remain somewhere, but I think I got the majority of them.
An attempt has been made to make all files roughly follow the rules
here:
https://github.com/google/styleguide/blob/gh-pages/docguide/style.md
Note that not all of them have super meaningful introductions with
ToCs/etc, but the rest should be relatively consistent with that guide.
BUG=None
TEST=Manual inspection
Change-Id: I158048d972d49966e3b8ff1e07e5429928edb339
Reviewed-on: https://chromium-review.googlesource.com/1504893
Commit-Ready: George Burgess <gbiv@chromium.org>
Tested-by: George Burgess <gbiv@chromium.org>
Reviewed-by: George Burgess <gbiv@chromium.org>
diff --git a/README b/README
deleted file mode 100644
index 3ab3d7b..0000000
--- a/README
+++ /dev/null
@@ -1,10 +0,0 @@
-To run scripts in this directory, first run:
-
-export PYTHONPATH=$(readlink -f .):$PYTHONPATH
-
-from this directory.
-
-Then you can run any script.
-
-To get help on any script, type in python <script> --help, or refer to the
-header of the script for more information.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a318e38
--- /dev/null
+++ b/README.md
@@ -0,0 +1,18 @@
+# `toolchain-utils`
+
+Various utilities used by the Chrome OS toolchain team.
+
+## Note
+
+To run Python scripts in this directory, first run:
+
+```
+export PYTHONPATH=$(readlink -f .):$PYTHONPATH
+```
+
+from this directory.
+
+Then you can run any script.
+
+To get help on any script, type in `python <script> --help`, or refer to the
+header of the script for more information.
diff --git a/android_bench_suite/README.md b/android_bench_suite/README.md
new file mode 100644
index 0000000..b539c7c
--- /dev/null
+++ b/android_bench_suite/README.md
@@ -0,0 +1,49 @@
+# `android_bench_suite`
+
+This is a Android Toolchain benchmark suite.
+
+Where to find this suite:
+
+This suite locates at google3, please create a google3 branch first, then run:
+
+```
+$ cd experimental/users/zhizhouy/benchtoolchain
+```
+
+Copy this directory to the place you want to put it.
+
+To use this suite:
+1. Configure the basic envrionment in `env_setting` file.
+
+2. Run `./apply_patches.py`, which will:
+
+ 1. Patch all the android benchmarks in the android tree.
+ Benchmark Panorama does not exist in android tree, so perftests/
+ gets copied into the top-level of android tree.
+
+ 2. Apply patch autotest.diff to `android_root/external/autotest`, which
+ includes all the test scripts for benchmarks. Copy testcases to
+ related autotest directory.
+
+ If you have applied the patch partially and hope to discard the
+ patch, just run `discard_patches.py`
+
+3. Build and run benchmark on the device using ./run.py. You can either
+ use test configuration file (-t `test_config`), or set all the variables
+ manually.
+
+4. The raw results locate at `bench_result_*` in bench suite home
+ directory.
+
+5. The JSON format result will be generated for crosperf report.
+
+Utility tools:
+
+1. Autotest is a test framework located in android exteranl/autotest
+ Before first time running it, please run
+ `utils/build_externals.py` first to ensure all the environments
+ and tools needed are installed.
+
+2. Crosperf is a report generating tool in ChromeOS toolchain utilities.
+ Please look for it in chromium source:
+ `src/third_party/toolchain-utils/crosperf`.
diff --git a/android_bench_suite/README.txt b/android_bench_suite/README.txt
deleted file mode 100644
index 3d0cceb..0000000
--- a/android_bench_suite/README.txt
+++ /dev/null
@@ -1,41 +0,0 @@
-This is a Android Toolchain benchmark suite.
-===========================================
-Where to find this suite:
- This suite locates at google3, please create a google3 branch first,
- then run:
- $cd experimental/users/zhizhouy/benchtoolchain
- Copy this directory to the place you want to put it.
-
-To use this suite:
- 1. Configure the basic envrionment in env_setting file.
-
- 2. Run ./apply_patches.py, which will:
- 1) Patch all the android benchmarks in the android tree.
- Benchmark Panorama does not exist in android tree, so perftests/
- gets copied into the top-level of android tree.
-
- 2) Apply patch autotest.diff to android_root/external/autotest, which
- includes all the test scripts for benchmarks. Copy testcases to
- related autotest directory.
-
- If you have applied the patch partially and hope to discard the
- patch, just run discard_patches.py
-
- 3. Build and run benchmark on the device using ./run.py. You can either
- use test configuration file (-t test_config), or set all the variables
- manually.
-
- 4. The raw results locate at bench_result_* in bench suite home
- directory.
-
- 5. The JSON format result will be generated for crosperf report.
-
-Utility tools:
- 1. Autotest is a test framework located in android exteranl/autotest
- Before first time running it, please run
- utils/build_externals.py first to ensure all the environments
- and tools needed are installed.
-
- 2. Crosperf is a report generating tool in ChromeOS toolchain utilities.
- Please look for it in chromium source:
- src/third_party/toolchain-utils/crosperf.
diff --git a/bestflags/README b/bestflags/README.md
similarity index 85%
rename from bestflags/README
rename to bestflags/README.md
index d9fc5ba..c9f4397 100644
--- a/bestflags/README
+++ b/bestflags/README.md
@@ -1,3 +1,5 @@
+# bestflags
+
There is a vast set of compiler flags that can be used to build Chrome for
ChromeOS. This option space has not been explored before. This directory
provides an infrastructure to build Chrome with certain flag combinations, test
@@ -6,10 +8,10 @@
in the N-Dimensional space of compiler flag combinations.
Currently, three different algorithms are built, namely genetic algorithm, hill
-climbing and negative flag iterative elimination. The module 'testing_batch.py'
+climbing and negative flag iterative elimination. The module `testing_batch.py`
contains the testing of these algorithms.
-To run the script, type in python testing_batch.py.
+To run the script, type in `python testing_batch.py`.
For further information about the project, please refer to the design document
at:
diff --git a/bestflags/examples/omnetpp/README b/bestflags/examples/omnetpp/README
deleted file mode 100644
index eba522f..0000000
--- a/bestflags/examples/omnetpp/README
+++ /dev/null
@@ -1,23 +0,0 @@
-This directory contains the omnetpp example in SPEC2006 benchmark.
-
-It also contains the json configuration file which includes the meta data
-information to run the experiment.
-
-This directory contains a build file build_omnetpp which is used by the build
-module of the framework to compile the application.
-This directory contains a test file test_omnetpp which is used by the test
-module of the framework to benchmark the optimization compilation.
-This directory contains a conf file which includes the set of optimization flags
-the experiment will try.
-
-To use this direction, first gives the file the executable permission.
- chmod a+x build_bikjmp
- chmod a+x test_bikjmp
-
-Copy the SPEC2006 benchmark into this directory.
-
-To run, invoke the example_algorithm.py in the parent directory.
- python example_algorithms.py --file=examples/omnetpp/example.json
-
-For help,
- python example_algorithms.py --help
\ No newline at end of file
diff --git a/bestflags/examples/omnetpp/README.md b/bestflags/examples/omnetpp/README.md
new file mode 100644
index 0000000..b4582d0
--- /dev/null
+++ b/bestflags/examples/omnetpp/README.md
@@ -0,0 +1,34 @@
+# `omnetpp`
+
+This directory contains the omnetpp example in SPEC2006 benchmark.
+
+It also contains the json configuration file which includes the meta data
+information to run the experiment.
+
+This directory contains a build file `build_omnetpp` which is used by the build
+module of the framework to compile the application.
+This directory contains a test file `test_omnetpp` which is used by the test
+module of the framework to benchmark the optimization compilation.
+This directory contains a conf file which includes the set of optimization flags
+the experiment will try.
+
+To use this direction, first gives the file the executable permission.
+
+```
+chmod a+x build_bikjmp
+chmod a+x test_bikjmp
+```
+
+Copy the SPEC2006 benchmark into this directory.
+
+To run, invoke the `example_algorithm.py` in the parent directory.
+
+```
+python example_algorithms.py --file=examples/omnetpp/example.json
+```
+
+For help,
+
+```
+python example_algorithms.py --help
+```
diff --git a/binary_search_tool/README.bisect b/binary_search_tool/README.bisect
deleted file mode 100644
index 49e0c08..0000000
--- a/binary_search_tool/README.bisect
+++ /dev/null
@@ -1,217 +0,0 @@
-
-bisect.py is a wrapper around the general purpose
-binary_search_state.py. It provides a user friendly interface for
-bisecting various compilation errors. The 2 currently provided
-methods of bisecting are ChromeOS package and object bisection. Each
-method defines a default set of options to pass to
-binary_search_state.py and allow the user to override these defaults
-(see the "Overriding" section).
-
-** NOTE **
-All commands, examples, scripts, etc. are to be run from your chroot unless
-stated otherwise.
-
-Bisection Methods:
-
-1) ChromeOS Package:
- This method will bisect across all packages in a ChromeOS repository and find
- the offending packages (according to your test script). This method takes the
- following arguments:
-
- board: The board to bisect on. For example: daisy, falco, etc.
- remote: The IP address of the physical machine you're using to test with.
-
- By default the ChromeOS package method will do a simple interactive test that
- pings the machine and prompts the user if the machine is good.
-
- a) Setup:
- The ChromeOS package method requires that you have three build trees:
-
- /build/${board}.bad - The build tree for your "bad" build
- /build/${board}.good - The build tree for your "good" build
- /build/${board}.work - A full copy of /build/${board}.bad
-
- b) Cleanup:
- bisect.py does most cleanup for you, the only
- thing required by the user is to cleanup all built images and the
- three build trees made in /build/
-
- c) Default Arguments:
- --get_initial_items='cros_pkg/get_initial_items.sh'
- --switch_to_good='cros_pkg/switch_to_good.sh'
- --switch_to_bad='cros_pkg/switch_to_bad.sh'
- --test_setup_script='cros_pkg/test_setup.sh'
- --test_script='cros_pkg/interactive_test.sh'
- --incremental
- --prune
- --file_args
-
- d) Additional Documentation:
- See ./cros_pkg/README.cros_pkg_triage for full documentation of ChromeOS
- package bisection.
-
- e) Examples:
- i) Basic interactive test package bisection, on daisy board:
- ./bisect.py package daisy 172.17.211.184
-
- ii) Basic boot test package bisection, on daisy board:
- ./bisect.py package daisy 172.17.211.184 -t cros_pkg/boot_test.sh
-
-2) ChromeOS Object:
- This method will bisect across all objects in a ChromeOS package and find
- the offending objects (according to your test script). This method takes the
- following arguments:
-
- board: The board to bisect on. For example: daisy, falco, etc.
- remote: The IP address of the physical machine you're using to test with.
- package: The package to bisect with. For example: chromeos-chrome
- dir: (Optional) the directory for your good/bad build trees. Defaults to
- $BISECT_DIR or /tmp/sysroot_bisect. This value will set $BISECT_DIR
- for all bisecting scripts.
-
- By default the ChromeOS object method will do a simple interactive test that
- pings the machine and prompts the user if the machine is good.
-
- a) Setup:
- The ChromeOS package method requires that you populate your good and bad set
- of objects. sysroot_wrapper will automatically detect the BISECT_STAGE
- variable and use this to populate emerged objects. Here is an example:
-
- # Defaults to /tmp/sysroot_bisect
- export BISECT_DIR="/path/to/where/you/want/to/store/builds/"
-
- export BISECT_STAGE="POPULATE_GOOD"
- ./switch_to_good_compiler.sh
- emerge-${board} -C ${package_to_bisect}
- emerge-${board} ${package_to_bisect}
-
- export BISECT_STAGE="POPULATE_BAD"
- ./switch_to_bad_compiler.sh
- emerge-${board} -C {package_to_bisect}
- emerge-${board} ${package_to_bisect}
-
- b) Cleanup:
- The user must clean up all built images and the populated object files.
-
- c) Default Arguments:
- --get_initial_items='sysroot_wrapper/get_initial_items.sh'
- --switch_to_good='sysroot_wrapper/switch_to_good.sh'
- --switch_to_bad='sysroot_wrapper/switch_to_bad.sh'
- --test_setup_script='sysroot_wrapper/test_setup.sh'
- --test_script='sysroot_wrapper/interactive_test.sh'
- --noincremental
- --prune
- --file_args
-
- d) Additional Documentation:
- See ./sysroot_wrapper/README for full documentation of ChromeOS object file
- bisecting.
-
- e) Examples:
- i) Basic interactive test object bisection, on daisy board for
- cryptohome package:
- ./bisect.py object daisy 172.17.211.184 cryptohome
-
- ii) Basic boot test package bisection, on daisy board for cryptohome
- package:
- ./bisect.py object daisy 172.17.211.184 cryptohome \
- --test_script=sysroot_wrapper/boot_test.sh
-
-3) Android object:
- NOTE: Because this isn't a ChromeOS bisection tool, the concept of a
- chroot doesn't exist. Just run this tool from a normal shell.
-
- This method will bisect across all objects in the Android source tree and
- find the offending objects (according to your test script). This method takes
- the following arguments:
-
- android_src: The location of your android source tree
- num_jobs: (Optional) The number of jobs to pass to make. This is dependent
- on how many cores your machine has. A good number is probably
- somewhere around 5 to 10.
- device_id: (Optional) The serial code for the device you are testing on.
- This is used to determine which device should be used in case
- multiple devices are plugged into your computer. You can get
- serial code for your device by running "adb devices".
- dir: (Optional) the directory for your good/bad build trees. Defaults to
- $BISECT_DIR or ~/ANDROID_BISECT/. This value will set $BISECT_DIR
- for all bisecting scripts.
-
- By default the Android object method will do a simple interactive test that
- pings the machine and prompts the user if the machine is good.
-
- a) Setup:
- The Android object method requires that you populate your good and bad set
- of objects. The Android compiler wrapper will automatically detect the
- BISECT_STAGE variable and use this to populate emerged objects. Here is an
- example:
-
- # Defaults to ~/ANDROID_BISECT/
- export BISECT_DIR="/path/to/where/you/want/to/store/builds/"
-
- export BISECT_STAGE="POPULATE_GOOD"
- # Install the "good" compiler
- ./switch_to_good_compiler.sh
- make clean
- make -j <your_preferred_number_of_jobs>
-
- export BISECT_STAGE="POPULATE_BAD"
- # Install the "bad" compiler
- ./switch_to_bad_compiler.sh
- make clean
- make -j <your_preferred_number_of_jobs>
-
- b) Cleanup:
- The user must clean up all built images and the populated object files.
-
- c) Default Arguments:
- --get_initial_items='android/get_initial_items.sh'
- --switch_to_good='android/switch_to_good.sh'
- --switch_to_bad='android/switch_to_bad.sh'
- --test_setup_script='android/test_setup.sh'
- --test_script='android/interactive_test.sh'
- --incremental
- --prune
- --file_args
-
- d) Additional Documentation:
- See ./android/README.android for full documentation of Android object file
- bisecting.
-
- e) Examples:
- i) Basic interactive test android bisection, where the android source is
- at ~/android_src:
- ./bisect.py android ~/android_src
-
- ii) Basic boot test android bisection, where the android source is at
- ~/android_src, and 10 jobs will be used to build android:
- ./bisect.py android ~/android_src --num_jobs=10 \
- --test_script=sysroot_wrapper/boot_test.sh
-
-Resuming:
- bisect.py and binary_search_state.py offer the
- ability to resume a bisection in case it was interrupted by a
- SIGINT, power failure, etc. Every time the tool completes a
- bisection iteration its state is saved to disk (usually to the file
- "./bisect_driver.py.state"). If passed the --resume option, the tool
- it will automatically detect the state file and resume from the last
- completed iteration.
-
-Overriding:
- You can run ./bisect.py --help or ./binary_search_state.py
- --help for a full list of arguments that can be overriden. Here are
- a couple of examples:
-
- Example 1 (do boot test instead of interactive test):
- ./bisect.py package daisy 172.17.211.182 --test_script=cros_pkg/boot_test.sh
-
- Example 2 (do package bisector system test instead of interactive test, this
- is used to test the bisecting tool itself -- see comments in
- hash_test.sh for more details):
- ./bisect.py package daisy 172.17.211.182 \
- --test_script=common/hash_test.sh --test_setup_script=""
-
- Example 3 (enable verbose mode, disable pruning, and disable verification):
- ./bisect.py package daisy 172.17.211.182 \
- --verbose --prune=False --verify=False
-
diff --git a/binary_search_tool/README.bisect.md b/binary_search_tool/README.bisect.md
new file mode 100644
index 0000000..74715ca
--- /dev/null
+++ b/binary_search_tool/README.bisect.md
@@ -0,0 +1,248 @@
+# `bisect.py`
+
+`bisect.py` is a wrapper around the general purpose
+`binary_search_state.py`. It provides a user friendly interface for
+bisecting various compilation errors. The 2 currently provided
+methods of bisecting are ChromeOS package and object bisection. Each
+method defines a default set of options to pass to
+`binary_search_state.py` and allow the user to override these defaults
+(see the "Overriding" section).
+
+Please note that all commands, examples, scripts, etc. are to be run from your
+chroot unless stated otherwise.
+
+## Bisection Methods
+
+### ChromeOS Package
+
+This method will bisect across all packages in a ChromeOS repository and find
+the offending packages (according to your test script). This method takes the
+following arguments:
+
+* board: The board to bisect on. For example: daisy, falco, etc.
+* remote: The IP address of the physical machine you're using to test with.
+
+By default the ChromeOS package method will do a simple interactive test that
+pings the machine and prompts the user if the machine is good.
+
+1. Setup: The ChromeOS package method requires that you have three build trees:
+
+ ```
+ /build/${board}.bad - The build tree for your "bad" build
+ /build/${board}.good - The build tree for your "good" build
+ /build/${board}.work - A full copy of /build/${board}.bad
+ ```
+
+1. Cleanup: bisect.py does most cleanup for you, the only thing required by the
+ user is to cleanup all built images and the three build trees made in
+ `/build/`
+
+1. Default Arguments:
+
+ ```
+ --get_initial_items='cros_pkg/get_initial_items.sh'
+ --switch_to_good='cros_pkg/switch_to_good.sh'
+ --switch_to_bad='cros_pkg/switch_to_bad.sh'
+ --test_setup_script='cros_pkg/test_setup.sh'
+ --test_script='cros_pkg/interactive_test.sh'
+ --incremental
+ --prune
+ --file_args
+ ```
+
+1. Additional Documentation: See `./cros_pkg/README.cros_pkg_triage` for full
+ documentation of ChromeOS package bisection.
+
+1. Examples:
+
+ 1. Basic interactive test package bisection, on daisy board:
+
+ ```
+ ./bisect.py package daisy 172.17.211.184
+ ```
+
+ 2. Basic boot test package bisection, on daisy board:
+
+ ```
+ ./bisect.py package daisy 172.17.211.184 -t cros_pkg/boot_test.sh
+ ```
+
+### ChromeOS Object
+
+This method will bisect across all objects in a ChromeOS package and find
+the offending objects (according to your test script). This method takes the
+following arguments:
+
+* board: The board to bisect on. For example: daisy, falco, etc.
+* remote: The IP address of the physical machine you're using to test with.
+* package: The package to bisect with. For example: chromeos-chrome
+* dir: (Optional) the directory for your good/bad build trees. Defaults to
+ $BISECT_DIR or /tmp/sysroot_bisect. This value will set $BISECT_DIR
+ for all bisecting scripts.
+
+By default the ChromeOS object method will do a simple interactive test that
+pings the machine and prompts the user if the machine is good.
+
+1. Setup: The ChromeOS package method requires that you populate your good and
+ bad set of objects. `sysroot_wrapper` will automatically detect the
+ `BISECT_STAGE` variable and use this to populate emerged objects. Here is an
+ example:
+
+ ```
+ # Defaults to /tmp/sysroot_bisect
+ export BISECT_DIR="/path/to/where/you/want/to/store/builds/"
+
+ export BISECT_STAGE="POPULATE_GOOD"
+ ./switch_to_good_compiler.sh
+ emerge-${board} -C ${package_to_bisect}
+ emerge-${board} ${package_to_bisect}
+
+ export BISECT_STAGE="POPULATE_BAD"
+ ./switch_to_bad_compiler.sh
+ emerge-${board} -C {package_to_bisect}
+ emerge-${board} ${package_to_bisect}
+ ```
+
+1. Cleanup: The user must clean up all built images and the populated object
+ files.
+
+1. Default Arguments:
+
+ ```
+ --get_initial_items='sysroot_wrapper/get_initial_items.sh'
+ --switch_to_good='sysroot_wrapper/switch_to_good.sh'
+ --switch_to_bad='sysroot_wrapper/switch_to_bad.sh'
+ --test_setup_script='sysroot_wrapper/test_setup.sh'
+ --test_script='sysroot_wrapper/interactive_test.sh'
+ --noincremental
+ --prune
+ --file_args
+ ```
+
+1. Additional Documentation: See `./sysroot_wrapper/README` for full
+ documentation of ChromeOS object file bisecting.
+
+1. Examples:
+
+ 1. Basic interactive test object bisection, on daisy board for cryptohome
+ package: `./bisect.py object daisy 172.17.211.184 cryptohome`
+
+ 2. Basic boot test package bisection, on daisy board for cryptohome
+ package: `./bisect.py object daisy 172.17.211.184 cryptohome
+ --test_script=sysroot_wrapper/boot_test.sh`
+
+### Android object
+
+NOTE: Because this isn't a ChromeOS bisection tool, the concept of a
+ chroot doesn't exist. Just run this tool from a normal shell.
+
+This method will bisect across all objects in the Android source tree and
+find the offending objects (according to your test script). This method takes
+the following arguments:
+
+* `android_src`: The location of your android source tree
+
+* `num_jobs`: (Optional) The number of jobs to pass to make. This is dependent
+ on how many cores your machine has. A good number is probably somewhere
+ around 5 to 10.
+
+* `device_id`: (Optional) The serial code for the device you are testing on.
+ This is used to determine which device should be used in case multiple
+ devices are plugged into your computer. You can get serial code for your
+ device by running "adb devices".
+
+* `dir`: (Optional) the directory for your good/bad build trees. Defaults to
+ `$BISECT_DIR` or `~/ANDROID_BISECT/`. This value will set `$BISECT_DIR` for
+ all bisecting scripts.
+
+ By default the Android object method will do a simple interactive test that
+ pings the machine and prompts the user if the machine is good.
+
+1. Setup: The Android object method requires that you populate your good and
+ bad set of objects. The Android compiler wrapper will automatically detect
+ the `BISECT_STAGE` variable and use this to populate emerged objects. Here
+ is an example:
+
+ ```
+ # Defaults to ~/ANDROID_BISECT/
+ export BISECT_DIR="/path/to/where/you/want/to/store/builds/"
+
+ export BISECT_STAGE="POPULATE_GOOD"
+ # Install the "good" compiler
+ ./switch_to_good_compiler.sh
+ make clean
+ make -j <your_preferred_number_of_jobs>
+
+ export BISECT_STAGE="POPULATE_BAD"
+ # Install the "bad" compiler
+ ./switch_to_bad_compiler.sh
+ make clean
+ make -j <your_preferred_number_of_jobs>
+ ```
+
+1. Cleanup: The user must clean up all built images and the populated object
+ files.
+
+1. Default Arguments:
+
+ ```
+ --get_initial_items='android/get_initial_items.sh'
+ --switch_to_good='android/switch_to_good.sh'
+ --switch_to_bad='android/switch_to_bad.sh'
+ --test_setup_script='android/test_setup.sh'
+ --test_script='android/interactive_test.sh'
+ --incremental
+ --prune
+ --file_args
+ ```
+
+1. Additional Documentation: See `./android/README.android` for full
+ documentation of Android object file bisecting.
+
+1. Examples:
+
+ 1. Basic interactive test android bisection, where the android source is at
+ ~/android_src: `./bisect.py android ~/android_src`
+
+ 2. Basic boot test android bisection, where the android source is at
+ `~/android_src`, and 10 jobs will be used to build android: `./bisect.py
+ android ~/android_src --num_jobs=10
+ --test_script=sysroot_wrapper/boot_test.sh`
+
+### Resuming
+
+`bisect.py` and `binary_search_state.py` offer the
+ability to resume a bisection in case it was interrupted by a
+SIGINT, power failure, etc. Every time the tool completes a
+bisection iteration its state is saved to disk (usually to the file
+`./bisect_driver.py.state`). If passed the --resume option, the tool
+it will automatically detect the state file and resume from the last
+completed iteration.
+
+### Overriding
+
+You can run `./bisect.py --help` or `./binary_search_state.py
+--help` for a full list of arguments that can be overriden. Here are
+a couple of examples:
+
+Example 1 (do boot test instead of interactive test):
+
+```
+./bisect.py package daisy 172.17.211.182 --test_script=cros_pkg/boot_test.sh
+```
+
+Example 2 (do package bisector system test instead of interactive test, this
+ is used to test the bisecting tool itself -- see comments in
+ hash_test.sh for more details):
+
+```
+./bisect.py package daisy 172.17.211.182 \
+ --test_script=common/hash_test.sh --test_setup_script=""
+```
+
+Example 3 (enable verbose mode, disable pruning, and disable verification):
+
+```
+./bisect.py package daisy 172.17.211.182
+ --verbose --prune=False --verify=False
+```
diff --git a/binary_search_tool/README.pass_bisect b/binary_search_tool/README.pass_bisect
deleted file mode 100644
index 3d419b2..0000000
--- a/binary_search_tool/README.pass_bisect
+++ /dev/null
@@ -1,77 +0,0 @@
-This document describes a feature for the bisection tool, which provides
-pass and transformation level bisection for a bad object file.
-
-Before reading this document, please refer to README.bisect for general usage
-of the bisection tool.
-
-The benefit of using pass level bisection is:
-When building a bad object file, it can tell you which pass and transformation
-in the compiler caused the error.
-
-Notice: This tool will only work for LLVM/clang, since it is using options
- `-opt-bisect-limit` and `print-debug-counter` that only exist in LLVM.
-
-ARGUMENTS
-
- All the required arguments in object-file-level bisection tool are still
- to be provided. In addition, you will need to add the following arguments:
-
- 1)--pass_bisect: enables pass level bisection
- 2)--ir_diff: enables output of IR differences
-
- Please refer to `--help` or the examples below for details about how to use
- them.
-
-HOW TO USE: ChromeOS
-
-TODO - Future work: Currently this only works for Android.
-
-HOW TO USE: Android
-
- 1) Prerequisite
-
- A general setup is still needed for Android, which means that you need
- to populate good and bad set of objects with two versions of compilers.
-
- See the documentation in README.bisect for more detailed instructions.
-
- 2) Pass/Transformation Bisection
-
- If you do not wish to override the other arguments, this command should
- be sufficient to do pass/transformation level bisection:
-
- ./bisect.py android PATH_TO_ANDROID_HOME_DIR
- --pass_bisect=’android/generate_cmd.sh’
- --prune=False
- --ir_diff
- --verbose
-
- Where:
- --pass_bisect:
- Enables pass/transformation level bisection and with default
- script to generate the command as ‘android/generate_cmd.sh’.
- --prune:
- For now, prune must be set to False to return only the first
- bad item.
- --ir_diff:
- Optional argument to print out IR differences.
- --verbose:
- To show IR diff, verbose needs to be on.
-
- Other default arguments:
- --get_initial_items='android/get_initial_items.sh'
- --switch_to_good='android/switch_to_good.sh'
- --switch_to_bad='android/switch_to_bad.sh'
- --test_setup_script='android/test_setup.sh'
- --test_script='android/interactive_test.sh'
- --incremental
- --prune
- --file_args
-
- You can always override them if needed. See README.bisect for more
- details.
-
- 3) Other features:
-
- Features such as resuming, number of jobs, and device id remain the
- same as before. See README.bisect for more details.
diff --git a/binary_search_tool/README.pass_bisect.md b/binary_search_tool/README.pass_bisect.md
new file mode 100644
index 0000000..d03a563
--- /dev/null
+++ b/binary_search_tool/README.pass_bisect.md
@@ -0,0 +1,83 @@
+# Pass bisection
+
+This document describes a feature for the bisection tool, which provides
+pass and transformation level bisection for a bad object file.
+
+Before reading this document, please refer to README.bisect for general usage
+of the bisection tool.
+
+The benefit of using pass level bisection is:
+When building a bad object file, it can tell you which pass and transformation
+in the compiler caused the error.
+
+*Notice:* This tool will only work for LLVM/clang, since it is using options
+`-opt-bisect-limit` and `print-debug-counter` that only exist in LLVM.
+
+## Arguments
+
+All the required arguments in object-file-level bisection tool are still
+to be provided. In addition, you will need to add the following arguments:
+
+1. `--pass_bisect`: enables pass level bisection
+2. `--ir_diff`: enables output of IR differences
+
+Please refer to `--help` or the examples below for details about how to use
+them.
+
+## HOW TO USE: ChromeOS
+
+*TODO* - Future work: Currently this only works for Android.
+
+## HOW TO USE: Android
+
+1. Prerequisites: A general setup is still needed for Android, which means that
+ you need to populate good and bad set of objects with two versions of
+ compilers.
+
+ See the documentation in `README.bisect.md` for more detailed instructions.
+
+1. Pass/Transformation Bisection: If you do not wish to override the other
+ arguments, this command should be sufficient to do pass/transformation level
+ bisection:
+
+ ```
+ ./bisect.py android PATH_TO_ANDROID_HOME_DIR
+ --pass_bisect=’android/generate_cmd.sh’
+ --prune=False
+ --ir_diff
+ --verbose
+ ```
+
+ Where:
+
+ ```
+ --pass_bisect:
+ Enables pass/transformation level bisection and with default
+ script to generate the command as ‘android/generate_cmd.sh’.
+ --prune:
+ For now, prune must be set to False to return only the first
+ bad item.
+ --ir_diff:
+ Optional argument to print out IR differences.
+ --verbose:
+ To show IR diff, verbose needs to be on.
+ ```
+
+ Other default arguments:
+
+ ```
+ --get_initial_items='android/get_initial_items.sh'
+ --switch_to_good='android/switch_to_good.sh'
+ --switch_to_bad='android/switch_to_bad.sh'
+ --test_setup_script='android/test_setup.sh'
+ --test_script='android/interactive_test.sh'
+ --incremental
+ --prune
+ --file_args
+ ```
+
+ You can always override them if needed. See README.bisect for more
+ details.
+
+1. Other features: Features such as resuming, number of jobs, and device id
+ remain the same as before. See README.bisect for more details.
diff --git a/binary_search_tool/README.testing b/binary_search_tool/README.testing
deleted file mode 100644
index 6c81ab9..0000000
--- a/binary_search_tool/README.testing
+++ /dev/null
@@ -1,80 +0,0 @@
-This file explains how to set up and run the various kinds of bisection tests.
-
-The bisection tool comes with several sets of tests which you should
-run after updating any of the bisection tool scripts OR after updating
-the Android compiler wrapper (to make sure the wrapper will still work
-correctly with bisection).
-
-Before you start.
-----------------
-
-Before you can run the tests, your PYTHONPATH environment variable
-must be correct. This means that it must include both the
-toolchain-utils directory and the binary_search_tool directory. The
-easiest way to set it is:
-
-$ cd toolchain-utils
-$ export PYTHONPATH=`pwd`:${PYTHONPATH}
-$ cd binary_search_tool
-$ export PYTHONPATH=`pwd`:${PYTHONPATH}
-
-
-Running the unittests.
-----------------------
-
-To run the basic unit tests:
-
-$ cd toolchain-utils/binary_search_tool/test
-$ ./binary_search_tool_tester.py
-
-Running the bisection tests, testing the compiler wrapper.
-----------------------------------------------------------
-
-If you want to run the bisection tests, and test the compiler wrapper
-(to make sure the POPULATE_GOOD and POPULATE_BAD stages are still
-working properly) you can do the following.
-
-If you are testing with the ANDROID COMPILER WRAPPER, you need to to some
-preliminary setup:
-
-Set up the compiler wrapper to replace GCC:
-
- $ cd <android-root/prebuilts/clang/host/linux-x86/clang-368880/bin
- $ cp clang gcc
- $ whereis gcc
- gcc: /usr/bin/gcc /usr/lib/gcc /usr/bin/X11/gcc /usr/share/man/man1/gcc.1.gz
- $ cd /usr/bin
- $ ls -l gcc
- lrwxrwxrwx 1 root root 7 Feb 3 17:00 gcc -> gcc-4.8*
- $ sudo mv gcc gcc.real
- $ sudo ln -s <android-root>/prebuilts/clang/host/linux-x86/clang-3688880/bin/gcc gcc
-
-Move to the correct directory, then run the test script:
-
- $ cd toolchain-utils/binary_search_tool
- $ ./run_bisect_test.py
-
-
-If you are testing with the CHROMEOS COMPILER WRAPPER, you MUST run the
-tests from INSIDE your CHROOT (but you don't need to do any special setup):
-
- $ cd <path-to-chromeos-root>
- $ cros_sdk
- $ cd ~/trunk/src/third_party/toolchain-utils
-
- Set up your PYTHONPATH:
-
- $ export PYTHONPATH=`pwd`:${PYTHONPATH}
- $ cd binary_search_tool
- $ export PYTHONPATH=`pwd`:${PYTHONPATH}
-
- Run the test script:
-
- $ ./run_bisect_test.py
-
-
-Running the bisection tests, without testing the compiler wrapper.
-------------------------------------------------------------------
-
-$ cd toolchain-utils/binary_search_tool
-$ ./full_bisect_test/run-test-nowrapper.sh
diff --git a/binary_search_tool/README.testing.md b/binary_search_tool/README.testing.md
new file mode 100644
index 0000000..139dc08
--- /dev/null
+++ b/binary_search_tool/README.testing.md
@@ -0,0 +1,94 @@
+# Testing the binary search tool
+
+This file explains how to set up and run the various kinds of bisection tests.
+
+The bisection tool comes with several sets of tests which you should
+run after updating any of the bisection tool scripts OR after updating
+the Android compiler wrapper (to make sure the wrapper will still work
+correctly with bisection).
+
+## Before you start.
+
+Before you can run the tests, your PYTHONPATH environment variable
+must be correct. This means that it must include both the
+toolchain-utils directory and the `binary_search_tool` directory. The
+easiest way to set it is:
+
+```
+$ cd toolchain-utils
+$ export PYTHONPATH=`pwd`:${PYTHONPATH}
+$ cd binary_search_tool
+$ export PYTHONPATH=`pwd`:${PYTHONPATH}
+```
+
+
+## Running the unittests.
+
+To run the basic unit tests:
+
+```
+$ cd toolchain-utils/binary_search_tool/test
+$ ./binary_search_tool_tester.py
+```
+
+# Running the bisection tests, testing the compiler wrapper.
+
+If you want to run the bisection tests, and test the compiler wrapper
+(to make sure the `POPULATE_GOOD` and `POPULATE_BAD` stages are still
+working properly) you can do the following.
+
+If you are testing with the ANDROID COMPILER WRAPPER, you need to to some
+preliminary setup:
+
+Set up the compiler wrapper to replace GCC:
+
+```
+$ cd <android-root/prebuilts/clang/host/linux-x86/clang-368880/bin
+$ cp clang gcc
+$ whereis gcc
+gcc: /usr/bin/gcc /usr/lib/gcc /usr/bin/X11/gcc /usr/share/man/man1/gcc.1.gz
+$ cd /usr/bin
+$ ls -l gcc
+lrwxrwxrwx 1 root root 7 Feb 3 17:00 gcc -> gcc-4.8*
+$ sudo mv gcc gcc.real
+$ sudo ln -s \
+ <android-root>/prebuilts/clang/host/linux-x86/clang-3688880/bin/gcc gcc
+```
+
+Move to the correct directory, then run the test script:
+
+```
+$ cd toolchain-utils/binary_search_tool
+$ ./run_bisect_test.py
+```
+
+If you are testing with the CHROMEOS COMPILER WRAPPER, you MUST run the
+tests from INSIDE your CHROOT (but you don't need to do any special setup):
+
+```
+$ cd <path-to-chromeos-root>
+$ cros_sdk
+$ cd ~/trunk/src/third_party/toolchain-utils
+```
+
+Set up your `PYTHONPATH`:
+
+```
+$ export PYTHONPATH=`pwd`:${PYTHONPATH}
+$ cd binary_search_tool
+$ export PYTHONPATH=`pwd`:${PYTHONPATH}
+```
+
+Run the test script:
+
+```
+$ ./run_bisect_test.py
+```
+
+
+## Running the bisection tests, without testing the compiler wrapper.
+
+```
+$ cd toolchain-utils/binary_search_tool
+$ ./full_bisect_test/run-test-nowrapper.sh
+```
diff --git a/binary_search_tool/android/README.android b/binary_search_tool/android/README.android
deleted file mode 100644
index 6e79d48..0000000
--- a/binary_search_tool/android/README.android
+++ /dev/null
@@ -1,191 +0,0 @@
-
-binary_search_state.py is a general binary search triage tool that
-performs a binary search on a set of things to try to identify which
-thing or thing(s) in the set is 'bad'. binary_search_state.py assumes
-that the user has two sets, one where everything is known to be good,
-and one which contains at least one bad item. binary_search_state.py
-then copies items from the good and bad sets into a working set and
-tests the result (good or bad). binary_search_state.py requires that
-a set of scripts be supplied to it for any particular job. For more
-information on binary_search_state.py, see
-
-https://sites.google.com/a/google.com/chromeos-toolchain-team-home2/home/team-tools-and-scripts/binary-searcher-tool-for-triage
-
-This particular set of scripts is designed to work with
-binary_search_state.py in order to find the bad object or set of
-bad objects in an Android build. Furthermore, it can also help find
-the bad compiler pass and transformation when building that bad object.
-
-
-QUICKSTART:
-
-After setting up your 2 build trees (see Prerequisites section), do the
-following:
-
- - Decide which test script to use (boot_test.sh or
- interactive_test.sh)
- - Get the serial number for the Android device you will use for testing.
- - Run the following:
-
- $ cd <android_src>
- $ source build/envsetup.sh
- $ lunch <android_device_lunch_combo>
- $ cd <path_to_toolchain_utils>/binary_search_tool/
- $ NUM_JOBS=10 ANDROID_SERIAL=<device_serial> \
- ./android/setup.sh <android_src>
-
- If you chose the boot test, then:
- TEST_SCRIPT=android/boot_test.sh
-
- If you chose the interactive test, then:
- TEST_SCRIPT=android/interactive_test.sh
-
- Finally, run the binary search tool:
-
- $ python ./binary_search_state.py \
- --get_initial_items=android/get_initial_items.sh \
- --switch_to_good=android/switch_to_good.sh \
- --switch_to_bad=android/switch_to_bad.sh \
- --test_setup_script=android/test_setup.sh \
- --test_script=$TEST_SCRIPT \
- --file_args \
- --prune
-
- Once you have completely finished doing the binary search/triage,
- run the cleanup script:
-
- $ android/cleanup.sh
-
-
-
-FILES AND SCRIPTS:
-
- Check the header comments for each script for more in depth documentation.
-
- boot_test.sh - One of two possible test scripts used to determine
- if the Android image built from the objects is good
- or bad. This script tests to see if the image
- booted, and requires no user intervention.
-
- cleanup.sh - This is called after the binary search tool completes. This
- script will clean up the common.sh file generated by setup.sh
-
- get_initial_items.sh - This script is used to determine all Android objects
- that will be bisected.
-
- test_setup.sh - This script will build and flash your image to the
- Android device. If the flash fails, this script will
- help the user troubleshoot by trying to flash again or
- by asking the user to manually flash it.
-
- interactive_test.sh - One of two possible scripts used to determine
- if the Android image built from the objects
- is good or bad. This script requires user
- interaction to determine if the image is
- good or bad.
-
- setup.sh - This is the first script the user should call, after
- taking care of the prerequisites. It sets up the
- environment appropriately for running the Android
- object binary search triage, and it generates the
- necessary common script (see below).
-
- switch_to_bad.sh - This script is used to link objects from the
- 'bad' build tree into the work area.
-
- switch_to_good.sh - This script is used to link objects from the
- 'good' build tree into the work area.
-
- generate_cmd.sh - This script will generate another temporary script, which
- contains the command line options to build the bad object
- file again with pass/transformation level limit.
-
-
-GENERATED SCRIPTS:
-
- common.sh - contains basic environment variable definitions for
- this binary search triage session.
-
-ASSUMPTIONS:
-
-- There are two different Android builds, for the same board/lunch combo with
- the same set of generated object files. One build creates a good working
- Android image and the other does not.
-
-- The toolchain bug you are tracking down is not related to the linker. If the
- linker is broken or generates bad code, this tool is unlikely to help you.
-
-
-PREREQUISITES FOR USING THESE SCRIPTS:
-
- Step 1: Decide where to store each build tree
- By default, each build tree is stored in "~/ANDROID_BISECT". However you
- can override this by exporting BISECT_DIR set to whatever directory you
- please. Keep in mind these build trees take dozens of gigabytes each.
-
- Step 2: Setup your android build environment
- 1. `cd <android_src>`
- 2. `source build/envsetup.sh`
- 3. `lunch <android_device_lunch_combo>`
-
- Step 3: Populate the good build tree
- 1. `make clean`
- 2. `export BISECT_STAGE=POPULATE_GOOD`
- 3. Install your "good" toolchain in Android, this will most likely be
- the toolchain that comes preinstalled with the Android source.
- 4. Build all of Android: `make -j10`. The "-j" parameter depends on how
- many cores your machine has. See Android documentation for more details.
-
- Step 4: Populate the bad build tree
- 1. `make clean`
- 2. `export BISECT_STAGE=POPULATE_BAD`
- 3. Install your "bad" toolchain in Android.
- 4. Build all of Android again.
-
- Step 5: Run the android setup script
- 1. `cd <path_to_toolchain_utils>/binary_search_tool/`
- 2. `NUM_JOBS=<jobs> ANDROID_SERIAL=<android_serial_num> \
- android/setup.sh <android_src>`
-
- WARNING: It's important that you leave the full "out/" directory in your
- Android source alone after Step 4. The binary search tool will
- use this directory as a skeleton to build each test image while
- triaging.
-
-USING THESE SCRIPTS FOR BINARY TRIAGE OF OBJECTS:
-
-To use these scripts, you must first run setup.sh, passing it the path to your
-Android source directory. setup.sh will do the following:
-
- - Verify that your build trees are set up correctly (with good, bad).
- - Verify that each build tree has the same contents.
- - Verify that the android build environment (lunch, etc.) are setup in your
- current shell.
- - Create the common.sh file that the other scripts passed to the
- binary triage tool will need.
-
-
-This set of scripts comes with two alternate test scripts. One test
-script, boot_test.sh, just checks to make sure that the image
-booted (wait for device to boot to home screen) and assumes that is enough.
-The other test script, interactive_test.sh, is interactive and asks YOU
-to tell it whether the image on the android device is ok or not (it
-prompts you and waits for a response).
-
-
-Once you have run setup.sh (and decided which test script you
-want to use) run the binary triage tool using these scripts to
-isolate/identify the bad object:
-
-./binary_search_state.py \
- --get_initial_items=android/get_initial_items.sh \
- --switch_to_good=android/switch_to_good.sh \
- --switch_to_bad=android/switch_to_bad.sh \
- --test_setup_script=android/test_setup.sh \
- --test_script=android/boot_test.sh \ # could use interactive_test.sh instead
- --prune
-
-
-After you have finished running the tool and have identified the bad
-object(s), you will want to run the cleanup script (android/cleanup.sh).
-
diff --git a/binary_search_tool/android/README.android.md b/binary_search_tool/android/README.android.md
new file mode 100644
index 0000000..9445dcb
--- /dev/null
+++ b/binary_search_tool/android/README.android.md
@@ -0,0 +1,209 @@
+# Android's binary search tool
+
+`binary_search_state.py` is a general binary search triage tool that
+performs a binary search on a set of things to try to identify which
+thing or thing(s) in the set is 'bad'. `binary_search_state.py` assumes
+that the user has two sets, one where everything is known to be good,
+and one which contains at least one bad item. `binary_search_state.py`
+then copies items from the good and bad sets into a working set and
+tests the result (good or bad). `binary_search_state.py` requires that
+a set of scripts be supplied to it for any particular job. For more
+information on `binary_search_state.py`, see
+
+https://sites.google.com/a/google.com/chromeos-toolchain-team-home2/home/team-tools-and-scripts/binary-searcher-tool-for-triage
+
+This particular set of scripts is designed to work with
+`binary_search_state.py` in order to find the bad object or set of
+bad objects in an Android build. Furthermore, it can also help find
+the bad compiler pass and transformation when building that bad object.
+
+
+## QUICKSTART
+
+After setting up your 2 build trees (see Prerequisites section), do the
+following:
+
+- Decide which test script to use (`boot_test.sh` or
+ `interactive_test.sh`)
+- Get the serial number for the Android device you will use for testing.
+- Run the following:
+
+ ```
+ $ cd <android_src>
+ $ source build/envsetup.sh
+ $ lunch <android_device_lunch_combo>
+ $ cd <path_to_toolchain_utils>/binary_search_tool/
+ $ NUM_JOBS=10 ANDROID_SERIAL=<device_serial> \
+ ./android/setup.sh <android_src>
+ ```
+
+ If you chose the boot test, then:
+
+ ```
+ TEST_SCRIPT=android/boot_test.sh
+ ```
+
+ If you chose the interactive test, then:
+
+ ```
+ TEST_SCRIPT=android/interactive_test.sh
+ ```
+
+ Finally, run the binary search tool:
+
+ ```
+ $ python ./binary_search_state.py \
+ --get_initial_items=android/get_initial_items.sh \
+ --switch_to_good=android/switch_to_good.sh \
+ --switch_to_bad=android/switch_to_bad.sh \
+ --test_setup_script=android/test_setup.sh \
+ --test_script=$TEST_SCRIPT \
+ --file_args \
+ --prune
+ ```
+
+ Once you have completely finished doing the binary search/triage,
+ run the cleanup script:
+
+ ```
+ $ android/cleanup.sh
+ ```
+
+
+## FILES AND SCRIPTS
+
+Check the header comments for each script for more in depth documentation.
+
+`boot_test.sh` - One of two possible test scripts used to determine
+ if the Android image built from the objects is good
+ or bad. This script tests to see if the image
+ booted, and requires no user intervention.
+
+`cleanup.sh` - This is called after the binary search tool completes. This
+ script will clean up the common.sh file generated by setup.sh
+
+`get_initial_items.sh` - This script is used to determine all Android objects
+ that will be bisected.
+
+`test_setup.sh` - This script will build and flash your image to the
+ Android device. If the flash fails, this script will
+ help the user troubleshoot by trying to flash again or
+ by asking the user to manually flash it.
+
+`interactive_test.sh` - One of two possible scripts used to determine
+ if the Android image built from the objects
+ is good or bad. This script requires user
+ interaction to determine if the image is
+ good or bad.
+
+`setup.sh` - This is the first script the user should call, after
+ taking care of the prerequisites. It sets up the
+ environment appropriately for running the Android
+ object binary search triage, and it generates the
+ necessary common script (see below).
+
+`switch_to_bad.sh` - This script is used to link objects from the
+ 'bad' build tree into the work area.
+
+`switch_to_good.sh` - This script is used to link objects from the
+ 'good' build tree into the work area.
+
+`generate_cmd.sh` - This script will generate another temporary script, which
+ contains the command line options to build the bad object
+ file again with pass/transformation level limit.
+
+
+## GENERATED SCRIPTS
+
+`common.sh` - contains basic environment variable definitions for
+ this binary search triage session.
+
+## ASSUMPTIONS
+
+- There are two different Android builds, for the same board/lunch combo with
+ the same set of generated object files. One build creates a good working
+ Android image and the other does not.
+
+- The toolchain bug you are tracking down is not related to the linker. If the
+ linker is broken or generates bad code, this tool is unlikely to help you.
+
+
+PREREQUISITES FOR USING THESE SCRIPTS:
+
+1. Decide where to store each build tree
+ By default, each build tree is stored in `~/ANDROID_BISECT`. However you
+ can override this by exporting `BISECT_DIR` set to whatever directory you
+ please. Keep in mind these build trees take dozens of gigabytes each.
+
+2. Setup your android build environment
+
+ ```
+ cd <android_src>
+ source build/envsetup.sh
+ lunch <android_device_lunch_combo>
+ ```
+
+3. Populate the good build tree
+
+ 1. `make clean`
+ 2. `export BISECT_STAGE=POPULATE_GOOD`
+ 3. Install your "good" toolchain in Android, this will most likely be
+ the toolchain that comes preinstalled with the Android source.
+ 4. Build all of Android: `make -j10`. The "-j" parameter depends on how
+ many cores your machine has. See Android documentation for more details.
+
+4. Populate the bad build tree
+
+ 1. `make clean`
+ 2. `export BISECT_STAGE=POPULATE_BAD`
+ 3. Install your "bad" toolchain in Android.
+ 4. Build all of Android again.
+
+5. Run the android setup script
+
+ 1. `cd <path_to_toolchain_utils>/binary_search_tool/`
+ 2. `NUM_JOBS=<jobs> ANDROID_SERIAL=<android_serial_num>
+ android/setup.sh <android_src>`
+
+WARNING: It's important that you leave the full `out/` directory in your
+ Android source alone after Step 4. The binary search tool will
+ use this directory as a skeleton to build each test image while
+ triaging.
+
+## USING THESE SCRIPTS FOR BINARY TRIAGE OF OBJECTS
+
+To use these scripts, you must first run setup.sh, passing it the path to your
+Android source directory. setup.sh will do the following:
+
+- Verify that your build trees are set up correctly (with good, bad).
+- Verify that each build tree has the same contents.
+- Verify that the android build environment (lunch, etc.) are setup in your
+ current shell.
+- Create the common.sh file that the other scripts passed to the
+ binary triage tool will need.
+
+
+This set of scripts comes with two alternate test scripts. One test
+script, `boot_test.sh`, just checks to make sure that the image
+booted (wait for device to boot to home screen) and assumes that is enough.
+The other test script, `interactive_test.sh`, is interactive and asks YOU
+to tell it whether the image on the android device is ok or not (it
+prompts you and waits for a response).
+
+
+Once you have run `setup.sh` (and decided which test script you
+want to use) run the binary triage tool using these scripts to
+isolate/identify the bad object:
+
+```
+./binary_search_state.py \
+ --get_initial_items=android/get_initial_items.sh \
+ --switch_to_good=android/switch_to_good.sh \
+ --switch_to_bad=android/switch_to_bad.sh \
+ --test_setup_script=android/test_setup.sh \
+ --test_script=android/boot_test.sh \ # could use interactive_test.sh instead
+ --prune
+```
+
+After you have finished running the tool and have identified the bad
+object(s), you will want to run the cleanup script (android/cleanup.sh).
diff --git a/binary_search_tool/cros_pkg/README.cros_pkg_triage b/binary_search_tool/cros_pkg/README.cros_pkg_triage
deleted file mode 100644
index 5e28500..0000000
--- a/binary_search_tool/cros_pkg/README.cros_pkg_triage
+++ /dev/null
@@ -1,185 +0,0 @@
-
-binary_search_state.py is a general binary search triage tool that
-performs a binary search on a set of things to try to identify which
-thing or thing(s) in the set is 'bad'. binary_search_state.py assumes
-that the user has two sets, one where everything is known to be good,
-ane one which contains at least one bad item. binary_search_state.py
-then copies items from the good and bad sets into a working set and
-tests the result (good or bad). binary_search_state.py requires that
-a set of scripts be supplied to it for any particular job. For more
-information on binary_search_state.py, see
-
-https://sites.google.com/a/google.com/chromeos-toolchain-team-home2/home/team-tools-and-scripts/binary-searcher-tool-for-triage
-
-This particular set of scripts is designed to work wtih
-binary_search_state.py in order to find the bad package or set of
-packages in a ChromeOS build.
-
-
-QUICKSTART:
-
-After setting up your 3 build trees (see Prerequisites section), do the
-following:
-
- - Decide which test script to use (boot_test.sh or
- interactive_test.sh)
- - Get the IP name or address of the chromebook you will use for testing.
- - Do the following inside your chroot:
-
- $ cd ~/trunk/src/third_party/toolchain_utils/binary_search_tool
- $ ./cros_pkg/setup.sh <board-to-test> <IP-name-or-address-of-chromebook>
-
- If you chose the boot test, then:
-
- $ python ./binary_search_state.py \
- --get_initial_items=cros_pkg/get_initial_items.sh \
- --switch_to_good=cros_pkg/switch_to_good.sh \
- --switch_to_bad=cros_pkg/switch_to_bad.sh \
- --test_setup_script=cros_pkg/test_setup.sh \
- --test_script=cros_pkg/boot_test.sh \
- --file_args \
- --prune
-
- Otherwise, if you chose the interactive test, then:
-
- $ python ./binary_search_state.py \
- --get_initial_items=cros_pkg/get_initial_items.sh \
- --switch_to_good=cros_pkg/switch_to_good.sh \
- --switch_to_bad=cros_pkg/switch_to_bad.sh \
- --test_setup_script=cros_pkg/test_setup.sh \
- --test_script=cros_pkg/interactive_test.sh \
- --file_args \
- --prune
-
- Once you have completely finished doing the binary search/triage,
- run the genereated cleanup script, to restore your chroot to the state
- it was in before you ran the setup.sh script:
-
- $ cros_pkg/${BOARD}_cleanup.sh
-
-
-
-FILES AND SCRIPTS:
-
- boot_test.sh - One of two possible test scripts used to determine
- if the ChromeOS image built from the packages is good
- or bad. This script tests to see if the image
- booted, and requires no user intervention.
-
- create_cleanup_script.py - This is called by setup.sh, to
- generate ${BOARD}_cleanup.sh,
- which is supposed to be run by the user
- after the binary search triage process is
- finished, to undo the changes made by
- setup.sh and return everything
- to its original state.
-
- get_initial_items.sh - This script is used to determine the current
- set of ChromeOS packages.
-
- test_setup.sh - This script will build and flash your image to the
- remote machine. If the flash fails, this script will
- help the user troubleshoot by flashing through usb or
- by retrying the flash over ethernet.
-
- interactive_test.sh - One of two possible scripts used to determine
- if the ChromeOS image built from the packages
- is good or bad. This script requires user
- interaction to determine if the image is
- good or bad.
-
- setup.sh - This is the first script the user should call, after
- taking care of the prerequisites. It sets up the
- environment appropriately for running the ChromeOS
- package binary search triage, and it generates two
- necessary scripts (see below).
-
- switch_to_bad.sh - This script is used to copy packages from the
- 'bad' build tree into the work area.
-
- switch_to_good.sh - This script is used to copy packages from the
- good' build tree into the work area.
-
-
-GENERATED SCRIPTS:
-
- common.sh - contains basic environment variable definitions for
- this binary search triage session.
-
- ${BOARD}_cleanup.sh - script to undo all the changes made by
- running setup.sh, and returning
- everything to its original state. The user
- should manually run this script once the
- binary search triage process is over.
-
-ASSUMPTIONS:
-
-- There are two different ChromeOS builds, for the same board, with the
- same set of ChromeOS packages. One build creates a good working ChromeOS
- image and the other does not.
-
-- You have saved the complete build trees for both the good and bad builds.
-
-
-PREREQUISITES FOR USING THESE SCRIPTS (inside the chroot):
-
-- The "good" build tree, for the board, is in /build/${board}.good
- (e.g. /build/lumpy.good or /build/daisy.good).
-
-- The "bad" build tree is in /build/${board}.bad
- (e.g. /build/lumpy.bad or /build/daisy.bad).
-
-- You made a complete copy of the "bad" build tree , and put it in
- /build/${board}.work (e.g. /build/lumpy.work or /build/daisy.work.
- The easiest way to do this is to use something similar to the
- following set of commands (this example assumes the board is
- 'lumpy'):
-
- $ cd /build
- $ sudo tar -cvf lumpy.bad.tar lumpy.bad
- $ sudo mv lumpy.bad lumpy.work
- $ sudo tar -xvf lumpy.bad.tar
-
-
-USING THESE SCRIPTS FOR BINARY TRIAGE OF PACKAGES:
-
-To use these scripts, you must first run setup.sh, passing it two
-arguments (in order): the board for which you are building the image;
-and the name or ip address of the chromebook you want to use for
-testing your chromeos images. setup.sh will do the following:
-
- - Verify that your build trees are set up correctly (with good, bad
- and work).
- - Create a soft link for /build/${board} pointing to the work build
- tree.
- - Create the common.sh file that the other scripts passed to the
- binary triage tool will need.
- - Create a cleanup script, ${board}_cleanup.sh, for you to
- run after you are done with the binary triages, to undo all of these
- various changes that setup.sh did.
-
-
-This set of scripts comes with two alternate test scripts. One test
-script, boot_test.sh, just checks to make sure that the image
-booted (i.e. responds to ping) and assumes that is enough. The other
-test script, interactive_test.sh, is interactive and asks YOU
-to tell it whether the image on the chromebook is ok or not (it
-prompts you and waits for a response).
-
-
-Once you have run setup.sh (and decided which test script you
-want to use) run the binary triage tool using these scripts to
-isolate/identify the bad package:
-
-~/trunk/src/third_party/toolchain_utils/binary_search_tool/binary_search_state.py \
- --get_initial_items=cros_pkg/get_initial_items.sh \
- --switch_to_good=cros_pkg/switch_to_good.sh \
- --switch_to_bad=cros_pkg/switch_to_bad.sh \
- --test_setup_script=cros_pkg/test_setup.sh \
- --test_script=cros_pkg/boots_test.sh \ # could use interactive_test.sh instead
- --prune
-
-
-After you have finished running the tool and have identified the bad
-package(s), you will want to run the cleanup script that setup.sh
-generated (cros_pkg/${BOARD}_cleanup.sh).
diff --git a/binary_search_tool/cros_pkg/README.cros_pkg_triage.md b/binary_search_tool/cros_pkg/README.cros_pkg_triage.md
new file mode 100644
index 0000000..17121dd
--- /dev/null
+++ b/binary_search_tool/cros_pkg/README.cros_pkg_triage.md
@@ -0,0 +1,193 @@
+# CrOS's binary search tool
+
+`binary_search_state.py` is a general binary search triage tool that
+performs a binary search on a set of things to try to identify which
+thing or thing(s) in the set is 'bad'. `binary_search_state.py` assumes
+that the user has two sets, one where everything is known to be good,
+ane one which contains at least one bad item. `binary_search_state.py`
+then copies items from the good and bad sets into a working set and
+tests the result (good or bad). `binary_search_state.py` requires that
+a set of scripts be supplied to it for any particular job. For more
+information on `binary_search_state.py`, see
+
+https://sites.google.com/a/google.com/chromeos-toolchain-team-home2/home/team-tools-and-scripts/binary-searcher-tool-for-triage
+
+This particular set of scripts is designed to work wtih
+`binary_search_state.py` in order to find the bad package or set of
+packages in a ChromeOS build.
+
+
+## QUICKSTART
+
+After setting up your 3 build trees (see Prerequisites section), do the
+following:
+
+- Decide which test script to use (`boot_test.sh` or
+ `interactive_test.sh`)
+- Get the IP name or address of the chromebook you will use for testing.
+- Do the following inside your chroot:
+
+ ```
+ $ cd ~/trunk/src/third_party/toolchain_utils/binary_search_tool
+ $ ./cros_pkg/setup.sh <board-to-test> <IP-name-or-address-of-chromebook>
+ ```
+
+ If you chose the boot test, then:
+
+ ```
+ $ python ./binary_search_state.py \
+ --get_initial_items=cros_pkg/get_initial_items.sh \
+ --switch_to_good=cros_pkg/switch_to_good.sh \
+ --switch_to_bad=cros_pkg/switch_to_bad.sh \
+ --test_setup_script=cros_pkg/test_setup.sh \
+ --test_script=cros_pkg/boot_test.sh \
+ --file_args \
+ --prune
+ ```
+
+ Otherwise, if you chose the interactive test, then:
+
+ ```
+ $ python ./binary_search_state.py \
+ --get_initial_items=cros_pkg/get_initial_items.sh \
+ --switch_to_good=cros_pkg/switch_to_good.sh \
+ --switch_to_bad=cros_pkg/switch_to_bad.sh \
+ --test_setup_script=cros_pkg/test_setup.sh \
+ --test_script=cros_pkg/interactive_test.sh \
+ --file_args \
+ --prune
+ ```
+
+ Once you have completely finished doing the binary search/triage,
+ run the genereated cleanup script, to restore your chroot to the state
+ it was in before you ran the `setup.sh` script:
+
+ ```
+ $ cros_pkg/${BOARD}_cleanup.sh
+ ```
+
+
+## FILES AND SCRIPTS
+
+`boot_test.sh` - One of two possible test scripts used to determine
+ if the ChromeOS image built from the packages is good
+ or bad. This script tests to see if the image
+ booted, and requires no user intervention.
+
+`create_cleanup_script.py` - This is called by setup.sh, to
+ generate ${BOARD}_cleanup.sh,
+ which is supposed to be run by the user
+ after the binary search triage process is
+ finished, to undo the changes made by
+ setup.sh and return everything
+ to its original state.
+
+`get_initial_items.sh` - This script is used to determine the current
+ set of ChromeOS packages.
+
+`test_setup.sh` - This script will build and flash your image to the
+ remote machine. If the flash fails, this script will
+ help the user troubleshoot by flashing through usb or
+ by retrying the flash over ethernet.
+
+`interactive_test.sh` - One of two possible scripts used to determine
+ if the ChromeOS image built from the packages
+ is good or bad. This script requires user
+ interaction to determine if the image is
+ good or bad.
+
+`setup.sh` - This is the first script the user should call, after
+ taking care of the prerequisites. It sets up the
+ environment appropriately for running the ChromeOS
+ package binary search triage, and it generates two
+ necessary scripts (see below).
+
+`switch_to_bad.sh` - This script is used to copy packages from the
+ 'bad' build tree into the work area.
+
+`switch_to_good.sh` - This script is used to copy packages from the
+ 'good' build tree into the work area.
+
+
+## GENERATED SCRIPTS
+
+`common.sh` - contains basic environment variable definitions for
+ this binary search triage session.
+
+`${BOARD}_cleanup.sh` - script to undo all the changes made by
+ running setup.sh, and returning
+ everything to its original state. The user
+ should manually run this script once the
+ binary search triage process is over.
+
+## ASSUMPTIONS
+
+- There are two different ChromeOS builds, for the same board, with the
+ same set of ChromeOS packages. One build creates a good working ChromeOS
+ image and the other does not.
+
+- You have saved the complete build trees for both the good and bad builds.
+
+
+## PREREQUISITES FOR USING THESE SCRIPTS (inside the chroot)
+
+- The "good" build tree, for the board, is in /build/${board}.good
+ (e.g. /build/lumpy.good or /build/daisy.good).
+
+- The "bad" build tree is in /build/${board}.bad
+ (e.g. /build/lumpy.bad or /build/daisy.bad).
+
+- You made a complete copy of the "bad" build tree , and put it in
+ /build/${board}.work (e.g. /build/lumpy.work or /build/daisy.work.
+ The easiest way to do this is to use something similar to the
+ following set of commands (this example assumes the board is
+ 'lumpy'):
+
+ ```
+ $ cd /build
+ $ sudo tar -cvf lumpy.bad.tar lumpy.bad
+ $ sudo mv lumpy.bad lumpy.work
+ $ sudo tar -xvf lumpy.bad.tar
+ ```
+
+
+## USING THESE SCRIPTS FOR BINARY TRIAGE OF PACKAGES
+
+To use these scripts, you must first run setup.sh, passing it two
+arguments (in order): the board for which you are building the image;
+and the name or ip address of the chromebook you want to use for
+testing your chromeos images. setup.sh will do the following:
+
+- Verify that your build trees are set up correctly (with good, bad and work).
+- Create a soft link for /build/${board} pointing to the work build tree.
+- Create the common.sh file that the other scripts passed to the binary triage
+ tool will need.
+- Create a cleanup script, ${board}_cleanup.sh, for you to run after you are
+ done with the binary triages, to undo all of these various changes that
+ setup.sh did.
+
+This set of scripts comes with two alternate test scripts. One test
+script, `boot_test.sh`, just checks to make sure that the image
+booted (i.e. responds to ping) and assumes that is enough. The other
+test script, `interactive_test.sh`, is interactive and asks YOU
+to tell it whether the image on the chromebook is ok or not (it
+prompts you and waits for a response).
+
+
+Once you have run `setup.sh` (and decided which test script you
+want to use) run the binary triage tool using these scripts to
+isolate/identify the bad package:
+
+```
+~/trunk/src/third_party/toolchain_utils/binary_search_tool/binary_search_state.py \
+ --get_initial_items=cros_pkg/get_initial_items.sh \
+ --switch_to_good=cros_pkg/switch_to_good.sh \
+ --switch_to_bad=cros_pkg/switch_to_bad.sh \
+ --test_setup_script=cros_pkg/test_setup.sh \
+ --test_script=cros_pkg/boots_test.sh \ # could use interactive_test.sh instead
+ --prune
+```
+
+After you have finished running the tool and have identified the bad
+package(s), you will want to run the cleanup script that `setup.sh`
+generated (`cros_pkg/${BOARD}_cleanup.sh`).
diff --git a/binary_search_tool/ndk/README b/binary_search_tool/ndk/README
deleted file mode 100644
index 324d139..0000000
--- a/binary_search_tool/ndk/README
+++ /dev/null
@@ -1,84 +0,0 @@
-
-This is an example bisection for an NDK build system. This example specifically
-bisects the sample NDK Teapot app. All steps (setup and otherwise) for bisection
-can be found in DO_BISECTION.sh. This shell script is meant to show the process
-required to bisect a compiler problem in an arbitrary NDK app build system.
-
-There are three necessary setup steps to run this example:
-
- 1. Install the NDK (known to work with r12b)
- a. See here for NDK: https://developer.android.com/ndk/index.html
- b. Go here for older NDK downloads: https://github.com/android-ndk/ndk/wiki
-
- 2. Install the compiler wrapper provided with this repo. See
- compiler_wrapper.py for more details.
- a. Essentially you must go into the NDK source (or where you build system
- stores its toolchain), rename your compilers to <compiler>.real, and
- create a symlink pointing to compiler_wrapper.py named <compiler>
- (where your compiler used to be).
- b. If you're using the toolchains that come with the NDK they live at:
- <ndk_path>/toolchains/<arch>/prebuilt/<host>/bin
- example:
- <ndk_path>/toolchains/llvm/prebuilt/linux-x86_64/bin/clang
-
- 3. Plug in an Arm7 compatible Android device with usb debugging enabled.
- a. This bisection example was tested with a Nexus 5X
- b. It should be relatively simple to change the example to work with other
- types of devices. Just change the scripts, and change PATCH1 to use a
- different build flavor (like x86). See below for more details.
-
-This example contains two patches:
-
- PATCH1 - This is the necessary changes to the build system to make the
- bisection easier. More specifically, it adds an arm7 build flavor to gradle.
- By default, this project will build objects for all possible architectures and
- package them into one big apk. These object files meant for another
- architecture just sit there and don't actually execute. By adding a build
- flavor for arm7, our compiler wrapper won't try to bisect object files meant
- for another device.
-
- PATCH2 - This patch is what inserts the "compiler error". This is a simple
- nullptr error in one of the source files, but it is meant to mimic bad code
- generation. The result of the error is the app simply crashes immediately
- after starting.
-
-Using another device architecture:
-
- If we want to bisect for an x86-64 device we first need to provide a arch
- specific build flavor in our app/build.gradle file:
-
- create("x86-64") {
- ndk.abiFilters.add("x86_64")
- }
-
- We want to add this under the same "productFlavors" section that our arm7
- build flavor is in (see PATCH1). Now we should have the "installx86-64Debug"
- task in our build system. We can use this to build and install an x86-64
- version of our app.
-
- Now we want to change our test_setup.sh script to run our new gradle task:
- ./gradlew installx86-64Debug
-
- Keep in mind, these specific build flavors are not required. If your build
- system makes these device specific builds difficult to implement, the
- bisection tool will function perfectly fine without them. However, the
- downside of not having targetting a single architecture is the bisection will
- take longer (as it will need to search across more object files).
-
-Additional Documentation:
- These are internal Google documents, if you are a developer external to
- Google please ask whoever gave you this sample for access or copies to the
- documentation. If you cannot gain access, the various READMEs paired with the
- bisector should help you.
-
- * Ahmad's original presentation:
- https://goto.google.com/zxdfyi
-
- * Bisection tool update design doc:
- https://goto.google.com/zcwei
-
- * Bisection tool webpage:
- https://goto.google.com/ruwpyi
-
- * Compiler wrapper webpage:
- https://goto.google.com/xossn
diff --git a/binary_search_tool/ndk/README.md b/binary_search_tool/ndk/README.md
new file mode 100644
index 0000000..e41311a
--- /dev/null
+++ b/binary_search_tool/ndk/README.md
@@ -0,0 +1,89 @@
+# NDK Bisection tool
+
+This is an example bisection for an NDK build system. This example specifically
+bisects the sample NDK Teapot app. All steps (setup and otherwise) for bisection
+can be found in `DO_BISECTION.sh`. This shell script is meant to show the
+process required to bisect a compiler problem in an arbitrary NDK app build
+system.
+
+There are three necessary setup steps to run this example:
+
+1. Install the NDK (known to work with r12b)
+
+ 1. See here for NDK: https://developer.android.com/ndk/index.html
+ 2. Go here for older NDK downloads: https://github.com/android-ndk/ndk/wiki
+
+1. Install the compiler wrapper provided with this repo. See
+ compiler_wrapper.py for more details.
+
+ 1. Essentially you must go into the NDK source (or where you build system
+ stores its toolchain), rename your compilers to <compiler>.real, and
+ create a symlink pointing to compiler_wrapper.py named <compiler>
+ (where your compiler used to be).
+
+ 2. If you're using the toolchains that come with the NDK they live at:
+ `<ndk_path>/toolchains/<arch>/prebuilt/<host>/bin`
+ example:
+ `<ndk_path>/toolchains/llvm/prebuilt/linux-x86_64/bin/clang`
+
+1. Plug in an Arm7 compatible Android device with usb debugging enabled.
+
+ 1. This bisection example was tested with a Nexus 5X
+
+ 2. It should be relatively simple to change the example to work with other
+ types of devices. Just change the scripts, and change PATCH1 to use a
+ different build flavor (like x86). See below for more details.
+
+This example contains two patches:
+
+`PATCH1` - This is the necessary changes to the build system to make the
+bisection easier. More specifically, it adds an arm7 build flavor to gradle.
+By default, this project will build objects for all possible architectures and
+package them into one big apk. These object files meant for another
+architecture just sit there and don't actually execute. By adding a build
+flavor for arm7, our compiler wrapper won't try to bisect object files meant
+for another device.
+
+`PATCH2` - This patch is what inserts the "compiler error". This is a simple
+nullptr error in one of the source files, but it is meant to mimic bad code
+generation. The result of the error is the app simply crashes immediately
+after starting.
+
+## Using another device architecture
+
+If we want to bisect for an x86-64 device we first need to provide a arch
+specific build flavor in our app/build.gradle file:
+
+```
+create("x86-64") {
+ ndk.abiFilters.add("x86_64")
+}
+```
+
+We want to add this under the same "productFlavors" section that our arm7
+build flavor is in (see PATCH1). Now we should have the "installx86-64Debug"
+task in our build system. We can use this to build and install an x86-64
+version of our app.
+
+Now we want to change our `test_setup.sh` script to run our new gradle task:
+```
+./gradlew installx86-64Debug
+```
+
+Keep in mind, these specific build flavors are not required. If your build
+system makes these device specific builds difficult to implement, the
+bisection tool will function perfectly fine without them. However, the
+downside of not having targetting a single architecture is the bisection will
+take longer (as it will need to search across more object files).
+
+## Additional Documentation
+
+These are internal Google documents, if you are a developer external to
+Google please ask whoever gave you this sample for access or copies to the
+documentation. If you cannot gain access, the various READMEs paired with the
+bisector should help you.
+
+* Ahmad's original presentation: https://goto.google.com/zxdfyi
+* Bisection tool update design doc: https://goto.google.com/zcwei
+* Bisection tool webpage: https://goto.google.com/ruwpyi
+* Compiler wrapper webpage: https://goto.google.com/xossn
diff --git a/binary_search_tool/sysroot_wrapper/README b/binary_search_tool/sysroot_wrapper/README
deleted file mode 100644
index 599d700..0000000
--- a/binary_search_tool/sysroot_wrapper/README
+++ /dev/null
@@ -1,28 +0,0 @@
-This is a set of scripts to use when triaging compiler problem by using
-the bisecting functionality included in the sysroot_wrapper.hardened.
-The only script that you need to create for your triaging problem is the
-test_script.sh (The ones in this directory are here only as an example).
-
-Before running the binary searcher tool you will need to run the setup script:
-
-./sysroot_wrapper/setup.sh ${board} ${remote_ip} ${package}
-
-This setup script will ensure your $BISECT_DIR is properly populated and
-generate a common variable script for the convenience of the scripts in
-./sysroot_wrapper
-
-To run the binary searcher tool with these scripts, execute it like this:
-
-./binary_search_state.py --get_initial_items=./sysroot_wrapper/get_initial_items.sh --switch_to_good=./sysroot_wrapper/switch_to_good.sh --switch_to_bad=./sysroot_wrapper/switch_to_bad.sh --test_script=./sysroot_wrapper/test_script.sh --noincremental --file_args 2>&1 | tee /tmp/binary_search.log
-
-Finally once done you will want to run the cleanup script:
-
-./sysroot_wrapper/cleanup.sh
-
-For more information on how to use the sysroot_wrapper to do object file
-triaging see:
-
-https://sites.google.com/a/google.com/chromeos-toolchain-team-home2/home/team-tools-and-scripts/bisecting-compiler-problems
-
-
-
diff --git a/binary_search_tool/sysroot_wrapper/README.md b/binary_search_tool/sysroot_wrapper/README.md
new file mode 100644
index 0000000..89904a0
--- /dev/null
+++ b/binary_search_tool/sysroot_wrapper/README.md
@@ -0,0 +1,35 @@
+# Sysroot wrapper
+
+This is a set of scripts to use when triaging compiler problem by using
+the bisecting functionality included in the `sysroot_wrapper.hardened`.
+The only script that you need to create for your triaging problem is the
+`test_script.sh` (The ones in this directory are here only as an example).
+
+Before running the binary searcher tool you will need to run the setup script:
+
+```
+./sysroot_wrapper/setup.sh ${board} ${remote_ip} ${package}
+```
+
+This setup script will ensure your `$BISECT_DIR` is properly populated and
+generate a common variable script for the convenience of the scripts in
+`./sysroot_wrapper`
+
+To run the binary searcher tool with these scripts, execute it like this:
+
+```
+./binary_search_state.py \
+ --get_initial_items=./sysroot_wrapper/get_initial_items.sh \
+ --switch_to_good=./sysroot_wrapper/switch_to_good.sh \
+ --switch_to_bad=./sysroot_wrapper/switch_to_bad.sh \
+ --test_script=./sysroot_wrapper/test_script.sh \
+ --noincremental \
+ --file_args \
+ 2>&1 | tee /tmp/binary_search.log
+```
+
+Finally once done you will want to run the cleanup script:
+`./sysroot_wrapper/cleanup.sh`
+
+For more information on how to use the `sysroot_wrapper` to do object file
+triaging see: https://sites.google.com/a/google.com/chromeos-toolchain-team-home2/home/team-tools-and-scripts/bisecting-compiler-problems
diff --git a/crosperf/experiment_files/README b/crosperf/experiment_files/README.md
similarity index 81%
rename from crosperf/experiment_files/README
rename to crosperf/experiment_files/README.md
index d9c9687..8c1fe20 100644
--- a/crosperf/experiment_files/README
+++ b/crosperf/experiment_files/README.md
@@ -1,16 +1,20 @@
+# Experiment files
+
To use these experiment files, replace the board, remote and images
placeholders and run crosperf on them.
Further information about crosperf:
https://sites.google.com/a/google.com/chromeos-toolchain-team-home2/home/team-tools-and-scripts/crosperf-cros-image-performance-comparison-tool
-The final experiment file should look something like the following (but with
+The final experiment file should look something like the following (but with
different actual values for the fields):
+```
board: lumpy
remote: 123.45.67.089
# Add images you want to test:
+
my_image {
chromeos_image: /usr/local/chromeos/src/build/images/lumpy/chromiumos_test_image.bin
}
@@ -21,14 +25,15 @@
}
# Paste experiment benchmarks here. Example, I pasted
-# page_cycler_v2.morejs here.
+# `page_cycler_v2.morejs` here.
-# This experiment just runs a short autotest which measures the performance of
-# Telemetry's page_cycler_v2.morejs. In addition, it profiles
+# This experiment just runs a short autotest which measures the performance
+# of Telemetry's `page_cycler_v2.morejs`. In addition, it profiles cycles.
-perg_args: record -e cycles
+perf_args: record -e cycles
benchmark: page_cycler_v2.morejs {
suite: telemetry_Crosperf
iterations: 1
}
+```
diff --git a/mem_tests/README b/mem_tests/README
deleted file mode 100644
index 4e35f68..0000000
--- a/mem_tests/README
+++ /dev/null
@@ -1,46 +0,0 @@
-Usage
------
-
-These scripts are made to parse TCMalloc output in order to extract certain
-info from them.
-
-In particular, these scripts rely on the error logging system for ChromeOS in
-order to extract information. In order to use a script (e.g. total_mem.py), you
-just have the command:
-
-./total_mem.py FILENAME
-
-where FILENAME is the name of the log file to be parsed.
-
-Codebase Changes
-----------------
-
-There are two ideas that motivate these changes:
-
-1- Turn on TCMalloc sampling.
-2- Use perf to collect the sample information.
-
-The following files have to be changed:
-
-in chrome/browser/metrics/perf_provider_chrome_os:
-
-add:
- #include "third_party/tcmalloc/chromium/src/gperftools/malloc_extension.h"
-
-Change the perf profiling interval to something small (60*1000 milliseconds).
-
-inside DoPeriodicCollection, insert the following code:
-
- std::string output;
- char* chr_arr = new char[9999];
- MallocExtension::instance() ->GetHeapSample(&output);
- MallocExtension::instance() ->GetStats(chr_arr, 9999);
- LOG(ERROR) << "Output Heap Data: ";
- LOG(ERROR) << output;
- LOG(ERROR) << "Output Heap Stats: ";
- output = "";
- for (unsigned int i = 0; i < strlen(chr_arr); i++) {
- output += chr_arr[i];
- }
- LOG(ERROR) << output;
- delete[] chr_arr;
diff --git a/mem_tests/README.md b/mem_tests/README.md
new file mode 100644
index 0000000..44bf16c
--- /dev/null
+++ b/mem_tests/README.md
@@ -0,0 +1,52 @@
+# Memory tests
+
+## Usage
+
+These scripts are made to parse TCMalloc output in order to extract certain
+info from them.
+
+In particular, these scripts rely on the error logging system for ChromeOS in
+order to extract information. In order to use a script (e.g. `total_mem.py`),
+you just have the command:
+
+```
+./total_mem.py FILENAME
+```
+
+where `FILENAME` is the name of the log file to be parsed.
+
+## Codebase Changes
+
+There are two ideas that motivate these changes:
+
+1. Turn on TCMalloc sampling.
+2. Use perf to collect the sample information.
+
+
+The following files have to be changed:
+
+in `chrome/browser/metrics/perf_provider_chrome_os`, add:
+
+```
+#include "third_party/tcmalloc/chromium/src/gperftools/malloc_extension.h"
+```
+
+Change the perf profiling interval to something small (60*1000 milliseconds).
+
+Inside DoPeriodicCollection, insert the following code:
+
+```
+std::string output;
+char* chr_arr = new char[9999];
+MallocExtension::instance() ->GetHeapSample(&output);
+MallocExtension::instance() ->GetStats(chr_arr, 9999);
+LOG(ERROR) << "Output Heap Data: ";
+LOG(ERROR) << output;
+LOG(ERROR) << "Output Heap Stats: ";
+output = "";
+for (unsigned int i = 0; i < strlen(chr_arr); i++) {
+ output += chr_arr[i];
+}
+LOG(ERROR) << output;
+delete[] chr_arr;
+```
