Home | History | Annotate | Download | only in targetprep 
      1 /*
      2  * Copyright (C) 2010 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 package com.android.tradefed.targetprep;
     18 
     19 import com.android.tradefed.build.IDeviceBuildInfo;
     20 import com.android.tradefed.device.DeviceNotAvailableException;
     21 import com.android.tradefed.device.ITestDevice;
     22 import com.android.tradefed.util.CommandStatus;
     23 
     24 import java.util.Collection;
     25 
     26 /**
     27  * Flashes a device image on a device.
     28  */
     29 public interface IDeviceFlasher {
     30 
     31     /**
     32      * Enum of options for handling the userdata image
     33      */
     34     public enum UserDataFlashOption {
     35         /** flash the given userdata image on device */
     36         FLASH,
     37         /** flash the userdata image included in device image zip */
     38         FLASH_IMG_ZIP,
     39         /** wipe the device's userdata partition using fastboot erase, if supported by device */
     40         WIPE,
     41         /** wipe the device's userdata partition using fastboot erase, even if it's unadvised */
     42         FORCE_WIPE,
     43         /** delete content from the device's /data partition using adb shell rm */
     44         WIPE_RM,
     45         /** push the contents of the tests zip file onto the device's userdata partition */
     46         TESTS_ZIP,
     47         /** leave the userdata partition as is */
     48         RETAIN;
     49     }
     50 
     51     /**
     52      * Override options for a device. Used to override default option values if the defaults are not
     53      * supported by a particular device.
     54      *
     55      * @param device
     56      */
     57     public void overrideDeviceOptions(ITestDevice device);
     58 
     59     /**
     60      * Sets the mechanism by which the flasher can retrieve resource files for flashing.
     61      *
     62      * @param retriever the {@link IFlashingResourcesRetriever} to use
     63      */
     64     public void setFlashingResourcesRetriever(IFlashingResourcesRetriever retriever);
     65 
     66     /**
     67      * Toggles whether the user data image should be flashed, wiped, or retained
     68      *
     69      * @param flashOption
     70      */
     71     public void setUserDataFlashOption(UserDataFlashOption flashOption);
     72 
     73     /**
     74      * Sets the list of paths under {@code /data} to avoid clearing when using
     75      * {@link ITestsZipInstaller}
     76      * <p />
     77      * Note that the granularity of the skip list is direct children of {@code /data}.
     78      */
     79     public void setDataWipeSkipList(Collection<String> dataWipeSkipList);
     80 
     81     /**
     82      * Gets whether the user data image should be flashed, wiped, or retained
     83      *
     84      * @return Whether the user data image should be flashed, wiped, or retained
     85      */
     86     public UserDataFlashOption getUserDataFlashOption();
     87 
     88     /**
     89      * Set the timeout for wiping the data.
     90      */
     91     public void setWipeTimeout(long timeout);
     92 
     93     /**
     94      * Sets if system should always be flashed even if running current build
     95      * @param forceSystemFlash
     96      */
     97     public void setForceSystemFlash(boolean forceSystemFlash);
     98 
     99     /**
    100      * Flashes build on device.
    101      * <p/>
    102      * Returns immediately after flashing is complete. Callers should wait for device to be
    103      * online and available before proceeding with testing.
    104      *
    105      * @param device the {@link ITestDevice} to flash
    106      * @param deviceBuild the {@link IDeviceBuildInfo} to flash
    107      *
    108      * @throws TargetSetupError if failed to flash build
    109      * @throws DeviceNotAvailableException if device becomes unresponsive
    110      */
    111     public void flash(ITestDevice device, IDeviceBuildInfo deviceBuild) throws TargetSetupError,
    112             DeviceNotAvailableException;
    113 
    114     /**
    115      * Retrieve the command execution status for flashing primary system partitions.
    116      * <p>
    117      * Note that if system partitions are not flashed (system already has the build to be flashed)
    118      * the command status may be <code>null</code>
    119      */
    120     public CommandStatus getSystemFlashingStatus();
    121 
    122 }
    123