usb_get_cfg(9f)

1usb_get_cfg(9F)          Kernel Functions for Drivers          usb_get_cfg(9F)
2
3
4

NAME

6       usb_get_cfg, usb_set_cfg - Get and set current USB device configuration
7

SYNOPSIS

9       #include <sys/usb/usba.h>
10
11
12
13       int usb_get_cfg(dev_info_t *dip, uint_t cfgval, usb_flags_t flags);
14
15
16       int usb_set_cfg(dev_info_t *dip, uint_t cfg_index, usb_flags_t flags,
17            void (*callback)(usb_pipe_handle_t pipe_handle, usb_opaque_t
18            callback_arg, int  rval, usb_cb_flags_t flags), usb_opaque_t
19            callback_arg);
20
21

INTERFACE LEVEL

23       Solaris DDI specific (Solaris DDI)
24

PARAMETERS

26       For usb_get_cfg():
27
28       dip       Pointer to device's dev_info structure.
29
30
31       cfgval    Pointer to returned configuration value.
32
33
34       flags     Not used.  Always waits for completion.
35
36
37
38       For usb_set_cfg():
39
40       dip             Pointer to device's dev_info structure.
41
42
43       cfg_index       Desired    device    configuration    index.   Set   to
44                       USB_DEV_DEFAULT_CONFIG_INDEX to restore default config‐
45                       uration.
46
47
48       flags           Only USB_FLAGS_SLEEP is recognized. Wait for completion
49                       and do not call callback.
50
51
52       callback        Callback handler to notify of asynchronous completion.
53
54
55       callback_arg    Second argument passed to callback handler.
56
57

DESCRIPTION

59       The usb_get_cfg() function  retrieves  the  current  configuration.  It
60       ignores  the  flags  argument  and  always  blocks while contacting the
61       device.
62
63
64       The usb_set_cfg() function sets a new configuration. Because this  call
65       changes  the  device's  mode of operation, the device must be quiescent
66       and have all pipes, with the exception of  the  default  control  pipe,
67       closed.  The driver must have control over the entire device and cannot
68       own just a single interface on a composite  device.  Additionally,  its
69       device  node  must  not  be  a parent to other device nodes that can be
70       operated by other drivers. The driver must own the device  exclusively,
71       otherwise  drivers managing other parts of the device would be affected
72       without their knowledge or control.
73
74
75       This call updates all internal USBA framework data structures,  whereas
76       issuing   a   raw   USB_REQ_SET_CFG   device  request  does  not.   The
77       usb_set_cfg() function is the only supported programmatic way to change
78       device configuration.
79
80
81       This  call blocks if USB_FLAGS_SLEEP is set in flags.  It returns imme‐
82       diately and calls the callback on completion if USB_FLAGS_SLEEP is  not
83       set.
84

RETURN VALUES

86       For usb_get_cfg():
87
88       USB_SUCCESS         New configuration is retrieved.
89
90
91       USB_INVALID_ARGS    cfgval or dip is NULL.
92
93
94       USB_FAILURE         Configuration cannot be retrieved.
95
96
97
98       For usb_set_cfg():
99
100       USB_SUCCESS            New configuration is set.
101
102
103       USB_INVALID_ARGS       dip is NULL.
104
105                              USB_FLAGS_SLEEP is clear and callback is NULL.
106
107
108       USB_INVALID_CONTEXT    Called     from     interrupt    context    with
109                              USB_FLAGS_SLEEP specified.
110
111
112       USB_INVALID_PERM       Caller does not own entire device or device is a
113                              parent to child devices.
114
115
116       USB_BUSY               One or more pipes other than the default control
117                              pipe are open on the device.
118
119
120       USB_INVALID_PIPE       Pipe handle is NULL or invalid, or pipe is clos‐
121                              ing or closed.
122
123
124       USB_FAILURE            An illegal configuration is specified.
125
126                              One or more pipes other than the default control
127                              pipe are open on the device.
128
129

CONTEXT

131       The usb_get_cfg() function may be called from user or kernel context.
132
133
134       The usb_set_cfg() function may be called from user  or  kernel  context
135       always. It may be called from interrupt context only if USB_FLAGS_SLEEP
136       is not set in flags.
137
138
139       If the USB_CB_ASYNC_REQ_FAILED bit  is  clear  in  usb_cb_flags_t,  the
140       callback, if supplied, can block because it is executing in kernel con‐
141       text.  Otherwise  the  callback  cannot  block.  Please  see  usb_call‐
142       back_flags(9S) for more information on callbacks.
143

EXAMPLES

145          Setting the configuration to the one at index 1 (in the
146           array of usb_cfg_data_t configuration nodes as returned
147           by usb_get_dev_data()), and verifying what the configuration
148           is at that index. (See usb_get_dev_data(9F)).
149
150           uint_t cfg_index = 1;
151
152           /*
153            * Assume all pipes other than the default control pipe
154            * are closed and make sure all requests to the default
155            * control pipe have completed. /
156            */
157
158
159           if (usb_set_cfg(dip, cfg_index, USB_FLAGS_SLEEP, NULL, 0)
160                   != USB_SUCCESS) {
161                   cmn_err (CE_WARN,
162                       "%s%d: Error setting USB device to configuration #%d",
163                       ddi_driver_name(dip), ddi_get_instance(dip), cfg_index);
164           }
165
166           if (usb_get_cfg(dip, &bConfigurationValue, 0) == USB_SUCCESS) {
167                   cmn_err (CE_WARN, "%s%d: USB device active configuration is %d",
168                       ddi_driver_name(dip), ddi_get_instance(dip),
169                       bConfigurationValue);
170           } else {
171                   ...
172                   ...
173           }
174
175
176

ATTRIBUTES

178       See attributes(5) for descriptions of the following attributes:
179
180
181
182
183       ┌─────────────────────────────┬─────────────────────────────┐
184       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
185       ├─────────────────────────────┼─────────────────────────────┤
186       │Architecture                 │PCI-based systems            │
187       ├─────────────────────────────┼─────────────────────────────┤
188       │Interface stability          │Committed                    │
189       ├─────────────────────────────┼─────────────────────────────┤
190       │Availability                 │SUNWusb                      │
191       └─────────────────────────────┴─────────────────────────────┘
192