cfgadm_usb man page on OpenIndiana

Man page or keyword search:  
man Server   20441 pages
apropos Keyword Search (all sections)
Output format
OpenIndiana logo
[printable version]

cfgadm_usb(1M)		System Administration Commands		cfgadm_usb(1M)

NAME
       cfgadm_usb - USB hardware-specific commands for cfgadm

SYNOPSIS
       /usr/sbin/cfgadm [-f] [-y | -n] [-v] -c function ap_id...

       /usr/sbin/cfgadm -f [-y | -n] [-v] [-o hardware_options]
	    -x hardware_function ap_id...

       /usr/sbin/cfgadm -v [-a] [-s listing_option]
	    [-l [ap_id | ap_type...]]

       /usr/sbin/cfgadm -v -h [ap_id]...

DESCRIPTION
       The    Universal	   Serial    Bus   (USB)   hardware-specific   library
       /usr/lib/cfgadm/usb.so.1 provides the functionality  for	 administering
       USB  devices  via the cfgadm(1M) command. cfgadm operates on attachment
       points. For details regarding attachment points, refer to cfgadm(1M).

       For USB administration, the only attachment points  supported  are  the
       ports of hubs attached to the USB bus.

       Attachment  points are named through attachment point IDs (ap_ids). The
       USB bus is hierarchical, so the ap_ids  are  as	well.  USB  hubs  have
       ports,  numbered from 1 to n. All USB ap_ids consist of a string of the
       following form:

	 usbN/A[.B[.C[...]]]

       where
	 N is the Nth USB host controller on the system,
	 A is port #A on the root (top) hub.
	 B is port #B of the hub plugged into port #A of the hub above it.
	 C is port #C of the hub plugged into port #B of the hub above it, and
	 so forth.

       For  example,  the  first port on the root hub of USB controller 0 (the
       only controller), has a logical ap_id:

	 usb0/1

       Similarly, the second port on the first external hub plugged  into  the
       first  port  on	the root hub of the first USB controller has a logical
       ap_id:

	 usb0/1.2

       For example, if the ap_id is usb0/1.4.3.4, it represents port 4 of  the
       hub  plugged  into  port	 3  of	the hub plugged into port 4 of the hub
       plugged into port 1 of the root hub of the first USB host controller on
       the system.

	 example# cfgadm -l
	 Ap_Id		      Type	   Receptacle	Occupant     Condition
	 usb0/1		      USB-hub	   connected	configured   ok
	 usb0/2		      unknown	   empty	unconfigured ok
	 usb0/1.1	      USB-storage  connected	configured   ok
	 usb0/1.2	      unknown	   empty	unconfigured ok
	 usb0/1.3	      unknown	   empty	unconfigured ok
	 usb0/1.4	      USB-device   connected	configured   ok

       USB2.0  chips have one EHCI host USB2.0 host controller and a number of
       companion USB 1.x host controllers  (either  OHCI  or  UHCI  host  con‐
       trollers).

       When a USB2.0 device has been plugged in, it shows up on the EHCI logi‐
       cal ports which might not have a 1 to 1 mapping	to  external  physical
       port  numbers  on  the  system. When a USB1.x device is plugged in, the
       EHCI host controller reroutes the device to a companion host controller
       and the device shows up on the companion's logical port number.

       The  mapping  of	 logical port numbers to physical port numbers can get
       quite complicated. For example:

	 % cfgadm
	 Ap_Id		      Type	   Receptacle	Occupant     Condition
	 c0		      scsi-bus	   connected	configured   unknown
	 usb0/1		      usb-mouse	   connected	configured   ok
	 usb0/2		      usb-kbd	   connected	configured   ok
	 usb0/3		      unknown	   empty	unconfigured ok
	 usb0/4		      usb-hub	   connected	configured   ok
	 usb0/4.1	      unknown	   empty	unconfigured ok
	 usb0/4.2	      unknown	   empty	unconfigured ok
	 usb0/4.3	      unknown	   empty	unconfigured ok
	 usb0/4.4	      usb-storage  connected	configured   ok
	 usb1/1		      unknown	   empty	unconfigured ok
	 usb1/2		      unknown	   empty	unconfigured ok
	 usb1/3		      unknown	   empty	unconfigured ok
	 usb2/1		      unknown	   empty	unconfigured ok
	 usb2/2		      usb-device   connected	configured   ok
	 usb3/1		      unknown	   empty	unconfigured ok
	 usb3/2		      unknown	   empty	unconfigured ok
	 usb3/3		      unknown	   empty	unconfigured ok
	 usb3/4		      unknown	   empty	unconfigured ok
	 usb3/5		      unknown	   empty	unconfigured ok

       In this example usb0 is the onboard USB 1.x host controller.  usb1  and
       usb2  are  companion  OHCI  USB1.x host controllers and usb3 is an EHCI
       USB2.0 host controller.

       The following table shows  the  somewhat	 confusing  routing  for  this
       USB2.0 chip:

	 logical port number	  physical port number
	 -------------------	  --------------------
	      usb1/1		  internal port 1
	      usb1/2		  external port 1
	      usb1/3		  external port 3

	      usb2/1		  internal port 2
	      usb2/2		  external port 2

	      usb3/1		  internal port 1
	      usb3/2		  internal port 2
	      usb3/3		  external port 1
	      usb3/4		  external port 2
	      usb3/5		  external port 3

       Unfortunately, the exact routing can often only be determined by exper‐
       imentation.

       The receptacle states for attachment points at the USB  port  have  the
       following meanings:

       connected

	   USB	port  is powered on and enabled. A USB device is plugged in to
	   the port. The device is logically connected to the USB bus.

       disconnected

	   USB port is powered on and enabled. A USB device  is	 plugged  into
	   the	port.  The device has been logically disconnected from the USB
	   bus (using the cfgadm -c disconnect command).

       empty

	   USB port is powered on, but no device is plugged in to it.

       The occupant states for devices at USB port attachment  points  at  the
       USB port have the following meanings:

       configured

	   The USB device at the USB port is configured and usable by Solaris.

       unconfigured

	   The	USB  device  at	 the  USB  port was explicitly off-lined using
	   cfgadm -c unconfigure, or was not successfully configured  for  use
	   with Solaris, for example, having no driver or a device problem.

       The attachment point conditions are:

       ok

	   Normal state - ready for use.

       failing

	   Not used.

       failed

	   Not used.

       unusable

	   The	user  has physically removed a device while an application had
	   the device open (there might be outstanding	I/O).  Users  need  to
	   reinsert  the  same physical device and close the application prop‐
	   erly before removing the device again. The  port  cannot  configure
	   other inserted devices until this is done.

	   If  the original device cannot be reinserted into the port, see the
	   System Administration Guide: Advanced Administration	 for  instruc‐
	   tions for clearing this attachment point condition.

       unknown

	   Not used.

       A  USB  device  can  be hotplugged or hotunplugged at any time, and the
       system detects the event and takes the appropriate action.

       It is not necessary to transition  a  receptacle	 to  the  disconnected
       state  before removing its device from the USB. However, it is not rec‐
       ommended to hot-remove devices currently	 in  use  (such	 as  removable
       disks currently opened by a volume manager or some other application).

