doc/html/ref/usbs-start-rx.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 >Receiving Data from the Host</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 USB Slave Support"
  23 HREF="io-usb-slave.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Devtab Entries"
  26 HREF="usbs-devtab.html"><LINK
  27 REL="NEXT"
  28 TITLE="Sending Data to the Host"
  29 HREF="usbs-start-tx.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="usbs-devtab.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="usbs-start-tx.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="USBS-START-RX">Receiving Data from the Host</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN16314"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 ><TT
  91 CLASS="FUNCTION"
  92 >usbs_start_rx_buffer</TT
  93 >&nbsp;--&nbsp;Receiving Data from the Host</DIV
  94 ><DIV
  95 CLASS="REFSYNOPSISDIV"
  96 ><A
  97 NAME="AEN16318"><H2
  98 >Synopsis</H2
  99 ><DIV
 100 CLASS="FUNCSYNOPSIS"
 101 ><A
 102 NAME="AEN16319"><P
 103 ></P
 104 ><TABLE
 105 BORDER="5"
 106 BGCOLOR="#E0E0F0"
 107 WIDTH="70%"
 108 ><TR
 109 ><TD
 110 ><PRE
 111 CLASS="FUNCSYNOPSISINFO"
 112 >#include &lt;cyg/io/usb/usbs.h&gt;</PRE
 113 ></TD
 114 ></TR
 115 ></TABLE
 116 ><P
 117 ><CODE
 118 ><CODE
 119 CLASS="FUNCDEF"
 120 >void usbs_start_rx_buffer</CODE
 121 >(usbs_rx_endpoint* ep, unsigned char* buffer, int length, void (*)(void*,int) complete_fn, void * complete_data);</CODE
 122 ></P
 123 ><P
 124 ><CODE
 125 ><CODE
 126 CLASS="FUNCDEF"
 127 >void usbs_start_rx</CODE
 128 >(usbs_rx_endpoint* ep);</CODE
 129 ></P
 130 ><P
 131 ></P
 132 ></DIV
 133 ></DIV
 134 ><DIV
 135 CLASS="REFSECT1"
 136 ><A
 137 NAME="AEN16339"
 138 ></A
 139 ><H2
 140 ><TT
 141 CLASS="FUNCTION"
 142 >Description</TT
 143 ></H2
 144 ><P
 145 ><TT
 146 CLASS="FUNCTION"
 147 >usbs_start_rx_buffer</TT
 148 > is a USB-specific function
 149 to accept a transfer from host to peripheral. It can be used for bulk,
 150 interrupt or isochronous transfers, but not for control messages.
 151 Instead those involve manipulating the <A
 152 HREF="usbs-control.html"
 153 ><SPAN
 154 CLASS="STRUCTNAME"
 155 >usbs_control_endpoint</SPAN
 156 ></A
 157 >
 158 data structure directly. The function takes five arguments:</P
 159 ><P
 160 ></P
 161 ><OL
 162 TYPE="1"
 163 ><LI
 164 ><P
 165 >The first argument identifies the specific endpoint that should be
 166 used. Different USB devices will support different sets of endpoints
 167 and the device driver will provide appropriate data structures. The
 168 device driver's documentation should be consulted for details of which
 169 endpoints are available.</P
 170 ></LI
 171 ><LI
 172 ><P
 173 >The <TT
 174 CLASS="PARAMETER"
 175 ><I
 176 >buffer</I
 177 ></TT
 178 > and <TT
 179 CLASS="PARAMETER"
 180 ><I
 181 >length</I
 182 ></TT
 183 >
 184 arguments control the actual transfer. USB device drivers are not
 185 expected to perform any buffering or to support partial transfers, so
 186 the length specified should correspond to the maximum transfer that is
 187 currently possible and the buffer should be at least this large. For
 188 isochronous transfers the USB specification imposes an upper bound of
 189 1023 bytes, and a smaller limit may be set in the <A
 190 HREF="usbs-enum.html#AEN16179"
 191 >enumeration data</A
 192 >. Interrupt
 193 transfers are similarly straightforward with an upper bound of 64
 194 bytes, or less as per the enumeration data. Bulk transfers are more
 195 complicated because they can involve multiple 64-byte packets plus a
 196 terminating packet of less than 64 bytes, so there is no predefined
 197 limit on the transfer size. Instead it is left to higher-level
 198 protocols to specify an appropriate upper bound.</P
 199 ><P
 200 >One technique that may work for bulk transfers is to exploit the fact
 201 that such transfers happen in 64-byte packets: it may be possible to
 202 receive an initial 64 bytes, corresponding to the first packet in the
 203 transfer; these 64 bytes can then be examined to determine the total
 204 transfer size, and the remaining data can be transferred in another
 205 receive operation. This technique is not guaranteed to work with all
 206 USB hardware. Also, if the delay between accepting the first packet and
 207 the remainder of the transfer is excessive then this could cause
 208 timeout problems for the host-side software. For these reasons this
 209 technique should be avoided.</P
 210 ></LI
 211 ><LI
 212 ><P
 213 ><TT
 214 CLASS="FUNCTION"
 215 >usbs_start_rx_buffer</TT
 216 > is non-blocking. It merely
 217 starts the receive operation, and does not wait for completion. At
 218 some later point the USB device driver will invoke the completion
 219 function parameter with two arguments: the completion data defined by
 220 the last parameter and a result field. A result &gt;=
 221 <TT
 222 CLASS="LITERAL"
 223 >0</TT
 224 > indicates a successful transfer of that many
 225 bytes, which may be less than the upper bound imposed by the
 226 <TT
 227 CLASS="PARAMETER"
 228 ><I
 229 >length</I
 230 ></TT
 231 > argument. A result &lt;
 232 <TT
 233 CLASS="LITERAL"
 234 >0</TT
 235 > indicates an error. The most likely errors are
 236 <TT
 237 CLASS="LITERAL"
 238 >-EPIPE</TT
 239 > to indicate that the connection between the
 240 host and the target has been broken, and <TT
 241 CLASS="LITERAL"
 242 >-EAGAIN</TT
 243 >
 244 for when the endpoint has been <A
 245 HREF="usbs-halt.html"
 246 >halted</A
 247 >. Specific USB device drivers may
 248 specify additional error conditions.</P
 249 ></LI
 250 ></OL
 251 ><P
 252 >The normal sequence of events is that the USB device driver will
 253 update the appropriate hardware registers. At some point after that
 254 the host will attempt to send data by transmitting an OUT token
 255 followed by a data packet, and since a receive operation is now in
 256 progress the data will be accepted and ACK'd. If there were no receive
 257 operation then the peripheral would instead generate a NAK. The USB
 258 hardware will generate an interrupt once the whole packet has been
 259 received, and the USB device driver will service this interrupt and
 260 arrange for a DSR to be called. Isochronous and interrupt transfers
 261 involve just a single packet. However, bulk transfers may involve
 262 multiple packets so the device driver has to check whether the packet
 263 was a full 64 bytes or whether it was a terminating packet of less
 264 than this. When the device driver DSR detects a complete transfer it
 265 will inform higher-level code by invoking the supplied completion
 266 function.</P
 267 ><P
 268 >This means that the completion function will normally be invoked by a
 269 DSR and not in thread context - although some USB device drivers may
 270 have a different implementation. Therefore the completion function is
 271 restricted in what it can do. In particular it must not make any
 272 calls that will or may block such as locking a mutex or allocating
 273 memory. The kernel documentation should be consulted for more details
 274 of DSR's and interrupt handling generally.</P
 275 ><P
 276 >It is possible that the completion function will be invoked before
 277 <TT
 278 CLASS="FUNCTION"
 279 >usbs_start_rx_buffer</TT
 280 > returns. Such an event would
 281 be unusual because the transfer cannot happen until the next time the
 282 host tries to send data to this peripheral, but it may happen if for
 283 example another interrupt happens and a higher priority thread is
 284 scheduled to run. Also, if the endpoint is currently halted then the
 285 completion function will be invoked immediately with
 286 <TT
 287 CLASS="LITERAL"
 288 >-EAGAIN</TT
 289 >: typically this will happen in the current
 290 thread rather than in a separate DSR. The completion function is
 291 allowed to start another transfer immediately by calling
 292 <TT
 293 CLASS="FUNCTION"
 294 >usbs_start_rx_buffer</TT
 295 > again.</P
 296 ><P
 297 >USB device drivers are not expected to perform any locking. It is the
 298 responsibility of higher-level code to ensure that there is only one
 299 receive operation for a given endpoint in progress at any one time. If
 300 there are concurrent calls to
 301 <TT
 302 CLASS="FUNCTION"
 303 >usbs_start_rx_buffer</TT
 304 > then the resulting behaviour
 305 is undefined. For typical USB applications this does not present any
 306 problems, because only one piece of code will access a given endpoint
 307 at any particular time.</P
 308 ><P
 309 >The following code fragment illustrates a very simple use of
 310 <TT
 311 CLASS="FUNCTION"
 312 >usbs_start_rx_buffer</TT
 313 > to implement a blocking
 314 receive, using a semaphore to synchronise between the foreground
 315 thread and the DSR. For a simple example like this no completion data
 316 is needed.</P
 317 ><TABLE
 318 BORDER="5"
 319 BGCOLOR="#E0E0F0"
 320 WIDTH="70%"
 321 ><TR
 322 ><TD
 323 ><PRE
 324 CLASS="PROGRAMLISTING"
 325 >static int error_code = 0;
 326 static cyg_sem_t completion_wait;
 327
 328 static void
 329 completion_fn(void* data, int result)
 330 {
 331     error_code = result;
 332     cyg_semaphore_post(&amp;completion_wait);
 333 }
 334
 335 int
 336 blocking_receive(usbs_rx_endpoint* ep, unsigned char* buf, int len)
 337 {
 338     error_code = 0;
 339     usbs_start_rx_buffer(ep, buf, len, &amp;completion_fn, NULL);
 340     cyg_semaphore_wait(&amp;completion_wait);
 341     return error_code;
 342 }</PRE
 343 ></TD
 344 ></TR
 345 ></TABLE
 346 ><P
 347 >There is also a utility function <TT
 348 CLASS="FUNCTION"
 349 >usbs_start_rx</TT
 350 >. This
 351 can be used by code that wants to manipulate <A
 352 HREF="usbs-data.html"
 353 >data endpoints</A
 354 > directly, specifically the
 355 <TT
 356 CLASS="STRUCTFIELD"
 357 ><I
 358 >complete_fn</I
 359 ></TT
 360 >,
 361 <TT
 362 CLASS="STRUCTFIELD"
 363 ><I
 364 >complete_data</I
 365 ></TT
 366 >,
 367 <TT
 368 CLASS="STRUCTFIELD"
 369 ><I
 370 >buffer</I
 371 ></TT
 372 > and
 373 <TT
 374 CLASS="STRUCTFIELD"
 375 ><I
 376 >buffer_size</I
 377 ></TT
 378 > fields.
 379 <TT
 380 CLASS="FUNCTION"
 381 >usbs_start_tx</TT
 382 > just invokes a function
 383 supplied by the device driver.</P
 384 ></DIV
 385 ><DIV
 386 CLASS="NAVFOOTER"
 387 ><HR
 388 ALIGN="LEFT"
 389 WIDTH="100%"><TABLE
 390 SUMMARY="Footer navigation table"
 391 WIDTH="100%"
 392 BORDER="0"
 393 CELLPADDING="0"
 394 CELLSPACING="0"
 395 ><TR
 396 ><TD
 397 WIDTH="33%"
 398 ALIGN="left"
 399 VALIGN="top"
 400 ><A
 401 HREF="usbs-devtab.html"
 402 ACCESSKEY="P"
 403 >Prev</A
 404 ></TD
 405 ><TD
 406 WIDTH="34%"
 407 ALIGN="center"
 408 VALIGN="top"
 409 ><A
 410 HREF="ecos-ref.html"
 411 ACCESSKEY="H"
 412 >Home</A
 413 ></TD
 414 ><TD
 415 WIDTH="33%"
 416 ALIGN="right"
 417 VALIGN="top"
 418 ><A
 419 HREF="usbs-start-tx.html"
 420 ACCESSKEY="N"
 421 >Next</A
 422 ></TD
 423 ></TR
 424 ><TR
 425 ><TD
 426 WIDTH="33%"
 427 ALIGN="left"
 428 VALIGN="top"
 429 >Devtab Entries</TD
 430 ><TD
 431 WIDTH="34%"
 432 ALIGN="center"
 433 VALIGN="top"
 434 ><A
 435 HREF="io-usb-slave.html"
 436 ACCESSKEY="U"
 437 >Up</A
 438 ></TD
 439 ><TD
 440 WIDTH="33%"
 441 ALIGN="right"
 442 VALIGN="top"
 443 >Sending Data to the Host</TD
 444 ></TR
 445 ></TABLE
 446 ></DIV
 447 ></BODY
 448 ></HTML
 449 >