README.cros_pkg_triage.md
1# CrOS's binary search tool
2
3`binary_search_state.py` is a general binary search triage tool that
4performs a binary search on a set of things to try to identify which
5thing or thing(s) in the set is 'bad'. `binary_search_state.py` assumes
6that the user has two sets, one where everything is known to be good,
7ane one which contains at least one bad item. `binary_search_state.py`
8then copies items from the good and bad sets into a working set and
9tests the result (good or bad). `binary_search_state.py` requires that
10a set of scripts be supplied to it for any particular job. For more
11information on `binary_search_state.py`, see
12
13https://sites.google.com/a/google.com/chromeos-toolchain-team-home2/home/team-tools-and-scripts/binary-searcher-tool-for-triage
14
15This particular set of scripts is designed to work wtih
16`binary_search_state.py` in order to find the bad package or set of
17packages in a ChromeOS build.
18
19
20## QUICKSTART
21
22After setting up your 3 build trees (see Prerequisites section), do the
23following:
24
25- Decide which test script to use (`boot_test.sh` or
26 `interactive_test.sh`)
27- Get the IP name or address of the chromebook you will use for testing.
28- Do the following inside your chroot:
29
30 ```
31 $ cd ~/trunk/src/third_party/toolchain_utils/binary_search_tool
32 $ ./cros_pkg/setup.sh <board-to-test> <IP-name-or-address-of-chromebook>
33 ```
34
35 If you chose the boot test, then:
36
37 ```
38 $ python ./binary_search_state.py \
39 --get_initial_items=cros_pkg/get_initial_items.sh \
40 --switch_to_good=cros_pkg/switch_to_good.sh \
41 --switch_to_bad=cros_pkg/switch_to_bad.sh \
42 --test_setup_script=cros_pkg/test_setup.sh \
43 --test_script=cros_pkg/boot_test.sh \
44 --file_args \
45 --prune
46 ```
47
48 Otherwise, if you chose the interactive test, then:
49
50 ```
51 $ python ./binary_search_state.py \
52 --get_initial_items=cros_pkg/get_initial_items.sh \
53 --switch_to_good=cros_pkg/switch_to_good.sh \
54 --switch_to_bad=cros_pkg/switch_to_bad.sh \
55 --test_setup_script=cros_pkg/test_setup.sh \
56 --test_script=cros_pkg/interactive_test.sh \
57 --file_args \
58 --prune
59 ```
60
61 Once you have completely finished doing the binary search/triage,
62 run the genereated cleanup script, to restore your chroot to the state
63 it was in before you ran the `setup.sh` script:
64
65 ```
66 $ cros_pkg/${BOARD}_cleanup.sh
67 ```
68
69
70## FILES AND SCRIPTS
71
72`boot_test.sh` - One of two possible test scripts used to determine
73 if the ChromeOS image built from the packages is good
74 or bad. This script tests to see if the image
75 booted, and requires no user intervention.
76
77`create_cleanup_script.py` - This is called by setup.sh, to
78 generate ${BOARD}_cleanup.sh,
79 which is supposed to be run by the user
80 after the binary search triage process is
81 finished, to undo the changes made by
82 setup.sh and return everything
83 to its original state.
84
85`get_initial_items.sh` - This script is used to determine the current
86 set of ChromeOS packages.
87
88`test_setup.sh` - This script will build and flash your image to the
89 remote machine. If the flash fails, this script will
90 help the user troubleshoot by flashing through usb or
91 by retrying the flash over ethernet.
92
93`interactive_test.sh` - One of two possible scripts used to determine
94 if the ChromeOS image built from the packages
95 is good or bad. This script requires user
96 interaction to determine if the image is
97 good or bad.
98
99`setup.sh` - This is the first script the user should call, after
100 taking care of the prerequisites. It sets up the
101 environment appropriately for running the ChromeOS
102 package binary search triage, and it generates two
103 necessary scripts (see below).
104
105`switch_to_bad.sh` - This script is used to copy packages from the
106 'bad' build tree into the work area.
107
108`switch_to_good.sh` - This script is used to copy packages from the
109 'good' build tree into the work area.
110
111
112## GENERATED SCRIPTS
113
114`common.sh` - contains basic environment variable definitions for
115 this binary search triage session.
116
117`${BOARD}_cleanup.sh` - script to undo all the changes made by
118 running setup.sh, and returning
119 everything to its original state. The user
120 should manually run this script once the
121 binary search triage process is over.
122
123## ASSUMPTIONS
124
125- There are two different ChromeOS builds, for the same board, with the
126 same set of ChromeOS packages. One build creates a good working ChromeOS
127 image and the other does not.
128
129- You have saved the complete build trees for both the good and bad builds.
130
131
132## PREREQUISITES FOR USING THESE SCRIPTS (inside the chroot)
133
134- The "good" build tree, for the board, is in /build/${board}.good
135 (e.g. /build/lumpy.good or /build/daisy.good).
136
137- The "bad" build tree is in /build/${board}.bad
138 (e.g. /build/lumpy.bad or /build/daisy.bad).
139
140- You made a complete copy of the "bad" build tree , and put it in
141 /build/${board}.work (e.g. /build/lumpy.work or /build/daisy.work.
142 The easiest way to do this is to use something similar to the
143 following set of commands (this example assumes the board is
144 'lumpy'):
145
146 ```
147 $ cd /build
148 $ sudo tar -cvf lumpy.bad.tar lumpy.bad
149 $ sudo mv lumpy.bad lumpy.work
150 $ sudo tar -xvf lumpy.bad.tar
151 ```
152
153
154## USING THESE SCRIPTS FOR BINARY TRIAGE OF PACKAGES
155
156To use these scripts, you must first run setup.sh, passing it two
157arguments (in order): the board for which you are building the image;
158and the name or ip address of the chromebook you want to use for
159testing your chromeos images. setup.sh will do the following:
160
161- Verify that your build trees are set up correctly (with good, bad and work).
162- Create a soft link for /build/${board} pointing to the work build tree.
163- Create the common.sh file that the other scripts passed to the binary triage
164 tool will need.
165- Create a cleanup script, ${board}_cleanup.sh, for you to run after you are
166 done with the binary triages, to undo all of these various changes that
167 setup.sh did.
168
169This set of scripts comes with two alternate test scripts. One test
170script, `boot_test.sh`, just checks to make sure that the image
171booted (i.e. responds to ping) and assumes that is enough. The other
172test script, `interactive_test.sh`, is interactive and asks YOU
173to tell it whether the image on the chromebook is ok or not (it
174prompts you and waits for a response).
175
176
177Once you have run `setup.sh` (and decided which test script you
178want to use) run the binary triage tool using these scripts to
179isolate/identify the bad package:
180
181```
182~/trunk/src/third_party/toolchain_utils/binary_search_tool/binary_search_state.py \
183 --get_initial_items=cros_pkg/get_initial_items.sh \
184 --switch_to_good=cros_pkg/switch_to_good.sh \
185 --switch_to_bad=cros_pkg/switch_to_bad.sh \
186 --test_setup_script=cros_pkg/test_setup.sh \
187 --test_script=cros_pkg/boots_test.sh \ # could use interactive_test.sh instead
188 --prune
189```
190
191After you have finished running the tool and have identified the bad
192package(s), you will want to run the cleanup script that `setup.sh`
193generated (`cros_pkg/${BOARD}_cleanup.sh`).
194