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      */
overrideDeviceOptions(ITestDevice device)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      */
setFlashingResourcesRetriever(IFlashingResourcesRetriever retriever)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      */
setUserDataFlashOption(UserDataFlashOption flashOption)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      */
setDataWipeSkipList(Collection<String> dataWipeSkipList)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      */
getUserDataFlashOption()86     public UserDataFlashOption getUserDataFlashOption();
87 
88     /**
89      * Set the timeout for wiping the data.
90      */
setWipeTimeout(long timeout)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      */
setForceSystemFlash(boolean forceSystemFlash)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      */
flash(ITestDevice device, IDeviceBuildInfo deviceBuild)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      */
getSystemFlashingStatus()120     public CommandStatus getSystemFlashingStatus();
121 
122     /**
123      * Sets if an additional ramdisk should be flashed after updating device via image zip
124      *
125      * @param shouldFlashRamdisk
126      */
setShouldFlashRamdisk(boolean shouldFlashRamdisk)127     public default void setShouldFlashRamdisk(boolean shouldFlashRamdisk) {
128         // Ignore
129     }
130 
131     /**
132      * Checks if the flasher is set to have an additional ramdisk should be flashed after updating
133      * device via image zip
134      */
shouldFlashRamdisk()135     public default boolean shouldFlashRamdisk() {
136         return false;
137     }
138 }
139