Android fastboot

### http://www.omappedia.org/wiki/Android_Fastboot ###

Android Fastboot

[edit]Overview

Fastboot is the method android uses to flash the android build onto the target. If you really want the details, the fastboot protocol specification is found in the android source fastboot_protocol.txt

What's with the name 'fastboot' or how are you booting faster ? This feature should be renamed 'making-the-bootloader-simple-to-use'. Fastboot speeds up your development NOT the time it takes to boot.

[edit]Flashing with Fastboot

The biggest benifit of fastboot is that it automates the manual steps of flashing nand. Look back on the manual steps here. As an example In fastboot all you need to do to flash the kernel is from your host machine.

The fastboot client is built as part of a normal android build, it is located ./out/host/linux-x86/bin/fastboot'

# sudo fastboot flash kernel path-to-kernel/uImage

Similarly for the rootfs

# sudo fastboot flash system path-to-system/system.img

The general form to flash is

# sudo fastboot flash <partition name> <file>

That is it, all the details are taken care of for you. You do not have to know to unlock the NAND, which flavor of ECC to use, which method of writing to NAND or even where the flash happens. Its all done for you.

[edit]Getting fastboot client

The fastboot client is part of Android. It is built when you build Android. You wil find fastboot in out/host/linux-x86/bin/fastboot.

[edit]Supported Partitions

Regions in NAND are given names. Their offsets and sizes are set in U-boot. To run most fastboot client commands, you need to know what partition name corresponds to which file.

NAND partition names
name	offset	size
xloader	0x00000000	0x00080000
bootloader	0x00080000	0x00180000
environment	0x001C0000	0x00040000
kernel	0x00200000	0x01D00000
system	0x02000000	0x0A000000
userdata	0x0C000000	0x02000000
cache	0x0E000000	0x02000000

NAND partition input files
name	type of file	usual file
xloader	xloader binary	MLO
bootloader	uboot binary	u-boot.bin
environment	text file	list of variables to set
kernel	kernel or kernel + ramdisk	uImage, uMulti
system	yaffs2	system.img
userdata	yaffs2	userdata.img
cache	yaffs2	?

[edit]Text file format

Instead of setting the environment manually, a text file is used set and unset environment variables. The text file is list of variable / value pairs. One variable per line. The setting and unsetting are similar to the u-boot setenv command.

• To set

variable value

• To unset

variable 

• This is an example of the minimal environment file needed to boot an android uMulti image and system.img

bootdelay 10
bootargs console=ttyS3,115200n8
bootcmd nand unlock; nand read.i 81000000 ${kernel_nand_offset} ${kernel_nand_size}; bootm 81000000

• Fastboot supports comments in environment files

The comments in environment files are now similar to bash. The '#' is the comment character.
The limitation is that the '#' must be in used before any other non-whitespace character.

This is valid:
# Use this one

This is not valid:
bootcmd bootm 81000000 # My boot command

[edit]Kernel Nand_offset and Nand_size

In general when fastboot flashes a partition, it saves the nand offset and size of the image as enviroment variables. The format of the names are

• <partition name>_nand_offset
• <partition name>_nand_size

As and example when the kernel is flashed, you can view the u-boot environment and see that

• kernel_nand_offset=0x140000
• kernel_nand_size=0x1f70000

The benifit of these variables is that you can write general environment files.

[edit]Fastboot on the Zoom II

[edit]On Target

Connect the board to allow for USBOTG to work y as described here. On u-boot prompt, enter command fastboot. (this can also be done automatically in u-boot through setenv bootcmd 'fastboot') During usb setup, the large LED in the top left of the Zoom II binks red and blue. When the setup is complete, the blue LED should be on.

[edit]On Host

# lsusb 
Bus 008 Device 030: ID 0451:cafe Texas Instruments, Inc. <----- fastboot 
Bus 008 Device 005: ID 0d8c:000c C-Media Electronics, Inc. Audio Adapter
Bus 008 Device 004: ID 05e3:0608 Genesys Logic, Inc. USB-2.0 4-Port HUB
Bus 008 Device 003: ID 2001:3c05 D-Link Corp. [hex] DUB-E100 Fast Ethernet [asix]

For more detail, look in proc fs.

