FastbootDeviceFlasher

public class FastbootDeviceFlasher
extends Object implements IDeviceFlasher

java.lang.Object
   ↳ com.android.tradefed.targetprep.FastbootDeviceFlasher
Known Direct Subclasses
CdmaDeviceFlasher A class that flashes an image on a physical Android device with a CDMA radio. 


A class that relies on fastboot to flash an image on physical Android hardware.

Summary

Constants

String BASEBAND_IMAGE_NAME

Public constructors

FastbootDeviceFlasher()

Public methods

void flash(ITestDevice device, IDeviceBuildInfo deviceBuild)

Flashes build on device.

IDeviceFlasher.UserDataFlashOption getUserDataFlashOption()

Gets whether the user data image should be flashed, wiped, or retained

void overrideDeviceOptions(ITestDevice device)

Override options for a device.

void setDataWipeSkipList(Collection<String> dataWipeSkipList)

Sets the list of paths under /data to avoid clearing when using ITestsZipInstaller

Note that the granularity of the skip list is direct children of /data.

void setFlashingResourcesRetriever(IFlashingResourcesRetriever retriever)

Sets the mechanism by which the flasher can retrieve resource files for flashing.

void setForceSystemFlash(boolean forceSystemFlash)

Sets if system should always be flashed even if running current build

void setUserDataFlashOption(IDeviceFlasher.UserDataFlashOption flashOption)

Toggles whether the user data image should be flashed, wiped, or retained

void setWipeTimeout(long timeout)

Set the timeout for wiping the data.

Protected methods

void checkAndFlashBaseband(ITestDevice device, IDeviceBuildInfo deviceBuild)

If needed, flash the baseband image on device.

boolean checkAndFlashBootloader(ITestDevice device, IDeviceBuildInfo deviceBuild)

If needed, flash the bootloader image on device.

boolean checkAndFlashSystem(ITestDevice device, String systemBuildId, String systemBuildFlavor, IDeviceBuildInfo deviceBuild)

If needed, flash the system image on device.

boolean checkShouldFlashBaseband(ITestDevice device, IDeviceBuildInfo deviceBuild)

Check if the baseband on the provided device needs to be flashed.

IFlashingResourcesParser createFlashingResourcesParser(IDeviceBuildInfo localBuild, DeviceDescriptor descriptor)

Factory method for creating a IFlashingResourcesParser.

void downloadExtraImageFiles(IFlashingResourcesParser resourceParser, IFlashingResourcesRetriever retriever, IDeviceBuildInfo localBuild)

Hook to allow subclasses to download extra custom image files if needed.

void downloadFlashingResources(ITestDevice device, IDeviceBuildInfo localBuild)

Downloads extra flashing image files needed

String executeFastbootCmd(ITestDevice device, String... cmdArgs)

Helper method to execute fastboot command.

String executeLongFastbootCmd(ITestDevice device, String... cmdArgs)

Helper method to execute a long-running fastboot command.

void flashBaseband(ITestDevice device, File basebandImageFile)

Flashes the given baseband image and reboot back into bootloader

void flashBootloader(ITestDevice device, File bootloaderImageFile)

Flashes the given bootloader image and reboots back into bootloader

void flashPartition(ITestDevice device, File imgFile, String partition)

Flash an individual partition of a device

void flashSystem(ITestDevice device, IDeviceBuildInfo deviceBuild)

Flash the system image on device.

void flashUserData(ITestDevice device, IDeviceBuildInfo deviceBuild)

Flash userdata partition on device.

void flashUserDataFromDeviceImageFile(ITestDevice device, IDeviceBuildInfo deviceBuild)

Extracts the userdata.img from device image file and flashes it onto device

String getBootPartitionName()

Get the boot partition name for this device flasher.

String getBootloaderFilePrefix(ITestDevice device)

Get the bootloader file prefix.

IFlashingResourcesRetriever getFlashingResourcesRetriever()
String getImageVersion(ITestDevice device, String imageName)

Helper method to get the current image version on device.

IRunUtil getRunUtil()

Exposed for testing.

void handleUserDataFlashing(ITestDevice device, IDeviceBuildInfo deviceBuild)

Handle flashing of userdata/cache partition

boolean hasPartition(ITestDevice device, String partition)

