blob: 650a6daae0a55d2e1ad948e3a09d879bc96c3357 [file] [log] [blame]
Tom Rini83d290c2018-05-06 17:58:06 -04001SPDX-License-Identifier: GPL-2.0+
wdenke2211742002-11-02 23:30:20 +00002/*
3 * (C) Copyright 2001
4 * Denis Peter, MPL AG Switzerland
wdenke2211742002-11-02 23:30:20 +00005 */
6
Heiko Schocher98f705c2017-06-27 16:49:14 +02007USB Support
8===========
wdenke2211742002-11-02 23:30:20 +00009
10The USB support is implemented on the base of the UHCI Host
11controller.
12
Simon Glass89d48362011-02-16 11:14:33 -080013Currently supported are USB Hubs, USB Keyboards, USB Floppys, USB
14flash sticks and USB network adaptors.
wdenke2211742002-11-02 23:30:20 +000015Tested with a TEAC Floppy TEAC FD-05PUB and Chicony KU-8933 Keyboard.
16
17How it works:
18-------------
19
20The USB (at least the USB UHCI) needs a frame list (4k), transfer
Andy Shevchenkob5f38502021-11-12 18:37:47 +030021descriptor and queue headers which are all located in the main memory.
22The UHCI allocates every millisecond the PCI bus and reads the current
wdenke2211742002-11-02 23:30:20 +000023frame pointer. This may cause to crash the OS during boot. So the USB
24_MUST_ be stopped during OS boot. This is the reason, why the USB is
25NOT automatically started during start-up. If someone needs the USB
26he has to start it and should therefore be aware that he had to stop
27it before booting the OS.
28
29For USB keyboards this can be done by a script which is automatically
Andy Shevchenkob5f38502021-11-12 18:37:47 +030030started after the U-Boot is up and running. To boot an OS with a
wdenke2211742002-11-02 23:30:20 +000031USB keyboard another script is necessary, which first disables the
32USB and then executes the boot command. If the boot command fails,
Andy Shevchenkob5f38502021-11-12 18:37:47 +030033the script can re-enable the USB keyboard.
wdenke2211742002-11-02 23:30:20 +000034
35Common USB Commands:
36- usb start:
37- usb reset: (re)starts the USB. All USB devices will be
38 initialized and a device tree is build for them.
39- usb tree: shows all USB devices in a tree like display
40- usb info [dev]: shows all USB infos of the device dev, or of all
41 the devices
42- usb stop [f]: stops the USB. If f==1 the USB will also stop if
Andy Shevchenkob5f38502021-11-12 18:37:47 +030043 a USB keyboard is assigned as stdin. The stdin
wdenke2211742002-11-02 23:30:20 +000044 is then switched to serial input.
45Storage USB Commands:
Andy Shevchenkob5f38502021-11-12 18:37:47 +030046- usb scan: scans the USB for storage devices. The USB must be
wdenke2211742002-11-02 23:30:20 +000047 running for this command (usb start)
Richard Genoudc5a927c2012-11-29 23:18:31 +000048- usb device [dev]: show or set current USB storage device
wdenke2211742002-11-02 23:30:20 +000049- usb part [dev]: print partition table of one or all USB storage
50 devices
51- usb read addr blk# cnt:
52 read `cnt' blocks starting at block `blk#'to
53 memory address `addr'
54- usbboot addr dev:part:
55 boot from USB device
56
57Config Switches:
58----------------
Jon Loeligerb3aff0c2007-07-10 11:19:50 -050059CONFIG_CMD_USB enables basic USB support and the usb command
Andy Shevchenkob5f38502021-11-12 18:37:47 +030060CONFIG_USB_UHCI defines the lowlevel part. A lowlevel part must be defined
Jon Loeligerb3aff0c2007-07-10 11:19:50 -050061 if using CONFIG_CMD_USB
wdenke2211742002-11-02 23:30:20 +000062CONFIG_USB_KEYBOARD enables the USB Keyboard
63CONFIG_USB_STORAGE enables the USB storage devices
Simon Glass4fdbcf82011-06-13 16:13:11 -070064CONFIG_USB_HOST_ETHER enables USB ethernet adapter support
65
66
67USB Host Networking
68===================
69
70If you have a supported USB Ethernet adapter you can use it in U-Boot
71to obtain an IP address and load a kernel from a network server.
72
73Note: USB Host Networking is not the same as making your board act as a USB
74client. In that case your board is pretending to be an Ethernet adapter
75and will appear as a network interface to an attached computer. In that
76case the connection is via a USB cable with the computer acting as the host.
77
78With USB Host Networking, your board is the USB host. It controls the
79Ethernet adapter to which it is directly connected and the connection to
80the outside world is your adapter's Ethernet cable. Your board becomes an
81independent network device, able to connect and perform network operations
82independently of your computer.
83
84
85Device support
86--------------
87
88Currently supported devices are listed in the drivers according to
89their vendor and product IDs. You can check your device by connecting it
90to a Linux machine and typing 'lsusb'. The drivers are in
91drivers/usb/eth.
92
93For example this lsusb output line shows a device with Vendor ID 0x0x95
94and product ID 0x7720:
95
96Bus 002 Device 010: ID 0b95:7720 ASIX Electronics Corp. AX88772
97
98If you look at drivers/usb/eth/asix.c you will see this line within the
99supported device list, so we know this adapter is supported.
100
Wolfgang Denk04e5ae72011-09-11 21:24:09 +0200101 { 0x0b95, 0x7720 }, /* Trendnet TU2-ET100 V3.0R */
Simon Glass4fdbcf82011-06-13 16:13:11 -0700102
103If your adapter is not listed there is a still a chance that it will
104work. Try looking up the manufacturer of the chip inside your adapter.
105or take the adapter apart and look for chip markings. Then add a line
106for your vendor/product ID into the table of the appropriate driver,
107build U-Boot and see if it works. If not then there might be differences
108between the chip in your adapter and the driver. You could try to get a
109datasheet for your device and add support for it to U-Boot. This is not
110particularly difficult - you only need to provide support for four basic
111functions: init, halt, send and recv.
112
113
114Enabling USB Host Networking
115----------------------------
116
117The normal U-Boot commands are used with USB networking, but you must
118start USB first. For example:
119
120usb start
121setenv bootfile /tftpboot/uImage
122bootp
123
124
125To enable USB Host Ethernet in U-Boot, your platform must of course
126support USB with CONFIG_CMD_USB enabled and working. You will need to
Andy Shevchenkob5f38502021-11-12 18:37:47 +0300127add some settings to your board configuration:
Simon Glass4fdbcf82011-06-13 16:13:11 -0700128
Chris Packham0683fb72017-08-28 20:50:47 +1200129CONFIG_CMD_USB=y /* the 'usb' interactive command */
130CONFIG_USB_HOST_ETHER=y /* Enable USB Ethernet adapters */
Gerhard Sittigdd11aca2014-03-08 19:46:18 +0100131
132and one or more of the following for individual adapter hardware:
133
Chris Packham0683fb72017-08-28 20:50:47 +1200134CONFIG_USB_ETHER_ASIX=y
135CONFIG_USB_ETHER_ASIX88179=y
136CONFIG_USB_ETHER_LAN75XX=y
137CONFIG_USB_ETHER_LAN78XX=y
138CONFIG_USB_ETHER_MCS7830=y
139CONFIG_USB_ETHER_RTL8152=y
140CONFIG_USB_ETHER_SMSC95XX=y
Simon Glass4fdbcf82011-06-13 16:13:11 -0700141
142As with built-in networking, you will also want to enable some network
143commands, for example:
144
Chris Packham0683fb72017-08-28 20:50:47 +1200145CONFIG_CMD_NET=y
146CONFIG_CMD_PING=y
147CONFIG_CMD_DHCP=y
Simon Glass4fdbcf82011-06-13 16:13:11 -0700148
149and some bootp options, which tell your board to obtain its subnet,
150gateway IP, host name and boot path from the bootp/dhcp server. These
151settings should start you off:
152
153#define CONFIG_BOOTP_SUBNETMASK
154#define CONFIG_BOOTP_GATEWAY
155#define CONFIG_BOOTP_HOSTNAME
156#define CONFIG_BOOTP_BOOTPATH
157
158You can also set the default IP address of your board and the server
159as well as the default file to load when a 'bootp' command is issued.
Gerhard Sittigdd11aca2014-03-08 19:46:18 +0100160However note that encoding these individual network settings into a
Andy Shevchenkob5f38502021-11-12 18:37:47 +0300161common executable is discouraged, as it leads to potential conflicts,
Gerhard Sittigdd11aca2014-03-08 19:46:18 +0100162and all the parameters can either get stored in the board's external
163environment, or get obtained from the bootp server if not set.
Simon Glass4fdbcf82011-06-13 16:13:11 -0700164
Wolfgang Denk04e5ae72011-09-11 21:24:09 +0200165#define CONFIG_IPADDR 10.0.0.2 (replace with your value)
166#define CONFIG_SERVERIP 10.0.0.1 (replace with your value)
Joe Hershbergerb3f44c22011-10-13 13:03:48 +0000167#define CONFIG_BOOTFILE "uImage"
Simon Glass4fdbcf82011-06-13 16:13:11 -0700168
Simon Glass4fdbcf82011-06-13 16:13:11 -0700169The 'usb start' command should identify the adapter something like this:
170
171CrOS> usb start
172(Re)start USB...
173USB EHCI 1.00
174scanning bus for devices... 3 USB Device(s) found
175 scanning bus for storage devices... 0 Storage Device(s) found
176 scanning bus for ethernet devices... 1 Ethernet Device(s) found
177CrOS> print ethact
178ethact=asx0
179
180You can see that it found an ethernet device and we can print out the
181device name (asx0 in this case).
182
183Then 'bootp' or 'dhcp' should use it to obtain an IP address from DHCP,
184perhaps something like this:
185
186CrOS> bootp
187Waiting for Ethernet connection... done.
188BOOTP broadcast 1
189BOOTP broadcast 2
190DHCP client bound to address 172.22.73.81
191Using asx0 device
192TFTP from server 172.22.72.144; our IP address is 172.22.73.81
193Filename '/tftpboot/uImage-sjg-seaboard-261347'.
194Load address: 0x40c000
195Loading: #################################################################
Wolfgang Denk04e5ae72011-09-11 21:24:09 +0200196 #################################################################
197 #################################################################
198 ################################################
Simon Glass4fdbcf82011-06-13 16:13:11 -0700199done
200Bytes transferred = 3557464 (364858 hex)
201CrOS>
202
203
204Another way of doing this is to issue a tftp command, which will cause the
205bootp to happen automatically.
206
207
208MAC Addresses
209-------------
210
211Most Ethernet dongles have a built-in MAC address which is unique in the
212world. This is important so that devices on the network can be
Andy Shevchenkob5f38502021-11-12 18:37:47 +0300213distinguished from each other. MAC address conflicts are evil and
214generally result in strange and erratic behaviour.
Simon Glass4fdbcf82011-06-13 16:13:11 -0700215
216Some boards have USB Ethernet chips on-board, and these sometimes do not
217have an assigned MAC address. In this case it is up to you to assign
218one which is unique. You should obtain a valid MAC address from a range
219assigned to you before you ship the product.
220
221Built-in Ethernet adapters support setting the MAC address by means of
222an ethaddr environment variable for each interface (ethaddr, eth1addr,
223eth2addr). There is similar support on the USB network side, using the
224names usbethaddr, usbeth1addr, etc. They are kept separate since we
225don't want a USB device taking the MAC address of a built-in device or
226vice versa.
227
228So if your USB Ethernet chip doesn't have a MAC address available then
229you must set usbethaddr to a suitable MAC address. At the time of
230writing this functionality is only supported by the SMSC driver.