blob: fb7e688dafed752e97493faa8835d39f593b1114 [file] [log] [blame]
wdenke2211742002-11-02 23:30:20 +00001/*
2 * (C) Copyright 2001
3 * Denis Peter, MPL AG Switzerland
4 *
Wolfgang Denk1a459662013-07-08 09:37:19 +02005 * SPDX-License-Identifier: GPL-2.0+
wdenke2211742002-11-02 23:30:20 +00006 */
7
Heiko Schocher98f705c2017-06-27 16:49:14 +02008USB Support
9===========
wdenke2211742002-11-02 23:30:20 +000010
11The USB support is implemented on the base of the UHCI Host
12controller.
13
Simon Glass89d48362011-02-16 11:14:33 -080014Currently supported are USB Hubs, USB Keyboards, USB Floppys, USB
15flash sticks and USB network adaptors.
wdenke2211742002-11-02 23:30:20 +000016Tested with a TEAC Floppy TEAC FD-05PUB and Chicony KU-8933 Keyboard.
17
18How it works:
19-------------
20
21The USB (at least the USB UHCI) needs a frame list (4k), transfer
22descripor and queue headers which are all located in the main memory.
23The UHCI allocates every milisecond the PCI bus and reads the current
24frame 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
26NOT automatically started during start-up. If someone needs the USB
27he has to start it and should therefore be aware that he had to stop
28it before booting the OS.
29
30For USB keyboards this can be done by a script which is automatically
31started after the U-Boot is up and running. To boot an OS with a an
32USB keyboard another script is necessary, which first disables the
33USB and then executes the boot command. If the boot command fails,
34the script can reenable the USB kbd.
35
36Common 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.
46Storage USB Commands:
47- usb scan: scans the USB for storage devices.The USB must be
48 running for this command (usb start)
Richard Genoudc5a927c2012-11-29 23:18:31 +000049- usb device [dev]: show or set current USB storage device
wdenke2211742002-11-02 23:30:20 +000050- 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
58Config Switches:
59----------------
Jon Loeligerb3aff0c2007-07-10 11:19:50 -050060CONFIG_CMD_USB enables basic USB support and the usb command
61CONFIG_USB_UHCI defines the lowlevel part.A lowlevel part must be defined
62 if using CONFIG_CMD_USB
wdenke2211742002-11-02 23:30:20 +000063CONFIG_USB_KEYBOARD enables the USB Keyboard
64CONFIG_USB_STORAGE enables the USB storage devices
Simon Glass4fdbcf82011-06-13 16:13:11 -070065CONFIG_USB_HOST_ETHER enables USB ethernet adapter support
66
67
68USB Host Networking
69===================
70
71If you have a supported USB Ethernet adapter you can use it in U-Boot
72to obtain an IP address and load a kernel from a network server.
73
74Note: USB Host Networking is not the same as making your board act as a USB
75client. In that case your board is pretending to be an Ethernet adapter
76and will appear as a network interface to an attached computer. In that
77case the connection is via a USB cable with the computer acting as the host.
78
79With USB Host Networking, your board is the USB host. It controls the
80Ethernet adapter to which it is directly connected and the connection to
81the outside world is your adapter's Ethernet cable. Your board becomes an
82independent network device, able to connect and perform network operations
83independently of your computer.
84
85
86Device support
87--------------
88
89Currently supported devices are listed in the drivers according to
90their vendor and product IDs. You can check your device by connecting it
91to a Linux machine and typing 'lsusb'. The drivers are in
92drivers/usb/eth.
93
94For example this lsusb output line shows a device with Vendor ID 0x0x95
95and product ID 0x7720:
96
97Bus 002 Device 010: ID 0b95:7720 ASIX Electronics Corp. AX88772
98
99If you look at drivers/usb/eth/asix.c you will see this line within the
100supported device list, so we know this adapter is supported.
101
Wolfgang Denk04e5ae72011-09-11 21:24:09 +0200102 { 0x0b95, 0x7720 }, /* Trendnet TU2-ET100 V3.0R */
Simon Glass4fdbcf82011-06-13 16:13:11 -0700103
104If your adapter is not listed there is a still a chance that it will
105work. Try looking up the manufacturer of the chip inside your adapter.
106or take the adapter apart and look for chip markings. Then add a line
107for your vendor/product ID into the table of the appropriate driver,
108build U-Boot and see if it works. If not then there might be differences
109between the chip in your adapter and the driver. You could try to get a
110datasheet for your device and add support for it to U-Boot. This is not
111particularly difficult - you only need to provide support for four basic
112functions: init, halt, send and recv.
113
114
115Enabling USB Host Networking
116----------------------------
117
118The normal U-Boot commands are used with USB networking, but you must
119start USB first. For example:
120
121usb start
122setenv bootfile /tftpboot/uImage
123bootp
124
125
126To enable USB Host Ethernet in U-Boot, your platform must of course
127support USB with CONFIG_CMD_USB enabled and working. You will need to
128add some config settings to your board header file:
129
Gerhard Sittigdd11aca2014-03-08 19:46:18 +0100130#define CONFIG_CMD_USB /* the 'usb' interactive command */
Wolfgang Denk04e5ae72011-09-11 21:24:09 +0200131#define CONFIG_USB_HOST_ETHER /* Enable USB Ethernet adapters */
Gerhard Sittigdd11aca2014-03-08 19:46:18 +0100132
133and one or more of the following for individual adapter hardware:
134
135#define CONFIG_USB_ETHER_ASIX
136#define CONFIG_USB_ETHER_MCS7830
137#define CONFIG_USB_ETHER_SMSC95XX
Simon Glass4fdbcf82011-06-13 16:13:11 -0700138
139As with built-in networking, you will also want to enable some network
140commands, for example:
141
142#define CONFIG_CMD_NET
Simon Glass4fdbcf82011-06-13 16:13:11 -0700143#define CONFIG_CMD_PING
144#define CONFIG_CMD_DHCP
145
146and some bootp options, which tell your board to obtain its subnet,
147gateway IP, host name and boot path from the bootp/dhcp server. These
148settings should start you off:
149
150#define CONFIG_BOOTP_SUBNETMASK
151#define CONFIG_BOOTP_GATEWAY
152#define CONFIG_BOOTP_HOSTNAME
153#define CONFIG_BOOTP_BOOTPATH
154
155You can also set the default IP address of your board and the server
156as well as the default file to load when a 'bootp' command is issued.
Gerhard Sittigdd11aca2014-03-08 19:46:18 +0100157However note that encoding these individual network settings into a
158common exectuable is discouraged, as it leads to potential conflicts,
159and all the parameters can either get stored in the board's external
160environment, or get obtained from the bootp server if not set.
Simon Glass4fdbcf82011-06-13 16:13:11 -0700161
Wolfgang Denk04e5ae72011-09-11 21:24:09 +0200162#define CONFIG_IPADDR 10.0.0.2 (replace with your value)
163#define CONFIG_SERVERIP 10.0.0.1 (replace with your value)
Joe Hershbergerb3f44c22011-10-13 13:03:48 +0000164#define CONFIG_BOOTFILE "uImage"
Simon Glass4fdbcf82011-06-13 16:13:11 -0700165
166
167The 'usb start' command should identify the adapter something like this:
168
169CrOS> usb start
170(Re)start USB...
171USB EHCI 1.00
172scanning bus for devices... 3 USB Device(s) found
173 scanning bus for storage devices... 0 Storage Device(s) found
174 scanning bus for ethernet devices... 1 Ethernet Device(s) found
175CrOS> print ethact
176ethact=asx0
177
178You can see that it found an ethernet device and we can print out the
179device name (asx0 in this case).
180
181Then 'bootp' or 'dhcp' should use it to obtain an IP address from DHCP,
182perhaps something like this:
183
184CrOS> bootp
185Waiting for Ethernet connection... done.
186BOOTP broadcast 1
187BOOTP broadcast 2
188DHCP client bound to address 172.22.73.81
189Using asx0 device
190TFTP from server 172.22.72.144; our IP address is 172.22.73.81
191Filename '/tftpboot/uImage-sjg-seaboard-261347'.
192Load address: 0x40c000
193Loading: #################################################################
Wolfgang Denk04e5ae72011-09-11 21:24:09 +0200194 #################################################################
195 #################################################################
196 ################################################
Simon Glass4fdbcf82011-06-13 16:13:11 -0700197done
198Bytes transferred = 3557464 (364858 hex)
199CrOS>
200
201
202Another way of doing this is to issue a tftp command, which will cause the
203bootp to happen automatically.
204
205
206MAC Addresses
207-------------
208
209Most Ethernet dongles have a built-in MAC address which is unique in the
210world. This is important so that devices on the network can be
211distinguised from each other. MAC address conflicts are evil and
212generally result in strange and eratic behaviour.
213
214Some boards have USB Ethernet chips on-board, and these sometimes do not
215have an assigned MAC address. In this case it is up to you to assign
216one which is unique. You should obtain a valid MAC address from a range
217assigned to you before you ship the product.
218
219Built-in Ethernet adapters support setting the MAC address by means of
220an ethaddr environment variable for each interface (ethaddr, eth1addr,
221eth2addr). There is similar support on the USB network side, using the
222names usbethaddr, usbeth1addr, etc. They are kept separate since we
223don't want a USB device taking the MAC address of a built-in device or
224vice versa.
225
226So if your USB Ethernet chip doesn't have a MAC address available then
227you must set usbethaddr to a suitable MAC address. At the time of
228writing this functionality is only supported by the SMSC driver.