Copyright 2023 Peter Tribble
Copyright 2003 (c), Sun Microsystems, Inc. All Rights Reserved
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
cfgadm -l [-a] [-o parsable] ap_id...
cfgadm -c function [-f] [-y | -n] [-o nopoweroff] [-v] ap_id...
cfgadm -t [-v] ap_id...
cfgadm -x [-f] [-v] function ap_id...
The cfgadm command resides in /usr/sbin. See cfgadm(8). The cfgadm_sbd plugin resides in /usr/platform/${arch}/lib/cfgadm.
Each board slot appears as a single attachment point in the device tree. Each component appears as a dynamic attachment point. You can view the type, state, and condition of each component, and the states and condition of each board slot by using the -a option.
The cfgadm options perform differently depending on the platform. Additionally, the form of the attachment points is different depending on the platform.
The component failed testing.
The component is operational.
The component has not been tested.
The component is connected to the board slot.
The following are the names and descriptions of the occupant states for components: configured
The component is available for use by the operating system.
The component is not available for use by the operating system.
The board failed testing.
The board is operational.
The board has not been tested.
The board slot is unusable.
Caution: Removing a board that is in the connected state or that is powered on and in the disconnected state crashes the operating system and can result in permanent damage to the system.
The following are the names and descriptions of the receptacle states for boards: connected
The board is powered on and connected to the system bus. You can view the components on a board only after it is in the connected state.
The board is disconnected from the system bus. A board can be in the disconnected state without being powered off. However, a board must be powered off and in the disconnected state before you remove it from the slot.
A board is not present.
The occupant state of a disconnected board is always unconfigured. The following table contains the names and descriptions of the occupant states for boards: configured
At least one component on the board is configured.
All of the components on the board are unconfigured.
The following list contains the functions that change the state:
configure
unconfigure
connect
disconnect
The following list contains the functions that change the condition:
poweron
poweroff
test
In the following code examples, the permanent memory on board 0 must be moved to another board. Thus, board 0 is the source, and board 1 is the target.
A status change operation cannot be initiated on a board while it is marked as busy. For brevity, the CPU information has been removed from the code examples.
The process is started with the following command:
# cfgadm -c unconfigure -y SB0::memory &
First, the memory on board 1 in the same address range as the permanent memory on board 0 must be deleted. During this phase, the source board, the target board, and the memory attachment points are marked as busy. You can display the status with the following command:
# cfgadm -a -s cols=ap_id:type:r_state:o_state:busy SB0 SB1
Ap_Id Type Receptacle Occupant Busy
SB0 CPU connected configured y
SB0::memory memory connected configured y
SB1 CPU connected configured y
SB1::memory memory connected configured y
After the memory has been deleted on board 1, it is marked as unconfigured. The memory on board 0 remains configured, but it is still marked as busy, as in the following example.
Ap_Id Type Receptacle Occupant Busy SB0 CPU connected configured y SB0::memory memory connected configured y SB1 CPU connected configured y SB1::memory memory connected unconfigured n
The memory from board 0 is then copied to board 1. After it has been copied, the occupant state for the memory is switched. The memory on board 0 becomes unconfigured, and the memory on board 1 becomes configured. At this point in the process, only board 0 remains busy, as in the following example.
Ap_Id Type Receptacle Occupant Busy SB0 CPU connected configured y SB0::memory memory connected unconfigured n SB1 CPU connected configured n SB1::memory memory connected configured n
After the entire process has been completed, the memory on board 0 remains unconfigured, and the attachment points are not busy, as in the following example.
Ap_Id Type Receptacle Occupant Busy SB0 CPU connected configured n SB0::memory memory connected unconfigured n SB1 CPU connected configured n SB1::memory memory connected configured n
The permanent memory has been moved, and the memory on board 0 has been unconfigured. At this point, you can initiate a new state changing operation on either board.
command -o sbd_options,platform=platform_options
Performs a state change function. You can use the following functions: unconfigure
Changes the occupant state to unconfigured. This function applies to system board slots and to all of the components on the system board. The unconfigure function removes the CPUs from the CPU list and deletes the physical memory from the system memory pool. If any device is still in use, the cfgadm command fails and reports the failure to the user. You can retry the command as soon as the device is no longer busy. If a CPU is in use, you must ensure that it is off line before you proceed. See pbind(8), psradm(8) and psrinfo(8). The unconfigure function moves the physical memory to another system board before it deletes the memory from the board you want to unconfigure. Depending of the type of memory being moved, the command fails if it cannot find enough memory on another board or if it cannot find an appropriate physical memory range. For permanent memory, the operating system must be suspended (that is, quiesced) while the memory is moved and the memory controllers are reprogrammed. If the operating system must be suspended, you will be prompted to proceed with the operation. You can use the -y or -n options to always answer yes or no respectively. Moving memory can take several minutes to complete, depending on the amount of memory and the system load. You can monitor the progress of the operation by issuing a status command against the memory attachment point. You can also interrupt the memory operation by stopping the cfgadm command. The deleted memory is returned to the system memory pool.
Changes the receptacle state to disconnected. This function applies only to system board slots. If the occupant state is configured, the disconnect function attempts to unconfigure the occupant. It then powers off the system board. At this point, the board can be removed from the slot. If you specify -o nopoweroff, the disconnect function leaves the board powered on.
Changes the occupant state to configured. This function applies to system board slots and to any components on the system board. If the receptacle state is disconnected, the configure function attempts to connect the receptacle. It then walks the tree of devices that is created by the connect function, and attaches the devices if necessary. Running this function configures all of the components on the board, except those that have already been configured. For CPUs, the configure function adds the CPUs to the CPU list. For memory, the configure function ensures that the memory is initialized then adds the memory to the system memory pool. The CPUs and the memory are ready for use after the configure function has been completed successfully. For I/O devices, you must use the mount and the ifconfig commands before the devices can be used. See ifconfig(8) and mount(8).
Changes the receptacle state to connected. This function applies only to system board slots. After the connect function is completed successfully, you can use the -a option to view the status of the components on the board. The connect function leaves all of the components in the unconfigured state.
Overrides software state changing constraints. The -f option never overrides fundamental safety and availability constraints of the hardware and operating system.
Lists the state and condition of attachment points specified in the format controlled by the -s, -v, and -a options as specified in cfgadm(8). The cfgadm_sbd plugin provides specific information in the info field as described below. The format of this information might be altered by the -o parsable option. The parsable info field is composed of the following: cpu
The cpu type displays the following information: cpuid=#[,#.\|.\|.]
Where # is a number, and represents the ID of the CPU. If more than one # is present, this CPU has multiple active virtual processors.
Where # is a number and represents the speed of the CPU in MHz.
Where # is a number and represents the size of the ecache in MBytes. If the CPU has multiple active virtual processors, the ecache could either be shared among the virtual processors, or divided between them.
The memory type displays the following information, as appropriate: address=#
Where # is a number, representing the base physical address.
Where # is a number, representing the size of the memory in KBytes.
Where # is a number, representing the size of permanent memory in KBytes.
An operating system setting that prevents the memory from being unconfigured.
The board is participating in interleaving with other boards.
Represents the source attachment point.
Represents the target attachment point.
Where # is a number, representing the amount of memory that has already been deleted in KBytes.
Where # is a number, representing the amount of memory to be deleted in KBytes.
The io type displays the following information: device=path
Represents the physical path to the I/O component.
The I/O component is referenced.
The board type displays the following boolean name. If it are not present, then the opposite applies. powered-on
The board is powered on.
Returns the information in the info field as a boolean name or a set of name=value pairs, separated by a space character. The -o parsable option can be used in conjunction with the -s option. See the cfgadm(8) man page for more information about the -s option.
Tests the board. Before a board can be connected, it must pass the appropriate level of testing. Use of this option always attempts to test the board, even if it has already passed the appropriate level of testing. Testing is also performed when a -c connect state change function is issued, in which case the test step can be skipped if the board already shows an appropriate level of testing. Thus the -t option can be used to explicitly request that the board be tested.
Performs an sbd-class function. You can use the following functions: poweron
Powers the system board on. The receptacle state must be disconnected.
Powers the system board off. The receptacle state must be disconnected.
The exact format depends on the platform and typically corresponds to the physical labelling on the machine.
The component attachment point ID takes the form component_typeX, where component_type equals one of the component types described in "Component Types" and X equals the component number. The component number is a board-relative unit number. The above convention does not apply to memory components. Any DR action on a memory attachment point affects all of the memory on the system board.
Example 1 Listing All of the System Board
# cfgadm -a -s "select=class(sbd)"
Ap_Id Type Receptacle Occupant Condition
SB0 CPU connected configured ok
SB0::cpu0 cpu connected configured ok
SB0::memory memory connected configured ok
IO1 HPCI connected configured ok
IO1::pci0 io connected configured ok
IO1::pci1 io connected configured ok
SB2 CPU disconnected unconfigured failed
SB3 CPU disconnected unconfigured unusable
SB4 unknown empty unconfigured unknown
This example demonstrates the mapping of the following conditions:
The board in Slot 2 failed testing.
Slot 3 is unusable; thus, you cannot hot plug a board into that slot.
Example 2 Listing All of the CPUs on the System Board
# cfgadm -a -s "select=class(sbd):type(cpu)"
Ap_Id Type Receptacle Occupant Condition
SB0::cpu0 cpu connected configured ok
SB0::cpu1 cpu connected configured ok
SB0::cpu2 cpu connected configured ok
SB0::cpu3 cpu connected configured ok
Example 3 Displaying the CPU Information Field
# cfgadm -l -s noheadings,cols=info SB0::cpu0
cpuid 16, speed 400 MHz, ecache 8 Mbytes
Example 4 Displaying the CPU Information Field in Parsable Format
# cfgadm -l -s noheadings,cols=info -o parsable SB0::cpu0
cpuid=16 speed=400 ecache=8
Example 5 Displaying the Devices on an I/O Board
# cfgadm -a -s noheadings,cols=ap_id:info -o parsable IO1 IO1 powered-on assigned IO1::pci0 device=/devices/saf@0/pci@0,2000 referenced IO1::pci1 device=/devices/saf@0/pci@1,2000 referenced
Example 6 Monitoring an Unconfigure Operation
In the following example, the memory sizes are displayed in Kbytes.
# cfgadm -c unconfigure -y SB0::memory & # cfgadm -l -s noheadings,cols=info -o parsable SB0::memory SB1::memory address=0x0 size=2097152 permanent=752592 target=SB1::memory deleted=1273680 remaining=823472 address=0x1000000 size=2097152 source=SB0::memory
| ATTRIBUTE TYPE ATTRIBUTE VALUE |
| Stability See below. |
The interface stability is evolving. The output stability is unstable.
# cfgadm -c unconfigure -y SB0::memory & # watch_memdel SB0 #!/bin/sh # This is the watch_memdel script. if [ -z "$1" ]; then printf "usage: %s board_id\en" `basename $0` exit 1 fi board_id=$1 cfgadm_info='cfgadm -s noheadings,cols=info -o parsable' eval `$cfgadm_info $board_id::memory` if [ -z "$remaining" ]; then echo no memory delete in progress involving $board_id exit 0 fi echo deleting target $target while true do eval `$cfgadm_info $board_id::memory` if [ -n "$remaining" -a "$remaining" -ne 0 ] then echo $deleted KBytes deleted, $remaining KBytes remaining remaining= else echo memory delete is done exit 0 fi sleep 1 done exit 0