README.cros_pkg_triage revision c4d58d04b0f92b52c645f0b8a0fc1d5e5b983e5f 
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 (cros_pkg_boot_test.sh or
25   cros_pkg_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/cros_pkg
30   $ ./cros_pkg_setup.sh <board-to-test> \
31                         <IP-name-or-address-of-chromebook>
32
33   If you chose the boot test, then:
34
35   $ python ../binary_search_state.py \
36       --get_initial_items=cros_pkg_get_initial_items.sh \
37       --switch_to_good=cros_pkg_switch_to_good.sh \
38       --switch_to_bad=cros_pkg_switch_to_bad.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_script=cros_pkg_interactive_test.sh \
50       --file_args \
51       --prune
52
53   Once you have completely finished doing the binary search/triage,
54   run the genereated cleanup script, to restore your chroot to the state
55   it was in before you ran the cros_pkg_setup.sh script:
56
57   $ ./cros_pkg_${BOARD}_cleanup.sh
58
59
60
61FILES AND SCRIPTS:
62
63  cros_pkg_boot_test.sh - One of two possible test scripts used to determine
64                          if the ChromeOS image built from the packages is good
65                          or bad.  This script tests to see if the image
66                          booted, and requires no user intervention.
67
68  cros_pkg_create_cleanup_script.py - This is called by cros_pkg_setup.sh, to
69                                      generate cros_pkg_${BOARD}_cleanup.sh,
70                                      which is supposed to be run by the user
71                                      after the binary search triage process is
72                                      finished, to undo the changes made by
73                                      cros_pkg_setup.sh and return everything
74                                      to its original state.
75
76  cros_pkg_get_initial_items.sh - This script is used to determine the current
77                                  set of ChromeOS packages.
78
79  cros_pkg_interactive_test.sh - One of two possible scripts used to determine
80                                 if the ChromeOS image built from the packages
81                                 is good or bad.  This script requires user
82                                 interaction to determine if the image is
83                                 good or bad.
84
85  cros_pkg_setup.sh - This is the first script the user should call, after
86                      taking care of the prerequisites.  It sets up the
87                      environment appropriately for running the ChromeOS
88                      package binary search triage, and it generates two
89                      necessary scripts (see below).
90
91  cros_pkg_switch_to_bad.sh - This script is used to copy packages from the
92                              'bad' build tree into the work area.
93
94  cros_pkg_switch_to_good.sh - This script is used to copy packages from the
95                               'good' build tree into the work area.
96
97
98GENERATED SCRIPTS:
99
100  cros_pkg_common.sh  - contains basic environment variable definitions for
101                        this binary search triage session.
102
103  cros_pkg_${BOARD}_cleanup.sh - script to undo all the changes made by
104                                 running cros_pkg_setup.sh, and returning
105                                 everything to its original state. The user
106                                 should manually run this script once the
107                                 binary search triage process is over.
108
109ASSUMPTIONS:
110
111- There are two different ChromeOS builds, for the same board, with the
112  same set of ChromeOS packages.  One build creates a good working ChromeOS
113  image and the other does not.
114
115- You have saved the complete build trees for both the good and bad builds.
116
117
118PREREQUISITES FOR USING THESE SCRIPTS (inside the chroot):
119
120- The "good" build tree, for the board, is in /build/${board}.good
121  (e.g. /build/lumpy.good or /build/daisy.good).
122
123- The "bad" build tree is in /build/${board}.bad
124  (e.g. /build/lumpy.bad or /build/daisy.bad).
125
126- You made a complete copy of the "bad" build tree , and put it in
127  /build/${board}.work (e.g. /build/lumpy.work or /build/daisy.work.
128  The easiest way to do this is to use something similar to the
129  following set of commands (this example assumes the board is
130  'lumpy'):
131
132   $ cd /build
133   $ sudo tar -cvf lumpy.bad.tar lumpy.bad
134   $ sudo mv lumpy.bad lumpy.work
135   $ sudo tar -xvf lumpy.bad.tar
136
137
138USING THESE SCRIPTS FOR BINARY TRIAGE OF PACKAGES:
139
140To use these scripts, you must first run cros_pkg_setup.sh, passing it two
141arguments (in order): the board for which you are building the image;
142and the name or ip address of the chromebook you want to use for
143testing your chromeos images.  cros_pkg_setup.sh will do the following:
144
145   - Verify that your build trees are set up correctly (with good, bad
146     and work).
147   - Create a soft link for /build/${board} pointing to the work build
148     tree.
149   - Create the cros_pkg_common.sh file that the other scripts passed to the
150     binary triage tool will need.
151   - Create a cleanup script, cros_pkg_${board}_cleanup.sh, for you to
152     run after you are done with the binary triages, to undo all of these
153     various changes that cros_pkg_setup.sh did.
154
155
156This set of scripts comes with two alternate test scripts.  Both test
157scripts build the image and push it onto the Chromebook.  One test
158script, cros_pkg_boot_test.sh, just checks to make sure that the image
159booted (i.e. responds to ping) and assumes that is enough.  The other
160test script, cros_pkg_interactive_test.sh, is interactive and asks YOU
161to tell it whether the image on the chromebook is ok or not (it
162prompts you and waits for a response).
163
164
165Once you have run cros_pkg_setup.sh (and decided which test script you
166want to use) run the binary triage tool using these scripts to
167isolate/identify the bad package:
168
169~/trunk/src/third_party/toolchain_utils/binary_search_tool/binary_search_state.py \
170 --get_initial_items=cros_pkg_get_initial_items.sh \
171 --switch_to_good=cros_pkg_switch_to_good.sh \
172 --switch_to_bad=cros_pkg_switch_to_bad.sh \
173 --test_script=cros_pkg_boots_test.sh \  # could use cros_pkg_interactive_test.sh instead
174 --prune
175
176
177After you have finished running the tool and have identified the bad
178package(s), you will want to run the cleanup script that cros_pkg_setup.sh
179generated (cros_pkg_${BOARD}_cleanup.sh).
180