1 |
786 |
skrzyp |
<!-- Copyright (C) 2002 Free Software Foundation, 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 -- 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 <cyg/io/usb/usbs.h>
|
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 |
|
|
…
|
204 |
|
|
const usbs_enumeration_data* enumeration_data;
|
205 |
|
|
void (*start_fn)(usbs_control_endpoint*);
|
206 |
|
|
…
|
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 |
|
|
…
|
272 |
|
|
int state;
|
273 |
|
|
void (*state_change_fn)(struct usbs_control_endpoint*, void*,
|
274 |
|
|
usbs_state_change, int);
|
275 |
|
|
void* state_change_data;
|
276 |
|
|
…
|
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 << 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 |
|
|
…
|
452 |
|
|
unsigned char control_buffer[8];
|
453 |
|
|
usbs_control_return (*standard_control_fn)(struct usbs_control_endpoint*, void*);
|
454 |
|
|
void* standard_control_data;
|
455 |
|
|
…
|
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 |
|
|
><cyg/io/usb/usb.h></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 |
|
|
…
|
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 |
|
|
…
|
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 |
|
|
…
|
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 |
|
|
…
|
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 |
|
|
…
|
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 |
|
|
> </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 |
|
|
>
|