usbseth.sgml

eCos操作系统源码

    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);
    …
}
</programlisting>
</refsect1>

</refentry>

<!-- }}} -->
<!-- {{{ Data Transfer                  -->

<refentry id="usbseth-data">
<refmeta>
<refentrytitle>USB-ethernet Data Transfers</refentrytitle>
</refmeta>
<refnamediv>
<refname>USB-ethernet Data Transfers</refname>
<refpurpose>Exchanging ethernet packets with the USB host</refpurpose>
</refnamediv>

<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;cyg/io/usb/usbs_eth.h&gt;
</funcsynopsisinfo>	

<funcprototype>
<funcdef>void <function>usbs_eth_start_rx</function></funcdef>
<paramdef>usbs_eth* <parameter>usbseth</parameter></paramdef>
<paramdef>unsigned char* <parameter>buffer</parameter></paramdef>
<paramdef>void (*)(usbs_eth*, void*, int) <parameter>complete_fn</parameter></paramdef>
<paramdef>void* <parameter>complete_data</parameter></paramdef>
</funcprototype>

<funcprototype>
<funcdef>void <function>usbs_eth_start_tx</function></funcdef>
<paramdef>usbs_eth* <parameter>usbseth</parameter></paramdef>
<paramdef>unsigned char* <parameter>buffer</parameter></paramdef>
<paramdef>void (*)(usbs_eth*, void*, int) <parameter>complete_fn</parameter></paramdef>
<paramdef>void* <parameter>complete_data</parameter></paramdef>
</funcprototype>

</funcsynopsis>
</refsynopsisdiv>

<refsect1><title>Description</title>
<para>
The USB-ethernet package provides two main modes of operation. In the
first mode it provides a <link linkend="usbseth-netdev">network device
driver</link> for use by a TCP/IP stack running inside the USB
peripheral. All incoming ethernet packets should be passed up the
TCP/IP stack, and only the stack will generate outgoing packets. Apart
from <link linkend="usbseth-init">initialization</link> and possibly
certain <link linkend="usbseth-control">control operations</link>,
higher-level code will not interact with the USB-ethernet package
directly.
</para>
<para>
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.
<function>usbs_eth_start_rx</function> and
<function>usbs_eth_start_tx</function> allow for this lower-level
access to the USB-ethernet package.
</para>
<para>
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.
</para>
<para>
The transmit and receive functions work in much the same way. The
first argument identifies the <structname>usbs_eth</structname>
structure that should be used. For the majority of applications this
will be <literal>usbs_eth0</literal>. The second argument specifies
the location of the ethernet packet; outgoing for
<function>usbs_eth_start_tx</function> and incoming for
<function>usbs_eth_start_rx</function>. This buffer should correspond
to the <link linkend="usbseth-protocol">protocol</link>:
</para>
<orderedlist>
<listitem>
<para>
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.
</para>
</listitem>
<listitem>
<para>
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.
</para>
</listitem>
</orderedlist>
<para>
Both <function>usbs_eth_start_tx</function> and
<function>usbs_eth_start_rx</function> are asynchronous: the transfer
is started and, some time later, a completion function will be invoked.
The third and fourth arguments to both
<function>usbs_eth_start_tx</function> and
<function>usbs_eth_start_rx</function> supply the completion function
and an argument to that function respectively. The completion function
will be invoked with three arguments: a pointer to the
<structname>usbs_eth</structname> data structure, usually
<literal>usbs_eth0</literal>; the supplied completion data ; and a
return code field. A negative value indicates that an error occurred,
for example <literal>-EPIPE</literal> if the connection between USB
host and peripheral has been broken, or <literal>-EAGAIN</literal> 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.
</para>
<para>
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
<function>usbs_eth_start_rx</function> or
<function>usbs_eth_start_tx</function> returns. This is especially
likely to happen if the current thread is descheduled after starting
the data transfer but before returning from these functions.
</para>
<para>
For transmit operations, it is possible for
<function>usbs_eth_start_tx</function> to invoke the completion
function immediately. If there is no current connection between host
and target then the transmit will fail immediately with
<literal>-EPIPE</literal>. 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 <link
linkend="usbseth-init"><function>usbs_eth_init</function></link>, or
it must be a broadcast packet, or the host must have enabled
promiscuous mode. 
</para>
</refsect1>

</refentry>

<!-- }}} -->
<!-- {{{ State and Control Messages     -->

<refentry id="usbseth-control">
<refmeta>
<refentrytitle>USB-ethernet State Handling</refentrytitle>
</refmeta>
<refnamediv>
<refname>USB-ethernet State Handling</refname>
<refpurpose>Maintaining the USB-ethernet connection with the host</refpurpose>
</refnamediv>

<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;cyg/io/usb/usbs_eth.h&gt;
</funcsynopsisinfo>	

<funcprototype>
<funcdef>usbs_control_return <function>usbs_eth_class_control_handler</function></funcdef>
<paramdef>usbs_control_endpoint* <parameter>ep0</parameter></paramdef>
<paramdef>void* <parameter>callback_data</parameter></paramdef>
</funcprototype>

<funcprototype>
<funcdef>void <function>usbs_eth_state_change_handler</function></funcdef>
<paramdef>usbs_control_endpoint* <parameter>ep0</parameter></paramdef>
<paramdef>void* <parameter>callback_data</parameter></paramdef>
<paramdef>usbs_state_change <parameter>change</parameter></paramdef>
<paramdef>int <parameter>old_state</parameter></paramdef>
</funcprototype>

<funcprototype>
<funcdef>void <function>usbs_eth_disable</function></funcdef>
<paramdef>usbs_eth* <parameter>usbseth></parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>usbs_eth_enable</function></funcdef>
<paramdef>usbs_eth* <parameter>usbseth></parameter></paramdef>
</funcprototype>

</funcsynopsis>
</refsynopsisdiv>

<refsect1><title>Description</title>
<para>
When the USB-ethernet package is initialized by a call to <link
linkend="usbseth-init"><function>usbs_eth_init</function></link> it
installs <function>usbs_eth_state_change_handler</function> 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
<function>usbs_eth_enable</function> and
<function>usbs_eth_disable</function> 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 <function>usbs_eth_init</function>. This
alternative handler will either chain into
<function>usbs_eth_state_change_handler</function> when appropriate,
or else it will invoke <function>usbs_eth_enable</function> and
<function>usbs_eth_disable</function> directly. For further details of
state change handlers and control endpoints generally, see the
documentation for the common USB-slave package.
</para>
<para>
Similarly, <function>usbs_eth_init</function> will install
<function>usbs_eth_class_control_handler</function> in the control
endpoint data structure as the appropriate handler for class-specific
USB control messages. This code will handle the ethernet-specific
<link linkend="usbseth-protocol">control messages </link>, 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.
</para>
<para>
As an alternative to chaining the state change handler, higher-level
code can instead call <function>usbs_eth_disable</function> and
<function>usbs_eth_enable</function> 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 <function>usbs_eth_enable</function> is to restart receive
operations and to allow transmits. The main effect of
<function>usbs_eth_disable</function> is to block further transmits:
any current receive operations need to be aborted at the USB level,
for example by halting the appropriate endpoint.
</para>
</refsect1>

</refentry>

<!-- }}} -->