📄 usbseth-data.html
字号:
<!-- Copyright (C) 2003 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 is obtained from the copyright holder. --><HTML><HEAD><TITLE>USB-ethernet Data Transfers</TITLE><meta name="MSSmartTagsPreventParsing" content="TRUE"><METANAME="GENERATOR"CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+"><LINKREL="HOME"TITLE="eCos Reference Manual"HREF="ecos-ref.html"><LINKREL="UP"TITLE="eCos Support for Developing USB-ethernet Peripherals"HREF="io-usb-slave-eth.html"><LINKREL="PREVIOUS"TITLE="Initializing the USB-ethernet Package"HREF="usbseth-init.html"><LINKREL="NEXT"TITLE="USB-ethernet State Handling"HREF="usbseth-control.html"></HEAD><BODYCLASS="REFENTRY"BGCOLOR="#FFFFFF"TEXT="#000000"LINK="#0000FF"VLINK="#840084"ALINK="#0000FF"><DIVCLASS="NAVHEADER"><TABLESUMMARY="Header navigation table"WIDTH="100%"BORDER="0"CELLPADDING="0"CELLSPACING="0"><TR><THCOLSPAN="3"ALIGN="center">eCos Reference Manual</TH></TR><TR><TDWIDTH="10%"ALIGN="left"VALIGN="bottom"><AHREF="usbseth-init.html"ACCESSKEY="P">Prev</A></TD><TDWIDTH="80%"ALIGN="center"VALIGN="bottom"></TD><TDWIDTH="10%"ALIGN="right"VALIGN="bottom"><AHREF="usbseth-control.html"ACCESSKEY="N">Next</A></TD></TR></TABLE><HRALIGN="LEFT"WIDTH="100%"></DIV><H1><ANAME="USBSETH-DATA">USB-ethernet Data Transfers</H1><DIVCLASS="REFNAMEDIV"><ANAME="AEN17445"></A><H2>Name</H2>USB-ethernet Data Transfers -- Exchanging ethernet packets with the USB host</DIV><DIVCLASS="REFSYNOPSISDIV"><ANAME="AEN17448"><H2>Synopsis</H2><DIVCLASS="FUNCSYNOPSIS"><ANAME="AEN17449"><P></P><TABLEBORDER="5"BGCOLOR="#E0E0F0"WIDTH="70%"><TR><TD><PRECLASS="FUNCSYNOPSISINFO">#include <cyg/io/usb/usbs_eth.h></PRE></TD></TR></TABLE><P><CODE><CODECLASS="FUNCDEF">void usbs_eth_start_rx</CODE>(usbs_eth* usbseth, unsigned char* buffer, void (*)(usbs_eth*, void*, int) complete_fn, void* complete_data);</CODE></P><P><CODE><CODECLASS="FUNCDEF">void usbs_eth_start_tx</CODE>(usbs_eth* usbseth, unsigned char* buffer, void (*)(usbs_eth*, void*, int) complete_fn, void* complete_data);</CODE></P><P></P></DIV></DIV><DIVCLASS="REFSECT1"><ANAME="AEN17473"></A><H2>Description</H2><P>The USB-ethernet package provides two main modes of operation. In thefirst mode it provides a <AHREF="usbseth-netdev.html">network devicedriver</A> for use by a TCP/IP stack running inside the USBperipheral. All incoming ethernet packages should be passed up theTCP/IP stack, and only the stack will generate outgoing packets. Apartfrom <AHREF="usbseth-init.html">initialization</A> and possiblycertain <AHREF="usbseth-control.html">control operations</A>,higher-level code will not interact with the USB-ethernet packagedirectly.</P><P>In the second mode there is no TCP/IP stack running inside the USBperipheral. For example, a simple USB-ethernet converter has anethernet chip and a USB port: ethernet packets received by theethernet chip need to be forwarded to the USB host, and ethernetpackets sent by the USB host need to be sent out of the ethernet chip.<TTCLASS="FUNCTION">usbs_eth_start_rx</TT> and<TTCLASS="FUNCTION">usbs_eth_start_tx</TT> allow for this lower-levelaccess to the USB-ethernet package.</P><P>The two modes of operation are mutually exclusive. If the networkdevice driver mode is enabled then application code should communicateat the TCP/IP level, and not by using the lower-level functions.Instead, it is the network device driver that will make use of thesefunctions, and it assumes that it has exclusive access. The packagedoes not perform any locking.</P><P>The transmit and receive functions work in much the same way. Thefirst argument identifies the <SPANCLASS="STRUCTNAME">usbs_eth</SPAN>structure that should be used. For the majority of applications thiswill be <TTCLASS="LITERAL">usbs_eth0</TT>. The second argument specifiesthe location of the ethernet packet; outgoing for<TTCLASS="FUNCTION">usbs_eth_start_tx</TT> and incoming for<TTCLASS="FUNCTION">usbs_eth_start_rx</TT>. This buffer should correspondto the <AHREF="usbseth-protocol.html">protocol</A>:</P><P></P><OLTYPE="1"><LI><P>Outgoing packets can consist of up to 1516 bytes, consisting of atwo-byte header specific to USB-ethernet followed by a standardethernet frame (a header with 6-byte destination address, 6-bytesource address and a further two bytes, followed by a payload ofup to 1500 bytes). The two-byte USB-ethernet header consists simply ofthe size of the ethernet frame, i.e. the size of the rest of thepacket not including the USB-ethernet header, with the leastsignificant byte first.</P></LI><LI><P>For incoming packets the supplied buffer should usually be at least1516 bytes. There may be special circumstances in which a smallerbuffer might be safe; for example, if the host-side device driver ismodified to support only smaller packets. Once the packet has beenreceived the buffer will contain a two-byte header specific toUSB-ethernet, followed by a normal ethernet frame. The headergives the size of the ethernet frame, excluding the header, with theleast significant byte first.</P></LI></OL><P>Both <TTCLASS="FUNCTION">usbs_eth_start_tx</TT> and<TTCLASS="FUNCTION">usbs_eth_start_rx</TT> are asynchronous: the transferis started and, some time later, a completion function will be invoked.The third and fourth arguments to both<TTCLASS="FUNCTION">usbs_eth_start_tx</TT> and<TTCLASS="FUNCTION">usbs_eth_start_rx</TT> supply the completion functionand an argument to that function respectively. The completion functionwill be invoked with three arguments: a pointer to the<SPANCLASS="STRUCTNAME">usbs_eth</SPAN> data structure, usually<TTCLASS="LITERAL">usbs_eth0</TT>; the supplied completion data ; and areturn code field. A negative value indicates that an error occurred,for example <TTCLASS="LITERAL">-EPIPE</TT> if the connection between USBhost and peripheral has been broken, or <TTCLASS="LITERAL">-EAGAIN</TT> ifan endpoint has been halted. A positive value indicates the total sizeof the transfer, which should correspond to the size in theUSB-ethernet header plus an additional two bytes for the headeritself.</P><P>If the data transfer is succesful then the completion function willtypically be invoked in DSR context rather than in thread context,although this depends on the implementation of the underlying USBdevice driver. Therefore the completion function is restricted in whatit can do; in particular, it must not make any calls that will or mayblock such as locking a mutex or allocating memory. The kerneldocumentation should be consulted for more details of DSR's andinterrupt handling generally. Note that if the transfer finishesquickly then the completion function may be invoked before<TTCLASS="FUNCTION">usbs_eth_start_rx</TT> or<TTCLASS="FUNCTION">usbs_eth_start_tx</TT> returns. This is especiallylikely to happen if the current thread is descheduled after startingthe data transfer but before returning from these functions.</P><P>For transmit operations, it is possible for<TTCLASS="FUNCTION">usbs_eth_start_tx</TT> to invoke the completionfunction immediately. If there is no current connection between hostand target then the transmit will fail immediately with<TTCLASS="LITERAL">-EPIPE</TT>. In addition the USB-ethernet package willcheck the destination MAC address and make sure that the ethernetframe really is intended for the host: either it must be for theaddress specified in the initialization call <AHREF="usbseth-init.html"><TTCLASS="FUNCTION">usbs_eth_init</TT></A>, orit must be a broadcast packet, or the host must have enabledpromiscuous mode. </P></DIV><DIVCLASS="NAVFOOTER"><HRALIGN="LEFT"WIDTH="100%"><TABLESUMMARY="Footer navigation table"WIDTH="100%"BORDER="0"CELLPADDING="0"CELLSPACING="0"><TR><TDWIDTH="33%"ALIGN="left"VALIGN="top"><AHREF="usbseth-init.html"ACCESSKEY="P">Prev</A></TD><TDWIDTH="34%"ALIGN="center"VALIGN="top"><AHREF="ecos-ref.html"ACCESSKEY="H">Home</A></TD><TDWIDTH="33%"ALIGN="right"VALIGN="top"><AHREF="usbseth-control.html"ACCESSKEY="N">Next</A></TD></TR><TR><TDWIDTH="33%"ALIGN="left"VALIGN="top">Initializing the USB-ethernet Package</TD><TDWIDTH="34%"ALIGN="center"VALIGN="top"><AHREF="io-usb-slave-eth.html"ACCESSKEY="U">Up</A></TD><TDWIDTH="33%"ALIGN="right"VALIGN="top">USB-ethernet State Handling</TD></TR></TABLE></DIV></BODY></HTML>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -