1 <!-- 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. -->
12 >Control Endpoints</TITLE
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
22 TITLE="eCos USB Slave Support"
23 HREF="io-usb-slave.html"><LINK
25 TITLE="Halted Endpoints"
26 HREF="usbs-halt.html"><LINK
28 TITLE="Data Endpoints"
29 HREF="usbs-data.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
82 NAME="USBS-CONTROL">Control Endpoints</H1
90 >Control Endpoints -- Control endpoint data structure</DIV
92 CLASS="REFSYNOPSISDIV"
104 >#include <cyg/io/usb/usbs.h>
106 typedef struct usbs_control_endpoint {
108 } usbs_control_endpoint;</PRE
121 >usbs_control_endpoint</TT
124 >The device driver for a USB slave device should supply one
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
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
154 >/dev/usbs_ep0/standard</TT
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
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
190 >usbs_control_endpoint</SPAN
192 contains the following fields related to initialization.</P
200 CLASS="PROGRAMLISTING"
201 >typedef struct usbs_control_endpoint {
203 const usbs_enumeration_data* enumeration_data;
204 void (*start_fn)(usbs_control_endpoint*);
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"
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
231 > member is normally accessed
233 HREF="usbs-start.html"
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
255 >There are three <SPAN
257 >usbs_control_endpoint</SPAN
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
268 CLASS="PROGRAMLISTING"
269 >typedef struct usbs_control_endpoint {
272 void (*state_change_fn)(struct usbs_control_endpoint*, void*,
273 usbs_state_change, int);
274 void* state_change_data;
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 << 7)
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
302 >The USB standard defines a number of states for a given USB
303 peripheral. The initial state is <SPAN
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
326 > states to its default or
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
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
353 up and running. Note that some USB device drivers may be unable to
354 distinguish between the <SPAN
374 but generally this is not important to higher-level code.</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
387 state is a combination of <SPAN
394 previous state, for example <SPAN
414 >. When the peripheral subsequently
415 detects USB traffic it would switch back to the
424 >The USB device driver and the common USB slave package will maintain
425 the current state in the control endpoint's
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
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
451 >state_change_data</I
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
458 >eCos does not provide any utility functions for updating or examining
468 >state_change_data</I
470 > fields. Instead, it is
471 expected that the fields in the
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
485 >Standard Control Messages</H3
493 CLASS="PROGRAMLISTING"
494 >typedef struct usbs_control_endpoint {
496 unsigned char control_buffer[8];
497 usbs_control_return (*standard_control_fn)(struct usbs_control_endpoint*, void*);
498 void* standard_control_data;
500 } usbs_control_endpoint;
503 USBS_CONTROL_RETURN_HANDLED = 0,
504 USBS_CONTROL_RETURN_UNKNOWN = 1,
505 USBS_CONTROL_RETURN_STALL = 2
506 } usbs_control_return;
508 extern usbs_control_return usbs_handle_standard_control(struct usbs_control_endpoint*);</PRE
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
523 >The USB device driver will always accept the initial eight-byte
524 header, storing it in the <TT
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"
537 standard control messages will be handled by the device driver itself;
564 > requests when applied to endpoints.</P
566 >If a standard control message cannot be handled by the device driver
567 itself, the driver checks the
571 >standard_control_fn</I
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
580 >standard_control_data</I
583 allows the higher level code to associate arbitrary data with the
584 control endpoint. The callback function can return one of three
591 > to indicate that the request has
592 been processed; <SPAN
598 > if the message should be
599 handled by the default code; or <SPAN
606 an error condition. If higher level code has not installed a callback
607 function or if the callback function has returned
614 > then the device driver will invoke a
617 >usbs_handle_standard_control</TT
619 provided by the common USB slave package.</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
635 >The default handler will take care of the
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
650 ><cyg/io/usb/usb.h></TT
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
663 >Other Control Messages</H3
671 CLASS="PROGRAMLISTING"
672 >typedef struct usbs_control_endpoint {
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;
681 } usbs_control_endpoint;</PRE
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
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
702 >USBS_CONTROL_RETURN_HANDLED</TT
703 > to report success or
706 >USBS_CONTROL_RETURN_STALL</TT
707 > to report failure. The
708 device driver will report this to the host.</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
720 >Buffer Management</H3
728 CLASS="PROGRAMLISTING"
729 >typedef struct usbs_control_endpoint {
731 unsigned char* buffer;
733 void (*fill_buffer_fn)(struct usbs_control_endpoint*);
736 usbs_control_return (*complete_fn)(struct usbs_control_endpoint*, int);
738 } usbs_control_endpoint;</PRE
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
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
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
781 indicating that the current transfer has been cancelled.</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
794 >When the host requests another chunk of data (typically eight bytes),
795 the USB device driver will examine the
801 > field. If non-zero then
807 > contains at least one more byte of
822 > has dropped to 0, the
828 > field will be examined. If
829 non-null it will be invoked to refill the buffer.</P
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
861 > is NULL, no more data is
862 available and the transfer has completed.</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
873 >If the requested data is contiguous then the only fields that need
874 to be manipulated are <TT
891 >. If the requested data is not
892 contiguous then the initial control message handler should update
898 > and some or all of the other
899 fields, as required. An example of this is the handling of the
909 >usbs_handle_standard_control</TT
926 CLASS="PROGRAMLISTING"
927 >typedef struct usbs_control_endpoint {
928 void (*poll_fn)(struct usbs_control_endpoint*);
929 int interrupt_vector;
931 } usbs_control_endpoint;</PRE
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
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
957 SUMMARY="Footer navigation table"
968 HREF="usbs-halt.html"
986 HREF="usbs-data.html"
996 >Halted Endpoints</TD
1002 HREF="io-usb-slave.html"
projects / karo-tx-redboot.git / blob