hotplug man page on SmartOS

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

hotplug(1M)		System Administration Commands		   hotplug(1M)

NAME
       hotplug - configure hotplug connectors and ports

SYNOPSIS
       hotplug list [-l] [-v] [path [connection]]

       hotplug online path port

       hotplug offline [-f] [-q] path port

       hotplug enable path connector

       hotplug disable [-f] [-q] path connector

       hotplug poweron path connector

       hotplug poweroff [-f] [-q] path connector

       hotplug set -o options path connector

       hotplug get -o options path connector

       hotplug -?

DESCRIPTION
       The hotplug command is used to manage hotplug connections. A connection
       can be a connector or port. A hotplug connector is a representation  of
       a  physical  point  in  the  system where components can be inserted or
       removed. A hotplug port is a representation of a logical point  in  the
       system  device  tree  where the connection of a device to the system is
       managed.

       The hotplug command only supports hotplug operations on hotplug connec‐
       tors  for  PCI  Express buses and PCI buses that implement the Standard
       PCI Hotplug feature. Hotplug ports on PCI Expresss  and	PCI  buses  in
       systems	with  PCI Express fabrics are also supported. Additional buses
       may be supported in the future.

       The hotplug command operates on the following kinds of objects:

       path

	   Hotplug connectors and ports are integrated into the Solaris device
	   tree. The names of connectors and ports are unique relative only to
	   their bus controller. A device path is required to uniquely	refer‐
	   ence a connector or port.

       connector

	   If  a  hardware  component  supports	 being	physically inserted or
	   removed, then a hotplug connector  represents  the  location	 where
	   this	 action may occur. When a connector exists, it has a hierarchy
	   of ports and device nodes that depend upon it.

       port

	   All device nodes can be virtually hotplugged, even if  their	 hard‐
	   ware	 does  not support physical hotplugging. A hotplug port exists
	   between a device node and its parent	 node  in  the	system	device
	   tree.  It  represents  the  location	 where the device node and its
	   dependents can be managed.

       connection

	   A hotplug connection is a generic term to refer to either a hotplug
	   connector or a hotplug port.

       Hotplug	connectors  and	 ports are managed according to a state model.
       The hotplug command can list information about the hotplug  connections
       in  a system, or it can initiate change of state operations on specific
       hotplug connections.

       Hotplug connectors can be in the following states:

       empty

	   A component is not physically inserted in the connector.

       present

	   A component is physically inserted in the connector, but the compo‐
	   nent is powered off. The component is not in use.

       powered

	   A component is physically inserted in the connector, and the compo‐
	   nent is powered on. The component is disabled and is not in use.

       enabled

	   A component is physically inserted in the connector. The  component
	   is  powered	on  and	 has  been probed and tested. The component is
	   enabled and devices that represent its functions can be used.

       Hotplug ports can be in the following states:

       port-empty

	   No device exists for the hotplug port.

       port-present

	   A device exists for the hotplug port, but the device has  not  been
	   probed  and	it has no attached device driver. The device is not in
	   use.

       offline

	   A device exists for the hotplug  port,  and	the  device  has  been
	   probed.  A  device driver is not attached, and the device is not in
	   use.

       online

	   A device exists for the hotplug port,  and  its  device  driver  is
	   fully attached. The device is in use.

       maintenance

	   A  device  exists  for  the	hotplug port, and its device driver is
	   fully attached. The device is in use, but not fully operational.  A
	   maintenance or fault management operation is affecting the device.

       The  hotplug  command  can  also access bus private properties for each
       hotplug connector. The current values of bus private properties can  be
       displayed.  New	values	for  each  bus	private	 property  can	be set
       directly.