# cat /proc/bus/usb/devices
T:  Bus=01 Lev=01 Prnt=01 Port=05 Cnt=02 Dev#= 85 Spd=480 MxCh= 0
D:  Ver= 1.10 Cls=ff(vend.) Sub=ff Prot=ff MxPS=64 #Cfgs=  1
P:  Vendor=0451 ProdID=cafe Rev= 3.11
S:  Manufacturer=Texas Instruments
S:  Product=Zoom2
S:  SerialNumber=00123
C:* #Ifs= 1 Cfg#= 1 Atr=c0 MxPwr=100mA
I:* If#= 0 Alt= 0 #EPs= 2 Cls=ff(vend.) Sub=42 Prot=03 Driver=(none)
E:  Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms
E:  Ad=01(O) Atr=02(Bulk) MxPS=  64 Ivl=0ms

[edit]Trouble Shooting

If you fail to see the fastboot device on the host or the Zoom II red LED remains on First check the usb cable is connected to Zoom II usb and battery or AC power is connected to Zoom II

If you are connected, then follow these steps:

1. Remove power from the Zoom II
2. Unplug usb from Zoom II
3. Remove Zoom II from debug board
4. Plug AC power to zoom II
5. Press the power button on the top right of zoom II
6. Wait for top left LED to flash blue
7. Put Zoom II on the debug board board
8. Cycle power from debug board
9. Verify u boot on serial console connected to left most usb on debug board
10. Restart the serial console if console is unresponsive
11. Type fastboot on uboot console
12. Plug in usb to zoom II

Verifying if fast boot client recognizes the Zoom2 device:

sudo sudo fastboot devices
Output: 00123   fastboot

[edit]Use Cases

NOTE: All features of fastboot have been implemented in v1.1 u-boot and x-loader. Please upgrade to v1.1 from here

Flashing Android on NAND

[edit]On target

• start fastboot

# fastboot

[edit]On host side

# sudo fastboot flash xloader MLO-Zoom2
# sudo fastboot flash bootloader uboot-Zoom2
# sudo fastboot flash kernel uMulti-Image
# sudo fastboot flash system system.img
# sudo fastboot flash userdata userdata.img
# sudo fastboot erase cache
# sudo fastboot flash environment environment_vars.txt

The environment_vars.txt file is

bootdelay 10
bootargs console=ttyS3,115200n8
bootcmd nand unlock; nand read.i 81000000 ${kernel_nand_offset} ${kernel_nand_size}; bootm 81000000

The locations of the images relative to the top of the android source tree is

 
xloader  : bootloader/MLO
bootloader : bootloader/u-boot.bin
uMulti-Image : See bellow
kernel : kernel/arch/arm/boot/zImage
ramdisk.img : out/target/product/zoom2/ramdisk.img
system : out/target/product/zoom2/system.img
userdata : out/target/product/zoom2/userdata.img

uMulti-Image = combine the Android ramdisk with the kernel, use the u-boot utility mkimage

 
mkimage -A arm -O linux -T multi -C none \
    -a 0x80008000 -e 0x80008000 -n 'Name_Of_Your_Release'' \
    -d <path-to-kernel>/arch/arm/boot/zImage:<path-to-android-out-dir>/ramdisk.img \
    uMulti-2

[edit]Flashing NAND w/o debug board

This usecase assumes you only have a Zoom II and still want to flash your board. To do this you need to put the Zoom II into the fastboot preboot mode by holding down two keys while the board is booting. Follow these steps.

1. Disconnect the debug board from Zoom II
2. Disconnect the power and usb cables to Zoom II
3. Reset the board with the small button on back, interior of the Zoom II.
4. Hold down the large center 'OK' button
5. You only have about 1/2 second between steps 3 & 4 before normal booting continues. Holding the 'Ok' button before step 3 is helpful.

You should see

• LED briefly blink red to off
• LED stay on red

The continuous red LED means that fastboot command has started. Next you should Connect the USB cable from the host to the Zoom II

You should see:

• LED blink red to blue
• Continous blue

This means that USB discovery by the host was successful. You are ready to go! If you do not see a continous blue LED, repeat the setup steps. The instructions from the host side are the same as the use case with the debug board.

[edit]Updating only kernel on NAND

[edit]On target

• start fastboot

# fastboot

[edit]On Host

# sudo fastboot flash kernel uMulti-Image

[edit]Updating system image on NAND

[edit]On target

• start fastboot

# fastboot

