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
`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`	`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`	`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.
`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()`
`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`	`preFlashSetup(ITestDevice device, IDeviceBuildInfo deviceBuild)` Perform any additional pre-flashing setup required.
`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

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.

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

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
`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
`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 ITestDevice#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

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

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

getFlashingResourcesRetriever

protected IFlashingResourcesRetriever getFlashingResourcesRetriever ()

Returns
`IFlashingResourcesRetriever`

getImageVersion

protected 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

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

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

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`