Name

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.

Name

Synopsis

#include <cyg/io/usb/usbs_eth.h>

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:

1. 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.

2. 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.

Name

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.

Name

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.

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.

Name

Synopsis

#include <cyg/io/usb/usbs_eth.h>

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.