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

Subversion Repositories openrisc

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

powered by: WebSVN 2.1.0

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