1cfgadm_usb(1M) System Administration Commands cfgadm_usb(1M)
2
6 cfgadm_usb - USB hardware-specific commands for cfgadm
7
9 /usr/sbin/cfgadm [-f] [-y | -n] [-v] -c function ap_id...
10 /usr/sbin/cfgadm -f [-y | -n] [-v] [-o hardware_options]
13 -x hardware_function ap_id...
14 /usr/sbin/cfgadm -v [-a] [-s listing_option]
17 [-l [ap_id | ap_type...]]
18 /usr/sbin/cfgadm -v -h [ap_id]...
21
24 The Universal Serial Bus (USB) hardware-specific library
25 /usr/lib/cfgadm/usb.so.1 provides the functionality for administering
26 USB devices via the cfgadm(1M) command. cfgadm operates on attachment
27 points. For details regarding attachment points, refer to cfgadm(1M).
28 For USB administration, the only attachment points supported are the
31 ports of hubs attached to the USB bus.
32 Attachment points are named through attachment point IDs (ap_ids). The
35 USB bus is hierarchical, so the ap_ids are as well. USB hubs have
36 ports, numbered from 1 to n. All USB ap_ids consist of a string of the
37 following form:
38 usbN/A[.B[.C[...]]]
40 where
45 N is the Nth USB host controller on the system,
46 A is port #A on the root (top) hub.
47 B is port #B of the hub plugged into port #A of the hub above it.
48 C is port #C of the hub plugged into port #B of the hub above it, and
49 so forth.
50 For example, the first port on the root hub of USB controller 0 (the
53 only controller), has a logical ap_id:
54 usb0/1
56 Similarly, the second port on the first external hub plugged into the
61 first port on the root hub of the first USB controller has a logical
62 ap_id:
63 usb0/1.2
65 For example, if the ap_id is usb0/1.4.3.4, it represents port 4 of the
70 hub plugged into port 3 of the hub plugged into port 4 of the hub
71 plugged into port 1 of the root hub of the first USB host controller on
72 the system.
73 example# cfgadm -l
75 Ap_Id Type Receptacle Occupant Condition
76 usb0/1 USB-hub connected configured ok
77 usb0/2 unknown empty unconfigured ok
78 usb0/1.1 USB-storage connected configured ok
79 usb0/1.2 unknown empty unconfigured ok
80 usb0/1.3 unknown empty unconfigured ok
81 usb0/1.4 USB-device connected configured ok
82 USB2.0 chips have one EHCI host USB2.0 host controller and a number of
87 companion USB 1.x host controllers (either OHCI or UHCI host con‐
88 trollers).
89 When a USB2.0 device has been plugged in, it shows up on the EHCI logi‐
92 cal ports which might not have a 1 to 1 mapping to external physical
93 port numbers on the system. When a USB1.x device is plugged in, the
94 EHCI host controller reroutes the device to a companion host controller
95 and the device shows up on the companion's logical port number.
96 The mapping of logical port numbers to physical port numbers can get
99 quite complicated. For example:
100 % cfgadm
102 Ap_Id Type Receptacle Occupant Condition
103 c0 scsi-bus connected configured unknown
104 usb0/1 usb-mouse connected configured ok
105 usb0/2 usb-kbd connected configured ok
106 usb0/3 unknown empty unconfigured ok
107 usb0/4 usb-hub connected configured ok
108 usb0/4.1 unknown empty unconfigured ok
109 usb0/4.2 unknown empty unconfigured ok
110 usb0/4.3 unknown empty unconfigured ok
111 usb0/4.4 usb-storage connected configured ok
112 usb1/1 unknown empty unconfigured ok
113 usb1/2 unknown empty unconfigured ok
114 usb1/3 unknown empty unconfigured ok
115 usb2/1 unknown empty unconfigured ok
116 usb2/2 usb-device connected configured ok
117 usb3/1 unknown empty unconfigured ok
118 usb3/2 unknown empty unconfigured ok
119 usb3/3 unknown empty unconfigured ok
120 usb3/4 unknown empty unconfigured ok
121 usb3/5 unknown empty unconfigured ok
122 In this example usb0 is the onboard USB 1.x host controller. usb1 and
127 usb2 are companion OHCI USB1.x host controllers and usb3 is an EHCI
128 USB2.0 host controller.
129 The following table shows the somewhat confusing routing for this
132 USB2.0 chip:
133 logical port number physical port number
135 ------------------- --------------------
136 usb1/1 internal port 1
137 usb1/2 external port 1
138 usb1/3 external port 3
139 usb2/1 internal port 2
141 usb2/2 external port 2
142 usb3/1 internal port 1
144 usb3/2 internal port 2
145 usb3/3 external port 1
146 usb3/4 external port 2
147 usb3/5 external port 3
148 Unfortunately, the exact routing can often only be determined by exper‐
153 imentation.
154 The receptacle states for attachment points at the USB port have the
157 following meanings:
158 connected
160 USB port is powered on and enabled. A USB device is plugged in to
162 the port. The device is logically connected to the USB bus.
163 disconnected
166 USB port is powered on and enabled. A USB device is plugged into
168 the port. The device has been logically disconnected from the USB
169 bus (using the cfgadm -c disconnect command).
170 empty
173 USB port is powered on, but no device is plugged in to it.
175 The occupant states for devices at USB port attachment points at the
179 USB port have the following meanings:
180 configured
182 The USB device at the USB port is configured and usable by Solaris.
184 unconfigured
187 The USB device at the USB port was explicitly off-lined using
189 cfgadm -c unconfigure, or was not successfully configured for use
190 with Solaris, for example, having no driver or a device problem.
191 The attachment point conditions are:
195 ok
197 Normal state - ready for use.
199 failing
202 Not used.
204 failed
207 Not used.
209 unusable
212 The user has physically removed a device while an application had
214 the device open (there might be outstanding I/O). Users need to
215 reinsert the same physical device and close the application prop‐
216 erly before removing the device again. The port cannot configure
217 other inserted devices until this is done.
218 If the original device cannot be reinserted into the port, see the
220 for instructions for clearing this attachment point condition.
221 unknown
224 Not used.
226 A USB device can be hotplugged or hotunplugged at any time, and the
230 system detects the event and takes the appropriate action.
231 It is not necessary to transition a receptacle to the disconnected
234 state before removing its device from the USB. However, it is not rec‐
235 ommended to hot-remove devices currently in use (such as removable
236 disks currently opened by a volume manager or some other application).
237
239 cfgadm defines several types of operations. These operations include
240 invoking configuration state changes (-c), invoking hardware-specific
241 functions (-x), and obtaining configuration administration help mes‐
242 sages (-h).
243 If any of these operations fail, the device and attachment point might
246 not be in the expected state. Use the cfgadm -l command to display the
247 device's current status.
248 All other options have the same meaning as defined in cfgadm(1M).
251 The following options are supported:
254 -c function
256 The following generic commands are defined for the USB hardware
258 specific library. The following configuration state change opera‐
259 tions are supported:
260 configure
262 If there is a USB device plugged into the port, this command
264 attempts to configure it and set everything up so that it is
265 usable by Solaris. This command does an implied connect
266 (reverse of disconnect) if necessary. This command accomplishes
267 nothing, and returns an error message, if the device at that
268 port is already configured. After successful execution of this
269 command, the device is ready for use under Solaris.
270 disconnect
273 Performs an unconfigure on the ap_id (if it is not already
275 unconfigured), and then transitions the receptacle to the dis‐
276 connected state, even though a device is still be plugged into
277 the port. Issuing a cfgadm -c configure, or physically hotplug‐
278 ging the device, brings the device back to the connected recep‐
279 tacle state, and to the configured occupant state, assuming a
280 driver can be found and there are no problems enumerating and
281 configuring the device.
282 unconfigure
285 Makes the device plugged into the port unusable by Solaris
287 (offline it). If successful, cfgadm reports this ap_id's occu‐
288 pant state as unconfigured. Issuing a configure to the ap_id
289 (if successful) brings its occupant back to the configured
290 (online) condition, as it physically hotplugging the device on
291 the port.
292 -f
296 Not supported.
298 -h ap_id
301 USB specific help can be obtained by using the help option with any
303 USB attachment point.
304 -l[v]
307 The -l option works as described in cfgadm(1M). When paired with
309 the -v option, the Information field contains the following USB-
310 specific information:
311 o Mfg: manufacturer string (iManufacturer)
313 o Product: product string (iProduct)
315 o NConfigs: total number of configurations the device sup‐
317 ports (bNumConfigurations).
318 o Config: current configuration setting in decimal (con‐
320 figuration index, not configuration value).
321 o The configuration string descriptor for the current con‐
323 figuration (iConfiguration)
324 See the Universal Serial Bus specification for a description of
325 these fields.
326 -o hardware_options
329 Hardware options are only supported for the hardware-specific com‐
331 mand, -x usb_config. See the description of that command below for
332 an explanation of the options available.
333 -s listing_options
336 Attachment points of class USB can be listed by using the select
338 sub-option. See cfgadm(1M).
339 -x hardware_function
342 The following hardware-specific functions are defined:
344 usb_config -o config=n
346 This command requires the mandatory config value to be speci‐
348 fied using the -o option.
349 Sets the USB configuration of a multi-configuration USB device
351 at ap_id to configuration index n. The device is set to this
352 configuration henceforth and this setting persists across
353 reboots, hot-removes, and unconfigure/configure of the device.
354 Valid values of n range from 0 to (Nconfigs -1). The device is
356 reset by a disconnect followed by a configure. The configure
357 causes the device to be configured to the new configuration
358 setting.
359 If any of these steps fail, the configuration file and the
361 device are restored to their previous state and an error mes‐
362 sage is issued.
363 usb_reset
366 Performs a software reset (re-enumeration) of the device. This
368 is the equivalent of removing the device and inserting it back
369 again. The port on the hub is power cycled if the hub supports
370 power cycling of individual ports.
371 If the connected device is a hub, this function has the effect
373 of resetting that hub and any devices down the tree of which it
374 is the root.
375 If any of these steps fail, the device is restored to its pre‐
377 vious state and an error message is issued.
378 State table: attachment points state versus commands:
383 Valid states:
385 empty/unconfigured → no device connected
386 disconnected/unconfigured → logically disconnected,
388 unavailable,
389 devinfo node removed,
390 device physically connected
391 connected/unconfigured → logically connected,
393 unavailable,
394 devinfo node present
395 connected/configured → connected, available
397 The table below clarifies the state transitions resulting from actions
402 or commands:
403 current state operation new state
405 ------------- --------- ---------
406 empty/
407 unconfigured:
408 device plugged in: connected/configured or
409 connected/unconfigured
410 (if enumeration failed)
411 device removed: n/a
412 cfgadm -c unconfigure: empty/unconfigured
413 cfgadm -c configure: empty/unconfigured
414 cfgadm -c disconnect: empty/unconfigured
415 (no-op and error)
416 disconnected/
418 unconfigured:
419 device plugged in: n/a
420 device removed: empty/unconfigured
421 cfgadm -c unconfigure: disconnected/unconfigured
422 cfgadm -c configure: connected/configured, or
423 connected/unconfigured
424 (if reenumeration failed)
425 cfgadm -c disconnect: disconnected/unconfigured
426 connected/unconfigured:
428 device plugged in: n/a
429 device removed: empty/unconfigured
430 cfgadm -c unconfigure: connected/unconfigured
431 cfgadm -c configure: connected/configured, or
432 connected/unconfigured
433 (if reenumeration failed)
434 cfgadm -c disconnect: disconnected/unconfigured
435 connected/configured:
437 device plugged in: n/a
438 device removed: empty/unconfigured or
439 connected/configured,
440 but with ap condition
441 'unusable' if device
442 was open when removed
443 cfgadm -c unconfigure: connected/unconfigured
444 cfgadm -c configure: connected/configured
445 cfgadm -c disconnect: disconnected/unconfigured
446
450 Example 1 Listing the Status of All USB Devices
451 The following command lists the status of all USB devices on the sys‐
454 tem:
455 # cfgadm
458 Ap_Id Type Receptacle Occupant Condition
459 usb0/1 USB-hub connected configured ok
460 usb0/2 unknown empty unconfigured ok
461 usb0/1.1 USB-storage connected configured ok
462 usb0/1.2 unknown empty unconfigured ok
463 usb0/1.3 unknown empty unconfigured ok
464 usb0/1.4 USB-device connected configured ok
465 Notice that cfgadm treats the USB-device device at ap_id usb0/1.4 as a
470 single unit, since it cannot currently control individual interfaces.
471 Example 2 Listing the Status of a Port with No Device Plugged In
474 The following command lists the status of a port with no device plugged
477 in:
478 example# cfgadm -l usb0/1.3
481 Ap_Id Type Receptacle Occupant Condition
482 usb0/1.3 unknown empty unconfigured ok
483 Example 3 Listing the Status of the Same Port with a Device Plugged In
487 The following command lists the status of the same port after physi‐
490 cally plugging in a device that configures without problems:
491 example# cfgadm -l usb0/1.3
494 Ap_Id Type Receptacle Occupant Condition
495 usb0/1.3 USB-hub connected configured ok
496 Example 4 Unconfiguring an Existing USB Device
500 The following command unconfigures the USB device attached to usb0/1.3,
503 then displays the status of the ap_id:
504 example# cfgadm -c unconfigure usb0/1.3
507 Unconfigure the device: /devices/pci@0,0/pci8086,7112@7,2/hub@2:2.3
508 This operation suspends activity on the USB device
509 Continue (yes/no)?
510 Enter:
512 y
514 example# cfgadm -l usb0/1.3
516 Ap_Id Type Receptacle Occupant Condition
517 usb0/1.3 unknown connected unconfigured ok
518 Example 5 Unconfiguring and Logically Disconnecting an Existing USB
522 Device
523 The following command unconfigures and logically disconnects a USB
526 device attached to usb0/1.3:
527 example# cfgadm -c disconnect usb0/1.3
530 Disconnect the device: /devices/pci@0,0/pci8086,7112@7,2/hub@2:2.3
531 This operation suspends activity on the USB device
532 Continue (yes/no)?
533 Enter:
535 y
537 example# cfgadm -l usb0/1.3
539 Ap_Id Type Receptacle Occupant Condition
540 usb0/1.3 unknown disconnected unconfigured ok
541 A disconnect implies that cfgadm does an unconfigure first. The recep‐
546 tacle status now shows disconnected, even though the device is still
547 physically connected. In this case, a physical hotplug or using the
548 cfgadm -c configure on the ap_id brings it back on-line.
549 Example 6 Configuring a Previously Unconfigured USB Device
552 The following command configures a USB device that was previously
555 attached to usb0/1.3:
556 example # cfgadm -yc configure usb0/1.3
559 example# cfgadm -l usb0/1.3
560 Ap_Id Type Receptacle Occupant Condition
561 usb0/1.3 unknown connected configured ok
562 Example 7 Resetting a USB Device
566 The following command resets a USB device:
569 example# cfgadm -x usb_reset usb0/1.3
572 Reset the device: /devices/pci@0,0/pci8086,7112@7,2/hub@2:2.3
573 This operation suspends activity on the USB device
574 Continue (yes/no)?
575 Enter:
577 y
579 Example 8 Displaying Detailed Information About a USB Device
583 The following command displays detailed information about a USB device.
586 This device shows the following USB-specific information in the 'Infor‐
587 mation' field:
588 o Manufacturer string: Iomega
591 o Product string: USB Zip 250
593 o Number of configurations supported: 1
595 o Configuration currently active: 0
597 o Configuration string descriptor for configuration 0: Default
599 example# cfgadm -lv usb0/1.5
601 Ap_Id Receptacle Occupant Condition Information
602 When Type Busy Phys_Id
603 usb0/1.5 connected configured ok Mfg:"Io
604 mega" Product:"USB Zip 250" NConfigs:1 Config:0 : Default
605 example# cfgadm -l -s "cols=ap_id:info" usb0/1.5
609 Ap_Id Information
610 usb0/1.5 Mfg:"Iomega" Product:"USB Zip 250"
611 NConfigs:1 Config:0 : Default
612 Example 9 Displaying Detailed Information About All USB Devices
616 The following command displays detailed information about all USB
619 devices on the system:
620 example# cfgadm -l -s "select=class(usb),cols=ap_id:info"
623 Ap_Id Information
624 usb0/1 Mfg:<undefined> Product:<undefined>
625 NConfigs:1 Config:0 <no cfg str descr>
626 usb0/2
627 usb0/1.1 Mfg:<undefined> Product:<undefined>
628 NConfigs:1 Config:0 <no cfg str descr>
629 usb0/1.2
630 usb0/1.3
631 usb0/1.4 Mfg:"Wizard" Product:"Modem/ISDN"
632 NConfigs:3 Config:1 : V.90 Analog Modem
633 usb0/1.5 Mfg:"Iomega" Product:"USB Zip 250"
634 NConfigs:1 Config:0 : Default
635 usb0/1.6 Mfg:"SOLID YEAR" Product:"SOLID YEAR
636 USB"NConfigs:1 Config:0 <no cfg str descr>
637 usb0/1.7
638 Lines containing only an ap_id are empty ports. These can be filtered
643 out. This example only lists USB ap_ids with connected devices, and
644 information about those devices.
645 example# cfgadm -l -s "select=class(usb),cols=ap_id:info" | grep Mfg
648 usb0/1 Mfg:<undefined> Product:<undefined>
649 NConfigs:1 Config:0 <no cfg str descr>
650 usb0/1.1 Mfg:<undefined> Product:<undefined>
651 NConfigs:1 Config:0 <no cfg str descr>
652 usb0/1.4 Mfg:"Wizard" Product:"Modem/ISDN"
653 NConfigs:3 Config:1 : V.90 Analog Modem
654 usb0/1.5 Mfg:"Iomega" Product:"USB Zip 250"
655 NConfigs:1 Config:0 : Default
656 usb0/1.6 Mfg:"SOLID YEAR" Product:"SOLID YEAR USB"
657 Config:0 <no cfg str descr>
658 Example 10 Listing Information About a Multi-configuration USB Device
662 The following example lists information about a multi-configuration USB
665 device.
666 Notice the NConfigs field: the configurations available for this device
670 are 0, 1, and 2 (0 to (NConfigs-1)).
671 example# cfgadm -l -s "cols=ap_id:info" usb0/1.4
674 Ap_Id Information
675 usb0/1.4 Mfg:"Wizard" Product:"Modem/ISDN"
676 NConfigs:3 Config:1 V.90 Analog Modem"
677 Example 11 Setting the Current Configuration of a Multi-configuration
681 USB Device
682 The following example sets the current configuration of a multi-config‐
685 uration USB device:
686 example# cfgadm -o config=2 -x usb_config usb0/1.4
689 Setting the device: /devices/pci@1f,2000/usb@1/device@3
690 to USB configuration 2
691 This operation suspends activity on the USB device
692 Continue (yes/no)?
693 Enter:
695 y
697 USB configuration changed successfully.
699 The device path should be checked to ensure that the right instance of
704 a device is being referred to, in the case where multiple devices of
705 the exact same type are on the same bus. This information is available
706 in the 'Information' field.
707
710 /usr/lib/cfgadm/usb.so.1
711 Hardware specific library for generic USB device administration
713
716 See attributes(5) for descriptions of the following attributes:
717 ┌─────────────────────────────┬─────────────────────────────┐
722 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
723 ├─────────────────────────────┼─────────────────────────────┤
724 │Availability │SUNWcsl │
725 └─────────────────────────────┴─────────────────────────────┘
726
728 cfgadm(1M), config_admin(3CFGADM), attributes(5), scsa2usb(7D),
729 usba(7D)
730 Universal Serial Bus 1.1 Specification (www.usb.org)
733
738 cfgadm(1M) can not unconfigure, disconnect, reset, or change the con‐
739 figuration of any USB device currently opened by any application. These
740 operations also fail on a hub if a device in its hierarchy is opened by
741 an application. See scsa2usb(7D) for unconfiguring a USB mass-storage
742 device that is currently in use.
743 Only super-users can execute any functions on an attachment point. How‐
746 ever, one need not be a super-user to list the attachment points.
747SunOS 5.11 1 Mar 2007 cfgadm_usb(1M)