doc/html/ref/usbs-start-tx.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 >Sending Data to 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="Receiving Data from the Host"
  26 HREF="usbs-start-rx.html"><LINK
  27 REL="NEXT"
  28 TITLE="Halted Endpoints"
  29 HREF="usbs-halt.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-start-rx.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-halt.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-TX">Sending Data to the Host</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN16386"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 ><TT
  91 CLASS="FUNCTION"
  92 >usbs_start_tx_buffer</TT
  93 >&nbsp;--&nbsp;Sending Data to the Host</DIV
  94 ><DIV
  95 CLASS="REFSYNOPSISDIV"
  96 ><A
  97 NAME="AEN16390"><H2
  98 >Synopsis</H2
  99 ><DIV
 100 CLASS="FUNCSYNOPSIS"
 101 ><A
 102 NAME="AEN16391"><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_tx_buffer</CODE
 121 >(usbs_tx_endpoint* ep, const 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_tx</CODE
 128 >(usbs_tx_endpoint* ep);</CODE
 129 ></P
 130 ><P
 131 ></P
 132 ></DIV
 133 ></DIV
 134 ><DIV
 135 CLASS="REFSECT1"
 136 ><A
 137 NAME="AEN16411"
 138 ></A
 139 ><H2
 140 ><TT
 141 CLASS="FUNCTION"
 142 >Description</TT
 143 ></H2
 144 ><P
 145 ><TT
 146 CLASS="FUNCTION"
 147 >usbs_start_tx_buffer</TT
 148 > is a USB-specific function
 149 to transfer data from peripheral to host. 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 allowed to modify the buffer during the transfer, so the data can
 186 reside in read-only memory. The transfer will be for all the data
 187 specified, and it is the responsibility of higher-level code to make
 188 sure that the host is expecting this amount of data. For isochronous
 189 transfers the USB specification imposes an upper bound of 1023 bytes,
 190 but a smaller limit may be set in the <A
 191 HREF="usbs-enum.html#AEN16179"
 192 >enumeration data</A
 193 >. Interrupt
 194 transfers have an upper bound of 64 bytes or less, as per the
 195 enumeration data. Bulk transfers are more complicated because they can
 196 involve multiple 64-byte packets plus a terminating packet of less
 197 than 64 bytes, so the basic USB specification does not impose an upper
 198 limit on the total transfer size. Instead it is left to higher-level
 199 protocols to specify an appropriate upper bound. If the peripheral
 200 attempts to send more data than the host is willing to accept then the
 201 resulting behaviour is undefined and may well depend on the specific
 202 host operating system being used.</P
 203 ><P
 204 >For bulk transfers, the USB device driver or the underlying hardware
 205 will automatically split the transfer up into the appropriate number
 206 of full-size 64-byte packets plus a single terminating packet, which
 207 may be 0 bytes.</P
 208 ></LI
 209 ><LI
 210 ><P
 211 ><TT
 212 CLASS="FUNCTION"
 213 >usbs_start_tx_buffer</TT
 214 > is non-blocking. It merely
 215 starts the transmit operation, and does not wait for completion. At
 216 some later point the USB device driver will invoke the completion
 217 function parameter with two arguments: the completion data defined by
 218 the last parameter, and a result field. This result will be either an
 219 error code &lt; <TT
 220 CLASS="LITERAL"
 221 >0</TT
 222 >, or the amount of data
 223 transferred which should correspond to the
 224 <TT
 225 CLASS="PARAMETER"
 226 ><I
 227 >length</I
 228 ></TT
 229 > argument. The most likely errors are
 230 <TT
 231 CLASS="LITERAL"
 232 >-EPIPE</TT
 233 > to indicate that the connection between the
 234 host and the target has been broken, and <TT
 235 CLASS="LITERAL"
 236 >-EAGAIN</TT
 237 >
 238 for when the endpoint has been <A
 239 HREF="usbs-halt.html"
 240 >halted</A
 241 >. Specific USB device drivers may
 242 define additional error conditions.</P
 243 ></LI
 244 ></OL
 245 ><P
 246 >The normal sequence of events is that the USB device driver will
 247 update the appropriate hardware registers. At some point after that
 248 the host will attempt to fetch data by transmitting an IN token. Since
 249 a transmit operation is now in progress the peripheral can send a
 250 packet of data, and the host will generate an ACK. At this point the
 251 USB hardware will generate an interrupt, and the device driver will
 252 service this interrupt and arrange for a DSR to be called. Isochronous
 253 and interrupt transfers involve just a single packet. However, bulk
 254 transfers may involve multiple packets so the device driver has to
 255 check whether there is more data to send and set things up for the
 256 next packet. When the device driver DSR detects a complete transfer it
 257 will inform higher-level code by invoking the supplied completion
 258 function.</P
 259 ><P
 260 >This means that the completion function will normally be invoked by a
 261 DSR and not in thread context - although some USB device drivers may
 262 have a different implementation. Therefore the completion function is
 263 restricted in what it can do, in particular it must not make any
 264 calls that will or may block such as locking a mutex or allocating
 265 memory. The kernel documentation should be consulted for more details
 266 of DSR's and interrupt handling generally.</P
 267 ><P
 268 >It is possible that the completion function will be invoked before
 269 <TT
 270 CLASS="FUNCTION"
 271 >usbs_start_tx_buffer</TT
 272 > returns. Such an event would
 273 be unusual because the transfer cannot happen until the next time the
 274 host tries to fetch data from this peripheral, but it may happen if,
 275 for example, another interrupt happens and a higher priority thread is
 276 scheduled to run. Also, if the endpoint is currently halted then the
 277 completion function will be invoked immediately with
 278 <TT
 279 CLASS="LITERAL"
 280 >-EAGAIN</TT
 281 >: typically this will happen in the current
 282 thread rather than in a separate DSR. The completion function is
 283 allowed to start another transfer immediately by calling
 284 <TT
 285 CLASS="FUNCTION"
 286 >usbs_start_tx_buffer</TT
 287 > again.</P
 288 ><P
 289 >USB device drivers are not expected to perform any locking. It is the
 290 responsibility of higher-level code to ensure that there is only one
 291 transmit operation for a given endpoint in progress at any one time.
 292 If there are concurrent calls to
 293 <TT
 294 CLASS="FUNCTION"
 295 >usbs_start_tx_buffer</TT
 296 > then the resulting behaviour
 297 is undefined. For typical USB applications this does not present any
 298 problems because only piece of code will access a given endpoint at
 299 any particular time.</P
 300 ><P
 301 >The following code fragment illustrates a very simple use of
 302 <TT
 303 CLASS="FUNCTION"
 304 >usbs_start_tx_buffer</TT
 305 > to implement a blocking
 306 transmit, using a semaphore to synchronise between the foreground
 307 thread and the DSR. For a simple example like this no completion data
 308 is needed.</P
 309 ><TABLE
 310 BORDER="5"
 311 BGCOLOR="#E0E0F0"
 312 WIDTH="70%"
 313 ><TR
 314 ><TD
 315 ><PRE
 316 CLASS="PROGRAMLISTING"
 317 >static int error_code = 0;
 318 static cyg_sem_t completion_wait;
 319
 320 static void
 321 completion_fn(void* data, int result)
 322 {
 323     error_code = result;
 324     cyg_semaphore_post(&amp;completion_wait);
 325 }
 326
 327 int
 328 blocking_transmit(usbs_tx_endpoint* ep, const unsigned char* buf, int len)
 329 {
 330     error_code = 0;
 331     usbs_start_tx_buffer(ep, buf, len, &amp;completion_fn, NULL);
 332     cyg_semaphore_wait(&amp;completion_wait);
 333     return error_code;
 334 }</PRE
 335 ></TD
 336 ></TR
 337 ></TABLE
 338 ><P
 339 >There is also a utility function <TT
 340 CLASS="FUNCTION"
 341 >usbs_start</TT
 342 >. This
 343 can be used by code that wants to manipulate <A
 344 HREF="usbs-data.html"
 345 >data endpoints</A
 346 > directly, specifically the
 347 <TT
 348 CLASS="STRUCTFIELD"
 349 ><I
 350 >complete_fn</I
 351 ></TT
 352 >,
 353 <TT
 354 CLASS="STRUCTFIELD"
 355 ><I
 356 >complete_data</I
 357 ></TT
 358 >,
 359 <TT
 360 CLASS="STRUCTFIELD"
 361 ><I
 362 >buffer</I
 363 ></TT
 364 > and
 365 <TT
 366 CLASS="STRUCTFIELD"
 367 ><I
 368 >buffer_size</I
 369 ></TT
 370 > fields.
 371 <TT
 372 CLASS="FUNCTION"
 373 >usbs_start_tx</TT
 374 > just calls a function supplied by
 375 the device driver.</P
 376 ></DIV
 377 ><DIV
 378 CLASS="NAVFOOTER"
 379 ><HR
 380 ALIGN="LEFT"
 381 WIDTH="100%"><TABLE
 382 SUMMARY="Footer navigation table"
 383 WIDTH="100%"
 384 BORDER="0"
 385 CELLPADDING="0"
 386 CELLSPACING="0"
 387 ><TR
 388 ><TD
 389 WIDTH="33%"
 390 ALIGN="left"
 391 VALIGN="top"
 392 ><A
 393 HREF="usbs-start-rx.html"
 394 ACCESSKEY="P"
 395 >Prev</A
 396 ></TD
 397 ><TD
 398 WIDTH="34%"
 399 ALIGN="center"
 400 VALIGN="top"
 401 ><A
 402 HREF="ecos-ref.html"
 403 ACCESSKEY="H"
 404 >Home</A
 405 ></TD
 406 ><TD
 407 WIDTH="33%"
 408 ALIGN="right"
 409 VALIGN="top"
 410 ><A
 411 HREF="usbs-halt.html"
 412 ACCESSKEY="N"
 413 >Next</A
 414 ></TD
 415 ></TR
 416 ><TR
 417 ><TD
 418 WIDTH="33%"
 419 ALIGN="left"
 420 VALIGN="top"
 421 >Receiving Data from the Host</TD
 422 ><TD
 423 WIDTH="34%"
 424 ALIGN="center"
 425 VALIGN="top"
 426 ><A
 427 HREF="io-usb-slave.html"
 428 ACCESSKEY="U"
 429 >Up</A
 430 ></TD
 431 ><TD
 432 WIDTH="33%"
 433 ALIGN="right"
 434 VALIGN="top"
 435 >Halted Endpoints</TD
 436 ></TR
 437 ></TABLE
 438 ></DIV
 439 ></BODY
 440 ></HTML
 441 >