xref: /openbmc/u-boot/doc/README.usb (revision 843a7ee8)
1/*
2 * (C) Copyright 2001
3 * Denis Peter, MPL AG Switzerland
4 *
5 * See file CREDITS for list of people who contributed to this
6 * project.
7 *
8 * This program is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU General Public License as
10 * published by the Free Software Foundation; either version 2 of
11 * the License, or (at your option) any later version.
12 *
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the
16 * GNU General Public License for more details.
17 *
18 * You should have received a copy of the GNU General Public License
19 * along with this program; if not, write to the Free Software
20 * Foundation, Inc., 59 Temple Place, Suite 330, Boston,
21 * MA 02111-1307 USA
22 *
23 */
24
25USB Support for PIP405 and MIP405 (UHCI)
26========================================
27
28The USB support is implemented on the base of the UHCI Host
29controller.
30
31Currently supported are USB Hubs, USB Keyboards, USB Floppys, USB
32flash sticks and USB network adaptors.
33Tested with a TEAC Floppy TEAC FD-05PUB and Chicony KU-8933 Keyboard.
34
35How it works:
36-------------
37
38The USB (at least the USB UHCI) needs a frame list (4k), transfer
39descripor and queue headers which are all located in the main memory.
40The UHCI allocates every milisecond the PCI bus and reads the current
41frame pointer. This may cause to crash the OS during boot. So the USB
42_MUST_ be stopped during OS boot. This is the reason, why the USB is
43NOT automatically started during start-up. If someone needs the USB
44he has to start it and should therefore be aware that he had to stop
45it before booting the OS.
46
47For USB keyboards this can be done by a script which is automatically
48started after the U-Boot is up and running. To boot an OS with a an
49USB keyboard another script is necessary, which first disables the
50USB and then executes the boot command. If the boot command fails,
51the script can reenable the USB kbd.
52
53Common USB Commands:
54- usb start:
55- usb reset:	    (re)starts the USB. All USB devices will be
56		    initialized and a device tree is build for them.
57- usb tree:	    shows all USB devices in a tree like display
58- usb info [dev]:   shows all USB infos of the device dev, or of all
59		    the devices
60- usb stop [f]:	    stops the USB. If f==1 the USB will also stop if
61		    an USB keyboard is assigned as stdin. The stdin
62		    is then switched to serial input.
63Storage USB Commands:
64- usb scan:	    scans the USB for storage devices.The USB must be
65		    running for this command (usb start)
66- usb device [dev]: show or set current USB staorage device
67- usb part [dev]:   print partition table of one or all USB storage
68		    devices
69- usb read addr blk# cnt:
70		    read `cnt' blocks starting at block `blk#'to
71		    memory address `addr'
72- usbboot addr dev:part:
73		    boot from USB device
74
75Config Switches:
76----------------
77CONFIG_CMD_USB	    enables basic USB support and the usb command
78CONFIG_USB_UHCI	    defines the lowlevel part.A lowlevel part must be defined
79		    if using CONFIG_CMD_USB
80CONFIG_USB_KEYBOARD enables the USB Keyboard
81CONFIG_USB_STORAGE  enables the USB storage devices
82CONFIG_USB_HOST_ETHER	enables USB ethernet adapter support
83
84
85USB Host Networking
86===================
87
88If you have a supported USB Ethernet adapter you can use it in U-Boot
89to obtain an IP address and load a kernel from a network server.
90
91Note: USB Host Networking is not the same as making your board act as a USB
92client. In that case your board is pretending to be an Ethernet adapter
93and will appear as a network interface to an attached computer. In that
94case the connection is via a USB cable with the computer acting as the host.
95
96With USB Host Networking, your board is the USB host. It controls the
97Ethernet adapter to which it is directly connected and the connection to
98the outside world is your adapter's Ethernet cable. Your board becomes an
99independent network device, able to connect and perform network operations
100independently of your computer.
101
102
103Device support
104--------------
105
106Currently supported devices are listed in the drivers according to
107their vendor and product IDs. You can check your device by connecting it
108to a Linux machine and typing 'lsusb'. The drivers are in
109drivers/usb/eth.
110
111For example this lsusb output line shows a device with Vendor ID 0x0x95
112and product ID 0x7720:
113
114Bus 002 Device 010: ID 0b95:7720 ASIX Electronics Corp. AX88772
115
116If you look at drivers/usb/eth/asix.c you will see this line within the
117supported device list, so we know this adapter is supported.
118
119	{ 0x0b95, 0x7720 },	/* Trendnet TU2-ET100 V3.0R */
120
121If your adapter is not listed there is a still a chance that it will
122work. Try looking up the manufacturer of the chip inside your adapter.
123or take the adapter apart and look for chip markings. Then add a line
124for your vendor/product ID into the table of the appropriate driver,
125build U-Boot and see if it works. If not then there might be differences
126between the chip in your adapter and the driver. You could try to get a
127datasheet for your device and add support for it to U-Boot. This is not
128particularly difficult - you only need to provide support for four basic
129functions: init, halt, send and recv.
130
131
132Enabling USB Host Networking
133----------------------------
134
135The normal U-Boot commands are used with USB networking, but you must
136start USB first. For example:
137
138usb start
139setenv bootfile /tftpboot/uImage
140bootp
141
142
143To enable USB Host Ethernet in U-Boot, your platform must of course
144support USB with CONFIG_CMD_USB enabled and working. You will need to
145add some config settings to your board header file:
146
147#define CONFIG_USB_HOST_ETHER	/* Enable USB Ethernet adapters */
148#define CONFIG_USB_ETHER_ASIX	/* Asix, or whatever driver(s) you want */
149
150As with built-in networking, you will also want to enable some network
151commands, for example:
152
153#define CONFIG_CMD_NET
154#define CONFIG_CMD_PING
155#define CONFIG_CMD_DHCP
156
157and some bootp options, which tell your board to obtain its subnet,
158gateway IP, host name and boot path from the bootp/dhcp server. These
159settings should start you off:
160
161#define CONFIG_BOOTP_SUBNETMASK
162#define CONFIG_BOOTP_GATEWAY
163#define CONFIG_BOOTP_HOSTNAME
164#define CONFIG_BOOTP_BOOTPATH
165
166You can also set the default IP address of your board and the server
167as well as the default file to load when a 'bootp' command is issued.
168All of these can be obtained from the bootp server if not set.
169
170#define CONFIG_IPADDR		10.0.0.2  (replace with your value)
171#define CONFIG_SERVERIP		10.0.0.1  (replace with your value)
172#define CONFIG_BOOTFILE		"uImage"
173
174
175The 'usb start' command should identify the adapter something like this:
176
177CrOS> usb start
178(Re)start USB...
179USB EHCI 1.00
180scanning bus for devices... 3 USB Device(s) found
181       scanning bus for storage devices... 0 Storage Device(s) found
182       scanning bus for ethernet devices... 1 Ethernet Device(s) found
183CrOS> print ethact
184ethact=asx0
185
186You can see that it found an ethernet device and we can print out the
187device name (asx0 in this case).
188
189Then 'bootp' or 'dhcp' should use it to obtain an IP address from DHCP,
190perhaps something like this:
191
192CrOS> bootp
193Waiting for Ethernet connection... done.
194BOOTP broadcast 1
195BOOTP broadcast 2
196DHCP client bound to address 172.22.73.81
197Using asx0 device
198TFTP from server 172.22.72.144; our IP address is 172.22.73.81
199Filename '/tftpboot/uImage-sjg-seaboard-261347'.
200Load address: 0x40c000
201Loading: #################################################################
202	 #################################################################
203	 #################################################################
204	 ################################################
205done
206Bytes transferred = 3557464 (364858 hex)
207CrOS>
208
209
210Another way of doing this is to issue a tftp command, which will cause the
211bootp to happen automatically.
212
213
214MAC Addresses
215-------------
216
217Most Ethernet dongles have a built-in MAC address which is unique in the
218world. This is important so that devices on the network can be
219distinguised from each other. MAC address conflicts are evil and
220generally result in strange and eratic behaviour.
221
222Some boards have USB Ethernet chips on-board, and these sometimes do not
223have an assigned MAC address. In this case it is up to you to assign
224one which is unique. You should obtain a valid MAC address from a range
225assigned to you before you ship the product.
226
227Built-in Ethernet adapters support setting the MAC address by means of
228an ethaddr environment variable for each interface (ethaddr, eth1addr,
229eth2addr). There is similar support on the USB network side, using the
230names usbethaddr, usbeth1addr, etc. They are kept separate since we
231don't want a USB device taking the MAC address of a built-in device or
232vice versa.
233
234So if your USB Ethernet chip doesn't have a MAC address available then
235you must set usbethaddr to a suitable MAC address. At the time of
236writing this functionality is only supported by the SMSC driver.
237