| blob | 5fa2432cb8e8568536d30c3d4f8c9d9a5dd4d2e2 |
1 '\" te
2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH CFGADM_USB 1M "Mar 1, 2007"
7 .SH NAME
8 cfgadm_usb \- USB hardware-specific commands for cfgadm
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB/usr/sbin/cfgadm\fR [\fB-f\fR] [\fB-y\fR | \fB-n\fR] [\fB-v\fR] \fB-c\fR \fIfunction\fR \fIap_id\fR...
13 .fi
15 .LP
16 .nf
17 \fB/usr/sbin/cfgadm\fR \fB-f\fR [\fB-y\fR | \fB-n\fR] [\fB-v\fR] [\fB-o\fR \fIhardware_options\fR]
18 \fB-x\fR \fIhardware_function\fR \fIap_id\fR...
19 .fi
21 .LP
22 .nf
23 \fB/usr/sbin/cfgadm\fR \fB-v\fR [\fB-a\fR] [\fB-s\fR \fIlisting_option\fR]
24 [\fB-l\fR [\fIap_id\fR | \fIap_type\fR...]]
25 .fi
27 .LP
28 .nf
29 \fB/usr/sbin/cfgadm\fR \fB-v\fR \fB-h\fR [\fIap_id\fR]...
30 .fi
32 .SH DESCRIPTION
33 .LP
34 The Universal Serial Bus (\fBUSB\fR) hardware-specific library
35 \fB/usr/lib/cfgadm/usb.so.1\fR provides the functionality for administering
36 \fBUSB\fR devices via the \fBcfgadm\fR(1M) command. \fBcfgadm\fR operates on
37 attachment points. For details regarding attachment points, refer to
38 \fBcfgadm\fR(1M).
39 .sp
40 .LP
41 For \fBUSB\fR administration, the only attachment points supported are the
42 ports of hubs attached to the \fBUSB\fR bus.
43 .sp
44 .LP
45 Attachment points are named through attachment point IDs (\fIap_ids\fR). The
46 \fBUSB\fR bus is hierarchical, so the \fIap_ids\fR are as well. \fBUSB\fR hubs
47 have ports, numbered from \fB1\fR to \fIn\fR. All \fBUSB\fR \fIap_ids\fR
48 consist of a string of the following form:
49 .sp
50 .in +2
51 .nf
52 usb\fIN\fR/\fIA\fR[.\fIB\fR[.\fIC\fR[...]]]
53 .fi
54 .in -2
55 .sp
57 .sp
58 .LP
59 where
60 .br
61 .in +2
62 \fIN\fR is the \fIN\fRth \fBUSB\fR host controller on the system,
63 .in -2
64 .br
65 .in +2
66 \fIA\fR is port #\fIA\fR on the root (top) hub.
67 .in -2
68 .br
69 .in +2
70 \fIB\fR is port #\fIB\fR of the hub plugged into port #\fIA\fR of the hub above
71 it.
72 .in -2
73 .br
74 .in +2
75 \fIC\fR is port #\fIC\fR of the hub plugged into port #\fIB \fRof the hub above
76 it, and so forth.
77 .in -2
78 .sp
79 .LP
80 For example, the first port on the root hub of USB controller \fB0\fR (the only
81 controller), has a logical \fIap_id\fR:
82 .sp
83 .in +2
84 .nf
85 usb0/1
86 .fi
87 .in -2
88 .sp
90 .sp
91 .LP
92 Similarly, the second port on the first external hub plugged into the first
93 port on the root hub of the first \fBUSB\fR controller has a logical
94 \fIap_id\fR:
95 .sp
96 .in +2
97 .nf
98 usb0/1.2
99 .fi
100 .in -2
101 .sp
103 .sp
104 .LP
105 For example, if the \fIap_id\fR is \fBusb0/1.4.3.4\fR, it represents port
106 \fB4\fR of the hub plugged into port \fB3\fR of the hub plugged into port
107 \fB4\fR of the hub plugged into port \fB1\fR of the root hub of the first
108 \fBUSB\fR host controller on the system.
109 .sp
110 .in +2
111 .nf
112 example# \fBcfgadm -l\fR
113 Ap_Id Type Receptacle Occupant Condition
114 usb0/1 USB-hub connected configured ok
115 usb0/2 unknown empty unconfigured ok
116 usb0/1.1 USB-storage connected configured ok
117 usb0/1.2 unknown empty unconfigured ok
118 usb0/1.3 unknown empty unconfigured ok
119 usb0/1.4 USB-device connected configured ok
120 .fi
121 .in -2
122 .sp
124 .sp
125 .LP
126 \fBUSB 2.0\fR chips have one \fBEHCI\fR host \fBUSB 2.0\fR host controller and a
127 number of companion \fBUSB 1.\fR\fIx\fR host controllers (either \fBOHCI\fR or
128 \fBUHCI\fR host controllers).
129 .sp
130 .LP
131 When a \fBUSB 2.0\fR device has been plugged in, it shows up on the \fBEHCI\fR
132 logical ports which might not have a \fB1\fR to \fB1\fR mapping to external
133 physical port numbers on the system. When a \fBUSB 1.\fR\fIx\fR device is
134 plugged in, the \fBEHCI\fR host controller reroutes the device to a companion
135 host controller and the device shows up on the companion's logical port
136 number.
137 .sp
138 .LP
139 The mapping of logical port numbers to physical port numbers can get quite
140 complicated. For example:
141 .sp
142 .in +2
143 .nf
144 % cfgadm
145 Ap_Id Type Receptacle Occupant Condition
146 c0 scsi-bus connected configured unknown
147 usb0/1 usb-mouse connected configured ok
148 usb0/2 usb-kbd connected configured ok
149 usb0/3 unknown empty unconfigured ok
150 usb0/4 usb-hub connected configured ok
151 usb0/4.1 unknown empty unconfigured ok
152 usb0/4.2 unknown empty unconfigured ok
153 usb0/4.3 unknown empty unconfigured ok
154 usb0/4.4 usb-storage connected configured ok
155 usb1/1 unknown empty unconfigured ok
156 usb1/2 unknown empty unconfigured ok
157 usb1/3 unknown empty unconfigured ok
158 usb2/1 unknown empty unconfigured ok
159 usb2/2 usb-device connected configured ok
160 usb3/1 unknown empty unconfigured ok
161 usb3/2 unknown empty unconfigured ok
162 usb3/3 unknown empty unconfigured ok
163 usb3/4 unknown empty unconfigured ok
164 usb3/5 unknown empty unconfigured ok
165 .fi
166 .in -2
167 .sp
169 .sp
170 .LP
171 In this example \fBusb0\fR is the onboard USB 1.\fIx\fR host controller.
172 \fBusb1\fR and \fBusb2\fR are companion \fBOHCI USB 1.\fR\fIx\fR host
173 controllers and \fBusb3\fR is an \fBEHCI USB 2.0\fR host controller.
174 .sp
175 .LP
176 The following table shows the somewhat confusing routing for this USB 2.0 chip:
177 .sp
178 .in +2
179 .nf
180 logical port number physical port number
181 ------------------- --------------------
182 usb1/1 internal port 1
183 usb1/2 external port 1
184 usb1/3 external port 3
186 usb2/1 internal port 2
187 usb2/2 external port 2
189 usb3/1 internal port 1
190 usb3/2 internal port 2
191 usb3/3 external port 1
192 usb3/4 external port 2
193 usb3/5 external port 3
194 .fi
195 .in -2
196 .sp
198 .sp
199 .LP
200 Unfortunately, the exact routing can often only be determined by
201 experimentation.
202 .sp
203 .LP
204 The receptacle states for attachment points at the \fBUSB\fR port have the
205 following meanings:
206 .sp
207 .ne 2
208 .na
209 \fB\fBconnected\fR\fR
210 .ad
211 .sp .6
212 .RS 4n
213 \fBUSB\fR port is powered on and enabled. A USB device is plugged in to the
214 port. The device is logically connected to the USB bus.
215 .RE
217 .sp
218 .ne 2
219 .na
220 \fB\fBdisconnected\fR\fR
221 .ad
222 .sp .6
223 .RS 4n
224 \fBUSB\fR port is powered on and enabled. A \fBUSB\fR device is plugged into
225 the port. The device has been logically disconnected from the \fBUSB\fR bus
226 (using the \fBcfgadm\fR \fB-c\fR \fBdisconnect\fR command).
227 .RE
229 .sp
230 .ne 2
231 .na
232 \fB\fBempty\fR\fR
233 .ad
234 .sp .6
235 .RS 4n
236 \fBUSB\fR port is powered on, but no device is plugged in to it.
237 .RE
239 .sp
240 .LP
241 The occupant states for devices at \fBUSB\fR port attachment points at the
242 \fBUSB\fR port have the following meanings:
243 .sp
244 .ne 2
245 .na
246 \fB\fBconfigured\fR\fR
247 .ad
248 .sp .6
249 .RS 4n
250 The \fBUSB\fR device at the \fBUSB\fR port is configured and usable by Solaris.
251 .RE
253 .sp
254 .ne 2
255 .na
256 \fB\fBunconfigured\fR\fR
257 .ad
258 .sp .6
259 .RS 4n
260 The \fBUSB\fR device at the \fBUSB\fR port was explicitly off-lined using
261 \fBcfgadm\fR \fB-c\fR \fBunconfigure\fR, or was not successfully configured for
262 use with Solaris, for example, having no driver or a device problem.
263 .RE
265 .sp
266 .LP
267 The attachment point conditions are:
268 .sp
269 .ne 2
270 .na
271 \fB\fBok\fR\fB\fR\fR
272 .ad
273 .sp .6
274 .RS 4n
275 Normal state - ready for use.
276 .RE
278 .sp
279 .ne 2
280 .na
281 \fB\fBfailing\fR\fR
282 .ad
283 .sp .6
284 .RS 4n
285 Not used.
286 .RE
288 .sp
289 .ne 2
290 .na
291 \fB\fBfailed\fR\fR
292 .ad
293 .sp .6
294 .RS 4n
295 Not used.
296 .RE
298 .sp
299 .ne 2
300 .na
301 \fB\fBunusable\fR\fR
302 .ad
303 .sp .6
304 .RS 4n
305 The user has physically removed a device while an application had the device
306 open (there might be outstanding \fBI/O\fR). Users need to reinsert the same
307 physical device and close the application properly before removing the device
308 again. The port cannot configure other inserted devices until this is done.
309 .sp
310 If the original device cannot be reinserted into the port, see the \fI\fR for
311 instructions for clearing this attachment point condition.
312 .RE
314 .sp
315 .ne 2
316 .na
317 \fB\fBunknown\fR\fR
318 .ad
319 .sp .6
320 .RS 4n
321 Not used.
322 .RE
324 .sp
325 .LP
326 A \fBUSB\fR device can be hotplugged or hotunplugged at any time, and the
327 system detects the event and takes the appropriate action.
328 .sp
329 .LP
330 It is not necessary to transition a receptacle to the \fBdisconnected\fR state
331 before removing its device from the \fBUSB\fR. However, it is not recommended
332 to hot-remove devices currently in use (such as removable disks currently
333 opened by a volume manager or some other application).
334 .SH OPTIONS
335 .LP
336 \fBcfgadm\fR defines several types of operations. These operations include
337 invoking configuration state changes (\fB-c\fR), invoking hardware-specific
338 functions (\fB-x\fR), and obtaining configuration administration help messages
339 (\fB-h\fR).
340 .sp
341 .LP
342 If any of these operations fail, the device and attachment point might not be
343 in the expected state. Use the \fBcfgadm\fR \fB-l\fR command to display the
344 device's current status.
345 .sp
346 .LP
347 All other options have the same meaning as defined in \fBcfgadm\fR(1M).
348 .sp
349 .LP
350 The following options are supported:
351 .sp
352 .ne 2
353 .na
354 \fB\fB-c\fR \fIfunction\fR\fR
355 .ad
356 .sp .6
357 .RS 4n
358 The following generic commands are defined for the \fBUSB\fR hardware specific
359 library. The following configuration state change operations are supported:
360 .sp
361 .ne 2
362 .na
363 \fB\fBconfigure\fR\fR
364 .ad
365 .sp .6
366 .RS 4n
367 If there is a \fBUSB\fR device plugged into the port, this command attempts to
368 configure it and set everything up so that it is usable by Solaris. This
369 command does an implied \fBconnect\fR (reverse of \fBdisconnect\fR) if
370 necessary. This command accomplishes nothing, and returns an error message, if
371 the device at that port is already configured. After successful execution of
372 this command, the device is ready for use under Solaris.
373 .RE
375 .sp
376 .ne 2
377 .na
378 \fB\fBdisconnect\fR\fR
379 .ad
380 .sp .6
381 .RS 4n
382 Performs an \fBunconfigure\fR on the \fIap_id\fR (if it is not already
383 \fBunconfigured\fR), and then transitions the receptacle to the
384 \fBdisconnected\fR state, even though a device is still be plugged into the
385 port. Issuing a \fBcfgadm\fR \fB-c\fR \fBconfigure\fR, or physically
386 hotplugging the device, brings the device back to the \fBconnected\fR
387 receptacle state, and to the \fBconfigured\fR occupant state, assuming a driver
388 can be found and there are no problems enumerating and configuring the device.
389 .RE
391 .sp
392 .ne 2
393 .na
394 \fB\fBunconfigure\fR\fR
395 .ad
396 .sp .6
397 .RS 4n
398 Makes the device plugged into the port unusable by Solaris (offline it). If
399 successful, \fBcfgadm\fR reports this \fIap_id\fR's occupant state as
400 \fBunconfigured\fR. Issuing a \fBconfigure\fR to the \fIap_id\fR (if
401 successful) brings its occupant back to the \fBconfigured\fR (online)
402 condition, as it physically hotplugging the device on the port.
403 .RE
405 .RE
407 .sp
408 .ne 2
409 .na
410 \fB\fB-f\fR\fR
411 .ad
412 .sp .6
413 .RS 4n
414 Not supported.
415 .RE
417 .sp
418 .ne 2
419 .na
420 \fB\fB-h\fR \fIap_id\fR\fR
421 .ad
422 .sp .6
423 .RS 4n
424 \fBUSB\fR specific help can be obtained by using the help option with any
425 \fBUSB\fR attachment point.
426 .RE
428 .sp
429 .ne 2
430 .na
431 \fB\fB-l\fR[\fBv\fR]\fR
432 .ad
433 .sp .6
434 .RS 4n
435 The \fB-l\fR option works as described in \fBcfgadm\fR(1M). When paired with
436 the \fB-v\fR option, the \fBInformation\fR field contains the following
437 \fBUSB\fR-specific information:
438 .RS +4
439 .TP
440 .ie t \(bu
441 .el o
442 \fBMfg\fR: manufacturer string (\fBiManufacturer\fR)
443 .RE
444 .RS +4
445 .TP
446 .ie t \(bu
447 .el o
448 \fBProduct\fR: product string (\fBiProduct\fR)
449 .RE
450 .RS +4
451 .TP
452 .ie t \(bu
453 .el o
454 \fBNConfigs\fR: total number of configurations the device supports
455 (\fBbNumConfigurations\fR).
456 .RE
457 .RS +4
458 .TP
459 .ie t \(bu
460 .el o
461 \fBConfig\fR: current configuration setting in decimal (configuration index,
462 not configuration value).
463 .RE
464 .RS +4
465 .TP
466 .ie t \(bu
467 .el o
468 The configuration string descriptor for the current configuration
469 (\fBiConfiguration\fR)
470 .RE
471 See the Universal Serial Bus specification for a description of these fields.
472 .RE
474 .sp
475 .ne 2
476 .na
477 \fB\fB-o\fR \fIhardware_options\fR\fR
478 .ad
479 .sp .6
480 .RS 4n
481 Hardware options are only supported for the hardware-specific command, \fB-x\fR
482 \fBusb_config\fR. See the description of that command below for an explanation
483 of the options available.
484 .RE
486 .sp
487 .ne 2
488 .na
489 \fB\fB-s\fR \fIlisting_options\fR\fR
490 .ad
491 .sp .6
492 .RS 4n
493 Attachment points of class \fBUSB\fR can be listed by using the \fBselect\fR
494 sub-option. See \fBcfgadm\fR(1M).
495 .RE
497 .sp
498 .ne 2
499 .na
500 \fB\fB-x\fR \fIhardware_function\fR\fR
501 .ad
502 .sp .6
503 .RS 4n
504 The following hardware-specific functions are defined:
505 .sp
506 .ne 2
507 .na
508 \fB\fBusb_config\fR \fB-o\fR \fBconfig=\fR\fIn\fR\fR
509 .ad
510 .sp .6
511 .RS 4n
512 This command requires the mandatory \fBconfig\fR value to be specified using
513 the \fB-o\fR option.
514 .sp
515 Sets the \fBUSB\fR configuration of a multi-configuration \fBUSB\fR device at
516 \fIap_id\fR to configuration index \fIn\fR. The device is set to this
517 configuration henceforth and this setting persists across reboots, hot-removes,
518 and unconfigure/configure of the device.
519 .sp
520 Valid values of \fIn\fR range from \fB0\fR to (\fBNconfigs -1\fR). The device
521 is reset by a \fBdisconnect\fR followed by a \fBconfigure\fR. The
522 \fBconfigure\fR causes the device to be configured to the new configuration
523 setting.
524 .sp
525 If any of these steps fail, the configuration file and the device are restored
526 to their previous state and an error message is issued.
527 .RE
529 .sp
530 .ne 2
531 .na
532 \fB\fBusb_reset\fR\fR
533 .ad
534 .sp .6
535 .RS 4n
536 Performs a software reset (re-enumeration) of the device. This is the
537 equivalent of removing the device and inserting it back again. The port on the
538 hub is power cycled if the hub supports power cycling of individual ports.
539 .sp
540 If the connected device is a hub, this function has the effect of resetting
541 that hub and any devices down the tree of which it is the root.
542 .sp
543 If any of these steps fail, the device is restored to its previous state and an
544 error message is issued.
545 .RE
547 .RE
549 .sp
550 .LP
551 State table: attachment points state versus commands:
552 .sp
553 .in +2
554 .nf
555 Valid states:
556 empty/unconfigured \(-> no device connected
558 disconnected/unconfigured \(-> logically disconnected,
559 unavailable,
560 devinfo node removed,
561 device physically connected
563 connected/unconfigured \(-> logically connected,
564 unavailable,
565 devinfo node present
567 connected/configured \(-> connected, available
568 .fi
569 .in -2
570 .sp
572 .sp
573 .LP
574 The table below clarifies the state transitions resulting from actions or
575 commands:
576 .sp
577 .in +2
578 .nf
579 current state operation new state
580 ------------- --------- ---------
581 empty/
582 unconfigured:
583 device plugged in: connected/configured or
584 connected/unconfigured
585 (if enumeration failed)
586 device removed: n/a
587 cfgadm -c unconfigure: empty/unconfigured
588 cfgadm -c configure: empty/unconfigured
589 cfgadm -c disconnect: empty/unconfigured
590 (no-op and error)
592 disconnected/
593 unconfigured:
594 device plugged in: n/a
595 device removed: empty/unconfigured
596 cfgadm -c unconfigure: disconnected/unconfigured
597 cfgadm -c configure: connected/configured, or
598 connected/unconfigured
599 (if reenumeration failed)
600 cfgadm -c disconnect: disconnected/unconfigured
602 connected/unconfigured:
603 device plugged in: n/a
604 device removed: empty/unconfigured
605 cfgadm -c unconfigure: connected/unconfigured
606 cfgadm -c configure: connected/configured, or
607 connected/unconfigured
608 (if reenumeration failed)
609 cfgadm -c disconnect: disconnected/unconfigured
611 connected/configured:
612 device plugged in: n/a
613 device removed: empty/unconfigured or
614 connected/configured,
615 but with ap condition
616 'unusable' if device
617 was open when removed
618 cfgadm -c unconfigure: connected/unconfigured
619 cfgadm -c configure: connected/configured
620 cfgadm -c disconnect: disconnected/unconfigured
621 .fi
622 .in -2
623 .sp
625 .SH EXAMPLES
626 .LP
627 \fBExample 1 \fRListing the Status of All USB Devices
628 .sp
629 .LP
630 The following command lists the status of all \fBUSB\fR devices on the system:
632 .sp
633 .in +2
634 .nf
635 # cfgadm
636 Ap_Id Type Receptacle Occupant Condition
637 usb0/1 USB-hub connected configured ok
638 usb0/2 unknown empty unconfigured ok
639 usb0/1.1 USB-storage connected configured ok
640 usb0/1.2 unknown empty unconfigured ok
641 usb0/1.3 unknown empty unconfigured ok
642 usb0/1.4 USB-device connected configured ok
643 .fi
644 .in -2
645 .sp
647 .sp
648 .LP
649 Notice that \fBcfgadm\fR treats the \fBUSB-device\fR device at \fBap_id
650 usb0/1.4\fR as a single unit, since it cannot currently control individual
651 interfaces.
653 .LP
654 \fBExample 2 \fRListing the Status of a Port with No Device Plugged In
655 .sp
656 .LP
657 The following command lists the status of a port with no device plugged in:
659 .sp
660 .in +2
661 .nf
662 example# \fBcfgadm -l usb0/1.3\fR
663 Ap_Id Type Receptacle Occupant Condition
664 usb0/1.3 unknown empty unconfigured ok
665 .fi
666 .in -2
667 .sp
669 .LP
670 \fBExample 3 \fRListing the Status of the Same Port with a Device Plugged In
671 .sp
672 .LP
673 The following command lists the status of the same port after physically
674 plugging in a device that configures without problems:
676 .sp
677 .in +2
678 .nf
679 example# \fBcfgadm -l usb0/1.3\fR
680 Ap_Id Type Receptacle Occupant Condition
681 usb0/1.3 USB-hub connected configured ok
682 .fi
683 .in -2
684 .sp
686 .LP
687 \fBExample 4 \fRUnconfiguring an Existing USB Device
688 .sp
689 .LP
690 The following command unconfigures the \fBUSB\fR device attached to
691 \fBusb0/1.3\fR, then displays the status of the \fBap_id\fR:
693 .sp
694 .in +2
695 .nf
696 example# \fBcfgadm -c unconfigure usb0/1.3\fR
697 Unconfigure the device: /devices/pci@0,0/pci8086,7112@7,2/hub@2:2.3
698 This operation suspends activity on the USB device
699 Continue (yes/no)?
701 Enter:
703 \fBy\fR
705 example# \fBcfgadm -l usb0/1.3\fR
706 Ap_Id Type Receptacle Occupant Condition
707 usb0/1.3 unknown connected unconfigured ok
708 .fi
709 .in -2
710 .sp
712 .LP
713 \fBExample 5 \fRUnconfiguring and Logically Disconnecting an Existing USB
714 Device
715 .sp
716 .LP
717 The following command unconfigures and logically disconnects a \fBUSB\fR device
718 attached to \fBusb0/1.3\fR:
720 .sp
721 .in +2
722 .nf
723 example# \fBcfgadm -c disconnect usb0/1.3\fR
724 Disconnect the device: /devices/pci@0,0/pci8086,7112@7,2/hub@2:2.3
725 This operation suspends activity on the USB device
726 Continue (yes/no)?
728 Enter:
730 \fBy\fR
732 example# \fBcfgadm -l usb0/1.3\fR
733 Ap_Id Type Receptacle Occupant Condition
734 usb0/1.3 unknown disconnected unconfigured ok
735 .fi
736 .in -2
737 .sp
739 .sp
740 .LP
741 A \fBdisconnect\fR implies that \fBcfgadm\fR does an \fBunconfigure\fR first.
742 The receptacle status now shows \fBdisconnected\fR, even though the device is
743 still physically connected. In this case, a physical hotplug or using the
744 \fBcfgadm \fR\fB-c\fR \fBconfigure\fR on the \fBap_id\fR brings it back
745 on-line.
747 .LP
748 \fBExample 6 \fRConfiguring a Previously Unconfigured USB Device
749 .sp
750 .LP
751 The following command configures a \fBUSB\fR device that was previously
752 attached to \fBusb0/1.3\fR:
754 .sp
755 .in +2
756 .nf
757 example # \fBcfgadm -yc configure usb0/1.3\fR
758 example# \fBcfgadm -l usb0/1.3\fR
759 Ap_Id Type Receptacle Occupant Condition
760 usb0/1.3 unknown connected configured ok
761 .fi
762 .in -2
763 .sp
765 .LP
766 \fBExample 7 \fRResetting a USB Device
767 .sp
768 .LP
769 The following command resets a \fBUSB\fR device:
771 .sp
772 .in +2
773 .nf
774 example# \fBcfgadm -x usb_reset usb0/1.3\fR
775 Reset the device: /devices/pci@0,0/pci8086,7112@7,2/hub@2:2.3
776 This operation suspends activity on the USB device
777 Continue (yes/no)?
779 Enter:
781 \fBy\fR
782 .fi
783 .in -2
784 .sp
786 .LP
787 \fBExample 8 \fRDisplaying Detailed Information About a USB Device
788 .sp
789 .LP
790 The following command displays detailed information about a \fBUSB\fR device.
791 This device shows the following \fBUSB\fR-specific information in
792 the '\fBInformation\fR' field:
794 .RS +4
795 .TP
796 .ie t \(bu
797 .el o
798 Manufacturer string: Iomega
799 .RE
800 .RS +4
801 .TP
802 .ie t \(bu
803 .el o
804 Product string: \fBUSB Zip 250\fR
805 .RE
806 .RS +4
807 .TP
808 .ie t \(bu
809 .el o
810 Number of configurations supported: 1
811 .RE
812 .RS +4
813 .TP
814 .ie t \(bu
815 .el o
816 Configuration currently active: 0
817 .RE
818 .RS +4
819 .TP
820 .ie t \(bu
821 .el o
822 Configuration string descriptor for configuration 0: Default
823 .RE
824 .sp
825 .in +2
826 .nf
827 example# \fBcfgadm -lv usb0/1.5\fR
828 Ap_Id Receptacle Occupant Condition Information
829 When Type Busy Phys_Id
830 usb0/1.5 connected configured ok Mfg:"Io
831 mega" Product:"USB Zip 250" NConfigs:1 Config:0 : Default
832 .fi
833 .in -2
834 .sp
836 .sp
837 .in +2
838 .nf
839 example# \fBcfgadm -l -s "cols=ap_id:info" usb0/1.5\fR
840 Ap_Id Information
841 usb0/1.5 Mfg:"Iomega" Product:"USB Zip 250"
842 NConfigs:1 Config:0 : Default
843 .fi
844 .in -2
845 .sp
847 .LP
848 \fBExample 9 \fRDisplaying Detailed Information About All USB Devices
849 .sp
850 .LP
851 The following command displays detailed information about all \fBUSB\fR devices
852 on the system:
854 .sp
855 .in +2
856 .nf
857 example# \fBcfgadm -l -s "select=class(usb),cols=ap_id:info"\fR
858 Ap_Id Information
859 usb0/1 Mfg:<undefined> Product:<undefined>
860 NConfigs:1 Config:0 <no cfg str descr>
861 usb0/2
862 usb0/1.1 Mfg:<undefined> Product:<undefined>
863 NConfigs:1 Config:0 <no cfg str descr>
864 usb0/1.2
865 usb0/1.3
866 usb0/1.4 Mfg:"Wizard" Product:"Modem/ISDN"
867 NConfigs:3 Config:1 : V.90 Analog Modem
868 usb0/1.5 Mfg:"Iomega" Product:"USB Zip 250"
869 NConfigs:1 Config:0 : Default
870 usb0/1.6 Mfg:"SOLID YEAR" Product:"SOLID YEAR
871 USB"NConfigs:1 Config:0 <no cfg str descr>
872 usb0/1.7
873 .fi
874 .in -2
875 .sp
877 .sp
878 .LP
879 Lines containing only an \fBap_id\fR are empty ports. These can be filtered
880 out. This example only lists \fBUSB\fR \fBap_id\fRs with connected devices, and
881 information about those devices.
883 .sp
884 .in +2
885 .nf
886 example# \fBcfgadm -l -s "select=class(usb),cols=ap_id:info" | grep Mfg\fR
887 usb0/1 Mfg:<undefined> Product:<undefined>
888 NConfigs:1 Config:0 <no cfg str descr>
889 usb0/1.1 Mfg:<undefined> Product:<undefined>
890 NConfigs:1 Config:0 <no cfg str descr>
891 usb0/1.4 Mfg:"Wizard" Product:"Modem/ISDN"
892 NConfigs:3 Config:1 : V.90 Analog Modem
893 usb0/1.5 Mfg:"Iomega" Product:"USB Zip 250"
894 NConfigs:1 Config:0 : Default
895 usb0/1.6 Mfg:"SOLID YEAR" Product:"SOLID YEAR USB"
896 Config:0 <no cfg str descr>
897 .fi
898 .in -2
899 .sp
901 .LP
902 \fBExample 10 \fRListing Information About a Multi-configuration USB Device
903 .sp
904 .LP
905 The following example lists information about a multi-configuration \fBUSB\fR
906 device.
908 .sp
909 .LP
910 Notice the \fBNConfigs\fR field: the configurations available for this device
911 are \fB0\fR, \fB1\fR, and \fB2\fR (\fB0\fR to (\fIN\fR\fBConfigs-1\fR)).
913 .sp
914 .in +2
915 .nf
916 example# \fBcfgadm -l -s "cols=ap_id:info" usb0/1.4\fR
917 Ap_Id Information
918 usb0/1.4 Mfg:"Wizard" Product:"Modem/ISDN"
919 NConfigs:3 Config:1 V.90 Analog Modem"
920 .fi
921 .in -2
922 .sp
924 .LP
925 \fBExample 11 \fRSetting the Current Configuration of a Multi-configuration USB
926 Device
927 .sp
928 .LP
929 The following example sets the current configuration of a multi-configuration
930 USB device:
932 .sp
933 .in +2
934 .nf
935 example# \fBcfgadm -o config=2 -x usb_config usb0/1.4\fR
936 Setting the device: /devices/pci@1f,2000/usb@1/device@3
937 to USB configuration 2
938 This operation suspends activity on the USB device
939 Continue (yes/no)?
941 Enter:
943 \fBy\fR
945 USB configuration changed successfully.
946 .fi
947 .in -2
948 .sp
950 .sp
951 .LP
952 The device path should be checked to ensure that the right instance of a device
953 is being referred to, in the case where multiple devices of the exact same type
954 are on the same bus. This information is available in the '\fBInformation\fR'
955 field.
957 .SH FILES
958 .ne 2
959 .na
960 \fB\fB/usr/lib/cfgadm/usb.so.1\fR\fR
961 .ad
962 .sp .6
963 .RS 4n
964 Hardware specific library for generic USB device administration
965 .RE
967 .SH SEE ALSO
968 .LP
969 \fBcfgadm\fR(1M), \fBconfig_admin\fR(3CFGADM), \fBattributes\fR(5),
970 \fBscsa2usb\fR(7D), \fBusba\fR(7D)
971 .sp
972 .LP
973 Universal Serial Bus 1.1 Specification (\fBwww.usb.org\fR)
974 .sp
975 .LP
976 \fI\fR
977 .SH NOTES
978 .LP
979 \fBcfgadm\fR(1M) can not unconfigure, disconnect, reset, or change the
980 configuration of any \fBUSB\fR device currently opened by any application.
981 These operations also fail on a hub if a device in its hierarchy is opened by
982 an application. See \fBscsa2usb\fR(7D) for unconfiguring a \fBUSB\fR
983 mass-storage device that is currently in use.
984 .sp
985 .LP
986 Only super-users can execute any functions on an attachment point. However, one
987 need not be a super-user to list the attachment points.