1# Fastboot in GBL 2 3This document describes Fastboot in the [GBL UEFI bootloader](../efi/BUILD). 4 5## Transport 6 7The GBL UEFI bootloader supports both Fastboot over TCP and USB. To enable 8Fastboot over TCP, the UEFI loader needs to implement the 9`EFI_SIMPLE_NETWORK_PROTOCOL` protocol. To enable Fastboot over USB, the 10[GBL_EFI_FASTBOOT_USB_PROTOCOL](./GBL_EFI_FASTBOOT_USB_PROTOCOL.md) protocol is 11needed. GBL automatically establishes the corresponding transport channel if 12the needed protocol is available. 13 14## The Partition Argument 15 16Fastboot commands such as `fastboot flash`, `fastboot fetch` and 17`fastboot getvar partition-size` operate on partitions and requires a partition 18name argument. See this [doc](./partitions.md) for how GBL defines and handles 19partitions on storage devices. GBL fastboot additionaly supports accessing sub 20ranges of partitions and disambiguating betweeen same name partitions on 21multiple storage devices (i.e. in the presence of external or removable boot 22storage). The following summarizes the supported syntaxes for partition name 23argument in fastboot. 24 25* Partition 26 ```sh 27 <part>[/<storage_id>] 28 <part>/[<storage_id>][/<offset>] 29 <part>/[<storage_id>]/[<offset>][/<size>] 30 ``` 31 32 This specifies range `[offset, offset+size)` in partition `part` on the 33 storage device with ID `storage_id`. `storage_id` is a hex string and 34 represents a unique integer ID assigned to each storage device detected 35 by GBL. The integer ID is for disambiguation purpose in case multiple storage 36 devices have same name partitions. If `storage_id` is not given, GBL will 37 check if a default storage ID is set via 38 `fastboot oem gbl-set-default-block <storage_id>` and use the default ID if 39 set. If the default ID is not set, GBL will check that `part` can match to a 40 unique parition. Otherwise, it will be rejected. The default ID can be unset 41 via `fastboot oem gbl-unset-default-block`. `offset` and `size` must be a 42 64bit integer hex string. `offset` defaults to 0 if not given. `size` 43 defaults to the rest of the partition after `offset` if not given. 44 45 Examples: 46 * `fastboot flash boot_a` -- If there is only one storage or a default 47 storage ID is set via `fastboot oem gbl-set-default-block <default ID>`, 48 flashes in the entire range of the storage. If not, checks that `boot_a` 49 can match to a unique partition among all storage devices and flashes to 50 it. 51 * `fastboot flash boot_a/0x0` or `boot_a/0` -- Flashes in the entire range of 52 partition "boot_a" on storage device 0. 53 * `fastboot flash boot_a/0/200` -- Flashes only in range `[512, end)` of 54 partition "boot_a" on storage device 0. 55 * `fastboot flash boot_a/0/200/200` -- Flashes only in range `[512, 1024)` of 56 partition "boot_a" on storage device 0. 57 * `fastboot flash boot_a///` -- Same as `"fastboot flash boot_a"`. 58 * `fastboot flash boot_a//200/200` -- Same as `"fastboot flash boot_a///"`, 59 except that it only flashes in range `[512, 1024)` 60 61* Raw storage devices by ID 62 ``` 63 /[<storage_id>] 64 /[<storage_id>][/<offset>] 65 /[<storage_id>][/<offset>][/<size>] 66 ``` 67 68 This is similar to the case of partition except that `part` is an empty 69 string. It specifies range`[offset, offset+size)` of the raw data on the 70 storage device with ID `storage_id`. If `storage_id` is not given, GBL will 71 check if a default storage ID is set via 72 `fastboot oem gbl-set-default-block <storage_id>` and use the default ID if 73 set. Otherwise it is rejected. `offset` defaults to 0 if not given. `size` 74 defaults to the rest of the block after `offset` if not given. This semantic 75 applies to all storage devcies that can detected by GBL, whether or not it is 76 a raw storage partition or GPT device. 77 78 Examples: 79 * `fastboot flash /` -- If there is only one storage or a default storage ID 80 is set via `fastboot oem gbl-set-default-block <default ID>`, flashes in 81 the entire range of the storage. 82 * `fastboot flash /0x0` or `/0` -- Flashes in the entire range of storage 83 device 0. 84 * `fastboot flash /0/200` -- Flashes only in range `[512, end)` of storage 85 device 0. 86 * `fastboot flash /0/200/200` -- Flashes only in range `[512, 1024)` of 87 storage device 0. 88 * `fastboot flash ///` -- Same as `"fastboot flash /"`. 89 * `fastboot flash //200/200` -- Same as `"fastboot flash ///"`, except that 90 it only flashes in range `[512, 1024)` 91 92Note: AOSP fastboot client tool introduces a special flash command syntax 93`fastboot flash vendor_boot_a:<part_size>` for performing vendor ramdisk 94repacking and flashing. This however, does not work with GBL's `'/'` syntax 95discussed above, i.e. `fastboot flash vendor_boot_a/0:<part_size>` will not 96trigger the repack and flash flow for the vendor_boot_a partition on storage 0 97as might be expected. Instead, in this case, user should run 98`fastboot oem gbl-set-default-block 0` to set the default block to 0 first and 99then use `fastboot flash vendor_boot_a:<part size>` normally. 100 101### Updating GPT Partition Table 102 103GBL supports the following syntaxes for updating GPT partition table on a 104storage device: 105 106``` 107fastboot flash gpt <path to MBR+primary GPT blob file> 108fastboot flash gpt/<storage_id> <path to MBR+primary GPT blob file> 109fastboot flash gpt/[<storage_id>][/resize] <path to MBR+primary GPT blob file> 110``` 111 112User must provide an image file that contains a MBR block and the primary GPT 113header and entries. The above command will verify the given GPT and update it 114to the specified storage device. If the `resize` option is given, GBL will 115adjust the ending block of the last partition entry to cover the rest of the 116storage. This is useful for sharing one single GPT blob file for different 117devices with varying size of storage. 118 119Examples: 120 * `fastboot flash gpt` -- If there is only one storage or a default storage 121 ID is set via `fastboot oem gbl-set-default-block <default ID>`, updates 122 the GPT of that storage. 123 * `fastboot flash gpt//resize` -- Same as `fastboot flash gpt` but also 124 performs resizing. 125 * `fastboot flash gpt/0` -- Update GPT to storage device 0. 126 * `fastboot flash gpt/0/resize` -- Same as `fastboot flash gpt/0` but also 127 performs resizing. 128 129To erase existing GPT partition table on a storage device, use: 130 131``` 132fastboot erase gpt 133fastboot erase gpt/<storage_id> 134``` 135 136Note: The above only erases GPT partition table. Partition content remains 137unchanged. 138 139Examples: 140 * `fastboot erase gpt` -- If there is only one storage or a default storage 141 ID is set via `fastboot oem gbl-set-default-block <default ID>`, erase 142 the GPT of that storage. 143 * `fastboot flash gpt/0` -- Erase GPT to storage device 0. 144 145## Non-blocking `fastboot flash`. 146 147If the UEFI firmware supports `EFI_BLOCK_IO2_PROTOCOL` for the storage devices, 148GBL Fastboot provides an option to make `fastboot flash` non-blocking. 149Specifically, after the image is downloaded, GBL Fastboot will launch a 150separate task in the background for writing the image to the device, while 151itself will continue to listen for the next Fastboot command from the host, 152including a new `fastboot flash` command. This provides some paralellism 153between downloading and flashing when the host is flashing multiple images. 154Example: 155 156``` 157fastboot oem gbl-enable-async-task 158fastboot flash boot_a <image> 159fastboot flash boot_b <image> 160fastboot flash vendor_boot_a <image> 161... 162fastboot oem gbl-sync-blocks 163fastboot oem gbl-disable-async-task 164``` 165 166If a storage device is busy processing a previous flash when a new image is 167downloaded and ready to be flashed, it will be blocked until the previous flash 168is completed. Different storage devices are independent to each other. 169 170Because IO is now non-blocking, the return status of a `fastboot flash` does 171not necessarily represents the status of the IO. If a storage device encounters 172errors while processing a non-blocking IO, all subsequent flash requests will 173be rejected and the host should reboot the device. 174`fastboot oem gbl-sync-blocks` can be used to wait until all currently pending 175flash are completed. The command returns error if any previous or current flash 176encounters errors. 177