SUB-COMMANDS
       The following subcommands are supported:

       list

	   Show information for hotplug connectors, ports, and	their  associ‐
	   ated	 devices.  Hotplug connectors and hotplug ports are integrated
	   into the Solaris device tree hierarchy. The list subcommand	there‐
	   fore	 displays the hierarchy of device nodes with additional infor‐
	   mation included to show the locations  of  hotplug  connectors  and
	   hotplug  ports.  The	 names	of  hotplug connectors are enclosed in
	   square brackets, and the names of hotplug  ports  are  enclosed  in
	   angled  brackets.  The  current state of each hotplug connection is
	   displayed next to its name.

       online

	   Change the state of a hotplug port to the online state.

       offline

	   Change the state of a hotplug port to the offline state.

       enable

	   Change the state of a hotplug connector to the enabled  state.  All
	   of  the  hotplug  connector's dependent ports will be automatically
	   probed and initialized into the online state.

       disable

	   Change the state of a hotplug connector from the enabled  state  to
	   the powered state. All dependent ports that are in the online state
	   will first be transitioned to the port-present state.

       poweron

	   Change the state of a hotplug connector from the present  state  to
	   the powered state.

       poweroff

	   Change the state of a hotplug connector from the powered or enabled
	   state to the present state. All dependent ports  that  are  in  the
	   online  state will first be transitioned to the port-present state,
	   and will then be removed.

       set

	   Set bus-specific properties for a hotplug connector. The  specified
	   option  string is a bus specific string of name and value pairs, as
	   could be parsed by getsubopt(3C). The  names	 and  values  will  be
	   passed  directly  to	 the bus controller that manages the specified
	   hotplug connector to perform a bus-specific function.

       get

	   Display the current values of bus specific properties for a hotplug
	   connector.  The specified option string is a bus specific string of
	   named properties, as could be parsed by  getsubopt(3C).  The	 names
	   will	 be  passed  directly  to  the bus controller to specify which
	   properties should be returned. The current  values  of  each	 named
	   property will then be displayed.

OPTIONS
       The following options are supported:

       -l, --list-path

	   Show	 full  paths  to connections and device nodes. By default, the
	   list subcommand shows hotplug connectors, ports, and devices in the
	   format  of a tree. This option enables the display of full paths to
	   each connection and device node.

       -v, --verbose

	   Show verbose usage details. By default, the list  subcommand	 shows
	   only	 hotplug  connectors,  ports, and devices. This option enables
	   the display of more detailed information about how the devices  are
	   currently consumed. Examples include mounted filesystems or plumbed
	   network interfaces associated with individual devices.

       -f, --force

	   Force the operation.	 Some  change  state  operations  that	impact
	   resources currently in use will fail with a warning. A forced oper‐
	   ation will attempt to ignore these warnings and proceed.

	   This option should be used with extreme caution.

       -q, --query

	   Query the operation. Instead of actually performing a change	 state
	   operation, perform a test to predict if the operation would succeed
	   or fail. If it would fail, show the error messages  that  would  be
	   expected if the operation had really been attempted.

	   It is not possible to predict every failure. An operation that suc‐
	   ceeds during a query could still fail for another reason when actu‐
	   ally attempted.

	   This option will not actually change the state of the system.

       -o options, --=options

	   Specify  bus-specific  properties  for  a  set  or get command. The
	   options string conforms to the getsubopt(3C) syntax convention.

	   For the get subcommand, there are two special options that  can  be
	   used.  The special options value of help will display all supported
	   properties and their possible values. The special options value  of
	   all will display the current value of all supported properties.

	   For	the  set  subcommand,  there is one special option that can be
	   used. The special options value of help will display all  supported
	   properties which can be set and their possible values.

	   See	"Notes"	 section  for  the  properties	supported  by bus con‐
	   trollers.

       -?, --help

	   Display a brief help message on proper use of the command.

