usb_set_alt_if(9f)

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

NAME

6       usb_get_alt_if,  usb_set_alt_if,  usb_get_if_number,  usb_owns_device -
7       Get and set alternate interface values
8

SYNOPSIS

10       #include <sys/usb/usba.h>
11
12
13
14       int usb_get_alt_if(dev_info_t *dip, uint_t interface_number,
15            uint_t *alternate_number, usb_flags_t flags);
16
17
18       int usb_set_alt_if(dev_info_t *dip, uint_t interface_number,
19            uint_t alternate_number, usb_flags_t flags,
20            void (*callback)(usb_pipe_handle_t pipe_handle,
21            usb_opaque_t callback_arg, int rval, usb_cb_flags_t flags),
22            usb_opaque_t callback_arg);
23
24
25       int usb_get_if_number(dev_info_t *dip);
26
27
28       boolean_t usb_owns_device(dev_info_t *dip);
29
30

INTERFACE LEVEL

32       Solaris DDI specific (Solaris DDI)
33

PARAMETERS

35       For usb_get_alt_if():
36
37       dip                 Pointer to device's dev_info structure.
38
39
40       interface_number    Interface of the desired alternate.
41
42
43       alternate_number    Address  where   current   alternate   setting   is
44                           returned.
45
46
47       flags               No flags are recognized. Reserved for future expan‐
48                           sion.
49
50
51
52       For usb_set_alt_if():
53
54       dip                 Pointer to device's dev_info structure.
55
56
57       interface_number    Interface of the desired alternate.
58
59
60       alternate_number    Alternate interface number to be set.
61
62
63       flags               Only USB_FLAGS_SLEEP is recognized. Wait  for  com‐
64                           pletion and do not call callback.
65
66
67       callback            Callback  handler to notify of asynchronous comple‐
68                           tion.
69
70
71       callback_arg        Second argument passed to callback handler.
72
73
74
75       For usb_get_if_number():
76
77       dip    Pointer to device's dev_info structure.
78
79
80
81       For usb_owns_device():
82
83       dip    Pointer to device's dev_info structure.
84
85

DESCRIPTION

87       USB devices can have multiple configurations,  each  with  many  inter‐
88       faces.  Within  interfaces are alternate settings, and within alternate
89       settings are endpoints.
90
91
92       Each interface within a configuration may be represented by the  kernel
93       as  a  device  node. Only one set of device nodes (interfaces as deter‐
94       mined by the configuration) can be active at one time.
95
96
97       Alternates to an interface represent different ways the kernel  sees  a
98       device  node.  Only  one  alternate  setting within an interface can be
99       active (or selected) at one time.  The functions presented in this  man
100       page get or set interface or alternate setting information.
101
102
103       The usb_get_alt_if() function requests the device to return the current
104       alternate setting of the given interface.  This  function  ignores  the
105       flags argument and always blocks.
106
107
108       The  usb_set_alt_if() function requests the device to set the interface
109       and its alternate setting as specified. Because this call  changes  the
110       current  device's interface and sets the new interface's mode of opera‐
111       tion as seen by the system, the driver must insure that all pipes other
112       than  the  default control pipe are closed and quiescent. To avoid con‐
113       tending with another driver for a different part  of  the  device,  the
114       driver  must  be bound to: the entire device, the interface-association
115       which includes the alternative interface, or  to  the  interface  whose
116       number is interface_number.
117
118
119       If  USB_FLAGS_SLEEP is set in flags, usb_set_alt_if() blocks until com‐
120       pleted. Otherwise, usb_set_alt_if() returns immediately and  calls  the
121       callback handler when completed.
122
123
124       callback  is  the asynchronous callback handler and takes the following
125       arguments:
126
127       usb_pipe_handle_t pipe_handle
128
129           Handle of the default control pipe used to perform the request.
130
131
132       usb_opaque_t callback_arg
133
134           Callback_arg specified to usb_set_alt_if().
135
136
137       int rval
138
139           Request status.
140
141
142       usb_cb_flags_t callback_flags:
143
144           Status of the queueing operation. Can be:
145
146           USB_CB_NO_INFO - Callback was uneventful.
147
148           USB_CB_ASYNC_REQ_FAILED   -  Error queueing request.
149
150           USB_CB_NO_RESOURCES   -   Error allocating resources.
151
152
153
154       The usb_get_if_number()  function  returns  the  interface  number,  or
155       USB_COMBINED_NODE or USB_DEVICE_NODE node indicating that the driver is
156       bound to the entire device.
157
158
159       The usb_owns_device() function returns B_TRUE if the driver of the  dip
160       argument  owns the entire device, or B_FALSE if it owns just a particu‐
161       lar interface.
162

