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. -->
12 >Sending Data to the Host</TITLE
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
22 TITLE="eCos USB Slave Support"
23 HREF="io-usb-slave.html"><LINK
25 TITLE="Receiving Data from the Host"
26 HREF="usbs-start-rx.html"><LINK
28 TITLE="Halted Endpoints"
29 HREF="usbs-halt.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="usbs-start-rx.html"
82 NAME="USBS-START-TX">Sending Data to the Host</H1
92 >usbs_start_tx_buffer</TT
93 > -- Sending Data to the Host</DIV
95 CLASS="REFSYNOPSISDIV"
111 CLASS="FUNCSYNOPSISINFO"
112 >#include <cyg/io/usb/usbs.h></PRE
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
127 >void usbs_start_tx</CODE
128 >(usbs_tx_endpoint* ep);</CODE
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"
155 >usbs_control_endpoint</SPAN
158 data structure directly. The function takes five arguments:</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
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"
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
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
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
222 >, or the amount of data
223 transferred which should correspond to the
229 > argument. The most likely errors are
233 > to indicate that the connection between the
234 host and the target has been broken, and <TT
238 for when the endpoint has been <A
239 HREF="usbs-halt.html"
241 >. Specific USB device drivers may
242 define additional error conditions.</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
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
268 >It is possible that the completion function will be invoked before
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
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
286 >usbs_start_tx_buffer</TT
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
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
301 >The following code fragment illustrates a very simple use of
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
316 CLASS="PROGRAMLISTING"
317 >static int error_code = 0;
318 static cyg_sem_t completion_wait;
321 completion_fn(void* data, int result)
324 cyg_semaphore_post(&completion_wait);
328 blocking_transmit(usbs_tx_endpoint* ep, const unsigned char* buf, int len)
331 usbs_start_tx_buffer(ep, buf, len, &completion_fn, NULL);
332 cyg_semaphore_wait(&completion_wait);
339 >There is also a utility function <TT
343 can be used by code that wants to manipulate <A
344 HREF="usbs-data.html"
346 > directly, specifically the
374 > just calls a function supplied by
375 the device driver.</P
382 SUMMARY="Footer navigation table"
393 HREF="usbs-start-rx.html"
411 HREF="usbs-halt.html"
421 >Receiving Data from the Host</TD
427 HREF="io-usb-slave.html"
435 >Halted Endpoints</TD