OPTIONS
       cfgadm  defines	several	 types of operations. These operations include
       invoking configuration state changes (-c),  invoking  hardware-specific
       functions  (-x),	 and  obtaining configuration administration help mes‐
       sages (-h).

       If any of these operations fail, the device and attachment point	 might
       not  be in the expected state. Use the cfgadm -l command to display the
       device's current status.

       All other options have the same meaning as defined in cfgadm(1M).

       The following options are supported:

       -c function

	   The following generic commands are defined  for  the	 USB  hardware
	   specific  library.  The following configuration state change opera‐
	   tions are supported:

	   configure

	       If there is a USB device plugged into the  port,	 this  command
	       attempts	 to  configure	it and set everything up so that it is
	       usable  by  Solaris.  This  command  does  an  implied  connect
	       (reverse of disconnect) if necessary. This command accomplishes
	       nothing, and returns an error message, if the  device  at  that
	       port  is already configured. After successful execution of this
	       command, the device is ready for use under Solaris.

	   disconnect

	       Performs an unconfigure on the ap_id  (if  it  is  not  already
	       unconfigured),  and then transitions the receptacle to the dis‐
	       connected state, even though a device is still be plugged  into
	       the port. Issuing a cfgadm -c configure, or physically hotplug‐
	       ging the device, brings the device back to the connected recep‐
	       tacle  state,  and to the configured occupant state, assuming a
	       driver can be found and there are no problems  enumerating  and
	       configuring the device.

	   unconfigure

	       Makes  the  device  plugged  into  the port unusable by Solaris
	       (offline it). If successful, cfgadm reports this ap_id's	 occu‐
	       pant  state  as	unconfigured. Issuing a configure to the ap_id
	       (if successful) brings its  occupant  back  to  the  configured
	       (online)	 condition, as it physically hotplugging the device on
	       the port.

       -f

	   Not supported.

       -h ap_id

	   USB specific help can be obtained by using the help option with any
	   USB attachment point.

       -l[v]

	   The	-l  option  works as described in cfgadm(1M). When paired with
	   the -v option, the Information field contains  the  following  USB-
	   specific information:

	       o      Mfg: manufacturer string (iManufacturer)

	       o      Product: product string (iProduct)

	       o      NConfigs: total number of configurations the device sup‐
		      ports (bNumConfigurations).

	       o      Config: current configuration setting in	decimal	 (con‐
		      figuration index, not configuration value).

	       o      The configuration string descriptor for the current con‐
		      figuration (iConfiguration)
	   See the Universal Serial Bus specification  for  a  description  of
	   these fields.

       -o hardware_options

	   Hardware  options are only supported for the hardware-specific com‐
	   mand, -x usb_config. See the description of that command below  for
	   an explanation of the options available.

       -s listing_options

	   Attachment  points  of  class USB can be listed by using the select
	   sub-option. See cfgadm(1M).

       -x hardware_function

	   The following hardware-specific functions are defined:

	   usb_config -o config=n

	       This command requires the mandatory config value to  be	speci‐
	       fied using the -o option.

	       Sets  the USB configuration of a multi-configuration USB device
	       at ap_id to configuration index n. The device is	 set  to  this
	       configuration  henceforth  and  this  setting  persists	across
	       reboots, hot-removes, and unconfigure/configure of the device.

	       Valid values of n range from 0 to (Nconfigs -1). The device  is
	       reset  by  a  disconnect followed by a configure. The configure
	       causes the device to be configured  to  the  new	 configuration
	       setting.

	       If  any	of  these  steps  fail, the configuration file and the
	       device are restored to their previous state and an  error  mes‐
	       sage is issued.

	   usb_reset

	       Performs	 a software reset (re-enumeration) of the device. This
	       is the equivalent of removing the device and inserting it  back
	       again.  The port on the hub is power cycled if the hub supports
	       power cycling of individual ports.

	       If the connected device is a hub, this function has the	effect
	       of resetting that hub and any devices down the tree of which it
	       is the root.

	       If any of these steps fail, the device is restored to its  pre‐
	       vious state and an error message is issued.

       State table: attachment points state versus commands:

	 Valid states:
	     empty/unconfigured		→ no device connected

	     disconnected/unconfigured	→ logically disconnected,
					   unavailable,
					   devinfo node removed,
					   device physically connected

	     connected/unconfigured	→ logically connected,
					   unavailable,
					   devinfo node present

	     connected/configured	→ connected, available

       The  table below clarifies the state transitions resulting from actions
       or commands:

	 current state	    operation		new state
	 -------------	    ---------		---------
	 empty/
	 unconfigured:
		       device plugged in:     connected/configured or
					      connected/unconfigured
					      (if enumeration failed)
		       device removed:	      n/a
		       cfgadm -c unconfigure: empty/unconfigured
		       cfgadm -c configure:   empty/unconfigured
		       cfgadm -c disconnect:  empty/unconfigured
					      (no-op and error)

	 disconnected/
	 unconfigured:
		       device plugged in:     n/a
		       device removed:	      empty/unconfigured
		       cfgadm -c unconfigure: disconnected/unconfigured
		       cfgadm -c configure:   connected/configured, or
					      connected/unconfigured
					      (if reenumeration failed)
		      cfgadm -c disconnect:   disconnected/unconfigured

	 connected/unconfigured:
		      device plugged in:      n/a
		      device removed:	      empty/unconfigured
		      cfgadm -c unconfigure:  connected/unconfigured
		      cfgadm -c configure:    connected/configured, or
					      connected/unconfigured
					      (if reenumeration failed)
		      cfgadm -c disconnect:   disconnected/unconfigured

	 connected/configured:
		      device plugged in:      n/a
		      device removed:	      empty/unconfigured or
					      connected/configured,
					      but with ap condition
					      'unusable' if device
					      was open when removed
		      cfgadm -c unconfigure:  connected/unconfigured
		      cfgadm -c configure:    connected/configured
		      cfgadm -c disconnect:   disconnected/unconfigured

