Subversion Repositories openrisc_me
Compare Revisions
- This comparison shows the changes necessary to convert path
/openrisc/trunk/rtos/ecos-2.0/packages/io/usb/eth/slave/v2_0/doc
- from Rev 27 to Rev 174
- ↔ Reverse comparison
Rev 27 → Rev 174
<!-- Copyright (C) 2001 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 substantively modified versions of this --> |
<!-- document is prohibited without the explicit permission of the --> |
<!-- copyright holder. --> |
<!-- Distribution of the work or derivative of the work in any --> |
<!-- standard (paper) book form is prohibited unless prior --> |
<!-- permission is obtained from the copyright holder. --> |
<HTML |
><HEAD |
><TITLE |
>Communication Protocol</TITLE |
><META |
NAME="GENERATOR" |
CONTENT="Modular DocBook HTML Stylesheet Version 1.64 |
"><LINK |
REL="HOME" |
TITLE="eCos Support for Developing USB-ethernet Peripherals" |
HREF="io-usb-slave-eth.html"><LINK |
REL="PREVIOUS" |
TITLE="Example Host-side Device Driver" |
HREF="usbseth-host.html"></HEAD |
><BODY |
CLASS="REFENTRY" |
BGCOLOR="#FFFFFF" |
TEXT="#000000" |
LINK="#0000FF" |
VLINK="#840084" |
ALINK="#0000FF" |
><DIV |
CLASS="NAVHEADER" |
><TABLE |
WIDTH="100%" |
BORDER="0" |
CELLPADDING="0" |
CELLSPACING="0" |
><TR |
><TH |
COLSPAN="3" |
ALIGN="center" |
>eCos Support for Developing USB-ethernet Peripherals</TH |
></TR |
><TR |
><TD |
WIDTH="10%" |
ALIGN="left" |
VALIGN="bottom" |
><A |
HREF="usbseth-host.html" |
>Prev</A |
></TD |
><TD |
WIDTH="80%" |
ALIGN="center" |
VALIGN="bottom" |
></TD |
><TD |
WIDTH="10%" |
ALIGN="right" |
VALIGN="bottom" |
> </TD |
></TR |
></TABLE |
><HR |
ALIGN="LEFT" |
WIDTH="100%"></DIV |
><H1 |
><A |
NAME="USBSETH-PROTOCOL" |
>Communication Protocol</A |
></H1 |
><DIV |
CLASS="REFNAMEDIV" |
><A |
NAME="AEN281" |
></A |
><H2 |
>Name</H2 |
>Communication Protocol -- Protocol used between the host-side device driver and the eCos |
USB-ethernet package </DIV |
><DIV |
CLASS="REFSECT1" |
><A |
NAME="AEN284" |
></A |
><H2 |
>Description</H2 |
><P |
>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.</P |
><P |
>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.</P |
><P |
>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 <A |
HREF="usbseth-init.html" |
><TT |
CLASS="FUNCTION" |
>usbs_eth_init</TT |
></A |
>, e.g. |
0x405D90A9BC02. The remaining data is as specified by the appropriate |
<A |
HREF="http://www.ietf.org" |
TARGET="_top" |
>IETF RFC's</A |
>. The actual bulk |
USB transfer involves the following sequence of 44 bytes:</P |
><TABLE |
BORDER="0" |
BGCOLOR="#E0E0E0" |
WIDTH="100%" |
><TR |
><TD |
><PRE |
CLASS="SCREEN" |
>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</PRE |
></TD |
></TR |
></TABLE |
><P |
>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 <A |
HREF="usbseth-control.html" |
><TT |
CLASS="FUNCTION" |
>usbs_eth_class_control_handler</TT |
></A |
>. 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.</P |
><P |
>The first control message can be used by the host to obtain a MAC |
address:</P |
><TABLE |
BORDER="0" |
BGCOLOR="#E0E0E0" |
WIDTH="100%" |
><TR |
><TD |
><PRE |
CLASS="PROGRAMLISTING" |
>#define ECOS_USBETH_CONTROL_GET_MAC_ADDRESS 0x01</PRE |
></TD |
></TR |
></TABLE |
><P |
>The control message's type field should specify IN as the direction. |
The request field should be <TT |
CLASS="LITERAL" |
>0x01</TT |
>. 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 |
<A |
HREF="usbseth-init.html" |
><TT |
CLASS="FUNCTION" |
>usbs_eth_init</TT |
></A |
>.</P |
><P |
>The second control message can be used by the host to enable or |
disable promiscuous mode.</P |
><TABLE |
BORDER="0" |
BGCOLOR="#E0E0E0" |
WIDTH="100%" |
><TR |
><TD |
><PRE |
CLASS="PROGRAMLISTING" |
>#define ECOS_USBETH_CONTROL_SET_PROMISCUOUS_MODE 0x02</PRE |
></TD |
></TR |
></TABLE |
><P |
>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 |
<TT |
CLASS="LITERAL" |
>0x02</TT |
>. 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.</P |
></DIV |
><DIV |
CLASS="NAVFOOTER" |
><HR |
ALIGN="LEFT" |
WIDTH="100%"><TABLE |
WIDTH="100%" |
BORDER="0" |
CELLPADDING="0" |
CELLSPACING="0" |
><TR |
><TD |
WIDTH="33%" |
ALIGN="left" |
VALIGN="top" |
><A |
HREF="usbseth-host.html" |
>Prev</A |
></TD |
><TD |
WIDTH="34%" |
ALIGN="center" |
VALIGN="top" |
><A |
HREF="io-usb-slave-eth.html" |
>Home</A |
></TD |
><TD |
WIDTH="33%" |
ALIGN="right" |
VALIGN="top" |
> </TD |
></TR |
><TR |
><TD |
WIDTH="33%" |
ALIGN="left" |
VALIGN="top" |
>Example Host-side Device Driver</TD |
><TD |
WIDTH="34%" |
ALIGN="center" |
VALIGN="top" |
> </TD |
><TD |
WIDTH="33%" |
ALIGN="right" |
VALIGN="top" |
> </TD |
></TR |
></TABLE |
></DIV |
></BODY |
></HTML |
> |
<!-- Copyright (C) 2001 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 substantively modified versions of this --> |
<!-- document is prohibited without the explicit permission of the --> |
<!-- copyright holder. --> |
<!-- Distribution of the work or derivative of the work in any --> |
<!-- standard (paper) book form is prohibited unless prior --> |
<!-- permission is obtained from the copyright holder. --> |
<HTML |
><HEAD |
><TITLE |
>Initializing the USB-ethernet Package</TITLE |
><META |
NAME="GENERATOR" |
CONTENT="Modular DocBook HTML Stylesheet Version 1.64 |
"><LINK |
REL="HOME" |
TITLE="eCos Support for Developing USB-ethernet Peripherals" |
HREF="io-usb-slave-eth.html"><LINK |
REL="PREVIOUS" |
TITLE="Introduction" |
HREF="usbseth-intro.html"><LINK |
REL="NEXT" |
TITLE="USB-ethernet Data Transfers" |
HREF="usbseth-data.html"></HEAD |
><BODY |
CLASS="REFENTRY" |
BGCOLOR="#FFFFFF" |
TEXT="#000000" |
LINK="#0000FF" |
VLINK="#840084" |
ALINK="#0000FF" |
><DIV |
CLASS="NAVHEADER" |
><TABLE |
WIDTH="100%" |
BORDER="0" |
CELLPADDING="0" |
CELLSPACING="0" |
><TR |
><TH |
COLSPAN="3" |
ALIGN="center" |
>eCos Support for Developing USB-ethernet Peripherals</TH |
></TR |
><TR |
><TD |
WIDTH="10%" |
ALIGN="left" |
VALIGN="bottom" |
><A |
HREF="usbseth-intro.html" |
>Prev</A |
></TD |
><TD |
WIDTH="80%" |
ALIGN="center" |
VALIGN="bottom" |
></TD |
><TD |
WIDTH="10%" |
ALIGN="right" |
VALIGN="bottom" |
><A |
HREF="usbseth-data.html" |
>Next</A |
></TD |
></TR |
></TABLE |
><HR |
ALIGN="LEFT" |
WIDTH="100%"></DIV |
><H1 |
><A |
NAME="USBSETH-INIT" |
>Initializing the USB-ethernet Package</A |
></H1 |
><DIV |
CLASS="REFNAMEDIV" |
><A |
NAME="AEN47" |
></A |
><H2 |
>Name</H2 |
><TT |
CLASS="FUNCTION" |
>usbs_eth_init</TT |
> -- Initializing the USB-ethernet Package</DIV |
><DIV |
CLASS="REFSYNOPSISDIV" |
><A |
NAME="AEN51" |
></A |
><H2 |
>Synopsis</H2 |
><DIV |
CLASS="FUNCSYNOPSIS" |
><A |
NAME="AEN52" |
></A |
><P |
></P |
><TABLE |
BORDER="0" |
BGCOLOR="#E0E0E0" |
WIDTH="100%" |
><TR |
><TD |
><PRE |
CLASS="FUNCSYNOPSISINFO" |
>#include <cyg/io/usb/usbs_eth.h></PRE |
></TD |
></TR |
></TABLE |
><P |
><CODE |
><CODE |
CLASS="FUNCDEF" |
>void usbs_eth_init</CODE |
>(usbs_eth* usbeth, usbs_control_endpoint* ep0, usbs_rx_endpoint* ep1, usbs_tx_endpoint* ep2, unsigned char* mac_address);</CODE |
></P |
><P |
></P |
></DIV |
></DIV |
><DIV |
CLASS="REFSECT1" |
><A |
NAME="AEN67" |
></A |
><H2 |
>Description</H2 |
><P |
>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.</P |
><P |
>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 <TT |
CLASS="FUNCTION" |
>usbs_eth_init</TT |
> function.</P |
><P |
>The first argument identifies the specific |
<SPAN |
CLASS="STRUCTNAME" |
>usbs_eth</SPAN |
> 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 |
<TT |
CLASS="LITERAL" |
>usbs_eth0</TT |
> to support this. If multiple |
<SPAN |
CLASS="STRUCTNAME" |
>usbs_eth</SPAN |
> 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 |
<TT |
CLASS="FUNCTION" |
>usbs_eth_init()</TT |
>. </P |
><P |
>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 |
<TT |
CLASS="FUNCTION" |
>usbs_eth_disable</TT |
> and |
<TT |
CLASS="FUNCTION" |
>usbs_eth_enable</TT |
> control functions. The package |
also assumes that no other code is interested in USB state changes or |
class control messages: it installs handlers |
<A |
HREF="usbseth-control.html" |
><TT |
CLASS="FUNCTION" |
>usbs_eth_state_change_handler</TT |
></A |
> |
and |
<A |
HREF="usbseth-control.html" |
><TT |
CLASS="FUNCTION" |
>usbs_eth_class_control_handler</TT |
></A |
> |
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 |
<TT |
CLASS="FUNCTION" |
>usbs_eth_init</TT |
>, and those replacements should |
invoke the USB-ethernet ones when appropriate.</P |
><P |
>The final argument to <TT |
CLASS="FUNCTION" |
>usbs_eth_init</TT |
> 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 <A |
HREF="usbseth-intro.html#AEN22" |
>scenario</A |
> in which the |
USB-ethernet package is being used.</P |
><P |
>The call to <TT |
CLASS="FUNCTION" |
>usbs_eth_init</TT |
> 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. </P |
><TABLE |
BORDER="0" |
BGCOLOR="#E0E0E0" |
WIDTH="100%" |
><TR |
><TD |
><PRE |
CLASS="PROGRAMLISTING" |
>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); |
… |
}</PRE |
></TD |
></TR |
></TABLE |
></DIV |
><DIV |
CLASS="NAVFOOTER" |
><HR |
ALIGN="LEFT" |
WIDTH="100%"><TABLE |
WIDTH="100%" |
BORDER="0" |
CELLPADDING="0" |
CELLSPACING="0" |
><TR |
><TD |
WIDTH="33%" |
ALIGN="left" |
VALIGN="top" |
><A |
HREF="usbseth-intro.html" |
>Prev</A |
></TD |
><TD |
WIDTH="34%" |
ALIGN="center" |
VALIGN="top" |
><A |
HREF="io-usb-slave-eth.html" |
>Home</A |
></TD |
><TD |
WIDTH="33%" |
ALIGN="right" |
VALIGN="top" |
><A |
HREF="usbseth-data.html" |
>Next</A |
></TD |
></TR |
><TR |
><TD |
WIDTH="33%" |
ALIGN="left" |
VALIGN="top" |
>Introduction</TD |
><TD |
WIDTH="34%" |
ALIGN="center" |
VALIGN="top" |
> </TD |
><TD |
WIDTH="33%" |
ALIGN="right" |
VALIGN="top" |
>USB-ethernet Data Transfers</TD |
></TR |
></TABLE |
></DIV |
></BODY |
></HTML |
> |
Network Device 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.
USB-ethernet Data Transfers
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:
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.
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.
I. eCos Support for Developing USB-ethernet Peripherals
- Table of Contents
- Introduction — eCos support for developing USB ethernet peripherals
- Initializing the USB-ethernet Package — Initializing the USB-ethernet Package
- USB-ethernet Data Transfers — Exchanging ethernet packets with the USB host
- USB-ethernet State Handling — Maintaining the USB-ethernet connection with the host
- Network Device for the eCos TCP/IP Stack — USB-ethernet support for the eCos TCP/IP Stack
- Example Host-side Device Driver — Provide host-side support for the eCos USB-ethernet package
- Communication Protocol — Protocol used between the host-side device driver and the eCos +USB-ethernet package
Next | ||
Introduction |
Introduction
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.
Prev | Home | Next |
eCos Support for Developing USB-ethernet Peripherals | Initializing the USB-ethernet Package |
Example Host-side Device Driver
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.
Note: 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.
USB-ethernet State Handling
Synopsis
#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.