EXAMPLES
       Example 1 Showing All Hotplug Connections

       The following command shows all hotplug connections:

	 # hotplug list -v
	 pci@0,0
		 <pci.2,1> (ONLINE)
		  pci108e,534a@2,1
			  [pci30] (EMPTY)
		 <pci.e,0> (ONLINE)
		  pci10de,5d@e
			  <pci.b,0> (ONLINE)
			  display@b
			  [NEM0] (ENABLED)
			  <pci.a,0> (ONLINE)
			  pci108e,534a@a,0
				  { Network interface nge0 }
				  { nge0: hosts IP addresses: 10.0.0.1 }
			  <pci.a,1> (MAINTENANCE)
			  pci108e,534a@a,1
			  [NEM1] (EMPTY)
		  <pci.c,0> (OFFLINE)
			 pci108e,534a@4

       To show the full paths of hotplug connections and  devices,  enter  the
       following command:

	 # hotplug list -l
	 /pci@0,0 <pci.2,1> (ONLINE)
	 /pci@0,0/pci108e,534a@2,1 [pci30] (EMPTY)
	 /pci@0,0 pci.e,0> (ONLINE)
	 /pci@0,0/pci10de,5d@e <pci.b,0> (ONLINE)
	 /pci@0,0/pci10de,5d@e/display@b
	 /pci@0,0/pci10de,5d@e [NEM0] (ENABLED)
	 /pci@0,0/pci10de,5d@e <pci.a,0> (ONLINE)
	 /pci@0,0/pci10de,5d@e/pci108e,534a@a,0
	 /pci@0,0/pci10de,5d@e <pci.a,1> (MAINTENANCE)
	 /pci@0,0/pci10de,5d@e/pci108e,534a@a,0
	 /pci@0,0/pci10de,5d@e [NEM1] (EMPTY)
	 /pci@0,0 pci.c,0> (OFFLINE)
	 /pci@0,0/pci108e,534a@4

       Example 2 Reporting Failure During State Change Operation

       If  a  change  of state operation fails, an explanation is displayed to
       describe the failure. An attempt to offline a hotplug port with	depen‐
       dent devices that are currently in use by the system might fail as fol‐
       lows:

	 # hotplug offline /pci@0,0/pci10de,5d@e pci.a,0
	 ERROR: devices or resources are busy.
	 pci108e,534a@a,0:
	     { Network interface nge0 }
	     { nge0: hosts IP addresses: 10.0.0.1 }
	     { Plumbed IP Address }

       Example 3 Displaying Bus-Specific Properties and Values

       The following command displays all  supported  bus-specific  properties
       and their possible values:

	 # hotplug get -o help /pci@0,0 pci.2,1
	 power_led=<on|off|blink>
	 fault_led=<on|off|blink>
	 active_led=<on|off|blink>
	 attn_led=<on|off|blink>
	 card_type=<type description>
	 board_type=<type description>

       Example 4 Displaying Bus-Specific Options

       The  following  command displays the card type and the current state of
       the Power LED of a PCI hotplug connector:

	 # hotplug get -o card_type,power_led /pci@0,0 pci.2,1
	 card_type=fibre
	 power_led=on

       Example 5 Setting a Bus-Specific Property

       The following command turns on the attention LED of a PCI hotplug  con‐
       nector:

	 # hotplug set -o attn_led=on /pci@0,0 pci.2,1

EXIT STATUS
       0

	   Successful completion.

       1

	   Invalid command line options were specified.

       2

	   The specified path or connection does not exist.

       3

	   A fatal error occurred. One or more error messages are displayed on
	   standard error.

       4

	   The hotplug service is not available.

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

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Availability		     │SUNWcsu			   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Interface Stability	     │Committed			   │
       └─────────────────────────────┴─────────────────────────────┘

SEE ALSO
       cfgadm(1M), hotplugd(1M), getsubopt(3C), attributes(5)

DIAGNOSTICS
       The following error message is displayed on systems that	 do  not  have
       any supported I/O buses:

	 ERROR: there are no connections to display.
	 (See hotplug(1m) for more information.)

       If  this	 error	message is seen, note that the system might still have
       other I/O devices that support hotplugging, through the cfgadm(1M) com‐
       mand instead of hotplug.

NOTES
       The  hotplug  service  (FMRI  svc:/system/hotplug) must be enabled as a
       prerequisite for using the hotplug command. See hotplugd(1M).

       The authorization solaris.hotplug.modify must be granted	 in  order  to
       perform	change-of-state	 operations. Alternatively, the rights profile
       "Hotplug Management" can be granted, which includes that authorization.

       Verbose usage information is gathered from the RCM framework. Its  for‐
       mat and content is subject to change.

       The  following  bus  specific  properties are supported in PCI bus con‐
       trollers:

       power_led | fault_led | attn_led | active_led

	   States of a specific LED of a slot. The value could be on, off,  or
	   blink.

	   They	 can  all  be  used  with  get	subcommand,  but only property
	   attn_led can be used with set subcommand.

       card_type | board_type

	   Type of a card or board of a slot.

	   They can all be used with get subcommand, but neither can  be  used
	   with set subcommand.

SunOS 5.11			  11 Feb 2010			   hotplug(1M)
[top]

List of man pages available for SmartOS

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