#####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####

# 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:

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.

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.