doc/README.usb

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