Checks with the bootloader if the specified partition exists or not

void verifyRequiredBoards(ITestDevice device, IFlashingResourcesParser resourceParser, String deviceProductType)

Verify that the device's product type supports the build-to-be-flashed.

void wipeCache(ITestDevice device)

Wipe the cache partition on device.

void wipePartition(ITestDevice device, String partition)

Wipe the specified partition with `fastboot erase <name>`

Constants

BASEBAND_IMAGE_NAME

String BASEBAND_IMAGE_NAME

Constant Value: "radio"

Public constructors

FastbootDeviceFlasher

FastbootDeviceFlasher ()

Public methods

flash

void flash (ITestDevice device, 
                IDeviceBuildInfo deviceBuild)

Flashes build on device.

Returns immediately after flashing is complete. Callers should wait for device to be online and available before proceeding with testing.

Parameters
device ITestDevice: the ITestDevice to flash
deviceBuild IDeviceBuildInfo: the IDeviceBuildInfo to flash
Throws
TargetSetupError
DeviceNotAvailableException

getUserDataFlashOption

IDeviceFlasher.UserDataFlashOption getUserDataFlashOption ()

Gets whether the user data image should be flashed, wiped, or retained

Returns
IDeviceFlasher.UserDataFlashOption Whether the user data image should be flashed, wiped, or retained

overrideDeviceOptions

void overrideDeviceOptions (ITestDevice device)

Override options for a device. Used to override default option values if the defaults are not supported by a particular device.

setDataWipeSkipList

void setDataWipeSkipList (Collection<String> dataWipeSkipList)

Sets the list of paths under /data to avoid clearing when using ITestsZipInstaller

Note that the granularity of the skip list is direct children of /data.

Parameters
dataWipeSkipList Collection

setFlashingResourcesRetriever

void setFlashingResourcesRetriever (IFlashingResourcesRetriever retriever)

Sets the mechanism by which the flasher can retrieve resource files for flashing.

Parameters
retriever IFlashingResourcesRetriever: the IFlashingResourcesRetriever to use

setForceSystemFlash

void setForceSystemFlash (boolean forceSystemFlash)

Sets if system should always be flashed even if running current build

setUserDataFlashOption

void setUserDataFlashOption (IDeviceFlasher.UserDataFlashOption flashOption)

Toggles whether the user data image should be flashed, wiped, or retained

setWipeTimeout

void setWipeTimeout (long timeout)

Set the timeout for wiping the data.

Parameters
timeout long

Protected methods

checkAndFlashBaseband

void checkAndFlashBaseband (ITestDevice device, 
                IDeviceBuildInfo deviceBuild)

If needed, flash the baseband image on device. Will only flash baseband if current version on device != required version

Parameters
device ITestDevice: the ITestDevice to flash
deviceBuild IDeviceBuildInfo: the IDeviceBuildInfo that contains the baseband image to flash
Throws
DeviceNotAvailableException if device is not available
TargetSetupError if failed to flash baseband

checkAndFlashBootloader

boolean checkAndFlashBootloader (ITestDevice device, 
                IDeviceBuildInfo deviceBuild)

If needed, flash the bootloader image on device.

Will only flash bootloader if current version on device != required version.

Parameters
device ITestDevice: the ITestDevice to flash
deviceBuild IDeviceBuildInfo: the IDeviceBuildInfo that contains the bootloader image to flash
Returns
boolean true if bootloader was flashed, false if it was skipped
Throws
DeviceNotAvailableException if device is not available
TargetSetupError if failed to flash bootloader

checkAndFlashSystem

boolean checkAndFlashSystem (ITestDevice device, 
                String systemBuildId, 
                String systemBuildFlavor, 
                IDeviceBuildInfo deviceBuild)

If needed, flash the system image on device.

Please look at shouldFlashSystem(String, String, IDeviceBuildInfo)

Regardless of path chosen, after method execution device should be booting into userspace.

Parameters
device ITestDevice: the ITestDevice to flash
systemBuildId String: the current build id running on the device
systemBuildFlavor String: the current build flavor running on the device
deviceBuild IDeviceBuildInfo: the IDeviceBuildInfo that contains the system image to flash
Returns
boolean true if system was flashed, false if it was skipped
Throws
DeviceNotAvailableException if device is not available
TargetSetupError if failed to flash bootloader

