1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
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).
|
