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