[edit]On Host

# sudo fastboot flash system system.img

[edit]Updating bootloader image on NAND

[edit]On target

• start fastboot

# fastboot

[edit]On Host

# sudo fastboot flash bootloader uboot-Zoom2
# sudo fastboot flash environment environment_vars.txt

[edit]Updating linux kernel and yaffs2 filesystem on NAND

[edit]On target

• start fastboot

# fastboot

[edit]On Host

# sudo fastboot flash xloader MLO-Zoom2
# sudo fastboot flash bootloader uboot-Zoom2
# sudo fastboot flash kernel uImage
# sudo fastboot flash system filesystem.yaff2
# sudo fastboot erase userdata
# sudo fastboot erase cache
# sudo fastboot flash environment Kernel_rootfs

The Kernel_rootfs file is

bootdelay 10
bootargs console=ttyS3,115200n8 root=/dev/mtdblock4 rw rootfstype=yaffs2 init=/sbin/init
bootcmd nand unlock; nand read.i 80000000 ${kernel_nand_offset} ${kernel_nand_size}; bootm

[edit]Rebooting the board

[edit]On target

• start fastboot

# fastboot

[edit]On Host

# sudo fastboot reboot

[edit]Booting a test kernel from memory, no flashing

[edit]On target

• start fastboot

# fastboot

[edit]On Host

# sudo fastboot boot uImage

[edit]Rebooting a test bootloader from memory, no flashing

[edit]On target

• start fastboot

# fastboot

[edit]On Host

# sudo fastboot boot u-boot.bin

[edit]Issues

• The use of nand unlock in the bootargs is intended for development only.
• The maximum download size is 240M.
• fastboot_client flashall is not implemented

[edit]Pending Changes

[edit]Runtime Partitions

How do you customize the NAND layout by adding or deleting partitions?

Fastboot reuses the kernel's method of customizing the NAND partitions and most of the partitions are changable. This is the list of the unchangable or static partitions.

Static NAND partition names
name	offset	size
xloader	0x00000000	0x00080000
bootloader	0x00080000	0x00180000
environment	0x001C0000	0x00040000

The runtime partitions are defined by the u-boot environment variable fbparts. Its format is simlar to the kernel's boot command line variable mtdparts. Here is an example of how the system partition is defined at runtime for fastboot and for the kernel.

• Fastboot: fbparts 160m@32m(system)yaffs|swecc
• Kernel: mtdparts=omap2-nand.0:160m@32m(system)

For fastboot, 160m@32m(system)yaffs|swecc, means create a partition at 32M with a size of 160M, name it 'system' and use the fastboot flags yaffs and swecc.

For the kernel, omap2-nand.0:160m@32m(system), means for the omap2-nand.0 device, create a partition at 32M with a size of 160M and name it 'system'

Format of fbparts The format is:

<size>@<offset>(<name>)<optional-flags>,

• <size> = is the extent of the nand partition, in bytes. This should be a multiple of the NAND block size.
• <offset> = is where the nand partition begins, in bytes. This should be a multiple of the NAND block size.
• <name> = is the same as what is used by the fastboot client.

The supported flags control how the data is written into nand they are

i        : use nand write.i
yaffs    : use nand write.yaffs
swecc    : use nand software ecc
hwecc    : use nand hardware ecc

Multiple flags can be or-ed together with a '|'

[edit]Timeout and user exiting of fastboot

In addition to disconnecting the usb cable, the user can exit fastboot when a user defined timeout expires or when a Ctrl-C is seen from the console.

This is the new fastboot help

# help fastboot fastboot [inactive timeout]     
- Run as a fastboot usb device. The optional inactive timeout is the decimal seconds before the normal console resumes.
<pre>

To run fastboot with a timeout of 100 seconds, do 
<pre>
# fastboot 100

The console prints out

Fastboot inactivity timeout 100 seconds 
Disconnect USB cable to finish fastboot.. 
Fastboot inactivity detected

You can still do

# fastboot

It will behave as it did before. If you want to stop it, now you can use the Ctrl-C on the console. The timeout happens when inactivity is seen during the fastboot command. The timeout is reset after each command. If the command takes longer than timeout, like reflashing the system image, it will not timeout during the command. Because host discovery of the fastboot device can take a couple of seconds, it is recommended that the timeout be at least 10 seconds.