usbs_eth.h

eCos操作系统源码

#ifndef CYGONCE_USBS_ETH_H
#define  CYGONCE_USBS_ETH_H_
//==========================================================================
//
//      include/usbs_eth.h
//
//      Description of the USB slave-side ethernet support
//
//==========================================================================
//####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
// Contributors: bartv
// Date:         2000-10-04
// Purpose:
// Description:  USB slave-side ethernet support
//
//
//####DESCRIPTIONEND####
//==========================================================================

#ifdef __cplusplus
extern "C" {
#endif
    
//
// The primary purpose of the USB slave-side ethernet code is to
// provide an ethernet service for the host. Essentially this means
// the following:
//
// 1) the host can transmit an ethernet frame to the USB peripheral.
//    This frame is received by the code in this package and then
//    passed up to higher-level code for processing. Typically the
//    frame will originate from a TCP/IP stack running inside the
//    host, and the higher-level code will forward the frame via a
//    real ethernet chip or some other ethernet-style device.
//
// 2) higher-level code will provide ethernet frames to be sent to
//    the host, usually to a TCP/IP stack running on the host. The
//    exact source of the ethernet frame is not known.
//
// 3) the host may initiate a number of control operations, for
//    example it may request the MAC address or it may want to
//    control the filtering mode (e.g. enable promiscuous mode).
//
// 4) there are USB control-related operations, for example actions
//    to be taken when the peripheral is disconnected from the
//    bus or when the host wants to disable the ethernet interface.
//
// It is possible to develop a USB ethernet peripheral that does not
// involve a TCP/IP stack inside the peripheral, in fact that is the
// most common implementation. Instead a typical peripheral would
// involve a USB port, an ethernet port, and a cheap microcontroller
// just powerful enough to forward packets between the two. The eCos
// USB code can be used in this way, and the primary external
// interface provides enough functionality for this to work.
//
//                  +---------------+   ethernet
//   +----+         |               |     |
//   |    |   USB   |      app      |     |
//   |host|---------|     /   \     |-----o
//   |    |         |    /     \    |     |
//   +----+         | USB-eth   eth |     |
//                  +---------------+     |
//                   USB peripheral
//
// Note that the USB-ethernet code does not know anything about the
// real ethernet device or what the application gets up to, it just
// provides an interface to the app. The above represents just one
// possible use for a USB-ethernet device.
//
// Also worth mentioning: when the host TCP/IP stack requests the MAC
// address USB-eth would normally respond with the MAC address for the
// real ethernet device. That way things like host-side DHCP should
// just work.
//
// Alternatively for some applications it is desirable to run a TCP/IP
// stack inside the peripheral as well as on the host. This makes
// things a fair bit more complicated, something like this.
//
//                  +---------------+
//                  |      app      |
//                  |       |       |  ethernet
//   +----+         |       |       |     |
//   |    |   USB   |     TCP/IP    |     |
//   |host|---------|     /   \     |-----o
//   |    |         |    /     \    |     |
//   +----+         | USB-eth   eth |     |
//                  +---------------+     |
//                   USB peripheral
//
// 
// Usually this will involve enabling the bridge code in the TCP/IP
// stack, or possibly performing some sort of bridging below the
// TCP/IP stack. One way of getting things to work is to view the
// USB connection as a small ethernet segment with just two
// attached machines, the host and the peripheral. The two will
// need separate MAC addresses, in addition to the MAC address
// for the real ethernet device. This way the bridge code
// sees things the way it expects.    
//
// There will still be some subtle differences between a setup like
// this and a conventional ethernet bridge, mainly because there
// is a host-side TCP/IP stack which can perform control operations.
// For example the host stack may request that USB-eth go into
// promiscuous mode. A conventional ethernet bridge just deals
// with ethernet segments and does not need to worry about
// control requests coming in from one of the segments.
//
// It is not absolutely essential that there is another network.
// However without another network this setup would look to the host
// like an ethernet segment with just two machines attached to it, the
// host itself and the USB peripheral, yet it still involves all the
// complexities of ethernet such as broadcast masks and IP subnets.
// Anything along these lines is likely to prove somewhat confusing,
// and the USB peripheral should probably act like some other class
// of USB device instead.
//
// One special setup has the host acting as a bridge to another
// network, rather than the peripheral. This might make sense for
// mobile peripherals such as PDA's, as a way of connecting the
// peripheral to an existing LAN without needing a LAN adapter.
// Enabling bridging in the host may be a complex operation, limiting
// the applicability of such a setup.
//
// This package will only implement the eCos network driver interface
// if explicitly enabled. The package-specific interface is always
// provided, although trying to mix and match the two may lead to
// terrible confusion: once the network driver is active nothing else
// should use the lower-level USB ethernet code. However application
// code is responsible for initializing the package, and specifically
// for providing details of the USB endpoints that should be used.
//
// The package assumes that it needs to provide just one
// instantiation. Conceivably there may be applications where it makes
// sense for a USB peripheral to supply two separate ethernet devices
// to the host, but that would be an unusual setup. Also a peripheral
// might provide two or more USB slave ports to allow multiple hosts
// to be connected, with a separate USB-ethernet instantiation for
// each port, but again that would be an unusual setup. Applications
// which do require more than one instantiation are responsible
// for doing this inside the application code.

// The public interface depends on configuration options.
#include <pkgconf/io_usb_slave_eth.h>

// Define the interface in terms of eCos data types.
#include <cyg/infra/cyg_type.h>

// The generic USB support
#include <cyg/io/usb/usbs.h>

// Network driver definition, to support cloning of usbs_eth_netdev0
#ifdef CYGPKG_USBS_ETHDRV
# include <cyg/io/eth/netdev.h>
#endif

// Cache details, to allow alignment to cache line boundaries etc.
#include <cyg/hal/hal_cache.h>    
    
// ----------------------------------------------------------------------------
// Maximum transfer size. This is not specified by io/eth. It can be
// determined from <netinet/if_ether.h> but the TCP/IP stack may not
// be loaded so that header file cannot be used.
//
// Some (most?) USB implementations have implementation problems. For
// example the SA11x0 family cannot support transfers that are exact
// multiples of the 64-byte USB bulk packet size, instead it is
// necessary to add explicit size information. This can be encoded
// conveniently at the start of the buffer.
//
// So the actual MTU consists of:
//  1) a 1500 byte payload