Update fastboot documentation to reflect merged USB/UDP implementation.
Signed-off-by: Alex Kiernan alex.kiernan@gmail.com Reviewed-by: Simon Glass sjg@chromium.org ---
Changes in v8: - add Reviewed-by: tag
Changes in v7: None Changes in v6: - new
Changes in v5: None Changes in v4: None Changes in v3: None Changes in v2: None
doc/README.android-fastboot | 240 +++++++++++++++++++++++------------- 1 file changed, 156 insertions(+), 84 deletions(-)
diff --git a/doc/README.android-fastboot b/doc/README.android-fastboot index 2c3ee7810a..431191c473 100644 --- a/doc/README.android-fastboot +++ b/doc/README.android-fastboot @@ -1,142 +1,214 @@ +================ Android Fastboot -~~~~~~~~~~~~~~~~ +================
Overview ======== -The protocol that is used over USB is described in -README.android-fastboot-protocol in same directory.
-The current implementation is a minimal support of the erase command,the -"oem format" command and flash command;it only supports eMMC devices. +The protocol that is used over USB and UDP is described in the +``README.android-fastboot-protocol`` file in the same directory. + +The current implementation supports the following standard commands: + +- ``boot`` +- ``continue`` +- ``download`` +- ``erase`` (if enabled) +- ``flash`` (if enabled) +- ``getvar`` +- ``reboot`` +- ``reboot-bootloader`` +- ``set_active`` (only a stub implementation which always succeeds) + +The following OEM commands are supported (if enabled): + +- oem format - this executes ``gpt write mmc %x $partitions`` + +Support for both eMMC and NAND devices is included.
Client installation =================== -The counterpart to this gadget is the fastboot client which can -be found in Android's platform/system/core repository in the fastboot -folder. It runs on Windows, Linux and even OSX. Linux user are lucky since -they only need libusb. -Windows users need to bring some time until they have Android SDK (currently -http://dl.google.com/android/installer_r12-windows.exe) installed. You -need to install ADB package which contains the required glue libraries for -accessing USB. Also you need "Google USB driver package" and "SDK platform -tools". Once installed the usb driver is placed in your SDK folder under -extras\google\usb_driver. The android_winusb.inf needs a line like - - %SingleBootLoaderInterface% = USB_Install, USB\VID_0451&PID_D022 - -either in the [Google.NTx86] section for 32bit Windows or [Google.NTamd64] -for 64bit Windows. VID and PID should match whatever the fastboot is -advertising. + +The counterpart to this is the fastboot client which can be found in +Android's ``platform/system/core`` repository in the fastboot +folder. It runs on Windows, Linux and OSX. The fastboot client is +part of the Android SDK Platform-Tools and can be downloaded from: + +https://developer.android.com/studio/releases/platform-tools
Board specific ============== + +USB configuration +----------------- + The fastboot gadget relies on the USB download gadget, so the following options must be configured:
-CONFIG_USB_GADGET_DOWNLOAD -CONFIG_USB_GADGET_VENDOR_NUM -CONFIG_USB_GADGET_PRODUCT_NUM -CONFIG_USB_GADGET_MANUFACTURER +:: + + CONFIG_USB_GADGET_DOWNLOAD + CONFIG_USB_GADGET_VENDOR_NUM + CONFIG_USB_GADGET_PRODUCT_NUM + CONFIG_USB_GADGET_MANUFACTURER
-NOTE: The CONFIG_USB_GADGET_VENDOR_NUM must be one of the numbers supported by -the fastboot client. The list of vendor IDs supported can be found in the -fastboot client source code (fastboot.c) mentioned above. +NOTE: The ``CONFIG_USB_GADGET_VENDOR_NUM`` must be one of the numbers +supported by the fastboot client. The list of vendor IDs supported can +be found in the fastboot client source code.
-The fastboot function is enabled by defining CONFIG_USB_FUNCTION_FASTBOOT, -CONFIG_CMD_FASTBOOT and CONFIG_ANDROID_BOOT_IMAGE. +General configuration +---------------------
-The fastboot protocol requires a large memory buffer for downloads. This -buffer should be as large as possible for a platform. The location of the -buffer and size are set with CONFIG_FASTBOOT_BUF_ADDR and -CONFIG_FASTBOOT_BUF_SIZE. +The fastboot protocol requires a large memory buffer for +downloads. This buffer should be as large as possible for a +platform. The location of the buffer and size are set with +``CONFIG_FASTBOOT_BUF_ADDR`` and ``CONFIG_FASTBOOT_BUF_SIZE``. These +may be overridden on the fastboot command line using ``-l`` and +``-s``. + +Fastboot environment variables +============================== + +Partition aliases +-----------------
Fastboot partition aliases can also be defined for devices where GPT limitations prevent user-friendly partition names such as "boot", "system" and "cache". Or, where the actual partition name doesn't match a standard -partition name used commonly with fastboot. Current implentation checks -aliases when accessing partitions by name (flash_write and erase functions). -To define a partition alias add an environment variable similar to: -fastboot_partition_alias_<alias partition name>=<actual partition name> -Example: fastboot_partition_alias_boot=LNX +partition name used commonly with fastboot. + +The current implementation checks aliases when accessing partitions by +name (flash_write and erase functions). To define a partition alias +add an environment variable similar to: + +``fastboot_partition_alias_<alias partition name>=<actual partition name>`` + +for example: + +``fastboot_partition_alias_boot=LNX`` + +Variable overrides +------------------ + +Variables retrived through ``getvar`` can be overridden by defining +environment variables of the form ``fastboot.<variable>``. These are +looked up first so can be used to override values which would +otherwise be returned. Using this mechanism you can also return types +for NAND filesystems, as the fully parameterised variable is looked +up, e.g. + +``fastboot.partition-type:boot=jffs2`` + +Boot command +------------ + +When executing the fastboot ``boot`` command, if ``fastboot_bootcmd`` is set then +that will be executed in place of ``bootm <CONFIG_FASTBOOT_BUF_ADDR>``.
Partition Names =============== -The Fastboot implementation in U-boot allows to write images into disk -partitions (currently on eMMC). Target partitions are referred on the host -computer by their names. + +The Fastboot implementation in U-Boot allows to write images into disk +partitions. Target partitions are referred on the host computer by +their names.
For GPT/EFI the respective partition name is used.
For MBR the partitions are referred by generic names according to the following schema:
- <device type> <device index letter> <partition index> + <device type><device index letter><partition index>
-Example: hda3, sdb1, usbda1 +Example: ``hda3``, ``sdb1``, ``usbda1``
The device type is as follows:
- * IDE, ATAPI and SATA disks: hd - * SCSI disks: sd - * USB media: usbd - * MMC and SD cards: mmcsd - * Disk on chip: docd - * other: xx + * IDE, ATAPI and SATA disks: ``hd`` + * SCSI disks: ``sd`` + * USB media: ``usbd`` + * MMC and SD cards: ``mmcsd`` + * Disk on chip: ``docd`` + * other: ``xx``
-The device index starts from 'a' and refers to the interface (e.g. USB +The device index starts from ``a`` and refers to the interface (e.g. USB controller, SD/MMC controller) or disk index. The partition index starts -from 1 and describes the partition number on the particular device. +from ``1`` and describes the partition number on the particular device.
Writing Partition Table ======================= + Fastboot also allows to write the partition table to the media. This can be done by writing the respective partition table image to a special target "gpt" or "mbr". These names can be customized by defining the following configuration options:
-CONFIG_FASTBOOT_GPT_NAME -CONFIG_FASTBOOT_MBR_NAME +:: + + CONFIG_FASTBOOT_GPT_NAME + CONFIG_FASTBOOT_MBR_NAME
In Action ========= -Enter into fastboot by executing the fastboot command in u-boot and you -should see: -|GADGET DRIVER: usb_dnl_fastboot + +Enter into fastboot by executing the fastboot command in U-Boot for either USB: + +:: + + => fastboot usb 0 + +or UDP: + +:: + + => fastboot udp + link up on port 0, speed 100, full duplex + Using ethernet@4a100000 device + Listening for fastboot command on 192.168.0.102
On the client side you can fetch the bootloader version for instance: -|>fastboot getvar bootloader-version -|bootloader-version: U-Boot 2014.04-00005-gd24cabc -|finished. total time: 0.000s + +:: + + $ fastboot getvar bootloader-version + bootloader-version: U-Boot 2014.04-00005-gd24cabc + finished. total time: 0.000s
or initiate a reboot: -|>fastboot reboot + +:: + + $ fastboot reboot
and once the client comes back, the board should reset.
You can also specify a kernel image to boot. You have to either specify -the an image in Android format _or_ pass a binary kernel and let the +the an image in Android format *or* pass a binary kernel and let the fastboot client wrap the Android suite around it. On OMAP for instance you take zImage kernel and pass it to the fastboot client:
-|>fastboot -b 0x80000000 -c "console=ttyO2 earlyprintk root=/dev/ram0 -| mem=128M" boot zImage -|creating boot image... -|creating boot image - 1847296 bytes -|downloading 'boot.img'... -|OKAY [ 2.766s] -|booting... -|OKAY [ -0.000s] -|finished. total time: 2.766s - -and on the gadget side you should see: -|Starting download of 1847296 bytes -|........................................................ -|downloading of 1847296 bytes finished -|Booting kernel.. -|## Booting Android Image at 0x81000000 ... -|Kernel load addr 0x80008000 size 1801 KiB -|Kernel command line: console=ttyO2 earlyprintk root=/dev/ram0 mem=128M -| Loading Kernel Image ... OK -|OK -| -|Starting kernel ... +:: + + $ fastboot -b 0x80000000 -c "console=ttyO2 earlyprintk root=/dev/ram0 mem=128M" boot zImage + creating boot image... + creating boot image - 1847296 bytes + downloading 'boot.img'... + OKAY [ 2.766s] + booting... + OKAY [ -0.000s] + finished. total time: 2.766s + +and on the U-Boot side you should see: + +:: + + Starting download of 1847296 bytes + ........................................................ + downloading of 1847296 bytes finished + Booting kernel.. + ## Booting Android Image at 0x81000000 ... + Kernel load addr 0x80008000 size 1801 KiB + Kernel command line: console=ttyO2 earlyprintk root=/dev/ram0 mem=128M + Loading Kernel Image ... OK + OK + + Starting kernel ...