checkShouldFlashBaseband

boolean checkShouldFlashBaseband (ITestDevice device, 
                IDeviceBuildInfo deviceBuild)

Check if the baseband on the provided device needs to be flashed.

Parameters
device ITestDevice: the ITestDevice to check
deviceBuild IDeviceBuildInfo: the IDeviceBuildInfo that contains the baseband image to check
Returns
boolean
Throws
DeviceNotAvailableException if device is not available
TargetSetupError if failed to flash baseband

createFlashingResourcesParser

IFlashingResourcesParser createFlashingResourcesParser (IDeviceBuildInfo localBuild, 
                DeviceDescriptor descriptor)

Factory method for creating a IFlashingResourcesParser.

Exposed for unit testing.

Parameters
localBuild IDeviceBuildInfo: the IDeviceBuildInfo to parse
descriptor DeviceDescriptor: the descriptor of the device being flashed.
Returns
IFlashingResourcesParser a IFlashingResourcesParser created by the factory method.
Throws
TargetSetupError

downloadExtraImageFiles

void downloadExtraImageFiles (IFlashingResourcesParser resourceParser, 
                IFlashingResourcesRetriever retriever, 
                IDeviceBuildInfo localBuild)

Hook to allow subclasses to download extra custom image files if needed.

Parameters
resourceParser IFlashingResourcesParser: the IFlashingResourcesParser
retriever IFlashingResourcesRetriever: the IFlashingResourcesRetriever
localBuild IDeviceBuildInfo: the IDeviceBuildInfo
Throws
TargetSetupError

downloadFlashingResources

void downloadFlashingResources (ITestDevice device, 
                IDeviceBuildInfo localBuild)

Downloads extra flashing image files needed

Parameters
device ITestDevice: the ITestDevice to download resources for
localBuild IDeviceBuildInfo: the IDeviceBuildInfo to populate. Assumes device image file is already set
Throws
DeviceNotAvailableException if device is not available
TargetSetupError if failed to retrieve resources

executeFastbootCmd

String executeFastbootCmd (ITestDevice device, 
                String... cmdArgs)

Helper method to execute fastboot command.

Parameters
device ITestDevice: the ITestDevice to execute command on
cmdArgs String: the arguments to provide to fastboot
Returns
String String the stderr output from command if non-empty. Otherwise returns the stdout Some fastboot commands are weird in that they dump output to stderr on success case
Throws
DeviceNotAvailableException if device is not available
TargetSetupError if fastboot command fails

executeLongFastbootCmd

String executeLongFastbootCmd (ITestDevice device, 
                String... cmdArgs)

Helper method to execute a long-running fastboot command.

Note: Most fastboot commands normally execute within the timeout allowed by executeFastbootCommand(String). However, when multiple devices are flashing devices at once, fastboot commands can take much longer than normal.

Parameters
device ITestDevice: the ITestDevice to execute command on
cmdArgs String: the arguments to provide to fastboot
Returns
String String the stderr output from command if non-empty. Otherwise returns the stdout Some fastboot commands are weird in that they dump output to stderr on success case
Throws
DeviceNotAvailableException if device is not available
TargetSetupError if fastboot command fails

flashBaseband

void flashBaseband (ITestDevice device, 
                File basebandImageFile)

Flashes the given baseband image and reboot back into bootloader

Parameters
device ITestDevice: the ITestDevice to flash
basebandImageFile File: the baseband image File
Throws
DeviceNotAvailableException if device is not available
TargetSetupError if failed to flash baseband

flashBootloader

void flashBootloader (ITestDevice device, 
                File bootloaderImageFile)

Flashes the given bootloader image and reboots back into bootloader

Parameters
device ITestDevice: the ITestDevice to flash
bootloaderImageFile File: the bootloader image File
Throws
DeviceNotAvailableException if device is not available
TargetSetupError if failed to flash

flashPartition

void flashPartition (ITestDevice device, 
                File imgFile, 
                String partition)

Flash an individual partition of a device

Parameters
device ITestDevice: the ITestDevice to flash
imgFile File: a File pointing to the image to be flashed
partition String: the name of the partition to be flashed
Throws
DeviceNotAvailableException
TargetSetupError

