usbseth.sgml

eCos操作系统源码

<!-- DOCTYPE reference  PUBLIC "-//OASIS//DTD DocBook V3.1//EN" -->

<!-- {{{ Banner                         -->

<!-- =============================================================== -->
<!--                                                                 -->
<!--     usbseth.sgml                                                -->
<!--                                                                 -->
<!--     USB slave-side ethernet support package.                    -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- ####COPYRIGHTBEGIN####                                          -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- Copyright (C) 2001, 2002 Red Hat, Inc.                          -->
<!-- This material may be distributed only subject to the terms      -->
<!-- and conditions set forth in the Open Publication License, v1.0  -->
<!-- or later (the latest version is presently available at          -->
<!-- http://www.opencontent.org/openpub/)                            -->
<!-- Distribution of the work or derivative of the work in any       -->
<!-- standard (paper) book form is prohibited unless prior           -->
<!-- permission obtained from the copyright holder                   -->
<!-- =============================================================== -->
<!--                                                                 -->      
<!-- ####COPYRIGHTEND####                                            -->
<!-- =============================================================== -->
<!-- #####DESCRIPTIONBEGIN####                                       -->
<!--                                                                 -->
<!-- Author(s):   bartv                                              -->
<!-- Contact(s):  bartv                                              -->
<!-- Date:        2001/01/13                                         -->
<!-- Version:     0.01                                               -->
<!--                                                                 -->
<!-- ####DESCRIPTIONEND####                                          -->
<!-- =============================================================== -->

<!-- }}} -->

<part id="io-usb-slave-eth">
<!-- reference id="io-usb-slave-eth" -->
  <title>eCos Support for Developing USB-ethernet Peripherals</title>

<!-- {{{ Intro                          -->

<refentry id="usbseth-intro">
<refmeta>
<refentrytitle>Introduction</refentrytitle>
</refmeta>
<refnamediv>
<refname>Introduction</refname>
<refpurpose>eCos support for developing USB ethernet peripherals</refpurpose>
</refnamediv>

<refsect1><title>Introduction</title>
<para>
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.
</para>
<para>
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:
</para>
<screen width=72 format=linespecific>
$ ecosconfig add usbs_eth
</screen>
<para>
Typically, this will automatically cause the USB device driver to
become active. Loading the USB-ethernet package automatically provides
functionality for <link linkend="usbseth-init">initialization</link>,
<link linkend="usbseth-data">data transfer</link>, and the handling of
<link linkend="usbseth-control">control messages</link> and state
changes. If the current configuration includes the eCos TCP/IP stack
then the <link linkend="usbseth-netdev">network device driver</link>
support will be enabled as well by default, allowing the stack to
exchange ethernet frames over the USB bus.
</para>
<para>
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 <link
linkend="usbseth-protocol">protocol</link> between USB
<link linkend="usbseth-host">host device driver</link> and the
peripheral. 
</para>
</refsect1>

<refsect1><title id="usbseth-intro-scenarios">Usage Scenarios</title>
<para>
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:
</para>
<informalfigure PgWide=1>
<mediaobject>
<imageobject>
<imagedata fileref="simple.png" Align="Center">
</imageobject>
</mediaobject>
</informalfigure>
<para>
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 <function>usbs_eth_start_tx</function>
function. Similarly, higher-level code needs to detect packets coming
from the host, using <function>usbs_eth_start_rx</function>, 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
<link linkend="usbseth-init">initialization</link>.
</para>
<para>
In a more complicated scenario, there is a TCP/IP stack running inside
the peripheral.
</para>
<informalfigure PgWide=1>
<mediaobject>
<imageobject>
<imagedata fileref="tcpip.png" Align="Center">
</imageobject>
</mediaobject>
</informalfigure>
<para>
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.
</para>
<para>
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. 
</para>
</refsect1>
</refentry>

<!-- }}} -->
<!-- {{{ Initialization                 -->

<refentry id="usbseth-init">
<refmeta>
<refentrytitle>Initializing the USB-ethernet Package</refentrytitle>
</refmeta>
<refnamediv>
<refname><function>usbs_eth_init</function></refname>
<refpurpose>Initializing the USB-ethernet Package</refpurpose>
</refnamediv>

<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;cyg/io/usb/usbs_eth.h&gt;
</funcsynopsisinfo>	
<funcprototype>
<funcdef>void <function>usbs_eth_init</function></funcdef>
<paramdef>usbs_eth* <parameter>usbeth</parameter></paramdef>
<paramdef>usbs_control_endpoint* <parameter>ep0</parameter></paramdef>
<paramdef>usbs_rx_endpoint* <parameter>ep1</parameter></paramdef>
<paramdef>usbs_tx_endpoint* <parameter>ep2</parameter></paramdef>
<paramdef>unsigned char* <parameter>mac_address</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>

<refsect1><title>Description</title>
<para>
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.
</para>
<para>
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 <function>usbs_eth_init</function> function.
</para>
<para>
The first argument identifies the specific
<structname>usbs_eth</structname> 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
<literal>usbs_eth0</literal> to support this. If multiple
<structname>usbs_eth</structname> 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
<function>usbs_eth_init()</function>. 
</para>
<para>
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
<function>usbs_eth_disable</function> and
<function>usbs_eth_enable</function> control functions. The package
also assumes that no other code is interested in USB state changes or
class control messages: it installs handlers
<link linkend="usbseth-control"><function>usbs_eth_state_change_handler</function></link>
and
<link linkend="usbseth-control"><function>usbs_eth_class_control_handler</function></link>
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
<function>usbs_eth_init</function>, and those replacements should
invoke the USB-ethernet ones when appropriate.
</para>
<para>
The final argument to <function>usbs_eth_init</function> 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 <link
linkend="usbseth-intro-scenarios">scenario</link> in which the
USB-ethernet package is being used.
</para>
<para>
The call to <function>usbs_eth_init</function> 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. 
</para>
<programlisting width=72>
int
main(int argc, char** argv)
{
    unsigned char host_MAC[6] = { 0x40, 0x5d, 0x90, 0xa9, 0xbc, 0x02 };