Add documentation for USB Host Networking

This describes what it is for, devices supported, how to enable for your
board in U-Boot, setting up the server, and notes about MAC addresses.

Signed-off-by: Simon Glass <sjg@chromium.org>
Tested-by: Eric Bénard <eric@eukrea.com>

1 files changed, 156 insertions, 1 deletions

diff --git a/doc/README.usb b/doc/README.usb
index 9aa4f62ddf..a8a4058de1 100644
--- a/doc/README.usb
+++ b/doc/README.usb
@@ -79,4 +79,159 @@ CONFIG_USB_UHCI	    defines the lowlevel part.A lowlevel part must be defined
 		    if using CONFIG_CMD_USB
 CONFIG_USB_KEYBOARD enables the USB Keyboard
 CONFIG_USB_STORAGE  enables the USB storage devices
-CONFIG_USB_HOST_ETHER	enables USB ethernet dongle support
+CONFIG_USB_HOST_ETHER	enables USB ethernet adapter support
+
+
+USB Host Networking
+===================
+
+If you have a supported USB Ethernet adapter you can use it in U-Boot
+to obtain an IP address and load a kernel from a network server.
+
+Note: USB Host Networking is not the same as making your board act as a USB
+client. In that case your board is pretending to be an Ethernet adapter
+and will appear as a network interface to an attached computer. In that
+case the connection is via a USB cable with the computer acting as the host.
+
+With USB Host Networking, your board is the USB host. It controls the
+Ethernet adapter to which it is directly connected and the connection to
+the outside world is your adapter's Ethernet cable. Your board becomes an
+independent network device, able to connect and perform network operations
+independently of your computer.
+
+
+Device support
+--------------
+
+Currently supported devices are listed in the drivers according to
+their vendor and product IDs. You can check your device by connecting it
+to a Linux machine and typing 'lsusb'. The drivers are in
+drivers/usb/eth.
+
+For example this lsusb output line shows a device with Vendor ID 0x0x95
+and product ID 0x7720:
+
+Bus 002 Device 010: ID 0b95:7720 ASIX Electronics Corp. AX88772
+
+If you look at drivers/usb/eth/asix.c you will see this line within the
+supported device list, so we know this adapter is supported.
+
+        { 0x0b95, 0x7720 },     /* Trendnet TU2-ET100 V3.0R */
+
+If your adapter is not listed there is a still a chance that it will
+work. Try looking up the manufacturer of the chip inside your adapter.
+or take the adapter apart and look for chip markings. Then add a line
+for your vendor/product ID into the table of the appropriate driver,
+build U-Boot and see if it works. If not then there might be differences
+between the chip in your adapter and the driver. You could try to get a
+datasheet for your device and add support for it to U-Boot. This is not
+particularly difficult - you only need to provide support for four basic
+functions: init, halt, send and recv.
+
+
+Enabling USB Host Networking
+----------------------------
+
+The normal U-Boot commands are used with USB networking, but you must
+start USB first. For example:
+
+usb start
+setenv bootfile /tftpboot/uImage
+bootp
+
+
+To enable USB Host Ethernet in U-Boot, your platform must of course
+support USB with CONFIG_CMD_USB enabled and working. You will need to
+add some config settings to your board header file:
+
+#define CONFIG_USB_HOST_ETHER   /* Enable USB Ethernet adapters */
+#define CONFIG_USB_ETHER_ASIX   /* Asix, or whatever driver(s) you want */
+
+As with built-in networking, you will also want to enable some network
+commands, for example:
+
+#define CONFIG_CMD_NET
+#define CONFIG_NET_MULTI
+#define CONFIG_CMD_PING
+#define CONFIG_CMD_DHCP
+
+and some bootp options, which tell your board to obtain its subnet,
+gateway IP, host name and boot path from the bootp/dhcp server. These
+settings should start you off:
+
+#define CONFIG_BOOTP_SUBNETMASK
+#define CONFIG_BOOTP_GATEWAY
+#define CONFIG_BOOTP_HOSTNAME
+#define CONFIG_BOOTP_BOOTPATH
+
+You can also set the default IP address of your board and the server
+as well as the default file to load when a 'bootp' command is issued.
+All of these can be obtained from the bootp server if not set.
+
+#define CONFIG_IPADDR           10.0.0.2  (replace with your value)
+#define CONFIG_SERVERIP         10.0.0.1  (replace with your value)
+#define CONFIG_BOOTFILE         uImage
+
+
+The 'usb start' command should identify the adapter something like this:
+
+CrOS> usb start
+(Re)start USB...
+USB EHCI 1.00
+scanning bus for devices... 3 USB Device(s) found
+       scanning bus for storage devices... 0 Storage Device(s) found
+       scanning bus for ethernet devices... 1 Ethernet Device(s) found
+CrOS> print ethact
+ethact=asx0
+
+You can see that it found an ethernet device and we can print out the
+device name (asx0 in this case).
+
+Then 'bootp' or 'dhcp' should use it to obtain an IP address from DHCP,
+perhaps something like this:
+
+CrOS> bootp
+Waiting for Ethernet connection... done.
+BOOTP broadcast 1
+BOOTP broadcast 2
+DHCP client bound to address 172.22.73.81
+Using asx0 device
+TFTP from server 172.22.72.144; our IP address is 172.22.73.81
+Filename '/tftpboot/uImage-sjg-seaboard-261347'.
+Load address: 0x40c000
+Loading: #################################################################
+         #################################################################
+         #################################################################
+         ################################################
+done
+Bytes transferred = 3557464 (364858 hex)
+CrOS>
+
+
+Another way of doing this is to issue a tftp command, which will cause the
+bootp to happen automatically.
+
+
+MAC Addresses
+-------------
+
+Most Ethernet dongles have a built-in MAC address which is unique in the
+world. This is important so that devices on the network can be
+distinguised from each other. MAC address conflicts are evil and
+generally result in strange and eratic behaviour.
+
+Some boards have USB Ethernet chips on-board, and these sometimes do not
+have an assigned MAC address. In this case it is up to you to assign
+one which is unique. You should obtain a valid MAC address from a range
+assigned to you before you ship the product.
+
+Built-in Ethernet adapters support setting the MAC address by means of
+an ethaddr environment variable for each interface (ethaddr, eth1addr,
+eth2addr). There is similar support on the USB network side, using the
+names usbethaddr, usbeth1addr, etc. They are kept separate since we
+don't want a USB device taking the MAC address of a built-in device or
+vice versa.
+
+So if your USB Ethernet chip doesn't have a MAC address available then
+you must set usbethaddr to a suitable MAC address. At the time of
+writing this functionality is only supported by the SMSC driver.