usbseth.sgml

eCos操作系统源码

<!-- {{{ netdev device                  -->

<refentry id="usbseth-netdev">
<refmeta>
<refentrytitle>Network Device for the eCos TCP/IP Stack</refentrytitle>
</refmeta>
<refnamediv>
<refname>Network Device</refname>
<refpurpose>USB-ethernet support for the eCos TCP/IP Stack</refpurpose>
</refnamediv>

<refsect1><title>Description</title>
<para>
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 <link
linkend="usbseth-init"><function>usbs_eth_init</function></link>, but
after that it will be the TCP/IP stack rather than application code
that transmits or receives ethernet frames.
</para>
<para>
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 <literal>CYGPKG_USBS_ETHDRV</literal>. By
default this will be enabled if the TCP/IP package
<literal>CYGPKG_NET</literal> is loaded, and disabled otherwise. 
</para>
<para>
There are a number of other configuration options related to the
network device. <literal>CYGFUN_USBS_ETHDRV_STATISTICS</literal>
determines whether or not the package will maintain statistics, mainly
intended for SNMP: by default this will be enabled if the SNMP support
package <literal>CYGPKG_SNMPAGENT</literal> is loaded, and disabled
otherwise. The name of the ethernet device is controlled by
<literal>CYGDATA_USBS_ETHDRV_NAME</literal>, and has a default value
of either <literal>eth0</literal> or <literal>eth1</literal>
depending on whether or not there is another network device driver
present in the configuration.
</para>
<para>
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.
</para>
</refsect1>

</refentry>

<!-- }}} -->
<!-- {{{ ecos_usbeth                    -->

<refentry id="usbseth-host">
<refmeta>
<refentrytitle>Example Host-side Device Driver</refentrytitle>
</refmeta>
<refnamediv>
<refname>Example Host-side Device Driver</refname>
<refpurpose>Provide host-side support for the eCos USB-ethernet package</refpurpose>
</refnamediv>

<refsect1><title>Description</title>
<para>
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 <literal>0x4242</literal> rather than an
official vendor id supplied by the <ulink
url="http://www.usb.org/">USB Implementers Forum</ulink>. 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 <link
linkend="usbseth-protocol">Communication Protocol</link> section.
</para>
<para>
The host-side device driver can be found in the <filename
class="directory">host</filename> subdirectory of the USB-ethernet
package, specifically the file <filename>ecos_usbeth.c</filename>, and
comes with a <filename>Makefile</filename>. Both files may need
to be modified for specific applications. For example, the vendor id
table <literal>ecos_usbeth_implementations</literal> may need to be
updated for the specific USB peripheral being built. The
<filename>Makefile</filename> assumes that the Linux kernel sources
reside in <filename class="directory">/usr/src/linux</filename>, and
that the kernel has already been configured and built. Assuming this
is the case, the device driver can be built simply by invoking
<command>make</command> with no additional arguments. This will result
in a dynamically loadable kernel module,
<filename>ecos_usbeth.o</filename>, in the current directory.
</para>
<note>
<para>
As normal for Linux kernel builds, the generated files such as
<filename>ecos_usbeth.o</filename> 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 <filename class="directory">host</filename>
subdirectory and building that copy.
</para>
</note>
<para>
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:
</para>
<screen width=72 format=linespecific>
# insmod usb-uhci
Using /lib/modules/2.2.16-22/usb/usb-uhci.o
</screen>
<para>
Depending on the host hardware, the <literal>uhci</literal> or
<literal>usb-ohci</literal> modules may be more appropriate. Loading
the generic USB module will typically result in a number of messages
to the logfile <filename>/var/log/messages</filename>, 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:
</para>
<screen width=72 format=linespecific>
# insmod ecos_usbeth.o
</screen>
<para>
This should result in a number of additional diagnostics in the
logfile:
</para>
<screen width=72 format=linespecific>
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
</screen>
<para>
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
<filename>ecos_usbeth.o</filename> module will be selected and this
will be reported in the system log:
</para>
<screen width=86 format=linespecific>
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
</screen>
<para>
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
<command>ifconfig</command>.
</para>
</refsect1>

</refentry>

<!-- }}} -->
<!-- {{{ Protocol                       -->

<refentry id="usbseth-protocol">
<refmeta>
<refentrytitle>Communication Protocol</refentrytitle>
</refmeta>
<refnamediv>
<refname>Communication Protocol</refname>
<refpurpose>Protocol used between the host-side device driver and the eCos
USB-ethernet package </refpurpose>
</refnamediv>

<refsect1><title>Description</title>
<para>
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.
</para>
<para>
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.
</para>
<para>
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 <link
linkend="usbseth-init"><function>usbs_eth_init</function></link>, e.g.
0x405D90A9BC02. The remaining data is as specified by the appropriate
<ulink url="http://www.ietf.org">IETF RFC's</ulink>. The actual bulk
USB transfer involves the following sequence of 44 bytes:
</para>
<screen width=72 format=linespecific>
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
</screen>
<para>
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 <link linkend="usbseth-control"><function>
usbs_eth_class_control_handler</function></link>. 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.
</para>
<para>
The first control message can be used by the host to obtain a MAC
address:
</para>
<programlisting width=72>
#define ECOS_USBETH_CONTROL_GET_MAC_ADDRESS         0x01
</programlisting>
<para>
The control message's type field should specify IN as the direction.
The request field should be <literal>0x01</literal>. 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
<link
linkend="usbseth-init"><function>usbs_eth_init</function></link>.
</para>
<para>
The second control message can be used by the host to enable or
disable promiscuous mode.
</para>
<programlisting width=72>
#define ECOS_USBETH_CONTROL_SET_PROMISCUOUS_MODE    0x02
</programlisting>
<para>
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
<literal>0x02</literal>. 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.
</para>
</refsect1>

</refentry>

<!-- }}} -->

</part>
<!-- /reference -->