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