OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [usbs-data.html] - Blame information for rev 28

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 28 unneback
<!-- 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
>Data Endpoints</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="Control Endpoints"
26
HREF="usbs-control.html"><LINK
27
REL="NEXT"
28
TITLE="Writing a USB Device Driver"
29
HREF="usbs-writing.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-control.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-writing.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-DATA">Data Endpoints</H1
83
><DIV
84
CLASS="REFNAMEDIV"
85
><A
86
NAME="AEN16660"
87
></A
88
><H2
89
>Name</H2
90
>Data Endpoints&nbsp;--&nbsp;Data endpoint data structures</DIV
91
><DIV
92
CLASS="REFSYNOPSISDIV"
93
><A
94
NAME="AEN16663"><H2
95
>Synopsis</H2
96
><TABLE
97
BORDER="5"
98
BGCOLOR="#E0E0F0"
99
WIDTH="70%"
100
><TR
101
><TD
102
><PRE
103
CLASS="SYNOPSIS"
104
>#include &lt;cyg/io/usb/usbs.h&gt;
105
 
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);
110
    void*                complete_data;
111
    unsigned char*       buffer;
112
    int                  buffer_size;
113
    cyg_bool             halted;
114
} usbs_rx_endpoint;
115
 
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);
120
    void*                complete_data;
121
    const unsigned char* buffer;
122
    int                  buffer_size;
123
    cyg_bool             halted;
124
} usbs_tx_endpoint;</PRE
125
></TD
126
></TR
127
></TABLE
128
></DIV
129
><DIV
130
CLASS="REFSECT1"
131
><A
132
NAME="AEN16665"
133
></A
134
><H2
135
>Receive and Transmit Data Structures</H2
136
><P
137
>In addition to a single <SPAN
138
CLASS="STRUCTNAME"
139
>usbs_control_endpoint</SPAN
140
>
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
145
<TT
146
CLASS="LITERAL"
147
>usbs_sa11x0_ep1</TT
148
> for receives and
149
<TT
150
CLASS="LITERAL"
151
>usbs_sa11x0_ep2</TT
152
> for transmits.</P
153
><P
154
>Unlike control endpoints, the common USB slave package does provide a
155
number of utility routines to manipulate data endpoints. For example
156
<A
157
HREF="usbs-start-rx.html"
158
><TT
159
CLASS="FUNCTION"
160
>usbs_start_rx_buffer</TT
161
></A
162
>
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
165
<TT
166
CLASS="LITERAL"
167
>/dev/usbs1r</TT
168
> and <TT
169
CLASS="LITERAL"
170
>/dev/usbs2w</TT
171
>, so
172
higher-level code can <TT
173
CLASS="FUNCTION"
174
>open</TT
175
> these devices and then
176
perform blocking <TT
177
CLASS="FUNCTION"
178
>read</TT
179
> and
180
<TT
181
CLASS="FUNCTION"
182
>write</TT
183
> operations.</P
184
><P
185
>However, the operation of data endpoints and the various
186
endpoint-related functions is relatively straightforward. First
187
consider a <SPAN
188
CLASS="STRUCTNAME"
189
>usbs_rx_endpoint</SPAN
190
> structure. The
191
device driver will provide the members
192
<TT
193
CLASS="STRUCTFIELD"
194
><I
195
>start_rx_fn</I
196
></TT
197
> and
198
<TT
199
CLASS="STRUCTFIELD"
200
><I
201
>set_halted_fn</I
202
></TT
203
>, and it will maintain the
204
<TT
205
CLASS="STRUCTFIELD"
206
><I
207
>halted</I
208
></TT
209
> field. To receive data, higher-level
210
code sets the <TT
211
CLASS="STRUCTFIELD"
212
><I
213
>buffer</I
214
></TT
215
>,
216
<TT
217
CLASS="STRUCTFIELD"
218
><I
219
>buffer_size</I
220
></TT
221
>,
222
<TT
223
CLASS="STRUCTFIELD"
224
><I
225
>complete_fn</I
226
></TT
227
> and optionally the
228
<TT
229
CLASS="STRUCTFIELD"
230
><I
231
>complete_data</I
232
></TT
233
> fields. Next the
234
<TT
235
CLASS="STRUCTFIELD"
236
><I
237
>start_rx_fn</I
238
></TT
239
> member should be called. When
240
the transfer has finished the device driver will invoke the completion
241
function, using <TT
242
CLASS="STRUCTFIELD"
243
><I
244
>complete_data</I
245
></TT
246
> as the first
247
argument and a size field for the second argument. A negative size
248
indicates an error of some sort: <TT
249
CLASS="LITERAL"
250
>-EGAIN</TT
251
> indicates
252
that the endpoint has been halted, usually at the request of the host;
253
<TT
254
CLASS="LITERAL"
255
>-EPIPE</TT
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
259
><P
260
>If higher-level code needs to halt or unhalt an endpoint then it can
261
invoke the <TT
262
CLASS="STRUCTFIELD"
263
><I
264
>set_halted_fn</I
265
></TT
266
> member. When an
267
endpoint is halted, invoking <TT
268
CLASS="STRUCTFIELD"
269
><I
270
>start_rx_fn</I
271
></TT
272
>
273
wit <TT
274
CLASS="STRUCTFIELD"
275
><I
276
>buffer_size</I
277
></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
281
><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
288
><P
289
>Transmit endpoints work in essentially the same way as receive
290
endpoints. Higher-level code should set the
291
<TT
292
CLASS="STRUCTFIELD"
293
><I
294
>buffer</I
295
></TT
296
> and
297
<TT
298
CLASS="STRUCTFIELD"
299
><I
300
>buffer_size</I
301
></TT
302
> fields to point at the data to
303
be transferred, then call <TT
304
CLASS="STRUCTFIELD"
305
><I
306
>start_tx_fn</I
307
></TT
308
>, and
309
the device driver will invoked the completion function when the
310
transfer has completed.</P
311
><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
319
></DIV
320
><DIV
321
CLASS="NAVFOOTER"
322
><HR
323
ALIGN="LEFT"
324
WIDTH="100%"><TABLE
325
SUMMARY="Footer navigation table"
326
WIDTH="100%"
327
BORDER="0"
328
CELLPADDING="0"
329
CELLSPACING="0"
330
><TR
331
><TD
332
WIDTH="33%"
333
ALIGN="left"
334
VALIGN="top"
335
><A
336
HREF="usbs-control.html"
337
ACCESSKEY="P"
338
>Prev</A
339
></TD
340
><TD
341
WIDTH="34%"
342
ALIGN="center"
343
VALIGN="top"
344
><A
345
HREF="ecos-ref.html"
346
ACCESSKEY="H"
347
>Home</A
348
></TD
349
><TD
350
WIDTH="33%"
351
ALIGN="right"
352
VALIGN="top"
353
><A
354
HREF="usbs-writing.html"
355
ACCESSKEY="N"
356
>Next</A
357
></TD
358
></TR
359
><TR
360
><TD
361
WIDTH="33%"
362
ALIGN="left"
363
VALIGN="top"
364
>Control Endpoints</TD
365
><TD
366
WIDTH="34%"
367
ALIGN="center"
368
VALIGN="top"
369
><A
370
HREF="io-usb-slave.html"
371
ACCESSKEY="U"
372
>Up</A
373
></TD
374
><TD
375
WIDTH="33%"
376
ALIGN="right"
377
VALIGN="top"
378
>Writing a USB Device Driver</TD
379
></TR
380
></TABLE
381
></DIV
382
></BODY
383
></HTML
384
>

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.