cfgadm_sbd(1M)
NAME
cfgadm_sbd - cfgadm commands for system board administration
SYNOPSIS
cfgadm -l [-a] [-o parsable] ap_id...
cfgadm -c function [-f] [-y | -n] [-o unassign | nopower-
off] [-v] ap_id...
cfgadm -t [-v] ap_id...
cfgadm -x [-f] [-v] function ap_id...
DESCRIPTION
The cfgadm_sbd plugin provides dynamic reconfiguration func-
tionality for connecting, configuring, unconfiguring, and
disconnecting class sbd system boards. It also enables you
to connect or disconnect a system board from a running sys-
tem 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. Additionally, 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 com-
ponent conditions:
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
operating 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
disconnected. 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 recepta-
cle 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 uncon-
figured. The following table contains the names and descrip-
tions 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 maintained on the system con-
troller. 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 visible 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 expli-
citly using -x assign or implicitly 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 disconnect
using -o unassign.
State Change Functions
Functions that change the state of a board slot or a com-
ponent on the board can be issued concurrently against any
attachment point. Only one state changing operation is per-
mitted 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 concurrently against any attachment point. Only one
availability 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 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 pro-
cess, 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 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.
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 contains 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 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(1M), psradm(1M) and psrinfo(1M).
The unconfigure function moves the physical
memory to another system board before it deletes
the memory from the board you want to unconfig-
ure. 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 com-
plete, 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 inter-
rupt the memory operation by stopping the cfgadm
command. The deleted memory is returned to the
system memory pool.
disconnect
Changes the receptacle state to disconnected.
This function applies only to system board
slots.
If the occupant state is configured, the discon-
nect function attempts to unconfigure the occu-
pant. 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 disconnect
function leaves the board powered on. If you
specify -o unassign, the disconnect function
unassigns the board from the domain.
If you unassign a board from a domain, you can
assign it to another domain. However, 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 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 con-
figured.
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 suc-
cessfully.
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 connected. 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 success-
fully, you can use the -a option to view the
status of the components on the board. The con-
nect function leaves all of the components in
the unconfigured state.
The assignment step applies only to platforms
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
specified in the format controlled by the -s, -v, and
-a options as specified in cfgadm(1M). 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 pro-
cessors.
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 virtual processors,
the ecache could either be shared among
the virtual processors, or divided between
them.
memory
The memory type displays the following informa-
tion, 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 prevents
the memory from being unconfigured.
inter-board-interleave
The board is participating in interleaving
with other boards.
source=ap_id
Represents the source attachment point.
target=ap_id
Represents the target 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 information:
device=path
Represents the physical path to the I/O
component.
referenced
The I/O component is referenced.
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
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.
-x function
Performs an sbd-class function. You can use the fol-
lowing 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 number.
The exact format depends on the platform and typically
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 compon-
tents. 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 infor-
mation 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 con-
ditions:
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 attri-
bute:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWkvm.u |
|_____________________________|_____________________________|
| Stability | See below. |
|_____________________________|_____________________________|
The interface stability is evolving. The output stability is
unstable.
SEE ALSO
cfgadm(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 pro-
gress of a memory delete operation. It also contains plat-
form specific information.
Memory Delete Monitoring
The following shell script can be used to monitor the pro-
gress 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 associated
options.
Attempting to perform any other operation from the domain
will result in an error that states that the operation is
not supported. All operations 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 sys-
tem and I/O boards are available).
The -t and -x options behave differently on the Sun Fire
high-end system 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 automati-
cally without user intervention. The driver unconfig-
ures a CPU and a stretch of contiguous physical
memory. Then, it sends a command to the system con-
troller 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 available component
list for each domain. This information is maintained
on the system controller. Only the platform adminis-
trator 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 com-
ponent types:
cpu CPU
io I/O device
memory
Memory
Note: An operation on a memory component affects all of the
memory components 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 fol-
lowing 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 maximum 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 com-
ponent types:
cpu CPU
pci I/O device
memory
Memory
Note: An operation on a memory component affects all of the
memory components on the board.
Man(1) output converted with
man2html