Network Device -- USB-ethernet support for the eCos TCP/IP Stack
Description
If the USB peripheral involves running the eCos TCP/IP stack and that
-stack needs to use USB-ethernet as a transport layer (or as one of the
-transports), then the USB-ethernet package can provide a suitable
-network device driver. It is still necessary for higher-level code to
-perform appropriate initialization by calling usbs_eth_init, but
-after that it will be the TCP/IP stack rather than application code
-that transmits or receives ethernet frames.
Not all peripherals involving the USB-ethernet package will require a
-TCP/IP stack. Hence the provision of the network device is controlled
-by a configuration option CYGPKG_USBS_ETHDRV. By
-default this will be enabled if the TCP/IP package
-CYGPKG_NET is loaded, and disabled otherwise.
There are a number of other configuration options related to the
-network device. CYGFUN_USBS_ETHDRV_STATISTICS
-determines whether or not the package will maintain statistics, mainly
-intended for SNMP: by default this will be enabled if the SNMP support
-package CYGPKG_SNMPAGENT is loaded, and disabled
-otherwise. The name of the ethernet device is controlled by
-CYGDATA_USBS_ETHDRV_NAME, and has a default value
-of either eth0 or eth1
-depending on whether or not there is another network device driver
-present in the configuration.
Usually eCos network device drivers default to using DHCP for
-obtaining necessary information such as IP addresses. This is not
-appropriate for USB-ethernet devices. On the host-side the
-USB-ethernet network device will not exist until the USB peripheral
-has been plugged in and communication has been established. Therefore
-any DHCP daemon on the host would not be listening on that network
-device at the point that eCos requests its IP and other information. A
-related issue is that the use of DHCP would imply the presence of a
-DHCP daemon on every affected host machine, as opposed to a single
-daemon (plus backups) for the network as a whole. For these reasons
-the USB-ethernet package precludes the use of DHCP as a way of setting
-the IP address, instead requiring alternatives such as manual
-configuration.
The USB-ethernet package provides two main modes of operation. In the
-first mode it provides a network device
-driver for use by a TCP/IP stack running inside the USB
-peripheral. All incoming ethernet packages should be passed up the
-TCP/IP stack, and only the stack will generate outgoing packets. Apart
-from initialization and possibly
-certain control operations,
-higher-level code will not interact with the USB-ethernet package
-directly.
In the second mode there is no TCP/IP stack running inside the USB
-peripheral. For example, a simple USB-ethernet converter has an
-ethernet chip and a USB port: ethernet packets received by the
-ethernet chip need to be forwarded to the USB host, and ethernet
-packets sent by the USB host need to be sent out of the ethernet chip.
-usbs_eth_start_rx and
-usbs_eth_start_tx allow for this lower-level
-access to the USB-ethernet package.
The two modes of operation are mutually exclusive. If the network
-device driver mode is enabled then application code should communicate
-at the TCP/IP level, and not by using the lower-level functions.
-Instead, it is the network device driver that will make use of these
-functions, and it assumes that it has exclusive access. The package
-does not perform any locking.
The transmit and receive functions work in much the same way. The
-first argument identifies the usbs_eth
-structure that should be used. For the majority of applications this
-will be usbs_eth0. The second argument specifies
-the location of the ethernet packet; outgoing for
-usbs_eth_start_tx and incoming for
-usbs_eth_start_rx. This buffer should correspond
-to the protocol:
Outgoing packets can consist of up to 1516 bytes, consisting of a
-two-byte header specific to USB-ethernet followed by a standard
-ethernet frame (a header with 6-byte destination address, 6-byte
-source address and a further two bytes, followed by a payload of
-up to 1500 bytes). The two-byte USB-ethernet header consists simply of
-the size of the ethernet frame, i.e. the size of the rest of the
-packet not including the USB-ethernet header, with the least
-significant byte first.
For incoming packets the supplied buffer should usually be at least
-1516 bytes. There may be special circumstances in which a smaller
-buffer might be safe; for example, if the host-side device driver is
-modified to support only smaller packets. Once the packet has been
-received the buffer will contain a two-byte header specific to
-USB-ethernet, followed by a normal ethernet frame. The header
-gives the size of the ethernet frame, excluding the header, with the
-least significant byte first.
Both usbs_eth_start_tx and
-usbs_eth_start_rx are asynchronous: the transfer
-is started and, some time later, a completion function will be invoked.
-The third and fourth arguments to both
-usbs_eth_start_tx and
-usbs_eth_start_rx supply the completion function
-and an argument to that function respectively. The completion function
-will be invoked with three arguments: a pointer to the
-usbs_eth data structure, usually
-usbs_eth0; the supplied completion data ; and a
-return code field. A negative value indicates that an error occurred,
-for example -EPIPE if the connection between USB
-host and peripheral has been broken, or -EAGAIN if
-an endpoint has been halted. A positive value indicates the total size
-of the transfer, which should correspond to the size in the
-USB-ethernet header plus an additional two bytes for the header
-itself.
If the data transfer is succesful then the completion function will
-typically be invoked in DSR context rather than in thread context,
-although this depends on the implementation of the underlying USB
-device driver. Therefore the completion function is restricted in what
-it can do; in particular, it must not make any calls that will or may
-block such as locking a mutex or allocating memory. The kernel
-documentation should be consulted for more details of DSR's and
-interrupt handling generally. Note that if the transfer finishes
-quickly then the completion function may be invoked before
-usbs_eth_start_rx or
-usbs_eth_start_tx returns. This is especially
-likely to happen if the current thread is descheduled after starting
-the data transfer but before returning from these functions.
For transmit operations, it is possible for
-usbs_eth_start_tx to invoke the completion
-function immediately. If there is no current connection between host
-and target then the transmit will fail immediately with
--EPIPE. In addition the USB-ethernet package will
-check the destination MAC address and make sure that the ethernet
-frame really is intended for the host: either it must be for the
-address specified in the initialization call usbs_eth_init, or
-it must be a broadcast packet, or the host must have enabled
-promiscuous mode.
Introduction -- eCos support for developing USB ethernet peripherals
Introduction
The eCos USB-ethernet package provides additional support for USB
-peripherals that involve some sort of ethernet-style network. This can
-be a traditional ethernet, or it can involve some other networking
-technology that uses ethernet frames as a unit of transfer. It
-provides functions to transfer ethernet frames over the USB bus,
-handles certain control messages from the host, and optionally it can
-provide a network device driver for use by the eCos TCP/IP stack.
-The package comes with an example host-side device driver.
The USB-ethernet package is not tied to any specific hardware. It
-requires the presence of USB hardware and a suitable device driver,
-but not all USB peripherals involve ethernet communications. Hence the
-configuration system cannot load the package automatically for
-specific targets, in the way that a USB device driver or an ethernet
-driver can be loaded automatically. Instead, the package has to be
-added explicitly. When using the command line tools this will involve
-an operation like the following:
$ ecosconfig add usbs_eth
Typically, this will automatically cause the USB device driver to
-become active. Loading the USB-ethernet package automatically provides
-functionality for initialization,
-data transfer, and the handling of
-control messages and state
-changes. If the current configuration includes the eCos TCP/IP stack
-then the network device driver
-support will be enabled as well by default, allowing the stack to
-exchange ethernet frames over the USB bus.
There is a USB standard for a class of communication devices including
-ethernet. The package does not implement this standard, due to
-limitations in the hardware for which the package was first developed.
-Instead, the package uses its own protocol between USB
-host device driver and the
-peripheral.
Usage Scenarios
The USB-ethernet package can be used several different scenarios. In
-a simple scenario, the peripheral serves only to connect the USB host
-to a suitable network:
After initialization, and once the USB connection between host and
-peripheral has been established, higher-level code needs to detect
-packets that are intended for the host, and to forward these. This can
-be achieved by the low-level usbs_eth_start_tx
-function. Similarly, higher-level code needs to detect packets coming
-from the host, using usbs_eth_start_rx, and to
-forward these using the real network. As far as the host is concerned
-it is connected directly to the network. In this scenario there is no
-confusion about addresses: there is a single MAC address for the
-host/peripheral combination, corresponding to the connection to the
-real network, and it is this address which should be supplied during
-initialization.
In a more complicated scenario, there is a TCP/IP stack running inside
-the peripheral.
This involves the USB-ethernet package providing a service both to the
-host and to the eCos TCP/IP stack. It achieves the latter by acting as
-an eCos network device. Typically, the TCP/IP stack will be configured
-to act as a network bridge. The USB peripheral needs to examine the
-packets arriving over the real network. Some of these packets will be
-intended for the host, while others will be intended for the
-peripheral itself. To distinguish between these two scenarios, two
-distinct MAC addresses are needed: one for the host, and one for the
-peripheral. Similarly, packets sent by the host may have to be
-forwarded via the real network, or they may be intended for the TCP/IP
-stack inside the peripheral. Packets generated inside the peripheral's
-TCP/IP stack may need to be sent via the real network or over the USB
-bus. The network bridge software will have to take care of all these
-possibilities. Unusually for a network bridge, one of the network
-segments being bridged will only ever have one machine attached.
There are other possible usage scenarios. For example, the peripheral
-might not be attached to a real network at all. Instead it could be
-the USB host that acts as a network bridge, allowing a TCP/IP stack
-inside the peripheral to communicate with the outside world. The
-various details will depend on the exact type of peripheral being
-developed.
Example Host-side Device Driver -- Provide host-side support for the eCos USB-ethernet package
Description
The USB-ethernet package is supplied with a single host-side device
-driver. This driver has been developed against the Linux kernel
-2.2.16-22, as shipped with Red Hat 7. The driver is provided as is and
-should not be considered production quality: for example it only
-checks for a bogus vendor id 0x4242 rather than an
-official vendor id supplied by the USB Implementers Forum. Also, if the
-peripheral involves multiple configurations or multiple interfaces, it
-will fail to detect this. However, the driver can be used for simple
-testing and as the basis of a full device driver. Details of the
-protocol used between host and peripheral can be found in the Communication Protocol section.
The host-side device driver can be found in the host subdirectory of the USB-ethernet
-package, specifically the file ecos_usbeth.c, and
-comes with a Makefile. Both files may need
-to be modified for specific applications. For example, the vendor id
-table ecos_usbeth_implementations may need to be
-updated for the specific USB peripheral being built. The
-Makefile assumes that the Linux kernel sources
-reside in /usr/src/linux, and
-that the kernel has already been configured and built. Assuming this
-is the case, the device driver can be built simply by invoking
-make with no additional arguments. This will result
-in a dynamically loadable kernel module,
-ecos_usbeth.o, in the current directory.
Note: As normal for Linux kernel builds, the generated files such as
-ecos_usbeth.o live in the same directory as the
-source tree. This is very different from eCos where the source tree
-(or component repository) is kept separate from any builds. There may
-be problems if the component repository is kept read-only or if it is
-put under source code control. Any such problems can be avoided by
-making a copy of the host
-subdirectory and building that copy.
Loading the kernel module into the current system requires root
-privileges. If the generic USB support is also a loadable module and
-has not been loaded already, this must happen first:
Depending on the host hardware, the uhci or
-usb-ohci modules may be more appropriate. Loading
-the generic USB module will typically result in a number of messages
-to the logfile /var/log/messages, giving details
-of the specific host-side hardware that has been detected plus any
-hubs. The next step is to load the USB-ethernet module:
# insmod ecos_usbeth.o
This should result in a number of additional diagnostics in the
-logfile:
If a suitable USB peripheral is now connected the host will detect
-this, assign an address in the local USB network, obtain enumeration
-data, and find a suitable device driver. Assuming the peripheral and
-device driver agree on the supported vendor ids, the
-ecos_usbeth.o module will be selected and this
-will be reported in the system log:
Apr 1 18:04:12 grumpy kernel: usb.c: USB new device connect, assigned device number 3
-Apr 1 18:04:12 grumpy kernel: eCos-based USB ethernet peripheral active at eth1
What can happen next depends very much on the software that is running
-on top of the USB-ethernet package inside the peripheral. For example,
-if there is a TCP/IP stack then it should be possible to bring up a
-network connection between host and peripheral using
-ifconfig.
\ No newline at end of file
Index: simple.png
===================================================================
Cannot display: file marked as a binary type.
svn:mime-type = application/octet-stream
Index: simple.png
===================================================================
--- simple.png (revision 174)
+++ simple.png (nonexistent)
simple.png
Property changes :
Deleted: svn:mime-type
## -1 +0,0 ##
-application/octet-stream
\ No newline at end of property
Index: makefile
===================================================================
--- makefile (revision 174)
+++ makefile (nonexistent)
@@ -1,55 +0,0 @@
-#=============================================================================
-#
-# makefile
-#
-# For building the USB-ethernet package documentation
-#
-#=============================================================================
-#####ECOSGPLCOPYRIGHTBEGIN####
-## -------------------------------------------
-## This file is part of eCos, the Embedded Configurable Operating System.
-## Copyright (C) 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.
-##
-## eCos is free software; you can redistribute it and/or modify it under
-## the terms of the GNU General Public License as published by the Free
-## Software Foundation; either version 2 or (at your option) any later version.
-##
-## eCos is distributed in the hope that it will be useful, but WITHOUT ANY
-## WARRANTY; without even the implied warranty of MERCHANTABILITY or
-## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
-## for more details.
-##
-## You should have received a copy of the GNU General Public License along
-## with eCos; if not, write to the Free Software Foundation, Inc.,
-## 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
-##
-## As a special exception, if other files instantiate templates or use macros
-## or inline functions from this file, or you compile this file and link it
-## with other works to produce a work based on this file, this file does not
-## by itself cause the resulting work to be covered by the GNU General Public
-## License. However the source code for this file must still be made available
-## in accordance with section (3) of the GNU General Public License.
-##
-## This exception does not invalidate any other reasons why a work based on
-## this file might be covered by the GNU General Public License.
-##
-## Alternative licenses for eCos may be arranged by contacting Red Hat, Inc.
-## at http://sources.redhat.com/ecos/ecos-license/
-## -------------------------------------------
-#####ECOSGPLCOPYRIGHTEND####
-#=============================================================================
-#####DESCRIPTIONBEGIN####
-#
-# Author(s): bartv
-# Date: 2001-01-11
-#####DESCRIPTIONEND####
-#=============================================================================
-
-TOPLEVEL := ../../../../../..
-MAIN_SGML := usbseth.sgml
-MAIN_HTML := io-usb-slave-eth.html
-MAIN_PDF := io-usb-slave-eth.pdf
-OTHER_SGML :=
-PICTURES := simple tcpip
-
-include $(TOPLEVEL)/pkgconf/rules.doc
Index: simple.fig
===================================================================
--- simple.fig (revision 174)
+++ simple.fig (nonexistent)
@@ -1,23 +0,0 @@
-#FIG 3.2
-Portrait
-Center
-Inches
-Letter
-100.00
-Single
--2
-1200 2
-2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
- 600 600 2400 600 2400 2400 600 2400 600 600
-2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2
- 2400 1500 4200 1500
-2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
- 4200 600 6000 600 6000 2400 4200 2400 4200 600
-2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2
- 6000 1500 6600 1500
-2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2
- 6600 300 6600 2700
-4 0 0 50 0 0 12 0.0000 4 135 675 3000 1425 USB bus\001
-4 0 0 50 0 0 12 0.0000 4 135 735 1200 1425 USB host\001
-4 0 0 50 0 0 12 0.0000 4 180 1155 4500 1425 USB peripheral\001
-4 0 0 50 0 0 12 0.0000 4 135 945 6150 2925 real network\001
Index: usbseth.sgml
===================================================================
--- usbseth.sgml (revision 174)
+++ usbseth.sgml (nonexistent)
@@ -1,810 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- eCos Support for Developing USB-ethernet Peripherals
-
-
-
-
-
-Introduction
-
-
-Introduction
-eCos support for developing USB ethernet peripherals
-
-
-Introduction
-
-The eCos USB-ethernet package provides additional support for USB
-peripherals that involve some sort of ethernet-style network. This can
-be a traditional ethernet, or it can involve some other networking
-technology that uses ethernet frames as a unit of transfer. It
-provides functions to transfer ethernet frames over the USB bus,
-handles certain control messages from the host, and optionally it can
-provide a network device driver for use by the eCos TCP/IP stack.
-The package comes with an example host-side device driver.
-
-
-The USB-ethernet package is not tied to any specific hardware. It
-requires the presence of USB hardware and a suitable device driver,
-but not all USB peripherals involve ethernet communications. Hence the
-configuration system cannot load the package automatically for
-specific targets, in the way that a USB device driver or an ethernet
-driver can be loaded automatically. Instead, the package has to be
-added explicitly. When using the command line tools this will involve
-an operation like the following:
-
-
-$ ecosconfig add usbs_eth
-
-
-Typically, this will automatically cause the USB device driver to
-become active. Loading the USB-ethernet package automatically provides
-functionality for initialization,
-data transfer, and the handling of
-control messages and state
-changes. If the current configuration includes the eCos TCP/IP stack
-then the network device driver
-support will be enabled as well by default, allowing the stack to
-exchange ethernet frames over the USB bus.
-
-
-There is a USB standard for a class of communication devices including
-ethernet. The package does not implement this standard, due to
-limitations in the hardware for which the package was first developed.
-Instead, the package uses its own protocol between USB
-host device driver and the
-peripheral.
-
-
-
-Usage Scenarios
-
-The USB-ethernet package can be used several different scenarios. In
-a simple scenario, the peripheral serves only to connect the USB host
-to a suitable network:
-
-
-
-
-
-
-
-
-
-After initialization, and once the USB connection between host and
-peripheral has been established, higher-level code needs to detect
-packets that are intended for the host, and to forward these. This can
-be achieved by the low-level usbs_eth_start_tx
-function. Similarly, higher-level code needs to detect packets coming
-from the host, using usbs_eth_start_rx, and to
-forward these using the real network. As far as the host is concerned
-it is connected directly to the network. In this scenario there is no
-confusion about addresses: there is a single MAC address for the
-host/peripheral combination, corresponding to the connection to the
-real network, and it is this address which should be supplied during
-initialization.
-
-
-In a more complicated scenario, there is a TCP/IP stack running inside
-the peripheral.
-
-
-
-
-
-
-
-
-
-This involves the USB-ethernet package providing a service both to the
-host and to the eCos TCP/IP stack. It achieves the latter by acting as
-an eCos network device. Typically, the TCP/IP stack will be configured
-to act as a network bridge. The USB peripheral needs to examine the
-packets arriving over the real network. Some of these packets will be
-intended for the host, while others will be intended for the
-peripheral itself. To distinguish between these two scenarios, two
-distinct MAC addresses are needed: one for the host, and one for the
-peripheral. Similarly, packets sent by the host may have to be
-forwarded via the real network, or they may be intended for the TCP/IP
-stack inside the peripheral. Packets generated inside the peripheral's
-TCP/IP stack may need to be sent via the real network or over the USB
-bus. The network bridge software will have to take care of all these
-possibilities. Unusually for a network bridge, one of the network
-segments being bridged will only ever have one machine attached.
-
-
-There are other possible usage scenarios. For example, the peripheral
-might not be attached to a real network at all. Instead it could be
-the USB host that acts as a network bridge, allowing a TCP/IP stack
-inside the peripheral to communicate with the outside world. The
-various details will depend on the exact type of peripheral being
-developed.
-
-
-
-
-
-
-
-
-
-Initializing the USB-ethernet Package
-
-
-usbs_eth_init
-Initializing the USB-ethernet Package
-
-
-
-
-
-#include <cyg/io/usb/usbs_eth.h>
-
-
-void usbs_eth_init
-usbs_eth* usbeth
-usbs_control_endpoint* ep0
-usbs_rx_endpoint* ep1
-usbs_tx_endpoint* ep2
-unsigned char* mac_address
-
-
-
-
-Description
-
-The USB-ethernet package is not tied to any specific hardware. It
-requires certain functionality: there must be USB-slave hardware
-supported by a device driver; there must also be two endpoints for
-bulk transfers between host and peripheral, one for each direction;
-there must also be a control endpoint, although of course that is
-implicit with any USB hardware.
-
-
-However, USB-slave hardware may well provide more endpoints than the
-minimum required for ethernet support. Some of those endpoints might
-be used by other packages, while other endpoints might be used
-directly by the application, or might not be needed for the peripheral
-being built. There is also the possibility of a USB peripheral that
-supports multiple configurations, with the ethernet support active in
-only some of those configurations. The USB-ethernet package has no
-knowledge about any of this, so it relies on higher-level code to tell
-it which endpoints should be used and other information. This is the
-purpose of the usbs_eth_init function.
-
-
-The first argument identifies the specific
-usbs_eth data structure that is affected. It
-is expected that the vast majority of affected applications will only
-provide a single USB-ethernet device to a single host, and the package
-automatically provides a suitable data structure
-usbs_eth0 to support this. If multiple
-usbs_eth structures are needed for some
-reason then these need to be instantiated by other code, and each one
-needs to be initialised by a call to
-usbs_eth_init().
-
-
-The next three arguments identify the endpoints that should be used
-for USB communications: a control endpoint, a receive endpoint for
-ethernet packets coming from the host to the peripheral, and a
-transmit endpoint for ethernet packets going in the other direction.
-Obviously all three endpoints should be provided by the same USB
-hardware. The USB-ethernet package assumes that it has sole access to
-the receive and transmit endpoints, subject to the use of
-usbs_eth_disable and
-usbs_eth_enable control functions. The package
-also assumes that no other code is interested in USB state changes or
-class control messages: it installs handlers
-usbs_eth_state_change_handler
-and
-usbs_eth_class_control_handler
-in the control endpoint. If any other code does need to handle USB
-state changes or class control messages then replacement handlers
-should be installed after the call to
-usbs_eth_init, and those replacements should
-invoke the USB-ethernet ones when appropriate.
-
-
-The final argument to usbs_eth_init specifies
-the MAC address (or Ethernet Station Address) that should be provided
-to the host-side device driver. Since the USB-ethernet package does not
-interact directly with a real ethernet device it cannot obtain the MAC
-address from any hardware. Instead, it must be supplied by higher-level
-code. The details depend on the scenario in which the
-USB-ethernet package is being used.
-
-
-The call to usbs_eth_init should normally happen
-after the enumeration data has been provided but before the underlying
-USB device driver has been started. If the USB device were to be
-started first then a connection between host and peripheral could be
-established immediately, and the host-side device driver would attempt
-to contact the USB-ethernet package for information such as the MAC
-address.
-
-
-int
-main(int argc, char** argv)
-{
- unsigned char host_MAC[6] = { 0x40, 0x5d, 0x90, 0xa9, 0xbc, 0x02 };
-
- usbs_sa11x0_ep0.enumeration_data = &usb_enum_data;
- …
- usbs_eth_init(&usbs_eth0, &usbs_sa11x0_ep0, &usbs_sa11x0_ep1, &usbs_sa11x0_ep2, host_MAC);
- …
- usbs_start(&usbs_sa11x0_ep0);
- …
-}
-
-
-
-
-
-
-
-
-
-
-USB-ethernet Data Transfers
-
-
-USB-ethernet Data Transfers
-Exchanging ethernet packets with the USB host
-
-
-
-
-
-#include <cyg/io/usb/usbs_eth.h>
-
-
-
-void usbs_eth_start_rx
-usbs_eth* usbseth
-unsigned char* buffer
-void (*)(usbs_eth*, void*, int) complete_fn
-void* complete_data
-
-
-
-void usbs_eth_start_tx
-usbs_eth* usbseth
-unsigned char* buffer
-void (*)(usbs_eth*, void*, int) complete_fn
-void* complete_data
-
-
-
-
-
-Description
-
-The USB-ethernet package provides two main modes of operation. In the
-first mode it provides a network device
-driver for use by a TCP/IP stack running inside the USB
-peripheral. All incoming ethernet packages should be passed up the
-TCP/IP stack, and only the stack will generate outgoing packets. Apart
-from initialization and possibly
-certain control operations,
-higher-level code will not interact with the USB-ethernet package
-directly.
-
-
-In the second mode there is no TCP/IP stack running inside the USB
-peripheral. For example, a simple USB-ethernet converter has an
-ethernet chip and a USB port: ethernet packets received by the
-ethernet chip need to be forwarded to the USB host, and ethernet
-packets sent by the USB host need to be sent out of the ethernet chip.
-usbs_eth_start_rx and
-usbs_eth_start_tx allow for this lower-level
-access to the USB-ethernet package.
-
-
-The two modes of operation are mutually exclusive. If the network
-device driver mode is enabled then application code should communicate
-at the TCP/IP level, and not by using the lower-level functions.
-Instead, it is the network device driver that will make use of these
-functions, and it assumes that it has exclusive access. The package
-does not perform any locking.
-
-
-The transmit and receive functions work in much the same way. The
-first argument identifies the usbs_eth
-structure that should be used. For the majority of applications this
-will be usbs_eth0. The second argument specifies
-the location of the ethernet packet; outgoing for
-usbs_eth_start_tx and incoming for
-usbs_eth_start_rx. This buffer should correspond
-to the protocol:
-
-
-
-
-Outgoing packets can consist of up to 1516 bytes, consisting of a
-two-byte header specific to USB-ethernet followed by a standard
-ethernet frame (a header with 6-byte destination address, 6-byte
-source address and a further two bytes, followed by a payload of
-up to 1500 bytes). The two-byte USB-ethernet header consists simply of
-the size of the ethernet frame, i.e. the size of the rest of the
-packet not including the USB-ethernet header, with the least
-significant byte first.
-
-
-
-
-For incoming packets the supplied buffer should usually be at least
-1516 bytes. There may be special circumstances in which a smaller
-buffer might be safe; for example, if the host-side device driver is
-modified to support only smaller packets. Once the packet has been
-received the buffer will contain a two-byte header specific to
-USB-ethernet, followed by a normal ethernet frame. The header
-gives the size of the ethernet frame, excluding the header, with the
-least significant byte first.
-
-
-
-
-Both usbs_eth_start_tx and
-usbs_eth_start_rx are asynchronous: the transfer
-is started and, some time later, a completion function will be invoked.
-The third and fourth arguments to both
-usbs_eth_start_tx and
-usbs_eth_start_rx supply the completion function
-and an argument to that function respectively. The completion function
-will be invoked with three arguments: a pointer to the
-usbs_eth data structure, usually
-usbs_eth0; the supplied completion data ; and a
-return code field. A negative value indicates that an error occurred,
-for example -EPIPE if the connection between USB
-host and peripheral has been broken, or -EAGAIN if
-an endpoint has been halted. A positive value indicates the total size
-of the transfer, which should correspond to the size in the
-USB-ethernet header plus an additional two bytes for the header
-itself.
-
-
-If the data transfer is succesful then the completion function will
-typically be invoked in DSR context rather than in thread context,
-although this depends on the implementation of the underlying USB
-device driver. Therefore the completion function is restricted in what
-it can do; in particular, it must not make any calls that will or may
-block such as locking a mutex or allocating memory. The kernel
-documentation should be consulted for more details of DSR's and
-interrupt handling generally. Note that if the transfer finishes
-quickly then the completion function may be invoked before
-usbs_eth_start_rx or
-usbs_eth_start_tx returns. This is especially
-likely to happen if the current thread is descheduled after starting
-the data transfer but before returning from these functions.
-
-
-For transmit operations, it is possible for
-usbs_eth_start_tx to invoke the completion
-function immediately. If there is no current connection between host
-and target then the transmit will fail immediately with
--EPIPE. In addition the USB-ethernet package will
-check the destination MAC address and make sure that the ethernet
-frame really is intended for the host: either it must be for the
-address specified in the initialization call usbs_eth_init, or
-it must be a broadcast packet, or the host must have enabled
-promiscuous mode.
-
-
-
-
-
-
-
-
-
-
-USB-ethernet State Handling
-
-
-USB-ethernet State Handling
-Maintaining the USB-ethernet connection with the host
-
-
-
-
-
-#include <cyg/io/usb/usbs_eth.h>
-
-
-
-usbs_control_return usbs_eth_class_control_handler
-usbs_control_endpoint* ep0
-void* callback_data
-
-
-
-void usbs_eth_state_change_handler
-usbs_control_endpoint* ep0
-void* callback_data
-usbs_state_change change
-int old_state
-
-
-
-void usbs_eth_disable
-usbs_eth* usbseth>
-
-
-void usbs_eth_enable
-usbs_eth* usbseth>
-
-
-
-
-
-Description
-
-When the USB-ethernet package is initialized by a call to usbs_eth_init it
-installs usbs_eth_state_change_handler to handle
-USB state changes. This allows the package to detect when the
-connection between the host and the peripheral is established or
-broken, resulting in internal calls to
-usbs_eth_enable and
-usbs_eth_disable respectively. This is
-appropriate if no other code needs to access the USB device. However,
-if there is other code, either other USB-related packages or the
-application itself, that needs to perform I/O over the USB bus, then
-typically the USB-ethernet package should not have exclusive access to
-state change events. Instead, the assumption is that higher-level
-code, typically provided by the application, will install an
-alternative state change handler in the control endpoint data
-structure after the call to usbs_eth_init. This
-alternative handler will either chain into
-usbs_eth_state_change_handler when appropriate,
-or else it will invoke usbs_eth_enable and
-usbs_eth_disable directly. For further details of
-state change handlers and control endpoints generally, see the
-documentation for the common USB-slave package.
-
-
-Similarly, usbs_eth_init will install
-usbs_eth_class_control_handler in the control
-endpoint data structure as the appropriate handler for class-specific
-USB control messages. This code will handle the ethernet-specific
-control messages , for example
-requests by the host to enable or disable promiscuous mode or to
-obtain the MAC address. If the USB device is not shared with any other
-code then this is both necessary and sufficient. However, if other code
-is involved and if that code also needs to process certain control
-messages, higher-level code should install its own handler and chain
-to the USB-ethernet one when appropriate. It should be noted that the
-request code is encoded in just a single byte, so there is a real
-possibility that exactly the same number will be used by different
-protocols for different requests. Any such problems will have to be
-identified and resolved by application developers, and may involve
-modifying the source code for the USB-ethernet package.
-
-
-As an alternative to chaining the state change handler, higher-level
-code can instead call usbs_eth_disable and
-usbs_eth_enable directly. These functions may
-also be called if the USB-ethernet package should become inactive for
-reasons not related directly to events on the USB bus. The main effect
-of usbs_eth_enable is to restart receive
-operations and to allow transmits. The main effect of
-usbs_eth_disable is to block further transmits:
-any current receive operations need to be aborted at the USB level,
-for example by halting the appropriate endpoint.
-
-
-
-
-
-
-
-
-
-
-Network Device for the eCos TCP/IP Stack
-
-
-Network Device
-USB-ethernet support for the eCos TCP/IP Stack
-
-
-Description
-
-If the USB peripheral involves running the eCos TCP/IP stack and that
-stack needs to use USB-ethernet as a transport layer (or as one of the
-transports), then the USB-ethernet package can provide a suitable
-network device driver. It is still necessary for higher-level code to
-perform appropriate initialization by calling usbs_eth_init, but
-after that it will be the TCP/IP stack rather than application code
-that transmits or receives ethernet frames.
-
-
-Not all peripherals involving the USB-ethernet package will require a
-TCP/IP stack. Hence the provision of the network device is controlled
-by a configuration option CYGPKG_USBS_ETHDRV. By
-default this will be enabled if the TCP/IP package
-CYGPKG_NET is loaded, and disabled otherwise.
-
-
-There are a number of other configuration options related to the
-network device. CYGFUN_USBS_ETHDRV_STATISTICS
-determines whether or not the package will maintain statistics, mainly
-intended for SNMP: by default this will be enabled if the SNMP support
-package CYGPKG_SNMPAGENT is loaded, and disabled
-otherwise. The name of the ethernet device is controlled by
-CYGDATA_USBS_ETHDRV_NAME, and has a default value
-of either eth0 or eth1
-depending on whether or not there is another network device driver
-present in the configuration.
-
-
-Usually eCos network device drivers default to using DHCP for
-obtaining necessary information such as IP addresses. This is not
-appropriate for USB-ethernet devices. On the host-side the
-USB-ethernet network device will not exist until the USB peripheral
-has been plugged in and communication has been established. Therefore
-any DHCP daemon on the host would not be listening on that network
-device at the point that eCos requests its IP and other information. A
-related issue is that the use of DHCP would imply the presence of a
-DHCP daemon on every affected host machine, as opposed to a single
-daemon (plus backups) for the network as a whole. For these reasons
-the USB-ethernet package precludes the use of DHCP as a way of setting
-the IP address, instead requiring alternatives such as manual
-configuration.
-
-
-
-
-
-
-
-
-
-
-Example Host-side Device Driver
-
-
-Example Host-side Device Driver
-Provide host-side support for the eCos USB-ethernet package
-
-
-Description
-
-The USB-ethernet package is supplied with a single host-side device
-driver. This driver has been developed against the Linux kernel
-2.2.16-22, as shipped with Red Hat 7. The driver is provided as is and
-should not be considered production quality: for example it only
-checks for a bogus vendor id 0x4242 rather than an
-official vendor id supplied by the USB Implementers Forum. Also, if the
-peripheral involves multiple configurations or multiple interfaces, it
-will fail to detect this. However, the driver can be used for simple
-testing and as the basis of a full device driver. Details of the
-protocol used between host and peripheral can be found in the Communication Protocol section.
-
-
-The host-side device driver can be found in the host subdirectory of the USB-ethernet
-package, specifically the file ecos_usbeth.c, and
-comes with a Makefile. Both files may need
-to be modified for specific applications. For example, the vendor id
-table ecos_usbeth_implementations may need to be
-updated for the specific USB peripheral being built. The
-Makefile assumes that the Linux kernel sources
-reside in /usr/src/linux, and
-that the kernel has already been configured and built. Assuming this
-is the case, the device driver can be built simply by invoking
-make with no additional arguments. This will result
-in a dynamically loadable kernel module,
-ecos_usbeth.o, in the current directory.
-
-
-
-As normal for Linux kernel builds, the generated files such as
-ecos_usbeth.o live in the same directory as the
-source tree. This is very different from eCos where the source tree
-(or component repository) is kept separate from any builds. There may
-be problems if the component repository is kept read-only or if it is
-put under source code control. Any such problems can be avoided by
-making a copy of the host
-subdirectory and building that copy.
-
-
-
-Loading the kernel module into the current system requires root
-privileges. If the generic USB support is also a loadable module and
-has not been loaded already, this must happen first:
-
-
-# insmod usb-uhci
-Using /lib/modules/2.2.16-22/usb/usb-uhci.o
-
-
-Depending on the host hardware, the uhci or
-usb-ohci modules may be more appropriate. Loading
-the generic USB module will typically result in a number of messages
-to the logfile /var/log/messages, giving details
-of the specific host-side hardware that has been detected plus any
-hubs. The next step is to load the USB-ethernet module:
-
-
-# insmod ecos_usbeth.o
-
-
-This should result in a number of additional diagnostics in the
-logfile:
-
-
-Apr 1 18:01:08 grumpy kernel: eCos USB-ethernet device driver
-Apr 1 18:01:08 grumpy kernel: usb.c: registered new driver ecos_usbeth
-
-
-If a suitable USB peripheral is now connected the host will detect
-this, assign an address in the local USB network, obtain enumeration
-data, and find a suitable device driver. Assuming the peripheral and
-device driver agree on the supported vendor ids, the
-ecos_usbeth.o module will be selected and this
-will be reported in the system log:
-
-
-Apr 1 18:04:12 grumpy kernel: usb.c: USB new device connect, assigned device number 3
-Apr 1 18:04:12 grumpy kernel: eCos-based USB ethernet peripheral active at eth1
-
-
-What can happen next depends very much on the software that is running
-on top of the USB-ethernet package inside the peripheral. For example,
-if there is a TCP/IP stack then it should be possible to bring up a
-network connection between host and peripheral using
-ifconfig.
-
-
-
-
-
-
-
-
-
-
-Communication Protocol
-
-
-Communication Protocol
-Protocol used between the host-side device driver and the eCos
-USB-ethernet package
-
-
-Description
-
-There is a USB standard for the protocol to be used between the host
-and a class of communication devices, including ethernet. However, the
-eCos USB-ethernet package does not implement this protocol: the target
-hardware for which the package was first developed had certain
-limitations, and could not implement the standard. Instead, the package
-implements a simple new protocol.
-
-
-A USB-ethernet peripheral involves bulk transfers on two endpoints:
-one endpoint will be used for packets from host to peripheral and the
-other will be used for the opposite direction. Transfers in both
-directions are variable length, with a lower limit of 16 bytes and an
-upper limit of 1516 bytes. The first two bytes of each transfer
-constitute a header specific to USB-ethernet. The next 14 bytes form
-the normal header for an ethernet frame: destination MAC address,
-source MAC address, and a protocol field. The remaining data, up to
-1500 bytes, are the payload. The first two bytes give the size of the
-ethernet frame, least significant byte first, with a value between 14
-and 1514.
-
-
-For example an ARP request from host to peripheral involves an
-ethernet frame of 42 bytes (0x002A), with the usual 14-byte header and
-a 28-byte payload. The destination is the broadcast address
-0xFFFFFFFFFFFF. The source depends on the MAC address specified for
-the host in the call to usbs_eth_init, e.g.
-0x405D90A9BC02. The remaining data is as specified by the appropriate
-IETF RFC's. The actual bulk
-USB transfer involves the following sequence of 44 bytes:
-
-
-2a 00 ff ff ff ff ff ff 40 5d 90 a9 bc 02 08 06
-00 01 08 00 06 04 00 01 40 5d 90 a9 bc 02 0a 00
-00 01 00 00 00 00 00 00 0a 00 00 02
-
-
-In addition there are two control messages. These will be sent by the
-host to endpoint 0, the control endpoint, and by default they will
-be handled by
-usbs_eth_class_control_handler. If class-specific
-control messages are intercepted by other code then it is the
-responsibility of that code to invoke the USB-ethernet handler when
-appropriate.
-
-
-The first control message can be used by the host to obtain a MAC
-address:
-
-
-#define ECOS_USBETH_CONTROL_GET_MAC_ADDRESS 0x01
-
-
-The control message's type field should specify IN as the direction.
-The request field should be 0x01. The length fields
-should specify a size of 6 bytes. The remaining fields of the control
-message will be ignored by the USB-ethernet package. The response
-consists of the 6-byte MAC address supplied by the initialization call
-usbs_eth_init.
-
-
-The second control message can be used by the host to enable or
-disable promiscuous mode.
-
-
-#define ECOS_USBETH_CONTROL_SET_PROMISCUOUS_MODE 0x02
-
-
-This control message involves no further data so the length field
-should be set to 0. The value field should be non-zero to enable
-promiscuous mode, zero to disable it. The request field should be
-0x02. The remaining fields in the control message
-will be ignored. It is the responsibility of the host-side device
-driver to keep track of whether or not promiscuous mode is currently
-enabled. It will be disabled when the peripheral changes to
-Configured state, typically at the point where the host-side device
-driver has been activated.
-
-
-
-
-
-
-
-
-
Index: usbseth-control.html
===================================================================
--- usbseth-control.html (revision 174)
+++ usbseth-control.html (nonexistent)
@@ -1,309 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-USB-ethernet State Handling
eCos Support for Developing USB-ethernet Peripherals
void usbs_eth_state_change_handler(usbs_control_endpoint* ep0, void* callback_data, usbs_state_change change, int old_state);
void usbs_eth_disable(usbs_eth* usbseth>);
void usbs_eth_enable(usbs_eth* usbseth>);
Description
When the USB-ethernet package is initialized by a call to usbs_eth_init it
-installs usbs_eth_state_change_handler to handle
-USB state changes. This allows the package to detect when the
-connection between the host and the peripheral is established or
-broken, resulting in internal calls to
-usbs_eth_enable and
-usbs_eth_disable respectively. This is
-appropriate if no other code needs to access the USB device. However,
-if there is other code, either other USB-related packages or the
-application itself, that needs to perform I/O over the USB bus, then
-typically the USB-ethernet package should not have exclusive access to
-state change events. Instead, the assumption is that higher-level
-code, typically provided by the application, will install an
-alternative state change handler in the control endpoint data
-structure after the call to usbs_eth_init. This
-alternative handler will either chain into
-usbs_eth_state_change_handler when appropriate,
-or else it will invoke usbs_eth_enable and
-usbs_eth_disable directly. For further details of
-state change handlers and control endpoints generally, see the
-documentation for the common USB-slave package.
Similarly, usbs_eth_init will install
-usbs_eth_class_control_handler in the control
-endpoint data structure as the appropriate handler for class-specific
-USB control messages. This code will handle the ethernet-specific
-control messages , for example
-requests by the host to enable or disable promiscuous mode or to
-obtain the MAC address. If the USB device is not shared with any other
-code then this is both necessary and sufficient. However, if other code
-is involved and if that code also needs to process certain control
-messages, higher-level code should install its own handler and chain
-to the USB-ethernet one when appropriate. It should be noted that the
-request code is encoded in just a single byte, so there is a real
-possibility that exactly the same number will be used by different
-protocols for different requests. Any such problems will have to be
-identified and resolved by application developers, and may involve
-modifying the source code for the USB-ethernet package.
As an alternative to chaining the state change handler, higher-level
-code can instead call usbs_eth_disable and
-usbs_eth_enable directly. These functions may
-also be called if the USB-ethernet package should become inactive for
-reasons not related directly to events on the USB bus. The main effect
-of usbs_eth_enable is to restart receive
-operations and to allow transmits. The main effect of
-usbs_eth_disable is to block further transmits:
-any current receive operations need to be aborted at the USB level,
-for example by halting the appropriate endpoint.