packages/io/usb/eth/slave/v2_0/doc/usbseth-data.html

   1 <!-- Copyright (C) 2001 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of substantively modified versions of this         -->
   7 <!-- document is prohibited without the explicit permission of the   -->
   8 <!-- copyright holder.                                               -->
   9 <!-- Distribution of the work or derivative of the work in any       -->
  10 <!-- standard (paper) book form is prohibited unless prior           -->
  11 <!-- permission is obtained from the copyright holder.               -->
  12 <HTML
  13 ><HEAD
  14 ><TITLE
  15 >USB-ethernet Data Transfers</TITLE
  16 ><META
  17 NAME="GENERATOR"
  18 CONTENT="Modular DocBook HTML Stylesheet Version 1.64
  19 "><LINK
  20 REL="HOME"
  21 TITLE="eCos Support for Developing USB-ethernet Peripherals"
  22 HREF="io-usb-slave-eth.html"><LINK
  23 REL="PREVIOUS"
  24 TITLE="Initializing the USB-ethernet Package"
  25 HREF="usbseth-init.html"><LINK
  26 REL="NEXT"
  27 TITLE="USB-ethernet State Handling"
  28 HREF="usbseth-control.html"></HEAD
  29 ><BODY
  30 CLASS="REFENTRY"
  31 BGCOLOR="#FFFFFF"
  32 TEXT="#000000"
  33 LINK="#0000FF"
  34 VLINK="#840084"
  35 ALINK="#0000FF"
  36 ><DIV
  37 CLASS="NAVHEADER"
  38 ><TABLE
  39 WIDTH="100%"
  40 BORDER="0"
  41 CELLPADDING="0"
  42 CELLSPACING="0"
  43 ><TR
  44 ><TH
  45 COLSPAN="3"
  46 ALIGN="center"
  47 >eCos Support for Developing USB-ethernet Peripherals</TH
  48 ></TR
  49 ><TR
  50 ><TD
  51 WIDTH="10%"
  52 ALIGN="left"
  53 VALIGN="bottom"
  54 ><A
  55 HREF="usbseth-init.html"
  56 >Prev</A
  57 ></TD
  58 ><TD
  59 WIDTH="80%"
  60 ALIGN="center"
  61 VALIGN="bottom"
  62 ></TD
  63 ><TD
  64 WIDTH="10%"
  65 ALIGN="right"
  66 VALIGN="bottom"
  67 ><A
  68 HREF="usbseth-control.html"
  69 >Next</A
  70 ></TD
  71 ></TR
  72 ></TABLE
  73 ><HR
  74 ALIGN="LEFT"
  75 WIDTH="100%"></DIV
  76 ><H1
  77 ><A
  78 NAME="USBSETH-DATA"
  79 >USB-ethernet Data Transfers</A
  80 ></H1
  81 ><DIV
  82 CLASS="REFNAMEDIV"
  83 ><A
  84 NAME="AEN94"
  85 ></A
  86 ><H2
  87 >Name</H2
  88 >USB-ethernet Data Transfers&nbsp;--&nbsp;Exchanging ethernet packets with the USB host</DIV
  89 ><DIV
  90 CLASS="REFSYNOPSISDIV"
  91 ><A
  92 NAME="AEN97"
  93 ></A
  94 ><H2
  95 >Synopsis</H2
  96 ><DIV
  97 CLASS="FUNCSYNOPSIS"
  98 ><A
  99 NAME="AEN98"
 100 ></A
 101 ><P
 102 ></P
 103 ><TABLE
 104 BORDER="0"
 105 BGCOLOR="#E0E0E0"
 106 WIDTH="100%"
 107 ><TR
 108 ><TD
 109 ><PRE
 110 CLASS="FUNCSYNOPSISINFO"
 111 >#include &lt;cyg/io/usb/usbs_eth.h&gt;</PRE
 112 ></TD
 113 ></TR
 114 ></TABLE
 115 ><P
 116 ><CODE
 117 ><CODE
 118 CLASS="FUNCDEF"
 119 >void usbs_eth_start_rx</CODE
 120 >(usbs_eth* usbseth, unsigned char* buffer, void (*)(usbs_eth*, void*, int) complete_fn, void* complete_data);</CODE
 121 ></P
 122 ><P
 123 ><CODE
 124 ><CODE
 125 CLASS="FUNCDEF"
 126 >void usbs_eth_start_tx</CODE
 127 >(usbs_eth* usbseth, unsigned char* buffer, void (*)(usbs_eth*, void*, int) complete_fn, void* complete_data);</CODE
 128 ></P
 129 ><P
 130 ></P
 131 ></DIV
 132 ></DIV
 133 ><DIV
 134 CLASS="REFSECT1"
 135 ><A
 136 NAME="AEN122"
 137 ></A
 138 ><H2
 139 >Description</H2
 140 ><P
 141 >The USB-ethernet package provides two main modes of operation. In the
 142 first mode it provides a <A
 143 HREF="usbseth-netdev.html"
 144 >network device
 145 driver</A
 146 > for use by a TCP/IP stack running inside the USB
 147 peripheral. All incoming ethernet packages should be passed up the
 148 TCP/IP stack, and only the stack will generate outgoing packets. Apart
 149 from <A
 150 HREF="usbseth-init.html"
 151 >initialization</A
 152 > and possibly
 153 certain <A
 154 HREF="usbseth-control.html"
 155 >control operations</A
 156 >,
 157 higher-level code will not interact with the USB-ethernet package
 158 directly.</P
 159 ><P
 160 >In the second mode there is no TCP/IP stack running inside the USB
 161 peripheral. For example, a simple USB-ethernet converter has an
 162 ethernet chip and a USB port: ethernet packets received by the
 163 ethernet chip need to be forwarded to the USB host, and ethernet
 164 packets sent by the USB host need to be sent out of the ethernet chip.
 165 <TT
 166 CLASS="FUNCTION"
 167 >usbs_eth_start_rx</TT
 168 > and
 169 <TT
 170 CLASS="FUNCTION"
 171 >usbs_eth_start_tx</TT
 172 > allow for this lower-level
 173 access to the USB-ethernet package.</P
 174 ><P
 175 >The two modes of operation are mutually exclusive. If the network
 176 device driver mode is enabled then application code should communicate
 177 at the TCP/IP level, and not by using the lower-level functions.
 178 Instead, it is the network device driver that will make use of these
 179 functions, and it assumes that it has exclusive access. The package
 180 does not perform any locking.</P
 181 ><P
 182 >The transmit and receive functions work in much the same way. The
 183 first argument identifies the <SPAN
 184 CLASS="STRUCTNAME"
 185 >usbs_eth</SPAN
 186 >
 187 structure that should be used. For the majority of applications this
 188 will be <TT
 189 CLASS="LITERAL"
 190 >usbs_eth0</TT
 191 >. The second argument specifies
 192 the location of the ethernet packet; outgoing for
 193 <TT
 194 CLASS="FUNCTION"
 195 >usbs_eth_start_tx</TT
 196 > and incoming for
 197 <TT
 198 CLASS="FUNCTION"
 199 >usbs_eth_start_rx</TT
 200 >. This buffer should correspond
 201 to the <A
 202 HREF="usbseth-protocol.html"
 203 >protocol</A
 204 >:</P
 205 ><P
 206 ></P
 207 ><OL
 208 TYPE="1"
 209 ><LI
 210 ><P
 211 >Outgoing packets can consist of up to 1516 bytes, consisting of a
 212 two-byte header specific to USB-ethernet followed by a standard
 213 ethernet frame (a header with 6-byte destination address, 6-byte
 214 source address and a further two bytes, followed by a payload of
 215 up to 1500 bytes). The two-byte USB-ethernet header consists simply of
 216 the size of the ethernet frame, i.e. the size of the rest of the
 217 packet not including the USB-ethernet header, with the least
 218 significant byte first.</P
 219 ></LI
 220 ><LI
 221 ><P
 222 >For incoming packets the supplied buffer should usually be at least
 223 1516 bytes. There may be special circumstances in which a smaller
 224 buffer might be safe; for example, if the host-side device driver is
 225 modified to support only smaller packets. Once the packet has been
 226 received the buffer will contain a two-byte header specific to
 227 USB-ethernet, followed by a normal ethernet frame. The header
 228 gives the size of the ethernet frame, excluding the header, with the
 229 least significant byte first.</P
 230 ></LI
 231 ></OL
 232 ><P
 233 >Both <TT
 234 CLASS="FUNCTION"
 235 >usbs_eth_start_tx</TT
 236 > and
 237 <TT
 238 CLASS="FUNCTION"
 239 >usbs_eth_start_rx</TT
 240 > are asynchronous: the transfer
 241 is started and, some time later, a completion function will be invoked.
 242 The third and fourth arguments to both
 243 <TT
 244 CLASS="FUNCTION"
 245 >usbs_eth_start_tx</TT
 246 > and
 247 <TT
 248 CLASS="FUNCTION"
 249 >usbs_eth_start_rx</TT
 250 > supply the completion function
 251 and an argument to that function respectively. The completion function
 252 will be invoked with three arguments: a pointer to the
 253 <SPAN
 254 CLASS="STRUCTNAME"
 255 >usbs_eth</SPAN
 256 > data structure, usually
 257 <TT
 258 CLASS="LITERAL"
 259 >usbs_eth0</TT
 260 >; the supplied completion data ; and a
 261 return code field. A negative value indicates that an error occurred,
 262 for example <TT
 263 CLASS="LITERAL"
 264 >-EPIPE</TT
 265 > if the connection between USB
 266 host and peripheral has been broken, or <TT
 267 CLASS="LITERAL"
 268 >-EAGAIN</TT
 269 > if
 270 an endpoint has been halted. A positive value indicates the total size
 271 of the transfer, which should correspond to the size in the
 272 USB-ethernet header plus an additional two bytes for the header
 273 itself.</P
 274 ><P
 275 >If the data transfer is succesful then the completion function will
 276 typically be invoked in DSR context rather than in thread context,
 277 although this depends on the implementation of the underlying USB
 278 device driver. Therefore the completion function is restricted in what
 279 it can do; in particular, it must not make any calls that will or may
 280 block such as locking a mutex or allocating memory. The kernel
 281 documentation should be consulted for more details of DSR's and
 282 interrupt handling generally. Note that if the transfer finishes
 283 quickly then the completion function may be invoked before
 284 <TT
 285 CLASS="FUNCTION"
 286 >usbs_eth_start_rx</TT
 287 > or
 288 <TT
 289 CLASS="FUNCTION"
 290 >usbs_eth_start_tx</TT
 291 > returns. This is especially
 292 likely to happen if the current thread is descheduled after starting
 293 the data transfer but before returning from these functions.</P
 294 ><P
 295 >For transmit operations, it is possible for
 296 <TT
 297 CLASS="FUNCTION"
 298 >usbs_eth_start_tx</TT
 299 > to invoke the completion
 300 function immediately. If there is no current connection between host
 301 and target then the transmit will fail immediately with
 302 <TT
 303 CLASS="LITERAL"
 304 >-EPIPE</TT
 305 >. In addition the USB-ethernet package will
 306 check the destination MAC address and make sure that the ethernet
 307 frame really is intended for the host: either it must be for the
 308 address specified in the initialization call <A
 309 HREF="usbseth-init.html"
 310 ><TT
 311 CLASS="FUNCTION"
 312 >usbs_eth_init</TT
 313 ></A
 314 >, or
 315 it must be a broadcast packet, or the host must have enabled
 316 promiscuous mode. </P
 317 ></DIV
 318 ><DIV
 319 CLASS="NAVFOOTER"
 320 ><HR
 321 ALIGN="LEFT"
 322 WIDTH="100%"><TABLE
 323 WIDTH="100%"
 324 BORDER="0"
 325 CELLPADDING="0"
 326 CELLSPACING="0"
 327 ><TR
 328 ><TD
 329 WIDTH="33%"
 330 ALIGN="left"
 331 VALIGN="top"
 332 ><A
 333 HREF="usbseth-init.html"
 334 >Prev</A
 335 ></TD
 336 ><TD
 337 WIDTH="34%"
 338 ALIGN="center"
 339 VALIGN="top"
 340 ><A
 341 HREF="io-usb-slave-eth.html"
 342 >Home</A
 343 ></TD
 344 ><TD
 345 WIDTH="33%"
 346 ALIGN="right"
 347 VALIGN="top"
 348 ><A
 349 HREF="usbseth-control.html"
 350 >Next</A
 351 ></TD
 352 ></TR
 353 ><TR
 354 ><TD
 355 WIDTH="33%"
 356 ALIGN="left"
 357 VALIGN="top"
 358 >Initializing the USB-ethernet Package</TD
 359 ><TD
 360 WIDTH="34%"
 361 ALIGN="center"
 362 VALIGN="top"
 363 >&nbsp;</TD
 364 ><TD
 365 WIDTH="33%"
 366 ALIGN="right"
 367 VALIGN="top"
 368 >USB-ethernet State Handling</TD
 369 ></TR
 370 ></TABLE
 371 ></DIV
 372 ></BODY
 373 ></HTML
 374 >