FastbootDeviceFlasher

public class FastbootDeviceFlasher
extends Object implements IDeviceFlasher

java.lang.Object
   ↳ com.android.tradefed.targetprep.FastbootDeviceFlasher


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

Summary

Fields

public static final String BASEBAND_IMAGE_NAME

Public constructors

FastbootDeviceFlasher()

Public methods

static String fetchImageVersion(IRunUtil runUtil, ITestDevice device, String imageName)

Helper method to get the current image version on device.

void flash(ITestDevice device, IDeviceBuildInfo deviceBuild)

Flashes build on device.

CommandStatus getSystemFlashingStatus()

Retrieve the command execution status for flashing primary system partitions.

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 preFlashOperations(ITestDevice device, IDeviceBuildInfo deviceBuild)

All setup operations & checks that must occur before actual flashing critical section.

void setDataWipeSkipList( 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 setFlashOptions( flashOptions)

Sets a list of options to pass with flash/update commands.

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 setIncrementalFlashing(IncrementalImageUtil incrementalUtil)
void setRamdiskPartition(String ramdiskPartition)

Sets ramdisk partition

void setShouldFlashRamdisk(boolean shouldFlashRamdisk)

Sets if an additional ramdisk should be flashed after updating device via image zip

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.

boolean shouldFlashRamdisk()

Checks if the flasher is set to have an additional ramdisk should be flashed after updating device via image zip

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.

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

Helper method to execute a long-running fastboot command with environment variables.

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 flashExtraImages(ITestDevice device, IDeviceBuildInfo deviceBuild)

Flash any device specific partitions before flashing system and rebooting.

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

Flash an individual partition of a device

void flashRamdiskIfNeeded(ITestDevice device, IDeviceBuildInfo deviceBuild)
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.

String getCurrentSlot(ITestDevice device)

Helper method to retrieve the current slot (for A/B capable devices).

IFlashingResourcesRetriever getFlashingResourcesRetriever()
FuseUtil getFuseUtil()
String getImageVersion(ITestDevice device, String imageName)
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 preFlashSetup(ITestDevice device, IDeviceBuildInfo deviceBuild)

Perform any additional pre-flashing setup required.

void setSystemBuildInfo(String systemBuildId, String systemBuildFlavor)
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>`

Fields

BASEBAND_IMAGE_NAME

public static final String BASEBAND_IMAGE_NAME

Public constructors

FastbootDeviceFlasher

public FastbootDeviceFlasher ()

Public methods

fetchImageVersion

public static String fetchImageVersion (IRunUtil runUtil, 
                ITestDevice device, 
                String imageName)

Helper method to get the current image version on device.

Parameters
runUtil IRunUtil

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

flash

public 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
DeviceNotAvailableException
TargetSetupError

getSystemFlashingStatus

public CommandStatus getSystemFlashingStatus ()

Retrieve the command execution status for flashing primary system partitions.

Note that if system partitions are not flashed (system already has the build to be flashed) the command status may be null

Returns
CommandStatus

getUserDataFlashOption

public 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

public 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.

preFlashOperations

public void preFlashOperations (ITestDevice device, 
                IDeviceBuildInfo deviceBuild)

All setup operations & checks that must occur before actual flashing critical section. None of those operations will be included in the concurrency-controlled critical section.

Parameters
device ITestDevice: the ITestDevice to flash

deviceBuild IDeviceBuildInfo: the IDeviceBuildInfo to flash

Throws
DeviceNotAvailableException
TargetSetupError

setDataWipeSkipList

public void setDataWipeSkipList ( 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

setFlashOptions

public void setFlashOptions ( flashOptions)

Sets a list of options to pass with flash/update commands.

setFlashingResourcesRetriever

public 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

public void setForceSystemFlash (boolean forceSystemFlash)

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

setIncrementalFlashing

public void setIncrementalFlashing (IncrementalImageUtil incrementalUtil)

Parameters
incrementalUtil IncrementalImageUtil

setRamdiskPartition

public void setRamdiskPartition (String ramdiskPartition)

Sets ramdisk partition

setShouldFlashRamdisk

public void setShouldFlashRamdisk (boolean shouldFlashRamdisk)

Sets if an additional ramdisk should be flashed after updating device via image zip

setUserDataFlashOption

public void setUserDataFlashOption (IDeviceFlasher.UserDataFlashOption flashOption)

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

setWipeTimeout

public void setWipeTimeout (long timeout)

Set the timeout for wiping the data.

Parameters
timeout long

shouldFlashRamdisk

public boolean shouldFlashRamdisk ()

Checks if the flasher is set to have an additional ramdisk should be flashed after updating device via image zip

Returns
boolean

Protected methods

checkAndFlashBaseband

protected 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

protected 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

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

If needed, flash the system image on device.

Please look at ERROR(/#shouldFlashSystem(String,String,com.android.tradefed.build.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

protected 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

protected 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
com.android.tradefed.targetprep.TargetSetupError
TargetSetupError

downloadExtraImageFiles

protected 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
com.android.tradefed.targetprep.TargetSetupError
TargetSetupError

downloadFlashingResources

protected 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

protected 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

protected 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 INativeDevice.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

executeLongFastbootCmd

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

Helper method to execute a long-running fastboot command with environment variables.

Note: Most fastboot commands normally execute within the timeout allowed by INativeDevice.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

envVarMap : the map which carries environment variables which need to be set before running the fastboot command

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

protected 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 ERROR(/File)

Throws
DeviceNotAvailableException if device is not available
TargetSetupError if failed to flash baseband

flashBootloader

protected 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 ERROR(/File)

Throws
DeviceNotAvailableException if device is not available
TargetSetupError if failed to flash

flashExtraImages

protected void flashExtraImages (ITestDevice device, 
                IDeviceBuildInfo deviceBuild)

Flash any device specific partitions before flashing system and rebooting. No-op unless overridden.

Parameters
device ITestDevice: the ITestDevice to flash

deviceBuild IDeviceBuildInfo: the IDeviceBuildInfo containing the build files

Throws
com.android.tradefed.device.DeviceNotAvailableException
com.android.tradefed.targetprep.TargetSetupError
DeviceNotAvailableException
TargetSetupError

flashPartition

protected 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 ERROR(/File) pointing to the image to be flashed

partition String: the name of the partition to be flashed

Throws
DeviceNotAvailableException
TargetSetupError

flashRamdiskIfNeeded

protected void flashRamdiskIfNeeded (ITestDevice device, 
                IDeviceBuildInfo deviceBuild)

Parameters
device ITestDevice

deviceBuild IDeviceBuildInfo

Throws
DeviceNotAvailableException
TargetSetupError

flashSystem

protected 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

protected 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

protected 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

protected String getBootPartitionName ()

Get the boot partition name for this device flasher.

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

Returns
String

getBootloaderFilePrefix

protected 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

getCurrentSlot

protected String getCurrentSlot (ITestDevice device)

Helper method to retrieve the current slot (for A/B capable devices).

Parameters
device ITestDevice: the ITestDevice to execute command on.

Returns
String "a", "b" or null (if device is not A/B capable)

Throws
com.android.tradefed.device.DeviceNotAvailableException
com.android.tradefed.targetprep.TargetSetupError
DeviceNotAvailableException
TargetSetupError

getFlashingResourcesRetriever

protected IFlashingResourcesRetriever getFlashingResourcesRetriever ()

Returns
IFlashingResourcesRetriever

getFuseUtil

protected FuseUtil getFuseUtil ()

Returns
FuseUtil

getImageVersion

protected String getImageVersion (ITestDevice device, 
                String imageName)

Parameters
device ITestDevice

imageName String

Returns
String

Throws
DeviceNotAvailableException
TargetSetupError

getRunUtil

protected IRunUtil getRunUtil ()

Exposed for testing.

Returns
IRunUtil

handleUserDataFlashing

protected 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
com.android.tradefed.device.DeviceNotAvailableException
com.android.tradefed.targetprep.TargetSetupError
DeviceNotAvailableException
TargetSetupError

hasPartition

protected 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

preFlashSetup

protected void preFlashSetup (ITestDevice device, 
                IDeviceBuildInfo deviceBuild)

Perform any additional pre-flashing setup required. No-op unless overridden.

Parameters
device ITestDevice: the ITestDevice to prepare

deviceBuild IDeviceBuildInfo: the IDeviceBuildInfo containing the build files

Throws
com.android.tradefed.device.DeviceNotAvailableException
com.android.tradefed.targetprep.TargetSetupError
DeviceNotAvailableException
TargetSetupError

setSystemBuildInfo

protected void setSystemBuildInfo (String systemBuildId, 
                String systemBuildFlavor)

Parameters
systemBuildId String

systemBuildFlavor String

verifyRequiredBoards

protected 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 IFlashingResourcesParser.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

protected 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

protected 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