#ident "@(#)hotplug.1m.txt 1.12 09/07/13 SMI" System Administration Commands hotplug(1M) NAME hotplug - configure hotplug connectors and ports. SYNOPSIS hotplug list [-v] [-l] [ [ | ]] hotplug changestate [-f] [-q] -s { | } hotplug set -o hotplug get -o hotplug -? DESCRIPTION The hotplug command is used to manage hotplug connectors and ports. A hotplug connector is a representation of a physical point in the system where components may be inserted or removed. A hotplug port is a representation of a point in the system device tree where the connection of a branch of devices to the system is managed. 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 only unique relative to their bus controller. A device path is required to uniquely reference 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 may be virtually hotplugged, even if their hardware 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. state The state of a hotplug connector or port. The value of the state is a string description of the requested state. There are two sets of states: one for connectors, and one for ports. The state of a connector describes the physical state of the connector and its connected components. The state of a port describes the virtual state of a port and its dependent branch of the system device tree. The states for hotplug connectors are the following: empty The hotplug connector is un-probed, and its dependent hotplug ports and devices are removed from the system. present The hotplug connector is probed, and any inserted hardware components are detected. powered Power is applied to the components inserted in a hotplug connector. enabled The hotplug connector is fully functional, and its associated hotplug ports can be used. The states for hotplug ports are the following: port-empty The hotplug port is empty, with no dependent device nodes. port-present The hotplug port is occupied, and it has dependent device nodes in the system. But those dependent device nodes have not been initialized yet and are not yet functional. initialize The dependent device nodes of a hotplug port have been created, but their drivers are not attached. The devices are not yet functional. probed The dependent device nodes of a hotplug port have been probed, which means the system has identified the devices and bound them to device drivers. But they are not yet fully attached and so the devices are not yet functional. attached The dependent device nodes of a hotplug port have attached drivers. There may still be additional post-processing in progress to prepare the devices for normal operations. operational The dependent device nodes of a hotplug port are fully operational. maintenance The dependent device nodes of a hotplug port are in use, but not fully operational. A maintenance or fault management operation is affecting the devices. SUBCOMMANDS The following subcommands are supported: list Show information for hotplug connectors, ports, and their associated devices. changestate Transition the specified hotplug connector or port to the specified target state. The following states are the possible target states for changestate command: For a connector: "present", "powered", "enabled". For a port: "port-present", "initialize", "operational". When a connector is upgraded to "enabled" state, its dependent devices will be configured to "operational" state. set Set bus specific properties to the specified hotplug connector. The specified option string is an arbitrary string of name/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 Query bus specific properties from the specified hotplug connector or port. The specified option string is an arbitrary string of name/value pairs, as could be parsed by getsubopt(3C). The names and values will be passed directly to the bus controller to specify which properties should be returned. 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 only shows 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 operation 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 which may succeed or fail, perform a test to predict if the operation would succeed or fail. And if it would fail, show the error messages that would be expected if the operation had really been attempted. This option will not actually change the state of the system. -s state --state=state Specify the target state of a changestate command. -o options --options=options Specify bus specific properties for a set or get command. The options string conforms to the getsubopt(3C) syntax convention. The options can be keyword "help", on which a list of all supported properties and their possible values will be printed. For get command, the options can also be keyword "all", on which a list of all supported properties and their current values will be printed. -? --help Display a brief help message on proper use of the command. EXAMPLES Example 1: Showing all hotplug connections To show information about all hotplug connections, enter the following command: # hotplug list -v pci@0,0 (OPERATIONAL) pci108e,534a@2,1 [pci30] (EMPTY) (OPERATIONAL) pci10de,5d@e (OPERATIONAL) display@b [NEM0] (ENABLED) (OPERATIONAL) pci108e,534a@a,0:nge0 (network@0, Network interface nge0) (SUNW_datalink/2, nge0: hosts IP addresses: 10.0.0.1) (MAINTENANCE) pci108e,534a@a,1:nge1 [NEM1] (EMPTY) (ATTACHED) pci108e,534a@4:sound,audio To show the full paths of hotplug connections and devices, enter the following command: # hotplug list -l /pci@0,0 (OPERATIONAL) /pci@0,0/pci108e,534a@2,1 [pci30] (EMPTY) /pci@0,0 (OPERATIONAL) /pci@0,0/pci10de,5d@e (OPERATIONAL) /pci@0,0/pci10de,5d@e/display@b /pci@0,0/pci10de,5d@e [NEM0] (ENABLED) /pci@0,0/pci10de,5d@e (OPERATIONAL) /pci@0,0/pci10de,5d@e/pci108e,534a@a,0:nge0 /pci@0,0/pci10de,5d@e (MAINTENANCE) /pci@0,0/pci10de,5d@e/pci108e,534a@a,0:nge1 /pci@0,0/pci10de,5d@e [NEM1] (EMPTY) /pci@0,0 (ATTACHED) /pci@0,0/pci108e,534a@4:sound,audio Example 2: Failure during state change operation If a change state operation is attempted and fails, an explanation is displayed. In the previous example there exists a plumbed network interface within the virtual connector , which is associated with the device path of "/pci@0,0/pci10de,5d@e." An attempt to offline this connector would fail, as follows: # hotplug changestate -s port-empty /pci@0,0/pci10de,5d@e pci.a,0 Operation failed: resource is busy. pci108e,534a@a,0:nge0 (network@0, Network interface e1000g0) (SUNW_datalink/2, IP: Device consumers prohibit offline(e1000g0)) Example 3: Displaying all supported bus specific properties and their possible values. # hotplug get -o help /pci@0,0 pci.2.1 power_led= fault_led= active_led= attn_led= card_type= board_type= Example 4: Displaying bus specific options To display 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 bus specific property To turn on the Attention LED of a PCI hotplug connector: # hotplug set -o attn_led=on /pci@0,0 pci.2.1 ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Availability | SUNWcsu | |_____________________________|_____________________________| | Interface Stability | Evolving | |_____________________________|_____________________________| NOTES Verbose usage information is gathered from the RCM framework. Its format and content is subject to change.