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

Subversion Repositories openrisc

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

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
>USB-ethernet Data Transfers</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 Support for Developing USB-ethernet Peripherals"
23
HREF="io-usb-slave-eth.html"><LINK
24
REL="PREVIOUS"
25
TITLE="Initializing the USB-ethernet Package"
26
HREF="usbseth-init.html"><LINK
27
REL="NEXT"
28
TITLE="USB-ethernet State Handling"
29
HREF="usbseth-control.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="usbseth-init.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="usbseth-control.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="USBSETH-DATA">USB-ethernet Data Transfers</H1
83
><DIV
84
CLASS="REFNAMEDIV"
85
><A
86
NAME="AEN17445"
87
></A
88
><H2
89
>Name</H2
90
>USB-ethernet Data Transfers&nbsp;--&nbsp;Exchanging ethernet packets with the USB host</DIV
91
><DIV
92
CLASS="REFSYNOPSISDIV"
93
><A
94
NAME="AEN17448"><H2
95
>Synopsis</H2
96
><DIV
97
CLASS="FUNCSYNOPSIS"
98
><A
99
NAME="AEN17449"><P
100
></P
101
><TABLE
102
BORDER="5"
103
BGCOLOR="#E0E0F0"
104
WIDTH="70%"
105
><TR
106
><TD
107
><PRE
108
CLASS="FUNCSYNOPSISINFO"
109
>#include &lt;cyg/io/usb/usbs_eth.h&gt;</PRE
110
></TD
111
></TR
112
></TABLE
113
><P
114
><CODE
115
><CODE
116
CLASS="FUNCDEF"
117
>void usbs_eth_start_rx</CODE
118
>(usbs_eth* usbseth, unsigned char* buffer, void (*)(usbs_eth*, void*, int) complete_fn, void* complete_data);</CODE
119
></P
120
><P
121
><CODE
122
><CODE
123
CLASS="FUNCDEF"
124
>void usbs_eth_start_tx</CODE
125
>(usbs_eth* usbseth, unsigned char* buffer, void (*)(usbs_eth*, void*, int) complete_fn, void* complete_data);</CODE
126
></P
127
><P
128
></P
129
></DIV
130
></DIV
131
><DIV
132
CLASS="REFSECT1"
133
><A
134
NAME="AEN17473"
135
></A
136
><H2
137
>Description</H2
138
><P
139
>The USB-ethernet package provides two main modes of operation. In the
140
first mode it provides a <A
141
HREF="usbseth-netdev.html"
142
>network device
143
driver</A
144
> for use by a TCP/IP stack running inside the USB
145
peripheral. All incoming ethernet packages should be passed up the
146
TCP/IP stack, and only the stack will generate outgoing packets. Apart
147
from <A
148
HREF="usbseth-init.html"
149
>initialization</A
150
> and possibly
151
certain <A
152
HREF="usbseth-control.html"
153
>control operations</A
154
>,
155
higher-level code will not interact with the USB-ethernet package
156
directly.</P
157
><P
158
>In the second mode there is no TCP/IP stack running inside the USB
159
peripheral. For example, a simple USB-ethernet converter has an
160
ethernet chip and a USB port: ethernet packets received by the
161
ethernet chip need to be forwarded to the USB host, and ethernet
162
packets sent by the USB host need to be sent out of the ethernet chip.
163
<TT
164
CLASS="FUNCTION"
165
>usbs_eth_start_rx</TT
166
> and
167
<TT
168
CLASS="FUNCTION"
169
>usbs_eth_start_tx</TT
170
> allow for this lower-level
171
access to the USB-ethernet package.</P
172
><P
173
>The two modes of operation are mutually exclusive. If the network
174
device driver mode is enabled then application code should communicate
175
at the TCP/IP level, and not by using the lower-level functions.
176
Instead, it is the network device driver that will make use of these
177
functions, and it assumes that it has exclusive access. The package
178
does not perform any locking.</P
179
><P
180
>The transmit and receive functions work in much the same way. The
181
first argument identifies the <SPAN
182
CLASS="STRUCTNAME"
183
>usbs_eth</SPAN
184
>
185
structure that should be used. For the majority of applications this
186
will be <TT
187
CLASS="LITERAL"
188
>usbs_eth0</TT
189
>. The second argument specifies
190
the location of the ethernet packet; outgoing for
191
<TT
192
CLASS="FUNCTION"
193
>usbs_eth_start_tx</TT
194
> and incoming for
195
<TT
196
CLASS="FUNCTION"
197
>usbs_eth_start_rx</TT
198
>. This buffer should correspond
199
to the <A
200
HREF="usbseth-protocol.html"
201
>protocol</A
202
>:</P
203
><P
204
></P
205
><OL
206
TYPE="1"
207
><LI
208
><P
209
>Outgoing packets can consist of up to 1516 bytes, consisting of a
210
two-byte header specific to USB-ethernet followed by a standard
211
ethernet frame (a header with 6-byte destination address, 6-byte
212
source address and a further two bytes, followed by a payload of
213
up to 1500 bytes). The two-byte USB-ethernet header consists simply of
214
the size of the ethernet frame, i.e. the size of the rest of the
215
packet not including the USB-ethernet header, with the least
216
significant byte first.</P
217
></LI
218
><LI
219
><P
220
>For incoming packets the supplied buffer should usually be at least
221
1516 bytes. There may be special circumstances in which a smaller
222
buffer might be safe; for example, if the host-side device driver is
223
modified to support only smaller packets. Once the packet has been
224
received the buffer will contain a two-byte header specific to
225
USB-ethernet, followed by a normal ethernet frame. The header
226
gives the size of the ethernet frame, excluding the header, with the
227
least significant byte first.</P
228
></LI
229
></OL
230
><P
231
>Both <TT
232
CLASS="FUNCTION"
233
>usbs_eth_start_tx</TT
234
> and
235
<TT
236
CLASS="FUNCTION"
237
>usbs_eth_start_rx</TT
238
> are asynchronous: the transfer
239
is started and, some time later, a completion function will be invoked.
240
The third and fourth arguments to both
241
<TT
242
CLASS="FUNCTION"
243
>usbs_eth_start_tx</TT
244
> and
245
<TT
246
CLASS="FUNCTION"
247
>usbs_eth_start_rx</TT
248
> supply the completion function
249
and an argument to that function respectively. The completion function
250
will be invoked with three arguments: a pointer to the
251
<SPAN
252
CLASS="STRUCTNAME"
253
>usbs_eth</SPAN
254
> data structure, usually
255
<TT
256
CLASS="LITERAL"
257
>usbs_eth0</TT
258
>; the supplied completion data ; and a
259
return code field. A negative value indicates that an error occurred,
260
for example <TT
261
CLASS="LITERAL"
262
>-EPIPE</TT
263
> if the connection between USB
264
host and peripheral has been broken, or <TT
265
CLASS="LITERAL"
266
>-EAGAIN</TT
267
> if
268
an endpoint has been halted. A positive value indicates the total size
269
of the transfer, which should correspond to the size in the
270
USB-ethernet header plus an additional two bytes for the header
271
itself.</P
272
><P
273
>If the data transfer is succesful then the completion function will
274
typically be invoked in DSR context rather than in thread context,
275
although this depends on the implementation of the underlying USB
276
device driver. Therefore the completion function is restricted in what
277
it can do; in particular, it must not make any calls that will or may
278
block such as locking a mutex or allocating memory. The kernel
279
documentation should be consulted for more details of DSR's and
280
interrupt handling generally. Note that if the transfer finishes
281
quickly then the completion function may be invoked before
282
<TT
283
CLASS="FUNCTION"
284
>usbs_eth_start_rx</TT
285
> or
286
<TT
287
CLASS="FUNCTION"
288
>usbs_eth_start_tx</TT
289
> returns. This is especially
290
likely to happen if the current thread is descheduled after starting
291
the data transfer but before returning from these functions.</P
292
><P
293
>For transmit operations, it is possible for
294
<TT
295
CLASS="FUNCTION"
296
>usbs_eth_start_tx</TT
297
> to invoke the completion
298
function immediately. If there is no current connection between host
299
and target then the transmit will fail immediately with
300
<TT
301
CLASS="LITERAL"
302
>-EPIPE</TT
303
>. In addition the USB-ethernet package will
304
check the destination MAC address and make sure that the ethernet
305
frame really is intended for the host: either it must be for the
306
address specified in the initialization call <A
307
HREF="usbseth-init.html"
308
><TT
309
CLASS="FUNCTION"
310
>usbs_eth_init</TT
311
></A
312
>, or
313
it must be a broadcast packet, or the host must have enabled
314
promiscuous mode. </P
315
></DIV
316
><DIV
317
CLASS="NAVFOOTER"
318
><HR
319
ALIGN="LEFT"
320
WIDTH="100%"><TABLE
321
SUMMARY="Footer navigation table"
322
WIDTH="100%"
323
BORDER="0"
324
CELLPADDING="0"
325
CELLSPACING="0"
326
><TR
327
><TD
328
WIDTH="33%"
329
ALIGN="left"
330
VALIGN="top"
331
><A
332
HREF="usbseth-init.html"
333
ACCESSKEY="P"
334
>Prev</A
335
></TD
336
><TD
337
WIDTH="34%"
338
ALIGN="center"
339
VALIGN="top"
340
><A
341
HREF="ecos-ref.html"
342
ACCESSKEY="H"
343
>Home</A
344
></TD
345
><TD
346
WIDTH="33%"
347
ALIGN="right"
348
VALIGN="top"
349
><A
350
HREF="usbseth-control.html"
351
ACCESSKEY="N"
352
>Next</A
353
></TD
354
></TR
355
><TR
356
><TD
357
WIDTH="33%"
358
ALIGN="left"
359
VALIGN="top"
360
>Initializing the USB-ethernet Package</TD
361
><TD
362
WIDTH="34%"
363
ALIGN="center"
364
VALIGN="top"
365
><A
366
HREF="io-usb-slave-eth.html"
367
ACCESSKEY="U"
368
>Up</A
369
></TD
370
><TD
371
WIDTH="33%"
372
ALIGN="right"
373
VALIGN="top"
374
>USB-ethernet State Handling</TD
375
></TR
376
></TABLE
377
></DIV
378
></BODY
379
></HTML
380
>

powered by: WebSVN 2.1.0

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