From patchwork Mon Jun 13 23:13:11 2011 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Simon Glass X-Patchwork-Id: 100185 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from theia.denx.de (theia.denx.de [85.214.87.163]) by ozlabs.org (Postfix) with ESMTP id 788A2B6FA9 for ; Tue, 14 Jun 2011 09:14:05 +1000 (EST) Received: from localhost (localhost [127.0.0.1]) by theia.denx.de (Postfix) with ESMTP id F3DF728186; Tue, 14 Jun 2011 01:13:59 +0200 (CEST) X-Virus-Scanned: Debian amavisd-new at theia.denx.de Received: from theia.denx.de ([127.0.0.1]) by localhost (theia.denx.de [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id z3qUYWWeTl5O; Tue, 14 Jun 2011 01:13:59 +0200 (CEST) Received: from theia.denx.de (localhost [127.0.0.1]) by theia.denx.de (Postfix) with ESMTP id 68E0B28169; Tue, 14 Jun 2011 01:13:58 +0200 (CEST) Received: from localhost (localhost [127.0.0.1]) by theia.denx.de (Postfix) with ESMTP id 3A34328163 for ; Tue, 14 Jun 2011 01:13:56 +0200 (CEST) X-Virus-Scanned: Debian amavisd-new at theia.denx.de Received: from theia.denx.de ([127.0.0.1]) by localhost (theia.denx.de [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id n8QJoWsO+MId for ; Tue, 14 Jun 2011 01:13:55 +0200 (CEST) X-policyd-weight: NOT_IN_SBL_XBL_SPAMHAUS=-1.5 NOT_IN_SPAMCOP=-1.5 NOT_IN_BL_NJABL=-1.5 (only DNSBL check requested) Received: from smtp-out.google.com (smtp-out.google.com [74.125.121.67]) by theia.denx.de (Postfix) with ESMTPS id 788C428169 for ; Tue, 14 Jun 2011 01:13:54 +0200 (CEST) Received: from hpaq5.eem.corp.google.com (hpaq5.eem.corp.google.com [172.25.149.5]) by smtp-out.google.com with ESMTP id p5DNDd2w012528; Mon, 13 Jun 2011 16:13:39 -0700 Received: from sglass.mtv.corp.google.com (sglass.mtv.corp.google.com [172.22.72.144]) by hpaq5.eem.corp.google.com with ESMTP id p5DNDbWx032366; Mon, 13 Jun 2011 16:13:38 -0700 Received: by sglass.mtv.corp.google.com (Postfix, from userid 121222) id 6656B140C1B; Mon, 13 Jun 2011 16:13:37 -0700 (PDT) From: Simon Glass To: U-Boot Mailing List Date: Mon, 13 Jun 2011 16:13:11 -0700 Message-Id: <1308006792-22544-4-git-send-email-sjg@chromium.org> X-Mailer: git-send-email 1.7.3.1 In-Reply-To: <1308006792-22544-1-git-send-email-sjg@chromium.org> References: <1308006792-22544-1-git-send-email-sjg@chromium.org> MIME-Version: 1.0 X-System-Of-Record: true Cc: Andy Fleming Subject: [U-Boot] [PATCH v8 3/4] Add documentation for USB Host Networking X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.9 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: u-boot-bounces@lists.denx.de Errors-To: u-boot-bounces@lists.denx.de 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. Changes for v6: - Adjust documentation file according to Wolfgang's comments Signed-off-by: Simon Glass Tested-by: Eric Bénard --- doc/README.usb | 157 +++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 files changed, 156 insertions(+), 1 deletions(-) diff --git a/doc/README.usb b/doc/README.usb index 9aa4f62..a8a4058 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.