cfgadm_sbd(1M) System Administration Commands cfgadm_sbd(1M)NAMEcfgadm_sbd - cfgadm commands for system board administration
SYNOPSIS
cfgadm -l [-a] [-o parsable] ap_id...
cfgadm -c function [-f] [-y | -n]
[-o unassign | nopoweroff] [-v] ap_id...
cfgadm -t [-v] ap_id...
cfgadm -x [-f] [-v] function ap_id...
DESCRIPTION
The cfgadm_sbd plugin provides dynamic reconfiguration functionality
for connecting, configuring, unconfiguring, and disconnecting class sbd
system boards. It also enables you to connect or disconnect a system
board from a running system without having to reboot the system.
The cfgadm command resides in /usr/sbin. See cfgadm(1M). The cfgadm_sbd
plugin resides /usr/platform/sun4u/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. Addi‐
tionally, the form of the attachment points is different depending on
the platform. See the Platform Notes section for more information.
Component Conditions
The following are the names and descriptions of the component condi‐
tions:
failed The component failed testing.
ok The component is operational.
unknown The component has not been tested.
Component States
The following is the name and description of the receptacle state for
components:
connected 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 Solaris oper‐
ating environment.
unconfigured The component is not available for use by the Solaris
operating environment.
Board Conditions
The following are the names and descriptions of the board conditions.
failed The board failed testing.
ok The board is operational.
unknown The board has not been tested.
unusable The board slot is unusable.
Board States
Inserting a board changes the receptacle state from empty to discon‐
nected. Removing a board changes the receptacle state from disconnected
to empty.
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.
disconnected 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.
empty 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.
unconfigured All of the components on the board are unconfigured.
Dynamic System Domains
Platforms based on dynamic system domains (DSDs, referred to as domains
in this document) divide the slots in the chassis into electrically
isolated hardware partitions (that is, DSDs). Platforms that are not
based on DSDs assign all slots to the system permanently.
A slot can be empty or populated, and it can be assigned or available
to any number of domains. The number of slots available to a given
domain is controlled by an available component list (ACL) that is main‐
tained on the system controller. The ACL is not the access control list
provided by the Solaris operating environment.
A slot is visible to a domain only if the slot is in the domain's ACL
and if it is not assigned to another domain. An unassigned slot is vis‐
ible to all domains that have the slot in their ACL. After a slot has
been assigned to a domain, the slot is no longer visible to any other
domain.
A slot that is visible to a domain, but not assigned, must first be
assigned to the domain before any other state changing commands are
applied. The assign can be done explicitly using -x assign or implic‐
itly as part of a connect. A slot must be unassigned from a domain
before it can be used by another domain. The unassign is always
explicit, either directly using -x unassign or as an option to discon‐
nect using -o unassign.
State Change Functions
Functions that change the state of a board slot or a component on the
board can be issued concurrently against any attachment point. Only one
state changing operation is permitted at a given time. A Y in the Busy
field in the state changing information indicates an operation is in
progress.
The following list contains the functions that change the state:
o configure
o unconfigure
o connect
o disconnect
Availability Change Functions
Commands that change the availability of a board can be issued concur‐
rently against any attachment point. Only one availability change oper‐
ation is permitted at a given time. These functions also change the
information string in the cfgadm -l output. A Y in the Busy field indi‐
cates that an operation is in progress.
The following list contains the functions that change the availability:
o assign
o unassign
Condition Change Functions
Functions that change the condition of a board slot or a component on
the board can be issued concurrently against any attachment point. Only
one condition change operation is permitted at a given time. These
functions also change the information string in the cfgadm -l output. A
Y in the Busy field indicates an operation is in progress.
The following list contains the functions that change the condition:
o poweron
o poweroff
o test
Unconfigure Process
This section contains a description of the unconfigure process, and
illustrates the states of source and target boards at different stages
during the process of moving permanent memory.
In the following code examples, the permanent memory on board 0 must be
moved to another board in the domain. 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 unconfig‐
ured. 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 config‐
ured. 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.
Platform-Specific Options
You can specify platform-specific options that follow the options
interpreted by the system board plugin. All platform-specific options
must be preceded by the platform keyword. The following example con‐
tains the general format of a command with platform-specific options:
command -o sbd_options,platform=platform_options
OPTIONS
This man page does not include the -v, -a, -s, or -h options for the
cfgadm command. See cfgadm(1M) for descriptions of those options. The
following options are supported by the cfgadm_sbd plugin:
-c function Performs a state change function. You can use the fol‐
lowing functions:
unconfigure Changes the occupant state to unconfig‐
ured. 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 physi‐
cal 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(1M), psradm(1M) and psrinfo(1M).
The unconfigure function moves the physi‐
cal 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 sys‐
tem 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 mem‐
ory 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.
disconnect Changes the receptacle state to discon‐
nected. This function applies only to
system board slots.
If the occupant state is configured, the
disconnect function attempts to unconfig‐
ure the occupant. It then powers off the
system board. At this point, the board
can be removed from the slot.
This function leaves the board in the
assigned state on platforms that support
dynamic system domains.
If you specify -o nopoweroff, the discon‐
nect function leaves the board powered
on. If you specify -o unassign, the dis‐
connect function unassigns the board from
the domain.
If you unassign a board from a domain,
you can assign it to another domain. How‐
ever, if it is assigned to another
domain, it is not available to the domain
from which is was unassigned.
configure 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 con‐
nect the receptacle. It then walks the
tree of devices that is created by the
connect function, and attaches the
devices if necessary. Running this func‐
tion 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 mem‐
ory 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(1M) and
mount(1M).
connect Changes the receptacle state to con‐
nected. This function applies only to
system board slots.
If the board slot is not assigned to the
domain, the connect function attempts to
assign the slot to the domain. Next, it
powers on and tests the board, then it
connects the board electronically to the
system bus and probes the components.
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.
The assignment step applies only to plat‐
forms that support dynamic system
domains.
-f Overrides software state changing constraints.
The -f option never overrides fundamental safety and
availability constraints of the hardware and operating
system.
-l Lists the state and condition of attachment points spec‐
ified in the format controlled by the -s, -v, and -a
options as specified in cfgadm(1M). The cfgadm_sbd plug‐
in 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 informa‐
tion:
cpuid=#[,#...] Where # is a number,
and represents the ID
of the CPU. If more
than one # is present,
this CPU has multiple
active virtual proces‐
sors.
speed=# Where # is a number
and represents the
speed of the CPU in
MHz.
ecache=# Where # is a number
and represents the
size of the ecache in
MBytes. If the CPU has
multiple active vir‐
tual processors, the
ecache could either be
shared among the vir‐
tual processors, or
divided between them.
memory The memory type displays the following infor‐
mation, as appropriate:
address=# Where # is a number,
representing the
base physical
address.
size=# Where # is a number,
representing the
size of the memory
in KBytes.
permanent=# Where # is a number,
representing the
size of permanent
memory in KBytes.
unconfigurable An operating system
setting that pre‐
vents the memory
from being unconfig‐
ured.
inter-board-interleave The board is partic‐
ipating in inter‐
leaving with other
boards.
source=ap_id Represents the
source attachment
point.
target=ap_id Represents the tar‐
get attachment
point.
deleted=# Where # is a number,
representing the
amount of memory
that has already
been deleted in
KBytes.
remaining=# Where # is a number,
representing the
amount of memory to
be deleted in
KBytes.
io The io type displays the following informa‐
tion:
device=path Represents the physical path to
the I/O component.
referenced The I/O component is refer‐
enced.
board The board type displays the following boolean
names. If they are not present, then the oppo‐
site applies.
assigned The board is assigned to the
domain.
powered-on The board is powered on.
The same items appear in the info field in a
more readable format if the -o parsable option
is not specified.
-o parsable 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(1M) man page for more
information about the -s option.
-t Tests the board.
Before a board can be connected, it must pass the appro‐
priate 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 appro‐
priate level of testing. Thus the -t option can be used
to explicitly request that the board be tested.
-x function Performs an sbd-class function. You can use the follow‐
ing functions:
assign Assigns a board to a domain.
The receptacle state must be disconnected or
empty. The board must also be listed in the
domain available component list. See Dynamic
System Domains.
unassign Unassigns a board from a domain.
The receptacle state must be disconnected or
empty. The board must also be listed in the
domain available component list. See Dynamic
System Domains.
poweron Powers the system board on.
The receptacle state must be disconnected.
poweroff Powers the system board off.
The receptacle state must be disconnected.
OPERANDS
The following operands are supported:
Receptacle ap_id For the Sun Fire high-end systems such as the Sun
Fire 15K , the receptacle attachment point ID takes
the form SBX or IOX, where X equals the slot num‐
ber.
The exact format depends on the platform and typi‐
cally corresponds to the physical labelling on the
machine. See the platform specific information in
the NOTES section.
Component ap_id 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 com‐
pontents. Any DR action on a memory attachment
point affects all of the memory on the system
board.
EXAMPLES
The following examples show user input and system output on a Sun Fire
15K system. User input, specifically references to attachment points
and system output might differ on other Sun Fire systems, such as the
Sun Fire midrange systems such as the 6800. Refer to the Platform Notes
for specific information about using the cfgadm_sbd plugin on non-Sun
Fire high-end models.
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:
o The board in Slot 2 failed testing.
o 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
Example 7 Assigning a Slot to a Domain
# cfgadm -x assign SB2
Example 8 Unassigning a Slot from a Domain
# cfgadm -x unassign SB3
ATTRIBUTES
See attributes(5) for a description of the following attribute:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │SUNWkvm.u │
├─────────────────────────────┼─────────────────────────────┤
│Stability │See below. │
└─────────────────────────────┴─────────────────────────────┘
The interface stability is evolving. The output stability is unstable.
SEE ALSOcfgadm(1M), devfsadm(1M), ifconfig(1M), mount(1M), pbind(1M),
psradm(1M), psrinfo(1M), config_admin(3CFGADM), attributes(5)NOTES
This section contains information on how to monitor the progress of a
memory delete operation. It also contains platform specific informa‐
tion.
Memory Delete Monitoring
The following shell script can be used to monitor the progress of a
memory delete operation.
# 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\n" `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
Sun Enterprise 10000 Platform Notes
The following syntax is used to refer to Platform Notes attachment
points on the Sun Enterprise 10000 system:
board::component
where board refers to the system board; and component refers to the
individual component. System boards can range from SB0 (zero) to SB15.
A maximum of sixteen system boards are available.
The DR 3.0 model running on a Sun Enterprise 10000 domain supports a
limited subset of the functionality provided by the cfgadm_sbd plugin.
The only supported operation is to view the status of attachment points
in the domain. This corresponds to the -l option and all of its associ‐
ated options.
Attempting to perform any other operation from the domain will result
in an error that states that the operation is not supported. All opera‐
tions to add or remove a system board must be initiated from the System
Service Processor.
Sun Fire High-End System Platform Notes
The following syntax is used to refer to attachment points on the Sun
Fire high-end systems:
board::component
where board refers to the system board or I/O board; and component
refers to the individual component.
Depending on the system's configuration, system boards can range from
SB0 (zero) through SB17, and I/O boards can range from IO0 (IO zero)
through IO17. (A maximum of eighteen system and I/O boards are avail‐
able).
The -t and -x options behave differently on the Sun Fire high-end sys‐
tem platforms. The following list describes their behavior:
-t The system controller uses a CPU to test system
boards by running LPOST, sequenced by the hpost
command. To test I/O boards, the driver starts
the testing in response to the -t option, and
the test runs automatically without user inter‐
vention. The driver unconfigures a CPU and a
stretch of contiguous physical memory. Then, it
sends a command to the system controller to
test the board. The system controller uses the
CPU and memory to test the I/O board from
inside of a transaction/error cage. You can
only use CPUs from system boards (not MCPU
boards) to test I/O boards.
-x assign | unassign In the Sun Fire high-end system administration
model, the platform administrator controls the
platform hardware through the use of an avail‐
able component list for each domain. This
information is maintained on the system con‐
troller. Only the platform administrator can
modify the available component list for a
domain.
The domain administrator is only allowed to
assign or unassign a board if it is in the
available component list for that domain. The
platform administrator does not have this
restriction, and can assign or unassign a board
even if it is not in the available component
list for a domain.
Sun Fire 15K Component Types
The following are the names and descriptions of the component types:
cpu CPU
io I/O device
memory Memory
Note: An operation on a memory component affects all of the memory com‐
ponents on the board.
Sun Fire Midrange Systems Platform Notes
References to attachment points are slightly different on Sun Fire
midrange servers such as the 6800, 4810, 4800, and 3800 systems than on
the Sun Fire high-end systems. The following syntax is used to refer to
attachment points on Sun Fire systems other than the Sun Fire 15K:
N#.board::component
where N# refers to the node; board refers to the system board or I/O
board; and component refers to the individual component.
Depending on the system's configuration, system boards can range from
SB0 through SB5, and I/O boards can range from IB6 through IB9. (A max‐
imum of six system and four I/O boards are available).
Sun Fire Midrange System Component Types
The following are the names and descriptions of the component types:
cpu CPU
pci I/O device
memory Memory
Note: An operation on a memory component affects all of the memory com‐
ponents on the board.
SunOS 5.11 13 Oct 2003 cfgadm_sbd(1M)