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 >Data Endpoints</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="Control Endpoints"
26 HREF="usbs-control.html"><LINK
28 TITLE="Writing a USB Device Driver"
29 HREF="usbs-writing.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="usbs-control.html"
71 HREF="usbs-writing.html"
82 NAME="USBS-DATA">Data Endpoints</H1
90 >Data Endpoints -- Data endpoint data structures</DIV
92 CLASS="REFSYNOPSISDIV"
104 >#include <cyg/io/usb/usbs.h>
106 typedef struct usbs_rx_endpoint {
107 void (*start_rx_fn)(struct usbs_rx_endpoint*);
108 void (*set_halted_fn)(struct usbs_rx_endpoint*, cyg_bool);
109 void (*complete_fn)(void*, int);
111 unsigned char* buffer;
116 typedef struct usbs_tx_endpoint {
117 void (*start_tx_fn)(struct usbs_tx_endpoint*);
118 void (*set_halted_fn)(struct usbs_tx_endpoint*, cyg_bool);
119 void (*complete_fn)(void*, int);
121 const unsigned char* buffer;
124 } usbs_tx_endpoint;</PRE
135 >Receive and Transmit Data Structures</H2
137 >In addition to a single <SPAN
139 >usbs_control_endpoint</SPAN
141 data structure per USB slave device, the USB device driver should also
142 provide receive and transmit data structures corresponding to the
143 other endpoints. The names of these are determined by the device
144 driver. For example, the SA1110 USB device driver package provides
154 >Unlike control endpoints, the common USB slave package does provide a
155 number of utility routines to manipulate data endpoints. For example
157 HREF="usbs-start-rx.html"
160 >usbs_start_rx_buffer</TT
163 can be used to receive data from the host into a buffer. In addition
164 the USB device driver can provide devtab entries such as
172 higher-level code can <TT
175 > these devices and then
185 >However, the operation of data endpoints and the various
186 endpoint-related functions is relatively straightforward. First
189 >usbs_rx_endpoint</SPAN
191 device driver will provide the members
203 >, and it will maintain the
209 > field. To receive data, higher-level
239 > member should be called. When
240 the transfer has finished the device driver will invoke the completion
247 argument and a size field for the second argument. A negative size
248 indicates an error of some sort: <TT
252 that the endpoint has been halted, usually at the request of the host;
256 > indicates that the connection between the
257 host and the peripheral has been broken. Certain device drivers may
258 generate other error codes.</P
260 >If higher-level code needs to halt or unhalt an endpoint then it can
267 endpoint is halted, invoking <TT
278 > set to 0 indicates that
279 higher-level code wants to block until the endpoint is no longer
280 halted; at that point the completion function will be invoked.</P
282 >USB device drivers are allowed to assume that higher-level protocols
283 ensure that host and peripheral agree on the amount of data that will
284 be transferred, or at least on an upper bound. Therefore there is no
285 need for the device driver to maintain its own buffers, and copy
286 operations are avoided. If the host sends more data than expected then
287 the resulting behaviour is undefined.</P
289 >Transmit endpoints work in essentially the same way as receive
290 endpoints. Higher-level code should set the
302 > fields to point at the data to
303 be transferred, then call <TT
309 the device driver will invoked the completion function when the
310 transfer has completed.</P
312 >USB device drivers are not expected to perform any locking. If at any
313 time there are two concurrent receive operations for a given endpoint,
314 or two concurrent transmit operations, then the resulting behaviour is
315 undefined. It is the responsibility of higher-level code to perform
316 any synchronisation that may be necessary. In practice, conflicts are
317 unlikely because typically a given endpoint will only be accessed
318 sequentially by just one part of the overall system.</P
325 SUMMARY="Footer navigation table"
336 HREF="usbs-control.html"
354 HREF="usbs-writing.html"
364 >Control Endpoints</TD
370 HREF="io-usb-slave.html"
378 >Writing a USB Device Driver</TD