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

Subversion Repositories openrisc

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

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 
>Control 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="Halted Endpoints"
26 
HREF="usbs-halt.html"><LINK
27 
REL="NEXT"
28 
TITLE="Data Endpoints"
29 
HREF="usbs-data.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-halt.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-data.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-CONTROL"
80 
>Control Endpoints</A
81 
></H1
82 
><DIV
83 
CLASS="REFNAMEDIV"
84 
><A
85 
NAME="AEN489"
86 
></A
87 
><H2
88 
>Name</H2
89 
>Control Endpoints&nbsp;--&nbsp;Control endpoint data structure</DIV
90 
><DIV
91 
CLASS="REFSYNOPSISDIV"
92 
><A
93 
NAME="AEN492"
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_control_endpoint {
108 
    *hellip;
109 
} usbs_control_endpoint;</PRE
110 
></TD
111 
></TR
112 
></TABLE
113 
></DIV
114 
><DIV
115 
CLASS="REFSECT1"
116 
><A
117 
NAME="AEN494"
118 
></A
119 
><H2
120 
><TT
121 
CLASS="LITERAL"
122 
>usbs_control_endpoint</TT
123 
> Data Structure</H2
124 
><P
125 
>The device driver for a USB slave device should supply one
126 
<SPAN
127 
CLASS="STRUCTNAME"
128 
>usbs_control_endpoint</SPAN
129 
> data structure per USB
130 
device. This corresponds to endpoint 0 which will be used for all
131 
control message interaction between the host and that device. The data
132 
structure is also used for internal management purposes, for example
133 
to keep track of the current state. In a typical USB peripheral there
134 
will only be one such data structure in the entire system, but if
135 
there are multiple USB slave ports, allowing the peripheral to be
136 
connected to multiple hosts, then there will be a separate data
137 
structure for each one. The name or names of the data structures are
138 
determined by the device drivers. For example, the SA11x0 USB device
139 
driver package provides <TT
140 
CLASS="LITERAL"
141 
>usbs_sa11x0_ep0</TT
142 
>.</P
143 
><P
144 
>The operations on a control endpoint do not fit cleanly into a
145 
conventional open/read/write I/O model. For example, when the host
146 
sends a control message to the USB peripheral this may be one of four
147 
types: standard, class, vendor and reserved. Some or all of the
148 
standard control messages will be handled automatically by the common
149 
USB slave package or by the device driver itself. Other standard
150 
control messages and the other types of control messages may be
151 
handled by a class-specific package or by application code. Although
152 
it would be possible to have devtab entries such as
153 
<TT
154 
CLASS="LITERAL"
155 
>/dev/usbs_ep0/standard</TT
156 
> and
157 
<TT
158 
CLASS="LITERAL"
159 
>/dev/usbs_ep0/class</TT
160 
>, and then support read and
161 
write operations on these devtab entries, this would add significant
162 
overhead and code complexity. Instead, all of the fields in the
163 
control endpoint data structure are public and can be manipulated
164 
directly by higher level code if and when required. </P
165 
><P
166 
>Control endpoints involve a number of callback functions, with
167 
higher-level code installing suitable function pointers in the control
168 
endpoint data structure. For example, if the peripheral involves
169 
vendor-specific control messages then a suitable handler for these
170 
messages should be installed. Although the exact details depend on the
171 
device driver, typically these callback functions will be invoked at
172 
DSR level rather than thread level. Therefore, only certain eCos
173 
functions can be invoked; specifically, those functions that are
174 
guaranteed not to block. If a potentially blocking function such as a
175 
semaphore wait or a mutex lock operation is invoked from inside the
176 
callback then the resulting behaviour is undefined, and the system as
177 
a whole may fail. In addition, if one of the callback functions
178 
involves significant processing effort then this may adversely affect
179 
the system's real time characteristics. The eCos kernel documentation
180 
should be consulted for more details of DSR handling.</P
181 
><DIV
182 
CLASS="REFSECT2"
183 
><A
184 
NAME="AEN504"
185 
></A
186 
><H3
187 
>Initialization</H3
188 
><P
189 
>The <SPAN
190 
CLASS="STRUCTNAME"
191 
>usbs_control_endpoint</SPAN
192 
> data structure
193 
contains the following fields related to initialization.</P
194 
><TABLE
195 
BORDER="0"
196 
BGCOLOR="#E0E0E0"
197 
WIDTH="100%"
198 
><TR
199 
><TD
200 
><PRE
201 
CLASS="PROGRAMLISTING"
202 
>typedef struct usbs_control_endpoint {
203 
    &#8230;
204 
    const usbs_enumeration_data* enumeration_data;
205 
    void                         (*start_fn)(usbs_control_endpoint*);
206 
    &#8230;
207 
};</PRE
208 
></TD
209 
></TR
210 
></TABLE
211 
><P
212 
>It is the responsibility of higher-level code, usually the
213 
application, to define the USB enumeration data. This needs to be
214 
installed in the control endpoint data structure early on during
215 
system startup, before the USB device is actually started and any
216 
interaction with the host is possible. Details of the enumeration data
217 
are supplied in the section <A
218 
HREF="usbs-enum.html"
219 
>USB Enumeration
220 
Data</A
221 
>. Typically, the enumeration data is constant for a given
222 
peripheral, although it can be constructed dynamically if necessary.
223 
However, the enumeration data cannot change while the peripheral is
224 
connected to a host: the peripheral cannot easily claim to be a
225 
keyboard one second and a printer the next.</P
226 
><P
227 
>The <TT
228 
CLASS="STRUCTFIELD"
229 
><I
230 
>start_fn</I
231 
></TT
232 
> member is normally accessed
233 
via the utility <A
234 
HREF="usbs-start.html"
235 
><TT
236 
CLASS="FUNCTION"
237 
>usbs_start</TT
238 
></A
239 
> rather
240 
than directly. It is provided by the device driver and should be
241 
invoked once the system is fully initialized and interaction with the
242 
host is possible. A typical implementation would change the USB data
243 
pins from tristated to active. If the peripheral is already plugged
244 
into a host then the latter should detect this change and start
245 
interacting with the peripheral, including requesting the enumeration
246 
data.</P
247 
></DIV
248 
><DIV
249 
CLASS="REFSECT2"
250 
><A
251 
NAME="AEN515"
252 
></A
253 
><H3
254 
>State</H3
255 
><P
256 
>There are three <SPAN
257 
CLASS="STRUCTNAME"
258 
>usbs_control_endpoint</SPAN
259 
> fields
260 
related to the current state of a USB slave device, plus some state
261 
constants and an enumeration of the possible state changes:</P
262 
><TABLE
263 
BORDER="0"
264 
BGCOLOR="#E0E0E0"
265 
WIDTH="100%"
266 
><TR
267 
><TD
268 
><PRE
269 
CLASS="PROGRAMLISTING"
270 
>typedef struct usbs_control_endpoint {
271 
    &#8230;
272 
    int     state;
273 
    void    (*state_change_fn)(struct usbs_control_endpoint*, void*,
274 
                               usbs_state_change, int);
275 
    void*   state_change_data;
276 
    &#8230;
277 
};
278 
 
