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 
     23 import java.util.Collection;
     24 
     25 /**
     26  * Flashes a device image on a device.
     27  */
     28 public interface IDeviceFlasher {
     29 
     30     /**
     31      * Enum of options for handling the userdata image
     32      */
     33     public enum UserDataFlashOption {
     34         /** flash the given userdata image on device */
     35         FLASH,
     36         /** flash the userdata image included in device image zip */
     37         FLASH_IMG_ZIP,
     38         /** wipe the device's userdata partition using fastboot erase, if supported by device */
     39         WIPE,
     40         /** wipe the device's userdata partition using fastboot erase, even if it's unadvised */
     41         FORCE_WIPE,
     42         /** delete content from the device's /data partition using adb shell rm */
     43         WIPE_RM,
     44         /** push the contents of the tests zip file onto the device's userdata partition */
     45         TESTS_ZIP,
     46         /** leave the userdata partition as is */
     47         RETAIN;
     48     }
     49 
     50     /**
     51      * Override options for a device. Used to override default option values if the defaults are not
     52      * supported by a particular device.
     53      *
     54      * @param device
     55      */
     56     public void overrideDeviceOptions(ITestDevice device);
     57 
     58     /**
     59      * Sets the mechanism by which the flasher can retrieve resource files for flashing.
     60      *
     61      * @param retriever the {@link IFlashingResourcesRetriever} to use
     62      */
     63     public void setFlashingResourcesRetriever(IFlashingResourcesRetriever retriever);
     64 
     65     /**
     66      * Toggles whether the user data image should be flashed, wiped, or retained
     67      *
     68      * @param flashOption
     69      */
     70     public void setUserDataFlashOption(UserDataFlashOption flashOption);
     71 
     72     /**
     73      * Sets the list of paths under {@code /data} to avoid clearing when using
     74      * {@link ITestsZipInstaller}
     75      * <p />
     76      * Note that the granularity of the skip list is direct children of {@code /data}.
     77      */
     78     public void setDataWipeSkipList(Collection<String> dataWipeSkipList);
     79 
     80     /**
     81      * Gets whether the user data image should be flashed, wiped, or retained
     82      *
     83      * @return Whether the user data image should be flashed, wiped, or retained
     84      */
     85     public UserDataFlashOption getUserDataFlashOption();
     86 
     87     /**
     88      * Set the timeout for wiping the data.
     89      */
     90     public void setWipeTimeout(long timeout);
     91 
     92     /**
     93      * Sets if system should always be flashed even if running current build
     94      * @param forceSystemFlash
     95      */
     96     public void setForceSystemFlash(boolean forceSystemFlash);
     97 
     98     /**
     99      * Flashes build on device.
    100      * <p/>
    101      * Returns immediately after flashing is complete. Callers should wait for device to be
    102      * online and available before proceeding with testing.
    103      *
    104      * @param device the {@link ITestDevice} to flash
    105      * @param deviceBuild the {@link IDeviceBuildInfo} to flash
    106      *
    107      * @throws TargetSetupError if failed to flash build
    108      * @throws DeviceNotAvailableException if device becomes unresponsive
    109      */
    110     public void flash(ITestDevice device, IDeviceBuildInfo deviceBuild) throws TargetSetupError,
    111             DeviceNotAvailableException;
    112 
    113 }
    114