Eric Lee / smarc-uboot | Embedian Git Server

Commit 277b1333b780acd8ddb761c9160c06ffdf1c3901

Authored by Alex Kiernan 2018-05-29 23:30:56 +0800

Committed by Marek Vasut 2018-05-30 17:59:21 +0800

Exists in smarc_8mq_lf_v2020.04 and in 11 other branches

fastboot: Update fastboot documentation

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>

Showing 1 changed file with 156 additions and 84 deletions Side-by-side Diff

doc/README.android-fastboot

doc/README.android-fastboot

Diff comments View file @ 277b133

	1	+================
1	2	Android Fastboot
2		-~~~~~~~~~~~~~~~~
	3	+================
3	4
4	5	Overview
5	6	========
6		-The protocol that is used over USB is described in
7		-README.android-fastboot-protocol in same directory.
8	7
9		-The current implementation is a minimal support of the erase command,the
10		-"oem format" command and flash command;it only supports eMMC devices.
	8	+The protocol that is used over USB and UDP is described in the
	9	+``README.android-fastboot-protocol`` file in the same directory.
11	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.
	28	+
12	29	Client installation
13	30	===================
14		-The counterpart to this gadget is the fastboot client which can
15		-be found in Android's platform/system/core repository in the fastboot
16		-folder. It runs on Windows, Linux and even OSX. Linux user are lucky since
17		-they only need libusb.
18		-Windows users need to bring some time until they have Android SDK (currently
19		-http://dl.google.com/android/installer_r12-windows.exe) installed. You
20		-need to install ADB package which contains the required glue libraries for
21		-accessing USB. Also you need "Google USB driver package" and "SDK platform
22		-tools". Once installed the usb driver is placed in your SDK folder under
23		-extras\google\usb_driver. The android_winusb.inf needs a line like
24	31
25		- %SingleBootLoaderInterface% = USB_Install, USB\VID_0451&PID_D022
	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:
26	36
27		-either in the [Google.NTx86] section for 32bit Windows or [Google.NTamd64]
28		-for 64bit Windows. VID and PID should match whatever the fastboot is
29		-advertising.
	37	+https://developer.android.com/studio/releases/platform-tools
30	38
31	39	Board specific
32	40	==============
	41	+
	42	+USB configuration
	43	+-----------------
	44	+
33	45	The fastboot gadget relies on the USB download gadget, so the following
34	46	options must be configured:
35	47
36		-CONFIG_USB_GADGET_DOWNLOAD
37		-CONFIG_USB_GADGET_VENDOR_NUM
38		-CONFIG_USB_GADGET_PRODUCT_NUM
39		-CONFIG_USB_GADGET_MANUFACTURER
	48	+::
40	49
41		-NOTE: The CONFIG_USB_GADGET_VENDOR_NUM must be one of the numbers supported by
42		-the fastboot client. The list of vendor IDs supported can be found in the
43		-fastboot client source code (fastboot.c) mentioned above.
	50	+ CONFIG_USB_GADGET_DOWNLOAD
	51	+ CONFIG_USB_GADGET_VENDOR_NUM
	52	+ CONFIG_USB_GADGET_PRODUCT_NUM
	53	+ CONFIG_USB_GADGET_MANUFACTURER
44	54
45		-The fastboot function is enabled by defining CONFIG_USB_FUNCTION_FASTBOOT,
46		-CONFIG_CMD_FASTBOOT and CONFIG_ANDROID_BOOT_IMAGE.
	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.
47	58
48		-The fastboot protocol requires a large memory buffer for downloads. This
49		-buffer should be as large as possible for a platform. The location of the
50		-buffer and size are set with CONFIG_FASTBOOT_BUF_ADDR and
51		-CONFIG_FASTBOOT_BUF_SIZE.
	59	+General configuration
	60	+---------------------
52	61
	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``.
	68	+
	69	+Fastboot environment variables
	70	+==============================
	71	+
	72	+Partition aliases
	73	+-----------------
	74	+
53	75	Fastboot partition aliases can also be defined for devices where GPT
54	76	limitations prevent user-friendly partition names such as "boot", "system"
55	77	and "cache". Or, where the actual partition name doesn't match a standard
56		-partition name used commonly with fastboot. Current implentation checks
57		-aliases when accessing partitions by name (flash_write and erase functions).
58		-To define a partition alias add an environment variable similar to:
59		-fastboot_partition_alias_<alias partition name>=<actual partition name>
60		-Example: fastboot_partition_alias_boot=LNX
	78	+partition name used commonly with fastboot.
61	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>``.
	107	+
62	108	Partition Names
63	109	===============
64		-The Fastboot implementation in U-boot allows to write images into disk
65		-partitions (currently on eMMC). Target partitions are referred on the host
66		-computer by their names.
67	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.
	114	+
68	115	For GPT/EFI the respective partition name is used.
69	116
70	117	For MBR the partitions are referred by generic names according to the
71	118	following schema:
72	119
73		- <device type> <device index letter> <partition index>
	120	+ <device type><device index letter><partition index>
74	121
75		-Example: hda3, sdb1, usbda1
	122	+Example: ``hda3``, ``sdb1``, ``usbda1``
76	123
77	124	The device type is as follows:
78	125
79		- * IDE, ATAPI and SATA disks: hd
80		- * SCSI disks: sd
81		- * USB media: usbd
82		- * MMC and SD cards: mmcsd
83		- * Disk on chip: docd
84		- * other: xx
	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``
85	132
86		-The device index starts from 'a' and refers to the interface (e.g. USB
	133	+The device index starts from ``a`` and refers to the interface (e.g. USB
87	134	controller, SD/MMC controller) or disk index. The partition index starts
88		-from 1 and describes the partition number on the particular device.
	135	+from ``1`` and describes the partition number on the particular device.
89	136
90	137	Writing Partition Table
91	138	=======================
	139	+
92	140	Fastboot also allows to write the partition table to the media. This can be
93	141	done by writing the respective partition table image to a special target
94	142	"gpt" or "mbr". These names can be customized by defining the following
95	143	configuration options:
96	144
97		-CONFIG_FASTBOOT_GPT_NAME
98		-CONFIG_FASTBOOT_MBR_NAME
	145	+::
99	146
	147	+ CONFIG_FASTBOOT_GPT_NAME
	148	+ CONFIG_FASTBOOT_MBR_NAME
	149	+
100	150	In Action
101	151	=========
102		-Enter into fastboot by executing the fastboot command in u-boot and you
103		-should see:
104		-\|GADGET DRIVER: usb_dnl_fastboot
105	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
	167	+
106	168	On the client side you can fetch the bootloader version for instance:
107		-\|>fastboot getvar bootloader-version
108		-\|bootloader-version: U-Boot 2014.04-00005-gd24cabc
109		-\|finished. total time: 0.000s
110	169
	170	+::
	171	+
	172	+ $ fastboot getvar bootloader-version
	173	+ bootloader-version: U-Boot 2014.04-00005-gd24cabc
	174	+ finished. total time: 0.000s
	175	+
111	176	or initiate a reboot:
112		-\|>fastboot reboot
113	177
	178	+::
	179	+
	180	+ $ fastboot reboot
	181	+
114	182	and once the client comes back, the board should reset.
115	183
116	184	You can also specify a kernel image to boot. You have to either specify
117		-the an image in Android format _or_ pass a binary kernel and let the
	185	+the an image in Android format or pass a binary kernel and let the
118	186	fastboot client wrap the Android suite around it. On OMAP for instance you
119	187	take zImage kernel and pass it to the fastboot client:
120	188
121		-\|>fastboot -b 0x80000000 -c "console=ttyO2 earlyprintk root=/dev/ram0
122		-\| mem=128M" boot zImage
123		-\|creating boot image...
124		-\|creating boot image - 1847296 bytes
125		-\|downloading 'boot.img'...
126		-\|OKAY [ 2.766s]
127		-\|booting...
128		-\|OKAY [ -0.000s]
129		-\|finished. total time: 2.766s
	189	+::
130	190
131		-and on the gadget side you should see:
132		-\|Starting download of 1847296 bytes
133		-\|........................................................
134		-\|downloading of 1847296 bytes finished
135		-\|Booting kernel..
136		-\|## Booting Android Image at 0x81000000 ...
137		-\|Kernel load addr 0x80008000 size 1801 KiB
138		-\|Kernel command line: console=ttyO2 earlyprintk root=/dev/ram0 mem=128M
139		-\| Loading Kernel Image ... OK
140		-\|OK
141		-\|
142		-\|Starting kernel ...
	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
	213	+
	214	+ Starting kernel ...