Subversion Repositories openrisc_2011-10-31

Introduction

Introduction

eCos support for developing USB ethernet peripherals

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 

linkend="usbseth-protocol">protocol between USB

host device driver and the

peripheral.

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

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 

linkend="usbseth-intro-scenarios">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

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 

linkend="usbseth-init">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>

When the USB-ethernet package is initialized by a call to 

linkend="usbseth-init">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

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 

linkend="usbseth-init">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

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 

url="http://www.usb.org/">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 

linkend="usbseth-protocol">Communication Protocol section.

The host-side device driver can be found in the 

class="directory">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 

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 

linkend="usbseth-init">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

linkend="usbseth-init">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.