doc/README.usb

   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
  25 USB Support for PIP405 and MIP405 (UHCI)
  26 ========================================
  27
  28 The USB support is implemented on the base of the UHCI Host
  29 controller.
  30
  31 Currently supported are USB Hubs, USB Keyboards, USB Floppys, USB
  32 flash sticks and USB network adaptors.
  33 Tested with a TEAC Floppy TEAC FD-05PUB and Chicony KU-8933 Keyboard.
  34
  35 How it works:
  36 -------------
  37
  38 The USB (at least the USB UHCI) needs a frame list (4k), transfer
  39 descripor and queue headers which are all located in the main memory.
  40 The UHCI allocates every milisecond the PCI bus and reads the current
  41 frame 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
  43 NOT automatically started during start-up. If someone needs the USB
  44 he has to start it and should therefore be aware that he had to stop
  45 it before booting the OS.
  46
  47 For USB keyboards this can be done by a script which is automatically
  48 started after the U-Boot is up and running. To boot an OS with a an
  49 USB keyboard another script is necessary, which first disables the
  50 USB and then executes the boot command. If the boot command fails,
  51 the script can reenable the USB kbd.
  52
  53 Common 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.
  63 Storage 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 storage 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
  75 Config Switches:
  76 ----------------
  77 CONFIG_CMD_USB      enables basic USB support and the usb command
  78 CONFIG_USB_UHCI     defines the lowlevel part.A lowlevel part must be defined
  79                     if using CONFIG_CMD_USB
  80 CONFIG_USB_KEYBOARD enables the USB Keyboard
  81 CONFIG_USB_STORAGE  enables the USB storage devices
  82 CONFIG_USB_HOST_ETHER   enables USB ethernet adapter support
  83
  84
  85 USB Host Networking
  86 ===================
  87
  88 If you have a supported USB Ethernet adapter you can use it in U-Boot
  89 to obtain an IP address and load a kernel from a network server.
  90
  91 Note: USB Host Networking is not the same as making your board act as a USB
  92 client. In that case your board is pretending to be an Ethernet adapter
  93 and will appear as a network interface to an attached computer. In that
  94 case the connection is via a USB cable with the computer acting as the host.
  95
  96 With USB Host Networking, your board is the USB host. It controls the
  97 Ethernet adapter to which it is directly connected and the connection to
  98 the outside world is your adapter's Ethernet cable. Your board becomes an
  99 independent network device, able to connect and perform network operations
 100 independently of your computer.
 101
 102
 103 Device support
 104 --------------
 105
 106 Currently supported devices are listed in the drivers according to
 107 their vendor and product IDs. You can check your device by connecting it
 108 to a Linux machine and typing 'lsusb'. The drivers are in
 109 drivers/usb/eth.
 110
 111 For example this lsusb output line shows a device with Vendor ID 0x0x95
 112 and product ID 0x7720:
 113
 114 Bus 002 Device 010: ID 0b95:7720 ASIX Electronics Corp. AX88772
 115
 116 If you look at drivers/usb/eth/asix.c you will see this line within the
 117 supported device list, so we know this adapter is supported.
 118
 119         { 0x0b95, 0x7720 },     /* Trendnet TU2-ET100 V3.0R */
 120
 121 If your adapter is not listed there is a still a chance that it will
 122 work. Try looking up the manufacturer of the chip inside your adapter.
 123 or take the adapter apart and look for chip markings. Then add a line
 124 for your vendor/product ID into the table of the appropriate driver,
 125 build U-Boot and see if it works. If not then there might be differences
 126 between the chip in your adapter and the driver. You could try to get a
 127 datasheet for your device and add support for it to U-Boot. This is not
 128 particularly difficult - you only need to provide support for four basic
 129 functions: init, halt, send and recv.
 130
 131
 132 Enabling USB Host Networking
 133 ----------------------------
 134
 135 The normal U-Boot commands are used with USB networking, but you must
 136 start USB first. For example:
 137
 138 usb start
 139 setenv bootfile /tftpboot/uImage
 140 bootp
 141
 142
 143 To enable USB Host Ethernet in U-Boot, your platform must of course
 144 support USB with CONFIG_CMD_USB enabled and working. You will need to
 145 add 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
 150 As with built-in networking, you will also want to enable some network
 151 commands, for example:
 152
 153 #define CONFIG_CMD_NET
 154 #define CONFIG_CMD_PING
 155 #define CONFIG_CMD_DHCP
 156
 157 and some bootp options, which tell your board to obtain its subnet,
 158 gateway IP, host name and boot path from the bootp/dhcp server. These
 159 settings 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
 166 You can also set the default IP address of your board and the server
 167 as well as the default file to load when a 'bootp' command is issued.
 168 All 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
 175 The 'usb start' command should identify the adapter something like this:
 176
 177 CrOS> usb start
 178 (Re)start USB...
 179 USB EHCI 1.00
 180 scanning 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
 183 CrOS> print ethact
 184 ethact=asx0
 185
 186 You can see that it found an ethernet device and we can print out the
 187 device name (asx0 in this case).
 188
 189 Then 'bootp' or 'dhcp' should use it to obtain an IP address from DHCP,
 190 perhaps something like this:
 191
 192 CrOS> bootp
 193 Waiting for Ethernet connection... done.
 194 BOOTP broadcast 1
 195 BOOTP broadcast 2
 196 DHCP client bound to address 172.22.73.81
 197 Using asx0 device
 198 TFTP from server 172.22.72.144; our IP address is 172.22.73.81
 199 Filename '/tftpboot/uImage-sjg-seaboard-261347'.
 200 Load address: 0x40c000
 201 Loading: #################################################################
 202          #################################################################
 203          #################################################################
 204          ################################################
 205 done
 206 Bytes transferred = 3557464 (364858 hex)
 207 CrOS>
 208
 209
 210 Another way of doing this is to issue a tftp command, which will cause the
 211 bootp to happen automatically.
 212
 213
 214 MAC Addresses
 215 -------------
 216
 217 Most Ethernet dongles have a built-in MAC address which is unique in the
 218 world. This is important so that devices on the network can be
 219 distinguised from each other. MAC address conflicts are evil and
 220 generally result in strange and eratic behaviour.
 221
 222 Some boards have USB Ethernet chips on-board, and these sometimes do not
 223 have an assigned MAC address. In this case it is up to you to assign
 224 one which is unique. You should obtain a valid MAC address from a range
 225 assigned to you before you ship the product.
 226
 227 Built-in Ethernet adapters support setting the MAC address by means of
 228 an ethaddr environment variable for each interface (ethaddr, eth1addr,
 229 eth2addr). There is similar support on the USB network side, using the
 230 names usbethaddr, usbeth1addr, etc. They are kept separate since we
 231 don't want a USB device taking the MAC address of a built-in device or
 232 vice versa.
 233
 234 So if your USB Ethernet chip doesn't have a MAC address available then
 235 you must set usbethaddr to a suitable MAC address. At the time of
 236 writing this functionality is only supported by the SMSC driver.