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

Subversion Repositories openrisc_me

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [packages/] [io/] [usb/] [slave/] [v2_0/] [doc/] [usbs-data.html] - Blame information for rev 219

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

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

powered by: WebSVN 2.1.0

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