1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
|
<!-- Copyright (C) 2002 Free Software Foundation, Inc. -->
<!-- This material may be distributed only subject to the terms -->
<!-- and conditions set forth in the Open Publication License, v1.0 -->
<!-- or later (the latest version is presently available at -->
<!-- http://www.opencontent.org/openpub/). -->
<!-- Distribution of substantively modified versions of this -->
<!-- document is prohibited without the explicit permission of the -->
<!-- copyright holder. -->
<!-- Distribution of the work or derivative of the work in any -->
<!-- standard (paper) book form is prohibited unless prior -->
<!-- permission is obtained from the copyright holder. -->
<HTML
><HEAD
><TITLE
>Data Endpoints</TITLE
><meta name="MSSmartTagsPreventParsing" content="TRUE">
<META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.64
"><LINK
REL="HOME"
TITLE="eCos USB Slave Support"
HREF="io-usb-slave.html"><LINK
REL="PREVIOUS"
TITLE="Control Endpoints"
HREF="usbs-control.html"><LINK
REL="NEXT"
TITLE="Writing a USB Device Driver"
HREF="usbs-writing.html"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>eCos USB Slave Support</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="usbs-control.html"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="usbs-writing.html"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="USBS-DATA"
>Data Endpoints</A
></H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN623"
></A
><H2
>Name</H2
>Data Endpoints -- Data endpoint data structures</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN626"
></A
><H2
>Synopsis</H2
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="SYNOPSIS"
>#include <cyg/io/usb/usbs.h>
typedef struct usbs_rx_endpoint {
void (*start_rx_fn)(struct usbs_rx_endpoint*);
void (*set_halted_fn)(struct usbs_rx_endpoint*, cyg_bool);
void (*complete_fn)(void*, int);
void* complete_data;
unsigned char* buffer;
int buffer_size;
cyg_bool halted;
} usbs_rx_endpoint;
typedef struct usbs_tx_endpoint {
void (*start_tx_fn)(struct usbs_tx_endpoint*);
void (*set_halted_fn)(struct usbs_tx_endpoint*, cyg_bool);
void (*complete_fn)(void*, int);
void* complete_data;
const unsigned char* buffer;
int buffer_size;
cyg_bool halted;
} usbs_tx_endpoint;</PRE
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN628"
></A
><H2
>Receive and Transmit Data Structures</H2
><P
>In addition to a single <SPAN
CLASS="STRUCTNAME"
>usbs_control_endpoint</SPAN
>
data structure per USB slave device, the USB device driver should also
provide receive and transmit data structures corresponding to the
other endpoints. The names of these are determined by the device
driver. For example, the SA1110 USB device driver package provides
<TT
CLASS="LITERAL"
>usbs_sa11x0_ep1</TT
> for receives and
<TT
CLASS="LITERAL"
>usbs_sa11x0_ep2</TT
> for transmits.</P
><P
>Unlike control endpoints, the common USB slave package does provide a
number of utility routines to manipulate data endpoints. For example
<A
HREF="usbs-start-rx.html"
><TT
CLASS="FUNCTION"
>usbs_start_rx_buffer</TT
></A
>
can be used to receive data from the host into a buffer. In addition
the USB device driver can provide devtab entries such as
<TT
CLASS="LITERAL"
>/dev/usbs1r</TT
> and <TT
CLASS="LITERAL"
>/dev/usbs2w</TT
>, so
higher-level code can <TT
CLASS="FUNCTION"
>open</TT
> these devices and then
perform blocking <TT
CLASS="FUNCTION"
>read</TT
> and
<TT
CLASS="FUNCTION"
>write</TT
> operations.</P
><P
>However, the operation of data endpoints and the various
endpoint-related functions is relatively straightforward. First
consider a <SPAN
CLASS="STRUCTNAME"
>usbs_rx_endpoint</SPAN
> structure. The
device driver will provide the members
<TT
CLASS="STRUCTFIELD"
><I
>start_rx_fn</I
></TT
> and
<TT
CLASS="STRUCTFIELD"
><I
>set_halted_fn</I
></TT
>, and it will maintain the
<TT
CLASS="STRUCTFIELD"
><I
>halted</I
></TT
> field. To receive data, higher-level
code sets the <TT
CLASS="STRUCTFIELD"
><I
>buffer</I
></TT
>,
<TT
CLASS="STRUCTFIELD"
><I
>buffer_size</I
></TT
>,
<TT
CLASS="STRUCTFIELD"
><I
>complete_fn</I
></TT
> and optionally the
<TT
CLASS="STRUCTFIELD"
><I
>complete_data</I
></TT
> fields. Next the
<TT
CLASS="STRUCTFIELD"
><I
>start_rx_fn</I
></TT
> member should be called. When
the transfer has finished the device driver will invoke the completion
function, using <TT
CLASS="STRUCTFIELD"
><I
>complete_data</I
></TT
> as the first
argument and a size field for the second argument. A negative size
indicates an error of some sort: <TT
CLASS="LITERAL"
>-EGAIN</TT
> indicates
that the endpoint has been halted, usually at the request of the host;
<TT
CLASS="LITERAL"
>-EPIPE</TT
> indicates that the connection between the
host and the peripheral has been broken. Certain device drivers may
generate other error codes.</P
><P
>If higher-level code needs to halt or unhalt an endpoint then it can
invoke the <TT
CLASS="STRUCTFIELD"
><I
>set_halted_fn</I
></TT
> member. When an
endpoint is halted, invoking <TT
CLASS="STRUCTFIELD"
><I
>start_rx_fn</I
></TT
>
wit <TT
CLASS="STRUCTFIELD"
><I
>buffer_size</I
></TT
> set to 0 indicates that
higher-level code wants to block until the endpoint is no longer
halted; at that point the completion function will be invoked.</P
><P
>USB device drivers are allowed to assume that higher-level protocols
ensure that host and peripheral agree on the amount of data that will
be transferred, or at least on an upper bound. Therefore there is no
need for the device driver to maintain its own buffers, and copy
operations are avoided. If the host sends more data than expected then
the resulting behaviour is undefined.</P
><P
>Transmit endpoints work in essentially the same way as receive
endpoints. Higher-level code should set the
<TT
CLASS="STRUCTFIELD"
><I
>buffer</I
></TT
> and
<TT
CLASS="STRUCTFIELD"
><I
>buffer_size</I
></TT
> fields to point at the data to
be transferred, then call <TT
CLASS="STRUCTFIELD"
><I
>start_tx_fn</I
></TT
>, and
the device driver will invoked the completion function when the
transfer has completed.</P
><P
>USB device drivers are not expected to perform any locking. If at any
time there are two concurrent receive operations for a given endpoint,
or two concurrent transmit operations, then the resulting behaviour is
undefined. It is the responsibility of higher-level code to perform
any synchronisation that may be necessary. In practice, conflicts are
unlikely because typically a given endpoint will only be accessed
sequentially by just one part of the overall system.</P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="usbs-control.html"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="io-usb-slave.html"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="usbs-writing.html"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Control Endpoints</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
> </TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Writing a USB Device Driver</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
|
