v811_spc009/external/toolchain-utils/binary_search_tool/cros_pkg

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).