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.