1/* 2 * (C) Copyright 2001 3 * Denis Peter, MPL AG Switzerland 4 * 5 * SPDX-License-Identifier: GPL-2.0+ 6 */ 7 8USB Support for PIP405 and MIP405 (UHCI) 9======================================== 10 11The USB support is implemented on the base of the UHCI Host 12controller. 13 14Currently supported are USB Hubs, USB Keyboards, USB Floppys, USB 15flash sticks and USB network adaptors. 16Tested 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) 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 58Config Switches: 59---------------- 60CONFIG_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 63CONFIG_USB_KEYBOARD enables the USB Keyboard 64CONFIG_USB_STORAGE enables the USB storage devices 65CONFIG_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 102 { 0x0b95, 0x7720 }, /* Trendnet TU2-ET100 V3.0R */ 103 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 130#define CONFIG_USB_HOST_ETHER /* Enable USB Ethernet adapters */ 131#define CONFIG_USB_ETHER_ASIX /* Asix, or whatever driver(s) you want */ 132 133As with built-in networking, you will also want to enable some network 134commands, for example: 135 136#define CONFIG_CMD_NET 137#define CONFIG_CMD_PING 138#define CONFIG_CMD_DHCP 139 140and some bootp options, which tell your board to obtain its subnet, 141gateway IP, host name and boot path from the bootp/dhcp server. These 142settings 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 149You can also set the default IP address of your board and the server 150as well as the default file to load when a 'bootp' command is issued. 151All 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 158The 'usb start' command should identify the adapter something like this: 159 160CrOS> usb start 161(Re)start USB... 162USB EHCI 1.00 163scanning 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 166CrOS> print ethact 167ethact=asx0 168 169You can see that it found an ethernet device and we can print out the 170device name (asx0 in this case). 171 172Then 'bootp' or 'dhcp' should use it to obtain an IP address from DHCP, 173perhaps something like this: 174 175CrOS> bootp 176Waiting for Ethernet connection... done. 177BOOTP broadcast 1 178BOOTP broadcast 2 179DHCP client bound to address 172.22.73.81 180Using asx0 device 181TFTP from server 172.22.72.144; our IP address is 172.22.73.81 182Filename '/tftpboot/uImage-sjg-seaboard-261347'. 183Load address: 0x40c000 184Loading: ################################################################# 185 ################################################################# 186 ################################################################# 187 ################################################ 188done 189Bytes transferred = 3557464 (364858 hex) 190CrOS> 191 192 193Another way of doing this is to issue a tftp command, which will cause the 194bootp to happen automatically. 195 196 197MAC Addresses 198------------- 199 200Most Ethernet dongles have a built-in MAC address which is unique in the 201world. This is important so that devices on the network can be 202distinguised from each other. MAC address conflicts are evil and 203generally result in strange and eratic behaviour. 204 205Some boards have USB Ethernet chips on-board, and these sometimes do not 206have an assigned MAC address. In this case it is up to you to assign 207one which is unique. You should obtain a valid MAC address from a range 208assigned to you before you ship the product. 209 210Built-in Ethernet adapters support setting the MAC address by means of 211an ethaddr environment variable for each interface (ethaddr, eth1addr, 212eth2addr). There is similar support on the USB network side, using the 213names usbethaddr, usbeth1addr, etc. They are kept separate since we 214don't want a USB device taking the MAC address of a built-in device or 215vice versa. 216 217So if your USB Ethernet chip doesn't have a MAC address available then 218you must set usbethaddr to a suitable MAC address. At the time of 219writing this functionality is only supported by the SMSC driver. 220