OpenCores
URL https://opencores.org/ocsvn/openrisc_2011-10-31/openrisc_2011-10-31/trunk

Subversion Repositories openrisc_2011-10-31

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [usbs-devtab.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
>Devtab Entries</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="Starting up a USB Device"
26
HREF="usbs-start.html"><LINK
27
REL="NEXT"
28
TITLE="Receiving Data from the Host"
29
HREF="usbs-start-rx.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.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-start-rx.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-DEVTAB">Devtab Entries</H1
83
><DIV
84
CLASS="REFNAMEDIV"
85
><A
86
NAME="AEN16237"
87
></A
88
><H2
89
>Name</H2
90
>Devtab Entries&nbsp;--&nbsp;Data endpoint data structure</DIV
91
><DIV
92
CLASS="REFSYNOPSISDIV"
93
><A
94
NAME="AEN16240"><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
>/dev/usb0c
105
/dev/usb1r
106
/dev/usb2w</PRE
107
></TD
108
></TR
109
></TABLE
110
></DIV
111
><DIV
112
CLASS="REFSECT1"
113
><A
114
NAME="AEN16242"
115
></A
116
><H2
117
>Devtab Entries</H2
118
><P
119
>USB device drivers provide two ways of transferring data between host
120
and peripheral. The first involves USB-specific functionality such as
121
<A
122
HREF="usbs-start-rx.html"
123
><TT
124
CLASS="FUNCTION"
125
>usbs_start_rx_buffer</TT
126
></A
127
>.
128
This provides non-blocking I/O: a transfer is started, and some time
129
later the device driver will call a supplied completion function. The
130
second uses the conventional I/O model: there are entries in the
131
device table corresponding to the various endpoints. Standard calls
132
such as <TT
133
CLASS="FUNCTION"
134
>open</TT
135
> can then be used to get a suitable
136
handle. Actual I/O happens via blocking <TT
137
CLASS="FUNCTION"
138
>read</TT
139
> and
140
<TT
141
CLASS="FUNCTION"
142
>write</TT
143
> calls. In practice the blocking operations
144
are simply implemented using the underlying non-blocking
145
functionality.</P
146
><P
147
>Each endpoint will have its own devtab entry. The exact names are
148
controlled by the device driver package, but typically the root will
149
be <TT
150
CLASS="LITERAL"
151
>/dev/usb</TT
152
>. This is followed by one or more
153
decimal digits giving the endpoint number, followed by
154
<TT
155
CLASS="LITERAL"
156
>c</TT
157
> for a control endpoint, <TT
158
CLASS="LITERAL"
159
>r</TT
160
> for
161
a receive endpoint (host to peripheral), and <TT
162
CLASS="LITERAL"
163
>w</TT
164
> for
165
a transmit endpoint (peripheral to host). If the target hardware
166
involves more than one USB device then different roots should be used,
167
for example <TT
168
CLASS="LITERAL"
169
>/dev/usb0c</TT
170
> and
171
<TT
172
CLASS="LITERAL"
173
>/dev/usb1_0c</TT
174
>. This may require explicit
175
manipulation of device driver configuration options by the application
176
developer.</P
177
><P
178
>At present the devtab entry for a control endpoint does not support
179
any I/O operations. </P
180
><DIV
181
CLASS="REFSECT2"
182
><A
183
NAME="AEN16258"
184
></A
185
><H3
186
><TT
187
CLASS="FUNCTION"
188
>write</TT
189
> operations</H3
190
><P
191
><TT
192
CLASS="FUNCTION"
193
>cyg_io_write</TT
194
> and similar functions in
195
higher-level packages can be used to perform a transfer from
196
peripheral to host. Successive write operations will not be coalesced.
197
For example, when doing a 1000 byte write to an endpoint that uses the
198
bulk transfer protocol this will involve 15 full-size 64-byte packets
199
and a terminating 40-byte packet. USB device drivers are not expected
200
to do any locking, and if higher-level code performs multiple
201
concurrent write operations on a single endpoint then the resulting
202
behaviour is undefined.</P
203
><P
204
>A USB <TT
205
CLASS="FUNCTION"
206
>write</TT
207
> operation will never transfer less
208
data than specified. It is the responsibility of higher-level code to
209
ensure that the amount of data being transferred is acceptable to the
210
host-side code. Usually this will be defined by a higher-level
211
protocol. If an attempt is made to transfer more data than the host
212
expects then the resulting behaviour is undefined.</P
213
><P
214
>There are two likely error conditions. <TT
215
CLASS="LITERAL"
216
>EPIPE</TT
217
>
218
indicates that the connection between host and target has been broken.
219
<TT
220
CLASS="LITERAL"
221
>EAGAIN</TT
222
> indicates that the endpoint has been
223
stalled, either at the request of the host or by other activity
224
inside the peripheral.</P
225
></DIV
226
><DIV
227
CLASS="REFSECT2"
228
><A
229
NAME="AEN16268"
230
></A
231
><H3
232
><TT
233
CLASS="FUNCTION"
234
>read</TT
235
> operations</H3
236
><P
237
><TT
238
CLASS="FUNCTION"
239
>cyg_io_read</TT
240
> and similar functions in higher-level
241
packages can be used to perform a transfer from host to peripheral.
242
This should be a complete transfer: higher-level protocols should
243
define an upper bound on the amount of data being transferred, and the
244
<TT
245
CLASS="FUNCTION"
246
>read</TT
247
> operation should involve at least this
248
amount of data. The return value will indicate the actual transfer
249
size, which may be less than requested.</P
250
><P
251
>Some device drivers may support partial reads, but USB device drivers
252
are not expected to perform any buffering because that involves both
253
memory and code overheads. One technique that may work for bulk
254
transfers is to exploit the fact that such transfers happen in 64-byte
255
packets. It is possible to <TT
256
CLASS="FUNCTION"
257
>read</TT
258
> an initial 64
259
bytes, corresponding to the first packet in the transfer. These 64
260
bytes can then be examined to determine the total transfer size, and
261
the remaining data can be transferred in another
262
<TT
263
CLASS="FUNCTION"
264
>read</TT
265
> operation. This technique is not guaranteed
266
to work with all USB hardware. Also, if the delay between accepting
267
the first packet and the remainder of the transfer is excessive then
268
this could cause timeout problems for the host-side software. For
269
these reasons the use of partial reads should be avoided.</P
270
><P
271
>There are two likely error conditions. <TT
272
CLASS="LITERAL"
273
>EPIPE</TT
274
>
275
indicates that the connection between host and target has been broken.
276
<TT
277
CLASS="LITERAL"
278
>EAGAIN</TT
279
> indicates that the endpoint has been
280
stalled, either at the request of the host or by other activity
281
inside the peripheral.</P
282
><P
283
>USB device drivers are not expected to do any locking. If higher-level
284
code performs multiple concurrent read operations on a single endpoint
285
then the resulting behaviour is undefined.</P
286
></DIV
287
><DIV
288
CLASS="REFSECT2"
289
><A
290
NAME="AEN16281"
291
></A
292
><H3
293
><TT
294
CLASS="FUNCTION"
295
>select</TT
296
> operations</H3
297
><P
298
>Typical USB device drivers will not provide any support for
299
<TT
300
CLASS="FUNCTION"
301
>select</TT
302
>. Consider bulk transfers from the host to
303
the peripheral. At the USB device driver level there is no way of
304
knowing in advance how large a transfer will be, so it is not feasible
305
for the device driver to buffer the entire transfer. It may be
306
possible to buffer part of the transfer, for example the first 64-byte
307
packet, and copy this into application space at the start of a
308
<TT
309
CLASS="FUNCTION"
310
>read</TT
311
>, but this adds code and memory overheads.
312
Worse, it means that there is an unknown but potentially long delay
313
between a peripheral accepting the first packet of a transfer and the
314
remaining packets, which could confuse or upset the host-side
315
software.</P
316
><P
317
>With some USB hardware it may be possible for the device driver to
318
detect OUT tokens from the host without actually accepting the data,
319
and this would indicate that a  <TT
320
CLASS="FUNCTION"
321
>read</TT
322
> is likely to
323
succeed. However, it would not be reliable since the host-side I/O
324
operation could time out. A similar mechanism could be used to
325
implement <TT
326
CLASS="FUNCTION"
327
>select</TT
328
> for outgoing data, but again
329
this would not be reliable.</P
330
><P
331
>Some device drivers may provide partial support for
332
<TT
333
CLASS="FUNCTION"
334
>select</TT
335
> anyway, possibly under the control of a
336
configuration option. The device driver's documentation should be
337
consulted for further information. It is also worth noting that the
338
USB-specific non-blocking API can often be used as an alternative to
339
<TT
340
CLASS="FUNCTION"
341
>select</TT
342
>.</P
343
></DIV
344
><DIV
345
CLASS="REFSECT2"
346
><A
347
NAME="AEN16293"
348
></A
349
><H3
350
><TT
351
CLASS="FUNCTION"
352
>get_config</TT
353
> and
354
<TT
355
CLASS="FUNCTION"
356
>set_config</TT
357
> operations</H3
358
><P
359
>There are no <TT
360
CLASS="FUNCTION"
361
>set_config</TT
362
> or
363
<TT
364
CLASS="FUNCTION"
365
>get_config</TT
366
> (also known as
367
<TT
368
CLASS="FUNCTION"
369
>ioctl</TT
370
>) operations defined for USB devices.
371
Some device drivers may provide hardware-specific facilities this way. </P
372
><DIV
373
CLASS="NOTE"
374
><BLOCKQUOTE
375
CLASS="NOTE"
376
><P
377
><B
378
>Note: </B
379
>Currently the USB-specific functions related to <A
380
HREF="usbs-halt.html"
381
>halted endpoints</A
382
> cannot be accessed readily
383
via devtab entries. This functionality should probably be made
384
available via <TT
385
CLASS="FUNCTION"
386
>set_config</TT
387
> and
388
<TT
389
CLASS="FUNCTION"
390
>get_config</TT
391
>. It may also prove useful to provide
392
a <TT
393
CLASS="FUNCTION"
394
>get_config</TT
395
> operation that maps from the
396
devtab entries to the underlying endpoint data structures.</P
397
></BLOCKQUOTE
398
></DIV
399
></DIV
400
><DIV
401
CLASS="REFSECT2"
402
><A
403
NAME="AEN16307"
404
></A
405
><H3
406
>Presence</H3
407
><P
408
>The devtab entries are optional. If the USB device is accessed
409
primarily by class-specific code such as the USB-ethernet package and
410
that package uses the USB-specific API directly, the devtab entries
411
are redundant. Even if application code does need to access the USB
412
device, the non-blocking API may be more convenient than the blocking
413
I/O provided via the devtab entries. In these cases the devtab entries
414
serve no useful purpose, but they still impose a memory overhead. It
415
is possible to suppress the presence of these entries by disabling the
416
configuration option
417
<TT
418
CLASS="LITERAL"
419
>CYGGLO_IO_USB_SLAVE_PROVIDE_DEVTAB_ENTRIES</TT
420
>.</P
421
></DIV
422
></DIV
423
><DIV
424
CLASS="NAVFOOTER"
425
><HR
426
ALIGN="LEFT"
427
WIDTH="100%"><TABLE
428
SUMMARY="Footer navigation table"
429
WIDTH="100%"
430
BORDER="0"
431
CELLPADDING="0"
432
CELLSPACING="0"
433
><TR
434
><TD
435
WIDTH="33%"
436
ALIGN="left"
437
VALIGN="top"
438
><A
439
HREF="usbs-start.html"
440
ACCESSKEY="P"
441
>Prev</A
442
></TD
443
><TD
444
WIDTH="34%"
445
ALIGN="center"
446
VALIGN="top"
447
><A
448
HREF="ecos-ref.html"
449
ACCESSKEY="H"
450
>Home</A
451
></TD
452
><TD
453
WIDTH="33%"
454
ALIGN="right"
455
VALIGN="top"
456
><A
457
HREF="usbs-start-rx.html"
458
ACCESSKEY="N"
459
>Next</A
460
></TD
461
></TR
462
><TR
463
><TD
464
WIDTH="33%"
465
ALIGN="left"
466
VALIGN="top"
467
>Starting up a USB Device</TD
468
><TD
469
WIDTH="34%"
470
ALIGN="center"
471
VALIGN="top"
472
><A
473
HREF="io-usb-slave.html"
474
ACCESSKEY="U"
475
>Up</A
476
></TD
477
><TD
478
WIDTH="33%"
479
ALIGN="right"
480
VALIGN="top"
481
>Receiving Data from the Host</TD
482
></TR
483
></TABLE
484
></DIV
485
></BODY
486
></HTML
487
>

powered by: WebSVN 2.1.0

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