EXAMPLES
       Example 1 Listing the Status of All USB Devices

       The following command lists the status of all USB devices on  the  sys‐
       tem:

	 # cfgadm
	 Ap_Id		 Type	      Receptacle   Occupant	Condition
	 usb0/1		 USB-hub      connected	   configured	ok
	 usb0/2		 unknown      empty	   unconfigured ok
	 usb0/1.1	 USB-storage  connected	   configured	ok
	 usb0/1.2	 unknown      empty	   unconfigured ok
	 usb0/1.3	 unknown      empty	   unconfigured ok
	 usb0/1.4	 USB-device connected	 configured   ok

       Notice  that cfgadm treats the USB-device device at ap_id usb0/1.4 as a
       single unit, since it cannot currently control individual interfaces.

       Example 2 Listing the Status of a Port with No Device Plugged In

       The following command lists the status of a port with no device plugged
       in:

	 example# cfgadm -l usb0/1.3
	 Ap_Id		 Type	      Receptacle   Occupant	Condition
	 usb0/1.3	 unknown      empty	   unconfigured ok

       Example 3 Listing the Status of the Same Port with a Device Plugged In

       The  following  command	lists the status of the same port after physi‐
       cally plugging in a device that configures without problems:

	 example# cfgadm -l usb0/1.3
	 Ap_Id		 Type	      Receptacle   Occupant	Condition
	 usb0/1.3	 USB-hub      connected	   configured	ok

       Example 4 Unconfiguring an Existing USB Device

       The following command unconfigures the USB device attached to usb0/1.3,
       then displays the status of the ap_id:

	 example# cfgadm -c unconfigure usb0/1.3
	 Unconfigure the device: /devices/pci@0,0/pci8086,7112@7,2/hub@2:2.3
	 This operation suspends activity on the USB device
	 Continue (yes/no)?

	 Enter:

	 y

	 example# cfgadm -l usb0/1.3
	 Ap_Id		 Type	      Receptacle   Occupant	Condition
	 usb0/1.3	 unknown      connected	   unconfigured ok

       Example	5  Unconfiguring  and  Logically Disconnecting an Existing USB
       Device

       The following command unconfigures  and	logically  disconnects	a  USB
       device attached to usb0/1.3:

	 example# cfgadm -c disconnect usb0/1.3
	 Disconnect the device: /devices/pci@0,0/pci8086,7112@7,2/hub@2:2.3
	 This operation suspends activity on the USB device
	 Continue (yes/no)?

	 Enter:

	 y

	 example# cfgadm -l usb0/1.3
	 Ap_Id	       Type	    Receptacle	   Occupant	   Condition
	 usb0/1.3      unknown	    disconnected   unconfigured	   ok

       A  disconnect implies that cfgadm does an unconfigure first. The recep‐
       tacle status now shows disconnected, even though the  device  is	 still
       physically  connected.  In  this	 case, a physical hotplug or using the
       cfgadm -c configure on the ap_id brings it back on-line.

       Example 6 Configuring a Previously Unconfigured USB Device

       The following command configures	 a  USB	 device	 that  was  previously
       attached to usb0/1.3:

	 example # cfgadm -yc configure usb0/1.3
	 example# cfgadm -l usb0/1.3
	 Ap_Id		 Type	      Receptacle   Occupant	Condition
	 usb0/1.3	 unknown      connected	   configured	ok

       Example 7 Resetting a USB Device

       The following command resets a USB device:

	 example# cfgadm -x usb_reset usb0/1.3
	 Reset the device: /devices/pci@0,0/pci8086,7112@7,2/hub@2:2.3
	 This operation suspends activity on the USB device
	 Continue (yes/no)?

	 Enter:

	 y

       Example 8 Displaying Detailed Information About a USB Device

       The following command displays detailed information about a USB device.
       This device shows the following USB-specific information in the 'Infor‐
       mation' field:

	   o	  Manufacturer string: Iomega

	   o	  Product string: USB Zip 250

	   o	  Number of configurations supported: 1

	   o	  Configuration currently active: 0

	   o	  Configuration string descriptor for configuration 0: Default

	 example# cfgadm -lv  usb0/1.5
	 Ap_Id		       Receptacle   Occupant	 Condition  Information
	 When	      Type	   Busy		Phys_Id
	 usb0/1.5     connected	   configured	ok	   Mfg:"Io
	 mega"	Product:"USB Zip 250"  NConfigs:1  Config:0 : Default

	 example# cfgadm -l -s "cols=ap_id:info" usb0/1.5
	 Ap_Id			       Information
	 usb0/1.5		       Mfg:"Iomega"  Product:"USB Zip 250"
	 NConfigs:1  Config:0 : Default

       Example 9 Displaying Detailed Information About All USB Devices

       The  following  command	displays  detailed  information	 about all USB
       devices on the system:

	 example# cfgadm -l -s "select=class(usb),cols=ap_id:info"
	 Ap_Id			       Information
	 usb0/1			       Mfg:<undefined>	Product:<undefined>
	 NConfigs:1  Config:0 <no cfg str descr>
	 usb0/2
	 usb0/1.1		       Mfg:<undefined>	Product:<undefined>
	 NConfigs:1  Config:0 <no cfg str descr>
	 usb0/1.2
	 usb0/1.3
	 usb0/1.4		       Mfg:"Wizard"  Product:"Modem/ISDN"
	 NConfigs:3  Config:1 : V.90 Analog Modem
	 usb0/1.5		       Mfg:"Iomega"  Product:"USB Zip 250"
	 NConfigs:1  Config:0 : Default
	 usb0/1.6		       Mfg:"SOLID YEAR"	 Product:"SOLID YEAR
	 USB"NConfigs:1	 Config:0 <no cfg str descr>
	 usb0/1.7

       Lines containing only an ap_id are empty ports. These can  be  filtered
       out.  This  example  only  lists USB ap_ids with connected devices, and
       information about those devices.

	 example# cfgadm -l -s "select=class(usb),cols=ap_id:info" | grep Mfg
	 usb0/1			       Mfg:<undefined>	Product:<undefined>
	 NConfigs:1  Config:0 <no cfg str descr>
	 usb0/1.1		       Mfg:<undefined>	Product:<undefined>
	 NConfigs:1  Config:0 <no cfg str descr>
	 usb0/1.4		       Mfg:"Wizard"  Product:"Modem/ISDN"
	 NConfigs:3  Config:1 : V.90 Analog Modem
	 usb0/1.5		       Mfg:"Iomega"  Product:"USB Zip 250"
	 NConfigs:1  Config:0 : Default
	 usb0/1.6		       Mfg:"SOLID YEAR"	 Product:"SOLID YEAR USB"
	 Config:0 <no cfg str descr>

       Example 10 Listing Information About a Multi-configuration USB Device

       The following example lists information about a multi-configuration USB
       device.

       Notice the NConfigs field: the configurations available for this device
       are 0, 1, and 2 (0 to (NConfigs-1)).

	 example# cfgadm -l -s "cols=ap_id:info" usb0/1.4
	 Ap_Id			       Information
	 usb0/1.4		       Mfg:"Wizard"  Product:"Modem/ISDN"
	 NConfigs:3  Config:1 V.90 Analog Modem"

       Example 11 Setting the Current Configuration of	a  Multi-configuration
       USB Device

       The following example sets the current configuration of a multi-config‐
       uration USB device:

	 example# cfgadm -o config=2 -x usb_config usb0/1.4
	 Setting the device: /devices/pci@1f,2000/usb@1/device@3
	 to USB configuration 2
	 This operation suspends activity on the USB device
	 Continue (yes/no)?

	 Enter:

	 y

	 USB configuration changed successfully.

       The device path should be checked to ensure that the right instance  of
       a  device  is  being referred to, in the case where multiple devices of
       the exact same type are on the same bus. This information is  available
       in the 'Information' field.

FILES
       /usr/lib/cfgadm/usb.so.1

	   Hardware specific library for generic USB device administration

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Availability		     │system/library		   │
       └─────────────────────────────┴─────────────────────────────┘

SEE ALSO
       cfgadm(1M),    config_admin(3CFGADM),	attributes(5),	 scsa2usb(7D),
       usba(7D)

       Universal Serial Bus 1.1 Specification (www.usb.org)

       System Administration Guide: Advanced Administration

NOTES
       cfgadm(1M) can not unconfigure, disconnect, reset, or change  the  con‐
       figuration of any USB device currently opened by any application. These
       operations also fail on a hub if a device in its hierarchy is opened by
       an  application.	 See scsa2usb(7D) for unconfiguring a USB mass-storage
       device that is currently in use.

       Only super-users can execute any functions on an attachment point. How‐
       ever, one need not be a super-user to list the attachment points.

SunOS 5.11			  6 Nov 2009			cfgadm_usb(1M)
[top]

List of man pages available for OpenIndiana

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net