279 
#define USBS_STATE_DETACHED             0x01
280 
#define USBS_STATE_ATTACHED             0x02
281 
#define USBS_STATE_POWERED              0x03
282 
#define USBS_STATE_DEFAULT              0x04
283 
#define USBS_STATE_ADDRESSED            0x05
284 
#define USBS_STATE_CONFIGURED           0x06
285 
#define USBS_STATE_MASK                 0x7F
286 
#define USBS_STATE_SUSPENDED            (1 &lt;&lt; 7)
287 
 
288 
typedef enum {
289 
    USBS_STATE_CHANGE_DETACHED          = 1,
290 
    USBS_STATE_CHANGE_ATTACHED          = 2,
291 
    USBS_STATE_CHANGE_POWERED           = 3,
292 
    USBS_STATE_CHANGE_RESET             = 4,
293 
    USBS_STATE_CHANGE_ADDRESSED         = 5,
294 
    USBS_STATE_CHANGE_CONFIGURED        = 6,
295 
    USBS_STATE_CHANGE_DECONFIGURED      = 7,
296 
    USBS_STATE_CHANGE_SUSPENDED         = 8,
297 
    USBS_STATE_CHANGE_RESUMED           = 9
298 
} usbs_state_change;</PRE
299 
></TD
300 
></TR
301 
></TABLE
302 
><P
303 
>The USB standard defines a number of states for a given USB
304 
peripheral. The initial state is <I
305 
CLASS="EMPHASIS"
306 
>detached</I
307 
>, where
308 
the peripheral is either not connected to a host at all or, from the
309 
host's perspective, the peripheral has not started up yet because the
310 
relevant pins are tristated. The peripheral then moves via
311 
intermediate <I
312 
CLASS="EMPHASIS"
313 
>attached</I
314 
> and
315 
<I
316 
CLASS="EMPHASIS"
317 
>powered</I
318 
> states to its default or
319 
<I
320 
CLASS="EMPHASIS"
321 
>reset</I
322 
> state, at which point the host and
323 
peripheral can actually start exchanging data. The first message is
324 
from host to peripheral and provides a unique 7-bit address within the
325 
local USB network, resulting in a state change to
326 
<I
327 
CLASS="EMPHASIS"
328 
>addressed</I
329 
>. The host then requests enumeration
330 
data and performs other initialization. If everything succeeds the
331 
host sends a standard set-configuration control message, after which
332 
the peripheral is <I
333 
CLASS="EMPHASIS"
334 
>configured</I
335 
> and expected to be
336 
up and running. Note that some USB device drivers may be unable to
337 
distinguish between the <I
338 
CLASS="EMPHASIS"
339 
>detached</I
340 
>,
341 
<I
342 
CLASS="EMPHASIS"
343 
>attached</I
344 
> and <I
345 
CLASS="EMPHASIS"
346 
>powered</I
347 
> states
348 
but generally this is not important to higher-level code.</P
349 
><P
350 
>A USB host should generate at least one token every millisecond. If a
351 
peripheral fails to detect any USB traffic for a period of time then
352 
typically this indicates that the host has entered a power-saving
353 
mode, and the peripheral should do the same if possible. This
354 
corresponds to the <I
355 
CLASS="EMPHASIS"
356 
>suspended</I
357 
> bit. The actual
358 
state is a combination of <I
359 
CLASS="EMPHASIS"
360 
>suspended</I
361 
> and the
362 
previous state, for example <I
363 
CLASS="EMPHASIS"
364 
>configured</I
365 
> and
366 
<I
367 
CLASS="EMPHASIS"
368 
>suspended</I
369 
> rather than just
370 
<I
371 
CLASS="EMPHASIS"
372 
>suspended</I
373 
>. When the peripheral subsequently
374 
detects USB traffic it would switch back to the
375 
<I
376 
CLASS="EMPHASIS"
377 
>configured</I
378 
> state.</P
379 
><P
380 
>The USB device driver and the common USB slave package will maintain
381 
the current state in the control endpoint's
382 
<TT
383 
CLASS="STRUCTFIELD"
384 
><I
385 
>state</I
386 
></TT
387 
> field. There should be no need for
388 
any other code to change this field, but it can be examined whenever
389 
appropriate. In addition whenever a state change occurs the generic
390 
code can invoke a state change callback function. By default, no such
391 
callback function will be installed. Some class-specific packages such
392 
as the USB-ethernet package will install a suitable function to keep
393 
track of whether or not the host-peripheral connection is up, that is
394 
whether or not ethernet packets can be exchanged. Application code can
395 
also update this field. If multiple parties want to be informed of
396 
state changes, for example both a class-specific package and
397 
application code, then typically the application code will install its
398 
state change handler after the class-specific package and is
399 
responsible for chaining into the package's handler.</P
400 
><P
401 
>The state change callback function is invoked with four arguments. The
402 
first identifies the control endpoint. The second is an arbitrary
403 
pointer: higher-level code can fill in the
404 
<TT
405 
CLASS="STRUCTFIELD"
406 
><I
407 
>state_change_data</I
408 
></TT
409 
> field to set this. The
410 
third argument specifies the state change that has occurred, and the
411 
last argument supplies the previous state (the new state is readily
412 
available from the control endpoint structure).</P
413 
><P
414 
>eCos does not provide any utility functions for updating or examining
415 
the <TT
416 
CLASS="STRUCTFIELD"
417 
><I
418 
>state_change_fn</I
419 
></TT
420 
> or
421 
<TT
422 
CLASS="STRUCTFIELD"
423 
><I
424 
>state_change_data</I
425 
></TT
426 
> fields. Instead, it is
427 
expected that the fields in the
428 
<SPAN
429 
CLASS="STRUCTNAME"
430 
>usbs_control_endpoint</SPAN
431 
> data structure will be
432 
manipulated directly. Any utility functions would do just this, but
433 
at the cost of increased code and cpu overheads.</P
434 
></DIV
435 
><DIV
436 
CLASS="REFSECT2"
437 
><A
438 
NAME="AEN545"
439 
></A
440 
><H3
441 
>Standard Control Messages</H3
442 
><TABLE
443 
BORDER="0"
444 
BGCOLOR="#E0E0E0"
445 
WIDTH="100%"
446 
><TR
447 
><TD
448 
><PRE
449 
CLASS="PROGRAMLISTING"
450 
>typedef struct usbs_control_endpoint {
451 
    &#8230;
452 
    unsigned char       control_buffer[8];
453 
    usbs_control_return (*standard_control_fn)(struct usbs_control_endpoint*, void*);
454 
    void*               standard_control_data;
455 
    &#8230;
456 
} usbs_control_endpoint;
457 
 
