#ident "@(#)hotplug.1m.txt 1.3 09/06/05 SMI" System Administration Commands hotplug(1M) NAME hotplug - configure hotplug connectors and ports. SYNOPSIS hotplug list [-a] [-v] [ | ]] hotplug changestate [-f] [-q] -s [ | ] hotplug passthru [ | ] 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. 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 target state that a hotplug connector or port shall be transitioned to during a changestate command. The value of the target state is a string description of the requested state, and may be one of the following: empty The hotplug connector is un-probed, and its dependent hotplug ports and devices are removed from the system. This state only applies to hotplug connectors. present The hotplug connector is probed, and any dependent hotplug ports and devices are detected. This state only applies to hotplug connectors. powered Power is applied to the dependent devices in a hotplug connector. This state only applies to hotplug connectors. enabled The hotplug connector is fully functional. This state only applies to hotplug connectors. port-empty The hotplug port is empty, and has no dependent device nodes. This state only applies to hotplug ports. port-present The hotplug port has dependent device nodes. This state only applies to hotplug ports. offline The dependent device nodes of a hotplug port are disabled. This state only applies to hotplug ports. online The dependent device nodes of a hotplug port are enabled. This state only applies to hotplug ports. maintenance The dependent device nodes of a hotplug port are enabled, but not fully operational. A maintenance or fault management operation is affecting the devices. This state only applies to hotplug ports. SUBCOMMANDS The following subcommands are supported: list Show information for all hotplug connectors and ports, or for only a specific hotplug connector or port. changestate Transition the specified hotplug connector or port to the specified target state. passthru Send a bus specific command to 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 that manages the specified hotplug connector or port to perform a bus specific function. OPTIONS The following options are supported: -a --all Show all dependents. By default, if a path is specified, the list subcommand will only show immediate details of the path and its directly associated connectors and ports. And if a connector or port is specified, the display will be further constrained. This option enables including all dependent connectors, ports, and devices. This option is implied if no path is specified. -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 Specify the target state of a changestate command. EXAMPLES Example 1: Showing all hotplug connectors To show information about all hotplug connectors, enter the following command: # hotplug list -v pci@0,0 [pci.2.1] pci108e,534a@2,1 [pci.3.0] (OFFLINE) pci10de,5d@e [pci.e,0] display@b [NEM0] pci108e,534a@a,0:nge0 (network@0, Network interface e1000g0) (SUNW_datalink/2, e1000g0: hosts IP addresses: 10.0.0.1) pci108e,534a@a,1:nge1 (MAINTENANCE) [NEM1] (EMPTY) pci108e,534a@4:sound,audio (OFFLINE) 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 offline /pci@0,0/pci10de,5d@e pci.a,0 Operation failed. Explanation: resource is busy. pci@0,0 pci10de,5d@e [pci.e,0] [NEM0] pci108e,534a@a,0:nge0 (network@0, Network interface e1000g0) (SUNW_datalink/2, IP: Device consumers prohibit offline(e1000g0)) ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Availability | SUNWcsu | |_____________________________|_____________________________| | Interface Stability | Evolving | |_____________________________|_____________________________|