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.device; 18 19 import com.android.ddmlib.AndroidDebugBridge; 20 import com.android.tradefed.command.remote.DeviceDescriptor; 21 import com.android.tradefed.util.IRunUtil; 22 23 import java.io.PrintWriter; 24 import java.util.List; 25 26 /** 27 * Interface for managing the set of available devices for testing. 28 */ 29 public interface IDeviceManager { 30 /** 31 * A listener for fastboot state changes. 32 */ 33 public static interface IFastbootListener { 34 /** 35 * Callback when fastboot state has been updated for all devices. 36 */ 37 public void stateUpdated(); 38 } 39 40 /** 41 * Initialize the device manager. This must be called once and only once before any other 42 * methods are called. 43 */ 44 public void init(); 45 46 /** 47 * Initialize the device manager with a device filter. This filter can be used to instruct 48 * the DeviceManager to ignore certain connected devices. 49 * 50 * @param globalDeviceFilter the device filter 51 */ 52 public void init(IDeviceSelection globalDeviceFilter, List<IDeviceMonitor> deviceMonitors); 53 54 /** 55 * Request a physical device for testing 56 * 57 * @return a {@link ITestDevice} for testing, or <code>null</code> if one is not available 58 */ 59 public ITestDevice allocateDevice(); 60 61 /** 62 * Request a device for testing that meets certain criteria. 63 * 64 * @param options the {@link IDeviceSelection} the device should meet. 65 * @return a {@link ITestDevice} for testing, or <code>null</code> if one 66 * is not available 67 */ 68 public ITestDevice allocateDevice(IDeviceSelection options); 69 70 /** 71 * Rudely allocate a device, even if its not currently available. 72 * <p/> 73 * Will have no effect if device is already allocated. 74 * 75 * @param serial the device serial to allocate 76 * @return the {@link ITestDevice}, or <code>null</code> if it could not be allocated 77 */ 78 public ITestDevice forceAllocateDevice(String serial); 79 80 /** 81 * Return a device to the pool 82 * <p/> 83 * Attempts to return a device that hasn't been previously allocated will be ignored. 84 * 85 * @param device the {@link ITestDevice} to free 86 * @param state the {@link com.android.tradefed.device.FreeDeviceState}. Used to control if 87 * device is returned to available device pool. 88 */ 89 public void freeDevice(ITestDevice device, FreeDeviceState state); 90 91 /** 92 * Helper method to launch emulator. 93 * <p/> 94 * Will launch the emulator as specified by the caller 95 * 96 * @param device the placeholder {@link ITestDevice} representing allocated emulator device 97 * @param bootTimeout the time in ms to wait for the emulator to boot 98 * @param runUtil 99 * @param emulatorArgs command line arguments to launch the emulator 100 * @throws DeviceNotAvailableException if emulator fails to boot or come online 101 */ 102 void launchEmulator(ITestDevice device, long bootTimeout, IRunUtil runUtil, 103 List<String> emulatorArgs) throws DeviceNotAvailableException; 104 105 /** 106 * Shut down the given emulator. 107 * <p/> 108 * Blocks until emulator disappears from adb. Will have no effect if emulator is already not 109 * available. 110 * 111 * @param device the {@link ITestDevice} representing emulator to shut down 112 * @throws DeviceNotAvailableException if emulator fails to shut down 113 */ 114 public void killEmulator(ITestDevice device) throws DeviceNotAvailableException; 115 116 /** 117 * Connect to a device with adb-over-tcp 118 * <p/> 119 * This method allocates a new device, which should eventually be freed via 120 * {@link #disconnectFromTcpDevice(ITestDevice)} 121 * <p/> 122 * The returned {@link ITestDevice} will be online, but may not be responsive. 123 * <p/> 124 * Note that performing action such as a reboot on a tcp connected device, will sever the 125 * tcp connection to the device, and result in a {@link DeviceNotAvailableException} 126 * 127 * @param ipAndPort the original ip address and port of the device to connect to 128 * @return the {@link ITestDevice} or <code>null</code> if a tcp connection could not be formed 129 */ 130 public ITestDevice connectToTcpDevice(String ipAndPort); 131 132 /** 133 * Disconnect from an adb-over-tcp connected device. 134 * <p/> 135 * Switches the device back to usb mode, and frees it. 136 * 137 * @param tcpDevice the device currently in tcp mode, previously allocated via 138 * {@link #connectToTcpDevice(String)} 139 * @return <code>true</code> if switch to usb mode was successful 140 */ 141 public boolean disconnectFromTcpDevice(ITestDevice tcpDevice); 142 143 /** 144 * A helper method that switches the given usb device to adb-over-tcp mode, and then connects to 145 * it via {@link #connectToTcpDevice(String)}. 146 * 147 * @param usbDevice the device currently in usb mode 148 * @return the newly allocated {@link ITestDevice} in tcp mode or <code>null</code> if a tcp 149 * connection could not be formed 150 * @throws DeviceNotAvailableException if the connection with <var>usbDevice</var> was lost and 151 * could not be recovered 152 */ 153 public ITestDevice reconnectDeviceToTcp(ITestDevice usbDevice) 154 throws DeviceNotAvailableException; 155 156 /** 157 * Stops device monitoring services, and terminates the ddm library. 158 * <p/> 159 * This must be called upon application termination. 160 * 161 * @see AndroidDebugBridge#terminate() 162 */ 163 public void terminate(); 164 165 /** Stops the device recovery thread. */ 166 public void terminateDeviceRecovery(); 167 168 /** Stop the Device Monitors. */ 169 public void terminateDeviceMonitor(); 170 171 /** Like {@link #terminate()}, but attempts to forcefully shut down adb as well. */ 172 public void terminateHard(); 173 174 /** Stop adb bridge and services depend on adb connections. */ 175 public void stopAdbBridge(); 176 177 /** 178 * Restart (if {@link #stopAdbBridge()} was called) adb bridge and services depend on adb 179 * connections. 180 */ 181 public void restartAdbBridge(); 182 183 /** 184 * Returns a map of all known devices and their state 185 * 186 * @return a list of device serials and their {@link 187 * com.android.tradefed.device.DeviceAllocationState} 188 */ 189 public List<DeviceDescriptor> listAllDevices(); 190 191 /** 192 * Output a user-friendly description containing list of known devices, their state, and 193 * values for commonly used {@link IDeviceSelection} options. 194 * 195 * @param printWriter the {@link PrintWriter} to output the description to 196 */ 197 public void displayDevicesInfo(PrintWriter printWriter); 198 199 /** 200 * Informs the manager that a listener is interested in fastboot state changes. 201 * <p/> 202 * Currently a {@link IDeviceManager} will only monitor devices in fastboot if there are one or 203 * more active listeners. 204 * <p/> 205 * TODO: this is a bit of a hack - find a better solution 206 * 207 * @param listener 208 */ 209 public void addFastbootListener(IFastbootListener listener); 210 211 /** 212 * Informs the manager that a listener is no longer interested in fastboot state changes. 213 * @param listener 214 */ 215 public void removeFastbootListener(IFastbootListener listener); 216 217 /** 218 * Determine if given serial represents a null device 219 */ 220 public boolean isNullDevice(String serial); 221 222 /** 223 * Determine if given serial represents a emulator 224 */ 225 public boolean isEmulator(String serial); 226 227 /** 228 * Adds a {@link IDeviceMonitor} 229 */ 230 public void addDeviceMonitor(IDeviceMonitor mon); 231 232 /** 233 * Removes a previously added {@link IDeviceMonitor}. Has no effect if mon has not been added. 234 */ 235 public void removeDeviceMonitor(IDeviceMonitor mon); 236 237 /** 238 * Returns the path to the fastboot binary path to use. 239 */ 240 public String getFastbootPath(); 241 242 /** 243 * Wait until a first physical device is connected. If a device was connected before, it 244 * returns directly True. If no device was added, it returns false after timeout. 245 * 246 * @param timeout time to wait in millisecond before returning false. 247 */ 248 public boolean waitForFirstDeviceAdded(long timeout); 249 250 /** 251 * Get the number of available flashing permits 252 * 253 * @return Number of available flashing permits or Integer.MAX_VALUE if not available. 254 */ 255 public int getAvailableFlashingPermits(); 256 257 /** 258 * Request permission to flash. If the number of concurrent flashers is limited, this will 259 * wait in line in order to remain under the flash limit count. 260 */ 261 public void takeFlashingPermit(); 262 263 /** 264 * Restore a flashing permit that we acquired previously 265 */ 266 public void returnFlashingPermit(); 267 268 /** Get the adb version currently in use by the device manager. */ 269 public String getAdbVersion(); 270 } 271
