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