458 
typedef enum {
459 
    USBS_CONTROL_RETURN_HANDLED = 0,
460 
    USBS_CONTROL_RETURN_UNKNOWN = 1,
461 
    USBS_CONTROL_RETURN_STALL   = 2
462 
} usbs_control_return;
463 
 
464 
extern usbs_control_return usbs_handle_standard_control(struct usbs_control_endpoint*);</PRE
465 
></TD
466 
></TR
467 
></TABLE
468 
><P
469 
>When a USB peripheral is connected to the host it must always respond
470 
to control messages sent to endpoint 0. Control messages always
471 
consist of an initial eight-byte header, containing fields such as a
472 
request type. This may be followed by a further data transfer, either
473 
from host to peripheral or from peripheral to host. The way this is
474 
handled is described in the <A
475 
HREF="usbs-control.html#AEN578"
476 
>Buffer Management</A
477 
> section below.</P
478 
><P
479 
>The USB device driver will always accept the initial eight-byte
480 
header, storing it in the <TT
481 
CLASS="STRUCTFIELD"
482 
><I
483 
>control_buffer</I
484 
></TT
485 
>
486 
field. Then it determines the request type: standard, class, vendor,
487 
or reserved. The way in which the last three of these are processed is
488 
described in the section <A
489 
HREF="usbs-control.html#AEN570"
490 
>Other
491 
Control Messages</A
492 
>. Some
493 
standard control messages will be handled by the device driver itself;
494 
typically the <I
495 
CLASS="EMPHASIS"
496 
>set-address</I
497 
> request and the
498 
<I
499 
CLASS="EMPHASIS"
500 
>get-status</I
501 
>, <I
502 
CLASS="EMPHASIS"
503 
>set-feature</I
504 
> and
505 
<I
506 
CLASS="EMPHASIS"
507 
>clear-feature</I
508 
> requests when applied to endpoints.</P
509 
><P
510 
>If a standard control message cannot be handled by the device driver
511 
itself, the driver checks the
512 
<TT
513 
CLASS="STRUCTFIELD"
514 
><I
515 
>standard_control_fn</I
516 
></TT
517 
> field in the control
518 
endpoint data structure. If higher-level code has installed a suitable
519 
callback function then this will be invoked with two argument, the
520 
control endpoint data structure itself and the
521 
<TT
522 
CLASS="STRUCTFIELD"
523 
><I
524 
>standard_control_data</I
525 
></TT
526 
> field. The latter
527 
allows the higher level code to associate arbitrary data with the
528 
control endpoint. The callback function can return one of three
529 
values: <I
530 
CLASS="EMPHASIS"
531 
>HANDLED</I
532 
> to indicate that the request has
533 
been processed; <I
534 
CLASS="EMPHASIS"
535 
>UNKNOWN</I
536 
> if the message should be
537 
handled by the default code; or <I
538 
CLASS="EMPHASIS"
539 
>STALL</I
540 
> to indicate
541 
an error condition. If higher level code has not installed a callback
542 
function or if the callback function has returned
543 
<I
544 
CLASS="EMPHASIS"
545 
>UNKNOWN</I
546 
> then the device driver will invoke a
547 
default handler, <TT
548 
CLASS="FUNCTION"
549 
>usbs_handle_standard_control</TT
550 
>
551 
provided by the common USB slave package.</P
552 
><P
553 
>The default handler can cope with all of the standard control messages
554 
for a simple USB peripheral. However, if the peripheral involves
555 
multiple configurations, multiple interfaces in a configuration, or
556 
alternate settings for an interface, then this cannot be handled by
557 
generic code. For example, a multimedia peripheral may support various
558 
alternate settings for a given data source with different bandwidth
559 
requirements, and the host can select a setting that takes into
560 
account the current load. Clearly higher-level code needs to be aware
561 
when the host changes the current setting, so that it can adjust the
562 
rate at which data is fed to or retrieved from the host. Therefore the
563 
higher-level code needs to install its own standard control callback
564 
and process appropriate messages, rather than leaving these to the
565 
default handler.</P
566 
><P
567 
>The default handler will take care of the
568 
<I
569 
CLASS="EMPHASIS"
570 
>get-descriptor</I
571 
> request used to obtain the
572 
enumeration data. It has support for string descriptors but ignores
573 
language encoding issues. If language encoding is important for the
574 
peripheral then this will have to be handled by an
575 
application-specific standard control handler.</P
576 
><P
577 
>The header file <TT
578 
CLASS="FILENAME"
579 
>&lt;cyg/io/usb/usb.h&gt;</TT
580 
> defines various
581 
constants related to control messages, for example the function codes
582 
corresponding to the standard request types. This header file is
583 
provided by the common USB package, not by the USB slave package,
584 
since the information is also relevant to USB hosts.</P
585 
></DIV
586 
><DIV
587 
CLASS="REFSECT2"
588 
><A
589 
NAME="AEN570"
590 
></A
591 
><H3
592 
>Other Control Messages</H3
593 
><TABLE
594 
BORDER="0"
595 
BGCOLOR="#E0E0E0"
596 
WIDTH="100%"
597 
><TR
598 
><TD
599 
><PRE
600 
CLASS="PROGRAMLISTING"
601 
>typedef struct usbs_control_endpoint {
602 
    &#8230;
603 
    usbs_control_return (*class_control_fn)(struct usbs_control_endpoint*, void*);
604 
    void*               class_control_data;
605 
    usbs_control_return (*vendor_control_fn)(struct usbs_control_endpoint*, void*);
606 
    void*               vendor_control_data;
607 
    usbs_control_return (*reserved_control_fn)(struct usbs_control_endpoint*, void*);
608 
    void*               reserved_control_data;
609 
    &#8230;
610 
} usbs_control_endpoint;</PRE
611 
></TD
612 
></TR
613 
></TABLE
614 
><P
615 
>Non-standard control messages always have to be processed by
616 
higher-level code. This could be class-specific packages. For example,
617 
the USB-ethernet package will handle requests for getting the MAC
618 
address and for enabling or disabling promiscuous mode. In all cases
619 
the device driver will store the initial request in the
620 
<TT
621 
CLASS="STRUCTFIELD"
622 
><I
623 
>control_buffer</I
624 
></TT
625 
> field, check for an
626 
appropriate handler, and invoke it with details of the control
627 
endpoint and any handler-specific data that has been installed
628 
alongside the handler itself. The handler should return either
629 
<TT
630 
CLASS="LITERAL"
631 
>USBS_CONTROL_RETURN_HANDLED</TT
632 
> to report success or
633 
<TT
634 
CLASS="LITERAL"
635 
>USBS_CONTROL_RETURN_STALL</TT
636 
> to report failure. The
637 
device driver will report this to the host.</P
638 
><P
639 
>If there are multiple parties interested in a particular type of
640 
control messages, it is the responsibility of application code to
641 
install an appropriate handler and process the requests appropriately. </P
642 
></DIV
643 
><DIV
644 
CLASS="REFSECT2"
645 
><A
646 
NAME="AEN578"
647 
></A
648 
><H3
649 
>Buffer Management</H3
650 
><TABLE
651 
BORDER="0"
652 
BGCOLOR="#E0E0E0"
653 
WIDTH="100%"
654 
><TR
655 
><TD
656 
><PRE
657 
CLASS="PROGRAMLISTING"
658 
>typedef struct usbs_control_endpoint {
659 
    &#8230;
660 
    unsigned char*      buffer;
661 
    int                 buffer_size;
662 
    void                (*fill_buffer_fn)(struct usbs_control_endpoint*);
663 
    void*               fill_data;
664 
    int                 fill_index;
665 
    usbs_control_return (*complete_fn)(struct usbs_control_endpoint*, int);
666 
    &#8230;
667 
} usbs_control_endpoint;</PRE
668 
></TD
669 
></TR
670 
></TABLE
671 
><P
672 
>Many USB control messages involve transferring more data than just the
673 
initial eight-byte header. The header indicates the direction of the
674 
transfer, OUT for host to peripheral or IN for peripheral to host.
675 
It also specifies a length field, which is exact for an OUT transfer
676 
or an upper bound for an IN transfer. Control message handlers can
677 
manipulate six fields within the control endpoint data structure to
678 
ensure that the transfer happens correctly.</P
679 
><P
680 
>For an OUT transfer, the handler should examine the length field in
681 
the header and provide a single buffer for all the data. A
682 
class-specific protocol would typically impose an upper bound on the
683 
amount of data, allowing the buffer to be allocated statically.
684 
The handler should update the <TT
685 
CLASS="STRUCTFIELD"
686 
><I
687 
>buffer</I
688 
></TT
689 
> and
690 
<TT
691 
CLASS="STRUCTFIELD"
692 
><I
693 
>complete_fn</I
694 
></TT
695 
> fields. When all the data has
696 
been transferred the completion callback will be invoked, and its
697 
return value determines the response sent back to the host. The USB
698 
standard allows for a new control message to be sent before the
699 
current transfer has completed, effectively cancelling the current
700 
operation. When this happens the completion function will also be
701 
invoked. The second argument to the completion function specifies what
702 
has happened, with a value of 0 indicating success and an error code
703 
such as <TT
704 
CLASS="LITERAL"
705 
>-EPIPE</TT
706 
> or <TT
707 
CLASS="LITERAL"
708 
>-EIO</TT
709 
>
710 
indicating that the current transfer has been cancelled.</P
711 
><P
712 
>IN transfers are a little bit more complicated. The required
713 
information, for example the enumeration data, may not be in a single
714 
contiguous buffer. Instead a mechanism is provided by which the buffer
715 
can be refilled, thus allowing the transfer to move from one record to
716 
the next. Essentially, the transfer operates as follows:</P
717 
><P
718 
></P
719 
><OL
720 
TYPE="1"
721 
><LI
722 
><P
723 
>When the host requests another chunk of data (typically eight bytes),
724 
the USB device driver will examine the
725 
<TT
726 
CLASS="STRUCTFIELD"
727 
><I
728 
>buffer_size</I
729 
></TT
730 
> field. If non-zero then
731 
<TT
732 
CLASS="STRUCTFIELD"
733 
><I
734 
>buffer</I
735 
></TT
736 
> contains at least one more byte of
737 
data, and then <TT
738 
CLASS="STRUCTFIELD"
739 
><I
740 
>buffer_size</I
741 
></TT
742 
> is decremented.</P
743 
></LI
744 
><LI
745 
><P
746 
>When <TT
747 
CLASS="STRUCTFIELD"
748 
><I
749 
>buffer_size</I
750 
></TT
751 
> has dropped to 0, the
752 
<TT
753 
CLASS="STRUCTFIELD"
754 
><I
755 
>fill_buffer_fn</I
756 
></TT
757 
> field will be examined. If
758 
non-null it will be invoked to refill the buffer.</P
759 
></LI
760 
><LI
761 
><P
762 
>The <TT
763 
CLASS="STRUCTFIELD"
764 
><I
765 
>fill_data</I
766 
></TT
767 
> and
768 
<TT
769 
CLASS="STRUCTFIELD"
770 
><I
771 
>fill_index</I
772 
></TT
773 
> fields are not used by the
774 
device driver. Instead these fields are available to the refill
775 
function to keep track of the current state of the transfer.</P
776 
></LI
777 
><LI
778 
><P
779 
>When <TT
780 
CLASS="STRUCTFIELD"
781 
><I
782 
>buffer_size</I
783 
></TT
784 
> is 0 and
785 
<TT
786 
CLASS="STRUCTFIELD"
787 
><I
788 
>fill_buffer_fn</I
789 
></TT
790 
> is NULL, no more data is
791 
available and the transfer has completed.</P
792 
></LI
793 
><LI
794 
><P
795 
>Optionally a completion function can be installed. This will be
796 
invoked with 0 if the transfer completes successfully, or with an
797 
error code if the transfer is cancelled because of another control
798 
messsage. </P
799 
></LI
800 
></OL
801 
><P
802 
>If the requested data is contiguous then the only fields that need
803 
to be manipulated are <TT
804 
CLASS="STRUCTFIELD"
805 
><I
806 
>buffer</I
807 
></TT
808 
> and
809 
<TT
810 
CLASS="STRUCTFIELD"
811 
><I
812 
>buffer_size</I
813 
></TT
814 
>, and optionally
815 
<TT
816 
CLASS="STRUCTFIELD"
817 
><I
818 
>complete_fn</I
819 
></TT
820 
>. If the requested data is not
821 
contiguous then the initial control message handler should update
822 
<TT
823 
CLASS="STRUCTFIELD"
824 
><I
825 
>fill_buffer_fn</I
826 
></TT
827 
> and some or all of the other
828 
fields, as required. An example of this is the handling of the
829 
standard <I
830 
CLASS="EMPHASIS"
831 
>get-descriptor</I
832 
> control message by
833 
<TT
834 
CLASS="FUNCTION"
835 
>usbs_handle_standard_control</TT
836 
>.</P
837 
></DIV
838 
><DIV
839 
CLASS="REFSECT2"
840 
><A
841 
NAME="AEN615"
842 
></A
843 
><H3
844 
>Polling Support</H3
845 
><TABLE
846 
BORDER="0"
847 
BGCOLOR="#E0E0E0"
848 
WIDTH="100%"
849 
><TR
850 
><TD
851 
><PRE
852 
CLASS="PROGRAMLISTING"
853 
>typedef struct usbs_control_endpoint {
854 
    void                (*poll_fn)(struct usbs_control_endpoint*);
855 
    int                 interrupt_vector;
856 
    &#8230;
857 
} usbs_control_endpoint;</PRE
858 
></TD
859 
></TR
860 
></TABLE
861 
><P
862 
>In nearly all circumstances USB I/O should be interrupt-driven.
863 
However, there are special environments such as RedBoot where polled
864 
operation may be appropriate. If the device driver can operate in
865 
polled mode then it will provide a suitable function via the
866 
<TT
867 
CLASS="STRUCTFIELD"
868 
><I
869 
>poll_fn</I
870 
></TT
871 
> field, and higher-level code can
872 
invoke this regularly. This polling function will take care of all
873 
endpoints associated with the device, not just the control endpoint.
874 
If the USB hardware involves a single interrupt vector then this will
875 
be identified in the data structure as well.</P
876 
></DIV
877 
></DIV
878 
><DIV
879 
CLASS="NAVFOOTER"
880 
><HR
881 
ALIGN="LEFT"
882 
WIDTH="100%"><TABLE
883 
WIDTH="100%"
884 
BORDER="0"
885 
CELLPADDING="0"
886 
CELLSPACING="0"
887 
><TR
888 
><TD
889 
WIDTH="33%"
890 
ALIGN="left"
891 
VALIGN="top"
892 
><A
893 
HREF="usbs-halt.html"
894 
>Prev</A
895 
></TD
896 
><TD
897 
WIDTH="34%"
898 
ALIGN="center"
899 
VALIGN="top"
900 
><A
901 
HREF="io-usb-slave.html"
902 
>Home</A
903 
></TD
904 
><TD
905 
WIDTH="33%"
906 
ALIGN="right"
907 
VALIGN="top"
908 
><A
909 
HREF="usbs-data.html"
910 
>Next</A
911 
></TD
912 
></TR
913 
><TR
914 
><TD
915 
WIDTH="33%"
916 
ALIGN="left"
917 
VALIGN="top"
918 
>Halted Endpoints</TD
919 
><TD
920 
WIDTH="34%"
921 
ALIGN="center"
922 
VALIGN="top"
923 
>&nbsp;</TD
924 
><TD
925 
WIDTH="33%"
926 
ALIGN="right"
927 
VALIGN="top"
928 
>Data Endpoints</TD
929 
></TR
930 
></TABLE
931 
></DIV
932 
></BODY
933 
></HTML
934 
>

powered by: WebSVN 2.1.0

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