doc/html/ref/usbseth-data.html

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