Commit 3aab70af authored by Sebastian Siewior's avatar Sebastian Siewior Committed by Lukasz Majewski

usb/gadget: add the fastboot gadget

This patch contains an implementation of the fastboot protocol on the
device side and documentation. This is based on USB download gadget
infrastructure. The fastboot function implements the getvar, reboot,
download and reboot commands. What is missing is the flash handling i.e.
writting the image to media.

v3 (Rob Herring):
This is based on with the
following changes:
- Rebase to current mainline and updates for current gadget API
- Use SPDX identifiers for licenses
- Traced the history and added missing copyright to cmd_fastboot.c
- Use load_addr/load_size for transfer buffer
- Allow vendor strings to be optional
- Set vendor/product ID from config defines
- Allow Ctrl-C to exit fastboot mode
- Major re-write to use the USB download gadget. Consolidated function
code to a single file.
- Moved globals into single struct.
- Use puts and putc as appropriate.
set the fastboot transfer buffer.
- Add CONFIG option documentation to README
- Rebase using new downloader registration
Signed-off-by: default avatarSebastian Andrzej Siewior <>
Signed-off-by: default avatarRob Herring <>
parent 9ace3fc8
......@@ -1558,6 +1558,28 @@ The following options need to be configured:
entering dfuMANIFEST state. Host waits this timeout, before
sending again an USB request to the device.
- USB Device Android Fastboot support:
This enables the command "fastboot" which enables the Android
fastboot mode for the platform's USB device. Fastboot is a USB
protocol for downloading images, flashing and device control
used on Android devices.
See doc/ for more information.
This enables support for booting images which use the Android
image format header.
The fastboot protocol requires a large memory buffer for
downloads. Define this to the starting RAM address to use for
downloaded images.
The fastboot protocol requires a large memory buffer for
downloads. This buffer should be as large as possible for a
platform. Define this to the size available RAM for fastboot.
- Journaling Flash filesystem support:
......@@ -168,6 +168,8 @@ obj-y += cmd_usb.o
obj-y += usb.o usb_hub.o
obj-$(CONFIG_USB_STORAGE) += usb_storage.o
obj-$(CONFIG_CMD_FASTBOOT) += cmd_fastboot.o
obj-$(CONFIG_CMD_USB_MASS_STORAGE) += cmd_usb_mass_storage.o
obj-$(CONFIG_CMD_THOR_DOWNLOAD) += cmd_thordown.o
obj-$(CONFIG_CMD_XIMG) += cmd_ximg.o
* Copyright 2008 - 2009 Windriver, <>
* Author: Tom Rix <>
* (C) Copyright 2014 Linaro, Ltd.
* Rob Herring <>
* SPDX-License-Identifier: GPL-2.0+
#include <common.h>
#include <command.h>
#include <g_dnl.h>
static int do_fastboot(cmd_tbl_t *cmdtp, int flag, int argc, char *const argv[])
int ret;
ret = g_dnl_register("usb_dnl_fastboot");
if (ret)
return ret;
while (1) {
if (ctrlc())
fastboot, 1, 1, do_fastboot,
"fastboot - enter USB Fastboot protocol",
Android Fastboot
The protocol that is used over USB is described in in same directory.
The current implementation does not yet support the flash and erase
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 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
Board specific
The fastboot gadget relies on the USB download gadget, so the following
options must be configured:
The fastboot function is enabled by defining CONFIG_CMD_FASTBOOT and
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_USB_FASTBOOT_BUF_ADDR and
In Action
Enter into fastboot by executing the fastboot command in u-boot and you
should see:
|GADGET DRIVER: usb_dnl_fastboot
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
or initiate a 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
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]
|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
|Starting kernel ...
FastBoot Version 0.4
The fastboot protocol is a mechanism for communicating with bootloaders
over USB. It is designed to be very straightforward to implement, to
allow it to be used across a wide range of devices and from hosts running
Linux, Windows, or OSX.
Basic Requirements
* Two bulk endpoints (in, out) are required
* Max packet size must be 64 bytes for full-speed and 512 bytes for
high-speed USB
* The protocol is entirely host-driven and synchronous (unlike the
multi-channel, bi-directional, asynchronous ADB protocol)
Transport and Framing
1. Host sends a command, which is an ascii string in a single
packet no greater than 64 bytes.
2. Client response with a single packet no greater than 64 bytes.
The first four bytes of the response are "OKAY", "FAIL", "DATA",
or "INFO". Additional bytes may contain an (ascii) informative
a. INFO -> the remaining 60 bytes are an informative message
(providing progress or diagnostic messages). They should
be displayed and then step #2 repeats
b. FAIL -> the requested command failed. The remaining 60 bytes
of the response (if present) provide a textual failure message
to present to the user. Stop.
c. OKAY -> the requested command completed successfully. Go to #5
d. DATA -> the requested command is ready for the data phase.
A DATA response packet will be 12 bytes long, in the form of
DATA00000000 where the 8 digit hexidecimal number represents
the total data size to transfer.
3. Data phase. Depending on the command, the host or client will
send the indicated amount of data. Short packets are always
acceptable and zero-length packets are ignored. This phase continues
until the client has sent or received the number of bytes indicated
in the "DATA" response above.
4. Client responds with a single packet no greater than 64 bytes.
The first four bytes of the response are "OKAY", "FAIL", or "INFO".
Similar to #2:
a. INFO -> display the remaining 60 bytes and return to #4
b. FAIL -> display the remaining 60 bytes (if present) as a failure
reason and consider the command failed. Stop.
c. OKAY -> success. Go to #5
5. Success. Stop.
Example Session
Host: "getvar:version" request version variable
Client: "OKAY0.4" return version "0.4"
Host: "getvar:nonexistant" request some undefined variable
Client: "OKAY" return value ""
Host: "download:00001234" request to send 0x1234 bytes of data
Client: "DATA00001234" ready to accept data
Host: < 0x1234 bytes > send data
Client: "OKAY" success
Host: "flash:bootloader" request to flash the data to the bootloader
Client: "INFOerasing flash" indicate status / progress
"INFOwriting flash"
"OKAY" indicate success
Host: "powerdown" send a command
Client: "FAILunknown command" indicate failure
Command Reference
* Command parameters are indicated by printf-style escape sequences.
* Commands are ascii strings and sent without the quotes (which are
for illustration only here) and without a trailing 0 byte.
* Commands that begin with a lowercase letter are reserved for this
specification. OEM-specific commands should not begin with a
lowercase letter, to prevent incompatibilities with future specs.
"getvar:%s" Read a config/version variable from the bootloader.
The variable contents will be returned after the
OKAY response.
"download:%08x" Write data to memory which will be later used
by "boot", "ramdisk", "flash", etc. The client
will reply with "DATA%08x" if it has enough
space in RAM or "FAIL" if not. The size of
the download is remembered.
"verify:%08x" Send a digital signature to verify the downloaded
data. Required if the bootloader is "secure"
otherwise "flash" and "boot" will be ignored.
"flash:%s" Write the previously downloaded image to the
named partition (if possible).
"erase:%s" Erase the indicated partition (clear to 0xFFs)
"boot" The previously downloaded data is a boot.img
and should be booted according to the normal
procedure for a boot.img
"continue" Continue booting as normal (if possible)
"reboot" Reboot the device.
"reboot-bootloader" Reboot back into the bootloader.
Useful for upgrade processes that require upgrading
the bootloader and then upgrading other partitions
using the new bootloader.
"powerdown" Power off the device.
Client Variables
The "getvar:%s" command is used to read client variables which
represent various information about the device and the software
on it.
The various currently defined names are:
version Version of FastBoot protocol supported.
It should be "0.3" for this document.
version-bootloader Version string for the Bootloader.
version-baseband Version string of the Baseband Software
product Name of the product
serialno Product serial number
secure If the value is "yes", this is a secure
bootloader requiring a signature before
it will install or boot images.
Names starting with a lowercase character are reserved by this
specification. OEM-specific names should not start with lowercase
......@@ -18,6 +18,7 @@ obj-$(CONFIG_THOR_FUNCTION) += f_thor.o
obj-$(CONFIG_DFU_FUNCTION) += f_dfu.o
obj-$(CONFIG_USB_GADGET_MASS_STORAGE) += f_mass_storage.o
obj-$(CONFIG_CMD_FASTBOOT) += f_fastboot.o
obj-y += ether.o
* (C) Copyright 2008 - 2009
* Windriver, <>
* Tom Rix <>
* Copyright 2011 Sebastian Andrzej Siewior <>
* Copyright 2014 Linaro, Ltd.
* Rob Herring <>
* SPDX-License-Identifier: GPL-2.0+
#include <common.h>
#include <errno.h>
#include <malloc.h>
#include <linux/usb/ch9.h>
#include <linux/usb/gadget.h>
#include <linux/usb/composite.h>
#include <linux/compiler.h>
#include <version.h>
#include <g_dnl.h>
#define FASTBOOT_VERSION "0.4"
/* The 64 defined bytes plus \0 */
#define RESPONSE_LEN (64 + 1)
#define EP_BUFFER_SIZE 4096
struct f_fastboot {
struct usb_function usb_function;
/* IN/OUT EP's and correspoinding requests */
struct usb_ep *in_ep, *out_ep;
struct usb_request *in_req, *out_req;
static inline struct f_fastboot *func_to_fastboot(struct usb_function *f)
return container_of(f, struct f_fastboot, usb_function);
static struct f_fastboot *fastboot_func;
static unsigned int download_size;
static unsigned int download_bytes;
static struct usb_endpoint_descriptor fs_ep_in = {
.bDescriptorType = USB_DT_ENDPOINT,
.bEndpointAddress = USB_DIR_IN,
.bInterval = 0x00,
static struct usb_endpoint_descriptor fs_ep_out = {
.bDescriptorType = USB_DT_ENDPOINT,
.bEndpointAddress = USB_DIR_OUT,
.bInterval = 0x00,
static struct usb_endpoint_descriptor hs_ep_out = {
.bDescriptorType = USB_DT_ENDPOINT,
.bEndpointAddress = USB_DIR_OUT,
.bInterval = 0x00,
static struct usb_interface_descriptor interface_desc = {
.bDescriptorType = USB_DT_INTERFACE,
.bInterfaceNumber = 0x00,
.bAlternateSetting = 0x00,
.bNumEndpoints = 0x02,
static struct usb_descriptor_header *fb_runtime_descs[] = {
(struct usb_descriptor_header *)&interface_desc,
(struct usb_descriptor_header *)&fs_ep_in,
(struct usb_descriptor_header *)&hs_ep_out,
* static strings, in UTF-8
static const char fastboot_name[] = "Android Fastboot";
static struct usb_string fastboot_string_defs[] = {
[0].s = fastboot_name,
{ } /* end of list */
static struct usb_gadget_strings stringtab_fastboot = {
.language = 0x0409, /* en-us */
.strings = fastboot_string_defs,
static struct usb_gadget_strings *fastboot_strings[] = {
static void rx_handler_command(struct usb_ep *ep, struct usb_request *req);
static void fastboot_complete(struct usb_ep *ep, struct usb_request *req)
int status = req->status;
if (!status)
printf("status: %d ep '%s' trans: %d\n", status, ep->name, req->actual);
static int fastboot_bind(struct usb_configuration *c, struct usb_function *f)
int id;
struct usb_gadget *gadget = c->cdev->gadget;
struct f_fastboot *f_fb = func_to_fastboot(f);
/* DYNAMIC interface numbers assignments */
id = usb_interface_id(c, f);
if (id < 0)
return id;
interface_desc.bInterfaceNumber = id;
id = usb_string_id(c->cdev);
if (id < 0)
return id;
fastboot_string_defs[0].id = id;
interface_desc.iInterface = id;
f_fb->in_ep = usb_ep_autoconfig(gadget, &fs_ep_in);
if (!f_fb->in_ep)
return -ENODEV;
f_fb->in_ep->driver_data = c->cdev;
f_fb->out_ep = usb_ep_autoconfig(gadget, &fs_ep_out);
if (!f_fb->out_ep)
return -ENODEV;
f_fb->out_ep->driver_data = c->cdev;
hs_ep_out.bEndpointAddress = fs_ep_out.bEndpointAddress;
return 0;
static void fastboot_unbind(struct usb_configuration *c, struct usb_function *f)
memset(fastboot_func, 0, sizeof(*fastboot_func));
static void fastboot_disable(struct usb_function *f)
struct f_fastboot *f_fb = func_to_fastboot(f);
if (f_fb->out_req) {
usb_ep_free_request(f_fb->out_ep, f_fb->out_req);
f_fb->out_req = NULL;
if (f_fb->in_req) {
usb_ep_free_request(f_fb->in_ep, f_fb->in_req);
f_fb->in_req = NULL;
static struct usb_request *fastboot_start_ep(struct usb_ep *ep)
struct usb_request *req;
req = usb_ep_alloc_request(ep, 0);
if (!req)
return NULL;
req->length = EP_BUFFER_SIZE;
if (!req->buf) {
usb_ep_free_request(ep, req);
return NULL;
memset(req->buf, 0, req->length);
return req;
static int fastboot_set_alt(struct usb_function *f,
unsigned interface, unsigned alt)
int ret;
struct usb_composite_dev *cdev = f->config->cdev;
struct usb_gadget *gadget = cdev->gadget;
struct f_fastboot *f_fb = func_to_fastboot(f);
debug("%s: func: %s intf: %d alt: %d\n",
__func__, f->name, interface, alt);
/* make sure we don't enable the ep twice */
if (gadget->speed == USB_SPEED_HIGH)
ret = usb_ep_enable(f_fb->out_ep, &hs_ep_out);
ret = usb_ep_enable(f_fb->out_ep, &fs_ep_out);
if (ret) {
puts("failed to enable out ep\n");
return ret;
f_fb->out_req = fastboot_start_ep(f_fb->out_ep);
if (!f_fb->out_req) {
puts("failed to alloc out req\n");
ret = -EINVAL;
goto err;
f_fb->out_req->complete = rx_handler_command;
ret = usb_ep_enable(f_fb->in_ep, &fs_ep_in);
if (ret) {
puts("failed to enable in ep\n");
goto err;
f_fb->in_req = fastboot_start_ep(f_fb->in_ep);
if (!f_fb->in_req) {
puts("failed alloc req in\n");
ret = -EINVAL;
goto err;
f_fb->in_req->complete = fastboot_complete;
ret = usb_ep_queue(f_fb->out_ep, f_fb->out_req, 0);
if (ret)
goto err;
return 0;
return ret;
static int fastboot_add(struct usb_configuration *c)
struct f_fastboot *f_fb = fastboot_func;
int status;
debug("%s: cdev: 0x%p\n", __func__, c->cdev);
if (!f_fb) {
f_fb = memalign(CONFIG_SYS_CACHELINE_SIZE, sizeof(*f_fb));
if (!f_fb)
return -ENOMEM;
fastboot_func = f_fb;
memset(f_fb, 0, sizeof(*f_fb));
f_fb-> = "f_fastboot";
f_fb->usb_function.hs_descriptors = fb_runtime_descs;
f_fb->usb_function.bind = fastboot_bind;
f_fb->usb_function.unbind = fastboot_unbind;
f_fb->usb_function.set_alt = fastboot_set_alt;
f_fb->usb_function.disable = fastboot_disable;
f_fb->usb_function.strings = fastboot_strings;
status = usb_add_function(c, &f_fb->usb_function);
if (status) {
fastboot_func = f_fb;