Alex Kiernan | a59e913 | 2018-05-29 15:30:56 +0000 | [diff] [blame] | 1 | ================ |
Sebastian Siewior | 9d4471e | 2014-05-05 15:08:10 -0500 | [diff] [blame] | 2 | Android Fastboot |
Alex Kiernan | a59e913 | 2018-05-29 15:30:56 +0000 | [diff] [blame] | 3 | ================ |
Sebastian Siewior | 9d4471e | 2014-05-05 15:08:10 -0500 | [diff] [blame] | 4 | |
| 5 | Overview |
| 6 | ======== |
Sebastian Siewior | 9d4471e | 2014-05-05 15:08:10 -0500 | [diff] [blame] | 7 | |
Alex Kiernan | a59e913 | 2018-05-29 15:30:56 +0000 | [diff] [blame] | 8 | The protocol that is used over USB and UDP is described in the |
| 9 | ``README.android-fastboot-protocol`` file in the same directory. |
| 10 | |
| 11 | The current implementation supports the following standard commands: |
| 12 | |
| 13 | - ``boot`` |
| 14 | - ``continue`` |
| 15 | - ``download`` |
| 16 | - ``erase`` (if enabled) |
| 17 | - ``flash`` (if enabled) |
| 18 | - ``getvar`` |
| 19 | - ``reboot`` |
| 20 | - ``reboot-bootloader`` |
| 21 | - ``set_active`` (only a stub implementation which always succeeds) |
| 22 | |
| 23 | The following OEM commands are supported (if enabled): |
| 24 | |
| 25 | - oem format - this executes ``gpt write mmc %x $partitions`` |
| 26 | |
| 27 | Support for both eMMC and NAND devices is included. |
Sebastian Siewior | 9d4471e | 2014-05-05 15:08:10 -0500 | [diff] [blame] | 28 | |
| 29 | Client installation |
| 30 | =================== |
Sebastian Siewior | 9d4471e | 2014-05-05 15:08:10 -0500 | [diff] [blame] | 31 | |
Alex Kiernan | a59e913 | 2018-05-29 15:30:56 +0000 | [diff] [blame] | 32 | The counterpart to this is the fastboot client which can be found in |
| 33 | Android's ``platform/system/core`` repository in the fastboot |
| 34 | folder. It runs on Windows, Linux and OSX. The fastboot client is |
| 35 | part of the Android SDK Platform-Tools and can be downloaded from: |
Sebastian Siewior | 9d4471e | 2014-05-05 15:08:10 -0500 | [diff] [blame] | 36 | |
Alex Kiernan | a59e913 | 2018-05-29 15:30:56 +0000 | [diff] [blame] | 37 | https://developer.android.com/studio/releases/platform-tools |
Sebastian Siewior | 9d4471e | 2014-05-05 15:08:10 -0500 | [diff] [blame] | 38 | |
| 39 | Board specific |
| 40 | ============== |
Alex Kiernan | a59e913 | 2018-05-29 15:30:56 +0000 | [diff] [blame] | 41 | |
| 42 | USB configuration |
| 43 | ----------------- |
| 44 | |
Sebastian Siewior | 9d4471e | 2014-05-05 15:08:10 -0500 | [diff] [blame] | 45 | The fastboot gadget relies on the USB download gadget, so the following |
| 46 | options must be configured: |
| 47 | |
Alex Kiernan | a59e913 | 2018-05-29 15:30:56 +0000 | [diff] [blame] | 48 | :: |
| 49 | |
| 50 | CONFIG_USB_GADGET_DOWNLOAD |
| 51 | CONFIG_USB_GADGET_VENDOR_NUM |
| 52 | CONFIG_USB_GADGET_PRODUCT_NUM |
| 53 | CONFIG_USB_GADGET_MANUFACTURER |
| 54 | |
| 55 | NOTE: The ``CONFIG_USB_GADGET_VENDOR_NUM`` must be one of the numbers |
| 56 | supported by the fastboot client. The list of vendor IDs supported can |
| 57 | be found in the fastboot client source code. |
Sebastian Siewior | 9d4471e | 2014-05-05 15:08:10 -0500 | [diff] [blame] | 58 | |
Alex Kiernan | a59e913 | 2018-05-29 15:30:56 +0000 | [diff] [blame] | 59 | General configuration |
| 60 | --------------------- |
Barnes, Clifton A | 1f9f321 | 2014-07-22 11:23:56 -0400 | [diff] [blame] | 61 | |
Alex Kiernan | a59e913 | 2018-05-29 15:30:56 +0000 | [diff] [blame] | 62 | The fastboot protocol requires a large memory buffer for |
| 63 | downloads. This buffer should be as large as possible for a |
| 64 | platform. The location of the buffer and size are set with |
| 65 | ``CONFIG_FASTBOOT_BUF_ADDR`` and ``CONFIG_FASTBOOT_BUF_SIZE``. These |
| 66 | may be overridden on the fastboot command line using ``-l`` and |
| 67 | ``-s``. |
Sebastian Siewior | 9d4471e | 2014-05-05 15:08:10 -0500 | [diff] [blame] | 68 | |
Alex Kiernan | a59e913 | 2018-05-29 15:30:56 +0000 | [diff] [blame] | 69 | Fastboot environment variables |
| 70 | ============================== |
| 71 | |
| 72 | Partition aliases |
| 73 | ----------------- |
Sebastian Siewior | 9d4471e | 2014-05-05 15:08:10 -0500 | [diff] [blame] | 74 | |
Michael Scott | ced3349 | 2015-03-11 10:02:31 -0700 | [diff] [blame] | 75 | Fastboot partition aliases can also be defined for devices where GPT |
| 76 | limitations prevent user-friendly partition names such as "boot", "system" |
| 77 | and "cache". Or, where the actual partition name doesn't match a standard |
Alex Kiernan | a59e913 | 2018-05-29 15:30:56 +0000 | [diff] [blame] | 78 | partition name used commonly with fastboot. |
| 79 | |
| 80 | The current implementation checks aliases when accessing partitions by |
| 81 | name (flash_write and erase functions). To define a partition alias |
| 82 | add an environment variable similar to: |
| 83 | |
| 84 | ``fastboot_partition_alias_<alias partition name>=<actual partition name>`` |
| 85 | |
| 86 | for example: |
| 87 | |
| 88 | ``fastboot_partition_alias_boot=LNX`` |
| 89 | |
| 90 | Variable overrides |
| 91 | ------------------ |
| 92 | |
| 93 | Variables retrived through ``getvar`` can be overridden by defining |
| 94 | environment variables of the form ``fastboot.<variable>``. These are |
| 95 | looked up first so can be used to override values which would |
| 96 | otherwise be returned. Using this mechanism you can also return types |
| 97 | for NAND filesystems, as the fully parameterised variable is looked |
| 98 | up, e.g. |
| 99 | |
| 100 | ``fastboot.partition-type:boot=jffs2`` |
| 101 | |
| 102 | Boot command |
| 103 | ------------ |
| 104 | |
| 105 | When executing the fastboot ``boot`` command, if ``fastboot_bootcmd`` is set then |
| 106 | that will be executed in place of ``bootm <CONFIG_FASTBOOT_BUF_ADDR>``. |
Michael Scott | ced3349 | 2015-03-11 10:02:31 -0700 | [diff] [blame] | 107 | |
Petr Kulhavy | 9f174c9 | 2016-09-09 10:27:16 +0200 | [diff] [blame] | 108 | Partition Names |
| 109 | =============== |
Alex Kiernan | a59e913 | 2018-05-29 15:30:56 +0000 | [diff] [blame] | 110 | |
| 111 | The Fastboot implementation in U-Boot allows to write images into disk |
| 112 | partitions. Target partitions are referred on the host computer by |
| 113 | their names. |
Petr Kulhavy | 9f174c9 | 2016-09-09 10:27:16 +0200 | [diff] [blame] | 114 | |
| 115 | For GPT/EFI the respective partition name is used. |
| 116 | |
| 117 | For MBR the partitions are referred by generic names according to the |
| 118 | following schema: |
| 119 | |
Alex Kiernan | a59e913 | 2018-05-29 15:30:56 +0000 | [diff] [blame] | 120 | <device type><device index letter><partition index> |
Petr Kulhavy | 9f174c9 | 2016-09-09 10:27:16 +0200 | [diff] [blame] | 121 | |
Alex Kiernan | a59e913 | 2018-05-29 15:30:56 +0000 | [diff] [blame] | 122 | Example: ``hda3``, ``sdb1``, ``usbda1`` |
Petr Kulhavy | 9f174c9 | 2016-09-09 10:27:16 +0200 | [diff] [blame] | 123 | |
| 124 | The device type is as follows: |
| 125 | |
Alex Kiernan | a59e913 | 2018-05-29 15:30:56 +0000 | [diff] [blame] | 126 | * IDE, ATAPI and SATA disks: ``hd`` |
| 127 | * SCSI disks: ``sd`` |
| 128 | * USB media: ``usbd`` |
| 129 | * MMC and SD cards: ``mmcsd`` |
| 130 | * Disk on chip: ``docd`` |
| 131 | * other: ``xx`` |
Petr Kulhavy | 9f174c9 | 2016-09-09 10:27:16 +0200 | [diff] [blame] | 132 | |
Alex Kiernan | a59e913 | 2018-05-29 15:30:56 +0000 | [diff] [blame] | 133 | The device index starts from ``a`` and refers to the interface (e.g. USB |
Petr Kulhavy | 9f174c9 | 2016-09-09 10:27:16 +0200 | [diff] [blame] | 134 | controller, SD/MMC controller) or disk index. The partition index starts |
Alex Kiernan | a59e913 | 2018-05-29 15:30:56 +0000 | [diff] [blame] | 135 | from ``1`` and describes the partition number on the particular device. |
Petr Kulhavy | 9f174c9 | 2016-09-09 10:27:16 +0200 | [diff] [blame] | 136 | |
| 137 | Writing Partition Table |
| 138 | ======================= |
Alex Kiernan | a59e913 | 2018-05-29 15:30:56 +0000 | [diff] [blame] | 139 | |
Petr Kulhavy | 9f174c9 | 2016-09-09 10:27:16 +0200 | [diff] [blame] | 140 | Fastboot also allows to write the partition table to the media. This can be |
| 141 | done by writing the respective partition table image to a special target |
| 142 | "gpt" or "mbr". These names can be customized by defining the following |
| 143 | configuration options: |
| 144 | |
Alex Kiernan | a59e913 | 2018-05-29 15:30:56 +0000 | [diff] [blame] | 145 | :: |
| 146 | |
| 147 | CONFIG_FASTBOOT_GPT_NAME |
| 148 | CONFIG_FASTBOOT_MBR_NAME |
Petr Kulhavy | 9f174c9 | 2016-09-09 10:27:16 +0200 | [diff] [blame] | 149 | |
Sebastian Siewior | 9d4471e | 2014-05-05 15:08:10 -0500 | [diff] [blame] | 150 | In Action |
| 151 | ========= |
Alex Kiernan | a59e913 | 2018-05-29 15:30:56 +0000 | [diff] [blame] | 152 | |
| 153 | Enter into fastboot by executing the fastboot command in U-Boot for either USB: |
| 154 | |
| 155 | :: |
| 156 | |
| 157 | => fastboot usb 0 |
| 158 | |
| 159 | or UDP: |
| 160 | |
| 161 | :: |
| 162 | |
| 163 | => fastboot udp |
| 164 | link up on port 0, speed 100, full duplex |
| 165 | Using ethernet@4a100000 device |
| 166 | Listening for fastboot command on 192.168.0.102 |
Sebastian Siewior | 9d4471e | 2014-05-05 15:08:10 -0500 | [diff] [blame] | 167 | |
| 168 | On the client side you can fetch the bootloader version for instance: |
Alex Kiernan | a59e913 | 2018-05-29 15:30:56 +0000 | [diff] [blame] | 169 | |
| 170 | :: |
| 171 | |
| 172 | $ fastboot getvar bootloader-version |
| 173 | bootloader-version: U-Boot 2014.04-00005-gd24cabc |
| 174 | finished. total time: 0.000s |
Sebastian Siewior | 9d4471e | 2014-05-05 15:08:10 -0500 | [diff] [blame] | 175 | |
| 176 | or initiate a reboot: |
Alex Kiernan | a59e913 | 2018-05-29 15:30:56 +0000 | [diff] [blame] | 177 | |
| 178 | :: |
| 179 | |
| 180 | $ fastboot reboot |
Sebastian Siewior | 9d4471e | 2014-05-05 15:08:10 -0500 | [diff] [blame] | 181 | |
| 182 | and once the client comes back, the board should reset. |
| 183 | |
| 184 | You can also specify a kernel image to boot. You have to either specify |
Alex Kiernan | a59e913 | 2018-05-29 15:30:56 +0000 | [diff] [blame] | 185 | the an image in Android format *or* pass a binary kernel and let the |
Sebastian Siewior | 9d4471e | 2014-05-05 15:08:10 -0500 | [diff] [blame] | 186 | fastboot client wrap the Android suite around it. On OMAP for instance you |
| 187 | take zImage kernel and pass it to the fastboot client: |
| 188 | |
Alex Kiernan | a59e913 | 2018-05-29 15:30:56 +0000 | [diff] [blame] | 189 | :: |
| 190 | |
| 191 | $ fastboot -b 0x80000000 -c "console=ttyO2 earlyprintk root=/dev/ram0 mem=128M" boot zImage |
| 192 | creating boot image... |
| 193 | creating boot image - 1847296 bytes |
| 194 | downloading 'boot.img'... |
| 195 | OKAY [ 2.766s] |
| 196 | booting... |
| 197 | OKAY [ -0.000s] |
| 198 | finished. total time: 2.766s |
| 199 | |
| 200 | and on the U-Boot side you should see: |
| 201 | |
| 202 | :: |
| 203 | |
| 204 | Starting download of 1847296 bytes |
| 205 | ........................................................ |
| 206 | downloading of 1847296 bytes finished |
| 207 | Booting kernel.. |
| 208 | ## Booting Android Image at 0x81000000 ... |
| 209 | Kernel load addr 0x80008000 size 1801 KiB |
| 210 | Kernel command line: console=ttyO2 earlyprintk root=/dev/ram0 mem=128M |
| 211 | Loading Kernel Image ... OK |
| 212 | OK |
Sebastian Siewior | 9d4471e | 2014-05-05 15:08:10 -0500 | [diff] [blame] | 213 | |
Alex Kiernan | a59e913 | 2018-05-29 15:30:56 +0000 | [diff] [blame] | 214 | Starting kernel ... |