flashSystem

void flashSystem (ITestDevice device, 
                IDeviceBuildInfo deviceBuild)

Flash the system image on device.

Parameters
device ITestDevice: the ITestDevice to flash
deviceBuild IDeviceBuildInfo: the IDeviceBuildInfo to flash
Throws
DeviceNotAvailableException if device is not available
TargetSetupError if fastboot command fails

flashUserData

void flashUserData (ITestDevice device, 
                IDeviceBuildInfo deviceBuild)

Flash userdata partition on device.

Parameters
device ITestDevice: the ITestDevice to flash
deviceBuild IDeviceBuildInfo: the IDeviceBuildInfo that contains the files to flash
Throws
DeviceNotAvailableException if device is not available
TargetSetupError if failed to flash user data

flashUserDataFromDeviceImageFile

void flashUserDataFromDeviceImageFile (ITestDevice device, 
                IDeviceBuildInfo deviceBuild)

Extracts the userdata.img from device image file and flashes it onto device

Parameters
device ITestDevice: the ITestDevice to flash
deviceBuild IDeviceBuildInfo: the IDeviceBuildInfo that contains the files to flash
Throws
DeviceNotAvailableException if device is not available
TargetSetupError if failed to extract or flash user data

getBootPartitionName

String getBootPartitionName ()

Get the boot partition name for this device flasher.

Defaults to 'hboot'. Subclasses should override if necessary.

Returns
String

getBootloaderFilePrefix

String getBootloaderFilePrefix (ITestDevice device)

Get the bootloader file prefix.

Defaults to getBootPartitionName(). Subclasses should override if necessary.

Parameters
device ITestDevice: the ITestDevice to flash
Returns
String
Throws
DeviceNotAvailableException if device is not available
TargetSetupError if failed to get prefix

getFlashingResourcesRetriever

IFlashingResourcesRetriever getFlashingResourcesRetriever ()

Returns
IFlashingResourcesRetriever

getImageVersion

String getImageVersion (ITestDevice device, 
                String imageName)

Helper method to get the current image version on device.

Parameters
device ITestDevice: the ITestDevice to execute command on
imageName String: the name of image to get.
Returns
String String the stdout output from command
Throws
DeviceNotAvailableException if device is not available
TargetSetupError if fastboot command fails or version could not be determined

getRunUtil

IRunUtil getRunUtil ()

Exposed for testing.

Returns
IRunUtil

handleUserDataFlashing

void handleUserDataFlashing (ITestDevice device, 
                IDeviceBuildInfo deviceBuild)

Handle flashing of userdata/cache partition

Parameters
device ITestDevice: the ITestDevice to flash
deviceBuild IDeviceBuildInfo: the IDeviceBuildInfo that contains the files to flash
Throws
DeviceNotAvailableException
TargetSetupError
DeviceNotAvailableException

hasPartition

boolean hasPartition (ITestDevice device, 
                String partition)

Checks with the bootloader if the specified partition exists or not

Parameters
device ITestDevice: the ITestDevice to operate on
partition String: the name of the partition to be checked
Returns
boolean
Throws
DeviceNotAvailableException

verifyRequiredBoards

void verifyRequiredBoards (ITestDevice device, 
                IFlashingResourcesParser resourceParser, 
                String deviceProductType)

Verify that the device's product type supports the build-to-be-flashed.

The base implementation will verify that the deviceProductType is included in the getRequiredBoards() collection. Subclasses may override as desired.

Parameters
device ITestDevice: the ITestDevice to be flashed
resourceParser IFlashingResourcesParser: the IFlashingResourcesParser
deviceProductType String: the device's product type
Throws
TargetSetupError if the build's required board info did not match the device

wipeCache

void wipeCache (ITestDevice device)

Wipe the cache partition on device.

Parameters
device ITestDevice: the ITestDevice to flash
Throws
DeviceNotAvailableException if device is not available
TargetSetupError if failed to flash cache

wipePartition

void wipePartition (ITestDevice device, 
                String partition)

Wipe the specified partition with `fastboot erase <name>`

Parameters
device ITestDevice: the ITestDevice to operate on
partition String: the name of the partition to be wiped
Throws
DeviceNotAvailableException
TargetSetupError