1STRUCT USB_GADGET_DR(9)     Kernel Mode Gadget API     STRUCT USB_GADGET_DR(9)
2
3
4

NAME

6       struct_usb_gadget_driver - driver for usb ´slave´ devices
7

SYNOPSIS

9       struct usb_gadget_driver {
10         char * function;
11         enum usb_device_speed speed;
12         int (* bind) (struct usb_gadget *);
13         void (* unbind) (struct usb_gadget *);
14         int (* setup) (struct usb_gadget *,const struct usb_ctrlrequest *);
15         void (* disconnect) (struct usb_gadget *);
16         void (* suspend) (struct usb_gadget *);
17         void (* resume) (struct usb_gadget *);
18         struct device_driver driver;
19       };
20

MEMBERS

22       function
23           String describing the gadget´s function
24
25       speed
26           Highest speed the driver handles.
27
28       bind
29           Invoked when the driver is bound to a gadget, usually after
30           registering the driver. At that point, ep0 is fully initialized,
31           and ep_list holds the currently-available endpoints. Called in a
32           context that permits sleeping.
33
34       unbind
35           Invoked when the driver is unbound from a gadget, usually from
36           rmmod (after a disconnect is reported). Called in a context that
37           permits sleeping.
38
39       setup
40           Invoked for ep0 control requests that aren´t handled by the
41           hardware level driver. Most calls must be handled by the gadget
42           driver, including descriptor and configuration management. The 16
43           bit members of the setup data are in USB byte order. Called
44           in_interrupt; this may not sleep. Driver queues a response to ep0,
45           or returns negative to stall.
46
47       disconnect
48           Invoked after all transfers have been stopped, when the host is
49           disconnected. May be called in_interrupt; this may not sleep. Some
50           devices can´t detect disconnect, so this might not be called except
51           as part of controller shutdown.
52
53       suspend
54           Invoked on USB suspend. May be called in_interrupt.
55
56       resume
57           Invoked on USB resume. May be called in_interrupt.
58
59       driver
60           Driver model state for this driver.
61

DESCRIPTION

63       Devices are disabled till a gadget driver successfully binds, which
64       means the driver will handle setup requests needed to enumerate (and
65       meet “chapter 9” requirements) then do some useful work.
66
67       If gadget->is_otg is true, the gadget driver must provide an OTG
68       descriptor during enumeration, or else fail the bind call. In such
69       cases, no USB traffic may flow until both bind returns without having
70       called usb_gadget_disconnect, and the USB host stack has initialized.
71
72       Drivers use hardware-specific knowledge to configure the usb hardware.
73       endpoint addressing is only one of several hardware characteristics
74       that are in descriptors the ep0 implementation returns from setup
75       calls.
76
77       Except for ep0 implementation, most driver code shouldn´t need change
78       to run on top of different usb controllers. It´ll use endpoints set up
79       by that ep0 implementation.
80
81       The usb controller driver handles a few standard usb requests. Those
82       include set_address, and feature flags for devices, interfaces, and
83       endpoints (the get_status, set_feature, and clear_feature requests).
84
85       Accordingly, the driver´s setup callback must always implement all
86       get_descriptor requests, returning at least a device descriptor and a
87       configuration descriptor. Drivers must make sure the endpoint
88       descriptors match any hardware constraints. Some hardware also
89       constrains other descriptors. (The pxa250 allows only configurations 1,
90       2, or 3).
91
92       The driver´s setup callback must also implement set_configuration, and
93       should also implement set_interface, get_configuration, and
94       get_interface. Setting a configuration (or interface) is where
95       endpoints should be activated or (config 0) shut down.
96
97       (Note that only the default control endpoint is supported. Neither
98       hosts nor devices generally support control traffic except to ep0.)
99
100       Most devices will ignore USB suspend/resume operations, and so will not
101       provide those callbacks. However, some may need to change modes when
102       the host is not longer directing those activities. For example, local
103       controls (buttons, dials, etc) may need to be re-enabled since the
104       (remote) host can´t do that any longer; or an error state might be
105       cleared, to make the device behave identically whether or not power is
106       maintained.
107

AUTHOR

109       David Brownell <dbrownell@users.sourceforge.net>
110           Author.
111

113Kernel Hackers Manual 2.6.         June 2019           STRUCT USB_GADGET_DR(9)
Impressum