RETURN VALUES

164       For usb_get_alt_if():
165
166       USB_SUCCESS            Interface's alternate setting  was  successfully
167                              obtained.
168
169
170       USB_INVALID_ARGS       Pointer to alternate_number and/or dip are NULL.
171
172
173       USB_INVALID_CONTEXT    Called from interrupt context.
174
175
176       USB_FAILURE            The interface number is invalid.
177
178                              An access error occurred.
179
180
181
182       For usb_set_alt_if():
183
184       USB_SUCCESS            Alternate interface was successfully set.
185
186
187       USB_INVALID_ARGS       dip  is NULL. USB_FLAGS_SLEEP is clear and call‐
188                              back is NULL.
189
190
191       USB_INVALID_PERM       dip does not own the interface to be set.
192
193
194       USB_INVALID_CONTEXT    Called    from    interrupt     context     with
195                              USB_FLAGS_SLEEP specified.
196
197
198       USB_INVALID_PIPE       Pipe  handle  is  NULL,  invalid, or refers to a
199                              pipe that is closing or closed.
200
201
202       USB_FAILURE            The interface number  and/or  alternate  setting
203                              are invalid.
204
205                              Pipes were open.
206
207                              An access error occurred.
208
209
210
211       For usb_get_if_number():
212
213
214       USB_COMBINED_NODE  if  the  driver is responsible for the entire active
215       device configuration. The dip doesn't correspond to an entire  physical
216       device.
217
218
219       USB_DEVICE_NODE if the driver is responsible for the entire device. The
220       dip corresponds to an entire physical device.
221
222
223       interface number: otherwise.
224
225
226       For usb_owns_device():
227
228       B_TRUE     Driver of the dip argument owns the entire device.
229
230
231       B_FALSE    Driver of the dip argument owns only the current interface.
232
233

CONTEXT

235       The usb_get_if_number() and usb_owns_device() functions may  be  called
236       from user or kernel context.
237
238
239       The  usb_set_alt_if() function may always be called from user or kernel
240       context.  It  may  be   called   from   interrupt   context   only   if
241       USB_FLAGS_SLEEP is not set in flags. If the USB_CB_ASYNC_REQ_FAILED bit
242       is clear in  usb_cb_flags_t,  the  callback,  if  supplied,  can  block
243       because  it is executing in kernel context. Otherwise the callback can‐
244       not block. See usb_callback_flags(9S) for  more  information  on  call‐
245       backs.
246
247
248       The  usb_get_alt_if()  function  may be called from user or kernel con‐
249       text.
250

EXAMPLES

252         /* Change alternate setting of interface 0.  Wait for completion. */
253         if (usb_set_alt_if(
254             dip, 0, new_alternate_setting_num, USB_FLAGS_SLEEP, NULL, 0) !=
255             USB_SUCCESS) {
256                 cmn_err (CE_WARN,
257                     "%s%d: Error setting alternate setting on pipe",
258                     ddi_driver_name(dip), ddi_get_instance(dip));
259                 }
260         }
261
262

ATTRIBUTES

264       See attributes(5) for descriptions of the following attributes:
265
266
267
268
269       ┌─────────────────────────────┬─────────────────────────────┐
270       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
271       ├─────────────────────────────┼─────────────────────────────┤
272       │Architecture                 │PCI-based systems            │
273       ├─────────────────────────────┼─────────────────────────────┤
274       │Interface stability          │Committed                    │
275       ├─────────────────────────────┼─────────────────────────────┤
276       │Availability                 │SUNWusb                      │
277       └─────────────────────────────┴─────────────────────────────┘
278