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